Documentation 2026-10-13 23:57 UTC to 2026-10-14 22:58 UTC

855 855 

856원격 서버의 상태는 `"connected"`를 보고한 후에도 변경될 수 있습니다. 세션 중간에 연결이 끊어지면 Claude Code는 서버를 다시 `"pending"`으로 이동하면서 [재연결](/docs/ko/mcp#automatic-reconnection)합니다. 나중에 TypeScript에서 `mcpServerStatus()` 호출 또는 Python에서 [`ClaudeSDKClient.get_mcp_status()`](/docs/ko/agent-sdk/python#methods)를 호출하면 이전에 연결된 것으로 본 서버에 대해 `"pending"`을 보고할 수 있으며, 사용자 측에서 구성 변경이 없습니다.856원격 서버의 상태는 `"connected"`를 보고한 후에도 변경될 수 있습니다. 세션 중간에 연결이 끊어지면 Claude Code는 서버를 다시 `"pending"`으로 이동하면서 [재연결](/docs/ko/mcp#automatic-reconnection)합니다. 나중에 TypeScript에서 `mcpServerStatus()` 호출 또는 Python에서 [`ClaudeSDKClient.get_mcp_status()`](/docs/ko/agent-sdk/python#methods)를 호출하면 이전에 연결된 것으로 본 서버에 대해 `"pending"`을 보고할 수 있으며, 사용자 측에서 구성 변경이 없습니다.

857 857 

8585번의 재연결 시도가 실패한 후 서버는 `"failed"`를 보고하거나, 다시 인증이 필요할 때 `"needs-auth"`를 보고합니다. 수동으로 다시 시도하려면 TypeScript에서 [`reconnectMcpServer()`](/docs/ko/agent-sdk/typescript#methods)를 호출하거나 Python에서 [`ClaudeSDKClient.reconnect_mcp_server()`](/docs/ko/agent-sdk/python#methods)를 호출하십시오.8585번의 재연결 시도가 실패한 후 서버는 `"failed"`를 보고하거나, 다시 인증이 필요할 때 `"needs-auth"`를 보고합니다. `"failed"` 상태의 HTTP 또는 SSE 서버는 사용자가 호출하지 않아도 `"connected"`로 돌아올 수 있습니다. Claude Code가 일시적인 오류 후 [백그라운드에서 계속 재시도](/docs/ko/mcp#mid-session-drops-of-a-remote-server)하기 때문입니다. 수동으로 다시 시도하려면 TypeScript에서 [`reconnectMcpServer()`](/docs/ko/agent-sdk/typescript#methods)를 호출하거나 Python에서 [`ClaudeSDKClient.reconnect_mcp_server()`](/docs/ko/agent-sdk/python#methods)를 호출하십시오.

859 859 

860<h2 id="troubleshooting">860<h2 id="troubleshooting">

861 문제 해결861 문제 해결

424 Claude Code가 시스템 프롬프트 외부에 추가하는 컨텍스트424 Claude Code가 시스템 프롬프트 외부에 추가하는 컨텍스트

425</h2>425</h2>

426 426 

427시스템 알림은 Claude Code가 세션 중에 대화에 추가하는 메시지로, CLAUDE.md 파일의 내용이나 파일이 디스크에서 변경되었다는 메모와 같은 Claude에 컨텍스트를 제공합니다. Claude Code는 이를 시스템 프롬프트가 아닌 대화에 전송하므로, `claude_code` 사전 설정을 사용하거나 `systemPrompt`로 자신의 문자열을 전달하든 Claude에 도달합니다.427시스템 리마인더는 Claude Code가 세션 중에 대화에 추가하는 메시지로, CLAUDE.md 파일의 내용이나 파일이 디스크에서 변경되었다는 메모와 같은 컨텍스트를 Claude에 제공합니다. Claude Code는 이를 시스템 프롬프트가 아닌 대화에 전송하므로, `claude_code` 사전 설정을 사용하든 `systemPrompt`로 자체 문자열을 전달하든 대부분 Claude에 도달합니다.

428 428 

429이 섹션에서는 [에이전트의 동작을 변경할 가능성이 가장 높은 알림](#reminders-claude-code-adds-to-the-conversation), [에이전트가 대체하는 컨텍스트를 끄는 방법](#turn-off-the-context-your-agent-replaces), 그리고 [특정 요청에서 Claude가 받은 내용을 확인하는 방법](#see-what-claude-received)을 다룹니다.429이 섹션에서는 [에이전트의 동작을 변경할 가능성이 가장 높은 알림](#reminders-claude-code-adds-to-the-conversation), [에이전트가 대체하는 컨텍스트를 끄는 방법](#turn-off-the-context-your-agent-replaces), 그리고 [특정 요청에서 Claude가 받은 내용을 확인하는 방법](#see-what-claude-received)을 다룹니다.

430 430 

448`systemPrompt`로 자신의 문자열을 전달하는 경우, 시스템 알림이 무엇인지 설명하는 문장을 추가합니다. `claude_code` 사전 설정에는 하나가 있으며, 문자열이 전체 사전 설정을 대체합니다. 없으면 프롬프트의 아무것도 Claude에게 CLAUDE.md 콘텐츠 및 훅 출력과 같은 알림이 사용자가 아닌 애플리케이션에서 오는 것임을 알려주지 않습니다. 예를 들어:448`systemPrompt`로 자신의 문자열을 전달하는 경우, 시스템 알림이 무엇인지 설명하는 문장을 추가합니다. `claude_code` 사전 설정에는 하나가 있으며, 문자열이 전체 사전 설정을 대체합니다. 없으면 프롬프트의 아무것도 Claude에게 CLAUDE.md 콘텐츠 및 훅 출력과 같은 알림이 사용자가 아닌 애플리케이션에서 오는 것임을 알려주지 않습니다. 예를 들어:

449 449 

450```text theme={null}450```text theme={null}

451애플리케이션이 이 대화에 시스템 알림을 추가합니다. 이를 사용자의 메시지가 아닌 애플리케이션의 컨텍스트로 취급합니다.451The application adds system reminders to this conversation. Treat them as context from the application, not as messages from the user.

452```452```

453 453 

454<h3 id="turn-off-the-context-your-agent-replaces">454<h3 id="turn-off-the-context-your-agent-replaces">

467| 모든 CLAUDE.md 파일 | `CLAUDE_CODE_DISABLE_CLAUDE_MDS=1` 설정 |467| 모든 CLAUDE.md 파일 | `CLAUDE_CODE_DISABLE_CLAUDE_MDS=1` 설정 |

468| 작업 목록 알림, 파일 변경 메모 및 스킬 목록 | `CLAUDE_CODE_DISABLE_ATTACHMENTS=1` 설정 |468| 작업 목록 알림, 파일 변경 메모 및 스킬 목록 | `CLAUDE_CODE_DISABLE_ATTACHMENTS=1` 설정 |

469 469 

470Claude Code의 기본 제공 커밋 및 풀 요청 지침은 알림이 아닙니다. 이는 Bash 도구의 설명의 일부이므로 사용자 정의 `systemPrompt`를 전달할 때도 Claude에 도달합니다.470기본 제공 커밋 및 풀 리퀘스트 지침을 제외하려면 `includeGitInstructions`를 `false`로 설정합니다. 이 지침은 Bash 도구 설명의 일부이므로 사용자 정의 `systemPrompt`를 사용할 때도 Claude에 도달합니다. 다만 최소 기본값, 사용자 정의 `systemPrompt`, 또는 자체 프롬프트가 있는 사용자 정의 메인 스레드 에이전트를 사용하는 경우에는 git 상태 스냅샷 없이 세션이 시작됩니다.

471 471 

472`CLAUDE_CODE_DISABLE_ATTACHMENTS`를 설정하면, Claude Code는 `@` 파일 언급을 파일 콘텐츠로 확장하는 대신 일반 텍스트로 전송합니다. 사용 가능한 서브에이전트 목록 및 백그라운드 작업 알림은 여전히 도착합니다.472`CLAUDE_CODE_DISABLE_ATTACHMENTS`를 설정하면, Claude Code는 또한 `@` 파일 언급을 파일 콘텐츠로 확장하는 대신 일반 텍스트로 전송합니다. 사용 가능한 서브에이전트 목록 및 백그라운드 작업 알림은 여전히 도착합니다. `@` 파일 언급의 확장만 중지하려면 Claude Code v2.1.299 이상에서 대신 [`CLAUDE_CODE_DISABLE_FILE_MENTIONS=1`](/docs/ko/env-vars#variables)을 설정합니다. 그러면 Claude는 언급된 경로와 함께 파일 도구로 해당 경로를 읽으라는 메모를 받습니다.

473 473 

474다음 예제는 `append`에 자체 커밋 규칙을 포함하는 에이전트용입니다. 트레일러 및 푸터를 제거하기 위해 두 `attribution` 키를 빈 문자열로 설정하고, Claude Code의 자체 커밋 워크플로우 지침이 귀하의 지침과 경쟁하지 않도록 `includeGitInstructions`를 끕니다:474다음 예제는 `append`에 자체 커밋 규칙을 포함하는 에이전트용입니다. 트레일러 및 푸터를 제거하기 위해 두 `attribution` 키를 빈 문자열로 설정하고, Claude Code의 자체 커밋 워크플로우 지침이 귀하의 지침과 경쟁하지 않도록 `includeGitInstructions`를 끕니다:

475 475 

164| `mcpServers` | `(string \| object)[]` | 아니오 | 이 에이전트에서 사용 가능한 MCP 서버(이름 또는 인라인 구성으로) |164| `mcpServers` | `(string \| object)[]` | 아니오 | 이 에이전트에서 사용 가능한 MCP 서버(이름 또는 인라인 구성으로) |

165| `initialPrompt` | `string` | 아니오 | 이 에이전트가 주 스레드 에이전트로 실행될 때 첫 번째 사용자 턴으로 자동 제출됩니다. 에이전트가 서브에이전트로 호출될 때는 무시됩니다 |165| `initialPrompt` | `string` | 아니오 | 이 에이전트가 주 스레드 에이전트로 실행될 때 첫 번째 사용자 턴으로 자동 제출됩니다. 에이전트가 서브에이전트로 호출될 때는 무시됩니다 |

166| `maxTurns` | `number` | 아니오 | 에이전트가 중지되기 전의 최대 에이전트 턴 수입니다. 에이전트가 제한에 도달하면 Claude Code는 부분으로 표시된 출력을 반환하며, [에이전트를 재개](#resume-subagents)하여 계속할 수 있습니다. 부분 표시는 Claude Code v2.1.246 이상이 필요합니다 |166| `maxTurns` | `number` | 아니오 | 에이전트가 중지되기 전의 최대 에이전트 턴 수입니다. 에이전트가 제한에 도달하면 Claude Code는 부분으로 표시된 출력을 반환하며, [에이전트를 재개](#resume-subagents)하여 계속할 수 있습니다. 부분 표시는 Claude Code v2.1.246 이상이 필요합니다 |

167| `autoCompactWindow` | `number` | 아니오 | 이 에이전트가 서브에이전트로 실행될 때 [자동 압축 윈도우](/docs/ko/sub-agents#subagent-auto-compact-window)를 `100000`에서 `1000000` 사이의 토큰 수로 낮춥니다. TypeScript Agent SDK v0.3.296 이상이 필요합니다. Python SDK의 [`AgentDefinition`](/docs/ko/agent-sdk/python#agentdefinition)에는 이 필드가 없습니다 |

167| `background` | `boolean` | 아니오 | 호출될 때 이 에이전트를 비차단 백그라운드 작업으로 실행합니다 |168| `background` | `boolean` | 아니오 | 호출될 때 이 에이전트를 비차단 백그라운드 작업으로 실행합니다 |

168| `omitClaudeMd` | `boolean` | 아니오 | 이 에이전트가 서브에이전트로 실행될 때 사용자, 프로젝트 및 로컬 CLAUDE.md 파일 없이 실행합니다. 관리되는 정책 파일은 여전히 로드됩니다. 에이전트가 주 스레드 에이전트로 실행될 때는 무시됩니다. TypeScript Agent SDK v0.3.271 이상이 필요합니다. Python SDK의 [`AgentDefinition`](/docs/ko/agent-sdk/python#agentdefinition)에는 이 필드가 없습니다 |169| `omitClaudeMd` | `boolean` | 아니오 | 이 에이전트의 초기 컨텍스트에서 사용자, 프로젝트 및 로컬 CLAUDE.md 파일을 제외합니다. 관리되는 정책 파일은 여전히 로드됩니다. 에이전트가 주 스레드 에이전트로 실행될 때는 무시됩니다. TypeScript Agent SDK v0.3.271 이상이 필요합니다. Python SDK의 [`AgentDefinition`](/docs/ko/agent-sdk/python#agentdefinition)에는 이 필드가 없습니다 |

169| `effort` | `'low' \| 'medium' \| 'high' \| 'xhigh' \| 'max' \| number` | 아니오 | 이 에이전트의 추론 노력 수준 |170| `effort` | `'low' \| 'medium' \| 'high' \| 'xhigh' \| 'max' \| number` | 아니오 | 이 에이전트의 추론 노력 수준 |

170| `permissionMode` | `PermissionMode` | 아니오 | 이 에이전트 내 도구 실행을 위한 권한 모드입니다. [서브에이전트 상속 규칙](/docs/ko/agent-sdk/permissions#available-modes)이 적용 시기를 결정합니다 |171| `permissionMode` | `PermissionMode` | 아니오 | 이 에이전트 내 도구 실행을 위한 권한 모드입니다. [서브에이전트 상속 규칙](/docs/ko/agent-sdk/permissions#available-modes)이 적용 시기를 결정합니다 |

171 172 

44 44 

45| 값 | 동작 |45| 값 | 동작 |

46| :- | :- |46| :- | :- |

47| (설정 안 함) | 도구 검색이 켜져 있습니다. 도구 정의는 지연되고 필요에 따라 발견됩니다. Google Cloud의 Agent Platform의 Claude 4.5 세대보다 이전 모델, 비공식 `ANTHROPIC_BASE_URL`, 또는 Azure에서 호스팅되는 Microsoft Foundry 배포에서는 미리 로드로 폴백됩니다. |47| (설정 안 함) | 도구 검색이 켜져 있습니다. 도구 정의는 지연되고 필요에 따라 발견됩니다. Opus 4 및 Sonnet 4보다 이전 모델, Opus 4.5, Sonnet 4.5, Haiku 4.5보다 이전의 Google Cloud Agent Platform 모델, 비공식 `ANTHROPIC_BASE_URL`, 또는 Azure에서 호스팅되는 Microsoft Foundry 배포에서는 미리 로드로 폴백됩니다. |

48| `true` | 도구 검색이 항상 켜져 있습니다. Azure에서 호스팅되는 Microsoft Foundry 배포에서는 서버 측 거부가 여전히 미리 로드를 강제하고, Google Cloud의 Agent Platform의 Claude 4.5 세대보다 이전 모델에서는 SDK가 도구 정의를 계속 미리 로드합니다. SDK는 프록시를 통해 베타 헤더를 전송하며, `tool_reference` 블록을 지원하지 않는 프록시에서는 요청이 실패합니다. |48| `true` | 비공식 `ANTHROPIC_BASE_URL`에서도 도구 검색이 켜진 상태로 유지됩니다. (설정 안 함)의 나머지 폴백은 여전히 적용됩니다. SDK는 프록시를 통해 베타 헤더를 전송하며, `tool_reference` 블록을 지원하지 않는 프록시에서는 요청이 실패합니다. |

49| `auto` | 도구 검색이 연기할 수 있는 도구 정의의 토큰을 계산하고 총합을 모델의 컨텍스트 윈도우와 비교합니다. 총합이 윈도우의 10%에 도달하면 도구 검색이 활성화됩니다. 그 아래에서는 SDK가 모든 도구 정의를 컨텍스트에 미리 로드합니다. |49| `auto` | 도구 검색이 연기할 수 있는 도구 정의의 토큰을 계산하고 총합을 모델의 컨텍스트 윈도우와 비교합니다. 총합이 윈도우의 10%에 도달하면 도구 검색이 활성화됩니다. 그 아래에서는 SDK가 모든 도구 정의를 컨텍스트에 미리 로드합니다. |

50| `auto:N` | `auto`와 동일하지만 사용자 정의 백분율입니다. `auto:5`는 해당 정의가 컨텍스트 윈도우의 5%에 도달할 때 활성화됩니다. 낮은 값은 더 빨리 활성화됩니다. |50| `auto:N` | `auto`와 동일하지만 사용자 정의 백분율입니다. `auto:5`는 해당 정의가 컨텍스트 윈도우의 5%에 도달할 때 활성화됩니다. 낮은 값은 더 빨리 활성화됩니다. |

51| `false` | 도구 검색이 꺼져 있습니다. 모든 도구 정의는 매 턴마다 컨텍스트에 로드됩니다. |51| `false` | 도구 검색이 꺼져 있습니다. 모든 도구 정의는 매 턴마다 컨텍스트에 로드됩니다. |

52 52 

53[`CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS`](/docs/ko/env-vars) 설정은 도구 검색을 끕니다. `ENABLE_TOOL_SEARCH`를 직접 설정하여 이를 재정의할 수 없습니다. 조직은 Claude Code v2.1.227 이상에서 [관리 설정](/docs/ko/managed-settings)을 통해 도구 검색을 켜진 상태로 유지할 수 있습니다. [사전 릴리스 기능 비활성화](/docs/ko/llm-gateway-protocol#disable-pre-release-capabilities)는 재정의가 적용되는 위치와 변수가 제거하는 항목을 다룹니다.53[`CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS`](/docs/ko/env-vars) 설정은 도구 검색을 끕니다. `ENABLE_TOOL_SEARCH`를 직접 설정하여 이를 재정의할 수 없습니다. 조직은 Claude Code v2.1.227 이상에서 [관리형 설정](/docs/ko/managed-settings)을 통해 이 변수가 설정된 상태에서도 도구 검색을 켜진 상태로 유지할 수 있습니다. [HIPAA 구성을 받는](/docs/ko/hipaa-setup#check-how-developers-sign-in-and-connect) 세션에서는 도구 검색이 꺼지며, `ENABLE_TOOL_SEARCH`와 관리형 설정 모두 이를 다시 켤 수 없습니다. [사전 릴리스 기능 비활성화](/docs/ko/llm-gateway-protocol#disable-pre-release-capabilities)는 재정의가 적용되는 위치와 변수가 제거하는 항목을 다룹니다.

54 54 

55도구 검색은 원격 MCP 서버에서 오든 [사용자 정의 SDK MCP 서버](/docs/ko/agent-sdk/custom-tools)에서 오든 모든 등록된 도구에 적용됩니다. `auto`를 사용할 때 SDK는 도구 검색이 연기할 수 있는 모든 정의를 하나의 결합된 임계값으로 계산합니다: [`alwaysLoad`](/docs/ko/mcp#exempt-a-server-from-deferral)로 표시되지 않은 모든 MCP 도구(모든 서버에서), 그리고 필요에 따라 로드되는 기본 제공 도구입니다. SDK는 Bash, Read, Edit과 같은 핵심 기본 제공 도구를 미리 로드하고 임계값에 계산하지 않습니다. 플러그인 중 하나에 포함된 [mod](/docs/ko/plugins/mods/reference#tools)도 도구를 연기하거나 미리 로드할 수 있으며, 이에 따라 해당 계산이 달라집니다.55도구 검색은 원격 MCP 서버에서 오든 [사용자 정의 SDK MCP 서버](/docs/ko/agent-sdk/custom-tools)에서 오든 모든 등록된 도구에 적용됩니다. `auto`를 사용할 때 SDK는 도구 검색이 연기할 수 있는 모든 정의를 하나의 결합된 임계값으로 계산합니다: [`alwaysLoad`](/docs/ko/mcp#exempt-a-server-from-deferral)로 표시되지 않은 모든 MCP 도구(모든 서버에서), 그리고 필요에 따라 로드되는 기본 제공 도구입니다. SDK는 Bash, Read, Edit과 같은 핵심 기본 제공 도구를 미리 로드하고 임계값에 계산하지 않습니다. 플러그인 중 하나에 포함된 [mod](/docs/ko/plugins/mods/reference#tools)도 도구를 연기하거나 미리 로드할 수 있으며, 이에 따라 해당 계산이 달라집니다.

56 56 

167 167 

168* **최대 도구:** 카탈로그에 10,000개의 도구168* **최대 도구:** 카탈로그에 10,000개의 도구

169* **검색 결과:** 기본적으로 검색당 가장 관련성이 높은 5개의 도구 반환169* **검색 결과:** 기본적으로 검색당 가장 관련성이 높은 5개의 도구 반환

170* **모델 지원:** Claude Sonnet 4.5, Claude Haiku 4.5, Claude Opus 4.5 및 이후 모델; 현재 목록은 [API 문서의 모델 호환성](https://platform.claude.com/docs/ko/agents-and-tools/tool-use/tool-search-tool#model-compatibility)을 참조하십시오. Google Cloud의 Agent Platform에서도 동일한 최소 요구 사항이 적용됩니다.170* **모델 지원:** Opus 4, Sonnet 4, Haiku 4.5 및 이후 모델, 또는 Google Cloud의 Agent Platform에서는 Opus 4.5, Sonnet 4.5, Haiku 4.5 및 이후 모델. 이전 모델에서는 [도구 검색 구성](#configure-tool-search)에서 설명하는 것처럼 SDK가 도구 정의를 미리 로드합니다.

171 171 

172<h2 id="related-documentation">172<h2 id="related-documentation">

173 관련 문서173 관련 문서

776 776 

777값은 플래그 설정 계층에 기록되며, 시작 시 `query()`의 인라인 `settings` 옵션이 설정한 값 위에 병합됩니다. 이는 [페이지 내 우선순위 섹션](#settings-precedence)에서 프로그래밍 방식 옵션이라고 부르는 것과 동일한 계층입니다.777값은 플래그 설정 계층에 기록되며, 시작 시 `query()`의 인라인 `settings` 옵션이 설정한 값 위에 병합됩니다. 이는 [페이지 내 우선순위 섹션](#settings-precedence)에서 프로그래밍 방식 옵션이라고 부르는 것과 동일한 계층입니다.

778 778 

779연속 호출 시 최상위 키는 얕은 병합됩니다. `{ permissions: {...} }`로 두 번째 호출을 하면 이전 호출의 `permissions` 객체에 깊은 병합되는 대신 전체 `permissions` 객체가 대체됩니다.779연속 호출은 최상위 키를 얕게 병합합니다. `{ permissions: {...} }`로 두 번째 호출을 하면 이전 호출의 `permissions` 객체에 깊게 병합되지 않고 전체 객체가 대체됩니다.

780 780 

781`applyFlagSettings()`로 설정한 키를 지우려면 해당 키에 `null`을 전달하세요. 그러면 대부분의 키는 먼저 시작 시 `query()`의 `settings` 옵션이 설정한 값으로 폴백하고, 그다음 우선순위가 더 낮은 소스로 폴백합니다. 지워진 `model`은 설정 파일이 `model`을 설정하더라도 [Claude Code의 기본 모델](/docs/ko/model-config)로 재설정됩니다. `undefined`를 전달하면 JSON 직렬화 시 삭제되므로 효과가 없습니다.781`applyFlagSettings()`로 설정한 키를 지우려면 해당 키에 `null`을 전달하세요. 그러면 대부분의 키는 먼저 시작 시 `query()`의 `settings` 옵션이 설정한 값으로 폴백하고, 그다음 우선순위가 더 낮은 소스로 폴백합니다. 지워진 `model`은 설정 파일이 `model`을 설정하더라도 [Claude Code의 기본 모델](/docs/ko/model-config)로 재설정됩니다. `undefined`를 전달하면 JSON 직렬화 시 삭제되므로 효과가 없습니다.

782 782 

908 | "malformed"908 | "malformed"

909 | "not_honoured"909 | "not_honoured"

910 >;910 >;

911 claude_code_version?: string;

911};912};

912```913```

913 914 

922 923 

923요청의 `sdkMcpServerManifests` 필드와 응답의 `sdk_mcp_manifests_parked` 필드는 [`createSdkMcpServer()`](#createsdkmcpserver)로 생성한 프로세스 내 [SDK MCP 서버](/docs/ko/agent-sdk/custom-tools)를 위한 것입니다. 애플리케이션에서는 두 필드 모두 설정하거나 읽지 않습니다.924요청의 `sdkMcpServerManifests` 필드와 응답의 `sdk_mcp_manifests_parked` 필드는 [`createSdkMcpServer()`](#createsdkmcpserver)로 생성한 프로세스 내 [SDK MCP 서버](/docs/ko/agent-sdk/custom-tools)를 위한 것입니다. 애플리케이션에서는 두 필드 모두 설정하거나 읽지 않습니다.

924 925 

926`claude_code_version`은 세션의 턴을 실행하는 프로세스의 Claude Code 버전입니다. [`SDKSystemMessage`](#sdksystemmessage) init 메시지에 포함된 값과 동일하므로, 첫 번째 턴 전에 CLI 버전을 읽을 수 있습니다.

927 

928* 이 필드에는 Claude Code v2.1.296이 번들된 Agent SDK v0.3.296 이상이 필요합니다.

929* 필드가 `undefined`이고 `pathToClaudeCodeExecutable`을 설정한 경우, 이를 Claude Code v2.1.296 이상으로 지정하세요.

930 

925응답은 항상 `fast_mode_state`를 보고하며, 무언가가 [빠른 모드](/docs/ko/fast-mode)를 차단하는 경우 `fast_mode_disabled_reason`이 그와 함께 이유 코드를 전달하므로, 가용성을 다시 도출하는 대신 차단된 상태를 설명할 수 있습니다. 두 동작 모두 Claude Code v2.1.219 이상이 필요합니다. v2.1.219 이전에는 빠른 모드를 사용할 수 없을 때 응답에서 `fast_mode_state`가 생략되었고 이유도 전달되지 않았습니다. 이유 코드와 그 의미는 결과 메시지의 [`fast_mode_disabled_reason`](#sdkresultmessage)을 참조하세요.931응답은 항상 `fast_mode_state`를 보고하며, 무언가가 [빠른 모드](/docs/ko/fast-mode)를 차단하는 경우 `fast_mode_disabled_reason`이 그와 함께 이유 코드를 전달하므로, 가용성을 다시 도출하는 대신 차단된 상태를 설명할 수 있습니다. 두 동작 모두 Claude Code v2.1.219 이상이 필요합니다. v2.1.219 이전에는 빠른 모드를 사용할 수 없을 때 응답에서 `fast_mode_state`가 생략되었고 이유도 전달되지 않았습니다. 이유 코드와 그 의미는 결과 메시지의 [`fast_mode_disabled_reason`](#sdkresultmessage)을 참조하세요.

926 932 

927성공한 `initialize`의 제어 응답 래퍼에는 `pending_permission_requests` 배열도 포함됩니다. 이 필드는 위의 `SDKControlInitializeResponse` 페이로드가 아니라 응답 래퍼 자체에 있습니다. 각 항목은 세션이 실행 중에 권한 요청을 위해 스트리밍하는 것과 동일한 `{ type: "control_request", request_id, request }` 형태의 완전한 `control_request` 메시지입니다.933성공한 `initialize`의 제어 응답 래퍼에는 `pending_permission_requests` 배열도 포함됩니다. 이 필드는 위의 `SDKControlInitializeResponse` 페이로드가 아니라 응답 래퍼 자체에 있습니다. 각 항목은 세션이 실행 중에 권한 요청을 위해 스트리밍하는 것과 동일한 `{ type: "control_request", request_id, request }` 형태의 완전한 `control_request` 메시지입니다.

1218 skills?: string[];1224 skills?: string[];

1219 initialPrompt?: string;1225 initialPrompt?: string;

1220 maxTurns?: number;1226 maxTurns?: number;

1227 autoCompactWindow?: number;

1221 background?: boolean;1228 background?: boolean;

1222 omitClaudeMd?: boolean;1229 omitClaudeMd?: boolean;

1223 memory?: "user" | "project" | "local";1230 memory?: "user" | "project" | "local";

1238| `skills` | 아니요 | 에이전트 컨텍스트에 미리 로드할 스킬 이름의 배열입니다 |1245| `skills` | 아니요 | 에이전트 컨텍스트에 미리 로드할 스킬 이름의 배열입니다 |

1239| `initialPrompt` | 아니요 | 이 에이전트가 메인 스레드 에이전트로 실행될 때 첫 번째 사용자 턴으로 자동 제출됩니다 |1246| `initialPrompt` | 아니요 | 이 에이전트가 메인 스레드 에이전트로 실행될 때 첫 번째 사용자 턴으로 자동 제출됩니다 |

1240| `maxTurns` | 아니요 | 중지하기 전 최대 에이전트 턴 수(API 왕복)입니다 |1247| `maxTurns` | 아니요 | 중지하기 전 최대 에이전트 턴 수(API 왕복)입니다 |

1248| `autoCompactWindow` | 아니요 | 이 에이전트가 서브에이전트로 실행될 때 [자동 압축 윈도우](/docs/ko/sub-agents#subagent-auto-compact-window)를 `100000`에서 `1000000` 사이의 토큰 수로 낮춥니다. TypeScript Agent SDK v0.3.296 이상이 필요합니다 |

1241| `background` | 아니요 | 호출될 때 이 에이전트를 비차단 백그라운드 작업으로 실행합니다 |1249| `background` | 아니요 | 호출될 때 이 에이전트를 비차단 백그라운드 작업으로 실행합니다 |

1242| `omitClaudeMd` | 아니요 | 이 에이전트가 서브에이전트로 실행될 때 사용자, 프로젝트, 로컬 CLAUDE.md 파일 없이 실행합니다. 관리형 정책 파일은 여전히 로드됩니다. Agent 도구 프롬프트에서 필요한 모든 것을 받는 에이전트에 사용하세요. 이 에이전트가 메인 스레드 에이전트로 실행될 때는 무시됩니다. TypeScript Agent SDK v0.3.271 이상이 필요합니다 |1250| `omitClaudeMd` | 아니요 | 사용자, 프로젝트, 로컬 CLAUDE.md 파일을 이 에이전트의 초기 컨텍스트에서 제외합니다. 관리형 정책 파일은 여전히 로드됩니다. 필요한 모든 것을 Agent 도구 프롬프트에서 받는 에이전트에 사용하십시오. 이 에이전트가 메인 스레드 에이전트로 실행될 때는 무시됩니다. TypeScript Agent SDK v0.3.271 이상이 필요합니다 |

1243| `memory` | 아니요 | 이 에이전트의 메모리 소스입니다: `'user'`, `'project'` 또는 `'local'` |1251| `memory` | 아니요 | 이 에이전트의 메모리 소스입니다: `'user'`, `'project'` 또는 `'local'` |

1244| `effort` | 아니요 | 이 에이전트의 추론 effort 수준입니다. 이름이 지정된 수준 또는 정수를 허용합니다 |1252| `effort` | 아니요 | 이 에이전트의 추론 effort 수준입니다. 이름이 지정된 수준 또는 정수를 허용합니다 |

1245| `permissionMode` | 아니요 | 이 에이전트 내에서 도구를 실행할 때의 권한 모드입니다. 적용 시점은 [서브에이전트 상속 규칙](/docs/ko/agent-sdk/permissions#available-modes)이 결정합니다. [`PermissionMode`](#permissionmode)를 참조하세요 |1253| `permissionMode` | 아니요 | 이 에이전트 내에서 도구를 실행할 때의 권한 모드입니다. 적용 시점은 [서브에이전트 상속 규칙](/docs/ko/agent-sdk/permissions#available-modes)이 결정합니다. [`PermissionMode`](#permissionmode)를 참조하세요 |

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

2435* `senderTaskId`: 팀원의 작업 ID입니다. cross-session peer의 경우에는 존재하지 않습니다.2443* `senderTaskId`: 팀원의 작업 ID입니다. cross-session peer의 경우에는 존재하지 않습니다.

2436* `name`: Claude Code가 정규화한 발신자의 표시 이름입니다. Claude Code는 Unicode 제어, 서식, 서로게이트, 줄 또는 단락 구분자 코드 포인트를 제거한 다음, 결과의 앞뒤 공백을 제거하고 말줄임표를 붙여 최대 64개 코드 포인트로 제한합니다. Claude Code v2.1.205 이상이 필요합니다.2444* `name`: Claude Code가 정규화한 발신자의 표시 이름입니다. Claude Code는 Unicode 제어, 서식, 서로게이트, 줄 또는 단락 구분자 코드 포인트를 제거한 다음, 결과의 앞뒤 공백을 제거하고 말줄임표를 붙여 최대 64개 코드 포인트로 제한합니다. Claude Code v2.1.205 이상이 필요합니다.

2437* `body`: peer 엔벨로프가 제거된 디코딩된 메시지 본문으로, 모델이 보는 내용과 바이트 단위로 정확히 일치합니다. 팀원 메시지에는 항상 존재하며, cross-session peer의 경우 턴이 Claude Code가 구성한 정확히 하나의 peer 엔벨로프일 때만 존재합니다. 메시지 텍스트를 다시 파싱하는 대신 `name`과 `body`를 렌더링하세요. Claude Code v2.1.205 이상이 필요합니다.2445* `body`: 피어 엔벨로프를 제거한 디코딩된 메시지 본문으로, 모델이 보는 내용과 바이트 단위로 정확히 일치합니다. 단일 팀원 메시지에는 존재하며, 여러 메시지가 병합된 경우에는 존재하지 않습니다. 세션 간 피어의 경우 턴이 Claude Code가 구성한 정확히 하나의 피어 엔벨로프일 때만 존재합니다. 메시지 텍스트를 다시 파싱하는 대신 `name`과 `body`를 렌더링하세요. v2.1.299 이전에는 병합된 메시지가 첫 번째 메시지의 `body`를 유지했습니다. Claude Code v2.1.205 이상이 필요합니다.

2438* `fromSession`: 발신자의 호스트에서 열 수 있는 세션 ID로, UI가 발신 세션으로 다시 연결할 수 있도록 발신자의 호스트가 설정합니다. `from`과 마찬가지로 발신자가 주장하는 값이므로 탐색 대상으로만 사용하고, 발신자 신원의 증거로 취급하지 마세요. Claude Code v2.1.216 이상이 필요합니다.2446* `fromSession`: 발신자의 호스트에서 열 수 있는 세션 ID로, UI가 발신 세션으로 다시 연결할 수 있도록 발신자의 호스트가 설정합니다. `from`과 마찬가지로 발신자가 주장하는 값이므로 탐색 대상으로만 사용하고, 발신자 신원의 증거로 취급하지 마세요. Claude Code v2.1.216 이상이 필요합니다.

2439* `verifiedPeerPid`: 이 세션의 cross-session 메시징 소켓에 연결한 프로세스의 프로세스 ID로, 커널이 검증하며 페이로드가 아닌 연결 자체에서 읽어옵니다. 발신자를 식별할 때는 `from`이 아닌 이 값을 사용하세요. `from`은 같은 사용자의 어떤 프로세스든 위조할 수 있습니다. Windows나 소켓이 아닌 유입 경로처럼 Claude Code가 검증할 수 없는 경우에는 이 필드가 존재하지 않으므로, 값이 없으면 발신자가 검증되지 않았다는 의미입니다. 중계된 트래픽의 경우 이 값은 메시지 작성자가 아닌 중계자를 식별하며, 프로세스 ID는 재사용될 수 있으므로 인증 토큰이 아닌 출처 정보로 취급하세요. Claude Code v2.1.216 이상이 필요합니다.2447* `verifiedPeerPid`: 이 세션의 cross-session 메시징 소켓에 연결한 프로세스의 프로세스 ID로, 커널이 검증하며 페이로드가 아닌 연결 자체에서 읽어옵니다. 발신자를 식별할 때는 `from`이 아닌 이 값을 사용하세요. `from`은 같은 사용자의 어떤 프로세스든 위조할 수 있습니다. Windows나 소켓이 아닌 유입 경로처럼 Claude Code가 검증할 수 없는 경우에는 이 필드가 존재하지 않으므로, 값이 없으면 발신자가 검증되지 않았다는 의미입니다. 중계된 트래픽의 경우 이 값은 메시지 작성자가 아닌 중계자를 식별하며, 프로세스 ID는 재사용될 수 있으므로 인증 토큰이 아닌 출처 정보로 취급하세요. Claude Code v2.1.216 이상이 필요합니다.

2440 2448 

3442 offset?: number;3450 offset?: number;

3443 limit?: number;3451 limit?: number;

3444 pages?: string;3452 pages?: string;

3453 allow_large?: boolean;

3445};3454};

3446```3455```

3447 3456 

3448텍스트, 이미지, PDF 및 Jupyter 노트북을 포함한 로컬 파일 시스템에서 파일을 읽습니다. PDF 페이지 범위의 경우 `pages`를 사용합니다(예: `"1-5"`).3457텍스트, 이미지, PDF 및 Jupyter 노트북을 포함한 로컬 파일 시스템에서 파일을 읽습니다.

3458 

3459* PDF 페이지 범위의 경우 `pages`를 사용합니다(예: `"1-5"`).

3460* `allow_large`를 사용하면 세션의 컨텍스트 윈도우에 여유가 있을 때 Claude가 [일반적인 크기 제한](/docs/ko/tools-reference#large-files)을 넘는 텍스트 파일을 읽을 수 있습니다. Claude Code v2.1.296을 번들로 포함하는 Agent SDK v0.3.296 이상이 필요합니다.

3449 3461 

3450PDF의 경우 Claude는 Read 호출의 `tool_result` 콘텐츠 내에서 파일의 내용을 받습니다. `pdf` [출력](#tool-output-types)을 반환하는 읽기는 요약 `text` 블록 다음에 `document` 블록을 전달합니다. `parts` 출력을 반환하는 읽기는 요약 `text` 블록 다음에 추출된 페이지당 하나의 블록을 전달합니다: `image` 블록 또는 Claude Code가 이를 이미지로 렌더링할 수 없을 때 페이지의 이름을 지정하는 `text` 블록입니다. Agent SDK v0.3.242 이전에는 Claude Code가 도구 결과 후 별도의 `user` 메시지로 파일의 내용을 전달했습니다.3462PDF의 경우 Claude는 Read 호출의 `tool_result` 콘텐츠 내에서 파일의 내용을 받습니다. `pdf` [출력](#tool-output-types)을 반환하는 읽기는 요약 `text` 블록 다음에 `document` 블록을 전달합니다. `parts` 출력을 반환하는 읽기는 요약 `text` 블록 다음에 추출된 페이지당 하나의 블록을 전달합니다: `image` 블록 또는 Claude Code가 이를 이미지로 렌더링할 수 없을 때 페이지의 이름을 지정하는 `text` 블록입니다. Agent SDK v0.3.242 이전에는 Claude Code가 도구 결과 후 별도의 `user` 메시지로 파일의 내용을 전달했습니다.

3451 3463 

270| **작업 목록** | 팀원들이 요청하고 완료하는 공유 작업 항목 목록 |270| **작업 목록** | 팀원들이 요청하고 완료하는 공유 작업 항목 목록 |

271| **메일박스** | 에이전트 간 통신을 위한 메시징 시스템 |271| **메일박스** | 에이전트 간 통신을 위한 메시징 시스템 |

272 272 

273각 에이전트의 메일박스는 `~/.claude/teams/{team-name}/inboxes/{agent-name}.json`의 JSON 파일입니다. Claude Code는 메일박스 파일을 읽을 때 모든 항목을 검증합니다. 메시지 형식과 일치하지 않는 항목은 오류로 보고되고 파일에서 제거됩니다. 유효한 메시지는 여전히 전달됩니다. v2.1.207 이전에는 단일 형식이 잘못된 메일박스 항목으로 인해 매초 반복되는 오류가 발생했으며 파일을 수동으로 삭제할 때까지 해당 메일박스의 전달이 차단되었습니다.273각 에이전트의 메일박스는 `~/.claude/teams/{team-name}/inboxes/{agent-name}.json`의 JSON 파일입니다. Claude Code는 메일박스 파일을 읽을 때 모든 항목을 검증합니다. 메시지 형식과 일치하지 않는 항목은 오류로 보고되고 파일에서 제거됩니다. 유효한 메시지는 여전히 전달됩니다.

274 274 

275Claude Code는 메시지가 일반 텍스트이든 계획 승인이나 종료 요청과 같은 구조화된 프로토콜 메시지이든 수신자의 메일박스 파일에 대한 쓰기가 성공할 때만 메시지를 전송된 것으로 보고합니다. 쓰기가 실패하면(예: 디스크가 가득 찼거나 메일박스 디렉토리를 쓸 수 없는 경우), 전송 에이전트는 오류를 받고 아무것도 전송되지 않습니다. [팀원의 받은편지함에 쓰기 실패](/docs/ko/errors#failed-to-write-to-a-teammate-inbox)에서 오류 메시지 및 복구 단계를 참조합니다.275Claude Code는 메시지가 일반 텍스트이든 계획 승인이나 종료 요청과 같은 구조화된 프로토콜 메시지이든 수신자의 메일박스 파일에 대한 쓰기가 성공할 때만 메시지를 전송된 것으로 보고합니다. 쓰기가 실패하면(예: 디스크가 가득 찼거나 메일박스 디렉토리를 쓸 수 없는 경우), 전송 에이전트는 오류를 받고 아무것도 전송되지 않습니다. [팀원의 받은편지함에 쓰기 실패](/docs/ko/errors#failed-to-write-to-a-teammate-inbox)에서 오류 메시지 및 복구 단계를 참조합니다.

276 276 

309* **`model`**: Claude Code는 생성 프롬프트가 모델을 명명하지 않을 때 두 표시 모드에서 정의의 `model`을 사용합니다. [Claude Code가 팀원의 모델을 선택하는 방법](#specify-teammates-and-models)을 참조합니다.309* **`model`**: Claude Code는 생성 프롬프트가 모델을 명명하지 않을 때 두 표시 모드에서 정의의 `model`을 사용합니다. [Claude Code가 팀원의 모델을 선택하는 방법](#specify-teammates-and-models)을 참조합니다.

310* **`disallowedTools`**: 프로세스 내 팀원의 경우, Claude Code는 정의의 `disallowedTools`에 있는 도구를 팀원의 도구 세트에서 제거합니다. `SendMessage`와 Claude Code가 추가하는 Task 도구는 목록에 이름이 있더라도 계속 사용할 수 있습니다.310* **`disallowedTools`**: 프로세스 내 팀원의 경우, Claude Code는 정의의 `disallowedTools`에 있는 도구를 팀원의 도구 세트에서 제거합니다. `SendMessage`와 Claude Code가 추가하는 Task 도구는 목록에 이름이 있더라도 계속 사용할 수 있습니다.

311* **`effort`**: 프로세스 내 팀원의 경우, Claude Code는 [frontmatter effort 규칙](/docs/ko/model-config#set-the-effort-level)에 따라 정의의 [`effort`](/docs/ko/sub-agents#supported-frontmatter-fields)를 적용합니다.311* **`effort`**: 프로세스 내 팀원의 경우, Claude Code는 [frontmatter effort 규칙](/docs/ko/model-config#set-the-effort-level)에 따라 정의의 [`effort`](/docs/ko/sub-agents#supported-frontmatter-fields)를 적용합니다.

312* **`autoCompactWindow`**: 프로세스 내 팀원의 경우, Claude Code는 [해당 필드의 규칙](/docs/ko/sub-agents#subagent-auto-compact-window)에 따라 정의의 [`autoCompactWindow`](/docs/ko/sub-agents#supported-frontmatter-fields)를 적용합니다. 분할 창 팀원은 이 필드를 무시합니다. Claude Code v2.1.296 이상이 필요합니다.

312* **본문**: 프로세스 내 팀원의 경우, Claude Code는 정의의 본문을 기본 시스템 프롬프트에 추가 지시로 추가합니다. 분할 창 팀원의 경우, Claude Code는 본문을 기본 시스템 프롬프트 대신 사용합니다.313* **본문**: 프로세스 내 팀원의 경우, Claude Code는 정의의 본문을 기본 시스템 프롬프트에 추가 지시로 추가합니다. 분할 창 팀원의 경우, Claude Code는 본문을 기본 시스템 프롬프트 대신 사용합니다.

313* **`skills`**: Claude Code는 두 표시 모드에서 팀원에게 정의의 `skills`을 적용하지 않습니다. 팀원은 프로젝트 및 사용자 설정에서 skills을 로드합니다.314* **`skills`**: Claude Code는 두 표시 모드에서 팀원에게 정의의 `skills`을 적용하지 않습니다. 팀원은 프로젝트 및 사용자 설정에서 skills을 로드합니다.

314* **`mcpServers`**: 분할 창 팀원의 경우, Claude Code는 [해당 필드의 규칙](/docs/ko/sub-agents#scope-mcp-servers-to-a-subagent)에 따라 정의의 `mcpServers`를 적용하며, 이는 `--agent`로 시작된 세션도 포함합니다. 프로세스 내 팀원은 필드를 무시하고 프로젝트 및 사용자 설정에서 MCP 서버를 로드합니다.315* **`mcpServers`**: 분할 창 팀원의 경우, Claude Code는 [해당 필드의 규칙](/docs/ko/sub-agents#scope-mcp-servers-to-a-subagent)에 따라 정의의 `mcpServers`를 적용하며, 이는 `--agent`로 시작된 세션도 포함합니다. 프로세스 내 팀원은 필드를 무시하고 프로젝트 및 사용자 설정에서 MCP 서버를 로드합니다.

50 </Step>50 </Step>

51 51 

52 <Step title="엿보기 및 답변">52 <Step title="엿보기 및 답변">

53 화살표 키로 행을 선택하고 `Space`를 눌러 엿보기 패널을 엽니다. 전체 대화 기록이 아닌 세션의 가장 최근 출력 또는 기다리고 있는 질문을 표시합니다. 답변을 입력하고 `Enter`를 눌러 에이전트 뷰를 떠나지 않고 전송합니다.53 화살표 키로 행을 선택하고 `Space`를 눌러 엿보기 패널을 엽니다. 전체 트랜스크립트가 아닌 세션의 가장 최근 출력 또는 기다리고 있는 질문을 표시합니다. 답변을 입력하고 `Enter`를 눌러 에이전트 뷰를 떠나지 않고 전송합니다.

54 </Step>54 </Step>

55 55 

56 <Step title="연결 및 분리">56 <Step title="연결 및 분리">

57 전체 대화를 원할 때 행에서 `Enter` 또는 `→`를 눌러 연결합니다. 세션이 전체 대화형 Claude Code 세션으로 터미널을 인수합니다. 빈 프롬프트에서 `←`를 눌러 분리하고 테이블로 돌아갑니다.57 전체 대화를 원할 때 행에서 `Enter` 또는 `→`를 눌러 연결합니다. 세션이 전체 대화형 Claude Code 세션으로 터미널을 차지합니다. 빈 프롬프트에서 `←`를 눌러 분리하고 테이블로 돌아갑니다.

58 </Step>58 </Step>

59 59 

60 <Step title="기존 세션 가져오기">60 <Step title="기존 세션 가져오기">

64 </Step>64 </Step>

65</Steps>65</Steps>

66 66 

67일반 `claude` 세션 내에서 프롬프트 푸터의 `←` 힌트는 `← 2 agents`와 같이 입력을 기다리는 백그라운드 에이전트의 수를 세고, 입력이 필요한 에이전트가 없을 때 `← for agents`로 돌아갑니다. 99 이상의 개수는 `99+`로 표시됩니다. 개수는 터미널이 포커스되어 있는 동안 약 10초마다 새로 고쳐지고 포커스가 돌아올 때 즉시 새로 고쳐집니다. 이동할 때와 에이전트가 완료될 때 색상이 잠깐 변하며, 백그라운드 세션이 입력이 필요한 에이전트가 없을 때 완료되면 `← 2 done`과 같이 완료된 개수를 잠깐 표시합니다. [`prefersReducedMotion` 설정](/docs/ko/settings-reference#prefersreducedmotion)이 켜져 있으면 두 플래시 모두 꺼지며, [화면 읽기 모드](/docs/ko/accessibility)에서는 힌트가 숨겨집니다.67일반 `claude` 세션 내에서 프롬프트 푸터의 `←` 힌트는 `← 2 agents`와 같이 입력을 기다리는 백그라운드 에이전트의 수를 세고, 입력이 필요한 에이전트가 없을 때 `← for agents`로 돌아갑니다. 99를 초과하는 개수는 `99+`로 표시됩니다. 개수는 터미널이 포커스되어 있는 동안 약 10초마다 새로 고쳐지고 포커스가 돌아올 때 즉시 새로 고쳐집니다. 이동할 때와 에이전트가 완료될 때 색상이 잠깐 변하며, 백그라운드 세션이 입력이 필요한 에이전트가 없을 때 완료되면 `← 2 done`과 같이 완료된 개수를 잠깐 표시합니다. [`prefersReducedMotion` 설정](/docs/ko/settings-reference#prefersreducedmotion)이 켜져 있으면 두 플래시 모두 꺼지며, [화면 읽기 모드](/docs/ko/accessibility)에서는 힌트가 숨겨집니다.

68 68 

69<h3 id="open-agent-view-by-default">69<h3 id="open-agent-view-by-default">

70 기본적으로 에이전트 뷰 열기70 기본적으로 에이전트 뷰 열기

290 290 

291`←`를 누른 행은 화살표 키 또는 마우스로 선택을 이동한 후에도 굵고 흐릿하지 않은 이름을 유지하므로 어느 세션에서 왔는지 알 수 있습니다.291`←`를 누른 행은 화살표 키 또는 마우스로 선택을 이동한 후에도 굵고 흐릿하지 않은 이름을 유지하므로 어느 세션에서 왔는지 알 수 있습니다.

292 292 

293도구가 실행 중일 때 `←`를 누르면 Claude Code는 도구가 완료될 때까지 기다린 후 백그라운드로 보내며, Claude는 백그라운드 세션에서 응답을 계속합니다. 대신 기다리지 않고 즉시 백그라운드로 보내려면 `←`를 다시 누릅니다. 진행 중인 작업을 백그라운드 세션으로 이월할 수 없으면 Claude Code는 [`/background`](#from-inside-a-session)와 마찬가지로 `Background this session?` 대화 상자를 먼저 표시합니다.293도구가 실행 중일 때 `←`를 누르면 Claude Code는 도구가 완료될 때까지 기다린 후 백그라운드로 보내며, Claude는 백그라운드 세션에서 응답을 계속합니다. 대신 기다리지 않고 즉시 백그라운드로 보내려면 `←`를 다시 누릅니다. 진행 중인 백그라운드 작업을 백그라운드 세션으로 이월할 수 없으면 Claude Code는 [`/background`](#from-inside-a-session)와 마찬가지로 `Background this session?` 대화 상자를 먼저 표시합니다.

294 294 

295약 10초가 지나면 Claude Code는 더 이상 기다리지 않고 세션을 백그라운드로 보냅니다. 단, 다음과 같은 경우는 예외입니다:295약 10초가 지나면 Claude Code는 더 이상 기다리지 않고 세션을 백그라운드로 보냅니다. 단, 다음과 같은 경우는 예외입니다:

296 296 

219 자격 증명 캐싱 및 해결 시간 초과219 자격 증명 캐싱 및 해결 시간 초과

220</h4>220</h4>

221 221 

222Claude Code는 AWS 기본 자격 증명 공급자 체인을 한 번 해결하고 해결된 자격 증명을 메모리에 유지합니다. 만료되기 5분 전까지 또는 만료 기한이 없을 때 1시간 동안 재사용하므로 SSO 기반 프로필은 자격 증명 수명당 약 한 번 IAM Identity Center에서 자격 증명을 요청합니다. API의 자격 증명 오류는 캐시를 지우고 재시도는 새로운 자격 증명을 해결합니다. Claude Code v2.1.207 이상이 필요합니다.222Claude Code는 AWS 기본 자격 증명 공급자 체인을 한 번 해결하고 해결된 자격 증명을 메모리에 유지합니다. 만료되기 5분 전까지 또는 만료 기한이 없을 때 1시간 동안 재사용하므로 SSO 기반 프로필은 자격 증명 수명당 약 한 번 IAM Identity Center에서 자격 증명을 요청합니다. API의 자격 증명 오류는 캐시를 지우고 재시도는 새로운 자격 증명을 해결합니다.

223 223 

224캐시는 공급자 체인을 사용하지 않는 Amazon Bedrock API 키를 제외하고 이 단계의 시작 부분에 나열된 모든 자격 증명 방법을 포함합니다. 대신 모든 요청에서 체인을 해결하려면 [`CLAUDE_CODE_SKIP_AWS_CRED_CACHE=1`](/docs/ko/env-vars)을 설정합니다.224캐시는 공급자 체인을 사용하지 않는 Amazon Bedrock API 키를 제외하고 이 단계의 시작 부분에 나열된 모든 자격 증명 방법을 포함합니다. 대신 모든 요청에서 체인을 해결하려면 [`CLAUDE_CODE_SKIP_AWS_CRED_CACHE=1`](/docs/ko/env-vars)을 설정합니다.

225 225 

276 276 

277`Expiration`은 선택 사항입니다. 명령이 유효한 ISO 8601 `Expiration`을 반환하면 Claude Code는 해당 시간 5분 전까지 자격 증명을 캐시합니다. 없으면 자격 증명이 1시간 동안 캐시됩니다.277`Expiration`은 선택 사항입니다. 명령이 유효한 ISO 8601 `Expiration`을 반환하면 Claude Code는 해당 시간 5분 전까지 자격 증명을 캐시합니다. 없으면 자격 증명이 1시간 동안 캐시됩니다.

278 278 

279`awsCredentialExport`를 `awsAuthRefresh` 없이 구성하면 Claude Code는 내보낸 자격 증명을 직접 사용하고 시작 시 AWS 기본 자격 증명 공급자 체인을 다시 해결하지 않습니다. Claude Code v2.1.206 이상이 필요합니다.279`awsCredentialExport`를 `awsAuthRefresh` 없이 구성하면 Claude Code는 내보낸 자격 증명을 직접 사용하고 시작 시 AWS 기본 자격 증명 공급자 체인을 다시 해결하지 않습니다.

280 280 

281<h3 id="3-configure-claude-code">281<h3 id="3-configure-claude-code">

282 3. Claude Code 구성282 3. Claude Code 구성

358* 백그라운드 작업에 Haiku를 사용하려면 `ANTHROPIC_DEFAULT_HAIKU_MODEL`을 계정에서 사용 가능한 모델 ID로 설정합니다.358* 백그라운드 작업에 Haiku를 사용하려면 `ANTHROPIC_DEFAULT_HAIKU_MODEL`을 계정에서 사용 가능한 모델 ID로 설정합니다.

359 359 

360<Warning>360<Warning>

361 Opus 모델은 Sonnet 모델보다 토큰당 가격이 높으므로 기본 모델을 고정하지 않는 배포는 v2.1.207 이상으로 업데이트되면 Opus 요금으로 청구됩니다. Sonnet 4.5를 기본 모델로 유지하려면 `ANTHROPIC_MODEL`을 전체 모델 ID로 설정합니다. `ANTHROPIC_DEFAULT_SONNET_MODEL`로 기본값을 조종하고 `ANTHROPIC_DEFAULT_OPUS_MODEL`을 설정하지 않는 배포는 조종된 Sonnet 모델을 기본값으로 유지합니다.361 Opus 모델은 Sonnet 모델보다 토큰당 가격이 높으므로 기본 모델을 고정하지 않으면 Opus 요금으로 청구됩니다. Sonnet 4.5를 기본 모델로 사용하려면 `ANTHROPIC_MODEL`을 전체 모델 ID로 설정합니다. `ANTHROPIC_DEFAULT_SONNET_MODEL`로 기본값을 조종하고 `ANTHROPIC_DEFAULT_OPUS_MODEL`을 설정하지 않는 배포는 조종된 Sonnet 모델을 기본값으로 유지합니다.

362</Warning>362</Warning>

363 363 

364v2.1.280 이전에는 Amazon Bedrock의 기본 모델이 Opus 5로 기본값이 지정되었고 `opus` 별칭은 v2.1.219부터 Opus 5로 해결되었습니다. v2.1.207부터 v2.1.218에서 Amazon Bedrock의 기본 모델은 Opus 4.8로 기본값이 지정되었고 `opus` 별칭은 Opus 4.8로 해결되었습니다. v2.1.207 이전에는 기본 모델이 Sonnet 4.5로 기본값이 지정되었고, `opus` 별칭은 Opus 4.6으로 해결되었으며, 백그라운드 작업은 항상 기본 모델을 사용했습니다.364v2.1.280 이전에는 Amazon Bedrock의 기본 모델이 Opus 5로 기본값이 지정되었고 `opus` 별칭은 v2.1.219부터 Opus 5로 해결되었습니다. v2.1.207부터 v2.1.218에서 Amazon Bedrock의 기본 모델은 Opus 4.8로 기본값이 지정되었고 `opus` 별칭은 Opus 4.8로 해결되었습니다.

365 365 

366모델을 추가로 사용자 정의하려면 다음 방법 중 하나를 사용합니다.366모델을 추가로 사용자 정의하려면 다음 방법 중 하나를 사용합니다.

367 367 

188 188 

189[권한 모드](/docs/ko/permission-modes)는 보낸 댓글이 도착할 때 Claude가 수행하는 작업을 결정합니다:189[권한 모드](/docs/ko/permission-modes)는 보낸 댓글이 도착할 때 Claude가 수행하는 작업을 결정합니다:

190 190 

191* **Claude가 자동으로 답변합니다**: 권한 모드가 Claude가 당신에게 묻지 않고 답변을 게시하도록 허용할 때, Claude는 스레드를 읽고 답변하며, 댓글이 변경을 요청할 때 아티팩트를 편집합니다. `Auto-replied to comment thread on Artifact: <name>` 또는 `Auto-edited Artifact: <name> in response to a comment thread`가 표시됩니다.191* **Claude가 자동으로 답변합니다**: 권한 모드가 Claude가 사용자에게 묻지 않고 답변을 게시하도록 허용할 때, Claude는 스레드를 읽고 답변합니다. `Auto-replied to comment thread on Artifact: <name>`이 표시됩니다.

192* **Claude가 당신을 기다립니다**: 계획 모드 외부에서 답변 게시에 승인이 필요할 때, `Comments are waiting on Artifact: <name>`이 표시됩니다. Claude는 스레드를 읽을 승인을 요청하고, 다시 답변을 게시할 승인을 요청합니다.192* **Claude가 당신을 기다립니다**: 계획 모드 외부에서 답변 게시에 승인이 필요할 때, `Comments are waiting on Artifact: <name>`이 표시됩니다. Claude는 스레드를 읽을 승인을 요청하고, 다시 답변을 게시할 승인을 요청합니다.

193* **Claude가 계획 모드에서 일시 중지됩니다**: `Comments are waiting on Artifact: <name>`이 표시되고, 계획 모드를 종료하고 스레드를 읽고 답변하도록 요청할 때까지 Claude는 답변하지 않습니다.193* **Claude가 계획 모드에서 일시 중지됩니다**: `Comments are waiting on Artifact: <name>`이 표시되고, 계획 모드를 종료하고 스레드를 읽고 답변하도록 요청할 때까지 Claude는 답변하지 않습니다.

194 194 

58</h2>58</h2>

59 59 

60<Steps>60<Steps>

61 <Step title="Chrome으로 Claude Code 시작">61 <Step title="Chrome과 함께 Claude Code 실행하기">

62 `--chrome` 플래그로 Claude Code를 시작합니다:62 `--chrome` 플래그를 사용하여 Claude Code를 시작합니다.

63 63 

64 ```bash theme={null}64 ```bash theme={null}

65 claude --chrome65 claude --chrome

66 ```66 ```

67 67 

68 Chrome으로 처음 시작하면 Claude Code가 통합 기능을 소개하고 사이트 권한의 작동 방식을 설명하는 일회성 대화 상자를 표시합니다. Enter 키를 눌러 계속합니다.68 Chrome과 함께 처음 실행하면 Claude Code가 통합 기능을 소개하고 사이트 권한의 작동 방식을 설명하는 일회성 대화 상자를 표시합니다. Enter 키를 눌러 계속합니다.

69 69 

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

71 </Step>71 </Step>

72 72 

73 <Step title="Claude에게 브라우저 사용을 요청">73 <Step title="Claude에게 브라우저 사용 요청하기">

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

75 75 

76 ```text wrap theme={null}76 ```text wrap theme={null}

77 code.claude.com/docs로 이동하여 검색 상자를 클릭하고,77 Go to code.claude.com/docs, click on the search box,

78 "hooks"를 입력한 후 나타나는 결과를 알려주세요78 type "hooks", and tell me what results appear

79 ```79 ```

80 80 

81 Claude Code가 브라우저 작업 전에 권한을 요청하면 승인합니다. 대화 상자는 `Claude in Chrome wants to`로 시작하며, 세션 동안 해당 사이트의 모든 작업을 허용하는 옵션을 제공합니다. Claude가 새 탭을 열고 작업을 시작합니다.81 Claude Code가 브라우저 작업 전에 권한을 요청하면 승인합니다. 대화 상자는 `Claude in Chrome wants to`로 시작하며, 해당 세션 동안 그 사이트의 모든 작업을 허용하는 옵션을 제공합니다. Claude가 새 탭을 열고 작업을 시작합니다.

82 </Step>82 </Step>

83</Steps>83</Steps>

84 84 

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

86 86 

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

88 88 

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

90 90 

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

92 Claude가 요청할 때 확장 프로그램 설치92 Claude가 요청할 때 확장 프로그램 설치하기

93</h3>93</h3>

94 94 

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

96 96 

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

98 98 

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

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

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

102 102 

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

104 104 

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

106* 조직이 [관리형 세트와 함께 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는 설치 프롬프트를 표시하지 않습니다.106* 조직에서 [관리 대상 세트와 함께 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는 설치 프롬프트를 표시하지 않습니다.

107 107 

108<h3 id="enable-chrome-by-default">108<h3 id="enable-chrome-by-default">

109 기본적으로 Chrome 활성화109 기본으로 Chrome 활성화하기

110</h3>110</h3>

111 111 

112매번 `--chrome`을 전달하지 않고 Chrome을 연결하려면 CLI 세션에서 `/chrome`을 실행하고 **기본적으로 활성화**를 선택합니다. [VS Code 확장 프로그램](/docs/ko/vs-code#automate-browser-tasks-with-chrome)에서는 프롬프트 상자에 `/chrome`을 입력하고 **기본적으로 활성화** 스위치를 켭니다. 두 곳은 하나의 설정을 공유하므로 어느 쪽에서 켜든 CLI와 VS Code 모두에서 켜집니다.112매번 `--chrome`을 전달하지 않고 Chrome을 연결하려면 CLI 세션에서 `/chrome`을 실행하고 `Enabled by default`를 선택합니다. [VS Code 확장 프로그램](/docs/ko/vs-code#automate-browser-tasks-with-chrome)에서는 프롬프트 상자에 `/chrome`을 입력하고 `Enabled by default` 스위치를 켭니다. 두 곳은 하나의 설정을 공유하므로 어느 쪽에서 켜든 CLI와 VS Code 모두에서 켜집니다.

113 113 

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

115 115 

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

117 117 

118<Note>118<Note>

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

120</Note>120</Note>

121 121 

122<h3 id="manage-site-permissions">122<h3 id="manage-site-permissions">

123 사이트 권한 관리123 사이트 권한 관리하기

124</h3>124</h3>

125 125 

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

127 127 

128<h3 id="permission-prompts-in-vs-code-sessions">128<h3 id="permission-prompts-in-vs-code-sessions">

129 VS Code 세션의 권한 프롬프트129 VS Code 세션의 권한 프롬프트

130</h3>130</h3>

131 131 

132VS Code 세션에서 Claude Code가 브라우저 작업 전에 확인을 요청하면 프롬프트가 채팅 패널에 카드로 표시됩니다. 작업 대상이 허용하지 않은 사이트인 경우 카드에서 해당 사이트를 허용하는 옵션도 제공합니다.132VS Code 세션에서 Claude Code가 브라우저 작업 전에 확인을 요청하면 프롬프트가 채팅 패널에 카드 형태로 나타납니다. 작업 대상이 허용하지 않은 사이트인 경우 카드에서 해당 사이트를 허용하는 옵션도 제공합니다.

133 133 

134[기본적으로 활성화](#enable-chrome-by-default)가 켜져 있어 시작 시 브라우저에 연결된 세션에서는 Claude Code가 Manual, Edit automatically, Auto, Bypass permissions 모드에서 허용하지 않은 사이트에 대한 브라우저 작업 전에 확인을 요청합니다. Auto 및 Bypass permissions 모드에서는 해당 세션에서 `@browser`를 입력하기 전까지 이 동작이 적용됩니다.134[기본으로 Chrome 활성화](#enable-chrome-by-default)가 켜져 있어 시작 시 브라우저에 연결된 세션에서는, Manual, Edit automatically, Auto, Bypass permissions 모드에서 허용하지 않은 사이트에 대한 브라우저 작업 전에 Claude Code가 사용자에게 확인을 요청합니다. Auto 및 Bypass permissions 모드에서는 해당 세션에서 `@browser`를 입력할 때까지 이 동작이 적용됩니다.

135 135 

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

137 플랜 모드의 브라우저 도구137 플랜 모드의 브라우저 도구

138</h3>138</h3>

139 139 

140[플랜 모드](/docs/ko/permission-modes#analyze-before-you-edit-with-plan-mode)에서는 Claude가 GIF를 녹화하거나, 새 탭을 열거나, 단축키를 실행하기 전에 권한 프롬프트가 표시됩니다. 대화형 CLI 세션에서 [권한 우회 모드를 사용할 수 있고](/docs/ko/permission-modes#skip-all-checks-with-bypasspermissions-mode) [기능 플래그 가져오기](/docs/ko/env-vars#features-that-need-feature-flag-fetching)가 꺼져 있으면 이러한 호출은 프롬프트 없이 실행됩니다.140[플랜 모드](/docs/ko/permission-modes#analyze-before-you-edit-with-plan-mode)에서는 Claude가 GIF를 녹화하거나, 새 탭을 열거나, 단축키를 실행하기 전에 권한 프롬프트가 나타납니다. 대화형 CLI 세션에서 [bypass permissions 모드를 사용할 수 있고](/docs/ko/permission-modes#skip-all-checks-with-bypasspermissions-mode) [기능 플래그 가져오기](/docs/ko/env-vars#features-that-need-feature-flag-fetching)가 꺼져 있으면 이러한 호출은 프롬프트 없이 실행됩니다.

141 141 

142`createIfEmpty`를 설정하는 `tabs_context_mcp` 호출도 확인을 요청하며, 이러한 작업 중 하나라도 포함하는 `browser_batch` 호출도 마찬가지입니다.142`tabs_context_mcp` 호출도 `createIfEmpty`를 설정하면 확인을 요청하며, 이러한 작업 중 하나라도 포함하는 `browser_batch` 호출도 마찬가지입니다.

143 143 

144<h2 id="example-workflows">144<h2 id="example-workflows">

145 예제 워크플로145 예제 워크플로

858`models` 블록은 관리자가 선별하는 선택적 모델 목록으로, `/v1/models`에서 제공되며 업스트림별로 모델 ID를 변환하는 데 사용됩니다. 미국 이외의 Amazon Bedrock 지역, Amazon Bedrock 프로비저닝된 처리량 ARN 및 Microsoft Foundry 배포 이름에 필수입니다.858`models` 블록은 관리자가 선별하는 선택적 모델 목록으로, `/v1/models`에서 제공되며 업스트림별로 모델 ID를 변환하는 데 사용됩니다. 미국 이외의 Amazon Bedrock 지역, Amazon Bedrock 프로비저닝된 처리량 ARN 및 Microsoft Foundry 배포 이름에 필수입니다.

859 859 

860```yaml theme={null}860```yaml theme={null}

861auto_include_builtin_models: true # false: 아래 목록만 노출861auto_include_builtin_models: true # false: expose only the list below

862models:862models:

863 - id: claude-opus-4-8863 - id: claude-opus-4-8

864 label: Claude Opus 4.8864 label: Claude Opus 4.8

865 # description: 이를 표시하는 클라이언트에 나타나는 선택적 텍스트865 # description: optional text shown in clients that surface it

866 upstream_model:866 upstream_model:

867 anthropic: claude-opus-4-8867 anthropic: claude-opus-4-8

868 bedrock: us.anthropic.claude-opus-4-8 # 또는 추론 프로필 ARN868 bedrock: us.anthropic.claude-opus-4-8 # or an inference-profile ARN

869 foundry: your-opus-deployment-name869 foundry: your-opus-deployment-name

870```870```

871 871 

1020 policies:1020 policies:

1021 - match: {}1021 - match: {}

1022 cli:1022 cli:

1023 # 모델 액세스(/v1/messages에서도 서버 측으로 강제됨)1023 # Model access (also enforced server-side at /v1/messages)

1024 availableModels: [claude-opus-4-8, claude-sonnet-4-6, claude-haiku-4-5]1024 availableModels: [claude-opus-4-8, claude-sonnet-4-6, claude-haiku-4-5]

1025 enforceAvailableModels: true # Default가 목록 안에서 해석됨1025 enforceAvailableModels: true # Default resolves inside the list

1026 1026 

1027 # 권한 정책1027 # Permission policy

1028 permissions:1028 permissions:

1029 deny:1029 deny:

1030 - "WebFetch"1030 - "WebFetch"

1031 - "Read(./.env)"1031 - "Read(./.env)"

1032 - "Read(./secrets/**)"1032 - "Read(./secrets/**)"

1033 disableBypassPermissionsMode: disable # --dangerously-skip-permissions 차단1033 disableBypassPermissionsMode: disable # blocks --dangerously-skip-permissions

1034 allowManagedPermissionRulesOnly: true # 사용자/프로젝트 권한 규칙 무시1034 allowManagedPermissionRulesOnly: true # ignore user/project permission rules

1035 1035 

1036 # CLI 프로세스로 푸시되는 환경입니다. DISABLE_UPDATES는 백그라운드 및1036 # Environment pushed into the CLI process. DISABLE_UPDATES blocks

1037 # 수동 업데이트를 차단하고, DISABLE_AUTOUPDATER는 백그라운드1037 # background and manual updates; DISABLE_AUTOUPDATER stops only

1038 # 업데이트만 중지합니다.1038 # background updates.

1039 env:1039 env:

1040 DISABLE_UPDATES: "1" # 자체 배포를 통해 버전 고정1040 DISABLE_UPDATES: "1" # pin versions via your own distribution

1041 1041 

1042 # 조직 전체 훅입니다. 훅 명령은 게이트웨이가 아닌 개발자 머신에서1042 # Org-wide hooks. Hook commands run on developer machines, not the

1043 # 실행되므로, 경로는 정책 대상의 모든 클라이언트 OS에 존재해야 합니다.1043 # gateway, so the path must exist on every client OS in the policy.

1044 hooks:1044 hooks:

1045 PostToolUse:1045 PostToolUse:

1046 - matcher: "Edit|Write"1046 - matcher: "Edit|Write"

1074 1074 

1075게이트웨이의 [텔레메트리](#telemetry) 구성은 `OTEL_EXPORTER_OTLP_ENDPOINT`를 푸시하므로, `telemetry.forward_to`를 설정하면 각 대화형 클라이언트에서 대화 상자가 표시됩니다. 이 대화 상자는 손상되었거나 악의적인 게이트웨이로부터 개발자의 머신을 보호하는 것이지, 개발자로부터 조직을 보호하는 것이 아닙니다.1075게이트웨이의 [텔레메트리](#telemetry) 구성은 `OTEL_EXPORTER_OTLP_ENDPOINT`를 푸시하므로, `telemetry.forward_to`를 설정하면 각 대화형 클라이언트에서 대화 상자가 표시됩니다. 이 대화 상자는 손상되었거나 악의적인 게이트웨이로부터 개발자의 머신을 보호하는 것이지, 개발자로부터 조직을 보호하는 것이 아닙니다.

1076 1076 

1077`claude -p`, Agent SDK 세션, Claude Desktop의 Code 탭 세션 같은 [비대화형 실행](/docs/ko/server-managed-settings#security-approval-dialogs)은 대화 상자를 표시할 수 없습니다. 비대화형 실행은 푸시된 설정을 해당 실행에만 적용하고 승인된 것으로 기록하지 않으므로, 개발자의 다음 대화형 세션에서는 여전히 대화 상자가 표시됩니다. v2.1.207 이전에는 비대화형 실행이 설정을 승인된 것으로 저장했으므로, 이후의 대화형 세션에서 해당 설정에 대한 대화 상자가 표시되지 않았습니다.1077`claude -p`, Agent SDK 세션, Claude Desktop의 Code 탭 세션 같은 [비대화형 실행](/docs/ko/server-managed-settings#security-approval-dialogs)은 대화 상자를 표시할 수 없습니다. 이 경우 해당 실행에 한해 푸시된 설정을 적용하고 승인된 것으로 기록하지 않으므로, 개발자의 다음 대화형 세션에서는 여전히 대화 상자가 표시됩니다.

1078 1078 

1079개발자가 거부하면 Claude Code는 정책을 적용하는 대신 해당 세션을 종료합니다. 따라서 새 훅이나 대화 상자를 표시하는 env 변수를 광범위한 정책으로 푸시하면, 일치하는 모든 개발자가 대화형 세션에서 대화 상자를 보게 됩니다. 실행 중인 대화형 세션은 다음 시간별 폴링 시 이를 표시하며, 그렇지 않으면 개발자가 다음에 대화형 세션을 시작할 때 나타납니다.1079개발자가 거부하면 Claude Code는 정책을 적용하는 대신 해당 세션을 종료합니다. 따라서 새 훅이나 대화 상자를 표시하는 env 변수를 광범위한 정책으로 푸시하면, 일치하는 모든 개발자가 대화형 세션에서 대화 상자를 보게 됩니다. 실행 중인 대화형 세션은 다음 시간별 폴링 시 이를 표시하며, 그렇지 않으면 개발자가 다음에 대화형 세션을 시작할 때 나타납니다.

1080 1080 

1502```yaml theme={null}1502```yaml theme={null}

1503load_test_mode:1503load_test_mode:

1504 enabled: true1504 enabled: true

1505 reply_tokens: 750 # 각 준비된 응답에 담기는 텍스트의 대략적인 토큰 수1505 reply_tokens: 750 # roughly how many tokens of text each canned reply carries

1506 reply_seconds: 9.5 # 스트리밍 응답에 걸리는 시간1506 reply_seconds: 9.5 # how long a streamed reply takes

1507```1507```

1508 1508 

1509| 필드 | 필수 | 설명 |1509| 필드 | 필수 | 설명 |

392 392 

393질문 및 피드백은 [Claude Code 지원](https://support.claude.com/en/collections/14445694-claude-code)을 사용하거나 [Claude Code GitHub 저장소](https://github.com/anthropics/claude-code/issues)에서 이슈를 열어주세요. Anthropic 계정 팀에 문의할 수도 있습니다. 문제를 보고할 때 다음을 포함하세요:393질문 및 피드백은 [Claude Code 지원](https://support.claude.com/en/collections/14445694-claude-code)을 사용하거나 [Claude Code GitHub 저장소](https://github.com/anthropics/claude-code/issues)에서 이슈를 열어주세요. Anthropic 계정 팀에 문의할 수도 있습니다. 문제를 보고할 때 다음을 포함하세요:

394 394 

395* **Gateway 문제**: 해당 창의 gateway stderr, 비밀번호가 제거된 `gateway.yaml`, `/`의 랜딩 페이지에 표시된 gateway 버전, `/managed/settings`의 `x-cc-gateway-version` 응답 헤더, 최근에 변경된 사항395* **Gateway 문제**: 해당 창의 gateway stderr, 시크릿을 가린 `gateway.yaml`, `/`의 랜딩 페이지에 표시된 gateway 버전, `/managed/settings`의 `x-cc-gateway-version` 응답 헤더, 최근에 변경된 사항

396* **로그인 문제**: 개발자가 `claude --debug-file ./claude-debug.txt`를 실행하고 재현한 후 해당 파일과 동일한 창의 gateway 감사 로그를 전송396* **로그인 문제**: 개발자가 `claude --debug-file ./claude-debug.txt`를 실행하고 재현한 후 해당 파일과 동일한 창의 gateway 감사 로그를 전송

397* **추론 문제**: 요청된 모델, 구성된 업스트림, 요청에 대한 gateway 감사 로그(어느 업스트림이 제공했는지 및 응답 상태 기록)397* **추론 문제**: 요청된 모델, 구성된 업스트림, 요청에 대한 gateway 감사 로그(어느 업스트림이 제공했는지 및 응답 상태 기록)

398 398 

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

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

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

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

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

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

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

298 298 

299클라우드 세션은 텍스트 출력을 생성하는 [기본 제공 명령](/docs/ko/commands)을 지원합니다. `/plugin` 또는 `/resume`과 같이 터미널 인터페이스에서만 실행되는 명령은 사용할 수 없습니다. 터미널에서 선택기 또는 패널을 열어야 하는 명령은 클라우드 세션에서 다르게 작동합니다:299클라우드 세션은 텍스트 출력을 생성하는 [기본 제공 명령](/docs/ko/commands)을 지원합니다. `/plugin` 또는 `/resume`과 같이 터미널 인터페이스에서만 실행되는 명령은 사용할 수 없습니다. 터미널에서 선택기 또는 패널을 열어야 하는 명령은 클라우드 세션에서 다르게 작동합니다:

300 300 

301* **`/model`, `/effort`, `/color`, 및 `/rename`**: 터미널 선택기 또는 슬라이더를 열지 않고 대신 인수로 값을 전달합니다(예: `/model sonnet`). 인수 형식은 세션의 환경에서 Claude Code v2.1.205 이상이 필요하며 각 명령의 [가용성 참고 사항](/docs/ko/commands#all-commands)을 따릅니다.301* **`/model`, `/effort`, `/color`, 및 `/rename`**: 터미널 선택기 또는 슬라이더를 열지 않고 대신 인수로 값을 전달합니다(예: `/model sonnet`). 인수 형식은 각 명령의 [가용성 참고 사항](/docs/ko/commands#all-commands)을 따릅니다.

302* **`/fast`**: 빠른 모드가 [계정에서 사용 가능](/docs/ko/fast-mode#requirements)할 때 세션에 대해 [빠른 모드](/docs/ko/fast-mode#use-fast-mode-in-cloud-sessions)를 전환합니다. 세션의 환경에서 Claude Code v2.1.271 이상이 필요합니다.302* **`/fast`**: 빠른 모드가 [계정에서 사용 가능](/docs/ko/fast-mode#requirements)할 때 세션에 대해 [빠른 모드](/docs/ko/fast-mode#use-fast-mode-in-cloud-sessions)를 전환합니다. 세션의 환경에서 Claude Code v2.1.271 이상이 필요합니다.

303* **`/config`**: 웹에서는 값을 설정하는 대신 Claude Code 설정 섹션을 열며, `key=value`를 포함한 명령 뒤의 텍스트는 무시됩니다. 클라우드 세션의 설정을 변경하려면 환경에 [환경 변수](/docs/ko/cloud-environments#set-environment-variables)를 설정하거나, 하나의 저장소가 있는 세션에서 해당 저장소의 `.claude/settings.json`에 키를 커밋하세요. [클라우드 세션의 설정](/docs/ko/settings#settings-in-cloud-sessions)에서 각 세션이 읽는 내용을 나열합니다.303* **`/config`**: 웹에서는 값을 설정하는 대신 Claude Code 설정 섹션을 열며, `key=value`를 포함한 명령 뒤의 텍스트는 무시됩니다. 클라우드 세션의 설정을 변경하려면 환경에 [환경 변수](/docs/ko/cloud-environments#set-environment-variables)를 설정하거나, 하나의 저장소가 있는 세션에서 해당 저장소의 `.claude/settings.json`에 키를 커밋하세요. [클라우드 세션의 설정](/docs/ko/settings#settings-in-cloud-sessions)에서 각 세션이 읽는 내용을 나열합니다.

304 304 

420* **격리된 가상 머신**: 각 세션은 격리된 Anthropic 관리 VM에서 실행됩니다. 조직이 [자체 호스팅 환경](/docs/ko/self-hosted-environments)으로 라우팅하는 세션은 자신의 인프라에서 실행되며, 격리는 배포의 책임입니다420* **격리된 가상 머신**: 각 세션은 격리된 Anthropic 관리 VM에서 실행됩니다. 조직이 [자체 호스팅 환경](/docs/ko/self-hosted-environments)으로 라우팅하는 세션은 자신의 인프라에서 실행되며, 격리는 배포의 책임입니다

421* <span id="default-allowed-domains" />**네트워크 액세스 제어**: Anthropic 호스팅 환경에서 네트워크 액세스는 기본적으로 제한되며 비활성화할 수 있습니다. 액세스 수준, [기본 허용 도메인](/docs/ko/cloud-environments#default-allowed-domains), 그리고 허용 목록을 통과하지 않는 트래픽에 대해서는 [네트워크 액세스](/docs/ko/cloud-environments#network-access)를 참조하세요. 자체 호스팅 환경에서는 자신의 네트워크 경계에서 세션 송신을 제한합니다. 네트워크 액세스가 비활성화된 상태에서 실행할 때 Claude Code는 여전히 Anthropic API와 통신할 수 있으며, 이는 VM에서 데이터가 나갈 수 있습니다.421* <span id="default-allowed-domains" />**네트워크 액세스 제어**: Anthropic 호스팅 환경에서 네트워크 액세스는 기본적으로 제한되며 비활성화할 수 있습니다. 액세스 수준, [기본 허용 도메인](/docs/ko/cloud-environments#default-allowed-domains), 그리고 허용 목록을 통과하지 않는 트래픽에 대해서는 [네트워크 액세스](/docs/ko/cloud-environments#network-access)를 참조하세요. 자체 호스팅 환경에서는 자신의 네트워크 경계에서 세션 송신을 제한합니다. 네트워크 액세스가 비활성화된 상태에서 실행할 때 Claude Code는 여전히 Anthropic API와 통신할 수 있으며, 이는 VM에서 데이터가 나갈 수 있습니다.

422* **자격 증명 보호**: Anthropic 호스팅 환경에서 git 자격 증명 및 서명 키는 샌드박스 외부에 유지되며, 프록시는 범위 자격 증명으로 세션을 대신하여 인증합니다. 자체 호스팅 환경에서 배포는 git 자격 증명을 제공합니다. [git 구성](/docs/ko/self-hosted-environments-deploy#configure-git)을 참조하세요422* **자격 증명 보호**: Anthropic 호스팅 환경에서 git 자격 증명 및 서명 키는 샌드박스 외부에 유지되며, 프록시는 범위 자격 증명으로 세션을 대신하여 인증합니다. 자체 호스팅 환경에서 배포는 git 자격 증명을 제공합니다. [git 구성](/docs/ko/self-hosted-environments-deploy#configure-git)을 참조하세요

423* **네트워크 시크릿**: Anthropic 호스팅 환경의 Pro 및 Max 플랜에서 [클라우드 환경에 추가한](/docs/ko/cloud-environments#add-network-secrets) 키는 샌드박스 외부에 동일한 방식으로 유지되며, 세션을 떠난 후 일치하는 요청에 첨부됩니다. 자체 호스팅 환경에는 네트워크 시크릿이 없으며 Team 및 Enterprise 플랜에는 아직 없습니다423* **네트워크 시크릿**: Anthropic 호스팅 환경에서 [클라우드 환경에 추가한](/docs/ko/cloud-environments#add-network-secrets) 키는 샌드박스 외부에 동일한 방식으로 유지되며, 세션을 떠난 후 일치하는 요청에 첨부됩니다. 자체 호스팅 환경에는 네트워크 시크릿이 없습니다

424* **안전한 분석**: 코드는 PR을 생성하기 전에 세션의 격리된 환경 내에서 분석 및 수정됩니다424* **안전한 분석**: 코드는 PR을 생성하기 전에 세션의 격리된 환경 내에서 분석 및 수정됩니다

425 425 

426<h2 id="troubleshooting">426<h2 id="troubleshooting">

472| 메시지 | 의미 |472| 메시지 | 의미 |

473| - | - |473| - | - |

474| `Cloud sessions aren't available with <provider>. They run on Anthropic's infrastructure and require an Anthropic account.` | Claude Code가 타사 제공자용으로 구성되어 있습니다. 메시지에는 `Amazon Bedrock` 또는 `Google Vertex AI`와 같이 구성에서 사용하는 레이블로 제공자 이름이 표시됩니다. 예를 들어 `CLAUDE_CODE_USE_BEDROCK`의 설정을 해제하는 방식으로 해당 제공자의 구성을 제거하고 Anthropic 계정으로 로그인하세요(`claude auth login`). |474| `Cloud sessions aren't available with <provider>. They run on Anthropic's infrastructure and require an Anthropic account.` | Claude Code가 타사 제공자용으로 구성되어 있습니다. 메시지에는 `Amazon Bedrock` 또는 `Google Vertex AI`와 같이 구성에서 사용하는 레이블로 제공자 이름이 표시됩니다. 예를 들어 `CLAUDE_CODE_USE_BEDROCK`의 설정을 해제하는 방식으로 해당 제공자의 구성을 제거하고 Anthropic 계정으로 로그인하세요(`claude auth login`). |

475| `Cloud sessions are disabled by your organization's policy. Contact your organization admin to enable them.` | `allow_remote_sessions` 조직 정책이 꺼져 있습니다. |475| `Cloud sessions are disabled by your organization's policy. Contact your organization admin to enable them.` | `allow_remote_sessions` 조직 정책이 꺼져 있습니다. [Cloud sessions are disabled by your organization's policy](/docs/ko/errors#cloud-sessions-are-disabled-by-your-organizations-policy)를 참조하세요. 메시지에 대신 이 세션이 사용 중인 자격 증명이 표시되면 [클라우드 세션은 claude.ai 로그인을 사용합니다](/docs/ko/errors#cloud-sessions-use-your-claude-ai-login)를 참조하세요. |

476| `Couldn't verify your organization's policy for cloud sessions. Check your network connection and try again.` | Claude Code가 조직의 정책을 가져올 수 없어서 클라우드 세션이 허용된다고 가정하는 대신 전송을 거부합니다. 네트워크 연결을 확인하고 다시 시도하세요. |476| `Couldn't verify your organization's policy for cloud sessions. Check your network connection and try again.` | Claude Code가 조직의 정책 로드를 아직 완료하지 않아서 클라우드 세션이 허용된다고 가정하는 대신 전송을 거부합니다. 네트워크 연결을 확인하고 다시 시도하세요. |

477| `Cloud sessions aren't available:` 뒤에 원인이 표시됨 | 조직의 정책을 로드하지 못했으며, 메시지의 나머지 부분에 그 이유가 표시됩니다. 표시된 원인에 따라 조치하세요. [Couldn't verify your organization's policy for cloud sessions](/docs/ko/errors#couldnt-verify-your-organizations-policy-for-cloud-sessions)를 참조하세요. |

477| `Attaching to an existing cloud session is not enabled for your account.` | `-p` 없이 `--cloud <session-id>`를 실행했습니다. `claude -p "your message" --cloud <session-id>`로 메시지를 보내세요. |478| `Attaching to an existing cloud session is not enabled for your account.` | `-p` 없이 `--cloud <session-id>`를 실행했습니다. `claude -p "your message" --cloud <session-id>`로 메시지를 보내세요. |

478| `Session not found: <id>` | ID 또는 URL이 액세스할 수 있는 세션과 일치하지 않습니다. 세션의 claude.ai/code URL과 대조하여 확인하세요. |479| `Session not found: <id>` | ID 또는 URL이 액세스할 수 있는 세션과 일치하지 않습니다. 세션의 claude.ai/code URL과 대조하여 확인하세요. |

479| `cloud session <id> is archived and cannot accept new messages` | 세션이 보관되었습니다. 대신 새 세션을 시작하세요. |480| `cloud session <id> is archived and cannot accept new messages` | 세션이 보관되었습니다. 대신 새 세션을 시작하세요. |

1525| - | - | - |1525| - | - | - |

1526| `skills/<name>/SKILL.md` | `name`, `description`, `when_to_use`, `argument-hint`, `arguments`, `disable-model-invocation`, `user-invocable`, `allowed-tools`, `disallowed-tools`, `model`, `effort`, `context`, `agent`, `background`, `hooks`, `paths`, `shell`, `metadata`, `license`, `compatibility` | [Skill 프론트매터](/docs/ko/skills#frontmatter-reference) |1526| `skills/<name>/SKILL.md` | `name`, `description`, `when_to_use`, `argument-hint`, `arguments`, `disable-model-invocation`, `user-invocable`, `allowed-tools`, `disallowed-tools`, `model`, `effort`, `context`, `agent`, `background`, `hooks`, `paths`, `shell`, `metadata`, `license`, `compatibility` | [Skill 프론트매터](/docs/ko/skills#frontmatter-reference) |

1527| `commands/*.md` | `name`과 `paths`를 제외한 skill 필드 | [Skill 프론트매터](/docs/ko/skills#frontmatter-reference) |1527| `commands/*.md` | `name`과 `paths`를 제외한 skill 필드 | [Skill 프론트매터](/docs/ko/skills#frontmatter-reference) |

1528| `agents/*.md` | `name`, `description`, `tools`, `disallowedTools`, `model`, `permissionMode`, `maxTurns`, `skills`, `mcpServers`, `hooks`, `memory`, `background`, `effort`, `isolation`, `color`, `initialPrompt`, `omitClaudeMd`, `experimental` | [Subagent 프론트매터](/docs/ko/sub-agents#supported-frontmatter-fields) |1528| `agents/*.md` | `name`, `description`, `tools`, `disallowedTools`, `model`, `permissionMode`, `maxTurns`, `autoCompactWindow`, `skills`, `mcpServers`, `hooks`, `memory`, `background`, `effort`, `isolation`, `color`, `initialPrompt`, `omitClaudeMd`, `experimental` | [서브에이전트 frontmatter](/docs/ko/sub-agents#supported-frontmatter-fields) |

1529| `output-styles/*.md` | `name`, `description`, `keep-coding-instructions`, `force-for-plugin` | [Output style 프론트매터](/docs/ko/output-styles#frontmatter) |1529| `output-styles/*.md` | `name`, `description`, `keep-coding-instructions`, `force-for-plugin` | [Output style 프론트매터](/docs/ko/output-styles#frontmatter) |

1530| `rules/*.md` | `paths` | [Rule 프론트매터](/docs/ko/memory#rules-frontmatter-reference) |1530| `rules/*.md` | `paths` | [Rule 프론트매터](/docs/ko/memory#rules-frontmatter-reference) |

1531 1531 

291 291 

292Claude Platform on AWS는 직접 Claude API와 동일한 모델 ID를 사용합니다.292Claude Platform on AWS는 직접 Claude API와 동일한 모델 ID를 사용합니다.

293 293 

294기본 별칭 `fable`, `opus`, `sonnet` 및 `haiku`는 Claude Platform on AWS에 대한 Claude Code의 기본 제공 기본값으로 확인되며, 이는 최신 릴리스보다 뒤떨어질 수 있습니다. `ANTHROPIC_DEFAULT_OPUS_MODEL` 없이 `opus` 별칭은 Opus 5.5로 확인됩니다. v2.1.280 이전에는 v2.1.219부터 Opus 5로 확인되었으며, v2.1.207부터 Opus 4.8로 확인되었고, 그 이전에는 Opus 4.7로 확인되었습니다.294기본 별칭 `fable`, `opus`, `sonnet` 및 `haiku`는 Claude Platform on AWS에 대한 Claude Code의 기본 제공 기본값으로 확인되며, 이는 최신 릴리스보다 뒤떨어질 수 있습니다. `ANTHROPIC_DEFAULT_OPUS_MODEL` 없이 `opus` 별칭은 Opus 5.5로 확인됩니다. v2.1.280 이전에는 v2.1.219부터 Opus 5로 확인되었으며, v2.1.207부터 Opus 4.8로 확인되었습니다.

295 295 

296Claude Code를 팀에 배포하는 경우 모델 ID를 명시적으로 고정하여 새 릴리스가 모든 사람을 한 번에 이동하지 않도록 하십시오.296Claude Code를 팀에 배포하는 경우 모델 ID를 명시적으로 고정하여 새 릴리스가 모든 사람을 한 번에 이동하지 않도록 하십시오.

297 297 

347예를 들어:347예를 들어:

348 348 

349```text theme={null}349```text theme={null}

350이 프로젝트는 payments API의 p95 지연 시간을 200ms 이하로 유지합니다: 프로파일링, 쿼리 및 캐싱 수정, 그리고 이에 따른 의존성 업그레이드를 payments-api 저장소에서 수행합니다.350This project holds p95 latency for the payments API under 200 ms: profiling, query and caching fixes, and the dependency upgrades that come with them, in the payments-api repository.

351 351 

352- main에서 브랜치를 만들고 스레드당 하나의 드래프트 풀 리퀘스트를 엽니다.352- Branch from main and open one draft pull request per thread.

353- 작업을 완료하기 전에 `make test`와 `make lint`를 실행하고 최종 메시지에 요약 줄을 붙여넣습니다.353- Before you call work done, run `make test` and `make lint` and paste the summary lines in your final message.

354- 저장소, 시크릿, API, 또는 커넥터와 같이 필요한 것에 도달할 수 없으면, 첫 번째 메시지에서 정확히 무엇이 누락되었는지 말하고 멈춥니다. 대체하거나, 모의하거나, 추측하지 마세요.354- If you can't reach something you need, such as a repository, a secret, an API, or a connector, say exactly what's missing in your first message and stop. Don't substitute, mock, or guess.

355- 스레드에서 나에게 묻지 않고 병합하거나, 강제 푸시하거나, CI 구성을 변경하지 마세요.355- Don't merge, force-push, or change CI configuration without asking me in the thread.

356```356```

357 357 

358한 저장소에 대한 규칙(예: 빌드 명령)은 해당 저장소의 `CLAUDE.md`에 속하며, 저장소가 프로젝트의 일부일 때 모든 클라우드 스레드가 이를 읽습니다. 작업이 진행 중일 때 스레드를 수정하면, Claude에게 수정 사항을 기억하도록 말하세요: 이는 [프로젝트 메모리](#give-a-project-standing-context)로 이동하고 이후 클라우드 스레드는 이를 가지고 시작합니다.358한 저장소에 대한 규칙(예: 빌드 명령)은 해당 저장소의 `CLAUDE.md`에 속하며, 저장소가 프로젝트의 일부일 때 모든 클라우드 스레드가 이를 읽습니다. 작업이 진행 중일 때 스레드를 수정하면, Claude에게 수정 사항을 기억하도록 말하세요: 이는 [프로젝트 메모리](#give-a-project-standing-context)로 이동하고 이후 클라우드 스레드는 이를 가지고 시작합니다.

414 414 

415* 스킬, 서브에이전트, 명령: 프로젝트에 추가한 저장소에 커밋합니다. 예를 들어 `.claude/skills/<skill-name>/SKILL.md`의 스킬입니다. 각 클라우드 스레드는 프로젝트의 모든 저장소를 복제하고 각 저장소에서 `.claude/skills/`, `.claude/agents/`, `.claude/commands/`를 로드하므로, 한 저장소에 커밋된 스킬은 모든 클라우드 스레드에서 사용 가능합니다. 클라우드 스레드는 또한 [claude.ai 계정에 대해 활성화한 스킬](/docs/ko/skills#skills-in-cowork-and-cloud-sessions)을 로드합니다.415* 스킬, 서브에이전트, 명령: 프로젝트에 추가한 저장소에 커밋합니다. 예를 들어 `.claude/skills/<skill-name>/SKILL.md`의 스킬입니다. 각 클라우드 스레드는 프로젝트의 모든 저장소를 복제하고 각 저장소에서 `.claude/skills/`, `.claude/agents/`, `.claude/commands/`를 로드하므로, 한 저장소에 커밋된 스킬은 모든 클라우드 스레드에서 사용 가능합니다. 클라우드 스레드는 또한 [claude.ai 계정에 대해 활성화한 스킬](/docs/ko/skills#skills-in-cowork-and-cloud-sessions)을 로드합니다.

416* 플러그인: **프로젝트 설정 > 플러그인**에서 추가합니다; 각 새로운 클라우드 스레드에 로드됩니다. 저장소가 `.claude/settings.json`에서 선언하는 플러그인은 [클라우드 스레드에 로드되지 않습니다](/docs/ko/cloud-environments#what-carries-over-from-your-setup).416* 플러그인: **프로젝트 설정 > 플러그인**에서 추가합니다; 각 새로운 클라우드 스레드에 로드됩니다. 저장소가 `.claude/settings.json`에서 선언하는 플러그인은 [클라우드 스레드에 로드되지 않습니다](/docs/ko/cloud-environments#what-carries-over-from-your-setup).

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

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

419 419 

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

435| 프로젝트 지침 | Memory | [기본 규칙](#give-a-project-standing-context) 모든 새 스레드가 수신 |435| 프로젝트 지침 | Memory | [기본 규칙](#give-a-project-standing-context) 모든 새 스레드가 수신 |

436| 프로젝트 저장소 | Environment | 새 스레드가 복제하는 저장소 |436| 프로젝트 저장소 | Environment | 새 스레드가 복제하는 저장소 |

437| 클라우드 환경 | Environment | 새 스레드가 실행하는 [클라우드 환경](#choose-an-environment-for-threads) |437| 클라우드 환경 | Environment | 새 스레드가 실행하는 [클라우드 환경](#choose-an-environment-for-threads) |

438| 커넥터 | Environment | claude.ai 커넥터를 관리하는 링크 스레드가 가져옴 |

439| 플러그인 | Plugins | 각 새 스레드에 로드되는 플러그인 |438| 플러그인 | Plugins | 각 새 스레드에 로드되는 플러그인 |

440| 사용 | Usage | 스레드 및 모델별 [토큰 사용](#usage-and-cost) |439| 사용 | Usage | 스레드 및 모델별 [토큰 사용](#usage-and-cost) |

441| Memory | Memory | 프로젝트의 [메모리 파일](#give-a-project-standing-context) |440| Memory | Memory | 프로젝트의 [메모리 파일](#give-a-project-standing-context) |

10 클라우드 환경은 [클라우드 세션](/docs/ko/claude-code-on-the-web)에 적용되며, 이는 Pro, Max, Team 플랜에서 사용 가능하고, [프리미엄 시트 또는 Chat + Claude Code 시트](https://support.claude.com/en/articles/11845131-use-claude-code-with-your-team-or-enterprise-plan)가 있는 Enterprise 사용자를 위한 것입니다.10 클라우드 환경은 [클라우드 세션](/docs/ko/claude-code-on-the-web)에 적용되며, 이는 Pro, Max, Team 플랜에서 사용 가능하고, [프리미엄 시트 또는 Chat + Claude Code 시트](https://support.claude.com/en/articles/11845131-use-claude-code-with-your-team-or-enterprise-plan)가 있는 Enterprise 사용자를 위한 것입니다.

11</Note>11</Note>

12 12 

13각 [클라우드 세션](/docs/ko/claude-code-on-the-web)은 클라우드 환경에서 실행됩니다. 환경을 구성하여 [네트워크 액세스](#access-levels)를 허용하거나 거부하고, 세션에 대한 [환경 변수](#set-environment-variables)를 설정하며, Pro 및 Max 플랜에서 세션이 값을 직접 보지 않고도 사용할 수 있는 [네트워크 시크릿](#add-network-secrets)을 저장하고, Claude가 작업을 시작하기 전에 [설정 스크립트](#setup-scripts)를 실행할 수 있습니다.13각 [클라우드 세션](/docs/ko/claude-code-on-the-web)은 클라우드 환경에서 실행됩니다. 환경을 구성하여 [네트워크 액세스](#access-levels)를 허용하거나 거부하고, 세션에 대한 [환경 변수](#set-environment-variables)를 설정하며, 세션이 값을 직접 보지 않고도 사용할 수 있는 [네트워크 시크릿](#add-network-secrets)을 저장하고, Claude가 작업을 시작하기 전에 [설정 스크립트](#setup-scripts)를 실행할 수 있습니다.

14 14 

15동일한 환경이 클라우드 세션을 시작하는 모든 곳에 적용됩니다: [Desktop 앱](/docs/ko/desktop), [Claude 모바일 앱](/docs/ko/mobile), [claude.ai/code](https://claude.ai/code)의 브라우저, [`claude --cloud`](/docs/ko/claude-code-on-the-web#from-terminal-to-cloud)를 사용한 터미널, [루틴](/docs/ko/routines), 그리고 [Claude Tag](https://claude.com/docs/claude-tag/overview). 이러한 각 표면은 [자체 호스팅 환경](/docs/ko/self-hosted-environments)으로도 라우팅할 수 있습니다. [가용성 및 제한 사항](/docs/ko/self-hosted-environments#availability-and-limitations)은 Claude Tag 세션이 하나에서 실행될 때 Claude가 아직 사용할 수 없는 항목을 다룹니다.15동일한 환경이 클라우드 세션을 시작하는 모든 곳에 적용됩니다: [Desktop 앱](/docs/ko/desktop), [Claude 모바일 앱](/docs/ko/mobile), [claude.ai/code](https://claude.ai/code)의 브라우저, [`claude --cloud`](/docs/ko/claude-code-on-the-web#from-terminal-to-cloud)를 사용한 터미널, [루틴](/docs/ko/routines), 그리고 [Claude Tag](https://claude.com/docs/claude-tag/overview). 이러한 각 표면은 [자체 호스팅 환경](/docs/ko/self-hosted-environments)으로도 라우팅할 수 있습니다. [가용성 및 제한 사항](/docs/ko/self-hosted-environments#availability-and-limitations)은 Claude Tag 세션이 하나에서 실행될 때 Claude가 아직 사용할 수 없는 항목을 다룹니다.

16 16 

44 환경 구성44 환경 구성

45</h2>45</h2>

46 46 

47[웹 온보딩](/docs/ko/web-quickstart) 후 [claude.ai/code](https://claude.ai/code)에서 또는 [Desktop 앱](/docs/ko/desktop#cloud-sessions)의 프롬프트 상자에서 환경 선택기를 통해 환경을 생성, 편집 및 보관할 수 있습니다. 생성한 환경은 계정에 개인적으로 속하며, Owner가 생성한 [공유 환경](#organization-shared-environments)은 동일한 선택기에 나타납니다. 구성 없이 사용 가능한 항목은 [설치된 도구](#installed-tools)를 참조하십시오.47[claude.ai/code](https://claude.ai/code)에서 새 세션을 시작하는 화면의 메시지 상자 아래에 있는 환경 선택기에서 환경을 추가, 편집 및 보관할 수 있습니다. 해당 화면에 접근하려면 [웹 온보딩](/docs/ko/web-quickstart)을 완료하십시오. Desktop 앱의 경우 [클라우드 세션](/docs/ko/desktop#cloud-sessions)을 참조하십시오. 생성한 환경은 계정에 개인적으로 속하며, Owner가 생성한 [공유 환경](#organization-shared-environments)도 함께 선택기에 나타납니다. 구성 없이 사용 가능한 항목은 [설치된 도구](#installed-tools)를 참조하십시오.

48 

49선택기는 새 세션의 첫 번째 메시지를 보내기 전까지만 표시됩니다. 실행 중인 자신의 클라우드 세션 환경을 편집하려면 상단의 세션 제목 뒤에 있는 캐럿을 선택한 다음 **Edit cloud environment**를 선택합니다.

48 50 

49<Steps>51<Steps>

50 <Step title="환경 선택기 열기">52 <Step title="환경 선택기 열기">

51 [claude.ai/code](https://claude.ai/code)에서 메시지 상자 위의 행에 있는 현재 환경의 이름을 표시하는 클라우드 아이콘을 선택합니다. 선택기에 대한 설정 페이지나 직접 URL은 없습니다.53 새 세션 화면에서 메시지 상자 아래 행의 첫 번째 컨트롤을 선택합니다.

52 

53 <Frame>

54 <img src="https://mintcdn.com/claude-code/ZFId6l95856c5LSw/images/cloud-environment-selector.png?fit=max&auto=format&n=ZFId6l95856c5LSw&q=85&s=cc2813a5664519eaf5a89d793ce5af26" alt="claude.ai/code의 메시지 상자 위에 열려 있는 환경 선택기입니다. 환경 이름 Default를 표시하는 클라우드 버튼이 메시지 상자 위의 행에 있습니다. 열린 메뉴에는 Download 및 Desktop only 레이블이 있는 Local 행, Default 환경이 체크 표시로 선택되어 있고 마우스를 올리면 설정 기어 아이콘이 표시되는 Cloud 섹션, Add cloud environment 옵션, 그리고 설정 지침이 있는 Remote Control 섹션이 나열됩니다." width="1672" height="682" data-path="images/cloud-environment-selector.png" />

55 </Frame>

56 </Step>54 </Step>

57 55 

58 <Step title="환경 추가 또는 편집">56 <Step title="환경 추가 또는 편집">

59 **Cloud**를 선택하여 환경을 나열합니다. 그런 다음 **Add cloud environment**를 선택하거나, 기존 환경 위에 마우스를 올리고 오른쪽에 나타나는 설정 아이콘을 선택합니다.57 * **환경 추가**: 메뉴 하단의 **New environment**를 선택하여 **New environment** 대화 상자를 엽니다. 양식을 작성하고 **Add environment**를 선택합니다. 그러면 새 세션이 추가한 환경을 사용합니다.

58 * **환경 편집**: **Cloud** 아래에서 해당 환경의 행을 찾습니다. **Cloud**가 단일 행인 경우 이를 선택하여 목록을 엽니다. 환경이 **Cloud** 아래에 나열되지 않은 경우 해당 제목 아래의 **More** 행을 선택합니다. 환경의 행 위에 마우스를 올리고 오른쪽에 나타나는 설정 아이콘을 선택하여 대화 상자를 엽니다.

60 59 

61 대화 상자에는 이름, 네트워크 액세스 수준, 환경 변수 및 설정 스크립트가 포함됩니다. Pro 또는 Max 플랜에서 기존 클라우드 환경을 편집할 때 대화 상자에는 [네트워크 시크릿](#add-network-secrets)도 포함됩니다.60 대화 상자에는 이름, 네트워크 액세스 수준, 환경 변수 및 설정 스크립트가 포함됩니다. 세션이 키를 보지 않고 사용하도록 키를 저장하려면 [네트워크 시크릿 추가](#add-network-secrets)를 참조하십시오.

62 

63 <Frame>

64 <img src="https://mintcdn.com/claude-code/ZFId6l95856c5LSw/images/cloud-environment-dialog.png?fit=max&auto=format&n=ZFId6l95856c5LSw&q=85&s=30d4478b31d1f879f7ee287ddab32505" alt="New cloud environment 대화 상자입니다. 기본값 자리 표시자가 있는 Name 필드, Trusted로 설정된 Network access 선택기(네트워크 정책 및 액세스 수준에 대한 링크 포함), .env 형식 자리 표시자 텍스트가 있는 Environment variables 상자(환경을 사용하는 모든 사람이 값을 볼 수 있다는 참고 사항 포함), Claude Code가 시작되기 전에 새 세션이 시작될 때 실행되는 Bash 스크립트로 설명된 Setup script 상자, 그리고 Cancel 및 Create environment 버튼이 있습니다." width="874" height="1372" data-path="images/cloud-environment-dialog.png" />

65 </Frame>

66 </Step>61 </Step>

67</Steps>62</Steps>

68 63 

91 86 

92클라우드 세션은 시작할 때 자체적으로 일부 변수도 설정합니다. [`CLAUDE_AUTOCOMPACT_PCT_OVERRIDE`](/docs/ko/claude-code-on-the-web#manage-context)의 경우, 세션이 설정하는 값이 여기에 추가한 값을 재정의하므로 여기에 해당 키를 추가해도 효과가 없습니다.87클라우드 세션은 시작할 때 자체적으로 일부 변수도 설정합니다. [`CLAUDE_AUTOCOMPACT_PCT_OVERRIDE`](/docs/ko/claude-code-on-the-web#manage-context)의 경우, 세션이 설정하는 값이 여기에 추가한 값을 재정의하므로 여기에 해당 키를 추가해도 효과가 없습니다.

93 88 

94환경을 사용하는 모든 사람이 값을 읽을 수 있습니다. Pro 및 Max 플랜에서는 에이전트 프록시가 요청에 첨부할 수 있는 키에 대해 [네트워크 시크릿](#add-network-secrets)을 대신 사용하십시오. [시크릿을 받지 않는 요청](#requests-that-never-get-the-credential)은 해당 섹션에 나열되어 있습니다.89환경을 사용하는 모든 사람이 값을 읽을 수 있습니다. Anthropic 호스팅 환경에서는 에이전트 프록시가 요청에 첨부할 수 있는 키에 대해 [네트워크 시크릿](#add-network-secrets)을 대신 사용하십시오. [시크릿을 받지 않는 요청](#requests-that-never-get-the-credential)은 해당 섹션에 나열되어 있습니다.

95 90 

96<span id="add-api-credentials" />91<span id="add-api-credentials" />

97 92 

101 96 

102네트워크 시크릿은 클라우드 환경에 저장하는 API 키 또는 토큰으로, Claude가 키를 보지 않고도 환경의 모든 세션에서 해당 API를 호출할 수 있게 합니다. Anthropic의 에이전트 프록시는 각 요청이 세션의 VM을 떠난 후 나열한 호스트에 대한 요청에 키를 추가하므로, 키 자체는 VM 외부에 유지됩니다.97네트워크 시크릿은 클라우드 환경에 저장하는 API 키 또는 토큰으로, Claude가 키를 보지 않고도 환경의 모든 세션에서 해당 API를 호출할 수 있게 합니다. Anthropic의 에이전트 프록시는 각 요청이 세션의 VM을 떠난 후 나열한 호스트에 대한 요청에 키를 추가하므로, 키 자체는 VM 외부에 유지됩니다.

103 98 

104네트워크 시크릿은 Pro 및 Max 플랜에서 사용 가능합니다. Team 또는 Enterprise 플랜에서는 아직 사용할 수 없으므로 **Network secrets** 섹션이 해당 플랜의 환경 대화 상자에 나타나지 않습니다.99네트워크 시크릿은 Pro, Max, Team 및 Enterprise 플랜에서 사용할 수 있습니다. 직접 추가할 수 있는지 확인하려면 [요구 사항](#requirements)을 참조하십시오.

105 100 

106<h4 id="requirements">101<h4 id="requirements">

107 요구 사항102 요구 사항

109 104 

110다음 요구 사항에 따라 시크릿을 추가할 수 있는지, 그리고 추가된 후 에이전트 프록시가 이를 사용할 수 있는지가 결정됩니다.105다음 요구 사항에 따라 시크릿을 추가할 수 있는지, 그리고 추가된 후 에이전트 프록시가 이를 사용할 수 있는지가 결정됩니다.

111 106 

112* **Role**: claude.ai 조직의 조직 관리자 역할107* **Role**: Pro, Max 및 Team 플랜에서는 역할에 관계없이 자신의 환경에서 시크릿을 추가하고 삭제할 수 있습니다. Team 및 Enterprise에서는 Owner가 claude.ai 조직의 조직 관리자 역할을 보유하고 Admin은 보유하지 않으며, 이에 따라 다음 경우에 표시되는 내용이 달라집니다.

113 * Team 및 Enterprise에서는 Owner가 보유하고 Admin은 보유하지 않습니다.108 * **Enterprise의 자신의 환경**: 조직 관리자 역할이 있으면 시크릿을 추가하고 삭제합니다. 역할이 없으면 **Network secrets** 섹션에 "Only an organization admin can add or delete network secrets"라는 참고 사항 아래에 시크릿이 나열되며, **Add secret** 또는 삭제 버튼은 없습니다. Owner에게 [공유 환경](#organization-shared-environments)에 시크릿을 추가하도록 요청한 다음 해당 환경에서 세션을 실행하십시오.

114 * Pro 및 Max에서는 자신의 조직에서 보유합니다.109 * **공유 환경**: Owner가 관리자 설정에서 [시크릿을 추가하고 삭제](#add-a-credential)합니다. 조직 관리자 역할이 없으면 환경의 대화 상자에 **Network secrets** 섹션이 없으므로 Owner에게 시크릿 추가를 요청하십시오.

110 * **Team의 자신의 환경**: 조직 관리자 역할이 없으면 **Add secret**이 하나의 호스트를 받는 [더 짧은 양식](#add-a-secret-without-the-role)을 엽니다.

115* **Environment type**: 이미 존재하는 Anthropic 호스팅 클라우드 환경입니다. [자체 호스팅 환경](/docs/ko/self-hosted-environments)에는 네트워크 시크릿이 없습니다.111* **Environment type**: 이미 존재하는 Anthropic 호스팅 클라우드 환경입니다. [자체 호스팅 환경](/docs/ko/self-hosted-environments)에는 네트워크 시크릿이 없습니다.

116* **API reachability**: API가 인터넷에서의 연결을 수락합니다. 요청이 Anthropic의 네트워크에서 나가기 때문입니다.112* **API reachability**: API가 인터넷에서의 연결을 수락합니다. 요청이 Anthropic의 네트워크에서 나가기 때문입니다.

117* **Encryption keys**: 조직이 고객 관리 암호화 키를 사용하는 경우 네트워크 시크릿을 저장할 수 없습니다.113* **Encryption keys**: 조직이 고객 관리 암호화 키를 사용하는 경우 네트워크 시크릿을 저장할 수 없습니다.

122 118 

123시크릿은 한 번에 하나씩 추가하며, 추가한 후에는 편집할 수 없습니다. 시크릿의 호스트 또는 값을 변경하려면 삭제하고 다시 추가합니다.119시크릿은 한 번에 하나씩 추가하며, 추가한 후에는 편집할 수 없습니다. 시크릿의 호스트 또는 값을 변경하려면 삭제하고 다시 추가합니다.

124 120 

121[공유 환경](#organization-shared-environments)에 시크릿을 추가하려면 [관리자 설정](https://claude.ai/admin-settings)의 **Cloud environments** 페이지에서 편집할 환경을 연 다음, **Network secrets** 섹션에서 1단계를 계속 진행합니다. Team 플랜을 사용 중이고 [조직 관리자 역할](#requirements)이 없다면 자신의 환경에서 1단계를 따른 다음 [더 짧은 양식을 작성](#add-a-secret-without-the-role)합니다.

122 

125<Steps>123<Steps>

126 <Step title="환경의 네트워크 시크릿 열기">124 <Step title="환경의 네트워크 시크릿 열기">

127 [claude.ai/code](https://claude.ai/code)에서 [편집할 환경을 엽니다](#configure-your-environment). **Edit environment** 대화 상자에서 **Network secrets** 섹션을 찾습니다. 환경에 이미 있는 시크릿이 각각 적용되는 호스트와 함께 표시됩니다.125 [claude.ai/code](https://claude.ai/code)에서 [편집할 환경을 엽니다](#configure-your-environment). **Edit cloud environment** 대화 상자에서 **Network secrets** 섹션을 찾습니다. 환경에 이미 있는 시크릿이 각각 적용되는 호스트와 함께 표시됩니다.

128 </Step>126 </Step>

129 127 

130 <Step title="시크릿 추가">128 <Step title="시크릿 추가">

131 **Add secret**을 선택하고 양식을 작성합니다. 요청 헤더에서 전달되는 API 키에 대해 기본 **Credential type**인 **Bearer**를 유지하고 다음 필드를 작성합니다.129 **Add secret**을 선택하고 양식을 작성합니다. 요청 헤더에서 전달되는 API 키에 대해 기본 **Secret type**인 **Bearer**를 유지하고 다음 필드를 작성합니다.

132 130 

133 * **Name**: `Internal billing API`와 같은 시크릿의 레이블131 * **Name**: `Internal billing API`와 같은 시크릿의 레이블

134 * **Allowed websites**: `api.example.com`과 같은 API의 호스트입니다. 선행 `*.`은 모든 하위 도메인과 일치합니다.132 * **Allowed websites**: `api.example.com`과 같은 API의 호스트입니다. 선행 `*.`은 모든 하위 도메인과 일치합니다.

135 * **Custom headers**: 키를 전달하는 헤더에 대한 한 행입니다. 행은 헤더의 **Name**으로 `Authorization`, **Prefix**로 `Bearer`가 입력된 상태로 시작합니다. 키 자체를 **Value**로 붙여넣습니다. `X-Api-Key`와 같이 접두사 없는 값을 사용하는 헤더의 경우 이름을 변경하고 접두사를 지웁니다.133 * **Custom headers**: 키를 전달하는 헤더에 대한 한 행입니다. 행은 헤더의 **Name**으로 `Authorization`, **Prefix**로 `Bearer`가 입력된 상태로 시작합니다. 키 자체를 **Value**로 붙여넣습니다. `X-Api-Key`와 같이 접두사 없는 값을 사용하는 헤더의 경우 이름을 변경하고 접두사를 지웁니다.

136 134 

137 다른 방식으로 인증하는 API의 경우 다른 **Credential type**을 선택합니다. 목록은 Team 및 Enterprise 플랜의 Slack 통합인 [Claude Tag](https://claude.com/docs/claude-tag/overview)가 [연결](https://claude.com/docs/claude-tag/admins/add-connections)에 제공하는 것과 동일합니다.135 다른 방식으로 인증하는 API의 경우 다른 **Secret type**을 선택합니다. 목록은 Team 및 Enterprise 플랜의 Slack 통합인 [Claude Tag](https://claude.com/docs/claude-tag/overview)가 [연결](https://claude.com/docs/claude-tag/admins/add-connections)에 제공하는 것과 동일합니다.

138 </Step>136 </Step>

139 137 

140 <Step title="시크릿 저장">138 <Step title="시크릿 저장">

141 **Connect**를 선택합니다. 시크릿이 호스트와 함께 목록에 나타나며, 대화 상자의 **Save changes** 버튼 없이 저장됩니다. 저장 후 값을 다시 볼 수 없습니다.139 **Add**를 선택합니다. 시크릿이 호스트와 함께 목록에 나타나며, 대화 상자의 **Save changes** 버튼 없이 저장됩니다. 저장 후 값을 다시 볼 수 없습니다.

142 </Step>140 </Step>

143</Steps>141</Steps>

144 142 

145시크릿이 작동하는지 확인하려면 환경에서 세션을 시작하고 Claude에게 `curl` 등으로 API를 호출하도록 요청합니다. API는 키가 요청에 있는 것처럼 응답하며, 키는 세션의 환경 변수나 파일에 나타나지 않습니다. 목록이 시크릿을 **Not sent**로 표시하는 경우, 아래의 참고 사항에 이유와 수행할 작업이 설명되어 있습니다. 호스트가 정확히 일치하지 않고 겹치는 두 시크릿은 마커를 받지 않으며, 에이전트 프록시는 그 중 하나만 보냅니다.143시크릿이 작동하는지 확인하려면 환경에서 세션을 시작하고 Claude에게 `curl` 등으로 API를 호출하도록 요청합니다. API는 키가 요청에 있는 것처럼 응답하며, 키는 세션의 환경 변수나 파일에 나타나지 않습니다. 목록이 시크릿을 **Not sent**로 표시하는 경우, 아래의 참고 사항에 이유와 수행할 작업이 설명되어 있습니다. 호스트가 정확히 일치하지 않고 겹치는 두 시크릿은 마커를 받지 않으며, 에이전트 프록시는 그 중 하나만 보냅니다.

146 144 

145<h4 id="add-a-secret-without-the-role">

146 조직 관리자 역할 없이 Team 플랜에서 시크릿 추가

147</h4>

148 

149Team 플랜을 사용 중이고 [조직 관리자 역할](#requirements)이 없다면 **Add secret** 양식은 하나의 호스트에 대해 하나의 시크릿을 받습니다. 환경의 [**Network secrets** 섹션](#add-a-credential)에서 **Add secret**을 선택하고 다음 필드를 작성한 다음, 양식의 **Add secret** 버튼을 선택합니다.

150 

151* **Host**: `api.example.com`과 같이 시크릿을 받는 하나의 호스트입니다. 양식은 `*.` 와일드카드를 허용하지 않습니다.

152* **Name**: 시크릿의 선택적 레이블

153* **Secret type**: 요청 헤더에서 전달되는 키의 경우 **Token**, 또는 **Username and password**입니다. 토큰의 경우 키를 **Value**로 붙여넣습니다.

154 

147<h4 id="which-requests-get-the-credential">155<h4 id="which-requests-get-the-credential">

148 시크릿을 받는 요청156 시크릿을 받는 요청

149</h4>157</h4>

175 환경 보관183 환경 보관

176</h3>184</h3>

177 185 

178자신의 환경 중 하나를 보관하려면 편집을 위해 열고 **Archive**를 선택합니다. Owner는 관리 설정의 **Cloud environments** 페이지에서 [공유 환경](#organization-shared-environments)을 보관합니다. 환경을 삭제할 수 없으며, 보관만 할 수 있습니다.186자신의 환경 중 하나를 보관하려면 편집을 위해 열고 **Archive environment**를 선택한 다음 확인합니다. 환경이 [조직과 공유된](#organization-shared-environments) 경우에는 Owner가 [관리자 설정](https://claude.ai/admin-settings)의 **Cloud environments** 페이지에서 보관하므로, 본인이 Owner가 아니라면 Owner에게 요청하십시오. 환경을 삭제할 수 없으며, 보관만 할 수 있습니다.

179 187 

180보관은 실행 중인 세션이 아닌 새 세션에 영향을 미칩니다.188보관은 실행 중인 세션이 아닌 새 세션에 영향을 미칩니다.

181 189 

199 207 

200Owner는 [claude.ai/admin-settings/claude-code](https://claude.ai/admin-settings/claude-code)에서 조직의 [기본 환경](#the-default-environment)을 별도로 선택합니다.208Owner는 [claude.ai/admin-settings/claude-code](https://claude.ai/admin-settings/claude-code)에서 조직의 [기본 환경](#the-default-environment)을 별도로 선택합니다.

201 209 

202모든 구성원의 공유 환경 세션은 해당 변수를 읽으므로 비밀 정보를 포함하지 마십시오. 세션에 읽을 수 없는 키를 제공하는 [네트워크 시크릿](#add-network-secrets)은 Team 또는 Enterprise 플랜에서 아직 사용할 수 없습니다.210공유 환경의 세션에 읽을 수 없는 키를 제공하려면 **Cloud environments** 페이지에서 환경을 편집할 때 [네트워크 시크릿](#add-network-secrets)을 추가하십시오. 모든 구성원의 세션이 변수를 읽으므로 변수에 비밀 정보를 포함하지 마십시오.

203 211 

204<h3 id="set-the-environment-a-claude-tag-channel-uses">212<h3 id="set-the-environment-a-claude-tag-channel-uses">

205 Claude Tag 채널이 사용하는 환경 설정213 Claude Tag 채널이 사용하는 환경 설정

216 224 

217각 환경은 하나의 네트워크 액세스 수준을 설정하며, 이는 세션이 만들 수 있는 아웃바운드 연결을 제어합니다. 기본 수준인 **Trusted**는 패키지 레지스트리 및 기타 [허용 목록 도메인](#default-allowed-domains)을 허용합니다. **Custom**은 자신의 도메인 목록을 사용합니다.225각 환경은 하나의 네트워크 액세스 수준을 설정하며, 이는 세션이 만들 수 있는 아웃바운드 연결을 제어합니다. 기본 수준인 **Trusted**는 패키지 레지스트리 및 기타 [허용 목록 도메인](#default-allowed-domains)을 허용합니다. **Custom**은 자신의 도메인 목록을 사용합니다.

218 226 

219환경의 네트워크 액세스를 변경하려면 [편집을 위해 열고](#configure-your-environment) 대화 상자에서 **Network access** 선택기를 사용합니다. [공유 환경](#organization-shared-environments)은 읽기 전용으로 열리므로 Owner는 [관리 설정](https://claude.ai/admin-settings)의 **Cloud environments** 페이지에서 네트워크 액세스를 변경합니다. 선택기를 여는 클라우드 아이콘은 [Default 환경](#the-default-environment) 아래에 나열된 앱 표면 및 [루틴 편집기](/docs/ko/routines#environments-and-network-access)에 나타납니다. 개인 환경에는 claude.ai 계정 설정에 별도의 페이지가 없습니다.227환경의 네트워크 액세스를 변경하려면 [편집을 위해 열고](#configure-your-environment) 대화 상자에서 **Network access** 선택기를 사용합니다. [공유 환경](#organization-shared-environments)은 읽기 전용으로 열리므로 Owner는 [관리자 설정](https://claude.ai/admin-settings)의 **Cloud environments** 페이지에서 네트워크 액세스를 변경합니다. 선택기를 여는 컨트롤은 [Default 환경](#the-default-environment) 아래에 나열된 앱 사용 환경 및 [루틴 편집기](/docs/ko/routines#environments-and-network-access)에 나타납니다. 개인 환경에는 claude.ai 계정 설정에 별도의 페이지가 없습니다.

220 228 

221Anthropic 호스팅 환경의 네트워크 액세스를 변경하면 기존 세션은 세션의 [네트워크 허용 목록](#access-levels)을 통과하는 요청에 대해 약 1분 이내에 새 설정을 따릅니다. 새 세션을 시작할 필요가 없습니다.229Anthropic 호스팅 환경의 네트워크 액세스를 변경하면 기존 세션은 세션의 [네트워크 허용 목록](#access-levels)을 통과하는 요청에 대해 약 1분 이내에 새 설정을 따릅니다. 새 세션을 시작할 필요가 없습니다.

222 230 

274* **Git 자격 증명**: VM 내부의 git 클라이언트는 범위가 지정된 자격 증명을 사용하며, 프록시는 이를 확인하고 실제 GitHub 토큰으로 교환합니다.282* **Git 자격 증명**: VM 내부의 git 클라이언트는 범위가 지정된 자격 증명을 사용하며, 프록시는 이를 확인하고 실제 GitHub 토큰으로 교환합니다.

275* **API 요청**: 기본 제공 GitHub 도구의 요청 및 [`proxy-injected` 자리 표시자](#work-with-github-issues-and-pull-requests) 아래의 `gh`에서의 요청은 실제 자격 증명이 대체되어 나갑니다.283* **API 요청**: 기본 제공 GitHub 도구의 요청 및 [`proxy-injected` 자리 표시자](#work-with-github-issues-and-pull-requests) 아래의 `gh`에서의 요청은 실제 자격 증명이 대체되어 나갑니다.

276* **푸시 제한**: 프록시는 브랜치 삭제 및 태그와 같이 브랜치가 아닌 항목의 푸시를 거부합니다. 푸시가 업데이트할 수 있는 브랜치는 제한하지 않습니다. 이를 제한하려면 GitHub에서 브랜치 보호 규칙 또는 규칙 세트를 사용합니다.284* **푸시 제한**: 프록시는 브랜치 삭제 및 태그와 같이 브랜치가 아닌 항목의 푸시를 거부합니다. 푸시가 업데이트할 수 있는 브랜치는 제한하지 않습니다. 이를 제한하려면 GitHub에서 브랜치 보호 규칙 또는 규칙 세트를 사용합니다.

277* **저장소 범위**: 프록시는 세션에 연결된 저장소에 대한 GitHub API 요청을 처리합니다. 다른 저장소에 대한 API 요청은 `GitHub access to`로 시작하고 `is not enabled for this session`을 포함하는 메시지와 함께 403을 받습니다.285* **저장소 범위**: 프록시는 세션에 연결된 저장소에 대한 GitHub API 요청을 처리합니다. 다른 저장소에 대한 API 요청은 `GitHub access to`로 시작하고 `is not enabled for this session`을 포함하는 메시지와 함께 403을 받습니다. `github.com/{owner}/{repo}/archive/` 또는 `codeload.github.com` URL을 통해 가져오는 소스 아카이브도 저장소가 연결되어 있지 않으면 공개 저장소라도 동일한 403을 받습니다.

278* **GraphQL 제한**: 프록시는 GitHub의 GraphQL 엔드포인트에 대한 요청을 `GitHub GraphQL is not available from Claude Code sessions`로 시작하는 메시지와 함께 403으로 거부하며, 이 메시지는 REST 폴백인 `gh api repos/{owner}/{repo}/...`를 안내합니다. `gh pr` 및 `gh issue`와 같이 GraphQL을 사용하는 `gh` 하위 명령도 동일한 403을 받습니다. 제한은 제공하는 자격 증명과 관계없이 프록시를 통한 모든 요청에 적용되므로 설정한 `GH_TOKEN`은 동일한 403을 받습니다. Claude는 Projects v2와 같이 GraphQL에만 존재하는 GitHub API에 프록시를 통해 도달할 수 없습니다.286* **GraphQL 제한**: 프록시는 GitHub의 GraphQL 엔드포인트에 대한 요청을 `GitHub GraphQL is not available from Claude Code sessions`로 시작하는 메시지와 함께 403으로 거부하며, 이 메시지는 REST 폴백인 `gh api repos/{owner}/{repo}/...`를 안내합니다. `gh pr` 및 `gh issue`와 같이 GraphQL을 사용하는 `gh` 하위 명령도 동일한 403을 받습니다. 제한은 제공하는 자격 증명과 관계없이 프록시를 통한 모든 요청에 적용되므로 설정한 `GH_TOKEN`은 동일한 403을 받습니다. Claude는 Projects v2와 같이 GraphQL에만 존재하는 GitHub API에 프록시를 통해 도달할 수 없습니다.

279 287 

280공개 리포지토리의 커밋된 파일은 `raw.githubusercontent.com`을 통해 도착하며, [보안 프록시](#security-proxy)가 대신 처리합니다. 해당 도메인은 기본 [Trusted 목록](#default-allowed-domains)에 있으므로 환경의 [액세스 수준](#access-levels)이 이를 제외하지 않는 한 이러한 파일은 도달 가능합니다.288공개 리포지토리의 커밋된 파일은 `raw.githubusercontent.com`을 통해 도착하며, [보안 프록시](#security-proxy)가 대신 처리합니다. 해당 도메인은 기본 [Trusted 목록](#default-allowed-domains)에 있으므로 환경의 [액세스 수준](#access-levels)이 이를 제외하지 않는 한 이러한 파일은 도달 가능합니다.

318| 사용자 설정에서만 활성화된 플러그인 | 아니오 | 사용자 범위 `enabledPlugins`은 머신의 `~/.claude/settings.json`에 있습니다 |326| 사용자 설정에서만 활성화된 플러그인 | 아니오 | 사용자 범위 `enabledPlugins`은 머신의 `~/.claude/settings.json`에 있습니다 |

319| `claude mcp add`로 기본 로컬 범위 또는 사용자 범위에서 추가한 MCP 서버 | 아니오 | 이는 저장소가 아닌 머신의 `~/.claude.json`에 씁니다. 저장소의 [`.mcp.json`](/docs/ko/mcp#project-scope)에 쓰는 `claude mcp add --scope project`로 서버를 추가하고 해당 파일을 커밋합니다. 하나의 저장소가 있는 세션이 이를 로드합니다 |327| `claude mcp add`로 기본 로컬 범위 또는 사용자 범위에서 추가한 MCP 서버 | 아니오 | 이는 저장소가 아닌 머신의 `~/.claude.json`에 씁니다. 저장소의 [`.mcp.json`](/docs/ko/mcp#project-scope)에 쓰는 `claude mcp add --scope project`로 서버를 추가하고 해당 파일을 커밋합니다. 하나의 저장소가 있는 세션이 이를 로드합니다 |

320| 저장소의 `.claude/settings.json` `env` 블록의 전송 변수(예: `NODE_EXTRA_CA_CERTS` 및 [mTLS 클라이언트 인증서 변수](/docs/ko/network-config#mtls-authentication)) | 아니오 | 호스팅 환경이 세션의 API 연결을 관리하므로 Claude Code는 이러한 키를 무시하고 각 무시된 키를 세션의 디버그 로그에 기록합니다 |328| 저장소의 `.claude/settings.json` `env` 블록의 전송 변수(예: `NODE_EXTRA_CA_CERTS` 및 [mTLS 클라이언트 인증서 변수](/docs/ko/network-config#mtls-authentication)) | 아니오 | 호스팅 환경이 세션의 API 연결을 관리하므로 Claude Code는 이러한 키를 무시하고 각 무시된 키를 세션의 디버그 로그에 기록합니다 |

321| Claude가 호출하는 서비스의 API 키 및 토큰 | Pro 및 Max 플랜에서 [네트워크 시크릿](#add-network-secrets)으로 | 환경에 키를 한 번 추가하면 에이전트 프록시가 나열한 호스트에 대한 요청에 이를 첨부합니다. 에이전트 프록시가 [첨부할 수 없는](#requests-that-never-get-the-credential) 키 또는 Team 또는 Enterprise 플랜의 모든 키는 환경 변수에 남아 있습니다 |329| Claude가 호출하는 서비스의 API 키 및 토큰 | Anthropic 호스팅 환경에서 [네트워크 시크릿](#add-network-secrets)으로 | 환경에 키를 한 번 추가하면 에이전트 프록시가 나열한 호스트에 대한 요청에 이를 첨부합니다. 에이전트 프록시가 [첨부할 수 없는](#requests-that-never-get-the-credential) 키는 환경 변수에 남아 있습니다 |

322| AWS SSO와 같은 대화형 인증 | 아니오 | 지원되지 않습니다. SSO는 클라우드 세션에서 실행할 수 없는 브라우저 기반 로그인이 필요합니다 |330| AWS SSO와 같은 대화형 인증 | 아니오 | 지원되지 않습니다. SSO는 클라우드 세션에서 실행할 수 없는 브라우저 기반 로그인이 필요합니다 |

323 331 

324자신의 구성을 클라우드 세션에서 사용 가능하게 하려면 저장소에 커밋합니다.332자신의 구성을 클라우드 세션에서 사용 가능하게 하려면 저장소에 커밋합니다.

325 333 

326환경을 사용하는 모든 사람이 환경 변수 및 설정 스크립트를 읽을 수 있습니다. 대화 상자의 **Environment variables** 아래의 참고 사항이 이를 안내하고 비밀을 추가하지 않도록 경고합니다. Pro 및 Max 플랜에서는 에이전트 프록시가 첨부할 수 있는 키를 대신 [네트워크 시크릿](#add-network-secrets)으로 저장합니다.334환경을 사용하는 모든 사람이 환경 변수 및 설정 스크립트를 읽을 수 있습니다. 대화 상자의 **Environment variables** 아래의 참고 사항이 이를 안내하고 비밀을 추가하지 않도록 경고합니다. Anthropic 호스팅 환경에서는 에이전트 프록시가 첨부할 수 있는 키를 대신 [네트워크 시크릿](#add-network-secrets)으로 저장합니다.

327 335 

328<h4 id="add-personal-preferences-without-committing-to-the-repo">336<h4 id="add-personal-preferences-without-committing-to-the-repo">

329 저장소에 커밋하지 않고 개인 기본 설정 추가337 저장소에 커밋하지 않고 개인 기본 설정 추가

155* 리포지토리에 대한 쓰기, 유지 관리 또는 관리자 권한이 있어야 합니다155* 리포지토리에 대한 쓰기, 유지 관리 또는 관리자 권한이 있어야 합니다

156* PR은 열려 있어야 합니다156* PR은 열려 있어야 합니다

157 157 

158리포지토리가 조직에 속하고 해당 조직의 멤버십이 비공개인 경우(GitHub의 기본값), GitHub는 Claude에게 사용자를 멤버로 식별하지 않습니다. Claude는 여전히 댓글에 👀로 반응할 수 있지만 팀이나 조직의 기본 권한이 쓰기 액세스를 제공하더라도 리포지토리에 협력자로 직접 추가되지 않으면 검토를 시작하지 않습니다. 이를 해결하려면 [조직 멤버십을 공개로 설정](https://docs.github.com/en/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-your-membership-in-organizations/publicizing-or-hiding-organization-membership)하거나 리포지토리 관리자에게 협력자로 리포지토리에 추가해 달라고 요청하세요.

159 

160자동 트리거와 달리 수동 트리거는 명시적 요청이 초안 상태와 관계없이 지금 검토를 원한다는 신호이므로 초안 PR에서 실행됩니다.158자동 트리거와 달리 수동 트리거는 명시적 요청이 초안 상태와 관계없이 지금 검토를 원한다는 신호이므로 초안 PR에서 실행됩니다.

161 159 

162해당 PR에서 검토가 이미 실행 중인 경우 요청은 진행 중인 검토가 완료될 때까지 대기열에 추가됩니다. PR의 확인 실행을 통해 진행 상황을 모니터링할 수 있습니다.160해당 PR에서 검토가 이미 실행 중인 경우 요청은 진행 중인 검토가 완료될 때까지 대기열에 추가됩니다. PR의 확인 실행을 통해 진행 상황을 모니터링할 수 있습니다.

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

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

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

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

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

72| `/claude-api [migrate\|upgrade\|managed-agents-onboard\|prompt-audit\|cost-optimize\|build-eval\|hillclimb\|preserved-thinking-migration]` | **[스킬](/docs/ko/skills#bundled-skills).** 프로젝트 언어에 맞는 [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 API 프로젝트 작업](/docs/ko/skills#work-on-claude-api-projects)을 참조하세요 |72| `/claude-api [migrate\|upgrade\|managed-agents-onboard\|prompt-audit\|cost-optimize\|build-eval\|hillclimb\|preserved-thinking-migration]` | **[스킬](/docs/ko/skills#bundled-skills).** 프로젝트 언어에 맞는 [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 API 프로젝트 작업](/docs/ko/skills#work-on-claude-api-projects)을 참조하세요 |

73| `/claude-in-chrome [task]` | **[스킬](/docs/ko/skills#bundled-skills).** [Claude in Chrome](/docs/ko/chrome)을 통해 페이지 테스트, 양식 작성, 콘솔 로그 읽기 등의 작업을 Claude가 브라우저에서 수행하도록 합니다. 세션에서 Chrome 통합이 활성화된 경우(예: `claude --chrome` 사용) 또는 Claude Code가 [확장 프로그램 설치](/docs/ko/chrome#install-the-extension-when-claude-asks)를 제안할 수 있는 경우에 사용할 수 있습니다 |73| `/claude-in-chrome [task]` | **[스킬](/docs/ko/skills#bundled-skills).** [Claude in Chrome](/docs/ko/chrome)을 통해 페이지 테스트, 양식 작성, 콘솔 로그 읽기 등의 작업을 Claude가 브라우저에서 수행하도록 합니다. 세션에서 Chrome 통합이 활성화된 경우(예: `claude --chrome` 사용) 또는 Claude Code가 [확장 프로그램 설치](/docs/ko/chrome#install-the-extension-when-claude-asks)를 제안할 수 있는 경우에 사용할 수 있습니다 |

74| `/clear [name]` | 빈 컨텍스트로 새 대화를 시작합니다. 이름을 전달하면 `/resume` 선택기에서 이전 대화에 레이블을 지정합니다. 같은 대화를 계속하면서 컨텍스트를 확보하려면 대신 `/compact`를 사용합니다. `/resume`으로 이전 대화를 재개하거나, 같은 Claude Code 프로세스 내에서는 [되감기 메뉴의 이전 세션 항목](/docs/ko/checkpointing#rewind-past-a-cleared-conversation)에서 복원합니다. 별칭: `/reset`, `/new` |74| `/clear [name]` | 빈 컨텍스트로 새 대화를 시작합니다. 이름을 전달하면 `/resume` 선택기에서 이전 대화에 레이블을 지정합니다. 같은 대화를 계속하면서 컨텍스트를 확보하려면 대신 `/compact`를 사용합니다. `/resume`으로 이전 대화를 재개하거나, 같은 Claude Code 프로세스 내에서는 [되감기 메뉴의 이전 세션 항목](/docs/ko/checkpointing#rewind-past-a-cleared-conversation)에서 복원합니다. 별칭: `/reset`, `/new` |

75| `/code-review [low\|medium\|high\|xhigh\|max\|ultra] [--fix] [--comment] [--max-findings n\|all\|default] [pr#\|branch\|path]` | **[스킬](/docs/ko/skills#bundled-skills).** 현재 diff 또는 전달한 PR 번호, 브랜치, 경로에서 정확성 버그를 리뷰합니다. 모델과 effort 수준에 따라 정리할 부분도 리뷰 대상에 포함됩니다. 발견 사항을 적용하려면 `--fix`를, GitHub PR 또는 GitLab 병합 요청에 게시하려면 `--comment`를, 심층 [클라우드 리뷰](/docs/ko/ultrareview)를 실행하려면 `ultra`를 전달합니다. GitLab 병합 요청에 게시하려면 Claude Code v2.1.257 이상이 필요합니다. `github.com` PR 대상에 `ultra`를 사용할 때 `--post`를 전달하면 실행 대화 상자에서 [완료된 발견 사항을 PR에 게시](/docs/ko/ultrareview#post-findings-to-the-pull-request)하는 옵션이 미리 선택됩니다. `--post`는 Claude Code v2.1.227 이상이 필요합니다. effort 수준, 대상 지정, `/simplify`와의 관계는 [로컬에서 diff 리뷰하기](/docs/ko/code-review#review-a-diff-locally)를 참조하세요. 별칭: `/review` |75| `/code-review [low\|medium\|high\|xhigh\|max\|ultra] [--fix] [--comment] [--max-findings n\|all\|default] [pr#\|branch\|path]` | **[스킬](/docs/ko/skills#bundled-skills).** 현재 diff 또는 전달한 PR 번호, 브랜치, 경로에서 정확성 버그를 리뷰합니다. 모델과 effort 수준에 따라 정리할 부분도 리뷰 대상에 포함됩니다. 발견 사항을 적용하려면 `--fix`를, GitHub PR 또는 GitLab 병합 요청에 게시하려면 `--comment`를, 심층 [클라우드 리뷰](/docs/ko/ultrareview)를 실행하려면 `ultra`를 전달합니다. GitLab 병합 요청에 게시하려면 Claude Code v2.1.257 이상이 필요합니다. `github.com` PR 대상에 `ultra`를 사용할 때 `--post`를 전달하면 실행 대화 상자에서 [완료된 발견 사항을 PR에 게시](/docs/ko/ultrareview#post-findings-to-the-pull-request)하는 옵션이 미리 선택됩니다. `--post`는 Claude Code v2.1.227 이상이 필요합니다. effort 수준, 대상 지정, `/simplify`와의 관계는 [로컬에서 diff 리뷰하기](/docs/ko/code-review#review-a-diff-locally)를 참조하세요. 별칭: `/review` |

76| `/color [color\|default]` | 현재 세션의 프롬프트 바 색상을 설정합니다. 사용 가능한 색상: `red`, `blue`, `green`, `yellow`, `purple`, `orange`, `pink`, `cyan`. 초기화하려면 `default`를 사용하고, 인수 없이 실행하면 임의의 색상이 선택됩니다. [Remote Control](/docs/ko/remote-control)이 연결되어 있으면 색상이 claude.ai/code와 동기화됩니다. 비대화형 모드(`-p`)에서도 사용할 수 있으며, Claude Code v2.1.205 이상이 필요합니다 |76| `/color [color\|default]` | 현재 세션의 프롬프트 바 색상을 설정합니다. 사용 가능한 색상: `red`, `blue`, `green`, `yellow`, `purple`, `orange`, `pink`, `cyan`. 초기화하려면 `default`를 사용하고, 인수 없이 실행하면 임의의 색상이 선택됩니다. [Remote Control](/docs/ko/remote-control)이 연결되어 있으면 색상이 claude.ai/code와 동기화됩니다. 비대화형 모드(`-p`)에서도 사용할 수 있습니다 |

77| `/compact [instructions]` | 지금까지의 대화를 요약하여 컨텍스트를 확보합니다. 선택적으로 요약의 초점에 대한 지침을 전달할 수 있습니다. [압축이 규칙, 스킬, 메모리 파일을 처리하는 방식](/docs/ko/context-window#what-survives-compaction)을 참조하세요 |77| `/compact [instructions]` | 지금까지의 대화를 요약하여 컨텍스트를 확보합니다. 선택적으로 요약의 초점에 대한 지침을 전달할 수 있습니다. [압축이 규칙, 스킬, 메모리 파일을 처리하는 방식](/docs/ko/context-window#what-survives-compaction)을 참조하세요 |

78| `/config [key=value ...]` | 테마, 모델, [출력 스타일](/docs/ko/output-styles) 및 기타 환경설정을 조정하는 [설정](/docs/ko/settings) 인터페이스를 엽니다. 하나 이상의 `key=value` 쌍을 전달하면 인터페이스를 열지 않고 설정을 직접 지정할 수 있습니다(예: `/config thinking=false`, `/config theme=dark`, `/config model=sonnet`). `key=value` 형식은 비대화형 모드(`-p`)와 [Remote Control](/docs/ko/remote-control)을 통한 Claude 모바일 앱에서도 작동합니다. `key=value` 형식으로는 [`autoContinueAtUsageLimit`](/docs/ko/interactive-mode#turn-automatic-continue-off)처럼 패널에서 확인이 필요한 설정을 켤 수 없지만, 끌 수는 있습니다. 허용되는 키 목록을 보려면 `/config --help`를 실행합니다. 별칭: `/settings` |78| `/config [key=value ...]` | 테마, 모델, [출력 스타일](/docs/ko/output-styles) 및 기타 환경설정을 조정하는 [설정](/docs/ko/settings) 인터페이스를 엽니다. 하나 이상의 `key=value` 쌍을 전달하면 인터페이스를 열지 않고 설정을 직접 지정할 수 있습니다(예: `/config thinking=false`, `/config theme=dark`, `/config model=sonnet`). `key=value` 형식은 비대화형 모드(`-p`)와 [Remote Control](/docs/ko/remote-control)을 통한 Claude 모바일 앱에서도 작동합니다. `key=value` 형식으로는 [`autoContinueAtUsageLimit`](/docs/ko/interactive-mode#turn-automatic-continue-off)처럼 패널에서 확인이 필요한 설정을 켤 수 없지만, 끌 수는 있습니다. 허용되는 키 목록을 보려면 `/config --help`를 실행합니다. 별칭: `/settings` |

79| `/context [all]` | 현재 컨텍스트 사용량을 색상 그리드로 시각화합니다. 컨텍스트를 많이 사용하는 도구, 메모리 비대화, 용량 경고에 대한 최적화 제안을 표시합니다. 대화가 컨텍스트 윈도우를 초과하면 출력에 한도를 얼마나 초과했는지와 공간을 확보하는 명령을 알려주는 [경고](/docs/ko/errors#context-exceeds-the-token-limit)가 포함됩니다. [전체 화면 모드](/docs/ko/fullscreen)에서는 그리드가 보이도록 `/context`가 항목별 세부 내역을 접습니다. 펼치려면 `all`을 전달합니다 |79| `/context [all]` | 현재 컨텍스트 사용량을 색상 그리드로 시각화합니다. 컨텍스트를 많이 사용하는 도구, 메모리 비대화, 용량 경고에 대한 최적화 제안을 표시합니다. 대화가 컨텍스트 윈도우를 초과하면 출력에 한도를 얼마나 초과했는지와 공간을 확보하는 명령을 알려주는 [경고](/docs/ko/errors#context-exceeds-the-token-limit)가 포함됩니다. [전체 화면 모드](/docs/ko/fullscreen)에서는 그리드가 보이도록 `/context`가 항목별 세부 내역을 접습니다. 펼치려면 `all`을 전달합니다 |

91| `/effort [level\|auto\|status\|ultracode [on\|off]]` | [effort 수준](/docs/ko/model-config#adjust-effort-level)을 `low`부터 `xhigh`, `max` 또는 `auto`로 설정합니다. `status`는 현재 수준을 출력합니다. `ultracode` 또는 `ultracode on`은 현재 수준에서 세션의 [ultracode](/docs/ko/workflows#let-claude-decide-with-ultracode)를 켜고, `ultracode off`는 끕니다. [`ultracode`](/docs/ko/settings-reference#ultracode) 키는 유지됩니다. `max`는 세션에만 적용됩니다. `on` 및 `off` 인수와 현재 수준 유지 기능은 Claude Code v2.1.284 이상이 필요합니다. v2.1.284 이전에는 `/effort ultracode`가 세션을 `xhigh`로 설정했고, `/effort ultracode off`는 `Invalid argument`로 실패했습니다. Claude가 응답하는 중에 실행하면, Claude Code가 [캐시 경고](/docs/ko/prompt-caching#changing-effort-level)를 표시하는 경우 이를 확인한 후 해당 턴의 다음 요청에 새 수준을 적용합니다. v2.1.242 이전에는 Claude Code가 Anthropic에서 가져온 기능 플래그에 따라 명령을 턴 도중에 실행할지 턴이 끝날 때까지 대기열에 둘지 결정했으며, [서드 파티 제공업체](/docs/ko/third-party-integrations) 사용 시처럼 [기능 플래그를 가져오지](/docs/ko/env-vars#features-that-need-feature-flag-fetching) 않는 세션에서는 항상 대기열에 두었습니다. `-p`에서 작동합니다 |91| `/effort [level\|auto\|status\|ultracode [on\|off]]` | [effort 수준](/docs/ko/model-config#adjust-effort-level)을 `low`부터 `xhigh`, `max` 또는 `auto`로 설정합니다. `status`는 현재 수준을 출력합니다. `ultracode` 또는 `ultracode on`은 현재 수준에서 세션의 [ultracode](/docs/ko/workflows#let-claude-decide-with-ultracode)를 켜고, `ultracode off`는 끕니다. [`ultracode`](/docs/ko/settings-reference#ultracode) 키는 유지됩니다. `max`는 세션에만 적용됩니다. `on` 및 `off` 인수와 현재 수준 유지 기능은 Claude Code v2.1.284 이상이 필요합니다. v2.1.284 이전에는 `/effort ultracode`가 세션을 `xhigh`로 설정했고, `/effort ultracode off`는 `Invalid argument`로 실패했습니다. Claude가 응답하는 중에 실행하면, Claude Code가 [캐시 경고](/docs/ko/prompt-caching#changing-effort-level)를 표시하는 경우 이를 확인한 후 해당 턴의 다음 요청에 새 수준을 적용합니다. v2.1.242 이전에는 Claude Code가 Anthropic에서 가져온 기능 플래그에 따라 명령을 턴 도중에 실행할지 턴이 끝날 때까지 대기열에 둘지 결정했으며, [서드 파티 제공업체](/docs/ko/third-party-integrations) 사용 시처럼 [기능 플래그를 가져오지](/docs/ko/env-vars#features-that-need-feature-flag-fetching) 않는 세션에서는 항상 대기열에 두었습니다. `-p`에서 작동합니다 |

92| `/exit` | CLI를 종료합니다. 연결된 [백그라운드 세션](/docs/ko/agent-view#attach-to-a-session)에서는 분리되며 세션은 계속 실행됩니다. 별칭: `/quit` |92| `/exit` | CLI를 종료합니다. 연결된 [백그라운드 세션](/docs/ko/agent-view#attach-to-a-session)에서는 분리되며 세션은 계속 실행됩니다. 별칭: `/quit` |

93| `/export [filename]` | 현재 대화를 일반 텍스트로 내보냅니다. 파일 이름을 지정하면 해당 파일에 직접 기록합니다. 지정하지 않으면 클립보드에 복사하거나 파일로 저장하는 대화 상자가 열립니다 |93| `/export [filename]` | 현재 대화를 일반 텍스트로 내보냅니다. 파일 이름을 지정하면 해당 파일에 직접 기록합니다. 지정하지 않으면 클립보드에 복사하거나 파일로 저장하는 대화 상자가 열립니다 |

94| `/fast [on\|off]` | [빠른 모드](/docs/ko/fast-mode)를 켜거나 끕니다. Claude가 응답하는 중에 실행하면 Claude Code가 턴이 끝날 때까지 기다리지 않고 빠른 모드를 전환하지만, 진행 중인 턴은 원래 속도로 완료됩니다. v2.1.242 이전에는 Claude Code가 Anthropic에서 가져온 기능 플래그에 따라 명령을 턴 도중에 실행할지 턴이 끝날 때까지 대기열에 둘지 결정했으며, [기능 플래그를 가져오지](/docs/ko/env-vars#features-that-need-feature-flag-fetching) 않는 세션에서는 항상 대기열에 두었습니다. `-p`를 사용한 비대화형 모드에서는 사용이 제한됩니다. [빠른 모드 전환](/docs/ko/fast-mode#toggle-fast-mode)을 참조하세요. Claude Code v2.1.205 이상이 필요합니다 |94| `/fast [on\|off]` | [빠른 모드](/docs/ko/fast-mode)를 켜거나 끕니다. Claude가 응답하는 중에 실행하면 Claude Code가 턴이 끝날 때까지 기다리지 않고 빠른 모드를 전환하지만, 진행 중인 턴은 원래 속도로 완료됩니다. v2.1.242 이전에는 Claude Code가 Anthropic에서 가져온 기능 플래그에 따라 명령을 턴 도중에 실행할지 턴이 끝날 때까지 대기열에 둘지 결정했으며, [기능 플래그를 가져오지](/docs/ko/env-vars#features-that-need-feature-flag-fetching) 않는 세션에서는 항상 대기열에 두었습니다. `-p`를 사용한 비대화형 모드에서는 사용이 제한됩니다. [빠른 모드 전환](/docs/ko/fast-mode#toggle-fast-mode)을 참조하세요 |

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

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

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

111| `/login` | Anthropic 계정에 로그인합니다 |111| `/login` | Anthropic 계정에 로그인합니다 |

112| `/logout` | Anthropic 계정에서 로그아웃합니다 |112| `/logout` | Anthropic 계정에서 로그아웃합니다 |

113| `/loop [interval] [prompt]` | **[스킬](/docs/ko/skills#bundled-skills).** 세션이 열려 있는 동안 프롬프트를 반복 실행합니다. 간격을 생략하면 Claude가 [반복 간격을 스스로 조절](/docs/ko/scheduled-tasks#let-claude-choose-the-interval)합니다. 프롬프트를 생략하면 Claude가 [기본 제공 유지 관리 프롬프트](/docs/ko/scheduled-tasks#run-the-built-in-maintenance-prompt) 또는 사용자의 [`loop.md`](/docs/ko/scheduled-tasks#customize-the-default-prompt-with-loop-md)를 실행합니다. 예: `/loop 5m check if the deploy finished`. [일정에 따라 프롬프트 실행](/docs/ko/scheduled-tasks)을 참조하세요. 별칭: `/proactive` |113| `/loop [interval] [prompt]` | **[스킬](/docs/ko/skills#bundled-skills).** 세션이 열려 있는 동안 프롬프트를 반복 실행합니다. 간격을 생략하면 Claude가 [반복 간격을 스스로 조절](/docs/ko/scheduled-tasks#let-claude-choose-the-interval)합니다. 프롬프트를 생략하면 Claude가 [기본 제공 유지 관리 프롬프트](/docs/ko/scheduled-tasks#run-the-built-in-maintenance-prompt) 또는 사용자의 [`loop.md`](/docs/ko/scheduled-tasks#customize-the-default-prompt-with-loop-md)를 실행합니다. 예: `/loop 5m check if the deploy finished`. [일정에 따라 프롬프트 실행](/docs/ko/scheduled-tasks)을 참조하세요. 별칭: `/proactive` |

114| `/mcp [reconnect (<server>\|all)\|enable\|disable [<server>\|all]]` | MCP 서버 연결과 OAuth 인증을 관리합니다. 인수 없이 실행하면 대화형 목록이 열리며, 서버 이름 또는 `all`과 함께 `reconnect`, `enable`, `disable`을 전달하면 목록을 열지 않고 연결 상태를 변경합니다. `reconnect all`은 [실패했거나 인증이 필요한 모든 서버를 재시도](/docs/ko/mcp#retry-failed-servers-yourself)합니다. 비대화형 모드(`-p`)에서도 사용할 수 있으며, 이 경우 인수 없이 실행하면 목록을 여는 대신 서버 상태의 텍스트 요약을 출력합니다. Claude Code v2.1.205 이상이 필요합니다 |114| `/mcp [reconnect (<server>\|all)\|enable\|disable [<server>\|all]]` | MCP 서버 연결과 OAuth 인증을 관리합니다. 인수 없이 실행하면 대화형 목록이 열리며, 서버 이름 또는 `all`과 함께 `reconnect`, `enable`, `disable`을 전달하면 목록을 열지 않고 연결 상태를 변경합니다. `reconnect all`은 [실패했거나 인증이 필요한 모든 서버를 재시도](/docs/ko/mcp#retry-failed-servers-yourself)합니다. 비대화형 모드(`-p`)에서 인수 없이 실행하면 목록을 여는 대신 서버 상태의 텍스트 요약을 출력합니다 |

115| `/memory` | `CLAUDE.md` 파일을 편집하고, [자동 메모리](/docs/ko/memory#auto-memory)를 활성화 또는 비활성화하며, 자동 메모리 항목을 확인합니다 |115| `/memory` | `CLAUDE.md` 파일을 편집하고, [자동 메모리](/docs/ko/memory#auto-memory)를 활성화 또는 비활성화하며, 자동 메모리 항목을 확인합니다 |

116| `/mobile` | Claude 모바일 앱을 다운로드할 수 있는 QR 코드를 표시합니다. 별칭: `/ios`, `/android` |116| `/mobile` | Claude 모바일 앱을 다운로드할 수 있는 QR 코드를 표시합니다. 별칭: `/ios`, `/android` |

117| `/model [model]` | AI 모델을 전환하고 새 세션의 기본값으로 저장합니다. 지원되는 모델의 경우 왼쪽/오른쪽 화살표를 사용하여 [effort 수준을 조정](/docs/ko/model-config#adjust-effort-level)합니다. 인수 없이 실행하면 선택기가 열리며, 행에서 `s`를 누르면 현재 세션에 대해서만 전환합니다. [Claude Code가 전환 확인을 요청하는 경우](/docs/ko/prompt-caching#switching-models)를 참조하세요. Claude Code가 확인을 요청하는 경우 전환을 확인하면, 현재 응답이 끝날 때까지 기다리지 않고 변경 사항을 적용합니다. v2.1.242 이전에는 Claude Code가 Anthropic에서 가져온 기능 플래그에 따라 명령을 턴 도중에 실행할지 턴이 끝날 때까지 대기열에 둘지 결정했으며, [서드 파티 제공업체](/docs/ko/third-party-integrations) 사용 시처럼 [기능 플래그를 가져오지](/docs/ko/env-vars#features-that-need-feature-flag-fetching) 않는 세션에서는 항상 대기열에 두었습니다. 비대화형 모드(`-p`)에서도 선택기 대신 모델 인수와 함께 사용할 수 있으며, 이 경우 현재 세션에만 적용되고 기본값으로 저장되지 않습니다. Claude Code v2.1.205 이상이 필요합니다 |117| `/model [model]` | AI 모델을 전환하고 새 세션의 기본값으로 저장합니다. 지원되는 모델의 경우 왼쪽/오른쪽 화살표를 사용하여 [effort 수준을 조정](/docs/ko/model-config#adjust-effort-level)합니다. 인수 없이 실행하면 선택기가 열리며, 행에서 `s`를 누르면 현재 세션에 대해서만 전환합니다. [Claude Code가 전환 확인을 요청하는 경우](/docs/ko/prompt-caching#switching-models)를 참조하세요. Claude Code가 확인을 요청하는 경우 전환을 확인하면, 현재 응답이 끝날 때까지 기다리지 않고 변경 사항을 적용합니다. v2.1.242 이전에는 Claude Code가 Anthropic에서 가져온 기능 플래그에 따라 명령을 턴 도중에 실행할지 턴이 끝날 때까지 대기열에 둘지 결정했으며, [서드 파티 제공업체](/docs/ko/third-party-integrations) 사용 시처럼 [기능 플래그를 가져오지](/docs/ko/env-vars#features-that-need-feature-flag-fetching) 않는 세션에서는 항상 대기열에 두었습니다. 비대화형 모드(`-p`)에서도 선택기 대신 모델 인수와 함께 사용할 수 있으며, 이 경우 현재 세션에만 적용되고 기본값으로 저장되지 않습니다. Claude Code v2.1.205 이상이 필요합니다 |

130| `/release-notes` | 대화형 버전 선택기에서 변경 로그를 확인합니다. 특정 버전을 선택하여 해당 릴리스 노트를 보거나, 모든 버전을 표시하도록 선택합니다. 릴리스 노트는 Claude가 보는 대화에 들어가지 않고 트랜스크립트에 표시됩니다 |130| `/release-notes` | 대화형 버전 선택기에서 변경 로그를 확인합니다. 특정 버전을 선택하여 해당 릴리스 노트를 보거나, 모든 버전을 표시하도록 선택합니다. 릴리스 노트는 Claude가 보는 대화에 들어가지 않고 트랜스크립트에 표시됩니다 |

131| `/reload-plugins [--force]` | 다시 시작하지 않고 보류 중인 변경 사항을 적용하기 위해 모든 활성 [플러그인](/docs/ko/plugins/overview)을 다시 로드합니다. 다시 로드된 각 구성 요소의 개수를 보고하고 로드 오류를 표시합니다. 다시 로드로 인해 로드되는 MCP 도구가 바뀌어 프롬프트 캐시가 무효화되는 경우, `--force`를 전달하지 않으면 명령이 경고를 표시하고 건너뜁니다. 비대화형 모드(`-p`), Agent SDK, 데스크톱 앱에서도 사용할 수 있으며, 이 경우 세션에 직접 입력한 입력에 대해서만 실행되고 플러그인 MCP 서버 변경 사항은 적용하지 않습니다. Claude Code v2.1.260 이상이 필요합니다. [다시 시작하지 않고 플러그인 변경 사항 적용](/docs/ko/plugins/cli-reference#reload-plugins)을 참조하세요 |131| `/reload-plugins [--force]` | 다시 시작하지 않고 보류 중인 변경 사항을 적용하기 위해 모든 활성 [플러그인](/docs/ko/plugins/overview)을 다시 로드합니다. 다시 로드된 각 구성 요소의 개수를 보고하고 로드 오류를 표시합니다. 다시 로드로 인해 로드되는 MCP 도구가 바뀌어 프롬프트 캐시가 무효화되는 경우, `--force`를 전달하지 않으면 명령이 경고를 표시하고 건너뜁니다. 비대화형 모드(`-p`), Agent SDK, 데스크톱 앱에서도 사용할 수 있으며, 이 경우 세션에 직접 입력한 입력에 대해서만 실행되고 플러그인 MCP 서버 변경 사항은 적용하지 않습니다. Claude Code v2.1.260 이상이 필요합니다. [다시 시작하지 않고 플러그인 변경 사항 적용](/docs/ko/plugins/cli-reference#reload-plugins)을 참조하세요 |

132| `/reload-skills` | [스킬](/docs/ko/skills) 및 명령 디렉터리를 다시 검색하여 세션 중 디스크에서 추가되거나 변경된 스킬을 다시 시작하지 않고 사용할 수 있도록 합니다. 사용 가능한 스킬 수와 추가 또는 제거된 스킬 수를 보고합니다 |132| `/reload-skills` | [스킬](/docs/ko/skills) 및 명령 디렉터리를 다시 검색하여 세션 중 디스크에서 추가되거나 변경된 스킬을 다시 시작하지 않고 사용할 수 있도록 합니다. 사용 가능한 스킬 수와 추가 또는 제거된 스킬 수를 보고합니다 |

133| `/remote-control` | claude.ai에서 [Remote Control](/docs/ko/remote-control)로 이 세션을 사용할 수 있도록 합니다. 로그아웃 상태에서 실행하면 Remote Control에 claude.ai 구독이 필요하다는 내용과 로그인 방법이 출력됩니다. v2.1.206 이전에는 `Unknown command: /remote-control`이 표시되었습니다. 별칭: `/rc` |133| `/remote-control` | claude.ai에서 [Remote Control](/docs/ko/remote-control)로 이 세션을 사용할 수 있도록 합니다. 로그아웃 상태에서 실행하면 Remote Control에 claude.ai 구독이 필요하다는 내용과 로그인 방법이 출력됩니다. 별칭: `/rc` |

134| `/remote-env` | CLI에서 시작하는 클라우드 세션의 기본 [클라우드 환경](/docs/ko/cloud-environments#select-an-environment-from-the-cli)을 선택합니다 |134| `/remote-env` | CLI에서 시작하는 클라우드 세션의 기본 [클라우드 환경](/docs/ko/cloud-environments#select-an-environment-from-the-cli)을 선택합니다 |

135| `/rename [name]` | 현재 세션의 이름을 바꾸고 프롬프트 바에 이름을 표시합니다. 이름을 지정하지 않으면 대화 기록에서 자동으로 생성합니다. 비대화형 모드(`-p`)에서도 사용할 수 있으며, Claude Code v2.1.205 이상이 필요합니다. claude.ai와 데스크톱 앱을 포함한 모든 이름 변경 사용 환경에서, Claude Code는 새 이름의 제어 문자와 보이지 않는 문자를 공백으로 바꾸고 이름을 200자로 제한합니다. 보이지 않는 문자를 제거한 후 이름이 비어 있으면 Claude Code는 이를 거부하고 `That name is empty once invisible characters are removed. Usage: /rename <name>`을 표시합니다. 문자 대체와 길이 제한은 Claude Code v2.1.221 이상이 필요합니다 |135| `/rename [name]` | 현재 세션의 이름을 바꾸고 프롬프트 바에 이름을 표시합니다. 이름을 지정하지 않으면 대화 기록에서 자동으로 생성합니다. 비대화형 모드(`-p`)에서도 사용할 수 있습니다. claude.ai와 데스크톱 앱을 포함한 모든 이름 변경 사용 환경에서, Claude Code는 새 이름의 제어 문자와 보이지 않는 문자를 공백으로 바꾸고 이름을 200자로 제한합니다. 보이지 않는 문자를 제거한 후 이름이 비어 있으면 Claude Code는 이를 거부하고 `That name is empty once invisible characters are removed. Usage: /rename <name>`을 표시합니다. 문자 대체와 길이 제한은 Claude Code v2.1.221 이상이 필요합니다 |

136| `/resume [session]` | ID나 이름으로 대화를 재개하거나 세션 선택기를 엽니다. [백그라운드 세션](/docs/ko/agent-view)은 선택기에 `bg` 표시와 함께 나타납니다. 선택기에서 또는 ID나 이름으로 아직 실행 중인 세션을 재개하면 [해당 세션이 열립니다](/docs/ko/sessions#resume-a-running-background-session). 현재 대화는 백그라운드로 이동하고 이 터미널은 실행 중인 세션에 연결됩니다. 빈 프롬프트에서 `←`를 누르면 에이전트 보기로 돌아가며, 여기에는 떠나온 대화도 나열됩니다. v2.1.285 이전에는 Claude Code가 이를 거부하고 `claude attach`로 세션을 열거나 먼저 중지하라고 안내했습니다. 별칭: `/continue` |136| `/resume [session]` | ID나 이름으로 대화를 재개하거나 세션 선택기를 엽니다. [백그라운드 세션](/docs/ko/agent-view)은 선택기에 `bg` 표시와 함께 나타납니다. 선택기에서 또는 ID나 이름으로 아직 실행 중인 세션을 재개하면 [해당 세션이 열립니다](/docs/ko/sessions#resume-a-running-background-session). 현재 대화는 백그라운드로 이동하고 이 터미널은 실행 중인 세션에 연결됩니다. 빈 프롬프트에서 `←`를 누르면 에이전트 보기로 돌아가며, 여기에는 떠나온 대화도 나열됩니다. v2.1.285 이전에는 Claude Code가 이를 거부하고 `claude attach`로 세션을 열거나 먼저 중지하라고 안내했습니다. 별칭: `/continue` |

137| `/review [low\|medium\|high\|xhigh\|max\|ultra] [--fix] [--comment] [--max-findings n\|all\|default] [pr#\|branch\|path]` | [`/code-review`](/docs/ko/code-review#review-a-diff-locally)의 별칭입니다. 현재 diff 또는 전달한 PR 번호, 브랜치, 경로(예: `/review 1234`)를 리뷰하며, 동일한 effort 수준과 플래그를 받습니다. 수준을 지정하지 않으면 마지막으로 입력한 `low`부터 `max`까지의 수준을 재사용합니다. 정확한 규칙은 [로컬에서 diff 리뷰하기](/docs/ko/code-review#review-a-diff-locally)를 참조하세요. 심층 클라우드 리뷰에는 [`/code-review ultra`](/docs/ko/ultrareview)를 사용합니다. v2.1.223 이전에는 `/review`가 번호로 지정한 GitHub 풀 리퀘스트에 대해 단일 패스의 읽기 전용 리뷰를 실행하는 별도의 명령이었으며, 인수 없이 실행하면 선택할 수 있도록 열린 PR을 나열했습니다. v2.1.186부터 v2.1.201까지는 `/code-review medium`과 동일한 멀티 에이전트 엔진을 실행했습니다 |137| `/review [low\|medium\|high\|xhigh\|max\|ultra] [--fix] [--comment] [--max-findings n\|all\|default] [pr#\|branch\|path]` | [`/code-review`](/docs/ko/code-review#review-a-diff-locally)의 별칭입니다. 현재 diff 또는 전달한 PR 번호, 브랜치, 경로(예: `/review 1234`)를 리뷰하며, 동일한 effort 수준과 플래그를 받습니다. 수준을 지정하지 않으면 마지막으로 입력한 `low`부터 `max`까지의 수준을 재사용합니다. 정확한 규칙은 [로컬에서 diff 리뷰하기](/docs/ko/code-review#review-a-diff-locally)를 참조하세요. 심층 클라우드 리뷰에는 [`/code-review ultra`](/docs/ko/ultrareview)를 사용합니다. v2.1.223 이전에는 `/review`가 번호로 지정한 GitHub 풀 리퀘스트에 대해 단일 패스의 읽기 전용 리뷰를 실행하는 별도의 명령이었으며, 인수 없이 실행하면 선택할 수 있도록 열린 PR을 나열했습니다. v2.1.186부터 v2.1.201까지는 `/code-review medium`과 동일한 멀티 에이전트 엔진을 실행했습니다 |

138| `/rewind` | 대화 및/또는 코드를 이전 시점으로 되감거나, 선택한 메시지부터 요약합니다. [체크포인트](/docs/ko/checkpointing)를 참조하세요. 별칭: `/checkpoint`, `/undo` |138| `/rewind` | 대화 및/또는 코드를 이전 시점으로 되감거나, 선택한 메시지부터 요약합니다. [체크포인트](/docs/ko/checkpointing)를 참조하세요. 별칭: `/checkpoint`, `/undo` |

413 팁:413 팁:

414 414 

415 * 파일 경로는 상대 또는 절대 경로일 수 있습니다415 * 파일 경로는 상대 또는 절대 경로일 수 있습니다

416 * @를 입력하여 경로 제안 메뉴를 열고, Enter 또는 Tab을 눌러 강조 표시된 경로를 수락한 다음 다시 Enter를 눌러 메시지를 보내기416 * `@`를 입력하여 경로 제안 메뉴를 열고, Enter 또는 Tab을 눌러 강조 표시된 경로를 수락한 다음 다시 Enter를 눌러 메시지를 보내기

417 * @ 파일 참조는 파일의 디렉토리 및 상위 디렉토리에 `CLAUDE.md`를 추가합니다417 * @ 파일 참조는 파일의 디렉토리 및 상위 디렉토리에 `CLAUDE.md`를 추가합니다

418 * 디렉토리 참조는 내용이 아닌 파일 목록을 표시합니다418 * 디렉토리 참조는 내용이 아닌 파일 목록을 표시합니다

419 * 단일 메시지에서 여러 파일을 참조할 수 있습니다 (예: "@file1.js and @file2.js")419 * 단일 메시지에서 여러 파일을 참조할 수 있습니다 (예: "@file1.js and @file2.js")

420</Tip>420</Tip>

421 421 

422`@` 참조가 메시지에 파일 내용과 디렉토리 목록을 포함하지 않도록 하려면 셸 또는 사용자 설정에서 [`CLAUDE_CODE_DISABLE_FILE_MENTIONS=1`](/docs/ko/env-vars#variables)을 설정하십시오. 그러면 Claude는 참조된 경로를 받으며, 파일 도구를 사용해 해당 경로를 읽으라는 안내도 함께 받습니다. 이 변수는 Claude Code v2.1.299 이상이 필요하며, Claude Code는 프로젝트 및 로컬 설정에서는 이 변수를 무시합니다.

423 

422***424***

423 425 

424<h3 id="run-claude-on-a-schedule">426<h3 id="run-claude-on-a-schedule">

1602| 시스템 프롬프트 및 출력 스타일 | 계속 적용됨 |1602| 시스템 프롬프트 및 출력 스타일 | 계속 적용됨 |

1603| 프로젝트 루트 CLAUDE.md 및 범위 미지정 규칙 | 디스크에서 다시 주입됨 |1603| 프로젝트 루트 CLAUDE.md 및 범위 미지정 규칙 | 디스크에서 다시 주입됨 |

1604| 자동 메모리 | 디스크에서 다시 주입됨 |1604| 자동 메모리 | 디스크에서 다시 주입됨 |

1605| [Git 상태 스냅샷](/docs/ko/settings-reference#includegitinstructions) | Claude Code가 저장소에서 새로운 것을 읽음 |1605| [Git 상태 스냅샷](/docs/ko/settings-reference#includegitinstructions) | 세션이 스냅샷과 함께 시작된 경우, Claude Code가 저장소에서 새로운 스냅샷을 읽음 |

1606| [플랜 모드](/docs/ko/permission-modes#analyze-before-you-edit-with-plan-mode)에서 Claude가 작성한 계획 | 디스크에서 다시 주입됨 |1606| [플랜 모드](/docs/ko/permission-modes#analyze-before-you-edit-with-plan-mode)에서 Claude가 작성한 계획 | 디스크에서 다시 주입됨 |

1607| `paths:` frontmatter가 있는 규칙 | Claude Code가 [필요할 때](/docs/ko/memory#path-specific-rules) 다시 로드함 |1607| `paths:` frontmatter가 있는 규칙 | Claude Code가 [필요할 때](/docs/ko/memory#path-specific-rules) 다시 로드함 |

1608| 하위 디렉토리의 중첩 CLAUDE.md | Claude Code가 [필요할 때](/docs/ko/memory#how-claude-md-files-load) 다시 로드함 |1608| 하위 디렉토리의 중첩 CLAUDE.md | Claude Code가 [필요할 때](/docs/ko/memory#how-claude-md-files-load) 다시 로드함 |

1622 컨텍스트가 가득 찰 때1622 컨텍스트가 가득 찰 때

1623</h2>1623</h2>

1624 1624 

1625Claude Code는 제한에 접근할 때 자동으로 압축하므로 컨텍스트 윈도우가 가득 차도 세션이 끝나지 않습니다. 자동 패스는 타임라인의 `/compact` 단계와 동일한 방식으로 작동합니다. [컨텍스트가 가득 찰 때](/docs/ko/how-claude-code-works#when-context-fills-up)에서 보존되는 항목을 참조하세요.1625Claude Code는 제한에 접근할 때 자동으로 압축하므로 컨텍스트 윈도우가 가득 차도 세션이 끝나지 않습니다. 자동 패스는 타임라인의 `/compact` 단계와 동일한 방식으로 작동합니다. [컨텍스트가 가득 찰 때](/docs/ko/how-claude-code-works#when-context-fills-up)에서 보존되는 항목을 참조하세요. 유휴 상태로 둔 대화도 Claude Code가 압축하는 경우에 대해서는 [유휴 압축](/docs/ko/settings-reference#idlecompaction)을 참조하세요.

1626 1626 

1627자동 패스가 실행되기 전에 조치를 취할 수도 있습니다:1627자동 패스가 실행되기 전에 조치를 취할 수도 있습니다:

1628 1628 

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

129* **Claude Code가 시작되기 전에 터미널에 쓰지 마십시오.** `exec` 전에 인쇄된 모든 것은 세션이 초기화 전에 종료되면 충돌 원인으로 보고됩니다.129* **Claude Code가 시작되기 전에 터미널에 쓰지 마십시오.** `exec` 전에 인쇄된 모든 것은 세션이 초기화 전에 종료되면 충돌 원인으로 보고됩니다.

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

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

131 132 

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

133 런처 값의 형식134 런처 값의 형식

170| Skill이 `/skills`에 나타나지 않습니다 | Skill 파일이 폴더 대신 `.claude/skills/name.md`에 있습니다 | 폴더 내에 `SKILL.md`를 사용하세요: `.claude/skills/name/SKILL.md`. |170| Skill이 `/skills`에 나타나지 않습니다 | Skill 파일이 폴더 대신 `.claude/skills/name.md`에 있습니다 | 폴더 내에 `SKILL.md`를 사용하세요: `.claude/skills/name/SKILL.md`. |

171| Skill이 `/skills`에 나타나지만 Claude가 호출하지 않습니다 | Skill의 frontmatter에 `disable-model-invocation: true`가 있거나, 설명이 요청을 표현하는 방식과 일치하지 않습니다 | `/skills`의 배지를 확인하세요: "user-only" 레이블은 Claude가 자동으로 트리거하지 않음을 의미합니다. [skill 호출](/docs/ko/skills)을 참조하세요. |171| Skill이 `/skills`에 나타나지만 Claude가 호출하지 않습니다 | Skill의 frontmatter에 `disable-model-invocation: true`가 있거나, 설명이 요청을 표현하는 방식과 일치하지 않습니다 | `/skills`의 배지를 확인하세요: "user-only" 레이블은 Claude가 자동으로 트리거하지 않음을 의미합니다. [skill 호출](/docs/ko/skills)을 참조하세요. |

172| 하위 디렉토리 `CLAUDE.md` 지침이 무시되는 것처럼 보입니다 | 하위 디렉토리 파일은 세션 시작 시가 아니라 필요에 따라 로드됩니다 | 하위 디렉토리의 `CLAUDE.md`를 로드하려면 Claude에게 해당 하위 디렉토리의 다른 파일을 읽도록 요청하세요. [하위 디렉토리 파일이 로드되는 시점](/docs/ko/memory#how-claude-md-files-load)을 참조하세요. |172| 하위 디렉토리 `CLAUDE.md` 지침이 무시되는 것처럼 보입니다 | 하위 디렉토리 파일은 세션 시작 시가 아니라 필요에 따라 로드됩니다 | 하위 디렉토리의 `CLAUDE.md`를 로드하려면 Claude에게 해당 하위 디렉토리의 다른 파일을 읽도록 요청하세요. [하위 디렉토리 파일이 로드되는 시점](/docs/ko/memory#how-claude-md-files-load)을 참조하세요. |

173| Subagent가 `CLAUDE.md` 지침을 무시합니다 | 기본 제공 Explore 및 Plan 에이전트는 `CLAUDE.md`를 건너뜁니다. 사용자 정의 subagent는 정의가 [`omitClaudeMd`](/docs/ko/sub-agents#supported-frontmatter-fields)를 설정하지 않는 한 메인 대화와 동일한 방식으로 로드합니다 | Explore 또는 Plan의 경우 위임 프롬프트에서 지침을 다시 명시하세요. `omitClaudeMd`를 설정하는 subagent의 경우 필드를 제거하세요. 다른 사용자 정의 subagent의 경우 중요한 지침을 에이전트 파일 본문에 넣으세요. 이는 에이전트의 시스템 프롬프트가 됩니다. [시작 시 로드되는 항목](/docs/ko/sub-agents#what-loads-at-startup)을 참조하세요. |173| 서브에이전트가 `CLAUDE.md` 지침을 무시합니다 | 기본 제공 Explore 및 Plan 에이전트는 시작 시 `CLAUDE.md`를 건너뜁니다. 사용자 정의 서브에이전트는 정의에 [`omitClaudeMd`](/docs/ko/sub-agents#supported-frontmatter-fields)가 설정되어 있지 않는 한 메인 대화와 동일한 방식으로 로드합니다 | Explore 또는 Plan의 경우 위임 프롬프트에서 지침을 다시 명시하세요. `omitClaudeMd`를 설정하는 서브에이전트의 경우 필드를 제거하세요. 다른 사용자 정의 서브에이전트의 경우 중요한 지침을 에이전트 파일 본문에 넣으세요. 이는 에이전트의 시스템 프롬프트가 됩니다. [시작 시 로드되는 항목](/docs/ko/sub-agents#what-loads-at-startup)을 참조하세요. |

174| 세션 종료 시 정리 로직이 실행되지 않습니다 | `SessionEnd` hook이 구성되지 않았습니다 | `settings.json`에 `SessionEnd` hook을 추가하세요. [hook 이벤트 목록](/docs/ko/hooks#hook-events)을 참조하세요. |174| 세션 종료 시 정리 로직이 실행되지 않습니다 | `SessionEnd` hook이 구성되지 않았습니다 | `settings.json`에 `SessionEnd` hook을 추가하세요. [hook 이벤트 목록](/docs/ko/hooks#hook-events)을 참조하세요. |

175| `.mcp.json`의 MCP 서버가 로드되지 않습니다 | 파일이 `.claude/` 아래에 있거나, 서버가 VS Code의 `mcp.json`처럼 최상위 `servers` 키 아래에 있으며, `mcpServers` 대신 | 프로젝트 MCP 구성은 `.claude/` 내부가 아닌 저장소 루트에 `.mcp.json`으로 이동하며, 서버는 `mcpServers` 키 아래에 있습니다. [MCP 구성](/docs/ko/mcp)을 참조하세요. |175| `.mcp.json`의 MCP 서버가 로드되지 않습니다 | 파일이 `.claude/` 아래에 있거나, 서버가 VS Code의 `mcp.json`처럼 최상위 `servers` 키 아래에 있으며, `mcpServers` 대신 | 프로젝트 MCP 구성은 `.claude/` 내부가 아닌 저장소 루트에 `.mcp.json`으로 이동하며, 서버는 `mcpServers` 키 아래에 있습니다. [MCP 구성](/docs/ko/mcp)을 참조하세요. |

176| `settings.json`의 `mcpServers` 아래에 추가된 MCP 서버가 나타나지 않습니다 | `settings.json`이 `mcpServers` 키를 읽지 않습니다 | 저장소 루트의 `.mcp.json`에서 프로젝트 서버를 정의하거나 사용자 범위 서버의 경우 `claude mcp add --scope user`를 실행하세요. [MCP 구성](/docs/ko/mcp)을 참조하세요. |176| `settings.json`의 `mcpServers` 아래에 추가된 MCP 서버가 나타나지 않습니다 | `settings.json`이 `mcpServers` 키를 읽지 않습니다 | 저장소 루트의 `.mcp.json`에서 프로젝트 서버를 정의하거나 사용자 범위 서버의 경우 `claude mcp add --scope user`를 실행하세요. [MCP 구성](/docs/ko/mcp)을 참조하세요. |

101| **Accept edits** | `acceptEdits` | Claude는 파일 편집을 자동으로 수락하고 `mkdir`, `touch`, `mv`와 같은 일반적인 파일시스템 명령을 자동으로 수락하지만 다른 터미널 명령 실행 전에는 여전히 요청합니다. 파일 변경을 신뢰하고 더 빠른 반복을 원할 때 사용합니다. |101| **Accept edits** | `acceptEdits` | Claude는 파일 편집을 자동으로 수락하고 `mkdir`, `touch`, `mv`와 같은 일반적인 파일시스템 명령을 자동으로 수락하지만 다른 터미널 명령 실행 전에는 여전히 요청합니다. 파일 변경을 신뢰하고 더 빠른 반복을 원할 때 사용합니다. |

102| **Plan** | `plan` | Claude는 파일을 읽고 명령을 실행하여 탐색한 다음 소스 코드를 편집하지 않고 계획을 제안합니다. 먼저 접근 방식을 검토하려는 복잡한 작업에 좋습니다. |102| **Plan** | `plan` | Claude는 파일을 읽고 명령을 실행하여 탐색한 다음 소스 코드를 편집하지 않고 계획을 제안합니다. 먼저 접근 방식을 검토하려는 복잡한 작업에 좋습니다. |

103| **Auto** | `auto` | Claude는 일상적인 프롬프트 없이 실행됩니다. 셸 명령 및 네트워크 요청과 같은 작업이 실행되기 전에 백그라운드 분류기가 요청과의 정렬을 확인합니다. [자동 모드가 사용 가능](#auto-mode-availability)할 때 나타나며, 별도의 Settings 토글이 없습니다. |103| **Auto** | `auto` | Claude는 일상적인 프롬프트 없이 실행됩니다. 셸 명령 및 네트워크 요청과 같은 작업이 실행되기 전에 백그라운드 분류기가 요청과의 정렬을 확인합니다. [자동 모드가 사용 가능](#auto-mode-availability)할 때 나타나며, 별도의 Settings 토글이 없습니다. |

104| **Bypass permissions** | `bypassPermissions` | Claude는 [이 모드가 자동으로 승인하지 않는 작업](/docs/ko/permission-modes#actions-no-mode-auto-approves), Claude가 [외부 사이트에서 작동](#browse-external-sites)할 때 안전 분류기, 또는 [세션 아카이빙](#work-across-sessions)과 같이 Claude가 항상 먼저 묻는 데스크톱 작업을 제외하고 권한 프롬프트 없이 실행됩니다. CLI의 `--dangerously-skip-permissions`와 동일합니다. Pro 및 Max 플랜에서는 Settings → Claude Code의 "Allow bypass permissions mode"에서 활성화합니다. Team 및 Enterprise 플랜에서는 Settings 토글이 없으며 조직 정책이 대신 제어합니다. 샌드박스 컨테이너 또는 VM에서만 사용합니다. |104| **Bypass permissions** | `bypassPermissions` | Claude는 [어떤 모드도 자동으로 승인하지 않는 작업](/docs/ko/permission-modes#actions-no-mode-auto-approves), Claude가 [외부 사이트에서 작동](#browse-external-sites)할 때의 안전 분류기, 또는 세션 삭제와 같은 데스크톱 작업(단, [세션 아카이브](#work-across-sessions)는 해당되지 않음)을 제외하고 권한 프롬프트 없이 실행됩니다. CLI의 `--dangerously-skip-permissions`와 동일합니다. Pro 및 Max 플랜에서는 Settings → Claude Code의 "Allow bypass permissions mode"에서 활성화합니다. Team 및 Enterprise 플랜에서는 Settings 토글이 없으며 조직 정책이 대신 제어합니다. 샌드박스 컨테이너 또는 VM에서만 사용합니다. |

105 105 

106이전 버전의 Code 탭은 이러한 모드를 Ask permissions, Auto accept edits, Plan mode로 표시했습니다.106이전 버전의 Code 탭은 이러한 모드를 Ask permissions, Auto accept edits, Plan mode로 표시했습니다.

107 107 

131 131 

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

133 133 

134<Note>

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

136</Note>

137 

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

135 139 

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

218 222 

219<Note>223<Note>

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

225 

226 [SSH 세션](#ssh-sessions)에서는 Claude가 원격 머신에서 브랜치를 푸시하고 `gh pr create`를 실행하므로, **Create PR**을 클릭하기 전에 원격 머신에 `git`과 `gh`를 설정합니다. SSH 세션에서는 Desktop이 설치를 요청하지 않으므로 원격 머신에 `gh`를 직접 설치합니다. 그런 다음 원격 머신에서 `git push`가 작동하는지, 그리고 `gh auth status`가 로그인된 상태로 보고하는지 확인합니다.

221</Note>227</Note>

222 228 

223<h2 id="arrange-your-workspace">229<h2 id="arrange-your-workspace">

453 459 

454Claude Code는 세션 간에 4가지 안전 동작을 적용합니다:460Claude Code는 세션 간에 4가지 안전 동작을 적용합니다:

455 461 

456* 세션을 아카이브하기 전에 Claude는 먼저 묻습니다. Auto 및 Bypass 권한을 포함한 모든 권한 모드에서 승인 카드가 표시됩니다.462* Claude가 세션을 아카이브하기 전에 승인 카드가 표시됩니다. 단, 자동 모드와 Bypass permissions 모드에서는 Claude가 승인 카드 없이 세션을 아카이브할 수 있습니다. 확인을 받으려면 Manual로 전환하세요.

457* 이 사용 환경을 통해 Claude는 예약 작업 실행과 같이 아무도 보고 있지 않은 세션에서 교차 세션 메시지를 보낼 수 없으며 그러한 세션으로 메시지를 전달할 수도 없습니다.463* 이 사용 환경을 통해 Claude는 예약 작업 실행과 같이 아무도 보고 있지 않은 세션에서 교차 세션 메시지를 보낼 수 없으며 그러한 세션으로 메시지를 전달할 수도 없습니다.

458* Claude Code는 수신 세션 자체에 [교차 세션 메시징](/docs/ko/cross-session-messaging#availability)이 없더라도 이 사용 환경의 각 메시지를 수신 세션의 [인바운드 컨트롤](/docs/ko/cross-session-messaging#control-inbound-messages)에 대해 확인합니다. 수신 세션에서 [`crossSessionInbound`](/docs/ko/settings-reference#crosssessioninbound)를 `refuse`로 설정하면 Claude Code는 이 사용 환경의 메시지를 삭제합니다. Claude Code는 거부를 Claude 데스크톱 앱에 보고합니다. v2.1.234 이전에는 Claude Code가 교차 세션 메시징이 없는 수신 세션으로 가는 이 사용 환경의 모든 메시지를 삭제했습니다.464* Claude Code는 수신 세션 자체에 [교차 세션 메시징](/docs/ko/cross-session-messaging#availability)이 없더라도 이 사용 환경의 각 메시지를 수신 세션의 [인바운드 컨트롤](/docs/ko/cross-session-messaging#control-inbound-messages)에 대해 확인합니다. 수신 세션에서 [`crossSessionInbound`](/docs/ko/settings-reference#crosssessioninbound)를 `refuse`로 설정하면 Claude Code는 이 사용 환경의 메시지를 삭제합니다. Claude Code는 거부를 Claude 데스크톱 앱에 보고합니다. v2.1.234 이전에는 Claude Code가 교차 세션 메시징이 없는 수신 세션으로 가는 이 사용 환경의 모든 메시지를 삭제했습니다.

459* Claude Code는 각 수신 메시지를 인용하고 보낸 세션에 귀속시키며, Claude는 메시지에 따라 행동할 때에도 여전히 수신 세션의 자체 권한 설정을 따릅니다.465* Claude Code는 각 수신 메시지를 인용하고 보낸 세션에 귀속시키며, Claude는 메시지에 따라 행동할 때에도 여전히 수신 세션의 자체 권한 설정을 따릅니다.

546 552 

547[Skills](/docs/ko/skills)는 Claude가 할 수 있는 것을 확장합니다. Claude는 관련이 있을 때 자동으로 로드하거나 직접 호출할 수 있습니다: 프롬프트 상자에서 `/`를 입력하거나 **+** 버튼을 클릭하고 **Slash commands**를 선택하여 사용 가능한 것을 찾아봅니다. 여기에는 [내장 명령](/docs/ko/commands), [사용자 정의 skills](/docs/ko/skills#create-your-first-skill), 코드베이스의 프로젝트 skills, [설치된 플러그인](/docs/ko/plugins/install)의 skills가 포함됩니다. 하나를 선택하면 입력 필드에 강조 표시됩니다. 그 후 작업을 입력하고 평소대로 보냅니다.553[Skills](/docs/ko/skills)는 Claude가 할 수 있는 것을 확장합니다. Claude는 관련이 있을 때 자동으로 로드하거나 직접 호출할 수 있습니다: 프롬프트 상자에서 `/`를 입력하거나 **+** 버튼을 클릭하고 **Slash commands**를 선택하여 사용 가능한 것을 찾아봅니다. 여기에는 [내장 명령](/docs/ko/commands), [사용자 정의 skills](/docs/ko/skills#create-your-first-skill), 코드베이스의 프로젝트 skills, [설치된 플러그인](/docs/ko/plugins/install)의 skills가 포함됩니다. 하나를 선택하면 입력 필드에 강조 표시됩니다. 그 후 작업을 입력하고 평소대로 보냅니다.

548 554 

549Claude가 작업 중일 때 다른 메시지와 동일하게 명령을 보낼 수 있으며, 턴이 완료되면 세션이 유휴 상태로 돌아갑니다. v2.1.206 이전에는 턴 중에 보낸 명령이 세션을 실행 중으로 표시된 상태로 남길 수 있었고 그 후에 보낸 메시지는 전달되지 않았습니다.555Claude가 작업 중일 때 다른 메시지와 동일하게 명령을 보낼 수 있으며, 턴이 완료되면 세션이 유휴 상태로 돌아갑니다.

550 556 

551로컬 세션은 `~/.claude/skills/`에서 개인 skills를 로드합니다. [SSH](#ssh-sessions) 세션은 사용자 머신이 아닌 원격 호스트의 홈 디렉토리에서 `~/.claude/skills/`를 읽습니다.557로컬 세션은 `~/.claude/skills/`에서 개인 skills를 로드합니다. [SSH](#ssh-sessions) 세션은 사용자 머신이 아닌 원격 호스트의 홈 디렉토리에서 `~/.claude/skills/`를 읽습니다.

552 558 

693 699 

694* **`true`**: Claude는 자동으로 사용 가능한 포트를 찾아 사용합니다. 대부분의 개발 서버에 적합합니다.700* **`true`**: Claude는 자동으로 사용 가능한 포트를 찾아 사용합니다. 대부분의 개발 서버에 적합합니다.

695* **`false`**: Claude는 오류로 실패합니다. OAuth 콜백 또는 CORS allowlists와 같이 서버가 특정 포트를 사용해야 할 때 사용합니다.701* **`false`**: Claude는 오류로 실패합니다. OAuth 콜백 또는 CORS allowlists와 같이 서버가 특정 포트를 사용해야 할 때 사용합니다.

696* **설정되지 않음 (기본값)**: Claude는 서버가 정확한 포트가 필요한지 묻고 답변을 저장합니다.702* **설정되지 않음 (기본값)**: 아래의 한 가지 경우를 제외하고 `true`와 마찬가지로 서버가 다음으로 사용 가능한 포트를 받습니다. Claude Desktop v2.37337.0 이전에는 대신 Claude가 서버에 해당 포트가 정확히 필요한지 묻고, 답변을 `launch.json`에 저장합니다.

697 703 

698Claude가 다른 포트를 선택하면 할당된 포트를 `PORT` 환경 변수를 통해 서버에 전달합니다.704선호하는 포트가 사용 중이고 `autoPort`가 설정되지 않은 경우, 다음 조건이 모두 충족되면 서버는 중지된 상태로 유지됩니다:

705 

706* `npm`, `yarn`, `pnpm` 또는 `bun` 스크립트를 통해 서버를 시작합니다.

707* 선호하는 포트가 해당 스크립트에 하드코딩되어 있거나, Claude가 스크립트를 검사할 수 없습니다.

708* `runtimeArgs`에서 포트를 전달하지 않습니다.

709 

710이 경우 포트를 비우거나, 하드코딩된 값을 제거하거나, 스크립트와 일치하도록 `port`를 변경합니다. 대신 `"autoPort": true`를 설정하는 방법은 `PORT`를 읽는 스크립트에서만 작동합니다.

711 

712할당된 포트를 전달하는 `PORT` 환경 변수에서 서버가 포트를 읽도록 합니다. Claude가 서버를 다른 포트로 옮기면 `runtimeArgs`의 `--port` 또는 `-p` 값도 일치하도록 다시 작성합니다.

699 713 

700<h4 id="examples">714<h4 id="examples">

701 예제715 예제

785 로컬 세션799 로컬 세션

786</h3>800</h3>

787 801 

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

789 803 

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

791 805 

840 854 

841Linux 또는 macOS 원격 머신에는 지원되는 프로세서, SFTP를 지원하는 SSH 서버, `noexec`로 마운트되지 않은 설치 폴더, 작동하는 셸, 네트워크 액세스가 필요합니다. 연결하기 전에, 또는 로그인한 후 연결이 실패할 때 각 요구 사항을 확인하세요:855Linux 또는 macOS 원격 머신에는 지원되는 프로세서, SFTP를 지원하는 SSH 서버, `noexec`로 마운트되지 않은 설치 폴더, 작동하는 셸, 네트워크 액세스가 필요합니다. 연결하기 전에, 또는 로그인한 후 연결이 실패할 때 각 요구 사항을 확인하세요:

842 856 

843* **시스템**: x86\_64 또는 arm64 프로세서. 머신은 Claude Code의 [시스템 요구 사항](/docs/ko/setup#system-requirements)도 충족해야 합니다.857* **시스템**: x86\_64 또는 arm64 프로세서. 머신은 Claude Code의 [시스템 요구 사항](/docs/ko/setup#system-requirements)도 충족해야 합니다. Linux에서 Claude Code에는 glibc 2.17 이상 또는 musl이 필요합니다. 머신에 어느 것이 있는지 확인하려면 해당 머신에서 `ldd --version`을 실행합니다. Alpine Linux와 같은 musl 기반 배포판에서는 [Claude Code에 필요한 패키지](/docs/ko/setup#alpine-linux-and-musl-based-distributions)도 설치합니다.

844* **SFTP**: SSH 서버가 SFTP 하위 시스템을 제공해야 하며, 이는 `sshd_config`의 `Subsystem sftp` 줄로 켜집니다. 확인하려면 컴퓨터의 터미널에서 `sftp`로 동일한 호스트와 포트에 연결합니다. 정상적으로 작동하는 서버는 `sftp>` 프롬프트를 표시합니다.858* **SFTP**: SSH 서버가 SFTP 하위 시스템을 제공해야 하며, 이는 `sshd_config`의 `Subsystem sftp` 줄로 켜집니다. 확인하려면 컴퓨터의 터미널에서 `sftp`로 동일한 호스트와 포트에 연결합니다. 정상적으로 작동하는 서버는 `sftp>` 프롬프트를 표시합니다.

845* **연결당 세션 수**: macOS 및 Linux의 Desktop은 하나의 SSH 연결에서 여러 세션을 엽니다. 서버의 `sshd_config`가 `MaxSessions 1`로 설정되어 있다면 OpenSSH의 기본값인 10 등으로 값을 늘립니다.859* **연결당 세션 수**: macOS 및 Linux의 Desktop은 하나의 SSH 연결에서 여러 세션을 엽니다. 서버의 `sshd_config`가 `MaxSessions 1`로 설정되어 있다면 OpenSSH의 기본값인 10 등으로 값을 늘립니다.

846* **설치 폴더**: Desktop은 홈 디렉터리의 `~/.claude/remote/` 아래에 도우미 프로그램과 Claude Code를 설치합니다. 해당 위치에서 이를 실행하므로 이 폴더는 `noexec`로 마운트된 파일 시스템에 있으면 안 됩니다. 연결하는 각 사용자의 홈 디렉터리에 약 1 GB의 디스크 공간을 확보하세요.860* **설치 폴더**: Desktop은 홈 디렉터리의 `~/.claude/remote/` 아래에 도우미 프로그램과 Claude Code를 설치합니다. 해당 위치에서 이를 실행하므로 이 폴더는 `noexec`로 마운트된 파일 시스템에 있으면 안 됩니다. 연결하는 각 사용자의 홈 디렉터리에 약 1 GB의 디스크 공간을 확보하세요. 이 폴더에 담긴 내용은 [원격 머신의 파일 및 프로세스](#files-and-processes-on-the-remote-machine)를 참조하세요.

847* **셸**: 원격 머신에서 계정에 설정된 셸은 Bash, Zsh, `sh`처럼 SSH를 통해 전송된 명령을 실행할 수 있어야 합니다861* **셸**: 원격 머신에서 계정에 설정된 셸은 Bash, Zsh, `sh`처럼 SSH를 통해 전송된 명령을 실행할 수 있어야 합니다

848* **네트워크**: Claude Code는 원격 머신에서 실행되며 네트워크 요청도 그곳에서 보내므로, 머신에는 [Claude Code에 필요한 네트워크 액세스](/docs/ko/network-config#network-access-requirements)가 있어야 합니다. 머신이 Claude Code를 다운로드할 수 없는 경우 Desktop이 컴퓨터에서 다운로드하여 업로드합니다. Claude Code의 다른 요청은 여전히 원격 머신에서 전송됩니다.862* **네트워크**: Claude Code는 원격 머신에서 실행되며 네트워크 요청도 그곳에서 보내므로, 머신에는 [Claude Code에 필요한 네트워크 액세스](/docs/ko/network-config#network-access-requirements)가 있어야 합니다. 머신이 Claude Code를 다운로드할 수 없는 경우 Desktop이 컴퓨터에서 다운로드하여 업로드합니다. Claude Code의 다른 요청은 여전히 원격 머신에서 전송됩니다.

849 863 

878 892 

879**SSH host** 필드에 `devbox`를 입력합니다.893**SSH host** 필드에 `devbox`를 입력합니다.

880 894 

895<h5 id="use-variables-from-your-shell-in-a-proxycommand">

896 `ProxyCommand`에서 셸의 변수 사용

897</h5>

898 

899`ProxyCommand` 또는 `Match exec` 명령에서 직접 정의한 환경 변수를 사용하려면 `~/.zshrc`와 같은 셸 시작 파일에서 해당 변수를 내보낸 다음 Desktop을 종료했다가 다시 엽니다. Desktop은 시작할 때 로그인 셸이 내보내는 값을 읽고, 종료할 때까지 그 값을 유지합니다.

900 

901이 기능을 사용하려면 Claude Desktop v2.37337.0 이상과 `-0`을 허용하는 `env` 명령이 필요합니다. 컴퓨터의 터미널에서 `env -0`을 실행하여 확인할 수 있습니다.

902 

881<h5 id="raise-the-ssh-connection-timeout">903<h5 id="raise-the-ssh-connection-timeout">

882 SSH 연결 타임아웃 늘리기904 SSH 연결 타임아웃 늘리기

883</h5>905</h5>

894 916 

895`ssh`는 호스트에 대해 처음 찾은 값을 사용하므로, 이 항목을 `ConnectTimeout`을 설정하는 `Host *` 항목보다 위에 두세요. 확인하려면 컴퓨터의 터미널에서 `ssh -G devbox`를 실행합니다. 출력에 `connecttimeout 120`이 포함됩니다. 값을 변경한 후에는 Desktop을 종료했다가 다시 엽니다.917`ssh`는 호스트에 대해 처음 찾은 값을 사용하므로, 이 항목을 `ConnectTimeout`을 설정하는 `Host *` 항목보다 위에 두세요. 확인하려면 컴퓨터의 터미널에서 `ssh -G devbox`를 실행합니다. 출력에 `connecttimeout 120`이 포함됩니다. 값을 변경한 후에는 Desktop을 종료했다가 다시 엽니다.

896 918 

919<h5 id="forwarding-settings-that-desktop-leaves-off">

920 Desktop이 끄는 포워딩 설정

921</h5>

922 

923원격 머신에 대한 연결에서 Desktop은 SSH 구성이 `ForwardAgent`, `ForwardX11`, `LocalForward`, `RemoteForward`, `DynamicForward`, `Tunnel`을 켜더라도 이를 끈 상태로 둡니다. [터미널](#run-commands-in-the-terminal) 또는 `!` 명령에서는 Desktop이 이러한 설정을 따르는 별도의 `ssh`를 시작할 수 있으므로, 포워딩 설정이 [일부 경우에만](#limits-while-desktop-is-disconnected) 적용된다고 예상하세요.

924 

925* **원격 머신의 포트에 연결하려면**: [직접 포워딩합니다](#reach-a-port-on-the-remote-machine)

926* **원격 머신에서 자신의 키를 사용하려면**: `git push`용 자격 증명처럼 원격 머신 자체에 자격 증명을 설정합니다

927 

928Desktop이 SSH 에이전트나 포트를 포워딩하지 않도록 하려면 컴퓨터의 터미널에서 `ssh -G devbox`를 실행합니다. 그런 다음 `ssh -G -o HostName=devbox.internal.example.com -l alice devbox`처럼, 출력된 `hostname` 및 `user` 값을 사용하여 Desktop이 실행할 수 있는 방식으로 다시 실행합니다. 두 번째 출력에는 첫 번째 출력에서 건너뛴 `Match` 블록의 설정이 표시될 수 있습니다.

929 

930두 출력에서 `no`가 아닌 값을 가진 `forwardagent` 줄과 `localforward`, `remoteforward`, `dynamicforward`로 시작하는 줄을 찾습니다. 찾으면 SSH 구성에서 해당 설정을 제거합니다. `ProxyCommand`가 `ssh`로 연결하는 호스트에 대해서도 동일하게 수행합니다.

931 

932<h4 id="reach-a-port-on-the-remote-machine">

933 원격 머신의 포트에 연결

934</h4>

935 

936포트 3000의 개발 서버처럼 원격 머신에서 실행되는 서버를 열려면 포트를 직접 포워딩합니다. 컴퓨터의 터미널에서 `-L`과 연결하는 호스트(예: `devbox`)를 지정하여 `ssh`를 실행합니다:

937 

938```bash theme={null}

939ssh -N -L 3000:localhost:3000 devbox

940```

941 

942연결에 **SSH port** 또는 \*\*SSH key (optional)\*\*를 입력했다면 같은 값으로 `-p` 또는 `-i`를 추가합니다. 이 명령을 실행 상태로 두고 컴퓨터의 브라우저에서 `http://localhost:3000`을 열면 원격 머신의 포트 3000에 연결됩니다. `ssh`가 `open failed: administratively prohibited`를 출력하면 머신의 관리자에게 TCP 포워딩을 허용해 달라고 요청하세요. 이는 SSH 서버의 `sshd_config`에 있는 `AllowTcpForwarding`이 제어합니다.

943 

897<h4 id="windows-remote-machines">944<h4 id="windows-remote-machines">

898 Windows 원격 머신945 Windows 원격 머신

899</h4>946</h4>

925Claude Code는 Desktop이 원격 머신에 설치하는 백그라운드 도우미 아래에서 프로세스로 실행되므로, 계속 실행되는 데 SSH 연결이 필요하지 않습니다. 이 섹션의 동작을 사용하려면 Claude Desktop v2.31226.0 이상이 필요합니다.972Claude Code는 Desktop이 원격 머신에 설치하는 백그라운드 도우미 아래에서 프로세스로 실행되므로, 계속 실행되는 데 SSH 연결이 필요하지 않습니다. 이 섹션의 동작을 사용하려면 Claude Desktop v2.31226.0 이상이 필요합니다.

926 973 

927<Warning>974<Warning>

928 Claude 계정으로 Desktop에 로그인하는 경우 작업이 밤새 실행될 것으로 기대하지 마세요. Desktop은 Desktop이 실행 중이고 연결되어 있는 동안에만 작업의 로그인을 갱신하므로, 연결이 끊긴 후 작업의 로그인이 만료될 수 있으며 그러면 작업이 중지됩니다. 연결이 끊길 때 남아 있는 시간은 상황에 따라 다릅니다.975 Claude 계정으로 Desktop에 로그인하는 경우 작업이 밤새 실행될 것으로 기대하지 마세요. Desktop은 Desktop이 실행 중이고 연결되어 있는 동안에만 작업의 로그인을 갱신하므로, 연결이 끊긴 후 작업의 로그인이 만료될 수 있으며 그러면 작업이 중지됩니다. 연결이 끊길 때 남아 있는 시간은 상황에 따라 다르며, 단 몇 분일 수도 있습니다.

929 976 

930 지금까지 수행한 작업은 원격 머신에 남아 있으며, 돌아와서 메시지를 보내 계속할 수 있습니다.977 지금까지 수행한 작업은 원격 머신에 남아 있으며, 돌아와서 메시지를 보내 계속할 수 있습니다.

931 978 

1076 1123 

1077이 필드를 사용하려면 Claude Desktop v1.44121.0 이상이 필요합니다. 조직에서 세션이 사용할 수 있는 폴더를 제한하는 경우 Desktop은 이 필드를 숨기고 워크트리를 프로젝트 내부에 유지합니다.1124이 필드를 사용하려면 Claude Desktop v1.44121.0 이상이 필요합니다. 조직에서 세션이 사용할 수 있는 폴더를 제한하는 경우 Desktop은 이 필드를 숨기고 워크트리를 프로젝트 내부에 유지합니다.

1078 1125 

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

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

1128</h4>

1129 

1130Desktop은 Linux 또는 macOS 원격 머신에 연결하는 각 사용자의 홈 디렉터리에 있는 `~/.claude/remote/` 아래에 도우미 프로그램과 Claude Code를 설치합니다. 도우미는 어떤 네트워크 포트에서도 수신 대기하지 않지만, Claude Code와 Claude Code가 시작하는 MCP 서버 및 개발 서버와 같은 프로그램은 수신 대기할 수 있습니다.

1131 

1132| 폴더 | 내용 |

1133| - | - |

1134| `~/.claude/remote/srv/` | 도우미. 버전마다 하나의 폴더 |

1135| `~/.claude/remote/ccd-cli/` | Claude Code. 버전마다 하나의 파일 |

1136| `~/.claude/remote/run/` | 소켓 및 로그와 같은 도우미의 런타임 파일. 연결하는 컴퓨터마다 하나의 폴더 |

1137| `~/.claude/remote/plugins/` | Desktop이 사용자의 컴퓨터에서 복사하는 플러그인 |

1138| [`~/.claude/uploads/`](/docs/ko/claude-directory#clear-local-data) | 사용자가 메시지에 첨부하는 파일. 세션마다 하나의 폴더 |

1139 

1140한 사용자의 프로세스를 나열하려면 원격 머신에서 해당 사용자로 `pgrep -fl "$HOME/.claude/remote/"`를 실행하거나, `$HOME` 대신 해당 사용자의 홈 디렉터리를 넣어 실행합니다:

1141 

1142* **도우미**: 연결하는 각 컴퓨터에 대해 하나 이상의 `server` 프로세스

1143* **Claude Code**: 도우미가 사용자의 세션을 위해 시작하는 프로세스로, 각각 `2.1.295-…`와 같이 버전 이름을 딴 파일에서 실행됩니다

1144 

1145Desktop은 사용자의 SSH 연결을 통해 `~/.claude/remote/run/` 아래 도우미 폴더에 있는 Unix 소켓 `rpc.sock`으로 도우미에 접근합니다. 소켓의 모드는 600이고 해당 폴더의 모드는 700이므로, root를 제외한 머신의 다른 사용자는 이 소켓에 연결할 수 없습니다.

1146 

1147도우미가 자체적으로 중지되는 경우는 [Desktop 연결이 끊긴 동안의 제한](#limits-while-desktop-is-disconnected)을 참조하세요.

1148 

1149한 사용자에 대해 도우미와 Claude Code를 제거하려면:

1150 

1151<Steps>

1152 <Step title="Desktop 종료">

1153 사용자가 연결하는 각 컴퓨터에서 Desktop을 종료합니다. Desktop은 다음에 연결할 때 두 프로그램을 다시 설치하며, 자동으로 다시 연결할 수 있습니다.

1154 </Step>

1155 

1156 <Step title="프로세스 종료">

1157 원격 머신에 해당 사용자로 로그인한 상태에서 [`pgrep`](#files-and-processes-on-the-remote-machine)이 나열하는 각 프로세스 ID로 `kill`을 실행합니다.

1158 </Step>

1159 

1160 <Step title="폴더 삭제">

1161 `~/.claude/remote/`를 삭제합니다. `~/.claude/` 및 `~/.claude.json`에 있는 Claude Code 자체 파일을 제거하려면 [설정 파일 제거](/docs/ko/setup#remove-configuration-files)를 참조하세요.

1162 </Step>

1163</Steps>

1164 

1165<h5 id="end-one-session’s-process">

1166 한 세션의 프로세스 종료

1167</h5>

1168 

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

1170 

1171워크트리가 있는 세션을 보관하기 전에 [세션으로 병렬 작업](#work-in-parallel-with-sessions)을 참조하세요.

1172 

1173<h5 id="see-who-connected-to-the-remote-machine">

1174 원격 머신에 연결한 사용자 확인

1175</h5>

1176 

1177원격 머신에 누가 연결했는지 확인하려면 해당 머신에서 SSH 서버의 로그를 읽습니다. 로그에서 Desktop의 로그인은 터미널의 로그인과 같은 형태로 표시됩니다. macOS 또는 Linux의 Desktop에서는 세션마다가 아니라 Desktop이 연결할 때마다 항목이 하나씩 기록됩니다.

1178 

1179<h4 id="use-mcp-servers-set-up-on-the-remote-machine">

1180 원격 머신에 설정된 MCP 서버 사용

1181</h4>

1182 

1183SSH 세션에서 `~/.claude.json` 또는 프로젝트의 `.mcp.json`에 있는 [MCP 서버](/docs/ko/mcp)를 사용하려면 원격 머신의 해당 파일에 서버를 설정합니다. Claude Code는 해당 stdio 서버를 원격 머신에서 시작하므로, 이러한 서버가 실행하는 명령을 원격 머신에 설치하세요. `claude_desktop_config.json`의 서버에 대해서는 [Desktop 연결이 끊긴 동안의 제한](#limits-while-desktop-is-disconnected)을 참조하세요.

1184 

1079<h4 id="open-an-ssh-session-from-a-link">1185<h4 id="open-an-ssh-session-from-a-link">

1080 링크에서 SSH 세션 열기1186 링크에서 SSH 세션 열기

1081</h4>1187</h4>

1207* **Cowork**: 어떤 키도 [Cowork](https://claude.com/docs/cowork/overview) 세션이나 Cowork 예약 작업에 적용되지 않습니다1313* **Cowork**: 어떤 키도 [Cowork](https://claude.com/docs/cowork/overview) 세션이나 Cowork 예약 작업에 적용되지 않습니다

1208* **클라우드 세션**: 어떤 키도 [클라우드 세션](#cloud-sessions)의 사용 가능 여부를 변경하지 않습니다. 클라우드 세션을 끄려면 [Admin console controls](#admin-console-controls)의 **Cloud sessions** 설정을 사용합니다.1314* **클라우드 세션**: 어떤 키도 [클라우드 세션](#cloud-sessions)의 사용 가능 여부를 변경하지 않습니다. 클라우드 세션을 끄려면 [Admin console controls](#admin-console-controls)의 **Cloud sessions** 설정을 사용합니다.

1209 1315 

1210예제를 조정할 때는 호스트명과 Desktop 버전을 확인하세요:1316예제를 조정할 때는 호스트명, Desktop 버전, 파일 권한을 확인하세요:

1211 1317 

1212* **호스트명**: `sshHostAllowlist`의 패턴이 `user@`를 제외한 각 `sshConfigs` 항목의 호스트명과 일치하는지 확인합니다. 그렇지 않으면 개발자가 해당 호스트에 연결할 수 없습니다. Desktop이 호스트명을 일치시키는 방식은 [SSH 호스트 연결을 제한하여 사용자가 연결할 수 있는 호스트를 제한합니다](#restrict-which-ssh-hosts-users-can-connect-to)를 참조하세요.1318* **호스트명**: `sshHostAllowlist`의 패턴이 `user@`를 제외한 각 `sshConfigs` 항목의 호스트명과 일치하는지 확인합니다. 그렇지 않으면 개발자가 해당 호스트에 연결할 수 없습니다. Desktop이 호스트명을 일치시키는 방식은 [SSH 호스트 연결을 제한하여 사용자가 연결할 수 있는 호스트를 제한합니다](#restrict-which-ssh-hosts-users-can-connect-to)를 참조하세요.

1213* **버전**: `disableDesktopLocalSessions`를 사용하려면 Claude Desktop v1.37937.0 이상이 필요합니다1319* **버전**: `disableDesktopLocalSessions`를 사용하려면 Claude Desktop v1.37937.0 이상이 필요합니다

1320* **파일 권한**: 컴퓨터에서 각 개발자의 계정이 관리형 설정 파일을 읽을 수 있는지 확인합니다. Desktop은 계정이 읽을 수 없는 파일의 키를 적용하지 않으며, Claude Code도 [해당 키 없이 시작됩니다](/docs/ko/managed-settings#find-entries-claude-code-dropped).

1214 1321 

1215세 키를 하나의 [관리형 소스](/docs/ko/managed-settings#how-claude-code-combines-managed-sources), 즉 제공하는 소스 중 가장 높은 순위의 소스에 넣습니다. [서버 관리형 설정](/docs/ko/server-managed-settings)을 제공하는 경우 각 컴퓨터의 가장 높은 순위의 MDM 정책 또는 관리형 설정 파일에도 세 키의 사본을 유지하세요. Desktop은 실행 시 서버 관리형 설정을 가져오며, 가져오기가 성공할 때까지는 컴퓨터의 사본이 적용됩니다.1322세 키를 하나의 [관리형 소스](/docs/ko/managed-settings#how-claude-code-combines-managed-sources), 즉 제공하는 소스 중 가장 높은 순위의 소스에 넣습니다. [서버 관리형 설정](/docs/ko/server-managed-settings)을 제공하는 경우 각 컴퓨터의 가장 높은 순위의 MDM 정책 또는 관리형 설정 파일에도 세 키의 사본을 유지하세요. Desktop은 실행 시 서버 관리형 설정을 가져오며, 가져오기가 성공할 때까지는 컴퓨터의 사본이 적용됩니다.

1216 1323 

1558 1665 

1559MCP 서버 토글이 응답하지 않거나 Windows에서 서버가 연결되지 않으면 서버가 설정에 올바르게 구성되었는지 확인하고, 앱을 다시 시작하고, Task Manager에서 서버 프로세스가 실행 중인지 확인하고, 연결 오류에 대한 서버 로그를 검토합니다.1666MCP 서버 토글이 응답하지 않거나 Windows에서 서버가 연결되지 않으면 서버가 설정에 올바르게 구성되었는지 확인하고, 앱을 다시 시작하고, Task Manager에서 서버 프로세스가 실행 중인지 확인하고, 연결 오류에 대한 서버 로그를 검토합니다.

1560 1667 

1668<h3 id="ssh-connection-fails-after-you-log-in">

1669 로그인 후 SSH 연결 실패

1670</h3>

1671 

1672이 표에서 카드의 제목 또는 오류 메시지 끝에 있는 코드를 찾은 다음 마지막 열의 안내를 따릅니다. 메시지를 보려면 실패 카드에서 **View details**를 선택합니다.

1673 

1674| 카드의 제목 | 코드 | 조치 |

1675| - | - | - |

1676| `<host>'s SSH server has SFTP turned off` | `[SFTP_UNAVAILABLE]` | [원격 머신 요구 사항](#remote-machine-requirements-for-ssh-sessions)에 설명된 대로 서버의 `sshd_config`에서 SFTP를 켭니다 |

1677| `SFTP doesn't start on <host>` | `[SFTP_NOT_STARTED]` | 컴퓨터의 터미널에서 `sftp`로 동일한 호스트에 연결하여 무엇이 시작을 막는지 확인한 다음, Desktop 메시지에 언급된 설정과 파일을 확인합니다 |

1678| `<host> allows too few SSH sessions per connection` | `[SESSION_LIMIT]` | 서버의 `sshd_config`에서 `MaxSessions`를 높입니다. 예를 들어 OpenSSH 기본값인 10으로 설정합니다 |

1679| `<host> is out of disk space` | `[ENOSPC]` 또는 `[EDQUOT]` | 원격 머신의 홈 디렉터리 또는 `/tmp`에서 공간 또는 할당량을 확보합니다 |

1680| `This computer is out of disk space` | `Couldn't prepare the deploy locally`로 시작하는 메시지의 `[ENOSPC]` 또는 `[EDQUOT]` | 컴퓨터의 공간을 확보합니다 |

1681| `Claude Code won't start on <host>` | `[CLI_UNRESPONSIVE]` | 1분 정도 기다린 후 다시 시도합니다. 계속 실패하면 원격 머신에서 메시지에 언급된 명령을 실행하여 Claude Code가 그곳에서 응답하는지 확인합니다. |

1682 

1683그 외의 메시지는 [원격 머신 요구 사항](#remote-machine-requirements-for-ssh-sessions)을 확인합니다.

1684 

1561<h3 id="app-won’t-quit">1685<h3 id="app-won’t-quit">

1562 앱이 종료되지 않음1686 앱이 종료되지 않음

1563</h3>1687</h3>

268| `CLAUDE_CODE_DISABLE_FAST_MODE` | `1`로 설정하면 [빠른 모드](/docs/ko/fast-mode)를 비활성화합니다 |268| `CLAUDE_CODE_DISABLE_FAST_MODE` | `1`로 설정하면 [빠른 모드](/docs/ko/fast-mode)를 비활성화합니다 |

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

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

271| `CLAUDE_CODE_DISABLE_FILE_MENTIONS` | `1`로 설정하면 Claude Code가 파일과 디렉터리의 [`@` 멘션](/docs/ko/common-workflows#reference-files-and-directories)을 확장하지 않습니다. 대신 Claude는 멘션된 경로와 함께 파일 도구로 읽으라는 안내를 받습니다. [프로젝트 및 로컬 설정](/docs/ko/settings-reference#variables-claude-code-ignores-in-env)에서는 무시됩니다. Claude Code v2.1.299 이상이 필요합니다 |

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

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

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

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

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

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

332| `CLAUDE_CODE_IDLE_COMPACT_MIN_TOKENS` | [유휴 압축](/docs/ko/settings-reference#idlecompaction)이 대화에 적용되는 컨텍스트 크기(토큰)입니다(기본값: `200000`). 양의 정수를 허용하며 그 외의 값은 무시됩니다. `100000` 미만의 값은 최저 임계값인 `100000`으로 올려집니다. 유휴 압축은 조건을 충족하는 대화에 대해 기본적으로 켜져 있습니다. 끄려면 `idleCompaction`을 `false`로 설정합니다. Claude Code v2.1.290 이상이 필요합니다 |

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

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

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

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

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

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

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

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

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

364| `CLAUDE_CODE_OVERLOADED_RETRY_MAX_DELAY_MS` | API가 `529` 과부하 오류로 거부한 요청의 [자동 재시도](/docs/ko/errors#tune-retry-behavior) 사이 지수 백오프의 상한(밀리초)으로, 기본값 32000을 대신합니다. API 용량이 가득 찼을 때 이후 재시도 간격이 계속 벌어지도록 하려면 값을 높이세요. 32000에서 64000 사이의 밀리초 정수를 숫자만으로 지정하며, Claude Code는 다른 값을 설정되지 않은 것으로 간주합니다. `CLAUDE_CODE_RETRY_WATCHDOG`가 `1`로 설정된 경우나 거부된 요청이 [빠른 모드](/docs/ko/fast-mode#handle-rate-limits)로 전송된 경우에는 효과가 없습니다. Claude Code v2.1.296 이상이 필요합니다 |

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

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

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

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

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

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

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

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

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

386| `CLAUDE_CODE_RETRY_WATCHDOG_MAX_WAIT_MS` | `CLAUDE_CODE_RETRY_WATCHDOG`가 설정된 경우 각 API 요청이 `429` 및 `529` 오류를 기다리며 보내는 최대 시간(밀리초)입니다. 이 시간이 지나면 다음 해당 오류에서 요청이 종료됩니다. 30분에 해당하는 `1800000`처럼 숫자로만 된 양의 정수를 지정합니다. 설정하지 않으면 대기 시간에 제한이 없습니다. Claude Code v2.1.295 이상이 필요합니다 |389| `CLAUDE_CODE_RETRY_WATCHDOG_MAX_WAIT_MS` | `CLAUDE_CODE_RETRY_WATCHDOG`가 설정된 경우 각 API 요청이 `429` 및 `529` 오류를 기다리며 보내는 최대 시간(밀리초)입니다. 이 시간이 지나면 다음 해당 오류에서 요청이 종료됩니다. 30분에 해당하는 `1800000`처럼 숫자로만 된 양의 정수를 지정합니다. 설정하지 않으면 대기 시간에 제한이 없습니다. Claude Code v2.1.295 이상이 필요합니다 |

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

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

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

443| `CLAUDE_CODE_YOU_SHOULD_KNOW_DEBUG` | `1`로 설정하면 이 세션에서 [You should know mod](/docs/ko/interactive-mode#you-should-know-suggestions)가 수행한 마지막 세 번의 확인 각각에 대한 줄을 프롬프트 위에 표시합니다. 메모가 나타나지 않을 때 mod가 확인을 수행하고 있는지 확인하는 데 사용합니다. Claude Code v2.1.287 이상이 필요합니다 |

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

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

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

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

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

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

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

456| `DISABLE_COMPACT` | 자동 압축과 수동 `/compact` 명령을 모두 포함한 모든 압축을 비활성화하려면 `1`로 설정합니다 |460| `DISABLE_COMPACT` | 자동 압축과 수동 `/compact` 명령을 모두 포함한 모든 압축을 비활성화하려면 `1`로 설정합니다 |

457| `DISABLE_COST_WARNINGS` | 비용 경고 메시지를 비활성화하려면 `1`로 설정합니다 |461| `DISABLE_COST_WARNINGS` | 비용 경고 메시지를 비활성화하려면 `1`로 설정합니다 |

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

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

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

480| `ENABLE_PROMPT_CACHING_1H_BEDROCK` | deprecated. 대신 `ENABLE_PROMPT_CACHING_1H`를 사용하세요 |484| `ENABLE_PROMPT_CACHING_1H_BEDROCK` | deprecated. 대신 `ENABLE_PROMPT_CACHING_1H`를 사용하세요 |

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

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

483| `FORCE_AUTOUPDATE_PLUGINS` | 메인 자동 업데이터가 `DISABLE_AUTOUPDATER`로 비활성화된 경우에도 플러그인 자동 업데이트를 강제하려면 `1`로 설정합니다 |487| `FORCE_AUTOUPDATE_PLUGINS` | 메인 자동 업데이터가 `DISABLE_AUTOUPDATER`로 비활성화된 경우에도 플러그인 자동 업데이트를 강제하려면 `1`로 설정합니다 |

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

593* [`claude import` 또는 `/import` 명령](/docs/ko/cli-reference#cli-commands) 실행597* [`claude import` 또는 `/import` 명령](/docs/ko/cli-reference#cli-commands) 실행

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

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

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

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

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

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

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

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

602* Claude Code가 [API가 거부할 입력 스키마를 가진 MCP 도구를 제외](/docs/ko/mcp#tools-with-invalid-input-schemas)하도록 하기. Claude Code는 해당 스키마를 그대로 전송하며, 이를 포함한 요청은 [도구를 위치로 지정하는 400 오류](/docs/ko/errors#tool-input-schema-is-invalid)와 함께 실패합니다607* Claude Code가 [API가 거부할 입력 스키마를 가진 MCP 도구를 제외](/docs/ko/mcp#tools-with-invalid-input-schemas)하도록 하기. Claude Code는 해당 스키마를 그대로 전송하며, 이를 포함한 요청은 [도구를 위치로 지정하는 400 오류](/docs/ko/errors#tool-input-schema-is-invalid)와 함께 실패합니다

608* 1시간 프롬프트 캐시가 만료되기 직전에 Claude Code가 [터미널 세션이 유휴 상태인 동안 긴 대화를 압축](/docs/ko/settings-reference#idlecompaction)하도록 하기

603 609 

604<h3 id="first-session-after-an-install-or-upgrade">610<h3 id="first-session-after-an-install-or-upgrade">

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

134| `proxy refused the connection` | [네트워크](#the-proxy-refused-the-connection) |134| `proxy refused the connection` | [네트워크](#the-proxy-refused-the-connection) |

135| `403` with `GitHub GraphQL is not available from Claude Code sessions` in a cloud session | [GitHub proxy](/docs/ko/cloud-environments#github-proxy) |135| `403` with `GitHub GraphQL is not available from Claude Code sessions` in a cloud session | [GitHub proxy](/docs/ko/cloud-environments#github-proxy) |

136| `The cloud environments service returned an empty response` / `The cloud environments service returned a response in an unexpected format` | [네트워크](#the-cloud-environments-service-returned-an-empty-or-unexpected-response) |136| `The cloud environments service returned an empty response` / `The cloud environments service returned a response in an unexpected format` | [네트워크](#the-cloud-environments-service-returned-an-empty-or-unexpected-response) |

137| `Failed to fetch session from Sessions API: Failed to fetch session logs` | [네트워크](#failed-to-fetch-session-from-sessions-api) |

137| `Couldn't reconnect to your Remote Control session` | [네트워크](#couldnt-reconnect-to-your-remote-control-session) |138| `Couldn't reconnect to your Remote Control session` | [네트워크](#couldnt-reconnect-to-your-remote-control-session) |

138| `N sessions ended while this machine was offline — the environment was cleaned up on the server and can't be resumed.` | [네트워크](#sessions-ended-while-this-machine-was-offline) |139| `N sessions ended while this machine was offline — the environment was cleaned up on the server and can't be resumed.` | [네트워크](#sessions-ended-while-this-machine-was-offline) |

139| `Couldn't share the transcript.` | [네트워크](#couldnt-share-the-transcript) |140| `Couldn't share the transcript.` | [네트워크](#couldnt-share-the-transcript) |

153| `Request too large for the API's 32MB request limit` | [요청 오류](#request-too-large) |154| `Request too large for the API's 32MB request limit` | [요청 오류](#request-too-large) |

154| `Image was too large` | [요청 오류](#image-was-too-large) |155| `Image was too large` | [요청 오류](#image-was-too-large) |

155| `Unable to resize image` | [요청 오류](#unable-to-resize-image) |156| `Unable to resize image` | [요청 오류](#unable-to-resize-image) |

157| `Request rejected as unprocessable by the model` | [요청 오류](#request-rejected-as-unprocessable-by-the-model) |

156| `PDF too large` / `PDF is password protected` / `pdftoppm is not installed` | [요청 오류](#pdf-errors) |158| `PDF too large` / `PDF is password protected` / `pdftoppm is not installed` | [요청 오류](#pdf-errors) |

157| `Extra inputs are not permitted` | [요청 오류](#extra-inputs-are-not-permitted) |159| `Extra inputs are not permitted` | [요청 오류](#extra-inputs-are-not-permitted) |

158| `API Error: 400 ... tools.N.custom.input_schema: JSON schema is invalid` / `Property keys should match pattern` | [요청 오류](#tool-input-schema-is-invalid) |160| `API Error: 400 ... tools.N.custom.input_schema: JSON schema is invalid` / `Property keys should match pattern` | [요청 오류](#tool-input-schema-is-invalid) |

161| `Tool "mcp__<server>__<tool>" is not sent to Claude: its name has <N> characters and the API accepts at most 128` | [요청 오류](#mcp-tool-name-over-128-characters) |

162| `tools.N.custom.name: String should have at most 128 characters` | [요청 오류](#mcp-tool-name-over-128-characters) |

159| `tool_use.name: String should have at most 200 characters` | [요청 오류](#tool-use-name-over-200-characters) |163| `tool_use.name: String should have at most 200 characters` | [요청 오류](#tool-use-name-over-200-characters) |

160| `There's an issue with the selected model` | [요청 오류](#theres-an-issue-with-the-selected-model) |164| `There's an issue with the selected model` | [요청 오류](#theres-an-issue-with-the-selected-model) |

161| `Model ... is not a recognized model id` | [요청 오류](#model-is-not-a-recognized-model-id) |165| `Model ... is not a recognized model id` | [요청 오류](#model-is-not-a-recognized-model-id) |

198| `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) |202| `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) |

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

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

201| `Couldn't verify your organization's policy for cloud sessions` | [명령줄 오류](#cloud-sessions-are-disabled-by-your-organizations-policy) |205| `Cloud sessions use your claude.ai login`, 자격 증명을 명시하는 정책 거부 메시지의 끝에 표시됨 | [명령줄 오류](#cloud-sessions-use-your-claude-ai-login) |

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

207| `Cloud sessions aren't available:` 뒤에 조직 정책을 불러올 수 없는 이유가 표시됨 | [명령줄 오류](#couldnt-verify-your-organizations-policy-for-cloud-sessions) |

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

209| `Nothing was stashed: "<path>" is now a folder in place of a tracked file or link` / `are now folders in place of tracked files or links` | [명령줄 오류](#nothing-was-stashed-because-a-folder-replaced-a-tracked-file) |

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

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

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

259| `Output styles are saved to local settings (.claude/settings.local.json), which this session doesn't load` | [명령줄 오류](#output-styles-are-saved-to-local-settings-which-this-session-doesnt-load) |266| `Output styles are saved to local settings (.claude/settings.local.json), which this session doesn't load` | [명령줄 오류](#output-styles-are-saved-to-local-settings-which-this-session-doesnt-load) |

260| `/recap only runs when you ask for it yourself in this session` | [명령줄 오류](#recap-only-runs-when-you-ask-for-it-yourself) |267| `/recap only runs when you ask for it yourself in this session` | [명령줄 오류](#recap-only-runs-when-you-ask-for-it-yourself) |

261| `` `plugin eval` is currently in early access `` / `` `plugin eval` is currently unavailable `` | [플러그인 오류](#plugin-eval-is-currently-in-early-access) |268| `` `plugin eval` is currently in early access `` / `` `plugin eval` is currently unavailable `` | [플러그인 오류](#plugin-eval-is-currently-in-early-access) |

269| `cannot be evaluated where sessions load it` | [eval로 플러그인 테스트](/docs/ko/plugin-evals#cannot-be-evaluated-where-sessions-load-it) |

262| `Marketplace "<name>" is registered from an untrusted source` | [플러그인 오류](#marketplace-is-registered-from-an-untrusted-source) |270| `Marketplace "<name>" is registered from an untrusted source` | [플러그인 오류](#marketplace-is-registered-from-an-untrusted-source) |

263| `Claude Code refuses the marketplace name "<name>"` | [플러그인 오류](#claude-code-refuses-the-marketplace-name) |271| `Claude Code refuses the marketplace name "<name>"` | [플러그인 오류](#claude-code-refuses-the-marketplace-name) |

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

358| `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) |366| `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) |

359| `Claude Code exited after an unrecoverable interface error (...)` | [구성 경고](#exited-after-an-unrecoverable-interface-error) |367| `Claude Code exited after an unrecoverable interface error (...)` | [구성 경고](#exited-after-an-unrecoverable-interface-error) |

360| `Agent descriptions are over the 15.0k-token limit` | [구성 경고](#agent-descriptions-are-over-the-15000-token-limit) |368| `Agent descriptions are over the 15.0k-token limit` | [구성 경고](#agent-descriptions-are-over-the-15000-token-limit) |

369| `hook needs quotes around a path with a space` | [구성 경고](#hook-needs-quotes-around-a-path-with-a-space) |

361| `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) |370| `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) |

371| `N skill or command names refused: run with --debug to see which ([names]), rename, then restart` | [구성 경고](#skill-or-command-name-refused) |

362| `Ignoring N permissions.allow entries from ... this workspace has not been trusted` | [구성 경고](#workspace-has-not-been-trusted) |372| `Ignoring N permissions.allow entries from ... this workspace has not been trusted` | [구성 경고](#workspace-has-not-been-trusted) |

363| `is a network path, which cannot be added as a working directory` | [구성 경고](#working-directory-is-a-network-path) |373| `is a network path, which cannot be added as a working directory` | [구성 경고](#working-directory-is-a-network-path) |

364| `Remote managed settings failed to load (<cause>)` | [구성 경고](#remote-managed-settings-failed-to-load) |374| `Remote managed settings failed to load (<cause>)` | [구성 경고](#remote-managed-settings-failed-to-load) |

447| [`CLAUDE_CODE_RETRY_WATCHDOG`](/docs/ko/env-vars) | 설정 안 됨 | CI 작업과 같은 무인 세션에서 `1`로 설정하면 `CLAUDE_CODE_MAX_RETRIES`회 시도 후 실패하는 대신 `429` 및 `529` 용량 오류를 무기한 재시도합니다. 표준 속도 요청이 지출 한도나 소진된 사용량 크레딧을 보고하는 `429`를 받으면, 일정에 따라 재설정되는 [게이트웨이 지출 한도](#spend-limit-reached)에서 온 것이라도 Claude Code는 즉시 실패합니다. v2.1.239 이전에는 워치독이 이를 무기한 재시도했습니다. 빠른 모드 요청에 대해서는 [속도 제한 처리](/docs/ko/fast-mode#handle-rate-limits)를 참조하세요. v2.1.199 이상에서는 서버 오류, 시간 초과, 끊어진 연결 등 다른 일시적인 오류의 기본 재시도 횟수도 약 3시간의 백오프에 해당하는 300으로 높이고, `CLAUDE_CODE_MAX_RETRIES`를 명시적으로 설정한 경우 15의 상한을 제거합니다. |457| [`CLAUDE_CODE_RETRY_WATCHDOG`](/docs/ko/env-vars) | 설정 안 됨 | CI 작업과 같은 무인 세션에서 `1`로 설정하면 `CLAUDE_CODE_MAX_RETRIES`회 시도 후 실패하는 대신 `429` 및 `529` 용량 오류를 무기한 재시도합니다. 표준 속도 요청이 지출 한도나 소진된 사용량 크레딧을 보고하는 `429`를 받으면, 일정에 따라 재설정되는 [게이트웨이 지출 한도](#spend-limit-reached)에서 온 것이라도 Claude Code는 즉시 실패합니다. v2.1.239 이전에는 워치독이 이를 무기한 재시도했습니다. 빠른 모드 요청에 대해서는 [속도 제한 처리](/docs/ko/fast-mode#handle-rate-limits)를 참조하세요. v2.1.199 이상에서는 서버 오류, 시간 초과, 끊어진 연결 등 다른 일시적인 오류의 기본 재시도 횟수도 약 3시간의 백오프에 해당하는 300으로 높이고, `CLAUDE_CODE_MAX_RETRIES`를 명시적으로 설정한 경우 15의 상한을 제거합니다. |

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

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

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

450| [`API_TIMEOUT_MS`](/docs/ko/env-vars) | 600000 | 요청당 타임아웃(밀리초)입니다. 느린 네트워크나 프록시의 경우 값을 높이세요. [No response from API](#no-response-from-api)에 설명된 대로, Claude Code가 응답 헤더를 기다리는 시간의 상한으로도 사용됩니다. |461| [`API_TIMEOUT_MS`](/docs/ko/env-vars) | 600000 | 요청당 타임아웃(밀리초)입니다. 느린 네트워크나 프록시의 경우 값을 높이세요. [No response from API](#no-response-from-api)에 설명된 대로, Claude Code가 응답 헤더를 기다리는 시간의 상한으로도 사용됩니다. |

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

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

2097 2108 

2098v2.1.236 이전에는 Claude Code가 이러한 메시지 대신 원시 JavaScript TypeError를 표시했습니다.2109v2.1.236 이전에는 Claude Code가 이러한 메시지 대신 원시 JavaScript TypeError를 표시했습니다.

2099 2110 

2111<h3 id="failed-to-fetch-session-from-sessions-api">

2112 Failed to fetch session from Sessions API

2113</h3>

2114 

2115이 메시지는 Claude Code가 [터미널로 가져오도록 요청한 클라우드 세션](/docs/ko/claude-code-on-the-web#from-cloud-to-terminal)을 찾았지만 Anthropic 서버에서 해당 세션의 대화 기록을 읽을 수 없어 세션을 열지 않았음을 의미합니다:

2116 

2117```text theme={null}

2118Failed to fetch session from Sessions API: Failed to fetch session logs

2119```