Documentation — Spybara

accessibility.md +11 −5

Details

45| [`axScreenReader`](/docs/ko/settings-reference#axscreenreader) | 설정 | `true`일 때 모든 세션에 대한 스크린 리더 모드입니다. |45| [`axScreenReader`](/docs/ko/settings-reference#axscreenreader) | 설정 | `true`일 때 모든 세션에 대한 스크린 리더 모드입니다. |

47| [`CLAUDE_AX_PREPARK_MS`](/docs/ko/env-vars#variables) | 환경 변수 | Claude Code가 줄의 시작 부분에 커서를 두고 스크린 리더 모드에서 새로운 또는 변경된 줄을 작성하기 전에 대기하는 시간입니다. Claude Code v2.1.233 이상이 필요합니다. |47| [`CLAUDE_AX_PREPARK_MS`](/docs/ko/env-vars#variables) | 환경 변수 | 설정한 경우, 스크린 리더 모드에서 Claude Code가 새 줄이나 변경된 줄을 작성하기 전에 터미널 커서를 현재 줄의 시작 부분에 유지하는 시간(밀리초)입니다. Claude Code v2.1.233 이상이 필요합니다. |

48| [`CLAUDE_CODE_ACCESSIBILITY`](/docs/ko/env-vars#variables) | 환경 변수 | `1`로 설정할 때 macOS Zoom과 같은 스크린 확대기에 대해 표시 상태를 유지하는 터미널 커서입니다. 커서는 입력 캐럿을 따르고, Claude Code v2.1.218 이상에서는 `/config` 및 `/plugin`과 같은 메뉴 및 패널의 강조 표시된 행을 따릅니다. |48| [`CLAUDE_CODE_ACCESSIBILITY`](/docs/ko/env-vars#variables) | 환경 변수 | `1`로 설정할 때 macOS Zoom과 같은 스크린 확대기에 대해 표시 상태를 유지하는 터미널 커서입니다. 커서는 입력 캐럿을 따르고, Claude Code v2.1.218 이상에서는 `/config` 및 `/plugin`과 같은 메뉴 및 패널의 강조 표시된 행을 따릅니다. |

49| [`prefersReducedMotion`](/docs/ko/settings-reference#prefersreducedmotion) | 설정 | `true`일 때 스피너, 반짝임 및 기타 애니메이션이 감소하거나 없습니다. |49| [`prefersReducedMotion`](/docs/ko/settings-reference#prefersreducedmotion) | 설정 | `true`일 때 스피너, 반짝임 및 기타 애니메이션이 감소하거나 없습니다. |

50| [`theme`](/docs/ko/settings-reference#theme) | 설정 | 색맹 친화적인 `dark-daltonized` 및 `light-daltonized` 테마를 포함한 인터페이스 색상입니다. [`/theme`](/docs/ko/commands#all-commands)을 사용하여 하나를 선택할 수도 있습니다. |50| [`theme`](/docs/ko/settings-reference#theme) | 설정 | 색맹 친화적인 `dark-daltonized` 및 `light-daltonized` 테마를 포함한 인터페이스 색상입니다. [`/theme`](/docs/ko/commands#all-commands)을 사용하여 하나를 선택할 수도 있습니다. |

60* 색상만으로 표시되는 신호 없음60* 색상만으로 표시되는 신호 없음

61* 변경되지 않은 콘텐츠의 다시 그리기 없음. 진행 상황 스피너는 정적 텍스트로 렌더링됨61* 변경되지 않은 콘텐츠의 다시 그리기 없음. 진행 상황 스피너는 정적 텍스트로 렌더링됨

62* Claude의 답변의 표는 상자 문자 그리드 대신 `Header: value` 문장으로 읽힙니다62* Claude의 답변의 표는 상자 문자 그리드 대신 `Header: value` 문장으로 읽힙니다

63* diff는 일반 텍스트로 한 줄씩 읽히며 `+`와 `-`가 추가된 줄과 삭제된 줄을 표시하므로, 파일 편집 승인 프롬프트에서 응답하기 전에 제안된 변경 사항을 들을 수 있습니다

63 64

64Claude Code는 터미널의 스크롤백에 인쇄하는 모든 것을 남겨두므로 스크린 리더의 검토 명령이나 터미널의 검색을 사용하여 이전 턴을 다시 읽을 수 있습니다. Claude Code는 스크린 리더 모드에서 [`tui` 설정](/docs/ko/settings-reference#tui)을 무시합니다. [알려진 제한 사항](#known-limitations)에 나열된 연결된 백그라운드 세션을 제외하고, [전체 화면 렌더링](/docs/ko/fullscreen) 대신 스크롤링 텍스트를 인쇄합니다.65Claude Code는 터미널의 스크롤백에 인쇄하는 모든 것을 남겨두므로 스크린 리더의 검토 명령이나 터미널의 검색을 사용하여 이전 턴을 다시 읽을 수 있습니다. Claude Code는 스크린 리더 모드에서 [`tui` 설정](/docs/ko/settings-reference#tui)을 무시합니다. [알려진 제한 사항](#known-limitations)에 나열된 연결된 백그라운드 세션을 제외하고, [전체 화면 렌더링](/docs/ko/fullscreen) 대신 스크롤링 텍스트를 인쇄합니다.

65 66

~~66Claude Code는 또한 스크린 리더가 따라갈 수 있도록 두 지점에서 대기합니다:~~67Claude Code가 시작 시 [확인 줄](#turn-on-screen-reader-mode)을 인쇄한 후, 스크린 리더가 줄을 완료할 수 있도록 프롬프트를 그리기 전에 3초 동안 대기합니다. 아무 키나 눌러 대기를 종료합니다. 대기 길이를 변경하려면 [`CLAUDE_AX_STARTUP_QUIET_MS`](/docs/ko/env-vars#variables)를 설정합니다.

68* Claude Code가 확인 줄을 인쇄한 후 스크린 리더가 줄을 완료할 수 있도록 프롬프트를 그리기 전에 3초 동안 대기합니다. 아무 키나 눌러 대기를 종료합니다. 대기 길이를 변경하려면 [`CLAUDE_AX_STARTUP_QUIET_MS`](/docs/ko/env-vars#variables)를 설정합니다.

69* Claude Code가 힌트나 Claude의 답변 중 더 많은 부분과 같은 새로운 또는 변경된 줄을 작성하기 전에 커서를 줄의 시작으로 이동하고 50밀리초 동안 대기합니다. 스크린 리더는 첫 번째 문자부터 줄을 읽습니다. 입력 줄의 끝에 입력하거나 삭제한 문자는 즉시 나타납니다. 대기 길이를 변경하려면 [`CLAUDE_AX_PREPARK_MS`](/docs/ko/env-vars#variables)를 설정합니다.

70 68

71트랜스크립트의 각 메시지는 스크린 리더가 발표하는 레이블로 시작하며, 이것이 무엇인지 이름을 지정합니다: 사용자의 메시지, Claude의 답변 및 생각, 도구 활동, 오류 및 경고, 그리고 프롬프트. 레이블은 또한 검색 가능하므로 터미널의 스크롤백을 검색하여 트랜스크립트의 섹션 간에 이동할 수 있습니다:69트랜스크립트의 각 메시지는 스크린 리더가 발표하는 레이블로 시작하며, 이것이 무엇인지 이름을 지정합니다: 사용자의 메시지, Claude의 답변 및 생각, 도구 활동, 오류 및 경고, 그리고 프롬프트. 레이블은 또한 검색 가능하므로 터미널의 스크롤백을 검색하여 트랜스크립트의 섹션 간에 이동할 수 있습니다:

72 70

94 92

95[권한 모드](/docs/ko/permission-modes)를 `Shift+Tab`으로 순환할 때, Claude Code는 도착한 권한 모드를 발표합니다(예: `[plan mode on]` 또는 `[accept edits on]`). Claude Code는 발표를 한 번 인쇄하고 나중의 다시 그리기에서 반복하지 않습니다.93[권한 모드](/docs/ko/permission-modes)를 `Shift+Tab`으로 순환할 때, Claude Code는 도착한 권한 모드를 발표합니다(예: `[plan mode on]` 또는 `[accept edits on]`). Claude Code는 발표를 한 번 인쇄하고 나중의 다시 그리기에서 반복하지 않습니다.

96 94

95<h3 id="read-earlier-output-without-losing-your-place">

96 위치를 잃지 않고 이전 출력 읽기

97</h3>

99이전 출력을 읽는 동안 스크린 리더가 프롬프트로 다시 이동한다면, 스크린 리더가 터미널 커서를 따라가고 있는 것입니다. Claude Code는 새 텍스트를 작성할 때마다 터미널 커서를 프롬프트로 다시 이동합니다.

100

101읽는 동안 위치를 유지하려면 스크린 리더가 터미널 커서를 따라가지 않도록 설정합니다. NVDA에서는 `NVDA+6`을 눌러 검토 커서가 터미널 커서를 따라가지 않도록 합니다. 따라가기를 다시 켜려면 `NVDA+6`을 한 번 더 누릅니다.

102

97<h3 id="jump-between-turns">103<h3 id="jump-between-turns">

98 턴 간에 이동104 턴 간에 이동

99</h3>105</h3>

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

Details

302압축 동작을 여러 가지 방법으로 사용자 정의할 수 있습니다:302압축 동작을 여러 가지 방법으로 사용자 정의할 수 있습니다:

303 303

304* **CLAUDE.md의 요약 지침:** 압축기는 다른 컨텍스트처럼 CLAUDE.md를 읽으므로 요약할 때 보존할 내용을 알려주는 섹션을 포함할 수 있습니다. 압축기는 의도와 일치하므로 섹션 헤더는 자유 형식입니다.304* **CLAUDE.md의 요약 지침:** 압축기는 다른 컨텍스트처럼 CLAUDE.md를 읽으므로 요약할 때 보존할 내용을 알려주는 섹션을 포함할 수 있습니다. 압축기는 의도와 일치하므로 섹션 헤더는 자유 형식입니다.

305* **`PreCompact` hook:** 압축 전에 사용자 정의 로직을 실행합니다(예: 전체 기록을 보관). hook은 `trigger` 필드(`manual` 또는 `auto`)를 받습니다. [hooks](/docs/ko/agent-sdk/hooks)를 참조하세요.305* **`PreCompact` 훅:** 압축 전에 사용자 정의 로직을 실행합니다(예: 전체 트랜스크립트를 보관). 훅은 `trigger` 필드(`manual` 또는 `auto`)를 받습니다. [훅](/docs/ko/agent-sdk/hooks)을 참조하세요.

306* **수동 압축:** `/compact`를 프롬프트 문자열로 보내 필요에 따라 압축을 트리거합니다. 이 방식으로 전송된 명령은 일반적인 SDK 입력입니다. [이름으로 명령 디스패치](/docs/ko/agent-sdk/skills#dispatch-commands-by-name)를 참조하세요.306* **수동 압축:** `/compact`를 프롬프트 문자열로 보내 필요에 따라 압축을 트리거합니다. 이 방식으로 전송된 명령은 일반적인 SDK 입력입니다. [이름으로 명령 디스패치](/docs/ko/agent-sdk/skills#dispatch-commands-by-name)를 참조하세요.

307 307

308<Accordion title="예제: CLAUDE.md의 요약 지침">308<Accordion title="예제: CLAUDE.md의 요약 지침">

325 325

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

327 327

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

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

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

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

332 332

333기능별 컨텍스트 비용의 자세한 분석은 [컨텍스트 비용 이해](/docs/ko/features-overview#understand-context-costs)를 참조하세요.333기능별 컨텍스트 비용의 자세한 분석은 [컨텍스트 비용 이해](/docs/ko/features-overview#understand-context-costs)를 참조하세요.

334 334

agent-sdk/python.md +1 −1

Details

1488`ClaudeAgentOptions`의 `betas` 필드와 함께 사용하여 베타 기능을 활성화합니다.1488`ClaudeAgentOptions`의 `betas` 필드와 함께 사용하여 베타 기능을 활성화합니다.

1489 1489

1490<Warning>1490<Warning>

1491 `context-1m-2025-08-07` 베타는 2026년 4월 30일부터 폐기되었습니다. Claude Sonnet 4.5 또는 Sonnet 4와 함께 이 헤더를 전달하면 효과가 없으며, 표준 200k 토큰 컨텍스트 윈도우를 초과하는 요청은 오류를 반환합니다. 1M 토큰 컨텍스트 윈도우를 사용하려면 [Claude Opus 5.5, Claude Opus 5, Claude Sonnet 5, Claude Sonnet 4.6, Claude Opus 4.6, Claude Opus 4.7, 또는 Claude Opus 4.8](https://platform.claude.com/docs/en/about-claude/models/overview)로 마이그레이션하십시오. 이들은 베타 헤더 없이 표준 가격으로 1M 컨텍스트를 포함합니다.1491 Claude API에서 `context-1m-2025-08-07` 베타는 Claude Sonnet 4.5 및 Claude Sonnet 4에 대해 폐기되었습니다. 두 모델 중 하나와 함께 이를 계속 전달하면 표준 200K 토큰 컨텍스트 윈도우를 초과하는 요청이 오류를 반환하므로, `betas`에서 제거하십시오. 1M 토큰 컨텍스트 윈도우로 세션을 실행하려면 `model`을 `claude-sonnet-5-5` 또는 `claude-opus-5-5`와 같이 [기본적으로 1M 윈도우로 실행되는](/docs/ko/model-config#extended-context) 모델로 설정합니다. `[1m]` 변형을 통해서만 1M에 도달하는 모델의 경우 `claude-opus-4-6[1m]`처럼 모델 ID에 접미사를 추가합니다.

1492</Warning>1492</Warning>

1493 1493

1494<h3 id="mcpsdkserverconfig">1494<h3 id="mcpsdkserverconfig">

agent-sdk/streaming-vs-single-mode.md +2 −0

Details

166 166

167예제를 실행하면 TypeScript 버전은 완료될 때마다 각 응답을 출력합니다. Python 버전의 `receive_response()` 루프는 첫 번째 결과 메시지에서 끝나므로 보안 분석을 출력합니다. 두 응답을 모두 읽으려면 [Python 참조의 대화 계속 예제](/docs/ko/agent-sdk/python#example-continuing-a-conversation)에 표시된 대로 메시지당 하나의 `query()` 및 `receive_response()` 쌍을 사용합니다.167예제를 실행하면 TypeScript 버전은 완료될 때마다 각 응답을 출력합니다. Python 버전의 `receive_response()` 루프는 첫 번째 결과 메시지에서 끝나므로 보안 분석을 출력합니다. 두 응답을 모두 읽으려면 [Python 참조의 대화 계속 예제](/docs/ko/agent-sdk/python#example-continuing-a-conversation)에 표시된 대로 메시지당 하나의 `query()` 및 `receive_response()` 쌍을 사용합니다.

168 168

169이미지 블록의 `source`가 누락되었거나 객체가 아닌 경우 SDK는 오류를 보고하지 않습니다. Claude Code는 이미지 대신 `[Image could not be processed: image block has no source object]`와 같은 텍스트 메모를 Claude에 보내고, 세션은 계속됩니다.

170

169<Note>171<Note>

170 TypeScript SDK에서 예를 들어 읽는 파일이 누락되었을 때 메시지 생성기가 throw하면, 스트림은 원래 오류 대신 `Claude Code process aborted by user`라고 읽는 오류로 끝나므로, 해당 메시지가 표시되면 먼저 생성기 내부의 코드를 확인하십시오. 오류 앞에 번들된 SDK 소스의 긴 축소된 줄이 있을 수도 있으므로, 오류 텍스트를 찾기 위해 출력의 끝까지 읽으십시오.172 TypeScript SDK에서 예를 들어 읽는 파일이 누락되었을 때 메시지 생성기가 throw하면, 스트림은 원래 오류 대신 `Claude Code process aborted by user`라고 읽는 오류로 끝나므로, 해당 메시지가 표시되면 먼저 생성기 내부의 코드를 확인하십시오. 오류 앞에 번들된 SDK 소스의 긴 축소된 줄이 있을 수도 있으므로, 오류 텍스트를 찾기 위해 출력의 끝까지 읽으십시오.

171 173

agent-sdk/subagents.md +15 −15

Details

186</Note>186</Note>

187 187

188<h2 id="what-subagents-inherit">188<h2 id="what-subagents-inherit">

189 서브에이전트가 상속하는 것189 서브에이전트가 상속하는 항목

190</h2>190</h2>

191 191

192서브에이전트가 [포크](/docs/ko/sub-agents#fork-the-current-conversation)가 아닌 경우, 그 컨텍스트 윈도우는 새로 시작되며 부모 대화가 없지만 비어있지는 않습니다. 부모에서 서브에이전트로 전달하는 유일한 콘텐츠는 Agent 도구의 프롬프트 문자열이므로, 서브에이전트가 필요로 하는 파일 경로, 오류 메시지 또는 결정 사항을 해당 프롬프트에 직접 포함시켜야 합니다.192서브에이전트가 [포크](/docs/ko/sub-agents#fork-the-current-conversation)가 아닌 경우, 컨텍스트 윈도우는 부모 대화 없이 새로 시작되지만 비어 있지는 않습니다. 부모에서 서브에이전트로 전달되는 유일한 콘텐츠는 Agent 도구의 프롬프트 문자열이므로, 서브에이전트에 필요한 파일 경로, 오류 메시지 또는 결정 사항은 해당 프롬프트에 직접 포함해야 합니다.

193 193

194[`SendMessage`](/docs/ko/tools-reference) 도구를 가진 서브에이전트는 세션에서 실행 중인 다른 명명된 에이전트 목록으로 시작하므로, 메시지를 보낼 수 있는 이름이 무엇인지 알 수 있습니다. Claude Code는 서브에이전트의 첫 번째 턴에 자동으로 목록을 추가합니다. [포크](/docs/ko/sub-agents#fork-the-current-conversation)는 부모 대화를 상속하기 때문에 목록을 받지 않습니다.194[`SendMessage`](/docs/ko/tools-reference) 도구가 있는 서브에이전트는 세션에서 실행 중인 다른 이름 있는 에이전트의 목록을 가지고 시작하므로, 어떤 이름으로 메시지를 보낼 수 있는지 알 수 있습니다. Claude Code는 이 목록을 서브에이전트의 첫 번째 턴에 자동으로 추가합니다. [포크](/docs/ko/sub-agents#fork-the-current-conversation)는 대신 부모 대화를 상속하므로 이 목록을 받지 않습니다.

195 195

196서브에이전트는 또한 메인 세션의 확장 사고 구성을 상속합니다.196서브에이전트는 메인 세션의 확장 사고 구성도 상속합니다.

197 197

198아래 표는 포크가 아닌 서브에이전트의 컨텍스트에 포함되는 것과 제외되는 것을 나열합니다.198아래 표는 포크가 아닌 서브에이전트의 컨텍스트에 포함되는 항목과 제외되는 항목을 나열합니다.

199 199

200| 서브에이전트가 받는 것 | 서브에이전트가 받지 않는 것 |200| 서브에이전트가 받는 항목 | 서브에이전트가 받지 않는 항목 |

201| :- | :- |201| :- | :- |

203| Project CLAUDE.md ([`settingSources`](/docs/ko/agent-sdk/claude-code-features#control-filesystem-settings-with-settingsources)를 통해 로드됨), [`omitClaudeMd`](#agentdefinition-configuration)를 설정하지 않는 한 | 미리 로드된 스킬 콘텐츠, `AgentDefinition.skills`에 나열된 경우 제외 |203| 프로젝트 CLAUDE.md([`settingSources`](/docs/ko/agent-sdk/claude-code-features#control-filesystem-settings-with-settingsources)를 통해 로드됨). 단, 에이전트가 [`omitClaudeMd`](#agentdefinition-configuration)를 설정한 경우는 제외 | 미리 로드된 스킬 콘텐츠(`AgentDefinition.skills`에 나열된 경우 제외) |

205 205

206<Note>206<Note>

207 부모는 서브에이전트의 최종 메시지를 Agent 도구 결과로 받지만, 자신의 응답에서 요약할 수 있습니다. 서브에이전트 출력을 사용자 대면 응답에 그대로 보존하려면, 메인 `query()` 호출에 전달하는 프롬프트 또는 `systemPrompt` 옵션에 그렇게 하도록 하는 지시사항을 포함시키십시오.207 부모는 서브에이전트의 최종 보고서를 받지만, 자체 응답에서 이를 요약할 수 있습니다. 사용자에게 표시되는 응답에서 서브에이전트 출력을 그대로 유지하려면, 메인 `query()` 호출에 전달하는 프롬프트 또는 `systemPrompt` 옵션에 그렇게 하도록 지시하는 내용을 포함하십시오.

208 208

209 v2.1.210 이상에서 Claude Code는 부모가 읽기 전에 [최종 메시지에서 지시사항 형태의 패턴을 스캔합니다](/docs/ko/sub-agents#subagent-output-scanning). 스캔은 세 가지 패턴 유형을 다르게 처리합니다:209 v2.1.210 이상에서는 Claude Code가 부모가 최종 메시지를 읽기 전에 [최종 메시지에서 지시문 형태의 패턴을 스캔](/docs/ko/sub-agents#subagent-output-scanning)합니다. 스캔은 세 가지 종류의 패턴을 다르게 처리합니다.

210 210

211 * **제어 태그 모방**: Claude Code는 `<system-reminder>` 블록과 같이 하네스만 내보내는 태그를 제자리에서 중립화합니다. 여는 꺾쇠 괄호 뒤에 백슬래시를 삽입하고 아무것도 삭제하지 않습니다.211 * **제어 태그 모방**: Claude Code는 `<system-reminder>` 블록처럼 하네스만 생성하는 태그를 그 자리에서 무력화합니다. 여는 꺾쇠괄호 뒤에 백슬래시를 삽입하며 아무것도 삭제하지 않습니다.

212 * **권한 구성 언급**: Claude Code는 `.claude/settings.json`, `bypassPermissions` 또는 `--dangerously-skip-permissions`와 같은 권한 구성에 대한 참조를 작성된 그대로 유지합니다.212 * **권한 구성 언급**: Claude Code는 `.claude/settings.json`, `bypassPermissions` 또는 `--dangerously-skip-permissions`와 같은 권한 구성에 대한 참조를 작성된 그대로 유지합니다.

213 * **턴 마커**: `Human:` 또는 `Assistant:`로 시작하는 줄은 콜론 앞에 백슬래시를 받으므로 메시지가 대화 턴 경계를 모방할 수 없습니다.213 * **턴 마커**: `Human:` 또는 `Assistant:`로 시작하는 줄은 콜론 앞에 백슬래시가 추가되므로, 메시지가 대화 턴 경계를 모방할 수 없습니다.

214 214

215 제어 태그 또는 권한 구성 일치의 경우, Claude Code는 일치된 패턴의 이름을 지정하는 `[harness: ...]` 마커 줄을 앞에 붙입니다. 턴 마커 일치는 마커 줄을 추가하지 않습니다. 이것이 스캔이 수행하는 유일한 수정 사항입니다. 서브에이전트의 텍스트를 제거하거나 다시 표현하지 않습니다.215 제어 태그 또는 권한 구성이 일치하는 경우, Claude Code는 일치한 패턴을 명시하는 `[harness: ...]` 마커 줄을 앞에 추가합니다. 턴 마커가 일치하는 경우에는 마커 줄이 추가되지 않습니다. 스캔이 수행하는 수정은 이것뿐이며, 서브에이전트의 텍스트를 제거하거나 바꿔 쓰지 않습니다.

216</Note>216</Note>

217 217

218속도 제한과 같이 서브에이전트를 조기에 종료하는 API 오류는 결과로 전달되지 않습니다. [서브에이전트의 API 오류](/docs/ko/sub-agents#api-errors-in-subagents)에서 포그라운드 및 백그라운드 동작을 참조하십시오.218속도 제한과 같이 서브에이전트를 조기에 종료시키는 API 오류는 결과로 전달되지 않습니다. 포그라운드 및 백그라운드 동작에 대해서는 [서브에이전트의 API 오류](/docs/ko/sub-agents#api-errors-in-subagents)를 참조하십시오.

219 219

220<h2 id="invoke-subagents">220<h2 id="invoke-subagents">

221 서브에이전트 호출221 서브에이전트 호출

agent-sdk/typescript.md +130 −132

Details

1554* `'model_not_found'`: 선택한 모델이 존재하지 않거나 계정이나 배포에서 사용할 수 없음1554* `'model_not_found'`: 선택한 모델이 존재하지 않거나 계정이나 배포에서 사용할 수 없음

1555* `'overloaded'`: API가 서버가 용량에 도달했기 때문에 529를 반환했으며, 할당량에 대한 429인 `'rate_limit'`과는 다름1555* `'overloaded'`: API가 서버가 용량에 도달했기 때문에 529를 반환했으며, 할당량에 대한 429인 `'rate_limit'`과는 다름

1556* `'account_on_hold'`: [계정이 보류 중](/docs/ko/errors#your-account-is-on-hold)1556* `'account_on_hold'`: [계정이 보류 중](/docs/ko/errors#your-account-is-on-hold)

1557* `'cloud_credential_error'`: Claude Code가 실행되는 머신에서 사용 가능한 AWS 또는 Google Cloud 자격증명을 얻을 수 없어서 클라우드 제공자에게 요청이 도달하지 않았습니다. 일반적인 원인은 해당 머신에서 만료되었거나 완료되지 않은 클라우드 로그인이지만, 일시적으로 도달할 수 없는 자격증명 서비스도 동일한 값을 보고합니다. [AWS 또는 Google Cloud 자격증명을 로드할 수 없음](/docs/ko/errors#could-not-load-aws-or-google-cloud-credentials)을 참조하세요. TypeScript Agent SDK v0.3.267 이상이 필요하며, Claude Code v2.1.267을 번들로 포함합니다.1557* `'cloud_credential_error'`: Claude Code가 실행되는 머신에서 사용 가능한 AWS 또는 Google Cloud 자격 증명을 얻을 수 없어서 클라우드 제공자에게 요청이 도달하지 않았습니다. 일반적인 원인은 해당 머신에서 만료되었거나 완료되지 않은 클라우드 로그인이지만, 일시적으로 도달할 수 없는 자격 증명 서비스도 동일한 값을 보고합니다. [AWS 또는 Google Cloud 자격 증명을 로드할 수 없음](/docs/ko/errors#could-not-load-aws-or-google-cloud-credentials)을 참조하세요. TypeScript Agent SDK v0.3.267 이상이 필요하며, Claude Code v2.1.267을 번들로 포함합니다.

1558 1558

1559`aborted`는 중단이나 중지가 스트림이 완료되기 전에 어시스턴트 메시지를 자를 때 `true`입니다: 메시지에는 `stop_reason`이 없고 콘텐츠가 단어 중간에 끝날 수 있습니다. 이 필드는 정상적으로 완료된 메시지에는 없습니다. Agent SDK v0.3.214 이상이 필요합니다.1559`aborted`는 중단이나 중지가 스트림이 완료되기 전에 어시스턴트 메시지를 자를 때 `true`입니다: 메시지에는 `stop_reason`이 없고 콘텐츠가 단어 중간에 끝날 수 있습니다. 이 필드는 정상적으로 완료된 메시지에는 없습니다. Agent SDK v0.3.214 이상이 필요합니다.

1560 1560

1561Claude Code는 [`user_message_uuid`](#user_message_uuid)의 조건에 따라 턴의 첫 번째 어시스턴트 메시지에 `user_message_uuid`와 `user_message_uuids`를 설정합니다. Claude Code가 재시작으로 중단된 턴을 다시 실행할 때, 이러한 필드를 전달하는 다시 실행된 어시스턴트 메시지도 [`resume_reason`](#resume_reason)을 전달합니다.1561Claude Code는 [`user_message_uuid`](#user_message_uuid)의 조건에 따라 턴의 첫 번째 어시스턴트 메시지에 `user_message_uuid`와 `user_message_uuids`를 설정합니다. Claude Code가 재시작으로 중단된 턴을 다시 실행할 때, 이러한 필드를 전달하는 다시 실행된 어시스턴트 메시지도 [`resume_reason`](#resume_reason)을 전달합니다.

1562 1562

1563`timestamp`는 메시지의 콘텐츠가 생성을 완료한 ISO 8601 시간입니다. 값은 해당 머신의 시계에서 나오므로 표시 목적으로만 사용하고 메시지를 순서대로 정렬하지 마세요. 하나의 API 턴은 동일한 `message.id`를 공유하는 여러 어시스턴트 메시지를 생성할 수 있으며, 각각 자신의 `timestamp`를 가집니다. 필드가 없으면 메시지를 받은 시간으로 돌아가세요.1563`timestamp`는 메시지를 생성한 프로세스에서 메시지의 콘텐츠가 생성을 완료한 ISO 8601 시간입니다. 값은 해당 머신의 시계에서 나오므로 표시 목적으로만 사용하고 이를 기준으로 메시지를 정렬하지 마세요. 하나의 API 턴은 동일한 `message.id`를 공유하는 여러 어시스턴트 메시지를 생성할 수 있으며, 각각 자신의 `timestamp`를 가집니다. 필드가 없으면 메시지를 받은 시간으로 대체하세요.

1564 1564

1565`context_usage`는 `/context` 보고서의 구조화된 복사본이며, [`SDKContextUsage`](#sdkcontextusage)로 입력되고 Agent SDK v0.3.232 이상이 필요합니다. 프롬프트로 `/context`를 보낼 때, Claude Code는 보고서를 어시스턴트 메시지로 전달하며, 그 `message.content`는 마크다운 테이블을 보유하고, `context_usage`를 동일한 메시지에 첨부합니다. Claude Code는 다른 어시스턴트 메시지에는 필드를 설정하지 않으며, 이전 버전은 `/context` 테이블을 없이 전달하므로, 필드가 있을 때는 분석을 읽고 없을 때는 마크다운 텍스트로 돌아가세요.1565`context_usage`는 `/context` 보고서의 구조화된 복사본이며, [`SDKContextUsage`](#sdkcontextusage) 타입이고 Agent SDK v0.3.232 이상이 필요합니다. 프롬프트로 `/context`를 보낼 때, Claude Code는 `message.content`에 마크다운 테이블을 담은 어시스턴트 메시지로 보고서를 전달하고, 동일한 메시지에 `context_usage`를 첨부합니다. Claude Code는 다른 어시스턴트 메시지에는 이 필드를 설정하지 않으며, 이전 버전은 이 필드 없이 `/context` 테이블을 전달하므로, 필드가 있을 때는 필드에서 분석을 읽고 없을 때는 마크다운 텍스트로 대체하세요.

1566 1566

1567<h3 id="sdkusermessage">1567<h3 id="sdkusermessage">

1568 `SDKUserMessage`1568 `SDKUserMessage`

1587};1587};

1588```1588```

1589 1589

1590사용자가 프롬프트 UI에 붙여넣은 콘텐츠를 보내려면 `pasted_content`를 설정하세요. 입력한 것이 아니라 붙여넣은 것이며, 붙여넣기당 하나의 항목이고, 각각 문자열 또는 콘텐츠 블록 배열입니다. Claude Code는 각 항목의 텍스트를 입력된 텍스트 뒤에 순서대로 추가하며, 각 붙여넣기를 `<pasted_content>` 태그로 감쌀 수 있습니다. 텍스트 이외의 블록은 무시되므로 이미지와 문서는 `message.content`에서 보내세요. Agent SDK v0.3.277 이상이 필요합니다.1590사용자가 프롬프트 UI에 입력하지 않고 붙여넣은 콘텐츠를 보내려면 `pasted_content`를 설정하세요. 붙여넣기당 하나의 항목이며, 각각 문자열 또는 콘텐츠 블록 배열입니다. Claude Code는 각 항목의 텍스트를 입력된 텍스트 뒤에 순서대로 추가하며, 각 붙여넣기를 `<pasted_content>` 태그로 감쌀 수 있습니다. 텍스트 이외의 블록은 무시되므로 이미지와 문서는 `message.content`에서 보내세요. Agent SDK v0.3.277 이상이 필요합니다.

1591 1591

1592Claude Code가 보낸 메시지를 처리하는 방식을 변경하려면 `shouldQuery` 또는 `client_composed`를 설정하세요:1592Claude Code가 보낸 메시지를 처리하는 방식을 변경하려면 `shouldQuery` 또는 `client_composed`를 설정하세요:

1593 1593

1596 1596

1597`tool_result` 블록을 전달하는 메시지에서 `tool_use_result`는 모델로 전송된 텍스트가 아니라 도구의 구조화된 출력 객체입니다. 해당 형태는 일치하는 `tool_use` 블록으로 명명된 도구에 따라 다르므로 필드는 `unknown`으로 입력됩니다. 기본 제공 형태는 [도구 출력 타입](#tool-output-types)에 나열되어 있습니다.1597`tool_result` 블록을 전달하는 메시지에서 `tool_use_result`는 모델로 전송된 텍스트가 아니라 도구의 구조화된 출력 객체입니다. 해당 형태는 일치하는 `tool_use` 블록으로 명명된 도구에 따라 다르므로 필드는 `unknown`으로 입력됩니다. 기본 제공 형태는 [도구 출력 타입](#tool-output-types)에 나열되어 있습니다.

1598 1598

1599`Agent` 도구의 경우 `tool_use_result`는 [`AgentOutput`](#agent-2)입니다. `completed` 결과에서 `content`는 Claude Code가 `tool_result` 텍스트에 추가하는 에이전트 ID 및 사용량 트레일러 없이 서브에이전트의 보고서를 보유하므로, 해당 텍스트를 구문 분석하는 대신 `tool_use_result`에서 렌더링하세요.1599`Agent` 도구의 경우 `tool_use_result`는 [`AgentOutput`](#agent-2)입니다. `tool_result` 텍스트를 구문 분석하는 대신 이를 기반으로 렌더링하세요. `completed` 결과의 `content`는 서브에이전트의 보고서를 보유하며, 보고서가 `SubagentHandback` 도구 호출을 거치는 서브에이전트의 경우 보고서 대신 해당 인계에 관한 짧은 메모를 보유합니다. Claude Code v2.1.271 이상의 [자동 모드](/docs/ko/permission-modes#eliminate-prompts-with-auto-mode)에서는 `completed` 결과를 생성하는 모든 서브에이전트가 [포크](/docs/ko/sub-agents#fork-the-current-conversation)가 아닌 한 그 방식으로 보고하며, Claude는 서브에이전트로부터 보고서를 별도의 메시지로 받습니다.

1600 1600

1601결과에 `resource_link` 블록이 포함된 MCP 도구의 경우, `tool_use_result`는 [`SDKMcpResourceLink`](#sdkmcpresourcelink) 항목의 `resourceLinks` 배열을 가진 객체입니다. Claude는 각 링크를 `tool_result` 블록의 텍스트 줄로 받으므로, 해당 텍스트를 구문 분석하는 대신 `resourceLinks`를 읽어 서버가 반환한 파일을 렌더링하세요. Claude Code는 결과에 링크가 없을 때 `resourceLinks`를 생략하고, 서브에이전트의 결과에서 생략하며, 결과당 최대 50개의 링크를 유지하고, 배열이 64 KiB의 직렬화된 JSON에 도달하면 링크 추가를 중지합니다. `resourceLinks`는 Agent SDK v0.3.257 이상이 필요합니다.1601결과에 `resource_link` 블록이 포함된 MCP 도구의 경우, `tool_use_result`는 [`SDKMcpResourceLink`](#sdkmcpresourcelink) 항목의 `resourceLinks` 배열을 가진 객체입니다. Claude는 각 링크를 `tool_result` 블록의 텍스트 줄로 받으므로, 해당 텍스트를 구문 분석하는 대신 `resourceLinks`를 읽어 서버가 반환한 파일을 렌더링하세요. Claude Code는 결과에 링크가 없을 때 `resourceLinks`를 생략하고, 서브에이전트의 결과에서 생략하며, 결과당 최대 50개의 링크를 유지하고, 배열이 64 KiB의 직렬화된 JSON에 도달하면 링크 추가를 중지합니다. `resourceLinks`는 Agent SDK v0.3.257 이상이 필요합니다.

1602 1602

1603Claude Code에 `message.content`의 어느 부분을 사용자가 붙여넣었는지 알려주려면 `inline_pastes`를 설정하세요. 입력한 것이 아니라 붙여넣은 것이며, 붙여넣기당 하나의 문자열입니다. 프롬프트 텍스트는 사용자가 배치한 위치에 유지됩니다. Claude Code는 각 나열된 붙여넣기를 `<pasted_content>` 태그로 감쌀 수 있으므로 Claude는 붙여넣은 자료를 사용자 자신의 단어와 구별할 수 있습니다. 프롬프트의 마지막 텍스트 블록의 붙여넣기만 감싸집니다. TypeScript Agent SDK v0.3.280 이상이 필요합니다.1603Claude Code에 `message.content`의 어느 부분을 사용자가 입력하지 않고 붙여넣었는지 알려주려면 `inline_pastes`를 설정하세요. 붙여넣기당 하나의 문자열입니다. 프롬프트 텍스트는 사용자가 배치한 위치에 유지됩니다. Claude Code는 각 나열된 붙여넣기를 그 자리에서 `<pasted_content>` 태그로 감쌀 수 있으므로 Claude는 붙여넣은 자료를 사용자 자신의 말과 구별할 수 있습니다. 프롬프트의 마지막 텍스트 블록의 붙여넣기만 감싸집니다. TypeScript Agent SDK v0.3.280 이상이 필요합니다.

1604 1604

1605<h3 id="sdkusermessagereplay">1605<h3 id="sdkusermessagereplay">

1606 `SDKUserMessageReplay`1606 `SDKUserMessageReplay`

1704결과의 여러 필드는 `subtype` 이상의 진단 세부 정보를 전달합니다:1704결과의 여러 필드는 `subtype` 이상의 진단 세부 정보를 전달합니다:

1705 1705

1706* `api_error_status`: 대화를 종료한 API 오류의 HTTP 상태 코드입니다. 턴이 API 오류 없이 끝났을 때는 없거나 `null`입니다.1706* `api_error_status`: 대화를 종료한 API 오류의 HTTP 상태 코드입니다. 턴이 API 오류 없이 끝났을 때는 없거나 `null`입니다.

1707* `ttft_ms`: 첫 번째 완전한 어시스턴트 메시지가 도착할 때 측정된 밀리초 단위의 첫 번째 토큰까지의 시간입니다. 성공 팔에만 있습니다.1707* `ttft_ms`: 첫 번째 완전한 어시스턴트 메시지가 도착할 때 측정된 밀리초 단위의 첫 번째 토큰까지의 시간입니다. 성공 분기에만 있습니다.

1708* `ttft_stream_ms`: 응답 스트림이 열릴 때 첫 번째 `message_start` 스트림 이벤트까지의 밀리초 단위 시간입니다. `ttft_ms`보다 낮습니다. 두 사이의 간격은 첫 번째 메시지를 스트리밍하는 데 소요된 시간입니다. 성공 팔에만 있습니다.1708* `ttft_stream_ms`: 응답 스트림이 열릴 때 첫 번째 `message_start` 스트림 이벤트까지의 밀리초 단위 시간입니다. `ttft_ms`보다 낮습니다. 두 값 사이의 차이는 첫 번째 메시지를 스트리밍하는 데 소요된 시간입니다. 성공 분기에만 있습니다.

1709* `user_message_uuid`: 이 턴이 답변한 메시지의 `uuid`입니다. 어느 결과가 이를 전달하는지는 [`user_message_uuid`](#user_message_uuid)를 참조하세요.1709* `user_message_uuid`: 이 턴이 답변한 메시지의 `uuid`입니다. 어느 결과가 이를 전달하는지는 [`user_message_uuid`](#user_message_uuid)를 참조하세요.

1710* `user_message_uuids`: Claude Code가 이 턴에서 답변한 모든 메시지의 `uuid`입니다. [`user_message_uuids`](#user_message_uuids)를 참조하세요.1710* `user_message_uuids`: Claude Code가 이 턴에서 답변한 모든 메시지의 `uuid`입니다. [`user_message_uuids`](#user_message_uuids)를 참조하세요.

1711* `resume_reason`: Claude Code가 재시작으로 중단된 후 이 턴을 다시 실행한 이유입니다. 두 팔에 모두 있으며, 이러한 다시 실행에만 있습니다. [`resume_reason`](#resume_reason)을 참조하세요.1711* `resume_reason`: Claude Code가 재시작으로 중단된 후 이 턴을 다시 실행한 이유입니다. 두 분기에 모두 있으며, 이러한 다시 실행에만 있습니다. [`resume_reason`](#resume_reason)을 참조하세요.

1712* `local_command`: 턴이 디스패치한 명령의 이름이며, `/compact` 같은 에이전트 루프에 들어가지 않고 명령이 완료된 턴의 성공 결과에 있습니다. 이름은 소문자 문자와 밑줄로 접혀 있으므로 `/reload-plugins`는 `reload_plugins`를 보고합니다. MCP 서버가 제공하는 명령과 기본 제공 `/mcp`는 `mcp`를 보고합니다. 직접 정의한 명령은 `custom`을 보고합니다. 인수는 절대 포함되지 않습니다. 에이전트 루프에 들어간 모든 턴과 명령을 실행하지 않은 전송에는 없습니다. Agent SDK v0.3.268 이상이 필요합니다.1712* `local_command`: 턴이 디스패치한 명령의 이름이며, `/compact` 같이 에이전트 루프에 들어가지 않고 명령이 완료된 턴의 성공 결과에 있습니다. 이름은 소문자와 밑줄로 변환되므로 `/reload-plugins`는 `reload_plugins`를 보고합니다. MCP 서버가 제공하는 명령과 기본 제공 `/mcp`는 `mcp`를 보고합니다. 직접 정의한 명령은 `custom`을 보고합니다. 인수는 절대 포함되지 않습니다. 에이전트 루프에 들어간 모든 턴과 명령을 실행하지 않은 전송에는 없습니다. Agent SDK v0.3.268 이상이 필요합니다.

1713* `request_sent_wall_ms`: Claude Code가 API 요청을 디스패치한 에포크 밀리초이며, 서버 측 타임스탬프에 대한 조인입니다. [`user_message_uuid`](#user_message_uuid)와 함께만 있으며, `is_error` false인 성공 결과에서 API 요청을 보낸 턴에만 있습니다.1713* `request_sent_wall_ms`: Claude Code가 API 요청을 디스패치한 에포크 밀리초이며, 서버 측 타임스탬프와의 조인에 사용됩니다. [`user_message_uuid`](#user_message_uuid)와 함께만 있으며, `is_error`가 false인 성공 결과에서 API 요청을 보낸 턴에만 있습니다.

1714* `first_content_frame_ms`: 첫 번째 `content_block_start` 또는 `content_block_delta` 스트림 이벤트까지의 밀리초 단위 시간이며, 생각 블록을 콘텐츠로 계산합니다. 성공 팔에만 있으며, `is_error`가 false일 때만 있습니다. Agent SDK v0.3.260 이상이 필요합니다.1714* `first_content_frame_ms`: 첫 번째 `content_block_start` 또는 `content_block_delta` 스트림 이벤트까지의 밀리초 단위 시간이며, thinking 블록을 콘텐츠로 계산합니다. 성공 분기에만 있으며, `is_error`가 false일 때만 있습니다. Agent SDK v0.3.260 이상이 필요합니다.

1715* `first_stream_post_ms`, `first_stream_post_ack_ms`, `first_stream_post_wall_ms`: 턴의 첫 번째 스트림 이벤트를 업로드하기 위한 타이밍입니다. Claude Code는 [클라우드 세션](/docs/ko/claude-code-on-the-web) 같은 claude.ai로 스트리밍하는 세션에서만 기록하며, `query()`가 생성하는 결과는 이를 전달하지 않습니다. Agent SDK v0.3.260 이상이 필요합니다.1715* `first_stream_post_ms`, `first_stream_post_ack_ms`, `first_stream_post_wall_ms`: 턴의 첫 번째 스트림 이벤트를 업로드하기 위한 타이밍입니다. Claude Code는 [클라우드 세션](/docs/ko/claude-code-on-the-web) 같은 claude.ai로 스트리밍하는 세션에서만 기록하며, `query()`가 생성하는 결과는 이를 전달하지 않습니다. Agent SDK v0.3.260 이상이 필요합니다.

1716* `usage`: 메인 에이전트 루프만 해당합니다. 서브에이전트 및 보조 모델 호출을 제외하며, 스트리밍 입력 세션에서는 턴당입니다. 토큰/비용 회계에는 `modelUsage`를 선호하세요.1716* `usage`: 메인 에이전트 루프만 해당합니다. 서브에이전트 및 보조 모델 호출을 제외하며, 스트리밍 입력 세션에서는 턴당입니다. 토큰/비용 회계에는 `modelUsage`를 선호하세요.

1717* `modelUsage`: 이 `query()` 호출 중에 쿼리 파이프라인을 통해 수행된 모든 모델 호출에 대한 모델별 합계이며, 메인 루프, 서브에이전트, 압축 및 Workflow 에이전트 같은 내부 호출을 포함합니다. 권한 분류자 및 토큰 계산 요청 같은 해당 파이프라인 외부의 도우미 호출은 제외됩니다. 세션을 재개하는 호출도 [세션의 이전 호출에서 복원된 모델별 합계](/docs/ko/agent-sdk/cost-tracking#accumulate-costs-across-multiple-calls)를 계산합니다. 스트리밍 입력 세션에서 합계는 턴 전체에 누적되므로 결과 전체에서 합산하는 대신 최신 결과를 읽으세요. 재설정에 대해서는 [스트리밍 입력 모드에서 비용 추적](/docs/ko/agent-sdk/cost-tracking#track-costs-in-streaming-input-mode)을 참조하고, 0으로 설정된 결과에 대해서는 [세션 충돌 후 합계 복구](/docs/ko/agent-sdk/cost-tracking#recover-totals-after-a-session-crash)를 참조하세요.1717* `modelUsage`: 이 `query()` 호출 중에 쿼리 파이프라인을 통해 수행된 모든 모델 호출에 대한 모델별 합계이며, 메인 루프, 서브에이전트, 압축 및 Workflow 에이전트 같은 내부 호출을 포함합니다. 권한 분류기 및 토큰 계산 요청 같은 해당 파이프라인 외부의 도우미 호출은 제외됩니다. 세션을 재개하는 호출도 [세션의 이전 호출에서 복원된 모델별 합계](/docs/ko/agent-sdk/cost-tracking#accumulate-costs-across-multiple-calls)를 계산합니다. 스트리밍 입력 세션에서 합계는 턴 전체에 누적되므로 결과 전체에서 합산하는 대신 최신 결과를 읽으세요. 재설정에 대해서는 [스트리밍 입력 모드에서 비용 추적](/docs/ko/agent-sdk/cost-tracking#track-costs-in-streaming-input-mode)을 참조하고, 0으로 설정된 결과에 대해서는 [세션 충돌 후 합계 복구](/docs/ko/agent-sdk/cost-tracking#recover-totals-after-a-session-crash)를 참조하세요.

1718* `total_cost_usd`: `modelUsage`와 동일한 호출을 포함하고 동일한 지점에서 재설정되는 누적 예상 비용(USD)입니다. 세션을 재개하는 호출도 [세션의 이전 호출에서 복원된 합계](/docs/ko/agent-sdk/cost-tracking#accumulate-costs-across-multiple-calls)를 계산합니다. 이는 추정치이지 청구 명세서가 아닙니다. 정확도 주의 사항은 [비용 및 사용량 추적](/docs/ko/agent-sdk/cost-tracking)을 참조하세요.1718* `total_cost_usd`: `modelUsage`와 동일한 호출을 포함하고 동일한 지점에서 재설정되는 누적 예상 비용(USD)입니다. 세션을 재개하는 호출도 [세션의 이전 호출에서 복원된 합계](/docs/ko/agent-sdk/cost-tracking#accumulate-costs-across-multiple-calls)를 계산합니다. 이는 추정치이지 청구 명세서가 아닙니다. 정확도 주의 사항은 [비용 및 사용량 추적](/docs/ko/agent-sdk/cost-tracking)을 참조하세요.

1719* `queued_turn_count`: Claude Code가 결과를 생성했을 때 `origin: { kind: "human" }`으로 보낸 메시지 중 여전히 대기 중인 메시지의 수입니다. `0`과 없는 필드가 무엇을 의미하는지는 [`queued_turn_count`](#queued_turn_count)를 참조하세요.1719* `queued_turn_count`: Claude Code가 결과를 생성했을 때 `origin: { kind: "human" }`으로 보낸 메시지 중 여전히 대기 중인 메시지의 수입니다. `0`과 없는 필드가 무엇을 의미하는지는 [`queued_turn_count`](#queued_turn_count)를 참조하세요.

1720* `result_index`: 이 결과가 프로세스가 작성하는 모든 결과에서 0부터 계산하여 실행의 전달 순서에서 어디에 떨어지는지입니다. 두 팔에 모두 있습니다. 쓰기가 실패한 결과도 여전히 번호를 소비하므로 시퀀스의 간격은 결과가 손실되었음을 의미합니다. Agent SDK v0.3.268 이상이 필요합니다.1720* `result_index`: 프로세스가 작성하는 모든 결과에서 0부터 계산하여, 실행의 전달 순서에서 이 결과가 차지하는 위치입니다. 두 분기에 모두 있습니다. 쓰기가 실패한 결과도 여전히 번호를 소비하므로 시퀀스의 간격은 결과가 손실되었음을 의미합니다. Agent SDK v0.3.268 이상이 필요합니다.

1721* `startup_failure_reason`: Claude Code가 알려진 시작 실패로 종료하기 전에 작성하는 `error_during_execution` 결과에서 Claude Code가 시작을 거부한 이유입니다. 값과 어느 실패가 이를 전달하는지는 [`startup_failure_reason`](#startup_failure_reason)을 참조하세요. Agent SDK v0.3.274 이상이 필요합니다.1721* `startup_failure_reason`: Claude Code가 알려진 시작 실패로 종료하기 전에 작성하는 `error_during_execution` 결과에서 Claude Code가 시작을 거부한 이유입니다. 값과 어느 실패가 이를 전달하는지는 [`startup_failure_reason`](#startup_failure_reason)을 참조하세요. Agent SDK v0.3.274 이상이 필요합니다.

1722* `terminal_reason`: 루프가 끝난 이유입니다. `"completed"`, `"max_turns"`, `"tool_deferred"`, `"aborted_streaming"`, `"aborted_tools"`, `"hook_stopped"`, `"stop_hook_prevented"`, `"background_requested"`, `"blocking_limit"`, `"rapid_refill_breaker"`, `"prompt_too_long"`, `"image_error"`, `"model_error"`, `"api_error"`, `"malformed_tool_use_exhausted"`, `"budget_exhausted"`, `"structured_output_retry_exhausted"`, `"tool_deferred_unavailable"`, 또는 `"turn_setup_failed"` 중 하나입니다.1722* `terminal_reason`: 루프가 끝난 이유입니다. `"completed"`, `"max_turns"`, `"tool_deferred"`, `"aborted_streaming"`, `"aborted_tools"`, `"hook_stopped"`, `"stop_hook_prevented"`, `"background_requested"`, `"blocking_limit"`, `"rapid_refill_breaker"`, `"prompt_too_long"`, `"image_error"`, `"model_error"`, `"api_error"`, `"malformed_tool_use_exhausted"`, `"budget_exhausted"`, `"structured_output_retry_exhausted"`, `"tool_deferred_unavailable"`, 또는 `"turn_setup_failed"` 중 하나입니다.

1723* `fast_mode_state`: `"on"`, `"off"`, 또는 `"cooldown"` 중 하나입니다.1723* `fast_mode_state`: `"on"`, `"off"`, 또는 `"cooldown"` 중 하나입니다.

1724* `fast_mode_disabled_reason`: [빠른 모드](/docs/ko/fast-mode)를 지금 사용할 수 없는 이유입니다. 빠른 모드를 차단하는 것이 없을 때는 없지만, 요청이 여전히 표준 속도로 실행될 수 있습니다. 빠른 모드 속도 제한 후 쿨다운 중에 Claude Code는 `fast_mode_state: "cooldown"`을 보고하며 이유 코드 없이 쿨다운이 만료되면 빠른 모드를 다시 활성화합니다. Claude Code v2.1.219 이상이 필요합니다.1724* `fast_mode_disabled_reason`: [빠른 모드](/docs/ko/fast-mode)를 지금 사용할 수 없는 이유입니다. 빠른 모드를 차단하는 것이 없을 때는 없지만, 요청이 여전히 표준 속도로 실행될 수 있습니다. 빠른 모드 속도 제한 후 쿨다운 중에 Claude Code는 이유 코드 없이 `fast_mode_state: "cooldown"`을 보고하며 쿨다운이 만료되면 빠른 모드를 다시 활성화합니다. Claude Code v2.1.219 이상이 필요합니다.

1725 1725

1726이유 코드를 사용하여 자신의 UI에서 빠른 모드가 꺼진 이유를 설명하는 대신 가용성을 다시 도출하세요. 각 코드는 빠른 모드를 차단한 검사의 이름을 지정합니다:1726가용성을 다시 도출하는 대신 이유 코드를 사용하여 자체 UI에서 빠른 모드가 꺼진 이유를 설명하세요. 각 코드는 빠른 모드를 차단한 검사의 이름을 지정합니다:

1727 1727

1728| 이유 코드 | 의미 |1728| 이유 코드 | 의미 |

1729| - | - |1729| - | - |

1733| `network_error` | [가용성 검사](/docs/ko/fast-mode#use-fast-mode-behind-proxies-and-llm-gateways)가 `api.anthropic.com`에 도달할 수 없음 |1733| `network_error` | [가용성 검사](/docs/ko/fast-mode#use-fast-mode-behind-proxies-and-llm-gateways)가 `api.anthropic.com`에 도달할 수 없음 |

1740 1740

1741동일한 필드 쌍이 [`SDKSystemMessage`](#sdksystemmessage)와 [`SDKControlInitializeResponse`](#sdkcontrolinitializeresponse)에 나타나므로 첫 번째 턴 전에 빠른 모드 상태를 읽을 수 있습니다.1741동일한 필드 쌍이 [`SDKSystemMessage`](#sdksystemmessage)와 [`SDKControlInitializeResponse`](#sdkcontrolinitializeresponse)에 나타나므로 첫 번째 턴 전에 빠른 모드 상태를 읽을 수 있습니다.

1742 1742

1743`origin` 필드는 이 결과를 트리거한 사용자 메시지의 [`SDKMessageOrigin`](#sdkmessageorigin)을 전달합니다. SDK가 완료된 배경 작업 같은 합성 후속 턴을 주입할 때, 결과 `SDKResultMessage`는 `origin: { kind: "task-notification" }`을 전달합니다. 트리거가 발생하고 서버 검증 메시지가 다른 세션에서 도착하는 루틴도 이 종류와 함께 도착하며, 각각 [작업 알림 서브종류](#task-notification-subkinds)에 설명된 `subkind`를 가집니다. `kind`를 확인하여 프롬프트에 답변하는 결과를 주입된 후속 조치와 구별한 후 라우팅하거나 억제하세요. 애플리케이션이 [예약된 실행을 선언](#declare-a-scheduled-run)하면, 해당 결과도 `kind: "task-notification"`을 전달하므로 `kind`만으로 억제하지 마세요.1743`origin` 필드는 이 결과를 트리거한 사용자 메시지의 [`SDKMessageOrigin`](#sdkmessageorigin)을 전달합니다. SDK가 완료된 백그라운드 작업 같은 합성 후속 턴을 주입할 때, 결과 `SDKResultMessage`는 `origin: { kind: "task-notification" }`을 전달합니다. 트리거가 발생한 루틴과 다른 세션에서 온 서버 검증 메시지도 이 종류로 도착하며, 각각 [작업 알림 서브종류](#task-notification-subkinds)에 설명된 `subkind`를 가집니다. 라우팅하거나 억제하기 전에 `kind`를 확인하여 프롬프트에 답변하는 결과를 주입된 후속 조치와 구별하세요. 애플리케이션이 [예약된 실행을 선언](#declare-a-scheduled-run)하면, 해당 결과도 `kind: "task-notification"`을 전달하므로 `kind`만으로 억제하지 마세요.

1744 1744

1745여러 배경 작업 완료가 함께 대기 중일 때, Claude Code는 각 턴이 아니라 하나의 턴에서 답변할 수 있습니다. 각 완료는 여전히 이 원점을 가진 자신의 결과를 생성합니다. Claude Code가 함께 답변하는 완료 중 마지막을 제외한 모든 것은 순서대로 `num_turns: 0`인 빈 결과를 생성하며, 마지막 것의 결과는 모두에 답변하는 턴을 전달합니다.1745여러 백그라운드 작업 완료가 함께 대기 중일 때, Claude Code는 각각 하나의 턴이 아니라 하나의 턴에서 모두 답변할 수 있습니다. 각 완료는 여전히 이 origin을 가진 자신의 결과를 생성합니다. Claude Code가 함께 답변하는 완료 중 마지막을 제외한 모든 것은 순서대로 `num_turns: 0`인 빈 결과를 생성하며, 마지막 것의 결과는 모두에 답변하는 턴을 전달합니다.

1746 1746

1747필드는 시작 오류 같은 사용자 턴 전에 내보낸 결과에는 없습니다.1747필드는 시작 오류 같은 사용자 턴 전에 내보낸 결과에는 없습니다.

1748 1748

1749`PreToolUse` 훅이 `permissionDecision: "defer"`를 반환할 때, 결과는 `stop_reason: "tool_deferred"`를 가지며 `deferred_tool_use`는 보류 중인 도구의 `id`, `name`, `input`을 전달합니다. 이 필드를 읽어 자신의 UI에서 요청을 표시한 다음 동일한 `session_id`로 재개하여 계속하세요. 전체 왕복은 [나중에 도구 호출 연기](/docs/ko/hooks#defer-a-tool-call-for-later)를 참조하세요.1749`PreToolUse` 훅이 `permissionDecision: "defer"`를 반환할 때, 결과는 `stop_reason: "tool_deferred"`를 가지며 `deferred_tool_use`는 보류 중인 도구의 `id`, `name`, `input`을 전달합니다. 이 필드를 읽어 자체 UI에서 요청을 표시한 다음 동일한 `session_id`로 재개하여 계속하세요. 전체 왕복은 [나중에 도구 호출 연기](/docs/ko/hooks#defer-a-tool-call-for-later)를 참조하세요.

1750 1750

1751<h4 id="user_message_uuid">1751<h4 id="user_message_uuid">

1752 `user_message_uuid`1752 `user_message_uuid`

1753</h4>1753</h4>

1754 1754

1755턴이 답변하는 [`SDKUserMessage`](#sdkusermessage)의 `uuid`이며, Claude Code의 회신을 보낸 메시지와 일치시킬 수 있도록 에코됩니다. Claude Code는 메시지에 설정한 경우에만 `uuid`를 에코합니다. 필드는 `SDKUserMessage`에서 선택 사항이며, `query()`에 전달된 문자열 프롬프트는 없습니다.1755턴이 답변하는 [`SDKUserMessage`](#sdkusermessage)의 `uuid`이며, Claude Code의 회신을 보낸 메시지와 일치시킬 수 있도록 에코됩니다. Claude Code는 메시지에 설정한 경우에만 `uuid`를 에코합니다. 필드는 `SDKUserMessage`에서 선택 사항이며, `query()`에 전달된 문자열 프롬프트는 이를 전달하지 않습니다.

1756 1756

1757턴이 답변하는 메시지는 턴이 시작된 방식에 따라 다릅니다:1757턴이 답변하는 메시지는 턴이 시작된 방식에 따라 다릅니다:

1758 1758

1759* **보낸 일반 메시지**(즉, `isSynthetic: true` 없음): 턴은 전체 실행 동안 해당 메시지에 답변합니다. 여러 메시지를 가깝게 보낼 때, Claude Code는 이를 하나의 턴으로 병합할 수 있으며, 필드는 마지막 메시지의 `uuid`만 전달합니다. 병합된 메시지 중 하나와 회신을 일치시키려면 [`user_message_uuids`](#user_message_uuids)를 사용하세요.1759* **보낸 일반 메시지**(즉, `isSynthetic: true` 없음): 턴은 전체 실행 동안 해당 메시지에 답변합니다. 여러 메시지를 가깝게 보낼 때, Claude Code는 이를 하나의 턴으로 병합할 수 있으며, 필드는 마지막 메시지의 `uuid`만 전달합니다. 병합된 메시지 중 하나와 회신을 일치시키려면 [`user_message_uuids`](#user_message_uuids)를 사용하세요.

1760* **`isSynthetic: true`로 보낸 메시지**: 턴은 처음에 해당 메시지에 답변합니다. Claude Code가 도구 호출 사이에 일반 메시지를 선택하면, 턴은 그 이후로 선택된 메시지에 답변합니다. 합성 메시지의 `uuid`를 에코하려면 Agent SDK v0.3.265 이상이 필요합니다. 이전 버전은 합성 턴에서 아무것도 에코하지 않습니다.1760* **`isSynthetic: true`로 보낸 메시지**: 턴은 처음에 해당 메시지에 답변합니다. Claude Code가 도구 호출 사이에 일반 메시지를 선택하면, 턴은 그 이후로 선택된 메시지에 답변합니다. 합성 메시지의 `uuid`를 에코하려면 Agent SDK v0.3.265 이상이 필요합니다. 이전 버전은 합성 턴에서 아무것도 에코하지 않습니다.

1761* **Claude Code가 [`CLAUDE_CODE_RESUME_INTERRUPTED_TURN`](/docs/ko/env-vars) 아래에서 중단된 턴을 다시 실행하기 위해 생성하는 프롬프트**: 중단된 턴의 마지막 프롬프트가 보낸 일반 메시지일 때, 턴을 열었는지 또는 Claude Code가 턴 중에 선택했는지 여부에 관계없이, 다시 실행은 처음에 해당 메시지에 답변합니다. [`resume_reason`](#resume_reason)은 중단된 시도의 다시 실행 프레임을 알려줍니다. 마지막 프롬프트가 보낸 일반 메시지가 아닐 때, 다시 실행은 처음에 보낸 메시지에 답변하지 않습니다. Claude Code가 도구 호출 사이에 일반 메시지를 선택하면, 턴은 그 이후로 선택된 메시지에 답변합니다. 중단된 턴의 프롬프트를 에코하려면 Agent SDK v0.3.268 이상이 필요합니다.1761* **Claude Code가 [`CLAUDE_CODE_RESUME_INTERRUPTED_TURN`](/docs/ko/env-vars) 아래에서 중단된 턴을 다시 실행하기 위해 생성하는 프롬프트**: 중단된 턴의 마지막 프롬프트가 보낸 일반 메시지일 때, 턴을 열었는지 또는 Claude Code가 턴 중에 선택했는지 여부에 관계없이, 다시 실행은 처음에 해당 메시지에 답변합니다. [`resume_reason`](#resume_reason)은 다시 실행의 프레임을 중단된 시도의 프레임과 구별해 줍니다. 마지막 프롬프트가 보낸 일반 메시지가 아닐 때, 다시 실행은 처음에 보낸 메시지에 답변하지 않습니다. Claude Code가 도구 호출 사이에 일반 메시지를 선택하면, 턴은 그 이후로 선택된 메시지에 답변합니다. 중단된 턴의 프롬프트를 에코하려면 Agent SDK v0.3.268 이상이 필요합니다.

1762* **Claude Code가 자체적으로 생성한 다른 프롬프트**: 턴은 처음에 보낸 메시지에 답변하지 않으며 프레임은 에코를 전달하지 않습니다. Claude Code가 도구 호출 사이에 일반 메시지를 선택하면, 턴은 그 이후로 해당 메시지에 답변합니다. 선택 에코는 Agent SDK v0.3.265 이상이 필요합니다. 이전 버전은 이러한 턴에서 아무것도 에코하지 않습니다.1762* **Claude Code가 자체적으로 생성한 다른 프롬프트**: 턴은 처음에 보낸 메시지에 답변하지 않으며 프레임은 에코를 전달하지 않습니다. Claude Code가 도구 호출 사이에 일반 메시지를 선택하면, 턴은 그 이후로 해당 메시지에 답변합니다. 선택 에코는 Agent SDK v0.3.265 이상이 필요합니다. 이전 버전은 이러한 턴에서 아무것도 에코하지 않습니다.

1763 1763

1764Claude Code는 세 가지 종류의 프레임에서 답변된 메시지의 `uuid`를 에코합니다:1764Claude Code는 세 가지 종류의 프레임에서 답변된 메시지의 `uuid`를 에코합니다:

1765 1765

1766* **결과**: 보낸 메시지에 답변한 턴의 모든 결과입니다. Agent SDK v0.3.265 이상에서 모든 이러한 결과가 이를 전달합니다. v0.3.265 이전에는 일반 메시지가 시작한 턴의 성공 결과가 턴이 API 요청을 보내지 않았거나 연기된 도구 호출로 끝났을 때 이를 전달하지 않았습니다. v0.3.246 이전에는 오류 결과도 이를 전달하지 않았으며, v0.3.216 이전에는 모든 결과가 이를 전달하지 않았습니다.1766* **결과**: 보낸 메시지에 답변한 턴의 모든 결과입니다. Agent SDK v0.3.265 이상에서 모든 이러한 결과가 이를 전달합니다. v0.3.265 이전에는 일반 메시지가 시작한 턴의 성공 결과가 턴이 API 요청을 보내지 않았거나 연기된 도구 호출로 끝났을 때 이를 전달하지 않았습니다. v0.3.246 이전에는 오류 결과도 이를 전달하지 않았으며, v0.3.216 이전에는 모든 결과가 이를 전달하지 않았습니다.

1767* **턴의 첫 번째 회신**: 첫 번째 [어시스턴트 메시지](#sdkassistantmessage) 또는 `includePartialMessages`를 사용하면 `event.type`이 `ping`이 아닌 첫 번째 [스트림 이벤트](#sdkpartialassistantmessage)이므로 결과가 도착하기 전에 회신을 바인딩할 수 있습니다. 턴이 아무것도 스트리밍하지 않을 때, Claude Code는 대신 첫 번째 어시스턴트 메시지에 설정합니다. 첫 번째 회신 에코는 Agent SDK v0.3.246 이상이 필요합니다. 턴 중에 턴이 답변하는 메시지가 변경될 때, 변경 후 첫 번째 회신도 필드를 전달하며, Agent SDK v0.3.265 이상에서 필드를 전달합니다. 이전 버전은 턴당 하나의 회신 프레임에 설정합니다.1767* **턴의 첫 번째 회신**: 첫 번째 [어시스턴트 메시지](#sdkassistantmessage) 또는 `includePartialMessages`를 사용하면 `event.type`이 `ping`이 아닌 첫 번째 [스트림 이벤트](#sdkpartialassistantmessage)이므로 결과가 도착하기 전에 회신을 바인딩할 수 있습니다. 턴이 아무것도 스트리밍하지 않을 때, Claude Code는 대신 첫 번째 어시스턴트 메시지에 설정합니다. 첫 번째 회신 에코는 Agent SDK v0.3.246 이상이 필요합니다. 턴 중에 턴이 답변하는 메시지가 변경될 때, Agent SDK v0.3.265 이상에서는 변경 후 첫 번째 회신도 필드를 전달합니다. 이전 버전은 턴당 하나의 회신 프레임에 설정합니다.

1768* **턴의 모든 [`thinking_tokens`](#sdkthinkingtokensmessage) 프레임**: 턴의 첫 번째 회신을 기다리지 않고 보낸 메시지에 생각 진행을 귀속시킬 수 있습니다. Agent SDK v0.3.260 이상이 필요합니다.1768* **턴의 모든 [`thinking_tokens`](#sdkthinkingtokensmessage) 프레임**: 턴의 첫 번째 회신을 기다리지 않고 보낸 메시지에 사고 진행을 귀속시킬 수 있습니다. Agent SDK v0.3.260 이상이 필요합니다.

1769 1769

1770Claude Code는 다음 경우에 필드를 생략합니다:1770Claude Code는 다음 경우에 필드를 생략합니다:

1771 1771

1784 1784

1785Claude Code가 턴이 실행되는 동안 보낸 일반 메시지를 선택할 때, 해당 메시지의 `uuid`를 결과의 목록에 추가합니다.1785Claude Code가 턴이 실행되는 동안 보낸 일반 메시지를 선택할 때, 해당 메시지의 `uuid`를 결과의 목록에 추가합니다.

1786 1786

1787첫 번째 회신이나 결과가 목록 없이 `user_message_uuid`를 전달할 때, 이전 Claude Code 버전에서 나온 것이므로 단일 필드로 돌아가세요.1787첫 번째 회신이나 결과가 목록 없이 `user_message_uuid`를 전달할 때, 이전 Claude Code 버전에서 나온 것이므로 단일 필드로 대체하세요.

1788 1788

1789<h4 id="resume_reason">1789<h4 id="resume_reason">

1790 `resume_reason`1790 `resume_reason`

1797* **다시 실행의 결과**: 성공 및 오류 팔 모두에서, 결과가 `user_message_uuid`를 전달하는지 여부에 관계없이.1797* **다시 실행의 결과**: 성공 및 오류 팔 모두에서, 결과가 `user_message_uuid`를 전달하는지 여부에 관계없이.

1798* **다시 실행의 회신 프레임**: [`user_message_uuid`](#user_message_uuid)를 전달하는 것들.1798* **다시 실행의 회신 프레임**: [`user_message_uuid`](#user_message_uuid)를 전달하는 것들.

1799 1799

1800값은 `interrupted_turn` 같은 턴이 다시 실행된 이유를 명명하는 짧은 소문자 토큰입니다. 필드는 다른 모든 턴에는 없습니다.1800값은 `interrupted_turn` 같이 턴이 다시 실행된 이유를 명명하는 짧은 소문자 토큰입니다. 필드는 다른 모든 턴에는 없습니다.

1801 1801

1802<h4 id="queued_turn_count">1802<h4 id="queued_turn_count">

1803 `queued_turn_count`1803 `queued_turn_count`

1807 1807

1808`0`과 없는 필드가 무엇을 의미하는지:1808`0`과 없는 필드가 무엇을 의미하는지:

1809 1809

1810* **`0`**: Claude Code는 해당 `origin` 없이 보낸 메시지를 계산하지 않으며, 작업 알림을 계산하지 않으므로 턴이 여전히 따를 수 있습니다.1810* **`0`**: Claude Code는 해당 `origin` 없이 보낸 메시지를 계산하지 않으며, 작업 알림을 계산하지 않으므로 턴이 여전히 뒤따를 수 있습니다.

1811* **없음**: Claude Code가 충돌이나 치명적 시작 오류 후 내보내는 최종 결과는 필드를 생략하며, [0으로 설정된 합계를 전달할 수 있습니다](/docs/ko/agent-sdk/cost-tracking#recover-totals-after-a-session-crash).1811* **없음**: Claude Code가 충돌이나 치명적 시작 오류 후 내보내는 최종 결과는 필드를 생략하며, [0으로 설정된 합계를 전달할 수 있습니다](/docs/ko/agent-sdk/cost-tracking#recover-totals-after-a-session-crash).

1812 1812

1813<h4 id="startup_failure_reason">1813<h4 id="startup_failure_reason">

1814 `startup_failure_reason`1814 `startup_failure_reason`

1815</h4>1815</h4>

1816 1816

1817Claude Code가 시작을 거부한 이유이므로 애플리케이션이 재시도 대신 수정을 제공할 수 있습니다. Claude Code는 알려진 시작 실패로 종료하기 전에 작성하는 `error_during_execution` 결과에 설정합니다. 해당 결과는 0으로 설정된 합계를 전달하며, 해당 `errors` 배열은 stderr과 동일한 텍스트를 전달합니다. 필드는 다른 모든 결과에는 없습니다. Agent SDK v0.3.274 이상이 필요합니다.1817Claude Code가 시작을 거부한 이유이므로 애플리케이션이 재시도 대신 수정 방법을 제공할 수 있습니다. Claude Code는 알려진 시작 실패로 종료하기 전에 작성하는 `error_during_execution` 결과에 설정합니다. 해당 결과는 0으로 설정된 합계를 전달하며, 해당 `errors` 배열은 stderr과 동일한 텍스트를 전달합니다. 필드는 다른 모든 결과에는 없습니다. Agent SDK v0.3.274 이상이 필요합니다.

1818 1818

1819모든 `SDKStartupFailureReason` 값에 대해 이 결과를 받으려면 [`env`](#options)에서 `CLAUDE_CODE_STARTUP_FAILURE_RESULTS`를 `1`로 설정하세요. 해당 변수 없이, Claude Code는 이러한 실패에 대해서만 결과를 작성하며, 나머지는 stderr 출력, 0이 아닌 종료, 결과 메시지 없음으로 끝납니다:1819모든 `SDKStartupFailureReason` 값에 대해 이 결과를 받으려면 [`env`](#options)에서 `CLAUDE_CODE_STARTUP_FAILURE_RESULTS`를 `1`로 설정하세요. 해당 변수 없이, Claude Code는 다음 실패에 대해서만 결과를 작성하며, 나머지는 stderr 출력, 0이 아닌 종료, 결과 메시지 없음으로 끝납니다:

1820 1820

1821* Claude Code가 [세션을 워크트리로 반환할 수 없기 때문에](/docs/ko/worktrees#the-session-resumes-outside-its-worktree) 중지하는 재개이며, `worktree_unverified` 또는 `worktree_resume_refused`입니다. 해당 섹션은 어느 오류가 어느 값을 전달하는지 말합니다.1821* Claude Code가 [세션을 워크트리로 반환할 수 없기 때문에](/docs/ko/worktrees#the-session-resumes-outside-its-worktree) 중지하는 재개이며, `worktree_unverified` 또는 `worktree_resume_refused`입니다. 해당 섹션은 어느 오류가 어느 값을 전달하는지 설명합니다.

1822* 배경 세션이 보유하는 대화의 거부된 [`continue`](#options)이며, `session_held_by_background`입니다. 이러한 대화의 거부된 [`resume`](#options)의 경우, Claude Code는 변수가 설정되었을 때만 결과를 작성합니다.1822* 백그라운드 세션이 보유하는 대화의 거부된 [`continue`](#options)이며, `session_held_by_background`입니다. 이러한 대화의 거부된 [`resume`](#options)의 경우, Claude Code는 변수가 설정되었을 때만 결과를 작성합니다.

1823 1823

1824```typescript theme={null}1824```typescript theme={null}

1825type SDKStartupFailureReason =1825type SDKStartupFailureReason =

1846 1846

1847| 값 | 세션을 중지한 것 |1847| 값 | 세션을 중지한 것 |

1848| :- | :- |1848| :- | :- |

1849| `org_pin_api_key_conflict` | 관리 설정이 [첫 번째 당사자 또는 Cloud 게이트웨이 로그인](/docs/ko/authentication#restrict-login-to-your-organization)을 요구하며, Anthropic API 키, 인증 토큰, 또는 `apiKeyHelper`가 대신 구성됨 |1849| `org_pin_api_key_conflict` | 관리형 설정이 [퍼스트 파티 또는 Cloud 게이트웨이 로그인](/docs/ko/authentication#restrict-login-to-your-organization)을 요구하며, Anthropic API 키, 인증 토큰, 또는 `apiKeyHelper`가 대신 구성됨 |

1850| `provider_not_allowed` | 관리 설정이 [이 머신이 사용할 수 있는 API 제공자를 나열](/docs/ko/settings-reference#allowedproviders)하며, 세션이 나열되지 않은 제공자 또는 설정이 고정하지 않은 엔드포인트에 대해 설정됨. Claude Code v2.1.285 이상이 필요함 |1850| `provider_not_allowed` | 관리형 설정이 [이 머신이 사용할 수 있는 API 제공자를 나열](/docs/ko/settings-reference#allowedproviders)하며, 세션이 나열되지 않은 제공자 또는 설정이 고정하지 않은 엔드포인트에 대해 설정됨. Claude Code v2.1.285 이상이 필요함 |

1853| `managed_settings_invalid` | 관리 정책 설정을 읽을 수 없음, 핀이 조직을 명명하지 않음, 또는 [관리 모델 제한](/docs/ko/errors#managed-settings-block-the-default-model)이 기본 옵션에 대해 허용된 모델을 남기지 않음 |1853| `managed_settings_invalid` | 관리형 정책 설정을 읽을 수 없음, 핀이 조직을 명명하지 않음, 또는 [관리형 모델 제한](/docs/ko/errors#managed-settings-block-the-default-model)이 기본 옵션에 대해 허용된 모델을 남기지 않음 |

1856| `gateway_access_denied` | Cloud 게이트웨이에 대한 관리 설정 요청이 403으로 돌아옴(게이트웨이의 [문제 해결 테이블](/docs/ko/claude-apps-gateway-deploy#troubleshooting)이 다룸) |1856| `gateway_access_denied` | Cloud 게이트웨이에 대한 관리형 설정 요청이 403으로 돌아옴(게이트웨이의 [문제 해결 테이블](/docs/ko/claude-apps-gateway-deploy#troubleshooting)이 다룸) |

1860| `shell_tool_missing` | Windows에서 사용 가능한 셸 도구가 없음: Git Bash가 없으며, PowerShell이 없거나 `CLAUDE_CODE_USE_POWERSHELL_TOOL`로 꺼짐 |1860| `shell_tool_missing` | Windows에서 사용 가능한 셸 도구가 없음: Git Bash가 없으며, PowerShell이 없거나 `CLAUDE_CODE_USE_POWERSHELL_TOOL`로 꺼짐 |

1866 1866

1867<h3 id="sdksystemmessage">1867<h3 id="sdksystemmessage">

1912`terminal_slash_commands`는 `slash_commands`의 항목 중 인터페이스가 로컬 터미널에 바인딩된 것들의 이름을 지정합니다(예: `exit`). 다른 `slash_commands` 항목처럼 보낼 수 있습니다. 필드는 원격 또는 모바일 클라이언트가 명령 메뉴에서 이를 숨길 수 있도록 존재합니다. 필드는 비어 있지 않을 때만 있으며, Agent SDK v0.3.229 이상이 필요합니다.1912`terminal_slash_commands`는 `slash_commands`의 항목 중 인터페이스가 로컬 터미널에 바인딩된 것들의 이름을 지정합니다(예: `exit`). 다른 `slash_commands` 항목처럼 보낼 수 있습니다. 필드는 원격 또는 모바일 클라이언트가 명령 메뉴에서 이를 숨길 수 있도록 존재합니다. 필드는 비어 있지 않을 때만 있으며, Agent SDK v0.3.229 이상이 필요합니다.

1913 1913

1914* 각 `mcp_servers` 항목의 `source`: 서버의 정의가 어디에서 나왔는지이며, [`McpServerStatus`](#mcpserverstatus)의 `source`와 동일한 값입니다. Agent SDK v0.3.274 이상이 필요합니다.1914* 각 `mcp_servers` 항목의 `source`: 서버의 정의가 어디에서 나왔는지이며, [`McpServerStatus`](#mcpserverstatus)의 `source`와 동일한 값입니다. Agent SDK v0.3.274 이상이 필요합니다.

1915* `effort`: [노력 수준](/docs/ko/model-config#adjust-effort-level) Claude Code가 세션의 다음 요청에서 보내거나, 보내지 않을 때 `null`입니다. Claude Code는 [Remote Control](/docs/ko/remote-control) 클라이언트로 보내는 초기화 메시지에만 필드를 설정하며, 애플리케이션이 읽는 초기화 메시지에서 생략합니다. Agent SDK v0.3.234 이상이 필요합니다.1915* `effort`: Claude Code가 세션의 다음 요청에서 보내는 [effort 수준](/docs/ko/model-config#adjust-effort-level)이며, 보내지 않을 때는 `null`입니다. Claude Code는 [Remote Control](/docs/ko/remote-control) 클라이언트로 보내는 초기화 메시지에만 필드를 설정하며, 애플리케이션이 읽는 초기화 메시지에서는 생략합니다. Agent SDK v0.3.234 이상이 필요합니다.

1916 1916

1917`capabilities` 배열은 이 CLI가 구현하는 프로토콜 동작의 이름을 지정하므로 `claude_code_version` 문자열을 비교하는 대신 기능을 감지할 수 있습니다. 이는 열린 집합입니다: 인식하지 못하는 값은 무시하고, 동작이 의존하는 특정 기능을 확인하세요. 필드는 Claude Code v2.1.205 이상이 필요하며 이전 CLI에는 없습니다.1917`capabilities` 배열은 이 CLI가 구현하는 프로토콜 동작의 이름을 지정하므로 `claude_code_version` 문자열을 비교하는 대신 기능을 감지할 수 있습니다. 이는 열린 집합입니다: 인식하지 못하는 값은 무시하고, 의존하는 동작에 해당하는 특정 기능을 확인하세요. 필드는 Claude Code v2.1.205 이상이 필요하며 이전 CLI에는 없습니다.

1918 1918

1919| 기능 | 의미 |1919| 기능 | 의미 |

1920| - | - |1920| - | - |

1921| `interrupt_receipt_v1` | [`interrupt()`](#query-object)는 중단이 도착했을 때 보류 중이던 메시지를 나열하는 [`SDKControlInterruptResponse`](#sdkcontrolinterruptresponse) 영수증으로 해결됨 |1921| `interrupt_receipt_v1` | [`interrupt()`](#query-object)는 중단이 도착했을 때 보류 중이던 메시지를 나열하는 [`SDKControlInterruptResponse`](#sdkcontrolinterruptresponse) 영수증으로 해결됨 |

1922| `interrupt_cancel_queued_v1` | `interrupt` 제어 요청이 `cancel_queued: true`를 준수하여 영수증이 `still_queued` 아래에 나열할 메시지를 취소하고 대신 `cancelled` 아래에 나열합니다. [`SDKControlInterruptResponse`](#sdkcontrolinterruptresponse)를 참조하세요. Claude Code v2.1.219 이상이 필요함 |1922| `interrupt_cancel_queued_v1` | `interrupt` 제어 요청이 `cancel_queued: true`를 준수하여 영수증이 `still_queued` 아래에 나열할 메시지를 취소하고 대신 `cancelled` 아래에 나열합니다. [`SDKControlInterruptResponse`](#sdkcontrolinterruptresponse)를 참조하세요. Claude Code v2.1.219 이상이 필요함 |

1923 1923

1924`plugin_errors` 배열은 플러그인 로드 실패를 나열합니다. 항목은 로드되지 않았으며 `plugins`에서 없는 플러그인이거나, 훅 파일 같은 부분 없이 로드된 플러그인을 설명합니다. 아무것도 실패하지 않았을 때 키는 생략됩니다. `SDKSystemMessage`는 Agent SDK v0.3.283 이상에서 `plugin_errors`를 선언합니다.1924`plugin_errors` 배열은 플러그인 로드 실패를 나열합니다. 항목은 로드되지 않아 `plugins`에 없는 플러그인이거나, 훅 파일 같은 일부 부분 없이 로드된 플러그인을 설명합니다. 아무것도 실패하지 않았을 때 키는 생략됩니다. `SDKSystemMessage`는 Agent SDK v0.3.283 이상에서 `plugin_errors`를 선언합니다.

1925 1925

1926[`plugins` 옵션](#options)의 디렉토리 또는 아카이브 자체가 로드되지 않을 때, 항목의 `plugin` 필드는 플러그인 이름 대신 `inline[0]` 같은 위치 태그를 보유합니다. 이는 예를 들어 경로가 존재하지 않거나 매니페스트가 유효하지 않을 때 발생합니다. 이러한 항목을 `path` 필드로 옵션과 일치시키세요.1926[`plugins` 옵션](#options)의 디렉터리 또는 아카이브 자체가 로드되지 않을 때, 항목의 `plugin` 필드는 플러그인 이름 대신 `inline[0]` 같은 위치 태그를 보유합니다. 이는 예를 들어 경로가 존재하지 않거나 매니페스트가 유효하지 않을 때 발생합니다. 이러한 항목을 `path` 필드로 옵션과 일치시키세요.

1927 1927

1928아래 테이블은 각 `plugin_errors` 항목의 필드를 나열합니다.1928아래 테이블은 각 `plugin_errors` 항목의 필드를 나열합니다.

1929 1929

1930| 필드 | 타입 | 설명 |1930| 필드 | 타입 | 설명 |

1931| - | - | - |1931| - | - | - |

1936 1936

1937<h3 id="sdkpartialassistantmessage">1937<h3 id="sdkpartialassistantmessage">

1938 `SDKPartialAssistantMessage`1938 `SDKPartialAssistantMessage`

1939</h3>1939</h3>

1940 1940

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

1942 1942

1943```typescript theme={null}1943```typescript theme={null}

1944type SDKPartialAssistantMessage = {1944type SDKPartialAssistantMessage = {

1981 1981

1982루프에서 내보낸 일반 텍스트 배너입니다. Claude Code가 발생시키는 경고, 공지, 기타 비오류 상태 줄과 `UserPromptSubmit` 훅의 블록 이유 같은 훅 피드백을 전달합니다.1982루프에서 내보낸 일반 텍스트 배너입니다. Claude Code가 발생시키는 경고, 공지, 기타 비오류 상태 줄과 `UserPromptSubmit` 훅의 블록 이유 같은 훅 피드백을 전달합니다.

1983 1983

1984Claude Code v2.1.227 이상에서 훅의 [`systemMessage`](/docs/ko/hooks#json-output)는 이 메시지로 도착할 수 있으며, 각 줄은 훅의 이름으로 접두사가 붙습니다(예: `PostToolUse:Bash says:`). 각 [이벤트의 섹션](/docs/ko/hooks#hook-events)은 훅 페이지에서 출력이 어떻게 표시되는지 말합니다.1984Claude Code v2.1.227 이상에서 훅의 [`systemMessage`](/docs/ko/hooks#json-output)는 이 메시지로 도착할 수 있으며, 각 줄에는 훅의 이름이 접두사로 붙습니다(예: `PostToolUse:Bash says:`). 훅 페이지의 각 [이벤트 섹션](/docs/ko/hooks#hook-events)에서 출력이 어떻게 표시되는지 설명합니다.

1985 1985

1986`content`를 주어진 `level`에서 평문으로 렌더링하세요.1986`content`를 주어진 `level`에서 평문으로 렌더링하세요.

1987 1987

2002 `SDKWorkerShuttingDownMessage`2002 `SDKWorkerShuttingDownMessage`

2003</h3>2003</h3>

2004 2004

2005정상적인 워커 분해 시 내보내지므로 원격 클라이언트는 하트비트 타임아웃을 기다리는 대신 워커가 종료된 이유를 표시할 수 있습니다. `reason`은 호스트 CLI에서 설정한 짧은 snake\_case 문자열입니다(예: `"host_exit"` 또는 `"remote_control_disabled"`). 라이브 스트리밍할 때만 이에 대해 조치하세요. 재개된 세션은 이 메시지의 과거 인스턴스를 재생하므로 그 경우 무시하세요.2005정상적인 워커 종료 시 내보내지므로 원격 클라이언트는 하트비트 타임아웃을 기다리는 대신 워커가 종료된 이유를 표시할 수 있습니다. `reason`은 호스트 CLI에서 설정한 짧은 snake\_case 문자열입니다(예: `"host_exit"` 또는 `"remote_control_disabled"`). 라이브 스트리밍할 때만 이에 대해 조치하세요. 재개된 세션은 이 메시지의 과거 인스턴스를 재생하므로 그 경우 무시하세요.

2006 2006

2007```typescript theme={null}2007```typescript theme={null}

2008type SDKWorkerShuttingDownMessage = {2008type SDKWorkerShuttingDownMessage = {

2018 `SDKPluginInstallMessage`2018 `SDKPluginInstallMessage`

2019</h3>2019</h3>

2020 2020

2021플러그인 설치 진행 이벤트입니다. [`CLAUDE_CODE_SYNC_PLUGIN_INSTALL`](/docs/ko/env-vars)이 설정되었을 때 내보내지므로 Agent SDK 애플리케이션이 첫 번째 턴 전에 마켓플레이스 플러그인 설치를 추적할 수 있습니다. `started`와 `completed` 상태는 전체 설치를 괄호로 묶습니다. `installed`와 `failed` 상태는 개별 마켓플레이스를 보고하며 `name`을 포함합니다.2021플러그인 설치 진행 이벤트입니다. [`CLAUDE_CODE_SYNC_PLUGIN_INSTALL`](/docs/ko/env-vars)이 설정되었을 때 내보내지므로 Agent SDK 애플리케이션이 첫 번째 턴 전에 마켓플레이스 플러그인 설치를 추적할 수 있습니다. `started`와 `completed` 상태는 전체 설치의 시작과 끝을 나타냅니다. `installed`와 `failed` 상태는 개별 마켓플레이스를 보고하며 `name`을 포함합니다.

2022 2022

2023```typescript theme={null}2023```typescript theme={null}

2024type SDKPluginInstallMessage = {2024type SDKPluginInstallMessage = {

2036 `SDKPermissionDeniedMessage`2036 `SDKPermissionDeniedMessage`

2037</h3>2037</h3>

2038 2038

2039권한 시스템이 대화형 프롬프트 없이 도구 호출을 거부할 때 내보낸 스트림 이벤트입니다. 이를 사용하여 거부를 UI에서 렌더링하세요. 이는 뒤따르는 `is_error` 도구 결과만 관찰하는 것이 아니라 발생할 때입니다. 어느 거부를 보고하는지는 실행이 권한 프롬프트를 처리하는 방식에 따라 다릅니다:2039권한 시스템이 대화형 프롬프트 없이 도구 호출을 거부할 때 내보내는 스트림 이벤트입니다. 뒤따르는 `is_error` 도구 결과만 관찰하는 대신, 이를 사용하여 거부가 발생하는 즉시 UI에서 렌더링하세요. 어느 거부를 보고하는지는 실행이 권한 프롬프트를 처리하는 방식에 따라 다릅니다:

2040 2040

2041* **[`canUseTool`](#canusetool) 콜백과 기본 [`permissionPrompts: 'host'`](#options)**: 권한 프롬프트는 콜백으로 가며, 이 이벤트는 Claude Code가 호출 없이 자체적으로 결정한 거부를 보고합니다.2041* **[`canUseTool`](#canusetool) 콜백과 기본 [`permissionPrompts: 'host'`](#options)**: 권한 프롬프트는 콜백으로 가며, 이 이벤트는 Claude Code가 콜백을 호출하지 않고 자체적으로 결정한 거부를 보고합니다.

2042* **둘 다 없음**: 베어 `-p` 실행 또는 `canUseTool`도 `permissionPromptToolName`도 설정하지 않는 `query()`, 프롬프트했을 도구 호출을 거부하며, 이 이벤트는 이러한 거부와 Claude Code가 자체적으로 결정한 거부를 보고합니다. v2.1.223 이전에는 Claude Code가 콜백 없는 실행에서 이 이벤트를 내보내지 않았습니다.2042* **둘 다 없음**: 베어 `-p` 실행 또는 `canUseTool`도 `permissionPromptToolName`도 설정하지 않는 `query()`는 확인을 요청했을 도구 호출을 거부하며, 이 이벤트는 이러한 거부와 Claude Code가 자체적으로 결정한 거부를 보고합니다. v2.1.223 이전에는 Claude Code가 콜백 없는 실행에서 이 이벤트를 내보내지 않았습니다.

2043* **MCP 프롬프트 도구**(기본 `permissionPrompts: 'host'`와 함께 `permissionPromptToolName` 또는 [`--permission-prompt-tool`](/docs/ko/cli-reference#cli-flags) 플래그로 설정): Claude Code는 이 이벤트를 전혀 내보내지 않으며, 규칙 거부도 자체적으로 결정한 것도 아닙니다.2043* **MCP 프롬프트 도구**(`permissionPromptToolName` 또는 [`--permission-prompt-tool`](/docs/ko/cli-reference#cli-flags) 플래그로 설정)와 기본 `permissionPrompts: 'host'`: Claude Code는 자체적으로 결정한 규칙 거부에 대해서도 이 이벤트를 전혀 내보내지 않습니다.

2044* **[`permissionPrompts: 'none'`](#options)**: Claude Code는 프롬프트했을 호출을 거부하며, `canUseTool` 또는 MCP 프롬프트 도구도 설정되었을 때도 마찬가지이며, 이 이벤트는 이러한 거부와 Claude Code가 자체적으로 결정한 거부를 보고합니다. Claude Code v2.1.259 이상이 필요합니다.2044* **[`permissionPrompts: 'none'`](#options)**: `canUseTool` 또는 MCP 프롬프트 도구가 함께 설정되어 있더라도 Claude Code는 확인을 요청했을 호출을 거부하며, 이 이벤트는 이러한 거부와 Claude Code가 자체적으로 결정한 거부를 보고합니다. Claude Code v2.1.259 이상이 필요합니다.

2045 2045

2046모든 구성에서 이 이벤트는 `PreToolUse` 훅 경로에서 결정된 거부를 건너뜁니다. 훅이 호출을 거부했는지 또는 거부 규칙이 훅의 허용 또는 요청 결정을 재정의했는지 여부에 관계없이. 이벤트는 또한 최선의 노력입니다: 가끔 Claude Code는 이 이벤트를 내보내지 않고 거부를 기록하므로 [결과 메시지](#sdkresultmessage)의 `permission_denials`이 권위 있는 기록입니다.2046모든 구성에서 이 이벤트는 `PreToolUse` 훅 경로에서 결정된 거부를 건너뜁니다. 훅이 호출을 직접 거부했는지 또는 거부 규칙이 훅의 허용 또는 요청 결정을 재정의했는지는 관계없습니다. 이벤트는 또한 최선의 노력 방식입니다: 가끔 Claude Code는 이 이벤트를 내보내지 않고 거부를 기록하므로 [결과 메시지](#sdkresultmessage)의 `permission_denials`이 권위 있는 기록입니다.

2047 2047

2048```typescript theme={null}2048```typescript theme={null}

2049type SDKPermissionDeniedMessage = {2049type SDKPermissionDeniedMessage = {

2064| - | - | - |2064| - | - | - |

2071 2071

2072<h3 id="sdkpermissiondenial">2072<h3 id="sdkpermissiondenial">

2087 `SDKContextUsage`2087 `SDKContextUsage`

2088</h3>2088</h3>

2089 2089

2090`/context` 보고서의 구조화된 형태이며, [`SDKAssistantMessage`](#sdkassistantmessage)에서 `/context` 결과를 전달하는 것으로 `context_usage`로 전달됩니다. Agent SDK v0.3.232 이상은 타입을 내보냅니다. [`SDKControlGetContextUsageResponse`](#sdkcontrolgetcontextusageresponse)와 달리, 사용량 분석을 렌더링하는 데 필요한 데이터만 전달하며, `color`와 `gridRows` 같은 표시 필드는 없습니다. Claude Code는 메시지 스트림에 나타나지 않는 토큰 계산 API 요청으로 보고서를 계산합니다. [이러한 요청이 어떻게 처리되는지](#sdkcontrolgetcontextusageresponse)를 참조하세요.2090`/context` 보고서의 구조화된 형태이며, `/context` 결과를 전달하는 [`SDKAssistantMessage`](#sdkassistantmessage)에 `context_usage`로 전달됩니다. Agent SDK v0.3.232 이상은 이 타입을 내보냅니다. [`SDKControlGetContextUsageResponse`](#sdkcontrolgetcontextusageresponse)와 달리, 사용량 분석을 렌더링하는 데 필요한 데이터만 전달하며, `color`와 `gridRows` 같은 표시 필드는 없습니다. Claude Code는 메시지 스트림에 나타나지 않는 토큰 계산 API 요청으로 보고서를 계산합니다. [이러한 요청이 어떻게 처리되는지](#sdkcontrolgetcontextusageresponse)를 참조하세요.

2091 2091

2092```typescript theme={null}2092```typescript theme={null}

2093type SDKContextUsage = {2093type SDKContextUsage = {

2124};2124};

2125```2125```

2126 2126

2127테이블은 Claude Code가 각 필드에 넣는 것을 나열합니다. `model`에서 `over_limit`까지의 필드는 세션 전체를 설명하며, 수집 필드는 개별 항목에 토큰을 귀속시킵니다.2127테이블은 Claude Code가 각 필드에 넣는 것을 나열합니다. `model`에서 `over_limit`까지의 필드는 세션 전체를 설명하며, 컬렉션 필드는 개별 항목에 토큰을 귀속시킵니다.

2128 2128

2129| 필드 | 타입 | 설명 |2129| 필드 | 타입 | 설명 |

2130| - | - | - |2130| - | - | - |

2133| `raw_max_tokens` | `number` | 모델의 컨텍스트 윈도우 또는 적용되는 낮은 [자동 압축 윈도우](/docs/ko/model-config#context-window-and-auto-compaction)(예: 설정한 것 또는 1M 토큰 윈도우가 있는 일부 모델에 Claude Code가 적용하는 200K 경계). Claude Code는 `total_tokens`를 이 윈도우에 대해 측정 |2133| `raw_max_tokens` | `number` | 모델의 컨텍스트 윈도우 또는 적용되는 경우 더 낮은 [자동 압축 윈도우](/docs/ko/model-config#context-window-and-auto-compaction)(예: 직접 설정한 것 또는 1M 토큰 윈도우가 있는 일부 모델에 Claude Code가 적용하는 200K 경계). Claude Code는 `total_tokens`를 이 윈도우에 대해 측정 |

2141 2141

2142`over_limit.kind`는 Claude Code가 윈도우를 해결한 방식을 기록하며, 다음 요청을 API가 수락하는지 여부가 아닙니다:2142`over_limit.kind`는 다음 요청을 API가 수락하는지 여부가 아니라 Claude Code가 윈도우를 결정한 방식을 기록합니다:

2143 2143

2144* `hard_limit`: 윈도우는 Claude Code가 모델 자신의 제한이라고 믿는 것이며, 그 이상으로 API가 요청을 거부함2144* `hard_limit`: 윈도우는 Claude Code가 모델 자체의 제한이라고 판단한 것이며, 이를 넘으면 API가 요청을 거부함

2145* `compaction_window`: 윈도우는 압축 정책 윈도우이며, 모델의 제한과 일치할 수도 있고 아닐 수도 있음2145* `compaction_window`: 윈도우는 압축 정책 윈도우이며, 모델의 제한과 일치할 수도 있고 아닐 수도 있음

2146 2146

2147Claude Code는 기존 것을 재구성하는 대신 선택적 필드로 새 데이터를 추가하여 타입을 점진적으로 발전시킵니다. 알고 있는 필드를 읽고 인식하지 못하는 것은 무시하세요.2147Claude Code는 기존 필드를 재구성하는 대신 새 데이터를 선택적 필드로 추가하는 방식으로 타입을 점진적으로 발전시킵니다. 알고 있는 필드를 읽고 인식하지 못하는 필드는 무시하세요.

2148 2148

2149<h3 id="sdkcontextusagecategory">2149<h3 id="sdkcontextusagecategory">

2150 `SDKContextUsageCategory`2150 `SDKContextUsageCategory`

2151</h3>2151</h3>

2152 2152

2153`/context` 사용량별 범주 분석의 한 행입니다.2153`/context` 범주별 사용량 분석의 한 행입니다.

2154 2154

2155```typescript theme={null}2155```typescript theme={null}

2156type SDKContextUsageCategory = {2156type SDKContextUsageCategory = {

2164 2164

2165| 필드 | 타입 | 설명 |2165| 필드 | 타입 | 설명 |

2166| - | - | - |2166| - | - | - |

2170 2170

2171각 `kind` 값은 행의 토큰이 무엇인지 말합니다:2171각 `kind` 값은 행의 토큰이 무엇인지 나타냅니다:

2172 2172

2173* `used`: 컨텍스트 윈도우를 차지하는 콘텐츠2173* `used`: 컨텍스트 윈도우를 차지하는 콘텐츠

2174* `free`: 남은 윈도우2174* `free`: 남은 윈도우

2175* `buffer`: 압축 예약2175* `buffer`: 압축 예비 공간

2176* `deferred`: Claude Code가 윈도우 밖에 보유하고 사용량 계산에서 제외하는 도구 스키마이며, 인식을 위해 나열됨2176* `deferred`: Claude Code가 윈도우 밖에 보유하고 사용량 계산에서 제외하는 도구 스키마이며, 참고용으로 나열됨

2177 2177

2178<h3 id="sdkmessageorigin">2178<h3 id="sdkmessageorigin">

2179 `SDKMessageOrigin`2179 `SDKMessageOrigin`

2207 2207

2208| `kind` | 의미 |2208| `kind` | 의미 |

2209| - | - |2209| - | - |

2210| `human` | 최종 사용자의 직접 입력. 애플리케이션이 사용자가 입력한 것을 사용자 메시지로 전달하면, 명시적으로 `origin`을 `{ kind: "human" }`으로 설정하세요: Claude Code는 `origin` 없는 사용자 메시지를 미귀속으로 취급하며, [`ultracode` 워크플로우 키워드](/docs/ko/workflows#ask-for-a-workflow-in-your-prompt) 같은 인간 입력 프롬프트를 요구하는 검사는 이를 수락하지 않습니다. v2.1.210 이전에는 Claude Code가 사용자 메시지의 없는 `origin`을 인간 입력으로 취급했습니다. |2210| `human` | 최종 사용자의 직접 입력. 애플리케이션이 사용자가 입력한 것을 사용자 메시지로 전달하면, 명시적으로 `origin`을 `{ kind: "human" }`으로 설정하세요: Claude Code는 `origin` 없는 사용자 메시지를 미귀속으로 취급하며, [`ultracode` 워크플로 키워드](/docs/ko/workflows#ask-for-a-workflow-in-your-prompt) 같이 사람이 입력한 프롬프트를 요구하는 검사는 이를 수락하지 않습니다. v2.1.210 이전에는 Claude Code가 사용자 메시지에 `origin`이 없으면 사람의 입력으로 취급했습니다. |

2212| `peer` | 다른 에이전트의 메시지: 프로세스 내 [팀원](/docs/ko/agent-teams) 또는 [교차 세션 피어](/docs/ko/cross-session-messaging), 다른 Claude Code 세션. [피어 원점 필드](#peer-origin-fields)에서 필드별 의미와 신뢰 모델을 참조하세요. |2212| `peer` | 다른 에이전트의 메시지: 프로세스 내 [팀원](/docs/ko/agent-teams) 또는 [교차 세션 피어](/docs/ko/cross-session-messaging), 즉 다른 Claude Code 세션. 필드별 의미와 신뢰 모델은 [피어 origin 필드](#peer-origin-fields)를 참조하세요. |

2213| `task-notification` | 신선한 사용자 프롬프트 없이 도착하는 전달(예: 완료된 배경 작업)을 위해 주입된 합성 턴. [`SDKTaskNotificationMessage`](#sdktasknotificationmessage)에서 해당 팔을 참조하세요. 애플리케이션이 [예약된 실행으로 선언](#declare-a-scheduled-run)하는 프롬프트도 이 종류를 전달합니다. 선택적 `subkind`는 알림을 발생시킨 것을 표시합니다. [작업 알림 서브종류](#task-notification-subkinds)를 참조하세요. |2213| `task-notification` | 새로운 사용자 프롬프트 없이 도착하는 전달(예: 완료된 백그라운드 작업)을 위해 주입된 합성 턴. 해당 분기는 [`SDKTaskNotificationMessage`](#sdktasknotificationmessage)를 참조하세요. 애플리케이션이 [예약된 실행으로 선언](#declare-a-scheduled-run)하는 프롬프트도 이 종류를 전달합니다. 선택적 `subkind`는 알림을 발생시킨 것을 표시합니다. [작업 알림 서브종류](#task-notification-subkinds)를 참조하세요. |

2216| `unclassified` | 출처를 결정할 수 없는 주입된 턴. Claude Code v2.1.223 이상이 필요합니다. Claude Code가 `isSynthetic: true`와 다른 `kind`로 분류할 수 없는 [`SDKUserMessage`](#sdkusermessage)를 받을 때, 메시지가 도착할 때 이 종류를 설정하고 턴을 인간 입력으로 취급하는 대신 비사용자 소스로 모델에 프레임합니다. 애플리케이션은 이 값을 설정하지 않아야 합니다. |2216| `unclassified` | 출처를 결정할 수 없는 주입된 턴. Claude Code v2.1.223 이상이 필요합니다. Claude Code가 `isSynthetic: true`인 [`SDKUserMessage`](#sdkusermessage)를 받았는데 다른 `kind`로 분류할 수 없을 때, 메시지가 도착하는 시점에 이 종류를 설정하고 턴을 사람의 입력으로 취급하는 대신 비사용자 소스로 모델에 제시합니다. 애플리케이션은 이 값을 설정하지 않아야 합니다. |

2217 2217

2218<h3 id="task-notification-subkinds">2218<h3 id="task-notification-subkinds">

2219 작업 알림 서브종류2219 작업 알림 서브종류

2220</h3>2220</h3>

2221 2221

2222Claude Code가 작업 알림을 세션에 전달할 때, Anthropic 서버가 해당 알림이 어디에서 나왔는지 확인했으면 `origin`에 `subkind`를 설정합니다. 또한 애플리케이션이 [예약된 실행으로 메시지를 선언](#declare-a-scheduled-run)할 때 `subkind`를 설정하며, TypeScript Agent SDK v0.3.280 이상이 필요합니다. `subkind`는 Claude Code v2.1.213 이상이 필요하며, 두 가지 값 중 하나를 취합니다:2222Claude Code가 작업 알림을 세션에 전달할 때, Anthropic 서버가 해당 알림이 어디에서 나왔는지 확인했으면 알림의 `origin`에 `subkind`를 설정합니다. 또한 애플리케이션이 직접 [메시지를 예약된 실행으로 선언](#declare-a-scheduled-run)할 때도 `subkind`를 설정하며, 이는 TypeScript Agent SDK v0.3.280 이상이 필요합니다. `subkind`는 Claude Code v2.1.213 이상이 필요하며, 두 가지 값 중 하나를 취합니다:

2223 2223

2224* `scheduled-trigger`: 알림은 [루틴](/docs/ko/routines)의 저장된 프롬프트이며, 루틴의 트리거 중 하나가 발생했기 때문에 전달됩니다: 일정, [API 트리거](/docs/ko/routines#add-an-api-trigger), [GitHub 트리거](/docs/ko/routines#add-a-github-trigger), 또는 **지금 실행**. 애플리케이션이 [예약된 실행으로 선언](#declare-a-scheduled-run)하는 프롬프트도 이 값을 전달합니다. Claude Code는 이를 세션의 할당된 작업으로 모델에 프레임하며, [다른 작업 알림이 전달하는 공지](#sdktasknotificationmessage)와 다른 공지를 사용합니다.2224* `scheduled-trigger`: 알림은 [루틴](/docs/ko/routines)의 저장된 프롬프트이며, 루틴의 트리거 중 하나가 발생했기 때문에 전달됩니다: 일정, [API 트리거](/docs/ko/routines#add-an-api-trigger), [GitHub 트리거](/docs/ko/routines#add-a-github-trigger), 또는 **Run now**. 애플리케이션이 [예약된 실행으로 선언](#declare-a-scheduled-run)하는 프롬프트도 이 값을 전달합니다. Claude Code는 이를 세션의 할당된 작업으로 모델에 제시하며, [다른 작업 알림이 전달하는 공지](#sdktasknotificationmessage)와 다른 공지를 사용합니다.

2225* `peer-send-message`: 알림은 [클라우드 세션](/docs/ko/claude-code-on-the-web)이 서로 메시지를 보내는 데 사용하는 서버 측 `send_message` 도구의 메시지이며, [교차 세션 `SendMessage` 도구](/docs/ko/cross-session-messaging)가 아니며, Anthropic 서버가 두 세션이 동일한 비공개 세션 그룹에 속한다고 확인했습니다. Claude Code v2.1.224 이상이 필요합니다. 서버가 그 방식으로 확인하지 않은 `send_message` 전달은 `subkind`를 얻지 못합니다.2225* `peer-send-message`: 알림은 다른 세션이 [클라우드 세션](/docs/ko/claude-code-on-the-web)이 서로 메시지를 보내는 데 사용하는 서버 측 `send_message` 도구로 보낸 메시지이며([교차 세션 `SendMessage` 도구](/docs/ko/cross-session-messaging)가 아님), Anthropic 서버가 두 세션이 동일한 비공개 세션 그룹에 속한다고 확인했습니다. Claude Code v2.1.224 이상이 필요합니다. 서버가 그 방식으로 확인하지 않은 `send_message` 전달은 subkind를 얻지 못합니다.

2226 2226

2227다른 모든 작업 알림에는 `subkind`가 없습니다. 여기에는 [PR 활동](/docs/ko/claude-code-on-the-web#how-claude-responds-to-pr-activity)이 세션에 전달되고 완료된 작업 같은 배경 이벤트가 포함됩니다. [교차 세션 `SendMessage` 도구](/docs/ko/cross-session-messaging)의 메시지는 작업 알림이 아닙니다: 동일한 머신의 세션에서 오든 다른 머신의 Anthropic 서버를 통해 오든, Claude Code는 이들에게 `kind: "peer"`를 제공하고 [피어 원점 필드](#peer-origin-fields)를 제공합니다.2227다른 모든 작업 알림에는 `subkind`가 없습니다. 여기에는 세션에 전달되는 [PR 활동](/docs/ko/claude-code-on-the-web#how-claude-responds-to-pr-activity)과 완료된 작업 같은 백그라운드 이벤트가 포함됩니다. [교차 세션 `SendMessage` 도구](/docs/ko/cross-session-messaging)의 메시지는 작업 알림이 아닙니다: 동일한 머신의 세션에서 오든 다른 머신에서 Anthropic 서버를 통해 오든, Claude Code는 이들에게 `kind: "peer"`와 [피어 origin 필드](#peer-origin-fields)를 부여합니다.

2228 2228

2229`fireReason`은 `scheduled-trigger` 알림이 발생한 이유를 `scheduled`, `manual`, `retry`, `catch_up`, 또는 `api` 같은 짧은 소문자 토큰으로 말합니다. Anthropic 서버는 [루틴](/docs/ko/routines)의 전달에 설정하며, 애플리케이션은 예약된 실행을 선언할 때 설정합니다. 어느 것도 보내지 않았을 때는 없습니다. TypeScript Agent SDK v0.3.280 이상이 필요합니다.2229`fireReason`은 `scheduled-trigger` 알림이 발생한 이유를 `scheduled`, `manual`, `retry`, `catch_up`, 또는 `api` 같은 짧은 소문자 토큰으로 나타냅니다. Anthropic 서버는 [루틴](/docs/ko/routines)의 전달에 이를 설정하며, 애플리케이션은 예약된 실행을 선언할 때 설정합니다. 둘 다 보내지 않았을 때는 없습니다. TypeScript Agent SDK v0.3.280 이상이 필요합니다.

2230 2230

2231<h4 id="declare-a-scheduled-run">2231<h4 id="declare-a-scheduled-run">

2232 예약된 실행 선언2232 예약된 실행 선언

2233</h4>2233</h4>

2234 2234

2235애플리케이션이 자신의 일정에 따라 프롬프트를 실행하면, 각 실행을 선언하여 Claude Code가 턴을 라이브 사용자 입력이 아니라 예약된 작업으로 모델에 프레임하도록 하세요. [`env`](#options)에서 `CLAUDE_CODE_HOST_SCHEDULED_RUN`을 `1`로 설정하여 세션을 시작한 다음, 실행의 [`SDKUserMessage`](#sdkusermessage)를 `origin: { kind: "task-notification", subkind: "scheduled-trigger", fireReason: "scheduled" }`와 `isSynthetic` 없이 보내세요. Claude Code는 해당 변수 없이 시작된 프로세스에서 선언을 무시합니다. 또한 환경이 [`CLAUDECODE`](/docs/ko/env-vars) 또는 `CLAUDE_CODE_CHILD_SESSION`을 전달하는 프로세스에서도 무시합니다. Claude Code는 값이 1\~32개의 소문자 문자 또는 밑줄일 때만 `fireReason`을 유지합니다. TypeScript Agent SDK v0.3.280 이상이 필요합니다.2235애플리케이션이 자체 일정에 따라 프롬프트를 실행한다면, 각 실행을 선언하여 Claude Code가 턴을 사용자의 실시간 입력이 아니라 예약 작업으로 모델에 제시하도록 하세요. [`env`](#options)에서 `CLAUDE_CODE_HOST_SCHEDULED_RUN`을 `1`로 설정하여 세션을 시작한 다음, 실행의 [`SDKUserMessage`](#sdkusermessage)를 `origin: { kind: "task-notification", subkind: "scheduled-trigger", fireReason: "scheduled" }`와 함께 `isSynthetic` 없이 보내세요. Claude Code는 해당 변수 없이 시작된 프로세스에서 선언을 무시합니다. 또한 환경에 [`CLAUDECODE`](/docs/ko/env-vars) 또는 `CLAUDE_CODE_CHILD_SESSION`이 있는 프로세스에서도 무시합니다. Claude Code는 값이 1\~32개의 소문자 또는 밑줄일 때만 `fireReason`을 유지합니다. TypeScript Agent SDK v0.3.280 이상이 필요합니다.

2236 2236

2237<h3 id="peer-origin-fields">2237<h3 id="peer-origin-fields">

2238 피어 원점 필드2238 피어 origin 필드

2239</h3>2239</h3>

2240 2240

2241`peer` 원점은 메시지를 보낸 에이전트를 식별합니다: `SendMessage`를 사용하여 `main`으로 보내는 프로세스 내 [팀원](/docs/ko/agent-teams) 또는 [교차 세션 피어](/docs/ko/cross-session-messaging), 다른 Claude Code 세션. 교차 세션 피어는 macOS 및 Linux에서 Claude Code v2.1.224 이상이 필요합니다. [교차 세션 메시징 가용성](/docs/ko/cross-session-messaging#availability)에서 네이티브 Windows 요구 사항을 참조하세요. 교차 세션 피어는 동일한 머신에서 실행되거나, [다른 머신](/docs/ko/cross-session-messaging#message-sessions-on-other-machines)에서 또는 [클라우드](/docs/ko/claude-code-on-the-web)에서 Remote Control을 통해 메시지가 도착할 때 실행될 수 있습니다. 두 종류의 발신자는 필드를 다르게 채웁니다:2241`peer` origin은 메시지를 보낸 에이전트를 식별합니다: `SendMessage`를 사용하여 `main`으로 보내는 프로세스 내 [팀원](/docs/ko/agent-teams) 또는 [교차 세션 피어](/docs/ko/cross-session-messaging), 즉 다른 Claude Code 세션입니다. 교차 세션 피어는 macOS 및 Linux에서 Claude Code v2.1.224 이상이 필요합니다. 네이티브 Windows 요구 사항은 [교차 세션 메시징 가용성](/docs/ko/cross-session-messaging#availability)을 참조하세요. 교차 세션 피어는 동일한 머신에서 실행되거나, 메시지가 Remote Control을 통해 도착하는 경우 [다른 머신](/docs/ko/cross-session-messaging#message-sessions-on-other-machines)이나 [클라우드](/docs/ko/claude-code-on-the-web)에서 실행될 수 있습니다. 두 종류의 발신자는 필드를 다르게 채웁니다:

2242 2242

2243* `from`: 팀원의 이름 또는 교차 세션 피어의 발신자 주소. [일방향 교차 머신 메시지](/docs/ko/cross-session-messaging#message-sessions-on-other-machines)의 경우, 발신자는 회신 주소가 없으며 `from`은 `"unknown"`입니다. 값은 발신자가 작성한 것입니다. `verifiedPeerPid`는 확인된 신원입니다.2243* `from`: 팀원의 이름 또는 교차 세션 피어의 발신자 주소. [일방향 교차 머신 메시지](/docs/ko/cross-session-messaging#message-sessions-on-other-machines)의 경우, 발신자는 회신 주소가 없으며 `from`은 `"unknown"`입니다. 값은 발신자가 작성한 것이며, `verifiedPeerPid`가 확인된 신원입니다.

2244* `fromMode`: 발신 세션의 권한 클래스이며, `bypass` 또는 `prompting`이며, 세션 간에 피어 메시지를 중계하는 호스트(예: [데스크톱 앱](/docs/ko/desktop#work-across-sessions))에서 선언됩니다. Claude Code는 [인바운드 제어](/docs/ko/cross-session-messaging#control-inbound-messages)를 적용할 때 수신 세션에서 읽습니다. Agent SDK v0.3.234 이상이 필요합니다.2244* `fromMode`: 발신 세션의 권한 클래스(`bypass` 또는 `prompting`)이며, 세션 간에 피어 메시지를 중계하는 호스트(예: [데스크톱 앱](/docs/ko/desktop#work-across-sessions))가 선언합니다. Claude Code는 [인바운드 제어](/docs/ko/cross-session-messaging#control-inbound-messages)를 적용할 때 수신 세션에서 이를 읽습니다. Agent SDK v0.3.234 이상이 필요합니다.

2245* `senderTaskId`: 팀원의 작업 ID. 교차 세션 피어에는 없습니다.2245* `senderTaskId`: 팀원의 작업 ID. 교차 세션 피어에는 없습니다.

2246* `name`: 발신자의 표시 이름이며, Claude Code에서 정규화됩니다: Unicode 제어, 형식, 대리, 줄 또는 단락 구분자 코드 포인트를 제거한 다음 결과를 자르고 64개 코드 포인트로 제한하며 줄임표를 추가합니다. Claude Code v2.1.205 이상이 필요합니다.2246* `name`: 발신자의 표시 이름이며, Claude Code가 정규화합니다: Unicode 제어, 형식, 대리, 줄 또는 단락 구분자 코드 포인트를 제거한 다음 결과를 트림하고 64개 코드 포인트로 제한하며 줄임표를 추가합니다. Claude Code v2.1.205 이상이 필요합니다.

2247* `body`: 피어 봉투가 제거된 디코딩된 메시지 본문이며, 모델이 보는 것과 바이트 정확합니다. 팀원 메시지에는 항상 있습니다. 교차 세션 피어의 경우, 턴이 정확히 Claude Code에서 형성한 하나의 피어 봉투일 때만 있습니다. 메시지 텍스트를 다시 구문 분석하는 대신 `name`과 `body`를 렌더링하세요. Claude Code v2.1.205 이상이 필요합니다.2247* `body`: 피어 봉투가 제거된 디코딩된 메시지 본문이며, 모델이 보는 것과 바이트 단위로 정확히 일치합니다. 팀원 메시지에는 항상 있습니다. 교차 세션 피어의 경우, 턴이 Claude Code가 형성한 정확히 하나의 피어 봉투일 때만 있습니다. 메시지 텍스트를 다시 구문 분석하는 대신 `name`과 `body`를 렌더링하세요. Claude Code v2.1.205 이상이 필요합니다.

2248* `fromSession`: 발신자의 호스트 열기 가능 세션 ID이며, 발신자의 호스트에서 설정되므로 UI가 발신 세션으로 다시 링크할 수 있습니다. `from`처럼, 발신자가 주장한 것입니다: 발신자의 신원 증명으로 취급하지 말고 네비게이션 대상으로만 사용하세요. Claude Code v2.1.216 이상이 필요합니다.2248* `fromSession`: 발신자의 호스트에서 열 수 있는 세션 ID이며, 발신자의 호스트가 설정하므로 UI가 발신 세션으로 다시 링크할 수 있습니다. `from`처럼 발신자가 주장한 것입니다: 탐색 대상으로만 사용하고 발신자 신원의 증명으로 취급하지 마세요. Claude Code v2.1.216 이상이 필요합니다.

2249* `verifiedPeerPid`: 이 세션의 교차 세션 메시징 소켓에 연결된 프로세스의 프로세스 ID이며, 커널에서 확인되고 페이로드가 아니라 연결 자체에서 읽습니다. 발신자를 식별하려면 `from`이 아니라 이를 사용하세요: `from`은 동일한 사용자 프로세스에서 위조 가능합니다. 필드는 Claude Code가 확인할 수 없을 때(예: Windows 또는 비소켓 수신)는 없으므로 없는 값은 발신자가 확인되지 않음을 의미합니다. 중계된 트래픽의 경우 메시지의 작성자가 아니라 중계를 식별하며, 프로세스 ID는 재사용 가능하므로 인증 토큰이 아니라 출처로 취급하세요. Claude Code v2.1.216 이상이 필요합니다.2249* `verifiedPeerPid`: 이 세션의 교차 세션 메시징 소켓에 연결된 프로세스의 프로세스 ID이며, 커널이 확인하고 페이로드가 아니라 연결 자체에서 읽습니다. 발신자를 식별하려면 `from`이 아니라 이를 사용하세요: `from`은 동일한 사용자의 어떤 프로세스든 위조할 수 있습니다. Claude Code가 확인할 수 없을 때(예: Windows 또는 비소켓 수신) 필드는 없으므로, 값이 없으면 발신자가 확인되지 않았음을 의미합니다. 중계된 트래픽의 경우 메시지의 작성자가 아니라 중계자를 식별하며, 프로세스 ID는 재사용될 수 있으므로 인증 토큰이 아니라 출처 정보로 취급하세요. Claude Code v2.1.216 이상이 필요합니다.

2250 2250

2251<h2 id="hook-types">2251<h2 id="hook-types">

2252 훅 타입2252 훅 타입

5088```5088```

5089 5089

5090<Warning>5090<Warning>

5091 `context-1m-2025-08-07` 베타는 2026년 4월 30일부터 폐기되었습니다. Claude Sonnet 4.5 또는 Sonnet 4와 함께 이 값을 전달하면 효과가 없으며, 표준 200k 토큰 컨텍스트 윈도우를 초과하는 요청은 오류를 반환합니다. 1M 토큰 컨텍스트 윈도우를 사용하려면 [Claude Opus 5.5, Claude Opus 5, Claude Sonnet 5, Claude Sonnet 4.6, Claude Opus 4.6, Claude Opus 4.7 또는 Claude Opus 4.8](https://platform.claude.com/docs/en/about-claude/models/overview)으로 마이그레이션하세요. 이들은 베타 헤더 없이 표준 가격으로 1M 컨텍스트를 포함합니다.5091 Claude API에서 `context-1m-2025-08-07` 베타는 Claude Sonnet 4.5 및 Claude Sonnet 4에 대해 폐기되었습니다. 두 모델 중 하나와 함께 이 값을 여전히 전달하면 표준 200K 토큰 컨텍스트 윈도우를 초과하는 요청이 오류를 반환하므로, `betas`에서 제거하세요. 1M 토큰 컨텍스트 윈도우로 세션을 실행하려면 `model`을 `claude-sonnet-5-5` 또는 `claude-opus-5-5`처럼 [기본적으로 1M 윈도우로 실행되는](/docs/ko/model-config#extended-context) 모델로 설정하세요. `[1m]` 변형을 통해서만 1M에 도달하는 모델의 경우, `claude-opus-4-6[1m]`처럼 모델 ID에 접미사를 추가하세요.

5092</Warning>5092</Warning>

5093 5093

5094<h3 id="slashcommand">5094<h3 id="slashcommand">

5132| 필드 | 타입 | 설명 |5132| 필드 | 타입 | 설명 |

5133| :- | :- | :- |5133| :- | :- | :- |

5143 5143

5185* **`plugin`**: [플러그인](/docs/ko/agent-sdk/plugins)이 제공하는 서버입니다. 해당 `name`은 [플러그인 제공 MCP 서버](/docs/ko/mcp#plugin-provided-mcp-servers) 아래에 설명된 범위가 지정된 `plugin:<plugin-name>:<server-name>` 형식입니다.5185* **`plugin`**: [플러그인](/docs/ko/agent-sdk/plugins)이 제공하는 서버입니다. 해당 `name`은 [플러그인 제공 MCP 서버](/docs/ko/mcp#plugin-provided-mcp-servers) 아래에 설명된 범위가 지정된 `plugin:<plugin-name>:<server-name>` 형식입니다.

5186* **구성 범위**: `user`, `project`, `local`, `dynamic`, `managed`, `enterprise`, `claudeai` 또는 `agent`. `.mcp.json` 서버는 `project`를 보고하고, [MCP 설치 범위](/docs/ko/mcp#mcp-installation-scopes)는 `local`, `project` 및 `user`를 정의합니다. 애플리케이션이 [`mcpServers` 옵션](#options)에서 전달하는 서버(인프로세스 SDK 서버 제외)는 `dynamic`을 보고합니다.5186* **구성 범위**: `user`, `project`, `local`, `dynamic`, `managed`, `enterprise`, `claudeai` 또는 `agent`. `.mcp.json` 서버는 `project`를 보고하고, [MCP 설치 범위](/docs/ko/mcp#mcp-installation-scopes)는 `local`, `project` 및 `user`를 정의합니다. 애플리케이션이 [`mcpServers` 옵션](#options)에서 전달하는 서버(인프로세스 SDK 서버 제외)는 `dynamic`을 보고합니다.

5187 5187

5188`name` 또는 `mcp__<server>__` 도구 이름 접두사가 아닌 `source`를 기반으로 신뢰 결정을 내립니다. `sdk` 이외의 모든 소스에 대해 `name`은 신뢰할 수 없는 텍스트입니다. 표시하기 전에 이스케이프하세요.5188`name` 또는 `mcp__<server>__` 도구 이름 접두사가 아닌 `source`를 기반으로 신뢰 결정을 내리세요. `sdk` 이외의 모든 소스에 대해 `name`은 신뢰할 수 없는 텍스트입니다. 표시하기 전에 이스케이프하세요.

5189 5189

5190`McpServerProvenance` 및 이를 전달하는 필드는 Agent SDK v0.3.274 이상이 필요합니다.5190`McpServerProvenance` 및 이를 전달하는 필드는 Agent SDK v0.3.274 이상이 필요합니다.

5191 5191

5222 5222

5223`source`는 서버의 정의가 어디에서 왔는지를 나타내며, [`McpServerProvenance`](#mcpserverprovenance)의 `source`와 동일한 값 및 신뢰 규칙을 가집니다. 필드는 Agent SDK v0.3.274 이상이 필요하며 이전 버전에서는 없습니다.5223`source`는 서버의 정의가 어디에서 왔는지를 나타내며, [`McpServerProvenance`](#mcpserverprovenance)의 `source`와 동일한 값 및 신뢰 규칙을 가집니다. 필드는 Agent SDK v0.3.274 이상이 필요하며 이전 버전에서는 없습니다.

5224 5224

5225`_meta`는 도구의 `_meta`의 MCP Apps 멤버를 전달하므로, 애플리케이션이 [`readMcpResource()`](#query-object)로 렌더링할 `ui://` 리소스를 찾을 수 있습니다. Claude Code는 `ui` 객체와 더 이상 사용되지 않는 평면 `ui/resourceUri` 문자열을 통과시키고, 다른 모든 키를 보류합니다. `ui` 내에서 `resourceUri`는 `ui://` 문자열이고 `visibility`는 서버가 설정할 때 `"model"` 및 `"app"`의 배열이며, 다른 멤버는 변경되지 않고 통과합니다. Claude Code는 값이 잘못된 형식일 때 어느 키든 삭제하고, 도구가 둘 다 선언하지 않을 때 `_meta`를 생략합니다. 필드는 초기화 메시지의 [`capabilities`](#sdksystemmessage)에 `mcp_tool_ui_meta_v1`이 포함될 때만 나타나며, TypeScript Agent SDK v0.3.280 이상이 필요합니다.5225`tools` 항목의 `_meta`는 해당 도구의 `_meta`의 MCP Apps 멤버를 전달하므로, 애플리케이션이 [`readMcpResource()`](#query-object)로 렌더링할 `ui://` 리소스를 찾을 수 있습니다. Claude Code는 `ui` 객체와 deprecated된 평면 `ui/resourceUri` 문자열을 통과시키고, 다른 모든 키를 보류합니다. `ui` 내에서 `resourceUri`는 `ui://` 문자열이고 `visibility`는 서버가 설정할 때 `"model"` 및 `"app"`의 배열이며, 다른 멤버는 변경되지 않고 통과합니다. Claude Code는 값이 잘못된 형식일 때 어느 키든 삭제하고, 도구가 둘 다 선언하지 않을 때 `_meta`를 생략합니다. 필드는 초기화 메시지의 [`capabilities`](#sdksystemmessage)에 `mcp_tool_ui_meta_v1`이 포함될 때만 나타나며, TypeScript Agent SDK v0.3.280 이상이 필요합니다.

5226 5226

5227<h3 id="mcpserverstatusconfig">5227<h3 id="mcpserverstatusconfig">

5228 `McpServerStatusConfig`5228 `McpServerStatusConfig`

5339 5339

5340* **청구**: 청구를 위해서가 아니라 관찰 가능성을 위해 분류를 읽으세요. `output_tokens`는 권위 있는 합계로 유지되며, `output_tokens - thinking_tokens`는 비추론 출력을 근사합니다.5340* **청구**: 청구를 위해서가 아니라 관찰 가능성을 위해 분류를 읽으세요. `output_tokens`는 권위 있는 합계로 유지되며, `output_tokens - thinking_tokens`는 비추론 출력을 근사합니다.

5341* **개수가 포함하는 것**: 모델이 생성한 원본 추론이며, 응답 본문에서 반환된 사고 텍스트보다 길 수 있습니다. API는 해당 원본 텍스트를 다시 토큰화하여 계산하므로, 모델의 정확한 생성 개수와 몇 토큰 정도 다를 수 있습니다.5341* **개수가 포함하는 것**: 모델이 생성한 원본 추론이며, 응답 본문에서 반환된 사고 텍스트보다 길 수 있습니다. API는 해당 원본 텍스트를 다시 토큰화하여 계산하므로, 모델의 정확한 생성 개수와 몇 토큰 정도 다를 수 있습니다.

5342* **스트리밍**: 스트리밍된 어시스턴트 메시지에서 이 분류는 `output_tokens`처럼 `message_start` 자리 표시자이며 실제 개수를 전달하지 않으므로, [결과 메시지에서 출력 토큰 읽기](/docs/ko/agent-sdk/cost-tracking#read-output-tokens-from-the-result-message)에서 설명하는 대로 결과 메시지에서 읽으세요. 결과 메시지에서 모델 또는 제공자가 분류를 보고하지 않을 때 `thinking_tokens`는 `0`을 읽습니다.5342* **스트리밍**: 스트리밍된 어시스턴트 메시지에서 이 분류는 `output_tokens`처럼 `message_start` 자리 표시자이며 실제 개수를 전달하지 않으므로, [결과 메시지에서 출력 토큰 읽기](/docs/ko/agent-sdk/cost-tracking#read-output-tokens-from-the-result-message)에서 설명하는 대로 결과 메시지의 `usage`에서 읽으세요. 결과 메시지에서 모델 또는 제공자가 분류를 보고하지 않을 때 `thinking_tokens`는 `0`입니다.

5343* **`null` 경우**: `output_tokens_details` 자체는 Claude Code가 합성하는 어시스턴트 메시지(예: API 오류 메시지)에서 `null`입니다.5343* **`null` 경우**: `output_tokens_details` 자체는 Claude Code가 합성하는 어시스턴트 메시지(예: API 오류 메시지)에서 `null`입니다.

5344 5344

5345<h3 id="calltoolresult">5345<h3 id="calltoolresult">

5352type CallToolResult = {5352type CallToolResult = {

5353 content: Array<{5353 content: Array<{

5355 // 추가 필드는 타입에 따라 다릅니다5355 // Additional fields vary by type

5356 }>;5356 }>;

5357 structuredContent?: Record<string, unknown>;5357 structuredContent?: Record<string, unknown>;

5358 isError?: boolean;5358 isError?: boolean;

5393 `ThinkingConfig`5393 `ThinkingConfig`

5394</h3>5394</h3>

5395 5395

5396Claude의 사고/추론 동작을 제어합니다. 더 이상 사용되지 않는 `maxThinkingTokens`보다 우선합니다.5396Claude의 사고/추론 동작을 제어합니다. deprecated된 `maxThinkingTokens`보다 우선합니다.

5397 5397

5398```typescript theme={null}5398```typescript theme={null}

5399type ThinkingDisplay = "summarized" | "omitted";5399type ThinkingDisplay = "summarized" | "omitted";

5401type ThinkingConfig =5401type ThinkingConfig =

5402 | { type: "adaptive"; display?: ThinkingDisplay } // 모델이 언제 그리고 얼마나 추론할지 결정합니다 (Opus 4.6+)5402 | { type: "adaptive"; display?: ThinkingDisplay } // 모델이 언제 그리고 얼마나 추론할지 결정합니다 (Opus 4.6+)

5403 | { type: "enabled"; budgetTokens?: number; display?: ThinkingDisplay } // 고정 사고 토큰 예산5403 | { type: "enabled"; budgetTokens?: number; display?: ThinkingDisplay } // 고정 사고 토큰 예산

5404 | { type: "disabled" }; // 확장된 사고 없음5404 | { type: "disabled" }; // 확장 사고 없음

5405```5405```

5406 5406

5407선택적 `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` 블록을 반환합니다.5407선택적 `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` 블록을 반환합니다.

5477 5477

5478* **호출이 이름을 지정하지 않는 서버**: Claude Code는 플러그인 제공 서버를 계속 실행합니다. Agent SDK v0.3.210 이상이 필요합니다.5478* **호출이 이름을 지정하지 않는 서버**: Claude Code는 플러그인 제공 서버를 계속 실행합니다. Agent SDK v0.3.210 이상이 필요합니다.

5479* **호출이 이름을 지정하는 서버**: CLI가 시작 시 시작한 기본 제공 서버를 제외하고, Claude Code는 구성이 전달한 것과 다를 때만 실행 중인 서버를 교체합니다.5479* **호출이 이름을 지정하는 서버**: CLI가 시작 시 시작한 기본 제공 서버를 제외하고, Claude Code는 구성이 전달한 것과 다를 때만 실행 중인 서버를 교체합니다.

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

5481 5481

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

5483 5483

5484`added`는 Claude Code가 추가하거나 교체한 서버를 나열하며, 연결 여부와 관계없이 나열합니다. 연결 실패한 서버는 `added`와 `errors` 모두에 나타나며, `errors` 아래에 실패 텍스트가 있고 [`mcpServerStatus()`](#methods)에서 `failed` 행이 있습니다. Claude Code v2.1.257 이전에는 연결 시도가 던진 서버는 `errors` 아래에만 보고되었습니다.5484`added`는 Claude Code가 추가하거나 교체한 서버를 나열하며, 연결 여부와 관계없이 나열합니다. 연결 실패한 서버는 `added`와 `errors` 모두에 나타나며, `errors` 아래에 실패 텍스트가 있고 [`mcpServerStatus()`](#methods)에서 `failed` 행이 있습니다. Claude Code v2.1.257 이전에는 연결 시도가 예외를 던진 서버는 `errors` 아래에만 보고되었습니다.

5485 5485

5486<h3 id="rewindfilesresult">5486<h3 id="rewindfilesresult">

5487 `RewindFilesResult`5487 `RewindFilesResult`

5500};5500};

5501```5501```

5502 5502

5503`skippedLinks`는 되감기가 링크 안전을 위해 복원하거나 삭제하기를 거부한 추적된 경로의 개수를 계산합니다. 추적된 경로의 심볼릭 링크, 하드 링크 또는 기타 일반 파일이 아닌 파일, 체크포인트가 취해졌을 때 가리키던 위치로 더 이상 확인되지 않는 부모 디렉토리, 또는 안전하게 읽을 수 없는 백업입니다. 필드는 Claude Code v2.1.216 이상이 필요합니다. `rewindFiles(userMessageId, { dryRun: true })`를 사용한 미리보기 호출은 이를 설정하지 않습니다.5503`skippedLinks`는 되감기가 링크 안전을 위해 복원하거나 삭제하기를 거부한 추적된 경로의 개수를 계산합니다. 추적된 경로의 심볼릭 링크, 하드 링크 또는 기타 일반 파일이 아닌 파일, 체크포인트가 생성되었을 때 가리키던 위치로 더 이상 확인되지 않는 부모 디렉토리, 또는 안전하게 읽을 수 없는 백업입니다. 필드는 Claude Code v2.1.216 이상이 필요합니다. `rewindFiles(userMessageId, { dryRun: true })`를 사용한 미리보기 호출은 이를 설정하지 않습니다.

5504 5504

5505<h3 id="sdkstatusmessage">5505<h3 id="sdkstatusmessage">

5506 `SDKStatusMessage`5506 `SDKStatusMessage`

5523 `SDKTaskNotificationMessage`5523 `SDKTaskNotificationMessage`

5524</h3>5524</h3>

5525 5525

5526백그라운드 작업이 완료, 실패 또는 중지될 때의 알림입니다. 백그라운드 작업에는 `run_in_background` Bash 명령, [Monitor](#monitor) 감시 및 백그라운드 서브에이전트가 포함됩니다. `ambient` 필드는 [`SDKTaskStartedMessage`](#sdktaskstartedmessage)를 참조하세요. 이는 이를 정의하고 해당 버전 요구 사항을 정의합니다.5526백그라운드 작업이 완료, 실패 또는 중지될 때의 알림입니다. 백그라운드 작업에는 `run_in_background` Bash 명령, [Monitor](#monitor) 감시 및 백그라운드 서브에이전트가 포함됩니다. `ambient` 필드는 이를 정의하고 버전 요구 사항을 설명하는 [`SDKTaskStartedMessage`](#sdktaskstartedmessage)를 참조하세요.

5527 5527

5528```typescript theme={null}5528```typescript theme={null}

5529type SDKTaskNotificationMessage = {5529type SDKTaskNotificationMessage = {

5546};5546};

5547```5547```

5548 5548

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

5550`completed` 알림에서 `resource_links`는 도구가 [`SDKMcpResourceLink`](#sdkmcpresourcelink) 항목으로 참조로 반환한 파일을 나열하며, [`tool_use_result.resourceLinks`](#sdkusermessage)와 동일한 50개 링크 및 64 KiB 제한이 있습니다. Claude Code는 결과에 링크가 없을 때 `resource_links`를 생략하고 MCP 도구 호출이 아닌 작업에 대한 알림에서 생략합니다. `resource_links`는 Agent SDK v0.3.257 이상이 필요합니다.

5551 5550

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

5553 5552

5554작업 알림 턴을 감지하려면, [`SDKUserMessage`](#sdkusermessage) 또는 [`SDKResultMessage`](#sdkresultmessage)의 `origin.kind === "task-notification"`을 확인하세요. 공지 텍스트와 일치하는 대신 필요한 경우 동일한 필드에서 `subkind`를 읽으세요. v2.1.205 이전에 Claude Code는 세션이 유휴 상태일 때 도착한 알림에서 공지를 생략했습니다.5553작업 알림 턴을 감지하려면, 공지 텍스트와 일치시키는 대신 [`SDKUserMessage`](#sdkusermessage) 또는 [`SDKResultMessage`](#sdkresultmessage)의 `origin.kind === "task-notification"`을 확인하세요. 무엇이 이를 발생시켰는지 알아야 하는 경우 동일한 필드에서 `subkind`를 읽으세요. v2.1.205 이전에 Claude Code는 세션이 유휴 상태일 때 도착한 알림에서 공지를 생략했습니다.

5555 5554

5556<h3 id="sdktoolusesummarymessage">5555<h3 id="sdktoolusesummarymessage">

5557 `SDKToolUseSummaryMessage`5556 `SDKToolUseSummaryMessage`

5670 5669

5671* `parent_tool_use_id`로 표시기를 추적합니다. 이는 서브에이전트당 고유합니다. `tool_use_id`는 하나의 어시스턴트 턴에서 병렬 서브에이전트에 의해 공유되므로, 이를 통해 추적하면 한 서브에이전트의 업데이트가 다른 서브에이전트의 표시기를 지울 수 있습니다.5670* `parent_tool_use_id`로 표시기를 추적합니다. 이는 서브에이전트당 고유합니다. `tool_use_id`는 하나의 어시스턴트 턴에서 병렬 서브에이전트에 의해 공유되므로, 이를 통해 추적하면 한 서브에이전트의 업데이트가 다른 서브에이전트의 표시기를 지울 수 있습니다.

5672* 동일한 `parent_tool_use_id`에 대한 나중의 `tool_progress`가 `subagent_retry` 또는 `heartbeat: true` 없이 도착하거나 도구의 결과 메시지가 도착할 때 표시기를 지웁니다. `heartbeat: true`가 있는 프레임은 생동성만 보고하므로, 하나가 도착할 때 표시기를 유지합니다. `attempt`는 지속적인 재시도 아래에서 `max_retries`를 초과할 수 있으므로, 카운터에서 지우기를 파생하지 마세요.5671* 동일한 `parent_tool_use_id`에 대한 나중의 `tool_progress`가 `subagent_retry` 또는 `heartbeat: true` 없이 도착하거나 도구의 결과 메시지가 도착할 때 표시기를 지웁니다. `heartbeat: true`가 있는 프레임은 생동성만 보고하므로, 하나가 도착할 때 표시기를 유지합니다. `attempt`는 지속적인 재시도 아래에서 `max_retries`를 초과할 수 있으므로, 카운터에서 지우기를 파생하지 마세요.

5673* `error_category`를 자신의 메시지 텍스트를 선택하기 위한 토큰으로 취급하고, 표시 텍스트로 취급하지 마세요. 값은 `rate_limit`, `overloaded`, `authentication_failed`, `server_error`, `cloud_credential_error` 및 `unknown`입니다. 인식하지 못하는 값을 `unknown`을 처리하는 방식으로 처리하세요. 나중 릴리스는 값을 추가할 수 있습니다.5672* `error_category`를 자신의 메시지 텍스트를 선택하기 위한 토큰으로 취급하고, 표시 텍스트로 취급하지 마세요. 값은 `rate_limit`, `overloaded`, `authentication_failed`, `server_error`, `cloud_credential_error` 및 `unknown`입니다. 이후 릴리스에서 값이 추가될 수 있으므로, 인식하지 못하는 값은 `unknown`을 처리하는 방식으로 처리하세요.

5674 5673

5675<h3 id="sdkauthstatusmessage">5674<h3 id="sdkauthstatusmessage">

5676 `SDKAuthStatusMessage`5675 `SDKAuthStatusMessage`

5711};5710};

5712```5711```

5713 5712

5714`ambient`는 세션의 작업의 일부가 아닌 작업(예: Claude Code가 자신의 작업을 위해 실행하는 작업)에 대해 `true`입니다. 라이브 업데이트 감시자도 주변입니다. 여기에는 사용자가 요청한 감시자가 포함됩니다. 주변 작업을 활동 표시기에서 제외합니다. 필드는 Agent SDK v0.3.247 이상이 필요합니다.5713`ambient`는 세션의 작업의 일부가 아닌 작업(예: Claude Code가 자신의 작업을 위해 실행하는 작업)에 대해 `true`입니다. 라이브 업데이트 감시자도 ambient이며, 여기에는 사용자가 요청한 감시자가 포함됩니다. ambient 작업을 활동 표시기에서 제외하세요. 필드는 Agent SDK v0.3.247 이상이 필요합니다.

5715 5714

5716`ambient`는 또한 [`SDKTaskNotificationMessage`](#sdktasknotificationmessage) 및 [`SDKBackgroundTasksChangedMessage`](#sdkbackgroundtaskschangedmessage) 항목에 나타납니다.5715`ambient`는 또한 [`SDKTaskNotificationMessage`](#sdktasknotificationmessage) 및 [`SDKBackgroundTasksChangedMessage`](#sdkbackgroundtaskschangedmessage) 항목에 나타납니다.

5717 5716

5720* `is_backgrounded`: Claude Code는 `"local_agent"` 및 `"local_bash"` 작업에서 이를 설정합니다. `true`는 작업이 백그라운드에서 실행됨을 의미합니다. `false`는 작업이 포그라운드에서 실행되고, 이를 시작한 도구 호출은 작업이 완료되거나 백그라운드로 이동할 때까지 차단된 상태로 유지됨을 의미합니다.5719* `is_backgrounded`: Claude Code는 `"local_agent"` 및 `"local_bash"` 작업에서 이를 설정합니다. `true`는 작업이 백그라운드에서 실행됨을 의미합니다. `false`는 작업이 포그라운드에서 실행되고, 이를 시작한 도구 호출은 작업이 완료되거나 백그라운드로 이동할 때까지 차단된 상태로 유지됨을 의미합니다.

5721* `spawn_depth`: Claude Code는 `"local_agent"` 작업에서만 이를 설정합니다. 주 스레드가 생성한 서브에이전트는 깊이 `1`을 가집니다. 깊이 `1` 서브에이전트가 생성한 서브에이전트는 깊이 `2`를 가지며, 이런 식으로 계속됩니다.5720* `spawn_depth`: Claude Code는 `"local_agent"` 작업에서만 이를 설정합니다. 주 스레드가 생성한 서브에이전트는 깊이 `1`을 가집니다. 깊이 `1` 서브에이전트가 생성한 서브에이전트는 깊이 `2`를 가지며, 이런 식으로 계속됩니다.

5722 5721

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

5724 5723

5725<h3 id="sdktaskprogressmessage">5724<h3 id="sdktaskprogressmessage">

5726 `SDKTaskProgressMessage`5725 `SDKTaskProgressMessage`

5754 `SDKTaskUpdatedMessage`5753 `SDKTaskUpdatedMessage`

5755</h3>5754</h3>

5756 5755

5757백그라운드 작업의 상태가 변경될 때 내보내집니다. 예를 들어 `running`에서 `completed`로 전환될 때입니다. `patch`를 `task_id`로 키가 지정된 로컬 작업 맵에 병합합니다. `end_time` 필드는 Unix epoch 타임스탬프(밀리초)이며 `Date.now()`와 비교할 수 있습니다.5756백그라운드 작업의 상태가 변경될 때 내보내집니다. 예를 들어 `running`에서 `completed`로 전환될 때입니다. `patch`를 `task_id`로 키가 지정된 로컬 작업 맵에 병합하세요. `end_time` 필드는 Unix epoch 타임스탬프(밀리초)이며 `Date.now()`와 비교할 수 있습니다.

5758 5757

5759```typescript theme={null}5758```typescript theme={null}

5760type SDKTaskUpdatedMessage = {5759type SDKTaskUpdatedMessage = {

5780 5779

5781라이브 백그라운드 작업 집합이 변경될 때마다 내보내집니다. 작업이 시작되거나, 완료되거나, 종료되거나, 포그라운드 에이전트가 백그라운드로 전환되거나, 작업의 `description` 또는 `ambient` 필드가 변경될 때입니다.5780라이브 백그라운드 작업 집합이 변경될 때마다 내보내집니다. 작업이 시작되거나, 완료되거나, 종료되거나, 포그라운드 에이전트가 백그라운드로 전환되거나, 작업의 `description` 또는 `ambient` 필드가 변경될 때입니다.

5782 5781

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

5784 5783

5785이러한 작업별 이벤트에 대한 순서는 지정되지 않으므로, 두 스트림을 상관시키지 마세요.5784이러한 작업별 이벤트에 대한 순서는 지정되지 않으므로, 두 스트림을 상관시키지 마세요.

5786 5785

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

5788 5787

5789실행 중인 세션에 반복된 `initialize` 제어 요청을 전송할 때(예: 전송 간격 후 [`reinitialize()`](#query-object) 사용), Claude Code는 응답 뒤에 현재 라이브 집합의 스냅샷을 따릅니다. 비어 있을 때도 마찬가지입니다. 재연결하는 호스트는 다음 멤버십 변경을 기다리지 않고 실행 중인 것을 알 수 있습니다. Agent SDK v0.3.239 이전에 Claude Code는 반복된 `initialize` 후 스냅샷을 전송하지 않았습니다.5788실행 중인 세션에 반복된 `initialize` 제어 요청을 전송할 때(예: 전송 간격 후 [`reinitialize()`](#query-object) 사용), Claude Code는 응답 뒤에 현재 라이브 집합의 스냅샷을 보냅니다. 비어 있을 때도 마찬가지입니다. 따라서 재연결하는 호스트는 다음 멤버십 변경을 기다리지 않고 실행 중인 것을 알 수 있습니다. Agent SDK v0.3.239 이전에 Claude Code는 반복된 `initialize` 후 스냅샷을 전송하지 않았습니다.

5790 5789

5791Claude Code v2.1.203 이상이 필요합니다.5790Claude Code v2.1.203 이상이 필요합니다.

5792 5791

5809 `SDKThinkingTokensMessage`5808 `SDKThinkingTokensMessage`

5810</h3>5809</h3>

5811 5810

5812Claude가 사고 블록을 생성하는 동안 내보내집니다. 여기에는 지금까지 생성된 사고 토큰의 실행 추정치가 포함됩니다. `estimated_tokens`는 현재 사고 블록의 실행 합계이고 `estimated_tokens_delta`는 이 프레임에서 전달된 증분입니다. 진행 상황 표시에 사용하세요.5811Claude가 사고 블록(편집된 블록 포함)을 생성하는 동안 내보내집니다. `estimated_tokens`는 현재 블록에서 지금까지 생성된 사고 토큰의 누적 추정치이고, `estimated_tokens_delta`는 이 프레임이 전달하는 증분입니다. 이 추정치는 진행 상황 표시에 사용하세요.

5813 5812

5814모델 또는 제공자가 분류를 보고할 때, 최상위 에이전트 루프의 최종 개수는 결과 메시지의 [`usage.output_tokens_details.thinking_tokens`](#usage)입니다. 이는 [서브에이전트 토큰을 포함하지 않습니다](/docs/ko/agent-sdk/cost-tracking#get-the-total-cost-of-a-query).5813모델 또는 제공자가 분류를 보고할 때, 최상위 에이전트 루프의 최종 개수는 결과 메시지의 [`usage.output_tokens_details.thinking_tokens`](#usage)입니다. 이는 [서브에이전트 토큰을 포함하지 않습니다](/docs/ko/agent-sdk/cost-tracking#get-the-total-cost-of-a-query).

5815 5814

5867};5866};

5868```5867```

5869 5868

5870`errorCode`가 `"credits_required"`일 때, 거부는 포함된 사용량이 소진된 claude.ai 구독에서 발생하며, 사용자가 사용 크레딧을 구매할 때까지 세션을 계속할 수 없습니다. `canUserPurchaseCredits`는 인증된 사용자가 계정에 대한 크레딧을 구매할 수 있는지 여부를 나타내고, `hasChargeableSavedPaymentMethod`는 저장된 결제 방법이 파일에 있는지 여부를 나타냅니다. 세 필드 모두 크레딧 필수 거부가 아닌 속도 제한 이벤트에서는 없습니다. Claude Code v2.1.181 이상이 필요합니다.5869`errorCode`가 `"credits_required"`일 때, 거부는 포함된 사용량이 소진된 claude.ai 구독에서 발생하며, 사용자가 사용량 크레딧을 구매할 때까지 세션을 계속할 수 없습니다. `canUserPurchaseCredits`는 인증된 사용자가 계정에 대한 크레딧을 구매할 수 있는지 여부를 나타내고, `hasChargeableSavedPaymentMethod`는 저장된 결제 수단이 등록되어 있는지 여부를 나타냅니다. 세 필드 모두 크레딧 필수 거부가 아닌 속도 제한 이벤트에서는 없습니다. Claude Code v2.1.181 이상이 필요합니다.

5871 5870

5872<h3 id="sdklocalcommandoutputmessage">5871<h3 id="sdklocalcommandoutputmessage">

5873 `SDKLocalCommandOutputMessage`5872 `SDKLocalCommandOutputMessage`

5889 `SDKCommandsChangedMessage`5888 `SDKCommandsChangedMessage`

5890</h3>5889</h3>

5891 5890

5892사용 가능한 명령 집합이 세션 중간에 변경될 때 내보내집니다. 예를 들어 에이전트가 하위 디렉토리에 들어갈 때 스킬이 발견될 때입니다. `commands` 배열은 전체 업데이트된 목록이므로, 캐시된 명령 목록을 이 페이로드로 바꾸세요. 5891사용 가능한 명령 집합이 세션 중간에 변경될 때 내보내집니다. 예를 들어 에이전트가 하위 디렉토리에 들어갈 때 Claude Code가 스킬을 발견하는 경우입니다. `commands` 배열은 전체 업데이트된 목록이므로, 캐시된 명령 목록을 이 페이로드로 교체하세요. 이 메시지 후 [`supportedCommands()`](#query-object)를 호출하면 동일한 업데이트된 목록을 반환합니다. 메서드는 최신 푸시를 추적하기 때문입니다. 이는 Agent SDK v0.3.216 이상이 필요합니다. 이전 SDK 버전에서 `supportedCommands()`는 초기화 시 캡처된 스냅샷을 반환하며 세션 중간 변경을 반영하지 않습니다.

5893이 메시지 후 [`supportedCommands()`](#query-object)를 호출하면 동일한 업데이트된 목록을 반환합니다. 메서드는 최신 푸시를 추적하기 때문입니다. 이는 Agent SDK v0.3.216 이상이 필요합니다. 이전 SDK 버전에서 `supportedCommands()`는 초기화 시 캡처된 스냅샷을 반환하며 세션 중간 변경을 반영하지 않습니다.

5894 5892

5895Claude Code는 또한 MCP 서버의 [프롬프트](/docs/ko/mcp#use-mcp-prompts-as-commands)가 목록에 참여하거나 떠날 때 이 메시지를 내보냅니다. 예를 들어 세션이 시작된 후 서버가 연결을 완료할 때입니다. 이는 Claude Code v2.1.281 이상이 필요합니다.5893Claude Code는 또한 MCP 서버의 [프롬프트](/docs/ko/mcp#use-mcp-prompts-as-commands)가 목록에 추가되거나 제거될 때 이 메시지를 내보냅니다. 예를 들어 세션이 시작된 후 서버가 연결을 완료할 때입니다. 이는 Claude Code v2.1.281 이상이 필요합니다.

5896 5894

5897```typescript theme={null}5895```typescript theme={null}

5898type SDKCommandsChangedMessage = {5896type SDKCommandsChangedMessage = {

5908 `SDKPromptSuggestionMessage`5906 `SDKPromptSuggestionMessage`

5909</h3>5907</h3>

5910 5908

5911[`promptSuggestions`](#options)가 활성화되었을 때 턴 후에 내보내집니다. Claude Code가 해당 턴에 대한 제안을 생성했습니다. 예측된 다음 사용자 프롬프트를 포함합니다. 제안을 받지 않는 턴은 [Claude Code가 제안을 건너뛸 때](/docs/ko/interactive-mode#when-claude-code-skips-suggestions)를 참조하세요.5909[`promptSuggestions`](#options)가 활성화되어 있고 Claude Code가 해당 턴에 대한 제안을 생성한 경우 턴 후에 내보내집니다. 예측된 다음 사용자 프롬프트를 포함합니다. 제안을 받지 않는 턴은 [Claude Code가 제안을 건너뛸 때](/docs/ko/interactive-mode#when-claude-code-skips-suggestions)를 참조하세요.

5912 5910

5913```typescript theme={null}5911```typescript theme={null}

5914type SDKPromptSuggestionMessage = {5912type SDKPromptSuggestionMessage = {

5945 5943

5946`trigger`, `user_message_uuid` 및 `timestamp` 필드는 Claude Code v2.1.281 이상이 필요합니다.5944`trigger`, `user_message_uuid` 및 `timestamp` 필드는 Claude Code v2.1.281 이상이 필요합니다.

5947 5945

5948SDK의 게시된 타이핑은 Claude Code v2.1.203 이상에서 `SDKConversationResetMessage`를 선언합니다. v2.1.203 이전에는 `SDKMessage`가 타입을 선언하지 않고 참조했으므로, `skipLibCheck`가 비활성화되었을 때 `type === "conversation_reset"`에 대한 좁혀지기가 타입 검사에 실패했습니다.5946SDK의 게시된 타이핑은 Claude Code v2.1.203 이상에서 `SDKConversationResetMessage`를 선언합니다. v2.1.203 이전에는 `SDKMessage`가 타입을 선언하지 않고 참조했으므로, `skipLibCheck`가 비활성화되었을 때 `type === "conversation_reset"`에 대한 타입 좁히기가 타입 검사에 실패했습니다.

5949 5947

5950<h3 id="aborterror">5948<h3 id="aborterror">

5951 `AbortError`5949 `AbortError`

5957class AbortError extends Error {}5955class AbortError extends Error {}

5958```5956```

5959 5957

5960SDK의 타입 API에서 `AbortError`는 유일한 오류 클래스입니다. Claude Code 프로세스 종료 또는 시작 실패와 같은 다른 실패는 일치할 SDK 클래스가 없는 오류로 메시지 반복을 거부합니다. [문제 해결](/docs/ko/agent-sdk/troubleshooting)은 각각의 원인과 수정 사항과 함께 메시지로 이러한 오류를 키합니다.5958SDK의 타입 API에서 `AbortError`는 유일한 오류 클래스입니다. Claude Code 프로세스 종료 또는 시작 실패와 같은 다른 실패는 일치시킬 SDK 클래스가 없는 오류로 메시지 반복을 거부합니다. [문제 해결](/docs/ko/agent-sdk/troubleshooting)은 이러한 오류를 메시지별로 정리하여 각각의 원인과 해결 방법을 제공합니다.

5961 5959

5962<h2 id="sandbox-configuration">5960<h2 id="sandbox-configuration">

5963 샌드박스 구성5961 샌드박스 구성

amazon-bedrock.md +2 −0

Details

527 527

528조직에서 [Claude 앱 게이트웨이](/docs/ko/claude-apps-gateway) 정책을 통해 guardrail 헤더를 전달하는 경우, 이는 [승인이 필요한 설정](/docs/ko/server-managed-settings#environment-variables-and-the-approval-dialog)으로 계산됩니다.528조직에서 [Claude 앱 게이트웨이](/docs/ko/claude-apps-gateway) 정책을 통해 guardrail 헤더를 전달하는 경우, 이는 [승인이 필요한 설정](/docs/ko/server-managed-settings#environment-variables-and-the-approval-dialog)으로 계산됩니다.

529 529

530guardrail이 응답 도중에 차단하는 경우, 그때까지 스트리밍된 텍스트는 그대로 유지되며 응답은 guardrail에 차단된 응답용으로 구성된 메시지로 끝납니다.

531

530<h2 id="use-the-mantle-endpoint">532<h2 id="use-the-mantle-endpoint">

531 Mantle 엔드포인트 사용533 Mantle 엔드포인트 사용

532</h2>534</h2>

chrome.md +96 −34

Details

6 6

7> Claude Code를 Chrome 브라우저에 연결하여 웹 앱을 테스트하고, 콘솔 로그로 디버깅하며, 양식 작성을 자동화하고, 웹 페이지에서 데이터를 추출합니다.7> Claude Code를 Chrome 브라우저에 연결하여 웹 앱을 테스트하고, 콘솔 로그로 디버깅하며, 양식 작성을 자동화하고, 웹 페이지에서 데이터를 추출합니다.

8 8

9Claude Code는 [Claude in Chrome 브라우저 확장 프로그램](https://chromewebstore.google.com/detail/claude/fcoeoabgfenejglbffodgkkbkcdhcgfn)과 통합되어 CLI 또는 [VS Code 확장 프로그램](/docs/ko/vs-code#automate-browser-tasks-with-chrome)에서 브라우저 자동화 기능을 제공합니다. 코드를 작성한 후 컨텍스트를 전환하지 않고 브라우저에서 테스트하고 디버깅합니다.9Claude Code는 [Claude in Chrome 브라우저 확장 프로그램](https://chromewebstore.google.com/detail/claude/fcoeoabgfenejglbffodgkkbkcdhcgfn)과 통합되어 CLI 또는 [VS Code 확장 프로그램](/docs/ko/vs-code#automate-browser-tasks-with-chrome)에서 브라우저 자동화 기능을 제공합니다. 코드를 빌드한 후 컨텍스트를 전환하지 않고 브라우저에서 테스트하고 디버깅합니다.

10 10

11Claude는 브라우저 작업을 위해 새 탭을 열고 브라우저의 로그인 상태를 공유하므로 이미 로그인한 모든 사이트에 액세스할 수 있습니다. 브라우저 작업은 실시간으로 표시되는 Chrome 창에서 실행됩니다. Claude가 로그인 페이지나 CAPTCHA를 만나면 일시 중지하고 수동으로 처리하도록 요청합니다.11Claude는 브라우저 작업을 위해 새 탭을 열고 브라우저의 로그인 상태를 공유하므로 이미 로그인한 모든 사이트에 액세스할 수 있습니다. 브라우저 작업은 실시간으로 표시되는 Chrome 창에서 실행됩니다. Claude가 로그인 페이지나 CAPTCHA를 만나면 일시 중지하고 수동으로 처리하도록 요청합니다.

12 12

13확장 프로그램은 Claude가 연 탭을 세션에 연결된 Chrome 탭 그룹으로 모읍니다. 로컬 세션에서는 세션이 종료될 때 Claude Code가 해당 그룹을 닫는지 여부가 세션이 종료되는 방식에 따라 달라집니다.

15* `/clear`를 입력하면 Claude Code는 열려 있는 페이지를 포함하여 그룹을 닫습니다. 단, clear 이후에도 유지되는 작업이 아직 실행 중인 경우는 예외입니다

16* `/resume`과 같은 명령으로 세션을 전환하거나, Claude Code를 종료하거나, clear 이후에도 유지되는 작업이 아직 실행 중인 상태에서 `/clear`를 실행하면, Claude Code는 그룹에 빈 새 탭만 있는 경우에만 그룹을 닫으므로 아직 읽고 있을 수 있는 페이지는 열린 상태로 유지됩니다

13<Note>18<Note>

14 Chrome 통합은 Google Chrome 및 Microsoft Edge에서 작동합니다. Brave, Arc 또는 기타 Chromium 기반 브라우저에서는 아직 지원되지 않습니다. Windows Subsystem for Linux(WSL)도 지원되지 않습니다.19 Chrome 통합은 Google Chrome 및 Microsoft Edge에서 작동합니다. Claude Code는 Brave, Arc, Vivaldi, Opera를 포함한 기타 Chromium 기반 브라우저에서도 확장 프로그램을 감지하고 연결을 설정합니다. Chrome 통합은 Windows Subsystem for Linux(WSL)에서는 지원되지 않습니다.

15</Note>20</Note>

16 21

17<h2 id="capabilities">22<h2 id="capabilities">

18 기능23 기능

19</h2>24</h2>

20 25

~~21Chrome이 연결되면 단일 워크플로우에서 브라우저 작업과 코딩 작업을 연결할 수 있습니다.~~26Chrome이 연결되면 단일 워크플로에서 브라우저 작업과 코딩 작업을 연결할 수 있습니다.

22 27

23* **라이브 디버깅**: 콘솔 오류 및 DOM 상태를 직접 읽은 후 이를 유발한 코드를 수정합니다.28* **라이브 디버깅**: 콘솔 오류 및 DOM 상태를 직접 읽은 후 이를 유발한 코드를 수정합니다.

~~24* **디자인 검증**: Figma 목업에서 UI를 빌드한 후 브라우저에서 열어 일치하는지 확인합니다.~~29* **디자인 검증**: Figma 목업에서 UI를 만든 후 브라우저에서 열어 일치하는지 확인합니다.

25* **웹 앱 테스트**: 양식 유효성 검사를 테스트하고, 시각적 회귀를 확인하거나, 사용자 흐름을 검증합니다.30* **웹 앱 테스트**: 양식 유효성 검사를 테스트하고, 시각적 회귀를 확인하거나, 사용자 흐름을 검증합니다.

26* **인증된 웹 앱**: API 커넥터 없이 Google Docs, Gmail, Notion 또는 로그인한 모든 앱과 상호작용합니다.31* **인증된 웹 앱**: API 커넥터 없이 Google Docs, Gmail, Notion 또는 로그인한 모든 앱과 상호작용합니다.

27* **데이터 추출**: 웹 페이지에서 구조화된 정보를 가져와 로컬에 저장합니다.32* **데이터 추출**: 웹 페이지에서 구조화된 정보를 가져와 로컬에 저장합니다.

~~28* **작업 자동화**: 데이터 입력, 양식 작성 또는 다중 사이트 워크플로우와 같은 반복적인 브라우저 작업을 자동화합니다.~~33* **작업 자동화**: 데이터 입력, 양식 작성 또는 다중 사이트 워크플로와 같은 반복적인 브라우저 작업을 자동화합니다.

34* **파일 업로드**: 로컬 컴퓨터의 파일을 웹 페이지의 업로드 필드에 첨부합니다.

29* **세션 기록**: 브라우저 상호작용을 GIF로 기록하여 발생한 상황을 문서화하거나 공유합니다.35* **세션 기록**: 브라우저 상호작용을 GIF로 기록하여 발생한 상황을 문서화하거나 공유합니다.

30 36

31<h2 id="prerequisites">37<h2 id="prerequisites">

~~32 필수 요구사항~~38 사전 요구 사항

33</h2>39</h2>

34 40

35Chrome에서 Claude Code를 사용하기 전에 다음이 필요합니다.41Chrome에서 Claude Code를 사용하기 전에 다음이 필요합니다.

36 42

~~37* [Google Chrome](https://www.google.com/chrome/) 또는 [Microsoft Edge](https://www.microsoft.com/edge) 브라우저~~43* [Google Chrome](https://www.google.com/chrome/), [Microsoft Edge](https://www.microsoft.com/edge) 또는 Brave, Arc, Vivaldi, Opera와 같은 기타 Chromium 기반 브라우저

38* [Claude in Chrome 확장 프로그램](https://chromewebstore.google.com/detail/claude/fcoeoabgfenejglbffodgkkbkcdhcgfn) 버전 1.0.36 이상(Chrome 웹 스토어에서 두 브라우저 모두에 사용 가능)44* [Claude in Chrome 확장 프로그램](https://chromewebstore.google.com/detail/claude/fcoeoabgfenejglbffodgkkbkcdhcgfn) 버전 1.0.36 이상(Chrome 웹 스토어에서 제공)

39* [Claude Code](/docs/ko/quickstart#step-1-install-claude-code)45* [Claude Code](/docs/ko/quickstart#step-1-install-claude-code)

40* 직접 Anthropic 플랜 (Pro, Max, Team 또는 Enterprise)46* 직접 Anthropic 플랜 (Pro, Max, Team 또는 Enterprise)

41 47

48Chrome 통합을 사용하려면 `/login`으로 로그인해야 합니다. API 키 또는 [`claude setup-token`](/docs/ko/authentication#generate-a-long-lived-token)으로 생성한 장기 토큰으로 인증하는 경우, 브라우저 확장 프로그램이 해당 자격 증명으로 인증할 수 없으므로 `--chrome`을 전달하더라도 Claude Code는 Chrome 통합을 비활성화한 상태로 유지합니다. v2.1.216 이전에는 이러한 세션에서 Chrome 통합을 활성화할 수 있었지만, 브라우저 확장 프로그램에 연결하려는 모든 시도가 403 오류로 실패했습니다.

42<Note>50<Note>

43 Chrome 통합은 Amazon Bedrock, Google Cloud의 Agent Platform 또는 Microsoft Foundry와 같은 타사 제공자를 통해 사용할 수 없습니다. 타사 제공자를 통해서만 Claude에 액세스하는 경우 이 기능을 사용하려면 별도의 claude.ai 계정이 필요합니다.51 Chrome 통합은 Amazon Bedrock, Google Cloud의 Agent Platform 또는 Microsoft Foundry와 같은 타사 제공자를 통해 사용할 수 없습니다. 타사 제공자를 통해서만 Claude에 액세스하는 경우 이 기능을 사용하려면 별도의 claude.ai 계정이 필요합니다.

44</Note>52</Note>

55 claude --chrome63 claude --chrome

56 ```64 ```

57 65

~~58 기존 세션 내에서 `/chrome`을 실행하여 Chrome을 활성화할 수도 있습니다.~~66 Chrome으로 처음 시작하면 Claude Code가 통합 기능을 소개하고 사이트 권한의 작동 방식을 설명하는 일회성 대화 상자를 표시합니다. Enter 키를 눌러 계속합니다.

68 플래그 없이 이후 세션에서도 Chrome을 활성화하려면 [기본적으로 Chrome 활성화](#enable-chrome-by-default)를 참조하세요.

59 </Step>69 </Step>

60 70

61 <Step title="Claude에게 브라우저 사용을 요청">71 <Step title="Claude에게 브라우저 사용을 요청">

~~62 이 예제는 페이지로 이동하고, 상호작용하며, 터미널이나 편집기에서 모두 발견한 내용을 보고합니다:~~72 이 예제는 페이지로 이동하고, 상호작용하며, 발견한 내용을 보고하는 모든 과정을 터미널이나 편집기에서 수행합니다:

63 73

~~64 ```text theme={null}~~74 ```text wrap theme={null}

65 code.claude.com/docs로 이동하여 검색 상자를 클릭하고,75 code.claude.com/docs로 이동하여 검색 상자를 클릭하고,

66 "hooks"를 입력한 후 나타나는 결과를 알려주세요76 "hooks"를 입력한 후 나타나는 결과를 알려주세요

67 ```77 ```

68 78

~~69 첫 번째 브라우저 작업은 `claude-in-chrome` 스킬을 사용할 수 있는 권한을 요청합니다. 승인하면 Claude가 새 탭을 열고 작업을 시작합니다.~~79 Claude Code가 브라우저 작업 전에 권한을 요청하면 승인합니다. 대화 상자는 `Claude in Chrome wants to`로 시작하며, 세션 동안 해당 사이트의 모든 작업을 허용하는 옵션을 제공합니다. Claude가 새 탭을 열고 작업을 시작합니다.

70 </Step>80 </Step>

71</Steps>81</Steps>

72 82

73언제든지 `/chrome`을 실행하여 연결 상태를 확인하고, 권한을 관리하거나, 확장 프로그램을 다시 연결하거나, 사용할 연결된 브라우저를 선택할 수 있습니다. 브라우저 작업이 시작될 때 둘 이상의 브라우저가 연결되어 있으면 Claude가 하나를 선택하도록 요청합니다.83언제든지 `/chrome`을 실행하여 연결 상태를 확인하고, 권한을 관리하거나, 확장 프로그램을 다시 연결하거나, 사용할 연결된 브라우저를 선택할 수 있습니다. 상태 패널에 "상태: 활성화됨" 및 "확장 프로그램: 설치됨"이 표시되면 통합 기능이 정상적으로 작동하는 것입니다.

85둘 이상의 브라우저가 연결되어 있으면 Claude가 사용할 브라우저를 직접 선택합니다. 선택하기 전에 브라우저 작업이 시작되면 Claude가 하나를 선택하도록 요청합니다. 나중에 브라우저를 전환하려면 `/chrome`을 실행하고 \*\*브라우저 선택…\*\*을 선택합니다. 다른 브라우저가 연결되더라도 Claude는 선택한 브라우저를 계속 사용합니다.

74 86

75VS Code의 경우 [VS Code에서 브라우저 자동화](/docs/ko/vs-code#automate-browser-tasks-with-chrome)를 참조하세요.87VS Code의 경우 [VS Code에서 브라우저 자동화](/docs/ko/vs-code#automate-browser-tasks-with-chrome)를 참조하세요.

76 88

89<h3 id="install-the-extension-when-claude-asks">

90 Claude가 요청할 때 확장 프로그램 설치

91</h3>

93대화형 세션에서 Claude가 브라우저를 필요로 하는데 Claude Code가 확장 프로그램을 감지하지 못하면, Claude Code는 "Claude가 브라우저를 사용하려고 합니다"라는 제목의 설치 프롬프트를 표시합니다. Claude Code는 세션당 최대 한 번만 묻습니다.

95프롬프트는 세 가지 선택지를 제공합니다:

97* **확장 프로그램 설치**: 브라우저에서 확장 프로그램 설치 페이지를 열고 안내형 설정을 시작합니다. Claude Code는 설치를 기다린 후 확장 프로그램을 연결하고 같은 세션에서 브라우저 도구를 활성화합니다. 연결이 준비되면 "브라우저 도구로 계속"을 선택하고, Claude가 브라우저에서 작업을 재개합니다. "브라우저 도구 없이 계속"을 선택하여 설정을 종료하고 나중에 `/chrome`으로 완료할 수 있습니다.

98* **나중에**: 브라우저 도구 없이 작업을 계속합니다. Claude Code는 이후 세션에서 다시 물을 수 있습니다.

99* **다시 묻지 않음**: 이후 세션에서 프롬프트를 표시하지 않습니다. 언제든지 `/chrome`으로 통합 기능을 설정할 수 있습니다.

100

101두 가지 관리형 MCP 정책이 프롬프트를 끕니다:

102

103* 조직이 [`deniedMcpServers` 관리형 설정](/docs/ko/managed-mcp#policy-based-control-with-allowlists-and-denylists)으로 `claude-in-chrome` MCP 서버를 차단하면 Claude Code는 설치 프롬프트를 표시하지 않습니다.

104* 조직이 [관리형 세트와 함께 Claude in Chrome 허용](/docs/ko/managed-mcp#allow-claude-in-chrome-alongside-the-managed-set) 없이 [`managed-mcp.json`](/docs/ko/managed-mcp#exclusive-control-with-managed-mcp-json) 파일을 배포하면 Claude Code는 설치 프롬프트를 표시하지 않습니다.

105

77<h3 id="enable-chrome-by-default">106<h3 id="enable-chrome-by-default">

78 기본적으로 Chrome 활성화107 기본적으로 Chrome 활성화

79</h3>108</h3>

80 109

81각 세션마다 `--chrome`을 전달하지 않으려면 `/chrome`을 실행하고 "기본적으로 활성화"를 선택합니다.110각 세션마다 `--chrome`을 전달하지 않으려면 `/chrome`을 실행하고 "기본적으로 활성화"를 선택합니다.

82 111

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

113

83[VS Code 확장 프로그램](/docs/ko/vs-code#automate-browser-tasks-with-chrome)에서는 Chrome 확장 프로그램이 설치되어 있으면 Chrome을 사용할 수 있습니다. 추가 플래그가 필요하지 않습니다.114[VS Code 확장 프로그램](/docs/ko/vs-code#automate-browser-tasks-with-chrome)에서는 Chrome 확장 프로그램이 설치되어 있으면 Chrome을 사용할 수 있습니다. 추가 플래그가 필요하지 않습니다.

84 115

85<Note>116<Note>

90 사이트 권한 관리121 사이트 권한 관리

91</h3>122</h3>

92 123

93사이트 수준 권한은 Chrome 확장 프로그램에서 상속됩니다. Chrome 확장 프로그램 설정에서 권한을 관리하여 Claude가 탐색하고, 클릭하고, 입력할 수 있는 사이트를 제어합니다.124사이트 수준 권한은 Chrome 확장 프로그램에서 상속됩니다. Chrome 확장 프로그램 설정에서 권한을 관리하여 Claude가 탐색하고, 클릭하고, 입력할 수 있는 사이트를 제어합니다. [자동 모드](/docs/ko/permission-modes#eliminate-prompts-with-auto-mode)에서 자동 모드 분류기 자체가 특정 사이트에 대한 브라우저 호출을 승인하면, 권한 규칙이 Claude in Chrome에 대해 어떤 사이트라도 거부하지 않는 한 확장 프로그램은 해당 호출에 대한 자체 사이트별 확인을 건너뜁니다.

94 125

95<h3 id="browser-tools-in-plan-mode">126<h3 id="browser-tools-in-plan-mode">

~~96 계획 모드에서의 브라우저 도구~~127 플랜 모드의 브라우저 도구

97</h3>128</h3>

98 129

99[계획 모드](/docs/ko/permission-modes#analyze-before-you-edit-with-plan-mode)에서는 페이지나 브라우저 상태만 읽는 브라우저 도구 호출이 권한 프롬프트 없이 실행되고, 상태를 변경하는 호출은 승인을 요청합니다.130[플랜 모드](/docs/ko/permission-modes#analyze-before-you-edit-with-plan-mode)에서는 Claude가 GIF를 녹화하거나, 새 탭을 열거나, 단축키를 실행하기 전에 권한 프롬프트가 표시됩니다. 세션에서 [권한 우회 모드를 사용할 수 있고](/docs/ko/permission-modes#skip-all-checks-with-bypasspermissions-mode) [기능 플래그 가져오기](/docs/ko/env-vars#features-that-need-feature-flag-fetching)가 꺼져 있으면 이러한 호출은 프롬프트 없이 실행됩니다.

~~100~~

101* **읽기 전용 호출**: `read_page`, `get_page_text`, `find`, 콘솔 메시지 또는 네트워크 요청 읽기, 스크린샷 촬영

102* **상태 변경 호출**: 클릭, 입력, 탐색, 탭 및 창 관리, GIF 녹화

103 131

104v2.1.199부터 `tabs_context_mcp`의 `createIfEmpty`, 콘솔 및 네트워크 리더의 `clear`, 스크린샷의 `save_to_disk`와 같이 상태 변경 입력 플래그를 설정하는 읽기 전용 호출도 승인을 요청합니다. `browser_batch` 호출은 내부의 모든 작업이 읽기 전용일 때만 프롬프트 없이 실행됩니다.132`createIfEmpty`를 설정하는 `tabs_context_mcp` 호출도 확인을 요청하며, 이러한 작업 중 하나라도 포함하는 `browser_batch` 호출도 마찬가지입니다.

105 133

106<h2 id="example-workflows">134<h2 id="example-workflows">

107 예제 워크플로우135 예제 워크플로

108</h2>136</h2>

109 137

110이 예제들은 브라우저 작업과 코딩 작업을 결합하는 일반적인 방법을 보여줍니다. `/mcp`를 실행하고 `claude-in-chrome`을 선택한 후 **도구 보기**를 선택하여 사용 가능한 브라우저 도구의 전체 목록을 확인합니다.138이 예제들은 브라우저 작업과 코딩 작업을 결합하는 일반적인 방법을 보여줍니다. `/mcp`를 실행하고 `claude-in-chrome`을 선택한 후 **도구 보기**를 선택하여 사용 가능한 브라우저 도구의 전체 목록을 확인합니다.

115 143

116웹 앱을 개발할 때 Claude에게 변경 사항이 올바르게 작동하는지 확인하도록 요청합니다.144웹 앱을 개발할 때 Claude에게 변경 사항이 올바르게 작동하는지 확인하도록 요청합니다.

117 145

118```text theme={null}146```text wrap theme={null}

119방금 로그인 양식 유효성 검사를 업데이트했습니다. localhost:3000을 열고,147방금 로그인 양식 유효성 검사를 업데이트했습니다. localhost:3000을 열고,

120잘못된 데이터로 양식을 제출해 보고, 오류 메시지가 올바르게148잘못된 데이터로 양식을 제출해 보고, 오류 메시지가 올바르게

121나타나는지 확인해 주시겠어요?149나타나는지 확인해 주시겠어요?

129 157

130Claude는 콘솔 출력을 읽어 문제 진단을 도울 수 있습니다. 로그가 상세할 수 있으므로 모든 콘솔 출력을 요청하는 대신 Claude에게 찾을 패턴을 알려줍니다.158Claude는 콘솔 출력을 읽어 문제 진단을 도울 수 있습니다. 로그가 상세할 수 있으므로 모든 콘솔 출력을 요청하는 대신 Claude에게 찾을 패턴을 알려줍니다.

131 159

132```text theme={null}160```text wrap theme={null}

133대시보드 페이지를 열고 페이지가 로드될 때 콘솔에서 오류를161대시보드 페이지를 열고 페이지가 로드될 때 콘솔에서 오류를

134확인해 주세요.162확인해 주세요.

135```163```

142 170

143반복적인 데이터 입력 작업을 가속화합니다.171반복적인 데이터 입력 작업을 가속화합니다.

144 172

145```text theme={null}173```text wrap theme={null}

146contacts.csv에 고객 연락처 스프레드시트가 있습니다. 각 행에 대해174contacts.csv에 고객 연락처 스프레드시트가 있습니다. 각 행에 대해

147crm.example.com의 CRM으로 이동하여 "연락처 추가"를 클릭하고175crm.example.com의 CRM으로 이동하여 "연락처 추가"를 클릭하고

148이름, 이메일 및 전화 필드를 작성해 주세요.176이름, 이메일 및 전화 필드를 작성해 주세요.

150 178

151Claude는 로컬 파일을 읽고, 웹 인터페이스를 탐색하며, 각 레코드에 대한 데이터를 입력합니다.179Claude는 로컬 파일을 읽고, 웹 인터페이스를 탐색하며, 각 레코드에 대한 데이터를 입력합니다.

152 180

181<h3 id="upload-files-to-web-pages">

182 웹 페이지에 파일 업로드

183</h3>

184

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

186

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

188

189```text wrap theme={null}

190bugs.example.com의 버그 트래커를 열고, 새 이슈를 만든 다음,

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

192```

193

194업로드에는 세 가지 제한이 적용됩니다.

195

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

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

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

199

153<h3 id="draft-content-in-google-docs">200<h3 id="draft-content-in-google-docs">

154 Google Docs에서 콘텐츠 작성201 Google Docs에서 콘텐츠 작성

155</h3>202</h3>

156 203

157API 설정 없이 Claude를 사용하여 문서에 직접 작성합니다.204API 설정 없이 Claude를 사용하여 문서에 직접 작성합니다.

158 205

159```text theme={null}206```text wrap theme={null}

160최근 커밋을 기반으로 프로젝트 업데이트를 작성하고207최근 커밋을 기반으로 프로젝트 업데이트를 작성하고

161docs.google.com/document/d/abc123의 Google Doc에 추가해 주세요.208docs.google.com/document/d/abc123의 Google Doc에 추가해 주세요.

162```209```

169 216

170웹사이트에서 구조화된 정보를 가져옵니다.217웹사이트에서 구조화된 정보를 가져옵니다.

171 218

172```text theme={null}219```text wrap theme={null}

173제품 목록 페이지로 이동하여 각 항목의 이름, 가격 및 가용성을220제품 목록 페이지로 이동하여 각 항목의 이름, 가격 및 가용성을

174추출합니다. 결과를 CSV 파일로 저장해 주세요.221추출합니다. 결과를 CSV 파일로 저장해 주세요.

175```222```

177Claude는 페이지로 이동하여 콘텐츠를 읽고 데이터를 구조화된 형식으로 컴파일합니다.224Claude는 페이지로 이동하여 콘텐츠를 읽고 데이터를 구조화된 형식으로 컴파일합니다.

178 225

179<h3 id="run-multi-site-workflows">226<h3 id="run-multi-site-workflows">

180 다중 사이트 워크플로우 실행227 다중 사이트 워크플로 실행

181</h3>228</h3>

182 229

183여러 웹사이트에서 작업을 조정합니다.230여러 웹사이트에서 작업을 조정합니다.

184 231

185```text theme={null}232```text wrap theme={null}

186내 캘린더에서 내일의 회의를 확인한 후, 외부 참석자가 있는 각233내 캘린더에서 내일의 회의를 확인한 후, 외부 참석자가 있는 각

187회의에 대해 해당 회사 웹사이트를 찾아보고 그들이 하는 일에 대한234회의에 대해 해당 회사 웹사이트를 찾아보고 그들이 하는 일에 대한

188메모를 추가해 주세요.235메모를 추가해 주세요.

189```236```

190 237

191Claude는 탭 전체에서 작업하여 정보를 수집하고 워크플로우를 완료합니다.238Claude는 탭 전체에서 작업하여 정보를 수집하고 워크플로를 완료합니다.

192 239

193<h3 id="record-a-demo-gif">240<h3 id="record-a-demo-gif">

194 데모 GIF 기록241 데모 GIF 기록

196 243

197브라우저 상호작용의 공유 가능한 기록을 만듭니다.244브라우저 상호작용의 공유 가능한 기록을 만듭니다.

198 245

199```text theme={null}246```text wrap theme={null}

200장바구니에 항목을 추가하는 것부터 확인 페이지까지 체크아웃247장바구니에 항목을 추가하는 것부터 확인 페이지까지 체크아웃

201흐름을 완료하는 방법을 보여주는 GIF를 기록해 주세요.248흐름을 완료하는 방법을 보여주는 GIF를 기록해 주세요.

202```249```

203 250

204Claude는 상호작용 시퀀스를 기록하고 GIF 파일로 저장합니다.251Claude는 상호작용 시퀀스를 기록하고 GIF 파일로 저장합니다. 기록에는 로그인된 페이지의 계정 세부 정보를 포함하여 브라우저에 표시되는 모든 내용이 담기므로, 팀 외부에 공유하기 전에 검토합니다.

252

253<h3 id="save-screenshots-to-disk">

254 스크린샷을 디스크에 저장

255</h3>

256

257Claude에게 스크린샷을 파일로 보관하도록 요청합니다.

258

259```text wrap theme={null}

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

261```

262

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

205 264

206<h2 id="troubleshooting">265<h2 id="troubleshooting">

207 문제 해결266 문제 해결

221 280

222Chrome 통합을 처음 활성화할 때 Claude Code는 네이티브 메시징 호스트 구성 파일을 설치합니다. Chrome은 시작 시 이 파일을 읽으므로 첫 번째 시도에서 확장 프로그램이 감지되지 않으면 Chrome을 다시 시작하여 새 구성을 선택합니다.281Chrome 통합을 처음 활성화할 때 Claude Code는 네이티브 메시징 호스트 구성 파일을 설치합니다. Chrome은 시작 시 이 파일을 읽으므로 첫 번째 시도에서 확장 프로그램이 감지되지 않으면 Chrome을 다시 시작하여 새 구성을 선택합니다.

223 282

224v2.1.199부터 Claude Code는 첫 번째 설치 시에만 확장 프로그램을 연결하도록 요청하는 브라우저 탭을 엽니다. Claude Code 빌드 또는 구성 디렉터리 전환 후와 같이 구성 파일을 다시 작성하는 이후 세션에서는 다시 열지 않습니다.283Claude Code는 첫 번째 설치 시에만 확장 프로그램을 연결하도록 요청하는 브라우저 탭을 엽니다. 빌드 또는 구성 디렉터리 전환 후와 같이 이후 세션에서 구성 파일을 다시 작성하는 경우에는 Claude Code가 탭을 다시 열지 않습니다.

225 284

226연결이 계속 실패하면 다음 위치에 호스트 구성 파일이 있는지 확인합니다.285연결이 계속 실패하면 다음 위치에 호스트 구성 파일이 있는지 확인합니다.

227 286

237* **Linux**: `~/.config/microsoft-edge/NativeMessagingHosts/com.anthropic.claude_code_browser_extension.json`296* **Linux**: `~/.config/microsoft-edge/NativeMessagingHosts/com.anthropic.claude_code_browser_extension.json`

238* **Windows**: Windows 레지스트리에서 `HKCU\Software\Microsoft\Edge\NativeMessagingHosts\`를 확인합니다.297* **Windows**: Windows 레지스트리에서 `HKCU\Software\Microsoft\Edge\NativeMessagingHosts\`를 확인합니다.

239 298

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

300

240<h3 id="browser-not-responding">301<h3 id="browser-not-responding">

241 브라우저가 응답하지 않음302 브라우저가 응답하지 않음

242</h3>303</h3>

261 322

262* **명명된 파이프 충돌 (EADDRINUSE)**: 다른 프로세스가 동일한 명명된 파이프를 사용 중인 경우 Claude Code를 다시 시작합니다. Chrome을 사용 중일 수 있는 다른 Claude Code 세션을 모두 닫습니다.323* **명명된 파이프 충돌 (EADDRINUSE)**: 다른 프로세스가 동일한 명명된 파이프를 사용 중인 경우 Claude Code를 다시 시작합니다. Chrome을 사용 중일 수 있는 다른 Claude Code 세션을 모두 닫습니다.

263* **네이티브 메시징 호스트 오류**: 시작 시 네이티브 메시징 호스트가 충돌하면 Claude Code를 다시 설치하여 호스트 구성을 다시 생성해 봅니다.324* **네이티브 메시징 호스트 오류**: 시작 시 네이티브 메시징 호스트가 충돌하면 Claude Code를 다시 설치하여 호스트 구성을 다시 생성해 봅니다.

325* **설정 페이지가 열리지 않음**: Claude Code를 업데이트합니다. v2.1.211 이전에는 Windows에서 확장 프로그램 연결을 요청하는 브라우저 탭이 열리지 않을 수 있었습니다.

264 326

265<h3 id="common-error-messages">327<h3 id="common-error-messages">

266 일반적인 오류 메시지328 일반적인 오류 메시지

270 332

271| 오류 | 원인 | 해결 방법 |333| 오류 | 원인 | 해결 방법 |

272| - | - | - |334| - | - | - |

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

277 339

cli-reference.md +22 −14

Details

7> Claude Code 명령줄 인터페이스의 완전한 참조로, 명령어와 플래그를 포함합니다.7> Claude Code 명령줄 인터페이스의 완전한 참조로, 명령어와 플래그를 포함합니다.

8 8

9<h2 id="cli-commands">9<h2 id="cli-commands">

~~10 CLI 명령어~~10 CLI 명령

11</h2>11</h2>

12 12

~~13이러한 명령어를 사용하여 세션을 시작하고, 콘텐츠를 파이프하고, 대화를 재개하고, 업데이트를 관리할 수 있습니다:~~13이러한 명령을 사용하여 세션을 시작하고, 콘텐츠를 파이프하고, 대화를 재개하고, 업데이트를 관리할 수 있습니다:

14 14

~~15| 명령어 | 설명 | 예시 |~~15| 명령 | 설명 | 예시 |

16| :- | :- | :- |16| :- | :- | :- |

26| `claude install [version]` | 네이티브 바이너리를 설치하거나 재설치합니다. `2.1.118`과 같은 버전, 또는 `stable` 또는 `latest`를 허용합니다. [특정 버전 설치](/docs/ko/setup#install-a-specific-version) 참조 | `claude install stable` |26| `claude install [version]` | 네이티브 바이너리를 설치하거나 재설치합니다. `2.1.118`과 같은 버전, 또는 `stable` 또는 `latest`를 허용합니다. [특정 버전 설치](/docs/ko/setup#install-a-specific-version) 참조 | `claude install stable` |

27| `claude auth login` | Anthropic 계정에 로그인합니다. `--email`을 사용하여 이메일 주소를 미리 입력하고, `--sso`를 사용하여 SSO 인증을 강제하고, `--console`을 사용하여 Claude 구독 대신 API 사용 청구를 위해 Anthropic Console로 로그인할 수 있습니다 | `claude auth login --console` |27| `claude auth login` | Anthropic 계정에 로그인합니다. `--email`을 사용하여 이메일 주소를 미리 입력하고, `--sso`를 사용하여 SSO 인증을 강제하고, `--console`을 사용하여 Claude 구독 대신 API 사용 청구를 위해 Anthropic Console로 로그인할 수 있습니다 | `claude auth login --console` |

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

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

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

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

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

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

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

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

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

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

44| `claude remote-control` | Claude.ai 또는 Claude 앱에서 Claude Code를 제어하기 위한 [Remote Control](/docs/ko/remote-control) 서버를 시작합니다. 서버 모드에서 실행됩니다(로컬 대화형 세션 없음). [서버 모드 플래그](/docs/ko/remote-control#start-a-remote-control-session) 참조. 서버를 중지한 후 이를 제공하던 세션을 다시 가져올 수 있습니다. [서버 중지 후 세션 재개](/docs/ko/remote-control#resume-sessions-after-stopping-the-server) 참조 | `claude remote-control --name "My Project"` |44| `claude remote-control` | Claude.ai 또는 Claude 앱에서 Claude Code를 제어하기 위한 [Remote Control](/docs/ko/remote-control) 서버를 시작합니다. 서버 모드에서 실행됩니다(로컬 대화형 세션 없음). [서버 모드 플래그](/docs/ko/remote-control#start-a-remote-control-session) 참조. 서버를 중지한 후 이를 제공하던 세션을 다시 가져올 수 있습니다. [서버 중지 후 세션 재개](/docs/ko/remote-control#resume-sessions-after-stopping-the-server) 참조 | `claude remote-control --name "My Project"` |

45| `claude respawn <id>` | 대화를 유지하면서 실행 중이거나 중지된 [백그라운드 세션](/docs/ko/agent-view#manage-sessions-from-the-shell)을 다시 시작합니다. `--all`을 사용하여 모든 실행 중인 세션을 다시 시작합니다(예: 업데이트된 Claude Code 바이너리를 선택하기 위해) | `claude respawn 7c5dcf5d` |45| `claude respawn <id>` | 대화를 유지하면서 실행 중이거나 중지된 [백그라운드 세션](/docs/ko/agent-view#manage-sessions-from-the-shell)을 다시 시작합니다. `--all`을 사용하여 모든 실행 중인 세션을 다시 시작합니다(예: 업데이트된 Claude Code 바이너리를 선택하기 위해) | `claude respawn 7c5dcf5d` |

46| `claude rm <id>` | [백그라운드 세션](/docs/ko/agent-view#manage-sessions-from-the-shell)을 목록에서 제거합니다. 제거가 [세션의 worktree를 통해 거부](/docs/ko/agent-view#what-deleting-a-session-removes)되고 두 번째 `claude rm`이 이를 해결할 수 있을 때, 거부는 전달할 정확한 플래그와 값을 인쇄합니다: `--discard-unpushed <commit>@<worktree-id>`는 푸시되지 않은 커밋이 있는 worktree를 해당 커밋과 함께 삭제하고, `--force-remove-worktree <worktree-id>`는 git 또는 `WorktreeRemove` 훅이 제거할 수 없는 worktree 디렉토리를 삭제합니다. `--discard-unpushed`는 Claude Code v2.1.260 이상이 필요하고, `--force-remove-worktree`는 v2.1.268 이상이 필요합니다. 대화 기록은 로컬 머신에 남아 있으며 `claude --resume`을 통해 사용할 수 있습니다 | `claude rm 7c5dcf5d` |46| `claude rm <id>` | [백그라운드 세션](/docs/ko/agent-view#manage-sessions-from-the-shell)을 목록에서 제거합니다. 제거가 [세션의 worktree를 통해 거부](/docs/ko/agent-view#what-deleting-a-session-removes)되고 두 번째 `claude rm`이 이를 해결할 수 있을 때, 거부는 전달할 정확한 플래그와 값을 인쇄합니다: `--discard-unpushed <commit>@<worktree-id>`는 푸시되지 않은 커밋이 있는 worktree를 해당 커밋과 함께 삭제하고, `--force-remove-worktree <worktree-id>`는 git 또는 `WorktreeRemove` 훅이 제거할 수 없는 worktree 디렉토리를 삭제합니다. `--discard-unpushed`는 Claude Code v2.1.260 이상이 필요하고, `--force-remove-worktree`는 v2.1.268 이상이 필요합니다. 대화 트랜스크립트는 로컬 머신에 남아 있으며 `claude --resume`을 통해 사용할 수 있습니다 | `claude rm 7c5dcf5d` |

47| `claude self-hosted-runner` | 이 머신 또는 컨테이너를 [자체 호스팅 환경](/docs/ko/self-hosted-environments)에 등록하고 인프라에서 Claude Code 클라우드 세션을 호스팅하는 러너 프로세스를 시작합니다. 안내식 운영자 연습을 위해 `claude self-hosted-runner setup`을 실행하고, 배포된 러너를 [진단](/docs/ko/self-hosted-environments-deploy#troubleshooting)하기 위해 `claude self-hosted-runner doctor`를 실행하고, [온디맨드 러너](/docs/ko/self-hosted-environments-configuration#on-demand-runners)를 생성하기 위해 `claude self-hosted-runner orchestrator`를 실행합니다. Claude Code v2.1.224 이상이 필요합니다 | `claude self-hosted-runner setup` |47| `claude self-hosted-runner` | 이 머신 또는 컨테이너를 [자체 호스팅 환경](/docs/ko/self-hosted-environments)에 등록하고 인프라에서 Claude Code 클라우드 세션을 호스팅하는 러너 프로세스를 시작합니다. 안내식 운영자 연습을 위해 `claude self-hosted-runner setup`을 실행하고, 배포된 러너를 [진단](/docs/ko/self-hosted-environments-deploy#troubleshooting)하기 위해 `claude self-hosted-runner doctor`를 실행하고, [온디맨드 러너](/docs/ko/self-hosted-environments-configuration#on-demand-runners)를 생성하기 위해 `claude self-hosted-runner orchestrator`를 실행합니다. Claude Code v2.1.224 이상이 필요합니다 | `claude self-hosted-runner setup` |

48| `claude setup-token` | CI 및 스크립트를 위한 장기 OAuth 토큰을 생성합니다. 토큰을 저장하지 않고 터미널에 인쇄합니다. Claude 구독이 필요합니다. [장기 토큰 생성](/docs/ko/authentication#generate-a-long-lived-token) 참조 | `claude setup-token` |48| `claude setup-token` | CI 및 스크립트를 위한 장기 OAuth 토큰을 생성합니다. 토큰을 저장하지 않고 터미널에 인쇄합니다. Claude 구독이 필요합니다. [장기 토큰 생성](/docs/ko/authentication#generate-a-long-lived-token) 참조 | `claude setup-token` |

50| `claude ultrareview [target]` | [ultrareview](/docs/ko/ultrareview#run-ultrareview-non-interactively)를 비대화형으로 실행합니다. 결과를 stdout으로 인쇄하고 성공 시 0으로 종료되거나 실패 시 1로 종료됩니다. 원본 페이로드는 `--json`을 사용하고 45분 기본값을 재정의하려면 `--timeout <minutes>`를 사용합니다. `github.com` 풀 요청 대상에서 `--post`를 사용하여 완료된 결과를 GitHub 계정에서 PR에 일반 댓글로 게시합니다. `--no-post`가 기본값입니다. `--post` 및 `--no-post`는 Claude Code v2.1.227 이상이 필요합니다. [풀 요청에 결과 게시](/docs/ko/ultrareview#post-findings-to-the-pull-request) 참조 | `claude ultrareview 1234 --json` |50| `claude ultrareview [target]` | [ultrareview](/docs/ko/ultrareview#run-ultrareview-non-interactively)를 비대화형으로 실행합니다. 결과를 stdout으로 인쇄하고 성공 시 0으로 종료되거나 실패 시 1로 종료됩니다. 원본 페이로드는 `--json`을 사용하고 45분 기본값을 재정의하려면 `--timeout <minutes>`를 사용합니다. `github.com` 풀 리퀘스트 대상에서 `--post`를 사용하여 완료된 결과를 GitHub 계정에서 PR에 일반 댓글로 게시합니다. `--no-post`가 기본값입니다. `--post` 및 `--no-post`는 Claude Code v2.1.227 이상이 필요합니다. [풀 리퀘스트에 결과 게시](/docs/ko/ultrareview#post-findings-to-the-pull-request) 참조 | `claude ultrareview 1234 --json` |

51 51

52하위 명령어를 잘못 입력하면 Claude Code는 가장 가까운 일치를 제안하고 세션을 시작하지 않고 종료합니다. 예를 들어, `claude udpate`는 `Did you mean claude update?`를 인쇄합니다.52하위 명령을 잘못 입력하면 Claude Code는 가장 가까운 일치를 제안하고 세션을 시작하지 않고 종료합니다. 예를 들어, `claude udpate`는 `Did you mean claude update?`를 인쇄합니다.

53 53

54v2.1.199부터 `claude --dangerously-skip-permissions daemon <subcommand>`는 `daemon` 하위 명령어를 실행합니다. 이전 버전에서는 `daemon <subcommand>`를 새 대화형 세션의 프롬프트로 처리했으므로 플래그가 먼저 올 때 하위 명령어가 실행되지 않았습니다. 이는 `claude`가 플래그를 포함하도록 별칭이 지정된 경우 일반적인 설정입니다. 선행 `--dangerously-skip-permissions` 또는 `--allow-dangerously-skip-permissions`만 이 방식으로 `daemon`으로 라우팅됩니다. 다른 선행 플래그는 여전히 대화형 세션을 시작합니다.54v2.1.199부터 `claude --dangerously-skip-permissions daemon <subcommand>`는 `daemon` 하위 명령을 실행합니다. 이전 버전에서는 `daemon <subcommand>`를 새 대화형 세션의 프롬프트로 처리했으므로 플래그가 먼저 올 때 하위 명령이 실행되지 않았습니다. 이는 `claude`가 플래그를 포함하도록 별칭이 지정된 경우 일반적인 설정입니다. 선행 `--dangerously-skip-permissions` 또는 `--allow-dangerously-skip-permissions`만 이 방식으로 `daemon`으로 라우팅됩니다. 다른 선행 플래그는 여전히 대화형 세션을 시작합니다.

55 55

56<h2 id="cli-flags">56<h2 id="cli-flags">

57 CLI 플래그57 CLI 플래그

157| `--system-prompt-snapshot` | `off`를 사용하면 모든 요청에서 프롬프트를 다시 빌드합니다. `on`(기본값)을 사용하면 [기록이 적용되는 경우](#system-prompt-flags-in-resumed-conversations) 기록된 프롬프트를 재사용합니다 | `claude --append-system-prompt "Draft rules" --system-prompt-snapshot off` |157| `--system-prompt-snapshot` | `off`를 사용하면 모든 요청에서 프롬프트를 다시 빌드합니다. `on`(기본값)을 사용하면 [기록이 적용되는 경우](#system-prompt-flags-in-resumed-conversations) 기록된 프롬프트를 재사용합니다 | `claude --append-system-prompt "Draft rules" --system-prompt-snapshot off` |

158 158

159`--system-prompt` 및 `--system-prompt-file`은 상호 배타적입니다. 추가 플래그는 대체 플래그 중 하나와 결합할 수 있습니다.159이러한 플래그는 결합할 수 있습니다. 기본 프롬프트를 바꾸면서도 자체 텍스트를 추가하려면 `--append-system-prompt` 또는 `--append-system-prompt-file`을 `--system-prompt` 또는 `--system-prompt-file`과 함께 전달합니다. Claude Code v2.1.283 이상에서는 `--append-system-prompt`와 `--append-system-prompt-file`처럼 플래그를 자체 파일 형식과 함께 전달할 수도 있으며, Claude Code는 둘 다 사용합니다.

160

161예를 들어, 셸에서 다음을 실행하면 파일의 스타일 가이드와 추가 지침 하나를 모두 추가합니다:

162

163```bash theme={null}

164claude -p --append-system-prompt-file ./style.md --append-system-prompt "Always reply in French" "Summarize README.md"

165```

166

167Claude는 기본 시스템 프롬프트 뒤에 `style.md`의 내용, 빈 줄, 그리고 `Always reply in French`가 이어진 프롬프트를 받습니다. `--append-system-prompt`를 `--append-system-prompt-file`보다 먼저 전달하더라도 파일 내용이 먼저 옵니다.

160 168

161대체 텍스트가 모든 실행에서 동일한 지침과 실행마다 변경되는 컨텍스트를 결합할 때 지침과 컨텍스트 사이에만 `__SYSTEM_PROMPT_DYNAMIC_BOUNDARY__`를 포함하는 줄을 추가합니다. Claude Code는 첫 번째 이러한 줄에서 프롬프트를 분할하고 해당 줄을 제거하므로 위의 부분은 캐시된 상태로 유지되고 아래의 부분은 변경됩니다. Claude Code v2.1.275 이상이 필요합니다. [사용자 정의 프롬프트의 정적 부분 캐시](/docs/ko/agent-sdk/modifying-system-prompts#cache-the-static-part-of-a-custom-prompt)는 분할이 적용되는 구성을 나열합니다.169대체 텍스트가 모든 실행에서 동일한 지침과 실행마다 변경되는 컨텍스트를 결합할 때 지침과 컨텍스트 사이에만 `__SYSTEM_PROMPT_DYNAMIC_BOUNDARY__`를 포함하는 줄을 추가합니다. Claude Code는 첫 번째 이러한 줄에서 프롬프트를 분할하고 해당 줄을 제거하므로 위의 부분은 캐시된 상태로 유지되고 아래의 부분은 변경됩니다. Claude Code v2.1.275 이상이 필요합니다. [사용자 정의 프롬프트의 정적 부분 캐시](/docs/ko/agent-sdk/modifying-system-prompts#cache-the-static-part-of-a-custom-prompt)는 분할이 적용되는 구성을 나열합니다.

162 170

commands.md +1 −1

Details

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

100| `/heapdump` | JavaScript 힙 스냅샷 및 메모리 분석을 `~/Desktop` 또는 Desktop 폴더가 없는 Linux의 홈 디렉토리에 작성하여 높은 메모리 사용량을 진단합니다. 메모리 문제를 보고할 때 `-diagnostics.json` 파일만 첨부합니다. `.heapsnapshot`에는 전체 대화 및 자격 증명이 포함되어 있으므로 공유하지 마십시오. [출력으로 수행할 작업](/docs/ko/troubleshooting#high-cpu-or-memory-usage)을 참조하십시오. |100| `/heapdump` | JavaScript 힙 스냅샷 및 메모리 분석을 `~/Desktop` 또는 Desktop 폴더가 없는 Linux의 홈 디렉토리에 작성하여 높은 메모리 사용량을 진단합니다. 메모리 문제를 보고할 때 `-diagnostics.json` 파일만 첨부합니다. `.heapsnapshot`에는 전체 대화 및 자격 증명이 포함되어 있으므로 공유하지 마십시오. [출력으로 수행할 작업](/docs/ko/troubleshooting#high-cpu-or-memory-usage)을 참조하십시오. |

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

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

105| `/init` | `CLAUDE.md` 가이드로 프로젝트를 초기화합니다. `CLAUDE_CODE_NEW_INIT=1`을 설정하여 스킬, 훅 및 개인 메모리 파일을 안내하는 대화형 흐름을 얻습니다. `/init`이 OpenAI Codex 또는 Google Gemini CLI 구성을 찾으면 `/import`로 이를 수행하도록 제안합니다. |105| `/init` | `CLAUDE.md` 가이드로 프로젝트를 초기화합니다. `CLAUDE_CODE_NEW_INIT=1`을 설정하여 스킬, 훅 및 개인 메모리 파일을 안내하는 대화형 흐름을 얻습니다. `/init`이 OpenAI Codex 또는 Google Gemini CLI 구성을 찾으면 `/import`로 이를 수행하도록 제안합니다. |

debug-your-config.md +4 −2

Details

65 훅 확인65 훅 확인

66</h2>66</h2>

67 67

68`/hooks`를 실행하여 현재 세션에 등록된 모든 훅을 이벤트별로 그룹화하여 나열합니다. 정의한 훅이 나타나지 않으면 읽혀지지 않는 것입니다: 훅은 독립 실행형 파일이 아니라 설정 파일의 `"hooks"` 키 아래에 있습니다.68`/hooks`를 실행하여 현재 세션에 등록된 모든 훅을 이벤트별로 그룹화하여 나열합니다. 정의한 훅이 나타나지 않으면 Claude Code가 해당 훅을 로드하지 않은 것입니다. 다음 원인을 확인하십시오:

70* 훅이 독립 실행형 파일에 정의되어 있습니다. 훅은 [설정 파일](/docs/ko/settings#settings-files)의 `"hooks"` 키 아래에 있어야 합니다.

71* `matcher` 값이 단일 문자열이 아닌 배열입니다. Claude Code는 대화형 세션을 시작할 때와 `claude doctor`에서 해당 항목을 잘못된 설정으로 나열합니다. 배열이 `PreToolUse` 또는 `PermissionRequest` 아래에 있으면 해당 파일의 다른 훅도 모두 로드되지 않습니다.

69 72

70훅이 나타나지만 실행되지 않으면, 매처가 보통 원인입니다. 다음 실수를 확인하십시오:73훅이 나타나지만 실행되지 않으면, 매처가 보통 원인입니다. 다음 실수를 확인하십시오:

71 74

72* `matcher` 필드는 여러 도구 이름을 일치시키기 위해 `|`를 사용하는 단일 문자열입니다(예: `"Edit|Write"`). `,` 구분 기호는 동등하므로 `"Edit,Write"`는 동일한 도구를 일치시킵니다. v2.1.191 이전에는 쉼표가 정규식 평가로 넘어가고 매처가 일치하지 않으므로, v2.1.191이 아직 아니면 `|`를 사용하십시오.75* `matcher` 필드는 여러 도구 이름을 일치시키기 위해 `|`를 사용하는 단일 문자열입니다(예: `"Edit|Write"`). `,` 구분 기호는 동등하므로 `"Edit,Write"`는 동일한 도구를 일치시킵니다. v2.1.191 이전에는 쉼표가 정규식 평가로 넘어가고 매처가 일치하지 않으므로, v2.1.191이 아직 아니면 `|`를 사용하십시오.

73* 잘못된 도구 이름은 아무것도 일치하지 않는 매처를 생성하므로 훅이 자동으로 실패합니다.76* 잘못된 도구 이름은 아무것도 일치하지 않는 매처를 생성하므로 훅이 자동으로 실패합니다.

74* 배열 값은 스키마 오류입니다: Claude Code는 설정 오류 알림을 표시하고 전체 사용자, 프로젝트 또는 로컬 설정 파일을 거부하며, `claude doctor`는 검증 실패를 보고하고, 해당 파일의 훅이 `/hooks`에 나타나지 않습니다. [관리되는 설정](/docs/ko/managed-settings)에서는 Claude Code가 파일을 포함하는 전체 `hooks` 키를 삭제하므로 해당 파일의 훅이 적용되지 않습니다. 파일의 다른 설정은 계속 적용되며, `claude doctor`는 삭제된 키를 나열합니다.

75 77

76`settings.json`을 편집하면 파일 안정성 지연 후 실행 중인 세션에서 변경 사항이 적용됩니다. 세션이 시작된 후 파일이나 프로젝트의 `.claude/` 폴더를 생성한 경우에도 다시 시작할 필요가 없습니다. v2.1.257 이전에는 Claude Code가 세션이 시작된 후 생성된 `.claude/` 폴더의 편집을 감지하지 못했습니다.78`settings.json`을 편집하면 파일 안정성 지연 후 실행 중인 세션에서 변경 사항이 적용됩니다. 세션이 시작된 후 파일이나 프로젝트의 `.claude/` 폴더를 생성한 경우에도 다시 시작할 필요가 없습니다. v2.1.257 이전에는 Claude Code가 세션이 시작된 후 생성된 `.claude/` 폴더의 편집을 감지하지 못했습니다.

77 79

env-vars.md +374 −370

Details

56 </Tab>56 </Tab>

57</Tabs>57</Tabs>

58 58

~~59할당 줄은 성공 시 아무것도 출력하지 않으므로, `claude`를 실행하기 전에 같은 셸에서 변수를 출력하여 설정되었는지 확인합니다:~~59할당 줄은 성공 시 아무것도 출력하지 않습니다. 변수가 설정되었는지 확인하려면 같은 셸에서 변수를 출력합니다:

60 60

61<Tabs>61<Tabs>

62 <Tab title="macOS, Linux, WSL">62 <Tab title="macOS, Linux, WSL">

103| 관리되는 설정 | 관리자가 배포한 조직의 모든 사람 |103| 관리형 설정 | 관리자가 배포한 조직의 모든 사람 |

104 104

105각 파일이 있는 위치는 [설정 파일](/docs/ko/settings#where-settings-live)을 참조하고, 둘 이상이 같은 변수를 설정할 때 결합되는 방식은 [설정 우선순위](/docs/ko/settings#settings-precedence)를 참조합니다.105각 파일이 있는 위치는 [설정 파일](/docs/ko/settings#where-settings-live)을 참조하고, 둘 이상이 같은 변수를 설정할 때 결합되는 방식은 [설정 우선순위](/docs/ko/settings#settings-precedence)를 참조합니다.

106 106

124 변수124 변수

125</h2>125</h2>

126 126

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

128 128

129<Note>129<Note>

130 동작을 켜거나 끄는 변수의 경우, `1` 또는 `true`를 설정하여 켜고 `0` 또는 `false`를 설정하여 끕니다. 대소문자는 상관없습니다.130 동작을 켜거나 끄는 변수의 경우, 대소문자에 관계없이 `1`, `true`, `yes`, `on`으로 설정하면 켜지고 `0`, `false`, `no`, `off`로 설정하면 꺼집니다.

131 131

132 일부 변수는 설정 여부만 읽으므로, `0`을 포함한 모든 비어있지 않은 값이 동작을 켜고, 변수를 설정 해제하거나 빈 값으로 설정하여 동작을 끕니다. 이러한 변수들은 다음과 같습니다:132 일부 변수는 설정 여부만 확인하므로 `0`을 포함하여 비어 있지 않은 모든 값이 동작을 켜며, 동작을 끄려면 변수를 설정 해제하거나 빈 값으로 설정해야 합니다. 다음 변수가 이렇게 동작합니다:

133 133

134 * `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC`134 * `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC`

135 * `DISABLE_TELEMETRY`135 * `DISABLE_TELEMETRY`

138 * `FALLBACK_FOR_ALL_PRIMARY_MODELS`138 * `FALLBACK_FOR_ALL_PRIMARY_MODELS`

139 * `IS_DEMO`139 * `IS_DEMO`

140 140

141 다른 하나의 변수는 자체 규칙을 가집니다: `FORCE_HYPERLINK`는 숫자를 읽으므로 `0`만 끕니다. 각 변수의 행도 자체 규칙을 명시합니다.141 또 다른 변수 하나는 고유한 규칙을 따릅니다. `FORCE_HYPERLINK`는 숫자를 읽으므로 `0`만 이 동작을 끕니다. 각 변수의 행에도 해당 변수의 규칙이 명시되어 있습니다.

142</Note>142</Note>

143 143

144| 변수 | 목적 |144| 변수 | 용도 |

145| :- | :- |145| :- | :- |

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

183| `ANTHROPIC_FOUNDRY_RESOURCE` | Microsoft Foundry 리소스 이름입니다(예: `my-resource`). `ANTHROPIC_FOUNDRY_BASE_URL`이 설정되지 않으면 필수입니다([Microsoft Foundry](/docs/ko/microsoft-foundry) 참조) |183| `ANTHROPIC_FOUNDRY_RESOURCE` | Microsoft Foundry 리소스 이름입니다(예: `my-resource`). `ANTHROPIC_FOUNDRY_BASE_URL`이 설정되지 않은 경우 필수입니다([Microsoft Foundry](/docs/ko/microsoft-foundry) 참조) |

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

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

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

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

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

191| `ANTHROPIC_WORKSPACE_ID` | [워크로드 ID 페더레이션](https://platform.claude.com/docs/en/manage-claude/workload-identity-federation)의 워크스페이스 ID입니다. 페더레이션 규칙이 둘 이상의 워크스페이스로 범위가 지정되어 있을 때 설정하여 토큰 교환이 어느 워크스페이스를 대상으로 할지 알 수 있도록 합니다 |191| `ANTHROPIC_WORKSPACE_ID` | [Workload Identity Federation](https://platform.claude.com/docs/en/manage-claude/workload-identity-federation)의 워크스페이스 ID입니다. 페더레이션 규칙의 범위가 둘 이상의 워크스페이스로 지정된 경우, 토큰 교환이 대상 워크스페이스를 알 수 있도록 이 값을 설정하세요 |

192| `API_FORCE_IDLE_TIMEOUT` | 바이트가 도착하지 않을 때 스트리밍 모델 응답을 중단하는 5분 본문 유휴 타임아웃을 재정의합니다. 느린 [게이트웨이](/docs/ko/llm-gateway) 또는 로컬 모델이 청크 사이에 5분 이상 일시 중지할 때 타임아웃을 끄려면 `0`으로 설정하거나, 모든 제공자에 대해 켜려면 `1`로 설정합니다. 설정되지 않으면, 타임아웃은 직접 Anthropic API 및 [Claude Platform on AWS](/docs/ko/claude-platform-on-aws) 이외의 제공자에서 활성화됩니다. [스트림 감시견](/docs/ko/network-config#streaming-idle-watchdogs)은 독립적으로 실행되며 여기서 `0`을 설정해도 긴 침묵을 중단합니다 |192| `API_FORCE_IDLE_TIMEOUT` | 바이트가 도착하지 않을 때 스트리밍 모델 응답을 중단하는 5분 본문 유휴 타임아웃을 재정의합니다. 예를 들어 느린 [게이트웨이](/docs/ko/llm-gateway)나 로컬 모델이 청크 사이에 5분 넘게 멈추는 경우 `0`으로 설정하여 타임아웃을 끄거나, `1`로 설정하여 모든 제공업체에서 켜 둘 수 있습니다. 설정하지 않으면 Anthropic API 직접 연결, [Claude Platform on AWS](/docs/ko/claude-platform-on-aws), `CLAUDE_ENABLE_BYTE_WATCHDOG_BEDROCK=1`이 설정된 Amazon Bedrock 이외의 제공업체에서 타임아웃이 활성화됩니다. [스트림 워치독](/docs/ko/network-config#streaming-idle-watchdogs)은 이와 독립적으로 실행되며, 여기서 `0`을 설정하더라도 오래 지속되는 무응답 상태를 중단합니다 |

193| `API_TIMEOUT_MS` | API 요청의 타임아웃(밀리초 단위)(기본값: 600000, 또는 10분; 최대값: 2147483647). 느린 네트워크에서 요청이 타임아웃되거나 프록시를 통해 라우팅할 때 이를 증가시킵니다. 최대값 이상의 값은 기본 타이머를 오버플로우하여 요청이 즉시 실패하게 합니다 |193| `API_TIMEOUT_MS` | API 요청의 타임아웃(밀리초)입니다(기본값: 600000, 즉 10분, 최댓값: 2147483647). 느린 네트워크에서 요청이 시간 초과되거나 프록시를 통해 라우팅할 때 이 값을 늘리세요. 최댓값을 초과하는 값은 기본 타이머를 오버플로시켜 요청이 즉시 실패하게 합니다 |

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

195| `BASH_DEFAULT_TIMEOUT_MS` | 장시간 실행되는 bash 명령의 기본 타임아웃입니다(기본값: 120000, 또는 2분) |195| `BASH_DEFAULT_TIMEOUT_MS` | 포그라운드 Bash 또는 PowerShell 도구 명령의 기본 타임아웃(밀리초)입니다(기본값: 120000, 즉 2분). 30분보다 긴 기본값은 [백그라운드 명령의 시간 제한](/docs/ko/tools-reference#time-limit-for-background-commands) 기본값으로도 사용됩니다. 백그라운드 시간 제한에는 Claude Code v2.1.285 이상이 필요합니다 |

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

197| `BASH_MAX_TIMEOUT_MS` | 모델이 장시간 실행되는 bash 명령에 대해 설정할 수 있는 최대 타임아웃입니다(기본값: 600000, 또는 10분). 유효한 상한은 이것과 `BASH_DEFAULT_TIMEOUT_MS` 중 더 큰 값입니다 |197| `BASH_MAX_TIMEOUT_MS` | 모델이 포그라운드 Bash 또는 PowerShell 도구 명령에 설정할 수 있는 최대 타임아웃(밀리초)입니다(기본값: 600000, 즉 10분). 실제 상한은 이 값과 `BASH_DEFAULT_TIMEOUT_MS` 중 더 큰 값입니다. 2시간보다 긴 실제 상한은 [백그라운드 명령의 시간 제한](/docs/ko/tools-reference#time-limit-for-background-commands) 최댓값으로도 사용됩니다. 백그라운드 시간 제한에는 Claude Code v2.1.285 이상이 필요합니다 |

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

199| `CCR_FORCE_BUNDLE` | [`claude --cloud`](/docs/ko/claude-code-on-the-web#send-local-repositories-without-github)가 원격에서 복제하는 대신 로컬 리포지토리를 번들로 묶고 업로드하도록 강제하려면 `1`로 설정하세요 |199| `CCR_FORCE_BUNDLE` | `1`로 설정하면 [`claude --cloud`](/docs/ko/claude-code-on-the-web#send-local-repositories-without-github)가 원격에서 클론하는 대신 로컬 저장소를 번들링하여 업로드하도록 강제합니다 |

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

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

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

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

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

205| `CLAUDE_ASYNC_AGENT_STALL_TIMEOUT_MS` | 서브에이전트의 정체 타임아웃(밀리초 단위)입니다. 기본값 `600000`(10분); `CLAUDE_STREAM_IDLE_TIMEOUT_MS`를 스트림 감시견이 켜져 있는 동안 올리면, 기본값이 함께 올라갑니다. [느리거나 정체된 API 응답 처리](/docs/ko/agent-sdk/typescript#handle-slow-or-stalled-api-responses)에서 설명합니다. 타이머는 각 스트리밍 진행 이벤트에서 재설정됩니다. 창 내에 진행이 도착하지 않으면, Claude Code는 서브에이전트를 중단하고 정체를 부모에 보고합니다 |205| `CLAUDE_ASYNC_AGENT_STALL_TIMEOUT_MS` | 서브에이전트의 정체 타임아웃(밀리초)입니다. 기본값은 `600000`(10분)이며, 스트림 워치독이 켜져 있는 상태에서 `CLAUDE_STREAM_IDLE_TIMEOUT_MS`를 늘리면 [느리거나 정체된 API 응답 처리](/docs/ko/agent-sdk/typescript#handle-slow-or-stalled-api-responses)에 설명된 대로 기본값도 함께 증가합니다. 타이머는 스트리밍 진행 이벤트마다 재설정되며, 해당 시간 내에 진행 이벤트가 도착하지 않으면 Claude Code는 서브에이전트를 중단하고 정체를 상위 에이전트에 보고합니다 |

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

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

208| `CLAUDE_AX_PREPARK_MS` | [화면 판독기 모드](/docs/ko/accessibility#what-your-screen-reader-hears)에서, Claude Code가 커서를 줄의 시작에 두고 새로운 또는 변경된 줄을 쓰기 전에 대기하는 밀리초 수입니다. 기본값 `50`. 즉시 쓰려면 `0`으로 설정하세요. Claude Code는 대기를 `5000`으로 제한합니다. Claude Code v2.1.233 이상이 필요합니다 |208| `CLAUDE_AX_PREPARK_MS` | [스크린 리더 모드](/docs/ko/accessibility)에서 Claude Code가 새 줄이나 변경된 줄을 쓰기 전에 대기하는 시간(밀리초)입니다. 기본값은 `0`이므로 Claude Code는 대기하지 않습니다. v2.1.287 이전에는 기본값이 `50`이었습니다. Claude Code는 대기 시간을 최대 `5000`으로 제한합니다. Claude Code v2.1.233 이상이 필요합니다 |

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

210| `CLAUDE_AX_STARTUP_QUIET_MS` | [화면 판독기 모드](/docs/ko/accessibility)에서, Claude Code가 시작 확인 줄 이후 첫 번째 인터페이스 렌더링을 유지하는 밀리초 수이므로 화면 판독기가 새 출력이 중단되기 전에 줄을 완전히 말할 수 있습니다. 기본값 `3000`. 즉시 렌더링하려면 `0`으로 설정하세요. Claude Code는 보류를 `600000`(10분)으로 제한합니다. 첫 번째 키 입력이 보류를 조기에 종료합니다. Claude Code v2.1.217 이상이 필요합니다 |210| `CLAUDE_AX_STARTUP_QUIET_MS` | [스크린 리더 모드](/docs/ko/accessibility)에서 시작 확인 줄 이후 Claude Code가 첫 인터페이스 렌더링을 보류하는 시간(밀리초)으로, 새 출력이 끼어들기 전에 스크린 리더가 해당 줄을 끝까지 읽을 수 있게 합니다. 기본값은 `3000`입니다. 즉시 렌더링하려면 `0`으로 설정하세요. Claude Code는 보류 시간을 최대 `600000`(10분)으로 제한합니다. 첫 번째 키 입력 시 보류가 일찍 끝납니다. Claude Code v2.1.217 이상이 필요합니다 |

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

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

214| `CLAUDE_CODE_ACCESSIBILITY` | 기본 터미널 커서를 표시하고 반전된 텍스트 커서 표시기를 비활성화하려면 `1`로 설정하세요. macOS Zoom 같은 화면 확대기가 커서 위치를 추적할 수 있습니다 |214| `CLAUDE_CODE_ACCESSIBILITY` | `1`로 설정하면 기본 터미널 커서를 계속 표시하고 반전 텍스트 커서 표시기를 비활성화합니다. macOS Zoom과 같은 화면 돋보기가 커서 위치를 추적할 수 있게 합니다 |

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

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

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

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

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

220| `CLAUDE_CODE_ARTIFACT_COMMENTS` | Claude가 [아티팩트의 댓글](/docs/ko/artifacts#collect-comments-on-an-artifact)을 읽고 회신하지 않도록 하려면 `0`으로 설정하세요. `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC`이 [아티팩트를 꺼](/docs/ko/artifacts#availability)도록 설정되었을 때는 효과가 없습니다. Claude Code v2.1.221 이상이 필요합니다 |220| `CLAUDE_CODE_ARTIFACT_COMMENTS` | `0`으로 설정하면 Claude가 [아티팩트의 댓글](/docs/ko/artifacts#collect-comments-on-an-artifact)을 읽고 답하지 않습니다. `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC`이 [아티팩트를 끈](/docs/ko/artifacts#availability) 경우에는 효과가 없습니다. Claude Code v2.1.221 이상이 필요합니다 |

221| `CLAUDE_CODE_ARTIFACT_COMMENTS_AUTOREACT` | Claude가 [자신에게 전송된 댓글에 자동으로 회신](/docs/ko/artifacts#let-claude-reply-to-comments-on-its-own)하지 않도록 하려면 `0`으로 설정하세요. Claude Code v2.1.228 이상이 필요합니다 |221| `CLAUDE_CODE_ARTIFACT_COMMENTS_AUTOREACT` | `0`으로 설정하면 Claude가 [자신에게 보내진 댓글에 스스로 답하지](/docs/ko/artifacts#let-claude-reply-to-comments-on-its-own) 않습니다. Claude Code v2.1.228 이상이 필요합니다 |

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

223| `CLAUDE_CODE_AUTO_BACKGROUND_WORKER_CHECKIN_SECONDS` | `CLAUDE_AUTO_BACKGROUND_TASKS`가 활성화되면, Claude가 여전히 실행 중인 [백그라운드 서브에이전트](/docs/ko/sub-agents#run-subagents-in-foreground-or-background)를 확인하도록 상기시키는 간격(초 단위)입니다. `1`에서 `86400`까지의 일반 정수만 허용합니다. 다른 값이나 표기법은 설정 해제로 읽힙니다. 설정되지 않으면 체크인 알림이 없습니다. Claude Code v2.1.248 이상이 필요합니다 |223| `CLAUDE_CODE_AUTO_BACKGROUND_WORKER_CHECKIN_SECONDS` | `CLAUDE_AUTO_BACKGROUND_TASKS`가 활성화된 경우, 아직 실행 중인 [백그라운드 서브에이전트](/docs/ko/sub-agents#run-subagents-in-foreground-or-background)를 확인하도록 Claude에게 보내는 리마인더 사이의 간격(초)입니다. `1`부터 `86400`까지의 일반 정수만 허용하며, 다른 값이나 표기는 설정되지 않은 것으로 읽힙니다. 설정하지 않으면 확인 리마인더가 없습니다. Claude Code v2.1.248 이상이 필요합니다 |

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

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

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

227| `CLAUDE_CODE_AWS_CHAIN_RESOLVE_TIMEOUT_MS` | Claude Code가 AWS 기본 자격 증명 제공자 체인이 자격 증명을 생성할 때까지 대기하는 시간(밀리초 단위)입니다. 그 후 요청이 [`AWS default-chain credential resolve timed out`](/docs/ko/errors#aws-default-chain-credential-resolve-timed-out)으로 실패합니다(기본값: `60000`). `aws-vault` 같은 래퍼를 통한 MFA를 사용한 브라우저 기반 SSO 로그인 같이 체인의 단계가 합법적으로 더 오래 필요할 때 이를 올리세요. [Amazon Bedrock](/docs/ko/amazon-bedrock#credential-caching-and-resolution-timeout), [Claude Platform on AWS](/docs/ko/claude-platform-on-aws), [Mantle 엔드포인트](/docs/ko/amazon-bedrock#use-the-mantle-endpoint)에서 Claude Code가 기본 체인으로 서명하는 모든 곳에 적용됩니다. Claude Code v2.1.207 이상이 필요합니다 |227| `CLAUDE_CODE_AWS_CHAIN_RESOLVE_TIMEOUT_MS` | 요청이 [`AWS default-chain credential resolve timed out`](/docs/ko/errors#aws-default-chain-credential-resolve-timed-out) 오류로 실패하기 전에 Claude Code가 AWS 기본 자격 증명 공급자 체인이 자격 증명을 생성하기를 기다리는 시간(밀리초)입니다(기본값: `60000`). `aws-vault`와 같은 래퍼를 통한 MFA 포함 브라우저 기반 SSO 로그인처럼 체인의 단계가 실제로 더 오래 걸리는 경우 이 값을 늘리세요. Claude Code가 기본 체인으로 서명하는 모든 곳에 적용됩니다: [Amazon Bedrock](/docs/ko/amazon-bedrock#credential-caching-and-resolution-timeout), [Claude Platform on AWS](/docs/ko/claude-platform-on-aws), [Mantle 엔드포인트](/docs/ko/amazon-bedrock#use-the-mantle-endpoint). Claude Code v2.1.207 이상이 필요합니다 |

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

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

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

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

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

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

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

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

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

240| `CLAUDE_CODE_DISABLE_1M_CONTEXT` | [1M 컨텍스트 창](/docs/ko/model-config#extended-context) 지원을 비활성화하려면 `1`로 설정하세요. 설정되면, 1M 모델 변형은 모델 선택기에서 사용할 수 없으며, Claude Code는 [Sonnet 5.5](/docs/ko/model-config#sonnet-5-5-and-sonnet-5-context-window) 같은 기본 1M 창을 가진 모델과 Fable 모델을 200K 창으로 유지합니다. [확장 컨텍스트](/docs/ko/model-config#extended-context)에서 보류가 어떻게 적용되는지 참조하세요. 규정 준수 요구 사항이 있는 엔터프라이즈 환경에 유용합니다. 인식되지 않는 `[1m]` 모델 ID의 창을 수정하는 역할은 [게이트웨이 또는 사용자 정의 모델 ID의 창 수정](/docs/ko/model-config#correct-the-window-for-a-gateway-or-custom-model-id)을 참조하세요 |240| `CLAUDE_CODE_DISABLE_1M_CONTEXT` | `1`로 설정하면 [1M 컨텍스트 윈도우](/docs/ko/model-config#extended-context) 지원을 비활성화합니다. 설정하면 모델 선택기에서 1M 모델 변형을 사용할 수 없으며, Claude Code는 [Sonnet 5.5](/docs/ko/model-config#sonnet-5-5-and-sonnet-5-context-window) 및 Fable 모델처럼 기본 1M 윈도우를 가진 모델의 세션을 200K 윈도우로 제한합니다. 이 제한이 적용되는 방식은 [확장 컨텍스트](/docs/ko/model-config#extended-context)를 참조하세요. 규정 준수 요구 사항이 있는 엔터프라이즈 환경에 유용합니다. 인식되지 않는 `[1m]` 모델 ID의 윈도우를 수정하는 데 이 변수가 하는 역할은 [게이트웨이 또는 사용자 지정 모델 ID의 윈도우 수정](/docs/ko/model-config#correct-the-window-for-a-gateway-or-custom-model-id)을 참조하세요 |

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

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

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

244| `CLAUDE_CODE_DISABLE_AGENT_VIEW` | [백그라운드 에이전트 및 에이전트 보기](/docs/ko/agent-view)를 끄려면 `1`로 설정하세요: `claude agents`, `--bg`, `/background`, 및 온디맨드 감독자. [`disableAgentView`](/docs/ko/settings-reference#disableagentview) 설정과 동등합니다 |244| `CLAUDE_CODE_DISABLE_AGENT_VIEW` | `1`로 설정하면 [백그라운드 에이전트와 에이전트 뷰](/docs/ko/agent-view)(`claude agents`, `--bg`, `/background`, 온디맨드 슈퍼바이저)를 끕니다. [`disableAgentView`](/docs/ko/settings-reference#disableagentview) 설정과 동일합니다 |

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

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

248| `CLAUDE_CODE_DISABLE_AUTO_MEMORY` | [자동 메모리](/docs/ko/memory#auto-memory)를 비활성화하려면 `1`로 설정하세요. `--bare` 모드 또는 [`autoMemoryEnabled: false`](/docs/ko/settings-reference#automemoryenabled)가 그렇지 않으면 비활성화할 때에도 자동 메모리를 강제로 켜려면 `0`으로 설정하세요. 비활성화되면, Claude는 자동 메모리 파일을 생성하거나 로드하지 않습니다 |248| `CLAUDE_CODE_DISABLE_AUTH_REFRESH_LOCK` | `1`로 설정하면 Claude Code 프로세스가 다른 프로세스가 [`gcpAuthRefresh`](/docs/ko/settings-reference#gcpauthrefresh) 또는 [`awsAuthRefresh`](/docs/ko/settings-reference#awsauthrefresh) 명령을 실행하는 동안 기다리지 않고 직접 실행합니다. Claude Code v2.1.286 이상이 필요합니다 |

249| `CLAUDE_CODE_DISABLE_BACKGROUND_TASKS` | 모든 백그라운드 작업 기능을 비활성화하려면 `1`로 설정하세요. Bash 및 서브에이전트 도구의 `run_in_background` 매개변수, 자동 백그라운드 처리, Ctrl+B 단축키 포함 |249| `CLAUDE_CODE_DISABLE_AUTO_MEMORY` | `1`로 설정하면 [자동 메모리](/docs/ko/memory#auto-memory)를 비활성화합니다. `0`으로 설정하면 `--bare` 모드나 [`autoMemoryEnabled: false`](/docs/ko/settings-reference#automemoryenabled)로 인해 비활성화되는 경우에도 자동 메모리를 강제로 켭니다. 비활성화하면 Claude는 자동 메모리 파일을 생성하거나 로드하지 않습니다 |

250| `CLAUDE_CODE_DISABLE_BEDROCK_CONTENT_TYPE_DEFAULT` | Claude Code가 [Amazon Bedrock](/docs/ko/amazon-bedrock) 스트리밍 응답을 누락되거나 빈 `Content-Type` 헤더가 있는 Amazon Bedrock의 이진 이벤트 스트림으로 처리하지 않도록 하려면 `1`로 설정하세요. 기본적으로 Claude Code는 게이트웨이가 그렇지 않으면 수정되지 않은 응답에서 헤더를 삭제했다고 가정하므로 본문을 디코드하고 스트리밍이 계속 작동합니다. 게이트웨이가 스트림을 서버 전송 이벤트로 다시 내보내는 경우에만 설정하세요. Claude Code는 헤더 없는 본문을 서버 전송 이벤트로 읽습니다. Claude Code v2.1.239 이상이 필요합니다 |250| `CLAUDE_CODE_DISABLE_BACKGROUND_TASKS` | `1`로 설정하면 Bash 및 서브에이전트 도구의 `run_in_background` 매개변수, 자동 백그라운드 전환, Ctrl+B 단축키를 포함한 모든 백그라운드 작업 기능을 비활성화합니다 |

251| `CLAUDE_CODE_DISABLE_BEDROCK_CONTENT_TYPE_GUARD` | [Amazon Bedrock](/docs/ko/amazon-bedrock) 스트리밍 응답이 `application/vnd.amazon.eventstream` 콘텐츠 유형을 전달하는지 확인하는 것을 건너뛰려면 `1`로 설정하세요. 이 변수 없이, 응답이 다른 콘텐츠 유형을 전달하면, Claude Code는 해당 유형을 명명하는 오류로 요청을 실패합니다. 이는 [게이트웨이 또는 프록시가 응답을 변환](/docs/ko/amazon-bedrock#streaming-errors-behind-a-gateway-or-proxy)하고 있음을 의미합니다. 이 변수를 설정하는 대신 `Content-Type` 헤더와 본문을 수정되지 않은 상태로 전달하도록 게이트웨이를 구성하세요. Claude Code v2.1.208 이상이 필요합니다 |251| `CLAUDE_CODE_DISABLE_BEDROCK_CONTENT_TYPE_DEFAULT` | `1`로 설정하면 Claude Code가 `Content-Type` 헤더가 없거나 비어 있는 [Amazon Bedrock](/docs/ko/amazon-bedrock) 스트리밍 응답을 Amazon Bedrock의 바이너리 이벤트 스트림으로 취급하지 않습니다. 기본적으로 Claude Code는 게이트웨이가 나머지는 수정되지 않은 응답에서 헤더만 삭제했다고 가정하므로, 본문을 디코딩하여 스트리밍이 계속 작동합니다. 스트림을 서버 전송 이벤트로도 다시 내보내는 게이트웨이에 대해서만 이 변수를 설정하세요. 그러면 Claude Code는 헤더가 없는 본문을 대신 서버 전송 이벤트로 읽습니다. Claude Code v2.1.239 이상이 필요합니다 |

252| `CLAUDE_CODE_DISABLE_BG_EXIT_HANDOFF` | [백그라운드 세션](/docs/ko/agent-view)의 실행 중인 백그라운드 셸 명령, 동적 워크플로우, 및 v2.1.198부터 백그라운드 서브에이전트가 [감독자](/docs/ko/agent-view#the-supervisor-process)가 해당 세션의 프로세스를 중지, 재시작 또는 업데이트할 때 다음 프로세스로 전달되지 않도록 하려면 `1`로 설정하세요. 이 전달에만 영향을 미칩니다: `←`를 누르거나 [`/background`](/docs/ko/agent-view#from-inside-a-session)로 세션을 백그라운드 처리하면 진행 중인 작업이 계속 전달되고, `CLAUDE_DISABLE_ADOPT`는 둘 다 끕니다. Claude Code v2.1.196 이상이 필요합니다 |252| `CLAUDE_CODE_DISABLE_BEDROCK_CONTENT_TYPE_GUARD` | `1`로 설정하면 [Amazon Bedrock](/docs/ko/amazon-bedrock) 스트리밍 응답이 `application/vnd.amazon.eventstream` content-type을 가지고 있는지 확인하는 검사를 건너뜁니다. 이 변수가 없으면 응답이 다른 content-type을 가진 경우 Claude Code는 해당 유형을 명시하는 오류와 함께 요청을 실패 처리하며, 이는 [게이트웨이나 프록시가 응답을 변환하고 있음](/docs/ko/amazon-bedrock#streaming-errors-behind-a-gateway-or-proxy)을 의미합니다. 이 변수를 설정하기보다는 게이트웨이가 `Content-Type` 헤더와 본문을 수정하지 않고 전달하도록 구성하세요. Claude Code v2.1.208 이상이 필요합니다 |

253| `CLAUDE_CODE_DISABLE_BG_SHELL_PRESSURE_REAP` | 메모리 압박 상태에서 [백그라운드 셸 명령](/docs/ko/interactive-mode#background-bash-commands)을 종료하지 않도록 하려면 `1`로 설정하세요. 기본적으로, macOS 및 Linux에서, Claude Code는 운영 체제가 중요한 메모리 압박을 보고하고 세션이 30분 동안 유휴 상태이며 턴이나 서브에이전트가 실행 중이 아닐 때 백그라운드 셸을 종료합니다. Windows에는 메모리 압박 신호가 없으므로 이 변수는 효과가 없습니다. Claude Code v2.1.193 이상이 필요합니다 |253| `CLAUDE_CODE_DISABLE_BG_EXIT_HANDOFF` | `1`로 설정하면 [슈퍼바이저](/docs/ko/agent-view#the-supervisor-process)가 [백그라운드 세션](/docs/ko/agent-view)의 프로세스를 중지, 재시작 또는 업데이트할 때 해당 세션에서 실행 중인 백그라운드 셸 명령, 동적 워크플로, 그리고 v2.1.198부터는 백그라운드 서브에이전트를 세션의 다음 프로세스로 넘기지 않고 중지합니다. 이 인계에만 영향을 줍니다. `←` 또는 [`/background`](/docs/ko/agent-view#from-inside-a-session)로 세션을 백그라운드로 전환하면 진행 중인 작업이 여전히 이어지며, `CLAUDE_DISABLE_ADOPT`는 두 가지를 모두 끕니다. Claude Code v2.1.196 이상이 필요합니다 |

254| `CLAUDE_CODE_DISABLE_BUNDLED_SKILLS` | Claude Code에 포함된 [스킬](/docs/ko/skills) 및 워크플로우를 비활성화하려면 `1`로 설정하세요: 번들 스킬 및 워크플로우는 완전히 제거되고, `/init` 같은 기본 제공 명령은 입력 가능하지만 모델에서 숨겨집니다. `/doctor`는 기본 제공 명령처럼 입력 가능합니다. `DISABLE_DOCTOR_COMMAND`로 숨기세요. 플러그인, `.claude/skills/`, `.claude/commands/`의 스킬은 영향을 받지 않습니다. [`disableBundledSkills`](/docs/ko/settings-reference#disablebundledskills) 설정과 동등합니다 |254| `CLAUDE_CODE_DISABLE_BG_SHELL_PRESSURE_REAP` | `1`로 설정하면 Claude Code가 시스템 메모리 압박 상황에서 [백그라운드 셸 명령](/docs/ko/interactive-mode#background-bash-commands)을 종료하지 않습니다. 기본적으로 macOS와 Linux에서 Claude Code는 운영 체제가 심각한 메모리 압박을 보고하고, 세션이 실행 중인 턴이나 서브에이전트 없이 30분 동안 유휴 상태였을 때 백그라운드 셸을 종료합니다. Windows에는 메모리 압박 신호가 없으므로 이 변수는 효과가 없습니다. Claude Code v2.1.193 이상이 필요합니다 |

255| `CLAUDE_CODE_DISABLE_CFC_PROMPT` | [Claude in Chrome](/docs/ko/chrome) 브라우저 도구를 사용 가능하게 유지하면서 시스템 프롬프트의 Chrome 섹션과 `/claude-in-chrome` [번들 스킬](/docs/ko/skills#bundled-skills)을 생략하려면 `1`로 설정하세요. Claude Code를 포함하고 자신의 브라우저 지침을 제공하는 호스트용입니다. Claude Code v2.1.257 이상이 필요합니다 |255| `CLAUDE_CODE_DISABLE_BUNDLED_SKILLS` | `1`로 설정하면 Claude Code에 포함된 [스킬](/docs/ko/skills)과 워크플로를 비활성화합니다. 번들 스킬과 워크플로는 완전히 제거되며, `/init`와 같은 기본 제공 명령은 계속 입력할 수 있지만 모델에는 숨겨집니다. `/doctor`는 기본 제공 명령처럼 계속 입력할 수 있으며, 숨기려면 대신 `DISABLE_DOCTOR_COMMAND`를 사용하세요. 플러그인, `.claude/skills/`, `.claude/commands/`의 스킬은 영향을 받지 않습니다. [`disableBundledSkills`](/docs/ko/settings-reference#disablebundledskills) 설정과 동일합니다 |

256| `CLAUDE_CODE_DISABLE_CLAUDE_MDS` | 사용자, 프로젝트, 자동 메모리 파일을 포함한 CLAUDE.md 메모리 파일을 컨텍스트에 로드하지 않으려면 `1`로 설정하세요 |256| `CLAUDE_CODE_DISABLE_CFC_PROMPT` | `1`로 설정하면 [Claude in Chrome](/docs/ko/chrome) 브라우저 도구는 계속 사용할 수 있게 유지하면서 시스템 프롬프트의 Chrome 섹션과 `/claude-in-chrome` [번들 스킬](/docs/ko/skills#bundled-skills)을 생략합니다. Claude Code를 내장하고 자체 브라우저 지침을 제공하는 호스트를 위한 것입니다. Claude Code v2.1.257 이상이 필요합니다 |

257| `CLAUDE_CODE_DISABLE_CRON` | [예약된 작업](/docs/ko/scheduled-tasks)을 비활성화하려면 `1`로 설정하세요. `/loop` 스킬 및 cron 도구를 사용할 수 없게 되고 이미 예약된 작업이 중지됩니다. 세션 중간에 이미 실행 중인 작업 포함 |257| `CLAUDE_CODE_DISABLE_CLAUDE_MDS` | `1`로 설정하면 사용자, 프로젝트, 자동 메모리 파일을 포함한 모든 CLAUDE.md 메모리 파일을 컨텍스트에 로드하지 않습니다 |

258| `CLAUDE_CODE_DISABLE_DANGEROUS_RM_TIMEOUT` | [중요 경로 제거](/docs/ko/permission-modes#critical-paths) 프롬프트의 시간 제한을 끄려면 `1`로 설정하세요. `auto` 모드에서 Claude Code는 이러한 제거를 분류기 대신 전송하고, `bypassPermissions` 모드에서 프롬프트는 답변을 기다립니다. Claude Code를 시작하는 환경에서 설정하세요. Claude Code는 설정 파일의 `env` 블록을 통해 전달된 복사본을 무시합니다. Claude Code v2.1.281 이상이 필요합니다 |258| `CLAUDE_CODE_DISABLE_CRON` | `1`로 설정하면 [예약 작업](/docs/ko/scheduled-tasks)을 비활성화합니다. `/loop` 스킬과 cron 도구를 사용할 수 없게 되며, 세션 도중 이미 실행 중인 작업을 포함하여 이미 예약된 모든 작업이 더 이상 실행되지 않습니다 |

259| `CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS` | Anthropic 특정 `anthropic-beta` 요청 헤더 및 베타 도구 스키마 필드(예: `defer_loading` 및 `eager_input_streaming`)를 API 요청에서 제거하려면 `1`로 설정하세요. 프록시 게이트웨이가 "Unexpected value(s) for the `anthropic-beta` header" 또는 "Extra inputs are not permitted" 같은 오류로 요청을 거부할 때 사용합니다. 표준 필드(`name`, `description`, `input_schema`, `cache_control`)는 보존됩니다. [MCP 도구 검색](/docs/ko/mcp#scale-with-mcp-tool-search)은 비활성화되고 모든 MCP 도구는 도구 검색을 설정해도 미리 로드됩니다. Claude Code v2.1.227 이상에서는 [관리 설정](/docs/ko/managed-settings)이 도구 검색을 켜진 상태로 유지할 수 있습니다. [사전 릴리스 기능 비활성화](/docs/ko/llm-gateway-protocol#disable-pre-release-capabilities)는 재정의가 적용되는 위치를 다룹니다 |259| `CLAUDE_CODE_DISABLE_DANGEROUS_RM_TIMEOUT` | `1`로 설정하면 [중요 경로 삭제](/docs/ko/permission-modes#critical-paths) 프롬프트의 시간 제한을 끕니다. 그러면 `auto` 모드에서는 Claude Code가 이러한 삭제를 대신 분류기로 보내고, `bypassPermissions` 모드에서는 프롬프트가 사용자의 응답을 기다립니다. Claude Code는 설정 `env` 블록을 통해 전달된 값을 무시하므로, Claude Code를 실행하는 환경에서 설정하세요. Claude Code v2.1.281 이상이 필요합니다 |

260| `CLAUDE_CODE_DISABLE_EXPLORE_PLAN_AGENTS` | 기본 제공 [Explore 및 Plan 서브에이전트](/docs/ko/sub-agents#built-in-subagents)를 비활성화하려면 `1`로 설정하세요. Claude는 검색 도구 또는 범용 서브에이전트로 탐색하고, [계획 모드](/docs/ko/permission-modes#analyze-before-you-edit-with-plan-mode)는 Explore 및 Plan 에이전트를 시작하는 대신 파일을 직접 읽습니다. `Explore` 또는 `Plan`이라는 사용자 정의 서브에이전트는 영향을 받지 않습니다. Agent SDK 또는 비대화형 모드에서 모든 기본 제공 서브에이전트 유형을 제거하려면 `CLAUDE_AGENT_SDK_DISABLE_BUILTIN_AGENTS`를 대신 사용하세요. Claude Code v2.1.198 이상이 필요합니다 |260| `CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS` | `1`로 설정하면 API 요청에서 Anthropic 전용 `anthropic-beta` 요청 헤더와 베타 도구 스키마 필드(`defer_loading`, `eager_input_streaming` 등)를 제거합니다. 프록시 게이트웨이가 "Unexpected value(s) for the `anthropic-beta` header" 또는 "Extra inputs are not permitted"와 같은 오류로 요청을 거부할 때 사용하세요. 표준 필드(`name`, `description`, `input_schema`, `cache_control`)는 유지됩니다. `ENABLE_TOOL_SEARCH`를 설정하더라도 [MCP 도구 검색](/docs/ko/mcp#scale-with-mcp-tool-search)이 비활성화되고 모든 MCP 도구가 미리 로드됩니다. Claude Code v2.1.227 이상에서는 [관리형 설정](/docs/ko/managed-settings)으로 도구 검색을 켜 둘 수 있습니다. 재정의가 적용되는 위치는 [사전 출시 기능 비활성화](/docs/ko/llm-gateway-protocol#disable-pre-release-capabilities)에서 다룹니다 |

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

262| `CLAUDE_CODE_DISABLE_FEEDBACK_SURVEY` | "Claude가 어떻게 하고 있나요?" 세션 품질 설문조사를 비활성화하려면 `1`로 설정하세요. `DISABLE_TELEMETRY`, `DO_NOT_TRACK`, 또는 `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC`이 설정되면 설문조사도 비활성화됩니다. `CLAUDE_CODE_ENABLE_FEEDBACK_SURVEY_FOR_OTEL`이 다시 옵트인하지 않는 한입니다. 완전히 비활성화하는 대신 샘플 속도를 설정하려면 [`feedbackSurveyRate`](/docs/ko/settings-reference#feedbacksurveyrate) 설정을 사용하세요. [세션 품질 설문조사](/docs/ko/data-usage#session-quality-surveys)를 참조하세요 |262| `CLAUDE_CODE_DISABLE_FAST_MODE` | `1`로 설정하면 [빠른 모드](/docs/ko/fast-mode)를 비활성화합니다 |

263| `CLAUDE_CODE_DISABLE_FILE_CHECKPOINTING` | 파일 [체크포인팅](/docs/ko/checkpointing)을 비활성화하려면 `1`로 설정하세요. `/rewind` 명령이 코드 변경을 복원할 수 없습니다. [`fileCheckpointingEnabled`](/docs/ko/settings-reference#filecheckpointingenabled) 설정을 재정의합니다 |263| `CLAUDE_CODE_DISABLE_FEEDBACK_SURVEY` | `1`로 설정하면 "How is Claude doing?" 세션 품질 설문을 비활성화합니다. `DISABLE_TELEMETRY`, `DO_NOT_TRACK` 또는 `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC`이 설정된 경우에도 설문이 비활성화되며, `CLAUDE_CODE_ENABLE_FEEDBACK_SURVEY_FOR_OTEL`로 다시 옵트인한 경우는 예외입니다. 완전히 비활성화하는 대신 샘플링 비율을 설정하려면 [`feedbackSurveyRate`](/docs/ko/settings-reference#feedbacksurveyrate) 설정을 사용하세요. [세션 품질 설문](/docs/ko/data-usage#session-quality-surveys)을 참조하세요 |

264| `CLAUDE_CODE_DISABLE_GIT_INSTRUCTIONS` | 기본 제공 커밋 및 PR 워크플로우 지침과 git 상태 스냅샷을 Claude의 컨텍스트에서 제거하려면 `1`로 설정하세요. 자신의 git 워크플로우 스킬을 사용할 때 유용합니다. 설정되면 [`includeGitInstructions`](/docs/ko/settings-reference#includegitinstructions) 설정보다 우선합니다 |264| `CLAUDE_CODE_DISABLE_FILE_CHECKPOINTING` | `1`로 설정하면 파일 [체크포인트](/docs/ko/checkpointing)를 비활성화합니다. `/rewind` 명령으로 코드 변경 사항을 복원할 수 없게 됩니다. [`fileCheckpointingEnabled`](/docs/ko/settings-reference#filecheckpointingenabled) 설정을 재정의합니다 |

265| `CLAUDE_CODE_DISABLE_LEGACY_MODEL_REMAP` | Anthropic API에서 Opus 4.0 및 4.1을 현재 Opus 버전으로 자동 재매핑하지 않으려면 `1`로 설정하세요. 의도적으로 이전 모델을 고정하려고 할 때 사용합니다. 재매핑은 Amazon Bedrock, Google Cloud의 Agent Platform, Microsoft Foundry에서 실행되지 않습니다 |265| `CLAUDE_CODE_DISABLE_GIT_INSTRUCTIONS` | `1`로 설정하면 Claude의 컨텍스트에서 기본 제공 커밋 및 PR 워크플로 지침과 git 상태 스냅샷을 제거합니다. 자체 git 워크플로 스킬을 사용할 때 유용합니다. 설정하면 [`includeGitInstructions`](/docs/ko/settings-reference#includegitinstructions) 설정보다 우선합니다 |

266| `CLAUDE_CODE_DISABLE_MOUSE` | [전체 화면 렌더링](/docs/ko/fullscreen)에서 마우스 추적을 비활성화하려면 `1`로 설정하세요. `PgUp` 및 `PgDn`을 사용한 키보드 스크롤은 여전히 작동합니다. 터미널의 기본 선택 시 복사 동작을 유지하려면 이를 사용하세요 |266| `CLAUDE_CODE_DISABLE_LEGACY_MODEL_REMAP` | `1`로 설정하면 Anthropic API에서 Opus 4.0 및 4.1이 현재 Opus 버전으로 자동 재매핑되는 것을 방지합니다. 의도적으로 이전 모델을 고정하려는 경우 사용하세요. 재매핑은 Amazon Bedrock, Google Cloud's Agent Platform, Microsoft Foundry에서는 실행되지 않습니다 |

267| `CLAUDE_CODE_DISABLE_MOUSE_CLICKS` | [전체 화면 렌더링](/docs/ko/fullscreen)에서 클릭, 드래그, 호버 처리를 비활성화하려면 `1`로 설정하세요. 마우스 휠 스크롤은 유지됩니다. Claude Code 내에서 휠 스크롤이 작동하기를 원하지만 클릭이 커서를 배치하거나, 도구 출력을 확장하거나, 링크를 열지 않기를 원할 때 사용합니다. 둘 다 설정되면 `CLAUDE_CODE_DISABLE_MOUSE`가 우선합니다. Claude Code v2.1.195 이상이 필요합니다 |267| `CLAUDE_CODE_DISABLE_MODEL_ACCESS_FALLBACK` | `1`로 설정하면 세션 도중 계정이 세션 모델에 대한 접근 권한을 잃었을 때 [Amazon Bedrock](/docs/ko/amazon-bedrock#when-a-model-is-disabled-mid-session)과 [Google Cloud's Agent Platform](/docs/ko/google-vertex-ai#when-a-model-is-disabled-mid-session)의 Claude Code가 이전 모델로 전환하지 않으며, 대신 거부된 요청이 즉시 실패합니다. 구성한 [폴백 모델 체인](/docs/ko/model-config#fallback-model-chains)은 해당 거부 시에도 여전히 전환되며, [시작 시 모델 검사](/docs/ko/amazon-bedrock#startup-model-checks)도 실행 시점에 여전히 폴백합니다. Claude Code v2.1.285 이상이 필요합니다 |

268| `CLAUDE_CODE_DISABLE_MTLS_RELOAD_ON_STALE_CONNECTION` | API 요청이 연결 재설정 또는 TLS 핸드셰이크 오류 같은 연결 수준 오류로 실패할 때 Claude Code가 [mTLS 클라이언트 인증서 및 키](/docs/ko/network-config#mtls-authentication)를 다시 읽지 않도록 하려면 `1`로 설정하세요. 다시 로드가 비활성화되면, Claude Code는 다음에 설정을 적용하거나 다음 시작 시에만 회전된 파일을 로드합니다. Claude Code v2.1.232 이상이 필요합니다 |268| `CLAUDE_CODE_DISABLE_MOUSE` | `1`로 설정하면 [전체 화면 렌더링](/docs/ko/fullscreen)에서 마우스 추적을 비활성화합니다. `PgUp`과 `PgDn`을 사용한 키보드 스크롤은 계속 작동합니다. 터미널 기본의 선택 시 복사 동작을 유지하려면 사용하세요 |

269| `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC` | 비필수 네트워크 트래픽을 비활성화하려면 `1` 같은 비어있지 않은 값으로 설정하세요: 자동 업데이트, 원격 측정, 오류 보고, `/feedback` 명령, [Claude 작성 피드백](/docs/ko/tools-reference#sendfeedback-tool-behavior), 릴리스 노트, [PR 및 MR 상태 배지](/docs/ko/interactive-mode#pr-review-status) 확인, [빠른 모드](/docs/ko/fast-mode#use-fast-mode-behind-proxies-and-llm-gateways) 확인 같은 가용성 확인. 또한 로컬 명령이지만 네트워크 트래픽이 아닌 플러그인 `command` 소스의 [백그라운드 실행](/docs/ko/plugins/loading#when-a-command-source-re-runs)을 중지합니다. 종속성 설치를 트리거할 수 있기 때문입니다. **`0` 또는 `false`로 설정하면 여전히 이 트래픽을 비활성화합니다**. 대부분의 온/오프 변수와 달리 변수를 설정 해제하여 다시 허용하세요. 또한 기능 플래그 가져오기를 비활성화하여 [Remote Control](/docs/ko/remote-control#requirements) 및 기타 [기능 플래그 가져오기가 필요한 기능](#features-that-need-feature-flag-fetching)을 사용할 수 없게 합니다. 공식 플러그인 마켓플레이스 자동 설치는 포함되지 않습니다. `CLAUDE_CODE_DISABLE_OFFICIAL_MARKETPLACE_AUTOINSTALL`으로 비활성화하세요. [게이트웨이 모델 검색](/docs/ko/llm-gateway-connect#add-gateway-models-to-the-model-picker)에는 영향을 주지 않습니다. 이는 자신의 옵트인이 있습니다 |269| `CLAUDE_CODE_DISABLE_MOUSE_CLICKS` | `1`로 설정하면 마우스 휠 스크롤은 유지하면서 [전체 화면 렌더링](/docs/ko/fullscreen)에서 클릭, 드래그, 호버 처리를 비활성화합니다. Claude Code 내에서 휠 스크롤은 작동하게 하되 클릭으로 커서를 배치하거나, 도구 출력을 펼치거나, 링크를 열지 않게 하려면 사용하세요. 둘 다 설정된 경우 `CLAUDE_CODE_DISABLE_MOUSE`가 우선합니다. Claude Code v2.1.195 이상이 필요합니다 |

270| `CLAUDE_CODE_DISABLE_NONSTREAMING_FALLBACK` | 스트리밍 요청이 스트림 중간에 실패할 때 비스트리밍 폴백을 비활성화하려면 `1`로 설정하세요. 스트리밍 오류는 재시도 계층으로 전파됩니다. 프록시 또는 게이트웨이가 폴백으로 인해 중복 도구 실행을 생성할 때 유용합니다 |270| `CLAUDE_CODE_DISABLE_MTLS_RELOAD_ON_STALE_CONNECTION` | `1`로 설정하면 API 요청이 연결 재설정이나 TLS 핸드셰이크 오류와 같은 연결 수준 오류로 실패할 때 Claude Code가 [mTLS 클라이언트 인증서와 키](/docs/ko/network-config#mtls-authentication)를 다시 읽지 않습니다. 다시 읽기가 비활성화되면 Claude Code는 다음에 설정을 적용할 때나 다음 시작 시에만 교체된 파일을 로드합니다. Claude Code v2.1.232 이상이 필요합니다 |

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

272| `CLAUDE_CODE_DISABLE_OFFICIAL_MARKETPLACE_AUTOINSTALL` | 공식 플러그인 마켓플레이스의 자동 등록을 비활성화하려면 `1`로 설정하세요. Claude Code는 마켓플레이스를 등록하려고 할 때 변수를 읽습니다. 보통 머신의 첫 대화형 시작 중입니다. 그 시점에서 변수가 설정되면, Claude Code는 등록을 영구적으로 건너뜁니다. 나중에 변수를 설정 해제해도 건너뛰기가 취소되지 않습니다. 언제든지 `claude plugin marketplace add anthropics/claude-plugins-official`을 실행하여 마켓플레이스를 등록하세요 |272| `CLAUDE_CODE_DISABLE_NONSTREAMING_FALLBACK` | `1`로 설정하면 스트리밍 요청이 스트림 도중 실패할 때의 비스트리밍 폴백을 비활성화합니다. 대신 스트리밍 오류가 재시도 계층으로 전파됩니다. 프록시나 게이트웨이로 인해 폴백이 도구를 중복 실행하는 경우 유용합니다 |

273| `CLAUDE_CODE_DISABLE_PERMISSION_PROMPT_NOTIFY_HOOKS` | Claude Code가 Claude Desktop 및 VS Code 확장이 Claude Code를 호스팅하는 방식인 Agent SDK의 `canUseTool` 콜백으로 전송하는 세션에서 [응답되지 않은 권한 요청에 대한 `Notification` 훅](/docs/ko/hooks#notification)을 실행하지 않도록 하려면 `1`로 설정하세요. 터미널 세션에는 효과가 없습니다. Claude Code v2.1.233 이상이 필요합니다 |273| `CLAUDE_CODE_DISABLE_NOTIFICATION_PRESENCE_CHECK` | `1`로 설정하면 사용자가 터미널에서 입력 중이거나 터미널에 포커스가 있는 동안에도 `PushNotification` 도구의 데스크톱 알림을 전송합니다. 기본적으로 이 도구는 최근 키보드 활동이나 터미널 포커스를 감지하면 데스크톱 알림과 [모바일 푸시](/docs/ko/remote-control#mobile-push-notifications)를 모두 건너뜁니다. 이 변수는 해당 로컬 검사만 비활성화하므로, 서버가 사용자가 활동 중임을 감지하면 여전히 모바일 푸시를 억제할 수 있습니다. Claude Code v2.1.193 이상이 필요합니다 |

274| `CLAUDE_CODE_DISABLE_POLICY_SKILLS` | 시스템 전체 관리 스킬 디렉토리에서 스킬 로드를 건너뛰려면 `1`로 설정하세요. Claude Code가 운영자 제공 스킬을 로드하지 않아야 하는 컨테이너 또는 CI 세션에 유용합니다 |274| `CLAUDE_CODE_DISABLE_OFFICIAL_MARKETPLACE_AUTOINSTALL` | `1`로 설정하면 공식 플러그인 마켓플레이스의 자동 등록을 비활성화합니다. Claude Code는 마켓플레이스를 등록하려는 시점, 일반적으로 머신에서 처음 대화형으로 실행할 때 이 변수를 읽습니다. 그 시점에 변수가 설정되어 있으면 Claude Code는 등록을 영구적으로 건너뜁니다. 나중에 변수를 설정 해제해도 건너뛴 등록은 되돌려지지 않습니다. 언제든지 마켓플레이스를 등록하려면 `claude plugin marketplace add anthropics/claude-plugins-official`을 실행하세요 |

275| `CLAUDE_CODE_DISABLE_POWERSHELL_CMD_RM_DENY` | [PowerShell 도구](/docs/ko/tools-reference#powershell-tool)가 [시스템 경로](/docs/ko/permission-modes#remove-item-in-powershell)(예: 드라이브 루트 또는 홈 디렉토리)에서 `cmd` 기본 제공 `rd`, `rmdir`, `del`, `erase`를 거부하는 확인을 끄려면 `1`로 설정하세요. Claude Code는 설정 파일의 `env` 블록에서 이 변수를 무시합니다. Claude Code v2.1.283 이상이 필요합니다 |275| `CLAUDE_CODE_DISABLE_PERMISSION_PROMPT_NOTIFY_HOOKS` | `1`로 설정하면 Claude Code가 권한 요청을 Agent SDK의 `canUseTool` 콜백으로 보내는 세션(Claude Desktop과 VS Code 확장이 Claude Code를 호스팅하는 방식)에서 [응답하지 않은 권한 요청에 대한 `Notification` 훅](/docs/ko/hooks#notification)을 실행하지 않습니다. 터미널 세션에서는 효과가 없습니다. Claude Code v2.1.233 이상이 필요합니다 |

276| `CLAUDE_CODE_DISABLE_SUBSTITUTION_RM_PROMPT` | [중요 경로](/docs/ko/permission-modes#critical-paths) 확인을 `rm -rf "$(pwd)"` 같은 명령 치환의 전체 출력인 재귀 `rm`에 대해 끄려면 `1`로 설정하세요. 다른 중요 경로 확인은 계속 실행됩니다. Claude Code를 시작하는 환경에서 설정하세요. Claude Code는 설정 파일의 `env` 블록을 통해 전달된 복사본을 무시합니다. Claude Code v2.1.281 이상이 필요합니다 |276| `CLAUDE_CODE_DISABLE_POLICY_SKILLS` | `1`로 설정하면 시스템 전체 관리형 스킬 디렉터리에서 스킬을 로드하지 않습니다. 운영자가 프로비저닝한 스킬을 로드하지 않아야 하는 컨테이너나 CI 세션에 유용합니다 |

277| `CLAUDE_CODE_DISABLE_TERMINAL_TITLE` | 대화 컨텍스트를 기반으로 자동 터미널 제목 업데이트를 비활성화하려면 `1`로 설정하세요. 또한 [세션 제목을 생성](/docs/ko/sessions#name-your-sessions)하는 백그라운드 소형/빠른 모델 요청을 건너뜁니다 |277| `CLAUDE_CODE_DISABLE_POWERSHELL_CMD_RM_DENY` | `1`로 설정하면 드라이브 루트나 홈 디렉터리와 같은 [시스템 경로](/docs/ko/permission-modes#remove-item-in-powershell)에서 `cmd` 기본 제공 명령인 `rd`, `rmdir`, `del`, `erase`를 거부하는 [PowerShell 도구](/docs/ko/tools-reference#powershell-tool) 검사를 끕니다. Claude Code는 설정 파일의 `env` 블록에 있는 이 변수를 무시합니다. Claude Code v2.1.283 이상이 필요합니다 |

278| `CLAUDE_CODE_DISABLE_THINKING` | API 요청에서 `thinking` 매개변수를 완전히 생략하려면 `1`로 설정하세요. 이는 매개변수를 거부하는 프록시 및 게이트웨이의 호환성 옵션입니다. 기본적으로 생각하는 모델에서 매개변수를 생략하면 모델이 여전히 생각할 수 있습니다. Anthropic API에서 [확장 사고](https://platform.claude.com/docs/en/build-with-claude/extended-thinking)를 명시적으로 비활성화하려면 `MAX_THINKING_TOKENS=0`을 대신 사용하세요. 어느 변수도 Opus 5.5, Sonnet 5.5, Fable 모델에서 사고를 끄지 않습니다. 이들은 사고를 끌 수 없습니다. [타사 제공자](/docs/ko/third-party-integrations)에서 `MAX_THINKING_TOKENS=0`은 마찬가지로 매개변수를 생략하므로 두 변수는 동일하게 작동합니다 |278| `CLAUDE_CODE_DISABLE_SUBSTITUTION_RM_PROMPT` | `1`로 설정하면 `rm -rf "$(pwd)"`처럼 대상이 전적으로 명령 치환의 출력인 재귀 `rm`에 대한 [중요 경로](/docs/ko/permission-modes#critical-paths) 검사를 끕니다. 다른 중요 경로 검사는 계속 실행됩니다. Claude Code는 설정 `env` 블록을 통해 전달된 값을 무시하므로, Claude Code를 실행하는 환경에서 설정하세요. Claude Code v2.1.281 이상이 필요합니다 |

279| `CLAUDE_CODE_DISABLE_UNKNOWN_MODEL_WINDOW_ENFORCEMENT` | Claude Code가 모델 ID를 인식하지 못할 때(예: [LLM 게이트웨이](/docs/ko/llm-gateway) 별칭) 사전 [자동 압축](/docs/ko/costs#reduce-token-usage)을 건너뛰려면 `1`로 설정하세요. 이 변수 없이, Claude Code는 ID에 대해 가정하는 컨텍스트 창에서 압축합니다. `CLAUDE_CODE_MAX_CONTEXT_TOKENS`은 대신 가정된 창을 수정할 수 있습니다. [게이트웨이 또는 사용자 정의 모델 ID의 창 수정](/docs/ko/model-config#correct-the-window-for-a-gateway-or-custom-model-id)을 참조하여 각 변수가 언제 적용되는지 확인하세요. Claude Code v2.1.223 이상이 필요합니다 |279| `CLAUDE_CODE_DISABLE_TERMINAL_TITLE` | `1`로 설정하면 대화 컨텍스트에 기반한 자동 터미널 제목 업데이트를 비활성화합니다. 또한 [세션 제목을 생성하는](/docs/ko/sessions#name-your-sessions) 백그라운드 small/fast 모델 요청도 건너뜁니다 |

280| `CLAUDE_CODE_DISABLE_VIRTUAL_SCROLL` | [전체 화면 렌더링](/docs/ko/fullscreen)에서 가상 스크롤을 비활성화하고 대화 기록의 모든 메시지를 렌더링하려면 `1`로 설정하세요. 전체 화면 모드에서 스크롤이 메시지가 나타나야 할 위치에 빈 영역을 표시하면 이를 사용하세요 |280| `CLAUDE_CODE_DISABLE_THINKING` | `1`로 설정하면 API 요청에서 `thinking` 매개변수를 완전히 생략합니다. 이는 이 매개변수를 거부하는 프록시와 게이트웨이를 위한 호환성 옵션입니다. 기본적으로 사고하는 모델에서는 매개변수를 생략해도 모델이 여전히 사고할 수 있습니다. Anthropic API에서 [확장 사고](https://platform.claude.com/docs/en/build-with-claude/extended-thinking)를 명시적으로 비활성화하려면 대신 `MAX_THINKING_TOKENS=0`을 사용하세요. 사고를 끌 수 없는 Opus 5.5, Sonnet 5.5, Fable 모델에서는 두 변수 모두 사고를 끄지 않습니다. [서드 파티 제공업체](/docs/ko/third-party-integrations)에서는 `MAX_THINKING_TOKENS=0`도 마찬가지로 매개변수를 생략하므로, 두 변수가 동일하게 동작합니다 |

281| `CLAUDE_CODE_DISABLE_WINDOWS_SHELL_LAUNCHER` | Windows에서 `cmd.exe` 런처를 통하지 않고 [PowerShell 도구](/docs/ko/tools-reference#powershell-tool) 명령을 직접 시작하려면 `1`로 설정하세요. 기본적으로 런처는 [백그라운드에서 실행 중인](/docs/ko/tools-reference#background-commands) PowerShell 명령이 [세션의 다음 프로세스로 이월](/docs/ko/agent-view#the-supervisor-process)되도록 합니다. 예를 들어 [세션을 백그라운드 처리](/docs/ko/agent-view#from-inside-a-session)할 때입니다. 변수를 설정하면, 백그라운드 처리된 PowerShell 명령은 세션의 프로세스가 종료될 때 중지됩니다. Bash 명령은 영향을 받지 않습니다. Claude Code v2.1.269 이상이 필요합니다 |281| `CLAUDE_CODE_DISABLE_UNKNOWN_MODEL_WINDOW_ENFORCEMENT` | `1`로 설정하면 [LLM 게이트웨이](/docs/ko/llm-gateway) 별칭처럼 Claude Code가 모델 ID를 인식하지 못할 때 선제적 [자동 압축](/docs/ko/costs#reduce-token-usage)을 건너뜁니다. 이 변수가 없으면 Claude Code는 해당 ID에 대해 가정한 컨텍스트 윈도우에서 압축합니다. 대신 `CLAUDE_CODE_MAX_CONTEXT_TOKENS`로 가정된 윈도우를 수정할 수 있습니다. 각 변수가 적용되는 경우는 [게이트웨이 또는 사용자 지정 모델 ID의 윈도우 수정](/docs/ko/model-config#correct-the-window-for-a-gateway-or-custom-model-id)을 참조하세요. Claude Code v2.1.223 이상이 필요합니다 |

282| `CLAUDE_CODE_DISABLE_WORKFLOWS` | [워크플로우](/docs/ko/workflows#turn-workflows-off)를 비활성화하려면 `1`로 설정하세요. [`disableWorkflows`](/docs/ko/settings-reference#disableworkflows) 설정과 동등합니다 |282| `CLAUDE_CODE_DISABLE_VIRTUAL_SCROLL` | `1`로 설정하면 [전체 화면 렌더링](/docs/ko/fullscreen)에서 가상 스크롤을 비활성화하고 트랜스크립트의 모든 메시지를 렌더링합니다. 전체 화면 모드에서 스크롤할 때 메시지가 나타나야 할 곳에 빈 영역이 표시되는 경우 사용하세요 |

283| `CLAUDE_CODE_EFFORT_LEVEL` | 지원되는 모델의 노력 수준을 설정합니다. 값: `low`, `medium`, `high`, `xhigh`, `max`, 또는 모델 기본값을 사용하려면 `auto`. 사용 가능한 수준은 모델에 따라 다릅니다. `--effort`, `/effort`, `modelSettings` 및 `effortLevel` 설정보다 우선합니다. [`maxEffortLevel`](/docs/ko/settings-reference#maxeffortlevel) 상한이 여전히 적용됩니다. [노력 수준 조정](/docs/ko/model-config#adjust-effort-level)을 참조하세요 |283| `CLAUDE_CODE_DISABLE_WEB_FETCH` | `1`로 설정하면 [WebFetch](/docs/ko/tools-reference#webfetch-tool-behavior) 도구를 끕니다. [WebSearch](/docs/ko/tools-reference#websearch-tool-behavior) 도구는 계속 사용할 수 있습니다. Claude Code v2.1.285 이상이 필요합니다 |

284| `CLAUDE_CODE_ENABLE_AUTO_MODE` | 이전 릴리스와의 호환성을 위해 허용되며 효과가 없습니다. 자동 모드는 Amazon Bedrock, Google Cloud의 Agent Platform, Microsoft Foundry, 서명된 [Claude 앱 게이트웨이](/docs/ko/claude-apps-gateway) 세션을 포함한 모든 제공자에서 기본적으로 사용 가능합니다. v2.1.158부터 v2.1.206까지, 이러한 제공자에서 [자동 모드](/docs/ko/permission-modes#eliminate-prompts-with-auto-mode)를 사용 가능하게 하려면 이를 `1`로 설정해야 했습니다 |284| `CLAUDE_CODE_DISABLE_WINDOWS_SHELL_LAUNCHER` | `1`로 설정하면 Windows에서 [PowerShell 도구](/docs/ko/tools-reference#powershell-tool) 명령을 `cmd.exe` 런처를 거치지 않고 직접 시작합니다. 기본적으로 런처는 [백그라운드에서 실행 중인](/docs/ko/tools-reference#background-commands) PowerShell 명령이 [세션의 다음 프로세스로 이어지도록](/docs/ko/agent-view#the-supervisor-process) 합니다. 예를 들어 [세션을 백그라운드로 전환할](/docs/ko/agent-view#from-inside-a-session) 때가 그렇습니다. 변수를 설정하면 백그라운드로 전환된 PowerShell 명령은 세션의 프로세스가 종료될 때 중지됩니다. Bash 명령은 영향을 받지 않습니다. Claude Code v2.1.269 이상이 필요합니다 |

285| `CLAUDE_CODE_ENABLE_AWAY_SUMMARY` | [세션 요약](/docs/ko/interactive-mode#session-recap) 가용성을 재정의합니다. `/config` 토글에 관계없이 요약을 강제로 끄려면 `0`으로 설정하세요. [`awaySummaryEnabled`](/docs/ko/settings-reference#awaysummaryenabled)가 `false`일 때 요약을 강제로 켜려면 `1`로 설정하세요. 설정 및 `/config` 토글보다 우선합니다 |285| `CLAUDE_CODE_DISABLE_WORKFLOWS` | `1`로 설정하면 [워크플로](/docs/ko/workflows#turn-workflows-off)를 비활성화합니다. [`disableWorkflows`](/docs/ko/settings-reference#disableworkflows) 설정과 동일합니다 |

286| `CLAUDE_CODE_ENABLE_BACKGROUND_PLUGIN_REFRESH` | 백그라운드 설치가 완료된 후 [비대화형 모드](/docs/ko/headless)에서 턴 경계에서 플러그인 상태를 새로 고치려면 `1`로 설정하세요. 기본적으로 꺼져 있습니다. 새로 고침이 세션 중간에 시스템 프롬프트를 변경하기 때문에 [프롬프트 캐싱](/docs/ko/prompt-caching)이 해당 턴에 대해 무효화됩니다 |286| `CLAUDE_CODE_EFFORT_LEVEL` | 지원되는 모델의 effort 수준을 설정합니다. 값: `low`, `medium`, `high`, `xhigh`, `max`, 또는 모델 기본값을 사용하려면 `auto`. 사용 가능한 수준은 모델에 따라 다릅니다. `--effort`, `/effort`, `modelSettings` 및 `effortLevel` 설정보다 우선합니다. [`maxEffortLevel`](/docs/ko/settings-reference#maxeffortlevel) 상한은 여전히 적용됩니다. [effort 수준 조정](/docs/ko/model-config#adjust-effort-level)을 참조하세요 |

287| `CLAUDE_CODE_ENABLE_FEEDBACK_SURVEY_FOR_OTEL` | Anthropic 바운드 비필수 트래픽이 차단될 때 "Claude가 어떻게 하고 있나요?" 세션 품질 설문조사를 자신의 [OpenTelemetry 수집기](/docs/ko/monitoring-usage)로 라우팅하려면 `1`로 설정하세요. 설문조사 등급은 이 모드에서 구성된 수집기로만 OTEL 이벤트로 내보내집니다. 이 모드에서는 설문조사 데이터가 Anthropic으로 전송되지 않습니다. `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC`, `DISABLE_TELEMETRY`, 또는 `DO_NOT_TRACK`이 설정되면 적용되고, 그렇지 않으면 효과가 없습니다. `CLAUDE_CODE_DISABLE_FEEDBACK_SURVEY` 및 조직 제품 피드백 정책이 우선합니다 |287| `CLAUDE_CODE_ENABLE_AUTO_MODE` | 이전 릴리스와의 호환성을 위해 허용되며 효과가 없습니다. 자동 모드는 Amazon Bedrock, Google Cloud's Agent Platform, Microsoft Foundry, 로그인된 [Claude apps gateway](/docs/ko/claude-apps-gateway) 세션을 포함한 모든 제공업체에서 기본적으로 사용할 수 있습니다. v2.1.158부터 v2.1.206까지는 해당 제공업체에서 [자동 모드](/docs/ko/permission-modes#eliminate-prompts-with-auto-mode)를 사용하려면 이 값을 `1`로 설정해야 했습니다 |

288| `CLAUDE_CODE_ENABLE_FINE_GRAINED_TOOL_STREAMING` | 도구 호출 입력이 Claude가 생성할 때 API에서 스트리밍되는지 여부를 제어합니다. 이것이 꺼져 있으면, 긴 파일 쓰기 같은 큰 도구 입력은 Claude가 생성을 마친 후에만 도착합니다. 이는 중단된 것처럼 보일 수 있습니다. Anthropic API에서 기본적으로 활성화됩니다. Amazon Bedrock 및 Google Cloud의 Agent Platform에서는 배포된 컨테이너가 지원하는 모델별로 활성화됩니다. 프록시를 통해 라우팅할 때 강제로 켜려면 `1`로 설정하세요. `ANTHROPIC_BASE_URL`, `ANTHROPIC_VERTEX_BASE_URL`, 또는 `ANTHROPIC_BEDROCK_BASE_URL`을 통해 라우팅합니다. Microsoft Foundry 및 [게이트웨이](/docs/ko/llm-gateway) 연결에서는 기본적으로 꺼져 있습니다 |288| `CLAUDE_CODE_ENABLE_AWAY_SUMMARY` | [세션 요약](/docs/ko/interactive-mode#session-recap) 사용 가능 여부를 재정의합니다. `/config` 토글과 관계없이 요약을 강제로 끄려면 `0`으로 설정하세요. [`awaySummaryEnabled`](/docs/ko/settings-reference#awaysummaryenabled)가 `false`일 때 요약을 강제로 켜려면 `1`로 설정하세요. 설정과 `/config` 토글보다 우선합니다 |

289| `CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY` | `ANTHROPIC_BASE_URL`이 LiteLLM, Kong, 또는 내부 프록시 같은 Anthropic 호환 게이트웨이를 가리킬 때 게이트웨이의 `/v1/models` 엔드포인트에서 `/model` 선택기를 채우려면 `1`로 설정하세요. 기본적으로 꺼져 있습니다. 공유 API 키로 지원되는 게이트웨이는 그렇지 않으면 모든 사용자에게 키가 액세스할 수 있는 모든 모델을 표시하기 때문입니다. 검색된 모델은 여전히 세션이 수신하는 [`availableModels`](/docs/ko/settings-reference#availablemodels) 허용 목록으로 필터링됩니다. [MDM 또는 관리 설정 파일](/docs/ko/managed-settings#delivery-mechanisms)을 통해 목록을 전달하세요. [서버 관리 전달은 게이트웨이 구성에서 사용할 수 없습니다](/docs/ko/server-managed-settings#platform-availability) |289| `CLAUDE_CODE_ENABLE_BACKGROUND_PLUGIN_REFRESH` | `1`로 설정하면 백그라운드 설치가 완료된 후 [비대화형 모드](/docs/ko/headless)에서 턴 경계마다 플러그인 상태를 새로 고칩니다. 새로 고침은 세션 도중 시스템 프롬프트를 변경하여 해당 턴의 [프롬프트 캐싱](/docs/ko/prompt-caching)을 무효화하므로 기본적으로 꺼져 있습니다 |

290| `CLAUDE_CODE_ENABLE_OPUS_4_7_FAST_MODE` | v2.1.142에서 제거되었습니다. [빠른 모드](/docs/ko/fast-mode) 기본값이 Opus 4.6에서 Opus 4.7로 이동했을 때입니다 |290| `CLAUDE_CODE_ENABLE_FEEDBACK_SURVEY_FOR_OTEL` | Anthropic으로 향하는 비필수 트래픽이 차단된 경우 "How is Claude doing?" 세션 품질 설문을 자체 [OpenTelemetry 수집기](/docs/ko/monitoring-usage)로 보내려면 `1`로 설정합니다. 설문 평가는 구성된 수집기에 OTEL 이벤트로만 내보내집니다. 이 모드에서는 설문 데이터가 Anthropic으로 전송되지 않습니다. `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC`, `DISABLE_TELEMETRY` 또는 `DO_NOT_TRACK`이 설정된 경우에 적용되며, 그 외에는 효과가 없습니다. `CLAUDE_CODE_DISABLE_FEEDBACK_SURVEY`와 조직의 제품 피드백 정책이 우선합니다 |

291| `CLAUDE_CODE_ENABLE_PROMPT_SUGGESTION` | 프롬프트 입력에 나타나는 회색 예측인 프롬프트 제안을 끄려면 `false`로 설정하세요. [`promptSuggestionEnabled`](/docs/ko/settings-reference#promptsuggestionenabled) 설정보다 우선합니다. 이는 `/config`의 **프롬프트 제안** 토글이 쓰는 것입니다. Claude Code는 또한 [계정이 사용 제한에 가깝거나 도달했을 때 제안을 일시 중지](/docs/ko/interactive-mode#when-claude-code-skips-suggestions)합니다. 제한에 도달할 때까지 켜진 상태로 유지하려면 `true`로 설정하세요. Claude Code v2.1.238 이상이 필요합니다. [프롬프트 제안](/docs/ko/interactive-mode#prompt-suggestions)을 참조하세요 |291| `CLAUDE_CODE_ENABLE_FINE_GRAINED_TOOL_STREAMING` | Claude가 도구 호출 입력을 생성하는 동안 API에서 스트리밍할지 여부를 제어합니다. 이 기능이 꺼져 있으면 긴 파일 쓰기와 같은 큰 도구 입력은 Claude가 생성을 마친 후에야 도착하므로 멈춘 것처럼 보일 수 있습니다. Anthropic API에서는 기본적으로 활성화됩니다. Amazon Bedrock과 Google Cloud의 Agent Platform에서는 배포된 컨테이너가 지원하는 경우 모델별로 활성화됩니다. 사용하지 않으려면 `0`으로 설정합니다. `ANTHROPIC_BASE_URL`, `ANTHROPIC_VERTEX_BASE_URL` 또는 `ANTHROPIC_BEDROCK_BASE_URL`을 통해 프록시로 라우팅할 때 강제로 켜려면 `1`로 설정합니다. Microsoft Foundry 및 [게이트웨이](/docs/ko/llm-gateway) 연결에서는 기본적으로 꺼져 있습니다 |

292| `CLAUDE_CODE_ENABLE_TASKS` | [작업이 있는 세션](/docs/ko/tools-reference#task-tool-availability)에서 Claude Code가 제공하는 작업 추적 도구를 선택합니다. 기본적으로 Claude Code는 Task 도구 `TaskCreate`, `TaskUpdate`, `TaskGet`, `TaskList`를 제공합니다. 대신 레거시 `TodoWrite` 도구를 얻으려면 `0`으로 설정하세요. [작업 목록](/docs/ko/interactive-mode#task-list)을 참조하세요 |292| `CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY` | `ANTHROPIC_BASE_URL`이 LiteLLM, Kong 또는 내부 프록시와 같은 Anthropic 호환 게이트웨이를 가리킬 때 게이트웨이의 `/v1/models` 엔드포인트에서 `/model` 선택기를 채우려면 `1`로 설정합니다. 공유 API 키를 사용하는 게이트웨이에서는 키가 액세스할 수 있는 모든 모델이 모든 사용자에게 표시되므로 기본적으로 꺼져 있습니다. 검색된 모델은 여전히 세션이 받는 [`availableModels`](/docs/ko/settings-reference#availablemodels) 허용 목록으로 필터링됩니다. [게이트웨이 구성에서는 서버 관리 전달을 사용할 수 없으므로](/docs/ko/server-managed-settings#platform-availability) [MDM 또는 관리형 설정 파일](/docs/ko/managed-settings#delivery-mechanisms)을 통해 목록을 전달합니다 |

293| `CLAUDE_CODE_ENABLE_TELEMETRY` | OpenTelemetry 데이터 수집을 메트릭 및 로깅에 대해 활성화하려면 `1`로 설정하세요. OTel 익스포터를 구성하기 전에 필수입니다. 셸, 사용자 설정 또는 관리 설정에서 설정하세요. [프로젝트 및 로컬 설정](/docs/ko/settings-reference#variables-claude-code-ignores-in-env)에서는 무시됩니다. [모니터링](/docs/ko/monitoring-usage)을 참조하세요 |293| `CLAUDE_CODE_ENABLE_OPUS_4_7_FAST_MODE` | [빠른 모드](/docs/ko/fast-mode) 기본값이 Opus 4.6에서 Opus 4.7로 변경된 v2.1.142에서 제거되었습니다 |

294| `CLAUDE_CODE_ENABLE_TODO_TOOLS` | 모든 모델에서 작업 추적 도구를 얻으려면 `1`로 설정하세요. 없으면 Claude Code는 [작업 도구 가용성](/docs/ko/tools-reference#task-tool-availability)에 나열된 모델에서만 기본적으로 제공합니다. `CLAUDE_CODE_ENABLE_TASKS`는 여전히 Task 도구 또는 `TodoWrite`를 선택합니다. Claude Code v2.1.233 이상이 필요합니다 |294| `CLAUDE_CODE_ENABLE_PROMPT_SUGGESTION` | 프롬프트 입력에 표시되는 회색 예측인 프롬프트 제안을 끄려면 `false`로 설정합니다. `/config`의 **Prompt suggestions** 토글이 기록하는 [`promptSuggestionEnabled`](/docs/ko/settings-reference#promptsuggestionenabled) 설정보다 우선합니다. Claude Code는 또한 [계정이 사용 한도에 가까워지거나 도달하면 제안을 일시 중지합니다](/docs/ko/interactive-mode#when-claude-code-skips-suggestions). 한도에 도달할 때까지 제안을 계속 켜 두려면 `true`로 설정합니다. Claude Code v2.1.238 이상이 필요합니다. [프롬프트 제안](/docs/ko/interactive-mode#prompt-suggestions)을 참조하세요 |

295| `CLAUDE_CODE_EXIT_AFTER_STOP_DELAY` | 쿼리 루프가 유휴 상태가 된 후 자동으로 종료되기 전에 대기할 시간(밀리초 단위)입니다. SDK 모드를 사용하는 자동화된 워크플로우 및 스크립트에 유용합니다 |295| `CLAUDE_CODE_ENABLE_TASKS` | [작업 추적 도구가 있는 세션](/docs/ko/tools-reference#task-tool-availability)에서 Claude Code가 제공하는 작업 추적 도구를 선택합니다. 기본적으로 Claude Code는 Task 도구인 `TaskCreate`, `TaskUpdate`, `TaskGet`, `TaskList`를 제공합니다. 대신 레거시 `TodoWrite` 도구를 사용하려면 `0`으로 설정합니다. [작업 목록](/docs/ko/interactive-mode#task-list)을 참조하세요 |

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

297| `CLAUDE_CODE_EXTRA_BODY` | 모든 API 요청 본문의 최상위 수준으로 병합할 JSON 객체입니다. Claude Code가 직접 노출하지 않는 제공자 특정 매개변수를 전달하는 데 유용합니다. 셸에서 내보낸 값은 또한 `claude agents` 또는 `--bg`로 디스패치하는 [백그라운드 세션](/docs/ko/agent-view)에 적용됩니다. v2.1.206 이전에는 백그라운드 세션이 셸 내보낸 값을 무시하고 백그라운드 감독자 프로세스가 상속한 복사본을 사용했습니다 |297| `CLAUDE_CODE_ENABLE_TODO_TOOLS` | 모든 모델에서 작업 추적 도구를 사용하려면 `1`로 설정합니다. 이 변수가 없으면 Claude Code는 [Task 도구 가용성](/docs/ko/tools-reference#task-tool-availability)에 나열된 모델에서만 기본적으로 이 도구를 제공합니다. `CLAUDE_CODE_ENABLE_TASKS`는 여전히 Task 도구와 `TodoWrite` 중 어느 것을 사용할지 선택합니다. Claude Code v2.1.233 이상이 필요합니다 |

299| `CLAUDE_CODE_FORCE_SESSION_PERSISTENCE` | 이 `claude`가 다른 Claude Code 세션 내에서 시작되었을 때에도 대화 기록 지속성, 프롬프트 기록, `claude agents` 등록을 강제하려면 `1`로 설정하세요. 상속된 `CLAUDE_CODE_CHILD_SESSION` 값(예: `screen` 세션 또는 Claude Code의 Bash 도구에 의해 먼저 시작된 백그라운드 런처)이 진정한 최상위 세션을 중첩된 것으로 잘못 분류할 때 사용합니다. v2.1.178부터 Claude Code는 tmux 경우를 자동으로 감지하고 상속된 마커를 무시하므로 tmux는 더 이상 이 변수가 필요하지 않습니다. 또한 v2.1.169 이상에서 인정됩니다. v2.1.170 및 v2.1.171에서는 효과가 없습니다. 이 변수가 재정의하는 중첩 세션 감지가 제거되었습니다 |299| `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS` | [에이전트 팀](/docs/ko/agent-teams)을 활성화하려면 `1`로 설정합니다. 에이전트 팀은 실험적 기능이며 기본적으로 비활성화되어 있습니다 |

300| `CLAUDE_CODE_FORCE_STRIKETHROUGH` | 터미널이 지원하지만 SSH를 통해 `TERM_PROGRAM`이 전달되지 않는 경우처럼 자동 감지되지 않을 때 Claude의 응답에서 `~~text~~`에 대한 취소선 렌더링을 강제하려면 `1`로 설정하세요. 감지되지 않으면, 감지되지 않은 터미널은 취소선으로 렌더링하는 대신 리터럴 `~~` 마커를 표시합니다. Claude Code v2.1.186 이상이 필요합니다 |300| `CLAUDE_CODE_EXTRA_BODY` | 모든 API 요청 본문의 최상위 수준에 병합할 JSON 객체입니다. Claude Code가 직접 노출하지 않는 공급자별 매개변수를 전달할 때 유용합니다. 셸에서 내보낸 값은 `claude agents` 또는 `--bg`로 디스패치하는 [백그라운드 세션](/docs/ko/agent-view)에도 적용됩니다. v2.1.206 이전에는 백그라운드 세션이 셸에서 내보낸 값을 무시하고 백그라운드 supervisor 프로세스가 상속한 값을 사용했습니다 |

301| `CLAUDE_CODE_FORCE_SYNC_OUTPUT` | 터미널이 지원하지만 자동 감지되지 않을 때 DEC 프라이빗 모드 2026 [동기화된 출력](https://gist.github.com/christianparpart/d8a62cc1ab659194337d73e399004036)을 강제로 활성화하려면 `1`로 설정하세요. Emacs `eat` 같은 BSU/ESU를 구현하지만 기능 프로브에 응답하지 않는 에뮬레이터에 유용합니다. tmux에서는 효과가 없습니다. [전체 화면 렌더링](/docs/ko/fullscreen)으로 전환하는 `CLAUDE_CODE_NO_FLICKER`와 달리, 이는 렌더러를 변경하지 않습니다 |301| `CLAUDE_CODE_FILE_READ_MAX_OUTPUT_TOKENS` | 파일 읽기의 기본 토큰 제한을 재정의합니다. 더 큰 파일을 전체적으로 읽어야 할 때 유용합니다 |

302| `CLAUDE_CODE_FORK_SUBAGENT` | [포크 모드](/docs/ko/sub-agents#turn-fork-mode-on-or-off)를 제어합니다. 이는 Claude가 [포크된 서브에이전트](/docs/ko/sub-agents#fork-the-current-conversation)를 자신이 생성하도록 하며 대화형 세션에서만 기본적으로 켜져 있습니다. `claude -p` 및 Agent SDK에서도 켜려면 `1`로 설정하거나, 모든 종류의 세션에서 끄려면 `0`으로 설정하세요. 포크 모드가 켜져 있는지 여부에 관계없이 `/subtask`를 실행할 수 있습니다. 대화형 기본값은 Claude Code v2.1.232 이상이 필요합니다. 이전 버전에서는 포크 모드를 켜려면 변수를 `1`로 설정하세요 |302| `CLAUDE_CODE_FORCE_SESSION_PERSISTENCE` | 이 `claude`가 다른 Claude Code 세션 내부에서 실행된 경우에도 트랜스크립트 저장, 프롬프트 기록, `claude agents` 등록을 강제하려면 `1`로 설정합니다. 예를 들어 `screen` 세션이나 Claude Code의 Bash 도구가 처음 시작한 백그라운드 런처에서 상속된 `CLAUDE_CODE_CHILD_SESSION` 값으로 인해 실제 최상위 세션이 중첩 세션으로 잘못 분류될 때 사용합니다. v2.1.178부터 Claude Code는 tmux의 경우를 자동으로 감지하고 상속된 마커를 무시하므로 tmux에서는 더 이상 이 변수가 필요하지 않습니다. v2.1.169 이하에서도 적용되며, 이 변수가 재정의하는 중첩 세션 감지가 제거된 v2.1.170 및 v2.1.171에서는 효과가 없습니다 |

303| `CLAUDE_CODE_FORWARD_SUBAGENT_TEXT` | `claude -p --output-format stream-json` 출력에서 [서브에이전트](/docs/ko/sub-agents) 텍스트 및 사고 블록을 내보내려면 `1`로 설정하세요. [`--forward-subagent-text`](/docs/ko/cli-reference#cli-flags) 플래그와 동일한 동작입니다. 하네스가 `claude`를 호출하고 플래그 자체를 전달할 수 없을 때 변수를 사용합니다. 플래그와 달리 비대화형 모드에서 stream-json 출력 외부에서 오류로 종료되는 것과 달리, 변수는 무시되므로 중첩된 호출이 프로세스 전체에서 설정될 때 계속 작동합니다. Claude Code v2.1.211 이상이 필요합니다 |303| `CLAUDE_CODE_FORCE_STRIKETHROUGH` | 터미널이 취소선을 지원하지만 자동으로 감지되지 않는 경우(예: `TERM_PROGRAM`이 전달되지 않는 SSH 환경), Claude의 응답에서 `~~text~~`를 취소선으로 강제 렌더링하려면 `1`로 설정합니다. 이 설정이 없으면 감지되지 않은 터미널에서는 텍스트를 취소선으로 렌더링하는 대신 `~~` 마커가 그대로 표시됩니다. Claude Code v2.1.186 이상이 필요합니다 |

304| `CLAUDE_CODE_GATEWAY_HINT_HEADERS` | 사용자 정의 프록시 또는 Amazon Bedrock 또는 Claude Platform on AWS 같은 타사 제공자에서 [게이트웨이 힌트 헤더](/docs/ko/llm-gateway-protocol#gateway-hint-headers)(예: `x-claude-code-request-class` 및 `x-claude-code-compaction`)를 전송하려면 `1`로 설정하세요. Anthropic API에 대한 직접 연결을 포함한 모든 연결에서 전송을 중지하려면 `0`으로 설정하세요. Claude Code는 기본적으로 직접 연결에서 전송합니다. Claude Code v2.1.273 이상이 필요합니다 |304| `CLAUDE_CODE_FORCE_SYNC_OUTPUT` | 터미널이 DEC private mode 2026 [동기화된 출력](https://gist.github.com/christianparpart/d8a62cc1ab659194337d73e399004036)을 지원하지만 자동으로 감지되지 않을 때 강제로 활성화하려면 `1`로 설정합니다. BSU/ESU를 구현하지만 기능 프로브에 응답하지 않는 Emacs `eat`과 같은 에뮬레이터에 유용합니다. tmux에서는 효과가 없습니다. [전체 화면 렌더링](/docs/ko/fullscreen)으로 전환하는 `CLAUDE_CODE_NO_FLICKER`와 달리 이 설정은 렌더러를 변경하지 않습니다 |

305| `CLAUDE_CODE_GATEWAY_MODEL_DISCOVERY_TIMEOUT_MS` | `CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY`가 켜는 [게이트웨이 모델 검색](/docs/ko/llm-gateway-protocol#model-discovery) 요청의 타임아웃(밀리초 단위)(기본값: `3000`). 게이트웨이가 시작 시 `/v1/models`에 응답하는 데 3초 이상 필요할 때 올리세요. 일반 숫자만 사용합니다. `0`, 음수 값, 기타 표기법은 기본값을 유지합니다. Claude Code v2.1.269 이상이 필요합니다 |305| `CLAUDE_CODE_FORK_SUBAGENT` | Claude가 [포크된 서브에이전트](/docs/ko/sub-agents#fork-the-current-conversation)를 직접 생성할 수 있게 하는 [포크 모드](/docs/ko/sub-agents#turn-fork-mode-on-or-off)를 제어하며, 포크 모드는 대화형 세션에서만 기본적으로 켜져 있습니다. `claude -p`와 Agent SDK에서도 켜려면 `1`로, 모든 종류의 세션에서 끄려면 `0`으로 설정합니다. `/subtask`는 포크 모드가 켜져 있는지와 관계없이 실행할 수 있습니다. 대화형 기본값에는 Claude Code v2.1.232 이상이 필요하며, 이전 버전에서는 포크 모드를 켜려면 변수를 `1`로 설정합니다 |

306| `CLAUDE_CODE_GIT_BASH_PATH` | Windows 전용: Git Bash 실행 파일(`bash.exe`)의 경로입니다. Git Bash가 설치되었지만 PATH에 없을 때 사용합니다. 경로가 존재하지 않거나 파일이 `bash.exe`, `sh.exe`, `bash`, 또는 `sh`로 명명되지 않으면, Claude Code는 변수를 무시하고 설정 해제된 것처럼 Git Bash를 자동 감지하며, `--debug`로 볼 수 있는 경고를 기록합니다. v2.1.219 이전에는 경로가 존재하지 않으면 Claude Code가 시작 시 종료되었고, bash 또는 sh인지 확인하지 않고 기존 파일을 셸로 사용했습니다. [Windows 설정](/docs/ko/setup#set-up-on-windows)을 참조하세요 |306| `CLAUDE_CODE_FORWARD_SUBAGENT_TEXT` | `claude -p --output-format stream-json` 출력에서 [서브에이전트](/docs/ko/sub-agents) 텍스트와 thinking 블록을 내보내려면 `1`로 설정합니다. [`--forward-subagent-text`](/docs/ko/cli-reference#cli-flags) 플래그와 동일한 동작입니다. 하니스가 `claude`를 호출하면서 플래그를 직접 전달할 수 없을 때 변수를 사용합니다. stream-json 출력을 사용하는 비대화형 모드 외부에서는 오류와 함께 종료되는 플래그와 달리, 변수는 그러한 환경에서 무시되므로 프로세스 전체에 설정되어 있어도 중첩 호출이 계속 작동합니다. Claude Code v2.1.211 이상이 필요합니다 |

307| `CLAUDE_CODE_GLOB_HIDDEN` | Claude가 [Glob 도구](/docs/ko/tools-reference#glob-tool-behavior)를 호출할 때 결과에서 숨김 파일을 제외하려면 `false`로 설정하세요. 기본적으로 포함됩니다. `@` 파일 자동 완성, `ls`, Grep, Read에는 영향을 주지 않습니다 |307| `CLAUDE_CODE_GATEWAY_HINT_HEADERS` | 사용자 지정 프록시 또는 Amazon Bedrock이나 Claude Platform on AWS와 같은 서드파티 공급자에서 `x-claude-code-request-class` 및 `x-claude-code-compaction`과 같은 [게이트웨이 힌트 헤더](/docs/ko/llm-gateway-protocol#gateway-hint-headers)를 보내려면 `1`로 설정합니다. Claude Code가 기본적으로 헤더를 보내는 Anthropic API 직접 연결을 포함하여 모든 연결에서 헤더 전송을 중지하려면 `0`으로 설정합니다. Claude Code v2.1.273 이상이 필요합니다 |

308| `CLAUDE_CODE_GLOB_NO_IGNORE` | [Glob 도구](/docs/ko/tools-reference#glob-tool-behavior)가 `.gitignore` 패턴을 존중하도록 하려면 `false`로 설정하세요. 기본적으로 Glob은 gitignored 파일을 포함한 모든 일치 파일을 반환합니다. `@` 파일 자동 완성에는 영향을 주지 않습니다. 이는 자신의 [`respectGitignore` 설정](/docs/ko/settings-reference#respectgitignore)을 가집니다 |308| `CLAUDE_CODE_GATEWAY_MODEL_DISCOVERY_TIMEOUT_MS` | `CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY`가 켜는 [게이트웨이 모델 검색](/docs/ko/llm-gateway-protocol#model-discovery) 요청의 타임아웃(밀리초)입니다(기본값: `3000`). 게이트웨이가 시작 시 `/v1/models`에 응답하는 데 3초보다 오래 걸리는 경우 값을 늘립니다. 숫자만 허용되며, `0`, 음수 값 및 기타 표기는 기본값을 유지합니다. Claude Code v2.1.269 이상이 필요합니다 |

309| `CLAUDE_CODE_GLOB_TIMEOUT_SECONDS` | Glob 도구 파일 검색의 타임아웃(초 단위)입니다. 대부분의 플랫폼에서 기본값은 20초이고 WSL에서는 60초입니다 |309| `CLAUDE_CODE_GIT_BASH_PATH` | Windows 전용: Git Bash 실행 파일(`bash.exe`)의 경로입니다. Git Bash가 설치되어 있지만 PATH에 없을 때 사용합니다. 경로가 존재하지 않거나 파일 이름이 `bash.exe`, `sh.exe`, `bash`, `sh`가 아니면 Claude Code는 변수를 무시하고 설정되지 않은 것처럼 Git Bash를 자동 감지하며, `--debug`로 볼 수 있는 경고를 로그에 기록합니다. v2.1.219 이전에는 경로가 존재하지 않으면 Claude Code가 시작 시 종료되었고, bash 또는 sh인지 확인하지 않고 존재하는 아무 파일이나 셸로 사용했습니다. [Windows 설정](/docs/ko/setup#set-up-on-windows)을 참조하세요 |

310| `CLAUDE_CODE_GOAL_CHECKIN_MINUTES` | 백그라운드 작업이 활성 목표를 대기 상태로 유지할 수 있는 시간(분 단위)입니다. 그 후 Claude Code는 [Claude에 이를 확인하도록 요청](/docs/ko/goal#background-work-defers-evaluation)합니다. 기본값 `30`. 체크인을 끄려면 `0`으로 설정하세요. 일반 숫자로 전체 분을 제공합니다. 최대 `10080`(1주). Claude Code는 다른 값을 기본값으로 취급합니다. Claude Code v2.1.234 이상이 필요합니다 |310| `CLAUDE_CODE_GLOB_HIDDEN` | Claude가 [Glob 도구](/docs/ko/tools-reference#glob-tool-behavior)를 호출할 때 결과에서 dotfile을 제외하려면 `false`로 설정합니다. 기본적으로 포함됩니다. `@` 파일 자동 완성, `ls`, Grep 또는 Read에는 영향을 주지 않습니다 |

311| `CLAUDE_CODE_HIDE_CWD` | 시작 로고에서 작업 디렉토리를 숨기려면 `1`로 설정하세요. 경로가 OS 사용자 이름을 노출하는 화면 공유 또는 녹화에 유용합니다 |311| `CLAUDE_CODE_GLOB_NO_IGNORE` | [Glob 도구](/docs/ko/tools-reference#glob-tool-behavior)가 `.gitignore` 패턴을 따르도록 하려면 `false`로 설정합니다. 기본적으로 Glob은 gitignore된 파일을 포함하여 일치하는 모든 파일을 반환합니다. 자체 [`respectGitignore` 설정](/docs/ko/settings-reference#respectgitignore)이 있는 `@` 파일 자동 완성에는 영향을 주지 않습니다 |

313| `CLAUDE_CODE_IDE_SKIP_AUTO_INSTALL` | IDE 확장의 자동 설치를 건너뛰려면 `1`로 설정하세요. [`autoInstallIdeExtension`](/docs/ko/settings-reference#autoinstallideextension)을 `false`로 설정하는 것과 동등합니다 |313| `CLAUDE_CODE_GOAL_CHECKIN_MINUTES` | Claude Code가 [Claude에게 활성 목표를 확인하도록 요청하기](/docs/ko/goal#background-work-defers-evaluation) 전에 백그라운드 작업이 활성 목표를 대기 상태로 유지할 수 있는 시간(분)입니다. 기본값은 `30`입니다. 확인을 끄려면 `0`으로 설정합니다. 최대 `10080`(1주일)까지 정수 분 단위로 숫자만 입력합니다. Claude Code는 그 외의 값을 설정되지 않은 것으로 간주하고 기본값을 사용합니다. Claude Code v2.1.234 이상이 필요합니다 |

315| `CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS` | Agent 도구가 다른 것을 생성하기를 거부하기 전에 한 세션에서 실행할 수 있는 [서브에이전트](/docs/ko/sub-agents#concurrent-subagent-limit) 수입니다(기본값: 20). 일반 숫자로 양의 정수를 허용합니다. 다른 것은 무시되므로 변수는 상한을 조정할 수 있지만 비활성화할 수 없습니다. Claude Code v2.1.217 이상이 필요합니다 |315| `CLAUDE_CODE_IDE_HOST_OVERRIDE` | IDE 확장에 연결하는 데 사용되는 호스트 주소를 재정의합니다. 기본적으로 Claude Code는 WSL에서 Windows로의 라우팅을 포함하여 올바른 주소를 자동으로 감지합니다 |

316| `CLAUDE_CODE_MAX_CONTEXT_TOKENS` | Claude Code가 활성 모델에 대해 가정하는 컨텍스트 창 크기를 재정의합니다. v2.1.193부터 적용 방식은 Claude Code가 모델 ID를 확인하는 방식에 따라 다릅니다. [게이트웨이 또는 사용자 정의 모델 ID의 창 수정](/docs/ko/model-config#correct-the-window-for-a-gateway-or-custom-model-id)을 참조하세요. `ANTHROPIC_BASE_URL`을 통해 이름이 기본 제공 크기와 일치하지 않는 모델로 라우팅할 때 사용합니다 |316| `CLAUDE_CODE_IDE_SKIP_AUTO_INSTALL` | IDE 확장의 자동 설치를 건너뛰려면 `1`로 설정합니다. [`autoInstallIdeExtension`](/docs/ko/settings-reference#autoinstallideextension)을 `false`로 설정하는 것과 같습니다 |

317| `CLAUDE_CODE_MAX_MCP_DESCRIPTION_LENGTH` | Claude Code가 모델로 전송하는 각 MCP 도구 설명 및 각 MCP 서버의 지침의 최대 길이(문자 단위)(기본값: 2048). Claude Code는 [더 긴 텍스트를 자릅니다](/docs/ko/mcp#for-mcp-server-authors). 일반 숫자로 양의 정수를 허용합니다. 다른 것은 무시되고 기본값이 적용됩니다. Claude Code v2.1.280 이상이 필요합니다 |317| `CLAUDE_CODE_IDE_SKIP_VALID_CHECK` | 연결 중 IDE lockfile 항목의 유효성 검사를 건너뛰려면 `1`로 설정합니다. IDE가 실행 중인데도 자동 연결이 IDE를 찾지 못할 때 사용합니다 |

318| `CLAUDE_CODE_MAX_OUTPUT_TOKENS` | 대부분의 요청에 대한 최대 출력 토큰 수를 설정합니다. 기본값 및 상한은 모델에 따라 다릅니다. [최대 출력 토큰](https://platform.claude.com/docs/en/about-claude/models/overview#latest-models-comparison)을 참조하세요. Claude Code는 인식하지 못하는 모델 ID(예: 게이트웨이 특정 이름)에 대해 32000으로 기본값을 설정하고 모델의 상한 이상의 값을 상한으로 낮춥니다. 이 값을 증가시키면 [자동 압축](/docs/ko/costs#reduce-token-usage)이 트리거되기 전에 사용 가능한 유효 컨텍스트 창이 감소합니다 |318| `CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS` | Agent 도구가 추가 생성을 거부하기 전에 한 세션에서 동시에 실행할 수 있는 [서브에이전트](/docs/ko/sub-agents#concurrent-subagent-limit) 수입니다(기본값: 20). 숫자로 된 양의 정수를 허용하며, 그 외의 값은 무시되므로 이 변수로 상한을 조정할 수는 있지만 비활성화할 수는 없습니다. Claude Code v2.1.217 이상이 필요합니다 |

319| `CLAUDE_CODE_MAX_RETRIES` | 실패한 API 요청을 재시도할 횟수를 재정의합니다(기본값: 10). v2.1.186부터 15로 제한됩니다. v2.1.199부터 `CLAUDE_CODE_RETRY_WATCHDOG`이 기본값을 올리고 상한을 제거합니다. 더 오래 중단되는 것을 기다려야 하는 무인 세션의 경우 `CLAUDE_CODE_RETRY_WATCHDOG`을 대신 설정하세요 |319| `CLAUDE_CODE_MAX_CONTEXT_TOKENS` | Claude Code가 활성 모델에 대해 가정하는 컨텍스트 윈도우 크기를 재정의합니다. v2.1.193부터는 Claude Code가 모델 ID를 확인하는 방식에 따라 적용 방식이 달라집니다. [게이트웨이 또는 사용자 지정 모델 ID의 윈도우 수정](/docs/ko/model-config#correct-the-window-for-a-gateway-or-custom-model-id)을 참조하세요. 컨텍스트 윈도우가 해당 이름의 기본 제공 크기와 일치하지 않는 모델로 `ANTHROPIC_BASE_URL`을 통해 라우팅할 때 사용합니다 |

320| `CLAUDE_CODE_MAX_SUBAGENTS_PER_SESSION` | v2.1.224에서 제거되었으며 이제 작동하지 않습니다. 이전에는 한 세션에서 Agent 도구로 Claude가 생성할 수 있는 [서브에이전트](/docs/ko/sub-agents)의 총 수를 제한했습니다(기본값: 200). 상한을 초과하여 생성하면 `Subagent spawn limit reached`로 실패했습니다. [동시 서브에이전트 제한](/docs/ko/sub-agents#concurrent-subagent-limit) 및 [깊이 제한](/docs/ko/sub-agents#let-subagents-spawn-their-own-subagents)은 여전히 적용됩니다 |320| `CLAUDE_CODE_MAX_MCP_DESCRIPTION_LENGTH` | Claude Code가 모델에 보내는 각 MCP 도구 설명과 각 MCP 서버 지침의 최대 길이(문자 수)입니다(기본값: 2048). Claude Code는 [더 긴 텍스트를 잘라냅니다](/docs/ko/mcp#for-mcp-server-authors). 숫자로 된 양의 정수를 허용합니다. 그 외의 값은 무시되고 기본값이 적용됩니다. Claude Code v2.1.280 이상이 필요합니다 |

321| `CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH` | 주 대화 아래에 허용되는 [서브에이전트 계층](/docs/ko/sub-agents#let-subagents-spawn-their-own-subagents) 수입니다 (기본값: 3). 기본값에서 서브에이전트는 자신의 서브에이전트를 생성할 수 있고, 세 번째 계층의 서브에이전트는 더 이상 생성할 수 없습니다. 중첩을 끄려면 `1`로 설정하세요. v2.1.217부터 v2.1.218까지 기본값은 1이었으므로 제한을 올리지 않으면 서브에이전트가 자신의 것을 생성할 수 없었습니다. v2.1.219는 기본값을 3으로 올렸습니다. 일반 숫자로 양의 정수를 허용합니다. 다른 것은 무시되므로 제한을 조정할 수 있지만 제거할 수 없습니다. Claude Code v2.1.217 이상이 필요합니다 |321| `CLAUDE_CODE_MAX_OUTPUT_TOKENS` | 대부분의 요청에 대한 최대 출력 토큰 수를 설정합니다. 기본값과 상한은 모델마다 다릅니다. [최대 출력 토큰](https://platform.claude.com/docs/en/about-claude/models/overview#latest-models-comparison)을 참조하세요. Claude Code는 모델의 상한을 초과하는 값을 상한으로 낮춥니다. Claude Code가 알고 있는 모델로 확인할 수 없는 모델 ID의 경우 기본값은 32000이고 상한은 128000입니다. 이 값을 늘리면 [자동 압축](/docs/ko/costs#reduce-token-usage)이 트리거되기 전에 사용할 수 있는 유효 컨텍스트 윈도우가 줄어듭니다 |

322| `CLAUDE_CODE_MAX_TOOL_USE_CONCURRENCY` | 병렬로 실행할 수 있는 읽기 전용 도구 및 서브에이전트의 최대 수입니다(기본값: 10). 더 높은 값은 병렬 처리를 증가시키지만 더 많은 리소스를 소비합니다 |322| `CLAUDE_CODE_MAX_RETRIES` | 실패한 API 요청을 재시도하는 횟수를 재정의합니다(기본값: 10). v2.1.186부터 최대 15로 제한됩니다. v2.1.199부터는 `CLAUDE_CODE_RETRY_WATCHDOG`이 기본값을 높이고 상한을 제거합니다. 더 긴 장애 동안 기다려야 하는 무인 세션에는 대신 `CLAUDE_CODE_RETRY_WATCHDOG`을 설정합니다 |

323| `CLAUDE_CODE_MAX_TURNS` | 명시적 제한이 전달되지 않을 때 에이전트 턴 수를 제한합니다. [`--max-turns`](/docs/ko/cli-reference#cli-flags) 전달과 동등합니다. 둘 다 설정되면 플래그가 우선합니다. 양의 정수가 아닌 값은 상한이 없는 것으로 취급하는 대신 시작 시 오류로 거부됩니다 |323| `CLAUDE_CODE_MAX_SUBAGENTS_PER_SESSION` | v2.1.224에서 제거되어 현재는 아무 효과가 없습니다. 이전에는 Claude가 한 세션에서 Agent 도구로 생성할 수 있는 [서브에이전트](/docs/ko/sub-agents)의 총수를 제한했습니다(기본값: 200). 상한을 넘어 생성하면 `Subagent spawn limit reached`와 함께 실패했습니다. [동시 서브에이전트 제한](/docs/ko/sub-agents#concurrent-subagent-limit)과 [깊이 제한](/docs/ko/sub-agents#let-subagents-spawn-their-own-subagents)은 여전히 적용됩니다 |

324| `CLAUDE_CODE_MAX_WEB_SEARCHES_PER_SESSION` | 한 세션이 만들 수 있는 [WebSearch](/docs/ko/tools-reference#websearch-tool-behavior) 호출의 총 수에 대한 상한입니다(기본값: 200). Claude가 상한에 도달하면, 추가 WebSearch 호출은 이미 수집한 정보로 계속하도록 지시하는 알림을 반환합니다. 상한 없이 양의 정수를 허용합니다. 다른 것은 무시되고 기본값이 적용되므로 상한을 올릴 수 있지만 끌 수 없습니다. Claude Code v2.1.212 이상이 필요합니다 |324| `CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH` | 메인 대화 아래에 허용되는 [서브에이전트 계층](/docs/ko/sub-agents#let-subagents-spawn-their-own-subagents) 수 (기본값: 3)입니다. 기본값에서는 서브에이전트가 자체 서브에이전트를 생성할 수 있으며, 세 번째 계층의 서브에이전트는 더 이상 생성할 수 없습니다. 중첩을 끄려면 `1`로 설정합니다. v2.1.217부터 v2.1.218까지는 기본값이 1이었으므로 제한을 높이지 않으면 서브에이전트가 자체 서브에이전트를 생성할 수 없었습니다. v2.1.219에서 기본값이 3으로 높아졌습니다. 숫자로 된 양의 정수를 허용하며, 그 외의 값은 무시되므로 제한을 조정할 수는 있지만 제거할 수는 없습니다. Claude Code v2.1.217 이상이 필요합니다 |

326| `CLAUDE_CODE_MCP_AUTO_BACKGROUND_MS` | 여전히 실행 중인 MCP 도구 호출이 [백그라운드 작업으로 이동](/docs/ko/mcp#automatic-backgrounding-of-long-tool-calls)하기 전의 경과 시간(밀리초 단위)(기본값: 120000, 또는 2분). 자동 백그라운드 처리를 끄려면 `0`으로 설정하세요. Claude Code v2.1.212 이상이 필요합니다 |326| `CLAUDE_CODE_MAX_TURNS` | 명시적 제한이 전달되지 않을 때 에이전트 턴 수를 제한합니다. [`--max-turns`](/docs/ko/cli-reference#cli-flags)를 전달하는 것과 같으며, 둘 다 설정된 경우 `--max-turns`가 우선합니다. 양의 정수가 아닌 값은 제한 없음으로 처리되지 않고 시작 시 오류와 함께 거부됩니다 |

327| `CLAUDE_CODE_MCP_STARTUP_WAIT_MS` | [비대화형](/docs/ko/headless) 세션의 첫 번째 턴이 여전히 연결 중인 MCP 서버를 기다리는 시간(밀리초 단위)입니다. 기본 [첫 번째 턴 대기](/docs/ko/agent-sdk/mcp#connection-timing) 대신입니다. 설정되면, 대기는 모든 보류 중인 서버를 다룹니다. 대기를 건너뛰려면 `0`으로 설정하세요. [`--permission-prompt-tool`](/docs/ko/cli-reference#cli-flags) 서버는 값에 관계없이 자신의 `MCP_TIMEOUT` 대기를 유지합니다. Claude Code v2.1.274 이상이 필요합니다 |327| `CLAUDE_CODE_MAX_WEB_SEARCHES_PER_SESSION` | 한 세션에서 수행할 수 있는 [WebSearch](/docs/ko/tools-reference#websearch-tool-behavior) 호출의 총수 상한입니다(기본값: 200). Claude가 상한에 도달하면 이후 WebSearch 호출은 이미 수집한 정보로 계속 진행하라는 알림을 반환합니다. 상한이 없는 양의 정수를 허용합니다. 그 외의 값은 무시되고 기본값이 적용되므로 상한을 높일 수는 있지만 끌 수는 없습니다. Claude Code v2.1.212 이상이 필요합니다 |

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

329| `CLAUDE_CODE_MESSAGING_SOCKET` | Claude Code에 의해 설정됩니다. 사용자가 설정하지 않습니다: [수신함 소켓](/docs/ko/cross-session-messaging#the-sessions-inbox-socket)을 바인드하는 세션에서, Claude Code는 소켓을 바인드할 때 해당 소켓의 경로를 훅 및 Bash 명령으로 내보냅니다. 메시징이 켜진 상태로 시작하는 세션에서 Claude Code는 모든 훅이 실행되기 전에 소켓을 바인드합니다. 머신의 다른 세션이 이 경로로 메시지를 전달합니다. 각 세션은 부모에서 상속된 것이 아니라 자신의 소켓을 내보내고, 도착한 메시지는 세션의 [인바운드 제어](/docs/ko/cross-session-messaging#control-inbound-messages)를 통과합니다. 설정 `env` 블록은 이를 설정할 수 없습니다. Claude Code v2.1.224 이상이 필요합니다 |329| `CLAUDE_CODE_MCP_AUTO_BACKGROUND_MS` | 아직 실행 중인 MCP 도구 호출이 [백그라운드 작업으로 이동하기](/docs/ko/mcp#automatic-backgrounding-of-long-tool-calls) 전까지의 경과 시간(밀리초)입니다(기본값: 120000, 즉 2분). 자동 백그라운드 전환을 끄려면 `0`으로 설정합니다. Claude Code v2.1.212 이상이 필요합니다 |

330| `CLAUDE_CODE_MESSAGING_TOKEN` | Claude Code에 의해 설정됩니다. 사용자가 설정하지 않습니다: [수신함 소켓](/docs/ko/cross-session-messaging#the-sessions-inbox-socket)을 바인드하는 세션에서, Claude Code는 이 세션별 토큰을 훅 및 Bash 명령과 함께 `CLAUDE_CODE_MESSAGING_SOCKET`과 함께 내보냅니다. 소켓에 게시하는 스크립트는 `{"type":"auth","token":"<token>"}` 첫 번째 줄로 전송하여 세션에 속함을 증명할 수 있습니다. 기본 Windows에서 Claude Code는 이 줄을 요구하고 유효한 것으로 열지 않는 모든 연결을 닫습니다. [자신의 자식 규칙](/docs/ko/cross-session-messaging#the-sessions-inbox-socket)은 Claude Code가 토큰을 참조할 때를 말합니다. 각 세션은 부모 세션에서 상속된 것이 아니라 자신의 토큰을 내보냅니다. 설정 `env` 블록은 이를 설정할 수 없습니다. Claude Code v2.1.228 이상이 필요합니다 |330| `CLAUDE_CODE_MCP_STARTUP_WAIT_MS` | [비대화형](/docs/ko/headless) 세션의 첫 번째 턴이 아직 연결 중인 MCP 서버를 기다리는 시간(밀리초)으로, 기본 [첫 번째 턴 대기](/docs/ko/agent-sdk/mcp#connection-timing)를 대신합니다. 설정하면 대기는 보류 중인 모든 서버에 적용됩니다. 대기를 건너뛰려면 `0`으로 설정합니다. [`--permission-prompt-tool`](/docs/ko/cli-reference#cli-flags) 서버는 값과 관계없이 자체 `MCP_TIMEOUT` 대기를 유지합니다. Claude Code v2.1.274 이상이 필요합니다 |

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

332| `CLAUDE_CODE_NEW_INIT` | `/init`이 대화형 설정 흐름을 실행하도록 하려면 `1`로 설정하세요. 흐름은 CLAUDE.md, 스킬, 훅을 포함한 생성할 파일을 묻고 코드베이스를 탐색한 후 작성합니다. 이 변수 없이 `/init`은 프롬프트 없이 CLAUDE.md를 자동으로 생성합니다 |332| `CLAUDE_CODE_MESSAGING_SOCKET` | 사용자가 아니라 Claude Code가 설정합니다. [수신함 소켓](/docs/ko/cross-session-messaging#the-sessions-inbox-socket)을 바인딩하는 세션에서 Claude Code는 소켓을 바인딩할 때 해당 소켓의 경로를 훅과 Bash 명령에 내보냅니다. 메시징이 켜진 상태로 시작하는 세션에서는 Claude Code가 훅이 실행되기 전에 소켓을 바인딩합니다. 머신의 다른 세션은 이 경로로 메시지를 전달합니다. 각 세션은 부모로부터 상속된 소켓이 아닌 자체 소켓을 내보내며, 이 소켓으로 도착하는 메시지는 세션의 [인바운드 제어](/docs/ko/cross-session-messaging#control-inbound-messages)를 거칩니다. 설정의 `env` 블록으로는 설정할 수 없습니다. Claude Code v2.1.224 이상이 필요합니다 |

333| `CLAUDE_CODE_NONBLOCKING_STDOUT` | 두 번째 비차단 파일 디스크립터를 통해 터미널 출력을 쓰려면 `1`로 설정하세요. 일시 중지된 tmux 제어 모드 창 또는 정체된 SSH 연결 같이 읽기를 중지하는 터미널이 Claude Code를 세션 중간에 동결할 수 없습니다. macOS, Linux, WSL에서 stdout이 터미널일 때 적용됩니다. Claude Code v2.1.261 이상이 필요합니다 |333| `CLAUDE_CODE_MESSAGING_TOKEN` | 사용자가 아니라 Claude Code가 설정합니다. [수신함 소켓](/docs/ko/cross-session-messaging#the-sessions-inbox-socket)을 바인딩하는 세션에서 Claude Code는 `CLAUDE_CODE_MESSAGING_SOCKET`과 함께 이 세션별 토큰을 훅과 Bash 명령에 내보냅니다. 소켓에 게시하는 스크립트는 첫 번째 줄로 `{"type":"auth","token":"<token>"}`를 보내 해당 세션에 속함을 증명할 수 있습니다. 네이티브 Windows에서는 Claude Code가 이 줄을 요구하며, 유효한 줄로 시작하지 않는 연결은 닫습니다. Claude Code가 토큰을 확인하는 시점은 [자식 프로세스 규칙](/docs/ko/cross-session-messaging#the-sessions-inbox-socket)에 설명되어 있습니다. 각 세션은 부모 세션에서 상속된 토큰이 아닌 자체 토큰을 내보냅니다. 설정의 `env` 블록으로는 설정할 수 없습니다. Claude Code v2.1.228 이상이 필요합니다 |

334| `CLAUDE_CODE_NO_FLICKER` | [전체 화면 렌더링](/docs/ko/fullscreen)을 활성화하려면 `1`로 설정하세요. 깜박임을 줄이고 긴 대화에서 메모리를 평평하게 유지하는 연구 미리보기입니다. [`tui`](/docs/ko/settings-reference#tui) 설정을 재정의합니다. `/tui fullscreen`으로도 전환할 수 있습니다 |334| `CLAUDE_CODE_NATIVE_CURSOR` | 그려진 블록 대신 입력 캐럿 위치에 터미널 자체 커서를 표시하려면 `1`로 설정합니다. 커서는 터미널의 깜박임, 모양, 포커스 설정을 따릅니다 |

335| `CLAUDE_CODE_OAUTH_REFRESH_TOKEN` | Claude.ai 인증을 위한 OAuth 새로 고침 토큰입니다. 설정되면, `claude auth login`은 브라우저를 열지 않고 이 토큰을 직접 교환합니다. `CLAUDE_CODE_OAUTH_SCOPES`가 필요합니다. 자동화된 환경에서 인증을 프로비저닝하는 데 유용합니다 |335| `CLAUDE_CODE_NEW_INIT` | `/init`이 대화형 설정 흐름을 실행하도록 하려면 `1`로 설정합니다. 이 흐름은 코드베이스를 탐색하고 파일을 작성하기 전에 CLAUDE.md, 스킬, 훅 등 어떤 파일을 생성할지 묻습니다. 이 변수가 없으면 `/init`은 묻지 않고 CLAUDE.md를 자동으로 생성합니다 |

336| `CLAUDE_CODE_OAUTH_SCOPES` | 새로 고침 토큰이 발급된 공백으로 구분된 OAuth 범위입니다. 예: `"user:profile user:inference user:sessions:claude_code"`. `CLAUDE_CODE_OAUTH_REFRESH_TOKEN`이 설정되면 필수입니다 |336| `CLAUDE_CODE_NONBLOCKING_STDOUT` | 두 번째 논블로킹 파일 디스크립터를 통해 터미널 출력을 쓰려면 `1`로 설정합니다. 이렇게 하면 일시 중지된 tmux 컨트롤 모드 창이나 멈춘 SSH 연결처럼 읽기를 중단한 터미널이 세션 도중 Claude Code를 멈추게 할 수 없습니다. stdout이 터미널인 경우 macOS, Linux, WSL에 적용됩니다. Claude Code v2.1.261 이상이 필요합니다 |

337| `CLAUDE_CODE_OAUTH_TOKEN` | claude.ai 인증을 위한 OAuth 액세스 토큰입니다. `/login`의 대안입니다. SDK 및 자동화된 환경용입니다. 키체인 저장 자격 증명보다 우선합니다. [`claude setup-token`](/docs/ko/authentication#generate-a-long-lived-token)으로 생성하세요. [`/login`](/docs/ko/authentication#authentication-precedence)을 실행하지 않으면, Claude Code는 전체 세션에 대해 설정한 토큰을 사용합니다. 만료된 토큰을 교체하려면 새 토큰을 생성하고 다시 시작하세요 |337| `CLAUDE_CODE_NO_FLICKER` | 깜박임을 줄이고 긴 대화에서 메모리 사용량을 일정하게 유지하는 리서치 프리뷰인 [전체 화면 렌더링](/docs/ko/fullscreen)을 활성화하려면 `1`로 설정합니다. [`tui`](/docs/ko/settings-reference#tui) 설정을 재정의합니다. `/tui fullscreen`으로 전환할 수도 있습니다 |

338| `CLAUDE_CODE_OPUS_4_6_FAST_MODE_OVERRIDE` | v2.1.160에서 제거되었으며 이제 작동하지 않습니다. 이전에는 [빠른 모드](/docs/ko/fast-mode)를 현재 기본값 대신 Claude Opus 4.6으로 고정했습니다. Opus 4.6은 더 이상 빠른 모드를 지원하지 않습니다 |338| `CLAUDE_CODE_OAUTH_REFRESH_TOKEN` | Claude.ai 인증을 위한 OAuth 새로 고침 토큰입니다. 설정하면 `claude auth login`이 브라우저를 여는 대신 이 토큰을 직접 교환합니다. `CLAUDE_CODE_OAUTH_SCOPES`가 필요합니다. 자동화된 환경에서 인증을 프로비저닝할 때 유용합니다 |

339| `CLAUDE_CODE_OTEL_CONTENT_MAX_LENGTH` | 콘텐츠 보유 OpenTelemetry 속성(모델 응답, 도구 콘텐츠, 시스템 프롬프트, 원본 API 본문)의 최대 길이입니다. 자르기 마커 포함. UTF-16 코드 단위(기본값: 61440, 즉 60KB). 원격 측정 백엔드가 64KB보다 큰 속성 값을 허용하는 경우에만 올리거나, 원격 측정 볼륨을 줄이려면 낮추세요. Claude Code v2.1.214 이상이 필요합니다. [모니터링](/docs/ko/monitoring-usage)을 참조하세요 |339| `CLAUDE_CODE_OAUTH_SCOPES` | 새로 고침 토큰이 발급될 때 사용된, 공백으로 구분된 OAuth 범위입니다(예: `"user:profile user:inference user:sessions:claude_code"`). `CLAUDE_CODE_OAUTH_REFRESH_TOKEN`이 설정된 경우 필요합니다 |

340| `CLAUDE_CODE_OTEL_DIAG_STDERR` | OpenTelemetry 익스포터 진단 오류를 stderr에 쓰려면 `1`로 설정하세요. 기본적으로 이러한 오류는 `--debug`에서만 나타나므로 Prometheus 포트 충돌 같은 잘못 구성된 익스포터는 그렇지 않으면 조용히 실패합니다. Claude Code v2.1.179 이상이 필요합니다. [모니터링](/docs/ko/monitoring-usage)을 참조하세요 |340| `CLAUDE_CODE_OAUTH_TOKEN` | claude.ai 인증을 위한 OAuth 액세스 토큰입니다. SDK 및 자동화된 환경에서 `/login`의 대안입니다. 키체인에 저장된 자격 증명보다 우선합니다. [`claude setup-token`](/docs/ko/authentication#generate-a-long-lived-token)으로 생성합니다. [`/login`](/docs/ko/authentication#authentication-precedence)을 실행하지 않는 한 Claude Code는 세션 전체에서 설정한 토큰을 사용합니다. 만료된 토큰을 교체하려면 새 토큰을 생성하고 다시 시작합니다 |

341| `CLAUDE_CODE_OTEL_FLUSH_TIMEOUT_MS` | 보류 중인 OpenTelemetry 스팬을 플러시하기 위한 타임아웃(밀리초 단위)(기본값: 5000). [모니터링](/docs/ko/monitoring-usage)을 참조하세요 |341| `CLAUDE_CODE_OPUS_4_6_FAST_MODE_OVERRIDE` | v2.1.160에서 제거되어 현재는 아무 효과가 없습니다. 이전에는 [빠른 모드](/docs/ko/fast-mode)를 현재 기본값 대신 Claude Opus 4.6으로 고정했습니다. Opus 4.6은 더 이상 빠른 모드를 지원하지 않습니다 |

342| `CLAUDE_CODE_OTEL_HEADERS_HELPER_DEBOUNCE_MS` | 동적 OpenTelemetry 헤더를 새로 고치기 위한 간격(밀리초 단위)(기본값: 1740000 / 29분). [동적 헤더](/docs/ko/monitoring-usage#dynamic-headers)를 참조하세요 |342| `CLAUDE_CODE_OTEL_CONTENT_MAX_LENGTH` | 콘텐츠를 포함하는 OpenTelemetry 속성(모델 응답, 도구 콘텐츠, 시스템 프롬프트, 원시 API 본문)의 최대 길이로, 잘림 마커를 포함하며 UTF-16 코드 단위로 측정합니다(기본값: 61440, 즉 60KB). 텔레메트리 백엔드가 64KB보다 큰 속성 값을 허용하는 경우에만 늘리거나, 텔레메트리 양을 줄이려면 낮춥니다. Claude Code v2.1.214 이상이 필요합니다. [모니터링](/docs/ko/monitoring-usage)을 참조하세요 |

343| `CLAUDE_CODE_OTEL_SHUTDOWN_TIMEOUT_MS` | 종료 시 OpenTelemetry 익스포터가 완료되기 위한 타임아웃(밀리초 단위)(기본값: 2000). 메트릭이 종료 시 삭제되면 증가시키세요. [모니터링](/docs/ko/monitoring-usage)을 참조하세요 |343| `CLAUDE_CODE_OTEL_DIAG_STDERR` | OpenTelemetry 익스포터의 진단 오류를 stderr에 쓰려면 `1`로 설정합니다. 기본적으로 이러한 오류는 `--debug`를 사용할 때만 표시되므로, 그렇지 않으면 Prometheus 포트 충돌과 같이 잘못 구성된 익스포터가 아무 알림 없이 실패합니다. Claude Code v2.1.179 이상이 필요합니다. [모니터링](/docs/ko/monitoring-usage)을 참조하세요 |

344| `CLAUDE_CODE_PACKAGE_MANAGER_AUTO_UPDATE` | 새 버전을 사용할 수 있을 때 Claude Code가 백그라운드에서 패키지 관리자의 업그레이드 명령을 실행하도록 하려면 `1`로 설정하세요. Homebrew 및 WinGet 설치에 적용됩니다. 다른 패키지 관리자는 업그레이드 명령을 실행하지 않고 계속 표시합니다. [자동 업데이트](/docs/ko/setup#auto-updates)를 참조하세요 |344| `CLAUDE_CODE_OTEL_FLUSH_TIMEOUT_MS` | 보류 중인 OpenTelemetry 스팬을 플러시하기 위한 타임아웃(밀리초)입니다(기본값: 5000). [모니터링](/docs/ko/monitoring-usage)을 참조하세요 |

345| `CLAUDE_CODE_PERFORCE_MODE` | Perforce 인식 쓰기 보호를 활성화하려면 `1`로 설정하세요. 설정되면, Edit, Write, NotebookEdit은 대상 파일이 소유자 쓰기 비트를 부족하면 `p4 edit <file>` 힌트로 실패합니다. Perforce는 `p4 edit`이 열 때까지 동기화된 파일에서 이를 지웁니다. 이는 Claude Code가 Perforce 변경 추적을 우회하지 않도록 방지합니다 |345| `CLAUDE_CODE_OTEL_HEADERS_HELPER_DEBOUNCE_MS` | 동적 OpenTelemetry 헤더를 새로 고치는 간격(밀리초)입니다(기본값: 1740000 / 29분). [동적 헤더](/docs/ko/monitoring-usage#dynamic-headers)를 참조하세요 |

346| `CLAUDE_CODE_PLUGIN_CACHE_DIR` | 플러그인 루트 디렉토리를 재정의합니다. 이름에도 불구하고, 이는 캐시 자체가 아니라 부모 디렉토리를 설정합니다: 마켓플레이스 및 플러그인 캐시는 이 경로 아래의 하위 디렉토리에 있습니다. 기본값은 `~/.claude/plugins`입니다 |346| `CLAUDE_CODE_OTEL_SHUTDOWN_TIMEOUT_MS` | 종료 시 OpenTelemetry 익스포터가 완료되기까지의 타임아웃(밀리초)입니다(기본값: 2000). 종료 시 메트릭이 누락되면 값을 늘립니다. [모니터링](/docs/ko/monitoring-usage)을 참조하세요 |

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

348| `CLAUDE_CODE_PLUGIN_GIT_TIMEOUT_MS` | 플러그인 마켓플레이스를 복제하거나 새로 고치기 위한 타임아웃(밀리초 단위)(기본값: 120000). 큰 리포지토리 또는 느린 네트워크 연결의 경우 이 값을 증가시키세요. [Git 복제 시간 초과](/docs/ko/plugins/troubleshooting#git-clone-timed-out-after-120s)를 참조하세요 |348| `CLAUDE_CODE_PERFORCE_MODE` | Perforce 인식 쓰기 보호를 활성화하려면 `1`로 설정합니다. 설정하면 대상 파일에 소유자 쓰기 비트가 없을 때 Edit, Write, NotebookEdit이 `p4 edit <file>` 힌트와 함께 실패합니다. Perforce는 동기화된 파일에서 `p4 edit`으로 열 때까지 이 비트를 해제합니다. 이를 통해 Claude Code가 Perforce 변경 추적을 우회하는 것을 방지합니다 |

349| `CLAUDE_CODE_PLUGIN_KEEP_MARKETPLACE_ON_FAILURE` | 마켓플레이스 새로 고침이 원격에 도달하거나 인증할 수 없을 때 재복제 시도를 건너뛰고 기존 마켓플레이스 체크아웃을 계속 사용하려면 `1`로 설정하세요. 재복제가 동일한 방식으로 실패하는 오프라인 또는 에어갭 환경에 유용합니다. [마켓플레이스 업데이트가 오프라인 환경에서 계속 실패](/docs/ko/plugins/troubleshooting#marketplace-updates-keep-failing-offline)를 참조하세요 |349| `CLAUDE_CODE_PLUGIN_CACHE_DIR` | 플러그인 루트 디렉터리를 재정의합니다. 이름과 달리 이 변수는 캐시 자체가 아닌 상위 디렉터리를 설정합니다. 마켓플레이스와 플러그인 캐시는 이 경로 아래의 하위 디렉터리에 있습니다. 기본값은 `~/.claude/plugins`입니다 |

350| `CLAUDE_CODE_PLUGIN_PREFER_HTTPS` | GitHub `owner/repo` 단축 소스를 SSH 대신 HTTPS를 통해 복제하려면 `1`로 설정하세요. 플러그인 설치 및 업데이트, `/plugin marketplace add` 및 `update`에 적용됩니다. CI 러너, 컨테이너, 또는 `github.com`에 대해 구성된 SSH 키가 없는 모든 환경에 유용합니다 |350| `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)를 참조하세요 |

351| `CLAUDE_CODE_PLUGIN_SEED_DIR` | 하나 이상의 읽기 전용 플러그인 시드 디렉토리의 경로입니다. Unix에서는 `:`로, Windows에서는 `;`로 구분합니다. 사전 채워진 플러그인 디렉토리를 컨테이너 이미지에 번들로 묶는 데 사용합니다. Claude Code는 시작 시 이러한 디렉토리에서 마켓플레이스를 등록하고 재복제 없이 사전 캐시된 플러그인을 사용합니다. [컨테이너 및 CI에 대한 플러그인 사전 채우기](/docs/ko/plugins/org#seed-containers-and-ci)를 참조하세요 |351| `CLAUDE_CODE_PLUGIN_GIT_TIMEOUT_MS` | 플러그인 마켓플레이스를 복제하거나 새로 고치기 위한 타임아웃(밀리초)입니다(기본값: 120000). 대형 저장소나 느린 네트워크 연결의 경우 이 값을 늘립니다. [Git 복제 시간 초과](/docs/ko/plugins/troubleshooting#git-clone-timed-out-after-120s)를 참조하세요 |

352| `CLAUDE_CODE_POWERSHELL_RESPECT_EXECUTION_POLICY` | PowerShell을 도구 호출, 훅, 상태 줄 명령에 대해 생성할 때 Claude Code가 `-ExecutionPolicy Bypass`를 전달하지 않도록 하려면 `1`로 설정하세요. 대신 머신의 유효한 실행 정책을 존중합니다. 기본적으로 Claude Code는 프로세스 범위에서 실행 정책을 우회하므로 `.ps1` 스크립트 및 모듈 가져오기가 기본 제한 Windows 설치에서 작동합니다. 프로세스 범위 우회는 이 설정에 관계없이 Group Policy `MachinePolicy` 또는 `UserPolicy`를 재정의하지 않습니다 |352| `CLAUDE_CODE_PLUGIN_KEEP_MARKETPLACE_ON_FAILURE` | 마켓플레이스 새로 고침이 원격에 연결하거나 인증할 수 없을 때 재복제 시도를 건너뛰고 기존 마켓플레이스 체크아웃을 계속 사용하려면 `1`로 설정합니다. 재복제가 같은 방식으로 실패할 오프라인 또는 에어갭 환경에서 유용합니다. [오프라인 환경에서 마켓플레이스 업데이트 실패](/docs/ko/plugins/troubleshooting#marketplace-updates-keep-failing-offline)를 참조하세요 |

353| `CLAUDE_CODE_PRINT_BG_WAIT_CEILING_MS` | [비대화형 모드](/docs/ko/headless#background-tasks-at-exit)에서 `-p` 플래그를 사용하는 최종 턴 후 백그라운드 서브에이전트 및 워크플로우를 기다리는 유휴 대기의 상한(밀리초 단위)입니다. 유휴 대기는 Claude가 백그라운드 결과를 처리하기 위해 턴을 취할 때마다 다시 시작됩니다. 기본값: `600000`, 또는 10분. 유휴 대기가 상한에 도달하면, Claude Code는 나머지 백그라운드 작업을 기다리는 것을 중지하고 종료합니다. 무한정 기다리려면 `0`으로 설정하세요. 이 상한은 일반 백그라운드 셸에 적용되는 5초 유예 기간과는 별개입니다. Claude Code v2.1.182 이상이 필요합니다 |353| `CLAUDE_CODE_PLUGIN_PREFER_HTTPS` | GitHub `owner/repo` 축약형 소스를 SSH 대신 HTTPS로 복제하려면 `1`로 설정합니다. 플러그인 설치 및 업데이트와 `/plugin marketplace add` 및 `update`에 적용됩니다. CI 러너, 컨테이너 또는 `github.com`에 대한 SSH 키가 구성되지 않은 모든 환경에서 유용합니다 |

354| `CLAUDE_CODE_PROCESS_WRAPPER` | 자신의 바이너리에서 Claude Code가 시작하는 프로세스를 시작합니다. 예를 들어 [에이전트 보기](/docs/ko/agent-view) 세션을 호스팅하는 백그라운드 서비스. `/opt/corp/launcher` 같은 argv 접두사로 제공되는 기업 런처를 통해 시작합니다. 분리된 백그라운드 서비스가 상속하도록 사용자 또는 [관리 설정](/docs/ko/managed-settings)의 `env` 블록에서 설정하세요. 프로젝트 및 로컬 설정은 이를 설정할 수 없습니다. [`processWrapper` 설정](/docs/ko/settings-reference#processwrapper)과 동등합니다. Claude Code v2.1.210 이상이 필요합니다. 둘 다 설정되면 이 변수가 우선합니다. VS Code 확장은 자신의 `claudeProcessWrapper` 설정을 통해 자신의 런처를 구성합니다. Windows에서는 무시됩니다. [기업 런처 뒤에서 Claude Code 실행](/docs/ko/corporate-launcher)을 참조하세요. 값 형식, 런처가 다루는 것, 런처가 만족해야 하는 계약을 참조하세요. Claude Code v2.1.208 이상이 필요합니다 |354| `CLAUDE_CODE_PLUGIN_SEED_DIR` | 하나 이상의 읽기 전용 플러그인 시드 디렉터리 경로로, Unix에서는 `:`, Windows에서는 `;`로 구분합니다. 미리 채워진 플러그인 디렉터리를 컨테이너 이미지에 번들로 포함할 때 사용합니다. Claude Code는 시작 시 이 디렉터리에서 마켓플레이스를 등록하고 재복제 없이 미리 캐시된 플러그인을 사용합니다. [컨테이너용 플러그인 미리 채우기](/docs/ko/plugins/org#seed-containers-and-ci)를 참조하세요 |

355| `CLAUDE_CODE_PROJECT_DIR_NAME` | `CLAUDE_CONFIG_DIR`과 함께 설정하여 Claude Code가 해당 세션의 대화 기록 및 자동 메모리를 저장하는 `projects/` 디렉토리 이름을 선택합니다. 작업 디렉토리 경로에서 파생된 것 대신입니다. 예를 들어 `CLAUDE_CONFIG_DIR=/srv/tenant-a CLAUDE_CODE_PROJECT_DIR_NAME=work claude`로 시작하면 `/srv/tenant-a/projects/work/` 아래에 저장합니다. `CLAUDE_CONFIG_DIR`이 설정 해제되면 Claude Code는 이 변수를 무시합니다. `claude`를 시작하는 환경에서만 읽습니다. 설정 파일 `env` 블록에서는 읽지 않습니다. [프로젝트 디렉토리 이름 직접 지정](/docs/ko/sessions#name-the-project-directory-yourself)을 참조하세요. Claude Code v2.1.234 이상이 필요합니다 |355| `CLAUDE_CODE_POWERSHELL_RESPECT_EXECUTION_POLICY` | 도구 호출, 훅, 상태줄 명령을 위해 PowerShell을 생성할 때 Claude Code가 `-ExecutionPolicy Bypass`를 전달하지 않고 대신 머신의 유효 실행 정책을 따르도록 하려면 `1`로 설정합니다. 기본적으로 Claude Code는 기본값이 Restricted인 Windows 설치에서도 `.ps1` 스크립트와 모듈 가져오기가 작동하도록 프로세스 범위에서 실행 정책을 우회합니다. 프로세스 범위 우회는 이 설정과 관계없이 그룹 정책 `MachinePolicy` 또는 `UserPolicy`를 재정의하지 않습니다 |

356| `CLAUDE_CODE_PROMPT_CACHE_TTL` | `5m` 또는 `1h`로 설정합니다. Claude Code가 허용하는 유일한 값입니다. 주 대화에 대한 [프롬프트 캐시 TTL](/docs/ko/prompt-caching#cache-lifetime)을 선택합니다: 대화형, `-p`, SDK 턴, 그리고 이들과 함께 인라인으로 실행되는 헬퍼. `promptCacheTtl` 설정 및 `ENABLE_PROMPT_CACHING_1H`보다 우선합니다. `FORCE_PROMPT_CACHING_5M`이 이를 재정의합니다. API는 1시간 캐시 쓰기를 더 높은 속도로 청구합니다. Claude Code v2.1.242 이상이 필요합니다 |356| `CLAUDE_CODE_PRINT_BG_WAIT_CEILING_MS` | `-p` 플래그를 사용하는 [비대화형 모드](/docs/ko/headless#background-tasks-at-exit)에서 마지막 턴 이후 백그라운드 서브에이전트와 워크플로를 유휴 상태로 기다리는 시간의 상한(밀리초)입니다. Claude가 백그라운드 결과를 처리하기 위해 턴을 진행할 때마다 유휴 대기가 다시 시작됩니다. 기본값: `600000`, 즉 10분. 유휴 대기가 상한에 도달하면 Claude Code는 남은 백그라운드 작업을 기다리지 않고 종료합니다. 무기한 기다리려면 `0`으로 설정합니다. 이 상한은 일반 백그라운드 셸에 적용되는 5초 유예 기간과는 별개입니다. Claude Code v2.1.182 이상이 필요합니다 |

357| `CLAUDE_CODE_PROPAGATE_TRACEPARENT` | `ANTHROPIC_BASE_URL`이 사용자 정의 프록시를 가리킬 때 W3C 추적 컨텍스트를 전파하려면 `1`로 설정하세요. 전파는 모델 및 HTTP MCP 요청의 `traceparent` 헤더와 Bash, PowerShell, 훅 서브프로세스의 `TRACEPARENT` 환경 변수를 다룹니다. 기본적으로 전파는 Anthropic API에 직접 연결할 때만 활성화됩니다. v2.1.152에서 추가되었습니다. [추적(베타)](/docs/ko/monitoring-usage#traces-beta)을 참조하세요 |357| `CLAUDE_CODE_PROCESS_WRAPPER` | [에이전트 뷰](/docs/ko/agent-view) 세션을 호스팅하는 백그라운드 서비스처럼 Claude Code가 자체 바이너리에서 시작하는 프로세스를, `/opt/corp/launcher`와 같은 argv 접두사로 지정한 기업용 런처를 통해 실행합니다. 분리된 백그라운드 서비스가 이를 상속하도록 셸 export가 아닌 사용자 설정 또는 [관리형 설정](/docs/ko/managed-settings)의 `env` 블록에 설정합니다. 프로젝트 및 로컬 설정에서는 설정할 수 없습니다. Claude Code v2.1.210 이상이 필요한 [`processWrapper` 설정](/docs/ko/settings-reference#processwrapper)과 동일하며, 둘 다 설정된 경우 이 변수가 우선합니다. VS Code 확장은 자체 `claudeProcessWrapper` 설정을 통해 별도로 런처를 구성합니다. Windows에서는 무시됩니다. 값 형식, 런처가 다루는 범위, 런처가 충족해야 하는 계약은 [기업용 런처 뒤에서 Claude Code 실행하기](/docs/ko/corporate-launcher)를 참조하세요. Claude Code v2.1.208 이상이 필요합니다 |

358| `CLAUDE_CODE_PROVIDER_MANAGED_BY_HOST` | Claude Code를 포함하고 자신을 대신하여 모델 제공자 라우팅을 관리하는 호스트 플랫폼에 의해 설정됩니다. 설정되면, Claude Code는 `CLAUDE_CODE_USE_BEDROCK`, `ANTHROPIC_BASE_URL`, `ANTHROPIC_API_KEY` 같은 설정 파일의 제공자 선택, 엔드포인트, 인증 변수를 무시합니다. 따라서 사용자 설정이 호스트의 라우팅을 재정의할 수 없습니다. Claude Code는 또한 [관리 설정](/docs/ko/managed-settings)의 `model`, `fallbackModel`, `modelOverrides` 같은 모델 선택 키를 무시합니다. 어느 관리 소스가 전달하든 호스트의 모델 구성이 오래된 관리 모델 고정보다 우선합니다. Claude Code는 또한 관리 `env` 블록의 `ANTHROPIC_MODEL` 및 `ANTHROPIC_DEFAULT_*_MODEL` 계열 같은 모델 선택 변수를 무시합니다. 관리 설정의 [`availableModels`](/docs/ko/model-config#restrict-model-selection) 허용 목록은 호스트가 자신의 것을 제공하지 않으면 여전히 적용됩니다. Claude Code는 또한 Amazon Bedrock, Claude Platform on AWS, Google Cloud의 Agent Platform, Microsoft Foundry 같은 타사 제공자에서 그렇지 않으면 적용하는 자동 원격 측정 옵트아웃을 건너뜁니다. 따라서 원격 측정은 표준 `DISABLE_TELEMETRY` 옵트아웃을 따릅니다. [API 제공자별 기본 동작](/docs/ko/data-usage#default-behaviors-by-api-provider)을 참조하세요 |358| `CLAUDE_CODE_PROJECT_DIR_NAME` | `CLAUDE_CONFIG_DIR`과 함께 설정하여, 작업 디렉터리 경로에서 파생된 이름 대신 Claude Code가 해당 세션의 트랜스크립트와 자동 메모리를 저장하는 `projects/` 디렉터리 이름을 선택합니다. 예를 들어 `CLAUDE_CONFIG_DIR=/srv/tenant-a CLAUDE_CODE_PROJECT_DIR_NAME=work claude`로 Claude Code를 시작하면 `/srv/tenant-a/projects/work/` 아래에 저장됩니다. Claude Code는 `CLAUDE_CONFIG_DIR`이 설정되지 않은 경우 이 변수를 무시하며, `claude`를 시작하는 환경에서만 읽고 [설정 파일의 `env` 블록](#in-settings-files)에서는 읽지 않습니다. [프로젝트 디렉터리 이름 직접 지정하기](/docs/ko/sessions#name-the-project-directory-yourself)를 참조하세요. Claude Code v2.1.234 이상이 필요합니다 |

359| `CLAUDE_CODE_PROXY_RESOLVES_HOSTS` | 호출자 대신 프록시가 DNS 확인을 수행하도록 허용하려면 `1`로 설정하세요. 프록시가 호스트 이름 확인을 처리해야 하는 환경에 옵트인합니다 |359| `CLAUDE_CODE_PROMPT_CACHE_TTL` | Claude Code가 허용하는 유일한 값인 `5m` 또는 `1h`로 설정하여 메인 대화, 즉 대화형, `-p`, SDK 턴과 이와 함께 인라인으로 실행되는 헬퍼의 [프롬프트 캐시 TTL](/docs/ko/prompt-caching#cache-lifetime)을 선택합니다. `promptCacheTtl` 설정과 `ENABLE_PROMPT_CACHING_1H`보다 우선하며, `FORCE_PROMPT_CACHING_5M`이 이 변수를 재정의합니다. API는 1시간 캐시 쓰기에 더 높은 요금을 청구합니다. Claude Code v2.1.242 이상이 필요합니다 |

360| `CLAUDE_CODE_REMOTE` | Claude Code가 [클라우드 세션](/docs/ko/claude-code-on-the-web)으로 실행 중일 때 자동으로 `true`로 설정됩니다. 훅 또는 설정 스크립트에서 읽어 클라우드 세션에 있는지 감지합니다 |360| `CLAUDE_CODE_PROPAGATE_TRACEPARENT` | `ANTHROPIC_BASE_URL`이 사용자 지정 프록시를 가리킬 때 W3C 트레이스 컨텍스트를 전파하려면 `1`로 설정합니다. 전파 대상은 모델 및 HTTP MCP 요청의 `traceparent` 헤더와 Bash, PowerShell, 훅 하위 프로세스의 `TRACEPARENT` 환경 변수입니다. 기본적으로 전파는 Anthropic API에 직접 연결된 경우에만 활성화됩니다. v2.1.152에서 추가되었습니다. [트레이스(베타)](/docs/ko/monitoring-usage#traces-beta)를 참조하세요 |

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

362| `CLAUDE_CODE_RESTRICTED` | 세션을 제한된 모드로 시작하려면 `1`로 설정하세요. [`--restricted`](/docs/ko/cli-reference#cli-flags)를 전달하는 것과 동일합니다. Claude Code는 설정 파일의 `env` 블록에서 이 변수를 무시합니다. Claude Code v2.1.248 이상이 필요합니다 |362| `CLAUDE_CODE_PROXY_RESOLVES_HOSTS` | 호출자 대신 프록시가 DNS 확인을 수행하도록 허용하려면 `1`로 설정합니다. 프록시가 호스트 이름 확인을 처리해야 하는 환경을 위한 옵트인 설정입니다 |

363| `CLAUDE_CODE_RESUME_INTERRUPTED_TURN` | 이전 세션이 턴 중간에 끝났으면 자동으로 재개하려면 `1`로 설정하세요. SDK 모드에서 사용되므로 모델이 SDK가 프롬프트를 다시 전송하도록 요구하지 않고 계속됩니다. 이를 끄려면 변수를 설정 해제하거나 `0`으로 설정하세요. v2.1.221 이전에는 Claude Code가 `0` 및 기타 거짓 값을 무시했으므로 비대화형 모드에서 재개를 트리거했고 변수를 설정 해제하는 것이 끄는 유일한 방법이었습니다 |363| `CLAUDE_CODE_REMOTE` | Claude Code가 [클라우드 세션](/docs/ko/claude-code-on-the-web)으로 실행될 때 자동으로 `true`로 설정됩니다. 훅이나 설정 스크립트에서 이 값을 읽어 클라우드 세션 안에 있는지 감지합니다 |

364| `CLAUDE_CODE_RESUME_INTERRUPTED_TURN_MAX_AGE_MS` | 턴 중간에 끝난 세션이 재개 시 자동으로 계속되기 위한 마지막 대화 기록 메시지의 최대 나이(밀리초 단위)입니다. 마지막 메시지가 이 경계보다 오래되면, Claude Code는 `CLAUDE_CODE_RESUME_INTERRUPTED_TURN` 자동 재개 및 `CLAUDE_CODE_RESUME_PROMPT` 계속 메시지를 건너뛰고 세션이 유휴 상태로 시작되므로 명시적으로 계속할 수 있습니다. 설정 해제 또는 `0`은 경계가 없음을 의미합니다. 단, 마지막 요청이 API 오류로 실패한 턴은 해당 오류가 6시간 미만일 때만 재개됩니다. 양수 값은 모든 턴을 경계합니다. 음수 또는 숫자가 아닌 값은 1시간 경계를 적용합니다. 장시간 실행되는 에이전트의 스폰 스크립트는 이를 설정하여 오래된 대화 기록에 대한 재시작이 오래된 프롬프트를 다시 실행하지 않도록 할 수 있습니다. Claude Code는 충돌한 [에이전트 보기](/docs/ko/agent-view) 세션을 재시작할 때 자신이 대화를 상속한 대화형 세션의 1시간 경계를 설정합니다. Claude Code v2.1.211 이상이 필요합니다 |364| `CLAUDE_CODE_REMOTE_SESSION_ID` | [클라우드 세션](/docs/ko/claude-code-on-the-web)에서 현재 세션의 ID로 자동 설정됩니다. 이 값을 읽어 세션 트랜스크립트로 돌아가는 링크를 구성합니다. [출력을 세션에 다시 연결하기](/docs/ko/cloud-environments#link-output-back-to-the-session)를 참조하세요 |

365| `CLAUDE_CODE_RESUME_PROMPT` | `CLAUDE_CODE_RESUME_INTERRUPTED_TURN`이 프롬프트를 다시 전송하는 대신 중단된 턴을 계속할 때 Claude에 전송하는 계속 메시지를 재정의합니다. 또는 `-p`로 [지연된 도구 호출](/docs/ko/hooks#defer-a-tool-call-for-later)을 재개할 때입니다. 기본값은 `Continue from where you left off.`입니다. 빈 문자열은 기본값을 사용합니다 |365| `CLAUDE_CODE_RESTRICTED` | [`--restricted`](/docs/ko/cli-reference#cli-flags)를 전달하는 것과 마찬가지로 세션을 제한 모드로 시작하려면 `1`로 설정합니다. Claude Code는 설정 파일의 `env` 블록에 있는 이 변수를 무시합니다. Claude Code v2.1.248 이상이 필요합니다 |

366| `CLAUDE_CODE_RETRY_WATCHDOG` | 평가 하네스, CI 작업, 원격 작업자 같은 무인 세션에 대해 `1`로 설정하세요. `CLAUDE_CODE_MAX_RETRIES` 시도 후 실패하는 대신 `429` 및 `529` 용량 오류를 무한정 재시도합니다. Claude Code는 표준 속도 요청이 지출 제한 또는 소진된 사용 크레딧을 보고하는 `429`를 받으면 즉시 실패합니다. 예를 들어 [게이트웨이 지출 상한](/docs/ko/errors#spend-limit-reached)에서 재설정되는 것입니다. v2.1.239 이전에는 감시견이 이들을 무한정 재시도했습니다. 빠른 모드 요청의 경우 [속도 제한 처리](/docs/ko/fast-mode#handle-rate-limits)를 참조하세요. 감시견은 시도 사이에 최대 5분까지 백오프하거나 응답이 속도 제한 재설정 시간을 전달할 때까지 백오프합니다. 따라서 사용 제한에 도달한 세션은 남은 창을 기다립니다. v2.1.199 이상에서는 또한 서버 오류, 타임아웃, 끊어진 연결 같은 다른 일시적 오류에 대한 기본 재시도 횟수를 300으로 올립니다. 대략 3시간의 백오프입니다. 그리고 변수를 명시적으로 설정하면 `CLAUDE_CODE_MAX_RETRIES`의 15 상한을 제거합니다. Claude Code v2.1.186 이상이 필요합니다 |366| `CLAUDE_CODE_RESUME_INTERRUPTED_TURN` | 이전 세션이 턴 도중에 종료된 경우 자동으로 재개하려면 `1`로 설정합니다. SDK 모드에서 SDK가 프롬프트를 다시 보내지 않아도 모델이 계속 진행하도록 하는 데 사용됩니다. 이 기능을 끄려면 변수를 설정 해제하거나 `0`으로 설정합니다. v2.1.221 이전에는 Claude Code가 `0` 및 기타 falsy 값을 무시했으므로, `0`으로 설정해도 비대화형 모드에서 재개가 트리거되었고 변수를 설정 해제하는 것만이 이를 끄는 유일한 방법이었습니다 |

367| `CLAUDE_CODE_SAFE_MODE` | 안전 모드로 시작하려면 `1`로 설정하세요: CLAUDE.md, 스킬, 플러그인, 훅, MCP 서버, 사용자 정의 명령 및 에이전트, 출력 스타일, 워크플로우, 사용자 정의 테마, 사용자 정의 키 바인딩, 상태 줄 및 파일 제안 명령, LSP 서버, 자동 메모리는 로드되지 않습니다. 손상된 구성을 문제 해결합니다. 관리 설정 정책은 여전히 적용됩니다. 정책 구성 훅, 상태 줄, 파일 제안 명령 포함. 관리 플러그인, 관리 스킬, 관리 CLAUDE.md, 정책 구성 MCP 서버는 로드되지 않습니다. [`--safe-mode`](/docs/ko/cli-reference#cli-flags) 전달과 동등합니다. 직접 생성된 자식 프로세스는 변수를 상속합니다 |367| `CLAUDE_CODE_RESUME_INTERRUPTED_TURN_MAX_AGE_MS` | 턴 도중에 종료된 세션이 재개 시 자동으로 계속되기 위한 마지막 트랜스크립트 메시지의 최대 경과 시간(밀리초)입니다. 마지막 메시지가 이 한계보다 오래되면 Claude Code는 `CLAUDE_CODE_RESUME_INTERRUPTED_TURN` 자동 재개와 `CLAUDE_CODE_RESUME_PROMPT` 계속 메시지를 건너뛰고, 세션은 유휴 상태로 시작되므로 사용자가 명시적으로 계속해야 합니다. 설정하지 않거나 `0`이면 한계가 없습니다. 단, 마지막 요청이 API 오류로 실패한 턴은 해당 오류가 발생한 지 6시간 미만인 경우에만 재개됩니다. 양수 값은 이러한 턴을 포함한 모든 턴에 한계를 적용하며, 음수 또는 숫자가 아닌 값은 1시간 한계를 적용합니다. 장기 실행 에이전트의 생성 스크립트에서 이 값을 설정하면 오래된 트랜스크립트로 재시작할 때 오래된 프롬프트가 다시 실행되지 않도록 할 수 있습니다. Claude Code는 대화형 세션에서 대화를 상속한 [에이전트 뷰](/docs/ko/agent-view) 세션이 충돌하여 재시작할 때 자체적으로 1시간 한계를 설정합니다. Claude Code v2.1.211 이상이 필요합니다 |

368| `CLAUDE_CODE_SCRIPT_CAPS` | `CLAUDE_CODE_SUBPROCESS_ENV_SCRUB`이 설정되었을 때 세션당 특정 스크립트를 호출할 수 있는 횟수를 제한하는 JSON 객체입니다. 키는 명령 텍스트에 대해 일치하는 부분 문자열입니다. 값은 정수 호출 제한입니다. 예를 들어 `{"deploy.sh": 2}`는 `deploy.sh`를 최대 2번 호출할 수 있습니다. 일치는 부분 문자열 기반이므로 `./scripts/deploy.sh $(evil)` 같은 셸 확장 트릭도 상한에 대해 계산됩니다. `xargs` 또는 `find -exec`을 통한 런타임 팬아웃은 감지되지 않습니다. 이는 심층 방어 제어입니다 |368| `CLAUDE_CODE_RESUME_PROMPT` | `CLAUDE_CODE_RESUME_INTERRUPTED_TURN`이 프롬프트를 다시 보내는 대신 중단된 턴을 계속할 때, 또는 `-p`로 [지연된 도구 호출](/docs/ko/hooks#defer-a-tool-call-for-later)을 재개할 때 Claude Code가 Claude에 보내는 계속 메시지를 재정의합니다. 기본값은 `Continue from where you left off.`입니다. 빈 문자열을 지정하면 기본값이 사용됩니다 |

369| `CLAUDE_CODE_SCROLL_SPEED` | [전체 화면 렌더링](/docs/ko/fullscreen#mouse-wheel-scrolling)에서 마우스 휠 스크롤 배수를 설정합니다. `0.5` 같은 1 미만의 분수 값을 포함하여 1에서 20까지의 양수 값을 허용합니다. 터미널이 이미 휠 이벤트를 증폭하는 가속 트랙패드 및 휠 스크롤을 느리게 합니다. 터미널이 노치당 하나의 휠 이벤트를 증폭 없이 전송하면 `3`으로 설정하여 `vim`과 일치시킵니다. JetBrains IDE 터미널에서는 무시됩니다. Claude Code는 자신의 스크롤 처리를 사용합니다 |369| `CLAUDE_CODE_RETRY_WATCHDOG` | eval 하니스, CI 작업, 원격 워커와 같은 무인 세션에서는 `1`로 설정합니다. `429` 및 `529` 용량 오류를 `CLAUDE_CODE_MAX_RETRIES`회 시도 후 실패하는 대신 무기한 재시도합니다. 표준 속도 요청이 지출 한도나 소진된 사용량 크레딧을 보고하는 `429`를 받으면, 일정에 따라 재설정되는 [게이트웨이 지출 상한](/docs/ko/errors#spend-limit-reached)에서 온 경우라도 Claude Code는 즉시 실패합니다. v2.1.239 이전에는 watchdog이 이를 무기한 재시도했습니다. 빠른 모드 요청의 경우 [속도 제한 처리](/docs/ko/fast-mode#handle-rate-limits)를 참조하세요. watchdog은 시도 사이에 최대 5분까지, 또는 응답에 속도 제한 재설정 시간이 포함된 경우 제한이 재설정될 때까지 백오프하므로, 사용 한도에 도달한 세션은 남은 기간 동안 기다립니다. v2.1.199 이상에서는 서버 오류, 타임아웃, 끊어진 연결과 같은 기타 일시적 오류의 기본 재시도 횟수도 300(약 3시간의 백오프)으로 높이고, `CLAUDE_CODE_MAX_RETRIES`를 명시적으로 설정한 경우 15의 상한을 제거합니다. Claude Code v2.1.186 이상이 필요합니다 |

370| `CLAUDE_CODE_SEND_FEEDBACK` | 세션에 대해 [Claude 작성 피드백](/docs/ko/tools-reference#sendfeedback-tool-behavior)을 끄려면 `0`으로 설정하세요. 계정이 이미 액세스 권한을 가진 경우 켜려면 `1`로 설정하세요. 변수는 액세스 권한을 부여할 수 없으며, `DISABLE_FEEDBACK_COMMAND` 및 [`feedbackDrafts`](/docs/ko/settings-reference#feedbackdrafts) 설정의 `off` 값 같은 피드백을 끄는 다른 스위치는 여전히 적용됩니다 |370| `CLAUDE_CODE_SAFE_MODE` | 안전 모드로 시작하려면 `1`로 설정합니다. 안전 모드에서는 손상된 구성의 문제 해결을 위해 CLAUDE.md, 스킬, 플러그인, 훅, MCP 서버, 사용자 지정 명령 및 에이전트, 출력 스타일, 워크플로, 사용자 지정 테마, 사용자 지정 키보드 단축키, 상태줄 및 파일 제안 명령, LSP 서버, 자동 메모리가 로드되지 않습니다. 정책으로 구성된 훅, 상태줄, 파일 제안 명령을 포함한 관리형 설정 정책은 계속 적용되지만, 관리형 플러그인, 관리형 스킬, 관리형 CLAUDE.md, 정책으로 구성된 MCP 서버는 적용되지 않습니다. [`--safe-mode`](/docs/ko/cli-reference#cli-flags)를 전달하는 것과 같습니다. 직접 생성된 자식 프로세스는 이 변수를 상속합니다 |

371| `CLAUDE_CODE_SESSIONEND_HOOKS_TIMEOUT_MS` | [SessionEnd](/docs/ko/hooks#sessionend) 훅의 시간 예산(밀리초 단위)을 재정의합니다. 값은 또한 자신의 `timeout`을 설정하지 않는 각 훅의 타임아웃입니다. 세션 종료, `/clear`, 대화형 `/resume`을 통한 세션 전환에 적용됩니다. 기본적으로 예산은 1.5초입니다. 설정 파일에서 구성된 가장 높은 훅별 `timeout`으로 자동으로 올라갑니다. 최대 60초입니다. 플러그인 제공 훅의 타임아웃은 예산을 올리지 않습니다 |371| `CLAUDE_CODE_SCRIPT_CAPS` | `CLAUDE_CODE_SUBPROCESS_ENV_SCRUB`이 설정된 경우 특정 스크립트를 세션당 호출할 수 있는 횟수를 제한하는 JSON 객체입니다. 키는 명령 텍스트와 대조하는 부분 문자열이고, 값은 정수 호출 제한입니다. 예를 들어 `{"deploy.sh": 2}`는 `deploy.sh`를 최대 두 번까지 호출할 수 있도록 허용합니다. 일치는 부분 문자열 기반이므로 `./scripts/deploy.sh $(evil)`과 같은 셸 확장 트릭도 상한에 포함됩니다. `xargs` 또는 `find -exec`를 통한 런타임 팬아웃은 감지되지 않습니다. 이는 심층 방어 제어입니다 |

372| `CLAUDE_CODE_SESSION_ID` | Bash 및 PowerShell 도구 서브프로세스, [hook 명령](/docs/ko/hooks) 서브프로세스, stdio [MCP 서버](/docs/ko/mcp) 서브프로세스에서 현재 세션 ID로 자동으로 설정됩니다. Bash, PowerShell, 훅의 경우 이는 훅 JSON 입력의 `session_id` 필드와 일치하며 `/clear`에서 업데이트됩니다. MCP 서버 서브프로세스는 생성된 ID를 유지합니다. `--resume <session-id>`에서 재개된 ID를 수신합니다. `--continue` 또는 명시적 ID 없는 `--resume`에서 초기 시작 ID를 대신 수신할 수 있습니다. 스크립트 및 외부 도구를 이를 시작한 Claude Code 세션과 연관시키는 데 사용합니다 |372| `CLAUDE_CODE_SCROLL_SPEED` | [전체 화면 렌더링](/docs/ko/fullscreen#mouse-wheel-scrolling)에서 마우스 휠 스크롤 배율을 설정합니다. 20 이하의 모든 양수 값을 허용하며, 이미 휠 이벤트를 증폭하는 터미널에서 가속된 트랙패드 및 휠 스크롤을 느리게 하기 위한 `0.5`와 같은 1 미만의 소수 값도 포함합니다. 터미널이 증폭 없이 노치당 하나의 휠 이벤트를 보내는 경우 `vim`과 맞추려면 `3`으로 설정합니다. Claude Code가 자체 스크롤 처리를 사용하는 JetBrains IDE 터미널에서는 무시됩니다 |

373| `CLAUDE_CODE_SHELL` | Claude Code가 Bash 도구 명령을 실행하는 데 사용하는 셸을 설정합니다. `/opt/homebrew/bin/bash` 같은 `bash` 또는 `zsh` 바이너리의 경로를 허용합니다. `fish` 같은 다른 셸은 지원되지 않습니다. 값이 작동하는 `bash` 또는 `zsh` 경로가 아니면, Claude Code는 이를 무시하고 자동 감지로 폴백합니다. 자동 감지는 `$SHELL`이 `bash` 또는 `zsh`를 가리킬 때 사용하고, 그렇지 않으면 PATH 및 표준 설치 위치에서 찾은 첫 번째 작동 `zsh`를 선택한 후 `bash`를 선택합니다 |373| `CLAUDE_CODE_SEND_FEEDBACK` | 세션에서 [Claude가 작성하는 피드백](/docs/ko/tools-reference#sendfeedback-tool-behavior)을 끄려면 `0`으로 설정합니다. 계정에 이미 액세스 권한이 있는 경우 켜려면 `1`로 설정합니다. 이 변수 자체로는 액세스 권한을 부여할 수 없으며, `DISABLE_FEEDBACK_COMMAND` 및 [`feedbackDrafts`](/docs/ko/settings-reference#feedbackdrafts) 설정의 `off` 값과 같이 피드백을 끄는 다른 스위치는 계속 적용됩니다 |

374| `CLAUDE_CODE_SHELL_PREFIX` | Claude Code가 생성하는 셸 명령을 래핑하는 명령 접두사입니다: Bash 도구 호출, [훅](/docs/ko/hooks) 명령, [상태 줄](/docs/ko/statusline) 명령, stdio [MCP 서버](/docs/ko/mcp) 시작 명령. PowerShell 훅 및 exec 형식 훅은 접두사 없이 실행됩니다. 로깅 또는 감사에 유용합니다. `/path/to/logger.sh` 같은 단순 실행 파일 경로를 설정하면 각 명령을 `/path/to/logger.sh '<command>'`로 실행합니다. 래퍼는 `$1`에서 명령줄을 단일 셸 인용 인수로 수신하므로 래퍼는 `exec bash -c "$1"` 같이 `$1`을 다시 평가해야 합니다. `$1`을 단순 실행 파일 경로로 취급하면 `npx -y <package>` 같은 인수를 전달하는 stdio MCP 서버가 손상됩니다. Bash 도구 호출의 경우 `$1`은 Claude Code가 조립하는 전체 셸 호출을 포함합니다. 실행한 명령만이 아닙니다 |374| `CLAUDE_CODE_SESSIONEND_HOOKS_TIMEOUT_MS` | [SessionEnd](/docs/ko/hooks#sessionend) 훅의 시간 예산(밀리초)을 재정의합니다. 이 값은 자체 `timeout`을 설정하지 않은 각 훅의 타임아웃이기도 합니다. 세션 종료, `/clear`, 대화형 `/resume`을 통한 세션 전환에 적용됩니다. 기본적으로 예산은 1.5초이며, 설정 파일에 구성된 가장 높은 훅별 `timeout`까지 최대 60초로 자동으로 늘어납니다. 플러그인이 제공하는 훅의 타임아웃은 예산을 늘리지 않습니다 |

375| `CLAUDE_CODE_SIMPLE` | 최소 시스템 프롬프트 및 Bash, 파일 읽기, 파일 편집 도구만으로 실행하려면 `1`로 설정하세요. `--mcp-config`의 MCP 도구는 여전히 사용 가능합니다. 훅, 스킬, 사용자 정의 명령, 서브에이전트, 설치된 플러그인, MCP 서버, 자동 메모리, CLAUDE.md의 자동 검색을 비활성화합니다. `--add-dir`로 전달하는 디렉토리의 스킬은 여전히 로드됩니다. OAuth 토큰 및 키체인 자격 증명은 읽지 않으므로 Anthropic 인증은 `ANTHROPIC_API_KEY` 또는 `--settings`의 `apiKeyHelper`에서 와야 합니다. [`--bare`](/docs/ko/headless#start-faster-with-bare-mode)를 전달하는 것과 동등합니다 |375| `CLAUDE_CODE_SESSION_ID` | Bash 및 PowerShell 도구 하위 프로세스, [훅 명령](/docs/ko/hooks) 하위 프로세스, stdio [MCP 서버](/docs/ko/mcp) 하위 프로세스에서 현재 세션 ID로 자동 설정됩니다. Bash, PowerShell, 훅의 경우 이 값은 훅 JSON 입력의 `session_id` 필드와 일치하며 `/clear` 시 업데이트됩니다. MCP 서버 하위 프로세스는 생성될 때의 ID를 유지합니다. `--resume <session-id>`에서는 재개된 ID를 받아 훅 및 Bash와 일치합니다. 명시적 ID 없이 `--continue` 또는 `--resume`을 사용하면 대신 초기 시작 ID를 받을 수 있습니다. 스크립트 및 외부 도구를 이를 실행한 Claude Code 세션과 연관시키는 데 사용합니다 |

376| `CLAUDE_CODE_SIMPLE_SYSTEM_PROMPT` | 모든 모델에서 더 짧은 시스템 프롬프트 및 축약된 도구 설명을 사용하려면 `1`로 설정하세요. 실험 또는 서버 구성이 그렇지 않으면 활성화할 때에도 옵트아웃하려면 `0`, `false`, `no`, 또는 `off`로 설정하세요. 전체 도구 집합, 훅, MCP 서버, CLAUDE.md 검색은 활성화된 상태로 유지됩니다 |376| `CLAUDE_CODE_SHELL` | Claude Code가 Bash 도구 명령을 실행하는 데 사용하는 셸을 설정합니다. `bash` 또는 `zsh` 바이너리 경로를 허용합니다(예: `/opt/homebrew/bin/bash`). `fish`와 같은 다른 셸은 지원되지 않습니다. 값이 작동하는 `bash` 또는 `zsh` 경로가 아니면 Claude Code는 이를 무시하고 자동 감지로 폴백합니다. 자동 감지는 `$SHELL`이 `bash` 또는 `zsh`를 가리키면 이를 사용하고, 그렇지 않으면 `PATH`와 표준 설치 위치에서 찾은 첫 번째로 작동하는 `zsh`, 그다음 `bash`를 선택합니다 |

377| `CLAUDE_CODE_SKIP_ANTHROPIC_AWS_AUTH` | [Claude Platform on AWS](/docs/ko/claude-platform-on-aws)에 대한 클라이언트 측 인증을 건너뛰세요. 게이트웨이가 자신이 요청에 서명하는 경우 |377| `CLAUDE_CODE_SHELL_PREFIX` | Claude Code가 생성하는 셸 명령을 감싸는 명령 접두사로, Bash 도구 호출, [훅](/docs/ko/hooks) 명령, [상태줄](/docs/ko/statusline) 명령, stdio [MCP 서버](/docs/ko/mcp) 시작 명령에 적용됩니다. PowerShell 훅과 exec 형식 훅은 접두사 없이 실행됩니다. 로깅이나 감사에 유용합니다. `/path/to/logger.sh`와 같은 단순 실행 파일 경로를 설정하면 각 명령이 `/path/to/logger.sh '<command>'`로 실행됩니다. 래퍼는 명령줄을 `$1`에 셸 인용된 단일 인수로 받으므로, 래퍼는 `exec bash -c "$1"`과 같이 셸로 `$1`을 다시 평가해야 합니다. `$1`을 단순 실행 파일 경로로 취급하면 `npx -y <package>`와 같은 인수를 전달하는 stdio MCP 서버가 작동하지 않습니다. Bash 도구 호출의 경우 `$1`에는 Claude가 실행한 명령뿐 아니라 환경 설정을 포함하여 Claude Code가 조립한 전체 셸 호출이 포함됩니다 |

378| `CLAUDE_CODE_SKIP_AWS_CRED_CACHE` | AWS 기본 자격 증명 제공자 체인의 인프로세스 캐시를 끄려면 `1`로 설정하세요. Claude Code는 모든 API 요청에서 체인을 확인합니다. 캐시가 꺼져 있으면, SSO 지원 프로필은 모든 요청에서 IAM Identity Center에 자격 증명을 요청합니다. [자격 증명 캐싱 및 확인 타임아웃](/docs/ko/amazon-bedrock#credential-caching-and-resolution-timeout)을 참조하세요. Claude Code v2.1.207 이상이 필요합니다 |378| `CLAUDE_CODE_SIMPLE` | 최소한의 시스템 프롬프트와 Bash, 파일 읽기, 파일 편집 도구만으로 실행하려면 `1`로 설정합니다. `--mcp-config`의 MCP 도구는 계속 사용할 수 있습니다. 훅, 스킬, 사용자 지정 명령, 서브에이전트, 설치된 플러그인, MCP 서버, 자동 메모리, CLAUDE.md의 자동 검색을 비활성화합니다. `--add-dir`로 전달한 디렉터리의 스킬은 계속 로드됩니다. OAuth 토큰과 키체인 자격 증명을 읽지 않으므로 Anthropic 인증은 `ANTHROPIC_API_KEY` 또는 `--settings`의 `apiKeyHelper`에서 제공되어야 합니다. [`--bare`](/docs/ko/headless#start-faster-with-bare-mode)를 전달하는 것과 같습니다 |

379| `CLAUDE_CODE_SKIP_BEDROCK_AUTH` | Amazon Bedrock에 대한 AWS 인증을 건너뛰세요(예: LLM 게이트웨이 사용 시) |379| `CLAUDE_CODE_SIMPLE_SYSTEM_PROMPT` | 모든 모델에서 더 짧은 시스템 프롬프트와 축약된 도구 설명을 사용하려면 `1`로 설정합니다. 실험이나 서버 구성으로 활성화되는 모델에서도 사용하지 않으려면 `0`, `false`, `no`, `off`로 설정합니다. 전체 도구 세트, 훅, MCP 서버, CLAUDE.md 검색은 활성화된 상태로 유지됩니다 |

380| `CLAUDE_CODE_SKIP_FAST_MODE_NETWORK_ERRORS` | 네트워크가 확인의 직접 요청을 `api.anthropic.com`으로 차단할 때 실패한 [빠른 모드](/docs/ko/fast-mode#use-fast-mode-behind-proxies-and-llm-gateways) 가용성 확인을 사용 가능한 것으로 취급하려면 `1`로 설정하세요. Claude Code는 여전히 "조직에서 비활성화됨" 응답을 존중합니다 |380| `CLAUDE_CODE_SKIP_ANTHROPIC_AWS_AUTH` | 요청에 직접 서명하는 게이트웨이를 위해 [Claude Platform on AWS](/docs/ko/claude-platform-on-aws)의 클라이언트 측 인증을 건너뜁니다 |

381| `CLAUDE_CODE_SKIP_FAST_MODE_ORG_CHECK` | 프록시가 확인의 요청을 가로채는 경우 클라이언트 측 [빠른 모드](/docs/ko/fast-mode#use-fast-mode-behind-proxies-and-llm-gateways) 가용성 확인을 건너뛰려면 `1`로 설정하세요. API는 조직이 빠른 모드를 비활성화했을 때 빠른 모드 요청을 여전히 거부합니다 |381| `CLAUDE_CODE_SKIP_AWS_CRED_CACHE` | AWS 기본 자격 증명 공급자 체인에서 확인한 자격 증명의 프로세스 내 캐시를 끄려면 `1`로 설정합니다. 이렇게 하면 Claude Code가 API 요청마다 체인을 확인합니다. 캐시가 꺼져 있으면 SSO 기반 프로필이 요청마다 IAM Identity Center에 자격 증명을 요청합니다. [자격 증명 캐싱 및 확인 타임아웃](/docs/ko/amazon-bedrock#credential-caching-and-resolution-timeout)을 참조하세요. Claude Code v2.1.207 이상이 필요합니다 |

382| `CLAUDE_CODE_SKIP_FOUNDRY_AUTH` | Microsoft Foundry에 대한 Azure 인증을 건너뛰세요. 프록시 또는 게이트웨이가 자신의 `Authorization` 헤더를 주입하는 경우입니다. Claude Code는 Azure 자격 증명 없이 요청을 전송하고 `ANTHROPIC_CUSTOM_HEADERS`를 통해 제공하는 것 같은 제공하는 `Authorization` 헤더를 보존합니다. `ANTHROPIC_FOUNDRY_API_KEY` 또는 `ANTHROPIC_FOUNDRY_AUTH_TOKEN`이 설정되면 무시됩니다. v2.1.203 이전에는 이 변수가 API 키도 설정되지 않으면 Microsoft Foundry 클라이언트가 요청을 전송할 수 없게 남겨두었습니다 |382| `CLAUDE_CODE_SKIP_BEDROCK_AUTH` | Amazon Bedrock에 대한 AWS 인증을 건너뜁니다(예: LLM 게이트웨이를 사용하는 경우) |

383| `CLAUDE_CODE_SKIP_MANTLE_AUTH` | Amazon Bedrock Mantle에 대한 AWS 인증을 건너뛰세요(예: LLM 게이트웨이 사용 시) |383| `CLAUDE_CODE_SKIP_FAST_MODE_NETWORK_ERRORS` | 확인 요청이 `api.anthropic.com`에 직접 연결하는 것을 차단하는 네트워크를 위해, 실패한 [빠른 모드](/docs/ko/fast-mode#use-fast-mode-behind-proxies-and-llm-gateways) 가용성 확인을 사용 가능한 것으로 처리하려면 `1`로 설정합니다. Claude Code는 "disabled by your organization" 응답은 계속 따릅니다 |

384| `CLAUDE_CODE_SKIP_PROMPT_HISTORY` | 프롬프트 기록 및 세션 대화 기록을 디스크에 쓰지 않으려면 `1`로 설정하세요. 이 변수로 시작된 세션은 `--resume`, `--continue`, 위쪽 화살표 기록에 나타나지 않습니다. 임시 스크립트 세션에 유용합니다 |384| `CLAUDE_CODE_SKIP_FAST_MODE_ORG_CHECK` | 확인 요청을 거부하는 대신 가로채는 프록시를 위해 클라이언트 측 [빠른 모드](/docs/ko/fast-mode#use-fast-mode-behind-proxies-and-llm-gateways) 가용성 확인을 건너뛰려면 `1`로 설정합니다. 조직에서 빠른 모드를 비활성화한 경우 API는 여전히 빠른 모드 요청을 거부합니다 |

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

386| `CLAUDE_CODE_STARTUP_FAILURE_RESULTS` | `--output-format stream-json`으로 시작된 세션이 [Claude Code가 시작을 거부한 이유를 명명하는 결과 메시지](/docs/ko/agent-sdk/typescript#startup_failure_reason)를 작성하도록 하려면 `1`로 설정하세요. 그렇지 않으면 stderr만으로 끝나는 시작 실패의 경우입니다. Claude Code v2.1.274 이상이 필요합니다 |386| `CLAUDE_CODE_SKIP_MANTLE_AUTH` | Amazon Bedrock Mantle에 대한 AWS 인증을 건너뜁니다(예: LLM 게이트웨이를 사용하는 경우) |

387| `CLAUDE_CODE_STOP_HOOK_BLOCK_CAP` | [Stop](/docs/ko/hooks#stop) 또는 [SubagentStop](/docs/ko/hooks#subagentstop) 훅이 턴 종료를 차단할 수 있는 최대 연속 횟수입니다(기본값: 8). 그 후 Claude Code는 이를 재정의하고 턴을 어쨌든 종료합니다. 훅이 합법적으로 더 많은 반복이 필요하면 `0`으로 설정하여 상한을 비활성화하거나 이를 올리세요 |387| `CLAUDE_CODE_SKIP_MODEL_ACCESS_MEMORY` | [Amazon Bedrock](/docs/ko/amazon-bedrock) 및 [Google Cloud의 Agent Platform](/docs/ko/google-vertex-ai)의 [시작 모델 확인](/docs/ko/amazon-bedrock#startup-model-checks)은 계정에서 호출할 수 없는 것으로 확인된 모델을 이 머신에 최대 하루 동안 기억합니다. 이 기억 기능을 끄려면 `1`로 설정합니다. Claude Code v2.1.285 이상이 필요합니다 |

388| `CLAUDE_CODE_SUBAGENT_MODEL` | [서브에이전트](/docs/ko/sub-agents#choose-a-model), [에이전트 팀](/docs/ko/agent-teams#specify-teammates-and-models) 팀원, [워크플로우](/docs/ko/workflows) 에이전트의 기본 모델입니다. 다른 방식으로 할당되지 않은 경우입니다. `haiku` 같은 별칭 또는 전체 모델 이름을 허용합니다. 두 소스가 우선합니다: Claude가 에이전트를 생성할 때 전달하는 모델, 에이전트 정의의 `model` 필드(예: `inherit` 포함). 이를 변경하려면 [`CLAUDE_CODE_SUBAGENT_MODEL_FORCE`](/docs/ko/sub-agents#run-every-subagent-on-one-model)를 설정하세요. [모델 선택](/docs/ko/sub-agents#choose-a-model)에서 전체 순서를 참조하세요. `inherit`로 설정하는 것은 설정 해제하는 것과 동일합니다. v2.1.251 이전에는 이 변수가 호출별 모델과 정의의 `model` 필드를 모두 재정의했습니다 |388| `CLAUDE_CODE_SKIP_PROMPT_HISTORY` | 프롬프트 기록과 세션 트랜스크립트를 디스크에 쓰지 않으려면 `1`로 설정합니다. 이 변수를 설정한 상태로 시작한 세션은 `--resume`, `--continue` 또는 위쪽 화살표 기록에 나타나지 않습니다. 임시 스크립트 세션에 유용합니다 |

389| `CLAUDE_CODE_SUBAGENT_MODEL_FORCE` | 서브에이전트, 팀원, 워크플로우 에이전트에 하나의 모델을 강제하려면 `1`로 설정하세요. [모든 서브에이전트를 하나의 모델에서 실행](/docs/ko/sub-agents#run-every-subagent-on-one-model)은 어느 모델인지 말합니다. Claude Code v2.1.257 이상이 필요합니다 |389| `CLAUDE_CODE_SKIP_VERTEX_AUTH` | Google Cloud의 Agent Platform에 대한 Google 인증을 건너뜁니다(예: LLM 게이트웨이를 사용하는 경우) |

390| `CLAUDE_CODE_SUBAGENT_PROMPT_CACHE_TTL` | `5m` 또는 `1h`로 설정합니다. Claude Code가 허용하는 유일한 값입니다. [서브에이전트](/docs/ko/sub-agents), 워크플로우, 백그라운드 작업 같은 주 대화 외부의 요청에 대한 [프롬프트 캐시 TTL](/docs/ko/prompt-caching#cache-lifetime)을 선택합니다. `subagentPromptCacheTtl` 설정 및 `ENABLE_PROMPT_CACHING_1H`보다 우선합니다. `FORCE_PROMPT_CACHING_5M`이 이를 재정의합니다. API는 1시간 캐시 쓰기를 더 높은 속도로 청구합니다. Claude Code v2.1.242 이상이 필요합니다 |390| `CLAUDE_CODE_STARTUP_FAILURE_RESULTS` | `--output-format stream-json`으로 시작한 세션이, 원래는 stderr 출력만으로 끝나는 시작 실패에 대해 [Claude Code가 시작을 거부한 이유를 알려주는 결과 메시지](/docs/ko/agent-sdk/typescript#startup_failure_reason)를 쓰도록 하려면 `1`로 설정합니다. Claude Code v2.1.274 이상이 필요합니다 |

391| `CLAUDE_CODE_SUBPROCESS_ENV_SCRUB` | 서브프로세스 환경에서 자격 증명을 제거하려면 `1`로 설정하세요(Bash 도구, 훅, MCP stdio 서버): Anthropic 및 클라우드 제공자 자격 증명, Claude Code가 자격 증명으로 인식하는 다른 변수, 패키지 레지스트리 URL에 포함된 자격 증명. 부모 Claude 프로세스는 API 호출을 위해 이러한 자격 증명을 유지하지만 자식 프로세스는 읽을 수 없습니다. 셸 확장을 통해 비밀을 유출하려는 프롬프트 주입 공격에 대한 노출을 줄입니다. v2.1.251 이상에서는 스크럽이 또한 Claude Code의 자신의 구성 저장소 포인터 변수(예: `CLAUDE_CONFIG_DIR`)를 제거합니다. 자식 프로세스가 재배치된 구성 디렉토리를 찾을 수 없습니다. 서브프로세스가 이러한 변수를 필요로 하면 스크럽을 설정 해제하세요. Linux에서는 또한 Bash 서브프로세스를 격리된 PID 네임스페이스에서 실행하므로 `/proc`을 통해 호스트 프로세스 환경을 읽을 수 없습니다. 부작용으로 `ps`, `pgrep`, `kill`은 호스트 프로세스를 보거나 신호할 수 없습니다. `claude-code-action`은 `allowed_non_write_users`가 구성되었을 때 자동으로 이를 설정합니다 |391| `CLAUDE_CODE_STOP_HOOK_BLOCK_CAP` | Claude Code가 이를 재정의하고 턴을 종료하기 전에 [Stop](/docs/ko/hooks#stop) 또는 [SubagentStop](/docs/ko/hooks#subagentstop) 훅이 턴 종료를 연속으로 차단할 수 있는 최대 횟수입니다(기본값: 8). 상한을 비활성화하려면 `0`으로 설정합니다. 훅이 해결하는 데 정당하게 더 많은 반복이 필요한 경우 이 값을 늘립니다 |

392| `CLAUDE_CODE_SYNC_PLUGIN_INSTALL` | 비대화형 모드(`-p` 플래그)에서 첫 번째 쿼리 전에 플러그인 설치가 완료될 때까지 기다리려면 `1`로 설정하세요. 없으면 플러그인이 백그라운드에서 설치되고 첫 번째 턴에서 사용할 수 없을 수 있습니다. `CLAUDE_CODE_SYNC_PLUGIN_INSTALL_TIMEOUT_MS`와 결합하여 대기를 경계하세요 |392| `CLAUDE_CODE_SUBAGENT_MODEL` | 다른 방법으로 모델이 지정되지 않은 [서브에이전트](/docs/ko/sub-agents#choose-a-model), [에이전트 팀](/docs/ko/agent-teams#specify-teammates-and-models) 팀원, [워크플로](/docs/ko/workflows) 에이전트의 기본 모델입니다. `haiku`와 같은 별칭이나 전체 모델 이름을 허용합니다. 두 가지 소스가 이 값보다 우선합니다. Claude가 에이전트를 생성할 때 전달하는 모델과, `inherit`을 포함한 에이전트 정의의 `model` 필드입니다. 이를 변경하려면 [`CLAUDE_CODE_SUBAGENT_MODEL_FORCE`](/docs/ko/sub-agents#run-every-subagent-on-one-model)를 설정합니다. 전체 순서는 [모델 선택](/docs/ko/sub-agents#choose-a-model)을 참조하세요. `inherit`으로 설정하는 것은 설정하지 않는 것과 같습니다. v2.1.251 이전에는 이 변수가 호출별 모델과 정의의 `model` 필드를 모두 재정의했습니다 |

393| `CLAUDE_CODE_SYNC_PLUGIN_INSTALL_TIMEOUT_MS` | 동기 플러그인 설치의 타임아웃(밀리초 단위)입니다. 초과되면, Claude Code는 플러그인 없이 진행하고 오류를 기록합니다. 기본값 없음: 이 변수 없이 동기 설치는 완료될 때까지 기다립니다 |393| `CLAUDE_CODE_SUBAGENT_MODEL_FORCE` | 서브에이전트, 팀원, 워크플로 에이전트에 하나의 모델을 강제로 적용하려면 `1`로 설정합니다. 어떤 모델이 적용되는지는 [모든 서브에이전트를 하나의 모델로 실행하기](/docs/ko/sub-agents#run-every-subagent-on-one-model)에서 설명합니다. Claude Code v2.1.257 이상이 필요합니다 |

394| `CLAUDE_CODE_SYNC_SKILLS` | 비대화형 모드(`-p` 플래그)에서 Claude Code가 계정에 대해 활성화된 스킬을 다운로드하고 `CLAUDE_CODE_SYNC_SKILLS_WAIT_TIMEOUT_MS`까지 목록을 기다리도록 하려면 `1`로 설정하세요. 다운로드 자체는 백그라운드에서 완료되고, Claude는 스킬을 호출할 때 해당 스킬의 다운로드를 기다립니다. claude.ai 인증이 필요합니다. claude.ai 계정에 로그인하는 터미널 세션은 [이러한 스킬을 다운로드](/docs/ko/skills#where-synced-skills-load)하여 `~/.claude/skills/synced/`로 이동하고 이 변수 없이 약 10분마다 재동기화합니다. `-p` 실행이 첫 번째 쿼리에서 현재 스킬을 필요로 할 때만 설정하세요. v2.1.273 이전에는 터미널 세션이 이 변수로 설정된 `-p` 실행에서만 다운로드했습니다. `synced` 폴더 이름은 [이 다운로드를 위해 예약됩니다](/docs/ko/skills#where-skills-live). v2.1.227 이전에는 스킬이 `~/.claude/skills/`로 직접 다운로드되었습니다. Claude Code는 [다운로드된 스킬에 추가 규칙을 적용합니다](/docs/ko/skills#how-synced-skills-behave). 예를 들어 머신에서 `!` 명령을 실행하지 않습니다 |394| `CLAUDE_CODE_SUBAGENT_PROMPT_CACHE_TTL` | Claude Code가 허용하는 유일한 값인 `5m` 또는 `1h`로 설정하여 [서브에이전트](/docs/ko/sub-agents), 워크플로, 백그라운드 작업과 같이 메인 대화 외부의 요청에 대한 [프롬프트 캐시 TTL](/docs/ko/prompt-caching#cache-lifetime)을 선택합니다. `subagentPromptCacheTtl` 설정과 `ENABLE_PROMPT_CACHING_1H`보다 우선하며, `FORCE_PROMPT_CACHING_5M`이 이 변수를 재정의합니다. API는 1시간 캐시 쓰기에 더 높은 요금을 청구합니다. Claude Code v2.1.242 이상이 필요합니다 |

395| `CLAUDE_CODE_SYNC_SKILLS_INSTALL_TIMEOUT_MS` | 앱이 [Agent SDK](/docs/ko/agent-sdk/typescript#query-object)를 기반으로 스킬을 다시 로드할 때 실행되는 스킬 재동기화의 타임아웃(밀리초 단위)(기본값: 30000). 초과되면, 재로드는 도착한 스킬로 계속되고 나머지 다운로드는 백그라운드에서 완료됩니다 |395| `CLAUDE_CODE_SUBPROCESS_ENV_SCRUB` | 하위 프로세스 환경(Bash 도구, 훅, MCP stdio 서버)에서 자격 증명을 제거하려면 `1`로 설정합니다. 제거 대상은 Anthropic 및 클라우드 공급자 자격 증명, Claude Code가 자격 증명으로 인식하는 기타 모든 변수, 패키지 레지스트리 URL에 포함된 자격 증명입니다. 상위 Claude 프로세스는 API 호출을 위해 이러한 자격 증명을 유지하지만 자식 프로세스는 이를 읽을 수 없으므로, 셸 확장을 통해 비밀을 유출하려는 프롬프트 인젝션 공격에 대한 노출이 줄어듭니다. v2.1.251 이상에서는 Claude Code 자체 구성 저장소 포인터 변수(예: `CLAUDE_CONFIG_DIR`)도 제거하므로 자식 프로세스가 재배치된 구성 디렉터리를 찾을 수 없습니다. 하위 프로세스에 이러한 변수가 필요하면 이 변수를 설정하지 않은 상태로 둡니다. Linux에서는 Bash 하위 프로세스를 격리된 PID 네임스페이스에서 실행하여 `/proc`를 통해 호스트 프로세스 환경을 읽을 수 없게 합니다. 부작용으로 `ps`, `pgrep`, `kill`이 호스트 프로세스를 보거나 신호를 보낼 수 없습니다. `claude-code-action`은 `allowed_non_write_users`가 구성되면 이를 자동으로 설정합니다 |

396| `CLAUDE_CODE_SYNC_SKILLS_WAIT_TIMEOUT_MS` | `CLAUDE_CODE_SYNC_SKILLS`가 설정되었을 때 첫 번째 쿼리가 초기 스킬 목록을 기다리는 타임아웃(밀리초 단위)(기본값: 5000). 초과되면, 첫 번째 쿼리는 도착한 스킬로 실행됩니다. 다운로드는 어느 쪽이든 백그라운드에서 완료되고, Claude는 스킬을 호출할 때 해당 스킬의 다운로드를 기다립니다 |396| `CLAUDE_CODE_SYNC_PLUGIN_INSTALL` | 비대화형 모드(`-p` 플래그)에서 첫 번째 쿼리 전에 플러그인 설치가 완료될 때까지 기다리려면 `1`로 설정합니다. 이 설정이 없으면 플러그인은 백그라운드에서 설치되며 첫 번째 턴에서 사용하지 못할 수 있습니다. 대기 시간을 제한하려면 `CLAUDE_CODE_SYNC_PLUGIN_INSTALL_TIMEOUT_MS`와 함께 사용합니다 |

397| `CLAUDE_CODE_SYNTAX_HIGHLIGHT` | diff 출력에서 구문 강조를 비활성화하려면 `false`로 설정하세요. 색상이 터미널 설정을 방해할 때 유용합니다. 코드 블록 및 파일 미리보기에서도 강조를 비활성화하려면 [`syntaxHighlightingDisabled`](/docs/ko/settings-reference#syntaxhighlightingdisabled) 설정을 사용하세요 |397| `CLAUDE_CODE_SYNC_PLUGIN_INSTALL_TIMEOUT_MS` | 동기 플러그인 설치의 타임아웃(밀리초)입니다. 초과하면 Claude Code는 플러그인 없이 진행하고 오류를 로그에 기록합니다. 기본값은 없습니다. 이 변수가 없으면 동기 설치는 완료될 때까지 기다립니다 |

398| `CLAUDE_CODE_TASK_LIST_ID` | 세션 전체에서 작업 목록을 공유합니다. 여러 Claude Code 인스턴스에서 동일한 ID를 설정하여 [작업 도구가 있는 세션](/docs/ko/tools-reference#task-tool-availability)에서 공유 작업 목록을 조정합니다. [작업 목록](/docs/ko/interactive-mode#task-list)을 참조하세요 |398| `CLAUDE_CODE_SYNC_SKILLS` | `-p` 플래그를 사용하는 비대화형 모드에서, Claude Code가 해당 실행에서 claude.ai 계정에 활성화된 스킬을 다운로드하고 첫 번째 쿼리를 실행하기 전에 `CLAUDE_CODE_SYNC_SKILLS_WAIT_TIMEOUT_MS`까지 스킬 목록을 기다리도록 하려면 `1`로 설정합니다. 다운로드 자체는 백그라운드에서 완료되며, Claude는 스킬을 호출할 때 해당 스킬의 다운로드를 기다립니다. claude.ai 인증이 필요합니다. claude.ai 계정으로 로그인한 터미널 세션은 이 변수 없이도 이러한 스킬을 `~/.claude/skills/synced/`에 [다운로드하고](/docs/ko/skills#where-synced-skills-load) 약 10분마다 다시 동기화하므로, `-p` 실행의 첫 번째 쿼리에서 현재 스킬이 필요한 경우에만 설정합니다. v2.1.273 이전에는 터미널 세션이 이 변수가 설정된 `-p` 실행에서만 스킬을 다운로드했습니다. `synced` 폴더 이름은 [이 다운로드용으로 예약되어 있습니다](/docs/ko/skills#where-skills-live). v2.1.227 이전에는 스킬이 `~/.claude/skills/`에 직접 다운로드되었습니다. Claude Code는 머신에서 `!` 명령을 실행하지 않는 것과 같이 [다운로드된 스킬에 추가 규칙](/docs/ko/skills#how-synced-skills-behave)을 적용합니다 |

399| `CLAUDE_CODE_TEAM_TEARDOWN_PARK_TIMEOUT_MS` | 비대화형 세션이 [에이전트 팀](/docs/ko/agent-teams)이 종료될 때까지 기다리는 시간(밀리초 단위)을 재정의합니다. 1000에서 60000을 허용합니다. 범위를 벗어난 값은 무시되고 기본값 10000이 적용됩니다. Claude Code v2.1.206 이상이 필요합니다 |399| `CLAUDE_CODE_SYNC_SKILLS_INSTALL_TIMEOUT_MS` | [Agent SDK](/docs/ko/agent-sdk/typescript#query-object)로 빌드된 앱이 스킬을 다시 로드할 때 세션 중에 실행되는 스킬 재동기화의 타임아웃(밀리초)입니다(기본값: 30000). 초과하면 도착한 스킬로 다시 로드가 계속되고, 남은 다운로드는 백그라운드에서 완료됩니다 |

400| `CLAUDE_CODE_TMPDIR` | 내부 임시 파일에 사용되는 임시 디렉토리를 재정의합니다. Claude Code는 Unix에서 `/claude-{uid}/`를 또는 Windows에서 `/claude/`를 이 경로에 추가합니다. 기본값: macOS에서 `/tmp`, Linux 및 Windows에서 `os.tmpdir()`. macOS 및 Linux에서 [샌드박스](/docs/ko/sandboxing) Bash 서브프로세스는 재정의가 긴 경로일 때 시스템 기본값 아래에서 짧은 폴백 `$TMPDIR`을 수신합니다. 일부 도구는 임시 경로가 너무 길 때 실패하기 때문입니다. 샌드박스되지 않은 Bash 명령은 설정되었을 때 셸의 `$TMPDIR`을 상속합니다. Claude Code의 자신의 임시 파일은 항상 재정의를 사용합니다. 셸, 사용자 설정, 관리 설정에서 설정하세요. [프로젝트 및 로컬 설정](/docs/ko/settings-reference#variables-claude-code-ignores-in-env)에서는 무시됩니다 |400| `CLAUDE_CODE_SYNC_SKILLS_WAIT_TIMEOUT_MS` | `CLAUDE_CODE_SYNC_SKILLS`가 설정된 경우 첫 번째 쿼리가 초기 스킬 목록을 기다리는 타임아웃(밀리초)입니다(기본값: 5000). 초과하면 첫 번째 쿼리는 도착한 스킬로 실행됩니다. 어느 경우든 다운로드는 백그라운드에서 완료되며, Claude는 스킬을 호출할 때 해당 스킬의 다운로드를 기다립니다 |

401| `CLAUDE_CODE_TMUX_TRUECOLOR` | tmux 내에서 24비트 트루컬러 출력을 허용하려면 `1` 같은 비어있지 않은 값으로 설정하세요. **`0` 또는 `false`로 설정하면 여전히 트루컬러를 허용합니다**. 대부분의 온/오프 변수와 달리 변수를 설정 해제하여 256색 제한을 복원하세요. 기본적으로 `$TMUX`가 설정되면 Claude Code는 256색으로 제한합니다. tmux는 구성되지 않으면 트루컬러 이스케이프 시퀀스를 통과하지 않기 때문입니다. `~/.tmux.conf`에 `set -ga terminal-overrides ',*:Tc'`를 추가한 후 이를 설정하세요. [터미널 구성](/docs/ko/terminal-config)에서 다른 tmux 설정을 참조하세요 |401| `CLAUDE_CODE_SYNTAX_HIGHLIGHT` | diff 출력에서 구문 강조를 비활성화하려면 `false`로 설정합니다. 색상이 터미널 설정과 충돌할 때 유용합니다. 코드 블록과 파일 미리 보기에서도 강조를 비활성화하려면 [`syntaxHighlightingDisabled`](/docs/ko/settings-reference#syntaxhighlightingdisabled) 설정을 사용합니다 |

402| `CLAUDE_CODE_TOOL_MEMORY_CGROUP_EXCLUDE` | Linux 및 WSL에서, Claude Code가 도구 메모리 상한에서 [제외하는 프로세스 종류](/docs/ko/tools-reference#memory-limit-on-linux-and-wsl)의 쉼표로 구분된 목록입니다. 예: `mcp` 또는 `lsp`. 모든 종류를 제한하려면 `none`으로 설정하거나, Bash, PowerShell, Monitor 도구 명령만 제한하려면 `all-new`로 설정하세요. Claude Code는 어떤 것을 나열하든 Bash, PowerShell, Monitor 도구 명령을 상한 아래로 유지합니다. Claude Code v2.1.246 이상이 필요합니다 |402| `CLAUDE_CODE_TASK_LIST_ID` | 세션 간에 작업 목록을 공유합니다. [Task 도구가 있는 세션](/docs/ko/tools-reference#task-tool-availability)에서 여러 Claude Code 인스턴스에 동일한 ID를 설정하여 공유 작업 목록에서 협업합니다. [작업 목록](/docs/ko/interactive-mode#task-list)을 참조하세요 |

403| `CLAUDE_CODE_TOOL_MEMORY_LIMIT` | Linux 및 WSL에서, [Bash 및 PowerShell 도구 명령이 사용할 수 있는 메모리를 제한](/docs/ko/tools-reference#memory-limit-on-linux-and-wsl)하려면 `4G` 같은 크기로 설정합니다. v2.1.246 이상에서 Monitor 도구 명령입니다. 바이트 수만 또는 `K`, `M`, `G`, `T` 접미사가 있는 일반 숫자로 크기를 작성합니다. 상한을 끄려면 `0` 또는 `off`로 설정하세요. Claude Code가 시작하는 첫 번째 프로세스가 상한을 켜거나 끈 후, 변경된 값은 다음에 `claude`를 시작할 때 적용됩니다. Claude Code v2.1.233 이상이 필요합니다 |403| `CLAUDE_CODE_TEAM_TEARDOWN_PARK_TIMEOUT_MS` | 비대화형 세션이 종료 시 [에이전트 팀](/docs/ko/agent-teams) 해체가 완료될 때까지 기다리는 시간을 밀리초 단위로 재정의합니다. 1000에서 60000까지 허용하며, 범위를 벗어난 값은 무시되고 기본값 10000이 적용됩니다. Claude Code v2.1.206 이상이 필요합니다 |

404| `CLAUDE_CODE_USER_DIALOG_TIMEOUT_MS` | Claude Code가 [Remote Control](/docs/ko/remote-control) 또는 SDK 호스트 같은 원격 클라이언트로 전달하는 대화 상자의 기한(밀리초 단위)입니다. 또는 [보류 중인 교차 세션 메시지](/docs/ko/cross-session-messaging#control-inbound-messages)의 승인 대화 상자입니다. 권한 프롬프트 및 `AskUserQuestion` 질문은 자신의 흐름을 사용하고 이것으로 관리되지 않습니다. Claude Code v2.1.236 이상에서는 또한 무인 상태로 실행될 수 있는 세션의 세션 중간 [Fable 사용 크레딧 동의 프롬프트](/docs/ko/model-config#fable-and-usage-credits)를 경계합니다. [인바운드 메시지 제어](/docs/ko/cross-session-messaging#control-inbound-messages) 및 [비대화형 세션](/docs/ko/cross-session-messaging#non-interactive-sessions)은 기한이 적용되지 않는 경우를 포함한 전체 보류 메시지 만료 규칙을 다룹니다. [`dialogExpiry`](/docs/ko/settings-reference#dialogexpiry) 설정을 재정의합니다. `0` 또는 음수 값은 기한을 비활성화합니다 |404| `CLAUDE_CODE_TMPDIR` | 내부 임시 파일에 사용되는 임시 디렉터리를 재정의합니다. Claude Code는 Unix에서는 이 경로에 `/claude-{uid}/`를, Windows에서는 `/claude/`를 추가합니다. 기본값: macOS에서는 `/tmp`, Linux 및 Windows에서는 `os.tmpdir()`. macOS와 Linux에서 재정의 경로가 긴 경우, 일부 도구는 임시 경로가 너무 길면 실패하므로 [샌드박스가 적용된](/docs/ko/sandboxing) Bash 하위 프로세스는 시스템 기본값 아래의 짧은 대체 `$TMPDIR`을 받습니다. 샌드박스가 적용되지 않은 Bash 명령은 셸의 `$TMPDIR`이 설정된 경우 이를 상속합니다. 네이티브 Windows에서 셸이 `$TMPDIR`을 설정하지 않으면, `$TMPDIR`을 참조하는 Bash 명령은 재정의 값을 받거나, 재정의를 설정하지 않은 경우 `%TEMP%`를 받습니다. Claude Code 자체 임시 파일은 항상 재정의 값을 사용합니다. 셸, 사용자 설정 또는 관리형 설정에서 설정합니다. [프로젝트 및 로컬 설정](/docs/ko/settings-reference#variables-claude-code-ignores-in-env)에서는 무시됩니다 |

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

429| `DEBUG` | 디버그 모드를 활성화하려면 `1`로 설정하세요. [`--debug`](/docs/ko/cli-reference#cli-flags)로 시작하는 것과 동등합니다. 디버그 로그는 `~/.claude/debug/<session-id>.txt` 또는 `CLAUDE_CODE_DEBUG_LOGS_DIR`로 설정된 경로에 기록됩니다. `1`, `true`, `yes`, `on` 같은 참 값만 디버그 모드를 활성화하므로 다른 도구에 대해 설정된 `DEBUG=express:*` 같은 네임스페이스 패턴은 이를 트리거하지 않습니다 |433| `DEBUG` | 디버그 모드를 활성화하려면 `1`로 설정합니다. [`--debug`](/docs/ko/cli-reference#cli-flags)로 실행하는 것과 동일합니다. 디버그 로그는 `~/.claude/debug/<session-id>.txt` 또는 `CLAUDE_CODE_DEBUG_LOGS_DIR`로 설정된 경로에 기록됩니다. 참으로 간주되는 값 `1`, `true`, `yes`, `on`만 디버그 모드를 활성화하므로, 다른 도구를 위해 설정된 `DEBUG=express:*`와 같은 네임스페이스 패턴은 디버그 모드를 트리거하지 않습니다 |

430| `DISABLE_AUTOUPDATER` | 자동 백그라운드 업데이트를 비활성화하려면 `1`로 설정하세요. 수동 `claude update`는 여전히 작동합니다. `DISABLE_UPDATES`를 사용하여 둘 다 차단하세요 |434| `DISABLE_AUTOUPDATER` | 자동 백그라운드 업데이트를 비활성화하려면 `1`로 설정합니다. 수동 `claude update`는 여전히 작동합니다. 둘 다 차단하려면 `DISABLE_UPDATES`를 사용하세요 |

431| `DISABLE_AUTO_COMPACT` | 컨텍스트 제한에 접근할 때 자동 압축을 비활성화하려면 `1`로 설정하세요. 수동 `/compact` 명령은 사용 가능하게 유지됩니다. 압축이 발생할 때 명시적 제어를 원할 때 사용합니다. [`autoCompactEnabled`](/docs/ko/settings-reference#autocompactenabled) 설정을 재정의합니다 |435| `DISABLE_AUTO_COMPACT` | 컨텍스트 한도에 가까워질 때 자동 압축을 비활성화하려면 `1`로 설정합니다. 수동 `/compact` 명령은 계속 사용할 수 있습니다. 압축 시점을 명시적으로 제어하려는 경우에 사용합니다. [`autoCompactEnabled`](/docs/ko/settings-reference#autocompactenabled) 설정을 재정의합니다 |

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

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

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

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

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

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

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

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

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

450| `DISABLE_UPDATES` | 수동 `claude update` 및 `claude install`을 포함한 모든 업데이트를 차단하려면 `1`로 설정하세요. `DISABLE_AUTOUPDATER`보다 더 엄격합니다. 자신의 채널을 통해 Claude Code를 배포하고 사용자가 자동 업데이트하지 않아야 할 때 사용합니다 |454| `DISABLE_UPDATES` | 수동 `claude update` 및 `claude install`을 포함한 모든 업데이트를 차단하려면 `1`로 설정합니다. `DISABLE_AUTOUPDATER`보다 엄격합니다. 자체 채널을 통해 Claude Code를 배포하며 사용자가 직접 업데이트해서는 안 되는 경우에 사용합니다 |

452| `DO_NOT_TRACK` | `DISABLE_TELEMETRY`와 동일한 효과로 원격 측정을 옵트아웃하려면 `1`로 설정하세요. [기능 플래그 가져오기](#features-that-need-feature-flag-fetching)도 포함합니다. Claude Code는 이 변수를 표준 부울로 읽으므로 `0`은 원격 측정을 켜진 상태로 유지하고, 많은 개발자 CLI에서 인식하는 교차 도구 규칙으로 이를 존중합니다 |456| `DO_NOT_TRACK` | 텔레메트리를 거부하려면 `1`로 설정합니다. [기능 플래그 가져오기](#features-that-need-feature-flag-fetching)에 대한 영향을 포함하여 `DISABLE_TELEMETRY`와 동일한 효과를 가집니다. Claude Code는 이 변수를 표준 불리언으로 읽으므로 `0`이면 텔레메트리가 켜진 상태로 유지되며, 여러 개발자 CLI에서 인식하는 도구 간 공통 규칙으로서 이를 준수합니다 |

453| `ENABLE_BETA_TRACING_DETAILED` | `BETA_TRACING_ENDPOINT`와 함께 [상세 베타 추적](/docs/ko/monitoring-usage#traces-beta)을 켜려면 `1`로 설정하세요. 콘텐츠 보유 스팬 속성 및 `claude_code.hook` 스팬을 추가합니다. 대화형 CLI 세션은 또한 조직이 베타에 대해 허용 목록에 있어야 합니다. 두 변수 모두 [프로젝트 및 로컬 설정](/docs/ko/settings-reference#variables-claude-code-ignores-in-env)에서는 무시됩니다 |457| `ENABLE_BETA_TRACING_DETAILED` | `BETA_TRACING_ENDPOINT`와 함께 `1`로 설정하면 [상세 베타 추적](/docs/ko/monitoring-usage#traces-beta)이 켜지며, 콘텐츠를 포함하는 span 속성과 `claude_code.hook` span이 추가됩니다. 대화형 CLI 세션에서는 조직이 베타 허용 목록에 등록되어 있어야 합니다. 두 변수 모두 [프로젝트 및 로컬 설정](/docs/ko/settings-reference#variables-claude-code-ignores-in-env)에서는 무시됩니다 |

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

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

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

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

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

461| `FORCE_PROMPT_CACHING_5M` | 1시간 TTL이 그렇지 않으면 적용될 때에도 5분 프롬프트 캐시 TTL을 강제하려면 `1`로 설정하세요. `CLAUDE_CODE_PROMPT_CACHE_TTL`, `CLAUDE_CODE_SUBAGENT_PROMPT_CACHE_TTL`, `ENABLE_PROMPT_CACHING_1H`, `promptCacheTtl` 및 `subagentPromptCacheTtl` 설정을 재정의합니다 |465| `FORCE_PROMPT_CACHING_5M` | 1시간 TTL이 적용될 경우에도 5분 프롬프트 캐시 TTL을 강제하려면 `1`로 설정합니다. `CLAUDE_CODE_PROMPT_CACHE_TTL`, `CLAUDE_CODE_SUBAGENT_PROMPT_CACHE_TTL`, `ENABLE_PROMPT_CACHING_1H`, 그리고 `promptCacheTtl` 및 `subagentPromptCacheTtl` 설정을 재정의합니다 |

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

465| `MAX_MCP_OUTPUT_TOKENS` | MCP 도구 응답에서 허용되는 최대 토큰 수입니다. Claude Code는 출력이 10,000 토큰을 초과할 때 경고를 표시합니다. [`anthropic/maxResultSizeChars`](/docs/ko/mcp#raise-the-limit-for-a-specific-tool)를 선언하는 도구는 텍스트 콘텐츠에 대해 해당 문자 제한을 사용하지만, 이러한 도구의 이미지 콘텐츠는 여전히 이 변수의 영향을 받습니다(기본값: 25000) |469| `MAX_MCP_OUTPUT_TOKENS` | MCP 도구 응답에 허용되는 최대 토큰 수입니다. 출력이 10,000 토큰을 초과하면 Claude Code가 경고를 표시합니다. [`anthropic/maxResultSizeChars`](/docs/ko/mcp#raise-the-limit-for-a-specific-tool)를 선언하는 도구는 텍스트 콘텐츠에 대해 대신 해당 문자 한도를 사용하지만, 이러한 도구의 이미지 콘텐츠에는 여전히 이 변수가 적용됩니다(기본값: 25000) |

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

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

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

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

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

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

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

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

474| `MCP_DISCOVERY_CACHE_TTL_S` | Claude Code가 새로 고침 없이 [검색 캐시](/docs/ko/mcp#server-status-detail) 항목을 사용하는 시간(초 단위)입니다(기본값: 900). 항목이 이보다 오래되었을 때 시작에서 Claude Code는 여전히 사용하지만 백그라운드에서 새로 고칩니다. 항목이 `MCP_DISCOVERY_CACHE_MAX_STALE_S`보다 오래되었을 때 Claude Code는 버립니다. Claude Code는 값을 `MCP_DISCOVERY_CACHE_MAX_STALE_S`로 제한합니다. 기본값은 4시간입니다. v2.1.238 이전에는 Claude Code가 값을 제한하지 않았습니다 |478| `MCP_DISCOVERY_CACHE_TTL_S` | Claude Code가 [디스커버리 캐시](/docs/ko/mcp#server-status-detail) 항목을 새로 고치지 않고 사용하는 시간(초)입니다(기본값: 900). 항목이 이보다 오래된 상태에서 시작하면 Claude Code는 여전히 해당 항목을 사용하지만 백그라운드에서 새로 고칩니다. 항목이 `MCP_DISCOVERY_CACHE_MAX_STALE_S`보다 오래되면 Claude Code는 대신 해당 항목을 버립니다. Claude Code는 이 값을 기본적으로 4시간인 `MCP_DISCOVERY_CACHE_MAX_STALE_S`로 제한합니다. v2.1.238 이전에는 Claude Code가 값을 제한하지 않았습니다 |

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

476| `MCP_PROTOCOL_NEGOTIATION` | [v2 MCP 클라이언트 런타임](/docs/ko/mcp#mcp-client-runtimes)에서만, Claude Code가 MCP 프로토콜 개정 2026-07-28에 대해 서버를 조사하는지 여부입니다. `auto`로 설정하여 HTTP, claude.ai 커넥터, stdio 서버를 조사합니다. 서버가 조사에 응답하지 않으면 이전 프로토콜에서 연결됩니다. SSE 및 WebSocket 서버는 항상 그렇게 합니다. `legacy`로 설정하여 모든 서버에 대해 조사를 건너뜁니다. 변수 없이 Claude Code는 HTTP 서버를 조사하고, [기능 플래그를 가져오는 세션](/docs/ko/mcp#mcp-client-runtimes)에서 claude.ai 커넥터 서버도 조사합니다. 다른 값은 디버그 로그의 경고로 무시됩니다. Claude Code v2.1.221 이상이 필요합니다 |480| `MCP_PROTOCOL_NEGOTIATION` | [v2 MCP 클라이언트 런타임](/docs/ko/mcp#mcp-client-runtimes)에서만, Claude Code가 서버에 MCP 프로토콜 개정판 2026-07-28을 탐색할지 여부를 지정합니다. HTTP, claude.ai 커넥터 및 stdio 서버를 탐색하려면 `auto`로 설정합니다. 탐색에 응답하지 않는 서버는 SSE 및 WebSocket 서버가 항상 그러하듯 대신 이전 프로토콜로 연결됩니다. 모든 서버에 대해 탐색을 건너뛰려면 `legacy`로 설정합니다. 이 변수가 없으면 Claude Code는 HTTP 서버를 탐색하며, [기능 플래그를 가져오는](#features-that-need-feature-flag-fetching) 세션에서는 claude.ai 커넥터 서버도 탐색합니다. 그 밖의 값은 디버그 로그에 경고를 남기고 무시됩니다. Claude Code v2.1.221 이상이 필요합니다 |

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

512| `VERTEX_REGION_CLAUDE_5_5_SONNET` | Google Cloud의 Agent Platform 사용 시 Claude Sonnet 5.5의 리전을 재정의합니다. v2.1.284에서 추가되었습니다 |516| `VERTEX_REGION_CLAUDE_5_5_SONNET` | Google Cloud's Agent Platform 사용 시 Claude Sonnet 5.5의 리전을 재정의합니다. v2.1.284에서 추가되었습니다 |

~~518~~ 522

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

~~520~~ 524

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

522 526

523<h2 id="features-that-need-feature-flag-fetching">527<h2 id="features-that-need-feature-flag-fetching">

524 기능 플래그 가져오기가 필요한 기능528 기능 플래그 가져오기가 필요한 기능

errors.md +1014 −997

Details

8 8

9이 페이지에는 Claude Code가 표시하는 런타임 오류와 각 오류에서 복구하는 방법, 그리고 오류 없이 응답이 이상해 보일 때 확인할 사항이 나열되어 있습니다. 설정 중 `command not found` 또는 TLS 오류와 같은 설치 오류는 [설치 및 로그인 문제 해결](/docs/ko/troubleshoot-install)을 참조하십시오.9이 페이지에는 Claude Code가 표시하는 런타임 오류와 각 오류에서 복구하는 방법, 그리고 오류 없이 응답이 이상해 보일 때 확인할 사항이 나열되어 있습니다. 설정 중 `command not found` 또는 TLS 오류와 같은 설치 오류는 [설치 및 로그인 문제 해결](/docs/ko/troubleshoot-install)을 참조하십시오.

10 10

11[래퍼 및 IDE 오류](#wrapper-and-ide-errors)를 제외하고, 이는 Claude Code 자체가 아닌 실행 프로그램이 출력하는 오류이며, 이러한 오류 및 복구 명령은 CLI, [데스크톱 앱](/docs/ko/desktop), [웹의 Claude Code](/docs/ko/claude-code-on-the-web)에 모두 적용됩니다. 세 가지 모두 동일한 Claude Code CLI를 래핑하기 때문입니다. 다른 표면별 문제는 해당 표면의 페이지에 있는 문제 해결 섹션을 참조하십시오.11Claude Code 자체가 아닌 실행 프로그램이 출력하는 [래퍼 및 IDE 오류](#wrapper-and-ide-errors)를 제외하면, 이러한 오류와 복구 명령은 CLI, [데스크톱 앱](/docs/ko/desktop), [클라우드 세션](/docs/ko/claude-code-on-the-web)에 모두 적용됩니다. 세 가지 모두 동일한 Claude Code CLI를 래핑하기 때문입니다. 기타 사용 환경별 문제는 해당 사용 환경 페이지의 문제 해결 섹션을 참조하십시오.

12 12

13<Note>13<Note>

14 Claude Code는 모델 응답을 위해 Claude API를 호출하므로 대부분의 런타임 오류는 기본 API 오류 코드에 매핑됩니다. 이 페이지에서는 Claude Code 내에서 각 오류의 의미와 복구 방법을 다룹니다. 원본 HTTP 상태 코드 정의는 [Claude Platform 오류 참조](https://platform.claude.com/docs/en/api/errors)를 참조하십시오.14 Claude Code는 모델 응답을 위해 Claude API를 호출하므로 대부분의 런타임 오류는 기본 API 오류 코드에 매핑됩니다. 이 페이지에서는 Claude Code 내에서 각 오류의 의미와 복구 방법을 다룹니다. 원본 HTTP 상태 코드 정의는 [Claude Platform 오류 참조](https://platform.claude.com/docs/en/api/errors)를 참조하십시오.

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

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

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

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

51| `You've hit your monthly spend limit` / `You've hit your individual spend limit` / `You've hit your org's monthly spend limit` / `You've hit your channel's monthly spend limit` / `You've hit your team's shared budget` / `You've hit your individual usage limit` | [사용 제한](#youve-hit-your-monthly-spend-limit) |51| `You've hit your monthly spend limit` / `You've hit your individual spend limit` / `You've hit your org's monthly spend limit` / `You've hit your channel's monthly spend limit` / `You've hit your team's shared budget` / `You've hit your individual usage limit` | [사용 한도](#youve-hit-your-monthly-spend-limit) |

54| `Not logged in · Please run /login` | [인증](#not-logged-in) |54| `Not logged in · Please run /login` | [인증](#not-logged-in) |

55| `Couldn't save your login` | [인증](#couldnt-save-your-login) |55| `Couldn't save your login` | [인증](#couldnt-save-your-login) |

56| `Authentication required · Sign in again to continue` | [인증](#not-logged-in) |56| `Authentication required · Sign in again to continue` | [인증](#not-logged-in) |

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

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

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

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

250| `Monitor "<name>" from plugin <plugin> references ${user_config.*} in its command` | [플러그인 오류](#plugin-command-references-user-config) |251| `Monitor "<name>" from plugin <plugin> references ${user_config.*} in its command` | [플러그인 오류](#plugin-command-references-user-config) |

251| `headersHelper for MCP server '<name>' references ${user_config.*}` | [플러그인 오류](#plugin-command-references-user-config) |252| `headersHelper for MCP server '<name>' references ${user_config.*}` | [플러그인 오류](#plugin-command-references-user-config) |

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

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

290| `Reading a local file from outside this session's connected folders, or through a link, needs the approval card` | [도구 오류](#reading-a-local-file-from-outside-the-connected-folders) |292| `Reading a local file from outside this session's connected folders, or through a link, needs the approval card` | [도구 오류](#reading-a-local-file-from-outside-the-connected-folders) |

291| `cannot read file_path (...) — the file could not be examined, and no one can answer the approval card` | [도구 오류](#reading-a-local-file-from-outside-the-connected-folders) |293| `cannot read file_path (...) — the file could not be examined, and no one can answer the approval card` | [도구 오류](#reading-a-local-file-from-outside-the-connected-folders) |

295| `The safety check for domain ... is rate-limited` | [도구 오류](#webfetch-domain-safety-check-failed) |

296| `The safety check for domain ... is temporarily rate-limited` | [도구 오류](#webfetch-domain-safety-check-failed) |

297| `Unable to verify if domain ... is safe to fetch` | [도구 오류](#webfetch-domain-safety-check-failed) |

293| `Can't open MCP settings while no terminal is attached to this background session` | [백그라운드 세션 오류](#commands-refused-in-a-background-session) |298| `Can't open MCP settings while no terminal is attached to this background session` | [백그라운드 세션 오류](#commands-refused-in-a-background-session) |

295| `blocked because the path is spelled in a form that cannot be safely resolved` | [백그라운드 세션 오류](#write-or-command-blocked-because-the-path-cannot-be-safely-resolved) |300| `blocked because the path is spelled in a form that cannot be safely resolved` | [백그라운드 세션 오류](#write-or-command-blocked-because-the-path-cannot-be-safely-resolved) |

323| `Transcript saving is off — CLAUDE_CODE_SKIP_PROMPT_HISTORY is set` | [세션 저장 경고](#transcript-saving-is-off-skip-prompt-history) |328| `Transcript saving is off — CLAUDE_CODE_SKIP_PROMPT_HISTORY is set` | [세션 저장 경고](#transcript-saving-is-off-skip-prompt-history) |

324| `Transcript saving is off — inherited CLAUDE_CODE_CHILD_SESSION marker` | [세션 저장 경고](#transcript-saving-is-off-child-session-marker) |329| `Transcript saving is off — inherited CLAUDE_CODE_CHILD_SESSION marker` | [세션 저장 경고](#transcript-saving-is-off-child-session-marker) |

325| `Claude Code's fullscreen renderer didn't finish starting last time on this machine` / `Claude Code's fullscreen renderer has repeatedly failed to start on this machine` | [구성 경고](#fullscreen-failed-start-notice) |330| `Claude Code's fullscreen renderer didn't finish starting last time on this machine` / `Claude Code's fullscreen renderer has repeatedly failed to start on this machine` | [전체 화면 렌더링](/docs/ko/fullscreen#fullscreen-renderer-didnt-finish-starting) |

326| `Claude Code exited after an unrecoverable interface error (...)` | [구성 경고](#exited-after-an-unrecoverable-interface-error) |331| `Claude Code exited after an unrecoverable interface error (...)` | [구성 경고](#exited-after-an-unrecoverable-interface-error) |

328| `Not loaded: rename <path>, then restart — its name uses "<name>", a name reserved for the skills synced from your claude.ai account` | [구성 경고](#a-skill-command-or-workflow-wasnt-loaded-because-its-name-is-reserved) |333| `Not loaded: rename <path>, then restart — its name uses "<name>", a name reserved for the skills synced from your claude.ai account` | [구성 경고](#a-skill-command-or-workflow-wasnt-loaded-because-its-name-is-reserved) |

415 서버 오류420 서버 오류

416</h2>421</h2>

417 422

418이러한 오류의 대부분은 추론 제공자에서 발생합니다: Anthropic API의 Anthropic 서비스, Amazon Bedrock의 해당 제공자 엔드포인트 뒤의 서비스, Google Cloud의 Agent Platform, Microsoft Foundry 또는 사용자 정의 게이트웨이입니다. [자동 모드가 작업의 안전성을 결정할 수 없음](#auto-mode-cannot-determine-the-safety-of-an-action) 및 [API 오류로 인해 에이전트가 조기에 종료됨](#agent-terminated-early-due-to-an-api-error)은 또한 사용자 측의 원인을 다룹니다. 예를 들어 분류자 모델을 호출할 수 없는 Amazon Bedrock 계정이나 사용 한도에 도달한 하위 에이전트입니다.423이러한 오류의 대부분은 추론 제공자에서 발생합니다: Anthropic API의 Anthropic 서비스, Amazon Bedrock의 해당 제공자 엔드포인트 뒤의 서비스, Google Cloud의 Agent Platform, Microsoft Foundry 또는 사용자 정의 게이트웨이입니다. [자동 모드가 작업의 안전성을 결정할 수 없음](#auto-mode-cannot-determine-the-safety-of-an-action) 및 [API 오류로 인해 에이전트가 조기에 종료됨](#agent-terminated-early-due-to-an-api-error)은 또한 사용자 측의 원인을 다룹니다. 예를 들어 분류기 모델을 호출할 수 없는 Amazon Bedrock 계정이나 사용 한도에 도달한 서브에이전트입니다.

419 424

420<h3 id="api-error-500-internal-server-error">425<h3 id="api-error-500-internal-server-error">

421 API 오류: 500 내부 서버 오류426 API 오류: 500 내부 서버 오류

457 462

458* [status.claude.com](https://status.claude.com) 또는 메시지에 명시된 제공자 상태 페이지에서 용량 공지를 확인합니다463* [status.claude.com](https://status.claude.com) 또는 메시지에 명시된 제공자 상태 페이지에서 용량 공지를 확인합니다

459* 몇 분 후에 다시 시도합니다464* 몇 분 후에 다시 시도합니다

460* `/model`을 실행하고 다른 모델로 전환하여 계속 작업합니다. 용량은 모델별로 추적되기 때문입니다. Claude Code는 한 모델이 특히 높은 부하를 받을 때 이를 수행하도록 프롬프트합니다. 예를 들어 `Opus is experiencing high load, please use /model to switch to Sonnet`입니다. Fable 모델에서 메시지는 Fable을 명시합니다.465* `/model`을 실행하고 다른 모델로 전환하여 계속 작업합니다. 용량은 모델별로 추적되기 때문입니다. Claude Code는 한 모델이 특히 높은 부하를 받을 때 모델 전환을 요청합니다. 예를 들어 `Opus is experiencing high load, please use /model to switch to Sonnet`입니다. Fable 모델에서 메시지는 Fable을 명시합니다.

461 466

462 Claude Desktop 앱이 실행하는 세션(예: Code 탭 또는 Cowork)에서 메시지는 `Opus is experiencing high load. Switch to Sonnet.`으로 읽히며 앱의 모델 선택기로 모델을 전환합니다.467 Claude Desktop 앱이 실행하는 세션(예: Code 탭 또는 Cowork)에서 메시지는 `Opus is experiencing high load. Switch to Sonnet.`으로 읽히며 앱의 모델 선택기로 모델을 전환합니다.

463 468

471Request timed out476Request timed out

472```477```

473 478

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

475 480

476**수행할 작업:**481**수행할 작업:**

477 482

483 API에서 응답 없음488 API에서 응답 없음

484</h3>489</h3>

485 490

486Claude Code가 스트리밍 요청을 보냈고 API가 첫 바이트의 마감 시간 내에 응답 헤더를 반환하지 않아 Claude Code가 전체 `API_TIMEOUT_MS` 요청 시간 초과(기본값 10분)를 기다리는 대신 요청을 중단했습니다. Claude Code는 [재시도 예산](#tune-retry-behavior)이 허용하는 경우 최대 한 번 요청을 다시 보냅니다. 재시도도 응답이 없을 때 턴이 이 메시지로 끝나며, 각 시도가 대기한 시간을 표시합니다. [`CLAUDE_CODE_RETRY_WATCHDOG`](/docs/ko/env-vars)을 설정하면 일회 재시도 상한이 적용되지 않으며 Claude Code는 [재시도 동작 조정](#tune-retry-behavior)에 설명된 예산 내에서 재시도합니다.491Claude Code가 스트리밍 요청을 보냈고 API가 첫 바이트의 마감 시간 내에 응답 헤더를 반환하지 않아 Claude Code가 전체 `API_TIMEOUT_MS` 요청 타임아웃(기본값 10분)을 기다리는 대신 요청을 중단했습니다. Claude Code는 [재시도 예산](#tune-retry-behavior)이 허용하는 경우 최대 한 번 요청을 다시 보냅니다. 재시도도 응답이 없을 때 턴이 이 메시지로 끝나며, 각 시도가 대기한 시간을 표시합니다. [`CLAUDE_CODE_RETRY_WATCHDOG`](/docs/ko/env-vars)을 설정하면 일회 재시도 상한이 적용되지 않으며 Claude Code는 [재시도 동작 조정](#tune-retry-behavior)에 설명된 예산 내에서 재시도합니다.

487 492

488```text theme={null}493```text theme={null}

489API Error: No response from API (waited 3m, then 10m on the retry). If a proxy or gateway on your network holds responses until they complete, raise API_TIMEOUT_MS or CLAUDE_STREAM_FIRST_BYTE_TIMEOUT_MS to wait longer.494API Error: No response from API (waited 3m, then 10m on the retry). If a proxy or gateway on your network holds responses until they complete, raise API_TIMEOUT_MS or CLAUDE_STREAM_FIRST_BYTE_TIMEOUT_MS to wait longer.

491 496

492Claude Code는 첫 시도의 응답 헤더 대기와 재시도의 대기를 별도로 설정합니다:497Claude Code는 첫 시도의 응답 헤더 대기와 재시도의 대기를 별도로 설정합니다:

493 498

494* **첫 시도**: 1 이상으로 설정할 때 [`CLAUDE_STREAM_FIRST_BYTE_TIMEOUT_MS`](/docs/ko/env-vars), 10초에서 30분 사이로 제한됩니다. 그렇지 않으면 Claude Code는 [스트리밍 유휴 감시자](/docs/ko/network-config#streaming-idle-watchdogs)에 나열된 바이트 수준 감시자 시간 초과를 사용하므로 해당 시간 초과를 변경하는 변수가 이 대기도 변경합니다. 어느 쪽이든 Claude Code는 요청 본문의 32KB마다 1초를 추가합니다.499* **첫 시도**: 1 이상으로 설정할 때 [`CLAUDE_STREAM_FIRST_BYTE_TIMEOUT_MS`](/docs/ko/env-vars), 10초에서 30분 사이로 제한됩니다. 그렇지 않으면 Claude Code는 [스트리밍 유휴 감시자](/docs/ko/network-config#streaming-idle-watchdogs)에 나열된 바이트 수준 감시자 타임아웃을 사용하므로 해당 타임아웃을 변경하는 변수가 이 대기도 변경합니다. 어느 쪽이든 Claude Code는 요청 본문의 32KB마다 1초를 추가합니다.

495* **재시도**: `API_TIMEOUT_MS`보다 1초 적게, 기본값으로 거의 10분이므로 재시도가 응답을 생성이 완료될 때까지 보유하는 프록시 또는 게이트웨이를 초과할 수 있습니다. Amazon Bedrock에서 재시도는 첫 시도와 동일한 마감 시간을 사용하며 메시지는 두 가지 대신 하나의 기간을 표시합니다.500* **재시도**: `API_TIMEOUT_MS`보다 1초 적게, 기본값으로 거의 10분이므로 재시도가 응답을 생성이 완료될 때까지 보유하는 프록시 또는 게이트웨이를 초과할 수 있습니다. Amazon Bedrock에서 재시도는 첫 시도와 동일한 마감 시간을 사용하며 메시지는 두 가지 대신 하나의 기간을 표시합니다.

496 501

497어느 대기도 양수 `API_TIMEOUT_MS`보다 1초 적게 초과하지 않으며, 11초 미만의 양수 `API_TIMEOUT_MS`는 마감 시간을 끕니다. 바이트 수준 감시자는 응답 헤더가 도착한 후에만 시작되므로 그 후 바이트 전송을 중지하는 응답은 이 마감 시간 대신 [정지된 스트림 규칙](#automatic-retries)을 따릅니다.502어느 대기도 양수 `API_TIMEOUT_MS`보다 1초 적은 값을 초과하지 않으며, 11초 미만의 양수 `API_TIMEOUT_MS`는 마감 시간을 끕니다. 바이트 수준 감시자는 응답 헤더가 도착한 후에만 시작되므로 그 후 바이트 전송을 중지하는 응답은 이 마감 시간 대신 [정지된 스트림 규칙](#automatic-retries)을 따릅니다.

498 503

499**수행할 작업:**504**수행할 작업:**

500 505

503* 네트워크의 프록시 또는 게이트웨이가 응답을 생성이 완료될 때까지 보유하는 경우 `API_TIMEOUT_MS`를 높여 재시도가 더 오래 대기하도록 합니다. Amazon Bedrock에서 `CLAUDE_STREAM_FIRST_BYTE_TIMEOUT_MS`도 높입니다.508* 네트워크의 프록시 또는 게이트웨이가 응답을 생성이 완료될 때까지 보유하는 경우 `API_TIMEOUT_MS`를 높여 재시도가 더 오래 대기하도록 합니다. Amazon Bedrock에서 `CLAUDE_STREAM_FIRST_BYTE_TIMEOUT_MS`도 높입니다.

504* 첫 시도가 계속 시간 초과되고 재시도가 성공하면 `CLAUDE_STREAM_FIRST_BYTE_TIMEOUT_MS`를 높여 첫 시도도 충분히 오래 대기하도록 합니다.509* 첫 시도가 계속 시간 초과되고 재시도가 성공하면 `CLAUDE_STREAM_FIRST_BYTE_TIMEOUT_MS`를 높여 첫 시도도 충분히 오래 대기하도록 합니다.

505 510

506v2.1.242 이전에는 Claude Code가 응답 없는 스트리밍 요청이 실패하기 전에 전체 `API_TIMEOUT_MS` 요청 시간 초과(기본값 10분)를 기다렸습니다. v2.1.261 이전에는 재시도가 첫 시도와 동일한 마감 시간을 기다렸고 메시지는 기간을 표시하지 않았습니다.511v2.1.242 이전에는 Claude Code가 응답 없는 스트리밍 요청이 실패하기 전에 전체 `API_TIMEOUT_MS` 요청 타임아웃(기본값 10분)을 기다렸습니다. v2.1.261 이전에는 재시도가 첫 시도와 동일한 마감 시간을 기다렸고 메시지는 기간을 표시하지 않았습니다.

507 512

508<h3 id="the-response-above-may-be-incomplete">513<h3 id="the-response-above-may-be-incomplete">

509 위의 응답이 불완전할 수 있음514 위의 응답이 불완전할 수 있음

510</h3>515</h3>

511 516

512스트리밍 요청이 응답이 진행 중일 때 실패했습니다. Claude가 텍스트 블록 또는 도구 호출을 완료한 후 또는 생각을 마친 후 하나를 시작했습니다. 요청을 다시 보내면 동일한 도구 호출을 두 번 실행할 수 있으므로 Claude Code는 Claude가 완료한 출력을 유지하고 턴을 버리는 대신 이 공지를 추가합니다. 표시되는 변형은 원인을 명시합니다:517스트리밍 요청이 응답이 진행 중일 때 실패했습니다. Claude가 텍스트 블록 또는 도구 호출을 완료한 후 또는 사고를 마친 후 하나를 시작했습니다. 요청을 다시 보내면 동일한 도구 호출을 두 번 실행할 수 있으므로 Claude Code는 Claude가 완료한 출력을 유지하고 턴을 버리는 대신 이 공지를 추가합니다. 표시되는 변형은 원인을 명시합니다:

513 518

514```text theme={null}519```text theme={null}

515API Error: Server error mid-response. The response above may be incomplete.520API Error: Server error mid-response. The response above may be incomplete.

524* `Connection lost mid-response`: 연결이 끊어졌습니다. 프록시 또는 게이트웨이가 응답이 완료되기 전에 응답 본문을 깔끔하게 종료할 때도 이 변형이 표시됩니다.529* `Connection lost mid-response`: 연결이 끊어졌습니다. 프록시 또는 게이트웨이가 응답이 완료되기 전에 응답 본문을 깔끔하게 종료할 때도 이 변형이 표시됩니다.

525* `Your computer went to sleep mid-response`: Claude Code가 응답이 스트리밍되는 동안 컴퓨터가 절전 모드로 전환되었음을 감지했습니다. 컴퓨터가 깨어나면 Claude Code는 연결을 끊어진 것으로 취급하고 읽기를 중지합니다.530* `Your computer went to sleep mid-response`: Claude Code가 응답이 스트리밍되는 동안 컴퓨터가 절전 모드로 전환되었음을 감지했습니다. 컴퓨터가 깨어나면 Claude Code는 연결을 끊어진 것으로 취급하고 읽기를 중지합니다.

526* `Part of the response never arrived`: 스트림 이벤트가 API와 Claude Code 사이에서 손실되어 나중 이벤트가 도착하지 않은 콘텐츠를 참조했습니다. v2.1.281 이전에는 이 경우 턴이 `API Error: Content block not found`로 종료되었습니다.531* `Part of the response never arrived`: 스트림 이벤트가 API와 Claude Code 사이에서 손실되어 나중 이벤트가 도착하지 않은 콘텐츠를 참조했습니다. v2.1.281 이전에는 이 경우 턴이 `API Error: Content block not found`로 종료되었습니다.

527* `The response stream was malformed`: 이미 완료된 콘텐츠 블록에 대한 이벤트가 도착했거나 손상된 이벤트가 도착했습니다. 손상된 이벤트는 데이터가 유효한 JSON이 아니거나 콘텐츠가 누락되었거나 콘텐츠가 이벤트의 유형과 일치하지 않는 이벤트입니다. v2.1.284 이전에는 파서의 원본 오류(예: `API Error: JSON Parse error`로 시작하는 오류)가 Claude가 생각, 텍스트 블록 또는 도구 호출을 완료한 후 유효하지 않은 JSON이 있는 이벤트가 도착했을 때 대신 나타났습니다.532* `The response stream was malformed`: 이미 완료된 콘텐츠 블록에 대한 이벤트가 도착했거나 손상된 이벤트가 도착했습니다. 손상된 이벤트는 데이터가 유효한 JSON이 아니거나 콘텐츠가 누락되었거나 콘텐츠가 이벤트의 유형과 일치하지 않는 이벤트입니다. v2.1.284 이전에는 파서의 원본 오류(예: `API Error: JSON Parse error`로 시작하는 오류)가 Claude가 사고, 텍스트 블록 또는 도구 호출을 완료한 후 유효하지 않은 JSON이 있는 이벤트가 도착했을 때 대신 나타났습니다. v2.1.287 이전에는 [Amazon Bedrock 가드레일](/docs/ko/amazon-bedrock#aws-guardrails)이 이미 사고와 일부 텍스트를 스트리밍한 응답을 차단했을 때 가드레일의 메시지 대신 이 변형이 나타났습니다.

528* `The response stopped arriving`: 연결은 열려 있었지만 데이터 전달을 중지했으므로 스트리밍 유휴 감시자가 중단했습니다. v2.1.222 이전에는 Claude Code가 `ANTHROPIC_BASE_URL` 또는 `ANTHROPIC_AWS_BASE_URL`을 통해 도달한 [게이트웨이](/docs/ko/gateways) 연결에서 서버의 킵얼라이브 핑이 여전히 도착하는 동안 이 실패를 보고할 수 있었습니다. 파싱된 응답 이벤트만 계산했기 때문입니다. 업그레이드하면 해당 경로에서 이러한 거짓 시간 초과를 중지합니다. `ANTHROPIC_BEDROCK_BASE_URL`과 같은 제공자 기본 URL을 통해 도달한 게이트웨이는 바이트 감시자로 래핑되지 않습니다. [스트리밍 유휴 감시자](/docs/ko/network-config#streaming-idle-watchdogs)를 참조하세요.533* `The response stopped arriving`: 연결은 열려 있었지만 데이터 전달을 중지했으므로 스트리밍 유휴 감시자가 중단했습니다. v2.1.222 이전에는 Claude Code가 `ANTHROPIC_BASE_URL` 또는 `ANTHROPIC_AWS_BASE_URL`을 통해 도달한 [게이트웨이](/docs/ko/gateways) 연결에서 서버의 킵얼라이브 핑이 여전히 도착하는 동안 이 실패를 보고할 수 있었습니다. 파싱된 응답 이벤트만 계산했기 때문입니다. 업그레이드하면 해당 경로에서 이러한 거짓 시간 초과를 중지합니다. `ANTHROPIC_BEDROCK_BASE_URL`과 같은 제공자 기본 URL을 통해 도달한 게이트웨이는 바이트 감시자로 래핑되지 않습니다. [스트리밍 유휴 감시자](/docs/ko/network-config#streaming-idle-watchdogs)를 참조하세요.

529 534

530v2.1.227 이전에는 `Connection lost mid-response`가 `Connection closed mid-response`로 읽혔고 `The response stopped arriving`이 `Response stalled mid-stream`으로 읽혔습니다.535v2.1.227 이전에는 `Connection lost mid-response`가 `Connection closed mid-response`로 읽혔고 `The response stopped arriving`이 `Response stalled mid-stream`으로 읽혔습니다.

531 536

532Claude가 텍스트 또는 도구 호출을 시작하기 전에 손실되거나 중복된 스트림 이벤트가 도착하면 이 공지가 표시되지 않습니다:537Claude가 텍스트 또는 도구 호출을 시작하기 전에 손실되거나 중복되거나 손상된 스트림 이벤트가 도착하면 이 공지가 표시되지 않습니다:

533 538

534* Claude가 생각만 완료했으면 Claude Code가 요청을 다시 발급합니다. 다시 발급된 스트림이 동일한 방식으로 끊어지면 턴이 `Part of the response never arrived and no response was produced. Try again.` 또는 `The response stream was malformed and no response was produced. Try again.`으로 끝납니다.539* Claude가 사고만 완료했으면 Claude Code가 요청을 다시 발급합니다. 다시 발급된 스트림이 동일한 방식으로 끊어지면 턴이 `Part of the response never arrived and no response was produced. Try again.` 또는 `The response stream was malformed and no response was produced. Try again.`으로 끝납니다.

535* 아무것도 완료되지 않았으면 Claude Code가 스트리밍 없이 요청을 다시 보냅니다. [`CLAUDE_CODE_DISABLE_NONSTREAMING_FALLBACK`](/docs/ko/env-vars)으로 해당 폴백을 끈 경우 턴이 손실된 이벤트에 대해 `API Error: Content block not found`로 끝나거나 중복된 이벤트에 대해 `API Error: Content block already closed`로 끝납니다. 손상된 이벤트의 경우 폴백이 꺼져 있으면 턴이 `API Error: Stream event unreadable` 또는 파서의 원본 오류로 끝납니다.540* 아무것도 완료되지 않았으면 Claude Code가 스트리밍 없이 요청을 다시 보냅니다. [`CLAUDE_CODE_DISABLE_NONSTREAMING_FALLBACK`](/docs/ko/env-vars)으로 해당 폴백을 끈 경우 턴이 손실된 이벤트에 대해 `API Error: Content block not found`로 끝나거나 중복된 이벤트에 대해 `API Error: Content block already closed`로 끝납니다. 손상된 이벤트의 경우 폴백이 꺼져 있으면 턴이 `API Error: Stream event unreadable` 또는 파서의 원본 오류로 끝납니다.

536 541

5374가지 경우에 Claude Code는 이 공지를 즉시 표시하지 않고 실패를 처리합니다:5424가지 경우에 Claude Code는 이 공지를 즉시 표시하지 않고 실패를 처리합니다:

538 543

539* 응답의 앞부분에서 Claude Code는 실패를 재시도하거나 다른 오류로 턴을 종료합니다. [자동 재시도](#automatic-retries)를 참조하세요.544* 응답의 앞부분에서 Claude Code는 실패를 재시도하거나 다른 오류로 턴을 종료합니다. [자동 재시도](#automatic-retries)를 참조하세요.

540* 이러한 실패 중 하나가 Claude가 응답을 마친 후에 도착하면 Claude Code는 완전한 응답을 유지하고 이 공지 없이 턴을 정상적으로 종료합니다. v2.1.222 이전에는 Claude Code가 응답이 완료된 후 연결이 끊어지거나 정지되었을 때 이 공지를 표시했고 응답이 완전했음에도 불구하고 턴을 오류로 보고했습니다.545* 이러한 실패 중 하나가 Claude가 응답을 마친 후에 도착하면 Claude Code는 완전한 응답을 유지하고 이 공지 없이 턴을 정상적으로 종료합니다. v2.1.222 이전에는 Claude Code가 응답이 완료된 후 연결이 끊어지거나 정지되었을 때 이 공지를 표시했고 응답이 완전했음에도 불구하고 턴을 오류로 보고했습니다.

541* [비대화형 세션](/docs/ko/headless)(예: `-p` 실행, [Agent SDK](/docs/ko/agent-sdk/overview) 실행 또는 [클라우드 세션](/docs/ko/claude-code-on-the-web))에서 잘린 응답이 주 대화에 있고 텍스트를 포함하지만 도구 호출이 없는 경우 `continue`를 직접 보낼 필요가 없습니다: Claude Code는 부분 출력을 유지하고 Claude에게 중단된 위치에서 계속하도록 프롬프트합니다. 최대 3번 연속으로. 이 공지는 Claude Code가 해당 연속을 모두 사용한 후에만 이러한 응답에 대해 표시됩니다. v2.1.246 이전에는 Claude Code가 비대화형 턴을 첫 번째 잘림에서 이 공지로 종료했습니다.546* [비대화형 세션](/docs/ko/headless)(예: `-p` 실행, [Agent SDK](/docs/ko/agent-sdk/overview) 실행 또는 [클라우드 세션](/docs/ko/claude-code-on-the-web))에서 잘린 응답이 주 대화에 있고 텍스트를 포함하지만 도구 호출이 없는 경우 `continue`를 직접 보낼 필요가 없습니다: Claude Code는 부분 출력을 유지하고 Claude에게 중단된 위치에서 계속하도록 요청하며, 최대 3번 연속으로 요청합니다. 이 공지는 Claude Code가 해당 연속을 모두 사용한 후에만 이러한 응답에 대해 표시됩니다. v2.1.246 이전에는 Claude Code가 비대화형 턴을 첫 번째 잘림에서 이 공지로 종료했습니다.

542* [하위 에이전트](/docs/ko/sub-agents#api-errors-in-subagents)에서, 세션이 대화형인지 여부와 관계없이: 잘린 응답이 텍스트를 포함하지만 도구 호출이 없을 때 Claude Code는 하위 에이전트에게 계속하도록 프롬프트합니다. 공지는 해당 연속이 사용될 때까지만 하위 에이전트의 마지막 메시지가 됩니다. v2.1.257 이전에는 하위 에이전트가 첫 번째 잘림에서 이 공지를 표시했습니다.547* [서브에이전트](/docs/ko/sub-agents#api-errors-in-subagents)에서, 세션이 대화형인지 여부와 관계없이: 잘린 응답이 텍스트를 포함하지만 도구 호출이 없을 때 Claude Code는 서브에이전트에게 계속하도록 요청합니다. 공지는 해당 연속을 모두 사용한 후에만 서브에이전트의 마지막 메시지가 됩니다. v2.1.257 이전에는 서브에이전트가 첫 번째 잘림에서 이 공지를 표시했습니다.

543 548

544**수행할 작업:**549**수행할 작업:**

545 550

546* 대화형 세션에서 화면에 남아 있는 응답을 읽습니다: Claude Code는 오류 전에 Claude가 완료한 모든 블록을 유지하지만 턴이 끝날 때 중단된 최종 블록을 버립니다. 따라서 최종 문장 또는 도구 호출이 누락될 수 있습니다. `continue`로 회신하여 Claude가 마지막으로 완료한 블록에서 계속하도록 합니다.551* 대화형 세션에서 화면에 남아 있는 응답을 읽습니다: Claude Code는 오류 전에 Claude가 완료한 모든 블록을 유지하지만 턴이 끝날 때 중단된 최종 블록을 버립니다. 따라서 최종 문장 또는 도구 호출이 누락될 수 있습니다. `continue`로 회신하여 Claude가 마지막으로 완료한 블록에서 계속하도록 합니다.

547* [비대화형 모드](/docs/ko/headless)(`-p`):552* [비대화형 모드](/docs/ko/headless)(`-p`):

548 * 기본 텍스트 출력을 사용하면 Claude Code는 턴의 앞부분에서 여전히 보유한 마지막 완료된 텍스트 블록을 인쇄한 후 이 메시지를 인쇄합니다. 보유하지 않으면 Claude Code는 이 메시지만 인쇄합니다. 예를 들어 Claude Code가 턴 중간에 대화를 압축하고 해당 텍스트를 지웠기 때문입니다. v2.1.219 이전에는 Claude Code가 `-p` 텍스트 출력에서만 이 메시지를 인쇄했고 이미 생성한 응답을 버렸습니다.553 * 기본 텍스트 출력을 사용하면 Claude Code는 턴의 앞부분에서 여전히 보유한 마지막 완료된 텍스트 블록을 인쇄한 후 이 메시지를 인쇄합니다. 보유하지 않으면 Claude Code는 이 메시지만 인쇄합니다. 예를 들어 Claude Code가 턴 중간에 대화를 압축하고 해당 텍스트를 지웠기 때문입니다. v2.1.219 이전에는 Claude Code가 `-p` 텍스트 출력에서 이 메시지만 인쇄했고 이미 생성한 응답을 버렸습니다.

549 * `--output-format json` 또는 `stream-json`을 사용하면 Claude Code는 이 메시지를 `result` 필드에 보고합니다.554 * `--output-format json` 또는 `stream-json`을 사용하면 Claude Code는 이 메시지를 `result` 필드에 보고합니다.

550 * 연결이 안정적이면 턴을 계속하려면 세션을 재개하고 [대화 계속](/docs/ko/headless#continue-conversations)에 설명된 대로 `continue`를 보냅니다.555 * 연결이 안정되면 턴을 계속하려면 세션을 재개하고 [대화 계속](/docs/ko/headless#continue-conversations)에 설명된 대로 `continue`를 보냅니다.

551 556

552<h3 id="auto-mode-cannot-determine-the-safety-of-an-action">557<h3 id="auto-mode-cannot-determine-the-safety-of-an-action">

553 자동 모드가 작업의 안전성을 결정할 수 없음558 자동 모드가 작업의 안전성을 결정할 수 없음

554</h3>559</h3>

555 560

556[자동 모드](/docs/ko/permission-modes#eliminate-prompts-with-auto-mode)가 작업을 분류하는 데 사용하는 모델이 결정을 내릴 수 없어 자동 모드가 작업을 자동으로 승인하지 않았습니다. 표시되는 메시지는 분류자가 실패한 방식에 따라 다릅니다.561[자동 모드](/docs/ko/permission-modes#eliminate-prompts-with-auto-mode)가 작업을 분류하는 데 사용하는 모델이 결정을 내릴 수 없어 자동 모드가 작업을 자동으로 승인하지 않았습니다. 표시되는 메시지는 분류기가 실패한 방식에 따라 다릅니다.

557 562

558작업 디렉토리 내의 읽기, 검색 및 편집은 분류자를 건너뛰므로 이러한 모든 경우에 계속 작동합니다.563작업 디렉터리 내의 읽기, 검색 및 편집은 분류기를 건너뛰므로 이러한 모든 경우에 계속 작동합니다.

559 564

560분류자 모델을 사용할 수 없을 때:565분류기 모델을 사용할 수 없을 때:

561 566

562```text theme={null}567```text theme={null}

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

565 570

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

567 572

568범주가 맞지 않으면 메시지는 괄호에 범주 없이 나타납니다. 둘 이상의 실패가 해당 형식을 생성합니다. [Amazon Bedrock](/docs/ko/amazon-bedrock)에서, [Mantle 엔드포인트](/docs/ko/amazon-bedrock#use-the-mantle-endpoint) 포함, AWS 계정이 메시지에 명시된 모델을 호출할 수 없을 때도 나타나며, 계정에 모델에 대한 액세스 권한이 부여될 때까지 모든 재시도에서 해당 실패가 반복됩니다.573맞는 범주가 없으면 메시지는 괄호에 범주 없이 나타납니다. 둘 이상의 실패가 해당 형식을 생성합니다. [Amazon Bedrock](/docs/ko/amazon-bedrock)에서, [Mantle 엔드포인트](/docs/ko/amazon-bedrock#use-the-mantle-endpoint) 포함, AWS 계정이 메시지에 명시된 모델을 호출할 수 없을 때도 나타나며, 계정에 모델에 대한 액세스 권한이 부여될 때까지 모든 재시도에서 해당 실패가 반복됩니다.

569 574

570**수행할 작업:**575**수행할 작업:**

571 576

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

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

575 580

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

577 582

578분류자가 파싱할 수 없는 응답을 반환했을 때:583분류기가 파싱할 수 없는 응답을 반환했을 때:

579 584

580```text theme={null}585```text theme={null}

581Auto mode could not evaluate this action and is blocking it for safety — run with --debug for details586Auto mode could not evaluate this action and is blocking it for safety — run with --debug for details

586* 작업을 재시도합니다. 이는 일반적으로 다음 시도에서 성공합니다591* 작업을 재시도합니다. 이는 일반적으로 다음 시도에서 성공합니다

587* `claude --debug`를 실행하고 작업을 반복하여 디버그 로그에서 세부 정보를 확인합니다592* `claude --debug`를 실행하고 작업을 반복하여 디버그 로그에서 세부 정보를 확인합니다

588 593

589별도의 API 안전 검사가 이전 대화 내용으로 인해 분류자 요청을 차단했을 때:594별도의 API 안전 검사가 이전 대화 내용으로 인해 분류기 요청을 차단했을 때:

590 595

591```text theme={null}596```text theme={null}

592Auto mode could not evaluate this action and is blocking it for safety — a safety check separate from auto mode blocked this request because of earlier conversation content — it isn't about the action itself — run with --debug for details597Auto mode could not evaluate this action and is blocking it for safety — a safety check separate from auto mode blocked this request because of earlier conversation content — it isn't about the action itself — run with --debug for details

594 599

595Claude Code는 작업을 거부하지만 Claude에게 이것이 작업이 안전하지 않다는 판단이 아니며 재시도하는 대신 다른 작업을 계속하도록 알립니다. 이러한 거부는 [자동 모드의 일시 중지 임계값](/docs/ko/permission-modes#when-auto-mode-falls-back)에 대해 계산되지 않습니다. [비대화형](/docs/ko/headless) `-p` 실행에서 Claude Code는 실행을 중지하지 않습니다. Claude가 수신하는 내용은 작업을 요청한 위치에 따라 다릅니다:600Claude Code는 작업을 거부하지만 Claude에게 이것이 작업이 안전하지 않다는 판단이 아니며 재시도하는 대신 다른 작업을 계속하도록 알립니다. 이러한 거부는 [자동 모드의 일시 중지 임계값](/docs/ko/permission-modes#when-auto-mode-falls-back)에 대해 계산되지 않습니다. [비대화형](/docs/ko/headless) `-p` 실행에서 Claude Code는 실행을 중지하지 않습니다. Claude가 수신하는 내용은 작업을 요청한 위치에 따라 다릅니다:

596 601

597* `-p` 실행 중 `--input-format stream-json` 없이 [백그라운드 하위 에이전트](/docs/ko/sub-agents#run-subagents-in-foreground-or-background)에 Claude Code는 `Agent aborted: auto mode classifier request refused by the safety safeguard in headless mode`를 포함하는 오류 결과를 반환합니다602* `-p` 실행 중 `--input-format stream-json` 없이 [백그라운드 서브에이전트](/docs/ko/sub-agents#run-subagents-in-foreground-or-background)에 Claude Code는 `Agent aborted: auto mode classifier request refused by the safety safeguard in headless mode`를 포함하는 오류 결과를 반환합니다

598* 대화형 세션 및 `-p` 실행의 주 대화를 포함한 다른 모든 곳에서 Claude Code는 해당 거부를 Claude에게 반환합니다603* 대화형 세션 및 `-p` 실행의 주 대화를 포함한 다른 모든 곳에서 Claude Code는 해당 거부를 Claude에게 반환합니다

599 604

600v2.1.225 이전에는 Claude Code가 이러한 거부를 일시 중지 임계값에 대해 계산했고 진정한 분류자 블록과 동일한 거부 메시지를 반환했습니다.605v2.1.225 이전에는 Claude Code가 이러한 거부를 일시 중지 임계값에 대해 계산했고 진정한 분류기 차단과 동일한 거부 메시지를 반환했습니다.

601 606

602**수행할 작업:**607**수행할 작업:**

603 608

604* 이것은 작업에 대한 결정이 아닙니다. 대화에 이미 있는 내용이 Claude Code가 대화를 분류자에게 보낼 때 API의 안전 필터를 트리거했습니다609* 이것은 작업에 대한 결정이 아닙니다. 대화에 이미 있는 내용이 자동 모드가 대화를 분류기에 보낼 때 API의 안전 필터를 트리거했습니다

605* 재시도는 도움이 되지 않습니다. 동일한 대화 내용이 필터를 다시 트리거합니다610* 재시도는 도움이 되지 않습니다. 동일한 대화 내용이 필터를 다시 트리거합니다

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

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

608 613

609대화가 분류자의 컨텍스트 윈도우보다 커졌을 때:614대화가 분류기의 컨텍스트 윈도우보다 커졌을 때:

610 615

611```text theme={null}616```text theme={null}

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

615작업에 발생하는 일은 Claude가 요청한 위치에 따라 다릅니다:620작업에 발생하는 일은 Claude가 요청한 위치에 따라 다릅니다:

616 621

617* 대화형 세션에서 자동 모드는 해당 작업에 대해 일반 권한 프롬프트로 폴백하므로 수동으로 승인하거나 거부할 수 있습니다622* 대화형 세션에서 자동 모드는 해당 작업에 대해 일반 권한 프롬프트로 폴백하므로 수동으로 승인하거나 거부할 수 있습니다

618* [비대화형](/docs/ko/headless) `-p` 실행 중 `--input-format stream-json` 없이 [백그라운드 하위 에이전트](/docs/ko/sub-agents#run-subagents-in-foreground-or-background)에 Claude Code는 `Agent aborted: auto mode classifier transcript exceeded context window in headless mode`를 포함하는 오류 결과를 반환하고 실행을 계속합니다623* [비대화형](/docs/ko/headless) `-p` 실행 중 `--input-format stream-json` 없이 [백그라운드 서브에이전트](/docs/ko/sub-agents#run-subagents-in-foreground-or-background)에 Claude Code는 `Agent aborted: auto mode classifier transcript exceeded context window in headless mode`를 포함하는 오류 결과를 반환하고 실행을 계속합니다

619* [`--permission-prompt-tool`](/docs/ko/cli-reference#cli-flags) 없이 `-p` 실행의 다른 곳에서 폴백할 프롬프트가 없으므로 작업이 실행되지 않고 실행이 계속됩니다624* [`--permission-prompt-tool`](/docs/ko/cli-reference#cli-flags) 없이 `-p` 실행의 다른 곳에서 폴백할 프롬프트가 없으므로 작업이 실행되지 않고 실행이 계속됩니다

620 625

621**수행할 작업:**626**수행할 작업:**

622 627

623* 대화형 세션에서 나타나는 프롬프트에서 작업을 승인하거나 거부합니다628* 대화형 세션에서 나타나는 프롬프트에서 작업을 승인하거나 거부합니다

624* 대화형 세션에서 `/compact`를 실행하여 대화 크기를 줄여 후속 작업이 분류자 윈도우에 맞도록 합니다629* 대화형 세션에서 `/compact`를 실행하여 대화 크기를 줄여 후속 작업이 분류기 윈도우에 다시 맞도록 합니다

625 630

626<h3 id="the-server-returned-no-safety-verdict">631<h3 id="the-server-returned-no-safety-verdict">

627 서버가 안전 판정을 반환하지 않음632 서버가 안전 판정을 반환하지 않음

628</h3>633</h3>

629 634

630[서버 측 분류자 검토](/docs/ko/permission-modes#server-side-classifier-review) 하에서 자동 모드는 서버가 판정을 제공하지 않을 때 작업을 거부합니다. 거부는 Claude Code가 하나를 결정할 수 있을 때 괄호에 범주를 명시합니다. 예를 들어 `(timed out)`:635[서버 측 분류기 검토](/docs/ko/permission-modes#server-side-classifier-review) 하에서 자동 모드는 서버가 판정을 제공하지 않을 때 작업을 거부합니다. 거부는 Claude Code가 하나를 결정할 수 있을 때 괄호에 범주를 명시합니다. 예를 들어 `(timed out)`:

631 636

632```text theme={null}637```text theme={null}

633The server-side auto mode classifier gave no verdict (timed out), so auto mode cannot determine the safety of <tool>.638The server-side auto mode classifier gave no verdict (timed out), so auto mode cannot determine the safety of <tool>.

635 640

636메시지의 나머지 부분은 Claude에게 한 번의 재시도가 도움이 될 수 있는지 알려줍니다. 이러한 거부 중 일부 전에 Claude Code는 대기하므로 Claude의 다음 시도가 즉시 따르지 않습니다. 대화형 세션에서 대기 중에 스피너는 `Auto mode check unavailable`을 카운트다운과 함께 표시하며, `Esc`를 누르면 턴이 중단됩니다.641메시지의 나머지 부분은 Claude에게 한 번의 재시도가 도움이 될 수 있는지 알려줍니다. 이러한 거부 중 일부 전에 Claude Code는 대기하므로 Claude의 다음 시도가 즉시 따르지 않습니다. 대화형 세션에서 대기 중에 스피너는 `Auto mode check unavailable`을 카운트다운과 함께 표시하며, `Esc`를 누르면 턴이 중단됩니다.

637 642

63810개 응답이 연속으로 판정이 없은 후 자동 모드는 턴을 중지합니다:64310개 응답이 연속으로 판정이 없으면 자동 모드는 턴을 중지합니다:

639 644

640```text theme={null}645```text theme={null}

641Auto mode is unavailable — the server returned no safety verdict for the last 10 responses, so Claude stopped. Send a message to try again, or switch out of auto mode.646Auto mode is unavailable — the server returned no safety verdict for the last 10 responses, so Claude stopped. Send a message to try again, or switch out of auto mode.

643 648

644중지 메시지는 각 세션 종류에서 다른 위치에 나타납니다:649중지 메시지는 각 세션 종류에서 다른 위치에 나타납니다:

645 650

646* 대화형 세션에서 메시지는 대화 기록에 경고로 나타나고 턴이 끝납니다651* 대화형 세션에서 메시지는 트랜스크립트에 경고로 나타나고 턴이 끝납니다

647* [비대화형](/docs/ko/headless) `-p` 실행에서 실행이 끝나고 실행 오류를 보고합니다. 기본 텍스트 출력을 사용하면 메시지가 stderr에 인쇄됩니다.652* [비대화형](/docs/ko/headless) `-p` 실행에서 실행이 끝나고 실행 오류를 보고합니다. 기본 텍스트 출력을 사용하면 메시지가 stderr에 인쇄됩니다.

648* [하위 에이전트](/docs/ko/sub-agents)가 한도에 도달했을 때 하위 에이전트는 완료 전에 중지되고 Claude는 자동 모드가 중지했다는 메모와 함께 생성한 것을 받습니다653* [서브에이전트](/docs/ko/sub-agents)가 한도에 도달했을 때 서브에이전트는 완료 전에 중지되고 Claude는 자동 모드가 중지했다는 메모와 함께 서브에이전트가 생성한 것을 받습니다

649 654

650**수행할 작업:**655**수행할 작업:**

651 656

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

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

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

655* 대신 작업을 직접 승인하려면 [자동 모드를 전환](/docs/ko/permission-modes#switch-permission-modes)합니다660* 대신 작업을 직접 승인하려면 [자동 모드에서 전환](/docs/ko/permission-modes#switch-permission-modes)합니다

656 661

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

658 663

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

661</h3>666</h3>

662 667

663[하위 에이전트](/docs/ko/sub-agents)의 API 요청이 사용 한도에 도달했거나 서버 오류에 대한 재시도가 소진되었기 때문에 터미널로 실패했으므로 하위 에이전트가 작업을 마치기 전에 중지했습니다. 이 메시지는 Claude Code v2.1.199 이상이 필요합니다. 그 이전에는 API 오류 텍스트가 하위 에이전트의 결과인 것처럼 Claude에게 반환되었습니다.668[서브에이전트](/docs/ko/sub-agents)의 API 요청이 사용 한도에 도달했거나 서버 오류에 대한 재시도가 소진되는 등의 이유로 최종적으로 실패했으므로 서브에이전트가 작업을 마치기 전에 중지했습니다. 이 메시지는 Claude Code v2.1.199 이상이 필요합니다. 그 이전에는 API 오류 텍스트가 서브에이전트의 결과인 것처럼 Claude에게 반환되었습니다.

664 669

665```text theme={null}670```text theme={null}

666Agent terminated early due to an API error: <error detail>671Agent terminated early due to an API error: <error detail>

668 673

669**수행할 작업:**674**수행할 작업:**

670 675

671* 콜론 뒤의 오류 세부 정보를 이 페이지의 자체 섹션(예: [사용 한도](#usage-limits) 또는 [서버 오류](#server-errors))과 일치시키고 해당 섹션의 단계를 따릅니다676* 콜론 뒤의 오류 세부 정보를 이 페이지의 해당 섹션(예: [사용 한도](#usage-limits) 또는 [서버 오류](#server-errors))과 대조하고 해당 섹션의 단계를 따릅니다

672* 기본 오류가 해결되면 Claude에게 작업을 재시도하거나 [하위 에이전트를 재개](/docs/ko/sub-agents#resume-subagents)하도록 요청합니다677* 기본 오류가 해결되면 Claude에게 작업을 재시도하거나 [서브에이전트를 재개](/docs/ko/sub-agents#resume-subagents)하도록 요청합니다

673 678

674속도 제한, 오버로드 또는 서버 오류가 이미 텍스트 출력을 생성한 포그라운드 하위 에이전트를 중단할 때 Claude는 이 오류 대신 불완전으로 표시된 부분 출력을 수신합니다. 유일한 출력이 도구 호출인 하위 에이전트도 이 오류를 받습니다. v2.1.199에서는 해당 형태가 빈 부분 결과를 대신 반환했습니다. [하위 에이전트의 API 오류](/docs/ko/sub-agents#api-errors-in-subagents)를 참조하세요.679속도 제한, 오버로드 또는 서버 오류가 이미 텍스트 출력을 생성한 포그라운드 서브에이전트를 중단할 때 Claude는 이 오류 대신 불완전으로 표시된 부분 출력을 수신합니다. 유일한 출력이 도구 호출인 서브에이전트도 이 오류를 받습니다. v2.1.199에서는 해당 형태가 빈 부분 결과를 대신 반환했습니다. [서브에이전트의 API 오류](/docs/ko/sub-agents#api-errors-in-subagents)를 참조하세요.

675 680

676<h2 id="usage-limits">681<h2 id="usage-limits">

677 사용 한도682 사용 한도

882 인증 오류887 인증 오류

883</h2>888</h2>

884 889

885이러한 오류는 Claude Code가 API에 대해 사용자의 신원을 증명할 수 없음을 의미합니다. 언제든지 `/status`를 실행하여 현재 활성화된 자격증명을 확인하십시오.890이 오류는 Claude Code가 API에 사용자의 신원을 증명할 수 없다는 의미입니다. 현재 어떤 자격 증명이 활성화되어 있는지 확인하려면 언제든지 `/status`를 실행하십시오.

886 891

887<h3 id="not-logged-in">892<h3 id="not-logged-in">

888 로그인하지 않음893 로그인되지 않음

889</h3>894</h3>

890 895

891이 세션에 유효한 자격증명이 없습니다.896이 세션에 사용할 수 있는 유효한 자격 증명이 없습니다.

892 897

893```text theme={null}898```text theme={null}

894Not logged in · Please run /login899Not logged in · Please run /login

895```900```

896 901

897Claude Desktop 앱이 실행하는 세션(예: Code 탭 또는 Cowork)에서 메시지는 `Authentication required · Sign in again to continue`로 읽으며, 앱에서 다시 로그인합니다.902Code 탭이나 Cowork처럼 Claude Desktop 앱이 실행하는 세션에서는 메시지가 `Authentication required · Sign in again to continue`로 표시되며, 앱에서 다시 로그인합니다.

898 903

899**수행할 작업:**904동일한 [구성 디렉터리](/docs/ko/claude-directory)를 사용하는 다른 Claude Code 창에서 claude.ai 계정으로 로그인하면, 이 메시지를 표시하는 대화형 세션은 자동으로 해당 로그인을 사용하기 시작합니다. 세션을 다시 시작할 필요가 없습니다.

905

906macOS에서 v2.1.286 이전에는 다른 창에서 로그인한 후에도 세션이 계속 이 메시지를 표시할 수 있었습니다. 해당 버전에서는 메시지를 표시하는 세션을 다시 시작하십시오.

900 907

901* `/login`을 실행하여 Claude 구독 또는 Console 계정으로 인증합니다.908**해결 방법:**

902* 환경 변수가 사용자를 인증할 것으로 예상했다면, `ANTHROPIC_API_KEY`가 `claude`를 실행한 셸에서 설정되고 내보내졌는지 확인합니다.

903* CI 또는 자동화에서 대화형 로그인이 불가능한 경우, 시작 시 키를 가져오는 [`apiKeyHelper`](/docs/ko/settings-reference#apikeyhelper) 스크립트를 구성합니다.

904* [인증 우선순위](/docs/ko/authentication#authentication-precedence)를 참조하여 여러 자격증명이 있을 때 Claude Code가 어떤 자격증명을 사용하는지 이해합니다.

905 909

906반복적으로 로그인하라는 메시지가 표시되면, [로그인하지 않음 또는 토큰 만료됨](/docs/ko/troubleshoot-install#not-logged-in-or-token-expired)에서 시스템 시계 확인 및 macOS 자격증명 저장소 복구 단계를 참조하십시오.910* `/login`을 실행하여 Claude 구독 또는 Console 계정으로 인증합니다

911* 환경 변수로 인증되기를 기대했다면 `claude`를 실행한 셸에서 `ANTHROPIC_API_KEY`가 설정되고 export되었는지 확인합니다

912* 대화형 로그인이 불가능한 CI 또는 자동화 환경에서는 시작 시 키를 가져오는 [`apiKeyHelper`](/docs/ko/settings-reference#apikeyhelper) 스크립트를 구성합니다

913* 여러 자격 증명이 있을 때 Claude Code가 어떤 자격 증명을 사용하는지 이해하려면 [인증 우선순위](/docs/ko/authentication#authentication-precedence)를 참조하십시오

914

915로그인하라는 메시지가 반복해서 표시되면 시스템 시계 확인 및 macOS 자격 증명 저장소 복구 단계에 대해 [로그인되지 않음 또는 토큰 만료](/docs/ko/troubleshoot-install#not-logged-in-or-token-expired)를 참조하십시오.

907 916

908<h3 id="could-not-resolve-authentication-method">917<h3 id="could-not-resolve-authentication-method">

909 인증 방법을 확인할 수 없음918 인증 방법을 확인할 수 없음

910</h3>919</h3>

911 920

912세션이 자격증명 없이 API 클라이언트에 도달했습니다. [백그라운드 세션](/docs/ko/agent-view) 및 클라우드 세션은 워커가 자격증명 없이 시작될 때 이 메시지를 표시합니다. 대화형, `-p` 및 Agent SDK 실행은 [로그인하지 않음](#not-logged-in)과 동일한 조건을 보고하며 이 문자열을 디버그 로그에만 기록하므로, 거기서 찾은 경우 대신 해당 항목을 따릅니다.921세션이 자격 증명 없이 API 클라이언트에 도달했습니다. [백그라운드 세션](/docs/ko/agent-view)과 클라우드 세션은 워커가 자격 증명 없이 시작될 때 이 메시지를 표시합니다. 대화형, `-p`, Agent SDK 실행은 동일한 상태를 [로그인되지 않음](#not-logged-in)으로 보고하고 이 문자열은 디버그 로그에만 기록하므로, 디버그 로그에서 이 문자열을 발견했다면 해당 항목을 따르십시오.

913 922

914```text theme={null}923```text theme={null}

915Could not resolve authentication method. Expected one of apiKey, authToken, credentials, config, or profile to be set. Or for one of the "X-Api-Key" or "Authorization" headers to be explicitly omitted924Could not resolve authentication method. Expected one of apiKey, authToken, credentials, config, or profile to be set. Or for one of the "X-Api-Key" or "Authorization" headers to be explicitly omitted

916```925```

917 926

918현재 버전에서 오류는 워커 프로세스에 사용 가능한 자격증명이 없음을 의미합니다. v2.1.174 이전에는 유휴 사전 초기화된 워커에 할당된 백그라운드 세션이 유효한 자격증명이 구성되어 있어도 이런 식으로 실패할 수 있었습니다. v2.1.176 이전에는 요청되기 전에 유휴 상태였던 클라우드 세션도 마찬가지였습니다. 업그레이드하여 복구합니다.927현재 버전에서 이 오류는 워커 프로세스에서 사용할 수 있는 자격 증명이 없었다는 의미입니다. v2.1.174 이전에는 유휴 상태의 사전 초기화된 워커에 할당된 백그라운드 세션이 유효한 자격 증명이 구성되어 있어도 이런 방식으로 실패할 수 있었습니다. v2.1.176 이전에는 할당되기 전에 유휴 상태로 있던 클라우드 세션도 마찬가지였습니다. 업그레이드하면 복구됩니다.

919 928

920**수행할 작업:**929**해결 방법:**

921 930

922* 백그라운드 또는 클라우드 세션에서 이것이 나타나고 자격증명이 이미 구성되어 있으면 v2.1.176 이상으로 업그레이드합니다.931* 백그라운드 또는 클라우드 세션에서 이 메시지가 나타나고 자격 증명이 이미 구성되어 있다면 v2.1.176 이상으로 업그레이드합니다

923* `ANTHROPIC_API_KEY`, `CLAUDE_CODE_OAUTH_TOKEN` 또는 클라우드 공급자 자격증명이 대화형 셸이 아닌 워커를 실행하는 환경에서 설정되어 있는지 확인합니다.932* `ANTHROPIC_API_KEY`, `CLAUDE_CODE_OAUTH_TOKEN` 또는 클라우드 제공업체 자격 증명이 대화형 셸뿐만 아니라 워커를 실행하는 환경에도 설정되어 있는지 확인합니다

924* Agent SDK의 경우, [빠른 시작의 인증 설정](/docs/ko/agent-sdk/quickstart#setup)을 참조합니다.933* Agent SDK의 경우 [빠른 시작의 인증 설정](/docs/ko/agent-sdk/quickstart#setup)을 참조하십시오

925* 동일한 환경의 대화형 세션에서 `/status`를 실행하여 어떤 자격증명 소스가 확인되는지 확인합니다.934* 동일한 환경의 대화형 세션에서 `/status`를 실행하여 어떤 자격 증명 소스가 확인되는지 확인합니다

926 935

927<h3 id="invalid-api-key">936<h3 id="invalid-api-key">

928 잘못된 API 키937 잘못된 API 키

929</h3>938</h3>

930 939

931`ANTHROPIC_API_KEY` 환경 변수 또는 `apiKeyHelper` 스크립트가 API가 거부한 키를 반환했습니다. 또는 Claude Code가 `ANTHROPIC_API_KEY`의 키를 전송하기 전에 차단했습니다.940`ANTHROPIC_API_KEY` 환경 변수 또는 `apiKeyHelper` 스크립트가 API에서 거부한 키를 반환했거나, Claude Code가 `ANTHROPIC_API_KEY`의 키를 전송하기 전에 차단했습니다.

932 941

933```text theme={null}942```text theme={null}

934Invalid API key · Fix external API key943Invalid API key · Fix external API key

935```944```

936 945

937메시지가 `Fix external API key` 이후로 계속되고 `Invalid X-Api-Key header value from ANTHROPIC_API_KEY: it contains a line break at character 41 (120 characters on 2 lines).`와 같은 설명이 있으면, API는 키를 보지 못했습니다. Claude Code가 HTTP 헤더가 전달할 수 없는 문자를 찾았고 전송하기 전에 요청을 중지했습니다. 설명을 읽고 값을 수정하는 방법은 [잘못된 요청 헤더 값](#invalid-request-header-value)을 참조합니다.946메시지가 `Fix external API key` 뒤에 `Invalid X-Api-Key header value from ANTHROPIC_API_KEY: it contains a line break at character 41 (120 characters on 2 lines).`와 같은 설명으로 이어지면, API는 키를 전혀 받지 않은 것입니다. Claude Code가 HTTP 헤더로 전달할 수 없는 문자를 발견하고 요청을 전송하기 전에 중단했습니다. 설명을 읽고 값을 수정하는 방법은 [잘못된 요청 헤더 값](#invalid-request-header-value)을 참조하십시오.

938 947

939**수행할 작업:**948**해결 방법:**

940 949

941* 오타를 확인하고 [Console](https://platform.claude.com/settings/keys)에서 키가 취소되지 않았는지 확인합니다.950* 오타가 있는지 확인하고 [Console](https://platform.claude.com/settings/keys)에서 키가 취소되지 않았는지 확인합니다

942* 동일한 셸에서 `env | grep ANTHROPIC`을 실행하거나, PowerShell에서 `Get-ChildItem Env:ANTHROPIC*`을 실행합니다. direnv, dotenv 셸 플러그인 및 IDE 터미널과 같은 도구는 명시적으로 설정하지 않고도 프로젝트의 `.env` 파일에서 오래된 키를 로드할 수 있습니다.951* 동일한 셸에서 `env | grep ANTHROPIC`을 실행하거나, PowerShell에서는 `Get-ChildItem Env:ANTHROPIC*`를 실행합니다. direnv, dotenv 셸 플러그인, IDE 터미널과 같은 도구는 명시적으로 설정하지 않아도 프로젝트의 `.env` 파일에서 오래된 키를 로드할 수 있습니다.

943* `ANTHROPIC_API_KEY`를 설정 해제하고 `/login`을 실행하여 대신 구독 인증을 사용합니다.952* `ANTHROPIC_API_KEY`를 설정 해제하고 `/login`을 실행하여 대신 구독 인증을 사용합니다

944* 키가 [`apiKeyHelper`](/docs/ko/settings-reference#apikeyhelper) 스크립트에서 오는 경우, 스크립트를 직접 실행하여 stdout에 유효한 키를 인쇄하는지 확인합니다.953* 키가 [`apiKeyHelper`](/docs/ko/settings-reference#apikeyhelper) 스크립트에서 제공되는 경우, 스크립트를 직접 실행하여 stdout에 유효한 키를 출력하는지 확인합니다

945* `/status`를 실행하여 Claude Code가 실제로 사용 중인 자격증명 소스를 확인합니다.954* `/status`를 실행하여 Claude Code가 실제로 사용하는 자격 증명 소스를 확인합니다

946 955

947<h3 id="your-apikeyhelper-script-is-failing">956<h3 id="your-apikeyhelper-script-is-failing">

948 apiKeyHelper 스크립트가 실패 중입니다957 apiKeyHelper 스크립트 실패

949</h3>958</h3>

950 959

951Claude Code가 [`apiKeyHelper`](/docs/ko/settings-reference#apikeyhelper) 설정에서 명령을 실행했지만 키를 다시 받지 못했습니다. 키 없이 요청이 자리 표시자 자격증명으로 API에 도달하고, API가 `401`로 거부합니다. 터미널의 `Authentication` 패널은 다음 중 어떤 일이 발생했는지 보여줍니다:960Claude Code가 [`apiKeyHelper`](/docs/ko/settings-reference#apikeyhelper) 설정의 명령을 실행했지만 키를 받지 못했습니다. 키가 없으면 요청은 자리 표시자 자격 증명과 함께 API에 도달하고, API는 `401`로 이를 거부합니다. 터미널의 `Authentication` 패널에 다음 중 어떤 상황이 발생했는지 표시됩니다.

952 961

953* 명령이 오류로 종료되었거나 시간 초과되었습니다.962* 명령이 오류와 함께 종료되었거나 시간 초과되었습니다

954* 명령이 stdout에 아무것도 인쇄하지 않았습니다.963* 명령이 stdout에 아무것도 출력하지 않았습니다

955* 명령이 로그인 배너 또는 로그 라인과 같이 키 이외의 것을 인쇄했습니다. 패널은 `returned output that cannot be used as an API key`를 표시하고 무엇이 잘못되었는지 말하며, 출력을 반복하지 않습니다. v2.1.227 이전에는 Claude Code가 주변 공백을 자른 후 명령이 인쇄한 모든 것을 전송했습니다.964* 명령이 로그인 배너나 로그 줄처럼 키 이외의 내용을 출력했습니다. 패널에는 `returned output that cannot be used as an API key`가 표시되고 출력을 반복하지 않고 무엇이 잘못되었는지 알려 줍니다. v2.1.227 이전에는 Claude Code가 앞뒤 공백을 제거한 후 명령이 출력한 내용을 그대로 전송했습니다.

956 965

957```text theme={null}966```text theme={null}

958Your apiKeyHelper script is failing · This usually means you need to re-authenticate with your provider · Run /status to see the script's error output967Your apiKeyHelper script is failing · This usually means you need to re-authenticate with your provider · Run /status to see the script's error output

959```968```

960 969

961[비대화형 모드](/docs/ko/headless)에서 stderr도 `apiKeyHelper failed:`로 접두사가 붙은 특정 이유를 전달합니다.970[비대화형 모드](/docs/ko/headless)에서는 stderr에도 `apiKeyHelper failed:` 접두사와 함께 구체적인 이유가 표시됩니다.

962 971

963Claude Code는 스크립트를 다시 실행하고 이 메시지를 표시하기 전에 요청을 최대 2회 더 재시도하므로, 실패는 3번의 시도 내에 표시됩니다. v2.1.208 이전에는 Claude Code가 전체 [재시도 예산](#automatic-retries)을 자리 표시자 자격증명으로 요청을 재전송하는 데 사용한 후 일반적인 `401` 인증 오류 대신 스크립트 실패를 보고했습니다.972Claude Code는 이 메시지를 표시하기 전에 스크립트를 다시 실행하고 요청을 최대 두 번 더 재시도하므로, 실패는 세 번의 시도 안에 드러납니다. v2.1.208 이전에는 Claude Code가 전체 [재시도 한도](#automatic-retries)를 소진하며 자리 표시자 자격 증명으로 요청을 다시 전송한 다음, 스크립트 실패 대신 일반적인 `401` 인증 오류를 보고했습니다.

964 973

965`/login`을 실행하는 것은 여기서 도움이 되지 않습니다: 헬퍼의 출력은 설정이 있는 한 저장된 로그인보다 [우선순위](/docs/ko/authentication#authentication-precedence)를 갖습니다.974여기서는 `/login`을 실행해도 도움이 되지 않습니다. 설정이 존재하는 동안에는 헬퍼의 출력이 저장된 로그인보다 [우선합니다](/docs/ko/authentication#authentication-precedence).

966 975

967**수행할 작업:**976**해결 방법:**

968 977

969* `apiKeyHelper`에 구성된 명령을 셸에서 직접 실행하여 실패를 재현합니다.978* `apiKeyHelper`에 구성된 명령을 셸에서 직접 실행하여 실패를 재현합니다

970* 명령이 만료된 세션을 보고하면, 예를 들어 SSO 또는 비밀 자격증명 모음에 다시 로그인하여 자격증명 공급자로 다시 인증합니다.979* 명령이 세션 만료를 보고하면 자격 증명 제공업체에서 다시 인증합니다. 예를 들어 SSO 또는 시크릿 볼트에 다시 로그인합니다

971* 명령이 stdout에만 키를 인쇄하도록 수정합니다. 단일 인쇄 가능한 ASCII 토큰으로 최대 16,384자이며 종료 코드 0으로 종료합니다. 작동하는 설정은 [apiKeyHelper로 자격증명 회전](/docs/ko/llm-gateway-connect#rotate-credentials-with-apikeyhelper)을 참조합니다.980* 명령이 stdout에 키만 출력하도록 수정합니다. 키는 최대 16,384자의 출력 가능한 ASCII로 된 단일 토큰이어야 하며, 명령은 종료 코드 0으로 종료되어야 합니다. 작동하는 설정은 [apiKeyHelper로 자격 증명 교체](/docs/ko/llm-gateway-connect#rotate-credentials-with-apikeyhelper)를 참조하십시오.

972* `/status`를 실행하여 실패를 확인하고 `apiKeyHelper`가 활성 자격증명 소스인지 확인합니다. `apiKeyHelper` 행은 종료 코드 및 명령의 오류 출력과 같은 마지막 실패의 세부 정보와 함께 `Failing`을 표시하며, 다음 성공적인 실행 후 사라집니다. v2.1.274 이전에는 `/status`가 실패가 아닌 자격증명 소스만 표시했습니다.981* `/status`를 실행하여 실패 내용을 확인하고 `apiKeyHelper`가 활성 자격 증명 소스인지 확인합니다. `apiKeyHelper` 행에는 종료 코드 및 명령의 오류 출력과 같은 마지막 실패의 세부 정보와 함께 `Failing`이 표시되며, 다음 실행이 성공하면 사라집니다. v2.1.274 이전에는 `/status`에 실패가 아닌 자격 증명 소스만 표시되었습니다.

973* 명령이 실패할 때마다 종료 코드와 오류 출력도 터미널의 `Authentication` 패널에 나타납니다. v2.1.212 이전에는 패널의 제목이 `Cloud authentication`이었습니다.982* 명령이 실패할 때마다 종료 코드와 오류 출력이 터미널의 `Authentication` 패널에도 표시됩니다. v2.1.212 이전에는 패널 제목이 `Cloud authentication`이었습니다.

974 983

975<h3 id="invalid-request-header-value">984<h3 id="invalid-request-header-value">

976 잘못된 요청 헤더 값985 잘못된 요청 헤더 값

977</h3>986</h3>

978 987

979Claude Code가 요청 헤더로 전송하려던 값에 HTTP 헤더가 전달할 수 없는 문자가 포함되어 있습니다: 줄 바꿈, NUL 바이트 또는 `U+00FF` 위의 문자(예: 곡선 따옴표 또는 너비가 0인 공백). Claude Code는 아무것도 전송되기 전에 요청을 중지하고 수정할 변수 또는 설정의 이름을 지정합니다. 일반적인 원인은 보이지 않는 문자 또는 잘못된 줄 바꿈을 전달한 문서 또는 채팅에서 붙여넣은 자격증명입니다.988Claude Code가 요청 헤더로 전송하려던 값에 HTTP 헤더로 전달할 수 없는 문자가 포함되어 있습니다. 줄바꿈, NUL 바이트 또는 둥근 따옴표나 폭이 없는 공백처럼 `U+00FF`보다 큰 문자가 이에 해당합니다. Claude Code는 아무것도 전송하기 전에 요청을 중단하고 수정해야 할 변수 또는 설정의 이름을 알려 줍니다. 일반적인 원인은 문서나 채팅에서 붙여 넣은 자격 증명에 보이지 않는 문자나 불필요한 줄바꿈이 포함된 경우입니다.

980 989

981Claude Code는 Claude API에 직접 또는 [LLM 게이트웨이](/docs/ko/llm-gateway)를 통해 요청을 전송할 때 이 확인을 실행합니다. [Amazon Bedrock](/docs/ko/amazon-bedrock)과 같은 타사 클라우드 공급자에서는 Claude Code가 전송하기 전에 실행하지 않습니다.990Claude Code는 Claude API에 직접 또는 [LLM 게이트웨이](/docs/ko/llm-gateway)를 통해 요청을 전송할 때 이 검사를 실행합니다. [Amazon Bedrock](/docs/ko/amazon-bedrock)과 같은 타사 클라우드 제공업체에서는 Claude Code가 전송 전에 이 검사를 실행하지 않습니다.

982 991

983```text theme={null}992```text theme={null}

984Invalid auth token · Fix external auth token993Invalid auth token · Fix external auth token

986Invalid request header from the environment · Fix the environment variable995Invalid request header from the environment · Fix the environment variable

987```996```

988 997

989메시지의 첫 번째 부분은 잘못된 값이 어디에서 왔는지에 따라 달라집니다:998메시지의 첫 부분은 잘못된 값이 어디에서 왔는지에 따라 달라집니다.

990 999

991* `Invalid auth token`: [`ANTHROPIC_AUTH_TOKEN`](/docs/ko/env-vars) 또는 [`CLAUDE_CODE_OAUTH_TOKEN`](/docs/ko/env-vars)의 베어러 토큰1000* `Invalid auth token`: [`ANTHROPIC_AUTH_TOKEN`](/docs/ko/env-vars) 또는 [`CLAUDE_CODE_OAUTH_TOKEN`](/docs/ko/env-vars)의 bearer 토큰

992* `Invalid ANTHROPIC_CUSTOM_HEADERS`: [`ANTHROPIC_CUSTOM_HEADERS`](/docs/ko/env-vars)에서 설정한 헤더 이름 또는 값입니다. 설명은 `ANTHROPIC_CUSTOM_HEADERS`에서 구문 분석된 3개 중 2번째 고유 헤더와 같이 어떤 `Name: Value` 쌍이 잘못되었는지 계산하며, 이름이나 값을 반복하지 않습니다.1001* `Invalid ANTHROPIC_CUSTOM_HEADERS`: [`ANTHROPIC_CUSTOM_HEADERS`](/docs/ko/env-vars)에 설정한 헤더 이름 또는 값. 설명은 이름이나 값을 반복하지 않고 `distinct header 2 of 3 parsed from ANTHROPIC_CUSTOM_HEADERS`처럼 몇 번째 `Name: Value` 쌍에 문제가 있는지 알려 줍니다. 이름과 값은 모두 사용자가 직접 지정한 것이기 때문입니다.

993* `Invalid request header from the environment`: Claude Code가 `CLAUDE_AGENT_SDK_CLIENT_APP`과 같은 다른 환경 변수에서 요청 헤더로 복사하는 값입니다. 설명은 수정할 변수의 이름을 지정합니다.1002* `Invalid request header from the environment`: Claude Code가 `CLAUDE_AGENT_SDK_CLIENT_APP`과 같은 다른 환경 변수에서 요청 헤더로 복사하는 값. 설명에 수정해야 할 변수의 이름이 표시됩니다.

994 1003

995Claude Code는 이 확인으로 포착된 잘못된 `ANTHROPIC_API_KEY`를 [잘못된 API 키](#invalid-api-key)로 보고하며, 동일한 후행 설명이 있습니다. 잘못된 저장된 `/login` 자격증명을 [로그인하지 않음](#not-logged-in)으로 보고합니다. [`apiKeyHelper`](/docs/ko/settings-reference#apikeyhelper) 스크립트의 출력은 이 확인에 도달하지 않습니다: Claude Code는 스크립트가 실행될 때 유효성을 검사하며, HTTP 헤더가 전달할 수 없는 출력은 [apiKeyHelper 스크립트가 실패 중입니다](#your-apikeyhelper-script-is-failing)로 실패합니다.1004Claude Code는 이 검사에서 발견된 잘못된 `ANTHROPIC_API_KEY`를 동일한 후행 설명과 함께 [잘못된 API 키](#invalid-api-key)로 보고합니다. 저장된 `/login` 자격 증명이 잘못된 경우에는 대신 [로그인되지 않음](#not-logged-in)으로 보고합니다. `/login`을 실행하여 새 자격 증명을 저장하십시오. [`apiKeyHelper`](/docs/ko/settings-reference#apikeyhelper) 스크립트의 출력은 이 검사에 도달하지 않습니다. Claude Code는 스크립트가 실행될 때 출력을 검증하며, HTTP 헤더로 전달할 수 없는 출력은 [apiKeyHelper 스크립트 실패](#your-apikeyhelper-script-is-failing)로 실패합니다.

996 1005

997두 번째 `·` 이후에 메시지는 다음과 같은 전체 예제에서 문제를 설명합니다:1006두 번째 `·` 뒤에는 다음 전체 예시와 같이 메시지가 문제를 설명합니다.

998 1007

999```text theme={null}1008```text theme={null}

1000Invalid auth token · Fix external auth token · Invalid Authorization header value from ANTHROPIC_AUTH_TOKEN: it contains a line break at character 41 (120 characters on 2 lines).1009Invalid auth token · Fix external auth token · Invalid Authorization header value from ANTHROPIC_AUTH_TOKEN: it contains a line break at character 41 (120 characters on 2 lines).

1001```1010```

1002 1011

1003위치는 1부터 시작하는 문자를 계산합니다. 설명은 고정된 구문과 문자 수로 구성되므로 값 자체를 포함하지 않습니다. 바이트 순서 표시, 너비가 0인 공백 또는 곡선 따옴표와 같이 잘 알려진 보이지 않는 또는 인쇄 문자인 경우에만 잘못된 문자의 이름을 지정하며, 다른 모든 것을 `a non-ASCII character`로 보고합니다.1012위치는 1부터 시작하여 문자 수를 셉니다. 설명은 고정된 문구와 문자 수로 구성되므로 값 자체는 절대 포함되지 않습니다. 문제가 되는 문자가 바이트 순서 표시, 폭이 없는 공백, 둥근 따옴표처럼 잘 알려진 보이지 않는 문자나 타이포그래피 문자인 경우에만 해당 문자의 이름을 표시하며, 그 밖의 문자는 `a non-ASCII character`로 보고합니다.

1004 1013

1005**수행할 작업:**1014**해결 방법:**

1006 1015

1007* 메시지가 이름을 지정한 변수 또는 설정을 다시 설정하고, 동일한 소스에서 붙여넣는 대신 보고된 위치 주변의 문자를 다시 입력합니다.1016* 메시지가 가리키는 변수 또는 설정을 다시 설정하되, 같은 출처에서 다시 붙여 넣는 대신 보고된 위치 주변의 문자를 직접 다시 입력합니다

1008* `ANTHROPIC_CUSTOM_HEADERS`의 경우, 한 줄에 하나의 `Name: Value` 쌍을 유지하고 메시지가 계산하는 쌍을 다시 작성합니다.1017* `ANTHROPIC_CUSTOM_HEADERS`의 경우 한 줄에 `Name: Value` 쌍을 하나씩 두고, 메시지가 가리키는 쌍을 다시 작성합니다

1009* `/status`를 실행하여 어떤 자격증명 소스가 활성화되어 있는지 확인합니다.1018* `/status`를 실행하여 어떤 자격 증명 소스가 활성화되어 있는지 확인합니다

1010 1019

1011<h3 id="this-organization-has-been-disabled">1020<h3 id="this-organization-has-been-disabled">

1012 이 조직이 비활성화되었습니다1021 이 조직은 비활성화되었습니다

1013</h3>1022</h3>

1014 1023

1015Claude Code가 비활성화된 Console 조직의 오래된 `ANTHROPIC_API_KEY`를 사용 중입니다. 저장된 구독 로그인이 있으면 키가 이를 재정의합니다.1024Claude Code가 비활성화된 Console 조직의 오래된 `ANTHROPIC_API_KEY`를 사용하고 있습니다. 저장된 구독 로그인이 있는 경우 키가 이를 재정의합니다.

1016 1025

1017```text theme={null}1026```text theme={null}

1018Your ANTHROPIC_API_KEY belongs to a disabled organization · Unset the environment variable to use your subscription instead1027Your ANTHROPIC_API_KEY belongs to a disabled organization · Unset the environment variable to use your subscription instead

1020API Error: 400 ... This organization has been disabled.1029API Error: 400 ... This organization has been disabled.

1021```1030```

1022 1031

1023`·` 이후의 힌트는 저장된 자격증명에 따라 달라집니다: 첫 번째 형식은 저장된 `/login`이 키를 설정 해제한 후 인수할 수 있을 때 나타나고, 두 번째는 키가 유일한 자격증명일 때 나타납니다.1032`·` 뒤의 안내는 저장된 자격 증명에 따라 달라집니다. 첫 번째 형태는 키를 설정 해제한 후 저장된 `/login`이 대신 사용될 수 있을 때 나타나고, 두 번째 형태는 키가 유일한 자격 증명일 때 나타납니다.

1024 1033

1025환경 변수는 `/login`보다 우선순위를 가지므로, 셸 프로필에서 내보낸 키 또는 `.env` 파일에서 로드된 키는 작동하는 Pro 또는 Max 구독이 있어도 사용됩니다. 비대화형 모드(`-p`)에서는 키가 있을 때 항상 사용됩니다.1034환경 변수는 `/login`보다 우선하므로, 작동하는 Pro 또는 Max 구독이 있더라도 셸 프로필에서 export되었거나 `.env` 파일에서 로드된 키가 사용됩니다. 비대화형 모드(`-p`)에서는 키가 있으면 항상 사용됩니다.

1026 1035

1027**수행할 작업:**1036**해결 방법:**

1028 1037

1029* 현재 셸에서 `ANTHROPIC_API_KEY`를 설정 해제하고 셸 프로필에서 제거한 후 `claude`를 다시 실행합니다.1038* 현재 셸에서 `ANTHROPIC_API_KEY`를 설정 해제하고 셸 프로필에서 제거한 다음 `claude`를 다시 실행합니다

1030* 메시지가 `Update or unset`이라고 하면, 폴백할 저장된 로그인이 없습니다. 키를 설정 해제하고 `/login`을 실행하거나, 활성 Console 조직의 키로 바꿉니다.1039* 메시지에 `Update or unset`이라고 표시되면 대신 사용할 저장된 로그인이 없는 것입니다. 키를 설정 해제하고 `/login`을 실행하거나, 활성 Console 조직의 키로 교체합니다.

1031* 그 후 `/status`를 실행하여 활성 자격증명이 구독인지 확인합니다.1040* 이후 `/status`를 실행하여 활성 자격 증명이 구독인지 확인합니다

1032* 환경 변수가 설정되지 않았고 오류가 지속되면, 비활성화된 조직은 `/login`에 연결된 조직입니다. 지원팀에 문의하거나 다른 계정으로 로그인합니다.1041* 환경 변수가 설정되어 있지 않은데도 오류가 계속되면 지원팀에 문의하거나 다른 계정으로 로그인합니다.

1033 1042

1034<h3 id="your-organization-has-disabled-api-key-authentication">1043<h3 id="your-organization-has-disabled-api-key-authentication">

1035 조직이 API 키 인증을 비활성화했습니다1044 조직에서 API 키 인증을 비활성화함

1036</h3>1045</h3>

1037 1046

1038이 메시지는 Claude Code v2.1.169 이상이 필요합니다. Console 조직의 관리자가 API 키 인증을 비활성화했으므로 API가 Claude Code가 전송 중인 키를 거부합니다. 복구 힌트는 키가 어디에서 왔는지에 따라 `·` 이후에 달라집니다:1047이 메시지는 Claude Code v2.1.169 이상이 필요합니다. Console 조직의 관리자가 API 키 인증을 꺼 두었기 때문에 API가 Claude Code에서 전송하는 키를 거부합니다. `·` 뒤의 복구 안내는 키의 출처에 따라 다릅니다.

1039 1048

1040```text theme={null}1049```text theme={null}

1041Your organization has disabled API key authentication · Run /login to sign in with your claude.ai account1050Your organization has disabled API key authentication · Run /login to sign in with your claude.ai account

1045Your organization has disabled API key authentication · Sign in again with your claude.ai account1054Your organization has disabled API key authentication · Sign in again with your claude.ai account

1046```1055```

1047 1056

1048마지막 형식은 Claude Desktop 앱이 실행하는 세션(예: Code 탭 또는 Cowork)에 나타나며, 앱에서 다시 로그인합니다.1057마지막 형태는 Code 탭이나 Cowork처럼 Claude Desktop 앱이 실행하는 세션에서 나타나며, 이 경우 앱에서 다시 로그인합니다.

1049 1058

1050환경 변수와 `apiKeyHelper`는 `/login`보다 우선순위를 가지므로, 둘 중 하나가 여전히 키를 제공하는 동안 `/login`을 실행하는 것만으로는 도움이 되지 않습니다. [인증 우선순위](/docs/ko/authentication#authentication-precedence)를 참조합니다.1059환경 변수와 `apiKeyHelper`는 `/login`보다 우선하므로, 둘 중 하나가 여전히 키를 제공하는 동안에는 `/login`만 실행해서는 도움이 되지 않습니다. [인증 우선순위](/docs/ko/authentication#authentication-precedence)를 참조하십시오.

1051 1060

1052**수행할 작업:**1061**해결 방법:**

1053 1062

1054* 메시지가 `ANTHROPIC_API_KEY`의 이름을 지정하면, 현재 셸에서 설정을 해제하고 셸 프로필 또는 `.env` 파일에서 제거한 후 `claude`를 다시 실행합니다.1063* 메시지에 `ANTHROPIC_API_KEY`가 표시되면 현재 셸에서 설정 해제하고 셸 프로필 또는 `.env` 파일에서 제거한 다음 `claude`를 다시 실행합니다

1055* 메시지가 `apiKeyHelper`의 이름을 지정하면, `settings.json`에서 [`apiKeyHelper`](/docs/ko/settings-reference#apikeyhelper) 설정을 제거합니다.1064* 메시지에 `apiKeyHelper`가 표시되면 `settings.json`에서 [`apiKeyHelper`](/docs/ko/settings-reference#apikeyhelper) 설정을 제거합니다

1056* `/login`을 실행하여 claude.ai 계정으로 로그인합니다.1065* `/login`을 실행하여 claude.ai 계정으로 로그인합니다

1057* 그 후 `/status`를 실행하여 활성 자격증명이 API 키가 아닌 구독인지 확인합니다.1066* 이후 `/status`를 실행하여 활성 자격 증명이 API 키가 아닌 구독인지 확인합니다

1058* 자동화를 위해 API 키 인증이 필요하면, 조직 관리자에게 Console에서 이를 다시 활성화하도록 요청합니다.1067* 자동화를 위해 API 키 인증이 필요한 경우 조직 관리자에게 Console에서 다시 활성화해 달라고 요청합니다

1059 1068

1060<h3 id="your-organization-has-disabled-claude-subscription-access">1069<h3 id="your-organization-has-disabled-claude-subscription-access">

1061 조직이 Claude 구독 액세스를 비활성화했습니다1070 조직에서 Claude 구독 액세스를 비활성화함

1062</h3>1071</h3>

1063 1072

1064Claude 조직이 구독 로그인으로 Claude Code에 로그인하는 것을 허용하지 않습니다. 동일한 계정으로 `/login`을 다시 실행하면 동일한 오류가 반환됩니다.1073Claude 조직에서 구독 로그인으로 Claude Code에 로그인하는 것을 허용하지 않습니다. 동일한 계정으로 `/login`을 다시 실행하면 같은 오류가 반환됩니다.

1065 1074

1066```text theme={null}1075```text theme={null}

1067Your organization has disabled Claude subscription access for Claude Code · Use an Anthropic API key instead, or ask your admin to enable access1076Your organization has disabled Claude subscription access for Claude Code · Use an Anthropic API key instead, or ask your admin to enable access

1068```1077```

1069 1078

1070이것은 서버 측 조직 설정이므로 로컬 설정, 환경 변수 또는 CLI 플래그에서 재정의할 수 없습니다.1079이는 서버 측 조직 설정이므로 로컬 설정, 환경 변수 또는 CLI 플래그로 재정의할 수 없습니다.

1071 1080

1072Agent SDK 및 `-p` 비대화형 모드는 이를 `oauth_org_not_allowed` 오류 코드로 표시합니다.1081Agent SDK와 `-p` 비대화형 모드에서는 이를 `oauth_org_not_allowed` 오류 코드로 표시합니다.

1073 1082

1074**수행할 작업:**1083**해결 방법:**

1075 1084

1076* 조직 관리자에게 조직에 대한 Claude Code 액세스를 활성화하도록 요청합니다.1085* 관리자에게 조직의 Claude Code 액세스를 활성화해 달라고 요청합니다

1077* 구독 대신 Console API 키로 인증합니다. 설정은 [Claude Console 인증](/docs/ko/authentication#claude-console-authentication)을 참조합니다.1086* 구독 대신 Console API 키로 인증합니다. 설정 방법은 [Claude Console 인증](/docs/ko/authentication#claude-console-authentication)을 참조하십시오.

1078* 관리자이고 액세스를 활성화하는 옵션이 보이지 않으면, [Anthropic 지원](https://support.claude.com)에 문의합니다.1087* 본인이 관리자인데 액세스를 활성화하는 옵션이 보이지 않으면 [Anthropic 지원팀](https://support.claude.com)에 문의합니다

1079 1088

1080<h3 id="routines-are-disabled-by-your-organizations-policy">1089<h3 id="routines-are-disabled-by-your-organizations-policy">

1081 루틴이 조직의 정책에 의해 비활성화되었습니다1090 조직 정책에 의해 루틴이 비활성화됨

1082</h3>1091</h3>

1083 1092

1084Team 또는 Enterprise 조직의 Owner가 조직 수준에서 루틴을 비활성화했습니다. 오류는 예를 들어 claude.ai/code의 [루틴](/docs/ko/routines) UI에서 루틴을 생성하거나 실행하려고 할 때 나타납니다. Claude Code v2.1.227 이상에서는 동일한 설정이 CLI에서 [`/schedule`도 숨깁니다](/docs/ko/routines#troubleshooting).1093Team 또는 Enterprise 조직의 Owner가 조직 수준에서 루틴을 껐습니다. 이 오류는 claude.ai/code의 [루틴](/docs/ko/routines) UI 등에서 루틴을 만들거나 실행하려고 할 때 나타납니다. Claude Code v2.1.227 이상에서는 동일한 설정이 CLI에서 [`/schedule`도 숨깁니다](/docs/ko/routines#troubleshooting).

1085 1094

1086```text theme={null}1095```text theme={null}

1087Routines are disabled by your organization's policy.1096Routines are disabled by your organization's policy.

1088```1097```

1089 1098

1090이것은 서버 측 설정이므로 로컬 설정, 환경 변수 또는 CLI 플래그에서 재정의할 수 없습니다.1099이는 서버 측 설정이므로 로컬 설정, 환경 변수 또는 CLI 플래그로 재정의할 수 없습니다.

1091 1100

1092**수행할 작업:**1101**해결 방법:**

1093 1102

1094* 조직의 Owner에게 [claude.ai/admin-settings/claude-code](https://claude.ai/admin-settings/claude-code)에서 **루틴** 토글을 활성화하도록 요청합니다.1103* 조직의 Owner에게 [claude.ai/admin-settings/claude-code](https://claude.ai/admin-settings/claude-code)에서 **Routines** 토글을 활성화해 달라고 요청합니다

1095* 조직 수준의 루틴이 필요하지 않은 일회성 예약 작업의 경우, [예약된 작업](/docs/ko/scheduled-tasks)을 참조합니다.1104* 조직 수준 루틴이 필요하지 않은 일회성 예약 작업은 [예약 작업](/docs/ko/scheduled-tasks)을 참조하십시오

1096 1105

1097<h3 id="remote-control-requires-the-anthropic-api">1106<h3 id="remote-control-requires-the-anthropic-api">

1098 Remote Control에는 Anthropic API가 필요합니다1107 Remote Control에는 Anthropic API가 필요함

1099</h3>1108</h3>

1100 1109

1101세션이 Anthropic API와 직접 통신하지 않으므로 [Remote Control](/docs/ko/remote-control)이 필요로 하는 것입니다.1110세션이 Anthropic API와 직접 통신하지 않고 있으나, [Remote Control](/docs/ko/remote-control)에는 직접 통신이 필요합니다.

1102 1111

1103```text theme={null}1112```text theme={null}

1104Remote Control is only available when using Claude via api.anthropic.com. CLAUDE_CODE_USE_BEDROCK is set, so this session is using Amazon Bedrock — unset it (or run in a shell without it) to use Remote Control.1113Remote Control is only available when using Claude via api.anthropic.com. CLAUDE_CODE_USE_BEDROCK is set, so this session is using Amazon Bedrock — unset it (or run in a shell without it) to use Remote Control.

1105```1114```

1106 1115

1107두 번째 문장은 세션을 Anthropic API에서 멀어지게 한 것을 설명합니다. v2.1.219 이전에는 메시지가 첫 번째 문장만 있었습니다. 원인에 따라 메시지는 다음의 이름을 지정합니다:1116두 번째 문장은 무엇이 세션을 Anthropic API가 아닌 다른 곳으로 라우팅했는지 설명합니다. v2.1.219 이전에는 메시지가 첫 번째 문장만으로 구성되었습니다. 원인에 따라 메시지는 다음을 명시합니다.

1108 1117

1109* `CLAUDE_CODE_USE_BEDROCK`(예: [Amazon Bedrock](/docs/ko/amazon-bedrock)) 또는 `CLAUDE_CODE_USE_VERTEX`(예: [Google Cloud의 Agent Platform](/docs/ko/google-vertex-ai))와 같은 `CLAUDE_CODE_USE_*` 공급자 변수1118* [Amazon Bedrock](/docs/ko/amazon-bedrock)의 `CLAUDE_CODE_USE_BEDROCK` 또는 [Google Cloud's Agent Platform](/docs/ko/google-vertex-ai)의 `CLAUDE_CODE_USE_VERTEX`와 같은 `CLAUDE_CODE_USE_*` 제공업체 변수

1110* [`ANTHROPIC_BASE_URL`](/docs/ko/env-vars)이 `api.anthropic.com` 이외의 호스트를 가리키고 있습니다. 예를 들어 [LLM 게이트웨이](/docs/ko/llm-gateway) 또는 프록시이며, claude.ai로 로그인할 때도 마찬가지입니다. v2.1.196 이전에는 사용자 정의 기본 URL이 Remote Control을 차단하지 않았습니다.1119* claude.ai로 로그인한 경우에도 [LLM 게이트웨이](/docs/ko/llm-gateway)나 프록시처럼 `api.anthropic.com` 이외의 호스트를 가리키는 [`ANTHROPIC_BASE_URL`](/docs/ko/env-vars). v2.1.196 이전에는 사용자 지정 기본 URL이 Remote Control을 차단하지 않았습니다

1111* `ANTHROPIC_UNIX_SOCKET`이 설정되어 있으므로 세션이 `api.anthropic.com`이 아닌 로컬 소켓을 통해 요청을 전송합니다.1120* `ANTHROPIC_UNIX_SOCKET`이 설정되어 있어 세션이 `api.anthropic.com` 대신 로컬 소켓을 통해 요청을 전송하는 경우

1112* `/login`을 통한 엔터프라이즈 [클라우드 게이트웨이](/docs/ko/claude-apps-gateway) 로그인으로, Remote Control을 지원하지 않으며 설정 해제할 변수가 없습니다.1121* `/login`을 통해 이루어진 엔터프라이즈 [클라우드 게이트웨이](/docs/ko/claude-apps-gateway) 로그인. 이 로그인은 Remote Control을 지원하지 않으며 설정 해제할 변수가 없습니다

1113 1122

1114**수행할 작업:**1123**해결 방법:**

1115 1124

1116* 메시지가 이름을 지정한 변수(예: `CLAUDE_CODE_USE_BEDROCK` 또는 `ANTHROPIC_BASE_URL`)를 설정 해제하고 세션을 다시 시작하거나, Anthropic API와 직접 통신하는 세션에서 Remote Control을 시작합니다.1125* `CLAUDE_CODE_USE_BEDROCK` 또는 `ANTHROPIC_BASE_URL`처럼 메시지가 가리키는 변수를 설정 해제하고 세션을 다시 시작하거나, Anthropic API와 직접 통신하는 세션에서 Remote Control을 시작합니다

1117* 변수가 셸에 설정되지 않았으면, [설정 파일](/docs/ko/settings#where-settings-live)의 `env` 키를 확인합니다. 이는 모든 세션에 환경 변수를 적용합니다.1126* 셸에 변수가 설정되어 있지 않다면 모든 세션에 환경 변수를 적용하는 [설정 파일](/docs/ko/settings#where-settings-live)의 `env` 키를 확인합니다

1118* 이 및 다른 Remote Control 시작 메시지의 경우, [Remote Control 문제 해결](/docs/ko/remote-control#troubleshooting)을 참조합니다.1127* 이 메시지와 다른 Remote Control 시작 메시지에 대해서는 [Remote Control 문제 해결](/docs/ko/remote-control#troubleshooting)을 참조하십시오

1119 1128

1120<h3 id="remote-control-couldnt-refresh-your-login">1129<h3 id="remote-control-couldnt-refresh-your-login">

1121 Remote Control이 로그인을 새로 고칠 수 없습니다1130 Remote Control이 로그인을 갱신하지 못함

1122</h3>1131</h3>

1123 1132

1124Claude Code는 저장된 claude.ai 로그인을 사용하여 얻고 갱신하는 단기 자격증명에서 라이브 [Remote Control](/docs/ko/remote-control) 연결을 실행합니다. claude.ai가 해당 로그인을 더 이상 수락하지 않거나 Claude Code에 저장된 로그인이 남아 있지 않으면, Claude Code는 Remote Control을 중지하고 다시 로그인하도록 요청합니다. 두 실패 모두 Claude Code가 여전히 연결 중이거나 나중에 자격증명을 갱신할 때 발생할 수 있습니다.1133Claude Code는 저장된 claude.ai 로그인을 사용하여 얻고 갱신하는 단기 자격 증명으로 실시간 [Remote Control](/docs/ko/remote-control) 연결을 실행합니다. claude.ai가 해당 로그인을 더 이상 수락하지 않거나 Claude Code에 저장된 로그인이 남아 있지 않으면, Claude Code는 Remote Control을 중지하고 다시 로그인하도록 요구합니다. 두 실패 모두 Claude Code가 아직 연결 중일 때나 나중에 자격 증명을 갱신할 때 발생할 수 있습니다.

1125 1134

1126Claude Code가 로그인 서비스에 저장된 로그인을 새로 고치도록 요청하고 응답을 받지 못하면, Remote Control을 계속 실행하고 연결의 현재 자격증명이 여전히 유효한 동안 새로 고침을 다시 시도합니다. 새로 고침이 응답을 받지 못하는 경우는 Claude Code가 로그인 서비스에 도달할 수 없거나, 요청이 시간 초과되거나, 서비스가 로그인을 거부하지 않고 실패할 때입니다. 해당 자격증명이 만료될 때 로그인 서비스가 여전히 응답하지 않으면, Claude Code는 Remote Control을 중지하고 `OAuth token refresh failed`를 보고합니다.1135Claude Code가 로그인 서비스에 저장된 로그인 갱신을 요청했는데 응답을 받지 못하면, 연결의 현재 자격 증명이 아직 유효한 동안 Remote Control을 계속 실행하면서 갱신을 다시 시도합니다. Claude Code가 로그인 서비스에 연결할 수 없거나, 요청이 시간 초과되거나, 서비스가 로그인을 거부하지 않은 채 실패하면 갱신 응답을 받지 못합니다. 해당 자격 증명이 만료될 때까지 로그인 서비스가 여전히 응답하지 않으면 Claude Code는 Remote Control을 중지하고 `OAuth token refresh failed`를 보고합니다.

1127 1136

1128Claude Code가 Remote Control을 중지하면, 경고 및 `Remote Control disconnected`로 시작하는 기록 라인에 이유를 표시합니다. 로컬 세션은 Remote Control 없이 계속 실행됩니다. 이 섹션은 다음 라인을 다룹니다:1137Claude Code는 Remote Control을 중지할 때 경고와 `Remote Control disconnected`로 시작하는 트랜스크립트 줄에 이유를 표시합니다. 로컬 세션은 Remote Control 없이 계속 실행됩니다. 이 섹션에서는 다음 줄을 다룹니다.

1129 1138

1130```text theme={null}1139```text theme={null}

1131Remote Control disconnected — Claude.ai login expired — run /login to restore Remote Control1140Remote Control disconnected — Claude.ai login expired — run /login to restore Remote Control

1137Remote Control disconnected — Signed out of Claude — run /login, then /remote-control1146Remote Control disconnected — Signed out of Claude — run /login, then /remote-control

1138```1147```

1139 1148

1140Claude Code는 메시지의 중간에 원인의 이름을 지정합니다:1149Claude Code는 메시지 중간에 원인을 명시합니다.

1141 1150

1142* ` Claude.ai login expired` 및 `Claude.ai login was rejected`: claude.ai가 더 이상 저장된 로그인 토큰을 수락하지 않습니다. 만료되었거나 취소되었기 때문입니다.1151* `Claude.ai login expired` 및 `Claude.ai login was rejected`: 저장된 로그인 토큰이 만료되었거나 취소되어 claude.ai가 더 이상 이를 수락하지 않습니다

1143* ` OAuth token unavailable`: Claude Code가 연결의 자격증명이 갱신될 때 저장된 로그인 토큰이 없었습니다.1152* `OAuth token unavailable`: 연결의 자격 증명을 갱신해야 할 시점에 Claude Code에 저장된 로그인 토큰이 없었습니다

1144* `OAuth token refresh failed`: Claude Code가 다시 연결할 때 claude.ai가 저장된 로그인 토큰을 거부했으며, 토큰을 새로 고치면 새 토큰이 생성되지 않았습니다.1153* `OAuth token refresh failed`: Claude Code가 다시 연결하는 동안 claude.ai가 저장된 로그인 토큰을 거부했으며, 토큰 갱신으로 새 토큰을 얻지 못했습니다

1145* `JWT refresh failed: no OAuth token`: Claude Code가 갱신할 저장된 로그인 토큰을 찾지 못했습니다.1154* `JWT refresh failed: no OAuth token`: Claude Code가 갱신에 사용할 저장된 로그인 토큰을 찾지 못했습니다

1146* ` Signed out of Claude`: 예를 들어 다른 터미널에서 `/logout`을 실행하여 이 머신에서 로그아웃했으므로 Claude Code가 연결을 갱신할 저장된 로그인이 없습니다.1155* `Signed out of Claude`: 예를 들어 다른 터미널에서 `/logout`을 실행하는 등 이 컴퓨터에서 로그아웃했기 때문에, Claude Code에 연결을 갱신할 저장된 로그인이 남아 있지 않습니다

1147 1156

1148**수행할 작업:**1157**해결 방법:**

1149 1158

1150* `/login`을 실행하여 다시 로그인합니다.1159* `/login`을 실행하여 다시 로그인합니다

1151* `/remote-control`을 실행하여 세션을 다시 연결합니다. ` run /login to restore Remote Control`으로 끝나는 메시지는 이 단계가 필요하지 않습니다: Claude Code는 로그인하면 자동으로 다시 연결됩니다.1160* `/remote-control`을 실행하여 세션을 다시 연결합니다. `run /login to restore Remote Control`로 끝나는 메시지에서는 이 단계가 필요하지 않습니다. 로그인하면 Claude Code가 자동으로 다시 연결합니다.

1152 1161

1153v2.1.224 이전에는 `OAuth token refresh failed — run /login to re-authenticate`가 `OAuth token refresh failed — re-authenticate, then re-enable Remote Control`으로 읽혔으며, `JWT refresh failed: no OAuth token — run /login`이 `no OAuth token available for recovery (code <N>)`으로 읽혔습니다. ` Claude.ai login expired`, `Claude.ai login was rejected` 및 `OAuth token unavailable` 메시지는 v2.1.225에서 추가되었습니다.1162v2.1.224 이전에는 `OAuth token refresh failed — run /login to re-authenticate`가 `OAuth token refresh failed — re-authenticate, then re-enable Remote Control`로, `JWT refresh failed: no OAuth token — run /login`이 `no OAuth token available for recovery (code <N>)`로 표시되었습니다. `Claude.ai login expired`, `Claude.ai login was rejected`, `OAuth token unavailable` 메시지는 v2.1.225에서 추가되었습니다.

1154 1163

1155v2.1.238 이전에는 Claude Code가 현재 `Signed out of Claude`라고 하는 경우를 `JWT refresh failed: no OAuth token — run /login`으로 보고했으며, 한 번의 로그인 새로 고침이 응답을 받지 못하자마자 `Claude.ai login expired — run /login to restore Remote Control`으로 Remote Control을 중지했습니다.1164v2.1.238 이전에는 현재 `Signed out of Claude`로 표시되는 경우를 Claude Code가 `JWT refresh failed: no OAuth token — run /login`으로 보고했으며, 로그인 갱신에 한 번이라도 응답이 없으면 즉시 `Claude.ai login expired — run /login to restore Remote Control`과 함께 Remote Control을 중지했습니다.

1156 1165

1157<h3 id="remote-control-stopped-because-the-signed-in-account-changed">1166<h3 id="remote-control-stopped-because-the-signed-in-account-changed">

1158 Remote Control이 로그인한 계정이 변경되어 중지되었습니다1167 로그인한 계정이 변경되어 Remote Control이 중지됨

1159</h3>1168</h3>

1160 1169

1161Claude Code는 이 머신에서 다른 claude.ai 계정 또는 조직으로 로그인할 때 [Remote Control](/docs/ko/remote-control) 세션 중에 이 라인을 표시합니다. 예를 들어 다른 터미널에서 `/login`을 실행하여 Claude Code 세션 외부에서 전환했습니다.1170[Remote Control](/docs/ko/remote-control) 세션 중에 이 컴퓨터에서 다른 claude.ai 계정 또는 조직으로 로그인하면 Claude Code가 이 줄을 표시합니다. 예를 들어 다른 터미널에서 `/login`을 실행하는 등 Claude Code 세션 외부에서 전환한 경우입니다.

1162 1171

1163`/login`을 통해 로그인하는 동안 시작한 Remote Control 세션은 당시 로그인한 claude.ai 계정 및 조직에 속합니다.1172`/login`을 통해 로그인한 상태에서 시작한 Remote Control 세션은 그 당시 로그인되어 있던 claude.ai 계정과 조직에 속합니다.

1164 1173

1165```text theme={null}1174```text theme={null}

1166Remote Control disconnected — signed-in claude.ai account or organization changed on this machine — run /remote-control to start a session for the current account, or /login to switch back, then /remote-control1175Remote Control disconnected — signed-in claude.ai account or organization changed on this machine — run /remote-control to start a session for the current account, or /login to switch back, then /remote-control

1167```1176```

1168 1177

1169Claude Code는 claude.ai가 계정 또는 조직이 변경되었음을 확인하자마자 Remote Control 세션을 중지합니다. 로컬 세션은 Remote Control 없이 계속 실행됩니다.1178Claude Code는 claude.ai가 계정 또는 조직이 변경되었음을 확인하는 즉시 Remote Control 세션을 중지합니다. 로컬 세션은 Remote Control 없이 계속 실행됩니다.

1170 1179

1171**수행할 작업:**1180**해결 방법:**

1172 1181

1173* `/remote-control`을 실행하여 현재 계정 또는 조직에서 새 Remote Control 세션을 시작합니다.1182* `/remote-control`을 실행하여 현재 계정 또는 조직으로 새 Remote Control 세션을 시작합니다

1174* 다시 전환하려면, `/login`을 실행하고 이전 계정 또는 조직으로 다시 로그인합니다. 그런 다음 `/remote-control`을 실행합니다.1183* 다시 전환하려면 `/login`을 실행하고 이전 계정 또는 조직으로 다시 로그인합니다. 그런 다음 `/remote-control`을 실행합니다.

1175 1184

1176v2.1.234 이전에는 Claude Code가 Claude Code 세션 외부에서 다른 계정 또는 조직으로 전환할 때 알아차리지 못했습니다. Claude Code는 Remote Control 서버에 대한 나중의 요청이 `Remote Control server rejected the request (HTTP 404)`로 실패할 때까지 Remote Control 세션을 연결된 상태로 유지했습니다. 해당 실패는 전환 후 몇 시간이 지날 수 있습니다.1185v2.1.234 이전에는 Claude Code 세션 외부에서 다른 계정 또는 조직으로 전환해도 Claude Code가 이를 감지하지 못했습니다. Claude Code는 이후 Remote Control 서버에 대한 요청이 `Remote Control server rejected the request (HTTP 404)`로 실패할 때까지 Remote Control 세션의 연결을 유지했습니다. 이 실패는 전환 후 몇 시간이 지나서 발생할 수도 있었습니다.

1177 1186

1178<h3 id="remote-control-stopped-because-the-app-running-the-session-signed-out-or-switched-accounts">1187<h3 id="remote-control-stopped-because-the-app-running-the-session-signed-out-or-switched-accounts">

1179 Remote Control이 세션을 실행 중인 앱이 로그아웃하거나 계정을 전환하여 중지되었습니다1188 세션을 실행하는 앱이 로그아웃하거나 계정을 전환하여 Remote Control이 중지됨

1180</h3>1189</h3>

1181 1190

1182Claude 데스크톱 앱 또는 IDE가 세션을 호스팅할 때, Claude Code는 `/login`이 아닌 해당 앱에서 로그인 토큰을 가져옵니다. claude.ai가 해당 토큰을 거부할 때, Claude Code는 앱에 새 토큰을 요청합니다. 앱이 로그아웃했거나 이제 다른 Claude 계정으로 로그인했다고 응답하면, Claude Code는 [Remote Control](/docs/ko/remote-control) 세션을 종료하고 앱에 다음 라인 중 하나를 보냅니다:1191Claude 데스크톱 앱이나 IDE가 세션을 호스팅하는 경우, Claude Code는 `/login`이 아닌 해당 앱에서 로그인 토큰을 받습니다. claude.ai가 그 토큰을 거부하면 Claude Code는 앱에 새 토큰을 요청합니다. 앱이 로그아웃 상태라고 응답하거나 현재 다른 Claude 계정으로 로그인되어 있다고 응답하면, Claude Code는 [Remote Control](/docs/ko/remote-control) 세션을 종료하고 앱에 다음 줄 중 하나를 전송합니다.

1183 1192

1184```text theme={null}1193```text theme={null}

1185Remote Control stopped — the app running this session is now signed in to a different Claude account1194Remote Control stopped — the app running this session is now signed in to a different Claude account

1188 1197

1189로컬 세션은 Remote Control 없이 계속 실행됩니다.1198로컬 세션은 Remote Control 없이 계속 실행됩니다.

1190 1199

1191**수행할 작업:**1200**해결 방법:**

1192 1201

1193* 앱이 로그아웃했으면, 다시 로그인한 후 앱에서 Remote Control을 다시 켭니다.1202* 앱이 로그아웃된 경우 앱에 다시 로그인한 다음 앱에서 Remote Control을 다시 켭니다

1194* 앱이 계정을 전환했으면, Claude Code는 새 계정에서 종료된 세션을 계속할 수 없습니다. 해당 계정에서 새 Remote Control 세션을 시작합니다.1203* 앱이 계정을 전환한 경우 Claude Code는 종료된 세션을 새 계정으로 계속할 수 없습니다. 해당 계정으로 새 Remote Control 세션을 시작합니다.

1195 1204

1196v2.1.238 이전에는 Claude Code가 두 경우 모두에서 앱에 [Remote Control이 로그인을 새로 고칠 수 없습니다](#remote-control-couldnt-refresh-your-login)에 나열된 `run /login` 메시지를 보냈습니다.1205v2.1.238 이전에는 두 경우 모두 Claude Code가 [Remote Control이 로그인을 갱신하지 못함](#remote-control-couldnt-refresh-your-login)에 나열된 `run /login` 메시지를 앱에 전송했습니다.

1197 1206

1198<h3 id="oauth-token-revoked-or-expired">1207<h3 id="oauth-token-revoked-or-expired">

1199 OAuth 토큰이 취소되었거나 만료되었습니다1208 OAuth 토큰 취소 또는 만료

1200</h3>1209</h3>

1201 1210

1202저장된 로그인이 더 이상 유효하지 않습니다. 취소된 토큰은 어디서나 로그아웃했거나 관리자가 액세스를 제거했음을 의미합니다. 만료된 토큰은 자동 새로 고침이 세션 중에 실패했음을 의미합니다.1211저장된 로그인이 더 이상 유효하지 않습니다. 토큰이 취소되었다면 모든 곳에서 로그아웃했거나 관리자가 액세스 권한을 제거한 것이고, 토큰이 만료되었다면 세션 중에 자동 갱신이 실패한 것입니다.

1203 1212

1204두 메시지 모두 Claude Code가 전송한 요청에 대해 API가 반환한 거부를 보고합니다. 저장된 로그인이 실패한 새로 고침 후 이미 지워진 경우, 대신 [로그인 만료됨](#login-expired)을 봅니다. [`CLAUDE_CODE_OAUTH_TOKEN`](/docs/ko/env-vars)에서 장기 토큰으로 인증하면, 해당 토큰이 만료되거나 취소될 때 동일한 메시지가 표시됩니다.1213두 메시지 모두 Claude Code가 전송한 요청에 대해 API가 반환한 거부를 보고합니다. 갱신 실패 후 저장된 로그인이 이미 삭제된 경우에는 대신 [로그인 만료](#login-expired)가 표시됩니다. [`CLAUDE_CODE_OAUTH_TOKEN`](/docs/ko/env-vars)의 장기 토큰으로 인증하는 경우에도 해당 토큰이 만료되거나 취소되면 동일한 메시지가 표시됩니다.

1205 1214

1206```text theme={null}1215```text theme={null}

1207OAuth token revoked · Please run /login1216OAuth token revoked · Please run /login

1208Please run /login · API Error: 401 OAuth token has expired ...1217Please run /login · API Error: 401 OAuth token has expired ...

1209```1218```

1210 1219

1211**수행할 작업:**1220**해결 방법:**

1212 1221

1213* `/login`을 실행하여 다시 로그인합니다.1222* `/login`을 실행하여 다시 로그인합니다

1214* ` CLAUDE_CODE_OAUTH_TOKEN` 환경 변수로 인증하면, Claude Code는 요청이 401로 실패한 후 설정한 값을 계속 전송하며, 저장된 로그인의 토큰으로 전환하지 않습니다. [`/status`](/docs/ko/commands)는 이 자격증명을 `Auth token` 행으로 표시하며 `CLAUDE_CODE_OAUTH_TOKEN`을 읽습니다. [`claude setup-token`](/docs/ko/authentication#generate-a-long-lived-token)으로 새 토큰을 생성하고 이를 사용하여 다시 시작하거나, 변수를 설정 해제하고 `/login`을 실행합니다. v2.1.225 이전에는 Claude Code가 세션 중에 변수의 값을 저장된 로그인의 단기 액세스 토큰으로 바꿀 수 있었으며, 해당 토큰이 만료되면 세션이 다시 401 오류로 실패했습니다.1223* `CLAUDE_CODE_OAUTH_TOKEN` 환경 변수로 인증하는 경우, 요청이 401로 실패한 후에도 Claude Code는 저장된 로그인의 토큰으로 전환하지 않고 사용자가 설정한 값을 계속 전송합니다. [`/status`](/docs/ko/commands)는 이 자격 증명을 `CLAUDE_CODE_OAUTH_TOKEN`이라고 표시된 `Auth token` 행으로 보여 줍니다. [`claude setup-token`](/docs/ko/authentication#generate-a-long-lived-token)으로 새 토큰을 생성하고 해당 토큰으로 다시 시작하거나, 변수를 설정 해제하고 `/login`을 실행합니다. v2.1.225 이전에는 Claude Code가 세션 도중 변수의 값을 저장된 로그인의 단기 액세스 토큰으로 대체할 수 있었으며, 그 토큰이 만료되면 세션이 다시 401 오류로 실패했습니다.

1215* 시작 간 반복적인 로그인 프롬프트의 경우, [로그인하지 않음 또는 토큰 만료됨](/docs/ko/troubleshoot-install#not-logged-in-or-token-expired)의 시스템 시계 확인 및 macOS 자격증명 저장소 복구 단계를 참조합니다.1224* 실행할 때마다 로그인하라는 메시지가 반복되는 경우 [문제 해결](/docs/ko/troubleshoot-install#not-logged-in-or-token-expired)의 시스템 시계 확인 및 macOS 자격 증명 저장소 복구 단계를 참조하십시오

1216* `403 Forbidden` 및 OAuth 브라우저 문제를 포함한 다른 실패의 경우, [로그인 및 인증](/docs/ko/troubleshoot-install#login-and-authentication)을 참조합니다.1225* `403 Forbidden` 및 OAuth 브라우저 문제를 포함한 기타 실패는 [로그인 및 인증](/docs/ko/troubleshoot-install#login-and-authentication)을 참조하십시오

1217 1226

1218<h3 id="api-error-401-invalid-authentication-credentials">1227<h3 id="api-error-401-invalid-authentication-credentials">

1219 API 오류: 401 잘못된 인증 자격증명1228 API Error: 401 Invalid authentication credentials

1220</h3>1229</h3>

1221 1230

1222API가 자격증명의 형식을 인식했지만 뒤에 있는 계정 또는 조직을 거부했습니다. Anthropic은 자격증명이 최근에 취소되었거나, 조직이 비활성화되었거나 액세스를 제거했거나, 계정 자체가 비활성화되었을 때 이 메시지를 반환하므로, 만료된 토큰이 원인이 아닙니다. 자격증명은 저장된 로그인 또는 승인된 `ANTHROPIC_API_KEY`일 수 있으며, 수정이 다르므로 `/status`를 실행하여 어떤 것이 활성화되어 있는지 확인하여 시작합니다.1231API가 자격 증명의 형식은 인식했지만 그 뒤에 있는 계정 또는 조직을 거부했습니다. Anthropic은 자격 증명이 최근에 취소되었거나, 조직이 비활성화되었거나 사용자의 액세스 권한을 제거했거나, 계정 자체가 비활성화되었을 때 이 메시지를 반환하므로, 토큰 만료는 원인이 아닙니다. 자격 증명은 저장된 로그인일 수도 있고 승인된 `ANTHROPIC_API_KEY`일 수도 있으며 해결 방법이 다르므로, 먼저 `/status`를 실행하여 어떤 것이 활성화되어 있는지 확인하십시오.

1223 1232

1224```text theme={null}1233```text theme={null}

1225Please run /login · API Error: 401 Invalid authentication credentials1234Please run /login · API Error: 401 Invalid authentication credentials

1226```1235```

1227 1236

1228**수행할 작업:**1237**해결 방법:**

1229 1238

1230* `/status`가 사용 중이 아닌 것으로 표시되지 않은 `API key` 행을 표시하면, 승인된 [`ANTHROPIC_API_KEY`](/docs/ko/authentication#authentication-precedence)가 활성 자격증명이며 로그인보다 우선순위를 가지므로 `/login`이 이를 바꾸지 않습니다. Claude Console에서 키를 회전하거나, `unset ANTHROPIC_API_KEY`를 실행하거나, PowerShell에서 `Remove-Item Env:ANTHROPIC_API_KEY`를 실행하여 구독으로 폴백합니다.1239* `/status`에 사용 중이 아니라고 표시되지 않은 `API key` 행이 있으면, 승인된 [`ANTHROPIC_API_KEY`](/docs/ko/authentication#authentication-precedence)가 활성 자격 증명이며 로그인보다 우선하므로 `/login`으로 대체되지 않습니다. Claude Console에서 키를 교체하거나, `unset ANTHROPIC_API_KEY`(PowerShell에서는 `Remove-Item Env:ANTHROPIC_API_KEY`)를 실행하여 구독으로 되돌립니다.

1231* `/status`가 로그인만 표시하면, `/login`을 한 번 실행합니다. 자격증명이 취소되었으면, 새 로그인이 이를 바꿉니다.1240* `/status`에 로그인만 표시되면 `/login`을 한 번 실행합니다. 자격 증명이 취소된 경우 새 로그인이 이를 대체합니다.

1232* 동일한 로그인 계정에 대해 동일한 메시지가 반환되면, 계정 또는 조직이 더 이상 활성화되지 않습니다. `/status`가 보고하는 계정 및 조직을 확인하고, 조직 관리자에게 액세스를 복구하도록 요청합니다.1241* 동일한 로그인 계정에 대해 같은 메시지가 다시 나타나면 해당 계정 또는 조직이 더 이상 활성 상태가 아닙니다. `/status`가 보고하는 계정과 조직을 확인하고 조직 관리자에게 액세스 권한 복원을 요청합니다.

1233* [`ANTHROPIC_BASE_URL`](/docs/ko/env-vars)이 [LLM 게이트웨이](/docs/ko/llm-gateway)를 가리키면, `401` 이후의 텍스트는 Anthropic의 메시지가 아닌 게이트웨이의 메시지이며, `/login`이 이를 변경하지 않습니다. 게이트웨이가 예상하는 자격증명을 대신 수정합니다.1242* [`ANTHROPIC_BASE_URL`](/docs/ko/env-vars)이 [LLM 게이트웨이](/docs/ko/llm-gateway)를 가리키는 경우, `401` 뒤의 텍스트는 Anthropic이 아닌 게이트웨이의 메시지이며 `/login`으로는 바뀌지 않습니다. 대신 게이트웨이가 요구하는 자격 증명을 수정합니다.

1234 1243

1235<h3 id="login-expired">1244<h3 id="login-expired">

1236 로그인 만료됨1245 로그인 만료

1237</h3>1246</h3>

1238 1247

1239Claude Code가 저장된 claude.ai 또는 Claude Console 로그인을 갱신하려고 했으며 OAuth 서비스가 저장된 새로 고침 토큰을 거부했으므로, Claude Code가 저장된 자격증명을 지웠습니다. 그 후, 각 모델 요청은 `/login`만 새 자격증명을 만들 수 있으므로 API에 도달하기 전에 로컬에서 이 메시지로 중지됩니다.1248Claude Code가 저장된 claude.ai 로그인을 갱신하려고 했으나 OAuth 서비스가 저장된 갱신 토큰을 거부하여, Claude Code가 저장된 자격 증명을 삭제했습니다. 그 이후에는 `/login`만 새 자격 증명을 만들 수 있으므로, 각 모델 요청이 API에 도달하기 전에 로컬에서 이 메시지와 함께 중단됩니다.

1240 1249

1241v2.1.206 이전에는 Claude Code가 환경에 남아 있는 모든 자격증명으로 모델 요청을 어쨌든 전송했으며, 모든 모델이 로그인하라는 프롬프트 대신 [선택한 모델에 문제가 있습니다](#theres-an-issue-with-the-selected-model) 또는 401로 실패했습니다.1250v2.1.206 이전에는 Claude Code가 환경에 남아 있는 자격 증명으로 모델 요청을 그대로 전송했으며, 그 결과 모든 모델이 로그인하라는 안내 대신 [선택한 모델에 문제가 있음](#theres-an-issue-with-the-selected-model) 또는 401로 실패했습니다.

1242 1251

1243```text theme={null}1252```text theme={null}

1244Login expired · Please run /login1253Login expired · Please run /login

1245```1254```

1246 1255

1247[비대화형 모드](/docs/ko/headless)(`-p`) 및 [Agent SDK](/docs/ko/agent-sdk/overview)에서 메시지는 다음과 같이 읽으며, 구조화된 오류 코드는 `authentication_failed`입니다:1256[비대화형 모드](/docs/ko/headless)(`-p`)와 [Agent SDK](/docs/ko/agent-sdk/overview)에서는 메시지가 다음과 같이 표시되며, 구조화된 오류 코드는 `authentication_failed`입니다.

1248 1257

1249```text theme={null}1258```text theme={null}

1250Failed to authenticate: OAuth session expired and could not be refreshed1259Failed to authenticate: OAuth session expired and could not be refreshed

1251```1260```

1252 1261

1253이것은 [OAuth 토큰이 취소되었거나 만료되었습니다](#oauth-token-revoked-or-expired)와 동일한 상태가 아닙니다. 이러한 메시지는 API가 반환한 거부를 보고합니다. Claude Code 자체는 이미 갱신하지 못한 로그인에 대해 `Login expired`를 생성하므로, 요청을 전송하지 않습니다. 계정 자체가 일시 중단되었기 때문에 갱신이 실패하면, Claude Code는 대신 [계정이 보류 중입니다](#your-account-is-on-hold)를 표시합니다.1262이는 [OAuth 토큰 취소 또는 만료](#oauth-token-revoked-or-expired)와 같은 상태가 아닙니다. 해당 메시지는 API가 반환한 거부를 보고합니다. `Login expired`는 이미 갱신에 실패한 로그인에 대해 Claude Code 자체가 생성하므로 요청을 전송하지 않습니다. 로그인이 오래되어서가 아니라 계정 자체가 정지되어 갱신이 실패한 경우에는 Claude Code가 대신 [계정이 보류됨](#your-account-is-on-hold)을 표시합니다.

1254 1263

1255API 키, [`CLAUDE_CODE_OAUTH_TOKEN`](/docs/ko/env-vars) 또는 타사 공급자로 인증된 세션은 저장된 로그인을 사용하지 않으며 이 메시지를 절대 보지 않습니다.1264API 키, [`CLAUDE_CODE_OAUTH_TOKEN`](/docs/ko/env-vars) 또는 타사 제공업체로 인증된 세션은 저장된 로그인을 사용하지 않으므로 이 메시지가 표시되지 않습니다.

1256 1265

1257요청이 실패하기 전에 이 상태를 확인할 수 있습니다: [`/status`](/docs/ko/commands)는 `Login` 행을 표시하며 `Expired — log in again`을 읽고, 만료된 로그인에 대해 저장한 조직 및 이메일을 표시합니다. 행은 저장된 로그인이 활성 자격증명이고 더 이상 갱신할 수 없을 때만 나타납니다. 다른 방식으로 인증된 세션은 만료된 로그인이 저장되어 있어도 행을 표시하지 않습니다. v2.1.210 이전에는 `/status`가 이 상태에서 로그인이 존재했던 적이 있다는 표시를 주지 않았습니다. 지워진 자격증명이 보고할 것이 없었기 때문입니다.1266요청이 실패하기 전에 이 상태를 확인할 수 있습니다. [`/status`](/docs/ko/commands)에 `Expired — log in again`이라고 표시된 `Login` 행과 함께 만료된 로그인에 대해 저장된 조직 및 이메일이 표시됩니다. 이 행은 저장된 로그인이 활성 자격 증명이고 더 이상 갱신할 수 없는 경우에만 나타납니다. 다른 방식으로 인증된 세션에서는 만료된 로그인이 저장되어 있더라도 이 행이 표시되지 않습니다. v2.1.210 이전에는 자격 증명이 삭제되어 보고할 내용이 없었기 때문에, 이 상태에서 `/status`에 로그인이 존재했었다는 표시가 전혀 없었습니다.

1258 1267

1259**수행할 작업:**1268**해결 방법:**

1260 1269

1261* `/login`을 실행하여 다시 로그인합니다. 로그인하지 않고 재시도하면 모든 요청에서 동일한 메시지가 표시됩니다.1270* `/login`을 실행하여 다시 로그인합니다. 로그인하지 않고 재시도하면 모든 요청에서 같은 메시지가 표시됩니다.

1262* 비대화형 모드에서는 동일한 환경에서 `claude`를 실행하고, `/login`을 완료한 후 명령을 다시 실행합니다. 대화형으로 로그인할 수 없는 자동화의 경우, `ANTHROPIC_API_KEY`로 인증하거나 [`claude setup-token`](/docs/ko/authentication#generate-a-long-lived-token)으로 장기 토큰을 생성합니다.1271* 다른 Claude Code 창에서 claude.ai 계정으로 로그인하는 경우, 이 세션이 언제 자동으로 해당 로그인을 사용하기 시작하는지는 [로그인되지 않음](#not-logged-in)을 참조하십시오.

1263* 로그인이 계속 실패하면, [로그인 및 인증](/docs/ko/troubleshoot-install#login-and-authentication)을 참조합니다.1272* 비대화형 모드에서는 동일한 환경에서 `claude`를 실행하고 `/login`을 완료한 다음 명령을 다시 실행합니다. 대화형으로 로그인할 수 없는 자동화 환경에서는 `ANTHROPIC_API_KEY`로 인증하거나 [`claude setup-token`으로 장기 토큰을 생성](/docs/ko/authentication#generate-a-long-lived-token)합니다.

1273* 로그인이 계속 실패하면 [로그인 및 인증](/docs/ko/troubleshoot-install#login-and-authentication)을 참조하십시오

1264 1274

1265<h3 id="could-not-refresh-your-login">1275<h3 id="could-not-refresh-your-login">

1266 다른 Claude Code 프로세스가 로그인을 새로 고치고 있어서 로그인을 새로 고칠 수 없습니다1276 다른 Claude Code 프로세스가 로그인을 갱신하고 있어 갱신할 수 없음

1267</h3>1277</h3>

1268 1278

1269이 메시지는 로그인이 거부되었다는 의미가 아닙니다. 저장된 claude.ai 로그인이 만료되었으며 갱신이 필요했습니다. 동일한 머신의 다른 Claude Code 프로세스가 공유 새로 고침 잠금을 보유했거나, 종료되고 뒤에 남겨두었으며, 이 세션이 기다리는 동안 새로 고침이 진행되지 않았습니다. Claude Code는 전송하기 전에 요청을 중지합니다:1279이 메시지는 로그인이 거부되었다는 의미가 아닙니다. 저장된 claude.ai 로그인이 만료되어 갱신이 필요했습니다. 동일한 컴퓨터의 다른 Claude Code 프로세스가 공유 갱신 잠금을 보유하고 있었거나 잠금을 남겨 둔 채 종료되었고, 이 세션이 기다리는 동안 갱신이 진행되지 않았습니다. Claude Code는 요청을 전송하기 전에 중단합니다.

1270 1280

1271```text theme={null}1281```text theme={null}

1272Could not refresh your login because another Claude Code process is refreshing it (or exited mid-refresh) · Try again in a minute; if it keeps happening, close other Claude Code windows or sign in again with /login1282Could not refresh your login because another Claude Code process is refreshing it (or exited mid-refresh) · Try again in a minute; if it keeps happening, close other Claude Code windows or sign in again with /login

1273```1283```

1274 1284

1275[비대화형 모드](/docs/ko/headless)(`-p`) 및 [Agent SDK](/docs/ko/agent-sdk/overview)에서 메시지는 다음과 같이 읽으며, 구조화된 오류 코드는 `server_error`입니다:1285[비대화형 모드](/docs/ko/headless)(`-p`)와 [Agent SDK](/docs/ko/agent-sdk/overview)에서는 메시지가 다음과 같이 표시되며, 구조화된 오류 코드는 `server_error`입니다.

1276 1286

1277```text theme={null}1287```text theme={null}

1278Failed to refresh OAuth token: another Claude Code process is refreshing it or exited mid-refresh. This is usually transient; retry in a minute, and if it persists close other Claude Code processes or sign in again1288Failed to refresh OAuth token: another Claude Code process is refreshing it or exited mid-refresh. This is usually transient; retry in a minute, and if it persists close other Claude Code processes or sign in again

1279```1289```

1280 1290

1281API 키, [`CLAUDE_CODE_OAUTH_TOKEN`](/docs/ko/env-vars) 또는 타사 공급자로 인증된 세션은 저장된 로그인을 사용하지 않으며 이 메시지를 절대 보지 않습니다.1291API 키, [`CLAUDE_CODE_OAUTH_TOKEN`](/docs/ko/env-vars) 또는 타사 제공업체로 인증된 세션은 저장된 로그인을 사용하지 않으므로 이 메시지가 표시되지 않습니다.

1282 1292

1283**수행할 작업:**1293**해결 방법:**

1284 1294

1285* 1분 후에 다시 시도합니다. 다른 프로세스가 먼저 새로 고침을 완료하면, 이 세션이 갱신된 로그인을 사용합니다.1295* 1분 후에 다시 시도합니다. 다른 프로세스가 먼저 갱신을 완료하면 이 세션은 갱신된 로그인을 사용합니다.

1286* 메시지가 계속 반환되면, 다른 Claude Code 창과 프로세스를 닫은 후 재시도합니다.1296* 메시지가 계속 나타나면 다른 Claude Code 창과 프로세스를 닫은 다음 재시도합니다.

1287* 다른 Claude Code 프로세스가 실행 중이지 않은 상태에서 반환되면, `/login`을 실행합니다. 다시 로그인하면 새로 고침 잠금을 기다리지 않습니다.1297* 실행 중인 다른 Claude Code 프로세스가 없는데도 메시지가 나타나면 `/login`을 실행합니다. 다시 로그인하는 것은 갱신 잠금을 기다리지 않습니다.

1288 1298

1289<h3 id="couldnt-save-your-login">1299<h3 id="couldnt-save-your-login">

1290 로그인을 저장할 수 없습니다1300 로그인을 저장할 수 없음

1291</h3>1301</h3>

1292 1302

1293claude.ai로 로그인했지만 Claude Code가 로그인을 자격증명 저장소에 저장할 수 없어서, 로그인이 완료되지 않았습니다. macOS에서는 예를 들어 절전 또는 유휴 후 로그인 키체인이 잠길 때 발생할 수 있으며, Claude Code가 동일한 세션 중에 이미 자격증명을 읽거나 저장한 후입니다.1303claude.ai로 로그인했지만 Claude Code가 로그인을 자격 증명 저장소에 저장할 수 없어서 로그인이 완료되지 않았습니다. macOS에서는 같은 세션 중에 Claude Code가 이미 로그인 키체인에서 자격 증명을 읽거나 저장한 후, 예를 들어 절전이나 유휴 상태로 인해 키체인이 잠기면 이런 상황이 발생할 수 있습니다.

1294 1304

1295```text theme={null}1305```text theme={null}

1296Couldn't save your login. If your Mac's keychain is locked, unlock it and log in again.1306Couldn't save your login. If your Mac's keychain is locked, unlock it and log in again.

1297Couldn't save your login. Try logging in again.1307Couldn't save your login. Try logging in again.

1298```1308```

1299 1309

1300첫 번째 형식은 macOS에 나타나고 두 번째는 다른 곳에 나타납니다. 시간 초과 또는 읽을 수 없는 저장소와 같은 일시적인 자격증명 저장소 실패는 동일한 메시지를 생성합니다.1310첫 번째 형태는 macOS에서, 두 번째 형태는 그 외의 모든 환경에서 나타납니다. 시간 초과나 읽을 수 없는 저장소와 같은 일시적인 자격 증명 저장소 실패도 같은 메시지를 생성합니다.

1301 1311

1302**수행할 작업:**1312**해결 방법:**

1303 1313

1304* macOS에서 로그인 키체인을 잠금 해제한 후 `/login`을 다시 실행합니다.1314* macOS에서는 로그인 키체인의 잠금을 해제한 다음 `/login`을 다시 실행합니다

1305* 다른 플랫폼에서 `/login`을 다시 실행합니다.1315* 다른 플랫폼에서는 `/login`을 다시 실행합니다

1306* 로그인이 여전히 저장되지 않으면, [로그인하지 않음 또는 토큰 만료됨](/docs/ko/troubleshoot-install#not-logged-in-or-token-expired)에서 키체인 잠금 해제 명령 및 기타 자격증명 저장소 복구 단계를 참조합니다.1316* 그래도 로그인이 저장되지 않으면 키체인 잠금 해제 명령과 기타 자격 증명 저장소 복구 단계에 대해 [로그인되지 않음 또는 토큰 만료](/docs/ko/troubleshoot-install#not-logged-in-or-token-expired)를 참조하십시오

1307 1317

1308<h3 id="failed-to-start-oauth-callback-server">1318<h3 id="failed-to-start-oauth-callback-server">

1309 Failed to start OAuth callback server1319 OAuth 콜백 서버를 시작하지 못함

1310</h3>1320</h3>

1311 1321

1312`/login`, `claude auth login` 또는 `claude setup-token`이 브라우저를 통해 로그인할 때, Claude Code는 `127.0.0.1`에서 수신 포트를 열어서 브라우저가 로그인 결과를 반환할 수 있도록 합니다. 이 메시지는 Claude Code가 해당 포트를 열 수 없었으며, 로그인이 브라우저 창 또는 로그인 URL이 나타나기 전에 중지됨을 의미합니다:1322`/login`, `claude auth login` 또는 `claude setup-token`이 브라우저를 통해 로그인을 진행할 때, Claude Code는 브라우저가 로그인 결과를 돌려보낼 수 있도록 `127.0.0.1`에서 수신 대기 포트를 엽니다. 이 메시지는 Claude Code가 해당 포트를 열 수 없었다는 의미이며, 브라우저 창이나 로그인 URL이 나타나기 전에 로그인이 중단됩니다.

1313 1323

1314```text theme={null}1324```text theme={null}

1315Failed to start OAuth callback server: Failed to start server. Is port 0 in use?1325Failed to start OAuth callback server: Failed to start server. Is port 0 in use?

1316```1326```

1317 1327

1318메시지가 `Is port 0 in use?`로 끝나면, IPv4 루프백 주소 `127.0.0.1`에서 수신하려는 시도가 완전히 실패했습니다. 실패가 로그인 URL이 존재하기 전에 발생하므로, `Paste code here if prompted` 흐름은 해결책으로 사용할 수 없습니다.1328메시지가 `Is port 0 in use?`로 끝나면 IPv4 루프백 주소 `127.0.0.1`에서 수신 대기하려는 시도가 완전히 실패한 것입니다. 로그인 URL이 생성되기 전에 실패가 발생하므로 `Paste code here if prompted` 흐름을 우회 방법으로 사용할 수 없습니다.

1319 1329

1320**수행할 작업:**1330**해결 방법:**

1321 1331

1322* 로컬 리스너 없이 지금 바로 로그인하려면: claude.ai 구독을 사용하면, 로그인이 작동하는 머신에서 [`claude setup-token`](/docs/ko/authentication#generate-a-long-lived-token)을 실행하고 인쇄하는 토큰을 이 머신에서 `CLAUDE_CODE_OAUTH_TOKEN`으로 설정합니다. 그렇지 않으면 [Claude Console](https://platform.claude.com/settings/keys)의 키로 `ANTHROPIC_API_KEY`를 설정합니다. [인증 우선순위](/docs/ko/authentication#authentication-precedence)는 Claude Code가 여러 자격증명 중에서 선택하는 방식을 설명합니다.1332* 로컬 리스너 없이 즉시 로그인하려면: claude.ai 구독을 사용하는 경우 로그인이 작동하는 컴퓨터에서 [`claude setup-token`](/docs/ko/authentication#generate-a-long-lived-token)을 실행하고, 출력된 토큰을 이 컴퓨터에서 `CLAUDE_CODE_OAUTH_TOKEN`으로 설정합니다. 그렇지 않으면 `ANTHROPIC_API_KEY`를 [Claude Console](https://platform.claude.com/settings/keys)의 키로 설정합니다. Claude Code가 자격 증명 중에서 선택하는 방식은 [인증 우선순위](/docs/ko/authentication#authentication-precedence)에 설명되어 있습니다.

1323* 대신 이 머신에서 브라우저 로그인을 사용하려면, Claude Code가 `127.0.0.1`에서 수신할 수 있어야 합니다. 샌드박스 내에서 실행되면, 샌드박스의 정책이 로컬 포트에서 수신하도록 허용하는지 확인한 후 `/login`을 다시 실행합니다. 할 수 있어야 하는데도 여전히 실패하면, `/feedback`을 실행하여 보고서에 환경 세부 정보가 포함되도록 합니다.1333* 대신 이 컴퓨터에서 브라우저 로그인을 사용하려면 Claude Code가 `127.0.0.1`에서 수신 대기할 수 있어야 합니다. 샌드박스 안에서 실행되는 경우 샌드박스 정책이 로컬 포트에서의 수신 대기를 허용하는지 확인한 다음 `/login`을 다시 실행합니다. 수신 대기가 가능해야 하는데도 여전히 실패하면 `/feedback`을 실행하여 보고서에 환경 세부 정보가 포함되도록 합니다.

1324 1334

1325<h3 id="claude-login-not-accepted">1335<h3 id="claude-login-not-accepted">

1326 Claude login not accepted1336 Claude 로그인이 수락되지 않음

1327</h3>1337</h3>

1328 1338

1329[클라우드 세션](/docs/ko/claude-code-on-the-web)을 시작하려고 했으며, 서버가 401로 생성을 거부했습니다: 이 머신이 전송한 Claude 로그인을 수락하지 않았습니다. 일반적으로 로그인이 만료되었거나 취소되었기 때문입니다.1339[클라우드 세션](/docs/ko/claude-code-on-the-web)을 시작하려고 했으나 서버가 401과 함께 세션 생성을 거부했습니다. 서버가 이 컴퓨터에서 전송한 Claude 로그인을 수락하지 않았으며, 일반적으로 로그인이 만료되었거나 취소되었기 때문입니다.

1330 1340

1331라인의 첫 번째 부분은 서버가 제공할 때 서버 자신의 이유입니다. 그렇지 않으면 라인은 다음과 같이 읽습니다:1341줄의 첫 부분은 서버가 이유를 제공하는 경우 서버 자체의 이유입니다. 그렇지 않으면 줄은 다음과 같습니다.

1332 1342

1333```text theme={null}1343```text theme={null}

1334Claude login not accepted · Run /login, then try again1344Claude login not accepted · Run /login, then try again

1335```1345```

1336 1346

1337**수행할 작업:**1347**해결 방법:**

1338 1348

1339* `/login`을 실행하고, 로그인을 완료한 후 세션을 다시 시작합니다.1349* `/login`을 실행하고 로그인을 완료한 다음 세션을 다시 시작합니다

1340 1350

1341<h3 id="artifacts-need-a-claude-ai-login">1351<h3 id="artifacts-need-a-claude-ai-login">

1342 아티팩트에 claude.ai 로그인이 필요합니다1352 아티팩트에는 claude.ai 로그인이 필요함

1343</h3>1353</h3>

1344 1354

1345Claude Code가 세션에 아티팩트에 사용할 수 있는 claude.ai 로그인이 없어서 [아티팩트](/docs/ko/artifacts) 게시 또는 읽기를 거부했습니다.1355세션에 아티팩트에 사용할 수 있는 claude.ai 로그인이 없기 때문에 Claude Code가 [아티팩트](/docs/ko/artifacts) 게시 또는 읽기를 거부했습니다.

1346 1356

1347메시지의 모든 형식은 동일한 단어로 시작하며, 그 뒤에 세션이 인증하는 방식에 따라 달라지는 해결책이 있습니다. 경쟁하는 자격증명이 없으면 다음과 같이 읽습니다:1357모든 형태의 메시지는 같은 문구로 시작하며, 그 뒤에 세션의 인증 방식에 따라 달라지는 해결책이 이어집니다. 경쟁하는 자격 증명이 없을 때는 다음과 같습니다.

1348 1358

1349```text theme={null}1359```text theme={null}

1350Artifacts need a claude.ai login. Run /login and select "Claude account with subscription", then retry — the "Anthropic Console account" option does not provide claude.ai credentials.1360Artifacts need a claude.ai login. Run /login and select "Claude account with subscription", then retry — the "Anthropic Console account" option does not provide claude.ai credentials.

1351```1361```

1352 1362

1353**수행할 작업:**1363**해결 방법:**

1354 1364

1355* `/login`을 실행하고 **Claude account with subscription**을 선택합니다. **Anthropic Console account** 옵션은 claude.ai 자격증명을 제공하지 않습니다.1365* `/login`을 실행하고 **Claude account with subscription**을 선택합니다. **Anthropic Console account** 옵션은 claude.ai 자격 증명을 제공하지 않습니다.

1356* 메시지가 `ANTHROPIC_API_KEY`, `apiKeyHelper` 설정 또는 이전 `/login`으로 저장된 Console 키와 같이 우선순위를 갖는 자격증명의 이름을 지정하면, 메시지가 말하는 방식으로 제거한 후 `/login`을 실행합니다.1366* 메시지가 `ANTHROPIC_API_KEY`, `apiKeyHelper` 설정 또는 이전 `/login`으로 저장된 Console 키처럼 우선하는 자격 증명을 명시하면, 메시지에 안내된 방법으로 이를 제거한 다음 `/login`을 실행합니다

1357* 메시지가 이 원격 세션이 이를 실행한 머신을 통해 인증한다고 하면, 해당 머신에서 claude.ai에 로그인한 후 세션을 다시 연결합니다.1367* 메시지에 이 원격 세션이 자신을 실행한 컴퓨터를 통해 인증한다고 표시되면, 해당 컴퓨터에서 claude.ai에 로그인한 다음 세션을 다시 연결합니다

1358* 메시지가 자격증명이 세션의 호스트 환경에 의해 주입된다고 하면, 해당 세션에서 이를 변경할 수 없습니다. claude.ai에 로그인한 세션을 시작합니다.1368* 메시지에 자격 증명이 세션의 호스트 환경에서 주입된다고 표시되면 해당 세션에서는 이를 변경할 수 없습니다. claude.ai에 로그인된 세션을 시작합니다

1359* 계획, 모델 공급자 및 조직 정책과 같은 아티팩트가 가진 다른 요구 사항은 [가용성](/docs/ko/artifacts#availability)을 참조합니다.1369* 플랜, 모델 제공업체, 조직 정책 등 아티팩트의 기타 요구 사항은 [사용 가능 여부](/docs/ko/artifacts#availability)를 참조하십시오

1360 1370

1361<h3 id="administrator-policy-requires-a-cloud-gateway-sign-in">1371<h3 id="administrator-policy-requires-a-cloud-gateway-sign-in">

1362 관리자 정책에 Cloud 게이트웨이 로그인이 필요합니다1372 관리자 정책에 따라 Cloud 게이트웨이 로그인이 필요함

1363</h3>1373</h3>

1364 1374

1365관리자의 [관리 설정](/docs/ko/managed-settings)이 이 머신에서 [`forceLoginMethod`](/docs/ko/settings-reference#forceloginmethod)를 `"gateway"`로 설정했거나 [`forceLoginGatewayUrl`](/docs/ko/settings-reference#forcelogingatewayurl)을 설정했습니다. `CLAUDE_CODE_USE_BEDROCK`과 같은 변수를 통해 클라우드 공급자를 선택하지 않으면, Claude Code는 [Claude apps 게이트웨이](/docs/ko/claude-apps-gateway) 로그인만 수락합니다. 두 가지 메시지 중 하나가 표시됩니다:1375이 컴퓨터에서 관리자의 [관리형 설정](/docs/ko/managed-settings)이 [`forceLoginMethod`](/docs/ko/settings-reference#forceloginmethod)를 `"gateway"`로 설정했거나 [`forceLoginGatewayUrl`](/docs/ko/settings-reference#forcelogingatewayurl)을 설정했습니다. `CLAUDE_CODE_USE_BEDROCK`과 같은 변수로 클라우드 제공업체를 선택하지 않는 한, Claude Code는 [Claude 앱 게이트웨이](/docs/ko/claude-apps-gateway) 로그인만 허용합니다. 다음 두 메시지 중 하나가 표시됩니다.

1366 1376

1367```text theme={null}1377```text theme={null}

1368Not signed in to the Cloud gateway — run /login.1378Not signed in to the Cloud gateway — run /login.

1369```1379```

1370 1380

1371세션에 게이트웨이 로그인이 없을 때 모델 요청이 이 메시지로 실패합니다. 예를 들어 정책이 머신에 도달한 이후 `/login`을 실행하지 않았기 때문입니다.1381세션에 게이트웨이 로그인이 없으면, 예를 들어 정책이 컴퓨터에 적용된 이후 `/login`을 실행하지 않았다면, 모델 요청이 이 메시지와 함께 실패합니다.

1372 1382

1373또한 `ANTHROPIC_API_KEY`, `ANTHROPIC_AUTH_TOKEN` 또는 `apiKeyHelper` 자격증명이 구성되어 있고 관리 설정이 `forceLoginMethod`를 설정하면, Claude Code는 대신 시작 시 다음과 같이 시작하는 메시지로 종료됩니다:1383컴퓨터에 Anthropic에서 발급한 자격 증명도 있고 관리형 설정이 `forceLoginMethod` 또는 `forceLoginOrgUUID`를 설정한 경우에는 Claude Code가 대신 시작 시 종료됩니다. 해당 자격 증명은 `ANTHROPIC_API_KEY` 또는 `ANTHROPIC_AUTH_TOKEN` 변수, `apiKeyHelper` 설정, 또는 이전 Claude Console 로그인으로 저장된 API 키일 수 있습니다. 메시지는 다음과 같이 시작합니다.

1374 1384

1375```text theme={null}1385```text theme={null}

1376Administrator policy requires a Cloud gateway sign-in on this machine; the1386Administrator policy requires a Cloud gateway sign-in on this machine; the

1378ANTHROPIC_AUTH_TOKEN, or apiKeyHelper) is not used.1388ANTHROPIC_AUTH_TOKEN, or apiKeyHelper) is not used.

1379```1389```

1380 1390

1381**수행할 작업:**1391**해결 방법:**

1382 1392

1383* `/login`을 실행하고 **Cloud gateway** 화면에서 로그인을 완료합니다.1393* `/login`을 실행하고 **Cloud gateway** 화면에서 로그인을 완료합니다

1384* 시작 메시지의 경우, 구성한 `ANTHROPIC_API_KEY`, `ANTHROPIC_AUTH_TOKEN` 또는 `apiKeyHelper` 설정을 제거한 후 `claude`를 시작하고 `/login`을 실행합니다.1394* 시작 시 메시지의 경우, 구성한 `ANTHROPIC_API_KEY`, `ANTHROPIC_AUTH_TOKEN` 또는 `apiKeyHelper` 설정을 제거합니다. 저장된 Console API 키를 제거하려면 `claude auth logout`을 실행합니다. 이 명령은 저장된 claude.ai 로그인도 제거합니다. `CLAUDE_CODE_USE_*`로 클라우드 제공업체를 선택하면 세션이 로그인 없이 시작됩니다. 그렇지 않으면 `claude`를 시작하고 `/login`을 실행합니다

1385* 머신이 게이트웨이를 요구하지 않아야 한다고 생각하면, 관리 설정에서 `forceLoginMethod` 및 `forceLoginGatewayUrl`을 제거하도록 머신을 관리하는 관리자에게 요청합니다.1395* 이 컴퓨터에 게이트웨이가 필요하지 않아야 한다고 생각되면, 컴퓨터를 관리하는 관리자에게 관리형 설정에서 `forceLoginMethod`와 `forceLoginGatewayUrl`을 제거해 달라고 요청합니다

1386 1396

1387v2.1.265에서는 회귀가 API 키, `apiKeyHelper` 또는 사용자 정의 헤더로 인증하는 일부 LLM 게이트웨이 및 프록시 구성에서도 첫 번째 메시지를 표시했으며, 머신에 관리자 요구 사항이 없었습니다. v2.1.266 이상으로 업데이트합니다. 구성을 변경할 필요가 없습니다.1397v2.1.265에서는 회귀 문제로 인해, 컴퓨터에 관리자 요구 사항이 없는데도 API 키, `apiKeyHelper` 또는 사용자 지정 헤더로 인증하는 일부 LLM 게이트웨이 및 프록시 구성에서 첫 번째 메시지가 표시되었습니다. v2.1.266 이상으로 업데이트하십시오. 구성을 변경할 필요는 없습니다.

1388 1398

1389v2.1.261 이전에는 `forceLoginMethod`를 `"gateway"`로 설정한 머신에서 Claude Code가 모델 요청을 실패하는 대신 남은 저장된 로그인을 사용했으며, 구성된 환경 자격증명을 `This machine's managed settings require a first-party login` 대신 시작 메시지로 보고했습니다. v2.1.265 이전에는 관리 설정이 `forceLoginGatewayUrl`만 설정한 머신이 게이트웨이 로그인을 요구하지 않았으며, Claude Code가 거기서 남은 자격증명을 사용했습니다.1399v2.1.261 이전에는 `forceLoginMethod`를 `"gateway"`로 설정한 컴퓨터에서 Claude Code가 모델 요청을 실패시키는 대신 남아 있는 저장된 로그인을 사용했으며, 구성된 환경 자격 증명을 시작 시 메시지 대신 `This machine's managed settings require a first-party login`으로 보고했습니다. v2.1.265 이전에는 관리형 설정에서 `forceLoginGatewayUrl`만 설정한 컴퓨터에서 게이트웨이 로그인이 요구되지 않았으며, Claude Code가 그곳에 남아 있는 자격 증명을 사용했습니다.

1390 1400

1391<h3 id="your-account-is-on-hold">1401<h3 id="your-account-is-on-hold">

1392 계정이 보류 중입니다1402 계정이 보류됨

1393</h3>1403</h3>

1394 1404

1395로그인 뒤의 Claude 계정이 일시 중단되었습니다. Claude Code는 저장된 로그인을 갱신하려고 할 때 보류를 알게 되면 첫 번째 메시지를 표시하고, 브라우저에서 완료한 로그인이 이를 보고하면 두 번째 메시지를 표시합니다:1405로그인에 연결된 Claude 계정이 정지되었습니다. Claude Code는 저장된 로그인을 갱신하려다 보류 사실을 알게 되면 첫 번째 메시지를 표시하고, 브라우저에서 완료한 로그인이 이를 보고하면 두 번째 메시지를 표시합니다.

1396 1406

1397```text theme={null}1407```text theme={null}

1398Your account is on hold and can't use Claude Code. View details or appeal: https://claude.ai/restricted1408Your account is on hold and can't use Claude Code. View details or appeal: https://claude.ai/restricted

1399Your account is on hold and can't sign in to Claude Code. View details or appeal: https://claude.ai/restricted1409Your account is on hold and can't sign in to Claude Code. View details or appeal: https://claude.ai/restricted

1400```1410```

1401 1411

1402동일한 계정으로 다시 로그인하면 메시지가 지워지지 않습니다. 보류가 로그인이 아닌 계정에 있기 때문입니다. [비대화형 모드](/docs/ko/headless)(`-p`) 및 [Agent SDK](/docs/ko/agent-sdk/overview)에서 구조화된 오류 코드는 `account_on_hold`입니다. v2.1.235 이전에는 Claude Code가 보류된 계정을 [로그인 만료됨 · /login을 실행하십시오](#login-expired)로 보고했으며, 복구 단계가 보류를 지울 수 없습니다.1412보류는 로그인이 아닌 계정에 적용되므로 같은 계정으로 다시 로그인해도 메시지가 해결되지 않습니다. [비대화형 모드](/docs/ko/headless)(`-p`)와 [Agent SDK](/docs/ko/agent-sdk/overview)에서 구조화된 오류 코드는 `account_on_hold`입니다. v2.1.235 이전에는 Claude Code가 보류된 계정을 [Login expired · Please run /login](#login-expired)으로 보고했으며, 그 복구 단계로는 보류를 해제할 수 없었습니다.

1403 1413

1404**수행할 작업:**1414**해결 방법:**

1405 1415

1406* 메시지의 링크를 열어 보류의 세부 정보를 보거나 이의를 제기합니다.1416* 메시지의 링크를 열어 보류의 세부 정보를 확인하거나 이의를 제기합니다

1407* 보류의 영향을 받지 않는 다른 Claude 계정 또는 API 키가 있으면, 보류가 해결되는 동안 계속 작업할 수 있습니다: 해당 계정으로 `/login`을 실행하거나, `ANTHROPIC_API_KEY`로 키를 설정합니다.1417* 보류의 영향을 받지 않는 다른 Claude 계정이나 API 키가 있다면 보류가 해결되는 동안 계속 작업할 수 있습니다. 해당 계정으로 `/login`을 실행하거나 `ANTHROPIC_API_KEY`로 키를 설정합니다

1408 1418

1409<h3 id="anthropic-profile-login-expired">1419<h3 id="anthropic-profile-login-expired">

1410 Anthropic 프로필 로그인 만료됨1420 Anthropic 프로필 로그인 만료

1411</h3>1421</h3>

1412 1422

1413Claude Code가 저장된 로그인 자격증명이 만료된 Anthropic 자격증명 프로필을 통해 인증 중이며, 프로필이 Claude Code가 갱신하는 데 사용할 수 있는 새로 고침 자격증명을 보유하지 않습니다. Claude Code는 동일한 만료된 자격증명을 읽을 재시도가 있으므로 각 요청을 로컬에서 중지합니다.1423Claude Code가 저장된 로그인 자격 증명이 만료된 Anthropic 자격 증명 프로필을 통해 인증하고 있으며, 해당 프로필에 Claude Code가 갱신에 사용할 수 있는 갱신 자격 증명이 없습니다. 재시도해도 같은 만료된 자격 증명을 읽게 되므로, Claude Code는 재시도 없이 각 요청을 로컬에서 중단합니다.

1414 1424

1415```text theme={null}1425```text theme={null}

1416Anthropic profile login expired · Re-authenticate your Anthropic profile1426Anthropic profile login expired · Re-authenticate your Anthropic profile

1417Anthropic profile login expired · Run /login to use your claude.ai account instead, or re-authenticate the profile1427Anthropic profile login expired · Run /login to use your claude.ai account instead, or re-authenticate the profile

1418```1428```

1419 1429

1420이것은 활성 자격증명이 Anthropic 자격증명 프로필에서 올 때만 나타나며, `ANTHROPIC_PROFILE` 환경 변수로 선택하거나, Claude Code가 Anthropic 구성 디렉토리에서 활성 프로필로 발견하거나, Claude Code가 [API 키 없이 로그인](/docs/ko/authentication#sign-in-without-an-api-key)할 때 작성했습니다. `/login`의 claude.ai 옵션, API 키, `ANTHROPIC_AUTH_TOKEN`과 같은 베어러 토큰 또는 타사 공급자로 인증하는 세션은 이 메시지를 절대 보지 않습니다.1430이 메시지는 활성 자격 증명이 Anthropic 자격 증명 프로필에서 제공되는 경우에만 나타납니다. 이러한 프로필은 `ANTHROPIC_PROFILE` 환경 변수로 선택한 프로필, Claude Code가 Anthropic 구성 디렉터리에서 활성 프로필로 찾은 프로필, 또는 [API 키 없이 로그인](/docs/ko/authentication#sign-in-without-an-api-key)할 때 Claude Code가 작성한 프로필입니다. API 키, `ANTHROPIC_AUTH_TOKEN`과 같은 bearer 토큰 또는 타사 제공업체로 인증하는 세션에서는 이 메시지가 표시되지 않습니다.

1421 1431

1422[키 없는 로그인을 제공](/docs/ko/authentication#sign-in-without-an-api-key)하는 머신에서는 `/login`을 실행하고, Anthropic Console 계정을 선택하고, 다시 로그인하여 키 없는 Console 로그인 또는 Claude Platform CLI의 `ant auth login`이 작성한 프로필을 갱신합니다. Claude Code는 해당 프로필의 만료된 자격증명을 바꿉니다. 페더레이션 프로필 또는 다른 도구가 만든 프로필의 경우, `/login`이 자격증명을 갱신하지 않습니다. 어떤 형식을 보는지는 프로필을 선택했는지 아니면 Claude Code가 발견했는지에 따라 달라집니다:1432[키 없는 로그인을 제공하는](/docs/ko/authentication#sign-in-without-an-api-key) 컴퓨터에서는 `/login`을 실행하고 Anthropic Console 계정을 선택한 다음 다시 로그인하여, 키 없는 Console 로그인이나 Claude Platform CLI의 `ant auth login`이 작성한 프로필을 갱신합니다. Claude Code는 해당 프로필의 만료된 자격 증명을 교체합니다. 페더레이션 프로필이나 다른 도구가 만든 프로필의 경우 `/login`으로 자격 증명이 갱신되지 않습니다. 어떤 형태가 표시되는지는 프로필을 직접 선택했는지 Claude Code가 찾았는지에 따라 다릅니다.

1423 1433

1424* `ANTHROPIC_PROFILE`을 명시적으로 설정하면, 메시지는 `Re-authenticate your Anthropic profile`로 끝납니다.1434* `ANTHROPIC_PROFILE`을 명시적으로 설정한 경우 메시지는 `Re-authenticate your Anthropic profile`로 끝납니다.

1425* Claude Code가 구성 디렉토리에서 프로필을 발견했으면, 메시지는 `/login`을 제공합니다. Claude Code가 작동하는 `/login`을 발견된 프로필보다 우선순위를 주고 대신 claude.ai 또는 Console 계정으로 인증하기 때문입니다. v2.1.234 이전에는 Claude Code가 이 경우에도 `Re-authenticate your Anthropic profile` 형식을 표시했습니다.1435* Claude Code가 구성 디렉터리에서 프로필을 찾은 경우, Claude Code는 작동하는 `/login`을 찾은 프로필보다 우선 적용하고 그 후 claude.ai 또는 Console 계정으로 인증하므로 메시지가 `/login`을 제안합니다. v2.1.234 이전에는 이 경우에도 Claude Code가 `Re-authenticate your Anthropic profile` 형태를 표시했습니다.

1426 1436

1427**수행할 작업:**1437**해결 방법:**

1428 1438

1429* 프로필에 다시 로그인한 후 재시도합니다: [키 없는 로그인을 제공](/docs/ko/authentication#sign-in-without-an-api-key)하는 머신에서는 키 없는 Console 로그인 또는 Claude Platform CLI의 `ant auth login`이 작성한 프로필의 경우 `/login`을 실행하고 Anthropic Console 계정을 선택합니다. 다른 프로필의 경우, 프로필을 만든 도구를 사용합니다.1439* 프로필에 다시 로그인한 다음 재시도합니다. [키 없는 로그인을 제공하는](/docs/ko/authentication#sign-in-without-an-api-key) 컴퓨터에서 키 없는 Console 로그인이나 Claude Platform CLI의 `ant auth login`이 작성한 프로필의 경우 `/login`을 실행하고 Anthropic Console 계정을 선택합니다. 다른 프로필의 경우 해당 프로필을 만든 도구를 사용합니다

1430* 관리자가 프로필의 자격증명을 프로비저닝했으면, 새 자격증명을 발급하도록 요청합니다.1440* 관리자가 프로필의 자격 증명을 프로비저닝한 경우 새 자격 증명을 발급해 달라고 요청합니다

1431* `/status`를 실행하여 활성 자격증명 소스 및 프로필 이름을 확인합니다.1441* `/status`를 실행하여 활성 자격 증명 소스와 프로필 이름을 확인합니다

1432* 프로필 사용을 중지하려면, 설정했으면 `ANTHROPIC_PROFILE`을 설정 해제한 후 `/login` 또는 `ANTHROPIC_API_KEY`와 같은 다른 방식으로 인증합니다.1442* 프로필 사용을 중단하려면 `ANTHROPIC_PROFILE`을 설정했다면 설정 해제한 다음, `/login`이나 `ANTHROPIC_API_KEY`와 같은 다른 방법으로 인증합니다

1433 1443

1434<h3 id="oauth-scope-requirement">1444<h3 id="oauth-scope-requirement">

1435 OAuth 범위 요구 사항1445 OAuth 범위 요구 사항

1436</h3>1446</h3>

1437 1447

1438저장된 토큰이 최신 기능이 필요로 하는 권한 범위보다 앞서 있습니다:1448저장된 토큰이 새 기능에 필요한 권한 범위가 도입되기 이전에 발급되었습니다.

1439 1449

1440```text theme={null}1450```text theme={null}

1441OAuth token does not meet scope requirement: user:profile1451OAuth token does not meet scope requirement: user:profile

1442```1452```

1443 1453

1444**수행할 작업:**1454**해결 방법:**

1445 1455

1446* `/login`을 실행하여 현재 범위가 있는 새 토큰을 가져옵니다. 먼저 로그아웃할 필요가 없습니다.1456* `/login`을 실행하여 현재 범위가 포함된 새 토큰을 받습니다. 먼저 로그아웃할 필요는 없습니다.

1447 1457

1448<h3 id="claude-ai-rejected-the-session-token">1458<h3 id="claude-ai-rejected-the-session-token">

1449 claude.ai가 세션 토큰을 거부했습니다1459 claude.ai가 세션 토큰을 거부함

1450</h3>1460</h3>

1451 1461

1452[claude.ai 커넥터](/docs/ko/mcp#use-mcp-servers-from-claude-ai) 요청이 실패했습니다. claude.ai가 Claude Code 로그인의 토큰을 거부했습니다. 일반적으로 만료되었거나 새로 고칠 수 없는 로그인입니다. 거부된 토큰은 로그인이며, 커넥터 자신의 claude.ai 인증이 아니므로, 커넥터를 다시 인증해도 해결되지 않습니다. `/mcp`에서 커넥터는 `session token rejected`로 표시되며 세부 정보 보기는 다음과 같이 읽습니다:1462claude.ai가 Claude Code 로그인의 토큰을 거부했기 때문에 [claude.ai 커넥터](/docs/ko/mcp#use-mcp-servers-from-claude-ai) 요청이 실패했습니다. 거부된 토큰은 claude.ai에서의 커넥터 자체 권한 부여가 아닌 사용자의 로그인이므로, 커넥터에 다시 권한을 부여해도 해결되지 않습니다. `/mcp`에서 커넥터는 `session token rejected`로 표시되며 세부 정보 보기에는 다음과 같이 표시됩니다.

1453 1463

1454```text theme={null}1464```text theme={null}

1455claude.ai rejected the session token. Run /login, then reconnect.1465claude.ai rejected the session token. Run /login, then reconnect.

1456```1466```

1457 1467

1458**수행할 작업:**1468**해결 방법:**

1459 1469

1460* `/login`을 실행하여 다시 로그인합니다.1470* `/login`을 실행하여 다시 로그인합니다

1461* `/mcp`에서 커넥터를 다시 연결하거나, `/mcp reconnect <server>`를 실행합니다. 다시 로그인하기 전에 다시 연결하면 커넥터가 동일한 상태로 유지됩니다. `/mcp` 패널의 **Reconnect** 옵션은 `your claude.ai session token was rejected`를 보고합니다. 입력된 `/mcp reconnect <server>` 형식은 토큰이 여전히 거부되었음에도 불구하고 성공적인 다시 연결을 보고합니다.1471* `/mcp`에서 커넥터를 다시 연결하거나 `/mcp reconnect <server>`를 실행합니다. 다시 로그인하기 전에 다시 연결하면 커넥터가 같은 상태로 남습니다. `/mcp` 패널의 **Reconnect** 옵션은 `your claude.ai session token was rejected`를 보고하며, 직접 입력하는 `/mcp reconnect <server>` 형태는 토큰이 여전히 거부되는 상태인데도 다시 연결에 성공했다고 보고합니다.

1462 1472

1463v2.1.222 이전에는 Claude Code가 커넥터를 인증이 필요한 것으로 표시했으며, 이는 완료해도 상태를 해결하지 못하는 커넥터의 인증 흐름을 가리켰습니다.1473v2.1.222 이전에는 Claude Code가 대신 커넥터를 인증이 필요한 상태로 표시했으며, 이로 인해 커넥터의 권한 부여 흐름을 완료해도 상태가 해결되지 않는데도 해당 흐름으로 안내했습니다.

1464 1474

1465<h3 id="mcp-server-needs-you-to-sign-in-again">1475<h3 id="mcp-server-needs-you-to-sign-in-again">

1466 MCP 서버가 다시 로그인하도록 요청합니다1476 MCP 서버에 다시 로그인해야 함

1467</h3>1477</h3>

1468 1478

1469원격 [MCP 서버](/docs/ko/mcp)가 세션 중에 도구 호출에서 자격증명을 거부했습니다. 일반적으로 로그인 또는 토큰이 만료되었거나 취소되었거나 토큰이 도구가 필요로 하는 권한이 부족합니다. 도구 호출이 실패하고 `/mcp`가 서버를 [인증이 필요한 것](/docs/ko/mcp#authenticate-with-remote-mcp-servers)으로 표시합니다.1479원격 [MCP 서버](/docs/ko/mcp)가 세션 도중 도구 호출에서 자격 증명을 거부했습니다. 일반적으로 로그인이나 토큰이 만료되었거나 토큰에 도구에 필요한 권한이 없기 때문입니다. 도구 호출이 실패하고, `/mcp`는 서버를 [인증이 필요한](/docs/ko/mcp#authenticate-with-remote-mcp-servers) 상태로 표시합니다.

1470 1480

1471Claude Code에서 로그인하는 서버(claude.ai 커넥터 포함)의 경우, 로그인이 만료되었거나 취소되었습니다:1481claude.ai 커넥터를 포함하여 Claude Code에서 로그인하는 서버의 경우, 로그인이 만료되었거나 취소된 것입니다.

1472 1482

1473```text theme={null}1483```text theme={null}

1474MCP server "<name>" needs you to sign in again (run /mcp to re-authenticate)1484MCP server "<name>" needs you to sign in again (run /mcp to re-authenticate)

1475```1485```

1476 1486

1477`/mcp`를 실행하고, 서버를 선택하고, 메뉴에서 다시 로그인합니다.1487`/mcp`를 실행하고 서버를 선택한 다음 해당 메뉴에서 다시 로그인합니다.

1478 1488

1479[`headersHelper`](/docs/ko/mcp#use-dynamic-headers-for-custom-authentication) 스크립트로 구성된 서버의 경우, Claude Code가 이미 헬퍼를 다시 실행하고 표시하기 전에 호출을 한 번 재시도했습니다:1489[`headersHelper`](/docs/ko/mcp#use-dynamic-headers-for-custom-authentication) 스크립트로 구성된 서버의 경우, Claude Code는 이 메시지를 표시하기 전에 이미 헬퍼를 다시 실행하고 호출을 한 번 재시도했습니다.

1480 1490

1481```text theme={null}1491```text theme={null}

1482MCP server "<name>" rejected the credential from its headersHelper (check the helper and run /mcp to reconnect, or to authenticate if the server also uses OAuth)1492MCP server "<name>" rejected the credential from its headersHelper (check the helper and run /mcp to reconnect, or to authenticate if the server also uses OAuth)

1483```1493```

1484 1494

1485헬퍼가 서버가 수락하는 자격증명을 반환하는지 확인한 후, `/mcp`에서 다시 연결합니다. 이는 헬퍼를 다시 실행합니다.1495헬퍼가 서버에서 수락하는 자격 증명을 반환하는지 확인한 다음, 헬퍼를 다시 실행하는 `/mcp`에서 다시 연결합니다.

1486 1496

1487정적 `Authorization` 헤더가 있는 서버의 경우:1497구성에 정적 `Authorization` 헤더가 있는 서버의 경우:

1488 1498

1489```text theme={null}1499```text theme={null}

1490MCP server "<name>" rejected the Authorization header in its config (update it, then run /mcp to reconnect)1500MCP server "<name>" rejected the Authorization header in its config (update it, then run /mcp to reconnect)

1491```1501```

1492 1502

1493서버가 구성된 곳에서 헤더 값을 업데이트한 후 `/mcp`에서 다시 연결합니다.1503서버가 구성된 위치에서 헤더 값을 업데이트한 다음 `/mcp`에서 다시 연결합니다.

1494 1504

1495v2.1.273 이전에는 만료된 로그인, `headersHelper` 및 `Authorization` 헤더 경우가 모두 `MCP server "<name>" requires re-authorization (token expired)`를 표시했습니다.1505v2.1.273 이전에는 로그인 만료, `headersHelper`, `Authorization` 헤더의 경우 모두 `MCP server "<name>" requires re-authorization (token expired)`가 표시되었습니다.

1496 1506

1497서버는 HTTP 403 `insufficient_scope`로 도구 호출을 거부하여 범위를 요청할 수도 있습니다. 때로는 토큰이 이미 나열한 범위입니다. 메시지는 해당 범위의 이름을 지정합니다:1507서버는 범위에 대한 권한 부여를 요청하기 위해 HTTP 403 `insufficient_scope`로 도구 호출을 거부할 수도 있으며, 때로는 토큰에 이미 나열된 범위일 수도 있습니다. 메시지에 해당 범위가 표시됩니다.

1498 1508

1499```text theme={null}1509```text theme={null}

1500MCP server "<name>" needs additional permissions (scope: "<scope>") — run /mcp to re-authenticate1510MCP server "<name>" needs additional permissions (scope: "<scope>") — run /mcp to re-authenticate

1501```1511```

1502 1512

1503`/mcp`를 실행하고, 서버를 선택하고, 메뉴에서 다시 인증합니다.1513`/mcp`를 실행하고 서버를 선택한 다음 해당 메뉴에서 다시 인증합니다.

1504 1514

1505서버의 구성이 [`oauth.scopes`](/docs/ko/mcp#restrict-oauth-scopes) 또는 [`authServerMetadataUrl`](/docs/ko/mcp#override-oauth-metadata-discovery)을 설정하지 않으면, Claude Code가 서버가 이름을 지정한 범위를 요청합니다. 어느 설정이든 Claude Code가 해당 설정의 범위를 요청합니다. `oauth.scopes`를 고정했으면, 다시 인증하기 전에 누락된 범위를 해당 목록에 추가합니다.1515서버 구성에 [`oauth.scopes`](/docs/ko/mcp#restrict-oauth-scopes)와 [`authServerMetadataUrl`](/docs/ko/mcp#override-oauth-metadata-discovery)이 모두 설정되어 있지 않으면 Claude Code는 서버가 명시한 범위를 요청합니다. 둘 중 하나가 설정되어 있으면 Claude Code는 대신 해당 설정의 범위를 요청합니다. `oauth.scopes`를 고정했다면 다시 인증하기 전에 누락된 범위를 해당 목록에 추가하십시오.

1506 1516

1507v2.1.274 이전에는 이 경우가 `needs you to sign in again` 메시지를 표시했으며, v2.1.273 이전에는 다른 경우처럼 `requires re-authorization (token expired)`를 표시했습니다.1517v2.1.274 이전에는 이 경우 `needs you to sign in again` 메시지가 표시되었으며, v2.1.273 이전에는 다른 경우와 마찬가지로 `requires re-authorization (token expired)`가 표시되었습니다.

1508 1518

1509<h3 id="mcp-server-url-is-missing-or-not-a-valid-url">1519<h3 id="mcp-server-url-is-missing-or-not-a-valid-url">

1510 MCP 서버 URL이 누락되었거나 유효한 URL이 아닙니다1520 MCP 서버 URL이 없거나 유효한 URL이 아님

1511</h3>1521</h3>

1512 1522

1513Claude Code가 원격 MCP 서버에 대한 OAuth 로그인을 시작하기를 거부했습니다. 서버의 구성된 `url`이 URL로 구문 분석되지 않기 때문입니다. Claude Code가 서버에 대해 보고할 더 구체적인 구성 문제가 없으면, [`claude mcp login <name>`](/docs/ko/mcp#authenticate-from-the-command-line)을 셸에서 실행하면 거부가 다음과 같이 인쇄됩니다:1523서버에 구성된 `url`을 URL로 파싱할 수 없기 때문에 Claude Code가 원격 MCP 서버에 대한 OAuth 로그인 시작을 거부했습니다. Claude Code가 해당 서버에 대해 보고할 더 구체적인 구성 문제가 없는 한, 셸에서 [`claude mcp login <name>`](/docs/ko/mcp#authenticate-from-the-command-line)을 실행하면 거부 내용이 다음과 같이 출력됩니다.

1514 1524

1515```text theme={null}1525```text theme={null}

1516Couldn't complete authentication for "<name>": This server's URL is missing or not a valid URL, so sign-in can't start. Fix the URL in its MCP config (or set the environment variable it uses) and try again.1526Couldn't complete authentication for "<name>": This server's URL is missing or not a valid URL, so sign-in can't start. Fix the URL in its MCP config (or set the environment variable it uses) and try again.

1517```1527```

1518 1528

1519**수행할 작업:**1529**해결 방법:**

1520 1530

1521* 서버가 구성된 곳에서 항목의 `url`을 서버의 실제 엔드포인트로 설정하거나, 해당 [`${VAR}` 참조](/docs/ko/mcp#environment-variable-expansion-in-mcp-json)가 이름을 지정하는 환경 변수를 설정한 후 로그인을 다시 실행합니다.1531* 서버가 구성된 위치에서 항목의 `url`을 서버의 실제 엔드포인트로 설정하거나, 해당 [`${VAR}` 참조](/docs/ko/mcp#environment-variable-expansion-in-mcp-json)가 가리키는 환경 변수를 설정한 다음 로그인을 다시 실행합니다.

1522 1532

1523<h3 id="issuer-mismatch-in-authorization-response">1533<h3 id="issuer-mismatch-in-authorization-response">

1524 인증 응답의 발급자 불일치1534 권한 부여 응답의 발급자 불일치

1525</h3>1535</h3>

1526 1536

1527[MCP OAuth 로그인](/docs/ko/mcp#authenticate-with-remote-mcp-servers) 중에 인증 서버가 Claude Code로 리디렉션되었으며, `iss` 매개변수가 Claude Code가 서버의 OAuth 메타데이터에서 예상한 발급자의 이름을 지정하지 않습니다. 이 단계에서 잘못된 발급자는 인증 서버 혼합 공격이 어떻게 보이는지이므로, Claude Code는 인증 코드를 교환하는 대신 로그인을 실패합니다. Claude Code는 브라우저 로그인 후 `/mcp` 서버 메뉴에 오류를 표시합니다:1537[MCP OAuth 로그인](/docs/ko/mcp#authenticate-with-remote-mcp-servers) 중에 권한 부여 서버가 Claude Code로 다시 리디렉션했는데, `iss` 파라미터가 Claude Code가 서버의 OAuth 메타데이터에서 예상한 발급자를 가리키지 않았습니다. 이 단계에서 잘못된 발급자가 나타나는 것은 권한 부여 서버 혼동(mix-up) 공격의 형태이므로, Claude Code는 권한 부여 코드를 교환하는 대신 로그인을 실패 처리합니다. Claude Code는 브라우저 로그인 후 `/mcp` 서버 메뉴에 오류를 표시합니다.

1528 1538

1529```text theme={null}1539```text theme={null}

1530Issuer mismatch in authorization response (RFC 9207): expected "https://auth.example.com", received "https://other.example.com"1540Issuer mismatch in authorization response (RFC 9207): expected "https://auth.example.com", received "https://other.example.com"

1531```1541```

1532 1542

1533`expected`는 서버의 OAuth 메타데이터의 발급자이며, `received`는 리디렉션이 전달한 `iss` 값입니다. `iss` 매개변수를 전달하지 않는 로그인은 확인을 통과합니다. 서버의 메타데이터가 `authorization_response_iss_parameter_supported`를 설정하지 않으면, 이 경우 Claude Code는 로그인을 실패합니다.1543`expected`는 서버의 OAuth 메타데이터에 있는 발급자이고, `received`는 리디렉션에 포함된 `iss` 값입니다. 리디렉션에 `iss` 파라미터가 없는 로그인은 검사를 통과하지만, 서버의 메타데이터가 `authorization_response_iss_parameter_supported`를 설정한 경우에는 Claude Code가 로그인을 실패 처리합니다.

1534 1544

1535**수행할 작업:**1545**해결 방법:**

1536 1546

1537* `/mcp`에서 로그인을 다시 시도합니다.1547* `/mcp`에서 로그인을 다시 시도합니다

1538* 오류가 반복되면, 서버 운영자에게 보고합니다. 수정은 서버 측입니다: 인증 서버는 메타데이터에서 광고하는 것과 동일한 발급자를 `iss` 매개변수에서 반환해야 합니다.1548* 오류가 반복되면 서버 운영자에게 보고합니다. 해결은 서버 측에서 이루어져야 합니다. 권한 부여 서버는 메타데이터에 게시한 것과 동일한 발급자를 `iss` 파라미터로 반환해야 합니다

1539* 서버가 수정되는 동안 연결하려면, [`MCP_SDK_GENERATION=v1`](/docs/ko/env-vars)로 Claude Code를 시작합니다. 해당 [런타임](/docs/ko/mcp#mcp-client-runtimes)은 이 확인을 실행하지 않습니다. 이것은 혼합 공격에 대한 보호를 제거하므로 서버 측 수정을 선호합니다.1549* 서버가 수정되는 동안 연결하려면 [`MCP_SDK_GENERATION=v1`](/docs/ko/env-vars)로 Claude Code를 시작합니다. 이 [런타임](/docs/ko/mcp#mcp-client-runtimes)은 이 검사를 실행하지 않습니다. 이 방법은 혼동 공격에 대한 보호를 제거하므로 서버 측 수정을 우선하십시오

1540 1550

1541v2.1.232 이전에는 Claude Code가 점진적 롤아웃에서만 v2 런타임을 사용했거나 `MCP_SDK_GENERATION=v2`를 설정했을 때 사용했습니다.1551v2.1.232 이전에는 Claude Code가 단계적 출시 중이거나 `MCP_SDK_GENERATION=v2`를 설정한 경우에만 v2 런타임을 사용했습니다.

1542 1552

1543<h3 id="refusing-to-send-credentials-to-non-https-token-endpoint">1553<h3 id="refusing-to-send-credentials-to-non-https-token-endpoint">

1544 HTTPS가 아닌 토큰 엔드포인트로 자격증명을 전송하기를 거부합니다1554 https가 아닌 토큰 엔드포인트로 자격 증명 전송을 거부함

1545</h3>1555</h3>

1546 1556

1547[v2 런타임](/docs/ko/mcp#mcp-client-runtimes)에서 Claude Code는 [MCP OAuth](/docs/ko/mcp#authenticate-with-remote-mcp-servers) 토큰 요청을 HTTPS를 통해 제공되거나 `localhost`, `127.0.0.1` 또는 `::1`에서만 전송합니다. 이 메시지는 서버의 토큰 엔드포인트가 둘 다 아니므로 Claude Code가 요청을 전송하기 전에 중지했음을 의미합니다. 이는 브라우저 로그인 후에 발생하므로 브라우저 단계가 먼저 성공하고, Claude Code가 서버의 토큰을 새로 고칠 때마다 다시 발생합니다.1557[v2 런타임](/docs/ko/mcp#mcp-client-runtimes)에서 Claude Code는 HTTPS로 제공되거나 `localhost`, `127.0.0.1`, `::1`에 있는 토큰 엔드포인트로만 [MCP OAuth](/docs/ko/mcp#authenticate-with-remote-mcp-servers) 토큰 요청을 전송합니다. 이 메시지는 서버의 토큰 엔드포인트가 둘 다 해당하지 않아 Claude Code가 요청을 전송하기 전에 중단했다는 의미입니다. 이는 브라우저 로그인 후에 발생하므로 브라우저 단계는 먼저 성공하며, Claude Code가 서버의 토큰을 갱신할 때마다 다시 발생합니다.

1548 1558

1549전체 형식에서 메시지는 MCP SDK에서 오며 거부한 토큰 엔드포인트를 인용합니다. 디버그 로그에서 로그인의 경우 `Error during auth completion:` 뒤에 오고, 새로 고침의 경우 `Token refresh failed:` 뒤에 옵니다. 셸에서 `claude mcp login <name>`은 `Couldn't complete authentication for "<name>":` 뒤에 인쇄하고, 세션에서 `/mcp`는 서버의 메뉴 아래에 표시합니다:1559전체 형태의 메시지는 MCP SDK에서 생성되며 거부한 토큰 엔드포인트를 인용합니다. 디버그 로그에서는 로그인의 경우 `Error during auth completion:` 뒤에, 갱신의 경우 `Token refresh failed:` 뒤에 나타납니다. 셸에서는 `claude mcp login <name>`이 `Couldn't complete authentication for "<name>":` 뒤에 이를 출력하며, 세션에서는 `/mcp`가 서버 메뉴 아래에 표시합니다.

1550 1560

1551```text theme={null}1561```text theme={null}

1552Refusing to send credentials to non-https token endpoint 'http://192.168.1.50:8123/oauth/token'. OAuth token requests MUST use TLS (localhost / 127.0.0.1 / ::1 are exempt).1562Refusing to send credentials to non-https token endpoint 'http://192.168.1.50:8123/oauth/token'. OAuth token requests MUST use TLS (localhost / 127.0.0.1 / ::1 are exempt).

1553```1563```

1554 1564

1555Claude Code는 쿼리 문자열이 있거나 긴 무작위 경로 세그먼트가 있는 서버 URL을 가능성 있게 비밀로 취급합니다. 그러한 서버의 경우, MCP SDK가 발생시키는 로그인 오류를 표시하거나 로깅하기 전에 수정합니다. 이 오류는 릴리스 간에 변경될 수 있는 짧은 이름(예: `io`)으로 읽은 후 `from the MCP SDK for` 및 수정된 서버 URL이 옵니다. MCP SDK의 다른 오류는 거기서 동일한 모양을 취합니다. 수정된 메시지는 서버의 토큰 엔드포인트가 `localhost`, `127.0.0.1` 또는 `::1` 이외의 주소에서 일반 `http://`일 때만 이 오류일 수 있습니다.1565Claude Code는 쿼리 문자열이나 임의로 보이는 긴 경로 세그먼트가 있는 서버 URL을 비밀일 수 있는 것으로 취급합니다. 이러한 서버의 경우 MCP SDK가 발생시키는 로그인 오류를 표시하거나 로그에 기록하기 전에 편집(redact)합니다. 그러면 이 오류는 `io`처럼 릴리스마다 바뀔 수 있는 짧은 이름 뒤에 `from the MCP SDK for`와 편집된 서버 URL이 이어지는 형태로 표시됩니다. MCP SDK의 다른 오류도 여기서 같은 형태를 띱니다. 편집된 메시지가 이 오류일 수 있는 경우는 서버의 토큰 엔드포인트가 `localhost`, `127.0.0.1`, `::1` 이외의 주소에 있는 일반 `http://`인 경우뿐입니다.

1556 1566

1557**수행할 작업:**1567**해결 방법:**

1558 1568

1559* 예를 들어 서버를 역방향 프록시 또는 TLS를 종료하는 터널 뒤에 놓고 서버가 `https://` 주소를 광고하도록 구성하여 해당 토큰 엔드포인트를 HTTPS를 통해 제공합니다.1569* 토큰 엔드포인트를 HTTPS로 제공합니다. 예를 들어 TLS를 종료하는 리버스 프록시나 터널 뒤에 서버를 두고 서버가 `https://` 주소를 게시하도록 구성합니다

1560* 서버를 변경하지 않고 연결하려면, [`MCP_SDK_GENERATION=v1`](/docs/ko/env-vars)로 Claude Code를 시작합니다. 해당 [런타임](/docs/ko/mcp#mcp-client-runtimes)은 이 규칙을 적용하지 않으며 일반 HTTP를 통해 토큰 요청을 전송합니다. 이 선택은 종료할 때까지 지속되며 모든 서버에 적용됩니다. v1 런타임은 또한 [발급자 확인](#issuer-mismatch-in-authorization-response)을 건너뜁니다. 따라서 엔드포인트를 HTTPS를 통해 제공하는 것을 선호합니다.1570* 서버를 변경하지 않고 연결하려면 [`MCP_SDK_GENERATION=v1`](/docs/ko/env-vars)로 Claude Code를 시작합니다. 이 [런타임](/docs/ko/mcp#mcp-client-runtimes)은 이 규칙을 적용하지 않으며 토큰 요청을 일반 HTTP로 전송합니다. 이 선택은 종료할 때까지 유지되며 모든 서버에 적용됩니다. v1 런타임은 [발급자 검사](#issuer-mismatch-in-authorization-response)도 건너뛰므로, 엔드포인트를 HTTPS로 제공하는 방법을 우선하십시오

1561 1571

1562<h3 id="aws-credentials-expired-or-invalid">1572<h3 id="aws-credentials-expired-or-invalid">

1563 AWS 자격증명이 만료되었거나 유효하지 않습니다1573 AWS 자격 증명 만료 또는 잘못됨

1564</h3>1574</h3>

1565 1575

1566AWS 세션 토큰이 만료되었거나 거부되었습니다. 이 메시지는 [Claude Platform on AWS](/docs/ko/claude-platform-on-aws) 또는 [Mantle 엔드포인트](/docs/ko/amazon-bedrock#use-the-mantle-endpoint)에서 401로 나타나며, 이는 해당 공급자가 만료된 보안 토큰을 보고하는 방식입니다.1576AWS 세션 토큰이 만료되었거나 거부되었습니다. 이 메시지는 [Claude Platform on AWS](/docs/ko/claude-platform-on-aws) 또는 [Mantle 엔드포인트](/docs/ko/amazon-bedrock#use-the-mantle-endpoint)에서 401이 반환될 때 나타나며, 이는 해당 제공업체가 만료된 보안 토큰을 보고하는 방식입니다.

1567 1577

1568중간의 작업 힌트는 설정에 따라 달라집니다. 안정적인 부분은 선행 `AWS credentials expired or invalid`입니다:1578중간의 조치 안내는 설정에 따라 다릅니다. 고정된 부분은 앞쪽의 `AWS credentials expired or invalid`입니다.

1569 1579

1570```text theme={null}1580```text theme={null}

1571AWS credentials expired or invalid · run /login and select "Claude Platform on AWS · refresh credentials", or run `aws sso login --profile myprofile` in another terminal · API Error: 401 ...1581AWS credentials expired or invalid · run /login and select "Claude Platform on AWS · refresh credentials", or run `aws sso login --profile myprofile` in another terminal · API Error: 401 ...

1572```1582```

1573 1583

1574v2.1.273 이전에는 `awsAuthRefresh`가 구성되었을 때만 이 메시지가 나타났습니다.1584v2.1.273 이전에는 `awsAuthRefresh`가 구성된 경우에만 이 메시지가 나타났습니다.

1575 1585

1576**수행할 작업:**1586**해결 방법:**

1577 1587

1578* 힌트가 자격증명이 이 환경에서 관리된다고 하면, 이를 실행한 앱이 자격증명을 소유하며 여기의 다른 단계는 적용되지 않습니다: 재시도하거나, 관리자에게 문의합니다.1588* 안내에 자격 증명이 이 환경에서 관리된다고 표시되면, Claude Code를 실행한 앱이 자격 증명을 소유하므로 여기의 다른 단계는 적용되지 않습니다. 재시도하거나 관리자에게 문의합니다

1579* [`awsAuthRefresh`](/docs/ko/amazon-bedrock#advanced-credential-configuration)가 설정되면, 메시지에서 이름을 지정한 명령(예: `aws sso login --profile myprofile`)을 다른 터미널에서 실행하고 브라우저 로그인을 완료한 후 재시도합니다. 그렇지 않으면 사용하는 AWS 자격증명을 직접 새로 고칩니다: SSO 로그인, 액세스 키, API 키 또는 프록시 토큰입니다.1589* [`awsAuthRefresh`](/docs/ko/amazon-bedrock#advanced-credential-configuration)가 설정된 경우, 메시지에 명시된 `aws sso login --profile myprofile`과 같은 명령을 다른 터미널에서 실행하고 브라우저 로그인을 완료한 다음 재시도합니다. 그렇지 않으면 사용하는 AWS 자격 증명을 직접 갱신합니다. SSO 로그인, 액세스 키, API 키 또는 프록시 토큰이 이에 해당합니다

1580* `awsAuthRefresh`가 대화형 세션에 설정되면, `/login`을 실행하고, **3rd-party platform**을 선택한 후, **Using 3rd-party platforms** 아래에서 **Claude Platform on AWS · refresh credentials**를 선택하여 Claude Code를 다시 시작하지 않고 동일한 명령을 실행할 수 있습니다. [AWS 자격증명 구성](/docs/ko/claude-platform-on-aws#1-configure-aws-credentials)을 참조합니다.1590* 대화형 세션에서 `awsAuthRefresh`가 설정되어 있으면, 대신 `/login`을 실행하고 **3rd-party platform**을 선택한 다음 **Using 3rd-party platforms** 아래의 **Claude Platform on AWS · refresh credentials**를 선택하여 Claude Code를 다시 시작하지 않고 같은 명령을 실행할 수 있습니다. [AWS 자격 증명 구성](/docs/ko/claude-platform-on-aws#1-configure-aws-credentials)을 참조하십시오

1581* 새로 고침 명령이 성공한 후에도 오류가 반복되면, 동일한 셸 및 프로필에서 `aws sts get-caller-identity`로 Claude Code 외부에서 ID가 유효한지 확인합니다.1591* 갱신 명령이 성공한 후에도 오류가 반복되면 같은 셸과 프로필에서 `aws sts get-caller-identity`로 Claude Code 외부에서 ID가 유효한지 확인합니다

1582 1592

1583<h3 id="aws-authentication-failed">1593<h3 id="aws-authentication-failed">

1584 AWS 인증 실패1594 AWS 인증 실패

1585</h3>1595</h3>

1586 1596

1587AWS 공급자가 403을 반환했거나, [Amazon Bedrock](/docs/ko/amazon-bedrock)이 401을 반환했습니다.1597AWS 제공업체가 403을 반환했거나 [Amazon Bedrock](/docs/ko/amazon-bedrock)이 401을 반환했습니다.

1588 1598

1589Amazon Bedrock은 만료된 보안 토큰을 403으로 보고하지만, 403은 또한 누락된 IAM 권한과 같은 `AccessDeniedException`의 인증 거부를 보고하는 방식입니다. Claude Code는 이 두 원인을 구분할 수 없습니다.1599Amazon Bedrock은 만료된 보안 토큰을 403으로 보고하지만, 누락된 IAM 권한으로 인한 `AccessDeniedException`과 같은 권한 부여 거부도 403으로 보고합니다. Claude Code는 이 두 원인을 구분할 수 없습니다.

1590 1600

1591Amazon Bedrock의 401은 [AWS 자격증명이 만료되었거나 유효하지 않습니다](#aws-credentials-expired-or-invalid) 아래가 아닌 여기에 도달합니다. 해당 엔드포인트의 401은 일반적으로 요청 경로의 다른 것(예: 회사 프록시)에서 옵니다.1601Amazon Bedrock은 만료된 토큰을 401로 보고하지 않으므로, Amazon Bedrock의 401도 [AWS 자격 증명 만료 또는 잘못됨](#aws-credentials-expired-or-invalid)이 아닌 여기에 해당합니다. 해당 엔드포인트의 401은 일반적으로 회사 프록시처럼 요청 경로상의 다른 요소에서 발생합니다.

1592 1602

1593자격증명 새로 고침은 만료된 토큰을 수정하고 다른 원인을 수정할 수 없으므로, 메시지는 둘 다 제공합니다:1603자격 증명 갱신은 만료된 토큰은 해결하지만 다른 원인은 해결할 수 없으므로, 메시지는 두 가지를 모두 제시합니다.

1594 1604

1595```text theme={null}1605```text theme={null}

1596AWS authentication failed · run /login and select "Claude Platform on AWS · refresh credentials", or run `aws sso login --profile myprofile` in another terminal · if credentials are current, check AWS permissions and model access · API Error: 403 ...1606AWS authentication failed · run /login and select "Claude Platform on AWS · refresh credentials", or run `aws sso login --profile myprofile` in another terminal · if credentials are current, check AWS permissions and model access · API Error: 403 ...

1597```1607```

1598 1608

1599중간의 작업 힌트는 설정에 따라 달라집니다. 안정적인 부분은 선행 `AWS authentication failed`입니다.1609중간의 조치 안내는 설정에 따라 다릅니다. 고정된 부분은 앞쪽의 `AWS authentication failed`입니다.

1600 1610

1601403이 지정된 모델 ID로 모델에 액세스할 수 없다는 Amazon Bedrock의 답변일 때, 힌트는 대신 Amazon Bedrock 콘솔에서 계정 및 지역에 대해 모델을 활성화하도록 지시합니다.1611403이 지정된 모델 ID의 모델에 대한 액세스 권한이 없다는 Amazon Bedrock의 응답인 경우, 안내는 대신 Amazon Bedrock 콘솔에서 계정과 리전에 대해 모델을 활성화하도록 알려 줍니다.

1602 1612

1603v2.1.273 이전에는 `awsAuthRefresh`가 구성되었을 때만 이 메시지가 나타났습니다.1613v2.1.273 이전에는 `awsAuthRefresh`가 구성된 경우에만 이 메시지가 나타났습니다.

1604 1614

1605**수행할 작업:**1615**해결 방법:**

1606 1616

1607* 힌트가 자격증명이 이 환경에서 관리된다고 하면, 이를 실행한 앱이 자격증명을 소유하며 여기의 다른 단계는 적용되지 않습니다: 재시도하거나, 관리자에게 문의합니다.1617* 안내에 자격 증명이 이 환경에서 관리된다고 표시되면, Claude Code를 실행한 앱이 자격 증명을 소유하므로 여기의 다른 단계는 적용되지 않습니다. 재시도하거나 관리자에게 문의합니다

1608* 만료된 자격증명이 원인일 수 있으므로 AWS 자격증명을 새로 고칩니다: 설정되면 [`awsAuthRefresh`](/docs/ko/amazon-bedrock#advanced-credential-configuration)에서 이름을 지정한 명령을 실행하거나, SSO 로그인, 액세스 키, API 키 또는 프록시 토큰을 직접 새로 고칩니다.1618* 만료된 자격 증명이 원인일 경우에 대비하여 AWS 자격 증명을 갱신합니다. [`awsAuthRefresh`](/docs/ko/amazon-bedrock#advanced-credential-configuration)가 설정되어 있으면 메시지에 명시된 명령을 실행하고, 그렇지 않으면 SSO 로그인, 액세스 키, API 키 또는 프록시 토큰을 직접 갱신합니다

1609* 자격증명이 현재이면, [IAM 구성](/docs/ko/amazon-bedrock#iam-configuration)의 IAM 권한이 사용 중인 ID에 연결되어 있고 선택한 모델이 계정 및 지역에 대해 활성화되어 있는지 확인합니다.1619* 자격 증명이 최신 상태라면 [IAM 구성](/docs/ko/amazon-bedrock#iam-configuration)의 IAM 권한이 사용 중인 ID에 연결되어 있고 선택한 모델이 계정과 리전에 대해 활성화되어 있는지 확인합니다

1610* `aws sts get-caller-identity`를 실행하여 요청이 어떤 ID를 사용하는지 확인합니다.1620* `aws sts get-caller-identity`를 실행하여 요청에 어떤 ID가 사용되는지 확인합니다

1611 1621

1612<h3 id="google-cloud-credentials-expired-or-invalid">1622<h3 id="google-cloud-credentials-expired-or-invalid">

1613 Google Cloud 자격증명이 만료되었거나 유효하지 않습니다1623 Google Cloud 자격 증명 만료 또는 잘못됨

1614</h3>1624</h3>

1615 1625

1616[Google Cloud의 Agent Platform](/docs/ko/google-vertex-ai)에 대한 Google Cloud 자격증명이 만료되었거나 거부되었습니다: 요청이 401을 반환했으며, 이는 Agent Platform이 자격증명 만료를 보고하는 방식입니다.1626[Google Cloud's Agent Platform](/docs/ko/google-vertex-ai)용 Google Cloud 자격 증명이 만료되었거나 거부되었습니다. 요청이 401을 반환했으며, 이는 Agent Platform이 자격 증명 만료를 보고하는 방식입니다.

1617 1627

1618중간의 작업 힌트는 설정에 따라 달라집니다. 안정적인 부분은 선행 `Google Cloud credentials expired or invalid`입니다:1628중간의 조치 안내는 설정에 따라 다릅니다. 고정된 부분은 앞쪽의 `Google Cloud credentials expired or invalid`입니다.

1619 1629

1620```text theme={null}1630```text theme={null}

1621Google Cloud credentials expired or invalid · refresh your Google Cloud credentials (application default sign-in, or the key file in GOOGLE_APPLICATION_CREDENTIALS) and retry · API Error: 401 ...1631Google Cloud credentials expired or invalid · refresh your Google Cloud credentials (application default sign-in, or the key file in GOOGLE_APPLICATION_CREDENTIALS) and retry · API Error: 401 ...

1622```1632```

1623 1633

1624**수행할 작업:**1634**해결 방법:**

1625 1635

1626* 힌트가 자격증명이 이 환경에서 관리된다고 하면, 이를 실행한 앱이 자격증명을 소유하며 여기의 다른 단계는 적용되지 않습니다: 재시도하거나, 관리자에게 문의합니다.1636* 안내에 자격 증명이 이 환경에서 관리된다고 표시되면, Claude Code를 실행한 앱이 자격 증명을 소유하므로 여기의 다른 단계는 적용되지 않습니다. 재시도하거나 관리자에게 문의합니다

1627* 애플리케이션 기본 자격증명으로 인증하면, 메시지에서 이름을 지정한 [`gcpAuthRefresh`](/docs/ko/google-vertex-ai#advanced-credential-configuration) 명령을 실행하거나, `gcloud auth application-default login`을 실행하고 로그인을 완료한 후 재시도합니다.1637* 애플리케이션 기본 자격 증명으로 인증하는 경우, 메시지에 명시된 [`gcpAuthRefresh`](/docs/ko/google-vertex-ai#advanced-credential-configuration) 명령 또는 `gcloud auth application-default login`을 실행하고 로그인을 완료한 다음 재시도합니다

1628* `CLAUDE_CODE_SKIP_VERTEX_AUTH`가 설정된 [LLM 게이트웨이](/docs/ko/llm-gateway)를 통해 라우팅하면, `ANTHROPIC_AUTH_TOKEN` 또는 `ANTHROPIC_CUSTOM_HEADERS`의 게이트웨이 토큰을 새로 고친 후 재시도합니다.1638* `CLAUDE_CODE_SKIP_VERTEX_AUTH`를 설정하고 [LLM 게이트웨이](/docs/ko/llm-gateway)를 통해 라우팅하는 경우, `ANTHROPIC_AUTH_TOKEN` 또는 `ANTHROPIC_CUSTOM_HEADERS`의 게이트웨이 토큰을 갱신한 다음 재시도합니다

1629* 서비스 계정 키 파일로 인증하면, `GOOGLE_APPLICATION_CREDENTIALS`가 유효한 키를 가리키는지 확인합니다. [GCP 자격증명 구성](/docs/ko/google-vertex-ai#3-configure-gcp-credentials)을 참조합니다.1639* 서비스 계정 키 파일로 인증하는 경우 `GOOGLE_APPLICATION_CREDENTIALS`가 유효한 키를 가리키는지 확인합니다. [GCP 자격 증명 구성](/docs/ko/google-vertex-ai#3-configure-gcp-credentials)을 참조하십시오

1630* 새로 고침 후에도 오류가 반복되면, 동일한 셸에서 `gcloud auth application-default print-access-token`으로 Claude Code 외부에서 ID가 작동하는지 확인합니다.1640* 갱신 후에도 오류가 반복되면 같은 셸에서 `gcloud auth application-default print-access-token`으로 Claude Code 외부에서 ID가 작동하는지 확인합니다

1631 1641

1632v2.1.273 이전에는 Agent Platform의 401이 자격증명을 새로 고칠 수 없는 일반적인 `Please run /login` 또는 `Failed to authenticate` 메시지를 표시했습니다.1642v2.1.273 이전에는 Agent Platform의 401이 대신 일반적인 `Please run /login` 또는 `Failed to authenticate` 메시지를 표시했으며, 이 방법으로는 Google Cloud 자격 증명을 갱신할 수 없었습니다.

1633 1643

1634<h3 id="google-cloud-authentication-failed">1644<h3 id="google-cloud-authentication-failed">

1635 Google Cloud 인증 실패1645 Google Cloud 인증 실패

1636</h3>1646</h3>

1637 1647

1638[Google Cloud의 Agent Platform](/docs/ko/google-vertex-ai)이 403을 반환했으며, 이는 만료된 자격증명이 아닌 인증 거부에 사용합니다. 일반적으로 인증하는 ID에 IAM 권한이 부족하거나, 모델이 프로젝트에 대해 활성화되지 않았습니다.1648[Google Cloud's Agent Platform](/docs/ko/google-vertex-ai)이 403을 반환했습니다. Agent Platform은 만료된 자격 증명이 아닌 권한 부여 거부에 403을 사용합니다. 일반적으로 인증에 사용하는 ID에 IAM 권한이 없거나, 프로젝트에 대해 모델이 활성화되어 있지 않은 경우입니다.

1639 1649

1640중간의 작업 힌트는 설정에 따라 달라집니다. 안정적인 부분은 선행 `Google Cloud authentication failed`입니다:1650중간의 조치 안내는 설정에 따라 다릅니다. 고정된 부분은 앞쪽의 `Google Cloud authentication failed`입니다.

1641 1651

1642```text theme={null}1652```text theme={null}

1643Google Cloud authentication failed · refresh your Google Cloud credentials (application default sign-in, or the key file in GOOGLE_APPLICATION_CREDENTIALS) and retry · if credentials are current, check GCP IAM permissions and Vertex AI model access · API Error: 403 ...1653Google Cloud authentication failed · refresh your Google Cloud credentials (application default sign-in, or the key file in GOOGLE_APPLICATION_CREDENTIALS) and retry · if credentials are current, check GCP IAM permissions and Vertex AI model access · API Error: 403 ...

1644```1654```

1645 1655

1646**수행할 작업:**1656**해결 방법:**

1647 1657

1648* 힌트가 자격증명이 이 환경에서 관리된다고 하면, 이를 실행한 앱이 자격증명을 소유하며 여기의 다른 단계는 적용되지 않습니다: 재시도하거나, 관리자에게 문의합니다.1658* 안내에 자격 증명이 이 환경에서 관리된다고 표시되면, Claude Code를 실행한 앱이 자격 증명을 소유하므로 여기의 다른 단계는 적용되지 않습니다. 재시도하거나 관리자에게 문의합니다

1649* [IAM 구성](/docs/ko/google-vertex-ai#iam-configuration)의 역할이 인증하는 ID에 부여되어 있는지 확인합니다.1659* [IAM 구성](/docs/ko/google-vertex-ai#iam-configuration)의 역할이 인증에 사용하는 ID에 부여되어 있는지 확인합니다

1650* 모델이 프로젝트에 대해 활성화되어 있는지 확인합니다. [모델 액세스 요청](/docs/ko/google-vertex-ai#2-request-model-access)을 참조합니다.1660* 프로젝트에 대해 모델이 활성화되어 있는지 확인합니다. [모델 액세스 요청](/docs/ko/google-vertex-ai#2-request-model-access)을 참조하십시오

1651 1661

1652v2.1.273 이전에는 Agent Platform의 403이 자격증명을 새로 고칠 수 없는 일반적인 `Please run /login` 또는 `Failed to authenticate` 메시지를 표시했습니다.1662v2.1.273 이전에는 Agent Platform의 403이 대신 일반적인 `Please run /login` 또는 `Failed to authenticate` 메시지를 표시했으며, 이 방법으로는 Google Cloud 자격 증명을 갱신할 수 없었습니다.

1653 1663

1654<h3 id="microsoft-foundry-authentication-failed">1664<h3 id="microsoft-foundry-authentication-failed">

1655 Microsoft Foundry 인증 실패1665 Microsoft Foundry authentication failed

1656</h3>1666</h3>

1657 1667

1658[Microsoft Foundry](/docs/ko/microsoft-foundry)가 401 또는 403을 반환했습니다: 요청의 Azure 자격증명이 거부되었거나, 뒤에 있는 ID가 Foundry 리소스에 액세스할 수 없습니다. `/login`은 Azure 자격증명을 발급할 수 없습니다. 중간의 작업 힌트는 설정에 따라 달라집니다. 안정적인 부분은 선행 `Microsoft Foundry authentication failed`입니다:1668[Microsoft Foundry](/docs/ko/microsoft-foundry)가 401 또는 403을 반환했습니다. 요청에 포함된 Azure 자격 증명이 거부되었거나, 해당 자격 증명의 ID에 Foundry 리소스에 대한 액세스 권한이 없습니다. `/login`은 Azure 자격 증명을 발급할 수 없습니다. 중간의 조치 안내는 설정에 따라 달라집니다. 고정된 부분은 앞부분의 `Microsoft Foundry authentication failed`입니다.

1659 1669

1660```text theme={null}1670```text theme={null}

1661Microsoft Foundry authentication failed · refresh your Foundry credential (ANTHROPIC_FOUNDRY_AUTH_TOKEN, ANTHROPIC_FOUNDRY_API_KEY, Azure sign-in for Entra, or your proxy token) and retry · if credentials are current, check access to the Foundry resource · API Error: 401 ...1671Microsoft Foundry authentication failed · refresh your Foundry credential (ANTHROPIC_FOUNDRY_AUTH_TOKEN, ANTHROPIC_FOUNDRY_API_KEY, Azure sign-in for Entra, or your proxy token) and retry · if credentials are current, check access to the Foundry resource · API Error: 401 ...

1662```1672```

1663 1673

1664**수행할 작업:**1674**조치 방법:**

1665 1675

1666* 힌트가 자격증명이 이 환경에서 관리된다고 하면, 이를 실행한 앱이 자격증명을 소유하며 여기의 다른 단계는 적용되지 않습니다: 재시도하거나, 관리자에게 문의합니다.1676* 안내에 자격 증명이 이 환경에서 관리된다고 표시되면, Claude Code를 실행한 앱이 자격 증명을 소유하므로 여기의 다른 단계는 적용되지 않습니다. 재시도하거나 관리자에게 문의하십시오

1667* [Azure 자격증명 구성](/docs/ko/microsoft-foundry#2-configure-azure-credentials)에서 구성한 자격증명을 새로 고칩니다: `ANTHROPIC_FOUNDRY_API_KEY`를 회전하거나, 새 `ANTHROPIC_FOUNDRY_AUTH_TOKEN`을 발급하거나, `az login`을 실행하여 기본 Microsoft Entra 자격증명 체인이 다시 로그인할 수 있도록 합니다.1677* [Azure 자격 증명 구성](/docs/ko/microsoft-foundry#2-configure-azure-credentials)에서 구성한 자격 증명을 새로 고치십시오. `ANTHROPIC_FOUNDRY_API_KEY`를 교체하거나, 새 `ANTHROPIC_FOUNDRY_AUTH_TOKEN`을 발급하거나, `az login`을 실행하여 기본 Microsoft Entra 자격 증명 체인이 다시 로그인할 수 있도록 합니다

1668* 자격증명이 현재이면, ID가 Foundry 리소스에 액세스할 수 있는지 확인합니다. [Azure RBAC 구성](/docs/ko/microsoft-foundry#azure-rbac-configuration)을 참조합니다.1678* 자격 증명이 최신 상태라면 해당 ID에 Foundry 리소스에 대한 액세스 권한이 있는지 확인하십시오. [Azure RBAC 구성](/docs/ko/microsoft-foundry#azure-rbac-configuration)을 참조하십시오

1669 1679

1670v2.1.273 이전에는 Microsoft Foundry의 401 또는 403이 자격증명을 새로 고칠 수 없는 일반적인 `Please run /login` 또는 `Failed to authenticate` 메시지를 표시했습니다.1680v2.1.273 이전에는 Microsoft Foundry의 401 또는 403에 대해 Azure 자격 증명을 새로 고칠 수 없는 일반적인 `Please run /login` 또는 `Failed to authenticate` 메시지가 대신 표시되었습니다.

1671 1681

1672<h3 id="could-not-load-aws-or-google-cloud-credentials">1682<h3 id="could-not-load-aws-or-google-cloud-credentials">

1673 AWS 또는 Google Cloud 자격증명을 로드할 수 없습니다1683 Could not load AWS or Google Cloud credentials

1674</h3>1684</h3>

1675 1685

1676Claude Code가 AWS 자격증명 공급자 체인 또는 머신의 Google 애플리케이션 기본 자격증명에서 사용 가능한 자격증명을 얻을 수 없어서, 요청이 클라우드 공급자에 도달하지 않았습니다. Claude Code는 캐시된 자격증명을 지우고 표시하기 전에 두 번 재시도합니다. `·` 이후의 세부 정보는 만료된 SSO 세션, `Could not load the default credentials`로 보고된 누락된 애플리케이션 기본 자격증명 또는 `invalid_grant`로 보고된 취소된 로그인과 같은 특정 원인의 이름을 지정합니다:1686Claude Code가 실행 중인 머신에서 AWS 자격 증명 공급자 체인이나 Google 애플리케이션 기본 자격 증명으로부터 사용 가능한 자격 증명을 얻지 못했기 때문에, 요청이 클라우드 공급자에 도달하지 않았습니다. Claude Code는 이 메시지를 표시하기 전에 캐시된 자격 증명을 지우고 두 번 재시도합니다. `·` 뒤의 세부 정보는 구체적인 원인을 나타냅니다. 예를 들어 만료된 SSO 세션, `Could not load the default credentials`로 보고되는 애플리케이션 기본 자격 증명 누락, `invalid_grant`로 보고되는 취소된 로그인 등이 있습니다.

1677 1687

1678```text theme={null}1688```text theme={null}

1679API Error: Could not load AWS credentials · Could not load credentials from any providers. Check or refresh your AWS credentials and try again.1689API Error: Could not load AWS credentials · Could not load credentials from any providers. Check or refresh your AWS credentials and try again.

1680API Error: Could not load Google Cloud credentials · invalid_grant. Check or refresh your Google Cloud credentials and try again.1690API Error: Could not load Google Cloud credentials · invalid_grant. Check or refresh your Google Cloud credentials and try again.

1681```1691```

1682 1692

1683[비대화형 모드](/docs/ko/headless)에서 `-p`와 [Agent SDK](/docs/ko/agent-sdk/overview)에서 구조화된 오류 코드는 `cloud_credential_error`입니다. v2.1.267 이전에는 메시지가 `API Error:` 이후의 세부 정보만 표시했으며, 구조화된 코드는 `server_error` 또는 `unknown`이었습니다.1693`-p`를 사용하는 [비대화형 모드](/docs/ko/headless)와 [Agent SDK](/docs/ko/agent-sdk/overview)에서 구조화된 오류 코드는 `cloud_credential_error`입니다. v2.1.267 이전에는 메시지에 `API Error:` 뒤의 세부 텍스트만 표시되었고, 구조화된 코드는 `server_error` 또는 `unknown`이었습니다.

1684 1694

1685**수행할 작업:**1695**조치 방법:**

1686 1696

1687* `aws sso login --profile myprofile` 또는 `gcloud auth application-default login`과 같은 공급자의 로그인 명령을 실행한 후 재시도합니다. [Bedrock, Agent Platform 또는 Foundry 자격증명이 로드되지 않음](/docs/ko/troubleshoot-install#bedrock-agent-platform-or-foundry-credentials-not-loading)은 Claude Code 외부에서 자격증명을 확인하는 방법을 보여줍니다.1697* `aws sso login --profile myprofile` 또는 `gcloud auth application-default login`과 같은 공급자의 로그인 명령을 실행한 후 재시도하십시오. [Bedrock, Agent Platform 또는 Foundry 자격 증명이 로드되지 않음](/docs/ko/troubleshoot-install#bedrock-agent-platform-or-foundry-credentials-not-loading)에서 Claude Code 외부에서 자격 증명을 확인하는 방법을 설명합니다

1688* 세부 정보가 `AWS default-chain credential resolve timed out`을 읽으면, 체인이 실패하지 않고 중단되었으므로, 대신 [AWS default-chain credential resolve timed out](#aws-default-chain-credential-resolve-timed-out)을 따릅니다.1698* 세부 정보가 `AWS default-chain credential resolve timed out`이라면 체인이 실패한 것이 아니라 멈춘 것이므로, 대신 [AWS default-chain credential resolve timed out](#aws-default-chain-credential-resolve-timed-out)을 따르십시오

1689 1699

1690<h3 id="aws-default-chain-credential-resolve-timed-out">1700<h3 id="aws-default-chain-credential-resolve-timed-out">

1691 AWS default-chain credential resolve timed out1701 AWS default-chain credential resolve timed out

1692</h3>1702</h3>

1693 1703

1694AWS 기본 자격증명 공급자 체인이 60초 내에 자격증명을 생성하지 않아서, Claude Code가 확인을 중지하고 요청을 실패했습니다. 이 시간 초과는 [AWS 또는 Google Cloud 자격증명을 로드할 수 없습니다](#could-not-load-aws-or-google-cloud-credentials)의 한 원인입니다. 실패는 로컬 자격증명 확인입니다: 요청이 [Amazon Bedrock](/docs/ko/amazon-bedrock), [Claude Platform on AWS](/docs/ko/claude-platform-on-aws) 또는 [Mantle 엔드포인트](/docs/ko/amazon-bedrock#use-the-mantle-endpoint)에 도달하지 않았습니다. Claude Code는 [자격증명 캐시](/docs/ko/amazon-bedrock#credential-caching-and-resolution-timeout)를 지우고 이 오류가 표시되기 전에 재시도하므로, 이를 볼 때쯤 체인이 반복된 시도에서 중단되었습니다.1704AWS 기본 자격 증명 공급자 체인이 60초 이내에 자격 증명을 생성하지 못했기 때문에 Claude Code가 확인 작업을 중단하고 요청을 실패 처리했습니다. 이 시간 초과는 [Could not load AWS or Google Cloud credentials](#could-not-load-aws-or-google-cloud-credentials)의 원인 중 하나입니다. 이 실패는 로컬 자격 증명 확인 과정에서 발생한 것으로, 요청은 [Amazon Bedrock](/docs/ko/amazon-bedrock), [Claude Platform on AWS](/docs/ko/claude-platform-on-aws) 또는 [Mantle 엔드포인트](/docs/ko/amazon-bedrock#use-the-mantle-endpoint)에 도달하지 않았습니다. Claude Code는 이 오류를 표시하기 전에 [자격 증명 캐시](/docs/ko/amazon-bedrock#credential-caching-and-resolution-timeout)를 지우고 재시도하므로, 이 오류가 표시될 때는 체인이 반복된 시도에서 멈춘 상태입니다.

1695 1705

1696```text theme={null}1706```text theme={null}

1697API Error: Could not load AWS credentials · AWS default-chain credential resolve timed out. Check or refresh your AWS credentials and try again.1707API Error: Could not load AWS credentials · AWS default-chain credential resolve timed out. Check or refresh your AWS credentials and try again.

1698```1708```

1699 1709

1700일반적인 원인은 AWS 프로필의 `credential_process` 명령이 받을 수 없는 입력을 기다리고 있으며, 컨테이너 또는 VM의 인스턴스 메타데이터 서비스(IMDS)가 체인의 프로브에 응답하지 않습니다.1710일반적인 원인으로는 받을 수 없는 입력을 기다리는 AWS 프로필의 `credential_process` 명령, 그리고 인스턴스 메타데이터 서비스(IMDS)가 체인의 프로브에 응답하지 않는 컨테이너나 VM이 있습니다.

1701 1711

1702v2.1.267 이전에는 메시지가 `API Error: AWS default-chain credential resolve timed out`을 읽었습니다.1712v2.1.267 이전에는 메시지가 `API Error: AWS default-chain credential resolve timed out`으로 표시되었습니다.

1703v2.1.207 이전에는 중단된 체인이 실패하는 대신 요청을 무한정 기다리게 했습니다.1713v2.1.207 이전에는 체인이 멈추면 요청이 실패하지 않고 무기한 대기했습니다.

1704 1714

1705**수행할 작업:**1715**조치 방법:**

1706 1716

1707* 동일한 셸에서 동일한 `AWS_PROFILE`로 `aws sts get-caller-identity`를 실행합니다. 또한 중단되면, 프로필을 수정합니다. 대화형으로 프롬프트하는 `credential_process` 명령이 일반적인 원인입니다.1717* 동일한 셸에서 동일한 `AWS_PROFILE`로 `aws sts get-caller-identity`를 실행하십시오. 이 명령도 멈춘다면 프로필을 수정하십시오. 대화형으로 입력을 요청하는 `credential_process` 명령이 흔한 원인입니다.

1708* Claude Code를 시작하기 전에 로그인 단계를 완료합니다. 예를 들어 `aws sso login --profile myprofile`을 실행하여 체인이 브라우저 흐름을 기다리는 대신 로컬 SSO 캐시에서 확인되도록 합니다.1718* Claude Code를 시작하기 전에 로그인 단계를 완료하십시오. 예: `aws sso login --profile myprofile`

1709* 체인이 `aws-vault`와 같은 래퍼를 통해 MFA가 있는 SSO와 같이 60초 이상 필요로 하는 대화형 로그인을 실행하면, [`CLAUDE_CODE_AWS_CHAIN_RESOLVE_TIMEOUT_MS`](/docs/ko/env-vars)에서 밀리초 단위로 제한을 높입니다.1719* `aws-vault`와 같은 래퍼를 통한 MFA 포함 SSO처럼 체인이 실제로 60초 이상 필요한 대화형 로그인을 실행하는 경우, [`CLAUDE_CODE_AWS_CHAIN_RESOLVE_TIMEOUT_MS`](/docs/ko/env-vars)로 제한을 밀리초 단위로 늘리십시오

1710 1720

1711<h3 id="bedrock-setup-verification-timed-out-waiting-for-aws">1721<h3 id="bedrock-setup-verification-timed-out-waiting-for-aws">

1712 Bedrock 설정 확인이 AWS를 기다리다가 시간 초과되었습니다1722 Bedrock setup verification timed out waiting for AWS

1713</h3>1723</h3>

1714 1724

1715[Bedrock 설정 마법사](/docs/ko/amazon-bedrock#sign-in-with-bedrock)의 자격증명 확인 중 AWS에 대한 호출(예: 자격증명 조회 또는 ID 확인)이 60초 제한 내에 완료되지 않았습니다. 마법사가 기다리기를 중지하고 확인 단계를 실패합니다:1725[Bedrock 설정 마법사](/docs/ko/amazon-bedrock#sign-in-with-bedrock)의 자격 증명 확인 중에 자격 증명 조회나 ID 확인과 같은 AWS 호출이 60초 제한 내에 완료되지 않았습니다. 마법사는 대기를 중단하고 확인 단계를 실패 처리합니다.

1716 1726

1717```text theme={null}1727```text theme={null}

1718Timed out after 60s waiting for AWS. Check your network and proxy settings; if a credential helper needs longer to prompt you, raise CLAUDE_CODE_AWS_CHAIN_RESOLVE_TIMEOUT_MS.1728Timed out after 60s waiting for AWS. Check your network and proxy settings; if a credential helper needs longer to prompt you, raise CLAUDE_CODE_AWS_CHAIN_RESOLVE_TIMEOUT_MS.

1719```1729```

1720 1730

1721숫자는 제한을 반영합니다: 기본적으로 60초 또는 [`CLAUDE_CODE_AWS_CHAIN_RESOLVE_TIMEOUT_MS`](/docs/ko/env-vars)에서 설정한 값입니다.1731숫자는 설정된 제한을 반영합니다. 기본값은 60초이며, [`CLAUDE_CODE_AWS_CHAIN_RESOLVE_TIMEOUT_MS`](/docs/ko/env-vars)에 설정한 값이 있으면 그 값이 표시됩니다.

1722 1732

1723일반적인 원인은 SSO 토큰 새로 고침을 포함하여 AWS에 대한 요청을 중단하는 네트워크 또는 프록시이며, 자격증명 헬퍼가 볼 수 없는 입력을 기다리고 있습니다. 헬퍼가 합법적으로 더 많은 시간이 필요할 때만 제한을 높입니다.1733일반적인 원인으로는 SSO 토큰 새로 고침을 포함하여 AWS에 대한 요청을 지연시키는 네트워크나 프록시, 그리고 화면에 보이지 않는 입력을 계속 기다리고 있는 자격 증명 도우미가 있습니다. 도우미가 실제로 더 많은 시간을 필요로 하는 경우에만 제한을 늘리십시오.

1724 1734

1725AWS에 대한 단일 중단된 요청도 자체 요청별 시간 초과로 실패할 수 있으며, 동일한 단계에서 더 짧은 메시지를 표시합니다:1735AWS에 대한 단일 요청이 멈춘 경우 자체 요청별 타임아웃으로 실패할 수도 있으며, 이때는 같은 단계에서 더 짧은 메시지가 표시됩니다.

1726 1736

1727```text theme={null}1737```text theme={null}

1728A request to AWS timed out. Check your network and proxy settings, then try again.1738A request to AWS timed out. Check your network and proxy settings, then try again.

1729```1739```

1730 1740

1731동일한 시간 초과가 모델 핀 단계에서 발생하면, 마법사가 메시지를 표시하는 대신 모델을 `unreachable`로 표시합니다.1741모델 고정 단계에서 동일한 시간 초과가 발생하면, 마법사는 두 메시지 중 어느 것도 표시하지 않고 해당 모델을 `unreachable`로 표시합니다.

1732 1742

1733**수행할 작업:**1743**조치 방법:**

1734 1744

1735* 동일한 셸에서 `aws sts get-caller-identity`를 실행합니다. 또한 중단되면, 중단이 Claude Code 외부에 있습니다. 네트워크, 프록시 또는 AWS 프로필의 자격증명 헬퍼에서 먼저 수정합니다.1745* 동일한 셸에서 `aws sts get-caller-identity`를 실행하십시오. 이 명령도 멈춘다면 지연은 Claude Code 외부, 즉 네트워크, 프록시 또는 AWS 프로필의 자격 증명 도우미에서 발생하는 것이므로 이를 먼저 해결하십시오.

1736* 마법사를 열기 전에 대화형 로그인을 완료합니다. 예를 들어 `aws sso login --profile myprofile`을 실행합니다.1746* 마법사를 열기 전에 대화형 로그인을 완료하십시오. 예: `aws sso login --profile myprofile`

1737* AWS 프로필의 자격증명 헬퍼가 합법적으로 60초 이상 프롬프트를 기다려야 하면, [`CLAUDE_CODE_AWS_CHAIN_RESOLVE_TIMEOUT_MS`](/docs/ko/env-vars)에서 밀리초 단위로 제한을 높입니다.1747* AWS 프로필의 자격 증명 도우미가 확인을 요청하는 데 실제로 60초보다 오래 걸리는 경우, [`CLAUDE_CODE_AWS_CHAIN_RESOLVE_TIMEOUT_MS`](/docs/ko/env-vars)로 제한을 밀리초 단위로 늘리십시오

1738 1748

1739<h3 id="cloud-gateway-session-expired">1749<h3 id="cloud-gateway-session-expired">

1740 클라우드 게이트웨이 세션 만료됨1750 Cloud gateway session expired

1741</h3>1751</h3>

1742 1752

1743[Claude apps 게이트웨이](/docs/ko/claude-apps-gateway)를 통해 로그인했으며, 이 머신에 저장된 게이트웨이 세션이 만료되었으며 갱신할 수 없거나, 게이트웨이가 더 이상 수락하지 않습니다. 예를 들어 게이트웨이의 [JWT 비밀이 교체된](/docs/ko/claude-apps-gateway-deploy#jwt-secret-rotation) 후입니다. 대화형으로 `claude`를 시작할 때 이 라인을 보면, 세션이 게이트웨이에서 로그아웃된 상태로 열렸습니다:1753[Claude apps 게이트웨이](/docs/ko/claude-apps-gateway)를 통해 로그인했으나, 이 머신에 저장된 게이트웨이 세션이 만료되어 갱신할 수 없거나, 예를 들어 게이트웨이의 [JWT 시크릿이 교체된](/docs/ko/claude-apps-gateway-deploy#jwt-secret-rotation) 후처럼 게이트웨이가 더 이상 해당 세션을 허용하지 않습니다. `claude`를 대화형으로 시작할 때 이 줄이 표시되면, 세션이 게이트웨이에서 로그아웃된 상태로 열린 것입니다.

1744 1754

1745```text theme={null}1755```text theme={null}

1746Cloud gateway session expired — run /login to reconnect.1756Cloud gateway session expired — run /login to reconnect.

1747```1757```

1748 1758

1749동일한 라인이 게이트웨이 자격증명이 만료되고 Claude Code가 갱신할 수 없을 때 세션 중에 나타날 수 있습니다.1759게이트웨이 자격 증명이 만료되고 Claude Code가 이를 갱신할 수 없는 경우 세션 도중에도 같은 줄이 표시될 수 있습니다.

1750 1760

1751[비대화형](/docs/ko/headless) 실행, 백그라운드 또는 기타 무인 세션 또는 `claude auth` 이외의 `claude` 하위 명령에서, Claude Code는 게이트웨이가 더 이상 세션을 수락하지 않을 때 대신 이 메시지로 종료됩니다:1761[비대화형](/docs/ko/headless) 실행, 백그라운드 또는 기타 무인 세션, 또는 `claude auth` 이외의 `claude` 하위 명령에서는 게이트웨이가 더 이상 세션을 허용하지 않을 때 Claude Code가 대신 다음 메시지와 함께 종료됩니다.

1752 1762

1753```text theme={null}1763```text theme={null}

1754Cloud gateway <url> no longer accepts this session. Start `claude` and sign in again with /login.1764Cloud gateway <url> no longer accepts this session. Start `claude` and sign in again with /login.

1755```1765```

1756 1766

1757**수행할 작업:**1767**조치 방법:**

1758 1768

1759* 세션에서 `/login`을 실행하고 브라우저 로그인을 완료합니다.1769* 세션에서 `/login`을 실행하고 브라우저 로그인을 완료하십시오

1760* 비대화형 실행의 경우, 동일한 환경에서 `claude`를 시작하고, `/login`을 실행한 후 명령을 다시 실행합니다.1770* 비대화형 실행의 경우 동일한 환경에서 `claude`를 시작하고 `/login`을 실행한 다음 명령을 다시 실행하십시오

1761 1771

1762<h3 id="sign-in-timed-out-while-waiting-for-you-to-continue">1772<h3 id="sign-in-timed-out-while-waiting-for-you-to-continue">

1763 로그인이 계속하기를 기다리다가 시간 초과되었습니다1773 Sign-in timed out while waiting for you to continue

1764</h3>1774</h3>

1765 1775

1766[Claude apps 게이트웨이](/docs/ko/claude-apps-gateway) 로그인 중에 게이트웨이가 로그인한 계정의 이름을 지정했으며, Claude Code가 자격증명을 저장하기 전에 확인하도록 요청했습니다. 로그인 자신의 만료를 지나 확인을 열어 두었으며, 게이트웨이가 갱신할 수 있는 새로 고침 토큰을 발급하지 않았으므로, Claude Code가 계속할 때 아무것도 저장하지 않았습니다:1776[Claude apps 게이트웨이](/docs/ko/claude-apps-gateway) 로그인 중에 게이트웨이가 로그인한 계정을 알려 주었고, Claude Code는 자격 증명을 저장하기 전에 해당 계정을 확인하도록 요청했습니다. 확인 화면을 로그인 자체의 만료 시간이 지나도록 열어 두었고, 게이트웨이가 이를 갱신할 수 있는 리프레시 토큰을 발급하지 않았기 때문에, 계속을 선택했을 때 Claude Code는 아무것도 저장하지 않았습니다.

1767 1777

1768```text theme={null}1778```text theme={null}

1769Sign-in timed out while waiting for you to continue. Try again.1779Sign-in timed out while waiting for you to continue. Try again.

1770```1780```

1771 1781

1772**수행할 작업:**1782**조치 방법:**

1773 1783

1774* `/login`을 다시 실행하고 로그인이 만료되기 전에 계정을 확인합니다.1784* `/login`을 다시 실행하고 로그인이 만료되기 전에 계정을 확인하십시오

1775 1785

1776<h3 id="gateway-refused-the-request">1786<h3 id="gateway-refused-the-request">

1777 게이트웨이가 요청을 거부했습니다1787 Gateway refused the request

1778</h3>1788</h3>

1779 1789

1780[Claude apps 게이트웨이](/docs/ko/claude-apps-gateway)를 통해 로그인했으며, 요청이 403을 반환했습니다: 게이트웨이 또는 뒤의 업스트림이 거부했습니다. 다시 로그인하면 거부가 변경되지 않으므로, 메시지는 게이트웨이 관리자를 가리킵니다:1790[Claude apps 게이트웨이](/docs/ko/claude-apps-gateway)를 통해 로그인한 상태에서 요청이 403을 반환했습니다. 게이트웨이 또는 그 뒤의 업스트림이 요청을 거부한 것입니다. 다시 로그인해도 거부는 바뀌지 않으므로, 메시지는 게이트웨이 관리자에게 문의하도록 안내합니다.

1781 1791

1782```text theme={null}1792```text theme={null}

1783Gateway refused the request · signing in again won't change this — check with your gateway administrator · API Error: 403 ...1793Gateway refused the request · signing in again won't change this — check with your gateway administrator · API Error: 403 ...

1784```1794```

1785 1795

1786**수행할 작업:**1796**조치 방법:**

1787 1797

1788* 게이트웨이 관리자에게 요청을 조회하도록 요청합니다. `API Error:` 꼬리는 게이트웨이가 반환한 거부를 전달합니다.1798* 게이트웨이 관리자에게 해당 요청을 조회하도록 요청하십시오. `API Error:` 뒷부분에 게이트웨이가 반환한 거부 내용이 포함되어 있습니다

1789* 관리자의 경우: 게이트웨이의 [액세스 제어 규칙](/docs/ko/claude-apps-gateway-config#http-tuning)이 [감사 로그](/docs/ko/claude-apps-gateway-deploy#logs)가 이유와 함께 기록하는 403을 반환하며, 업스트림의 인증 거부는 [업스트림 오류 메시지](/docs/ko/claude-apps-gateway-config#upstream-error-messages)에 따라 통과합니다.1799* 관리자의 경우: 게이트웨이의 [액세스 제어 규칙](/docs/ko/claude-apps-gateway-config#http-tuning)은 403을 반환하며 [감사 로그](/docs/ko/claude-apps-gateway-deploy#logs)에 그 사유가 기록됩니다. 업스트림의 인가 거부는 [업스트림 오류 메시지](/docs/ko/claude-apps-gateway-config#upstream-error-messages)에 따라 그대로 전달됩니다

1790 1800

1791v2.1.273 이전에는 게이트웨이 세션의 403이 일반적인 `Please run /login` 또는 `Failed to authenticate` 메시지를 표시했으며, 다시 로그인해도 거부가 지워지지 않았습니다.1801v2.1.273 이전에는 게이트웨이 세션의 403에 대해 일반적인 `Please run /login` 또는 `Failed to authenticate` 메시지가 대신 표시되었으며, 다시 로그인해도 거부가 해소되지 않았습니다.

1792 1802

1793<h2 id="network-and-connection-errors">1803<h2 id="network-and-connection-errors">

1794 네트워크 및 연결 오류1804 네트워크 및 연결 오류

1848 1858

1849Claude Code는 API 요청과 동일한 [프록시 구성](/docs/ko/network-config)을 통해 확인을 보내고 각 프로브에 10초를 제공합니다. 실패한 프로브가 프록시를 통과한 경우, 메시지는 `HTTPS_PROXY`와 같이 이를 구성한 환경 변수의 이름을 지정합니다. v2.1.222 이전에는 확인이 타임아웃이 없는 다른 프록시 전송을 사용했습니다. `https://` 스키마가 있는 프록시 URL 뒤에서 `Checking connectivity...`에서 무한정 정지될 수 있었고, 동일한 프록시를 통한 API 요청이 성공하더라도 실패할 수 있었습니다.1859Claude Code는 API 요청과 동일한 [프록시 구성](/docs/ko/network-config)을 통해 확인을 보내고 각 프로브에 10초를 제공합니다. 실패한 프로브가 프록시를 통과한 경우, 메시지는 `HTTPS_PROXY`와 같이 이를 구성한 환경 변수의 이름을 지정합니다. v2.1.222 이전에는 확인이 타임아웃이 없는 다른 프록시 전송을 사용했습니다. `https://` 스키마가 있는 프록시 URL 뒤에서 `Checking connectivity...`에서 무한정 정지될 수 있었고, 동일한 프록시를 통한 API 요청이 성공하더라도 실패할 수 있었습니다.

1850 1860

1851Claude Code는 [관리되는 설정 파일, MDM 정책 또는 정책 도우미](/docs/ko/managed-settings)가 [`forceLoginMethod`](/docs/ko/settings-reference#forceloginmethod)를 `"gateway"`로 설정하거나 `forceLoginMethod` 없이 [`forceLoginGatewayUrl`](/docs/ko/settings-reference#forcelogingatewayurl)을 설정할 때 이 확인을 건너뜁니다. 두 구성 중 하나를 사용하면 Claude Code는 Anthropic 로그인 방법이 아닌 **클라우드 게이트웨이** 화면에서 로그인 단계를 엽니다. Claude Code는 또한 머신에 관리되는 설정 소스가 존재하지만 읽을 수 없을 때 확인을 건너뜁니다. 해당 소스가 게이트웨이 구성을 보유할 수 있기 때문입니다. v2.1.247 이전에는 Claude Code가 이 구성에서도 확인을 실행했고, Anthropic의 엔드포인트에 도달할 수 없을 때 이 오류로 종료했습니다.1861Claude Code는 [관리형 설정 파일, MDM 정책 또는 정책 도우미](/docs/ko/managed-settings)가 [`forceLoginMethod`](/docs/ko/settings-reference#forceloginmethod)를 `"gateway"`로 설정하거나 `forceLoginMethod` 없이 [`forceLoginGatewayUrl`](/docs/ko/settings-reference#forcelogingatewayurl)을 설정할 때 이 확인을 건너뜁니다. 두 구성 중 하나를 사용하면 Claude Code는 Anthropic 로그인 방법이 아닌 **클라우드 게이트웨이** 화면에서 로그인 단계를 엽니다. Claude Code는 또한 머신에 관리형 설정 소스가 존재하지만 읽을 수 없을 때 확인을 건너뜁니다. 해당 소스가 게이트웨이 구성을 보유할 수 있기 때문입니다. v2.1.247 이전에는 Claude Code가 이 구성에서도 확인을 실행했고, Anthropic의 엔드포인트에 도달할 수 없을 때 이 오류로 종료했습니다.

1852 1862

1853**수행할 작업:**1863**수행할 작업:**

1854 1864

1884그 시작 후, 메시지는 반환된 내용과 실패한 요청을 보고합니다:1894그 시작 후, 메시지는 반환된 내용과 실패한 요청을 보고합니다:

1885 1895

1886* 콘텐츠 유형, `body is an HTML page` 또는 `empty body`와 같은 본문의 종류, 바이트 단위의 크기, 응답이 Anthropic 요청 ID를 전달했는지 여부를 포함하는 `Response:` 절. 응답이 `nginx` 또는 `cloudflare`와 같은 인식 가능한 서버의 이름을 지정하거나 `cf-ray` 또는 `via`와 같은 중간 헤더를 전달하는 경우, 절은 이들도 나열합니다.1896* 콘텐츠 유형, `body is an HTML page` 또는 `empty body`와 같은 본문의 종류, 바이트 단위의 크기, 응답이 Anthropic 요청 ID를 전달했는지 여부를 포함하는 `Response:` 절. 응답이 `nginx` 또는 `cloudflare`와 같은 인식 가능한 서버의 이름을 지정하거나 `cf-ray` 또는 `via`와 같은 중간 헤더를 전달하는 경우, 절은 이들도 나열합니다.

1887* 실패한 스트리밍 요청의 ID와 재시도를 트리거한 실패의 이름을 지정하는 문장. 스트림이 실패 전에 열린 경우, 도착한 스트림 이벤트의 수와 도움이 된 경우 시도가 실패했을 때 스트림이 얼마나 오래 침묵했는지도 보고합니다.1897* 실패한 스트리밍 요청의 ID와 재시도를 트리거한 실패의 이름을 지정하는 문장. 스트림이 실패 전에 열린 경우, 도착한 스트림 이벤트의 수와, 이벤트가 하나라도 도착했다면 시도가 실패했을 때 스트림이 얼마나 오래 침묵했는지도 보고합니다.

1888 1898

1889v2.1.234 이전에는 메시지가 `intercepting the request` 후에 종료되었습니다.1899v2.1.234 이전에는 메시지가 `intercepting the request` 후에 종료되었습니다.

1890 1900

1977 1987

1978**수행할 작업:**1988**수행할 작업:**

1979 1989

1980이러한 단계는 자신의 환경 중 하나를 변경합니다. [조직 공유 환경](/docs/ko/cloud-environments#organization-shared-environments)은 선택기에서 읽기 전용으로 열리므로, [관리 설정](https://claude.ai/admin-settings)의 **클라우드 환경** 페이지에서 소유자에게 네트워크 액세스를 변경하도록 요청합니다.1990이러한 단계는 자신의 환경 중 하나를 변경합니다. [조직 공유 환경](/docs/ko/cloud-environments#organization-shared-environments)은 선택기에서 읽기 전용으로 열리므로, [관리자 설정](https://claude.ai/admin-settings)의 **클라우드 환경** 페이지에서 Owner에게 네트워크 액세스를 변경하도록 요청합니다.

1981 1991

1982* 루틴을 편집하기 위해 열거나 클라우드 세션을 시작합니다. 환경의 이름(예: **기본**)을 표시하는 클라우드 아이콘을 선택하여 선택기를 엽니다. 환경 위에 마우스를 올리고 설정 아이콘을 클릭합니다.1992* [루틴의 양식](/docs/ko/routines#environments-and-network-access) 또는 클라우드 세션을 시작하는 [환경 선택기](/docs/ko/cloud-environments#configure-your-environment)에서 환경을 편집용으로 엽니다.

1983* **클라우드 환경 업데이트** 대화 상자에서 **네트워크 액세스**를 **신뢰할 수 있는**에서 **사용자 정의**로 변경한 다음 차단된 도메인을 **허용된 도메인**에 추가합니다. 한 줄에 하나의 도메인을 입력합니다. **또한 일반적인 패키지 관리자의 기본 목록 포함**을 확인하여 사용자 정의 도메인과 함께 [기본 허용 목록](/docs/ko/cloud-environments#default-allowed-domains)을 유지합니다. 제한 없는 액세스를 원하는 경우 대신 **전체**를 선택합니다.1993* **클라우드 환경 편집** 대화 상자에서 **네트워크 액세스**를 **신뢰할 수 있는**에서 **사용자 정의**로 변경한 다음 차단된 도메인을 **허용된 도메인**에 추가합니다. 한 줄에 하나의 도메인을 입력합니다. **또한 일반적인 패키지 관리자의 기본 목록 포함**을 확인하여 사용자 정의 도메인과 함께 [기본 허용 목록](/docs/ko/cloud-environments#default-allowed-domains)을 유지합니다. 제한 없는 액세스를 원하는 경우 대신 **전체**를 선택합니다.

1984* **변경 사항 저장**을 클릭합니다. 다음 실행은 업데이트된 허용 목록을 사용합니다. 이미 열려 있는 클라우드 세션의 경우, [네트워크 액세스 변경이 기존 세션에 도달할 때](/docs/ko/cloud-environments#network-access)를 참조합니다.1994* **변경 사항 저장**을 클릭합니다. 다음 실행은 업데이트된 허용 목록을 사용합니다. 이미 열려 있는 클라우드 세션의 경우, [네트워크 액세스 변경이 기존 세션에 도달할 때](/docs/ko/cloud-environments#network-access)를 참조합니다.

1985 1995

1986액세스 수준 및 기본 허용 목록은 [네트워크 액세스](/docs/ko/cloud-environments#network-access)를 참조합니다. 로컬 CLI 세션은 이 정책의 영향을 받지 않습니다.1996액세스 수준 및 기본 허용 목록은 [네트워크 액세스](/docs/ko/cloud-environments#network-access)를 참조합니다. 로컬 CLI 세션은 이 정책의 영향을 받지 않습니다.

2023The cloud environments service returned a response in an unexpected format (HTTP 200 without a usable environments list). This is usually temporary — try again in a moment.2033The cloud environments service returned a response in an unexpected format (HTTP 200 without a usable environments list). This is usually temporary — try again in a moment.

2024```2034```

2025 2035

2026서버는 요청을 수락했지만 환경 목록이 아닌 본문으로 응답했습니다: 비어 있음, JSON이 아님, 또는 목록이 없는 JSON. 이는 일반적으로 서비스 측 중단을 동반하며 자체적으로 해결됩니다. 목록을 요청한 표면에 따라 Claude Code는 `/remote-env` 대화 상자에서 `couldn't list environments:`와 같은 접두사를 추가할 수 있습니다.2036서버는 요청을 수락했지만 환경 목록이 아닌 본문으로 응답했습니다: 비어 있음, JSON이 아님, 또는 목록이 없는 JSON. 이는 일반적으로 서비스 측 중단을 동반하며 자체적으로 해결됩니다. 목록을 요청한 사용 환경에 따라 Claude Code는 `/remote-env` 대화 상자에서 `couldn't list environments:`와 같은 접두사를 추가할 수 있습니다.

2027 2037

2028**수행할 작업:**2038**수행할 작업:**

2029 2039

2062 2072

2063**수행할 작업:**2073**수행할 작업:**

2064 2074

2065* Claude Code가 이 메시지 아래에 유지된 worktree를 나열할 때 이들에서 커밋되지 않은 작업을 선택합니다.2075* Claude Code가 이 메시지 아래에 유지된 worktree를 나열할 때 이들에서 커밋되지 않은 작업을 가져옵니다.

2066* `claude remote-control`을 실행하여 새로운 환경을 시작합니다.2076* `claude remote-control`을 실행하여 새로운 환경을 시작합니다.

2067 2077

2068<h3 id="couldnt-share-the-transcript">2078<h3 id="couldnt-share-the-transcript">

2075Couldn't share the transcript.2085Couldn't share the transcript.

2076```2086```

2077 2087

2078업로드는 8 MiB 제한에 맞아야 합니다. 긴 세션에서 Claude Code는 점진적으로 공유의 일부를 삭제합니다. 마지막 요청의 모델 설정이 먼저, 그 다음 구조화된 대화 및 서브에이전트 트랜스크립트이며, 축소된 버전을 보낼 수 없거나 네트워크 또는 서버 오류가 업로드를 중지할 때만 이 메시지를 표시합니다. Claude Code가 로컬 아카이브를 대신 저장할 때, 메시지는 아카이브를 쓸 수 없었음을 의미합니다.2088업로드는 8 MiB 제한에 맞아야 합니다. 긴 세션에서 Claude Code는 점진적으로 공유의 일부를 삭제합니다. 마지막 요청의 모델 설정이 먼저, 그 다음 구조화된 대화 및 서브에이전트 트랜스크립트이며, 축소된 버전을 보낼 수 없거나 네트워크 또는 서버 오류가 업로드를 중지할 때 이 메시지를 표시합니다. Claude Code가 로컬 아카이브를 대신 저장할 때, 메시지는 아카이브를 쓸 수 없었음을 의미합니다.

2079 2089

2080**수행할 작업:**2090**수행할 작업:**

2081 2091

2101 2111

2102**수행할 작업:**2112**수행할 작업:**

2103 2113

2104* 서명되지 않은 표현의 경우, `/login`을 실행하고 다시 보냅니다.2114* 로그인되지 않았다는 문구의 경우, `/login`을 실행하고 다시 보냅니다.

2105* 그 외의 경우, 다시 보냅니다. 다른 요청도 실패하는 경우, 네트워크 연결을 확인하고 [API에 연결할 수 없음](#unable-to-connect-to-api)을 참조합니다.2115* 그 외의 경우, 다시 보냅니다. 다른 요청도 실패하는 경우, 네트워크 연결을 확인하고 [API에 연결할 수 없음](#unable-to-connect-to-api)을 참조합니다.

2106* 계속 실패하면 메시지가 말하는 대로 [github.com/anthropics/claude-code/issues](https://github.com/anthropics/claude-code/issues)에서 보고서를 제출합니다.2116* 계속 실패하면 메시지가 말하는 대로 [github.com/anthropics/claude-code/issues](https://github.com/anthropics/claude-code/issues)에서 보고서를 제출합니다.

2107 2117

2847 명령줄 오류2857 명령줄 오류

2848</h2>2858</h2>

2849 2859

2850이러한 오류는 `claude` 명령줄과 그 하위 명령어, 프롬프트에서 제출하는 명령어 이름, 그리고 셸 명령어를 실행하여 컨텍스트를 수집한 후 프롬프트를 실행하는 `/security-review` 같은 명령어에서 발생합니다. 또한 CLI를 다시 시작하는 `/tui`에서도 발생합니다.2860이러한 오류는 `claude` 명령줄과 그 하위 명령, 프롬프트에서 제출하는 명령 이름, 그리고 `/security-review`처럼 프롬프트가 실행되기 전에 셸 명령을 실행하여 컨텍스트를 수집하는 명령에서 발생합니다. CLI를 다시 시작하는 `/tui`에서도 발생합니다.

2851 2861

2852<h3 id="conflict-between-bg-and-print">2862<h3 id="conflict-between-bg-and-print">

2853 \--bg와 --print 간의 충돌2863 `--bg`와 `--print` 간 충돌

2854</h3>2864</h3>

2855 2865

2856이 메시지는 Claude Code v2.1.198 이상이 필요합니다. 동일한 `claude` 호출에서 `--bg`를 `-p` 또는 `--print`와 결합했습니다. `--bg`는 나중에 `claude agents`로 연결할 수 있는 [백그라운드 세션](/docs/ko/agent-view#from-your-shell)을 시작하는 반면, `--print`는 [비대화형](/docs/ko/headless)으로 실행되며 `claude agents`가 연결할 수 있는 대화형 세션을 시작하지 않습니다. v2.1.198 이전에는 이 조합이 연결할 수 없는 백그라운드 작업을 자동으로 생성했습니다.2866이 메시지는 Claude Code v2.1.198 이상이 필요합니다. 같은 `claude` 호출에서 `--bg`를 `-p` 또는 `--print`와 함께 사용한 경우입니다. `--bg`는 나중에 `claude agents`로 연결하는 [백그라운드 세션](/docs/ko/agent-view#from-your-shell)을 시작하는 반면, `--print`는 [비대화형](/docs/ko/headless)으로 실행되며 `claude agents`가 연결하는 대화형 세션을 시작하지 않습니다. v2.1.198 이전에는 이 조합이 아무 메시지 없이 연결할 수 없는 백그라운드 작업을 생성했습니다.

2857 2867

2858```text theme={null}2868```text theme={null}

2859--bg and --print conflict: --print never starts the interactive session that `claude agents` attaches to, so the job would be unattachable. The prompt is the positional — drop --print: `claude --bg '<task>'`.2869--bg and --print conflict: --print never starts the interactive session that `claude agents` attaches to, so the job would be unattachable. The prompt is the positional — drop --print: `claude --bg '<task>'`.

2860```2870```

2861 2871

2862**해야 할 일:**2872**조치 방법:**

2863 2873

2864* `-p` 또는 `--print`를 제거합니다. `--bg`는 프롬프트를 위치 인수로 사용하므로 `claude --bg "<task>"`가 완전한 명령어입니다. [셸에서 새 에이전트 디스패치](/docs/ko/agent-view#from-your-shell)를 참조하세요.2874* `-p` 또는 `--print`를 제거합니다. `--bg`는 프롬프트를 위치 인수로 받으므로 `claude --bg "<task>"`만으로 완전한 명령이 됩니다. [셸에서 새 에이전트 디스패치하기](/docs/ko/agent-view#from-your-shell)를 참조하세요.

2865* 프롬프트를 비대화형으로 실행하고 백그라운드 세션을 만드는 대신 결과를 출력하려면 `--bg`를 제거하고 `claude -p "<task>"`를 실행합니다.2875* 백그라운드 세션을 만드는 대신 프롬프트를 비대화형으로 실행하고 결과를 출력하려면 `--bg`를 제거하고 `claude -p "<task>"`를 실행합니다

2876

2877<h3 id="conflict-between-a-system-prompt-flag-and-its-file-form">

2878 시스템 프롬프트 플래그와 해당 파일 형식 간 충돌

2879</h3>

2880

2881하나의 `claude` 호출에서 [`--append-subagent-system-prompt`](/docs/ko/cli-reference#cli-flags)를 `--append-subagent-system-prompt-file`과 함께 전달했기 때문에 `claude`가 세션을 시작하지 않고 코드 1로 종료됩니다:

2882

2883```text theme={null}

2884Error: Cannot use both --append-subagent-system-prompt and --append-subagent-system-prompt-file. Please use only one.

2885```

2886

2887v2.1.283 이전에는 `--system-prompt`를 `--system-prompt-file`과 함께, 또는 `--append-system-prompt`를 `--append-system-prompt-file`과 함께 전달했을 때도 `claude`가 같은 방식으로 종료되었습니다. 이 쌍들이 [결합](/docs/ko/cli-reference#system-prompt-flags)되지 않고 충돌했기 때문입니다. 해당 버전에서는 메시지에 함께 사용한 쌍이 표시됩니다.

2888

2889**조치 방법:**

2890

2891* 플래그의 한 가지 형식만 유지하고 다른 하나는 제거합니다. 고정된 프롬프트 파일과 실행별 텍스트를 결합하려면 두 플래그를 모두 전달하는 대신 실행 전에 텍스트를 파일에 병합합니다

2866 2892

2867<h3 id="invalid-agents-configuration">2893<h3 id="invalid-agents-configuration">

2868 잘못된 --agents 구성2894 잘못된 `--agents` 구성

2869</h3>2895</h3>

2870 2896

2871`--agents`에 전달한 값이 유효하지 않아서 `claude`가 세션을 시작하는 대신 코드 1로 종료됩니다. `--safe-mode`를 전달하거나 [`CLAUDE_CODE_SAFE_MODE`](/docs/ko/env-vars#variables)를 설정하면 Claude Code는 `--agents`를 완전히 무시합니다. `--resume` 또는 `--continue`를 사용하면 인라인 JSON 값은 확인되지 않고 세션이 시작됩니다. 파일에서 읽은 값은 매번 시작할 때 확인됩니다. v2.1.242 이전에는 Claude Code가 어쨌든 세션을 시작했습니다.2897`--agents`에 전달한 값이 유효하지 않으므로 `claude`가 세션을 시작하지 않고 코드 1로 종료됩니다. `--safe-mode`를 전달하거나 [`CLAUDE_CODE_SAFE_MODE`](/docs/ko/env-vars#variables)를 설정하면 Claude Code는 `--agents`를 완전히 무시합니다. `--resume` 또는 `--continue`를 사용하면 인라인 JSON 값은 검사되지 않고 세션이 시작되며, 파일에서 읽은 값은 실행할 때마다 검사됩니다. v2.1.242 이전에는 Claude Code가 그대로 세션을 시작했습니다.

2872 2898

2873```text theme={null}2899```text theme={null}

2874Error: Invalid --agents configuration:2900Error: Invalid --agents configuration:

2875<what failed>2901<what failed>

2876```2902```

2877 2903

2878첫 번째 줄 다음에 오는 내용은 값이 어떻게 실패했는지에 따라 달라집니다. Claude Code는 이러한 확인을 순서대로 실행하고 실패하는 첫 번째 확인에서 중지합니다. 값에 두 가지 문제가 있으면 첫 번째를 수정한 후에만 두 번째를 볼 수 있습니다:2904첫 번째 줄 다음에 오는 내용은 값이 어떻게 실패했는지에 따라 달라집니다. Claude Code는 다음 검사를 순서대로 실행하며 처음 실패하는 검사에서 중단합니다. 값에 두 종류의 문제가 있으면 첫 번째 문제를 수정한 후에야 두 번째 문제가 표시됩니다:

2879 2905

28801. 값이 `{`로 시작하지만 JSON으로 파싱되지 않거나 `--agents` 파일의 내용이 파싱되지 않으면 Claude Code는 JSON 파서의 메시지를 포함하는 `invalid JSON:` 줄 하나를 출력합니다.29061. 값이 `{`로 시작하지만 JSON으로 파싱되지 않거나 `--agents` 파일의 내용이 파싱되지 않으면, Claude Code는 JSON 파서 자체의 메시지를 담은 `invalid JSON:` 줄 하나를 출력합니다

28812. 파싱되지만 에이전트 정의가 [CLI 정의 하위 에이전트](/docs/ko/sub-agents#choose-the-subagent-scope)의 스키마와 일치하지 않으면 Claude Code는 문제당 한 줄을 출력합니다.29072. 파싱은 되지만 에이전트 정의가 [CLI에서 정의한 서브에이전트](/docs/ko/sub-agents#choose-the-subagent-scope)의 스키마와 일치하지 않으면, Claude Code는 문제마다 한 줄씩 출력합니다

28823. 에이전트 이름이 `-`로 시작하면 Claude Code는 `<name>: agent names must not start with '-'`를 출력합니다.29083. 에이전트 이름이 `-`로 시작하면 Claude Code는 `<name>: agent names must not start with '-'`를 출력합니다

2883 2909

2884문제 줄이 20개를 초과하면 Claude Code는 처음 20개를 출력하고 나머지를 `…and N more`로 바꿉니다.2910문제 줄이 20개를 넘으면 Claude Code는 처음 20개를 출력하고 나머지는 `…and N more`로 대체합니다.

2885 2911

2886`--print`를 사용하면 `--agents`는 인라인 객체 대신 [JSON 파일의 경로](/docs/ko/sub-agents#choose-the-subagent-scope)도 허용합니다. v2.1.281 이전에는 `--agents`가 인라인 JSON만 허용했고 파일 경로를 유효하지 않은 JSON으로 취급했습니다. 파일 형식에는 이 메시지 대신 출력되는 자체 거부가 있습니다:2912`--print`와 함께 사용하면 `--agents`는 인라인 객체 대신 [JSON 파일 경로](/docs/ko/sub-agents#choose-the-subagent-scope)도 받습니다. v2.1.281 이전에는 `--agents`가 인라인 JSON만 받았으며 파일 경로를 잘못된 JSON으로 처리했습니다. 파일 형식에는 자체적인 거부 메시지가 있으며, 이 메시지 대신 출력됩니다. 다음은 그 예입니다:

2887 2913

2888* **`Error: --agents takes a JSON object, or a file path only with --print (-p)`**: Claude Code가 대화형 세션에서 값을 파일 경로로 읽었습니다. 정의를 인라인 JSON으로 전달하거나 `-p`를 추가하여 파일에서 읽습니다.2914* **`Error: --agents takes a JSON object, or a file path only with --print (-p)`**: Claude Code가 대화형 세션에서 값을 파일 경로로 읽었습니다. 정의를 인라인 JSON으로 전달하거나, `-p`를 추가하여 파일에서 읽도록 합니다.

2889* **`Error: --agents file not found: <path>`**: 해당 경로에 파일이 없습니다. `{`로 시작하지 않고 유효한 JSON이 아닌 값은 경로로 읽혀지므로 셸이 손상시킨 인라인 JSON도 이런 식으로 실패할 수 있습니다. 경로 또는 인용을 확인하고 명령어를 다시 실행합니다.2915* **`Error: --agents file not found: <path>`**: 해당 경로에 파일이 없습니다. `{`로 시작하지 않고 유효한 JSON도 아닌 값은 경로로 읽히므로, 셸이 망가뜨린 인라인 JSON도 이런 방식으로 실패할 수 있습니다. 경로나 따옴표 처리를 확인한 후 명령을 다시 실행합니다.

2890 2916

2891**해야 할 일:**2917**조치 방법:**

2892 2918

2893* 메시지가 나열한 각 문제를 수정한 후 명령어를 다시 실행합니다. [CLI 정의 하위 에이전트가 사용하는 필드](/docs/ko/sub-agents#choose-the-subagent-scope)를 참조하세요.2919* 메시지에 나열된 각 문제를 수정한 후 명령을 다시 실행합니다. [CLI에서 정의한 서브에이전트가 받는 필드](/docs/ko/sub-agents#choose-the-subagent-scope)를 참조하세요.

2894 2920

2895<h3 id="cloud-sessions-cannot-be-created-from-a-restricted-session">2921<h3 id="cloud-sessions-cannot-be-created-from-a-restricted-session">

2896 클라우드 세션을 --restricted 세션에서 만들 수 없음2922 `--restricted` 세션에서는 클라우드 세션을 만들 수 없음

2897</h3>2923</h3>

2898 2924

2899[`--restricted`](/docs/ko/cli-reference#cli-flags)로 세션을 시작하면 Claude Code는 이 세션에서 [클라우드 세션](/docs/ko/claude-code-on-the-web#from-terminal-to-cloud)을 만드는 것을 거부합니다. 새 세션이 제한된 프로세스 외부에서 실행되고 제한된 모드를 적용하지 않기 때문입니다. Claude Code는 서버에 연결하기 전에 클라이언트에서 거부하므로 클라우드 세션이 생성되지 않습니다:2925[`--restricted`](/docs/ko/cli-reference#cli-flags)로 세션을 시작하면 Claude Code는 해당 세션에서 [클라우드 세션](/docs/ko/claude-code-on-the-web#from-terminal-to-cloud)을 만드는 것을 거부합니다. 새 세션이 제한된 프로세스 밖에서 실행되어 제한 모드를 적용하지 않기 때문입니다. Claude Code는 서버에 연결하기 전에 클라이언트에서 거부하므로 클라우드 세션이 생성되지 않습니다:

2900 2926

2901```text theme={null}2927```text theme={null}

2902Cloud sessions cannot be created from a --restricted session: they would not enforce it.2928Cloud sessions cannot be created from a --restricted session: they would not enforce it.

2903```2929```

2904 2930

2905**해야 할 일:**2931**조치 방법:**

2906 2932

2907* 제한된 세션에서 로컬로 작업을 실행합니다.2933* 제한된 세션에서 작업을 로컬로 실행합니다

2908* 세션이 어떻게 시작되었는지 제어할 수 있으면 `--restricted` 없이 새 `claude` 세션을 시작하고 거기서 클라우드 세션을 만듭니다.2934* 세션이 시작되는 방식을 제어할 수 있다면 `--restricted` 없이 새 `claude` 세션을 시작하고 그곳에서 클라우드 세션을 만듭니다

2909 2935

2910v2.1.248 이전에는 Claude Code에 `--restricted` 플래그가 없었고 이전 버전은 알 수 없는 옵션 오류로 플래그 자체를 거부했습니다.2936v2.1.248 이전에는 Claude Code에 `--restricted` 플래그가 없었으며, 이전 버전은 알 수 없는 옵션 오류로 플래그 자체를 거부합니다.

2911 2937

2912<h3 id="cloud-sessions-are-disabled-by-your-organizations-policy">2938<h3 id="cloud-sessions-are-disabled-by-your-organizations-policy">

2913 조직의 정책에 의해 클라우드 세션이 비활성화됨2939 조직 정책에 의해 클라우드 세션이 비활성화됨

2914</h3>2940</h3>

2915 2941

2916조직의 `allow_remote_sessions` 정책이 꺼져 있어서 [클라우드 세션](/docs/ko/claude-code-on-the-web)과 이를 사용하는 명령어를 사용할 수 없습니다:2942조직의 `allow_remote_sessions` 정책이 꺼져 있으므로 [클라우드 세션](/docs/ko/claude-code-on-the-web)과 이를 사용하는 명령을 사용할 수 없습니다:

2917 2943

2918```text theme={null}2944```text theme={null}

2919Cloud sessions are disabled by your organization's policy. Contact your organization admin to enable them.2945Cloud sessions are disabled by your organization's policy. Contact your organization admin to enable them.

2920```2946```

2921 2947

2922메시지는 [터미널에서 클라우드 세션을 만들](/docs/ko/claude-code-on-the-web#from-terminal-to-cloud) 때 나타나고 `/teleport`, `/remote-env`, 또는 `/web-setup` 같은 클라우드 세션이 필요한 명령어를 제출할 때 나타납니다. v2.1.268 이전에는 이러한 명령어 중 하나를 제출하면 대신 [`Unknown command`](#unknown-command)를 반환했습니다.2948이 메시지는 [터미널에서 클라우드 세션을 만들 때](/docs/ko/claude-code-on-the-web#from-terminal-to-cloud)와 `/teleport`, `/remote-env`, `/web-setup`처럼 클라우드 세션이 필요한 명령을 제출할 때 나타납니다. v2.1.268 이전에는 이러한 명령 중 하나를 제출하면 대신 [`Unknown command`](#unknown-command)가 반환되었습니다.

2923 2949

2924이것은 서버 측 조직 정책이므로 로컬 설정, 환경 변수 또는 CLI 플래그에서 재정의할 수 없습니다.2950이는 서버 측 조직 정책이므로 로컬 설정, 환경 변수 또는 CLI 플래그로 재정의할 수 없습니다.

2925 2951

2926Claude Code가 조직의 정책을 아직 로드하지 않았거나 가져올 수 없으면 이러한 명령어는 대신 `Couldn't verify your organization's policy for cloud sessions. Check your network connection, then restart Claude Code and try again.`으로 응답합니다.2952Claude Code가 아직 조직의 정책을 로드하지 않았거나 가져올 수 없는 경우, 해당 명령은 대신 `Couldn't verify your organization's policy for cloud sessions. Check your network connection, then restart Claude Code and try again.`으로 응답합니다.

2927 2953

2928**해야 할 일:**2954**조치 방법:**

2929 2955

2930* 조직의 [Owner](/docs/ko/server-managed-settings#access-control)에게 [claude.ai/admin-settings/claude-code](https://claude.ai/admin-settings/claude-code)의 Claude Code 관리자 설정에서 클라우드 세션을 활성화하도록 요청합니다.2956* 조직의 [Owner](/docs/ko/server-managed-settings#access-control)에게 [claude.ai/admin-settings/claude-code](https://claude.ai/admin-settings/claude-code)의 Claude Code 관리자 설정에서 클라우드 세션을 활성화하도록 요청합니다

2931* 메시지에서 정책을 확인할 수 없다고 하면 네트워크 연결을 확인한 후 Claude Code를 다시 시작하고 다시 시도합니다.2957* 메시지에 정책을 확인할 수 없다고 표시되면 네트워크 연결을 확인한 후 Claude Code를 다시 시작하고 다시 시도합니다

2932 2958

2933<h3 id="the-json-schema-value-is-not-a-valid-json-schema">2959<h3 id="the-json-schema-value-is-not-a-valid-json-schema">

2934 \--json-schema 값이 유효한 JSON Schema가 아님2960 `--json-schema` 값이 유효한 JSON Schema가 아님

2935</h3>2961</h3>

2936 2962

2937[비대화형 모드](/docs/ko/headless#get-structured-output)에서 [`--json-schema`](/docs/ko/cli-reference#cli-flags)에 전달한 스키마가 JSON Schema 컴파일에 실패했으므로 `claude`가 프롬프트를 실행하는 대신 코드 1로 종료됩니다. v2.1.205 이전에는 유효하지 않은 스키마가 오류 없이 구조화되지 않은 출력을 생성했고 `format` 키워드를 사용하는 모든 스키마는 유효하지 않은 것으로 처리되었습니다.2963[비대화형 모드](/docs/ko/headless#get-structured-output)에서 [`--json-schema`](/docs/ko/cli-reference#cli-flags)에 전달한 스키마가 JSON Schema 컴파일에 실패했으므로 `claude`가 프롬프트를 실행하지 않고 코드 1로 종료됩니다. v2.1.205 이전에는 잘못된 스키마가 오류 없이 구조화되지 않은 출력을 생성했으며, `format` 키워드를 사용하는 모든 스키마가 유효하지 않은 것으로 처리되었습니다.

2938 2964

2939```text theme={null}2965```text theme={null}

2940Error: --json-schema is not a valid JSON Schema: data/type must be equal to one of the allowed values2966Error: --json-schema is not a valid JSON Schema: data/type must be equal to one of the allowed values

2941```2967```

2942 2968

2943두 번째 콜론 뒤의 텍스트는 검증자의 진단이며 실패한 키워드 또는 위치를 이름 지정합니다. `"format": "email"` 같은 `format` 키워드를 사용하는 스키마는 유효합니다: Claude Code는 `format`을 주석으로 허용하고 적용하지 않습니다.2969두 번째 콜론 뒤의 텍스트는 검증기의 진단 메시지이며 실패한 키워드나 위치를 나타냅니다. `"format": "email"`처럼 `format` 키워드를 사용하는 스키마는 유효합니다. Claude Code는 `format`을 주석으로 받아들이며 이를 강제하지 않습니다.

2944 2970

2945Claude Code는 스키마 컴파일 전에 두 가지 확인을 실행합니다: 파싱할 수 없는 JSON 값을 `Error: --json-schema is not valid JSON`으로 거부하고 유효한 JSON이지만 객체가 아닌 것을 `Error: --json-schema must be a JSON object`로 거부합니다.2971Claude Code는 스키마 컴파일 전에 두 가지 검사를 실행합니다. 파싱할 수 없는 JSON 값은 `Error: --json-schema is not valid JSON`으로 거부하고, 객체가 아닌 유효한 JSON은 `Error: --json-schema must be a JSON object`로 거부합니다.

2946 2972

2947**해야 할 일:**2973**조치 방법:**

2948 2974

2949* 진단이 이름 지정한 스키마 부분을 수정한 후 명령어를 다시 실행합니다.2975* 진단 메시지가 가리키는 스키마 부분을 수정한 후 명령을 다시 실행합니다

2950* [구조화된 출력 가져오기](/docs/ko/headless#get-structured-output)에서 작동하는 스키마와 명령어를 참조하세요.2976* 작동하는 스키마와 명령은 [구조화된 출력 얻기](/docs/ko/headless#get-structured-output)를 참조하세요

2951 2977

2952<h3 id="settings-file-exceeds-the-2mib-limit">2978<h3 id="settings-file-exceeds-the-2mib-limit">

2953 설정 파일이 2MiB 제한을 초과함2979 설정 파일이 2MiB 제한을 초과함

2954</h3>2980</h3>

2955 2981

2956[`--settings`](/docs/ko/cli-reference#cli-flags)에 전달한 파일이 2MiB보다 크므로 `claude`가 시작 시 코드 1로 종료되고 로드하지 않습니다. v2.1.214 이전에는 Claude Code가 크기 확인 없이 파일을 읽었고 수 기가바이트 파일이나 `/dev/zero` 같은 장치 파일이 메모리를 무한정 증가시켰습니다.2982[`--settings`](/docs/ko/cli-reference#cli-flags)에 전달한 파일이 2MiB보다 크므로 `claude`가 파일을 로드하지 않고 시작 시 코드 1로 종료됩니다. v2.1.214 이전에는 Claude Code가 크기 검사 없이 파일을 읽었으며, 수 기가바이트 크기의 파일이나 `/dev/zero` 같은 장치 파일로 인해 메모리가 무한정 증가했습니다.

2957 2983

2958```text theme={null}2984```text theme={null}

2959Error: Settings file exceeds the 2MiB limit: /path/to/settings.json2985Error: Settings file exceeds the 2MiB limit: /path/to/settings.json

2960```2986```

2961 2987

2962Claude Code는 일반 파일이 아닌 `--settings` 경로를 같은 방식으로 거부합니다: 장치, FIFO 또는 소켓은 `Error: Cannot use settings file (Not a regular file (device, FIFO, or socket))`을 보고하고 경로를 따르며 디렉토리는 `EISDIR` 이유를 보고합니다.2988Claude Code는 일반 파일이 아닌 `--settings` 경로도 같은 방식으로 거부합니다. 장치, FIFO 또는 소켓은 `Error: Cannot use settings file (Not a regular file (device, FIFO, or socket))`과 함께 경로를 보고하며, 디렉터리는 `EISDIR` 사유를 보고합니다.

2963 2989

2964**해야 할 일:**2990**조치 방법:**

2965 2991

2966* `--settings`를 2MiB 미만의 일반 JSON 설정 파일로 지정합니다. 형식은 [설정](/docs/ko/settings)을 참조하세요.2992* `--settings`가 2MiB 미만의 일반 JSON 설정 파일을 가리키도록 합니다. 형식은 [설정](/docs/ko/settings)을 참조하세요.

2967 2993

2968<h3 id="the-current-directory-no-longer-exists">2994<h3 id="the-current-directory-no-longer-exists">

2969 현재 디렉토리가 더 이상 존재하지 않음2995 현재 디렉터리가 더 이상 존재하지 않음

2970</h3>2996</h3>

2971 2997

2972셸이 디렉토리에 들어간 후 삭제되거나 이동된 디렉토리에서 `claude`를 시작했습니다. 예를 들어 다른 셸이 제거한 worktree 또는 임시 디렉토리입니다. Claude Code가 작업 디렉토리를 읽을 수 없으므로 대화형 및 [비대화형](/docs/ko/headless) 모드 모두에서 세션을 시작하기 전에 코드 1로 종료됩니다. v2.1.239 이전에는 Claude Code가 축소된 번들 소스와 stderr의 원시 `ENOENT ... uv_cwd` 스택으로 충돌했습니다.2998셸이 진입한 후 삭제되거나 이동된 디렉터리에서 `claude`를 시작한 경우입니다. 예를 들어 다른 셸이 제거한 worktree나 임시 디렉터리가 이에 해당합니다. Claude Code가 작업 디렉터리를 읽을 수 없으므로 대화형 모드와 [비대화형](/docs/ko/headless) 모드 모두에서 세션을 시작하기 전에 코드 1로 종료됩니다. v2.1.239 이전에는 이 메시지 대신 Claude Code가 축소된 번들 소스와 원시 `ENOENT ... uv_cwd` 스택을 stderr에 출력하며 충돌했습니다.

2973 2999

2974```text theme={null}3000```text theme={null}

2975The current directory no longer exists (it was deleted or moved). Start Claude Code from an existing directory.3001The current directory no longer exists (it was deleted or moved). Start Claude Code from an existing directory.

2976error: The current working directory was deleted, so that command didn't work. Please cd into a different directory and try again.3002error: The current working directory was deleted, so that command didn't work. Please cd into a different directory and try again.

2977```3003```

2978 3004

2979원인과 해결책은 두 형식 모두 동일합니다.3005두 형식 모두 원인과 해결 방법은 같습니다.

2980 3006

2981Claude Code가 권한 변경 같은 다른 이유로 작업 디렉토리를 읽을 수 없으면 메시지는 오류 코드를 이름 지정합니다: `Can't read the current directory (EACCES). Start Claude Code from a different directory.`3007권한 변경처럼 다른 이유로 Claude Code가 작업 디렉터리를 읽을 수 없는 경우, 메시지에는 대신 오류 코드가 표시됩니다: `Can't read the current directory (EACCES). Start Claude Code from a different directory.`

2982 3008

2983macOS에서 `~/Desktop`, `~/Documents`, `~/Downloads` 또는 iCloud Drive의 디렉토리에 대한 `EPERM`은 보통 macOS가 터미널 앱을 해당 폴더에서 차단하고 있다는 의미입니다. 해당 폴더를 읽는 다른 명령어도 같은 방식으로 실패합니다: `ls`는 `sudo`를 사용해도 `Operation not permitted`를 보고합니다.3009macOS에서 `~/Desktop`, `~/Documents`, `~/Downloads` 또는 iCloud Drive에 있는 디렉터리에 대해 `EPERM`이 발생하면 일반적으로 macOS가 터미널 앱의 해당 폴더 접근을 차단하고 있다는 의미입니다. 해당 폴더를 읽는 다른 명령도 같은 방식으로 실패합니다. 그곳에서 `ls`를 실행하면 `sudo`를 사용하더라도 `Operation not permitted`가 보고됩니다.

2984 3010

2985**해야 할 일:**3011**조치 방법:**

2986 3012

2987* 홈 또는 프로젝트 디렉토리 같은 존재하는 디렉토리로 변경한 후 `claude`를 다시 실행합니다.3013* 홈 디렉터리나 프로젝트 디렉터리처럼 존재하는 디렉터리로 이동한 후 `claude`를 다시 실행합니다

2988* 디렉토리가 같은 경로에서 다시 생성되었으면 셸이 여전히 삭제된 것을 보유합니다. `cd "$PWD"`를 실행하거나 디렉토리를 나갔다가 다시 들어간 후 `claude`를 다시 실행합니다.3014* 디렉터리가 같은 경로에 다시 생성된 경우 셸은 여전히 삭제된 디렉터리를 가리키고 있습니다. `cd "$PWD"`를 실행하거나 디렉터리에서 나갔다가 다시 들어간 후 `claude`를 다시 실행합니다

2989* macOS의 `EPERM`의 경우 Cmd+Q로 터미널 앱을 종료하고 다시 열고 해당 폴더로 돌아가 `claude`를 실행합니다. 해당 폴더의 `ls`가 여전히 실패하면 **System Settings > Privacy & Security > Files and Folders**를 열고 터미널 앱에 대한 폴더를 켠 후 터미널을 다시 엽니다.3015* macOS에서 `EPERM`이 발생하면 Cmd+Q로 터미널 앱을 종료하고 다시 연 후 해당 폴더로 돌아가 `claude`를 실행합니다. 해당 폴더에서 `ls`가 여전히 실패하면 **시스템 설정 > 개인정보 보호 및 보안 > 파일 및 폴더**를 열고 터미널 앱에 대해 해당 폴더를 켠 다음 터미널을 다시 엽니다

2990 3016

2991<h3 id="temp-directory-refused-or-cannot-be-created">3017<h3 id="temp-directory-refused-or-cannot-be-created">

2992 임시 디렉토리가 거부되었거나 만들 수 없음3018 임시 디렉터리가 거부되었거나 생성할 수 없음

2993</h3>3019</h3>

2994 3020

2995macOS 및 Linux에서 Claude Code는 시작 시 시스템 임시 디렉토리 또는 [`CLAUDE_CODE_TMPDIR`](/docs/ko/env-vars) 재정의 아래에 `claude-<uid>` 개인 임시 디렉토리를 만듭니다. 디렉토리를 만들 수 없거나 해당 경로의 항목이 안전 확인에 실패하면 Claude Code는 세션을 시작하는 대신 실패를 stderr에 출력하고 코드 1로 종료됩니다:3021macOS와 Linux에서 Claude Code는 시작 시 시스템 임시 디렉터리 또는 [`CLAUDE_CODE_TMPDIR`](/docs/ko/env-vars) 재정의 위치 아래에 `claude-<uid>`라는 전용 임시 디렉터리를 만듭니다. 디렉터리를 만들 수 없거나 해당 경로에 이미 있는 항목이 안전 검사를 통과하지 못하면, Claude Code는 세션을 시작하지 않고 실패 내용을 stderr에 출력한 후 코드 1로 종료합니다:

2996 3022

2997```text wrap theme={null}3023```text wrap theme={null}

2998ENOSPC: no space left on device, mkdir '/tmp/claude-501'3024ENOSPC: no space left on device, mkdir '/tmp/claude-501'

3004Temp directory /tmp/claude-501 is not readable (its mode may have been altered, or a path component denies search). Refusing to use it — restore its permissions (chmod 0700) or remove it. Set CLAUDE_CODE_TMPDIR to a directory you control, or ask an administrator to remove it.3030Temp directory /tmp/claude-501 is not readable (its mode may have been altered, or a path component denies search). Refusing to use it — restore its permissions (chmod 0700) or remove it. Set CLAUDE_CODE_TMPDIR to a directory you control, or ask an administrator to remove it.

3005```3031```

3006 3032

3007**해야 할 일:**3033**조치 방법:**

3008 3034

3009* `ENOSPC`의 경우 임시 디렉토리를 보유하는 볼륨의 디스크 공간을 확보합니다.3035* `ENOSPC`의 경우 임시 디렉터리가 있는 볼륨의 디스크 공간을 확보합니다

3010* `Refusing to use it` 형식의 경우 링크가 가리키는 것이 아니라 이름 지정된 항목 자체를 제거하고 Claude Code를 다시 시작합니다. `owned by uid` 형식의 경우 관리자 또는 해당 사용자만 제거할 수 있습니다.3036* `Refusing to use it` 형식의 경우 링크가 가리키는 대상이 아니라 표시된 항목 자체를 제거하고 Claude Code를 다시 시작합니다. `owned by uid` 형식의 경우 관리자나 해당 사용자만 이를 제거할 수 있습니다

3011* `is not readable`의 경우 이름 지정된 디렉토리에서 `chmod 0700`을 실행하거나 제거하고 다시 시작합니다.3037* `is not readable`의 경우 표시된 디렉터리에 `chmod 0700`을 실행하거나, 디렉터리를 제거하고 다시 시작합니다

3012* 이러한 경우 중 하나에서 [`CLAUDE_CODE_TMPDIR`](/docs/ko/env-vars)을 제어하는 디렉토리로 설정하고 Claude Code를 시작하여 거부된 경로를 그대로 둡니다.3038* 이러한 모든 경우에 거부된 경로는 그대로 두고 [`CLAUDE_CODE_TMPDIR`](/docs/ko/env-vars)를 직접 제어하는 디렉터리로 설정한 후 Claude Code를 다시 시작할 수 있습니다

3013 3039

3014<h3 id="directory-couldnt-be-resolved-to-a-real-location">3040<h3 id="directory-couldnt-be-resolved-to-a-real-location">

3015 디렉토리를 실제 위치로 확인할 수 없음3041 디렉터리를 실제 위치로 확인할 수 없음

3016</h3>3042</h3>

3017 3043

3018작업 디렉토리의 하위 디렉토리에 대해 `/add-dir`을 실행했고 Claude Code가 디렉토리를 실제 위치로 확인할 수 없습니다.3044작업 디렉터리의 하위 디렉터리에 대해 `/add-dir`을 실행했지만 Claude Code가 디렉터리의 실제 위치를 확인할 수 없는 경우입니다.

3019 3045

3020작업 디렉토리의 하위 디렉토리에 이미 파일 액세스 권한이 있으므로 `/add-dir`은 해당 스킬, 명령어 및 에이전트만 로드합니다. 로드하기 전에 Claude Code는 심볼릭 링크가 확인된 디렉토리의 실제 위치가 작업 디렉토리 내부에 있는지 확인합니다. Claude Code가 해당 위치를 확인할 수 없으면 아무것도 로드하지 않고 이 메시지를 표시합니다:3046작업 디렉터리의 하위 디렉터리에는 이미 파일 접근 권한이 있으므로 `/add-dir`은 해당 디렉터리의 스킬, 명령, 에이전트만 로드합니다. 이를 로드하기 전에 Claude Code는 심볼릭 링크를 모두 확인한 디렉터리의 실제 위치가 작업 디렉터리 안에 있는지 검사합니다. Claude Code가 그 위치를 확인할 수 없으면 아무것도 로드하지 않고 다음 메시지를 표시합니다:

3021 3047

3022```text theme={null}3048```text theme={null}

3023packages/app couldn't be resolved to a real location, so its skills, commands, and agents weren't loaded. Check that it is a directory inside the working directory and try again.3049packages/app couldn't be resolved to a real location, so its skills, commands, and agents weren't loaded. Check that it is a directory inside the working directory and try again.

3024```3050```

3025 3051

3026**해야 할 일:**3052**조치 방법:**

3027 3053

3028* 경로가 작업 디렉토리 내부의 실제 디렉토리를 이름 지정하는지 확인한 후 `/add-dir`을 다시 실행합니다.3054* 경로가 작업 디렉터리 안의 실제 디렉터리를 가리키는지 확인한 후 `/add-dir`을 다시 실행합니다

3029* 메시지는 파일 액세스를 변경하지 않습니다. 디렉토리의 `.claude/` 콘텐츠가 로드되지 않았음을 보고할 뿐입니다.3055* 이 메시지는 파일 접근 권한을 변경하지 않으며, 디렉터리의 `.claude/` 콘텐츠가 로드되지 않았다는 사실만 알립니다

3030 3056

3031v2.1.261 이전에는 작업 디렉토리가 `/net/<host>` 자동 마운트에 있을 때 모든 `/add-dir <subdirectory>`에 대해 이 메시지가 나타났습니다. Claude Code는 설계상 경로를 확인하기를 거부합니다. 디렉토리는 정상이었고 재시도할 수 없었습니다.3057v2.1.261 이전에는 작업 디렉터리가 `/net/<host>` 자동 마운트에 있을 때 모든 `/add-dir <subdirectory>`에 대해 이 메시지가 나타났습니다. 이 위치에서는 Claude Code가 설계상 경로 확인을 하지 않으므로, 디렉터리에는 문제가 없었고 재시도해도 도움이 되지 않았습니다.

3032 3058

3033<h3 id="workspace-not-trusted-when-starting-remote-control">3059<h3 id="workspace-not-trusted-when-starting-remote-control">

3034 Remote Control 시작 시 작업 영역을 신뢰하지 않음3060 Remote Control 시작 시 워크스페이스를 신뢰할 수 없음

3035</h3>3061</h3>

3036 3062

3037신뢰하지 않은 디렉토리에서 `claude remote-control` 또는 그 `claude rc` 별칭으로 [Remote Control](/docs/ko/remote-control) 서버 모드를 시작했습니다. 명령어의 표준 입력 또는 표준 출력이 터미널이 아닐 때 이 메시지가 나타납니다. 예를 들어 하나가 리디렉션되거나 파이프되었을 때입니다. 명령어는 코드 1로 종료됩니다:3063신뢰하지 않은 디렉터리에서 `claude remote-control` 또는 그 별칭인 `claude rc`로 [Remote Control](/docs/ko/remote-control) 서버 모드를 시작했으며, 명령이 해당 디렉터리를 신뢰할지 물을 수 없었던 경우입니다. 예를 들어 명령의 표준 입력이나 표준 출력 중 하나가 리디렉션되거나 파이프로 연결되어 터미널이 아닌 경우가 이에 해당합니다. 명령은 코드 1로 종료됩니다:

3038 3064

3039```text theme={null}3065```text theme={null}

3040Error: Workspace not trusted. Please run `claude` in /Users/you/project first to review and accept the workspace trust dialog.3066Error: Workspace not trusted. Please run `claude` in /Users/you/project first to review and accept the workspace trust dialog.

3041```3067```

3042 3068

3043터미널에 나타나는 두 가지 변형도 신뢰 디렉토리를 켜는 것을 표시하기에 너무 작은 터미널이나 크기를 보고하지 않은 터미널에서 시작됩니다. 창을 확대하거나 일반 터미널 창으로 전환한 후 `claude rc`를 다시 실행합니다.3069역시 `Error: Workspace not trusted.`로 시작하는 두 가지 변형은 디렉터리를 신뢰할 때 켜지는 항목을 표시하기에는 너무 작은 터미널이나 크기를 보고하지 않은 터미널에서 나타납니다. 창을 키우거나 일반 터미널 창으로 전환한 후 `claude rc`를 다시 실행합니다.

3044 3070

3045홈 디렉토리에서 메시지는 다릅니다. 작업 영역 신뢰 대화가 홈 디렉토리에 대한 신뢰를 저장하지 않기 때문입니다. v2.1.214 이전에는 홈 디렉토리가 위의 메시지를 표시했고 그 조언은 거기서 성공할 수 없었습니다.3071홈 디렉터리에서는 메시지가 다릅니다. 워크스페이스 신뢰 대화 상자는 홈 디렉터리에 대한 신뢰를 저장하지 않으므로, 그곳에서 수락해도 이 검사를 통과할 수 없기 때문입니다. v2.1.214 이전에는 홈 디렉터리에서 위의 메시지가 표시되었지만, 그 안내는 홈 디렉터리에서 효과가 없었습니다.

3046 3072

3047```text theme={null}3073```text theme={null}

3048Error: Workspace not trusted. /Users/you is your home directory, and for security home-directory trust is never saved, so running `claude` here first won't help. Run `claude rc` from a project directory instead (run `claude` there once to accept the trust dialog).3074Error: Workspace not trusted. /Users/you is your home directory, and for security home-directory trust is never saved, so running `claude` here first won't help. Run `claude rc` from a project directory instead (run `claude` there once to accept the trust dialog).

3049```3075```

3050 3076

3051[`Trust <directory>?` 질문](/docs/ko/remote-control#requirements)에서 `n`을 답하거나 Enter를 누르면 명령어는 디렉토리를 이름 지정하는 `Remote Control did not start` 메시지를 출력하고 코드 1로 종료됩니다. `claude rc`를 다시 실행하여 `y`를 답합니다.3077[`Trust <directory>?` 질문](/docs/ko/remote-control#requirements)에 `n`으로 답하거나 Enter를 누르면, 명령은 디렉터리 이름이 포함된 `Remote Control did not start` 메시지를 출력하고 코드 1로 종료됩니다. `claude rc`를 다시 실행하여 `y`로 답합니다.

3052 3078

3053**해야 할 일:**3079**조치 방법:**

3054 3080

3055* 먼저 터미널에서 디렉토리를 신뢰합니다: 거기서 `claude rc`를 실행하고 `y`를 답하거나 거기서 `claude`를 실행하고 [작업 영역 신뢰 대화](/docs/ko/permissions#project-allow-rules-and-workspace-trust)를 수락한 후 원래 명령어를 다시 실행합니다.3081* 먼저 터미널에서 디렉터리를 신뢰합니다. 해당 디렉터리에서 `claude rc`를 실행하여 `y`로 답하거나, `claude`를 실행하여 [워크스페이스 신뢰 대화 상자](/docs/ko/permissions#project-allow-rules-and-workspace-trust)를 수락한 후 원래 명령을 다시 실행합니다

3056* 홈 디렉토리에서 프로젝트 디렉토리로 변경하고 거기서 Remote Control을 시작합니다.3082* 홈 디렉터리에 있는 경우 프로젝트 디렉터리로 이동하여 그곳에서 Remote Control을 시작합니다

3057 3083

3058v2.1.284 이전에는 명령어가 터미널에서도 묻지 않았습니다.3084v2.1.284 이전에는 터미널에서도 명령이 묻지 않았습니다.

3059 3085

3060<h3 id="not-carried-over-to-the-sessions-remote-control-starts">3086<h3 id="not-carried-over-to-the-sessions-remote-control-starts">

3061 Remote Control이 시작하는 세션으로 이월되지 않음3087 Remote Control이 시작하는 세션으로 전달되지 않음

3062</h3>3088</h3>

3063 3089

3064[Remote Control](/docs/ko/remote-control)을 `remote-control` 동사 앞의 전역 `claude` 플래그로 시작했습니다. Remote Control이 시작하는 세션을 제한하거나 구성하는 플래그입니다. 예를 들어 `--settings`, `--setting-sources`, `--permission-mode`, `--disallowed-tools` 또는 `--mcp-config`입니다. 동사 앞에 배치된 플래그는 절대 이러한 세션에 도달하지 않습니다. Claude Code는 대신 시작을 거부하고 플래그를 이름 지정합니다:3090`remote-control` 동사 앞에 전역 `claude` 플래그를 두고 [Remote Control](/docs/ko/remote-control)을 시작한 경우입니다. 해당 플래그는 `--settings`, `--setting-sources`, `--permission-mode`, `--disallowed-tools`, `--mcp-config`처럼 Remote Control이 시작하는 세션을 제한하거나 구성하는 플래그입니다. 동사 앞에 둔 플래그는 이러한 세션에 전달되지 않습니다. Claude Code는 대신 플래그 이름을 표시하며 시작을 거부합니다:

3065 3091

3066```text theme={null}3092```text theme={null}

3067Error: `--settings` before `remote-control` is not carried over to the sessions Remote Control starts, so Remote Control refuses to start rather than drop it — remove it, and give Remote Control's own options after the verb (see `claude remote-control --help`).3093Error: `--settings` before `remote-control` is not carried over to the sessions Remote Control starts, so Remote Control refuses to start rather than drop it — remove it, and give Remote Control's own options after the verb (see `claude remote-control --help`).

3068```3094```

3069 3095

3070Claude Code는 `--verbose`, `--model` 또는 래퍼 주입 `--session-id` 또는 `--plugin-dir` 같은 드롭하기에 무해한 전역 플래그를 거부하지 않습니다: 무시하고 Remote Control이 시작됩니다.3096Claude Code는 `--verbose`, `--model`, 또는 래퍼가 주입한 `--session-id`나 `--plugin-dir`처럼 제거해도 무해한 전역 플래그는 거부하지 않습니다. 이를 무시하고 Remote Control을 시작합니다.

3071 3097

3072Claude Code는 또한 아직 무해한 것으로 인식하지 못하는 전역 플래그를 거부하므로 최신 릴리스에 추가된 플래그는 나중 릴리스가 무해한 것으로 표시할 때까지 이 메시지에 나타날 수 있습니다.3098Claude Code는 아직 무해하다고 인식하지 못한 전역 플래그에 대해서도 시작을 거부하므로, 최신 릴리스에서 추가된 플래그는 이후 릴리스에서 무해한 것으로 표시될 때까지 이 메시지에 나타날 수 있습니다.

3073 3099

3074**해야 할 일:**3100**조치 방법:**

3075 3101

3076* 동사 앞에서 플래그를 제거하고 [Remote Control의 자체 옵션](/docs/ko/remote-control#start-a-remote-control-session)을 그 뒤에 전달합니다. `claude remote-control --help`가 이를 나열합니다.3102* 동사 앞에서 플래그를 제거하고 [Remote Control 자체의 옵션](/docs/ko/remote-control#start-a-remote-control-session)을 동사 뒤에 전달합니다. `claude remote-control --help`에서 옵션 목록을 확인할 수 있습니다

3077* 거부된 플래그가 `--permission-mode`이면 `claude remote-control --permission-mode <mode>`를 실행하여 Remote Control이 시작하는 세션의 권한 모드를 설정합니다.3103* 거부된 플래그가 `--permission-mode`인 경우 `claude remote-control --permission-mode <mode>`를 실행하여 Remote Control이 시작하는 세션의 권한 모드를 설정합니다

3078 3104

3079v2.1.248 이전에는 `claude remote-control`이 전역 플래그가 먼저 올 때 자체 플래그를 허용하지 않았고 명령어가 알 수 없는 옵션 오류로 실패했습니다.3105v2.1.248 이전에는 전역 플래그가 먼저 오면 `claude remote-control`이 자체 플래그를 받지 않았으며, 명령이 `unknown option` 오류로 실패했습니다.

3080 3106

3081<h3 id="claude-import-is-not-yet-available-in-this-build">3107<h3 id="claude-import-is-not-yet-available-in-this-build">

3082 claude import는 이 빌드에서 아직 사용할 수 없음3108 이 빌드에서는 아직 claude import를 사용할 수 없음

3083</h3>3109</h3>

3084 3110

3085[`claude import`](/docs/ko/cli-reference#cli-commands)를 실행했고 Claude Code가 가져오기 흐름이 꺼져 있음을 발견했으므로 명령어가 이 메시지를 출력하는 대신 코드 1로 종료됩니다. v2.1.222 이전에는 가져오기 흐름이 꺼진 빌드가 `import`를 프롬프트로 취급하고 이 메시지를 출력하는 대신 대화형 세션을 시작했습니다.3111[`claude import`](/docs/ko/cli-reference#cli-commands)를 실행했지만 Claude Code가 가져오기 흐름이 꺼져 있음을 확인했으므로, 명령이 가져오기를 시작하지 않고 코드 1로 종료됩니다. v2.1.222 이전에는 가져오기 흐름이 꺼진 빌드에서 `import`를 프롬프트로 처리하여 이 메시지를 출력하는 대신 대화형 세션을 시작했습니다.

3086 3112

3087```text theme={null}3113```text theme={null}

3088`claude import` is not yet available in this build. Run `claude` and use /mcp or edit ~/.claude/settings.json directly.3114`claude import` is not yet available in this build. Run `claude` and use /mcp or edit ~/.claude/settings.json directly.

3089```3115```

3090 3116

3091Claude Code는 Anthropic에서 가져온 기능 플래그를 통해 `claude import`를 켜고 디스크에 캐시합니다. 이 메시지는 캐시된 값이 꺼져 있다는 의미입니다. 원인은 보통 다음 중 하나입니다:3117Claude Code는 Anthropic에서 가져와 디스크에 캐시하는 기능 플래그를 통해 `claude import`를 켭니다. 이 메시지는 캐시된 값이 꺼져 있다는 의미입니다. 원인은 일반적으로 다음 중 하나입니다:

3092 3118

3093* 설치 후 세션을 시작하지 않았으므로 Claude Code가 플래그를 아직 가져오지 않았습니다. 첫 번째 `claude import`는 기능을 사용할 수 있을 때도 이를 출력할 수 있습니다.3119* 설치 후 아직 세션을 시작하지 않아 Claude Code가 플래그를 가져오지 않았습니다. 기능을 사용할 수 있는 경우에도 첫 번째 `claude import`에서 이 메시지가 출력될 수 있습니다.

3094* Amazon Bedrock, Google Cloud의 Agent Platform, Microsoft Foundry, Claude Platform on AWS를 통해 Claude Code를 사용하거나 [Claude 앱 게이트웨이](/docs/ko/claude-apps-gateway#availability-and-limitations)를 통해 사용합니다. Claude Code는 이러한 세션에서 기능 플래그를 가져오지 않으므로 `claude import`는 사용할 수 없습니다.3120* Amazon Bedrock, Google Cloud의 Agent Platform, Microsoft Foundry 또는 Claude Platform on AWS를 통해, 또는 [Claude 앱 게이트웨이](/docs/ko/claude-apps-gateway#availability-and-limitations)를 통해 Claude Code를 사용하고 있습니다. 이러한 세션에서는 Claude Code가 기능 플래그를 가져오지 않으므로 `claude import`를 계속 사용할 수 없습니다.

3095* `DISABLE_TELEMETRY`, `DO_NOT_TRACK`, `DISABLE_GROWTHBOOK` 또는 [`CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC`](/docs/ko/env-vars)를 설정했습니다. 이는 기능 플래그 가져오기를 끕니다. 따라서 `claude import`는 사용할 수 없습니다.3121* 기능 플래그 가져오기를 끄는 `DISABLE_TELEMETRY`, `DO_NOT_TRACK`, `DISABLE_GROWTHBOOK` 또는 [`CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC`](/docs/ko/env-vars)를 설정했으므로 `claude import`를 계속 사용할 수 없습니다.

3096 3122

3097**해야 할 일:**3123**조치 방법:**

3098 3124

3099* 새로 설치한 경우 `claude`를 시작하고 세션이 로드될 때까지 기다린 후 종료하고 `claude import`를 다시 실행합니다.3125* 새로 설치한 경우 `claude`를 시작하고 세션이 로드될 때까지 기다린 후 종료하고 `claude import`를 다시 실행합니다

3100* 기능 플래그 가져오기가 꺼진 경우 구성을 직접 설정합니다: [`claude mcp add`](/docs/ko/mcp#installing-mcp-servers)로 MCP 서버를 추가하고 [`CLAUDE.md` 파일](/docs/ko/memory#how-claude-md-files-load), [스킬 및 명령어](/docs/ko/skills#where-skills-live) 및 [하위 에이전트](/docs/ko/sub-agents#choose-the-subagent-scope)를 만듭니다. 메시지는 또한 `~/.claude/settings.json`을 이름 지정합니다. `claude import`가 이월하는 구성 중에서 해당 파일은 [권한 모드](/docs/ko/settings-reference#permission-settings)만 보유합니다. Claude Code는 이 파일에서 MCP 서버를 읽지 않습니다.3126* 기능 플래그 가져오기가 계속 꺼져 있는 경우 구성을 직접 설정합니다. [`claude mcp add`](/docs/ko/mcp#installing-mcp-servers)로 MCP 서버를 추가하고, 옮기려는 [`CLAUDE.md` 파일](/docs/ko/memory#how-claude-md-files-load), [스킬과 명령](/docs/ko/skills#where-skills-live), [서브에이전트](/docs/ko/sub-agents#choose-the-subagent-scope)를 만듭니다. 메시지에는 `~/.claude/settings.json`도 언급됩니다. `claude import`가 옮기는 구성 중 이 파일에는 [권한 모드](/docs/ko/settings-reference#permission-settings)만 저장되며, Claude Code는 이 파일에서 MCP 서버를 읽지 않습니다.

3101 3127

3102<h3 id="could-not-read-claude-code-config">3128<h3 id="could-not-read-claude-code-config">

3103 Claude Code 구성을 읽을 수 없음3129 Claude Code 구성을 읽을 수 없음

3104</h3>3130</h3>

3105 3131

3106로그인 및 프로젝트별 상태를 저장하는 파일인 `~/.claude.json`을 파싱할 수 없는 동안 [`claude import`](/docs/ko/cli-reference#cli-commands)를 실행했습니다. 하위 명령어는 가용성을 확인하기 위해 해당 파일을 읽지만 대화형 세션이 표시하는 복구 대화를 표시하지 않으므로 코드 1로 종료됩니다. v2.1.222 이전에는 읽을 수 없는 구성 파일이 있는 `claude import`가 대화형 세션을 시작했고 복구 대화가 파일을 처리했습니다.3132Claude Code가 로그인 정보와 프로젝트별 상태를 저장하는 파일인 `~/.claude.json`을 파싱할 수 없는 상태에서 [`claude import`](/docs/ko/cli-reference#cli-commands)를 실행한 경우입니다. 이 하위 명령은 사용 가능 여부를 확인하기 위해 해당 파일을 읽지만 대화형 세션이 표시하는 복구 대화 상자는 표시하지 않으므로 코드 1로 종료됩니다. v2.1.222 이전에는 구성 파일을 읽을 수 없을 때 `claude import`가 대화형 세션을 시작했으며, 그 복구 대화 상자가 파일을 처리했습니다.

3107 3133

3108```text theme={null}3134```text theme={null}

3109Could not read Claude Code config — run `claude` with no arguments to recover it.3135Could not read Claude Code config — run `claude` with no arguments to recover it.

3110```3136```

3111 3137

3112**해야 할 일:**3138**조치 방법:**

3113 3139

3114* 인수 없이 `claude`를 실행합니다. Claude Code가 유효하지 않은 파일을 감지하고 재설정을 제안합니다. 그런 다음 `claude import`를 다시 실행합니다.3140* 인수 없이 `claude`를 실행합니다. Claude Code가 잘못된 파일을 감지하고 초기화를 제안합니다. 그런 다음 `claude import`를 다시 실행합니다.

3115* 수동으로 편집한 내용을 유지하려면 편집기에서 `~/.claude.json`의 JSON 구문을 수정한 후 `claude import`를 다시 실행합니다.3141* 직접 수정한 내용을 유지하려면 대신 편집기에서 `~/.claude.json`의 JSON 구문을 수정한 후 `claude import`를 다시 실행합니다

3116 3142

3117<h3 id="could-not-import-a-server-from-claude-desktop">3143<h3 id="could-not-import-a-server-from-claude-desktop">

3118 Claude Desktop에서 서버를 가져올 수 없음3144 Claude Desktop에서 서버를 가져올 수 없음

3119</h3>3145</h3>

3120 3146

3121Claude Code가 `claude mcp add-from-claude-desktop`에서 선택한 서버 중 하나를 추가할 수 없습니다. 명령어는 여전히 다른 선택된 서버를 가져오고 추가할 수 없는 각 서버당 한 줄을 출력합니다. v2.1.205 이전에는 실패한 첫 번째 서버가 가져오기를 중지했고 선택된 서버 중 어느 것도 추가되지 않았습니다.3147Claude Code가 `claude mcp add-from-claude-desktop`에서 선택한 서버 중 하나를 추가할 수 없는 경우입니다. 명령은 선택한 다른 서버는 계속 가져오며, 추가할 수 없는 서버마다 한 줄씩 출력합니다. v2.1.205 이전에는 처음 실패한 서버에서 가져오기가 중단되었습니다.

3122 3148

3123```text theme={null}3149```text theme={null}

3124Could not import my server: Invalid name my server. Names can only contain letters, numbers, hyphens, and underscores.3150Could not import my server: Invalid name my server. Names can only contain letters, numbers, hyphens, and underscores.

3125```3151```

3126 3152

3127서버 이름 뒤의 텍스트는 이유입니다. 가장 일반적인 것은 이름 확인입니다: Claude Desktop은 서버 이름에 공백 및 마침표 같은 문자를 허용하지만 `claude mcp`는 문자, 숫자, 하이픈 및 밑줄로 제한합니다. 다른 이유로는 검증에 실패하는 서버 구성과 조직의 [MCP 정책](/docs/ko/managed-mcp)에 의해 차단된 서버가 있습니다.3153서버 이름 뒤의 텍스트가 사유입니다. 가장 흔한 사유는 이름 검사입니다. Claude Desktop은 서버 이름에 공백이나 마침표 같은 문자를 허용하지만, `claude mcp`는 문자, 숫자, 하이픈, 밑줄만 허용합니다. 그 밖의 사유로는 검증에 실패한 서버 구성과 조직의 [MCP 정책](/docs/ko/managed-mcp)에 의해 차단된 서버가 있습니다.

3128 3154

3129**해야 할 일:**3155**조치 방법:**

3130 3156

3131* `claude_desktop_config.json`에서 서버 이름을 문자, 숫자, 하이픈 및 밑줄만 사용하도록 바꾼 후 `claude mcp add-from-claude-desktop`을 다시 실행합니다.3157* `claude_desktop_config.json`에서 서버 이름을 문자, 숫자, 하이픈, 밑줄만 사용하도록 변경한 후 `claude mcp add-from-claude-desktop`을 다시 실행합니다

3132* 유효한 이름으로 `claude mcp add` 또는 `claude mcp add-json`을 사용하여 해당 서버를 직접 추가합니다. [Claude Desktop에서 MCP 서버 가져오기](/docs/ko/mcp#import-mcp-servers-from-claude-desktop)를 참조하세요.3158* `claude mcp add` 또는 `claude mcp add-json`을 사용하여 유효한 이름으로 해당 서버를 직접 추가합니다. [Claude Desktop에서 MCP 서버 가져오기](/docs/ko/mcp#import-mcp-servers-from-claude-desktop)를 참조하세요.

3133 3159

3134<h3 id="cannot-add-mcp-server-to-the-managed-scope">3160<h3 id="cannot-add-mcp-server-to-the-managed-scope">

3135 MCP 서버를 관리 범위에 추가할 수 없음3161 관리형 범위에 MCP 서버를 추가할 수 없음

3136</h3>3162</h3>

3137 3163

3138`--scope managed`로 `claude mcp add` 또는 `claude mcp add-json`을 실행했습니다. 해당 범위는 조직이 [`managedMcpServers`](/docs/ko/settings-reference#managedmcpservers) 관리 설정을 통해 제공하는 서버를 보유합니다. Claude Code는 관리 설정에서만 읽으므로 명령어가 해당 범위에 서버를 쓸 수 없습니다.3164`--scope managed`와 함께 `claude mcp add` 또는 `claude mcp add-json`을 실행한 경우입니다. 이 범위에는 조직이 [`managedMcpServers`](/docs/ko/settings-reference#managedmcpservers) 관리형 설정을 통해 제공하는 서버가 담깁니다. Claude Code는 이를 관리형 설정에서만 읽으므로, 명령으로 해당 범위에 서버를 쓸 수 없습니다.

3139 3165

3140```text theme={null}3166```text theme={null}

3141Cannot add MCP server to scope: managed3167Cannot add MCP server to scope: managed

3142```3168```

3143 3169

3144**해야 할 일:**3170**조치 방법:**

3145 3171

3146* 쓸 수 있는 범위에 서버를 추가합니다: `local`, `user` 또는 `project`. `--scope` 없이 명령어는 `local`을 사용합니다. [MCP 설치 범위](/docs/ko/mcp#mcp-installation-scopes)를 참조하세요.3172* 쓸 수 있는 범위인 `local`, `user`, `project` 중 하나에 서버를 추가합니다. `--scope`가 없으면 명령은 `local`을 사용합니다. [MCP 설치 범위](/docs/ko/mcp#mcp-installation-scopes)를 참조하세요

3147* 조직의 모든 사용자에게 서버를 제공하려면 배포하는 관리 설정의 [`managedMcpServers`](/docs/ko/settings-reference#managedmcpservers)에 추가합니다.3173* 조직의 모든 사용자에게 서버를 제공하려면 배포하는 관리형 설정의 [`managedMcpServers`](/docs/ko/settings-reference#managedmcpservers)에 서버를 추가합니다

3148 3174

3149<h3 id="cant-read-mcp-json">3175<h3 id="cant-read-mcp-json">

3150 .mcp.json을 읽을 수 없음3176 .mcp.json을 읽을 수 없음

3151</h3>3177</h3>

3152 3178

3153프로젝트의 [`.mcp.json`](/docs/ko/mcp#project-scope)을 읽는 명령어(예: `--scope project`로 `claude mcp add` 또는 `claude mcp add-json` 또는 `claude mcp remove`)가 현재 디렉토리의 파일이 일반 파일이 아니거나 2MiB보다 크다는 것을 발견했으므로 파일을 읽는 대신 이 오류로 종료됩니다.3179`--scope project`를 사용한 `claude mcp add`나 `claude mcp add-json`, 또는 `claude mcp remove`처럼 프로젝트의 [`.mcp.json`](/docs/ko/mcp#project-scope)을 읽는 명령이 현재 디렉터리의 파일이 일반 파일이 아니거나 2MiB보다 크다는 것을 확인하여, 파일을 읽지 않고 이 오류로 종료된 경우입니다.

3154 3180

3155```text theme={null}3181```text theme={null}

3156Can't read .mcp.json: it isn't a regular file or is larger than 2097152 bytes. Fix or remove it, then run the command again.3182Can't read .mcp.json: it isn't a regular file or is larger than 2097152 bytes. Fix or remove it, then run the command again.

3157```3183```

3158 3184

3159v2.1.257 이전에는 `.mcp.json`의 FIFO가 명령어를 출력 없이 영원히 기다리게 했고 `/dev/zero` 같은 장치 파일에 대한 심볼릭 링크가 프로세스가 종료될 때까지 메모리를 증가시켰습니다.3185v2.1.257 이전에는 `.mcp.json`에 FIFO가 있으면 명령이 출력 없이 무한정 대기했으며, `/dev/zero` 같은 장치 파일로의 심볼릭 링크는 프로세스가 종료될 때까지 메모리를 증가시켰습니다.

3160 3186

3161**해야 할 일:**3187**조치 방법:**

3162 3188

3163* 현재 디렉토리의 `.mcp.json`에 무엇이 있는지 확인합니다. [프로젝트 범위 형식](/docs/ko/mcp#project-scope)의 일반 JSON 파일로 바꾸거나 삭제한 후 명령어를 다시 실행합니다.3189* 현재 디렉터리의 `.mcp.json`에 무엇이 있는지 확인합니다. [프로젝트 범위 형식](/docs/ko/mcp#project-scope)의 일반 JSON 파일로 교체하거나 삭제한 후 명령을 다시 실행합니다.

3164 3190

3165<h3 id="mcp-server-was-not-saved-or-removed">3191<h3 id="mcp-server-was-not-saved-or-removed">

3166 MCP 서버는 저장되지 않았거나 제거되지 않음3192 MCP 서버가 저장되거나 제거되지 않음

3167</h3>3193</h3>

3168 3194

3169`claude mcp add`, `claude mcp add-json` 또는 `claude mcp remove`를 `user` 또는 `local` [범위](/docs/ko/mcp#mcp-installation-scopes)의 서버에 대해 실행했습니다. 두 범위 모두 `~/.claude.json`에 저장되고 쓴 후 Claude Code가 읽을 때 변경이 해당 파일에 없습니다. 명령어는 성공 줄 대신 이 오류로 종료됩니다.3195`user` 또는 `local` [범위](/docs/ko/mcp#mcp-installation-scopes)의 서버에 대해 `claude mcp add`, `claude mcp add-json` 또는 `claude mcp remove`를 실행한 경우입니다. 두 범위 모두 `~/.claude.json`에 저장되는데, 쓰기 후 Claude Code가 파일을 다시 읽었을 때 변경 사항이 해당 파일에 없습니다. 명령은 성공 메시지 대신 이 오류로 종료됩니다.

3170 3196

3171```text theme={null}3197```text theme={null}

3172MCP server "example" was not saved to /home/user/.claude.json. If that file is read-only or protected by a sandbox, make it writable or run the command outside the sandbox, then add the server again.3198MCP server "example" was not saved to /home/user/.claude.json. If that file is read-only or protected by a sandbox, make it writable or run the command outside the sandbox, then add the server again.

3173```3199```

3174 3200

3175제거 후 메시지는 `was not removed from`을 읽고 `then remove the server again`으로 끝납니다. `local` 범위 서버의 경우 경로 뒤에 항목이 속한 프로젝트 디렉토리가 `(local scope for /path/to/project)`로 따릅니다.3201제거 후에는 메시지가 `was not removed from`으로 표시되며 `then remove the server again`으로 끝납니다. `local` 범위 서버의 경우 경로 뒤에 해당 항목이 속한 프로젝트 디렉터리가 `(local scope for /path/to/project)` 형태로 표시됩니다.

3176 3202

3177v2.1.283 이전에는 `claude mcp add`, `claude mcp add-json` 및 `claude mcp remove`가 변경이 파일에 도달하지 않았을 때도 성공을 보고했습니다.3203v2.1.283 이전에는 변경 사항이 파일에 반영되지 않은 경우에도 `claude mcp add`, `claude mcp add-json`, `claude mcp remove`가 성공을 보고했습니다.

3178 3204

3179**해야 할 일:**3205**조치 방법:**

3180 3206

3181* 메시지가 이름 지정하는 파일을 쓸 수 있게 만들거나 샌드박스 외부에서 명령어를 실행한 후 동일한 추가 또는 제거 명령어를 다시 실행합니다.3207* 메시지에 표시된 파일을 쓰기 가능하게 만들거나 샌드박스 밖에서 명령을 실행한 후 같은 추가 또는 제거 명령을 다시 실행합니다.

3182 3208

3183<h3 id="mcp-server-may-not-have-been-saved-or-removed">3209<h3 id="mcp-server-may-not-have-been-saved-or-removed">

3184 MCP 서버는 저장되지 않았거나 제거되지 않았을 수 있음3210 MCP 서버가 저장되거나 제거되지 않았을 수 있음

3185</h3>3211</h3>

3186 3212

3187`claude mcp add`, `claude mcp add-json` 또는 `claude mcp remove`를 `user` 또는 `local` [범위](/docs/ko/mcp#mcp-installation-scopes)의 서버에 대해 실행했고 Claude Code가 변경을 확인하기 위해 `~/.claude.json`을 읽을 수 없습니다. 변경이 디스크에 있을 수도 있고 없을 수도 있습니다. 괄호의 텍스트는 해당 읽기의 오류입니다.3213`user` 또는 `local` [범위](/docs/ko/mcp#mcp-installation-scopes)의 서버에 대해 `claude mcp add`, `claude mcp add-json` 또는 `claude mcp remove`를 실행했지만, Claude Code가 변경 사항을 확인하기 위해 `~/.claude.json`을 다시 읽을 수 없었던 경우입니다. 변경 사항이 디스크에 있을 수도 있고 없을 수도 있습니다. 괄호 안의 텍스트는 해당 읽기에서 발생한 오류입니다.

3188 3214

3189```text theme={null}3215```text theme={null}

3190MCP server "example" may not have been saved: /home/user/.claude.json could not be read to confirm the change (EACCES: permission denied, open '/home/user/.claude.json'). Run `claude mcp get example` to check, then add the server again if it is missing.3216MCP server "example" may not have been saved: /home/user/.claude.json could not be read to confirm the change (EACCES: permission denied, open '/home/user/.claude.json'). Run `claude mcp get example` to check, then add the server again if it is missing.

3191```3217```

3192 3218

3193제거 후 메시지는 `may not have been removed`를 읽고 `then remove the server again if it is still listed`로 끝납니다.3219제거 후에는 메시지가 `may not have been removed`로 표시되며 `then remove the server again if it is still listed`로 끝납니다.

3194 3220

3195v2.1.283 이전에는 변경을 확인할 수 없었을 때도 명령어가 성공을 보고했습니다.3221v2.1.283 이전에는 변경 사항을 확인할 수 없는 경우에도 명령이 성공을 보고했습니다.

3196 3222

3197**해야 할 일:**3223**조치 방법:**

3198 3224

3199* `claude mcp get <name>`을 실행하여 변경이 디스크에 있는지 확인합니다. `local` 범위 서버의 경우 서버가 속한 프로젝트 디렉토리에서 실행합니다. 로컬 범위는 프로젝트별이기 때문입니다.3225* `claude mcp get <name>`을 실행하여 변경 사항이 디스크에 있는지 확인합니다. `local` 범위 서버의 경우 로컬 범위는 프로젝트별이므로 서버가 속한 프로젝트 디렉터리에서 실행합니다.

3200* 추가 후 서버가 누락되었거나 제거 후 여전히 나열되면 동일한 추가 또는 제거 명령어를 다시 실행합니다.3226* 추가 후 서버가 없거나 제거 후에도 여전히 목록에 있으면 같은 추가 또는 제거 명령을 다시 실행합니다.

3201 3227

3202<h3 id="anthropic-hosted-and-doesnt-support-local-oauth">3228<h3 id="anthropic-hosted-and-doesnt-support-local-oauth">

3203 서버는 Anthropic 호스팅이며 로컬 OAuth를 지원하지 않음3229 서버가 Anthropic에서 호스팅되며 로컬 OAuth를 지원하지 않음

3204</h3>3230</h3>

3205 3231

3206URL이 타사 ID 공급자를 통해 인증하는 Anthropic 호스팅 커넥터 호스트를 가리키는 MCP 서버에 대한 로그인을 시작했습니다. 이러한 호스트에는 `microsoft365.mcp.claude.com`, `gmail.mcp.claude.com` 및 `gcal.mcp.claude.com`이 포함됩니다. Claude Code는 `/mcp` 패널과 `claude mcp login` 모두에서 이러한 호스트에 대한 로컬 OAuth 흐름을 시작하기를 거부합니다. [이들의 로그인은 claude.ai를 통해서만 작동](/docs/ko/mcp#use-mcp-servers-from-claude-ai)하기 때문입니다.3232서드 파티 ID 공급자를 통해 인증하는 Anthropic 호스팅 커넥터 호스트를 URL로 가리키는 MCP 서버에 대해 로그인을 시작한 경우입니다. 이러한 호스트에는 `microsoft365.mcp.claude.com`, `gmail.mcp.claude.com`, `gcal.mcp.claude.com`이 포함됩니다. [이러한 호스트의 로그인은 claude.ai를 통해서만 작동](/docs/ko/mcp#use-mcp-servers-from-claude-ai)하므로, Claude Code는 `/mcp` 패널과 `claude mcp login` 모두에서 이러한 호스트에 대한 로컬 OAuth 흐름 시작을 거부합니다.

3207 3233

3208```text theme={null}3234```text theme={null}

3209"gmail" is Anthropic-hosted and doesn't support local OAuth. Connect it via Settings → Connectors on claude.ai (requires `claude login`), then it'll be available here automatically.3235"gmail" is Anthropic-hosted and doesn't support local OAuth. Connect it via Settings → Connectors on claude.ai (requires `claude login`), then it'll be available here automatically.

3210```3236```

3211 3237

3212Claude Code는 URL로 이러한 호스트를 일치시키므로 `claude mcp add` 또는 `.mcp.json`으로 추가한 서버가 이 중 하나를 가리킬 때 메시지가 나타납니다.3238**조치 방법:**

~~3213~~

3214**해야 할 일:**

3215 3239

3216* `claude mcp remove <name>`으로 항목을 제거하여 같은 URL의 claude.ai 커넥터를 숨길 수 없습니다.3240* 같은 URL의 claude.ai 커넥터를 가리지 않도록 `claude mcp remove <name>`으로 해당 항목을 제거합니다

3217* 제거한 후 [claude.ai/customize/connectors](https://claude.ai/customize/connectors)에서 서비스를 연결합니다. Claude Code에서 사용하는 계정에 로그인합니다. 연결되면 활성 인증 방법이 claude.ai 구독 로그인이면 [커넥터가 Claude Code에 자동으로 나타납니다](/docs/ko/mcp#use-mcp-servers-from-claude-ai).3241* 제거한 후 Claude Code에서 사용하는 계정으로 로그인한 상태에서 [claude.ai/customize/connectors](https://claude.ai/customize/connectors)에서 서비스를 연결합니다. 연결되면 현재 인증 방법이 claude.ai 구독 로그인인 경우 [커넥터가 Claude Code에 자동으로 나타납니다](/docs/ko/mcp#use-mcp-servers-from-claude-ai)

3218 3242

3219<h3 id="server-rejected-the-authorization-header-minted-by-the-configured-headershelper">3243<h3 id="server-rejected-the-authorization-header-minted-by-the-configured-headershelper">

3220 서버가 구성된 headersHelper에 의해 발행된 Authorization 헤더를 거부함3244 서버가 구성된 headersHelper가 생성한 Authorization 헤더를 거부함

3221</h3>3245</h3>

3222 3246

3223[`headersHelper`](/docs/ko/mcp#use-dynamic-headers-for-custom-authentication)가 `Authorization` 헤더를 제공하는 MCP 서버가 HTTP 401 또는 403으로 연결에 응답했으므로 Claude Code는 연결을 실패로 보고합니다. 헬퍼가 `Authorization` 헤더를 제공하므로 Claude Code는 [서버에 대해 OAuth로 폴백하지 않습니다](/docs/ko/mcp#authenticate-with-remote-mcp-servers):3247[`headersHelper`](/docs/ko/mcp#use-dynamic-headers-for-custom-authentication)가 `Authorization` 헤더를 제공하는 MCP 서버가 HTTP 401 또는 403으로 연결에 응답했으므로 Claude Code가 연결 실패를 보고합니다. 헬퍼가 `Authorization` 헤더를 제공하므로 Claude Code는 해당 서버에 대해 [OAuth로 폴백하지 않습니다](/docs/ko/mcp#authenticate-with-remote-mcp-servers):

3224 3248

3225```text theme={null}3249```text theme={null}

3226Server rejected the Authorization header minted by the configured headersHelper (HTTP 401). Check that the helper command returns a valid credential for this MCP endpoint — OAuth fallback is disabled when the helper supplies Authorization.3250Server rejected the Authorization header minted by the configured headersHelper (HTTP 401). Check that the helper command returns a valid credential for this MCP endpoint — OAuth fallback is disabled when the helper supplies Authorization.

3227```3251```

3228 3252

3229Claude Code는 각 연결 시도에서 헬퍼를 다시 실행하므로 토큰 회전 경쟁 같은 일시적 거부 후 재시도가 새 자격 증명으로 성공할 수 있습니다.3253Claude Code는 연결을 시도할 때마다 헬퍼를 다시 실행하므로, 토큰 교체 경합처럼 일시적인 거부 후의 재시도는 새 자격 증명으로 성공할 수 있습니다.

3230 3254

3231**해야 할 일:**3255**조치 방법:**

3232 3256

3233* Claude Code가 실행하는 방식으로 `headersHelper` 명령어를 직접 실행합니다: [Claude Code가 실행하는 디렉토리](/docs/ko/mcp#where-the-helper-runs)에서, [Claude Code가 설정하는 환경 변수](/docs/ko/mcp#use-dynamic-headers-for-custom-authentication)를 사용하고, [Claude Code가 프로젝트 `.mcp.json`, 플러그인 또는 프로젝트 에이전트 파일의 서버에 대해 제거하는 자격 증명 변수](/docs/ko/mcp#which-variables-a-helper-can-read) 없이. 서버의 엔드포인트가 허용하는 `Authorization` 값을 출력하는지 확인합니다.3257* Claude Code가 실행하는 방식과 동일하게 `headersHelper` 명령을 직접 실행합니다. 즉, [Claude Code가 헬퍼를 실행하는 디렉터리](/docs/ko/mcp#where-the-helper-runs)에서, [Claude Code가 헬퍼에 설정하는 환경 변수](/docs/ko/mcp#use-dynamic-headers-for-custom-authentication)와 함께, 그리고 프로젝트 `.mcp.json`, 플러그인 또는 프로젝트 에이전트 파일에서 온 서버의 경우 [Claude Code가 제거하는 자격 증명 변수](/docs/ko/mcp#which-variables-a-helper-can-read) 없이 실행합니다. 서버의 엔드포인트가 받아들이는 `Authorization` 값이 출력되는지 확인합니다

3234* 헬퍼 또는 자격 증명 소스를 수정한 후 `/mcp`에서 서버를 선택하고 **Reconnect**를 선택합니다.3258* 헬퍼나 그 자격 증명 소스를 수정한 후 `/mcp`에서 서버를 선택하고 **Reconnect**를 선택합니다

3235 3259

3236v2.1.248 이전에는 Claude Code가 헬퍼가 `Authorization` 헤더를 제공하는 서버에 대해 OAuth 검색을 실행했습니다. 해당 검색은 거부된 자격 증명을 보고하는 대신 `Incompatible auth server: does not support dynamic client registration`으로 실패할 수 있습니다.3260v2.1.248 이전에는 헬퍼가 `Authorization` 헤더를 제공하는 서버에 대해서도 Claude Code가 OAuth 검색을 실행했습니다. 이 검색은 거부된 자격 증명을 보고하는 대신 `Incompatible auth server: does not support dynamic client registration`으로 실패할 수 있었습니다.

3237 3261

3238<h3 id="mcp-permission-prompt-tool-not-found">3262<h3 id="mcp-permission-prompt-tool-not-found">

3239 MCP 권한 프롬프트 도구를 찾을 수 없음3263 MCP 권한 프롬프트 도구를 찾을 수 없음

3240</h3>3264</h3>

3241 3265

3242[`--permission-prompt-tool`](/docs/ko/cli-reference#cli-flags)에 전달한 도구가 실행이 처음 권한 결정이 필요할 때 연결된 MCP 도구 중에 없습니다. 서버가 연결되지 않았거나 연결된 서버가 해당 이름의 도구를 노출하지 않기 때문입니다. Claude Code는 여전히 프롬프트를 보냅니다: [비대화형](/docs/ko/headless) 실행은 승인이 필요한 첫 번째 도구 호출에서 이 오류로 종료되고 코드 1로 종료되므로 요청이 이루어졌음에도 불구하고 답변을 생성하지 않습니다. 첫 번째 프롬프트 전에 Claude Code는 [`MCP_TIMEOUT`](/docs/ko/env-vars)으로 설정된 서버당 연결 타임아웃 30초까지 해당 서버가 연결될 때까지 기다립니다. v2.1.206 이전에는 시작이 서버가 연결을 완료할 때까지 기다리지 않았으므로 느리게 시작하지만 정상인 서버가 이 오류를 생성했습니다.3266실행에서 처음으로 권한 결정이 필요했을 때 [`--permission-prompt-tool`](/docs/ko/cli-reference#cli-flags)에 전달한 도구가 연결된 MCP 도구 중에 없었던 경우입니다. 해당 서버가 연결되지 않았거나, 연결된 서버 중 그 이름의 도구를 노출하는 서버가 없기 때문입니다. Claude Code는 여전히 프롬프트를 전송합니다. [비대화형](/docs/ko/headless) 실행은 첫 번째 도구 호출에서 이 오류와 종료 코드 1로 종료되므로, 요청이 이루어졌더라도 응답을 생성하지 않습니다. 첫 번째 프롬프트 전에 Claude Code는 [`MCP_TIMEOUT`](/docs/ko/env-vars)으로 설정되는 서버별 연결 타임아웃인 최대 30초 동안 해당 서버가 연결되기를 기다립니다. v2.1.206 이전에는 시작 시 서버 연결이 완료되기를 기다리지 않았으므로, 시작이 느리지만 정상적인 서버에서도 이 오류가 발생했습니다.

3243 3267

3244```text theme={null}3268```text theme={null}

3245Error: MCP tool mcp__permissions__approve (passed via --permission-prompt-tool) not found. Available MCP tools: none3269Error: MCP tool mcp__permissions__approve (passed via --permission-prompt-tool) not found. Available MCP tools: none

3246```3270```

3247 3271

3248`Available MCP tools:` 뒤의 목록은 대기가 끝났을 때 연결된 MCP 도구를 이름 지정합니다.3272`Available MCP tools:` 뒤의 목록은 연결되어 있던 MCP 도구를 나타냅니다.

3249 3273

3250**해야 할 일:**3274**조치 방법:**

3251 3275

3252* 서버가 시작되고 연결된 상태로 유지되는지 확인합니다: 같은 디렉토리에서 `claude mcp list`를 실행하고 서버가 연결됨으로 나열되는지 확인합니다.3276* 서버가 시작되고 연결 상태를 유지하는지 확인합니다. 같은 디렉터리에서 `claude mcp list`를 실행하여 서버가 연결됨으로 표시되는지 확인합니다

3253* 도구 이름이 서버가 노출하는 `mcp__<server>__<tool>` 이름과 일치하는지 확인합니다.3277* 도구 이름이 서버가 노출하는 `mcp__<server>__<tool>` 이름과 일치하는지 확인합니다

3254* 서버가 시작하는 데 30초 이상 필요하면 [`MCP_TIMEOUT`](/docs/ko/env-vars)을 높입니다.3278* 서버가 시작하는 데 30초 이상 필요하면 [`MCP_TIMEOUT`](/docs/ko/env-vars)을 늘립니다

3255 3279

3256<h3 id="oauth-callback-port-is-already-in-use">3280<h3 id="oauth-callback-port-is-already-in-use">

3257 OAuth 콜백 포트가 이미 사용 중3281 OAuth 콜백 포트가 이미 사용 중임

3258</h3>3282</h3>

3259 3283

3260OAuth를 사용하여 원격 MCP 서버에 로그인하면 Claude Code는 로그인 콜백을 수신하기 위해 로컬 리스너를 시작합니다. 해당 리스너가 필요한 포트가 다른 프로세스에 의해 보유되면 로그인이 이 메시지로 실패합니다. 이는 주로 [`MCP_OAUTH_CALLBACK_PORT`](/docs/ko/env-vars) 변수 또는 `--callback-port`를 통해 설정된 [고정 콜백 포트](/docs/ko/mcp#use-a-fixed-oauth-callback-port)에서 발생합니다. 하나 없이 Claude Code는 사용 가능한 포트를 선택합니다.3284OAuth로 원격 MCP 서버에 로그인하면 Claude Code는 로그인 콜백을 받기 위해 로컬 리스너를 시작합니다. 해당 리스너에 필요한 포트를 다른 프로세스가 점유하고 있으면 로그인이 이 메시지와 함께 실패합니다. 이는 주로 [`MCP_OAUTH_CALLBACK_PORT`](/docs/ko/env-vars) 변수나 `--callback-port`로 설정한 [고정 콜백 포트](/docs/ko/mcp#use-a-fixed-oauth-callback-port)에서 발생합니다. 고정 포트가 없으면 Claude Code가 사용 가능한 포트를 선택하기 때문입니다.

3261 3285

3262```text theme={null}3286```text theme={null}

3263OAuth callback port <port> is already in use — another process may be holding it. Run `lsof -ti:<port> -sTCP:LISTEN` to find it.3287OAuth callback port <port> is already in use — another process may be holding it. Run `lsof -ti:<port> -sTCP:LISTEN` to find it.

3264```3288```

3265 3289

3266Windows에서 제안된 명령어는 대신 `netstat -ano | findstr :<port>`입니다.3290Windows에서는 대신 `netstat -ano | findstr :<port>` 명령이 제안됩니다.

3267 3291

3268**해야 할 일:**3292**조치 방법:**

3269 3293

3270* 메시지의 명령어를 실행하여 포트를 보유하는 프로세스를 찾고 중지하거나 완료될 때까지 기다립니다.3294* 메시지의 명령을 실행하여 포트를 점유한 프로세스를 찾고, 해당 프로세스를 중지하거나 완료될 때까지 기다립니다

3271* 다른 프로그램이 해당 포트를 영구적으로 필요로 하면 서버에 다른 리디렉션 URI를 등록하고 `MCP_OAUTH_CALLBACK_PORT` 또는 `--callback-port`(사용하는 것)로 포트를 설정합니다.3295* 다른 프로그램이 해당 포트를 계속 필요로 한다면 서버에 다른 리디렉션 URI를 등록하고, 사용하는 방식에 따라 `MCP_OAUTH_CALLBACK_PORT` 또는 `--callback-port`로 그 포트를 설정합니다

3272* 그런 다음 로그인을 다시 시작합니다. 예를 들어 `/mcp`에서 서버를 선택합니다.3296* 그런 다음 `/mcp`에서 서버를 선택하는 등의 방법으로 로그인을 다시 시작합니다

3273 3297

3274<h3 id="no-available-ports-for-oauth-redirect">3298<h3 id="no-available-ports-for-oauth-redirect">

3275 OAuth 리디렉션에 사용 가능한 포트 없음3299 OAuth 리디렉션에 사용할 수 있는 포트가 없음

3276</h3>3300</h3>

3277 3301

3278[OAuth](/docs/ko/mcp#authenticate-with-remote-mcp-servers)를 사용하여 원격 MCP 서버에 로그인하면 Claude Code는 로그인 콜백을 수신하기 위해 로컬 리스너를 시작합니다. Claude Code가 로컬 포트를 바인드할 수 없을 때 로그인이 이 메시지로 실패합니다. 머신의 무언가가 `127.0.0.1`에서 수신 대기하는 것을 방지합니다. 예를 들어 보안 소프트웨어 또는 로컬 리스너를 거부하는 샌드박스 정책입니다.3302[OAuth](/docs/ko/mcp#authenticate-with-remote-mcp-servers)로 원격 MCP 서버에 로그인하면 Claude Code는 로그인 콜백을 받기 위해 로컬 리스너를 시작합니다. Claude Code가 이를 위한 로컬 포트를 바인딩할 수 없으면 로그인이 이 메시지와 함께 실패합니다. 보안 소프트웨어나 로컬 리스너를 거부하는 샌드박스 정책처럼, 머신의 무언가가 `127.0.0.1`에서 수신 대기하는 것을 막고 있습니다.

3279 3303

3280```text theme={null}3304```text theme={null}

3281No available ports for OAuth redirect3305No available ports for OAuth redirect

3282```3306```

3283 3307

3284v2.1.268 이전에는 Claude Code가 운영 체제 할당 포트로 폴백하지 않았으므로 메시지는 Claude Code가 선택한 포트만 바인드할 수 없을 때도 나타났습니다. 이는 Hyper-V가 Claude Code가 선택하는 포트를 포함하는 포트 범위를 예약하는 Windows 호스트에서 발생할 수 있습니다.3308v2.1.268 이전에는 Claude Code가 운영 체제가 할당하는 포트로 폴백하지 않았으므로, 자체적으로 선택한 포트만 바인딩할 수 없는 경우에도 이 메시지가 나타났습니다. 이는 Hyper-V가 Claude Code가 선택하는 포트를 포함하는 포트 범위를 예약하는 Windows 호스트에서 발생할 수 있습니다.

3285 3309

3286**해야 할 일:**3310**조치 방법:**

3287 3311

3288* 보안 소프트웨어 또는 샌드박스 정책이 프로세스가 `127.0.0.1`에서 수신 대기하는 것을 차단하는지 확인하고 Claude Code가 로컬 포트를 바인드하도록 허용합니다.3312* 보안 소프트웨어나 샌드박스 정책이 `127.0.0.1`에서 프로세스가 수신 대기하는 것을 차단하는지 확인하고, Claude Code가 로컬 포트를 바인딩하도록 허용합니다

3289* 그런 다음 로그인을 다시 시작합니다. 예를 들어 `/mcp`에서 서버를 선택합니다.3313* 그런 다음 `/mcp`에서 서버를 선택하는 등의 방법으로 로그인을 다시 시작합니다

3290 3314

3291<h3 id="security-review-fails-without-origin-head">3315<h3 id="security-review-fails-without-origin-head">

3292 /security-review가 origin/HEAD 없이 실패함3316 origin/HEAD 없이 /security-review가 실패함

3293</h3>3317</h3>

3294 3318

3295[`/security-review`](/docs/ko/commands#all-commands)는 `origin/HEAD`에 대해 분기를 비교하여 검토 컨텍스트를 구축합니다. `origin/HEAD`는 `origin` 원격의 기본 분기가 무엇인지 기록하는 로컬 ref입니다. 해당 ref가 없으면 diff를 수집하는 git 명령어가 실패하고 검토가 시작하기 전에 중지됩니다.3319[`/security-review`](/docs/ko/commands#all-commands)는 `origin` 원격의 기본 브랜치를 기록하는 로컬 ref인 `origin/HEAD`와 현재 브랜치의 diff를 구해 리뷰 컨텍스트를 구성합니다. 해당 ref가 없으면 diff를 수집하는 git 명령이 실패하고 리뷰가 시작되기 전에 중단됩니다.

3296 3320

3297```text theme={null}3321```text theme={null}

3298Error: Shell command failed for pattern "!`git diff --name-only origin/HEAD...`": [stderr]3322Error: Shell command failed for pattern "!`git diff --name-only origin/HEAD...`": [stderr]

3301'git <command> [<revision>...] -- [<file>...]'3325'git <command> [<revision>...] -- [<file>...]'

3302```3326```

3303 3327

3304메시지는 대신 `git log` 또는 다른 `git diff`를 인용할 수 있습니다. Git은 원격이 기본 분기를 광고하고 fetch refspec이 이를 포함할 때만 `origin/HEAD`를 만듭니다. 전체 `git clone`이 커밋이 있는 원격을 수행합니다. ref는 이러한 설정에서 누락됩니다:3328메시지에 `git log`나 다른 `git diff`가 대신 인용될 수도 있습니다. Git은 원격이 기본 브랜치를 알리고 fetch refspec이 이를 포함하는 경우에만 `origin/HEAD`를 만들며, 커밋이 있는 원격을 완전히 `git clone`하면 이 조건이 충족됩니다. 다음과 같은 설정에서는 ref가 없습니다:

3305 3329

3306* 단일 분기 또는 CI 체크아웃(너무 좁은 refspec을 가져옴)3330* 너무 좁은 refspec을 가져오는 단일 브랜치 또는 CI 체크아웃

3307* 서버 측 HEAD가 아무도 푸시하지 않은 분기를 가리키는 원격3331* 서버 측 HEAD가 아무도 푸시하지 않은 브랜치를 가리키는 원격

3308* `origin` 원격이 없거나 가져온 적이 없는 저장소3332* `origin` 원격이 없거나 한 번도 fetch하지 않은 저장소

3309 3333

3310Claude Code는 [동적 컨텍스트를 주입](/docs/ko/skills#when-an-injected-command-fails)하는 모든 스킬에 대해 동일한 오류를 표시하고 실패한 주입 명령어는 해당 스킬의 호출을 중단합니다. 명령어가 실행되기 전에 두 개의 형제 문자열이 발생합니다:3334Claude Code는 [동적 컨텍스트를 주입](/docs/ko/skills#when-an-injected-command-fails)하는 모든 스킬에 대해 같은 오류를 표시하며, 주입된 명령이 실패하면 해당 스킬의 호출이 중단됩니다. 명령이 실행되기 전에 발생하는 관련 메시지가 두 가지 있습니다:

3311 3335

3312* `Shell command permission check failed for pattern "..."`: 명령어의 권한 확인이 허용하지 않았습니다. [주입 명령어의 권한 확인](/docs/ko/skills#permission-checks-on-injected-commands)은 각 권한 모드에서 어떤 결과가 중단되는지 그리고 `allowed-tools`로 명령어를 사전 승인하는 방법을 다룹니다.3336* `Shell command permission check failed for pattern "..."`: 명령의 권한 검사가 명령을 허용하지 않았습니다. [주입된 명령의 권한 검사](/docs/ko/skills#permission-checks-on-injected-commands)에서 각 권한 모드에서 어떤 결과가 중단을 일으키는지와 `allowed-tools`로 명령을 사전 승인하는 방법을 다룹니다

3313* ``Skill <name> requires bash (`shell: bash` in frontmatter) but Git Bash was not found``: 스킬의 frontmatter가 bash가 없는 머신에서 bash를 요구합니다. Git for Windows를 설치하거나 frontmatter를 `shell: powershell`로 변경합니다. [주입 명령어가 실행되는 방식](/docs/ko/skills#how-injected-commands-run)을 참조하세요.3337* ``Skill <name> requires bash (`shell: bash` in frontmatter) but Git Bash was not found``: 스킬의 frontmatter가 bash가 없는 머신에서 bash를 요구합니다. Git for Windows를 설치하거나 frontmatter를 `shell: powershell`로 변경합니다. [주입된 명령의 실행 방식](/docs/ko/skills#how-injected-commands-run)을 참조하세요

3314 3338

3315**해야 할 일:**3339**조치 방법:**

3316 3340

3317* 원격의 기본 분기를 이름 지정하여 ref를 만듭니다: `git remote set-head origin <default-branch>`. 이는 로컬 추적 ref `origin/<default-branch>`가 존재할 때마다 작동합니다. 단일 분기 클론처럼 없으면 먼저 분기를 가져옵니다: `git remote set-branches --add origin <branch>`를 실행한 후 `git fetch origin`을 실행한 후 set-head 명령어를 다시 실행합니다. `/security-review`를 다시 실행합니다.3341* 원격의 기본 브랜치를 지정하여 ref를 만듭니다: `git remote set-head origin <default-branch>`. 이 방법은 로컬 추적 ref `origin/<default-branch>`가 있으면 항상 작동합니다. 단일 브랜치 클론처럼 해당 ref가 없으면 먼저 브랜치를 가져옵니다. `git remote set-branches --add origin <branch>`를 실행한 다음 `git fetch origin`을 실행하고 set-head 명령을 다시 실행합니다. 그런 다음 `/security-review`를 다시 실행합니다.

3318* 분기를 이름 지정하지 않으려면 `git fetch origin`을 실행한 후 `git remote set-head origin --auto`를 실행합니다. 이는 원격에 기본 분기가 무엇인지 묻습니다. 원격이 비어 있거나 HEAD가 아무도 푸시하지 않은 분기를 가리킬 때 `error: Cannot determine remote HEAD`로 실패합니다. 대신 분기를 명시적으로 이름 지정합니다. 클론이 해당 분기를 가져오지 않을 때 `error: Not a valid ref`로 실패합니다. 먼저 위와 같이 refspec을 넓힙니다.3342* 브랜치 이름을 지정하지 않으려면 `git fetch origin`을 실행한 다음 원격에 기본 브랜치가 무엇인지 묻는 `git remote set-head origin --auto`를 실행합니다. 원격이 비어 있거나 HEAD가 아무도 푸시하지 않은 브랜치를 가리켜 기본 브랜치를 알리지 않으면 `error: Cannot determine remote HEAD`로 실패하므로, 대신 브랜치를 명시적으로 지정합니다. 클론이 해당 브랜치를 가져오지 않으면 `error: Not a valid ref`로 실패하므로, 먼저 위와 같이 refspec을 넓힙니다.

3319* 저장소에 원격이 없으면 `git remote add origin <url>`로 추가하고 ref를 만들기 전에 가져옵니다. 원격이 비어 있으면 `git push -u origin HEAD`로 분기를 먼저 푸시하고 set-head 명령어에서 해당 분기를 이름 지정합니다. `origin/HEAD`는 방금 푸시한 분기를 가리키므로 분기가 이와 달라질 때까지 `/security-review`는 빈 diff를 봅니다.3343* 저장소에 원격이 없으면 `git remote add origin <url>`로 원격을 추가하고 ref를 만들기 전에 fetch합니다. 원격이 비어 있으면 먼저 `git push -u origin HEAD`로 브랜치를 푸시하고 set-head 명령에서 해당 브랜치를 지정합니다. 그러면 `origin/HEAD`가 방금 푸시한 브랜치를 가리키므로, 브랜치가 갈라질 때까지 `/security-review`에는 빈 diff가 표시됩니다.

3320 3344

3321<h3 id="input-must-be-provided-when-using-print">3345<h3 id="input-must-be-provided-when-using-print">

3322 \--print 사용 시 입력을 제공해야 함3346 `--print` 사용 시 입력을 제공해야 함

3323</h3>3347</h3>

3324 3348

3325베어 `claude`는 대화형 UI를 시작하기 위해 stdout이 터미널이어야 합니다. stdout이 리디렉션되거나 PowerShell ISE 및 일부 IDE 출력 창 같은 실제 터미널이 아닐 때 `claude`는 대신 [비대화형](/docs/ko/headless)으로 실행됩니다. 이는 프롬프트가 필요한 `claude -p`와 동일한 모드이므로 메시지는 플래그를 전달하지 않았을 때도 `--print`를 이름 지정합니다. `-p`/`--print`를 프롬프트 없이 전달하고 stdin에 파이프된 것이 없으면 어디서나 동일한 오류를 생성합니다.3349인수 없는 `claude`로 대화형 UI를 시작하려면 stdout이 터미널이어야 합니다. stdout이 리디렉션되거나, PowerShell ISE나 일부 IDE 출력 창처럼 콘솔이 실제 터미널이 아니면, `claude`는 대신 [비대화형](/docs/ko/headless)으로 실행됩니다. 이는 프롬프트가 필요한 `claude -p`와 같은 모드이므로, 플래그를 전달하지 않았더라도 메시지에 `--print`가 표시됩니다. 프롬프트 없이, 그리고 stdin으로 아무것도 파이프하지 않고 `-p`/`--print`를 전달해도 어디서나 같은 오류가 발생합니다.

3326 3350

3327```text theme={null}3351```text theme={null}

3328Error: Input must be provided either through stdin or as a prompt argument when using --print3352Error: Input must be provided either through stdin or as a prompt argument when using --print

3329```3353```

3330 3354

3331**해야 할 일:**3355**조치 방법:**

3332 3356

3333* 대화형 사용의 경우 실제 터미널에서 `claude`를 실행합니다: ISE가 아닌 Windows Terminal 또는 PowerShell 콘솔, IDE의 통합 터미널이 아닌 출력 창.3357* 대화형으로 사용하려면 실제 터미널에서 `claude`를 실행합니다. ISE 대신 Windows Terminal이나 PowerShell 콘솔을, 출력 창 대신 IDE의 통합 터미널을 사용합니다

3334* 일회용 사용의 경우 프롬프트를 전달합니다: `claude -p "your question"` 또는 `echo "your question" | claude -p`로 파이프합니다.3358* 일회성으로 사용하려면 프롬프트를 전달합니다: `claude -p "your question"`, 또는 `echo "your question" | claude -p`로 파이프합니다

3335 3359

3336<h3 id="input-contained-only-whitespace">3360<h3 id="input-contained-only-whitespace">

3337 입력에 공백만 포함됨3361 입력에 공백만 포함됨

3338</h3>3362</h3>

3339 3363

3340[비대화형 모드](/docs/ko/headless)에서 Claude Code는 API가 보이는 텍스트가 없는 메시지를 거부하기 때문에 공백, 탭 또는 줄 바꿈으로만 구성된 프롬프트를 보내는 대신 거부합니다. 어떤 메시지를 보는지는 빈 프롬프트가 어디서 왔는지에 따라 달라집니다:3364[비대화형 모드](/docs/ko/headless)에서 Claude Code는 공백, 탭 또는 줄바꿈으로만 이루어진 프롬프트를 전송하지 않고 거부합니다. API가 보이는 텍스트가 없는 메시지를 거부하기 때문입니다. 표시되는 메시지는 빈 프롬프트의 출처에 따라 다릅니다:

3341 3365

3342* **`claude -p`의 프롬프트 인수 또는 파이프된 stdin**: `claude`는 `Error: Input contained only whitespace. Provide a prompt with text through stdin or as a prompt argument when using --print`로 종료됩니다.3366* **`claude -p`의 프롬프트 인수 또는 파이프된 stdin**: `claude`가 `Error: Input contained only whitespace. Provide a prompt with text through stdin or as a prompt argument when using --print`로 종료됩니다

3343* **실행 중인 `--input-format stream-json` 또는 [Agent SDK](/docs/ko/agent-sdk/overview) 세션에 제출된 메시지**: Claude Code는 모델을 호출하지 않고 턴을 종료하고 세션은 사용 가능한 상태로 유지됩니다. 거부는 정보 메시지로 그리고 턴의 결과 텍스트로 도착합니다: `Blank prompt — the message was only whitespace, so nothing was sent to the model.`3367* **실행 중인 `--input-format stream-json` 또는 [Agent SDK](/docs/ko/agent-sdk/overview) 세션에 제출된 메시지**: Claude Code는 모델을 호출하지 않고 턴을 종료하며 세션은 계속 사용할 수 있습니다. 거부는 정보 메시지와 턴의 결과 텍스트로 전달됩니다: `Blank prompt — the message was only whitespace, so nothing was sent to the model.`

3344 3368

3345v2.1.229 이전에는 Claude Code가 공백 전용 메시지를 API로 보냈고 API는 400 오류로 요청을 거부했습니다.3369v2.1.229 이전에는 Claude Code가 공백만 있는 메시지를 API로 전송했으며, API는 400 오류로 요청을 거부했습니다.

3346 3370

3347**해야 할 일:**3371**조치 방법:**

3348 3372

3349* 프롬프트에 보이는 텍스트를 포함합니다. 스크립트가 변수 또는 파일에서 프롬프트를 구축하면 Claude Code를 호출하기 전에 소스가 비어 있지 않은지 확인합니다.3373* 프롬프트에 보이는 텍스트를 포함합니다. 스크립트가 변수나 파일에서 프롬프트를 구성하는 경우 Claude Code를 호출하기 전에 소스가 비어 있지 않은지 확인합니다.

3350 3374

3351<h3 id="stream-json-input-carried-over-256m-characters-with-no-newline">3375<h3 id="stream-json-input-carried-over-256m-characters-with-no-newline">

3352 stream-json 입력이 줄 바꿈 없이 256M 문자를 초과함3376 stream-json 입력이 줄바꿈 없이 256M자를 초과함

3353</h3>3377</h3>

3354 3378

3355프로그램이 `claude -p --input-format stream-json` 실행에 stdin으로 줄 바꿈 없이 268,435,456자 이상을 보냈으므로 Claude Code는 이 오류를 stderr에 출력하고 더 많은 입력을 버퍼링하는 대신 코드 1로 종료됩니다. 메시지는 해당 예산을 `256M`으로 명시합니다. v2.1.257 이전에는 Claude Code가 이러한 입력을 제한 없이 버퍼링했고 프로세스가 충돌하거나 종료될 때까지 메모리를 증가시켰습니다.3379프로그램이 `claude -p --input-format stream-json` 실행에 줄바꿈 없이 268,435,456자를 초과하여 stdin으로 보냈으므로, Claude Code가 더 많은 입력을 버퍼링하지 않고 이 오류를 stderr에 출력한 후 코드 1로 종료합니다. 메시지에서는 이 한도를 `256M`으로 표시합니다. v2.1.257 이전에는 Claude Code가 이러한 입력을 제한 없이 버퍼링하여, 프로세스가 충돌하거나 종료될 때까지 메모리가 증가했습니다.

3356 3380

3357```text theme={null}3381```text theme={null}

3358Error: stream-json input carried over 256M characters with no newline. Each stream-json message must be a single newline-terminated JSON line: either the producer is not newline-terminating its messages, or one message exceeded this budget.3382Error: stream-json input carried over 256M characters with no newline. Each stream-json message must be a single newline-terminated JSON line: either the producer is not newline-terminating its messages, or one message exceeded this budget.

3359```3383```

3360 3384

3361줄 바꿈 없이 이 정도로 긴 입력은 보통 생산자가 stream-json 생산자가 아니라는 의미입니다. 예를 들어 실수로 파이프된 바이너리 파일 또는 일반 로그 출력입니다. 예산을 초과하는 단일 메시지는 동일한 확인에 실패합니다.3385줄바꿈 없이 이렇게 긴 입력은 일반적으로 실수로 파이프된 바이너리 파일이나 일반 로그 출력처럼 생산자가 stream-json 생산자가 아니라는 의미입니다. 한도를 초과하는 단일 메시지도 같은 검사에서 실패합니다.

3362 3386

3363**해야 할 일:**3387**조치 방법:**

3364 3388

3365* stdin으로 파이프되는 것을 확인합니다. [`--input-format stream-json`](/docs/ko/cli-reference#cli-flags)을 사용하면 모든 메시지는 줄 바꿈으로 종료된 JSON 줄 하나여야 합니다.3389* stdin으로 무엇이 파이프되는지 확인합니다. [`--input-format stream-json`](/docs/ko/cli-reference#cli-flags)에서는 모든 메시지가 줄바꿈으로 끝나는 하나의 JSON 줄이어야 합니다

3366* 일반 텍스트를 대신 보내려면 `--input-format stream-json`을 제거합니다. `claude -p`는 기본적으로 stdin에서 일반 텍스트 프롬프트를 읽습니다.3390* 대신 일반 텍스트를 보내려면 `--input-format stream-json`을 제거합니다. `claude -p`는 기본적으로 stdin에서 일반 텍스트 프롬프트를 읽습니다

3367 3391

3368<h3 id="unknown-command">3392<h3 id="unknown-command">

3369 알 수 없는 명령어3393 알 수 없는 명령

3370</h3>3394</h3>

3371 3395

3372대화형 터미널 세션에서 이 세션의 명령어와 일치하지 않는 `/` 이름을 제출했으므로 Claude Code는 아무것도 실행하지 않고 이름을 보고합니다:3396대화형 터미널 세션에서 이 세션의 어떤 명령과도 일치하지 않는 `/` 이름을 제출했으므로, Claude Code가 아무것도 실행하지 않고 해당 이름을 보고합니다:

3373 3397

3374```text theme={null}3398```text theme={null}

3375Unknown command: /hepl. Did you mean /help?3399Unknown command: /hepl. Did you mean /help?

3376```3400```

3377 3401

3378Claude Code는 이 세션의 메뉴가 나열하는 가장 가까운 명령어 이름 또는 별칭을 제안합니다. 가까운 것이 없으면 메시지는 이름 뒤에 끝납니다. 원인은 보통 다음 중 하나입니다:3402Claude Code는 이 세션의 메뉴에 나열된 명령 이름이나 별칭 중 가장 가까운 것을 제안합니다. 가까운 것이 없으면 메시지는 이름 뒤에서 끝납니다. 원인은 일반적으로 다음 중 하나입니다:

3379 3403

3380* `/hepl`을 `/help`로 하는 오타입니다. [명령어 메뉴가 입력과 일치하는 방식](/docs/ko/commands#how-the-command-menu-matches-what-you-type)은 제출하기 전에 가까운 일치를 선택하는 것을 다룹니다.3404* `/help` 대신 `/hepl`처럼 오타를 입력했습니다. [명령 메뉴가 입력 내용과 일치시키는 방식](/docs/ko/commands#how-the-command-menu-matches-what-you-type)에서 제출하기 전에 가까운 일치 항목을 선택하는 방법을 다룹니다

3381* 플랫폼, 계획 또는 인증 방법 같은 요구 사항이 충족되지 않아 이 세션에서 사용할 수 없는 명령어입니다. [`/web-setup`](/docs/ko/web-quickstart#web-setup-shows-no-commands-match-or-unknown-command) 및 [`/schedule`](/docs/ko/routines#schedule-returns-unknown-command)의 문제 해결 항목은 두 가지 일반적인 경우를 안내합니다. 일부 명령어는 조직의 정책이 비활성화할 때 [`Cloud sessions are disabled by your organization's policy`](#cloud-sessions-are-disabled-by-your-organizations-policy) 같은 자체 메시지로 응답합니다.3405* 명령이 존재하지만 플랫폼, 플랜 또는 인증 방법 같은 요구 사항이 충족되지 않아 이 세션에서 사용할 수 없습니다. [`/web-setup`](/docs/ko/web-quickstart#web-setup-shows-no-commands-match-or-unknown-command)과 [`/schedule`](/docs/ko/routines#schedule-returns-unknown-command)의 문제 해결 항목에서 흔한 두 가지 사례를 안내합니다. 일부 명령은 조직의 정책이 이를 비활성화한 경우 [`Cloud sessions are disabled by your organization's policy`](#cloud-sessions-are-disabled-by-your-organizations-policy)처럼 자체 메시지로 응답합니다

3382* [플러그인](/docs/ko/plugins/overview) 또는 [MCP 서버](/docs/ko/mcp#use-mcp-prompts-as-commands)의 명령어가 이 세션에 설치되거나 연결되지 않았습니다.3406* 이 세션에 설치되거나 연결되지 않은 [플러그인](/docs/ko/plugins/overview) 또는 [MCP 서버](/docs/ko/mcp#use-mcp-prompts-as-commands)의 명령입니다

3383 3407

3384Claude Code는 대화형 터미널 세션에서만 일치하지 않는 `/` 이름에 이 방식으로 응답합니다. 다른 모든 세션에서는 대신 프롬프트를 Claude에 일반 메시지로 보냅니다. 명령어가 실행되지 않았고 Claude가 세션에서 실행할 수 있는 명령어 목록이 있다는 메모가 포함됩니다. 이러한 세션에는 다음이 포함됩니다:3408Claude Code는 대화형 터미널 세션에서만 일치하지 않는 `/` 이름에 이런 방식으로 응답합니다. 그 밖의 모든 세션에서는 명령이 실행되지 않았다는 메모와 이 세션에서 Claude가 실행할 수 있는 명령 목록과 함께 프롬프트를 일반 메시지로 Claude에 전송합니다. 이러한 세션에는 다음이 포함됩니다:

3385 3409

3386* `-p` 실행3410* `-p` 실행

3387* [Agent SDK](/docs/ko/agent-sdk/overview) 애플리케이션3411* [Agent SDK](/docs/ko/agent-sdk/overview) 애플리케이션

3388* [Desktop 앱](/docs/ko/desktop)의 Code 탭3412* [데스크톱 앱](/docs/ko/desktop)의 Code 탭

3389* [VS Code 확장](/docs/ko/vs-code)의 채팅 패널3413* [VS Code 확장](/docs/ko/vs-code)의 채팅 패널

3390* [클라우드 세션](/docs/ko/claude-code-on-the-web) 및 [루틴](/docs/ko/routines)3414* [클라우드 세션](/docs/ko/claude-code-on-the-web)과 [루틴](/docs/ko/routines)

3391 3415

3392이러한 세션 중 하나에서 실행할 수 없는 기본 제공 명령어의 경우 Claude Code는 여전히 명령어를 Claude로 보내는 대신 사용할 수 없다고 응답합니다. v2.1.274 이전에는 클라우드 세션과 루틴만 일치하지 않는 이름을 Claude로 보냈습니다. v2.1.273 이전에는 `Unknown command`로도 응답했습니다.3416이러한 세션 중 하나에서 실행할 수 없는 기본 제공 명령의 경우, Claude Code는 여전히 Claude에 전송하는 대신 해당 명령을 사용할 수 없다고 응답합니다. v2.1.274 이전에는 클라우드 세션과 루틴만 일치하지 않는 이름을 Claude에 전송했습니다. v2.1.273 이전에는 클라우드 세션과 루틴도 `Unknown command`로 응답했습니다.

3393 3417

3394Claude Code는 `/`로 시작하는 모든 프롬프트를 명령어로 취급하지 않습니다. `/` 뒤의 첫 번째 단어가 Lean doc 주석을 여는 `/-` 같은 구두점으로 시작하거나 `/var/log/syslog` 같은 경로일 때 프롬프트를 Claude에 일반 메시지로 보냅니다.3418Claude Code는 `/`로 시작하는 모든 프롬프트를 명령으로 처리하지는 않습니다. `/` 뒤의 첫 단어가 Lean 문서 주석을 여는 `/--`처럼 구두점으로 시작하거나 `/var/log/syslog` 같은 경로인 경우, 프롬프트를 일반 메시지로 Claude에 전송합니다.

3395 3419

3396v2.1.236 이전에는 명령어 메뉴가 입력한 이름에 대한 가까운 일치를 나열하는 동안 Enter를 누르면 Claude Code가 일치를 실행했으므로 `/hepl` 같은 오타가 이 메시지를 생성하는 대신 `/help`를 실행했습니다.3420v2.1.236 이전에는 명령 메뉴에 입력한 이름과 가까운 일치 항목이 나열된 상태에서 `Enter`를 누르면 Claude Code가 그 일치 항목을 실행했으므로, `/hepl` 같은 오타가 이 메시지를 표시하는 대신 `/help`를 실행했습니다.

3397 3421

3398**해야 할 일:**3422**조치 방법:**

3399 3423

3400* 제안된 이름을 실행하거나 `/` 뒤에 이름의 일부를 입력하여 이 세션에서 사용 가능한 것을 확인합니다.3424* 제안된 이름을 실행하거나, `/` 다음에 이름의 일부를 입력하여 이 세션에서 사용할 수 있는 명령을 확인합니다

3401* Claude Code가 문서화된 명령어를 알 수 없는 것으로 보고하면 [명령어 참조](/docs/ko/commands)의 행에서 이름 지정하는 요구 사항을 확인합니다.3425* Claude Code가 문서화된 명령을 알 수 없다고 보고하면 [명령 참조](/docs/ko/commands)에서 해당 행을 확인하여 명시된 요구 사항을 살펴봅니다

3402 3426

3403<h3 id="diff-is-too-large-for-ultrareview">3427<h3 id="diff-is-too-large-for-ultrareview">

3404 Diff가 ultrareview에 너무 큼3428 ultrareview에 비해 diff가 너무 큼

3405</h3>3429</h3>

3406 3430

3407분기와 기본 분기 간의 diff(커밋되지 않은 변경 사항 및 스테이징된 변경 사항 포함)가 [ultrareview](/docs/ko/ultrareview)의 크기 제한을 초과하므로 `/code-review ultra` 및 `claude ultrareview` 하위 명령어는 클라우드 세션이 시작되기 전에 검토를 거부합니다. 거부된 검토는 무료 실행을 사용하지 않으며 사용 크레딧을 청구하지 않습니다. 메시지는 적용 중인 제한, diff의 크기 및 가장 많은 변경된 줄에 기여하는 파일을 이름 지정합니다. v2.1.216 이전에는 메시지가 원시 diff 통계만 표시했습니다.3431커밋되지 않은 변경 사항과 스테이징된 변경 사항을 포함하여 현재 브랜치와 기본 브랜치 간의 diff가 [ultrareview](/docs/ko/ultrareview)의 크기 제한을 초과하므로, `/code-review ultra`와 `claude ultrareview` 하위 명령이 클라우드 세션이 시작되기 전에 리뷰를 거부합니다. 거부된 리뷰는 무료 실행을 사용하지 않으며 사용량 크레딧도 청구하지 않습니다. 메시지에는 적용 중인 제한, diff의 크기, 변경된 줄 수가 가장 많은 파일이 표시됩니다. v2.1.216 이전에는 메시지에 원시 diff 통계만 표시되었습니다.

3408 3432

3409```text theme={null}3433```text theme={null}

3410Diff is too large for ultrareview: 812 files, 96,410 lines changed (limits: 500 files, 8,000 lines). Largest files: package-lock.json (41,904 lines), dist/bundle.js (18,210 lines), src/generated/api.ts (9,876 lines). Pass a closer base branch (`/code-review ultra <branch>`) to narrow the scope, or split the change.3434Diff is too large for ultrareview: 812 files, 96,410 lines changed (limits: 500 files, 8,000 lines). Largest files: package-lock.json (41,904 lines), dist/bundle.js (18,210 lines), src/generated/api.ts (9,876 lines). Pass a closer base branch (`/code-review ultra <branch>`) to narrow the scope, or split the change.

3411```3435```

3412 3436

3413풀 요청을 검토하면 동일한 제한이 적용됩니다. 해당 형식의 메시지는 `PR #<N> is too large for ultrareview`로 시작하고 PR의 파일 및 줄 수를 이름 지정합니다.3437풀 리퀘스트를 리뷰할 때도 같은 제한이 적용됩니다. 이 경우 메시지는 `PR #<N> is too large for ultrareview`로 시작하며 PR의 파일 수와 줄 수가 표시됩니다.

3414 3438

3415**해야 할 일:**3439**조치 방법:**

3416 3440

3417* 기본 분기를 더 가깝게 전달합니다. 예를 들어 `/code-review ultra develop`이므로 검토는 해당 분기에 대한 diff만 포함합니다.3441* `/code-review ultra develop`처럼 작업에 더 가까운 기본 브랜치를 전달하여 리뷰가 해당 브랜치와의 diff만 다루도록 합니다

3418* 변경을 더 작은 분기로 분할하고 각각을 검토합니다. 메시지가 이름 지정하는 파일은 가장 많은 변경된 줄에 기여하므로 이들을 자신의 분기로 이동하여 시작합니다.3442* 변경 사항을 더 작은 브랜치로 나누고 각각을 리뷰합니다. 메시지에 표시된 파일이 변경된 줄 수가 가장 많으므로, 먼저 해당 파일을 별도의 브랜치로 옮기는 것부터 시작합니다.

3419 3443

3420<h3 id="could-not-find-merge-base-with-the-base-branch">3444<h3 id="could-not-find-merge-base-with-the-base-branch">

3421 기본 분기와의 병합 기반을 찾을 수 없음3445 기본 브랜치와의 merge-base를 찾을 수 없음

3422</h3>3446</h3>

3423 3447

3424`/code-review ultra` 및 `claude ultrareview` 하위 명령어는 두 분기 간의 diff를 검토합니다. 이는 두 분기가 공유하는 커밋이 필요합니다. `git merge-base`가 없으면 Claude Code는 클라우드 세션이 시작되기 전에 검토를 거부합니다. Claude Code가 완전한 것으로 확인할 수 있는 클론에서 최소 하나의 분기가 있으면 대신 [모든 추적된 파일을 검토](/docs/ko/ultrareview#diff-limits-and-fallbacks)로 폴백합니다. 기본 분기를 전혀 찾을 수 없을 때, Claude Code가 클론이 완전한지 확인할 수 없을 때 또는 SHA-256 객체 형식 같은 전체 트리 diff가 불가능한 드문 저장소에서 이 거부를 봅니다.3448`/code-review ultra`와 `claude ultrareview` 하위 명령은 현재 브랜치와 기본 브랜치 간의 diff를 리뷰하며, 이를 위해서는 두 브랜치가 공유하는 커밋이 필요합니다. `git merge-base`가 공유 커밋을 찾지 못하면 Claude Code는 클라우드 세션이 시작되기 전에 리뷰를 거부합니다. Claude Code가 완전하다고 확인할 수 있고 브랜치가 하나 이상 있는 클론에서는 거부하는 대신 [추적되는 모든 파일을 리뷰](/docs/ko/ultrareview#diff-limits-and-fallbacks)하는 방식으로 폴백합니다. 이 거부는 기본 브랜치를 전혀 찾을 수 없는 경우, Claude Code가 클론이 완전한지 확인할 수 없는 경우, 또는 SHA-256 객체 형식처럼 전체 트리 diff가 불가능한 드문 저장소에서 표시됩니다.

3425 3449

3426```text theme={null}3450```text theme={null}

3427Could not find merge-base with main. Pass the base branch explicitly (e.g. `/code-review ultra develop`) or make sure you're in a git repo with a main branch.3451Could not find merge-base with main. Pass the base branch explicitly (e.g. `/code-review ultra develop`) or make sure you're in a git repo with a main branch.

3428```3452```

3429 3453

3430첫 번째 문장 뒤의 힌트는 Claude Code가 관찰한 것에 따라 달라집니다:3454첫 번째 문장 뒤의 힌트는 Claude Code가 관찰한 내용에 따라 달라집니다:

3431 3455

3432* **기본 분기를 전달하지 않았습니다**: Claude Code는 저장소의 기본 분기와 비교했고 위의 예와 같이 기본을 명시적으로 전달하도록 제안합니다.3456* **기본 브랜치를 전달하지 않은 경우**: Claude Code가 저장소의 기본 브랜치와 비교했으며, 위의 예처럼 기본 브랜치를 명시적으로 전달하도록 제안합니다

3433* **클론에 이미 있는 기본 분기를 전달했습니다**: 힌트는 ``Make sure <branch> exists locally or on origin (try `git fetch origin <branch>`)``를 읽습니다.3457* **클론에 이미 있던 기본 브랜치를 전달한 경우**: 힌트는 ``Make sure <branch> exists locally or on origin (try `git fetch origin <branch>`)``입니다

3434* **클론에 없는 기본 분기를 전달했습니다**: Claude Code는 비교하기 전에 origin에서 가져왔습니다. 힌트는 ``<branch> was fetched from origin but shares no history with HEAD. If another branch is your real base, pass it explicitly (`/code-review ultra <branch>`)``를 읽습니다. Claude Code가 클론이 얕은지 확인할 수 없을 때 대신 `git fetch --unshallow origin`을 제안합니다. v2.1.221 이전에는 모든 가져온 기본 분기에 대해 `git fetch --unshallow origin`을 제안했고 완전한 클론에서 해당 명령어는 `fatal: --unshallow on a complete repository does not make sense`로 실패합니다.3458* **클론에 없던 기본 브랜치를 전달한 경우**: Claude Code가 비교하기 전에 origin에서 해당 브랜치를 가져왔습니다. 힌트는 ``<branch> was fetched from origin but shares no history with HEAD. If another branch is your real base, pass it explicitly (`/code-review ultra <branch>`)``이며, Claude Code가 클론이 얕은 클론인지 판단할 수 없으면 대신 `git fetch --unshallow origin`을 제안합니다. v2.1.221 이전에는 가져온 모든 기본 브랜치에 대해 힌트가 `git fetch --unshallow origin`을 제안했는데, 완전한 클론에서는 이 명령이 `fatal: --unshallow on a complete repository does not make sense`로 실패합니다.

3435 3459

3436**해야 할 일:**3460**조치 방법:**

3437 3461

3438* 다른 분기가 실제 기본이면 명시적으로 전달합니다: `/code-review ultra <branch>`3462* 다른 브랜치가 실제 기본 브랜치라면 명시적으로 전달합니다: `/code-review ultra <branch>`

3439* 클론이 전체 기록을 갖지 않을 수 있으면 `git fetch --unshallow origin`을 실행하고 검토를 다시 실행합니다.3463* 클론에 전체 기록이 없을 수 있다면 `git fetch --unshallow origin`을 실행하고 리뷰를 다시 실행합니다

3440 3464

3441<h3 id="your-checkout-has-no-branches">3465<h3 id="your-checkout-has-no-branches">

3442 체크아웃에 분기가 없음3466 체크아웃에 브랜치가 없음

3443</h3>3467</h3>

3444 3468

3445체크아웃은 커밋을 가질 수 있지만 분기는 없습니다: `git init` 뒤에 `git fetch <url>` 및 `git checkout FETCH_HEAD`를 실행하면 분기가 없는 분리된 HEAD를 얻습니다. Claude Code는 저장소를 git 번들로 패키징하여 [ultrareview](/docs/ko/ultrareview)를 위해 업로드하고 분기나 다른 ref가 없는 저장소를 번들할 수 없으므로 `/code-review ultra` 및 `claude ultrareview` 하위 명령어는 클라우드 세션이 시작되기 전에 검토를 거부합니다.3469체크아웃에 커밋은 있지만 브랜치는 없을 수 있습니다. `git init`을 실행한 후 `git fetch <url>`과 `git checkout FETCH_HEAD`를 실행하면 ref가 없는 분리된 HEAD가 됩니다. Claude Code는 [ultrareview](/docs/ko/ultrareview)를 위해 업로드할 저장소를 git 번들로 패키징하는데, 브랜치나 다른 ref가 없는 저장소는 번들로 만들 수 없으므로 `/code-review ultra`와 `claude ultrareview` 하위 명령이 클라우드 세션이 시작되기 전에 리뷰를 거부합니다.

3446 3470

3447```text theme={null}3471```text theme={null}

3448Your checkout has no branches (detached HEAD only), which cloud review can't bundle. Create one first — `git checkout -b <name>` — then rerun /code-review ultra.3472Your checkout has no branches (detached HEAD only), which cloud review can't bundle. Create one first — `git checkout -b <name>` — then rerun /code-review ultra.

3449```3473```

3450 3474

3451v2.1.221 이전에는 Claude Code가 이 체크아웃의 모든 추적된 파일을 검토하려고 시도했고 업로드가 실패했습니다.3475v2.1.221 이전에는 Claude Code가 이 체크아웃에서 추적되는 모든 파일을 리뷰하려고 시도했으며, 업로드가 실패했습니다.

3452 3476

3453**해야 할 일:**3477**조치 방법:**

3454 3478

3455* 현재 커밋에서 `git checkout -b <name>`으로 분기를 만든 후 검토를 다시 실행합니다.3479* `git checkout -b <name>`으로 현재 커밋에 브랜치를 만든 후 리뷰를 다시 실행합니다

3456 3480

3457<h3 id="no-github-account-is-connected-to-your-claude-account">3481<h3 id="no-github-account-is-connected-to-your-claude-account">

3458 GitHub 계정이 Claude 계정에 연결되지 않음3482 Claude 계정에 연결된 GitHub 계정이 없음

3459</h3>3483</h3>

3460 3484

3461`/code-review ultra <PR#>` 또는 `claude ultrareview <PR#>`을 실행했고 클라우드 세션을 만들기 전에 Claude Code는 서버에 [Claude 계정에 연결된 GitHub 계정](/docs/ko/ultrareview#review-a-pull-request)이 PR의 저장소에 도달할 수 있는지 묻습니다. 계정이 연결되지 않았거나 연결이 만료되었으므로 클라우드 클론이 실패하고 Claude Code는 시작을 거부합니다. Claude Code는 거부된 시작에 대해 무료 실행을 사용하거나 사용 크레딧을 청구하지 않습니다.3485`/code-review ultra <PR#>` 또는 `claude ultrareview <PR#>`를 실행했으며, Claude Code는 클라우드 세션을 만들기 전에 [Claude 계정에 연결된 GitHub 계정](/docs/ko/ultrareview#review-a-pull-request)이 PR의 저장소에 접근할 수 있는지 서버에 확인합니다. 연결된 계정이 없거나 연결이 만료되어 클라우드 클론이 실패할 것이므로 Claude Code가 실행을 거부합니다. Claude Code는 거부된 실행에 대해 무료 실행을 사용하거나 사용량 크레딧을 청구하지 않습니다.

3462 3486

3463```text theme={null}3487```text theme={null}

3464Ultrareview clones <owner>/<repo> in the cloud with the GitHub account connected to your Claude account, and none is connected (or the connection expired). To fix: run /web-setup to reuse your GitHub CLI login, or connect an account at https://claude.ai/connect-github — then re-run /code-review ultra 1234 (allow a minute after connecting).3488Ultrareview clones <owner>/<repo> in the cloud with the GitHub account connected to your Claude account, and none is connected (or the connection expired). To fix: run /web-setup to reuse your GitHub CLI login, or connect an account at https://claude.ai/connect-github — then re-run /code-review ultra 1234 (allow a minute after connecting).

3465```3489```

3466 3490

3467[`/web-setup`](/docs/ko/web-quickstart#connect-from-your-terminal)이 세션에서 사용할 수 없으면 메시지는 claude.ai 링크만 이름 지정합니다.3491세션에서 [`/web-setup`](/docs/ko/web-quickstart#connect-from-your-terminal)을 사용할 수 없는 경우 메시지에는 claude.ai 링크만 표시됩니다.

3468 3492

3469**해야 할 일:**3493**조치 방법:**

3470 3494

3471* `/web-setup`을 실행하여 GitHub CLI 로그인을 Claude 계정에 연결하거나 [claude.ai/connect-github](https://claude.ai/connect-github)에서 계정을 연결합니다.3495* `/web-setup`을 실행하여 GitHub CLI 로그인을 Claude 계정에 연결하거나, [claude.ai/connect-github](https://claude.ai/connect-github)에서 계정을 연결합니다

3472* 연결 후 1분 후 검토를 다시 실행합니다.3496* 연결하고 1분 정도 지난 후 리뷰를 다시 실행합니다

3473 3497

3474v2.1.248 이전에는 Claude Code가 시작 전에 이를 확인하지 않았습니다.3498v2.1.248 이전에는 Claude Code가 실행 전에 이를 확인하지 않았습니다.

3475 3499

3476<h3 id="your-connected-github-account-cant-see-the-repository">3500<h3 id="your-connected-github-account-cant-see-the-repository">

3477 연결된 GitHub 계정이 저장소를 볼 수 없음3501 연결된 GitHub 계정이 저장소를 볼 수 없음

3478</h3>3502</h3>

3479 3503

3480`/code-review ultra <PR#>` 또는 `claude ultrareview <PR#>`을 실행했고 [Claude 계정에 연결된 GitHub 계정](/docs/ko/ultrareview#review-a-pull-request)이 PR의 저장소를 읽을 수 없으므로 클라우드 클론이 실패하고 Claude Code는 시작을 거부합니다. Claude Code는 거부된 시작에 대해 무료 실행을 사용하거나 사용 크레딧을 청구하지 않습니다.3504`/code-review ultra <PR#>` 또는 `claude ultrareview <PR#>`를 실행했지만 [Claude 계정에 연결된 GitHub 계정](/docs/ko/ultrareview#review-a-pull-request)이 PR의 저장소를 읽을 수 없으므로, 클라우드 클론이 실패할 것이어서 Claude Code가 실행을 거부합니다. Claude Code는 거부된 실행에 대해 무료 실행을 사용하거나 사용량 크레딧을 청구하지 않습니다.

3481 3505

3482```text theme={null}3506```text theme={null}

3483Your connected GitHub account can't see <owner>/<repo> — usually the Claude GitHub app isn't installed on <owner> or wasn't granted this repo (web-connected accounts need it for private repos), or a different GitHub account is connected. To fix: run /web-setup to reuse your GitHub CLI login, or install the app at https://github.com/apps/claude/installations/new — then re-run /code-review ultra 1234.3507Your connected GitHub account can't see <owner>/<repo> — usually the Claude GitHub app isn't installed on <owner> or wasn't granted this repo (web-connected accounts need it for private repos), or a different GitHub account is connected. To fix: run /web-setup to reuse your GitHub CLI login, or install the app at https://github.com/apps/claude/installations/new — then re-run /code-review ultra 1234.

3484```3508```

3485 3509

3486[`/web-setup`](/docs/ko/web-quickstart#connect-from-your-terminal)이 세션에서 사용할 수 없으면 메시지는 앱 설치만 이름 지정합니다.3510세션에서 [`/web-setup`](/docs/ko/web-quickstart#connect-from-your-terminal)을 사용할 수 없는 경우 메시지에는 앱 설치만 표시됩니다.

3487 3511

3488**해야 할 일:**3512**조치 방법:**

3489 3513

3490* 로컬 `gh` CLI가 저장소를 읽을 수 있으면 `/web-setup`을 실행하여 해당 로그인을 Claude 계정에 연결합니다.3514* 로컬 `gh` CLI가 저장소를 읽을 수 있다면 `/web-setup`을 실행하여 해당 로그인을 Claude 계정에 연결합니다

3491* 변경 후 검토를 다시 실행합니다.3515* 변경 후 리뷰를 다시 실행합니다

3492 3516

3493v2.1.248 이전에는 Claude Code가 시작 전에 이를 확인하지 않았습니다.3517v2.1.248 이전에는 Claude Code가 실행 전에 이를 확인하지 않았습니다.

3494 3518

3495<h3 id="the-github-app-preflight-failed-transiently">3519<h3 id="the-github-app-preflight-failed-transiently">

3496 GitHub 앱 사전 점검이 일시적으로 실패함3520 GitHub App 사전 확인이 일시적으로 실패함

3497</h3>3521</h3>

3498 3522

3499로컬 저장소에서 [클라우드 세션](/docs/ko/claude-code-on-the-web)을 시작했고 두 단계가 함께 실패했습니다. Claude Code가 저장소 번들을 구축하거나 업로드할 수 없습니다. 업로드 전에 클라우드 서비스가 GitHub에서 저장소를 클론할 수 있는지 확인했고 명확한 답변 대신 재시도가 지울 수 있는 오류로 끝났습니다. 예를 들어 네트워크 오류, 타임아웃 또는 임시 서버 오류입니다. 전체 메시지는 번들을 중지한 것으로 시작합니다. 예를 들어 `Could not upload repo bundle (<error>)`이고 사전 점검 문장으로 끝납니다:3523로컬 저장소에서 [클라우드 세션](/docs/ko/claude-code-on-the-web)을 시작했는데 두 단계가 함께 실패한 경우입니다. Claude Code가 저장소 번들을 빌드하거나 업로드할 수 없었습니다. 업로드 전에 Claude Code는 클라우드 서비스가 GitHub에서 저장소를 클론할 수 있는지 확인했는데, 이 확인이 명확한 답 대신 네트워크 오류, 타임아웃, 일시적인 서버 오류처럼 재시도로 해결될 수 있는 오류로 끝났습니다. 전체 메시지는 `Could not upload repo bundle (<error>)`처럼 번들을 막은 원인으로 시작하며 사전 확인 문장으로 끝납니다:

3500 3524

3501```text theme={null}3525```text theme={null}

3502Could not upload repo bundle (<error>). The GitHub App preflight failed transiently (network or service hiccup) — retry in a moment to start from GitHub instead3526Could not upload repo bundle (<error>). The GitHub App preflight failed transiently (network or service hiccup) — retry in a moment to start from GitHub instead

3503```3527```

3504 3528

3505**해야 할 일:**3529**조치 방법:**

3506 3530

3507* 잠시 후 명령어를 다시 실행합니다. GitHub 확인이 통과하면 Claude Code는 GitHub 클론에서 세션을 시작할 수 있으므로 실패한 업로드가 더 이상 시작을 차단하지 않습니다.3531* 잠시 후 명령을 다시 실행합니다. GitHub 확인이 통과하면 Claude Code가 GitHub 클론에서 세션을 시작할 수 있으므로, 실패한 업로드가 더 이상 실행을 막지 않습니다

3508* 재시도가 계속 실패하면 메시지의 시작이 업로드를 중지한 것을 이름 지정합니다. 수정할 수 있는 원인이 있으면 수정하여 세션이 대신 로컬 저장소에서 시작할 수 있습니다.3532* 재시도가 계속 실패하면 메시지의 시작 부분에 업로드를 막은 원인이 표시됩니다. 수정할 수 있는 원인이라면 이를 수정하여 대신 로컬 저장소에서 세션이 시작되도록 합니다

3509 3533

3510v2.1.251 이전에는 Claude Code가 GitHub 확인이 일시적으로만 실패했을 때도 `Please set up GitHub on https://claude.ai/code`로 메시지를 끝냈고 설정 조언은 일시적 실패를 지울 수 없습니다.3534v2.1.251 이전에는 GitHub 확인이 일시적으로만 실패한 경우에도 Claude Code가 메시지를 `Please set up GitHub on https://claude.ai/code`로 끝냈으며, 설정 안내로는 일시적인 실패를 해결할 수 없었습니다.

3511 3535

3512<h3 id="the-repository-upload-cant-follow-a-git-setting">3536<h3 id="the-repository-upload-cant-follow-a-git-setting">

3513 저장소 업로드가 git 설정을 따를 수 없음3537 저장소 업로드가 git 설정을 따를 수 없음

3514</h3>3538</h3>

3515 3539

3516[로컬 저장소를 업로드하는 클라우드 세션](/docs/ko/claude-code-on-the-web#send-local-repositories-without-github)을 시작했거나 [분기의 ultrareview](/docs/ko/ultrareview)를 시작했고 업로드가 파일에 적용할 속성 규칙을 결정하는 git 설정을 따를 수 없습니다. 업로드가 진행되고 규칙을 놓쳤다면 git이 저장하기 전에 변환하는 파일(예: 깨끗한 필터가 암호화하는 파일)이 디스크에 있는 그대로 클라우드에 도달할 수 있습니다. Claude Code는 대신 업로드를 거부하고 아무것도 업로드되지 않습니다:3540[로컬 저장소를 업로드하는 클라우드 세션](/docs/ko/claude-code-on-the-web#send-local-repositories-without-github) 또는 브랜치의 [ultrareview](/docs/ko/ultrareview)를 시작했는데, 파일에 적용할 속성 규칙을 결정하는 git 설정 중 하나를 업로드가 따를 수 없는 경우입니다. 업로드를 진행하면서 규칙을 놓치면, clean 필터가 암호화하는 파일처럼 git이 저장하기 전에 변환하는 파일이 디스크에 있는 그대로 클라우드에 전송될 수 있습니다. Claude Code는 대신 업로드를 거부하며 아무것도 업로드되지 않습니다:

3517 3541

3518```text theme={null}3542```text theme={null}

3519Not uploading this working tree: core.ignoreCase (which decides whether .gitattributes patterns match file names regardless of letter case) is set in <file>, and the upload cannot follow that setting, so a file git would change before storing it (to encrypt it, for example) could be uploaded as it is on disk. Move the core.ignoreCase line into this repository's .git/config or directly into your ~/.gitconfig, then retry.3543Not uploading this working tree: core.ignoreCase (which decides whether .gitattributes patterns match file names regardless of letter case) is set in <file>, and the upload cannot follow that setting, so a file git would change before storing it (to encrypt it, for example) could be uploaded as it is on disk. Move the core.ignoreCase line into this repository’s .git/config or directly into your ~/.gitconfig, then retry.

3520```3544```

3521 3545

3522메시지는 설정과 설정된 위치를 이름 지정하고 히트한 경우에 대한 수정으로 끝납니다. 동일한 거부는 `core.attributesFile` 및 `attr.tree`에 대해 나타나며 각각 자체 수정이 있습니다.3546메시지에는 설정과 설정된 위치가 표시되며, 해당하는 경우에 맞는 해결 방법으로 끝납니다. 같은 거부가 `core.attributesFile`과 `attr.tree`에 대해서도 각각의 해결 방법과 함께 나타납니다.

3523 3547

3524메시지는 해당 지시문의 조건이 이 저장소에 적용되지 않을 때도 `include` 또는 `includeIf` 지시문을 통해 git 구성이 끌어오는 구성 파일을 이름 지정할 수 있습니다.3548메시지에는 git 구성이 `include` 또는 `includeIf` 지시문을 통해 가져오는 설정 파일이 표시될 수 있으며, 해당 지시문의 조건이 이 저장소에 적용되지 않는 경우에도 마찬가지입니다.

3525 3549

3526**해야 할 일:**3550**조치 방법:**

3527 3551

3528* 메시지의 최종 문장에서 수정을 적용합니다.3552* 메시지의 마지막 문장에 있는 해결 방법을 적용합니다

3529 3553

3530<h3 id="github-isnt-connected-to-your-claude-account">3554<h3 id="github-isnt-connected-to-your-claude-account">

3531 GitHub가 Claude 계정에 연결되지 않음3555 GitHub가 Claude 계정에 연결되지 않음

3532</h3>3556</h3>

3533 3557

3534로컬 저장소에서 [클라우드 세션](/docs/ko/claude-code-on-the-web)을 시작했습니다. 예를 들어 `/autofix-pr`을 사용합니다. GitHub 계정이 Claude 계정에 연결되지 않았거나 연결이 만료되었으므로 Claude Code는 시작을 거부합니다:3558`/autofix-pr` 등으로 로컬 저장소에서 [클라우드 세션](/docs/ko/claude-code-on-the-web)을 시작한 경우입니다. Claude 계정에 연결된 GitHub 계정이 없거나 연결이 만료되었으므로 Claude Code가 실행을 거부합니다:

3535 3559

3536```text theme={null}3560```text theme={null}

3537GitHub isn't connected to your Claude account, so this repository can't be cloned in the cloud. Run /web-setup to connect with your GitHub CLI login, or connect on the web at https://claude.ai/connect-github3561GitHub isn't connected to your Claude account, so this repository can't be cloned in the cloud. Run /web-setup to connect with your GitHub CLI login, or connect on the web at https://claude.ai/connect-github

3538```3562```

3539 3563

3540[`/schedule`](/docs/ko/routines)로 루틴을 만들 때 동일한 메시지가 저장소를 이름 지정하는 설정 메모로 나타납니다. 메모는 루틴 만들기를 차단하지 않습니다.3564[`/schedule`](/docs/ko/routines)로 루틴을 만들 때는 같은 메시지가 저장소 이름이 포함된 설정 안내로 나타나며, 이 안내는 루틴 생성을 막지 않습니다.

3541 3565

3542**해야 할 일:**3566**조치 방법:**

3543 3567

3544* `/web-setup`을 실행하여 GitHub CLI 로그인을 Claude 계정에 연결하거나 [claude.ai/connect-github](https://claude.ai/connect-github)에서 계정을 연결합니다. [GitHub 인증 옵션](/docs/ko/claude-code-on-the-web#github-authentication-options)을 참조하여 두 가지가 어떻게 다른지 확인합니다.3568* `/web-setup`을 실행하여 GitHub CLI 로그인을 Claude 계정에 연결하거나, [claude.ai/connect-github](https://claude.ai/connect-github)에서 계정을 연결합니다. 두 방법의 차이점은 [GitHub 인증 옵션](/docs/ko/claude-code-on-the-web#github-authentication-options)을 참조하세요.

3545* 연결 후 1분 후 명령어를 다시 실행합니다.3569* 연결하고 1분 정도 지난 후 명령을 다시 실행합니다

3546 3570

3547v2.1.268 이전에는 Claude Code가 이를 Claude GitHub 앱 확인의 임시 실패로 보고했고 재시도하거나 앱을 설치하도록 제안했습니다. 둘 다 GitHub 계정을 연결하지 않습니다.3571v2.1.268 이전에는 Claude Code가 이를 Claude GitHub App 확인의 일시적인 실패로 보고하고 재시도하거나 앱을 설치하도록 제안했지만, 둘 다 GitHub 계정을 연결하지 않습니다.

3548 3572

3549<h3 id="single-sign-on-authorization-needed">3573<h3 id="single-sign-on-authorization-needed">

3550 싱글 사인온 인증 필요3574 싱글 사인온 인가 필요

3551</h3>3575</h3>

3552 3576

3553[`/install-github-app`](/docs/ko/github-actions#quick-setup)을 실행했고 SAML 싱글 사인온을 적용하는 조직의 저장소를 선택했습니다. 설정 전에 Claude Code는 GitHub CLI로 저장소에 대한 액세스를 확인하고 GitHub는 `gh` 토큰이 아직 조직에 대해 인증되지 않았기 때문에 해당 확인을 거부했습니다. 마법사는 인증 단계와 함께 경고를 표시합니다:3577[`/install-github-app`](/docs/ko/github-actions#quick-setup)을 실행하고 SAML 싱글 사인온을 적용하는 조직의 저장소를 선택한 경우입니다. 설정 전에 Claude Code는 GitHub CLI로 저장소에 대한 접근 권한을 확인하는데, `gh` 토큰이 아직 해당 조직에 대해 인가되지 않아 GitHub가 이 확인을 거부했습니다. 마법사는 인가 절차와 함께 경고를 표시합니다:

3554 3578

3555```text theme={null}3579```text theme={null}

3556Single sign-on authorization needed3580Single sign-on authorization needed

3557<owner>/<repo> belongs to an organization that enforces SAML single sign-on, and your GitHub CLI token isn't authorized for it yet.3581<owner>/<repo> belongs to an organization that enforces SAML single sign-on, and your GitHub CLI token isn't authorized for it yet.

3558```3582```

3559 3583

3560**해야 할 일:**3584**조치 방법:**

3561 3585

3562* `gh auth refresh -h github.com -s repo,workflow`를 실행하여 GitHub CLI 로그인을 `repo` 및 `workflow` 범위로 다시 인증하고 GitHub가 싱글 사인온을 요청할 때 조직을 인증합니다.3586* `gh auth refresh -h github.com -s repo,workflow`를 실행하여 `repo` 및 `workflow` 범위로 GitHub CLI 로그인을 다시 인가하고, GitHub가 싱글 사인온을 요청하면 조직을 인가합니다

3563* `GH_TOKEN`에서 개인 액세스 토큰으로 인증하면 [github.com/settings/tokens](https://github.com/settings/tokens)를 열고 토큰에서 **Configure SSO**를 선택하고 조직을 인증합니다.3587* `GH_TOKEN`의 개인 액세스 토큰으로 인증하는 경우 [github.com/settings/tokens](https://github.com/settings/tokens)를 열고 토큰에서 **Configure SSO**를 선택한 후 조직을 인가합니다

3564* `/install-github-app`을 다시 실행합니다.3588* `/install-github-app`을 다시 실행합니다

3565 3589

3566v2.1.273 이전에는 Claude Code가 이 조건에 대해 `Admin permissions required` 경고를 표시했습니다.3590v2.1.273 이전에는 이 상황에서 Claude Code가 대신 `Admin permissions required` 경고를 표시했습니다.

3567 3591

3568<h3 id="failed-to-resume-the-conversation">3592<h3 id="failed-to-resume-the-conversation">

3569 대화를 재개하지 못함3593 대화를 재개하지 못함

3570</h3>3594</h3>

3571 3595

3572Claude Code가 [`claude --resume` 선택기](/docs/ko/sessions#use-the-session-picker)에서 선택한 세션의 저장된 기록을 읽거나 처리할 수 없으므로 부분적으로 로드된 상태에서 계속하는 대신 프로세스를 종료합니다. 메시지는 재시도 명령어를 포함합니다:3596Claude Code가 [`claude --resume` 선택기](/docs/ko/sessions#use-the-session-picker)에서 선택한 세션의 저장된 트랜스크립트를 읽거나 처리할 수 없으므로, 부분적으로 로드된 상태로 계속하는 대신 프로세스를 종료합니다. 메시지에는 재시도할 명령이 포함됩니다:

3573 3597

3574```text theme={null}3598```text theme={null}

3575Failed to resume the conversation.3599Failed to resume the conversation.

3576Run claude --resume <session-id> to retry, or claude to start a new session.3600Run claude --resume <session-id> to retry, or claude to start a new session.

3577```3601```

3578 3602

3579Claude Code는 메시지를 표시한 후 코드 1로 종료됩니다. 실행 중인 세션 내의 `/resume` 선택기는 대화에서 `Failed to resume conversation`을 보고하고 현재 세션은 계속 실행됩니다. v2.1.216 이전에는 `claude --resume` 선택기에서 실패한 재개가 `Resuming conversation…` 스피너에 무한정 머물렀습니다.3603Claude Code는 메시지를 표시한 후 코드 1로 종료됩니다. 실행 중인 세션 내의 `/resume` 선택기는 대신 대화에 `Failed to resume conversation`을 보고하며, 현재 세션은 계속 실행됩니다. v2.1.216 이전에는 `claude --resume` 선택기에서 재개에 실패하면 이 메시지를 표시하는 대신 `Resuming conversation…` 스피너에 무한정 머물렀습니다.

3580 3604

3581**해야 할 일:**3605**조치 방법:**

3582 3606

3583* 메시지의 세션 ID로 `claude --resume <session-id>`를 실행하여 재시도합니다.3607* 메시지의 세션 ID로 `claude --resume <session-id>`를 실행하여 재시도합니다

3584* 모든 재시도가 같은 방식으로 실패하면 `claude update`를 실행하고 다시 재개합니다. v2.1.275 이전의 버전은 저장된 기록에 읽을 수 없는 항목이 포함되어 있을 때 재개에 실패합니다.3608* 모든 재시도가 같은 방식으로 실패하면 `claude update`를 실행하고 다시 재개합니다. v2.1.275 이전 버전은 저장된 트랜스크립트에 읽을 수 없는 항목이 있으면 재개에 실패합니다.

3585* 재시도가 다시 실패하면 `claude`를 실행하여 새 세션을 시작합니다.3609* 재시도가 다시 실패하면 `claude`를 실행하여 새 세션을 시작합니다

3586 3610

3587<h3 id="no-conversation-found-with-the-session-id">3611<h3 id="no-conversation-found-with-the-session-id">

3588 세션 ID와 일치하는 대화를 찾을 수 없음3612 세션 ID에 해당하는 대화를 찾을 수 없음

3589</h3>3613</h3>

3590 3614

3591`claude --resume <session-id>`에 세션 ID를 전달했고 저장된 기록이 일치하지 않습니다:3615`claude --resume <session-id>`에 세션 ID를 전달했지만 일치하는 저장된 트랜스크립트가 없는 경우입니다:

3592 3616

3593```text theme={null}3617```text theme={null}

3594No conversation found with session ID: <session-id>3618No conversation found with session ID: <session-id>

3595```3619```

3596 3620

3597Claude Code는 메시지를 표시한 후 코드 1로 종료됩니다. Claude Code는 [현재 프로젝트를 먼저 검색한 후 이 머신의 다른 모든 프로젝트를 검색](/docs/ko/sessions#resume-a-session)합니다. v2.1.223 이전에는 조회가 현재 프로젝트 디렉토리와 git worktree에서 중지되었으므로 세션이 마지막으로 작동한 디렉토리에서 재개합니다.3621Claude Code는 메시지를 표시한 후 코드 1로 종료됩니다. Claude Code는 [현재 프로젝트를 먼저 검색한 다음 이 머신의 다른 모든 프로젝트](/docs/ko/sessions#resume-a-session)에서 ID를 검색합니다. v2.1.223 이전에는 현재 프로젝트 디렉터리와 그 git worktree에서만 검색했으므로, 세션이 마지막으로 작업한 디렉터리에서 재개해야 했습니다.

3598 3622

3599일반적인 원인:3623일반적인 원인:

3600 3624

3601* **잘못된 ID**: 비대화형 실행의 경우 ID는 [`--output-format json` 출력](/docs/ko/headless#get-structured-output)의 `session_id` 필드입니다.3625* **잘못 입력한 ID**: 비대화형 실행의 경우 ID는 [`--output-format json` 출력](/docs/ko/headless#get-structured-output)의 `session_id` 필드입니다

3602* **삭제된 기록**: Claude Code는 [보존 기간](/docs/ko/sessions#where-transcripts-are-stored) 후 기록을 제거합니다. 기본값은 30일이며 [보존 스윕 규칙](/docs/ko/claude-directory#cleaned-up-automatically)을 따릅니다.3626* **삭제된 트랜스크립트**: Claude Code는 [보존 정리 규칙](/docs/ko/claude-directory#cleaned-up-automatically)에 따라 [보존 기간](/docs/ko/sessions#where-transcripts-are-stored)(기본값 30일)이 지나면 트랜스크립트를 제거합니다

3603* **다른 머신**: Claude Code는 기록을 로컬로 저장하므로 세션이 실행된 머신에서 재개합니다.3627* **다른 머신**: Claude Code는 트랜스크립트를 로컬에 저장하므로 세션이 실행된 머신에서 재개해야 합니다

3604* **중복 복사본**: `~/.claude/projects` 아래에 프로젝트 디렉토리를 복사했으므로 두 기록이 동일한 ID를 가지면 Claude Code는 이 메시지를 보고하고 임의로 하나의 복사본을 재개하지 않습니다.3628* **중복 사본**: `~/.claude/projects` 아래의 프로젝트 디렉터리를 복사하여 두 트랜스크립트가 같은 ID를 갖게 되면, Claude Code는 임의로 한 사본을 재개하는 대신 이 메시지를 보고합니다

3605 3629

3606**해야 할 일:**3630**조치 방법:**

3607 3631

3608* 대화형 세션의 경우 `claude --resume`으로 [세션 선택기](/docs/ko/sessions#use-the-session-picker)를 열고 `Ctrl+A`를 눌러 이 머신의 모든 프로젝트로 확장한 후 세션을 선택합니다.3632* 대화형 세션의 경우 `claude --resume`으로 [세션 선택기](/docs/ko/sessions#use-the-session-picker)를 열고 `Ctrl+A`를 눌러 이 머신의 모든 프로젝트로 범위를 넓힌 후 세션을 선택합니다

3609* `claude -p` 또는 [Agent SDK](/docs/ko/agent-sdk/overview)로 만든 세션은 선택기에 나타나지 않으므로 원래 실행이 출력한 `session_id`에 대해 ID를 다시 확인합니다.3633* `claude -p` 또는 [Agent SDK](/docs/ko/agent-sdk/overview)로 만든 세션은 선택기에 나타나지 않으므로, 원래 실행에서 출력된 `session_id`와 ID를 다시 대조합니다

3610 3634

3611<h3 id="windows-reported-an-error-ebadf">3635<h3 id="windows-reported-an-error-ebadf">

3612 Windows가 이 세션의 기록 파일을 읽을 때 오류를 보고함 (EBADF)3636 Claude Code가 이 세션의 트랜스크립트 파일을 읽을 때 Windows에서 오류(EBADF)를 보고했습니다

3613</h3>3637</h3>

3614 3638

3615Windows에서 세션을 재개했고 저장된 [기록 파일](/docs/ko/sessions#where-transcripts-are-stored)이 정상적으로 열렸으며 읽기가 EBADF 시스템 오류로 실패했습니다. 시스템 오류는 읽기가 실패한 이유를 말하지 않으므로 메시지는 가능한 원인과 시도할 것을 제안합니다:3639Windows에서 세션을 재개했을 때 저장된 [트랜스크립트 파일](/docs/ko/sessions#where-transcripts-are-stored)은 정상적으로 열렸지만, 이를 읽는 과정에서 시스템 오류 EBADF로 실패한 경우입니다. 시스템 오류는 읽기에 실패한 이유를 알려 주지 않으므로, 메시지는 가능성 있는 원인과 시도해 볼 방법을 제시합니다:

3616 3640

3617```text theme={null}3641```text theme={null}

3618Windows reported an error (EBADF) when Claude Code read this session's transcript file, although the file had opened normally. This can happen when other software intercepts file reads — security, encryption or endpoint-management tools, for example. If it keeps happening for this conversation, try excluding the folder that holds Claude Code's session transcripts from such software (the .claude folder in your user profile, unless the app or CLAUDE_CONFIG_DIR points Claude Code elsewhere), or adding Claude Code to its allowed applications, then resume again.3642Windows reported an error (EBADF) when Claude Code read this session's transcript file, although the file had opened normally. This can happen when other software intercepts file reads — security, encryption or endpoint-management tools, for example. If it keeps happening for this conversation, try excluding the folder that holds Claude Code's session transcripts from such software (the .claude folder in your user profile, unless the app or CLAUDE_CONFIG_DIR points Claude Code elsewhere), or adding Claude Code to its allowed applications, then resume again.

3619```3643```

3620 3644

3621메시지는 명령어의 자체 실패 줄을 따릅니다. 예를 들어 `Failed to resume session <session-id>`. `claude --resume` 또는 [`claude -p`](/docs/ko/headless) 명령어는 메시지를 표시한 후 코드 1로 종료됩니다. `/resume` 후 실행 중인 세션 내에서 현재 세션은 계속 실행됩니다.3645이 메시지는 `Failed to resume session <session-id>`와 같은 명령 자체의 실패 줄 다음에 표시됩니다. `claude --resume` 또는 [`claude -p`](/docs/ko/headless) 명령은 이 메시지를 표시한 후 코드 1로 종료됩니다. 세션 내에서 `/resume`을 실행한 경우에는 현재 세션이 계속 실행됩니다.

3622 3646

3623**해야 할 일:**3647**해결 방법:**

3624 3648

3625* 보안, 암호화 또는 엔드포인트 관리 도구 같은 파일 읽기를 스캔하거나 가로채는 소프트웨어에서 기록을 보유하는 폴더를 제외합니다. 기록은 기본적으로 `%USERPROFILE%\.claude\projects` 아래에 있거나 [`CLAUDE_CONFIG_DIR`](/docs/ko/env-vars)이 이름 지정하는 디렉토리 아래에 있습니다.3649* 보안, 암호화 또는 엔드포인트 관리 도구와 같이 파일 읽기를 검사하거나 가로채는 소프트웨어에서 세션 트랜스크립트가 저장된 폴더를 제외합니다. 트랜스크립트는 기본적으로 `%USERPROFILE%\.claude\projects` 아래에 저장되며, [`CLAUDE_CONFIG_DIR`](/docs/ko/env-vars)이 지정된 경우 해당 디렉터리 아래에 저장됩니다

3626* 제외를 추가할 수 없으면 대신 해당 소프트웨어의 허용된 애플리케이션에 Claude Code를 추가합니다.3650* 제외 항목을 추가할 수 없다면 대신 해당 소프트웨어의 허용된 애플리케이션에 Claude Code를 추가합니다

3627* 세션을 다시 재개합니다.3651* 세션을 다시 재개합니다

3628 3652

3629v2.1.282 이전에는 실패가 설명 없이 나타났습니다: `claude --resume <session-id>`는 `Failed to resume session <session-id>`에서 끝났고 `-p` 실행은 `Failed to resume session: EBADF: bad file descriptor, read` 같은 시스템 오류 텍스트만 출력했습니다.3653v2.1.282 이전에는 이 실패가 아무런 설명 없이 발생했습니다. `claude --resume <session-id>`는 `Failed to resume session <session-id>`로 종료되었고, `-p` 실행은 `Failed to resume session: EBADF: bad file descriptor, read`와 같은 시스템 오류 텍스트만 출력했습니다.

3630 3654

3631<h3 id="cannot-switch-renderers-in-this-session">3655<h3 id="cannot-switch-renderers-in-this-session">

3632 이 세션에서 렌더러를 전환할 수 없음3656 Cannot switch renderers in this session

3633</h3>3657</h3>

3634 3658

3635렌더러를 전환하면 Claude Code가 프로세스를 다시 시작합니다. [`/tui`](/docs/ko/fullscreen#enable-fullscreen-rendering)를 Claude Code가 다시 시작하기를 거부하는 세션에서 실행했으므로 전환하지 않고 아무것도 저장하지 않습니다. 어떤 메시지를 보는지는 원인을 알려줍니다:3659렌더러를 전환하면 Claude Code는 프로세스를 다시 시작합니다. Claude Code가 다시 시작을 거부하는 세션에서 [`/tui`](/docs/ko/fullscreen#enable-fullscreen-rendering)를 실행했기 때문에 전환되지 않았고 아무것도 저장되지 않았습니다. 표시되는 메시지를 보면 원인을 알 수 있습니다:

~~3636~~

3637* `Cannot switch renderers while work is running in the background`: 백그라운드 셸 또는 하위 에이전트 같은 재시작이 중단할 백그라운드 작업이 실행 중입니다. [`/tasks`](/docs/ko/commands)로 작업이 완료될 때까지 기다리거나 중지한 후 `/tui fullscreen` 또는 `/tui default`를 다시 실행합니다.

3638*

3639 3660

3640`Cannot switch renderers in this session`: 세션에 Claude Code가 다시 시작된 프로세스로 전달할 수 없는 제한이 있습니다. v2.1.234 이전에는 Claude Code가 어쨌든 다시 시작했고 다시 시작된 세션이 제한 없이 실행되었습니다.3661* `Cannot switch renderers while work is running in the background`: 백그라운드 셸이나 서브에이전트처럼 다시 시작하면 중단될 백그라운드 작업이 실행 중입니다. 작업이 끝날 때까지 기다리거나 [`/tasks`](/docs/ko/commands)로 작업을 중지한 다음 `/tui fullscreen` 또는 `/tui default`를 다시 실행합니다

3662* `Cannot switch renderers in this session`: 세션에 Claude Code가 다시 시작된 프로세스로 전달할 수 없는 제한 사항이 있습니다. v2.1.234 이전에는 Claude Code가 그래도 다시 시작했으며, 다시 시작된 세션은 해당 제한 사항 없이 실행되었습니다

3641 3663

3642제한 메시지에서 괄호 안의 부분은 Claude Code가 찾은 제한을 이름 지정합니다:3664제한 사항 메시지에서 괄호 안의 부분은 Claude Code가 발견한 제한 사항을 나타냅니다:

3643 3665

3644```text theme={null}3666```text theme={null}

3645Cannot switch renderers in this session — it has restrictions a restart can't carry over (permission rules set for this session only). Nothing was changed. Running /tui fullscreen in a session started without them switches every later session too.3667Cannot switch renderers in this session — it has restrictions a restart can't carry over (permission rules set for this session only). Nothing was changed. Running /tui fullscreen in a session started without them switches every later session too.

3646```3668```

3647 3669

3648메시지가 괄호 안에 표시할 수 있는 각 이유:3670메시지의 괄호 안에 표시될 수 있는 각 이유는 다음과 같습니다:

3649 3671

3650* `launch flags: a custom system prompt, a tool allowlist, or restricted settings`: Claude Code가 다시 시작된 프로세스로 전달하지 않는 플래그로 세션을 시작했습니다. 이러한 플래그에는 [`--system-prompt`](/docs/ko/cli-reference#cli-flags), `--system-prompt-file`, `--append-system-prompt-file`, [`--tools`](/docs/ko/cli-reference#cli-flags) 허용 목록, [`--setting-sources`](/docs/ko/cli-reference#cli-flags) 및 [`--permission-prompt-tool`](/docs/ko/cli-reference#cli-flags)이 포함됩니다.3672* `launch flags: a custom system prompt, a tool allowlist, or restricted settings`: Claude Code가 다시 시작된 프로세스로 다시 전달하지 않는 플래그로 세션을 시작했습니다. 이러한 플래그에는 [`--system-prompt`](/docs/ko/cli-reference#cli-flags), `--system-prompt-file`, `--append-system-prompt-file`, [`--tools`](/docs/ko/cli-reference#cli-flags) 허용 목록, [`--setting-sources`](/docs/ko/cli-reference#cli-flags), [`--permission-prompt-tool`](/docs/ko/cli-reference#cli-flags)이 포함됩니다

3651* `permission rules set for this session only`: 훅 또는 SDK 호출자의 [권한 업데이트](/docs/ko/hooks#permission-update-entries)가 `session` 대상으로 거부 또는 요청 규칙을 추가했습니다. 세션 범위 허용 규칙은 거부를 트리거하지 않습니다. 재시작이 이를 제거하고 Claude Code가 대신 다시 프롬프트합니다.3673* `permission rules set for this session only`: 훅 또는 SDK 호출자의 [권한 업데이트](/docs/ko/hooks#permission-update-entries)가 `session` 대상으로 거부 또는 확인 규칙을 추가했습니다. 세션 범위의 허용 규칙은 거부를 유발하지 않습니다. 다시 시작하면 해당 규칙이 삭제되며, Claude Code는 대신 다시 확인을 요청합니다

3652* `ask-before-running rules with no command-line form`: 훅 또는 SDK 호출자의 권한 업데이트가 Claude Code가 `--allowed-tools` 및 `--disallowed-tools`로 전달하는 규칙과 함께 요청 규칙을 추가했습니다. 요청 규칙에 대한 플래그는 없습니다.3674* `ask-before-running rules with no command-line form`: 훅 또는 SDK 호출자의 권한 업데이트가 Claude Code가 `--allowed-tools` 및 `--disallowed-tools`로 다시 전달하는 규칙과 함께 확인 규칙을 추가했습니다. 확인 규칙에 해당하는 플래그는 없습니다

3653* `permission rules a command line cannot carry intact` 및 `added directories a command line cannot carry intact`: 권한 업데이트가 세션 중간에 규칙 또는 디렉토리 경로를 추가했습니다. 다시 시작된 프로세스의 명령줄이 텍스트를 동일한 값으로 전달할 수 없습니다.3675* `permission rules a command line cannot carry intact` 및 `added directories a command line cannot carry intact`: 권한 업데이트가 세션 도중에 규칙 또는 디렉터리 경로를 추가했습니다. 다시 시작된 프로세스의 명령줄은 해당 텍스트를 동일한 값으로 전달할 수 없습니다

3654 3676

3655**해야 할 일:**3677**해결 방법:**

3656 3678

3657* 이러한 제한 없이 시작된 세션에서 `/tui fullscreen` 또는 `/tui default`를 실행하여 다시 전환합니다. Claude Code는 [`tui` 설정](/docs/ko/settings-reference#tui)을 거기에 저장합니다.3679* 해당 제한 사항 없이 시작된 세션에서 `/tui fullscreen`을 실행하거나, 다시 되돌리려면 `/tui default`를 실행합니다. Claude Code는 해당 세션에서 [`tui` 설정](/docs/ko/settings-reference#tui)을 저장합니다

3658 3680

3659<h3 id="couldnt-open-claude-desktop">3681<h3 id="couldnt-open-claude-desktop">

3660 Claude Desktop을 열 수 없음3682 Claude Desktop을 열 수 없습니다

3661</h3>3683</h3>

3662 3684

3663[`/desktop`](/docs/ko/desktop#coming-from-the-cli) 또는 그 별칭 `/app`을 실행했거나 [`claude --desktop`](/docs/ko/cli-reference#cli-flags)을 셸에서 실행했고 Claude Code가 Claude Desktop을 열기 위해 사용하는 시스템 명령어가 실패했습니다. `/desktop` 후 세션은 터미널에 남아 있습니다. `claude --desktop`은 메시지를 `Error:` 접두사 없이 출력하고 상태 1로 종료됩니다.3685세션에서 [`/desktop`](/docs/ko/desktop#coming-from-the-cli) 또는 그 별칭인 `/app`을 실행했거나 셸에서 [`claude --desktop`](/docs/ko/cli-reference#cli-flags)을 실행했는데, Claude Code가 Claude Desktop을 여는 데 사용하는 시스템 명령이 실패한 경우입니다. `/desktop` 실행 후에는 세션이 터미널에 그대로 유지되며, `claude --desktop`은 `Error:` 접두사 없이 메시지를 출력하고 상태 1로 종료됩니다.

3664 3686

3665괄호의 텍스트는 실패한 명령어를 이름 지정합니다. 종료 상태와 첫 번째 오류 출력 줄이 있으면 함께 표시됩니다. macOS에서 해당 명령어는 `open`입니다. 이 예와 같이 Windows에서는 `rundll32`입니다:3687괄호 안의 텍스트는 실패한 명령을 나타내며, 해당 명령이 종료 상태와 오류 출력을 생성한 경우 종료 상태와 오류 출력의 첫 번째 줄도 함께 표시됩니다. macOS에서는 이 예시처럼 해당 명령이 `open`이고, Windows에서는 `rundll32`입니다:

3666 3688

3667```text theme={null}3689```text theme={null}

3668Error: Couldn't open Claude Desktop (`open` exited 1: LSOpenURLsWithRole() failed for the URL claude://resume?session=<session-id> with error -10814). Open Claude Desktop and try again.3690Error: Couldn't open Claude Desktop (`open` exited 1: LSOpenURLsWithRole() failed for the URL claude://resume?session=<session-id> with error -10814). Open Claude Desktop and try again.

3669```3691```

3670 3692

3671**해야 할 일:**3693**해결 방법:**

3672 3694

3673* Claude Desktop을 직접 열고 `/desktop` 또는 `claude --desktop`을 다시 실행합니다.3695* Claude Desktop을 직접 연 다음 `/desktop` 또는 `claude --desktop`을 다시 실행합니다

3674* 실패한 명령어의 전체 오류 출력을 읽으려면 `/debug`로 디버그 로깅을 켜고 `/desktop`을 다시 실행하거나 `claude --desktop --debug-file <path>`를 실행한 후 디버그 로그를 확인합니다.3696* 실패한 명령의 전체 오류 출력을 확인하려면 `/debug`로 디버그 로깅을 켜고 `/desktop`을 다시 실행하거나, `claude --desktop --debug-file <path>`를 실행한 다음 디버그 로그를 확인합니다

3675 3697

3676v2.1.285 이전에는 메시지가 `Open Claude Desktop and run /desktop again.`으로 끝났습니다. v2.1.275 이전에는 `Failed to open Claude Desktop. Please try opening it manually.`였고 무엇이 실패했는지 말하지 않았습니다.3698v2.1.285 이전에는 메시지가 `Open Claude Desktop and run /desktop again.`으로 끝났습니다. v2.1.275 이전에는 메시지가 `Failed to open Claude Desktop. Please try opening it manually.`였으며 무엇이 실패했는지 알려 주지 않았습니다.

3677 3699

3678<h3 id="terminal-setup-left-your-zed-keymap-unchanged">3700<h3 id="terminal-setup-left-your-zed-keymap-unchanged">

3679 /terminal-setup이 Zed 키맵을 변경하지 않음3701 /terminal-setup이 Zed 키맵을 변경하지 않았습니다

3680</h3>3702</h3>

3681 3703

3682Zed에서 [`/terminal-setup`](/docs/ko/terminal-config#enter-multiline-prompts)을 실행했고 Claude Code가 Zed `keymap.json`에 대한 업데이트를 완료할 수 없어서 파일을 그대로 두었습니다.3704Zed에서 [`/terminal-setup`](/docs/ko/terminal-config#enter-multiline-prompts)을 실행했지만 Claude Code가 Zed `keymap.json` 업데이트를 완료할 수 없어 파일을 그대로 둔 경우입니다.

3683 3705

3684각 메시지는 키맵 경로를 이름 지정하고 직접 추가할 키바인딩 블록으로 끝납니다:3706각 메시지는 키맵 경로를 알려 주며, 직접 추가할 키보드 단축키 블록으로 끝납니다:

3685 3707

3686```text theme={null}3708```text theme={null}

3687Couldn't update your Zed keymap, so it was left unchanged.3709Couldn't update your Zed keymap, so it was left unchanged.

3689{ "context": "Terminal", "bindings": { "shift-enter": ["terminal::SendText", "\u001b\r"] } }3711{ "context": "Terminal", "bindings": { "shift-enter": ["terminal::SendText", "\u001b\r"] } }

3690```3712```

3691 3713

3692메시지의 첫 줄은 원인을 이름 지정합니다:3714메시지의 첫 번째 줄은 원인을 나타냅니다:

3693 3715

3694* `Couldn't read your Zed keymap, so it was left unchanged.`: Claude Code가 파일을 읽을 수 없습니다. 예를 들어 파일 권한 때문입니다.3716* `Couldn't read your Zed keymap, so it was left unchanged.`: 파일 권한 등의 이유로 Claude Code가 파일을 읽을 수 없었습니다

3695* `Your Zed keymap isn't a readable list of keybindings, so it was left unchanged.`: 파일이 잘 읽혔지만 `//` 주석 및 후행 쉼표가 허용되어도 키바인딩 블록 배열로 파싱되지 않습니다.3717* `Your Zed keymap isn't a readable list of keybindings, so it was left unchanged.`: 파일은 정상적으로 읽혔지만, `//` 주석과 후행 쉼표를 허용하더라도 키보드 단축키 블록의 배열로 파싱되지 않습니다

3696* `Couldn't back up your Zed keymap; not modifying it.`: Claude Code가 파일을 옆에 `.bak` 백업으로 복사할 수 없어서 아무것도 변경하지 않았습니다.3718* `Couldn't back up your Zed keymap; not modifying it.`: Claude Code가 파일을 같은 위치의 `.bak` 백업으로 복사할 수 없어 아무것도 변경하지 않았습니다

3697* `Couldn't update your Zed keymap, so it was left unchanged.`: 병합된 결과가 바인딩을 전달하는 유효한 키맵으로 확인되지 않아서 Claude Code가 쓰는 대신 버렸습니다. 중복된 키가 있는 키바인딩 블록이 이를 유발할 수 있습니다.3719* `Couldn't update your Zed keymap, so it was left unchanged.`: 병합된 결과가 해당 바인딩을 포함한 유효한 키맵으로 확인되지 않아 Claude Code가 파일에 쓰는 대신 결과를 폐기했습니다. 키가 중복된 키보드 단축키 블록이 원인일 수 있습니다

3698 3720

3699**해야 할 일:**3721**해결 방법:**

3700 3722

3701* 메시지의 블록을 메시지가 이름 지정하는 경로의 `keymap.json`의 최상위 배열에 복사합니다.3723* 메시지의 블록을 복사하여 메시지에 표시된 경로에 있는 `keymap.json`의 최상위 배열에 추가합니다

3702* `isn't a readable list of keybindings`의 경우 구문 오류를 수정하거나 파일의 최상위 값을 배열로 만든 후 `/terminal-setup`을 다시 실행합니다.3724* `isn't a readable list of keybindings`의 경우, 구문 오류를 수정하거나 파일의 최상위 값을 배열로 만든 다음 `/terminal-setup`을 다시 실행합니다

3703 3725

3704v2.1.247 이전에는 `/terminal-setup`이 `//` 주석 또는 후행 쉼표를 사용하는 Zed 키맵을 파싱할 수 없었고 전체 파일을 자신의 바인딩만으로 바꾸면서 바인딩이 설치되었다고 보고했습니다. 이전 버전이 바꾼 키맵을 복원하려면 [멀티라인 프롬프트 입력](/docs/ko/terminal-config#enter-multiline-prompts) 아래에 설명된 `.bak` 백업 파일을 사용합니다.3726v2.1.247 이전에는 `/terminal-setup`이 `//` 주석이나 후행 쉼표를 사용하는 Zed 키맵을 파싱할 수 없었으며, 바인딩이 설치되었다고 보고하면서 전체 파일을 자체 바인딩만으로 대체했습니다. 이전 버전에서 대체된 키맵을 복원하려면 [여러 줄 프롬프트 입력](/docs/ko/terminal-config#enter-multiline-prompts)에 설명된 `.bak` 백업 파일을 사용합니다.

3705 3727

3706<h3 id="skill-usage-reports-are-not-available-on-this-connection">3728<h3 id="skill-usage-reports-are-not-available-on-this-connection">

3707 스킬 사용 보고서는 이 연결에서 사용할 수 없음3729 Skill usage reports are not available on this connection

3708</h3>3730</h3>

3709 3731

3710[Remote Control](/docs/ko/remote-control)을 통해, 휴대폰 또는 브라우저에서 [`/skill-doctor`](/docs/ko/skills#find-unused-skills)를 실행했습니다. Claude Code는 Remote Control을 통해 스킬 사용 보고서를 보내지 않고 대신 이 메시지로 응답합니다:3732휴대폰이나 브라우저에서 [Remote Control](/docs/ko/remote-control)을 통해 [`/skill-doctor`](/docs/ko/skills#find-unused-skills)를 실행한 경우입니다. Claude Code는 스킬 사용 보고서를 Remote Control을 통해 전송하지 않으며, 대신 다음 메시지로 응답합니다:

3711 3733

3712```text theme={null}3734```text theme={null}

3713Skill usage reports are not available on this connection.3735Skill usage reports are not available on this connection.

3714```3736```

3715 3737

3716**해야 할 일:**3738**해결 방법:**

3717 3739

3718* 세션이 실행 중인 머신의 터미널에서 `/skill-doctor`를 실행하거나 거기서 `claude -p "/skill-doctor"`를 실행합니다.3740* 세션이 실행 중인 머신의 터미널에서 `/skill-doctor`를 실행하거나, 해당 머신에서 `claude -p "/skill-doctor"`를 실행합니다

3719 3741

3720<h3 id="custom-output-styles-cant-be-selected-over-remote-control">3742<h3 id="custom-output-styles-cant-be-selected-over-remote-control">

3721 사용자 정의 출력 스타일을 Remote Control을 통해 선택할 수 없음3743 사용자 지정 출력 스타일은 Remote Control을 통해 선택할 수 없습니다

3722</h3>3744</h3>

3723 3745

3724[Remote Control](/docs/ko/remote-control)을 통해 모바일 앱 또는 웹에서 [`/output-style`](/docs/ko/output-styles#change-your-output-style)을 실행했거나 명령어가 세션으로 릴레이된 메시지에 도착했습니다. 이러한 턴이 계정 소유자에게서 오지 않을 수 있으므로 Claude Code는 [기본 제공 스타일](/docs/ko/output-styles#built-in-output-styles)만 나열하고 선택하며 명령어가 스타일을 나열하거나 제공한 이름을 인식하지 못할 때마다 이 공지를 추가합니다. [사용자 정의 스타일](/docs/ko/output-styles#create-a-custom-output-style) 이름은 존재하지 않는 이름과 동일한 응답을 받습니다:3746[Remote Control](/docs/ko/remote-control)을 통해 모바일 앱이나 웹에서 [`/output-style`](/docs/ko/output-styles#change-your-output-style)을 실행했거나, 세션으로 전달된 메시지에 해당 명령이 포함된 경우입니다. 이러한 턴은 계정 소유자가 보낸 것이 아닐 수 있으므로, Claude Code는 해당 턴에서 [기본 제공 스타일](/docs/ko/output-styles#built-in-output-styles)만 나열하고 선택하며, 명령이 스타일을 나열하거나 입력한 이름을 인식하지 못할 때마다 이 안내를 추가합니다. [사용자 지정 스타일](/docs/ko/output-styles#create-a-custom-output-style) 이름에는 존재하지 않는 이름과 동일한 응답이 반환됩니다:

3725 3747

3726```text theme={null}3748```text theme={null}

3727Custom output styles can't be selected over Remote Control or from a relayed message. Select one in the session itself, or pick a built-in style here.3749Custom output styles can't be selected over Remote Control or from a relayed message. Select one in the session itself, or pick a built-in style here.

3728```3750```

3729 3751

3730**해야 할 일:**3752**해결 방법:**

3731 3753

3732* 기본 제공 스타일을 선택합니다. 예를 들어 `/output-style concise`.3754* 기본 제공 스타일을 선택합니다. 예: `/output-style concise`

3733* 사용자 정의 스타일을 사용하려면 프로젝트의 `.claude/settings.local.json`에서 [`outputStyle`](/docs/ko/settings-reference#outputstyle)을 설정하거나 세션 자체의 터미널에서 `/output-style <style>`을 실행합니다(있는 경우).3755* 사용자 지정 스타일을 사용하려면 프로젝트의 `.claude/settings.local.json`에서 [`outputStyle`](/docs/ko/settings-reference#outputstyle)을 설정하거나, 세션에 자체 터미널이 있는 경우 해당 터미널에서 `/output-style <style>`을 실행합니다

3734 3756

3735<h3 id="output-styles-are-saved-to-local-settings-which-this-session-doesnt-load">3757<h3 id="output-styles-are-saved-to-local-settings-which-this-session-doesnt-load">

3736 출력 스타일이 이 세션이 로드하지 않는 로컬 설정에 저장됨3758 출력 스타일은 이 세션이 로드하지 않는 로컬 설정에 저장됩니다

3737</h3>3759</h3>

3738 3760

3739이 세션의 설정 소스가 `local`을 제외하는 세션에서 `/output-style <style>` 또는 `/config outputStyle=<style>`으로 [출력 스타일](/docs/ko/output-styles)을 전환하려고 했습니다. 예를 들어 [`settingSources`](/docs/ko/agent-sdk/typescript#options)가 `"local"`을 생략하는 [Agent SDK](/docs/ko/agent-sdk/typescript) 세션과 [`--setting-sources`](/docs/ko/cli-reference#cli-flags) 값이 `local`을 생략하는 CLI 세션입니다. 두 명령어 모두 스타일을 `.claude/settings.local.json`에 저장합니다. 이러한 세션은 절대 다시 읽지 않으므로 Claude Code는 효과가 없을 설정을 쓰는 대신 거부합니다:3761설정 소스에서 `local`이 제외된 세션에서 `/output-style <style>` 또는 `/config outputStyle=<style>`로 [출력 스타일](/docs/ko/output-styles)을 전환하려고 한 경우입니다. 예를 들어 [`settingSources`](/docs/ko/agent-sdk/typescript#options)에서 `"local"`이 빠진 [Agent SDK](/docs/ko/agent-sdk/typescript) 세션과, `local`이 빠진 [`--setting-sources`](/docs/ko/cli-reference#cli-flags) 값으로 시작된 CLI 세션이 있습니다. 두 명령 모두 스타일을 `.claude/settings.local.json`에 저장하는데, 이러한 세션은 이 파일을 다시 읽지 않으므로 Claude Code는 효과가 없는 설정을 쓰는 대신 거부합니다:

3740 3762

3741```text theme={null}3763```text theme={null}

3742Output styles are saved to local settings (.claude/settings.local.json), which this session doesn't load, so the style can't be changed here.3764Output styles are saved to local settings (.claude/settings.local.json), which this session doesn't load, so the style can't be changed here.

3743```3765```

3744 3766

3745**해야 할 일:**3767**해결 방법:**

3746 3768

3747* 세션의 설정 소스에 `local`을 추가하고 다시 전환합니다.3769* 세션의 설정 소스에 `local`을 추가한 다음 다시 전환합니다

3748* 세션이 로드하는 설정 파일(예: 프로젝트의 `.claude/settings.json` 또는 `~/.claude/settings.json`)에서 [`outputStyle`](/docs/ko/settings-reference#outputstyle) 키를 설정합니다. TypeScript SDK에서 대신 인라인 `settings` 객체 내에서 `outputStyle`을 설정합니다. [출력 스타일 활성화](/docs/ko/agent-sdk/modifying-system-prompts#activate-an-output-style)를 참조하세요.3770* 프로젝트의 `.claude/settings.json` 또는 `~/.claude/settings.json`과 같이 세션이 로드하는 설정 파일에서 [`outputStyle`](/docs/ko/settings-reference#outputstyle) 키를 설정합니다. TypeScript SDK에서는 대신 인라인 `settings` 객체 안에 `outputStyle`을 설정합니다. [출력 스타일 활성화](/docs/ko/agent-sdk/modifying-system-prompts#activate-an-output-style)를 참조하세요

3749 3771

3750<h2 id="plugin-errors">3772<h2 id="plugin-errors">

3751 플러그인 오류3773 플러그인 오류

3858 3880

3859플러그인 훅, [모니터](/docs/ko/plugins/components#monitors) 또는 MCP [`headersHelper`](/docs/ko/mcp#use-dynamic-headers-for-custom-authentication) 명령이 `${user_config.KEY}` [플러그인 옵션](/docs/ko/plugins/manifest-reference#user-configuration)을 참조하며 대체된 문자열이 셸에 전달됩니다. 구성된 값에 `$(...)`, 백틱 또는 `;`이 포함되면 여기서 코드로 실행되므로 Claude Code는 값을 대체하는 대신 구성 요소를 시작하기를 거부합니다. 확인은 명령 템플릿에서 실행되므로 아직 값이 구성되지 않았을 때도 오류가 나타납니다. v2.1.207 이전에는 값이 셸 명령으로 대체되었습니다.3881플러그인 훅, [모니터](/docs/ko/plugins/components#monitors) 또는 MCP [`headersHelper`](/docs/ko/mcp#use-dynamic-headers-for-custom-authentication) 명령이 `${user_config.KEY}` [플러그인 옵션](/docs/ko/plugins/manifest-reference#user-configuration)을 참조하며 대체된 문자열이 셸에 전달됩니다. 구성된 값에 `$(...)`, 백틱 또는 `;`이 포함되면 여기서 코드로 실행되므로 Claude Code는 값을 대체하는 대신 구성 요소를 시작하기를 거부합니다. 확인은 명령 템플릿에서 실행되므로 아직 값이 구성되지 않았을 때도 오류가 나타납니다. v2.1.207 이전에는 값이 셸 명령으로 대체되었습니다.

3860 3882

3861표현은 어느 표면이 옵션을 참조했는지에 따라 다릅니다. 셸 형식 훅은 다음을 보고합니다:3883표현은 어느 사용 환경이 옵션을 참조했는지에 따라 다릅니다. 셸 형식 훅은 다음을 보고합니다:

3862 3884

3863```text theme={null}3885```text theme={null}

3864Hook from plugin formatter@acme-tools references ${user_config.*} in a shell-form command. The substituted value would be re-parsed by the shell. Use exec form instead — {"command": "<executable>", "args": ["${user_config.KEY}", ...]} — or read $CLAUDE_PLUGIN_OPTION_<KEY> from the hook's environment. Command: ./scripts/notify.sh ${user_config.webhook_url}3886Hook from plugin formatter@acme-tools references ${user_config.*} in a shell-form command. The substituted value would be re-parsed by the shell. Use exec form instead — {"command": "<executable>", "args": ["${user_config.KEY}", ...]} — or read $CLAUDE_PLUGIN_OPTION_<KEY> from the hook's environment. Command: ./scripts/notify.sh ${user_config.webhook_url}

3926commands path escapes plugin directory: ./commands\deploy.md — its path contains a backslash, which is not resolved reliably on this platform3948commands path escapes plugin directory: ./commands\deploy.md — its path contains a backslash, which is not resolved reliably on this platform

3927```3949```

3928 3950

3929v2.1.251 이전에는 Claude Code가 마켓플레이스 항목에서 선언된 `commands` 경로를 플러그인 디렉터리 외부를 가리킬 때도 로드했습니다. Claude Code는 이미 `plugin.json`에서 선언된 경로와 마켓플레이스 항목의 다른 구성 요소 경로를 거부했습니다.3951v2.1.251 이전에는 Claude Code가 마켓플레이스 항목에서 선언된 `commands` 경로를 플러그인 디렉터리 외부를 가리킬 때도 로드했습니다.

3930 3952

3931v2.1.257 이전에는 확인이 경로의 철자만 보았으며 심볼릭 링크가 이어지는 위치는 보지 않았습니다.3953v2.1.257 이전에는 확인이 경로의 철자만 보았으며 심볼릭 링크가 이어지는 위치는 보지 않았습니다.

3932 3954

4003 4025

4004Claude Code는 `~/.claude/plugins/known_marketplaces.json`의 레지스트리 파일에 추가한 플러그인 마켓플레이스를 유지합니다. `claude plugin install`과 같이 레지스트리가 필요한 플러그인 명령은 Claude Code가 파일을 사용할 수 없을 때 두 가지 메시지 중 하나로 실패합니다:4026Claude Code는 `~/.claude/plugins/known_marketplaces.json`의 레지스트리 파일에 추가한 플러그인 마켓플레이스를 유지합니다. `claude plugin install`과 같이 레지스트리가 필요한 플러그인 명령은 Claude Code가 파일을 사용할 수 없을 때 두 가지 메시지 중 하나로 실패합니다:

4005 4027

4006* `Failed to load marketplace configuration`: 파일이 유효한 JSON이 아니거나 읽을 수 없습니다. 빈 파일도 이런 식으로 실패합니다.4028* `Failed to load marketplace configuration`: 파일이 존재하지만 유효한 JSON이 아니거나 읽을 수 없습니다. 빈 파일도 이런 식으로 실패합니다.

4007* `Marketplace configuration file is corrupted`: 파일이 유효한 JSON이지만 내용이 레지스트리 스키마와 일치하지 않습니다.4029* `Marketplace configuration file is corrupted`: 파일이 유효한 JSON이지만 내용이 레지스트리 스키마와 일치하지 않습니다.

4008 4030

4009누락된 파일은 실패가 아닙니다: Claude Code는 이를 마켓플레이스가 없는 레지스트리로 취급합니다.

~~4010~~

4011빈 파일의 경우 `claude plugin install`은 다음을 보고합니다:4031빈 파일의 경우 `claude plugin install`은 다음을 보고합니다:

4012 4032

4013```text theme={null}4033```text theme={null}

4019**수행할 작업:**4039**수행할 작업:**

4020 4040

4021* `~/.claude/plugins/known_marketplaces.json`을 열고 JSON을 복구하거나 메시지가 레지스트리 스키마와 일치하지 않는 것으로 이름을 지정한 항목을 수정하십시오.4041* `~/.claude/plugins/known_marketplaces.json`을 열고 JSON을 복구하거나 메시지가 레지스트리 스키마와 일치하지 않는 것으로 이름을 지정한 항목을 수정하십시오.

4022* 복구할 수 없으면 파일을 삭제하거나 내용을 `{}`로 바꾼 다음 `claude plugin marketplace add <source>`로 각 마켓플레이스를 다시 추가하십시오. Claude Code는 신뢰한 폴더에서 다음에 시작할 때 사용자 또는 관리 설정이 [`extraKnownMarketplaces`](/docs/ko/settings-reference#extraknownmarketplaces)에서 선언한 마켓플레이스를 다시 등록합니다.4042* 복구할 수 없으면 파일을 삭제하거나 내용을 `{}`로 바꾼 다음 `claude plugin marketplace add <source>`로 각 마켓플레이스를 다시 추가하십시오. Claude Code는 신뢰한 폴더에서 다음에 시작할 때 사용자 또는 관리형 설정이 [`extraKnownMarketplaces`](/docs/ko/settings-reference#extraknownmarketplaces)에서 선언한 마켓플레이스를 다시 등록합니다.

4023 4043

4024<h3 id="plugin-is-required-by-your-organization">4044<h3 id="plugin-is-required-by-your-organization">

4025 Plugin is required by your organization4045 Plugin is required by your organization

4092 4112

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

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

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

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

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

4098 4118

4127 4147

4128**할 일:**4148**할 일:**

4129 4149

4130* 당신 쪽에서는 아무것도 할 필요가 없습니다: 오류는 도구의 결과로 Claude에 반환되며 메시지 자체가 Claude에 null 바이트를 제거하고 다시 시도하도록 지시합니다.4150* 사용자 쪽에서는 아무것도 할 필요가 없습니다: 오류는 도구의 결과로 Claude에 반환되며 메시지 자체가 Claude에 null 바이트를 제거하고 다시 시도하도록 지시합니다.

4131 4151

4132v2.1.281 이전에는 Read, Write, Edit 또는 NotebookEdit 경로의 null 바이트가 `Path contains null bytes`라는 이름의 오류로 전체 턴을 종료했으며 도구는 실행되지 않았습니다.4152v2.1.281 이전에는 Read, Write, Edit 또는 NotebookEdit 경로의 null 바이트가 `Path contains null bytes`라는 이름의 오류로 전체 턴을 종료했으며 도구는 실행되지 않았습니다.

4133 4153

4193 팀원의 받은편지함에 쓰기 실패4213 팀원의 받은편지함에 쓰기 실패

4194</h3>4214</h3>

4195 4215

4196Claude Code가 `~/.claude/teams/{team-name}/inboxes/` 아래의 팀원 메일박스 파일에 메시지를 쓸 수 없어서 수신자가 아무것도 받지 못했습니다. 쓰기는 Claude Code가 파일을 만들거나 업데이트할 수 없을 때 실패합니다. 예를 들어 디스크가 가득 찼거나, 디렉토리를 쓸 수 없거나, 다른 에이전트가 받은편지함 잠금을 너무 오래 유지하는 경우입니다. v2.1.224 이전에는 Claude Code가 쓰기가 실패했을 때도 메시지를 보낸 것으로 보고했습니다.4216Claude Code가 `~/.claude/teams/{team-name}/inboxes/` 아래의 팀원 메일박스 파일에 메시지를 쓸 수 없어서 수신자가 아무것도 받지 못했습니다. 쓰기는 Claude Code가 파일을 만들거나 업데이트할 수 없을 때 실패합니다. 예를 들어 디스크가 가득 찼거나, 디렉터리를 쓸 수 없거나, 다른 에이전트가 받은편지함 잠금을 너무 오래 유지하는 경우입니다. v2.1.224 이전에는 Claude Code가 쓰기가 실패했을 때도 메시지를 보낸 것으로 보고했습니다.

4197 4217

4198오류는 터미널의 배너가 아닌 전송 에이전트의 도구 결과에 나타나며 Claude에 다시 시도하도록 지시합니다:4218오류는 터미널의 배너가 아닌 전송 에이전트의 도구 결과에 나타나며 Claude에 다시 시도하도록 지시합니다:

4199 4219

4203 4223

4204구조화된 [에이전트 팀](/docs/ko/agent-teams) 프로토콜 메시지는 동일한 방식으로 실패하며 오류는 전달되지 않은 메시지의 이름을 지정합니다: Claude Code가 계획 승인, 계획 거부, 종료 요청 또는 종료 거부를 쓸 수 없을 때 오류는 `Failed to write the <message> to <name>'s inbox — nothing was sent`로 읽습니다. 해당 목록의 `plan approval`은 팀원의 계획을 승인하는 리드의 결정입니다. 팀원의 계획 제출은 별도의 `plan approval request` 메시지입니다. 해당 메시지와 두 개의 다른 프로토콜 메시지는 자신의 메시지 텍스트와 결과를 전달합니다:4224구조화된 [에이전트 팀](/docs/ko/agent-teams) 프로토콜 메시지는 동일한 방식으로 실패하며 오류는 전달되지 않은 메시지의 이름을 지정합니다: Claude Code가 계획 승인, 계획 거부, 종료 요청 또는 종료 거부를 쓸 수 없을 때 오류는 `Failed to write the <message> to <name>'s inbox — nothing was sent`로 읽습니다. 해당 목록의 `plan approval`은 팀원의 계획을 승인하는 리드의 결정입니다. 팀원의 계획 제출은 별도의 `plan approval request` 메시지입니다. 해당 메시지와 두 개의 다른 프로토콜 메시지는 자신의 메시지 텍스트와 결과를 전달합니다:

4205 4225

4206* `Failed to write the plan approval request to the lead's inbox — plan not submitted; try again`: 팀원의 계획이 리드에 도달하지 않았고 팀원은 재제출이 성공할 때까지 계획 모드에 남아 있습니다.4226* `Failed to write the plan approval request to the lead's inbox — plan not submitted; try again`: 팀원의 계획이 리드에 도달하지 않았고 팀원은 재제출이 성공할 때까지 플랜 모드에 남아 있습니다.

4207* `The permission request could not be delivered to the team lead (mailbox write failed)`: 팀원의 권한 요청이 리드에 도달하지 않았으므로 아무도 도구 호출을 승인하지 않았습니다.4227* `The permission request could not be delivered to the team lead (mailbox write failed)`: 팀원의 권한 요청이 리드에 도달하지 않았으므로 아무도 도구 호출을 승인하지 않았습니다.

4208* `The confirmation could not be written to team-lead's inbox.`: 종료 승인 자체가 적용되었고 팀원이 종료됩니다. 리드에 대한 확인만 누락되었습니다.4228* `The confirmation could not be written to team-lead's inbox.`: 종료 승인 자체가 적용되었고 팀원이 종료됩니다. 리드에 대한 확인만 누락되었습니다.

4209 4229

4224Its agent definition was not restored: the folder its definition file came from is not trusted (source: projectSettings), so the teammate is running with the team-essential tools and no custom instructions. To restore it, the user needs to run Claude Code in that folder once and accept the trust dialog (the --debug log names the folder); do not change trust settings on the user's behalf.4244Its agent definition was not restored: the folder its definition file came from is not trusted (source: projectSettings), so the teammate is running with the team-essential tools and no custom instructions. To restore it, the user needs to run Claude Code in that folder once and accept the trust dialog (the --debug log names the folder); do not change trust settings on the user's behalf.

4225```4245```

4226 4246

4227확인은 프로젝트의 `.claude/agents/` 디렉토리 또는 `--add-dir` 디렉토리의 정의에 적용되며 부모 폴더에 대한 신뢰 대화를 수락하는 것은 충족하지 않습니다.4247확인은 프로젝트의 `.claude/agents/` 디렉터리 또는 `--add-dir` 디렉터리의 정의에 적용되며 부모 폴더에 대한 신뢰 대화를 수락하는 것은 충족하지 않습니다.

4228 4248

4229**할 일:**4249**할 일:**

4230 4250

4245 4265

4246**할 일:**4266**할 일:**

4247 4267

4248* Claude에 메시지를 요약하거나 대량 콘텐츠를 파일에 넣고 수신자가 읽을 수 있도록 파일의 경로를 보내도록 요청합니다.4268* Claude에 메시지를 요약하거나 대량 콘텐츠를 파일에 넣고 파일의 경로를 보내도록 요청합니다.

4249* Claude에 콘텐츠를 여러 개의 더 짧은 메시지로 나누도록 요청합니다.4269* Claude에 콘텐츠를 여러 개의 더 짧은 메시지로 나누도록 요청합니다.

4250 4270

4251v2.1.235 이전에는 Claude Code가 과도한 크기의 메시지를 보낸 것으로 보고했습니다. 수신 세션이 읽지 않고 삭제했습니다.4271v2.1.235 이전에는 Claude Code가 과도한 크기의 메시지를 보낸 것으로 보고했습니다. 수신 세션이 읽지 않고 삭제했습니다.

4288 4308

4289**할 일:**4309**할 일:**

4290 4310

4291* 수신자가 삭제된 메시지를 본 적이 없다고 가정합니다. Claude Code는 동일하게 Claude에 알리고 여전히 중요한 것을 나중에 한 메시지에 포함하도록 지시합니다.4311* 수신자가 삭제된 메시지를 본 적이 없다고 가정합니다. Claude Code는 동일하게 Claude에 알리고, 곧바로 다시 보내는 대신 여전히 중요한 것을 나중에 한 메시지에 포함하도록 지시합니다.

4292* 세션이 서로 자주 업데이트를 보내면 Claude에 더 적은 수의 더 큰 메시지를 보내도록 요청합니다. 예를 들어 세션이 작업을 완료할 때 한 보고서입니다.4312* 세션이 서로 자주 업데이트를 보내면 Claude에 더 적은 수의 더 큰 메시지를 보내도록 요청합니다. 예를 들어 세션이 작업을 완료할 때 한 보고서입니다.

4293* `a relay loop between sessions was cut`의 경우 세션 중 하나에 직접 다음 지시를 입력합니다. Claude가 자신의 프롬프트에 응답하여 보내는 메시지는 새 체인을 시작합니다.4313* `a relay loop between sessions was cut`의 경우 세션 중 하나에 직접 다음 지시를 입력합니다. Claude가 사용자의 프롬프트에 응답하여 보내는 메시지는 새 체인을 시작합니다.

4294 4314

4295v2.1.238 이전에는 수신자의 받은편지함이 메시지를 삭제했을 때 전송 세션이 보고를 받지 못했습니다.4315v2.1.238 이전에는 수신자의 받은편지함이 메시지를 삭제했을 때 전송 세션이 보고를 받지 못했습니다.

4296 4316

4306 4326

4307`Refusing to send:` 뒤의 텍스트는 실패한 확인의 이름을 지정합니다:4327`Refusing to send:` 뒤의 텍스트는 실패한 확인의 이름을 지정합니다:

4308 4328

4309* `reply target is a symlink`: 기호 링크가 대상 세션의 소켓 경로에 있습니다. Claude Code는 링크가 대상 세션이 만들지 않은 엔드포인트로 메시지를 리디렉션할 수 있으므로 이를 통해 전달하지 않습니다.4329* `reply target is a symlink`: 심볼릭 링크가 대상 세션의 소켓 경로에 있습니다. Claude Code는 링크가 대상 세션이 만들지 않은 엔드포인트로 메시지를 리디렉션할 수 있으므로 이를 통해 전달하지 않습니다.

4310* `cannot vet reply target`: Claude Code가 대상 경로를 전혀 검사할 수 없습니다. 예를 들어 권한 오류로 읽기가 실패한 경우입니다.4330* `cannot vet reply target`: Claude Code가 대상 경로를 전혀 검사할 수 없습니다. 예를 들어 권한 오류로 읽기가 실패한 경우입니다.

4311 4331

4312**할 일:**4332**할 일:**

4326 4346

4327각 거부는 이유를 지정합니다:4347각 거부는 이유를 지정합니다:

4328 4348

4329* `its symlink resolution changed after permission was checked`: 경로를 따라 또는 Grep 또는 Glob 검색 루트에서 기호 링크가 권한 확인과 작업 사이에 대체되었습니다. 읽기 거부에서 괄호 안의 구문은 어느 비교가 실패했는지 지정합니다.4349* `its symlink resolution changed after permission was checked`: 경로를 따라 또는 Grep 또는 Glob 검색 루트에서 심볼릭 링크가 권한 확인과 작업 사이에 대체되었습니다. 읽기 거부에서 괄호 안의 구문은 어느 비교가 실패했는지 지정합니다.

4330* `its parent-directory symlink resolution changed after permission was checked`: 쓰기 경로가 통과하는 디렉토리가 더 이상 승인된 위치로 해석되지 않습니다.4350* `its parent-directory symlink resolution changed after permission was checked`: 쓰기 경로가 통과하는 디렉터리가 더 이상 승인된 위치로 해석되지 않습니다.

4331* `where it leads on disk could not be determined (a link on the way could not be examined, or the links do not resolve)`: Claude Code가 경로를 디스크의 최종 위치로 따를 수 없습니다. 예를 들어 경로의 기호 링크가 루프를 형성하거나 링크가 해석되지 않는 경우입니다.4351* `where it leads on disk could not be determined (a link on the way could not be examined, or the links do not resolve)`: Claude Code가 경로를 디스크의 최종 위치로 따를 수 없습니다. 예를 들어 경로의 심볼릭 링크가 루프를 형성하는 경우입니다.

4332* `it is a symbolic link. Write to the link's target path instead`: 기호 링크가 요청된 쓰기 위치 자체에 있습니다. 예를 들어 `CLAUDE.md`가 `AGENTS.md`로의 기호 링크입니다. 메시지는 Claude를 링크의 대상으로 지시합니다.4352* `it is a symbolic link. Write to the link's target path instead`: 심볼릭 링크가 요청된 쓰기 위치 자체에 있습니다. 예를 들어 `CLAUDE.md`가 `AGENTS.md`로의 심볼릭 링크입니다. 메시지는 Claude를 링크의 대상으로 지시합니다.

4333* `Refusing to write through symlink: <path>. Resolve the symlink and pass the real target path explicitly.`: 다른 작성자가 파일을 열 때 같은 조건이 포착됩니다. 예를 들어 기호 링크된 `.mcp.json`에 대한 쓰기입니다.4353* `Refusing to write through symlink: <path>. Resolve the symlink and pass the real target path explicitly.`: 다른 작성자가 파일을 열 때 같은 조건이 포착됩니다. 예를 들어 심볼릭 링크된 `.mcp.json`에 대한 쓰기입니다.

4334* `Refusing to write into symlinked directory: <path>`: 파일을 보유한 디렉토리 자체가 기호 링크입니다. 예를 들어 프로젝트의 `.claude/` 디렉토리가 다른 위치로 연결되어 있습니다.4354* `Refusing to write into symlinked directory: <path>`: 파일을 보유한 디렉터리 자체가 심볼릭 링크입니다. 예를 들어 프로젝트의 `.claude/` 디렉터리가 다른 위치로 연결되어 있습니다.

4335* `a path one of its Read deny rules is written through changed while the search was being prepared. Retry.`: `Read` 거부 규칙이 기호 링크를 통과하는 경로의 이름을 지정했고 Claude Code가 검색을 준비하는 동안 해당 링크가 변경되었습니다.4355* `a path one of its Read deny rules is written through changed while the search was being prepared. Retry.`: 검색에 대한 `Read` 거부 규칙이 심볼릭 링크를 통과하는 경로의 이름을 지정했고 Claude Code가 검색을 준비하는 동안 해당 링크가 변경되었습니다.

4336* `it could not be opened (EACCES) — it is unreadable, or is being replaced concurrently.`: 검색 루트가 존재하지만 열 수 없습니다. 괄호 안의 코드는 운영 체제 오류입니다.4356* `it could not be opened (EACCES) — it is unreadable, or is being replaced concurrently.`: 검색 루트가 존재하지만 열 수 없습니다. 괄호 안의 코드는 운영 체제 오류입니다.

4337* `its permission check expired before it ran (too many concurrent file operations). Retry.`: Claude Code가 많은 동시 파일 작업 중에 도구가 사용하기 전에 승인 기록을 제거했습니다. 다시 시도하면 새로운 권한 확인을 실행합니다.4357* `its permission check expired before it ran (too many concurrent file operations). Retry.`: Claude Code가 많은 동시 파일 작업 중에 도구가 사용하기 전에 승인 기록을 제거했습니다. 재시도하면 새로운 권한 확인을 실행합니다.

4338* `ripgrep was found only by name on PATH, and a search outside the working directory cannot apply your Read deny rules in that configuration`: Claude Code가 `rg` 바이너리를 절대 경로로 해석할 수 없어서 작업 디렉토리 외부의 검색을 거부하는 것이 거부 규칙을 적용하지 않는 것보다 낫습니다.4358* `ripgrep was found only by name on PATH, and a search outside the working directory cannot apply your Read deny rules in that configuration`: Claude Code가 `rg` 바이너리를 절대 경로로 해석할 수 없어서, 거부 규칙이 적용되지 않는 검색을 실행하는 대신 작업 디렉터리 외부의 검색을 거부합니다.

4339 4359

4340**할 일:**4360**할 일:**

4341 4361

4342* 보통 아무것도 하지 않습니다: 거부는 Claude에 도구 결과로 도달하고 거부된 작업은 실행되지 않습니다.4362* 보통 아무것도 하지 않습니다: 거부는 Claude에 도구 결과로 도달하고 거부된 작업은 실행되지 않습니다.

4343* 한 경로에서 기호 링크 거부가 반복되면 빌드 도구 또는 파일 감시자와 같이 링크를 계속 다시 쓰는 것을 찾거나 Claude에 링크된 경로 대신 파일의 해석된 경로를 사용하도록 요청합니다.4363* 한 경로에서 심볼릭 링크 거부가 반복되면 빌드 도구 또는 파일 감시자와 같이 링크를 계속 다시 쓰는 것을 찾거나 Claude에 링크된 경로 대신 파일의 해석된 경로를 사용하도록 요청합니다.

4344* 이 거부가 Claude Code가 AppContainer 또는 제한된 토큰 샌드박스 내의 Windows에서 실행될 때 모든 파일에 대해 나타나면 v2.1.265 이상으로 업그레이드합니다.4364* 이 거부가 Claude Code가 AppContainer 또는 제한된 토큰 샌드박스 내의 Windows에서 실행될 때 모든 파일에 대해 나타나면 v2.1.265 이상으로 업그레이드합니다.

4345* 읽기 거부가 macOS에서 스크린샷을 프롬프트로 드래그한 것처럼 아무것도 다시 쓰지 않는 파일에 대해 나타나면 v2.1.273 이상으로 업그레이드합니다.4365* 읽기 거부가 macOS에서 스크린샷을 프롬프트로 드래그한 것처럼 아무것도 다시 쓰지 않는 파일에 대해 나타나면 v2.1.273 이상으로 업그레이드합니다.

4346* ripgrep 거부의 경우 패키지 관리자로 ripgrep을 설치하여 `rg`가 `PATH`의 절대 경로로 해석되거나 검색을 작업 디렉토리 아래로 유지합니다.4366* ripgrep 거부의 경우 패키지 관리자로 ripgrep을 설치하여 `rg`가 `PATH`의 절대 경로로 해석되도록 하거나 검색을 작업 디렉터리 아래로 유지합니다.

4347 4367

4348v2.1.251 이전에는 Claude Code가 파일 쓰기에 대해서만 경로의 해석을 다시 확인했으므로 권한 확인 후 대체된 링크가 메시지 없이 읽기 또는 검색을 다른 위치로 리디렉션할 수 있었습니다. 이러한 거부 중에서 부모 디렉토리, 기호 링크를 통한, 그리고 기호 링크된 디렉토리 쓰기 거부만 이전 버전에 나타납니다.4368v2.1.251 이전에는 Claude Code가 파일 쓰기에 대해서만 경로의 해석을 다시 확인했으므로 권한 확인 후 대체된 링크가 메시지 없이 읽기 또는 검색을 다른 위치로 리디렉션할 수 있었습니다. 이러한 거부 중에서 부모 디렉터리, 심볼릭 링크를 통한, 그리고 심볼릭 링크된 디렉터리 쓰기 거부만 이전 버전에 나타납니다.

4349 4369

4350v2.1.280 이전에는 `where it leads on disk could not be determined` 거부가 나타나지 않았습니다.4370v2.1.280 이전에는 `where it leads on disk could not be determined` 거부가 나타나지 않았습니다.

4351 4371

4353 작업 출력 스왑 거부4373 작업 출력 스왑 거부

4354</h3>4374</h3>

4355 4375

4356Claude Code는 각 Bash 명령의 출력을 임시 디렉토리 아래의 파일에 저장합니다. 이러한 파일 중 하나를 열 때마다 경로가 여전히 생성한 파일로 이어지는지 확인합니다. 기호 링크, 추가 하드 링크 또는 이동된 디렉토리가 리디렉션하지 않습니다. 이 메시지는 확인이 실패했음을 의미하므로 Claude Code는 해당 경로를 통해 쓰거나 읽는 대신 작업을 거부했습니다. 메시지는 Bash 도구 결과에 나타납니다:4376Claude Code는 각 Bash 명령의 출력을 임시 디렉터리 아래의 파일에 저장합니다. 이러한 파일 중 하나를 열 때마다 경로가 여전히 생성한 파일로 이어지는지 확인합니다. 심볼릭 링크, 추가 하드 링크 또는 이동된 디렉터리가 리디렉션하지 않습니다. 이 메시지는 확인이 실패했음을 의미하므로 Claude Code는 해당 경로를 통해 쓰거나 읽는 대신 작업을 거부했습니다. 메시지는 Bash 도구 결과에 나타납니다:

4357 4377

4358```text wrap theme={null}4378```text wrap theme={null}

4359task output swap refused (tasks dir moved or linked): /private/tmp/claude-501/-Users-you-my-project/1f0e62dc-4b0a-4f5e-9c2d-8a7b6c5d4e3f/tasks/b7k2f9m3q.output. To recover: restart Claude Code with CLAUDE_CODE_TMPDIR set to a fresh directory; or, if /private/tmp/claude-501/-Users-you-my-project is a stray directory or a symbolic link that should not be there, remove that entry itself (not what it points to) and restart.4379task output swap refused (tasks dir moved or linked): /private/tmp/claude-501/-Users-you-my-project/1f0e62dc-4b0a-4f5e-9c2d-8a7b6c5d4e3f/tasks/b7k2f9m3q.output. To recover: restart Claude Code with CLAUDE_CODE_TMPDIR set to a fresh directory; or, if /private/tmp/claude-501/-Users-you-my-project is a stray directory or a symbolic link that should not be there, remove that entry itself (not what it points to) and restart.

4369 4389

4370**할 일:**4390**할 일:**

4371 4391

4372* v2.1.260 이상으로 업그레이드합니다. 이전 버전은 링크 또는 이동된 디렉토리가 없을 때도 이 메시지를 표시하기도 했습니다.4392* v2.1.260 이상으로 업그레이드합니다. 이전 버전은 링크 또는 이동된 디렉터리가 없을 때도 이 메시지를 표시하기도 했습니다.

4373* [`CLAUDE_CODE_TMPDIR`](/docs/ko/env-vars)을 새 디렉토리로 설정하여 Claude Code를 다시 시작합니다.4393* [`CLAUDE_CODE_TMPDIR`](/docs/ko/env-vars)을 새 디렉터리로 설정하여 Claude Code를 다시 시작합니다.

4374* 또는 Claude Code 임시 디렉토리 아래의 프로젝트 디렉토리를 확인합니다. 예제 메시지의 `/private/tmp/claude-501/-Users-you-my-project`입니다. 해당 경로가 기호 링크이거나 거기에 있으면 안 되는 디렉토리이면 링크의 대상이 아닌 링크 또는 디렉토리 자체를 제거하고 Claude Code를 다시 시작합니다.4394* 또는 Claude Code 임시 디렉터리 아래의 프로젝트 디렉터리를 확인합니다. 예제 메시지의 `/private/tmp/claude-501/-Users-you-my-project`입니다. 해당 경로가 심볼릭 링크이거나 거기에 있으면 안 되는 디렉터리이면 링크의 대상이 아닌 링크 또는 디렉터리 자체를 제거하고 Claude Code를 다시 시작합니다.

4375* 거부가 반복되면 프로세스가 세션이 실행되는 동안 Claude Code의 임시 디렉토리 아래의 항목을 대체, 링크 또는 제거합니다. [`CLAUDE_CODE_TMPDIR`](/docs/ko/env-vars)을 다른 것이 관리하지 않는 디렉토리로 설정하고 다시 시작합니다.4395* 거부가 반복되면 프로세스가 세션이 실행되는 동안 Claude Code의 임시 디렉터리 아래의 항목을 대체, 링크 또는 제거합니다. [`CLAUDE_CODE_TMPDIR`](/docs/ko/env-vars)을 다른 것이 관리하지 않는 디렉터리로 설정하고 다시 시작합니다.

4376 4396

4377<h3 id="disk-quota-or-temp-filesystem-is-full">4397<h3 id="disk-quota-or-temp-filesystem-is-full">

4378 디스크 할당량 또는 임시 파일 시스템이 가득 참4398 디스크 할당량 또는 임시 파일 시스템이 가득 참

4379</h3>4399</h3>

4380 4400

4381Claude Code는 각 Bash 및 PowerShell 명령의 출력을 임시 디렉토리 아래의 파일에 저장합니다. 명령이 0이 아닌 코드로 종료되고 출력이 전혀 없으면 Claude Code는 해당 파일을 보유한 파일 시스템이 공간 또는 inode가 부족한지, 또는 디스크 할당량이 사용되었는지 확인합니다. 그렇다면 진단이 빈 출력 대신 명령의 결과에 나타납니다:4401Claude Code는 각 Bash 및 PowerShell 명령의 출력을 임시 디렉터리 아래의 파일에 저장합니다. 명령이 0이 아닌 코드로 종료되고 출력이 전혀 없으면 Claude Code는 해당 파일을 보유한 파일 시스템이 공간 또는 inode가 부족한지, 또는 디스크 할당량이 사용되었는지 확인합니다. 그렇다면 진단이 빈 출력 대신 명령의 결과에 나타납니다:

4382 4402

4383```text wrap theme={null}4403```text wrap theme={null}

4384Your disk quota is full on the filesystem with Claude Code's temp directory /private/tmp/claude-501/-Users-you-my-project/1f0e62dc-4b0a-4f5e-9c2d-8a7b6c5d4e3f/tasks (EDQUOT), so any output this command printed was lost, and it may have failed because it could not write. Delete files you no longer need there, or restart Claude Code with CLAUDE_CODE_TMPDIR set to a directory on another filesystem.4404Your disk quota is full on the filesystem with Claude Code's temp directory /private/tmp/claude-501/-Users-you-my-project/1f0e62dc-4b0a-4f5e-9c2d-8a7b6c5d4e3f/tasks (EDQUOT), so any output this command printed was lost, and it may have failed because it could not write. Delete files you no longer need there, or restart Claude Code with CLAUDE_CODE_TMPDIR set to a directory on another filesystem.

4386 4406

4387메시지는 무엇이 부족한지 지정합니다:4407메시지는 무엇이 부족한지 지정합니다:

4388 4408

4389* `Your disk quota is full ... (EDQUOT)`: 해당 파일 시스템에 대한 당신의 할당량이 사용되었습니다. 할당량은 파일 시스템이 여전히 여유 공간을 표시하는 동안 가득 찰 수 있습니다.4409* `Your disk quota is full ... (EDQUOT)`: 해당 파일 시스템에 대한 사용자 본인의 할당량이 사용되었습니다. 할당량은 파일 시스템이 여전히 여유 공간을 표시하는 동안 가득 찰 수 있습니다.

4390* `The filesystem with Claude Code's temp directory ..., or your disk quota on it, is full (ENOSPC)`: 파일 시스템 또는 할당량에 공간이 남지 않았습니다.4410* `The filesystem with Claude Code's temp directory ..., or your disk quota on it, is full (ENOSPC)`: 파일 시스템 또는 할당량에 공간이 남지 않았습니다.

4391* `Command output was lost: the temp filesystem at ... is full` 또는 `... is out of inodes`: 파일 시스템에 거의 여유 공간이 남지 않았거나 inode가 부족합니다.4411* `Command output was lost: the temp filesystem at ... is full` 또는 `... is out of inodes`: 파일 시스템에 거의 여유 공간이 남지 않았거나 inode가 부족합니다.

4392 4412

4393**할 일:**4413**할 일:**

4394 4414

4395* Claude Code의 임시 디렉토리를 보유한 파일 시스템에서 더 이상 필요하지 않은 파일을 삭제합니다. `EDQUOT`의 경우 당신의 할당량에 포함되는 파일을 삭제합니다. `out of inodes`의 경우 각 파일이 크기에 관계없이 하나의 inode를 차지하므로 몇 개의 큰 파일이 아닌 많은 파일을 삭제합니다.4415* Claude Code의 임시 디렉터리를 보유한 파일 시스템에서 더 이상 필요하지 않은 파일을 삭제합니다. `EDQUOT`의 경우 사용자 본인의 할당량에 포함되는 파일을 삭제합니다. `out of inodes`의 경우 각 파일이 크기에 관계없이 하나의 inode를 차지하므로 몇 개의 큰 파일이 아닌 많은 파일을 삭제합니다.

4396* 또는 [`CLAUDE_CODE_TMPDIR`](/docs/ko/env-vars)을 여유 공간이 있는 파일 시스템의 디렉토리로 설정하여 Claude Code를 다시 시작합니다.4416* 또는 [`CLAUDE_CODE_TMPDIR`](/docs/ko/env-vars)을 여유 공간이 있는 파일 시스템의 디렉터리로 설정하여 Claude Code를 다시 시작합니다.

4397* 그런 다음 Claude에 명령을 다시 실행하도록 합니다. 인쇄한 출력은 손실되었으며 잘리지 않았습니다.4417* 그런 다음 Claude에 명령을 다시 실행하도록 합니다. 인쇄한 출력은 손실되었으며 잘리지 않았습니다.

4398 4418

4399<h3 id="the-source-file-is-not-valid-utf-8-text">4419<h3 id="the-source-file-is-not-valid-utf-8-text">

4413**할 일:**4433**할 일:**

4414 4434

4415* 보통 아무것도 하지 않습니다: Claude가 파일을 다시 쓰고 게시합니다.4435* 보통 아무것도 하지 않습니다: Claude가 파일을 다시 쓰고 게시합니다.

4416* 파일이 당신이 작성하거나 내보낸 것이면 UTF-8로 다시 저장하고 각 `U+FFFD`를 이전 편집, 붙여넣기 또는 변환이 손실한 문자로 바꿉니다.4436* 파일이 사용자가 작성하거나 내보낸 것이면 UTF-8로 다시 저장하고 각 `U+FFFD`를 이전 편집, 붙여넣기 또는 변환이 손실한 문자로 바꿉니다.

4417* 페이지에 의도적인 `U+FFFD`를 표시하려면 리터럴 문자 대신 HTML에서 `�`로 작성합니다.4437* 페이지에 의도적인 `U+FFFD`를 표시하려면 리터럴 문자 대신 HTML에서 `�`로 작성합니다.

4418 4438

4419v2.1.267 이전에는 Claude Code가 그러한 파일을 확인 없이 업로드했고 서버가 대신 게시를 거부했습니다.4439v2.1.267 이전에는 Claude Code가 그러한 파일을 확인 없이 업로드했고 서버가 대신 게시를 거부했습니다.

4422 Cowork 세션에서 연결된 폴더 외부의 로컬 파일 읽기4442 Cowork 세션에서 연결된 폴더 외부의 로컬 파일 읽기

4423</h3>4443</h3>

4424 4444

4425Claude Desktop 앱에서 머신에서 실행 중인 [Cowork](https://claude.com/docs/cowork/overview) 세션에서 Claude가 [아티팩트](/docs/ko/artifacts)에 대한 로컬 파일의 이름을 지정했습니다. Claude Code가 파일이 세션의 연결된 폴더 내의 일반 파일인지 확인할 수 없습니다: 경로가 해당 폴더 외부에 있거나, 기호 링크를 통과하거나, 나타나는 것과 다른 파일의 이름을 지정할 수 있는 방식으로 철자가 지정되었습니다. 그러한 파일을 읽으려면 승인이 필요하며, 승인 카드를 표시할 수 없는 세션(예: 모든 승인을 건너뛰도록 설정된 세션)에서 Claude Code는 읽기를 거부합니다.4445Claude Desktop 앱에서 머신에서 실행 중인 [Cowork](https://claude.com/docs/cowork/overview) 세션에서 Claude가 [아티팩트](/docs/ko/artifacts)에 대한 로컬 파일의 이름을 지정했습니다. Claude Code가 파일이 세션의 연결된 폴더 내의 일반 파일인지 확인할 수 없습니다: 경로가 해당 폴더 외부에 있거나, 심볼릭 링크를 통과하거나, 나타나는 것과 다른 파일의 이름을 지정할 수 있는 방식으로 철자가 지정되었습니다. 그러한 파일을 읽으려면 승인이 필요하며, 승인 카드를 표시할 수 없는 세션(예: 모든 승인을 건너뛰도록 설정된 세션)에서 Claude Code는 읽기를 거부합니다.

4426 4446

4427거부는 Artifact 도구 결과에 나타납니다. 파일을 전혀 검사할 수 없을 때 대신 해당 실패의 이름을 지정합니다:4447거부는 Artifact 도구 결과에 나타납니다. 파일을 전혀 검사할 수 없을 때 대신 해당 실패의 이름을 지정합니다:

4428 4448

4435**할 일:**4455**할 일:**

4436 4456

4437* 보통 아무것도 하지 않습니다: 메시지는 Claude에 연결된 폴더 내의 일반 파일을 대신 사용하도록 지시합니다.4457* 보통 아무것도 하지 않습니다: 메시지는 Claude에 연결된 폴더 내의 일반 파일을 대신 사용하도록 지시합니다.

4438* 정확한 파일을 아티팩트에 넣으려면 세션의 연결된 폴더 중 하나에 일반 파일(기호 링크 아님)로 복사하고 다시 요청합니다.4458* 정확한 파일을 아티팩트에 넣으려면 세션의 연결된 폴더 중 하나에 일반 파일(심볼릭 링크 아님)로 복사하고 다시 요청합니다.

4439 4459

4440<h3 id="webfetch-cannot-fetch-localhost">4460<h3 id="webfetch-cannot-fetch-localhost">

4441 WebFetch는 localhost를 가져올 수 없음4461 WebFetch는 localhost를 가져올 수 없음

4453 4473

4454v2.1.268 이전에는 WebFetch가 이러한 URL을 일반 `Invalid URL` 오류로 보고했습니다.4474v2.1.268 이전에는 WebFetch가 이러한 URL을 일반 `Invalid URL` 오류로 보고했습니다.

4455 4475

4476<h3 id="webfetch-domain-safety-check-failed">

4477 WebFetch 도메인 안전 확인 실패

4478</h3>

4479

4480URL을 가져오기 전에 WebFetch는 URL의 호스트명을 `api.anthropic.com`으로 보내 Anthropic의 [도메인 안전 차단 목록](/docs/ko/data-usage#webfetch-domain-safety-check)과 대조합니다. 확인을 완료할 수 없으면 WebFetch는 도메인이 안전한지 확인할 수 없으므로 페이지를 가져오지 않으며, 도구 결과에는 대신 다음 메시지 중 하나가 포함됩니다:

4481

4482```text wrap theme={null}

4483The safety check for domain example.com is rate-limited (too many domain checks from this network; the limit is shared and can stay exhausted for minutes). Do not retry WebFetch in a loop or sleep to wait it out; continue without this page and report that its safety check was rate-limited. A single later attempt is fine; if that is rate-limited too, stop.

4484

4485Unable to verify if domain example.com is safe to fetch. This may be due to network restrictions or enterprise security policies blocking claude.ai.

4486```

4487

4488* `rate-limited`: 확인 엔드포인트가 HTTP `429`로 응답했습니다. 메시지는 Claude에 페이지 없이 계속하고 나중에 최대 한 번만 다시 시도하도록 지시합니다. Claude Code는 실패한 확인을 캐시하지 않으므로 나중에 해당 도메인을 가져오면 확인이 다시 실행됩니다. 네트워크의 세션에서 이 문제가 자주 발생하면 설정에서 [`skipWebFetchPreflight: true`](/docs/ko/settings-reference#skipwebfetchpreflight)로 확인을 건너뛸 수 있습니다.

4489* `Unable to verify`: 확인 요청이 실패했거나, 시간 초과되었거나, 다른 오류 상태를 받았습니다. 네트워크가 `api.anthropic.com`을 차단하는 경우 해당 도메인을 허용 목록에 추가하거나 설정에서 [`skipWebFetchPreflight: true`](/docs/ko/settings-reference#skipwebfetchpreflight)로 확인을 건너뜁니다.

4490

4491v2.1.286 이전에는 속도 제한 메시지가 `The safety check for domain example.com is temporarily rate-limited (too many domain checks from this network). Retry after about a minute; retrying sooner will fail the same way.`였습니다.

4492v2.1.285 이전에는 속도 제한된 확인이 대신 `Unable to verify` 메시지로 보고되었습니다.

4493

4456<h2 id="background-session-errors">4494<h2 id="background-session-errors">

4457 백그라운드 세션 오류4495 백그라운드 세션 오류

4458</h2>4496</h2>

4459 4497

4460[백그라운드 세션](/docs/ko/agent-view)은 자체 대화형 터미널 없이 실행되므로 터미널이 필요한 명령은 다르게 작동합니다. 이러한 메시지는 백그라운드 세션의 기록, 백그라운드 세션에 연결된 터미널, 디스패치하는 세션 또는 셸에 나타나거나, 아래의 [worktree-guard 항목](#write-or-command-blocked-because-the-path-cannot-be-safely-resolved)의 경우 worktree에 격리된 모든 세션이나 worktree 격리 서브에이전트를 실행하는 세션에 나타납니다. 메시지가 특정 표면에만 해당하는 경우 해당 항목에 명시됩니다.4498[백그라운드 세션](/docs/ko/agent-view)은 자체 대화형 터미널 없이 실행되므로 터미널이 필요한 명령은 다르게 작동합니다. 이러한 메시지는 백그라운드 세션의 트랜스크립트, 백그라운드 세션에 연결된 터미널, 디스패치하는 세션 또는 셸에 나타나거나, 아래의 [worktree-guard 항목](#write-or-command-blocked-because-the-path-cannot-be-safely-resolved)의 경우 worktree에 격리된 모든 세션이나 worktree 격리 서브에이전트를 실행하는 세션에 나타납니다. 메시지가 특정 사용 환경에만 해당하는 경우 해당 항목에 명시됩니다.

4461 4499

4462<h3 id="commands-refused-in-a-background-session">4500<h3 id="commands-refused-in-a-background-session">

4463 백그라운드 세션에서 거부된 명령4501 백그라운드 세션에서 거부된 명령

4482 경로를 안전하게 확인할 수 없어서 쓰기 또는 명령이 차단됨4520 경로를 안전하게 확인할 수 없어서 쓰기 또는 명령이 차단됨

4483</h3>4521</h3>

4484 4522

4485Claude가 [worktree 격리 가드](/docs/ko/agent-view#how-file-edits-are-isolated)가 하나의 확인 가능한 위치로 확인할 수 없는 철자로 파일 또는 작업 디렉토리를 처리했습니다. 가드는 [worktree에 격리된 모든 세션](/docs/ko/worktrees#how-claude-code-enforces-isolation)(대화형 또는 백그라운드)과 [worktree 격리 서브에이전트](/docs/ko/worktrees#isolate-subagents-with-worktrees)에서 쓰기 및 명령 작업 디렉토리를 확인합니다. 공유 체크아웃에 도달하지 않는지 확인하기 전에 심볼릭 링크를 확인하며, 확인이 실패하면 공유 체크아웃에 도달하도록 하는 대신 작업을 차단합니다. 메시지는 거부하는 경로 형식과 재시도 방법을 명시합니다:4523Claude가 [worktree 격리 가드](/docs/ko/agent-view#how-file-edits-are-isolated)가 하나의 확인 가능한 위치로 확인할 수 없는 철자로 파일 또는 작업 디렉터리를 처리했습니다. 가드는 [worktree에 격리된 모든 세션](/docs/ko/worktrees#how-claude-code-enforces-isolation)(대화형 또는 백그라운드)과 [worktree 격리 서브에이전트](/docs/ko/worktrees#isolate-subagents-with-worktrees)에서 쓰기 및 명령 작업 디렉터리를 확인합니다. 공유 체크아웃에 도달하지 않는지 확인하기 전에 심볼릭 링크를 확인하며, 확인이 실패하면 공유 체크아웃에 도달하도록 하는 대신 작업을 차단합니다. 메시지는 거부하는 경로 형식과 재시도 방법을 명시합니다:

4486 4524

4487```text theme={null}4525```text theme={null}

4488This write was blocked because the path is spelled in a form that cannot be safely resolved (for example through a symlink storing a raw dot segment, a network-share or device-namespace shape, or an unreadable ancestor directory). If the file is inside the worktree /path/to/worktree, address it by its direct symlink-free path instead.4526This write was blocked because the path is spelled in a form that cannot be safely resolved (for example through a symlink storing a raw dot segment, a network-share or device-namespace shape, or an unreadable ancestor directory). If the file is inside the worktree /path/to/worktree, address it by its direct symlink-free path instead.

4489```4527```

4490 4528

4491차단된 명령은 작업 디렉토리에 대해 동일한 원인을 보고하고 `re-run the command from its direct symlink-free path`로 끝납니다. v2.1.217 이전에는 가드가 심볼릭 링크를 확인하지 않고 경로 철자를 비교했으므로 이러한 철자는 차단되지 않았으며 심볼릭 링크를 통한 쓰기는 공유 체크아웃에 도달할 수 있었습니다.4529차단된 명령은 작업 디렉터리에 대해 동일한 원인을 보고하고 `re-run the command from its direct symlink-free path`로 끝납니다. v2.1.217 이전에는 가드가 심볼릭 링크를 확인하지 않고 경로 철자를 비교했으므로 이러한 철자는 차단되지 않았으며 심볼릭 링크를 통한 쓰기는 공유 체크아웃에 도달할 수 있었습니다.

4492 4530

4493**할 일:**4531**할 일:**

4494 4532

4495* 일반적으로 아무것도 하지 않습니다: 전체 메시지는 Claude에 도구 오류로 전달되며 Claude는 명시하는 직접 경로로 재시도합니다. 차단된 파일 편집의 경우 대화 뷰에는 짧은 `Error editing file` 줄만 표시됩니다. 전체 메시지는 `Ctrl+O`로 열 수 있는 기록 뷰에 나타납니다. 차단된 명령은 명령 출력에 인쇄합니다.4533* 일반적으로 아무것도 하지 않습니다: 전체 메시지는 Claude에 도구 오류로 전달되며 Claude는 명시하는 직접 경로로 재시도합니다. 차단된 파일 편집의 경우 대화 뷰에는 짧은 `Error editing file` 줄만 표시됩니다. 전체 메시지는 `Ctrl+O`로 열 수 있는 트랜스크립트 뷰에 나타납니다. 차단된 명령은 명령 출력에 인쇄합니다.

4496* 같은 파일에서 차단이 반복되면 경로가 `docs/current -> ../README.md`와 같이 `..`를 포함하는 대상을 가진 커밋된 심볼릭 링크를 통해 실행될 가능성이 높습니다. Claude에 링크를 통하지 않고 실제 경로로 대상 파일을 편집하도록 요청합니다.4534* 같은 파일에서 차단이 반복되면 경로가 `docs/current -> ../README.md`와 같이 `..`를 포함하는 대상을 가진 커밋된 심볼릭 링크를 통해 실행될 가능성이 높습니다. Claude에 링크를 통하지 않고 실제 경로로 대상 파일을 편집하도록 요청합니다.

4497 4535

4498<h3 id="write-or-command-blocked-because-the-path-names-a-network-location">4536<h3 id="write-or-command-blocked-because-the-path-names-a-network-location">

4499 경로가 네트워크 위치를 명시하기 때문에 쓰기 또는 명령이 차단됨4537 경로가 네트워크 위치를 명시하기 때문에 쓰기 또는 명령이 차단됨

4500</h3>4538</h3>

4501 4539

4502Claude가 머신에 없는 드라이브, `\\server\share\file`과 같은 UNC 공유 또는 `/net` 자동 마운트 경로를 명시하는 경로를 통해 파일 또는 작업 디렉토리를 처리했으며, 세션의 체크아웃은 로컬 디스크에 있습니다. 동일한 [worktree 격리 가드](#write-or-command-blocked-because-the-path-cannot-be-safely-resolved)는 그러한 경로가 공유 체크아웃을 벗어나는지 확인할 수 없으므로 작업을 차단합니다. 세션을 worktree에 격리해도 차단이 해제되지 않습니다. 메시지는 대신 사용할 경로 형식을 명시합니다:4540Claude가 머신에 없는 드라이브, `\\server\share\file`과 같은 UNC 공유 또는 `/net` 자동 마운트 경로를 명시하는 경로를 통해 파일 또는 작업 디렉터리를 처리했으며, 세션의 체크아웃은 로컬 디스크에 있습니다. 동일한 [worktree 격리 가드](#write-or-command-blocked-because-the-path-cannot-be-safely-resolved)는 그러한 경로가 공유 체크아웃을 벗어나는지 확인할 수 없으므로 작업을 차단합니다. 세션을 worktree에 격리해도 차단이 해제되지 않습니다. 메시지는 대신 사용할 경로 형식을 명시합니다:

4503 4541

4504```text theme={null}4542```text theme={null}

4505This write was blocked because the path is network-shaped (a UNC share or /net automount spelling) while this session's checkout is local. Isolating cannot unblock it. If the file is genuinely inside the worktree /path/to/worktree, address it by its local, plainly-spelled path instead.4543This write was blocked because the path is network-shaped (a UNC share or /net automount spelling) while this session's checkout is local. Isolating cannot unblock it. If the file is genuinely inside the worktree /path/to/worktree, address it by its local, plainly-spelled path instead.

4506```4544```

4507 4545

4508차단된 명령은 작업 디렉토리에 대해 동일한 원인을 보고하고 `re-run the command from its local, plainly-spelled path`로 끝납니다. v2.1.217 이전에는 가드가 경로 텍스트만 비교했으므로 UNC 또는 `/net` 경로를 통해 체크아웃 내부의 파일을 처리하는 것은 차단되지 않았습니다.4546차단된 명령은 작업 디렉터리에 대해 동일한 원인을 보고하고 `re-run the command from its local, plainly-spelled path`로 끝납니다. v2.1.217 이전에는 가드가 경로 텍스트만 비교했으므로 UNC 또는 `/net` 경로를 통해 체크아웃 내부의 파일을 처리하는 것은 차단되지 않았습니다.

4509 4547

4510**할 일:**4548**할 일:**

4511 4549

4533* 의도적으로 주 체크아웃에 작용하려면 세션 외부의 터미널에서 명령을 직접 실행합니다.4571* 의도적으로 주 체크아웃에 작용하려면 세션 외부의 터미널에서 명령을 직접 실행합니다.

4534 4572

4535<h3 id="this-session-has-no-saved-transcript">4573<h3 id="this-session-has-no-saved-transcript">

4536 이 세션에는 저장된 기록이 없습니다4574 이 세션에는 저장된 트랜스크립트가 없습니다

4537</h3>4575</h3>

4538 4576

4539`←` 또는 `/background`로 다른 대화에서 백그라운드로 처리되고 첫 번째 응답이 완료되기 전에 중지된 [백그라운드 세션](/docs/ko/agent-view)에 연결했습니다. 첫 번째 응답이 완료될 때까지 대화는 백그라운드로 처리된 세션에만 존재하므로 `claude attach`는 같은 세션 ID로 빈 대화를 시작하는 대신 중지된 세션을 시작하기를 거부합니다. 메시지는 이 세션에 대한 `claude respawn` 명령으로 끝납니다:4577`←` 또는 `/background`로 다른 대화에서 백그라운드로 처리되고 첫 번째 응답이 완료되기 전에 중지된 [백그라운드 세션](/docs/ko/agent-view)에 연결했습니다. 첫 번째 응답이 완료될 때까지 대화는 백그라운드로 처리된 세션에만 존재하므로 `claude attach`는 같은 세션 ID로 빈 대화를 시작하는 대신 중지된 세션을 시작하기를 거부합니다. 메시지는 이 세션에 대한 `claude respawn` 명령으로 끝납니다:

4548 4586

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

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

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

4552 4590

4553<h3 id="this-session-is-running-in-another-terminal">4591<h3 id="this-session-is-running-in-another-terminal">

4554 이 세션이 다른 터미널에서 실행 중입니다4592 이 세션이 다른 터미널에서 실행 중입니다

4555</h3>4593</h3>

4556 4594

4557[에이전트 뷰](/docs/ko/agent-view)에서 중지된 세션의 행을 열었으며, 저장된 대화가 이미 이 머신의 다른 라이브 Claude Code 프로세스에서 열려 있으므로 Claude Code는 같은 기록에 쓸 두 번째 프로세스를 시작하기를 거부합니다. 표시되는 메시지는 [대화를 보유한 것](/docs/ko/agent-view#opening-a-session-says-the-conversation-is-already-open)에 따라 다릅니다:4595[에이전트 뷰](/docs/ko/agent-view)에서 중지된 세션의 행을 열었으며, 저장된 대화가 이미 이 머신의 다른 라이브 Claude Code 프로세스에서 열려 있으므로 Claude Code는 같은 트랜스크립트에 쓸 두 번째 프로세스를 시작하기를 거부합니다. 표시되는 메시지는 [대화를 보유한 것](/docs/ko/agent-view#opening-a-session-says-the-conversation-is-already-open)에 따라 다릅니다:

4558 4596

4559```text theme={null}4597```text theme={null}

4560Can't open — this session is running in another terminal4598Can't open — this session is running in another terminal

4576 이 세션의 저장된 대화가 더 이상 디스크에 없습니다4614 이 세션의 저장된 대화가 더 이상 디스크에 없습니다

4577</h3>4615</h3>

4578 4616

4579백그라운드 서비스가 꺼져 있는 동안 종료된 [백그라운드 세션](/docs/ko/agent-view)을 열었으며, [기록 정리](/docs/ko/settings-reference#cleanupperioddays)가 저장된 대화를 제거했습니다. 예를 들어 머신이 몇 주 동안 꺼져 있었습니다. 일반적으로 이러한 행을 열면 [저장된 대화를 재개](/docs/ko/agent-view#sessions-show-as-failed-after-shutdown)합니다. 재개할 것이 없으면 Claude Code는 세션의 원래 프롬프트를 다시 실행하도록 요청하지 않고 거부합니다:4617백그라운드 서비스가 꺼져 있는 동안 종료된 [백그라운드 세션](/docs/ko/agent-view)을 열었으며, [트랜스크립트 정리](/docs/ko/settings-reference#cleanupperioddays)가 저장된 대화를 제거했습니다. 예를 들어 머신이 몇 주 동안 꺼져 있었습니다. 일반적으로 이러한 행을 열면 [저장된 대화를 재개](/docs/ko/agent-view#sessions-show-as-failed-after-shutdown)합니다. 재개할 것이 없으면 Claude Code는 묻지 않고 세션의 원래 프롬프트를 다시 실행하는 대신 거부합니다:

4580 4618

4581```text theme={null}4619```text theme={null}

4582This session's saved conversation is no longer on disk (it ended while the background service was off, and old transcripts are cleaned up), so there is nothing to resume. `claude rm 7c5dcf5d` deletes the row; `claude respawn 7c5dcf5d` runs its original prompt again instead.4620This session's saved conversation is no longer on disk (it ended while the background service was off, and old transcripts are cleaned up), so there is nothing to resume. `claude rm 7c5dcf5d` deletes the row; `claude respawn 7c5dcf5d` runs its original prompt again instead.

4595 Worktree에 어디에도 푸시되지 않은 커밋이 있습니다4633 Worktree에 어디에도 푸시되지 않은 커밋이 있습니다

4596</h3>4634</h3>

4597 4635

4598Claude Code가 다른 곳에 저장되었는지 확인할 수 없는 커밋을 보유한 [백그라운드 세션](/docs/ko/agent-view#what-deleting-a-session-removes)을 삭제하려고 했습니다. Claude Code는 커밋을 보지 않고 파괴하는 대신 worktree와 세션 행을 유지합니다. `claude rm`은 분기와 푸시되지 않은 커밋을 명시하고 진행 방법을 설명합니다:4636Claude Code가 다른 곳에 저장되었는지 확인할 수 없는 커밋을 worktree에 보유한 [백그라운드 세션](/docs/ko/agent-view#what-deleting-a-session-removes)을 삭제하려고 했습니다. Claude Code는 커밋을 보지 않고 파괴하는 대신 worktree와 세션 행을 유지합니다. `claude rm`은 브랜치와 푸시되지 않은 커밋을 명시하고 진행 방법을 설명합니다:

4599 4637

4600```text theme={null}4638```text theme={null}

4601kept 7c5dcf5d — its worktree is still at "/home/you/project/.claude/worktrees/fix-login"4639kept 7c5dcf5d — its worktree is still at “/home/you/project/.claude/worktrees/fix-login”

4602 2 unpushed commits on "claude/fix-login": a1b2c3d "Fix login flow" and 1 more. They exist on no remote, so deleting the worktree would lose them.4640 2 unpushed commits on “claude/fix-login”: a1b2c3d “Fix login flow” and 1 more. They exist on no remote, so deleting the worktree would lose them.

4603 push them and run 'claude rm 7c5dcf5d' again, or discard the worktree and its commits: claude rm 7c5dcf5d --discard-unpushed a1b2c3d000000000000000000000000000000000@0123456789abcdef0123456789abcdef4641 push them and run 'claude rm 7c5dcf5d' again, or discard the worktree and its commits: claude rm 7c5dcf5d --discard-unpushed a1b2c3d000000000000000000000000000000000@0123456789abcdef0123456789abcdef

4604```4642```

4605 4643

4606Claude Code가 커밋을 요약할 수 없으면 메시지는 `The worktree has unpushed commits`를 대신 읽습니다. [에이전트 뷰](/docs/ko/agent-view)에서 세션의 행은 `not deleted`를 표시하고 같은 이유를 표시합니다.4644Claude Code가 커밋을 요약할 수 없으면 세부 정보 줄에 `The worktree has unpushed commits`가 대신 표시됩니다. [에이전트 뷰](/docs/ko/agent-view)에서 세션의 행은 `not deleted`를 표시하고 같은 이유를 표시합니다.

4607 4645

4608원격의 커밋은 삭제를 차단하지 않습니다. 로컬 `origin` 원격의 기본 분기의 로컬 복사본의 커밋도 차단하지 않습니다. 해당 분기가 주 체크아웃(저장소 디렉토리 자체, worktree가 아님)에서 체크아웃되어 있는 한.4646원격의 커밋은 삭제를 차단하지 않습니다. `origin` 원격의 기본 브랜치의 로컬 복사본의 커밋도 차단하지 않습니다. 해당 브랜치가 주 체크아웃(저장소 디렉터리 자체, worktree가 아님)에서 체크아웃되어 있는 한.

4609 4647

4610**할 일:**4648**할 일:**

4611 4649

4612* 커밋을 유지하려면 worktree의 분기를 푸시하거나 주 체크아웃에서 체크아웃된 기본 분기로 병합한 다음 세션을 다시 삭제합니다.4650* 커밋을 유지하려면 worktree의 브랜치를 푸시하거나 주 체크아웃에서 체크아웃된 기본 브랜치로 병합한 다음 세션을 다시 삭제합니다.

4613* 커밋을 버리려면 메시지가 인쇄한 `claude rm <id> --discard-unpushed` 명령을 실행하거나 에이전트 뷰의 세션 행에서 `Ctrl+X`를 두 번 누릅니다. 이는 세션과 worktree를 분기, 푸시되지 않은 커밋 및 커밋되지 않은 변경 사항과 함께 제거합니다. worktree가 거부 이후 커밋을 얻으면 Claude Code는 다시 유지하고 업데이트된 상태를 표시합니다.4651* 커밋을 버리려면 메시지가 인쇄한 `claude rm <id> --discard-unpushed` 명령을 실행하거나 에이전트 뷰의 세션 행에서 `Ctrl+X`를 다시 두 번 누릅니다. 이는 세션과 worktree를 브랜치, 푸시되지 않은 커밋 및 커밋되지 않은 변경 사항과 함께 제거합니다. worktree가 거부 이후 커밋을 얻으면 Claude Code는 다시 유지하고 업데이트된 상태를 표시합니다.

4614* 메시지가 worktree가 다른 완료된 세션에 의해서도 기록되었다고 말하면 다시 삭제해도 버리지 않습니다: 커밋을 푸시한 다음 세션을 다시 삭제합니다.4652* 메시지가 worktree가 다른 완료된 세션에 의해서도 기록되었다고 말하면 다시 삭제해도 버리지 않습니다: 커밋을 푸시한 다음 세션을 다시 삭제합니다.

4615 4653

4616v2.1.268 이전에는 `claude rm`이 커밋 요약을 `kept` 줄 자체에 배치했습니다. `claude rm`이 커밋을 요약할 수 없으면 `kept` 줄은 요약 대신 `worktree has commits that are not pushed anywhere`를 읽었습니다.4654v2.1.268 이전에는 `claude rm`이 커밋 요약을 `kept` 줄 자체에 배치했습니다. `claude rm`이 커밋을 요약할 수 없으면 `kept` 줄은 요약 대신 `worktree has commits that are not pushed anywhere`를 표시했습니다.

4617 4655

4618v2.1.260 이전에는 메시지가 분기 또는 커밋을 명시하지 않았으며, 다시 삭제하는 것은 같은 방식으로 거부되었습니다: 푸시하지 않고 세션을 삭제하는 것은 `git worktree remove --force <path>`로 worktree를 직접 제거한 다음 `claude rm <id>`를 다시 실행하는 것을 의미했습니다.4656v2.1.260 이전에는 메시지가 브랜치 또는 커밋을 명시하지 않았으며, 다시 삭제하는 것은 같은 방식으로 거부되었습니다: 푸시하지 않고 세션을 삭제하는 것은 `git worktree remove --force <path>`로 worktree를 직접 제거한 다음 `claude rm <id>`를 다시 실행하는 것을 의미했습니다.

4619 4657

4620v2.1.248 이전에는 주 체크아웃에서 체크아웃된 기본 분기가 계산되지 않았습니다: 이미 병합한 분기는 커밋이 원격에 도달할 때까지 이 거부를 트리거했습니다.4658v2.1.248 이전에는 주 체크아웃에서 체크아웃된 기본 브랜치가 계산되지 않았습니다: 이미 병합한 브랜치는 커밋이 원격에 도달할 때까지 이 거부를 트리거했습니다.

4621 4659

4622<h3 id="terminal-host-process-died">4660<h3 id="terminal-host-process-died">

4623 터미널 호스트 프로세스가 종료됨4661 터미널 호스트 프로세스가 종료됨

4631terminal host process died — press Enter to restart4669terminal host process died — press Enter to restart

4632```4670```

4633 4671

4634확인이 실행되기 전에 행을 열면 바닥글에 `This session's terminal host process died (the conversation is saved) — press Enter to restart it`가 표시되고 행이 실패로 변합니다.4672셸에서 `claude attach <id>`는 이미 죽은 호스트로 실패 표시된 세션을 다시 시작하고, 그렇지 않으면 원인을 인쇄하고 종료합니다:

~~4635~~

4636셸에서 `claude attach <id>`는 이미 죽은 호스트로 표시된 세션을 다시 시작하고, 그렇지 않으면 원인을 인쇄하고 종료합니다:

4637 4673

4638```text theme={null}4674```text theme={null}

4639Couldn't attach to <id> — This session's terminal host process died (the conversation is saved) — run `claude attach <id>` again to restart it on a fresh host.4675Couldn't attach to <id> — This session's terminal host process died (the conversation is saved) — run `claude attach <id>` again to restart it on a fresh host.

4641 4677

4642어느 쪽이든 대화가 저장됩니다.4678어느 쪽이든 대화가 저장됩니다.

4643 4679

4644[셸 명령](/docs/ko/agent-view#run-a-shell-command)을 실행하는 행은 대신 `terminal host process died — its output is gone; the command was not run again`을 표시하고, `claude attach`는 `This command's terminal host process died — its output is gone and the command was not run again`을 인쇄합니다. Claude Code는 절대 명령을 다시 실행하지 않습니다.4680[셸 명령](/docs/ko/agent-view#run-a-shell-command)을 실행하는 행은 대신 `terminal host process died — its output is gone; the command was not run again`을 표시하고, `claude attach`는 `This command's terminal host process died — its output is gone and the command was not run again`을 인쇄합니다. Claude Code는 절대 명령을 대신 다시 실행하지 않습니다.

4645 4681

4646**할 일:**4682**할 일:**

4647 4683

4698 세션 에이전트를 더 이상 사용할 수 없습니다4734 세션 에이전트를 더 이상 사용할 수 없습니다

4699</h3>4735</h3>

4700 4736

4701[사용자 정의 에이전트](/docs/ko/sub-agents#invoke-subagents-explicitly)를 실행 중이던 세션을 재개했으며, `--agent` 또는 `agent` 설정으로 시작했으며, Claude Code가 해당 이름의 에이전트를 찾지 못했습니다. 세션의 원래 디렉토리를 먼저 검색하며, [해당 작업 공간을 신뢰](/docs/ko/permissions#project-allow-rules-and-workspace-trust)한 경우, 그 다음 재개하는 디렉토리를 검색합니다. 세션은 여전히 재개되지만 기본 도구를 사용하므로 에이전트의 도구 제한이 더 이상 적용되지 않습니다:4737[사용자 정의 에이전트](/docs/ko/sub-agents#invoke-subagents-explicitly)를 실행 중이던 세션을 재개했으며, `--agent` 또는 `agent` 설정으로 시작했으며, Claude Code가 해당 이름의 에이전트를 찾지 못했습니다. 세션의 원래 디렉터리를 먼저 검색하며, [해당 워크스페이스를 신뢰](/docs/ko/permissions#project-allow-rules-and-workspace-trust)한 경우, 그 다음 재개하는 디렉터리를 검색합니다. 세션은 여전히 재개되지만 기본 도구를 사용하므로 에이전트의 도구 제한이 더 이상 적용되지 않습니다:

4702 4738

4703```text theme={null}4739```text theme={null}

4704This session was running agent 'code-reviewer', which is no longer available (no agent by that name in /home/you/project). Continuing with the default tools and system prompt — the agent's tool restrictions no longer apply. To restore it, re-create the agent, or resume with an explicit --agent <name>.4740This session was running agent 'code-reviewer', which is no longer available (no agent by that name in /home/you/project). Continuing with the default tools and system prompt — the agent's tool restrictions no longer apply. To restore it, re-create the agent, or resume with an explicit --agent <name>.

4705```4741```

4706 4742

4707경고는 Claude Code가 검색한 디렉토리만 명시하며, [백그라운드 세션](/docs/ko/agent-view)을 깨우거나, `/resume` 또는 `claude --resume`을 실행하거나, [비대화형 모드](/docs/ko/headless)에서 재개할 때 재개된 대화에 나타나며, 여기서 stderr로도 이동합니다. `--input-format stream-json`을 사용하는 세션은 Agent SDK가 시작 후 에이전트를 제공하므로 표시하지 않습니다.4743경고는 Claude Code가 검색한 디렉터리만 명시하며, [백그라운드 세션](/docs/ko/agent-view)을 깨우거나, `/resume` 또는 `claude --resume`을 실행하거나, [비대화형 모드](/docs/ko/headless)에서 재개할 때 재개된 대화에 나타나며, 비대화형 모드에서는 stderr로도 출력됩니다. `--input-format stream-json`을 사용하는 세션은 Agent SDK가 시작 후 에이전트를 제공하므로 표시하지 않습니다.

4708 4744

4709Claude Code는 폴백을 세션에 저장하지 않으므로 경고는 조치할 때까지 각 재개에서 반복됩니다. 기본 제공 `claude` 에이전트는 기본 도구 세트로 폴백해도 아무것도 변경되지 않으므로 경고를 트리거하지 않습니다. v2.1.216 이전에는 Claude Code가 기본 에이전트로 자동으로 계속했으며, 조회는 재개하는 디렉토리만 포함했으므로 프로젝트 범위 에이전트는 다른 디렉토리에서 재개할 때 손실되었습니다.4745Claude Code는 폴백을 세션에 저장하지 않으므로 경고는 조치할 때까지 각 재개에서 반복됩니다. 기본 제공 `claude` 에이전트는 기본 도구 세트로 폴백해도 아무것도 변경되지 않으므로 경고를 트리거하지 않습니다. v2.1.216 이전에는 Claude Code가 기본 에이전트로 자동으로 계속했으며, 조회는 재개하는 디렉터리만 포함했으므로 프로젝트 범위 에이전트는 다른 디렉터리에서 재개할 때 손실되었습니다.

4710 4746

4711**할 일:**4747**할 일:**

4712 4748

4713* 세션의 프로젝트에서 `.claude/agents/<name>.md`에 또는 개인 에이전트의 경우 `~/.claude/agents/<name>.md`에 에이전트 파일을 다시 만든 다음 다시 재개합니다.4749* 세션의 프로젝트에서 `.claude/agents/<name>.md`에 또는 개인 에이전트의 경우 `~/.claude/agents/<name>.md`에 에이전트 파일을 다시 만든 다음 다시 재개합니다.

4714* 또는 존재하는 에이전트를 명시하는 `--agent <name>`으로 재개하여 대신 해당 에이전트로 세션을 실행합니다.4750* 또는 존재하는 에이전트를 명시하는 `--agent <name>`으로 재개하여 대신 해당 에이전트로 세션을 실행합니다.

4715* 에이전트가 프로젝트 범위이고 세션의 원래 디렉토리를 신뢰하지 않았으면 거기서 Claude Code를 한 번 실행하고 신뢰 대화를 수락한 다음 다시 재개합니다.4751* 에이전트가 프로젝트 범위이고 세션의 원래 디렉터리를 신뢰하지 않았으면 거기서 Claude Code를 한 번 실행하고 신뢰 대화 상자를 수락한 다음 다시 재개합니다.

4716 4752

4717<h3 id="claude_code_process_wrapper-launcher-errors">4753<h3 id="claude_code_process_wrapper-launcher-errors">

4718 CLAUDE\_CODE\_PROCESS\_WRAPPER 런처 오류4754 CLAUDE\_CODE\_PROCESS\_WRAPPER 런처 오류

4744 4780

4745일부 계정에서 메시지는 `background service` 대신 `daemon`을 말합니다.4781일부 계정에서 메시지는 `background service` 대신 `daemon`을 말합니다.

4746 4782

4747npm 설치에서 `npm install -g @anthropic-ai/claude-code`가 바이너리를 대체하는 동안 나타나는 `EUNKNOWN`은 [백그라운드 세션을 시작할 때 EACCES](#eacces-when-starting-a-background-session)와 같은 원인을 가지며 설치가 완료된 후 재시도할 때 지워집니다.4783npm 설치에서 `npm install -g @anthropic-ai/claude-code`가 바이너리를 대체하는 동안 나타나는 `EUNKNOWN`은 [재설치 중 `EACCES`](#eacces-when-starting-a-background-session)와 같은 원인을 가지며 설치가 완료된 후 재시도할 때 지워집니다.

4748 4784

4749Claude Code는 서비스가 터미널을 닫을 때 생존하도록 PowerShell을 통해 백그라운드 서비스를 시작하며, PowerShell 7이 설치되어 있으면 PowerShell 7을 사용하고 그렇지 않으면 Windows PowerShell 5.1을 사용합니다. PowerShell이 실행될 수 없으면 Claude Code는 대신 서비스를 직접 시작하므로 PowerShell만 차단하는 정책은 이 오류를 발생시키지 않습니다.4785Claude Code는 서비스가 터미널을 닫을 때 생존하도록 PowerShell을 통해 백그라운드 서비스를 시작하며, PowerShell 7이 설치되어 있으면 PowerShell 7을 사용하고 그렇지 않으면 Windows PowerShell 5.1을 사용합니다. 어느 PowerShell도 실행될 수 없으면 Claude Code는 대신 서비스를 직접 시작하므로 PowerShell만 차단하는 정책은 이 오류를 발생시키지 않습니다.

4750 4786

4751v2.1.212 이전에는 Claude Code가 Windows PowerShell 5.1만 사용하여 서비스를 시작했으므로 그룹 정책이 PowerShell 5.1을 차단한 모든 머신이 `Couldn't start the session — EUNKNOWN: unknown error, uv_spawn`으로 실패했으며, PowerShell 7이 설치되어 있었습니다.4787v2.1.212 이전에는 Claude Code가 Windows PowerShell 5.1만 사용하여 서비스를 시작했으므로 그룹 정책이 PowerShell 5.1을 차단한 모든 머신이 PowerShell 7이 설치되어 있어도 `Couldn't start the session — EUNKNOWN: unknown error, uv_spawn`으로 실패했습니다.

4752 4788

4753**할 일:**4789**할 일:**

4754 4790

4755* 메시지가 `Couldn't start the session`을 읽으면 v2.1.212 이상으로 업그레이드합니다. 이전 버전에서는 별도의 터미널에서 `claude daemon run`을 먼저 실행한 다음 백그라운드 세션을 다시 시작할 수 있습니다. 해당 명령은 백그라운드 서비스를 터미널의 전경에서 실행하므로 서비스는 해당 터미널이 열려 있는 동안만 지속됩니다.4791* 메시지가 `Couldn't start the session`이면 v2.1.212 이상으로 업그레이드합니다. 이전 버전에서는 별도의 터미널에서 `claude daemon run`을 먼저 실행한 다음 백그라운드 세션을 다시 시작할 수 있습니다. 해당 명령은 백그라운드 서비스를 터미널의 전경에서 실행하므로 서비스는 해당 터미널이 열려 있는 동안만 지속됩니다.

4756* npm 설치가 바이너리를 대체 중이면 완료될 때까지 기다린 다음 백그라운드 세션을 다시 시작합니다.4792* npm 설치가 바이너리를 대체 중이면 완료될 때까지 기다린 다음 백그라운드 세션을 다시 시작합니다.

4757* npm 설치가 실행 중이 아닌 동안 v2.1.212 이상에서 오류가 나타나면 Windows 관리자에게 제한 정책에서 Claude Code 실행 파일을 허용하도록 요청합니다.4793* npm 설치가 실행 중이 아닌 동안 v2.1.212 이상에서 오류가 나타나면 제한 정책이 Claude Code 실행 파일을 차단하는지 Windows 관리자에게 확인합니다.

4758* 터미널을 닫을 때 백그라운드 서비스가 중지되면 Claude Code는 PowerShell 없이 시작했습니다. PowerShell 7을 설치하거나 관리자에게 PowerShell을 차단 해제하도록 요청하여 서비스가 터미널을 초과할 수 있도록 합니다.4794* 터미널을 닫을 때 백그라운드 서비스가 중지되면 Claude Code는 PowerShell 없이 시작했습니다. PowerShell 7을 설치하거나 관리자에게 PowerShell을 차단 해제하도록 요청하여 서비스가 터미널보다 오래 유지될 수 있도록 합니다.

4759 4795

4760<h3 id="eacces-when-starting-a-background-session">4796<h3 id="eacces-when-starting-a-background-session">

4761 백그라운드 세션을 시작할 때 EACCES4797 백그라운드 세션을 시작할 때 EACCES

4762</h3>4798</h3>

4763 4799

4764Claude Code는 [백그라운드 서비스](/docs/ko/agent-view#the-supervisor-process)를 시작하기 위해 자신의 바이너리를 실행할 수 없었습니다. npm 설치에서 이는 일반적으로 `npm install -g @anthropic-ai/claude-code`가 그 순간에 바이너리를 대체했다는 의미입니다. 직접 실행했든 [자동 업데이터](/docs/ko/setup#auto-updates)가 실행했든 상관없습니다. 오류는 [에이전트 뷰](/docs/ko/agent-view)에서 세션을 열 때 나타납니다:4800Claude Code는 백그라운드 세션을 호스팅하는 [백그라운드 서비스](/docs/ko/agent-view#the-supervisor-process)를 시작하기 위해 자신의 바이너리를 실행할 수 없었습니다. npm 설치에서 이는 일반적으로 `npm install -g @anthropic-ai/claude-code`가 그 순간에 바이너리를 대체했다는 의미입니다. 직접 실행했든 [자동 업데이터](/docs/ko/setup#auto-updates)가 실행했든 상관없습니다. 오류는 [에이전트 뷰](/docs/ko/agent-view)에서 세션을 열 때 나타납니다:

4765 4801

4766```text theme={null}4802```text theme={null}

4767Couldn't start the background service — spawn background service: EACCES: permission denied, posix_spawn '/usr/local/lib/node_modules/@anthropic-ai/claude-code/bin/claude'4803Couldn't start the background service — spawn background service: EACCES: permission denied, posix_spawn '/usr/local/lib/node_modules/@anthropic-ai/claude-code/bin/claude'

4780**할 일:**4816**할 일:**

4781 4817

4782* 몇 초 기다린 다음 세션을 열거나 다시 디스패치합니다. 메시지가 Claude Code가 업데이트 중이라고 말하면 업데이트가 완료된 후 재시도합니다.4818* 몇 초 기다린 다음 세션을 열거나 다시 디스패치합니다. 메시지가 Claude Code가 업데이트 중이라고 말하면 업데이트가 완료된 후 재시도합니다.

4783* npm 설치가 실행 중이 아닌 동안 오류가 지속되면 사용자가 설치된 바이너리를 실행할 수 없습니다. 권한과 디렉토리를 확인하거나 Claude Code를 다시 설치합니다.4819* npm 설치가 실행 중이 아닌 동안 오류가 지속되면 사용자가 설치된 바이너리를 실행할 수 없습니다. 바이너리와 해당 디렉터리의 권한을 확인하거나 Claude Code를 다시 설치합니다.

4784 4820

4785<h3 id="background-service-exited-before-it-became-reachable">4821<h3 id="background-service-exited-before-it-became-reachable">

4786 백그라운드 서비스가 도달 가능해지기 전에 종료됨4822 백그라운드 서비스가 도달 가능해지기 전에 종료됨

4787</h3>4823</h3>

4788 4824

4789Claude Code가 [백그라운드 서비스](/docs/ko/agent-view#the-supervisor-process)로 시작한 프로세스가 연결을 수락하기 전에 종료되어 Claude Code가 세션을 열 수 없었습니다. 서비스가 종료되기 전에 오류를 인쇄했으면 괄호의 이유는 종료 코드 또는 신호와 서비스가 인쇄한 첫 번째 줄을 제공하며, 이는 중지된 것을 명시합니다:4825Claude Code가 [백그라운드 서비스](/docs/ko/agent-view#the-supervisor-process)로 시작한 프로세스가 연결을 수락하기 전에 종료되어 Claude Code가 세션을 열 수 없었습니다. 서비스가 종료되기 전에 오류를 인쇄했으면 괄호의 이유는 종료 코드 또는 신호와 서비스가 인쇄한 첫 번째 줄을 제공하며, 이는 중지된 원인을 명시합니다:

4790 4826

4791```text theme={null}4827```text theme={null}

4792Couldn't reach the background service (background service exited before it became reachable (exit code N): <the service's first error line>) — run 'claude daemon status'4828Couldn't reach the background service (background service exited before it became reachable (exit code N): <the service's first error line>) — run 'claude daemon status'

4793```4829```

4794 4830

4795[에이전트 뷰](/docs/ko/agent-view)에서 세션을 열 때 같은 이유가 `Couldn't start the background service —`를 따릅니다. 서비스가 종료되기 전에 아무것도 인쇄하지 않으면 메시지는 `nothing on stderr`을 대신 말합니다.4831[에이전트 뷰](/docs/ko/agent-view)에서 세션을 열 때 같은 이유가 `Couldn't start the background service —` 뒤에 나타납니다. 서비스가 종료되기 전에 아무것도 인쇄하지 않으면 메시지는 `nothing on stderr`을 대신 말합니다.

4796 4832

4797Claude Code는 서비스의 오류 줄로 실패를 보고합니다. v2.1.246 이전에는 실패가 45초 대기 후에만 표시되었으며, `background service did not become reachable within 45s`로 서비스의 오류 줄 없이 표시되었습니다.4833Claude Code는 서비스의 오류 줄로 실패를 보고합니다. v2.1.246 이전에는 실패가 45초 대기 후에만 표시되었으며, `background service did not become reachable within 45s`로 서비스의 오류 줄 없이 표시되었습니다.

4798 4834

4799두 인용된 이유는 알려진 원인을 가집니다:4835두 인용된 이유는 알려진 원인을 가집니다:

4800 4836

4801* `Error: claude native binary not installed.`: npm 설치가 그 순간에 Claude Code 바이너리를 대체했으므로 서비스가 npm의 자리 표시자를 대신 실행했습니다. 설치가 완료된 후 재시도합니다. 설치가 실행 중이 아닌 동안 줄이 지속되면 [npm 설치를 완료](/docs/ko/troubleshoot-install#native-binary-not-found-after-npm-install)합니다. v2.1.257 이전에는 macOS npm 자체 업데이트가 설치 창 동안 모든 시작에서 이 실패를 생성했습니다.4837* `Error: claude native binary not installed.`: npm 설치가 그 순간에 Claude Code 바이너리를 대체했으므로 서비스가 npm의 자리 표시자를 대신 실행했습니다. 설치가 완료된 후 재시도합니다. 설치가 실행 중이 아닌 동안 줄이 지속되면 [npm 설치를 완료](/docs/ko/troubleshoot-install#native-binary-not-found-after-npm-install)합니다. v2.1.257 이전에는 macOS npm 자체 업데이트가 설치 창 동안 모든 시작에서 이 실패를 생성했습니다.

4802* Windows에서 모든 시작에서 종료 코드 1로 `nothing on stderr`: `daemon.lock`은 Claude Code가 신호를 보낼 수도 없고 종료되었음을 증명할 수도 없는 프로세스를 명시하므로 각 새 서비스는 다른 서비스가 잠금을 보유한다고 결론짓고 종료합니다. Claude Code가 종료되었음을 증명할 수 있는 잠금은 자동으로 대체되며 이 실패를 생성하지 않습니다. 실패가 모든 시작에서 반복되면 `~/.claude/daemon.lock`을 삭제한 다음 세션을 열거나 다시 디스패치합니다. v2.1.257 이전에는 그러한 잠금이 파일을 삭제할 때까지 모든 시작을 차단했습니다.4838* Windows에서 모든 시작에서 종료 코드 1로 `nothing on stderr`: `daemon.lock`은 Claude Code가 신호를 보낼 수도 없고 종료되었음을 증명할 수도 없는 프로세스를 명시하므로 각 새 서비스는 다른 서비스가 잠금을 보유한다고 결론짓고 종료합니다. Claude Code가 작성자가 종료되었음을 증명할 수 있는 잠금은 자동으로 대체되며 이 실패를 생성하지 않습니다. 실패가 모든 시작에서 반복되면 `~/.claude/daemon.lock`을 삭제한 다음 세션을 열거나 다시 디스패치합니다. v2.1.257 이전에는 그러한 잠금이 파일을 삭제할 때까지 모든 시작을 차단했습니다.

4803 4839

4804**할 일:**4840**할 일:**

4805 4841

4807* `claude daemon status`를 실행하여 서비스가 지금 실행 중인지 확인합니다.4843* `claude daemon status`를 실행하여 서비스가 지금 실행 중인지 확인합니다.

4808 4844

4809<h3 id="working-directory-no-longer-exists-when-starting-a-background-session">4845<h3 id="working-directory-no-longer-exists-when-starting-a-background-session">

4810 백그라운드 세션을 시작할 때 작업 디렉토리가 더 이상 존재하지 않음4846 백그라운드 세션을 시작할 때 작업 디렉터리가 더 이상 존재하지 않음

4811</h3>4847</h3>

4812 4848

4813더 이상 존재하지 않는 디렉토리에서 [백그라운드 세션](/docs/ko/agent-view)을 시작하려고 했습니다. Claude Code는 세션을 시작하지 않으며 메시지는 누락된 디렉토리를 명시합니다:4849[백그라운드 세션](/docs/ko/agent-view)을 시작한 디렉터리가 세션이 시작되는 동안 제거되었습니다. Claude Code는 세션을 시작하지 않으며 메시지는 누락된 디렉터리를 명시합니다:

4814 4850

4815```text theme={null}4851```text theme={null}

4816Couldn't start a background session (working directory no longer exists or is not accessible: /tmp/demo)4852Couldn't start a background session (working directory no longer exists or is not accessible: /tmp/demo)

4818 4854

4819v2.1.257 이전에는 세션이 시작된 것처럼 보였다가 에이전트 뷰에서 같은 이유로 실패한 행으로 표시되었습니다.4855v2.1.257 이전에는 세션이 시작된 것처럼 보였다가 에이전트 뷰에서 같은 이유로 실패한 행으로 표시되었습니다.

4820 4856

4821v2.1.281 이전에는 이 메시지가 세션을 시작하기 전에 디렉토리가 이미 없었을 때도 나타났습니다. 그 경우는 [`could not be resolved on disk`](#workspace-not-trusted-when-dispatching-a-background-session)를 보고합니다.4857v2.1.281 이전에는 이 메시지가 세션을 시작하기 전에 디렉터리가 이미 없었을 때도 나타났습니다. 그 경우는 [`could not be resolved on disk`](#workspace-not-trusted-when-dispatching-a-background-session)를 보고합니다.

4822 4858

4823**할 일:**4859**할 일:**

4824 4860

4825* 메시지가 명시하는 디렉토리를 다시 만들거나 존재하는 디렉토리에서 디스패치한 다음 다시 시도합니다.4861* 메시지가 명시하는 디렉터리를 다시 만들거나 존재하는 디렉터리에서 디스패치한 다음 다시 시도합니다.

4826 4862

4827<h3 id="workspace-not-trusted-when-dispatching-a-background-session">4863<h3 id="workspace-not-trusted-when-dispatching-a-background-session">

4828 백그라운드 세션을 디스패치할 때 작업 공간을 신뢰하지 않음4864 백그라운드 세션을 디스패치할 때 워크스페이스를 신뢰하지 않음

4829</h3>4865</h3>

4830 4866

4831[신뢰하지 않은](/docs/ko/permissions#project-allow-rules-and-workspace-trust) 디렉토리에서 [백그라운드 세션](/docs/ko/agent-view)을 시작하거나 다시 시작했으며, 작업 공간 신뢰 대화가 나타날 수 없었습니다. Claude Code는 세션을 시작하지 않습니다:4867[신뢰하지 않은](/docs/ko/permissions#project-allow-rules-and-workspace-trust) 디렉터리에서 [백그라운드 세션](/docs/ko/agent-view)을 시작하거나 다시 시작했으며, 워크스페이스 신뢰 대화 상자가 나타나 확인을 요청할 수 없었습니다. Claude Code는 세션을 시작하지 않습니다:

4832 4868

4833```text theme={null}4869```text theme={null}

4834Workspace not trusted. Run `claude` in /path/to/project once and accept the trust prompt, then retry.4870Workspace not trusted. Run `claude` in /path/to/project once and accept the trust prompt, then retry.

4835```4871```

4836 4872

4837세션의 자체 디렉토리의 터미널에서 같은 명령은 신뢰 대화를 대신 표시하고 수락하면 세션을 시작합니다. 이 메시지는 스크립트와 같이 대화가 나타날 수 없는 곳이나 다른 디렉토리에서 세션을 다시 시작할 때 나타납니다.4873세션의 자체 디렉터리의 터미널에서 같은 명령은 신뢰 대화 상자를 대신 표시하고 수락하면 세션을 시작합니다. 이 메시지는 스크립트와 같이 대화 상자가 나타날 수 없는 곳이나 세션 자체 디렉터리가 아닌 다른 디렉터리에서 세션을 다시 시작할 때 나타납니다.

4838 4874

4839두 가지 변형은 다른 원인을 명시합니다:4875두 가지 변형은 다른 원인을 명시합니다:

4840 4876

4841* **`The home directory is trusted one session at a time`**: 세션의 디렉토리는 홈 디렉토리입니다. Claude Code는 홈 디렉토리에 대한 신뢰를 절대 저장하지 않으므로 이전 세션에서 대화를 수락해도 계산되지 않습니다.4877* **`The home directory is trusted one session at a time`**: 세션의 디렉터리는 홈 디렉터리입니다. Claude Code는 홈 디렉터리에 대한 신뢰를 절대 저장하지 않으므로 이전 세션에서 그곳의 대화 상자를 수락해도 계산되지 않습니다.

4842* **`<path> could not be resolved on disk`**: Claude Code가 디스크에서 세션의 디렉토리를 찾을 수 없었습니다.4878* **`<path> could not be resolved on disk`**: Claude Code가 디스크에서 세션의 디렉터리를 찾을 수 없었습니다.

4879

4880v2.1.286 이전에는 Windows에서 신뢰 기록이 다른 대소문자의 경로로 저장된 경우 이미 신뢰한 디렉터리에서도 이 메시지가 나타날 수 있었습니다. v2.1.286 이상으로 업데이트하십시오.

4843 4881

4844**할 일:**4882**할 일:**

4845 4883

4846* 메시지가 명시하는 디렉토리에서 `claude`를 실행하고 신뢰 대화를 수락한 다음 명령을 다시 실행합니다.4884* 메시지가 명시하는 디렉터리에서 `claude`를 실행하고 신뢰 대화 상자를 수락한 다음 명령을 다시 실행합니다.

4847* 홈 디렉토리 메시지의 경우 홈 디렉토리의 터미널에서 명령을 실행하여 대화가 나타날 수 있도록 하거나 프로젝트 디렉토리에서 대신 세션을 시작합니다.4885* 홈 디렉터리 메시지의 경우 홈 디렉터리의 터미널에서 명령을 실행하여 대화 상자가 나타날 수 있도록 하거나 프로젝트 디렉터리에서 대신 세션을 시작합니다.

4848* `could not be resolved on disk` 메시지의 경우 디렉토리를 다시 만들거나 존재하는 디렉토리에서 새 세션을 시작합니다.4886* `could not be resolved on disk` 메시지의 경우 디렉터리를 다시 만들거나 존재하는 디렉터리에서 새 세션을 시작합니다.

4849 4887

4850<h2 id="wrapper-and-ide-errors">4888<h2 id="wrapper-and-ide-errors">

4851 래퍼 및 IDE 오류4889 래퍼 및 IDE 오류

5026 구성 경고5064 구성 경고

5027</h2>5065</h2>

5028 5066

5029Claude Code는 이러한 메시지 대부분을 대화가 아닌 stderr에 기록하며, 대부분 시작 시에 기록합니다. 항목이 디버그 로그나 대화 보기의 시작 알림 같은 다른 곳에 나타나거나 요청 시간의 [인식되지 않은 모델 진단 줄](#unrecognized-model-id-on-a-request) 같은 다른 시간에 나타나면 그렇게 표시됩니다.5067Claude Code는 이러한 메시지 대부분을 대화가 아닌 stderr에 기록하며, 대부분 시작 시에 기록합니다. 메시지가 디버그 로그나 대화 보기의 시작 알림 같은 다른 곳에 나타나거나, 요청 시점의 [인식되지 않은 모델 진단 줄](#unrecognized-model-id-on-a-request)처럼 다른 시점에 나타나는 경우 해당 항목에 그렇게 명시되어 있습니다.

~~5030~~

5031<h3 id="fullscreen-failed-start-notice">

5032 전체 화면 렌더러가 시작을 완료하지 못함

5033</h3>

~~5034~~

5035이 머신의 이전 [전체 화면](/docs/ko/fullscreen) 세션이 시작을 완료하기 전에 종료되었으므로 Claude Code는 이 세션을 클래식 렌더러에서 시작하고 다음 알림 중 하나를 출력합니다:

~~5036~~

5037```text theme={null}

5038Claude Code의 전체 화면 렌더러가 이 머신에서 마지막으로 시작을 완료하지 못했으므로 이번 실행은 클래식 렌더러를 사용합니다. 다음 실행에서 전체 화면을 다시 시도할 것입니다. /tui default는 클래식 렌더러를 유지합니다.

~~5039~~

5040Claude Code의 전체 화면 렌더러가 이 머신에서 반복적으로 시작에 실패했으므로 여기서 비활성화되었습니다. /tui fullscreen을 실행하여 다시 시도하세요(이는 업데이트 후에도 재설정됩니다).

5041```

~~5042~~

5043**할 일:**

~~5044~~

5045* [전체 화면 렌더링](/docs/ko/fullscreen#fullscreen-renderer-didnt-finish-starting)을 따르세요. 어떤 알림을 받는지, Claude Code가 이후 세션에서 무엇을 하는지, 그리고 전체 화면을 다시 시도하거나 클래식 렌더러를 유지하는 방법을 설명합니다.

5046* 종료된 세션이 종료 메시지를 출력했다면 [Claude Code가 복구 불가능한 인터페이스 오류 후 종료됨](#exited-after-an-unrecoverable-interface-error)을 참조하여 이름이 지정된 내용을 확인하세요.

~~5047~~

5048v2.1.236 이전에는 Claude Code가 알림을 출력하지 않았고 실패한 시작 후에도 전체 화면 렌더링에서 세션을 계속 시작했습니다.

5049 5068

5050<h3 id="exited-after-an-unrecoverable-interface-error">5069<h3 id="exited-after-an-unrecoverable-interface-error">

5051 Claude Code가 복구 불가능한 인터페이스 오류 후 종료됨5070 Claude Code가 복구 불가능한 인터페이스 오류 후 종료됨

5052</h3>5071</h3>

5053 5072

5054Claude Code는 터미널 인터페이스가 복구할 수 없는 오류에 부딪혔을 때 이 메시지를 출력하고 종료합니다(두 렌더러 모두). 두 번째 문장은 [전체 화면](/docs/ko/fullscreen) 렌더러가 시작되는 동안 오류가 발생했을 때만 나타납니다:5073Claude Code는 터미널 인터페이스가 복구할 수 없는 오류에 부딪혀 종료될 때 이 메시지를 출력하며, 이는 두 렌더러 모두에서 발생할 수 있습니다. 두 번째 문장은 [전체 화면](/docs/ko/fullscreen) 렌더러가 시작되는 동안 오류가 발생했을 때만 나타납니다:

5055 5074

5056```text theme={null}5075```text theme={null}

5057Claude Code가 복구 불가능한 인터페이스 오류(<error>)로 인해 종료되었습니다. 전체 화면 렌더러가 시작되는 동안 발생했으므로 다음 실행은 클래식 렌더러를 사용할 것입니다(CLAUDE_CODE_DISABLE_ALTERNATE_SCREEN=1은 언제든지 이를 강제합니다).5076Claude Code exited after an unrecoverable interface error (<error>). It happened while the fullscreen renderer was starting, so the next launch will use the classic renderer (CLAUDE_CODE_DISABLE_ALTERNATE_SCREEN=1 forces that any time).

5058```5077```

5059 5078

5060**할 일:**5079**할 일:**

5061 5080

5062* Claude Code를 다시 시작하세요. 대화를 다시 시작하려면 같은 디렉토리에서 `claude --resume`을 실행하세요.5081* Claude Code를 다시 시작하세요. 대화를 이어서 진행하려면 같은 디렉터리에서 `claude --resume`을 실행하세요.

5063* 메시지가 전체 화면 렌더러를 언급하면 [전체 화면 렌더링](/docs/ko/fullscreen#fullscreen-renderer-didnt-finish-starting)에서 다음 실행이 무엇을 하는지, 전체 화면을 어떻게 켰는지에 따라 달라지는지, 그리고 전체 화면을 다시 시도하거나 클래식 렌더러를 유지하는 방법을 설명합니다.5082* 메시지가 전체 화면 렌더러를 언급하면 [전체 화면 렌더링](/docs/ko/fullscreen#fullscreen-renderer-didnt-finish-starting)에서 전체 화면을 켠 방식에 따라 다음 실행이 어떻게 동작하는지, 그리고 전체 화면을 다시 시도하거나 클래식 렌더러를 유지하는 방법을 확인하세요.

5064 5083

5065v2.1.236 이전에는 Claude Code가 이런 종류의 오류 후 메시지를 출력하지 않고 종료되었습니다.5084v2.1.236 이전에는 Claude Code가 이런 종류의 오류 후 메시지를 출력하지 않고 종료되었습니다.

5066 5085

5068 에이전트 설명이 15.0k 토큰 제한을 초과함5087 에이전트 설명이 15.0k 토큰 제한을 초과함

5069</h3>5088</h3>

5070 5089

5071Claude Code는 stderr가 아닌 대화 보기의 시작 알림으로 이 경고를 표시합니다. 기본 제공 에이전트를 제외한 [서브에이전트](/docs/ko/sub-agents)의 결합된 설명이 Claude Code가 추정하는 15,000 토큰을 초과합니다. 각 에이전트는 이름과 `description` frontmatter를 계산합니다. Claude Code는 합계가 제한을 초과하는지 여부와 관계없이 모든 에이전트를 로드하므로 경고는 로드되는 내용을 변경하지 않습니다.5090Claude Code는 stderr가 아닌 대화 보기의 시작 알림으로 이 경고를 표시합니다. 기본 제공 에이전트를 제외한 [서브에이전트](/docs/ko/sub-agents)의 설명을 합친 양이 Claude Code의 추정으로 15,000 토큰을 초과합니다. 각 에이전트는 이름과 `description` frontmatter가 계산에 포함됩니다. Claude Code는 합계가 제한을 초과하는지 여부와 관계없이 모든 에이전트를 로드하므로 이 경고는 로드되는 내용을 변경하지 않습니다.

5072 5091

5073```text theme={null}5092```text theme={null}

5074에이전트 설명이 15.0k 토큰 제한을 초과함(~16.2k 토큰) · Claude에게 .claude/agents/의 에이전트 설명을 정리하도록 요청하세요5093Agent descriptions are over the 15.0k-token limit (~16.2k tokens) · ask Claude to trim agent descriptions in .claude/agents/

5075```5094```

5076 5095

5077**할 일:**5096**할 일:**

5078 5097

5079* 에이전트 파일의 `description` frontmatter를 단축하거나 Claude에게 정리하도록 요청하세요.5098* 에이전트 파일의 `description` frontmatter를 줄이거나 Claude에게 정리하도록 요청하세요.

5080* 더 이상 사용하지 않는 에이전트 파일을 제거하세요.5099* 더 이상 사용하지 않는 에이전트 파일을 제거하세요.

5081 5100

5082<h3 id="a-skill-command-or-workflow-wasnt-loaded-because-its-name-is-reserved">5101<h3 id="a-skill-command-or-workflow-wasnt-loaded-because-its-name-is-reserved">

5083 스킬, 명령 또는 워크플로우가 로드되지 않았습니다(이름이 예약됨)5102 스킬, 명령 또는 워크플로가 로드되지 않았습니다(이름이 예약됨)

5084</h3>5103</h3>

5085 5104

5086스킬 폴더, frontmatter `name`, `.claude/commands/`의 파일 또는 하위 폴더, 또는 [저장된 워크플로우](/docs/ko/workflows#save-the-workflow-for-reuse)가 `anthropic-skills` 이름을 사용하거나 `anthropic-skills:`로 시작하는 이름을 사용합니다. Claude Code는 [claude.ai에서 동기화된 스킬을 위해 해당 이름을 예약](/docs/ko/skills#names-reserved-for-synced-skills)하고 해당 항목을 로드하지 않습니다.5105스킬 폴더, frontmatter `name`, `.claude/commands/`의 파일 또는 하위 폴더, 또는 [저장된 워크플로](/docs/ko/workflows#save-the-workflow-for-reuse)가 `anthropic-skills` 이름을 사용하거나 `anthropic-skills:`로 시작하는 이름을 사용합니다. Claude Code는 [claude.ai에서 동기화된 스킬을 위해 해당 이름을 예약](/docs/ko/skills#names-reserved-for-synced-skills)하며 해당 항목을 로드하지 않습니다.

5087 5106

5088Claude Code는 stderr가 아닌 대화 보기의 시작 알림으로 이 경고를 표시합니다:5107Claude Code는 stderr가 아닌 대화 보기의 시작 알림으로 이 경고를 표시합니다:

5089 5108

5090```text theme={null}5109```text theme={null}

5091로드되지 않음: .claude/skills/anthropic-skills의 이름을 바꾸고 다시 시작하세요 — 해당 이름은 "anthropic-skills"를 사용하며, 이는 claude.ai 계정에서 동기화된 스킬을 위해 예약된 이름입니다5110Not loaded: rename .claude/skills/anthropic-skills, then restart — its name uses "anthropic-skills", a name reserved for the skills synced from your claude.ai account

5092```5111```

5093 5112

5094알림은 거부된 첫 번째 항목에 대해 변경할 내용을 이름으로 지정합니다: 이름을 바꿀 폴더 또는 파일, 편집할 `name:` 줄, 또는 이름을 바꿀 워크플로우. 둘 이상의 항목이 거부되면 알림은 `· 2 more` 같은 개수로 끝나고 [디버그 로그](/docs/ko/debug-your-config)가 각각을 이름으로 지정합니다.5113알림은 거부된 첫 번째 항목에 대해 변경할 대상을 명시합니다: 이름을 바꿀 폴더 또는 파일, 편집할 `name:` 줄, 또는 이름을 바꿀 워크플로. 둘 이상의 항목이 거부되면 알림은 `· 2 more` 같은 개수로 끝나며 [디버그 로그](/docs/ko/debug-your-config)에 각 항목이 명시됩니다.

5095 5114

5096**할 일:**5115**할 일:**

5097 5116

5098* 알림이 이름으로 지정한 항목의 이름을 바꾸거나 가리키는 `name:` 줄을 편집한 후 세션을 다시 시작하세요.5117* 알림이 명시한 항목의 이름을 바꾸거나 알림이 가리키는 `name:` 줄을 편집한 후 세션을 다시 시작하세요.

5099 5118

5100v2.1.282 이전에는 Claude Code가 이러한 이름의 스킬과 명령을 로드했습니다.5119v2.1.282 이전에는 Claude Code가 이러한 이름의 스킬과 명령을 로드했습니다.

5101 5120

5102<h3 id="workspace-has-not-been-trusted">5121<h3 id="workspace-has-not-been-trusted">

5103 작업 영역이 신뢰되지 않음5122 워크스페이스가 신뢰되지 않음

5104</h3>5123</h3>

5105 5124

5106Claude Code는 프로젝트의 `.claude/settings.json` 또는 `.claude/settings.local.json`에서 `permissions.allow` 규칙 또는 `permissions.additionalDirectories` 항목을 찾았지만 [프로젝트 설정의 allow 규칙에는 작업 영역 신뢰가 필요](/docs/ko/permissions#project-allow-rules-and-workspace-trust)하기 때문에 적용하지 않았습니다. 개수, 설정 이름, 메시지에 이름이 지정된 파일은 구성에 따라 다릅니다. `deny` 및 `ask` 규칙은 영향을 받지 않습니다.5125Claude Code는 프로젝트의 `.claude/settings.json` 또는 `.claude/settings.local.json`에서 `permissions.allow` 규칙 또는 `permissions.additionalDirectories` 항목을 찾았지만 [프로젝트 설정의 허용 규칙에는 워크스페이스 신뢰가 필요](/docs/ko/permissions#project-allow-rules-and-workspace-trust)하기 때문에 적용하지 않았습니다. 메시지에 표시되는 개수, 설정 이름, 파일은 구성에 따라 다릅니다. `deny` 및 `ask` 규칙은 영향을 받지 않습니다.

5107 5126

5108```text theme={null}5127```text theme={null}

5109.claude/settings.local.json의 2개 permissions.allow 항목을 무시합니다: 이 작업 영역이 신뢰되지 않았습니다. 여기서 Claude Code를 대화형으로 한 번 실행하고 신뢰 대화를 수락하거나, /Users/you/.claude.json에서 projects["/Users/you/project"].hasTrustDialogAccepted: true를 설정하세요.5128Ignoring 2 permissions.allow entries from .claude/settings.local.json: this workspace has not been trusted. Run Claude Code interactively here once and accept the trust dialog, or set projects["/Users/you/project"].hasTrustDialogAccepted: true in /Users/you/.claude.json.

5110```5129```

5111 5130

5112**할 일:**5131**할 일:**

5113 5132

5114* 디렉토리에서 `claude`를 실행하고 신뢰 대화를 수락하세요. [프로젝트 allow 규칙 및 작업 영역 신뢰](/docs/ko/permissions#project-allow-rules-and-workspace-trust)는 해당 수락이 어느 폴더를 포함하는지 설명합니다.5133* 해당 디렉터리에서 `claude`를 실행하고 신뢰 대화 상자를 수락하세요. [프로젝트 허용 규칙 및 워크스페이스 신뢰](/docs/ko/permissions#project-allow-rules-and-workspace-trust)에서 해당 수락이 어느 폴더에 적용되는지 설명합니다.

5115* [비대화형 모드](/docs/ko/headless)에서 `-p`를 사용하면 대화가 표시되지 않습니다. 메시지가 출력하는 정확한 `projects` 키를 사용하여 `~/.claude.json`에서 `hasTrustDialogAccepted` 항목을 설정하세요.5134* `-p`를 사용하는 [비대화형 모드](/docs/ko/headless)에서는 대화 상자가 표시되지 않습니다. 메시지가 출력하는 정확한 `projects` 키를 사용하여 `~/.claude.json`에 `hasTrustDialogAccepted` 항목을 설정하세요.

5116* 메시지가 `.claude/settings.local.json`을 이름으로 지정하고 git 저장소 외부 또는 홈 디렉토리에서 Claude Code를 시작했다면 v2.1.200 이상으로 업데이트하세요. v2.1.196부터 v2.1.199까지의 버전은 이러한 작업 영역에서 자신의 `.claude/settings.local.json`을 저장소 제공으로 취급했습니다. v2.1.207 이상에서는 git 저장소 외부에서 업데이트하는 것만으로는 충분하지 않습니다(폴더를 신뢰하지 않은 경우): 폴더가 저장소 내부가 아님을 확인하면 git을 실행하고 Claude Code는 신뢰 대화를 수락한 후에만 해당 검사를 실행하므로 첫 번째 단계를 사용하세요. 홈 디렉토리 및 기타 [구성 홈](/docs/ko/permissions#project-allow-rules-and-workspace-trust)은 면제되며 대화를 기다리지 않습니다. [프로젝트 allow 규칙 및 작업 영역 신뢰](/docs/ko/permissions#project-allow-rules-and-workspace-trust)를 참조하세요.5135* 메시지가 `.claude/settings.local.json`을 명시하고 git 저장소 외부 또는 홈 디렉터리에서 Claude Code를 시작했다면 v2.1.200 이상으로 업데이트하세요. 버전 2.1.196부터 2.1.199까지는 이러한 워크스페이스에서 사용자 자신의 `.claude/settings.local.json`을 저장소에서 제공된 것으로 취급했습니다. v2.1.207 이상에서는 폴더를 신뢰하지 않은 경우 git 저장소 외부에서 업데이트만으로는 충분하지 않습니다. 폴더가 저장소 내부에 있지 않음을 확인하려면 git을 실행해야 하며, Claude Code는 신뢰 대화 상자를 수락한 후에만 이 검사를 실행하므로 첫 번째 단계를 사용하세요. 홈 디렉터리와 기타 [구성 홈](/docs/ko/permissions#project-allow-rules-and-workspace-trust)은 예외이며 대화 상자를 기다리지 않습니다. [프로젝트 허용 규칙 및 워크스페이스 신뢰](/docs/ko/permissions#project-allow-rules-and-workspace-trust)를 참조하세요.

5117 5136

5118<h3 id="working-directory-is-a-network-path">5137<h3 id="working-directory-is-a-network-path">

5119 작업 디렉토리가 네트워크 경로임5138 작업 디렉터리가 네트워크 경로임

5120</h3>5139</h3>

5121 5140

5122Claude Code는 네트워크 경로를 작업 디렉토리로 추가하지 않습니다. 네트워크 경로를 조회하면 이름이 지정된 호스트에 연결할 수 있으며, Windows에서는 해당 연결이 호스트에 자격 증명을 보낼 수 있으므로 Claude Code는 조회하지 않고 경로를 거부합니다. `/add-dir`을 이러한 경로로 실행할 때 또는 시작 시 경고로 이 메시지를 봅니다. 시작 시 나타나면 Claude Code는 해당 디렉토리 없이 시작합니다.5141Claude Code는 네트워크 경로를 작업 디렉터리로 추가하지 않습니다. 네트워크 경로를 조회하면 경로에 지정된 호스트에 연결할 수 있으며, Windows에서는 이 연결로 호스트에 자격 증명이 전송될 수 있으므로 Claude Code는 조회하지 않고 경로를 거부합니다. 이러한 경로로 `/add-dir`을 실행하거나 시작 시 경고로 이 메시지가 표시됩니다. 시작 시 나타나면 Claude Code는 해당 디렉터리 없이 시작합니다.

5123 5142

5124```text theme={null}5143```text theme={null}

5125\\server\share는 네트워크 경로이므로 작업 디렉토리로 추가할 수 없습니다. Windows에서는 공유를 드라이브 문자로 매핑하고 --add-dir로 실행 시 전달하세요(세션 중간에 추가된 드라이브 문자는 아직 원격 읽기 신뢰를 수행하지 않습니다).5144\\server\share is a network path, which cannot be added as a working directory. On Windows, map the share to a drive letter and pass it at launch with --add-dir (a drive letter added mid-session does not yet carry remote-read trust).

5126```5145```

5127 5146

5128Claude Code가 이 방식으로 거부하는 경로는 다음을 포함합니다:5147Claude Code가 이 방식으로 거부하는 경로는 다음과 같습니다:

5129 5148

5130* `\\server\share` 같은 UNC 공유5149* `\\server\share` 같은 UNC 공유

5131* `/net/<host>` 같은 자동 마운트 경로(해당 호스트의 자동 마운트 아래 디렉토리에서 Claude Code를 실행한 경우 제외)5150* `/net/<host>` 같은 자동 마운트 경로(해당 호스트의 자동 마운트 아래 디렉터리에서 Claude Code를 실행한 경우 제외)

5132* 기호 링크 또는 접합을 통해 네트워크 위치에 도달하는 로컬 경로5151* 심볼릭 링크 또는 정션을 통해 네트워크 위치에 도달하는 로컬 경로

5133 5152

5134매핑된 드라이브 문자 및 `\\wsl$` 경로는 네트워크 경로로 계산되지 않습니다.5153매핑된 드라이브 문자 및 `\\wsl$` 경로는 네트워크 경로로 간주되지 않습니다.

5135 5154

5136**할 일:**5155**할 일:**

5137 5156

5138* Windows에서는 `net use Z: \\server\share` 같은 명령으로 공유를 드라이브 문자로 매핑하고 `claude --add-dir Z:\`로 실행 시 드라이브를 전달하세요.5157* Windows에서는 `net use Z: \\server\share` 같은 명령으로 공유를 드라이브 문자에 매핑하고 `claude --add-dir Z:\`로 실행 시 해당 드라이브를 전달하세요.

5139* macOS 또는 Linux에서는 공유를 로컬 경로에 마운트하고 대신 해당 경로를 추가하세요.5158* macOS 또는 Linux에서는 공유를 로컬 경로에 마운트하고 대신 해당 경로를 추가하세요.

5140* 경로가 `permissions.additionalDirectories`에 있으면 이를 나열하는 설정 파일에서 제거하세요.5159* 경로가 `permissions.additionalDirectories`에 있으면 해당 경로를 나열한 설정 파일에서 제거하세요.

5141 5160

5142v2.1.257 이전에는 Claude Code가 도달 가능한 네트워크 경로를 작업 디렉토리로 수락했습니다.5161v2.1.257 이전에는 Claude Code가 도달 가능한 네트워크 경로를 작업 디렉터리로 수락했습니다.

5143 5162

5144<h3 id="remote-managed-settings-failed-to-load">5163<h3 id="remote-managed-settings-failed-to-load">

5145 원격 관리 설정을 로드하지 못함5164 원격 관리형 설정을 로드하지 못함

5146</h3>5165</h3>

5147 5166

5148세션이 [서버 관리 설정](/docs/ko/server-managed-settings)에 적합하지만 Claude Code가 설정을 가져올 수 없거나 서버가 반환한 내용을 적용할 수 없어서 대화형 세션에서 이 경고를 표시합니다.5167세션이 [서버 관리형 설정](/docs/ko/server-managed-settings) 적용 대상이지만 Claude Code가 설정을 가져오지 못했거나 서버가 반환한 내용을 적용하지 못했으므로 대화형 세션에서 이 경고를 표시합니다.

5149 5168

5150괄호로 묶인 원인은 `network error`, `request timed out`, 또는 `authentication rejected (401)` 같은 실패한 내용을 이름으로 지정합니다. `no setting in the server response could be applied as written` 원인은 서버가 응답했지만 반환된 설정 중 [검증](/docs/ko/server-managed-settings#invalid-entries-in-delivered-settings)을 통과한 것이 없음을 의미합니다. v2.1.282 이전에는 이 원인이 `server returned invalid settings`로 읽혔습니다.5169괄호 안의 원인은 `network error`, `request timed out`, `authentication rejected (401)`처럼 무엇이 실패했는지를 나타냅니다. `no setting in the server response could be applied as written` 원인은 서버가 응답했지만 반환된 설정 중 [검증](/docs/ko/server-managed-settings#invalid-entries-in-delivered-settings)을 통과한 것이 없음을 의미합니다. v2.1.282 이전에는 이 원인이 `server returned invalid settings`로 표시되었습니다.

5151 5170

5152줄의 나머지 부분은 세션이 실행되는 정책을 나타냅니다:5171줄의 나머지 부분은 세션이 어떤 정책으로 실행되는지를 나타냅니다:

5153 5172

5154* **이전 성공적인 가져오기에서 캐시된 설정**: Claude Code는 [보류된 환경 변수](/docs/ko/server-managed-settings#fetch-and-caching-behavior)를 제외한 해당 캐시된 정책에서 세션을 실행하며, 줄은 `using cached policy`로 읽습니다.5173* **이전에 성공한 가져오기에서 캐시된 설정**: Claude Code는 [보류된 환경 변수](/docs/ko/server-managed-settings#fetch-and-caching-behavior)를 제외한 캐시된 정책으로 세션을 실행하며, 줄에 `using cached policy`가 표시됩니다.

5155* **캐시 없음**: Claude Code는 서버 관리 설정 없이 세션을 실행하며, 줄은 `no remote policy applied`로 읽습니다.5174* **캐시 없음**: Claude Code는 서버 관리형 설정 없이 세션을 실행하며, 줄에 `no remote policy applied`가 표시됩니다.

5156 5175

5157**할 일:**5176**할 일:**

5158 5177

5159* 메시지가 이름으로 지정한 원인에 대해 조치하세요: 네트워크 원인의 경우 이 머신이 `api.anthropic.com`에 도달할 수 있는지 확인하세요. 인증 원인의 경우 `/status`로 로그인을 확인하세요.5178* 메시지가 명시한 원인에 따라 조치하세요: 네트워크 원인의 경우 이 머신이 `api.anthropic.com`에 도달할 수 있는지 확인하고, 인증 원인의 경우 `/status`로 로그인 상태를 확인하세요.

5160* `no setting in the server response could be applied as written`의 경우 관리자에게 서버의 설정을 수정하도록 요청하세요.5179* `no setting in the server response could be applied as written`의 경우 관리자에게 서버의 설정을 수정하도록 요청하세요.

5161* 전체 진단을 위해 `/status` 또는 `claude doctor`를 실행하세요.5180* 전체 진단을 보려면 `/status` 또는 `claude doctor`를 실행하세요.

5162 5181

5163v2.1.248 이전에는 Claude Code가 실패한 설정 가져오기를 디버그 로그에서만 보고했습니다.5182v2.1.248 이전에는 Claude Code가 설정 가져오기 실패를 디버그 로그에서만 보고했습니다.

5164 5183

5165<h3 id="managed-settings-were-not-approved">5184<h3 id="managed-settings-were-not-approved">

5166 관리 설정이 승인되지 않음5185 관리형 설정이 승인되지 않음

5167</h3>5186</h3>

5168 5187

5169조직의 [서버 관리 설정](/docs/ko/server-managed-settings)에 승인이 필요한 설정이 포함되어 있고 [보안 승인 대화](/docs/ko/server-managed-settings#security-approval-dialogs)를 거부했으므로 Claude Code는 이를 적용하지 않고 종료합니다:5188조직의 [서버 관리형 설정](/docs/ko/server-managed-settings)에 승인이 필요한 설정이 포함되어 있는데 [보안 승인 대화 상자](/docs/ko/server-managed-settings#security-approval-dialogs)를 거부했으므로, Claude Code는 설정을 적용하지 않고 종료합니다:

5170 5189

5171```text theme={null}5190```text theme={null}

5172관리 설정이 승인되지 않았습니다. 이를 적용하지 않고 종료합니다.5191Managed settings were not approved; exiting without applying them.

5173```5192```

5174 5193

5175**할 일:**5194**할 일:**

5176 5195

5177* Claude Code를 다시 시작하고 대화를 승인하여 조직의 설정에서 계속하세요. 거부된 대화는 기억되지 않으므로 다음 시작 시 다시 나타납니다.5196* Claude Code를 다시 시작하고 대화 상자를 승인하여 조직의 설정으로 계속 진행하세요. 거부한 대화 상자는 기억되지 않으므로 다음 시작 시 다시 나타납니다.

5178* 대화가 나열하는 설정에 대해 확실하지 않으면 승인하기 전에 조직의 관리 설정을 유지하는 사람에게 문의하세요.5197* 대화 상자에 나열된 설정이 확실하지 않으면 승인하기 전에 조직의 관리형 설정을 유지 관리하는 담당자에게 문의하세요.

5179 5198

5180<h3 id="managed-settings-block-the-default-model">5199<h3 id="managed-settings-block-the-default-model">

5181 관리 설정이 기본 모델을 차단함5200 관리형 설정이 기본 모델을 차단함

5182</h3>5201</h3>

5183 5202

5184조직의 [관리 설정](/docs/ko/managed-settings)이 기본 옵션이 해석되는 모델과 이를 단계적으로 낮출 수 있는 모든 모델을 차단합니다. 기본 옵션에서 시작할 세션은 차단된 모델을 실행하는 대신 시작 시 종료됩니다. 어떤 메시지를 보는지는 이를 차단하는 설정에 따라 다릅니다. [`deniedModels`](/docs/ko/model-config#block-specific-models-or-versions) 목록이 이를 차단하면 메시지는 다음과 같이 읽습니다:5203조직의 [관리형 설정](/docs/ko/managed-settings)이 Default 옵션이 가리키는 모델과 단계적으로 낮출 수 있는 모든 모델을 차단합니다. Default 옵션으로 시작하려던 세션은 차단된 모델을 실행하는 대신 시작 시 종료됩니다. 표시되는 메시지는 차단하는 설정에 따라 다릅니다. [`deniedModels`](/docs/ko/model-config#block-specific-models-or-versions) 목록이 차단하는 경우 메시지는 다음과 같습니다:

5185 5204

5186```text theme={null}5205```text theme={null}

5187Claude Code를 시작할 수 없습니다: 조직의 관리 설정이 "deniedModels"에서 기본 모델(claude-opus-5-5)을 차단하고 있으며, 허용하는 모델 중 기본값으로 사용할 수 있는 모델이 없습니다. 관리자에게 "deniedModels" 또는 "availableModels"을 업데이트하도록 요청하세요.5206Claude Code can't start: your organization's managed settings block the default model (claude-opus-5-5) in "deniedModels", and none of the models they allow can be used as the default instead. Ask your administrator to update "deniedModels" or "availableModels".

5188```5207```

5189 5208

5190`availableModels` 목록이 [`availableModelsMatch`](/docs/ko/settings-reference#availablemodelsmatch)를 `"exact"`로 설정하여 이를 생략하면 메시지는 다음과 같이 읽습니다:5209[`availableModelsMatch`](/docs/ko/settings-reference#availablemodelsmatch)가 `"exact"`로 설정된 `availableModels` 목록에서 해당 모델이 빠진 경우 메시지는 다음과 같습니다:

5191 5210

5192```text theme={null}5211```text theme={null}

5193Claude Code를 시작할 수 없습니다: 조직이 "availableModels"에 나열된 모델만 허용하며, 기본 모델로 사용할 수 있는 모델이 없습니다(claude-opus-5-5가 나열되지 않음). 관리자에게 "availableModels"을 업데이트하도록 요청하세요.5212Claude Code can't start: your organization allows only the models listed in "availableModels", and none of them can be used as the default model (claude-opus-5-5 isn't listed). Ask your administrator to update "availableModels".

5194```5213```

5195 5214

5196**할 일:**5215**할 일:**

5197 5216

5198* 설정을 관리하는 경우 사용자가 실행할 수 있는 모델을 `availableModels`에 추가하거나 모든 폴백을 차단하는 `deniedModels` 항목을 좁히세요. [특정 모델 또는 버전 차단](/docs/ko/model-config#block-specific-models-or-versions)은 기본 옵션이 어떻게 단계적으로 낮춰지는지 설명합니다.5217* 설정을 관리하는 경우 사용자가 실행할 수 있는 모델을 `availableModels`에 추가하거나 모든 폴백을 차단하는 `deniedModels` 항목의 범위를 좁히세요. [특정 모델 또는 버전 차단](/docs/ko/model-config#block-specific-models-or-versions)에서 Default 옵션이 단계적으로 낮아지는 방식을 설명합니다.

5199* 설정을 관리하지 않으면 메시지를 관리자에게 보내세요. 자신의 설정 파일은 관리 `availableModels` 또는 `deniedModels` 목록을 확대할 수 없습니다.5218* 설정을 관리하지 않는 경우 메시지를 관리자에게 보내세요. 사용자 자신의 설정 파일로는 관리형 `availableModels` 또는 `deniedModels` 목록을 확장할 수 없습니다.

5200 5219

5201<h3 id="managed-settings-dont-allow-this-api-provider">5220<h3 id="managed-settings-dont-allow-this-api-provider">

5202 관리 설정이 이 API 공급자를 허용하지 않음5221 관리형 설정이 이 API 공급자를 허용하지 않음

5203</h3>5222</h3>

5204 5223

5205조직의 [관리 설정](/docs/ko/managed-settings)이 [`allowedProviders`](/docs/ko/settings-reference#allowedproviders) 목록을 설정하고, 세션의 API 공급자가 목록에 없거나 세션이 해당 항목이 요구하는 방식으로 고정되지 않은 엔드포인트를 사용합니다. Claude Code는 시작 전, 로그인 전, 또는 세션이 다음으로 API에 연결할 때 거부합니다. 메시지는 허용된 공급자로 시작합니다:5224조직의 [관리형 설정](/docs/ko/managed-settings)이 [`allowedProviders`](/docs/ko/settings-reference#allowedproviders) 목록을 설정했는데, 세션의 API 공급자가 목록에 없거나 세션이 해당 항목이 요구하는 방식으로 고정되지 않은 엔드포인트를 사용합니다. Claude Code는 시작 시, 로그인 전, 또는 세션이 다음에 API에 연결할 때 거부합니다. 메시지는 허용된 공급자로 시작합니다:

5206 5225

5207```text theme={null}5226```text theme={null}

5208조직의 관리 설정이 Claude Code를 사용하도록 허용합니다: Anthropic API, Amazon Bedrock.5227Your organization's managed settings allow Claude Code to use: Anthropic API, Amazon Bedrock.

5209```5228```

5210 5229

5211목록이 비어 있으면 메시지는 대신 다음과 같이 읽습니다:5230목록이 비어 있으면 메시지는 대신 다음과 같습니다:

5212 5231

5213```text theme={null}5232```text theme={null}

5214조직의 관리 설정이 Claude Code를 사용하도록 허용하는 API 공급자가 없습니다(allowedProviders가 빈 목록임). 따라서 이 머신에서 시작할 수 없습니다.5233Your organization's managed settings allow Claude Code to use no API provider at all (allowedProviders is an empty list), so it cannot start on this machine.

5215```5234```

5216 5235

5217모든 항목이 인식되지 않으면 괄호 안의 텍스트는 대신 `(allowedProviders lists only unrecognized entries)`입니다.5236모든 항목이 인식되지 않으면 괄호 안의 내용이 대신 `(allowedProviders lists only unrecognized entries)`로 표시됩니다.

5218 5237

5219**할 일:**5238**할 일:**

5220 5239

5221* 메시지의 `To continue:` 단계를 따르세요.5240* 메시지의 `To continue:` 단계를 따르세요.

5222* 설정을 관리하는 경우 메시지의 `Admins:`로 시작하는 줄이 추가할 항목 또는 고정할 값을 이름으로 지정하며, [`allowedProviders`](/docs/ko/settings-reference#allowedproviders) 항목은 어느 소스의 `env` 블록이 이를 고정할 수 있는지 말합니다.5241* 설정을 관리하는 경우 메시지에서 `Admins:`로 시작하는 줄이 추가할 항목 또는 고정할 값을 명시하며, [`allowedProviders`](/docs/ko/settings-reference#allowedproviders) 항목에서 어느 소스의 `env` 블록으로 고정할 수 있는지 설명합니다.

5223 5242

5224<h3 id="mcp-server-is-blocked-by-enterprise-managed-policy">5243<h3 id="mcp-server-is-blocked-by-enterprise-managed-policy">

5225 MCP 서버가 엔터프라이즈 관리 정책에 의해 차단됨5244 MCP 서버가 엔터프라이즈 관리 정책에 의해 차단됨

5226</h3>5245</h3>

5227 5246

5228`/mcp`의 서버에서 **다시 연결**을 선택했거나 비활성화된 서버를 다시 켰으며, [MCP 서버를 제한](/docs/ko/managed-mcp)하는 설정이 해당 서버를 차단합니다. Claude Code는 이를 연결하기를 거부하고 표시합니다:5247`/mcp`에서 서버의 **Reconnect**를 선택했거나 비활성화된 서버를 다시 켰는데, [MCP 서버를 제한](/docs/ko/managed-mcp)하는 설정이 해당 서버를 차단합니다. Claude Code는 연결을 거부하고 다음을 표시합니다:

5229 5248

5230```text theme={null}5249```text theme={null}

5231MCP 서버 <name>이(가) 엔터프라이즈 관리 정책에 의해 차단되었습니다5250MCP server <name> is blocked by enterprise managed policy

5232```5251```

5233 5252

5234이러한 설정 중 하나가 메시지를 생성할 수 있습니다:5253다음 설정 중 하나가 이 메시지를 발생시킬 수 있습니다:

5235 5254

5236* 자신의 `~/.claude/settings.json` 또는 프로젝트의 `.claude/settings.json`에 있는 것을 포함하여 서버와 일치하는 [`deniedMcpServers`](/docs/ko/managed-mcp#policy-based-control-with-allowlists-and-denylists) 항목5255* 사용자 자신의 `~/.claude/settings.json` 또는 프로젝트의 `.claude/settings.json`에 있는 것을 포함하여 서버와 일치하는 [`deniedMcpServers`](/docs/ko/managed-mcp#policy-based-control-with-allowlists-and-denylists) 항목

5237* 서버가 일치하지 않는 [`allowedMcpServers`](/docs/ko/managed-mcp#policy-based-control-with-allowlists-and-denylists) 목록5256* 서버가 일치하지 않는 [`allowedMcpServers`](/docs/ko/managed-mcp#policy-based-control-with-allowlists-and-denylists) 목록

5238* `mcp`가 잠긴 [`strictPluginOnlyCustomization`](/docs/ko/settings-reference#strictpluginonlycustomization)으로, `~/.claude.json` 및 `.mcp.json`에서 구성된 서버를 차단합니다.5257* `mcp`가 잠긴 [`strictPluginOnlyCustomization`](/docs/ko/settings-reference#strictpluginonlycustomization)으로, `~/.claude.json` 및 `.mcp.json`에 구성된 서버를 차단합니다

5239* 서버가 claude.ai 커넥터일 때 [`disableClaudeAiConnectors`](/docs/ko/mcp#disable-claude-ai-connectors)5258* 서버가 claude.ai 커넥터인 경우 [`disableClaudeAiConnectors`](/docs/ko/mcp#disable-claude-ai-connectors)

5240 5259

5241**할 일:**5260**할 일:**

5242 5261

5243* 자신의 사용자 및 프로젝트 설정 파일에서 이러한 설정 중 하나를 확인하고 변경하거나 제거하세요.5262* 사용자 자신의 사용자 및 프로젝트 설정 파일에서 이러한 설정이 있는지 확인하고 변경하거나 제거하세요.

5244* 자신의 설정이 차단을 설명하지 않으면 관리자에게 어떤 관리 설정이 서버를 차단하는지 문의하세요.5263* 사용자 자신의 설정으로 차단이 설명되지 않으면 관리자에게 어떤 관리형 설정이 서버를 차단하는지 문의하세요.

5245 5264

5246v2.1.257 이전에는 `/mcp`의 **다시 연결** 및 다시 활성화가 세션 중간 정책 업데이트가 차단한 서버를 연결할 수 있었습니다.5265v2.1.257 이전에는 `/mcp`의 **Reconnect** 및 다시 활성화로 세션 중 정책 업데이트가 차단한 서버를 연결할 수 있었습니다.

5247 5266

5248<h3 id="managed-settings-document-could-not-be-parsed">5267<h3 id="managed-settings-document-could-not-be-parsed">

5249 관리 설정 문서를 구문 분석할 수 없음5268 관리형 설정 문서를 구문 분석할 수 없음

5250</h3>5269</h3>

5251 5270

5252조직이 [관리 설정](/docs/ko/managed-settings)을 배포하고 배포된 문서 중 하나가 있지만 JSON 객체로 구문 분석할 수 없어서 Claude Code는 문서가 수행하는 정책 없이 실행하는 대신 시작 시 코드 1로 종료됩니다. 줄은 메시지 앞에 실패한 소스를 이름으로 지정합니다:5271조직이 [관리형 설정](/docs/ko/managed-settings)을 배포했는데 배포된 문서 중 하나가 존재하지만 JSON 객체로 구문 분석할 수 없으므로, Claude Code는 해당 문서가 담고 있는 정책 없이 실행하는 대신 시작 시 코드 1로 종료합니다. 줄은 메시지 앞에 실패한 소스를 명시합니다:

5253 5272

5254```text theme={null}5273```text theme={null}

5255/Library/Application Support/ClaudeCode/managed-settings.json: 관리 설정 문서를 JSON 객체로 구문 분석할 수 없습니다. 해당 설정이 적용되지 않습니다. 수정하거나 제거하세요.5274/Library/Application Support/ClaudeCode/managed-settings.json: Managed settings document could not be parsed as a JSON object; none of its settings are in effect. Fix or remove it.

5256```5275```

5257 5276

5258소스는 다음 중 하나입니다:5277소스는 다음 중 하나입니다:

5259 5278

5260* `managed-settings.json` 파일의 경로 또는 `managed-settings.d` 아래의 드롭인 파일5279* `managed-settings.json` 파일 또는 `managed-settings.d` 아래 드롭인 파일의 경로

5261* macOS 관리 기본 설정 프로필, `per-user managed preferences` 또는 `device-level managed preferences`5280* macOS 관리 기본 설정 프로필, `per-user managed preferences` 또는 `device-level managed preferences`

5262* Windows 레지스트리 값, `Registry: HKLM\SOFTWARE\Policies\ClaudeCode\Settings`5281* Windows 레지스트리 값, `Registry: HKLM\SOFTWARE\Policies\ClaudeCode\Settings`

5263 5282

5264[Claude Code가 삭제한 항목 찾기](/docs/ko/managed-settings#find-entries-claude-code-dropped)는 각 소스를 구문 분석할 수 없게 만드는 것을 나열합니다.5283[Claude Code가 삭제한 항목 찾기](/docs/ko/managed-settings#find-entries-claude-code-dropped)에서 각 소스를 구문 분석할 수 없게 만드는 원인을 나열합니다.

5265 5284

5266Claude Code는 다른 관리 소스가 유효한 정책을 제공하더라도 시작을 거부합니다. 대화형 세션, `claude -p`, Agent SDK 세션, [백그라운드 세션](/docs/ko/agent-view), 및 대부분의 하위 명령(`claude doctor` 포함)에서 이 오류를 봅니다. 거부는 의도적으로 폐쇄됩니다: Claude Code가 구문 분석할 수 없는 문서의 설정은 적용될 수 없으며, 어쨌든 시작하면 조직의 제어 없이 세션이 실행됩니다.5285Claude Code는 다른 관리자 소스가 유효한 정책을 제공하더라도 시작을 거부합니다. 이 오류는 대화형 세션, `claude -p`, Agent SDK 세션, [백그라운드 세션](/docs/ko/agent-view), 그리고 `claude doctor`를 포함한 대부분의 하위 명령에서 표시됩니다. 이 거부는 의도적으로 안전하게 실패(fail closed)하도록 설계되었습니다. Claude Code가 구문 분석할 수 없는 문서의 설정은 적용할 수 없으며, 그래도 시작하면 조직의 통제 없이 세션이 실행되기 때문입니다.

5267 5286

5268구문 분석 가능한 문서의 스키마 문제는 이 오류를 생성하지 않습니다. [Claude Code가 삭제한 항목 찾기](/docs/ko/managed-settings#find-entries-claude-code-dropped)는 Claude Code가 하나를 사용하는 것을 다룹니다.5287구문 분석 가능한 문서의 스키마 문제는 이 오류를 발생시키지 않습니다. [Claude Code가 삭제한 항목 찾기](/docs/ko/managed-settings#find-entries-claude-code-dropped)에서 이 경우 Claude Code가 어떻게 처리하는지 다룹니다.

5269 5288

5270`managed-settings.d/` 디렉토리가 있지만 나열할 수 없으면 Claude Code는 `Managed settings drop-in directory could not be read:` 다음에 기본 오류 대신 보고합니다. [Claude Code가 삭제한 항목 찾기](/docs/ko/managed-settings#find-entries-claude-code-dropped)는 읽기 실패가 시작 시 종료되는 경우를 다룹니다.5289`managed-settings.d/` 디렉터리가 존재하지만 목록을 읽을 수 없으면 Claude Code는 대신 `Managed settings drop-in directory could not be read:` 뒤에 근본 오류를 보고합니다. [Claude Code가 삭제한 항목 찾기](/docs/ko/managed-settings#find-entries-claude-code-dropped)에서 읽기 실패로 시작 시 종료되는 경우를 다룹니다.

5271 5290

5272**할 일:**5291**할 일:**

5273 5292

5274* 머신을 관리하면 명명된 문서가 JSON 객체로 구문 분석되도록 수정하거나 파일, 프로필 또는 레지스트리 값을 제거하세요. 빈 `managed-settings.json`은 `{}`로 계산되며 실행을 차단하지 않습니다.5293* 머신을 관리하는 경우 명시된 문서가 JSON 객체로 구문 분석되도록 수정하거나 파일, 프로필 또는 레지스트리 값을 제거하세요. 빈 `managed-settings.json`은 `{}`로 간주되며 실행을 차단하지 않습니다.

5275* 관리하지 않으면 관리자에게 배포된 문서를 수정하도록 요청하세요. 자신의 설정 파일의 아무것도 이 오류를 야기하거나 지우지 않습니다.5294* 관리하지 않는 경우 관리자에게 배포된 문서를 수정하도록 요청하세요. 사용자 자신의 설정 파일은 이 오류를 일으키지도 해결하지도 않습니다.

5276 5295

5277<h3 id="unable-to-read-managed-policy-settings">5296<h3 id="unable-to-read-managed-policy-settings">

5278 관리 정책 설정을 읽을 수 없음5297 관리 정책 설정을 읽을 수 없음

5279</h3>5298</h3>

5280 5299

5281조직이 [관리 설정](/docs/ko/managed-settings)을 배포하고, 배포된 소스 중 하나가 있지만 운영 체제가 읽기를 거부하는 것이 아닌 I/O 오류 같은 이유로 읽을 수 없습니다. 다른 관리 소스가 정책을 제공하지 않으면 Claude Code는 소스가 수행할 수 있는 정책 없이 실행하는 대신 시작 시 종료됩니다:5300조직이 [관리형 설정](/docs/ko/managed-settings)을 배포했는데, 배포된 소스 중 하나가 존재하지만 운영 체제가 읽기를 거부한 것이 아니라 I/O 오류 같은 이유로 읽을 수 없습니다. 다른 관리자 소스가 정책을 제공하지 않으면, Claude Code는 해당 소스가 담고 있을 수 있는 정책 없이 실행하는 대신 시작 시 종료합니다:

5282 5301

5283```text theme={null}5302```text theme={null}

5284관리 정책 설정을 읽을 수 없습니다.5303Unable to read managed policy settings.

5285이 머신에는 조직 로그인 적용이 필요할 수 있지만 정책 파일을 로드하지 못했습니다.5304This machine may require organization login enforcement, but the policy file failed to load.

5286관리자에게 문의하세요.5305Contact your administrator.

5287 5306

5288세부 정보: <source>: <reason>5307Detail: <source>: <reason>

5289```5308```

5290 5309

5291동일한 상태에서 로그인 흐름, 이미 실행 중인 세션의 API 요청, 및 [`claude gateway`](/docs/ko/claude-apps-gateway) 서버는 [`allowedProviders`](/docs/ko/settings-reference#allowedproviders)를 이름으로 지정하는 첫 번째 줄의 변형으로 거부됩니다.5310같은 상태에서 로그인 흐름, 이미 실행 중인 세션의 API 요청, [`claude gateway`](/docs/ko/claude-apps-gateway) 서버는 [`allowedProviders`](/docs/ko/settings-reference#allowedproviders)를 명시하는 첫 번째 줄의 변형 메시지와 함께 거부됩니다.

5292 5311

5293운영 체제가 거부한 읽기(예: 루트 전용 파일)는 이 종료를 생성하지 않습니다: [세션은 해당 소스의 정책 없이 시작됩니다](/docs/ko/managed-settings#find-entries-claude-code-dropped). 구문 분석할 수 없는 소스의 경우 Claude Code는 [소스를 이름으로 지정하는 다른 메시지](#managed-settings-document-could-not-be-parsed)로 종료됩니다.5312루트 전용 파일처럼 운영 체제가 읽기를 거부한 경우에는 이 종료가 발생하지 않으며, [세션은 해당 소스의 정책 없이 시작됩니다](/docs/ko/managed-settings#find-entries-claude-code-dropped). 구문 분석할 수 없는 소스의 경우 Claude Code는 [소스를 명시하는 다른 메시지](#managed-settings-document-could-not-be-parsed)와 함께 종료합니다.

5294 5313

5295**할 일:**5314**할 일:**

5296 5315

5297* 머신을 관리하면 `Detail:` 줄이 이름으로 지정한 문제를 수정하여 배포된 소스를 읽을 수 있도록 하거나 소스를 제거하세요.5316* 머신을 관리하는 경우 `Detail:` 줄이 명시한 문제를 수정하여 배포된 소스를 읽을 수 있게 하거나 소스를 제거하세요.

5298* 관리하지 않으면 메시지를 관리자에게 보내세요. 자신의 설정 파일의 아무것도 이 오류를 야기하거나 지우지 않습니다.5317* 관리하지 않는 경우 메시지를 관리자에게 보내세요. 사용자 자신의 설정 파일은 이 오류를 일으키지도 해결하지도 않습니다.

5299 5318

5300v2.1.285 이전에는 claude.ai 또는 Claude Console 자격 증명으로 로그인한 세션만 이 메시지로 종료되었으며, 운영 체제가 거부한 읽기도 이를 생성했습니다.5319v2.1.285 이전에는 claude.ai 또는 Claude Console 자격 증명으로 로그인한 세션만 이 메시지와 함께 종료되었으며, 운영 체제가 거부한 읽기도 이 메시지를 발생시켰습니다.

5301 5320

5302<h3 id="otelheadershelper-failed">5321<h3 id="otelheadershelper-failed">

5303 otelHeadersHelper 실패5322 otelHeadersHelper 실패

5304</h3>5323</h3>

5305 5324

5306Claude Code는 [`otelHeadersHelper`](/docs/ko/settings-reference#otelheadershelper) 스크립트가 실패하거나 [스크립트 요구 사항](/docs/ko/monitoring-usage#script-requirements)을 충족하지 않는 출력을 출력할 때 대화형 세션당 한 번 터미널 인터페이스에서 알림으로 이 경고를 표시합니다.5325Claude Code는 [`otelHeadersHelper`](/docs/ko/settings-reference#otelheadershelper) 스크립트가 실패하거나 [스크립트 요구 사항](/docs/ko/monitoring-usage#script-requirements)을 충족하지 않는 출력을 내보낼 때, 대화형 세션당 한 번 터미널 인터페이스에 알림으로 이 경고를 표시합니다.

5307 5326

5308스크립트가 계속 실패하는 동안 내보내기가 실패하고 원격 분석 백엔드는 세션에서 아무것도 받지 않습니다.5327스크립트가 계속 실패하는 동안 내보내기가 실패하며 텔레메트리 백엔드는 세션에서 아무것도 받지 못합니다.

5309 5328

5310`See /status:` 뒤의 텍스트는 스크립트의 종료 코드 다음에 오류 출력 같은 실패한 내용을 나타냅니다:5329`See /status:` 뒤의 텍스트는 스크립트의 종료 코드와 그 뒤의 오류 출력처럼 무엇이 실패했는지를 나타냅니다:

5311 5330

5312```text theme={null}5331```text theme={null}

5313otelHeadersHelper 실패. 원격 분석을 내보내지 않습니다. /status 참조: exited 1: token service unreachable5332otelHeadersHelper failed; telemetry is not being exported. See /status: exited 1: token service unreachable

5314```5333```

5315 5334

5316**할 일:**5335**할 일:**

5317 5336

5318* `/status`를 실행하여 실패 세부 정보를 읽으세요.5337* `/status`를 실행하여 실패 세부 정보를 확인하세요.

5319* 스크립트가 30초 이내에 0으로 종료되고 stdout에 문자열 헤더 값의 JSON 객체를 출력하도록 수정하세요. [스크립트 요구 사항](/docs/ko/monitoring-usage#script-requirements)을 참조하세요.5338* 스크립트가 30초 이내에 0으로 종료되고 stdout에 문자열 헤더 값으로 이루어진 JSON 객체를 출력하도록 수정하세요. [스크립트 요구 사항](/docs/ko/monitoring-usage#script-requirements)을 참조하세요.

5320* 조직이 [관리 설정](/docs/ko/managed-settings)을 통해 스크립트를 배포하면 이를 유지하는 사람에게 수정하도록 요청하세요.5339* 조직이 [관리형 설정](/docs/ko/managed-settings)을 통해 스크립트를 배포하는 경우 이를 유지 관리하는 담당자에게 수정을 요청하세요.

5321 5340

5322[비대화형 모드](/docs/ko/headless)에서 `-p`를 사용하면 동일한 실패가 stderr에 `otelHeadersHelper failed (OpenTelemetry export headers unavailable): <error>` 대신 나타납니다.5341`-p`를 사용하는 [비대화형 모드](/docs/ko/headless)에서는 같은 실패가 대신 stderr에 `otelHeadersHelper failed (OpenTelemetry export headers unavailable): <error>`로 나타납니다.

5323 5342

5324<h3 id="headershelper-not-run">5343<h3 id="headershelper-not-run">

5325 headersHelper 실행되지 않음5344 headersHelper 실행되지 않음

5326</h3>5345</h3>

5327 5346

5328Claude Code는 MCP 서버를 정적 `headers`만으로 연결했으며 서버의 [`headersHelper`](/docs/ko/mcp#use-dynamic-headers-for-custom-authentication)를 건너뛰었습니다. 헬퍼는 셸 명령이고 폴더에 저장된 신뢰가 없기 때문입니다. 폴더는 `~/.claude.json`에서 항목을 손으로 설정하거나 홈 디렉토리 외부에서 대화형 세션에서 신뢰 대화를 수락할 때 저장된 신뢰를 얻습니다. [headersHelper가 실행되기 전에 폴더 신뢰](/docs/ko/mcp#trust-a-folder-before-its-headershelper-runs)를 참조하여 이 검사가 어떤 서버에 적용되는지 확인하세요.5347Claude Code는 MCP 서버를 정적 `headers`만으로 연결했으며 서버의 [`headersHelper`](/docs/ko/mcp#use-dynamic-headers-for-custom-authentication)를 건너뛰었습니다. 헬퍼는 셸 명령인데 해당 폴더에 저장된 신뢰가 없기 때문입니다. 폴더는 `~/.claude.json`에서 해당 항목을 직접 설정하거나, 홈 디렉터리 외부에서는 대화형 세션에서 신뢰 대화 상자를 수락할 때 저장된 신뢰를 얻습니다. 이 검사가 어떤 서버에 적용되는지는 [headersHelper가 실행되기 전에 폴더 신뢰](/docs/ko/mcp#trust-a-folder-before-its-headershelper-runs)를 참조하세요.

5329 5348

5330Claude Code는 [비대화형 모드](/docs/ko/headless)에서만 이 줄을 서버당 한 번 기록합니다. 대화형 세션에서는 동일한 거부를 디버그 로그에 기록합니다.5349Claude Code는 [비대화형 모드](/docs/ko/headless)에서만 서버당 한 번 이 줄을 기록합니다. 대화형 세션에서는 같은 거부를 대신 디버그 로그에 기록합니다.

5331 5350

5332```text theme={null}5351```text theme={null}

5333MCP 서버 'internal-api': headersHelper 실행되지 않음 — 이 작업 영역에 저장된 신뢰가 없습니다. 여기서 한 번 대화형으로 신뢰 대화를 수락하거나 /Users/you/.claude.json에서 projects["/Users/you/project"].hasTrustDialogAccepted를 설정하세요.5352MCP server 'internal-api': headersHelper not run — this workspace has no persisted trust; accept the trust dialog here once interactively, or set projects["/Users/you/project"].hasTrustDialogAccepted in /Users/you/.claude.json.

5334```5353```

5335 5354

5336메시지가 출력하는 `projects` 키는 [프로젝트 allow 규칙 및 작업 영역 신뢰](/docs/ko/permissions#project-allow-rules-and-workspace-trust)가 Claude Code가 신뢰를 키하는 폴더입니다. 부모 폴더에 대한 신뢰 대화를 수락하는 것은 검사를 만족하지 않으며, `-p` 또는 SDK 세션도 만족하지 않습니다.5355메시지가 출력하는 `projects` 키는 [프로젝트 허용 규칙 및 워크스페이스 신뢰](/docs/ko/permissions#project-allow-rules-and-workspace-trust)에서 설명하는, Claude Code가 신뢰의 기준으로 삼는 폴더입니다. 상위 폴더에 대한 신뢰 대화 상자를 수락해도 이 검사를 통과하지 못하며, `-p` 또는 SDK 세션으로도 통과하지 못합니다.

5337 5356

5338**할 일:**5357**할 일:**

5339 5358

5340* 메시지가 이름으로 지정한 폴더에서 `claude`를 실행하고 신뢰 대화를 수락한 후 `-p` 또는 SDK 명령을 다시 실행하세요.5359* 메시지가 명시한 폴더에서 `claude`를 실행하고 신뢰 대화 상자를 수락한 후 `-p` 또는 SDK 명령을 다시 실행하세요.

5341* `~/.claude.json`에서 `hasTrustDialogAccepted` 항목을 직접 설정하고 메시지가 출력하는 정확한 `projects` 키를 사용하세요.5360* 메시지가 출력하는 정확한 `projects` 키를 사용하여 `~/.claude.json`에 `hasTrustDialogAccepted` 항목을 직접 설정하세요.

5342* 홈 디렉토리에서 세션을 시작했으면 신뢰한 프로젝트 디렉토리에서 작업하세요. 홈 디렉토리에서 신뢰 대화를 수락하면 Claude Code는 현재 세션에만 해당 신뢰를 유지합니다.5361* 홈 디렉터리에서 세션을 시작했다면 신뢰한 프로젝트 디렉터리에서 작업하세요. 홈 디렉터리에서 신뢰 대화 상자를 수락하면 Claude Code는 현재 세션에만 해당 신뢰를 유지합니다.

5343 5362

5344<h3 id="malformed-tool-content-rule">5363<h3 id="malformed-tool-content-rule">

5345 잘못된 형식의 Tool(content) 규칙5364 잘못된 형식의 Tool(content) 규칙

5346</h3>5365</h3>

5347 5366

5348[권한 규칙](/docs/ko/permissions#permission-rule-syntax)이 설정 파일 중 하나에 `Tool` 또는 `Tool(content)` 형태가 아닙니다. 예를 들어 닫는 괄호 뒤에 텍스트가 있거나 괄호 중 하나가 누락되었습니다. Claude Code는 규칙을 건너뛰고 대화형 세션이 시작될 때 유효하지 않은 설정 대화에 나열하며, [`claude doctor`](/docs/ko/debug-your-config#check-resolved-settings) 출력에서:5367설정 파일 중 하나의 [권한 규칙](/docs/ko/permissions#permission-rule-syntax)이 `Tool` 또는 `Tool(content)` 형태가 아닙니다. 예를 들어 닫는 괄호 뒤에 텍스트가 있거나 괄호 중 하나가 누락된 경우입니다. Claude Code는 규칙을 건너뛰고, 대화형 세션이 시작될 때 유효하지 않은 설정 대화 상자와 [`claude doctor`](/docs/ko/debug-your-config#check-resolved-settings) 출력에 해당 규칙을 나열합니다:

5349 5368

5350```text theme={null}5369```text theme={null}

5351유효하지 않은 권한 규칙 "Bash(ls) x"를 건너뛰었습니다: 잘못된 형식의 Tool(content) 규칙. 규칙은 Tool 또는 Tool(content) 형태이며 닫는 ")"에서 끝나야 합니다. 내용 내의 괄호는 리터럴입니다.5370Invalid permission rule "Bash(ls) x" was skipped: Malformed Tool(content) rule. Rules take the form Tool or Tool(content) and must end at the closing ")"; parentheses inside the content are literal

5352```5371```

5353 5372

5354**할 일:**5373**할 일:**

5355 5374

5356* 메시지와 함께 나열된 설정 파일에서 규칙을 다시 작성하여 닫는 괄호에서 끝나도록 하세요. 예를 들어 `Bash(ls) x` 대신 `Bash(ls *)`5375* 메시지와 함께 나열된 설정 파일에서 규칙이 닫는 괄호에서 끝나도록 다시 작성하세요. 예를 들어 `Bash(ls) x` 대신 `Bash(ls *)`를 사용합니다.

5357* 내용 내의 괄호는 그대로 두세요. 이들은 리터럴이므로 `Edit(./Finance (2024)/**)` 같은 규칙은 이스케이프 없이 유효합니다.5376* 내용 안의 괄호는 그대로 두세요. 괄호는 리터럴로 처리되므로 `Edit(./Finance (2024)/**)` 같은 규칙은 이스케이프 없이도 유효합니다.

5358 5377

5359v2.1.260 이전에는 Claude Code가 일치하지 않는 괄호가 있는 규칙을 `Mismatched parentheses`로 보고했습니다.5378v2.1.260 이전에는 Claude Code가 괄호가 짝이 맞지 않는 규칙을 `Mismatched parentheses`로 보고했습니다.

5360 5379

5361<h3 id="is-not-matched-by-file-permission-checks">5380<h3 id="is-not-matched-by-file-permission-checks">

5362 파일 권한 검사와 일치하지 않음5381 파일 권한 검사와 일치하지 않음

5363</h3>5382</h3>

5364 5383

5365Claude Code는 [설정 파일](/docs/ko/settings#where-settings-live), [관리 설정](/docs/ko/managed-settings), 또는 `--allowedTools`, `--disallowedTools`, 또는 `--settings` 플래그 값에서 경로가 있는 `Write`, `NotebookEdit`, `MultiEdit`, 또는 `Glob` [권한 규칙](/docs/ko/permissions#read-and-edit)을 찾았습니다. 파일 권한을 `Edit` 및 `Read` 규칙에 대해서만 검사하므로 다른 파일 도구 중 하나를 이름으로 지정하는 경로 규칙을 절대 참조하지 않습니다. 규칙을 유지하고 다른 것은 변경하지 않습니다. 경고는 규칙, 괄호의 소스, 그리고 작성할 대체를 이름으로 지정합니다:5384Claude Code는 [설정 파일](/docs/ko/settings#where-settings-live), [관리형 설정](/docs/ko/managed-settings), 또는 `--allowedTools`, `--disallowedTools`, `--settings` 플래그 값에서 경로가 포함된 `Write`, `NotebookEdit`, `MultiEdit`, 또는 `Glob` [권한 규칙](/docs/ko/permissions#read-and-edit)을 찾았습니다. Claude Code는 파일 권한을 `Edit` 및 `Read` 규칙에 대해서만 검사하므로, 다른 파일 도구를 명시하는 경로 규칙은 전혀 참조하지 않습니다. 규칙은 유지되며 다른 것은 변경되지 않습니다. 경고는 규칙, 괄호 안의 소스, 그리고 대신 작성할 규칙을 명시합니다:

5366 5385

5367```text theme={null}5386```text theme={null}

5368권한 deny 규칙(.claude/settings.json): Write(docs/**)는 파일 권한 검사와 일치하지 않습니다 — Edit(path) 규칙만 있습니다. 대신 Edit(docs/**)를 사용하세요(Edit 규칙은 모든 파일 편집 도구를 포함합니다).5387Permission deny rule (.claude/settings.json): Write(docs/**) is not matched by file permission checks — only Edit(path) rules are. Use Edit(docs/**) instead (Edit rules cover all file-editing tools).

5369```5388```

5370 5389

5371**할 일:**5390**할 일:**

5372 5391

5373* `Write(path)`, `NotebookEdit(path)`, 및 레거시 `MultiEdit(path)` 규칙을 `Edit(path)`로 바꾸세요. `Edit` 규칙은 모든 파일 편집 도구를 포함합니다.5392* `Write(path)`, `NotebookEdit(path)`, 레거시 `MultiEdit(path)` 규칙을 `Edit(path)`로 바꾸세요. `Edit` 규칙은 모든 파일 편집 도구에 적용됩니다.

5374* `--allowedTools`를 제외하고, Claude Code가 경고 없이 `Glob` 규칙을 수락하며, `Glob(path)` 규칙을 `Read(path)`로 바꾸세요.5393* Claude Code가 경고 없이 `Glob` 규칙을 수락하는 `--allowedTools`를 제외하고, `Glob(path)` 규칙을 `Read(path)`로 바꾸세요.

5375* 경고가 괄호에 이름으로 지정한 소스에서 규칙을 수정하세요: 설정 파일 경로 또는 `--allowed-tools` 및 `--disallowed-tools`의 플래그 자체. 디스크에 존재하지 않는 `claude-settings-<hash>.json` 경로는 인라인 `--settings` 값을 나타냅니다. 해당 플래그에 전달하는 JSON을 수정하세요.5394* 경고가 괄호 안에 명시한 소스에서 규칙을 수정하세요: 설정 파일 경로, 또는 `--allowed-tools` 및 `--disallowed-tools`의 경우 플래그 자체입니다. 디스크에 존재하지 않는 `claude-settings-<hash>.json` 경로는 인라인 `--settings` 값을 나타냅니다. 해당 플래그에 전달하는 JSON을 수정하세요.

5376* `Write` 또는 `Glob` 같은 베어 도구 이름 규칙은 그대로 두세요. Claude Code는 [도구 수준](/docs/ko/permissions#match-all-uses-of-a-tool)에서 일치하며 이에 대해 경고하지 않습니다.5395* `Write` 또는 `Glob` 같은 도구 이름만 있는 규칙은 그대로 두세요. Claude Code는 이러한 규칙을 [도구 수준](/docs/ko/permissions#match-all-uses-of-a-tool)에서 일치시키며 경고하지 않습니다.

5377* 소스가 `managed policy settings`로 읽히면 경고를 관리 설정을 유지하는 사람에게 전달하세요. 자신이 직접 지울 수 없기 때문입니다.5396* 소스가 `managed policy settings`로 표시되면 사용자가 직접 해결할 수 없으므로 관리형 설정을 유지 관리하는 담당자에게 경고를 전달하세요.

5378 5397

5379[백그라운드 세션](/docs/ko/agent-view) 또는 `--output-format json` 또는 `stream-json`에서 Claude Code는 경고를 디버그 로그에 stderr 대신 기록하므로 머신 읽기 출력이 깨끗합니다. `--debug`로 실행하여 `~/.claude/debug/<session-id>.txt`에서 캡처하세요. v2.1.210 이전에는 Claude Code가 경고 없이 이러한 규칙을 수락했습니다.5398[백그라운드 세션](/docs/ko/agent-view)에서 또는 `--output-format json`이나 `stream-json`을 사용하는 경우, Claude Code는 기계가 읽는 출력을 깨끗하게 유지하기 위해 경고를 stderr 대신 디버그 로그에 기록합니다. `--debug`로 실행하면 `~/.claude/debug/<session-id>.txt`에서 확인할 수 있습니다. v2.1.210 이전에는 Claude Code가 경고 없이 이러한 규칙을 수락했습니다.

5380 5399

5381<h3 id="has-a-wildcard-before-the-rest-of-the-command">5400<h3 id="has-a-wildcard-before-the-rest-of-the-command">

5382 명령의 나머지 부분 앞에 와일드카드가 있음5401 명령의 나머지 부분 앞에 와일드카드가 있음

5383</h3>5402</h3>

5384 5403

5385Claude Code는 `Bash(git * main)` 또는 `Bash(git -C * status *)` 같이 `*`가 명령을 결정하는 나중의 단어 앞에 오는 `Bash` allow 규칙을 찾았습니다. [설정 파일](/docs/ko/settings#where-settings-live), [관리 설정](/docs/ko/managed-settings), 또는 `--allowedTools` 또는 `--settings` 플래그 값에서. `*`는 해당 위치에 삽입된 옵션을 포함한 모든 텍스트와 일치합니다: `Bash(git * main)`은 또한 `git -c core.fsmonitor=<script> diff main`을 승인합니다. 여기서 `-c`는 git이 명령이 이름을 지정하는 프로그램을 실행하게 합니다. [와일드카드 패턴](/docs/ko/permissions#wildcard-patterns)은 일치 규칙을 보여줍니다.5404Claude Code는 [설정 파일](/docs/ko/settings#where-settings-live), [관리형 설정](/docs/ko/managed-settings), 또는 `--allowedTools`나 `--settings` 플래그 값에서 `Bash(git * main)` 또는 `Bash(git -C * status *)`처럼 `*`가 어떤 명령인지를 결정하는 뒤쪽 단어보다 앞에 오는 `Bash` 허용 규칙을 찾았습니다. `*`는 해당 위치에 삽입된 옵션을 포함한 모든 텍스트와 일치합니다. 예를 들어 `Bash(git * main)`은 `git -c core.fsmonitor=<script> diff main`도 승인하는데, 여기서 `-c`는 git이 명령에 지정된 프로그램을 실행하게 만듭니다. [와일드카드 패턴](/docs/ko/permissions#wildcard-patterns)에서 일치 규칙을 확인할 수 있습니다.

5386 5405

5387경고는 의도한 것보다 와일드카드가 더 넓은 규칙을 좁힐 수 있도록 존재합니다. Claude Code는 규칙을 유지하고 일치 방식에 대해 아무것도 변경하지 않습니다. 경고는 규칙과 괄호의 소스를 이름으로 지정합니다:5406이 경고는 의도보다 넓은 와일드카드를 가진 규칙의 범위를 좁힐 수 있도록 하기 위한 것입니다. Claude Code는 규칙을 유지하며 일치 방식도 변경하지 않습니다. 경고는 규칙과 괄호 안의 소스를 명시합니다:

5388 5407

5389```text theme={null}5408```text theme={null}

5390권한 allow 규칙(.claude/settings.json): Bash(git -C * status *)는 명령의 나머지 부분 앞에 와일드카드가 있으므로 해당 위치에 삽입된 모든 옵션과도 일치하며 프롬프트 없이 이를 승인합니다. git의 경우 -c 및 --exec-path 같은 옵션은 임의의 명령을 실행할 수 있습니다. 해당 *를 의도한 정확한 값으로 바꾸거나 부분 명령 뒤에만 *를 사용하세요(예: Bash(git status *)).5409Permission allow rule (.claude/settings.json): Bash(git -C * status *) has a wildcard before the rest of the command, so it also matches any options inserted at that position and approves them without a prompt. For git, options such as -c and --exec-path can run arbitrary commands. Replace that * with the exact value you mean, or only use * after the subcommand (for example Bash(git status *)).

5391```5410```

5392 5411

5393**할 일:**5412**할 일:**

5394 5413

5395* 부분 명령 앞의 `*`를 의도한 정확한 값으로 바꾸세요: `Bash(git * main)` 대신 `Bash(git checkout main)`.5414* 하위 명령 앞의 `*`를 의도한 정확한 값으로 바꾸세요: `Bash(git * main)` 대신 `Bash(git checkout main)`.

5396* 모든 `*`를 부분 명령 뒤로 이동하세요: `Bash(git -C * status *)` 대신 `Bash(git status *)`. 허용하려는 부분 명령당 하나의 규칙을 작성하세요.5415* 모든 `*`를 하위 명령 뒤로 옮기세요: `Bash(git -C * status *)` 대신 `Bash(git status *)`. 허용하려는 하위 명령마다 규칙을 하나씩 작성하세요.

5397* 경고가 괄호에 이름으로 지정한 소스에서 규칙을 수정하세요: 설정 파일 경로 또는 `--allowed-tools` 플래그 자체. 디스크에 존재하지 않는 `claude-settings-<hash>.json` 경로는 인라인 `--settings` 값을 나타냅니다. 해당 플래그에 전달하는 JSON을 수정하세요.5416* 경고가 괄호 안에 명시한 소스에서 규칙을 수정하세요: 설정 파일 경로 또는 `--allowed-tools` 플래그 자체입니다. 디스크에 존재하지 않는 `claude-settings-<hash>.json` 경로는 인라인 `--settings` 값을 나타냅니다. 해당 플래그에 전달하는 JSON을 수정하세요.

5398* 소스가 `managed policy settings`로 읽히면 경고를 관리 설정을 유지하는 사람에게 전달하세요. 자신이 직접 지울 수 없기 때문입니다.5417* 소스가 `managed policy settings`로 표시되면 사용자가 직접 해결할 수 없으므로 관리형 설정을 유지 관리하는 담당자에게 경고를 전달하세요.

~~5399~~

5400Claude Code는 동일한 형태의 deny 및 ask 규칙에 대해 경고하지 않습니다: 이를 승인하는 대신 일치하는 추가 명령을 거부하거나 프롬프트합니다. 또한 부분 명령이 첫 번째 `*` 앞에 오는 규칙(예: `Bash(git commit *)`)이나 `*` 뒤에 옵션 이외의 단어가 없는 규칙(예: `Bash(git *)`)이나 `:*` 접두사 규칙(예: `Bash(git:*)`)에 대해서도 경고하지 않습니다.

5401 5418

5402[백그라운드 세션](/docs/ko/agent-view) 또는 `--output-format json` 또는 `stream-json`에서 Claude Code는 경고를 디버그 로그에 stderr 대신 기록하므로 머신 읽기 출력이 깨끗합니다. `--debug`로 실행하여 `~/.claude/debug/<session-id>.txt`에서 캡처하세요. v2.1.246 이전에는 Claude Code가 경고 없이 이러한 규칙을 수락했습니다.5419[백그라운드 세션](/docs/ko/agent-view)에서 또는 `--output-format json`이나 `stream-json`을 사용하는 경우, Claude Code는 기계가 읽는 출력을 깨끗하게 유지하기 위해 경고를 stderr 대신 디버그 로그에 기록합니다. `--debug`로 실행하면 `~/.claude/debug/<session-id>.txt`에서 확인할 수 있습니다. v2.1.246 이전에는 Claude Code가 경고 없이 이러한 규칙을 수락했습니다.

5403 5420

5404<h3 id="crosssessioninbound-must-be-one-of-accept-hold-refuse">5421<h3 id="crosssessioninbound-must-be-one-of-accept-hold-refuse">

5405 crossSessionInbound는 accept, hold, refuse 중 하나여야 함5422 crossSessionInbound는 accept, hold, refuse 중 하나여야 함

5406</h3>5423</h3>

5407 5424

5408설정 파일이 [`crossSessionInbound`](/docs/ko/settings-reference#crosssessioninbound)를 Claude Code가 인식하지 못하는 값(예: 오타 `"reject"`)으로 설정합니다. 경고의 두 번째 문장은 어떤 파일이 값을 보유하는지에 따라 다릅니다. 사용자, 프로젝트, 로컬 또는 `--settings` 파일에서 읽습니다:5425설정 파일이 [`crossSessionInbound`](/docs/ko/settings-reference#crosssessioninbound)를 오타 `"reject"`처럼 Claude Code가 인식하지 못하는 값으로 설정했습니다. 경고의 두 번째 문장은 어느 파일에 값이 있는지에 따라 다르며, 사용자, 프로젝트, 로컬 또는 `--settings` 파일에서는 다음과 같습니다:

5409 5426

5410```text theme={null}5427```text theme={null}

5411"crossSessionInbound"는 "accept", "hold", "refuse" 중 하나여야 합니다. "reject"를 받았습니다. 이 값은 무시되었습니다. 존재하는 동안 교차 세션 메시지는 전달되는 대신 승인을 위해 보류됩니다. 위의 값 중 하나로 설정하세요.5428"crossSessionInbound" must be one of "accept", "hold", "refuse"; received "reject". This value was ignored; while it is present, cross-session messages are held for your approval instead of being delivered. Set it to one of the values above.

5412```5429```

5413 5430

5414[관리 설정](/docs/ko/managed-settings)에서 Claude Code는 인식되지 않는 값을 가장 제한적인 값인 `refuse`로 취급하며 경고는 관리자가 수정할 때까지 교차 세션 메시지가 거부된다고 말합니다. hold가 다른 설정 파일의 값과 결합되는 방식은 [`crossSessionInbound`](/docs/ko/settings-reference#crosssessioninbound)를 참조하세요.5431[관리형 설정](/docs/ko/managed-settings)에서는 Claude Code가 인식되지 않는 값을 가장 제한적인 값인 `refuse`로 취급하며, 경고는 관리자가 수정할 때까지 세션 간 메시지가 거부된다고 알립니다. 보류가 다른 설정 파일의 값과 어떻게 결합되는지는 [`crossSessionInbound`](/docs/ko/settings-reference#crosssessioninbound)를 참조하세요.

5415 5432

5416**할 일:**5433**할 일:**

5417 5434

5418* 키를 `"accept"`, `"hold"`, 또는 `"refuse"`로 설정하거나 제거하세요.5435* 키를 `"accept"`, `"hold"`, 또는 `"refuse"`로 설정하거나 제거하세요.

5419* 경고가 관리 설정을 이름으로 지정하면 관리자에게 값을 수정하도록 요청하세요.5436* 경고가 관리형 설정을 명시하면 관리자에게 값을 수정하도록 요청하세요.

5420 5437

5421v2.1.248 이전에는 Claude Code가 인식되지 않는 값을 경고 없이 무시했습니다.5438v2.1.248 이전에는 Claude Code가 인식되지 않는 값을 경고 없이 무시했습니다.

5422 5439

5424 200K 제한이 적용되지 않음5441 200K 제한이 적용되지 않음

5425</h3>5442</h3>

5426 5443

5427[`CLAUDE_CODE_DISABLE_1M_CONTEXT=1`](/docs/ko/env-vars)을 설정했습니다. 이는 일반적으로 [자동 압축](/docs/ko/model-config#default-auto-compact-thresholds)이 1M 컨텍스트 모델의 세션을 200K 윈도우에 유지하게 하지만, 이 세션을 200K 이하로 제한하는 압축 임계값이 없으므로 대화가 이를 초과하여 증가할 수 있습니다.5444[`CLAUDE_CODE_DISABLE_1M_CONTEXT=1`](/docs/ko/env-vars)을 설정하면 일반적으로 [자동 압축](/docs/ko/model-config#default-auto-compact-thresholds)이 1M 컨텍스트 모델의 세션을 200K 윈도우로 유지하지만, 이 세션을 200K 이하로 제한하는 압축 임계값이 없으므로 대화가 200K를 넘어 커질 수 있습니다.

5428 5445

5429```text theme={null}5446```text theme={null}

5430CLAUDE_CODE_DISABLE_1M_CONTEXT가 설정되었지만 <model>에 대해 200K 제한이 적용되지 않으므로 이 세션은 이를 초과하여 증가할 수 있습니다. 이를 적용하려면 CLAUDE_CODE_AUTO_COMPACT_WINDOW=200000(또는 autoCompactWindow 설정)을 설정하세요.5447CLAUDE_CODE_DISABLE_1M_CONTEXT is set, but the 200K limit isn't enforced for <model>, so this session can grow past it. To enforce it, set CLAUDE_CODE_AUTO_COMPACT_WINDOW=200000 (or the autoCompactWindow setting).

5431```5448```

5432 5449

5433Claude Code는 기본 1M 윈도우가 있는 것으로 인식하는 모든 모델과 인식하지 못하는 모델 ID에 대해 가정하는 윈도우에서 압축하는 200K 제한을 자체적으로 적용합니다. 경고는 다른 구성이 해당 적용을 무효화할 때 나타납니다:5450Claude Code는 기본적으로 1M 윈도우를 가진 것으로 인식하는 모든 모델에 대해 200K 제한을 자체적으로 적용하며, 인식하지 못하는 모델 ID에 대해서는 가정한 윈도우에서 압축합니다. 이 경고는 다른 구성이 이러한 적용을 무력화할 때 나타납니다:

5434 5451

5435* 모델 ID가 Claude Code가 인식하지 못하는 것입니다(예: [LLM 게이트웨이](/docs/ko/llm-gateway) 별칭). [`CLAUDE_CODE_DISABLE_UNKNOWN_MODEL_WINDOW_ENFORCEMENT=1`](/docs/ko/env-vars)을 설정했거나 [`CLAUDE_CODE_MAX_CONTEXT_TOKENS`](/docs/ko/env-vars)로 가정하는 윈도우를 200K 이상으로 올렸습니다. 이 경우 메시지는 또한 `or update to a Claude Code version that recognizes <model>`을 해결책으로 제공합니다.5452* 모델 ID가 [LLM 게이트웨이](/docs/ko/llm-gateway) 별칭처럼 Claude Code가 인식하지 못하는 것이고, [`CLAUDE_CODE_DISABLE_UNKNOWN_MODEL_WINDOW_ENFORCEMENT=1`](/docs/ko/env-vars)을 설정했거나 [`CLAUDE_CODE_MAX_CONTEXT_TOKENS`](/docs/ko/env-vars)로 가정 윈도우를 200K 이상으로 올린 경우. 이 경우 메시지는 해결책으로 `or update to a Claude Code version that recognizes <model>`도 제시합니다.

5436* `context-1m` 베타는 [`ANTHROPIC_BETAS`](/docs/ko/env-vars) 또는 [`--betas`](/docs/ko/cli-reference#cli-flags) 플래그를 통해 요청되며 여전히 해당 베타를 수락하는 모델에서 API에 1M 윈도우를 요청하는 동안 아무것도 200K에서 세션을 압축하지 않습니다.5453* [`ANTHROPIC_BETAS`](/docs/ko/env-vars) 또는 [`--betas`](/docs/ko/cli-reference#cli-flags) 플래그로 요청한 `context-1m` 베타가 해당 베타를 지원하는 모델에서 여전히 API에 1M 윈도우를 요청하는 반면, 200K에서 세션을 압축하는 것이 없는 경우

5437 5454

5438**할 일:**5455**할 일:**

5439 5456

5440* [`CLAUDE_CODE_AUTO_COMPACT_WINDOW=200000`](/docs/ko/env-vars)을 설정하거나 [`autoCompactWindow`](/docs/ko/settings-reference#autocompactwindow) 설정을 `200000`으로 설정하여 자동 압축이 200K 경계에서 압축하도록 하세요.5457* [`CLAUDE_CODE_AUTO_COMPACT_WINDOW=200000`](/docs/ko/env-vars)을 설정하거나 [`autoCompactWindow`](/docs/ko/settings-reference#autocompactwindow) 설정을 `200000`으로 설정하여 자동 압축이 200K 경계에서 압축하도록 하세요.

5441* 메시지가 이 버전이 인식하지 못하는 모델 ID를 이름으로 지정하면 `claude update`를 실행하세요. ID를 1M 컨텍스트 모델로 인식하는 버전은 추가 구성 없이 제한을 적용합니다.5458* 메시지가 이 버전이 인식하지 못하는 모델 ID를 명시하면 `claude update`를 실행하세요. 해당 ID를 1M 컨텍스트 모델로 인식하는 버전은 추가 구성 없이 제한을 적용합니다.

5442* 세션이 모델의 전체 윈도우를 대신 사용하기를 원하면 `CLAUDE_CODE_DISABLE_1M_CONTEXT`를 설정 해제하세요. 경고는 200K 제한이 적용되지 않음을 보고합니다.5459* 세션이 대신 모델의 전체 윈도우를 사용하기를 원하면 `CLAUDE_CODE_DISABLE_1M_CONTEXT`를 설정 해제하세요. 이 경고는 200K 제한이 적용되지 않는다는 사실만 알립니다.

5443 5460

5444[백그라운드 세션](/docs/ko/agent-view) 또는 `--output-format json` 또는 `stream-json`에서 Claude Code는 경고를 디버그 로그에 stderr 대신 기록합니다.5461[백그라운드 세션](/docs/ko/agent-view)에서 또는 `--output-format json`이나 `stream-json`을 사용하는 경우, Claude Code는 경고를 stderr 대신 디버그 로그에 기록합니다.

5445 5462

5446<h3 id="unrecognized-model-id-on-a-request">5463<h3 id="unrecognized-model-id-on-a-request">

5447 요청에서 인식되지 않은 모델 ID5464 요청에서 인식되지 않은 모델 ID

5448</h3>5465</h3>

5449 5466

5450Claude Code는 Claude Code 버전이 인식하지 못하는 모델 ID에 대한 요청을 보냈으며, 해당 ID를 인식하는 모델에 매핑하는 [`modelOverrides`](/docs/ko/model-config#override-model-ids-per-version) 항목을 찾지 못했습니다. Claude Code는 여전히 구성한 대로 ID를 사용하여 요청을 보내며 종료하거나 모델을 전환하지 않습니다.5467Claude Code가 사용 중인 Claude Code 버전이 인식하지 못하는 모델 ID로 요청을 보냈으며, 해당 ID를 인식하는 모델에 매핑하는 [`modelOverrides`](/docs/ko/model-config#override-model-ids-per-version) 항목을 찾지 못했습니다. Claude Code는 여전히 구성된 그대로의 ID로 요청을 보내며, 종료하거나 모델을 전환하지 않습니다.

5451 5468

5452```text theme={null}5469```text theme={null}

5453[claude-code:unrecognized_model] {"model":"my-proxy-model","query_source":"sdk"}5470[claude-code:unrecognized_model] {"model":"my-proxy-model","query_source":"sdk"}

5454```5471```

5455 5472

5456stderr를 읽는 스크립트 또는 하네스에서 `[claude-code:unrecognized_model]` 접두사와 일치합니다. 접두사와 한 칸 뒤에 Claude Code는 한 줄 JSON 객체를 기록합니다. Claude Code는 나중 버전에서 필드를 추가할 수 있으므로 예상하지 못한 필드는 무시하세요. 최소한 이 두 가지를 기록합니다:5473stderr를 읽는 스크립트나 하네스에서는 `[claude-code:unrecognized_model]` 접두사로 일치시키세요. 접두사와 공백 하나 뒤에 Claude Code는 한 줄짜리 JSON 객체를 기록합니다. Claude Code는 이후 버전에서 필드를 추가할 수 있으므로 예상하지 못한 필드는 무시하세요. 최소한 다음 두 필드는 기록됩니다:

5457 5474

5458* `model`: 구성한 대로 모델 문자열5475* `model`: 구성된 그대로의 모델 문자열

5459* `query_source`: 모델을 사용한 요청 경로. Claude Code는 `-p` 실행에 대해 `sdk`를 보고하고 `agent:`로 시작하는 값을 서브에이전트에 대해 보고합니다.5476* `query_source`: 모델을 사용한 요청 경로. Claude Code는 `-p` 실행에 대해 `sdk`를, 서브에이전트에 대해 `agent:`로 시작하는 값을 보고합니다.

5460 5477

5461Claude Code는 실행 방식에 따라 두 곳 중 하나에 줄을 기록합니다:5478Claude Code는 실행 방식에 따라 두 곳 중 하나에 이 줄을 기록합니다:

5462 5479

5463* [비대화형 모드](/docs/ko/headless)에서 `-p`를 사용하면 Claude Code는 모든 `--output-format` 아래 stderr에 기록하므로 줄을 필터링하지 않고 stdout을 구문 분석할 수 있습니다.5480* `-p`를 사용하는 [비대화형 모드](/docs/ko/headless)에서는 모든 `--output-format`에서 stderr에 기록하므로, 이 줄을 걸러내지 않고도 stdout을 구문 분석할 수 있습니다.

5464* 대화형 세션 또는 [백그라운드 세션](/docs/ko/agent-view)에서 Claude Code는 디버그 로그에 기록합니다. `--debug`로 실행하여 `~/.claude/debug/<session-id>.txt`에서 캡처하세요.5481* 대화형 세션 또는 [백그라운드 세션](/docs/ko/agent-view)에서는 대신 디버그 로그에 기록합니다. `--debug`로 실행하면 `~/.claude/debug/<session-id>.txt`에서 확인할 수 있습니다.

5465 5482

5466Claude Code는 프로세스당 모델 문자열당 한 번 줄을 기록합니다. [서브에이전트](/docs/ko/sub-agents#choose-a-model) 또는 [백그라운드 기능](/docs/ko/costs#background-token-usage)이 사용하는 것 같은 추가 인식되지 않은 ID에 대해 별도의 줄을 기록합니다.5483Claude Code는 프로세스당 모델 문자열마다 한 번씩 이 줄을 기록합니다. [서브에이전트](/docs/ko/sub-agents#choose-a-model)나 [백그라운드 기능](/docs/ko/costs#background-token-usage)이 사용하는 것처럼 추가로 인식되지 않는 ID마다 별도의 줄을 기록합니다.

5467 5484

5468Claude Code는 인식하는 모델로 해석하는 공급자 ID에 대해 줄을 기록하지 않습니다. Amazon Bedrock `us.anthropic.claude-...` ID, Google Cloud의 `@` 버전 접미사가 있는 Agent Platform ID, Claude 모델 ID를 포함하는 Microsoft Foundry 배포 이름. Claude Code는 ARN 자체가 아닌 Amazon Bedrock [애플리케이션 추론 프로필 ARN](/docs/ko/amazon-bedrock#map-each-model-version-to-an-inference-profile) 뒤의 모델을 확인합니다. 잘못된 것 같은 해석할 수 없는 ARN에 대해 줄을 기록하지 않습니다.5485Claude Code는 Amazon Bedrock `us.anthropic.claude-...` ID, `@` 버전 접미사가 있는 Google Cloud의 Agent Platform ID, Claude 모델 ID를 포함하는 Microsoft Foundry 배포 이름처럼 인식하는 모델로 해석되는 공급자 ID에 대해서는 이 줄을 기록하지 않습니다. Amazon Bedrock [애플리케이션 추론 프로필 ARN](/docs/ko/amazon-bedrock#map-each-model-version-to-an-inference-profile)의 경우 ARN 자체가 아니라 그 뒤의 모델을 확인합니다. 잘못 입력한 ARN처럼 해석할 수 없는 ARN에 대해서는 줄을 기록하지 않습니다.

5469 5486

5470**할 일:**5487**할 일:**

5471 5488

5472* ID를 의도적으로 설정한 경우(예: [LLM 게이트웨이](/docs/ko/llm-gateway) 별칭) [`modelOverrides`](/docs/ko/model-config#override-model-ids-per-version) 항목을 [설정 파일](/docs/ko/settings#where-settings-live)에 추가하고 ID를 값으로 사용하세요. `opus` 같은 패밀리 별칭이 아닌 Anthropic 모델 ID를 키로 사용하세요. 예제 줄의 `my-proxy-model`에 대해 이 항목을 추가하세요:5489* [LLM 게이트웨이](/docs/ko/llm-gateway) 별칭처럼 ID를 의도적으로 설정한 경우, 해당 ID를 값으로 하는 [`modelOverrides`](/docs/ko/model-config#override-model-ids-per-version) 항목을 [설정 파일](/docs/ko/settings#where-settings-live)에 추가하세요. 키로는 `opus` 같은 패밀리 별칭이 아닌 Anthropic 모델 ID를 사용하세요. 예시 줄의 `my-proxy-model`에 대해서는 다음 항목을 추가합니다:

5473 5490

5474 ```json theme={null}5491 ```json theme={null}

5475 {5492 {

5479 }5496 }

5480 ```5497 ```

5481 5498

5482 Claude Code는 `my-proxy-model`을 `claude-opus-4-6`으로 취급하고 줄 기록을 중지합니다.5499 그러면 Claude Code는 `my-proxy-model`을 `claude-opus-4-6`으로 취급하고 줄 기록을 중지합니다.

5483 5500

5484* ID가 Claude Code 버전보다 최신 모델을 이름으로 지정하면 `claude update`를 실행하세요.5501* ID가 사용 중인 Claude Code 버전보다 최신 모델을 가리키면 `claude update`를 실행하세요.

5485 5502

5486* ID가 오타이면 [모델을 설정할 수 있는 위치](/docs/ko/model-config#setting-your-model) 또는 [별칭 변수](/docs/ko/model-config#environment-variables) 중 이를 보유한 곳에서 수정하세요. `query_source`가 `agent:`로 시작하면 [서브에이전트의 모델을 설정](/docs/ko/sub-agents#choose-a-model)한 곳에서 대신 수정하세요.5503* ID가 오타인 경우 [모델을 설정할 수 있는 위치](/docs/ko/model-config#setting-your-model) 또는 [별칭 변수](/docs/ko/model-config#environment-variables) 중 해당 ID가 있는 곳에서 수정하세요. `query_source`가 `agent:`로 시작하면 대신 [서브에이전트의 모델](/docs/ko/sub-agents#choose-a-model)을 설정한 곳에서 수정하세요.

5487 5504

5488v2.1.233 이전에는 Claude Code가 인식하지 못하는 모델 ID에 대한 요청을 보낼 때 줄을 기록하지 않았습니다.5505v2.1.233 이전에는 Claude Code가 인식하지 못하는 모델 ID로 요청을 보낼 때 줄을 기록하지 않았습니다.

5489 5506

5490<h3 id="stale-sandbox-mask-files-left-by-a-killed-session">5507<h3 id="stale-sandbox-mask-files-left-by-a-killed-session">

5491 종료된 세션이 남긴 오래된 샌드박스 마스크 파일5508 강제 종료된 세션이 남긴 오래된 샌드박스 마스크 파일

5492</h3>5509</h3>

5493 5510

5494`claude doctor`는 진단에서 이 경고를 출력하며 `/status`는 동일한 줄을 나열합니다. [샌드박싱](/docs/ko/sandboxing)이 파일 시스템 격리를 켜서 활성화되면 Linux 및 WSL2에 나타납니다.5511`claude doctor`는 진단 결과에 이 경고를 출력하며, `/status`에도 같은 줄이 나열됩니다. 이 경고는 Linux 및 WSL2에서 파일 시스템 격리가 켜진 상태로 [샌드박싱](/docs/ko/sandboxing)이 활성화된 경우에 나타납니다.

5495 5512

5496샌드박스된 명령이 실행되는 동안 샌드박스는 아직 존재하지 않는 파일에 대한 쓰기 거부를 0바이트 읽기 전용 자리 표시자를 만들어 유지하고 나중에 제거합니다. SIGKILL로 종료된 세션 같은 정리 전에 세션이 종료되면 자리 표시자가 남습니다. 이후 세션은 모든 시작에서 읽기 전용으로 다시 바인드하므로 "Yes, and don't ask again" 저장 같은 설정 쓰기가 하나가 있는 곳에서 실패합니다.5513샌드박스된 명령이 실행되는 동안 샌드박스는 아직 존재하지 않는 파일에 대한 쓰기 거부를 유지하기 위해 해당 위치에 0바이트 읽기 전용 자리 표시자를 만들고, 이후에 제거합니다. SIGKILL 등으로 이 정리 작업 전에 세션이 강제 종료되면 자리 표시자가 남습니다. 이후 세션은 시작할 때마다 이를 다시 읽기 전용으로 바인드하므로, 자리 표시자가 있는 위치에서는 "Yes, and don't ask again" 저장 같은 설정 쓰기가 실패합니다.

5497 5514

5498```text theme={null}5515```text theme={null}

5499- 종료된 세션이 남긴 오래된 샌드박스 마스크 파일: /home/you/project/.claude/settings.local.json5516- Stale sandbox mask files left by a killed session: /home/you/project/.claude/settings.local.json

5500 수정: 다른 Claude Code 세션이 해당 프로젝트에서 실행되지 않는 동안 각각을 `rm <path>`로 제거하세요 — 설정 파일이 속한 곳의 0바이트 읽기 전용 파일은 "Yes, and don't ask again" 저장을 실패하게 하며 샌드박스는 모든 시작에서 읽기 전용으로 다시 바인드합니다.5517 Fix: Remove each with `rm <path>` while no other Claude Code session is running in that project — a 0-byte read-only file where a settings file belongs makes "Yes, and don't ask again" fail to save, and the sandbox binds it read-only again on every start

5501```5518```

5502 5519

5503**할 일:**5520**할 일:**

5504 5521

5505* 해당 프로젝트에서 실행 중인 다른 Claude Code 세션을 종료한 후 `rm`으로 각 나열된 파일을 삭제하세요. 경고는 최대 3개 파일을 이름으로 지정하고 나머지를 계산하므로 경고가 더 이상 나타나지 않을 때까지 삭제 후 `claude doctor`를 다시 실행하세요. 다른 세션의 샌드박스가 여전히 사용 중인 자리 표시자는 해당 세션의 쓰기 보호의 라이브 부분입니다.5522* 해당 프로젝트에서 실행 중인 다른 Claude Code 세션을 종료한 후 나열된 각 파일을 `rm`으로 삭제하세요. 경고는 최대 3개의 파일을 명시하고 나머지는 개수로 표시하므로, 삭제 후 경고가 더 이상 나타나지 않을 때까지 `claude doctor`를 다시 실행하세요. 다른 세션의 샌드박스가 아직 사용 중인 자리 표시자는 해당 세션의 쓰기 보호에서 실제로 작동하는 부분입니다.

5506* "Yes, and don't ask again"으로 저장한 권한 선택이 고착되지 않으면 자리 표시자를 삭제한 후 다시 저장하세요.5523* "Yes, and don't ask again"으로 저장한 권한 선택이 유지되지 않았다면 자리 표시자를 삭제한 후 다시 저장하세요.

5507 5524

5508v2.1.257 이전에는 `claude doctor`가 이러한 파일을 플래그하지 않았습니다. 이전 버전은 세션이 종료될 때 동일한 자리 표시자를 남깁니다.5525v2.1.257 이전에는 `claude doctor`가 이러한 파일을 표시하지 않았으며, 이전 버전에서도 세션이 강제 종료되면 같은 자리 표시자가 남습니다.

5509 5526

5510<h2 id="responses-seem-lower-quality-than-usual">5527<h2 id="responses-seem-lower-quality-than-usual">

5511 응답 품질이 평소보다 낮아 보입니다5528 응답 품질이 평소보다 낮아 보입니다

hooks.md +789 −773

Details

12 12

13Hook은 Claude Code의 수명 주기에서 특정 지점에 자동으로 실행되는 사용자 정의 셸 명령, HTTP 엔드포인트, MCP 도구 호출, LLM 프롬프트 또는 서브에이전트입니다. Claude Code는 터미널의 세션, IDE 확장 프로그램, [데스크톱 앱](/docs/ko/desktop-quickstart), [클라우드 세션](/docs/ko/claude-code-on-the-web)을 포함하여 실행되는 모든 곳에서 동일한 hook 이벤트를 발생시킵니다. 이 참조를 사용하여 이벤트 스키마, 구성 옵션, JSON 입출력 형식, 비동기 hook, HTTP hook, MCP 도구 hook과 같은 고급 기능을 조회할 수 있습니다.13Hook은 Claude Code의 수명 주기에서 특정 지점에 자동으로 실행되는 사용자 정의 셸 명령, HTTP 엔드포인트, MCP 도구 호출, LLM 프롬프트 또는 서브에이전트입니다. Claude Code는 터미널의 세션, IDE 확장 프로그램, [데스크톱 앱](/docs/ko/desktop-quickstart), [클라우드 세션](/docs/ko/claude-code-on-the-web)을 포함하여 실행되는 모든 곳에서 동일한 hook 이벤트를 발생시킵니다. 이 참조를 사용하여 이벤트 스키마, 구성 옵션, JSON 입출력 형식, 비동기 hook, HTTP hook, MCP 도구 hook과 같은 고급 기능을 조회할 수 있습니다.

14 14

15플러그인은 Claude Code가 자체 프로세스에서 호출하는 JavaScript 함수로 훅을 등록할 수도 있으며, 이러한 함수는 이벤트에 대응할 뿐 아니라 인터페이스에 그리기도 할 수 있습니다. 이렇게 하는 플러그인을 [mod](/docs/ko/plugins/mods/overview)라고 하며, 이러한 함수 훅은 이 페이지가 아닌 [이벤트에 반응하기](/docs/ko/plugins/mods/events)에서 다룹니다. 이 페이지의 훅은 mod와 함께 계속 작동합니다.

15<h2 id="hook-lifecycle">17<h2 id="hook-lifecycle">

16 Hook 수명 주기18 Hook 수명 주기

17</h2>19</h2>

270 272

271[클라우드 세션](/docs/ko/claude-code-on-the-web)은 로컬 `~/.claude/settings.json`을 읽지 않습니다. 거기의 hook은 리포지토리에서 나옵니다. 즉, 한 리포지토리가 있는 세션의 `.claude/settings.json`과 모든 세션에서 선언하는 플러그인, 그리고 조직의 서버 관리 설정에서 나옵니다. [자체 호스팅 환경](/docs/ko/self-hosted-environments-configuration#permissions-and-tool-approval)에서 Claude Code는 또한 운영자가 실행기 호스트의 `~/.claude/`에서 시드한 hook을 실행하고, [Claude Code가 적용하는 관리형 소스](/docs/ko/managed-settings#how-claude-code-combines-managed-sources) 중 하나인 실행기 이미지의 관리형 설정 파일에서 hook을 실행합니다. 기본적으로 서버 관리 설정이나 MDM 전달 Claude Code 정책이 관리형 계층을 제공하지 않을 때만 해당됩니다. 클라우드 세션에 도달하는 파일에 대해서는 [설정에서 이월되는 항목](/docs/ko/cloud-environments#what-carries-over-from-your-setup)을 참조하십시오.273[클라우드 세션](/docs/ko/claude-code-on-the-web)은 로컬 `~/.claude/settings.json`을 읽지 않습니다. [자체 호스팅 환경](/docs/ko/self-hosted-environments-configuration#permissions-and-tool-approval)에서 Claude Code는 또한 운영자가 실행기 호스트의 `~/.claude/`에서 시드한 훅을 실행하고, 실행기 이미지의 관리형 설정 파일이 [Claude Code가 적용하는 관리형 소스](/docs/ko/managed-settings#how-claude-code-combines-managed-sources) 중 하나일 때 해당 파일의 훅을 실행합니다. 이는 기본적으로 서버 관리 설정이나 MDM 전달 Claude Code 정책이 관리형 계층을 제공하지 않을 때만 해당됩니다. 어떤 설정 파일과 플러그인, 따라서 어떤 훅이 클라우드 세션에 도달하는지는 [설정에서 이월되는 항목](/docs/ko/cloud-environments#what-carries-over-from-your-setup)을 참조하십시오.

272 274

273설정 파일 해결에 대한 자세한 내용은 [설정](/docs/ko/settings)을 참조하십시오.275설정 파일 해결에 대한 자세한 내용은 [설정](/docs/ko/settings)을 참조하십시오.

274 276

275설정 파일, 관리형 정책 설정 및 플러그인의 Hook도 [서브에이전트](/docs/ko/sub-agents) 내에서 실행됩니다. 서브에이전트가 도구를 호출할 때, `PreToolUse` 및 `PostToolUse`와 같은 도구 이벤트는 주 대화에서 구성된 것과 동일한 hook을 실행하며, 입력은 서브에이전트를 식별하는 `agent_id` 및 `agent_type` [공통 입력 필드](#common-input-fields)를 전달합니다.277설정 파일, 관리형 정책 설정 및 플러그인의 Hook도 [서브에이전트](/docs/ko/sub-agents) 내에서 실행됩니다. 서브에이전트가 도구를 호출할 때, `PreToolUse` 및 `PostToolUse`와 같은 도구 이벤트는 주 대화에서 구성된 것과 동일한 hook을 실행하며, 입력은 서브에이전트를 식별하는 `agent_id` 및 `agent_type` [공통 입력 필드](#common-input-fields)를 전달합니다.

276 278

277엔터프라이즈 관리자는 `allowManagedHooksOnly`를 사용하여 실행되는 hook을 제한할 수 있습니다:279관리자는 [관리형 설정](/docs/ko/managed-settings)에서 [`allowManagedHooksOnly`](/docs/ko/settings-reference#allowmanagedhooksonly)를 사용하여 실행되는 훅을 제한할 수 있습니다:

278 280

279* 사용자, 프로젝트, 로컬 및 플러그인 hook이 차단됩니다. 관리형 설정 `enabledPlugins`에서 강제 활성화된 플러그인의 Hook은 제외됩니다.281* 사용자, 프로젝트, 로컬 및 플러그인 hook이 차단됩니다. 관리형 설정 `enabledPlugins`에서 강제 활성화된 플러그인의 Hook은 제외됩니다.

280* Claude Code는 또한 [`statusLine`](/docs/ko/statusline), [`fileSuggestion`](/docs/ko/settings-reference#filesuggestion) 및 [`subagentStatusLine`](/docs/ko/statusline#subagent-status-lines) 설정을 관리형 설정으로 좁힙니다.282* Claude Code는 또한 [`statusLine`](/docs/ko/statusline), [`fileSuggestion`](/docs/ko/settings-reference#filesuggestion) 및 [`subagentStatusLine`](/docs/ko/statusline#subagent-status-lines) 설정을 관리형 설정으로 좁힙니다.

281* Claude Code는 또한 [`disableCommandPluginSources`](/docs/ko/settings-reference#disablecommandpluginsources)가 명시적으로 `false`로 설정되지 않은 한 [`command` 소스](/docs/ko/plugin-marketplaces#command-sources)가 있는 플러그인을 비활성화합니다. 여기에는 관리형 설정 `enabledPlugins`에서 강제 활성화된 플러그인이 포함됩니다. `command` 소스는 Claude Code v2.1.229 이상이 필요합니다.283* Claude Code는 또한 [`disableCommandPluginSources`](/docs/ko/settings-reference#disablecommandpluginsources)가 명시적으로 `false`로 설정되지 않은 한 [`command` 소스](/docs/ko/plugins/marketplace-reference#command-plugin-source)가 있는 플러그인을 비활성화합니다. 여기에는 관리형 설정 `enabledPlugins`에서 강제 활성화된 플러그인이 포함됩니다. `command` 소스는 Claude Code v2.1.229 이상이 필요합니다.

282* Claude Code는 또한 [`disableCommandPluginSources`](/docs/ko/settings-reference#disablecommandpluginsources)가 명시적으로 `false`로 설정되지 않은 한 마켓플레이스 [`headersHelper` 명령](/docs/ko/plugin-marketplaces#authenticate-archive-downloads)을 차단합니다. 단, 관리형 설정 자체가 선언하는 마켓플레이스는 제외됩니다.284* Claude Code는 또한 [`disableCommandPluginSources`](/docs/ko/settings-reference#disablecommandpluginsources)가 명시적으로 `false`로 설정되지 않은 한 마켓플레이스 [`headersHelper` 명령](/docs/ko/plugins/host-marketplace#authenticate-archive-downloads)을 차단합니다. 단, 관리형 설정 자체가 선언하는 마켓플레이스는 제외됩니다.

283 285

284[`allowManagedHooksOnly`에서 실행되는 항목](/docs/ko/settings-reference#what-runs-under-allowmanagedhooksonly)을 참조하십시오.286[`allowManagedHooksOnly`에서 실행되는 항목](/docs/ko/settings-reference#what-runs-under-allowmanagedhooksonly)을 참조하십시오.

285 287

304 306

305정규 표현식 경로의 matcher는 JavaScript의 `RegExp.prototype.test`로 테스트되며, 값의 어디든지 일치하면 성공합니다. `Edit.*`는 `Edit`과 `NotebookEdit` 모두와 일치합니다. 전체 문자열 일치가 필요한 경우 `^Edit$`와 같이 패턴을 `^` 및 `$`로 래핑하십시오.307정규 표현식 경로의 matcher는 JavaScript의 `RegExp.prototype.test`로 테스트되며, 값의 어디든지 일치하면 성공합니다. `Edit.*`는 `Edit`과 `NotebookEdit` 모두와 일치합니다. 전체 문자열 일치가 필요한 경우 `^Edit$`와 같이 패턴을 `^` 및 `$`로 래핑하십시오.

306 308

307쉼표 구분 기호와 주변 공백 허용은 Claude Code v2.1.191 이상이 필요합니다.

~~308~~

309정확한 일치 집합의 하이픈은 Claude Code v2.1.195 이상이 필요합니다. 이전 버전에서는 `code-reviewer`와 같은 하이픈이 있는 이름이 앵커 없는 정규 표현식으로 평가되므로 `senior-code-reviewer`에 대해서도 실행됩니다. 해당 버전에서 해당 이름만 일치하도록 `^code-reviewer$`로 앵커하십시오.

~~310~~

311`FileChanged` 및 `StopFailure`는 문자, 숫자, `_` 및 `|`만 포함하는 더 좁은 정확한 일치 집합을 사용합니다. matcher에 하이픈, 공백 또는 쉼표가 있으면 이 두 이벤트에 대해 정규 표현식 경로에 유지되며, `|`만 대안을 구분합니다. matcher 지원이 있는 다른 모든 이벤트는 `|` 또는 `,`를 허용합니다.309`FileChanged` 및 `StopFailure`는 문자, 숫자, `_` 및 `|`만 포함하는 더 좁은 정확한 일치 집합을 사용합니다. matcher에 하이픈, 공백 또는 쉼표가 있으면 이 두 이벤트에 대해 정규 표현식 경로에 유지되며, `|`만 대안을 구분합니다. matcher 지원이 있는 다른 모든 이벤트는 `|` 또는 `,`를 허용합니다.

312 310

313`FileChanged` 이벤트는 감시 목록을 작성할 때 이러한 규칙을 따르지 않습니다. [FileChanged](#filechanged)를 참조하십시오.311`FileChanged` 이벤트는 감시 목록을 작성할 때 이러한 규칙을 따르지 않습니다. [FileChanged](#filechanged)를 참조하십시오.

382* `mcp__brave-search__.*`는 이름에 하이픈이 포함된 서버의 모든 도구와 일치합니다.380* `mcp__brave-search__.*`는 이름에 하이픈이 포함된 서버의 모든 도구와 일치합니다.

383* `mcp__.*__write.*`는 모든 서버의 이름이 `write`로 시작하는 모든 도구와 일치합니다.381* `mcp__.*__write.*`는 모든 서버의 이름이 `write`로 시작하는 모든 도구와 일치합니다.

384 382

385정확한 일치 집합의 하이픈은 Claude Code v2.1.195 이상이 필요합니다. 이전 버전에서는 `mcp__brave-search`와 같은 하이픈이 있는 접두사가 앵커 없는 정규 표현식으로 평가되어 해당 서버의 모든 도구와 일치합니다. `mcp__brave-search__.*` 형식은 모든 버전에서 작동합니다.

~~386~~

387[플러그인 번들 MCP 서버](/docs/ko/mcp#plugin-provided-mcp-servers)의 도구는 플러그인 이름을 포함하는 범위 지정 서버 세그먼트를 사용합니다: `mcp__plugin_<plugin-name>_<server-name>__<tool>`. 베어 서버 키에 대해 작성된 matcher는 이러한 도구에 대해 실행되지 않습니다. `db` 키 아래에 서버를 번들하는 `my-plugin`이라는 플러그인의 경우 `query` 도구는 `mcp__plugin_my-plugin_db__query`로 나타나므로 해당 서버의 모든 도구에 대한 matcher는 `mcp__plugin_my-plugin_db__.*`입니다. 핸들러의 [`if` 필드](#common-fields)에서 동일한 범위 지정 도구 이름을 사용합니다. 범위 지정 이름이 작성되는 방식에 대해서는 [플러그인 제공 MCP 서버](/docs/ko/mcp#plugin-provided-mcp-servers)를 참조하십시오.383[플러그인 번들 MCP 서버](/docs/ko/mcp#plugin-provided-mcp-servers)의 도구는 플러그인 이름을 포함하는 범위 지정 서버 세그먼트를 사용합니다: `mcp__plugin_<plugin-name>_<server-name>__<tool>`. 베어 서버 키에 대해 작성된 matcher는 이러한 도구에 대해 실행되지 않습니다. `db` 키 아래에 서버를 번들하는 `my-plugin`이라는 플러그인의 경우 `query` 도구는 `mcp__plugin_my-plugin_db__query`로 나타나므로 해당 서버의 모든 도구에 대한 matcher는 `mcp__plugin_my-plugin_db__.*`입니다. 핸들러의 [`if` 필드](#common-fields)에서 동일한 범위 지정 도구 이름을 사용합니다. 범위 지정 이름이 작성되는 방식에 대해서는 [플러그인 제공 MCP 서버](/docs/ko/mcp#plugin-provided-mcp-servers)를 참조하십시오.

388 384

389이 예제는 모든 메모리 서버 작업을 기록하고 모든 MCP 서버의 쓰기 작업을 검증합니다:385이 예제는 모든 메모리 서버 작업을 기록하고 모든 MCP 서버의 쓰기 작업을 검증합니다:

423 419

424* **[명령 hook](#command-hook-fields)** (`type: "command"`): 셸 명령을 실행합니다. 스크립트는 stdin의 이벤트 [JSON 입력](#hook-input-and-output)을 수신하고 종료 코드 및 stdout을 통해 결과를 다시 전달합니다.420* **[명령 hook](#command-hook-fields)** (`type: "command"`): 셸 명령을 실행합니다. 스크립트는 stdin의 이벤트 [JSON 입력](#hook-input-and-output)을 수신하고 종료 코드 및 stdout을 통해 결과를 다시 전달합니다.

425* **[HTTP hook](#http-hook-fields)** (`type: "http"`): 이벤트의 JSON 입력을 HTTP POST 요청으로 URL에 보냅니다. 엔드포인트는 명령 hook과 동일한 [JSON 출력 형식](#json-output)을 사용하여 응답 본문을 통해 결과를 다시 전달합니다.421* **[HTTP hook](#http-hook-fields)** (`type: "http"`): 이벤트의 JSON 입력을 HTTP POST 요청으로 URL에 보냅니다. 엔드포인트는 명령 hook과 동일한 [JSON 출력 형식](#json-output)을 사용하여 응답 본문을 통해 결과를 다시 전달합니다.

426* **[MCP 도구 hook](#mcp-tool-hook-fields)** (`type: "mcp_tool"`): 이미 연결된 [MCP 서버](/docs/ko/mcp)의 도구를 호출합니다. 도구의 텍스트 출력은 명령 hook stdout처럼 처리됩니다.422* **[MCP 도구 훅](#mcp-tool-hook-fields)** (`type: "mcp_tool"`): 구성된 [MCP 서버](/docs/ko/mcp)의 도구를 호출합니다. 도구의 텍스트 출력은 명령 훅 stdout처럼 처리됩니다.

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

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

429 425

465 459

466Claude Code가 Bash 입력이 실행하는 명령을 결정할 수 없으면 패턴에 관계없이 hook을 실행합니다. `if` 필터는 최선의 노력이므로 하드 허용 또는 거부를 적용하려면 hook 대신 [권한 시스템](/docs/ko/permissions)을 사용하십시오.460Claude Code가 Bash 입력이 실행하는 명령을 결정할 수 없으면 패턴에 관계없이 hook을 실행합니다. `if` 필터는 최선의 노력이므로 하드 허용 또는 거부를 적용하려면 hook 대신 [권한 시스템](/docs/ko/permissions)을 사용하십시오.

476| `command` | 예 | 실행할 셸 명령. `args`를 사용하면 직접 생성할 실행 파일입니다. [Exec 형식 및 셸 형식](#exec-form-and-shell-form) 참조 |470| `command` | 예 | 실행할 셸 명령. `args`를 사용하면 직접 생성할 실행 파일입니다. [Exec 형식 및 셸 형식](#exec-form-and-shell-form) 참조 |

477| `args` | 아니요 | 인수 목록. 존재하면 `command`는 실행 파일로 해결되고 `args`를 인수 벡터로 하여 직접 생성되며, 셸이 관여하지 않습니다. [Exec 형식 및 셸 형식](#exec-form-and-shell-form) 참조 |471| `args` | 아니요 | 인수 목록. 존재하면 `command`는 실행 파일로 해결되고 `args`를 인수 벡터로 하여 직접 생성되며, 셸이 관여하지 않습니다. [Exec 형식 및 셸 형식](#exec-form-and-shell-form) 참조 |

478| `async` | 아니요 | `true`이면 차단하지 않고 백그라운드에서 실행됩니다. [백그라운드에서 hook 실행](#run-hooks-in-the-background) 참조 |472| `async` | 아니요 | `true`이면 차단하지 않고 백그라운드에서 실행됩니다. [백그라운드에서 hook 실행](#run-hooks-in-the-background) 참조 |

479| `asyncRewake` | 아니요 | `true`이면 백그라운드에서 실행되고 종료 코드 2에서 Claude를 깨웁니다. hook의 stderr 또는 stderr가 비어 있으면 stdout이 Claude에게 시스템 알림으로 표시되므로 장시간 실행되는 백그라운드 실패에 반응할 수 있습니다. |473| `asyncRewake` | 아니요 | `true`이면 백그라운드에서 실행되고 종료 코드 2에서 Claude를 깨웁니다. 훅의 stderr 또는 stderr가 비어 있으면 stdout이 Claude에게 [시스템 리마인더](/docs/ko/glossary#system-reminder)로 표시되므로 장시간 실행되는 백그라운드 실패에 반응할 수 있습니다. |

480| `shell` | 아니요 | 이 hook에 사용할 셸. `"bash"` 또는 `"powershell"`을 허용합니다. 기본값은 `"bash"` 또는 Git Bash가 설치되지 않은 경우 Windows에서 `"powershell"`입니다. `"powershell"`을 설정하면 Windows에서 PowerShell을 통해 명령을 실행합니다. `CLAUDE_CODE_USE_POWERSHELL_TOOL`이 필요하지 않습니다. hook이 PowerShell을 직접 생성하기 때문입니다. `args`가 설정되면 무시됩니다. |474| `shell` | 아니요 | 이 hook에 사용할 셸. `"bash"` 또는 `"powershell"`을 허용합니다. 기본값은 `"bash"` 또는 Git Bash가 설치되지 않은 경우 Windows에서 `"powershell"`입니다. `"powershell"`을 설정하면 Windows에서 PowerShell을 통해 명령을 실행합니다. `CLAUDE_CODE_USE_POWERSHELL_TOOL`이 필요하지 않습니다. hook이 PowerShell을 직접 생성하기 때문입니다. `args`가 설정되면 무시됩니다. |

481 475

482<a id="exec-form-and-shell-form" />476<a id="exec-form-and-shell-form" />

516 510

517두 형식 모두 동일한 [경로 자리 표시자](#reference-scripts-by-path)를 지원하며, 둘 다 생성된 프로세스에서 `CLAUDE_PROJECT_DIR`, `CLAUDE_PLUGIN_ROOT` 및 `CLAUDE_PLUGIN_DATA`를 환경 변수로 내보내므로 스크립트는 시작 방식에 관계없이 `process.env.CLAUDE_PLUGIN_ROOT`를 읽을 수 있습니다.511두 형식 모두 동일한 [경로 자리 표시자](#reference-scripts-by-path)를 지원하며, 둘 다 생성된 프로세스에서 `CLAUDE_PROJECT_DIR`, `CLAUDE_PLUGIN_ROOT` 및 `CLAUDE_PLUGIN_DATA`를 환경 변수로 내보내므로 스크립트는 시작 방식에 관계없이 `process.env.CLAUDE_PLUGIN_ROOT`를 읽을 수 있습니다.

518 512

519플러그인 hook은 추가로 [`${user_config.*}`](/docs/ko/plugins-reference#user-configuration) 값을 exec 형식에서만 대체합니다: 값은 일반 문자열로 `command` 및 각 `args` 요소로 대체되므로 셸이 다시 파싱하지 않습니다.513플러그인 훅은 추가로 [`${user_config.*}`](/docs/ko/plugins/manifest-reference#user-configuration) 값을 exec 형식에서만 대체합니다: 값은 일반 문자열로 `command` 및 각 `args` 요소로 대체되므로 셸이 다시 파싱하지 않습니다.

520 514

521`command`가 `${user_config.*}`를 참조하는 셸 형식 플러그인 hook은 실행되는 대신 [오류](/docs/ko/errors#plugin-command-references-user-config)로 실패합니다. 셸 형식 hook에서 옵션 값을 사용하려면 `$CLAUDE_PLUGIN_OPTION_<KEY>` 환경 변수(예: `webhook_url` 옵션의 경우 `$CLAUDE_PLUGIN_OPTION_WEBHOOK_URL`)를 읽거나 `args`를 설정하여 hook을 exec 형식으로 전환합니다. v2.1.207 이전에는 셸 형식 플러그인 hook 명령도 `${user_config.*}`를 대체했습니다.515`command`가 `${user_config.*}`를 참조하는 셸 형식 플러그인 hook은 실행되는 대신 [오류](/docs/ko/errors#plugin-command-references-user-config)로 실패합니다. 셸 형식 hook에서 옵션 값을 사용하려면 `$CLAUDE_PLUGIN_OPTION_<KEY>` 환경 변수(예: `webhook_url` 옵션의 경우 `$CLAUDE_PLUGIN_OPTION_WEBHOOK_URL`)를 읽거나 `args`를 설정하여 hook을 exec 형식으로 전환합니다. v2.1.207 이전에는 셸 형식 플러그인 hook 명령도 `${user_config.*}`를 대체했습니다.

522 516

573 567

574| 필드 | 필수 | 설명 |568| 필드 | 필수 | 설명 |

575| :- | :- | :- |569| :- | :- | :- |

576| `server` | 예 | 구성된 MCP 서버의 이름. [플러그인 번들 서버](/docs/ko/mcp#plugin-provided-mcp-servers)의 경우 `plugin:my-plugin:db`와 같은 범위 지정 이름 `plugin:<plugin-name>:<server-name>`입니다. 베어 서버 키가 아닙니다. 서버는 이미 연결되어 있어야 합니다. hook은 OAuth 또는 연결 흐름을 트리거하지 않습니다. |570| `server` | 예 | 구성된 MCP 서버의 이름. [플러그인 번들 서버](/docs/ko/mcp#plugin-provided-mcp-servers)의 경우 `plugin:my-plugin:db`와 같은 범위 지정 이름 `plugin:<plugin-name>:<server-name>`입니다. 베어 서버 키가 아닙니다. |

577| `tool` | 예 | 해당 서버에서 호출할 도구의 이름 |571| `tool` | 예 | 해당 서버에서 호출할 도구의 이름 |

578| `input` | 아니요 | 도구에 전달된 인수. 문자열 값은 hook의 [JSON 입력](#hook-input-and-output)에서 `${path}` 대체를 지원합니다. 예를 들어 `"${tool_input.file_path}"` |572| `input` | 아니요 | 도구에 전달된 인수. 문자열 값은 hook의 [JSON 입력](#hook-input-and-output)에서 `${path}` 대체를 지원합니다. 예를 들어 `"${tool_input.file_path}"` |

579 573

580Claude Code는 도구의 텍스트 콘텐츠를 명령 hook stdout과 동일한 방식으로 읽으며, [종료 코드 0](#exit-code-0) 아래의 파싱 규칙을 따릅니다. 명명된 서버가 연결되지 않았거나 도구가 `isError: true`를 반환하면 hook은 차단하지 않는 오류를 생성하고 실행이 계속됩니다.

~~581~~

582이 예제는 각 `Write` 또는 `Edit` 후에 `my_server` MCP 서버의 `security_scan` 도구를 호출하고 편집된 파일의 경로를 전달합니다:574이 예제는 각 `Write` 또는 `Edit` 후에 `my_server` MCP 서버의 `security_scan` 도구를 호출하고 편집된 파일의 경로를 전달합니다:

583 575

584```json theme={null}576```json theme={null}

601}593}

602```594```

603 595

604`mcp_tool` hook은 Claude Code가 세션의 MCP 서버를 hook에 사용 가능하게 만든 후에만 실행될 수 있습니다. `SessionStart` 및 `Setup`은 그 시점 이전에 실행될 수 있습니다:596<h5 id="how-the-tool’s-result-is-read">

597 도구 결과를 읽는 방식

598</h5>

605 599

606* **시작 시**: `SessionStart`는 `--continue` 또는 `--resume`으로 시작할 때를 포함하여 서버를 사용 가능하기 전에 실행됩니다. Claude Code는 도구를 호출하지 않고 이벤트의 `mcp_tool` hook을 건너뛰고 [디버그 로그](#debug-hooks)는 `mcp_tool hooks are not available for the 'SessionStart' hook event (no MCP client context)`를 기록합니다.600Claude Code는 도구의 텍스트 콘텐츠를 명령 훅 stdout과 동일한 방식으로 읽으며, [종료 코드 0 아래의 파싱 규칙](#exit-code-0)을 따릅니다. 도구가 `isError: true`를 반환하면 훅은 차단하지 않는 오류를 생성하고 실행이 계속됩니다.

607* **실행 중인 세션의 나중**: `/clear` 또는 압축 후 `SessionStart`는 서버가 이미 사용 가능한 상태에서 다시 실행되고 `mcp_tool` hook이 실행됩니다.

608* **`Setup`에서**: `Setup`은 항상 서버를 사용 가능하기 전에 실행되므로 Claude Code는 매번 `mcp_tool` hook을 건너뛰고 `SessionStart`를 명명하는 동일한 메시지를 기록합니다.

609 601

610예를 들어 이 구성은 matcher가 없는 `SessionStart` hook에서 `my_server` MCP 서버의 `load_context` 도구를 호출하므로 모든 `SessionStart` 소스에 적용됩니다:602<h5 id="when-the-server-is-still-connecting">

603 서버가 아직 연결 중일 때

604</h5>

611 605

612```json theme={null}606`PreToolUse` 또는 `Stop`과 같이 훅이 결과를 차단하거나 변경할 수 있는 이벤트에서 Claude Code는 도구를 호출하기 전에 연결 중인 서버를 최대 [`MCP_TIMEOUT`](/docs/ko/env-vars)까지, 그리고 훅 자체의 [`timeout`](#common-fields) 내에서 기다립니다. `Notification` 또는 `SessionEnd`와 같은 관찰용 이벤트에서는 기다리지 않습니다.

613{607

614 "hooks": {608[`cached` 상태](/docs/ko/mcp#server-status-detail)를 표시하는 서버는 훅이 해당 도구를 호출할 때 연결됩니다. 그 시점에 서버가 연결되어 있지 않으면 훅은 차단하지 않는 오류를 생성하고 실행이 계속됩니다. 훅은 OAuth 흐름을 시작하지 않으므로 먼저 [`/mcp`에서 서버를 인증](/docs/ko/mcp#authenticate-with-remote-mcp-servers)하십시오.

615 "SessionStart": [

616 {

617 "hooks": [

618 {

619 "type": "mcp_tool",

620 "server": "my_server",

621 "tool": "load_context"

622 }

623 ]

624 }

625 ]

626 }

627}

628```

629 609

630`claude`를 실행하면 Claude Code는 이 hook을 건너뛰고 `load_context`를 호출하지 않으며 `no MCP client context` 메시지를 디버그 로그에 씁니다. 동일한 세션에서 `/clear`를 실행하면 hook이 실행되고 `load_context`를 호출합니다. `type: "command"` hook은 `SessionStart`에서 실행되므로 세션이 첫 번째 턴에서 필요한 모든 항목에 하나를 사용합니다.610<h5 id="events-that-fire-before-mcp-servers-are-available">

611 MCP 서버를 사용할 수 있기 전에 실행되는 이벤트

612</h5>

613

614`--continue` 또는 `--resume`을 사용하는 경우를 포함한 시작 시의 `SessionStart`와 모든 `Setup` 이벤트는 세션의 MCP 서버를 훅에서 사용할 수 있게 되기 전에 실행됩니다. Claude Code는 도구를 호출하지 않고 해당 이벤트의 `mcp_tool` 훅을 건너뛰며, [디버그 로그](#debug-hooks)는 `mcp_tool hooks are not available for the 'SessionStart' hook event (no MCP client context)` 또는 `Setup`을 명명하는 동일한 메시지를 기록합니다. `/clear` 또는 압축 후 세션 중에 `SessionStart`가 다시 실행되면 해당 `mcp_tool` 훅이 실행됩니다. 세션이 시작 시 필요한 모든 항목에는 대신 `SessionStart`에서 `type: "command"` 훅을 사용하십시오.

631 615

632<h4 id="prompt-and-agent-hook-fields">616<h4 id="prompt-and-agent-hook-fields">

633 프롬프트 및 에이전트 hook 필드617 프롬프트 및 에이전트 hook 필드

638| 필드 | 필수 | 설명 |622| 필드 | 필수 | 설명 |

639| :- | :- | :- |623| :- | :- | :- |

640| `prompt` | 예 | 모델로 보낼 프롬프트 텍스트. hook 입력 JSON에 대한 자리 표시자로 `$ARGUMENTS`를 사용합니다. 리터럴 텍스트를 포함하려면 백슬래시로 이스케이프합니다: `\$1.00`은 `$1.00`으로 렌더링됩니다. |624| `prompt` | 예 | 모델로 보낼 프롬프트 텍스트. hook 입력 JSON에 대한 자리 표시자로 `$ARGUMENTS`를 사용합니다. 리터럴 텍스트를 포함하려면 백슬래시로 이스케이프합니다: `\$1.00`은 `$1.00`으로 렌더링됩니다. |

641| `model` | 아니요 | 평가에 사용할 모델. 기본값은 빠른 모델입니다. |625| `model` | 아니요 | 평가에 사용할 모델. 기본값은 Claude Code가 [백그라운드 기능](/docs/ko/costs#background-token-usage)에 사용하는 모델입니다. |

642 626

643<h3 id="reference-scripts-by-path">627<h3 id="reference-scripts-by-path">

644 경로별 스크립트 참조628 경로별 스크립트 참조

647프로젝트 또는 플러그인 루트를 기준으로 hook 스크립트를 참조하려면 이 자리 표시자를 사용합니다. hook이 실행될 때의 작업 디렉토리와 관계없이:631프로젝트 또는 플러그인 루트를 기준으로 hook 스크립트를 참조하려면 이 자리 표시자를 사용합니다. hook이 실행될 때의 작업 디렉토리와 관계없이:

648 632

649* `${CLAUDE_PROJECT_DIR}`: 세션이 시작된 프로젝트 루트. Claude Code는 또한 [stdio MCP 서버](/docs/ko/mcp#option-3-add-a-local-stdio-server) 및 플러그인 LSP 서버의 환경에서 이 변수를 설정합니다.633* `${CLAUDE_PROJECT_DIR}`: 세션이 시작된 프로젝트 루트. Claude Code는 또한 [stdio MCP 서버](/docs/ko/mcp#option-3-add-a-local-stdio-server) 및 플러그인 LSP 서버의 환경에서 이 변수를 설정합니다.

650* `${CLAUDE_PLUGIN_ROOT}`: [플러그인](/docs/ko/plugins)과 함께 번들된 스크립트의 플러그인 설치 디렉토리. 업데이트 전반에 걸쳐 경로가 어떻게 작동하는지에 대해서는 [플러그인 환경 변수](/docs/ko/plugins-reference#environment-variables)를 참조하십시오.634* `${CLAUDE_PLUGIN_ROOT}`: [플러그인](/docs/ko/plugins/overview)과 함께 번들된 스크립트의 플러그인 설치 디렉터리. 업데이트 전반에 걸쳐 경로가 어떻게 작동하는지에 대해서는 [플러그인 환경 변수](/docs/ko/plugins/manifest-reference#environment-variables)를 참조하십시오.

651* `${CLAUDE_PLUGIN_DATA}`: 플러그인 업데이트를 통해 유지되어야 하는 종속성 및 상태의 플러그인 [영구 데이터 디렉토리](/docs/ko/plugins-reference#persistent-data-directory).635* `${CLAUDE_PLUGIN_DATA}`: 플러그인 업데이트 후에도 유지되어야 하는 의존성 및 상태를 위한 플러그인의 [영구 데이터 디렉터리](/docs/ko/plugins/components#path-variables-and-persistent-data).

652 636

653<Note>637<Note>

654 **Worktree는 다릅니다.** Claude가 세션 중에 [worktree](/docs/ko/worktrees)에 들어가면 Claude Code는 `${CLAUDE_PROJECT_DIR}`을 원래 위치에 유지하고 worktree 경로를 다른 방식으로 hook에 전달합니다:638 **Worktree는 다릅니다.** Claude가 세션 중에 [worktree](/docs/ko/worktrees)에 들어가면 Claude Code는 `${CLAUDE_PROJECT_DIR}`을 원래 위치에 유지하고 worktree 경로를 다른 방식으로 hook에 전달합니다:

709 }693 }

710 ```694 ```

711 695

712 플러그인 hook 생성에 대한 자세한 내용은 [플러그인 구성 요소 참조](/docs/ko/plugins-reference#hooks)를 참조하십시오.696 플러그인 훅 생성에 대한 자세한 내용은 [플러그인 구성 요소 참조](/docs/ko/plugins/components#hooks)를 참조하십시오.

713 </Tab>697 </Tab>

714</Tabs>698</Tabs>

715 699

779 763

780macOS 및 Linux에서 명령 hook은 제어 터미널 없이 자신의 세션에서 실행됩니다. hook 프로세스 및 모든 자식 프로세스는 `/dev/tty`를 열거나 Claude Code 인터페이스에 직접 이스케이프 시퀀스를 보낼 수 없습니다. Windows에는 `/dev/tty`가 없습니다.764macOS 및 Linux에서 명령 hook은 제어 터미널 없이 자신의 세션에서 실행됩니다. hook 프로세스 및 모든 자식 프로세스는 `/dev/tty`를 열거나 Claude Code 인터페이스에 직접 이스케이프 시퀀스를 보낼 수 없습니다. Windows에는 `/dev/tty`가 없습니다.

781 765

782모든 플랫폼에서 사용자에게 메시지를 표시하려면 JSON 출력에서 [`systemMessage`](#json-output)를 반환합니다. 일부 이벤트는 이를 버리거나 다른 곳에 전달하며, 각 [이벤트의 섹션](#hook-events)에서 그렇게 말합니다. 데스크톱 알림을 트리거하거나 창 제목을 설정하거나 벨을 울리려면 대신 [`terminalSequence`](#emit-terminal-notifications)를 반환합니다.766모든 플랫폼에서 사용자에게 메시지를 표시하려면 JSON 출력에서 [`systemMessage`](#json-output)를 반환합니다. 일부 이벤트는 이를 버리거나 다른 곳에 전달하며, 각 [이벤트의 섹션](#hook-events)에서 이를 설명합니다. 데스크톱 알림을 트리거하거나 창 제목을 설정하거나 벨을 울리려면 대신 [`terminalSequence`](#emit-terminal-notifications)를 반환합니다.

783 767

784<h3 id="common-input-fields">768<h3 id="common-input-fields">

785 공통 입력 필드769 공통 입력 필드

790| 필드 | 설명 |774| 필드 | 설명 |

791| :- | :- |775| :- | :- |

793| `prompt_id` | 현재 처리 중인 사용자 프롬프트를 식별하는 UUID입니다. [OpenTelemetry 이벤트의 `prompt.id` 속성](/docs/ko/monitoring-usage#event-correlation-attributes)과 일치하므로 hook 출력을 단일 프롬프트의 원격 분석과 연관시킬 수 있습니다. 첫 번째 사용자 입력까지 없습니다. Claude Code v2.1.196 이상 필요 |777| `prompt_id` | 현재 처리 중인 사용자 프롬프트를 식별하는 UUID입니다. [OpenTelemetry 이벤트의 `prompt.id` 속성](/docs/ko/monitoring-usage#event-correlation-attributes)과 일치하므로 hook 출력을 단일 프롬프트의 텔레메트리와 연관시킬 수 있습니다. 첫 번째 사용자 입력 전까지는 없습니다. Claude Code v2.1.196 이상 필요 |

794| `transcript_path` | 대화 JSON 경로입니다. 트랜스크립트 파일은 비동기적으로 기록되며 메모리 내 대화보다 뒤떨어질 수 있으므로 hook이 발생할 때 현재 턴의 가장 최근 메시지를 아직 포함하지 않을 수 있습니다. 현재 턴의 최종 어시스턴트 텍스트가 필요한 hook은 트랜스크립트를 읽는 대신 [Stop](#stop) 및 [SubagentStop](#subagentstop)에서 `last_assistant_message`를 사용해야 합니다 |778| `transcript_path` | 대화 JSON 경로입니다. 트랜스크립트 파일은 비동기적으로 기록되며 메모리 내 대화보다 뒤처질 수 있으므로 hook이 발생할 때 현재 턴의 가장 최근 메시지를 아직 포함하지 않을 수 있습니다. 현재 턴의 최종 어시스턴트 텍스트가 필요한 hook은 트랜스크립트를 읽는 대신 [Stop](#stop) 및 [SubagentStop](#subagentstop)에서 `last_assistant_message`를 사용해야 합니다 |

795| `cwd` | hook이 호출될 때의 현재 작업 디렉토리 |779| `cwd` | hook이 호출될 때의 현재 작업 디렉터리 |

796| `scratchpad_dir` | 세션의 scratchpad 디렉토리 경로이며, Claude가 임시 작업 파일을 보관합니다. 세션에 scratchpad가 없거나 임시 디렉토리를 사용할 수 없을 때 없습니다. Claude Code v2.1.257 이상 필요 |780| `scratchpad_dir` | 세션의 [scratchpad 디렉터리](/docs/ko/claude-directory#session-scratchpad-directory) 경로이며, Claude가 임시 작업 파일을 보관하는 곳입니다. 세션에 scratchpad가 없거나 임시 디렉터리를 사용할 수 없을 때는 없습니다. Claude Code v2.1.257 이상 필요 |

797| `permission_mode` | 현재 [권한 모드](/docs/ko/permissions#permission-modes): `"default"`, `"plan"`, `"acceptEdits"`, `"auto"`, `"dontAsk"` 또는 `"bypassPermissions"`. **수동**으로 표시된 모드는 `"default"`로 도착하며 `"manual"`로 도착하지 않으므로 `"default"`와 일치하는 스크립트는 계속 작동합니다. 모든 이벤트가 이 필드를 받는 것은 아닙니다. 각 [hook 이벤트](#hook-events) 섹션의 JSON 예제를 확인하세요 |781| `permission_mode` | 현재 [권한 모드](/docs/ko/permissions#permission-modes): `"default"`, `"plan"`, `"acceptEdits"`, `"auto"`, `"dontAsk"` 또는 `"bypassPermissions"`. **수동**으로 표시된 모드는 `"default"`로 도착하며 `"manual"`로 도착하지 않으므로 `"default"`와 일치하는 스크립트는 계속 작동합니다. 모든 이벤트가 이 필드를 받는 것은 아닙니다. 각 [hook 이벤트](#hook-events) 섹션의 JSON 예제를 확인하세요 |

798| `effort` | [노력 수준](/docs/ko/model-config#adjust-effort-level)을 보유하는 `level` 필드가 있는 객체: `"low"`, `"medium"`, `"high"`, `"xhigh"` 또는 `"max"`. 설정한 수준을 활성 모델이 지원하지 않으면 `level`은 Claude Code가 대신 실행한 수준을 보고합니다. [노력 수준 조정](/docs/ko/model-config#adjust-effort-level)에서 수준을 선택하는 방법을 설명합니다. Ultracode는 별개의 수준이 아니며 `"xhigh"`로 보고됩니다. 객체는 [상태 줄](/docs/ko/statusline#available-data) `effort` 필드와 일치합니다. `PreToolUse`, `PostToolUse`, `Stop`, `SubagentStop`과 같은 도구 사용 컨텍스트 내에서 발생하는 이벤트에 대해 현재 모델이 노력 매개변수를 지원할 때 존재합니다. 수준은 `$CLAUDE_EFFORT` 환경 변수로 hook 명령 및 Bash 도구에서도 사용 가능합니다. |782| `effort` | hook이 실행될 때 적용 중인 [effort 수준](/docs/ko/model-config#adjust-effort-level)을 담은 `level` 필드가 있는 객체: `"low"`, `"medium"`, `"high"`, `"xhigh"` 또는 `"max"`. 활성 모델이 지원하지 않는 수준을 설정하면 `level`은 Claude Code가 대신 실행한 수준을 보고합니다. [effort 수준 조정](/docs/ko/model-config#adjust-effort-level)에서 해당 수준을 선택하는 방법을 설명합니다. 이 객체는 [상태줄](/docs/ko/statusline#available-data) `effort` 필드와 일치합니다. `PreToolUse`, `PostToolUse`, `Stop`, `SubagentStop`과 같이 도구 사용 컨텍스트 내에서 발생하는 이벤트에 대해 현재 모델이 effort 매개변수를 지원할 때 존재합니다. 이 수준은 `$CLAUDE_EFFORT` 환경 변수로 hook 명령 및 Bash 도구에서도 사용할 수 있습니다. |

800 784

801`--agent`로 실행하거나 subagent 내부에서 실행할 때 두 개의 추가 필드가 포함됩니다:785`--agent`로 실행하거나 서브에이전트 내부에서 실행할 때 두 개의 추가 필드가 포함됩니다:

802 786

803| 필드 | 설명 |787| 필드 | 설명 |

804| :- | :- |788| :- | :- |

806| `agent_type` | 에이전트 이름 (예: `"Explore"` 또는 `"security-reviewer"`). 세션이 `--agent`를 사용하거나 hook이 subagent 내부에서 발생할 때 존재합니다. subagent의 경우 subagent의 유형이 세션의 `--agent` 값보다 우선합니다. [SubagentStart](#subagentstart)에서 사용자 정의 및 플러그인 subagent가 보고하는 값과 플러그인 범위 이름에 대해 matcher를 작성하는 방법을 참조하세요. |790| `agent_type` | 에이전트 이름 (예: `"Explore"` 또는 `"security-reviewer"`). 세션이 `--agent`를 사용하거나 hook이 서브에이전트 내부에서 발생할 때 존재합니다. 서브에이전트의 경우 서브에이전트의 유형이 세션의 `--agent` 값보다 우선합니다. 사용자 정의 및 플러그인 서브에이전트가 보고하는 값과 플러그인 범위 이름에 대해 matcher를 작성하는 방법은 [SubagentStart](#subagentstart)를 참조하세요. |

807 791

808[`SessionStart`](#sessionstart) hook만 `model` 필드를 받을 수 있으며, Claude Code가 항상 포함하지는 않습니다. [`PreModelSwitch`](#premodelswitch) 및 [`PostModelSwitch`](#postmodelswitch) hook은 대신 `from_model` 및 `to_model`을 받으므로 PostModelSwitch hook을 사용하여 세션 중에 모델이 변경될 때 모델을 따릅니다.792[`SessionStart`](#sessionstart) hook만 `model` 필드를 받을 수 있으며, Claude Code가 항상 포함하지는 않습니다. [`PreModelSwitch`](#premodelswitch) 및 [`PostModelSwitch`](#postmodelswitch) hook은 대신 `from_model` 및 `to_model`을 받으므로, 세션 중에 모델이 변경되는 것을 추적하려면 PostModelSwitch hook을 사용합니다.

809 793

810`$CLAUDE_MODEL` 환경 변수는 없습니다. hook은 셸에서 설정한 경우 `$ANTHROPIC_MODEL`을 읽을 수 있지만, 세션 중에 `/model`로 모델을 전환할 때 해당 값은 변경되지 않습니다.794`$CLAUDE_MODEL` 환경 변수는 없습니다. hook은 셸에서 설정한 경우 `$ANTHROPIC_MODEL`을 읽을 수 있지만, 세션 중에 `/model`로 모델을 전환해도 해당 값은 변경되지 않습니다.

811 795

812hook 프로세스는 부모 환경을 상속하며, [`CLAUDE_CODE_SUBPROCESS_ENV_SCRUB`](/docs/ko/env-vars#variables)가 `1`로 설정된 경우 Claude Code가 [모든 서브프로세스에서 제거하는](/docs/ko/monitoring-usage#administrator-configuration) `OTEL_*` 내보내기 변수와 제거하는 변수를 제외합니다.796hook 프로세스는 부모 환경을 상속합니다. 단, Claude Code가 [생성하는 모든 서브프로세스에서 제거하는](/docs/ko/monitoring-usage#administrator-configuration) `OTEL_*` 내보내기 변수와, [`CLAUDE_CODE_SUBPROCESS_ENV_SCRUB`](/docs/ko/env-vars#variables)가 `1`로 설정된 경우 제거되는 변수는 제외됩니다.

813 797

814예를 들어 Bash 명령에 대한 `PreToolUse` hook은 stdin에서 다음을 받습니다:798예를 들어 Bash 명령에 대한 `PreToolUse` hook은 stdin에서 다음을 받습니다:

815 799

833}817}

834```818```

835 819

836`tool_name`, `tool_input`, `tool_use_id` 필드는 이벤트 특정입니다. 각 [hook 이벤트](#hook-events) 섹션에서는 해당 이벤트의 추가 필드를 문서화합니다.820`tool_name`, `tool_input`, `tool_use_id` 필드는 이벤트 특정 필드입니다. 각 [hook 이벤트](#hook-events) 섹션에서는 해당 이벤트의 추가 필드를 문서화합니다.

837 821

838<h3 id="exit-code-output">822<h3 id="exit-code-output">

839 종료 코드 출력823 종료 코드 출력

840</h3>824</h3>

841 825

842hook 명령의 종료 코드는 Claude Code에 작업을 진행할지, 차단할지 또는 무시할지를 알려줍니다. 종료 코드는 단독으로 작동하지 않습니다. Claude Code는 모든 종료 코드에서 [JSON 출력 필드](#json-output)를 stdout에서 읽으며, 표준 결정 모델을 사용하는 이벤트의 경우 스키마 검증을 통과하는 구문 분석된 객체가 코드와 함께 적용됩니다. Exit 2의 차단은 JSON이 재정의할 수 없는 유일한 결과입니다.826hook 명령의 종료 코드는 Claude Code에 작업을 진행할지, 차단할지 또는 무시할지를 알려줍니다. 종료 코드는 단독으로 작동하지 않습니다. Claude Code는 0뿐만 아니라 모든 종료 코드에서 stdout의 [JSON 출력 필드](#json-output)를 읽으며, 표준 결정 모델을 사용하는 이벤트의 경우 스키마 검증을 통과하는 구문 분석된 객체가 코드와 함께 적용됩니다. Exit 2의 차단은 JSON이 재정의할 수 없는 유일한 결과입니다.

843 827

844두 개의 표가 이벤트별 예외를 소유합니다: [이벤트별 종료 코드 2 동작](#exit-code-2-behavior-per-event)은 각 이벤트에 대해 종료 코드가 수행하는 작업을 말하고, [결정 제어](#decision-control)는 각 이벤트가 수행하는 결정 필드를 말합니다. `systemMessage`와 같은 범용 필드는 대부분의 이벤트에서 작동하며 [JSON 출력](#json-output) 표에 나열됩니다.828두 개의 표가 이벤트별 예외를 다룹니다: [이벤트별 종료 코드 2 동작](#exit-code-2-behavior-per-event)은 각 이벤트에 대해 종료 코드가 수행하는 작업을 설명하고, [결정 제어](#decision-control)는 각 이벤트가 적용하는 결정 필드를 설명합니다. `systemMessage`와 같은 범용 필드는 대부분의 이벤트에서 작동하며 [JSON 출력](#json-output) 표에 나열됩니다.

845 829

846<h4 id="exit-code-0">830<h4 id="exit-code-0">

847 종료 코드 0831 종료 코드 0

848</h4>832</h4>

849 833

850종료 0은 성공을 의미하며, JSON을 인쇄하여 구조화된 제어를 할 때 의도된 종료 코드입니다.834종료 0은 성공을 의미하며, 구조화된 제어를 위해 JSON을 출력할 때 의도된 종료 코드입니다.

851 835

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

853 837

854Claude Code가 stdout을 [JSON 출력](#json-output) 또는 일반 텍스트로 읽는지 여부는 주변 공백을 무시하고 시작 및 종료 방식에 따라 달라집니다:838Claude Code가 stdout을 [JSON 출력](#json-output)으로 읽는지 일반 텍스트로 읽는지는 주변 공백을 무시하고 시작 및 끝 문자에 따라 달라집니다:

855 839

856* **`{`로 시작하고 `}`로 끝남**: Claude Code는 이를 JSON으로 구문 분석합니다. 출력이 각각 자체적으로 JSON으로 구문 분석되는 두 줄 이상이고 필드를 설정하는 [JSON 출력](#json-output) 객체가 없는 경우 Claude Code는 전체 출력을 일반 텍스트로 취급합니다. 이러한 줄 중 하나가 필드를 설정하면 전체 출력은 아래에 설명된 구문 분석 실패입니다.840* **`{`로 시작하고 `}`로 끝남**: Claude Code는 이를 JSON으로 구문 분석합니다. 출력이 각각 자체적으로 JSON으로 구문 분석되는 두 줄 이상이고 필드를 설정하는 [JSON 출력](#json-output) 객체인 줄이 없는 경우 Claude Code는 전체 출력을 일반 텍스트로 취급합니다. 이러한 줄 중 하나가 필드를 설정하면 전체 출력은 아래에 설명된 구문 분석 실패가 됩니다.

857* **`{`로 시작하지만 `}`로 끝나지 않음**: Claude Code는 이를 일반 텍스트로 취급합니다.841* **`{`로 시작하지만 `}`로 끝나지 않음**: Claude Code는 이를 일반 텍스트로 취급합니다.

858* **다른 것으로 시작**: Claude Code는 이를 일반 텍스트, JSON 배열 또는 포함된 따옴표 JSON 문자열로 취급합니다.842* **다른 것으로 시작**: Claude Code는 JSON 배열이나 따옴표로 묶인 JSON 문자열을 포함하여 이를 일반 텍스트로 취급합니다.

859 843

860표준 결정 모델을 사용하는 이벤트의 경우 스키마 검증에 실패하는 구문 분석된 객체로 종료 0은 차단하지 않는 오류입니다: 작업이 진행되고 트랜스크립트는 검증 메시지와 함께 `<hook name> hook error` 알림을 표시합니다. 2 이외의 다른 종료 코드에서도 동일한 일이 발생하는 반면 [종료 2는 여전히 차단합니다](#exit-code-2).844표준 결정 모델을 사용하는 이벤트의 경우 스키마 검증에 실패하는 구문 분석된 객체와 함께 종료 0으로 나가면 차단하지 않는 오류입니다: 작업이 진행되고 트랜스크립트는 검증 메시지와 함께 `<hook name> hook error` 알림을 표시합니다. 2 이외의 다른 종료 코드에서도 동일한 일이 발생하며, [종료 2는 여전히 차단합니다](#exit-code-2).

861 845

862표준 결정 모델을 사용하는 이벤트의 경우 Claude Code가 stdout을 JSON으로 구문 분석하려고 시도하고 실패하면 2 이외의 모든 종료 코드에서 차단하지 않는 오류를 보고합니다. 트랜스크립트는 구문 분석 메시지와 함께 `<hook name> hook error` 알림을 표시합니다. 일반 텍스트 stdout을 컨텍스트로 추가하는 이벤트에서 Claude Code는 텍스트를 추가하지 않습니다. v2.1.248 이전에 Claude Code는 해당 stdout을 일반 텍스트로 취급했습니다.846표준 결정 모델을 사용하는 이벤트의 경우 Claude Code가 stdout을 JSON으로 구문 분석하려고 시도하고 실패하면 2 이외의 모든 종료 코드에서 차단하지 않는 오류를 보고합니다. 트랜스크립트는 구문 분석 메시지와 함께 `<hook name> hook error` 알림을 표시합니다. 일반 텍스트 stdout을 컨텍스트로 추가하는 이벤트에서 Claude Code는 텍스트를 추가하지 않습니다. v2.1.248 이전에는 Claude Code가 해당 stdout을 일반 텍스트로 취급했습니다.

863 847

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

865 849

866<h4 id="exit-code-2">850<h4 id="exit-code-2">

867 종료 코드 2851 종료 코드 2

868</h4>852</h4>

869 853

870종료 2는 차단 오류를 의미합니다. [차단할 수 있는 이벤트](#exit-code-2-behavior-per-event)에서 종료 2는 JSON을 인쇄하는지 여부와 관계없이 차단합니다: JSON `permissionDecision`의 `"allow"`도 이를 재정의할 수 없습니다. Claude Code는 여전히 stdout에서 유효한 [JSON 출력](#json-output)을 읽습니다. `Elicitation` 및 `ElicitationResult`에서 종료 2 hook의 `hookSpecificOutput`은 무시됩니다.854종료 2는 차단 오류를 의미합니다. [차단할 수 있는 이벤트](#exit-code-2-behavior-per-event)에서 종료 2는 JSON을 출력하는지 여부와 관계없이 차단합니다: JSON `permissionDecision`의 `"allow"`도 이를 재정의할 수 없습니다. Claude Code는 여전히 stdout에서 유효한 [JSON 출력](#json-output)을 읽습니다. `Elicitation` 및 `ElicitationResult`에서는 종료 2 hook의 `hookSpecificOutput`이 무시됩니다.

871 855

872차단 메시지는 차단 결정을 하는 JSON의 이유이며, 그렇지 않으면 stderr 텍스트입니다. 차단이 수행하는 작업은 이벤트에 따라 다릅니다: `PreToolUse`는 도구 호출을 차단하고 `UserPromptSubmit`은 프롬프트를 거부합니다. [이벤트별 종료 코드 2 동작](#exit-code-2-behavior-per-event)은 모든 이벤트의 효과를 나열하며, 각 이벤트의 섹션은 메시지가 어디로 가는지 말합니다.856차단 메시지는 JSON이 차단 결정을 하는 경우 해당 결정의 이유이며, 그렇지 않으면 stderr 텍스트입니다. 차단이 수행하는 작업은 이벤트에 따라 다릅니다: `PreToolUse`는 도구 호출을 차단하고 `UserPromptSubmit`은 프롬프트를 거부하는 식입니다. [이벤트별 종료 코드 2 동작](#exit-code-2-behavior-per-event)은 모든 이벤트의 효과를 나열하며, 각 이벤트의 섹션에서 메시지가 어디로 가는지 설명합니다.

873 857

874[JSON 출력](#json-output) 스키마 검증에 실패하는 JSON을 인쇄하면서 종료 2로 나가는 hook은 여전히 차단합니다: Claude Code는 stderr을 차단 이유로 사용하고 검증 실패를 디버그 로그에 기록합니다. v2.1.214 이전에 Claude Code는 해당 조합을 차단하지 않는 오류로 취급했으며 작업이 진행되었습니다.858[JSON 출력](#json-output) 스키마 검증에 실패하는 JSON을 출력하면서 종료 2로 나가는 hook은 여전히 차단합니다: Claude Code는 stderr을 차단 이유로 사용하고 검증 실패를 디버그 로그에 기록합니다. v2.1.214 이전에는 Claude Code가 해당 조합을 차단하지 않는 오류로 취급하여 작업이 진행되었습니다.

875 859

876이 스크립트는 `rm` 명령을 차단하고 다른 모든 명령을 일반 권한 흐름으로 남깁니다:860이 스크립트는 종료 2로 `rm` 명령을 차단하고 다른 모든 명령은 일반 권한 흐름에 맡깁니다:

877 861

878```bash theme={null}862```bash theme={null}

879#!/bin/bash863#!/bin/bash

880# stdin에서 JSON 입력을 읽고 명령을 확인합니다864# Reads JSON input from stdin, checks the command

881input=$(cat)865input=$(cat)

882command=$(jq -r '.tool_input.command' <<<"$input")866command=$(jq -r '.tool_input.command' <<<"$input")

883 867

884if [[ "$command" == rm* ]]; then868if [[ "$command" == rm* ]]; then

885 echo "Blocked: rm commands are not allowed" >&2869 echo "Blocked: rm commands are not allowed" >&2

886 exit 2 # 차단 오류: 도구 호출이 방지됨870 exit 2 # Blocking error: tool call is prevented

887fi871fi

888 872

889exit 0 # 결정 없음: 일반 권한 흐름이 적용됨873exit 0 # No decision: the normal permission flow applies

890```874```

891 875

892<h4 id="other-exit-codes">876<h4 id="other-exit-codes">

893 다른 종료 코드877 다른 종료 코드

894</h4>878</h4>

895 879

896다른 종료 코드는 대부분의 hook 이벤트에 대해 자체적으로 차단하지 않습니다. 발생하는 일은 stdout에 따라 다릅니다:880다른 종료 코드는 대부분의 hook 이벤트에서 그 자체로는 차단하지 않습니다. 발생하는 일은 stdout에 따라 다릅니다:

897 881

898* 스키마 검증을 통과하는 구문 분석된 객체를 사용하면 표준 결정 모델을 사용하는 이벤트의 경우 Claude Code는 종료 코드를 무시하고 JSON만 결과를 결정합니다:882* 스키마 검증을 통과하는 구문 분석된 객체가 있으면, 표준 결정 모델을 사용하는 이벤트의 경우 Claude Code는 종료 코드를 무시하고 JSON만으로 결과를 결정합니다:

899 * 이벤트가 지원하는 각 필드는 `permissionDecision`, `additionalContext`, `updatedInput`, `systemMessage`를 포함하여 수행되며 hook은 오류로 보고되지 않습니다.883 * 이벤트가 지원하는 각 필드는 `permissionDecision`, `additionalContext`, `updatedInput`, `systemMessage`를 포함하여 적용되며 hook은 오류로 보고되지 않습니다.

900 * [결정 제어](#decision-control)는 이벤트별 결정 필드를 나열합니다. `systemMessage`와 같은 범용 필드는 [JSON 출력](#json-output) 표를 따릅니다.884 * [결정 제어](#decision-control)는 이벤트별 결정 필드를 나열합니다. `systemMessage`와 같은 범용 필드는 [JSON 출력](#json-output) 표를 따릅니다.

901* 스키마 검증에 실패하는 구문 분석된 객체를 사용하면 표준 결정 모델을 사용하는 이벤트의 경우 [종료 0](#exit-code-0)과 동일한 차단하지 않는 오류입니다: 작업이 진행되고 `<hook name> hook error` 알림은 검증 메시지를 전달합니다.885* 스키마 검증에 실패하는 구문 분석된 객체가 있으면, 표준 결정 모델을 사용하는 이벤트의 경우 [종료 0](#exit-code-0)과 동일한 차단하지 않는 오류입니다: 작업이 진행되고 `<hook name> hook error` 알림에 검증 메시지가 표시됩니다.

902* Claude Code가 [JSON으로 구문 분석하려고 시도하고 실패](#exit-code-0)하는 stdout을 사용하면 Claude Code는 표준 결정 모델을 사용하는 이벤트에 대해 종료 0과 동일한 차단하지 않는 오류를 보고합니다. 작업이 진행되고 알림은 구문 분석 메시지를 전달합니다.886* Claude Code가 [JSON으로 구문 분석하려고 시도하고 실패](#exit-code-0)하는 stdout이 있으면, 표준 결정 모델을 사용하는 이벤트에 대해 Claude Code는 종료 0과 동일한 차단하지 않는 오류를 보고합니다. 작업이 진행되고 알림에 구문 분석 메시지가 표시됩니다.

903* Claude Code가 [일반 텍스트로 취급](#exit-code-0)하는 stdout을 사용하거나 빈 stdout을 사용하면 대부분의 hook 이벤트에 대해 차단하지 않는 오류입니다: 작업이 진행되고 트랜스크립트는 `<hook name> hook error` 알림을 표시한 후 stderr의 첫 번째 줄을 `Failed with non-blocking status code:`로 접두사를 붙여 표시합니다. 전체 stderr을 캡처하려면 [디버그 로깅](#debug-hooks)을 활성화합니다.887* Claude Code가 [일반 텍스트로 취급](#exit-code-0)하는 stdout이 있거나 stdout이 비어 있으면 대부분의 hook 이벤트에서 차단하지 않는 오류입니다: 작업이 진행되고 트랜스크립트는 `<hook name> hook error` 알림과 함께 `Failed with non-blocking status code:` 접두사가 붙은 stderr의 첫 번째 줄을 표시합니다. 전체 stderr을 캡처하려면 [디버그 로깅](#debug-hooks)을 활성화합니다.

904 888

905표준 결정 모델 외부의 이벤트는 [이벤트별 표](#exit-code-2-behavior-per-event)에서 자신의 행을 유지합니다: `WorktreeCreate`는 JSON이 무엇을 말하든 0이 아닌 종료 코드에서 생성을 실패하고, `StopFailure`와 같이 hook 출력을 완전히 버리는 이벤트는 모든 종료 코드에서 JSON을 무시하며, `terminalSequence`와 같은 부작용 필드는 여전히 발생합니다.889표준 결정 모델 외부의 이벤트는 [이벤트별 표](#exit-code-2-behavior-per-event)의 자체 행을 따릅니다: `WorktreeCreate`는 JSON 내용과 관계없이 0이 아닌 종료 코드에서 생성을 실패시키고, `StopFailure`와 같이 hook 출력을 완전히 버리는 이벤트는 모든 종료 코드에서 JSON을 무시합니다. 단, `terminalSequence`와 같은 부수 효과 필드는 여전히 동작합니다.

906 890

907시작할 수 없는 hook은 동일한 차단하지 않는 버킷에 도착합니다. 스크립트 경로가 존재하지 않거나 실행 가능하지 않으면 셸은 127과 같은 코드로 종료되고 인터프리터의 메시지와 함께 동일한 알림을 봅니다. 예를 들어 `Failed with non-blocking status code: /bin/sh: /path/to/hook.sh: No such file or directory`. 대부분의 hook 이벤트에서 작업이 진행됩니다. 정책 hook을 설정할 때 첫 번째 실행에서 이 알림을 확인합니다: `settings.json`의 오타 경로는 게이트를 조용히 비활성화합니다.891시작할 수 없는 hook도 동일한 차단하지 않는 범주에 속합니다. 스크립트 경로가 존재하지 않거나 실행 가능하지 않으면 셸은 127과 같은 코드로 종료되고 인터프리터의 메시지와 함께 동일한 알림이 표시됩니다. 예: `Failed with non-blocking status code: /bin/sh: /path/to/hook.sh: No such file or directory`. 대부분의 hook 이벤트에서 작업이 진행됩니다. 정책 hook을 설정할 때 첫 번째 실행에서 이 알림을 확인하세요: `settings.json`의 경로에 오타가 있으면 게이트가 조용히 비활성화됩니다.

908 892

909<Warning>893<Warning>

910 대부분의 hook 이벤트에서 종료 코드 2는 코드만으로 차단하는 유일한 종료 코드입니다. stdout에 유효한 JSON이 없으면 Claude Code는 종료 코드 1을 차단하지 않는 오류로 취급하고 작업을 진행합니다. 1이 기존 Unix 실패 코드이지만 말입니다. hook이 정책을 적용하려면 `exit 2`를 사용합니다. worktree 이벤트는 다릅니다: `WorktreeCreate`의 0이 아닌 종료 코드는 worktree 생성을 중단하고, `WorktreeRemove`의 0이 아닌 종료 코드는 디렉토리가 여전히 존재하면 worktree 제거를 실패하게 합니다.894 대부분의 hook 이벤트에서 종료 코드 2는 코드만으로 차단하는 유일한 종료 코드입니다. stdout에 유효한 JSON이 없으면 Claude Code는 1이 관례적인 Unix 실패 코드임에도 불구하고 종료 코드 1을 차단하지 않는 오류로 취급하고 작업을 진행합니다. hook이 정책을 적용하기 위한 것이라면 `exit 2`를 사용합니다. worktree 이벤트는 다릅니다: `WorktreeCreate`의 0이 아닌 종료 코드는 worktree 생성을 중단하고, `WorktreeRemove`의 0이 아닌 종료 코드는 이후에도 디렉터리가 여전히 존재하면 worktree 제거를 실패하게 합니다.

911</Warning>895</Warning>

912 896

913<h4 id="timeouts">897<h4 id="timeouts">

914 시간 초과898 타임아웃

915</h4>899</h4>

916 900

917[`async: true`](#run-hooks-in-the-background)로 실행하는 명령 hook을 제외하고 Claude Code는 [`timeout`](#common-fields)에 도달하는 `command`, `http`, `mcp_tool` hook을 취소하고 hook의 출력을 버리므로 대부분의 이벤트에서 시간 초과된 hook은 결정을 렌더링하지 않습니다.901[`async: true`](#run-hooks-in-the-background)로 실행하는 명령 hook을 제외하고, Claude Code는 [`timeout`](#common-fields)에 도달한 `command`, `http`, `mcp_tool` hook을 취소하고 hook의 출력을 버리므로 대부분의 이벤트에서 시간 초과된 hook은 결정을 내리지 않습니다.

918 902

919[`PreModelSwitch`](#premodelswitch)에서 시간 초과에서 취소된 hook은 모델 전환을 차단합니다. `PreToolUse`에서 두 hook 패밀리는 다릅니다:903[`PreModelSwitch`](#premodelswitch)에서는 타임아웃으로 취소된 hook이 모델 전환을 차단합니다. `PreToolUse`에서는 두 hook 유형이 다르게 동작합니다:

920 904

921* 시간 초과된 `command`, `http`, `mcp_tool` hook은 도구 호출을 차단하지 않습니다. 호출은 일반 [권한 흐름](/docs/ko/permissions)을 통해 계속되므로 정지된 hook이 게이트로 작동하기를 기대하지 마세요.905* 시간 초과된 `command`, `http`, `mcp_tool` hook은 도구 호출을 차단하지 않습니다. 호출은 일반 [권한 흐름](/docs/ko/permissions)을 통해 계속되므로 멈춘 hook이 게이트 역할을 할 것이라고 기대하지 마세요.

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

923 907

924<h4 id="exit-code-2-behavior-per-event">908<h4 id="exit-code-2-behavior-per-event">

925 이벤트별 종료 코드 2 동작909 이벤트별 종료 코드 2 동작

926</h4>910</h4>

927 911

928종료 코드 2는 hook이 "멈춰, 이것을 하지 마"라고 신호하는 방식입니다. 효과는 이벤트에 따라 다릅니다. 일부 이벤트는 차단할 수 있는 작업을 나타내기 때문입니다 (아직 발생하지 않은 도구 호출처럼) 그리고 다른 이벤트는 이미 발생했거나 방지할 수 없는 것을 나타냅니다.912종료 코드 2는 hook이 "멈추고, 이것을 하지 마세요"라고 신호하는 방식입니다. 효과는 이벤트에 따라 다릅니다. 일부 이벤트는 차단할 수 있는 작업(아직 발생하지 않은 도구 호출 등)을 나타내고, 다른 이벤트는 이미 발생했거나 방지할 수 없는 것을 나타내기 때문입니다.

929 913

931| :- | :- | :- |915| :- | :- | :- |

932| `PreToolUse` | 예 | 도구 호출을 차단합니다 |916| `PreToolUse` | 예 | 도구 호출을 차단합니다 |

933| `PermissionRequest` | 아니오 | 종료 코드 2는 이 이벤트에 대해 수행되지 않으며 권한 흐름은 변경되지 않고 진행됩니다. 대신 [`decision` 객체](#permissionrequest-decision-control)를 통해 거부합니다 |917| `PermissionRequest` | 아니오 | 이 이벤트에서는 종료 코드 2가 적용되지 않으며 권한 흐름은 변경 없이 진행됩니다. 대신 [`decision` 객체](#permissionrequest-decision-control)를 통해 거부합니다 |

934| `UserPromptSubmit` | 예 | 프롬프트 처리를 차단하고 프롬프트를 지웁니다 |918| `UserPromptSubmit` | 예 | 프롬프트를 차단하여 Claude에 도달하지 않게 합니다. [차단된 프롬프트가 남기는 것](#what-a-blocked-prompt-leaves-behind)을 참조하세요 |

935| `UserPromptExpansion` | 예 | 확장을 차단합니다 |919| `UserPromptExpansion` | 예 | 확장을 차단합니다 |

936| `Stop` | 예 | Claude가 중지되는 것을 방지하고 대화를 계속합니다 |920| `Stop` | 예 | Claude가 중지되는 것을 방지하고 대화를 계속합니다 |

937| `SubagentStop` | 예 | subagent가 중지되는 것을 방지합니다 |921| `SubagentStop` | 예 | 서브에이전트가 중지되는 것을 방지합니다 |

938| `TeammateIdle` | 예 | 팀원이 유휴 상태가 되는 것을 방지하므로 계속 작업합니다 |922| `TeammateIdle` | 예 | 팀원이 유휴 상태가 되는 것을 방지하므로 계속 작업합니다 |

939| `TaskCreated` | 예 | 작업 생성을 롤백합니다 |923| `TaskCreated` | 예 | 작업 생성을 롤백합니다 |

940| `TaskCompleted` | 예 | 작업이 완료로 표시되는 것을 방지합니다 |924| `TaskCompleted` | 예 | 작업이 완료로 표시되는 것을 방지합니다 |

941| `ConfigChange` | 예 | 구성 변경이 적용되는 것을 차단합니다 (`policy_settings` 제외) |925| `ConfigChange` | 예 | 구성 변경이 적용되는 것을 차단합니다 (`policy_settings` 제외) |

942| `StopFailure` | 아니오 | 출력과 종료 코드는 무시됩니다. `terminalSequence` 제외 |926| `StopFailure` | 아니오 | `terminalSequence`를 제외하고 출력과 종료 코드는 무시됩니다 |

943| `PostToolUse` | 아니오 | Claude에 stderr을 표시합니다. 도구가 이미 실행됨 |927| `PostToolUse` | 아니오 | Claude에 stderr을 표시합니다. 도구는 이미 실행되었습니다 |

944| `PostToolUseFailure` | 아니오 | Claude에 stderr을 표시합니다. 도구가 이미 실패함 |928| `PostToolUseFailure` | 아니오 | Claude에 stderr을 표시합니다. 도구는 이미 실패했습니다 |

945| `PostToolBatch` | 예 | 다음 모델 호출 전에 에이전트 루프를 중지합니다 |929| `PostToolBatch` | 예 | 다음 모델 호출 전에 에이전틱 루프를 중지합니다 |

946| `PermissionDenied` | 아니오 | 종료 코드와 stderr은 무시됩니다. 거부가 이미 발생했기 때문입니다. JSON `hookSpecificOutput.retry: true`를 사용하여 모델이 재시도할 수 있음을 알립니다. Claude Code는 [no-verdict 거부](#permissiondenied-decision-control)에 대해 `retry: true`를 무시합니다 |930| `PermissionDenied` | 아니오 | 거부가 이미 발생했기 때문에 종료 코드와 stderr은 무시됩니다. JSON `hookSpecificOutput.retry: true`를 사용하여 모델에 재시도할 수 있음을 알립니다. Claude Code는 [no-verdict 거부](#permissiondenied-decision-control)에 대해 `retry: true`를 무시합니다 |

947| `Notification` | 아니오 | 종료 코드와 stderr은 무시됩니다 |931| `Notification` | 아니오 | 종료 코드와 stderr은 무시됩니다 |

948| `SubagentStart` | 아니오 | 사용자에게만 stderr을 표시합니다 |932| `SubagentStart` | 아니오 | 사용자에게만 stderr을 표시합니다 |

949| `SessionStart` | 아니오 | 사용자에게만 stderr을 표시합니다 |933| `SessionStart` | 아니오 | 사용자에게만 stderr을 표시합니다 |

950| `Setup` | 아니오 | 종료 코드와 stderr은 무시됩니다 |934| `Setup` | 아니오 | 종료 코드와 stderr은 무시됩니다 |

951| `SessionEnd` | 아니오 | 사용자에게만 stderr을 표시합니다 |935| `SessionEnd` | 아니오 | 사용자에게만 stderr을 표시합니다 |

952| `CwdChanged` | 아니오 | 사용자에게만 stderr을 표시합니다 |936| `CwdChanged` | 아니오 | 사용자에게만 stderr을 표시합니다 |

953| `DirectoryAdded` | 아니오 | stderr은 디버그 로그로 갑니다. 디렉토리가 이미 추가됨 |937| `DirectoryAdded` | 아니오 | stderr은 디버그 로그로 갑니다. 디렉터리는 이미 추가되었습니다 |

954| `FileChanged` | 아니오 | 사용자에게만 stderr을 표시합니다 |938| `FileChanged` | 아니오 | 사용자에게만 stderr을 표시합니다 |

955| `PreCompact` | 예 | 압축을 차단합니다 |939| `PreCompact` | 예 | 압축을 차단합니다 |

956| `PostCompact` | 아니오 | 사용자에게만 stderr을 표시합니다 |940| `PostCompact` | 아니오 | 사용자에게만 stderr을 표시합니다 |

957| `PreModelSwitch` | 예 | 모델 전환을 차단하고 사용자에게 stderr을 표시합니다 |941| `PreModelSwitch` | 예 | 모델 전환을 차단하고 사용자에게 stderr을 표시합니다 |

958| `PostModelSwitch` | 아니오 | 사용자에게만 stderr을 표시합니다. 모델이 이미 전환됨 |942| `PostModelSwitch` | 아니오 | 사용자에게만 stderr을 표시합니다. 모델은 이미 전환되었습니다 |

959| `Elicitation` | 예 | elicitation을 거부합니다 |943| `Elicitation` | 예 | elicitation을 거부합니다 |

960| `ElicitationResult` | 예 | 응답을 차단합니다 (작업이 거부됨) |944| `ElicitationResult` | 예 | 응답을 차단합니다 (action이 decline이 됨) |

961| `WorktreeCreate` | 예 | 0이 아닌 종료 코드로 인해 worktree 생성이 실패합니다 |945| `WorktreeCreate` | 예 | 0이 아닌 종료 코드는 worktree 생성을 실패하게 합니다 |

962| `WorktreeRemove` | 예 | 0이 아닌 종료 코드로 인해 디렉토리가 여전히 존재하면 worktree 제거가 실패합니다. 디렉토리에 발생하는 일은 [WorktreeRemove](#worktreeremove)를 참조하세요 |946| `WorktreeRemove` | 예 | 0이 아닌 종료 코드는 이후에도 디렉터리가 여전히 존재하면 worktree 제거를 실패하게 합니다. 디렉터리에 발생하는 일은 [WorktreeRemove](#worktreeremove)를 참조하세요 |

963| `InstructionsLoaded` | 아니오 | 종료 코드는 무시됩니다 |947| `InstructionsLoaded` | 아니오 | 종료 코드는 무시됩니다 |

964| `MessageDisplay` | 아니오 | 원본 텍스트가 표시됩니다 |948| `MessageDisplay` | 아니오 | 원본 텍스트가 표시됩니다 |

965 949

966`SessionStart`, `SubagentStart`, `PostModelSwitch`의 경우 Claude Code는 종료 코드 2 stderr을 트랜스크립트에 `<hook name> hook error` 알림으로 렌더링하며, [차단하지 않는 오류](#exit-code-output)와 동일한 방식입니다. Claude는 이를 보지 못하며 세션 또는 subagent는 진행됩니다. `SubagentStart`의 경우 알림은 부모 대화가 아닌 subagent의 자신의 트랜스크립트에 나타납니다.950`SessionStart`, `SubagentStart`, `PostModelSwitch`의 경우 Claude Code는 종료 코드 2 stderr을 [차단하지 않는 오류](#exit-code-output)와 동일한 방식으로 트랜스크립트에 `<hook name> hook error` 알림으로 표시합니다. Claude는 이를 보지 못하며 세션 또는 서브에이전트는 계속 진행됩니다. `SubagentStart`의 경우 알림은 부모 대화가 아닌 서브에이전트 자체의 트랜스크립트에 나타납니다.

967 951

968<h3 id="http-response-handling">952<h3 id="http-response-handling">

969 HTTP 응답 처리953 HTTP 응답 처리

970</h3>954</h3>

971 955

972HTTP hook은 종료 코드와 stdout 대신 HTTP 상태 코드와 응답 본문을 사용합니다. 아래의 결과는 대부분의 이벤트에 적용됩니다. [이벤트별 표](#exit-code-2-behavior-per-event)에서 자신의 실패 계약을 가진 이벤트 (예: `WorktreeCreate`)는 실패한 HTTP hook에도 해당 계약을 적용합니다:956HTTP hook은 종료 코드와 stdout 대신 HTTP 상태 코드와 응답 본문을 사용합니다. 아래의 결과는 대부분의 이벤트에 적용됩니다. `WorktreeCreate`와 같이 [이벤트별 표](#exit-code-2-behavior-per-event)에 자체 실패 규칙이 있는 이벤트는 실패한 HTTP hook에도 해당 규칙을 적용합니다:

973 957

974* **2xx 빈 본문**: 성공, 종료 코드 0과 출력 없음과 동등958* **빈 본문의 2xx**: 성공, 출력 없는 종료 코드 0과 동일

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

976* **2xx 일반 텍스트와 같은 다른 본문**: 차단하지 않는 오류, 2xx가 아닌 상태와 동일하게 처리됩니다. Claude Code는 텍스트를 Claude의 컨텍스트에 추가하지 않습니다960* **일반 텍스트 등 그 밖의 본문의 2xx**: 차단하지 않는 오류이며, 2xx가 아닌 상태와 동일하게 처리됩니다. Claude Code는 텍스트를 Claude의 컨텍스트에 추가하지 않습니다

977* **2xx가 아닌 상태**: 차단하지 않는 오류, 실행이 계속됨961* **2xx가 아닌 상태**: 차단하지 않는 오류, 실행이 계속됨

978* **연결 실패**: 차단하지 않는 오류, 실행이 계속됨962* **연결 실패**: 차단하지 않는 오류, 실행이 계속됨

979* **시간 초과**: [시간 초과](#timeouts) 아래에 설명된 대로 hook이 취소됩니다963* **타임아웃**: [타임아웃](#timeouts)에 설명된 대로 hook이 취소됩니다

980 964

981명령 hook과 달리 HTTP hook은 상태 코드만으로 차단 오류를 신호할 수 없습니다. 도구 호출을 차단하거나 권한을 거부하려면 적절한 결정 필드를 포함하는 JSON 본문이 있는 2xx 응답을 반환합니다.965명령 hook과 달리 HTTP hook은 상태 코드만으로 차단 오류를 신호할 수 없습니다. 도구 호출을 차단하거나 권한을 거부하려면 적절한 결정 필드를 포함하는 JSON 본문과 함께 2xx 응답을 반환합니다.

982 966

983<h3 id="json-output">967<h3 id="json-output">

984 JSON 출력968 JSON 출력

985</h3>969</h3>

986 970

987종료 코드는 차단하거나 침묵할 수 있지만 JSON 출력은 더 세밀한 제어를 제공합니다. 종료 코드 2로 차단하는 대신 종료 0으로 JSON 객체를 stdout에 인쇄합니다. Claude Code는 해당 JSON에서 특정 필드를 읽어 차단, 허용 또는 사용자에게 에스컬레이션을 포함한 동작을 제어합니다. [결정 제어](#decision-control)는 차단, 허용 또는 에스컬레이션을 위한 필드를 나열합니다.971종료 코드로는 차단하거나 아무것도 하지 않는 것만 가능하지만, JSON 출력은 더 세밀한 제어를 제공합니다. 종료 코드 2로 차단하는 대신 종료 0으로 나가면서 JSON 객체를 stdout에 출력합니다. Claude Code는 해당 JSON에서 특정 필드를 읽어 동작을 제어하며, 여기에는 차단, 허용 또는 사용자에게 에스컬레이션하기 위한 [결정 제어](#decision-control)가 포함됩니다.

988 972

989<Note>973<Note>

990 hook당 하나의 접근 방식을 선택합니다: 종료 코드만 사용하여 신호하거나 종료 0으로 JSON을 인쇄하여 구조화된 제어를 합니다. 둘을 섞으면 종료 2는 [차단 효과](#exit-code-2-behavior-per-event)를 유지하고 Claude Code는 여전히 JSON 필드를 읽으며, [Elicitation](#elicitation) 예외가 [종료 코드 2](#exit-code-2) 아래에 기록됩니다.974 hook당 하나의 접근 방식을 선택합니다: 종료 코드만 사용하여 신호하거나, 종료 0으로 나가면서 JSON을 출력하여 구조화된 제어를 합니다. 둘을 섞으면 종료 2는 [차단 효과](#exit-code-2-behavior-per-event)를 유지하고 Claude Code는 여전히 JSON 필드를 읽습니다. 단, [종료 코드 2](#exit-code-2)에 설명된 elicitation 예외가 하나 있습니다.

991</Note>975</Note>

992 976

993hook의 stdout은 JSON 객체만 포함해야 합니다. 셸 프로필이 시작 시 텍스트를 인쇄하면 JSON 구문 분석을 방해할 수 있습니다. 문제 해결 가이드의 [Hook JSON이 효과가 없음](/docs/ko/hooks-guide#hook-json-has-no-effect)을 참조하세요.977hook의 stdout은 JSON 객체만 포함해야 합니다. 셸 프로필이 시작 시 텍스트를 출력하면 JSON 구문 분석을 방해할 수 있습니다. 문제 해결 가이드의 [Hook JSON이 효과가 없음](/docs/ko/hooks-guide#hook-json-has-no-effect)을 참조하세요.

994 978

995hook의 `additionalContext`, `systemMessage`, `initialUserMessage` 문자열 및 일반 stdout은 10,000자로 제한됩니다:979hook의 `additionalContext`, `systemMessage`, `initialUserMessage` 문자열 및 일반 stdout은 10,000자로 제한됩니다:

996 980

997* **범위**: Claude Code는 각 문자열을 자체적으로 측정하며, 동일한 이벤트에 대해 여러 hook이 실행되는 경우에도 마찬가지입니다. JSON 출력의 경우 각 필드는 별도로 측정되며, 일반 stdout은 전체적으로 측정됩니다.981* **범위**: Claude Code는 동일한 이벤트에 대해 여러 hook이 실행되는 경우에도 각 문자열을 개별적으로 측정합니다. JSON 출력의 경우 각 필드는 별도로 측정되며, 일반 stdout은 전체를 측정합니다.

998* **제한 초과**: Claude Code는 출력을 세션 디렉토리의 파일에 저장하고 파일 경로와 최대 처음 2,000자의 미리보기로 바꿉니다. 큰 유효한 Bash 결과는 [출력 제한](/docs/ko/tools-reference#output-limits) 아래에 설명된 동일한 방식으로 처리됩니다. 이 Bash 상한과 달리 이 제한에는 이를 높이기 위한 설정이나 환경 변수가 없습니다.982* **제한 초과**: Claude Code는 출력을 세션 디렉터리의 파일에 저장하고 파일 경로와 최대 처음 2,000자의 미리보기로 대체합니다. 큰 유효한 Bash 결과도 [출력 제한](/docs/ko/tools-reference#output-limits)에 설명된 대로 동일한 방식으로 처리됩니다. 해당 Bash 상한과 달리 이 제한에는 이를 높이기 위한 설정이나 환경 변수가 없습니다.

999* **파일 읽기**: Claude Code는 Claude에 파일을 읽도록 요청하지 않으므로 Claude가 항상 봐야 할 항목은 제한 내에 유지하세요.983* **파일 읽기**: Claude Code는 Claude에 파일을 읽도록 요청하지 않으므로 Claude가 항상 봐야 하는 내용은 제한 내에 유지하세요.

1000 984

1001JSON 객체는 세 가지 종류의 필드를 지원합니다:985JSON 객체는 세 가지 종류의 필드를 지원합니다:

1002 986

1003* **`continue`와 같은 범용 필드**는 아래 표에 나열됩니다. 모든 이벤트가 이들을 허용하지만 일부 이벤트는 이들을 버리거나 `systemMessage`를 트랜스크립트 이외의 다른 곳에 전달합니다. 각 이벤트의 섹션에서 그렇게 말합니다. `terminalSequence`는 [터미널 알림 내보내기](#emit-terminal-notifications) 아래에 나열된 예외를 제외하고 이러한 이벤트에서도 작동합니다.987* **`continue`와 같은 범용 필드**는 아래 표에 나열됩니다. 모든 이벤트가 이를 허용하지만 일부 이벤트는 이를 버리거나 `systemMessage`를 트랜스크립트 이외의 다른 곳에 전달합니다. 각 이벤트의 섹션에서 이를 설명합니다. `terminalSequence`는 [터미널 알림 내보내기](#emit-terminal-notifications)에 나열된 예외를 제외하고 이러한 이벤트에서도 작동합니다.

1004* \*\*최상위 `decision` 및 `reason`\*\*은 일부 이벤트에서 차단하거나 피드백을 제공하는 데 사용됩니다.988* \*\*최상위 `decision` 및 `reason`\*\*은 일부 이벤트에서 차단하거나 피드백을 제공하는 데 사용됩니다.

1005* \*\*`hookSpecificOutput`\*\*은 더 풍부한 제어가 필요한 이벤트를 위한 중첩 객체입니다. 이벤트 이름으로 설정된 `hookEventName` 필드가 필요합니다.989* \*\*`hookSpecificOutput`\*\*은 더 풍부한 제어가 필요한 이벤트를 위한 중첩 객체입니다. 이벤트 이름으로 설정된 `hookEventName` 필드가 필요합니다.

1006 990

1007| 필드 | 기본값 | 설명 |991| 필드 | 기본값 | 설명 |

1008| :- | :- | :- |992| :- | :- | :- |

1010| `stopReason` | 없음 | `continue`가 `false`일 때 사용자에게 표시되는 메시지. 대화에 남아 있으므로 대화가 계속되면 Claude가 이를 봅니다 |994| `stopReason` | 없음 | `continue`가 `false`일 때 사용자에게 표시되는 메시지. 대화에 남아 있으므로 대화가 계속되면 Claude가 이를 봅니다 |

1012| `systemMessage` | 없음 | 사용자에게 표시되는 경고 메시지. [Agent SDK](/docs/ko/agent-sdk/overview) 및 [`--output-format stream-json`](/docs/ko/headless) 출력에서 [`SDKInformationalMessage`](/docs/ko/agent-sdk/typescript#sdkinformationalmessage)로 도착할 수 있습니다 |996| `systemMessage` | 없음 | 사용자에게 표시되는 경고 메시지. [Agent SDK](/docs/ko/agent-sdk/overview) 및 [`--output-format stream-json`](/docs/ko/headless) 출력에서는 [`SDKInformationalMessage`](/docs/ko/agent-sdk/typescript#sdkinformationalmessage)로 도착할 수 있습니다 |

1013| `terminalSequence` | 없음 | Claude Code가 사용자를 대신하여 내보낼 터미널 이스케이프 시퀀스 (예: 데스크톱 알림, 창 제목 또는 벨). OSC `0`/`1`/`2`/`9`/`99`/`777` 및 BEL로 제한됩니다. 값에 허용 목록 외의 항목이 포함되면 필드는 무시됩니다. `/dev/tty`를 사용할 수 없는 hook 대신 이를 사용합니다 |997| `terminalSequence` | 없음 | 데스크톱 알림, 창 제목 또는 벨과 같이 Claude Code가 사용자를 대신하여 내보낼 터미널 이스케이프 시퀀스. OSC `0`/`1`/`2`/`9`/`99`/`777` 및 BEL로 제한됩니다. 값에 허용 목록 외의 항목이 포함되면 필드는 무시됩니다. hook에서 사용할 수 없는 `/dev/tty`에 쓰는 대신 이를 사용합니다 |

1014 998

1015Claude를 완전히 중지하려면:999Claude를 완전히 중지하려면:

1016 1000

1018{ "continue": false, "stopReason": "Build failed, fix errors before continuing" }1002{ "continue": false, "stopReason": "Build failed, fix errors before continuing" }

1019```1003```

1020 1004

1021`PreToolUse` 및 `PostToolUse` hook의 경우 도구 호출이 실패하거나 Claude가 여전히 응답을 스트리밍하는 동안 완료되어도 중지가 적용됩니다.1005`PreToolUse` 및 `PostToolUse` hook의 경우 Claude가 아직 응답을 스트리밍하는 동안 도구 호출이 실패하거나 완료되어도 중지가 적용됩니다.

1022 1006

1023<h4 id="emit-terminal-notifications">1007<h4 id="emit-terminal-notifications">

1024 터미널 알림 내보내기1008 터미널 알림 내보내기

1025</h4>1009</h4>

1026 1010

1027Hook은 제어 터미널 없이 실행되므로 이스케이프 시퀀스를 `/dev/tty`에 직접 쓰는 것이 실패합니다. 대신 `terminalSequence` 필드에 이스케이프 시퀀스를 반환하면 Claude Code가 자신의 터미널 쓰기 경로를 통해 이를 내보냅니다. 이는 race-free이고 tmux 및 GNU screen 내에서 작동하며 `/dev/tty`가 없는 Windows에서도 작동합니다.1011Hook은 제어 터미널 없이 실행되므로 이스케이프 시퀀스를 `/dev/tty`에 직접 쓰면 실패합니다. 대신 `terminalSequence` 필드에 이스케이프 시퀀스를 반환하면 Claude Code가 자체 터미널 쓰기 경로를 통해 이를 내보냅니다. 이 방식은 race-free이며 tmux 및 GNU screen 내에서 작동하고 `/dev/tty`가 없는 Windows에서도 작동합니다.

1028 1012

1029필드는 하나 이상의 허용 목록에 있는 이스케이프 시퀀스 문자열을 허용합니다:1013이 필드는 허용 목록에 있는 하나 이상의 이스케이프 시퀀스로 구성된 문자열을 허용합니다:

1030 1014

1031* OSC `0`, `1`, `2`: 창 및 아이콘 제목1015* OSC `0`, `1`, `2`: 창 및 아이콘 제목

1032* OSC `9`: iTerm2, ConEmu, Windows Terminal, WezTerm 알림 (`9;4` 작업 표시줄 진행률 포함)1016* OSC `9`: iTerm2, ConEmu, Windows Terminal, WezTerm 알림 (`9;4` 작업 표시줄 진행률 포함)

1033* OSC `99`: Kitty 알림1017* OSC `99`: Kitty 알림

1034* OSC `777`: urxvt, Ghostty, Warp 알림1018* OSC `777`: urxvt, Ghostty, Warp 알림

1035* 맨 BEL1019* 단독 BEL

1036 1020

1037시퀀스는 BEL 또는 ST로 종료될 수 있습니다. 허용 목록 외의 항목 (CSI 커서 및 색상 시퀀스, OSC 팔레트 시퀀스, OSC 8 하이퍼링크, OSC 52 클립보드 쓰기, OSC 1337 포함)은 거부되고 필드는 무시됩니다.1021시퀀스는 BEL 또는 ST로 종료될 수 있습니다. CSI 커서 및 색상 시퀀스, OSC 팔레트 시퀀스, OSC 8 하이퍼링크, OSC 52 클립보드 쓰기, OSC 1337을 포함하여 허용 목록 외의 항목은 거부되고 필드는 무시됩니다.

1038 1022

1039Claude Code는 hook의 출력을 처리할 때 시퀀스 자체를 기록하므로 필드는 `systemMessage` 및 `continue`를 버리는 이벤트 (예: `Notification` 및 `StopFailure`)에서 작동합니다. 두 가지 제한이 있습니다:1023Claude Code는 hook의 출력을 처리할 때 시퀀스를 직접 기록하므로 이 필드는 `Notification` 및 `StopFailure`와 같이 `systemMessage` 및 `continue`를 버리는 이벤트에서도 작동합니다. 두 가지 제한이 있습니다:

1040 1024

1041* Claude Code는 대화형 세션에서만 시퀀스를 기록하고 인터페이스가 화면에 있을 때만 기록합니다. `-p` 플래그를 사용한 비대화형 모드 및 Agent SDK에서 필드를 무시합니다.1025* Claude Code는 대화형 세션에서만, 그리고 인터페이스가 화면에 표시되어 있는 동안에만 시퀀스를 기록합니다. `-p` 플래그를 사용한 비대화형 모드와 Agent SDK에서는 이 필드를 무시합니다.

1042* `WorktreeCreate` 명령 hook은 Claude Code가 stdout을 worktree 경로로 읽기 때문에 JSON을 반환할 수 없습니다. HTTP `WorktreeCreate` hook은 JSON을 반환하고 필드를 포함할 수 있습니다.1026* `WorktreeCreate` 명령 hook은 Claude Code가 stdout을 worktree 경로로 읽기 때문에 JSON을 반환할 수 없습니다. HTTP `WorktreeCreate` hook은 JSON을 반환하므로 이 필드를 포함할 수 있습니다.

1043 1027

1044아래 예제는 `Notification` hook에서 데스크톱 알림을 발생시킵니다. 이스케이프 시퀀스는 `printf` 8진수 이스케이프로 빌드되므로 제어 바이트가 셸 명령줄에 나타나지 않으며, `jq -n --arg`는 JSON 출력을 빌드하므로 알림 메시지의 따옴표, 백슬래시, 줄바꿈이 올바르게 이스케이프됩니다:1028아래 예제는 `Notification` hook에서 데스크톱 알림을 발생시킵니다. 이스케이프 시퀀스는 `printf` 8진수 이스케이프로 만들어지므로 제어 바이트가 셸 명령줄에 나타나지 않으며, `jq -n --arg`로 JSON 출력을 만들어 알림 메시지의 따옴표, 백슬래시, 줄바꿈이 올바르게 이스케이프됩니다:

1045 1029

1046```bash theme={null}1030```bash theme={null}

1047#!/bin/bash1031#!/bin/bash

1048# Notification hook: Claude Code가 주의가 필요할 때 데스크톱을 ping합니다.1032# Notification hook: ping the desktop when Claude Code needs attention.

1049input=$(cat)1033input=$(cat)

1050title="Claude Code"1034title="Claude Code"

1051body=$(jq -r '.message // "Needs your attention"' <<<"$input")1035body=$(jq -r '.message // "Needs your attention"' <<<"$input")

1059 Claude를 위한 컨텍스트 추가1043 Claude를 위한 컨텍스트 추가

1060</h4>1044</h4>

1061 1045

1062`additionalContext` 필드는 hook에서 Claude의 컨텍스트 윈도우로 문자열을 전달합니다. Claude Code는 문자열을 시스템 미리 알림으로 래핑하고 hook이 발생한 지점에서 대화에 삽입합니다. Claude는 다음 모델 요청에서 미리 알림을 읽지만 인터페이스에 채팅 메시지로 나타나지 않습니다.1046`additionalContext` 필드는 hook의 문자열을 Claude의 컨텍스트 윈도우로 전달합니다. Claude Code는 문자열을 [시스템 리마인더](/docs/ko/glossary#system-reminder)로 감싸고 hook이 발생한 지점에서 대화에 삽입합니다. Claude는 다음 모델 요청에서 리마인더를 읽지만, 인터페이스에 채팅 메시지로 나타나지는 않습니다.

1063 1047

1064이벤트 이름과 함께 `hookSpecificOutput` 내에 `additionalContext`를 반환합니다:1048이벤트 이름과 함께 `hookSpecificOutput` 내에 `additionalContext`를 반환합니다:

1065 1049

1072}1056}

1073```1057```

1074 1058

1075미리 알림이 나타나는 위치는 이벤트에 따라 다릅니다:1059리마인더가 나타나는 위치는 이벤트에 따라 다릅니다:

1076 1060

1077* [SessionStart](#sessionstart) 및 [SubagentStart](#subagentstart): 대화 시작, 첫 번째 프롬프트 전1061* [SessionStart](#sessionstart) 및 [SubagentStart](#subagentstart): 대화 시작 시, 첫 번째 프롬프트 전

1078* [UserPromptSubmit](#userpromptsubmit) 및 [UserPromptExpansion](#userpromptexpansion): 제출된 프롬프트 옆1062* [UserPromptSubmit](#userpromptsubmit) 및 [UserPromptExpansion](#userpromptexpansion): 제출된 프롬프트와 함께

1079* [PreToolUse](#pretooluse), [PostToolUse](#posttooluse), [PostToolUseFailure](#posttoolusefailure), [PostToolBatch](#posttoolbatch): 도구 결과 옆1063* [PreToolUse](#pretooluse), [PostToolUse](#posttooluse), [PostToolUseFailure](#posttoolusefailure), [PostToolBatch](#posttoolbatch): 도구 결과 옆

1080* [Stop](#stop) 및 [SubagentStop](#subagentstop): 턴의 끝. 대화가 계속되므로 Claude가 피드백에 작용할 수 있습니다. [Stop 결정 제어](#stop-decision-control) 참조1064* [Stop](#stop) 및 [SubagentStop](#subagentstop): 턴의 끝. 대화가 계속되므로 Claude가 피드백에 따라 행동할 수 있습니다. [Stop 결정 제어](#stop-decision-control) 참조

1081* [PostModelSwitch](#postmodelswitch): 전환 후 다음 요청과 함께. [PostModelSwitch 결정 제어](#postmodelswitch-decision-control)에서 타이밍을 참조하세요1065* [PostModelSwitch](#postmodelswitch): 전환 후 다음 요청과 함께. 타이밍은 [PostModelSwitch 결정 제어](#postmodelswitch-decision-control)를 참조하세요

1082 1066

1083여러 hook이 동일한 이벤트에 대해 `additionalContext`를 반환하면 Claude는 모든 값을 받습니다.1067여러 hook이 동일한 이벤트에 대해 `additionalContext`를 반환하면 Claude는 모든 값을 받습니다.

1084 1068

1085값이 10,000자를 초과하면 Claude Code는 전체 텍스트를 세션 디렉토리의 파일에 쓰고 짧은 미리보기와 함께 파일 경로를 Claude에 전달합니다.1069값이 10,000자를 초과하면 Claude Code는 텍스트를 세션 디렉터리의 파일에 쓰고, 대신 최대 처음 2,000자의 미리보기와 함께 파일 경로를 Claude에 전달합니다. Claude는 파일을 읽을 수 있지만 Claude Code가 읽도록 요청하지는 않습니다.

1086 1070

1087Claude가 현재 환경 상태 또는 방금 실행된 작업에 대해 알아야 할 정보에 `additionalContext`를 사용합니다:1071Claude가 현재 환경 상태 또는 방금 실행된 작업에 대해 알아야 할 정보에 `additionalContext`를 사용합니다:

1088 1072

1089* **환경 상태**: 현재 분기, 배포 대상 또는 활성 기능 플래그1073* **환경 상태**: 현재 브랜치, 배포 대상 또는 활성 기능 플래그

1090* **조건부 프로젝트 규칙**: 방금 편집한 파일에 적용되는 테스트 명령, 이 worktree에서 읽기 전용인 디렉토리1074* **조건부 프로젝트 규칙**: 방금 편집한 파일에 적용되는 테스트 명령, 이 worktree에서 읽기 전용인 디렉터리

1091* **외부 데이터**: 사용자에게 할당된 열린 문제, 최근 CI 결과, 내부 서비스에서 가져온 콘텐츠1075* **외부 데이터**: 사용자에게 할당된 열린 이슈, 최근 CI 결과, 내부 서비스에서 가져온 콘텐츠

1092 1076

1093변경되지 않는 지침의 경우 [CLAUDE.md](/docs/ko/memory)를 선호합니다. 스크립트를 실행하지 않고 로드되며 정적 프로젝트 규칙의 표준 위치입니다.1077변경되지 않는 지침에는 [CLAUDE.md](/docs/ko/memory)를 사용하는 것이 좋습니다. 스크립트를 실행하지 않고 로드되며 정적 프로젝트 규칙을 위한 표준 위치입니다.

1094 1078

1095명령형 시스템 지침이 아닌 사실 진술로 텍스트를 작성합니다. "배포 대상은 프로덕션입니다" 또는 "이 리포지토리는 `bun test`를 사용합니다"와 같은 표현은 프로젝트 정보로 읽힙니다. 대역 외 시스템 명령으로 표현된 텍스트는 Claude의 프롬프트 주입 방어를 트리거할 수 있으며, 이로 인해 Claude가 텍스트를 컨텍스트로 취급하는 대신 사용자에게 표시합니다.1079텍스트는 명령형 시스템 지침이 아닌 사실 진술로 작성합니다. "배포 대상은 프로덕션입니다" 또는 "이 리포지토리는 `bun test`를 사용합니다"와 같은 표현은 프로젝트 정보로 읽힙니다. 대역 외 시스템 명령으로 표현된 텍스트는 Claude의 프롬프트 인젝션 방어를 트리거할 수 있으며, 이 경우 Claude는 텍스트를 컨텍스트로 취급하는 대신 사용자에게 표시합니다.

1096 1080

1097주입되면 텍스트는 세션 트랜스크립트에 저장됩니다. `PostToolUse` 또는 `UserPromptSubmit`과 같은 중간 세션 이벤트의 경우 `--continue` 또는 `--resume`으로 재개하면 과거 턴에 대해 hook을 다시 실행하는 대신 저장된 텍스트를 재생하므로 타임스탬프 또는 커밋 SHA와 같은 값이 재개 시 오래됩니다. `SessionStart` hook은 `source`가 `"resume"`으로 설정된 재개 시 다시 실행되거나 `"fork"`로 설정된 경우 `--fork-session`을 추가했으므로 컨텍스트를 새로 고칠 수 있습니다.1081Claude Code는 주입된 텍스트를 세션 트랜스크립트에 저장합니다. `PostToolUse` 또는 `UserPromptSubmit`과 같은 세션 중간 이벤트의 경우 `--continue` 또는 `--resume`으로 재개하면 Claude Code는 과거 턴에 대해 hook을 다시 실행하는 대신 저장된 텍스트를 재생하므로 타임스탬프나 커밋 SHA와 같은 값은 오래된 값이 됩니다. `SessionStart` hook은 재개 시 `source`가 `"resume"`으로, `--fork-session`을 추가한 경우 `"fork"`로 설정된 상태로 다시 실행되므로 컨텍스트를 새로 고칠 수 있습니다.

1098 1082

1099<h4 id="decision-control">1083<h4 id="decision-control">

1100 결정 제어1084 결정 제어

1101</h4>1085</h4>

1102 1086

1103모든 이벤트가 JSON을 통해 동작을 차단하거나 제어하는 것을 지원하는 것은 아닙니다. 그렇게 하는 이벤트는 각각 다른 필드 집합을 사용하여 해당 결정을 표현합니다. hook을 작성하기 전에 이 표를 빠른 참조로 사용하세요:1087모든 이벤트가 JSON을 통한 동작 차단이나 제어를 지원하는 것은 아닙니다. 이를 지원하는 이벤트는 각각 다른 필드 집합을 사용하여 결정을 표현합니다. hook을 작성하기 전에 이 표를 빠른 참조로 사용하세요:

1104 1088

1105| 이벤트 | 결정 패턴 | 주요 필드 |1089| 이벤트 | 결정 패턴 | 주요 필드 |

1106| :- | :- | :- |1090| :- | :- | :- |

1107| UserPromptSubmit, UserPromptExpansion, PostToolUse, PostToolUseFailure, PostToolBatch, Stop, SubagentStop, ConfigChange, PreCompact | 최상위 `decision` | `decision: "block"`, `reason`. Stop 및 SubagentStop은 또한 [오류가 아닌 피드백을 위해 대화를 계속하는](#stop-decision-control) `hookSpecificOutput.additionalContext`를 허용합니다 |1091| UserPromptSubmit, UserPromptExpansion, PostToolUse, PostToolUseFailure, PostToolBatch, Stop, SubagentStop, ConfigChange, PreCompact | 최상위 `decision` | `decision: "block"`, `reason`. Stop 및 SubagentStop은 [대화를 계속하는 오류가 아닌 피드백](#stop-decision-control)을 위해 `hookSpecificOutput.additionalContext`도 허용합니다 |

1108| TeammateIdle, TaskCompleted | 종료 코드 또는 `continue: false` | 종료 코드 2는 stderr 피드백으로 작업을 차단합니다. JSON `{"continue": false, "stopReason": "..."}` 또한 팀원을 완전히 중지하여 `Stop` hook 동작과 일치합니다. [TaskCompleted는 `TaskUpdate` 도구가 이벤트를 트리거했을 때 이를 무시합니다](#taskcompleted-decision-control) |1092| TeammateIdle, TaskCompleted | 종료 코드 또는 `continue: false` | 종료 코드 2는 stderr 피드백과 함께 작업을 차단합니다. JSON `{"continue": false, "stopReason": "..."}`도 `Stop` hook 동작과 마찬가지로 팀원을 완전히 중지합니다. [TaskCompleted는 `TaskUpdate` 도구가 이벤트를 트리거한 경우 이를 무시합니다](#taskcompleted-decision-control) |

1111| PreModelSwitch | `hookSpecificOutput` 또는 최상위 `decision` | `permissionDecision` (allow/deny/ask), `permissionDecisionReason`. `decision: "block"`도 [전환을 취소](#premodelswitch-decision-control)하고 사용자에게 stderr을 표시합니다 |1095| PreModelSwitch | `hookSpecificOutput` 또는 최상위 `decision` | `permissionDecision` (allow/deny/ask), `permissionDecisionReason`. `decision: "block"`도 [전환을 취소](#premodelswitch-decision-control)합니다 |

1113| PermissionDenied | `hookSpecificOutput` | `retry: true`는 모델이 거부된 도구 호출을 재시도할 수 있음을 알립니다. Claude Code는 [no-verdict 거부](#permissiondenied-decision-control)에 대해 이를 무시합니다 |1097| PermissionDenied | `hookSpecificOutput` | `retry: true`는 모델에 거부된 도구 호출을 재시도할 수 있음을 알립니다. Claude Code는 [no-verdict 거부](#permissiondenied-decision-control)에 대해 이를 무시합니다 |

1119| SessionStart, SubagentStart, PostModelSwitch | 컨텍스트만 | `hookSpecificOutput.additionalContext`는 Claude를 위한 컨텍스트를 추가합니다. SessionStart는 또한 [`initialUserMessage`, `watchPaths`, `sessionTitle`, `reloadSkills`](#sessionstart-decision-control)를 허용합니다. 차단 또는 결정 제어 없음 |1103| SessionStart, SubagentStart, PostModelSwitch | 컨텍스트만 | `hookSpecificOutput.additionalContext`는 Claude를 위한 컨텍스트를 추가합니다. SessionStart는 [`initialUserMessage`, `watchPaths`, `sessionTitle`, `reloadSkills`](#sessionstart-decision-control)도 허용합니다. 차단 또는 결정 제어 없음 |

1120| Setup, Notification, SessionEnd, PostCompact, InstructionsLoaded, StopFailure, CwdChanged, DirectoryAdded, FileChanged | 없음 | 결정 제어 없음. 로깅 또는 정리와 같은 부작용에 사용됨 |1104| Setup, Notification, SessionEnd, PostCompact, InstructionsLoaded, StopFailure, CwdChanged, DirectoryAdded, FileChanged | 없음 | 결정 제어 없음. 로깅이나 정리와 같은 부수 효과에 사용됩니다 |

~~1121~~ 1105

1122일부 이벤트는 또한 허용 또는 차단하는 것이 아니라 콘텐츠를 다시 작성할 수 있습니다:1106일부 이벤트는 허용하거나 차단하는 것 외에 콘텐츠를 다시 작성할 수도 있습니다:

~~1123~~ 1107

1124* `PreToolUse`: `hookSpecificOutput` 바로 아래의 `updatedInput`은 실행 전에 도구의 인수를 바꿉니다. [PreToolUse 결정 제어](#pretooluse-decision-control) 참조1108* `PreToolUse`: `hookSpecificOutput` 바로 아래의 `updatedInput`은 실행 전에 도구의 인수를 대체합니다. [PreToolUse 결정 제어](#pretooluse-decision-control) 참조

1125* `PermissionRequest`: `decision` 객체 내의 `updatedInput`. [PermissionRequest 결정 제어](#permissionrequest-decision-control) 참조1109* `PermissionRequest`: `decision` 객체 내의 `updatedInput`. [PermissionRequest 결정 제어](#permissionrequest-decision-control) 참조

1126* `PostToolUse`: `updatedToolOutput`은 도구의 결과를 바꿉니다. [PostToolUse 결정 제어](#posttooluse-decision-control) 참조1110* `PostToolUse`: `updatedToolOutput`은 도구의 결과를 대체합니다. [PostToolUse 결정 제어](#posttooluse-decision-control) 참조

1127* `UserPromptSubmit`: 프롬프트를 바꿀 수 없습니다. `additionalContext`를 옆에만 주입합니다1111* `UserPromptSubmit`: 프롬프트를 대체할 수 없으며, 프롬프트와 함께 `additionalContext`를 주입하기만 합니다

1128 1112

1129편집 또는 변환 사용 사례의 경우 아웃바운드 도구 입력에 대해 `PreToolUse`에서 가로채고 인바운드 도구 결과에 대해 `PostToolUse`에서 가로채세요.1113민감 정보 제거나 변환 사용 사례의 경우 나가는 도구 입력은 `PreToolUse`에서, 들어오는 도구 결과는 `PostToolUse`에서 가로채세요.

1130 1114

1131다음은 각 패턴의 실제 예입니다:1115다음은 각 패턴의 실제 예입니다:

1132 1116

1133<Tabs>1117<Tabs>

1134 <Tab title="최상위 결정">1118 <Tab title="최상위 결정">

1135 유일한 값은 `"block"`입니다. 작업을 진행하도록 허용하려면 JSON에서 `decision`을 생략하거나 JSON 없이 종료 0으로 나갑니다:1119 `decision`의 유일한 값은 `"block"`입니다. 작업 진행을 허용하려면 JSON에서 `decision`을 생략하거나 JSON 없이 종료 0으로 나갑니다:

1136 1120

1137 ```json theme={null}1121 ```json theme={null}

1138 {1122 {

1143 </Tab>1127 </Tab>

1144 1128

1145 <Tab title="PreToolUse">1129 <Tab title="PreToolUse">

1146 더 풍부한 제어를 위해 `hookSpecificOutput`을 사용합니다: 허용, 거부, 요청 또는 연기. 실행 전에 도구 입력을 수정하거나 Claude를 위한 추가 컨텍스트를 주입할 수도 있습니다. 전체 옵션 집합은 [PreToolUse 결정 제어](#pretooluse-decision-control)를 참조하세요.1130 더 풍부한 제어를 위해 `hookSpecificOutput`을 사용합니다: 허용, 거부 또는 사용자에게 에스컬레이션. 실행 전에 도구 입력을 수정하거나 Claude를 위한 추가 컨텍스트를 주입할 수도 있습니다. 전체 옵션은 [PreToolUse 결정 제어](#pretooluse-decision-control)를 참조하세요.

1147 1131

1148 ```json theme={null}1132 ```json theme={null}

1149 {1133 {

1157 </Tab>1141 </Tab>

1158 1142

1159 <Tab title="PermissionRequest">1143 <Tab title="PermissionRequest">

1160 `hookSpecificOutput`을 사용하여 사용자를 대신하여 권한 요청을 허용하거나 거부합니다. 허용할 때 도구의 입력을 수정하거나 권한 규칙을 적용하여 사용자가 다시 프롬프트되지 않도록 할 수 있습니다. 전체 옵션 집합은 [PermissionRequest 결정 제어](#permissionrequest-decision-control)를 참조하세요.1144 `hookSpecificOutput`을 사용하여 사용자를 대신해 권한 요청을 허용하거나 거부합니다. 허용할 때는 도구의 입력을 수정하거나 권한 규칙을 적용하여 사용자에게 다시 확인을 요청하지 않도록 할 수도 있습니다. 전체 옵션은 [PermissionRequest 결정 제어](#permissionrequest-decision-control)를 참조하세요.

1161 1145

1162 ```json theme={null}1146 ```json theme={null}

1163 {1147 {

1178Bash 명령 검증, 프롬프트 필터링, 자동 승인 스크립트를 포함한 확장 예제는 가이드의 [자동화할 수 있는 것](/docs/ko/hooks-guide#what-you-can-automate)과 [Bash 명령 검증기 참조 구현](https://github.com/anthropics/claude-code/blob/main/examples/hooks/bash_command_validator_example.py)을 참조하세요.1162Bash 명령 검증, 프롬프트 필터링, 자동 승인 스크립트를 포함한 확장 예제는 가이드의 [자동화할 수 있는 것](/docs/ko/hooks-guide#what-you-can-automate)과 [Bash 명령 검증기 참조 구현](https://github.com/anthropics/claude-code/blob/main/examples/hooks/bash_command_validator_example.py)을 참조하세요.

1179 1163

1180<h2 id="hook-events">1164<h2 id="hook-events">

1181 Hook 이벤트1165 훅 이벤트

1182</h2>1166</h2>

1183 1167

1184각 이벤트는 hook이 실행될 수 있는 Claude Code의 수명 주기의 지점에 해당합니다. 아래 섹션은 수명 주기와 일치하도록 정렬됩니다: 세션 설정에서 에이전트 루프를 거쳐 세션 종료까지. 각 섹션에서는 이벤트가 언제 발생하는지, 지원하는 matcher, 받는 JSON 입력, 출력을 통해 동작을 제어하는 방법을 설명합니다.1168각 이벤트는 훅이 실행될 수 있는 Claude Code 수명 주기의 한 시점에 해당합니다. 아래 섹션은 세션 설정부터 에이전틱 루프를 거쳐 세션 종료까지 수명 주기 순서대로 정렬되어 있습니다. 각 섹션에서는 이벤트가 언제 발생하는지, 어떤 matcher를 지원하는지, 어떤 JSON 입력을 받는지, 출력을 통해 동작을 어떻게 제어하는지 설명합니다.

1185 1169

1186<h3 id="sessionstart">1170<h3 id="sessionstart">

1187 SessionStart1171 SessionStart

1188</h3>1172</h3>

1189 1173

1190Claude Code가 새 세션을 시작하거나 기존 세션을 재개할 때 실행됩니다. 기존 문제나 코드베이스의 최근 변경 사항과 같은 개발 컨텍스트를 로드하거나 환경 변수를 설정하는 데 유용합니다. 스크립트가 필요하지 않은 정적 컨텍스트의 경우 [CLAUDE.md](/docs/ko/memory)를 사용하세요.1174Claude Code가 새 세션을 시작하거나 기존 세션을 재개할 때 실행됩니다. 기존 이슈나 코드베이스의 최근 변경 사항 같은 개발 컨텍스트를 로드하거나 환경 변수를 설정할 때 유용합니다. 스크립트가 필요하지 않은 정적 컨텍스트에는 대신 [CLAUDE.md](/docs/ko/memory)를 사용합니다.

1191 1175

1192SessionStart는 모든 세션에서 실행되므로 이러한 hook을 빠르게 유지하세요. `type: "command"` 및 `type: "mcp_tool"` hook만 지원됩니다. [MCP tool hook 필드](#mcp-tool-hook-fields)를 참조하여 `mcp_tool` hook이 언제 실행되는지 확인하세요.1176SessionStart는 모든 세션에서 실행되므로 이 훅은 빠르게 유지해야 합니다. `type: "command"` 및 `type: "mcp_tool"` 훅만 지원됩니다. `mcp_tool` 훅이 언제 실행되는지는 [MCP 도구 훅 필드](#mcp-tool-hook-fields)를 참조하십시오.

1193 1177

1194matcher 값은 세션이 시작된 방식에 해당합니다:1178matcher 값은 세션이 시작된 방식에 해당합니다.

1195 1179

1196| Matcher | 언제 발생하는지 |1180| Matcher | 발생 시점 |

1197| :- | :- |1181| :- | :- |

1198| `startup` | 새 세션 |1182| `startup` | 새 세션 |

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

1203 1187

1204v2.1.214 이전에는 포크된 세션이 소스 `"resume"`을 보고했습니다.1188v2.1.214 이전에는 분기된 세션이 source를 `"resume"`으로 보고했습니다.

1205 1189

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

1207 1191

1208세션 내에서 `/resume`으로 대화를 전환할 때 전환은 hook이 완료될 때까지 기다립니다. 백그라운드 hook이 여전히 실행 중인 동안 `/clear`를 실행하거나 다른 대화로 전환하면 반환하는 것이 세션에 적용되지 않습니다.1192세션 내에서 `/resume`으로 대화를 전환하면 대신 전환이 훅 완료를 기다립니다. 백그라운드 훅이 아직 실행 중일 때 `/clear`를 실행하거나 다른 대화로 전환하면 훅이 반환하는 내용은 세션에 적용되지 않습니다.

1209 1193

1210시작 시에도 동일한 대기가 적용됩니다 (재개된 세션 포함): SessionStart hook이 여전히 실행 중인 동안 전송하는 프롬프트는 완료될 때까지 Claude에 도달하지 않습니다.1194재개한 세션을 포함하여 실행 시에도 동일한 대기가 적용됩니다. SessionStart 훅이 아직 실행 중일 때 보낸 프롬프트는 훅이 완료될 때까지 Claude에게 전달되지 않습니다.

1211 1195

1212대기 중에 `Esc`를 눌러 프롬프트를 입력으로 다시 가져올 수 있습니다. Hook은 계속 실행됩니다.1196어느 쪽 대기 중이든 `Esc`를 누르면 프롬프트를 보내지 않고 입력란으로 되돌릴 수 있습니다. 훅은 계속 실행됩니다.

1213 1197

1214<h4 id="sessionstart-input">1198<h4 id="sessionstart-input">

1215 SessionStart 입력1199 SessionStart 입력

1216</h4>1200</h4>

1217 1201

1218[공통 입력 필드](#common-input-fields) 외에도 SessionStart hook은 `source` 및 선택적으로 `model`, `agent_type`, `session_title`을 받습니다:1202[공통 입력 필드](#common-input-fields) 외에도 SessionStart 훅은 `source`와 선택적으로 `model`, `agent_type`, `session_title`을 받습니다.

1219 1203

1220| 필드 | 설명 |1204| 필드 | 설명 |

1221| :- | :- |1205| :- | :- |

1222| `source` | 세션이 시작된 방식: 새 세션의 경우 `"startup"`, 재개된 세션의 경우 `"resume"`, `/clear` 후 `"clear"`, 압축 후 `"compact"`, 또는 기존 세션에서 포크된 새 세션의 경우 `"fork"` |1206| `source` | 세션이 시작된 방식: 새 세션은 `"startup"`, 재개된 세션은 `"resume"`, `/clear` 후에는 `"clear"`, 압축 후에는 `"compact"`, 기존 세션에서 분기된 새 세션은 `"fork"` |

1225| `session_title` | 이미 설정된 경우 현재 세션 제목 (예: `--name` 또는 `/rename`을 통해). `sessionTitle`을 내보내는 hook은 사용자가 명시적으로 설정한 제목을 덮어쓰지 않도록 먼저 `session_title`을 확인할 수 있습니다 |1209| `session_title` | 세션의 사용자 지정 제목입니다. 예를 들어 `--name`, `/rename`, 훅의 `sessionTitle` 출력 또는 Agent SDK의 `renameSession()`으로 제목이 설정된 경우에 존재합니다. `sessionTitle`을 내보내는 훅은 기존 사용자 지정 제목을 덮어쓰지 않도록 먼저 이 필드를 확인할 수 있습니다 |

1210

1211이름을 지정하지 않은 세션에도 [생성된 제목](/docs/ko/sessions#name-your-sessions)이 있을 수 있습니다. 이 제목은 사용자 지정 제목이 아니며 `session_title`에 나타나지 않습니다.

1226 1212

1227`source`가 `"resume"` 또는 `"fork"`이고 트랜스크립트에 Claude의 응답이 최소 하나 포함되어 있을 때 SessionStart hook은 아래의 네 필드도 받습니다. Hook은 이를 사용하여 첫 번째 요청 전에 오래된 대화를 재개하는 비용을 보고할 수 있습니다 (예: [`systemMessage`](#json-output)에서). 이 필드는 Claude Code v2.1.251 이상이 필요합니다.1213`source`가 `"resume"` 또는 `"fork"`이고 트랜스크립트에 Claude의 응답이 하나 이상 포함된 경우, SessionStart 훅은 아래 네 가지 필드도 받습니다. 훅은 이 필드를 사용하여 첫 요청 전에 오래된 대화를 재개하는 데 드는 비용을 보고할 수 있으며, 예를 들어 [`systemMessage`](#json-output)로 보고할 수 있습니다. 이 필드를 사용하려면 Claude Code v2.1.251 이상이 필요합니다.

1228 1214

1229| 필드 | 설명 |1215| 필드 | 설명 |

1230| :- | :- |1216| :- | :- |

1233| `prompt_cache_likely_expired` | 마지막 응답이 세션의 [prompt cache 수명](/docs/ko/prompt-caching#cache-lifetime)보다 오래되었거나 나중의 압축이 캐시된 대화를 대체했을 때 `true` |1219| `prompt_cache_likely_expired` | 마지막 응답이 세션의 [프롬프트 캐시 수명](/docs/ko/prompt-caching#cache-lifetime)보다 오래되었거나 이후의 압축이 캐시된 대화를 대체한 경우 `true` |

1235 1221

1236이 예제는 마지막 응답 90분 후에 재개된 세션의 입력을 보여줍니다:1222다음 예시는 마지막 응답 90분 후에 재개된 세션의 입력을 보여 줍니다.

1237 1223

1238```json theme={null}1224```json theme={null}

1239{1225{

1254 SessionStart 결정 제어1240 SessionStart 결정 제어

1255</h4>1241</h4>

1256 1242

1257Claude Code는 [일반 텍스트로 처리하는](#exit-code-0) stdout을 Claude의 컨텍스트에 추가합니다. 모든 hook에 사용 가능한 [JSON 출력 필드](#json-output) 외에도 이러한 이벤트 특정 필드를 반환할 수 있습니다:1243Claude Code는 [일반 텍스트로 취급하는](#exit-code-0) stdout을 Claude의 컨텍스트에 추가합니다. 모든 훅에서 사용할 수 있는 [JSON 출력 필드](#json-output) 외에도 다음 이벤트별 필드를 반환할 수 있습니다.

1258 1244

1259| 필드 | 설명 |1245| 필드 | 설명 |

1260| :- | :- |1246| :- | :- |

1261| `additionalContext` | 대화 시작 부분, 첫 번째 프롬프트 전에 Claude의 컨텍스트에 추가되는 문자열. [Claude를 위한 컨텍스트 추가](#add-context-for-claude)를 참조하여 텍스트가 전달되는 방식과 포함할 내용을 확인하세요 |1247| `additionalContext` | 대화 시작 시 첫 프롬프트 전에 Claude의 컨텍스트에 추가되는 문자열입니다. 텍스트가 전달되는 방식과 넣을 내용은 [Claude를 위한 컨텍스트 추가](#add-context-for-claude)를 참조하십시오 |

1262| `initialUserMessage` | 세션의 첫 번째 사용자 메시지로 사용되는 문자열. [비대화형 모드](/docs/ko/headless)에서 `-p` 플래그와 함께 적용되며, 프롬프트가 제공되지 않으면 첫 번째 턴이 됩니다. 프롬프트가 제공되면 다음 턴으로 따릅니다. `additionalContext`와 달리 기존 턴에 첨부되는 이것은 턴을 생성합니다 |1248| `initialUserMessage` | 세션의 첫 사용자 메시지로 사용되는 문자열입니다. `-p` 플래그를 사용하는 [비대화형 모드](/docs/ko/headless)에 적용되며, 프롬프트가 제공되지 않아도 첫 턴이 됩니다. 프롬프트가 제공되면 그 프롬프트가 다음 턴으로 이어집니다. 기존 턴에 첨부되는 `additionalContext`와 달리 이 필드는 턴을 생성합니다 |

1263| `sessionTitle` | 세션 제목을 설정합니다. `/rename`과 동일한 효과입니다. 시작 폴더, git 분기 또는 worktree 이름에서 세션을 자동으로 이름 지정하는 데 사용합니다. `source`가 `"startup"`, `"resume"` 또는 `"fork"`일 때 적용됩니다; `"clear"` 및 `"compact"`에서는 무시됩니다 |1249| `sessionTitle` | 세션 제목을 설정하며, `/rename`과 같은 효과가 있습니다. 실행 폴더, git 브랜치 또는 worktree 이름으로 세션 이름을 자동 지정할 때 사용합니다. `source`가 `"startup"`, `"resume"` 또는 `"fork"`일 때 적용되며, `"clear"` 및 `"compact"`에서는 무시됩니다 |

1265| `reloadSkills` | 부울. `true`일 때 Claude Code는 SessionStart hook이 완료된 후 [skill](/docs/ko/skills) 및 명령 디렉토리를 다시 스캔하므로 hook이 설치한 skill은 첫 번째 프롬프트부터 같은 세션에서 사용 가능합니다 |1251| `reloadSkills` | 불리언입니다. `true`이면 Claude Code는 SessionStart 훅이 완료된 후 [스킬](/docs/ko/skills) 및 명령 디렉터리를 다시 스캔하므로, 훅이 설치한 스킬을 첫 프롬프트부터 같은 세션에서 사용할 수 있습니다 |

1266 1252

1267```json theme={null}1253```json theme={null}

1268{1254{

1274}1260}

1275```1261```

1276 1262

1277이 이벤트에 대해 일반 stdout이 이미 Claude에 도달하므로 컨텍스트만 로드하는 hook은 JSON을 구축하지 않고 stdout에 직접 인쇄할 수 있습니다. `sessionTitle`과 같은 다른 필드와 컨텍스트를 결합해야 할 때 JSON 형식을 사용합니다.1263이 이벤트에서는 일반 stdout이 이미 Claude에게 전달되므로, 컨텍스트만 로드하는 훅은 JSON을 만들지 않고 stdout에 직접 출력할 수 있습니다. 컨텍스트를 `sessionTitle` 같은 다른 필드와 결합해야 할 때 JSON 형식을 사용합니다.

1278 1264

1279SessionStart hook이 skill을 설치하거나 업데이트할 때 `reloadSkills`를 사용합니다. Skill 발견은 일반적으로 SessionStart hook이 완료되기 전에 실행되므로 hook이 `~/.claude/skills/` 또는 `.claude/skills/`에 작성하는 파일은 그렇지 않으면 다음 세션에만 나타납니다. 이 예제는 공유 skill 리포지토리를 동기화하고 다시 스캔을 요청합니다:1265SessionStart 훅이 스킬을 설치하거나 업데이트할 때는 `reloadSkills`를 사용합니다. 스킬 검색은 일반적으로 SessionStart 훅이 완료되기 전에 실행되므로, 그렇지 않으면 훅이 `~/.claude/skills/` 또는 `.claude/skills/`에 쓴 파일은 다음 세션에서만 나타납니다. 다음 예시는 공유 스킬 저장소를 동기화하고 다시 스캔을 요청합니다.

1280 1266

1281```bash theme={null}1267```bash theme={null}

1282#!/bin/bash1268#!/bin/bash

1287echo '{"hookSpecificOutput": {"hookEventName": "SessionStart", "reloadSkills": true}}'1273echo '{"hookSpecificOutput": {"hookEventName": "SessionStart", "reloadSkills": true}}'

1288```1274```

1289 1275

1290리포지토리 URL은 자리 표시자입니다; 자신의 skill 리포지토리로 바꾸세요. 자리 표시자를 사용하면 복제가 실패하고 stderr에 `fatal:` 메시지를 인쇄합니다. 종료 코드 0으로 종료되는 SessionStart hook의 stderr은 정보 전용이므로 `reloadSkills` 요청은 여전히 적용됩니다.1276저장소 URL은 자리 표시자이므로 사용자의 스킬 저장소로 바꿔야 합니다. 자리 표시자를 그대로 사용하면 clone이 실패하고 stderr에 `fatal:` 메시지가 출력됩니다. 0으로 종료하는 SessionStart 훅의 stderr는 정보 제공용일 뿐이므로 `reloadSkills` 요청은 여전히 적용됩니다.

1291 1277

1292<h4 id="persist-environment-variables">1278<h4 id="persist-environment-variables">

1293 환경 변수 유지1279 환경 변수 유지

1294</h4>1280</h4>

1295 1281

1296SessionStart hook은 `CLAUDE_ENV_FILE` 환경 변수에 액세스할 수 있으며, 이는 후속 Bash 명령에 대한 환경 변수를 유지할 수 있는 파일 경로를 제공합니다.1282SessionStart 훅은 `CLAUDE_ENV_FILE` 환경 변수에 접근할 수 있으며, 이 변수는 이후 Bash 명령을 위해 환경 변수를 유지할 수 있는 파일 경로를 제공합니다.

1297 1283

1298개별 환경 변수를 설정하려면 `CLAUDE_ENV_FILE`에 `export` 문을 작성합니다. 다른 hook에서 설정한 변수를 유지하려면 추가 (`>>`)를 사용합니다:1284개별 환경 변수를 설정하려면 `CLAUDE_ENV_FILE`에 `export` 문을 씁니다. 다른 훅이 설정한 변수를 보존하려면 추가(`>>`)를 사용합니다.

1299 1285

1300```bash theme={null}1286```bash theme={null}

1301#!/bin/bash1287#!/bin/bash

1309exit 01295exit 0

1310```1296```

1311 1297

1312설정 명령의 환경 변경을 모두 캡처하려면 내보낸 변수를 이전과 이후에 비교합니다:1298설정 명령의 모든 환경 변경 사항을 캡처하려면 전후의 내보낸 변수를 비교합니다.

1313 1299

1314```bash theme={null}1300```bash theme={null}

1315#!/bin/bash1301#!/bin/bash

1316 1302

1317ENV_BEFORE=$(export -p | sort)1303ENV_BEFORE=$(export -p | sort)

1318 1304

1319# 환경을 수정하는 설정 명령을 실행합니다1305# Run your setup commands that modify the environment

1320source ~/.nvm/nvm.sh1306source ~/.nvm/nvm.sh

1321nvm use 201307nvm use 20

1322 1308

1329```1315```

1330 1316

1331<Note>1317<Note>

1332 `CLAUDE_ENV_FILE`은 SessionStart, [Setup](#setup), [CwdChanged](#cwdchanged), [FileChanged](#filechanged) hook에 사용 가능합니다. 다른 hook 유형은 이 변수에 액세스할 수 없습니다.1318 `CLAUDE_ENV_FILE`은 SessionStart, [Setup](#setup), [CwdChanged](#cwdchanged), [FileChanged](#filechanged) 훅에서 사용할 수 있습니다. 다른 훅 유형은 이 변수에 접근할 수 없습니다.

1333</Note>1319</Note>

1334 1320

1335<h3 id="setup">1321<h3 id="setup">

1336 Setup1322 Setup

1337</h3>1323</h3>

1338 1324

1339`--init-only`로 Claude Code를 시작하거나 [비대화형 모드](/docs/ko/headless)에서 `-p` 플래그와 함께 `--init` 또는 `--maintenance`로 시작할 때만 발생합니다. 일반 시작 시에는 발생하지 않습니다. 일회성 종속성 설치 또는 CI 또는 스크립트에서 명시적으로 트리거하는 예약된 정리에 사용합니다. 일반 세션 시작과 별도입니다. 세션별 초기화의 경우 대신 [SessionStart](#sessionstart)를 사용합니다.1325`--init-only`로 Claude Code를 실행하거나, `-p` 플래그를 사용하는 [비대화형 모드](/docs/ko/headless)에서 `--init` 또는 `--maintenance`로 실행할 때만 발생합니다. 일반 시작 시에는 발생하지 않습니다. 일반 세션 시작과 별도로 CI나 스크립트에서 명시적으로 트리거하는 일회성 의존성 설치나 예약된 정리 작업에 사용합니다. 세션별 초기화에는 대신 [SessionStart](#sessionstart)를 사용합니다.

1340 1326

1341matcher 값은 hook을 트리거한 CLI 플래그에 해당합니다:1327matcher 값은 훅을 트리거한 CLI 플래그에 해당합니다.

1342 1328

1343| Matcher | 언제 발생하는지 |1329| Matcher | 발생 시점 |

1344| :- | :- |1330| :- | :- |

1347 1333

1348`claude --init-only`를 실행하면 Claude Code는 Setup hook과 `startup` matcher가 있는 SessionStart hook을 실행한 다음 대화를 시작하지 않고 종료합니다.1334`claude --init-only`를 실행하면 Claude Code는 Setup 훅과 `startup` matcher를 사용하는 `SessionStart` 훅을 실행한 다음, 대화를 시작하지 않고 종료합니다.

1349 1335

1350`-p`로 대화를 시작하거나 계속할 때 프롬프트도 제공해야 합니다 (인수로 또는 stdin에 파이프됨). SessionStart hook이 [`initialUserMessage`](#sessionstart-decision-control)를 제공하거나 [연기된 도구 호출](#defer-a-tool-call-for-later)로 세션을 재개할 때 프롬프트를 건너뛸 수 있습니다.1336`-p`로 대화를 시작하거나 계속할 때는 인수로 또는 stdin 파이프로 프롬프트도 제공해야 합니다. `SessionStart` 훅이 [`initialUserMessage`](#sessionstart-decision-control)를 제공하거나 [지연된 도구 호출](#defer-a-tool-call-for-later)이 있는 세션을 재개할 때는 프롬프트를 생략할 수 있습니다.

1351 1337

1352성공 시 `--init-only`는 터미널에 아무것도 인쇄하지 않습니다. hook이 실행되었는지 확인하려면 `claude --debug-file <path> --init-only`로 시작하고 `<path>`를 로그 파일 위치로 바꾸고 Setup 및 SessionStart hook 항목에 대한 로그를 확인합니다.1338성공하면 `--init-only`는 터미널에 아무것도 출력하지 않습니다. 훅이 실행되었는지 확인하려면 `<path>`를 로그 파일 위치로 바꿔 `claude --debug-file <path> --init-only`로 시작하고, 로그에서 Setup 및 SessionStart 훅 항목을 확인합니다.

1353 1339

1354Setup은 모든 시작 시 발생하지 않으므로 종속성이 설치된 plugin은 Setup만으로는 의존할 수 없습니다. 실제 패턴은 첫 사용 시 종속성을 확인하고 누락되면 설치하는 것입니다. 예를 들어 `${CLAUDE_PLUGIN_DATA}/node_modules`를 테스트하고 없으면 `npm install`을 실행하는 hook 또는 skill입니다. [지속적 데이터 디렉토리](/docs/ko/plugins-reference#persistent-data-directory)를 참조하여 설치된 종속성을 저장할 위치를 확인하세요. plugin을 마켓플레이스를 통해 배포하는 경우 이 패턴이 필요하지 않을 수 있습니다: Claude Code는 [plugin을 캐시할 때 적격 Node.js 패키지 종속성을 자동으로 설치합니다](/docs/ko/plugins-reference#node-js-package-dependencies).1340Setup은 매번 실행될 때 발생하지 않으므로, 의존성 설치가 필요한 플러그인은 Setup에만 의존할 수 없습니다. 실용적인 패턴은 처음 사용할 때 의존성을 확인하고 없으면 설치하는 것입니다. 예를 들어 `${CLAUDE_PLUGIN_DATA}/node_modules`가 있는지 테스트하고 없으면 `npm install`을 실행하는 훅이나 스킬을 사용할 수 있습니다. 설치된 의존성을 저장할 위치는 [영구 데이터 디렉터리](/docs/ko/plugins/components#path-variables-and-persistent-data)를 참조하십시오. 마켓플레이스를 통해 플러그인을 배포하는 경우에는 이 패턴이 필요하지 않을 수 있습니다. Claude Code는 플러그인을 캐시할 때 [적격한 Node.js 패키지 의존성을 자동으로 설치](/docs/ko/plugins/loading#node-js-package-dependencies)합니다.

1355 1341

1356<h4 id="setup-input">1342<h4 id="setup-input">

1357 Setup 입력1343 Setup 입력

1358</h4>1344</h4>

1359 1345

1360[공통 입력 필드](#common-input-fields) 외에도 Setup hook은 `trigger` 필드를 받으며, 이는 `"init"` 또는 `"maintenance"`로 설정됩니다:1346[공통 입력 필드](#common-input-fields) 외에도 Setup 훅은 `"init"` 또는 `"maintenance"`로 설정된 `trigger` 필드를 받습니다.

1361 1347

1362```json theme={null}1348```json theme={null}

1363{1349{

1373 Setup 결정 제어1359 Setup 결정 제어

1374</h4>1360</h4>

1375 1361

1376Setup hook은 차단할 수 없습니다; 모든 종료 코드에서 실행이 계속됩니다. 모든 종료 코드에서 Claude Code는 Setup hook의 [JSON 출력 필드](#json-output) (예: `systemMessage`, `continue`, `hookSpecificOutput.additionalContext`)를 삭제합니다. `-p`를 사용하면 Setup hook의 stdout, stderr, 종료 코드는 `--output-format stream-json --verbose`로 시작할 때만 [`hook_response` 이벤트](/docs/ko/headless#read-session-metadata)로 실행 출력에 나타납니다.1362Setup 훅은 차단할 수 없으며, 어떤 종료 코드에서도 실행이 계속됩니다. 모든 종료 코드에서 Claude Code는 `systemMessage`, `continue`, `hookSpecificOutput.additionalContext` 같은 Setup 훅의 [JSON 출력 필드](#json-output)를 버립니다. `-p`를 사용하면 Setup 훅의 stdout, stderr, 종료 코드는 `--output-format stream-json --verbose`로 실행한 경우에만 실행 출력에 [`hook_response` 이벤트](/docs/ko/headless#read-session-metadata)로 나타납니다.

1377 1363

1378Setup hook은 `CLAUDE_ENV_FILE`에 액세스할 수 있습니다. 해당 파일에 작성된 변수는 [SessionStart hook](#persist-environment-variables)과 마찬가지로 세션의 후속 Bash 명령에 유지됩니다. `type: "command"` hook만 `Setup`에서 실행됩니다. `type: "mcp_tool"` hook은 [MCP tool hook 필드](#mcp-tool-hook-fields)에서 설명한 대로 `Setup`에서 항상 건너뜁니다.1364Setup 훅은 `CLAUDE_ENV_FILE`에 접근할 수 있습니다. 해당 파일에 쓴 변수는 [SessionStart 훅](#persist-environment-variables)과 마찬가지로 세션의 이후 Bash 명령에 유지됩니다. `Setup`에서는 `type: "command"` 훅만 실행됩니다. `Setup`의 `type: "mcp_tool"` 훅은 [MCP 도구 훅 필드](#mcp-tool-hook-fields)에 설명된 대로 항상 건너뜁니다.

1379 1365

1380<h3 id="instructionsloaded">1366<h3 id="instructionsloaded">

1381 InstructionsLoaded1367 InstructionsLoaded

1382</h3>1368</h3>

1383 1369

1384`CLAUDE.md` 또는 `.claude/rules/*.md` 파일이 컨텍스트에 로드될 때 발생합니다. 이 이벤트는 세션 시작 시 즉시 로드된 파일에 대해 발생하고 나중에 파일이 지연 로드될 때 다시 발생합니다. 예를 들어 Claude가 중첩된 `CLAUDE.md`를 포함하는 하위 디렉토리에 액세스할 때 또는 `paths:` frontmatter가 있는 조건부 규칙이 일치할 때입니다. hook은 차단 또는 결정 제어를 지원하지 않습니다. 관찰성 목적으로 비동기적으로 실행됩니다.1370`CLAUDE.md` 또는 `.claude/rules/*.md` 파일이 컨텍스트에 로드될 때 발생합니다. 이 이벤트는 세션 시작 시 즉시 로드되는 파일에 대해 발생하고, 이후 파일이 지연 로드될 때 다시 발생합니다. 예를 들어 Claude가 중첩된 `CLAUDE.md`가 포함된 하위 디렉터리에 접근하거나 `paths:` frontmatter가 있는 조건부 규칙이 일치할 때입니다. 이 훅은 차단이나 결정 제어를 지원하지 않습니다. 관찰 가능성을 위해 비동기적으로 실행됩니다.

1385 1371

1386이 이벤트는 Claude가 **Project instructions** 설정을 통해 [`AGENTS.md`를 직접 읽을 때](/docs/ko/memory#agents-md)는 발생하지 않습니다. `CLAUDE.md`가 `AGENTS.md`를 가져올 때는 다른 가져온 파일과 마찬가지로 `load_reason`이 `include`로 설정되어 발생하며, `CLAUDE.md`가 이에 대한 symlink일 때는 일반 `CLAUDE.md` 로드로 발생합니다.1372이 이벤트는 Claude가 **Project instructions** 설정을 통해 [`AGENTS.md`를 직접 읽을](/docs/ko/memory#agents-md) 때는 발생하지 않습니다. `CLAUDE.md`가 `AGENTS.md`를 가져올 때는 다른 가져온 파일과 마찬가지로 `load_reason`이 `include`로 설정되어 발생하며, `CLAUDE.md`가 해당 파일에 대한 심볼릭 링크일 때는 일반 `CLAUDE.md` 로드로 발생합니다.

1387 1373

1388matcher는 `load_reason`에 대해 실행됩니다. 예를 들어 `"matcher": "session_start"`를 사용하여 세션 시작 시에만 로드된 파일에 대해 발생하거나 `"matcher": "path_glob_match|nested_traversal"`을 사용하여 지연 로드에만 발생합니다.1374matcher는 `load_reason`에 대해 실행됩니다. 예를 들어 세션 시작 시 로드된 파일에 대해서만 발생시키려면 `"matcher": "session_start"`를, 지연 로드에 대해서만 발생시키려면 `"matcher": "path_glob_match|nested_traversal"`을 사용합니다.

1389 1375

1390<h4 id="instructionsloaded-input">1376<h4 id="instructionsloaded-input">

1391 InstructionsLoaded 입력1377 InstructionsLoaded 입력

1392</h4>1378</h4>

1393 1379

1394[공통 입력 필드](#common-input-fields) 외에도 InstructionsLoaded hook은 이러한 필드를 받습니다:1380[공통 입력 필드](#common-input-fields) 외에도 InstructionsLoaded 훅은 다음 필드를 받습니다.

1395 1381

1396| 필드 | 설명 |1382| 필드 | 설명 |

1397| :- | :- |1383| :- | :- |

1400| `load_reason` | 파일이 로드된 이유: `"session_start"`, `"nested_traversal"`, `"path_glob_match"`, `"include"` 또는 `"compact"`. `"compact"` 값은 압축 이벤트 후 명령 파일이 다시 로드될 때 발생합니다 |1386| `load_reason` | 파일이 로드된 이유: `"session_start"`, `"nested_traversal"`, `"path_glob_match"`, `"include"` 또는 `"compact"`. `"compact"` 값은 압축 이벤트 후 지침 파일이 다시 로드될 때 발생합니다 |

1404 1390

1405```json theme={null}1391```json theme={null}

1406{1392{

1418 InstructionsLoaded 결정 제어1404 InstructionsLoaded 결정 제어

1419</h4>1405</h4>

1420 1406

1421InstructionsLoaded hook은 결정 제어가 없습니다. 명령 로드를 차단하거나 수정할 수 없습니다. Claude Code는 이들의 [JSON 출력 필드](#json-output) (예: `systemMessage`, `continue`)를 삭제합니다. 감사 로깅, 규정 준수 추적 또는 관찰성을 위해 이 이벤트를 사용합니다.1407InstructionsLoaded 훅에는 결정 제어가 없습니다. 지침 로드를 차단하거나 수정할 수 없습니다. Claude Code는 `systemMessage`, `continue` 같은 [JSON 출력 필드](#json-output)를 버립니다. 이 이벤트는 감사 로깅, 규정 준수 추적 또는 관찰 가능성에 사용합니다.

1422 1408

1423<h3 id="userpromptsubmit">1409<h3 id="userpromptsubmit">

1424 UserPromptSubmit1410 UserPromptSubmit

1425</h3>1411</h3>

1426 1412

1427사용자가 프롬프트를 제출할 때, Claude가 처리하기 전에 실행됩니다. 이를 통해 프롬프트/대화를 기반으로 추가 컨텍스트를 추가하거나, 프롬프트를 검증하거나, 특정 유형의 프롬프트를 차단할 수 있습니다.1413사용자가 프롬프트를 제출하면 Claude가 처리하기 전에 실행됩니다. 이를 통해

1414프롬프트나 대화를 기반으로 추가 컨텍스트를 더하거나, 프롬프트를 검증하거나,

1415특정 유형의 프롬프트를 차단할 수 있습니다.

1428 1416

1429`UserPromptSubmit` hook은 `command`, `http`, `mcp_tool` 유형에 대해 기본 30초 시간 초과를 가지며, 이는 대부분의 다른 이벤트에서 이러한 유형의 기본 600초보다 짧습니다. 이 hook은 모든 프롬프트 전에 실행되고 완료될 때까지 모델 처리를 차단하므로 stuck hook은 세션을 정지시킵니다. hook에 더 많은 시간이 필요하면 hook 항목에서 `timeout` 필드를 설정합니다.1417`UserPromptSubmit` 훅의 기본 타임아웃은 `command`, `http`, `mcp_tool` 유형에서 30초이며, 대부분의 다른 이벤트에서 이 유형들의 기본값인 600초보다 짧습니다. 이 훅은 모든 프롬프트 전에 실행되고 완료될 때까지 모델 처리를 차단하므로, 멈춘 훅은 세션을 정지시킵니다. 훅에 더 많은 시간이 필요하면 훅 항목에서 `timeout` 필드를 설정합니다.

1430 1418

1431[`async: true`](#run-hooks-in-the-background)로 실행하는 명령 hook을 제외하고, 시간 초과에 도달한 `UserPromptSubmit` 명령, HTTP 또는 MCP 도구 hook은 취소되고 `additionalContext`를 포함한 출력은 삭제됩니다. 프롬프트는 해당 컨텍스트 없이 여전히 Claude에 전달됩니다. 트랜스크립트에는 hook 이름, 발생한 시간 초과, 출력이 삭제되었음을 나타내는 알림이 표시됩니다.1419[`async: true`](#run-hooks-in-the-background)로 실행하는 명령 훅을 제외하고, 타임아웃에 도달한 `UserPromptSubmit` 명령, HTTP 또는 MCP 도구 훅은 취소되며 `additionalContext`를 포함한 출력이 버려집니다. 프롬프트는 해당 컨텍스트 없이 여전히 Claude에게 전달됩니다. 트랜스크립트에는 훅 이름, 발생한 타임아웃, 출력이 버려졌다는 알림이 표시됩니다.

1432 1420

1433[Agent SDK callback hook](/docs/ko/agent-sdk/hooks)이 `UserPromptSubmit`에서 시간 초과에 도달하면 hook의 이름과 시간 초과를 나타내는 메시지로 프롬프트를 차단합니다. 왜냐하면 callback은 실패하더라도 통과시켜서는 안 되는 정책 게이트로 작동할 수 있기 때문입니다. 세션이 계속됩니다. v2.1.208 이전에는 callback 시간 초과가 실행 오류로 턴을 종료했습니다.1421`UserPromptSubmit`의 [Agent SDK 콜백 훅](/docs/ko/agent-sdk/hooks)이 타임아웃에 도달하면 훅 이름과 타임아웃을 명시한 메시지와 함께 프롬프트를 차단합니다. 해당 위치의 콜백은 실패 시 열려서는 안 되는 정책 게이트 역할을 할 수 있기 때문입니다. 세션은 계속됩니다. v2.1.208 이전에는 해당 이벤트에서 콜백 타임아웃이 발생하면 실행 오류로 턴이 종료되었습니다.

1434 1422

1435<h4 id="userpromptsubmit-input">1423<h4 id="userpromptsubmit-input">

1436 UserPromptSubmit 입력1424 UserPromptSubmit 입력

1437</h4>1425</h4>

1438 1426

1439[공통 입력 필드](#common-input-fields) 외에도 UserPromptSubmit hook은 사용자가 제출한 텍스트를 포함하는 `prompt` 필드를 받습니다.1427[공통 입력 필드](#common-input-fields) 외에도 UserPromptSubmit 훅은 사용자가 제출한 텍스트가 포함된 `prompt` 필드를 받습니다. `[Pasted text #N]` 자리 표시자로 축소된 붙여넣은 콘텐츠는 제자리에서 확장되어 도착합니다. Claude Code가 [Claude를 위해 붙여넣은 텍스트를 표시](/docs/ko/terminal-config#how-claude-treats-pasted-text)하는 세션에서는 확장된 콘텐츠가 `<pasted_content id="…">` 줄과 `</pasted_content id="…">` 줄 사이에 위치하므로, 훅이 프롬프트를 파싱한다면 이 줄들을 고려해야 합니다.

1428

1429UserPromptSubmit 훅은 세션에 사용자 지정 제목이 있으면 `session_title`도 받으며, 의미는 [SessionStart `session_title` 필드](#sessionstart-input)와 같습니다.

1440 1430

1441```json theme={null}1431```json theme={null}

1442{1432{

1453 UserPromptSubmit 결정 제어1443 UserPromptSubmit 결정 제어

1454</h4>1444</h4>

1455 1445

1456`UserPromptSubmit` hook은 사용자 프롬프트 처리 여부를 제어하고 컨텍스트를 추가할 수 있습니다. 모든 [JSON 출력 필드](#json-output)를 사용할 수 있습니다.1446`UserPromptSubmit` 훅은 사용자 프롬프트의 처리 여부를 제어하고 컨텍스트를 추가할 수 있습니다. 모든 [JSON 출력 필드](#json-output)를 사용할 수 있습니다.

1457 1447

1458종료 코드 0에서 대화에 컨텍스트를 추가하는 두 가지 방법이 있습니다:1448종료 코드 0에서 대화에 컨텍스트를 추가하는 방법은 두 가지입니다.

1459 1449

1460* **일반 텍스트 stdout**: Claude Code는 [일반 텍스트로 처리하는](#exit-code-0) stdout을 Claude의 컨텍스트에 추가합니다1450* **일반 텍스트 stdout**: Claude Code는 [일반 텍스트로 취급하는](#exit-code-0) stdout을 Claude의 컨텍스트에 추가합니다

1461* **`additionalContext`가 있는 JSON**: 더 많은 제어를 위해 아래 JSON 형식을 사용합니다. `additionalContext` 필드는 컨텍스트에 추가됩니다1451* **`additionalContext`가 있는 JSON**: 더 세밀하게 제어하려면 아래 JSON 형식을 사용합니다. `additionalContext` 필드가 컨텍스트로 추가됩니다

1462 1452

1463둘 다 가시적인 트랜스크립트 항목을 생성하지 않습니다. 일반 stdout과 `additionalContext` 값은 각각 hook의 이름으로 시작하는 시스템 알림으로 주입됩니다; Claude는 둘 다 읽습니다. 전달을 확인하려면 [디버그 로그](#debug-hooks)를 확인하세요.1453어느 채널도 트랜스크립트에 표시되는 항목을 생성하지 않습니다. 일반 stdout과 `additionalContext` 값은 각각 훅 이름으로 시작하는 시스템 리마인더로 주입되며, Claude는 둘 다 읽습니다. 전달을 확인하려면 [디버그 로그](#debug-hooks)를 확인합니다.

1464 1454

1465프롬프트를 차단하려면 `decision`을 `"block"`으로 설정한 JSON 객체를 반환합니다:1455프롬프트를 차단하려면 `decision`이 `"block"`으로 설정된 JSON 객체를 반환합니다.

1466 1456

1467| 필드 | 설명 |1457| 필드 | 설명 |

1468| :- | :- |1458| :- | :- |

1473| `suppressOriginalPrompt` | `decision`이 `"block"`일 때 `true`인 경우 사용자에게 표시되는 차단 메시지에서 원본 프롬프트 텍스트를 생략합니다 |1463| `suppressOriginalPrompt` | 훅이 프롬프트를 차단할 때 `true`이면 차단 메시지에서 프롬프트 텍스트를 제외합니다. [차단된 프롬프트가 남기는 것](#what-a-blocked-prompt-leaves-behind)을 참조하십시오 |

1474 1464

1475종료 코드 2로 차단하는 hook은 `reason`과 동일한 방식으로 라우팅됩니다: 차단 메시지는 stderr 텍스트를 사용자에게 표시하고 컨텍스트에 추가되지 않습니다.1465종료 코드 2로 차단하는 훅은 `reason`과 같은 방식으로 전달됩니다. 차단 메시지는 stderr 텍스트를 사용자에게 표시하며, 컨텍스트에는 추가되지 않습니다.

1476 1466

1477```json theme={null}1467```json theme={null}

1478{1468{

1481 "hookSpecificOutput": {1471 "hookSpecificOutput": {

1482 "hookEventName": "UserPromptSubmit",1472 "hookEventName": "UserPromptSubmit",

1483 "additionalContext": "My additional context here",1473 "additionalContext": "My additional context here",

1484 "sessionTitle": "My session title"1474 "sessionTitle": "My session title",

1475 "suppressOriginalPrompt": true

1485 }1476 }

1486}1477}

1487```1478```

1488 1479

1480<h4 id="what-a-blocked-prompt-leaves-behind">

1481 차단된 프롬프트가 남기는 것

1482</h4>

1483

1484차단된 프롬프트는 Claude에게 도달하지 않지만, 그 텍스트가 모든 곳에서 제거되는 것은 아닙니다. 기본적으로 사용자에게 표시되는 차단 메시지는 `Original prompt:` 뒤에 제출된 텍스트로 끝나며, Claude Code는 이 메시지를 디스크의 세션 트랜스크립트 파일에 씁니다. 메시지에서 텍스트를 제외하려면 `hookSpecificOutput` 안에 `"suppressOriginalPrompt": true`가 있는 JSON을 출력합니다. 이는 훅이 `decision: "block"`으로 차단하든 종료 코드 2로 차단하든 작동합니다. JSON을 출력하지 않는 종료 코드 2 훅은 항상 차단 메시지에 프롬프트 텍스트가 포함됩니다.

1485

1486`suppressOriginalPrompt`는 차단 메시지만 변경합니다. 제출된 텍스트는 세션 트랜스크립트나 프롬프트 기록 같은 로컬 파일에 여전히 나타날 수 있으므로, 차단 훅은 비밀 정보를 디스크에 남기지 않는 방법이 아닙니다. 이러한 파일을 제한하거나 제거하려면 [일반 텍스트 스토리지](/docs/ko/claude-directory#plaintext-storage) 및 [로컬 데이터 지우기](/docs/ko/claude-directory#clear-local-data)를 참조하십시오.

1487

1489<h3 id="userpromptexpansion">1488<h3 id="userpromptexpansion">

1490 UserPromptExpansion1489 UserPromptExpansion

1491</h3>1490</h3>

1492 1491

1493사용자가 입력한 slash 명령이 Claude에 도달하기 전에 프롬프트로 확장될 때 실행됩니다. 이를 사용하여 특정 명령이 직접 호출되는 것을 차단하거나, 특정 skill에 대한 컨텍스트를 주입하거나, 사용자가 호출하는 명령을 기록합니다. 예를 들어 `deploy`와 일치하는 hook은 승인 파일이 없으면 `/deploy`를 차단할 수 있고, review skill과 일치하는 hook은 팀의 review 체크리스트를 `additionalContext`로 추가할 수 있습니다.1492사용자가 입력한 명령이 Claude에게 도달하기 전에 프롬프트로 확장될 때 실행됩니다. 특정 명령의 직접 호출을 차단하거나, 특정 스킬에 컨텍스트를 주입하거나, 사용자가 호출하는 명령을 로그에 기록하는 데 사용합니다. 예를 들어 `deploy`와 일치하는 훅은 승인 파일이 없으면 `/deploy`를 차단할 수 있고, 리뷰 스킬과 일치하는 훅은 팀의 리뷰 체크리스트를 `additionalContext`로 추가할 수 있습니다.

1494 1493

1495이 이벤트는 `PreToolUse`가 다루지 않는 경로를 다룹니다: `PreToolUse` hook이 `Skill` 도구와 일치하면 Claude가 도구를 호출할 때만 발생하지만, `/skillname`을 직접 입력하면 `PreToolUse`를 우회합니다. `UserPromptExpansion`은 그 직접 경로에서 발생합니다.1494이 이벤트는 `PreToolUse`가 다루지 않는 경로를 다룹니다. `Skill` 도구와 일치하는 `PreToolUse` 훅은 Claude가 도구를 호출할 때만 발생하지만, `/skillname`을 직접 입력하면 `PreToolUse`를 우회합니다. `UserPromptExpansion`은 이 직접 경로에서 발생합니다.

1496 1495

1497`command_name`에서 일치합니다. matcher를 비워두어 모든 prompt 유형 slash 명령에서 발생하도록 합니다.1496`command_name`에 대해 일치시킵니다. 모든 프롬프트 유형 명령에서 발생시키려면 matcher를 비워 둡니다.

1498 1497

1499<h4 id="userpromptexpansion-input">1498<h4 id="userpromptexpansion-input">

1500 UserPromptExpansion 입력1499 UserPromptExpansion 입력

1501</h4>1500</h4>

1502 1501

1503[공통 입력 필드](#common-input-fields) 외에도 UserPromptExpansion hook은 `expansion_type`, `command_name`, `command_args`, `command_source`, 원본 `prompt` 문자열을 받습니다. `expansion_type` 필드는 skill 및 사용자 정의 명령의 경우 `slash_command`이거나 MCP 서버 프롬프트의 경우 `mcp_prompt`입니다.1502[공통 입력 필드](#common-input-fields) 외에도 UserPromptExpansion 훅은 `expansion_type`, `command_name`, `command_args`, `command_source`, 원본 `prompt` 문자열을 받습니다. `expansion_type` 필드는 스킬 및 사용자 지정 명령의 경우 `slash_command`, MCP 서버 프롬프트의 경우 `mcp_prompt`입니다.

1504 1503

1505```json theme={null}1504```json theme={null}

1506{1505{

1521 UserPromptExpansion 결정 제어1520 UserPromptExpansion 결정 제어

1522</h4>1521</h4>

1523 1522

1524`UserPromptExpansion` hook은 확장을 차단하거나 컨텍스트를 추가할 수 있습니다. 모든 [JSON 출력 필드](#json-output)를 사용할 수 있습니다.1523`UserPromptExpansion` 훅은 확장을 차단하거나 컨텍스트를 추가할 수 있습니다. 모든 [JSON 출력 필드](#json-output)를 사용할 수 있습니다.

1525 1524

1526| 필드 | 설명 |1525| 필드 | 설명 |

1527| :- | :- |1526| :- | :- |

1531 1530

1532종료 코드 2로 차단하는 hook은 `reason`과 동일한 방식으로 라우팅됩니다: 차단 메시지는 stderr 텍스트를 사용자에게 표시합니다.1531종료 코드 2로 차단하는 훅은 `reason`과 같은 방식으로 전달됩니다. 차단 메시지는 stderr 텍스트를 사용자에게 표시합니다.

1533 1532

1534```json theme={null}1533```json theme={null}

1535{1534{

1546 MessageDisplay1545 MessageDisplay

1547</h3>1546</h3>

1548 1547

1549어시스턴트 메시지가 화면으로 스트리밍되는 동안 실행됩니다. Claude Code는 메시지를 증분으로 표시합니다: 새로 완료된 줄의 배치가 렌더링될 준비가 될 때마다 hook이 한 번 실행되고 Claude Code는 hook의 대체 텍스트를 그 자리에 렌더링합니다. 긴 메시지는 여러 호출을 생성합니다; 짧은 메시지는 하나만 생성할 수 있습니다.1548어시스턴트 메시지가 화면에 스트리밍되는 동안 실행됩니다. Claude Code는 메시지를 단계적으로 표시합니다. 새로 완성된 줄의 배치가 렌더링될 준비가 될 때마다 훅이 해당 줄로 한 번 실행되고, Claude Code는 그 자리에 훅의 대체 텍스트를 렌더링합니다. 긴 메시지는 여러 번 호출되며, 짧은 메시지는 한 번만 호출될 수도 있습니다.

1550 1549

1551MessageDisplay를 사용하여:1550MessageDisplay는 다음 용도로 사용합니다.

1552 1551

1553* markdown을 제거하여 최소한의 표시1552* 최소한의 표시를 위해 markdown 제거

1554* Agent SDK 애플리케이션이 사용자에게 표시하는 텍스트 변환1553* Agent SDK 애플리케이션이 사용자에게 보여 주는 텍스트 변환

1555* Claude의 응답에서 API 키 또는 내부 호스트명 제거1554* Claude의 응답에서 API 키나 내부 호스트 이름 가리기

1556 1555

1557Claude Code는 각 배치를 hook이 반환할 때까지 보유하므로 hook을 빠르게 유지하세요. hook이 실패하거나 시간 초과되면 Claude Code는 원본 텍스트를 표시합니다. 이 이벤트의 기본 시간 초과는 10초입니다; hook에 더 많은 시간이 필요하면 hook 항목에서 `timeout` 필드를 설정합니다.1556Claude Code는 훅이 반환할 때까지 각 배치를 보류하므로 훅을 빠르게 유지해야 합니다. 훅이 실패하거나 시간 초과되면 Claude Code는 원본 텍스트를 표시합니다. 이 이벤트의 기본 타임아웃은 10초이며, 훅에 더 많은 시간이 필요하면 훅 항목에서 `timeout` 필드를 설정합니다.

1558 1557

1559MessageDisplay는 표시 전용입니다: 대체 텍스트는 화면에 렌더링되는 것만 변경합니다. 트랜스크립트와 Claude가 보는 것은 원본 텍스트를 유지하므로 Claude는 대체를 보지 못하고 verbose 모드는 원본을 표시합니다. hook은 어시스턴트 메시지 텍스트만 받으므로 도구 결과와 입력한 텍스트는 변경되지 않은 상태로 렌더링됩니다.1558MessageDisplay는 표시 전용입니다. 대체 텍스트는 화면에 렌더링되는 내용만 변경합니다. 트랜스크립트와 Claude가 보는 내용은 원본 텍스트를 유지하므로 Claude는 대체 텍스트를 보지 않으며, 상세 모드에서는 원본이 표시됩니다. 훅은 어시스턴트 메시지 텍스트만 받으므로 도구 결과와 사용자가 입력한 텍스트는 변경 없이 렌더링됩니다.

1560 1559

1561MessageDisplay는 matcher를 지원하지 않으며 텍스트를 스트리밍하는 모든 어시스턴트 메시지에 대해 발생합니다; 도구 호출 전용 응답과 같이 텍스트가 없는 메시지는 이를 트리거하지 않습니다.1560MessageDisplay는 matcher를 지원하지 않으며, 텍스트를 스트리밍하는 모든 어시스턴트 메시지에서 발생합니다. 도구 호출만 있는 응답처럼 텍스트가 없는 메시지는 이 훅을 트리거하지 않습니다.

1562 1561

1563비대화형 실행 (Agent SDK 쿼리 및 `claude -p` 포함)에서 MessageDisplay는 줄의 배치당 한 번이 아닌 어시스턴트 메시지당 한 번 실행됩니다. 단일 호출은 메시지가 완료된 후 도착하고 전체 메시지 텍스트를 전달합니다: `index`는 `0`, `final`은 `true`, `delta`는 전체 메시지를 보유합니다. 각 메시지에 대해 `delta` 텍스트를 수집하는 hook은 두 모드 모두에서 동일한 총 텍스트를 받습니다.1562Agent SDK 쿼리와 `claude -p`를 포함한 비대화형 실행에서는 MessageDisplay가 줄 배치마다 한 번이 아니라 어시스턴트 메시지마다 한 번 실행됩니다. 단일 호출은 메시지가 완료된 후 도착하며 전체 메시지 텍스트를 전달합니다. `index`는 `0`, `final`은 `true`이고, `delta`에는 메시지 전체가 담깁니다. 각 메시지의 `delta` 텍스트를 수집하는 훅은 두 모드에서 동일한 전체 텍스트를 받습니다.

1564 1563

1565<h4 id="messagedisplay-input">1564<h4 id="messagedisplay-input">

1566 MessageDisplay 입력1565 MessageDisplay 입력

1567</h4>1566</h4>

1568 1567

1569[공통 입력 필드](#common-input-fields) 외에도 MessageDisplay hook은 턴과 메시지의 식별자, 이 호출이 메시지 내에서의 위치, `delta`의 새 텍스트를 받습니다. 배치 경계는 텍스트가 스트리밍되는 방식에 따라 다르므로 줄이 특정 방식으로 그룹화될 것으로 예상하기보다는 `index` 및 `final`을 사용하여 메시지를 통한 진행 상황을 추적합니다.1568[공통 입력 필드](#common-input-fields) 외에도 MessageDisplay 훅은 턴과 메시지의 식별자, 메시지 내에서 이 호출의 위치, `delta`의 새 텍스트를 받습니다. 배치 경계는 텍스트가 스트리밍되는 방식에 따라 달라지므로, 줄이 특정 방식으로 그룹화될 것으로 기대하지 말고 `index`와 `final`을 사용하여 메시지 진행 상황을 추적합니다.

1570 1569

1571| 필드 | 설명 |1570| 필드 | 설명 |

1572| :- | :- |1571| :- | :- |

1577| `delta` | 이전 배치 이후의 새로 완료된 줄, 종료 줄바꿈 포함. 항상 전체 줄이며, 최종 배치는 줄 중간에 끝날 수 있습니다. 대화형 실행에서 메시지가 줄바꿈으로 끝나면 최종 배치의 delta는 비어 있으므로 비어 있지 않은 delta가 아닌 `final`을 메시지 끝 신호로 취급합니다. Agent SDK 및 `claude -p` 실행에서 단일 호출은 전체 메시지를 전달합니다 |1576| `delta` | 이전 배치 이후 새로 완성된 줄이며, 끝의 줄바꿈이 포함됩니다. 줄 중간에서 끝날 수 있는 마지막 배치를 제외하면 항상 완전한 줄입니다. 대화형 실행에서 메시지가 줄바꿈으로 끝나면 마지막 배치의 delta는 비어 있으므로, 비어 있지 않은 delta가 아니라 `final`을 메시지 종료 신호로 취급해야 합니다. Agent SDK 및 `claude -p` 실행에서는 단일 호출이 메시지 전체를 전달합니다 |

1578 1577

1579```json theme={null}1578```json theme={null}

1580{1579{

1594 MessageDisplay 출력1593 MessageDisplay 출력

1595</h4>1594</h4>

1596 1595

1597모든 hook에 사용 가능한 [JSON 출력 필드](#json-output) 외에도 MessageDisplay hook은 `displayContent`를 반환하여 화면의 delta를 바꿀 수 있습니다:1596모든 훅에서 사용할 수 있는 [JSON 출력 필드](#json-output) 외에도 MessageDisplay 훅은 화면의 delta를 대체하는 `displayContent`를 반환할 수 있습니다.

1598 1597

1599| 필드 | 설명 |1598| 필드 | 설명 |

1600| :- | :- |1599| :- | :- |

1602 1601

1603MessageDisplay hook은 결정 제어가 없습니다. 메시지를 차단하거나 트랜스크립트에 저장되거나 Claude에 전송되는 것을 변경할 수 없습니다. Claude Code는 이들의 JSON 출력에서 `displayContent`를 작동하고 `systemMessage` 및 `continue`를 삭제합니다.1602MessageDisplay 훅에는 결정 제어가 없습니다. 메시지를 차단하거나 트랜스크립트에 저장되거나 Claude에게 전송되는 내용을 변경할 수 없습니다. Claude Code는 JSON 출력의 `displayContent`에 따라 동작하고 `systemMessage`와 `continue`는 버립니다.

1604 1603

1605이 예제는 Claude의 응답에서 markdown 형식을 제거하여 일반 텍스트 표시를 합니다. 스크립트는 stdin에서 각 배치를 읽고 `delta`에서 굵은 마커와 인라인 코드 백틱을 제거하고 결과를 `displayContent`로 반환합니다.1604다음 예시는 일반 텍스트 표시를 위해 Claude의 응답에서 markdown 서식을 제거합니다. 스크립트는 stdin에서 각 배치를 읽고, `delta`에서 굵게 표시 기호와 인라인 코드 백틱을 제거한 다음, 결과를 `displayContent`로 반환합니다.

1606 1605

1607<Tabs>1606<Tabs>

1608 <Tab title="macOS/Linux">1607 <Tab title="macOS/Linux">

1609 설정 파일에서 이벤트에 대한 명령 hook을 등록합니다:1608 설정 파일에서 이벤트에 대한 명령 훅을 등록합니다.

1610 1609

1611 ```json theme={null}1610 ```json theme={null}

1612 {1611 {

1626 }1625 }

1627 ```1626 ```

1628 1627

1629 이 스크립트를 프로젝트의 `.claude/hooks/plain-display.sh`에 저장하고 `chmod +x`로 실행 가능하게 만듭니다:1628 이 스크립트를 프로젝트의 `.claude/hooks/plain-display.sh`에 저장하고 `chmod +x`로 실행 가능하게 만듭니다.

1630 1629

1631 ```bash theme={null}1630 ```bash theme={null}

1632 #!/bin/bash1631 #!/bin/bash

1635 </Tab>1634 </Tab>

1636 1635

1637 <Tab title="Windows (PowerShell)">1636 <Tab title="Windows (PowerShell)">

1638 PowerShell을 통해 스크립트를 실행하는 명령 hook을 등록합니다:1637 PowerShell을 통해 스크립트를 실행하는 명령 훅을 등록합니다.

1639 1638

1640 ```json theme={null}1639 ```json theme={null}

1641 {1640 {

1661 }1660 }

1662 ```1661 ```

1663 1662

1664 `-NoProfile` 플래그는 PowerShell 프로필 로드를 건너뛰어 hook이 빠르게 시작되도록 하고, `-ExecutionPolicy Bypass`는 PowerShell이 로컬 스크립트 파일을 실행하도록 합니다.1663 `-NoProfile` 플래그는 PowerShell 프로필 로드를 건너뛰어 훅이 빠르게 시작되도록 하고, `-ExecutionPolicy Bypass`는 PowerShell이 로컬 스크립트 파일을 실행할 수 있게 합니다.

1665 1664

1666 이 스크립트를 프로젝트의 `.claude/hooks/plain-display.ps1`에 저장합니다:1665 이 스크립트를 프로젝트의 `.claude/hooks/plain-display.ps1`에 저장합니다.

1667 1666

1668 ```powershell theme={null}1667 ```powershell theme={null}

1669 $batch = [Console]::In.ReadToEnd() | ConvertFrom-Json1668 $batch = [Console]::In.ReadToEnd() | ConvertFrom-Json

1678 </Tab>1677 </Tab>

1679</Tabs>1678</Tabs>

1680 1679

1681markdown이 없는 배치는 변경되지 않은 상태로 통과합니다. 스크립트가 실패하면 (예: `jq`가 누락된 경우) Claude Code는 원본 텍스트를 표시하고 [디버그 출력](#debug-hooks)에서만 실패를 기록하며 세션에서는 기록하지 않습니다.1680markdown이 없는 배치는 변경 없이 통과합니다. 예를 들어 `jq`가 없어 스크립트가 실패하면, Claude Code는 원본 텍스트를 표시하고 실패 사실은 세션이 아닌 [디버그 출력](#debug-hooks)에만 기록합니다.

1682 1681

1683<h3 id="pretooluse">1682<h3 id="pretooluse">

1684 PreToolUse1683 PreToolUse

1685</h3>1684</h3>

1686 1685

1687Claude가 도구 매개변수를 생성한 후 도구 호출을 처리하기 전에 실행됩니다. `EndConversation`을 제외한 모든 도구 이름에서 일치합니다: `Bash`, `PowerShell`, `Edit`, `Write`, `Read`, `Glob`, `Grep`, `Agent`, `Workflow`, `WebFetch`, `WebSearch`, `AskUserQuestion`, `ExitPlanMode`와 같은 기본 제공 도구, 그리고 모든 [MCP 도구 이름](#match-mcp-tools).1686Claude가 도구 매개변수를 생성한 후, 도구 호출을 처리하기 전에 실행됩니다. `EndConversation`을 제외한 모든 도구 이름에 대해 일치시킵니다. 여기에는 `Bash`, `PowerShell`, `Edit`, `Write`, `Read`, `Glob`, `Grep`, `Agent`, `Workflow`, `WebFetch`, `WebSearch`, `AskUserQuestion`, `ExitPlanMode` 같은 기본 제공 도구와 모든 [MCP 도구 이름](#match-mcp-tools)이 포함됩니다.

1688 1687

1689특정 파일이 디스크에서 변경될 때 (어떤 것이 작성했든) hook을 실행하려면 파일 편집 도구를 이름으로 일치시키는 대신 [FileChanged](#filechanged)를 사용합니다. PreToolUse와 달리 Claude Code는 FileChanged hook을 변경 후에 실행하고 결정 제어가 없으므로 쓰기를 차단할 수 없습니다.1688무엇이 파일을 썼든 디스크에서 특정 파일이 변경될 때 훅을 실행하려면, 파일 편집 도구를 이름으로 일치시키는 대신 [FileChanged](#filechanged)를 사용합니다. PreToolUse와 달리 Claude Code는 변경 후에 FileChanged 훅을 실행하며, 이 훅에는 결정 제어가 없으므로 쓰기를 차단할 수 없습니다.

1690 1689

1691<Warning>1690<Warning>

1692 PreToolUse는 Claude가 도구를 호출할 때만 실행됩니다. [프롬프트에서 `@`로 참조하는](/docs/ko/common-workflows#reference-files-and-directories) 파일은 도구 호출 없이 추가됩니다: Claude Code는 프롬프트를 구축하는 동안 해당 내용을 삽입하므로 `Read`와 일치하는 hook을 포함하여 PreToolUse hook이 발생하지 않습니다. 특정 경로를 `@` 참조에서 차단하려면 [`Read` 거부 규칙](/docs/ko/permissions#read-and-edit)을 대신 사용하세요.1691 PreToolUse는 Claude가 도구를 호출할 때만 실행됩니다. [프롬프트에서 `@`로 참조한](/docs/ko/common-workflows#reference-files-and-directories) 파일은 도구 호출 없이 추가됩니다. Claude Code가 프롬프트를 구성하는 동안 파일 내용을 삽입하므로, `Read`와 일치하는 훅을 포함하여 어떤 PreToolUse 훅도 발생하지 않습니다. `@` 참조에서 특정 경로를 차단하려면 대신 [`Read` 거부 규칙](/docs/ko/permissions#read-and-edit)을 사용합니다.

1693 1692

1694 PreToolUse는 또한 [`EndConversation`](/docs/ko/tools-reference#endconversation-tool-behavior)에 대해 발생하지 않습니다.1693 PreToolUse는 [`EndConversation`](/docs/ko/tools-reference#endconversation-tool-behavior)에서도 발생하지 않습니다.

1695</Warning>1694</Warning>

1696 1695

1697[PreToolUse 결정 제어](#pretooluse-decision-control)를 사용하여 도구 사용을 허용, 거부, 요청 또는 연기합니다.1696도구 호출을 허용, 거부, 확인 요청 또는 지연하려면 [PreToolUse 결정 제어](#pretooluse-decision-control)를 사용합니다.

1698 1697

1699[Agent SDK callback hook](/docs/ko/agent-sdk/hooks)이 `PreToolUse`에서 시간 초과를 초과하면 도구 호출을 차단하고 Claude는 시간 초과를 이름으로 지정하는 오류 결과를 받습니다. 다른 hook이 반환한 명시적 거부가 여전히 우선합니다.1698`PreToolUse`의 [Agent SDK 콜백 훅](/docs/ko/agent-sdk/hooks)이 타임아웃을 초과하면 도구 호출이 차단되고, Claude는 타임아웃을 명시한 오류 결과를 받습니다. 다른 훅이 반환한 명시적 거부는 여전히 우선합니다.

1700 1699

1701<h4 id="pretooluse-input">1700<h4 id="pretooluse-input">

1702 PreToolUse 입력1701 PreToolUse 입력

1703</h4>1702</h4>

1704 1703

1705[공통 입력 필드](#common-input-fields) 외에도 PreToolUse hook은 `tool_name`, `tool_input`, `tool_use_id`를 받습니다.1704[공통 입력 필드](#common-input-fields) 외에도 PreToolUse 훅은 `tool_name`, `tool_input`, `tool_use_id`를 받습니다.

1706 1705

1707[MCP 도구](#match-mcp-tools)의 경우 입력은 또한 서버의 `name`과 서버의 정의가 어디에서 왔는지를 나타내는 `source`가 있는 객체인 `mcp_server`를 전달합니다. `source` 값에는 `plugin`, `sdk`, `user`, `project`와 같은 구성 범위가 포함됩니다. [`McpServerProvenance`](/docs/ko/agent-sdk/typescript#mcpserverprovenance)는 Agent SDK 참조에서 모두 나열하고 인식하지 못하는 것을 처리하는 방법을 설명합니다. `name` 또는 `mcp__<server>__` 도구 이름 접두사가 아닌 `source`를 기반으로 신뢰 결정을 내립니다. `mcp_server` 필드는 Claude Code v2.1.274 이상이 필요합니다.1706[MCP 도구](#match-mcp-tools)의 경우 입력에 `mcp_server`도 포함됩니다. 이는 서버의 `name`과 서버 정의의 출처를 나타내는 `source`를 가진 객체입니다. `source` 값에는 `plugin`, `sdk`, 그리고 `user`, `project` 같은 구성 범위가 포함됩니다. Agent SDK 참조의 [`McpServerProvenance`](/docs/ko/agent-sdk/typescript#mcpserverprovenance)에 모든 값이 나열되어 있으며, 인식하지 못하는 값을 처리하는 방법도 설명되어 있습니다. 신뢰 결정은 `name`이나 `mcp__<server>__` 도구 이름 접두사가 아닌 `source`를 기반으로 내려야 합니다. `mcp_server` 필드를 사용하려면 Claude Code v2.1.274 이상이 필요합니다.

1708 1707

1709파일 도구 `Write`, `Edit`, `Read`의 경우 `tool_input.file_path`는 항상 절대 경로입니다:1708파일 도구 `Write`, `Edit`, `Read`의 경우 `tool_input.file_path`는 항상 절대 경로입니다.

1710 1709

1711* Claude Code는 hook이 실행되기 전에 `~` 및 상대 경로를 확장하므로 경로와 일치하는 hook은 `~` 또는 동일한 경로의 상대 철자를 통해 우회될 수 없습니다1710* Claude Code는 훅이 실행되기 전에 `~`와 상대 경로를 확장하므로, 경로에 대해 일치시키는 훅은 `~`나 같은 경로의 상대 표기로 우회할 수 없습니다

1712* Windows에서 경로는 `$PWD`가 `/c/project`처럼 보이는 Git Bash에서 hook이 실행되더라도 백슬래시 구분 기호로 도착합니다1711* Windows에서는 훅이 `$PWD`가 `/c/project`처럼 보이는 Git Bash에서 실행되더라도 경로가 백슬래시 구분 기호로 도착합니다

1713* 정방향 슬래시로 작성된 비교 (예: `/src/` 검사)는 백슬래시 경로와 절대 일치하지 않으며 hook이 차단할 것이 없는 것처럼 도구 호출이 진행됩니다1712* `/src/` 검사처럼 슬래시로 작성된 비교는 백슬래시 경로와 절대 일치하지 않으며, 도구 호출은 훅이 차단할 것이 없었던 것처럼 진행됩니다

1714* 비교 전에 구분 기호를 정규화합니다: Bash에서 `FILE_PATH="${FILE_PATH//\\//}"`, Python에서 `file_path.replace("\\", "/")`, 그런 다음 `^`로 고정하지 않고 `/src/`와 같은 경로 세그먼트와 일치합니다 (경로는 절대 경로이므로)1713* 비교하기 전에 구분 기호를 정규화합니다. Bash에서는 `FILE_PATH="${FILE_PATH//\\//}"`, Python에서는 `file_path.replace("\\", "/")`를 사용한 다음, 경로가 절대 경로이므로 `^`로 고정하지 말고 `/src/` 같은 경로 세그먼트와 일치시킵니다

1715 1714

1716Windows의 `Write` 호출은 다음을 전달합니다:1715Windows에서 `Write` 호출은 다음을 전달합니다.

1717 1716

1718```json theme={null}1717```json theme={null}

1719{1718{

1727}1726}

1728```1727```

1729 1728

1730`tool_input` 필드는 도구에 따라 다릅니다:1729`tool_input` 필드는 도구에 따라 다릅니다.

1731 1730

1732<a id="bash" />1731<a id="bash" />

1733 1732

1737 1736

1738셸 명령을 실행합니다.1737셸 명령을 실행합니다.

1739 1738

1740| 필드 | 유형 | 예제 | 설명 |1739| 필드 | 유형 | 예시 | 설명 |

1741| :- | :- | :- | :- |1740| :- | :- | :- | :- |

1744| `timeout` | 숫자 | `120000` | 선택적 시간 초과 (밀리초). [최대](/docs/ko/tools-reference#bash-tool-behavior) 이상의 값은 거부되지 않고 최대값으로 감소됩니다 |1743| `timeout` | number | `120000` | 밀리초 단위의 선택적 타임아웃입니다. [최대값](/docs/ko/tools-reference#bash-tool-behavior)을 초과하는 값은 거부되지 않고 최대값으로 줄어듭니다 |

1746 1745

1747Bash 명령이 Git 리포지토리의 파일을 변경할 때 Claude Code는 변경된 내용을 기록할 수 있습니다. [`bashEditDiffEnabled`](/docs/ko/settings-reference#basheditdiffenabled) 설정이 기록을 켤 때 모든 권한 모드에서 기록합니다; 해당 설정의 항목은 어떤 파일이 이를 설정할 수 있는지 말합니다. 그렇지 않으면 자동 모드 및 `bypassPermissions` 모드에서만 기록하고 Claude Code가 Bash를 통해 파일을 편집하도록 지시할 때만 기록합니다. `bashEditDiffEnabled`를 `false`로 설정하여 기록을 끕니다. 백그라운드 명령과 읽기 전용 명령은 diff를 전달하지 않습니다.1746Bash 명령이 Git 저장소의 파일을 변경하면 Claude Code는 변경된 내용을 기록할 수 있습니다. [`bashEditDiffEnabled`](/docs/ko/settings-reference#basheditdiffenabled) 설정으로 기록을 켜면 모든 권한 모드에서 변경 사항을 기록하며, 어떤 파일에서 이 설정을 지정할 수 있는지는 해당 설정 항목에 설명되어 있습니다. 그렇지 않으면 자동 모드와 `bypassPermissions` 모드에서만, 그리고 Claude Code가 Claude에게 Bash를 통해 파일을 편집하도록 지시할 때만 기록합니다. 기록을 끄려면 `bashEditDiffEnabled`를 `false`로 설정합니다. 백그라운드 명령과 읽기 전용 명령에는 diff가 없습니다.

1748 1747

1749[PostToolUse hook](#posttooluse)은 `tool_response.bashEditDiff`에서 변경된 파일을 받습니다. 목록은 명령이 실행되는 동안 리포지토리 아래에서 변경된 내용을 다룹니다. Git이 무시하는 파일과 하위 모듈의 파일은 나열되지 않습니다. Claude Code v2.1.269 이상이 필요합니다.1748그러면 [PostToolUse 훅](#posttooluse)은 `tool_response.bashEditDiff`에서 변경된 파일을 받습니다. 이 목록은 명령이 실행되는 동안 저장소 아래에서 변경된 내용을 다룹니다. Git이 무시하는 파일과 서브모듈의 파일은 나열되지 않습니다. Claude Code v2.1.269 이상이 필요합니다.

1750 1749

1751<Note>1750<Note>

1752 목록은 최선의 노력이며 공개 베타입니다. Claude Code는 변경을 놓칠 수 있고, 동시에 다른 프로세스가 변경한 파일을 포함할 수 있으며, 크기 제한에서 중지할 수 있습니다. 필드 형태가 변경될 수 있습니다. 정책을 적용하지 않고 검토할 내용을 찾기 위해 목록을 사용합니다.1751 이 목록은 최선의 노력에 기반한 것이며 공개 베타 상태입니다. Claude Code는 변경 사항을 놓치거나, 다른 프로세스가 동시에 변경한 파일을 포함하거나, 크기 제한에서 중단될 수 있습니다. 필드 형태는 변경될 수 있습니다. 이 목록은 정책을 강제하는 용도가 아니라 검토할 대상을 찾는 용도로 사용합니다.

1753</Note>1752</Note>

1754 1753

1755`changedFiles` 및 `files`는 명령이 변경한 내용을 나열합니다; 나머지 필드는 해당 목록이 얼마나 완전하고 신뢰할 수 있는지를 말합니다.1754`changedFiles`와 `files`는 명령이 변경한 내용을 나열하며, 나머지 필드는 해당 목록이 얼마나 완전하고 신뢰할 수 있는지를 나타냅니다.

1756 1755

1757| 필드 | 유형 | 예제 | 설명 |1756| 필드 | 유형 | 예시 | 설명 |

1758| :- | :- | :- | :- |1757| :- | :- | :- | :- |

1760| `files` | 배열 | `[{"filePath": "/path/to/src/app.ts", "hunks": [...]}]` | 최대 5개의 변경된 파일의 diff, 표시용. 명령이 추가하거나 제거한 파일의 경우 `created` 또는 `deleted`는 `true` |1759| `files` | array | `[{"filePath": "/path/to/src/app.ts", "hunks": [...]}]` | 표시용으로 최대 5개의 변경된 파일 diff입니다. 명령이 추가하거나 제거한 파일에는 `created` 또는 `deleted`가 `true`입니다 |

1761| `moreFiles` | 숫자 | `2` | `files`에 diff가 없는 변경된 파일의 개수 |1760| `moreFiles` | number | `2` | `files`에 diff가 없는 변경된 파일 수 |

1765 1764

1766<a id="powershell" />1765<a id="powershell" />

1767 1766

1769 PowerShell1768 PowerShell

1770</h5>1769</h5>

1771 1770

1772PowerShell 명령을 실행합니다. [PowerShell 도구](/docs/ko/tools-reference#powershell-tool)의 가용성을 플랫폼별로 참조하세요.1771PowerShell 명령을 실행합니다. 플랫폼별 사용 가능 여부는 [PowerShell 도구](/docs/ko/tools-reference#powershell-tool)를 참조하십시오.

1773 1772

1774필드는 Bash 도구와 일치하며 `command` 문자열에 명령이 있습니다:1773필드는 Bash 도구와 같으며, 명령 문자열은 `command`에 있습니다.

1775 1774

1776| 필드 | 유형 | 예제 | 설명 |1775| 필드 | 유형 | 예시 | 설명 |

1777| :- | :- | :- | :- |1776| :- | :- | :- | :- |

1780| `timeout` | 숫자 | `120000` | 선택적 시간 초과 (밀리초) |1779| `timeout` | number | `120000` | 밀리초 단위의 선택적 타임아웃 |

1782 1781

1783셸 명령을 검사하는 hook에서 `Bash|PowerShell`과 일치하여 두 도구를 모두 다룹니다:1782셸 명령을 검사하는 훅에서는 두 도구를 모두 다루도록 `Bash|PowerShell`과 일치시킵니다.

1784 1783

1785* Windows에서 PowerShell 도구가 활성화된 곳이면 Claude는 PowerShell을 기본 셸로 취급하고 셸 명령을 통해 라우팅합니다.1784* Windows에서 PowerShell 도구가 활성화된 곳이라면 Claude는 PowerShell을 기본 셸로 취급하고 셸 명령을 PowerShell을 통해 전달합니다.

1786* Git Bash가 없는 Windows에서 도구는 자동으로 활성화되고 Claude Code는 Bash 도구를 등록하지 않습니다.1785* Git Bash가 없는 Windows에서는 이 도구가 자동으로 활성화되며 Claude Code는 Bash 도구를 아예 등록하지 않습니다.

1787* `Bash`만 일치하는 hook은 거기서 절대 발생하지 않습니다.1786* `Bash`만 일치시키는 훅은 그런 환경에서 절대 발생하지 않습니다.

1788 1787

1789<h5 id="write">1788<h5 id="write">

1790 Write1789 Write

1792 1791

1793파일을 생성하거나 덮어씁니다.1792파일을 생성하거나 덮어씁니다.

1794 1793

1795| 필드 | 유형 | 예제 | 설명 |1794| 필드 | 유형 | 예시 | 설명 |

1796| :- | :- | :- | :- |1795| :- | :- | :- | :- |

1799 1798

1800<h5 id="edit">1799<h5 id="edit">

1801 Edit1800 Edit

1803 1802

1804기존 파일의 문자열을 바꿉니다.1803기존 파일의 문자열을 바꿉니다.

1805 1804

1806| 필드 | 유형 | 예제 | 설명 |1805| 필드 | 유형 | 예시 | 설명 |

1807| :- | :- | :- | :- |1806| :- | :- | :- | :- |

1812 1811

1813<h5 id="read">1812<h5 id="read">

1814 Read1813 Read

1816 1815

1817파일 내용을 읽습니다.1816파일 내용을 읽습니다.

1818 1817

1819| 필드 | 유형 | 예제 | 설명 |1818| 필드 | 유형 | 예시 | 설명 |

1820| :- | :- | :- | :- |1819| :- | :- | :- | :- |

1822| `offset` | 숫자 | `10` | 읽기를 시작할 선택적 줄 번호 |1821| `offset` | number | `10` | 읽기를 시작할 선택적 줄 번호 |

1823| `limit` | 숫자 | `50` | 읽을 선택적 줄 수 |1822| `limit` | number | `50` | 읽을 선택적 줄 수 |

1824 1823

1825<h5 id="glob">1824<h5 id="glob">

1826 Glob1825 Glob

1828 1827

1829glob 패턴과 일치하는 파일을 찾습니다.1828glob 패턴과 일치하는 파일을 찾습니다.

1830 1829

1831| 필드 | 유형 | 예제 | 설명 |1830| 필드 | 유형 | 예시 | 설명 |

1832| :- | :- | :- | :- |1831| :- | :- | :- | :- |

1833| `pattern` | 문자열 | `"**/*.ts"` | 파일과 일치시킬 glob 패턴 |1832| `pattern` | string | `"**/*.ts"` | 파일과 일치시킬 glob 패턴 |

1835 1834

1836<h5 id="grep">1835<h5 id="grep">

1837 Grep1836 Grep

1839 1838

1840정규식으로 파일 내용을 검색합니다.1839정규식으로 파일 내용을 검색합니다.

1841 1840

1842| 필드 | 유형 | 예제 | 설명 |1841| 필드 | 유형 | 예시 | 설명 |

1843| :- | :- | :- | :- |1842| :- | :- | :- | :- |

1846| `glob` | 문자열 | `"*.ts"` | 파일을 필터링할 선택적 glob 패턴 |1845| `glob` | string | `"*.ts"` | 파일을 필터링할 선택적 glob 패턴 |

1848| `-i` | 부울 | `true` | 대소문자를 구분하지 않는 검색 |1847| `-i` | boolean | `true` | 대소문자를 구분하지 않는 검색 |

1850 1849

1851<h5 id="webfetch">1850<h5 id="webfetch">

1852 WebFetch1851 WebFetch

1853</h5>1852</h5>

1854 1853

1855웹 콘텐츠를 가져오고 처리합니다.1854웹 콘텐츠를 가져와 처리합니다.

1856 1855

1857| 필드 | 유형 | 예제 | 설명 |1856| 필드 | 유형 | 예시 | 설명 |

1858| :- | :- | :- | :- |1857| :- | :- | :- | :- |

1859| `url` | 문자열 | `"https://example.com/api"` | 콘텐츠를 가져올 URL |1858| `url` | string | `"https://example.com/api"` | 콘텐츠를 가져올 URL |

1861 1860

1862<h5 id="websearch">1861<h5 id="websearch">

1863 WebSearch1862 WebSearch

1865 1864

1866웹을 검색합니다.1865웹을 검색합니다.

1867 1866

1868| 필드 | 유형 | 예제 | 설명 |1867| 필드 | 유형 | 예시 | 설명 |

1869| :- | :- | :- | :- |1868| :- | :- | :- | :- |

1873 1872

1874<h5 id="agent">1873<h5 id="agent">

1875 Agent1874 Agent

1876</h5>1875</h5>

1877 1876

1878[subagent](/docs/ko/sub-agents)를 생성합니다.1877[서브에이전트](/docs/ko/sub-agents)를 생성합니다.

1879 1878

1880| 필드 | 유형 | 예제 | 설명 |1879| 필드 | 유형 | 예시 | 설명 |

1881| :- | :- | :- | :- |1880| :- | :- | :- | :- |

1886 1885

1887foreground Agent 호출이 완료되면 [PostToolUse hook](#posttooluse)은 subagent의 결과와 실행 원격 측정을 `tool_response`에서 받습니다. 이 필드를 읽어 실행을 검사합니다; subagent 전체의 토큰 및 비용 롤업의 경우 [토큰 및 비용 카운터](/docs/ko/monitoring-usage#token-counter)를 `query_source` `"subagent"`로 필터링하여 사용합니다 (`totalTokens` 및 `usage`는 최종 요청만 다룹니다):1886포그라운드 Agent 호출이 완료되면 [PostToolUse 훅](#posttooluse)은 `tool_response`에서 서브에이전트의 결과와 실행 텔레메트리를 받습니다. 실행을 검사하려면 이 필드를 읽습니다. `totalTokens`와 `usage`는 마지막 요청만 다루므로, 서브에이전트 전반의 토큰 및 비용 집계에는 `query_source` `"subagent"`로 필터링한 [토큰 및 비용 카운터](/docs/ko/monitoring-usage#token-counter)를 사용합니다.

1888 1887

1889| 필드 | 유형 | 예제 | 설명 |1888| 필드 | 유형 | 예시 | 설명 |

1890| :- | :- | :- | :- |1889| :- | :- | :- | :- |

1893| `content` | 배열 | `[{"type": "text", "text": "Found 12 endpoints..."}]` | subagent의 최종 텍스트 블록, 또는 [`SubagentHandback`](/docs/ko/tools-reference)을 통해 보고서가 전달되는 subagent의 경우 그 손 전달에 대한 짧은 메모 |1892| `content` | array | `[{"type": "text", "text": "Found 12 endpoints..."}]` | 서브에이전트의 최종 텍스트 블록, 또는 보고서가 `SubagentHandback`을 통해 전달되는 서브에이전트의 경우 그 대신 해당 핸드백에 대한 짧은 메모 |

1896| `totalTokens` | 숫자 | `12450` | subagent의 최종 API 요청의 토큰 수: 입력, 출력, 캐시 토큰 결합. 이는 전체 실행 전체의 총계가 아닙니다 |1895| `totalTokens` | number | `12450` | 서브에이전트의 마지막 API 요청의 토큰 수로, 입력, 출력, 캐시 토큰을 합한 값입니다. 전체 실행에 걸친 합계가 아닙니다 |

1897| `totalDurationMs` | 숫자 | `48211` | subagent 실행의 벽시계 기간 |1896| `totalDurationMs` | number | `48211` | 서브에이전트 실행의 실제 소요 시간 |

1898| `totalToolUseCount` | 숫자 | `7` | subagent가 수행한 도구 호출 수 |1897| `totalToolUseCount` | number | `7` | 서브에이전트가 수행한 도구 호출 수 |

1899| `usage` | 객체 | `{"input_tokens": 8320, ...}` | 최종 API 요청의 유형별 토큰 분석: `input_tokens`, `output_tokens`, `cache_creation_input_tokens`, `cache_read_input_tokens` |1898| `usage` | object | `{"input_tokens": 8320, ...}` | 마지막 API 요청의 유형별 토큰 내역: `input_tokens`, `output_tokens`, `cache_creation_input_tokens`, `cache_read_input_tokens` |

1900 1899

1901Claude Code v2.1.271 이상에서 [`SubagentHandback`](/docs/ko/tools-reference) 도구로 실행되는 subagent는 해당 도구를 통해 보고서를 전달하며 텍스트로 반환하지 않습니다. 완료된 결과의 `content` 필드는 보고서 자체가 아닌 손 전달에 대한 짧은 메모를 전달합니다. 보고서를 읽으려면 `SubagentHandback`과 일치하는 `PreToolUse` 또는 `PostToolUse` hook을 일치시키고 `tool_input.message`를 읽습니다.1900Claude Code v2.1.271 이상에서는 Claude Code가 [자동 모드](/docs/ko/permission-modes#eliminate-prompts-with-auto-mode)에서 제공하는 [`SubagentHandback`](/docs/ko/tools-reference) 도구와 함께 실행되는 서브에이전트가 보고서를 텍스트로 반환하지 않고 해당 도구를 통해 전달합니다. 그러면 `completed` 결과의 `content` 필드에는 보고서 자체가 아니라 해당 핸드백에 대한 짧은 메모가 담깁니다. 보고서를 읽으려면 `SubagentHandback`에 `PreToolUse` 또는 `PostToolUse` 훅을 일치시키고 `tool_input.message`를 읽습니다.

1902 1901

1903백그라운드 subagent의 경우 도구는 작업이 백그라운드로 이동할 때 반환되므로 `tool_response`는 사용 필드를 전달하지 않습니다: 백그라운드 시작은 즉시 반환되고 foreground 작업이 실행 중 백그라운드로 이동하면 해당 전환에서 반환됩니다. `status: "async_launched"`, `agentId`, `description`, `prompt`, `outputFile`, `resolvedModel`이 있습니다.1902백그라운드 서브에이전트의 경우 작업이 백그라운드로 이동할 때 도구가 반환되므로 `tool_response`에는 사용량 필드가 없습니다. 백그라운드 실행은 즉시 반환되며, Claude Code가 실행 도중 백그라운드로 보낸 포그라운드 작업은 그 전환 시점에 반환됩니다. 여기에는 `status: "async_launched"`, `agentId`, `description`, `prompt`, `outputFile`, `resolvedModel`이 있습니다.

1904 1903

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

1906 1905

1907<a id="askuserquestion" />1906<a id="askuserquestion" />

1908 1907

1912 1911

1913사용자에게 1\~4개의 객관식 질문을 합니다.1912사용자에게 1\~4개의 객관식 질문을 합니다.

1914 1913

1915| 필드 | 유형 | 예제 | 설명 |1914| 필드 | 유형 | 예시 | 설명 |

1916| :- | :- | :- | :- |1915| :- | :- | :- | :- |

1917| `questions` | 배열 | `[{"question": "Which framework?", "header": "Framework", "options": [{"label": "React"}], "multiSelect": false}]` | 제시할 질문, 각각 `question` 문자열, 짧은 `header`, `options` 배열, 선택적 `multiSelect` 플래그 |1916| `questions` | array | `[{"question": "Which framework?", "header": "Framework", "options": [{"label": "React"}], "multiSelect": false}]` | 제시할 질문으로, 각각 `question` 문자열, 짧은 `header`, `options` 배열, 선택적 `multiSelect` 플래그를 가집니다 |

1918| `answers` | 객체 | `{"Which framework?": "React"}` | 선택적. 질문 텍스트를 선택한 옵션 레이블로 매핑합니다. 다중 선택 답변은 쉼표로 레이블을 결합합니다. Claude는 이 필드를 설정하지 않습니다; `updatedInput`을 통해 프로그래밍 방식으로 답변을 제공하세요 |1917| `answers` | object | `{"Which framework?": "React"}` | 선택 사항입니다. 질문 텍스트를 선택된 옵션 레이블에 매핑합니다. 다중 선택 답변은 레이블을 쉼표로 연결합니다. Claude는 이 필드를 설정하지 않으며, 프로그래밍 방식으로 답하려면 `updatedInput`을 통해 제공합니다 |

1919 1918

1920<h5 id="exitplanmode">1919<h5 id="exitplanmode">

1921 ExitPlanMode1920 ExitPlanMode

1922</h5>1921</h5>

1923 1922

1924Claude가 [plan 모드](/docs/ko/permission-modes#analyze-before-you-edit-with-plan-mode)를 떠나기 전에 계획을 제시하고 사용자에게 승인을 요청합니다. Claude는 도구를 호출하기 전에 계획을 파일에 디스크에 작성하므로 모델의 리터럴 `tool_input`은 일반적으로 비어 있습니다. Claude Code는 hook에 전달하기 전에 계획 내용과 파일 경로를 주입합니다.1923Claude가 [플랜 모드](/docs/ko/permission-modes#analyze-before-you-edit-with-plan-mode)를 떠나기 전에 계획을 제시하고 사용자에게 승인을 요청합니다. Claude는 도구를 호출하기 전에 계획을 디스크의 파일에 쓰므로, 모델에서 온 실제 `tool_input`은 일반적으로 비어 있습니다. Claude Code는 입력을 훅에 전달하기 전에 계획 내용과 파일 경로를 주입합니다.

1925 1924

1926| 필드 | 유형 | 예제 | 설명 |1925| 필드 | 유형 | 예시 | 설명 |

1927| :- | :- | :- | :- |1926| :- | :- | :- | :- |

1930| `allowedPrompts` | 배열 | `[{"tool": "Bash", "prompt": "run tests"}]` | 더 이상 사용되지 않음. Claude Code는 필드를 수락하지만 무시합니다. v2.1.205 이전에는 Claude가 계획을 구현하기 위해 요청하는 prompt 기반 권한을 전달했습니다 |1929| `allowedPrompts` | array | `[{"tool": "Bash", "prompt": "run tests"}]` | deprecated입니다. Claude Code는 이 필드를 받지만 무시합니다. v2.1.205 이전에는 Claude가 계획을 구현하기 위해 요청한 프롬프트 기반 권한을 담았습니다 |

1931 1930

1932`PostToolUse`에서 `tool_response`는 승인된 계획을 보유하는 `plan` 및 `filePath` 필드가 있는 객체이며, 내부 상태 플래그도 있습니다. 디스크에서 파일을 다시 읽는 대신 `tool_response.plan`에서 계획 내용을 읽으세요.1931`PostToolUse`에서 `tool_response`는 승인된 계획을 담은 `plan` 및 `filePath` 필드와 내부 상태 플래그가 있는 객체입니다. 디스크에서 파일을 다시 읽는 대신 `tool_response.plan`에서 계획 내용을 읽습니다.

1933 1932

1934<h4 id="pretooluse-decision-control">1933<h4 id="pretooluse-decision-control">

1935 PreToolUse 결정 제어1934 PreToolUse 결정 제어

1936</h4>1935</h4>

1937 1936

1938`PreToolUse` hook은 도구 호출 진행 여부를 제어할 수 있습니다. 최상위 `decision` 필드를 사용하는 다른 hook과 달리 PreToolUse는 `hookSpecificOutput` 객체 내에 결정을 반환합니다. 이는 더 풍부한 제어를 제공합니다: 네 가지 결과 (허용, 거부, 요청 또는 연기) 및 실행 전에 도구 입력을 수정하는 기능.1937`PreToolUse` 훅은 도구 호출의 진행 여부를 제어할 수 있습니다. 최상위 `decision` 필드를 사용하는 다른 훅과 달리 PreToolUse는 `hookSpecificOutput` 객체 안에서 결정을 반환합니다. 이를 통해 네 가지 결과(허용, 거부, 확인 요청, 지연)와 실행 전 도구 입력 수정 기능이라는 더 풍부한 제어가 가능합니다.

1939 1938

1940| 필드 | 설명 |1939| 필드 | 설명 |

1941| :- | :- |1940| :- | :- |

1942| `permissionDecision` | `"allow"`는 권한 프롬프트를 건너뜁니다 ([어떤 모드도 자동 승인하지 않는 작업](/docs/ko/permission-modes#actions-no-mode-auto-approves) 및 [`updatedInput`과 쌍을 이루어야 하는](#allow-with-updatedinput) `AskUserQuestion` 및 `ExitPlanMode` 제외). `"deny"`는 도구 호출을 방지합니다. `"ask"`는 사용자에게 확인을 요청합니다. `"defer"`는 나중에 재개하도록 연기합니다. [거부 및 요청 규칙](/docs/ko/permissions#manage-permissions)은 hook이 반환하는 것과 관계없이 여전히 평가됩니다 |1941| `permissionDecision` | `"allow"`는 권한 프롬프트를 건너뜁니다. 단, [어떤 모드도 자동 승인하지 않는 작업](/docs/ko/permission-modes#actions-no-mode-auto-approves)과 [`updatedInput`을 함께 사용](#allow-with-updatedinput)해야 하는 `AskUserQuestion` 및 `ExitPlanMode`는 예외입니다. `"deny"`는 도구 호출을 막습니다. `"ask"`는 사용자에게 확인을 요청합니다. `"defer"`는 나중에 도구를 재개할 수 있도록 정상적으로 종료합니다. [거부 및 확인 규칙](/docs/ko/permissions#manage-permissions)은 훅이 무엇을 반환하든 여전히 평가됩니다 |

1943| `permissionDecisionReason` | `"allow"` 및 `"ask"`의 경우 사용자에게 표시되지만 Claude에는 표시되지 않습니다. `"deny"`의 경우 Claude에 표시됩니다. `"defer"`의 경우 무시됩니다 |1942| `permissionDecisionReason` | `"ask"`의 경우 Claude가 아닌 사용자에게 표시됩니다. `"deny"`의 경우 Claude에게 표시됩니다. `"allow"`와 `"defer"`의 경우 [디버그 로그](#debug-hooks)에만 기록됩니다 |

1944| `updatedInput` | 실행 전에 도구의 입력 매개변수를 수정합니다. 전체 입력 객체를 바꾸므로 변경되지 않은 필드를 수정된 필드와 함께 포함합니다. Claude Code는 권한 규칙과 Bash 명령의 [자동 백그라운드 적격성](/docs/ko/tools-reference#background-commands)을 hook이 반환하는 입력에 대해 평가합니다 (Claude가 보낸 입력이 아님). `"allow"`와 결합하여 자동 승인하거나 `"ask"`와 결합하여 수정된 입력을 사용자에게 표시합니다. `"defer"`의 경우 무시됩니다 |1943| `updatedInput` | 실행 전에 도구의 입력 매개변수를 수정합니다. 입력 객체 전체를 대체하므로 수정된 필드와 함께 변경되지 않은 필드도 포함해야 합니다. Claude Code는 Claude가 보낸 입력이 아니라 훅이 반환한 입력에 대해 권한 규칙과 Bash 명령의 [자동 백그라운드 적격성](/docs/ko/tools-reference#foreground-commands-that-move-to-the-background)을 평가합니다. 자동 승인하려면 `"allow"`와, 수정된 입력을 사용자에게 보여 주려면 `"ask"`와 함께 사용합니다. `"defer"`에서는 무시됩니다 |

1945| `additionalContext` | 도구 결과와 함께 Claude의 컨텍스트에 추가되는 문자열. `"defer"`의 경우 무시됩니다. [Claude를 위한 컨텍스트 추가](#add-context-for-claude)를 참조하세요 |1944| `additionalContext` | 도구 결과와 함께 Claude의 컨텍스트에 추가되는 문자열입니다. `permissionDecision`이 `"defer"`이면 무시됩니다. [Claude를 위한 컨텍스트 추가](#add-context-for-claude)를 참조하십시오 |

1946 1945

1947여러 PreToolUse hook이 다른 결정을 반환할 때 우선순위는 `deny` > `defer` > `ask` > `allow`입니다.1946여러 PreToolUse 훅이 서로 다른 결정을 반환하면 우선순위는 `deny` > `defer` > `ask` > `allow`입니다.

1948 1947

1949종료 코드 2로 차단하는 hook은 `"deny"`와 동일한 방식으로 라우팅됩니다: Claude는 stderr 메시지를 거부 이유로 봅니다.1948종료 코드 2로 차단하는 훅은 `"deny"`와 같은 방식으로 전달됩니다. Claude는 stderr 메시지를 거부 이유로 봅니다.

1950 1949

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

1952 1951

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

1954 1953

1955```json theme={null}1954```json theme={null}

1956{1955{

1968 1967

1969<span id="allow-with-updatedinput" />1968<span id="allow-with-updatedinput" />

1970 1969

1971[비대화형 모드](/docs/ko/headless)에서 `-p` 플래그를 사용하면 Claude Code는 `AskUserQuestion` 및 `ExitPlanMode`를 실행에 [권한 호스트](/docs/ko/headless#turn-off-permission-prompts-in-unattended-runs)가 있을 때만 제공합니다 (예: Agent SDK `canUseTool` callback). 이 도구는 사용자 상호 작용이 필요합니다. `permissionDecision: "allow"`를 `updatedInput`과 함께 반환하면 해당 요구 사항을 충족합니다: hook은 stdin에서 도구의 입력을 읽고 자신의 UI를 통해 답변을 수집하고 `updatedInput`에서 반환하여 도구가 프롬프트 없이 실행되도록 합니다. `"allow"`만 반환하는 것은 이러한 도구에 충분하지 않습니다. `AskUserQuestion`의 경우 원본 `questions` 배열을 에코백하고 각 질문의 텍스트를 선택한 답변으로 매핑하는 [`answers`](#askuserquestion) 객체를 추가합니다.1970`-p` 플래그를 사용하는 [비대화형 모드](/docs/ko/headless)에서 Claude Code는 Agent SDK `canUseTool` 콜백처럼 프롬프트를 받을 [권한 호스트](/docs/ko/headless#turn-off-permission-prompts-in-unattended-runs)가 실행에 있을 때만 `AskUserQuestion`과 `ExitPlanMode`를 제공합니다. 이 도구들은 사용자 상호 작용이 필요합니다. `permissionDecision: "allow"`와 `updatedInput`을 함께 반환하면 이 요구 사항이 충족됩니다. 훅은 stdin에서 도구의 입력을 읽고, 자체 UI를 통해 답변을 수집한 다음, `updatedInput`으로 반환하여 도구가 프롬프트 없이 실행되도록 합니다. 이 도구들에는 `"allow"`만 반환하는 것으로는 충분하지 않습니다. `AskUserQuestion`의 경우 원본 `questions` 배열을 그대로 돌려주고, 각 질문의 텍스트를 선택된 답변에 매핑하는 [`answers`](#askuserquestion) 객체를 추가합니다.

1972 1971

1973v2.1.199부터 [`_meta["anthropic/requiresUserInteraction"]`](/docs/ko/mcp#require-approval-for-a-specific-tool)로 표시된 MCP 도구는 더 엄격합니다: hook은 `updatedInput`이 있거나 없이 `"allow"`로 승인 프롬프트를 건너뛸 수 없습니다. Claude Code는 hook이 도구가 필요한 상호 작용을 수집했는지 확인할 수 없기 때문입니다.1972v2.1.199부터 서버가 [`_meta["anthropic/requiresUserInteraction"]`](/docs/ko/mcp#require-approval-for-a-specific-tool)으로 표시한 MCP 도구는 더 엄격합니다. Claude Code는 훅이 도구에 필요한 상호 작용을 수집했는지 확인할 수 없으므로, 훅은 `updatedInput` 유무와 관계없이 `"allow"`로 승인 프롬프트를 건너뛸 수 없습니다.

1974 1973

1975<Note>1974<Note>

1976 PreToolUse는 이전에 최상위 `decision` 및 `reason` 필드를 사용했지만 이 이벤트에는 더 이상 사용되지 않습니다. 대신 `hookSpecificOutput.permissionDecision` 및 `hookSpecificOutput.permissionDecisionReason`을 사용합니다. 더 이상 사용되지 않는 값 `"approve"` 및 `"block"`은 각각 `"allow"` 및 `"deny"`로 매핑됩니다. PostToolUse 및 Stop과 같은 다른 이벤트는 계속 최상위 `decision` 및 `reason`을 현재 형식으로 사용합니다.1975 PreToolUse는 이전에 최상위 `decision` 및 `reason` 필드를 사용했지만, 이 이벤트에서는 deprecated되었습니다. 대신 `hookSpecificOutput.permissionDecision`과 `hookSpecificOutput.permissionDecisionReason`을 사용합니다. deprecated된 값 `"approve"`와 `"block"`은 각각 `"allow"`와 `"deny"`에 매핑됩니다. PostToolUse와 Stop 같은 다른 이벤트는 현재 형식으로 최상위 `decision`과 `reason`을 계속 사용합니다.

1977</Note>1976</Note>

1978 1977

1979<h4 id="defer-a-tool-call-for-later">1978<h4 id="defer-a-tool-call-for-later">

1980 도구 호출을 나중에 재개하도록 연기1979 나중을 위해 도구 호출 지연

1981</h4>1980</h4>

1982 1981

1983`"defer"`는 Claude Code를 subprocess로 실행하고 JSON 출력을 읽는 Agent SDK 앱 또는 Claude Code 위에 구축된 사용자 정의 UI와 같은 통합을 위한 것입니다. 이를 통해 호출 프로세스가 Claude를 도구 호출에서 일시 중지하고 자신의 인터페이스를 통해 입력을 수집하고 중단된 위치에서 재개할 수 있습니다. Claude Code는 [비대화형 모드](/docs/ko/headless)에서 `-p` 플래그를 사용할 때만 이 값을 준수합니다. 대화형 세션에서는 경고를 기록하고 hook 결과를 무시합니다.1982`"defer"`는 Agent SDK 앱이나 Claude Code 위에 구축된 사용자 지정 UI처럼 `claude -p`를 하위 프로세스로 실행하고 JSON 출력을 읽는 통합을 위한 것입니다. 이를 통해 호출 프로세스는 도구 호출 시점에서 Claude를 일시 중지하고, 자체 인터페이스를 통해 입력을 수집한 다음, 중단된 지점에서 재개할 수 있습니다. Claude Code는 `-p` 플래그를 사용하는 [비대화형 모드](/docs/ko/headless)에서만 이 값을 존중합니다. 대화형 세션에서는 경고를 로그에 기록하고 훅 결과를 무시합니다.

1984 1983

1985일반적인 경우는 `AskUserQuestion` 도구입니다: Claude가 사용자에게 뭔가를 묻고 싶지만 답변할 터미널이 없습니다. `-p` 실행은 [권한 호스트](/docs/ko/headless#turn-off-permission-prompts-in-unattended-runs)가 있을 때만 `AskUserQuestion`을 제공합니다 (예: `--permission-prompt-tool`으로 전달하는 MCP 도구). 왕복은 다음과 같이 작동합니다:1984`AskUserQuestion` 도구가 대표적인 사례입니다. Claude는 사용자에게 무언가를 묻고 싶지만 답할 터미널이 없습니다. `-p` 실행은 `--permission-prompt-tool`로 전달하는 MCP 도구 같은 [권한 호스트](/docs/ko/headless#turn-off-permission-prompts-in-unattended-runs)가 있을 때만 `AskUserQuestion`을 제공하므로, 권한 호스트와 함께 실행을 시작해야 합니다. 왕복 과정은 다음과 같습니다.

1986 1985

19871. Claude가 `AskUserQuestion`을 호출합니다. `PreToolUse` hook이 발생합니다.19861. Claude가 `AskUserQuestion`을 호출합니다. `PreToolUse` 훅이 발생합니다.

19882. hook이 `permissionDecision: "defer"`를 반환합니다. 도구가 실행되지 않습니다. 프로세스는 `stop_reason: "tool_deferred"`로 종료되고 보류 중인 도구 호출이 트랜스크립트에 유지됩니다.19872. 훅이 `permissionDecision: "defer"`를 반환합니다. 도구는 실행되지 않습니다. 프로세스는 `stop_reason: "tool_deferred"`로 종료되며, 보류 중인 도구 호출은 트랜스크립트에 보존됩니다.

19893. 호출 프로세스는 SDK 결과에서 `deferred_tool_use`를 읽고 자신의 UI에서 질문을 표시하고 답변을 기다립니다.19883. 호출 프로세스는 SDK 결과에서 `deferred_tool_use`를 읽고, 자체 UI에 질문을 표시한 다음, 답변을 기다립니다.

19904. 호출 프로세스는 동일한 권한 호스트와 함께 `claude -p --resume <session-id>`를 실행합니다. 동일한 도구 호출이 `PreToolUse`를 다시 발생시킵니다.19894. 호출 프로세스는 같은 권한 호스트로 `claude -p --resume <session-id>`를 실행합니다. 같은 도구 호출이 다시 `PreToolUse`를 발생시킵니다.

19915. hook이 `permissionDecision: "allow"`를 `updatedInput`의 답변과 함께 반환합니다. 도구가 실행되고 Claude가 계속됩니다.19905. 훅이 `updatedInput`에 답변을 담아 `permissionDecision: "allow"`를 반환합니다. 도구가 실행되고 Claude가 계속합니다.

1992 1991

1993`deferred_tool_use` 필드는 도구의 `id`, `name`, `input`을 전달합니다. `input`은 실행 전에 캡처된 도구 호출을 위해 Claude가 생성한 매개변수입니다:1992`deferred_tool_use` 필드에는 도구의 `id`, `name`, `input`이 담깁니다. `input`은 Claude가 도구 호출을 위해 생성한 매개변수로, 실행 전에 캡처됩니다.

1994 1993

1995```json theme={null}1994```json theme={null}

1996{1995{

2006}2005}

2007```2006```

2008 2007

2009시간 초과 또는 재시도 제한이 없습니다. 세션은 재개할 때까지 디스크에 유지됩니다 ([retention sweep 규칙](/docs/ko/claude-directory#cleaned-up-automatically)에 따라 [`cleanupPeriodDays`](/docs/ko/settings-reference#cleanupperioddays) 보존 스윕에 의해 30일 후 기본적으로 삭제됨). 재개할 때 답변이 준비되지 않으면 hook이 `"defer"`를 다시 반환할 수 있고 프로세스는 동일한 방식으로 종료됩니다. 호출 프로세스는 결국 `"allow"` 또는 `"deny"`를 반환하여 루프를 끝낼 시기를 제어합니다.2008타임아웃이나 재시도 제한은 없습니다. 세션은 재개할 때까지 디스크에 남아 있으며, [보존 정리 규칙](/docs/ko/claude-directory#cleaned-up-automatically)에 따라 기본적으로 30일 후 세션 파일을 삭제하는 [`cleanupPeriodDays`](/docs/ko/settings-reference#cleanupperioddays) 보존 정리의 적용을 받습니다. 재개할 때 답변이 준비되지 않았다면 훅은 다시 `"defer"`를 반환할 수 있으며, 프로세스는 같은 방식으로 종료됩니다. 호출 프로세스는 결국 훅에서 `"allow"` 또는 `"deny"`를 반환하여 루프를 끝낼 시점을 제어합니다.

2010 2009

2011`"defer"`는 Claude가 한 번에 단일 도구 호출을 만들 때만 작동합니다. Claude가 여러 도구 호출을 한 번에 만들면 `"defer"`는 경고와 함께 무시되고 도구는 일반 권한 흐름을 통해 진행됩니다. 제약이 존재하는 이유는 재개가 하나의 도구만 다시 실행할 수 있기 때문입니다: 다른 도구를 미해결 상태로 두지 않고 배치에서 하나의 호출을 연기할 방법이 없습니다.2010`"defer"`는 Claude가 턴에서 단일 도구 호출을 할 때만 작동합니다. Claude가 한 번에 여러 도구 호출을 하면 `"defer"`는 경고와 함께 무시되고 도구는 일반 권한 흐름을 통해 진행됩니다. 이 제약은 재개 시 하나의 도구만 다시 실행할 수 있기 때문에 존재합니다. 배치에서 하나의 호출을 지연하면서 나머지를 해결되지 않은 상태로 두지 않을 방법이 없습니다.

2012 2011

2013연기된 도구가 재개할 때 더 이상 사용 가능하지 않으면 프로세스는 `stop_reason: "tool_deferred_unavailable"`과 `is_error: true`로 종료되고 hook이 발생하기 전에 종료됩니다. 이는 도구를 제공한 MCP 서버가 재개된 세션에 연결되지 않을 때 발생합니다. `deferred_tool_use` 페이로드는 여전히 포함되므로 어느 도구가 누락되었는지 식별할 수 있습니다.2012재개할 때 지연된 도구를 더 이상 사용할 수 없으면 프로세스는 훅이 발생하기 전에 `stop_reason: "tool_deferred_unavailable"` 및 `is_error: true`로 종료됩니다. 이는 도구를 제공한 MCP 서버가 재개된 세션에 연결되어 있지 않을 때 발생합니다. `deferred_tool_use` 페이로드는 여전히 포함되므로 어떤 도구가 없어졌는지 식별할 수 있습니다.

2014 2013

2015<Note>2014<Note>

2016 plan 모드에서 연기된 세션을 재개하려면 [`--permission-prompt-tool`](/docs/ko/cli-reference#cli-flags)을 `--resume`과 함께 전달하여 Claude Code가 승인을 위해 계획을 제시할 수 있도록 합니다. 없으면 Claude Code는 plan 모드를 복원하지 않습니다. Claude Code v2.1.246 이상이 필요합니다.2015 플랜 모드에서 지연된 세션을 재개하려면 Claude Code가 승인을 위해 계획을 제시할 수 있도록 `--resume`과 함께 [`--permission-prompt-tool`](/docs/ko/cli-reference#cli-flags)을 전달합니다. 특정 다른 실행 플래그를 전달하면 재개된 실행이 플랜 모드로 돌아가지 않습니다. [`-p`로 플랜 모드에서 재개](/docs/ko/sessions#resume-in-plan-mode-with-p)를 참조하십시오. Claude Code v2.1.246 이상이 필요합니다.

2017 2016

2018 `-p`로 재개할 때 Claude Code는 저장된 다른 권한 모드를 복원하지 않습니다. 새 `claude -p` 실행이 시작할 권한 모드로 실행을 시작하므로 연기된 세션이 사용한 경우 `--permission-mode` 또는 `--dangerously-skip-permissions`를 다시 전달합니다. `claude --resume <session-id>`로 `-p` 없이 재개할 때 Claude Code는 [재개 시 권한 모드](/docs/ko/sessions#permission-mode-on-resume)에 나열된 예외를 제외하고 저장된 권한 모드를 복원합니다.2017 `-p`로 재개하면 Claude Code는 다른 저장된 권한 모드를 복원하지 않습니다. 새 `claude -p` 실행이 시작할 권한 모드로 실행을 시작하므로, 지연된 세션이 `--permission-mode` 또는 `--dangerously-skip-permissions`를 사용했다면 다시 전달해야 합니다. `-p` 없이 `claude --resume <session-id>`로 재개하면 Claude Code는 [재개 시 권한 모드](/docs/ko/sessions#permission-mode-on-resume)에 나열된 예외를 제외하고 저장된 권한 모드를 복원합니다.

2019</Note>2018</Note>

2020 2019

2021<h3 id="permissionrequest">2020<h3 id="permissionrequest">

2022 PermissionRequest2021 PermissionRequest

2023</h3>2022</h3>

2024 2023

2025Claude Code가 도구 사용 권한을 요청하려고 할 때 실행됩니다. [비대화형 모드](/docs/ko/headless)의 백그라운드 서브에이전트처럼 프롬프트를 표시할 수 없는 세션에서도 Claude Code는 이 hook을 실행하며, 어떤 hook도 결정을 반환하지 않으면 도구 호출을 거부합니다. [PermissionRequest 결정 제어](#permissionrequest-decision-control)를 사용하여 사용자를 대신하여 허용하거나 거부합니다.2024Claude Code가 도구 사용 권한을 요청하려고 할 때 실행됩니다. [비대화형 모드](/docs/ko/headless)의 백그라운드 서브에이전트처럼 프롬프트를 표시할 수 없는 세션에서도 Claude Code는 이 훅을 실행하며, 어떤 훅도 결정을 반환하지 않으면 도구 호출을 거부합니다.

2025사용자를 대신하여 허용하거나 거부하려면 [PermissionRequest 결정 제어](#permissionrequest-decision-control)를 사용합니다.

2026 2026

2027Claude가 도구 사용 권한을 요청하는 순간 신호가 필요할 때 이 이벤트를 사용합니다. Claude Code는 프롬프트가 약 6초 동안 기다린 후에야 `permission_prompt` 유형의 [Notification](#notification) hook을 실행합니다.2027Claude가 도구 사용 권한을 요청하는 순간에 신호가 필요할 때 이 이벤트를 사용합니다. Claude Code는 프롬프트가 약 6초 동안 대기한 후에만 `permission_prompt` 유형의 [Notification](#notification) 훅을 실행합니다.

2028 2028

2029Claude Code는 샌드박스 명령의 [네트워크 요청](/docs/ko/sandboxing#network-isolation)에 대해서는 PermissionRequest hook을 실행하지 않습니다. 해당 프롬프트에 대한 신호를 받으려면 `permission_prompt` 알림 유형을 사용합니다.2029Claude Code는 샌드박스 처리된 명령의 [네트워크 요청](/docs/ko/sandboxing#network-isolation)에 대해서는 PermissionRequest 훅을 실행하지 않습니다. 해당 프롬프트에 대한 신호를 받으려면 `permission_prompt` 알림 유형을 사용합니다.

2030 2030

2031도구 이름에서 일치합니다. PreToolUse와 동일한 값입니다.2031PreToolUse와 같은 값으로 도구 이름에 대해 일치시킵니다.

2032 2032

2033<h4 id="permissionrequest-input">2033<h4 id="permissionrequest-input">

2034 PermissionRequest 입력2034 PermissionRequest 입력

2035</h4>2035</h4>

2036 2036

2037PermissionRequest hook은 PreToolUse hook과 같은 `tool_name` 및 `tool_input` 필드를 받지만 `tool_use_id`는 없습니다. MCP 도구의 경우 [`mcp_server`](#pretooluse-input) 객체도 받습니다. 선택적 `permission_suggestions` 배열에는 Claude Code가 이 요청에 대해 제안하는 [권한 업데이트](#permission-update-entries) (예: 허용 규칙 추가 또는 권한 모드 변경)가 포함됩니다.2037PermissionRequest 훅은 PreToolUse 훅처럼 `tool_name`과 `tool_input` 필드를 받지만 `tool_use_id`는 받지 않습니다. MCP 도구의 경우 [`mcp_server`](#pretooluse-input) 객체도 받습니다. 선택적 `permission_suggestions` 배열에는 허용 규칙 추가나 권한 모드 변경처럼 Claude Code가 이 요청에 대해 제안하는 [권한 업데이트](#permission-update-entries)가 담깁니다.

2038 2038

2039`permission_suggestions` 배열은 권한 대화 상자에서 보는 옵션의 정확한 목록이 아닙니다. 각 권한 대화 상자는 자신의 옵션을 구축하기 때문입니다. 파일 편집과 같은 일부 대화 상자는 배열을 읽지 않고 요청 자체에서 옵션을 파생합니다. 배열을 읽는 대화 상자는 여전히 [`allowManagedPermissionRulesOnly`](/docs/ko/settings-reference#allowmanagedpermissionrulesonly)가 규칙 저장 옵션을 숨길 때와 같이 배열에 제안이 있는 옵션을 보류할 수 있습니다. 또한 제안 항목이 없는 옵션을 제공할 수 있습니다 (예: [**Yes, and switch to auto mode**](/docs/ko/permission-modes#switch-permission-modes), 권한 업데이트를 통하지 않고 권한 모드를 직접 변경하는 것).2039각 권한 대화 상자는 자체 옵션을 구성하므로 `permission_suggestions` 배열은 사용자에게 표시되는 옵션의 정확한 목록이 아닙니다. 파일 편집용 대화 상자처럼 일부 대화 상자는 배열을 전혀 읽지 않고 요청 자체에서 옵션을 도출합니다. 배열을 읽는 대화 상자도 제안이 배열에 남아 있는 옵션을 보류할 수 있습니다. 예를 들어 [`allowManagedPermissionRulesOnly`](/docs/ko/settings-reference#allowmanagedpermissionrulesonly)가 규칙 저장 옵션을 숨기는 경우입니다. 또한 권한 업데이트를 통하지 않고 권한 모드를 직접 변경하는 [**Yes, and switch to auto mode**](/docs/ko/permission-modes#switch-permission-modes)처럼 제안 항목이 없는 옵션을 제공할 수도 있습니다.

2040 2040

2041PreToolUse hook은 권한 상태와 관계없이 모든 도구 호출 전에 실행됩니다. PermissionRequest hook은 Claude Code가 권한을 요청하려고 할 때만 실행되거나 프롬프트할 수 없는 경우 자동 거부할 때만 실행됩니다. 둘 다 [`EndConversation`](/docs/ko/tools-reference#endconversation-tool-behavior)에 대해 발생하지 않습니다.2041PreToolUse 훅은 권한이 필요한지 여부와 관계없이 모든 도구 호출 전에 실행됩니다. PermissionRequest 훅은 Claude Code가 권한을 요청하려고 할 때, 또는 프롬프트를 표시할 수 없는 호출을 자동 거부하려고 할 때만 실행됩니다. 두 이벤트 모두 [`EndConversation`](/docs/ko/tools-reference#endconversation-tool-behavior)에서는 발생하지 않습니다.

2042 2042

2043```json theme={null}2043```json theme={null}

2044{2044{

2067 PermissionRequest 결정 제어2067 PermissionRequest 결정 제어

2068</h4>2068</h4>

2069 2069

2070`PermissionRequest` hook은 권한 요청을 허용하거나 거부할 수 있습니다. 모든 hook에 사용 가능한 [JSON 출력 필드](#json-output) 외에도 hook 스크립트는 이러한 이벤트 특정 필드가 있는 `decision` 객체를 반환할 수 있습니다:2070`PermissionRequest` 훅은 권한 요청을 허용하거나 거부할 수 있습니다. 모든 훅에서 사용할 수 있는 [JSON 출력 필드](#json-output) 외에도 훅 스크립트는 다음 이벤트별 필드가 있는 `decision` 객체를 반환할 수 있습니다.

2071 2071

2072| 필드 | 설명 |2072| 필드 | 설명 |

2073| :- | :- |2073| :- | :- |

2074| `behavior` | `"allow"`는 권한을 부여하고, `"deny"`는 거부합니다. [거부 및 요청 규칙](/docs/ko/permissions#manage-permissions)은 여전히 평가되므로 hook이 `"allow"`를 반환해도 일치하는 거부 규칙을 재정의하지 않습니다 |2074| `behavior` | `"allow"`는 권한을 부여하고, `"deny"`는 거부합니다. [거부 및 확인 규칙](/docs/ko/permissions#manage-permissions)은 여전히 평가되므로, `"allow"`를 반환하는 훅이 일치하는 거부 규칙을 재정의하지는 않습니다 |

2075| `updatedInput` | `"allow"`만 해당: 실행 전에 도구의 입력 매개변수를 수정합니다. 전체 입력 객체를 바꾸므로 변경되지 않은 필드를 수정된 필드와 함께 포함합니다. 수정된 입력은 거부 및 요청 규칙에 대해 다시 평가됩니다 |2075| `updatedInput` | `"allow"` 전용: 실행 전에 도구의 입력 매개변수를 수정합니다. 입력 객체 전체를 대체하므로 수정된 필드와 함께 변경되지 않은 필드도 포함해야 합니다. 수정된 입력은 거부 및 확인 규칙에 대해 다시 평가됩니다 |

2079 2079

2080`decision` 객체 없이 종료 코드 2로 종료하는 hook은 권한 흐름을 변경하지 않으며, 해당 stderr은 삭제됩니다. `decision` 객체만 요청을 허용하거나 거부할 수 있습니다.2080`decision` 객체 없이 종료 코드 2로 종료하는 훅은 권한 흐름을 변경하지 않으며, stderr는 버려집니다. `decision` 객체만 요청을 허용하거나 거부할 수 있습니다.

2081 2081

2082```json theme={null}2082```json theme={null}

2083{2083{

2097 권한 업데이트 항목2097 권한 업데이트 항목

2098</h4>2098</h4>

2099 2099

2100`updatedPermissions` 출력 필드와 [`permission_suggestions` 입력 필드](#permissionrequest-input) 모두 동일한 항목 객체 배열을 사용합니다. 각 항목에는 다른 필드를 결정하는 `type`과 변경이 작성되는 위치를 제어하는 `destination`이 있습니다.2100`updatedPermissions` 출력 필드와 [`permission_suggestions` 입력 필드](#permissionrequest-input)는 모두 같은 항목 객체 배열을 사용합니다. 각 항목에는 다른 필드를 결정하는 `type`과 변경 사항이 기록되는 위치를 제어하는 `destination`이 있습니다.

2101 2101

2102| `type` | 필드 | 효과 |2102| `type` | 필드 | 효과 |

2103| :- | :- | :- |2103| :- | :- | :- |

2104| `addRules` | `rules`, `behavior`, `destination` | 권한 규칙을 추가합니다. `rules`는 `{toolName, ruleContent?}` 객체의 배열입니다. 전체 도구와 일치하려면 `ruleContent`를 생략합니다. `behavior`는 `"allow"`, `"deny"` 또는 `"ask"`입니다 |2104| `addRules` | `rules`, `behavior`, `destination` | 권한 규칙을 추가합니다. `rules`는 `{toolName, ruleContent?}` 객체의 배열입니다. 도구 전체와 일치시키려면 `ruleContent`를 생략합니다. `behavior`는 `"allow"`, `"deny"` 또는 `"ask"`입니다 |

2107| `setMode` | `mode`, `destination` | 권한 모드를 변경합니다. 유효한 모드는 `default`, `auto`, `acceptEdits`, `dontAsk`, `bypassPermissions`, `plan`, `manual` (기본값의 별칭)입니다. `manual` 별칭은 Claude Code v2.1.200 이상이 필요합니다 |2107| `setMode` | `mode`, `destination` | 권한 모드를 변경합니다. 유효한 모드는 `default`, `auto`, `acceptEdits`, `dontAsk`, `bypassPermissions`, `plan`, 그리고 `default`의 별칭인 `manual`입니다. `manual` 별칭은 Claude Code v2.1.200 이상이 필요합니다 |

2110 2110

2111<Note>2111<Note>

2112 `setMode`와 `bypassPermissions`는 세션이 이미 bypass 모드를 사용 가능하게 시작된 경우에만 적용됩니다: `--dangerously-skip-permissions`, `--permission-mode bypassPermissions`, `--allow-dangerously-skip-permissions`, 또는 [사용자, `--settings`, 또는 관리형 설정](/docs/ko/settings-reference#permissions-defaultmode)의 `permissions.defaultMode: "bypassPermissions"`. 그렇지 않으면 업데이트는 작동하지 않습니다. [`permissions.disableBypassPermissionsMode`](/docs/ko/permissions#managed-settings)가 모드를 비활성화하거나 세션이 [제한된 모드](/docs/ko/cli-reference#cli-flags)로 시작될 때도 업데이트는 작동하지 않습니다.2112 `bypassPermissions`를 지정한 `setMode`는 bypass 모드를 이미 사용할 수 있는 상태로 세션을 시작한 경우에만 적용됩니다. 즉, `--dangerously-skip-permissions`, `--permission-mode bypassPermissions`, `--allow-dangerously-skip-permissions`를 사용했거나 [사용자, `--settings` 또는 관리형 설정](/docs/ko/settings-reference#permissions-defaultmode)에 `permissions.defaultMode: "bypassPermissions"`가 지정되어 있어야 합니다. 그렇지 않으면 이 업데이트는 아무 효과가 없습니다. [`permissions.disableBypassPermissionsMode`](/docs/ko/permissions#managed-settings)가 이 모드를 비활성화한 경우나 세션이 [제한 모드](/docs/ko/cli-reference#cli-flags)로 시작된 경우에도 업데이트는 아무 효과가 없습니다.

2113 2113

2114 `bypassPermissions`는 `destination`과 관계없이 `defaultMode`로 절대 유지되지 않습니다.2114 `bypassPermissions`는 `destination`과 관계없이 `defaultMode`로 저장되지 않습니다.

2115</Note>2115</Note>

2116 2116

2117모든 항목의 `destination` 필드는 변경이 메모리에만 유지되는지 또는 설정 파일에 유지되는지를 결정합니다.2117모든 항목의 `destination` 필드는 변경 사항을 메모리에만 유지할지 설정 파일에 저장할지를 결정합니다.

2118 2118

2120| :- | :- |2120| :- | :- |

2125 2125

2126hook은 받은 `permission_suggestions` 중 하나를 자신의 `updatedPermissions` 출력으로 에코할 수 있으며, 이는 사용자가 대화 상자에서 해당 옵션을 선택하는 것과 동등합니다.2126훅은 전달받은 `permission_suggestions` 중 하나를 그대로 자신의 `updatedPermissions` 출력으로 반환할 수 있습니다.

2127 2127

2128<h3 id="posttooluse">2128<h3 id="posttooluse">

2129 PostToolUse2129 PostToolUse

2130</h3>2130</h3>

2131 2131

2132도구가 성공적으로 완료된 직후 실행됩니다.2132도구가 성공적으로 완료된 직후에 실행됩니다.

2133 2133

2134도구 이름에서 일치합니다. PreToolUse와 동일한 값입니다.2134도구 이름으로 매칭하며, 값은 PreToolUse와 같습니다.

2135 2135

2136더 광범위하게 일치할 때 도구 이름이 올바른 필터가 아닙니다:2136도구 이름이 적절한 필터가 아닐 때는 더 넓게 매칭할 수 있습니다.

2137 2137

2138* 모든 도구가 성공적으로 완료된 후 hook을 실행하려면 `matcher`를 생략하거나 `"*"`로 설정합니다. Hook은 `git status --porcelain`을 실행하여 변경된 내용을 자체적으로 발견할 수 있으며, 이는 `git diff`가 놓치는 추적되지 않은 파일도 나열합니다. 도구 호출이 실패하는 경우 [PostToolUseFailure](#posttoolusefailure)에 동일한 hook을 추가합니다.2138* 어떤 도구든 성공적으로 완료된 후에 훅을 실행하려면 `matcher`를 생략하거나 `"*"`로 설정합니다. 그러면 훅이 무엇이 변경되었는지 직접 파악할 수 있습니다. 예를 들어 `git status --porcelain`을 실행하면 `git diff`가 놓치는 추적되지 않은 파일도 함께 나열됩니다. 실패한 도구 호출의 경우 같은 훅을 [PostToolUseFailure](#posttoolusefailure) 아래에 추가합니다.

2139* 특정 파일이 변경될 때 hook을 실행하려면 (어떤 것이 작성했든) [FileChanged](#filechanged)를 사용합니다. Claude Code는 `Edit|Write`와 일치하는 `PostToolUse` hook을 실행하지 않습니다 (Bash 명령 또는 Claude Code 외부의 프로세스가 동일한 파일을 다시 작성할 때).2139* 무엇이 파일을 기록했는지와 관계없이 특정 파일이 디스크에서 변경될 때 훅을 실행하려면 [FileChanged](#filechanged)를 사용합니다. `Bash` 명령이나 Claude Code 외부의 프로세스가 같은 파일을 다시 쓰는 경우, Claude Code는 `Edit|Write`에 매칭되는 `PostToolUse` 훅을 실행하지 않습니다.

2140 2140

2141<h4 id="posttooluse-input">2141<h4 id="posttooluse-input">

2142 PostToolUse 입력2142 PostToolUse 입력

2143</h4>2143</h4>

2144 2144

2145`PostToolUse` hook은 도구가 이미 성공적으로 실행된 후에 발생합니다. 입력에는 도구에 전송된 인수인 `tool_input`과 반환한 결과인 `tool_response`가 모두 포함됩니다. 둘 다의 정확한 스키마는 도구에 따라 다릅니다. 파일 도구 `tool_input` 경로는 [PreToolUse](#pretooluse-input)와 동일한 형식으로 도착합니다: 항상 절대 경로, 플랫폼의 기본 구분 기호 포함 (Windows에서는 백슬래시). [MCP 도구](#match-mcp-tools)의 경우 입력은 또한 [`mcp_server`](#pretooluse-input) 객체를 전달합니다.2145`PostToolUse` 훅은 도구가 이미 성공적으로 실행된 후에 발생합니다. 입력에는 도구에 전송된 인수인 `tool_input`과 도구가 반환한 결과인 `tool_response`가 모두 포함됩니다. 두 필드의 정확한 스키마는 도구에 따라 다릅니다. 파일 도구의 `tool_input` 경로는 [PreToolUse](#pretooluse-input)와 같은 형식으로 전달됩니다. 즉, 항상 절대 경로이며 플랫폼 고유의 구분자를 사용하므로 Windows에서는 백슬래시가 사용됩니다. MCP 도구의 경우 입력에 [`mcp_server`](#pretooluse-input) 객체도 포함됩니다.

2146 2146

2147```json theme={null}2147```json theme={null}

2148{2148{

2167 2167

2168| 필드 | 설명 |2168| 필드 | 설명 |

2169| :- | :- |2169| :- | :- |

2171 2171

2172<h4 id="posttooluse-decision-control">2172<h4 id="posttooluse-decision-control">

2173 PostToolUse 결정 제어2173 PostToolUse 결정 제어

2174</h4>2174</h4>

2175 2175

2176`PostToolUse` hook은 도구 실행 후 Claude에 피드백을 제공할 수 있습니다. 모든 hook에 사용 가능한 [JSON 출력 필드](#json-output) 외에도 hook 스크립트는 이러한 이벤트 특정 필드를 반환할 수 있습니다:2176`PostToolUse` 훅은 도구 실행 후 Claude에게 피드백을 제공할 수 있습니다. 모든 훅에서 사용할 수 있는 [JSON 출력 필드](#json-output) 외에도 훅 스크립트는 다음과 같은 이벤트별 필드를 반환할 수 있습니다.

2177 2177

2178| 필드 | 설명 |2178| 필드 | 설명 |

2179| :- | :- |2179| :- | :- |

2183| `classifierContext` | [자동 모드](/docs/ko/permission-modes#eliminate-prompts-with-auto-mode) 분류기를 위한 이 호출 결과에 대한 짧은 메모 (Claude가 아닌). [자동 모드 분류기를 위한 결과 주석](#annotate-a-result-for-the-auto-mode-classifier)을 참조하세요. Claude Code v2.1.236 이상이 필요합니다 |2183| `classifierContext` | Claude가 아닌 [자동 모드](/docs/ko/permission-modes#eliminate-prompts-with-auto-mode) 분류기를 위한, 이 호출 결과에 대한 짧은 메모입니다. [자동 모드 분류기를 위한 결과 주석 달기](#annotate-a-result-for-the-auto-mode-classifier)를 참조하세요. Claude Code v2.1.236 이상이 필요합니다 |

2186 2186

2187아래 예제는 `Bash` 호출의 출력을 바꿉니다. 대체 값은 `Bash` 도구의 출력 형태와 일치합니다:2187아래 예시는 `Bash` 호출의 출력을 대체합니다. 대체 값은 `Bash` 도구의 출력 형태와 일치합니다.

2188 2188

2189```json theme={null}2189```json theme={null}

2190{2190{

2202```2202```

2203 2203

2204<Warning>2204<Warning>

2205 `updatedToolOutput`은 Claude가 보는 것만 변경합니다. 도구는 hook이 발생할 때까지 이미 실행되었으므로 작성된 파일, 실행된 명령 또는 전송된 네트워크 요청은 이미 적용되었습니다. OpenTelemetry 도구 span 및 분석 이벤트와 같은 원격 측정도 hook이 실행되기 전에 원본 출력을 캡처합니다. 도구 호출을 실행 전에 방지하거나 수정하려면 [PreToolUse](#pretooluse) hook을 대신 사용합니다.2205 `updatedToolOutput`은 Claude가 보는 내용만 변경합니다. 훅이 발생할 때는 도구가 이미 실행된 상태이므로, 기록된 파일, 실행된 명령, 전송된 네트워크 요청은 이미 효과가 발생한 상태입니다. OpenTelemetry 도구 스팬 및 분석 이벤트와 같은 텔레메트리도 훅이 실행되기 전에 원래 출력을 수집합니다. 도구 호출이 실행되기 전에 이를 막거나 수정하려면 대신 [PreToolUse](#pretooluse) 훅을 사용합니다.

2206 2206

2207 대체 값은 도구의 출력 형태와 일치해야 합니다. 기본 제공 도구는 일반 문자열이 아닌 구조화된 객체를 반환합니다. 예를 들어 `Bash`는 `stdout`, `stderr`, `interrupted`, `isImage` 필드가 있는 객체를 반환합니다. 기본 제공 도구의 경우 도구의 출력 스키마와 일치하지 않는 값은 무시되고 원본 출력이 사용됩니다. MCP 도구 출력은 스키마 검증 없이 통과됩니다. Claude가 필요한 오류 세부 정보를 제거하면 잘못된 가정으로 진행할 수 있습니다.2207 대체 값은 도구의 출력 형태와 일치해야 합니다. 기본 제공 도구는 일반 문자열이 아닌 구조화된 객체를 반환합니다. 예를 들어 `Bash`는 `stdout`, `stderr`, `interrupted`, `isImage` 필드가 있는 객체를 반환합니다. 기본 제공 도구의 경우 도구의 출력 스키마와 일치하지 않는 값은 무시되고 원래 출력이 사용됩니다. MCP 도구 출력은 스키마 검증 없이 그대로 전달됩니다. Claude에게 필요한 오류 세부 정보를 제거하면 Claude가 잘못된 가정에 따라 작업을 진행할 수 있습니다.

2208</Warning>2208</Warning>

2209 2209

2210<h4 id="annotate-a-result-for-the-auto-mode-classifier">2210<h4 id="annotate-a-result-for-the-auto-mode-classifier">

2211 자동 모드 분류기를 위한 결과 주석2211 자동 모드 분류기를 위한 결과 주석 달기

2212</h4>2212</h4>

2213 2213

2214`classifierContext`를 반환하여 Claude가 아닌 [자동 모드](/docs/ko/permission-modes#eliminate-prompts-with-auto-mode) 분류기에 도구 호출 결과에 대한 짧은 메모를 보냅니다. 분류기는 [도구 결과 자체를 절대 받지 않으므로](/docs/ko/permission-modes#how-the-classifier-evaluates-actions) 이 필드는 분류기에 호출이 반환한 내용을 알려주는 지원되는 방법입니다. 필드는 Claude Code v2.1.236 이상이 필요합니다.2214`classifierContext`를 반환하면 도구 호출 결과에 대한 짧은 메모를 Claude가 아닌 [자동 모드](/docs/ko/permission-modes#eliminate-prompts-with-auto-mode) 분류기에 전송합니다. 분류기는 [도구 결과 자체를 전달받지 않으므로](/docs/ko/permission-modes#how-the-classifier-evaluates-actions), 이 필드는 분류기가 이후 작업을 검토하기 전에 호출이 반환한 내용에 대해 알려 줄 수 있는 공식적인 방법입니다. 이 필드는 Claude Code v2.1.236 이상이 필요합니다.

2215 2215

2216아래 예제는 분류기에 쿼리의 출력이 어디에서 왔는지를 알립니다:2216아래 예시는 쿼리 출력의 출처를 분류기에 알려 줍니다.

2217 2217

2218```json theme={null}2218```json theme={null}

2219{2219{

2224}2224}

2225```2225```

2226 2226

2227분류기가 메모에 부여하는 가중치는 hook을 구성한 위치에 따라 다릅니다:2227분류기가 메모에 부여하는 가중치는 훅을 어디에서 구성했는지에 따라 달라집니다.

2228 2228

2229* **Claude Code에서 구성된 Hook**: 설정 파일, plugin, skill, 에이전트 frontmatter의 hook의 경우 분류기는 메모를 검증되지 않은 애플리케이션 제공 컨텍스트로 취급합니다. 메모는 사용자 의도를 절대 설정하지 않으며, 메모가 승인 또는 요청을 주장하면 분류기는 대화에서 해당 주장을 확인합니다2229* **Claude Code에서 구성한 훅**: 설정 파일, 플러그인, 스킬, 에이전트 frontmatter에서 온 훅의 경우, 분류기는 메모를 검증되지 않은 애플리케이션 제공 컨텍스트로 취급합니다. 메모는 사용자 의도를 확립하지 않으며, 메모에서 사용자가 무언가를 승인하거나 요청했다고 주장하는 경우 분류기는 대화에 있는 사용자의 실제 메시지와 대조하여 그 주장을 확인합니다

2230* **In-process Agent SDK callback**: 애플리케이션이 hook을 [TypeScript SDK callback](/docs/ko/agent-sdk/hooks)으로 등록하고 라이브 세션 중에 메모를 반환할 때 분류기는 메모에서 전달된 사용자 진술을 사용자 의도로 가중치를 부여할 수 있습니다. 그러한 진술은 분류기가 메시지에서 수락할 사용자 진술을 충족할 수 있지만 자신의 메시지가 들어올릴 수 없는 차단을 절대 들어올리지 않습니다. 세션이 재개된 후 Claude Code는 복원된 메모를 검증되지 않은 컨텍스트로 취급합니다. 두 그룹의 hook이 동일한 호출에 주석을 달 때 분류기는 결합된 메모를 검증되지 않은 것으로 취급합니다2230* **프로세스 내 Agent SDK 콜백**: Claude Code를 내장한 애플리케이션이 훅을 [TypeScript SDK 콜백](/docs/ko/agent-sdk/hooks)으로 등록하고 실행 중인 세션에서 메모를 반환하는 경우, 분류기는 메모에 전달된 사용자 발언을 사용자 의도로 고려할 수 있습니다. 이러한 발언은 분류기가 사용자가 보낸 메시지로부터 수용할 수 있는 동의 요건을 충족할 수 있지만, 사용자 자신의 메시지로도 해제할 수 없는 차단을 해제하지는 않습니다. 세션이 재개된 후에는 Claude Code가 복원된 메모를 검증되지 않은 컨텍스트로 취급합니다. 두 그룹의 훅이 같은 호출에 주석을 다는 경우, 분류기는 결합된 메모를 검증되지 않은 것으로 취급합니다

2231 2231

2232Claude Code는 메모를 전달할 때 이러한 제한을 적용합니다:2232Claude Code는 메모를 전달할 때 다음과 같은 제한을 적용합니다.

2233 2233

2234* **길이**: Claude Code는 한 도구 호출에 대한 메모를 2,000자로 제한하고 나머지를 자릅니다. 제한은 해당 호출에 응답하는 모든 hook에서 공유됩니다2234* **길이**: Claude Code는 하나의 도구 호출에 대한 메모를 2,000자로 제한하고 나머지는 잘라냅니다. 이 제한은 해당 호출에 응답하는 모든 훅이 공유합니다

2235* **동기 응답만**: Claude Code는 [백그라운드에서 실행되는](#run-hooks-in-the-background) hook의 응답에서 필드를 무시합니다 (해당 응답이 도구 결과를 기록한 후 도착하기 때문)2235* **동기 응답만 해당**: [백그라운드에서 실행되는](#run-hooks-in-the-background) 훅의 응답은 Claude Code가 도구 결과를 기록한 후에 도착하므로, Claude Code는 이러한 응답의 필드를 무시합니다

2236* **분류기가 기록하지 않는 호출**: 분류기의 트랜스크립트는 파일 읽기 및 검색과 같은 읽기 전용 조회를 생략합니다. Claude Code는 해당 호출에 첨부된 메모를 삭제합니다2236* **분류기가 기록하지 않는 호출**: 분류기의 트랜스크립트는 파일 읽기 및 검색과 같은 읽기 전용 조회를 생략합니다. Claude Code는 이러한 호출에 첨부된 메모를 삭제합니다

2237* **재작성과의 상호 작용**: 메모가 `updatedToolOutput`으로 바꾸는 출력을 설명할 때 두 필드를 동일한 hook 응답에서 반환합니다. Claude Code는 해당 재작성이 거부되거나 다른 hook의 재작성이 이를 대체할 때 메모를 삭제합니다. Claude Code는 재작성 없이 반환하는 메모를 전달합니다 (다른 hook의 재작성이 이를 대체하더라도)2237* **재작성과의 상호작용**: 메모가 `updatedToolOutput`으로 대체하는 출력을 설명하는 경우, 같은 훅 응답에서 두 필드를 모두 반환합니다. 해당 재작성이 거부되거나 다른 훅의 재작성이 이를 대체하면 Claude Code는 메모를 삭제합니다. 재작성 없이 반환한 메모는 다른 훅이 출력을 재작성하더라도 Claude Code가 전달합니다

2238 2238

2239<Warning>2239<Warning>

2240 분류기는 `classifierContext`에 배치하는 콘텐츠를 애플리케이션 호스팅 세션의 정보로 읽으므로 신뢰할 수 없는 도구 출력 또는 제3자 텍스트를 복사하지 마세요. 메모를 이 호출에 대한 짧은 주장 (예: 출처에 대한 사실 또는 이에 대한 사용자 진술)으로 유지합니다; 필드를 사용하여 관련 없는 메시지 또는 이벤트 스트림을 전달하지 마세요.2240 분류기는 `classifierContext`에 넣은 내용을 세션을 호스팅하는 애플리케이션이 제공한 정보로 읽으므로, 신뢰할 수 없는 도구 출력이나 제3자 텍스트를 이 필드에 복사하지 마세요. 메모는 출처에 대한 사실이나 해당 호출에 대한 사용자 발언처럼 이 호출 하나에 대한 짧은 주장으로 유지하고, 관련 없는 메시지나 일련의 이벤트를 전달하는 데 이 필드를 사용하지 마세요.

2241</Warning>2241</Warning>

2242 2242

2243<h3 id="posttoolusefailure">2243<h3 id="posttoolusefailure">

2244 PostToolUseFailure2244 PostToolUseFailure

2245</h3>2245</h3>

2246 2246

2247도구 실행이 실패할 때 실행됩니다: 도구가 오류를 throw하거나 MCP 도구가 오류 결과를 반환합니다. 이를 사용하여 실패를 기록하고, 경고를 보내거나, Claude에 수정 피드백을 제공합니다.2247실행을 시작한 도구가 실패할 때 실행됩니다. 즉, 도구에서 오류가 발생했거나 MCP 도구가 오류 결과를 반환한 경우입니다. 실패를 로그에 기록하거나, 알림을 보내거나, Claude에게 수정 피드백을 제공하는 데 사용합니다.

2248 2248

2249도구 이름에서 일치합니다. PreToolUse와 동일한 값입니다.2249도구 이름으로 매칭하며, 값은 PreToolUse와 같습니다.

2250 2250

2251<Note>2251<Note>

2252 이 이벤트는 실행 전에 거부된 도구 호출에 대해 발생하지 않습니다: 알 수 없는 도구 이름, 스키마 또는 도구 특정 검증에 실패한 입력, 또는 권한 거부. 검증 거부는 `tool_use_error` 결과로 반환되고 hook이 실행되기 전에 발생하므로 `PreToolUse` 또는 이 이벤트를 발생시키지 않습니다. 권한 거부는 `PreToolUse`를 발생시키지만 이 이벤트는 발생시키지 않습니다; [PermissionDenied](#permissiondenied)를 참조하세요.2252 이 이벤트는 실행 전에 거부된 도구 호출에서는 발생하지 않습니다. 여기에는 알 수 없는 도구 이름, 스키마 또는 도구별 검증에 실패한 입력, 권한 거부가 해당합니다. 검증 거부는 `tool_use_error` 결과로 반환되며 훅이 실행되기 전에 발생하므로 `PreToolUse`와 `PostToolUseFailure` 모두 발생하지 않습니다. 권한 거부는 `PreToolUse`를 발생시키지만 이 이벤트는 발생시키지 않습니다. [PermissionDenied](#permissiondenied)를 참조하세요.

2253</Note>2253</Note>

2254 2254

2255<h4 id="posttoolusefailure-input">2255<h4 id="posttoolusefailure-input">

2256 PostToolUseFailure 입력2256 PostToolUseFailure 입력

2257</h4>2257</h4>

2258 2258

2259PostToolUseFailure hook은 PostToolUse와 동일한 `tool_name` 및 `tool_input` 필드를 받으며, 오류 정보는 최상위 필드로 받습니다. MCP 도구의 경우 [`mcp_server`](#pretooluse-input) 객체도 받습니다. 예를 들어 실패한 `npm test` 명령은 다음을 전달할 수 있습니다:2259PostToolUseFailure 훅은 PostToolUse와 같은 `tool_name` 및 `tool_input` 필드와 함께 최상위 필드로 오류 정보를 전달받습니다. MCP 도구의 경우 [`mcp_server`](#pretooluse-input) 객체도 전달받습니다. 예를 들어 실패한 `npm test` 명령은 다음을 전달할 수 있습니다.

2260 2260

2261```json theme={null}2261```json theme={null}

2262{2262{

2279 2279

2280| 필드 | 설명 |2280| 필드 | 설명 |

2281| :- | :- |2281| :- | :- |

2283| `is_interrupt` | 선택적 부울. 실패가 도구가 보고한 오류가 아닌 중단으로 도달했을 때 true. 실행 중인 도구를 취소하면 이 hook이 발생하지 않습니다; 도구 결과는 중단 메시지를 전달합니다 |2283| `is_interrupt` | 선택적 boolean입니다. 실패가 도구가 보고한 오류가 아니라 중단(abort)으로 Claude Code에 도달한 경우 true입니다. 실행 중인 도구를 취소하는 경우에는 이 훅이 발생하지 않으며, 대신 도구 결과에 중단 메시지가 포함됩니다 |

2285 2285

2286`error` 문자열은 일반적으로 Claude가 실패한 도구의 결과로 받는 것과 동일한 텍스트입니다. 형식은 도구 및 실패에 따라 다릅니다. `tool_name`, `is_interrupt`, 첫 번째 줄 `Exit code N`에 hook을 키합니다; 나머지 문자열을 표시 텍스트로 취급하고 안정적인 형식이 아닙니다.2286`error` 문자열은 일반적으로 Claude가 실패한 도구의 결과로 받는 텍스트와 같습니다. 형식은 도구와 실패 유형에 따라 다릅니다. 훅은 `tool_name`, `is_interrupt`, 첫 줄의 `Exit code N`을 기준으로 동작하도록 작성하고, 문자열의 나머지 부분은 안정적인 형식이 아닌 표시용 텍스트로 취급합니다.

2287 2287

2288* Bash 및 PowerShell의 경우 실행되고 종료된 명령은 첫 번째 줄 `Exit code N`을 생성하고 명령이 생성한 모든 출력을 stdout과 stderr이 인터리브된 하나의 블록으로 생성합니다2288* Bash와 PowerShell의 경우, 실행된 후 종료된 명령은 첫 줄에 `Exit code N`을 생성하고, 그 뒤에 명령이 생성한 출력을 stdout과 stderr가 섞인 하나의 블록으로 생성합니다

2289* 페이로드는 또한 Claude Code가 셸 프로세스 자체를 시작할 수 없을 때와 같이 종료 코드 줄이 없는 베어 실패 메시지를 전달할 수 있습니다2289* Claude Code가 셸 프로세스 자체를 시작할 수 없었던 경우, 페이로드에 종료 코드 줄 없이 실패 메시지만 포함될 수도 있습니다

2290* Claude Code는 `... [N characters truncated] ...` 마커 주위에 긴 문자열을 중간 자르고 `Command timed out after 2m 0s`와 같은 자신의 줄을 삽입할 수 있습니다2290* Claude Code는 긴 문자열의 중간 부분을 `... [N characters truncated] ...` 마커를 기준으로 잘라내며, `Command timed out after 2m 0s`와 같은 자체 줄을 삽입할 수 있습니다

2291 2291

2292<h4 id="posttoolusefailure-decision-control">2292<h4 id="posttoolusefailure-decision-control">

2293 PostToolUseFailure 결정 제어2293 PostToolUseFailure 결정 제어

2294</h4>2294</h4>

2295 2295

2296`PostToolUseFailure` hook은 도구 실패 후 Claude에 컨텍스트를 제공할 수 있습니다. 모든 hook에 사용 가능한 [JSON 출력 필드](#json-output) 외에도 hook 스크립트는 이러한 이벤트 특정 필드를 반환할 수 있습니다:2296`PostToolUseFailure` 훅은 도구 실패 후 Claude에게 컨텍스트를 제공할 수 있습니다. 모든 훅에서 사용할 수 있는 [JSON 출력 필드](#json-output) 외에도 훅 스크립트는 다음과 같은 이벤트별 필드를 반환할 수 있습니다.

2297 2297

2298| 필드 | 설명 |2298| 필드 | 설명 |

2299| :- | :- |2299| :- | :- |

2301 2301

2302```json theme={null}2302```json theme={null}

2303{2303{

2312 PostToolBatch2312 PostToolBatch

2313</h3>2313</h3>

2314 2314

2315배치의 모든 도구 호출이 해결된 후, Claude Code가 모델에 다음 요청을 보내기 전에 한 번 실행됩니다. `PostToolUse`는 도구당 한 번 발생하므로 Claude가 병렬 도구 호출을 만들 때 동시에 발생합니다. `PostToolBatch`는 전체 배치와 함께 정확히 한 번 발생하므로 단일 도구가 아닌 실행된 도구 집합에 따라 달라지는 컨텍스트를 주입하기에 적합한 위치입니다. 이 이벤트에는 matcher가 없습니다.2315배치의 모든 도구 호출이 처리된 후, Claude Code가 모델에 다음 요청을 보내기 전에 한 번 실행됩니다. `PostToolUse`는 도구마다 한 번씩 발생하므로, Claude가 병렬 도구 호출을 수행하면 동시에 발생합니다. `PostToolBatch`는 전체 배치에 대해 정확히 한 번 발생하므로, 단일 도구가 아닌 실행된 도구 집합에 따라 달라지는 컨텍스트를 주입하기에 적합한 위치입니다. 이 이벤트에는 matcher가 없습니다.

2316 2316

2317<h4 id="posttoolbatch-input">2317<h4 id="posttoolbatch-input">

2318 PostToolBatch 입력2318 PostToolBatch 입력

2319</h4>2319</h4>

2320 2320

2321[공통 입력 필드](#common-input-fields) 외에도 PostToolBatch hook은 배치의 모든 도구 호출을 설명하는 배열인 `tool_calls`를 받습니다:2321[공통 입력 필드](#common-input-fields) 외에도 PostToolBatch 훅은 배치의 모든 도구 호출을 설명하는 배열인 `tool_calls`를 전달받습니다.

2322 2322

2323```json theme={null}2323```json theme={null}

2324{2324{

2332 "tool_name": "Read",2332 "tool_name": "Read",

2333 "tool_input": {"file_path": "/.../ledger/accounts.py"},2333 "tool_input": {"file_path": "/.../ledger/accounts.py"},

2334 "tool_use_id": "toolu_01...",2334 "tool_use_id": "toolu_01...",

2335 "tool_response": " 1\tfrom __future__ import annotations\n 2\t..."2335 "tool_response": "1\tfrom __future__ import annotations\n2\t..."

2336 },2336 },

2337 {2337 {

2338 "tool_name": "Read",2338 "tool_name": "Read",

2339 "tool_input": {"file_path": "/.../ledger/transactions.py"},2339 "tool_input": {"file_path": "/.../ledger/transactions.py"},

2340 "tool_use_id": "toolu_02...",2340 "tool_use_id": "toolu_02...",

2341 "tool_response": " 1\tfrom __future__ import annotations\n 2\t..."2341 "tool_response": "1\tfrom __future__ import annotations\n2\t..."

2342 }2342 }

2343 ]2343 ]

2344}2344}

2345```2345```

2346 2346

2347`tool_response`는 모델이 해당 `tool_result` 블록에서 받는 것과 동일한 콘텐츠를 포함합니다. 값은 도구가 내보낸 것과 정확히 같은 직렬화된 문자열 또는 콘텐츠 블록 배열입니다. `Read`의 경우 원본 파일 내용이 아닌 줄 번호가 접두사로 붙은 텍스트를 의미합니다. 응답이 클 수 있으므로 필요한 필드만 구문 분석합니다.2347`tool_response`에는 모델이 해당 `tool_result` 블록에서 받는 것과 같은 내용이 포함됩니다. 값은 도구가 내보낸 그대로의 직렬화된 문자열 또는 콘텐츠 블록 배열입니다. `Read`의 경우 원시 파일 내용이 아니라 줄 번호가 앞에 붙은 텍스트입니다. 응답이 클 수 있으므로 필요한 필드만 파싱합니다.

2348 2348

2349<Note>2349<Note>

2350 `tool_response` 형태는 `PostToolUse`와 다릅니다. `PostToolUse`는 도구의 구조화된 `Output` 객체를 전달합니다 (예: `Write`의 경우 `{filePath: "...", type: "create"}`). `PostToolBatch`는 모델이 보는 직렬화된 `tool_result` 콘텐츠를 전달합니다.2350 `tool_response`의 형태는 `PostToolUse`의 형태와 다릅니다. `PostToolUse`는 도구의 구조화된 `Output` 객체(예: `Write`의 경우 `{filePath: "...", type: "create"}`)를 전달하고, `PostToolBatch`는 모델이 보는 직렬화된 `tool_result` 콘텐츠를 전달합니다.

2351</Note>2351</Note>

2352 2352

2353<h4 id="posttoolbatch-decision-control">2353<h4 id="posttoolbatch-decision-control">

2354 PostToolBatch 결정 제어2354 PostToolBatch 결정 제어

2355</h4>2355</h4>

2356 2356

2357`PostToolBatch` hook은 Claude에 대한 컨텍스트를 주입할 수 있습니다. 모든 hook에 사용 가능한 [JSON 출력 필드](#json-output) 외에도 hook 스크립트는 이러한 이벤트 특정 필드를 반환할 수 있습니다:2357`PostToolBatch` 훅은 Claude를 위한 컨텍스트를 주입할 수 있습니다. 모든 훅에서 사용할 수 있는 [JSON 출력 필드](#json-output) 외에도 훅 스크립트는 다음과 같은 이벤트별 필드를 반환할 수 있습니다.

2358 2358

2359| 필드 | 설명 |2359| 필드 | 설명 |

2360| :- | :- |2360| :- | :- |

2361| `additionalContext` | 다음 모델 호출 전에 한 번 주입되는 컨텍스트 문자열. [Claude를 위한 컨텍스트 추가](#add-context-for-claude)를 참조하여 전달 세부 정보, 포함할 내용, 재개된 세션이 과거 값을 처리하는 방식을 확인하세요 |2361| `additionalContext` | 다음 모델 호출 전에 한 번 주입되는 컨텍스트 문자열입니다. 전달 방식, 포함할 내용, 재개된 세션에서 이전 값을 처리하는 방식은 [Claude를 위한 컨텍스트 추가](#add-context-for-claude)를 참조하세요 |

2362 2362

2363```json theme={null}2363```json theme={null}

2364{2364{

2369}2369}

2370```2370```

2371 2371

2372`decision: "block"` 또는 `continue: false`를 반환하면 다음 모델 호출 전에 에이전트 루프가 중지됩니다. 차단 메시지는 JSON `reason` 또는 `stopReason`, 또는 종료 코드 2의 stderr에서 나옵니다. 트랜스크립트에 경고로 표시되고 대화에 유지되므로 Claude는 대화가 계속될 때 이를 봅니다.2372`decision: "block"` 또는 `continue: false`를 반환하면 다음 모델 호출 전에 에이전틱 루프가 중지됩니다. 차단 메시지는 JSON의 `reason` 또는 `stopReason`에서 가져오거나, 종료 코드 2인 경우 stderr에서 가져옵니다. 이 메시지는 트랜스크립트에 경고로 표시되며 대화에 남아 있으므로, 대화가 계속되면 Claude가 이를 보게 됩니다.

2373 2373

2374<h3 id="permissiondenied">2374<h3 id="permissiondenied">

2375 PermissionDenied2375 PermissionDenied

2376</h3>2376</h3>

2377 2377

2378[자동 모드](/docs/ko/permission-modes#eliminate-prompts-with-auto-mode)가 도구 호출을 거부할 때 실행됩니다 (분류기 판정이 없어서 거부할 때 포함 ([자동 모드가 작업의 안전성을 결정할 수 없음](/docs/ko/errors#auto-mode-cannot-determine-the-safety-of-an-action) 또는 응답이 구문 분석되지 않았을 때). 이 hook은 자동 모드에서만 발생합니다: 권한 대화 상자를 수동으로 거부할 때, `PreToolUse` hook이 호출을 차단할 때, 또는 `deny` 규칙이 일치할 때 실행되지 않습니다. 이를 사용하여 거부를 기록하고, 구성을 조정하거나, 모델이 도구 호출을 재시도할 수 있음을 알립니다.2378[자동 모드](/docs/ko/permission-modes#eliminate-prompts-with-auto-mode)가 도구 호출을 거부할 때 실행됩니다. 여기에는 [자동 모드와 별개인 안전 검사가 분류기 자체의 요청을 거부했거나](/docs/ko/errors#auto-mode-cannot-determine-the-safety-of-an-action) 분류기의 응답을 파싱할 수 없어서 분류기 판정 없이 거부한 경우도 포함됩니다. 이 훅은 자동 모드에서만 발생합니다. 사용자가 권한 대화 상자에서 직접 거부하거나, `PreToolUse` 훅이 호출을 차단하거나, `deny` 규칙이 매칭되는 경우에는 실행되지 않습니다. 거부를 로그에 기록하거나, 구성을 조정하거나, 모델에게 도구 호출을 재시도해도 된다고 알리는 데 사용합니다.

2379 2379

2380도구 이름에서 일치합니다. PreToolUse와 동일한 값입니다.2380도구 이름으로 매칭하며, 값은 PreToolUse와 같습니다.

2381 2381

2382<h4 id="permissiondenied-input">2382<h4 id="permissiondenied-input">

2383 PermissionDenied 입력2383 PermissionDenied 입력

2384</h4>2384</h4>

2385 2385

2386[공통 입력 필드](#common-input-fields) 외에도 PermissionDenied hook은 `tool_name`, `tool_input`, `tool_use_id`, `reason`을 받습니다. MCP 도구의 경우 [`mcp_server`](#pretooluse-input) 객체도 받습니다.2386[공통 입력 필드](#common-input-fields) 외에도 PermissionDenied 훅은 `tool_name`, `tool_input`, `tool_use_id`, `reason`을 전달받습니다. MCP 도구의 경우 [`mcp_server`](#pretooluse-input) 객체도 전달받습니다.

2387 2387

2388```json theme={null}2388```json theme={null}

2389{2389{

2404 2404

2405| 필드 | 설명 |2405| 필드 | 설명 |

2406| :- | :- |2406| :- | :- |

2407| `reason` | 거부 이유. 분류기 판정의 경우 대부분의 세션에서 `[Data Exfiltration]`과 같은 대괄호의 일치하는 규칙 이름을 지정합니다; [거부 검토](/docs/ko/auto-mode-config#review-denials)를 참조하여 다른 형식을 확인하세요. [판정 없는 거부](#permissiondenied-decision-control)의 경우 `Auto mode could not evaluate this action and is blocking it for safety`로 시작합니다. 분류기 모델을 사용할 수 없어서 거부하는 경우 고정 텍스트 `Classifier unavailable`입니다 |2407| `reason` | 거부 사유입니다. 분류기 판정의 경우 대부분의 세션에서 `[Data Exfiltration]`과 같이 매칭된 규칙 이름을 대괄호 안에 표시합니다. 다른 형식은 [거부 검토](/docs/ko/auto-mode-config#review-denials)를 참조하세요. [판정 없는 거부](#permissiondenied-decision-control)의 경우 `Auto mode could not evaluate this action and is blocking it for safety`로 시작합니다. 분류기 모델을 사용할 수 없어서 거부된 경우 고정 텍스트 `Classifier unavailable`입니다 |

2408 2408

2409<h4 id="permissiondenied-decision-control">2409<h4 id="permissiondenied-decision-control">

2410 PermissionDenied 결정 제어2410 PermissionDenied 결정 제어

2411</h4>2411</h4>

2412 2412

2413PermissionDenied hook은 모델이 거부된 도구 호출을 재시도할 수 있음을 알릴 수 있습니다. `hookSpecificOutput.retry`를 `true`로 설정한 JSON 객체를 반환합니다:2413PermissionDenied 훅은 모델에게 거부된 도구 호출을 재시도해도 된다고 알릴 수 있습니다. `hookSpecificOutput.retry`를 `true`로 설정한 JSON 객체를 반환합니다.

2414 2414

2415```json theme={null}2415```json theme={null}

2416{2416{

2421}2421}

2422```2422```

2423 2423

2424`retry`가 `true`일 때 Claude Code는 모델이 도구 호출을 재시도할 수 있음을 알리는 메시지를 대화에 추가합니다. 거부 자체는 역전되지 않습니다. hook이 JSON을 반환하지 않거나 `retry: false`를 반환하면 거부가 유지되고 모델은 원래 거부 메시지를 받습니다.2424`retry`가 `true`이면 Claude Code는 모델에게 도구 호출을 재시도해도 된다고 알리는 메시지를 대화에 추가합니다. Claude Code가 거부 자체를 번복하지는 않습니다. 훅이 JSON을 반환하지 않거나 `retry: false`를 반환하면 거부가 유지되고 모델은 원래의 거부 메시지를 받습니다.

2425 2425

2426분류기가 [작업에 대한 판정을 생성하지 않았을 때](/docs/ko/errors#auto-mode-cannot-determine-the-safety-of-an-action) Claude Code는 `retry: true`를 무시합니다: 응답이 구문 분석되지 않았거나 자동 모드와 별개의 안전 검사가 분류기의 요청을 거부했습니다. 이러한 거부의 경우 Claude Code는 이미 거부 메시지에서 나중에 재시도할지 또는 계속할지를 모델에 알립니다.2426분류기가 [작업에 대한 판정을 내리지 못한](/docs/ko/errors#auto-mode-cannot-determine-the-safety-of-an-action) 경우, 즉 분류기의 응답을 파싱할 수 없었거나 자동 모드와 별개인 안전 검사가 분류기 자체의 요청을 거부한 경우 Claude Code는 `retry: true`를 무시합니다. 이러한 거부의 경우 Claude Code는 이미 거부 메시지에서 모델에게 나중에 재시도할지 다음으로 넘어갈지 알려 줍니다.

2427 2427

2428<h3 id="notification">2428<h3 id="notification">

2429 Notification2429 Notification

2430</h3>2430</h3>

2431 2431

2432Claude Code가 알림을 보낼 때 실행됩니다. 알림 유형에서 일치합니다. 생략하여 모든 알림 유형에 대해 hook을 실행합니다.2432Claude Code가 알림을 보낼 때 실행됩니다. 알림 유형으로 매칭합니다. 모든 알림 유형에 대해 훅을 실행하려면 matcher를 생략합니다.

2433 2433

2434데스크톱 알림이 꺼져 있어도 이 hook 이벤트를 받습니다: `preferredNotifChannel` 설정 (예: `notifications_disabled`)은 알림 방식만 변경하고 hook이 실행되는지 여부는 변경하지 않습니다.2434데스크톱 알림을 꺼 두어도 이 훅 이벤트는 전달됩니다. `notifications_disabled`를 포함한 `preferredNotifChannel` 설정은 사용자에게 알리는 방식만 변경할 뿐 훅의 실행 여부에는 영향을 주지 않습니다.

2435 2435

2436| Matcher | 언제 발생하는지 |2436| Matcher | 발생 시점 |

2437| :- | :- |2437| :- | :- |

2438| `permission_prompt` | Claude가 도구 사용 또는 샌드박스 명령의 [네트워크 요청](/docs/ko/sandboxing#network-isolation)에 대한 권한이 필요하고 프롬프트가 약 6초 대기했습니다 |2438| `permission_prompt` | Claude가 도구 사용 또는 샌드박스 처리된 명령의 [네트워크 요청](/docs/ko/sandboxing#network-isolation)에 대한 사용자 승인을 필요로 하고, 프롬프트가 약 6초 동안 대기한 경우 |

2445| `agent_needs_input` | 백그라운드 세션이 입력을 기다리기 시작합니다 ([agent view](/docs/ko/agent-view)가 터미널에서 열려 있을 때) 또는 현재 세션이 [agent team](/docs/ko/agent-teams#choose-a-display-mode) 팀원의 터미널 설정 질문을 요청하고 약 6초 동안 입력하지 않았습니다 |2445| `agent_needs_input` | 터미널에서 [에이전트 뷰](/docs/ko/agent-view)가 열려 있는 동안 백그라운드 세션이 사용자 입력을 기다리기 시작한 경우. 터미널 세션에서 [에이전트 팀 팀원의 터미널 설정 질문](/docs/ko/agent-teams#choose-a-display-mode)이나 [분류기 요청 요금](/docs/ko/auto-mode-classifier-billing)에 대한 자동 모드 안내를 표시하고 사용자가 약 6초 동안 입력하지 않은 경우에도 발생합니다 |

2447| `quota_auto_resume_fired` | Claude Code는 claude.ai 사용 제한이 일시 중지한 작업을 계속합니다: 재설정 시 또는 Claude Code 중에 사용 가능한 사용을 만드는 것 (예: 사용 크레딧 추가, 계획 업그레이드, 모델 전환)으로 인해 더 빨리 |2447| `quota_auto_resume_fired` | claude.ai 사용 한도로 일시 중지된 작업을 Claude Code가 계속 진행하는 경우. 한도가 재설정될 때 진행하거나, 대기 중에 Claude Code에서 사용량 크레딧 추가, 플랜 업그레이드, 모델 전환 등의 작업으로 사용량을 다시 사용할 수 있게 되면 더 일찍 진행합니다. 단, [모델 설정 예외](/docs/ko/interactive-mode#wait-for-a-usage-limit-to-reset)가 적용됩니다 |

2448| `quota_auto_resume_stale` | claude.ai 사용 제한이 컴퓨터가 약 30분 이상 절전 중일 때 재설정됩니다. Claude Code는 계속하는 대신 `Enter`를 누를 때까지 기다립니다. 더 짧은 절전 후 계속하고 대신 `quota_auto_resume_fired`를 발생시킵니다 |2448| `quota_auto_resume_stale` | 컴퓨터가 약 30분 이상 절전 상태인 동안 claude.ai 사용 한도가 재설정된 경우. Claude Code는 계속 진행하지 않고 사용자가 `Enter`를 누를 때까지 기다립니다. 절전 시간이 더 짧으면 계속 진행하고 대신 `quota_auto_resume_fired`를 발생시킵니다 |

2449| `quota_auto_resume_disabled` | Claude Code는 claude.ai 사용 제한 대기를 종료하고 작업을 계속하지 않습니다: [`autoContinueAtUsageLimit`](/docs/ko/settings-reference#autocontinueatusagelimit)이 꺼졌거나 재설정이 Claude Code가 시작한 대기 중에 24시간 이상 멀어졌거나 계속된 작업이 제한을 계속 적중했거나 계속이 모델에 도달하기 전에 차단되었습니다. `Esc` 또는 `Ctrl+C`를 누르거나 **자동으로 계속하지 않음**을 선택할 때 발생하지 않습니다 |2449| `quota_auto_resume_disabled` | Claude Code가 작업을 계속하지 않고 claude.ai 사용 한도 대기를 종료하는 경우. 즉, Claude Code가 스스로 시작한 대기 중에 [`autoContinueAtUsageLimit`](/docs/ko/settings-reference#autocontinueatusagelimit)이 꺼졌거나 재설정 시점이 24시간 이상 뒤로 밀린 경우, 계속 진행한 작업이 계속 한도에 도달한 경우, 또는 계속 진행이 모델에 도달하기 전에 차단된 경우입니다. 사용자가 `Esc` 또는 `Ctrl+C`를 누르거나 **Don't continue automatically**를 선택한 경우에는 발생하지 않습니다 |

2450 2450

2451`agent_needs_input` 및 `agent_completed` 유형은 Claude Code v2.1.198 이상이 필요합니다.2451`agent_needs_input` 및 `agent_completed` 유형은 Claude Code v2.1.198 이상이 필요합니다.

2452 2452

2453`quota_auto_resume_fired`, `quota_auto_resume_stale`, `quota_auto_resume_disabled` 유형은 Claude Code v2.1.234 이상이 필요합니다.2453`quota_auto_resume_fired`, `quota_auto_resume_stale`, `quota_auto_resume_disabled` 유형은 Claude Code v2.1.234 이상이 필요합니다.

2454 2454

2455터미널 세션에서 샌드박스 명령의 네트워크 요청에 대한 `permission_prompt`는 Claude Code v2.1.246 이상이 필요합니다.2455터미널 세션에서 샌드박스 처리된 명령의 네트워크 요청에 대한 `permission_prompt`는 Claude Code v2.1.246 이상이 필요합니다.

2456 2456

2457팀원의 터미널 설정 질문에 대한 `agent_needs_input`은 Claude Code v2.1.248 이상이 필요합니다.2457팀원의 터미널 설정 질문에 대한 `agent_needs_input`은 Claude Code v2.1.248 이상이 필요합니다.

2458 2458

2459<Note>2459<Note>

2460 `permission_prompt`, `idle_prompt`, `elicitation_dialog`, `elicitation_url_dialog` 유형은 데스크톱 알림과 시간을 공유하므로 터미널 세션에서는 터미널에서 멀리 있는 것처럼 보일 때만 표시됩니다:2460 `permission_prompt`, `idle_prompt`, `elicitation_dialog`, `elicitation_url_dialog` 유형은 데스크톱 알림과 타이밍을 공유하므로, 터미널 세션에서는 사용자가 터미널에서 자리를 비운 것으로 보일 때만 표시됩니다.

2461 2461

2462 * 약 6초 동안 입력하지 않으면 `permission_prompt`를 예상합니다. 타이머는 권한 프롬프트가 나타날 때 시작되고 각 키 입력이 이를 연기합니다. Claude가 도구 사용 권한을 요청할 때 즉시 hook을 실행하려면 대신 [PermissionRequest](#permissionrequest)를 사용합니다.2462 * `permission_prompt`는 사용자가 약 6초 동안 입력하지 않으면 발생합니다. 타이머는 권한 프롬프트가 나타날 때 시작되며, 키를 입력할 때마다 연기됩니다. Claude가 도구 사용 권한을 요청할 때 즉시 훅을 실행하려면 대신 [PermissionRequest](#permissionrequest)를 사용합니다.

2463 * Claude가 응답을 마친 후 약 60초 후에 `idle_prompt`를 예상하고 입력하지 않은 경우에만. Claude Code는 claude.ai 사용 제한 재설정을 기다리는 동안 `idle_prompt`를 보내지 않습니다. 대기가 자체적으로 끝나면 `quota_auto_resume_*` 유형 중 하나가 대신 발생합니다.2463 * `idle_prompt`는 Claude가 응답을 마친 후 약 60초가 지나면 발생하며, 그 이후 사용자가 입력하지 않은 경우에만 발생합니다. Claude Code는 claude.ai 사용 한도가 재설정되기를 기다리는 동안에는 `idle_prompt`를 보내지 않습니다. 대기가 자체적으로 종료되면 대신 `quota_auto_resume_*` 유형 중 하나가 발생합니다.

2464 * elicitation 양식의 경우 `elicitation_dialog`를 예상하거나 약 6초 동안 입력하지 않은 경우 브라우저 URL 요청의 경우 `elicitation_url_dialog`. 둘 다 `permission_prompt`와 동일한 6초 게이트를 공유합니다: 타이머는 대화 상자가 나타날 때 시작되고 각 키 입력이 이를 연기합니다.2464 * elicitation 양식의 경우 `elicitation_dialog`, 브라우저 URL 요청의 경우 `elicitation_url_dialog`가 사용자가 약 6초 동안 입력하지 않으면 발생합니다. 둘 다 `permission_prompt`와 같은 6초 기준을 공유합니다. 타이머는 대화 상자가 나타날 때 시작되며, 키를 입력할 때마다 연기됩니다.

2465 2465

2466 권한 요청 또는 elicitation이 다른 대화 상자가 화면에 있는 동안 도착하면 동일한 6초 게이트를 유지하고 요청이 도착할 때부터 시간이 지정됩니다. 해당 알림은 요청이 여전히 열린 대화 상자 뒤에서 기다리는 동안 도달할 수 있습니다.2466 다른 대화 상자가 화면에 있는 동안 도착한 권한 요청이나 elicitation도 같은 6초 기준을 유지하며, 요청이 도착한 시점부터 시간을 잽니다. 요청이 아직 열린 대화 상자 뒤에서 대기하는 동안에도 알림이 전달될 수 있습니다.

2467</Note>2467</Note>

2468 2468

2469Claude Code는 권한 요청을 Agent SDK의 [`canUseTool` callback](/docs/ko/agent-sdk/user-input)으로 보내는 세션에서 `permission_prompt`를 다르게 시간합니다 (Claude Desktop 및 VS Code 확장이 Claude Code를 호스팅하는 방식):2469Claude Code가 권한 요청을 Agent SDK의 [`canUseTool` 콜백](/docs/ko/agent-sdk/user-input)으로 보내는 세션에서는 `permission_prompt`의 타이밍이 다릅니다. Claude Desktop과 VS Code 확장 프로그램이 이 방식으로 Claude Code를 호스팅합니다.

2470 2470

2471* Claude가 권한을 요청한 후 약 6초 후에 `permission_prompt`를 예상합니다. Claude Code는 입력하는 동안 이를 연기하지 않습니다.2471* `permission_prompt`는 Claude가 권한을 요청한 후 약 6초가 지나면 발생합니다. 사용자가 입력하는 동안에도 Claude Code는 이를 연기하지 않습니다.

2472* 또는 [PermissionRequest](#permissionrequest) hook이 더 빨리 답변하면 Claude Code는 `permission_prompt`를 실행하지 않습니다.2472* 사용자나 [PermissionRequest](#permissionrequest) 훅이 더 일찍 응답하면 Claude Code는 `permission_prompt`를 실행하지 않습니다.

2473* [`CLAUDE_CODE_DISABLE_PERMISSION_PROMPT_NOTIFY_HOOKS`](/docs/ko/env-vars)를 `1`로 설정하여 이 세션에서 `permission_prompt`를 끕니다.2473* 이러한 세션에서 `permission_prompt`를 끄려면 [`CLAUDE_CODE_DISABLE_PERMISSION_PROMPT_NOTIFY_HOOKS`](/docs/ko/env-vars)를 `1`로 설정합니다.

2474 2474

2475v2.1.233 이전에는 `permission_prompt`가 이 세션에서 발생하지 않았습니다.2475v2.1.233 이전에는 이러한 세션에서 `permission_prompt`가 발생하지 않았습니다.

2476 2476

2477별도의 matcher를 사용하여 알림 유형에 따라 다른 핸들러를 실행합니다. 이 구성은 Claude가 권한 승인이 필요할 때 권한 특정 경고 스크립트를 트리거하고 Claude가 유휴 상태일 때 다른 알림을 트리거합니다:2477알림 유형에 따라 서로 다른 핸들러를 실행하려면 별도의 matcher를 사용합니다. 다음 구성은 Claude가 권한 승인을 필요로 할 때 권한 전용 알림 스크립트를 트리거하고, Claude가 유휴 상태일 때 다른 알림을 트리거합니다.

2478 2478

2479```json theme={null}2479```json theme={null}

2480{2480{

2507 Notification 입력2507 Notification 입력

2508</h4>2508</h4>

2509 2509

2510[공통 입력 필드](#common-input-fields) 외에도 Notification hook은 알림 텍스트가 있는 `message`, 선택적 `title`, 발생한 유형을 나타내는 `notification_type`을 받습니다.2510[공통 입력 필드](#common-input-fields) 외에도 Notification 훅은 알림 텍스트가 담긴 `message`, 선택적 `title`, 발생한 유형을 나타내는 `notification_type`을 전달받습니다.

2511 2511

2512```json theme={null}2512```json theme={null}

2513{2513{

2521}2521}

2522```2522```

2523 2523

2524Notification hook은 알림을 차단하거나 수정할 수 없습니다. Claude Code는 이들의 `systemMessage` 및 `continue` 필드를 삭제하지만 여전히 [`terminalSequence`](#emit-terminal-notifications)를 내보냅니다 (데스크톱 알림 예제가 의존하는 것). Notification hook은 외부 서비스로 알림을 전달하는 것과 같은 부작용을 위한 것입니다.2524Notification 훅은 알림을 차단하거나 수정할 수 없습니다. Claude Code는 이 훅의 `systemMessage` 및 `continue` 필드를 삭제하지만, 데스크톱 알림 예시가 사용하는 [`terminalSequence`](#emit-terminal-notifications)는 계속 내보냅니다. Notification 훅은 알림을 외부 서비스로 전달하는 것과 같은 부수 효과를 위한 것입니다.

2525 2525

2526<h3 id="subagentstart">2526<h3 id="subagentstart">

2527 SubagentStart2527 SubagentStart

2528</h3>2528</h3>

2529 2529

2530Claude가 Agent 도구로 subagent를 생성할 때, Claude가 [subagent를 재개](/docs/ko/sub-agents#resume-subagents)할 때, 그리고 in-process [agent team](/docs/ko/agent-teams) 팀원이 새 메시지를 처리할 때마다 실행됩니다. 에이전트 유형 이름으로 필터링할 matcher를 지원합니다. 기본 제공 에이전트의 경우 이는 `general-purpose`, `Explore`, `Plan`과 같은 에이전트 이름입니다. [사용자 정의 subagent](/docs/ko/sub-agents)의 경우 이는 파일명이 아닌 에이전트의 frontmatter의 `name` 필드입니다.2530Claude가 Agent 도구로 서브에이전트를 생성할 때, Claude가 [서브에이전트를 재개](/docs/ko/sub-agents#resume-subagents)할 때, 그리고 프로세스 내 [에이전트 팀](/docs/ko/agent-teams) 팀원이 새 메시지를 처리할 때마다 실행됩니다. 에이전트 유형 이름으로 필터링하는 matcher를 지원합니다. 기본 제공 에이전트의 경우 `general-purpose`, `Explore`, `Plan`과 같은 에이전트 이름입니다. [사용자 정의 서브에이전트](/docs/ko/sub-agents)의 경우 파일 이름이 아니라 에이전트 frontmatter의 `name` 필드입니다.

2531 2531

2532[plugin](/docs/ko/plugins)에서 제공하는 subagent의 경우 에이전트 유형은 `my-plugin:reviewer`와 같은 plugin 범위 식별자이며, 파일명이 아닙니다. 콜론은 plugin 범위 이름을 정규식 경로에 배치하므로 정확한 일치를 위해 matcher를 `^` 및 `$`로 고정합니다: `^my-plugin:reviewer$`.2532[플러그인](/docs/ko/plugins/overview)으로 제공되는 서브에이전트의 경우 에이전트 유형은 단순한 frontmatter 이름이 아니라 `my-plugin:reviewer`와 같은 플러그인 범위 식별자입니다. 콜론이 있으면 플러그인 범위 이름이 정규식 경로로 처리되므로, 정확히 매칭하려면 matcher를 `^`와 `$`로 고정합니다: `^my-plugin:reviewer$`.

2533 2533

2534<h4 id="subagentstart-input">2534<h4 id="subagentstart-input">

2535 SubagentStart 입력2535 SubagentStart 입력

2536</h4>2536</h4>

2537 2537

2538[공통 입력 필드](#common-input-fields) 외에도 SubagentStart hook은 subagent의 고유 식별자가 있는 `agent_id`와 matcher가 필터링하는 에이전트 이름이 있는 `agent_type`을 받습니다.2538[공통 입력 필드](#common-input-fields) 외에도 SubagentStart 훅은 서브에이전트의 고유 식별자가 담긴 `agent_id`와 matcher가 필터링하는 에이전트 이름이 담긴 `agent_type`을 전달받습니다.

2539 2539

2540```json theme={null}2540```json theme={null}

2541{2541{

2548}2548}

2549```2549```

2550 2550

2551SubagentStart hook은 subagent 생성을 차단할 수 없지만 subagent에 컨텍스트를 주입할 수 있습니다. 모든 hook에 사용 가능한 [JSON 출력 필드](#json-output) 외에도 다음을 반환할 수 있습니다:2551SubagentStart 훅은 서브에이전트 생성을 차단할 수 없지만, 서브에이전트에 컨텍스트를 주입할 수 있습니다. 모든 훅에서 사용할 수 있는 [JSON 출력 필드](#json-output) 외에도 다음을 반환할 수 있습니다.

2552 2552

2553| 필드 | 설명 |2553| 필드 | 설명 |

2554| :- | :- |2554| :- | :- |

2555| `additionalContext` | subagent의 대화 시작 부분에 추가되는 문자열. 첫 번째 프롬프트 전에 추가됩니다. [Claude를 위한 컨텍스트 추가](#add-context-for-claude)를 참조하세요 |2555| `additionalContext` | 서브에이전트의 대화 시작 시, 첫 프롬프트 전에 서브에이전트의 컨텍스트에 추가되는 문자열입니다. [Claude를 위한 컨텍스트 추가](#add-context-for-claude)를 참조하세요 |

2556 2556

2557```json theme={null}2557```json theme={null}

2558{2558{

2563}2563}

2564```2564```

2565 2565

2566hook이 동일한 subagent에 대해 다시 실행될 때 Claude Code는 subagent의 컨텍스트가 이전 실행의 복사본을 이미 보유하지 않을 때만 반환된 컨텍스트를 주입합니다. 시작 시 주입된 복사본은 subagent의 [prompt cache](/docs/ko/prompt-caching#subagents-and-the-cache)를 그대로 두고 제자리에 유지됩니다. [자동 압축](/docs/ko/sub-agents#auto-compaction)이 해당 복사본을 삭제한 후 Claude Code는 다음 실행의 컨텍스트를 다시 주입합니다.2566같은 서브에이전트에 대해 훅이 다시 실행되면, Claude Code는 서브에이전트의 컨텍스트에 이전 실행의 사본이 아직 없는 경우에만 반환된 컨텍스트를 주입합니다. 시작 시 주입된 사본은 그대로 유지되므로 서브에이전트의 [프롬프트 캐시](/docs/ko/prompt-caching#subagents-and-the-cache)가 손상되지 않습니다. [자동 압축](/docs/ko/sub-agents#auto-compaction)으로 해당 사본이 삭제된 후에는 Claude Code가 다음 실행의 컨텍스트를 다시 주입합니다.

2567 2567

2568<h3 id="subagentstop">2568<h3 id="subagentstop">

2569 SubagentStop2569 SubagentStop

2570</h3>2570</h3>

2571 2571

2572Claude Code subagent가 응답을 마쳤을 때 실행됩니다. 에이전트 유형에서 일치합니다. SubagentStart와 동일한 값입니다.2572Claude Code 서브에이전트가 응답을 마쳤을 때 실행됩니다. 에이전트 유형으로 매칭하며, 값은 SubagentStart와 같습니다.

2573 2573

2574<h4 id="subagentstop-input">2574<h4 id="subagentstop-input">

2575 SubagentStop 입력2575 SubagentStop 입력

2576</h4>2576</h4>

2577 2577

2578[공통 입력 필드](#common-input-fields) 외에도 SubagentStop hook은 `stop_hook_active`, `agent_id`, `agent_type`, `agent_transcript_path`, `last_assistant_message`를 받습니다. `agent_type` 필드는 matcher 필터링에 사용되는 값입니다. `transcript_path`는 메인 세션의 트랜스크립트이고 `agent_transcript_path`는 중첩된 `subagents/` 폴더에 저장된 subagent의 자체 트랜스크립트입니다. `last_assistant_message` 필드는 subagent의 최종 응답의 텍스트 내용을 포함하므로 hook은 트랜스크립트 파일을 구문 분석하지 않고도 액세스할 수 있습니다.2578[공통 입력 필드](#common-input-fields) 외에도 SubagentStop 훅은 `stop_hook_active`, `agent_id`, `agent_type`, `agent_transcript_path`, `last_assistant_message`를 전달받습니다. `agent_type` 필드는 matcher 필터링에 사용되는 값입니다. `transcript_path`는 메인 세션의 트랜스크립트이고, `agent_transcript_path`는 중첩된 `subagents/` 폴더에 저장된 서브에이전트 자체의 트랜스크립트입니다. `last_assistant_message` 필드에는 서브에이전트의 최종 응답 텍스트 내용이 포함되므로, 훅은 트랜스크립트 파일을 파싱하지 않고도 이에 접근할 수 있습니다.

2579 2579

2580Claude Code v2.1.271 이상에서 [`SubagentHandback`](/docs/ko/tools-reference) 도구로 실행되는 subagent는 해당 도구를 통해 보고서를 전달하며 텍스트로 반환하지 않습니다. `last_assistant_message` 필드는 subagent의 닫는 텍스트 (있는 경우)를 보유하며, 이는 전달된 보고서가 아닙니다. 보고서는 해당 호출의 `message` 입력이며, `PreToolUse` 또는 `PostToolUse` hook이 `SubagentHandback`과 일치할 때 `tool_input.message`로 받습니다.2580모든 SubagentStop 이벤트가 Claude가 생성한 서브에이전트에서 오는 것은 아닙니다. Claude Code는 [프롬프트 제안](/docs/ko/interactive-mode#prompt-suggestions) 및 [`/btw` 곁가지 질문](/docs/ko/interactive-mode#side-questions-with-%2Fbtw)과 같은 일부 자체 기능을 위해 내부 에이전트도 실행하며, 이러한 에이전트 중 하나가 완료될 때도 SubagentStop이 발생합니다. 이러한 이벤트의 경우 `agent_type`은 [`--agent`](/docs/ko/cli-reference#cli-flags) 또는 [`agent` 설정](/docs/ko/settings-reference#agent)으로 지정된 것처럼 세션 자체가 실행되는 에이전트 이름이며, 세션이 에이전트 없이 실행되는 경우 빈 문자열입니다.

2581 2581

2582SubagentStop hook은 또한 [Stop 입력](#stop-input)에서 설명한 `background_tasks` 및 `session_crons` 배열을 받습니다. 두 배열 모두 subagent가 아닌 부모 세션으로 범위가 지정됩니다.2582에이전트 유형을 지정하는 `matcher`는 빈 `agent_type`과 매칭되지 않습니다. matcher가 생략되었거나, `""` 또는 `"*"`이거나, 빈 문자열과 매칭되는 정규식인 훅은 빈 `agent_type`을 가진 이벤트에서도 실행됩니다.

2583

2584Claude Code v2.1.271 이상에서는 [`SubagentHandback`](/docs/ko/tools-reference) 도구와 함께 실행되는 서브에이전트가 중지되기 전에 해당 도구를 통해 보고서를 전달합니다. 이 경우 `last_assistant_message` 필드에는 서브에이전트의 마무리 텍스트(있는 경우)가 담기며, 이는 전달된 보고서가 아닙니다. 보고서는 해당 호출의 `message` 입력이며, `SubagentHandback`에 매칭되는 `PreToolUse` 또는 `PostToolUse` 훅이 이를 `tool_input.message`로 전달받습니다.

2585

2586SubagentStop 훅은 [Stop 입력](#stop-input)에서 설명하는 `background_tasks` 및 `session_crons` 배열도 전달받습니다. 두 배열 모두 서브에이전트가 아닌 부모 세션 범위입니다.

2583 2587

2584```json theme={null}2588```json theme={null}

2585{2589{

2598}2602}

2599```2603```

2600 2604

2601SubagentStop hook은 [Stop hook](#stop-decision-control)과 동일한 결정 제어 형식을 사용합니다. 이들은 `hookSpecificOutput.additionalContext`를 지원하며 `hookEventName`을 `"SubagentStop"`으로 설정하여 subagent를 계속 실행하는 비오류 피드백을 제공합니다. `decision: "block"`을 `reason`과 함께 반환하면 subagent가 계속 실행되고 `reason`이 subagent의 다음 명령으로 전달됩니다. 종료 코드 2로 차단하는 hook은 stderr 메시지를 동일한 방식으로 전달합니다. subagent가 반환한 후 부모 세션에 컨텍스트를 주입하려면 `Agent` 도구에서 [`PostToolUse`](#posttooluse) hook을 대신 사용합니다.2605SubagentStop 훅은 [Stop 훅](#stop-decision-control)과 같은 결정 제어 형식을 사용하며, 여기에는 서브에이전트를 계속 실행시키는 오류가 아닌 피드백을 위해 `hookEventName`을 `"SubagentStop"`으로 설정한 `hookSpecificOutput.additionalContext`도 포함됩니다. `reason`과 함께 `decision: "block"`을 반환하면 서브에이전트가 계속 실행되며 `reason`이 서브에이전트의 다음 지시로 전달됩니다. 종료 코드 2로 차단하는 훅도 같은 방식으로 stderr 메시지를 전달합니다. 서브에이전트가 반환된 후 부모 세션에 컨텍스트를 주입하려면 대신 `Agent` 도구에 대한 [`PostToolUse`](#posttooluse) 훅을 사용합니다.

2602 2606

2603<h3 id="taskcreated">2607<h3 id="taskcreated">

2604 TaskCreated2608 TaskCreated

2605</h3>2609</h3>

2606 2610

2607작업이 `TaskCreate` 도구를 통해 생성될 때 실행됩니다. 이를 사용하여 명명 규칙을 적용하거나, 작업 설명을 요구하거나, 특정 작업이 생성되는 것을 방지합니다. [Task 도구가 없는 세션](/docs/ko/tools-reference#task-tool-availability)에서는 이 이벤트가 발생하지 않습니다.2611`TaskCreate` 도구를 통해 작업이 생성될 때 실행됩니다. 명명 규칙을 적용하거나, 작업 설명을 필수로 요구하거나, 특정 작업이 생성되지 않도록 막는 데 사용합니다. [Task 도구가 없는 세션](/docs/ko/tools-reference#task-tool-availability)에서는 이 이벤트가 발생하지 않습니다.

2608 2612

2609TaskCreated hook은 matcher를 지원하지 않으며 모든 발생에서 발생합니다.2613TaskCreated 훅은 matcher를 지원하지 않으며 매번 발생합니다.

2610 2614

2611<h4 id="taskcreated-input">2615<h4 id="taskcreated-input">

2612 TaskCreated 입력2616 TaskCreated 입력

2613</h4>2617</h4>

2614 2618

2615[공통 입력 필드](#common-input-fields) 외에도 TaskCreated hook은 `task_id`, `task_subject`, 선택적으로 `task_description`, `teammate_name`, `team_name`을 받습니다.2619[공통 입력 필드](#common-input-fields) 외에도 TaskCreated 훅은 `task_id`, `task_subject`와 선택적으로 `task_description`, `teammate_name`, `team_name`을 전달받습니다.

2616 2620

2617```json theme={null}2621```json theme={null}

2618{2622{

2630 2634

2631| 필드 | 설명 |2635| 필드 | 설명 |

2632| :- | :- |2636| :- | :- |

2638 2642

2639<h4 id="taskcreated-decision-control">2643<h4 id="taskcreated-decision-control">

2640 TaskCreated 결정 제어2644 TaskCreated 결정 제어

2641</h4>2645</h4>

2642 2646

2643TaskCreated hook은 작업 생성을 차단하는 두 가지 방법을 지원합니다. 어느 쪽이든 Claude Code는 작업을 삭제하고 메시지를 도구의 오류로 Claude에 반환합니다.2647TaskCreated 훅은 두 가지 방법으로 생성을 차단할 수 있습니다. 어느 방법이든 Claude Code는 작업을 삭제하고 메시지를 도구의 오류로 Claude에게 반환합니다. Claude Code는 이 이벤트의 `continue: false`를 무시하며 Claude는 계속 작업합니다.

2644 2648

2645* **종료 코드 2**: Claude Code는 stderr 텍스트를 메시지로 반환합니다.2649* **종료 코드 2**: Claude Code가 stderr 텍스트를 메시지로 반환합니다.

2646* **JSON `{"decision": "block", "reason": "..."}`**: Claude Code는 `reason`을 메시지로 반환합니다.2650* **JSON `{"decision": "block", "reason": "..."}`**: Claude Code가 `reason`을 메시지로 반환합니다.

2647 2651

2648이 예제는 제목이 필수 형식을 따르지 않는 작업을 차단합니다:2652이 예시는 제목이 필수 형식을 따르지 않는 작업을 차단합니다.

2649 2653

2650```bash theme={null}2654```bash theme={null}

2651#!/bin/bash2655#!/bin/bash

2664 TaskCompleted2668 TaskCompleted

2665</h3>2669</h3>

2666 2670

2667작업이 완료로 표시될 때 실행됩니다. 이는 두 가지 상황에서 발생합니다: 모든 에이전트가 TaskUpdate 도구를 통해 명시적으로 작업을 완료로 표시할 때 또는 [agent team](/docs/ko/agent-teams) 팀원이 진행 중인 작업으로 자신의 턴을 마칠 때입니다. 이를 사용하여 작업이 닫히기 전에 테스트 통과 또는 lint 검사와 같은 완료 기준을 적용할 수 있습니다.2671작업이 완료로 표시될 때 실행됩니다. 이 이벤트는 두 가지 상황에서 발생합니다. 어떤 에이전트든 TaskUpdate 도구를 통해 작업을 명시적으로 완료로 표시하는 경우, 또는 [에이전트 팀](/docs/ko/agent-teams) 팀원이 진행 중인 작업이 있는 상태에서 턴을 마치는 경우입니다. 작업이 종료되기 전에 테스트 통과나 린트 검사와 같은 완료 기준을 적용하는 데 사용합니다.

2668 2672

2669TaskCompleted hook은 matcher를 지원하지 않으며 모든 발생에서 발생합니다.2673TaskCompleted 훅은 matcher를 지원하지 않으며 매번 발생합니다.

2670 2674

2671<h4 id="taskcompleted-input">2675<h4 id="taskcompleted-input">

2672 TaskCompleted 입력2676 TaskCompleted 입력

2673</h4>2677</h4>

2674 2678

2675[공통 입력 필드](#common-input-fields) 외에도 TaskCompleted hook은 `task_id`, `task_subject`, 선택적으로 `task_description`, `teammate_name`, `team_name`을 받습니다.2679[공통 입력 필드](#common-input-fields) 외에도 TaskCompleted 훅은 `task_id`, `task_subject`와 선택적으로 `task_description`, `teammate_name`, `team_name`을 전달받습니다.

2676 2680

2677```json theme={null}2681```json theme={null}

2678{2682{

2691 2695

2692| 필드 | 설명 |2696| 필드 | 설명 |

2693| :- | :- |2697| :- | :- |

2699 2703

2700<h4 id="taskcompleted-decision-control">2704<h4 id="taskcompleted-decision-control">

2701 TaskCompleted 결정 제어2705 TaskCompleted 결정 제어

2702</h4>2706</h4>

2703 2707

2704TaskCompleted hook은 작업 완료를 제어하는 두 가지 방법을 지원합니다:2708TaskCompleted 훅은 작업 완료를 제어하는 두 가지 방법을 지원합니다.

2705 2709

2706* **종료 코드 2**: 작업이 완료로 표시되지 않고 stderr 메시지가 모델에 피드백으로 피드백됩니다.2710* **종료 코드 2**: 작업이 완료로 표시되지 않으며 stderr 메시지가 피드백으로 모델에 전달됩니다.

2707* **JSON `{"continue": false, "stopReason": "..."}`**: 팀원을 완전히 중지하여 `Stop` hook 동작과 일치합니다. `stopReason`은 사용자에게 표시됩니다. `TaskUpdate` 도구가 이벤트를 트리거했을 때 Claude Code는 `continue: false`를 무시합니다; 종료 코드 2는 여전히 완료를 차단합니다.2711* **JSON `{"continue": false, "stopReason": "..."}`**: 팀원이 턴을 마치면서 이벤트가 트리거된 경우, `Stop` 훅 동작과 마찬가지로 팀원을 완전히 중지합니다. `stopReason`은 사용자에게 표시됩니다. `TaskUpdate` 도구가 이벤트를 트리거한 경우 Claude Code는 `continue: false`를 무시하며, 종료 코드 2는 여전히 완료를 차단합니다.

2708 2712

2709이 예제는 테스트를 실행하고 실패하면 작업 완료를 차단합니다:2713이 예시는 테스트를 실행하고 테스트가 실패하면 작업 완료를 차단합니다.

2710 2714

2711```bash theme={null}2715```bash theme={null}

2712#!/bin/bash2716#!/bin/bash

2713INPUT=$(cat)2717INPUT=$(cat)

2714TASK_SUBJECT=$(echo "$INPUT" | jq -r '.task_subject')2718TASK_SUBJECT=$(echo "$INPUT" | jq -r '.task_subject')

2715 2719

2716# 테스트 스위트를 실행합니다2720# Run the test suite

2717if ! npm test 2>&1; then2721if ! npm test 2>&1; then

2718 echo "Tests not passing. Fix failing tests before completing: $TASK_SUBJECT" >&22722 echo "Tests not passing. Fix failing tests before completing: $TASK_SUBJECT" >&2

2719 exit 22723 exit 2

2726 Stop2730 Stop

2727</h3>2731</h3>

2728 2732

2729메인 Claude Code 에이전트가 응답을 마쳤을 때 실행됩니다. 중지가 사용자 중단으로 인해 발생한 경우 실행되지 않습니다. API 오류는 대신 [StopFailure](#stopfailure)를 발생시킵니다.2733메인 Claude Code 에이전트가 응답을 마쳤을 때 실행됩니다. 사용자 중단으로 인해

2734중지된 경우에는 실행되지 않습니다. API 오류는 대신

2735[StopFailure](#stopfailure)를 발생시킵니다.

2730 2736

2731<Tip>2737<Tip>

2732 [`/goal`](/docs/ko/goal) 명령은 세션 범위 prompt 기반 Stop hook의 기본 제공 바로 가기입니다. 조건이 유지될 때까지 Claude가 계속 작동하도록 하되 hook 구성을 작성하지 않으려는 경우 사용합니다.2738 [`/goal`](/docs/ko/goal) 명령은 세션 범위의 프롬프트 기반 Stop 훅을 위한 기본 제공 단축 기능입니다. 훅 구성을 작성하지 않고도 Claude가 특정 조건을 향해 계속 작업하도록 하려는 경우에 사용합니다.

2733</Tip>2739</Tip>

2734 2740

2735<h4 id="stop-input">2741<h4 id="stop-input">

2736 Stop 입력2742 Stop 입력

2737</h4>2743</h4>

2738 2744

2739[공통 입력 필드](#common-input-fields) 외에도 Stop hook은 `stop_hook_active`, `last_assistant_message`, `background_tasks`, `session_crons`를 받습니다. `stop_hook_active` 필드는 Claude Code가 이미 stop hook의 결과로 계속되고 있을 때 `true`입니다. 이 값을 확인하거나 트랜스크립트를 처리하여 Claude Code가 무한정 실행되는 것을 방지합니다. Claude Code는 8번 연속 차단 후 hook을 재정의하고 턴을 종료합니다.2745[공통 입력 필드](#common-input-fields) 외에도 Stop 훅은 `stop_hook_active`, `last_assistant_message`, `background_tasks`, `session_crons`를 전달받습니다. `stop_hook_active` 필드는 Claude Code가 이미 stop 훅의 결과로 계속 진행 중인 경우 `true`입니다. 결코 해결되지 않을 조건에서 차단하지 않도록 이 값을 확인하거나 트랜스크립트를 처리합니다. Claude Code는 연속 계속 진행 횟수를 8회로 제한합니다. stop 훅이 턴을 연속으로 8번 계속 진행시킨 후에는 Claude Code가 다음 차단을 재정의하고 턴을 종료합니다. 이 제한을 높이려면 [`CLAUDE_CODE_STOP_HOOK_BLOCK_CAP`](/docs/ko/env-vars)을 설정합니다.

2740 2746

2741`last_assistant_message` 필드는 Claude의 최종 응답의 텍스트 내용을 포함하므로 hook은 트랜스크립트 파일을 구문 분석하지 않고도 액세스할 수 있습니다. 방금 완료된 턴에 대해 작동하는 hook (예: 읽기 전용 또는 알림 hook)의 경우 트랜스크립트 파일에서 읽는 대신 이 필드를 사용하세요: 트랜스크립트 파일은 모든 버전에서 Stop 시간에 최종 메시지를 포함하도록 보장되지 않습니다.2747`last_assistant_message` 필드에는 Claude의 최종 응답 텍스트 내용이 포함되므로, 훅은 트랜스크립트 파일을 파싱하지 않고도 이에 접근할 수 있습니다. 소리 내어 읽기 훅이나 알림 훅처럼 방금 완료된 턴에 대해 작동하는 훅의 경우 `transcript_path`를 읽는 대신 이 필드를 사용합니다. 모든 버전에서 Stop 시점에 트랜스크립트 파일에 최종 메시지가 포함된다고 보장되지 않기 때문입니다.

2742 2748

2743`background_tasks` 및 `session_crons` 배열을 통해 hook은 "세션이 완료됨"과 "세션이 백그라운드 작업이 깨어날 때까지 일시 중지됨"을 구분할 수 있습니다. 작업 레지스트리에 도달할 수 있을 때 두 배열이 모두 존재하며, 진행 중이거나 예약된 것이 없을 때 비어 있습니다.2749`background_tasks` 및 `session_crons` 배열을 사용하면 훅이 "세션이 완료됨"과 "백그라운드 작업이 세션을 다시 깨울 때까지 일시 중지됨"을 구별할 수 있습니다. 두 배열은 작업 레지스트리에 접근할 수 있을 때 존재하며, 진행 중이거나 예약된 것이 없으면 비어 있습니다.

2744 2750

2745`background_tasks`의 각 항목은 하나의 진행 중인 작업을 설명하며 이러한 필드를 사용합니다:2751`background_tasks`의 각 항목은 진행 중인 작업 하나를 설명하며 다음 필드를 사용합니다.

2746 2752

2747| 필드 | 설명 |2753| 필드 | 설명 |

2748| :- | :- |2754| :- | :- |

2749| `id` | 작업 식별자 |2755| `id` | 작업 식별자입니다 |

2750| `type` | 친화적 작업 유형 레이블 (예: `shell`, `subagent`, `monitor`, `workflow`, `teammate`, `cloud session`, `MCP task`). 각 레이블은 어느 Claude Code 기능이 작업을 생성했는지 식별합니다. 인식되지 않는 유형의 경우 원본 판별식으로 폴백 |2756| `type` | `shell`, `subagent`, `monitor`, `workflow`, `teammate`, `cloud session`, `MCP task`와 같은 읽기 쉬운 작업 유형 레이블입니다. 각 레이블은 어떤 Claude Code 기능이 작업을 생성했는지 식별합니다. 인식되지 않는 유형의 경우 원시 판별값으로 대체됩니다 |

~~2758~~ 2764

2759`session_crons`의 각 항목은 `CronCreate`, `ScheduleWakeup`, `/loop`에서 소싱된 하나의 세션 범위 예약된 깨어남을 설명합니다:2765`session_crons`의 각 항목은 `CronCreate`, `ScheduleWakeup`, `/loop`에서 가져온 세션 범위의 예약된 깨우기 하나를 설명합니다.

2760 2766

2761| 필드 | 설명 |2767| 필드 | 설명 |

2762| :- | :- |2768| :- | :- |

2763| `id` | Cron 작업 식별자 |2769| `id` | Cron 작업 식별자입니다 |

2767 2773

2768이 예제는 하나의 진행 중인 셸 작업과 하나의 반복 cron이 있는 Stop 입력을 보여줍니다:2774이 예시는 진행 중인 셸 작업 하나와 반복 cron 하나가 있는 Stop 입력을 보여 줍니다.

2769 2775

2770```json theme={null}2776```json theme={null}

2771{2777{

2800 Stop 결정 제어2806 Stop 결정 제어

2801</h4>2807</h4>

2802 2808

2803`Stop` 및 `SubagentStop` hook은 Claude가 계속할지 여부를 제어할 수 있습니다. 모든 hook에 사용 가능한 [JSON 출력 필드](#json-output) 외에도 hook 스크립트는 이러한 이벤트 특정 필드를 반환할 수 있습니다:2809`Stop` 및 `SubagentStop` 훅은 Claude의 계속 진행 여부를 제어할 수 있습니다. 모든 훅에서 사용할 수 있는 [JSON 출력 필드](#json-output) 외에도 훅 스크립트는 다음과 같은 이벤트별 필드를 반환할 수 있습니다.

2804 2810

2805| 필드 | 설명 |2811| 필드 | 설명 |

2806| :- | :- |2812| :- | :- |

2809| `hookSpecificOutput.additionalContext` | 비오류 피드백 Claude. 대화가 계속되므로 Claude가 이에 따라 행동할 수 있지만 `decision: "block"`과 달리 트랜스크립트에 hook 오류가 아닌 hook 피드백으로 표시됩니다 |2815| `hookSpecificOutput.additionalContext` | Claude를 위한 오류가 아닌 피드백입니다. Claude가 이에 따라 조치할 수 있도록 대화가 계속되지만, `decision: "block"`과 달리 트랜스크립트에 훅 오류가 아닌 훅 피드백으로 표시됩니다 |

2810 2816

2811종료 코드 2로 차단하는 hook은 `reason`과 동일한 방식으로 라우팅됩니다: Claude는 stderr 메시지를 계속해야 하는 이유로 받습니다.2817종료 코드 2로 차단하는 훅은 `reason`과 같은 방식으로 전달됩니다. Claude는 stderr 메시지를 계속 진행해야 하는 이유에 대한 설명으로 전달받습니다.

2812 2818

2813```json theme={null}2819```json theme={null}

2814{2820{

2817}2823}

2818```2824```

2819 2825

2820`additionalContext`를 사용하면 hook이 설계대로 작동하고 Claude에 지침을 제공할 때 (예: "완료하기 전에 테스트 스위트를 실행하세요"). 대화를 `decision: "block"`과 동일한 루프 보호를 통해 계속하지만 트랜스크립트는 이를 `Stop hook feedback`으로 표시하고 hook 오류 알림이 표시되지 않습니다:2826훅이 설계대로 작동하면서 "완료하기 전에 테스트 스위트 실행"과 같은 지침을 Claude에게 제공하는 경우 `additionalContext`를 사용합니다. 이 필드는 `decision: "block"`과 같은 루프 보호 장치, 즉 `stop_hook_active` 입력과 연속 계속 진행 8회 제한을 거쳐 대화를 계속 진행하지만, 트랜스크립트에는 `Stop hook feedback`으로 표시되고 훅 오류 알림은 표시되지 않습니다.

2821 2827

2822```json theme={null}2828```json theme={null}

2823{2829{

2832 StopFailure2838 StopFailure

2833</h3>2839</h3>

2834 2840

2835[Stop](#stop) 대신 턴이 API 오류로 인해 종료될 때 실행됩니다. Claude Code는 hook의 출력과 종료 코드를 무시하며 [`terminalSequence`](#emit-terminal-notifications) 제외. 이를 사용하여 실패를 기록하고, 경고를 보내거나, Claude가 API 오류로 인해 응답을 완료할 수 없을 때 복구 조치를 취합니다.2841API 오류로 인해 턴이 종료될 때 [Stop](#stop) 대신 실행됩니다. Claude Code는 [`terminalSequence`](#emit-terminal-notifications)를 제외한 훅의 출력과 종료 코드를 무시합니다. 속도 제한, 인증 문제 또는 기타 API 오류로 인해 Claude가 응답을 완료할 수 없을 때 실패를 로그에 기록하거나, 알림을 보내거나, 복구 조치를 취하는 데 사용합니다.

2836 2842

2837<h4 id="stopfailure-input">2843<h4 id="stopfailure-input">

2838 StopFailure 입력2844 StopFailure 입력

2839</h4>2845</h4>

2840 2846

2841[공통 입력 필드](#common-input-fields) 외에도 StopFailure hook은 `error`, 선택적 `error_details`, 선택적 `last_assistant_message`를 받습니다. `error` 필드는 오류 유형을 식별하며 matcher 필터링에 사용됩니다.2847[공통 입력 필드](#common-input-fields) 외에도 StopFailure 훅은 `error`, 선택적 `error_details`, 선택적 `last_assistant_message`를 전달받습니다. `error` 필드는 오류 유형을 식별하며 matcher 필터링에 사용됩니다.

2842 2848

2843| 필드 | 설명 |2849| 필드 | 설명 |

2844| :- | :- |2850| :- | :- |

2845| `error` | 오류 유형: `rate_limit`, `overloaded`, `authentication_failed`, `oauth_org_not_allowed`, `account_on_hold`, `billing_error`, `invalid_request`, `model_not_found`, `server_error`, `max_output_tokens`, `cloud_credential_error`, 또는 `unknown` |2851| `error` | 오류 유형: `rate_limit`, `overloaded`, `authentication_failed`, `oauth_org_not_allowed`, `account_on_hold`, `billing_error`, `invalid_request`, `model_not_found`, `server_error`, `max_output_tokens`, `cloud_credential_error` 또는 `unknown` |

2847| `last_assistant_message` | 대화에 표시되는 렌더링된 오류 텍스트. `Stop` 및 `SubagentStop`과 달리 이 필드는 Claude의 대화형 출력을 보유하고 `StopFailure`의 경우 `"API Error: Rate limit reached"`와 같은 API 오류 문자열 자체를 포함합니다 |2853| `last_assistant_message` | 대화에 표시된 렌더링된 오류 텍스트입니다. 이 필드에 Claude의 대화 출력이 담기는 `Stop` 및 `SubagentStop`과 달리, `StopFailure`에서는 `"API Error: Rate limit reached"`와 같은 API 오류 문자열 자체가 담깁니다 |

2848 2854

2849```json theme={null}2855```json theme={null}

2850{2856{

2858}2864}

2859```2865```

2860 2866

2861StopFailure hook은 결정 제어가 없습니다. 이들은 알림 및 로깅 목적으로만 실행됩니다.2867StopFailure 훅에는 결정 제어가 없습니다. 알림 및 로깅 목적으로만 실행됩니다.

2862 2868

2863<h3 id="teammateidle">2869<h3 id="teammateidle">

2864 TeammateIdle2870 TeammateIdle

2865</h3>2871</h3>

2866 2872

2867[agent team](/docs/ko/agent-teams) 팀원이 자신의 턴을 마친 후 유휴 상태가 되려고 할 때 실행됩니다. 이를 사용하여 lint 검사 통과 또는 출력 파일 존재 확인과 같은 팀원이 작업을 중지하기 전에 품질 게이트를 적용합니다.2873[에이전트 팀](/docs/ko/agent-teams) 팀원이 턴을 마친 후 유휴 상태가 되려고 할 때 실행됩니다. 린트 검사 통과를 요구하거나 출력 파일이 존재하는지 확인하는 등, 팀원이 작업을 멈추기 전에 품질 기준을 적용하는 데 사용합니다.

2868 2874

2869TeammateIdle hook은 matcher를 지원하지 않으며 모든 발생에서 발생합니다.2875TeammateIdle 훅은 matcher를 지원하지 않으며 매번 발생합니다.

2870 2876

2871<h4 id="teammateidle-input">2877<h4 id="teammateidle-input">

2872 TeammateIdle 입력2878 TeammateIdle 입력

2873</h4>2879</h4>

2874 2880

2875[공통 입력 필드](#common-input-fields) 외에도 TeammateIdle hook은 `teammate_name` 및 `team_name`을 받습니다.2881[공통 입력 필드](#common-input-fields) 외에도 TeammateIdle 훅은 `teammate_name`과 `team_name`을 전달받습니다.

2876 2882

2877```json theme={null}2883```json theme={null}

2878{2884{

2888 2894

2889| 필드 | 설명 |2895| 필드 | 설명 |

2890| :- | :- |2896| :- | :- |

2893 2899

2894<h4 id="teammateidle-decision-control">2900<h4 id="teammateidle-decision-control">

2895 TeammateIdle 결정 제어2901 TeammateIdle 결정 제어

2896</h4>2902</h4>

2897 2903

2898TeammateIdle hook은 팀원 동작을 제어하는 두 가지 방법을 지원합니다:2904TeammateIdle 훅은 팀원 동작을 제어하는 두 가지 방법을 지원합니다.

2899 2905

2900* **종료 코드 2**: 팀원은 stderr 메시지를 피드백으로 받고 유휴 상태가 되는 대신 계속 작업합니다.2906* **종료 코드 2**: 팀원이 stderr 메시지를 피드백으로 받고 유휴 상태가 되는 대신 계속 작업합니다.

2901* **JSON `{"continue": false, "stopReason": "..."}`**: 팀원을 완전히 중지하여 `Stop` hook 동작과 일치합니다. `stopReason`은 사용자에게 표시됩니다.2907* **JSON `{"continue": false, "stopReason": "..."}`**: `Stop` 훅 동작과 마찬가지로 팀원을 완전히 중지합니다. `stopReason`은 사용자에게 표시됩니다.

2902 2908

2903이 예제는 팀원이 유휴 상태가 되도록 허용하기 전에 빌드 아티팩트가 존재하는지 확인합니다:2909이 예시는 팀원이 유휴 상태가 되도록 허용하기 전에 빌드 산출물이 존재하는지 확인합니다.

2904 2910

2905```bash theme={null}2911```bash theme={null}

2906#!/bin/bash2912#!/bin/bash

2917 ConfigChange2923 ConfigChange

2918</h3>2924</h3>

2919 2925

2920세션 중에 구성 파일이 변경될 때 실행됩니다. 이를 사용하여 설정 변경을 감사하고, 보안 정책을 적용하거나, 구성 파일에 대한 무단 수정을 차단합니다.2926세션 중에 설정 파일이 변경될 때 실행됩니다. 설정 변경을 감사하거나, 보안 정책을 적용하거나, 설정 파일에 대한 무단 수정을 차단하는 데 사용합니다.

2921 2927

2922Claude Code는 설정 파일, 관리형 정책 파일, skill 파일의 변경에 대해 ConfigChange hook을 실행합니다. 관리형 정책의 경우 `managed-settings.json` 또는 `managed-settings.d/`의 파일이 변경될 때만 실행합니다. [서버 관리 설정](/docs/ko/server-managed-settings)과 macOS 관리 기본 설정 또는 Windows 레지스트리 정책 변경을 적용하고 실행하지 않습니다. WSL에서 [`wslInheritsWindowsSettings`](/docs/ko/settings-reference#wslinheritswindowssettings)를 사용하면 정책 폴링 중에 변경된 Windows 측 관리 설정 파일도 실행하지 않고 적용합니다.2928Claude Code는 설정 파일, 관리형 정책 파일 또는 스킬 파일이 변경될 때 ConfigChange 훅을 실행합니다. 관리형 정책의 경우 `managed-settings.json` 또는 `managed-settings.d/`의 파일이 변경될 때만 실행합니다. [서버 관리형 설정](/docs/ko/server-managed-settings)과 macOS 관리형 환경설정 또는 Windows 레지스트리 정책의 변경 사항은 훅을 실행하지 않고 적용합니다. [`wslInheritsWindowsSettings`](/docs/ko/settings-reference#wslinheritswindowssettings)가 적용된 WSL에서는 정책 폴링 시 변경된 Windows 측 관리형 설정 파일도 훅을 실행하지 않고 적용합니다.

2923 2929

2924matcher는 구성 소스에서 필터링합니다:2930matcher는 구성 소스를 기준으로 필터링합니다.

2925 2931

2926| Matcher | 언제 발생하는지 |2932| Matcher | 발생 시점 |

2927| :- | :- |2933| :- | :- |

2933 2939

2934이 예제는 보안 감사를 위해 모든 구성 변경을 기록합니다:2940이 예시는 보안 감사를 위해 모든 구성 변경을 로그에 기록합니다.

2935 2941

2936```json theme={null}2942```json theme={null}

2937{2943{

2955 ConfigChange 입력2961 ConfigChange 입력

2956</h4>2962</h4>

2957 2963

2958[공통 입력 필드](#common-input-fields) 외에도 ConfigChange hook은 `source` 및 선택적으로 `file_path`를 받습니다. `source` 필드는 어떤 구성 유형이 변경되었는지 나타내고 `file_path`는 수정된 특정 파일의 경로를 제공합니다.2964[공통 입력 필드](#common-input-fields) 외에도 ConfigChange 훅은 `source`와 선택적으로 `file_path`를 전달받습니다. `source` 필드는 어떤 구성 유형이 변경되었는지 나타내고, `file_path`는 수정된 특정 파일의 경로를 제공합니다.

2959 2965

2960```json theme={null}2966```json theme={null}

2961{2967{

2972 ConfigChange 결정 제어2978 ConfigChange 결정 제어

2973</h4>2979</h4>

2974 2980

2975ConfigChange hook은 구성 변경이 적용되는 것을 차단할 수 있습니다. 종료 코드 2 또는 JSON `decision`을 사용하여 변경을 방지합니다. 차단되면 새 설정이 실행 중인 세션에 적용되지 않습니다.2981ConfigChange 훅은 구성 변경이 적용되지 않도록 차단할 수 있습니다. 변경을 막으려면 종료 코드 2 또는 JSON `decision`을 사용합니다. 차단되면 새 설정이 실행 중인 세션에 적용되지 않습니다.

2976 2982

2977| 필드 | 설명 |2983| 필드 | 설명 |

2978| :- | :- |2984| :- | :- |

2981 2987

2982```json theme={null}2988```json theme={null}

2983{2989{

2986}2992}

2987```2993```

2988 2994

2989`policy_settings` 변경은 차단할 수 없습니다. Hook은 여전히 `policy_settings` 소스에 대해 발생하므로 감사 로깅에 사용할 수 있지만 모든 차단 결정은 무시됩니다. 이는 엔터프라이즈 관리 설정이 항상 적용되도록 보장합니다. Claude Code는 [서버 관리 설정](/docs/ko/server-managed-settings)이 도착하거나 새로 고쳐질 때 ConfigChange hook을 실행하지 않습니다.2995`policy_settings` 변경은 차단할 수 없습니다. 머신의 관리형 설정 파일이 변경되면 `policy_settings` 소스에 대해서도 훅이 발생하므로 해당 편집을 로그에 기록하는 데 사용할 수 있지만, 차단 결정은 무시됩니다. 이를 통해 엔터프라이즈 관리형 설정이 항상 적용되도록 보장합니다. Claude Code는 [서버 관리형 설정](/docs/ko/server-managed-settings)이 도착하거나 새로 고쳐질 때 `ConfigChange` 훅을 실행하지 않습니다.

2990 2996

2991Claude Code는 ConfigChange hook의 JSON 출력에서 차단 결정을 작동하고 `systemMessage` 및 `continue`를 삭제합니다. 차단된 변경은 `reason`이 있거나 종료 코드 2의 stderr이 있는지 여부에 관계없이 메시지를 표시하지 않습니다. Claude Code는 디버그 로그에만 줄을 작성합니다.2997Claude Code는 ConfigChange 훅의 JSON 출력에서 차단 결정에 따라 동작하며 `systemMessage`와 `continue`는 삭제합니다. 차단된 변경은 `reason`으로 차단하든 종료 코드 2의 stderr로 차단하든 사용자나 Claude에게 아무 메시지도 표시하지 않습니다. Claude Code는 디버그 로그에 한 줄만 기록합니다.

2992 2998

2993<h3 id="cwdchanged">2999<h3 id="cwdchanged">

2994 CwdChanged3000 CwdChanged

2995</h3>3001</h3>

2996 3002

2997셸 명령이 메인 대화에서 작업 디렉토리를 변경할 때 실행됩니다 (예: Claude가 `cd` 명령을 실행할 때). 이를 사용하여 디렉토리 변경에 반응합니다: 환경 변수를 다시 로드하고, 프로젝트 특정 도구 체인을 활성화하거나, 설정 스크립트를 자동으로 실행합니다. [FileChanged](#filechanged)와 쌍을 이루어 [direnv](https://direnv.net/)와 같은 디렉토리별 환경을 관리하는 도구를 사용합니다.3003메인 대화의 셸 명령이 작업 디렉터리를 변경할 때 실행됩니다. 예를 들어 Claude가 `cd` 명령을 실행하는 경우입니다. 환경 변수 다시 로드, 프로젝트별 도구 체인 활성화, 설정 스크립트 자동 실행 등 디렉터리 변경에 대응하는 데 사용합니다. 디렉터리별 환경을 관리하는 [direnv](https://direnv.net/)와 같은 도구에는 [FileChanged](#filechanged)와 함께 사용합니다.

2998 3004

2999CwdChanged hook은 `CLAUDE_ENV_FILE`에 액세스할 수 있습니다. 해당 파일에 작성된 변수는 [SessionStart hook](#persist-environment-variables)과 마찬가지로 세션의 후속 Bash 명령에 유지됩니다.3005CwdChanged 훅은 [`CLAUDE_ENV_FILE`](#persist-environment-variables)에 접근할 수 있습니다. 해당 파일에 기록된 변수는 다음 CwdChanged 이벤트에서 Claude Code가 지울 때까지 이후의 Bash 명령에서 유지됩니다.

3000 3006

3001CwdChanged는 matcher를 지원하지 않으며 모든 디렉토리 변경에서 발생합니다.3007CwdChanged는 matcher를 지원하지 않으며 매번 발생합니다.

3002 3008

3003<h4 id="cwdchanged-input">3009<h4 id="cwdchanged-input">

3004 CwdChanged 입력3010 CwdChanged 입력

3005</h4>3011</h4>

3006 3012

3007[공통 입력 필드](#common-input-fields) 외에도 CwdChanged hook은 `old_cwd` 및 `new_cwd`를 받습니다.3013[공통 입력 필드](#common-input-fields) 외에도 CwdChanged 훅은 `old_cwd`와 `new_cwd`를 전달받습니다.

3008 3014

3009```json theme={null}3015```json theme={null}

3010{3016{

3021 CwdChanged 출력3027 CwdChanged 출력

3022</h4>3028</h4>

3023 3029

3024모든 hook에 사용 가능한 [JSON 출력 필드](#json-output) 외에도 CwdChanged hook은 `watchPaths`를 반환하여 [FileChanged](#filechanged)가 감시하는 파일 경로를 동적으로 설정할 수 있습니다:3030모든 훅에서 사용할 수 있는 [JSON 출력 필드](#json-output) 외에도 CwdChanged 훅은 [FileChanged](#filechanged)가 감시하는 파일 경로를 동적으로 설정하기 위해 `watchPaths`를 반환할 수 있습니다.

3025 3031

3026| 필드 | 설명 |3032| 필드 | 설명 |

3027| :- | :- |3033| :- | :- |

3029 3035

3030CwdChanged hook은 결정 제어가 없습니다. 디렉토리 변경을 차단할 수 없습니다.3036CwdChanged 훅에는 결정 제어가 없습니다. 디렉터리 변경을 차단할 수 없습니다.

3031 3037

3032Claude Code는 이들의 JSON 출력에서 `watchPaths` 및 `systemMessage`를 읽고 `continue`를 삭제합니다. 대화형 세션에서 `systemMessage`를 짧은 터미널 알림으로 표시합니다. 메시지는 SDK 메시지 스트림에 도달하지 않습니다.3038Claude Code는 JSON 출력에서 `watchPaths`와 `systemMessage`를 읽고 `continue`는 삭제합니다. 대화형 세션에서는 `systemMessage`를 짧은 터미널 알림으로 표시합니다. 이 메시지는 SDK 메시지 스트림에 도달하지 않습니다.

3033 3039

3034<h3 id="directoryadded">3040<h3 id="directoryadded">

3035 DirectoryAdded3041 DirectoryAdded

3036</h3>3042</h3>

3037 3043

3038[`/add-dir` 명령](/docs/ko/cli-reference#cli-flags)으로 또는 SDK 클라이언트가 `register_repo_root` 제어 요청으로 mid-session에 작업 디렉토리를 추가한 후 실행됩니다. 새로 추가된 리포지토리를 준비하는 데 사용합니다 (예: 종속성 설치).3044세션 중에 사용자가 `/add-dir` 명령으로 작업 디렉터리를 추가한 후, 또는 SDK 클라이언트가 `register_repo_root` 제어 요청으로 작업 디렉터리를 추가한 후에 실행됩니다. 예를 들어 의존성을 설치하는 등 새로 추가된 저장소를 준비하는 데 사용합니다.

3039 3045

3040Claude Code는 다음의 경우 이 이벤트를 발생시키지 않습니다:3046Claude Code는 다음 경우에 이 이벤트를 발생시키지 않습니다.

3041 3047

3042* 시작 시 `--add-dir` 플래그로 디렉토리를 전달합니다; [SessionStart](#sessionstart)가 이러한 디렉토리를 다룹니다3048* `--add-dir` 시작 플래그로 디렉터리를 전달하는 경우. 이러한 디렉터리는 [SessionStart](#sessionstart)에서 다룹니다

3043* `/permissions` Workspace 탭에서 디렉토리를 추가합니다3049* `/permissions` Workspace 탭에서 디렉터리를 추가하는 경우

3044* 이미 작업 디렉토리이거나 그 안에 있는 디렉토리를 추가합니다3050* 이미 작업 디렉터리이거나 작업 디렉터리 내부에 있는 디렉터리를 추가하는 경우

3045 3051

3046Claude Code는 샌드박스 및 권한 상태를 새로 고친 후 DirectoryAdded를 발생시키므로 샌드박스 도구는 hook이 실행될 때 새 디렉토리를 이미 봅니다. Hook 명령 자체는 샌드박스되지 않은 상태로 실행됩니다.3052Claude Code는 샌드박스 및 권한 상태를 새로 고친 후 DirectoryAdded를 발생시키므로, 훅이 실행될 때 샌드박스 처리된 도구는 이미 새 디렉터리를 인식합니다. 훅 명령 자체는 샌드박스 없이 실행됩니다.

3047 3053

3048Claude Code는 hook을 기다리지 않습니다: 추가가 즉시 완료되고 hook은 600초 기본 시간 초과로 백그라운드에서 실행됩니다.3054Claude Code는 훅을 기다리지 않습니다. 추가는 즉시 완료되며, 훅은 600초 기본 타임아웃으로 백그라운드에서 실행됩니다.

3049 3055

3050matcher는 디렉토리가 추가된 방식에 따라 필터링합니다:3056matcher는 디렉터리가 추가된 방식을 기준으로 필터링합니다.

3051 3057

3052| Matcher | 언제 발생하는지 |3058| Matcher | 발생 시점 |

3053| :- | :- |3059| :- | :- |

3056 3062

3057<h4 id="directoryadded-input">3063<h4 id="directoryadded-input">

3058 DirectoryAdded 입력3064 DirectoryAdded 입력

3059</h4>3065</h4>

3060 3066

3061[공통 입력 필드](#common-input-fields) 외에도 DirectoryAdded hook은 `directory` 및 `source`를 받습니다.3067[공통 입력 필드](#common-input-fields) 외에도 DirectoryAdded 훅은 `directory`와 `source`를 전달받습니다.

3062 3068

3063| 필드 | 설명 |3069| 필드 | 설명 |

3064| :- | :- |3070| :- | :- |

3067 3073

3068```json theme={null}3074```json theme={null}

3069{3075{

3076}3082}

3077```3083```

3078 3084

3079DirectoryAdded hook은 결정 제어가 없습니다. 추가를 차단할 수 없으며, 이는 hook이 실행될 때 이미 완료되었습니다. Claude Code는 이들의 JSON 출력에서 `continue` 필드를 삭제하고 소스별로 나머지를 다르게 표시합니다:3085DirectoryAdded 훅에는 결정 제어가 없습니다. 훅이 실행될 때 이미 완료된 추가를 차단할 수 없습니다. Claude Code는 JSON 출력에서 `continue` 필드를 삭제하고 나머지는 소스에 따라 다르게 표시합니다.

3080 3086

3081* `slash_command`: Claude Code는 hook의 `systemMessage`를 Claude에 다음 대화 턴의 컨텍스트로 전달하며, 사용자에게 표시하지 않습니다. 실패한 hook의 개수가 트랜스크립트에 나타납니다. 전체 실패 출력은 디버그 로그로 이동합니다3087* `slash_command`: Claude Code는 훅의 `systemMessage`를 사용자에게 표시하는 대신 다음 대화 턴에서 Claude에게 컨텍스트로 전달합니다. 실패한 훅의 개수가 트랜스크립트에 표시됩니다. 전체 실패 출력은 디버그 로그에 기록됩니다

3082* `register_repo_root`: Claude Code는 `systemMessage` 출력과 실패 출력을 디버그 로그에만 작성합니다3088* `register_repo_root`: Claude Code는 `systemMessage` 출력과 실패 출력을 디버그 로그에만 기록합니다

3083 3089

3084<h3 id="filechanged">3090<h3 id="filechanged">

3085 FileChanged3091 FileChanged

3086</h3>3092</h3>

3087 3093

3088감시된 파일이 디스크에서 변경될 때 실행됩니다. Claude Code는 파일 시스템 감시자로 변경을 감지하므로 어떤 것이 파일을 변경했든 hook이 실행됩니다: `Edit` 또는 `Write` 도구 호출, Claude가 `Bash`로 실행하는 스크립트, 또는 Claude Code 외부의 프로세스. 일반적인 사용은 프로젝트 구성 파일이 수정될 때 환경 변수를 다시 로드하는 것입니다.3094감시 중인 파일이 디스크에서 변경될 때 실행됩니다. Claude Code는 도구 호출을 검사하는 것이 아니라 파일 시스템 감시자로 변경을 감지하므로, `Edit` 또는 `Write` 도구 호출, Claude가 `Bash`로 실행하는 스크립트, Claude Code 외부의 프로세스 등 무엇이 파일을 변경했는지와 관계없이 훅을 실행합니다. 일반적인 용도는 프로젝트 설정 파일이 변경될 때 환경 변수를 다시 로드하는 것입니다.

3089 3095

3090이 이벤트의 `matcher`는 두 가지 역할을 합니다:3096이 이벤트의 `matcher`는 두 가지 역할을 합니다.

3091 3097

3092* **감시 목록 구축**: 값은 `|`로 분할되고 각 세그먼트는 작업 디렉토리의 리터럴 파일명으로 등록되므로 `".envrc|.env"`는 정확히 이 두 파일을 감시합니다. 정규식 패턴은 여기서 유용하지 않습니다: `^\.env`와 같은 값은 `^\.env`라는 리터럴 이름의 파일을 감시합니다.3098* **감시 목록 구성**: 값은 `|`를 기준으로 분할되며 각 세그먼트는 작업 디렉터리의 리터럴 파일 이름으로 등록되므로, `".envrc|.env"`는 정확히 이 두 파일을 감시합니다. 여기서는 정규식 패턴이 유용하지 않습니다. `^\.env`와 같은 값은 문자 그대로 `^\.env`라는 이름의 파일을 감시합니다.

3093* **hook 실행 필터링**: 감시된 파일이 변경되면 동일한 값이 표준 [matcher 규칙](#matcher-patterns)을 사용하여 변경된 파일의 basename에 대해 실행할 hook 그룹을 필터링합니다.3099* **실행할 훅 필터링**: 감시 중인 파일이 변경되면 같은 값이 변경된 파일의 basename에 대해 표준 [matcher 규칙](#matcher-patterns)을 사용하여 실행할 훅 그룹을 필터링합니다.

3094 3100

3095이 예제는 `data.csv`의 줄 끝을 정규화합니다 (Bash 명령 또는 외부 스크립트가 파일을 다시 작성한 후 포함):3101이 예시는 `Bash` 명령이나 외부 스크립트가 파일을 다시 쓰는 경우를 포함하여 `data.csv`가 변경될 때마다 줄 바꿈 문자를 정규화합니다.

3096 3102

3097```json theme={null}3103```json theme={null}

3098{3104{

3112}3118}

3113```3119```

3114 3120

3115hook은 [JSON 입력](#filechanged-input)의 `file_path` 필드에서 변경된 파일의 절대 경로를 stdin에서 읽습니다. `grep` 가드는 `perl`이 제거하는 것과 동일한 것을 테스트합니다 (줄 끝의 CR). 정규화 후 실행은 파일을 건드리지 않고 종료되므로 루프가 없습니다. 더 느슨한 가드는 `perl -i`가 대체하지 않을 때도 파일을 다시 작성하고 Claude Code가 모든 다시 작성 후 hook을 다시 실행하므로 무한 루프를 생성합니다. `/path/to/normalize-line-endings.sh`에 이 스크립트를 저장하고 실행 가능하게 만듭니다:3121훅은 stdin의 [JSON 입력](#filechanged-input)에 있는 `file_path` 필드에서 변경된 파일의 절대 경로를 읽습니다. 훅의 `grep` 가드는 `perl`이 제거하는 것과 같은 대상, 즉 줄 끝의 CR을 검사하므로 정규화 이후의 실행은 파일을 건드리지 않고 종료됩니다. 가드가 더 느슨하면 무한 루프가 발생합니다. `perl -i`는 아무것도 치환하지 않더라도 파일을 다시 쓰고, Claude Code는 파일을 다시 쓸 때마다 훅을 다시 실행하기 때문입니다. 이 스크립트를 `/path/to/normalize-line-endings.sh`에 저장하고 실행 가능하게 만듭니다.

3116 3122

3117```bash theme={null}3123```bash theme={null}

3118#!/bin/bash3124#!/bin/bash

3122fi3128fi

3123```3129```

3124 3130

3125hook이 작동하는지 확인하려면 Claude에 Bash 명령으로 `data.csv`에 CRLF 줄을 추가하도록 요청합니다. Claude Code는 hook을 실행하고 파일은 LF 끝으로 끝납니다.3131훅이 작동하는지 확인하려면 Claude에게 `Bash` 명령으로 `data.csv`에 CRLF 줄을 추가하도록 요청합니다. Claude Code가 훅을 실행하면 파일의 줄 바꿈이 LF로 바뀝니다.

3126 3132

3127미리 이름을 지정할 수 없는 파일을 감시하려면 hook에서 [`watchPaths`](#filechanged-output)를 반환하여 감시 목록을 동적으로 업데이트합니다. Claude Code는 무언가가 감시할 파일을 이름 지정할 때만 감시자를 시작하므로 matcher가 최소 하나의 파일을 이름 지정하는 FileChanged 그룹으로 목록을 시드하거나 [SessionStart](#sessionstart-decision-control) 또는 [CwdChanged](#cwdchanged) hook이 `watchPaths`를 반환합니다. matcher는 감시된 파일이 변경될 때 실행할 hook 그룹을 필터링하므로 동적 경로를 처리하는 그룹에 생략된 matcher를 제공합니다 (모든 감시된 파일과 일치하고 감시 목록에 아무것도 추가하지 않음). `"*"` matcher도 모든 파일과 일치하지만 Claude Code는 다른 값처럼 감시 목록에 `*`라는 리터럴 파일을 등록합니다.3133미리 이름을 지정할 수 없는 파일을 감시하려면 훅에서 [`watchPaths`](#filechanged-output)를 반환하여 감시 목록을 동적으로 업데이트합니다. Claude Code는 감시할 파일이 지정된 경우에만 감시자를 시작하므로, matcher에 하나 이상의 파일 이름을 지정한 FileChanged 그룹이나 `watchPaths`를 반환하는 [SessionStart](#sessionstart-decision-control) 또는 [CwdChanged](#cwdchanged) 훅으로 목록을 초기화합니다. 감시 중인 파일이 변경될 때 matcher는 여전히 실행할 훅 그룹을 필터링하므로, 동적 경로를 처리하는 그룹에는 matcher를 생략합니다. matcher를 생략하면 감시 중인 모든 파일과 매칭되며 감시 목록에는 아무것도 추가되지 않습니다. `"*"` matcher도 모든 파일과 매칭되지만, Claude Code는 이를 다른 값과 마찬가지로 `*`라는 이름의 리터럴 파일로 감시 목록에 등록합니다.

3128 3134

3129FileChanged hook은 `CLAUDE_ENV_FILE`에 액세스할 수 있습니다. 해당 파일에 작성된 변수는 [SessionStart hook](#persist-environment-variables)과 마찬가지로 세션의 후속 Bash 명령에 유지됩니다.3135FileChanged 훅은 [`CLAUDE_ENV_FILE`](#persist-environment-variables)에 접근할 수 있습니다. 해당 파일에 기록된 변수는 다음 [CwdChanged](#cwdchanged) 이벤트에서 Claude Code가 지울 때까지 이후의 Bash 명령에서 유지됩니다.

3130 3136

3131<h4 id="filechanged-input">3137<h4 id="filechanged-input">

3132 FileChanged 입력3138 FileChanged 입력

3133</h4>3139</h4>

3134 3140

3135[공통 입력 필드](#common-input-fields) 외에도 FileChanged hook은 `file_path` 및 `event`를 받습니다.3141[공통 입력 필드](#common-input-fields) 외에도 FileChanged 훅은 `file_path`와 `event`를 전달받습니다.

3136 3142

3137| 필드 | 설명 |3143| 필드 | 설명 |

3138| :- | :- |3144| :- | :- |

3141 3147

3142```json theme={null}3148```json theme={null}

3143{3149{

3154 FileChanged 출력3160 FileChanged 출력

3155</h4>3161</h4>

3156 3162

3157모든 hook에 사용 가능한 [JSON 출력 필드](#json-output) 외에도 FileChanged hook은 `watchPaths`를 반환하여 감시되는 파일 경로를 동적으로 업데이트할 수 있습니다:3163모든 훅에서 사용할 수 있는 [JSON 출력 필드](#json-output) 외에도 FileChanged 훅은 감시할 파일 경로를 동적으로 업데이트하기 위해 `watchPaths`를 반환할 수 있습니다.

3158 3164

3159| 필드 | 설명 |3165| 필드 | 설명 |

3160| :- | :- |3166| :- | :- |

3161| `watchPaths` | 절대 경로의 배열. 현재 동적 감시 목록을 바꿉니다 (matcher 구성의 경로는 항상 감시됨). hook 스크립트가 변경된 파일을 기반으로 감시할 추가 파일을 발견할 때 사용합니다 |3167| `watchPaths` | 절대 경로 배열입니다. 현재 동적 감시 목록을 대체합니다. `matcher` 구성의 경로는 항상 감시됩니다. 훅 스크립트가 변경된 파일을 기반으로 감시할 추가 파일을 발견한 경우에 사용합니다 |

3162 3168

3163FileChanged hook은 결정 제어가 없습니다. 파일 변경을 차단할 수 없습니다.3169FileChanged 훅에는 결정 제어가 없습니다. 파일 변경이 발생하는 것을 차단할 수 없습니다.

3164 3170

3165Claude Code는 이들의 JSON 출력에서 `watchPaths` 및 `systemMessage`를 읽고 `continue`를 삭제합니다. 대화형 세션에서 `systemMessage`를 짧은 터미널 알림으로 표시합니다. 메시지는 SDK 메시지 스트림에 도달하지 않습니다.3171Claude Code는 JSON 출력에서 `watchPaths`와 `systemMessage`를 읽고 `continue`는 삭제합니다. 대화형 세션에서는 `systemMessage`를 짧은 터미널 알림으로 표시합니다. 이 메시지는 SDK 메시지 스트림에 도달하지 않습니다.

3166 3172

3167<h3 id="worktreecreate">3173<h3 id="worktreecreate">

3168 WorktreeCreate3174 WorktreeCreate

3169</h3>3175</h3>

3170 3176

3171`claude --worktree`를 실행하거나 [subagent가 `isolation: "worktree"`를 사용](/docs/ko/sub-agents#choose-the-subagent-scope)할 때 또는 [백그라운드 세션](/docs/ko/agent-view#how-file-edits-are-isolated)을 위해 Claude Code가 자신의 worktree에서 격리할 때 실행됩니다. 기본적으로 Claude Code는 `git worktree`로 격리된 작업 복사본을 생성합니다. WorktreeCreate hook을 구성하면 기본 git 동작을 대체하여 SVN, Perforce 또는 Mercurial과 같은 다른 버전 제어 시스템을 사용할 수 있습니다.3177`claude --worktree`, [`isolation: "worktree"`를 사용하는 서브에이전트](/docs/ko/sub-agents#choose-the-subagent-scope), 또는 Claude Code가 자체 워크트리에 격리하는 [백그라운드 세션](/docs/ko/agent-view#how-file-edits-are-isolated) 등에서 워크트리가 생성될 때 실행됩니다. 기본적으로 Claude Code는 `git worktree`로 격리된 작업 사본을 만듭니다. WorktreeCreate 훅을 구성하면 이 기본 git 동작이 대체되므로 SVN, Perforce, Mercurial과 같은 다른 버전 관리 시스템을 사용할 수 있습니다.

3178

3179훅이 기본 동작을 완전히 대체하므로 [`.worktreeinclude`](/docs/ko/worktrees#copy-gitignored-files-into-worktrees)는 처리되지 않습니다. `.env`와 같은 로컬 설정 파일을 새 워크트리에 복사해야 한다면 훅 스크립트 내부에서 수행합니다.

3172 3180

3173hook은 생성된 worktree 디렉토리의 절대 경로를 반환해야 합니다. Claude Code는 이 경로를 격리된 세션의 작업 디렉토리로 사용합니다. [WorktreeCreate 출력](#worktreecreate-output)을 참조하여 각 hook 유형이 경로를 반환하는 방식을 확인하세요.3181훅은 생성된 worktree 디렉터리의 경로를 반환해야 합니다. Claude Code는 이 경로를 격리된 세션의 작업 디렉터리로 사용합니다. 각 훅 유형이 경로를 반환하는 방법은 [WorktreeCreate 출력](#worktreecreate-output)을 참조하세요.

3174 3182

3175hook이 기본 동작을 완전히 대체하므로 [`.worktreeinclude`](/docs/ko/worktrees#copy-gitignored-files-into-worktrees)는 처리되지 않습니다. `.env`와 같은 로컬 구성 파일을 새 worktree에 복사해야 하면 hook 스크립트 내에서 수행합니다.3183Claude Code는 훅의 성공 여부와 반환된 경로에 따라 동작하며, `systemMessage`와 `continue`는 삭제합니다.

3176 3184

3177이 예제는 SVN 작업 복사본을 생성하고 Claude Code가 사용할 경로를 인쇄합니다. 리포지토리 URL을 자신의 것으로 바꾸세요:3185이 예시는 SVN 작업 사본을 만들고 Claude Code가 사용할 경로를 출력합니다. 저장소 URL을 자신의 것으로 바꾸세요.

3178 3186

3179```json theme={null}3187```json theme={null}

3180{3188{

3193}3201}

3194```3202```

3195 3203

3196hook은 stdin의 JSON 입력에서 worktree `name`을 읽고, 새 디렉토리로 신선한 복사본을 체크아웃하고, 디렉토리 경로를 인쇄합니다. 마지막 줄의 `echo`는 Claude Code가 worktree 경로로 읽는 것입니다. 다른 모든 출력을 stderr로 리디렉션하여 경로를 방해하지 않도록 합니다.3204훅은 stdin의 JSON 입력에서 worktree `name`을 읽고, 새 디렉터리에 새 사본을 체크아웃한 다음, 디렉터리 경로를 출력합니다. 마지막 줄의 `echo`가 Claude Code가 worktree 경로로 읽는 부분입니다. 경로에 간섭하지 않도록 다른 모든 출력은 stderr로 리디렉션합니다.

3197 3205

3198<h4 id="worktreecreate-input">3206<h4 id="worktreecreate-input">

3199 WorktreeCreate 입력3207 WorktreeCreate 입력

3200</h4>3208</h4>

3201 3209

3202[공통 입력 필드](#common-input-fields) 외에도 WorktreeCreate hook은 `name` 필드를 받습니다. 이는 새 worktree의 slug 식별자이며, 사용자가 지정하거나 자동 생성됩니다 (예: `bold-oak-a3f2`).3210[공통 입력 필드](#common-input-fields) 외에도 WorktreeCreate 훅은 `name` 필드를 전달받습니다. 이는 새 워크트리의 슬러그 식별자로, 사용자가 지정하거나 자동 생성되며 예를 들면 `bold-oak-a3f2`와 같습니다.

3203 3211

3204```json theme={null}3212```json theme={null}

3205{3213{

3215 WorktreeCreate 출력3223 WorktreeCreate 출력

3216</h4>3224</h4>

3217 3225

3218WorktreeCreate hook은 표준 허용/차단 결정 모델을 사용하지 않습니다. 대신 hook의 성공 또는 실패가 결과를 결정합니다. hook은 생성된 worktree 디렉토리의 절대 경로를 반환해야 합니다:3226WorktreeCreate 훅은 표준 허용/차단 결정 모델을 사용하지 않습니다. 대신 훅의 성공 또는 실패가 결과를 결정합니다. 훅은 생성된 worktree 디렉터리의 경로를 반환해야 합니다.

3219 3227

3220* **명령 hook** (`type: "command"`): stdout의 마지막 비어 있지 않은 줄로 경로를 인쇄합니다. Claude Code는 경로를 읽기 전에 ANSI 이스케이프 코드를 제거하므로 셸 시작 배너가 `echo` 전에 인쇄되면 무시됩니다. 다른 모든 hook 출력을 stderr로 리디렉션합니다.3228* **명령 훅** (`type: "command"`): 경로를 stdout의 마지막 비어 있지 않은 줄로 출력합니다. Claude Code는 해당 줄을 읽기 전에 ANSI 이스케이프 코드를 제거하므로 `echo` 전에 출력된 셸 시작 배너는 무시됩니다. 그 밖의 훅 출력은 stderr로 리디렉션합니다.

3221* **HTTP hook** (`type: "http"`): 응답 본문에서 `{ "hookSpecificOutput": { "hookEventName": "WorktreeCreate", "worktreePath": "/absolute/path" } }`를 반환합니다.3229* **HTTP 훅** (`type: "http"`): 응답 본문에 `{ "hookSpecificOutput": { "hookEventName": "WorktreeCreate", "worktreePath": "/absolute/path" } }`를 반환합니다.

3222 3230

3223hook이 실패하거나 경로를 생성하지 않으면 worktree 생성이 오류로 실패합니다.3231훅이 실패하거나 경로를 생성하지 않으면 worktree 생성이 오류와 함께 실패합니다.

3224 3232

3225Claude Code는 hook이 실행된 디렉토리에 대해 상대 경로를 해결하고 `.` 또는 `..` 세그먼트를 축소합니다. 결과 경로가 Claude Code가 들어갈 수 있는 디렉토리가 아니면 세션은 경로를 이름으로 지정하는 오류를 인쇄하고 코드 1로 종료됩니다.3233Claude Code는 상대 경로를 훅이 실행된 디렉터리를 기준으로 해석하며, 경로에 포함된 `.` 또는 `..` 세그먼트를 정리합니다. 결과 경로가 Claude Code가 진입할 수 있는 디렉터리가 아니면 세션은 해당 경로를 명시한 오류를 출력하고 코드 1로 종료합니다.

3226 3234

3227Claude Code는 `.` 또는 `..` 세그먼트를 포함하는 절대 경로를 거부하고 리포지토리 루트 아래의 symlink를 통과하는 모든 경로를 거부합니다 (리포지토리에 커밋된 symlink가 worktree를 그 밖으로 리디렉션할 수 있기 때문). 오류는 거부된 구성 요소를 이름으로 지정합니다. 리포지토리 내부의 symlink를 통과하지 않는 정규화된 경로를 반환합니다. v2.1.216 이전에는 worktree 생성이 경로를 검사 없이 따랐습니다.3235Claude Code는 `.` 또는 `..` 세그먼트를 포함하는 절대 경로와 저장소 루트 아래의 심볼릭 링크를 통과하는 모든 경로를 거부합니다. 저장소에 커밋된 심볼릭 링크가 worktree를 저장소 외부로 리디렉션할 수 있기 때문입니다. 오류에는 거부된 구성 요소가 명시됩니다. 저장소 내부의 심볼릭 링크를 통과하지 않는 정규화된 경로를 반환해야 합니다. v2.1.216 이전에는 worktree 생성 시 이러한 검사 없이 훅의 경로를 그대로 따랐습니다.

3228 3236

3229<h3 id="worktreeremove">3237<h3 id="worktreeremove">

3230 WorktreeRemove3238 WorktreeRemove

3231</h3>3239</h3>

3232 3240

3233worktree가 제거될 때 실행됩니다. 이는 [WorktreeCreate](#worktreecreate)의 정리 대응입니다. 이 hook은 다음의 경우 발생합니다:3241worktree가 제거될 때 실행됩니다. [WorktreeCreate](#worktreecreate)에 대응하는 정리용 이벤트입니다. 이 이벤트는 다음과 같은 경우에 발생합니다.

3242

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

3244* `isolation: "worktree"`가 설정된 서브에이전트가 완료된 경우

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

3246

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

3234 3248

3235* `--worktree` 세션을 종료하고 제거하도록 선택합니다3249* **WorktreeRemove 훅이 없는 경우**: `--worktree` 세션을 종료하면서 제거를 선택하면 Claude Code는 WorktreeCreate 훅이 반환한 경로에 대해 `git worktree remove --force`로 폴백하므로, git이 인식하는 worktree는 제거됩니다. git이 인식하지 못하는 worktree(예: 훅이 git 이외의 버전 관리 시스템으로 생성한 worktree)는 디스크에 남습니다. [백그라운드 세션](/docs/ko/agent-view#what-deleting-a-session-removes)을 삭제할 때 훅이 생성한 worktree가 어떻게 처리되는지는 에이전트 뷰의 삭제 규칙을 참조하십시오.

3236* `isolation: "worktree"`를 가진 subagent가 완료됩니다3250* **훅이 0으로 종료하는 경우**: worktree가 제거된 것으로 간주됩니다. Claude Code는 훅에서 다른 정보를 읽지 않으므로 훅이 디렉터리를 실제로 삭제했는지 확인해야 합니다.

3237* [백그라운드 세션](/docs/ko/agent-view#what-deleting-a-session-removes)을 삭제합니다 (hook이 생성한 worktree)3251* **훅이 0이 아닌 코드로 종료하는 경우**: 이후에도 `worktree_path`의 디렉터리가 존재하면 제거가 실패하며, worktree는 git 폴백 없이 디스크에 남습니다. 0이 아닌 코드로 종료하기 전에 디렉터리를 삭제한 훅은 제거된 것으로 간주됩니다. 실패가 보고되는 방식은 [WorktreeRemove 입력](#worktreeremove-input)을 참조하십시오.

3238 3252

3239git 기반 worktree의 경우 Claude Code는 `git worktree remove`로 정리를 자동으로 처리합니다. git이 아닌 버전 제어 시스템에 대해 WorktreeCreate hook을 구성한 경우 정리를 처리하려면 WorktreeRemove hook과 쌍을 이루세요. 없으면 worktree 디렉토리가 디스크에 남아 있습니다.3253Claude Code는 WorktreeCreate 훅이 반환한 경로만 알기 때문에 훅이 생성한 worktree에 속한 브랜치를 삭제하지 않습니다. WorktreeCreate 훅이 브랜치를 생성한다면 WorktreeRemove 훅에서 해당 브랜치를 삭제하십시오.

3240 3254

3241Claude Code는 WorktreeRemove hook의 [JSON 출력 필드](#json-output) (예: `systemMessage`, `continue`)를 삭제합니다.3255Claude Code는 WorktreeRemove 훅의 `systemMessage`, `continue` 등 [JSON 출력 필드](#json-output)를 무시합니다.

3242 3256

3243백그라운드 세션 삭제의 경우 Claude Code는 hook을 실행하기 전에 저장된 worktree 경로를 확인하고 symlink이거나 리포지토리 루트 아래의 symlink를 통과하는 경로를 거부합니다. 여전히 파일을 포함하는 worktree에 대해서는 [agent view](/docs/ko/agent-view#what-deleting-a-session-removes)에서 삭제를 확인할 때만 hook이 실행됩니다; 그러한 worktree의 경우 [`claude rm`](/docs/ko/agent-view#manage-sessions-from-the-shell)은 대신 세션과 worktree를 유지합니다. v2.1.216 이전에는 hook이 이러한 검사 없이 저장된 경로에서 실행되었습니다.3257백그라운드 세션 삭제 시 Claude Code는 훅을 실행하기 전에 저장된 worktree 경로를 검증하며, 심볼릭 링크이거나 저장소 루트 아래의 심볼릭 링크를 통과하는 경로는 거부합니다. 아직 파일이 남아 있는 worktree에 대해서는 [에이전트 뷰](/docs/ko/agent-view#what-deleting-a-session-removes)에서 삭제를 확인한 경우에만 훅이 실행됩니다. 이러한 worktree의 경우 [`claude rm`](/docs/ko/agent-view#manage-sessions-from-the-shell)은 세션과 worktree를 그대로 유지합니다. v2.1.216 이전에는 이러한 검사 없이 저장된 경로에 대해 훅이 실행되었습니다.

3244 3258

3245Claude Code는 WorktreeCreate가 반환한 경로를 hook 입력의 `worktree_path`로 전달합니다. 이 예제는 해당 경로를 읽고 디렉토리를 제거합니다:3259Claude Code는 WorktreeCreate가 반환한 경로를 훅 입력의 `worktree_path`로 전달합니다. 다음 예시는 해당 경로를 읽어 디렉터리를 제거합니다.

3246 3260

3247```json theme={null}3261```json theme={null}

3248{3262{

3265 WorktreeRemove 입력3279 WorktreeRemove 입력

3266</h4>3280</h4>

3267 3281

3268[공통 입력 필드](#common-input-fields) 외에도 WorktreeRemove hook은 제거되는 worktree의 절대 경로인 `worktree_path` 필드를 받습니다.3282[공통 입력 필드](#common-input-fields) 외에도 WorktreeRemove 훅은 제거되는 worktree의 절대 경로인 `worktree_path` 필드를 받습니다.

3269 3283

3270```json theme={null}3284```json theme={null}

3271{3285{

3277}3291}

3278```3292```

3279 3293

3280WorktreeRemove hook의 종료 코드가 결과를 결정합니다. hook이 0이 아닌 코드로 종료되고 `worktree_path`의 디렉토리가 여전히 존재한 후 제거가 실패합니다:3294WorktreeRemove 훅의 종료 코드가 결과를 결정합니다. 훅이 0이 아닌 코드로 종료하고 이후에도 `worktree_path`의 디렉터리가 존재하면 제거가 실패합니다.

3281 3295

3282* worktree는 디스크에 유지되고 hook의 명령과 stderr은 [디버그 로그](#debug-hooks)로 이동합니다.3296* worktree는 디스크에 남으며, 훅의 명령과 stderr는 [디버그 로그](#debug-hooks)에 기록됩니다.

3283* 백그라운드 세션을 삭제하는 경우 세션도 유지됩니다. [agent view](/docs/ko/agent-view#what-deleting-a-session-removes)의 거부 메시지는 hook이 어떻게 끝났는지 (예: `exited 1`)를 보고하고 stderr의 시작을 인용하고 다시 삭제하면 디렉토리를 제거하는지 여부를 말합니다.3297* 백그라운드 세션을 삭제하던 중이었다면 세션도 유지됩니다. [에이전트 뷰](/docs/ko/agent-view#what-deleting-a-session-removes)의 거부 메시지는 `exited 1`과 같이 훅이 어떻게 종료되었는지 보고하고, stderr의 앞부분을 인용하며, 세션을 다시 삭제하면 디렉터리가 어쨌든 제거되는지 여부를 알려 줍니다.

3284 3298

3285<h3 id="precompact">3299<h3 id="precompact">

3286 PreCompact3300 PreCompact

3287</h3>3301</h3>

3288 3302

3289Claude Code가 압축 작업을 실행하려고 하기 전에 실행됩니다.3303Claude Code가 압축 작업을 실행하기 직전에 실행됩니다.

3290 3304

3291matcher 값은 압축이 수동으로 또는 자동으로 트리거되었는지 나타냅니다:3305matcher 값은 압축이 수동으로 트리거되었는지 자동으로 트리거되었는지를 나타냅니다.

3292 3306

3293| Matcher | 언제 발생하는지 |3307| Matcher | 발생 시점 |

3294| :- | :- |3308| :- | :- |

3297 3311

3298종료 코드 2로 압축을 차단합니다. 수동 `/compact`의 경우 stderr 메시지가 사용자에게 표시됩니다. JSON `"decision": "block"`을 사용하여 차단할 수도 있습니다.3312압축을 차단하려면 코드 2로 종료합니다. 수동 `/compact`의 경우 stderr 메시지가 사용자에게 표시됩니다. `"decision": "block"`이 포함된 JSON을 반환하여 차단할 수도 있습니다.

3299 3313

3300자동 압축 차단은 발생 시기에 따라 다른 효과를 가집니다. 컨텍스트 제한 전에 압축이 사전에 트리거된 경우 Claude Code는 이를 건너뛰고 대화가 압축되지 않은 상태로 계속됩니다. 컨텍스트 제한 오류를 복구하기 위해 압축이 트리거된 경우 기본 오류가 표시되고 현재 요청이 실패합니다.3314자동 압축을 차단하면 발생 시점에 따라 효과가 다릅니다. 컨텍스트 한도에 도달하기 전에 선제적으로 압축이 트리거된 경우 Claude Code는 압축을 건너뛰고 압축되지 않은 상태로 대화를 계속합니다. API가 이미 반환한 컨텍스트 한도 오류에서 복구하기 위해 압축이 트리거된 경우에는 원래 오류가 표시되고 현재 요청이 실패합니다.

3301 3315

3302Claude Code는 PreCompact hook의 `systemMessage` 및 `continue` 필드를 삭제합니다.3316Claude Code는 PreCompact 훅의 `systemMessage` 및 `continue` 필드를 무시합니다.

3303 3317

3304<h4 id="precompact-input">3318<h4 id="precompact-input">

3305 PreCompact 입력3319 PreCompact 입력

3306</h4>3320</h4>

3307 3321

3308[공통 입력 필드](#common-input-fields) 외에도 PreCompact hook은 `trigger` 및 `custom_instructions`를 받습니다. `manual`의 경우 `custom_instructions`는 사용자가 `/compact`에 전달하는 것을 포함하고 아무것도 전달하지 않으면 `null`입니다. `auto`의 경우 `custom_instructions`는 `null`입니다.3322[공통 입력 필드](#common-input-fields) 외에도 PreCompact 훅은 `trigger`와 `custom_instructions`를 받습니다. `manual`의 경우 `custom_instructions`에는 사용자가 `/compact`에 전달한 내용이 담기며, 아무것도 전달하지 않으면 `null`입니다. `auto`의 경우 `custom_instructions`는 `null`입니다.

3309 3323

3310```json theme={null}3324```json theme={null}

3311{3325{

3322 PostCompact3336 PostCompact

3323</h3>3337</h3>

3324 3338

3325Claude Code가 압축 작업을 완료한 후 실행됩니다. 이 이벤트를 사용하여 새로운 압축된 상태에 반응합니다 (예: 생성된 요약을 기록하거나 외부 상태를 업데이트). Claude Code는 PostCompact hook의 `systemMessage` 및 `continue` 필드를 삭제합니다.3339Claude Code가 압축 작업을 완료한 후 실행됩니다. 이 이벤트를 사용하여 새로 압축된 상태에 대응할 수 있습니다. 예를 들어 생성된 요약을 로그에 기록하거나 외부 상태를 업데이트할 수 있습니다. Claude Code는 PostCompact 훅의 `systemMessage` 및 `continue` 필드를 무시합니다.

3326 3340

3327`PreCompact`와 동일한 matcher 값이 적용됩니다:3341`PreCompact`와 동일한 matcher 값이 적용됩니다.

3328 3342

3329| Matcher | 언제 발생하는지 |3343| Matcher | 발생 시점 |

3330| :- | :- |3344| :- | :- |

3333 3347

3334<h4 id="postcompact-input">3348<h4 id="postcompact-input">

3335 PostCompact 입력3349 PostCompact 입력

3336</h4>3350</h4>

3337 3351

3338[공통 입력 필드](#common-input-fields) 외에도 PostCompact hook은 `trigger` 및 `compact_summary`를 받습니다. `compact_summary` 필드는 압축 작업에서 생성된 대화 요약을 포함합니다.3352[공통 입력 필드](#common-input-fields) 외에도 PostCompact 훅은 `trigger`와 `compact_summary`를 받습니다. `compact_summary` 필드에는 압축 작업으로 생성된 대화 요약이 담깁니다.

3339 3353

3340```json theme={null}3354```json theme={null}

3341{3355{

3348}3362}

3349```3363```

3350 3364

3351PostCompact hook은 결정 제어가 없습니다. 압축 결과에 영향을 미칠 수 없지만 후속 작업을 수행할 수 있습니다.3365PostCompact 훅에는 결정 제어 기능이 없습니다. 압축 결과에 영향을 줄 수는 없지만 후속 작업을 수행할 수 있습니다.

3352 3366

3353<h3 id="premodelswitch">3367<h3 id="premodelswitch">

3354 PreModelSwitch3368 PreModelSwitch

3355</h3>3369</h3>

3356 3370

3357Claude Code가 사용자 또는 클라이언트가 요청한 모델 전환을 적용하기 전에 실행됩니다. 이를 사용하여 전환을 차단하거나, 확인을 요청하거나, 전환이 발생하기 전에 비용을 표시합니다.3371사용자 또는 클라이언트가 요청한 모델 전환을 Claude Code가 적용하기 전에 실행됩니다. 전환을 차단하거나, 확인을 요구하거나, 전환이 일어나기 전에 전환 비용을 보여 주는 데 사용합니다.

3358 3372

3359PreModelSwitch는 Claude Code v2.1.251 이상이 필요합니다. Claude Code는 이 요청에 대해 실행합니다:3373PreModelSwitch에는 Claude Code v2.1.251 이상이 필요합니다. Claude Code는 다음 요청에 대해 이 훅을 실행합니다.

3360 3374

3361* `/model <name>` 및 `/model` 선택기3375* `/model <name>` 및 `/model` 선택기

3362* `Option+P` 또는 `Alt+P` 모델 선택기3376* `Option+P` 또는 `Alt+P` 모델 선택기

3363* `/config`의 Model 설정3377* `/config`의 Model 설정

3364* [fast mode](/docs/ko/fast-mode)를 켤 때 (모델을 변경하는 경우)3378* 세션의 모델을 변경하는 [빠른 모드](/docs/ko/fast-mode) 켜기

3365* [Agent SDK](/docs/ko/agent-sdk/typescript#query-object) 호스트 또는 [Remote Control](/docs/ko/remote-control)의 `set_model` 요청 또는 `apply_flag_settings` 요청의 모델 변경3379* [Agent SDK](/docs/ko/agent-sdk/typescript#query-object) 호스트 또는 [Remote Control](/docs/ko/remote-control)의 `set_model` 요청, 또는 `apply_flag_settings` 요청에 포함된 모델 변경

3366 3380

3367Claude Code는 자동 모델 폴백과 같이 Claude Code가 자체적으로 수행하는 전환에 대해 PreModelSwitch hook을 실행하지 않습니다. 이러한 변경은 [PostModelSwitch](#postmodelswitch)에만 도달합니다.3381Claude Code는 [자동 모델 폴백](/docs/ko/model-config#automatic-model-fallback)이나 세션 재개 시 모델 복원처럼 자체적으로 수행하는 전환에 대해서는 PreModelSwitch 훅을 실행하지 않습니다. 이러한 변경은 [PostModelSwitch](#postmodelswitch)에만 전달됩니다.

3368 3382

3369Claude Code는 matcher를 세션이 전환되는 모델의 정규 이름과 비교하고 `[1m]` 접미사를 무시합니다. `opus`, 날짜 모델 ID, Amazon Bedrock 모델 ID와 같은 공급자 특정 ID와 같은 별칭은 모두 해결되는 하나의 정규 이름과 일치하므로 `claude-opus-5`는 Opus 5의 모든 철자를 다룹니다.3383Claude Code는 `[1m]` 접미사를 무시하고, 세션이 전환하려는 모델의 정식 이름과 matcher를 비교합니다. `opus`와 같은 별칭, 날짜가 포함된 모델 ID, Amazon Bedrock 모델 ID와 같은 제공업체별 ID는 모두 해석 결과인 하나의 정식 이름과 일치하므로, `claude-opus-5`는 Opus 5의 모든 표기를 포괄합니다.

3370 3384

3371Claude Code가 대상의 정규 이름을 결정할 수 없을 때 (예: [LLM gateway](/docs/ko/llm-gateway)만 알고 있는 사용자 정의 모델 ID) matcher와 관계없이 모든 PreModelSwitch hook을 실행합니다. 차단하는 hook은 입력에서 `to_model`을 확인해야 합니다.3385[LLM 게이트웨이](/docs/ko/llm-gateway)만 아는 사용자 지정 모델 ID처럼 Claude Code가 대상의 정식 이름을 확인할 수 없는 경우에는 matcher와 관계없이 모든 PreModelSwitch 훅을 실행합니다. 따라서 차단하는 훅은 matcher에만 의존하지 말고 입력의 `to_model`을 확인해야 합니다.

3372 3386

3373matcher를 정확한 이름, `|`로 분리된 목록 (예: `claude-opus-4-6|claude-opus-5`) 또는 정규식 (예: `.*opus.*`)으로 작성합니다. 이 예제는 정확한 이름 matcher를 사용하고 hook 입력에서 `to_model`을 확인하므로 Opus 4.6으로의 전환을 거부하고 다른 대상을 허용합니다:3387matcher는 정확한 이름, `claude-opus-4-6|claude-opus-5`와 같은 `|`로 구분된 목록, 또는 `.*opus.*`와 같은 정규식으로 작성합니다. 다음 예시는 정확한 이름 matcher를 사용하면서 훅 입력의 `to_model`도 확인하므로, 코드 2로 종료하여 Opus 4.6으로의 전환을 거부하고 다른 대상은 허용합니다.

3374 3388

3375<Tabs>3389<Tabs>

3376 <Tab title="macOS/Linux">3390 <Tab title="macOS/Linux">

3377 명령은 `jq`로 `to_model`을 확인합니다:3391 명령이 `jq`로 `to_model`을 확인합니다.

3378 3392

3379 ```json theme={null}3393 ```json theme={null}

3380 {3394 {

3396 </Tab>3410 </Tab>

3397 3411

3398 <Tab title="Windows (PowerShell)">3412 <Tab title="Windows (PowerShell)">

3399 PowerShell을 통해 스크립트를 실행하는 명령 hook을 등록합니다:3413 PowerShell을 통해 스크립트를 실행하는 명령 훅을 등록합니다.

3400 3414

3401 ```json theme={null}3415 ```json theme={null}

3402 {3416 {

3423 }3437 }

3424 ```3438 ```

3425 3439

3426 이 스크립트를 프로젝트의 `.claude/hooks/block-opus-46.ps1`에 저장합니다:3440 다음 스크립트를 프로젝트의 `.claude/hooks/block-opus-46.ps1`에 저장합니다.

3427 3441

3428 ```powershell theme={null}3442 ```powershell theme={null}

3429 $hookInput = [Console]::In.ReadToEnd() | ConvertFrom-Json3443 $hookInput = [Console]::In.ReadToEnd() | ConvertFrom-Json

3436 </Tab>3450 </Tab>

3437</Tabs>3451</Tabs>

3438 3452

3439hook이 작동하는지 확인하려면 다른 모델을 실행하는 세션에서 `/model claude-opus-4-6`을 실행합니다. Claude Code는 현재 모델을 유지하고 PreModelSwitch hook이 전환을 차단했음을 보고하며 메시지를 이유로 표시합니다.3453훅이 작동하는지 확인하려면 다른 모델을 실행 중인 세션에서 `/model claude-opus-4-6`을 실행합니다. Claude Code는 현재 모델을 유지하고, PreModelSwitch 훅이 전환을 차단했다고 보고하며, 작성한 메시지를 이유로 표시합니다.

3440 3454

3441<h4 id="premodelswitch-input">3455<h4 id="premodelswitch-input">

3442 PreModelSwitch 입력3456 PreModelSwitch 입력

3443</h4>3457</h4>

3444 3458

3445[공통 입력 필드](#common-input-fields) 외에도 PreModelSwitch hook은 아래 표의 필드를 받습니다. 마지막 다섯 개는 새 모델로 대화를 다시 전송하는 비용을 설명하므로 hook은 전환이 발생하기 전에 해당 수치를 표시할 수 있습니다.3459[공통 입력 필드](#common-input-fields) 외에도 PreModelSwitch 훅은 다음 표의 필드를 받습니다. 마지막 다섯 개 필드는 대화를 새 모델로 다시 전송하는 비용을 설명하므로, 훅은 전환이 일어나기 전에 해당 수치를 보여 줄 수 있습니다.

3446 3460

3447| 필드 | 유형 | 설명 |3461| 필드 | 유형 | 설명 |

3448| :- | :- | :- |3462| :- | :- | :- |

3452| `source` | 문자열 | 요청이 어디에서 왔는지: `/model <name>`, `/config`의 Model 설정, 또는 fast mode 켜기의 경우 `"command"`, 모델 선택기의 경우 `"picker"`, Agent SDK 호스트 또는 Remote Control의 `set_model` 요청 또는 `apply_flag_settings` 요청의 경우 `"sdk"` |3466| `source` | string | 요청의 출처: `/model <name>`, `/config`의 Model 설정 또는 빠른 모드 켜기의 경우 `"command"`, 모델 선택기의 경우 `"picker"`, Agent SDK 호스트 또는 Remote Control의 `set_model` 요청이나 `apply_flag_settings` 요청의 모델 변경의 경우 `"sdk"` |

3456| `estimated_cache_write_usd` | 숫자 | `to_model`의 `cache_ttl` 속도에서 prompt cache에 `context_tokens`을 쓰는 예상 비용 (미국 달러), 다음 응답 제외. 서버가 전체 컨텍스트를 다시 캐시할 필요가 없을 수 있으므로 추정값으로 취급합니다 |3470| `estimated_cache_write_usd` | number | `to_model`에서 `cache_ttl` 요율로 `context_tokens`를 프롬프트 캐시에 쓰는 예상 비용(미화 달러). 다음 응답은 제외됩니다. 서버가 전체 컨텍스트를 다시 캐싱할 필요가 없을 수도 있으므로 추정치로 취급하십시오 |

3457| `pricing` | 문자열 | Claude Code가 `estimated_cache_write_usd`를 가격 책정한 방식: 조직이 구성한 경우 `"configured"` (자신의 속도), 목록 가격의 경우 `"catalog"`, `to_model`에 알려진 가격이 없고 Claude Code가 기본 속도를 가정한 경우 `"default"` |3471| `pricing` | string | Claude Code가 `estimated_cache_write_usd`의 가격을 산정한 방식: 조직이 자체 요율을 구성한 경우 해당 요율을 적용한 `"configured"`, 정가를 적용한 `"catalog"`, `to_model`의 가격을 알 수 없어 Claude Code가 기본 요율을 가정한 경우 `"default"` |

~~3458~~ 3472

3459이 예제는 Sonnet 5를 실행하는 세션에서 `/model opus`에 대한 입력을 보여줍니다:3473다음 예시는 Sonnet 5를 실행 중인 세션에서 `/model opus`를 실행할 때의 입력을 보여 줍니다.

3460 3474

3461```json theme={null}3475```json theme={null}

3462{3476{

3480 PreModelSwitch 결정 제어3494 PreModelSwitch 결정 제어

3481</h4>3495</h4>

3482 3496

3483`PreModelSwitch` hook은 전환을 취소하거나, 사용자에게 확인을 요청하거나, 진행하도록 허용할 수 있습니다. 종료 코드 2 또는 최상위 `decision: "block"`은 전환을 취소합니다.3497`PreModelSwitch` 훅은 전환을 취소하거나, 사용자에게 확인을 요청하거나, 전환을 진행하도록 할 수 있습니다. 종료 코드 2 또는 최상위 수준의 `decision: "block"`은 전환을 취소합니다.

3484 3498

3485더 세밀한 제어를 위해 [PreToolUse](#pretooluse-decision-control)처럼 `hookSpecificOutput` 객체에서 `permissionDecision` 및 `permissionDecisionReason`을 반환합니다. `PreModelSwitch`는 `"allow"`, `"deny"`, `"ask"`를 수락합니다. `"defer"`, `updatedInput`, `additionalContext`는 수락하지 않습니다. 아래 표는 두 필드를 설명합니다:3499보다 세밀하게 제어하려면 [PreToolUse](#pretooluse-decision-control)와 마찬가지로 `hookSpecificOutput` 객체에 `permissionDecision`과 `permissionDecisionReason`을 반환합니다. `PreModelSwitch`는 `"allow"`, `"deny"`, `"ask"`를 허용합니다. `"defer"`, `updatedInput`, `additionalContext`는 허용하지 않습니다. 아래 표에서 두 필드를 설명합니다.

3486 3500

3487| 필드 | 설명 |3501| 필드 | 설명 |

3488| :- | :- |3502| :- | :- |

3489| `permissionDecision` | `"allow"`는 진행하고 [prompt cache가 따뜻할 때 Claude Code가 표시하는 확인](/docs/ko/prompt-caching#switching-models)을 건너뜁니다. `"deny"`는 전환을 취소합니다. `"ask"`는 사용자에게 확인을 요청합니다 |3503| `permissionDecision` | `"allow"`는 전환을 진행하며 [프롬프트 캐시가 웜 상태일 때 Claude Code가 표시하는 확인](/docs/ko/prompt-caching#switching-models)을 건너뜁니다. `"deny"`는 전환을 취소합니다. `"ask"`는 사용자에게 확인을 요청합니다 |

3490| `permissionDecisionReason` | `"deny"`의 경우 사용자에게 전환이 차단된 이유로 표시되거나 `set_model` 요청에 대한 오류로 반환됩니다. `"ask"`의 경우 확인 프롬프트에 표시됩니다. `"allow"`의 경우 무시됩니다 |3504| `permissionDecisionReason` | `"deny"`의 경우 전환이 차단된 이유로 사용자에게 표시되거나, `set_model` 요청에 대한 오류로 반환됩니다. `"ask"`의 경우 확인 프롬프트에 표시됩니다. `"allow"`의 경우 무시됩니다 |

3491 3505

3492`"ask"` 프롬프트는 대화형 세션에서 `/model`만 표시할 수 있습니다. 비대화형 모드 (`-p` 플래그), `/config`, `set_model` 요청을 포함한 다른 모든 표면에서 Claude Code는 `"ask"`를 거부로 취급합니다.3506대화형 세션의 `/model`만 `"ask"` 프롬프트를 표시할 수 있습니다. `-p` 플래그를 사용하는 비대화형 모드, `/config`, `set_model` 요청을 포함한 다른 모든 사용 환경에서는 Claude Code가 `"ask"`를 거부로 처리합니다.

3493 3507

3494이 예제는 사용자에게 확인을 요청하고 `context_tokens`의 토큰 수를 인용합니다:3508다음 예시는 사용자에게 확인을 요청하며 `context_tokens`의 토큰 수를 인용합니다.

3495 3509

3496```json theme={null}3510```json theme={null}

3497{3511{

3503}3517}

3504```3518```

3505 3519

3506여러 PreModelSwitch hook이 다른 결정을 반환할 때 우선순위는 `deny` > `ask` > `allow`입니다.3520여러 PreModelSwitch 훅이 서로 다른 결정을 반환하면 우선순위는 `deny` > `ask` > `allow`입니다.

3507 3521

3508Claude Code는 결정과 관계없이 hook이 반환하는 모든 `systemMessage`를 사용자에게 표시하므로 비용 보고 hook은 `{"systemMessage": "..."}` 및 종료 0을 반환할 수 있습니다.3522Claude Code는 결정과 관계없이 훅이 반환한 `systemMessage`를 사용자에게 표시하므로, 비용 보고 훅은 `{"systemMessage": "..."}`를 반환하고 0으로 종료할 수 있습니다.

3509 3523

3510시간 초과 전에 응답하지 않는 PreModelSwitch hook은 전환을 차단합니다. 대조적으로 [PreToolUse](#timeouts)에서는 시간 초과된 명령 hook이 도구 호출이 계속되도록 허용합니다. 이 이벤트의 기본 시간 초과는 30초입니다. `PreModelSwitch`는 `command`, `http`, `mcp_tool` hook만 실행하므로 `prompt` 및 `agent` 기본값은 적용되지 않습니다.3524타임아웃 전에 응답하지 않는 PreModelSwitch 훅은 전환을 차단합니다. 반면 [PreToolUse](#timeouts)에서는 시간 초과된 명령 훅이 도구 호출을 계속 진행하도록 합니다. 이 이벤트의 기본 타임아웃은 30초입니다. `PreModelSwitch`는 `command`, `http`, `mcp_tool` 훅만 실행하므로 `prompt` 및 `agent` 기본값은 적용되지 않습니다.

3511 3525

35120 또는 2 이외의 코드로 종료하고 JSON 결정을 인쇄하지 않는 hook은 차단하지 않습니다: Claude Code는 stderr을 표시하고 [다른 종료 코드](#other-exit-codes)에서 설명한 대로 전환을 적용합니다.35260 또는 2 이외의 코드로 종료하고 JSON 결정을 출력하지 않는 훅은 차단하지 않습니다. [기타 종료 코드](#other-exit-codes)에 설명된 대로 Claude Code는 해당 stderr를 표시하고 전환을 적용합니다.

3513 3527

3514<h3 id="postmodelswitch">3528<h3 id="postmodelswitch">

3515 PostModelSwitch3529 PostModelSwitch

3516</h3>3530</h3>

3517 3531

3518세션의 모델이 변경된 후 실행됩니다. 모든 CLAUDE.md를 편집하지 않고 특정 모델에 적용되는 모델 특정 지침을 Claude에 제공하는 데 사용합니다 (예: 조직 전체 명령).3532세션의 모델이 변경된 후 실행됩니다. 모든 CLAUDE.md를 편집하지 않고도 Claude에게 모델별 지침을 제공하는 데 사용합니다. 예를 들어 특정 모델에 적용되는 조직 전체 지침을 제공할 수 있습니다.

3519 3533

3520PostModelSwitch는 Claude Code v2.1.251 이상이 필요합니다. 차단할 수 없습니다 (모델이 이미 변경되었기 때문). Claude Code는 다음 변경 후 PostModelSwitch hook을 실행합니다:3534PostModelSwitch에는 Claude Code v2.1.251 이상이 필요합니다. 모델이 이미 변경된 후이므로 차단할 수 없습니다. Claude Code는 다음 변경 후에 PostModelSwitch 훅을 실행합니다.

3521 3535

3522* 사용자 또는 클라이언트가 요청한 전환3536* 사용자 또는 클라이언트가 요청한 전환

3523* [자동 모델 폴백](/docs/ko/model-config#automatic-model-fallback) (세션의 모델을 변경)3537* 세션의 모델을 변경하는 [자동 모델 폴백](/docs/ko/model-config#automatic-model-fallback)

3524* [`opusplan`](/docs/ko/model-config#opusplan-model-setting)과 같은 설정이 plan 모드에 들어가거나 나갈 때3538* [`opusplan`](/docs/ko/model-config#opusplan-model-setting)과 같은 설정에서 플랜 모드에 진입하거나 플랜 모드를 벗어나는 경우

3525* Claude Code가 세션을 재개할 때 모델을 복원합니다3539* 세션 재개 시 Claude Code가 모델을 복원하는 경우

3526 3540

3527Claude Code는 [폴백 모델 체인](/docs/ko/model-config#fallback-model-chains)의 모델이 턴을 제공할 때 PostModelSwitch hook을 실행하지 않습니다 (해당 대체는 한 턴 지속되고 세션의 모델을 변경하지 않음).3541[폴백 모델 체인](/docs/ko/model-config#fallback-model-chains)의 모델이 턴을 처리하는 경우에는 Claude Code가 PostModelSwitch 훅을 실행하지 않습니다. 해당 대체는 한 턴 동안만 지속되며 세션의 모델을 변경하지 않기 때문입니다.

3528 3542

3529matcher는 [PreModelSwitch](#premodelswitch)와 동일한 규칙을 따릅니다: Claude Code는 세션이 전환되는 모델의 정규 이름과 비교합니다.3543matcher는 [PreModelSwitch](#premodelswitch)와 동일한 규칙을 따릅니다. Claude Code는 세션이 전환된 모델의 정식 이름과 matcher를 비교합니다.

3530 3544

3531이 예제는 세션의 모델이 Opus 모델로 변경될 때마다 지침을 추가합니다:3545다음 예시는 세션의 모델이 Opus 모델로 변경될 때마다 지침을 추가합니다.

3532 3546

3533```json theme={null}3547```json theme={null}

3534{3548{

3548}3562}

3549```3563```

3550 3564

3551hook이 작동하는지 확인하려면 다른 모델을 실행하는 세션에서 Opus 모델로 전환합니다 (예: Sonnet 세션에서 `/model opus` 실행). 그런 다음 Claude에 현재 모델에 대한 지침이 무엇인지 물어봅니다.3565훅이 작동하는지 확인하려면 다른 모델을 실행 중인 세션에서 Opus 모델로 전환한 다음(예: Sonnet 세션에서 `/model opus` 실행), 현재 모델에 대해 어떤 지침을 가지고 있는지 Claude에게 물어보십시오.

3552 3566

3553<h4 id="postmodelswitch-input">3567<h4 id="postmodelswitch-input">

3554 PostModelSwitch 입력3568 PostModelSwitch 입력

3555</h4>3569</h4>

3556 3570

3557PostModelSwitch hook은 [PreModelSwitch](#premodelswitch-input)와 동일한 필드를 받으며 `hook_event_name`은 `"PostModelSwitch"`로 설정되고 두 개의 추가 `source` 값이 있습니다: Claude Code가 자체적으로 수행한 변경의 경우 `"auto"` (자동 폴백 또는 기타 변경), 세션을 재개할 때 복원된 모델의 경우 `"resume"`.3571PostModelSwitch 훅은 [PreModelSwitch](#premodelswitch-input)와 동일한 필드를 받으며, `hook_event_name`은 `"PostModelSwitch"`로 설정되고 `source` 값이 두 가지 추가됩니다. 자동 폴백 또는 Claude Code가 자체적으로 수행한 기타 변경의 경우 `"auto"`, 세션 재개 시 복원된 모델의 경우 `"resume"`입니다.

3558 3572

3559`requested_model`은 `source`가 `"auto"`일 때 `null`입니다. `source`가 `"resume"`일 때 Claude Code가 복원한 저장된 모델 설정입니다.3573`source`가 `"auto"`이면 `requested_model`은 `null`입니다. `source`가 `"resume"`이면 Claude Code가 복원한 저장된 모델 설정입니다.

3560 3574

3561<h4 id="postmodelswitch-decision-control">3575<h4 id="postmodelswitch-decision-control">

3562 PostModelSwitch 결정 제어3576 PostModelSwitch 결정 제어

3563</h4>3577</h4>

3564 3578

3565Claude Code는 hook의 [일반 텍스트 stdout](#exit-code-0)을 종료 0에서 가져오거나 JSON 출력에서 `additionalContext`를 가져오고 전환 후 다음 요청과 함께 Claude에 전달합니다. 모든 hook에 사용 가능한 [JSON 출력 필드](#json-output) 외에도 다음을 반환할 수 있습니다:3579Claude Code는 종료 코드 0일 때 훅의 [일반 텍스트 stdout](#exit-code-0) 또는 JSON 출력의 `additionalContext`를 가져와, 전환 후 다음 요청과 함께 Claude에게 전달합니다. 모든 훅에서 사용할 수 있는 [JSON 출력 필드](#json-output) 외에도 다음을 반환할 수 있습니다.

3566 3580

3567| 필드 | 설명 |3581| 필드 | 설명 |

3568| :- | :- |3582| :- | :- |

3570 3584

3571다음 프롬프트를 보낸 후 5초 이내에 hook이 완료되지 않으면 Claude Code는 해당 출력 없이 그 요청을 보내고 대신 그다음 요청에 첨부합니다. 다음 요청 전에 모델이 여러 번 변경되면 Claude Code는 마지막 전환의 대상 모델에 대한 출력만 전달합니다.3585다음 프롬프트를 보낸 후 5초 이내에 훅이 완료되지 않으면 Claude Code는 출력 없이 해당 요청을 보내고 대신 그다음 요청에 출력을 첨부합니다. 다음 요청 전에 모델이 여러 번 변경되면 Claude Code는 마지막 전환의 대상 모델에 대한 출력만 전달합니다.

3572 3586

3573<h3 id="sessionend">3587<h3 id="sessionend">

3574 SessionEnd3588 SessionEnd

3575</h3>3589</h3>

3576 3590

3577Claude Code 세션이 종료될 때 실행됩니다. 정리 작업, 세션 통계 로깅 또는 세션 상태 저장에 유용합니다. 종료 이유별로 필터링할 matcher를 지원합니다.3591Claude Code 세션이 종료될 때 실행됩니다. 정리 작업, 세션

3592통계 로깅 또는 세션 상태 저장에 유용합니다. 종료 이유로 필터링하는 matcher를 지원합니다.

3578 3593

3579hook 입력의 `reason` 필드는 세션이 종료된 이유를 나타냅니다:3594훅 입력의 `reason` 필드는 세션이 종료된 이유를 나타냅니다.

3580 3595

3581| 이유 | 설명 |3596| 이유 | 설명 |

3582| :- | :- |3597| :- | :- |

3589 3604

3590<h4 id="sessionend-input">3605<h4 id="sessionend-input">

3591 SessionEnd 입력3606 SessionEnd 입력

3592</h4>3607</h4>

3593 3608

3594[공통 입력 필드](#common-input-fields) 외에도 SessionEnd hook은 세션이 종료된 이유를 나타내는 `reason` 필드를 받습니다. 모든 값은 위의 [이유 표](#sessionend)를 참조하세요.3609[공통 입력 필드](#common-input-fields) 외에도 SessionEnd 훅은 세션이 종료된 이유를 나타내는 `reason` 필드를 받습니다. 모든 값은 위의 [이유 표](#sessionend)를 참조하십시오.

3595 3610

3596```json theme={null}3611```json theme={null}

3597{3612{

3603}3618}

3604```3619```

3605 3620

3606SessionEnd hook은 결정 제어가 없습니다. 세션 종료를 차단할 수 없지만 정리 작업을 수행할 수 있습니다. Claude Code는 이들의 [JSON 출력 필드](#json-output) (예: `systemMessage`)를 삭제합니다.3621SessionEnd 훅에는 결정 제어 기능이 없습니다. 세션 종료를 차단할 수는 없지만 정리 작업을 수행할 수 있습니다. Claude Code는 `systemMessage` 등 해당 훅의 [JSON 출력 필드](#json-output)를 무시합니다.

3607 3622

3608SessionEnd hook의 기본 시간 초과는 1.5초입니다. 이는 세션 종료, `/clear`, 대화형 `/resume`을 통한 세션 전환 모두에 적용됩니다. hook에 더 많은 시간이 필요하면 hook 구성에서 `timeout`을 설정합니다. 전체 예산은 설정 파일의 가장 높은 hook별 `timeout`으로 자동으로 올라가며, 최대 60초입니다. plugin 제공 hook에 설정된 시간 초과는 예산을 올리지 않습니다. 예산을 명시적으로 재정의하려면 `CLAUDE_CODE_SESSIONEND_HOOKS_TIMEOUT_MS` 환경 변수를 밀리초 단위로 설정합니다. 설정한 값은 또한 자신의 `timeout`이 없는 각 hook의 시간 초과가 됩니다.3623SessionEnd 훅의 기본 타임아웃은 1.5초입니다. 이 타임아웃은 종료할 때, `/clear`를 실행할 때, 또는 대화형 `/resume`으로 세션을 전환할 때 적용됩니다. 훅에 더 많은 시간을 주는 방법은 두 가지입니다.

3609 3624

3610이 예제는 예산을 5초로 설정합니다:3625* **훅별 `timeout`**: 해당 훅의 구성에서 `timeout`을 설정합니다. 전체 허용 시간은 설정 파일에 있는 가장 높은 훅별 `timeout`에 맞춰 최대 60초까지 자동으로 늘어납니다. 이 방식으로 허용 시간을 늘려도 자체 `timeout`이 없는 훅은 여전히 기본값을 유지합니다. 플러그인이 제공하는 훅에 설정된 타임아웃은 허용 시간을 늘리지 않습니다.

3626* **`CLAUDE_CODE_SESSIONEND_HOOKS_TIMEOUT_MS`**: 이 환경 변수를 밀리초 단위로 설정하여 허용 시간을 명시적으로 재정의합니다. 설정한 값은 자체 `timeout`이 없는 각 훅의 타임아웃으로도 사용됩니다.

3627

3628다음 예시는 허용 시간을 5초로 설정합니다.

3611 3629

3612```bash theme={null}3630```bash theme={null}

3613CLAUDE_CODE_SESSIONEND_HOOKS_TIMEOUT_MS=5000 claude3631CLAUDE_CODE_SESSIONEND_HOOKS_TIMEOUT_MS=5000 claude

3614```3632```

3615 3633

3616v2.1.268 이전에는 `CLAUDE_CODE_SESSIONEND_HOOKS_TIMEOUT_MS`가 전체 예산만 올렸고 자신의 `timeout`이 없는 hook은 여전히 1.5초 후 취소되었습니다.3634v2.1.268 이전에는 `CLAUDE_CODE_SESSIONEND_HOOKS_TIMEOUT_MS`가 전체 허용 시간만 늘렸으며, 자체 `timeout`이 없는 훅은 여전히 1.5초 후에 취소되었습니다.

3617 3635

3618<h3 id="elicitation">3636<h3 id="elicitation">

3619 Elicitation3637 Elicitation

3620</h3>3638</h3>

3621 3639

3622MCP 서버가 작업 중 사용자 입력을 요청할 때 실행됩니다. 기본적으로 Claude Code는 사용자가 응답할 수 있는 대화형 대화 상자를 표시합니다. Hook은 이 요청을 가로채고 프로그래밍 방식으로 응답하여 대화 상자를 완전히 건너뛸 수 있습니다.3640MCP 서버가 작업 도중 사용자 입력을 요청할 때 실행됩니다. 기본적으로 Claude Code는 사용자가 응답할 수 있도록 대화형 대화 상자를 표시합니다. 훅은 이 요청을 가로채 프로그래밍 방식으로 응답하여 대화 상자를 완전히 건너뛸 수 있습니다.

3623 3641

3624matcher 필드는 MCP 서버 이름과 일치합니다.3642matcher 필드는 MCP 서버 이름과 비교됩니다.

3625 3643

3626<h4 id="elicitation-input">3644<h4 id="elicitation-input">

3627 Elicitation 입력3645 Elicitation 입력

3628</h4>3646</h4>

3629 3647

3630[공통 입력 필드](#common-input-fields) 외에도 Elicitation hook은 `mcp_server_name`, `message`, 선택적으로 `mode`, `url`, `elicitation_id`, `requested_schema` 필드를 받습니다.3648[공통 입력 필드](#common-input-fields) 외에도 Elicitation 훅은 `mcp_server_name`, `message` 및 선택적 필드인 `mode`, `url`, `elicitation_id`, `requested_schema`를 받습니다.

3631 3649

3632form 모드 elicitation (가장 일반적인 경우):3650가장 일반적인 경우인 폼 모드 elicitation의 예시입니다.

3633 3651

3634```json theme={null}3652```json theme={null}

3635{3653{

3636 "session_id": "abc123",3654 "session_id": "abc123",

3637 "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",3655 "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",

3638 "cwd": "/Users/...",3656 "cwd": "/Users/...",

3639 "permission_mode": "default",

3640 "hook_event_name": "Elicitation",3657 "hook_event_name": "Elicitation",

3641 "mcp_server_name": "my-mcp-server",3658 "mcp_server_name": "my-mcp-server",

3642 "message": "Please provide your credentials",3659 "message": "Please provide your credentials",

3650}3667}

3651```3668```

3652 3669

3653URL 모드 elicitation (브라우저 기반 인증):3670브라우저 기반 인증에 사용되는 URL 모드 elicitation의 예시입니다.

3654 3671

3655```json theme={null}3672```json theme={null}

3656{3673{

3657 "session_id": "abc123",3674 "session_id": "abc123",

3658 "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",3675 "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",

3659 "cwd": "/Users/...",3676 "cwd": "/Users/...",

3660 "permission_mode": "default",

3661 "hook_event_name": "Elicitation",3677 "hook_event_name": "Elicitation",

3662 "mcp_server_name": "my-mcp-server",3678 "mcp_server_name": "my-mcp-server",

3663 "message": "Please authenticate",3679 "message": "Please authenticate",

3670 Elicitation 출력3686 Elicitation 출력

3671</h4>3687</h4>

3672 3688

3673대화 상자를 표시하지 않고 프로그래밍 방식으로 응답하려면 `hookSpecificOutput`이 있는 JSON 객체를 반환합니다:3689대화 상자를 표시하지 않고 프로그래밍 방식으로 응답하려면 `hookSpecificOutput`이 포함된 JSON 객체를 반환합니다.

3674 3690

3675```json theme={null}3691```json theme={null}

3676{3692{

3686 3702

3687| 필드 | 값 | 설명 |3703| 필드 | 값 | 설명 |

3688| :- | :- | :- |3704| :- | :- | :- |

3691 3707

3692종료 코드 2는 elicitation을 거부합니다. Claude Code는 stderr 메시지를 어디에도 표시하지 않습니다.3708종료 코드 2는 elicitation을 거부합니다. Claude Code는 stderr 메시지를 어디에도 표시하지 않습니다.

3693 3709

3694Claude Code는 Elicitation hook의 JSON 출력에서 `hookSpecificOutput`을 작동하고 `systemMessage` 및 `continue`를 삭제합니다.3710Claude Code는 Elicitation 훅의 JSON 출력에서 `hookSpecificOutput`에 따라 동작하며 `systemMessage`와 `continue`는 무시합니다.

3695 3711

3696<h3 id="elicitationresult">3712<h3 id="elicitationresult">

3697 ElicitationResult3713 ElicitationResult

3698</h3>3714</h3>

3699 3715

3700사용자가 MCP elicitation에 응답한 후 실행됩니다. Hook은 응답을 관찰하고, 수정하거나, MCP 서버로 다시 전송되기 전에 차단할 수 있습니다.3716사용자가 MCP elicitation에 응답한 후 실행됩니다. 훅은 응답이 MCP 서버로 다시 전송되기 전에 이를 관찰, 수정 또는 차단할 수 있습니다.

3701 3717

3702matcher 필드는 MCP 서버 이름과 일치합니다.3718matcher 필드는 MCP 서버 이름과 비교됩니다.

3703 3719

3704<h4 id="elicitationresult-input">3720<h4 id="elicitationresult-input">

3705 ElicitationResult 입력3721 ElicitationResult 입력

3706</h4>3722</h4>

3707 3723

3708[공통 입력 필드](#common-input-fields) 외에도 ElicitationResult hook은 `mcp_server_name`, `action`, 선택적으로 `mode`, `elicitation_id`, `content` 필드를 받습니다.3724[공통 입력 필드](#common-input-fields) 외에도 ElicitationResult 훅은 `mcp_server_name`, `action` 및 선택적 필드인 `mode`, `elicitation_id`, `content`를 받습니다.

3709 3725

3710```json theme={null}3726```json theme={null}

3711{3727{

3712 "session_id": "abc123",3728 "session_id": "abc123",

3713 "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",3729 "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",

3714 "cwd": "/Users/...",3730 "cwd": "/Users/...",

3715 "permission_mode": "default",

3716 "hook_event_name": "ElicitationResult",3731 "hook_event_name": "ElicitationResult",

3717 "mcp_server_name": "my-mcp-server",3732 "mcp_server_name": "my-mcp-server",

3718 "action": "accept",3733 "action": "accept",

3726 ElicitationResult 출력3741 ElicitationResult 출력

3727</h4>3742</h4>

3728 3743

3729사용자의 응답을 재정의하려면 `hookSpecificOutput`이 있는 JSON 객체를 반환합니다:3744사용자의 응답을 재정의하려면 `hookSpecificOutput`이 포함된 JSON 객체를 반환합니다.

3730 3745

3731```json theme={null}3746```json theme={null}

3732{3747{

3741| 필드 | 값 | 설명 |3756| 필드 | 값 | 설명 |

3742| :- | :- | :- |3757| :- | :- | :- |

3745 3760

3746종료 코드 2는 응답을 차단하여 효과적인 작업을 `decline`으로 변경합니다. Claude Code는 stderr 메시지를 어디에도 표시하지 않습니다.3761종료 코드 2는 응답을 차단하여 실제 적용되는 작업을 `decline`으로 변경합니다. Claude Code는 stderr 메시지를 어디에도 표시하지 않습니다.

3747 3762

3748Claude Code는 ElicitationResult hook의 JSON 출력에서 `hookSpecificOutput`을 작동하고 `systemMessage` 및 `continue`를 삭제합니다.3763Claude Code는 ElicitationResult 훅의 JSON 출력에서 `hookSpecificOutput`에 따라 동작하며 `systemMessage`와 `continue`는 무시합니다.

3749 3764

3750<h2 id="prompt-based-hooks">3765<h2 id="prompt-based-hooks">

3751 프롬프트 기반 hook3766 프롬프트 기반 hook

3756다섯 가지 hook 유형 모두 (`command`, `http`, `mcp_tool`, `prompt`, `agent`)를 지원하는 이벤트:3771다섯 가지 hook 유형 모두 (`command`, `http`, `mcp_tool`, `prompt`, `agent`)를 지원하는 이벤트:

3757 3772

3758* `PermissionDenied`3773* `PermissionDenied`

3759* `PermissionRequest`

3760* `PostToolBatch`3774* `PostToolBatch`

3761* `PostToolUse`3775* `PostToolUse`

3762* `PostToolUseFailure`3776* `PostToolUseFailure`

3769* `UserPromptExpansion`3783* `UserPromptExpansion`

3770* `UserPromptSubmit`3784* `UserPromptSubmit`

3771 3785

3786`PermissionRequest`는 `command`, `http`, `mcp_tool`, `prompt` 훅을 지원하지만 `agent` 훅은 지원하지 않습니다. 이 이벤트에 에이전트 훅을 구성하면 Claude Code는 이를 건너뛰고 권한 흐름은 변경 없이 진행됩니다. 훅에서 허용하거나 거부하려면 명령 또는 HTTP 훅에서 [결정 객체](#permissionrequest-decision-control)를 반환합니다.

3787

3772`command`, `http` 및 `mcp_tool` hook을 지원하지만 `prompt` 또는 `agent`는 지원하지 않는 이벤트:3788`command`, `http` 및 `mcp_tool` hook을 지원하지만 `prompt` 또는 `agent`는 지원하지 않는 이벤트:

3773 3789

3774* `ConfigChange`3790* `ConfigChange`

3798 3814

3799프롬프트 기반 hook은 Bash 명령을 실행하는 대신:3815프롬프트 기반 hook은 Bash 명령을 실행하는 대신:

3800 3816

38011. hook 입력과 프롬프트를 Claude 모델 (기본값 Haiku)로 전송합니다38171. 훅 입력과 프롬프트를 Claude 모델로 전송합니다. 기본값은 Claude Code가 [백그라운드 기능](/docs/ko/costs#background-token-usage)에 사용하는 모델입니다

38022. LLM은 결정을 포함하는 구조화된 JSON으로 응답합니다38182. LLM은 결정을 포함하는 구조화된 JSON으로 응답합니다

38033. Claude Code는 결정을 자동으로 처리합니다38193. Claude Code는 결정을 자동으로 처리합니다

3804 3820

3831| :- | :- | :- |3847| :- | :- | :- |

3832| `type` | 예 | `"prompt"`여야 합니다 |3848| `type` | 예 | `"prompt"`여야 합니다 |

3833| `prompt` | 예 | LLM으로 전송할 프롬프트 텍스트. hook 입력 JSON에 대한 자리 표시자로 `$ARGUMENTS` 사용. `$ARGUMENTS`가 없으면 입력 JSON이 프롬프트에 추가됩니다 |3849| `prompt` | 예 | LLM으로 전송할 프롬프트 텍스트. hook 입력 JSON에 대한 자리 표시자로 `$ARGUMENTS` 사용. `$ARGUMENTS`가 없으면 입력 JSON이 프롬프트에 추가됩니다 |

3834| `model` | 아니오 | 평가에 사용할 모델. 기본값은 빠른 모델입니다 |3850| `model` | 아니오 | 평가에 사용할 모델. 기본값은 Claude Code가 [백그라운드 기능](/docs/ko/costs#background-token-usage)에 사용하는 모델입니다 |

3835| `timeout` | 아니오 | 초 단위 시간 초과. 기본값: 30 |3851| `timeout` | 아니오 | 초 단위 시간 초과. 기본값: 30 |

3836| `continueOnBlock` | 아니오 | 적용되는 이벤트에서 `true`는 `ok: false` 이유를 Claude에 다시 피드백하고 턴을 종료하는 대신 계속합니다. 기본값: `false`. 이벤트별 동작은 [응답 스키마](#response-schema)를 참조하세요 |3852| `continueOnBlock` | 아니오 | 적용되는 이벤트에서 `true`는 `ok: false` 이유를 Claude에 다시 피드백하고 턴을 종료하는 대신 계속합니다. 기본값: `false`. 이벤트별 동작은 [응답 스키마](#response-schema)를 참조하세요 |

3837 3853

3901 에이전트 hook은 실험적입니다. 동작 및 구성은 향후 릴리스에서 변경될 수 있습니다. 프로덕션 워크플로우의 경우 [명령 hook](#command-hook-fields)을 선호합니다.3917 에이전트 hook은 실험적입니다. 동작 및 구성은 향후 릴리스에서 변경될 수 있습니다. 프로덕션 워크플로우의 경우 [명령 hook](#command-hook-fields)을 선호합니다.

3902</Warning>3918</Warning>

3903 3919

3904에이전트 기반 hook (`type: "agent"`)은 프롬프트 기반 hook과 유사하지만 다중 턴 도구 액세스가 있습니다. 단일 LLM 호출 대신 에이전트 hook은 파일을 읽고, 코드를 검색하고, 코드베이스를 검사하여 조건을 확인할 수 있는 subagent를 생성합니다. 에이전트 hook은 프롬프트 기반 hook과 동일한 이벤트를 지원합니다.3920에이전트 기반 훅 (`type: "agent"`)은 프롬프트 기반 훅과 유사하지만 다중 턴 도구 액세스가 있습니다. 단일 LLM 호출 대신 에이전트 훅은 파일을 읽고, 코드를 검색하고, 코드베이스를 검사하여 조건을 확인할 수 있는 서브에이전트를 생성합니다. 에이전트 훅은 `PermissionRequest`를 제외하고 [프롬프트 기반 훅](#prompt-based-hooks)과 동일한 이벤트를 지원합니다.

3905 3921

3906<h3 id="how-agent-hooks-work">3922<h3 id="how-agent-hooks-work">

3907 에이전트 hook이 어떻게 작동하는지3923 에이전트 hook이 어떻게 작동하는지

hooks-guide.md +21 −18

Details

17</Tip>17</Tip>

18 18

19<h2 id="set-up-your-first-hook">19<h2 id="set-up-your-first-hook">

~~20 첫 번째 hook 설정~~20 첫 번째 훅 설정하기

21</h2>21</h2>

22 22

23Hook을 만들려면 [설정 파일](#configure-hook-location)에 `hooks` 블록을 추가합니다. 이 연습은 데스크톱 알림 hook을 만들므로 Claude가 터미널을 보는 대신 입력을 기다릴 때마다 알림을 받습니다.23훅을 만들려면 [설정 파일](#configure-hook-location)에 `hooks` 블록을 추가합니다. 이 안내에서는 데스크톱 알림 훅을 만듭니다. 이 훅을 사용하면 터미널을 계속 지켜보지 않아도 Claude가 입력을 기다릴 때마다 알림을 받을 수 있습니다.

24 24

25<Steps>25<Steps>

~~26 <Step title="설정에 hook 추가">~~26 <Step title="설정에 훅 추가하기">

27 `~/.claude/settings.json`을 열고 `Notification` hook을 추가합니다. 파일이 없으면 만듭니다. 아래 예제는 macOS용 `osascript`를 사용합니다. Linux 및 Windows 명령은 [Claude가 입력이 필요할 때 알림 받기](#get-notified-when-claude-needs-input)를 참조하세요.27 `~/.claude/settings.json`을 열고 `Notification` 훅을 추가합니다. 파일이 없으면 새로 만듭니다. 아래 예시는 macOS용 `osascript`를 사용합니다. Linux 및 Windows용 명령은 [Claude가 입력을 필요로 할 때 알림 받기](#get-notified-when-claude-needs-input)를 참조하세요.

28 28

29 ```json theme={null}29 ```json theme={null}

30 {30 {

44 }44 }

45 ```45 ```

46 46

47 설정 파일에 이미 `hooks` 키가 있으면 전체 객체를 바꾸는 대신 `Notification`을 기존 이벤트 키의 형제로 추가합니다. 각 이벤트 이름은 단일 `hooks` 객체 내의 키입니다:47 설정 파일에 이미 `hooks` 키가 있다면 전체 객체를 교체하지 말고 기존 이벤트 키와 같은 수준에 `Notification`을 추가합니다. 각 이벤트 이름은 단일 `hooks` 객체 안의 키입니다.

48 48

49 ```json theme={null}49 ```json theme={null}

50 {50 {

65 }65 }

66 ```66 ```

67 67

~~68 CLI에서 원하는 것을 설명하여 Claude에게 hook을 작성하도록 요청할 수도 있습니다.~~68 CLI에서 원하는 내용을 설명하여 Claude에게 훅 작성을 요청할 수도 있습니다.

69 </Step>69 </Step>

70 70

~~71 <Step title="구성 확인">~~71 <Step title="구성 확인하기">

72 `/hooks`를 입력하여 hooks 브라우저를 엽니다. 구성된 hooks가 있는 각 이벤트 옆에 개수가 있는 사용 가능한 모든 hook 이벤트 목록이 표시됩니다. `Notification`을 선택하여 새 hook이 목록에 나타나는지 확인합니다. Hook을 선택하면 세부 정보가 표시됩니다: 이벤트, matcher, 유형, 소스 파일 및 명령.72 Claude Code 프롬프트에 `/hooks`를 입력하여 훅 브라우저를 엽니다. 새 훅이 목록의 `Notification` 아래에 표시됩니다.

73 </Step>73 </Step>

74 74

~~75 <Step title="hook 테스트">~~75 <Step title="훅 테스트하기">

76 `Esc`를 눌러 CLI로 돌아갑니다. `Shift+Tab`을 누르면 상태 표시줄에 `⏸ manual mode on`이 표시될 때까지 누르고, Claude에게 권한이 필요한 작업을 수행하도록 요청한 다음 터미널에서 전환합니다. 데스크톱 알림을 받아야 합니다.76 `Esc`를 눌러 CLI로 돌아갑니다. 상태 표시줄에 `⏸ manual mode on`이 표시될 때까지 `Shift+Tab`을 누른 다음, Claude에게 권한이 필요한 작업을 요청하고 터미널에서 다른 곳으로 전환합니다. 데스크톱 알림이 표시되어야 합니다.

77 </Step>77 </Step>

78</Steps>78</Steps>

79 79

~~80<Tip>~~

~~81 `/hooks` 메뉴는 읽기 전용입니다. Hooks를 추가, 수정 또는 제거하려면 설정 JSON을 직접 편집하거나 Claude에게 변경을 요청합니다.~~

~~82</Tip>~~

84<h2 id="what-you-can-automate">80<h2 id="what-you-can-automate">

85 자동화할 수 있는 것81 자동화할 수 있는 것

86</h2>82</h2>

97 93

98Claude가 작업을 완료하고 입력이 필요할 때마다 데스크톱 알림을 받으므로 터미널을 확인하지 않고 다른 작업으로 전환할 수 있습니다.94Claude가 작업을 완료하고 입력이 필요할 때마다 데스크톱 알림을 받으므로 터미널을 확인하지 않고 다른 작업으로 전환할 수 있습니다.

99 95

100이 hook은 Claude가 입력 또는 권한을 기다릴 때 발생하는 `Notification` 이벤트를 사용합니다. 각 알림 유형이 발생하는 정확한 시점은 [각 알림 유형이 발생하는 시점](/docs/ko/hooks#notification)을 참조하세요. 각 탭은 플랫폼의 기본 알림 명령을 사용합니다. `~/.claude/settings.json`에 추가합니다:96이 훅은 Claude가 입력 또는 권한을 기다릴 때 Claude Code가 발생시키는 `Notification` 이벤트를 사용합니다. 정확한 시점은 [각 알림 유형이 발생하는 시점](/docs/ko/hooks#notification)을 참조하세요.

98아래의 각 탭은 플랫폼의 기본 알림 명령을 사용합니다. `~/.claude/settings.json`에 추가합니다:

101 99

102<Tabs>100<Tabs>

103 <Tab title="macOS">101 <Tab title="macOS">

120 ```118 ```

121 119

122 <Accordion title="알림이 나타나지 않으면">120 <Accordion title="알림이 나타나지 않으면">

123 `osascript`는 기본 제공 Script Editor 앱을 통해 알림을 라우팅합니다. Script Editor에 알림 권한이 없으면 명령이 자동으로 실패하고 macOS는 권한을 부여하도록 프롬프트하지 않습니다. Terminal에서 이를 한 번 실행하여 Script Editor가 알림 설정에 나타나도록 합니다:121 `osascript`는 기본 제공 Script Editor 앱을 통해 알림을 라우팅합니다. Script Editor에 알림 권한이 없으면 명령이 아무 표시 없이 실패하고 macOS는 권한을 부여하라고 확인을 요청하지 않습니다.

122

123 Terminal에서 이를 한 번 실행하여 Script Editor가 알림 설정에 나타나도록 합니다:

124 124

125 ```bash theme={null}125 ```bash theme={null}

126 osascript -e 'display notification "test"'126 osascript -e 'display notification "test"'

180 ```180 ```

181 181

182 <Accordion title="대화 상자가 나타나지 않으면">182 <Accordion title="대화 상자가 나타나지 않으면">

183 이 명령은 화면 모서리의 알림이 아닌 대화 상자를 열므로 대화 상자가 터미널 창 뒤에서 열릴 수 있습니다. 먼저 PowerShell에서 명령을 직접 테스트합니다. Claude Code를 WSL 내부에서 실행하는 경우 `powershell.exe`는 Windows interop을 통해 `PATH`에서 사용 가능해야 합니다.183 이 명령은 화면 모서리의 알림이 아닌 대화 상자를 열므로 대화 상자가 터미널 창 뒤에서 열릴 수 있습니다. 먼저 PowerShell에서 명령을 직접 테스트합니다.

184

185 Claude Code를 WSL 내부에서 실행하는 경우 `powershell.exe`는 Windows interop을 통해 `PATH`에서 사용 가능해야 합니다.

184 </Accordion>186 </Accordion>

185 </Tab>187 </Tab>

186</Tabs>188</Tabs>

212 214

213팀원의 터미널 설정 질문에 대한 `agent_needs_input`은 Claude Code v2.1.248 이상이 필요합니다.215팀원의 터미널 설정 질문에 대한 `agent_needs_input`은 Claude Code v2.1.248 이상이 필요합니다.

214 216

215`/hooks`를 입력하고 `Notification`을 선택하여 hook이 등록되었는지 확인합니다. 전체 이벤트 스키마는 [Notification 참조](/docs/ko/hooks#notification)를 참조하세요.217Claude Code 프롬프트에서 `/hooks`를 입력하고 `Notification` 아래에 훅이 표시되는지 확인합니다.

216 218

217<h3 id="auto-format-code-after-edits">219<h3 id="auto-format-code-after-edits">

218 편집 후 코드 자동 형식 지정220 편집 후 코드 자동 형식 지정

1055* 파일 편집은 일반적으로 자동으로 선택됩니다. 몇 초 후에 나타나지 않으면 파일 감시자가 변경을 놓쳤을 수 있습니다: 세션을 다시 시작하여 강제로 다시 로드합니다.1057* 파일 편집은 일반적으로 자동으로 선택됩니다. 몇 초 후에 나타나지 않으면 파일 감시자가 변경을 놓쳤을 수 있습니다: 세션을 다시 시작하여 강제로 다시 로드합니다.

1056* JSON이 유효한지 확인합니다: 후행 쉼표 및 주석은 허용되지 않습니다1058* JSON이 유효한지 확인합니다: 후행 쉼표 및 주석은 허용되지 않습니다

1057* 설정 파일이 올바른 위치에 있는지 확인합니다: 프로젝트 hooks의 경우 `.claude/settings.json`, 전역 hooks의 경우 `~/.claude/settings.json`1059* 설정 파일이 올바른 위치에 있는지 확인합니다: 프로젝트 hooks의 경우 `.claude/settings.json`, 전역 hooks의 경우 `~/.claude/settings.json`

1060* 메뉴에 `Only hooks from managed settings run here`가 표시되면 조직에서 [`allowManagedHooksOnly`](/docs/ko/settings-reference#allowmanagedhooksonly)를 설정한 것입니다. 사용자, 프로젝트 및 로컬 설정 파일의 훅은 실행되지 않으며 목록에 표시되지 않습니다

1058 1061

1059<h3 id="stop-hook-hits-the-block-cap">1062<h3 id="stop-hook-hits-the-block-cap">

1060 Stop hook이 블록 상한에 도달함1063 Stop hook이 블록 상한에 도달함

keybindings.md +6 −8

Details

545* Cyrillic과 같은 비라틴 레이아웃에서 Claude Code는 터미널이 Kitty 키보드 프로토콜을 사용하고 해당 위치를 보고할 때 키의 US 레이아웃 위치로 Ctrl 바로가기를 일치시킵니다. 러시아어 레이아웃이 활성화된 그러한 터미널에서 Ctrl과 물리적 W 키를 누르면 `ctrl+w`가 트리거됩니다. 위치를 보고하지 않는 터미널에서 Claude Code는 키 입력에 대해 터미널이 전송하는 것과 일치합니다: ASCII 제어 코드는 라틴 바로가기를 트리거하고 Cyrillic 문자로 도착하는 키 입력은 바인딩과 일치하지 않습니다545* Cyrillic과 같은 비라틴 레이아웃에서 Claude Code는 터미널이 Kitty 키보드 프로토콜을 사용하고 해당 위치를 보고할 때 키의 US 레이아웃 위치로 Ctrl 바로가기를 일치시킵니다. 러시아어 레이아웃이 활성화된 그러한 터미널에서 Ctrl과 물리적 W 키를 누르면 `ctrl+w`가 트리거됩니다. 위치를 보고하지 않는 터미널에서 Claude Code는 키 입력에 대해 터미널이 전송하는 것과 일치합니다: ASCII 제어 코드는 라틴 바로가기를 트리거하고 Cyrillic 문자로 도착하는 키 입력은 바인딩과 일치하지 않습니다

546* AZERTY와 같이 라틴 문자를 재배열하는 레이아웃에서 Claude Code는 키가 입력하는 문자와 일치하므로 Ctrl과 A로 표시된 키를 누르면 `ctrl+a`가 트리거됩니다546* AZERTY와 같이 라틴 문자를 재배열하는 레이아웃에서 Claude Code는 키가 입력하는 문자와 일치하므로 Ctrl과 A로 표시된 키를 누르면 `ctrl+a`가 트리거됩니다

547 547

548v2.1.247 이전에는 Ghostty, Kitty, WezTerm, iTerm2와 같이 Kitty 키보드 프로토콜을 사용하는 터미널에서 비라틴 레이아웃 아래의 Ctrl 바로가기를 누르면 해당 바인딩이 트리거되지 않았습니다.

~~549~~

550<h3 id="chords">548<h3 id="chords">

551 코드549 코드

552</h3>550</h3>

691 유효성 검사689 유효성 검사

692</h2>690</h2>

693 691

694Claude Code는 키바인딩을 검증하고 다음에 대해 디버그 로그에 경고를 기록합니다:692Claude Code는 키보드 단축키의 유효성을 검사하며, 다음과 같은 경우 디버그 로그에 경고를 기록합니다.

695 693

696* 구문 분석 오류(잘못된 JSON 또는 구조)694* 구문 분석 오류(잘못된 JSON 또는 구조)

697* 잘못된 수정자(modifier), 예를 들어 `ctl+k`. Claude Code는 인식하지 못하는 부분을 제거하고 남은 키스트로크에 바인딩을 적용합니다. 이 예에서는 `k`입니다.695* `ctl+k`와 같이 철자가 잘못된 수정자 키. Claude Code는 인식하지 못하는 부분을 제외하고 나머지 키 입력(이 예에서는 `k`)에 바인딩을 적용합니다.

698* 잘못된 컨텍스트 이름696* 잘못된 컨텍스트 이름

699* 잘못된 작업 값(예: 문자열이 아니거나 `null`인 작업)697* 문자열도 `null`도 아닌 작업과 같은 잘못된 작업 값

700* 알 수 없는 작업 이름(예: 등록된 작업의 오타). Claude Code는 바인딩을 건너뛰고 해당 키에 대한 기본 바인딩을 유지합니다. v2.1.246 이전에는 알 수 없는 작업 이름이 있는 바인딩이 해당 키를 자동으로 비활성화했습니다698* 등록된 작업 이름의 오타와 같은 알 수 없는 작업 이름. Claude Code는 해당 바인딩을 건너뛰고 그 키에 대한 기본 바인딩을 계속 적용합니다.

701* 예약된 단축키 충돌699* 예약된 단축키 충돌

702* 동일한 컨텍스트의 중복 바인딩700* 동일한 컨텍스트 내의 중복 바인딩

703 701

704[`--debug`](/docs/ko/cli-reference#cli-flags)를 사용하여 Claude Code를 시작하면 세부 정보를 확인할 수 있습니다.702자세한 내용을 확인하려면 [`--debug`](/docs/ko/cli-reference#cli-flags) 옵션으로 Claude Code를 시작합니다.

llm-gateway-protocol.md +1 −1

Details

73 73

74추론 응답을 스트리밍합니다. Claude Code는 도착하는 대로 스트림을 읽으므로, 게이트웨이가 완전한 응답을 버퍼링한 후 릴레이하면 Claude Code가 정지됩니다.74추론 응답을 스트리밍합니다. Claude Code는 도착하는 대로 스트림을 읽으므로, 게이트웨이가 완전한 응답을 버퍼링한 후 릴레이하면 Claude Code가 정지됩니다.

75 75

76각 응답의 전체 이벤트 시퀀스를 이벤트를 드롭하거나 중복하거나 재정렬하지 않고 전달합니다. 이벤트가 `content_block_start`가 도착하지 않은 콘텐츠 블록을 참조하거나, `content_block_stop`이 이미 도착한 블록을 참조할 때, Claude Code는 이를 적용하는 대신 해당 이벤트에서 스트림 읽기를 중지하므로, 중복된 `content_block_stop`은 동일한 도구 호출을 두 번 실행할 수 없습니다. [위의 응답이 불완전할 수 있습니다](/docs/ko/errors#the-response-above-may-be-incomplete)는 사용자가 보는 것을 설명하며, `응답의 일부가 도착하지 않음` 및 `응답 스트림이 잘못되었습니다` 변형 아래에 있습니다.76각 응답의 전체 이벤트 시퀀스를 이벤트를 드롭하거나 중복하거나 재정렬하지 않고 전달합니다. Amazon Bedrock 가드레일이 응답을 차단하면, 가드레일이 보내는 이벤트가 `content_block_stop`이 이미 도착한 콘텐츠 블록을 참조하더라도 해당 이벤트를 변경 없이 전달합니다. [AWS Guardrails](/docs/ko/amazon-bedrock#aws-guardrails)는 해당 응답이 어떻게 끝나는지 설명합니다. 그 밖의 이벤트가 `content_block_start`가 도착하지 않은 콘텐츠 블록을 참조하거나, `content_block_stop`이 이미 도착한 블록을 참조할 때, Claude Code는 이를 적용하는 대신 해당 이벤트에서 스트림 읽기를 중지하므로, 중복된 `content_block_stop`은 동일한 도구 호출을 두 번 실행할 수 없습니다. [위의 응답이 불완전할 수 있습니다](/docs/ko/errors#the-response-above-may-be-incomplete)는 사용자가 보는 것을 설명하며, `Part of the response never arrived` 및 `The response stream was malformed` 변형 아래에 있습니다.

77 77

78각 응답을 최종 `message_delta` 및 `message_stop` 이벤트를 통해 본문을 끝내기 전에 릴레이합니다. `message_delta`를 전달하는 본문이 `stop_reason`을 가지고 있고, 열린 콘텐츠 블록이 없으며, 해당 프레임 이후에 콘텐츠 블록 이벤트가 없을 때, `message_stop`이 없어도 완전한 것으로 간주됩니다. 게이트웨이가 콘텐츠 블록이 시작된 후 더 일찍 깔끔하게 끝내는 본문은 끊어진 연결과 동일하게 처리됩니다: [자동 재시도](/docs/ko/errors#automatic-retries)는 Claude Code가 요청을 다시 발행할 때를 말하며, [위의 응답이 불완전할 수 있습니다](/docs/ko/errors#the-response-above-may-be-incomplete)는 보이는 콘텐츠가 도착한 후 유지하는 것을 다룹니다. Claude Code는 `message_delta`가 전달하는 `stop_reason`을 유지하므로, 나중의 사용량 전용 `message_delta`의 `delta`가 `stop_reason: null`을 가지거나 `stop_reason` 키가 없을 때 이를 지우지 않습니다.78각 응답을 최종 `message_delta` 및 `message_stop` 이벤트를 통해 본문을 끝내기 전에 릴레이합니다. `message_delta`를 전달하는 본문이 `stop_reason`을 가지고 있고, 열린 콘텐츠 블록이 없으며, 해당 프레임 이후에 콘텐츠 블록 이벤트가 없을 때, `message_stop`이 없어도 완전한 것으로 간주됩니다. 게이트웨이가 콘텐츠 블록이 시작된 후 더 일찍 깔끔하게 끝내는 본문은 끊어진 연결과 동일하게 처리됩니다: [자동 재시도](/docs/ko/errors#automatic-retries)는 Claude Code가 요청을 다시 발행할 때를 말하며, [위의 응답이 불완전할 수 있습니다](/docs/ko/errors#the-response-above-may-be-incomplete)는 보이는 콘텐츠가 도착한 후 유지하는 것을 다룹니다. Claude Code는 `message_delta`가 전달하는 `stop_reason`을 유지하므로, 나중의 사용량 전용 `message_delta`의 `delta`가 `stop_reason: null`을 가지거나 `stop_reason` 키가 없을 때 이를 지우지 않습니다.

79 79

memory.md +62 −60

Details

41 CLAUDE.md 파일41 CLAUDE.md 파일

42</h2>42</h2>

43 43

44CLAUDE.md 파일은 Claude에게 프로젝트, 개인 워크플로우 또는 전체 조직을 위한 지속적인 지침을 제공하는 마크다운 파일입니다. 이 파일들을 일반 텍스트로 작성하면 Claude가 매 세션의 시작 시 이를 읽습니다. 저장소에서 `AGENTS.md`를 대신 사용하는 경우 [AGENTS.md](#agents-md)를 참조하십시오.44CLAUDE.md 파일은 Claude에게 프로젝트, 개인 워크플로 또는 전체 조직을 위한 지속적인 지침을 제공하는 마크다운 파일입니다. 이 파일들을 일반 텍스트로 작성하면 Claude가 매 세션의 시작 시 이를 읽습니다. 저장소에서 `AGENTS.md`를 대신 사용하는 경우 [AGENTS.md](#agents-md)를 참조하십시오.

45 45

46<h3 id="when-to-add-to-claude-md">46<h3 id="when-to-add-to-claude-md">

47 CLAUDE.md에 추가할 시기47 CLAUDE.md에 추가할 시기

54* 지난 세션에 입력한 것과 같은 수정 사항이나 설명을 채팅에 다시 입력할 때54* 지난 세션에 입력한 것과 같은 수정 사항이나 설명을 채팅에 다시 입력할 때

55* 새로운 팀원이 생산성을 높이기 위해 같은 컨텍스트가 필요할 때55* 새로운 팀원이 생산성을 높이기 위해 같은 컨텍스트가 필요할 때

56 56

57매 세션마다 Claude가 보유해야 할 사실들로 유지하십시오: 빌드 명령어, 규칙, 프로젝트 레이아웃, "항상 X를 수행하라"는 규칙. 항목이 다단계 절차이거나 코드베이스의 한 부분에만 해당하는 경우 [skill](/docs/ko/skills) 또는 [경로 범위 규칙](#organize-rules-with-claude/rules/)으로 이동하십시오. [확장 기능 개요](/docs/ko/features-overview#build-your-setup-over-time)에서 각 메커니즘을 사용할 시기를 다룹니다.57매 세션마다 Claude가 보유해야 할 사실들로 유지하십시오: 빌드 명령, 규칙, 프로젝트 레이아웃, "항상 X를 수행하라"는 규칙. 항목이 다단계 절차이거나 코드베이스의 한 부분에만 해당하는 경우 [스킬](/docs/ko/skills) 또는 [경로 범위 규칙](#organize-rules-with-claude/rules/)으로 이동하십시오. [확장 기능 개요](/docs/ko/features-overview#build-your-setup-over-time)에서 각 메커니즘을 사용할 시기를 다룹니다.

58 58

59<h3 id="choose-where-to-put-claude-md-files">59<h3 id="choose-where-to-put-claude-md-files">

60 CLAUDE.md 파일을 어디에 배치할지 선택하기60 CLAUDE.md 파일을 어디에 배치할지 선택하기

66| - | - | - | - | - |66| - | - | - | - | - |

71 71

72작업 디렉토리 위의 디렉토리 계층 구조에 있는 CLAUDE.md 및 CLAUDE.local.md 파일은 시작 시 로드됩니다. 하위 디렉토리의 파일은 Claude가 해당 디렉토리의 파일을 읽을 때 필요에 따라 로드됩니다. 전체 해석 순서는 [CLAUDE.md 파일이 로드되는 방식](#how-claude-md-files-load)을 참조하십시오.72작업 디렉터리 위의 디렉터리 계층 구조에 있는 CLAUDE.md 및 CLAUDE.local.md 파일은 시작 시 로드됩니다. 하위 디렉터리의 파일은 Claude가 해당 디렉터리의 파일을 읽을 때 필요에 따라 로드됩니다. 전체 해석 순서는 [CLAUDE.md 파일이 로드되는 방식](#how-claude-md-files-load)을 참조하십시오.

73 73

74대규모 프로젝트의 경우 [프로젝트 규칙](#organize-rules-with-claude/rules/)을 사용하여 지침을 주제별 파일로 나눌 수 있습니다. 규칙을 사용하면 특정 파일 유형이나 하위 디렉토리로 지침의 범위를 지정할 수 있습니다.74대규모 프로젝트의 경우 [프로젝트 규칙](#organize-rules-with-claude/rules/)을 사용하여 지침을 주제별 파일로 나눌 수 있습니다. 규칙을 사용하면 특정 파일 유형이나 하위 디렉터리로 지침의 범위를 지정할 수 있습니다.

75 75

76<h3 id="set-up-a-project-claude-md">76<h3 id="set-up-a-project-claude-md">

77 프로젝트 CLAUDE.md 설정하기77 프로젝트 CLAUDE.md 설정하기

78</h3>78</h3>

79 79

80프로젝트 CLAUDE.md는 `./CLAUDE.md` 또는 `./.claude/CLAUDE.md`에 저장할 수 있습니다. 이 파일을 만들고 프로젝트에서 작업하는 모든 사람에게 적용되는 지침을 추가하십시오: 빌드 및 테스트 명령어, 코딩 표준, 아키텍처 결정, 명명 규칙 및 일반적인 워크플로우. 이 지침은 버전 제어를 통해 팀과 공유되므로 개인 선호도보다는 프로젝트 수준의 표준에 집중하십시오. 파일이 로드되었는지 확인하려면 세션에서 `/context`를 실행하고 **Memory files** 아래의 목록을 확인하십시오.80프로젝트 CLAUDE.md는 `./CLAUDE.md` 또는 `./.claude/CLAUDE.md`에 저장할 수 있습니다. 이 파일을 만들고 프로젝트에서 작업하는 모든 사람에게 적용되는 지침을 추가하십시오: 빌드 및 테스트 명령, 코딩 표준, 아키텍처 결정, 명명 규칙 및 일반적인 워크플로. 이 지침은 버전 제어를 통해 팀과 공유되므로 개인 선호도보다는 프로젝트 수준의 표준에 집중하십시오. 파일이 로드되었는지 확인하려면 세션에서 `/context`를 실행하고 **Memory files** 아래의 목록을 확인하십시오.

81 81

82<Tip>82<Tip>

83 `/init`을 실행하여 시작 CLAUDE.md를 자동으로 생성하십시오. Claude가 코드베이스를 분석하고 발견한 빌드 명령어, 테스트 지침 및 프로젝트 규칙이 포함된 파일을 만듭니다. CLAUDE.md가 이미 존재하는 경우 `/init`은 덮어쓰지 않고 개선 사항을 제안합니다. 거기서부터 Claude가 자체적으로 발견하지 못할 지침으로 개선하십시오.83 `/init`을 실행하여 시작 CLAUDE.md를 자동으로 생성하십시오. Claude가 코드베이스를 분석하고 발견한 빌드 명령, 테스트 지침 및 프로젝트 규칙이 포함된 파일을 만듭니다. CLAUDE.md가 이미 존재하는 경우 `/init`은 덮어쓰지 않고 개선 사항을 제안합니다. 거기서부터 Claude가 자체적으로 발견하지 못할 지침으로 개선하십시오.

84 84

85 대화형 다단계 흐름을 활성화하려면 `/init`을 실행하기 전에 `CLAUDE_CODE_NEW_INIT` 환경 변수를 `1`로 설정하십시오. 셸에서 설정하거나 [환경 변수 설정](/docs/ko/env-vars#set-environment-variables)에 표시된 대로 설정 파일의 `env` 블록에서 설정하십시오. 설정하면 `/init`은 설정할 아티팩트를 묻습니다: CLAUDE.md 파일, 스킬 및 훅. 그런 다음 서브에이전트로 코드베이스를 탐색하고, 후속 질문을 통해 간격을 채우고, 파일을 작성하기 전에 검토 가능한 제안을 제시합니다. 이 변수는 `/init`이 실행되는 방식만 변경하므로 설정된 상태로 둘 수 있습니다.85 대화형 다단계 흐름을 사용하려면 `/init`을 실행하기 전에 `CLAUDE_CODE_NEW_INIT` 환경 변수를 `1`로 설정하십시오. 셸에서 설정하거나 [환경 변수 설정](/docs/ko/env-vars#set-environment-variables)에 표시된 대로 설정 파일의 `env` 블록에서 설정하십시오. 설정하면 `/init`은 설정할 아티팩트를 묻습니다: CLAUDE.md 파일, 스킬 및 훅. 그런 다음 서브에이전트로 코드베이스를 탐색하고, 후속 질문을 통해 빈 부분을 채우고, 파일을 작성하기 전에 검토 가능한 제안을 제시합니다. 이 변수는 `/init`이 실행되는 방식만 변경하므로 설정된 상태로 둘 수 있습니다.

86</Tip>86</Tip>

87 87

88<h3 id="write-effective-instructions">88<h3 id="write-effective-instructions">

89 효과적인 지침 작성하기89 효과적인 지침 작성하기

90</h3>90</h3>

91 91

92Claude는 CLAUDE.md 파일을 컨텍스트로 취급하며, 강제된 구성이 아니므로, 지침을 작성하는 방식이 Claude가 이를 따르는 신뢰성에 영향을 미칩니다. 검증할 수 있을 정도로 구체적인 지침을 작성하십시오:92Claude는 CLAUDE.md 파일을 강제된 구성이 아닌 컨텍스트로 취급하므로, 지침을 작성하는 방식이 Claude가 이를 따르는 신뢰성에 영향을 미칩니다. 검증할 수 있을 정도로 구체적인 지침을 작성하십시오:

93 93

94* "코드를 적절히 포맷하십시오" 대신 "2칸 들여쓰기 사용"94* "코드를 적절히 포맷하십시오" 대신 "2칸 들여쓰기 사용"

95* "변경 사항을 테스트하십시오" 대신 "커밋하기 전에 `npm test` 실행"95* "변경 사항을 테스트하십시오" 대신 "커밋하기 전에 `npm test` 실행"

98파일을 짧고, 정리되고, 일관되게 유지하십시오:98파일을 짧고, 정리되고, 일관되게 유지하십시오:

99 99

100* **크기**: CLAUDE.md 파일당 200줄 이하를 목표로 하십시오. 더 긴 파일은 더 많은 컨텍스트를 소비하고 준수를 감소시킵니다. 코드베이스의 일부에만 해당하는 지침을 [경로 범위 규칙](#path-specific-rules)으로 이동하십시오. 이러한 규칙은 Claude가 일치하는 파일로 작업할 때만 로드됩니다. [가져오기](#import-additional-files)는 긴 파일을 정리하는 데 도움이 되지만 컨텍스트 비용을 줄이지는 않습니다. 가져온 파일도 시작 시 로드되기 때문입니다.100* **크기**: CLAUDE.md 파일당 200줄 이하를 목표로 하십시오. 더 긴 파일은 더 많은 컨텍스트를 소비하고 준수를 감소시킵니다. 코드베이스의 일부에만 해당하는 지침을 [경로 범위 규칙](#path-specific-rules)으로 이동하십시오. 이러한 규칙은 Claude가 일치하는 파일로 작업할 때만 로드됩니다. [가져오기](#import-additional-files)는 긴 파일을 정리하는 데 도움이 되지만 컨텍스트 비용을 줄이지는 않습니다. 가져온 파일도 시작 시 로드되기 때문입니다.

101* **구조**: 관련 지침을 마크다운 헤더와 글머리 기호로 그룹화하십시오. 정리된 섹션은 조밀한 단락보다 따르기 쉽습니다.101* **구조**: 관련 지침을 마크다운 헤더와 글머리 기호로 그룹화하십시오. 정리된 섹션은 조밀한 단락보다 Claude가 따르기 쉽습니다.

102* **일관성**: 두 규칙이 서로 모순되면 Claude가 임의로 하나를 선택할 수 있습니다. CLAUDE.md 파일, 하위 디렉토리의 중첩된 CLAUDE.md 파일 및 [`.claude/rules/`](#organize-rules-with-claude/rules/)을 주기적으로 검토하여 오래되었거나 충돌하는 지침을 제거하십시오. 모노레포에서 [`claudeMdExcludes`](#exclude-specific-claude-md-files)를 사용하여 작업과 관련이 없는 다른 팀의 CLAUDE.md 파일을 건너뛰십시오.102* **일관성**: 두 지침이 서로 모순되면 Claude가 임의로 하나를 선택할 수 있습니다. CLAUDE.md 파일, 하위 디렉터리의 중첩된 CLAUDE.md 파일 및 [`.claude/rules/`](#organize-rules-with-claude/rules/)을 주기적으로 검토하여 오래되었거나 충돌하는 지침을 제거하십시오. Claude가 이를 대신 찾도록 하려면 [프롬프트 감사를 실행](#audit-your-instruction-files)하십시오.

103 103

104<h4 id="audit-your-instruction-files">104<h4 id="audit-your-instruction-files">

105 지침 파일 감사하기105 지침 파일 감사하기

106</h4>106</h4>

107 107

108Claude가 지침 파일에서 오래되었거나 충돌하는 내용을 확인하도록 하려면 세션에서 `/doctor prompt-audit`을 실행하십시오. Claude는 CLAUDE.md, CLAUDE.local.md 및 AGENTS.md 파일과 `.claude/` 및 `~/.claude/` 아래의 규칙, 스킬, 명령어, 서브에이전트 및 출력 스타일을 찾습니다. 이전 모델용으로 작성된 지침, 존재하지 않는 파일 또는 명령어에 대한 참조, 서로 모순되는 파일 등의 문제를 찾습니다. 발견 사항 보고서와 제안된 편집 세트를 받으며, Claude에게 적용하도록 요청할 때까지 파일의 아무것도 변경되지 않습니다.108Claude가 지침 파일에서 오래되었거나 충돌하는 내용을 확인하도록 하려면 세션에서 `/doctor prompt-audit`을 실행하십시오. Claude는 이전 모델용으로 작성된 지침, 존재하지 않는 파일 또는 명령에 대한 참조, 서로 모순되는 파일 등의 문제를 찾습니다. 발견 사항과 제안된 편집이 담긴 보고서가 제공되며, Claude에게 적용하도록 요청할 때까지 파일의 아무것도 변경되지 않습니다.

109 109

110기본적으로 감사는 CLAUDE.md, CLAUDE.local.md 및 AGENTS.md 파일과 `.claude/` 및 `~/.claude/` 아래의 규칙, 스킬, 명령어, 서브에이전트 및 출력 스타일을 다룹니다. 대신 하나의 파일 또는 디렉토리를 감사하려면 경로를 전달하십시오(예: `/doctor prompt-audit .claude/skills/deploy`).110기본적으로 감사는 CLAUDE.md, CLAUDE.local.md 및 AGENTS.md 파일과 `.claude/` 및 `~/.claude/` 아래의 규칙, 스킬, 명령, 서브에이전트 및 출력 스타일을 다룹니다. 대신 하나의 파일 또는 디렉터리를 감사하려면 경로를 전달하십시오(예: `/doctor prompt-audit .claude/skills/deploy`).

111 111

112감사는 번들된 `/claude-api` 스킬을 통해 실행되므로 [`skillOverrides`](/docs/ko/skills#override-skill-visibility-from-settings)에서 해당 스킬이 꺼져 있거나 [`disableBundledSkills`](/docs/ko/settings-reference#disablebundledskills)로 비활성화되어 있으면 사용할 수 없습니다. `/doctor prompt-audit`은 Claude Code v2.1.283 이상이 필요합니다.112감사는 번들된 `/claude-api` 스킬을 통해 실행됩니다. [`skillOverrides`](/docs/ko/skills#override-skill-visibility-from-settings)에서 해당 스킬이 꺼져 있거나 [`disableBundledSkills`](/docs/ko/settings-reference#disablebundledskills)로 비활성화되어 있는 동안에는 사용할 수 없습니다. `/doctor prompt-audit`은 Claude Code v2.1.283 이상이 필요합니다.

113 113

114<h3 id="import-additional-files">114<h3 id="import-additional-files">

115 추가 파일 가져오기115 추가 파일 가져오기

117 117

118CLAUDE.md 파일은 `@path/to/import` 구문을 사용하여 추가 파일을 가져올 수 있습니다. 가져온 파일은 확장되고 이를 참조하는 CLAUDE.md와 함께 시작 시 컨텍스트에 로드됩니다.118CLAUDE.md 파일은 `@path/to/import` 구문을 사용하여 추가 파일을 가져올 수 있습니다. 가져온 파일은 확장되고 이를 참조하는 CLAUDE.md와 함께 시작 시 컨텍스트에 로드됩니다.

119 119

120상대 경로와 절대 경로 모두 허용됩니다. 상대 경로는 작업 디렉토리가 아닌 가져오기를 포함하는 파일을 기준으로 해석됩니다. 가져온 파일은 최대 4홉의 깊이로 다른 파일을 재귀적으로 가져올 수 있습니다.120상대 경로와 절대 경로 모두 허용됩니다. 상대 경로는 작업 디렉터리가 아닌 가져오기를 포함하는 파일을 기준으로 해석됩니다. 가져온 파일은 최대 4홉의 깊이로 다른 파일을 재귀적으로 가져올 수 있습니다.

121 121

122경로에 공백이 포함된 파일을 가져오려면 각 공백 앞에 백슬래시를 붙이십시오. 백슬래시가 없으면 경로가 첫 번째 공백에서 끝나며, 가져오기가 자신의 줄에 있더라도 마찬가지입니다. 따옴표로 감싼 경로는 백슬래시 유무에 관계없이 가져오지 않습니다. 이 가져오기는 `Design Docs`라는 폴더에서 파일을 로드합니다:122경로에 공백이 포함된 파일을 가져오려면 각 공백 앞에 백슬래시를 붙이십시오. 백슬래시가 없으면 경로가 첫 번째 공백에서 끝나며, 가져오기가 자신의 줄에 있더라도 마찬가지입니다. 따옴표로 감싼 경로는 백슬래시 유무에 관계없이 가져오지 않습니다. 이 가져오기는 `Design Docs`라는 폴더에서 파일을 로드합니다:

123 123

127 127

128가져오기 구문 분석은 마크다운 코드 스팬과 펜스된 코드 블록을 건너뜁니다. CLAUDE.md에서 경로를 언급하되 가져오지 않으려면 백틱으로 감싸십시오: `` `@README` ``를 작성하면 텍스트가 리터럴로 유지되고, 백틱 외부의 `@README`는 파일을 가져옵니다.128가져오기 구문 분석은 마크다운 코드 스팬과 펜스된 코드 블록을 건너뜁니다. CLAUDE.md에서 경로를 언급하되 가져오지 않으려면 백틱으로 감싸십시오: `` `@README` ``를 작성하면 텍스트가 리터럴로 유지되고, 백틱 외부의 `@README`는 파일을 가져옵니다.

129 129

130README, package.json 및 워크플로우 가이드를 가져오려면 CLAUDE.md의 어디든지 `@` 구문으로 참조하십시오:130README, package.json 및 워크플로 가이드를 가져오려면 CLAUDE.md의 어디든지 `@` 구문으로 참조하십시오:

131 131

132```text theme={null}132```text theme={null}

133프로젝트 개요는 @README를 참조하고 이 프로젝트의 사용 가능한 npm 명령어는 @package.json을 참조하십시오.133See @README for project overview and @package.json for available npm commands for this project.

134 134

135# 추가 지침135# Additional Instructions

136- git 워크플로우 @docs/git-instructions.md136- git workflow @docs/git-instructions.md

137```137```

138 138

139버전 제어에 체크인되지 않아야 하는 개인 프로젝트별 선호도의 경우 프로젝트 루트에 `CLAUDE.local.md`를 만드십시오. 이는 `CLAUDE.md`와 함께 로드되고 같은 방식으로 처리됩니다. `CLAUDE.local.md`를 `.gitignore`에 추가하여 커밋되지 않도록 하십시오. `CLAUDE_CODE_NEW_INIT=1`이 설정된 상태에서 `/init`을 실행하고 개인 옵션을 선택하면 이를 자동으로 수행합니다.139버전 제어에 체크인되지 않아야 하는 개인 프로젝트별 선호도의 경우 프로젝트 루트에 `CLAUDE.local.md`를 만드십시오. 이는 `CLAUDE.md`와 함께 로드되고 같은 방식으로 처리됩니다. `CLAUDE.local.md`를 `.gitignore`에 추가하여 커밋되지 않도록 하십시오. `CLAUDE_CODE_NEW_INIT=1`이 설정된 상태에서 `/init`을 실행하고 개인 옵션을 선택하면 이를 자동으로 수행합니다.

140 140

141같은 저장소의 여러 git worktree에서 작업하는 경우, gitignored `CLAUDE.local.md`는 생성한 worktree에만 존재합니다. 여러 worktree에서 개인 지침을 공유하려면 대신 홈 디렉토리에서 파일을 가져오십시오:141같은 저장소의 여러 git worktree에서 작업하는 경우, gitignored `CLAUDE.local.md`는 생성한 worktree에만 존재합니다. 여러 worktree에서 개인 지침을 공유하려면 대신 홈 디렉터리에서 파일을 가져오십시오:

142 142

143```text theme={null}143```text theme={null}

144# 개인 선호도144# Individual Preferences

145- @~/.claude/my-project-instructions.md145- @~/.claude/my-project-instructions.md

146```146```

147 147

148<Warning>148<Warning>

149 프로젝트 수준 메모리 파일의 가져오기는 홈 디렉토리 가져오기와 같이 경로가 작업 디렉토리 외부로 해석될 때 외부입니다. Claude Code가 프로젝트에서 외부 가져오기를 처음 만날 때 파일을 나열하는 승인 대화를 표시합니다. 거부하면 가져오기가 비활성화된 상태로 유지되고 대화가 다시 나타나지 않습니다.149 프로젝트 수준 메모리 파일의 가져오기는 위의 홈 디렉터리 가져오기와 같이 경로가 작업 디렉터리 외부로 해석될 때 외부 가져오기입니다. Claude Code가 프로젝트에서 외부 가져오기를 처음 만날 때 파일을 나열하는 승인 대화 상자를 표시합니다. 거부하면 가져오기가 비활성화된 상태로 유지되고 대화 상자가 다시 나타나지 않습니다.

150 150

151 Claude Code는 공유 프로젝트에 커밋한 다른 사람의 파일로부터 보호하기 위해 대화를 표시합니다. `~/.claude/CLAUDE.md` 및 `~/.claude/rules/`와 같은 사용자 범위 메모리 파일은 본인이 작성한 파일입니다. [Cowork](https://claude.com/product/cowork) 데스크톱 세션을 제외하고 Claude Code는 대화 없이 이들의 가져오기를 로드하고 나머지 개인 구성처럼 신뢰합니다.151 Claude Code는 다른 사람이 공유 프로젝트에 커밋한 파일로부터 사용자를 보호하기 위해 대화 상자를 표시합니다. `~/.claude/CLAUDE.md` 및 `~/.claude/rules/`와 같은 사용자 범위 메모리 파일은 본인이 작성한 파일입니다. [Cowork](https://claude.com/product/cowork) 데스크톱 세션을 제외하고 Claude Code는 대화 상자 없이 이들의 가져오기를 로드하고 나머지 개인 구성처럼 신뢰합니다.

152 152

153 데스크톱의 Cowork 세션에서 Claude Code는 사용자 범위 파일에서 세션의 작업 디렉토리 외부의 경로로 해석되는 가져오기를 건너뛰고 파일의 나머지는 로드합니다. 이러한 세션에서는 심볼릭 링크 또는 하드 링크인 `~/.claude/CLAUDE.md`와 작업 디렉토리 외부를 가리키는 심볼릭 링크된 `~/.claude/rules/` 디렉토리 또는 규칙 파일도 건너뜁니다.153 데스크톱의 Cowork 세션에서 Claude Code는 사용자 범위 파일에서 세션의 작업 디렉터리 외부의 경로로 해석되는 가져오기를 건너뛰고 파일의 나머지는 로드합니다. 이러한 세션에서는 그 자체가 심볼릭 링크 또는 하드 링크인 `~/.claude/CLAUDE.md`와 작업 디렉터리 외부를 가리키는 심볼릭 링크된 `~/.claude/rules/` 디렉터리 또는 규칙 파일도 건너뜁니다.

154</Warning>154</Warning>

155 155

156<h3 id="how-claude-md-files-load">156<h3 id="how-claude-md-files-load">

157 CLAUDE.md 파일이 로드되는 방식157 CLAUDE.md 파일이 로드되는 방식

158</h3>158</h3>

159 159

160Claude Code는 현재 작업 디렉토리와 그 위의 모든 디렉토리에서 `CLAUDE.md` 및 `CLAUDE.local.md`를 로드합니다. `foo/bar/`에서 Claude Code를 실행하면 `foo/bar/CLAUDE.md`, `foo/CLAUDE.md` 및 이들 옆의 모든 `CLAUDE.local.md` 파일을 로드합니다.160Claude Code는 현재 작업 디렉터리와 그 위의 모든 디렉터리에서 `CLAUDE.md` 및 `CLAUDE.local.md`를 로드합니다. `foo/bar/`에서 Claude Code를 실행하면 `foo/bar/CLAUDE.md`, `foo/CLAUDE.md` 및 이들 옆의 모든 `CLAUDE.local.md` 파일을 로드합니다.

161 161

162발견된 모든 파일은 서로를 재정의하지 않고 컨텍스트에 연결됩니다. 디렉토리 트리 전체에서 콘텐츠는 파일 시스템 루트에서 작업 디렉토리까지 순서대로 정렬됩니다. `foo/bar/` 예시의 경우 `foo/CLAUDE.md`가 `foo/bar/CLAUDE.md` 이전에 컨텍스트에 나타나므로 Claude를 시작한 위치에 더 가까운 지침이 마지막에 읽힙니다. 각 디렉토리 내에서 `CLAUDE.local.md`는 `CLAUDE.md` 이후에 추가되므로 개인 노트가 해당 수준에서 Claude가 읽는 마지막 항목입니다.162발견된 모든 파일은 서로를 재정의하지 않고 컨텍스트에 연결됩니다. 디렉터리 트리 전체에서 콘텐츠는 파일 시스템 루트에서 작업 디렉터리까지 순서대로 정렬됩니다. `foo/bar/` 예시의 경우 `foo/CLAUDE.md`가 `foo/bar/CLAUDE.md` 이전에 컨텍스트에 나타나므로 Claude를 시작한 위치에 더 가까운 지침이 마지막에 읽힙니다. 각 디렉터리 내에서 `CLAUDE.local.md`는 `CLAUDE.md` 이후에 추가되므로 개인 노트가 해당 수준에서 Claude가 읽는 마지막 항목입니다.

163 163

164Claude는 또한 현재 작업 디렉토리 아래의 하위 디렉토리에서 `CLAUDE.md` 및 `CLAUDE.local.md` 파일을 발견합니다. 시작 시 로드하지 않고 Claude가 해당 하위 디렉토리의 파일을 읽을 때 포함됩니다.164Claude는 또한 현재 작업 디렉터리 아래의 하위 디렉터리에서 `CLAUDE.md` 및 `CLAUDE.local.md` 파일을 발견합니다. 시작 시 로드하지 않고 Claude가 해당 하위 디렉터리의 파일을 읽을 때 포함됩니다. `.claude/worktrees/` 아래의 워크트리 내부 파일에 대해서는 [워크트리로 서브에이전트 격리하기](/docs/ko/worktrees#isolate-subagents-with-worktrees)를 참조하십시오.

165 165

166대규모 모노레포에서 작업하고 다른 팀의 CLAUDE.md 파일이 선택되는 경우 [`claudeMdExcludes`](#exclude-specific-claude-md-files)를 사용하여 건너뛰십시오. 루트 및 디렉토리별 CLAUDE.md 파일과 규칙의 전체 레이아웃은 [모노레포 및 대규모 저장소](/docs/ko/large-codebases)를 참조하십시오.166대규모 모노레포에서 작업하고 다른 팀의 CLAUDE.md 파일이 선택되는 경우 [`claudeMdExcludes`](#exclude-specific-claude-md-files)를 사용하여 건너뛰십시오. 루트 및 디렉터리별 CLAUDE.md 파일과 규칙의 전체 레이아웃은 [모노레포 및 대규모 저장소](/docs/ko/large-codebases)를 참조하십시오.

167 167

168CLAUDE.md 파일의 블록 수준 HTML 주석(``)은 Claude의 컨텍스트에 주입되기 전에 제거됩니다. 컨텍스트 토큰을 소비하지 않고 인간 유지보수자를 위한 노트를 남기는 데 사용하십시오. 코드 블록 내의 주석은 보존됩니다. Read 도구로 CLAUDE.md 파일을 직접 열 때 주석이 표시됩니다.168CLAUDE.md 파일의 블록 수준 HTML 주석(``)은 Claude의 컨텍스트에 주입되기 전에 제거됩니다. 컨텍스트 토큰을 소비하지 않고 인간 유지보수자를 위한 노트를 남기는 데 사용하십시오. 코드 블록 내의 주석은 보존됩니다. Read 도구로 CLAUDE.md 파일을 직접 열 때 주석이 표시됩니다.

169 169

170<h4 id="load-from-additional-directories">170<h4 id="load-from-additional-directories">

171 추가 디렉토리에서 로드하기171 추가 디렉터리에서 로드하기

172</h4>172</h4>

173 173

174`--add-dir` 플래그는 Claude에게 주 작업 디렉토리 외부의 추가 디렉토리에 대한 액세스를 제공합니다. 기본적으로 이러한 디렉토리의 CLAUDE.md 파일은 로드되지 않습니다.174`--add-dir` 플래그는 Claude에게 주 작업 디렉터리 외부의 추가 디렉터리에 대한 액세스를 제공합니다. 기본적으로 이러한 디렉터리의 CLAUDE.md 파일은 로드되지 않습니다.

175 175

176추가 디렉토리에서 메모리 파일도 로드하려면 `CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD` 환경 변수를 설정하십시오:176추가 디렉터리에서 메모리 파일도 로드하려면 `CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD` 환경 변수를 설정하십시오:

177 177

178```bash theme={null}178```bash theme={null}

179CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1 claude --add-dir ../shared-config179CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1 claude --add-dir ../shared-config

181 181

182인라인 형식은 Bash 또는 Zsh에서 해당 한 번의 시작을 위해 변수를 설정합니다. 모든 세션에서 계속 설정하려면 [환경 변수 설정](/docs/ko/env-vars#set-environment-variables)에 표시된 대로 `~/.claude/settings.json`의 `env` 블록에 추가하십시오.182인라인 형식은 Bash 또는 Zsh에서 해당 한 번의 시작을 위해 변수를 설정합니다. 모든 세션에서 계속 설정하려면 [환경 변수 설정](/docs/ko/env-vars#set-environment-variables)에 표시된 대로 `~/.claude/settings.json`의 `env` 블록에 추가하십시오.

183 183

184이는 추가 디렉토리에서 `CLAUDE.md`, `.claude/CLAUDE.md`, `.claude/rules/*.md` 및 `CLAUDE.local.md`를 로드합니다. [`--setting-sources`](/docs/ko/cli-reference)에서 `local`을 제외하면 `CLAUDE.local.md`가 건너뛰어집니다.184이는 추가 디렉터리에서 `CLAUDE.md`, `.claude/CLAUDE.md`, `.claude/rules/*.md` 및 `CLAUDE.local.md`를 로드합니다. [`--setting-sources`](/docs/ko/cli-reference)에서 `local`을 제외하면 `CLAUDE.local.md`가 건너뛰어집니다.

185 185

186<h3 id="organize-rules-with-claude/rules/">186<h3 id="organize-rules-with-claude/rules/">

187 `.claude/rules/`로 규칙 정리하기187 `.claude/rules/`로 규칙 정리하기

188</h3>188</h3>

189 189

190더 큰 프로젝트의 경우 `.claude/rules/` 디렉토리를 사용하여 지침을 여러 파일로 정리할 수 있습니다. 이는 지침을 모듈식으로 유지하고 팀이 유지보수하기 쉽게 합니다. 규칙은 또한 [특정 파일 경로로 범위를 지정](#path-specific-rules)할 수 있으므로 Claude가 일치하는 파일로 작업할 때만 컨텍스트에 로드되어 노이즈를 줄이고 컨텍스트 공간을 절약합니다.190더 큰 프로젝트의 경우 `.claude/rules/` 디렉터리를 사용하여 지침을 여러 파일로 정리할 수 있습니다. 이는 지침을 모듈식으로 유지하고 팀이 유지보수하기 쉽게 합니다. 규칙은 또한 [특정 파일 경로로 범위를 지정](#path-specific-rules)할 수 있으므로 Claude가 일치하는 파일로 작업할 때만 컨텍스트에 로드되어 노이즈를 줄이고 컨텍스트 공간을 절약합니다.

191 191

192<Note>192<Note>

193 규칙은 매 세션마다 또는 일치하는 파일이 열릴 때 컨텍스트에 로드됩니다. 항상 컨텍스트에 있을 필요가 없는 작업별 지침의 경우 대신 [스킬](/docs/ko/skills)을 사용하십시오. 스킬은 호출할 때 또는 Claude가 프롬프트와 관련이 있다고 판단할 때만 로드됩니다.193 규칙은 매 세션마다 또는 일치하는 파일이 열릴 때 컨텍스트에 로드됩니다. 항상 컨텍스트에 있을 필요가 없는 작업별 지침의 경우 대신 [스킬](/docs/ko/skills)을 사용하십시오. 스킬은 호출할 때 또는 Claude가 프롬프트와 관련이 있다고 판단할 때만 로드됩니다.

197 규칙 설정하기197 규칙 설정하기

198</h4>198</h4>

199 199

200프로젝트의 `.claude/rules/` 디렉토리에 마크다운 파일을 배치하십시오. 각 파일은 `testing.md` 또는 `api-design.md`와 같은 설명적인 파일명으로 한 가지 주제를 다루어야 합니다. 모든 `.md` 파일은 재귀적으로 발견되므로 `frontend/` 또는 `backend/`와 같은 하위 디렉토리로 규칙을 정리할 수 있습니다:200프로젝트의 `.claude/rules/` 디렉터리에 마크다운 파일을 배치하십시오. 각 파일은 `testing.md` 또는 `api-design.md`와 같은 설명적인 파일명으로 한 가지 주제를 다루어야 합니다. 모든 `.md` 파일은 재귀적으로 발견되므로 `frontend/` 또는 `backend/`와 같은 하위 디렉터리로 규칙을 정리할 수 있습니다:

201 201

202```text theme={null}202```text theme={null}

203your-project/203your-project/

204├── .claude/204├── .claude/

205│ ├── CLAUDE.md # 주 프로젝트 지침205│ ├── CLAUDE.md # Main project instructions

206│ └── rules/206│ └── rules/

207│ ├── code-style.md # 코드 스타일 가이드라인207│ ├── code-style.md # Code style guidelines

208│ ├── testing.md # 테스트 규칙208│ ├── testing.md # Testing conventions

209│ └── security.md # 보안 요구사항209│ └── security.md # Security requirements

210```210```

211 211

212[`paths` frontmatter](#path-specific-rules)가 없는 규칙은 `.claude/CLAUDE.md`와 같은 우선순위로 시작 시 로드됩니다.212[`paths` frontmatter](#path-specific-rules)가 없는 규칙은 `.claude/CLAUDE.md`와 같은 우선순위로 시작 시 로드됩니다.

213 213

214프로젝트 규칙은 [`--setting-sources`](/docs/ko/cli-reference)에서 `project`를 제외하면 건너뛰어집니다. v2.1.211 이전에는 경로 범위 규칙 및 중첩된 `.claude/rules/` 디렉토리의 규칙을 포함하여 필요에 따라 로드되는 규칙이 `project`가 제외되었을 때도 로드되었습니다.214프로젝트 규칙은 [`--setting-sources`](/docs/ko/cli-reference)에서 `project`를 제외하면 건너뛰어집니다. v2.1.211 이전에는 경로 범위 규칙 및 중첩된 `.claude/rules/` 디렉터리의 규칙을 포함하여 필요에 따라 로드되는 규칙이 `project`가 제외되었을 때도 로드되었습니다.

215 215

216<h4 id="path-specific-rules">216<h4 id="path-specific-rules">

217 경로별 규칙217 경로별 규칙

225 - "src/api/**/*.ts"225 - "src/api/**/*.ts"

226---226---

227 227

228# API 개발 규칙228# API Development Rules

229 229

230- 모든 API 엔드포인트는 입력 검증을 포함해야 합니다230- All API endpoints must include input validation

231- 표준 오류 응답 형식 사용231- Use the standard error response format

232- OpenAPI 문서 주석 포함232- Include OpenAPI documentation comments

233```233```

234 234

235`paths` 필드가 없는 규칙은 무조건 로드되고 모든 파일에 적용됩니다. 경로 범위 규칙은 모든 도구 사용이 아닌 Claude가 패턴과 일치하는 파일을 읽을 때 트리거됩니다. v2.1.198부터 일치는 또한 Claude가 프로젝트 디렉토리의 심볼릭 링크된 경로를 통해 파일에 도달할 때도 작동합니다(예: 심볼릭 링크된 체크아웃).235`paths` 필드가 없는 규칙은 무조건 로드되고 모든 파일에 적용됩니다. 경로 범위 규칙은 모든 도구 사용이 아닌 Claude가 패턴과 일치하는 파일을 읽을 때 트리거됩니다. 일치는 Claude가 프로젝트 디렉터리의 심볼릭 링크된 경로를 통해 파일에 도달할 때도 작동합니다(예: 심볼릭 링크된 체크아웃).

236 236

237`paths` 필드에서 glob 패턴을 사용하여 확장자, 디렉토리 또는 조합으로 파일을 일치시키십시오:237`paths` 필드에서 glob 패턴을 사용하여 확장자, 디렉터리 또는 조합으로 파일을 일치시키십시오:

238 238

239| 패턴 | 일치 |239| 패턴 | 일치 |

240| - | - |240| - | - |

241| `**/*.ts` | 모든 디렉토리의 모든 TypeScript 파일 |241| `**/*.ts` | 모든 디렉터리의 모든 TypeScript 파일 |

242| `src/**/*` | `src/` 디렉토리 아래의 모든 파일 |242| `src/**/*` | `src/` 디렉터리 아래의 모든 파일 |

243| `*.md` | 프로젝트 루트의 마크다운 파일 |243| `*.md` | 프로젝트 루트의 마크다운 파일 |

244| `src/components/*.tsx` | 특정 디렉토리의 React 컴포넌트 |244| `src/components/*.tsx` | 특정 디렉터리의 React 컴포넌트 |

245 245

246여러 패턴을 지정하고 중괄호 확장을 사용하여 한 패턴에서 여러 확장자를 일치시킬 수 있습니다:246여러 패턴을 지정하고 중괄호 확장을 사용하여 한 패턴에서 여러 확장자를 일치시킬 수 있습니다:

247 247

258 258

259Claude Code는 예산을 초과할 패턴을 확장되지 않은 상태로 사용하며, 리터럴 중괄호는 파일과 일치하지 않습니다. v2.1.217 이전에는 많은 중괄호 그룹이 있는 `paths` 값이 시작 시 CLI를 정지시키거나 충돌시켰습니다.259Claude Code는 예산을 초과할 패턴을 확장되지 않은 상태로 사용하며, 리터럴 중괄호는 파일과 일치하지 않습니다. v2.1.217 이전에는 많은 중괄호 그룹이 있는 `paths` 값이 시작 시 CLI를 정지시키거나 충돌시켰습니다.

260 260

261Glob 구문은 `[`를 `[abc]`와 같은 괄호 표현식의 시작으로 취급합니다. `photos [2024/**`와 같이 괄호 표현식으로 읽을 수 없는 `[`가 있는 패턴은 유효하지 않습니다: 파일과 일치하지 않으며 규칙의 다른 패턴은 계속 작동합니다. 파일 이름의 리터럴 `[`를 일치시키려면 `photos \[2024/**`로 이스케이프하십시오. v2.1.207 이전에는 하나의 유효하지 않은 패턴이 모든 도구 사용 대신 규칙이 평가된 모든 파일에 대해 Read 도구를 실패하게 했습니다.261Glob 구문은 `[`를 `[abc]`와 같은 괄호 표현식의 시작으로 취급합니다. `photos [2024/**`와 같이 괄호 표현식으로 읽을 수 없는 `[`가 있는 패턴은 유효하지 않습니다: 아무것도 일치하지 않으며 규칙의 다른 패턴은 계속 작동합니다. 파일 이름의 리터럴 `[`를 일치시키려면 `photos \[2024/**`로 이스케이프하십시오. v2.1.207 이전에는 유효하지 않은 패턴 하나가 아무것도 일치하지 않는 대신, 규칙이 평가된 모든 파일에 대해 Read 도구를 실패하게 했습니다.

262 262

263<h4 id="rules-frontmatter-reference">263<h4 id="rules-frontmatter-reference">

264 규칙 frontmatter 참조264 규칙 frontmatter 참조

265</h4>265</h4>

266 266

267YAML [frontmatter](/docs/ko/glossary#frontmatter)로 규칙을 구성하십시오. `---` 마커 사이에 위치합니다. `paths`는 Claude Code가 규칙에서 읽는 유일한 필드입니다. 다른 필드는 오류 없이 무시됩니다. Claude Code는 규칙을 컨텍스트에 로드하기 전에 frontmatter를 제거합니다.267파일 상단의 `---` 마커 사이에 YAML [frontmatter](/docs/ko/glossary#frontmatter)를 사용하여 규칙을 구성하십시오. `paths`는 Claude Code가 규칙에서 읽는 유일한 필드입니다. 다른 필드는 오류 없이 무시됩니다. Claude Code는 규칙을 컨텍스트에 로드하기 전에 frontmatter를 제거합니다.

268 268

269| 필드 | 필수 | 설명 |269| 필드 | 필수 | 설명 |

270| :- | :- | :- |270| :- | :- | :- |

276 심볼릭 링크로 프로젝트 간 규칙 공유하기276 심볼릭 링크로 프로젝트 간 규칙 공유하기

277</h4>277</h4>

278 278

279`.claude/rules/` 디렉토리는 심볼릭 링크를 지원하므로 공유 규칙 세트를 유지하고 여러 프로젝트에 링크할 수 있습니다. 순환 심볼릭 링크는 감지되고 우아하게 처리됩니다.279`.claude/rules/` 디렉터리는 심볼릭 링크를 지원하므로 공유 규칙 세트를 유지하고 여러 프로젝트에 링크할 수 있습니다. 순환 심볼릭 링크는 감지되고 우아하게 처리됩니다.

280 280

281Claude Code는 대상이 작업 디렉토리 외부인 심볼릭 링크를 [외부 가져오기](#import-additional-files)처럼 취급합니다. 링크된 규칙은 프로젝트에 대한 외부 가져오기를 승인할 때까지 로드되지 않으며, 그 후 [`paths` 필드](#path-specific-rules)가 없는 규칙만 로드됩니다. Claude Code는 프로젝트 메모리 파일이 `@path`로 작업 디렉토리 외부의 파일을 가져올 때만 승인을 요청하며, 심볼릭 링크만으로는 요청하지 않습니다. 해당 승인 없이 공유 규칙을 로드하려면 [`~/.claude/rules/`](#user-level-rules)에 유지하십시오. 여기서 컴퓨터의 모든 프로젝트에 적용됩니다.281Claude Code는 대상이 작업 디렉터리 외부인 심볼릭 링크를 [외부 가져오기](#import-additional-files)처럼 취급합니다. 링크된 규칙은 프로젝트에 대한 외부 가져오기를 승인할 때까지 로드되지 않으며, 그 후 [`paths` 필드](#path-specific-rules)가 없는 규칙만 로드됩니다. Claude Code는 프로젝트 메모리 파일이 `@path`로 작업 디렉터리 외부의 파일을 가져올 때만 승인을 요청하며, 심볼릭 링크만으로는 요청하지 않습니다. 해당 승인 없이 공유 규칙을 로드하려면 [`~/.claude/rules/`](#user-level-rules)에 유지하십시오. 여기서 컴퓨터의 모든 프로젝트에 적용됩니다.

282 282

283이 예시는 공유 디렉토리와 개별 파일을 모두 링크합니다:283이 예시는 공유 디렉터리와 개별 파일을 모두 링크합니다:

284 284

285```bash theme={null}285```bash theme={null}

286ln -s ~/shared-claude-rules .claude/rules/shared286ln -s ~/shared-claude-rules .claude/rules/shared

287ln -s ~/company-standards/security.md .claude/rules/security.md287ln -s ~/company-standards/security.md .claude/rules/security.md

288```288```

289 289

290네트워크 경로(예: UNC 공유 `\\server\share` 또는 `/net` 또는 `/Network` 아래의 경로)에 `.claude/rules/` 또는 `CLAUDE.md` 심볼릭 링크를 가리키면 링크된 지침이 로드되지 않습니다. Claude Code는 이러한 경로를 조회하면 호스트에 연결할 수 있으므로 링크를 따르지 않습니다. `\\wsl$` 경로는 네트워크 경로로 계산되지 않습니다.290네트워크 경로(예: UNC 공유 `\\server\share` 또는 `/net` 또는 `/Network` 아래의 경로)에 `.claude/rules/` 또는 `CLAUDE.md` 심볼릭 링크를 가리키면 링크된 지침이 로드되지 않습니다. Claude Code는 이러한 경로를 조회하면 해당 경로가 가리키는 호스트에 연결할 수 있으므로 링크를 따르지 않습니다. `\\wsl$` 경로는 네트워크 경로로 계산되지 않습니다.

291 291

292<h4 id="user-level-rules">292<h4 id="user-level-rules">

293 사용자 수준 규칙293 사용자 수준 규칙

297 297

298```text theme={null}298```text theme={null}

299~/.claude/rules/299~/.claude/rules/

300├── preferences.md # 개인 코딩 선호도300├── preferences.md # Your personal coding preferences

301└── workflows.md # 선호하는 워크플로우301└── workflows.md # Your preferred workflows

302```302```

303 303

304Claude Code는 사용자 수준 규칙을 프로젝트 규칙 이전에 로드하므로 프로젝트 규칙이 Claude의 컨텍스트에서 사용자 규칙보다 나중에 나타납니다. 어느 쪽도 다른 쪽을 재정의하지 않습니다: 사용자 규칙과 프로젝트 규칙이 충돌하면 Claude가 둘 중 하나를 따를 수 있으므로 둘을 일관되게 유지하십시오.304Claude Code는 사용자 수준 규칙을 프로젝트 규칙 이전에 로드하므로 프로젝트 규칙이 Claude의 컨텍스트에서 사용자 규칙보다 나중에 나타납니다. 어느 쪽도 다른 쪽을 재정의하지 않습니다: 사용자 규칙과 프로젝트 규칙이 충돌하면 Claude가 둘 중 하나를 따를 수 있으므로 둘을 일관되게 유지하십시오.

347 347

348| 관심사 | 구성 위치 |348| 관심사 | 구성 위치 |

349| :- | :- |349| :- | :- |

363 363

364대규모 모노레포에서 상위 CLAUDE.md 파일에는 작업과 관련이 없는 지침이 포함될 수 있습니다. `claudeMdExcludes` 설정을 사용하면 경로 또는 glob 패턴으로 특정 파일을 건너뛸 수 있습니다.364대규모 모노레포에서 상위 CLAUDE.md 파일에는 작업과 관련이 없는 지침이 포함될 수 있습니다. `claudeMdExcludes` 설정을 사용하면 경로 또는 glob 패턴으로 특정 파일을 건너뛸 수 있습니다.

365 365

366이 예시는 상위 폴더의 최상위 CLAUDE.md 및 규칙 디렉토리를 제외합니다. `.claude/settings.local.json`에 추가하여 제외가 머신에 로컬로 유지되도록 하십시오:366이 예시는 상위 폴더의 최상위 CLAUDE.md 및 규칙 디렉터리를 제외합니다. `.claude/settings.local.json`에 추가하여 제외가 머신에 로컬로 유지되도록 하십시오:

367 367

368```json theme={null}368```json theme={null}

369{369{

376 376

377패턴은 glob 구문을 사용하여 절대 파일 경로와 일치합니다. 사용자, 프로젝트, 로컬 또는 관리형 정책을 포함한 모든 [설정 계층](/docs/ko/settings#where-settings-live)에서 `claudeMdExcludes`를 구성할 수 있습니다. 배열은 계층 전체에서 병합됩니다.377패턴은 glob 구문을 사용하여 절대 파일 경로와 일치합니다. 사용자, 프로젝트, 로컬 또는 관리형 정책을 포함한 모든 [설정 계층](/docs/ko/settings#where-settings-live)에서 `claudeMdExcludes`를 구성할 수 있습니다. 배열은 계층 전체에서 병합됩니다.

378 378

379[심볼릭 링크](#share-rules-across-projects-with-symlinks)를 통해 도달하는 규칙 파일을 제외하려면, 파일 또는 해당 디렉토리가 링크인지 여부에 관계없이 두 경로 중 하나에 대해 패턴을 작성하십시오: `.claude/rules/` 아래의 파일 경로 또는 링크 대상. 두 경로 중 하나와 일치하는 패턴은 파일을 제외합니다. v2.1.239 이전에는 링크 대상과 일치하는 패턴만 파일을 제외했습니다.379[심볼릭 링크](#share-rules-across-projects-with-symlinks)를 통해 도달하는 규칙 파일을 제외하려면, 파일 또는 해당 디렉터리가 링크인지 여부에 관계없이 두 경로 중 하나에 대해 패턴을 작성하십시오: `.claude/rules/` 아래의 파일 경로 또는 링크 대상. 두 경로 중 하나와 일치하는 패턴은 파일을 제외합니다. v2.1.239 이전에는 링크 대상과 일치하는 패턴만 파일을 제외했습니다.

380 380

381관리형 정책 CLAUDE.md 파일은 제외될 수 없습니다. 이는 개별 설정에 관계없이 조직 전체 지침이 항상 적용되도록 보장합니다.381관리형 정책 CLAUDE.md 파일은 제외될 수 없습니다. 이는 개별 설정에 관계없이 조직 전체 지침이 항상 적용되도록 보장합니다.

382 382

538 자동 메모리 활성화 또는 비활성화538 자동 메모리 활성화 또는 비활성화

539</h3>539</h3>

540 540

541자동 메모리는 기본적으로 켜져 있습니다. 토글하려면 세션에서 `/memory`를 열고 자동 메모리 토글을 사용하면 `autoMemoryEnabled`가 `~/.claude/settings.json`의 사용자 설정에 저장됩니다. 단일 프로젝트에 대해 끄려면 해당 프로젝트의 설정에서 `autoMemoryEnabled`를 설정합니다:541자동 메모리는 로컬 세션에서 기본적으로 켜져 있습니다. [Claude Tag](https://claude.com/docs/claude-tag/overview) 세션 외부에서는 [자체 호스팅 환경](/docs/ko/self-hosted-environments-configuration#how-each-session’s-config-is-assembled)의 세션이 기본적으로 자동 메모리가 꺼진 상태로 실행됩니다.

542

543토글하려면 세션에서 `/memory`를 열고 자동 메모리 토글을 사용하면 `autoMemoryEnabled`가 `~/.claude/settings.json`의 사용자 설정에 저장됩니다. 단일 프로젝트에 대해 끄려면 해당 프로젝트의 설정에서 `autoMemoryEnabled`를 설정합니다:

542 544

543```json theme={null}545```json theme={null}

544{546{

plugins/cli-reference.md +19 −1

Details

571* 태그가 이미 존재함571* 태그가 이미 존재함

572* 작업 트리가 더티함572* 작업 트리가 더티함

573 573

574<h3 id="plugin-test">

575 plugin test

576</h3>

577

578코드가 이벤트 핸들러를 등록하는 플러그인인 [mod](/docs/ko/plugins/mods/overview)의 테스트를 실행합니다. 이 명령에는 세션, 로그인, 네트워크가 필요하지 않습니다. 테스트 작성 방법은 [mod 테스트](/docs/ko/plugins/mods/test)를 참조하세요.

579

580```bash theme={null}

581claude plugin test [directory]

582```

583

584`[directory]`는 mod의 디렉토리이며 현재 디렉토리로 기본값입니다. 명령은 그 아래에서 이름이 `.test.ts` 또는 `.test.tsx`로 끝나는 모든 파일을 실행하고, 테스트가 실패하면 상태 1로 종료합니다.

585

586`./first-mod`에 있는 mod의 테스트를 실행합니다:

587

588```bash theme={null}

589claude plugin test ./first-mod

590```

591

574<h3 id="plugin-validate">592<h3 id="plugin-validate">

575 plugin validate593 plugin validate

576</h3>594</h3>

804 822

805`<plugin>`은 플러그인 `name` 또는 `name@marketplace`입니다.823`<plugin>`은 플러그인 `name` 또는 `name@marketplace`입니다.

806 824

807아래 표는 모든 세션 형식을 나열합니다. 셸 하위 명령어 `init`, `update`, `details`, `prune`, `eval` 및 `eval init`에는 세션 형식이 없습니다.825아래 표는 모든 세션 형식을 나열합니다. 셸 하위 명령 `init`, `update`, `details`, `prune`, `eval`, `eval init` 및 `test`에는 세션 형식이 없습니다.

808 826

809| 명령어 | 별칭 | 어떤 일을 하는지 |827| 명령어 | 별칭 | 어떤 일을 하는지 |

810| :- | :- | :- |828| :- | :- | :- |

plugins/loading.md +20 −14

Details

244 종속성 설치가 실행되는 경우244 종속성 설치가 실행되는 경우

245</h4>245</h4>

246 246

247Claude Code는 생성할 때마다 복사된 버전 디렉토리 내에서 설치를 실행합니다:247Claude Code는 복사된 버전 디렉토리를 생성할 때마다 그 안에 의존성을 설치합니다:

248 248

249* 플러그인을 설치할 때249* 플러그인을 설치할 때

250* Claude Code가 플러그인을 새 버전으로 업데이트할 때250* Claude Code가 플러그인을 새 버전으로 업데이트할 때

252 252

253로컬 디렉토리 마켓플레이스에서 [제자리로 로드된](#in-place-and-copied-plugins) 상대 경로 플러그인의 경우 Claude Code는 소스 디렉토리에 종속성을 설치하지 않습니다. 거기에 설치하거나 훅에서 [`${CLAUDE_PLUGIN_DATA}`](/docs/ko/plugins/components#path-variables-and-persistent-data)로 설치합니다.253로컬 디렉토리 마켓플레이스에서 [제자리로 로드된](#in-place-and-copied-plugins) 상대 경로 플러그인의 경우 Claude Code는 소스 디렉토리에 종속성을 설치하지 않습니다. 거기에 설치하거나 훅에서 [`${CLAUDE_PLUGIN_DATA}`](/docs/ko/plugins/components#path-variables-and-persistent-data)로 설치합니다.

254 254

255설치는 플러그인의 루트 디렉토리에 `package.json`과 지원되는 잠금 파일이 모두 포함될 때만 실행됩니다. 잠금 파일은 Claude Code가 실행하는 명령을 결정합니다:255설치는 플러그인의 루트 디렉토리에 `package.json`과 지원되는 잠금 파일이 모두 포함될 때만 실행됩니다.

256 256

257| 잠금 파일 | 명령 |257잠금 파일에 따라 Claude Code가 실행하는 패키지 관리자가 결정됩니다:

258

259| 잠금 파일 | 패키지 관리자 |

258| :- | :- |260| :- | :- |

259| `bun.lock` 또는 `bun.lockb` | `bun install --frozen-lockfile --ignore-scripts` |261| `bun.lock` | Bun |

260| `npm-shrinkwrap.json` 또는 `package-lock.json` | `npm ci --ignore-scripts` |262| `npm-shrinkwrap.json` 또는 `package-lock.json` | npm |

261 263

262플러그인에 이러한 잠금 파일이 두 개 이상 포함되어 있으면 Claude Code는 첫 번째 일치를 사용하며 순서대로 확인합니다: `bun.lock`, `bun.lockb`, `npm-shrinkwrap.json`, `package-lock.json`.264플러그인에 이러한 잠금 파일이 두 개 이상 포함되어 있으면 Claude Code는 첫 번째 일치를 사용하며 순서대로 확인합니다: `bun.lock`, `npm-shrinkwrap.json`, `package-lock.json`.

263 265

264Claude Code는 Yarn 및 pnpm 잠금 파일과 Bun 잠금 파일 옆의 `bunfig.toml`에 대한 설치를 건너뜁니다:266Claude Code는 다음과 같은 잠금 파일의 경우 설치를 건너뜁니다:

265 267

266* 플러그인에 `yarn.lock` 또는 `pnpm-lock.yaml`만 있으면 npm 잠금 파일로 바꿉니다268* **`bun.lockb`**: Bun의 바이너리 잠금 파일은 검사할 수 없습니다. 대신 텍스트 형식의 `bun.lock` 또는 npm 잠금 파일을 함께 배포합니다

267* `bunfig.toml`이 Bun 잠금 파일과 같은 디렉토리에 있으면 `bunfig.toml`을 제거하거나 Bun 잠금 파일을 npm 잠금 파일로 바꿉니다269* **`yarn.lock` 또는 `pnpm-lock.yaml`**: npm 잠금 파일로 바꿉니다

270* **Claude Code가 읽지 않는 형식의 잠금 파일**: npm 잠금 파일은 npm 7 이상이 작성하는 `lockfileVersion` `2` 또는 `3`이어야 하며, `bun.lock`은 `lockfileVersion`이 `2` 이하여야 합니다

268 271

269npm 잠금 파일을 포함하여 가장 많은 사용자에게 도달합니다. Claude Code는 사용자의 PATH에서 일치하는 잠금 파일의 패키지 관리자를 실행하고 해당 패키지 관리자가 누락된 경우 다른 잠금 파일을 시도하지 않습니다.272npm 잠금 파일을 포함하여 가장 많은 사용자에게 도달합니다. Claude Code는 사용자의 PATH에서 일치하는 잠금 파일의 패키지 관리자를 실행하고 해당 패키지 관리자가 누락된 경우 다른 잠금 파일을 시도하지 않습니다.

270 273

276 279

277Claude Code는 이 종속성 설치를 제한하여 설치 중에 플러그인 또는 패키지의 코드가 실행되지 않도록 하고 실행 시간을 제한합니다:280Claude Code는 이 종속성 설치를 제한하여 설치 중에 플러그인 또는 패키지의 코드가 실행되지 않도록 하고 실행 시간을 제한합니다:

278 281

279* **고정 해결**: Bun 및 npm은 잠금 파일이 고정한 것을 정확히 설치하고 `package.json`과 잠금 파일이 불일치할 때 버전을 다시 해결하는 대신 실패합니다282* **레지스트리 패키지만**: 모든 의존성은 잠금 파일에 정확한 버전으로 고정된 레지스트리 패키지여야 합니다. git, GitHub, 폴더, 워크스페이스 또는 링크된 의존성이 있는 플러그인은 설치되지 않습니다.

283* **`https` 다운로드**: 잠금 파일의 다운로드 링크는 설치하는 사용자 자신의 기본 npm 레지스트리를 가리키는 경우가 아니면 `https`를 사용해야 합니다.

284* **별도의 설치 폴더**: 패키지 관리자는 검사된 의존성 목록의 복사본만 포함하는 자체 폴더에서 실행되므로 npm과 Bun은 플러그인의 `.npmrc`, `.env` 또는 `bunfig.toml`을 읽지 않습니다. 설치가 성공하면 Claude Code는 결과 `node_modules`를 플러그인으로 옮깁니다.

285* **고정 해결**: 설치는 잠금 파일이 고정한 버전을 정확히 사용하며, `package.json`과 잠금 파일이 동일한 의존성을 나열하지 않으면 Claude Code는 설치를 건너뜁니다

280* **라이프사이클 스크립트 없음**: `--ignore-scripts`는 `preinstall`, `install`, `postinstall` 스크립트가 실행되지 않도록 하므로 해당 스크립트에서 네이티브 모듈을 빌드하는 종속성은 다운로드되지만 이 설치 중에 컴파일되지 않습니다286* **라이프사이클 스크립트 없음**: `--ignore-scripts`는 `preinstall`, `install`, `postinstall` 스크립트가 실행되지 않도록 하므로 해당 스크립트에서 네이티브 모듈을 빌드하는 종속성은 다운로드되지만 이 설치 중에 컴파일되지 않습니다

287* **재정의 또는 패치 없음**: `package.json`에서 npm `overrides`를 설정한 플러그인은 npm 잠금 파일로부터 설치되지 않으며, Bun `patchedDependencies`를 설정한 플러그인은 `bun.lock`으로부터 설치되지 않습니다

281* **60초 타임아웃**: Claude Code는 더 오래 실행되는 설치를 중지하고 실패로 처리합니다288* **60초 타임아웃**: Claude Code는 더 오래 실행되는 설치를 중지하고 실패로 처리합니다

282 289

283Claude Code는 이 종속성 설치 전에 npm 소스 플러그인을 가져오고 패키지의 자체 설치 스크립트는 가져오는 중에 실행되지 않습니다. [npm 플러그인 소스](/docs/ko/plugins/marketplace-reference#npm-plugin-source)를 참조합니다.290Claude Code는 이 종속성 설치 전에 npm 소스 플러그인을 가져오고 패키지의 자체 설치 스크립트는 가져오는 중에 실행되지 않습니다. [npm 플러그인 소스](/docs/ko/plugins/marketplace-reference#npm-plugin-source)를 참조합니다.

290 종속성 설치가 실패하거나 건너뛰어질 때297 종속성 설치가 실패하거나 건너뛰어질 때

291</h4>298</h4>

292 299

293실패하거나 건너뛴 설치는 플러그인을 절대 차단하지 않으며 각 경우는 다른 신호를 남깁니다:300실패하거나 건너뛴 설치는 플러그인을 절대 차단하지 않으며, 플러그인은 의존성 없이 로드됩니다. 각 경우는 다른 신호를 남깁니다:

294 301

295* 실패한 설치 또는 Yarn 또는 pnpm 잠금 파일 또는 `bunfig.toml` 때문에 건너뛴 설치는 `claude --debug` 출력에 경고로 나타납니다302* 실패한 설치, 또는 잠금 파일이나 [설치의 제한](#limits-on-the-dependency-install) 중 하나 때문에 건너뛴 설치는 `claude --debug` 출력에 이유를 명시하는 `Plugin dependency install warning` 줄로 나타납니다

296* `package.json`이 있고 잠금 파일이 없는 플러그인은 로그 항목 없이 건너뜁니다303* `package.json`이 있고 잠금 파일이 없는 플러그인은 로그 항목 없이 건너뜁니다

297* 시간 초과된 설치는 캐시된 복사본에 부분 `node_modules` 트리를 남길 수 있습니다

298 304

299자동 설치가 종속성을 제공할 수 없을 때 [영구 데이터 디렉토리](/docs/ko/plugins/components#path-variables-and-persistent-data)로 훅에서 설치합니다. 여기에는 라이프사이클 스크립트를 빌드해야 하는 패키지, Python 종속성, Yarn 또는 pnpm으로 잠긴 플러그인이 포함됩니다.305자동 설치가 의존성을 제공할 수 없을 때 [영구 데이터 디렉토리](/docs/ko/plugins/components#path-variables-and-persistent-data)로 훅에서 설치합니다. 여기에는 빌드를 위해 라이프사이클 스크립트가 필요한 패키지, Python 의존성, Yarn 또는 pnpm으로 잠긴 플러그인, 그리고 git 의존성과 같이 레지스트리 패키지가 아닌 의존성이 포함됩니다.

300 306

301<h2 id="versions-and-updates">307<h2 id="versions-and-updates">

302 버전 및 업데이트308 버전 및 업데이트

plugins/marketplace-reference.md +11 −3

Details

156| `url` | `url`, `ref`, `sha` | URL로 지정된 모든 git 저장소 |156| `url` | `url`, `ref`, `sha` | URL로 지정된 모든 git 저장소 |

158| `npm` | `package`, `version`, `registry` | npm 패키지로, npm 클라이언트로 가져오고 설치 스크립트를 실행하지 않고 압축을 풉니다 |158| `npm` | `package`, `version`, `registry` | npm 레지스트리 패키지 또는 tarball 링크로, npm 클라이언트로 가져오고 설치 스크립트를 실행하지 않고 압축을 풉니다 |

161 161

258 258

259`npm` 소스는 다음 필드를 사용합니다:259`npm` 소스는 다음 필드를 사용합니다:

260 260

261* `package`: 패키지 이름 또는 `@your-org/formatter`와 같은 스코프된 이름261* `package`: `@your-org/formatter`와 같은 레지스트리 패키지 이름, `@your-org/formatter@2.0.0`과 같이 버전이 추가된 이름, 또는 패키지의 tarball 파일에 대한 `https` 링크

262* `version`: 버전 또는 범위262* `version`: 버전, semver 범위 또는 dist-tag로, `package`가 버전이 추가되지 않은 패키지 이름일 때 사용됩니다. 생략하면 `latest`를 가져옵니다

263* `registry`: 기본 레지스트리에 없는 패키지의 레지스트리 URL263* `registry`: 기본 레지스트리에 없는 패키지의 레지스트리 URL

264 264

265Claude Code는 npm 클라이언트로 패키지를 가져옵니다. 패키지의 설치 스크립트(예: `preinstall` 또는 `postinstall`)는 절대 실행되지 않으며, 해당 종속성은 가져오기 중에 설치되지 않습니다. 패키지의 `package.json` 옆에 지원되는 lockfile이 있으면 Claude Code는 스크립트도 비활성화된 상태에서 별도의 단계에서 해당 [Node.js 패키지 종속성](/docs/ko/plugins/loading#node-js-package-dependencies)을 설치합니다.265Claude Code는 npm 클라이언트로 패키지를 가져옵니다. 패키지의 설치 스크립트(예: `preinstall` 또는 `postinstall`)는 절대 실행되지 않으며, 해당 종속성은 가져오기 중에 설치되지 않습니다. 패키지의 `package.json` 옆에 지원되는 lockfile이 있으면 Claude Code는 스크립트도 비활성화된 상태에서 별도의 단계에서 해당 [Node.js 패키지 종속성](/docs/ko/plugins/loading#node-js-package-dependencies)을 설치합니다.

266 266

267Claude Code는 무엇이든 가져오기 전에 `package` 값을 확인합니다. 거부된 값은 해당 값과 이유를 명시하는 메시지와 함께 설치를 실패시킵니다. 거부되는 값은 다음과 같습니다:

268

269* **git 주소, 폴더 또는 `file:` 경로, `npm:` 별칭**: git 저장소에는 [`github`, `url` 또는 `git-subdir` 소스](#plugin-sources)를, 마켓플레이스 내의 폴더에는 상대 경로를, 별칭에는 패키지 자체의 이름을 사용합니다

270* **github.com, gist.github.com, gitlab.com, bitbucket.org 또는 git.sr.ht의 tarball 링크**: 링크가 GitHub 릴리스 다운로드인 경우에도 거부되며, `gitlab.com/api/v4/` 아래의 GitLab npm 레지스트리 링크인 경우는 예외입니다

271* **`http`를 통한 tarball 링크**: 설치하는 사용자 자신의 기본 npm 레지스트리를 가리키지 않는 한 거부됩니다

272

273`registry` URL은 설치하는 사용자 자신의 기본 npm 레지스트리가 아닌 한 `https`를 사용해야 합니다. 그 외의 `http` 레지스트리를 사용하면 npm이 레지스트리에 접속하기 전에 설치가 실패합니다.

274

267```json theme={null}275```json theme={null}

268{276{

269 "name": "formatter",277 "name": "formatter",

plugins/mods/admin.md +51 −0

Details

167 167

168mod가 로드되지 않은 사용자는 디버그 로그에서 이유를 찾습니다. [거부 메시지](/docs/ko/plugins/mods/troubleshoot#refusal-messages)는 `allowManagedHooksOnly` 및 `disableAllHooks`의 줄을 나열하고 [기본 제공 가드의 메시지](/docs/ko/plugins/mods/troubleshoot#messages-from-the-built-in-guard)는 `allowManagedModsOnly`의 줄을 가집니다.168mod가 로드되지 않은 사용자는 디버그 로그에서 이유를 찾습니다. [거부 메시지](/docs/ko/plugins/mods/troubleshoot#refusal-messages)는 `allowManagedHooksOnly` 및 `disableAllHooks`의 줄을 나열하고 [기본 제공 가드의 메시지](/docs/ko/plugins/mods/troubleshoot#messages-from-the-built-in-guard)는 `allowManagedModsOnly`의 줄을 가집니다.

169 169

170<h3 id="allow-only-your-organization’s-mods">

171 조직의 mod만 허용

172</h3>

173

174조직의 mod를 실행하고 사용자가 가져오는 mod를 차단하려면 [정책 표](#choose-how-much-to-allow)의 **조직의 mod만** 행에 있는 설정과 함께 `disableSideloadFlags`를 배포합니다. 다음의 완전한 `managed-settings.json`을 사용하면 Claude Code가 사용자의 자체 mod를 거부하므로 해당 훅은 전혀 실행되지 않으며, 정책 mod가 다른 mod보다 먼저 실행됩니다:

175

176```json managed-settings.json theme={null}

177{

178 "extraKnownMarketplaces": {

179 "acme-tools": {

180 "source": { "source": "directory", "path": "/opt/acme/claude-plugins" }

181 }

182 },

183 "enabledPlugins": { "acme-guard@acme-tools": true },

184 "prependPlugins": ["acme-guard@acme-tools", "sec-default@builtin"],

185 "pluginConfigs": {

186 "cc-plugin-sec-default@builtin": {

187 "options": { "allowManagedModsOnly": true }

188 }

189 },

190 "disableSideloadFlags": true

191}

192```

193

194각 키 그룹은 한 가지 작업을 수행합니다:

195

196* **`extraKnownMarketplaces`, `enabledPlugins`, `prependPlugins`**: mod를 조직의 것으로 간주되도록 설치하고, 가드를 그 뒤에 두어 해당 mod를 먼저 실행합니다. [조직의 mod 설치 및 순서 설정](#install-your-organizations-mods)에서 이 키들이 가리키는 디렉터리를 다룹니다.

197* **`pluginConfigs`**: 가드의 `allowManagedModsOnly` 옵션을 설정하여 Claude Code가 사용자의 자체 mod를 거부하도록 합니다. 사용자의 설정 훅, 상태줄, `/goal`은 계속 작동합니다.

198* **`disableSideloadFlags`**: 시작 시 거부하는 플래그는 [`disableSideloadFlags`](/docs/ko/settings-reference#disablesideloadflags)를 참조하세요

199

200테스트 머신에서 정책을 확인하려면 셸에서 `claude --debug`로 세션을 시작하고 디버그 로그를 읽습니다:

201

202* **자신의 mod**: 해당 `hooks module` 줄에 `tier prepend`가 있습니다

203* **사용자가 설치한 mod**: `refused by cc-plugin-sec-default: mods are limited to your organization's by policy (allowManagedModsOnly)`라는 줄이 있습니다. 그보다 앞선 줄에는 해당 mod의 hooks module이 `loaded`되었다고 나오므로 거부 줄을 찾아야 합니다.

204* **플러그인 디렉터리**: `claude --plugin-dir ./any-mod`는 `--plugin-dir is disabled by your organization's managed settings (disableSideloadFlags)`로 시작하는 메시지와 함께 종료됩니다

205

206사용자가 추가할 수 있는 마켓플레이스도 제한하려면 이 파일을 [마켓플레이스 제한](/docs/ko/plugins/org#restrict-what-users-can-install)과 결합하세요.

207

208<h3 id="apply-your-plugin-controls-to-mods">

209 플러그인 제어를 mod에 적용

210</h3>

211

212mod는 플러그인이므로 [조직의 플러그인을 관리](/docs/ko/plugins/org)하는 방법은 mod를 포함하는 플러그인에도 적용됩니다:

213

214* **전체 머신에서 어떤 플러그인이 로드되는지 확인**: [감사 및 검토](/docs/ko/plugins/org#audit-and-review)

215* **검토한 플러그인을 업데이트할 수 있는 시점 결정**: [업데이트 정책 설정](/docs/ko/plugins/org#set-update-policy)

216* **파일럿 등 한 그룹에 다른 정책 적용**: [관리형 설정으로 강제할 수 없는 부분에 대한 계획](/docs/ko/plugins/org#plan-for-what-managed-settings-can’t-enforce)

217* **어떤 앱과 세션 종류가 플러그인 키를 적용하는지 확인**: [각 사용 환경이 플러그인 키를 적용하는 시점](/docs/ko/plugins/org#when-each-surface-applies-the-plugin-keys)

218* **CI 및 컨테이너 설정**: [컨테이너 및 CI 시드](/docs/ko/plugins/org#seed-containers-and-ci)

219* **사용자가 설치할 수 있는 mod 제공**: [마켓플레이스 호스팅](/docs/ko/plugins/host-marketplace). Claude Code가 GitHub, git, URL 또는 npm 소스에서 복사하는 mod는 [조직의 것](#install-your-organizations-mods)이 아니라 사용자의 것으로 간주됩니다.

220

170<h3 id="set-options-on-the-built-in-guard">221<h3 id="set-options-on-the-built-in-guard">

171 기본 제공 가드에서 옵션 설정222 기본 제공 가드에서 옵션 설정

172</h3>223</h3>

plugins/mods/events.md +28 −1

Details

190 190

191`$.ui.ask`와 같은 mods API 호출 내에서 대기를 유지하세요. 이 시간은 훅의 [10초 시간 제한](/docs/ko/plugins/mods/reference#limits)에 포함되지 않기 때문입니다. 자신의 약속을 기다리는 데 소비된 시간은 포함됩니다. Claude Code는 시간 초과된 훅을 건너뛰므로 보류된 명령이 실행됩니다.191`$.ui.ask`와 같은 mods API 호출 내에서 대기를 유지하세요. 이 시간은 훅의 [10초 시간 제한](/docs/ko/plugins/mods/reference#limits)에 포함되지 않기 때문입니다. 자신의 약속을 기다리는 데 소비된 시간은 포함됩니다. Claude Code는 시간 초과된 훅을 건너뛰므로 보류된 명령이 실행됩니다.

192 192

193<h4 id="approve-or-refuse-a-tool-call-before-the-user-is-asked">

194 사용자에게 묻기 전에 도구 호출 승인 또는 거부하기

195</h4>

196

197도구 호출의 실행 가능 여부를 결정하려면 Claude Code가 그 결정을 내리는 이벤트인 [`tool.check`](/docs/ko/plugins/mods/reference#tools)를 처리합니다. 이 이벤트는 권한 규칙과 설정 훅이 결정한 후에 발생하며, `next(e)`는 그 결정인 `allow`, `ask`, 또는 `deny`로 해결됩니다. 훅은 그 결정이나 다른 결정을 반환합니다. `e.input`에는 도구의 인수가 들어 있습니다. 예를 들어 Bash의 경우 `command`입니다.

198

199고정된 명령이나 경로에는 코드가 필요 없는 `Bash(npm test)`와 같은 [권한 규칙](/docs/ko/permissions#permission-rule-syntax)을 사용합니다. 현재 Git 브랜치나 다른 훅이 기록한 값처럼 그 시점의 상태에 따라 결정이 달라지는 경우 `tool.check`를 처리합니다.

200

201이 훅은 현재 브랜치가 `main`인 동안 `git push`를 거부합니다:

202

203```javascript theme={null}

204on('tool.check', { tool: 'Bash' }, async ($, e, next) => {

205 // 권한 규칙과 설정 훅이 결정한 것: 'allow', 'ask', 또는 'deny'

206 const decided = await next(e)

207 if (!e.input.command.includes('git push')) return decided

208 const branch = await $.process.run(['git', 'branch', '--show-current'])

209 if (branch.stdout.trim() !== 'main') return decided

210 return { decision: 'deny', reason: 'Push from a branch other than main' }

211})

212```

213

214`main`에서는 규칙이 `git push`를 허용하더라도 훅이 `deny`를 반환합니다. 다른 브랜치에서, 그리고 다른 명령의 경우 호출은 모드 없이 받았을 결정을 그대로 받습니다.

215

216훅은 명령의 텍스트와 일치 여부를 확인하므로 Claude를 위한 알림으로 취급하세요. 모든 사람에 대해 `main`으로의 푸시를 차단하려면 Git 호스트에서 브랜치를 보호하세요.

217

218훅은 세 가지 결정 중 어떤 것이든 반환할 수 있으므로 관리형 설정 외부의 `PreToolUse` 훅이 차단한 호출을 승인할 수도 있습니다. [훅으로 권한 확장하기](/docs/ko/permissions#extend-permissions-with-hooks)에 어떤 결정이 모드보다 우선하는지 나와 있습니다.

219

193<h3 id="rewrite-or-add-to-a-prompt">220<h3 id="rewrite-or-add-to-a-prompt">

194 프롬프트 재작성 또는 추가하기221 프롬프트 재작성 또는 추가하기

195</h3>222</h3>

301* **관리되는 설정의 `PreToolUse` 후킹**: 첫 번째 모드의 `tool.call` 후킹 전에 실행되며, 그 중 하나의 차단은 최종적이므로 모드가 호출을 보지 못합니다.328* **관리되는 설정의 `PreToolUse` 후킹**: 첫 번째 모드의 `tool.call` 후킹 전에 실행되며, 그 중 하나의 차단은 최종적이므로 모드가 호출을 보지 못합니다.

302* **다른 모든 설정 파일 및 플러그인의 `hooks/hooks.json`의 `PreToolUse` 후킹**: 마지막 모드가 `next`를 호출한 후, Claude Code의 자체 동작의 일부로 실행됩니다. `next`를 호출하지 않고 `tool.call`에 응답하는 모드는 이들이 실행되는 것을 방지하고, `next`를 호출하는 모드는 반환하는 결과에서 이들의 결정을 봅니다.329* **다른 모든 설정 파일 및 플러그인의 `hooks/hooks.json`의 `PreToolUse` 후킹**: 마지막 모드가 `next`를 호출한 후, Claude Code의 자체 동작의 일부로 실행됩니다. `next`를 호출하지 않고 `tool.call`에 응답하는 모드는 이들이 실행되는 것을 방지하고, `next`를 호출하는 모드는 반환하는 결과에서 이들의 결정을 봅니다.

303 330

304[`tool.check`](/docs/ko/plugins/mods/reference#tools)는 Claude Code가 도구 호출 실행 여부를 결정하는 이벤트입니다. 이는 해당 후킹과 권한 규칙이 결정한 후에 발생하며, `next(e)`는 해당 결정으로 해석됩니다. `tool.check`의 후킹은 `{ decision: 'allow' }`와 같은 다른 결정을 반환할 수 있으므로, 두 번째 그룹의 후킹이 차단한 호출을 승인할 수 있습니다. [후킹으로 권한 확장](/docs/ko/permissions#extend-permissions-with-hooks)은 어떤 결정이 모드보다 우선하는지 나열합니다.331[`tool.check`](#approve-or-refuse-a-tool-call-before-the-user-is-asked)는 해당 훅과 권한 규칙이 결정한 후에 발생하므로, 이 이벤트의 훅은 두 번째 그룹의 훅이 차단한 호출을 승인할 수 있습니다.

305 332

306<h3 id="handle-a-hook-that-fails">333<h3 id="handle-a-hook-that-fails">

307 실패한 후킹 처리334 실패한 후킹 처리

plugins/mods/interface.md +2 −2

Details

407 ```407 ```

408 408

409 ```text theme={null}409 ```text theme={null}

410 Note: Type a note and press Enter ⏎ add410 Note: Type a note and press Enter

411 ```411 ```

412 </Tab>412 </Tab>

413</Tabs>413</Tabs>

414 414

415이 표는 모든 요소를 나열합니다:415[인터페이스 갤러리](/docs/ko/plugins/mods/gallery)에는 대부분의 요소에 대한 샘플과 스크린샷이 있습니다. 이 표는 모든 요소를 나열합니다:

416 416

417| 요소 | 무엇을 그리는가 | 어디서 |417| 요소 | 무엇을 그리는가 | 어디서 |

418| :- | :- | :- |418| :- | :- | :- |

plugins/mods/overview.md +4 −0

Details

72* **사용자에게 묻지 않고 작동**: 사용자에게 묻기 전에 도구 호출 승인72* **사용자에게 묻지 않고 작동**: 사용자에게 묻기 전에 도구 호출 승인

73* **사용량 소비**: 플랜 또는 API 키의 모델 호출73* **사용량 소비**: 플랜 또는 API 키의 모델 호출

74 74

75모드는 샌드박스 안에서 실행되지 않습니다. [샌드박싱](/docs/ko/sandboxing)을 켜면 샌드박스는 Claude가 실행하는 Bash 명령을 격리하지만, 모드가 시작하는 프로세스는 샌드박스 외부에서 실행됩니다.

75도구 호출을 승인하는 모드는 `ask` 규칙이 프롬프트하는 호출이나 사용자의 `PreToolUse` 훅이 차단한 호출을 승인할 수 있습니다. [훅으로 권한 확장하기](/docs/ko/permissions#extend-permissions-with-hooks)에서는 이러한 모드가 승인할 수 있는 것(예: `deny` 규칙이 거부하는 호출을 승인할 수 있는 경우 포함)을 나열합니다.77도구 호출을 승인하는 모드는 `ask` 규칙이 프롬프트하는 호출이나 사용자의 `PreToolUse` 훅이 차단한 호출을 승인할 수 있습니다. [훅으로 권한 확장하기](/docs/ko/permissions#extend-permissions-with-hooks)에서는 이러한 모드가 승인할 수 있는 것(예: `deny` 규칙이 거부하는 호출을 승인할 수 있는 경우 포함)을 나열합니다.

76 78

77모드는 Claude Code 인터페이스의 대부분을 다시 스타일링할 수 있지만, 권한 프롬프트는 변경할 수 없습니다. 프롬프트가 표시하는 내용을 변경할 수 없습니다.79모드는 Claude Code 인터페이스의 대부분을 다시 스타일링할 수 있지만, 권한 프롬프트는 변경할 수 없습니다. 프롬프트가 표시하는 내용을 변경할 수 없습니다.

102 104

103조직을 통해 Claude Code를 사용하면 관리자가 로드되는 mods를 제한할 수도 있습니다. 관리자는 [사용자 설치 mods가 로드되지 않도록 중지](/docs/ko/plugins/mods/admin#stop-user-installed-mods-from-loading)에서 시작합니다.105조직을 통해 Claude Code를 사용하면 관리자가 로드되는 mods를 제한할 수도 있습니다. 관리자는 [사용자 설치 mods가 로드되지 않도록 중지](/docs/ko/plugins/mods/admin#stop-user-installed-mods-from-loading)에서 시작합니다.

104 106

107`disableAllHooks`와 조직의 `allowManagedModsOnly`는 mod를 중지하되 해당 플러그인의 나머지 부분은 그대로 둡니다. 플러그인은 설치된 상태로 유지되며, 플러그인의 스킬, 명령, 에이전트, MCP 서버는 로드됩니다. 다른 설정과 플래그는 더 넓은 범위에 영향을 줍니다. [`disableAllHooks`](/docs/ko/settings-reference#disableallhooks) 및 [`allowManagedHooksOnly`에서 실행되는 항목](/docs/ko/settings-reference#what-runs-under-allowmanagedhooksonly)에서 각 설정이 플러그인과 해당 설정 훅에 어떤 영향을 주는지 확인할 수 있습니다.

108

105mods가 로드될 수 있는지 확인하려면 [mods가 로드될 수 있는지 확인](/docs/ko/plugins/mods/troubleshoot#check-whether-mods-can-load)을 참조합니다.109mods가 로드될 수 있는지 확인하려면 [mods가 로드될 수 있는지 확인](/docs/ko/plugins/mods/troubleshoot#check-whether-mods-can-load)을 참조합니다.

106 110

107<Note>111<Note>

plugins/mods/troubleshoot.md +2 −0

Details

56 56

57콜론 뒤의 이유를 읽습니다. [거부 메시지](#refusal-messages) 섹션에는 각각이 나열되어 있습니다. 로그에 그러한 줄이 없으면 이 그룹의 다른 항목을 통해 작업합니다.57콜론 뒤의 이유를 읽습니다. [거부 메시지](#refusal-messages) 섹션에는 각각이 나열되어 있습니다. 로그에 그러한 줄이 없으면 이 그룹의 다른 항목을 통해 작업합니다.

58 58

59일부 설정은 플러그인의 나머지 부분은 계속 작동하도록 두고 mod만 중지합니다. [mod 켜기 또는 끄기](/docs/ko/plugins/mods/overview#turn-mods-on-or-off)에 해당 설정이 나와 있습니다.

59<h3 id="a-claude-p-run-prints-hooks-module-not-loaded">61<h3 id="a-claude-p-run-prints-hooks-module-not-loaded">

60 `claude -p` 실행이 `hooks module not loaded` 인쇄62 `claude -p` 실행이 `hooks module not loaded` 인쇄

61</h3>63</h3>

plugins/security.md +1 −1

Details

37 37

38Claude Code의 [권한 규칙](/docs/ko/permissions) 및 [sandbox](/docs/ko/sandboxing)는 Claude가 수행하는 도구 호출을 다루며, 플러그인이 자체적으로 실행하는 코드는 다루지 않습니다:38Claude Code의 [권한 규칙](/docs/ko/permissions) 및 [sandbox](/docs/ko/sandboxing)는 Claude가 수행하는 도구 호출을 다루며, 플러그인이 자체적으로 실행하는 코드는 다루지 않습니다:

39 39

~~40* **Hooks 및 서버 프로세스**: 명령 hooks는 전체 사용자 권한으로 셸 명령을 실행합니다. Claude Code는 hooks 및 MCP 서버를 sandbox 외부에서 실행합니다.~~40* **Hooks 및 서버 프로세스**: 명령 hooks는 전체 사용자 권한으로 셸 명령을 실행합니다. Claude Code는 hooks, MCP 서버 및 [mod](/docs/ko/plugins/mods/overview#what-a-mod-can-reach)가 시작하는 프로세스를 샌드박스 외부에서 실행합니다.

41* **Claude의 도구 호출**: 플러그인의 MCP 도구 중 하나에 대한 호출 및 플러그인의 `bin/`에서 실행 파일을 실행하는 Bash 명령은 도구 호출이므로 권한 규칙이 적용됩니다. mod가 도구 호출에 수행할 수 있는 작업에 대해서는 [mod를 신뢰할지 결정하기](/docs/ko/plugins/mods/overview#decide-whether-to-trust-a-mod)를 참조하십시오.41* **Claude의 도구 호출**: 플러그인의 MCP 도구 중 하나에 대한 호출 및 플러그인의 `bin/`에서 실행 파일을 실행하는 Bash 명령은 도구 호출이므로 권한 규칙이 적용됩니다. mod가 도구 호출에 수행할 수 있는 작업에 대해서는 [mod를 신뢰할지 결정하기](/docs/ko/plugins/mods/overview#decide-whether-to-trust-a-mod)를 참조하십시오.

42 42

43플러그인을 설치하면 해당 매니페스트 또는 마켓플레이스 항목이 [`defaultEnabled: false`](/docs/ko/plugins/install#choose-an-install-scope)를 설정하고 사용자가 직접 활성화하지 않은 경우를 제외하고는 플러그인이 활성화됩니다.43플러그인을 설치하면 해당 매니페스트 또는 마켓플레이스 항목이 [`defaultEnabled: false`](/docs/ko/plugins/install#choose-an-install-scope)를 설정하고 사용자가 직접 활성화하지 않은 경우를 제외하고는 플러그인이 활성화됩니다.

plugins/troubleshooting.md +15 −0

Details

460* **플러그인을 게시하는 경우**: URL이 제공하는 정확한 파일의 다이제스트를 다시 계산하고 마켓플레이스 항목의 `sha256`을 업데이트합니다. `shasum -a 256 my-plugin.zip`을 사용하거나 PowerShell에서 `Get-FileHash -Algorithm SHA256 my-plugin.zip`을 사용합니다.460* **플러그인을 게시하는 경우**: URL이 제공하는 정확한 파일의 다이제스트를 다시 계산하고 마켓플레이스 항목의 `sha256`을 업데이트합니다. `shasum -a 256 my-plugin.zip`을 사용하거나 PowerShell에서 `Get-FileHash -Algorithm SHA256 my-plugin.zip`을 사용합니다.

461* **플러그인을 설치하는 경우**: 세션에서 `/plugin marketplace update <name>`을 실행하여 항목이 수정된 경우 카탈로그를 새로고침한 다음 설치를 다시 시도합니다. 새로고침 후에도 다이제스트가 계속 불일치하면 설치하기 전에 마켓플레이스 소유자에게 어떤 파일을 핀했는지 물어봅니다.461* **플러그인을 설치하는 경우**: 세션에서 `/plugin marketplace update <name>`을 실행하여 항목이 수정된 경우 카탈로그를 새로고침한 다음 설치를 다시 시도합니다. 새로고침 후에도 다이제스트가 계속 불일치하면 설치하기 전에 마켓플레이스 소유자에게 어떤 파일을 핀했는지 물어봅니다.

462 462

463<h3 id="an-npm-plugin-source-must-name-a-registry-package">

464 `An npm plugin source must name a registry package`

465</h3>

466

467마켓플레이스 항목이 [`npm` 소스](/docs/ko/plugins/marketplace-reference#npm-plugin-source)를 사용하는 플러그인이 설치, 업데이트 또는 로드에 실패했으며, 메시지에 이 문장이 포함되어 있습니다. Claude Code는 아무것도 가져오기 전에 항목의 `package` 값을 확인하고 거부했습니다. 메시지는 값과 이유를 지정합니다:

468

469```text theme={null}

470"github:acme/formatter" was not installed: it is not an http or https link. An npm plugin source must name a registry package (name or name@version) or link to a tarball file. For a plugin in a git repository, use a "github", "url" or "git-subdir" source.

471```

472

473마켓플레이스 소유자가 항목을 변경해야 합니다:

474

475* **본인이 소유자인 경우**: `package`를 [npm 플러그인 소스 참조](/docs/ko/plugins/marketplace-reference#npm-plugin-source)가 허용하는 값으로 변경하거나, 항목을 `github`, `url` 또는 `git-subdir` 소스로 전환합니다.

476* **본인이 소유자가 아닌 경우**: 메시지를 마켓플레이스 소유자에게 보고합니다.

477

463<h3 id="marketplace-is-registered-from-an-untrusted-source">478<h3 id="marketplace-is-registered-from-an-untrusted-source">

464 `Marketplace "<name>" is registered from an untrusted source`479 `Marketplace "<name>" is registered from an untrusted source`

465</h3>480</h3>

remote-control.md +1 −1

Details

220 220

221이 명령들은 서버가 중지된 후 약 4시간 동안 작동합니다. 그 후에는 `claude remote-control`을 실행하여 새 세션을 시작하세요. 그 사이에 세션을 보관했으면 `--continue` 및 `--session-id`는 Claude Code v2.1.228 이상에서 이를 보관 해제합니다.221이 명령들은 서버가 중지된 후 약 4시간 동안 작동합니다. 그 후에는 `claude remote-control`을 실행하여 새 세션을 시작하세요. 그 사이에 세션을 보관했으면 `--continue` 및 `--session-id`는 Claude Code v2.1.228 이상에서 이를 보관 해제합니다.

222 222

223`claude --remote-control` 또는 `/remote-control`로 시작한 세션을 다시 가져오려면 `claude --continue` 또는 `claude --resume`으로 대화를 재개하세요. Remote Control이 다시 연결되지 않으면 [Remote Control 세션에 다시 연결할 수 없음](#couldnt-reconnect-to-your-remote-control-session)을 참조하세요.223`claude --remote-control` 또는 `/remote-control`로 시작한 세션을 다시 가져오려면 `claude --continue` 또는 `claude --resume`으로 대화를 재개하세요. 재개된 대화가 시작되는 권한 모드는 [재개 시 권한 모드](/docs/ko/sessions#permission-mode-on-resume)를 참조하세요. Remote Control이 다시 연결되지 않으면 [Remote Control 세션에 다시 연결할 수 없음](#couldnt-reconnect-to-your-remote-control-session)을 참조하세요.

224 224

225첫 번째 터미널이 여전히 Remote Control이 켜져 있는 동안 두 번째 터미널에서 대화를 재개하면 Claude Code는 두 번째 터미널에 `Remote Control not started here` 알림을 인쇄하고 세션을 첫 번째에서 가져가는 대신 Remote Control을 끕니다. 두 번째 터미널에서 `/remote-control`을 실행하여 Remote Control을 이동하세요.225첫 번째 터미널이 여전히 Remote Control이 켜져 있는 동안 두 번째 터미널에서 대화를 재개하면 Claude Code는 두 번째 터미널에 `Remote Control not started here` 알림을 인쇄하고 세션을 첫 번째에서 가져가는 대신 Remote Control을 끕니다. 두 번째 터미널에서 `/remote-control`을 실행하여 Remote Control을 이동하세요.

226 226

sandbox-environments.md +3 −1

Details

107 107

108* 프로젝트 디렉터리.108* 프로젝트 디렉터리.

109* Claude Code의 구성 경로 `~/.claude` 및 `~/.claude.json`.109* Claude Code의 구성 경로 `~/.claude` 및 `~/.claude.json`.

110* `/tmp`, Claude Code가 런타임 파일을 작성하는 위치.110* Claude Code가 런타임 파일을 작성하는 디렉터리. [`CLAUDE_CODE_TMPDIR`](/docs/ko/env-vars)를 설정하지 않은 경우 해당 디렉터리는 다음과 같습니다:

111 * **Linux 및 WSL2**: `/tmp`

112 * **macOS**: `/private/tmp`. `/tmp`는 이 디렉터리에 대한 심볼릭 링크이며, Seatbelt는 확인된 경로를 검사합니다.

111 113

112세션에 필요한 네트워크 도메인을 허용하십시오:114세션에 필요한 네트워크 도메인을 허용하십시오:

113 115

sandboxing.md +2 −1

Details

801* **기본 제공 파일 도구**: Read, Edit 및 Write는 권한 시스템을 직접 사용하며 샌드박스를 통해 실행되지 않습니다. [권한](/docs/ko/permissions)을 참조합니다.801* **기본 제공 파일 도구**: Read, Edit 및 Write는 권한 시스템을 직접 사용하며 샌드박스를 통해 실행되지 않습니다. [권한](/docs/ko/permissions)을 참조합니다.

802* **컴퓨터 사용**: Claude가 앱을 열고 화면을 제어할 때 격리된 환경이 아닌 실제 데스크톱에서 실행됩니다. 앱별 권한 프롬프트가 각 애플리케이션을 제어합니다. [CLI의 컴퓨터 사용](/docs/ko/computer-use) 또는 [Desktop의 컴퓨터 사용](/docs/ko/desktop#let-claude-use-your-computer)을 참조합니다.802* **컴퓨터 사용**: Claude가 앱을 열고 화면을 제어할 때 격리된 환경이 아닌 실제 데스크톱에서 실행됩니다. 앱별 권한 프롬프트가 각 애플리케이션을 제어합니다. [CLI의 컴퓨터 사용](/docs/ko/computer-use) 또는 [Desktop의 컴퓨터 사용](/docs/ko/desktop#let-claude-use-your-computer)을 참조합니다.

803* **환경 변수**: 샌드박싱된 Bash 명령은 기본적으로 부모 프로세스 환경을 상속합니다. 여기에는 설정된 모든 자격 증명이 포함됩니다. [`sandbox.credentials`](#protect-credentials)를 사용하여 샌드박싱된 명령에 대한 특정 변수를 설정 해제하거나 마스크하거나 [`CLAUDE_CODE_SUBPROCESS_ENV_SCRUB`](/docs/ko/env-vars)를 설정하여 모든 하위 프로세스에서 자격 증명을 제거합니다.803* **환경 변수**: 샌드박싱된 Bash 명령은 기본적으로 부모 프로세스 환경을 상속합니다. 여기에는 설정된 모든 자격 증명이 포함됩니다. [`sandbox.credentials`](#protect-credentials)를 사용하여 샌드박싱된 명령에 대한 특정 변수를 설정 해제하거나 마스크하거나 [`CLAUDE_CODE_SUBPROCESS_ENV_SCRUB`](/docs/ko/env-vars)를 설정하여 모든 하위 프로세스에서 자격 증명을 제거합니다.

804* **하위 에이전트**: [하위 에이전트](/docs/ko/sub-agents)는 부모 세션과 동일한 프로세스에서 실행되며 동일한 샌드박스 구성을 사용합니다. 부모 세션에서 샌드박싱이 활성화되면 하위 에이전트 내의 Bash 명령이 샌드박싱됩니다.804* **서브에이전트**: [서브에이전트](/docs/ko/sub-agents)는 부모 세션과 동일한 프로세스에서 실행되며 동일한 샌드박스 구성을 사용합니다. 부모 세션에서 샌드박싱이 활성화되면 서브에이전트 내의 Bash 명령이 샌드박싱됩니다.

805* **모드**: [모드](/docs/ko/plugins/mods/overview)는 Claude Code 내에서 자체 코드를 실행하는 플러그인이며, 모드가 시작하는 프로세스는 샌드박스 외부에서 실행됩니다. [모드가 접근할 수 있는 범위](/docs/ko/plugins/mods/overview#what-a-mod-can-reach)를 참조합니다.

805 806

806<Warning>807<Warning>

807 효과적인 샌드박싱은 파일시스템 및 네트워크 격리 모두를 필요로 합니다. 네트워크 격리가 없으면 손상된 에이전트가 SSH 키와 같은 민감한 파일을 유출할 수 있습니다. 파일시스템 격리가 없으면 권한 있는 정책이나 [파일시스템 레이어 비활성화](#disable-filesystem-isolation)로 인해 손상된 에이전트가 시스템 리소스를 백도어하여 네트워크 액세스를 얻을 수 있습니다. 기본값을 확대할 때 `allowWrite` 경로, 광범위한 `allowedDomains` 항목 또는 `excludedCommands` 예외가 다른 쪽의 제한을 취소하지 않는지 확인합니다.808 효과적인 샌드박싱은 파일시스템 및 네트워크 격리 모두를 필요로 합니다. 네트워크 격리가 없으면 손상된 에이전트가 SSH 키와 같은 민감한 파일을 유출할 수 있습니다. 파일시스템 격리가 없으면 권한 있는 정책이나 [파일시스템 레이어 비활성화](#disable-filesystem-isolation)로 인해 손상된 에이전트가 시스템 리소스를 백도어하여 네트워크 액세스를 얻을 수 있습니다. 기본값을 확대할 때 `allowWrite` 경로, 광범위한 `allowedDomains` 항목 또는 `excludedCommands` 예외가 다른 쪽의 제한을 취소하지 않는지 확인합니다.

self-hosted-environments-configuration.md +17 −0

Details

61 61

62래퍼에서 파일 디스크립터 3을 닫거나 재사용하지 마세요. 자식의 stdout 및 stderr 리디렉션은 괜찮습니다.62래퍼에서 파일 디스크립터 3을 닫거나 재사용하지 마세요. 자식의 stdout 및 stderr 리디렉션은 괜찮습니다.

63 63

64<h3 id="pass-the-system-prompt-flags-through">

65 시스템 프롬프트 플래그 전달

66</h3>

68Anthropic의 제어 평면이 세션에 보내는 시스템 프롬프트와 추가 시스템 프롬프트는 인라인 텍스트가 아닌 파일 경로로 래퍼에 전달됩니다. 러너는 각 프롬프트를 세션의 구성 디렉토리인 `CLAUDE_CONFIG_DIR`의 파일에 작성하고, 래퍼가 받는 인수에 [`--system-prompt-file <path>` 또는 `--append-system-prompt-file <path>`](/docs/ko/cli-reference#system-prompt-flags)로 해당 경로를 전달합니다.

70Claude Code v2.1.281 이상의 러너는 프롬프트를 파일로 전달합니다. v2.1.281 이전에는 러너가 이를 `--system-prompt <text>` 및 `--append-system-prompt <text>`로 전달했습니다.

72래퍼 스크립트 또는 [`command` 훅](#command)에서 이러한 플래그를 다음과 같이 처리하세요:

74* **그대로 전달**: `exec "$CLAUDE_RUNNER_CLAUDE_BIN" "$@"`로 래퍼를 종료하면 파일 플래그가 다른 모든 인수와 함께 전달됩니다. 이를 제거하거나 다시 작성하지 마세요. 세션에서 프롬프트 파일 플래그가 누락되면 제어 평면이 해당 세션에 보낸 지침 없이 실행됩니다.

75* **v2.1.281 이상의 러너에서는 추가한 파일 플래그가 서버의 플래그에 더해지지 않고 이를 대체함**: 각 프롬프트 파일 플래그는 단일 값을 받으며 Claude Code는 마지막 항목을 유지하므로, `"$@"` 뒤에 `--append-system-prompt-file <path>`를 추가하면 해당 파일의 내용이 서버의 추가 지침을 대체합니다. 서버의 지침 위에 지침을 추가하려면 러너 이미지의 `CLAUDE.md`에 넣으세요. 러너는 이를 [모든 세션의 사용자 수준 구성에 시드](#how-each-session’s-config-is-assembled)합니다.

64<h3 id="provision-credentials-scoped-to-the-session-creator">77<h3 id="provision-credentials-scoped-to-the-session-creator">

65 세션 작성자로 범위가 지정된 자격증명 프로비저닝78 세션 작성자로 범위가 지정된 자격증명 프로비저닝

66</h3>79</h3>

445* **작성자**: 제어 평면은 세션별 또는 타사 입력이 아닌 자신의 배포의 고정 상수에서 스크립트를 채웁니다.458* **작성자**: 제어 평면은 세션별 또는 타사 입력이 아닌 자신의 배포의 고정 상수에서 스크립트를 채웁니다.

446* **여전히 이를 관리하는 것**: `--settings`를 통해 제공된 훅은 관리되는 계층이 아닌 일반 병합 훅 구성에 들어가므로 관리되는 설정이 여전히 적용됩니다. `disableAllHooks`는 이를 비활성화하며, [`allowManagedHooksOnly`](/docs/ko/settings-reference#allowmanagedhooksonly)가 로드된 상태로 유지하는 범주에 포함되지 않습니다.459* **여전히 이를 관리하는 것**: `--settings`를 통해 제공된 훅은 관리되는 계층이 아닌 일반 병합 훅 구성에 들어가므로 관리되는 설정이 여전히 적용됩니다. `disableAllHooks`는 이를 비활성화하며, [`allowManagedHooksOnly`](/docs/ko/settings-reference#allowmanagedhooksonly)가 로드된 상태로 유지하는 범주에 포함되지 않습니다.

447 460

461[Claude Tag](https://claude.com/docs/claude-tag/overview) 세션을 제외하면, 자체 호스팅 환경의 세션은 기본적으로 [자동 메모리](/docs/ko/memory#auto-memory)가 꺼진 상태로 실행됩니다. 여러 세션에 걸쳐 유지되어야 하는 지침에는 러너 이미지 또는 저장소의 `CLAUDE.md`를 사용하십시오.

462

463호스트의 `~/.claude/`에 대한 러너의 스냅샷에는 `projects/` 디렉토리가 포함되지 않습니다. 자동 메모리의 기본 스토리지 위치는 이 디렉토리 아래에 있습니다. 이곳에 메모리 파일을 넣더라도 러너는 이를 세션으로 시드하지 않으며, 해당 파일로 자동 메모리가 켜지지도 않습니다.

464

448<h3 id="repository-committed-permission-rules">465<h3 id="repository-committed-permission-rules">

449 저장소 커밋된 권한 규칙466 저장소 커밋된 권한 규칙

450</h3>467</h3>

settings-reference.md +61 −49

Details

1958* 명령 대체, 하위 셸, 또는 `if` 또는 `for`와 같은 제어 흐름 블록1958* 명령 대체, 하위 셸, 또는 `if` 또는 `for`와 같은 제어 흐름 블록

1959* `docker build . > build.log`와 같은 리다이렉션(파일 디스크립터를 중복하는 것 제외, `2>&1`처럼)1959* `docker build . > build.log`와 같은 리다이렉션(파일 디스크립터를 중복하는 것 제외, `2>&1`처럼)

1960* 변수에서 오는 명령 이름1960* 변수에서 오는 명령 이름

1961* 경로 인수가 절대 경로이거나, `~`로 시작하거나, `..` 세그먼트를 포함하는 `git clone`, `git init`, `git worktree add`, `git worktree move`, 또는 `git bundle create`

1961 1962

1962예를 들어, `cd build && docker compose up`은 `docker *` 항목 아래에서 샌드박스된 상태로 유지되며, `cd` 항목을 추가해도 변경되지 않습니다.1963예를 들어, `cd build && docker compose up`은 `docker *` 항목 아래에서 샌드박스된 상태로 유지되며, `cd` 항목을 추가해도 변경되지 않습니다. `git *` 항목 아래에서 `git clone <url> vendor/lib`는 샌드박스 외부에서 실행되지만, `git clone <url> ~/tools`는 샌드박스된 상태로 유지됩니다. 클론은 대상 경로가 가리키는 곳이 어디든 실행 파일일 수도 있는 파일 트리 전체를 씁니다.

1963 1964

1964제외된 명령은 여전히 일반 권한 흐름을 거칩니다. 제외는 편의 기능이지 보안 경계가 아닙니다. 도구가 특정 위치에만 쓰기를 필요로 할 때는 [`filesystem.allowWrite`](#sandbox-filesystem-allowwrite)를 선호하십시오. Claude Code는 세션이 로드하는 모든 설정 범위에서 항목을 병합하며, 이 목록에 대한 관리되는 전용 잠금이 없으므로, 관리되는 목록을 좁게 유지하십시오.1965제외된 명령은 여전히 일반 권한 흐름을 거칩니다. 제외는 편의 기능이지 보안 경계가 아닙니다. 도구가 특정 위치에만 쓰기를 필요로 할 때는 [`filesystem.allowWrite`](#sandbox-filesystem-allowwrite)를 선호하십시오. Claude Code는 세션이 로드하는 모든 설정 범위에서 항목을 병합하며, 이 목록에 대한 관리되는 전용 잠금이 없으므로, 관리되는 목록을 좁게 유지하십시오.

1965 1966

4261 훅과 자동화4262 훅과 자동화

4262</h2>4263</h2>

4263 4264

4264훅을 등록하고, 실행할 훅을 제한하며, 워크플로우를 제어합니다. 훅 이벤트 및 페이로드는 [훅 참조](/docs/ko/hooks)를 참조하십시오.4265훅을 등록하고, 실행할 훅을 제한하며, 워크플로를 제어합니다. 훅 이벤트 및 페이로드는 [훅 참조](/docs/ko/hooks)를 참조하십시오.

4265 4266

4266<h3 id="allowedhttphookurls">4267<h3 id="allowedhttphookurls">

4267 `allowedHttpHookUrls`4268 `allowedHttpHookUrls`

4281}4282}

4282```4283```

4283 4284

4284호스트명 일치는 대소문자를 구분하지 않으며 정규화된 도메인 이름을 표시하는 후행 점이 있는 `hooks.example.com.`을 DNS가 처리하는 방식과 동일하게 `hooks.example.com`으로 취급합니다. 허용 목록은 관리되는 설정을 포함한 모든 소스의 훅에 적용됩니다.4285호스트명 일치는 대소문자를 구분하지 않으며 정규화된 도메인 이름을 표시하는 후행 점이 있는 `hooks.example.com.`을 DNS가 처리하는 방식과 동일하게 `hooks.example.com`으로 취급합니다. 허용 목록은 관리형 설정을 포함한 모든 소스의 훅에 적용됩니다.

4285 4286

4286<h3 id="allowmanagedhooksonly">4287<h3 id="allowmanagedhooksonly">

4287 `allowManagedHooksOnly`4288 `allowManagedHooksOnly`

4291 4292

4292* **범위**: [`관리됨`](#scopes)4293* **범위**: [`관리됨`](#scopes)

4293* **유형**: 부울4294* **유형**: 부울

4294 * `true`: 관리되는 훅만 실행되며, Agent SDK 훅 및 관리되는 설정이 강제로 활성화하는 플러그인의 훅도 실행됩니다. [`allowManagedHooksOnly`에서 실행되는 항목](#what-runs-under-allowmanagedhooksonly)을 참조하십시오.4295 * `true`: 관리형 훅만 실행되며, Agent SDK 훅 및 관리형 설정이 강제로 활성화하는 플러그인의 훅도 실행됩니다. [`allowManagedHooksOnly`에서 실행되는 항목](#what-runs-under-allowmanagedhooksonly)을 참조하십시오.

4295 * `false`: 모든 설정 범위 및 플러그인의 훅이 실행됨4296 * `false`: 모든 설정 범위 및 플러그인의 훅이 실행됨

4296* **기본값**: 설정되지 않음, 따라서 모든 설정 범위 및 플러그인의 훅이 실행됨4297* **기본값**: 설정되지 않음, 따라서 모든 설정 범위 및 플러그인의 훅이 실행됨

4297 4298

4307 4308

4308이를 `true`로 설정하면 Claude Code는 로드되는 훅 및 훅과 유사한 명령을 변경합니다:4309이를 `true`로 설정하면 Claude Code는 로드되는 훅 및 훅과 유사한 명령을 변경합니다:

4309 4310

4310* **관리되는 훅 및 SDK 훅 실행**: 관리되는 설정의 훅 및 [Agent SDK](/docs/ko/agent-sdk/overview)가 프로세스에 등록하는 훅4311* **관리형 훅 및 SDK 훅 실행**: 관리형 설정의 훅 및 [Agent SDK](/docs/ko/agent-sdk/overview)가 프로세스에 등록하는 훅

4311* **강제 활성화된 플러그인 훅 실행**: 관리되는 설정이 [`enabledPlugins`](#enabledplugins)를 통해 강제로 활성화하는 플러그인의 훅. Claude Code는 전체 `plugin@marketplace` ID와 일치하므로 다른 마켓플레이스의 동일한 이름의 플러그인은 차단된 상태로 유지됩니다. 이를 통해 조직 마켓플레이스를 통해 검증된 훅을 배포하면서 다른 모든 것을 차단할 수 있습니다. 이러한 플러그인의 [mod](/docs/ko/plugins/mods/overview)는 [조직의 것으로 계산될 때](/docs/ko/plugins/mods/admin#install-your-organizations-mods)만 로드됩니다.4312* **강제 활성화된 플러그인 훅 실행**: 관리형 설정이 [`enabledPlugins`](#enabledplugins)를 통해 강제로 활성화하는 플러그인의 훅. Claude Code는 전체 `plugin@marketplace` ID와 일치하므로 다른 마켓플레이스의 동일한 이름의 플러그인은 차단된 상태로 유지됩니다. 이를 통해 조직 마켓플레이스를 통해 검증된 훅을 배포하면서 다른 모든 것을 차단할 수 있습니다. 이러한 플러그인의 [mod](/docs/ko/plugins/mods/overview)는 [조직의 것으로 계산될 때](/docs/ko/plugins/mods/admin#install-your-organizations-mods)만 로드됩니다.

4312* **다른 모든 것은 차단됨**: 사용자, 프로젝트 및 로컬 훅, 다른 설치된 플러그인의 훅 및 mod, 에이전트 프론트매터에 선언된 훅. [Claude Code에 내장된 mod](/docs/ko/plugins/mods/overview#mods-built-into-claude-code)는 계속 실행됩니다. 사용자의 mod만 차단하려면 [`allowManagedModsOnly`](/docs/ko/plugins/mods/admin#set-options-on-the-built-in-guard)를 대신 설정합니다.4313* **다른 모든 것은 차단됨**: 사용자, 프로젝트 및 로컬 훅, 다른 설치된 플러그인의 훅 및 mod, 에이전트 frontmatter에 선언된 훅. [Claude Code에 내장된 mod](/docs/ko/plugins/mods/overview#mods-built-into-claude-code)는 계속 실행됩니다. 사용자의 mod만 차단하려면 [`allowManagedModsOnly`](/docs/ko/plugins/mods/admin#set-options-on-the-built-in-guard)를 대신 설정합니다.

4313* **명령 소스 플러그인 비활성화**: Claude Code는 또한 [`disableCommandPluginSources`](#disablecommandpluginsources)를 명시적으로 `false`로 설정하지 않는 한 [`command` 소스](/docs/ko/plugins/marketplace-reference#command-plugin-source)가 있는 플러그인(관리되는 `enabledPlugins`에서 강제로 활성화된 플러그인 포함)을 비활성화합니다.4314* **명령 소스 플러그인 비활성화**: Claude Code는 또한 [`disableCommandPluginSources`](#disablecommandpluginsources)를 명시적으로 `false`로 설정하지 않는 한 [`command` 소스](/docs/ko/plugins/marketplace-reference#command-plugin-source)가 있는 플러그인(관리형 `enabledPlugins`에서 강제로 활성화된 플러그인 포함)을 비활성화합니다.

4314* **마켓플레이스 `headersHelper` 명령 차단**: Claude Code는 또한 [`disableCommandPluginSources`](#disablecommandpluginsources)가 명시적으로 `false`로 설정되지 않는 한 마켓플레이스 [`headersHelper` 명령](/docs/ko/plugins/host-marketplace#authenticate-archive-downloads)을 차단합니다. 단, 관리되는 설정 자체가 선언하는 마켓플레이스는 제외됩니다. Claude Code v2.1.238 이상이 필요합니다.4315* **마켓플레이스 `headersHelper` 명령 차단**: Claude Code는 또한 [`disableCommandPluginSources`](#disablecommandpluginsources)가 명시적으로 `false`로 설정되지 않는 한 마켓플레이스 [`headersHelper` 명령](/docs/ko/plugins/host-marketplace#authenticate-archive-downloads)을 차단합니다. 단, 관리형 설정 자체가 선언하는 마켓플레이스는 제외됩니다. Claude Code v2.1.238 이상이 필요합니다.

4315* **상태 줄 및 파일 제안이 관리되는 설정으로 좁혀짐**: Claude Code는 [상태 줄 및 파일 제안 게이트](#status-line-and-file-suggestion-gates)를 따르면서 관리되는 설정에서만 [`statusLine`](/docs/ko/statusline), [`fileSuggestion`](#filesuggestion), [`subagentStatusLine`](/docs/ko/statusline#subagent-status-lines)을 읽습니다.4316* **상태줄 및 파일 제안이 관리형 설정으로 좁혀짐**: Claude Code는 [상태줄 및 파일 제안 게이트](#status-line-and-file-suggestion-gates)를 따르면서 관리형 설정에서만 [`statusLine`](/docs/ko/statusline), [`fileSuggestion`](#filesuggestion), [`subagentStatusLine`](/docs/ko/statusline#subagent-status-lines)을 읽습니다.

4316 4317

4317[`/goal`](/docs/ko/goal) 명령은 이 키가 설정된 동안 실행할 수 없습니다. 훅에 따라 달라지기 때문입니다.4318[`/goal`](/docs/ko/goal) 명령은 이 키가 설정된 동안 실행할 수 없습니다. 훅에 따라 달라지기 때문입니다.

4318 4319

4320 `disableAllHooks`4321 `disableAllHooks`

4321</h3>4322</h3>

4322 4323

4323[훅](/docs/ko/hooks#disable-or-remove-hooks), 모든 사용자 정의 [상태 줄](/docs/ko/statusline), 모든 사용자 정의 [파일 제안](#filesuggestion) 명령을 끕니다. 설정에서 삭제하지 않고 이 모든 것을 일시적으로 끄는 데 사용합니다.4324[훅](/docs/ko/hooks#disable-or-remove-hooks), 모든 사용자 정의 [상태줄](/docs/ko/statusline), 모든 사용자 정의 [파일 제안](#filesuggestion) 명령을 끕니다. 설정에서 삭제하지 않고 이 모든 것을 일시적으로 끄는 데 사용합니다.

4324 4325

4325* **범위**: [`모든 파일`](#scopes). 관리되는 설정만 관리되는 훅을 비활성화할 수 있습니다.4326* **범위**: [`모든 파일`](#scopes). 관리형 설정만 관리형 훅을 비활성화할 수 있습니다.

4326* **유형**: 부울4327* **유형**: 부울

4327 * `true`: Claude Code는 훅, 모든 사용자 정의 상태 줄, 모든 사용자 정의 파일 제안 명령을 끕니다.4328 * `true`: Claude Code는 훅, 모든 사용자 정의 상태줄, 모든 사용자 정의 파일 제안 명령을 끕니다.

4328 * `false`: 훅, 상태 줄, 파일 제안 명령이 실행됨4329 * `false`: 훅, 상태줄, 파일 제안 명령이 실행됨

4329* **기본값**: 설정되지 않음, 따라서 훅이 실행됨4330* **기본값**: 설정되지 않음, 따라서 훅이 실행됨

4330 4331

4331```json settings.json theme={null}4332```json settings.json theme={null}

4336 4337

4337범위는 키를 포함하는 파일에 따라 달라집니다:4338범위는 키를 포함하는 파일에 따라 달라집니다:

4338 4339

4339* **관리되는 설정에서**: Claude Code는 관리되는 훅을 포함한 모든 구성된 훅을 비활성화하고 [Agent SDK](/docs/ko/agent-sdk/overview)가 프로세스에 등록하는 훅을 계속 실행합니다.4340* **관리형 설정에서**: Claude Code는 관리형 훅을 포함한 모든 구성된 훅을 비활성화하고 [Agent SDK](/docs/ko/agent-sdk/overview)가 프로세스에 등록하는 훅을 계속 실행합니다.

4340* **다른 설정 파일에서**: Claude Code는 사용자, 프로젝트, 로컬 및 플러그인 훅을 비활성화합니다. 관리되는 훅, Agent SDK 훅, 관리되는 [`enabledPlugins`](#enabledplugins)에서 강제로 활성화된 플러그인의 훅은 계속 실행됩니다.4341* **다른 설정 파일에서**: Claude Code는 사용자, 프로젝트, 로컬 및 플러그인 훅을 비활성화합니다. 관리형 훅, Agent SDK 훅, 관리형 [`enabledPlugins`](#enabledplugins)에서 강제로 활성화된 플러그인의 훅은 계속 실행됩니다.

4341 4342

4342관리되는 설정이 이 키를 설정할 때 Agent SDK 훅을 실행 상태로 유지하려면 Claude Code v2.1.242 이상이 필요합니다.4343이 키는 코드가 훅을 등록하는 플러그인인 [mod](/docs/ko/plugins/mods/overview)도 중지합니다:

4344

4345* **관리형 설정에서**: 조직의 mod를 포함하여 설치된 모든 플러그인의 mod가 중지됩니다.

4346* **다른 설정 파일에서**: 사용자가 설치한 mod는 중지되고, [조직의 mod](/docs/ko/plugins/mods/admin#install-your-organizations-mods)는 계속 실행됩니다.

4347

4348Claude Code에 내장된 mod는 두 경우 모두 계속 실행됩니다. 각 mod에는 [자체 스위치](/docs/ko/plugins/mods/overview#mods-built-into-claude-code)가 있습니다.

4349

4350관리형 설정이 이 키를 설정할 때 Agent SDK 훅을 실행 상태로 유지하려면 Claude Code v2.1.242 이상이 필요합니다.

4343 4351

4344[`/goal`](/docs/ko/goal) 명령은 훅이 비활성화된 동안 실행할 수 없으며, `/hooks` 메뉴는 훅 대신 공지를 표시합니다.4352[`/goal`](/docs/ko/goal) 명령은 훅이 비활성화된 동안 실행할 수 없으며, `/hooks` 메뉴는 훅 대신 공지를 표시합니다.

4345 4353

4346<h4 id="status-line-and-file-suggestion-gates">4354<h4 id="status-line-and-file-suggestion-gates">

4347 상태 줄 및 파일 제안 게이트4355 상태줄 및 파일 제안 게이트

4348</h4>4356</h4>

4349 4357

4350Claude Code는 `statusLine`, `fileSuggestion`, `subagentStatusLine`에 대해 다음 순서로 두 가지 결정을 내립니다:4358Claude Code는 `statusLine`, `fileSuggestion`, `subagentStatusLine`에 대해 다음 순서로 두 가지 결정을 내립니다:

4351 4359

4352* **완전히 끔**: 관리되는 설정이 `disableAllHooks`를 설정하거나, 폴더가 [설정 파일의 훅과 동일한 워크스페이스 신뢰 규칙](/docs/ko/permissions#what-runs-before-you-trust-a-folder) 아래에서 신뢰되지 않을 때4360* **완전히 끔**: 관리형 설정이 `disableAllHooks`를 설정하거나, 폴더가 [설정 파일의 훅과 동일한 워크스페이스 신뢰 규칙](/docs/ko/permissions#what-runs-before-you-trust-a-folder) 아래에서 신뢰되지 않을 때

4353* **관리되는 설정으로 좁혀짐**: [`allowManagedHooksOnly`](#allowmanagedhooksonly)가 설정되었을 때, `disableAllHooks`가 [설정 우선순위](/docs/ko/hooks#disable-or-remove-hooks)가 적용된 후 관리되는 설정 외부에서 `true`일 때, 또는 `--safe-mode`로 Claude Code를 시작할 때4361* **관리형 설정으로 좁혀짐**: [`allowManagedHooksOnly`](#allowmanagedhooksonly)가 설정되었을 때, `disableAllHooks`가 [설정 우선순위](/docs/ko/hooks#disable-or-remove-hooks)가 적용된 후 관리형 설정 외부에서 `true`일 때, 또는 `--safe-mode`로 Claude Code를 시작할 때

4354 4362

4355좁혀짐 상태에서 Claude Code는 배포된 관리되는 값이 있으면 실행합니다. 그렇지 않으면 경고 없이 값을 건너뜁니다: 상태 줄이 비활성화되고 `@` 자동 완성은 기본 제공 파일 제안으로 돌아갑니다.4363좁혀짐 상태에서 Claude Code는 배포된 관리형 값이 있으면 실행합니다. 그렇지 않으면 경고 없이 값을 건너뜁니다: 상태줄이 비활성화되고 `@` 자동 완성은 기본 제공 파일 제안으로 돌아갑니다.

4356 4364

4357<h3 id="disableworkflows">4365<h3 id="disableworkflows">

4358 `disableWorkflows`4366 `disableWorkflows`

4359</h3>4367</h3>

4360 4368

4361[동적 워크플로우](/docs/ko/workflows#turn-workflows-off)와 관리되는 설정을 통한 조직과 같이 설정이 도달하는 모든 사람을 위한 번들 워크플로우 명령을 끕니다. 자신을 위해서만 워크플로우를 켜거나 끄려면 [`enableWorkflows`](#enableworkflows)를 대신 사용하십시오. `/config`의 **동적 워크플로우** 토글이 사용자 설정에 기록합니다.4369[동적 워크플로](/docs/ko/workflows#turn-workflows-off)와 관리형 설정을 통한 조직과 같이 설정이 도달하는 모든 사람을 위한 번들 워크플로 명령을 끕니다. 자신을 위해서만 워크플로를 켜거나 끄려면 [`enableWorkflows`](#enableworkflows)를 대신 사용하십시오. `/config`의 **동적 워크플로** 토글이 사용자 설정에 기록합니다.

4362 4370

4363* **범위**: [`모든 파일`](#scopes)4371* **범위**: [`모든 파일`](#scopes)

4364* **유형**: 부울4372* **유형**: 부울

4365 * `true`: Claude Code는 설정이 도달하는 모든 사람을 위해 동적 워크플로우와 번들 워크플로우 명령을 끕니다.4373 * `true`: Claude Code는 설정이 도달하는 모든 사람을 위해 동적 워크플로와 번들 워크플로 명령을 끕니다.

4366 * `false`: 설정되지 않은 것과 동일합니다. 워크플로우가 켜져 있는지 여부는 [`enableWorkflows`](#enableworkflows)와 계획의 기본값을 따릅니다.4374 * `false`: 설정되지 않은 것과 동일합니다. 워크플로가 켜져 있는지 여부는 [`enableWorkflows`](#enableworkflows)와 계획의 기본값을 따릅니다.

4367* **기본값**: `false`4375* **기본값**: `false`

4368* **세션별 재정의**: [`CLAUDE_CODE_DISABLE_WORKFLOWS`](/docs/ko/env-vars)는 한 세션 동안 워크플로우를 끕니다. 둘 중 하나가 워크플로우를 끄면 다른 하나는 다시 켤 수 없습니다.4376* **세션별 재정의**: [`CLAUDE_CODE_DISABLE_WORKFLOWS`](/docs/ko/env-vars)는 한 세션 동안 워크플로를 끕니다. 둘 중 하나가 워크플로를 끄면 다른 하나는 다시 켤 수 없습니다.

4369 4377

4370```json settings.json theme={null}4378```json settings.json theme={null}

4371{4379{

4377 `enableWorkflows`4385 `enableWorkflows`

4378</h3>4386</h3>

4379 4387

4380계획의 기본값이 원하는 것이 아닐 때 자신을 위해 [동적 워크플로우](/docs/ko/workflows)를 켜거나 끕니다. `/config`에 **동적 워크플로우**로 나타나며, 이는 이 키를 사용자 설정에 기록하고 계획의 기본값으로 다시 토글할 때 제거합니다. 관리되는 설정에서 모든 사람을 위해 워크플로우를 끄려면 [`disableWorkflows`](#disableworkflows)를 대신 사용하십시오.4388계획의 기본값이 원하는 것이 아닐 때 자신을 위해 [동적 워크플로](/docs/ko/workflows)를 켜거나 끕니다. `/config`에 **동적 워크플로**로 나타나며, 이는 이 키를 사용자 설정에 기록하고 계획의 기본값으로 다시 토글할 때 제거합니다. 관리형 설정에서 모든 사람을 위해 워크플로를 끄려면 [`disableWorkflows`](#disableworkflows)를 대신 사용하십시오.

4381 4389

4382* **범위**: [`모든 파일`](#scopes)4390* **범위**: [`모든 파일`](#scopes)

4383* **유형**: 부울4391* **유형**: 부울

4384 * `true`: Claude Code는 자신을 위해 동적 워크플로우를 켭니다.4392 * `true`: Claude Code는 자신을 위해 동적 워크플로를 켭니다.

4385 * `false`: Claude Code는 자신을 위해 동적 워크플로우를 끕니다.4393 * `false`: Claude Code는 자신을 위해 동적 워크플로를 끕니다.

4386* **기본값**: 설정되지 않음, 따라서 워크플로우는 켜져 있습니다. Pro 계획에서는 꺼져 있습니다.4394* **기본값**: 설정되지 않음, 따라서 워크플로는 켜져 있습니다. Pro 계획에서는 꺼져 있습니다.

4387* **세션별 재정의**: [`CLAUDE_CODE_DISABLE_WORKFLOWS`](/docs/ko/env-vars)는 한 세션 동안 워크플로우를 끕니다. `true`는 설정된 동안 워크플로우를 다시 켤 수 없습니다.4395* **세션별 재정의**: [`CLAUDE_CODE_DISABLE_WORKFLOWS`](/docs/ko/env-vars)는 한 세션 동안 워크플로를 끕니다. `true`는 설정된 동안 워크플로를 다시 켤 수 없습니다.

4388 4396

4389```json settings.json theme={null}4397```json settings.json theme={null}

4390{4398{

4392}4400}

4393```4401```

4394 4402

4395[`disableWorkflows`](#disableworkflows)와 조직의 워크플로우 정책도 우선순위를 가집니다: `enableWorkflows: true`는 어떤 소스가 워크플로우를 끄는 동안 워크플로우를 다시 켤 수 없습니다. Claude Code는 사용자 설정 이외의 소스가 `enableWorkflows`를 설정하거나 `disableWorkflows`를 `true`로 설정하는 동안 `/config` 행을 숨깁니다.4403[`disableWorkflows`](#disableworkflows)와 조직의 워크플로 정책도 우선순위를 가집니다: `enableWorkflows: true`는 어떤 소스가 워크플로를 끄는 동안 워크플로를 다시 켤 수 없습니다. Claude Code는 사용자 설정 이외의 소스가 `enableWorkflows`를 설정하거나 `disableWorkflows`를 `true`로 설정하는 동안 `/config` 행을 숨깁니다.

4396 4404

4397<h3 id="hooks">4405<h3 id="hooks">

4398 `hooks`4406 `hooks`

4400 4408

4401Claude Code의 수명 주기의 특정 지점(예: 도구 호출 전 또는 세션 시작 시)에서 [훅](/docs/ko/hooks)으로 자신의 명령, 프롬프트, 에이전트, HTTP 요청 또는 MCP 도구를 실행합니다. [훅 참조](/docs/ko/hooks#hook-events)는 모든 이벤트, 페이로드 및 종료 코드를 나열합니다. 각 이벤트는 매처 그룹 목록에 매핑되고, 각 그룹은 매처가 적용될 때 실행할 핸들러를 나열합니다.4409Claude Code의 수명 주기의 특정 지점(예: 도구 호출 전 또는 세션 시작 시)에서 [훅](/docs/ko/hooks)으로 자신의 명령, 프롬프트, 에이전트, HTTP 요청 또는 MCP 도구를 실행합니다. [훅 참조](/docs/ko/hooks#hook-events)는 모든 이벤트, 페이로드 및 종료 코드를 나열합니다. 각 이벤트는 매처 그룹 목록에 매핑되고, 각 그룹은 매처가 적용될 때 실행할 핸들러를 나열합니다.

4402 4410

4403* **범위**: [`모든 파일`](#scopes). 훅은 서로 대체하지 않고 파일 전체에서 병합되며, 관리되는 설정의 훅은 다른 파일에서 제거할 수 없습니다.4411* **범위**: [`모든 파일`](#scopes). 훅은 서로 대체하지 않고 파일 전체에서 병합되며, 관리형 설정의 훅은 다른 파일에서 제거할 수 없습니다.

4404* **유형**: [훅 이벤트](/docs/ko/hooks#hook-events)로 키가 지정된 객체. 각 값은 `"command"`, `"prompt"`, `"agent"`, `"http"` 또는 `"mcp_tool"`의 `type`을 가진 `hooks` 항목이 있는 `{ "matcher", "hooks" }` 그룹의 배열입니다.4412* **유형**: [훅 이벤트](/docs/ko/hooks#hook-events)로 키가 지정된 객체. 각 값은 `"command"`, `"prompt"`, `"agent"`, `"http"` 또는 `"mcp_tool"`의 `type`을 가진 `hooks` 항목이 있는 `{ "matcher", "hooks" }` 그룹의 배열입니다.

4405* **기본값**: 설정되지 않음, 따라서 훅이 실행되지 않음4413* **기본값**: 설정되지 않음, 따라서 훅이 실행되지 않음

4406 4414

4441}4449}

4442```4450```

4443 4451

4444허용 목록은 관리되는 설정을 포함한 모든 소스의 훅에 적용됩니다.4452허용 목록은 관리형 설정을 포함한 모든 소스의 훅에 적용됩니다.

4445 4453

4446<h3 id="workflowkeywordtriggerenabled">4454<h3 id="workflowkeywordtriggerenabled">

4447 `workflowKeywordTriggerEnabled`4455 `workflowKeywordTriggerEnabled`

4448</h3>4456</h3>

4449 4457

4450프롬프트에서 키워드 `ultracode`를 입력하면 [동적 워크플로우](/docs/ko/workflows#ask-for-a-workflow-in-your-prompt)가 트리거되는지 선택합니다. 단어를 입력하지 않고 입력하려면 `false`로 설정합니다.4458프롬프트에서 키워드 `ultracode`를 입력하면 [동적 워크플로](/docs/ko/workflows#ask-for-a-workflow-in-your-prompt)가 트리거되는지 선택합니다. 워크플로를 트리거하지 않고 이 단어를 입력하려면 `false`로 설정합니다.

4451 4459

4452* **범위**: [`모든 파일`](#scopes). `/config`에 **Ultracode 키워드 트리거**로 나타납니다.4460* **범위**: [`모든 파일`](#scopes). `/config`에 **Ultracode 키워드 트리거**로 나타납니다.

4453* **유형**: 부울4461* **유형**: 부울

4454 * `true`: 프롬프트에서 `ultracode`를 입력하면 동적 워크플로우가 트리거됨4462 * `true`: 프롬프트에서 `ultracode`를 입력하면 동적 워크플로가 트리거됨

4455 * `false`: 단어를 입력하지 않고 입력할 수 있음4463 * `false`: 워크플로를 트리거하지 않고 이 단어를 입력할 수 있음

4456* **기본값**: `true`4464* **기본값**: `true`

4457 4465

4458```json settings.json theme={null}4466```json settings.json theme={null}

4461}4469}

4462```4470```

4463 4471

4464`ultracode` 노력 설정, `/workflows`, 저장된 워크플로우 명령은 영향을 받지 않습니다.4472`ultracode` 노력 설정, `/workflows`, 저장된 워크플로 명령은 영향을 받지 않습니다.

4465 4473

4466<h3 id="workflowsizeguideline">4474<h3 id="workflowsizeguideline">

4467 `workflowSizeGuideline`4475 `workflowSizeGuideline`

4468</h3>4476</h3>

4469 4477

4470작성하는 동적 워크플로우에서 Claude가 목표로 하는 [에이전트 수](/docs/ko/workflows#set-a-size-guideline)를 설정합니다. Claude Code는 값을 Claude에 조언으로 보냅니다. 강제 상한이 아닙니다: `"small"`은 5개 미만의 에이전트를 요청하고, `"medium"`은 10개 미만, `"large"`는 50개 미만입니다. 워크플로우가 소비하는 것을 제한하려면 `"small"`을 선택합니다. Claude Code v2.1.219 이상이 필요합니다.4478작성하는 동적 워크플로에서 Claude가 목표로 하는 [에이전트 수](/docs/ko/workflows#set-a-size-guideline)를 설정합니다. Claude Code는 값을 Claude에 조언으로 보냅니다. 강제 상한이 아닙니다: `"small"`은 5개 미만의 에이전트를 요청하고, `"medium"`은 10개 미만, `"large"`는 50개 미만입니다. 워크플로가 소비하는 것을 제한하려면 `"small"`을 선택합니다. Claude Code v2.1.219 이상이 필요합니다.

4471 4479

4472* **범위**: [`모든 파일`](#scopes). 여기의 값은 `/config`의 **동적 워크플로우 크기** 선택보다 우선순위를 가집니다. Claude Code는 이를 `~/.claude.json`에 저장하고, 설정 파일이 키를 설정하는 동안 해당 행을 숨깁니다.4480* **범위**: [`모든 파일`](#scopes). 여기의 값은 `/config`의 **동적 워크플로 크기** 선택보다 우선순위를 가집니다. Claude Code는 이를 `~/.claude.json`에 저장하고, 설정 파일이 키를 설정하는 동안 해당 행을 숨깁니다.

4473* **유형**: 문자열, 다음 중 하나:4481* **유형**: 문자열, 다음 중 하나:

4474 * `"unrestricted"`: 지침 없음, 따라서 Claude는 워크플로우를 작업에 맞게 크기 조정4482 * `"unrestricted"`: 지침 없음, 따라서 Claude는 워크플로를 작업에 맞게 크기 조정

4475 * `"small"`: Claude는 5개 미만의 에이전트를 목표로 함4483 * `"small"`: Claude는 5개 미만의 에이전트를 목표로 함

4476 * `"medium"`: Claude는 10개 미만의 에이전트를 목표로 함4484 * `"medium"`: Claude는 10개 미만의 에이전트를 목표로 함

4477 * `"large"`: Claude는 50개 미만의 에이전트를 목표로 함4485 * `"large"`: Claude는 50개 미만의 에이전트를 목표로 함

5932 5940

5933머신이 Claude에 도달할 수 있는 서비스를 나열합니다. 예를 들어 Anthropic API, Amazon Bedrock, 또는 LLM 게이트웨이입니다. 나열되지 않은 공급자의 세션은 시작 시, 로그인 시, API에 다음으로 연락할 때 거부되므로 세션 중간에 나열되지 않은 공급자로 전환하는 것도 거부됩니다. [거부 메시지](/docs/ko/errors#managed-settings-dont-allow-this-api-provider)는 공급자를 선택한 것과 계속하는 단계를 이름 지정합니다. Claude Code v2.1.285 이상이 필요합니다.5941머신이 Claude에 도달할 수 있는 서비스를 나열합니다. 예를 들어 Anthropic API, Amazon Bedrock, 또는 LLM 게이트웨이입니다. 나열되지 않은 공급자의 세션은 시작 시, 로그인 시, API에 다음으로 연락할 때 거부되므로 세션 중간에 나열되지 않은 공급자로 전환하는 것도 거부됩니다. [거부 메시지](/docs/ko/errors#managed-settings-dont-allow-this-api-provider)는 공급자를 선택한 것과 계속하는 단계를 이름 지정합니다. Claude Code v2.1.285 이상이 필요합니다.

5934 5942

5935* **범위**: [`관리됨`](#scopes). 머신 자신의 관리자가 소싱한 목록, MDM 정책 및 관리 설정 파일은 서버 관리 설정도 하나를 전달할 때 계속 적용됩니다: 세션은 두 목록 모두의 공급자만 사용할 수 있으므로 서버 관리 목록은 머신이 허용하는 것을 좁힐 수 있지만 절대 확장할 수 없습니다. 어느 머신 소스의 `allowedProviders`가 계산되는지는 [Claude Code가 관리 소스를 결합하는 방법](/docs/ko/managed-settings#how-claude-code-combines-managed-sources)을 따릅니다. 서버 관리 설정만을 통해 전달된 목록은 [서버 관리 설정을 가져오는](/docs/ko/server-managed-settings#platform-availability) 세션에만 도달합니다.5943* **범위**: [`관리됨`](#scopes). 머신 자신의 관리자 소스인 MDM 정책 및 관리형 설정 파일이 설정한 목록은 서버 관리형 설정도 하나를 전달할 때 계속 적용됩니다: 세션은 두 목록 모두에 있는 공급자만 사용할 수 있으므로 서버 관리형 목록은 머신이 허용하는 것을 좁힐 수 있지만 절대 확장할 수 없습니다. 어느 머신 소스의 `allowedProviders`가 계산되는지는 [Claude Code가 관리 소스를 결합하는 방법](/docs/ko/managed-settings#how-claude-code-combines-managed-sources)을 따릅니다. 서버 관리형 설정만을 통해 전달된 목록은 [서버 관리형 설정을 가져오는](/docs/ko/server-managed-settings#platform-availability) 세션에만 도달합니다.

5936* **유형**: 문자열 배열, 각각 다음 중 하나:5944* **유형**: 문자열 배열, 각각 다음 중 하나:

5937 * `"anthropic"`: Anthropic의 자체 호스트의 Anthropic API, claude.ai 또는 Console 로그인 또는 API 키를 통해. [`forceLoginMethod`](#forceloginmethod) 또는 [`forceLoginOrgUUID`](#forceloginorguuid)와 쌍을 이루어 로그인도 제한합니다.5945 * `"anthropic"`: Anthropic의 자체 호스트의 Anthropic API, claude.ai 또는 Console 로그인 또는 API 키를 통해. [`forceLoginMethod`](#forceloginmethod) 또는 [`forceLoginOrgUUID`](#forceloginorguuid)와 쌍을 이루어 로그인도 제한합니다.

5938 * `"bedrock"`: [Amazon Bedrock](/docs/ko/amazon-bedrock)5946 * `"bedrock"`: [Amazon Bedrock](/docs/ko/amazon-bedrock)

5967어느 `env` 블록이 핀으로 계산되는지는 목록이 설정된 위치에 따라 다릅니다:5975어느 `env` 블록이 핀으로 계산되는지는 목록이 설정된 위치에 따라 다릅니다:

5968 5976

5969* **머신의 관리자 소스가 목록을 설정합니다**: 머신의 자체 관리자 소스의 `env` 블록만 계산됩니다.5977* **머신의 관리자 소스가 목록을 설정합니다**: 머신의 자체 관리자 소스의 `env` 블록만 계산됩니다.

5970* **서버 관리 설정만 목록을 설정합니다**: 해당 서버 관리 설정의 `env` 값도 계산됩니다.5978* **서버 관리형 설정만 목록을 설정합니다**: 해당 서버 관리형 설정의 `env` 값도 계산됩니다.

5971 5979

5972목록은 클라우드 공급자의 자격 증명 및 테넌시 변수 또는 `HTTPS_PROXY` 및 인증서 설정과 같은 네트워크 경로를 판단하지 않습니다. 관리 `env` 블록에서 플릿에 대해 이를 설정합니다.5980목록은 클라우드 공급자의 자격 증명 및 테넌시 변수 또는 `HTTPS_PROXY` 및 인증서 설정과 같은 네트워크 경로를 판단하지 않습니다. 관리 `env` 블록에서 플릿에 대해 이를 설정합니다.

5973 5981

5995 6003

5996마지막 두 경우는 도우미의 출력이 Claude Code가 보내는 자격 증명이고 `ANTHROPIC_AUTH_TOKEN`이 설정되지 않았을 때만 적용됩니다.6004마지막 두 경우는 도우미의 출력이 Claude Code가 보내는 자격 증명이고 `ANTHROPIC_AUTH_TOKEN`이 설정되지 않았을 때만 적용됩니다.

5997 6005

5998대화형 세션에서, 명령이 프로젝트 또는 로컬 설정에서 올 때, Claude Code는 작업 영역 신뢰 프롬프트를 수락할 때까지 실행하지 않습니다. [자격 증명 관리](/docs/ko/authentication#credential-management)를 참조하세요.6006대화형 세션에서, 명령이 프로젝트 또는 로컬 설정에서 올 때, Claude Code는 워크스페이스 신뢰 프롬프트를 수락할 때까지 실행하지 않습니다. [자격 증명 관리](/docs/ko/authentication#credential-management)를 참조하세요.

5999 6007

6000<h3 id="awsauthrefresh">6008<h3 id="awsauthrefresh">

6001 `awsAuthRefresh`6009 `awsAuthRefresh`

6003 6011

6004Claude Code가 [Amazon Bedrock](/docs/ko/amazon-bedrock)에 대해 가진 자격 증명이 작동을 멈출 때 `.aws` 디렉토리의 자격 증명을 새로 고치기 위해 `aws sso login`과 같은 자신의 명령을 실행합니다. Claude Code는 먼저 현재 자격 증명을 STS에 대해 확인하고 해당 확인이 실패할 때만 명령을 실행한 다음 새로 고쳐진 `.aws` 디렉토리를 읽습니다.6012Claude Code가 [Amazon Bedrock](/docs/ko/amazon-bedrock)에 대해 가진 자격 증명이 작동을 멈출 때 `.aws` 디렉토리의 자격 증명을 새로 고치기 위해 `aws sso login`과 같은 자신의 명령을 실행합니다. Claude Code는 먼저 현재 자격 증명을 STS에 대해 확인하고 해당 확인이 실패할 때만 명령을 실행한 다음 새로 고쳐진 `.aws` 디렉토리를 읽습니다.

6005 6013

6014별도의 터미널이나 IDE 창과 같이 동일한 명령과 자격 증명을 사용하는 여러 Claude Code 프로세스에서 동시에 확인이 실패하면, 한 프로세스가 명령을 실행하고 나머지는 각자 실행을 시작하는 대신 해당 실행을 기다립니다. 요청이 대기 중인 상태로 60초 동안 기다린 프로세스는 직접 명령을 실행합니다. 이를 끄려면 [`CLAUDE_CODE_DISABLE_AUTH_REFRESH_LOCK`](/docs/ko/env-vars)을 `1`로 설정하세요.

6015

6006* **범위**: [`모든 파일`](#scopes)6016* **범위**: [`모든 파일`](#scopes)

6007* **유형**: 문자열, 셸 명령줄6017* **유형**: 문자열, 셸 명령줄

6008* **기본값**: 설정되지 않음, 따라서 Claude Code는 AWS 자격 증명을 새로 고치지 않습니다.6018* **기본값**: 설정되지 않음, 따라서 Claude Code는 AWS 자격 증명을 새로 고치지 않습니다.

6019 `awsCredentialExport`6029 `awsCredentialExport`

6020</h3>6030</h3>

6021 6031

6022Claude Code가 `.aws` 디렉토리에 없는 자격 증명으로 [Amazon Bedrock](/docs/ko/amazon-bedrock)을 호출할 수 있도록 AWS 자격 증명을 JSON으로 인쇄하는 자신의 명령을 실행합니다. Claude Code는 `aws sts` 출력 형태와 평면 `aws configure export-credentials` 형태를 수락하고, 자격 증명을 자신의 Bedrock 클라이언트로 범위를 지정하므로 Claude Code가 실행하는 셸 명령은 여전히 주변 자격 증명을 봅니다.6032Claude Code가 `.aws` 디렉토리에 없는 자격 증명으로 [Amazon Bedrock](/docs/ko/amazon-bedrock)을 호출할 수 있도록 AWS 자격 증명을 JSON으로 인쇄하는 자신의 명령을 실행합니다. Claude Code는 `aws sts` 출력 형태와 평면 `aws configure export-credentials` 형태를 수락하고, 자격 증명을 자신의 Bedrock 클라이언트로 범위를 지정하므로 Claude가 실행하는 셸 명령은 여전히 주변 자격 증명을 봅니다.

6023 6033

6024* **범위**: [`모든 파일`](#scopes)6034* **범위**: [`모든 파일`](#scopes)

6025* **유형**: 문자열, 셸 명령줄6035* **유형**: 문자열, 셸 명령줄

6037 `forceLoginMethod`6047 `forceLoginMethod`

6038</h3>6048</h3>

6039 6049

6040사람들이 로그인할 수 있는 계정 종류를 제한합니다. `"claudeai"`로 설정하여 claude.ai 계정만 허용하거나, `"console"`로 설정하여 Claude Console 계정만 허용하거나, `"gateway"`로 설정하여 사람들을 첫 번째 당사자 로그인 대신 [클라우드 게이트웨이](/docs/ko/claude-apps-gateway)로 보냅니다. 관리자는 관리 설정에서 설정하고 [`forceLoginOrgUUID`](#forceloginorguuid)와 쌍을 이루어 개발자의 claude.ai 로그인을 한 조직 내에 유지합니다. 설정 파일에서 `"claudeai"` 또는 `"console"`로 설정하면, Claude Code는 해당 파일이 적용되는 세션에서 [키 없는 Console 로그인](/docs/ko/authentication#sign-in-without-an-api-key)도 제공하지 않습니다.6050사람들이 로그인할 수 있는 계정 종류를 제한합니다. `"claudeai"`로 설정하여 claude.ai 계정만 허용하거나, `"console"`로 설정하여 Claude Console 계정만 허용하거나, `"gateway"`로 설정하여 사람들을 첫 번째 당사자 로그인 대신 [클라우드 게이트웨이](/docs/ko/claude-apps-gateway)로 보냅니다. 관리자는 관리형 설정에서 설정하고 [`forceLoginOrgUUID`](#forceloginorguuid)와 쌍을 이루어 개발자의 claude.ai 로그인을 한 조직 내에 유지합니다. 설정 파일에서 `"claudeai"` 또는 `"console"`로 설정하면, Claude Code는 해당 파일이 적용되는 세션에서 [키 없는 Console 로그인](/docs/ko/authentication#sign-in-without-an-api-key)도 제공하지 않습니다.

6041 6051

6042* **범위**: [`모든 파일`](#scopes). Claude Code는 `"gateway"`를 머신의 관리 소스에서만 인정합니다: `managed-settings.json`, macOS plist 또는 Windows HKLM 레지스트리, 또는 정책 도우미. 사용자, 프로젝트, 로컬, HKCU, 서버 관리 설정에서는 `"gateway"`를 설정되지 않은 것으로 취급하며, [`forceLoginGatewayUrl`](#forcelogingatewayurl)과 동일한 규칙입니다.6052* **범위**: [`모든 파일`](#scopes). Claude Code는 `"gateway"`를 머신의 관리 소스에서만 인정합니다: `managed-settings.json`, macOS plist 또는 Windows HKLM 레지스트리, 또는 정책 도우미. 사용자, 프로젝트, 로컬, HKCU, 서버 관리형 설정에서는 `"gateway"`를 설정되지 않은 것으로 취급하며, [`forceLoginGatewayUrl`](#forcelogingatewayurl)과 동일한 규칙입니다.

6043* **유형**: 문자열, 다음 중 하나:6053* **유형**: 문자열, 다음 중 하나:

6044 * `"claudeai"`: claude.ai 계정만 로그인할 수 있습니다.6054 * `"claudeai"`: claude.ai 계정만 로그인할 수 있습니다.

6045 * `"console"`: Claude Console 계정만 로그인할 수 있습니다.6055 * `"console"`: Claude Console 계정만 로그인할 수 있습니다.

6064 6074

6065이 키 또는 `forceLoginMethod: "gateway"`는 머신을 게이트웨이 전용으로 만들므로, `CLAUDE_CODE_USE_*`로 클라우드 공급자를 선택하는 세션을 제외하고, `/login`은 로그인 방법 선택기 없이 클라우드 게이트웨이 화면에서 열립니다. [관리자 정책이 클라우드 게이트웨이 로그인을 요구합니다](/docs/ko/errors#administrator-policy-requires-a-cloud-gateway-sign-in)를 참조하여 남은 첫 번째 당사자 로그인 또는 API 키에 어떤 일이 발생하는지 확인하세요. 화면이 오류를 표시하는 대신 연결하도록 두 키를 모두 설정하세요.6075이 키 또는 `forceLoginMethod: "gateway"`는 머신을 게이트웨이 전용으로 만들므로, `CLAUDE_CODE_USE_*`로 클라우드 공급자를 선택하는 세션을 제외하고, `/login`은 로그인 방법 선택기 없이 클라우드 게이트웨이 화면에서 열립니다. [관리자 정책이 클라우드 게이트웨이 로그인을 요구합니다](/docs/ko/errors#administrator-policy-requires-a-cloud-gateway-sign-in)를 참조하여 남은 첫 번째 당사자 로그인 또는 API 키에 어떤 일이 발생하는지 확인하세요. 화면이 오류를 표시하는 대신 연결하도록 두 키를 모두 설정하세요.

6066 6076

6067* **범위**: [`관리됨`](#scopes). 머신의 소스에서만 읽습니다: `managed-settings.json`, macOS plist 또는 Windows HKLM 레지스트리, 또는 정책 도우미. Claude Code는 HKCU 및 서버 관리 설정에서 무시합니다.6077* **범위**: [`관리됨`](#scopes). 머신의 소스에서만 읽습니다: `managed-settings.json`, macOS plist 또는 Windows HKLM 레지스트리, 또는 정책 도우미. Claude Code는 HKCU 및 서버 관리형 설정에서 무시합니다.

6068* **유형**: 문자열, 스키마를 포함한 전체 URL6078* **유형**: 문자열, 스키마를 포함한 전체 URL

6069* **기본값**: 설정되지 않음, 따라서 클라우드 게이트웨이 화면은 IT 관리자에게 문의하도록 알리는 오류를 표시합니다.6079* **기본값**: 설정되지 않음, 따라서 클라우드 게이트웨이 화면은 IT 관리자에게 문의하도록 알리는 오류를 표시합니다.

6070 6080

6074}6084}

6075```6085```

6076 6086

6077값이 유효한 URL이 아니면, 로그인 화면이 보고하고, 관리 설정 파일의 나머지는 여전히 적용됩니다. [게이트웨이 URL 설정](/docs/ko/claude-apps-gateway#set-the-gateway-url)을 참조하세요.6087값이 유효한 URL이 아니면, 로그인 화면이 보고하고, 관리형 설정 파일의 나머지는 여전히 적용됩니다. [게이트웨이 URL 설정](/docs/ko/claude-apps-gateway#set-the-gateway-url)을 참조하세요.

6078 6088

6079<h3 id="forceloginorguuid">6089<h3 id="forceloginorguuid">

6080 `forceLoginOrgUUID`6090 `forceLoginOrgUUID`

6106 6116

6107이 키가 없으면, `/login`은 개인 주소의 모든 게이트웨이에 연결하고 다른 것은 없습니다. 이 키가 있으면, `/login`은 또한 나열된 블록 내의 게이트웨이를 직접 연결을 통해서만 수락합니다. 해당 연결의 머신 자신의 주소도 동일한 블록 내에 있어야 합니다.6117이 키가 없으면, `/login`은 개인 주소의 모든 게이트웨이에 연결하고 다른 것은 없습니다. 이 키가 있으면, `/login`은 또한 나열된 블록 내의 게이트웨이를 직접 연결을 통해서만 수락합니다. 해당 연결의 머신 자신의 주소도 동일한 블록 내에 있어야 합니다.

6108 6118

6109* **범위**: [`관리됨`](#scopes). 머신의 소스에서만 읽습니다: `managed-settings.json`, macOS plist 또는 Windows HKLM 레지스트리, 또는 정책 도우미. Claude Code는 HKCU 및 서버 관리 설정에서 무시합니다.6119* **범위**: [`관리됨`](#scopes). 머신의 소스에서만 읽습니다: `managed-settings.json`, macOS plist 또는 Windows HKLM 레지스트리, 또는 정책 도우미. Claude Code는 HKCU 및 서버 관리형 설정에서 무시합니다.

6110* **유형**: 문자열 배열, 최대 4개의 IPv4 CIDR 블록, 각각 `/8`에서 `/32`, 서로 겹치지 않음, 그리고 개인 공간과 겹치지 않음.6120* **유형**: 문자열 배열, 최대 4개의 IPv4 CIDR 블록, 각각 `/8`에서 `/32`, 서로 겹치지 않음, 그리고 개인 공간과 겹치지 않음.

6111* **기본값**: 설정되지 않음, 따라서 `/login`은 개인 주소의 게이트웨이만 수락합니다.6121* **기본값**: 설정되지 않음, 따라서 `/login`은 개인 주소의 게이트웨이만 수락합니다.

6112 6122

6126 6136

6127Claude Code가 Google Cloud Application Default Credentials가 만료되었거나 로드할 수 없음을 발견할 때 새로 고치기 위해 자신의 명령을 실행하여 [Google Cloud의 Agent Platform](/docs/ko/google-vertex-ai) 요청이 손으로 다시 인증하지 않고도 계속 작동하도록 합니다.6137Claude Code가 Google Cloud Application Default Credentials가 만료되었거나 로드할 수 없음을 발견할 때 새로 고치기 위해 자신의 명령을 실행하여 [Google Cloud의 Agent Platform](/docs/ko/google-vertex-ai) 요청이 손으로 다시 인증하지 않고도 계속 작동하도록 합니다.

6128 6138

6139별도의 터미널이나 IDE 창과 같이 동일한 명령과 자격 증명을 사용하는 여러 Claude Code 프로세스가 동시에 자격 증명이 만료되었음을 발견하면, 한 프로세스가 명령을 실행하고 나머지는 각자 실행을 시작하는 대신 해당 실행을 기다립니다. 요청이 대기 중인 상태로 60초 동안 기다린 프로세스는 직접 명령을 실행합니다. 이를 끄려면 [`CLAUDE_CODE_DISABLE_AUTH_REFRESH_LOCK`](/docs/ko/env-vars)을 `1`로 설정하세요.

6140

6129* **범위**: [`모든 파일`](#scopes)6141* **범위**: [`모든 파일`](#scopes)

6130* **유형**: 문자열, 셸 명령줄6142* **유형**: 문자열, 셸 명령줄

6131* **기본값**: 설정되지 않음, 따라서 Claude Code의 자격 증명 오류는 `gcloud auth application-default login`을 직접 실행하도록 알립니다.6143* **기본값**: 설정되지 않음, 따라서 Claude Code의 자격 증명 오류는 `gcloud auth application-default login`을 직접 실행하도록 알립니다.

skills.md +117 −38

Details

56 56

57Claude는 실패한 명령어나 누락된 단계와 같이 실행을 잘못 조종한 경우에만 기록된 파일을 편집하므로 세션별 diff 없이 파일을 커밋할 수 있습니다. v2.1.205 이전에는 번들된 스킬이 Claude에 실행이 학습한 모든 것을 포함하도록 지시했으므로 빈번한 병합 충돌이 발생했습니다.57Claude는 실패한 명령어나 누락된 단계와 같이 실행을 잘못 조종한 경우에만 기록된 파일을 편집하므로 세션별 diff 없이 파일을 커밋할 수 있습니다. v2.1.205 이전에는 번들된 스킬이 Claude에 실행이 학습한 모든 것을 포함하도록 지시했으므로 빈번한 병합 충돌이 발생했습니다.

58 58

59<h3 id="work-on-claude-api-projects">

60 Claude API 프로젝트 작업

61</h3>

63번들 `/claude-api` 스킬은 프로젝트 언어에 맞는 [Claude API](https://platform.claude.com/docs/en/api/overview) 및 [Managed Agents](https://platform.claude.com/docs/en/managed-agents/overview) 참조 자료를 로드합니다. 코드에서 `anthropic` 또는 `@anthropic-ai/sdk`를 가져오는 경우 Claude가 이 스킬을 자동으로 활성화하기도 합니다.

65스킬의 워크플로 중 하나를 시작하려면 Claude Code 프롬프트에서 스킬 이름 뒤에 하위 명령을 입력합니다(예: `/claude-api migrate`). 아래 표에는 각 하위 명령의 기능과 해당 하위 명령이 포함된 가장 이른 Claude Code 버전이 나와 있습니다. `migrate`와 `managed-agents-onboard`는 표에서 추적하는 가장 오래된 버전인 v2.1.221 이전부터 제공되었습니다.

67| 하위 명령 | 기능 | 최소 버전 |

68| :- | :- | :- |

69| `migrate` | 기존 Claude API 코드를 최신 모델에 맞게 업데이트 | v2.1.221 이전 |

70| `upgrade` | 프로젝트의 Anthropic SDK 의존성을 메이저 버전 간에 이전(현재는 Python `anthropic` 패키지를 0.x에서 1.x로) | v2.1.236 이상 |

71| `managed-agents-onboard` | 새 Managed Agent 생성 과정을 단계별로 안내 | v2.1.221 이전 |

72| `prompt-audit` | 프롬프트, 스킬, 도구 설명에서 이전 모델용으로 작성된 지침에 플래그를 지정하고 수정 사항을 diff로 제안 | v2.1.221 이상 |

73| `cost-optimize` | 프로젝트의 Claude API 지출이 어디에 쓰이는지 프로파일링하고, 프롬프트 캐싱, 불필요한 입력 및 출력 토큰 줄이기, 배치 처리, effort, 모델 선택 등의 옵션을 통한 절감 방안을 한 번에 하나씩 제안 | v2.1.247 이상 |

74| `build-eval` | Claude 기반 앱을 위한 평가 세트 구축 | v2.1.259 이상 |

75| `hillclimb` | 기존 평가를 기준으로 앱을 반복적으로 개선 | v2.1.259 이상 |

76| `preserved-thinking-migration` | 통합이 이전 턴, 시스템 프롬프트 또는 도구 목록에 가하는 편집 중 [preserved thinking](https://platform.claude.com/docs/en/build-with-claude/preserved-thinking) 블록을 무효화하는 편집을 찾아 각 편집으로 손실되는 추론의 양을 측정하고, 수정 사항을 한 번에 하나씩 제안하며 변경할 때마다 다시 측정 | v2.1.282 이상 |

59<h2 id="getting-started">78<h2 id="getting-started">

60 시작하기79 시작하기

61</h2>80</h2>

76 </Step>95 </Step>

77 96

78 <Step title="SKILL.md 작성">97 <Step title="SKILL.md 작성">

79 모든 skill에는 `SKILL.md` 파일이 필요합니다. 이 파일은 두 부분으로 구성됩니다: Claude에게 skill을 언제 사용할지 알려주는 `---` 마커 사이의 YAML frontmatter와 skill이 실행될 때 Claude가 따르는 지침이 포함된 markdown 콘텐츠입니다. 디렉토리 이름이 입력하는 명령어가 되고, `description`은 Claude가 skill을 자동으로 로드할지 결정하는 데 도움이 됩니다.98 모든 스킬에는 `SKILL.md` 파일이 필요합니다. 이 파일은 두 부분으로 구성됩니다: Claude에게 스킬을 언제 사용할지 알려주는 `---` 마커 사이의 YAML frontmatter와 스킬이 실행될 때 Claude가 따르는 지침이 포함된 markdown 콘텐츠입니다. 디렉토리 이름(또는 frontmatter `name`을 설정한 경우 해당 값)이 입력하는 명령이 되고, `description`은 Claude가 스킬을 자동으로 로드할지 결정하는 데 도움이 됩니다.

80 99

81 이를 `~/.claude/skills/summarize-changes/SKILL.md`에 저장합니다:100 이를 `~/.claude/skills/summarize-changes/SKILL.md`에 저장합니다:

82 101

130| Nested | `<subdir>/.claude/skills/<skill-name>/SKILL.md` | `<subdir>`에서 시작되거나 그 아래에서 시작된 세션. `<subdir>` 위에서 시작된 세션은 Claude가 그곳의 파일에서 작업할 때 스킬을 로드합니다. [모노레포 및 하위 디렉토리](#discovery-from-parent-and-nested-directories) 참조 |149| Nested | `<subdir>/.claude/skills/<skill-name>/SKILL.md` | `<subdir>`에서 시작되거나 그 아래에서 시작된 세션. `<subdir>` 위에서 시작된 세션은 Claude가 그곳의 파일에서 작업할 때 스킬을 로드합니다. [모노레포 및 하위 디렉토리](#discovery-from-parent-and-nested-directories) 참조 |

131| Additional directory | `.claude/skills/<skill-name>/SKILL.md` in a directory you pass with `--add-dir` | 해당 세션. [프로젝트 외부의 디렉토리](#skills-from-additional-directories) 참조 |150| Additional directory | `.claude/skills/<skill-name>/SKILL.md` in a directory you pass with `--add-dir` | 해당 세션. [프로젝트 외부의 디렉토리](#skills-from-additional-directories) 참조 |

134 153

135스킬 폴더는 또한 다음 규칙을 따릅니다:154스킬 폴더는 또한 다음 규칙을 따릅니다:

136 155

137* **심볼릭 링크된 폴더**: enterprise, personal 또는 project 위치의 `<skill-name>` 항목은 디스크의 다른 위치에 있는 디렉토리로의 심볼릭 링크일 수 있습니다. Claude Code는 대상에서 `SKILL.md`를 읽고 여러 위치가 같은 대상을 가리키더라도 스킬을 한 번만 로드합니다. 플러그인 스킬은 [심볼릭 링크를 다르게 처리합니다](/docs/ko/plugins-reference#share-files-within-a-marketplace-with-symlinks).156* **심볼릭 링크된 폴더**: enterprise, personal 또는 project 위치의 `<skill-name>` 항목은 디스크의 다른 위치에 있는 디렉터리로의 심볼릭 링크일 수 있습니다. Claude Code는 대상에서 `SKILL.md`를 읽고 여러 위치가 같은 대상을 가리키더라도 스킬을 한 번만 로드합니다. 플러그인 스킬은 [심볼릭 링크를 다르게 처리합니다](/docs/ko/plugins/host-marketplace#share-files-within-a-marketplace-with-symlinks).

138* **예약된 이름**: 스킬 폴더를 `synced`로 명명하지 마세요(대소문자 상관없음). Claude Code는 `~/.claude/skills/synced/`를 [claude.ai에서 다운로드한 스킬](#where-synced-skills-load)에 사용하며 enterprise, personal 및 project 위치에서 해당 이름으로 작성한 스킬을 건너뜁니다.157* **예약된 이름 `synced`**: 스킬 폴더 이름을 대소문자와 관계없이 `synced`로 지정하지 마세요. Claude Code는 `~/.claude/skills/synced/`를 [claude.ai에서 다운로드한 스킬](#where-synced-skills-load)에 사용하며 enterprise, personal 및 project 위치에서 해당 이름으로 작성한 스킬을 건너뜁니다.

158* **예약된 이름 `anthropic-skills`**: 플러그인 외부에서 이름이 `anthropic-skills`이거나 `anthropic-skills:`로 시작하는 스킬 폴더 또는 명령 파일은 로드되지 않습니다. [동기화된 스킬용으로 예약된 이름](#names-reserved-for-synced-skills)을 참조하세요.

139* **명령 파일**: `.claude/commands/`의 Markdown 파일은 이전 형식이며 여전히 작동합니다. `name` 및 `paths`를 제외한 동일한 [frontmatter](#frontmatter-reference)를 지원합니다. 호출하기 위해 입력하는 이름을 찾으려면 [스킬이 명령 이름을 얻는 방법](#how-a-skill-gets-its-command-name)을 참조하세요. 스킬은 [지원 파일](#add-supporting-files)도 지원하므로 새 작업에는 스킬을 선호합니다.159* **명령 파일**: `.claude/commands/`의 Markdown 파일은 이전 형식이며 여전히 작동합니다. `name` 및 `paths`를 제외한 동일한 [frontmatter](#frontmatter-reference)를 지원합니다. 호출하기 위해 입력하는 이름을 찾으려면 [스킬이 명령 이름을 얻는 방법](#how-a-skill-gets-its-command-name)을 참조하세요. 스킬은 [지원 파일](#add-supporting-files)도 지원하므로 새 작업에는 스킬을 선호합니다.

140* **플러그인으로서의 스킬 폴더**: 스킬 폴더에 `.claude-plugin/plugin.json`을 추가하면 [플러그인](/docs/ko/plugins-reference#skills-directory-plugins)으로 `<name>@skills-dir`이라는 이름으로 로드되므로 에이전트, 훅 및 MCP 서버를 번들할 수 있습니다. 프로젝트의 `.claude/skills/`에서는 먼저 워크스페이스 신뢰 대화를 수락해야 합니다.160* **플러그인으로서의 스킬 폴더**: 스킬 폴더에 `.claude-plugin/plugin.json`을 추가하면 `<name>@skills-dir`이라는 이름의 [플러그인](/docs/ko/plugins/loading#plugins-shared-through-a-repository)으로 로드되므로 에이전트, 훅 및 MCP 서버를 번들할 수 있습니다. 프로젝트의 `.claude/skills/`에서는 먼저 워크스페이스 신뢰 대화 상자를 수락해야 합니다.

141 161

142<h3 id="discovery-from-parent-and-nested-directories">162<h3 id="discovery-from-parent-and-nested-directories">

143 모노레포 및 하위 디렉토리에서 스킬 로드163 모노레포 및 하위 디렉토리에서 스킬 로드

145 165

146Claude Code는 세션을 시작한 디렉토리와 저장소 루트까지의 모든 상위 디렉토리의 `.claude/skills/`에서 프로젝트 스킬을 로드하므로 `packages/frontend/`에서 시작해도 루트에 정의된 스킬을 선택합니다. v2.1.246 이상에서 [`/cd`로 세션을 이동](/docs/ko/permissions#move-the-session-to-another-directory)하면 Claude Code는 새 디렉토리의 프로젝트 스킬을 추가합니다.166Claude Code는 세션을 시작한 디렉토리와 저장소 루트까지의 모든 상위 디렉토리의 `.claude/skills/`에서 프로젝트 스킬을 로드하므로 `packages/frontend/`에서 시작해도 루트에 정의된 스킬을 선택합니다. v2.1.246 이상에서 [`/cd`로 세션을 이동](/docs/ko/permissions#move-the-session-to-another-directory)하면 Claude Code는 새 디렉토리의 프로젝트 스킬을 추가합니다.

147 167

168연결된 [git worktree](/docs/ko/worktrees)에서 실행되는 세션에서 Claude Code는 worktree 루트까지만 상위 디렉터리를 검색합니다. Claude Code v2.1.277 이상에서는 worktree 체크아웃의 루트에 `.claude/skills` 디렉터리가 없으면 Claude Code가 대신 메인 체크아웃의 프로젝트 스킬을 로드합니다. [워크트리가 메인 체크아웃과 공유하는 항목](/docs/ko/worktrees#what-worktrees-share-with-the-main-checkout)을 참조하세요.

169

148시작한 위치 아래의 `.claude/skills/` 디렉토리의 스킬은 시작 시 로드되지 않습니다. Claude가 해당 하위 디렉토리의 파일을 처음 읽거나 편집할 때 로드되며 세션의 나머지 기간 동안 사용 가능합니다. 그때까지는 `/` 메뉴에 나타나지 않으며 이름으로 호출할 수 없습니다. 더 빨리 로드하려면 하위 디렉토리의 경로와 함께 `/add-dir`을 실행하세요. 이는 Claude Code v2.1.257 이상이 필요합니다.170시작한 위치 아래의 `.claude/skills/` 디렉토리의 스킬은 시작 시 로드되지 않습니다. Claude가 해당 하위 디렉토리의 파일을 처음 읽거나 편집할 때 로드되며 세션의 나머지 기간 동안 사용 가능합니다. 그때까지는 `/` 메뉴에 나타나지 않으며 이름으로 호출할 수 없습니다. 더 빨리 로드하려면 하위 디렉토리의 경로와 함께 `/add-dir`을 실행하세요. 이는 Claude Code v2.1.257 이상이 필요합니다.

149 171

150중첩된 스킬이 다른 스킬과 이름을 공유할 때 둘 다 사용 가능합니다. 저장소 루트에 `deploy` 스킬이 있고 `apps/web/.claude/skills/`에 다른 스킬이 있는 경우:172중첩된 스킬의 디렉터리 이름이 다른 스킬의 이름과 일치할 때 둘 다 사용 가능합니다. 저장소 루트에 `deploy` 스킬이 있고 `apps/web/.claude/skills/`에 다른 스킬이 있는 경우:

151 173

152* `/deploy`는 루트 스킬을 실행합니다. Claude Code는 또한 Claude를 위해 디렉토리 한정 변형을 나열하며, 작업 중인 파일이 있는 디렉토리의 스킬을 호출하도록 지시하므로 중첩된 스킬은 여전히 `apps/web/`의 작업에 적용됩니다.174* `/deploy`는 루트 스킬을 실행합니다. Claude Code는 또한 Claude를 위해 디렉토리 한정 변형을 나열하며, 작업 중인 파일이 있는 디렉토리의 스킬을 호출하도록 지시하므로 중첩된 스킬은 여전히 `apps/web/`의 작업에 적용됩니다.

153* `/apps/web:deploy`는 중첩된 스킬을 독립적으로 실행합니다. 설명에 적용되는 디렉토리의 이름이 지정됩니다.175* `/apps/web:deploy`는 중첩된 스킬을 독립적으로 실행합니다. 설명에 적용되는 디렉토리의 이름이 지정됩니다.

166 이름이 같은 스킬 해결188 이름이 같은 스킬 해결

167</h3>189</h3>

168 190

169두 스킬이 같은 이름을 공유할 때 각각이 어디에서 왔는지에 따라 `/name`이 실행하는 스킬이 결정됩니다. 표는 enterprise, personal, project, nested, plugin 및 claude.ai 위치, 번들된 스킬 및 명령 파일을 다룹니다:191두 스킬이 같은 디렉터리 이름이나 파일 이름을 공유할 때 각각이 어디에서 왔는지에 따라 `/name`이 실행하는 스킬이 결정됩니다. frontmatter `name` 필드로 설정된 이름의 경우 [스킬이 명령 이름을 얻는 방법](#how-a-skill-gets-its-command-name)을 참조하세요. 표는 enterprise, personal, project, nested, plugin 및 claude.ai 위치, 번들 스킬 및 명령 파일을 다룹니다:

170 192

171| 같은 이름 위치 | 실행되는 스킬 |193| 같은 이름 위치 | 실행되는 스킬 |

172| :- | :- |194| :- | :- |

175| 스킬과 `.claude/commands/`의 파일 | 스킬 |197| 스킬과 `.claude/commands/`의 파일 | 스킬 |

176| 프로젝트 루트 스킬과 중첩된 스킬 | 둘 다 로드됩니다. [모노레포 및 하위 디렉토리](#discovery-from-parent-and-nested-directories) 참조 |198| 프로젝트 루트 스킬과 중첩된 스킬 | 둘 다 로드됩니다. [모노레포 및 하위 디렉토리](#discovery-from-parent-and-nested-directories) 참조 |

178| 위의 모든 것과 [claude.ai 계정에서 동기화된](#how-synced-skills-behave) 스킬 | 다른 스킬 또는 명령. 동기화된 스킬은 여전히 `/anthropic-skills:<name>`으로 실행됩니다. [동기화된 스킬 이름이 다른 명령과 일치할 때](#when-a-synced-skill-name-matches-another-command) 참조 |200| 위의 모든 것과 [claude.ai 계정에서 동기화된](#how-synced-skills-behave) 스킬의 짧은 이름 | 다른 스킬 또는 명령. 이 경우 동기화된 스킬은 전체 이름으로만 나열되고 실행됩니다. [동기화된 스킬 이름이 다른 명령과 일치할 때](#when-a-synced-skill-name-matches-another-command) 참조 |

179 201

180<h3 id="skills-in-cowork-and-cloud-sessions">202<h3 id="skills-in-cowork-and-cloud-sessions">

181 Cowork 및 클라우드 세션에서 스킬 사용203 Cowork 및 클라우드 세션에서 스킬 사용

186스킬이 머신의 `~/.claude/skills/`에만 존재하면 [루틴](/docs/ko/routines)이 호출할 때 Claude Code는 스킬을 찾을 수 없다고 보고합니다. 각 루틴 실행이 새로운 클라우드 세션으로 시작되기 때문입니다. 이러한 세션에서 개인 스킬을 사용 가능하게 하려면:208스킬이 머신의 `~/.claude/skills/`에만 존재하면 [루틴](/docs/ko/routines)이 호출할 때 Claude Code는 스킬을 찾을 수 없다고 보고합니다. 각 루틴 실행이 새로운 클라우드 세션으로 시작되기 때문입니다. 이러한 세션에서 개인 스킬을 사용 가능하게 하려면:

187 209

188* Cowork 및 클라우드 세션의 경우 claude.ai 계정에 대해 스킬을 활성화합니다.210* Cowork 및 클라우드 세션의 경우 claude.ai 계정에 대해 스킬을 활성화합니다.

189* 클라우드 세션의 경우 대신 저장소의 `.claude/skills/`에 스킬을 커밋하거나 저장소의 `.claude/settings.json`에 선언된 플러그인에 포함시킬 수 있습니다. 저장소 선언 플러그인은 [세션 시작 시 설치됩니다](/docs/ko/cloud-environments#what-carries-over-from-your-setup). 사용자 설정에서만 활성화된 플러그인은 전송되지 않습니다.211* 클라우드 세션의 경우 대신 저장소의 `.claude/skills/`에 스킬을 커밋할 수 있습니다. 저장소의 `.claude/settings.json`에 선언된 플러그인과 사용자 설정에서만 활성화된 플러그인은 [클라우드 세션에서 로드되지 않습니다](/docs/ko/cloud-environments#what-carries-over-from-your-setup).

190 212

191[Desktop 예약된 작업](/docs/ko/desktop-scheduled-tasks)은 머신에서 로컬로 실행되므로 `~/.claude/skills/`를 로드합니다.213[Desktop 예약된 작업](/docs/ko/desktop-scheduled-tasks)은 머신에서 로컬로 실행되므로 `~/.claude/skills/`를 로드합니다.

192 214

219 241

220이전 세션이 동기화한 스킬은 디스크에 남아 있습니다. Claude Code는 같은 계정으로 로그인한 나중 세션에서 claude.ai에 도달할 수 없을 때도 이를 로드합니다.242이전 세션이 동기화한 스킬은 디스크에 남아 있습니다. Claude Code는 같은 계정으로 로그인한 나중 세션에서 claude.ai에 도달할 수 없을 때도 이를 로드합니다.

221 243

244Claude Code는 동기화된 스킬을 다운로드만 하며 업로드하지 않습니다. 사용자나 Claude가 `~/.claude/skills/synced/` 아래의 파일을 편집하면 변경 사항은 claude.ai 계정에 저장되지 않으며, 이후 동기화에서 덮어쓰거나 제거될 수 있습니다. 동기화된 스킬을 변경하려면 claude.ai에서 업데이트하세요. 다음 동기화에서 새 버전을 다운로드합니다.

245

222동기화된 스킬을 보려면 `/skills`를 실행하세요. 메뉴는 `claude.ai sync` 아래에 나열합니다.246동기화된 스킬을 보려면 `/skills`를 실행하세요. 메뉴는 `claude.ai sync` 아래에 나열합니다.

223 247

224`pdf` 및 `xlsx`와 같은 Anthropic의 일부 스킬은 항상 동기화됩니다. 나머지의 경우 claude.ai의 스킬 설정에서 스킬을 켜거나 꺼서 동기화 여부를 변경하세요.248`pdf` 및 `xlsx`와 같은 Anthropic의 일부 스킬은 항상 동기화됩니다. 나머지의 경우 claude.ai의 스킬 설정에서 스킬을 켜거나 꺼서 동기화 여부를 변경하세요.

231 동기화된 스킬 이름이 다른 명령과 일치할 때255 동기화된 스킬 이름이 다른 명령과 일치할 때

232</h4>256</h4>

233 257

234동기화된 스킬을 전체 이름 `/anthropic-skills:<name>` 또는 짧은 이름 `/<name>`으로 호출할 수 있습니다. 다른 명령이 해당 짧은 이름을 사용할 때 `/<name>`은 다른 명령을 실행하고 동기화된 스킬은 `/anthropic-skills:<name>`으로만 실행됩니다. 로컬 `deploy` 스킬과 동기화된 `deploy`가 있으면 `/deploy`는 로컬 스킬을 실행하고 `/anthropic-skills:deploy`는 동기화된 스킬을 실행합니다. v2.1.269 이전에는 동기화된 스킬이 짧은 이름만 가졌습니다.258동기화된 스킬은 짧은 이름 `/<name>` 또는 전체 이름 `/anthropic-skills:<name>`으로 호출할 수 있습니다. 다른 명령이 해당 짧은 이름을 사용할 때 `/<name>`은 다른 명령을 실행하고 동기화된 스킬은 `/anthropic-skills:<name>`으로만 실행됩니다. 로컬 `deploy` 스킬과 동기화된 `deploy`가 있으면 `/deploy`는 로컬 스킬을 실행하고 `/anthropic-skills:deploy`는 동기화된 스킬을 실행합니다. v2.1.269 이전에는 동기화된 스킬이 짧은 이름만 가졌습니다.

235 259

236다른 명령은 다음 중 하나일 수 있습니다:260`/` 메뉴, `/skills` 및 `/context`에서 동기화된 스킬은 짧은 이름으로 표시되며, 다른 명령이 짧은 이름을 사용하는 동안에는 전체 이름으로 표시됩니다. 세션에서 `/skills`를 실행하세요. 목록 아래의 안내에서 짧은 이름을 잃은 각 동기화된 스킬을 설명합니다. `~/.claude/`에 있는 personal 스킬이나 명령 파일 중 하나가 해당 이름을 사용하는 경우, 안내에는 이름을 되찾기 위해 무엇의 이름을 바꾸거나 삭제해야 하는지도 표시됩니다.

261

262v2.1.269부터 v2.1.280까지는 이러한 목록에 모든 동기화된 스킬이 전체 이름으로 표시되었고 `/skills`에는 이러한 안내가 없었습니다. 두 가지 모두 v2.1.281에서 변경되었습니다.

263

264짧은 이름을 사용하는 명령은 다음 중 하나일 수 있습니다:

237 265

238* 기본 제공 명령 또는 [번들된 스킬](#bundled-skills)(예: 세션에서 번들된 스킬을 끈 후 사용 불가능한 스킬 포함)266* 기본 제공 명령 또는 [번들된 스킬](#bundled-skills)(예: 세션에서 번들된 스킬을 끈 후 사용 불가능한 스킬 포함)

239* 모든 [로컬 수준](#where-skills-live)의 스킬 또는 `.claude/commands/`의 파일267* 모든 [로컬 수준](#where-skills-live)의 스킬 또는 `.claude/commands/`의 파일

246 274

247다른 알파벳의 모양이 비슷한 문자로만 다른 이름은 다른 이름으로 간주되며 `claude.ai sync` 레이블은 두 개를 구분하는 방법입니다. 이러한 검사 및 레이블에는 Claude Code v2.1.228 이상이 필요합니다.275다른 알파벳의 모양이 비슷한 문자로만 다른 이름은 다른 이름으로 간주되며 `claude.ai sync` 레이블은 두 개를 구분하는 방법입니다. 이러한 검사 및 레이블에는 Claude Code v2.1.228 이상이 필요합니다.

248 276

277<h4 id="names-reserved-for-synced-skills">

278 동기화된 스킬용으로 예약된 이름

279</h4>

280

281Claude Code는 `anthropic-skills`라는 이름과 `anthropic-skills:pdf`처럼 해당 네임스페이스 안의 모든 이름을 claude.ai에서 동기화된 스킬용으로 예약하므로, 동기화된 스킬의 전체 이름이 다른 것을 실행하는 일은 없습니다. 이 이름은 claude.ai 계정으로 로그인하는지 여부와 관계없이 모든 세션에서 예약됩니다.

282

283* **스킬 폴더, frontmatter `name`, `.claude/commands/`의 파일 또는 하위 폴더, 또는 [저장된 워크플로](/docs/ko/workflows#save-the-workflow-for-reuse)**: 로드되지 않습니다. [시작 알림](/docs/ko/errors#a-skill-command-or-workflow-wasnt-loaded-because-its-name-is-reserved)에 이름을 바꾸거나 편집해야 할 첫 번째 항목이 표시됩니다.

284* **`anthropic-skills`라는 이름의 플러그인**: 로드됩니다. 해당 플러그인의 스킬 중 하나와 동기화된 스킬의 이름이 모두 `<name>`인 경우 `/anthropic-skills:<name>`은 동기화된 스킬을 실행합니다.

285* **`anthropic-skills`라는 이름의 MCP 서버**: 연결되고 도구도 작동하지만 [프롬프트가 명령으로 표시되지 않습니다](/docs/ko/mcp#use-mcp-prompts-as-commands). 프롬프트를 나열하려면 MCP 구성에서 서버 이름을 변경하세요.

286

249<h4 id="how-claude-code-handles-the-frontmatter-of-a-synced-skill">287<h4 id="how-claude-code-handles-the-frontmatter-of-a-synced-skill">

250 Claude Code가 동기화된 스킬의 frontmatter를 처리하는 방법288 Claude Code가 동기화된 스킬의 frontmatter를 처리하는 방법

251</h4>289</h4>

269 세션 중 스킬 편집307 세션 중 스킬 편집

270</h3>308</h3>

271 309

272Claude Code는 [베어 모드](/docs/ko/headless#start-faster-with-bare-mode)를 제외하고 스킬 디렉토리의 파일 변경을 감시합니다. `~/.claude/skills/`, 프로젝트 `.claude/skills/` 또는 `--add-dir` 디렉토리 내의 `.claude/skills/` 아래에서 스킬을 추가, 편집 또는 제거하면 Claude Code는 재시작 없이 현재 세션 내에서 변경을 선택합니다. 세션이 시작될 때 존재하지 않았던 최상위 스킬 디렉토리를 만들면 Claude Code를 다시 시작하여 새 디렉토리를 감시할 수 있도록 합니다.310Claude Code는 [bare 모드](/docs/ko/headless#start-faster-with-bare-mode)를 제외하고 스킬 디렉터리의 파일 변경을 감시합니다. `~/.claude/skills/`, 프로젝트 `.claude/skills/` 또는 `--add-dir` 디렉터리 내의 `.claude/skills/` 아래에서 스킬을 추가, 편집 또는 제거하면 Claude Code는 재시작 없이 현재 세션 내에서 변경 사항을 반영합니다.

311

312세션이 시작될 때 존재하지 않았던 최상위 스킬 디렉터리를 만든 경우 [`/reload-skills`](/docs/ko/commands#all-commands)를 실행하여 그곳에 넣은 스킬을 가져오세요. Claude Code는 아직 해당 디렉터리를 감시하지 않으므로 이후 그곳에서 변경할 때마다 `/reload-skills`를 다시 실행하세요.

273 313

274라이브 변경 감지는 `SKILL.md` 텍스트만 다룹니다. 스킬 폴더가 [플러그인](/docs/ko/plugins-reference#skills-directory-plugins)이기도 한 경우 `hooks/`, `.mcp.json`, `agents/` 및 `output-styles/`의 변경 사항은 `/reload-plugins`가 적용되어야 합니다.314라이브 변경 감지는 `SKILL.md` 텍스트만 다룹니다. 스킬 폴더가 [플러그인](/docs/ko/plugins/loading#plugins-shared-through-a-repository)이기도 한 경우 `hooks/`, `.mcp.json`, `agents/` 및 `output-styles/`의 변경 사항을 적용하려면 `/reload-plugins`가 필요합니다.

275 315

276<h3 id="remove-a-skill">316<h3 id="remove-a-skill">

277 스킬 제거317 스킬 제거

281 321

282* **Personal 또는 project 스킬**: 스킬의 디렉토리 `~/.claude/skills/<skill-name>/` 또는 `.claude/skills/<skill-name>/`을 삭제합니다. Claude Code는 [현재 세션의 `/skills`에서 삭제합니다](#live-change-detection). Claude Code가 이미 로드한 콘텐츠는 [스킬 콘텐츠 수명 주기](#skill-content-lifecycle)를 따릅니다.322* **Personal 또는 project 스킬**: 스킬의 디렉토리 `~/.claude/skills/<skill-name>/` 또는 `.claude/skills/<skill-name>/`을 삭제합니다. Claude Code는 [현재 세션의 `/skills`에서 삭제합니다](#live-change-detection). Claude Code가 이미 로드한 콘텐츠는 [스킬 콘텐츠 수명 주기](#skill-content-lifecycle)를 따릅니다.

283* **Enterprise 스킬**: 관리자가 [관리형 설정 디렉토리](/docs/ko/managed-settings#delivery-mechanisms) 내의 `.claude/skills/`에서 스킬의 디렉토리를 삭제합니다. 예를 들어 Linux의 `/etc/claude-code/.claude/skills/<skill-name>/`.323* **Enterprise 스킬**: 관리자가 [관리형 설정 디렉토리](/docs/ko/managed-settings#delivery-mechanisms) 내의 `.claude/skills/`에서 스킬의 디렉토리를 삭제합니다. 예를 들어 Linux의 `/etc/claude-code/.claude/skills/<skill-name>/`.

284* **Plugin 스킬**: `/plugin` 메뉴에서 또는 `/plugin uninstall <plugin-name>@<marketplace-name>`으로 스킬을 제공하는 플러그인을 비활성화하거나 제거합니다. Claude Code는 [변경이 적용될 때](/docs/ko/discover-plugins#apply-plugin-changes-without-restarting) 또는 재시작할 때 플러그인의 스킬을 언로드합니다.324* **Plugin 스킬**: `/plugin` 메뉴에서 또는 `/plugin uninstall <plugin-name>@<marketplace-name>`으로 스킬을 제공하는 플러그인을 비활성화하거나 제거합니다. Claude Code는 [변경이 적용될 때](/docs/ko/plugins/cli-reference#reload-plugins) 또는 재시작할 때 플러그인의 스킬을 언로드합니다.

285* **claude.ai에서 동기화된 스킬**: [활성화한](#skills-in-cowork-and-cloud-sessions) 것과 같은 위치에서 claude.ai 계정에 대해 스킬을 끕니다. Claude Code는 다음 번에 [스킬을 동기화할 때](#where-synced-skills-load) `~/.claude/skills/synced/`에서 제거합니다. 대신 디렉토리를 직접 삭제하면 다음 동기화가 스킬이 claude.ai에서 활성화된 상태로 유지되는 동안 다시 다운로드합니다.325* **claude.ai에서 동기화된 스킬**: [활성화한](#skills-in-cowork-and-cloud-sessions) 것과 같은 위치에서 claude.ai 계정에 대해 스킬을 끕니다. Claude Code는 다음 번에 [스킬을 동기화할 때](#where-synced-skills-load) `~/.claude/skills/synced/`에서 제거합니다. 대신 디렉토리를 직접 삭제하면 다음 동기화가 스킬이 claude.ai에서 활성화된 상태로 유지되는 동안 다시 다운로드합니다.

286* **번들된 스킬**: [`disableBundledSkills`](#bundled-skills)를 `true`로 설정하여 번들된 스킬을 끄거나 [`skillOverrides`](#override-skill-visibility-from-settings)에서 하나의 스킬을 `"off"`로 설정하여 숨깁니다.326* **번들된 스킬**: [`disableBundledSkills`](#bundled-skills)를 `true`로 설정하여 번들된 스킬을 끄거나 [`skillOverrides`](#override-skill-visibility-from-settings)에서 하나의 스킬을 `"off"`로 설정하여 숨깁니다.

287 327

335 프론트매터 참고375 프론트매터 참고

336</h3>376</h3>

337 377

338마크다운 콘텐츠 외에도 `SKILL.md` 파일 상단의 `---` 마커 사이의 YAML 프론트매터 필드를 사용하여 스킬 동작을 구성할 수 있습니다.378`SKILL.md` 상단의 `---` 마커 사이에 있는 YAML [frontmatter](/docs/ko/glossary#frontmatter)로 스킬을 구성하고, 닫는 `---` 뒤에 스킬의 지침을 Markdown으로 작성합니다. 필드 이름은 `when_to_use`를 제외하고 하이픈으로 구분된 소문자 단어를 사용합니다. `.claude/commands/`의 [명령 파일](#where-skills-live)은 `name` 및 `paths`를 제외한 동일한 필드를 허용합니다. 이 예제는 네 개의 필드를 설정합니다.

339 379

340```yaml theme={null}380```yaml theme={null}

341---381---

348Your skill instructions here...388Your skill instructions here...

349```389```

350 390

351모든 필드는 선택 사항입니다. Claude가 스킬을 언제 사용할지 알 수 있도록 `description`만 권장됩니다.391모든 필드는 선택 사항입니다. Claude가 스킬을 언제 사용할지 알 수 있도록 `description`만 권장됩니다. 필드 이름은 하이픈을 포함하여 표와 정확히 일치해야 합니다. Claude Code는 인식하지 못하는 필드를 오류를 보고하지 않고 무시합니다.

352 392

353Claude Code는 파일의 첫 번째 줄이 `---`일 때만 프론트매터를 읽습니다. 그렇지 않으면 `---` 마커를 포함한 전체 파일을 스킬 콘텐츠로 취급합니다.393Claude Code는 파일의 첫 번째 줄이 `---`일 때만 frontmatter를 읽습니다. 그렇지 않으면 `---` 마커를 포함한 전체 파일을 스킬 콘텐츠로 취급합니다. 마커 사이의 YAML을 파싱할 수 없는 경우에도 스킬은 필드가 설정되지 않은 상태로 로드됩니다. 오류를 찾아 수정하려면 [스킬이 트리거되지 않음](#skill-not-triggering)을 참조하세요.

354 394

355부울 필드는 `true` 및 `false` 외에도 모든 문자 케이스에서 `yes`, `no`, `on`, `off`, `1`, `0`을 허용합니다. v2.1.218 이전에는 Claude Code가 `true` 및 `false`만 인식했습니다.395부울 필드는 `true` 및 `false` 외에도 모든 문자 케이스에서 `yes`, `no`, `on`, `off`, `1`, `0`을 허용합니다. v2.1.218 이전에는 Claude Code가 `true` 및 `false`만 인식했습니다.

356 396

357| 필드 | 필수 | 설명 |397| 필드 | 필수 | 설명 |

358| :- | :- | :- |398| :- | :- | :- |

359| `name` | 아니요 | 스킬 목록에 표시되는 표시 이름입니다. 기본값은 디렉토리 이름입니다. [스킬이 명령 이름을 얻는 방법](#how-a-skill-gets-its-command-name)을 참조하여 필드가 스킬을 호출하기 위해 입력하는 이름과 어떻게 상호 작용하는지 확인하세요. |399| `name` | 아니요 | `/` 메뉴에 표시되는 명령 이름입니다. 기본값은 디렉터리 이름입니다. [스킬이 명령 이름을 얻는 방법](#how-a-skill-gets-its-command-name)을 참조하여 필드가 스킬을 호출하기 위해 입력하는 이름과 어떻게 상호 작용하는지 확인하세요. |

360| `description` | 권장 | 스킬이 무엇을 하는지, 언제 사용할지입니다. Claude는 이를 사용하여 스킬을 적용할 시기를 결정합니다. 생략하면 마크다운 콘텐츠의 첫 번째 비어 있지 않은 줄을 사용합니다. 주요 사용 사례를 먼저 입력하세요. 결합된 `description` 및 `when_to_use` 텍스트는 컨텍스트 사용을 줄이기 위해 스킬 목록에서 1,536자로 잘립니다. |400| `description` | 권장 | 스킬이 무엇을 하는지, 언제 사용할지입니다. Claude는 이를 사용하여 스킬을 적용할 시기를 결정합니다. 생략하면 마크다운 콘텐츠의 첫 번째 비어 있지 않은 줄을 사용합니다. 주요 사용 사례를 먼저 입력하세요. 결합된 `description` 및 `when_to_use` 텍스트는 컨텍스트 사용을 줄이기 위해 스킬 목록에서 1,536자로 잘립니다. |

361| `when_to_use` | 아니요 | Claude가 스킬을 호출해야 할 때에 대한 추가 컨텍스트입니다. 예를 들어 트리거 구문이나 예제 요청입니다. 스킬 목록의 `description`에 추가되며 1,536자 제한에 포함됩니다. |401| `when_to_use` | 아니요 | Claude가 스킬을 호출해야 할 때에 대한 추가 컨텍스트입니다. 예를 들어 트리거 구문이나 예제 요청입니다. 스킬 목록의 `description`에 추가되며 1,536자 제한에 포함됩니다. |

362| `argument-hint` | 아니요 | 자동 완성 중에 표시되는 힌트로 예상 인수를 나타냅니다. 예: `[issue-number]` 또는 `[filename] [format]`. |402| `argument-hint` | 아니요 | 자동 완성 중에 표시되는 힌트로 예상 인수를 나타냅니다. 예: `[issue-number]` 또는 `[filename] [format]`. |

385 425

386| 배포 경로 | 사용할 수 있는 프론트매터 필드 |426| 배포 경로 | 사용할 수 있는 프론트매터 필드 |

387| :- | :- |427| :- | :- |

388| [모든 수준](#where-skills-live)의 Claude Code 스킬(예: [플러그인](/docs/ko/plugins) 스킬 포함) | 위 표의 모든 필드 |428| [모든 수준](#where-skills-live)의 Claude Code 스킬([플러그인](/docs/ko/plugins/overview) 스킬 포함) | 위 표의 모든 필드 |

389| claude.ai 스킬 업로드, Skills API, [anthropics/skills](https://github.com/anthropics/skills)의 `package_skill.py`로 패키징 | `name`, `description`, `license`, `compatibility`, `metadata`, `allowed-tools` |429| claude.ai 스킬 업로드, Skills API, [anthropics/skills](https://github.com/anthropics/skills)의 `package_skill.py`로 패키징 | `name`, `description`, `license`, `compatibility`, `metadata`, `allowed-tools` |

390 430

391[Cowork 및 클라우드 세션](#skills-in-cowork-and-cloud-sessions)(루틴 포함)에 대해 개인 스킬을 활성화하면 claude.ai에 업로드되므로 동일한 규칙이 적용됩니다.431[Cowork 및 클라우드 세션](#skills-in-cowork-and-cloud-sessions)(루틴 포함)에 대해 개인 스킬을 활성화하면 claude.ai에 업로드되므로 동일한 규칙이 적용됩니다.

402 스킬이 명령 이름을 얻는 방법442 스킬이 명령 이름을 얻는 방법

403</h4>443</h4>

404 444

405스킬을 호출하기 위해 입력하는 명령은 스킬 파일이 있는 위치와 플러그인 스킬의 경우 프론트매터 `name` 필드에서 나옵니다. 개인 또는 프로젝트 스킬에서 `name`은 스킬 목록에 표시되는 표시 레이블만 설정하고 명령은 여전히 디렉토리 이름에서 나옵니다. 플러그인 스킬에서 `name`은 명령의 마지막 세그먼트를 설정하고 플러그인 접두사는 제자리에 유지됩니다.445스킬을 호출하기 위해 입력하는 명령은 스킬 파일이 있는 위치에서 나오며, 스킬 디렉터리와 플러그인 스킬의 경우 frontmatter `name` 필드에서도 나옵니다. 개인 또는 프로젝트 스킬 디렉터리에서 `name`은 다른 명령이 이미 해당 이름을 사용하지 않는 한 `/` 메뉴에 표시되고 입력하는 명령을 설정합니다. 디렉터리 이름으로도 스킬을 호출할 수 있습니다. 플러그인 스킬에서 `name`은 명령의 마지막 세그먼트를 설정하고 플러그인 접두사는 제자리에 유지됩니다.

406 446

407아래 표는 각 레이아웃에 대해 명령 이름이 어디에서 나오는지 보여줍니다.447아래 표는 각 레이아웃에 대해 명령 이름이 어디에서 나오는지 보여줍니다.

408 448

409| 스킬 위치 | 명령 이름 소스 | 예제 |449| 스킬 위치 | 명령 이름 소스 | 예제 |

410| :- | :- | :- |450| :- | :- | :- |

412| [중첩된](#where-skills-live) `.claude/skills/` 디렉토리(이름이 다른 스킬과 충돌할 때) | 작업 디렉토리를 기준으로 한 서브디렉토리 경로, 그 다음 스킬 디렉토리 이름 | `apps/web/.claude/skills/deploy/SKILL.md` → `/apps/web:deploy` |452| [중첩된](#where-skills-live) `.claude/skills/` 디렉터리(디렉터리 이름이 다른 스킬과 충돌할 때) | 작업 디렉터리를 기준으로 한 서브디렉터리 경로, 그 다음 스킬 디렉터리 이름 | `apps/web/.claude/skills/deploy/SKILL.md` → `/apps/web:deploy` |

414| `.claude/commands/`의 서브디렉토리 아래의 파일 | `commands/`를 기준으로 한 서브디렉토리 경로(각 `/`를 `:`로 대체), 그 다음 확장자 없는 파일 이름 | `.claude/commands/frontend/component.md` → `/frontend:component` |454| `.claude/commands/`의 서브디렉토리 아래의 파일 | `commands/`를 기준으로 한 서브디렉토리 경로(각 `/`를 `:`로 대체), 그 다음 확장자 없는 파일 이름 | `.claude/commands/frontend/component.md` → `/frontend:component` |

415| 플러그인 `skills/` 서브디렉토리 | 프론트매터 `name` 또는 디렉토리 이름(플러그인으로 네임스페이스됨) | `my-plugin/skills/review/SKILL.md` → `/my-plugin:review`, 또는 `name: fancy`를 사용하면 `/my-plugin:fancy` |455| 플러그인 `skills/` 서브디렉토리 | 프론트매터 `name` 또는 디렉토리 이름(플러그인으로 네임스페이스됨) | `my-plugin/skills/review/SKILL.md` → `/my-plugin:review`, 또는 `name: fancy`를 사용하면 `/my-plugin:fancy` |

416| 플러그인 루트 `SKILL.md` | 프론트매터 `name`(플러그인 디렉토리 이름이 폴백) | `my-plugin/SKILL.md`에서 `name: review` → `/my-plugin:review`. [경로 동작 규칙](/docs/ko/plugins-reference#path-behavior-rules)을 참조하세요. |456| 플러그인 루트 `SKILL.md` | frontmatter `name`(플러그인 디렉터리 이름이 폴백) | `my-plugin/SKILL.md`에서 `name: review` → `/my-plugin:review`. [플러그인 루트의 단일 스킬](/docs/ko/plugins/components#skills)을 참조하세요. |

417| [claude.ai에서 동기화된](#how-synced-skills-behave) 스킬 | claude.ai 계정의 스킬 이름(접두사 `anthropic-skills:`) | 계정 스킬 `deploy` → `/anthropic-skills:deploy`, 또는 다른 명령이 해당 이름을 사용하지 않으면 `/deploy` |457| [claude.ai에서 동기화된](#how-synced-skills-behave) 스킬 | claude.ai 계정의 스킬 이름(접두사 `anthropic-skills:`) | 계정 스킬 `deploy` → `/anthropic-skills:deploy`, 또는 다른 명령이 해당 이름을 사용하지 않으면 `/deploy` |

418 458

419플러그인 스킬에서 프론트매터 `name`은 명령의 마지막 세그먼트에서 디렉토리 이름을 대체하므로 `my-plugin/skills/review/SKILL.md`에서 `name: fancy`는 `/my-plugin:fancy`가 됩니다. 다른 명령이 이미 해당 이름을 사용하지 않으면 `/fancy`도 스킬을 호출합니다. 작성한 `name`이 이미 플러그인 자체의 접두사로 시작하면 v2.1.246 이상에서 Claude Code는 접두사를 다시 추가하지 않습니다. 예를 들어 `name: my-plugin:fancy`는 여전히 `/my-plugin:fancy`가 됩니다. v2.1.216부터 v2.1.245까지 Claude Code는 `name`이 이미 접두사를 가지고 있을 때 접두사를 두 배로 했습니다.459플러그인 스킬에서 프론트매터 `name`은 명령의 마지막 세그먼트에서 디렉토리 이름을 대체하므로 `my-plugin/skills/review/SKILL.md`에서 `name: fancy`는 `/my-plugin:fancy`가 됩니다. 다른 명령이 이미 해당 이름을 사용하지 않으면 `/fancy`도 스킬을 호출합니다. 작성한 `name`이 이미 플러그인 자체의 접두사로 시작하면 v2.1.246 이상에서 Claude Code는 접두사를 다시 추가하지 않습니다. 예를 들어 `name: my-plugin:fancy`는 여전히 `/my-plugin:fancy`가 됩니다. v2.1.216부터 v2.1.245까지 Claude Code는 `name`이 이미 접두사를 가지고 있을 때 접두사를 두 배로 했습니다.

435| `$N` | `$0`(첫 번째 인수) 또는 `$1`(두 번째 인수)과 같이 `$ARGUMENTS[N]`의 약자입니다. |475| `$N` | `$0`(첫 번째 인수) 또는 `$1`(두 번째 인수)과 같이 `$ARGUMENTS[N]`의 약자입니다. |

436| `$name` | [`arguments`](#frontmatter-reference) 프론트매터 목록에 선언된 명명된 인수입니다. 이름은 순서대로 위치에 매핑되므로 `arguments: [issue, branch]`를 사용하면 플레이스홀더 `$issue`는 첫 번째 인수로 확장되고 `$branch`는 두 번째 인수로 확장됩니다. |476| `$name` | [`arguments`](#frontmatter-reference) 프론트매터 목록에 선언된 명명된 인수입니다. 이름은 순서대로 위치에 매핑되므로 `arguments: [issue, branch]`를 사용하면 플레이스홀더 `$issue`는 첫 번째 인수로 확장되고 `$branch`는 두 번째 인수로 확장됩니다. |

437| `${CLAUDE_SESSION_ID}` | 현재 세션 ID입니다. 로깅, 세션별 파일 생성 또는 스킬 출력을 세션과 연관시키는 데 유용합니다. |477| `${CLAUDE_SESSION_ID}` | 현재 세션 ID입니다. 로깅, 세션별 파일 생성 또는 스킬 출력을 세션과 연관시키는 데 유용합니다. |

438| `${CLAUDE_EFFORT}` | 현재 노력 수준: `low`, `medium`, `high`, `xhigh`, 또는 `max`. Ultracode는 별개의 수준이 아니며 `xhigh`로 보고됩니다. 이를 사용하여 활성 노력 설정에 스킬 지침을 조정합니다. |478| `${CLAUDE_EFFORT}` | 현재 effort 수준: `low`, `medium`, `high`, `xhigh`, 또는 `max`. 이를 사용하여 활성 effort 설정에 스킬 지침을 조정합니다. |

439| `${CLAUDE_SKILL_DIR}` | 스킬의 `SKILL.md` 파일을 포함하는 디렉토리입니다. 플러그인 스킬의 경우 플러그인 루트가 아닌 플러그인 내 스킬의 서브디렉토리입니다. 현재 작업 디렉토리와 관계없이 스킬과 함께 번들된 스크립트 또는 파일을 참조하려면 bash 주입 명령에서 사용합니다. |479| `${CLAUDE_SKILL_DIR}` | 스킬의 `SKILL.md` 파일을 포함하는 디렉토리입니다. 플러그인 스킬의 경우 플러그인 루트가 아닌 플러그인 내 스킬의 서브디렉토리입니다. 현재 작업 디렉토리와 관계없이 스킬과 함께 번들된 스크립트 또는 파일을 참조하려면 bash 주입 명령에서 사용합니다. |

440| `${CLAUDE_PROJECT_DIR}` | 프로젝트 루트 디렉토리입니다. 이는 [훅](/docs/ko/hooks#reference-scripts-by-path) 및 MCP 서버가 `CLAUDE_PROJECT_DIR`로 받는 동일한 경로입니다. 스킬이 설치된 위치와 관계없이 프로젝트 로컬 스크립트 또는 파일(예: `${CLAUDE_PROJECT_DIR}/.claude/hooks/helper.sh`)을 참조하려면 사용합니다. |480| `${CLAUDE_PROJECT_DIR}` | 프로젝트 루트 디렉토리입니다. 이는 [훅](/docs/ko/hooks#reference-scripts-by-path) 및 MCP 서버가 `CLAUDE_PROJECT_DIR`로 받는 동일한 경로입니다. 스킬이 설치된 위치와 관계없이 프로젝트 로컬 스크립트 또는 파일(예: `${CLAUDE_PROJECT_DIR}/.claude/hooks/helper.sh`)을 참조하려면 사용합니다. |

441| `${CLAUDE_PLUGIN_ROOT}` | 플러그인의 설치 디렉토리입니다. 플러그인 스킬에서만 치환됩니다. 플러그인의 스킬 간에 공유되는 리소스를 포함하여 플러그인의 어디에나 번들된 스크립트 또는 파일을 참조하려면 사용합니다. [플러그인 환경 변수](/docs/ko/plugins-reference#environment-variables)를 참조하세요. |481| `${CLAUDE_PLUGIN_ROOT}` | 플러그인의 설치 디렉터리입니다. 플러그인 스킬에서만 치환됩니다. 플러그인의 스킬 간에 공유되는 리소스를 포함하여 플러그인의 어디에나 번들된 스크립트 또는 파일을 참조하려면 사용합니다. [플러그인 환경 변수](/docs/ko/plugins/manifest-reference#environment-variables)를 참조하세요. |

442| `${CLAUDE_PLUGIN_DATA}` | 플러그인의 [지속적인 데이터 디렉토리](/docs/ko/plugins-reference#persistent-data-directory)로, 플러그인 업데이트를 통해 유지됩니다. 플러그인 스킬에서만 치환됩니다. 설치된 종속성, 생성된 파일 또는 업데이트를 초과해야 하는 캐시를 참조하려면 사용합니다. |482| `${CLAUDE_PLUGIN_DATA}` | 플러그인의 [지속적인 데이터 디렉터리](/docs/ko/plugins/components#path-variables-and-persistent-data)로, 플러그인 업데이트 후에도 유지됩니다. 플러그인 스킬에서만 치환됩니다. 설치된 의존성, 생성된 파일 또는 업데이트 이후에도 유지되어야 하는 캐시를 참조하려면 사용합니다. |

443 483

444Claude Code는 `${CLAUDE_SKILL_DIR}` 및 `${CLAUDE_PROJECT_DIR}`을 두 위치에서 치환합니다. 스킬의 마크다운 콘텐츠 및 [`allowed-tools`](#frontmatter-reference) 프론트매터의 Bash 규칙입니다. 플러그인 스킬에서 Claude Code는 `${CLAUDE_PLUGIN_ROOT}` 및 `${CLAUDE_PLUGIN_DATA}`를 동일한 두 위치에서 치환합니다. 두 위치에서 동일한 변수를 사용하면 스킬이 권한 프롬프트 없이 번들된 스크립트를 실행할 수 있습니다. 다음 스킬은 패턴을 보여줍니다.484Claude Code는 `${CLAUDE_SKILL_DIR}` 및 `${CLAUDE_PROJECT_DIR}`을 두 위치에서 치환합니다. 스킬의 마크다운 콘텐츠 및 [`allowed-tools`](#frontmatter-reference) 프론트매터의 Bash 규칙입니다. 플러그인 스킬에서 Claude Code는 `${CLAUDE_PLUGIN_ROOT}` 및 `${CLAUDE_PLUGIN_DATA}`를 동일한 두 위치에서 치환합니다. 두 위치에서 동일한 변수를 사용하면 스킬이 권한 프롬프트 없이 번들된 스크립트를 실행할 수 있습니다. 다음 스킬은 패턴을 보여줍니다.

445 485

555 595

556[자동 압축](/docs/ko/how-claude-code-works#when-context-fills-up)은 토큰 예산 내에서 호출된 스킬을 전달합니다. 대화가 컨텍스트를 확보하기 위해 요약될 때 Claude Code는 각 스킬의 처음 5,000토큰을 유지하면서 가장 최근의 각 스킬 호출을 다시 첨부합니다. 다시 첨부된 스킬은 25,000토큰의 결합 예산을 공유합니다. Claude Code는 가장 최근에 호출된 스킬부터 시작하여 이 예산을 채우므로 한 세션에서 많은 스킬을 호출한 경우 압축 후 이전 스킬이 완전히 삭제될 수 있습니다.596[자동 압축](/docs/ko/how-claude-code-works#when-context-fills-up)은 토큰 예산 내에서 호출된 스킬을 전달합니다. 대화가 컨텍스트를 확보하기 위해 요약될 때 Claude Code는 각 스킬의 처음 5,000토큰을 유지하면서 가장 최근의 각 스킬 호출을 다시 첨부합니다. 다시 첨부된 스킬은 25,000토큰의 결합 예산을 공유합니다. Claude Code는 가장 최근에 호출된 스킬부터 시작하여 이 예산을 채우므로 한 세션에서 많은 스킬을 호출한 경우 압축 후 이전 스킬이 완전히 삭제될 수 있습니다.

557 597

558스킬이 첫 번째 응답 후 동작에 영향을 미치지 않는 것처럼 보이면 콘텐츠는 일반적으로 여전히 존재하며 모델이 다른 도구나 접근 방식을 선택하고 있습니다. 스킬의 `description` 및 지침을 강화하여 모델이 계속 선호하도록 하거나 [훅](/docs/ko/hooks)을 사용하여 동작을 결정론적으로 적용합니다. 스킬이 크거나 그 후에 다른 스킬을 많이 호출한 경우 압축 후 다시 호출하여 전체 콘텐츠를 복원합니다.598세션 도중에 Claude가 스킬을 따르지 않게 되면 [Claude가 스킬을 따르지 않음](#claude-stops-following-a-skill)을 참조하세요.

559 599

560<h3 id="pre-approve-tools-for-a-skill">600<h3 id="pre-approve-tools-for-a-skill">

561 스킬에 대한 도구 사전 승인601 스킬에 대한 도구 사전 승인

700 740

701* **작업 디렉토리**: Claude Code는 각 명령을 세션 셸의 현재 작업 디렉토리에서 실행합니다. Claude가 `cd`를 실행할 때 해당 디렉토리가 이동합니다. 매번 동일하게 확인되어야 하는 경로에서 [`${CLAUDE_SKILL_DIR}` 또는 `${CLAUDE_PROJECT_DIR}`](#available-string-substitutions)을 사용합니다.741* **작업 디렉토리**: Claude Code는 각 명령을 세션 셸의 현재 작업 디렉토리에서 실행합니다. Claude가 `cd`를 실행할 때 해당 디렉토리가 이동합니다. 매번 동일하게 확인되어야 하는 경로에서 [`${CLAUDE_SKILL_DIR}` 또는 `${CLAUDE_PROJECT_DIR}`](#available-string-substitutions)을 사용합니다.

702* **stderr**: 기본 `bash` 셸을 사용하면 Claude Code는 stderr를 stdout으로 병합합니다. 명령이 stderr에 쓰는 모든 것이 주입된 텍스트에 나타납니다.742* **stderr**: 기본 `bash` 셸을 사용하면 Claude Code는 stderr를 stdout으로 병합합니다. 명령이 stderr에 쓰는 모든 것이 주입된 텍스트에 나타납니다.

703* **타임아웃**: 각 명령은 Bash 도구의 기본 2분 [타임아웃](/docs/ko/tools-reference#timeout-and-output-limits) 아래에서 실행됩니다. Bash 도구가 [시간 초과된 명령을 백그라운드로 이동](/docs/ko/tools-reference#background-commands)할 때 스킬은 여전히 렌더링됩니다. 주입된 텍스트는 이동을 보고하고 백그라운드 작업과 명령의 출력을 수집하는 파일의 이름을 지정합니다. 명령이 Bash 도구가 절대 자동으로 백그라운드하지 않는 명령인 경우 Claude Code는 타임아웃에서 이를 종료합니다. 이 실패는 [호출을 중단합니다](#when-an-injected-command-fails).743* **타임아웃**: 각 명령은 Bash 도구의 기본 2분 [타임아웃](/docs/ko/tools-reference#timeout-and-output-limits) 아래에서 실행됩니다. Bash 도구가 [시간 초과된 명령을 백그라운드로 이동](/docs/ko/tools-reference#foreground-commands-that-move-to-the-background)할 때 스킬은 여전히 렌더링됩니다. 주입된 텍스트는 이동을 보고하고 백그라운드 작업과 명령의 출력을 수집하는 파일의 이름을 지정합니다. 명령이 Bash 도구가 절대 자동으로 백그라운드하지 않는 명령인 경우 Claude Code는 타임아웃에서 이를 종료합니다. 이 실패는 [호출을 중단합니다](#when-an-injected-command-fails).

704* **출력 크기**: Bash 도구의 인라인 상한을 초과하는 출력은 잘린 텍스트가 아닌 파일 경로와 짧은 미리보기로 도착합니다. [출력 제한](/docs/ko/tools-reference#output-limits)은 상한과 각 경계를 조정하는 방법을 다룹니다.744* **출력 크기**: Bash 도구의 인라인 상한을 초과하는 출력은 잘린 텍스트가 아닌 파일 경로와 짧은 미리보기로 도착합니다. [출력 제한](/docs/ko/tools-reference#output-limits)은 상한과 각 경계를 조정하는 방법을 다룹니다.

705 745

706PowerShell 도구는 실행하는 명령에 동일한 타임아웃, 백그라운드 처리 및 출력 상한 동작을 적용합니다. 해당 세부 사항은 [PowerShell 도구](/docs/ko/tools-reference#powershell-tool) 섹션을 참조합니다.746PowerShell 도구는 실행하는 명령에 동일한 타임아웃, 백그라운드 처리 및 출력 상한 동작을 적용합니다. 해당 세부 사항은 [PowerShell 도구](/docs/ko/tools-reference#powershell-tool) 섹션을 참조합니다.

790이 스킬이 실행될 때:830이 스킬이 실행될 때:

791 831

7921. 새로운 격리된 컨텍스트가 생성됩니다8321. 새로운 격리된 컨텍스트가 생성됩니다

7932. 서브에이전트는 스킬 콘텐츠를 프롬프트로 받습니다 ("Research \$ARGUMENTS thoroughly...")8332. 서브에이전트는 스킬 콘텐츠를 프롬프트로 받습니다 ("Research \$ARGUMENTS thoroughly" 지침)

7943. `agent` 필드는 실행 환경 (모델, 도구 및 권한)을 결정합니다8343. `agent` 필드는 실행 환경 (모델, 도구 및 권한)을 결정합니다

7954. 서브에이전트는 결과를 요약하고 완료되면 주 대화에 반환합니다8354. 서브에이전트는 결과를 요약하고 완료되면 주 대화에 반환합니다

796 836

824 864

825권한 구문: 정확한 일치의 경우 `Skill(name)`, 모든 인수를 사용한 접두사 일치의 경우 `Skill(name *)`.865권한 구문: 정확한 일치의 경우 `Skill(name)`, 모든 인수를 사용한 접두사 일치의 경우 `Skill(name *)`.

826 866

827`deny` 규칙이 스킬의 자체 이름이 아닌 별칭 또는 정규화되지 않은 이름을 지정하면 Claude Code는 여전히 스킬을 차단합니다: `Skill(review)`를 사용하면 번들된 `/code-review`를 `/review` 별칭을 통해 차단하고, `Skill(deploy)`를 사용하면 [중첩된 스킬](#where-skills-live)을 `apps/web:deploy`로 나열된 정규화되지 않은 이름을 통해 차단합니다. v2.1.260 이전에는 Claude Code가 deny 규칙이 정규화되지 않은 이름만 지정할 때 정규화된 이름 아래에 나열된 중첩된 스킬을 차단하지 않았습니다.867아래 표는 규칙에 사용된 이름의 종류별로 `deny` 규칙이 작성한 이름 외에 추가로 차단하는 대상을 보여 줍니다.

828 868

829Claude Code는 `allow` 규칙을 스킬의 자체 이름과 Claude의 호출에서의 이름에 대해서만 일치시킵니다.869| `deny` 규칙에 지정한 이름 | 규칙 예시 | Claude Code가 추가로 차단하는 대상 |

870| :- | :- | :- |

871| 별칭 | `Skill(review)` | `/review` 별칭을 통한 번들 `/code-review` |

872| 정규화되지 않은 이름 | `Skill(deploy)` | `apps/web:deploy`로 나열된 [중첩된 스킬](#where-skills-live) |

873| [claude.ai에서 동기화된 스킬](#how-synced-skills-behave) | `Skill(anthropic-skills:deploy)` | Claude Desktop이 해당 스킬을 플러그인으로 세션에 전달할 때의 그 스킬 |

874| 동기화된 스킬의 플러그인 형식 | `Skill(deploy:deploy)` | 동기화된 스킬 |

875| [매개변수 형식](/docs/ko/permissions#match-by-input-parameter)의 스킬 | `Skill(skill:deploy)` | Claude가 별칭과 표시 이름을 포함하여 어떤 이름으로 호출하든 해당 스킬 |

876

877v2.1.260 이전에는 Claude Code가 deny 규칙이 정규화되지 않은 이름만 지정할 때 정규화된 이름 아래에 나열된 중첩된 스킬을 차단하지 않았습니다.

878

879Claude Code는 `allow` 규칙을 스킬의 자체 이름과 Claude의 호출에서의 이름에 대해서만 일치시킵니다. [동기화된 스킬](#how-synced-skills-behave)을 확인 요청 없이 승인하려면 [예약된 네임스페이스](#names-reserved-for-synced-skills) 안에서 이름을 지정합니다:

880

881* `Skill(anthropic-skills:pdf)`는 동기화된 `pdf` 스킬을 승인합니다

882* `Skill(anthropic-skills *)`는 모든 동기화된 스킬을 승인합니다

883* `Skill(anthropic *)`는 `anthropic-skills:pdf`를 포함하지 않습니다. 네임스페이스 외부의 접두사는 그 안의 이름과 일치하지 않기 때문입니다

830 884

831**프론트매터에 `disable-model-invocation: true`를 추가하여 개별 스킬 숨기기**. 이는 Claude의 컨텍스트에서 스킬을 제거합니다.885**프론트매터에 `disable-model-invocation: true`를 추가하여 개별 스킬 숨기기**. 이는 Claude의 컨텍스트에서 스킬을 제거합니다.

832 886

886 940

887스킬이 트리거되는 것을 보는 것은 Claude가 스킬을 찾았다는 의미이지, 의도한 대로 작동했다는 의미는 아닙니다. 스킬이 제대로 작동하는지 알기 위해서는 두 가지를 별도로 측정해야 합니다. Claude가 해야 할 프롬프트에서 스킬을 호출하는지 여부와 호출할 때 출력이 예상과 일치하는지 여부입니다.941스킬이 트리거되는 것을 보는 것은 Claude가 스킬을 찾았다는 의미이지, 의도한 대로 작동했다는 의미는 아닙니다. 스킬이 제대로 작동하는지 알기 위해서는 두 가지를 별도로 측정해야 합니다. Claude가 해야 할 프롬프트에서 스킬을 호출하는지 여부와 호출할 때 출력이 예상과 일치하는지 여부입니다.

888 942

889두 가지 모두에 대한 확인은 기준선 비교입니다. 현실적인 프롬프트 몇 개를 수집하고, 스킬을 사용할 수 있는 새로운 세션에서 각각을 실행한 후 [비활성화](#override-skill-visibility-from-settings)된 상태에서 다시 실행하고 결과를 비교합니다. 새로운 세션이 중요한 이유는 스킬 작성 시 남겨진 컨텍스트가 작성된 지침의 간격을 숨길 수 있기 때문입니다.943두 가지 모두에 대한 확인은 기준선 비교입니다. 현실적인 프롬프트 몇 개를 수집하고, 스킬을 사용할 수 있는 새로운 세션에서 각각을 실행한 후 스킬을 끈 상태에서 다시 실행하고 결과를 비교합니다. 새로운 세션이 중요한 이유는 스킬 작성 시 남겨진 컨텍스트가 작성된 지침의 간격을 숨길 수 있기 때문입니다.

890 944

891두 가지 도구가 해당 비교를 자동화합니다. [플러그인](/docs/ko/plugins)에서 제공되는 스킬의 경우, [`claude plugin eval`](/docs/ko/plugin-evals)은 플러그인을 사용하는 경우와 사용하지 않는 경우 각 프롬프트를 격리된 세션에서 실행하고, 정의한 또는 자동으로 작성된 채점자로 점수를 매기며, 임계값 이하에서 0이 아닌 값으로 종료하여 CI에서 이를 제어할 수 있습니다. Claude Code 대화 내에서 단일 스킬을 반복하는 경우, 아래의 스킬 생성자 플러그인은 자체 `evals/evals.json` 형식으로 유사한 루프를 실행합니다. 두 형식은 상호 교환할 수 없습니다.945두 번째 실행을 위해 스킬을 끄는 방법은 스킬의 출처에 따라 다릅니다:

946

947* **개인 또는 프로젝트 스킬**: [`skillOverrides`](#override-skill-visibility-from-settings)에서 `"off"`로 설정합니다.

948* **플러그인이 제공하는 스킬**: `skillOverrides`는 플러그인 스킬에 적용되지 않습니다. 대신 플러그인을 로드하지 않은 상태로 각 실행을 반복하는 [`claude plugin eval`](/docs/ko/plugin-evals#the-no-plugin-baseline)을 사용합니다.

949

950두 가지 도구가 기준선 비교를 자동화합니다. [플러그인](/docs/ko/plugins/overview)에 포함되어 배포되는 스킬의 경우, [`claude plugin eval`](/docs/ko/plugin-evals)은 플러그인을 사용하는 경우와 사용하지 않는 경우 각 프롬프트를 격리된 세션에서 실행하고, 정의한 또는 자동으로 작성된 채점자로 점수를 매기며, 임계값 이하에서 0이 아닌 값으로 종료하여 CI에서 이를 제어할 수 있습니다. Claude Code 대화 내에서 단일 스킬을 반복하는 경우, 아래의 스킬 생성자 플러그인은 자체 `evals/evals.json` 형식으로 유사한 루프를 실행합니다. 두 형식은 상호 교환할 수 없습니다.

892 951

893<h3 id="run-evals-with-skill-creator">952<h3 id="run-evals-with-skill-creator">

894 skill-creator로 평가 실행953 skill-creator로 평가 실행

903설치가 실패하면 Claude Code가 보고한 메시지와 일치시킵니다:962설치가 실패하면 Claude Code가 보고한 메시지와 일치시킵니다:

904 963

905* `Marketplace "claude-plugins-official" not found`: `/plugin marketplace add anthropics/claude-plugins-official`로 마켓플레이스를 추가한 후 설치를 다시 시도합니다.964* `Marketplace "claude-plugins-official" not found`: `/plugin marketplace add anthropics/claude-plugins-official`로 마켓플레이스를 추가한 후 설치를 다시 시도합니다.

906* 플러그인이 [마켓플레이스에서 찾을 수 없음](/docs/ko/discover-plugins#install-plugins): 플러그인 이름을 확인합니다.965* 플러그인이 [마켓플레이스에서 찾을 수 없음](/docs/ko/plugins/install#install-a-plugin): 플러그인 이름을 확인합니다.

907 966

908설치 요약에서 `Run /reload-plugins to activate.`를 보고하면 Claude Code가 해당 재로드를 실행합니다. 재로드 시 다음 메시지가 대화를 다시 읽을 것이라는 경고가 표시되면 `/reload-plugins --force`를 실행하여 현재 세션에서 플러그인의 스킬을 사용할 수 있게 합니다. 그런 다음 Claude에게 기존 스킬을 평가하도록 요청합니다. 예를 들어 `evaluate my summarize-changes skill with skill-creator`입니다. 플러그인은 테스트 케이스 작성을 안내하고 루프를 실행합니다:967설치 요약에서 `Run /reload-plugins to activate.`를 보고하면 Claude Code가 해당 재로드를 실행합니다. 재로드 시 다음 메시지가 대화를 다시 읽을 것이라는 경고가 표시되면 `/reload-plugins --force`를 실행하여 현재 세션에서 플러그인의 스킬을 사용할 수 있게 합니다. 그런 다음 Claude에게 기존 스킬을 평가하도록 요청합니다. 예를 들어 `evaluate my summarize-changes skill with skill-creator`입니다. 플러그인은 테스트 케이스 작성을 안내하고 루프를 실행합니다:

909 968

924스킬은 대상에 따라 다양한 범위에서 배포할 수 있습니다:983스킬은 대상에 따라 다양한 범위에서 배포할 수 있습니다:

925 984

926* **프로젝트 스킬**: `.claude/skills/`를 버전 관리에 커밋합니다985* **프로젝트 스킬**: `.claude/skills/`를 버전 관리에 커밋합니다

927* **플러그인**: [플러그인](/docs/ko/plugins)에서 `skills/` 디렉토리를 생성합니다986* **플러그인**: [플러그인](/docs/ko/plugins/overview)에서 `skills/` 디렉토리를 생성합니다

928* **관리형**: [관리형 설정](/docs/ko/managed-settings)을 통해 조직 전체에 배포합니다987* **관리형**: [관리형 설정](/docs/ko/managed-settings)을 통해 조직 전체에 배포합니다

929 988

930<h3 id="generate-visual-output">989<h3 id="generate-visual-output">

1139 1198

1140스킬이 플러그인에 포함되어 있으면 한 번에 하나씩 확인하는 대신 현실적인 프롬프트에서 얼마나 자주 트리거되는지 측정할 수 있습니다. [`tool_used: Skill` grader](/docs/ko/plugin-evals#create-your-first-eval-suite)를 사용하여 eval 케이스를 작성하고 각 설명 변경 후 `claude plugin eval`로 실행하세요.1199스킬이 플러그인에 포함되어 있으면 한 번에 하나씩 확인하는 대신 현실적인 프롬프트에서 얼마나 자주 트리거되는지 측정할 수 있습니다. [`tool_used: Skill` grader](/docs/ko/plugin-evals#create-your-first-eval-suite)를 사용하여 eval 케이스를 작성하고 각 설명 변경 후 `claude plugin eval`로 실행하세요.

1141 1200

1142frontmatter가 파싱되지 않는 `SKILL.md` 파일을 찾으려면 스킬 디렉토리에서 [`claude plugin validate`](/docs/ko/plugin-marketplaces#validate-a-plugin-or-a-directory-without-a-manifest)를 실행하세요. 예를 들어 프로젝트 스킬의 경우 `claude plugin validate .claude/skills` 또는 개인 스킬의 경우 `claude plugin validate ~/.claude/skills`입니다. Claude Code v2.1.233 이상이 필요합니다.1201frontmatter가 파싱되지 않는 `SKILL.md` 파일을 찾으려면 스킬 디렉토리에서 [`claude plugin validate`](/docs/ko/plugins/cli-reference#validate-a-directory)를 실행하세요. 예를 들어 프로젝트 스킬의 경우 `claude plugin validate .claude/skills` 또는 개인 스킬의 경우 `claude plugin validate ~/.claude/skills`입니다. Claude Code v2.1.233 이상이 필요합니다.

1143 1202

1144<h3 id="skill-triggers-too-often">1203<h3 id="skill-triggers-too-often">

1145 스킬이 너무 자주 트리거됨1204 스킬이 너무 자주 트리거됨

11501. 설명을 더 구체적으로 만드세요12091. 설명을 더 구체적으로 만드세요

11512. 수동 호출만 원하는 경우 `disable-model-invocation: true`를 추가하세요12102. 수동 호출만 원하는 경우 `disable-model-invocation: true`를 추가하세요

1152 1211

1212<h3 id="claude-stops-following-a-skill">

1213 Claude가 스킬을 따르지 않게 됨

1214</h3>

1215

1216Claude가 첫 번째 응답에서는 스킬을 따르다가 이후에 따르지 않게 되면, 다음 중 해당하는 경우부터 확인하세요:

1217

1218* **Claude가 매번 지켜져야 하는 규칙을 건너뛴 경우**: 규칙을 [훅](/docs/ko/hooks-guide)으로 옮기세요. Claude Code는 각 파일 편집 전과 같이 해당 이벤트가 발생할 때마다 Claude가 스킬을 따르고 있는지와 관계없이 훅을 실행합니다. 규칙을 스킬과 함께 유지하려면 스킬의 [`hooks` frontmatter](/docs/ko/hooks#hooks-in-skills-and-agents)에 훅을 정의하세요. 해당 훅은 스킬이 호출된 시점부터 세션이 끝날 때까지 적용됩니다.

1219* **Claude가 판단에 따라 적용해야 하는 지침을 건너뛴 경우**: 지침이 전체 작업에 적용되도록 표현하세요. 예를 들어 "테스트를 실행하세요" 대신 "편집할 때마다 테스트를 실행하세요"와 같이 작성합니다. Claude Code는 스킬이 호출될 때 스킬의 내용을 대화에 추가하며 이후 턴에서 [파일을 다시 읽지 않습니다](#skill-content-lifecycle).

1220* **대화가 압축된 경우**: 스킬을 다시 호출하여 전체 내용을 복원하세요. [압축](/docs/ko/how-claude-code-works#when-context-fills-up) 후 Claude Code는 [호출된 스킬의 시작 부분만 유지할 수 있으므로](#skill-content-lifecycle) 가장 중요한 지침을 `SKILL.md` 상단 가까이에 배치하세요.

1221

1153<h3 id="skill-descriptions-are-cut-short">1222<h3 id="skill-descriptions-are-cut-short">

1154 스킬 설명이 잘려 있음1223 스킬 설명이 잘려 있음

1155</h3>1224</h3>

1156 1225

1157Claude Code는 스킬 이름과 설명 목록을 컨텍스트에 로드하여 Claude가 사용 가능한 항목을 알 수 있도록 합니다. 목록에는 항상 모든 스킬 이름이 포함되지만 스킬이 많으면 Claude Code는 목록의 문자 예산에 맞추기 위해 설명을 단축하므로 Claude가 요청과 일치시키는 데 필요한 키워드가 제거될 수 있습니다. 예산은 모델의 컨텍스트 윈도우의 1%로 조정됩니다. 목록이 초과되면 Claude Code는 가장 적게 호출하는 스킬부터 설명을 삭제하므로 가장 자주 사용하는 스킬이 전체 텍스트를 유지합니다.1226Claude Code는 스킬 이름과 설명 목록을 컨텍스트에 로드하여 Claude가 사용 가능한 항목을 알 수 있도록 합니다. 목록에는 항상 모든 스킬 이름이 포함되지만 스킬이 많으면 Claude Code는 목록의 문자 예산에 맞추기 위해 일부 설명을 삭제하며, 이로 인해 Claude가 요청과 일치시키는 데 필요한 키워드가 제거됩니다. 예산은 모델의 컨텍스트 윈도우의 1%로 조정됩니다. 목록이 초과되면 Claude Code는 가장 적게 호출하는 스킬부터 설명을 삭제하므로 가장 자주 사용하는 스킬이 전체 텍스트를 유지합니다.

1158 1227

1159목록의 컨텍스트 비용 추정치와 가장 큰 기여자를 보려면 `/doctor`를 실행하세요. 사용하지 않는 스킬을 찾으려면 [`/skill-doctor`](#find-unused-skills)를 실행하세요. 목록이 예산을 초과하면 Claude Code는 [`--debug`](/docs/ko/cli-reference#cli-flags)로 볼 수 있는 디버그 로그에 경고를 작성합니다.1228목록의 컨텍스트 비용 추정치와 가장 큰 기여자를 보려면 `/doctor`를 실행하세요. 사용하지 않는 스킬을 찾으려면 [`/skill-doctor`](#find-unused-skills)를 실행하세요. 목록이 예산을 초과하면 Claude Code는 [`--debug`](/docs/ko/cli-reference#cli-flags)로 볼 수 있는 디버그 로그에 경고를 작성합니다.

1160 1229

1162 1231

1163예산을 높이려면 [`skillListingBudgetFraction`](/docs/ko/settings-reference#skilllistingbudgetfraction) 설정(예: `0.02` = 2%) 또는 `SLASH_COMMAND_TOOL_CHAR_BUDGET` 환경 변수를 고정 문자 수로 설정하세요. 다른 스킬을 위해 예산을 확보하려면 [`skillOverrides`](#override-skill-visibility-from-settings)에서 낮은 우선순위 항목을 `"name-only"`로 설정하여 설명 없이 나열되도록 하세요. 또한 소스에서 `description` 및 `when_to_use` 텍스트를 자르세요. 각 항목의 결합된 텍스트는 예산에 관계없이 1,536자로 제한되므로 주요 사용 사례를 먼저 배치하세요. 상한은 [`skillListingMaxDescChars`](/docs/ko/settings-reference#skilllistingmaxdescchars)로 구성할 수 있습니다.1232예산을 높이려면 [`skillListingBudgetFraction`](/docs/ko/settings-reference#skilllistingbudgetfraction) 설정(예: `0.02` = 2%) 또는 `SLASH_COMMAND_TOOL_CHAR_BUDGET` 환경 변수를 고정 문자 수로 설정하세요. 다른 스킬을 위해 예산을 확보하려면 [`skillOverrides`](#override-skill-visibility-from-settings)에서 낮은 우선순위 항목을 `"name-only"`로 설정하여 설명 없이 나열되도록 하세요. 또한 소스에서 `description` 및 `when_to_use` 텍스트를 자르세요. 각 항목의 결합된 텍스트는 예산에 관계없이 1,536자로 제한되므로 주요 사용 사례를 먼저 배치하세요. 상한은 [`skillListingMaxDescChars`](/docs/ko/settings-reference#skilllistingmaxdescchars)로 구성할 수 있습니다.

1164 1233

1234<h3 id="personal-skills-disappeared">

1235 개인 스킬이 사라짐

1236</h3>

1237

1238`~/.claude/skills/`에 만든 스킬 폴더가 사라졌다면 `~/.claude/skills/.trash/`를 확인하세요. Claude Code가 [claude.ai에서 스킬을 동기화](#how-synced-skills-behave)할 때는 별도의 `synced` 하위 폴더로 다운로드하며, 사용자가 만든 폴더는 이동하거나 삭제하지 않습니다.

1239

1240v2.1.280 이전에는 `~/.claude/skills/`에 `manifest.json`이라는 파일이 있으면 Claude Code가 해당 파일에 나열된 스킬 폴더를 `~/.claude/skills/.trash/` 아래의 타임스탬프 폴더로 이동했으며, 해당 스킬은 더 이상 로드되지 않았습니다.

1241

1242스킬을 복원하려면 타임스탬프 폴더에서 해당 스킬 폴더를 `~/.claude/skills/`로 다시 옮기세요. [보존 정리](/docs/ko/claude-directory#cleaned-up-automatically)가 휴지통 항목을 삭제하기 전에 이 작업을 수행하세요. 기본적으로 휴지통 항목은 휴지통으로 이동된 후 30일이 지나면 삭제됩니다.

1243

1165<h2 id="related-resources">1244<h2 id="related-resources">

1166 관련 리소스1245 관련 리소스

1167</h2>1246</h2>

1170* **[Skill 출력 품질 평가](https://agentskills.io/skill-creation/evaluating-skills)**: agentskills.io의 eval 파일 형식 및 반복 워크플로우1249* **[Skill 출력 품질 평가](https://agentskills.io/skill-creation/evaluating-skills)**: agentskills.io의 eval 파일 형식 및 반복 워크플로우

1171* **[Skill 작성 모범 사례](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices)**: Claude 제품 전체에 적용되는 작성 지침1250* **[Skill 작성 모범 사례](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices)**: Claude 제품 전체에 적용되는 작성 지침

1172* **[Subagents](/docs/ko/sub-agents)**: 특화된 에이전트에 작업 위임1251* **[Subagents](/docs/ko/sub-agents)**: 특화된 에이전트에 작업 위임

1173* **[플러그인](/docs/ko/plugins)**: 다른 확장과 함께 skills 패키징 및 배포1252* **[플러그인](/docs/ko/plugins/overview)**: 다른 확장과 함께 스킬 패키징 및 배포

1174* **[Hooks](/docs/ko/hooks)**: 도구 이벤트 주변 워크플로우 자동화1253* **[Hooks](/docs/ko/hooks)**: 도구 이벤트 주변 워크플로우 자동화

1175* **[메모리](/docs/ko/memory)**: 지속적인 컨텍스트를 위한 CLAUDE.md 파일 관리1254* **[메모리](/docs/ko/memory)**: 지속적인 컨텍스트를 위한 CLAUDE.md 파일 관리

1176* **[명령어](/docs/ko/commands)**: 기본 제공 명령어 및 번들 skills 참조1255* **[명령어](/docs/ko/commands)**: 기본 제공 명령어 및 번들 skills 참조

troubleshoot-install.md +24 −10

Details

22| `curl: (23)` 또는 `curl: (56) Failure writing output to destination` | [연결성 확인 또는 대체 설치 프로그램 사용](#curl-56-failure-writing-output-to-destination) |22| `curl: (23)` 또는 `curl: (56) Failure writing output to destination` | [연결성 확인 또는 대체 설치 프로그램 사용](#curl-56-failure-writing-output-to-destination) |

23| Linux에서 설치 중 `Killed` 또는 `Installation was killed before it could finish (exit code 137)` | [메모리 확보 또는 스왑 공간 추가](#install-killed-on-low-memory-linux-servers) |23| Linux에서 설치 중 `Killed` 또는 `Installation was killed before it could finish (exit code 137)` | [메모리 확보 또는 스왑 공간 추가](#install-killed-on-low-memory-linux-servers) |

24| 설치 중 `Raw mode is not supported` | [설치 프로그램 다시 실행](#raw-mode-is-not-supported-during-install) |24| 설치 중 `Raw mode is not supported` | [설치 프로그램 다시 실행](#raw-mode-is-not-supported-during-install) |

25| 설치 중 `EACCES: permission denied` | [설치 디렉터리의 권한 수정](#permission-errors-during-installation) |

25| `TLS connect error` 또는 `SSL/TLS secure channel` | [CA 인증서 업데이트](#tls-or-ssl-connection-errors) |26| `TLS connect error` 또는 `SSL/TLS secure channel` | [CA 인증서 업데이트](#tls-or-ssl-connection-errors) |

26| `Failed to fetch version` 또는 다운로드 서버에 도달할 수 없음 | [네트워크 및 프록시 설정 확인](#check-network-connectivity) |27| `Failed to fetch version` 또는 다운로드 서버에 도달할 수 없음 | [네트워크 및 프록시 설정 확인](#check-network-connectivity) |

27| `irm is not recognized` 또는 `The token '&&' is not a valid statement separator` | [셸에 맞는 명령 사용](#wrong-install-command-on-windows) |28| `irm is not recognized` 또는 `The token '&&' is not a valid statement separator` | [셸에 맞는 명령 사용](#wrong-install-command-on-windows) |

295 디렉토리 권한 확인296 디렉토리 권한 확인

296</h3>297</h3>

297 298

298설치 프로그램은 macOS 및 Linux의 `~/.local/bin/` 및 `~/.claude/`에 대한 쓰기 액세스가 필요합니다. Windows에서 설치 위치는 `%USERPROFILE%` 아래에 있으며 기본적으로 사용자가 쓸 수 있으므로 이 섹션은 거의 적용되지 않습니다.299권한 문제로 실패한 설치는 생성하거나 쓸 수 없었던 경로를 표시합니다. Windows에서는 설치가 `%USERPROFILE%` 아래에 기록되며, 이 위치는 기본적으로 사용자가 쓸 수 있으므로 이 섹션은 거의 적용되지 않습니다.

300

301macOS 및 Linux에서는 설치가 다음 위치에 기록됩니다:

302

303* `~/.claude/downloads/`: 설치 명령이 다운로드한 바이너리를 두는 위치

304* `~/.local/bin/`: `claude` 런처

305* `~/.local/share/claude/`: 다운로드하는 각 버전

306* `~/.local/state/claude/`: 잠금 파일

307* `~/.cache/claude/`: 스테이징된 다운로드

308* [`~/.claude.json`](/docs/ko/claude-directory): 설치 프로그램이 설치 방법을 기록하는 전역 설정 파일

309

310`XDG_DATA_HOME`, `XDG_STATE_HOME` 또는 `XDG_CACHE_HOME`을 설정한 경우 설치는 `~/.local/share`, `~/.local/state`, `~/.cache` 대신 해당 경로를 사용합니다. [`CLAUDE_CONFIG_DIR`](/docs/ko/env-vars)을 설정한 경우 전역 설정 파일은 홈 디렉터리 대신 해당 디렉터리 아래에 위치합니다.

299 311

300디렉토리가 쓸 수 있는지 확인하세요:312디렉토리가 쓸 수 있는지 확인하세요:

301 313

1045 1057

1046활성 Claude 구독이 있음에도 불구하고 `API Error: 400 ... "This organization has been disabled"`가 표시되면 `ANTHROPIC_API_KEY` 환경 변수가 구독을 무시하고 있습니다. 이는 이전 고용주 또는 프로젝트의 이전 API 키가 여전히 셸 프로필에 설정되어 있을 때 일반적으로 발생합니다.1058활성 Claude 구독이 있음에도 불구하고 `API Error: 400 ... "This organization has been disabled"`가 표시되면 `ANTHROPIC_API_KEY` 환경 변수가 구독을 무시하고 있습니다. 이는 이전 고용주 또는 프로젝트의 이전 API 키가 여전히 셸 프로필에 설정되어 있을 때 일반적으로 발생합니다.

1047 1059

1048`ANTHROPIC_API_KEY`가 있고 승인한 경우 Claude Code는 구독의 OAuth 자격증명 대신 해당 키를 사용합니다. `-p` 플래그를 사용한 비대화형 모드에서는 키가 있을 때 항상 사용됩니다. 전체 해결 순서는 [인증 우선순위](/docs/ko/authentication#authentication-precedence)를 참조하세요.1060`ANTHROPIC_API_KEY`가 있고 승인한 경우 Claude Code는 구독의 OAuth 자격 증명 대신 해당 키를 사용합니다. `-p` 플래그를 사용한 비대화형 모드에서는 키가 있을 때 항상 사용됩니다. 전체 해결 순서는 [인증 우선순위](/docs/ko/authentication#authentication-precedence)를 참조하세요.

1049 1061

1050대신 구독을 사용하려면 환경 변수를 설정 해제하고 셸 프로필에서 제거하세요:1062대신 구독을 사용하려면 환경 변수를 설정 해제하고 셸 프로필에서 제거하세요:

1051 1063

1098 1110

1099`/login`을 실행하여 다시 인증하세요. 이것이 자주 발생하면 토큰 검증이 올바른 타임스탬프에 따라 달라지므로 시스템 시계가 정확한지 확인하세요.1111`/login`을 실행하여 다시 인증하세요. 이것이 자주 발생하면 토큰 검증이 올바른 타임스탬프에 따라 달라지므로 시스템 시계가 정확한지 확인하세요.

1100 1112

1101한 머신의 병렬 세션은 저장된 로그인을 공유하고 그 갱신을 조정하여 한 번에 하나의 프로세스만 토큰을 새로고침합니다. v2.1.211 이전에는 머신을 절전 모드에서 깨우면 두 세션이 같은 토큰으로 갱신될 수 있어서 저장된 로그인이 취소되고 모든 열린 세션이 한 번에 다시 로그인하도록 요청받았습니다.1113한 머신의 병렬 세션은 저장된 로그인을 공유하고 그 갱신을 조정하여 한 번에 하나의 프로세스만 토큰을 새로고침합니다. 그중 한 세션에서 다시 로그인한 후 다른 세션이 어떻게 동작하는지는 [로그인하지 않음](/docs/ko/errors#not-logged-in)을 참조하세요.

1114

1115v2.1.211 이전에는 머신을 절전 모드에서 깨우면 두 세션이 같은 토큰으로 갱신될 수 있어서 저장된 로그인이 취소되고 모든 열린 세션이 한 번에 다시 로그인하도록 요청받았습니다.

1102 1116

1103macOS에서 Claude Code는 자격증명을 로그인 Keychain에 저장합니다. Keychain이 쓰기를 거부할 때(예: SSH 세션에서 잠겨 있거나 암호가 계정 암호와 동기화되지 않은 경우) Claude Code는 대신 자격증명을 일반 텍스트 `~/.claude/.credentials.json` 파일에 저장합니다. API 키를 생성하는 Console 로그인은 Keychain이 다시 쓰기 가능해질 때까지 실패합니다.1117macOS에서 Claude Code는 자격 증명을 로그인 Keychain에 저장합니다. Keychain이 쓰기를 거부할 때(예: SSH 세션에서 잠겨 있거나 암호가 계정 암호와 동기화되지 않은 경우) Claude Code는 대신 로그인을 일반 텍스트 `~/.claude/.credentials.json` 파일에 저장합니다. API 키를 생성하는 Console 로그인은 Keychain이 다시 쓰기 가능해질 때까지 실패합니다.

1104 1118

1105Keychain을 다시 쓰기 가능하게 만들고 로그인을 암호화된 Keychain으로 다시 이동하려면:1119Keychain을 다시 쓰기 가능하게 만들고 로그인을 암호화된 Keychain으로 다시 이동하려면:

1106 1120

1122 </Step>1136 </Step>

1123 1137

1124 <Step title="로그아웃 후 다시 로그인">1138 <Step title="로그아웃 후 다시 로그인">

1125 Keychain이 다시 쓰기 가능해지면 Claude Code는 다음 번에 자격증명을 쓸 때 자격증명을 다시 Keychain으로 이동합니다. 지금 강제하려면 `/logout`을 실행한 다음 `/login`을 실행하세요. 로그아웃하면 일반 텍스트 파일의 내용, 저장된 MCP 서버 로그인 및 플러그인 민감한 값을 포함한 모든 저장된 자격증명이 제거되므로 그 후에 MCP 서버를 다시 인증하고 플러그인 비밀을 다시 입력해야 합니다. 다시 로그인하면 Keychain에 로그인이 저장됩니다.1139 Keychain이 다시 쓰기 가능해지면 Claude Code는 다음 번에 자격 증명을 쓸 때 자격 증명을 다시 Keychain으로 이동합니다. 지금 강제하려면 `/logout`을 실행한 다음 `/login`을 실행하세요. 로그아웃하면 일반 텍스트 파일의 내용, 저장된 MCP 서버 로그인 및 플러그인 민감한 값을 포함한 모든 저장된 자격 증명이 제거되므로 그 후에 MCP 서버를 다시 인증하고 플러그인 비밀을 다시 입력해야 합니다. 다시 로그인하면 Keychain에 로그인이 저장됩니다.

1126 </Step>1140 </Step>

1127</Steps>1141</Steps>

1128 1142

1129<h3 id="bedrock-agent-platform-or-foundry-credentials-not-loading">1143<h3 id="bedrock-agent-platform-or-foundry-credentials-not-loading">

1130 Bedrock, Agent Platform 또는 Foundry 자격증명이 로드되지 않음1144 Bedrock, Agent Platform 또는 Foundry 자격 증명이 로드되지 않음

1131</h3>1145</h3>

1132 1146

1133Claude Code를 클라우드 공급자를 사용하도록 구성했고 Amazon Bedrock에서 `Could not load credentials from any providers`, Google Cloud의 Agent Platform에서 `Could not load the default credentials` 또는 Microsoft Foundry에서 `ChainedTokenCredential authentication failed`가 표시되면 클라우드 공급자 CLI가 현재 셸에서 인증되지 않았을 가능성이 높습니다.1147Claude Code를 클라우드 공급자를 사용하도록 구성했고 Amazon Bedrock에서 `Could not load credentials from any providers`, Google Cloud의 Agent Platform에서 `Could not load the default credentials` 또는 Microsoft Foundry에서 `ChainedTokenCredential authentication failed`가 표시되면 클라우드 공급자 CLI가 현재 셸에서 인증되지 않았을 가능성이 높습니다.

1134 1148

1135Amazon Bedrock의 경우 AWS 자격증명이 유효한지 확인하세요:1149Amazon Bedrock의 경우 AWS 자격 증명이 유효한지 확인하세요:

1136 1150

1137```bash theme={null}1151```bash theme={null}

1138aws sts get-caller-identity1152aws sts get-caller-identity

1139```1153```

1140 1154

1141Google Cloud의 Agent Platform의 경우 `ANTHROPIC_VERTEX_PROJECT_ID` 및 `CLOUD_ML_REGION`이 셸에 설정되어 있는지 확인한 다음 애플리케이션 기본 자격증명을 설정하세요:1155Google Cloud의 Agent Platform의 경우 `ANTHROPIC_VERTEX_PROJECT_ID` 및 `CLOUD_ML_REGION`이 셸에 설정되어 있는지 확인한 다음 애플리케이션 기본 자격 증명을 설정하세요:

1142 1156

1143```bash theme={null}1157```bash theme={null}

1144gcloud auth application-default login1158gcloud auth application-default login

1145```1159```

1146 1160

1147Microsoft Foundry의 경우 `ANTHROPIC_FOUNDRY_API_KEY`가 설정되어 있는지 확인하거나 Azure CLI로 로그인하여 기본 자격증명 체인이 계정을 찾을 수 있도록 하세요:1161Microsoft Foundry의 경우 `ANTHROPIC_FOUNDRY_API_KEY`가 설정되어 있는지 확인하거나 Azure CLI로 로그인하여 기본 자격 증명 체인이 계정을 찾을 수 있도록 하세요:

1148 1162

1149```bash theme={null}1163```bash theme={null}

1150az login1164az login

1151```1165```

1152 1166

1153자격증명이 터미널에서 작동하지만 VS Code 또는 JetBrains 확장에서 작동하지 않으면 IDE 프로세스가 셸 환경을 상속하지 않았을 가능성이 높습니다. IDE의 자체 설정에서 공급자 환경 변수를 설정하거나 이미 내보낸 터미널에서 IDE를 시작하세요.1167자격 증명이 터미널에서 작동하지만 VS Code 또는 JetBrains 확장에서 작동하지 않으면 IDE 프로세스가 셸 환경을 상속하지 않았을 가능성이 높습니다. IDE의 자체 설정에서 공급자 환경 변수를 설정하거나 이미 내보낸 터미널에서 IDE를 시작하세요.

1154 1168

1155전체 공급자 설정은 [Amazon Bedrock](/docs/ko/amazon-bedrock), [Google Cloud의 Agent Platform](/docs/ko/google-vertex-ai) 또는 [Microsoft Foundry](/docs/ko/microsoft-foundry)를 참조하세요.1169전체 공급자 설정은 [Amazon Bedrock](/docs/ko/amazon-bedrock), [Google Cloud의 Agent Platform](/docs/ko/google-vertex-ai) 또는 [Microsoft Foundry](/docs/ko/microsoft-foundry)를 참조하세요.

1156 1170

troubleshooting.md +5 −0

Details

803. 큰 파일 작업을 [서브에이전트](/docs/ko/sub-agents)로 이동하여 별도의 컨텍스트 창에서 실행합니다.803. 큰 파일 작업을 [서브에이전트](/docs/ko/sub-agents)로 이동하여 별도의 컨텍스트 창에서 실행합니다.

814. 이전 대화가 더 이상 필요하지 않으면 `/clear`를 실행합니다.814. 이전 대화가 더 이상 필요하지 않으면 `/clear`를 실행합니다.

82 82

83`/clear` 후에도 오류가 다시 발생하면 [`/context`](/docs/ko/debug-your-config)를 실행하고 `Messages` 행을 그 위의 행들과 비교합니다:

85* **`Messages`가 가장 큰 행인 경우**: 새 대화의 파일 또는 도구 출력이 윈도우를 다시 채우고 있으므로 1\~3단계를 다시 진행합니다.

86* **나머지 행을 합친 것이 더 큰 경우**: 세션 시작 시 로드되는 항목 때문에 작업할 공간이 너무 적게 남으므로 [시작 시 로드되는 항목을 줄입니다](/docs/ko/errors#prompt-is-too-long).

83<h3 id="command-hangs-or-freezes">88<h3 id="command-hangs-or-freezes">

84 명령 중단 또는 정지89 명령 중단 또는 정지

85</h3>90</h3>

ultrareview.md +9 −3

Details

66 66

67PR 모드에서 클라우드 샌드박스는 로컬 작업 트리를 번들로 묶는 대신 호스트에서 직접 풀 요청을 복제합니다. PR 모드는 `github.com`의 저장소 및 관리자가 Claude Code에 연결한 [GitHub Enterprise Server](/docs/ko/github-enterprise-server) 인스턴스에서 작동합니다.67PR 모드에서 클라우드 샌드박스는 로컬 작업 트리를 번들로 묶는 대신 호스트에서 직접 풀 요청을 복제합니다. PR 모드는 `github.com`의 저장소 및 관리자가 Claude Code에 연결한 [GitHub Enterprise Server](/docs/ko/github-enterprise-server) 인스턴스에서 작동합니다.

68 68

69`github.com`의 저장소의 경우 샌드박스는 Claude 계정에 연결된 GitHub 계정으로 복제하므로 계정이 PR의 저장소를 읽을 수 있어야 합니다. Claude Code는 [`CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC`](/docs/ko/env-vars#variables)을 설정하지 않은 경우 클라우드 세션을 생성하기 전에 이를 확인하고 [계정이 연결되지 않았거나](/docs/ko/errors#no-github-account-is-connected-to-your-claude-account) [계정이 저장소를 볼 수 없을 때](/docs/ko/errors#your-connected-github-account-cant-see-the-repository) 시작을 거부합니다. 거부는 수정 사항을 명시합니다. v2.1.248 이전에는 Claude Code가 시작 전에 이를 확인하지 않았습니다.69`github.com`의 저장소의 경우 샌드박스는 Claude 계정에 연결된 GitHub 계정으로 복제하므로 계정이 PR의 저장소를 읽을 수 있어야 합니다.

70 70

71GitHub CLI 로그인을 Claude 계정에 연결하려면 [`/web-setup`](/docs/ko/web-quickstart#connect-from-your-terminal)을 실행합니다.71GitHub CLI 로그인을 Claude 계정에 연결하려면 [`/web-setup`](/docs/ko/web-quickstart#connect-from-your-terminal)을 실행합니다.

72 72

157 157

158`/tasks`를 사용하여 실행 중이고 완료된 리뷰를 보고, 리뷰의 상세 보기를 열거나, 진행 중인 리뷰를 중지합니다. 리뷰를 중지하면 Claude Code는 클라우드 세션을 보관하고 부분 발견 사항은 반환하지 않습니다.158`/tasks`를 사용하여 실행 중이고 완료된 리뷰를 보고, 리뷰의 상세 보기를 열거나, 진행 중인 리뷰를 중지합니다. 리뷰를 중지하면 Claude Code는 클라우드 세션을 보관하고 부분 발견 사항은 반환하지 않습니다.

159 159

160Claude는 리뷰가 중지되었거나 해당 세션을 찾을 수 없다는 사실도 알려 줄 수 있습니다.

161

162* 리뷰가 완료되기 전에 claude.ai에서 리뷰의 클라우드 세션이 중지되거나 [보관](/docs/ko/claude-code-on-the-web#archive-sessions)되면 Claude는 리뷰가 중지되었다고 알려 줍니다.

163* 리뷰의 클라우드 세션이 삭제되었거나, 리뷰를 시작한 이후 다른 Claude 계정 또는 조직으로 로그인한 경우 Claude는 세션을 찾을 수 없다고 알려 줍니다.

164* 계정을 전환한 경우에도 리뷰는 리뷰를 시작한 계정에서 계속 완료될 수 있습니다. 리뷰가 아직 실행 중이라면 해당 계정으로 다시 로그인한 후 `claude --resume`으로 대화를 재개하여 리뷰를 다시 연결하십시오.

165

160리뷰가 완료되면 Claude Code는 검증된 발견 사항을 세션의 알림으로 표시합니다. 각 발견 사항에는 파일 위치와 문제에 대한 설명이 포함되어 있으므로 Claude에 직접 수정을 요청할 수 있습니다.166리뷰가 완료되면 Claude Code는 검증된 발견 사항을 세션의 알림으로 표시합니다. 각 발견 사항에는 파일 위치와 문제에 대한 설명이 포함되어 있으므로 Claude에 직접 수정을 요청할 수 있습니다.

161 167

162<h2 id="run-ultrareview-non-interactively">168<h2 id="run-ultrareview-non-interactively">

191하위 명령은 다음 세 가지 코드 중 하나로 종료됩니다:197하위 명령은 다음 세 가지 코드 중 하나로 종료됩니다:

192 198

193* **0**: 리뷰가 완료되었으며, 발견 사항이 있거나 없습니다199* **0**: 리뷰가 완료되었으며, 발견 사항이 있거나 없습니다

194* **1**: 리뷰가 시작되지 않았거나, 클라우드 세션에 오류가 발생했거나, 시간 초과가 경과했습니다200* **1**: 리뷰가 시작되지 않았거나 완료되기 전에 중지되었거나, 클라우드 세션에 오류가 발생했거나, 타임아웃이 경과했습니다

195* **130**: Ctrl-C로 하위 명령을 중단했습니다201* **130**: Ctrl-C로 하위 명령을 중단했습니다

196 202

197하위 명령을 중단하면 원격 리뷰는 계속 실행됩니다. stderr로 인쇄된 세션 URL을 따라 브라우저에서 시청합니다.203하위 명령을 중단하면 원격 리뷰는 계속 실행됩니다. stderr로 인쇄된 세션 URL을 따라 브라우저에서 시청합니다.

198 204

199`--post`를 사용하면 하위 명령은 발견 사항을 인쇄한 직후 게시를 시작합니다. 링크를 stderr로 인쇄합니다.205`--post`를 사용하면 하위 명령은 발견 사항을 인쇄한 직후 게시를 시작합니다. 링크를 stderr로 인쇄합니다.

200 206

201* 실행이 실패하거나, 시간 초과가 되거나, 중단하면 하위 명령은 아무것도 게시하지 않습니다.207* 실행이 실패하거나, 중지되거나, 시간 초과되거나, 사용자가 중단하면 하위 명령은 아무것도 게시하지 않습니다.

202* 리뷰가 완료되었지만 댓글이 게시되지 않으면 Claude Code는 이유를 stderr로 인쇄하고, 발견 사항은 stdout에 유지되므로 수동으로 게시할 수 있습니다.208* 리뷰가 완료되었지만 댓글이 게시되지 않으면 Claude Code는 이유를 stderr로 인쇄하고, 발견 사항은 stdout에 유지되므로 수동으로 게시할 수 있습니다.

203 209

204GitHub 풀 요청에 대한 자동 리뷰의 경우, [Code Review](/docs/ko/code-review)는 저장소와 직접 통합되고 CLI 단계 없이 발견 사항을 인라인 PR 댓글로 게시합니다.210GitHub 풀 요청에 대한 자동 리뷰의 경우, [Code Review](/docs/ko/code-review)는 저장소와 직접 통합되고 CLI 단계 없이 발견 사항을 인라인 PR 댓글로 게시합니다.

worktrees.md +2 −0

Details

131 131

132서브에이전트 worktree는 `--worktree`와 동일한 [기본 브랜치](#choose-the-base-branch)를 사용하므로, `worktree.baseRef`가 `"head"`로 설정되지 않은 한 저장소의 기본 브랜치에서 분기합니다.132서브에이전트 worktree는 `--worktree`와 동일한 [기본 브랜치](#choose-the-base-branch)를 사용하므로, `worktree.baseRef`가 `"head"`로 설정되지 않은 한 저장소의 기본 브랜치에서 분기합니다.

133 133

134자체 worktree에 있는 서브에이전트는 [시작 시 로드하는](/docs/ko/sub-agents#what-loads-at-startup) 지침 파일을 자신의 worktree가 아닌 기본 대화에서 가져옵니다. 해당 worktree가 `.claude/worktrees/` 아래의 기본 위치에 있으면, 서브에이전트는 worktree의 파일을 읽을 때 worktree 루트에 있는 `CLAUDE.md` 파일이나 `.claude/rules/` 디렉터리도 로드하지 않습니다. 이는 해당 파일이 worktree의 브랜치에서 다르더라도 마찬가지입니다.

135

134<h3 id="clean-up-subagent-and-background-session-worktrees">136<h3 id="clean-up-subagent-and-background-session-worktrees">

135 서브에이전트 및 백그라운드 세션 worktree 정리137 서브에이전트 및 백그라운드 세션 worktree 정리

136</h3>138</h3>

Documentation 2026-10-01 23:59 UTC to 2026-10-02 02:02 UTC