Documentation — Spybara

admin-setup.md +6 −6

Details

15</Note>15</Note>

16 16

17| 결정 | 선택 항목 | 참조 |17| 결정 | 선택 항목 | 참조 |

18| :------------------------------------------------------- | :--------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------- |18| :------------------------------------------------------- | :--------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

19| [API 제공자 선택](#choose-your-api-provider) | Claude Code가 인증하는 위치 및 청구 방식 | [Authentication](/ko/authentication), [Bedrock](/ko/amazon-bedrock), [Vertex AI](/ko/google-vertex-ai), [Foundry](/ko/microsoft-foundry) |19| [API 제공자 선택](#choose-your-api-provider) | Claude Code가 인증하는 위치 및 청구 방식 | [Authentication](/ko/authentication), [Amazon Bedrock](/ko/amazon-bedrock), [Google Cloud's Agent Platform](/ko/google-vertex-ai), [Microsoft Foundry](/ko/microsoft-foundry) |

33| Claude for Teams / Enterprise | Claude Code와 claude.ai를 실행할 인프라 없이 사용자당 구독 하나로 원하는 경우입니다. 이것이 기본 권장사항입니다. |33| Claude for Teams / Enterprise | Claude Code와 claude.ai를 실행할 인프라 없이 사용자당 구독 하나로 원하는 경우입니다. 이것이 기본 권장사항입니다. |

34| Claude Console | API 우선이거나 종량제 청구를 원하는 경우 |34| Claude Console | API 우선이거나 종량제 청구를 원하는 경우 |

35| Amazon Bedrock | 기존 AWS 규정 준수 제어 및 청구를 상속하려는 경우 |35| Amazon Bedrock | 기존 AWS 규정 준수 제어 및 청구를 상속하려는 경우 |

~~36| Google Vertex AI | 기존 GCP 규정 준수 제어 및 청구를 상속하려는 경우 |~~36| Google Cloud's Agent Platform | 기존 GCP 규정 준수 제어 및 청구를 상속하려는 경우 |

37| Microsoft Foundry | 기존 Azure 규정 준수 제어 및 청구를 상속하려는 경우 |37| Microsoft Foundry | 기존 Azure 규정 준수 제어 및 청구를 상속하려는 경우 |

38 38

39일부 Claude Code 기능에는 claude.ai 계정이 필요합니다. [Claude Code on the web](/ko/claude-code-on-the-web), [Routines](/ko/routines), [Code Review](/ko/code-review), [Remote Control](/ko/remote-control) 및 [Chrome extension](/ko/chrome)은 Console API 키 또는 클라우드 제공자 자격증명만으로는 사용할 수 없습니다. Bedrock, Vertex 또는 Foundry를 통해 배포하는 경우 개발자가 Claude for Teams 또는 Enterprise 시트도 필요한지 계획하세요. 각 기능 페이지에는 해당 플랜 요구사항이 나열되어 있습니다.39일부 Claude Code 기능에는 claude.ai 계정이 필요합니다. [Claude Code on the web](/ko/claude-code-on-the-web), [Routines](/ko/routines), [Code Review](/ko/code-review), [Remote Control](/ko/remote-control) 및 [Chrome extension](/ko/chrome)은 Console API 키 또는 클라우드 제공자 자격증명만으로는 사용할 수 없습니다. Amazon Bedrock, Google Cloud's Agent Platform 또는 Microsoft Foundry를 통해 배포하는 경우 개발자가 Claude for Teams 또는 Enterprise 시트도 필요한지 계획하세요. 각 기능 페이지에는 해당 플랜 요구사항이 나열되어 있습니다.

40 40

41인증, 지역 및 기능 패리티를 다루는 전체 제공자 비교는 [enterprise deployment overview](/ko/third-party-integrations)를 참조하세요. 각 제공자의 인증 설정은 [Authentication](/ko/authentication)에 있습니다.41인증, 지역 및 기능 패리티를 다루는 전체 제공자 비교는 [enterprise deployment overview](/ko/third-party-integrations)를 참조하세요. 각 제공자의 인증 설정은 [Authentication](/ko/authentication)에 있습니다.

42 42

57 57

58구성된 [`policyHelper`](/ko/settings#compute-managed-settings-with-a-policy-helper)는 네 가지 소스 모두를 선점합니다. 해당 출력이 실행을 위한 유일한 관리 구성이 됩니다. [설정 우선순위](/ko/settings#settings-precedence)를 참조하세요.58구성된 [`policyHelper`](/ko/settings#compute-managed-settings-with-a-policy-helper)는 네 가지 소스 모두를 선점합니다. 해당 출력이 실행을 위한 유일한 관리 구성이 됩니다. [설정 우선순위](/ko/settings#settings-precedence)를 참조하세요.

59 59

60Server-managed 설정은 인증 시 기기에 도달하고 활성 세션 중에 매시간 새로 고쳐지며 엔드포인트 인프라가 필요하지 않습니다. claude.ai 관리자 콘솔을 통한 전달에는 Claude for Teams 또는 Enterprise 플랜이 필요합니다. Bedrock, Vertex AI 또는 Foundry의 배포는 [Claude apps gateway](/ko/claude-apps-gateway)를 실행하여 동일한 원격 전달을 받을 수 있거나, 대신 파일 기반 또는 OS 수준 메커니즘 중 하나를 사용할 수 있습니다.60Server-managed 설정은 인증 시 기기에 도달하고 활성 세션 중에 매시간 새로 고쳐지며 엔드포인트 인프라가 필요하지 않습니다. claude.ai 관리자 콘솔을 통한 전달에는 Claude for Teams 또는 Enterprise 플랜이 필요합니다. Amazon Bedrock, Google Cloud의 Agent Platform 또는 Microsoft Foundry에 배포된 경우 [Claude apps gateway](/ko/claude-apps-gateway)를 실행하여 동일한 원격 전달을 받을 수 있거나, 대신 파일 기반 또는 OS 수준 메커니즘 중 하나를 사용할 수 있습니다.

61 61

62조직이 제공자를 혼합하는 경우 claude.ai 사용자를 위해 [server-managed settings](/ko/server-managed-settings)를 구성하고 다른 사용자도 관리 정책을 받을 수 있도록 [file-based or plist/registry fallback](/ko/settings#settings-files)을 구성하세요.62조직이 제공자를 혼합하는 경우 claude.ai 사용자를 위해 [server-managed settings](/ko/server-managed-settings)를 구성하고 다른 사용자도 관리 정책을 받을 수 있도록 [file-based or plist/registry fallback](/ko/settings#settings-files)을 구성하세요.

63 63

153* [Server-managed settings](/ko/server-managed-settings): Claude 관리자 콘솔에서 관리 정책 전달153* [Server-managed settings](/ko/server-managed-settings): Claude 관리자 콘솔에서 관리 정책 전달

154* [Settings reference](/ko/settings): 모든 설정 키, 파일 위치 및 우선순위 규칙154* [Settings reference](/ko/settings): 모든 설정 키, 파일 위치 및 우선순위 규칙

155* [Monorepos and large repos](/ko/large-codebases): 모노레포에 배포하는 조직을 위한 디렉터리별 구성 패턴155* [Monorepos and large repos](/ko/large-codebases): 모노레포에 배포하는 조직을 위한 디렉터리별 구성 패턴

156* [Amazon Bedrock](/ko/amazon-bedrock), [Google Vertex AI](/ko/google-vertex-ai), [Microsoft Foundry](/ko/microsoft-foundry): 제공자별 배포156* [Amazon Bedrock](/ko/amazon-bedrock), [Google Cloud's Agent Platform](/ko/google-vertex-ai), [Microsoft Foundry](/ko/microsoft-foundry): 제공자별 배포

157* [Claude Enterprise Administrator Guide](https://claude.com/resources/tutorials/claude-enterprise-administrator-guide): SSO, SCIM, 시트 관리 및 롤아웃 플레이북157* [Claude Enterprise Administrator Guide](https://claude.com/resources/tutorials/claude-enterprise-administrator-guide): SSO, SCIM, 시트 관리 및 롤아웃 플레이북

advisor.md +2 −2

Details

9{/* plan-availability: feature=advisor providers=anthropic */}9{/* plan-availability: feature=advisor providers=anthropic */}

10 10

11<Note>11<Note>

12 조언자 도구는 실험적이며 Anthropic API를 사용하는 Claude Code v2.1.98 이상이 필요합니다. Amazon Bedrock, Google Vertex AI 또는 Microsoft Foundry에서는 사용할 수 없습니다. 동작, 가격 책정 및 가용성은 변경될 수 있습니다.12 조언자 도구는 실험적이며 Anthropic API를 사용하는 Claude Code v2.1.98 이상이 필요합니다. Amazon Bedrock, Google Cloud의 Agent Platform 또는 Microsoft Foundry에서는 사용할 수 없습니다. 동작, 가격 책정 및 가용성은 변경될 수 있습니다.

13</Note>13</Note>

14 14

15조언자 도구를 사용하면 Claude가 작업 중 핵심 순간(예: 접근 방식을 확정하기 전, 반복되는 오류에 막혔을 때, 작업 완료를 선언하기 전)에 일반적으로 더 강력한 두 번째 모델을 참고할 수 있습니다. 조언자는 모든 도구 호출 및 결과를 포함한 전체 대화를 받고 Claude가 계속하기 전에 적용할 지침을 반환합니다.15조언자 도구를 사용하면 Claude가 작업 중 핵심 순간(예: 접근 방식을 확정하기 전, 반복되는 오류에 막혔을 때, 작업 완료를 선언하기 전)에 일반적으로 더 강력한 두 번째 모델을 참고할 수 있습니다. 조언자는 모든 도구 호출 및 결과를 포함한 전체 대화를 받고 Claude가 계속하기 전에 적용할 지침을 반환합니다.

162조언자 도구는 다음 모두를 요구합니다:162조언자 도구는 다음 모두를 요구합니다:

163 163

164* **Claude Code v2.1.98 이상**: `claude update`를 실행하여 업그레이드하세요.164* **Claude Code v2.1.98 이상**: `claude update`를 실행하여 업그레이드하세요.

165* **Anthropic API만**: 조언자는 서버 실행 도구입니다. Amazon Bedrock, Google Vertex AI 또는 Microsoft Foundry에서는 사용할 수 없습니다. [LLM 게이트웨이](/ko/llm-gateway)를 통해 `ANTHROPIC_BASE_URL`로 구성된 경우 가용성은 게이트웨이가 요청을 Anthropic API로 그대로 전달하는지 여부에 따라 달라집니다.165* **Anthropic API만**: 조언자는 서버 실행 도구입니다. Amazon Bedrock, Google Cloud의 Agent Platform 또는 Microsoft Foundry에서는 사용할 수 없습니다. `ANTHROPIC_BASE_URL`로 구성된 [LLM 게이트웨이](/ko/llm-gateway)를 통해 가용성은 게이트웨이가 요청을 Anthropic API로 그대로 전달하는지 여부에 따라 달라집니다.

166* **지원되는 주 모델**: Opus 4.6 이상, Sonnet 4.6 이상 또는 Haiku 4.5. {/* min-version: 2.1.170 */}Fable 5도 Claude Code v2.1.170 이상에서 적합합니다.166* **지원되는 주 모델**: Opus 4.6 이상, Sonnet 4.6 이상 또는 Haiku 4.5. {/* min-version: 2.1.170 */}Fable 5도 Claude Code v2.1.170 이상에서 적합합니다.

167 167

168<h2 id="turn-the-advisor-off">168<h2 id="turn-the-advisor-off">

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

Details

202 202

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

204 204

205[스트리밍 입력](/ko/agent-sdk/streaming-vs-single-mode)을 사용하면 턴이 최대 턴 제한에서 끝날 때 실행 중인 턴 중에 전송하는 메시지는 해당 턴이 끝날 때 대기열에 남아 있으며, 자신의 최대 턴 제한이 있는 자신의 턴을 시작합니다. v2.1.205 이전에는 턴의 최종 반복에 도착한 메시지가 끝나는 턴으로 소비되어 모델에 도달하지 않고 손실될 수 있었습니다.

206

205<h3 id="effort-level">207<h3 id="effort-level">

206 노력 수준208 노력 수준

207</h3>209</h3>

239| `"auto"`(TypeScript만) | 모델 분류기를 사용하여 각 도구 호출을 승인하거나 거부합니다. 가용성 및 동작은 [자동 모드](/ko/permission-modes#eliminate-prompts-with-auto-mode)를 참조하세요 |241| `"auto"` | 모델 분류기를 사용하여 각 도구 호출을 승인하거나 거부합니다. 가용성 및 동작은 [자동 모드](/ko/permission-modes#eliminate-prompts-with-auto-mode)를 참조하세요 |

240| `"bypassPermissions"` | 명시적 [`ask` 규칙](/ko/settings#permission-settings)이 일치하지 않는 한 요청하지 않고 모든 허용된 도구를 실행합니다; 권한이 평가되는 방식은 [권한이 평가되는 방식](/ko/agent-sdk/permissions#how-permissions-are-evaluated)을 참조하여 ask 규칙이 우선순위 순서에서 어디에 있는지 확인하세요. Unix에서 루트로 실행할 때는 사용할 수 없습니다. 에이전트의 조치가 관심 있는 시스템에 영향을 미칠 수 없는 격리된 환경에서만 사용합니다 |242| `"bypassPermissions"` | 명시적 [`ask` 규칙](/ko/settings#permission-settings)이 일치하지 않는 한 요청하지 않고 모든 허용된 도구를 실행합니다; 권한이 평가되는 방식은 [권한이 평가되는 방식](/ko/agent-sdk/permissions#how-permissions-are-evaluated)을 참조하여 ask 규칙이 우선순위 순서에서 어디에 있는지 확인하세요. Unix에서 루트로 실행할 때는 사용할 수 없습니다. 에이전트의 조치가 관심 있는 시스템에 영향을 미칠 수 없는 격리된 환경에서만 사용합니다 |

241 243

242대화형 애플리케이션의 경우 `"default"`를 도구 승인 콜백과 함께 사용하여 승인 프롬프트를 표시합니다. 개발 머신의 자율 에이전트의 경우 `"acceptEdits"`는 파일 편집 및 일반적인 파일시스템 명령(`mkdir`, `touch`, `mv`, `cp` 등)을 자동 승인하면서 다른 `Bash` 명령을 허용 규칙 뒤에 유지합니다. CI, 컨테이너 또는 기타 격리된 환경에 대해 `"bypassPermissions"`를 예약합니다. 전체 세부 정보는 [권한](/ko/agent-sdk/permissions)을 참조하세요.244대화형 애플리케이션의 경우 `"default"`를 도구 승인 콜백과 함께 사용하여 승인 프롬프트를 표시합니다. 개발 머신의 자율 에이전트의 경우 `"acceptEdits"`는 파일 편집 및 일반적인 파일시스템 명령(`mkdir`, `touch`, `mv`, `cp` 등)을 자동 승인하면서 다른 `Bash` 명령을 허용 규칙 뒤에 유지합니다. CI, 컨테이너 또는 기타 격리된 환경에 대해 `"bypassPermissions"`를 예약합니다. 전체 세부 정보는 [권한](/ko/agent-sdk/permissions)을 참조하세요.

260SDK에서 각 구성 요소가 컨텍스트에 어떻게 영향을 미치는지는 다음과 같습니다:262SDK에서 각 구성 요소가 컨텍스트에 어떻게 영향을 미치는지는 다음과 같습니다:

261 263

262| 소스 | 로드 시기 | 영향 |264| 소스 | 로드 시기 | 영향 |

263| :--------------- | :---------------------------------------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |265| :--------------- | :---------------------------------------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

266| **도구 정의** | 모든 요청; MCP 스키마는 기본적으로 지연됨 | 기본 제공 도구 스키마는 모든 요청에서 로드됩니다. [도구 검색](/ko/agent-sdk/mcp#mcp-tool-search)은 기본적으로 MCP 도구 스키마를 지연시키며, Vertex AI 또는 비자사 `ANTHROPIC_BASE_URL`에서 사전 로드로 폴백합니다. 전체 매트릭스는 [도구 검색 구성](/ko/agent-sdk/tool-search#configure-tool-search)을 참조하세요 |268| **도구 정의** | 모든 요청; MCP 스키마는 기본적으로 지연됨 | 기본 제공 도구 스키마는 모든 요청에서 로드됩니다. [도구 검색](/ko/agent-sdk/mcp#mcp-tool-search)은 기본적으로 MCP 도구 스키마를 지연시키며, Google Cloud의 Agent Platform 또는 비자사 `ANTHROPIC_BASE_URL`에서 사전 로드로 폴백합니다. 전체 매트릭스는 [도구 검색 구성](/ko/agent-sdk/tool-search#configure-tool-search)을 참조하세요 |

269 271

305 307

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

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

308* **MCP 서버 비용을 주시합니다.** [MCP 도구 검색](/ko/agent-sdk/mcp#mcp-tool-search)은 기본적으로 MCP 도구 스키마를 지연시키고 필요에 따라 로드합니다. 도구 검색이 꺼져 있거나, Vertex AI에 있거나, 비자사 `ANTHROPIC_BASE_URL` 뒤에 있으면 각 MCP 서버는 모든 도구 스키마를 모든 요청에 추가하므로 많은 도구가 있는 몇 개의 서버는 에이전트가 작업을 수행하기 전에 상당한 컨텍스트를 소비할 수 있습니다.310* **MCP 서버 비용을 주시합니다.** [MCP 도구 검색](/ko/agent-sdk/mcp#mcp-tool-search)은 기본적으로 MCP 도구 스키마를 지연시키고 필요에 따라 로드합니다. 도구 검색이 꺼져 있거나, Google Cloud의 Agent Platform에 있거나, 비자사 `ANTHROPIC_BASE_URL` 뒤에 있으면 각 MCP 서버는 모든 도구 스키마를 모든 요청에 추가하므로 많은 도구가 있는 몇 개의 서버는 에이전트가 작업을 수행하기 전에 상당한 컨텍스트를 소비할 수 있습니다.

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

310 312

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

agent-sdk/cost-tracking.md +2 −2

Details

292 프롬프트 캐시 TTL을 1시간으로 연장292 프롬프트 캐시 TTL을 1시간으로 연장

293</h3>293</h3>

294 294

295SDK에서 작성한 캐시 항목은 API 키로 인증하거나 Amazon Bedrock, Google Cloud Vertex AI 또는 Microsoft Foundry에서 실행할 때 기본적으로 5분 TTL을 사용합니다. 워크로드가 동일한 시스템 프롬프트 및 컨텍스트에 대해 많은 짧은 세션을 실행하고 세션 간에 5분보다 긴 간격이 있는 경우, 캐시는 세션 간에 만료되고 각 새 세션은 전체 입력 가격을 지불합니다.295SDK에서 작성한 캐시 항목은 API 키로 인증하거나 Amazon Bedrock, Google Cloud의 Agent Platform 또는 Microsoft Foundry에서 실행할 때 기본적으로 5분 TTL을 사용합니다. 워크로드가 동일한 시스템 프롬프트 및 컨텍스트에 대해 많은 짧은 세션을 실행하고 세션 간에 5분보다 긴 간격이 있는 경우, 캐시는 세션 간에 만료되고 각 새 세션은 전체 입력 가격을 지불합니다.

296 296

297캐시 쓰기에 1시간 TTL을 요청하려면 [`ENABLE_PROMPT_CACHING_1H`](/ko/env-vars) 환경 변수를 설정하십시오. 셸 또는 컨테이너 환경에서 내보내거나 `options.env`를 통해 전달할 수 있습니다.297캐시 쓰기에 1시간 TTL을 요청하려면 [`ENABLE_PROMPT_CACHING_1H`](/ko/env-vars) 환경 변수를 설정하십시오. 셸 또는 컨테이너 환경에서 내보내거나 `options.env`를 통해 전달할 수 있습니다.

298 298

299다음 예제는 Bedrock에서 실행되는 에이전트에 대해 1시간 TTL을 활성화합니다:299다음 예제는 Amazon Bedrock에서 실행되는 에이전트에 대해 1시간 TTL을 활성화합니다:

300 300

301<CodeGroup>301<CodeGroup>

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

agent-sdk/custom-tools.md +15 −13

Details

21| 도구 사전 승인 | 허용된 도구에 추가합니다. [허용된 도구 구성](#configure-allowed-tools)을 참조하세요. |21| 도구 사전 승인 | 허용된 도구에 추가합니다. [허용된 도구 구성](#configure-allowed-tools)을 참조하세요. |

27| 많은 도구로 확장 | [도구 검색](/ko/agent-sdk/tool-search)을 사용하여 필요에 따라 도구를 로드합니다. |27| 많은 도구로 확장 | [도구 검색](/ko/agent-sdk/tool-search)을 사용하여 필요에 따라 도구를 로드합니다. |

356 오류 처리356 오류 처리

357</h2>357</h2>

358 358

359핸들러가 오류를 보고하는 방식에 따라 에이전트 루프가 계속되는지 중지되는지가 결정됩니다:359핸들러 오류는 에이전트 루프를 중지하지 않습니다. SDK의 인프로세스 MCP 서버는 포착되지 않은 예외를 잡아서 오류 결과로 반환하므로, 오류를 보고하는 방식에 따라 Claude가 읽는 내용이 결정되며, 쿼리 실패 여부는 결정되지 않습니다:

360 360

361| 발생하는 상황 | 결과 |361| 발생하는 상황 | 결과 |

362| :---------------------------------------------------------------------- | :------------------------------------------------------------------------ |362| :---------------------------------------------------------------------- | :------------------------------------------------------------------------------------ |

363| 핸들러가 포착되지 않은 예외를 발생시킵니다 | 에이전트 루프가 중지됩니다. Claude는 오류를 보지 못하고 `query` 호출이 실패합니다. |363| 핸들러가 포착되지 않은 예외를 발생시킵니다 | MCP 서버는 이를 원본 예외 메시지를 담은 오류 결과로 변환합니다. Claude는 해당 메시지를 보고 에이전트 루프가 계속됩니다. |

364| 핸들러가 오류를 포착하고 `isError: true` (TS) / `"is_error": True` (Python)를 반환합니다 | 에이전트 루프가 계속됩니다. Claude는 오류를 데이터로 보고 재시도하거나, 다른 도구를 시도하거나, 실패를 설명할 수 있습니다. |364| 핸들러가 오류를 포착하고 `isError: true` (TS) / `"is_error": True` (Python)를 반환합니다 | Claude는 사용자가 작성한 메시지를 봅니다. 원본 예외가 부족한 컨텍스트(예: 어떤 요청이 실패했는지 또는 대신 시도할 사항)를 추가할 수 있습니다. |

365 365

366아래 예제는 핸들러 내에서 두 가지 종류의 실패를 포착합니다. 200이 아닌 HTTP 상태는 응답에서 포착되어 오류 결과로 반환됩니다. 네트워크 오류 또는 잘못된 JSON은 주변 `try/except` (Python) 또는 `try/catch` (TypeScript)로 포착되어 오류 결과로도 반환됩니다. 두 경우 모두 핸들러는 정상적으로 반환되고 에이전트 루프가 계속됩니다.366두 경우 모두 Claude는 재시도하거나, 다른 도구를 시도하거나, 실패를 설명할 수 있습니다. 원본 예외 메시지가 Claude가 작용하기에 충분하지 않을 때 오류를 직접 포착하세요.

367

368아래 예제는 핸들러 내에서 두 가지 종류의 실패를 포착하고 Claude가 읽는 오류 메시지를 작성합니다. 200이 아닌 HTTP 상태는 응답에서 포착되어 오류 결과로 반환됩니다. 네트워크 오류 또는 잘못된 JSON은 주변 `try/except` (Python) 또는 `try/catch` (TypeScript)로 포착되어 오류 결과로도 반환됩니다. 두 경우 모두 Claude는 단순한 예외 문자열 대신 실패를 설명하는 메시지를 받습니다.

367 369

368<CodeGroup>370<CodeGroup>

369 ```python Python theme={null}371 ```python Python theme={null}

397 data = response.json()399 data = response.json()

398 return {"content": [{"type": "text", "text": json.dumps(data, indent=2)}]}400 return {"content": [{"type": "text", "text": json.dumps(data, indent=2)}]}

399 except Exception as e:401 except Exception as e:

400 # 여기서 포착하면 에이전트 루프가 살아있습니다. 포착되지 않은 예외는402 # Claude가 읽는 메시지를 작성합니다. 포착되지 않은 예외는

401 # 전체 query() 호출을 종료합니다.403 # 컨텍스트 없이 원본 str(e)로 Claude에 도달합니다.

402 return {404 return {

403 "content": [{"type": "text", "text": f"Failed to fetch data: {str(e)}"}],405 "content": [{"type": "text", "text": f"Failed to fetch data: {str(e)}"}],

404 "is_error": True,406 "is_error": True,

440 ]442 ]

441 };443 };

442 } catch (error) {444 } catch (error) {

443 // 여기서 포착하면 에이전트 루프가 살아있습니다. 포착되지 않은 throw는445 // Claude가 읽는 메시지를 작성합니다. 포착되지 않은 throw는

444 // 전체 query() 호출을 종료합니다.446 // 컨텍스트 없이 원본 오류 메시지로 Claude에 도달합니다.

445 return {447 return {

446 content: [448 content: [

447 {449 {

461 이미지 및 리소스 반환463 이미지 및 리소스 반환

462</h2>464</h2>

463 465

464도구 결과의 `content` 배열은 `text`, `image`, `audio`, `resource` 및 `resource_link` 블록을 허용합니다. 동일한 응답에서 이들을 혼합할 수 있습니다. 오디오 블록은 디스크에 저장되며 Claude는 저장된 파일 경로가 포함된 텍스트 블록을 받습니다. 리소스 링크 블록은 링크의 이름, URI 및 설명을 포함하는 텍스트 블록으로 변환됩니다.466도구 결과의 `content` 배열은 `text`, `image`, `audio`, `resource` 및 `resource_link` 블록을 허용합니다. 동일한 응답에서 이들을 혼합할 수 있습니다. TypeScript에서 오디오 블록은 디스크에 저장되며 Claude는 저장된 파일 경로가 포함된 텍스트 블록을 받습니다. Python에서 SDK는 도구 결과에서 오디오 블록을 삭제하고 경고를 기록합니다. 리소스 링크 블록은 링크의 이름, URI 및 설명을 포함하는 텍스트 블록으로 변환됩니다.

465 467

466<h3 id="images">468<h3 id="images">

467 이미지469 이미지

535리소스 블록은 URI로 식별되는 콘텐츠 조각을 포함합니다. URI는 Claude가 참조할 레이블입니다. 실제 콘텐츠는 블록의 `text` 또는 `blob` 필드에 있습니다. 도구가 나중에 이름으로 주소를 지정하는 것이 합리적인 것을 생성할 때 사용합니다. 예를 들어 생성된 파일 또는 외부 시스템의 레코드입니다.537리소스 블록은 URI로 식별되는 콘텐츠 조각을 포함합니다. URI는 Claude가 참조할 레이블입니다. 실제 콘텐츠는 블록의 `text` 또는 `blob` 필드에 있습니다. 도구가 나중에 이름으로 주소를 지정하는 것이 합리적인 것을 생성할 때 사용합니다. 예를 들어 생성된 파일 또는 외부 시스템의 레코드입니다.

536 538

537| 필드 | 유형 | 참고 |539| 필드 | 유형 | 참고 |

538| :------------------ | :----------- | :------------------------------------------- |540| :------------------ | :----------- | :----------------------------------------------------------------------------------------- |

544 546

545이 예제는 도구 핸들러 내에서 반환된 리소스 블록을 보여줍니다. URI `file:///tmp/report.md`는 Claude가 나중에 참조할 수 있는 레이블입니다. SDK는 해당 경로에서 읽지 않습니다.547이 예제는 도구 핸들러 내에서 반환된 리소스 블록을 보여줍니다. URI `file:///tmp/report.md`는 Claude가 나중에 참조할 수 있는 레이블입니다. SDK는 해당 경로에서 읽지 않습니다.

agent-sdk/hooks.md +1 −1

Details

250 250

251* **입력 데이터:** 이벤트 세부 정보를 포함하는 입력된 객체입니다. 각 훅 유형은 자체 입력 형태를 가집니다. 예를 들어 `PreToolUseHookInput`은 `tool_name`과 `tool_input`을 포함하고, `NotificationHookInput`은 `message`를 포함합니다. [TypeScript](/ko/agent-sdk/typescript#hookinput) 및 [Python](/ko/agent-sdk/python#hookinput) SDK 참조에서 전체 타입 정의를 참조하세요.251* **입력 데이터:** 이벤트 세부 정보를 포함하는 입력된 객체입니다. 각 훅 유형은 자체 입력 형태를 가집니다. 예를 들어 `PreToolUseHookInput`은 `tool_name`과 `tool_input`을 포함하고, `NotificationHookInput`은 `message`를 포함합니다. [TypeScript](/ko/agent-sdk/typescript#hookinput) 및 [Python](/ko/agent-sdk/python#hookinput) SDK 참조에서 전체 타입 정의를 참조하세요.

252 * 모든 훅 입력은 `session_id`, `cwd`, `hook_event_name`을 공유합니다.252 * 모든 훅 입력은 `session_id`, `cwd`, `hook_event_name`을 공유합니다.

253 * `agent_id`와 `agent_type`은 훅이 서브에이전트 내에서 발생할 때 채워집니다. TypeScript에서는 기본 훅 입력에 있으며 모든 훅 유형에서 사용 가능합니다. Python에서는 `PreToolUse`, `PostToolUse`, `PostToolUseFailure`에만 있습니다.253 * `agent_id`와 `agent_type`은 훅이 서브에이전트 내에서 발생할 때 채워집니다. TypeScript에서는 기본 훅 입력에 있으며 모든 훅 유형에서 사용 가능합니다. Python에서는 `PreToolUse`, `PostToolUse`, `PostToolUseFailure`, `PermissionRequest`에서 선택적 필드이며, `SubagentStart`와 `SubagentStop`에서 필수 필드입니다.

254* **도구 사용 ID** (`str | None` / `string | undefined`): 동일한 도구 호출에 대해 `PreToolUse` 및 `PostToolUse` 이벤트를 연결합니다.254* **도구 사용 ID** (`str | None` / `string | undefined`): 동일한 도구 호출에 대해 `PreToolUse` 및 `PostToolUse` 이벤트를 연결합니다.

255* **컨텍스트:** TypeScript에서는 취소를 위한 `signal` 속성(`AbortSignal`)을 포함합니다. Python에서는 이 인수는 향후 사용을 위해 예약되어 있습니다.255* **컨텍스트:** TypeScript에서는 취소를 위한 `signal` 속성(`AbortSignal`)을 포함합니다. Python에서는 이 인수는 향후 사용을 위해 예약되어 있습니다.

256 256

agent-sdk/hosting.md +1 −1

Details

189 네트워크189 네트워크

190</h3>190</h3>

191 191

192SDK는 `api.anthropic.com`으로 또는 Bedrock 또는 Vertex에서 실행할 때 제공자의 지역 엔드포인트로 아웃바운드 HTTPS가 필요합니다. 에이전트가 [MCP 서버](/ko/agent-sdk/mcp) 또는 외부 도구를 사용하는 경우 해당 엔드포인트에 대한 아웃바운드 액세스도 필요합니다. 프로덕션의 경우 도메인 허용 목록을 적용하고, 자격 증명을 주입하고, 요청을 기록하는 송신 프록시를 통해 아웃바운드 트래픽을 라우팅하십시오. 전체 패턴은 [보안 배포](/ko/agent-sdk/secure-deployment)를 참조하십시오.192SDK는 `api.anthropic.com`으로 또는 Amazon Bedrock이나 Google Cloud의 Agent Platform에서 실행할 때 제공자의 지역 엔드포인트로 아웃바운드 HTTPS가 필요합니다. 에이전트가 [MCP 서버](/ko/agent-sdk/mcp) 또는 외부 도구를 사용하는 경우 해당 엔드포인트에 대한 아웃바운드 액세스도 필요합니다. 프로덕션의 경우 도메인 허용 목록을 적용하고, 자격 증명을 주입하고, 요청을 기록하는 송신 프록시를 통해 아웃바운드 트래픽을 라우팅하십시오. 전체 패턴은 [보안 배포](/ko/agent-sdk/secure-deployment)를 참조하십시오.

193 193

194인바운드 트래픽의 경우 컨테이너에서 HTTP 또는 WebSocket 포트를 노출합니다. 애플리케이션은 해당 포트에서 클라이언트 요청을 처리하고 내부적으로 SDK를 호출합니다. 서브프로세스 자체는 네트워크에서 수신 대기하지 않습니다.194인바운드 트래픽의 경우 컨테이너에서 HTTP 또는 WebSocket 포트를 노출합니다. 애플리케이션은 해당 포트에서 클라이언트 요청을 처리하고 내부적으로 SDK를 호출합니다. 서브프로세스 자체는 네트워크에서 수신 대기하지 않습니다.

195 195

agent-sdk/mcp.md +1 −1

Details

823 연결 시간 초과823 연결 시간 초과

824</h3>824</h3>

825 825

826MCP SDK는 서버 연결에 대해 기본 60초 시간 초과를 가집니다. 서버가 더 오래 시작되는 경우 연결이 실패합니다. 더 많은 시작 시간이 필요한 서버의 경우 다음을 고려합니다:826MCP 서버 연결은 기본적으로 30초 후 시간 초과됩니다. 서버가 더 오래 시작되는 경우 연결이 실패합니다. [`MCP_TIMEOUT`](/ko/env-vars) 환경 변수(밀리초 단위)로 제한을 높입니다. 더 많은 시작 시간이 필요한 서버의 경우 다음을 고려합니다:

827 827

828* 사용 가능한 경우 더 가벼운 서버 사용828* 사용 가능한 경우 더 가벼운 서버 사용

829* 에이전트를 시작하기 전에 서버 사전 준비829* 에이전트를 시작하기 전에 서버 사전 준비

agent-sdk/modifying-system-prompts.md +5 −1

Details

152 152

153* **CLI**: `/config`를 실행하고 출력 스타일을 선택합니다153* **CLI**: `/config`를 실행하고 출력 스타일을 선택합니다

154* **설정**: `.claude/settings.local.json`에서 `outputStyle`을 설정합니다154* **설정**: `.claude/settings.local.json`에서 `outputStyle`을 설정합니다

155* **TypeScript SDK**: `query()`에 전달된 인라인 `settings` 객체 내에서 `outputStyle`을 설정하거나, `settings`가 이를 설정하는 설정 파일을 가리키도록 합니다. `outputStyle`은 최상위 `Options` 필드가 아닙니다155* **TypeScript SDK**: `query()`에 전달된 인라인 `settings` 객체 내에서 `outputStyle`을 설정하거나, `settings`가 이를 설정하는 설정 파일을 가리키도록 합니다. `outputStyle`은 최상위 `Options` 필드가 아닙니다:

156

157 ```typescript theme={null}

158 const options = { settings: { outputStyle: "Explanatory" } };

159 ```

156 160

157Python SDK는 프로그래밍 방식으로 출력 스타일을 선택하는 옵션이 없습니다. `.claude/settings.local.json`에 쓸 수 없는 코드 전용 배포의 경우, `append` 또는 사용자 정의 프롬프트 문자열을 대신 사용하십시오.161Python SDK는 프로그래밍 방식으로 출력 스타일을 선택하는 옵션이 없습니다. `.claude/settings.local.json`에 쓸 수 없는 코드 전용 배포의 경우, `append` 또는 사용자 정의 프롬프트 문자열을 대신 사용하십시오.

158 162

agent-sdk/observability.md +2 −2

Details

206 206

207CLI는 Anthropic을 호출하는 데 사용하는 자격 증명을 기반으로 모든 이벤트에 [ID 속성](/ko/monitoring-usage#standard-attributes)을 첨부합니다. 하나의 배포에서 많은 최종 사용자를 제공하는 애플리케이션을 구축할 때 이러한 속성은 에이전트가 대신 작동한 최종 사용자가 아닌 서비스의 자격 증명을 식별합니다.207CLI는 Anthropic을 호출하는 데 사용하는 자격 증명을 기반으로 모든 이벤트에 [ID 속성](/ko/monitoring-usage#standard-attributes)을 첨부합니다. 하나의 배포에서 많은 최종 사용자를 제공하는 애플리케이션을 구축할 때 이러한 속성은 에이전트가 대신 작동한 최종 사용자가 아닌 서비스의 자격 증명을 식별합니다.

208 208

209도구 호출 및 MCP 활동을 애플리케이션의 최종 사용자에게 귀속시키려면 각 `query()` 호출에서 최종 사용자 ID를 리소스 속성으로 주입합니다. `OTEL_RESOURCE_ATTRIBUTES`가 [쉼표, 공백 및 등호 기호를 예약](/ko/monitoring-usage#multi-team-organization-support)하므로 값을 퍼센트 인코딩하세요. 다음 예제는 요청하는 사용자 및 테넌트를 한 요청의 모든 스팬 및 이벤트에 첨부합니다:209도구 호출 및 MCP 활동을 애플리케이션의 최종 사용자에게 귀속시키려면 각 `query()` 호출에서 최종 사용자 ID를 리소스 속성으로 주입합니다. `OTEL_RESOURCE_ATTRIBUTES`가 [쉼표, 공백 및 등호 기호를 예약](/ko/monitoring-usage#multi-team-organization-support)하므로 값을 퍼센트 인코딩하세요. 다음 예제는 요청하는 사용자 및 테넌트를 한 요청의 모든 스팬 및 이벤트에 첨부합니다. 웹 프레임워크의 `request` 객체가 사용자 및 테넌트 ID를 전달한다고 가정합니다:

210 210

211<CodeGroup>211<CodeGroup>

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

231 ```231 ```

232</CodeGroup>232</CodeGroup>

233 233

234최종 사용자 ID가 첨부되면 `tool_decision`, `tool_result`, `mcp_server_connection` 및 `permission_mode_changed` 이벤트는 Security Information and Event Management(SIEM) 플랫폼으로 전달할 수 있는 사용자별 감사 추적이 됩니다. 모니터링 참조의 [보안 이벤트 감사](/ko/monitoring-usage#audit-security-events)에서 보안 관련 이벤트의 전체 목록과 각 이벤트가 포함하는 속성을 확인하세요.234최종 사용자 ID가 첨부되면 `tool_decision`, `tool_result`, `mcp_server_connection` 및 `permission_mode_changed` 이벤트는 `claude_code.` 접두사가 있는 로그 레코드로 내보내지며, Security Information and Event Management(SIEM) 플랫폼으로 전달할 수 있는 사용자별 감사 추적이 됩니다. 모니터링 참조의 [보안 이벤트 감사](/ko/monitoring-usage#audit-security-events)에서 보안 관련 이벤트의 전체 목록과 각 이벤트가 포함하는 속성을 확인하세요.

235 235

236<h2 id="control-sensitive-data-in-exports">236<h2 id="control-sensitive-data-in-exports">

237 내보내기에서 민감한 데이터 제어237 내보내기에서 민감한 데이터 제어

agent-sdk/overview.md +2 −2

Details

87 87

88 * **Amazon Bedrock**: `CLAUDE_CODE_USE_BEDROCK=1` 환경 변수를 설정하고 AWS 자격 증명을 구성합니다88 * **Amazon Bedrock**: `CLAUDE_CODE_USE_BEDROCK=1` 환경 변수를 설정하고 AWS 자격 증명을 구성합니다

89 * **Claude Platform on AWS**: `CLAUDE_CODE_USE_ANTHROPIC_AWS=1` 및 `ANTHROPIC_AWS_WORKSPACE_ID`를 설정한 다음 AWS 자격 증명을 구성합니다89 * **Claude Platform on AWS**: `CLAUDE_CODE_USE_ANTHROPIC_AWS=1` 및 `ANTHROPIC_AWS_WORKSPACE_ID`를 설정한 다음 AWS 자격 증명을 구성합니다

~~90 * **Google Vertex AI**: `CLAUDE_CODE_USE_VERTEX=1` 환경 변수를 설정하고 Google Cloud 자격 증명을 구성합니다~~90 * **Google Cloud의 Agent Platform**: `CLAUDE_CODE_USE_VERTEX=1` 환경 변수를 설정하고 Google Cloud 자격 증명을 구성합니다

91 * **Microsoft Azure**: `CLAUDE_CODE_USE_FOUNDRY=1` 환경 변수를 설정하고 Azure 자격 증명을 구성합니다91 * **Microsoft Azure**: `CLAUDE_CODE_USE_FOUNDRY=1` 환경 변수를 설정하고 Azure 자격 증명을 구성합니다

92 92

93 [Bedrock](/ko/amazon-bedrock), [Claude Platform on AWS](/ko/claude-platform-on-aws), [Vertex AI](/ko/google-vertex-ai) 또는 [Azure AI Foundry](/ko/microsoft-foundry)의 설정 가이드를 참조하십시오.93 [Amazon Bedrock](/ko/amazon-bedrock), [Claude Platform on AWS](/ko/claude-platform-on-aws), [Google Cloud의 Agent Platform](/ko/google-vertex-ai), 또는 [Microsoft Foundry](/ko/microsoft-foundry)의 설정 가이드를 참조하십시오.

94 94

95 <Note>95 <Note>

96 이전에 승인되지 않은 경우, Anthropic은 타사 개발자가 Claude Agent SDK로 구축한 에이전트를 포함하여 자신의 제품에 대해 claude.ai 로그인 또는 속도 제한을 제공하도록 허용하지 않습니다. 대신 이 문서에 설명된 API 키 인증 방법을 사용하십시오.96 이전에 승인되지 않은 경우, Anthropic은 타사 개발자가 Claude Agent SDK로 구축한 에이전트를 포함하여 자신의 제품에 대해 claude.ai 로그인 또는 속도 제한을 제공하도록 허용하지 않습니다. 대신 이 문서에 설명된 API 키 인증 방법을 사용하십시오.

agent-sdk/permissions.md +2 −2

Details

109SDK는 다음 권한 모드를 지원합니다:109SDK는 다음 권한 모드를 지원합니다:

110 110

111| 모드 | 설명 | 도구 동작 |111| 모드 | 설명 | 도구 동작 |

112| :---------------------- | :---------- | :-------------------------------------------------------------------------------------------------------- |112| :------------------ | :---------- | :-------------------------------------------------------------------------------------------------------- |

119 119

120<Warning>120<Warning>

121 **하위 에이전트 상속:** 부모가 `bypassPermissions`, `acceptEdits` 또는 `auto`를 사용할 때 모든 하위 에이전트는 해당 모드를 상속하며 하위 에이전트별로 재정의할 수 없습니다. 하위 에이전트는 주 에이전트와 다른 시스템 프롬프트와 덜 제한된 동작을 가질 수 있으므로 `bypassPermissions`를 상속하면 전체 자율 시스템 액세스 권한이 부여됩니다. 명시적 [`ask` 규칙](#how-permissions-are-evaluated)은 여전히 프롬프트를 강제합니다.121 **하위 에이전트 상속:** 부모가 `bypassPermissions`, `acceptEdits` 또는 `auto`를 사용할 때 모든 하위 에이전트는 해당 모드를 상속하며 하위 에이전트별로 재정의할 수 없습니다. 하위 에이전트는 주 에이전트와 다른 시스템 프롬프트와 덜 제한된 동작을 가질 수 있으므로 `bypassPermissions`를 상속하면 전체 자율 시스템 액세스 권한이 부여됩니다. 명시적 [`ask` 규칙](#how-permissions-are-evaluated)은 여전히 프롬프트를 강제합니다.

agent-sdk/python.md +28 −6

Details

854class ClaudeAgentOptions:854class ClaudeAgentOptions:

855 tools: list[str] | ToolsPreset | None = None855 tools: list[str] | ToolsPreset | None = None

856 allowed_tools: list[str] = field(default_factory=list)856 allowed_tools: list[str] = field(default_factory=list)

858 mcp_servers: dict[str, McpServerConfig] | str | Path = field(default_factory=dict)858 mcp_servers: dict[str, McpServerConfig] | str | Path = field(default_factory=dict)

859 strict_mcp_config: bool = False859 strict_mcp_config: bool = False

860 permission_mode: PermissionMode | None = None860 permission_mode: PermissionMode | None = None

900| :---------------------------- | :------------------------------------------------------------------------------------ | :---------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |900| :---------------------------- | :------------------------------------------------------------------------------------ | :---------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

901| `tools` | `list[str] \| ToolsPreset \| None` | `None` | 도구 구성. Claude Code의 기본 도구를 위해 `{"type": "preset", "preset": "claude_code"}` 사용 |901| `tools` | `list[str] \| ToolsPreset \| None` | `None` | 도구 구성. Claude Code의 기본 도구를 위해 `{"type": "preset", "preset": "claude_code"}` 사용 |

902| `allowed_tools` | `list[str]` | `[]` | 프롬프트 없이 자동 승인할 도구. 이것은 Claude를 이 도구로만 제한하지 않습니다. 나열되지 않은 도구는 `permission_mode` 및 `can_use_tool`로 넘어갑니다. `disallowed_tools`를 사용하여 도구를 차단합니다. [권한](/ko/agent-sdk/permissions#allow-and-deny-rules) 참조 |902| `allowed_tools` | `list[str]` | `[]` | 프롬프트 없이 자동 승인할 도구. 이것은 Claude를 이 도구로만 제한하지 않습니다. 나열되지 않은 도구는 `permission_mode` 및 `can_use_tool`로 넘어갑니다. `disallowed_tools`를 사용하여 도구를 차단합니다. [권한](/ko/agent-sdk/permissions#allow-and-deny-rules) 참조 |

903| `system_prompt` | `str \| SystemPromptPreset \| None` | `None` | 시스템 프롬프트 구성. 사용자 정의 프롬프트의 경우 문자열을 전달하거나, Claude Code의 시스템 프롬프트를 위해 `{"type": "preset", "preset": "claude_code"}` 사용. 프리셋을 확장하려면 `"append"` 추가 |903| `system_prompt` | `str \| SystemPromptPreset \| SystemPromptFile \| None` | `None` | 시스템 프롬프트 구성. 사용자 정의 프롬프트의 경우 문자열을 전달하거나, Claude Code의 시스템 프롬프트를 위해 `{"type": "preset", "preset": "claude_code"}`를 선택적 `"append"`와 함께 사용하거나, `{"type": "file", "path": "..."}` 형식으로 디스크에서 큰 프롬프트를 로드합니다. [`SystemPromptPreset`](#systempromptpreset) 및 [`SystemPromptFile`](#systempromptfile) 참조 |

904| `mcp_servers` | `dict[str, McpServerConfig] \| str \| Path` | `{}` | MCP 서버 구성 또는 구성 파일 경로 |904| `mcp_servers` | `dict[str, McpServerConfig] \| str \| Path` | `{}` | MCP 서버 구성 또는 구성 파일 경로 |

905| `strict_mcp_config` | `bool` | `False` | `True`일 때, `mcp_servers`에 전달된 서버만 사용하고 프로젝트 `.mcp.json`, 사용자 설정, 플러그인 제공 MCP 서버 및 [claude.ai 커넥터](/ko/mcp#use-mcp-servers-from-claude-ai)를 무시합니다. CLI `--strict-mcp-config` 플래그에 매핑됩니다 |905| `strict_mcp_config` | `bool` | `False` | `True`일 때, `mcp_servers`에 전달된 서버만 사용하고 프로젝트 `.mcp.json`, 사용자 설정, 플러그인 제공 MCP 서버 및 [claude.ai 커넥터](/ko/mcp#use-mcp-servers-from-claude-ai)를 무시합니다. CLI `--strict-mcp-config` 플래그에 매핑됩니다 |

1002| `append` | 아니오 | 프리셋 시스템 프롬프트에 추가할 추가 지침 |1002| `append` | 아니오 | 프리셋 시스템 프롬프트에 추가할 추가 지침 |

1003| `exclude_dynamic_sections` | 아니오 | 작업 디렉토리, git 상태 및 메모리 경로와 같은 세션별 컨텍스트를 시스템 프롬프트에서 첫 사용자 메시지로 이동합니다. 사용자 및 머신 간 프롬프트 캐시 재사용을 개선합니다. [시스템 프롬프트 수정](/ko/agent-sdk/modifying-system-prompts#improve-prompt-caching-across-users-and-machines) 참조 |1003| `exclude_dynamic_sections` | 아니오 | 작업 디렉토리, git 상태 및 메모리 경로와 같은 세션별 컨텍스트를 시스템 프롬프트에서 첫 사용자 메시지로 이동합니다. 사용자 및 머신 간 프롬프트 캐시 재사용을 개선합니다. [시스템 프롬프트 수정](/ko/agent-sdk/modifying-system-prompts#improve-prompt-caching-across-users-and-machines) 참조 |

1004 1004

1005<h3 id="systempromptfile">

1006 `SystemPromptFile`

1007</h3>

1008

1009파일에서 사용자 정의 시스템 프롬프트를 로드하기 위한 구성입니다. 문자열로 전달하는 대신 파일 형식을 사용합니다. SDK는 이를 CLI [`--system-prompt-file`](/ko/cli-reference#system-prompt-flags) 플래그에 매핑합니다. 프롬프트가 큰 경우 파일 형식을 사용합니다: SDK는 문자열 `system_prompt`를 CLI 서브프로세스 argv에 전달하며, 이는 SDK가 API 요청을 보내기 전에 OS 명령줄 길이 제한의 대상입니다. Linux에서 대략 128 KB보다 긴 단일 인수는 `Argument list too long` 오류로 프로세스 생성에 실패합니다. Windows에서는 전체 명령줄이 대략 32 KB로 제한되므로 문자열 형식은 더 낮은 임계값에서 실패합니다.

1010

1011```python theme={null}

1012class SystemPromptFile(TypedDict):

1013 type: Literal["file"]

1014 path: str

1015```

1016

1017| 필드 | 필수 | 설명 |

1018| :----- | :- | :-------------------------------- |

1019| `type` | 예 | 디스크에서 프롬프트를 로드하려면 `"file"`이어야 합니다 |

1020| `path` | 예 | 시스템 프롬프트를 포함하는 파일의 경로 |

1021

1005<h3 id="settingsource">1022<h3 id="settingsource">

1006 `SettingSource`1023 `SettingSource`

1007</h3>1024</h3>

1022 기본 동작1039 기본 동작

1023</h4>1040</h4>

1024 1041

1025`setting_sources`가 생략되거나 `None`일 때, `query()`는 Claude Code CLI와 동일한 파일 시스템 설정을 로드합니다: 사용자, 프로젝트 및 로컬. 관리형 정책 설정은 모든 경우에 로드됩니다. 서버 관리 설정은 [적격 구성](/ko/server-managed-settings#platform-availability)에서 조직 자격증명으로 세션이 인증될 때 가져옵니다. [settingSources가 제어하지 않는 것](/ko/agent-sdk/claude-code-features#what-settingsources-does-not-control)에서 이것이 제어하지 않는 입력 및 비활성화 방법을 참조하십시오.1042`setting_sources`가 생략되거나 `None`일 때, `query()`는 Claude Code CLI와 동일한 파일 시스템 설정을 로드합니다: 사용자, 프로젝트 및 로컬. 관리형 정책 설정은 모든 경우에 로드됩니다. 서버 관리 설정은 [적격 구성](/ko/server-managed-settings#platform-availability)에서 조직 자격증명으로 세션이 인증될 때 가져옵니다. [Claude Code 기능 사용](/ko/agent-sdk/claude-code-features#what-settingsources-does-not-control)에서 이것이 제어하지 않는 입력 및 비활성화 방법을 참조하십시오.

1026 1043

1027<h4 id="why-use-setting_sources">1044<h4 id="why-use-setting_sources">

1028 setting\_sources를 사용하는 이유1045 setting\_sources를 사용하는 이유

1192 "plan", # Planning mode - explore without editing1209 "plan", # Planning mode - explore without editing

1193 "dontAsk", # Deny anything not pre-approved instead of prompting1210 "dontAsk", # Deny anything not pre-approved instead of prompting

1194 "bypassPermissions", # Bypass permission checks; explicit ask rules still prompt (use with caution)1211 "bypassPermissions", # Bypass permission checks; explicit ask rules still prompt (use with caution)

1212 "auto", # A model classifier approves or denies each tool call

1195]1213]

1196```1214```

1197 1215

1755```1773```

1756 1774

1757| 필드 | 타입 | 설명 |1775| 필드 | 타입 | 설명 |

1758| :------------------- | :--------------- | :---------------------------------- |1776| :------------------- | :--------------- | :-------------------------------------------------------------------------------------------------------------- |

1759| `uuid` | `str` | 이 이벤트의 고유 식별자입니다 |1777| `uuid` | `str` | 이 이벤트의 고유 식별자입니다 |

1760| `session_id` | `str` | 세션 식별자입니다 |1778| `session_id` | `str` | 세션 식별자입니다 |

1763 1781

1764<h3 id="ratelimitevent">1782<h3 id="ratelimitevent">

1765 `RateLimitEvent`1783 `RateLimitEvent`

2393 tool_name: str2411 tool_name: str

2394 tool_input: dict[str, Any]2412 tool_input: dict[str, Any]

2395 permission_suggestions: NotRequired[list[Any]]2413 permission_suggestions: NotRequired[list[Any]]

2414 agent_id: NotRequired[str]

2415 agent_type: NotRequired[str]

2396```2416```

2397 2417

2398| 필드 | 타입 | 설명 |2418| 필드 | 타입 | 설명 |

2399| :----------------------- | :----------------------------- | :--------------------- |2419| :----------------------- | :----------------------------- | :------------------------------------ |

2401| `tool_name` | `str` | 권한을 요청하는 도구의 이름 |2421| `tool_name` | `str` | 권한을 요청하는 도구의 이름 |

2424| `agent_id` | `str` (선택사항) | 서브에이전트 식별자, hook이 서브에이전트 내에서 발생할 때 존재 |

2425| `agent_type` | `str` (선택사항) | 서브에이전트 타입, hook이 서브에이전트 내에서 발생할 때 존재 |

2404 2426

2405<h3 id="hookjsonoutput">2427<h3 id="hookjsonoutput">

2406 `HookJSONOutput`2428 `HookJSONOutput`

agent-sdk/quickstart.md +4 −4

Details

121 121

122 * **Amazon Bedrock**: `CLAUDE_CODE_USE_BEDROCK=1` 환경 변수를 설정하고 AWS 자격 증명을 구성합니다122 * **Amazon Bedrock**: `CLAUDE_CODE_USE_BEDROCK=1` 환경 변수를 설정하고 AWS 자격 증명을 구성합니다

123 * **Claude Platform on AWS**: `CLAUDE_CODE_USE_ANTHROPIC_AWS=1` 및 `ANTHROPIC_AWS_WORKSPACE_ID`를 설정한 다음 AWS 자격 증명을 구성합니다123 * **Claude Platform on AWS**: `CLAUDE_CODE_USE_ANTHROPIC_AWS=1` 및 `ANTHROPIC_AWS_WORKSPACE_ID`를 설정한 다음 AWS 자격 증명을 구성합니다

124 * **Google Vertex AI**: `CLAUDE_CODE_USE_VERTEX=1` 환경 변수를 설정하고 Google Cloud 자격 증명을 구성합니다124 * **Google Cloud의 Agent Platform**: `CLAUDE_CODE_USE_VERTEX=1` 환경 변수를 설정하고 Google Cloud 자격 증명을 구성합니다

125 * **Microsoft Azure**: `CLAUDE_CODE_USE_FOUNDRY=1` 환경 변수를 설정하고 Azure 자격 증명을 구성합니다125 * **Microsoft Azure**: `CLAUDE_CODE_USE_FOUNDRY=1` 환경 변수를 설정하고 Azure 자격 증명을 구성합니다

126 126

127 [Bedrock](/ko/amazon-bedrock), [Claude Platform on AWS](/ko/claude-platform-on-aws), [Vertex AI](/ko/google-vertex-ai) 또는 [Azure AI Foundry](/ko/microsoft-foundry)의 설정 가이드를 참조하여 자세한 내용을 확인합니다.127 [Amazon Bedrock](/ko/amazon-bedrock), [Claude Platform on AWS](/ko/claude-platform-on-aws), [Google Cloud의 Agent Platform](/ko/google-vertex-ai) 또는 [Microsoft Foundry](/ko/microsoft-foundry)의 설정 가이드를 참조하여 자세한 내용을 확인합니다.

128 128

129 <Note>129 <Note>

130 이전에 승인되지 않은 경우 Anthropic은 타사 개발자가 claude.ai 로그인 또는 Claude Agent SDK를 기반으로 구축된 에이전트를 포함한 제품에 대한 속도 제한을 제공하는 것을 허용하지 않습니다. 대신 이 문서에 설명된 API 키 인증 방법을 사용하십시오.130 이전에 승인되지 않은 경우 Anthropic은 타사 개발자가 claude.ai 로그인 또는 Claude Agent SDK를 기반으로 구축된 에이전트를 포함한 제품에 대한 속도 제한을 제공하는 것을 허용하지 않습니다. 대신 이 문서에 설명된 API 키 인증 방법을 사용하십시오.

368**권한 모드**는 원하는 인간 감독의 양을 제어합니다:368**권한 모드**는 원하는 인간 감독의 양을 제어합니다:

369 369

370| 모드 | 동작 | 사용 사례 |370| 모드 | 동작 | 사용 사례 |

371| ----------------------- | ------------------------------------------------------------------------------------------------------- | ------------------------ |371| ------------------- | ------------------------------------------------------------------------------------------------------- | ------------------------ |

378 378

agent-sdk/streaming-output.md +3 −1

Details

91 uuid: str # Unique identifier for this event91 uuid: str # Unique identifier for this event

92 session_id: str # Session identifier92 session_id: str # Session identifier

93 event: dict[str, Any] # The raw Claude API stream event93 event: dict[str, Any] # The raw Claude API stream event

~~94 parent_tool_use_id: str | None # Parent tool ID if from a subagent~~94 parent_tool_use_id: str | None # Always None

95 ```95 ```

96 96

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

106 ```106 ```

107</CodeGroup>107</CodeGroup>

108 108

109`parent_tool_use_id` 필드는 Python에서는 항상 `None`이고 TypeScript에서는 `null`입니다. 스트림 이벤트는 주 세션에서만 발생합니다. 서브에이전트의 토큰 수준 델타는 전달되지 않습니다. 출력을 서브에이전트에 귀속시키려면 `parent_tool_use_id`를 포함하는 완전한 메시지를 사용하십시오. [서브에이전트 호출 감지](/ko/agent-sdk/subagents#detect-subagent-invocation)를 참조하십시오.

110

109`event` 필드는 [Claude API](https://platform.claude.com/docs/en/build-with-claude/streaming#event-types)의 원본 스트리밍 이벤트를 포함합니다. 일반적인 이벤트 유형은 다음과 같습니다:111`event` 필드는 [Claude API](https://platform.claude.com/docs/en/build-with-claude/streaming#event-types)의 원본 스트리밍 이벤트를 포함합니다. 일반적인 이벤트 유형은 다음과 같습니다:

110 112

111| 이벤트 유형 | 설명 |113| 이벤트 유형 | 설명 |

agent-sdk/structured-outputs.md +4 −0

Details

247 247

248SDK는 모든 기본 타입(object, array, string, number, boolean, null), `enum`, `const`, `required`, 중첩 객체 및 `$ref` 정의를 포함한 표준 JSON Schema 기능을 지원합니다. 지원되는 기능 및 제한사항의 전체 목록은 [JSON Schema 제한사항](https://platform.claude.com/docs/ko/build-with-claude/structured-outputs#json-schema-limitations)을 참조하세요.248SDK는 모든 기본 타입(object, array, string, number, boolean, null), `enum`, `const`, `required`, 중첩 객체 및 `$ref` 정의를 포함한 표준 JSON Schema 기능을 지원합니다. 지원되는 기능 및 제한사항의 전체 목록은 [JSON Schema 제한사항](https://platform.claude.com/docs/ko/build-with-claude/structured-outputs#json-schema-limitations)을 참조하세요.

249 249

250유효한 JSON Schema가 아닌 스키마는 문제를 명시하는 오류와 함께 시작 시 실행에 실패합니다. v2.1.205 이전에는 유효하지 않은 스키마가 자동으로 무시되었고 에이전트가 구조화되지 않은 텍스트를 반환했습니다.

251

252`"format": "email"`과 같은 `format` 키워드는 주석으로 허용되며 SDK의 유효성 검사기에 의해 적용되지 않습니다. v2.1.205 이전에는 `format`을 포함하는 모든 스키마가 유효하지 않은 것으로 처리되었습니다.

253

250<h2 id="example-todo-tracking-agent">254<h2 id="example-todo-tracking-agent">

251 예제: TODO 추적 에이전트255 예제: TODO 추적 에이전트

252</h2>256</h2>

agent-sdk/subagents.md +3 −1

Details

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

235</Note>235</Note>

236 236

237Claude Code v2.1.199 기준으로, 속도 제한과 같이 서브에이전트를 조기에 종료하는 API 오류는 절대 결과로 전달되지 않습니다. 서브에이전트가 이미 출력을 생성한 경우, Agent 도구는 서브에이전트가 완료되지 않았다는 메모와 함께 해당 부분 출력을 반환합니다. 그렇지 않으면 도구 결과는 오류 메시지인 `Agent terminated early due to an API error`이며, 그 뒤에 오류 세부 정보가 따릅니다. 자세한 내용은 [서브에이전트의 API 오류](/ko/sub-agents#api-errors-in-subagents)를 참조하세요.237속도 제한과 같이 서브에이전트를 조기에 종료하는 API 오류는 절대 결과로 전달되지 않습니다. 속도 제한, 과부하 또는 서버 오류가 이미 텍스트 출력을 생성한 포그라운드 서브에이전트를 중단하는 경우, Agent 도구는 서브에이전트가 완료되지 않았다는 메모와 함께 해당 부분 출력을 반환합니다. 아무것도 생성하지 않았거나 텍스트 없이 도구 호출만 있었던 서브에이전트는 오류 메시지 `Agent terminated early due to an API error`와 함께 실패하며, 그 뒤에 오류 세부 정보가 따릅니다. [서브에이전트의 API 오류](/ko/sub-agents#api-errors-in-subagents)에서 포그라운드 및 백그라운드 동작을 참조하세요.

238

239이 부분 출력 처리는 Claude Code v2.1.199 이상이 필요합니다. v2.1.199에서는 속도 제한, 과부하 또는 서버 오류로 인해 도구 호출만 있는 형태가 중단 메모만 포함된 빈 부분 결과로 남겨졌습니다.

238 240

239<h2 id="invoke-subagents">241<h2 id="invoke-subagents">

240 서브에이전트 호출242 서브에이전트 호출

agent-sdk/tool-search.md +4 −4

Details

33 도구 검색 구성33 도구 검색 구성

34</h2>34</h2>

35 35

36도구 검색은 기본적으로 켜져 있습니다. Vertex AI에서는 기본적으로 비활성화되어 있으며, Claude Sonnet 4.5 이상 및 Claude Opus 4.5 이상에서 지원됩니다. `ANTHROPIC_BASE_URL`이 비공식 호스트를 가리킬 때도 비활성화됩니다. 대부분의 프록시는 `tool_reference` 블록을 전달하지 않기 때문입니다. `ENABLE_TOOL_SEARCH` 환경 변수로 기본값을 재정의할 수 있습니다:36도구 검색은 기본적으로 켜져 있습니다. Google Cloud의 Agent Platform에서는 기본적으로 비활성화되어 있으며, Claude Sonnet 4.5 이상 및 Claude Opus 4.5 이상에서 지원됩니다. `ANTHROPIC_BASE_URL`이 비공식 호스트를 가리킬 때도 비활성화됩니다. 대부분의 프록시는 `tool_reference` 블록을 전달하지 않기 때문입니다. `ENABLE_TOOL_SEARCH` 환경 변수로 기본값을 재정의할 수 있습니다:

37 37

38| 값 | 동작 |38| 값 | 동작 |

~~39| :------- | :---------------------------------------------------------------------------------------------------------------------------------------------------- |~~39| :------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |

41| `true` | 도구 검색이 항상 켜져 있습니다. SDK는 Vertex AI 및 프록시를 통해서도 베타 헤더를 전송합니다. Sonnet 4.5 또는 Opus 4.5보다 이전 Vertex AI 모델이나 `tool_reference` 블록을 지원하지 않는 프록시에서는 요청이 실패합니다. |41| `true` | 도구 검색이 항상 켜져 있습니다. SDK는 Google Cloud의 Agent Platform 및 프록시를 통해서도 베타 헤더를 전송합니다. Sonnet 4.5 또는 Opus 4.5보다 이전 Google Cloud의 Agent Platform 모델이나 `tool_reference` 블록을 지원하지 않는 프록시에서는 요청이 실패합니다. |

agent-sdk/typescript.md +97 −11

Details

296</h4>296</h4>

297 297

298| 속성 | 타입 | 설명 |298| 속성 | 타입 | 설명 |

299| :------------------- | :---------------------- | :------------------------------------------------------------------------------ |299| :------------------- | :---------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

305| `parent_agent_id` | `string \| null` | [중첩된 서브에이전트](/ko/sub-agents#spawn-nested-subagents)의 메시지의 경우 이를 생성한 서브에이전트의 `agentId`입니다. 메인 세션 메시지, 최상위 서브에이전트의 메시지 및 이전 세션의 경우 `null`입니다. {/* min-version: 2.1.202 */}Claude Code v2.1.202 이상 필요 |

305 306

306<h4 id="example-2">307<h4 id="example-2">

307 예제308 예제

563 564

564```typescript theme={null}565```typescript theme={null}

565interface Query extends AsyncGenerator<SDKMessage, void> {566interface Query extends AsyncGenerator<SDKMessage, void> {

566 interrupt(): Promise<void>;567 interrupt(): Promise<SDKControlInterruptResponse | undefined>;

567 rewindFiles(568 rewindFiles(

568 userMessageId: string,569 userMessageId: string,

569 options?: { dryRun?: boolean }570 options?: { dryRun?: boolean }

593</h4>594</h4>

594 595

595| 메서드 | 설명 |596| 메서드 | 설명 |

596| :------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |597| :------------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

597| `interrupt()` | 쿼리를 중단합니다 (스트리밍 입력 모드에서만 사용 가능) |598| `interrupt()` | 쿼리를 중단합니다. 스트리밍 입력 모드에서만 사용 가능합니다. {/* min-version: 2.1.205 */}CLI가 [`SDKSystemMessage.capabilities`](#sdksystemmessage)에서 `interrupt_receipt_v1` 기능을 광고할 때 중단을 견디는 대기 중인 메시지를 나열하는 [`SDKControlInterruptResponse`](#sdkcontrolinterruptresponse)로 해결됩니다. v2.1.205 이전의 CLI에서는 `undefined`로 해결됩니다 |

598| `rewindFiles(userMessageId, options?)` | 파일을 지정된 사용자 메시지의 상태로 복원합니다. 변경 사항을 미리 보려면 `{ dryRun: true }`를 전달합니다. `enableFileCheckpointing: true`가 필요합니다. [파일 체크포인팅](/ko/agent-sdk/file-checkpointing) 참조 |599| `rewindFiles(userMessageId, options?)` | 파일을 지정된 사용자 메시지의 상태로 복원합니다. 변경 사항을 미리 보려면 `{ dryRun: true }`를 전달합니다. `enableFileCheckpointing: true`가 필요합니다. [파일 체크포인팅](/ko/agent-sdk/file-checkpointing) 참조 |

625* **다음 턴에 적용됨**: `model`, `effortLevel`, `ultracode`, `permissions`, `hooks`, `skillOverrides`, `fastMode`, `awaySummaryEnabled`, `agent`. `agent`를 전환하면 해당 에이전트의 모델 재정의, 훅 및 시스템 프롬프트도 다음 턴에 적용됩니다.626* **다음 턴에 적용됨**: `model`, `effortLevel`, `ultracode`, `permissions`, `hooks`, `skillOverrides`, `fastMode`, `awaySummaryEnabled`, `agent`. `agent`를 전환하면 해당 에이전트의 모델 재정의, 훅 및 시스템 프롬프트도 다음 턴에 적용됩니다.

626* **세션 중 효과 없음**: 시스템 프롬프트 옵션입니다. 이들은 시작 시 한 번 해결되므로 실행 중인 세션은 호출이 성공하더라도 원본 값을 유지합니다. 이를 변경하려면 새 세션을 시작합니다.627* **세션 중 효과 없음**: 시스템 프롬프트 옵션입니다. 이들은 시작 시 한 번 해결되므로 실행 중인 세션은 호출이 성공하더라도 원본 값을 유지합니다. 이를 변경하려면 새 세션을 시작합니다.

627 628

629`effortLevel`은 [노력 수준](/ko/model-config#adjust-effort-level) 이름을 허용합니다. 또한 `"ultracode"`를 허용하며, 이는 세션을 `xhigh` 노력으로 실행하고 [ultracode](/ko/workflows#let-claude-decide-with-ultracode)를 켭니다. `Settings` 타입은 해당 값 없이 `effortLevel`을 선언하므로 TypeScript에서 동등한 `{ ultracode: true }`를 전달합니다. {/* min-version: 2.1.203 */}`ultracode` 값은 Claude Code v2.1.203 이상이 필요하며 설정 파일의 `effortLevel` 키가 아닌 `applyFlagSettings()`에서만 허용됩니다.

630

628값은 플래그 설정 계층에 기록되며, 이는 `query()`의 인라인 `settings` 옵션이 시작 시 채우는 계층과 동일합니다. 플래그 설정은 [설정 우선순위 순서](/ko/settings#settings-precedence)의 상단 근처에 있습니다: 사용자, 프로젝트 및 로컬 설정을 재정의하며, 관리되는 정책 설정만 이를 재정의할 수 있습니다. 이는 [우선순위 섹션](#settings-precedence)이 프로그래밍 방식의 옵션이라고 부르는 것과 동일한 계층입니다.631값은 플래그 설정 계층에 기록되며, 이는 `query()`의 인라인 `settings` 옵션이 시작 시 채우는 계층과 동일합니다. 플래그 설정은 [설정 우선순위 순서](/ko/settings#settings-precedence)의 상단 근처에 있습니다: 사용자, 프로젝트 및 로컬 설정을 재정의하며, 관리되는 정책 설정만 이를 재정의할 수 있습니다. 이는 [우선순위 섹션](#settings-precedence)이 프로그래밍 방식의 옵션이라고 부르는 것과 동일한 계층입니다.

629 632

630연속 호출은 최상위 키를 얕게 병합합니다. `{ permissions: {...} }`를 포함한 두 번째 호출은 이전 호출의 전체 `permissions` 객체를 대체하며 깊게 병합하지 않습니다. 플래그 계층에서 키를 지우고 낮은 우선순위 소스로 돌아가려면 해당 키에 `null`을 전달합니다. `undefined`를 전달하면 JSON 직렬화가 이를 삭제하므로 효과가 없습니다.633연속 호출은 최상위 키를 얕게 병합합니다. `{ permissions: {...} }`를 포함한 두 번째 호출은 이전 호출의 전체 `permissions` 객체를 대체하며 깊게 병합하지 않습니다. 플래그 계층에서 키를 지우고 낮은 우선순위 소스로 돌아가려면 해당 키에 `null`을 전달합니다. `undefined`를 전달하면 JSON 직렬화가 이를 삭제하므로 효과가 없습니다.

693 696

694이들은 클라이언트가 연결되기 전에 발급되었으며 여전히 회신을 기다리고 있는 요청입니다. SDK는 배열을 읽고 각 항목을 [`canUseTool`](#canusetool) 콜백으로 전달하며, 이는 전송 간격 후 [`reinitialize()`](#query-object)가 트리거하는 것과 동일한 재전달입니다. 반복된 요청 ID를 멱등성으로 처리합니다. 연결이 끊어지기 전에 콜백이 이미 받은 요청을 반복할 수 있기 때문입니다.697이들은 클라이언트가 연결되기 전에 발급되었으며 여전히 회신을 기다리고 있는 요청입니다. SDK는 배열을 읽고 각 항목을 [`canUseTool`](#canusetool) 콜백으로 전달하며, 이는 전송 간격 후 [`reinitialize()`](#query-object)가 트리거하는 것과 동일한 재전달입니다. 반복된 요청 ID를 멱등성으로 처리합니다. 연결이 끊어지기 전에 콜백이 이미 받은 요청을 반복할 수 있기 때문입니다.

695 698

699<h3 id="sdkcontrolinterruptresponse">

700 `SDKControlInterruptResponse`

701</h3>

702

703중단 수신입니다: [`interrupt()`](#query-object)가 [`SDKSystemMessage.capabilities`](#sdksystemmessage)에서 `interrupt_receipt_v1` 기능을 광고하는 CLI에서 해결되는 값입니다. Claude Code v2.1.205 이상이 필요합니다. 이전 CLI는 빈 성공 페이로드로 중단에 응답하므로 `interrupt()`는 `undefined`로 해결됩니다.

704

705```typescript theme={null}

706type SDKControlInterruptResponse = {

707 still_queued: string[];

708};

709```

710

711`still_queued`는 중단을 견디는 사용자 메시지의 UUID를 나열합니다: 대기열에 여전히 있는 메시지와 다음 턴을 위해 이미 제거되었지만 아직 중단으로 도달할 수 없는 배치입니다. 각각은 중단 후 자체 턴으로 실행되며, 먼저 취소하지 않는 한 실행됩니다. 수신을 사용하여 다시 보낼 것인지 결정합니다. 이미 나열된 메시지를 다시 보내면 중복 턴이 생성됩니다.

712

713다음 주의 사항으로 목록을 해석합니다:

714

715* UUID가 있는 메시지만 나타납니다. 빈 배열은 다른 것이 실행되지 않음을 의미하지 않습니다.

716* 메인 스레드 메시지만 나열됩니다. 서브에이전트로 주소 지정된 메시지는 범위를 벗어납니다.

717* 목록에는 클라이언트가 보낸 적이 없는 UUID (예: [예약된 작업](/ko/scheduled-tasks) 트리거)가 포함될 수 있습니다. 오류로 취급하는 대신 인식하지 못하는 UUID를 무시합니다.

718

719수신은 중단이 처리되는 순간에 찍은 스냅샷이며, 깨끗한 중단에서 중단된 턴의 [`SDKResultMessage`](#sdkresultmessage) 전에 도착합니다. 해당 결과 후 대기열을 검사하는 대신 수신을 읽습니다: 루프는 다음 대기 중인 턴을 즉시 시작하므로 결과 후 검사하는 대기열이 이미 변경되었습니다.

720

696<h3 id="agentdefinition">721<h3 id="agentdefinition">

697 `AgentDefinition`722 `AgentDefinition`

698</h3>723</h3>

1097 | SDKTaskStartedMessage1122 | SDKTaskStartedMessage

1098 | SDKTaskProgressMessage1123 | SDKTaskProgressMessage

1099 | SDKTaskUpdatedMessage1124 | SDKTaskUpdatedMessage

1125 | SDKBackgroundTasksChangedMessage

1100 | SDKSessionStateChangedMessage1126 | SDKSessionStateChangedMessage

1101 | SDKWorkerShuttingDownMessage1127 | SDKWorkerShuttingDownMessage

1102 | SDKCommandsChangedMessage1128 | SDKCommandsChangedMessage

1110 | SDKPromptSuggestionMessage1136 | SDKPromptSuggestionMessage

1111 | SDKAPIRetryMessage1137 | SDKAPIRetryMessage

1112 | SDKMirrorErrorMessage1138 | SDKMirrorErrorMessage

1113 | SDKInformationalMessage;1139 | SDKInformationalMessage

1140 | SDKConversationResetMessage;

1114```1141```

1115 1142

1116<h3 id="sdkassistantmessage">1143<h3 id="sdkassistantmessage">

1273 output_style: string;1300 output_style: string;

1274 skills: string[];1301 skills: string[];

1275 plugins: { name: string; path: string }[];1302 plugins: { name: string; path: string }[];

1303 capabilities?: string[];

1276};1304};

1277```1305```

1278 1306

1307{/* min-version: 2.1.205 */}

1308

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

1310

1311| 기능 | 의미 |

1312| ---------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |

1313| `interrupt_receipt_v1` | [`interrupt()`](#query-object)는 중단을 생존하는 대기 중인 메시지의 이름을 지정하는 [`SDKControlInterruptResponse`](#sdkcontrolinterruptresponse) 영수증으로 해결됩니다 |

1314

1279<h3 id="sdkpartialassistantmessage">1315<h3 id="sdkpartialassistantmessage">

1280 `SDKPartialAssistantMessage`1316 `SDKPartialAssistantMessage`

1281</h3>1317</h3>

1282 1318

1283스트리밍 부분 메시지 (`includePartialMessages`가 true일 때만).1319스트리밍 부분 메시지 (`includePartialMessages`가 true일 때만). `parent_tool_use_id` 필드는 항상 `null`입니다: 스트림 이벤트는 메인 세션에만 내보내집니다. 서브에이전트 속성을 위해 `parent_tool_use_id`를 전달하는 완전한 메시지를 사용하거나 [`forwardSubagentText`](#options)를 활성화하여 서브에이전트 텍스트와 생각을 완전한 메시지로 수신합니다.

1284 1320

1285```typescript theme={null}1321```typescript theme={null}

1286type SDKPartialAssistantMessage = {1322type SDKPartialAssistantMessage = {

1421type SDKMessageOrigin =1457type SDKMessageOrigin =

1422 | { kind: "human" }1458 | { kind: "human" }

1423 | { kind: "channel"; server: string }1459 | { kind: "channel"; server: string }

1424 | { kind: "peer"; from: string; name?: string; senderTaskId?: string }1460 | {

1461 kind: "peer";

1462 from: string;

1463 name?: string;

1464 senderTaskId?: string;

1465 body?: string;

1466 }

1425 | { kind: "task-notification" }1467 | { kind: "task-notification" }

1426 | { kind: "coordinator" }1468 | { kind: "coordinator" }

1427 | { kind: "auto-continuation" };1469 | { kind: "auto-continuation" };

1428```1470```

1429 1471

1430| `kind` | 의미 |1472| `kind` | 의미 |

1431| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |1473| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |

1434| `peer` | 다른 에이전트의 메시지입니다. 프로세스 내 [팀원](/ko/agent-teams)이 `SendMessage`를 통해 `main`으로 보내는 경우, `from`은 팀원의 이름이고 `senderTaskId`는 해당 작업 ID입니다. 다른 로컬 Claude Code 프로세스와 같은 교차 세션 피어의 경우, `from`은 발신자 주소이고 `senderTaskId`는 없습니다. `name` 필드는 예약되어 있습니다. |1476| `peer` | 다른 에이전트의 메시지입니다. 프로세스 내 [팀원](/ko/agent-teams)이 `SendMessage`를 통해 `main`으로 보내는 경우, `from`은 팀원의 이름이고 `senderTaskId`는 해당 작업 ID입니다. 다른 로컬 Claude Code 프로세스와 같은 교차 세션 피어의 경우, `from`은 발신자 주소이고 `senderTaskId`는 없습니다. {/* min-version: 2.1.205 */}`name` 및 `body`는 Claude Code v2.1.205 이상이 필요합니다. `name`은 발신자의 표시 이름이며 Claude Code에서 정규화됩니다: 유니코드 제어, 형식, 서로게이트 및 줄 또는 단락 구분자 코드 포인트를 제거한 다음 결과를 자르고 64개 코드 포인트로 제한하고 줄임표를 추가합니다. `body`는 피어 봉투가 제거된 디코딩된 메시지 본문이며, 모델이 보는 것과 바이트 정확합니다. 팀원 메시지의 경우 `body`는 항상 존재합니다. 교차 세션 피어의 경우 Claude Code에서 형성한 정확히 하나의 피어 봉투인 경우에만 존재합니다. `name` 및 `body`를 렌더링하고 메시지 텍스트를 다시 파싱하지 마십시오. |

1435| `task-notification` | 백그라운드 작업이 완료된 후 주입된 합성 턴입니다. [`SDKTaskNotificationMessage`](#sdktasknotificationmessage)를 참조하십시오. |1477| `task-notification` | 백그라운드 작업이 완료된 후 주입된 합성 턴입니다. [`SDKTaskNotificationMessage`](#sdktasknotificationmessage)를 참조하십시오. |

2357 2399

2358```typescript theme={null}2400```typescript theme={null}

2359type ExitPlanModeInput = {2401type ExitPlanModeInput = {

2402 /** Deprecated: no longer used. */

2360 allowedPrompts?: Array<{2403 allowedPrompts?: Array<{

2361 tool: "Bash";2404 tool: "Bash";

2362 prompt: string;2405 prompt: string;

2364};2407};

2365```2408```

2366 2409

2367계획 모드를 종료합니다. 선택적으로 계획을 구현하는 데 필요한 프롬프트 기반 권한을 지정합니다.2410계획 모드를 종료합니다. `allowedPrompts` 필드는 더 이상 사용되지 않으며 무시됩니다. Claude Code는 기존 호출자 및 트랜스크립트가 유효성을 검사하도록 여전히 수락합니다. v2.1.205 이전에는 계획을 구현하기 위한 프롬프트 기반 Bash 권한을 요청했습니다.

2368 2411

2369<h3 id="listmcpresources">2412<h3 id="listmcpresources">

2370 ListMcpResources2413 ListMcpResources

2408};2451};

2409```2452```

2410 2453

2411격리된 작업을 위한 임시 git worktree를 만들고 입력합니다. 새 worktree를 만드는 대신 현재 저장소의 기존 worktree로 전환하려면 `path`를 전달합니다. `name` 및 `path`는 상호 배타적입니다.2454격리된 작업을 위한 임시 git worktree를 만들고 입력합니다. 새 worktree를 만드는 대신 기존 worktree로 전환하려면 `path`를 전달합니다. 첫 번째 입력 시 대상은 현재 저장소의 등록된 worktree이거나, 다중 저장소 작업 공간에서 그 안에 중첩된 저장소여야 합니다. worktree 세션 내에서는 세션의 저장소의 `.claude/worktrees/` 아래에 있어야 합니다. `name` 및 `path`는 상호 배타적입니다.

2412 2455

2413<h2 id="tool-output-types">2456<h2 id="tool-output-types">

2414 도구 출력 타입2457 도구 출력 타입

3656};3699};

3657```3700```

3658 3701

3702<h3 id="sdkbackgroundtaskschangedmessage">

3703 `SDKBackgroundTasksChangedMessage`

3704</h3>

3705

3706라이브 백그라운드 작업 집합이 변경될 때마다 내보내집니다. 작업이 시작되거나, 완료되거나, 종료되거나, 포그라운드 에이전트가 백그라운드로 전환될 때입니다. `tasks` 배열은 전체 라이브 집합입니다. `task_started` 및 `task_notification` 이벤트를 쌍으로 지정하는 대신 각 페이로드로 캐시된 집합을 바꾸므로, 다음 멤버십 변경이 놓친 이벤트를 수정합니다.

3707

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

3709

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

3711

3712{/* min-version: 2.1.203 */}Claude Code v2.1.203 이상이 필요합니다.

3713

3714```typescript theme={null}

3715type SDKBackgroundTasksChangedMessage = {

3716 type: "system";

3717 subtype: "background_tasks_changed";

3718 tasks: {

3719 task_id: string;

3720 task_type: string;

3721 description: string;

3722 }[];

3723 uuid: UUID;

3724 session_id: string;

3725};

3726```

3727

3659<h3 id="sdkfilespersistedevent">3728<h3 id="sdkfilespersistedevent">

3660 `SDKFilesPersistedEvent`3729 `SDKFilesPersistedEvent`

3661</h3>3730</h3>

3745};3814};

3746```3815```

3747 3816

3817<h3 id="sdkconversationresetmessage">

3818 `SDKConversationResetMessage`

3819</h3>

3820

3821세션의 대화가 세션을 종료하지 않고 바뀔 때 내보내집니다. 예를 들어 `/clear` 후, 계획 모드 종료 시, 또는 새로운 대화가 시작될 때입니다. `new_conversation_id` 아래에 빈 트랜스크립트를 마운트하고 캐시된 세션 제목을 버리세요.

3822

3823```typescript theme={null}

3824type SDKConversationResetMessage = {

3825 type: "conversation_reset";

3826 new_conversation_id: UUID;

3827 uuid: UUID;

3828 session_id: string;

3829};

3830```

3831

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

3833

3748<h3 id="aborterror">3834<h3 id="aborterror">

3749 `AbortError`3835 `AbortError`

3750</h3>3836</h3>

agent-sdk/user-input.md +3 −1

Details

198</CodeGroup>198</CodeGroup>

199 199

200<Note>200<Note>

201 Python에서 `can_use_tool`은 [스트리밍 모드](/ko/agent-sdk/streaming-vs-single-mode)와 스트림을 열어 두기 위해 `{"continue_": True}`를 반환하는 `PreToolUse` 훅이 필요합니다. 이 훅이 없으면 권한 콜백이 호출되기 전에 스트림이 닫힙니다.201 Python에서 `can_use_tool`은 [스트리밍 모드](/ko/agent-sdk/streaming-vs-single-mode)가 필요합니다. `query(prompt=generator)` 또는 `ClaudeSDKClient.connect(prompt=async_iterable)`을 통해 유한한 메시지 스트림을 전달하면, 등록된 훅이나 프로세스 내 MCP 서버가 스트림을 열어 두지 않는 한 권한 콜백이 호출되기 전에 SDK가 입력 스트림을 닫습니다. 위의 예제는 `{"continue_": True}`를 반환하는 `PreToolUse` 훅으로 스트림을 열어 둡니다. 프롬프트 없이 연결하고 `ClaudeSDKClient.query()`를 통해 메시지를 보내면 스트림이 자동으로 열려 있으며 훅이 필요하지 않습니다.

202</Note>202</Note>

203 203

204이 예제는 `y` 이외의 모든 입력이 거부로 처리되는 y/n 흐름을 사용합니다. 실제로는 사용자가 요청을 수정하거나, 피드백을 제공하거나, Claude를 완전히 리디렉션할 수 있는 더 풍부한 UI를 구축할 수 있습니다. 응답할 수 있는 모든 방법은 [도구 요청에 응답](#respond-to-tool-requests)을 참조하십시오.204이 예제는 `y` 이외의 모든 입력이 거부로 처리되는 y/n 흐름을 사용합니다. 실제로는 사용자가 요청을 수정하거나, 피드백을 제공하거나, Claude를 완전히 리디렉션할 수 있는 더 풍부한 UI를 구축할 수 있습니다. 응답할 수 있는 모든 방법은 [도구 요청에 응답](#respond-to-tool-requests)을 참조하십시오.

6864. **답변 매핑**: 코드는 입력이 숫자(옵션의 레이블 사용)인지 자유 텍스트(텍스트 직접 사용)인지 확인합니다.6864. **답변 매핑**: 코드는 입력이 숫자(옵션의 레이블 사용)인지 자유 텍스트(텍스트 직접 사용)인지 확인합니다.

6875. **Claude에 반환**: 응답에는 원본 `questions` 배열과 `answers` 매핑이 모두 포함됩니다.6875. **Claude에 반환**: 응답에는 원본 `questions` 배열과 `answers` 매핑이 모두 포함됩니다.

688 688

689TypeScript 버전을 `ask.ts`로 저장하고 `npx tsx ask.ts`로 실행하거나, Python 버전을 `ask.py`로 저장하고 `python ask.py`로 실행합니다.

690

689<CodeGroup>691<CodeGroup>

690 ```python Python theme={null}692 ```python Python theme={null}

691 import asyncio693 import asyncio

agent-view.md +88 −38

Details

90 90

91```text theme={null}91```text theme={null}

92고정됨92고정됨

~~93 ✽ clawd walk cycle Write assets/sprites/clawd-walk.png 3m~~93 ✽ clawd walk cycle 걷기 사이클 스프라이트 프레임 그리기 3m

94 94

95검토 준비 완료95검토 준비 완료

~~96 ∙ jump physics Opened PR with collision fix #2048 2h~~96 ∙ jump physics 충돌 수정으로 PR 열기 #2048 2h

97 97

98입력 필요98입력 필요

~~99 ✻ power-up design needs input: double jump or wall climb? 1m~~99 ✻ power-up design 이중 점프 또는 벽 타기? 1m

100 100

101작업 중101작업 중

102 ✽ collision detection Edit src/physics/CollisionSystem.ts 2m102 ✽ collision detection CollisionSystem에 swept-AABB 검사 추가 2m

103 ✢ playtest level 3 run 12 · all checkpoints cleared in 4m103 ✢ playtest level 3 실행 12 · 모든 체크포인트 통과 4m 후

104 104

105완료됨105완료됨

106 ✻ title screen result: menu, options, and credits done 9m106 ✻ title screen 결과: 메뉴, 옵션 및 크레딧 완료 9m

107 ∙ sound effects result: 14 SFX exported to assets/audio 4h107 ∙ sound effects 결과: 14개 SFX를 assets/audio로 내보냄 4h

108 … 6 more108 … 6 more

109```109```

110 110

141 141

142세션 상태는 자동 업데이트 및 감독자 재시작을 통해 디스크에 유지됩니다. 세션은 머신이 절전 상태일 때도 보존됩니다. 프로세스는 깨어날 때 재개되고 감독자는 시간 간격을 유휴로 취급하는 대신 다시 연결됩니다. 종료하면 여전히 실행 중인 세션이 중지됩니다. 복구 방법은 [종료 후 세션이 실패로 표시됨](#sessions-show-as-failed-after-shutdown)을 참조하세요.142세션 상태는 자동 업데이트 및 감독자 재시작을 통해 디스크에 유지됩니다. 세션은 머신이 절전 상태일 때도 보존됩니다. 프로세스는 깨어날 때 재개되고 감독자는 시간 간격을 유휴로 취급하는 대신 다시 연결됩니다. 종료하면 여전히 실행 중인 세션이 중지됩니다. 복구 방법은 [종료 후 세션이 실패로 표시됨](#sessions-show-as-failed-after-shutdown)을 참조하세요.

143 143

144응답하지 않는 세션을 열 때 감독자는 프로세스를 다시 시작하고 세션은 중단된 응답을 중단된 위치에서 계속합니다. 머신이 응답 중에 절전 상태일 때 세션이 해당 상태에 빠질 수 있습니다. Claude Code v2.1.200 이상이 필요합니다.

145

144<h3 id="row-summaries">146<h3 id="row-summaries">

145 행 요약147 행 요약

146</h3>148</h3>

147 149

148각 행의 한 줄 요약은 [Haiku 클래스 모델](/ko/model-config)에 의해 생성되므로 행은 세션이 무엇을 하고 있는지, 무엇이 필요한지, 또는 트랜스크립트를 열지 않고도 무엇을 생성했는지 알려줄 수 있습니다. 세션이 적극적으로 작동하는 동안 요약은 최대 15초마다 한 번, 그리고 각 턴이 끝날 때 한 번 새로고침됩니다.150각 행의 한 줄 요약은 [Haiku 클래스 모델](/ko/model-config)에 의해 생성되므로 행은 세션이 무엇을 하고 있는지, 무엇이 필요한지, 또는 트랜스크립트를 열지 않고도 무엇을 생성했는지 알려줄 수 있습니다. 세션이 적극적으로 작동하는 동안 행 텍스트는 최대 15초마다 한 번, 세션의 최근 출력에서 모델 요청을 보내지 않고 업데이트되며, 각 턴이 끝날 때 모델이 새로운 요약을 작성합니다.

151

152작업 중인 행은 세션이 수행 중인 작업을 표시하고, 차단된 행은 요청하는 질문을 표시합니다. 긴 턴 동안 모델은 약 1분마다 요약을 다시 작성하며, 각 다시 작성 후 2배씩 기다려 최대 4분까지 기다리므로 바쁜 행이 오래된 요약을 계속 표시하지 않습니다. 텍스트는 64열에서 잘리며, [엿보기 패널](#peek-and-reply)을 열어 전체 문장을 읽습니다. v2.1.205 이전에는 작업 중인 행이 보고서 대신 원시 도구 호출을 표시할 수 있었으며, 병렬 작업 항목을 실행하는 세션은 텍스트 앞에 `2/5`와 같은 `done/total` 개수를 표시했습니다.

153

154목록이 [디렉토리별로 그룹화](#organize-the-list)될 때 요약은 `입력 필요 · 이중 점프 또는 벽 타기?`와 같은 색상이 지정된 단어로 세션의 상태로 시작합니다. 기본 상태 그룹화에서 그룹 헤더가 이미 상태를 명명하므로 행은 요약만 표시합니다. v2.1.205 이전에는 디렉토리 그룹화된 행에 상태 단어가 없었습니다.

149 155

150세션이 서브에이전트, 백그라운드 셸 명령 또는 모니터와 같은 두 개 이상의 병렬 작업 항목을 실행 중일 때, `2/5`와 같은 `done/total` 개수가 요약 텍스트 앞에 나타납니다.156전체 출력에 문자나 숫자가 없는 턴(예: 조용한 반복에서 단일 기호를 인쇄하는 [`/loop`](/ko/scheduled-tasks) 세션)은 행의 이전 요약과 상태를 유지합니다. v2.1.205 이전에는 해당 턴이 재분류되었으며 입력을 기다리는 세션을 `작업 중`으로 다시 뒤집을 수 있었습니다.

151 157

152각 새로고침은 일반 제공자를 통한 하나의 짧은 Haiku 클래스 요청이며, 세션 자체와 동일한 [데이터 사용 약관](/ko/data-usage)에 따라 청구되고 처리됩니다. Bedrock, Vertex AI, Microsoft Foundry 및 사용자 정의 게이트웨이와 같은 타사 제공자에서는 Haiku 모델이 구성되지 않은 경우 요청이 세션의 주 모델로 폴백됩니다. 이러한 제공자에서 이 요약에 대한 모델을 선택하려면 [`ANTHROPIC_DEFAULT_HAIKU_MODEL`](/ko/model-config#environment-variables)을 설정합니다.158턴 끝 요약 및 각 중간 다시 작성은 일반 제공자를 통한 하나의 짧은 Haiku 클래스 요청이며, 세션 자체와 동일한 [데이터 사용 약관](/ko/data-usage)에 따라 청구되고 처리됩니다. Amazon Bedrock, Google Cloud의 Agent Platform, Microsoft Foundry 및 사용자 정의 게이트웨이와 같은 타사 제공자에서는 Haiku 모델이 구성되지 않은 경우 요청이 세션의 주 모델로 폴백됩니다. 이러한 제공자에서 이 요약에 대한 모델을 선택하려면 [`ANTHROPIC_DEFAULT_HAIKU_MODEL`](/ko/model-config#environment-variables)을 설정합니다.

153 159

154<h3 id="pull-request-status">160<h3 id="pull-request-status">

155 풀 리퀘스트 상태161 풀 리퀘스트 상태

156</h3>162</h3>

157 163

158세션이 풀 리퀘스트를 열면 `#1234` 레이블이 행의 오른쪽 가장자리에 나타나며, 하이퍼링크를 지원하는 터미널에서 풀 리퀘스트에 연결됩니다. 세션에 후속 조치를 보낼 때 레이블이 유지되므로 행이 라이브 진행 상황으로 되돌아가는 동안 풀 리퀘스트가 표시된 상태로 유지됩니다. 백그라운드 세션이 worktree에서 변경 사항을 격리하면 이러한 풀 리퀘스트를 직접 열며, [파일 편집이 격리되는 방식](#how-file-edits-are-isolated)은 이것이 발생하는 시기와 세션이 요청 없이 절대 수행하지 않는 작업을 다룹니다.164세션이 풀 리퀘스트를 열면 `#1234` 레이블이 행의 오른쪽 가장자리에 나타나며, 하이퍼링크를 지원하는 터미널에서 풀 리퀘스트에 연결됩니다. 레이블은 세션에 후속 조치를 보낼 때 유지되므로 행이 라이브 진행 상황으로 되돌아가는 동안 풀 리퀘스트가 표시된 상태로 유지됩니다. 백그라운드 세션이 worktree에서 변경 사항을 격리하면 이러한 풀 리퀘스트를 직접 열며, [파일 편집이 격리되는 방식](#how-file-edits-are-isolated)은 이것이 발생하는 시기와 세션이 요청 없이 절대 수행하지 않는 작업을 다룹니다.

165

166기존 풀 리퀘스트에서 작업하는 세션은 동일한 방식으로 연결됩니다. `gh`로 편집, 댓글, 닫기 또는 풀 리퀘스트를 준비 완료로 표시하면 명령의 자체 출력이 명명하는 풀 리퀘스트에 연결되므로, 캡처된 출력이 풀 리퀘스트를 명명하지 않는 `gh` 명령은 링크를 생성하지 않습니다. `gh pr merge`는 일반적인 경우이며, 결과를 대화형 터미널에만 인쇄하기 때문입니다. `gh pr checkout`으로 풀 리퀘스트를 체크아웃하거나 열린 풀 리퀘스트가 있는 브랜치로 푸시하면 대신 `gh pr view`로 해당 브랜치를 조회하여 연결합니다. v2.1.205 이전에는 세션이 생성하거나 체크아웃한 풀 리퀘스트만 연결되었으며, 푸시는 로컬 브랜치 이름이 일치할 때만 연결했습니다.

167

168Claude Code는 명령의 출력이 인라인 제한을 초과할 때 파일에 저장된 부분을 포함한 전체 명령 출력에서 풀 리퀘스트를 읽습니다. v2.1.205 이전에는 출력이 약 30,000자를 초과하는 Bash 호출에서 생성된 풀 리퀘스트가 연결되지 않았습니다.

159 169

160세션이 둘 이상의 풀 리퀘스트를 열었을 때 레이블은 `3 PRs`와 같은 개수를 표시하며, 가장 주의가 필요한 열린 풀 리퀘스트로 색상이 지정됩니다. [엿보기 패널](#peek-and-reply)을 열어 모두 확인합니다.170세션이 둘 이상의 풀 리퀘스트에 연결되면 레이블은 `3 PRs`와 같은 개수를 표시하며, 가장 주의가 필요한 열린 풀 리퀘스트로 색상이 지정됩니다. [엿보기 패널](#peek-and-reply)을 열어 모두 확인합니다.

161 171

162풀 리퀘스트 번호는 상태에 따라 색상이 지정됩니다:172풀 리퀘스트 번호는 상태에 따라 색상이 지정됩니다:

163 173

174 엿보기 및 답변184 엿보기 및 답변

175</h3>185</h3>

176 186

177선택된 행에서 `Space`를 눌러 엿보기 패널을 엽니다. 세션이 필요로 하는 것, 최근 출력 및 열린 풀 리퀘스트를 보여줍니다. 대부분의 경우 이것으로 충분하며 전체 트랜스크립트를 열 필요가 없습니다.187선택된 행에서 `Space`를 눌러 엿보기 패널을 엽니다. 세션의 전체 상태 문장(행이 잘린)과 마지막 변경 이후 경과 시간, 그리고 세션에 연결된 모든 풀 리퀘스트로 열립니다. 입력을 기다리는 세션의 경우 요청하는 정확한 질문도 답변 입력 위에 나타납니다. 대부분의 경우 엿보기 패널로 충분하며 전체 트랜스크립트를 열 필요가 없습니다.

178 188

179세션이 병렬 작업 항목을 실행 중일 때, 패널은 또한 가장 오래 실행 중인 항목의 이름과 실행 시간을 표시하므로 연결하지 않고도 세션이 기다리는 것을 볼 수 있습니다.189v2.1.205 이전에는 패널이 다른 것을 표시할 것이 없을 때만 상태 문장을 반복했으며 가장 오래 실행 중인 병렬 작업 항목을 명명했습니다.

180 190

181엿보기 패널에 답변을 입력하고 `Enter`를 눌러 해당 세션으로 전송합니다. 세션이 객관식 질문을 하는 경우 엿보기 패널은 옵션을 표시하고 숫자 키를 눌러 하나를 선택할 수 있습니다. 다른 차단된 세션의 경우 `Tab`을 눌러 입력을 편집하기 전에 제안된 답변으로 채웁니다. 답변 앞에 `!`를 붙여 Bash 명령을 대신 전송합니다.191엿보기 패널에 답변을 입력하고 `Enter`를 눌러 해당 세션으로 전송합니다. 세션이 객관식 질문을 하는 경우 엿보기 패널은 옵션을 표시하고 숫자 키를 눌러 하나를 선택할 수 있습니다. 다른 차단된 세션의 경우 `Tab`을 눌러 입력을 편집하기 전에 제안된 답변으로 채웁니다. 답변 앞에 `!`를 붙여 Bash 명령을 대신 전송합니다.

182 192

206 216

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

208 218

209행은 대화 기록이 없는 새로운 세션에서도 생성되므로 `→`는 이를 반환합니다. 해당 행이 유일한 경우 에이전트 뷰는 아래에 온보딩 힌트를 표시합니다.21910초 제한은 [서브에이전트](/ko/sub-agents)가 실행 중일 때 적용되지 않습니다. Claude Code는 계속 기다려서 작업이 이월되고, 기다리는 동안 `Still backgrounding after the current tool` 알림을 표시합니다. `←`를 다시 눌러 대기 없이 백그라운드로 보내면 서브에이전트가 처음부터 다시 시작됩니다. v2.1.203 이전에는 대기가 10초 후 종료되고 실행 중인 서브에이전트가 경고 없이 처음부터 다시 시작되었습니다.

220

221행은 대화 기록이 없는 새로운 세션에서도 생성되므로 `→`는 이를 반환합니다. {/* max-version: 2.1.202 */}v2.1.203 이전에는 해당 행이 유일한 경우 에이전트 뷰가 아래에 온보딩 힌트를 표시했습니다.

210 222

211`/config`에서 `leftArrowOpensAgents` 설정으로 이 단축키를 끌 수 있습니다.223`/config`에서 `leftArrowOpensAgents` 설정으로 이 단축키를 끌 수 있습니다.

212 224

302* `/model`은 [디스패치 모델](#set-the-model)을 설정합니다314* `/model`은 [디스패치 모델](#set-the-model)을 설정합니다

303* {/* min-version: 2.1.198 */}v2.1.198부터 `/login`은 세션에 연결하지 않고 다시 로그인할 수 있도록 로그인 대화 상자를 엽니다315* {/* min-version: 2.1.198 */}v2.1.198부터 `/login`은 세션에 연결하지 않고 다시 로그인할 수 있도록 로그인 대화 상자를 엽니다

304 316

305스킬, 사용자 정의 명령 및 `/init`과 같은 프롬프트 확장 기본 제공 명령은 새로운 백그라운드 세션으로 첫 번째 프롬프트로 전송됩니다. 다른 기본 제공 명령은 대신 `세션에 연결하여 실행` 힌트를 표시합니다.317스킬, 사용자 정의 명령 및 `/init`과 같은 프롬프트 확장 기본 제공 명령은 새로운 백그라운드 세션으로 첫 번째 프롬프트로 전송됩니다. 다른 기본 제공 명령은 대신 `세션에 연결하여 실행` 힌트를 표시합니다. {/* min-version: 2.1.203 */}입력한 모든 내용은 힌트 옆의 입력에 유지되므로 편집할 수 있습니다. v2.1.203 이전에는 힌트가 입력을 지웠고 입력한 텍스트가 손실되었습니다.

306 318

307반복되는 작업을 [스킬](/ko/skills)로 패키징하면 프롬프트를 다시 입력하지 않고 에이전트 뷰에서 동일한 워크플로우를 여러 번 시작할 수 있습니다.319반복되는 작업을 [스킬](/ko/skills)로 패키징하면 프롬프트를 다시 입력하지 않고 에이전트 뷰에서 동일한 워크플로우를 여러 번 시작할 수 있습니다.

308 320

315새로운 세션은 에이전트 뷰를 연 디렉토리에서 실행됩니다. 다른 디렉토리를 대상으로 하려면 다음 중 하나를 사용합니다:327새로운 세션은 에이전트 뷰를 연 디렉토리에서 실행됩니다. 다른 디렉토리를 대상으로 하려면 다음 중 하나를 사용합니다:

316 328

317* 해당 디렉토리에서 `claude agents`를 엽니다.329* 해당 디렉토리에서 `claude agents`를 엽니다.

318* 상위 디렉토리에서 `claude agents`를 열고 프롬프트에서 `@<repo>`로 하위 저장소를 언급하여 세션을 거기서 실행합니다. `@`를 입력하면 실행 디렉토리 아래 한 수준의 git 저장소와 이미 세션이 있는 모든 디렉토리가 나열됩니다. 이름에 공백이 포함된 디렉토리는 나열되지 않습니다.330* 상위 디렉토리에서 `claude agents`를 열고 프롬프트에서 `@<repo>`로 하위 저장소를 언급합니다. `@`를 입력하면 이러한 대상이 나열됩니다:

331

332 * 실행 디렉토리 아래 한 수준의 Git 저장소

333 * 실행한 저장소의 등록된 [git worktrees](/ko/worktrees)로, 디렉토리 트리 내부에 있으며, 체크아웃된 브랜치로 레이블이 지정됩니다. `git worktree add ../feature`와 같이 저장소 외부에 추가된 Worktree는 나열되지 않습니다

334 * 이미 목록에 세션이 있는 모든 디렉토리

335

336 이름에 공백이 포함된 디렉토리는 나열되지 않습니다. {/* min-version: 2.1.203 */}v2.1.203 이전에는 등록된 worktree가 나열되지 않았으므로 worktree로 디스패치하려면 해당 worktree의 디렉토리에서 `claude --bg`를 실행해야 했습니다.

319* 셸에서 디렉토리로 `cd`하고 `claude --bg "<prompt>"`를 실행합니다.337* 셸에서 디렉토리로 `cd`하고 `claude --bg "<prompt>"`를 실행합니다.

320 338

321에이전트 뷰가 디렉토리별로 그룹화되면 강조된 행의 디렉토리가 디스패치 대상이 되므로 그룹으로 스크롤하고 경로를 다시 입력하지 않고 디스패치할 수 있습니다.339에이전트 뷰가 디렉토리별로 그룹화되면 강조된 행의 디렉토리가 디스패치 대상이 되므로 그룹으로 스크롤하고 경로를 다시 입력하지 않고 디스패치할 수 있습니다.

425 443

426git 저장소 외부에서 세션은 작업 디렉토리에 직접 쓰며 서로 격리되지 않으므로 동일한 파일을 편집하는 병렬 세션을 디스패치하지 않도록 합니다. 다른 버전 제어 시스템을 사용하는 경우 [`WorktreeCreate` 훅](/ko/worktrees#non-git-version-control)을 구성하면 Claude는 git에 대해 수행하는 것과 동일한 방식으로 편집을 격리합니다.444git 저장소 외부에서 세션은 작업 디렉토리에 직접 쓰며 서로 격리되지 않으므로 동일한 파일을 편집하는 병렬 세션을 디스패치하지 않도록 합니다. 다른 버전 제어 시스템을 사용하는 경우 [`WorktreeCreate` 훅](/ko/worktrees#non-git-version-control)을 구성하면 Claude는 git에 대해 수행하는 것과 동일한 방식으로 편집을 격리합니다.

427 445

428에이전트 뷰에서 세션을 삭제하면(`Ctrl+X` 두 번) Claude가 생성한 worktree가 제거되며, 커밋되지 않은 변경 사항도 포함되므로 유지하려는 변경 사항을 먼저 병합하거나 푸시합니다. 셸에서 [`claude rm`](#manage-sessions-from-the-shell)으로 삭제하면 커밋되지 않은 변경 사항이 있는 worktree를 유지하고 경로를 인쇄하므로 직접 정리할 수 있습니다. 직접 생성한 worktree이고 세션을 시작한 경우 어느 쪽이든 그대로 유지됩니다.446훅이 git 저장소가 아닌 디렉토리에서 실패하면 세션은 해당 디렉토리에 대한 격리를 건너뛰고 작업 디렉토리를 제자리에서 편집합니다. git 저장소 내부에서는 세션이 격리될 때까지 쓰기가 차단됩니다. v2.1.203 이전에는 이 상태의 백그라운드 세션이 파일을 편집할 수 없었습니다: 격리될 때까지 모든 쓰기가 거부되었고 훅은 해당 디렉토리를 격리할 수 없었습니다.

447

448에이전트 뷰에서 `Ctrl+X` 두 번으로 세션을 삭제하면 Claude가 생성한 worktree가 제거되며, 커밋되지 않은 변경 사항도 포함되므로 유지하려는 변경 사항을 먼저 병합하거나 푸시합니다. 셸에서 [`claude rm`](#manage-sessions-from-the-shell)으로 삭제하면 커밋되지 않은 변경 사항이 있는 worktree를 유지하고 경로를 인쇄하므로 직접 정리할 수 있습니다. 직접 생성한 worktree이고 세션을 시작한 경우 어느 쪽이든 그대로 유지됩니다.

429 449

430세션의 worktree 경로를 찾으려면 세션을 엿보거나 연결하고 작업 디렉토리를 확인합니다.450세션의 worktree 경로를 찾으려면 세션을 엿보거나 연결하고 작업 디렉토리를 확인합니다.

431 451

432백그라운드 세션이 생성하는 [서브에이전트](/ko/sub-agents)는 세션의 작업 디렉토리를 상속하므로 파일 편집은 세션의 worktree가 아닌 작업 복사본에 저장됩니다. 서브에이전트에 자신의 별도 worktree를 제공하려면 프론트매터에서 [`isolation: worktree`](/ko/sub-agents#supported-frontmatter-fields)를 설정하거나 생성할 때 `isolation: "worktree"`를 전달합니다.452백그라운드 세션이 생성하는 [서브에이전트](/ko/sub-agents)는 세션의 작업 디렉토리를 상속하므로 파일 편집은 세션의 worktree에 저장됩니다. 서브에이전트에 자신의 별도 worktree를 제공하려면 프론트매터에서 [`isolation: worktree`](/ko/sub-agents#supported-frontmatter-fields)를 설정하거나 생성할 때 `isolation: "worktree"`를 전달합니다.

433 453

434v2.1.198부터 worktree에서 코드 변경을 격리한 백그라운드 세션은 또한 커밋하고, 자신의 브랜치를 푸시하고, 멈추지 않고 초안 풀 리퀘스트를 엽니다. [`#N` 레이블](#pull-request-status)은 풀 리퀘스트가 열릴 때 행에 나타납니다. `main` 또는 `master`로 푸시하지 않으며, 강제 푸시하거나 병합하지 않으며, 풀 리퀘스트를 열지 말도록 지시했거나 저장소에 원격이 없을 때 풀 리퀘스트를 건너뜁니다.454v2.1.198부터 worktree에서 코드 변경을 격리한 백그라운드 세션은 또한 커밋하고, 자신의 브랜치를 푸시하고, 멈추지 않고 초안 풀 리퀘스트를 엽니다. [`#N` 레이블](#pull-request-status)은 풀 리퀘스트가 열릴 때 행에 나타납니다. `main` 또는 `master`로 푸시하지 않으며, 강제 푸시하거나 병합하지 않으며, 풀 리퀘스트를 열지 말도록 지시했거나 저장소에 원격이 없을 때 풀 리퀘스트를 건너뜁니다.

435 455

464 484

465백그라운드 세션은 실행되는 디렉토리에서 [설정](/ko/settings)을 읽으며, 마치 거기서 `claude`를 시작한 것처럼 동일합니다. 여기에는 프로젝트 설정의 [`env` 값](/ko/settings#available-settings)이 포함되므로 거기에 설정된 `ANTHROPIC_MODEL` 또는 공급자 변수가 해당 디렉토리의 백그라운드 세션에 적용됩니다.485백그라운드 세션은 실행되는 디렉토리에서 [설정](/ko/settings)을 읽으며, 마치 거기서 `claude`를 시작한 것처럼 동일합니다. 여기에는 프로젝트 설정의 [`env` 값](/ko/settings#available-settings)이 포함되므로 거기에 설정된 `ANTHROPIC_MODEL` 또는 공급자 변수가 해당 디렉토리의 백그라운드 세션에 적용됩니다.

466 486

467`CLAUDE_CODE_USE_BEDROCK` 또는 `CLAUDE_CODE_USE_VERTEX`와 같은 클라우드 공급자 선택 및 `ANTHROPIC_DEFAULT_*_MODEL` 별칭은 세션을 디스패치한 셸을 따릅니다. `ANTHROPIC_BASE_URL` 및 쌍을 이루는 `ANTHROPIC_AUTH_TOKEN`과 같은 게이트웨이 엔드포인트 변수는 따르지 않습니다. 백그라운드 세션이 공급자 설정 및 자격 증명을 소싱하는 방법에 대해서는 [감독자 프로세스](#the-supervisor-process)를 참조하십시오.487`CLAUDE_CODE_USE_BEDROCK` 또는 `CLAUDE_CODE_USE_VERTEX`와 같은 클라우드 공급자 선택 및 `ANTHROPIC_DEFAULT_*_MODEL` 별칭은 세션을 디스패치한 셸을 따릅니다. 게이트웨이 `ANTHROPIC_BASE_URL`은 해당 셸에서 내보내진 경우 따르며, 감독자가 동일한 게이트웨이 환경으로 실행되고 세션이 디스패치한 디렉토리에서 실행되거나 `←` 또는 `/background`로 백그라운드로 이동한 자신의 세션일 때 `ANTHROPIC_CUSTOM_HEADERS`와 함께 따릅니다. 이는 첫 번째 셸이 에이전트 뷰를 열거나 백그라운드 세션을 디스패치할 때 게이트웨이 셸인 정상적인 경우입니다. `@repo` 또는 `--cwd`로 다른 디렉토리로 디스패치하면 셸의 게이트웨이를 전달하지 않습니다. 해당 프로젝트의 [설정](/ko/settings)이 엔드포인트를 제공합니다. 백그라운드 세션이 공급자 설정 및 자격 증명을 소싱하는 방법에 대해서는 [감독자 프로세스](#the-supervisor-process)를 참조하십시오.

468 488

469[권한 모드](/ko/permissions)는 세션을 시작한 방식에 따라 달라집니다. `/bg` 또는 `←`로 기존 세션을 백그라운드로 이동하면 현재 권한 모드가 유지되므로 `acceptEdits` 또는 `auto`로 전환한 세션은 분리 후에도 해당 모드에 유지됩니다. 에이전트 뷰 입력에서 디스패치하거나 셸에서 `claude --bg`를 실행하면 해당 디렉토리의 설정에서 `defaultMode`를 사용하거나 디스패치된 [서브에이전트의 프론트매터](/ko/sub-agents#supported-frontmatter-fields)에서 `permissionMode`를 사용합니다.489[권한 모드](/ko/permissions)는 세션을 시작한 방식에 따라 달라집니다. `/bg` 또는 `←`로 기존 세션을 백그라운드로 이동하면 현재 권한 모드가 유지되므로 `acceptEdits` 또는 `auto`로 전환한 세션은 분리 후에도 해당 모드에 유지됩니다. 에이전트 뷰 입력에서 디스패치하거나 셸에서 `claude --bg`를 실행하면 해당 디렉토리의 설정에서 `defaultMode`를 사용하거나 디스패치된 [서브에이전트의 프론트매터](/ko/sub-agents#supported-frontmatter-fields)에서 `permissionMode`를 사용합니다.

470 490

471권한 모드, 모델 및 노력은 백그라운드 세션이 시작된 방식과 함께 [구성 플래그](#from-inside-a-session)와 함께 감독자가 나중에 [세션의 프로세스를 중지하고 다시 시작](#the-supervisor-process)할 때 유지됩니다. `claude --bg --dangerously-skip-permissions` 또는 `claude --bg --permission-mode bypassPermissions`로 실행한 세션은 디렉토리의 `defaultMode`로 폴백하는 대신 해당 재시작 후 `bypassPermissions`에 유지되며, `/model` 또는 `/effort`로 세션 중에 변경한 모델 또는 노력은 유지됩니다.491권한 모드, 모델 및 노력은 백그라운드 세션이 시작된 방식과 함께 [구성 플래그](#from-inside-a-session)와 함께 감독자가 나중에 [세션의 프로세스를 중지하고 다시 시작](#the-supervisor-process)할 때 유지됩니다. `claude --bg --dangerously-skip-permissions` 또는 `claude --bg --permission-mode bypassPermissions`로 실행한 세션은 디렉토리의 `defaultMode`로 폴백하는 대신 해당 재시작 후 `bypassPermissions`에 유지되며, `/model` 또는 `/effort`로 세션 중에 변경한 모델 또는 노력은 유지됩니다.

472 492

493[`effortLevel` 설정](/ko/settings#available-settings)에서 가져온 노력은 `--effort` 또는 `/effort`에서 가져온 것이 아니므로 디스패치에서 고정되지 않습니다: 세션을 위해 시작된 각 프로세스는 설정을 다시 읽으므로 `settings.json`에서 `effortLevel`을 편집하면 `←` 또는 `/bg`로 백그라운드로 이동한 세션과 이후 재시작에 도달합니다. v2.1.203 이전에는 세션을 백그라운드로 이동하면 설정 파생 노력을 `--effort`를 전달한 것처럼 기록했으므로 나중의 `effortLevel` 편집은 도달하지 않았습니다.

494

495[`/rename`](/ko/commands) 또는 `Ctrl+R`로 설정한 이름도 해당 재시작 전체에서 유지되므로 [`claude --resume <name>`](/ko/sessions#name-your-sessions)은 여전히 세션을 해결합니다. v2.1.202 이전에는 재시작이 세션을 디스패치된 이름으로 되돌렸고 새 이름은 해결을 중지했습니다.

496

473에이전트 뷰를 열 때 `--permission-mode`, `--model`, `--effort` 또는 `--agent` 중 하나를 전달하여 에이전트 뷰에서 디스패치하는 모든 세션에 대한 기본값을 설정합니다:497에이전트 뷰를 열 때 `--permission-mode`, `--model`, `--effort` 또는 `--agent` 중 하나를 전달하여 에이전트 뷰에서 디스패치하는 모든 세션에 대한 기본값을 설정합니다:

474 498

475```bash theme={null}499```bash theme={null}

484 508

485이러한 플래그가 없으면 세션은 해당 디렉토리의 설정에서 `defaultMode`를 사용하거나 디스패치된 [서브에이전트의 프론트매터](/ko/sub-agents#supported-frontmatter-fields)에서 `permissionMode`를 사용하며, 에이전트 뷰 헤더에 표시된 모델을 사용합니다.509이러한 플래그가 없으면 세션은 해당 디렉토리의 설정에서 `defaultMode`를 사용하거나 디스패치된 [서브에이전트의 프론트매터](/ko/sub-agents#supported-frontmatter-fields)에서 `permissionMode`를 사용하며, 에이전트 뷰 헤더에 표시된 모델을 사용합니다.

486 510

487`bypassPermissions` 또는 `auto`를 사용하는 것은 대화형으로 한 번 실행하여 해당 모드를 수락할 때까지 거부됩니다. 이러한 모드는 감시하지 않는 세션이 승인 없이 작동하도록 허용하기 때문입니다. 이는 `claude agents`에 모드를 전달하든 `claude --bg --permission-mode`에 전달하든 동일하게 적용됩니다. `--allow-dangerously-skip-permissions`를 전달하면 동일한 면책 조항을 표시하고, 수락하면 `bypassPermissions`를 해당 세션의 `Shift+Tab` 사이클에서 사용 가능하게 만듭니다.511`bypassPermissions`를 `claude --bg --permission-mode`와 함께 사용하는 것은 대화형으로 한 번 실행하여 해당 모드를 수락할 때까지 거부됩니다. 이러한 모드는 감시하지 않는 세션이 승인 없이 작동하도록 허용하기 때문입니다. `claude agents`에 `--dangerously-skip-permissions` 또는 `--permission-mode bypassPermissions`를 전달하면 이전에 수락하지 않은 경우 동일한 면책 조항을 표시하고, 수락하면 해당 세션에서 시작하지 않고 `bypassPermissions`를 `Shift+Tab` 사이클에서 사용 가능하게 만듭니다. `--allow-dangerously-skip-permissions`를 전달하면 동일한 면책 조항을 표시하고, 수락하면 `bypassPermissions`를 해당 세션의 `Shift+Tab` 사이클에서 사용 가능하게 만듭니다.

488 512

489<h3 id="settings-plugins-and-mcp-servers">513<h3 id="settings-plugins-and-mcp-servers">

490 설정, 플러그인 및 MCP 서버514 설정, 플러그인 및 MCP 서버

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

530 554

555***

556

557title: "백그라운드 세션이 호스팅되는 방식"

558description: "백그라운드 세션이 감독자 프로세스에 의해 호스팅되고 관리되는 방식, 상태 저장 위치, 에이전트 뷰 비활성화 방법을 알아봅니다."

559-------------------------------------------------------------------------------------

560

531<h2 id="how-background-sessions-are-hosted">561<h2 id="how-background-sessions-are-hosted">

532 백그라운드 세션이 호스팅되는 방식562 백그라운드 세션이 호스팅되는 방식

533</h2>563</h2>

544 574

545감독자 및 세션은 대화형 세션과 동일한 저장된 자격 증명으로 인증하고 모델 API 이상의 추가 네트워크 연결을 하지 않습니다. `CLAUDE_CODE_USE_BEDROCK` 및 `ANTHROPIC_DEFAULT_*_MODEL` 별칭과 같은 공급자 선택 변수는 각 세션을 디스패치한 셸에서 읽혀지고 해당 워커에 적용됩니다.575감독자 및 세션은 대화형 세션과 동일한 저장된 자격 증명으로 인증하고 모델 API 이상의 추가 네트워크 연결을 하지 않습니다. `CLAUDE_CODE_USE_BEDROCK` 및 `ANTHROPIC_DEFAULT_*_MODEL` 별칭과 같은 공급자 선택 변수는 각 세션을 디스패치한 셸에서 읽혀지고 해당 워커에 적용됩니다.

546 576

547백그라운드 세션은 `ANTHROPIC_BASE_URL`, 동등한 Bedrock, Vertex 및 Foundry 기본 URL 변수, 또는 감독자를 시작한 셸이나 디스패칭 셸에서 쌍을 이루는 `ANTHROPIC_AUTH_TOKEN`과 같은 게이트웨이 엔드포인트 변수를 상속하지 않습니다. 세션은 저장된 자격 증명과 프로젝트 디렉토리의 [설정](/ko/settings)에 있는 `env` 값을 사용합니다. 프로젝트의 백그라운드 세션을 [LLM 게이트웨이](/ko/llm-gateway)로 지정하려면 셸에서 내보내는 대신 해당 프로젝트의 `.claude/settings.json` `env` 블록에 `ANTHROPIC_BASE_URL`을 설정합니다.577디스패칭 셸의 `PATH`는 워커에 동일한 방식으로 적용되므로 세션이 실행하는 셸 명령은 터미널에서 사용하는 것과 동일한 도구를 찾습니다. v2.1.203 이전에는 백그라운드 세션이 감독자를 처음 시작한 셸의 `PATH`를 유지했으므로 그 이후로 `PATH`에 추가된 도구가 누락될 수 있었으며, 특히 Windows에서 그러했습니다.

578

579백그라운드 세션은 `ANTHROPIC_BASE_URL` 또는 동등한 Amazon Bedrock, Google Cloud의 Agent Platform, Microsoft Foundry 기본 URL 변수와 같은 게이트웨이 엔드포인트 변수를 감독자를 시작한 셸에서 상속하지 않습니다. 디스패치하는 셸에서 게이트웨이를 내보내지 않으면 세션은 저장된 자격 증명과 프로젝트 디렉토리의 [설정](/ko/settings)에 있는 `env` 값을 사용합니다. 프로젝트의 모든 세션을 [LLM 게이트웨이](/ko/llm-gateway)로 지정하려면 해당 프로젝트의 `.claude/settings.json` `env` 블록에 `ANTHROPIC_BASE_URL`을 설정합니다.

580

581{/* min-version: 2.1.203 */}디스패치하는 셸에서 내보낸 게이트웨이 `ANTHROPIC_BASE_URL`은 해당 세션의 워커에 도달하며, `ANTHROPIC_CUSTOM_HEADERS`와 함께 내보낸 자격 증명도 함께 도달합니다. 단, 감독자가 동일한 게이트웨이가 있는 환경에서 시작된 경우입니다. 감독자는 에이전트 뷰를 열거나 백그라운드 세션을 디스패치하는 첫 번째 셸에서 환경을 캡처하므로 게이트웨이 셸에서 시작하면 해당 환경을 얻습니다. 포워드는 또한 디스패치하는 디렉토리 또는 `←` 또는 `/background`로 백그라운드된 자신의 세션으로 디스패치된 세션에만 적용됩니다. `@repo` 또는 `--cwd`로 다른 디렉토리로 디스패치하면 셸의 게이트웨이를 전달하지 않으며, 해당 프로젝트의 `settings.json` `env` 블록이 엔드포인트를 대신 제공합니다. 감독자의 환경이 다른 게이트웨이를 전달하거나 없으면 워커는 한 환경의 자격 증명을 다른 환경의 엔드포인트와 혼합하는 대신 기본 엔드포인트에 대해 저장된 자격 증명을 유지합니다. v2.1.203 이전에는 디스패칭 셸의 `ANTHROPIC_BASE_URL`이 삭제되었지만 함께 내보낸 `ANTHROPIC_API_KEY`는 유지되었으므로 게이트웨이의 키가 기본 엔드포인트로 전송되었고 모든 요청이 401로 실패했습니다.

582

583포워드된 엔드포인트는 해당 라이브 프로세스에만 적용되며 디스크에 기록되지 않습니다. 감독자가 유휴 세션을 중지하고 나중에 다시 시작할 때 다시 시작된 프로세스는 설정에서 엔드포인트를 다시 읽습니다. 게이트웨이 `ANTHROPIC_AUTH_TOKEN`을 사용하면 저장된 자격 증명으로 폴백되고, 게이트웨이 발급 `ANTHROPIC_API_KEY`를 사용하면 게이트웨이가 설정에 설정될 때까지 인증에 실패할 수 있습니다.

548 584

549각 백그라운드 세션은 자체 Claude Code 프로세스이며 터미널이 아닌 감독자에 의해 관리됩니다. 적극적으로 작업 중이거나, 입력을 기다리거나, 터미널이 연결된 세션은 프로세스를 실행 상태로 유지합니다. 실행 중인 백그라운드 셸 명령, 서브에이전트, 동적 워크플로우 또는 모니터는 활성 작업으로 간주되므로 개발 서버와 같은 장기 실행 프로세스는 세션을 활성 상태로 유지합니다.585각 백그라운드 세션은 자체 Claude Code 프로세스이며 터미널이 아닌 감독자에 의해 관리됩니다. 적극적으로 작업 중이거나, 입력을 기다리거나, 터미널이 연결된 세션은 프로세스를 실행 상태로 유지합니다. 실행 중인 백그라운드 셸 명령, 서브에이전트, 동적 워크플로우 또는 모니터는 활성 작업으로 간주되므로 개발 서버와 같은 장기 실행 프로세스는 세션을 활성 상태로 유지합니다.

550 586

570 606

571감독자는 디스크에 설치된 Claude Code 바이너리를 감시하고 일반 [자동 업데이터](/ko/setup#auto-updates)가 교체한 후 새 버전으로 다시 시작합니다. 이는 네트워크 검사가 아닌 로컬 파일 감시입니다. 백그라운드 세션은 분리된 프로세스이므로 다시 시작을 통해 계속 실행되고 새 감독자는 다시 연결됩니다. 유휴 고정된 세션도 새 버전으로 제자리에서 다시 시작되므로 다시 연결하지 않고도 업데이트를 적용합니다.607감독자는 디스크에 설치된 Claude Code 바이너리를 감시하고 일반 [자동 업데이터](/ko/setup#auto-updates)가 교체한 후 새 버전으로 다시 시작합니다. 이는 네트워크 검사가 아닌 로컬 파일 감시입니다. 백그라운드 세션은 분리된 프로세스이므로 다시 시작을 통해 계속 실행되고 새 감독자는 다시 연결됩니다. 유휴 고정된 세션도 새 버전으로 제자리에서 다시 시작되므로 다시 연결하지 않고도 업데이트를 적용합니다.

572 608

609감독자가 업데이트, 정지 또는 마이그레이션을 위해 세션을 다시 시작하는 동안 `claude attach`를 실행하면 실패하는 대신 대체 프로세스를 기다립니다. `Agent is updating to the new Claude Code…`와 같은 상태 줄은 기다리는 대상을 이름 지으며 경과된 초를 계산하고, 세션이 준비되면 명령이 연결됩니다. 약 60초 후에 대기를 중지하고 오류를 보고합니다. v2.1.205 이전에는 `claude attach`가 몇 초 후에 재시도를 중지하고 세션이 여전히 다시 시작되는 동안 오류를 인쇄했습니다.

610

573<h3 id="where-state-is-stored">611<h3 id="where-state-is-stored">

574 상태가 저장되는 위치612 상태가 저장되는 위치

575</h3>613</h3>

585 623

586각 백그라운드 세션에는 `CLAUDE_JOB_DIR` 환경 변수가 `~/.claude/jobs/<id>` 디렉토리로 설정되어 있으므로 세션이 실행하는 셸 명령은 병렬 세션과 충돌하지 않고 `$CLAUDE_JOB_DIR/tmp`에 임시 파일을 쓸 수 있습니다.624각 백그라운드 세션에는 `CLAUDE_JOB_DIR` 환경 변수가 `~/.claude/jobs/<id>` 디렉토리로 설정되어 있으므로 세션이 실행하는 셸 명령은 병렬 세션과 충돌하지 않고 `$CLAUDE_JOB_DIR/tmp`에 임시 파일을 쓸 수 있습니다.

587 625

588파일을 직접 읽지 않고 이 상태를 검사하려면 `claude daemon status`를 실행합니다. 감독자에 도달할 수 있는지 여부, 프로세스 ID 및 버전, 소켓 디렉토리, 그리고 활성 백그라운드 세션의 수를 보고합니다. `/doctor`는 동일한 검사의 요약을 포함합니다.626파일을 직접 읽지 않고 이 상태를 검사하려면 `claude daemon status`를 실행합니다. 감독자에 도달할 수 있는지 여부, 프로세스 ID 및 버전, 소켓 디렉토리, 그리고 활성 백그라운드 세션의 수를 보고합니다.

589 627

590명령은 또한 실행 중인 감독자가 호출한 `claude`와 다른 버전에 있을 때 경고하며, 이는 감독자가 아직 다시 시작하지 않은 업데이트 후에 발생합니다. 경고는 두 버전을 모두 표시하고 새 버전을 적용하려면 `claude daemon stop --any`를 실행하도록 지시합니다. Claude Code가 OS 서비스로 설치된 경우 제안된 명령은 플래그 없이 `claude daemon stop`입니다.628명령은 또한 실행 중인 감독자가 호출한 `claude`와 다른 버전에 있을 때 경고하며, 이는 감독자가 아직 다시 시작하지 않은 업데이트 후에 발생합니다. 경고는 두 버전을 모두 표시하고 새 버전을 적용하려면 `claude daemon stop --any`를 실행하도록 지시합니다. Claude Code가 OS 서비스로 설치된 경우 제안된 명령은 플래그 없이 `claude daemon stop`입니다.

591 629

592Windows에서 `claude daemon status`는 감독자의 파이프 키 파일이 잠겨 있거나 읽을 수 없을 때 일반적인 연결 실패를 보고하는 대신 기본 파일 오류를 표시합니다.630세션은 버전 불일치를 그대로 유지합니다. 이전 Claude Code 버전이 세션의 `state.json`을 업데이트할 때 인식하지 못하는 필드를 보존하고 세션을 나열된 상태로 유지합니다. {/* min-version: 2.1.200 */}`roster.json`의 세션 목록은 동일한 규칙을 따릅니다. 이전 버전이 다시 쓸 때 최신 버전이 작성한 필드를 보존하므로 최신 버전으로 시작한 세션은 도달 가능한 상태로 유지되고 감독자가 다시 시작한 후에도 입력을 계속 받습니다. v2.1.200 이전에는 이전 버전이 다시 쓸 때 해당 필드를 삭제할 수 있었습니다.

593 631

594세션은 버전 불일치를 그대로 유지합니다: 이전 Claude Code 버전이 세션의 `state.json`을 업데이트할 때 인식하지 못하는 필드를 보존하고 세션을 나열된 상태로 유지합니다.632Windows에서 `claude daemon status`는 감독자의 파이프 키 파일이 잠겨 있거나 읽을 수 없을 때 일반적인 연결 실패를 보고하는 대신 기본 파일 오류를 표시합니다.

595 633

596<h3 id="turn-off-agent-view">634<h3 id="turn-off-agent-view">

597 에이전트 뷰 끄기635 에이전트 뷰 끄기

615 에이전트 뷰가 세션 없이 열림653 에이전트 뷰가 세션 없이 열림

616</h3>654</h3>

617 655

618첫 번째 세션을 디스패치하기 전에 에이전트 뷰는 세션 목록 대신 짧은 온보딩 힌트와 예제 프롬프트를 표시합니다. 하단의 입력에 프롬프트를 입력하고 `Enter`를 눌러 첫 번째 세션을 디스패치합니다.656첫 번째 세션을 디스패치하기 전에 에이전트 뷰는 각 섹션 아래에 설명이 있는 빈 섹션 헤더와 입력 위에 한 줄 설명을 표시하며, 세션 목록 대신 표시됩니다. 하단의 입력에 프롬프트를 입력하고 `Enter`를 눌러 첫 번째 세션을 디스패치합니다.

619 657

620<h3 id="backgrounding-shows-a-background-this-session-dialog">658<h3 id="backgrounding-shows-a-background-this-session-dialog">

621 백그라운드로 이동하면 `Background this session?` 대화 상자가 표시됨659 백그라운드로 이동하면 `Background this session?` 대화 상자가 표시됨

637 675

638절전 상태만으로는 이 문제가 발생하지 않습니다. 세션은 절전 상태에서 보존되며 감독자는 깨어날 때 이들에 다시 연결됩니다.676절전 상태만으로는 이 문제가 발생하지 않습니다. 세션은 절전 상태에서 보존되며 감독자는 깨어날 때 이들에 다시 연결됩니다.

639 677

640<h3 id="a-session-fails-before-starting-with-a-possibly-low-memory-note">678<h3 id="opening-a-session-says-the-conversation-is-already-open">

641 세션이 시작되기 전에 `possibly low memory` 메모와 함께 실패함679 세션이 시작되기 전에 `possibly low memory` 메모와 함께 실패함

642</h3>680</h3>

643 681

647 685

648머신의 메모리를 확보한 후 행에 연결하거나, 엿보거나, 답변하면 감독자가 세션을 위한 새로운 프로세스를 시작합니다. 메모리가 계속 부족하면 감독자는 [유휴 세션을 중지](#the-supervisor-process)하여 자체적으로 리소스를 확보합니다.686머신의 메모리를 확보한 후 행에 연결하거나, 엿보거나, 답변하면 감독자가 세션을 위한 새로운 프로세스를 시작합니다. 메모리가 계속 부족하면 감독자는 [유휴 세션을 중지](#the-supervisor-process)하여 자체적으로 리소스를 확보합니다.

649 687

650<h3 id="agent-view-says-the-background-service-did-not-respond">688<h3 id="a-session-fails-before-starting-with-a-possibly-low-memory-note">

651 에이전트 뷰에서 백그라운드 서비스가 응답하지 않음689 에이전트 뷰에서 백그라운드 서비스가 응답하지 않음

652</h3>690</h3>

653 691

663 701

664Windows에서 감독자가 중지 요청에 응답하지 않으면, 명령이 프로세스 ID를 출력합니다. `taskkill /PID <pid>`로 해당 프로세스를 종료하여 복구를 완료합니다. `--keep-workers`를 전달했으면 백그라운드 세션은 여전히 보존됩니다.702Windows에서 감독자가 중지 요청에 응답하지 않으면, 명령이 프로세스 ID를 출력합니다. `taskkill /PID <pid>`로 해당 프로세스를 종료하여 복구를 완료합니다. `--keep-workers`를 전달했으면 백그라운드 세션은 여전히 보존됩니다.

665 703

666<h3 id="dispatch-fails-with-could-not-resolve-authentication-method">704<h3 id="agent-view-says-the-background-service-did-not-respond">

667 `Could not resolve authentication method` 오류로 디스패치 실패705 `Could not resolve authentication method` 오류로 디스패치 실패

668</h3>706</h3>

669 707

677 715

678원인 및 해결 방법의 전체 목록은 [오류 참조](/ko/errors#could-not-resolve-authentication-method)를 참조합니다.716원인 및 해결 방법의 전체 목록은 [오류 참조](/ko/errors#could-not-resolve-authentication-method)를 참조합니다.

679 717

680<h3 id="background-sessions-can’t-read-desktop-documents-or-downloads-on-macos">718<h3 id="dispatch-fails-with-could-not-resolve-authentication-method">

681 macOS에서 백그라운드 세션이 Desktop, Documents 또는 Downloads를 읽을 수 없음719 macOS에서 백그라운드 세션이 Desktop, Documents 또는 Downloads를 읽을 수 없음

682</h3>720</h3>

683 721

685 723

686기본 설치 프로그램을 사용하면 항목이 Claude Code로 표시되고 권한이 업데이트 전체에서 유지됩니다. Homebrew 또는 npm과 같은 다른 설치 방법을 사용하면 항목이 바이너리 경로를 표시하며 업데이트 후 다시 권한을 부여해야 할 수 있습니다.724기본 설치 프로그램을 사용하면 항목이 Claude Code로 표시되고 권한이 업데이트 전체에서 유지됩니다. Homebrew 또는 npm과 같은 다른 설치 방법을 사용하면 항목이 바이너리 경로를 표시하며 업데이트 후 다시 권한을 부여해야 할 수 있습니다.

687 725

688<h3 id="background-sessions-can’t-reach-local-network-hosts-on-macos">726<h3 id="background-sessions-can’t-read-desktop-documents-or-downloads-on-macos">

689 macOS에서 백그라운드 세션이 로컬 네트워크 호스트에 도달할 수 없음727 macOS에서 백그라운드 세션이 로컬 네트워크 호스트에 도달할 수 없음

690</h3>728</h3>

691 729

692macOS 15 이상에서 시스템은 로컬 네트워크 권한을 부여할 때까지 프로세스가 로컬 네트워크의 장치에 도달하는 것을 차단합니다. v2.1.198 이전에는 백그라운드 세션 호스트가 해당 권한을 요청하지 않았으므로, LAN 주소를 대상으로 하는 명령은 포그라운드 터미널에서 동일한 명령이 작동했음에도 불구하고 `connect: no route to host`로 실패했습니다. {/* min-version: 2.1.198 */}v2.1.198부터 백그라운드 세션의 첫 번째 명령이 로컬 네트워크 주소에 연결되면 Claude Code에 대한 macOS 로컬 네트워크 권한 프롬프트를 트리거합니다. 한 번 부여하면 이러한 명령은 포그라운드 터미널에서와 동일한 방식으로 LAN 호스트에 도달합니다.730macOS 15 이상에서 시스템은 로컬 네트워크 권한을 부여할 때까지 프로세스가 로컬 네트워크의 장치에 도달하는 것을 차단합니다. v2.1.198 이전에는 백그라운드 세션 호스트가 해당 권한을 요청하지 않았으므로, LAN 주소를 대상으로 하는 명령은 포그라운드 터미널에서 동일한 명령이 작동했음에도 불구하고 `connect: no route to host`로 실패했습니다. {/* min-version: 2.1.198 */}v2.1.198부터 백그라운드 세션의 첫 번째 명령이 로컬 네트워크 주소에 연결되면 Claude Code에 대한 macOS 로컬 네트워크 권한 프롬프트를 트리거합니다. 한 번 부여하면 이러한 명령은 포그라운드 터미널에서와 동일한 방식으로 LAN 호스트에 도달합니다.

693 731

694<h3 id="a-session-is-slow-to-respond-after-attaching">732<h3 id="background-sessions-can’t-reach-local-network-hosts-on-macos">

695 연결 후 세션이 응답이 느림733 연결 후 세션이 응답이 느림

696</h3>734</h3>

697 735

698세션이 완료되고 약 1시간 동안 연결되지 않으면 감독자는 리소스를 확보하기 위해 프로세스를 중지합니다. 연결하면 중단된 위치에서 새로운 프로세스를 시작합니다. 작업 중이거나 입력을 기다리는 세션 또는 [고정된](#organize-the-list) 세션은 이런 식으로 중지되지 않으므로, `Ctrl+T`로 세션을 고정하여 응답성을 유지합니다.736세션이 완료되고 약 1시간 동안 연결되지 않으면 감독자는 리소스를 확보하기 위해 프로세스를 중지합니다. 연결하면 중단된 위치에서 새로운 프로세스를 시작하고 세션으로 즉시 전환합니다. 작업 중이거나 입력을 기다리는 세션 또는 [고정된](#organize-the-list) 세션은 이런 식으로 중지되지 않으므로, `Ctrl+T`로 세션을 고정하여 응답성을 유지합니다.

699 737

700<h3 id="claude/worktrees/-is-filling-up">738<h3 id="a-session-is-slow-to-respond-after-attaching">

701 `.claude/worktrees/`가 채워지고 있음739 `.claude/worktrees/`가 채워지고 있음

702</h3>740</h3>

703 741

704에이전트 뷰에서 세션을 삭제하면 Claude가 생성한 워크트리가 제거됩니다. `claude rm`은 커밋되지 않은 변경 사항이 있는 워크트리를 유지하고 해당 경로를 출력합니다. 프로젝트 디렉토리에서 `git worktree list`로 남은 항목을 나열하고 각각을 `git worktree remove <path>`로 제거합니다. [워크트리 정리](/ko/worktrees#clean-up-worktrees)를 참조합니다.742에이전트 뷰에서 세션을 삭제하면 Claude가 생성한 워크트리가 제거됩니다. `claude rm`은 커밋되지 않은 변경 사항이 있는 워크트리를 유지하고 해당 경로를 출력합니다. 프로젝트 디렉토리에서 `git worktree list`로 남은 항목을 나열하고 각각을 `git worktree remove <path>`로 제거합니다. [워크트리 정리](/ko/worktrees#clean-up-worktrees)를 참조합니다.

705 743

744<h3 id="claude/worktrees/-is-filling-up">

745 세션이 시작되기 전에 대화가 이미 열려 있다고 표시됨

746</h3>

747

748중지된 행을 열 때 해당 대화가 같은 대화를 위해 여전히 종료 중인 백그라운드 워커와 같은 다른 실행 중인 비대화형 Claude Code 프로세스에 의해서도 열려 있으면, 두 프로세스가 같은 트랜스크립트에 쓸 수 없기 때문에 행의 프로세스를 시작하는 대신 `This conversation is already open in another running Claude session`을 표시합니다. 이미 대화를 열고 있는 세션에서 답변하거나 종료한 후 행을 다시 엽니다. 거부된 시도로 입력한 답변은 손실되지 않으며, 세션이 다음에 시작될 때 전송됩니다.

749

750v2.1.203 이전에는 이 상태가 어쨌든 두 번째 프로세스를 시작했습니다. 해당 프로세스는 `currently running as a background agent` 오류로 종료되었고 행은 실패로 표시되었습니다.

751

706<h2 id="limitations">752<h2 id="limitations">

707 제한 사항753 제한 사항

708</h2>754</h2>

731 777

732| 버전 | 변경 사항 |778| 버전 | 변경 사항 |

733| -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |779| -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

780| v2.1.205 | {/* min-version: 2.1.205 */}행 요약은 원시 도구 호출이나 `done/total` 개수 대신 세션의 자체 한 줄 보고서를 표시하며, 64개 열에서 잘립니다. 디렉터리로 그룹화된 행은 색상이 지정된 상태 단어로 열립니다. 엿보기 패널은 전체 상태 문장과 함께 열리며, 사용자의 입력을 기다리는 세션의 경우 회신 입력 위에 정확한 질문이 표시됩니다. `gh`로 풀 요청을 편집, 댓글, 종료 또는 준비 완료로 표시하는 세션은 풀 요청을 생성하거나 체크아웃하는 세션뿐만 아니라 연결됩니다. 푸시는 로컬 분기 이름이 일치하지 않을 때도 풀 요청을 연결하며, 생성 명령의 출력이 인라인 제한을 초과한 풀 요청도 연결됩니다. 읽을 수 있는 텍스트가 없는 턴은 세션의 이전 상태를 유지하며 `Working`으로 다시 전환하지 않습니다. `claude attach`는 재시작 중인 세션을 약 60초까지 기다리며, 실패하는 대신 이유를 명시하는 상태 줄이 표시됩니다. |

781| v2.1.203 | {/* min-version: 2.1.203 */}디스패치 셸에서 내보낸 게이트웨이 `ANTHROPIC_BASE_URL`은 감독자가 해당 게이트웨이 환경을 공유할 때 그것으로부터 디스패치된 세션에 함께 내보낸 API 키가 유지되는 대신 삭제되는 대신 같은 디렉터리에 도달합니다. 디스패치 셸의 `PATH`는 각 세션의 워커에 적용됩니다. 서브에이전트가 실행 중일 때 `←`를 누르면 10초 후에 다시 시작하는 대신 이들이 완료될 때까지 기다립니다. 빈 목록은 항상 각 섹션 헤더를 설명과 함께 표시합니다. 디스패치 입력에서 `@`를 입력하면 디렉터리 트리 내에 있는 시작 저장소의 등록된 git worktrees도 나열합니다. `effortLevel` 설정에서 상속된 노력은 디스패치 시 고정되는 대신 해당 설정에 대한 이후 편집을 따릅니다. 대화가 이미 다른 실행 중인 세션에서 열려 있는 중지된 세션을 열면 행이 실패하는 대신 메시지와 함께 거부됩니다. 에이전트 뷰에서 사용할 수 없는 명령은 입력에 입력된 텍스트를 남깁니다. git 저장소 외부에서 실패하는 `WorktreeCreate` 훅은 더 이상 세션이 파일을 편집하는 것을 차단하지 않습니다. |

782| v2.1.202 | {/* min-version: 2.1.202 */}백그라운드 세션에서 `/rename` 또는 `Ctrl+R`로 설정한 이름은 감독자가 프로세스를 중지하고 다시 시작할 때 세션이 디스패치된 이름으로 되돌아가는 대신 유지됩니다. |

783| v2.1.200 | {/* min-version: 2.1.200 */}더 이전 Claude Code 버전이 `roster.json`의 세션 목록을 다시 작성할 때 최신 버전이 작성한 필드를 보존하여 기존 `state.json` 보장과 일치하므로 최신 버전으로 시작한 세션은 감독자가 다시 시작한 후에도 입력을 계속 수락합니다. 응답을 중지한 세션을 열면 감독자가 프로세스를 다시 시작하고 세션은 중단된 응답을 중단된 위치에서 계속합니다. |

734| v2.1.199 | {/* min-version: 2.1.199 */}메모리 부족 호스트에서 시작을 완료하기 전에 프로세스가 종료되는 백그라운드 세션은 단순히 종료 이유만 표시하는 대신 행 상태에 `possibly low memory — free some up and retry`를 표시합니다. `←` 또는 `/background`로 세션을 백그라운드로 이동하면 `/color`를 새 행으로 이동합니다. |784| v2.1.199 | {/* min-version: 2.1.199 */}메모리 부족 호스트에서 시작을 완료하기 전에 프로세스가 종료되는 백그라운드 세션은 단순히 종료 이유만 표시하는 대신 행 상태에 `possibly low memory — free some up and retry`를 표시합니다. `←` 또는 `/background`로 세션을 백그라운드로 이동하면 `/color`를 새 행으로 이동합니다. |

735| v2.1.198 | {/* min-version: 2.1.198 */}에이전트 뷰는 백그라운드 세션이 입력이 필요하거나, 완료되거나, 실패할 때 `preferredNotifChannel`을 통해 알림을 보내고 `agent_needs_input` 또는 `agent_completed` 유형으로 `Notification` 훅을 실행합니다. `claude attach <id>` 내의 `←` 및 `/exit`는 셸로 종료하는 대신 에이전트 뷰로 돌아갑니다. `Ctrl+Z`는 셸로 돌아갑니다. 백그라운드 세션이 작업을 워크트리에 격리하면 자신의 격리된 분기를 커밋하고 푸시하며, `main` 또는 `master`를 사용하지 않고, 완료될 때 먼저 묻는 대신 초안 풀 요청을 엽니다. `/login`은 에이전트 뷰에서 실행되고 로그인 대화를 엽니다. `Background work is running` 종료 대화는 `Move to background and exit`를 제공합니다. 종료 핸드오프는 백그라운드 서브에이전트도 포함하며, 이들은 실패로 보고되는 대신 다음 깨어날 때 트랜스크립트에서 재개됩니다. `claude --bg`는 `-p` 또는 `--print`와 결합되면 오류로 거부됩니다. |785| v2.1.198 | {/* min-version: 2.1.198 */}에이전트 뷰는 백그라운드 세션이 입력이 필요하거나, 완료되거나, 실패할 때 `preferredNotifChannel`을 통해 알림을 보내고 `agent_needs_input` 또는 `agent_completed` 유형으로 `Notification` 훅을 실행합니다. `claude attach <id>` 내의 `←` 및 `/exit`는 셸로 종료하는 대신 에이전트 뷰로 돌아갑니다. `Ctrl+Z`는 셸로 돌아갑니다. 백그라운드 세션이 작업을 워크트리에 격리하면 자신의 격리된 분기를 커밋하고 푸시하며, `main` 또는 `master`를 사용하지 않고, 완료될 때 먼저 묻는 대신 초안 풀 요청을 엽니다. `/login`은 에이전트 뷰에서 실행되고 로그인 대화를 엽니다. `Background work is running` 종료 대화는 `Move to background and exit`를 제공합니다. 종료 핸드오프는 백그라운드 서브에이전트도 포함하며, 이들은 실패로 보고되는 대신 다음 깨어날 때 트랜스크립트에서 재개됩니다. `claude --bg`는 `-p` 또는 `--print`와 결합되면 오류로 거부됩니다. |

736| v2.1.196 | {/* min-version: 2.1.196 */}단일 `←` 누름이 포그라운드 세션을 백그라운드로 이동합니다. 이전 버전은 바닥글 힌트와 확인이 있는 두 번의 누름이 필요했습니다. `claude agents`에 전달된 `--dangerously-skip-permissions`는 자동으로 삭제되는 대신 면책 조항을 표시합니다. 이름을 지정하지 않은 대화형 세션은 세션 목록 및 `claude agents --json`에서 `my-app-3f`와 같은 기본 이름을 가집니다. 백그라운드 셸 명령 및 동적 워크플로우는 세션의 프로세스가 중지되거나, 다시 시작되거나, Windows를 포함한 업데이트될 때 생존합니다. `CLAUDE_CODE_DISABLE_BG_EXIT_HANDOFF=1`을 설정하여 핸드오프를 끕니다. 다시 시작 시 비어 있는 것으로 잘못 읽은 트랜스크립트는 삭제되는 대신 `.orphaned-` 접두사로 이름이 바뀝니다. |786| v2.1.196 | {/* min-version: 2.1.196 */}단일 `←` 누름이 포그라운드 세션을 백그라운드로 이동합니다. 이전 버전은 바닥글 힌트와 확인이 있는 두 번의 누름이 필요했습니다. `claude agents`에 전달된 `--dangerously-skip-permissions`는 자동으로 삭제되는 대신 면책 조항을 표시합니다. 이름을 지정하지 않은 대화형 세션은 세션 목록 및 `claude agents --json`에서 `my-app-3f`와 같은 기본 이름을 가집니다. 백그라운드 셸 명령 및 동적 워크플로우는 세션의 프로세스가 중지되거나, 다시 시작되거나, Windows를 포함한 업데이트될 때 생존합니다. `CLAUDE_CODE_DISABLE_BG_EXIT_HANDOFF=1`을 설정하여 핸드오프를 끕니다. 다시 시작 시 비어 있는 것으로 잘못 읽은 트랜스크립트는 삭제되는 대신 `.orphaned-` 접두사로 이름이 바뀝니다. |

738| v2.1.174 | {/* min-version: 2.1.174 */}백그라운드 세션은 더 이상 감독자의 시작 셸에서 `ANTHROPIC_BASE_URL`과 같은 게이트웨이 엔드포인트 변수를 상속하지 않습니다. 감독자는 사전 준비된 워커에 새로운 자격 증명 스냅샷을 제공하여 허위 `Could not resolve authentication method` 오류를 수정합니다. |788| v2.1.174 | {/* min-version: 2.1.174 */}백그라운드 세션은 더 이상 감독자의 시작 셸에서 `ANTHROPIC_BASE_URL`과 같은 게이트웨이 엔드포인트 변수를 상속하지 않습니다. 감독자는 사전 준비된 워커에 새로운 자격 증명 스냅샷을 제공하여 허위 `Could not resolve authentication method` 오류를 수정합니다. |

739| v2.1.172 | {/* min-version: 2.1.172 */}디스패치 입력의 `/model`이 세션 범위 디스패치 모델 재정의를 설정합니다. |789| v2.1.172 | {/* min-version: 2.1.172 */}디스패치 입력의 `/model`이 세션 범위 디스패치 모델 재정의를 설정합니다. |

740| v2.1.161 | {/* min-version: 2.1.161 */}행 요약은 병렬 작업 항목에 대해 `done/total` 개수를 표시합니다. 엿보기 패널은 가장 오래 실행 중인 병렬 작업 항목의 이름을 지정합니다. |790| v2.1.161 | {/* min-version: 2.1.161 */}행 요약은 병렬 작업 항목에 대해 `done/total` 개수를 표시합니다. 엿보기 패널은 가장 오래 실행 중인 병렬 작업 항목의 이름을 지정합니다. |

741| v2.1.157 | {/* min-version: 2.1.157 */}}`claude agents`는 `--agent`를 허용합니다. 디스패치된 세션은 `agent` 설정을 준수합니다. |791| v2.1.157 | {/* min-version: 2.1.157 */}`claude agents`는 `--agent`를 허용합니다. 디스패치된 세션은 `agent` 설정을 준수합니다. |

742| v2.1.145 | {/* min-version: 2.1.145 */}음성 받아쓰기는 엿보기 패널 답변 입력 및 디스패치 입력에서 지원됩니다. |792| v2.1.145 | {/* min-version: 2.1.145 */}음성 받아쓰기는 엿보기 패널 답변 입력 및 디스패치 입력에서 지원됩니다. |

743| v2.1.143 | {/* min-version: 2.1.143 */}}`worktree.bgIsolation` 설정이 추가되었습니다. `claude agents`는 `--allow-dangerously-skip-permissions`를 허용합니다. |793| v2.1.143 | {/* min-version: 2.1.143 */}`worktree.bgIsolation` 설정이 추가되었습니다. `claude agents`는 `--allow-dangerously-skip-permissions`를 허용합니다. |

744| v2.1.142 | {/* min-version: 2.1.142 */}}`claude agents`는 `--permission-mode`, `--model`, `--effort`, `--dangerously-skip-permissions`, `--settings`, `--add-dir`, `--plugin-dir`, `--mcp-config` 및 `--strict-mcp-config`를 허용합니다. |794| v2.1.142 | {/* min-version: 2.1.142 */}`claude agents`는 `--permission-mode`, `--model`, `--effort`, `--dangerously-skip-permissions`, `--settings`, `--add-dir`, `--plugin-dir`, `--mcp-config` 및 `--strict-mcp-config`를 허용합니다. |

745| v2.1.141 | {/* min-version: 2.1.141 */}}`claude agents`는 `--cwd`를 허용하여 목록을 한 프로젝트로 범위를 지정합니다. |795| v2.1.141 | {/* min-version: 2.1.141 */}`claude agents`는 `--cwd`를 허용하여 목록을 한 프로젝트로 범위를 지정합니다. |

746| v2.1.139 | {/* min-version: 2.1.139 */}에이전트 뷰가 연구 미리보기로 도입되었습니다. |796| v2.1.139 | {/* min-version: 2.1.139 */}에이전트 뷰가 연구 미리보기로 도입되었습니다. |

amazon-bedrock.md +35 −35

Details

82 필수 조건82 필수 조건

83</h2>83</h2>

84 84

~~85Claude Code를 Bedrock으로 구성하기 전에 다음을 확인하십시오:~~85Claude Code를 Amazon Bedrock으로 구성하기 전에 다음을 확인하십시오:

86 86

~~87* Bedrock 액세스가 활성화된 AWS 계정~~87* Amazon Bedrock 액세스가 활성화된 AWS 계정

~~88* Bedrock에서 원하는 Claude 모델(예: Claude Sonnet 4.6)에 대한 액세스~~88* Amazon Bedrock에서 원하는 Claude 모델(예: Claude Sonnet 4.6)에 대한 액세스

89* AWS CLI 설치 및 구성(선택 사항 - 자격 증명을 얻을 다른 메커니즘이 없는 경우에만 필요)89* AWS CLI 설치 및 구성(선택 사항 - 자격 증명을 얻을 다른 메커니즘이 없는 경우에만 필요)

90* 적절한 IAM 권한90* 적절한 IAM 권한

91 91

92Bedrock 자격 증명으로 로그인하려면 아래의 [Bedrock으로 로그인](#sign-in-with-bedrock)을 따르십시오. 팀 전체에 Claude Code를 배포하려면 [수동 설정](#set-up-manually) 단계를 사용하고 롤아웃 전에 [모델 버전을 고정](#4-pin-model-versions)하십시오.92자신의 Amazon Bedrock 자격 증명으로 로그인하려면 아래의 [Bedrock으로 로그인](#sign-in-with-bedrock)을 따르십시오. 팀 전체에 Claude Code를 배포하려면 [수동 설정](#set-up-manually) 단계를 사용하고 롤아웃 전에 [모델 버전 고정](#4-pin-model-versions)하십시오.

93 93

94<h2 id="sign-in-with-bedrock">94<h2 id="sign-in-with-bedrock">

95 Bedrock으로 로그인95 Bedrock으로 로그인

96</h2>96</h2>

97 97

98AWS 자격 증명이 있고 Bedrock을 통해 Claude Code 사용을 시작하려면 로그인 마법사가 이를 안내합니다. AWS 측 필수 조건은 계정당 한 번 완료하며, 마법사가 Claude Code 측을 처리합니다.98AWS 자격 증명이 있고 Amazon Bedrock을 통해 Claude Code 사용을 시작하려면 로그인 마법사가 이를 안내합니다. AWS 측 필수 조건은 계정당 한 번 완료하며, 마법사가 Claude Code 측을 처리합니다.

99 99

100<Steps>100<Steps>

101 <Step title="AWS 계정에서 Anthropic 모델 활성화">101 <Step title="AWS 계정에서 Anthropic 모델 활성화">

102 [Amazon Bedrock 콘솔](https://console.aws.amazon.com/bedrock/)에서 모델 카탈로그를 열고 Anthropic 모델을 선택한 후 사용 사례 양식을 제출하십시오. 제출 후 즉시 액세스가 부여됩니다. AWS Organizations의 경우 [사용 사례 세부 정보 제출](#1-submit-use-case-details)을 참조하고 권한의 경우 [IAM 구성](#iam-configuration)을 참조하십시오.102 [Amazon Bedrock 콘솔](https://console.aws.amazon.com/bedrock/)에서 모델 카탈로그를 열고 Anthropic 모델을 선택한 후 사용 사례 양식을 제출하십시오. 제출 후 즉시 액세스가 부여됩니다. AWS Organizations의 경우 [사용 사례 세부 정보 제출](#1-submit-use-case-details)을 참조하고 권한의 경우 [IAM 구성](#iam-configuration)을 참조하십시오.

103 </Step>103 </Step>

104 104

105 <Step title="Claude Code를 시작하고 Bedrock 선택">105 <Step title="Claude Code를 시작하고 Amazon Bedrock 선택">

106 `claude`를 실행하십시오. 로그인 프롬프트에서 **3rd-party platform**을 선택한 후 **Amazon Bedrock**을 선택하십시오.106 `claude`를 실행하십시오. 로그인 프롬프트에서 **3rd-party platform**을 선택한 후 **Amazon Bedrock**을 선택하십시오.

107 </Step>107 </Step>

108 108

109 <Step title="마법사 프롬프트 따르기">109 <Step title="마법사 프롬프트 따르기">

110 AWS에 인증하는 방법을 선택하십시오: `~/.aws` 디렉토리에서 감지된 AWS 프로필, Bedrock API 키, 액세스 키 및 시크릿, 또는 환경에 이미 있는 자격 증명. 마법사가 지역을 선택하고 계정이 호출할 수 있는 Claude 모델을 확인한 후 고정할 수 있도록 합니다. 결과를 [사용자 설정 파일](/ko/settings)의 `env` 블록에 저장하므로 환경 변수를 직접 내보낼 필요가 없습니다.110 AWS에 인증하는 방법을 선택하십시오: `~/.aws` 디렉토리에서 감지된 AWS 프로필, Amazon Bedrock API 키, 액세스 키 및 시크릿, 또는 환경에 이미 있는 자격 증명. 마법사가 지역을 선택하고 계정이 호출할 수 있는 Claude 모델을 확인한 후 고정할 수 있도록 합니다. 결과를 [사용자 설정 파일](/ko/settings)의 `env` 블록에 저장하므로 환경 변수를 직접 내보낼 필요가 없습니다.

111 </Step>111 </Step>

112</Steps>112</Steps>

113 113

117 수동으로 설정117 수동으로 설정

118</h2>118</h2>

119 119

120마법사 대신 환경 변수를 통해 Bedrock을 구성하려면(예: CI 또는 스크립트된 엔터프라이즈 롤아웃에서), 아래 단계를 따르십시오.120마법사 대신 환경 변수를 통해 Amazon Bedrock을 구성하려면(예: CI 또는 스크립트된 엔터프라이즈 롤아웃에서), 아래 단계를 따르십시오.

121 121

122<h3 id="1-submit-use-case-details">122<h3 id="1-submit-use-case-details">

123 1. 사용 사례 세부 정보 제출123 1. 사용 사례 세부 정보 제출

168 168

169`aws login`에 대해 [자세히 알아보기](https://docs.aws.amazon.com/signin/latest/userguide/command-line-sign-in.html).169`aws login`에 대해 [자세히 알아보기](https://docs.aws.amazon.com/signin/latest/userguide/command-line-sign-in.html).

170 170

171**옵션 E: Bedrock API 키**171**옵션 E: Amazon Bedrock API 키**

172 172

173```bash theme={null}173```bash theme={null}

174export AWS_BEARER_TOKEN_BEDROCK=your-bedrock-api-key174export AWS_BEARER_TOKEN_BEDROCK=your-bedrock-api-key

175```175```

176 176

177Bedrock API 키는 전체 AWS 자격 증명이 필요 없는 더 간단한 인증 방법을 제공합니다. [Bedrock API 키에 대해 자세히 알아보기](https://aws.amazon.com/blogs/machine-learning/accelerate-ai-development-with-amazon-bedrock-api-keys/).177Amazon Bedrock API 키는 전체 AWS 자격 증명이 필요 없는 더 간단한 인증 방법을 제공합니다. [Amazon Bedrock API 키에 대해 자세히 알아보기](https://aws.amazon.com/blogs/machine-learning/accelerate-ai-development-with-amazon-bedrock-api-keys/).

178 178

179<h4 id="advanced-credential-configuration">179<h4 id="advanced-credential-configuration">

180 고급 자격 증명 구성180 고급 자격 증명 구성

185이 두 설정은 서로 다른 트리거 조건을 가집니다:185이 두 설정은 서로 다른 트리거 조건을 가집니다:

186 186

187* **`awsAuthRefresh`**: Claude Code가 AWS 자격 증명이 만료되었음을 감지할 때만 실행됩니다. 타임스탬프를 기반으로 로컬에서 또는 API가 자격 증명 오류를 반환할 때 감지되며, 새로 고쳐진 자격 증명으로 요청을 다시 시도합니다.187* **`awsAuthRefresh`**: Claude Code가 AWS 자격 증명이 만료되었음을 감지할 때만 실행됩니다. 타임스탬프를 기반으로 로컬에서 또는 API가 자격 증명 오류를 반환할 때 감지되며, 새로 고쳐진 자격 증명으로 요청을 다시 시도합니다.

188* **`awsCredentialExport`**: 세션 시작 시 및 각 자격 증명 다시 로드 시 실행되며, AWS 기본 자격 증명 공급자 체인의 자격 증명이 여전히 유효한 경우에도 실행됩니다. Bedrock 계정이 기본 공급자 체인이 확인할 자격 증명과 다른 교차 계정 자격 증명을 필요로 할 때 사용하십시오.188* **`awsCredentialExport`**: 세션 시작 시 및 각 자격 증명 다시 로드 시 실행되며, AWS 기본 자격 증명 공급자 체인의 자격 증명이 여전히 유효한 경우에도 실행됩니다. Amazon Bedrock 계정이 기본 공급자 체인이 확인할 자격 증명과 다른 교차 계정 자격 증명을 필요로 할 때 사용하십시오.

189 189

190<h5 id="example-configuration">190<h5 id="example-configuration">

191 예제 구성191 예제 구성

227 3. Claude Code 구성227 3. Claude Code 구성

228</h3>228</h3>

229 229

230Bedrock을 활성화하려면 다음 환경 변수를 설정하십시오:230Amazon Bedrock을 활성화하려면 다음 환경 변수를 설정하십시오:

231 231

232```bash theme={null}232```bash theme={null}

233# Bedrock 통합 활성화233# Bedrock 통합 활성화

243# export ANTHROPIC_BEDROCK_BASE_URL=https://bedrock-runtime.us-east-1.amazonaws.com243# export ANTHROPIC_BEDROCK_BASE_URL=https://bedrock-runtime.us-east-1.amazonaws.com

244```244```

245 245

246Claude Code에 대해 Bedrock을 활성화할 때 다음을 염두에 두십시오:246Claude Code에 대해 Amazon Bedrock을 활성화할 때 다음을 염두에 두십시오:

247 247

248* {/* min-version: 2.1.172 */}v2.1.172부터 AWS 프로필의 지역을 재정의하거나 프로필에 지역이 없을 때만 `AWS_REGION`을 설정하면 됩니다. Claude Code는 다음 순서로 지역을 확인합니다:248* {/* min-version: 2.1.172 */}v2.1.172부터 AWS 프로필의 지역을 재정의하거나 프로필에 지역이 없을 때만 `AWS_REGION`을 설정하면 됩니다. Claude Code는 다음 순서로 지역을 확인합니다:

249 249

253 * `us-east-1`253 * `us-east-1`

254 254

255 활성 프로필은 설정된 경우 `AWS_PROFILE`이고, 그렇지 않으면 `default`입니다. `AWS_SHARED_CREDENTIALS_FILE` 또는 `AWS_CONFIG_FILE`을 설정하여 기본이 아닌 파일 경로를 가리킵니다. `/status`를 실행하여 확인된 지역을 확인하십시오. 지역이 AWS 구성 파일 또는 기본 폴백에서 나온 경우 `/status`도 소스를 표시합니다. v2.1.171 이전에서는 Claude Code가 AWS 구성 파일을 읽지 않으므로 `AWS_REGION`을 명시적으로 설정하십시오.255 활성 프로필은 설정된 경우 `AWS_PROFILE`이고, 그렇지 않으면 `default`입니다. `AWS_SHARED_CREDENTIALS_FILE` 또는 `AWS_CONFIG_FILE`을 설정하여 기본이 아닌 파일 경로를 가리킵니다. `/status`를 실행하여 확인된 지역을 확인하십시오. 지역이 AWS 구성 파일 또는 기본 폴백에서 나온 경우 `/status`도 소스를 표시합니다. v2.1.171 이전에서는 Claude Code가 AWS 구성 파일을 읽지 않으므로 `AWS_REGION`을 명시적으로 설정하십시오.

256* Bedrock을 사용할 때 `/logout` 명령은 AWS 자격 증명을 통해 인증이 처리되므로 사용할 수 없습니다.256* Amazon Bedrock을 사용할 때 `/logout` 명령은 AWS 자격 증명을 통해 인증이 처리되므로 사용할 수 없습니다.

257* WebSearch 도구는 Bedrock에서 사용할 수 없습니다. [WebSearch 도구 동작](/ko/tools-reference#websearch-tool-behavior)을 참조하십시오.257* WebSearch 도구는 Amazon Bedrock에서 사용할 수 없습니다. [WebSearch 도구 동작](/ko/tools-reference#websearch-tool-behavior)을 참조하십시오.

258* 다른 프로세스에 유출되지 않도록 하려는 `AWS_PROFILE`과 같은 환경 변수에 설정 파일을 사용할 수 있습니다. 자세한 내용은 [설정](/ko/settings)을 참조하십시오.258* 다른 프로세스에 유출되지 않도록 하려는 `AWS_PROFILE`과 같은 환경 변수에 설정 파일을 사용할 수 있습니다. 자세한 내용은 [설정](/ko/settings)을 참조하십시오.

259 259

260<h3 id="4-pin-model-versions">260<h3 id="4-pin-model-versions">

262</h3>262</h3>

263 263

264<Warning>264<Warning>

265 여러 사용자에게 배포할 때 특정 모델 버전을 고정하십시오. 고정하지 않으면 `sonnet` 및 `opus`와 같은 모델 별칭이 Claude Code의 Bedrock용 기본 제공 기본값으로 확인되며, 이는 최신 릴리스보다 뒤떨어질 수 있고 계정에서 아직 사용할 수 없을 수 있습니다. Claude Code는 기본값을 사용할 수 없을 때 [시작 시](#startup-model-checks) 이전 버전으로 폴백하지만, 고정하면 사용자가 새 모델로 이동하는 시기를 제어할 수 있습니다.265 여러 사용자에게 배포할 때 특정 모델 버전을 고정하십시오. 고정하지 않으면 `sonnet` 및 `opus`와 같은 모델 별칭이 Claude Code의 Amazon Bedrock용 기본 제공 기본값으로 확인되며, 이는 최신 릴리스보다 뒤떨어질 수 있고 계정에서 아직 사용할 수 없을 수 있습니다. Claude Code는 기본값을 사용할 수 없을 때 [시작 시](#startup-model-checks) 이전 버전으로 폴백하지만, 고정하면 사용자가 새 모델로 이동하는 시기를 제어할 수 있습니다.

266</Warning>266</Warning>

267 267

268이러한 환경 변수를 특정 Bedrock 모델 ID로 설정하십시오.268이러한 환경 변수를 특정 Amazon Bedrock 모델 ID로 설정하십시오.

269 269

270`ANTHROPIC_DEFAULT_OPUS_MODEL`이 없으면 Bedrock의 `opus` 별칭이 Opus 4.6으로 확인됩니다. 최신 모델을 사용하려면 Opus 4.8 ID로 설정하십시오:270`ANTHROPIC_DEFAULT_OPUS_MODEL`이 없으면 Amazon Bedrock의 `opus` 별칭이 Opus 4.6으로 확인됩니다. 최신 모델을 사용하려면 Opus 4.8 ID로 설정하십시오:

271 271

272```bash theme={null}272```bash theme={null}

273export ANTHROPIC_DEFAULT_OPUS_MODEL='us.anthropic.claude-opus-4-8'273export ANTHROPIC_DEFAULT_OPUS_MODEL='us.anthropic.claude-opus-4-8'

285| 소형/빠른 모델 | 기본 모델과 동일 |285| 소형/빠른 모델 | 기본 모델과 동일 |

286 286

287세션 제목 생성과 같은 백그라운드 작업은 소형/빠른 모델(일반적으로 Haiku 클래스 모델)을 사용합니다. Bedrock에서 Claude Code는 모든 계정 또는 지역에서 Haiku를 사용할 수 없을 수 있으므로 기본적으로 이를 기본 모델로 설정합니다. 백그라운드 작업에 Haiku를 사용하려면 `ANTHROPIC_DEFAULT_HAIKU_MODEL`을 계정에서 사용 가능한 모델 ID로 설정하십시오.287세션 제목 생성과 같은 백그라운드 작업은 소형/빠른 모델(일반적으로 Haiku 클래스 모델)을 사용합니다. Amazon Bedrock에서 Claude Code는 모든 계정 또는 지역에서 Haiku를 사용할 수 없을 수 있으므로 기본적으로 이를 기본 모델로 설정합니다. 백그라운드 작업에 Haiku를 사용하려면 `ANTHROPIC_DEFAULT_HAIKU_MODEL`을 계정에서 사용 가능한 모델 ID로 설정하십시오.

288 288

289모델을 추가로 사용자 정의하려면 다음 방법 중 하나를 사용하십시오:289모델을 추가로 사용자 정의하려면 다음 방법 중 하나를 사용하십시오:

290 290

305 305

3061시간 캐시 TTL은 5분 기본값보다 높은 요금으로 청구됩니다. [캐시 수명](/ko/prompt-caching#cache-lifetime)을 참조하십시오.3061시간 캐시 TTL은 5분 기본값보다 높은 요금으로 청구됩니다. [캐시 수명](/ko/prompt-caching#cache-lifetime)을 참조하십시오.

307 307

308<Note>프롬프트 캐싱은 모든 Bedrock 지역에서 사용할 수 없을 수 있습니다. 캐시 토큰 수가 0으로 유지되면 Bedrock 설명서에서 [지원되는 모델, 지역 및 제한](https://docs.aws.amazon.com/bedrock/latest/userguide/prompt-caching.html#prompt-caching-models)을 확인하십시오.</Note>308<Note>프롬프트 캐싱은 모든 Amazon Bedrock 지역에서 사용할 수 없을 수 있습니다. 캐시 토큰 수가 0으로 유지되면 Amazon Bedrock 설명서에서 [지원되는 모델, 지역 및 제한](https://docs.aws.amazon.com/bedrock/latest/userguide/prompt-caching.html#prompt-caching-models)을 확인하십시오.</Note>

309 309

310<h4 id="map-each-model-version-to-an-inference-profile">310<h4 id="map-each-model-version-to-an-inference-profile">

311 각 모델 버전을 추론 프로필에 매핑311 각 모델 버전을 추론 프로필에 매핑

326}326}

327```327```

328 328

329사용자가 `/model`에서 이러한 버전 중 하나를 선택하면 Claude Code는 매핑된 ARN으로 Bedrock을 호출합니다. 재정의가 없는 버전은 기본 제공 Bedrock 모델 ID 또는 시작 시 발견된 일치하는 추론 프로필로 폴백됩니다. 재정의가 `availableModels` 및 기타 모델 설정과 상호 작용하는 방식에 대한 자세한 내용은 [버전별 모델 ID 재정의](/ko/model-config#override-model-ids-per-version)를 참조하십시오.329사용자가 `/model`에서 이러한 버전 중 하나를 선택하면 Claude Code는 매핑된 ARN으로 Amazon Bedrock을 호출합니다. {/* min-version: 2.1.200 */}동일한 매핑은 `--model` 또는 `ANTHROPIC_MODEL`을 통해 Anthropic 모델 ID를 직접 전달할 때도 적용됩니다. 재정의가 없는 버전은 기본 제공 Amazon Bedrock 모델 ID 또는 시작 시 발견된 일치하는 추론 프로필로 폴백됩니다. v2.1.200 이전에는 `--model` 및 `ANTHROPIC_MODEL` 값이 재정의 맵을 거치지 않고 Amazon Bedrock에 그대로 도달했습니다. 재정의가 `availableModels` 및 기타 모델 설정과 상호 작용하는 방식에 대한 자세한 내용은 [버전별 모델 ID 재정의](/ko/model-config#override-model-ids-per-version)를 참조하십시오.

330 330

331<h2 id="startup-model-checks">331<h2 id="startup-model-checks">

332 시작 모델 확인332 시작 모델 확인

333</h2>333</h2>

334 334

335Claude Code가 Bedrock으로 구성되어 시작되면 사용하려는 모델이 계정에서 액세스 가능한지 확인합니다. 이 확인에는 Claude Code v2.1.94 이상이 필요합니다.335Claude Code가 Amazon Bedrock으로 구성되어 시작되면 사용하려는 모델이 계정에서 액세스 가능한지 확인합니다. 이 확인에는 Claude Code v2.1.94 이상이 필요합니다.

336 336

337현재 Claude Code 기본값보다 오래된 모델 버전을 고정했고 계정이 최신 버전을 호출할 수 있는 경우 Claude Code는 고정을 업데이트하라는 메시지를 표시합니다. 수락하면 새 모델 ID를 [사용자 설정 파일](/ko/settings)에 쓰고 Claude Code를 다시 시작합니다. 거부하면 다음 기본 버전 변경까지 기억됩니다. [애플리케이션 추론 프로필 ARN](#map-each-model-version-to-an-inference-profile)을 가리키는 고정은 관리자가 관리하므로 건너뜁니다.337현재 Claude Code 기본값보다 오래된 모델 버전을 고정했고 계정이 최신 버전을 호출할 수 있는 경우 Claude Code는 고정을 업데이트하라는 메시지를 표시합니다. 수락하면 새 모델 ID를 [사용자 설정 파일](/ko/settings)에 쓰고 Claude Code를 다시 시작합니다. 거부하면 다음 기본 버전 변경까지 기억됩니다. [애플리케이션 추론 프로필 ARN](#map-each-model-version-to-an-inference-profile)을 가리키는 고정은 관리자가 관리하므로 건너뜁니다.

338 338

339모델을 고정하지 않았고 현재 기본값을 계정에서 사용할 수 없는 경우 Claude Code는 현재 세션에서 이전 버전으로 폴백하고 알림을 표시합니다. 폴백은 유지되지 않습니다. Bedrock 계정에서 최신 모델을 활성화하거나 [버전을 고정](#4-pin-model-versions)하여 선택을 영구적으로 만드십시오.339모델을 고정하지 않았고 현재 기본값을 계정에서 사용할 수 없는 경우 Claude Code는 현재 세션에서 이전 버전으로 폴백하고 알림을 표시합니다. 폴백은 유지되지 않습니다. Amazon Bedrock 계정에서 최신 모델을 활성화하거나 [버전을 고정](#4-pin-model-versions)하여 선택을 영구적으로 만드십시오.

340 340

341<h2 id="iam-configuration">341<h2 id="iam-configuration">

342 IAM 구성342 IAM 구성

387 387

388토큰에 이 권한이 없으면 Claude Code는 대체 형태로 한 번 재시도하여 자동으로 복구되므로 요청은 여전히 성공하지만 각 새로운 모델은 추가 왕복을 추가합니다. 권한을 부여하면 재시도를 피할 수 있습니다. 이는 토큰의 정책이 일반적으로 전체 IAM 역할보다 좁은 `AWS_BEARER_TOKEN_BEDROCK` 배포에 가장 자주 적용됩니다.388토큰에 이 권한이 없으면 Claude Code는 대체 형태로 한 번 재시도하여 자동으로 복구되므로 요청은 여전히 성공하지만 각 새로운 모델은 추가 왕복을 추가합니다. 권한을 부여하면 재시도를 피할 수 있습니다. 이는 토큰의 정책이 일반적으로 전체 IAM 역할보다 좁은 `AWS_BEARER_TOKEN_BEDROCK` 배포에 가장 자주 적용됩니다.

389 389

390자세한 내용은 [Bedrock IAM 설명서](https://docs.aws.amazon.com/bedrock/latest/userguide/security-iam.html)를 참조하십시오.390자세한 내용은 [Amazon Bedrock IAM 설명서](https://docs.aws.amazon.com/bedrock/latest/userguide/security-iam.html)를 참조하십시오.

391 391

392<Note>392<Note>

393 비용 추적 및 액세스 제어를 단순화하기 위해 Claude Code용 전용 AWS 계정을 만드십시오.393 비용 추적 및 액세스 제어를 단순화하기 위해 Claude Code용 전용 AWS 계정을 만드십시오.

450export AWS_REGION=us-east-1450export AWS_REGION=us-east-1

451```451```

452 452

453Claude Code는 AWS 지역에서 엔드포인트 URL을 구성합니다. {/* min-version: 2.1.172 */}v2.1.172부터 지역은 [위의 Bedrock](#3-configure-claude-code)과 동일한 우선순위로 해결되며, 이전 버전은 `AWS_REGION`만 사용합니다. 사용자 정의 엔드포인트 또는 게이트웨이를 위해 URL을 재정의하려면 `ANTHROPIC_BEDROCK_MANTLE_BASE_URL`을 설정하십시오.453Claude Code는 AWS 지역에서 엔드포인트 URL을 구성합니다. {/* min-version: 2.1.172 */}v2.1.172부터 지역은 [위의 Amazon Bedrock](#3-configure-claude-code)과 동일한 우선순위로 해결되며, 이전 버전은 `AWS_REGION`만 사용합니다. 사용자 정의 엔드포인트 또는 게이트웨이를 위해 URL을 재정의하려면 `ANTHROPIC_BEDROCK_MANTLE_BASE_URL`을 설정하십시오.

454 454

455Claude Code 내에서 `/status`를 실행하여 확인하십시오. Mantle이 활성화되면 제공자 줄에 `Amazon Bedrock (Mantle)`이 표시됩니다.455Claude Code 내에서 `/status`를 실행하여 확인하십시오. Mantle이 활성화되면 제공자 줄에 `Amazon Bedrock (Mantle)`이 표시됩니다.

456 456

470 Invoke API와 함께 Mantle 실행470 Invoke API와 함께 Mantle 실행

471</h3>471</h3>

472 472

473Mantle에서 사용 가능한 모델이 현재 사용하는 모든 모델을 포함하지 않을 수 있습니다. `CLAUDE_CODE_USE_BEDROCK` 및 `CLAUDE_CODE_USE_MANTLE`을 모두 설정하면 Claude Code가 동일한 세션에서 두 엔드포인트를 모두 호출할 수 있습니다. Mantle 형식과 일치하는 모델 ID는 Mantle으로 라우팅되고 다른 모든 모델 ID는 Bedrock Invoke API로 이동합니다.473Mantle에서 사용 가능한 모델이 현재 사용하는 모든 모델을 포함하지 않을 수 있습니다. `CLAUDE_CODE_USE_BEDROCK` 및 `CLAUDE_CODE_USE_MANTLE`을 모두 설정하면 Claude Code가 동일한 세션에서 두 엔드포인트를 모두 호출할 수 있습니다. Mantle 형식과 일치하는 모델 ID는 Mantle으로 라우팅되고 다른 모든 모델 ID는 Amazon Bedrock Invoke API로 이동합니다.

474 474

475```bash theme={null}475```bash theme={null}

476export CLAUDE_CODE_USE_BEDROCK=1476export CLAUDE_CODE_USE_BEDROCK=1

516 516

517<h2 id="troubleshooting">517<h2 id="troubleshooting">

518 문제 해결518 문제 해결

540 540

541* 모델을 [추론 프로필](https://docs.aws.amazon.com/bedrock/latest/userguide/inference-profiles-support.html) ID로 지정하십시오541* 모델을 [추론 프로필](https://docs.aws.amazon.com/bedrock/latest/userguide/inference-profiles-support.html) ID로 지정하십시오

542 542

543Claude Code는 Bedrock [Invoke API](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_InvokeModelWithResponseStream.html)를 사용하며 Converse API를 지원하지 않습니다.543Claude Code는 Amazon Bedrock [Invoke API](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_InvokeModelWithResponseStream.html)를 사용하며 Converse API를 지원하지 않습니다.

544 544

545<h3 id="zero-token-counts-in-/context">545<h3 id="zero-token-counts-in-/context">

546 /context의 0 토큰 개수546 /context의 0 토큰 개수

547</h3>547</h3>

548 548

549`/context` 명령은 도구 스키마를 Bedrock count-tokens API로 전송하여 각 도구 그룹의 토큰을 계산합니다. {/* min-version: 2.1.196 */}v2.1.196 이전의 Claude Code 버전에서는 Bedrock이 스키마가 count-tokens API에서 허용하지 않는 필드를 포함하고 있어서 해당 요청을 거부했으므로 모든 도구 그룹이 0 토큰을 표시했습니다. 메시지 및 메모리 파일과 같은 분석의 다른 행은 영향을 받지 않습니다.549`/context` 명령은 도구 스키마를 Amazon Bedrock count-tokens API로 전송하여 각 도구 그룹의 토큰을 계산합니다. {/* min-version: 2.1.196 */}v2.1.196 이전의 Claude Code 버전에서는 Amazon Bedrock이 스키마가 count-tokens API에서 허용하지 않는 필드를 포함하고 있어서 해당 요청을 거부했으므로 모든 도구 그룹이 0 토큰을 표시했습니다. 메시지 및 메모리 파일과 같은 분석의 다른 행은 영향을 받지 않습니다.

550 550

551v2.1.196 이상으로 업데이트하십시오.551v2.1.196 이상으로 업데이트하십시오.

552 552

558 558

559유효한 자격 증명이 있는 Mantle 엔드포인트의 `403`은 AWS 계정이 요청한 모델에 대한 액세스 권한을 부여받지 않았음을 의미합니다. 액세스를 요청하려면 AWS 계정 팀에 문의하십시오.559유효한 자격 증명이 있는 Mantle 엔드포인트의 `403`은 AWS 계정이 요청한 모델에 대한 액세스 권한을 부여받지 않았음을 의미합니다. 액세스를 요청하려면 AWS 계정 팀에 문의하십시오.

560 560

561모델 ID를 이름으로 지정하는 `400`은 해당 모델이 Mantle에서 제공되지 않음을 의미합니다. Mantle은 표준 Bedrock 카탈로그와 별개의 자체 모델 라인업을 가지고 있으므로 `us.anthropic.claude-sonnet-4-6`과 같은 추론 프로필 ID는 작동하지 않습니다. Mantle 형식 ID를 사용하거나 [두 엔드포인트를 모두 활성화](#run-mantle-alongside-the-invoke-api)하여 Claude Code가 각 요청을 모델을 사용할 수 있는 엔드포인트로 라우팅하도록 하십시오.561모델 ID를 이름으로 지정하는 `400`은 해당 모델이 Mantle에서 제공되지 않음을 의미합니다. Mantle은 표준 Amazon Bedrock 카탈로그와 별개의 자체 모델 라인업을 가지고 있으므로 `us.anthropic.claude-sonnet-4-6`과 같은 추론 프로필 ID는 작동하지 않습니다. Mantle 형식 ID를 사용하거나 [두 엔드포인트를 모두 활성화](#run-mantle-alongside-the-invoke-api)하여 Claude Code가 각 요청을 모델을 사용할 수 있는 엔드포인트로 라우팅하도록 하십시오.

562 562

563<h2 id="additional-resources">563<h2 id="additional-resources">

564 추가 리소스564 추가 리소스

565</h2>565</h2>

566 566

567* [Bedrock 설명서](https://docs.aws.amazon.com/bedrock/)567* [Amazon Bedrock 설명서](https://docs.aws.amazon.com/bedrock/)

568* [Bedrock 가격](https://aws.amazon.com/bedrock/pricing/)568* [Amazon Bedrock 가격](https://aws.amazon.com/bedrock/pricing/)

569* [Bedrock 추론 프로필](https://docs.aws.amazon.com/bedrock/latest/userguide/inference-profiles-support.html)569* [Amazon Bedrock 추론 프로필](https://docs.aws.amazon.com/bedrock/latest/userguide/inference-profiles-support.html)

570* [Bedrock 토큰 번다운 및 할당량](https://docs.aws.amazon.com/bedrock/latest/userguide/quotas-token-burndown.html)570* [Amazon Bedrock 토큰 번다운 및 할당량](https://docs.aws.amazon.com/bedrock/latest/userguide/quotas-token-burndown.html)

571* [Claude Code on Amazon Bedrock: Quick Setup Guide](https://community.aws/content/2tXkZKrZzlrlu0KfH8gST5Dkppq/claude-code-on-amazon-bedrock-quick-setup-guide)571* [Claude Code on Amazon Bedrock: Quick Setup Guide](https://community.aws/content/2tXkZKrZzlrlu0KfH8gST5Dkppq/claude-code-on-amazon-bedrock-quick-setup-guide)

572* [Claude Code Monitoring Implementation (Bedrock)](https://github.com/aws-solutions-library-samples/guidance-for-claude-code-with-amazon-bedrock/blob/main/assets/docs/MONITORING.md)572* [Claude Code Monitoring Implementation (Amazon Bedrock)](https://github.com/aws-solutions-library-samples/guidance-for-claude-code-with-amazon-bedrock/blob/main/assets/docs/MONITORING.md)

artifacts.md +1 −1

Details

192| :----- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |192| :----- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

193| 플랜 | Pro, Max, Team 또는 Enterprise. Pro 및 Max 플랜에서는 아티팩트가 사용자에게만 비공개이며 관리자 관리가 적용되지 않습니다. Team 플랜에서는 아티팩트가 기본적으로 켜져 있습니다. Enterprise 플랜에서는 Owner가 claude.ai 관리 설정에서 [활성화](#manage-artifacts-for-your-organization)합니다. |193| 플랜 | Pro, Max, Team 또는 Enterprise. Pro 및 Max 플랜에서는 아티팩트가 사용자에게만 비공개이며 관리자 관리가 적용되지 않습니다. Team 플랜에서는 아티팩트가 기본적으로 켜져 있습니다. Enterprise 플랜에서는 Owner가 claude.ai 관리 설정에서 [활성화](#manage-artifacts-for-your-organization)합니다. |

194| 인증 | `/login`으로 claude.ai에 로그인했습니다. API 키, [게이트웨이 토큰](/ko/llm-gateway) 또는 클라우드 공급자 자격증명을 사용하는 세션은 게시할 수 없습니다. |194| 인증 | `/login`으로 claude.ai에 로그인했습니다. API 키, [게이트웨이 토큰](/ko/llm-gateway) 또는 클라우드 공급자 자격증명을 사용하는 세션은 게시할 수 없습니다. |

195| 모델 공급자 | Anthropic API. [Amazon Bedrock](/ko/amazon-bedrock), [Google Cloud Vertex AI](/ko/google-vertex-ai) 또는 [Microsoft Foundry](/ko/microsoft-foundry)에서는 사용할 수 없습니다. |195| 모델 공급자 | Anthropic API. [Amazon Bedrock](/ko/amazon-bedrock), [Google Cloud의 Agent Platform](/ko/google-vertex-ai) 또는 [Microsoft Foundry](/ko/microsoft-foundry)에서는 사용할 수 없습니다. |

196| 조직 정책 | 고객 관리 암호화 키(CMEK), HIPAA 및 [Zero Data Retention](/ko/zero-data-retention)이 조직에 대해 활성화되지 않습니다. |196| 조직 정책 | 고객 관리 암호화 키(CMEK), HIPAA 및 [Zero Data Retention](/ko/zero-data-retention)이 조직에 대해 활성화되지 않습니다. |

197| 표면 | Claude Code CLI 또는 Claude 데스크톱 앱 버전 1.13576.0 이상. [Agent SDK](/ko/agent-sdk/overview), GitHub Action 및 MCP 서버 컨텍스트에서 기본적으로 꺼져 있으며 [`CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC`](/ko/env-vars)이 설정된 경우입니다. |197| 표면 | Claude Code CLI 또는 Claude 데스크톱 앱 버전 1.13576.0 이상. [Agent SDK](/ko/agent-sdk/overview), GitHub Action 및 MCP 서버 컨텍스트에서 기본적으로 꺼져 있으며 [`CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC`](/ko/env-vars)이 설정된 경우입니다. |

198 198

authentication.md +19 −5

Details

6 6

7> Claude Code에 로그인하고 개인, 팀, 조직을 위한 인증을 구성합니다.7> Claude Code에 로그인하고 개인, 팀, 조직을 위한 인증을 구성합니다.

8 8

9Claude Code는 설정에 따라 여러 인증 방법을 지원합니다. 개별 사용자는 Claude.ai 계정으로 로그인할 수 있으며, 팀은 Claude for Teams 또는 Enterprise, Claude Console, 또는 Amazon Bedrock, Google Vertex AI, Microsoft Foundry와 같은 클라우드 제공자를 사용할 수 있습니다.9Claude Code는 설정에 따라 여러 인증 방법을 지원합니다. 개별 사용자는 Claude.ai 계정으로 로그인할 수 있으며, 팀은 Claude for Teams 또는 Enterprise, Claude Console, 또는 Amazon Bedrock, Google Cloud의 Agent Platform, Microsoft Foundry와 같은 클라우드 제공자를 사용할 수 있습니다.

10 10

11<h2 id="log-in-to-claude-code">11<h2 id="log-in-to-claude-code">

12 Claude Code에 로그인12 Claude Code에 로그인

23* **Claude Pro 또는 Max 구독**: Claude.ai 계정으로 로그인합니다. [claude.com/pricing](https://claude.com/pricing?utm_source=claude_code\&utm_medium=docs\&utm_content=authentication_pro_max)에서 구독합니다.23* **Claude Pro 또는 Max 구독**: Claude.ai 계정으로 로그인합니다. [claude.com/pricing](https://claude.com/pricing?utm_source=claude_code\&utm_medium=docs\&utm_content=authentication_pro_max)에서 구독합니다.

24* **Claude for Teams 또는 Enterprise**: 팀 관리자가 초대한 Claude.ai 계정으로 로그인합니다.24* **Claude for Teams 또는 Enterprise**: 팀 관리자가 초대한 Claude.ai 계정으로 로그인합니다.

25* **Claude Console**: Console 자격증명으로 로그인합니다. 관리자가 먼저 [초대](#claude-console-authentication)해야 합니다.25* **Claude Console**: Console 자격증명으로 로그인합니다. 관리자가 먼저 [초대](#claude-console-authentication)해야 합니다.

26* **클라우드 제공자**: 조직에서 [Amazon Bedrock](/ko/amazon-bedrock), [Google Vertex AI](/ko/google-vertex-ai), 또는 [Microsoft Foundry](/ko/microsoft-foundry)를 사용하는 경우 `claude`를 실행하기 전에 필요한 환경 변수를 설정합니다. 브라우저 로그인이 필요하지 않습니다.26* **클라우드 제공자**: 조직에서 [Amazon Bedrock](/ko/amazon-bedrock), [Google Cloud의 Agent Platform](/ko/google-vertex-ai), 또는 [Microsoft Foundry](/ko/microsoft-foundry)를 사용하는 경우 `claude`를 실행하기 전에 필요한 환경 변수를 설정합니다. 브라우저 로그인이 필요하지 않습니다.

27* **클라우드 게이트웨이**: 조직에서 자체 호스팅 [Claude 앱 게이트웨이](/ko/claude-apps-gateway)를 실행하는 경우 `/login`을 통해 회사 SSO로 로그인합니다. 게이트웨이에서 발급한 토큰이 세션의 유일한 자격증명입니다.27* **클라우드 게이트웨이**: 조직에서 자체 호스팅 [Claude 앱 게이트웨이](/ko/claude-apps-gateway)를 실행하는 경우 `/login`을 통해 회사 SSO로 로그인합니다. 게이트웨이에서 발급한 토큰이 세션의 유일한 자격증명입니다.

28 28

29Claude Code 프롬프트에서 `/logout`을 입력하여 로그아웃하고 다시 인증합니다.29Claude Code 프롬프트에서 `/logout`을 입력하여 로그아웃하고 다시 인증합니다.

40* [Claude Console](#claude-console-authentication)40* [Claude Console](#claude-console-authentication)

41* [Claude apps gateway](/ko/claude-apps-gateway), 개발자가 IdP로 로그인하고 구성한 클라우드 제공자로 추론을 라우팅하는 자체 호스팅 게이트웨이41* [Claude apps gateway](/ko/claude-apps-gateway), 개발자가 IdP로 로그인하고 구성한 클라우드 제공자로 추론을 라우팅하는 자체 호스팅 게이트웨이

42* [Amazon Bedrock](/ko/amazon-bedrock)42* [Amazon Bedrock](/ko/amazon-bedrock)

~~43* [Google Vertex AI](/ko/google-vertex-ai)~~43* [Google Cloud's Agent Platform](/ko/google-vertex-ai)

44* [Microsoft Foundry](/ko/microsoft-foundry)44* [Microsoft Foundry](/ko/microsoft-foundry)

45 45

46<h3 id="claude-for-teams-or-enterprise">46<h3 id="claude-for-teams-or-enterprise">

105 클라우드 제공자 인증105 클라우드 제공자 인증

106</h3>106</h3>

107 107

108Amazon Bedrock, Google Vertex AI 또는 Microsoft Foundry를 사용하는 팀의 경우:108Amazon Bedrock, Google Cloud's Agent Platform 또는 Microsoft Foundry를 사용하는 팀의 경우:

109 109

110<Steps>110<Steps>

111 <Step title="제공자 설정 따르기">111 <Step title="제공자 설정 따르기">

112 [Bedrock 문서](/ko/amazon-bedrock), [Vertex 문서](/ko/google-vertex-ai), 또는 [Microsoft Foundry 문서](/ko/microsoft-foundry)를 따릅니다.112 [Amazon Bedrock 문서](/ko/amazon-bedrock), [Google Cloud's Agent Platform 문서](/ko/google-vertex-ai), 또는 [Microsoft Foundry 문서](/ko/microsoft-foundry)를 따릅니다.

113 </Step>113 </Step>

114 114

115 <Step title="구성 배포">115 <Step title="구성 배포">

140 140

141`apiKeyHelper`, `ANTHROPIC_API_KEY`, `ANTHROPIC_AUTH_TOKEN`은 CLI 및 VS Code 확장 프로그램, Agent SDK, GitHub Actions를 포함하여 이를 래핑하는 표면에 적용됩니다. Claude Desktop 및 클라우드 세션은 `apiKeyHelper`를 호출하거나 이러한 환경 변수를 읽지 않습니다. 이들은 OAuth를 사용하며, [조직에서 배포한 타사 추론 구성](/ko/llm-gateway-connect#desktop-app)을 실행하는 데스크톱 세션은 해당 구성의 자격증명으로 인증합니다.141`apiKeyHelper`, `ANTHROPIC_API_KEY`, `ANTHROPIC_AUTH_TOKEN`은 CLI 및 VS Code 확장 프로그램, Agent SDK, GitHub Actions를 포함하여 이를 래핑하는 표면에 적용됩니다. Claude Desktop 및 클라우드 세션은 `apiKeyHelper`를 호출하거나 이러한 환경 변수를 읽지 않습니다. 이들은 OAuth를 사용하며, [조직에서 배포한 타사 추론 구성](/ko/llm-gateway-connect#desktop-app)을 실행하는 데스크톱 세션은 해당 구성의 자격증명으로 인증합니다.

142 142

143<h3 id="renew-an-expiring-login">

144 만료되는 로그인 갱신

145</h3>

146

147`/login`으로 생성한 로그인이 만료되기 5일 이내일 때 Claude Code는 시작 시 경고를 표시합니다: `Your login expires in 3 days · run /login to renew`. Claude Code v2.1.203 이상이 필요합니다.

148

149`/login`을 실행하여 갱신합니다. 경고는 정보 제공용이며 요청을 차단하지 않습니다: 로그인이 실제로 만료될 때까지 인증이 계속 작동합니다. 로그인 수명 자체는 변경되지 않습니다. 사전 경고는 v2.1.203이 추가한 것입니다.

150

151경고는 claude.ai 또는 Claude Console 로그인이 활성 자격증명일 때만 나타나며, 클라우드 제공자, `ANTHROPIC_API_KEY`, `ANTHROPIC_AUTH_TOKEN`, 또는 `apiKeyHelper`가 자격증명을 제공할 때는 나타나지 않습니다.

152

153조기 갱신은 무인으로 실행되는 세션에 가장 중요합니다. [에이전트 보기의 백그라운드 세션](/ko/agent-view) 또는 로그인보다 오래 지속되는 [Remote Control](/ko/remote-control) 세션은 자격증명이 만료되면 진행을 멈추고 다시 로그인할 때까지 복구할 수 없습니다.

154

143<h3 id="authentication-precedence">155<h3 id="authentication-precedence">

144 인증 우선순위156 인증 우선순위

145</h3>157</h3>

157 169

158[Claude Code on the Web](/ko/claude-code-on-the-web)은 항상 구독 자격증명을 사용합니다. 샌드박스 환경의 `ANTHROPIC_API_KEY` 및 `ANTHROPIC_AUTH_TOKEN`은 이를 재정의하지 않습니다.170[Claude Code on the Web](/ko/claude-code-on-the-web)은 항상 구독 자격증명을 사용합니다. 샌드박스 환경의 `ANTHROPIC_API_KEY` 및 `ANTHROPIC_AUTH_TOKEN`은 이를 재정의하지 않습니다.

159 171

172[Claude apps gateway](/ko/claude-apps-gateway) 세션에 서명한 것은 이 목록 외에 있습니다: Amazon Bedrock 또는 Google Cloud의 Agent Platform과 같은 제공자 선택이며 이들보다 우선합니다. 게이트웨이 세션이 존재할 때 CLI는 `CLAUDE_CODE_USE_BEDROCK`, `CLAUDE_CODE_USE_VERTEX`, 또는 `CLAUDE_CODE_USE_FOUNDRY`가 설정되어 있어도 게이트웨이 토큰으로 인증하며, 위의 베어러 토큰, API 키, `apiKeyHelper` 항목은 사용되지 않습니다.

173

160<h3 id="generate-a-long-lived-token">174<h3 id="generate-a-long-lived-token">

161 장기 토큰 생성175 장기 토큰 생성

162</h3>176</h3>

auto-mode-config.md +6 −6

Details

9[자동 모드](/ko/permission-modes#eliminate-prompts-with-auto-mode)를 사용하면 Claude Code가 각 도구 호출을 분류기를 통해 라우팅하여 권한 프롬프트 없이 실행될 수 있습니다. 분류기는 되돌릴 수 없거나 파괴적이거나 환경 외부를 대상으로 하는 모든 것을 차단합니다. 거부 및 명시적 요청 규칙은 분류기 이전에 평가되며 여전히 차단하거나 프롬프트합니다. `autoMode` 설정 블록을 사용하여 분류기에 조직이 신뢰하는 저장소, 버킷 및 도메인을 알려주면, 분류기가 일상적인 내부 작업 차단을 중지합니다.9[자동 모드](/ko/permission-modes#eliminate-prompts-with-auto-mode)를 사용하면 Claude Code가 각 도구 호출을 분류기를 통해 라우팅하여 권한 프롬프트 없이 실행될 수 있습니다. 분류기는 되돌릴 수 없거나 파괴적이거나 환경 외부를 대상으로 하는 모든 것을 차단합니다. 거부 및 명시적 요청 규칙은 분류기 이전에 평가되며 여전히 차단하거나 프롬프트합니다. `autoMode` 설정 블록을 사용하여 분류기에 조직이 신뢰하는 저장소, 버킷 및 도메인을 알려주면, 분류기가 일상적인 내부 작업 차단을 중지합니다.

10 10

11<Note>11<Note>

12 자동 모드는 Anthropic API의 모든 사용자가 사용할 수 있습니다. Amazon Bedrock, Google Cloud Vertex AI, Microsoft Foundry 및 로그인된 [Claude 앱 게이트웨이](/ko/claude-apps-gateway) 세션에서는 먼저 [`CLAUDE_CODE_ENABLE_AUTO_MODE`](/ko/permission-modes#enable-auto-mode-on-bedrock-vertex-ai-or-foundry)를 설정해야 합니다. Claude Code가 계정에서 자동 모드를 사용할 수 없다고 보고하는 경우, [전체 요구사항](/ko/permission-modes#eliminate-prompts-with-auto-mode)을 확인하세요. 여기에는 지원되는 모델과 Team 및 Enterprise 플랜의 Owner 활성화도 포함됩니다.12 자동 모드는 Anthropic API의 모든 사용자가 사용할 수 있습니다. Amazon Bedrock, Google Cloud의 Agent Platform, Microsoft Foundry 및 로그인된 [Claude 앱 게이트웨이](/ko/claude-apps-gateway) 세션에서는 먼저 [`CLAUDE_CODE_ENABLE_AUTO_MODE`](/ko/permission-modes#enable-auto-mode-on-bedrock-agent-platform-or-foundry)를 설정해야 합니다. Claude Code가 계정에서 자동 모드를 사용할 수 없다고 보고하는 경우, [전체 요구사항](/ko/permission-modes#eliminate-prompts-with-auto-mode)을 확인하세요. 여기에는 지원되는 모델과 Team 및 Enterprise 플랜의 Owner 활성화도 포함됩니다.

13</Note>13</Note>

14 14

15기본적으로 분류기는 작업 디렉토리와 현재 저장소의 구성된 원격 저장소만 신뢰합니다. 회사의 소스 제어 조직에 푸시하거나 팀 클라우드 버킷에 쓰기와 같은 작업은 `autoMode.environment`에 추가할 때까지 차단됩니다.15기본적으로 분류기는 작업 디렉토리와 현재 저장소의 구성된 원격 저장소만 신뢰합니다. 회사의 소스 제어 조직에 푸시하거나 팀 클라우드 버킷에 쓰기와 같은 작업은 `autoMode.environment`에 추가할 때까지 차단됩니다.

60 * **조직**60 * **조직**

61 * **Claude Code의 주요 용도**: 소프트웨어 개발으로 기본 설정됨61 * **Claude Code의 주요 용도**: 소프트웨어 개발으로 기본 설정됨

62 * **클라우드 제공자**62 * **클라우드 제공자**

~~63 * **저장소 가시성**: 원격 호스트 및 이름이 다르게 표시하지 않는 한 저장소는 비공개로 가정됩니다~~63 * **저장소 가시성**: 원격 호스트 및 이름이 다르게 표시하지 않는 한 저장소는 비공개로 가정됩니다. {/* min-version: 2.1.200 */}또는 대화 초반에 분류기가 읽는 가시성 확인이 공개임을 보여줍니다. 분류기는 사용자의 메시지와 Claude가 실행하는 명령을 읽으며, 그 출력은 읽지 않으므로, 증거는 저장소를 공개로 명명하는 사용자의 메시지와 같이 읽을 수 있는 것이어야 합니다. `gh repo view`의 출력만으로는 도달하지 않습니다. 트랜스크립트 증거 확인은 Claude Code v2.1.200 이상이 필요합니다.

64 * **내부 공유 / 스니펫 호스팅**: 공개 붙여넣기 및 gist 서비스는 명명할 때까지 신뢰 경계 외부로 취급됩니다64 * **내부 공유 / 스니펫 호스팅**: 공개 붙여넣기 및 gist 서비스는 명명할 때까지 신뢰 경계 외부로 취급됩니다

65 * **조직별 CLI**65 * **조직별 CLI**

66 * **비밀 관리**66 * **비밀 관리**

69 * **네트워크 태세**69 * **네트워크 태세**

70 * **보호된 배포 네임스페이스 / 환경**: 명명할 때까지 민감한 원격 대상 휴리스틱으로 폴백됩니다70 * **보호된 배포 네임스페이스 / 환경**: 명명할 때까지 민감한 원격 대상 휴리스틱으로 폴백됩니다

71 * **데이터 보존 / 기밀 해제**71 * **데이터 보존 / 기밀 해제**

72* **신뢰 슬롯**: 분류기가 경계 내부로 취급하는 것을 명명합니다. 슬롯은 신뢰할 수 있는 저장소, 소스 제어, 신뢰할 수 있는 내부 도메인, 신뢰할 수 있는 클라우드 버킷, 주요 내부 서비스 및 내부 패키지 레지스트리입니다. 저장소 및 소스 제어 항목은 기본적으로 작업 저장소와 그 구성된 원격 저장소로 설정됩니다. 다른 모든 신뢰 슬롯은 기본적으로 `None configured`로 설정되므로, 추가할 때까지 다른 것은 신뢰되지 않습니다.72* **신뢰 슬롯**: 분류기가 경계 내부로 취급하는 것을 명명합니다. 슬롯은 신뢰할 수 있는 저장소, 소스 제어, 신뢰할 수 있는 내부 도메인, 신뢰할 수 있는 클라우드 버킷, 주요 내부 서비스 및 내부 패키지 레지스트리입니다. 저장소 및 소스 제어 항목은 기본적으로 작업 저장소와 그 구성된 원격 저장소로 설정됩니다. 다른 모든 신뢰 슬롯은 기본적으로 `None configured`로 설정되므로, 추가할 때까지 다른 것은 신뢰되지 않습니다. {/* min-version: 2.1.203 */}저장소의 가시성은 기밀 자료만 범위를 지정합니다. 비공개 저장소는 기밀 자료의 허용 가능한 대상이지만, 저장소를 비공개로 만드는 것은 비밀, 개인 또는 위탁 데이터를 그 안에 지우지 않으며, 분류기는 작업 저장소 외부에서 이식되거나 재지정되거나 처음 읽은 콘텐츠를 해당 저장소 자체의 작업으로 취급하지 않습니다. 이 범위 지정은 Claude Code v2.1.203 이상이 필요합니다.

73* **민감도 슬롯**: 보호 규칙이 고위험으로 취급하는 것을 명명합니다. 슬롯은 민감한 데이터 위치 및 대상, 민감한 원격 대상 및 보호된 IaC 범위입니다. 각각은 기본적으로 광범위한 휴리스틱으로 설정되며, 예를 들어 이름에 `prod` 또는 `production`을 포함하는 모든 호스트 또는 네임스페이스를 민감한 원격 대상으로 취급하므로, 보호 규칙은 아무것도 구성하기 전에 활성화됩니다. 민감도 슬롯에서 구체적인 대상을 명명하면 휴리스틱 대신 명명된 대상에 해당 규칙이 적용됩니다.73* **민감도 슬롯**: 보호 규칙이 고위험으로 취급하는 것을 명명합니다. 슬롯은 민감한 데이터 위치 및 대상, 민감한 원격 대상 및 보호된 IaC 범위입니다. 각각은 기본적으로 광범위한 휴리스틱으로 설정되며, 예를 들어 이름에 `prod` 또는 `production`을 포함하는 모든 호스트 또는 네임스페이스를 민감한 원격 대상으로 취급하므로, 보호 규칙은 아무것도 구성하기 전에 활성화됩니다. 민감도 슬롯에서 구체적인 대상을 명명하면 휴리스틱 대신 명명된 대상에 해당 규칙이 적용됩니다.

74 74

75기본값과 함께 자신의 항목을 추가하려면 배열에 리터럴 문자열 `"$defaults"`를 포함하세요. 기본 항목은 해당 위치에 삽입되므로, 사용자 정의 항목은 기본값 앞이나 뒤에 올 수 있습니다.75기본값과 함께 자신의 항목을 추가하려면 배열에 리터럴 문자열 `"$defaults"`를 포함하세요. 기본 항목은 해당 위치에 삽입되므로, 사용자 정의 항목은 기본값 앞이나 뒤에 올 수 있습니다.

97* **클라우드 제공자 및 신뢰할 수 있는 버킷**: Claude가 읽고 쓸 수 있어야 하는 버킷 이름 또는 접두사97* **클라우드 제공자 및 신뢰할 수 있는 버킷**: Claude가 읽고 쓸 수 있어야 하는 버킷 이름 또는 접두사

98* **신뢰할 수 있는 내부 도메인**: 네트워크 내부의 API, 대시보드 및 서비스에 대한 호스트명(예: `*.internal.example.com`)98* **신뢰할 수 있는 내부 도메인**: 네트워크 내부의 API, 대시보드 및 서비스에 대한 호스트명(예: `*.internal.example.com`)

99* **주요 내부 서비스**: CI, 아티팩트 레지스트리, 내부 패키지 인덱스, 인시던트 도구99* **주요 내부 서비스**: CI, 아티팩트 레지스트리, 내부 패키지 인덱스, 인시던트 도구

100* **내부 패키지 레지스트리**: 설치가 라우팅되어야 하는 개인 npm, PyPI 또는 기타 레지스트리이므로, 공개 레지스트리를 위해 이를 우회하는 설치는 차단됩니다.100* **내부 패키지 레지스트리**: 설치가 라우팅되어야 하는 개인 npm, PyPI 또는 기타 레지스트리이므로, 공개 레지스트리를 위해 이를 우회하는 설치는 차단됩니다

101* **민감한 데이터 위치 및 대상**: 개인 데이터, 기밀 비즈니스 데이터, 자격 증명, 규제 데이터 또는 유사하게 민감한 자료를 보유하는 버킷, 데이터베이스 또는 경로, 그리고 각 위치의 데이터가 공유될 수 있는 대상이므로, 분류기가 콘텐츠에서 추측하는 대신 해당 위치를 보호합니다. {/* min-version: 2.1.195 */}{/* max-version: 2.1.197 */}Claude Code v2.1.195부터 v2.1.197까지는 이 항목을 PII / 규제 데이터 위치로 명명하고 대상 차원 없이 개인 또는 규제 데이터를 보유하는 위치만 포함합니다101* **민감한 데이터 위치 및 대상**: 개인 데이터, 기밀 비즈니스 데이터, 자격 증명, 규제 데이터 또는 유사하게 민감한 자료를 보유하는 버킷, 데이터베이스 또는 경로, 그리고 각 위치의 데이터가 공유될 수 있는 대상이므로, 분류기가 콘텐츠에서 추측하는 대신 해당 위치를 보호합니다. {/* min-version: 2.1.195 */}{/* max-version: 2.1.197 */}Claude Code v2.1.195부터 v2.1.197까지는 이 항목을 PII / 규제 데이터 위치로 명명하고 대상 차원 없이 개인 또는 규제 데이터를 보유하는 위치만 포함합니다

102* **민감한 원격 대상**: 프로덕션으로 계산되는 네임스페이스, 호스트 또는 컨테이너이므로, 원격 셸 및 포트 포워드는 명시적 승인이 필요합니다.102* **민감한 원격 대상**: 프로덕션으로 계산되는 네임스페이스, 호스트 또는 컨테이너이므로, 원격 셸 및 포트 포워드는 명시적 승인이 필요합니다

103* **보호된 IaC 범위**: 적용 또는 삭제가 항상 변경을 명명하도록 요구해야 하는 인프라 리소스입니다.103* **보호된 IaC 범위**: 적용 또는 삭제가 항상 변경을 명명하도록 요구해야 하는 인프라 리소스입니다

104* **추가 컨텍스트**: 규제 산업 제약, 다중 테넌트 인프라 또는 분류기가 위험으로 취급해야 할 사항에 영향을 미치는 규정 준수 요구사항104* **추가 컨텍스트**: 규제 산업 제약, 다중 테넌트 인프라 또는 분류기가 위험으로 취급해야 할 사항에 영향을 미치는 규정 준수 요구사항

105 105

106내부 패키지 레지스트리, 민감한 데이터 위치 및 대상, 민감한 원격 대상 및 보호된 IaC 범위 항목은 Claude Code v2.1.195 이상이 필요합니다. 이전 버전은 여전히 이를 일반 컨텍스트로 읽지만 이를 대상으로 하는 기본 제공 규칙이 없습니다.106내부 패키지 레지스트리, 민감한 데이터 위치 및 대상, 민감한 원격 대상 및 보호된 IaC 범위 항목은 Claude Code v2.1.195 이상이 필요합니다. 이전 버전은 여전히 이를 일반 컨텍스트로 읽지만 이를 대상으로 하는 기본 제공 규칙이 없습니다.

channels.md +1 −1

Details

7> 채널을 사용하여 MCP 서버에서 실행 중인 Claude Code 세션으로 메시지, 알림 및 웹훅을 푸시합니다. CI 결과, 채팅 메시지 및 모니터링 이벤트를 전달하여 Claude가 자리를 비웠을 때 반응할 수 있도록 합니다.7> 채널을 사용하여 MCP 서버에서 실행 중인 Claude Code 세션으로 메시지, 알림 및 웹훅을 푸시합니다. CI 결과, 채팅 메시지 및 모니터링 이벤트를 전달하여 Claude가 자리를 비웠을 때 반응할 수 있도록 합니다.

8 8

9<Note>9<Note>

10 채널은 [연구 미리보기](#research-preview)에 있으며 Claude Code v2.1.80 이상이 필요합니다. Anthropic 인증이 필요하며 claude.ai 또는 Console API 키를 통해 인증합니다. Amazon Bedrock, Google Vertex AI 또는 Microsoft Foundry에서는 사용할 수 없습니다. Team 및 Enterprise 조직은 [명시적으로 활성화](#enterprise-controls)해야 합니다.10 채널은 [연구 미리보기](#research-preview)에 있으며 Claude Code v2.1.80 이상이 필요합니다. Anthropic 인증이 필요하며 claude.ai 또는 Console API 키를 통해 인증합니다. Amazon Bedrock, Google Cloud의 Agent Platform 또는 Microsoft Foundry에서는 사용할 수 없습니다. Team 및 Enterprise 조직은 [명시적으로 활성화](#enterprise-controls)해야 합니다.

11</Note>11</Note>

12 12

13채널은 실행 중인 Claude Code 세션으로 이벤트를 푸시하는 MCP 서버이므로 Claude는 터미널에 없을 때 발생하는 일에 반응할 수 있습니다. 채널은 양방향일 수 있습니다. Claude는 이벤트를 읽고 동일한 채널을 통해 다시 회신합니다(채팅 브리지처럼). 이벤트는 세션이 열려 있는 동안에만 도착하므로 항상 켜진 설정의 경우 Claude를 백그라운드 프로세스 또는 지속적인 터미널에서 실행합니다.13채널은 실행 중인 Claude Code 세션으로 이벤트를 푸시하는 MCP 서버이므로 Claude는 터미널에 없을 때 발생하는 일에 반응할 수 있습니다. 채널은 양방향일 수 있습니다. Claude는 이벤트를 읽고 동일한 채널을 통해 다시 회신합니다(채팅 브리지처럼). 이벤트는 세션이 열려 있는 동안에만 도착하므로 항상 켜진 설정의 경우 Claude를 백그라운드 프로세스 또는 지속적인 터미널에서 실행합니다.

channels-reference.md +2 −2

Details

36* **채팅 플랫폼** (Telegram, Discord): 플러그인이 로컬에서 실행되고 플랫폼의 API를 폴링하여 새 메시지를 확인합니다. 누군가 봇에 DM을 보내면 플러그인이 메시지를 수신하고 Claude로 전달합니다. 노출할 URL이 없습니다.36* **채팅 플랫폼** (Telegram, Discord): 플러그인이 로컬에서 실행되고 플랫폼의 API를 폴링하여 새 메시지를 확인합니다. 누군가 봇에 DM을 보내면 플러그인이 메시지를 수신하고 Claude로 전달합니다. 노출할 URL이 없습니다.

37* **웹훅** (CI, 모니터링): 서버가 로컬 HTTP 포트에서 수신합니다. 외부 시스템이 해당 포트에 POST하고 서버가 페이로드를 Claude로 푸시합니다.37* **웹훅** (CI, 모니터링): 서버가 로컬 HTTP 포트에서 수신합니다. 외부 시스템이 해당 포트에 POST하고 서버가 페이로드를 Claude로 푸시합니다.

38 38

39<img src="https://mintlify.s3.us-west-1.amazonaws.com/claude-code/ko/images/channel-architecture.svg" alt="외부 시스템이 로컬 채널 서버에 연결되고 stdio를 통해 Claude Code와 통신하는 아키텍처 다이어그램" />39<img src="https://mintcdn.com/claude-code/9FG0ZKj9uKYiHmbi/images/channel-architecture.svg?fit=max&auto=format&n=9FG0ZKj9uKYiHmbi&q=85&s=9a037b7da80184ae49015c0256b21a1f" alt="외부 시스템이 로컬 채널 서버에 연결되고 stdio를 통해 Claude Code와 통신하는 아키텍처 다이어그램" width="600" height="220" data-path="images/channel-architecture.svg" />

40 40

41<h2 id="what-you-need">41<h2 id="what-you-need">

42 필요한 것42 필요한 것

474 474

475로컬 터미널 대화는 이 모든 과정을 통해 열려 있습니다. 터미널의 누군가가 원격 판정이 도착하기 전에 답변하면 해당 답변이 대신 적용되고 보류 중인 원격 요청이 삭제됩니다.475로컬 터미널 대화는 이 모든 과정을 통해 열려 있습니다. 터미널의 누군가가 원격 판정이 도착하기 전에 답변하면 해당 답변이 대신 적용되고 보류 중인 원격 요청이 삭제됩니다.

476 476

477<img src="https://mintlify.s3.us-west-1.amazonaws.com/claude-code/ko/images/channel-permission-relay.svg" alt="시퀀스 다이어그램: Claude Code가 permission_request 알림을 채널 서버로 보내고, 서버가 프롬프트를 채팅 앱으로 포맷하고 보내며, 인간이 판정으로 회신하고, 서버가 해당 회신을 Claude Code로 다시 권한 알림으로 구문 분석합니다" />477<img src="https://mintcdn.com/claude-code/9FG0ZKj9uKYiHmbi/images/channel-permission-relay.svg?fit=max&auto=format&n=9FG0ZKj9uKYiHmbi&q=85&s=97d57f128f0da55f105ab1e3a7e10240" alt="시퀀스 다이어그램: Claude Code가 permission_request 알림을 채널 서버로 보내고, 서버가 프롬프트를 채팅 앱으로 포맷하고 보내며, 인간이 판정으로 회신하고, 서버가 해당 회신을 Claude Code로 다시 권한 알림으로 구문 분석합니다" width="600" height="230" data-path="images/channel-permission-relay.svg" />

478 478

479<h3 id="permission-request-fields">479<h3 id="permission-request-fields">

480 권한 요청 필드480 권한 요청 필드

chrome.md +1 −1

Details

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

41 41

42<Note>42<Note>

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

44</Note>44</Note>

45 45

46<h2 id="get-started-in-the-cli">46<h2 id="get-started-in-the-cli">

claude-apps-gateway-config.md +5 −5

Details

4 4

5# Claude 앱 게이트웨이 구성5# Claude 앱 게이트웨이 구성

6 6

7> 모든 gateway.yaml 옵션에 대한 참조: 리스너 및 TLS, OIDC, 세션, Postgres 저장소, Bedrock/Claude Platform on AWS/Agent Platform/Foundry 업스트림, 모델 라우팅, 관리형 정책 및 텔레메트리.7> 모든 gateway.yaml 옵션에 대한 참조: 리스너 및 TLS, OIDC, 세션, Postgres 저장소, Amazon Bedrock, Claude Platform on AWS, Google Cloud의 Agent Platform, Microsoft Foundry 업스트림, 모델 라우팅, 관리형 정책 및 텔레메트리.

8 8

9Claude 앱 게이트웨이 배포는 하나의 YAML 파일(관례상 `gateway.yaml`)로 구성됩니다. 이 파일은 게이트웨이가 수행하는 모든 작업을 정의합니다: 어디서 수신 대기하는지, 개발자가 어떻게 로그인하는지, 추론이 어디로 가는지, 어떤 정책과 텔레메트리가 적용되는지입니다. 이 페이지는 해당 파일의 모든 옵션에 대한 참조입니다.9Claude 앱 게이트웨이 배포는 하나의 YAML 파일(관례상 `gateway.yaml`)로 구성됩니다. 이 파일은 게이트웨이가 수행하는 모든 작업을 정의합니다: 어디서 수신 대기하는지, 개발자가 어떻게 로그인하는지, 추론이 어디로 가는지, 어떤 정책과 텔레메트리가 적용되는지입니다. 이 페이지는 해당 파일의 모든 옵션에 대한 참조입니다.

10 10

26* [`oidc`](#oidc): ID 공급자(IdP), 발급자, 클라이언트, 클레임 매핑 및 로그인 가능 사용자 포함26* [`oidc`](#oidc): ID 공급자(IdP), 발급자, 클라이언트, 클레임 매핑 및 로그인 가능 사용자 포함

27* [`session`](#session): 게이트웨이가 발급하는 베어러 토큰, 비밀 및 수명 포함27* [`session`](#session): 게이트웨이가 발급하는 베어러 토큰, 비밀 및 수명 포함

28* [`store`](#store): 장치 권한 부여 및 속도 제한 카운터용 PostgreSQL28* [`store`](#store): 장치 권한 부여 및 속도 제한 카운터용 PostgreSQL

~~29* [`upstreams`](#upstreams): 추론이 가는 위치, Anthropic, Bedrock, Claude Platform on AWS, Agent Platform 또는 Foundry 여부~~29* [`upstreams`](#upstreams): 추론이 가는 위치, Anthropic, Amazon Bedrock, Claude Platform on AWS, Google Cloud의 Agent Platform 또는 Microsoft Foundry 여부

30 30

31**선택 사항 섹션:**31**선택 사항 섹션:**

32 32

131 131

132동일한 공급자의 여러 업스트림은 고유한 `name:`을 설정해야 합니다.132동일한 공급자의 여러 업스트림은 고유한 `name:`을 설정해야 합니다.

133 133

134Bedrock, Claude Platform on AWS, Agent Platform 및 Foundry 클라이언트는 시작 시 한 번 구축되며 SDK는 자격증명을 내부적으로 새로 고치므로 클라우드 자격증명을 회전해도 재시작이 필요하지 않습니다. 정적 Anthropic API 키 및 베어러는 시작 시 읽혀집니다. [Anthropic API](#anthropic-api)를 참조하세요.134Amazon Bedrock, Claude Platform on AWS, Google Cloud의 Agent Platform 및 Microsoft Foundry 클라이언트는 시작 시 한 번 구축되며 SDK는 자격증명을 내부적으로 새로 고치므로 클라우드 자격증명을 회전해도 재시작이 필요하지 않습니다. 정적 Anthropic API 키 및 베어러는 시작 시 읽혀집니다. [Anthropic API](#anthropic-api)를 참조하세요.

135 135

136<h4 id="anthropic-api">136<h4 id="anthropic-api">

137 Anthropic API137 Anthropic API

258 258

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

260 260

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

262 262

263| 설정 | 방법 |263| 설정 | 방법 |

264| ---------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |264| ---------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

406 `models`406 `models`

407</h3>407</h3>

408 408

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

410 410

411```yaml theme={null}411```yaml theme={null}

412auto_include_builtin_models: true # false: 아래 목록만 노출412auto_include_builtin_models: true # false: 아래 목록만 노출

claude-apps-gateway-deploy.md +1 −1

Details

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

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

286| 모든 Bedrock 요청이 502를 반환합니다. 로그는 `Could not load credentials from any providers` 표시 | EC2에서 IMDSv2의 기본 홉 제한 1은 컨테이너 내부에서 인스턴스 메타데이터 요청을 차단합니다. 부팅 및 `/readyz`는 AWS SDK가 클라이언트 구성이 아닌 첫 번째 요청에서 인스턴스 자격 증명을 확인하므로 어쨌든 통과합니다 | `aws ec2 modify-instance-metadata-options --instance-id <id> --http-put-response-hop-limit 2`로 홉 제한을 올리거나 시작 템플릿에서 설정하세요. 변경은 인스턴스의 모든 컨테이너에 적용됩니다. 가능한 경우 ECS 작업 역할을 선호하세요. 이는 ECS 컨테이너 자격 증명 엔드포인트에서 자격 증명을 읽고 변경을 완전히 피하거나, 노출을 제한하기 위해 전용 게이트웨이 인스턴스에 변경을 적용하세요. |286| 모든 Amazon Bedrock 요청이 502를 반환합니다. 로그는 `Could not load credentials from any providers` 표시 | EC2에서 IMDSv2의 기본 홉 제한 1은 컨테이너 내부에서 인스턴스 메타데이터 요청을 차단합니다. 부팅 및 `/readyz`는 AWS SDK가 클라이언트 구성이 아닌 첫 번째 요청에서 인스턴스 자격 증명을 확인하므로 어쨌든 통과합니다 | `aws ec2 modify-instance-metadata-options --instance-id <id> --http-put-response-hop-limit 2`로 홉 제한을 올리거나 시작 템플릿에서 설정하세요. 변경은 인스턴스의 모든 컨테이너에 적용됩니다. 가능한 경우 ECS 작업 역할을 선호하세요. 이는 ECS 컨테이너 자격 증명 엔드포인트에서 자격 증명을 읽고 변경을 완전히 피하거나, 노출을 제한하기 위해 전용 게이트웨이 인스턴스에 변경을 적용하세요. |

287| IdP 오류: unknown or unsupported scope | IdP가 인식하지 못하는 범위를 거부합니다 | `oidc.scopes`를 IdP가 허용하는 정확한 목록으로 설정하세요. `openid`를 포함해야 합니다. 기본값은 `openid profile email offline_access`입니다. |287| IdP 오류: unknown or unsupported scope | IdP가 인식하지 못하는 범위를 거부합니다 | `oidc.scopes`를 IdP가 허용하는 정확한 목록으로 설정하세요. `openid`를 포함해야 합니다. 기본값은 `openid profile email offline_access`입니다. |

288| `oidc.scopes` 설정 후 세션이 자동으로 갱신되지 않습니다 | `offline_access`가 재정의에서 삭제되었습니다 | IdP가 지원하면 `offline_access`를 다시 추가하세요. 새로고침 토큰이 없으면 개발자는 매 `session.ttl_hours`마다 브라우저 로그인을 다시 실행합니다. |288| `oidc.scopes` 설정 후 세션이 자동으로 갱신되지 않습니다 | `offline_access`가 재정의에서 삭제되었습니다 | IdP가 지원하면 `offline_access`를 다시 추가하세요. 새로고침 토큰이 없으면 개발자는 매 `session.ttl_hours`마다 브라우저 로그인을 다시 실행합니다. |

claude-apps-gateway-on-gcp.md +5 −5

Details

17</h2>17</h2>

18 18

19<Frame>19<Frame>

20 <img src="https://mintcdn.com/claude-code/-uq-4JE0W_JO5Er5/images/claude-gateway-gcp-architecture.svg?fit=max&auto=format&n=-uq-4JE0W_JO5Er5&q=85&s=cb705151c69128ac0da235852d5600ab" alt="Google Cloud의 Claude 앱 게이트웨이 다이어그램: Claude Code 클라이언트는 HTTPS를 통해 게이트웨이(Cloud Run 또는 GKE)에 연결되며, 이는 세션 상태를 위한 프라이빗 IP Cloud SQL 데이터베이스와 함께 VPC 내부에서 실행됩니다. 게이트웨이는 OIDC를 통해 Google Workspace에 대해 사용자에게 로그인하도록 하고, Secret Manager에서 구성 및 비밀을 읽고, 모델 요청을 Agent Platform으로 전달하며, 배포 시 Artifact Registry에서 이미지를 가져옵니다." width="760" height="400" data-path="images/claude-gateway-gcp-architecture.svg" />20 <img src="https://mintcdn.com/claude-code/-uq-4JE0W_JO5Er5/images/claude-gateway-gcp-architecture.svg?fit=max&auto=format&n=-uq-4JE0W_JO5Er5&q=85&s=cb705151c69128ac0da235852d5600ab" alt="Google Cloud의 Claude 앱 게이트웨이 다이어그램: Claude Code 클라이언트는 HTTPS를 통해 게이트웨이(Cloud Run 또는 GKE)에 연결되며, 이는 세션 상태를 위한 프라이빗 IP Cloud SQL 데이터베이스와 함께 VPC 내부에서 실행됩니다. 게이트웨이는 OIDC를 통해 Google Workspace에 대해 사용자에게 로그인하도록 하고, Secret Manager에서 구성 및 비밀을 읽고, 모델 요청을 Google Cloud의 Agent Platform으로 전달하며, 배포 시 Artifact Registry에서 이미지를 가져옵니다." width="760" height="400" data-path="images/claude-gateway-gcp-architecture.svg" />

21</Frame>21</Frame>

22 22

23참조 구성은 다음을 프로비저닝합니다:23참조 구성은 다음을 프로비저닝합니다:

80 </Step>80 </Step>

81 81

82 <Step title="서비스 계정 생성 및 IAM 권한 부여">82 <Step title="서비스 계정 생성 및 IAM 권한 부여">

83 게이트웨이는 Agent Platform을 호출할 권한이 있는 전용 서비스 계정으로 실행됩니다. VPC를 통해 Cloud SQL에 도달하는 암호 사용자이므로 Cloud SQL IAM 역할이 필요하지 않습니다:83 게이트웨이는 Google Cloud의 Agent Platform을 호출할 권한이 있는 전용 서비스 계정으로 실행됩니다. VPC를 통해 Cloud SQL에 도달하는 암호 사용자이므로 Cloud SQL IAM 역할이 필요하지 않습니다:

84 84

85 ```bash theme={null}85 ```bash theme={null}

86 gcloud iam service-accounts create claude-gateway --display-name="Claude apps gateway"86 gcloud iam service-accounts create claude-gateway --display-name="Claude apps gateway"

141 </Step>141 </Step>

142 142

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

144 `upstreams` 블록은 `auth: {}`를 사용하여 Agent Platform을 가리키므로 게이트웨이는 런타임 서비스 계정의 Application Default Credentials를 통해 인증합니다. 모든 필드는 [구성 참조](/ko/claude-apps-gateway-config)를 참조하세요.144 `upstreams` 블록은 `auth: {}`를 사용하여 Google Cloud의 Agent Platform을 가리키므로 게이트웨이는 런타임 서비스 계정의 Application Default Credentials를 통해 인증합니다. 모든 필드는 [구성 참조](/ko/claude-apps-gateway-config)를 참조하세요.

145 145

146 두 개의 `listen` 필드는 게이트웨이 앞에 무엇이 있는지에 따라 다릅니다:146 두 개의 `listen` 필드는 게이트웨이 앞에 무엇이 있는지에 따라 다릅니다:

147 147

226 --no-invoker-iam-check226 --no-invoker-iam-check

227 ```227 ```

228 228

229 Direct VPC egress(`--network`, `--subnet`, `--vpc-egress=private-ranges-only`)를 통해 서비스는 Cloud SQL 프라이빗 IP에 직접 도달할 수 있습니다. Agent Platform 엔드포인트 및 `accounts.google.com`에 대한 공개 egress는 VPC를 통하지 않고 인터넷으로 직접 이동하므로 Cloud NAT이 필요하지 않습니다.229 Direct VPC egress(`--network`, `--subnet`, `--vpc-egress=private-ranges-only`)를 통해 서비스는 Cloud SQL 프라이빗 IP에 직접 도달할 수 있습니다. Google Cloud의 Agent Platform 엔드포인트 및 `accounts.google.com`에 대한 공개 egress는 VPC를 통하지 않고 인터넷으로 직접 이동하므로 Cloud NAT이 필요하지 않습니다.

230 230

231 invoker IAM 확인은 열려 있거나 비활성화되어야 합니다. 게이트웨이는 자체 OIDC를 실행하고 클라이언트는 GCP 토큰을 가지지 않으므로 Cloud Run의 invoker 확인은 인증되지 않은 요청을 허용해야 합니다. 게이트웨이의 OIDC 로그인은 컨테이너에 도달하면 요청을 인증하며, `allowed_email_domains`는 어떤 도메인이 로그인할 수 있는지를 제어합니다.231 invoker IAM 확인은 열려 있거나 비활성화되어야 합니다. 게이트웨이는 자체 OIDC를 실행하고 클라이언트는 GCP 토큰을 가지지 않으므로 Cloud Run의 invoker 확인은 인증되지 않은 요청을 허용해야 합니다. 게이트웨이의 OIDC 로그인은 컨테이너에 도달하면 요청을 인증하며, `allowed_email_domains`는 어떤 도메인이 로그인할 수 있는지를 제어합니다.

232 232

318| `--no-invoker-iam-check`가 `invoker_iam_disabled is not currently available`로 거부됨 | `constraints/run.managed.requireInvokerIam`에 의해 차단됨 | `--allow-unauthenticated`를 사용합니다. `constraints/iam.allowedPolicyMemberDomains`를 통한 Domain Restricted Sharing도 차단하면 GKE 트랙을 사용하세요. 이는 `allUsers` 바인딩 없이 네트워크 계층에서 게이트웨이를 노출합니다. |318| `--no-invoker-iam-check`가 `invoker_iam_disabled is not currently available`로 거부됨 | `constraints/run.managed.requireInvokerIam`에 의해 차단됨 | `--allow-unauthenticated`를 사용합니다. `constraints/iam.allowedPolicyMemberDomains`를 통한 Domain Restricted Sharing도 차단하면 GKE 트랙을 사용하세요. 이는 `allUsers` 바인딩 없이 네트워크 계층에서 게이트웨이를 노출합니다. |

320| 게이트웨이 부팅이 Cloud Run의 Postgres 연결 타임아웃 오류로 종료됨 | 서비스가 VPC에 연결되지 않았거나 Cloud SQL이 해당 VPC에 프라이빗 IP가 없음. 저장소는 5초 후 대기를 중지 | Direct VPC egress를 위해 `--network` 및 `--subnet`으로 배포하고 Cloud SQL 인스턴스를 `--no-assign-ip` 및 동일한 VPC를 가리키는 `--network`로 생성 |320| 게이트웨이 부팅이 Cloud Run의 Postgres 연결 타임아웃 오류로 종료됨 | 서비스가 VPC에 연결되지 않았거나 Cloud SQL이 해당 VPC에 프라이빗 IP가 없음. 저장소는 5초 후 대기를 중지 | Direct VPC egress를 위해 `--network` 및 `--subnet`으로 배포하고 Cloud SQL 인스턴스를 `--no-assign-ip` 및 동일한 VPC를 가리키는 `--network`로 생성 |

321| Agent Platform 요청이 `403 PERMISSION_DENIED`를 반환 | 런타임이 `claude-gateway` 서비스 계정을 사용하지 않거나 모델이 프로젝트의 Model Garden에서 활성화되지 않음 | Cloud Run에서 `--service-account`를 설정하거나 GKE에서 Workload Identity를 바인딩하고 각 Claude 모델을 대상 지역의 Model Garden에서 활성화 |321| Google Cloud의 Agent Platform 요청이 `403 PERMISSION_DENIED`를 반환 | 런타임이 `claude-gateway` 서비스 계정을 사용하지 않거나 모델이 프로젝트의 Model Garden에서 활성화되지 않음 | Cloud Run에서 `--service-account`를 설정하거나 GKE에서 Workload Identity를 바인딩하고 각 Claude 모델을 대상 지역의 Model Garden에서 활성화 |

322| 스트리밍 응답이 고정 기간 후 차단됨 | 프론트 엔드 요청 타임아웃: GKE Ingress 뒤의 로드 밸런서 백엔드 서비스는 기본적으로 30초이고 Cloud Run은 300초 | GKE에서 `timeoutSec`이 높은 BackendConfig를 연결하거나 Cloud Run에서 `--timeout=3600`으로 배포 |322| 스트리밍 응답이 고정 기간 후 차단됨 | 프론트 엔드 요청 타임아웃: GKE Ingress 뒤의 로드 밸런서 백엔드 서비스는 기본적으로 30초이고 Cloud Run은 300초 | GKE에서 `timeoutSec`이 높은 BackendConfig를 연결하거나 Cloud Run에서 `--timeout=3600`으로 배포 |

323 323

324<h2 id="next-steps">324<h2 id="next-steps">

claude-apps-gateway-spend-limits.md +2 −2

Details

61 61

62각 응답 후 사용량 미터는 응답에서 토큰 수를 읽고 USD 정가로 가격을 책정한 후 세 기간 버킷 모두에 대해 Postgres 카운터를 증가시킵니다. 미터는 스트림의 단일 리더이므로 클라이언트의 바이트는 손상되지 않으며 미터링 실패는 응답을 손상시키지 않습니다.62각 응답 후 사용량 미터는 응답에서 토큰 수를 읽고 USD 정가로 가격을 책정한 후 세 기간 버킷 모두에 대해 Postgres 카운터를 증가시킵니다. 미터는 스트림의 단일 리더이므로 클라이언트의 바이트는 손상되지 않으며 미터링 실패는 응답을 손상시키지 않습니다.

63 63

64지출 한도는 토큰 수에서 USD 정가로 지출을 추정합니다. 이는 차단기이지 송장이 아닙니다. 권위 있는 청구를 위해 Anthropic Usage & Cost Admin API, Bedrock의 호출 로그 또는 Google Cloud의 Cloud Monitoring과 같은 공급자의 자체 사용량 보고에 대해 조정합니다.64지출 한도는 토큰 수에서 USD 정가로 지출을 추정합니다. 이는 차단기이지 송장이 아닙니다. 권위 있는 청구를 위해 Anthropic Usage & Cost Admin API, Amazon Bedrock의 호출 로그 또는 Google Cloud의 Cloud Monitoring과 같은 공급자의 자체 사용량 보고에 대해 조정합니다.

65 65

66가격 책정은 Claude Code CLI가 자체 비용 표시에 사용하는 것과 동일한 테이블을 사용하며, Anthropic, Bedrock (`us.anthropic.…-v1:0`), Agent Platform (`claude-…@date`) 및 Foundry ID 형식 전체에서 동일한 모델 ID 정규화를 사용합니다. Foundry 배포 이름 또는 추론 프로필 ARN과 같이 테이블이 배치할 수 없는 모델 ID는 0이 아닌 미알려진 모델 기본 계층인 백만 입력/출력 토큰당 $5/$25로 가격이 책정되므로 인식되지 않는 ID는 미계량으로 이동하여 한도를 우회할 수 없습니다. 게이트웨이는 부팅 시 및 런타임에 ID당 한 번 경고합니다.66가격 책정은 Claude Code CLI가 자체 비용 표시에 사용하는 것과 동일한 테이블을 사용하며, Anthropic, Amazon Bedrock (`us.anthropic.…-v1:0`), Google Cloud의 Agent Platform (`claude-…@date`) 및 Microsoft Foundry ID 형식 전체에서 동일한 모델 ID 정규화를 사용합니다. Microsoft Foundry 배포 이름 또는 추론 프로필 ARN과 같이 테이블이 배치할 수 없는 모델 ID는 0이 아닌 미알려진 모델 기본 계층인 백만 입력/출력 토큰당 \$5/\$25로 가격이 책정되므로 인식되지 않는 ID는 미계량으로 이동하여 한도를 우회할 수 없습니다. 게이트웨이는 부팅 시 및 런타임에 ID당 한 번 경고합니다.

67 67

68클라이언트 중단도 청구됩니다. 업스트림은 스트림의 터미널 프레임에서만 출력 토큰을 보고하므로 중단된 스트림은 이를 전달하지 않습니다. 미터는 스트림된 콘텐츠 크기에서 보수적인 하한 추정값(토큰당 약 4자)을 유지하고 터미널 사용량 프레임이 누락된 경우에만 청구합니다. 완전한 스트림은 항상 업스트림 보고 수를 청구합니다. 이 없이 제한된 개발자는 출력을 스트림하고 끝나기 직전에 각 요청을 중단하여 계산되지 않고 지출할 수 있습니다.68클라이언트 중단도 청구됩니다. 업스트림은 스트림의 터미널 프레임에서만 출력 토큰을 보고하므로 중단된 스트림은 이를 전달하지 않습니다. 미터는 스트림된 콘텐츠 크기에서 보수적인 하한 추정값(토큰당 약 4자)을 유지하고 터미널 사용량 프레임이 누락된 경우에만 청구합니다. 완전한 스트림은 항상 업스트림 보고 수를 청구합니다. 이 없이 제한된 개발자는 출력을 스트림하고 끝나기 직전에 각 요청을 중단하여 계산되지 않고 지출할 수 있습니다.

69 69

claude-code-on-the-web.md +20 −20

Details

4 4

5# 웹에서 Claude Code 사용하기5# 웹에서 Claude Code 사용하기

6 6

7> 클라우드 환경, 설정 스크립트, 네트워크 액세스 및 Docker를 Anthropic의 샌드박스에서 구성합니다. `--remote` 및 `--teleport`를 사용하여 웹과 터미널 간에 세션을 이동합니다.7> 클라우드 환경, 설정 스크립트, 네트워크 액세스 및 Docker를 Anthropic의 샌드박스에서 구성합니다. `--cloud` 및 `--teleport`를 사용하여 웹과 터미널 간에 세션을 이동합니다.

8 8

9<Note>9<Note>

10 웹에서 Claude Code는 Pro, Max 및 Team 사용자, 그리고 프리미엄 시트 또는 Chat + Claude Code 시트가 있는 Enterprise 사용자를 위한 연구 미리보기 상태입니다.10 웹에서 Claude Code는 Pro, Max 및 Team 사용자, 그리고 프리미엄 시트 또는 Chat + Claude Code 시트가 있는 Enterprise 사용자를 위한 연구 미리보기 상태입니다.

22* [클라우드 환경](#the-cloud-environment): 어떤 구성이 이월되는지, 어떤 도구가 설치되어 있는지, 환경을 구성하는 방법22* [클라우드 환경](#the-cloud-environment): 어떤 구성이 이월되는지, 어떤 도구가 설치되어 있는지, 환경을 구성하는 방법

23* [설정 스크립트](#setup-scripts) 및 종속성 관리23* [설정 스크립트](#setup-scripts) 및 종속성 관리

24* [네트워크 액세스](#network-access): 수준, 프록시 및 기본 허용 목록24* [네트워크 액세스](#network-access): 수준, 프록시 및 기본 허용 목록

~~25* [`--remote` 및 `--teleport`를 사용하여 웹과 터미널 간에 작업 이동](#move-tasks-between-web-and-terminal)~~25* [`--cloud` 및 `--teleport`를 사용하여 웹과 터미널 간에 작업 이동](#move-tasks-between-web-and-terminal)

26* [세션 작업](#work-with-sessions): 검토, 공유, 보관, 삭제26* [세션 작업](#work-with-sessions): 검토, 공유, 보관, 삭제

27* [Pull request 자동 수정](#auto-fix-pull-requests): CI 실패 및 검토 주석에 자동으로 응답27* [Pull request 자동 수정](#auto-fix-pull-requests): CI 실패 및 검토 주석에 자동으로 응답

28* [보안 및 격리](#security-and-isolation): 세션이 어떻게 격리되는지28* [보안 및 격리](#security-and-isolation): 세션이 어떻게 격리되는지

180환경은 [네트워크 액세스](#network-access), 환경 변수 및 세션이 시작되기 전에 실행되는 [설정 스크립트](#setup-scripts)를 제어합니다. 구성 없이 사용 가능한 것은 [설치된 도구](#installed-tools)를 참조하세요. 웹 인터페이스 또는 터미널에서 환경을 관리할 수 있습니다:180환경은 [네트워크 액세스](#network-access), 환경 변수 및 세션이 시작되기 전에 실행되는 [설정 스크립트](#setup-scripts)를 제어합니다. 구성 없이 사용 가능한 것은 [설치된 도구](#installed-tools)를 참조하세요. 웹 인터페이스 또는 터미널에서 환경을 관리할 수 있습니다:

181 181

182| 작업 | 방법 |182| 작업 | 방법 |

183| :----------------- | :------------------------------------------------------------------------------------------------------------------ |183| :-------------------- | :------------------------------------------------------------------------------------------------------------------ |

184| 환경 추가 | 현재 환경을 선택하여 선택기를 열고 **Add environment**를 선택합니다. 대화 상자에는 이름, 네트워크 액세스 수준, 환경 변수 및 설정 스크립트가 포함됩니다. |184| 환경 추가 | 현재 환경을 선택하여 선택기를 열고 **환경 추가**를 선택합니다. 대화 상자에는 이름, 네트워크 액세스 수준, 환경 변수 및 설정 스크립트가 포함됩니다. |

185| 환경 편집 | 클라우드 아이콘을 선택하여 현재 환경의 이름을 표시하고 선택기를 열고, 환경 위에 마우스를 올리고, 오른쪽에 나타나는 설정 아이콘을 클릭합니다. |185| 환경 편집 | 클라우드 아이콘을 선택하여 현재 환경의 이름을 표시하고 선택기를 열고, 환경 위에 마우스를 올리고, 오른쪽에 나타나는 설정 아이콘을 클릭합니다. |

186| 환경 보관 | 환경을 편집하기 위해 열고 **Archive**를 선택합니다. 보관된 환경은 선택기에서 숨겨지지만 기존 세션은 계속 실행됩니다. |186| 환경 보관 | 환경을 편집하기 위해 열고 **보관**을 선택합니다. 보관된 환경은 선택기에서 숨겨지지만 기존 세션은 계속 실행됩니다. |

187| `--remote`의 기본값 설정 | 터미널에서 `/remote-env`를 실행합니다. 단일 환경이 있으면 이 명령은 현재 구성을 표시합니다. `/remote-env`는 기본값만 선택합니다. 웹 인터페이스에서 환경을 추가, 편집 및 보관합니다. |187| CLI 클라우드 세션의 기본 환경 설정 | 터미널에서 `/remote-env`를 실행합니다. 단일 환경이 있으면 이 명령은 현재 구성을 표시합니다. `/remote-env`는 기본값만 선택합니다. 웹 인터페이스에서 환경을 추가, 편집 및 보관합니다. |

188 188

189환경 변수는 `.env` 형식을 사용하며 한 줄에 하나의 `KEY=value` 쌍입니다. 따옴표는 값의 일부로 저장되므로 값을 따옴표로 감싸지 마세요. 이 예제는 세 개의 변수를 정의합니다:189환경 변수는 `.env` 형식을 사용하며 한 줄에 하나의 `KEY=value` 쌍입니다. 따옴표는 값의 일부로 저장되므로 값을 따옴표로 감싸지 마세요. 이 예제는 세 개의 변수를 정의합니다:

190 190

627이러한 워크플로우는 동일한 claude.ai 계정에 로그인한 [Claude Code CLI](/ko/quickstart)가 필요합니다. 터미널에서 새 클라우드 세션을 시작하거나 클라우드 세션을 터미널로 가져와 로컬에서 계속할 수 있습니다. 클라우드 세션은 노트북을 닫아도 유지되며, Claude 모바일 앱을 포함한 어디서나 모니터링할 수 있습니다.627이러한 워크플로우는 동일한 claude.ai 계정에 로그인한 [Claude Code CLI](/ko/quickstart)가 필요합니다. 터미널에서 새 클라우드 세션을 시작하거나 클라우드 세션을 터미널로 가져와 로컬에서 계속할 수 있습니다. 클라우드 세션은 노트북을 닫아도 유지되며, Claude 모바일 앱을 포함한 어디서나 모니터링할 수 있습니다.

628 628

629<Note>629<Note>

630 CLI에서 세션 핸드오프는 일방향입니다: `--teleport`로 클라우드 세션을 터미널로 가져올 수 있지만 기존 터미널 세션을 웹으로 푸시할 수 없습니다. `--remote` 플래그는 현재 저장소에 대한 새로운 클라우드 세션을 생성합니다. [Desktop 앱](/ko/desktop#continue-in-another-surface)은 로컬 세션을 웹으로 보낼 수 있는 Continue in 메뉴를 제공합니다.630 CLI에서 세션 핸드오프는 일방향입니다: `--teleport`로 클라우드 세션을 터미널로 가져올 수 있지만 기존 터미널 세션을 웹으로 푸시할 수 없습니다. `--cloud` 플래그는 현재 저장소에 대한 새로운 클라우드 세션을 생성합니다. [Desktop 앱](/ko/desktop#continue-in-another-surface)은 로컬 세션을 웹으로 보낼 수 있는 Continue in 메뉴를 제공합니다.

631</Note>631</Note>

632 632

633<h3 id="from-terminal-to-web">633<h3 id="from-terminal-to-web">

634 터미널에서 웹으로634 터미널에서 웹으로

635</h3>635</h3>

636 636

637`--remote` 플래그로 명령줄에서 클라우드 세션을 시작하세요:637`--cloud` 플래그로 명령줄에서 클라우드 세션을 시작하세요:

638 638

639```bash theme={null}639```bash theme={null}

640claude --remote "Fix the authentication bug in src/auth/login.ts"640claude --cloud "Fix the authentication bug in src/auth/login.ts"

641```641```

642 642

643이렇게 하면 claude.ai에서 새 클라우드 세션이 생성됩니다. 세션은 현재 디렉토리의 GitHub 원격을 현재 분기에서 복제하므로, VM이 머신이 아닌 GitHub에서 복제하기 때문에 로컬 커밋이 있으면 먼저 푸시하세요. `--remote`는 한 번에 하나의 저장소에서 작동합니다. 작업은 클라우드에서 실행되는 동안 로컬에서 계속 작업할 수 있습니다.643이렇게 하면 claude.ai에서 새 클라우드 세션이 생성됩니다. 세션은 현재 디렉토리의 GitHub 원격을 현재 분기에서 복제하므로, VM이 머신이 아닌 GitHub에서 복제하기 때문에 로컬 커밋이 있으면 먼저 푸시하세요. `--cloud`는 한 번에 하나의 저장소에서 작동합니다. 작업은 클라우드에서 실행되는 동안 로컬에서 계속 작업할 수 있습니다. 더 이상 사용되지 않는 `--remote` 표기법은 여전히 `--cloud`의 더 이상 사용되지 않는 별칭으로 작동합니다.

644 644

645{/* min-version: 2.1.195 */}v2.1.195부터 CLI는 저장소 복제 및 [설정 스크립트](#setup-scripts) 실행과 같은 설정 단계의 라이브 체크리스트를 표시하며, 클라우드 컨테이너가 시작됩니다. 컨테이너가 프로비저닝되는 동안 입력한 메시지는 큐에 저장되었다가 세션이 준비되면 전송됩니다.645{/* min-version: 2.1.195 */}v2.1.195부터 CLI는 저장소 복제 및 [설정 스크립트](#setup-scripts) 실행과 같은 설정 단계의 라이브 체크리스트를 표시하며, 클라우드 컨테이너가 시작됩니다. 컨테이너가 프로비저닝되는 동안 입력한 메시지는 큐에 저장되었다가 세션이 준비되면 전송됩니다.

646 646

647<Note>647<Note>

648 `--remote`는 클라우드 세션을 생성합니다. `--remote-control`은 관련이 없습니다: 로컬 CLI 세션을 노출하여 웹에서 모니터링할 수 있습니다. [Remote Control](/ko/remote-control)을 참조하세요.648 `--cloud`는 클라우드 세션을 생성합니다. `--remote-control`은 관련이 없습니다: 로컬 CLI 세션을 노출하여 웹에서 모니터링할 수 있습니다. [Remote Control](/ko/remote-control)을 참조하세요.

649</Note>649</Note>

650 650

651Claude Code CLI에서 `/tasks`를 사용하여 진행 상황을 확인하거나 claude.ai 또는 Claude 모바일 앱에서 세션을 열어 직접 상호 작용하세요. 여기서 Claude를 조종하고, 피드백을 제공하거나, 다른 대화처럼 질문에 답변할 수 있습니다.651Claude Code CLI에서 `/tasks`를 사용하여 진행 상황을 확인하거나 claude.ai 또는 Claude 모바일 앱에서 세션을 열어 직접 상호 작용하세요. 여기서 Claude를 조종하고, 피드백을 제공하거나, 다른 대화처럼 질문에 답변할 수 있습니다.

663Plan Mode에서 Claude는 파일을 읽고, 명령을 실행하여 탐색하고, 소스 코드를 편집하지 않고 계획을 제안합니다. 계획에 만족하면 저장소에 저장하고, 커밋하고, 푸시하여 클라우드 VM이 복제할 수 있도록 한 다음 자율 실행을 위해 클라우드 세션을 시작하세요:663Plan Mode에서 Claude는 파일을 읽고, 명령을 실행하여 탐색하고, 소스 코드를 편집하지 않고 계획을 제안합니다. 계획에 만족하면 저장소에 저장하고, 커밋하고, 푸시하여 클라우드 VM이 복제할 수 있도록 한 다음 자율 실행을 위해 클라우드 세션을 시작하세요:

664 664

665```bash theme={null}665```bash theme={null}

666claude --remote "Execute the migration plan in docs/migration-plan.md"666claude --cloud "Execute the migration plan in docs/migration-plan.md"

667```667```

668 668

669이 패턴은 Claude가 클라우드에서 자율적으로 실행되도록 하면서 전략에 대한 제어를 제공합니다.669이 패턴은 Claude가 클라우드에서 자율적으로 실행되도록 하면서 전략에 대한 제어를 제공합니다.

670 670

671**ultraplan으로 클라우드에서 계획**: 웹 세션 자체에서 계획을 작성하고 검토하려면 [ultraplan](/ko/ultraplan)을 사용하세요. Claude는 웹에서 Claude Code on the web에서 계획을 생성하는 동안 계속 작업하고, 브라우저에서 섹션에 주석을 달고 원격으로 실행하거나 계획을 터미널로 다시 보낼 수 있습니다.671**ultraplan으로 클라우드에서 계획**: 웹 세션 자체에서 계획을 작성하고 검토하려면 [ultraplan](/ko/ultraplan)을 사용하세요. Claude는 웹에서 Claude Code on the web에서 계획을 생성하는 동안 계속 작업하고, 브라우저에서 섹션에 주석을 달고 원격으로 실행하거나 계획을 터미널로 다시 보낼 수 있습니다.

672 672

673**작업을 병렬로 실행**: 각 `--remote` 명령은 독립적으로 실행되는 자체 클라우드 세션을 생성합니다. 여러 작업을 시작할 수 있으며 모두 별도의 세션에서 동시에 실행됩니다:673**작업을 병렬로 실행**: 각 `--cloud` 명령은 독립적으로 실행되는 자체 클라우드 세션을 생성합니다. 여러 작업을 시작할 수 있으며 모두 별도의 세션에서 동시에 실행됩니다:

674 674

675```bash theme={null}675```bash theme={null}

676claude --remote "Fix the flaky test in auth.spec.ts"676claude --cloud "Fix the flaky test in auth.spec.ts"

677claude --remote "Update the API documentation"677claude --cloud "Update the API documentation"

678claude --remote "Refactor the logger to use structured output"678claude --cloud "Refactor the logger to use structured output"

679```679```

680 680

681Claude Code CLI에서 `/tasks`로 모든 세션을 모니터링하세요. 세션이 완료되면 웹 인터페이스에서 PR을 생성하거나 [세션을 텔레포트](#from-web-to-terminal)하여 터미널에서 계속 작업할 수 있습니다.681Claude Code CLI에서 `/tasks`로 모든 세션을 모니터링하세요. 세션이 완료되면 웹 인터페이스에서 PR을 생성하거나 [세션을 텔레포트](#from-web-to-terminal)하여 터미널에서 계속 작업할 수 있습니다.

684 GitHub 없이 로컬 저장소 보내기684 GitHub 없이 로컬 저장소 보내기

685</h4>685</h4>

686 686

687GitHub에 연결되지 않은 저장소에서 `claude --remote`를 실행하면 Claude Code가 로컬 저장소를 번들로 만들어 클라우드 세션에 직접 업로드합니다. 번들에는 모든 분기의 전체 저장소 기록과 추적된 파일에 대한 커밋되지 않은 변경 사항이 포함됩니다.687GitHub에 연결되지 않은 저장소에서 `claude --cloud`를 실행하면 Claude Code가 로컬 저장소를 번들로 만들어 클라우드 세션에 직접 업로드합니다. 번들에는 모든 분기의 전체 저장소 기록과 추적된 파일에 대한 커밋되지 않은 변경 사항이 포함됩니다.

688 688

689GitHub 액세스를 사용할 수 없을 때 이 폴백이 자동으로 활성화됩니다. GitHub가 연결되어 있어도 강제하려면 `CCR_FORCE_BUNDLE=1`을 설정하세요:689GitHub 액세스를 사용할 수 없을 때 이 폴백이 자동으로 활성화됩니다. GitHub가 연결되어 있어도 강제하려면 `CCR_FORCE_BUNDLE=1`을 설정하세요:

690 690

691```bash theme={null}691```bash theme={null}

692CCR_FORCE_BUNDLE=1 claude --remote "Run the test suite and fix any failures"692CCR_FORCE_BUNDLE=1 claude --cloud "Run the test suite and fix any failures"

693```693```

694 694

695번들된 저장소는 이러한 제한을 충족해야 합니다:695번들된 저장소는 이러한 제한을 충족해야 합니다:

731 `--teleport`를 사용할 수 없음731 `--teleport`를 사용할 수 없음

732</h4>732</h4>

733 733

734텔레포트는 claude.ai 구독 인증이 필요합니다. API 키, Bedrock, Vertex AI 또는 Microsoft Foundry를 통해 인증된 경우 `/login`을 실행하여 대신 claude.ai 계정으로 로그인하세요. 이미 claude.ai를 통해 로그인했는데 `--teleport`를 여전히 사용할 수 없으면 조직이 클라우드 세션을 비활성화했을 수 있습니다.734텔레포트는 claude.ai 구독 인증이 필요합니다. API 키, Amazon Bedrock, Google Cloud의 Agent Platform 또는 Microsoft Foundry를 통해 인증된 경우 `/login`을 실행하여 대신 claude.ai 계정으로 로그인하세요. 이미 claude.ai를 통해 로그인했는데 `--teleport`를 여전히 사용할 수 없으면 조직이 클라우드 세션을 비활성화했을 수 있습니다.

735 735

736<h2 id="work-with-sessions">736<h2 id="work-with-sessions">

737 세션 작업737 세션 작업

743 컨텍스트 관리743 컨텍스트 관리

744</h3>744</h3>

745 745

746클라우드 세션은 텍스트 출력을 생성하는 [기본 제공 명령](/ko/commands)을 지원합니다. `/model` 또는 `/config`와 같이 대화형 터미널 선택기를 여는 명령은 사용할 수 없습니다.746클라우드 세션은 텍스트 출력을 생성하는 [기본 제공 명령](/ko/commands)을 지원합니다. `/plugin` 또는 `/resume`과 같이 터미널 인터페이스에서만 실행되는 명령은 사용할 수 없습니다. {/* min-version: 2.1.205 */}`/model`, `/effort`, `/fast`, `/color`, `/rename`은 터미널 선택기 또는 슬라이더를 열지 않고 대신 인수로 값을 사용하여 작동합니다(예: `/model sonnet`). 인수 형식은 세션의 환경에서 Claude Code v2.1.205 이상이 필요하며 각 명령의 [가용성 참고 사항](/ko/commands#all-commands)을 따릅니다. 따라서 `/effort`는 모델의 [launch-default effort hold](/ko/model-config#adjust-effort-level)가 적용 중일 때 `Not applied`를 보고하고 `/fast`는 빠른 모드가 켜진 상태로 시작된 세션에서만 작동합니다. `/config`는 `key=value`를 전달할 때 설정을 지정합니다.

747 747

748컨텍스트 관리 특히:748컨텍스트 관리 특히:

749 749

claude-platform-on-aws.md +1 −1

Details

270 270

271`ANTHROPIC_AWS_WORKSPACE_ID`는 필수이며 모든 요청에서 `anthropic-workspace-id` 헤더로 전송됩니다. 기본 URL은 `AWS_REGION`에서 `https://aws-external-anthropic.{region}.api.aws`로 계산됩니다. URL을 직접 재정의하려면 `ANTHROPIC_AWS_BASE_URL`을 설정하십시오.271`ANTHROPIC_AWS_WORKSPACE_ID`는 필수이며 모든 요청에서 `anthropic-workspace-id` 헤더로 전송됩니다. 기본 URL은 `AWS_REGION`에서 `https://aws-external-anthropic.{region}.api.aws`로 계산됩니다. URL을 직접 재정의하려면 `ANTHROPIC_AWS_BASE_URL`을 설정하십시오.

272 272

273Claude Platform on AWS는 환경에 AWS 자격 증명이 있어도 선택 사항입니다. Bedrock 및 Foundry는 공급자 라우팅에서 우선하므로 설정된 경우 `CLAUDE_CODE_USE_BEDROCK` 및 `CLAUDE_CODE_USE_FOUNDRY`를 해제하십시오.273Claude Platform on AWS는 환경에 AWS 자격 증명이 있어도 선택 사항입니다. Amazon Bedrock 및 Microsoft Foundry는 공급자 라우팅에서 우선하므로 설정된 경우 `CLAUDE_CODE_USE_BEDROCK` 및 `CLAUDE_CODE_USE_FOUNDRY`를 해제하십시오.

274 274

275<h3 id="3-pin-model-versions">275<h3 id="3-pin-model-versions">

276 3. 모델 버전 고정276 3. 모델 버전 고정

cli-reference.md +10 −7

Details

25| `claude gateway` | 자체 호스팅 [Claude 앱 게이트웨이](/ko/claude-apps-gateway) 서버를 시작합니다. Bedrock, Vertex AI 또는 Foundry의 Claude Code 앞에 SSO 및 정책을 배포하는 관리자용입니다. [`gateway.yaml`](/ko/claude-apps-gateway-config)을 가리키는 `--config`가 필요합니다. Claude Code v2.1.195 이상에서 사용 가능합니다. | `claude gateway --config gateway.yaml` |25| `claude gateway` | 자체 호스팅 [Claude 앱 게이트웨이](/ko/claude-apps-gateway) 서버를 시작합니다. Amazon Bedrock, Google Cloud의 Agent Platform 또는 Microsoft Foundry의 Claude Code 앞에 SSO 및 정책을 배포하는 관리자용입니다. [`gateway.yaml`](/ko/claude-apps-gateway-config)을 가리키는 `--config`가 필요합니다. Claude Code v2.1.195 이상에서 사용 가능합니다. | `claude gateway --config gateway.yaml` |

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

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

32| `claude auto-mode defaults` | 기본 제공 [자동 모드](/ko/permission-modes#eliminate-prompts-with-auto-mode) 분류기 규칙을 JSON으로 인쇄합니다. `claude auto-mode config`를 사용하여 설정이 적용된 유효한 구성을 확인합니다 | `claude auto-mode defaults > rules.json` |32| `claude auto-mode defaults` | 기본 제공 [자동 모드](/ko/permission-modes#eliminate-prompts-with-auto-mode) 분류기 규칙을 JSON으로 인쇄합니다. `claude auto-mode config`를 사용하여 설정이 적용된 유효한 구성을 확인합니다 | `claude auto-mode defaults > rules.json` |

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

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

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

63| `--agents` | JSON을 통해 사용자 정의 subagents를 동적으로 정의합니다. subagent [frontmatter](/ko/sub-agents#supported-frontmatter-fields)와 동일한 필드 이름과 에이전트의 지시사항에 대한 `prompt` 필드를 사용합니다 | `claude --agents '{"reviewer":{"description":"Reviews code","prompt":"You are a code reviewer"}}'` |64| `--agents` | JSON을 통해 사용자 정의 subagents를 동적으로 정의합니다. subagent [frontmatter](/ko/sub-agents#supported-frontmatter-fields)와 동일한 필드 이름과 에이전트의 지시사항에 대한 `prompt` 필드를 사용합니다 | `claude --agents '{"reviewer":{"description":"Reviews code","prompt":"You are a code reviewer"}}'` |

64| `--allow-dangerously-skip-permissions` | `Shift+Tab` 모드 사이클에 `bypassPermissions`를 추가합니다. 이를 통해 `plan`과 같은 다른 모드에서 시작하고 나중에 `bypassPermissions`로 전환할 수 있습니다. [권한 모드](/ko/permission-modes#skip-all-checks-with-bypasspermissions-mode) 참조 | `claude --permission-mode plan --allow-dangerously-skip-permissions` |65| `--allow-dangerously-skip-permissions` | `Shift+Tab` 모드 사이클에 `bypassPermissions`를 추가합니다. 이를 통해 `plan`과 같은 다른 모드에서 시작하고 나중에 `bypassPermissions`로 전환할 수 있습니다. [권한 모드](/ko/permission-modes#skip-all-checks-with-bypasspermissions-mode) 참조 | `claude --permission-mode plan --allow-dangerously-skip-permissions` |

65| `--allowedTools`, `--allowed-tools` | 권한 프롬프트 없이 실행되는 도구입니다. 패턴 매칭에 대해 [권한 규칙 구문](/ko/settings#permission-rule-syntax)을 참조하세요. 사용 가능한 도구를 제한하려면 `--tools`를 대신 사용하세요 | `"Bash(git log *)" "Bash(git diff *)" "Read"` |66| `--allowedTools`, `--allowed-tools` | 권한 프롬프트 없이 실행되는 도구입니다. 패턴 매칭에 대해 [권한 규칙 구문](/ko/settings#permission-rule-syntax)을 참조하세요. 사용 가능한 도구를 제한하려면 `--tools`를 대신 사용하세요 | `"Bash(git log *)" "Bash(git diff *)" "Read"` |

67| `--append-subagent-system-prompt` | {/* min-version: 2.1.205 */}모든 [subagent](/ko/sub-agents)의 시스템 프롬프트 끝에 사용자 정의 텍스트를 추가합니다. 중첩된 subagents를 포함합니다. `-p`를 사용한 비대화형 모드에만 적용됩니다. Claude Code v2.1.205 이상이 필요합니다 | `claude -p --append-subagent-system-prompt "Cite file paths in every answer" "query"` |

68| `--ax-screen-reader` | {/* min-version: 2.1.181 */}스크린 리더 친화적 출력을 렌더링합니다: 장식용 테두리나 애니메이션 없는 평문입니다. 클래식 렌더러를 강제하므로 이 세션에 대해 [`tui`](/ko/settings#available-settings) 설정은 효과가 없습니다. [`CLAUDE_AX_SCREEN_READER`](/ko/env-vars) 및 [`axScreenReader`](/ko/settings#available-settings) 설정보다 우선합니다. Claude Code v2.1.181 이상이 필요합니다 | `claude --ax-screen-reader` |70| `--ax-screen-reader` | {/* min-version: 2.1.181 */}스크린 리더 친화적 출력을 렌더링합니다: 장식용 테두리나 애니메이션 없는 평문입니다. 클래식 렌더러를 강제하므로 이 세션에 대해 [`tui`](/ko/settings#available-settings) 설정은 효과가 없습니다. [`CLAUDE_AX_SCREEN_READER`](/ko/env-vars) 및 [`axScreenReader`](/ko/settings#available-settings) 설정보다 우선합니다. Claude Code v2.1.181 이상이 필요합니다 | `claude --ax-screen-reader` |

71| `--bg`, `--background` | 세션을 [백그라운드 에이전트](/ko/agent-view)로 시작하고 즉시 반환합니다. 세션 ID와 관리 명령어를 인쇄합니다. `--exec`과 결합하여 Claude 세션 대신 셸 명령어를 백그라운드 작업으로 실행하거나, `--agent`와 결합하여 특정 subagent를 실행합니다. {/* min-version: 2.1.198 */}`-p`/`--print`와 결합할 수 없습니다. [오류 참조](/ko/errors#command-line-errors) 참조 | `claude --bg "investigate the flaky test"` |73| `--bg`, `--background` | 세션을 [백그라운드 에이전트](/ko/agent-view)로 시작하고 즉시 반환합니다. 세션 ID와 관리 명령어를 인쇄합니다. `--exec`과 결합하여 Claude 세션 대신 셸 명령어를 백그라운드 작업으로 실행하거나, `--agent`와 결합하여 특정 subagent를 실행합니다. {/* min-version: 2.1.198 */}`-p`/`--print`와 결합할 수 없습니다. [오류 참조](/ko/errors#command-line-errors) 참조 | `claude --bg "investigate the flaky test"` |

72| `--channels` | (연구 미리보기) Claude가 이 세션에서 수신해야 할 [채널](/ko/channels) 알림이 있는 MCP 서버입니다. `plugin:<name>@<marketplace>` 항목의 공백으로 구분된 목록입니다. Claude.ai 인증이 필요합니다 | `claude --channels plugin:my-notifier@my-marketplace` |74| `--channels` | (연구 미리보기) Claude가 이 세션에서 수신해야 할 [채널](/ko/channels) 알림이 있는 MCP 서버입니다. `plugin:<name>@<marketplace>` 항목의 공백으로 구분된 목록입니다. Claude.ai 인증이 필요합니다 | `claude --channels plugin:my-notifier@my-marketplace` |

76| `--cloud` | 제공된 작업 설명으로 claude.ai에서 새 [웹 세션](/ko/claude-code-on-the-web)을 생성합니다 | `claude --cloud "Fix the login bug"` |

75| `--dangerously-load-development-channels` | 로컬 개발을 위해 승인된 허용 목록에 없는 [채널](/ko/channels-reference#test-during-the-research-preview)을 활성화합니다. `plugin:<name>@<marketplace>` 및 `server:<name>` 항목을 허용합니다. 확인을 요청합니다 | `claude --dangerously-load-development-channels server:webhook` |78| `--dangerously-load-development-channels` | 로컬 개발을 위해 승인된 허용 목록에 없는 [채널](/ko/channels-reference#test-during-the-research-preview)을 활성화합니다. `plugin:<name>@<marketplace>` 및 `server:<name>` 항목을 허용합니다. 확인을 요청합니다 | `claude --dangerously-load-development-channels server:webhook` |

76| `--dangerously-skip-permissions` | 권한 프롬프트를 건너뜁니다. `--permission-mode bypassPermissions`와 동일합니다. 이것이 건너뛰는 것과 건너뛰지 않는 것에 대해 [권한 모드](/ko/permission-modes#skip-all-checks-with-bypasspermissions-mode)를 참조하세요 | `claude --dangerously-skip-permissions` |79| `--dangerously-skip-permissions` | 권한 프롬프트를 건너뜁니다. `--permission-mode bypassPermissions`와 동일합니다. 이것이 건너뛰는 것과 건너뛰지 않는 것에 대해 [권한 모드](/ko/permission-modes#skip-all-checks-with-bypasspermissions-mode)를 참조하세요 | `claude --dangerously-skip-permissions` |

80| `--disallowedTools`, `--disallowed-tools` | 거부 규칙입니다. 단순 도구 이름은 모델의 컨텍스트에서 해당 도구를 제거합니다: `"Edit"`는 Edit를 제거하고, `"*"`는 모든 도구를 제거하며, `"mcp__*"`는 모든 MCP 도구를 제거합니다. `Bash(rm *)`과 같은 범위 지정 규칙은 도구를 사용 가능하게 유지하고 일치하는 호출만 거부합니다 | `"Bash(git log *)" "Bash(git diff *)" "Edit"` |83| `--disallowedTools`, `--disallowed-tools` | 거부 규칙입니다. 단순 도구 이름은 모델의 컨텍스트에서 해당 도구를 제거합니다: `"Edit"`는 Edit를 제거하고, `"*"`는 모든 도구를 제거하며, `"mcp__*"`는 모든 MCP 도구를 제거합니다. `Bash(rm *)`과 같은 범위 지정 규칙은 도구를 사용 가능하게 유지하고 일치하는 호출만 거부합니다 | `"Bash(git log *)" "Bash(git diff *)" "Edit"` |

81| `--effort` | 현재 세션에 대한 [노력 수준](/ko/model-config#adjust-effort-level)을 설정합니다. 옵션: `low`, `medium`, `high`, `xhigh`, `max`; 사용 가능한 수준은 모델에 따라 다릅니다. [`effortLevel`](/ko/settings#available-settings) 설정을 이 세션에 대해 재정의하며 지속되지 않습니다 | `claude --effort high` |84| `--effort` | 현재 세션에 대한 [노력 수준](/ko/model-config#adjust-effort-level)을 설정합니다. 옵션: `low`, `medium`, `high`, `xhigh`, `max` 또는 {/* min-version: 2.1.203 */}}`ultracode`. 사용 가능한 수준은 모델에 따라 다릅니다. `ultracode`는 세션을 `xhigh` 노력으로 시작하고 [ultracode](/ko/workflows#let-claude-decide-with-ultracode)를 켜며, Claude Code v2.1.203 이상이 필요합니다. [`effortLevel`](/ko/settings#available-settings) 설정을 이 세션에 대해 재정의하며 지속되지 않습니다 | `claude --effort high` |

82| `--enable-auto-mode` | {/* max-version: 2.1.110 */}v2.1.111에서 제거됨. 자동 모드는 이제 `Shift+Tab` 사이클에 기본적으로 포함됩니다. `--permission-mode auto`를 사용하여 시작합니다 | `claude --permission-mode auto` |85| `--enable-auto-mode` | {/* max-version: 2.1.110 */}v2.1.111에서 제거됨. 자동 모드는 이제 `Shift+Tab` 사이클에 기본적으로 포함됩니다. `--permission-mode auto`를 사용하여 시작합니다 | `claude --permission-mode auto` |

83| `--exclude-dynamic-system-prompt-sections` | 시스템 프롬프트의 머신별 섹션(작업 디렉토리, 환경 정보, 메모리 경로, git 상태)을 첫 번째 사용자 메시지로 이동합니다. 동일한 작업을 실행하는 다양한 사용자 및 머신 간에 프롬프트 캐시 재사용을 개선합니다. 기본 시스템 프롬프트에만 적용됩니다. `--system-prompt` 또는 `--system-prompt-file`이 설정되면 무시됩니다. 스크립트된 다중 사용자 워크로드의 경우 `-p`와 함께 사용합니다 | `claude -p --exclude-dynamic-system-prompt-sections "query"` |86| `--exclude-dynamic-system-prompt-sections` | 시스템 프롬프트의 머신별 섹션(작업 디렉토리, 환경 정보, 메모리 경로, git 상태)을 첫 번째 사용자 메시지로 이동합니다. 동일한 작업을 실행하는 다양한 사용자 및 머신 간에 프롬프트 캐시 재사용을 개선합니다. 기본 시스템 프롬프트에만 적용됩니다. `--system-prompt` 또는 `--system-prompt-file`이 설정되면 무시됩니다. 스크립트된 다중 사용자 워크로드의 경우 `-p`와 함께 사용합니다 | `claude -p --exclude-dynamic-system-prompt-sections "query"` |

91| `--include-hook-events` | 모든 hook 라이프사이클 이벤트를 출력 스트림에 포함합니다. `--output-format stream-json`이 필요합니다 | `claude -p --output-format stream-json --verbose --include-hook-events "query"` |94| `--include-hook-events` | 모든 hook 라이프사이클 이벤트를 출력 스트림에 포함합니다. `--output-format stream-json`이 필요합니다 | `claude -p --output-format stream-json --verbose --include-hook-events "query"` |

92| `--include-partial-messages` | 부분 스트리밍 이벤트를 출력에 포함합니다. `--print`와 `--output-format stream-json`이 필요합니다 | `claude -p --output-format stream-json --verbose --include-partial-messages "query"` |95| `--include-partial-messages` | 부분 스트리밍 이벤트를 출력에 포함합니다. `--print`와 `--output-format stream-json`이 필요합니다 | `claude -p --output-format stream-json --verbose --include-partial-messages "query"` |

94| `--json-schema` | 에이전트가 워크플로우를 완료한 후 JSON Schema와 일치하는 검증된 JSON 출력을 가져옵니다(인쇄 모드만 해당, [구조화된 출력](/ko/agent-sdk/structured-outputs) 참조) | `claude -p --json-schema '{"type":"object","properties":{...}}' "query"` |97| `--json-schema` | 에이전트가 워크플로우를 완료한 후 JSON Schema와 일치하는 검증된 JSON 출력을 가져옵니다(인쇄 모드만 해당). [구조화된 출력](/ko/agent-sdk/structured-outputs) 참조. {/* min-version: 2.1.205 */}Claude Code는 잘못된 스키마에서 오류로 종료되고 클라이언트 측 검증 없이 주석으로 `format` 키워드를 허용합니다. v2.1.205 이전에는 잘못된 스키마가 오류 없이 구조화되지 않은 출력을 생성했으며, `format`을 사용하는 스키마는 잘못된 것으로 취급되었습니다 | `claude -p --json-schema '{"type":"object","properties":{...}}' "query"` |

97| `--max-turns` | 에이전트 턴의 수를 제한합니다(인쇄 모드만 해당). 제한에 도달하면 오류로 종료됩니다. 기본적으로 제한 없음 | `claude -p --max-turns 3 "query"` |100| `--max-turns` | 에이전트 턴의 수를 제한합니다(인쇄 모드만 해당). 제한에 도달하면 오류로 종료됩니다. 기본적으로 제한 없음. {/* min-version: 2.1.205 */}}`--input-format stream-json`을 사용하면 Claude가 작업 중일 때 전송된 메시지는 대기열에 남아 있고 제한이 현재 메시지를 종료할 때 자신의 제한으로 자신의 턴으로 실행됩니다. v2.1.205 이전에는 Claude Code가 해당 메시지를 버렸습니다 | `claude -p --max-turns 3 "query"` |

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

100| `--name`, `-n` | 세션의 표시 이름을 설정합니다. `/resume`과 터미널 제목에 표시됩니다. `claude --resume <name>`으로 명명된 세션을 재개할 수 있습니다. <br /><br />[`/rename`](/ko/commands)은 세션 중에 이름을 변경하고 프롬프트 표시줄에도 표시합니다 | `claude -n "my-feature-work"` |103| `--name`, `-n` | 세션의 표시 이름을 설정합니다. `/resume`과 터미널 제목에 표시됩니다. `claude --resume <name>`으로 명명된 세션을 재개할 수 있습니다. <br /><br />[`/rename`](/ko/commands)은 세션 중에 이름을 변경하고 프롬프트 표시줄에도 표시합니다 | `claude -n "my-feature-work"` |

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

104| `--permission-mode` | 지정된 [권한 모드](/ko/permission-modes)에서 시작합니다. `default`, `acceptEdits`, `plan`, `auto`, `dontAsk` 또는 `bypassPermissions`를 허용합니다. 설정 파일의 `defaultMode`를 재정의합니다 | `claude --permission-mode plan` |107| `--permission-mode` | 지정된 [권한 모드](/ko/permission-modes)에서 시작합니다. `default`, `acceptEdits`, `plan`, `auto`, `dontAsk`, `bypassPermissions` 또는 {/* min-version: 2.1.200 */}}`manual`을 허용합니다. `manual`은 `default`의 별칭이며 UI가 Manual로 표시하는 모드를 선택하고 Claude Code v2.1.200 이상이 필요합니다. `claude --help`는 `default` 대신 이를 나열하며 두 값 모두 작동합니다. 설정 파일의 `defaultMode`를 재정의합니다 | `claude --permission-mode plan` |

105| `--permission-prompt-tool` | 비대화형 모드에서 권한 프롬프트를 처리할 MCP 도구를 지정합니다. {/* min-version: 2.1.199 */}v2.1.199부터 프롬프트 도구는 [사용자 상호작용이 필요한](/ko/mcp#require-approval-for-a-specific-tool) 것으로 표시된 MCP 도구를 승인할 수 없습니다: 하나에 대한 `allow` 결과는 거부로 변환됩니다 | `claude -p --permission-prompt-tool mcp_auth_tool "query"` |108| `--permission-prompt-tool` | 비대화형 모드에서 권한 프롬프트를 처리할 MCP 도구를 지정합니다. {/* min-version: 2.1.199 */}v2.1.199부터 프롬프트 도구는 [사용자 상호작용이 필요한](/ko/mcp#require-approval-for-a-specific-tool) 것으로 표시된 MCP 도구를 승인할 수 없습니다: 하나에 대한 `allow` 결과는 거부로 변환됩니다 | `claude -p --permission-prompt-tool mcp_auth_tool "query"` |

106| `--plugin-dir` | 이 세션에만 디렉토리 또는 `.zip` 아카이브에서 plugin을 로드합니다. 각 플래그는 하나의 경로를 사용합니다. 여러 plugins의 경우 플래그를 반복합니다: `--plugin-dir A --plugin-dir B.zip` | `claude --plugin-dir ./my-plugin` |109| `--plugin-dir` | 이 세션에만 디렉토리 또는 `.zip` 아카이브에서 plugin을 로드합니다. 각 플래그는 하나의 경로를 사용합니다. 여러 plugins의 경우 플래그를 반복합니다: `--plugin-dir A --plugin-dir B.zip` | `claude --plugin-dir ./my-plugin` |

107| `--plugin-url` | 이 세션에만 URL에서 plugin `.zip` 아카이브를 가져옵니다. 여러 plugins의 경우 플래그를 반복하거나 단일 따옴표 값에 공백으로 구분된 URL을 전달합니다 | `claude --plugin-url https://example.com/plugin.zip` |110| `--plugin-url` | 이 세션에만 URL에서 plugin `.zip` 아카이브를 가져옵니다. 여러 plugins의 경우 플래그를 반복하거나 단일 따옴표 값에 공백으로 구분된 URL을 전달합니다 | `claude --plugin-url https://example.com/plugin.zip` |

109| `--prompt-suggestions` | 각 턴 후에 예측된 다음 사용자 프롬프트를 포함하는 `prompt_suggestion` 메시지를 내보냅니다. `--print`, `--output-format stream-json` 및 `--verbose`가 필요합니다. [프롬프트 제안](/ko/interactive-mode#prompt-suggestions) 참조 | `claude -p --prompt-suggestions --output-format stream-json --verbose "query"` |112| `--prompt-suggestions` | 각 턴 후에 예측된 다음 사용자 프롬프트를 포함하는 `prompt_suggestion` 메시지를 내보냅니다. `--print`, `--output-format stream-json` 및 `--verbose`가 필요합니다. [프롬프트 제안](/ko/interactive-mode#prompt-suggestions) 참조 | `claude -p --prompt-suggestions --output-format stream-json --verbose "query"` |

111| `--remote-control`, `--rc` | claude.ai 또는 Claude 앱에서도 제어할 수 있도록 [Remote Control](/ko/remote-control#start-a-remote-control-session)이 활성화된 대화형 세션을 시작합니다. 선택적으로 세션의 이름을 전달할 수 있습니다 | `claude --remote-control "My Project"` |114| `--remote-control`, `--rc` | claude.ai 또는 Claude 앱에서도 제어할 수 있도록 [Remote Control](/ko/remote-control#start-a-remote-control-session)이 활성화된 대화형 세션을 시작합니다. 선택적으로 세션의 이름을 전달할 수 있습니다 | `claude --remote-control "My Project"` |

112| `--remote-control-session-name-prefix <prefix>` | 명시적 이름이 설정되지 않은 경우 자동 생성된 [Remote Control](/ko/remote-control) 세션 이름의 접두사입니다. 기본값은 머신의 호스트명이며, `myhost-graceful-unicorn`과 같은 이름을 생성합니다. 동일한 효과를 위해 `CLAUDE_REMOTE_CONTROL_SESSION_NAME_PREFIX`를 설정합니다 | `claude remote-control --remote-control-session-name-prefix dev-box` |115| `--remote-control-session-name-prefix <prefix>` | 명시적 이름이 설정되지 않은 경우 자동 생성된 [Remote Control](/ko/remote-control) 세션 이름의 접두사입니다. 기본값은 머신의 호스트명이며, `myhost-graceful-unicorn`과 같은 이름을 생성합니다. 동일한 효과를 위해 `CLAUDE_REMOTE_CONTROL_SESSION_NAME_PREFIX`를 설정합니다 | `claude remote-control --remote-control-session-name-prefix dev-box` |

113| `--replay-user-messages` | stdin에서 사용자 메시지를 다시 내보내 stdout으로 승인합니다. `--input-format stream-json`과 `--output-format stream-json`이 필요합니다 | `claude -p --input-format stream-json --output-format stream-json --verbose --replay-user-messages` |116| `--replay-user-messages` | stdin에서 사용자 메시지를 다시 내보내 stdout으로 승인합니다. `--input-format stream-json`과 `--output-format stream-json`이 필요합니다 | `claude -p --input-format stream-json --output-format stream-json --verbose --replay-user-messages` |

123| `--teammate-mode` | [에이전트 팀](/ko/agent-teams) 팀원 표시 방식을 설정합니다: `in-process`(기본값), `auto`, `tmux` 또는 {/* min-version: 2.1.186 */}`iterm2`(v2.1.186에서 추가됨). 기본값은 v2.1.179에서 `auto`에서 변경되었습니다. [`teammateMode`](/ko/settings#available-settings) 설정을 이 세션에 대해 재정의합니다. [디스플레이 모드 선택](/ko/agent-teams#choose-a-display-mode) 참조 | `claude --teammate-mode auto` |126| `--teammate-mode` | [에이전트 팀](/ko/agent-teams) 팀원 표시 방식을 설정합니다: `in-process`(기본값), `auto`, `tmux` 또는 {/* min-version: 2.1.186 */}}`iterm2`(v2.1.186에서 추가됨). 기본값은 v2.1.179에서 `auto`에서 변경되었습니다. [`teammateMode`](/ko/settings#available-settings) 설정을 이 세션에 대해 재정의합니다. [디스플레이 모드 선택](/ko/agent-teams#choose-a-display-mode) 참조 | `claude --teammate-mode auto` |

125| `--tools` | Claude가 사용할 수 있는 기본 제공 도구를 제한합니다. 모두 비활성화하려면 `""`를 사용하고, 모두 사용하려면 `"default"`를 사용하거나, `"Bash,Edit,Read"`와 같은 도구 이름을 사용합니다. MCP 도구는 영향을 받지 않습니다. 이들도 거부하려면 `--disallowedTools "mcp__*"`를 사용하거나, `--mcp-config` 없이 `--strict-mcp-config`를 전달하여 MCP 서버가 로드되지 않도록 합니다 | `claude --tools "Bash,Edit,Read"` |128| `--tools` | Claude가 사용할 수 있는 기본 제공 도구를 제한합니다. 모두 비활성화하려면 `""`를 사용하고, 모두 사용하려면 `"default"`를 사용하거나, `"Bash,Edit,Read"`와 같은 도구 이름을 사용합니다. MCP 도구는 영향을 받지 않습니다. 이들도 거부하려면 `--disallowedTools "mcp__*"`를 사용하거나, `--mcp-config` 없이 `--strict-mcp-config`를 전달하여 MCP 서버가 로드되지 않도록 합니다 | `claude --tools "Bash,Edit,Read"` |

code-review.md +1 −1

Details

270 270

271모든 모드에서 `@claude review`를 [댓글로 작성](#manually-trigger-reviews)하면 PR이 푸시 트리거 검토에 옵트인되므로 해당 댓글 이후 푸시당 추가 비용이 발생합니다. 향후 푸시에 구독하지 않고 단일 검토를 실행하려면 대신 `@claude review once`를 댓글로 작성하십시오.271모든 모드에서 `@claude review`를 [댓글로 작성](#manually-trigger-reviews)하면 PR이 푸시 트리거 검토에 옵트인되므로 해당 댓글 이후 푸시당 추가 비용이 발생합니다. 향후 푸시에 구독하지 않고 단일 검토를 실행하려면 대신 `@claude review once`를 댓글로 작성하십시오.

272 272

273비용은 조직이 다른 Claude Code 기능에 Amazon Bedrock 또는 Google Vertex AI를 사용하는지 여부와 관계없이 Anthropic 청구서에 나타납니다. Code Review의 월간 지출 한도를 설정하려면 [claude.ai/admin-settings/usage](https://claude.ai/admin-settings/usage)로 이동하여 Claude Code Review 서비스의 한도를 구성합니다.273비용은 조직이 다른 Claude Code 기능에 Amazon Bedrock 또는 Google Cloud의 Agent Platform을 사용하는지 여부와 관계없이 Anthropic 청구서에 나타납니다. Code Review의 월간 지출 한도를 설정하려면 [claude.ai/admin-settings/usage](https://claude.ai/admin-settings/usage)로 이동하여 Claude Code Review 서비스의 한도를 구성합니다.

274 274

275[분석](#view-usage)의 주간 비용 차트 또는 관리자 설정의 리포지토리별 평균 비용 열을 통해 지출을 모니터링합니다.275[분석](#view-usage)의 주간 비용 차트 또는 관리자 설정의 리포지토리별 평균 비용 열을 통해 지출을 모니터링합니다.

276 276

commands.md +21 −21

Details

24 24

25**병렬로 작업 실행.** Claude는 부작업을 [subagent](/ko/sub-agents)에게 위임하고, `/tasks`는 현재 세션의 백그라운드에서 실행 중인 작업을 나열합니다. `/background`는 전체 세션을 분리하여 [background agent](/ko/agent-view)로 계속 실행되도록 하고 터미널을 해제합니다. 코드베이스에 걸친 큰 변경의 경우, `/batch`는 이를 독립적인 단위로 분해하고 각각을 자신의 [worktree](/ko/worktrees)에서 실행합니다. [병렬로 agent 실행](/ko/agents)을 참조하여 이러한 접근 방식이 어떻게 관련되는지 확인하십시오.25**병렬로 작업 실행.** Claude는 부작업을 [subagent](/ko/sub-agents)에게 위임하고, `/tasks`는 현재 세션의 백그라운드에서 실행 중인 작업을 나열합니다. `/background`는 전체 세션을 분리하여 [background agent](/ko/agent-view)로 계속 실행되도록 하고 터미널을 해제합니다. 코드베이스에 걸친 큰 변경의 경우, `/batch`는 이를 독립적인 단위로 분해하고 각각을 자신의 [worktree](/ko/worktrees)에서 실행합니다. [병렬로 agent 실행](/ko/agents)을 참조하여 이러한 접근 방식이 어떻게 관련되는지 확인하십시오.

26 26

27**배포 전.** `/diff`는 변경된 내용을 표시하고, `/code-review`는 diff를 정확성 버그 및 정리에 대해 확인하며 `--fix`로 결과를 적용할 수 있고, `/review`는 GitHub pull request에서 동일한 읽기 전용 검토를 실행하며, `/security-review`는 더 깊은 읽기 전용 검토를 제공합니다. `/code-review ultra`는 클라우드에서 다중 agent 검토를 실행합니다.27**배포 전.** `/diff`는 변경된 내용을 표시하고, `/code-review`는 diff를 정확성 버그 및 정리에 대해 확인하며 `--fix`로 결과를 적용할 수 있고, `/review`는 GitHub pull request에서 빠른 단일 패스 읽기 전용 검토를 제공하며, `/code-review <level> <pr#>`은 다중 agent 검토를 실행하고, `/security-review`는 diff를 보안 취약점에 대해 확인합니다. `/code-review ultra`는 클라우드에서 다중 agent 검토를 실행합니다.

28 28

29**세션 간.** `/clear`는 프로젝트 메모리를 유지하면서 새 작업을 새로 시작합니다. `/resume` 및 `/branch`를 사용하면 이전 대화로 돌아가거나 분기할 수 있습니다. `/teleport`는 웹 세션을 이 터미널로 가져오고, `/remote-control`을 사용하면 다른 기기에서 이 로컬 세션을 계속할 수 있습니다.29**세션 간.** `/clear`는 프로젝트 메모리를 유지하면서 새 작업을 새로 시작합니다. `/resume` 및 `/branch`를 사용하면 이전 대화로 돌아가거나 분기할 수 있습니다. `/teleport`는 웹 세션을 이 터미널로 가져오고, `/remote-control`을 사용하면 다른 기기에서 이 로컬 세션을 계속할 수 있습니다.

30 30

31**문제가 발생했을 때.** `/rewind`는 코드와 대화를 checkpoint로 되돌리거나 대화의 일부를 요약합니다. `/doctor` 및 `/debug`는 설치 및 런타임 문제를 진단하고, `/feedback`은 세션 컨텍스트가 첨부된 버그를 보고합니다.31**문제가 발생했을 때.** `/rewind`는 코드와 대화를 checkpoint로 되돌리거나 대화의 일부를 요약합니다. `/doctor`는 설치 및 구성 문제를 진단하고 이를 수정할 수 있는 설정 점검을 실행하고, `/debug`는 런타임 문제를 진단하며, `/feedback`은 세션 컨텍스트가 첨부된 버그를 보고합니다.

32 32

33<h2 id="all-commands">33<h2 id="all-commands">

34 모든 명령어34 모든 명령어

48</Note>48</Note>

49 49

50| 명령어 | 목적 |50| 명령어 | 목적 |

51| :--------------------------------------------------------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |51| :--------------------------------------------------------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

52| `/add-dir <path>` | 현재 세션 중에 파일 액세스를 위한 작업 디렉토리를 추가합니다. 대부분의 `.claude/` 구성은 추가된 디렉토리에서 [발견되지 않습니다](/ko/permissions#additional-directories-grant-file-access-not-configuration). 나중에 `--continue` 또는 `--resume`을 사용하여 추가된 디렉토리에서 세션을 재개할 수 있습니다 |52| `/add-dir <path>` | 현재 세션 중에 파일 액세스를 위한 작업 디렉토리를 추가합니다. 대부분의 `.claude/` 구성은 추가된 디렉토리에서 [발견되지 않습니다](/ko/permissions#additional-directories-grant-file-access-not-configuration). 나중에 `--continue` 또는 `--resume`을 사용하여 추가된 디렉토리에서 세션을 재개할 수 있습니다 |

53| `/advisor [model\|off]` | {/* min-version: 2.1.98 */}[advisor tool](/ko/advisor)을 활성화 또는 비활성화합니다. 이 도구는 작업 중 주요 순간에 두 번째 모델에 지침을 요청합니다. `opus`, `sonnet`, `fable` ({/* min-version: 2.1.170 */}v2.1.170+) 또는 전체 모델 ID를 허용합니다. 인수 없이 선택기를 엽니다. Claude Code v2.1.98 이상이 필요합니다 |53| `/advisor [model\|off]` | {/* min-version: 2.1.98 */}[advisor tool](/ko/advisor)을 활성화 또는 비활성화합니다. 이 도구는 작업 중 주요 순간에 두 번째 모델에 지침을 요청합니다. `opus`, `sonnet`, `fable` ({/* min-version: 2.1.170 */}v2.1.170+) 또는 전체 모델 ID를 허용합니다. 인수 없이 선택기를 엽니다. Claude Code v2.1.98 이상이 필요합니다 |

54| `/agents` | {/* min-version: 2.1.198 */}v2.1.198부터 `/agents`를 실행하면 Claude에 [subagents](/ko/sub-agents)를 만들거나 관리하도록 요청하거나, `.claude/agents/` 또는 `~/.claude/agents/`를 직접 편집하도록 상기시키는 메시지를 인쇄합니다. {/* max-version: 2.1.197 */}v2.1.197 이전에는 subagent 구성을 만들고 관리하기 위한 대화형 인터페이스를 엽니다 |54| `/agents` | {/* min-version: 2.1.198 */}v2.1.198부터 `/agents`를 실행하면 Claude에 [subagents](/ko/sub-agents)를 만들거나 관리하도록 요청하거나, `.claude/agents/` 또는 `~/.claude/agents/`를 직접 편집하도록 상기시키는 메시지를 인쇄합니다. {/* max-version: 2.1.197 */}v2.1.197 이전에는 subagent 구성을 만들고 관리하기 위한 대화형 인터페이스를 엽니다 |

62| `/claude-api [migrate\|managed-agents-onboard]` | **[Skill](/ko/skills#bundled-skills).** 프로젝트의 언어(Python, TypeScript, Java, Go, Ruby, C#, PHP 또는 cURL) 및 Managed Agents 참조에 대한 Claude API 참조 자료를 로드합니다. 도구 사용, 스트리밍, 배치, 구조화된 출력 및 일반적인 함정을 다룹니다. 또한 코드가 `anthropic` 또는 `@anthropic-ai/sdk`를 가져올 때 자동으로 활성화됩니다. `/claude-api migrate`를 실행하여 기존 Claude API 코드를 최신 모델로 업그레이드합니다. Claude는 스캔할 파일과 대상 모델을 묻고, 모델 ID, thinking 구성 및 버전 간에 변경된 기타 매개변수를 업데이트합니다. `/claude-api managed-agents-onboard`를 실행하여 처음부터 새로운 Managed Agent를 만드는 대화형 안내를 받습니다 |62| `/claude-api [migrate\|managed-agents-onboard]` | **[Skill](/ko/skills#bundled-skills).** 프로젝트의 언어(Python, TypeScript, Java, Go, Ruby, C#, PHP 또는 cURL) 및 Managed Agents 참조에 대한 Claude API 참조 자료를 로드합니다. 도구 사용, 스트리밍, 배치, 구조화된 출력 및 일반적인 함정을 다룹니다. 또한 코드가 `anthropic` 또는 `@anthropic-ai/sdk`를 가져올 때 자동으로 활성화됩니다. `/claude-api migrate`를 실행하여 기존 Claude API 코드를 최신 모델로 업그레이드합니다. Claude는 스캔할 파일과 대상 모델을 묻고, 모델 ID, thinking 구성 및 버전 간에 변경된 기타 매개변수를 업데이트합니다. `/claude-api managed-agents-onboard`를 실행하여 처음부터 새로운 Managed Agent를 만드는 대화형 안내를 받습니다 |

63| `/clear [name]` | 빈 컨텍스트로 새 대화를 시작합니다. 이전 대화는 `/resume`에서 사용 가능하게 유지됩니다. 이름을 전달하여 `/resume` 선택기에서 이전 대화에 레이블을 지정합니다. 같은 대화를 계속하면서 컨텍스트를 확보하려면 `/compact`를 대신 사용하세요. 별칭: `/reset`, `/new` |63| `/clear [name]` | 빈 컨텍스트로 새 대화를 시작합니다. 이전 대화는 `/resume`에서 사용 가능하게 유지됩니다. 이름을 전달하여 `/resume` 선택기에서 이전 대화에 레이블을 지정합니다. 같은 대화를 계속하면서 컨텍스트를 확보하려면 `/compact`를 대신 사용하세요. 별칭: `/reset`, `/new` |

64| `/code-review [low\|medium\|high\|xhigh\|max\|ultra] [--fix] [--comment] [target]` | **[Skill](/ko/skills#bundled-skills).** 현재 diff를 정확성 버그에 대해 검토하고 재사용, 단순화 및 효율성 정리에 대해 검토합니다. `--fix`를 전달하여 결과를 작업 트리에 적용하고, `--comment`를 전달하여 현재 GitHub PR에 인라인 댓글로 게시하거나, `ultra`를 전달하여 깊은 [cloud review](/ko/ultrareview)를 실행합니다. {/* min-version: 2.1.154 */}v2.1.154부터 `/simplify`는 버그를 찾지 않고 정리만 수행하는 별도의 검토를 실행합니다. 노력 수준 및 대상 지정에 대해서는 [Review a diff locally](/ko/code-review#review-a-diff-locally)를 참조하세요 |64| `/code-review [low\|medium\|high\|xhigh\|max\|ultra] [--fix] [--comment] [target]` | **[Skill](/ko/skills#bundled-skills).** 현재 diff를 정확성 버그에 대해 검토하고 재사용, 단순화 및 효율성 정리에 대해 검토합니다. `--fix`를 전달하여 결과를 작업 트리에 적용하고, `--comment`를 전달하여 현재 GitHub PR에 인라인 댓글로 게시하거나, `ultra`를 전달하여 깊은 [cloud review](/ko/ultrareview)를 실행합니다. {/* min-version: 2.1.154 */}v2.1.154부터 `/simplify`는 버그를 찾지 않고 정리만 수행하는 별도의 검토를 실행합니다. 노력 수준 및 대상 지정에 대해서는 [Review a diff locally](/ko/code-review#review-a-diff-locally)를 참조하세요 |

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

66| `/compact [instructions]` | 지금까지의 대화를 요약하여 컨텍스트를 확보합니다. 선택적으로 요약에 대한 포커스 지침을 전달합니다. [compaction이 규칙, skills 및 메모리 파일을 처리하는 방법](/ko/context-window#what-survives-compaction)을 참조하세요 |66| `/compact [instructions]` | 지금까지의 대화를 요약하여 컨텍스트를 확보합니다. 선택적으로 요약에 대한 포커스 지침을 전달합니다. [compaction이 규칙, skills 및 메모리 파일을 처리하는 방법](/ko/context-window#what-survives-compaction)을 참조하세요 |

67| `/config [key=value ...]` | [Settings](/ko/settings) 인터페이스를 열어 테마, 모델, [output style](/ko/output-styles) 및 기타 기본 설정을 조정합니다. {/* min-version: 2.1.181 */}v2.1.181부터 하나 이상의 `key=value` 쌍을 전달하여 인터페이스를 열지 않고 설정을 직접 설정할 수 있습니다. 예를 들어 `/config thinking=false`. {/* min-version: 2.1.182 */}v2.1.182부터 명명된 약칭 키도 허용됩니다. 예를 들어 `/config theme=dark` 또는 `/config model=sonnet`. `key=value` 형식은 비대화형 모드(`-p`)와 [Remote Control](/ko/remote-control)에서도 작동합니다. `/config --help`를 실행하여 설정할 수 있는 모든 키를 나열합니다. 별칭: `/settings` |67| `/config [key=value ...]` | [Settings](/ko/settings) 인터페이스를 열어 테마, 모델, [output style](/ko/output-styles) 및 기타 기본 설정을 조정합니다. {/* min-version: 2.1.181 */}v2.1.181부터 하나 이상의 `key=value` 쌍을 전달하여 인터페이스를 열지 않고 설정을 직접 설정할 수 있습니다. 예를 들어 `/config thinking=false`. {/* min-version: 2.1.182 */}v2.1.182부터 명명된 약칭 키도 허용됩니다. 예를 들어 `/config theme=dark` 또는 `/config model=sonnet`. `key=value` 형식은 비대화형 모드(`-p`)와 [Remote Control](/ko/remote-control)에서도 작동합니다. `/config --help`를 실행하여 설정할 수 있는 모든 키를 나열합니다. 별칭: `/settings` |

68| `/context [all]` | 현재 컨텍스트 사용량을 색상 그리드로 시각화합니다. 컨텍스트 집약적 도구, 메모리 부풀림 및 용량 경고에 대한 최적화 제안을 표시합니다. [fullscreen mode](/ko/fullscreen)에서는 항목별 분석이 그리드를 표시하기 위해 축소됩니다. `all`을 전달하여 확장합니다 |68| `/context [all]` | 현재 컨텍스트 사용량을 색상 그리드로 시각화합니다. 컨텍스트 집약적 도구, 메모리 부풀림 및 용량 경고에 대한 최적화 제안을 표시합니다. [fullscreen mode](/ko/fullscreen)에서는 항목별 분석이 그리드를 표시하기 위해 축소됩니다. `all`을 전달하여 확장합니다 |

75| `/design-sync [hint]` | **[Skill](/ko/skills#bundled-skills).** 리포지토리의 React design system을 변환하고 [Claude Design](https://claude.ai/design)에 업로드하여 생성하는 디자인이 실제 구성 요소를 사용하도록 합니다. 선택적으로 design system의 이름을 지정합니다. 예를 들어 `/design-sync Acme DS`. 첫 번째 동기화는 모든 구성 요소를 확인하며 큰 리포지토리에서는 몇 시간이 걸릴 수 있습니다. Anthropic API에서 사용 가능합니다. Amazon Bedrock, Google Cloud의 Agent Platform 및 Microsoft Foundry에서는 기본 도구가 claude.ai에 도달할 수 없으므로 명령어를 사용할 수 없습니다 |75| `/design-sync [hint]` | **[Skill](/ko/skills#bundled-skills).** 리포지토리의 React design system을 변환하고 [Claude Design](https://claude.ai/design)에 업로드하여 생성하는 디자인이 실제 구성 요소를 사용하도록 합니다. 선택적으로 design system의 이름을 지정합니다. 예를 들어 `/design-sync Acme DS`. 첫 번째 동기화는 모든 구성 요소를 확인하며 큰 리포지토리에서는 몇 시간이 걸릴 수 있습니다. Anthropic API에서 사용 가능합니다. Amazon Bedrock, Google Cloud의 Agent Platform 및 Microsoft Foundry에서는 기본 도구가 claude.ai에 도달할 수 없으므로 명령어를 사용할 수 없습니다 |

77| `/diff` | 커밋되지 않은 변경 사항과 턴별 diff를 표시하는 대화형 diff 뷰어를 엽니다. 왼쪽/오른쪽 화살표를 사용하여 현재 git diff와 개별 Claude 턴 사이를 전환하고, 위/아래를 사용하여 파일을 탐색합니다. {/* min-version: 2.1.198 */}v2.1.198부터 열린 뷰어는 또한 리포지토리의 git 상태가 다른 터미널의 브랜치 전환 또는 커밋과 같이 세션 외부에서 변경될 때 자동으로 새로 고쳐집니다 |77| `/diff` | 커밋되지 않은 변경 사항과 턴별 diff를 표시하는 대화형 diff 뷰어를 엽니다. 왼쪽/오른쪽 화살표를 사용하여 현재 git diff와 개별 Claude 턴 사이를 전환하고, 위/아래를 사용하여 파일을 탐색합니다. {/* min-version: 2.1.198 */}v2.1.198부터 열린 뷰어는 또한 리포지토리의 git 상태가 다른 터미널의 브랜치 전환 또는 커밋과 같이 세션 외부에서 변경될 때 자동으로 새로 고쳐집니다 |

78| `/doctor` | Claude Code 설치 및 설정을 진단하고 확인합니다. 결과는 상태 아이콘과 함께 표시됩니다. `f`를 눌러 Claude가 보고된 문제를 수정하도록 합니다 |78| `/doctor` | **[Skill](/ko/skills#bundled-skills).** 설정 검사를 실행하여 문제를 진단하고 수정할 수 있습니다. 중복 또는 남은 설치, `PATH` 문제 및 구문 분석할 수 없는 설정 파일을 포함한 설치 상태를 확인합니다. 사용하지 않는 skills, MCP 서버 및 plugins와 컨텍스트 비용을 찾고, 로컬 `CLAUDE.md` 파일을 체크인된 파일과 중복 제거하고, 항상 로드되는 지침을 [skills](/ko/skills)로 마이그레이션하고 요청 시 로드되는 중첩 `CLAUDE.md` 파일로 마이그레이션하고, 느린 [hooks](/ko/hooks)를 표시하고, 최신 버전을 확인합니다. 또한 [auto mode](/ko/permissions#permission-modes)를 기본값으로 설정하고 자주 거부되는 읽기 전용 명령어를 [사전 승인](/ko/permissions)하도록 제안합니다. 먼저 결과를 보고하고 변경하기 전에 확인을 요청합니다. 터미널에서 `claude doctor`는 세션을 시작하지 않고 읽기 전용 설치 진단을 인쇄합니다. 별칭: `/checkup`. {/* min-version: 2.1.205 */}v2.1.205 이전에는 `/doctor`가 읽기 전용 진단 화면을 열었고 `f`를 누르면 보고서를 Claude로 보냈습니다 |

79| `/effort [level\|auto]` | 모델 [effort level](/ko/model-config#adjust-effort-level)을 설정합니다. `low`, `medium`, `high`, `xhigh`, `max` 또는 `ultracode`를 허용합니다. 사용 가능한 수준은 모델에 따라 다르며, `max` 및 `ultracode`는 세션 전용입니다. `ultracode`는 `xhigh` reasoning과 자동 [workflow](/ko/workflows#let-claude-decide-with-ultracode) 조율을 결합하는 Claude Code 설정입니다. `auto`는 모델 기본값으로 재설정합니다. 인수 없이 대화형 슬라이더를 엽니다. 왼쪽 및 오른쪽 화살표를 사용하여 수준을 선택하고 `Enter`를 눌러 적용합니다. 현재 응답이 완료될 때까지 기다리지 않고 즉시 적용됩니다 |79| `/effort [level\|auto]` | 모델 [effort level](/ko/model-config#adjust-effort-level)을 설정합니다. `low`, `medium`, `high`, `xhigh`, `max` 또는 `ultracode`를 허용합니다. 사용 가능한 수준은 모델에 따라 다르며, `max` 및 `ultracode`는 세션 전용입니다. `ultracode`는 `xhigh` reasoning과 자동 [workflow](/ko/workflows#let-claude-decide-with-ultracode) 조율을 결합하는 Claude Code 설정입니다. `auto`는 모델 기본값으로 재설정합니다. 인수 없이 대화형 슬라이더를 엽니다. 왼쪽 및 오른쪽 화살표를 사용하여 수준을 선택하고 `Enter`를 눌러 적용합니다. 현재 응답이 완료될 때까지 기다리지 않고 즉시 적용됩니다. {/* min-version: 2.1.205 */}비대화형 모드(`-p`)에서도 수준 인수와 함께 사용 가능하며, 현재 세션에만 적용되고 기본값으로 저장되지 않습니다. Claude Code v2.1.205 이상이 필요합니다. Fable 5, Opus 4.8 및 Opus 4.7에서는 [model-default effort hold](/ko/model-config#adjust-effort-level)가 적용되는 동안 비대화형 `/effort`가 `Not applied`를 보고하므로 대신 시작 시 `--effort`를 전달하세요 |

82| `/fast [on\|off]` | [fast mode](/ko/fast-mode)를 켜거나 끕니다 |82| `/fast [on\|off]` | [fast mode](/ko/fast-mode)를 켜거나 끕니다. {/* min-version: 2.1.205 */}비대화형 모드(`-p`)에서 `/fast`는 fast mode를 [`--settings`](/ko/cli-reference#cli-flags) 값으로 시작한 세션에서만 작동합니다. 예를 들어 `claude -p --settings '{"fastMode": true}'`. 토글은 현재 세션에만 적용되고 기본값으로 저장되지 않으며, 다른 비대화형 세션에서는 명령어가 fast mode를 사용할 수 없다고 보고합니다. Claude Code v2.1.205 이상이 필요합니다 |

84| `/fewer-permission-prompts` | **[Skill](/ko/skills#bundled-skills).** 트랜스크립트에서 일반적인 읽기 전용 Bash 및 MCP 도구 호출을 스캔한 다음, 권한 프롬프트를 줄이기 위해 프로젝트 `.claude/settings.json`에 우선순위가 지정된 허용 목록을 추가합니다 |84| `/fewer-permission-prompts` | **[Skill](/ko/skills#bundled-skills).** 트랜스크립트에서 일반적인 읽기 전용 Bash 및 MCP 도구 호출을 스캔한 다음, 권한 프롬프트를 줄이기 위해 프로젝트 `.claude/settings.json`에 우선순위가 지정된 허용 목록을 추가합니다 |

85| `/focus` | 포커스 뷰를 전환합니다. 마지막 프롬프트, 편집 diffstats가 있는 한 줄 도구 호출 요약 및 최종 응답만 표시합니다. {/* min-version: 2.1.198 */}v2.1.198부터 도구 호출 요약은 또한 턴에서 시작된 subagents의 개수를 세고 완료된 백그라운드 작업 알림을 단일 개수로 축소합니다. 선택 항목은 세션 전체에서 유지됩니다. 설정에서 [`viewMode`](/ko/settings#available-settings)를 설정하여 재정의할 수 있습니다. [fullscreen rendering](/ko/fullscreen)에서만 사용 가능합니다 |85| `/focus` | 포커스 뷰를 전환합니다. 마지막 프롬프트, 편집 diffstats가 있는 한 줄 도구 호출 요약 및 최종 응답만 표시합니다. {/* min-version: 2.1.198 */}v2.1.198부터 도구 호출 요약은 또한 턴에서 시작된 subagents의 개수를 세고 완료된 백그라운드 작업 알림을 단일 개수로 축소합니다. 선택 항목은 세션 전체에서 유지됩니다. 설정에서 [`viewMode`](/ko/settings#available-settings)를 설정하여 재정의할 수 있습니다. [fullscreen rendering](/ko/fullscreen)에서만 사용 가능합니다 |

86| `/fork <directive>` | {/* min-version: 2.1.161 */}[forked subagent](/ko/sub-agents#fork-the-current-conversation)를 생성합니다. 이는 전체 대화를 상속하고 지시문에서 작업하는 백그라운드 subagent이며, 당신은 계속 진행합니다. 그 결과는 완료되면 당신의 대화로 돌아옵니다. 대화의 복사본으로 자신이 전환하려면 `/branch`를 사용하세요. v2.1.161 이전에는 `/fork`가 `/branch`의 별칭입니다 |86| `/fork <directive>` | {/* min-version: 2.1.161 */}}[forked subagent](/ko/sub-agents#fork-the-current-conversation)를 생성합니다. 이는 전체 대화를 상속하고 지시문에서 작업하는 백그라운드 subagent이며, 당신은 계속 진행합니다. 그 결과는 완료되면 당신의 대화로 돌아옵니다. 대화의 복사본으로 자신이 전환하려면 `/branch`를 사용하세요. v2.1.161 이전에는 `/fork`가 `/branch`의 별칭입니다 |

87| `/goal [condition\|clear]` | [goal](/ko/goal)을 설정합니다. Claude는 조건이 충족될 때까지 여러 턴에 걸쳐 계속 작업합니다. 인수 없이 현재 또는 가장 최근에 달성한 goal을 표시합니다. `clear`, `stop`, `off`, `reset`, `none` 또는 `cancel`은 활성 goal을 조기에 제거합니다 |87| `/goal [condition\|clear]` | [goal](/ko/goal)을 설정합니다. Claude는 조건이 충족될 때까지 여러 턴에 걸쳐 계속 작업합니다. 인수 없이 현재 또는 가장 최근에 달성한 goal을 표시합니다. `clear`, `stop`, `off`, `reset`, `none` 또는 `cancel`은 활성 goal을 조기에 제거합니다 |

88| `/heapdump` | JavaScript 힙 스냅샷 및 메모리 분석을 `~/Desktop`에 작성하거나, Desktop 폴더가 없는 Linux의 경우 홈 디렉토리에 작성하여 높은 메모리 사용량을 진단합니다. [troubleshooting](/ko/troubleshooting#high-cpu-or-memory-usage)을 참조하세요 |88| `/heapdump` | JavaScript 힙 스냅샷 및 메모리 분석을 `~/Desktop`에 작성하거나, Desktop 폴더가 없는 Linux의 경우 홈 디렉토리에 작성하여 높은 메모리 사용량을 진단합니다. [troubleshooting](/ko/troubleshooting#high-cpu-or-memory-usage)을 참조하세요 |

99| `/loop [interval] [prompt]` | **[Skill](/ko/skills#bundled-skills).** 세션이 열려 있는 동안 프롬프트를 반복적으로 실행합니다. 간격을 생략하면 Claude가 반복 사이에 자동으로 속도를 조절합니다. 프롬프트를 생략하면 [사용 가능한 경우](/ko/scheduled-tasks#run-the-built-in-maintenance-prompt) Claude가 자동 유지 관리 검사를 실행하거나 `.claude/loop.md`의 프롬프트를 실행합니다. 예: `/loop 5m check if the deploy finished`. [Run prompts on a schedule](/ko/scheduled-tasks)을 참조하세요. 별칭: `/proactive` |99| `/loop [interval] [prompt]` | **[Skill](/ko/skills#bundled-skills).** 세션이 열려 있는 동안 프롬프트를 반복적으로 실행합니다. 간격을 생략하면 Claude가 반복 사이에 자동으로 속도를 조절합니다. 프롬프트를 생략하면 [사용 가능한 경우](/ko/scheduled-tasks#run-the-built-in-maintenance-prompt) Claude가 자동 유지 관리 검사를 실행하거나 `.claude/loop.md`의 프롬프트를 실행합니다. 예: `/loop 5m check if the deploy finished`. [Run prompts on a schedule](/ko/scheduled-tasks)을 참조하세요. 별칭: `/proactive` |

100| `/mcp [reconnect <server>\|enable\|disable [<server>\|all]]` | MCP 서버 연결 및 OAuth 인증을 관리합니다. 인수 없이 실행하여 대화형 목록을 열거나, `reconnect <server>`를 전달하여 연결이 끊긴 서버를 다시 연결하거나, `enable`/`disable`을 서버 이름 또는 `all`과 함께 전달하여 대화 상자를 열지 않고 연결 상태를 변경합니다 |100| `/mcp [reconnect <server>\|enable\|disable [<server>\|all]]` | MCP 서버 연결 및 OAuth 인증을 관리합니다. 인수 없이 실행하여 대화형 목록을 열거나, `reconnect <server>`를 전달하여 연결이 끊긴 서버를 다시 연결하거나, `enable`/`disable`을 서버 이름 또는 `all`과 함께 전달하여 대화 상자를 열지 않고 연결 상태를 변경합니다. {/* min-version: 2.1.205 */}비대화형 모드(`-p`)에서도 사용 가능하며, 인수 없이 실행하면 목록을 열지 않고 서버 상태의 텍스트 요약을 인쇄합니다. Claude Code v2.1.205 이상이 필요합니다 |

103| `/model [model]` | AI 모델을 전환하고 새 세션의 기본값으로 저장합니다. 이를 지원하는 모델의 경우 왼쪽/오른쪽 화살표를 사용하여 [effort level을 조정](/ko/model-config#adjust-effort-level)합니다. 인수 없이 선택기를 엽니다. 행에서 `s`를 눌러 현재 세션에만 전환합니다. 대화에 이전 출력이 있을 때 선택기가 확인을 요청합니다. 다음 응답이 캐시된 컨텍스트 없이 전체 기록을 다시 읽기 때문입니다. 확인되면 현재 응답이 완료될 때까지 기다리지 않고 변경 사항이 적용됩니다 |103| `/model [model]` | AI 모델을 전환하고 새 세션의 기본값으로 저장합니다. 이를 지원하는 모델의 경우 왼쪽/오른쪽 화살표를 사용하여 [effort level을 조정](/ko/model-config#adjust-effort-level)합니다. 인수 없이 선택기를 엽니다. 행에서 `s`를 눌러 현재 세션에만 전환합니다. 대화에 이전 출력이 있을 때 선택기가 확인을 요청합니다. 다음 응답이 캐시된 컨텍스트 없이 전체 기록을 다시 읽기 때문입니다. 확인되면 현재 응답이 완료될 때까지 기다리지 않고 변경 사항이 적용됩니다. {/* min-version: 2.1.205 */}비대화형 모드(`-p`)에서도 모델 인수와 함께 사용 가능하며, 현재 세션에만 적용되고 기본값으로 저장되지 않습니다. Claude Code v2.1.205 이상이 필요합니다 |

105| `/permissions` | 도구 권한에 대한 허용, 요청 및 거부 규칙을 관리합니다. 범위별로 규칙을 보고, 규칙을 추가 또는 제거하고, 작업 디렉토리를 관리하며, [최근 자동 모드 거부](/ko/auto-mode-config#review-denials)를 검토할 수 있는 대화형 대화 상자를 엽니다. 별칭: `/allowed-tools` |105| `/permissions` | 도구 권한에 대한 허용, 요청 및 거부 규칙을 관리합니다. 범위별로 규칙을 보고, 규칙을 추가 또는 제거하고, 작업 디렉토리를 관리하며, [최근 자동 모드 거부](/ko/auto-mode-config#review-denials)를 검토할 수 있는 대화형 대화 상자를 엽니다. 별칭: `/allowed-tools` |

106| `/plan [description]` | 프롬프트에서 직접 plan mode로 들어갑니다. 선택적 설명을 전달하여 plan mode로 들어가고 즉시 해당 작업으로 시작합니다. 예를 들어 `/plan fix the auth bug` |106| `/plan [description]` | 프롬프트에서 직접 plan mode로 들어갑니다. 선택적 설명을 전달하여 plan mode로 들어가고 즉시 해당 작업으로 시작합니다. 예를 들어 `/plan fix the auth bug` |

109| `/pr-comments [PR]` | {/* max-version: 2.1.90 */}v2.1.91에서 제거됨. 대신 Claude에 직접 pull request 댓글을 보도록 요청하세요. 이전 버전에서는 GitHub pull request의 댓글을 가져와 표시합니다. 현재 브랜치의 PR을 자동으로 감지하거나 PR URL 또는 번호를 전달합니다. `gh` CLI가 필요합니다 |109| `/pr-comments [PR]` | {/* max-version: 2.1.90 */}v2.1.91에서 제거됨. 대신 Claude에 직접 pull request 댓글을 보도록 요청하세요. 이전 버전에서는 GitHub pull request의 댓글을 가져와 표시합니다. 현재 브랜치의 PR을 자동으로 감지하거나 PR URL 또는 번호를 전달합니다. `gh` CLI가 필요합니다 |

111| `/radio` | Claude FM lo-fi 라디오를 브라우저에서 엽니다. 브라우저를 사용할 수 없을 때 스트림 URL을 인쇄합니다. Bedrock, Vertex 또는 Foundry에서는 사용할 수 없습니다 |111| `/radio` | Claude FM lo-fi 라디오를 브라우저에서 엽니다. 브라우저를 사용할 수 없을 때 스트림 URL을 인쇄합니다. Amazon Bedrock, Google Cloud의 Agent Platform 또는 Microsoft Foundry에서는 사용할 수 없습니다 |

114| `/reload-plugins [--force]` | 모든 활성 [plugins](/ko/plugins)를 다시 로드하여 재시작하지 않고 보류 중인 변경 사항을 적용합니다. 각 다시 로드된 구성 요소의 개수를 보고하고 로드 오류를 표시합니다. 다시 로드가 로드된 MCP 도구를 변경하고 프롬프트 캐시를 무효화할 때, 명령어는 경고하고 `--force`를 전달하지 않으면 건너뜁니다 |114| `/reload-plugins [--force]` | 모든 활성 [plugins](/ko/plugins)를 다시 로드하여 재시작하지 않고 보류 중인 변경 사항을 적용합니다. 각 다시 로드된 구성 요소의 개수를 보고하고 로드 오류를 표시합니다. 다시 로드가 로드된 MCP 도구를 변경하고 프롬프트 캐시를 무효화할 때, 명령어는 경고하고 `--force`를 전달하지 않으면 건너뜁니다 |

115| `/reload-skills` | {/* min-version: 2.1.152 */}}[skill](/ko/skills) 및 명령어 디렉토리를 다시 스캔하여 세션 중에 디스크에서 추가되거나 변경된 skills를 재시작하지 않고 사용할 수 있도록 합니다. 사용 가능한 skills의 개수와 추가되거나 제거된 skills의 개수를 보고합니다. v2.1.152에서 추가됨 |115| `/reload-skills` | {/* min-version: 2.1.152 */}}[skill](/ko/skills) 및 명령어 디렉토리를 다시 스캔하여 세션 중에 디스크에서 추가되거나 변경된 skills를 재시작하지 않고 사용할 수 있도록 합니다. 사용 가능한 skills의 개수와 추가되거나 제거된 skills의 개수를 보고합니다. v2.1.152에서 추가됨 |

118| `/rename [name]` | 현재 세션의 이름을 바꾸고 프롬프트 바에 이름을 표시합니다. 이름이 없으면 대화 기록에서 자동으로 생성합니다 |118| `/rename [name]` | 현재 세션의 이름을 바꾸고 프롬프트 바에 이름을 표시합니다. 이름이 없으면 대화 기록에서 자동으로 생성합니다. {/* min-version: 2.1.205 */}비대화형 모드(`-p`)에서도 사용 가능합니다. Claude Code v2.1.205 이상이 필요합니다 |

119| `/resume [session]` | ID 또는 이름으로 대화를 재개하거나 세션 선택기를 엽니다. v2.1.144부터 [background sessions](/ko/agent-view)이 선택기에 `bg`로 표시됩니다. 별칭: `/continue` |119| `/resume [session]` | ID 또는 이름으로 대화를 재개하거나 세션 선택기를 엽니다. v2.1.144부터 [background sessions](/ko/agent-view)이 선택기에 `bg`로 표시됩니다. 별칭: `/continue` |

120| `/review [PR]` | GitHub pull request를 번호로 검토합니다. `/code-review`와 동일한 검토 엔진을 사용합니다. 인수 없이 선택할 열린 PR을 나열합니다. 클라우드 기반 검토의 경우 [`/code-review ultra`](/ko/ultrareview)를 참조하세요 |120| `/review [PR]` | {/* min-version: 2.1.202 */}}GitHub pull request를 번호로 빠른 단일 패스, 읽기 전용 검토를 실행합니다. 인수 없이 선택할 열린 PR을 나열합니다. PR 번호 뒤의 텍스트는 추가 검토 지침이 됩니다. v2.1.186부터 v2.1.201까지 `/review`는 `/code-review medium`과 동일한 다중 agent 엔진을 실행했습니다. 선택한 노력 수준에서 다중 agent 검토의 경우 [`/code-review <level> <pr#>`](/ko/code-review#review-a-diff-locally)를 사용하세요. 클라우드 기반 검토의 경우 [`/code-review ultra`](/ko/ultrareview)를 참조하세요 |

121| `/rewind` | 대화 및/또는 코드를 이전 지점으로 되감기하거나 선택한 메시지에서 요약합니다. [checkpointing](/ko/checkpointing)을 참조하세요. 별칭: `/checkpoint`, `/undo` |121| `/rewind` | 대화 및/또는 코드를 이전 지점으로 되감기하거나 선택한 메시지에서 요약합니다. [checkpointing](/ko/checkpointing)을 참조하세요. 별칭: `/checkpoint`, `/undo` |

122| `/run` | **[Skill](/ko/skills#bundled-skills).** 프로젝트의 앱을 시작하고 구동하여 테스트나 타입 검사가 아닌 실행 중인 앱에서 변경 사항이 작동하는 것을 확인합니다. [Run and verify your app](/ko/skills#run-and-verify-your-app)을 참조하세요. {/* min-version: 2.1.145 */}Claude Code v2.1.145 이상이 필요합니다 |122| `/run` | **[Skill](/ko/skills#bundled-skills).** 프로젝트의 앱을 시작하고 구동하여 테스트나 타입 검사가 아닌 실행 중인 앱에서 변경 사항이 작동하는 것을 확인합니다. [Run and verify your app](/ko/skills#run-and-verify-your-app)을 참조하세요. {/* min-version: 2.1.145 */}}Claude Code v2.1.145 이상이 필요합니다 |

123| `/run-skill-generator` | **[Skill](/ko/skills#bundled-skills).** 깨끗한 환경에서 프로젝트의 앱을 빌드, 시작 및 구동하는 방법을 `/run` 및 `/verify`에 가르치고, 프로젝트별 [skill](/ko/skills#run-and-verify-your-app)을 작성합니다. {/* min-version: 2.1.145 */}Claude Code v2.1.145 이상이 필요합니다 |123| `/run-skill-generator` | **[Skill](/ko/skills#bundled-skills).** 깨끗한 환경에서 프로젝트의 앱을 빌드, 시작 및 구동하는 방법을 `/run` 및 `/verify`에 가르치고, 프로젝트별 [skill](/ko/skills#run-and-verify-your-app)을 작성합니다. {/* min-version: 2.1.145 */}}Claude Code v2.1.145 이상이 필요합니다 |

125| `/schedule [description]` | [routines](/ko/routines)를 만들거나, 업데이트하거나, 나열하거나, 실행합니다. Anthropic 관리 클라우드 인프라에서 실행됩니다. Claude가 설정 과정을 대화형으로 안내합니다. 별칭: `/routines` |125| `/schedule [description]` | [routines](/ko/routines)를 만들거나, 업데이트하거나, 나열하거나, 실행합니다. Anthropic 관리 클라우드 인프라에서 실행됩니다. Claude가 설정 과정을 대화형으로 안내합니다. 별칭: `/routines` |

126| `/scroll-speed` | 마우스 휠 [scroll speed](/ko/fullscreen#mouse-wheel-scrolling)를 대화형으로 조정합니다. 대화 상자가 열려 있는 동안 스크롤할 수 있는 눈금자를 사용하여 변경 사항을 미리 봅니다. [fullscreen rendering](/ko/fullscreen)에서만 사용 가능하며 JetBrains IDE 터미널에서는 사용할 수 없습니다 |126| `/scroll-speed` | 마우스 휠 [scroll speed](/ko/fullscreen#mouse-wheel-scrolling)를 대화형으로 조정합니다. 대화 상자가 열려 있는 동안 스크롤할 수 있는 눈금자를 사용하여 변경 사항을 미리 봅니다. [fullscreen rendering](/ko/fullscreen)에서만 사용 가능하며 JetBrains IDE 터미널에서는 사용할 수 없습니다 |

128| `/setup-bedrock` | [Amazon Bedrock](/ko/amazon-bedrock) 인증, 지역 및 모델 핀을 대화형 마법사를 통해 구성합니다. `CLAUDE_CODE_USE_BEDROCK=1`이 설정되어 있을 때만 표시됩니다. 처음 Bedrock을 사용하는 사용자는 로그인 화면에서도 이 마법사에 액세스할 수 있습니다 |128| `/setup-bedrock` | [Amazon Bedrock](/ko/amazon-bedrock) 인증, 지역 및 모델 핀을 대화형 마법사를 통해 구성합니다. `CLAUDE_CODE_USE_BEDROCK=1`이 설정되어 있을 때만 표시됩니다. 처음 Amazon Bedrock을 사용하는 사용자는 로그인 화면에서도 이 마법사에 액세스할 수 있습니다 |

129| `/setup-vertex` | [Google Vertex AI](/ko/google-vertex-ai) 인증, 프로젝트, 지역 및 모델 핀을 대화형 마법사를 통해 구성합니다. `CLAUDE_CODE_USE_VERTEX=1`이 설정되어 있을 때만 표시됩니다. 처음 Vertex AI를 사용하는 사용자는 로그인 화면에서도 이 마법사에 액세스할 수 있습니다 |129| `/setup-vertex` | [Google Cloud의 Agent Platform](/ko/google-vertex-ai) 인증, 프로젝트, 지역 및 모델 핀을 대화형 마법사를 통해 구성합니다. `CLAUDE_CODE_USE_VERTEX=1`이 설정되어 있을 때만 표시됩니다. 처음 Google Cloud의 Agent Platform을 사용하는 사용자는 로그인 화면에서도 이 마법사에 액세스할 수 있습니다 |

130| `/simplify [target]` | {/* min-version: 2.1.154 */}}**[Skill](/ko/skills#bundled-skills).** 변경된 코드를 정리 기회에 대해 검토하고 수정 사항을 적용합니다. 4개의 검토 [agents](/ko/sub-agents)가 병렬로 실행되어 기존 헬퍼의 재사용, 단순화, 효율성 및 변경이 추상화의 올바른 수준에 있는지 여부를 다룹니다. v2.1.154부터 검토는 정확성 버그를 찾지 않습니다. 버그를 찾으려면 `/code-review`를 사용하세요. 이전 버전에서 `/simplify`는 `/code-review --fix`와 동일합니다. 특정 대상을 검토하려면 경로 또는 PR 참조를 전달합니다 |130| `/simplify [target]` | {/* min-version: 2.1.154 */}}**[Skill](/ko/skills#bundled-skills).** 변경된 코드를 정리 기회에 대해 검토하고 수정 사항을 적용합니다. 4개의 검토 [agents](/ko/sub-agents)가 병렬로 실행되어 기존 헬퍼의 재사용, 단순화, 효율성 및 변경이 추상화의 올바른 수준에 있는지 여부를 다룹니다. v2.1.154부터 검토는 정확성 버그를 찾지 않습니다. 버그를 찾으려면 `/code-review`를 사용하세요. 이전 버전에서 `/simplify`는 `/code-review --fix`와 동일합니다. 특정 대상을 검토하려면 경로 또는 PR 참조를 전달합니다 |

131| `/skills` | 사용 가능한 [skills](/ko/skills)를 나열합니다. {/* min-version: 2.1.121 */}}v2.1.121부터 입력하여 이름으로 목록을 필터링합니다. `t`를 눌러 토큰 수로 정렬합니다. `Space`를 눌러 [Claude 또는 `/` 메뉴에서 skill의 가시성을 순환](/ko/skills#override-skill-visibility-from-settings)한 다음 `Enter`를 눌러 저장합니다 |131| `/skills` | 사용 가능한 [skills](/ko/skills)를 나열합니다. {/* min-version: 2.1.121 */}}v2.1.121부터 입력하여 이름으로 목록을 필터링합니다. `t`를 눌러 토큰 수로 정렬합니다. `Space`를 눌러 [Claude 또는 `/` 메뉴에서 skill의 가시성을 순환](/ko/skills#override-skill-visibility-from-settings)한 다음 `Enter`를 눌러 저장합니다 |

136| `/stop` | 현재 [background session](/ko/agent-view)을 중지합니다. 백그라운드 세션에 연결되어 있을 때만 사용 가능합니다. 트랜스크립트 및 모든 worktree는 유지됩니다. 중지하지 않고 분리하려면 `/exit`를 사용하거나 `←`를 누르세요 |136| `/stop` | 현재 [background session](/ko/agent-view)을 중지합니다. 백그라운드 세션에 연결되어 있을 때만 사용 가능합니다. 트랜스크립트 및 모든 worktree는 유지됩니다. 중지하지 않고 분리하려면 `/exit`를 사용하거나 `←`를 누르세요 |

144| `/ultrareview [PR]` | [ultrareview](/ko/ultrareview)를 사용하여 클라우드 샌드박스에서 깊은 다중 agent 코드 검토를 실행합니다. 선호되는 호출은 이제 `/code-review ultra`이며, `/ultrareview`는 별칭으로 유지됩니다. Pro 및 Max에서 3회 무료 실행을 포함한 후 [usage credits](https://support.claude.com/en/articles/12429409-extra-usage-for-paid-claude-plans)가 필요합니다 |144| `/ultrareview [PR]` | [ultrareview](/ko/ultrareview)를 사용하여 클라우드 샌드박스에서 깊은 다중 agent 코드 검토를 실행합니다. 선호되는 호출은 이제 `/code-review ultra`이며, `/ultrareview`는 별칭으로 유지됩니다. Pro 및 Max에서 3회 무료 실행을 포함한 후 [usage credits](https://support.claude.com/en/articles/12429409-extra-usage-for-paid-claude-plans)가 필요합니다 |

146| `/usage` | 세션 비용, 요금제 사용 제한 및 활동 통계를 표시합니다. Pro, Max, Team 또는 Enterprise 요금제에서는 skill, subagent, plugin 및 MCP 서버별 사용량 분석을 포함합니다. 자세한 내용은 [cost tracking guide](/ko/costs#using-the-%2Fusage-command)를 참조하세요. `/cost` 및 `/stats`는 별칭입니다 |146| `/usage` | 세션 비용, 요금제 사용 제한 및 활동 통계를 표시합니다. Pro, Max, Team 또는 Enterprise 요금제에서는 skill, subagent, plugin 및 MCP 서버별 사용량 분석을 포함합니다. 자세한 내용은 [cost tracking guide](/ko/costs#using-the-%2Fusage-command)를 참조하세요. `/cost` 및 `/stats`는 별칭입니다 |

147| `/usage-credits` | 제한에 도달했을 때 계속 작업할 수 있도록 사용 크레딧을 구성합니다. 이전에는 `/extra-usage` |147| `/usage-credits` | 제한에 도달했을 때 계속 작업할 수 있도록 사용 크레딧을 구성합니다. 사용 크레딧 청구 페이지를 브라우저에서 엽니다. {/* min-version: 2.1.205 */}}SSH를 통한 경우처럼 브라우저를 열 수 없을 때, 명령어는 대신 방문할 URL을 인쇄합니다. Claude Code v2.1.205 이상이 필요하며, 이전 버전은 그 경우 아무것도 표시하지 않았습니다. 이전에는 `/extra-usage` |

148| `/verify` | **[Skill](/ko/skills#bundled-skills).** 테스트나 타입 검사가 아닌 프로젝트의 앱을 빌드하고 실행하고 결과를 관찰하여 코드 변경이 수행해야 할 작업을 수행하는지 확인합니다. [Run and verify your app](/ko/skills#run-and-verify-your-app)을 참조하세요. {/* min-version: 2.1.145 */}Claude Code v2.1.145 이상이 필요합니다 |148| `/verify` | **[Skill](/ko/skills#bundled-skills).** 테스트나 타입 검사가 아닌 프로젝트의 앱을 빌드하고 실행하고 결과를 관찰하여 코드 변경이 수행해야 할 작업을 수행하는지 확인합니다. [Run and verify your app](/ko/skills#run-and-verify-your-app)을 참조하세요. {/* min-version: 2.1.145 */}}Claude Code v2.1.145 이상이 필요합니다 |

149| `/vim` | {/* max-version: 2.1.91 */}v2.1.92에서 제거됨. Vim과 Normal 편집 모드 사이를 전환하려면 `/config` → Editor mode를 사용하세요 |149| `/vim` | {/* max-version: 2.1.91 */}}v2.1.92에서 제거됨. Vim과 Normal 편집 모드 사이를 전환하려면 `/config` → Editor mode를 사용하세요 |

150| `/voice [hold\|tap\|off]` | [voice dictation](/ko/voice-dictation)을 전환하거나 특정 모드에서 활성화합니다. Claude.ai 계정이 필요합니다 |150| `/voice [hold\|tap\|off]` | [voice dictation](/ko/voice-dictation)을 전환하거나 특정 모드에서 활성화합니다. Claude.ai 계정이 필요합니다 |

151| `/web-setup` | 로컬 `gh` CLI 자격 증명을 사용하여 GitHub 계정을 [Claude Code on the web](/ko/web-quickstart#connect-from-your-terminal)에 연결합니다. `/schedule`은 GitHub가 연결되지 않은 경우 자동으로 이를 요청합니다 |151| `/web-setup` | 로컬 `gh` CLI 자격 증명을 사용하여 GitHub 계정을 [Claude Code on the web](/ko/web-quickstart#connect-from-your-terminal)에 연결합니다. `/schedule`은 GitHub가 연결되지 않은 경우 자동으로 이를 요청합니다 |

common-workflows.md +1 −1

Details

255 </Step>255 </Step>

256</Steps>256</Steps>

257 257

258`gh pr create`를 사용하여 PR을 만들면 세션이 자동으로 해당 PR에 연결됩니다. 나중에 `claude --from-pr <number>`로 재개하거나 [`/resume` 선택기](/ko/sessions#use-the-session-picker)에 PR URL을 붙여넣어 재개할 수 있습니다.258`gh pr create`를 사용하여 PR을 만들면 세션이 자동으로 해당 PR에 연결됩니다. 나중에 `claude --from-pr 123`으로 재개하거나 (123을 PR 번호로 바꾸기), [`/resume` 선택기](/ko/sessions#use-the-session-picker)에 PR URL을 붙여넣어 재개할 수 있습니다.

259 259

260<Tip>260<Tip>

261 Claude가 생성한 PR을 제출하기 전에 검토하고 Claude에게 잠재적 위험이나 고려사항을 강조하도록 요청하십시오.261 Claude가 생성한 PR을 제출하기 전에 검토하고 Claude에게 잠재적 위험이나 고려사항을 강조하도록 요청하십시오.

communications-kit.md +1 −1

Details

271 271

272때로는 Claude가 모든 편집 전에 요청하기를 원합니다. 때로는 그냥 배포하기를 원합니다. 영원히 하나를 선택할 필요는 없습니다.272때로는 Claude가 모든 편집 전에 요청하기를 원합니다. 때로는 그냥 배포하기를 원합니다. 영원히 하나를 선택할 필요는 없습니다.

273 273

274*Shift+Tab*은 Claude가 얻는 자유도를 순환합니다: *default*는 위험한 것 전에 요청하고, *acceptEdits*는 파일 편집과 일반적인 파일 시스템 명령어가 흐르도록 하면서도 다른 셸 명령어 전에 확인하고, *plan*은 무엇이든 건드리기 전에 승인을 위해 변경 사항을 제안합니다. Plan 모드는 신뢰 구축자이므로 여러 파일을 건드리는 모든 것에 대해 거기서 시작하십시오.274*Shift+Tab*은 Claude가 얻는 자유도를 순환합니다: *Manual*(`default` 설정 값)은 각 작업 전에 요청하고, *acceptEdits*는 파일 편집과 일반적인 파일 시스템 명령어가 흐르도록 하면서도 다른 셸 명령어 전에 확인하고, *plan*은 무엇이든 건드리기 전에 승인을 위해 변경 사항을 제안합니다. Plan 모드는 신뢰 구축자이므로 여러 파일을 건드리는 모든 것에 대해 거기서 시작하십시오.

275 275

276*지금 시도하기:* 다음 리팩토링에서 Shift+Tab을 누르면 "plan"이 표시될 때까지 누른 다음 변경 사항을 설명하십시오. 단일 파일이 움직이기 전에 전체 제안을 받을 것입니다.276*지금 시도하기:* 다음 리팩토링에서 Shift+Tab을 누르면 "plan"이 표시될 때까지 누른 다음 변경 사항을 설명하십시오. 단일 파일이 움직이기 전에 전체 제안을 받을 것입니다.

277 277

computer-use.md +1 −1

Details

240* macOS를 사용 중입니다. 컴퓨터 사용은 Linux 또는 Windows에서 사용할 수 없습니다. Windows에서는 [Desktop의 컴퓨터 사용](/ko/desktop#let-claude-use-your-computer)을 대신 사용합니다.240* macOS를 사용 중입니다. 컴퓨터 사용은 Linux 또는 Windows에서 사용할 수 없습니다. Windows에서는 [Desktop의 컴퓨터 사용](/ko/desktop#let-claude-use-your-computer)을 대신 사용합니다.

241* Claude Code v2.1.85 이상을 실행 중입니다. `claude --version`을 실행하여 확인합니다.241* Claude Code v2.1.85 이상을 실행 중입니다. `claude --version`을 실행하여 확인합니다.

242* Pro 또는 Max 플랜을 사용 중입니다. `/status`를 실행하여 구독을 확인합니다.242* Pro 또는 Max 플랜을 사용 중입니다. `/status`를 실행하여 구독을 확인합니다.

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

244* 대화형 세션에 있습니다. 컴퓨터 사용은 `-p` 플래그를 사용한 비대화형 모드에서 사용할 수 없습니다.244* 대화형 세션에 있습니다. 컴퓨터 사용은 `-p` 플래그를 사용한 비대화형 모드에서 사용할 수 없습니다.

245 245

246<h2 id="see-also">246<h2 id="see-also">

costs.md +1 −1

Details

51 사용자 정의 속도 제한이 있는 조직의 경우, 이 워크스페이스의 Claude Code 트래픽은 조직의 전체 API 속도 제한에 포함됩니다. Claude Console의 이 워크스페이스의 한도 페이지에서 [워크스페이스 속도 제한](https://platform.claude.com/docs/ko/api/rate-limits#setting-lower-limits-for-workspaces)을 설정하여 Claude Code의 할당량을 제한하고 다른 프로덕션 워크로드를 보호할 수 있습니다.51 사용자 정의 속도 제한이 있는 조직의 경우, 이 워크스페이스의 Claude Code 트래픽은 조직의 전체 API 속도 제한에 포함됩니다. Claude Console의 이 워크스페이스의 한도 페이지에서 [워크스페이스 속도 제한](https://platform.claude.com/docs/ko/api/rate-limits#setting-lower-limits-for-workspaces)을 설정하여 Claude Code의 할당량을 제한하고 다른 프로덕션 워크로드를 보호할 수 있습니다.

52</Note>52</Note>

53 53

54Bedrock, Vertex 및 Foundry에서 Claude Code는 클라우드에서 메트릭을 전송하지 않습니다. 자체 호스팅된 [Claude apps gateway](/ko/claude-apps-gateway)는 사용자별 사용량 귀속, 토큰 수를 포함한 OTLP 메트릭, 그리고 이러한 제공자에 대한 [사용자별 지출 한도](/ko/claude-apps-gateway-spend-limits)를 제공합니다. 다른 [LLM gateway](/ko/llm-gateway)를 통해 Claude Code를 라우팅하는 조직은 게이트웨이가 모든 요청을 보기 때문에 그곳에서 지출을 추적할 수 있습니다.54Amazon Bedrock, Google Cloud의 Agent Platform 및 Microsoft Foundry에서 Claude Code는 클라우드에서 메트릭을 전송하지 않습니다. 자체 호스팅된 [Claude apps gateway](/ko/claude-apps-gateway)는 사용자별 사용량 귀속, 토큰 수를 포함한 OTLP 메트릭, 그리고 이러한 제공자에 대한 [사용자별 지출 한도](/ko/claude-apps-gateway-spend-limits)를 제공합니다. 다른 [LLM gateway](/ko/llm-gateway)를 통해 Claude Code를 라우팅하는 조직은 게이트웨이가 모든 요청을 보기 때문에 그곳에서 지출을 추적할 수 있습니다.

55 55

56<h3 id="rate-limit-recommendations">56<h3 id="rate-limit-recommendations">

57 속도 제한 권장사항57 속도 제한 권장사항

data-usage.md +8 −8

Details

23 Development Partner Program23 Development Partner Program

24</h3>24</h3>

25 25

26[Development Partner Program](https://support.claude.com/ko/articles/11174108-about-the-development-partner-program)을 통해 학습할 자료를 제공하는 방법에 명시적으로 옵트인하는 경우, 제공된 자료를 사용하여 모델을 학습할 수 있습니다. 조직 관리자는 조직에 대해 Development Partner Program에 명시적으로 옵트인할 수 있습니다. 이 프로그램은 Anthropic 자체 API에만 사용 가능하며 Bedrock 또는 Vertex 사용자는 이용할 수 없습니다.26[Development Partner Program](https://support.claude.com/ko/articles/11174108-about-the-development-partner-program)을 통해 학습할 자료를 제공하는 방법에 명시적으로 옵트인하는 경우, 제공된 자료를 사용하여 모델을 학습할 수 있습니다. 조직 관리자는 조직에 대해 Development Partner Program에 명시적으로 옵트인할 수 있습니다. 이 프로그램은 Anthropic 자체 API에만 사용 가능하며 Amazon Bedrock 또는 Google Cloud의 Agent Platform 사용자는 이용할 수 없습니다.

27 27

28<h3 id="feedback-using-the-/feedback-command">28<h3 id="feedback-using-the-/feedback-command">

29 `/feedback` 명령을 사용한 피드백29 `/feedback` 명령을 사용한 피드백

39 39

40등급 메시지 이후에 "Anthropic이 세션 기록을 확인하여 Claude Code를 개선하는 데 도움을 줄 수 있나요?"라는 별도의 후속 질문이 표시될 수 있습니다. 이는 등급과 구별되는 선택적 두 번째 단계입니다:40등급 메시지 이후에 "Anthropic이 세션 기록을 확인하여 Claude Code를 개선하는 데 도움을 줄 수 있나요?"라는 별도의 후속 질문이 표시될 수 있습니다. 이는 등급과 구별되는 선택적 두 번째 단계입니다:

41 41

42* **예**: 대화 기록, 모든 서브에이전트 기록, 디스크의 원본 세션 로그 파일을 Anthropic에 업로드합니다. 알려진 API 키 및 토큰 패턴은 업로드 전에 제거됩니다. 소스 코드, 파일 내용 및 기타 대화 내용은 그대로 업로드됩니다. 공유된 기록은 최대 6개월 동안 보관됩니다. Bedrock, Vertex AI, Foundry, 로그인된 [Claude apps gateway](/ko/claude-apps-gateway) 세션에서는 Yes가 동일한 페이로드를 `~/.claude/feedback-bundles/` 아래의 로컬 아카이브에 작성합니다. 파일을 전달할 때까지 아무것도 머신을 떠나지 않습니다.42* **예**: 대화 기록, 모든 서브에이전트 기록, 디스크의 원본 세션 로그 파일을 Anthropic에 업로드합니다. 알려진 API 키 및 토큰 패턴은 업로드 전에 제거됩니다. 소스 코드, 파일 내용 및 기타 대화 내용은 그대로 업로드됩니다. 공유된 기록은 최대 6개월 동안 보관됩니다. Amazon Bedrock, Google Cloud의 Agent Platform, Microsoft Foundry, 로그인된 [Claude apps gateway](/ko/claude-apps-gateway) 세션에서는 Yes가 동일한 페이로드를 `~/.claude/feedback-bundles/` 아래의 로컬 아카이브에 작성합니다. 파일을 전달할 때까지 아무것도 머신을 떠나지 않습니다.

43* **아니오**: 아무것도 보내지 않고 거절합니다.43* **아니오**: 아무것도 보내지 않고 거절합니다.

44* **다시 묻지 않기**: 거절하고 향후 세션에서 이 후속 질문이 표시되지 않도록 합니다.44* **다시 묻지 않기**: 거절하고 향후 세션에서 이 후속 질문이 표시되지 않도록 합니다.

45 45

90저장 시 암호화는 모델 제공자에 따라 달라집니다:90저장 시 암호화는 모델 제공자에 따라 달라집니다:

91 91

92| 제공자 | 저장 시 암호화 |92| 제공자 | 저장 시 암호화 |

~~93| ---------------------- | ------------------------------------------------------------------------------------------------- |~~93| ---------------------------- | ------------------------------------------------------------------------------------------------- |

94| Anthropic API | 인프라 수준 디스크 암호화(AES-256). [Zero Data Retention](/ko/zero-data-retention)을 활성화하여 서버 측 지속성이 없도록 합니다. |94| Anthropic API | 인프라 수준 디스크 암호화(AES-256). [Zero Data Retention](/ko/zero-data-retention)을 활성화하여 서버 측 지속성이 없도록 합니다. |

95| Amazon Bedrock | AWS 관리 키를 사용한 AES-256. AWS KMS를 통해 고객 관리 키를 사용할 수 있습니다. |95| Amazon Bedrock | AWS 관리 키를 사용한 AES-256. AWS KMS를 통해 고객 관리 키를 사용할 수 있습니다. |

~~96| Google Cloud Vertex AI | Google 관리 암호화 키. CMEK를 사용할 수 있습니다. |~~96| Google Cloud의 Agent Platform | Google 관리 암호화 키. CMEK를 사용할 수 있습니다. |

97| Microsoft Foundry | 요청은 AES-256 디스크 암호화를 사용하는 Anthropic 인프라로 라우팅됩니다. |97| Microsoft Foundry | 요청은 AES-256 디스크 암호화를 사용하는 Anthropic 인프라로 라우팅됩니다. |

98 98

99Claude Code는 Anthropic의 API를 기반으로 구축되었습니다. API 로깅 절차를 포함한 API 보안 제어에 대한 자세한 내용은 [Anthropic Trust Center](https://trust.anthropic.com)의 규정 준수 아티팩트를 참조하세요.99Claude Code는 Anthropic의 API를 기반으로 구축되었습니다. API 로깅 절차를 포함한 API 보안 제어에 대한 자세한 내용은 [Anthropic Trust Center](https://trust.anthropic.com)의 규정 준수 아티팩트를 참조하세요.

121 121

122`/feedback` 명령을 실행하면 코드를 포함한 대화 기록의 복사본이 Anthropic으로 전송됩니다. 제출하기 전에 포함할 기록의 양을 선택합니다. 기본값인 현재 세션만 포함하거나, 지난 24시간 또는 7일 동안 같은 프로젝트의 다른 세션도 포함할 수 있습니다. 데이터는 TLS를 통해 전송 중에 암호화되고 Google Cloud Storage에 저장되며, Google Cloud Storage는 기본적으로 저장된 데이터를 암호화합니다. 선택적으로 공개 저장소에 GitHub 이슈가 생성됩니다. 거부하려면 `DISABLE_FEEDBACK_COMMAND` 환경 변수를 `1`로 설정합니다.122`/feedback` 명령을 실행하면 코드를 포함한 대화 기록의 복사본이 Anthropic으로 전송됩니다. 제출하기 전에 포함할 기록의 양을 선택합니다. 기본값인 현재 세션만 포함하거나, 지난 24시간 또는 7일 동안 같은 프로젝트의 다른 세션도 포함할 수 있습니다. 데이터는 TLS를 통해 전송 중에 암호화되고 Google Cloud Storage에 저장되며, Google Cloud Storage는 기본적으로 저장된 데이터를 암호화합니다. 선택적으로 공개 저장소에 GitHub 이슈가 생성됩니다. 거부하려면 `DISABLE_FEEDBACK_COMMAND` 환경 변수를 `1`로 설정합니다.

123 123

124Bedrock 또는 Vertex와 같은 타사 제공자를 사용하거나 Anthropic 자격 증명이 구성되지 않은 경우, `/feedback`은 보고서를 Anthropic으로 전송하는 대신 `~/.claude/feedback-bundles/` 아래의 로컬 아카이브에 작성합니다. 알려진 API 키 및 토큰 패턴은 아카이브가 작성되기 전에 제거됩니다. 파일을 Anthropic 계정 담당자에게 보내거나 지원 요청에 첨부할 때까지 머신을 벗어나지 않습니다.124Amazon Bedrock 또는 Google Cloud의 Agent Platform과 같은 타사 제공자를 사용하거나 Anthropic 자격 증명이 구성되지 않은 경우, `/feedback`은 보고서를 Anthropic으로 전송하는 대신 `~/.claude/feedback-bundles/` 아래의 로컬 아카이브에 작성합니다. 알려진 API 키 및 토큰 패턴은 아카이브가 작성되기 전에 제거됩니다. 파일을 Anthropic 계정 담당자에게 보내거나 지원 요청에 첨부할 때까지 머신을 벗어나지 않습니다.

125 125

126<h2 id="default-behaviors-by-api-provider">126<h2 id="default-behaviors-by-api-provider">

127 API 제공자별 기본 동작127 API 제공자별 기본 동작

128</h2>128</h2>

129 129

130기본적으로 Bedrock, Vertex, Foundry 또는 AWS의 Claude Platform을 사용할 때 오류 보고, 원격 측정 및 버그 보고가 비활성화됩니다. 세션 품질 설문조사 및 WebFetch 도메인 안전 검사는 예외이며 제공자와 관계없이 실행됩니다. 서명된 [Claude 앱 게이트웨이](/ko/claude-apps-gateway) 세션에서는 게이트웨이 자격 증명 자체에 의해 Anthropic에 대한 사용 분석, 오류 보고 및 설문조사 평가가 비활성화되며, 이를 다시 활성화할 수 있는 설정이 없습니다. `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC`을 설정하여 설문조사를 포함한 모든 필수가 아닌 트래픽을 한 번에 거부할 수 있습니다. 이 변수는 WebFetch 검사에 영향을 주지 않으며, WebFetch 검사는 자체 거부 옵션이 있습니다. 다음은 전체 기본 동작입니다:130기본적으로 Amazon Bedrock, Google Cloud의 Agent Platform, Microsoft Foundry 또는 AWS의 Claude Platform을 사용할 때 오류 보고, 원격 측정 및 버그 보고가 비활성화됩니다. 세션 품질 설문조사 및 WebFetch 도메인 안전 검사는 예외이며 제공자와 관계없이 실행됩니다. 서명된 [Claude 앱 게이트웨이](/ko/claude-apps-gateway) 세션에서는 게이트웨이 자격 증명 자체에 의해 Anthropic에 대한 사용 분석, 오류 보고 및 설문조사 평가가 비활성화되며, 이를 다시 활성화할 수 있는 설정이 없습니다. `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC`을 설정하여 설문조사를 포함한 모든 필수가 아닌 트래픽을 한 번에 거부할 수 있습니다. 이 변수는 WebFetch 검사에 영향을 주지 않으며, WebFetch 검사는 자체 거부 옵션이 있습니다. 다음은 전체 기본 동작입니다:

131 131

133| ------------------------------- | ------------------------------------------------------------------------------ | ------------------------------------------------------------------------------ | ------------------------------------------------------------------------------ | ------------------------------------------------------------------------------ | ------------------------------------------------------------------------------ |133| ------------------------------- | ------------------------------------------------------------------------------ | ------------------------------------------------------------------------------ | ------------------------------------------------------------------------------ | ------------------------------------------------------------------------------ | ------------------------------------------------------------------------------ |

139 139

140모든 환경 변수는 `settings.json`에 체크인할 수 있습니다([settings reference](/ko/settings) 참조).140모든 환경 변수는 `settings.json`에 체크인할 수 있습니다([settings reference](/ko/settings) 참조).

141 141

142v2.1.126부터 호스트 플랫폼이 `CLAUDE_CODE_PROVIDER_MANAGED_BY_HOST`를 설정하면, Vertex, Bedrock 및 Foundry에서 메트릭은 기본적으로 켜지며 표준 `DISABLE_TELEMETRY` 거부 옵션을 따릅니다. Sentry 오류 보고 및 `/feedback` 보고는 해당 제공자에서 기본적으로 꺼진 상태로 유지됩니다.142v2.1.126부터 호스트 플랫폼이 `CLAUDE_CODE_PROVIDER_MANAGED_BY_HOST`를 설정하면, Google Cloud의 Agent Platform, Amazon Bedrock 및 Microsoft Foundry에서 메트릭은 기본적으로 켜지며 표준 `DISABLE_TELEMETRY` 거부 옵션을 따릅니다. Sentry 오류 보고 및 `/feedback` 보고는 해당 제공자에서 기본적으로 꺼진 상태로 유지됩니다.

143 143

144<h3 id="webfetch-domain-safety-check">144<h3 id="webfetch-domain-safety-check">

145 WebFetch 도메인 안전 검사145 WebFetch 도메인 안전 검사

debug-your-config.md +11 −5

Details

19특정 카테고리에 대한 세부 정보는 전용 명령으로 팔로우업합니다:19특정 카테고리에 대한 세부 정보는 전용 명령으로 팔로우업합니다:

20 20

21| 명령 | 표시 내용 |21| 명령 | 표시 내용 |

~~22| :--------------- | :------------------------------------------------------------------------------------------------------------------------------------ |~~22| :--------------- | :------------------------------------------------------------------------------------------------ |

23| `/memory` | 로드된 `CLAUDE.md` 및 규칙 파일, 자동 메모리 항목 |23| `/memory` | 로드된 `CLAUDE.md` 및 규칙 파일, 자동 메모리 항목 |

24| `/skills` | 프로젝트, 사용자 및 플러그인 소스의 사용 가능한 스킬 |24| `/skills` | 프로젝트, 사용자 및 플러그인 소스의 사용 가능한 스킬 |

25| `/hooks` | 활성 훅 구성 |25| `/hooks` | 활성 훅 구성 |

26| `/mcp` | 연결된 MCP 서버 및 해당 상태 |26| `/mcp` | 연결된 MCP 서버 및 해당 상태 |

27| `/permissions` | 현재 적용 중인 허용 및 거부 규칙 |27| `/permissions` | 현재 적용 중인 허용 및 거부 규칙 |

28| `/doctor` | 구성 진단: 잘못된 키, 스키마 오류, 설치 상태. {/* min-version: 2.1.196 */}v2.1.196부터 동일한 범위에서 정의된 중복 [서브에이전트](/ko/sub-agents) 이름도 보고하며 활성 상태인 것을 표시합니다 |28| `/doctor` | 설정 점검: 설치 상태, 잘못된 설정 파일, 사용하지 않는 확장 프로그램 및 동일한 디렉토리의 중복 [서브에이전트](/ko/sub-agents) 이름(제안된 수정 사항 포함) |

30| `/status` | 활성 설정 소스, 관리 설정이 적용 중인지 여부 포함 |30| `/status` | 활성 설정 소스, 관리 설정이 적용 중인지 여부 포함 |

31 31

45 45

46설정은 관리, 사용자, 프로젝트 및 로컬 범위에 걸쳐 병합됩니다. 관리 설정은 존재할 때 항상 우선합니다. 나머지 중에서는 더 가까운 범위가 로컬, 프로젝트, 사용자 순서로 더 넓은 범위를 재정의합니다. 일부 설정은 또한 명령줄 플래그 또는 [환경 변수](/ko/env-vars)로 설정할 수 있으며, 이는 또 다른 재정의 계층으로 작동합니다. 설정이 적용되지 않는 것처럼 보일 때, 설정한 값은 보통 다른 범위 또는 환경 변수에 의해 재정의되고 있습니다.46설정은 관리, 사용자, 프로젝트 및 로컬 범위에 걸쳐 병합됩니다. 관리 설정은 존재할 때 항상 우선합니다. 나머지 중에서는 더 가까운 범위가 로컬, 프로젝트, 사용자 순서로 더 넓은 범위를 재정의합니다. 일부 설정은 또한 명령줄 플래그 또는 [환경 변수](/ko/env-vars)로 설정할 수 있으며, 이는 또 다른 재정의 계층으로 작동합니다. 설정이 적용되지 않는 것처럼 보일 때, 설정한 값은 보통 다른 범위 또는 환경 변수에 의해 재정의되고 있습니다.

47 47

48`/doctor`를 실행하여 구성 파일을 검증하고 잘못된 키 또는 스키마 오류를 표시합니다. `/doctor`가 문제를 보고할 때, `f`를 눌러 진단 보고서를 Claude에게 보내고 Claude가 수정 사항을 안내하도록 합니다.48`/doctor`를 실행하여 구성 및 설치를 확인합니다. 이는 잘못된 설정 파일, 중복 설치 및 사용하지 않는 확장 프로그램을 포함하여 발견한 내용을 보고한 다음, 사용자가 확인한 후에만 적용하는 수정 사항을 제안합니다. v2.1.205 이전에는 `/doctor`가 읽기 전용 진단 화면을 열었고 `f`를 누르면 보고서를 Claude에게 보내 수정하도록 했습니다.

50터미널에서 `claude doctor`는 세션을 시작하지 않고 읽기 전용 설치 및 설정 진단을 출력합니다.

49 51

50`/status`를 실행하여 관리 설정이 적용 중인지 여부를 포함하여 활성 설정 소스를 확인합니다. 주어진 키에 대해 어느 범위가 우선하는지 이해하려면 [범위가 상호작용하는 방식](/ko/settings#how-scopes-interact)을 참조합니다.52`/status`를 실행하여 관리 설정이 적용 중인지 여부를 포함하여 활성 설정 소스를 확인합니다. 주어진 키에 대해 어느 범위가 우선하는지 이해하려면 [범위가 상호작용하는 방식](/ko/settings#how-scopes-interact)을 참조합니다.

51 53

67 69

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

69 71

70훅이 나타나지만 실행되지 않으면, 매처가 보통 원인입니다. `matcher` 필드는 여러 도구 이름을 일치시키기 위해 `|`를 사용하는 단일 문자열입니다(예: `"Edit|Write"`). {/* min-version: 2.1.191 */}Claude Code v2.1.191 이상에서는 `,`도 구분 기호로 작동하므로 `"Edit,Write"`는 동등합니다. 이전 버전에서는 쉼표가 정규식 평가로 넘어가고 매처가 일치하지 않으므로, v2.1.191이 아직 아니면 `|`를 사용하십시오. 잘못된 도구 이름은 같은 이유로 자동으로 실패합니다. 배열 값은 스키마 오류입니다: Claude Code는 설정 오류 알림을 표시하고, `/doctor`는 검증 실패를 보고하며, 훅 항목은 `/hooks`에 나타나지 않도록 삭제됩니다.72훅이 나타나지만 실행되지 않으면, 매처가 보통 원인입니다. 다음 실수를 확인하십시오:

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

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

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

71 77

72`settings.json`에 대한 편집은 짧은 파일 안정성 지연 후 실행 중인 세션에서 적용됩니다. 다시 시작할 필요가 없습니다. 저장 후 몇 초가 지났는데도 `/hooks`가 여전히 이전 정의를 표시하면 `/hooks`를 다시 실행하여 보기를 새로 고칩니다.78`settings.json`에 대한 편집은 짧은 파일 안정성 지연 후 실행 중인 세션에서 적용됩니다. 다시 시작할 필요가 없습니다. 저장 후 몇 초가 지났는데도 `/hooks`가 여전히 이전 정의를 표시하면 `/hooks`를 다시 실행하여 보기를 새로 고칩니다.

73 79

77 깨끗한 구성에 대해 테스트83 깨끗한 구성에 대해 테스트

78</h2>84</h2>

79 85

80{/* min-version: 2.1.169 */}[`claude --safe-mode`](/ko/cli-reference#cli-flags)로 시작합니다. 이는 `CLAUDE.md`, 스킬, 플러그인, 훅, MCP 서버, 사용자 정의 명령 및 에이전트를 포함한 모든 사용자 정의가 비활성화된 세션을 시작합니다. 인증, 모델 선택, 기본 제공 도구 및 권한은 정상적으로 작동합니다. 안전 모드에서 문제가 사라지면, 이러한 표면 중 하나가 원인입니다. 위의 대상 확인을 사용하여 어느 것인지 찾습니다. 조직에서 배포한 관리 설정은 여전히 부분적으로 적용되므로, 정책 구성 훅 및 상태 줄은 안전 모드에서도 실행됩니다.86{/* min-version: 2.1.169 */}[`claude --safe-mode`](/ko/cli-reference#cli-flags)로 시작합니다. 이는 `CLAUDE.md`, 스킬, 플러그인, 훅, MCP 서버, 사용자 정의 명령 및 에이전트를 포함한 모든 사용자 정의가 비활성화된 세션을 시작합니다. 인증, 모델 선택, 기본 제공 도구 및 권한은 정상적으로 작동합니다. 안전 모드에서 문제가 사라지면, 이러한 표면 중 하나가 원인입니다. 위의 대상 확인을 사용하여 어느 것인지 찾습니다. 안전 모드는 여전히 조직에서 배포한 관리 훅 및 설정 정책을 적용합니다. 관리 플러그인, 스킬, `CLAUDE.md` 및 MCP 서버는 꺼집니다.

81 87

82안전 모드에서 문제가 지속되거나 설정 자체가 의심스러우면, 일반적인 설정에서 아무것도 로드하지 않는 세션과 비교합니다. [`CLAUDE_CONFIG_DIR`](/ko/env-vars)을 빈 디렉토리로 지정하여 `~/.claude` 아래의 모든 항목을 우회하고, 프로젝트 구성도 건너뛰도록 `.claude` 폴더, `.mcp.json` 또는 `CLAUDE.md`가 없는 디렉토리에서 시작합니다.88안전 모드에서 문제가 지속되거나 설정 자체가 의심스러우면, 일반적인 설정에서 아무것도 로드하지 않는 세션과 비교합니다. [`CLAUDE_CONFIG_DIR`](/ko/env-vars)을 빈 디렉토리로 지정하여 `~/.claude` 아래의 모든 항목을 우회하고, 프로젝트 구성도 건너뛰도록 `.claude` 폴더, `.mcp.json` 또는 `CLAUDE.md`가 없는 디렉토리에서 시작합니다.

83 89

desktop.md +64 −30

Details

78 권한 모드 선택하기78 권한 모드 선택하기

79</h3>79</h3>

80 80

81권한 모드는 세션 중에 Claude가 가질 자율성을 제어합니다: 파일 편집, 명령 실행 또는 둘 다 전에 묻는지 여부입니다. 전송 버튼 옆의 모드 선택기를 사용하여 언제든지 모드를 전환할 수 있습니다. Claude가 수행하는 작업을 정확히 보기 위해 권한 요청으로 시작한 다음, 편하면 자동 수락 편집 또는 Plan mode로 이동합니다.81권한 모드는 세션 중에 Claude가 가질 자율성을 제어합니다: 파일 편집, 명령 실행 또는 둘 다 전에 묻는지 여부입니다. 전송 버튼 옆의 모드 선택기를 사용하여 언제든지 모드를 전환할 수 있습니다. Claude가 수행하는 작업을 정확히 보기 위해 Manual로 시작한 다음, 편하면 Accept edits 또는 Plan으로 이동합니다.

82 82

83| 모드 | 설정 키 | 동작 |83| 모드 | 설정 키 | 동작 |

84| ------------- | ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |84| ---------------------- | ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

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

88| **Auto** | `auto` | Claude는 요청과의 정렬을 확인하는 백그라운드 안전 검사를 통해 모든 작업을 실행합니다. 감시를 유지하면서 권한 프롬프트를 줄입니다. Settings → Claude Code에서 활성화합니다. [가용성 요구 사항](#auto-mode-availability)을 아래에서 참조하세요. |88| **Auto** | `auto` | Claude는 요청과의 정렬을 확인하는 백그라운드 안전 검사를 통해 모든 작업을 실행합니다. 감시를 유지하면서 권한 프롬프트를 줄입니다. Settings → Claude Code에서 활성화합니다. [가용성 요구 사항](#auto-mode-availability)을 아래에서 참조하세요. |

89| **권한 무시** | `bypassPermissions` | Claude는 명시적 [ask rules](/ko/permissions#manage-permissions)에 의해 강제된 권한 프롬프트를 제외하고 권한 프롬프트 없이 실행되며, CLI의 `--dangerously-skip-permissions`와 동일합니다. Settings → Claude Code의 "권한 무시 모드 허용"에서 활성화합니다. 샌드박스 컨테이너 또는 VM에서만 사용합니다. 엔터프라이즈 관리자는 이 옵션을 비활성화할 수 있습니다. |89| **Bypass permissions** | `bypassPermissions` | Claude는 명시적 [ask rules](/ko/permissions#manage-permissions)에 의해 강제된 권한 프롬프트를 제외하고 권한 프롬프트 없이 실행되며, Claude가 [외부 사이트에서 작동](#browse-external-sites)할 때 안전 분류기에 의해 강제된 권한 프롬프트를 제외하고, CLI의 `--dangerously-skip-permissions`와 동일합니다. Settings → Claude Code의 "Allow bypass permissions mode"에서 활성화합니다. 샌드박스 컨테이너 또는 VM에서만 사용합니다. 엔터프라이즈 관리자는 이 옵션을 비활성화할 수 있습니다. |

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

90 92

91`dontAsk` 권한 모드는 [CLI](/ko/permission-modes#allow-only-pre-approved-tools-with-dontask-mode)에서만 사용 가능합니다.93`dontAsk` 권한 모드는 [CLI](/ko/permission-modes#allow-only-pre-approved-tools-with-dontask-mode)에서만 사용 가능합니다.

92 94

93<span id="auto-mode-availability" />95<span id="auto-mode-availability" />

94 96

95Auto mode는 Anthropic API의 모든 사용자에게 제공되는 연구 미리보기이며 Claude Opus 4.6 이상 또는 Sonnet 4.6 이상이 필요합니다. Google Cloud Vertex AI로 라우팅하는 엔터프라이즈 배포에서는 [`CLAUDE_CODE_ENABLE_AUTO_MODE`를 설정](/ko/permission-modes#enable-auto-mode-on-bedrock-vertex-ai-or-foundry)할 때까지 auto mode가 꺼져 있으며, 거기서는 Claude Sonnet 5, Opus 4.7, Opus 4.8만 지원됩니다.97Auto mode는 Anthropic API의 모든 사용자에게 제공되는 연구 미리보기이며 Claude Opus 4.6 이상 또는 Sonnet 4.6 이상이 필요합니다. Google Cloud의 Agent Platform으로 라우팅하는 엔터프라이즈 배포에서는 [`CLAUDE_CODE_ENABLE_AUTO_MODE`를 설정](/ko/permission-modes#enable-auto-mode-on-bedrock-agent-platform-or-foundry)할 때까지 auto mode가 꺼져 있으며, 거기서는 Claude Sonnet 5, Opus 4.7, Opus 4.8만 지원됩니다.

96 98

97<Tip title="모범 사례">99<Tip title="모범 사례">

98 복잡한 작업을 Plan mode에서 시작하여 Claude가 변경하기 전에 접근 방식을 매핑하도록 합니다. 계획을 승인한 후 자동 수락 편집 또는 권한 요청으로 전환하여 실행합니다. 이 워크플로우에 대한 자세한 내용은 [먼저 탐색, 그 다음 계획, 그 다음 코드](/ko/best-practices#explore-first-then-plan-then-code)를 참조하세요.100 복잡한 작업을 Plan에서 시작하여 Claude가 변경하기 전에 접근 방식을 매핑하도록 합니다. 계획을 승인한 후 Accept edits 또는 Manual로 전환하여 실행합니다. 이 워크플로우에 대한 자세한 내용은 [먼저 탐색, 그 다음 계획, 그 다음 코드](/ko/best-practices#explore-first-then-plan-then-code)를 참조하세요.

99</Tip>101</Tip>

100 102

101클라우드 세션은 자동 수락 편집, Plan mode, Auto mode를 지원합니다. 자동 수락 편집은 `default` 모드에 해당합니다: 클라우드 세션은 파일 편집을 미리 승인하므로 선택기는 권한 요청 대신 자동 수락 편집을 표시합니다. 권한 무시는 클라우드 환경이 이미 샌드박스되어 있기 때문에 사용할 수 없습니다.103클라우드 세션은 Accept edits, Plan, Auto를 지원합니다. Accept edits는 `default` 모드에 해당합니다: 클라우드 세션은 파일 편집을 미리 승인하므로 선택기는 Manual 대신 Accept edits를 표시합니다. Bypass permissions는 클라우드 환경이 이미 샌드박스되어 있기 때문에 사용할 수 없습니다.

102 104

103엔터프라이즈 관리자는 사용 가능한 권한 모드를 제한할 수 있습니다. 자세한 내용은 [엔터프라이즈 구성](#enterprise-configuration)을 참조하세요.105엔터프라이즈 관리자는 사용 가능한 권한 모드를 제한할 수 있습니다. 자세한 내용은 [엔터프라이즈 구성](#enterprise-configuration)을 참조하세요.

104 106

106 앱 미리보기108 앱 미리보기

107</h3>109</h3>

108 110

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

110 112

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

112 114

113미리보기 패널에서 다음을 수행할 수 있습니다:115Browser 패널에서 다음을 수행할 수 있습니다:

114 116

115* 임베드된 브라우저에서 실행 중인 앱과 직접 상호작용합니다117* Browser 패널에서 실행 중인 앱과 직접 상호작용합니다

116* Claude가 자동으로 자신의 변경 사항을 확인하는 것을 봅니다: 스크린샷을 찍고, DOM을 검사하고, 요소를 클릭하고, 양식을 채우고, 발견한 문제를 수정합니다118* Claude가 자동으로 자신의 변경 사항을 확인하는 것을 봅니다: 스크린샷을 찍고, DOM을 검사하고, 요소를 클릭하고, 양식을 채우고, 발견한 문제를 수정합니다

117* 세션 도구 모음의 **Preview** 드롭다운에서 서버를 시작하거나 중지합니다119* 세션 도구 모음의 서버 드롭다운에서 서버를 시작하거나 중지합니다

118* 드롭다운에서 **Persist sessions**을 선택하여 서버 재시작 시 쿠키 및 로컬 스토리지를 유지하므로 개발 중에 다시 로그인할 필요가 없습니다120* 드롭다운에서 **Persist sessions**을 선택하여 서버 재시작 시 쿠키 및 로컬 스토리지를 유지하므로 개발 중에 다시 로그인할 필요가 없습니다

119* 서버 구성을 편집하거나 모든 서버를 한 번에 중지합니다121* 서버 구성을 편집하거나 모든 서버를 한 번에 중지합니다

120 122

121Claude는 프로젝트를 기반으로 초기 서버 구성을 만듭니다. 앱이 사용자 정의 개발 명령을 사용하는 경우 `.claude/launch.json`을 편집하여 설정과 일치시킵니다. 전체 참조는 [미리보기 서버 구성](#configure-preview-servers)을 참조하세요.123Claude는 프로젝트를 기반으로 초기 서버 구성을 만듭니다. 앱이 사용자 정의 개발 명령을 사용하는 경우 `.claude/launch.json`을 편집하여 설정과 일치시킵니다. 전체 참조는 [미리보기 서버 구성](#configure-preview-servers)을 참조하세요.

122 124

123저장된 세션 데이터를 지우려면 Settings → Claude Code에서 **Persist preview sessions**을 토글 해제합니다. 미리보기를 완전히 비활성화하려면 Settings → Claude Code에서 **Preview**를 토글 해제합니다.125저장된 세션 데이터를 지우거나 Browser를 완전히 비활성화하려면 Settings → Claude Code에서 토글을 사용합니다.

126

127<h3 id="browse-external-sites">

128 외부 사이트 탐색하기

129</h3>

130

131Browser 패널은 탭 브라우저이므로 실행 중인 앱 옆에 문서, 이슈 추적기 또는 다른 사이트를 열 수 있습니다. Browser를 열려면 macOS에서 **Cmd+Shift+B**를 누르거나 Windows에서 **Ctrl+Shift+B**를 누르거나 **Views** 메뉴에서 선택합니다. 채팅에서 외부 링크를 클릭하면 선택기가 Browser 패널을 사용하려면 **Open in app**을 또는 자신의 브라우저를 사용하려면 **Default browser**를 제공합니다; macOS에서 **Cmd**-클릭 또는 Windows에서 **Ctrl**-클릭하면 시스템 브라우저에서 직접 링크를 엽니다. Google OAuth와 같은 팝업 로그인 흐름을 포함하여 패널의 사이트에 로그인할 수 있습니다.

132

133Claude는 [앱을 확인](#preview-your-app)하는 데 사용하는 동일한 도구를 사용하여 외부 페이지를 읽고 상호작용할 수 있으며, 두 가지 추가 안전 검사가 있습니다:

134

135* 안전 분류기는 모든 권한 모드에서 클릭 및 입력과 같은 외부 페이지에 대한 Claude의 쓰기 작업을 검토합니다. 이는 [auto mode](#choose-a-permission-mode)가 사용하는 동일한 분류기이며, 작업에 플래그를 지정하면 모드에 관계없이 권한 프롬프트를 받습니다.

136* Auto 및 Bypass permissions 이외의 권한 모드에서는 Claude가 새 사이트로 이동하기 전에 도메인 허용 목록 확인도 적용됩니다.

137

138<h4 id="approve-claude’s-actions-on-a-site">

139 사이트에서 Claude의 작업 승인하기

140</h4>

141

142Claude가 처음으로 외부 사이트에서 작동할 때 권한 카드가 나타나고 Claude는 선택을 기다립니다: **Allow once**, **Always allow**, 또는 **Deny**. **Allow once**는 아무것도 저장하지 않고 작업을 승인합니다. **Always allow**는 장치에 해당 사이트에 대한 승인을 저장하며, Settings에서 취소할 수 있습니다. 하위 도메인을 포함하여 각 사이트는 자체 승인이 필요합니다. 로컬 개발 서버 및 프로젝트 파일은 승인이 필요하지 않으므로 [auto-verify](#auto-verify-changes)는 프롬프트 없이 계속 작동합니다.

143

144승인된 사이트에서도 Claude는 입력 없이 항목을 구매하거나, 계정을 만들거나, CAPTCHA를 우회하지 않습니다. Browser 패널에서 탐색하면 [Claude in Chrome extension](/ko/chrome)과 동일한 안전 모델을 사용합니다. Claude가 민감한 사이트 및 위험한 작업을 처리하는 방법은 [Using Claude in Chrome safely](https://support.claude.com/en/articles/12902428-using-claude-in-chrome-safely)를 참조하세요.

145

146<h4 id="choose-between-the-browser-and-the-chrome-extension">

147 Browser와 Chrome 확장 프로그램 중 선택하기

148</h4>

149

150Browser 패널은 개인 브라우저와 별도의 깨끗한 브라우저 프로필을 사용하며 저장된 로그인이나 기록이 없습니다. 앱을 빌드 및 테스트하고 신원이 필요하지 않은 사이트에 사용합니다. Claude가 로그인한 세션에서 사용자로 작동하기를 원할 때는 대신 [Claude in Chrome extension](/ko/chrome)을 사용하세요. 이는 브라우저의 로그인 상태를 공유합니다.

151

152<h4 id="restrict-external-browsing-for-your-organization">

153 조직의 외부 탐색 제한하기

154</h4>

155

156Browser는 Claude in Chrome 확장 프로그램과 동일한 [site allowlist and blocklist controls](https://support.claude.com/en/articles/13065128-claude-in-chrome-admin-controls)를 따릅니다. 조직이 이미 확장 프로그램에 대해 해당 목록을 구성한 경우 Browser는 자동으로 이를 준수합니다. 관리자는 [`browserExternalPageTools` managed setting](#managed-settings)으로 외부 페이지에서 Claude의 도구를 끌 수도 있습니다. 도구가 비활성화되면 사용자는 여전히 외부 사이트로 이동할 수 있습니다; Claude의 도구는 이를 읽거나 작동할 수 없습니다.

124 157

125<h3 id="review-changes-with-diff-view">158<h3 id="review-changes-with-diff-view">

126 diff 보기로 변경 사항 검토하기159 diff 보기로 변경 사항 검토하기

151 184

152pull request를 연 후 CI 상태 표시줄이 세션에 나타납니다. Claude Code는 GitHub CLI를 사용하여 확인 결과를 폴링하고 실패를 표시합니다.185pull request를 연 후 CI 상태 표시줄이 세션에 나타납니다. Claude Code는 GitHub CLI를 사용하여 확인 결과를 폴링하고 실패를 표시합니다.

153 186

154* **자동 수정**: 활성화되면 Claude는 실패 출력을 읽고 반복하여 실패한 CI 확인을 자동으로 수정하려고 시도합니다.187* **Auto-fix**: 활성화되면 Claude는 실패 출력을 읽고 반복하여 실패한 CI 확인을 자동으로 수정하려고 시도합니다.

155* **자동 병합**: 활성화되면 모든 확인이 통과하면 Claude가 PR을 병합합니다. 병합 방법은 squash입니다. 자동 병합은 이 작업을 수행하기 위해 [GitHub 저장소 설정에서 활성화](https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/configuring-pull-request-merges/managing-auto-merge-for-pull-requests-in-your-repository)되어야 합니다.188* **Auto-merge**: 활성화되면 모든 확인이 통과하면 Claude가 PR을 병합합니다. 병합 방법은 squash입니다. Auto-merge는 이 작업을 수행하기 위해 [GitHub 저장소 설정에서 활성화](https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/configuring-pull-request-merges/managing-auto-merge-for-pull-requests-in-your-repository)되어야 합니다.

156 189

157CI 상태 표시줄의 **Auto-fix** 및 **Auto-merge** 토글을 사용하여 옵션을 활성화합니다. Claude Code는 CI가 완료되면 데스크톱 알림도 보냅니다. 세션이 PR을 병합하거나 닫은 후 자동으로 아카이브되도록 하려면 Settings → Claude Code에서 [auto-archive](#work-in-parallel-with-sessions)를 켭니다.190CI 상태 표시줄의 **Auto-fix** 및 **Auto-merge** 토글을 사용하여 옵션을 활성화합니다. Claude Code는 CI가 완료되면 데스크톱 알림도 보냅니다. 세션이 PR을 병합하거나 닫은 후 자동으로 아카이브되도록 하려면 Settings → Claude Code에서 [auto-archive](#work-in-parallel-with-sessions)를 켭니다.

158 191

164 워크스페이스 정렬하기197 워크스페이스 정렬하기

165</h2>198</h2>

166 199

167Code 탭은 모든 레이아웃으로 정렬할 수 있는 패널을 중심으로 구축되어 있습니다: 채팅, diff, 미리보기, 터미널, 파일, 계획, 작업, 서브에이전트. 패널을 헤더로 드래그하여 위치를 변경하거나 패널 가장자리를 드래그하여 크기를 조정합니다. macOS에서 \*\*Cmd+\\\*\*를 누르거나 Windows에서 \*\*Ctrl+\\\*\*를 눌러 포커스된 패널을 닫습니다. 세션 도구 모음의 **Views** 메뉴에서 추가 패널을 엽니다.200Code 탭은 모든 레이아웃으로 정렬할 수 있는 패널을 중심으로 구축되어 있습니다: 채팅, diff, 브라우저, 터미널, 파일, 계획, 작업, 서브에이전트. 패널을 헤더로 드래그하여 위치를 변경하거나 패널 가장자리를 드래그하여 크기를 조정합니다. macOS에서 \*\*Cmd+\\\*\*를 누르거나 Windows에서 \*\*Ctrl+\\\*\*를 눌러 포커스된 패널을 닫습니다. 세션 도구 모음의 **Views** 메뉴에서 추가 패널을 엽니다.

168 201

169<Note>202<Note>

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

180 파일 열기 및 편집하기213 파일 열기 및 편집하기

181</h3>214</h3>

182 215

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

184 217

185파일 패널은 로컬 및 SSH 세션에서 사용 가능합니다. 원격 세션의 경우 Claude에게 변경을 요청합니다.218파일 패널은 로컬 및 SSH 세션에서 사용 가능합니다. 클라우드 세션의 경우 Claude에게 변경을 요청합니다.

186 219

187<h3 id="open-files-in-other-apps">220<h3 id="open-files-in-other-apps">

188 다른 앱에서 파일 열기221 다른 앱에서 파일 열기

225| `Esc` | Claude의 응답 중지 |258| `Esc` | Claude의 응답 중지 |

230| `Cmd` `\` | 포커스된 패널 닫기 |263| `Cmd` `\` | 포커스된 패널 닫기 |

231| `Cmd` `;` | 사이드 채팅 열기 |264| `Cmd` `;` | 사이드 채팅 열기 |

437 470

438Claude는 개발 서버 설정을 자동으로 감지하고 세션을 시작할 때 선택한 폴더의 루트에 있는 `.claude/launch.json`에 구성을 저장합니다. Preview는 이 폴더를 작업 디렉토리로 사용하므로 부모 폴더를 선택한 경우 자신의 개발 서버가 있는 하위 폴더는 자동으로 감지되지 않습니다. 하위 폴더의 서버로 작업하려면 해당 폴더에서 직접 세션을 시작하거나 구성을 수동으로 추가합니다.471Claude는 개발 서버 설정을 자동으로 감지하고 세션을 시작할 때 선택한 폴더의 루트에 있는 `.claude/launch.json`에 구성을 저장합니다. Preview는 이 폴더를 작업 디렉토리로 사용하므로 부모 폴더를 선택한 경우 자신의 개발 서버가 있는 하위 폴더는 자동으로 감지되지 않습니다. 하위 폴더의 서버로 작업하려면 해당 폴더에서 직접 세션을 시작하거나 구성을 수동으로 추가합니다.

439 472

440예를 들어 `npm run dev` 대신 `yarn dev`를 사용하거나 포트를 변경하도록 서버가 시작되는 방식을 사용자 정의하려면 파일을 수동으로 편집하거나 Preview 드롭다운에서 **Edit configuration**을 클릭하여 코드 편집기에서 엽니다. 파일은 주석이 있는 JSON을 지원합니다.473예를 들어 `npm run dev` 대신 `yarn dev`를 사용하거나 포트를 변경하도록 서버가 시작되는 방식을 사용자 정의하려면 파일을 수동으로 편집하거나 서버 드롭다운에서 **Edit configuration**을 클릭하여 코드 편집기에서 엽니다. 파일은 주석이 있는 JSON을 지원합니다.

441 474

442```json theme={null}475```json theme={null}

443{476{

461 494

462`autoVerify`가 활성화되면 Claude는 파일을 편집한 후 자동으로 코드 변경 사항을 확인합니다. 스크린샷을 찍고, 오류를 확인하고, 응답을 완료하기 전에 변경 사항이 작동하는지 확인합니다.495`autoVerify`가 활성화되면 Claude는 파일을 편집한 후 자동으로 코드 변경 사항을 확인합니다. 스크린샷을 찍고, 오류를 확인하고, 응답을 완료하기 전에 변경 사항이 작동하는지 확인합니다.

463 496

464자동 확인은 기본적으로 켜져 있습니다. `.claude/launch.json`에 `"autoVerify": false`를 추가하여 프로젝트별로 비활성화하거나 **Preview** 드롭다운 메뉴에서 토글합니다.497자동 확인은 기본적으로 켜져 있습니다. `.claude/launch.json`에 `"autoVerify": false`를 추가하여 프로젝트별로 비활성화하거나 서버 드롭다운 메뉴에서 토글합니다.

465 498

466```json theme={null}499```json theme={null}

467{500{

703| `disableAutoMode` | 사용자가 [Auto](/ko/permission-modes#eliminate-prompts-with-auto-mode) 모드를 활성화하지 못하도록 하려면 `"disable"`로 설정합니다. 모드 선택기에서 Auto를 제거합니다. `permissions` 아래에서도 허용됩니다. |736| `disableAutoMode` | 사용자가 [Auto](/ko/permission-modes#eliminate-prompts-with-auto-mode) 모드를 활성화하지 못하도록 하려면 `"disable"`로 설정합니다. 모드 선택기에서 Auto를 제거합니다. `permissions` 아래에서도 허용됩니다. |

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

705| `sshConfigs` | 환경 드롭다운에 나타나는 [SSH 연결](#pre-configure-ssh-connections-for-your-team)을 사전 구성합니다. 사용자는 관리 연결을 편집하거나 삭제할 수 없습니다. |739| `sshConfigs` | 환경 드롭다운에 나타나는 [SSH 연결](#pre-configure-ssh-connections-for-your-team)을 사전 구성합니다. 사용자는 관리 연결을 편집하거나 삭제할 수 없습니다. |

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

707| `managedMcpServers` | 타사 배포에서 모든 사용자에게 MCP 서버 구성을 푸시합니다. 각 항목은 `"http"`, `"sse"`, 또는 `"stdio"`의 전송, 연결 세부 정보, 그리고 선택적으로 해당 서버의 어떤 도구를 사용자가 호출할 수 있는지 제한하는 `toolPolicy` 맵을 지정합니다. 타사(3P) Desktop 배포에서만 사용 가능합니다. 타사 배포는 관리 콘솔 설정을 받지 않으므로 관리 설정 파일 또는 MDM을 통해 이 키를 전달합니다. |741| `managedMcpServers` | 타사 배포에서 모든 사용자에게 MCP 서버 구성을 푸시합니다. 각 항목은 `"http"`, `"sse"`, 또는 `"stdio"`의 전송, 연결 세부 정보, 그리고 선택적으로 해당 서버의 어떤 도구를 사용자가 호출할 수 있는지 제한하는 `toolPolicy` 맵을 지정합니다. 타사(3P) Desktop 배포에서만 사용 가능합니다. 타사 배포는 관리 콘솔 설정을 받지 않으므로 관리 설정 파일 또는 MDM을 통해 이 키를 전달합니다. |

754 788

755이미 Claude Code CLI를 사용하는 경우 Desktop은 그래픽 인터페이스를 사용하여 동일한 기본 엔진을 실행합니다. 동일한 머신에서 동일한 프로젝트에서도 동시에 둘 다 실행할 수 있습니다. 각각은 별도의 세션 기록을 유지하지만 CLAUDE.md 파일을 통해 구성 및 프로젝트 메모리를 공유합니다.789이미 Claude Code CLI를 사용하는 경우 Desktop은 그래픽 인터페이스를 사용하여 동일한 기본 엔진을 실행합니다. 동일한 머신에서 동일한 프로젝트에서도 동시에 둘 다 실행할 수 있습니다. 각각은 별도의 세션 기록을 유지하지만 CLAUDE.md 파일을 통해 구성 및 프로젝트 메모리를 공유합니다.

756 790

757CLI 세션을 Desktop으로 이동하려면 터미널에서 `/desktop`을 실행합니다. Claude는 세션을 저장하고 데스크톱 앱에서 열고 CLI를 종료합니다. 이 명령은 Claude 구독으로 로그인했을 때 macOS 및 Windows에서 사용 가능합니다. API 키 인증이나 Bedrock, Vertex 또는 Foundry에서는 사용할 수 없습니다.791CLI 세션을 Desktop으로 이동하려면 터미널에서 `/desktop`을 실행합니다. Claude는 세션을 저장하고 데스크톱 앱에서 열고 CLI를 종료합니다. 이 명령은 Claude 구독으로 로그인했을 때 macOS 및 Windows에서 사용 가능합니다. API 키 인증이나 Amazon Bedrock, Google Cloud의 Agent Platform 또는 Microsoft Foundry에서는 사용할 수 없습니다.

758 792

759<Tip>793<Tip>

760 Desktop vs CLI를 사용할 때: 병렬 세션을 한 창에서 관리하거나, 패널을 나란히 정렬하거나, 변경 사항을 시각적으로 검토하려고 할 때 Desktop을 사용합니다. 스크립팅, 자동화, 터미널 워크플로우를 선호할 때 CLI를 사용합니다.794 Desktop vs CLI를 사용할 때: 병렬 세션을 한 창에서 관리하거나, 패널을 나란히 정렬하거나, 변경 사항을 시각적으로 검토하려고 할 때 Desktop을 사용합니다. 스크립팅, 자동화, 터미널 워크플로우를 선호할 때 CLI를 사용합니다.

804이 표는 CLI와 Desktop 간의 핵심 기능을 비교합니다. CLI 플래그의 전체 목록은 [CLI 참조](/ko/cli-reference)를 참조하세요.838이 표는 CLI와 Desktop 간의 핵심 기능을 비교합니다. CLI 플래그의 전체 목록은 [CLI 참조](/ko/cli-reference)를 참조하세요.

805 839

806| 기능 | CLI | Desktop |840| 기능 | CLI | Desktop |

807| ----------------------------------------------------- | --------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |841| ----------------------------------------------------- | --------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

810| [Third-party providers](/ko/third-party-integrations) | Bedrock, Vertex AI, Foundry | Anthropic의 API (기본값). 엔터프라이즈 배포는 Vertex AI 및 게이트웨이 공급자를 구성할 수 있습니다. [엔터프라이즈 구성 가이드](https://support.claude.com/en/articles/12622667-enterprise-configuration)를 참조하세요. Code 탭을 Bedrock, Vertex AI, Foundry 또는 자체 호스팅 LLM 게이트웨이에서 실행하려면 [Cowork on 3P 연구 미리보기](https://claude.com/docs/cowork/3p/overview)를 참조하세요. |844| [Third-party providers](/ko/third-party-integrations) | Amazon Bedrock, Google Cloud의 Agent Platform, Microsoft Foundry | Anthropic의 API (기본값). 엔터프라이즈 배포는 Google Cloud의 Agent Platform 및 게이트웨이 공급자를 구성할 수 있습니다. [엔터프라이즈 구성 가이드](https://support.claude.com/en/articles/12622667-enterprise-configuration)를 참조하세요. Code 탭을 Amazon Bedrock, Google Cloud의 Agent Platform, Microsoft Foundry 또는 자체 호스팅 LLM 게이트웨이에서 실행하려면 [Claude Desktop on 3P](https://claude.com/docs/third-party/claude-desktop/overview)를 참조하세요. |

825 859

826다음 기능은 CLI 또는 VS Code 확장에서만 사용 가능하며, 명시된 경우를 제외하고는 그렇습니다:860다음 기능은 CLI 또는 VS Code 확장에서만 사용 가능하며, 명시된 경우를 제외하고는 그렇습니다:

827 861

828* **Third-party providers**: Desktop은 Anthropic의 API에 기본적으로 연결됩니다. 엔터프라이즈 배포는 [관리 설정](https://support.claude.com/en/articles/12622667-enterprise-configuration)을 통해 Vertex AI 및 게이트웨이 공급자를 구성할 수 있습니다. CLI에서 Bedrock 또는 Foundry의 경우 [빠른 시작](/ko/quickstart)을 참조하세요. 위 섹션의 예외로, [Cowork on 3P 연구 미리보기](https://claude.com/docs/cowork/3p/overview)는 Code 탭을 Bedrock, Vertex AI, Foundry 또는 자체 호스팅 LLM 게이트웨이에서 실행합니다.862* **Third-party providers**: Desktop은 Anthropic의 API에 기본적으로 연결됩니다. 엔터프라이즈 배포는 [관리 설정](https://support.claude.com/en/articles/12622667-enterprise-configuration)을 통해 Google Cloud의 Agent Platform 및 게이트웨이 공급자를 구성할 수 있습니다. CLI에서 Amazon Bedrock 또는 Microsoft Foundry의 경우 [빠른 시작](/ko/quickstart)을 참조하세요. 위 섹션의 예외로, [Claude Desktop on 3P](https://claude.com/docs/third-party/claude-desktop/overview)는 Code 탭을 Amazon Bedrock, Google Cloud의 Agent Platform, Microsoft Foundry 또는 자체 호스팅 LLM 게이트웨이에서 실행합니다.

829* **Linux (베타)**: 컴퓨터 사용은 아직 Linux 데스크톱 앱에서 사용할 수 없습니다. [Linux에서 Claude Desktop](/ko/desktop-linux)을 참조하세요.863* **Linux (베타)**: 컴퓨터 사용은 아직 Linux 데스크톱 앱에서 사용할 수 없습니다. [Linux에서 Claude Desktop](/ko/desktop-linux)을 참조하세요.

830* **Inline code suggestions**: Desktop은 자동 완성 스타일 제안을 제공하지 않습니다. 대화형 프롬프트 및 명시적 코드 변경을 통해 작동합니다.864* **Inline code suggestions**: Desktop은 자동 완성 스타일 제안을 제공하지 않습니다. 대화형 프롬프트 및 명시적 코드 변경을 통해 작동합니다.

831* **Agent teams**: 서로 메시지를 주고받는 병렬 Claude Code 세션은 [CLI](/ko/agent-teams)에서 사용 가능하며 Desktop에서는 사용할 수 없습니다. 한 세션 내에서 다중 에이전트 작업의 경우 [동적 워크플로우](/ko/workflows)를 사용합니다. 이는 Desktop에서 실행됩니다.865* **Agent teams**: 서로 메시지를 주고받는 병렬 Claude Code 세션은 [CLI](/ko/agent-teams)에서 사용 가능하며 Desktop에서는 사용할 수 없습니다. 한 세션 내에서 다중 에이전트 작업의 경우 [동적 워크플로우](/ko/workflows)를 사용합니다. 이는 Desktop에서 실행됩니다.

832* **Terminal-dialog commands**: `/permissions`, `/config`, `/doctor`와 같이 터미널에서 대화형 패널을 여는 기본 제공 명령은 Code 탭에서 사용할 수 없으며 `isn't available in this environment`로 응답합니다. [설정 파일](/ko/settings)을 직접 편집하여 권한 규칙 및 구성을 관리하거나 독립 실행형 CLI에서 명령을 실행합니다.866* **Terminal-dialog commands**: `/permissions` 및 `/config`와 같이 터미널에서 대화형 패널을 여는 기본 제공 명령은 Code 탭에서 사용할 수 없으며 `isn't available in this environment`로 응답합니다. `/config`는 `/config theme=dark`와 같이 `key=value`를 전달할 때 설정을 지정합니다. 선택기 형식만 사용할 수 없습니다. [설정 파일](/ko/settings)을 직접 편집하여 권한 규칙 및 구성을 관리하거나 독립 실행형 CLI에서 명령을 실행합니다.

833 867

834<h2 id="troubleshooting">868<h2 id="troubleshooting">

835 문제 해결869 문제 해결

desktop-linux.md +26 −2

Details

25 설치25 설치

26</h2>26</h2>

27 27

~~28시스템의 정기적인 패키지 업데이트를 통해 업데이트가 도착하도록 Anthropic의 apt 저장소에서 설치하세요.~~28터미널을 열고 각 단계의 명령을 실행하여 시스템의 정기적인 패키지 업데이트를 통해 업데이트가 도착하도록 Anthropic의 apt 저장소에서 설치합니다.

29 29

30<Steps>30<Steps>

31 <Step title="Anthropic의 apt 저장소 추가">31 <Step title="Anthropic의 apt 저장소 추가">

32 이 단계에서는 `curl`을 사용하여 서명 키를 다운로드합니다. 새로운 Debian 및 Ubuntu 설치에는 curl이 포함되지 않을 수 있습니다. 다운로드 명령이 `sudo: curl: command not found` 오류로 실패하면 먼저 curl을 설치하세요:

34 ```bash theme={null}

35 sudo apt install curl

36 ```

32 Anthropic의 서명 키를 다운로드합니다:38 Anthropic의 서명 키를 다운로드합니다:

33 39

34 ```bash theme={null}40 ```bash theme={null}

69 다운로드한 파일에서 설치75 다운로드한 파일에서 설치

70</h3>76</h3>

71 77

72apt 저장소를 사용할 수 없는 경우 [claude.com/download](https://claude.com/download)에서 아키텍처(x64 또는 arm64)에 맞는 `.deb` 패키지를 다운로드한 후 소프트웨어 설치 프로그램으로 열거나 다운로드 디렉터리에서 실행합니다:78apt 저장소를 사용할 수 없는 경우 [claude.com/download](https://claude.com/download)에서 아키텍처(x64 또는 arm64)에 맞는 `.deb` 패키지를 다운로드한 후 소프트웨어 설치 프로그램으로 열거나 다운로드 파일이 포함된 디렉터리에서 apt를 사용하여 설치합니다:

73 79

74```bash theme={null}80```bash theme={null}

75sudo apt install ./claude-desktop_*.deb81sudo apt install ./claude-desktop_*.deb

76```82```

77 83

84apt가 `E: Unsupported file ./claude-desktop_*.deb given on commandline` 오류를 보고하면 패턴이 현재 디렉터리의 `.deb` 파일과 일치하지 않은 것입니다. 다운로드가 완료되었는지 확인한 후 파일이 포함된 디렉터리에서 명령을 다시 실행하세요.

78이런 방식으로 설치된 `.deb`는 업데이트를 받지 않습니다. apt를 통해 업데이트를 받으려면 위에 표시된 대로 저장소를 추가하거나 패키지가 `/etc/apt/sources.list.d/claude-desktop.list`에 작성하는 자리 표시자 항목의 `deb` 줄을 주석 해제합니다.86이런 방식으로 설치된 `.deb`는 업데이트를 받지 않습니다. apt를 통해 업데이트를 받으려면 위에 표시된 대로 저장소를 추가하거나 패키지가 `/etc/apt/sources.list.d/claude-desktop.list`에 작성하는 자리 표시자 항목의 `deb` 줄을 주석 해제합니다.

79 87

80<h2 id="update">88<h2 id="update">

103sudo rm /etc/apt/sources.list.d/claude-desktop.list111sudo rm /etc/apt/sources.list.d/claude-desktop.list

104```112```

105 113

114<h2 id="troubleshoot">

115 문제 해결

116</h2>

117

118<h3 id="unable-to-locate-package-claude-desktop">

119 claude-desktop 패키지를 찾을 수 없음

120</h3>

121

122`sudo apt install claude-desktop`이 `E: Unable to locate package claude-desktop` 오류로 실패하면 apt가 추가한 저장소를 찾지 못한 것입니다. 다음을 확인하십시오:

123

124* 저장소 항목이 작성되었는지 확인하십시오. `cat /etc/apt/sources.list.d/claude-desktop.list`는 [Anthropic의 apt 저장소 추가](#install) 단계의 `deb` 줄을 표시해야 합니다. 파일이 비어 있거나 없으면 해당 단계를 다시 실행하십시오.

125* 아키텍처가 지원되는지 확인하십시오. `dpkg --print-architecture`는 `amd64` 또는 `arm64`를 출력해야 합니다. 저장소는 다른 아키텍처에 대한 패키지를 게시하지 않습니다.

126* `sudo apt update`를 다시 실행하고 `downloads.claude.ai`와 관련된 오류가 있는지 출력을 확인하십시오. 네트워크 또는 키 오류가 있으면 저장소는 추가되었지만 도달하거나 확인할 수 없다는 의미입니다.

127

128저장소가 제자리에 있고 도달 가능하며 패키지를 여전히 찾을 수 없으면 대신 [다운로드한 파일에서 설치](#install-from-a-downloaded-file)하십시오.

129

106<h2 id="what’s-not-in-the-linux-beta-yet">130<h2 id="what’s-not-in-the-linux-beta-yet">

107 Linux 베타에서 아직 제공되지 않는 기능131 Linux 베타에서 아직 제공되지 않는 기능

108</h2>132</h2>

desktop-quickstart.md +8 −4

Details

89 </Step>89 </Step>

90 90

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

92 기본적으로 Code 탭은 [Ask permissions 모드](/ko/desktop#choose-a-permission-mode)에서 시작되며, Claude는 변경 사항을 제안하고 적용하기 전에 승인을 기다립니다. 다음을 볼 수 있습니다:92 기본적으로 Code 탭은 [Manual mode](/ko/desktop#choose-a-permission-mode)에서 시작되며, Claude는 변경 사항을 제안하고 적용하기 전에 승인을 기다립니다. 다음을 볼 수 있습니다:

93 93

94 1. 각 파일에서 정확히 무엇이 변경될지 보여주는 [diff 보기](/ko/desktop#review-changes-with-diff-view)94 1. 각 파일에서 정확히 무엇이 변경될지 보여주는 [diff 보기](/ko/desktop#review-changes-with-diff-view)

95 2. 각 변경 사항을 승인하거나 거부하는 Accept/Reject 버튼95 2. 각 변경 사항을 승인하거나 거부하는 Accept/Reject 버튼

113 113

114**커밋하기 전에 변경 사항 검토.** Claude가 파일을 편집한 후 `+12 -1` 표시기가 나타납니다. 이를 클릭하여 [diff 보기](/ko/desktop#review-changes-with-diff-view)를 열고, 파일별로 수정 사항을 검토하고, 특정 줄에 대해 댓글을 달 수 있습니다. Claude는 댓글을 읽고 수정합니다. **Review code**를 클릭하여 Claude가 diff를 평가하고 인라인 제안을 남기도록 합니다.114**커밋하기 전에 변경 사항 검토.** Claude가 파일을 편집한 후 `+12 -1` 표시기가 나타납니다. 이를 클릭하여 [diff 보기](/ko/desktop#review-changes-with-diff-view)를 열고, 파일별로 수정 사항을 검토하고, 특정 줄에 대해 댓글을 달 수 있습니다. Claude는 댓글을 읽고 수정합니다. **Review code**를 클릭하여 Claude가 diff를 평가하고 인라인 제안을 남기도록 합니다.

115 115

116**제어 수준 조정.** [권한 모드](/ko/desktop#choose-a-permission-mode)는 균형을 제어합니다. Ask permissions(기본값)는 모든 편집 전에 승인이 필요합니다. Auto accept edits는 파일 편집을 자동으로 수락하여 더 빠른 반복을 가능하게 합니다. Plan mode는 Claude가 파일을 건드리지 않고 접근 방식을 계획하도록 하며, 이는 큰 리팩토링 전에 유용합니다.116**제어 수준 조정.** [권한 모드](/ko/desktop#choose-a-permission-mode)는 Claude가 승인을 요청하지 않고 할 수 있는 작업의 양을 설정합니다:

117

118* **Manual**: 기본값입니다. Claude는 파일을 편집하거나 명령을 실행하기 전에 승인을 요청합니다.

119* **Accept edits**: Claude는 파일 편집을 자동으로 수락하여 더 빠른 반복을 가능하게 합니다.

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

117 121

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

119 123

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

121 125

122**앱 미리보기.** **Preview** 드롭다운을 클릭하여 dev 서버를 데스크톱에서 직접 실행합니다. Claude는 실행 중인 앱을 보고, 엔드포인트를 테스트하고, 로그를 검사하고, 보는 것에 대해 반복할 수 있습니다. [앱 미리보기](/ko/desktop#preview-your-app)를 참조하세요.126**앱 미리보기.** Desktop에서 dev 서버를 실행하면 앱이 Browser 창에서 열리며, 이는 [외부 사이트를 열 수도](/ko/desktop#browse-external-sites) 있습니다. Claude는 실행 중인 앱을 보고, 엔드포인트를 테스트하고, 로그를 검사하고, 보는 것에 대해 반복할 수 있습니다. [앱 미리보기](/ko/desktop#preview-your-app)를 참조하세요.

123 127

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

125 129

devcontainer.md +2 −2

Details

75인증 프롬프트에서 보는 내용은 제공자에 따라 다릅니다:75인증 프롬프트에서 보는 내용은 제공자에 따라 다릅니다:

76 76

77* **Anthropic**: Claude 또는 Anthropic Console 계정으로 브라우저를 통해 로그인77* **Anthropic**: Claude 또는 Anthropic Console 계정으로 브라우저를 통해 로그인

78* **[Amazon Bedrock, Google Vertex AI 또는 Microsoft Foundry](/ko/third-party-integrations)**: Claude Code는 클라우드 제공자 자격 증명을 사용하며 브라우저 프롬프트가 없습니다.78* **[Amazon Bedrock, Google Cloud의 Agent Platform 또는 Microsoft Foundry](/ko/third-party-integrations)**: Claude Code는 클라우드 제공자 자격 증명을 사용하며 브라우저 프롬프트가 없습니다.

79 79

80클라우드 제공자의 경우 호스트에서 자격 증명 파일을 마운트하는 대신 `containerEnv`, Codespaces 시크릿 또는 클라우드의 워크로드 ID를 통해 자격 증명을 컨테이너에 전달합니다. Claude Code가 읽는 자격 증명 체인은 [Amazon Bedrock](/ko/amazon-bedrock), [Google Vertex AI](/ko/google-vertex-ai) 또는 [Microsoft Foundry](/ko/microsoft-foundry)를 참조하세요.80클라우드 제공자의 경우 호스트에서 자격 증명 파일을 마운트하는 대신 `containerEnv`, Codespaces 시크릿 또는 클라우드의 워크로드 ID를 통해 자격 증명을 컨테이너에 전달합니다. Claude Code가 읽는 자격 증명 체인은 [Amazon Bedrock](/ko/amazon-bedrock), [Google Cloud의 Agent Platform](/ko/google-vertex-ai) 또는 [Microsoft Foundry](/ko/microsoft-foundry)를 참조하세요.

81 81

82조직에 맞는 경로를 결정하려면 [API 제공자 선택](/ko/admin-setup#choose-your-api-provider)을 참조하세요.82조직에 맞는 경로를 결정하려면 [API 제공자 선택](/ko/admin-setup#choose-your-api-provider)을 참조하세요.

83 83

discover-plugins.md +11 −2

Details

332* 입력하여 플러그인 이름 또는 설명으로 필터링332* 입력하여 플러그인 이름 또는 설명으로 필터링

333* Enter를 눌러 플러그인의 세부 정보 보기를 열고 활성화, 비활성화 또는 제거333* Enter를 눌러 플러그인의 세부 정보 보기를 열고 활성화, 비활성화 또는 제거

334 334

335프로젝트의 `.claude/settings.json`이 활성화하는 플러그인을 제거하면 어느 범위를 의도했는지 묻습니다: 자신만 비활성화하면 `.claude/settings.local.json`에 재정의를 작성하고 프로젝트에 플러그인을 설치된 상태로 두거나, 모두를 위해 제거하면 공유 `.claude/settings.json`에서 제거합니다. Claude Code v2.1.203 이상이 필요합니다. v2.1.203 이전에는 대화 상자에서 로컬 비활성화만 제공했습니다.

336

335세부 정보 보기는 플러그인이 제공하는 구성 요소를 표시합니다: commands, skills, agents, hooks, MCP servers 및 LSP servers. 동일한 인벤토리는 `claude plugin details` 명령어로 명령줄에서도 사용할 수 있습니다.337세부 정보 보기는 플러그인이 제공하는 구성 요소를 표시합니다: commands, skills, agents, hooks, MCP servers 및 LSP servers. 동일한 인벤토리는 `claude plugin details` 명령어로 명령줄에서도 사용할 수 있습니다.

336 338

337Claude Code v2.1.187 이상에서는 Installed 탭에 **Not used recently** 그룹이 추가되어 마켓플레이스에서 직접 설치했지만 최소 2주 동안 그리고 최소 10개 세션에서 호출하지 않은 플러그인을 표시하며, 세부 정보 보기는 각 플러그인에 대한 **Last used** 줄을 표시합니다. 이를 사용하여 더 이상 사용하지 않지만 여전히 시작 및 컨텍스트 비용을 추가하는 플러그인을 찾은 다음 비활성화하거나 제거합니다.339**Installed** 탭은 또한 마켓플레이스에서 직접 설치했지만 최소 2주 동안 그리고 최소 10개 세션에 걸쳐 사용하지 않은 플러그인을 **Not used recently** 헤더 아래에 수집합니다. 세부 정보 보기는 각 플러그인에 대한 **Last used** 줄을 표시합니다. 이를 사용하여 더 이상 사용하지 않지만 여전히 시작 및 컨텍스트 비용을 추가하는 플러그인을 찾은 다음 비활성화하거나 제거합니다. Claude Code v2.1.187 이상이 필요합니다.

340

341두 가지 종류의 플러그인은 사용하지 않는 것으로 나열되지 않습니다:

342

343* 조직에서 관리하거나 `--plugin-dir`로 로드하는 플러그인

344* theme, output style, monitor 또는 workflow를 제공하는 플러그인. 이들은 추적할 호출 없이 값을 제공하기 때문입니다

345

346**Not used recently** 헤더와 **Last used** 줄은 조직이 [`strictKnownMarketplaces`](/ko/settings#strictknownmarketplaces)로 마켓플레이스를 제한할 때 모두 숨겨집니다.

338 347

339조직에서 관리하는 플러그인 또는 `--plugin-dir`로 로드하는 플러그인은 사용하지 않는 것으로 나열되지 않으며, LSP server, theme, output style, monitor 또는 workflow를 제공하는 플러그인도 추적할 호출 없이 값을 제공하므로 나열되지 않습니다. 조직이 [`strictKnownMarketplaces`](/ko/settings#strictknownmarketplaces)로 마켓플레이스를 제한할 때 그룹과 **Last used** 줄이 모두 숨겨집니다.348플러그인의 [language server](/ko/plugins#add-lsp-servers-to-your-plugin)는 진단을 제공하거나 코드 네비게이션 요청에 응답할 때 사용된 것으로 계산되므로, 서버가 세션에서 활성화된 LSP 플러그인은 사용하지 않는 것으로 나열되지 않습니다. v2.1.203 이전에는 language server 활동을 사용으로 계산할 수 없었으므로, LSP server를 제공하는 플러그인은 theme 및 output style 플러그인과 동일한 방식으로 그룹에서 제외되었습니다.

340 349

341종속성을 선언하는 플러그인을 설치하면 설치 출력에 함께 자동 설치된 종속성이 나열됩니다.350종속성을 선언하는 플러그인을 설치하면 설치 출력에 함께 자동 설치된 종속성이 나열됩니다.

342 351

env-vars.md +70 −68

Details

96</h2>96</h2>

97 97

98| 변수 | 목적 |98| 변수 | 목적 |

99| :------------------------------------------------------ | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |99| :------------------------------------------------------ | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

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

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

103| `ANTHROPIC_AWS_BASE_URL` | [Claude Platform on AWS](/ko/claude-platform-on-aws) 엔드포인트 URL을 재정의합니다. 사용자 정의 리전 또는 [LLM 게이트웨이](/ko/llm-gateway)를 통해 라우팅할 때 사용합니다. 기본값은 `https://aws-external-anthropic.{AWS_REGION}.api.aws`입니다. |103| `ANTHROPIC_AWS_BASE_URL` | [Claude Platform on AWS](/ko/claude-platform-on-aws) 엔드포인트 URL을 재정의합니다. 사용자 정의 리전 또는 [LLM 게이트웨이](/ko/llm-gateway)를 통해 라우팅할 때 사용합니다. 기본값은 `https://aws-external-anthropic.{AWS_REGION}.api.aws`입니다. |

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

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

106| `ANTHROPIC_BEDROCK_BASE_URL` | Bedrock 엔드포인트 URL을 재정의합니다. 사용자 정의 Bedrock 엔드포인트 또는 [LLM 게이트웨이](/ko/llm-gateway)를 통해 라우팅할 때 사용합니다. [Amazon Bedrock](/ko/amazon-bedrock) 참조 |106| `ANTHROPIC_BEDROCK_BASE_URL` | Amazon Bedrock 엔드포인트 URL을 재정의합니다. 사용자 정의 Amazon Bedrock 엔드포인트 또는 [LLM 게이트웨이](/ko/llm-gateway)를 통해 라우팅할 때 사용합니다. [Amazon Bedrock](/ko/amazon-bedrock) 참조 |

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

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

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

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

130| `ANTHROPIC_DEFAULT_SONNET_MODEL_SUPPORTED_CAPABILITIES` | [모델 구성](/ko/model-config#customize-pinned-model-display-and-capabilities) 참조 |130| `ANTHROPIC_DEFAULT_SONNET_MODEL_SUPPORTED_CAPABILITIES` | [모델 구성](/ko/model-config#customize-pinned-model-display-and-capabilities) 참조 |

132| `ANTHROPIC_FOUNDRY_BASE_URL` | Foundry 리소스의 전체 기본 URL(예: `https://my-resource.services.ai.azure.com/anthropic`). `ANTHROPIC_FOUNDRY_RESOURCE`의 대안([Microsoft Foundry](/ko/microsoft-foundry) 참조) |132| `ANTHROPIC_FOUNDRY_AUTH_TOKEN` | {/* min-version: 2.1.203 */}Microsoft Entra 액세스 토큰과 같은 Microsoft Foundry 인증용 Bearer 토큰입니다. Claude Code는 이를 `Authorization: Bearer` 헤더로 전송합니다. `ANTHROPIC_FOUNDRY_API_KEY` 및 Azure 기본 자격 증명 체인보다 우선합니다. [Microsoft Foundry](/ko/microsoft-foundry) 참조. Claude Code v2.1.203 이상이 필요합니다. |

133| `ANTHROPIC_FOUNDRY_RESOURCE` | Foundry 리소스 이름(예: `my-resource`). `ANTHROPIC_FOUNDRY_BASE_URL`이 설정되지 않은 경우 필수([Microsoft Foundry](/ko/microsoft-foundry) 참조) |133| `ANTHROPIC_FOUNDRY_BASE_URL` | Microsoft Foundry 리소스의 전체 기본 URL(예: `https://my-resource.services.ai.azure.com/anthropic`). `ANTHROPIC_FOUNDRY_RESOURCE`의 대안([Microsoft Foundry](/ko/microsoft-foundry) 참조) |

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

136| `ANTHROPIC_SMALL_FAST_MODEL_AWS_REGION` | Bedrock 또는 Bedrock Mantle 사용 시 Haiku 클래스 모델의 AWS 리전을 재정의합니다. Bedrock에서는 `ANTHROPIC_DEFAULT_HAIKU_MODEL` 또는 더 이상 사용되지 않는 `ANTHROPIC_SMALL_FAST_MODEL`도 설정되어 있을 때만 적용됩니다. Bedrock은 그렇지 않으면 백그라운드 작업에 기본 모델을 사용하기 때문입니다. |137| `ANTHROPIC_SMALL_FAST_MODEL_AWS_REGION` | Amazon Bedrock 또는 Amazon Bedrock Mantle 사용 시 Haiku 클래스 모델의 AWS 리전을 재정의합니다. Amazon Bedrock에서는 `ANTHROPIC_DEFAULT_HAIKU_MODEL` 또는 더 이상 사용되지 않는 `ANTHROPIC_SMALL_FAST_MODEL`도 설정되어 있을 때만 적용됩니다. Amazon Bedrock은 그렇지 않으면 백그라운드 작업에 기본 모델을 사용하기 때문입니다. |

137| `ANTHROPIC_VERTEX_BASE_URL` | Vertex AI 엔드포인트 URL을 재정의합니다. 사용자 정의 Vertex 엔드포인트 또는 [LLM 게이트웨이](/ko/llm-gateway)를 통해 라우팅할 때 사용합니다. [Google Vertex AI](/ko/google-vertex-ai) 참조 |138| `ANTHROPIC_VERTEX_BASE_URL` | Google Cloud's Agent Platform 엔드포인트 URL을 재정의합니다. 사용자 정의 Google Cloud's Agent Platform 엔드포인트 또는 [LLM 게이트웨이](/ko/llm-gateway)를 통해 라우팅할 때 사용합니다. [Google Cloud's Agent Platform](/ko/google-vertex-ai) 참조 |

138| `ANTHROPIC_VERTEX_PROJECT_ID` | Vertex AI 요청용 GCP 프로젝트 ID입니다. `GCLOUD_PROJECT`, `GOOGLE_CLOUD_PROJECT` 또는 `GOOGLE_APPLICATION_CREDENTIALS` 자격 증명 파일의 프로젝트로 재정의됩니다. [Google Vertex AI](/ko/google-vertex-ai) 참조 |139| `ANTHROPIC_VERTEX_PROJECT_ID` | Google Cloud's Agent Platform 요청용 GCP 프로젝트 ID입니다. `GCLOUD_PROJECT`, `GOOGLE_CLOUD_PROJECT` 또는 `GOOGLE_APPLICATION_CREDENTIALS` 자격 증명 파일의 프로젝트로 재정의됩니다. [Google Cloud's Agent Platform](/ko/google-vertex-ai) 참조 |

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

140| `API_FORCE_IDLE_TIMEOUT` | {/* min-version: 2.1.169 */}바이트가 도착하지 않을 때 스트리밍 모델 응답을 중단하는 5분 유휴 타임아웃을 재정의합니다. 느린 [게이트웨이](/ko/llm-gateway) 또는 로컬 모델이 청크 사이에 5분 이상 일시 중지할 때 `0`으로 설정하여 타임아웃을 비활성화합니다. 모든 공급자에서 타임아웃을 활성화하려면 `1`로 설정합니다. 설정하지 않으면 타임아웃은 직접 Anthropic API 및 [Claude Platform on AWS](/ko/claude-platform-on-aws) 연결에서 비활성화되며, Claude Code의 자체 바이트 수준 스트림 감시견이 실행되고, [Vertex AI](/ko/google-vertex-ai), [Foundry](/ko/microsoft-foundry), [Mantle](/ko/amazon-bedrock#use-the-mantle-endpoint), [Bedrock](/ko/amazon-bedrock), 게이트웨이 연결을 포함한 다른 모든 공급자에서 활성화되므로 정체된 스트림이 중단되지 않고 중단됩니다. v2.1.169부터 |141| `API_FORCE_IDLE_TIMEOUT` | {/* min-version: 2.1.169 */}바이트가 도착하지 않을 때 스트리밍 모델 응답을 중단하는 5분 유휴 타임아웃을 재정의합니다. 느린 [게이트웨이](/ko/llm-gateway) 또는 로컬 모델이 청크 사이에 5분 이상 일시 중지할 때 `0`으로 설정하여 타임아웃을 비활성화합니다. 모든 공급자에서 타임아웃을 활성화하려면 `1`로 설정합니다. 설정하지 않으면 타임아웃은 직접 Anthropic API 및 [Claude Platform on AWS](/ko/claude-platform-on-aws) 연결에서 비활성화되며, Claude Code의 자체 바이트 수준 스트림 감시견이 실행되고, [Google Cloud's Agent Platform](/ko/google-vertex-ai), [Microsoft Foundry](/ko/microsoft-foundry), [Mantle](/ko/amazon-bedrock#use-the-mantle-endpoint), [Amazon Bedrock](/ko/amazon-bedrock), 게이트웨이 연결을 포함한 다른 모든 공급자에서 활성화되므로 정체된 스트림이 중단되지 않고 중단됩니다. v2.1.169부터 |

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

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

144| `BASH_MAX_OUTPUT_LENGTH` | bash 출력이 전체 출력이 파일에 저장되고 Claude가 경로와 짧은 미리보기를 받기 전의 최대 문자 수입니다. [Bash 도구 동작](/ko/tools-reference#bash-tool-behavior) 참조 |145| `BASH_MAX_OUTPUT_LENGTH` | bash 출력이 전체 출력이 파일에 저장되고 Claude가 경로와 짧은 미리보기를 받기 전의 최대 문자 수입니다. [Bash 도구 동작](/ko/tools-reference#bash-tool-behavior) 참조 |

146| `CCR_FORCE_BUNDLE` | GitHub 액세스가 가능한 경우에도 [`claude --remote`](/ko/claude-code-on-the-web#send-local-repositories-without-github)가 로컬 리포지토리를 번들로 제공하고 업로드하도록 강제하려면 `1`로 설정합니다. |147| `CCR_FORCE_BUNDLE` | GitHub 액세스가 가능한 경우에도 [`claude --cloud`](/ko/claude-code-on-the-web#send-local-repositories-without-github)가 로컬 리포지토리를 번들로 제공하고 업로드하도록 강제하려면 `1`로 설정합니다. |

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

148| `CLAUDE_AFK_COUNTDOWN_MS` | {/* min-version: 2.1.198 */}자동 계속 전에 응답하지 않은 `AskUserQuestion` 대화 상자에 화면상 카운트다운이 나타나기 전의 밀리초입니다. 기본값 `20000`(20초). `CLAUDE_AFK_TIMEOUT_MS` 참조. Claude Code v2.1.198 이상이 필요합니다. |149| `CLAUDE_AFK_COUNTDOWN_MS` | {/* min-version: 2.1.198 */}자동 계속 전에 응답하지 않은 [`AskUserQuestion`](/ko/tools-reference) 대화 상자에 화면상 카운트다운이 나타나기 전의 밀리초입니다. 기본값 `20000`(20초), 자동 계속 타임아웃으로 제한됩니다. 자동 계속이 켜져 있지 않으면 효과가 없습니다. [`askUserQuestionTimeout`](/ko/settings#available-settings) 설정 및 `CLAUDE_AFK_TIMEOUT_MS` 참조. Claude Code v2.1.198 이상이 필요합니다. |

149| `CLAUDE_AFK_TIMEOUT_MS` | {/* min-version: 2.1.198 */}응답하지 않은 [`AskUserQuestion`](/ko/tools-reference) 대화 상자가 자동으로 계속되기 전의 유휴 시간(밀리초)입니다. 기본값 `60000`(60초). 자리를 비웠을 때 질문을 열어 두려면 `86400000`(24시간)과 같은 큰 값을 설정합니다. `0`으로 설정해도 타임아웃이 꺼지지 않습니다. 대화 상자가 즉시 닫힙니다. Claude Code v2.1.198 이상이 필요합니다. |150| `CLAUDE_AFK_TIMEOUT_MS` | {/* min-version: 2.1.198 */}응답하지 않은 [`AskUserQuestion`](/ko/tools-reference) 대화 상자가 자동으로 계속되기 전의 유휴 시간(밀리초)입니다. {/* min-version: 2.1.200 */}자동 계속은 기본적으로 꺼져 있습니다. [`askUserQuestionTimeout`](/ko/settings#available-settings) 설정으로 옵트인합니다. 이 변수는 데모 및 자동화된 테스트를 위한 재정의입니다: 설정하면 해당 설정보다 우선하고 설정이 설정되지 않았거나 `never`인 경우에도 자동 계속을 켭니다. `0`으로 설정해도 타임아웃이 꺼지지 않습니다. 대화 상자가 즉시 닫힙니다. v2.1.198 및 v2.1.199에서는 자동 계속이 기본적으로 켜져 있었고 `60000`(60초) 타임아웃이 있었습니다. Claude Code v2.1.198 이상이 필요합니다. |

150| `CLAUDE_AGENT_SDK_DISABLE_BUILTIN_AGENTS` | 모든 기본 제공 [subagent](/ko/sub-agents) 유형(예: Explore 및 Plan)을 비활성화하려면 `1`로 설정합니다. 비대화형 모드(`-p` 플래그)에만 적용됩니다. SDK 사용자가 백지 상태를 원할 때 유용합니다. |151| `CLAUDE_AGENT_SDK_DISABLE_BUILTIN_AGENTS` | 모든 기본 제공 [subagent](/ko/sub-agents) 유형(예: Explore 및 Plan)을 비활성화하려면 `1`로 설정합니다. 비대화형 모드(`-p` 플래그)에만 적용됩니다. SDK 사용자가 백지 상태를 원할 때 유용합니다. |

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

152| `CLAUDE_ASYNC_AGENT_STALL_TIMEOUT_MS` | 백그라운드 subagent의 정체 타임아웃(밀리초). 기본값 `600000`(10분). 타이머는 각 스트리밍 진행 이벤트에서 재설정됩니다. 윈도우 내에 진행이 도착하지 않으면 subagent가 중단되고 작업이 실패로 표시되며 부분 결과가 부모에게 표시됩니다. |153| `CLAUDE_ASYNC_AGENT_STALL_TIMEOUT_MS` | 백그라운드 subagent의 정체 타임아웃(밀리초). 기본값 `600000`(10분). 타이머는 각 스트리밍 진행 이벤트에서 재설정됩니다. 윈도우 내에 진행이 도착하지 않으면 subagent가 중단되고 작업이 실패로 표시되며 부분 결과가 부모에게 표시됩니다. |

165| `CLAUDE_CODE_AUTO_COMPACT_WINDOW` | 자동 압축 계산에 사용되는 컨텍스트 용량을 토큰 단위로 설정합니다. 기본값은 모델의 컨텍스트 윈도우입니다: 표준 모델의 경우 200K 또는 [확장 컨텍스트](/ko/model-config#extended-context) 모델의 경우 1M입니다. Sonnet 5는 자체 [기본 임계값](/ko/model-config#sonnet-5-context-window)을 가집니다. 1M 모델에서 `500000`과 같은 낮은 값을 사용하여 압축 목적상 윈도우를 500K로 취급합니다. 값은 모델의 실제 컨텍스트 윈도우로 제한됩니다. `CLAUDE_AUTOCOMPACT_PCT_OVERRIDE`는 이 값의 백분율로 적용됩니다. 이 변수를 설정하면 압축 임계값이 상태 줄의 `used_percentage`에서 분리되며, 이는 항상 모델의 전체 컨텍스트 윈도우를 사용합니다. |166| `CLAUDE_CODE_AUTO_COMPACT_WINDOW` | 자동 압축 계산에 사용되는 컨텍스트 용량을 토큰 단위로 설정합니다. 기본값은 모델의 컨텍스트 윈도우입니다: 표준 모델의 경우 200K 또는 [확장 컨텍스트](/ko/model-config#extended-context) 모델의 경우 1M입니다. Sonnet 5는 자체 [기본 임계값](/ko/model-config#sonnet-5-context-window)을 가집니다. 1M 모델에서 `500000`과 같은 낮은 값을 사용하여 압축 목적상 윈도우를 500K로 취급합니다. 값은 모델의 실제 컨텍스트 윈도우로 제한됩니다. `CLAUDE_AUTOCOMPACT_PCT_OVERRIDE`는 이 값의 백분율로 적용됩니다. 이 변수를 설정하면 압축 임계값이 상태 줄의 `used_percentage`에서 분리되며, 이는 항상 모델의 전체 컨텍스트 윈도우를 사용합니다. |

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

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

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

169| `CLAUDE_CODE_CHILD_SESSION` | {/* min-version: 2.1.172 */}Bash, PowerShell, Monitor 도구, [훅](/ko/hooks) 명령, [상태 줄](/ko/statusline) 명령을 통해 Claude Code가 생성하는 subprocess에서 `1`로 설정됩니다. stdio [MCP 서버](/ko/mcp) subprocess에는 설정되지 않으며, 이는 장기 실행되고 이를 생성한 세션보다 오래 지속됩니다. `CLAUDECODE`와 달리 이는 Claude Code의 자체 생성 경로에서만 설정되고 IDE 확장에서는 설정되지 않으므로 중첩 세션을 IDE 통합 터미널에서 시작된 최상위 `claude`와 안정적으로 구분합니다. 이 방식으로 시작된 중첩 대화형 `claude` TUI는 `--resume`, `--continue`, 위쪽 화살표 기록, `claude agents` 목록에서 자동으로 제외됩니다. 비대화형 `claude -p` 세션은 여전히 지속됩니다. `CLAUDE_CODE_FORCE_SESSION_PERSISTENCE=1`을 설정하여 이 제외를 재정의합니다. Claude Code v2.1.172 이상이 필요합니다. |170| `CLAUDE_CODE_CHILD_SESSION` | {/* min-version: 2.1.172 */}Bash, PowerShell, Monitor 도구, [훅](/ko/hooks) 명령, [상태 줄](/ko/statusline) 명령을 통해 Claude Code가 생성하는 subprocess에서 `1`로 설정됩니다. stdio [MCP 서버](/ko/mcp) subprocess에는 설정되지 않으며, 이는 장기 실행되고 이를 생성한 세션보다 오래 지속됩니다. `CLAUDECODE`와 달리 이는 Claude Code의 자체 생성 경로에서만 설정되고 IDE 확장에서는 설정되지 않으므로 중첩 세션을 IDE 통합 터미널에서 시작된 최상위 `claude`와 안정적으로 구분합니다. 이 방식으로 시작된 중첩 대화형 `claude` TUI는 `--resume`, `--continue`, 위쪽 화살표 기록, `claude agents` 목록에서 자동으로 제외됩니다. 비대화형 `claude -p` 세션은 여전히 지속됩니다. `CLAUDE_CODE_FORCE_SESSION_PERSISTENCE=1`을 설정하여 이 제외를 재정의합니다. Claude Code v2.1.172 이상이 필요합니다. |

184| `CLAUDE_CODE_DISABLE_BACKGROUND_TASKS` | Bash 및 subagent 도구의 `run_in_background` 매개변수, 자동 백그라운드 처리, Ctrl+B 단축키를 포함한 모든 백그라운드 작업 기능을 비활성화하려면 `1`로 설정합니다. |185| `CLAUDE_CODE_DISABLE_BACKGROUND_TASKS` | Bash 및 subagent 도구의 `run_in_background` 매개변수, 자동 백그라운드 처리, Ctrl+B 단축키를 포함한 모든 백그라운드 작업 기능을 비활성화하려면 `1`로 설정합니다. |

185| `CLAUDE_CODE_DISABLE_BG_EXIT_HANDOFF` | {/* min-version: 2.1.196 */}[백그라운드 세션](/ko/agent-view)의 실행 중인 백그라운드 셸 명령, 동적 워크플로우, {/* min-version: 2.1.198 */}v2.1.198부터 백그라운드 subagent를 [감독자](/ko/agent-view#the-supervisor-process)가 중지, 재시작 또는 해당 세션의 프로세스를 업데이트할 때 중지하려면 `1`로 설정합니다. 대신 다음 프로세스로 전달하는 대신입니다. 이 핸드오프에만 영향을 줍니다: `←` 또는 [`/background`](/ko/agent-view#from-inside-a-session)로 세션을 백그라운드 처리하면 여전히 진행 중인 작업을 수행하고, `CLAUDE_DISABLE_ADOPT`는 둘 다 끕니다. Claude Code v2.1.196 이상이 필요합니다. |186| `CLAUDE_CODE_DISABLE_BG_EXIT_HANDOFF` | {/* min-version: 2.1.196 */}[백그라운드 세션](/ko/agent-view)의 실행 중인 백그라운드 셸 명령, 동적 워크플로우, {/* min-version: 2.1.198 */}v2.1.198부터 백그라운드 subagent를 [감독자](/ko/agent-view#the-supervisor-process)가 중지, 재시작 또는 해당 세션의 프로세스를 업데이트할 때 중지하려면 `1`로 설정합니다. 대신 다음 프로세스로 전달하는 대신입니다. 이 핸드오프에만 영향을 줍니다: `←` 또는 [`/background`](/ko/agent-view#from-inside-a-session)로 세션을 백그라운드 처리하면 여전히 진행 중인 작업을 수행하고, `CLAUDE_DISABLE_ADOPT`는 둘 다 끕니다. Claude Code v2.1.196 이상이 필요합니다. |

186| `CLAUDE_CODE_DISABLE_BG_SHELL_PRESSURE_REAP` | {/* min-version: 2.1.193 */}운영 체제가 메모리 압력을 보고할 때 Claude Code가 [백그라운드 셸 명령](/ko/interactive-mode#background-bash-commands)을 종료하지 않도록 하려면 `1`로 설정합니다. 기본적으로 macOS 및 Linux에서 Claude Code는 세션이 30분 동안 유휴 상태이고 턴 또는 subagent가 실행 중이 아닐 때 메모리 압력 신호에서 주 세션에서 시작된 백그라운드 셸을 종료합니다. Windows에는 메모리 압력 신호가 없으므로 이 변수는 효과가 없습니다. Claude Code v2.1.193 이상이 필요합니다. |187| `CLAUDE_CODE_DISABLE_BG_SHELL_PRESSURE_REAP` | {/* min-version: 2.1.193 */}운영 체제가 메모리 압력을 보고할 때 Claude Code가 [백그라운드 셸 명령](/ko/interactive-mode#background-bash-commands)을 종료하지 않도록 하려면 `1`로 설정합니다. 기본적으로 macOS 및 Linux에서 Claude Code는 세션이 30분 동안 유휴 상태이고 턴 또는 subagent가 실행 중이 아닐 때 메모리 압력 신호에서 주 세션에서 시작된 백그라운드 셸을 종료합니다. Windows에는 메모리 압력 신호가 없으므로 이 변수는 효과가 없습니다. Claude Code v2.1.193 이상이 필요합니다. |

187| `CLAUDE_CODE_DISABLE_BUNDLED_SKILLS` | Claude Code와 함께 제공되는 [skill](/ko/skills) 및 워크플로우를 비활성화하려면 `1`로 설정합니다: 번들 skill 및 워크플로우는 완전히 제거되고, `/init`과 같은 기본 제공 슬래시 명령은 입력 가능하지만 모델에서 숨겨집니다. 플러그인, `.claude/skills/`, `.claude/commands/`의 skill은 영향을 받지 않습니다. [`disableBundledSkills`](/ko/settings#available-settings) 설정과 동일합니다. `0`은 이를 재정의하지 않습니다. |188| `CLAUDE_CODE_DISABLE_BUNDLED_SKILLS` | Claude Code와 함께 제공되는 [skill](/ko/skills) 및 워크플로우를 비활성화하려면 `1`로 설정합니다: 번들 skill 및 워크플로우는 완전히 제거되고, `/init`과 같은 기본 제공 슬래시 명령은 입력 가능하지만 모델에서 숨겨집니다. `/doctor`는 기본 제공 명령처럼 입력 가능하지만 `DISABLE_DOCTOR_COMMAND`로 숨길 수 있습니다. 플러그인, `.claude/skills/`, `.claude/commands/`의 skill은 영향을 받지 않습니다. [`disableBundledSkills`](/ko/settings#available-settings) 설정과 동일합니다. `0`은 이를 재정의하지 않습니다. |

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

190| `CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS` | Anthropic 특정 `anthropic-beta` 요청 헤더 및 베타 도구 스키마 필드(`defer_loading` 및 `eager_input_streaming` 등)를 API 요청에서 제거하려면 `1`로 설정합니다. 프록시 게이트웨이가 "Unexpected value(s) for the `anthropic-beta` header" 또는 "Extra inputs are not permitted"와 같은 오류로 요청을 거부할 때 사용합니다. 표준 필드(`name`, `description`, `input_schema`, `cache_control`)는 유지됩니다. |191| `CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS` | Anthropic 특정 `anthropic-beta` 요청 헤더 및 베타 도구 스키마 필드(`defer_loading` 및 `eager_input_streaming` 등)를 API 요청에서 제거하려면 `1`로 설정합니다. 프록시 게이트웨이가 "Unexpected value(s) for the `anthropic-beta` header" 또는 "Extra inputs are not permitted"와 같은 오류로 요청을 거부할 때 사용합니다. 표준 필드(`name`, `description`, `input_schema`, `cache_control`)는 유지됩니다. |

193| `CLAUDE_CODE_DISABLE_FEEDBACK_SURVEY` | "Claude가 어떻게 하고 있나요?" 세션 품질 설문조사를 비활성화하려면 `1`로 설정합니다. `DISABLE_TELEMETRY`, `DO_NOT_TRACK`, 또는 `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC`이 설정되면 설문조사도 비활성화됩니다. `CLAUDE_CODE_ENABLE_FEEDBACK_SURVEY_FOR_OTEL`이 다시 옵트인하지 않으면 설문조사 샘플 레이트를 설정하려면 [`feedbackSurveyRate`](/ko/settings#available-settings) 설정을 사용합니다. [세션 품질 설문조사](/ko/data-usage#session-quality-surveys) 참조 |194| `CLAUDE_CODE_DISABLE_FEEDBACK_SURVEY` | "Claude가 어떻게 하고 있나요?" 세션 품질 설문조사를 비활성화하려면 `1`로 설정합니다. `DISABLE_TELEMETRY`, `DO_NOT_TRACK`, 또는 `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC`이 설정되면 설문조사도 비활성화됩니다. `CLAUDE_CODE_ENABLE_FEEDBACK_SURVEY_FOR_OTEL`이 다시 옵트인하지 않으면 설문조사 샘플 레이트를 설정하려면 [`feedbackSurveyRate`](/ko/settings#available-settings) 설정을 사용합니다. [세션 품질 설문조사](/ko/data-usage#session-quality-surveys) 참조 |

194| `CLAUDE_CODE_DISABLE_FILE_CHECKPOINTING` | 파일 [체크포인팅](/ko/checkpointing)을 비활성화하려면 `1`로 설정합니다. `/rewind` 명령이 코드 변경 사항을 복원할 수 없습니다. |195| `CLAUDE_CODE_DISABLE_FILE_CHECKPOINTING` | 파일 [체크포인팅](/ko/checkpointing)을 비활성화하려면 `1`로 설정합니다. `/rewind` 명령이 코드 변경 사항을 복원할 수 없습니다. |

195| `CLAUDE_CODE_DISABLE_GIT_INSTRUCTIONS` | Claude의 시스템 프롬프트에서 기본 제공 커밋 및 PR 워크플로우 지침과 git 상태 스냅샷을 제거하려면 `1`로 설정합니다. 자신의 git 워크플로우 skill을 사용할 때 유용합니다. 설정하면 [`includeGitInstructions`](/ko/settings#available-settings) 설정보다 우선합니다. |196| `CLAUDE_CODE_DISABLE_GIT_INSTRUCTIONS` | Claude의 시스템 프롬프트에서 기본 제공 커밋 및 PR 워크플로우 지침과 git 상태 스냅샷을 제거하려면 `1`로 설정합니다. 자신의 git 워크플로우 skill을 사용할 때 유용합니다. 설정하면 [`includeGitInstructions`](/ko/settings#available-settings) 설정보다 우선합니다. |

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

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

198| `CLAUDE_CODE_DISABLE_MOUSE_CLICKS` | {/* min-version: 2.1.195 */}[전체 화면 렌더링](/ko/fullscreen)에서 클릭, 드래그, 호버 처리를 비활성화하려면 `1`로 설정합니다. 마우스 휠 스크롤은 유지합니다. 휠 스크롤이 Claude Code 내에서 작동하기를 원하지만 클릭이 커서를 배치하거나, 도구 출력을 확장하거나, 링크를 열지 않기를 원할 때 사용합니다. 둘 다 설정하면 `CLAUDE_CODE_DISABLE_MOUSE`가 우선합니다. Claude Code v2.1.195 이상이 필요합니다. |199| `CLAUDE_CODE_DISABLE_MOUSE_CLICKS` | {/* min-version: 2.1.195 */}[전체 화면 렌더링](/ko/fullscreen)에서 클릭, 드래그, 호버 처리를 비활성화하려면 `1`로 설정합니다. 마우스 휠 스크롤은 유지합니다. 휠 스크롤이 Claude Code 내에서 작동하기를 원하지만 클릭이 커서를 배치하거나, 도구 출력을 확장하거나, 링크를 열지 않기를 원할 때 사용합니다. 둘 다 설정하면 `CLAUDE_CODE_DISABLE_MOUSE`가 우선합니다. Claude Code v2.1.195 이상이 필요합니다. |

199| `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC` | `DISABLE_AUTOUPDATER`, `DISABLE_FEEDBACK_COMMAND`, `DISABLE_ERROR_REPORTING`, `DISABLE_TELEMETRY` 설정과 동일합니다. |200| `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC` | `DISABLE_AUTOUPDATER`, `DISABLE_FEEDBACK_COMMAND`, `DISABLE_ERROR_REPORTING`, `DISABLE_TELEMETRY` 설정과 동일합니다. |

206| `CLAUDE_CODE_DISABLE_VIRTUAL_SCROLL` | [전체 화면 렌더링](/ko/fullscreen)에서 가상 스크롤을 비활성화하려면 `1`로 설정합니다. 전체 화면 모드에서 스크롤이 메시지가 나타나야 할 위치에 빈 영역을 표시하면 이를 사용합니다. |207| `CLAUDE_CODE_DISABLE_VIRTUAL_SCROLL` | [전체 화면 렌더링](/ko/fullscreen)에서 가상 스크롤을 비활성화하려면 `1`로 설정합니다. 전체 화면 모드에서 스크롤이 메시지가 나타나야 할 위치에 빈 영역을 표시하면 이를 사용합니다. |

207| `CLAUDE_CODE_DISABLE_WORKFLOWS` | [워크플로우](/ko/workflows#turn-workflows-off)를 비활성화하려면 `1`로 설정합니다. [`disableWorkflows`](/ko/settings#available-settings) 설정과 동일합니다. |208| `CLAUDE_CODE_DISABLE_WORKFLOWS` | [워크플로우](/ko/workflows#turn-workflows-off)를 비활성화하려면 `1`로 설정합니다. [`disableWorkflows`](/ko/settings#available-settings) 설정과 동일합니다. |

208| `CLAUDE_CODE_EFFORT_LEVEL` | 지원되는 모델의 노력 수준을 설정합니다. 값: `low`, `medium`, `high`, `xhigh`, `max`, 또는 `auto`(모델 기본값 사용). 사용 가능한 수준은 모델에 따라 다릅니다. `/effort` 및 `effortLevel` 설정보다 우선합니다. [노력 수준 조정](/ko/model-config#adjust-effort-level) 참조 |209| `CLAUDE_CODE_EFFORT_LEVEL` | 지원되는 모델의 노력 수준을 설정합니다. 값: `low`, `medium`, `high`, `xhigh`, `max`, 또는 `auto`(모델 기본값 사용). 사용 가능한 수준은 모델에 따라 다릅니다. `/effort` 및 `effortLevel` 설정보다 우선합니다. [노력 수준 조정](/ko/model-config#adjust-effort-level) 참조 |

209| `CLAUDE_CODE_ENABLE_AUTO_MODE` | {/* min-version: 2.1.158 */}Amazon Bedrock, Google Cloud Vertex AI, Microsoft Foundry에서 [자동 모드](/ko/permission-modes#eliminate-prompts-with-auto-mode)를 사용 가능하게 하려면 `1`로 설정합니다. Claude Code v2.1.158 이상이 필요합니다. Anthropic API에는 효과가 없으며, 자동 모드는 기본적으로 사용 가능합니다. [Bedrock, Vertex AI 또는 Foundry에서 자동 모드 활성화](/ko/permission-modes#enable-auto-mode-on-bedrock-vertex-ai-or-foundry) 참조 |210| `CLAUDE_CODE_ENABLE_APPEND_SUBAGENT_PROMPT` | {/* min-version: 2.1.205 */}모든 [subagent](/ko/sub-agents)의 시스템 프롬프트 끝에 추가 텍스트를 추가하는 것을 활성화하려면 `1`로 설정합니다. [`--append-subagent-system-prompt`](/ko/cli-reference#cli-flags) 플래그는 추가된 텍스트를 제공하고 이 변수를 자동으로 설정하므로 직접 설정할 필요가 없습니다. Claude Code v2.1.205 이상이 필요합니다. |

211| `CLAUDE_CODE_ENABLE_AUTO_MODE` | {/* min-version: 2.1.158 */}Amazon Bedrock, Google Cloud's Agent Platform, Microsoft Foundry에서 [자동 모드](/ko/permission-modes#eliminate-prompts-with-auto-mode)를 사용 가능하게 하려면 `1`로 설정합니다. Claude Code v2.1.158 이상이 필요합니다. Anthropic API에는 효과가 없으며, 자동 모드는 기본적으로 사용 가능합니다. [Amazon Bedrock, Google Cloud's Agent Platform 또는 Microsoft Foundry에서 자동 모드 활성화](/ko/permission-modes#enable-auto-mode-on-bedrock-agent-platform-or-foundry) 참조 |

210| `CLAUDE_CODE_ENABLE_AWAY_SUMMARY` | [세션 요약](/ko/interactive-mode#session-recap) 가용성을 재정의합니다. 재개를 강제로 끄려면 `0`으로 설정합니다. [`awaySummaryEnabled`](/ko/settings#available-settings)가 `false`일 때 재개를 강제로 켜려면 `1`로 설정합니다. 설정 및 `/config` 토글보다 우선합니다. |212| `CLAUDE_CODE_ENABLE_AWAY_SUMMARY` | [세션 요약](/ko/interactive-mode#session-recap) 가용성을 재정의합니다. 재개를 강제로 끄려면 `0`으로 설정합니다. [`awaySummaryEnabled`](/ko/settings#available-settings)가 `false`일 때 재개를 강제로 켜려면 `1`로 설정합니다. 설정 및 `/config` 토글보다 우선합니다. |

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

212| `CLAUDE_CODE_ENABLE_FEEDBACK_SURVEY_FOR_OTEL` | Anthropic 바운드 비필수 트래픽이 차단될 때 "Claude가 어떻게 하고 있나요?" 세션 품질 설문조사를 자신의 [OpenTelemetry 수집기](/ko/monitoring-usage)로 라우팅하려면 `1`로 설정합니다. 설문조사 등급은 구성된 수집기에 OTEL 이벤트로만 내보내집니다. 이 모드에서는 설문조사 데이터가 Anthropic으로 전송되지 않습니다. `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC`, `DISABLE_TELEMETRY`, 또는 `DO_NOT_TRACK`이 설정되었을 때 적용되며, 그렇지 않으면 효과가 없습니다. `CLAUDE_CODE_DISABLE_FEEDBACK_SURVEY` 및 조직 제품 피드백 정책이 우선합니다. |214| `CLAUDE_CODE_ENABLE_FEEDBACK_SURVEY_FOR_OTEL` | Anthropic 바운드 비필수 트래픽이 차단될 때 "Claude가 어떻게 하고 있나요?" 세션 품질 설문조사를 자신의 [OpenTelemetry 수집기](/ko/monitoring-usage)로 라우팅하려면 `1`로 설정합니다. 설문조사 등급은 구성된 수집기에 OTEL 이벤트로만 내보내집니다. 이 모드에서는 설문조사 데이터가 Anthropic으로 전송되지 않습니다. `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC`, `DISABLE_TELEMETRY`, 또는 `DO_NOT_TRACK`이 설정되었을 때 적용되며, 그렇지 않으면 효과가 없습니다. `CLAUDE_CODE_DISABLE_FEEDBACK_SURVEY` 및 조직 제품 피드백 정책이 우선합니다. |

213| `CLAUDE_CODE_ENABLE_FINE_GRAINED_TOOL_STREAMING` | 도구 호출 입력이 Claude가 생성할 때 API에서 스트리밍되는지 여부를 제어합니다. 이 없으면 파일 쓰기와 같은 큰 도구 입력이 Claude가 생성을 완료한 후에만 도착하므로 중단된 것처럼 보일 수 있습니다. Anthropic API에 대해 기본적으로 활성화됩니다. Bedrock 및 Vertex에서는 배포된 컨테이너가 지원하는 모델별로 활성화됩니다. 옵트아웃하려면 `0`으로 설정합니다. `ANTHROPIC_BASE_URL`, `ANTHROPIC_VERTEX_BASE_URL` 또는 `ANTHROPIC_BEDROCK_BASE_URL`을 통해 프록시로 라우팅할 때 강제로 활성화하려면 `1`로 설정합니다. Foundry 및 [게이트웨이](/ko/llm-gateway) 연결에는 기본적으로 꺼져 있습니다. |215| `CLAUDE_CODE_ENABLE_FINE_GRAINED_TOOL_STREAMING` | 도구 호출 입력이 Claude가 생성할 때 API에서 스트리밍되는지 여부를 제어합니다. 이 없으면 파일 쓰기와 같은 큰 도구 입력이 Claude가 생성을 완료한 후에만 도착하므로 중단된 것처럼 보일 수 있습니다. Anthropic API에 대해 기본적으로 활성화됩니다. Amazon Bedrock 및 Google Cloud's Agent Platform에서는 배포된 컨테이너가 지원하는 모델별로 활성화됩니다. 옵트아웃하려면 `0`으로 설정합니다. `ANTHROPIC_BASE_URL`, `ANTHROPIC_VERTEX_BASE_URL` 또는 `ANTHROPIC_BEDROCK_BASE_URL`을 통해 프록시로 라우팅할 때 강제로 활성화하려면 `1`로 설정합니다. Microsoft Foundry 및 [게이트웨이](/ko/llm-gateway) 연결에는 기본적으로 꺼져 있습니다. |

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

215| `CLAUDE_CODE_ENABLE_OPUS_4_7_FAST_MODE` | {/* max-version: 2.1.141 */}v2.1.142에서 제거됨. [빠른 모드](/ko/fast-mode) 기본값이 Opus 4.6에서 Opus 4.7로 이동했을 때 |217| `CLAUDE_CODE_ENABLE_OPUS_4_7_FAST_MODE` | {/* max-version: 2.1.141 */}v2.1.142에서 제거됨. [빠른 모드](/ko/fast-mode) 기본값이 Opus 4.6에서 Opus 4.7로 이동했을 때 |

216| `CLAUDE_CODE_ENABLE_PROMPT_SUGGESTION` | 프롬프트 제안을 비활성화하려면 `false`로 설정합니다(`/config`의 "프롬프트 제안" 토글). 이는 Claude가 응답한 후 프롬프트 입력에 나타나는 회색으로 표시된 예측입니다. [프롬프트 제안](/ko/interactive-mode#prompt-suggestions) 참조 |218| `CLAUDE_CODE_ENABLE_PROMPT_SUGGESTION` | 프롬프트 제안을 비활성화하려면 `false`로 설정합니다(`/config`의 "프롬프트 제안" 토글). 이는 Claude가 응답한 후 프롬프트 입력에 나타나는 회색으로 표시된 예측입니다. [프롬프트 제안](/ko/interactive-mode#prompt-suggestions) 참조 |

223| `CLAUDE_CODE_FORCE_SESSION_PERSISTENCE` | {/* min-version: 2.1.172 */}이 `claude`가 다른 Claude Code 세션 내부에서 시작되었을 때에도 트랜스크립트 지속성, 프롬프트 기록, `claude agents` 등록을 강제하려면 `1`로 설정합니다. 예를 들어 Claude Code의 Bash 도구에서 처음 시작된 tmux 서버에서 상속된 `CLAUDE_CODE_CHILD_SESSION` 값이 진정한 최상위 세션을 중첩으로 잘못 분류할 때 사용합니다. {/* min-version: 2.1.178 */}v2.1.178부터 Claude Code는 tmux 경우를 자동으로 감지하고 상속된 마커를 무시하므로 tmux는 더 이상 이 변수가 필요하지 않습니다. v2.1.169 이상에서도 인정됩니다. v2.1.170 및 v2.1.171에서는 효과가 없으며, 이를 재정의한 중첩 세션 감지가 제거되었습니다. |225| `CLAUDE_CODE_FORCE_SESSION_PERSISTENCE` | {{/* min-version: 2.1.172 */}}이 `claude`가 다른 Claude Code 세션 내부에서 시작되었을 때에도 트랜스크립트 지속성, 프롬프트 기록, `claude agents` 등록을 강제하려면 `1`로 설정합니다. 예를 들어 Claude Code의 Bash 도구에서 처음 시작된 tmux 서버에서 상속된 `CLAUDE_CODE_CHILD_SESSION` 값이 진정한 최상위 세션을 중첩으로 잘못 분류할 때 사용합니다. {{/* min-version: 2.1.178 */}}v2.1.178부터 Claude Code는 tmux 경우를 자동으로 감지하고 상속된 마커를 무시하므로 tmux는 더 이상 이 변수가 필요하지 않습니다. v2.1.169 이상에서도 인정됩니다. v2.1.170 및 v2.1.171에서는 효과가 없으며, 이를 재정의한 중첩 세션 감지가 제거되었습니다. |

224| `CLAUDE_CODE_FORCE_STRIKETHROUGH` | {/* min-version: 2.1.186 */}터미널이 지원하지만 자동 감지되지 않을 때 Claude의 응답에서 `~~text~~`에 대한 취소선 렌더링을 강제하려면 `1`로 설정합니다. SSH를 통해 `TERM_PROGRAM`이 전달되지 않는 경우와 같습니다. 이 없으면 감지되지 않은 터미널은 취소선으로 렌더링하는 대신 리터럴 `~~` 마커를 표시합니다. Claude Code v2.1.186 이상이 필요합니다. |226| `CLAUDE_CODE_FORCE_STRIKETHROUGH` | {{/* min-version: 2.1.186 */}}터미널이 지원하지만 자동 감지되지 않을 때 Claude의 응답에서 `~~text~~`에 대한 취소선 렌더링을 강제하려면 `1`로 설정합니다. SSH를 통해 `TERM_PROGRAM`이 전달되지 않는 경우와 같습니다. 이 없으면 감지되지 않은 터미널은 취소선으로 렌더링하는 대신 리터럴 `~~` 마커를 표시합니다. Claude Code v2.1.186 이상이 필요합니다. |

225| `CLAUDE_CODE_FORCE_SYNC_OUTPUT` | 터미널이 지원하지만 자동 감지되지 않을 때 DEC 개인 모드 2026 [동기화된 출력](https://gist.github.com/christianparpart/d8a62cc1ab659194337d73e399004036)을 강제로 활성화하려면 `1`로 설정합니다. Emacs `eat`과 같은 BSU/ESU를 구현하지만 기능 프로브에 응답하지 않는 에뮬레이터에 유용합니다. tmux에서는 효과가 없습니다. |227| `CLAUDE_CODE_FORCE_SYNC_OUTPUT` | 터미널이 지원하지만 자동 감지되지 않을 때 DEC 개인 모드 2026 [동기화된 출력](https://gist.github.com/christianparpart/d8a62cc1ab659194337d73e399004036)을 강제로 활성화하려면 `1`로 설정합니다. Emacs `eat`과 같은 BSU/ESU를 구현하지만 기능 프로브에 응답하지 않는 에뮬레이터에 유용합니다. tmux에서는 효과가 없습니다. |

226| `CLAUDE_CODE_FORK_SUBAGENT` | [포크된 subagent](/ko/sub-agents#fork-the-current-conversation)를 모델의 기본값으로 만들려면 `1`로 설정하거나, 비활성화하려면 `0`으로 설정합니다. 서버 측 롤아웃을 재정의합니다. 활성화되면 Claude는 일반 목적 subagent를 사용하는 대신 포크를 생성합니다. 포크는 새로 시작하는 대신 전체 대화 컨텍스트를 상속하는 subagent이며, 모든 subagent 생성은 백그라운드에서 실행됩니다. 명시적 [`/fork`](/ko/commands) 명령은 이 변수 없이도 작동합니다. 대화형 모드와 SDK 또는 `claude -p`를 통해 작동합니다. |228| `CLAUDE_CODE_FORK_SUBAGENT` | [포크된 subagent](/ko/sub-agents#fork-the-current-conversation)를 모델의 기본값으로 만들려면 `1`로 설정하거나, 비활성화하려면 `0`으로 설정합니다. 서버 측 롤아웃을 재정의합니다. 활성화되면 Claude는 일반 목적 subagent를 사용하는 대신 포크를 생성합니다. 포크는 새로 시작하는 대신 전체 대화 컨텍스트를 상속하는 subagent이며, 모든 subagent 생성은 백그라운드에서 실행됩니다. 명시적 [`/fork`](/ko/commands) 명령은 이 변수 없이도 작동합니다. 대화형 모드와 SDK 또는 `claude -p`를 통해 작동합니다. |

227| `CLAUDE_CODE_GIT_BASH_PATH` | Windows 전용: Git Bash 실행 파일(`bash.exe`)의 경로입니다. Git Bash가 설치되었지만 PATH에 없을 때 사용합니다. [Windows 설정](/ko/setup#set-up-on-windows) 참조 |229| `CLAUDE_CODE_GIT_BASH_PATH` | Windows 전용: Git Bash 실행 파일(`bash.exe`)의 경로입니다. Git Bash가 설치되었지만 PATH에 없을 때 사용합니다. [Windows 설정](/ko/setup#set-up-on-windows) 참조 |

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

233| `CLAUDE_CODE_IDE_SKIP_AUTO_INSTALL` | IDE 확장의 자동 설치를 건너뜁니다. [`autoInstallIdeExtension`](/ko/settings#global-config-settings)을 `false`로 설정하는 것과 동일합니다. |235| `CLAUDE_CODE_IDE_SKIP_AUTO_INSTALL` | IDE 확장의 자동 설치를 건너뜁니다. [`autoInstallIdeExtension`](/ko/settings#global-config-settings)을 `false`로 설정하는 것과 동일합니다. |

235| `CLAUDE_CODE_MAX_CONTEXT_TOKENS` | Claude Code가 활성 모델에 대해 가정하는 컨텍스트 윈도우 크기를 재정의합니다. {/* min-version: 2.1.193 */}v2.1.193부터 Claude Code가 Claude 모델로 인식하는 모델 이름에 대해 직접 적용됩니다. 인식된 Claude 모델의 경우 `DISABLE_COMPACT`도 설정되어 있을 때만 적용됩니다. `ANTHROPIC_BASE_URL`을 통해 이름의 기본 제공 크기와 일치하지 않는 컨텍스트 윈도우를 가진 모델로 라우팅할 때 사용합니다. |237| `CLAUDE_CODE_MAX_CONTEXT_TOKENS` | Claude Code가 활성 모델에 대해 가정하는 컨텍스트 윈도우 크기를 재정의합니다. {{/* min-version: 2.1.193 */}}v2.1.193부터 Claude Code가 Claude 모델로 인식하는 모델 이름에 대해 직접 적용됩니다. 인식된 Claude 모델의 경우 `DISABLE_COMPACT`도 설정되어 있을 때만 적용됩니다. `ANTHROPIC_BASE_URL`을 통해 이름의 기본 제공 크기와 일치하지 않는 컨텍스트 윈도우를 가진 모델로 라우팅할 때 사용합니다. |

236| `CLAUDE_CODE_MAX_OUTPUT_TOKENS` | 대부분의 요청에 대한 최대 출력 토큰 수를 설정합니다. 기본값 및 상한은 모델에 따라 다릅니다. [최대 출력 토큰](https://platform.claude.com/docs/en/about-claude/models/overview#latest-models-comparison) 참조. 이 값을 증가시키면 [자동 압축](/ko/costs#reduce-token-usage)이 트리거되기 전에 사용 가능한 효과적인 컨텍스트 윈도우가 감소합니다. |238| `CLAUDE_CODE_MAX_OUTPUT_TOKENS` | 대부분의 요청에 대한 최대 출력 토큰 수를 설정합니다. 기본값 및 상한은 모델에 따라 다릅니다. [최대 출력 토큰](https://platform.claude.com/docs/en/about-claude/models/overview#latest-models-comparison) 참조. 이 값을 증가시키면 [자동 압축](/ko/costs#reduce-token-usage)이 트리거되기 전에 사용 가능한 효과적인 컨텍스트 윈도우가 감소합니다. |

237| `CLAUDE_CODE_MAX_RETRIES` | 실패한 API 요청을 재시도할 횟수를 재정의합니다(기본값: 10). {/* min-version: 2.1.186 */}v2.1.186부터 최대 15로 제한됩니다. {/* min-version: 2.1.199 */}v2.1.199부터 `CLAUDE_CODE_RETRY_WATCHDOG`이 기본값을 올리고 제한을 제거합니다. 더 긴 중단을 기다려야 하는 무인 세션의 경우 `CLAUDE_CODE_RETRY_WATCHDOG`을 대신 설정합니다. |239| `CLAUDE_CODE_MAX_RETRIES` | 실패한 API 요청을 재시도할 횟수를 재정의합니다(기본값: 10). {{/* min-version: 2.1.186 */}}v2.1.186부터 최대 15로 제한됩니다. {{/* min-version: 2.1.199 */}}v2.1.199부터 `CLAUDE_CODE_RETRY_WATCHDOG`이 기본값을 올리고 제한을 제거합니다. 더 긴 중단을 기다려야 하는 무인 세션의 경우 `CLAUDE_CODE_RETRY_WATCHDOG`을 대신 설정합니다. |

238| `CLAUDE_CODE_MAX_TOOL_USE_CONCURRENCY` | 병렬로 실행할 수 있는 읽기 전용 도구 및 subagent의 최대 수(기본값: 10). 더 높은 값은 병렬 처리를 증가시키지만 더 많은 리소스를 소비합니다. |240| `CLAUDE_CODE_MAX_TOOL_USE_CONCURRENCY` | 병렬로 실행할 수 있는 읽기 전용 도구 및 subagent의 최대 수(기본값: 10). 더 높은 값은 병렬 처리를 증가시키지만 더 많은 리소스를 소비합니다. |

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

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

243| `CLAUDE_CODE_NEW_INIT` | `/init`이 대화형 설정 흐름을 실행하도록 하려면 `1`로 설정합니다. 흐름은 코드베이스를 탐색하고 작성하기 전에 CLAUDE.md, skill 및 훅을 포함하여 생성할 파일을 묻습니다. 이 변수가 없으면 `/init`은 프롬프트 없이 자동으로 CLAUDE.md를 생성합니다. |245| `CLAUDE_CODE_NEW_INIT` | `/init`이 대화형 설정 흐름을 실행하도록 하려면 `1`로 설정합니다. 흐름은 코드베이스를 탐색하고 작성하기 전에 CLAUDE.md, skill 및 훅을 포함하여 생성할 파일을 묻습니다. 이 변수가 없으면 `/init`은 프롬프트 없이 자동으로 CLAUDE.md를 생성합니다. |

244| `CLAUDE_CODE_NO_FLICKER` | [전체 화면 렌더링](/ko/fullscreen)을 활성화하려면 `1`로 설정합니다. 이는 깜박임을 줄이고 긴 대화에서 메모리를 평탄하게 유지하는 연구 미리보기입니다. [`tui`](/ko/settings#available-settings) 설정과 동일합니다. `/tui fullscreen`으로도 전환할 수 있습니다. |246| `CLAUDE_CODE_NO_FLICKER` | [전체 화면 렌더링](/ko/fullscreen)을 활성화하려면 `1`로 설정합니다. 이는 깜박임을 줄이고 긴 대화에서 메모리를 평탄하게 유지하는 연구 미리보기입니다. [`tui`](/ko/settings#available-settings) 설정과 동일합니다. `/tui fullscreen`으로도 전환할 수 있습니다. |

245| `CLAUDE_CODE_OAUTH_REFRESH_TOKEN` | Claude.ai 인증용 OAuth 새로 고침 토큰입니다. 설정하면 `claude auth login`이 브라우저를 열지 않고 이 토큰을 직접 교환합니다. `CLAUDE_CODE_OAUTH_SCOPES`가 필요합니다. 자동화된 환경에서 인증을 프로비저닝하는 데 유용합니다. |247| `CLAUDE_CODE_OAUTH_REFRESH_TOKEN` | Claude.ai 인증용 OAuth 새로 고침 토큰입니다. 설정하면 `claude auth login`이 브라우저를 열지 않고 이 토큰을 직접 교환합니다. `CLAUDE_CODE_OAUTH_SCOPES`가 필요합니다. 자동화된 환경에서 인증을 프로비저닝하는 데 유용합니다. |

246| `CLAUDE_CODE_OAUTH_SCOPES` | 새로 고침 토큰이 발급된 공백으로 구분된 OAuth 범위(예: `"user:profile user:inference user:sessions:claude_code"`). `CLAUDE_CODE_OAUTH_REFRESH_TOKEN`이 설정되면 필수입니다. |248| `CLAUDE_CODE_OAUTH_SCOPES` | 새로 고침 토큰이 발급된 공백으로 구분된 OAuth 범위(예: `"user:profile user:inference user:sessions:claude_code"`). `CLAUDE_CODE_OAUTH_REFRESH_TOKEN`이 설정되면 필수입니다. |

247| `CLAUDE_CODE_OAUTH_TOKEN` | Claude.ai 인증용 OAuth 액세스 토큰입니다. `/login`의 대안으로 SDK 및 자동화된 환경에 사용됩니다. 키체인 저장 자격 증명보다 우선합니다. [`claude setup-token`](/ko/authentication#generate-a-long-lived-token)으로 생성합니다. |249| `CLAUDE_CODE_OAUTH_TOKEN` | Claude.ai 인증용 OAuth 액세스 토큰입니다. `/login`의 대안으로 SDK 및 자동화된 환경에 사용됩니다. 키체인 저장 자격 증명보다 우선합니다. [`claude setup-token`](/ko/authentication#generate-a-long-lived-token)으로 생성합니다. |

248| `CLAUDE_CODE_OPUS_4_6_FAST_MODE_OVERRIDE` | {/* max-version: 2.1.159 */}v2.1.160에서 제거되었으며 이제 작동하지 않습니다. 이전에는 [빠른 모드](/ko/fast-mode)를 Claude Opus 4.6에 고정했습니다. |250| `CLAUDE_CODE_OPUS_4_6_FAST_MODE_OVERRIDE` | {{/* max-version: 2.1.159 */}}v2.1.160에서 제거되었으며 이제 작동하지 않습니다. 이전에는 [빠른 모드](/ko/fast-mode)를 Claude Opus 4.6에 고정했습니다. Opus 4.6은 더 이상 빠른 모드를 지원하지 않습니다. |

249| `CLAUDE_CODE_OTEL_DIAG_STDERR` | {/* min-version: 2.1.179 */}OpenTelemetry 내보내기 진단 오류를 stderr에 쓰려면 `1`로 설정합니다. 기본적으로 이러한 오류는 `--debug`에서만 나타나므로 Prometheus 포트 충돌과 같은 잘못 구성된 내보내기는 그렇지 않으면 자동으로 실패합니다. Claude Code v2.1.179 이상이 필요합니다. [모니터링](/ko/monitoring-usage) 참조 |251| `CLAUDE_CODE_OTEL_DIAG_STDERR` | {{/* min-version: 2.1.179 */}}OpenTelemetry 내보내기 진단 오류를 stderr에 쓰려면 `1`로 설정합니다. 기본적으로 이러한 오류는 `--debug`에서만 나타나므로 Prometheus 포트 충돌과 같은 잘못 구성된 내보내기는 그렇지 않으면 자동으로 실패합니다. Claude Code v2.1.179 이상이 필요합니다. [모니터링](/ko/monitoring-usage) 참조 |

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

251| `CLAUDE_CODE_OTEL_HEADERS_HELPER_DEBOUNCE_MS` | 동적 OpenTelemetry 헤더를 새로 고치는 간격(밀리초)(기본값: 1740000 / 29분). [동적 헤더](/ko/monitoring-usage#dynamic-headers) 참조 |253| `CLAUDE_CODE_OTEL_HEADERS_HELPER_DEBOUNCE_MS` | 동적 OpenTelemetry 헤더를 새로 고치는 간격(밀리초)(기본값: 1740000 / 29분). [동적 헤더](/ko/monitoring-usage#dynamic-headers) 참조 |

252| `CLAUDE_CODE_OTEL_SHUTDOWN_TIMEOUT_MS` | 종료 시 OpenTelemetry 내보내기가 완료되는 타임아웃(밀리초)(기본값: 2000). 메트릭이 종료 시 삭제되면 증가시킵니다. [모니터링](/ko/monitoring-usage) 참조 |254| `CLAUDE_CODE_OTEL_SHUTDOWN_TIMEOUT_MS` | 종료 시 OpenTelemetry 내보내기가 완료되는 타임아웃(밀리초)(기본값: 2000). 메트릭이 종료 시 삭제되면 증가시킵니다. [모니터링](/ko/monitoring-usage) 참조 |

258| `CLAUDE_CODE_PLUGIN_PREFER_HTTPS` | GitHub `owner/repo` 플러그인 소스를 SSH 대신 HTTPS를 통해 복제하려면 `1`로 설정합니다. CI 러너, 컨테이너 또는 `github.com`에 대해 구성된 SSH 키가 없는 모든 환경에서 유용합니다. |260| `CLAUDE_CODE_PLUGIN_PREFER_HTTPS` | GitHub `owner/repo` 플러그인 소스를 SSH 대신 HTTPS를 통해 복제하려면 `1`로 설정합니다. CI 러너, 컨테이너 또는 `github.com`에 대해 구성된 SSH 키가 없는 모든 환경에서 유용합니다. |

259| `CLAUDE_CODE_PLUGIN_SEED_DIR` | 하나 이상의 읽기 전용 플러그인 시드 디렉토리의 경로이며, Unix에서는 `:`로, Windows에서는 `;`로 구분됩니다. 이를 사용하여 사전 채워진 플러그인 디렉토리를 컨테이너 이미지에 번들로 제공합니다. Claude Code는 시작 시 이러한 디렉토리에서 마켓플레이스를 등록하고 다시 복제하지 않고 사전 캐시된 플러그인을 사용합니다. [컨테이너용 플러그인 사전 채우기](/ko/plugin-marketplaces#pre-populate-plugins-for-containers) 참조 |261| `CLAUDE_CODE_PLUGIN_SEED_DIR` | 하나 이상의 읽기 전용 플러그인 시드 디렉토리의 경로이며, Unix에서는 `:`로, Windows에서는 `;`로 구분됩니다. 이를 사용하여 사전 채워진 플러그인 디렉토리를 컨테이너 이미지에 번들로 제공합니다. Claude Code는 시작 시 이러한 디렉토리에서 마켓플레이스를 등록하고 다시 복제하지 않고 사전 캐시된 플러그인을 사용합니다. [컨테이너용 플러그인 사전 채우기](/ko/plugin-marketplaces#pre-populate-plugins-for-containers) 참조 |

260| `CLAUDE_CODE_POWERSHELL_RESPECT_EXECUTION_POLICY` | Claude Code가 PowerShell을 생성할 때 `-ExecutionPolicy Bypass`를 전달하지 않으려면 `1`로 설정합니다. 도구 호출, 훅, 상태 줄 명령의 경우 대신 머신의 효과적인 실행 정책을 존중합니다. 기본적으로 Claude Code는 프로세스 범위에서 실행 정책을 우회하므로 `.ps1` 스크립트 및 모듈 가져오기가 기본 제한 Windows 설치에서 작동합니다. 프로세스 범위 우회는 이 설정과 관계없이 Group Policy `MachinePolicy` 또는 `UserPolicy`를 재정의하지 않습니다. |262| `CLAUDE_CODE_POWERSHELL_RESPECT_EXECUTION_POLICY` | Claude Code가 PowerShell을 생성할 때 `-ExecutionPolicy Bypass`를 전달하지 않으려면 `1`로 설정합니다. 도구 호출, 훅, 상태 줄 명령의 경우 대신 머신의 효과적인 실행 정책을 존중합니다. 기본적으로 Claude Code는 프로세스 범위에서 실행 정책을 우회하므로 `.ps1` 스크립트 및 모듈 가져오기가 기본 제한 Windows 설치에서 작동합니다. 프로세스 범위 우회는 이 설정과 관계없이 Group Policy `MachinePolicy` 또는 `UserPolicy`를 재정의하지 않습니다. |

261| `CLAUDE_CODE_PRINT_BG_WAIT_CEILING_MS` | {/* min-version: 2.1.182 */}[비대화형 모드](/ko/headless#background-tasks-at-exit)에서 `-p` 플래그를 사용하여 최종 턴 후 결과가 출력의 일부인 백그라운드 subagent 및 워크플로우를 기다리는 최대 시간(밀리초). 기본값: `600000`, 또는 10분. 제한을 초과하면 남은 백그라운드 작업이 종료되고 프로세스가 종료됩니다. 일반 백그라운드 셸에 적용되는 5초 유예 기간과는 별개입니다. `0`으로 설정하여 무한정 대기합니다. |263| `CLAUDE_CODE_PRINT_BG_WAIT_CEILING_MS` | {{/* min-version: 2.1.182 */}}[비대화형 모드](/ko/headless#background-tasks-at-exit)에서 `-p` 플래그를 사용하여 최종 턴 후 결과가 출력의 일부인 백그라운드 subagent 및 워크플로우를 기다리는 최대 시간(밀리초). 기본값: `600000`, 또는 10분. 제한을 초과하면 남은 백그라운드 작업이 종료되고 프로세스가 종료됩니다. 일반 백그라운드 셸에 적용되는 5초 유예 기간과는 별개입니다. `0`으로 설정하여 무한정 대기합니다. |

262| `CLAUDE_CODE_PROPAGATE_TRACEPARENT` | {/* min-version: 2.1.152 */}}`ANTHROPIC_BASE_URL`이 사용자 정의 프록시를 가리킬 때 W3C 추적 컨텍스트를 전파하려면 `1`로 설정합니다. 전파는 모델 및 HTTP MCP 요청의 `traceparent` 헤더와 Bash, PowerShell, 훅 subprocess의 `TRACEPARENT` 환경 변수를 포함합니다. 기본적으로 전파는 Anthropic API에 직접 연결할 때만 활성화됩니다. v2.1.152에서 추가됨. [추적(베타)](/ko/monitoring-usage#traces-beta) 참조 |264| `CLAUDE_CODE_PROPAGATE_TRACEPARENT` | {{/* min-version: 2.1.152 */}}`ANTHROPIC_BASE_URL`이 사용자 정의 프록시를 가리킬 때 W3C 추적 컨텍스트를 전파하려면 `1`로 설정합니다. 전파는 모델 및 HTTP MCP 요청의 `traceparent` 헤더와 Bash, PowerShell, 훅 subprocess의 `TRACEPARENT` 환경 변수를 포함합니다. 기본적으로 전파는 Anthropic API에 직접 연결할 때만 활성화됩니다. v2.1.152에서 추가됨. [추적(베타)](/ko/monitoring-usage#traces-beta) 참조 |

263| `CLAUDE_CODE_PROVIDER_MANAGED_BY_HOST` | Claude Code를 포함하고 대신 모델 공급자 라우팅을 관리하는 호스트 플랫폼에서 설정합니다. 설정하면 설정 파일의 `CLAUDE_CODE_USE_BEDROCK`, `ANTHROPIC_BASE_URL`, `ANTHROPIC_API_KEY`와 같은 공급자 선택, 엔드포인트, 인증 변수가 무시되므로 사용자 설정이 호스트의 라우팅을 재정의할 수 없습니다. Bedrock, Vertex, Foundry에 대한 자동 원격 분석 옵트아웃도 건너뛰므로 원격 분석은 표준 `DISABLE_TELEMETRY` 옵트아웃을 따릅니다. [API 공급자별 기본 동작](/ko/data-usage#default-behaviors-by-api-provider) 참조 |265| `CLAUDE_CODE_PROVIDER_MANAGED_BY_HOST` | Claude Code를 포함하고 대신 모델 공급자 라우팅을 관리하는 호스트 플랫폼에서 설정합니다. 설정하면 설정 파일의 `CLAUDE_CODE_USE_BEDROCK`, `ANTHROPIC_BASE_URL`, `ANTHROPIC_API_KEY`와 같은 공급자 선택, 엔드포인트, 인증 변수가 무시되므로 사용자 설정이 호스트의 라우팅을 재정의할 수 없습니다. Amazon Bedrock, Google Cloud's Agent Platform, Microsoft Foundry에 대한 자동 원격 분석 옵트아웃도 건너뛰므로 원격 분석은 표준 `DISABLE_TELEMETRY` 옵트아웃을 따릅니다. [API 공급자별 기본 동작](/ko/data-usage#default-behaviors-by-api-provider) 참조 |

265| `CLAUDE_CODE_REMOTE` | Claude Code가 [클라우드 세션](/ko/claude-code-on-the-web)으로 실행 중일 때 자동으로 `true`로 설정됩니다. 훅 또는 설정 스크립트에서 이를 읽어 클라우드 환경에 있는지 감지합니다. |267| `CLAUDE_CODE_REMOTE` | Claude Code가 [클라우드 세션](/ko/claude-code-on-the-web)으로 실행 중일 때 자동으로 `true`로 설정됩니다. 훅 또는 설정 스크립트에서 이를 읽어 클라우드 환경에 있는지 감지합니다. |

266| `CLAUDE_CODE_REMOTE_SESSION_ID` | [클라우드 세션](/ko/claude-code-on-the-web)에서 현재 세션의 ID로 자동으로 설정됩니다. 세션 트랜스크립트로 다시 연결하는 링크를 구성하려면 이를 읽습니다. [세션으로 출력 다시 연결](/ko/claude-code-on-the-web#link-output-back-to-the-session) 참조 |268| `CLAUDE_CODE_REMOTE_SESSION_ID` | [클라우드 세션](/ko/claude-code-on-the-web)에서 현재 세션의 ID로 자동으로 설정됩니다. 세션 트랜스크립트로 다시 연결하는 링크를 구성하려면 이를 읽습니다. [세션으로 출력 다시 연결](/ko/claude-code-on-the-web#link-output-back-to-the-session) 참조 |

277| `CLAUDE_CODE_SIMPLE` | 최소 시스템 프롬프트 및 Bash, 파일 읽기, 파일 편집 도구만으로 실행하려면 `1`로 설정합니다. `--mcp-config`의 MCP 도구는 계속 사용 가능합니다. 훅, skill, 플러그인, MCP 서버, 자동 메모리, CLAUDE.md의 자동 검색을 비활성화합니다. OAuth 토큰 및 키체인 자격 증명은 읽지 않으므로 Anthropic 인증은 `ANTHROPIC_API_KEY` 또는 `--settings`의 `apiKeyHelper`에서 와야 합니다. [`--bare`](/ko/headless#start-faster-with-bare-mode) 전달과 동일합니다. |279| `CLAUDE_CODE_SIMPLE` | 최소 시스템 프롬프트 및 Bash, 파일 읽기, 파일 편집 도구만으로 실행하려면 `1`로 설정합니다. `--mcp-config`의 MCP 도구는 계속 사용 가능합니다. 훅, skill, 플러그인, MCP 서버, 자동 메모리, CLAUDE.md의 자동 검색을 비활성화합니다. OAuth 토큰 및 키체인 자격 증명은 읽지 않으므로 Anthropic 인증은 `ANTHROPIC_API_KEY` 또는 `--settings`의 `apiKeyHelper`에서 와야 합니다. [`--bare`](/ko/headless#start-faster-with-bare-mode) 전달과 동일합니다. |

278| `CLAUDE_CODE_SIMPLE_SYSTEM_PROMPT` | 모든 모델에서 더 짧은 시스템 프롬프트 및 축소된 도구 설명을 사용하려면 `1`로 설정합니다. `0`, `false`, `no`, 또는 `off`로 설정하여 실험 또는 서버 구성이 그렇지 않으면 활성화할 때에도 옵트아웃합니다. 전체 도구 세트, 훅, MCP 서버, CLAUDE.md 검색은 계속 활성화됩니다. |280| `CLAUDE_CODE_SIMPLE_SYSTEM_PROMPT` | 모든 모델에서 더 짧은 시스템 프롬프트 및 축소된 도구 설명을 사용하려면 `1`로 설정합니다. `0`, `false`, `no`, 또는 `off`로 설정하여 실험 또는 서버 구성이 그렇지 않으면 활성화할 때에도 옵트아웃합니다. 전체 도구 세트, 훅, MCP 서버, CLAUDE.md 검색은 계속 활성화됩니다. |

279| `CLAUDE_CODE_SKIP_ANTHROPIC_AWS_AUTH` | [Claude Platform on AWS](/ko/claude-platform-on-aws)에 대한 클라이언트 측 인증을 건너뜁니다. 게이트웨이가 요청에 자체 서명하는 경우 |281| `CLAUDE_CODE_SKIP_ANTHROPIC_AWS_AUTH` | [Claude Platform on AWS](/ko/claude-platform-on-aws)에 대한 클라이언트 측 인증을 건너뜁니다. 게이트웨이가 요청에 자체 서명하는 경우 |

281| `CLAUDE_CODE_SKIP_FOUNDRY_AUTH` | Microsoft Foundry에 대한 Azure 인증을 건너뜁니다(예: LLM 게이트웨이를 사용할 때). |283| `CLAUDE_CODE_SKIP_FOUNDRY_AUTH` | Microsoft Foundry에 대한 Azure 인증을 건너뜁니다(예: LLM 게이트웨이를 사용할 때). Claude Code는 요청을 Azure 자격 증명 없이 전송하고 `ANTHROPIC_CUSTOM_HEADERS`를 통해 제공하는 것과 같은 `Authorization` 헤더를 유지합니다. `ANTHROPIC_FOUNDRY_API_KEY` 또는 `ANTHROPIC_FOUNDRY_AUTH_TOKEN`이 설정되면 무시됩니다. {{/* min-version: 2.1.203 */}}v2.1.203 이전에는 이 변수가 API 키도 설정되지 않으면 Microsoft Foundry 클라이언트가 요청을 보낼 수 없게 했습니다. |

283| `CLAUDE_CODE_SKIP_PROMPT_HISTORY` | 프롬프트 기록 및 세션 트랜스크립트를 디스크에 쓰지 않으려면 `1`로 설정합니다. 이 변수로 시작된 세션은 `--resume`, `--continue` 또는 위쪽 화살표 기록에 나타나지 않습니다. 임시 스크립트 세션에 유용합니다. |285| `CLAUDE_CODE_SKIP_PROMPT_HISTORY` | 프롬프트 기록 및 세션 트랜스크립트를 디스크에 쓰지 않으려면 `1`로 설정합니다. 이 변수로 시작된 세션은 `--resume`, `--continue` 또는 위쪽 화살표 기록에 나타나지 않습니다. 임시 스크립트 세션에 유용합니다. |

285| `CLAUDE_CODE_STOP_HOOK_BLOCK_CAP` | [Stop](/ko/hooks#stop) 또는 [SubagentStop](/ko/hooks#subagentstop) 훅이 턴 종료를 차단할 수 있는 최대 연속 횟수입니다(기본값: 8). Claude Code가 턴을 어쨌든 종료하기 전입니다. `0`으로 설정하여 제한을 비활성화합니다. 훅이 해결하기 위해 더 많은 반복이 필요하면 이를 올립니다. |287| `CLAUDE_CODE_STOP_HOOK_BLOCK_CAP` | [Stop](/ko/hooks#stop) 또는 [SubagentStop](/ko/hooks#subagentstop) 훅이 턴 종료를 차단할 수 있는 최대 연속 횟수입니다(기본값: 8). Claude Code가 턴을 어쨌든 종료하기 전입니다. `0`으로 설정하여 제한을 비활성화합니다. 훅이 해결하기 위해 더 많은 반복이 필요하면 이를 올립니다. |

286| `CLAUDE_CODE_SUBAGENT_MODEL` | [모델 구성](/ko/model-config) 참조 {/* min-version: 2.1.196 */}v2.1.196부터 `inherit`로 설정하는 것은 설정하지 않은 것과 동일합니다. 이전 버전은 `inherit`를 모든 subagent를 주 대화의 모델로 강제하는 재정의로 취급했습니다. |288| `CLAUDE_CODE_SUBAGENT_MODEL` | [모델 구성](/ko/model-config) 참조 {{/* min-version: 2.1.196 */}}v2.1.196부터 `inherit`로 설정하는 것은 설정하지 않은 것과 동일합니다. 이전 버전은 `inherit`를 모든 subagent를 주 대화의 모델로 강제하는 재정의로 취급했습니다. |

287| `CLAUDE_CODE_SUBPROCESS_ENV_SCRUB` | Anthropic 및 클라우드 공급자 자격 증명을 subprocess 환경(Bash 도구, 훅, MCP stdio 서버)에서 제거하려면 `1`로 설정합니다. 부모 Claude 프로세스는 API 호출을 위해 이러한 자격 증명을 유지하지만 자식 프로세스는 이를 읽을 수 없으므로 셸 확장을 통해 비밀을 유출하려는 프롬프트 주입 공격에 대한 노출을 줄입니다. Linux에서는 Bash subprocess를 격리된 PID 네임스페이스에서도 실행하므로 `/proc`을 통해 호스트 프로세스 환경을 읽을 수 없습니다. 부작용으로 `ps`, `pgrep`, `kill`은 호스트 프로세스를 보거나 신호할 수 없습니다. `allowed_non_write_users`가 구성되면 `claude-code-action`이 자동으로 이를 설정합니다. |289| `CLAUDE_CODE_SUBPROCESS_ENV_SCRUB` | Anthropic 및 클라우드 공급자 자격 증명을 subprocess 환경(Bash 도구, 훅, MCP stdio 서버)에서 제거하려면 `1`로 설정합니다. 부모 Claude 프로세스는 API 호출을 위해 이러한 자격 증명을 유지하지만 자식 프로세스는 이를 읽을 수 없으므로 셸 확장을 통해 비밀을 유출하려는 프롬프트 주입 공격에 대한 노출을 줄입니다. Linux에서는 Bash subprocess를 격리된 PID 네임스페이스에서도 실행하므로 `/proc`을 통해 호스트 프로세스 환경을 읽을 수 없습니다. 부작용으로 `ps`, `pgrep`, `kill`은 호스트 프로세스를 보거나 신호할 수 없습니다. `allowed_non_write_users`가 구성되면 `claude-code-action`이 자동으로 이를 설정합니다. |

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

289| `CLAUDE_CODE_SYNC_PLUGIN_INSTALL_TIMEOUT_MS` | 동기 플러그인 설치의 타임아웃(밀리초). 초과되면 Claude Code는 플러그인 없이 진행하고 오류를 기록합니다. 기본값 없음: 이 변수가 없으면 동기 설치는 완료될 때까지 대기합니다. |291| `CLAUDE_CODE_SYNC_PLUGIN_INSTALL_TIMEOUT_MS` | 동기 플러그인 설치의 타임아웃(밀리초). 초과되면 Claude Code는 플러그인 없이 진행하고 오류를 기록합니다. 기본값 없음: 이 변수가 없으면 동기 설치는 완료될 때까지 대기합니다. |

293| `CLAUDE_CODE_SYNTAX_HIGHLIGHT` | diff 출력에서 구문 강조를 비활성화하려면 `false`로 설정합니다. 색상이 터미널 설정을 방해할 때 유용합니다. 코드 블록 및 파일 미리보기에서 강조를 비활성화하려면 [`syntaxHighlightingDisabled`](/ko/settings) 설정을 사용합니다. |295| `CLAUDE_CODE_SYNTAX_HIGHLIGHT` | diff 출력에서 구문 강조를 비활성화하려면 `false`로 설정합니다. 색상이 터미널 설정을 방해할 때 유용합니다. 코드 블록 및 파일 미리보기에서 강조를 비활성화하려면 [`syntaxHighlightingDisabled`](/ko/settings) 설정을 사용합니다. |

294| `CLAUDE_CODE_TASK_LIST_ID` | 세션 간에 작업 목록을 공유합니다. 여러 Claude Code 인스턴스에서 동일한 ID를 설정하여 공유 작업 목록에서 조정합니다. [작업 목록](/ko/interactive-mode#task-list) 참조 |296| `CLAUDE_CODE_TASK_LIST_ID` | 세션 간에 작업 목록을 공유합니다. 여러 Claude Code 인스턴스에서 동일한 ID를 설정하여 공유 작업 목록에서 조정합니다. [작업 목록](/ko/interactive-mode#task-list) 참조 |

296| `CLAUDE_CODE_TMPDIR` | 내부 임시 파일에 사용되는 임시 디렉토리를 재정의합니다. Claude Code는 이 경로에 `/claude-{uid}/`(Unix) 또는 `/claude/`(Windows)를 추가합니다. 기본값: macOS의 경우 `/tmp`, Linux/Windows의 경우 `os.tmpdir()`. {/* min-version: 2.1.161 */}v2.1.161부터 macOS 및 Linux에서 [샌드박스](/ko/sandboxing) Bash subprocess는 경로가 너무 길어지면 일부 도구가 실패하므로 시스템 기본값 아래에 짧은 폴백 `$TMPDIR`을 받습니다. 샌드박스되지 않은 Bash 명령은 셸의 `$TMPDIR`을 변경되지 않고 상속합니다. Claude Code의 자체 임시 파일은 항상 재정의를 사용합니다. |298| `CLAUDE_CODE_TMPDIR` | 내부 임시 파일에 사용되는 임시 디렉토리를 재정의합니다. Claude Code는 이 경로에 `/claude-{uid}/`(Unix) 또는 `/claude/`(Windows)를 추가합니다. 기본값: macOS의 경우 `/tmp`, Linux/Windows의 경우 `os.tmpdir()`. {{/* min-version: 2.1.161 */}}v2.1.161부터 macOS 및 Linux에서 [샌드박스](/ko/sandboxing) Bash subprocess는 경로가 너무 길어지면 일부 도구가 실패하므로 시스템 기본값 아래에 짧은 폴백 `$TMPDIR`을 받습니다. 샌드박스되지 않은 Bash 명령은 셸의 `$TMPDIR`을 변경되지 않고 상속합니다. Claude Code의 자체 임시 파일은 항상 재정의를 사용합니다. |

297| `CLAUDE_CODE_TMUX_TRUECOLOR` | tmux 내에서 24비트 truecolor 출력을 허용하려면 `1`로 설정합니다. 기본적으로 `$TMUX`가 설정되면 Claude Code는 256색으로 제한합니다. tmux는 구성되지 않으면 truecolor 이스케이프 시퀀스를 통과하지 않기 때문입니다. `~/.tmux.conf`에 `set -ga terminal-overrides ',*:Tc'`를 추가한 후 이를 설정합니다. [터미널 구성](/ko/terminal-config)에서 다른 tmux 설정을 참조합니다. |299| `CLAUDE_CODE_TMUX_TRUECOLOR` | tmux 내에서 24비트 truecolor 출력을 허용하려면 `1`로 설정합니다. 기본적으로 `$TMUX`가 설정되면 Claude Code는 256색으로 제한합니다. tmux는 구성되지 않으면 truecolor 이스케이프 시퀀스를 통과하지 않기 때문입니다. `~/.tmux.conf`에 `set -ga terminal-overrides ',*:Tc'`를 추가한 후 이를 설정합니다. [터미널 구성](/ko/terminal-config)에서 다른 tmux 설정을 참조합니다. |

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

303| `CLAUDE_CODE_USE_POWERSHELL_TOOL` | PowerShell 도구를 제어합니다. Windows에서 Git Bash가 없으면 도구가 자동으로 활성화됩니다. `0`으로 설정하여 비활성화합니다. Windows에 Git Bash가 설치되어 있으면 도구가 점진적으로 롤아웃됩니다: 옵트인하려면 `1`로 설정하거나 옵트아웃하려면 `0`으로 설정합니다. Linux, macOS, WSL에서는 `1`로 설정하여 활성화합니다. PATH에 `pwsh`가 필요합니다. Windows에서 활성화되면 Claude는 Git Bash를 통해 라우팅하는 대신 PowerShell 명령을 기본적으로 실행할 수 있습니다. [PowerShell 도구](/ko/tools-reference#powershell-tool) 참조 |305| `CLAUDE_CODE_USE_POWERSHELL_TOOL` | PowerShell 도구를 제어합니다. Windows에서 Git Bash가 없으면 도구가 자동으로 활성화됩니다. `0`으로 설정하여 비활성화합니다. Windows에 Git Bash가 설치되어 있으면 도구가 점진적으로 롤아웃됩니다: 옵트인하려면 `1`로 설정하거나 옵트아웃하려면 `0`으로 설정합니다. Linux, macOS, WSL에서는 `1`로 설정하여 활성화합니다. PATH에 `pwsh`가 필요합니다. Windows에서 활성화되면 Claude는 Git Bash를 통해 라우팅하는 대신 PowerShell 명령을 기본적으로 실행할 수 있습니다. [PowerShell 도구](/ko/tools-reference#powershell-tool) 참조 |

305| `CLAUDE_CONFIG_DIR` | 구성 디렉토리를 재정의합니다(기본값: `~/.claude`). 모든 설정, 자격 증명, 세션 기록 및 플러그인이 이 경로 아래에 저장됩니다. 여러 계정을 나란히 실행하는 데 유용합니다: 예를 들어 `alias claude-work='CLAUDE_CONFIG_DIR=~/.claude-work claude'` |307| `CLAUDE_CONFIG_DIR` | 구성 디렉토리를 재정의합니다(기본값: `~/.claude`). 모든 설정, 자격 증명, 세션 기록 및 플러그인이 이 경로 아래에 저장됩니다. 여러 계정을 나란히 실행하는 데 유용합니다: 예를 들어 `alias claude-work='CLAUDE_CONFIG_DIR=~/.claude-work claude'` |

306| `CLAUDE_DISABLE_ADOPT` | {/* min-version: 2.1.195 */}세션을 백그라운드 처리할 때 `←` 또는 [`/background`](/ko/agent-view#from-inside-a-session)를 눌러 진행 중인 백그라운드 작업을 수행하는 대신 중지하려면 `1`로 설정합니다. Claude Code는 백그라운드 처리 전에 확인을 요청한 다음 그렇지 않으면 수행할 작업을 중지합니다. Claude Code v2.1.195 이상이 필요합니다. |308| `CLAUDE_DISABLE_ADOPT` | {{/* min-version: 2.1.195 */}}세션을 백그라운드 처리할 때 `←` 또는 [`/background`](/ko/agent-view#from-inside-a-session)를 눌러 진행 중인 백그라운드 작업을 수행하는 대신 중지하려면 `1`로 설정합니다. Claude Code는 백그라운드 처리 전에 확인을 요청한 다음 그렇지 않으면 수행할 작업을 중지합니다. Claude Code v2.1.195 이상이 필요합니다. |

307| `CLAUDE_EFFORT` | Bash 도구 subprocess 및 훅 명령에서 활성 [노력 수준](/ko/model-config#adjust-effort-level)으로 자동으로 설정됩니다: `low`, `medium`, `high`, `xhigh`, 또는 `max`. Ultracode는 별개의 수준이 아니며 `xhigh`로 보고됩니다. [훅](/ko/hooks)에 전달된 `effort.level` 필드와 일치합니다. 현재 모델이 노력 매개변수를 지원할 때만 설정됩니다. |309| `CLAUDE_EFFORT` | Bash 도구 subprocess 및 훅 명령에서 활성 [노력 수준](/ko/model-config#adjust-effort-level)으로 자동으로 설정됩니다: `low`, `medium`, `high`, `xhigh`, 또는 `max`. Ultracode는 별개의 수준이 아니며 `xhigh`로 보고됩니다. [훅](/ko/hooks)에 전달된 `effort.level` 필드와 일치합니다. 현재 모델이 노력 매개변수를 지원할 때만 설정됩니다. |

308| `CLAUDE_ENABLE_BYTE_WATCHDOG` | 바이트 수준 스트리밍 유휴 감시견을 강제로 활성화하려면 `1`로 설정하거나, 강제로 비활성화하려면 `0`으로 설정합니다. 설정하지 않으면 감시견은 직접 Anthropic API 및 [Claude Platform on AWS](/ko/claude-platform-on-aws) 연결에 대해 기본적으로 활성화됩니다. 바이트 감시견은 `CLAUDE_STREAM_IDLE_TIMEOUT_MS`로 설정된 기간 동안 와이어에 바이트가 도착하지 않으면 연결을 중단합니다. 최소 5분이며 이벤트 수준 감시견과 독립적입니다. |310| `CLAUDE_ENABLE_BYTE_WATCHDOG` | 바이트 수준 스트리밍 유휴 감시견을 강제로 활성화하려면 `1`로 설정하거나, 강제로 비활성화하려면 `0`으로 설정합니다. 설정하지 않으면 감시견은 직접 Anthropic API 및 [Claude Platform on AWS](/ko/claude-platform-on-aws) 연결에 대해 기본적으로 활성화됩니다. 바이트 감시견은 `CLAUDE_STREAM_IDLE_TIMEOUT_MS`로 설정된 기간 동안 와이어에 바이트가 도착하지 않으면 연결을 중단합니다. 최소 5분이며 이벤트 수준 감시견과 독립적입니다. |

309| `CLAUDE_ENABLE_BYTE_WATCHDOG_BEDROCK` | Amazon Bedrock `vnd.amazon.eventstream` 응답에서 바이트 수준 스트리밍 유휴 감시견을 활성화하려면 `1`로 설정합니다. 기본적으로 꺼져 있습니다. `CLAUDE_STREAM_IDLE_TIMEOUT_MS`로 타임아웃을 구성합니다. |311| `CLAUDE_ENABLE_BYTE_WATCHDOG_BEDROCK` | Amazon Bedrock `vnd.amazon.eventstream` 응답에서 바이트 수준 스트리밍 유휴 감시견을 활성화하려면 `1`로 설정합니다. 기본적으로 꺼져 있습니다. `CLAUDE_STREAM_IDLE_TIMEOUT_MS`로 타임아웃을 구성합니다. |

310| `CLAUDE_ENABLE_STREAM_WATCHDOG` | 이벤트 수준 스트리밍 유휴 감시견을 강제로 활성화하려면 `1`로 설정하거나, 강제로 비활성화하려면 `0`으로 설정합니다.{/* min-version: 2.1.196 */}}설정하지 않으면 감시견은 모든 공급자에 대해 기본적으로 켜져 있습니다. v2.1.196 이전에는 설정하지 않은 기본값이 직접 Anthropic API에서 서버 제어이고 다른 공급자에서는 꺼져 있었습니다. {/* min-version: 2.1.169 */}}v2.1.169부터 직접 Anthropic API 및 Claude Platform on AWS 이외의 공급자도 `API_FORCE_IDLE_TIMEOUT`에 설명된 독립적인 5분 본문 유휴 타임아웃을 가집니다. Bedrock에서는 `CLAUDE_ENABLE_BYTE_WATCHDOG_BEDROCK=1`로 독립적인 바이트 수준 감시견을 활성화할 수도 있습니다. 둘 다 설정하면 함께 실행됩니다. `CLAUDE_STREAM_IDLE_TIMEOUT_MS`로 타임아웃을 구성합니다. |312| `CLAUDE_ENABLE_STREAM_WATCHDOG` | 이벤트 수준 스트리밍 유휴 감시견을 강제로 활성화하려면 `1`로 설정하거나, 강제로 비활성화하려면 `0`으로 설정합니다. {{/* min-version: 2.1.196 */}}설정하지 않으면 감시견은 모든 공급자에 대해 기본적으로 켜져 있습니다. v2.1.196 이전에는 설정하지 않은 기본값이 직접 Anthropic API에서 서버 제어이고 다른 공급자에서는 꺼져 있었습니다. {{/* min-version: 2.1.169 */}}v2.1.169부터 직접 Anthropic API 및 Claude Platform on AWS 이외의 공급자도 `API_FORCE_IDLE_TIMEOUT`에 설명된 독립적인 5분 본문 유휴 타임아웃을 가집니다. Amazon Bedrock에서는 `CLAUDE_ENABLE_BYTE_WATCHDOG_BEDROCK=1`로 독립적인 바이트 수준 감시견을 활성화할 수도 있습니다. 둘 다 설정하면 함께 실행됩니다. `CLAUDE_STREAM_IDLE_TIMEOUT_MS`로 타임아웃을 구성합니다. |

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

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

313| `CLAUDE_STREAM_IDLE_TIMEOUT_MS` | 스트리밍 유휴 감시견이 정체된 연결을 닫기 전의 타임아웃(밀리초). 설정하지 않으면 이벤트 수준 감시견은 기본값 300초이고 바이트 수준 감시견은 직접 Anthropic API 연결에서 기본값 180초입니다(Claude Platform on AWS 및 다른 공급자에서 300초). 설정하지 않은 180초 바이트 감시견 기본값은 별개의 값이며 5분 제한을 받지 않습니다. `API_FORCE_IDLE_TIMEOUT`에 설명된 본문 유휴 타임아웃은 독립적으로 적용됩니다. Bedrock에서는 `CLAUDE_ENABLE_BYTE_WATCHDOG_BEDROCK=1`일 때도 적용됩니다. |315| `CLAUDE_STREAM_IDLE_TIMEOUT_MS` | 스트리밍 유휴 감시견이 정체된 연결을 닫기 전의 타임아웃(밀리초). 설정하지 않으면 이벤트 수준 감시견은 기본값 300초이고 바이트 수준 감시견은 직접 Anthropic API 연결에서 기본값 180초입니다(Claude Platform on AWS 및 다른 공급자에서 300초). 설정하지 않은 180초 바이트 감시견 기본값은 별개의 값이며 5분 제한을 받지 않습니다. `API_FORCE_IDLE_TIMEOUT`에 설명된 본문 유휴 타임아웃은 독립적으로 적용됩니다. Amazon Bedrock에서는 `CLAUDE_ENABLE_BYTE_WATCHDOG_BEDROCK=1`일 때도 적용됩니다. |

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

316| `DISABLE_AUTO_COMPACT` | 컨텍스트 제한에 접근할 때 자동 압축을 비활성화하려면 `1`로 설정합니다. 수동 `/compact` 명령은 계속 사용 가능합니다. 압축이 발생하는 시기를 명시적으로 제어하려는 경우 사용합니다. |318| `DISABLE_AUTO_COMPACT` | 컨텍스트 제한에 접근할 때 자동 압축을 비활성화하려면 `1`로 설정합니다. 수동 `/compact` 명령은 계속 사용 가능합니다. 압축이 발생하는 시기를 명시적으로 제어하려는 경우 사용합니다. |

319| `DISABLE_DOCTOR_COMMAND` | `/doctor` 명령을 숨기려면 `1`로 설정합니다. 사용자가 설치 진단을 실행하지 않아야 하는 관리형 배포에 유용합니다. |321| `DISABLE_DOCTOR_COMMAND` | [`/doctor`](/ko/commands#all-commands) 설정 점검 skill 및 `/checkup` 별칭을 숨기려면 `1`로 설정합니다. 사용자가 설치 진단을 실행하지 않아야 하는 관리형 배포에 유용합니다. `claude doctor` 터미널 명령에는 영향을 주지 않습니다. {{/* min-version: 2.1.205 */}}v2.1.205 이전에는 이 변수가 `/doctor` 진단 화면 명령을 숨겼습니다. |

323| `DISABLE_GROWTHBOOK` | GrowthBook 기능 플래그 가져오기를 비활성화하려면 `1`로 설정합니다. 모든 플래그에 대해 코드 기본값을 사용합니다. 원격 분석 이벤트 로깅은 `DISABLE_TELEMETRY`도 설정되지 않으면 계속됩니다. |325| `DISABLE_GROWTHBOOK` | GrowthBook 기능 플래그 가져오기를 비활성화하려면 `1`로 설정합니다. 모든 플래그에 대해 코드 기본값을 사용합니다. 원격 분석 이벤트 로깅은 `DISABLE_TELEMETRY`도 설정되지 않으면 계속됩니다. |

325| `DISABLE_INSTALL_GITHUB_APP_COMMAND` | `/install-github-app` 명령을 숨기려면 `1`로 설정합니다. 타사 공급자(Bedrock, Vertex 또는 Foundry)를 사용할 때 이미 숨겨집니다. |327| `DISABLE_INSTALL_GITHUB_APP_COMMAND` | `/install-github-app` 명령을 숨기려면 `1`로 설정합니다. 타사 공급자(Amazon Bedrock, Google Cloud's Agent Platform, 또는 Microsoft Foundry)를 사용할 때 이미 숨겨집니다. |

326| `DISABLE_INTERLEAVED_THINKING` | interleaved-thinking 베타 헤더 전송을 방지하려면 `1`로 설정합니다. LLM 게이트웨이 또는 공급자가 [interleaved thinking](https://platform.claude.com/docs/en/build-with-claude/extended-thinking#interleaved-thinking)을 지원하지 않을 때 유용합니다. |328| `DISABLE_INTERLEAVED_THINKING` | interleaved-thinking 베타 헤더 전송을 방지하려면 `1`로 설정합니다. LLM 게이트웨이 또는 공급자가 [interleaved thinking](https://platform.claude.com/docs/en/build-with-claude/extended-thinking#interleaved-thinking)을 지원하지 않을 때 유용합니다. |

337| `DO_NOT_TRACK` | 원격 분석을 거부하려면 `1`로 설정합니다. `DISABLE_TELEMETRY` 설정과 동일합니다. Claude Code는 많은 개발자 CLI에서 인정하는 교차 도구 규칙으로 이를 존중합니다. |339| `DO_NOT_TRACK` | 원격 분석을 거부하려면 `1`로 설정합니다. `DISABLE_TELEMETRY` 설정과 동일합니다. Claude Code는 많은 개발자 CLI에서 인정하는 교차 도구 규칙으로 이를 존중합니다. |

338| `ENABLE_CLAUDEAI_MCP_SERVERS` | Claude Code에서 [claude.ai MCP 서버](/ko/mcp#use-mcp-servers-from-claude-ai)를 비활성화하려면 `false`로 설정합니다. 로그인한 사용자의 경우 기본적으로 활성화됩니다. 프로젝트별 또는 조직별로 비활성화하려면 설정 대신 [`disableClaudeAiConnectors`](/ko/settings#available-settings)를 설정합니다. |340| `ENABLE_CLAUDEAI_MCP_SERVERS` | Claude Code에서 [claude.ai MCP 서버](/ko/mcp#use-mcp-servers-from-claude-ai)를 비활성화하려면 `false`로 설정합니다. 로그인한 사용자의 경우 기본적으로 활성화됩니다. 프로젝트별 또는 조직별로 비활성화하려면 설정 대신 [`disableClaudeAiConnectors`](/ko/settings#available-settings)를 설정합니다. |

339| `ENABLE_PROMPT_CACHING_1H` | API 키, [Bedrock](/ko/amazon-bedrock), [Vertex](/ko/google-vertex-ai), [Foundry](/ko/microsoft-foundry), [Claude Platform on AWS](/ko/claude-platform-on-aws) 사용자를 위해 기본 5분 대신 1시간 [프롬프트 캐시 TTL](/ko/prompt-caching#cache-lifetime)을 요청하려면 `1`로 설정합니다. 구독 사용자는 자동으로 1시간 TTL을 받습니다. 1시간 캐시 쓰기는 더 높은 요금으로 청구됩니다. |341| `ENABLE_PROMPT_CACHING_1H` | API 키, [Amazon Bedrock](/ko/amazon-bedrock), [Google Cloud's Agent Platform](/ko/google-vertex-ai), [Microsoft Foundry](/ko/microsoft-foundry), [Claude Platform on AWS](/ko/claude-platform-on-aws) 사용자를 위해 기본 5분 대신 1시간 [프롬프트 캐시 TTL](/ko/prompt-caching#cache-lifetime)을 요청하려면 `1`로 설정합니다. 구독 사용자는 자동으로 1시간 TTL을 받습니다. 1시간 캐시 쓰기는 더 높은 요금으로 청구됩니다. |

341| `ENABLE_TOOL_SEARCH` | [MCP 도구 검색](/ko/mcp#scale-with-mcp-tool-search)을 제어합니다. 설정 해제: 모든 MCP 도구는 기본적으로 연기되지만 Vertex AI에서 또는 `ANTHROPIC_BASE_URL`이 비자사 호스트를 가리킬 때 미리 로드됩니다. 값: `true`(항상 연기 및 베타 헤더 전송, Vertex AI 모델 Sonnet 4.5 또는 Opus 4.5보다 이전 또는 `tool_reference`를 지원하지 않는 프록시에서 요청 실패), `auto`(임계값 모드: 도구가 컨텍스트의 10% 이내에 맞으면 미리 로드), `auto:N`(사용자 정의 임계값, 예: 5%의 경우 `auto:5`), `false`(모두 미리 로드) |343| `ENABLE_TOOL_SEARCH` | [MCP 도구 검색](/ko/mcp#scale-with-mcp-tool-search)을 제어합니다. 설정 해제: 모든 MCP 도구는 기본적으로 연기되지만 Google Cloud's Agent Platform에서 또는 `ANTHROPIC_BASE_URL`이 비자사 호스트를 가리킬 때 미리 로드됩니다. 값: `true`(항상 연기 및 베타 헤더 전송, Google Cloud's Agent Platform 모델 Sonnet 4.5 또는 Opus 4.5보다 이전 또는 `tool_reference`를 지원하지 않는 프록시에서 요청 실패), `auto`(임계값 모드: 도구가 컨텍스트의 10% 이내에 맞으면 미리 로드), `auto:N`(사용자 정의 임계값, 예: 5%의 경우 `auto:5`), `false`(모두 미리 로드) |

342| `FALLBACK_FOR_ALL_PRIMARY_MODELS` | 모든 기본 모델에서 반복된 과부하 오류 후 폴백을 트리거하려면 비어 있지 않은 값으로 설정합니다. {/* min-version: 2.1.160 */}v2.1.160부터 구성된 [폴백 모델 체인](/ko/model-config#fallback-model-chains)은 모든 기본 모델에 대해 반복된 과부하 오류에서 트리거되므로 이 변수는 폴백 모델로 전환하는 데 영향을 주지 않습니다. |344| `FALLBACK_FOR_ALL_PRIMARY_MODELS` | 모든 기본 모델에서 반복된 과부하 오류 후 폴백을 트리거하려면 비어 있지 않은 값으로 설정합니다. {{/* min-version: 2.1.160 */}}v2.1.160부터 구성된 [폴백 모델 체인](/ko/model-config#fallback-model-chains)은 모든 기본 모델에 대해 반복된 과부하 오류에서 트리거되므로 이 변수는 폴백 모델로 전환하는 데 영향을 주지 않습니다. |

349| `MAX_STRUCTURED_OUTPUT_RETRIES` | 비대화형 모드(`-p` 플래그)에서 모델의 응답이 [`--json-schema`](/ko/cli-reference#cli-flags)에 대한 유효성 검사에 실패할 때 재시도할 횟수입니다. 기본값은 5입니다. |351| `MAX_STRUCTURED_OUTPUT_RETRIES` | 비대화형 모드(`-p` 플래그)에서 모델의 응답이 [`--json-schema`](/ko/cli-reference#cli-flags)에 대한 유효성 검사에 실패할 때 재시도할 횟수입니다. 기본값은 5입니다. |

350| `MAX_THINKING_TOKENS` | [확장 사고](https://platform.claude.com/docs/en/build-with-claude/extended-thinking) 토큰 예산을 재정의합니다. 상한은 모델의 [최대 출력 토큰](https://platform.claude.com/docs/en/about-claude/models/overview#latest-models-comparison)에서 1을 뺀 값입니다. `0`으로 설정하여 Anthropic API에서 사고를 비활성화합니다. Fable 5는 사고를 끌 수 없으므로 이는 효과가 없습니다. [타사 공급자](/ko/third-party-integrations)에서 `0`은 마찬가지로 매개변수를 생략하므로 [적응형 추론](/ko/model-config#adjust-effort-level)이 있는 모델은 여전히 생각할 수 있습니다. 0이 아닌 값의 경우 적응형 추론 모델에서 `CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING`을 통해 적응형 추론이 비활성화되지 않으면 예산이 무시됩니다. |352| `MAX_THINKING_TOKENS` | [확장 사고](https://platform.claude.com/docs/en/build-with-claude/extended-thinking) 토큰 예산을 재정의합니다. 상한은 모델의 [최대 출력 토큰](https://platform.claude.com/docs/en/about-claude/models/overview#latest-models-comparison)에서 1을 뺀 값입니다. `0`으로 설정하여 Anthropic API에서 사고를 비활성화합니다. Fable 5는 사고를 끌 수 없으므로 이는 효과가 없습니다. [타사 공급자](/ko/third-party-integrations)에서 `0`은 마찬가지로 매개변수를 생략하므로 [적응형 추론](/ko/model-config#adjust-effort-level)이 있는 모델은 여전히 생각할 수 있습니다. 0이 아닌 값의 경우 적응형 추론 모델에서 `CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING`을 통해 적응형 추론이 비활성화되지 않으면 예산이 무시됩니다. |

351| `MCP_CLIENT_SECRET` | [사전 구성된 자격 증명](/ko/mcp#use-pre-configured-oauth-credentials)이 필요한 MCP 서버의 OAuth 클라이언트 시크릿입니다. `--client-secret`으로 서버를 추가할 때 대화형 프롬프트를 방지합니다. |353| `MCP_CLIENT_SECRET` | [사전 구성된 자격 증명](/ko/mcp#use-pre-configured-oauth-credentials)이 필요한 MCP 서버의 OAuth 클라이언트 시크릿입니다. `--client-secret`으로 서버를 추가할 때 대화형 프롬프트를 방지합니다. |

352| `MCP_CONNECTION_NONBLOCKING` | 시작이 첫 번째 쿼리 전에 MCP 서버 연결을 기다리는지 여부를 제어합니다. {/* min-version: 2.1.142 */}Claude Code v2.1.142부터 MCP 시작은 기본적으로 비블로킹입니다: 서버는 백그라운드에서 연결되고 완료되면 도구를 사용할 수 있게 됩니다. `0`으로 설정하여 블로킹 5초 연결 대기를 복원합니다. [`alwaysLoad: true`](/ko/mcp#exempt-a-server-from-deferral)로 구성된 서버는 도구가 첫 번째 프롬프트를 빌드할 때 존재해야 하므로 이 변수와 관계없이 항상 시작을 차단합니다. |354| `MCP_CONNECTION_NONBLOCKING` | 시작이 첫 번째 쿼리 전에 MCP 서버 연결을 기다리는지 여부를 제어합니다. {{/* min-version: 2.1.142 */}}Claude Code v2.1.142부터 MCP 시작은 기본적으로 비블로킹입니다: 서버는 백그라운드에서 연결되고 완료되면 도구를 사용할 수 있게 됩니다. `0`으로 설정하여 블로킹 5초 연결 대기를 복원합니다. [`alwaysLoad: true`](/ko/mcp#exempt-a-server-from-deferral)로 구성된 서버는 도구가 첫 번째 프롬프트를 빌드할 때 존재해야 하므로 이 변수와 관계없이 항상 시작을 차단합니다. |

353| `MCP_CONNECT_TIMEOUT_MS` | 블로킹 MCP 시작이 연결 배치를 기다리는 시간(밀리초)을 설정하고 도구 목록을 스냅샷하기 전입니다(기본값: 5000). [`alwaysLoad: true`](/ko/mcp#exempt-a-server-from-deferral)로 표시된 서버에 적용됩니다. 마감 시점에 여전히 보류 중인 서버는 백그라운드에서 계속 연결되지만 다음 쿼리까지 나타나지 않습니다. `MCP_TIMEOUT`과 다르며, 이는 개별 서버의 연결 시도를 제한합니다. |355| `MCP_CONNECT_TIMEOUT_MS` | 블로킹 MCP 시작이 연결 배치를 기다리는 시간(밀리초)을 설정하고 도구 목록을 스냅샷하기 전입니다(기본값: 5000). [`alwaysLoad: true`](/ko/mcp#exempt-a-server-from-deferral)로 표시된 서버에 적용됩니다. 마감 시점에 여전히 보류 중인 서버는 백그라운드에서 계속 연결되지만 다음 쿼리까지 나타나지 않습니다. `MCP_TIMEOUT`과 다르며, 이는 개별 서버의 연결 시도를 제한합니다. |

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

358| `MCP_TOOL_TIMEOUT` | MCP 도구 실행의 타임아웃(밀리초)(기본값: 100000000, 약 28시간). 서버별 `.mcp.json`의 `timeout` 필드가 해당 서버에 대해 이를 재정의합니다. 환경 변수의 경우 1000 미만의 값은 1초로 내림됩니다. 서버별 필드의 경우 1000 미만의 값은 무시됩니다. |360| `MCP_TOOL_TIMEOUT` | MCP 도구 실행의 타임아웃(밀리초)(기본값: 100000000, 약 28시간). 서버별 `.mcp.json`의 `timeout` 필드가 해당 서버에 대해 이를 재정의합니다. {{/* min-version: 2.1.203 */}}서버별 `timeout`이 최소 1000이면 해당 서버의 도구 호출에 대한 최소 유휴 윈도우를 설정하므로 `CLAUDE_CODE_MCP_TOOL_IDLE_TIMEOUT`이 더 빨리 중단하지 않습니다. 이 하한은 Claude Code v2.1.203 이상이 필요합니다. 환경 변수의 경우 1000 미만의 값은 1초로 내림됩니다. 서버별 필드의 경우 1000 미만의 값은 무시됩니다. |

360| `OTEL_LOG_ASSISTANT_RESPONSES` | {/* min-version: 2.1.193 */}}모델의 응답 텍스트를 `assistant_response` OpenTelemetry 로그 이벤트에 포함하려면 `1`로 설정합니다. 설정하지 않으면 `OTEL_LOG_USER_PROMPTS`의 값이 사용됩니다. `OTEL_LOG_USER_PROMPTS`가 설정된 경우에도 응답을 수정된 상태로 유지하려면 `0`으로 설정합니다. Claude Code v2.1.193 이상이 필요합니다. [모니터링](/ko/monitoring-usage#assistant-response-event) 참조 |362| `OTEL_LOG_ASSISTANT_RESPONSES` | {{/* min-version: 2.1.193 */}}모델의 응답 텍스트를 `assistant_response` OpenTelemetry 로그 이벤트에 포함하려면 `1`로 설정합니다. 설정하지 않으면 `OTEL_LOG_USER_PROMPTS`의 값이 사용됩니다. `OTEL_LOG_USER_PROMPTS`가 설정된 경우에도 응답을 수정된 상태로 유지하려면 `0`으로 설정합니다. Claude Code v2.1.193 이상이 필요합니다. [모니터링](/ko/monitoring-usage#assistant-response-event) 참조 |

361| `OTEL_LOG_RAW_API_BODIES` | Anthropic Messages API 요청 및 응답 JSON을 `api_request_body` / `api_response_body` 로그 이벤트로 내보냅니다. 60KB에서 잘린 인라인 본문의 경우 `1`로 설정하거나, 잘리지 않은 본문을 디스크에 쓰고 `body_ref` 경로를 내보내려면 `file:<dir>`로 설정합니다. 기본적으로 비활성화됩니다. 본문에는 전체 대화 기록이 포함됩니다. [모니터링](/ko/monitoring-usage#api-request-body-event) 참조 |363| `OTEL_LOG_RAW_API_BODIES` | Anthropic Messages API 요청 및 응답 JSON을 `api_request_body` / `api_response_body` 로그 이벤트로 내보냅니다. 60KB에서 잘린 인라인 본문의 경우 `1`로 설정하거나, 잘리지 않은 본문을 디스크에 쓰고 `body_ref` 경로를 내보내려면 `file:<dir>`로 설정합니다. 기본적으로 비활성화됩니다. 본문에는 전체 대화 기록이 포함됩니다. [모니터링](/ko/monitoring-usage#api-request-body-event) 참조 |

362| `OTEL_LOG_TOOL_CONTENT` | 도구 입력 및 출력 내용을 OpenTelemetry 스팬 이벤트에 포함하려면 `1`로 설정합니다. 민감한 데이터를 보호하기 위해 기본적으로 비활성화됩니다. [모니터링](/ko/monitoring-usage) 참조 |364| `OTEL_LOG_TOOL_CONTENT` | 도구 입력 및 출력 내용을 OpenTelemetry 스팬 이벤트에 포함하려면 `1`로 설정합니다. 민감한 데이터를 보호하기 위해 기본적으로 비활성화됩니다. [모니터링](/ko/monitoring-usage) 참조 |

363| `OTEL_LOG_TOOL_DETAILS` | 도구 입력 인수, MCP 서버 이름, 도구 실패 시 원본 오류 문자열, 기타 도구 세부 정보를 OpenTelemetry 추적 및 로그에 포함하려면 `1`로 설정합니다. PII를 보호하기 위해 기본적으로 비활성화됩니다. [모니터링](/ko/monitoring-usage) 참조 |365| `OTEL_LOG_TOOL_DETAILS` | 도구 입력 인수, MCP 서버 이름, 사용자 작성 워크플로우 이름, 도구 실패 시 원본 오류 문자열, `api_refusal` 이벤트의 거부 `category`, 기타 도구 세부 정보를 OpenTelemetry 추적 및 로그에 포함하려면 `1`로 설정합니다. PII를 보호하기 위해 기본적으로 비활성화됩니다. [모니터링](/ko/monitoring-usage) 참조 |

364| `OTEL_LOG_USER_PROMPTS` | 사용자 프롬프트 텍스트를 OpenTelemetry 추적 및 로그에 포함하려면 `1`로 설정합니다. 기본적으로 비활성화됩니다(프롬프트는 수정됨). [모니터링](/ko/monitoring-usage) 참조 |366| `OTEL_LOG_USER_PROMPTS` | 사용자 프롬프트 텍스트를 OpenTelemetry 추적 및 로그에 포함하려면 `1`로 설정합니다. 기본적으로 비활성화됩니다(프롬프트는 수정됨). [모니터링](/ko/monitoring-usage) 참조 |

366| `OTEL_METRICS_INCLUDE_ENTRYPOINT` | {/* min-version: 2.1.152 */}메트릭 속성에 세션 진입점을 포함하려면 `true`로 설정합니다(기본값: 제외). v2.1.152에서 추가됨. [모니터링](/ko/monitoring-usage) 참조 |368| `OTEL_METRICS_INCLUDE_ENTRYPOINT` | {{/* min-version: 2.1.152 */}}메트릭 속성에 세션 진입점을 포함하려면 `true`로 설정합니다(기본값: 제외). v2.1.152에서 추가됨. [모니터링](/ko/monitoring-usage) 참조 |

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

370| `SLASH_COMMAND_TOOL_CHAR_BUDGET` | [Skill 도구](/ko/skills#control-who-invokes-a-skill)에 표시되는 skill 메타데이터의 문자 예산을 재정의합니다. 예산은 컨텍스트 윈도우의 1%에서 동적으로 확장되며, 8,000자의 폴백이 있습니다. 이전 버전과의 호환성을 위해 레거시 이름이 유지됩니다. |372| `SLASH_COMMAND_TOOL_CHAR_BUDGET` | [Skill 도구](/ko/skills#control-who-invokes-a-skill)에 표시되는 skill 메타데이터의 문자 예산을 재정의합니다. 예산은 컨텍스트 윈도우의 1%에서 동적으로 확장되며, 8,000자의 폴백이 있습니다. 이전 버전과의 호환성을 위해 레거시 이름이 유지됩니다. |

371| `TASK_MAX_OUTPUT_LENGTH` | 잘림 전 [subagent](/ko/sub-agents) 출력의 최대 문자 수(기본값: 32000, 최대: 160000). 잘림 시 전체 출력이 디스크에 저장되고 경로가 잘린 응답에 포함됩니다. |373| `TASK_MAX_OUTPUT_LENGTH` | 잘림 전 [subagent](/ko/sub-agents) 출력의 최대 문자 수(기본값: 32000, 최대: 160000). 잘림 시 전체 출력이 디스크에 저장되고 경로가 잘린 응답에 포함됩니다. |

383| `VERTEX_REGION_CLAUDE_4_7_OPUS` | {/* min-version: 2.1.111 */}Vertex AI 사용 시 Claude Opus 4.7의 리전을 재정의합니다. v2.1.111에서 추가됨. |385| `VERTEX_REGION_CLAUDE_4_7_OPUS` | {{/* min-version: 2.1.111 */}}Google Cloud's Agent Platform 사용 시 Claude Opus 4.7의 리전을 재정의합니다. v2.1.111에서 추가됨. |

384| `VERTEX_REGION_CLAUDE_4_8_OPUS` | {/* min-version: 2.1.154 */}Vertex AI 사용 시 Claude Opus 4.8의 리전을 재정의합니다. v2.1.154에서 추가됨. |386| `VERTEX_REGION_CLAUDE_4_8_OPUS` | {{/* min-version: 2.1.154 */}}Google Cloud's Agent Platform 사용 시 Claude Opus 4.8의 리전을 재정의합니다. v2.1.154에서 추가됨. |

385| `VERTEX_REGION_CLAUDE_5_SONNET` | {/* min-version: 2.1.197 */}Vertex AI 사용 시 Claude Sonnet 5의 리전을 재정의합니다. v2.1.197에서 추가됨. |387| `VERTEX_REGION_CLAUDE_5_SONNET` | {{/* min-version: 2.1.197 */}}Google Cloud's Agent Platform 사용 시 Claude Sonnet 5의 리전을 재정의합니다. v2.1.197에서 추가됨. |

386| `VERTEX_REGION_CLAUDE_FABLE_5` | {/* min-version: 2.1.170 */}Vertex AI 사용 시 Claude Fable 5의 리전을 재정의합니다. v2.1.170에서 추가됨. |388| `VERTEX_REGION_CLAUDE_FABLE_5` | {{/* min-version: 2.1.170 */}}Google Cloud's Agent Platform 사용 시 Claude Fable 5의 리전을 재정의합니다. v2.1.170에서 추가됨. |

388 390

389표준 OpenTelemetry 내보내기 변수(`OTEL_METRICS_EXPORTER`, `OTEL_LOGS_EXPORTER`, `OTEL_EXPORTER_OTLP_ENDPOINT`, `OTEL_EXPORTER_OTLP_PROTOCOL`, `OTEL_EXPORTER_OTLP_HEADERS`, `OTEL_METRIC_EXPORT_INTERVAL`, `OTEL_RESOURCE_ATTRIBUTES` 및 신호별 변형)도 지원됩니다. 구성 세부 정보는 [모니터링](/ko/monitoring-usage)을 참조합니다.391표준 OpenTelemetry 내보내기 변수(`OTEL_METRICS_EXPORTER`, `OTEL_LOGS_EXPORTER`, `OTEL_EXPORTER_OTLP_ENDPOINT`, `OTEL_EXPORTER_OTLP_PROTOCOL`, `OTEL_EXPORTER_OTLP_HEADERS`, `OTEL_METRIC_EXPORT_INTERVAL`, `OTEL_RESOURCE_ATTRIBUTES` 및 신호별 변형)도 지원됩니다. 구성 세부 정보는 [모니터링](/ko/monitoring-usage)을 참조합니다.

390 392

errors.md +507 −303

Details

53| `SSL certificate verification failed` | [네트워크](#ssl-certificate-errors) |53| `SSL certificate verification failed` | [네트워크](#ssl-certificate-errors) |

54| `SSL certificate error (...)` during login or startup | [네트워크](#ssl-certificate-errors) |54| `SSL certificate error (...)` during login or startup | [네트워크](#ssl-certificate-errors) |

55| `403` with `x-deny-reason: host_not_allowed` in a cloud or routine session | [네트워크](#host-not-allowed-in-a-cloud-session) |55| `403` with `x-deny-reason: host_not_allowed` in a cloud or routine session | [네트워크](#host-not-allowed-in-a-cloud-session) |

56| `Couldn't reconnect to your Remote Control session` | [네트워크](#couldn%E2%80%99t-reconnect-to-your-remote-control-session) |

56| `Prompt is too long` | [요청 오류](#prompt-is-too-long) |57| `Prompt is too long` | [요청 오류](#prompt-is-too-long) |

57| `Error during compaction: Conversation too long` | [요청 오류](#error-during-compaction-conversation-too-long) |58| `Error during compaction: Conversation too long` | [요청 오류](#error-during-compaction-conversation-too-long) |

58| `Request too large` | [요청 오류](#request-too-large) |59| `Request too large` | [요청 오류](#request-too-large) |

61| `PDF too large` / `PDF is password protected` | [요청 오류](#pdf-errors) |62| `PDF too large` / `PDF is password protected` | [요청 오류](#pdf-errors) |

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

63| `There's an issue with the selected model` | [요청 오류](#there%E2%80%99s-an-issue-with-the-selected-model) |64| `There's an issue with the selected model` | [요청 오류](#there%E2%80%99s-an-issue-with-the-selected-model) |

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

64| `Claude Opus is not available with the Claude Pro plan` | [요청 오류](#claude-opus-is-not-available-with-the-claude-pro-plan) |66| `Claude Opus is not available with the Claude Pro plan` | [요청 오류](#claude-opus-is-not-available-with-the-claude-pro-plan) |

65| `Model ... is restricted by your organization's settings` | [요청 오류](#model-is-restricted-by-your-organization%E2%80%99s-settings) |67| `Model ... is restricted by your organization's settings` | [요청 오류](#model-is-restricted-by-your-organization%E2%80%99s-settings) |

66| `thinking.type.enabled is not supported for this model` | [요청 오류](#thinking-type-enabled-is-not-supported-for-this-model) |68| `thinking.type.enabled is not supported for this model` | [요청 오류](#thinking-type-enabled-is-not-supported-for-this-model) |

67| `max_tokens must be greater than thinking.budget_tokens` | [요청 오류](#thinking-budget-exceeds-output-limit) |69| `max_tokens must be greater than thinking.budget_tokens` | [요청 오류](#thinking-budget-exceeds-output-limit) |

68| `API Error: 400 due to tool use concurrency issues` | [요청 오류](#tool-use-or-thinking-block-mismatch) |70| `API Error: 400 due to tool use concurrency issues` | [요청 오류](#tool-use-or-thinking-block-mismatch) |

69| `Claude Code is unable to respond to this request, which appears to violate our Usage Policy` | [요청 오류](#usage-policy-refusal) |71| `Claude Code is unable to respond to this request, which appears to violate our Usage Policy` | [요청 오류](#usage-policy-refusal) |

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

73| `Installation was killed before it could finish (exit code 137)` | [설치 오류](#installation-was-killed-before-it-could-finish) |

74| `The connection dropped while downloading the update` | [설치 오류](#the-connection-dropped-while-downloading-the-update) |

75| `Download timed out: exceeded the total deadline` | [설치 오류](#the-connection-dropped-while-downloading-the-update) |

70| `--bg and --print conflict` | [명령줄 오류](#command-line-errors) |76| `--bg and --print conflict` | [명령줄 오류](#command-line-errors) |

77| `Error: --json-schema is not a valid JSON Schema` | [명령줄 오류](#command-line-errors) |

78| `Could not import <server>: <reason>` | [명령줄 오류](#could-not-import-a-server-from-claude-desktop) |

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

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

71| Responses seem lower quality than usual | [응답 품질](#responses-seem-lower-quality-than-usual) |81| Responses seem lower quality than usual | [응답 품질](#responses-seem-lower-quality-than-usual) |

72 82

73<h2 id="automatic-retries">83<h2 id="automatic-retries">

99 서버 오류109 서버 오류

100</h2>110</h2>

101 111

102이러한 오류는 계정이나 요청이 아닌 추론 제공자에서 발생합니다. Anthropic API의 경우 Anthropic 인프라를 의미합니다. Bedrock, Vertex AI, Foundry 또는 사용자 정의 게이트웨이의 경우 해당 제공자의 인프라를 의미합니다.112이러한 오류는 사용자의 계정이나 요청이 아닌 추론 제공자로부터 발생합니다. Anthropic API의 경우 Anthropic 인프라를 의미합니다. Amazon Bedrock, Google Cloud의 Agent Platform, Microsoft Foundry 또는 사용자 정의 게이트웨이의 경우 해당 제공자의 인프라를 의미합니다.

103 113

104<h3 id="api-error-500-internal-server-error">114<h3 id="api-error-500-internal-server-error">

105 API Error: 500 Internal server error115 API 오류: 500 내부 서버 오류

106</h3>116</h3>

107 117

108Claude Code는 모든 5xx 응답에 대해 상태 코드와 API의 오류 메시지를 표시합니다. 아래 예제는 Anthropic API의 500 응답을 보여줍니다.118Claude Code는 모든 5xx 응답에 대해 상태 코드와 API의 오류 메시지를 표시합니다. 아래 예제는 Anthropic API의 500 응답을 보여줍니다:

109 119

110```text theme={null}120```text theme={null}

111API Error: 500 Internal server error. This is a server-side issue, usually temporary — try again in a moment. If it persists, check https://status.claude.com.121API Error: 500 Internal server error. This is a server-side issue, usually temporary — try again in a moment. If it persists, check https://status.claude.com.

112```122```

113 123

114뒤따르는 문장은 서비스 상태를 확인할 위치를 나타내며 제공자에 따라 다릅니다. Bedrock, Vertex AI 및 Foundry 구성은 해당 제공자의 서비스 상태를 나타냅니다. 사용자 정의 `ANTHROPIC_BASE_URL`은 게이트웨이 호스트를 나타냅니다.124뒤따르는 문장은 서비스 상태를 확인할 위치를 나타내며 제공자에 따라 다릅니다. Amazon Bedrock, Google Cloud의 Agent Platform 및 Microsoft Foundry 구성은 해당 제공자의 서비스 상태를 나타냅니다. 사용자 정의 `ANTHROPIC_BASE_URL`은 게이트웨이 호스트를 나타냅니다.

115 125

116이는 API 내부의 예기치 않은 오류를 나타냅니다. 프롬프트, 설정 또는 계정으로 인한 것이 아닙니다.126이는 API 내부의 예기치 않은 실패를 나타냅니다. 사용자의 프롬프트, 설정 또는 계정으로 인해 발생하지 않습니다.

117 127

118**할 일:**128**수행할 작업:**

119 129

120* [status.claude.com](https://status.claude.com) 또는 메시지에 나열된 제공자 상태 페이지에서 활성 인시던트 확인130* [status.claude.com](https://status.claude.com) 또는 메시지에 명시된 제공자 상태 페이지에서 활성 인시던트를 확인합니다

121* 1분 기다린 후 메시지를 다시 보냅니다. 원본 메시지는 여전히 대화에 있으므로 긴 프롬프트의 경우 전체를 다시 붙여넣는 대신 `try again`을 입력할 수 있습니다.131* 1분 정도 기다린 후 메시지를 다시 보냅니다. 원본 메시지는 여전히 대화에 남아 있으므로 긴 프롬프트의 경우 전체 내용을 붙여넣는 대신 `try again`을 입력할 수 있습니다.

122* 게시된 인시던트가 없는데도 오류가 지속되면 `/feedback`을 실행하여 Anthropic이 요청 세부 정보로 조사할 수 있도록 합니다. 환경에서 `/feedback`을 사용할 수 없는 경우 [오류 보고](#report-an-error)를 참조하십시오.132* 게시된 인시던트가 없는데도 오류가 계속되면 `/feedback`을 실행하여 Anthropic이 요청 세부 정보로 조사할 수 있도록 합니다. 환경에서 `/feedback`을 사용할 수 없는 경우 [오류 보고](#report-an-error)를 참조하세요.

123 133

124<h3 id="api-error-repeated-529-overloaded-errors">134<h3 id="api-error-repeated-529-overloaded-errors">

125 API Error: Repeated 529 Overloaded errors135 API 오류: 반복된 529 과부하 오류

126</h3>136</h3>

127 137

128API가 모든 사용자에게 일시적으로 용량이 가득 찼습니다. Claude Code는 이 메시지를 표시하기 전에 이미 여러 번 재시도했습니다.138API가 모든 사용자에게 일시적으로 용량 부족 상태입니다. Claude Code는 이 메시지를 표시하기 전에 이미 여러 번 재시도했습니다:

129 139

130```text theme={null}140```text theme={null}

131API Error: Repeated 529 Overloaded errors. The API is at capacity — this is usually temporary. Try again in a moment. If it persists, check https://status.claude.com.141API Error: Repeated 529 Overloaded errors. The API is at capacity — this is usually temporary. Try again in a moment. If it persists, check https://status.claude.com.

133 143

134뒤따르는 문장은 500 오류와 동일한 방식으로 제공자에 따라 다릅니다.144뒤따르는 문장은 500 오류와 동일한 방식으로 제공자에 따라 다릅니다.

135 145

136529는 사용 제한이 아니며 할당량에 대해 계산되지 않습니다.146529는 사용자의 사용 한도가 아니며 할당량에 포함되지 않습니다.

137 147

138**할 일:**148**수행할 작업:**

139 149

140* [status.claude.com](https://status.claude.com) 또는 메시지에 나열된 제공자 상태 페이지에서 용량 공지 확인150* [status.claude.com](https://status.claude.com) 또는 메시지에 명시된 제공자 상태 페이지에서 용량 공지를 확인합니다

141* 몇 분 후 다시 시도151* 몇 분 후에 다시 시도합니다

142* `/model`을 실행하고 다른 모델로 전환하여 계속 작업합니다. 용량은 모델별로 추적되기 때문입니다. Claude Code는 한 모델이 특히 높은 부하를 받을 때 이를 수행하도록 프롬프트합니다. 예를 들어 `Opus is experiencing high load, please use /model to switch to Sonnet`.152* `/model`을 실행하고 다른 모델로 전환하여 계속 작업합니다. 용량은 모델별로 추적되기 때문입니다. Claude Code는 한 모델이 특히 높은 부하를 받을 때 이를 수행하도록 사용자에게 알립니다. 예를 들어 `Opus is experiencing high load, please use /model to switch to Sonnet`과 같습니다.

143 153

144<h3 id="request-timed-out">154<h3 id="request-timed-out">

145 Request timed out155 요청 시간 초과

146</h3>156</h3>

147 157

148API가 연결 기한 전에 응답하지 않았습니다.158API가 연결 마감 시간 전에 응답하지 않았습니다.

149 159

150```text theme={null}160```text theme={null}

151Request timed out161Request timed out

152```162```

153 163

154이는 높은 부하 기간 또는 매우 큰 응답이 생성될 때 발생할 수 있습니다. 기본 요청 시간 초과는 10분입니다.164이는 높은 부하 기간 동안 또는 모델이 매우 큰 응답을 생성할 때 발생할 수 있습니다. 기본 요청 시간 초과는 10분입니다.

155 165

156**할 일:**166**수행할 작업:**

157 167

158* 요청 재시도168* 요청을 다시 시도합니다

159* 장기 실행 작업의 경우 작업을 더 작은 프롬프트로 나눕니다.169* 장기 실행 작업의 경우 작업을 더 작은 프롬프트로 나눕니다

160* 느린 네트워크 또는 프록시가 원인인 경우 [자동 재시도](#automatic-retries)에 설명된 대로 `API_TIMEOUT_MS`를 높입니다.170* 느린 네트워크 또는 프록시가 원인인 경우 [자동 재시도](#automatic-retries)에 설명된 대로 `API_TIMEOUT_MS`를 높입니다

161* 시간 초과가 자주 발생하고 네트워크가 정상인 경우 아래 [네트워크 및 연결 오류](#network-and-connection-errors)를 참조하십시오.171* 시간 초과가 자주 발생하고 네트워크가 정상인 경우 아래의 [네트워크 및 연결 오류](#network-and-connection-errors)를 참조하세요

162 172

163<h3 id="the-response-above-may-be-incomplete">173<h3 id="the-response-above-may-be-incomplete">

164 The response above may be incomplete174 위의 응답이 불완전할 수 있습니다

165</h3>175</h3>

166 176

167스트리밍 응답이 Claude가 이미 표시되는 출력을 생성한 후 실패했습니다. 요청을 다시 보내면 동일한 도구 호출을 두 번 실행할 수 있으므로 Claude Code는 이미 스트리밍된 것을 유지하고 턴을 버리는 대신 이 공지를 추가합니다. 표시되는 변형은 원인을 나타냅니다.177스트리밍 응답이 Claude가 이미 표시 가능한 출력을 생성한 후 실패했습니다. 요청을 다시 보내면 동일한 도구 호출이 두 번 실행될 수 있으므로 Claude Code는 이미 스트리밍된 내용을 유지하고 대신 이 공지를 추가합니다. 표시되는 변형은 원인을 나타냅니다:

168 178

169```text theme={null}179```text theme={null}

170API Error: Server error mid-response. The response above may be incomplete.180API Error: Server error mid-response. The response above may be incomplete.

172API Error: Response stalled mid-stream. The response above may be incomplete.182API Error: Response stalled mid-stream. The response above may be incomplete.

173```183```

174 184

175* {/* min-version: 2.1.199 */}}`Server error mid-response`: 스트림 중간 과부하 또는 5xx 서버 오류입니다. 이 변형은 Claude Code v2.1.199 이상이 필요합니다. 그 전에는 부분 출력을 버리고 전체 턴을 오류로 보고했습니다.185* {/* min-version: 2.1.199 */}}`Server error mid-response`: 스트림 중간의 과부하 또는 5xx 서버 오류입니다. 이 변형은 Claude Code v2.1.199 이상이 필요합니다. 그 이전에는 부분 출력을 버리고 전체 턴을 오류로 보고했습니다.

176* `Connection closed mid-response`: 연결이 끊어졌습니다.186* `Connection closed mid-response`: 연결이 끊어졌습니다.

177* `Response stalled mid-stream`: 스트림이 데이터 전송을 중지했습니다.187* `Response stalled mid-stream`: 스트림이 데이터 전송을 중지했습니다.

178 188

179**할 일:**189**수행할 작업:**

180 190

181* 스트리밍된 응답을 읽습니다. 아무것도 손실되지 않았지만 마지막 문장이나 도구 호출이 누락될 수 있습니다.191* 스트리밍된 응답을 읽습니다. 아무것도 손실되지 않았지만 마지막 문장이나 도구 호출이 누락되었을 수 있습니다.

182* `continue`로 회신하여 Claude가 중단된 위치에서 계속하도록 합니다.192* `continue`로 회신하여 Claude가 중단된 위치에서 계속하도록 합니다

183* 표시되는 출력 전에 동일한 오류가 나타나면 Claude Code는 이를 완료하는 대신 요청을 재시도합니다. [자동 재시도](#automatic-retries)를 참조하십시오.193* 표시 가능한 출력이 없기 전에 동일한 오류가 나타나면 Claude Code는 완료하지 않고 요청을 재시도합니다. [자동 재시도](#automatic-retries)를 참조하세요.

184 194

185<h3 id="auto-mode-cannot-determine-the-safety-of-an-action">195<h3 id="auto-mode-cannot-determine-the-safety-of-an-action">

186 Auto mode cannot determine the safety of an action196 자동 모드가 작업의 안전성을 결정할 수 없습니다

187</h3>197</h3>

188 198

189[자동 모드](/ko/permission-modes#eliminate-prompts-with-auto-mode)가 작업을 분류하는 데 사용하는 모델이 결정을 생성할 수 없어서 자동 모드가 작업을 자동으로 승인하지 않았습니다. 표시되는 메시지는 분류기가 실패한 이유에 따라 다릅니다.199[자동 모드](/ko/permission-modes#eliminate-prompts-with-auto-mode)가 작업을 분류하는 데 사용하는 모델이 결정을 내릴 수 없어서 자동 모드가 작업을 자동으로 승인하지 않았습니다. 표시되는 메시지는 분류자가 실패한 이유에 따라 다릅니다.

190 200

191작업 디렉토리 내의 읽기, 검색 및 편집은 분류기를 건너뛰므로 이러한 모든 경우에 계속 작동합니다.201작업 디렉토리 내의 읽기, 검색 및 편집은 분류자를 건너뛰므로 이 모든 경우에 계속 작동합니다.

192 202

193분류기 모델이 과부하 상태일 때:203분류자 모델이 과부하 상태일 때:

194 204

195```text theme={null}205```text theme={null}

196<model> is temporarily unavailable, so auto mode cannot determine the safety of <tool> right now. Wait briefly and then try this action again.206<model> is temporarily unavailable, so auto mode cannot determine the safety of <tool> right now. Wait briefly and then try this action again.

197```207```

198 208

199**할 일:**209**수행할 작업:**

200 210

201* 몇 초 후 재시도합니다. Claude는 동일한 메시지를 보고 일반적으로 자동으로 재시도합니다.211* 몇 초 후에 재시도합니다. Claude는 동일한 메시지를 보고 일반적으로 자동으로 재시도합니다

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

203* 이는 일시적이며 [자동 모드 적격성](/ko/permission-modes#eliminate-prompts-with-auto-mode)과 무관합니다. 설정을 변경할 필요가 없습니다.213* 이는 일시적이며 [자동 모드 적격성](/ko/permission-modes#eliminate-prompts-with-auto-mode)과 무관합니다. 설정을 변경할 필요가 없습니다

204 214

205분류기가 구문 분석할 수 없는 응답을 반환했을 때:215분류자가 구문 분석할 수 없는 응답을 반환했을 때:

206 216

207```text theme={null}217```text theme={null}

208Auto mode could not evaluate this action and is blocking it for safety — run with --debug for details218Auto mode could not evaluate this action and is blocking it for safety — run with --debug for details

209```219```

210 220

211**할 일:**221**수행할 작업:**

212 222

213* 작업을 재시도합니다. 일반적으로 다음 시도에서 성공합니다.223* 작업을 재시도합니다. 일반적으로 다음 시도에서 성공합니다

214* `claude --debug`를 실행하고 작업을 반복하여 디버그 로그에서 기본 분류기 응답을 확인합니다.224* `claude --debug`를 실행하고 작업을 반복하여 디버그 로그에서 기본 분류자 응답을 확인합니다

215 225

216이전 대화 콘텐츠 때문에 별도의 API 안전 확인이 분류기 요청을 차단했을 때:226별도의 API 안전 검사가 이전 대화 내용으로 인해 분류자 요청을 차단했을 때:

217 227

218```text theme={null}228```text theme={null}

219Auto mode could not evaluate this action and is blocking it for safety — a safety check separate from auto mode blocked this request because of earlier conversation content — it isn't about the action itself — run with --debug for details229Auto mode could not evaluate this action and is blocking it for safety — a safety check separate from auto mode blocked this request because of earlier conversation content — it isn't about the action itself — run with --debug for details

220```230```

221 231

222**할 일:**232**수행할 작업:**

223 233

224* 이것은 작업에 대한 결정이 아닙니다. 대화에 이미 있는 콘텐츠가 자동 모드가 분류기에 대화를 보낼 때 API의 안전 필터를 트리거했습니다.234* 이는 사용자의 작업에 대한 결정이 아닙니다. 대화에 이미 있는 내용이 자동 모드가 분류자에게 대화를 보낼 때 API의 안전 필터를 트리거했습니다

225* 재시도는 도움이 되지 않습니다. 동일한 대화 콘텐츠가 필터를 다시 트리거합니다.235* 재시도는 도움이 되지 않습니다. 동일한 대화 내용이 필터를 다시 트리거합니다

226* 다른 [권한 모드](/ko/permission-modes)로 전환하여 메시지가 표시될 때 작업을 승인하거나 트리거 콘텐츠 없이 새 대화를 시작합니다.236* 다른 [권한 모드](/ko/permission-modes)로 전환하여 메시지가 표시될 때 작업을 승인하거나 트리거 내용이 없는 새로운 대화를 시작합니다

227 237

228대화가 분류기의 컨텍스트 윈도우보다 커졌을 때:238대화가 분류자의 컨텍스트 윈도우보다 커졌을 때:

229 239

230```text theme={null}240```text theme={null}

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

233 243

234대화형 세션에서 자동 모드는 해당 작업에 대해 일반 권한 프롬프트로 폴백하므로 수동으로 승인하거나 거부할 수 있습니다. [비대화형 모드](/ko/headless)에서는 트랜스크립트만 증가하고 재시도가 성공할 수 없기 때문에 실행이 중단됩니다.244대화형 세션에서 자동 모드는 해당 작업에 대해 일반 권한 프롬프트로 폴백하므로 수동으로 승인하거나 거부할 수 있습니다. [비대화형 모드](/ko/headless)에서는 트랜스크립트만 증가하고 재시도가 성공할 수 없기 때문에 실행이 중단됩니다.

235 245

236**할 일:**246**수행할 작업:**

237 247

238* 나타나는 프롬프트에서 작업을 승인하거나 거부합니다.248* 표시되는 프롬프트에서 작업을 승인하거나 거부합니다

239* `/compact`를 실행하여 대화 크기를 줄여서 후속 작업이 분류기 윈도우에 맞도록 합니다.249* `/compact`를 실행하여 대화 크기를 줄여서 후속 작업이 분류자 윈도우에 맞도록 합니다

240 250

241<h3 id="agent-terminated-early-due-to-an-api-error">251<h3 id="agent-terminated-early-due-to-an-api-error">

242 Agent terminated early due to an API error252 에이전트가 API 오류로 인해 조기에 종료되었습니다

243</h3>253</h3>

244 254

245{/* min-version: 2.1.199 */}}[서브에이전트](/ko/sub-agents)의 API 요청이 터미널로 실패했습니다. 예를 들어 사용 제한에 도달했거나 서버 오류에 대한 재시도가 소진되었으므로 서브에이전트가 작업을 완료하기 전에 중지했습니다. 이 메시지는 Claude Code v2.1.199 이상이 필요합니다. 그 전에는 API 오류 텍스트가 서브에이전트의 결과인 것처럼 Claude에 반환되었습니다.255{/* min-version: 2.1.199 */}[서브에이전트](/ko/sub-agents)의 API 요청이 사용 한도에 도달했거나 서버 오류에 대한 재시도가 소진되었기 때문에 터미널로 실패했으므로 서브에이전트가 작업을 완료하기 전에 중지되었습니다. 이 메시지는 Claude Code v2.1.199 이상이 필요합니다. 그 이전에는 API 오류 텍스트가 서브에이전트의 결과인 것처럼 Claude에 반환되었습니다.

246 256

247```text theme={null}257```text theme={null}

248Agent terminated early due to an API error: <error detail>258Agent terminated early due to an API error: <error detail>

249```259```

250 260

251**할 일:**261**수행할 작업:**

252 262

253* 콜론 뒤의 오류 세부 정보를 이 페이지의 자체 섹션(예: [사용 제한](#usage-limits) 또는 [서버 오류](#server-errors))과 일치시키고 해당 섹션의 단계를 따릅니다.263* 콜론 뒤의 오류 세부 정보를 이 페이지의 자체 섹션(예: [사용 한도](#usage-limits) 또는 [서버 오류](#server-errors))과 일치시키고 해당 섹션의 단계를 따릅니다

254* 기본 오류가 해결되면 Claude에게 작업을 재시도하거나 [서브에이전트를 재개](/ko/sub-agents#resume-subagents)하도록 요청합니다.264* 기본 오류가 해결되면 Claude에게 작업을 재시도하거나 [서브에이전트를 재개](/ko/sub-agents#resume-subagents)하도록 요청합니다

255 265

256속도 제한, 과부하 또는 서버 오류가 이미 출력을 생성한 포그라운드 서브에이전트를 중단할 때 Claude는 이 오류 대신 불완전한 것으로 표시된 부분 출력을 받습니다. [서브에이전트의 API 오류](/ko/sub-agents#api-errors-in-subagents)를 참조하십시오.266속도 제한, 과부하 또는 서버 오류가 이미 텍스트 출력을 생성한 포그라운드 서브에이전트를 중단할 때 Claude는 이 오류 대신 불완전으로 표시된 부분 출력을 받습니다. {/* min-version: 2.1.200 */}유일한 출력이 도구 호출인 서브에이전트도 이 오류를 받습니다. v2.1.199에서는 대신 빈 부분 결과를 반환했습니다. [서브에이전트의 API 오류](/ko/sub-agents#api-errors-in-subagents)를 참조하세요.

257 267

258<h2 id="usage-limits">268<h2 id="usage-limits">

259 사용 제한269 사용 한도

260</h2>270</h2>

261 271

262이러한 오류는 계정 또는 플랜에 연결된 할당량에 도달했음을 의미합니다. 이는 모든 사람에게 영향을 미치는 [서버 오류](#server-errors)와는 다릅니다.272이러한 오류는 계정 또는 플랜에 연결된 할당량에 도달했음을 의미합니다. 이는 모든 사용자에게 영향을 미치는 [서버 오류](#server-errors)와는 다릅니다.

263 273

264<h3 id="you’ve-hit-your-session-limit">274<h3 id="you’ve-hit-your-session-limit">

265 You've hit your session limit275 세션 한도에 도달했습니다

266</h3>276</h3>

267 277

268구독 플랜에는 롤링 사용 허용량이 포함됩니다. 소진되면 다음 메시지 중 하나가 표시됩니다.278구독 플랜에는 롤링 사용 허용량이 포함됩니다. 허용량이 소진되면 다음 메시지 중 하나가 표시됩니다:

269 279

270```text theme={null}280```text theme={null}

271You've hit your session limit · resets 3:45pm281You've hit your session limit · resets 3:45pm

275 285

276Claude Code는 메시지에 표시된 재설정 시간까지 추가 요청을 차단합니다.286Claude Code는 메시지에 표시된 재설정 시간까지 추가 요청을 차단합니다.

277 287

278**할 일:**288**수행할 작업:**

279 289

280* 오류에 표시된 재설정 시간을 기다립니다.290* 오류에 표시된 재설정 시간까지 기다립니다

281* `/usage`를 실행하여 플랜 제한 및 재설정 시간을 확인합니다.291* `/usage`를 실행하여 플랜 한도 및 재설정 시간을 확인합니다

282* `/usage-credits`를 실행하여 Pro 및 Max에서 추가 사용을 구매하거나 Team 및 Enterprise에서 관리자에게 요청합니다. [유료 플랜에 대한 사용 크레딧](https://support.claude.com/ko/articles/12429409-extra-usage-for-paid-claude-plans)을 참조하여 청구 방식을 확인하십시오.292* `/usage-credits`를 실행하여 Pro 및 Max에서 추가 사용량을 구매하거나, Team 및 Enterprise에서 관리자에게 요청합니다. 이 요금이 청구되는 방식에 대해서는 [유료 플랜의 사용 크레딧](https://support.claude.com/en/articles/12429409-extra-usage-for-paid-claude-plans)을 참조하세요.

283* 더 높은 기본 제한을 위해 플랜을 업그레이드하려면 [claude.com/pricing](https://claude.com/pricing)을 참조하십시오.293* 더 높은 기본 한도를 위해 플랜을 업그레이드하려면 [claude.com/pricing](https://claude.com/pricing)을 참조하세요.

284 294

285제한에 도달하기 전에 남은 허용량을 확인하려면 `rate_limits` 필드를 [사용자 정의 상태 줄](/ko/statusline#rate-limit-usage)에 추가하거나 데스크톱 앱에서 모델 선택기 옆의 [사용 링](/ko/desktop#check-usage)을 클릭합니다.295한도에 도달하기 전에 남은 허용량을 모니터링하려면 `rate_limits` 필드를 [사용자 정의 상태 줄](/ko/statusline#rate-limit-usage)에 추가하거나, Desktop 앱에서 모델 선택기 옆의 [사용 현황 링](/ko/desktop#check-usage)을 클릭합니다.

286 296

287<h3 id="usage-credits-required-for-1m-context">297<h3 id="usage-credits-required-for-1m-context">

288 Usage credits required for 1M context298 1M 컨텍스트에 필요한 사용 크레딧

289</h3>299</h3>

290 300

291선택한 모델은 1M 토큰 확장 컨텍스트 윈도우를 사용하며, 플랜에는 사용 크레딧을 통해서만 포함됩니다.301선택한 모델은 1M 토큰 확장 컨텍스트 윈도우를 사용하며, 플랜에는 사용 크레딧을 통해서만 포함됩니다.

294API Error: Usage credits required for 1M context · run /usage-credits to turn them on, or /model to switch to standard context304API Error: Usage credits required for 1M context · run /usage-credits to turn them on, or /model to switch to standard context

295```305```

296 306

297이는 할당량 소진이 아니라 자격 확인입니다. 세션 및 주간 허용량에 용량이 남아 있어도 발생합니다. [확장 컨텍스트](/ko/model-config#extended-context)에서 어떤 플랜에 1M 컨텍스트가 직접 포함되고 어떤 플랜에 사용 크레딧이 필요한지 확인하십시오.307이는 할당량 소진이 아니라 자격 확인입니다. 세션 및 주간 허용량에 용량이 남아 있어도 발생합니다. 1M 컨텍스트를 직접 포함하는 플랜과 사용 크레딧이 필요한 플랜에 대해서는 [확장 컨텍스트](/ko/model-config#extended-context)를 참조하세요.

298 308

299{/* min-version: 2.1.172 */}}컨텍스트가 200K 토큰을 초과하여 대화 중에 이 오류가 나타나면 Claude Code는 자동으로 대화를 표준 컨텍스트 제한 이하로 압축하고 이후 세션을 해당 제한으로 유지하므로 조치가 필요하지 않습니다. v2.1.172 이전 버전에서는 `/compact`를 포함한 모든 후속 요청에서 오류가 반복되었습니다. 해당 버전에서는 `/clear`를 실행하여 복구합니다. 아래 단계는 명시적으로 `[1m]` 모델을 선택한 경우에 적용됩니다.309{/* min-version: 2.1.172 */}이 오류가 컨텍스트가 200K 토큰을 초과하여 대화 중에 나타나면 Claude Code는 자동으로 대화를 표준 컨텍스트 한도 아래로 압축하고 이후 세션을 해당 한도로 유지하므로 조치가 필요하지 않습니다. v2.1.172 이전 버전에서는 `/compact`를 포함한 모든 후속 요청에서 오류가 반복되었습니다. 해당 버전에서는 `/clear`를 실행하여 복구합니다. 아래 단계는 명시적으로 `[1m]` 모델을 선택한 경우에 적용됩니다.

300 310

301**할 일:**311**수행할 작업:**

302 312

303* `/model`을 실행하고 `[1m]` 접미사가 없는 변형을 선택하여 표준 컨텍스트 윈도우로 폴백합니다.313* `/model`을 실행하고 `[1m]` 접미사가 없는 변형을 선택하여 표준 컨텍스트 윈도우로 폴백합니다

304* `/usage-credits`를 실행하여 Pro 및 Max에서 1M 변형에 대한 종량제 청구를 활성화하거나 Team 및 Enterprise에서 관리자에게 요청합니다.314* `/usage-credits`를 실행하여 Pro 및 Max에서 1M 변형에 대한 종량제 청구를 켜거나, Team 및 Enterprise에서 관리자에게 요청합니다

305* `/model` 후에도 오류가 지속되면 1M 모델 ID가 다른 곳에 설정되어 있을 수 있습니다. [선택한 모델에 문제가 있습니다](#there%E2%80%99s-an-issue-with-the-selected-model)에서 우선 순위 순서로 확인할 구성 위치를 참조하십시오.315* `/model` 후에도 오류가 지속되면 1M 모델 ID가 다른 곳에 설정되어 있을 수 있습니다. 우선순위 순서로 확인할 구성 위치에 대해서는 [선택한 모델에 문제가 있습니다](#there%E2%80%99s-an-issue-with-the-selected-model)를 참조하세요.

306* 모델 선택기에서 1M 변형을 완전히 제거하려면 [`CLAUDE_CODE_DISABLE_1M_CONTEXT=1`](/ko/env-vars)을 설정합니다.316* 모델 선택기에서 1M 변형을 완전히 제거하려면 [`CLAUDE_CODE_DISABLE_1M_CONTEXT=1`](/ko/env-vars)을 설정합니다.

307 317

308<h3 id="server-is-temporarily-limiting-requests">318<h3 id="server-is-temporarily-limiting-requests">

309 Server is temporarily limiting requests319 서버가 일시적으로 요청을 제한 중입니다

310</h3>320</h3>

311 321

312API가 플랜 할당량과 무관한 단기 스로틀을 적용했습니다.322API가 플랜 할당량과 무관한 단기 스로틀을 적용했습니다.

315API Error: Server is temporarily limiting requests (not your usage limit)325API Error: Server is temporarily limiting requests (not your usage limit)

316```326```

317 327

318Claude Code는 이를 플랜 제한과 구별합니다. 실제 제한 응답이 전달하는 통합 할당량 헤더가 없기 때문입니다. {/* min-version: 2.1.199 */}}v2.1.199부터 이는 인증 방식에 관계없이 [자동으로 재시도](#automatic-retries)됩니다. 이전 버전에서는 claude.ai 구독으로 로그인한 세션이 첫 번째 발생에서 턴을 실패했습니다. API 키 및 엔터프라이즈 로그인만 재시도했습니다.328Claude Code는 실제 한도 응답이 전달하는 통합 할당량 헤더의 부재로 이를 플랜 한도와 구분합니다. {/* min-version: 2.1.199 */}v2.1.199부터 이는 인증 방식에 관계없이 [자동으로 재시도](#automatic-retries)되며 백오프를 사용한 후 표시됩니다. 이전 버전에서는 claude.ai 구독으로 로그인한 세션이 첫 번째 발생 시 턴에 실패했습니다. API 키 및 Enterprise 로그인만 재시도했습니다.

319 329

320**할 일:**330**수행할 작업:**

321 331

322* 잠시 기다린 후 다시 시도합니다.332* 잠시 기다렸다가 다시 시도합니다

323* 지속되면 [status.claude.com](https://status.claude.com)을 확인합니다.333* 지속되면 [status.claude.com](https://status.claude.com)을 확인합니다

324 334

325<h3 id="request-rejected-429">335<h3 id="request-rejected-429">

326 Request rejected (429)336 요청 거부됨 (429)

327</h3>337</h3>

328 338

329API 키, Amazon Bedrock 프로젝트 또는 Google Vertex AI 프로젝트에 대해 구성된 속도 제한에 도달했습니다.339API 키, Amazon Bedrock 프로젝트 또는 Google Cloud 프로젝트에 대해 구성된 속도 제한에 도달했습니다.

330 340

331```text theme={null}341```text theme={null}

332API Error: Request rejected (429) · this may be a temporary capacity issue. If it persists, check https://status.claude.com.342API Error: Request rejected (429) · this may be a temporary capacity issue. If it persists, check https://status.claude.com.

333```343```

334 344

335뒤따르는 문장은 서비스 상태를 확인할 위치를 나타내며 제공자에 따라 다릅니다. Bedrock, Vertex AI 및 Foundry 구성은 Anthropic 상태 페이지 대신 해당 제공자의 서비스 상태를 나타냅니다. 사용자 정의 `ANTHROPIC_BASE_URL`은 게이트웨이 호스트를 나타냅니다.345뒤따르는 문장은 서비스 상태를 확인할 위치를 명시하며 공급자에 따라 다릅니다. Amazon Bedrock, Google Cloud의 Agent Platform 및 Microsoft Foundry 구성은 Anthropic 상태 페이지 대신 해당 공급자의 서비스 상태를 명시합니다. 사용자 정의 `ANTHROPIC_BASE_URL`은 게이트웨이 호스트를 명시합니다.

336 346

337**할 일:**347**수행할 작업:**

338 348

339* `/status`를 실행하고 활성 자격 증명이 예상한 것인지 확인합니다. 환경의 잘못된 `ANTHROPIC_API_KEY`가 구독 대신 저가형 키를 통해 요청을 라우팅할 수 있습니다.349* `/status`를 실행하고 활성 자격 증명이 예상한 것인지 확인합니다. 환경에 있는 잘못된 `ANTHROPIC_API_KEY`는 구독 대신 저가형 키를 통해 요청을 라우팅할 수 있습니다.

340* 제공자 콘솔에서 활성 제한을 확인하고 필요한 경우 더 높은 계층을 요청합니다.350* 공급자 콘솔에서 활성 한도를 확인하고 필요한 경우 더 높은 계층을 요청합니다

341* Anthropic API 키의 경우 [속도 제한 참조](https://platform.claude.com/docs/ko/api/rate-limits)에서 계층이 작동하는 방식과 워크스페이스별 상한을 설정하는 방법을 참조하십시오.351* Anthropic API 키의 경우 계층이 작동하는 방식 및 워크스페이스별 상한을 설정하는 방법에 대해서는 [속도 제한 참조](https://platform.claude.com/docs/en/api/rate-limits)를 참조하세요

342* 동시성 감소: [`CLAUDE_CODE_MAX_TOOL_USE_CONCURRENCY`](/ko/env-vars)를 낮추고, 많은 병렬 서브에이전트 실행을 피하거나, 대량 스크립팅 실행을 위해 `/model`로 더 작은 모델로 전환합니다.352* 동시성 감소: [`CLAUDE_CODE_MAX_TOOL_USE_CONCURRENCY`](/ko/env-vars)를 낮추고, 많은 병렬 서브에이전트 실행을 피하거나, 대량 스크립팅 실행을 위해 `/model`로 더 작은 모델로 전환합니다

343 353

344<h3 id="credit-balance-is-too-low">354<h3 id="credit-balance-is-too-low">

345 Credit balance is too low355 크레딧 잔액이 너무 낮습니다

346</h3>356</h3>

347 357

348Console 조직이 선불 크레딧을 모두 사용했습니다.358Console 조직의 선불 크레딧이 소진되었습니다.

349 359

350```text theme={null}360```text theme={null}

351Credit balance is too low361Credit balance is too low

352```362```

353 363

354**할 일:**364**수행할 작업:**

355 365

356* [platform.claude.com/settings/billing](https://platform.claude.com/settings/billing)에서 크레딧을 추가하고 자동 재로드를 활성화하여 잔액이 0에 도달하기 전에 자동으로 충전되도록 합니다.366* [platform.claude.com/settings/billing](https://platform.claude.com/settings/billing)에서 크레딧을 추가하고, 잔액이 0에 도달하기 전에 자동 충전을 활성화하는 것을 고려합니다

357* Pro, Max, Team 또는 Enterprise 플랜이 있는 경우 `/login`으로 구독 인증으로 전환합니다.367* Pro, Max, Team 또는 Enterprise 플랜이 있는 경우 `/login`으로 구독 인증으로 전환합니다

358* Console에서 워크스페이스별 지출 상한을 설정하여 단일 프로젝트가 조직 잔액을 소진하지 않도록 합니다. [비용 효율적으로 관리](/ko/costs)를 참조하십시오.368* Console에서 워크스페이스별 지출 상한을 설정하여 단일 프로젝트가 조직 잔액을 소진하지 않도록 합니다. [비용 효과적으로 관리](/ko/costs)를 참조하세요.

359 369

360<h2 id="authentication-errors">370<h2 id="authentication-errors">

361 인증 오류371 인증 오류

362</h2>372</h2>

363 373

364이러한 오류는 Claude Code가 API에 대한 신원을 증명할 수 없음을 의미합니다. 언제든지 `/status`를 실행하여 현재 활성 자격 증명을 확인합니다.374이러한 오류는 Claude Code가 API에 대한 신원을 증명할 수 없음을 의미합니다. 언제든지 `/status`를 실행하여 현재 활성화된 자격증명을 확인할 수 있습니다.

365 375

366<h3 id="not-logged-in">376<h3 id="not-logged-in">

367 Not logged in377 로그인되지 않음

368</h3>378</h3>

369 379

370이 세션에 유효한 자격 증명이 없습니다.380이 세션에 유효한 자격증명이 없습니다.

371 381

372```text theme={null}382```text theme={null}

373Not logged in · Please run /login383Not logged in · Please run /login

374```384```

375 385

376**할 일:**386**수행할 작업:**

377 387

378* `/login`을 실행하여 Claude 구독 또는 Console 계정으로 인증합니다.388* `/login`을 실행하여 Claude 구독 또는 Console 계정으로 인증합니다.

379* 환경 변수가 인증할 것으로 예상한 경우 `ANTHROPIC_API_KEY`가 설정되어 있고 `claude`를 시작한 셸에서 내보내졌는지 확인합니다.389* 환경 변수로 인증하려고 했다면 `ANTHROPIC_API_KEY`가 `claude`를 실행한 셸에서 설정되고 내보내졌는지 확인합니다.

380* 대화형 로그인이 불가능한 CI 또는 자동화의 경우 시작 시 키를 가져오는 [`apiKeyHelper`](/ko/settings#available-settings) 스크립트를 구성합니다.390* CI 또는 자동화에서 대화형 로그인이 불가능한 경우, 시작 시 키를 가져오는 [`apiKeyHelper`](/ko/settings#available-settings) 스크립트를 구성합니다.

381* [인증 우선순위](/ko/authentication#authentication-precedence)를 참조하여 여러 자격 증명이 있을 때 어느 것이 우선하는지 이해합니다.391* [인증 우선순위](/ko/authentication#authentication-precedence)를 참조하여 여러 자격증명이 있을 때 Claude Code가 사용하는 자격증명을 이해합니다.

382 392

383반복적으로 로그인하라는 메시지가 표시되면 시스템 시계 및 macOS Keychain 수정을 위해 [로그인되지 않음 또는 토큰 만료](/ko/troubleshoot-install#not-logged-in-or-token-expired)를 참조하십시오.393반복적으로 로그인하라는 메시지가 표시되면 시스템 시계 및 macOS Keychain 수정 사항에 대해 [로그인되지 않음 또는 토큰 만료됨](/ko/troubleshoot-install#not-logged-in-or-token-expired)을 참조합니다.

384 394

385<h3 id="could-not-resolve-authentication-method">395<h3 id="could-not-resolve-authentication-method">

386 Could not resolve authentication method396 인증 방법을 확인할 수 없음

387</h3>397</h3>

388 398

389세션이 자격 증명 없이 API 클라이언트에 도달했습니다. 이는 [백그라운드 세션](/ko/agent-view), 클라우드 세션 및 첫 번째 요청 전에 대화형 로그인 확인이 실행되지 않는 Agent SDK 컨텍스트에 나타납니다.399세션이 자격증명 없이 API 클라이언트에 도달했습니다. 이는 [백그라운드 세션](/ko/agent-view), 클라우드 세션 및 첫 번째 요청 전에 대화형 로그인 확인이 실행되지 않는 Agent SDK 컨텍스트에서 나타납니다.

390 400

391```text theme={null}401```text theme={null}

392Could not resolve authentication method. Expected one of apiKey, authToken, credentials, config, or profile to be set. Or for one of the "X-Api-Key" or "Authorization" headers to be explicitly omitted402Could not resolve authentication method. Expected one of apiKey, authToken, credentials, config, or profile to be set. Or for one of the "X-Api-Key" or "Authorization" headers to be explicitly omitted

393```403```

394 404

395{/* min-version: 2.1.174 */}}v2.1.174 이전에는 유효한 자격 증명이 구성되어 있어도 유휴 사전 초기화된 워커에 할당된 백그라운드 또는 클라우드 세션이 이런 방식으로 실패할 수 있었습니다. 복구하려면 업그레이드하십시오. 현재 버전에서 오류는 워커 프로세스에 사용 가능한 자격 증명이 없음을 의미합니다.405{/* min-version: 2.1.174 */}v2.1.174 이전에는 유휴 사전 초기화된 워커에 할당된 백그라운드 또는 클라우드 세션이 유효한 자격증명이 구성되어 있어도 이런 방식으로 실패할 수 있었습니다. 업그레이드하여 복구합니다. 현재 버전에서 이 오류는 워커 프로세스에 사용 가능한 자격증명이 없음을 의미합니다.

396 406

397**할 일:**407**수행할 작업:**

398 408

399* 백그라운드 또는 클라우드 세션에 이것이 나타나고 자격 증명이 이미 구성되어 있으면 v2.1.174 이상으로 업그레이드합니다.409* 백그라운드 또는 클라우드 세션에서 이것이 나타나고 자격증명이 이미 구성되어 있으면 v2.1.174 이상으로 업그레이드합니다.

400* `ANTHROPIC_API_KEY`, `CLAUDE_CODE_OAUTH_TOKEN` 또는 클라우드 공급자 자격 증명이 대화형 셸뿐만 아니라 워커를 시작하는 환경에 설정되어 있는지 확인합니다.410* `ANTHROPIC_API_KEY`, `CLAUDE_CODE_OAUTH_TOKEN` 또는 클라우드 공급자 자격증명이 대화형 셸뿐만 아니라 워커를 실행하는 환경에서 설정되어 있는지 확인합니다.

401* Agent SDK의 경우 [인증 설정](/ko/agent-sdk/overview#get-started)을 참조하십시오.411* Agent SDK의 경우 [인증 설정](/ko/agent-sdk/overview#get-started)을 참조합니다.

402* 동일한 환경의 대화형 세션에서 `/status`를 실행하여 어느 자격 증명 소스가 해결되는지 확인합니다.412* 동일한 환경의 대화형 세션에서 `/status`를 실행하여 어떤 자격증명 소스가 확인되는지 확인합니다.

403 413

404<h3 id="invalid-api-key">414<h3 id="invalid-api-key">

405 Invalid API key415 잘못된 API 키

406</h3>416</h3>

407 417

408`ANTHROPIC_API_KEY` 환경 변수 또는 `apiKeyHelper` 스크립트가 API가 거부한 키를 반환했습니다.418`ANTHROPIC_API_KEY` 환경 변수 또는 `apiKeyHelper` 스크립트가 API에서 거부한 키를 반환했습니다.

409 419

410```text theme={null}420```text theme={null}

411Invalid API key · Fix external API key421Invalid API key · Fix external API key

412```422```

413 423

414**할 일:**424**수행할 작업:**

415 425

416* 오타를 확인하고 [Console](https://platform.claude.com/settings/keys)에서 키가 취소되지 않았는지 확인합니다.426* 오타를 확인하고 [Console](https://platform.claude.com/settings/keys)에서 키가 취소되지 않았는지 확인합니다.

417* 동일한 셸에서 `env | grep ANTHROPIC`을 실행합니다. direnv, dotenv 셸 플러그인, IDE 터미널과 같은 도구는 명시적으로 설정하지 않고도 프로젝트의 `.env` 파일에서 오래된 키를 로드할 수 있습니다.427* 동일한 셸에서 `env | grep ANTHROPIC`을 실행합니다. direnv, dotenv 셸 플러그인 및 IDE 터미널과 같은 도구는 명시적으로 설정하지 않아도 프로젝트의 `.env` 파일에서 오래된 키를 로드할 수 있습니다.

418* `ANTHROPIC_API_KEY`를 설정 해제하고 `/login`을 실행하여 대신 구독 인증을 사용합니다.428* `ANTHROPIC_API_KEY`를 설정 해제하고 `/login`을 실행하여 대신 구독 인증을 사용합니다.

419* 키가 [`apiKeyHelper`](/ko/settings#available-settings) 스크립트에서 오는 경우 스크립트를 직접 실행하여 stdout에 유효한 키를 인쇄하는지 확인합니다.429* 키가 [`apiKeyHelper`](/ko/settings#available-settings) 스크립트에서 오는 경우 스크립트를 직접 실행하여 stdout에 유효한 키를 인쇄하는지 확인합니다.

420* `/status`를 실행하여 Claude Code가 실제로 사용 중인 자격 증명 소스를 확인합니다.430* `/status`를 실행하여 Claude Code가 실제로 사용 중인 자격증명 소스를 확인합니다.

421 431

422<h3 id="this-organization-has-been-disabled">432<h3 id="this-organization-has-been-disabled">

423 This organization has been disabled433 이 조직이 비활성화되었습니다

424</h3>434</h3>

425 435

426비활성화된 Console 조직의 오래된 `ANTHROPIC_API_KEY`가 구독 로그인을 재정의하고 있습니다.436비활성화된 Console 조직의 오래된 `ANTHROPIC_API_KEY`가 구독 로그인을 재정의하고 있습니다.

430API Error: 400 ... This organization has been disabled.440API Error: 400 ... This organization has been disabled.

431```441```

432 442

433환경 변수는 `/login`보다 우선하므로 셸 프로필에서 내보내거나 `.env` 파일에서 로드된 키는 작동하는 Pro 또는 Max 구독이 있어도 사용됩니다. 비대화형 모드(`-p`)에서는 키가 있을 때 항상 사용됩니다.443환경 변수는 `/login`보다 우선순위가 높으므로 셸 프로필에서 내보내거나 `.env` 파일에서 로드된 키는 작동하는 Pro 또는 Max 구독이 있어도 사용됩니다. 비대화형 모드(`-p`)에서는 키가 있을 때 항상 사용됩니다.

434 444

435**할 일:**445**수행할 작업:**

436 446

437* 현재 셸에서 `ANTHROPIC_API_KEY`를 설정 해제하고 셸 프로필에서 제거한 후 `claude`를 다시 시작합니다.447* 현재 셸에서 `ANTHROPIC_API_KEY`를 설정 해제하고 셸 프로필에서 제거한 후 `claude`를 다시 실행합니다.

438* 그 후 `/status`를 실행하여 활성 자격 증명이 구독인지 확인합니다.448* 그 후 `/status`를 실행하여 활성 자격증명이 구독인지 확인합니다.

439* 환경 변수가 설정되지 않았는데도 오류가 지속되면 비활성화된 조직이 `/login`에 연결된 것입니다. 지원팀에 문의하거나 다른 계정으로 로그인합니다.449* 환경 변수가 설정되지 않았는데도 오류가 지속되면 비활성화된 조직이 `/login`에 연결된 것입니다. 지원팀에 문의하거나 다른 계정으로 로그인합니다.

440 450

441<h3 id="your-organization-has-disabled-api-key-authentication">451<h3 id="your-organization-has-disabled-api-key-authentication">

442 Your organization has disabled API key authentication452 조직에서 API 키 인증을 비활성화했습니다

443</h3>453</h3>

444 454

445{/* min-version: 2.1.169 */}}455이 메시지는 Claude Code v2.1.169 이상이 필요합니다. Console 조직의 관리자가 API 키 인증을 비활성화했으므로 API가 Claude Code가 보내는 키를 거부합니다. `·` 뒤의 복구 힌트는 키가 어디에서 왔는지에 따라 다릅니다:

446Console 조직의 관리자가 API 키 인증을 비활성화했으므로 API가 Claude Code가 전송하는 키를 거부합니다. `·` 뒤의 복구 힌트는 키가 어디에서 왔는지에 따라 다릅니다.

447 456

448```text theme={null}457```text theme={null}

449Your organization has disabled API key authentication · Run /login to sign in with your claude.ai account458Your organization has disabled API key authentication · Run /login to sign in with your claude.ai account

452Your organization has disabled API key authentication · Unset the apiKeyHelper setting and run /login to sign in with your claude.ai account461Your organization has disabled API key authentication · Unset the apiKeyHelper setting and run /login to sign in with your claude.ai account

453```462```

454 463

455환경 변수와 `apiKeyHelper`는 `/login`보다 우선하므로 둘 중 하나가 여전히 키를 제공하는 동안 `/login`만 실행해서는 도움이 되지 않습니다. [인증 우선순위](/ko/authentication#authentication-precedence)를 참조하십시오.464환경 변수와 `apiKeyHelper`는 `/login`보다 우선순위가 높으므로 둘 중 하나가 여전히 키를 제공하는 동안 `/login`만 실행해도 도움이 되지 않습니다. [인증 우선순위](/ko/authentication#authentication-precedence)를 참조합니다.

456 465

457**할 일:**466**수행할 작업:**

458 467

459* 메시지에 `ANTHROPIC_API_KEY`가 명시되어 있으면 현재 셸에서 설정을 해제하고 셸 프로필 또는 `.env` 파일에서 제거한 후 `claude`를 다시 시작합니다.468* 메시지에 `ANTHROPIC_API_KEY`가 명시되어 있으면 현재 셸에서 설정 해제하고 셸 프로필 또는 `.env` 파일에서 제거한 후 `claude`를 다시 실행합니다.

460* 메시지에 `apiKeyHelper`가 명시되어 있으면 `settings.json`에서 [`apiKeyHelper`](/ko/settings#available-settings) 설정을 제거합니다.469* 메시지에 `apiKeyHelper`가 명시되어 있으면 `settings.json`에서 [`apiKeyHelper`](/ko/settings#available-settings) 설정을 제거합니다.

461* `/login`을 실행하여 claude.ai 계정으로 로그인합니다.470* `/login`을 실행하여 claude.ai 계정으로 로그인합니다.

462* 그 후 `/status`를 실행하여 활성 자격 증명이 API 키가 아닌 구독인지 확인합니다.471* 그 후 `/status`를 실행하여 활성 자격증명이 API 키가 아닌 구독인지 확인합니다.

463* 자동화를 위해 API 키 인증이 필요한 경우 조직 관리자에게 Console에서 다시 활성화하도록 요청합니다.472* 자동화를 위해 API 키 인증이 필요한 경우 조직 관리자에게 Console에서 다시 활성화하도록 요청합니다.

464 473

465<h3 id="your-organization-has-disabled-claude-subscription-access">474<h3 id="your-organization-has-disabled-claude-subscription-access">

466 Your organization has disabled Claude subscription access475 조직에서 Claude 구독 액세스를 비활성화했습니다

467</h3>476</h3>

468 477

469Claude 조직이 구독 로그인으로 Claude Code에 로그인하는 것을 허용하지 않습니다. 동일한 계정으로 `/login`을 다시 실행하면 동일한 오류가 반환됩니다.478Claude 조직이 구독 로그인으로 Claude Code에 로그인하는 것을 허용하지 않습니다. 동일한 계정으로 `/login`을 다시 실행하면 동일한 오류가 반환됩니다.

472Your organization has disabled Claude subscription access for Claude Code · Use an Anthropic API key instead, or ask your admin to enable access481Your organization has disabled Claude subscription access for Claude Code · Use an Anthropic API key instead, or ask your admin to enable access

473```482```

474 483

475이는 서버 측 조직 설정이므로 로컬 설정, 환경 변수 또는 CLI 플래그에서 재정의할 수 없습니다. Agent SDK 및 `-p` 비대화형 모드는 이를 `oauth_org_not_allowed` 오류 코드로 표시합니다.484이는 서버 측 조직 설정이므로 로컬 설정, 환경 변수 또는 CLI 플래그에서 재정의할 수 없습니다.

476 485

477**할 일:**486Agent SDK 및 `-p` 비대화형 모드는 이를 `oauth_org_not_allowed` 오류 코드로 표시합니다.

487

488**수행할 작업:**

478 489

479* 관리자에게 조직에 대해 Claude Code 액세스를 활성화하도록 요청합니다.490* 관리자에게 조직에 대해 Claude Code 액세스를 활성화하도록 요청합니다.

480* 구독 대신 Console API 키로 인증합니다. 설정은 [Claude Console 인증](/ko/authentication#claude-console-authentication)을 참조하십시오.491* 구독 대신 Console API 키로 인증합니다. 설정은 [Claude Console 인증](/ko/authentication#claude-console-authentication)을 참조합니다.

481* 관리자이고 액세스를 활성화하는 옵션이 보이지 않으면 [Anthropic 지원](https://support.claude.com)에 문의합니다.492* 관리자이고 액세스를 활성화하는 옵션이 보이지 않으면 [Anthropic 지원팀](https://support.claude.com)에 문의합니다.

482 493

483<h3 id="routines-are-disabled-by-your-organization’s-policy">494<h3 id="routines-are-disabled-by-your-organization’s-policy">

484 Routines are disabled by your organization's policy495 루틴이 조직의 정책에 의해 비활성화되었습니다

485</h3>496</h3>

486 497

487팀 또는 엔터프라이즈 조직의 Owner가 조직 수준에서 루틴을 비활성화했습니다. 오류는 `/schedule` 및 claude.ai/code의 [Routines](/ko/routines) UI에서 루틴을 생성하거나 실행하려고 할 때 나타납니다.498Team 또는 Enterprise 조직의 Owner가 조직 수준에서 루틴을 비활성화했습니다. 오류는 `/schedule` 및 claude.ai/code의 [루틴](/ko/routines) UI를 포함하여 루틴을 생성하거나 실행하려고 할 때 나타납니다.

488 499

489```text theme={null}500```text theme={null}

490Routines are disabled by your organization's policy.501Routines are disabled by your organization's policy.

492 503

493이는 서버 측 설정이므로 로컬 설정, 환경 변수 또는 CLI 플래그에서 재정의할 수 없습니다.504이는 서버 측 설정이므로 로컬 설정, 환경 변수 또는 CLI 플래그에서 재정의할 수 없습니다.

494 505

495**할 일:**506**수행할 작업:**

496 507

497* 조직의 Owner에게 [claude.ai/admin-settings/claude-code](https://claude.ai/admin-settings/claude-code)에서 **Routines** 토글을 활성화하도록 요청합니다.508* 조직의 Owner에게 [claude.ai/admin-settings/claude-code](https://claude.ai/admin-settings/claude-code)에서 **루틴** 토글을 활성화하도록 요청합니다.

498* 조직 수준의 루틴이 필요하지 않은 일회성 예약 작업의 경우 [예약된 작업](/ko/scheduled-tasks)을 참조하십시오.509* 조직 수준의 루틴이 필요하지 않은 일회성 예약 작업의 경우 [예약된 작업](/ko/scheduled-tasks)을 참조합니다.

499 510

500<h3 id="remote-control-requires-the-anthropic-api">511<h3 id="remote-control-requires-the-anthropic-api">

501 Remote Control requires the Anthropic API512 원격 제어에는 Anthropic API가 필요합니다

502</h3>513</h3>

503 514

504세션이 Anthropic API와 직접 통신하지 않으므로 [Remote Control](/ko/remote-control)이 쌍을 이룰 claude.ai 백엔드가 없습니다.515세션이 Anthropic API와 직접 통신하지 않으므로 [원격 제어](/ko/remote-control)가 쌍을 이룰 claude.ai 백엔드가 없습니다.

505 516

506```text theme={null}517```text theme={null}

507Remote Control is only available when using Claude via api.anthropic.com.518Remote Control is only available when using Claude via api.anthropic.com.

508```519```

509 520

510이는 Amazon Bedrock, Google Vertex AI 및 Microsoft Foundry에 나타납니다. {/* min-version: 2.1.196 */}}v2.1.196부터는 [`ANTHROPIC_BASE_URL`](/ko/env-vars)이 `api.anthropic.com` 이외의 호스트(예: [LLM 게이트웨이](/ko/llm-gateway) 또는 프록시)를 가리킬 때도 나타나며, claude.ai로 로그인한 경우에도 마찬가지입니다.521이는 Amazon Bedrock, Google Cloud의 Agent Platform 및 Microsoft Foundry에서 나타납니다. {/* min-version: 2.1.196 */}v2.1.196부터는 [`ANTHROPIC_BASE_URL`](/ko/env-vars)이 `api.anthropic.com` 이외의 호스트(예: [LLM 게이트웨이](/ko/llm-gateway) 또는 프록시)를 가리킬 때도 나타나며, claude.ai로 로그인한 경우에도 나타납니다.

511 522

512**할 일:**523**수행할 작업:**

513 524

514* `ANTHROPIC_BASE_URL`을 설정 해제하고 세션을 다시 시작하거나 Anthropic API와 직접 통신하는 세션에서 Remote Control을 시작합니다.525* `ANTHROPIC_BASE_URL`을 설정 해제하고 세션을 다시 시작하거나 Anthropic API와 직접 통신하는 세션에서 원격 제어를 시작합니다.

515* 이 및 기타 Remote Control 시작 메시지의 경우 [Remote Control 문제 해결](/ko/remote-control#troubleshooting)을 참조하십시오.526* 이 및 다른 원격 제어 시작 메시지의 경우 [원격 제어 문제 해결](/ko/remote-control#troubleshooting)을 참조합니다.

516 527

517<h3 id="oauth-token-revoked-or-expired">528<h3 id="oauth-token-revoked-or-expired">

518 OAuth token revoked or expired529 OAuth 토큰이 취소되었거나 만료되었습니다

519</h3>530</h3>

520 531

521저장된 로그인이 더 이상 유효하지 않습니다. 취소된 토큰은 어디서나 로그아웃했거나 관리자가 액세스를 제거했음을 의미합니다. 만료된 토큰은 자동 새로 고침이 세션 중에 실패했음을 의미합니다.532저장된 로그인이 더 이상 유효하지 않습니다. 취소된 토큰은 모든 곳에서 로그아웃했거나 관리자가 액세스를 제거했음을 의미하고, 만료된 토큰은 자동 새로 고침이 세션 중에 실패했음을 의미합니다.

522 533

523```text theme={null}534```text theme={null}

524OAuth token revoked · Please run /login535OAuth token revoked · Please run /login

526API Error: 401 ... authentication_error537API Error: 401 ... authentication_error

527```538```

528 539

529**할 일:**540**수행할 작업:**

530 541

531* `/login`을 실행하여 다시 로그인합니다.542* `/login`을 실행하여 다시 로그인합니다.

532* 동일한 세션 내에서 재인증 후 오류가 반환되면 먼저 `/logout`을 실행하여 저장된 토큰을 완전히 지운 후 `/login`을 실행합니다.543* 재인증 후 동일한 세션 내에서 오류가 반환되면 먼저 `/logout`을 실행하여 저장된 토큰을 완전히 지운 후 `/login`을 실행합니다.

533* 시작 간 반복적인 로그인 프롬프트의 경우 [문제 해결](/ko/troubleshoot-install#not-logged-in-or-token-expired)의 시스템 시계 및 macOS Keychain 확인을 참조하십시오.544* 시작 간에 반복적인 로그인 프롬프트의 경우 [문제 해결](/ko/troubleshoot-install#not-logged-in-or-token-expired)의 시스템 시계 및 macOS Keychain 확인을 참조합니다.

534* `403 Forbidden` 및 OAuth 브라우저 문제를 포함한 기타 오류는 [로그인 및 인증](/ko/troubleshoot-install#login-and-authentication)을 참조하십시오.545* `403 Forbidden` 및 OAuth 브라우저 문제를 포함한 다른 실패의 경우 [로그인 및 인증](/ko/troubleshoot-install#login-and-authentication)을 참조합니다.

535 546

536<h3 id="oauth-scope-requirement">547<h3 id="oauth-scope-requirement">

537 OAuth scope requirement548 OAuth 범위 요구사항

538</h3>549</h3>

539 550

540저장된 토큰은 최신 기능이 필요한 권한 범위보다 앞서 있습니다. 이는 `/usage` 및 상태 줄 사용 표시기에서 가장 자주 표시됩니다.551저장된 토큰이 최신 기능에 필요한 권한 범위보다 앞서 있습니다. 이는 `/usage` 및 상태 줄 사용량 표시기에서 가장 자주 나타납니다:

541 552

542```text theme={null}553```text theme={null}

543OAuth token does not meet scope requirement: user:profile554OAuth token does not meet scope requirement: user:profile

544```555```

545 556

546**할 일:**557**수행할 작업:**

547 558

548* `/login`을 실행하여 현재 범위로 새 토큰을 발급합니다. 먼저 로그아웃할 필요가 없습니다.559* `/login`을 실행하여 현재 범위로 새 토큰을 가져옵니다. 먼저 로그아웃할 필요가 없습니다.

549 560

550<h3 id="aws-credentials-expired-or-invalid">561<h3 id="aws-credentials-expired-or-invalid">

551 AWS credentials expired or invalid562 AWS 자격증명이 만료되었거나 유효하지 않습니다

552</h3>563</h3>

553 564

554{/* min-version: 2.1.198 */}}이 메시지는 Claude Code v2.1.198 이상이 필요하며 [`awsAuthRefresh`](/ko/amazon-bedrock#advanced-credential-configuration)가 설정 파일에 설정되어 있을 때만 나타납니다. AWS 세션 토큰이 만료되었거나 거부되었으며 Claude Code가 이미 실행한 자동 새로 고침이 API가 허용하는 자격 증명을 생성하지 못했습니다. [AWS의 Claude Platform](/ko/claude-platform-on-aws) 또는 [Mantle 엔드포인트](/ko/amazon-bedrock#use-the-mantle-endpoint)의 401에 나타나며, 이는 해당 제공자가 만료된 보안 토큰을 보고하는 방식입니다.565{/* min-version: 2.1.198 */}이 메시지는 Claude Code v2.1.198 이상이 필요하며 설정 파일에 [`awsAuthRefresh`](/ko/amazon-bedrock#advanced-credential-configuration)가 설정되어 있을 때만 나타납니다. AWS 세션 토큰이 만료되었거나 거부되었으며, Claude Code가 이미 실행한 자동 새로 고침이 API가 수락하는 자격증명을 생성하지 못했습니다. [AWS의 Claude Platform](/ko/claude-platform-on-aws) 또는 [Mantle 엔드포인트](/ko/amazon-bedrock#use-the-mantle-endpoint)에서 401이 나타나며, 이는 해당 공급자가 만료된 보안 토큰을 보고하는 방식입니다.

555 566

556중간의 작업 힌트는 설정의 `awsAuthRefresh` 명령을 나타내므로 다릅니다. 선행 부분은 `AWS credentials expired or invalid`입니다.567중간의 작업 힌트는 설정의 `awsAuthRefresh` 명령을 명시하므로 다릅니다. 안정적인 부분은 선행하는 `AWS credentials expired or invalid`입니다:

557 568

558```text theme={null}569```text theme={null}

559AWS credentials expired or invalid · run /login and select "Claude Platform on AWS · refresh credentials", or run `aws sso login --profile myprofile` in another terminal · API Error: 401 ...570AWS credentials expired or invalid · run /login and select "Claude Platform on AWS · refresh credentials", or run `aws sso login --profile myprofile` in another terminal · API Error: 401 ...

560```571```

561 572

562`awsAuthRefresh`가 구성되지 않으면 동일한 401은 대신 일반 `Please run /login` 메시지를 표시하며, AWS 자격 증명을 새로 고칠 수 없습니다.573`awsAuthRefresh`가 구성되지 않으면 동일한 401이 대신 일반 `Please run /login` 메시지를 표시하며, 이는 AWS 자격증명을 새로 고칠 수 없습니다.

563 574

564**할 일:**575**수행할 작업:**

565 576

566* 메시지에 명시된 `awsAuthRefresh` 명령(예: `aws sso login --profile myprofile`)을 다른 터미널에서 실행하고 브라우저 로그인을 완료한 후 재시도합니다.577* 메시지에 명시된 `awsAuthRefresh` 명령(예: `aws sso login --profile myprofile`)을 다른 터미널에서 실행하고 브라우저 로그인을 완료한 후 다시 시도합니다.

567* 대화형 세션에서 `/login`을 실행하고 **3rd-party platform**을 선택한 후 **Using 3rd-party platforms** 아래에서 **Claude Platform on AWS · refresh credentials**를 선택하여 Claude Code를 다시 시작하지 않고 동일한 명령을 실행합니다. [AWS 자격 증명 구성](/ko/claude-platform-on-aws#1-configure-aws-credentials)을 참조하십시오.578* 대화형 세션에서 `/login`을 실행하고 **3rd-party platform**을 선택한 후 **Using 3rd-party platforms** 아래에서 **Claude Platform on AWS · refresh credentials**를 선택하여 Claude Code를 다시 시작하지 않고 동일한 명령을 실행합니다. [AWS 자격증명 구성](/ko/claude-platform-on-aws#1-configure-aws-credentials)을 참조합니다.

568* 새로 고침 명령이 성공한 후에도 오류가 반복되면 동일한 셸 및 프로필에서 `aws sts get-caller-identity`로 Claude Code 외부에서 신원이 유효한지 확인합니다.579* 새로 고침 명령이 성공한 후에도 오류가 반복되면 동일한 셸 및 프로필에서 `aws sts get-caller-identity`를 사용하여 Claude Code 외부에서 ID가 유효한지 확인합니다.

569 580

570<h3 id="aws-authentication-failed">581<h3 id="aws-authentication-failed">

571 AWS authentication failed582 AWS 인증 실패

572</h3>583</h3>

573 584

574{/* min-version: 2.1.198 */}}이 메시지는 Claude Code v2.1.198 이상이 필요하며 [`awsAuthRefresh`](/ko/amazon-bedrock#advanced-credential-configuration)가 설정 파일에 설정되어 있을 때만 나타납니다. AWS 제공자가 403을 반환했거나 [Amazon Bedrock](/ko/amazon-bedrock)이 401을 반환했습니다.585{/* min-version: 2.1.198 */}이 메시지는 Claude Code v2.1.198 이상이 필요하며 설정 파일에 [`awsAuthRefresh`](/ko/amazon-bedrock#advanced-credential-configuration)가 설정되어 있을 때만 나타납니다. AWS 공급자가 403을 반환했거나 [Amazon Bedrock](/ko/amazon-bedrock)이 401을 반환했습니다.

575 586

576Claude Code는 어느 원인을 맞았는지 알 수 없습니다. Amazon Bedrock은 만료된 보안 토큰을 403으로 보고하지만 403은 또한 `AccessDeniedException`에서 누락된 IAM 권한 또는 계정에 대해 활성화되지 않은 모델과 같은 인증 거부를 보고하는 방식입니다.587Claude Code는 어느 원인을 맞혔는지 알 수 없습니다. Amazon Bedrock은 만료된 보안 토큰을 403으로 보고하지만, 403은 또한 IAM 권한 누락 또는 계정에 대해 활성화되지 않은 모델과 같은 `AccessDeniedException`의 권한 거부를 보고하는 방식입니다.

577 588

578Amazon Bedrock의 401도 [AWS 자격 증명 만료 또는 유효하지 않음](#aws-credentials-expired-or-invalid) 아래가 아닌 여기에 도달합니다. Bedrock이 만료된 토큰을 401로 보고하지 않기 때문입니다. 해당 엔드포인트의 401은 일반적으로 회사 프록시와 같은 요청 경로의 다른 것에서 나옵니다.589Amazon Bedrock의 401은 [AWS 자격증명이 만료되었거나 유효하지 않습니다](#aws-credentials-expired-or-invalid) 아래가 아닌 여기에 도달합니다. Amazon Bedrock은 만료된 토큰을 401로 보고하지 않기 때문입니다. 해당 엔드포인트의 401은 일반적으로 회사 프록시와 같은 요청 경로의 다른 것에서 옵니다.

579 590

580자격 증명 새로 고침은 만료된 토큰을 수정하고 다른 원인을 수정할 수 없으므로 메시지는 둘 다 제공합니다.591자격증명 새로 고침은 만료된 토큰을 수정하고 다른 원인을 수정할 수 없으므로 메시지는 둘 다 제공합니다:

581 592

582```text theme={null}593```text theme={null}

583AWS authentication failed · run /login and select "Claude Platform on AWS · refresh credentials", or run `aws sso login --profile myprofile` in another terminal · if credentials are current, check AWS permissions and model access · API Error: 403 ...594AWS authentication failed · run /login and select "Claude Platform on AWS · refresh credentials", or run `aws sso login --profile myprofile` in another terminal · if credentials are current, check AWS permissions and model access · API Error: 403 ...

584```595```

585 596

586중간의 작업 힌트는 설정의 `awsAuthRefresh` 명령을 나타내므로 다릅니다. 선행 부분은 `AWS authentication failed`입니다.597중간의 작업 힌트는 설정의 `awsAuthRefresh` 명령을 명시하므로 다릅니다. 안정적인 부분은 선행하는 `AWS authentication failed`입니다.

587 598

588**할 일:**599**수행할 작업:**

589 600

590* 메시지에 명시된 `awsAuthRefresh` 명령 또는 `aws sso login`을 실행합니다. 만료된 자격 증명이 원인일 수 있습니다.601* 메시지에 명시된 `awsAuthRefresh` 명령 또는 `aws sso login`을 실행합니다(만료된 자격증명이 원인일 수 있음).

591* 자격 증명이 현재이면 [IAM 구성](/ko/amazon-bedrock#iam-configuration)의 IAM 권한이 사용 중인 신원에 연결되어 있고 선택한 모델이 계정 및 지역에 대해 활성화되어 있는지 확인합니다.602* 자격증명이 최신이면 [IAM 구성](/ko/amazon-bedrock#iam-configuration)의 IAM 권한이 사용 중인 ID에 연결되어 있고 선택한 모델이 계정 및 지역에 대해 활성화되어 있는지 확인합니다.

592* `aws sts get-caller-identity`를 실행하여 요청이 사용하는 신원을 확인합니다. 오래된 `AWS_PROFILE` 또는 기본 프로필은 권한 불일치의 일반적인 원인입니다.603* `aws sts get-caller-identity`를 실행하여 요청이 어떤 ID를 사용하는지 확인합니다. 오래된 `AWS_PROFILE` 또는 기본 프로필은 권한 불일치의 일반적인 원인입니다.

593 604

594<h2 id="network-and-connection-errors">605<h2 id="network-and-connection-errors">

595 네트워크 및 연결 오류606 네트워크 및 연결 오류

598이러한 오류는 Claude Code의 네트워크 요청이 목적지에 도달하지 못했음을 의미합니다. 일반적으로 로컬 네트워크, 프록시 또는 방화벽, 또는 클라우드 환경의 네트워크 정책에서 발생합니다.609이러한 오류는 Claude Code의 네트워크 요청이 목적지에 도달하지 못했음을 의미합니다. 일반적으로 로컬 네트워크, 프록시 또는 방화벽, 또는 클라우드 환경의 네트워크 정책에서 발생합니다.

599 610

600<h3 id="unable-to-connect-to-api">611<h3 id="unable-to-connect-to-api">

601 Unable to connect to API612 API에 연결할 수 없음

602</h3>613</h3>

603 614

604API에 대한 TCP 연결이 실패했거나 완료되지 않았습니다.615API에 대한 TCP 연결이 실패했거나 완료되지 않았습니다.

612Request timed out. Check your internet connection and proxy settings623Request timed out. Check your internet connection and proxy settings

613```624```

614 625

615일반적인 원인으로는 인터넷 액세스 없음, `api.anthropic.com`을 차단하는 VPN, 또는 구성되지 않은 필수 회사 프록시가 있습니다.626일반적인 원인으로는 인터넷 접근 불가, `api.anthropic.com`을 차단하는 VPN, 또는 구성되지 않은 필수 회사 프록시가 있습니다.

616 627

617**할 일:**628**수행할 작업:**

618 629

619* 동일한 셸에서 `curl -I https://api.anthropic.com`을 실행하여 API 호스트에 도달할 수 있는지 확인합니다. Windows PowerShell에서는 `curl.exe -I https://api.anthropic.com`을 사용하여 기본 제공 `Invoke-WebRequest` 별칭이 사용되지 않도록 합니다.630* 동일한 셸에서 `curl -I https://api.anthropic.com`을 실행하여 API 호스트에 도달할 수 있는지 확인합니다. Windows PowerShell에서는 `curl.exe -I https://api.anthropic.com`을 사용하여 기본 제공 `Invoke-WebRequest` 별칭이 사용되지 않도록 합니다.

620* 회사 프록시 뒤에 있는 경우 Claude Code를 시작하기 전에 `HTTPS_PROXY`를 설정하고 [네트워크 구성](/ko/network-config)을 참조하십시오.631* 회사 프록시 뒤에 있는 경우 Claude Code를 시작하기 전에 `HTTPS_PROXY`를 설정하고 [네트워크 구성](/ko/network-config)을 참조합니다.

621* LLM 게이트웨이 또는 릴레이를 통해 라우팅하는 경우 [`ANTHROPIC_BASE_URL`](/ko/env-vars)을 해당 주소로 설정합니다. 설정은 [Claude Code를 LLM 게이트웨이에 연결](/ko/llm-gateway-connect)을 참조하십시오.632* LLM 게이트웨이 또는 릴레이를 통해 라우팅하는 경우 [`ANTHROPIC_BASE_URL`](/ko/env-vars)을 해당 주소로 설정합니다. 설정은 [Claude Code를 LLM 게이트웨이에 연결](/ko/llm-gateway-connect)을 참조합니다.

622* 방화벽이 [네트워크 액세스 요구 사항](/ko/network-config#network-access-requirements)에 나열된 호스트를 허용하는지 확인합니다.633* 방화벽이 [네트워크 액세스 요구 사항](/ko/network-config#network-access-requirements)에 나열된 호스트를 허용하는지 확인합니다.

623* 간헐적 오류는 [자동으로 재시도](#automatic-retries)됩니다. 지속적인 오류는 로컬 네트워크 문제를 나타냅니다.634* 간헐적 오류는 [자동으로 재시도](#automatic-retries)되며, 지속적인 오류는 로컬 네트워크 문제를 나타냅니다.

624 635

625`curl`이 성공하지만 Claude Code가 여전히 실패하면 원인은 일반적으로 네트워크 자체가 아닌 런타임과 네트워크 사이의 무언가입니다.636`curl`이 성공하지만 Claude Code가 여전히 실패하는 경우, 원인은 일반적으로 네트워크 자체가 아니라 런타임과 네트워크 사이의 무언가입니다:

626 637

627* Linux 및 WSL에서 `/etc/resolv.conf`에서 도달할 수 없는 네임서버를 확인합니다. 특히 WSL은 호스트에서 손상된 리졸버를 상속할 수 있습니다.638* Linux 및 WSL에서 `/etc/resolv.conf`에서 도달할 수 없는 네임서버를 확인합니다. 특히 WSL은 호스트에서 손상된 리졸버를 상속할 수 있습니다.

628* macOS에서 연결이 끊어지거나 제거된 VPN 클라이언트는 터널 인터페이스 또는 라우팅 규칙을 남길 수 있습니다. `ifconfig`에서 오래된 `utun` 인터페이스를 확인하고 시스템 설정에서 VPN의 네트워크 확장을 제거합니다.639* macOS에서 연결이 끊어지거나 제거된 VPN 클라이언트는 터널 인터페이스 또는 라우팅 규칙을 남길 수 있습니다. `ifconfig`에서 오래된 `utun` 인터페이스를 확인하고 시스템 설정에서 VPN의 네트워크 확장을 제거합니다.

629* Docker Desktop 및 유사한 컨테이너 런타임은 아웃바운드 트래픽을 가로챌 수 있습니다. 이를 종료하고 재시도하여 이를 배제합니다.640* Docker Desktop 및 유사한 컨테이너 런타임은 아웃바운드 트래픽을 가로챌 수 있습니다. 이를 종료하고 다시 시도하여 이를 배제합니다.

630 641

631<h3 id="ssl-certificate-errors">642<h3 id="ssl-certificate-errors">

632 SSL certificate errors643 SSL 인증서 오류

633</h3>644</h3>

634 645

635네트워크의 프록시 또는 보안 어플라이언스가 자체 인증서로 TLS 트래픽을 가로채고 있으며 Claude Code가 이를 신뢰하지 않습니다.646네트워크의 프록시 또는 보안 어플라이언스가 자체 인증서로 TLS 트래픽을 가로채고 있으며, Claude Code가 이를 신뢰하지 않습니다.

636 647

637```text theme={null}648```text theme={null}

638Unable to connect to API: SSL certificate verification failed. Check your proxy or corporate SSL certificates649Unable to connect to API: SSL certificate verification failed. Check your proxy or corporate SSL certificates

639Unable to connect to API: Self-signed certificate detected650Unable to connect to API: Self-signed certificate detected

640```651```

641 652

642{/* min-version: 2.1.199 */}}v2.1.199부터 인증서 검증 실패는 재시도되지 않으므로 이 오류는 전체 [재시도 예산](#automatic-retries) 후가 아닌 첫 번째 시도에 나타납니다. 이전 버전은 표시하기 전에 몇 분 동안 재시도했습니다. 핸드셰이크 시간 초과와 같은 일시적 TLS 조건은 여전히 재시도됩니다.653{/* min-version: 2.1.199 */}v2.1.199부터 인증서 검증 실패는 재시도되지 않으므로 이 오류는 전체 [재시도 예산](#automatic-retries) 후가 아니라 첫 번째 시도에 나타납니다. 이전 버전은 표시하기 전에 몇 분 동안 재시도했습니다. 핸드셰이크 타임아웃과 같은 일시적 TLS 조건은 여전히 재시도됩니다.

643 654

644`/login` 및 시작 연결 확인 중에 동일한 실패는 OpenSSL 코드 및 인라인 수정으로 보고됩니다.655`/login` 및 시작 연결 확인 중에 동일한 오류가 OpenSSL 코드 및 인라인 수정과 함께 보고됩니다:

645 656

646```text theme={null}657```text theme={null}

647SSL certificate error (UNABLE_TO_GET_ISSUER_CERT_LOCALLY). If you are behind a corporate proxy or TLS-intercepting firewall, set NODE_EXTRA_CA_CERTS to your CA bundle path, or ask IT to allowlist *.anthropic.com. Run /doctor for details.658SSL certificate error (UNABLE_TO_GET_ISSUER_CERT_LOCALLY). If you are behind a corporate proxy or TLS-intercepting firewall, set NODE_EXTRA_CA_CERTS to your CA bundle path, or ask IT to allowlist *.anthropic.com. Run `claude doctor` for details.

648```659```

649 660

650**할 일:**661**수행할 작업:**

651 662

652* 조직의 CA 번들을 내보내고 `NODE_EXTRA_CA_CERTS=/path/to/ca-bundle.pem`으로 Claude Code를 가리킵니다.663* 조직의 CA 번들을 내보내고 `NODE_EXTRA_CA_CERTS=/path/to/ca-bundle.pem`으로 Claude Code를 가리킵니다.

653* 전체 설정 지침은 [네트워크 구성](/ko/network-config#custom-ca-certificates)을 참조하십시오.664* 전체 설정 지침은 [네트워크 구성](/ko/network-config#custom-ca-certificates)을 참조합니다.

654* 인증서 검증을 완전히 비활성화하는 `NODE_TLS_REJECT_UNAUTHORIZED=0`을 설정하지 마십시오.665* `NODE_TLS_REJECT_UNAUTHORIZED=0`을 설정하지 마십시오. 이는 인증서 검증을 완전히 비활성화합니다.

655 666

656<h3 id="host-not-allowed-in-a-cloud-session">667<h3 id="host-not-allowed-in-a-cloud-session">

657 Host not allowed in a cloud session668 클라우드 세션에서 호스트가 허용되지 않음

658</h3>669</h3>

659 670

660클라우드 세션 또는 루틴의 아웃바운드 HTTP 요청이 환경의 네트워크 정책에 의해 차단되었습니다.671클라우드 세션 또는 루틴의 아웃바운드 HTTP 요청이 환경의 네트워크 정책에 의해 차단되었습니다.

664x-deny-reason: host_not_allowed675x-deny-reason: host_not_allowed

665```676```

666 677

667대상의 실제 인증서와 일치하지 않는 TLS 인증서도 표시될 수 있습니다. 클라우드 환경은 아웃바운드 트래픽을 네트워크 정책을 적용하는 프록시를 통해 라우팅하므로 인증서 불일치는 대상이 아닌 프록시가 연결을 종료했음을 의미합니다.678대상의 실제 인증서와 일치하지 않는 TLS 인증서도 표시될 수 있습니다. 클라우드 환경은 아웃바운드 트래픽을 네트워크 정책을 적용하는 프록시를 통해 라우팅하므로, 일치하지 않는 인증서는 대상이 아니라 프록시가 연결을 종료했음을 의미합니다.

668 679

669이것은 클라이언트 측 네트워크 문제가 아닙니다. 클라우드 세션 및 [루틴](/ko/routines)은 아웃바운드 트래픽이 환경의 허용 목록으로 필터링되는 샌드박스 환경 내에서 실행됩니다. **기본** 환경은 **신뢰할 수 있는** 액세스를 사용하며, 이는 패키지 레지스트리, 클라우드 공급자 API, 컨테이너 레지스트리 및 일반적인 개발 도메인의 [기본 허용 목록](/ko/claude-code-on-the-web#default-allowed-domains)을 허용하지만 다른 모든 것은 차단합니다.680이는 클라이언트 측 네트워크 문제가 아닙니다. 클라우드 세션 및 [루틴](/ko/routines)은 아웃바운드 트래픽이 환경의 허용 목록으로 필터링되는 샌드박스 환경 내에서 실행됩니다. **기본** 환경은 **신뢰할 수 있는** 액세스를 사용하며, 이는 패키지 레지스트리, 클라우드 공급자 API, 컨테이너 레지스트리 및 일반적인 개발 도메인의 [기본 허용 목록](/ko/claude-code-on-the-web#default-allowed-domains)을 허용하지만 다른 모든 것을 차단합니다.

670 681

671**할 일:**682**수행할 작업:**

672 683

673* 루틴을 편집하기 위해 열거나 클라우드 세션을 시작합니다. **기본**과 같은 환경 이름을 표시하는 클라우드 아이콘을 선택하여 선택기를 엽니다. 환경 위에 마우스를 올리고 설정 아이콘을 클릭합니다.684* 루틴을 편집하기 위해 열거나 클라우드 세션을 시작합니다. **기본**과 같은 환경 이름을 표시하는 클라우드 아이콘을 선택하여 선택기를 엽니다. 환경 위에 마우스를 올리고 설정 아이콘을 클릭합니다.

674* **클라우드 환경 업데이트** 대화 상자에서 **네트워크 액세스**를 **신뢰할 수 있는**에서 **사용자 정의**로 변경한 다음 차단된 도메인을 **허용된 도메인**에 추가합니다. 한 줄에 하나의 도메인을 입력합니다. **일반적인 패키지 관리자의 기본 목록도 포함**을 확인하여 사용자 정의 도메인과 함께 [기본 허용 목록](/ko/claude-code-on-the-web#default-allowed-domains)을 유지합니다. 제한 없는 액세스를 원하면 대신 **전체**를 선택합니다.685* **클라우드 환경 업데이트** 대화 상자에서 **네트워크 액세스**를 **신뢰할 수 있는**에서 **사용자 정의**로 변경한 다음 차단된 도메인을 **허용된 도메인**에 추가합니다. 한 줄에 하나의 도메인을 입력합니다. **일반적인 패키지 관리자의 기본 목록도 포함**을 확인하여 [기본 허용 목록](/ko/claude-code-on-the-web#default-allowed-domains)을 사용자 정의 도메인과 함께 유지합니다. 제한 없는 액세스를 원하는 경우 대신 **전체**를 선택합니다.

675* **변경 사항 저장**을 클릭합니다. 다음 실행은 업데이트된 허용 목록을 사용합니다.686* **변경 사항 저장**을 클릭합니다. 다음 실행은 업데이트된 허용 목록을 사용합니다.

676 687

677액세스 수준 및 기본 허용 목록은 [네트워크 액세스](/ko/claude-code-on-the-web#network-access)를 참조하십시오. 로컬 CLI 세션은 이 정책의 영향을 받지 않습니다.688액세스 수준 및 기본 허용 목록은 [네트워크 액세스](/ko/claude-code-on-the-web#network-access)를 참조합니다. 로컬 CLI 세션은 이 정책의 영향을 받지 않습니다.

689

690<h3 id="couldn’t-reconnect-to-your-remote-control-session">

691 Remote Control 세션에 다시 연결할 수 없음

692</h3>

693

694```text theme={null}

695Couldn't reconnect to your Remote Control session. Retry, or start a fresh session without --resume.

696```

697

698`claude --resume` 또는 `claude --continue`로 재개하면 해당 대화에 기록된 [Remote Control](/ko/remote-control) 세션에 다시 연결됩니다. 이 메시지는 네트워크 중단 또는 서버 오류와 같이 일시적일 수 있는 이유로 재연결이 실패했음을 의미하므로 Claude Code는 원격 세션이 여전히 존재하는지 확인할 수 없습니다. 로컬 세션은 Remote Control 없이 계속 실행됩니다.

699

700**수행할 작업:**

701

702* `/remote-control`을 실행하여 연결을 재시도합니다.

703* `--resume` 없이 Claude Code를 시작하여 새 Remote Control 세션을 만듭니다.

704* 다른 Remote Control 시작 메시지는 [Remote Control 문제 해결](/ko/remote-control#troubleshooting)을 참조합니다.

705

706서버가 이전 세션이 더 이상 존재하지 않음을 확인하면 이 메시지가 표시되지 않습니다. Claude Code는 이 경우 새 세션을 만듭니다. {/* min-version: 2.1.200 */}v2.1.200 이전에는 모든 재연결 실패가 새 Remote Control 세션을 만들었으며, 이는 claude.ai/code의 세션 목록에 추가 세션을 남겼습니다.

678 707

679<h2 id="request-errors">708<h2 id="request-errors">

680 요청 오류709 요청 오류

681</h2>710</h2>

682 711

683이러한 오류는 API가 요청을 수신했지만 내용을 거부했음을 의미합니다.712이러한 오류는 요청의 내용과 관련이 있습니다. 대부분은 API가 요청을 거부한 후 반환되며, 일부는 요청이 전송되기 전에 Claude Code에서 로컬로 생성됩니다.

684 713

685<h3 id="prompt-is-too-long">714<h3 id="prompt-is-too-long">

686 Prompt is too long715 프롬프트가 너무 깁니다

687</h3>716</h3>

688 717

689대화 및 첨부 파일이 모델의 컨텍스트 윈도우를 초과합니다.718대화와 첨부된 파일이 모델의 컨텍스트 윈도우를 초과합니다.

690 719

691```text theme={null}720```text theme={null}

692Prompt is too long721Prompt is too long

693```722```

694 723

695**할 일:**724**수행할 작업:**

696 725

697* `/compact`를 실행하여 이전 턴을 요약하고 공간을 확보하거나 `/clear`를 실행하여 새로 시작합니다.726* `/compact`를 실행하여 이전 턴을 요약하고 공간을 확보하거나, `/clear`를 실행하여 새로 시작합니다.

698* `/context`를 실행하여 윈도우를 소비하는 것의 분석을 확인합니다. 시스템 프롬프트, 도구, 메모리 파일, 메시지입니다.727* `/context`를 실행하여 윈도우를 소비하는 항목의 분석을 확인합니다: 시스템 프롬프트, 도구, 메모리 파일 및 메시지

699* `/mcp disable <name>`으로 사용하지 않는 MCP 서버를 비활성화하여 컨텍스트에서 도구 정의를 제거합니다.728* `/mcp disable <name>`으로 사용하지 않는 MCP 서버를 비활성화하여 컨텍스트에서 도구 정의를 제거합니다.

700* 큰 `CLAUDE.md` 메모리 파일을 자르거나 지침을 [경로 범위 규칙](/ko/memory#path-specific-rules)으로 이동하여 관련이 있을 때만 로드합니다.729* 큰 `CLAUDE.md` 메모리 파일을 정리하거나, 지침을 [경로 범위 규칙](/ko/memory#path-specific-rules)으로 이동하여 관련이 있을 때만 로드합니다.

701* 서브에이전트는 부모 세션에서 모든 MCP 도구 정의를 상속하므로 첫 번째 턴 전에 컨텍스트 윈도우를 채울 수 있습니다. 서브에이전트를 생성하기 전에 사용하지 않는 MCP 서버를 비활성화합니다.730* 서브에이전트는 부모 세션의 모든 MCP 도구 정의를 상속하므로, 첫 번째 턴 전에 컨텍스트 윈도우를 채울 수 있습니다. 서브에이전트를 생성하기 전에 사용하지 않는 MCP 서버를 비활성화합니다.

702* 자동 압축은 기본적으로 켜져 있으며 일반적으로 이 오류를 방지합니다. [`DISABLE_AUTO_COMPACT`](/ko/env-vars)를 설정한 경우 다시 활성화하거나 윈도우가 가득 차기 전에 `/compact`를 수동으로 실행합니다.731* 자동 압축은 기본적으로 활성화되어 있으며 일반적으로 이 오류를 방지합니다. [`DISABLE_AUTO_COMPACT`](/ko/env-vars)를 설정한 경우, 다시 활성화하거나 윈도우가 가득 차기 전에 `/compact`를 수동으로 실행합니다.

703 732

704[컨텍스트 윈도우 탐색](/ko/context-window)을 참조하여 컨텍스트가 어떻게 채워지는지 대화형으로 확인합니다.733[컨텍스트 윈도우 탐색](/ko/context-window)을 참조하여 컨텍스트가 어떻게 채워지는지 대화형으로 확인합니다.

705 734

706<h3 id="error-during-compaction-conversation-too-long">735<h3 id="error-during-compaction-conversation-too-long">

707 Error during compaction: Conversation too long736 압축 중 오류: 대화가 너무 깁니다

708</h3>737</h3>

709 738

710`/compact` 자체가 실패했습니다. 생성하는 요약을 보유할 충분한 여유 컨텍스트가 없기 때문입니다.739`/compact` 자체가 실패했습니다. 생성되는 요약을 보유할 충분한 여유 컨텍스트가 없기 때문입니다.

711 740

712```text theme={null}741```text theme={null}

713Error during compaction: Conversation too long. Press esc twice to go up a few messages and try again.742Error during compaction: Conversation too long. Press esc twice to go up a few messages and try again.

714```743```

715 744

716이는 윈도우가 자동 압축이 트리거되는 순간 이미 가득 차 있거나 `Prompt is too long`을 본 후 `/compact`를 실행할 때 발생할 수 있습니다.745이는 자동 압축이 트리거되는 순간 윈도우가 이미 가득 차 있거나, `Prompt is too long`을 본 후 `/compact`를 실행할 때 발생할 수 있습니다.

717 746

718**할 일:**747**수행할 작업:**

719 748

720* Esc를 두 번 눌러 메시지 목록을 열고 몇 턴 뒤로 이동합니다. 이는 컨텍스트에서 가장 최근 메시지를 제거합니다. 그런 다음 `/compact`를 다시 실행합니다.749* Esc를 두 번 눌러 메시지 목록을 열고 여러 턴을 뒤로 이동합니다. 이렇게 하면 가장 최근 메시지가 컨텍스트에서 제거됩니다. 그런 다음 `/compact`를 다시 실행합니다.

721* 뒤로 이동해도 충분한 공간이 확보되지 않으면 `/clear`를 실행하여 새 세션을 시작합니다. 이전 대화는 보존되며 `/resume`으로 다시 열 수 있습니다.750* 뒤로 이동해도 충분한 공간이 확보되지 않으면 `/clear`를 실행하여 새 세션을 시작합니다. 이전 대화는 보존되며 `/resume`으로 다시 열 수 있습니다.

722 751

723<h3 id="request-too-large">752<h3 id="request-too-large">

724 Request too large753 요청이 너무 큽니다

725</h3>754</h3>

726 755

727원본 요청 본문이 토큰화 전에 API의 바이트 제한을 초과했습니다. 일반적으로 큰 붙여넣은 파일 또는 첨부 파일 때문입니다.756원본 요청 본문이 토큰화 전에 API의 바이트 제한을 초과했습니다. 일반적으로 큰 붙여넣은 파일이나 첨부 파일 때문입니다.

728 757

729```text theme={null}758```text theme={null}

730Request too large (max 30 MB). Double press esc to go back and remove or shrink the attached content.759Request too large (max 30 MB). Double press esc to go back and remove or shrink the attached content.

732 761

733이는 [컨텍스트 윈도우 제한](#prompt-is-too-long)과 별개인 HTTP 요청의 크기 제한입니다.762이는 [컨텍스트 윈도우 제한](#prompt-is-too-long)과 별개인 HTTP 요청의 크기 제한입니다.

734 763

735**할 일:**764**수행할 작업:**

736 765

737* Esc를 두 번 눌러 뒤로 이동하고 과도한 크기의 콘텐츠를 추가한 턴을 지나갑니다.766* Esc를 두 번 눌러 뒤로 이동하고 과도한 크기의 콘텐츠를 추가한 턴을 지나갑니다.

738* 콘텐츠를 붙여넣는 대신 경로로 큰 파일을 참조하여 Claude가 청크 단위로 읽을 수 있도록 합니다.767* 콘텐츠를 붙여넣는 대신 경로로 큰 파일을 참조하여 Claude가 청크 단위로 읽을 수 있도록 합니다.

739* 이미지의 경우 아래 [Image was too large](#image-was-too-large)를 참조하십시오.768* 이미지의 경우 아래의 [이미지가 너무 컸습니다](#image-was-too-large)를 참조합니다.

740 769

741<h3 id="image-was-too-large">770<h3 id="image-was-too-large">

742 Image was too large771 이미지가 너무 컸습니다

743</h3>772</h3>

744 773

745붙여넣거나 첨부한 이미지가 API의 크기 또는 치수 제한을 초과합니다.774붙여넣거나 첨부한 이미지가 API의 크기 또는 치수 제한을 초과합니다.

749API Error: 400 ... image dimensions exceed max allowed size778API Error: 400 ... image dimensions exceed max allowed size

750```779```

751 780

752{/* min-version: 2.1.142 */}}Claude Code는 처리할 수 없는 이미지를 텍스트 자리 표시자로 바꾸고 다시 시도하므로 후속 메시지가 성공합니다. 2.1.142 이전 버전에서는 붙여넣은 이미지가 대화에 남아 있을 수 있으며 후속 메시지마다 동일한 오류를 반복합니다. 이러한 버전에서 복구하려면 Esc를 두 번 눌러 이미지가 추가된 턴을 지나갑니다.781{/* min-version: 2.1.142 */}Claude Code는 처리할 수 없는 이미지를 텍스트 자리 표시자로 바꾸고 다시 시도하므로 후속 메시지가 성공합니다. 2.1.142 이전 버전에서는 붙여넣은 이미지가 대화에 남아 있을 수 있으며 후속 메시지마다 동일한 오류를 반복할 수 있습니다. 이러한 버전에서 복구하려면 Esc를 두 번 눌러 이미지가 추가된 턴을 지나갑니다.

753 782

754**할 일:**783**수행할 작업:**

755 784

756* 붙여넣기 전에 이미지 크기를 조정합니다. API는 단일 이미지의 경우 가장 긴 가장자리에서 최대 8000픽셀을 허용하거나 많은 이미지가 컨텍스트에 있을 때 2000픽셀을 허용합니다.785* 붙여넣기 전에 이미지 크기를 조정합니다. API는 단일 이미지의 경우 가장 긴 가장자리에서 최대 8000픽셀, 많은 이미지가 컨텍스트에 있을 때 2000픽셀까지의 이미지를 허용합니다.

757* 전체 화면 대신 관련 영역의 더 타이트한 스크린샷을 찍습니다.786* 전체 화면 대신 관련 영역의 더 타이트한 스크린샷을 찍습니다.

758 787

759<h3 id="unable-to-resize-image">788<h3 id="unable-to-resize-image">

760 Unable to resize image789 이미지 크기 조정 불가

761</h3>790</h3>

762 791

763Claude Code가 API로 보내기 전에 첨부된 이미지를 축소할 수 없습니다.792Claude Code가 API로 보내기 전에 첨부된 이미지를 축소할 수 없었습니다.

764 793

765```text theme={null}794```text theme={null}

766Unable to resize image — image processing is unavailable and dimensions could not be read from the file header. Please convert the image to PNG, JPEG, GIF, or WebP.795Unable to resize image — image processing is unavailable and dimensions could not be read from the file header. Please convert the image to PNG, JPEG, GIF, or WebP.

769Unable to resize image — could not verify image dimensions are within the 2000x2000px API limit.798Unable to resize image — could not verify image dimensions are within the 2000x2000px API limit.

770```799```

771 800

772Claude Code는 일반적으로 큰 이미지를 자동으로 축소합니다. 이러한 오류는 네이티브 이미지 프로세서가 로드되지 않았거나 오류를 반환했으므로 이미지를 API 제한 내에 맞게 축소할 수 없음을 의미합니다.801Claude Code는 일반적으로 큰 이미지를 자동으로 크기 조정합니다. 이러한 오류는 네이티브 이미지 프로세서가 로드되지 않았거나 오류를 반환했으므로 이미지를 API 제한에 맞게 크기 조정할 수 없음을 의미합니다.

773 802

774**할 일:**803**수행할 작업:**

775 804

776* 메시지가 이미지를 변환하도록 요청하면 PNG, JPEG, GIF 또는 WebP로 변환하고 다시 첨부합니다. Claude Code는 이미지 프로세서 없이 이러한 형식의 치수를 확인할 수 있습니다.805* 메시지에서 이미지를 변환하도록 요청하면 PNG, JPEG, GIF 또는 WebP로 변환하고 다시 첨부합니다. Claude Code는 이미지 프로세서 없이 이러한 형식의 치수를 확인할 수 있습니다.

777* 메시지가 치수 또는 크기 제한을 보고하면 첨부하기 전에 이미지를 해당 제한 아래로 크기 조정하거나 다시 압축합니다.806* 메시지에서 치수 또는 크기 제한을 보고하면 첨부하기 전에 이미지를 해당 제한 아래로 크기 조정하거나 다시 압축합니다.

778 807

779<h3 id="pdf-errors">808<h3 id="pdf-errors">

780 PDF errors809 PDF 오류

781</h3>810</h3>

782 811

783첨부한 PDF를 처리할 수 없습니다.812첨부한 PDF를 처리할 수 없었습니다.

784 813

785```text theme={null}814```text theme={null}

786PDF too large (max 100 pages, 32 MB). Try splitting it or extracting text first.815PDF too large (max 100 pages, 32 MB). Try splitting it or extracting text first.

788The PDF file was not valid. Try converting to a different format first.817The PDF file was not valid. Try converting to a different format first.

789```818```

790 819

791**할 일:**820**수행할 작업:**

792 821

793* 과도한 크기의 PDF의 경우 Claude에게 전체 파일을 첨부하는 대신 Read 도구로 페이지 범위를 읽도록 요청하거나 `pdftotext`와 같은 도구로 텍스트를 추출하고 경로로 출력 파일을 참조합니다.822* 크기가 큰 PDF의 경우 전체 파일을 첨부하는 대신 Read 도구로 Claude에게 페이지 범위를 읽도록 요청하거나, `pdftotext`와 같은 도구로 텍스트를 추출하고 경로로 출력 파일을 참조합니다.

794* 보호되거나 유효하지 않은 PDF의 경우 암호를 제거하거나 소스 애플리케이션에서 파일을 다시 내보낸 후 다시 시도합니다.823* 보호되거나 유효하지 않은 PDF의 경우 암호를 제거하거나 원본 응용 프로그램에서 파일을 다시 내보낸 후 다시 시도합니다.

795 824

796<h3 id="extra-inputs-are-not-permitted">825<h3 id="extra-inputs-are-not-permitted">

797 Extra inputs are not permitted826 추가 입력은 허용되지 않습니다

798</h3>827</h3>

799 828

800Claude Code와 API 사이의 프록시 또는 LLM 게이트웨이가 `anthropic-beta` 요청 헤더를 제거했으므로 API가 이에 따라 달라지는 필드를 거부했습니다.829Claude Code와 API 사이의 프록시 또는 LLM 게이트웨이가 `anthropic-beta` 요청 헤더를 제거했으므로 API가 이에 따라 달라지는 필드를 거부했습니다.

805API Error: 400 ... Unexpected value(s) for the `anthropic-beta` header834API Error: 400 ... Unexpected value(s) for the `anthropic-beta` header

806```835```

807 836

808Claude Code는 `context_management`, `effort`, 도구 `input_examples`와 같은 베타 전용 필드를 이를 활성화하는 `anthropic-beta` 헤더와 함께 보냅니다. 게이트웨이가 본문을 전달하지만 헤더를 제거하면 API는 인식하지 못하는 필드를 봅니다.837Claude Code는 `context_management`, `effort` 및 도구 `input_examples`와 같은 베타 전용 필드를 이를 활성화하는 `anthropic-beta` 헤더와 함께 보냅니다. 게이트웨이가 본문을 전달하지만 헤더를 제거하면 API는 인식하지 못하는 필드를 봅니다.

809 838

810**할 일:**839**수행할 작업:**

811 840

812* `anthropic-beta` 헤더를 전달하도록 게이트웨이를 구성합니다. [기능 통과](/ko/llm-gateway-protocol#feature-pass-through)를 참조하여 게이트웨이가 전달해야 하는 것을 확인합니다.841* `anthropic-beta` 헤더를 전달하도록 게이트웨이를 구성합니다. 게이트웨이가 전달해야 하는 항목은 [기능 통과](/ko/llm-gateway-protocol#feature-pass-through)를 참조합니다.

813* 대체로 시작하기 전에 [`CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1`](/ko/env-vars)을 설정합니다. 이는 베타 헤더가 필요한 기능을 비활성화하여 헤더를 전달할 수 없는 게이트웨이를 통해 요청이 성공하도록 합니다.842* 대체 방법으로, 시작하기 전에 [`CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1`](/ko/env-vars)을 설정합니다. 이렇게 하면 베타 헤더가 필요한 기능이 비활성화되므로 헤더를 전달할 수 없는 게이트웨이를 통해 요청이 성공합니다.

814 843

815<h3 id="there’s-an-issue-with-the-selected-model">844<h3 id="there’s-an-issue-with-the-selected-model">

816 There's an issue with the selected model845 선택한 모델에 문제가 있습니다

817</h3>846</h3>

818 847

819{/* min-version: 2.1.160 */}}848구성된 모델 이름이 인식되지 않았거나 계정에 이에 대한 액세스 권한이 없습니다. v2.1.160 기준으로 여기에 대화형 형식으로 표시된 후행 힌트는 표면에 따라 다릅니다.

820구성된 모델 이름이 인식되지 않았거나 계정이 이에 액세스할 수 없습니다. v2.1.160부터 뒤따르는 힌트는 여기에 대화형 형식으로 표시되며 표면에 따라 다릅니다.

821 849

822```text theme={null}850```text theme={null}

823There's an issue with the selected model (claude-...). It may not exist or you may not have access to it. Run /model to pick a different model.851There's an issue with the selected model (claude-...). It may not exist or you may not have access to it. Run /model to pick a different model.

824```852```

825 853

826**할 일:**854**수행할 작업:**

827 855

828* **대화형 CLI**: `/model`을 실행하여 계정에서 사용 가능한 모델 중에서 선택합니다.856* **대화형 CLI**: `/model`을 실행하여 계정에서 사용 가능한 모델 중에서 선택합니다.

829* **비대화형 모드(`-p`)**: `--model`을 유효한 별칭 또는 ID와 함께 전달하거나 [`ANTHROPIC_MODEL`](/ko/env-vars)을 설정합니다. 오류 텍스트는 이 표면에서 `Run --model`을 표시합니다.857* **비대화형 모드(`-p`)**: `--model`을 유효한 별칭 또는 ID와 함께 전달하거나 [`ANTHROPIC_MODEL`](/ko/env-vars)을 설정합니다. 오류 텍스트는 이 표면에서 `Run --model`을 표시합니다.

830* **Agent SDK**: 모델이 프로그래밍 방식으로 설정되므로 오류 텍스트는 힌트를 생략합니다. TypeScript에서 [`Options`의 `model`](/ko/agent-sdk/typescript#options)을 설정하거나 Python에서 [`ClaudeAgentOptions(model=...)`](/ko/agent-sdk/python#claudeagentoptions)을 설정하고 구조화된 `model_not_found` 오류를 처리하여 자신의 재시도 또는 모델 선택기를 표시합니다.858* **Agent SDK**: 모델이 프로그래밍 방식으로 설정되므로 오류 텍스트는 힌트를 생략합니다. TypeScript에서 [`Options`의 `model`](/ko/agent-sdk/typescript#options)을 설정하거나 Python에서 [`ClaudeAgentOptions(model=...)`](/ko/agent-sdk/python#claudeagentoptions)을 설정하고, 구조화된 `model_not_found` 오류를 처리하여 자신의 재시도 또는 모델 선택기를 표시합니다.

831* `sonnet` 또는 `opus`와 같은 별칭을 전체 버전 ID 대신 사용합니다. 별칭은 유지 관리되는 기본값으로 확인되므로 오래되지 않습니다. [모델 구성](/ko/model-config)을 참조하십시오.859* 전체 버전이 지정된 ID 대신 `sonnet` 또는 `opus`와 같은 별칭을 사용합니다. 별칭은 유지 관리되는 기본값으로 확인되므로 오래되지 않습니다. [모델 구성](/ko/model-config)을 참조합니다.

832* 잘못된 모델이 계속 CLI에서 돌아오면 오래된 ID가 어딘가에 설정되어 있습니다. [우선순위 순서](/ko/model-config#setting-your-model)로 확인합니다. `--model` 플래그, `ANTHROPIC_MODEL` 환경 변수, 그 다음 `.claude/settings.local.json`의 `model` 필드, 프로젝트의 `.claude/settings.json`, 그리고 `~/.claude/settings.json`입니다. 오래된 값을 제거하면 Claude Code는 계정 기본값으로 폴백합니다.860* 잘못된 모델이 CLI에서 계속 반환되면 어딘가에 오래된 ID가 설정되어 있습니다. [우선 순위 순서](/ko/model-config#setting-your-model)로 확인합니다: `--model` 플래그, `ANTHROPIC_MODEL` 환경 변수, 그런 다음 `.claude/settings.local.json`의 `model` 필드, 프로젝트의 `.claude/settings.json` 및 `~/.claude/settings.json`. 오래된 값을 제거하면 Claude Code가 계정 기본값으로 폴백됩니다.

833* Vertex AI 배포의 경우 [Vertex AI 문제 해결](/ko/google-vertex-ai#troubleshooting)을 참조하십시오.861* Google Cloud의 Agent Platform 배포의 경우 [Google Cloud의 Agent Platform 문제 해결](/ko/google-vertex-ai#troubleshooting)을 참조합니다.

862

863<h3 id="model-is-not-a-recognized-model-id">

864 모델이 인식된 모델 ID가 아닙니다

865</h3>

866

867모델 스위치에 전달한 모델 문자열이 모델 별칭, 이 Claude Code 버전이 알고 있는 모델 ID 또는 `claude-`로 시작하는 ID가 아닙니다. 일반적인 원인은 ID의 오타, `Sonnet 5`와 같은 표시 이름(ID `claude-sonnet-5` 필요) 또는 최신 Claude Code 버전만 인식하는 별칭입니다. Claude Code는 스위치를 즉시 거부합니다. v2.1.200 이전에는 Claude Code가 문자열을 저장하고 [선택한 모델에 문제가 있습니다](#there%E2%80%99s-an-issue-with-the-selected-model)에서 다음 요청에 실패했습니다.

868

869```text theme={null}

870Model "claud-sonnet-5" is not a recognized model id. Did you mean 'claude-sonnet-5'?

871```

872

873후행 힌트는 가장 가까운 일치하는 별칭 또는 모델 ID의 이름을 지정합니다. 충분히 가까운 것이 없으면 `Run /model to see available models.`로 읽습니다.

874

875Claude Code는 API 요청이 이루어지기 전에 스위치가 요청되는 순간 로컬에서 이 오류를 생성합니다. [Agent SDK](/ko/agent-sdk/typescript) `setModel()` 메서드를 통해 또는 Claude Code CLI를 실행하는 [Desktop app](/ko/desktop)과 같은 앱에 의해 모델이 설정될 때 적용됩니다.

876

877**수행할 작업:**

878

879* 인수 없이 `/model`을 실행하여 선택기를 열고 계정에서 사용 가능한 모델 중에서 선택한 다음 거기에 표시된 별칭 또는 ID를 전달합니다.

880* 최신 Claude Code 버전이 지원하는 별칭을 사용한 경우 `claude update`를 실행합니다. `claude-`로 시작하는 전체 ID는 모델이 Claude Code 버전보다 최신이어도 이 확인을 통과하므로 업그레이드가 필요하지 않습니다.

881* v2.1.200 이전에 저장된 모델은 이 확인으로 복구되지 않습니다. 오래된 값이 계속 반환되면 [선택한 모델에 문제가 있습니다](#there%E2%80%99s-an-issue-with-the-selected-model)에 나열된 위치에서 제거합니다.

882* 확인은 Anthropic API에서만 실행됩니다. Amazon Bedrock, Google Cloud의 Agent Platform, Microsoft Foundry, [Claude Platform on AWS](/ko/claude-platform-on-aws) 및 [LLM 게이트웨이](/ko/llm-gateway) 또는 사용자 정의 `ANTHROPIC_BASE_URL` 뒤에서 공급자 또는 게이트웨이가 모델 이름을 정의하므로 Claude Code는 모든 문자열을 허용하고 통과합니다.

834 883

835<h3 id="claude-opus-is-not-available-with-the-claude-pro-plan">884<h3 id="claude-opus-is-not-available-with-the-claude-pro-plan">

836 Claude Opus is not available with the Claude Pro plan885 Claude Opus는 Claude Pro 플랜에서 사용할 수 없습니다

837</h3>886</h3>

838 887

839활성 구독 플랜에 선택한 모델이 포함되지 않습니다.888활성 구독 플랜에 선택한 모델이 포함되지 않습니다.

842Claude Opus is not available with the Claude Pro plan · Select a different model in /model891Claude Opus is not available with the Claude Pro plan · Select a different model in /model

843```892```

844 893

845**할 일:**894**수행할 작업:**

846 895

847* `/model`을 실행하고 플랜에 포함된 모델을 선택합니다.896* `/model`을 실행하고 플랜에 포함된 모델을 선택합니다.

848* 최근에 플랜을 업그레이드했는데도 여전히 이를 보면 `/logout`을 실행한 후 `/login`을 실행합니다. 저장된 토큰은 로그인 시 플랜을 반영하므로 웹에서 업그레이드해도 기존 세션에서 적용되지 않을 때까지 적용되지 않습니다.897* 최근에 플랜을 업그레이드했는데도 이것이 표시되면 `/logout`을 실행한 다음 `/login`을 실행합니다. 저장된 토큰은 로그인 시점의 플랜을 반영하므로 웹에서 업그레이드해도 기존 세션에서 다시 인증할 때까지 적용되지 않습니다.

849* 각 플랜에 포함된 모델은 [claude.com/pricing](https://claude.com/pricing)을 참조하십시오.898* 각 플랜에 포함된 모델은 [claude.com/pricing](https://claude.com/pricing)을 참조합니다.

850 899

851<h3 id="model-is-restricted-by-your-organization’s-settings">900<h3 id="model-is-restricted-by-your-organization’s-settings">

852 Model is restricted by your organization's settings901 모델이 조직의 설정으로 제한됩니다

853</h3>902</h3>

854 903

855{/* min-version: 2.1.187 */}}904조직 관리자가 claude.ai 관리 콘솔에서 이 모델을 비활성화했거나, 관리되는 설정의 [`availableModels`](/ko/model-config#restrict-model-selection) 허용 목록으로 제외되었습니다. 제한된 모델이 `--model`, `ANTHROPIC_MODEL` 또는 `model` 설정으로 설정된 경우 Claude Code는 허용된 모델을 대체하고 계속합니다. 제한된 모델에 대해 `/model <name>`을 입력하면 `Run /model to choose a different model.`로 거부되고 세션은 현재 모델을 유지합니다.

856조직 관리자가 claude.ai 관리 콘솔에서 이 모델을 비활성화했거나 관리되는 설정의 [`availableModels`](/ko/model-config#restrict-model-selection) 허용 목록으로 제외되었습니다. 제한된 모델이 `--model`, `ANTHROPIC_MODEL` 또는 `model` 설정으로 설정되었을 때 Claude Code는 허용된 모델로 대체하고 계속합니다. 제한된 모델에 대해 `/model <name>`을 입력하면 `Run /model to choose a different model.`로 거부되고 세션은 현재 모델을 유지합니다.

857 905

858```text theme={null}906```text theme={null}

859Model "claude-opus-4-8" is restricted by your organization's settings. Using claude-sonnet-4-6 instead.907Model "claude-opus-4-8" is restricted by your organization's settings. Using claude-sonnet-4-6 instead.

860```908```

861 909

862**할 일:**910Claude Code는 모델 패밀리 별칭(예: `opus`, `sonnet`, `haiku` 또는 `fable` 중 하나)을 최신 버전에 대한 요청이 아닌 해당 패밀리에 대한 요청으로 취급합니다. Anthropic API 및 [Claude Platform on AWS](/ko/claude-platform-on-aws)에서 제한된 패밀리 별칭은 조직 및 `availableModels` 허용 목록이 허용하는 패밀리의 최신 버전으로 확인되며, 대체 알림은 해당 버전의 이름을 지정합니다. Claude Code는 패밀리의 모든 버전이 제한될 때만 `/model <alias>`를 거부합니다. v2.1.205 이전에는 패밀리 별칭이 같은 패밀리의 이전 버전이 허용되었을 때도 최신 버전만을 기반으로 대체되거나 거부되었습니다.

911

912**수행할 작업:**

863 913

864* `/model`을 실행하여 조직이 허용하는 모델 중에서 선택합니다. 제한된 모델은 선택기에서 숨겨집니다.914* `/model`을 실행하여 조직이 허용하는 모델 중에서 선택합니다. 제한된 모델은 선택기에서 숨겨집니다.

865* 제한된 모델이 `--model`, `ANTHROPIC_MODEL` 또는 설정 파일의 `model` 필드에 설정되었으면 해당 값을 제거하거나 업데이트하여 각 시작 시 알림이 반복되지 않도록 합니다.915* 제한된 모델이 `--model`, `ANTHROPIC_MODEL` 또는 설정 파일의 `model` 필드에 설정된 경우 해당 값을 제거하거나 업데이트하여 각 시작 시 알림이 반복되지 않도록 합니다.

866* 제한된 모델에 액세스해야 하면 조직 관리자에게 활성화를 요청합니다. [조직 모델 제한](/ko/model-config#organization-model-restrictions)을 참조하십시오.916* 제한된 모델에 대한 액세스가 필요한 경우 조직 관리자에게 활성화를 요청합니다. [조직 모델 제한](/ko/model-config#organization-model-restrictions)을 참조합니다.

867 917

868<h3 id="thinking-type-enabled-is-not-supported-for-this-model">918<h3 id="thinking-type-enabled-is-not-supported-for-this-model">

869 thinking.type.enabled is not supported for this model919 thinking.type.enabled는 이 모델에서 지원되지 않습니다

870</h3>920</h3>

871 921

872Claude Code 버전이 Sonnet 5, Opus 4.8 또는 Opus 4.7의 최소값보다 오래되었습니다. CLI가 모델이 더 이상 허용하지 않는 생각 구성을 보냈습니다.922Claude Code 버전이 Sonnet 5, Opus 4.8 또는 Opus 4.7의 최소값보다 오래되었습니다. CLI가 모델이 더 이상 허용하지 않는 사고 구성을 보냈습니다.

873 923

874```text theme={null}924```text theme={null}

875API Error: 400 ... "thinking.type.enabled" is not supported for this model. Use "thinking.type.adaptive" and "output_config.effort" to control thinking behavior.925API Error: 400 ... "thinking.type.enabled" is not supported for this model. Use "thinking.type.adaptive" and "output_config.effort" to control thinking behavior.

876```926```

877 927

878**할 일:**928**수행할 작업:**

~~879~~

880{/* min-version: 2.1.197 */}}

881 929

882* `claude update`를 실행하고 Claude Code를 다시 시작합니다. Opus 4.7은 v2.1.111 이상이 필요합니다. Opus 4.8은 v2.1.154 이상이 필요합니다. Sonnet 5는 v2.1.197 이상이 필요합니다.930* `claude update`를 실행하고 Claude Code를 다시 시작합니다. Opus 4.7은 v2.1.111 이상이 필요합니다. Opus 4.8은 v2.1.154 이상이 필요합니다. Sonnet 5는 v2.1.197 이상이 필요합니다.

883* 업그레이드할 수 없으면 `/model`을 실행하고 Opus 4.6 또는 Sonnet 4.6을 선택합니다.931* 업그레이드할 수 없으면 `/model`을 실행하고 대신 Opus 4.6 또는 Sonnet 4.6을 선택합니다.

884* {/* min-version: agent-sdk@0.3.197 */}}[Agent SDK](/ko/agent-sdk/overview)에서 이를 맞으면 SDK 패키지를 대신 업그레이드합니다. Opus 4.8은 TypeScript SDK v0.3.154 이상과 Python SDK v0.2.88 이상이 필요합니다. Sonnet 5는 TypeScript SDK v0.3.197 이상이 필요합니다.932* {/* min-version: agent-sdk@0.3.197 */}[Agent SDK](/ko/agent-sdk/overview)에서 이것을 맞으면 SDK 패키지를 대신 업그레이드합니다. Opus 4.8은 TypeScript SDK v0.3.154 이상 및 Python SDK v0.2.88 이상이 필요합니다. Sonnet 5는 TypeScript SDK v0.3.197 이상이 필요합니다.

885 933

886<h3 id="thinking-budget-exceeds-output-limit">934<h3 id="thinking-budget-exceeds-output-limit">

887 Thinking budget exceeds output limit935 사고 예산이 출력 제한을 초과합니다

888</h3>936</h3>

889 937

890구성된 확장 생각 예산이 최대 응답 길이를 초과하므로 실제 답변을 위한 공간이 남지 않습니다.938구성된 확장 사고 예산이 최대 응답 길이를 초과하므로 실제 답변을 위한 공간이 남지 않습니다.

891 939

892```text theme={null}940```text theme={null}

893API Error: 400 ... max_tokens must be greater than thinking.budget_tokens941API Error: 400 ... max_tokens must be greater than thinking.budget_tokens

894```942```

895 943

896Claude Code는 Anthropic API에서 이러한 값을 자동으로 조정합니다. 일반적으로 [`MAX_THINKING_TOKENS`](/ko/env-vars)이 제공자의 출력 제한보다 높게 설정되었거나 플랜 모드가 생각 예산을 높일 때 Amazon Bedrock 또는 Google Vertex AI에서 이 오류를 봅니다.944Claude Code는 Anthropic API에서 이러한 값을 자동으로 조정합니다. 일반적으로 [`MAX_THINKING_TOKENS`](/ko/env-vars)가 공급자의 출력 제한보다 높게 설정되었거나 계획 모드가 사고 예산을 높일 때 Amazon Bedrock 또는 Google Cloud의 Agent Platform에서 이 오류가 표시됩니다.

897 945

898**할 일:**946**수행할 작업:**

899 947

900* `MAX_THINKING_TOKENS`를 낮추거나 [`CLAUDE_CODE_MAX_OUTPUT_TOKENS`](/ko/env-vars)를 생각 예산 위로 높입니다.948* `MAX_THINKING_TOKENS`를 낮추거나 [`CLAUDE_CODE_MAX_OUTPUT_TOKENS`](/ko/env-vars)를 사고 예산 위로 올립니다.

901* [확장 생각](/ko/model-config#extended-thinking)을 참조하여 예산이 출력 길이와 어떻게 상호 작용하는지 확인합니다.949* [확장 사고](/ko/model-config#extended-thinking)를 참조하여 예산이 출력 길이와 어떻게 상호 작용하는지 확인합니다.

902 950

903<h3 id="tool-use-or-thinking-block-mismatch">951<h3 id="tool-use-or-thinking-block-mismatch">

904 Tool use or thinking block mismatch952 도구 사용 또는 사고 블록 불일치

905</h3>953</h3>

906 954

907대화 기록이 일관성 없는 상태로 API에 도달했습니다. 일반적으로 도구 호출이 중단되거나 턴이 스트림 중간에 편집된 후입니다.955대화 기록이 API에 일관성 없는 상태로 도달했습니다. 일반적으로 도구 호출이 중단되거나 턴이 스트림 중간에 편집된 후입니다.

908 956

909```text theme={null}957```text theme={null}

910API Error: 400 due to tool use concurrency issues. Run /rewind to recover the conversation.958API Error: 400 due to tool use concurrency issues. Run /rewind to recover the conversation.

912API Error: 400 ... thinking blocks ... cannot be modified960API Error: 400 ... thinking blocks ... cannot be modified

913```961```

914 962

915세 가지 변형 모두 동일한 의미입니다. 기록의 `tool_use`, `tool_result`, `thinking` 블록 시퀀스가 더 이상 API가 예상하는 것과 일치하지 않습니다.963세 가지 변형 모두 동일한 의미입니다: 기록의 `tool_use`, `tool_result` 및 `thinking` 블록의 시퀀스가 더 이상 API가 예상하는 것과 일치하지 않습니다.

916 964

917**할 일:**965**수행할 작업:**

918 966

919* {/* max-version: 2.1.155 */}}Opus 4.7 또는 Opus 4.8을 사용하는 경우 먼저 `claude update`를 실행합니다. v2.1.156 이전 버전은 정상적인 도구 사용 중에 이 오류를 트리거할 수 있으며 `/rewind`는 이를 지우지 않습니다.967* {/* max-version: 2.1.155 */}Opus 4.7 또는 Opus 4.8을 사용하는 경우 먼저 `claude update`를 실행합니다. v2.1.156 이전 버전은 정상적인 도구 사용 중에 이 오류를 트리거할 수 있으며 `/rewind`는 이를 지우지 않습니다.

920* `/rewind`를 실행하거나 Esc를 두 번 눌러 손상된 턴 전의 체크포인트로 뒤로 이동하고 거기서 계속합니다. [체크포인팅](/ko/checkpointing)을 참조하여 체크포인트가 생성되고 복원되는 방식을 확인합니다.968* `/rewind`를 실행하거나 Esc를 두 번 눌러 손상된 턴 전의 체크포인트로 뒤로 이동하고 거기서 계속합니다. [체크포인팅](/ko/checkpointing)을 참조하여 체크포인트가 어떻게 생성되고 복원되는지 확인합니다.

921 969

922<h3 id="usage-policy-refusal">970<h3 id="usage-policy-refusal">

923 Usage Policy refusal971 사용 정책 거부

924</h3>972</h3>

925 973

926API가 대화의 내용이 [사용 정책](https://www.anthropic.com/legal/aup) 확인을 트리거했기 때문에 응답을 거부했습니다. 메시지에는 거부가 잘못되었다고 생각하는 경우 지원팀에 인용할 수 있는 요청 ID가 포함됩니다.974API가 대화의 콘텐츠가 [사용 정책](https://www.anthropic.com/legal/aup) 확인을 트리거했기 때문에 응답을 거부했습니다. 메시지에는 거부가 잘못되었다고 생각하는 경우 지원팀에 인용할 수 있는 요청 ID가 포함됩니다.

927 975

928```text theme={null}976```text theme={null}

929API Error: Claude Code is unable to respond to this request, which appears to violate our Usage Policy (https://www.anthropic.com/legal/aup). Please double press esc to edit your last message or start a new session for Claude Code to assist with a different task.977API Error: Claude Code is unable to respond to this request, which appears to violate our Usage Policy (https://www.anthropic.com/legal/aup). Please double press esc to edit your last message or start a new session for Claude Code to assist with a different task.

930```978```

931 979

932확인은 최신 프롬프트뿐만 아니라 전체 대화를 평가하므로 동일한 세션에서 새 메시지를 보내면 일반적으로 동일한 거부를 다시 트리거합니다. `--continue` 또는 `--resume`으로 세션을 종료하고 다시 열 때도 마찬가지입니다. 디스크의 기록에 여전히 트리거 콘텐츠가 포함되어 있기 때문입니다.980확인은 최신 프롬프트뿐만 아니라 전체 대화를 평가하므로 동일한 세션에서 새 메시지를 보내면 일반적으로 동일한 거부를 다시 트리거합니다. `--continue` 또는 `--resume`으로 세션을 종료하고 다시 열 때도 마찬가지입니다. 디스크의 기록에 여전히 트리거 콘텐츠가 포함되어 있기 때문입니다. [Amazon Bedrock](/ko/amazon-bedrock), [Google Cloud의 Agent Platform](/ko/google-vertex-ai) 및 [Microsoft Foundry](/ko/microsoft-foundry)에서 이 메시지는 모델의 안전 조치가 사이버 보안 주제로 플래그한 요청도 포함합니다. [안전 조치가 사이버 보안 주제를 플래그했습니다](#safety-measures-flagged-a-cybersecurity-topic)를 참조합니다.

933 981

934**할 일:**982**수행할 작업:**

935 983

936* Esc를 두 번 누르거나 `/rewind`를 실행하여 거부를 트리거한 턴 전의 체크포인트로 뒤로 이동한 후 다시 표현하거나 다른 접근 방식을 시도합니다. [체크포인팅](/ko/checkpointing)을 참조하십시오.984* Esc를 두 번 누르거나 `/rewind`를 실행하여 거부를 트리거한 턴 전의 체크포인트로 뒤로 이동한 다음 다시 표현하거나 다른 접근 방식을 취합니다. [체크포인팅](/ko/checkpointing)을 참조합니다.

937* 어느 턴이 원인인지 식별할 수 없으면 `/clear`를 실행하여 동일한 프로젝트에서 새 대화를 시작합니다. 이전 대화는 디스크에 보존되며 `/resume`에서 사용 가능합니다.985* 어느 턴이 원인인지 식별할 수 없으면 `/clear`를 실행하여 동일한 프로젝트에서 새 대화를 시작합니다. 이전 대화는 디스크에 보존되며 `/resume`에서 사용 가능합니다.

938* [비대화형 모드](/ko/headless)(`-p`)에서는 되감기를 사용할 수 없으므로 다시 표현된 프롬프트로 다시 시도하거나 `--continue` 없이 새 세션을 시작합니다. 정책 확인은 모델에 따라 다르므로 `--model`로 다른 모델로 전환하면 일부 경우에 거부를 해결할 수도 있습니다.986* [비대화형 모드](/ko/headless)(`-p`)에서는 되감기를 사용할 수 없으므로 `--continue` 없이 새 세션에서 다시 표현된 프롬프트로 다시 시도합니다. 정책 확인은 모델에 따라 다르므로 `--model`로 다른 모델로 전환하면 일부 경우에 거부를 해결할 수도 있습니다.

987

988<h3 id="safety-measures-flagged-a-cybersecurity-topic">

989 안전 조치가 사이버 보안 주제를 플래그했습니다

990</h3>

991

992모델의 안전 조치가 대화의 콘텐츠를 사이버 보안 주제로 플래그했습니다. 메시지는 요청을 플래그한 모델의 이름을 지정합니다:

993

994```text theme={null}

995API Error: Opus 4.8 has safety measures that flagged this message for a cybersecurity topic. To learn about the Cyber Verification Program and apply for access, visit our help center: https://support.claude.com/en/articles/14604842-real-time-cyber-safeguards-on-claude.

996

997If you were not engaging in a cybersecurity topic, please send feedback via /feedback.

998```

999

1000메시지는 정당한 사이버 보안 작업에 대한 액세스를 부여하는 [사이버 검증 프로그램](https://support.claude.com/en/articles/14604842-real-time-cyber-safeguards-on-claude)에 연결됩니다. 보안 조치 자체는 서버 측이며 v2.1.203보다 앞서 있습니다. 이 릴리스는 메시지의 표현과 연결되는 페이지만 변경했습니다.

1001

1002표시되는 내용은 공급자 및 모드에 따라 다릅니다:

1003

1004* [Amazon Bedrock](/ko/amazon-bedrock), [Google Cloud의 Agent Platform](/ko/google-vertex-ai) 및 [Microsoft Foundry](/ko/microsoft-foundry)에서 사이버 보안 플래그는 대신 [사용 정책 거부](#usage-policy-refusal) 메시지를 생성합니다.

1005* [비대화형 모드](/ko/headless)는 `/feedback` 문장을 생략합니다.

1006

1007{/* max-version: 2.1.202 */}v2.1.203 이전에는 메시지가 `<model>'s safeguards flagged this message for a cybersecurity topic. If your work requires this access, you can apply for an exemption:` 다음에 면제 양식 링크를 읽었습니다.

1008

1009**수행할 작업:**

1010

1011* 작업에 이 콘텐츠가 필요한 경우 [사이버 검증 프로그램](https://support.claude.com/en/articles/14604842-real-time-cyber-safeguards-on-claude)을 통해 액세스를 신청합니다.

1012* 요청이 사이버 보안 주제가 아닌 경우 `/feedback`을 실행하여 거짓 양성을 보고합니다.

1013* 동일한 세션에서 계속 작업하려면 Esc를 두 번 누르거나 `/rewind`를 실행하여 플래그를 트리거한 턴 전의 체크포인트로 뒤로 이동한 다음 다른 접근 방식을 취합니다. [체크포인팅](/ko/checkpointing)을 참조합니다.

1014

1015<h2 id="installation-errors">

1016 설치 오류

1017</h2>

1018

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

1020

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

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

1023</h3>

1024

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

1026

1027```text theme={null}

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

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

1030```

1031

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

1033

1034**수행할 작업:**

1035

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

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

1038

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

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

1041</h3>

1042

1043`claude install`, `claude update` 또는 [자동 업데이터](/ko/setup#auto-updates)가 Claude Code 바이너리를 가져오는 동안 다운로드 서버로의 연결이 끊어졌으며, 재시도로 복구되지 않았습니다. Claude Code는 연결이 끊어지거나, 전송이 중단되거나, 다운로드된 파일이 체크섬에 실패할 때 다운로드를 재시도하며, 총 3번까지 시도합니다. 404와 같은 완료된 HTTP 오류는 서버가 이미 응답했기 때문에 재시도되지 않습니다. {/* min-version: 2.1.202 */}v2.1.202 이전에는 단일 연결 끊김이 재시도 대신 단순한 오류 `aborted`로 다운로드를 즉시 실패했습니다.

1044

1045```text theme={null}

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

1047```

1048

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

1050

1051연결은 유지되지만 10분 이내에 완료되지 않는 다운로드는 `Download timed out: exceeded the total deadline` 대신 실패합니다. Claude Code는 시간 초과된 다운로드를 재시도하지 않습니다. 왜냐하면 기한 내에 완료하기에 너무 느린 연결은 즉시 재시도에서도 완료되지 않기 때문입니다. 아래 단계는 두 메시지 모두에 적용됩니다. v2.1.205 이전에는 동일한 10분 기한이 HTTP 클라이언트의 일반적인 `timeout of 600000ms exceeded`로 보고되었습니다.

1052

1053일반적인 원인은 전송이 완료되기 전에 긴 전송을 닫는 프록시 또는 게이트웨이입니다. Claude Code 바이너리는 큰 다운로드이므로, 일반 API 트래픽에는 영향을 주지 않는 프록시 연결 제한이 여전히 이를 중단할 수 있습니다.

1054

1055**수행할 작업:**

1056

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

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

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

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

939 1061

940<h2 id="command-line-errors">1062<h2 id="command-line-errors">

941 명령줄 오류1063 명령줄 오류

942</h2>1064</h2>

943 1065

944이러한 오류는 Claude Code의 `claude` 명령줄 자체 검증에서 나옵니다. Claude Code는 세션을 생성하거나 API 요청을 보내기 전에 즉시 인쇄합니다.1066이러한 오류는 `claude` 명령줄 및 해당 하위 명령에서 발생합니다. Claude Code는 프롬프트를 실행하거나 API 요청을 보내기 전에 이를 출력합니다.

945 1067

946<h3 id="conflict-between-bg-and-print">1068<h3 id="conflict-between-bg-and-print">

947 Conflict between --bg and --print1069 \--bg와 --print 간의 충돌

948</h3>1070</h3>

949 1071

950{/* min-version: 2.1.198 */}}1072이 메시지는 Claude Code v2.1.198 이상이 필요합니다. 동일한 `claude` 호출에서 `--bg`를 `-p` 또는 `--print`와 결합했습니다. `--bg`는 나중에 `claude agents`로 연결할 수 있는 [백그라운드 세션](/ko/agent-view#from-your-shell)을 시작하는 반면, `--print`는 [비대화형](/ko/headless)으로 실행되며 `claude agents`가 연결하는 대화형 세션을 시작하지 않습니다. v2.1.198 이전에는 이 조합이 자동으로 연결할 수 없는 백그라운드 작업을 생성했습니다.

951이 메시지는 Claude Code v2.1.198 이상이 필요합니다. 동일한 `claude` 호출에서 `--bg`를 `-p` 또는 `--print`와 결합했습니다. `--bg`는 나중에 `claude agents`로 첨부하는 [백그라운드 세션](/ko/agent-view#from-your-shell)을 시작하는 반면 `--print`는 [비대화형](/ko/headless)으로 실행되며 `claude agents`가 첨부하는 대화형 세션을 시작하지 않습니다. v2.1.198 이전에는 이 조합이 자동으로 첨부할 수 없는 백그라운드 작업을 자동으로 생성했습니다.

952 1073

953```text theme={null}1074```text theme={null}

954--bg and --print conflict: --print never starts the interactive session that `claude agents` attaches to, so the job would be unattachable. The prompt is the positional — drop --print: `claude --bg '<task>'`.1075--bg and --print conflict: --print never starts the interactive session that `claude agents` attaches to, so the job would be unattachable. The prompt is the positional — drop --print: `claude --bg '<task>'`.

955```1076```

956 1077

957**할 일:**1078**수행할 작업:**

1079

1080* `-p` 또는 `--print`를 제거합니다. `--bg`는 프롬프트를 위치 인수로 사용하므로 `claude --bg "<task>"`가 완전한 명령입니다. [셸에서 새 에이전트 디스패치](/ko/agent-view#from-your-shell)를 참조하세요.

1081* 프롬프트를 비대화형으로 실행하고 백그라운드 세션을 만드는 대신 결과를 출력하려면 `--bg`를 제거하고 `claude -p "<task>"`를 실행합니다.

1082

1083<h3 id="the-json-schema-value-is-not-a-valid-json-schema">

1084 \--json-schema 값이 유효한 JSON Schema가 아닙니다

1085</h3>

1086

1087[비대화형 모드](/ko/headless#get-structured-output)에서 [`--json-schema`](/ko/cli-reference#cli-flags)에 전달한 스키마가 JSON Schema 컴파일에 실패했으므로 `claude`는 프롬프트를 실행하는 대신 코드 1로 종료됩니다. v2.1.205 이전에는 유효하지 않은 스키마가 오류 없이 구조화되지 않은 출력을 생성했으며, `format` 키워드를 사용한 모든 스키마는 유효하지 않은 것으로 처리되었습니다.

1088

1089```text theme={null}

1090Error: --json-schema is not a valid JSON Schema: data/type must be equal to one of the allowed values

1091```

1092

1093두 번째 콜론 뒤의 텍스트는 검증자의 진단이며 실패한 키워드 또는 위치를 나타냅니다. `"format": "email"`과 같은 `format` 키워드를 사용하는 스키마는 유효합니다. Claude Code는 `format`을 주석으로 허용하며 이를 적용하지 않습니다.

1094

1095Claude Code는 스키마 컴파일 전에 두 가지 검사를 실행합니다. 구문 분석할 수 없는 JSON 값을 `Error: --json-schema is not valid JSON`으로 거부하고, 객체가 아닌 유효한 JSON을 `Error: --json-schema must be a JSON object`로 거부합니다.

1096

1097**수행할 작업:**

1098

1099* 진단이 명시한 스키마 부분을 수정한 후 명령을 다시 실행합니다.

1100* 진단이 `schema too large`인 경우 스키마의 중첩 및 `$ref` 재사용을 줄입니다.

1101* [구조화된 출력 가져오기](/ko/headless#get-structured-output)에서 작동하는 스키마 및 명령을 참조하세요.

1102

1103<h3 id="could-not-import-a-server-from-claude-desktop">

1104 Claude Desktop에서 서버를 가져올 수 없습니다

1105</h3>

1106

1107Claude Code는 `claude mcp add-from-claude-desktop`에서 선택한 서버 중 하나를 추가할 수 없습니다. 명령은 여전히 다른 선택된 서버를 가져오고 추가할 수 없는 각 서버마다 한 줄을 출력합니다. v2.1.205 이전에는 실패한 첫 번째 서버가 가져오기를 중지했으며 선택된 서버 중 어느 것도 추가되지 않았습니다.

1108

1109```text theme={null}

1110Could not import my server: Invalid name my server. Names can only contain letters, numbers, hyphens, and underscores.

1111```

1112

1113서버 이름 뒤의 텍스트가 이유입니다. 가장 일반적인 것은 이름 검사입니다. Claude Desktop은 서버 이름에 공백 및 마침표와 같은 문자를 허용하지만 `claude mcp`는 문자, 숫자, 하이픈 및 밑줄로만 제한합니다. 다른 이유로는 검증에 실패한 서버 구성과 조직의 [MCP 정책](/ko/managed-mcp)에 의해 차단된 서버가 있습니다.

1114

1115**수행할 작업:**

1116

1117* `claude_desktop_config.json`에서 서버 이름을 문자, 숫자, 하이픈 및 밑줄만 사용하도록 변경한 후 `claude mcp add-from-claude-desktop`을 다시 실행합니다.

1118* 유효한 이름으로 `claude mcp add` 또는 `claude mcp add-json`을 사용하여 해당 서버를 직접 추가합니다. [Claude Desktop에서 MCP 서버 가져오기](/ko/mcp#import-mcp-servers-from-claude-desktop)를 참조하세요.

1119

1120<h2 id="plugin-errors">

1121 플러그인 오류

1122</h2>

1123

1124이러한 오류는 [플러그인](/ko/plugins) 및 [마켓플레이스](/ko/plugin-marketplaces) 구성에서 발생합니다. 이 페이지의 메시지 중 하나를 생성하지 않는 플러그인 문제(예: 로드되지 않는 마켓플레이스 URL 또는 설치되지만 나타나지 않는 플러그인)의 경우 [플러그인 문제 해결](/ko/discover-plugins#troubleshooting)을 참조하십시오.

1125

1126<h3 id="marketplace-is-registered-from-an-untrusted-source">

1127 마켓플레이스가 신뢰할 수 없는 소스에서 등록됨

1128</h3>

1129

1130마켓플레이스가 [공식 Anthropic 마켓플레이스용으로 예약된](/ko/plugin-marketplaces#marketplace-schema) 이름으로 등록되어 있지만, 등록된 소스가 `anthropics` GitHub 저장소가 아닙니다. Claude Code는 마켓플레이스를 로드하거나 새로고침할 때마다 예약된 이름을 다시 확인하므로, 마켓플레이스와 여기서 설치된 플러그인이 로드되지 않습니다. v2.1.205 이전에는 마켓플레이스가 추가될 때만 이름이 확인되었으므로, 이름이 예약되기 전에 등록된 항목은 계속 로드되었습니다.

1131

1132```text theme={null}

1133Marketplace "claude-community" is registered from an untrusted source: The name 'claude-community' is reserved for official Anthropic marketplaces. Only repositories from 'github.com/anthropics/' can use this name. To fix it, remove the marketplace and re-add it from the official source.

1134```

1135

1136**수행할 작업:**

958 1137

959* `-p` 또는 `--print`를 제거합니다. `--bg`는 프롬프트를 위치 인수로 사용하므로 `claude --bg "<task>"`가 완전한 명령입니다. [셸에서 새 에이전트 디스패치](/ko/agent-view#from-your-shell)를 참조하십시오.1138* `claude plugin marketplace remove <name>`을 실행한 다음, 공식 `github.com/anthropics` 저장소에서 마켓플레이스를 다시 추가합니다

960* 프롬프트를 비대화형으로 실행하고 백그라운드 세션을 생성하는 대신 결과를 인쇄하려면 `--bg`를 제거하고 `claude -p "<task>"`를 실행합니다.1139* 이름이 예약되기 전에 해당 이름을 사용한 타사 마켓플레이스를 게시한 경우, 이름을 바꾸고 사용자에게 소스에서 다시 추가하도록 요청합니다

1140* [마켓플레이스 스키마](/ko/plugin-marketplaces#marketplace-schema)에서 예약된 이름 목록을 참조합니다

1141

1142<h2 id="configuration-warnings">

1143 구성 경고

1144</h2>

1145

1146Claude Code는 이러한 메시지를 시작 시 대화에 오류로 표시하지 않고 stderr에 기록합니다. 이는 읽었지만 적용하지 않은 구성을 보고합니다.

1147

1148<h3 id="workspace-has-not-been-trusted">

1149 작업 공간이 신뢰되지 않음

1150</h3>

1151

1152Claude Code는 프로젝트의 `.claude/settings.json` 또는 `.claude/settings.local.json`에서 `permissions.allow` 규칙 또는 `permissions.additionalDirectories` 항목을 찾았지만 [프로젝트 설정의 allow 규칙은 작업 공간 신뢰가 필요](/ko/permissions#project-allow-rules-and-workspace-trust)하기 때문에 적용하지 않았습니다. 메시지의 개수, 설정 이름 및 파일 이름은 구성에 따라 다릅니다. `deny` 및 `ask` 규칙은 영향을 받지 않습니다.

1153

1154```text theme={null}

1155Ignoring 2 permissions.allow entries from .claude/settings.local.json: this workspace has not been trusted. Run Claude Code interactively here once and accept the trust dialog, or set projects["/Users/you/project"].hasTrustDialogAccepted: true in /Users/you/.claude.json.

1156```

1157

1158**수행할 작업:**

1159

1160* 디렉터리에서 `claude`를 실행하고 신뢰 대화를 수락합니다. {/* min-version: 2.1.200 */}부모 디렉터리가 이미 신뢰된 경우에도 대화가 나타나며, 보류 중인 규칙을 나열하고 거절하여 규칙 없이 계속 작업할 수 있습니다. v2.1.200 이전에는 해당 상황에서 대화가 나타나지 않았으므로 이 단계를 완료할 수 없었습니다.

1161* `-p`를 사용한 [비대화형 모드](/ko/headless)에서는 대화가 표시되지 않습니다. 메시지가 출력하는 정확한 `projects` 키를 사용하여 `~/.claude.json`에서 `hasTrustDialogAccepted` 항목을 설정합니다.

1162* {/* min-version: 2.1.200 */}메시지에 `.claude/settings.local.json`이 명시되어 있고 git 저장소 외부 또는 홈 디렉터리에서 Claude Code를 시작한 경우 v2.1.200 이상으로 업데이트합니다. 버전 2.1.196부터 2.1.199까지는 해당 작업 공간에서 자신의 `.claude/settings.local.json`을 저장소 제공으로 취급했습니다. [프로젝트 allow 규칙 및 작업 공간 신뢰](/ko/permissions#project-allow-rules-and-workspace-trust)를 참조하세요.

961 1163

962<h2 id="responses-seem-lower-quality-than-usual">1164<h2 id="responses-seem-lower-quality-than-usual">

963 응답 품질이 평소보다 낮아 보임1165 응답 품질이 평소보다 낮아 보입니다

964</h2>1166</h2>

965 1167

966Claude의 답변이 오류 없이 예상보다 덜 유능해 보이면 원인은 일반적으로 모델 자체가 아닌 대화 상태입니다. Claude Code는 모델 버전을 자동으로 변경하지 않습니다. 세 가지 특정 경우에 대체 모델로 전환할 수 있습니다.1168Claude의 답변이 예상보다 능력이 떨어져 보이지만 오류가 표시되지 않는 경우, 원인은 일반적으로 모델 자체가 아니라 대화 상태입니다. Claude Code는 자동으로 모델 버전을 변경하지 않습니다. 다음 세 가지 특정 경우에만 폴백 모델로 전환할 수 있습니다.

1169

1170* 구성된 [`--fallback-model`](/ko/cli-reference#cli-flags)은 가용성 오류 후 해당 턴에만 인수를 받으며, 트랜스크립트에 공지가 표시됩니다.

1171* Amazon Bedrock 또는 Google Cloud의 Agent Platform 시작 확인에서 기본 모델을 사용할 수 없음을 발견합니다.

1172* [자동 모델 폴백](/ko/model-config#automatic-model-fallback)이 Fable 5에서 세션을 기본 Opus 모델로 이동하고 트랜스크립트에 공지를 표시합니다.

967 1173

968* 구성된 [`--fallback-model`](/ko/cli-reference#cli-flags)은 가용성 오류 후 해당 턴에만 인수를 받으며, 기록에 공지가 표시됩니다.1174아래의 모델 선택 확인은 두 번째 및 세 번째 경우를 포착합니다. 첫 번째는 `/model` 변경이 아닌 트랜스크립트 공지로 나타납니다. [모델 구성](/ko/model-config)에서 각 폴백이 적용되는 시기를 설명합니다.

969* Bedrock 또는 Vertex AI 시작 확인에서 기본 모델을 사용할 수 없음을 발견합니다.

970* [자동 모델 대체](/ko/model-config#automatic-model-fallback)는 Fable 5에서 세션을 기본 Opus 모델로 이동하고 기록에 공지를 표시합니다.

971 1175

972아래의 모델 선택 확인이 두 번째와 세 번째 경우를 포착합니다. 첫 번째는 `/model` 변경이 아닌 기록 공지로 나타납니다. [모델 구성](/ko/model-config)은 각 대체가 적용되는 시기를 설명합니다.1176먼저 다음을 확인하십시오.

973 1177

974먼저 다음을 확인합니다.1178* **모델 선택**: `/model`을 실행하여 예상하는 모델에 있는지 확인합니다. 이전 `/model` 선택 또는 `ANTHROPIC_MODEL` 환경 변수로 인해 의도한 것보다 작은 모델에 있을 수 있습니다.

1179* **노력 수준**: `/effort`를 실행하여 현재 추론 수준을 확인하고 어려운 디버깅 또는 설계 작업을 위해 수준을 높입니다. 기본값은 모델에 따라 다르므로 최대값 이하에 있다고 가정하기 전에 확인하십시오. 모델별 기본값 및 `ultrathink` 단축키는 [노력 수준 조정](/ko/model-config#adjust-effort-level)을 참조하십시오.

1180* **컨텍스트 압력**: `/context`를 실행하여 윈도우가 얼마나 찼는지 확인합니다. 용량에 가까우면 자연스러운 지점에서 `/compact`를 실행하거나 `/clear`를 실행하여 새로 시작합니다. [컨텍스트 윈도우 탐색](/ko/context-window)에서 자동 압축이 이전 턴에 어떻게 영향을 미치는지 확인하십시오.

1181* **오래된 지침**: 크거나 오래된 `CLAUDE.md` 파일 및 MCP 도구 정의는 컨텍스트를 소비하고 응답을 조종할 수 있습니다. {/* min-version: 2.1.205 */}`/doctor` 점검은 과도한 메모리 파일 및 사용하지 않는 확장 프로그램에 플래그를 지정하며, `/context`는 MCP 도구 토큰 사용량을 표시합니다. v2.1.205 이전에는 `/doctor`가 과도한 메모리 파일 및 서브에이전트 정의에 플래그를 지정하는 진단 화면을 열었습니다.

975 1182

976* **모델 선택**: `/model`을 실행하여 예상한 모델에 있는지 확인합니다. 이전 `/model` 선택 또는 `ANTHROPIC_MODEL` 환경 변수가 의도한 것보다 더 작은 모델에 있을 수 있습니다.1183응답이 잘못되면 수정으로 회신하는 것보다 되감기가 일반적으로 더 잘 작동합니다. Esc를 두 번 누르거나 `/rewind`를 실행하여 잘못된 턴 이전으로 돌아간 다음 더 구체적인 프롬프트로 다시 표현합니다. 스레드 내에서 수정하면 잘못된 시도가 컨텍스트에 남아 있어 나중의 답변을 고정시킬 수 있습니다. [체크포인팅](/ko/checkpointing)을 참조하십시오.

977* **노력 수준**: `/effort`를 실행하여 현재 추론 수준을 확인하고 어려운 디버깅 또는 설계 작업을 위해 높입니다. 기본값은 모델에 따라 다르므로 최대값 아래에 있다고 가정하기 전에 확인합니다. [노력 수준 조정](/ko/model-config#adjust-effort-level)을 참조하여 모델별 기본값 및 `ultrathink` 바로가기를 확인합니다.

978* **컨텍스트 압력**: `/context`를 실행하여 윈도우가 얼마나 가득 찼는지 확인합니다. 용량에 가까우면 자연스러운 중단점에서 `/compact`를 실행하거나 새로 시작하려면 `/clear`를 실행합니다. [컨텍스트 윈도우 탐색](/ko/context-window)을 참조하여 자동 압축이 이전 턴에 어떻게 영향을 미치는지 확인합니다.

979* **오래된 지침**: 크거나 오래된 `CLAUDE.md` 파일 및 MCP 도구 정의는 컨텍스트를 소비하고 응답을 조종할 수 있습니다. `/doctor`는 과도한 크기의 메모리 파일 및 서브에이전트 정의를 플래그합니다. `/context`는 MCP 도구 토큰 사용을 표시합니다.

980 1184

981응답이 잘못되면 수정으로 회신하는 것보다 일반적으로 되감기가 더 잘 작동합니다. Esc를 두 번 누르거나 `/rewind`를 실행하여 나쁜 턴 전으로 뒤로 이동한 후 더 구체적으로 프롬프트를 다시 표현합니다. 스레드 내에서 수정하면 잘못된 시도가 컨텍스트에 남아 있어 나중의 답변을 이에 고정할 수 있습니다. [체크포인팅](/ko/checkpointing)을 참조하십시오.1185위의 항목을 확인한 후에도 품질이 여전히 좋지 않으면 `/feedback`을 실행하고 예상한 것과 실제로 받은 것을 설명합니다. 이 방식으로 제출된 피드백에는 대화 트랜스크립트가 포함되어 있으며, 이는 Anthropic이 실제 회귀를 진단하는 가장 빠른 방법입니다. 환경에서 `/feedback`을 사용할 수 없는 경우 [오류 보고](#report-an-error)를 참조하십시오.

982 1186

983위의 확인 후에도 품질이 여전히 이상해 보이면 `/feedback`을 실행하고 예상한 것과 얻은 것을 설명합니다. 이 방식으로 제출된 피드백에는 대화 기록이 포함되어 있으므로 Anthropic이 실제 회귀를 진단하는 가장 빠른 방법입니다. 환경에서 `/feedback`을 사용할 수 없는 경우 [오류 보고](#report-an-error)를 참조하십시오.1187{/* min-version: 2.1.201 */}Sonnet 5가 요청을 거부하고 Claude Code v2.1.200 이전 버전에서 의심되는 프롬프트 주입을 인용하는 경우 `claude update`를 실행하여 v2.1.201 수정을 선택합니다.

984 1188

985<h2 id="report-an-error">1189<h2 id="report-an-error">

986 오류 보고1190 오류 보고

987</h2>1191</h2>

988 1192

989이 페이지는 Claude Code 런타임 오류를 다룹니다. 다른 구성 요소의 오류는 관련 가이드를 참조하십시오.1193이 페이지에서 다루지 않는 구성 요소의 오류는 관련 가이드를 참조하십시오:

990 1194

991* MCP 서버가 연결 또는 인증에 실패함: [MCP](/ko/mcp)1195* MCP 서버 연결 또는 인증 실패: [MCP](/ko/mcp)

992* 훅 스크립트가 실패했거나 도구를 차단함: [훅 디버그](/ko/hooks#debug-hooks)1196* 훅 스크립트 실패 또는 도구 차단: [Debug hooks](/ko/hooks#debug-hooks)

993* 설치 중 권한 거부 또는 파일 시스템 오류: [설치 및 로그인 문제 해결](/ko/troubleshoot-install)1197* 설치 중 권한 거부 또는 파일 시스템 오류: [Troubleshoot installation and login](/ko/troubleshoot-install)

994 1198

995오류가 여기에 나열되지 않았거나 제안된 수정이 도움이 되지 않으면:1199오류가 여기에 나열되지 않았거나 제안된 해결 방법이 도움이 되지 않는 경우:

996 1200

997* Claude Code 내에서 `/feedback`을 실행하여 기록 및 설명을 Anthropic에 보냅니다. 명령은 미리 채워진 GitHub 문제를 열 수도 있습니다. Bedrock, Vertex AI, Foundry 및 기타 타사 제공자에서 `/feedback`은 Anthropic 계정 담당자에게 보낼 수 있는 로컬 아카이브를 저장합니다.1201* Claude Code 내에서 `/feedback`을 실행하여 기록 및 설명을 Anthropic에 전송하십시오. 이 명령은 미리 작성된 GitHub 이슈를 열 수 있는 옵션도 제공합니다. Amazon Bedrock, Google Cloud의 Agent Platform, Microsoft Foundry 및 기타 타사 제공자에서는 `/feedback`이 Anthropic 계정 담당자에게 보낼 수 있는 로컬 아카이브를 저장합니다.

998* `/doctor`를 실행하여 로컬 구성 문제를 확인합니다.1202* 셸에서 `claude doctor`를 실행하여 설치의 읽기 전용 진단을 수행하거나, Claude Code 내에서 `/doctor` 점검을 실행하여 설정 문제를 찾고 해결하십시오

999* [status.claude.com](https://status.claude.com)에서 활성 인시던트를 확인합니다.1203* [status.claude.com](https://status.claude.com)에서 활성 인시던트를 확인하십시오

1000* GitHub의 [기존 문제](https://github.com/anthropics/claude-code/issues)를 검색합니다.1204* GitHub의 [기존 이슈](https://github.com/anthropics/claude-code/issues)를 검색하십시오

fast-mode.md +2 −2

Details

38* `/fast`를 입력하고 Tab을 눌러 켜거나 끕니다38* `/fast`를 입력하고 Tab을 눌러 켜거나 끕니다

39* [사용자 설정 파일](/ko/settings)에서 `"fastMode": true`를 설정합니다39* [사용자 설정 파일](/ko/settings)에서 `"fastMode": true`를 설정합니다

40 40

41기본적으로 빠른 모드는 세션 간에 유지됩니다. 관리자는 빠른 모드를 각 세션마다 재설정하도록 구성할 수 있습니다. 자세한 내용은 [세션별 옵트인 필요](#require-per-session-opt-in)를 참조합니다.41기본적으로 빠른 모드는 대화형 세션에서 켜면 세션 간에 유지됩니다. {/* min-version: 2.1.205 */}[비대화형 모드](/ko/headless)에서 `-p` 플래그를 사용하면, `/fast`는 [`--settings`](/ko/cli-reference#cli-flags) 값에 빠른 모드가 켜져 있는 상태로 시작된 세션에서만 작동합니다. 예를 들어 `claude -p --settings '{"fastMode": true}'`와 같이 사용하면, 토글이 해당 세션에만 적용되며 기본값으로 저장되지 않으며, 다른 비대화형 세션에서는 빠른 모드를 사용할 수 없다는 명령 보고가 나타납니다. 관리자는 빠른 모드를 각 세션마다 재설정하도록 구성할 수 있습니다. 자세한 내용은 [세션별 옵트인 필요](#require-per-session-opt-in)를 참조합니다.

42 42

43최상의 비용 효율성을 위해 대화 중간에 전환하기보다는 세션 시작 시 빠른 모드를 활성화합니다. 자세한 내용은 [비용 트레이드오프 이해](#understand-the-cost-tradeoff)를 참조합니다.43최상의 비용 효율성을 위해 대화 중간에 전환하기보다는 세션 시작 시 빠른 모드를 활성화합니다. 자세한 내용은 [비용 트레이드오프 이해](#understand-the-cost-tradeoff)를 참조합니다.

44 44

103 103

104빠른 모드는 다음 모두를 필요로 합니다:104빠른 모드는 다음 모두를 필요로 합니다:

105 105

106* **Anthropic API 또는 구독만 해당**: 빠른 모드는 Anthropic Console API 및 사용 크레딧을 사용하는 Claude 구독 요금제를 통해 사용할 수 있습니다. Amazon Bedrock, Google Vertex AI, Microsoft Azure Foundry 또는 AWS의 Claude Platform에서는 사용할 수 없습니다.106* **Anthropic API 또는 구독만 해당**: 빠른 모드는 Anthropic Console API 및 사용 크레딧을 사용하는 Claude 구독 요금제를 통해 사용할 수 있습니다. Amazon Bedrock, Google Cloud의 Agent Platform, Microsoft Foundry 또는 AWS의 Claude Platform에서는 사용할 수 없습니다.

107* **사용 크레딧 활성화**: 계정에 사용 크레딧이 활성화되어 있어야 하며, 이를 통해 요금제의 포함된 사용량을 초과하여 청구할 수 있습니다. 개인 계정의 경우 [Console 청구 설정](https://platform.claude.com/settings/organization/billing)에서 활성화합니다. Team 및 Enterprise의 경우 관리자가 조직에 대해 사용 크레딧을 활성화해야 합니다.107* **사용 크레딧 활성화**: 계정에 사용 크레딧이 활성화되어 있어야 하며, 이를 통해 요금제의 포함된 사용량을 초과하여 청구할 수 있습니다. 개인 계정의 경우 [Console 청구 설정](https://platform.claude.com/settings/organization/billing)에서 활성화합니다. Team 및 Enterprise의 경우 관리자가 조직에 대해 사용 크레딧을 활성화해야 합니다.

108 108

109<Note>109<Note>

feature-availability.md +16 −16

Details

4 4

5# 기능 가용성5# 기능 가용성

6 6

~~7> Anthropic 구독 플랜, Anthropic Console, Amazon Bedrock, AWS의 Claude Platform, Google Vertex AI, Microsoft Foundry에서 사용 가능한 Claude Code 기능을 비교합니다.~~7> Anthropic 구독 플랜, Anthropic Console, Amazon Bedrock, AWS의 Claude Platform, Google Cloud의 Agent Platform, Microsoft Foundry에서 사용 가능한 Claude Code 기능을 비교합니다.

8 8

9Claude Code CLI와 로컬에서 실행되는 모든 것은 모든 제공자에서 동일하게 작동합니다. 제공자별 설정 지침은 [엔터프라이즈 배포 개요](/ko/third-party-integrations)를 참조하십시오. 제공자에서 누락된 기능을 바로 확인하려면 [제공자별 요약](#summary-by-provider) 탭을 참조하십시오.9Claude Code CLI와 로컬에서 실행되는 모든 것은 모든 제공자에서 동일하게 작동합니다. 제공자별 설정 지침은 [엔터프라이즈 배포 개요](/ko/third-party-integrations)를 참조하십시오. 제공자에서 누락된 기능을 바로 확인하려면 [제공자별 요약](#summary-by-provider) 탭을 참조하십시오.

10 10

18 18

19* **Claude 구독**: claude.ai 계정으로 Pro, Max, Team 또는 Enterprise 플랜에 로그인합니다.19* **Claude 구독**: claude.ai 계정으로 Pro, Max, Team 또는 Enterprise 플랜에 로그인합니다.

20* **Anthropic Console**: Anthropic API 키로 인증합니다.20* **Anthropic Console**: Anthropic API 키로 인증합니다.

21* **Amazon Bedrock**: Bedrock 모델 카탈로그에서 Claude 모델을 사용하고 `CLAUDE_CODE_USE_BEDROCK`을 설정합니다. [Mantle 엔드포인트](/ko/amazon-bedrock#use-the-mantle-endpoint) (`CLAUDE_CODE_USE_MANTLE`)는 이 열에 포함됩니다.21* **Amazon Bedrock**: Amazon Bedrock 모델 카탈로그에서 Claude 모델을 사용하고 `CLAUDE_CODE_USE_BEDROCK`을 설정합니다. [Mantle 엔드포인트](/ko/amazon-bedrock#use-the-mantle-endpoint) (`CLAUDE_CODE_USE_MANTLE`)는 이 열에 포함됩니다.

22* **AWS의 Claude Platform**: AWS Marketplace를 통해 Claude를 구입했지만 Anthropic API를 호출하고 `CLAUDE_CODE_USE_ANTHROPIC_AWS`를 설정합니다.22* **AWS의 Claude Platform**: AWS Marketplace를 통해 Claude를 구입했지만 Anthropic API를 호출하고 `CLAUDE_CODE_USE_ANTHROPIC_AWS`를 설정합니다.

~~23* **Google Vertex AI**: Google 운영; `CLAUDE_CODE_USE_VERTEX`를 설정합니다.~~23* **Google Cloud의 Agent Platform**: Google 운영; `CLAUDE_CODE_USE_VERTEX`를 설정합니다.

24* **Microsoft Foundry**: Azure의 Anthropic 운영; `CLAUDE_CODE_USE_FOUNDRY`를 설정합니다.24* **Microsoft Foundry**: Azure의 Anthropic 운영; `CLAUDE_CODE_USE_FOUNDRY`를 설정합니다.

25 25

26<h3 id="features-available-on-every-provider">26<h3 id="features-available-on-every-provider">

53* [Artifacts](/ko/artifacts): Pro, Max, Team 및 Enterprise 플랜53* [Artifacts](/ko/artifacts): Pro, Max, Team 및 Enterprise 플랜

54* [음성 받아쓰기](/ko/voice-dictation)54* [음성 받아쓰기](/ko/voice-dictation)

55 55

56Desktop은 부분적인 예외입니다: Enterprise 배포는 [관리되는 설정](https://support.claude.com/en/articles/12622667-enterprise-configuration)을 통해 Desktop을 Vertex AI 또는 게이트웨이 제공자로 라우팅할 수 있으며, [Cowork on 3P 연구 미리보기](https://claude.com/docs/cowork/3p/overview)는 Bedrock, Vertex AI, Foundry 또는 자체 호스팅 LLM 게이트웨이에서 Code 탭을 실행합니다. 이러한 기능의 플랜별 가용성은 [구독 플랜별 가용성](#availability-by-subscription-plan)을 참조하십시오.56Desktop은 부분적인 예외입니다: Enterprise 배포는 [관리되는 설정](https://support.claude.com/en/articles/12622667-enterprise-configuration)을 통해 Desktop을 Google Cloud의 Agent Platform 또는 게이트웨이 제공자로 라우팅할 수 있으며, [Claude Desktop on 3P](https://claude.com/docs/third-party/claude-desktop/overview)는 Amazon Bedrock, Google Cloud의 Agent Platform, Microsoft Foundry 또는 자체 호스팅 LLM 게이트웨이에서 Code 탭을 실행합니다. 이러한 기능의 플랜별 가용성은 [구독 플랜별 가용성](#availability-by-subscription-plan)을 참조하십시오.

57 57

58<h3 id="cli-capabilities-that-vary-by-provider">58<h3 id="cli-capabilities-that-vary-by-provider">

59 제공자별로 다양한 CLI 기능59 제공자별로 다양한 CLI 기능

69 <th>Anthropic Console</th>69 <th>Anthropic Console</th>

70 <th>Amazon Bedrock</th>70 <th>Amazon Bedrock</th>

71 <th>AWS의 Claude Platform</th>71 <th>AWS의 Claude Platform</th>

~~72 <th>Google Vertex AI</th>~~72 <th>Google Cloud의 Agent Platform</th>

73 <th>Microsoft Foundry</th>73 <th>Microsoft Foundry</th>

74 </tr>74 </tr>

75 </thead>75 </thead>

161 <th>Anthropic Console</th>161 <th>Anthropic Console</th>

162 <th>Amazon Bedrock</th>162 <th>Amazon Bedrock</th>

163 <th>AWS의 Claude Platform</th>163 <th>AWS의 Claude Platform</th>

164 <th>Google Vertex AI</th>164 <th>Google Cloud의 Agent Platform</th>

165 <th>Microsoft Foundry</th>165 <th>Microsoft Foundry</th>

166 </tr>166 </tr>

167 </thead>167 </thead>

199 </tbody>199 </tbody>

200</table>200</table>

201 201

202<span id="fn1" style={{display: 'block', position: 'relative', top: '-120px'}} /><sup>1</sup> Vertex AI에서는 Claude 4 모델 이상에서 웹 검색을 사용할 수 있습니다.<br />202<span id="fn1" style={{display: 'block', position: 'relative', top: '-120px'}} /><sup>1</sup> Google Cloud의 Agent Platform에서는 Claude 4 모델 이상에서 웹 검색을 사용할 수 있습니다.<br />

203<span id="fn2" style={{display: 'block', position: 'relative', top: '-120px'}} /><sup>2</sup> `CLAUDE_CODE_ENABLE_AUTO_MODE`가 필요합니다. [자동 모드 구성](/ko/auto-mode-config)을 참조하십시오.<br />203<span id="fn2" style={{display: 'block', position: 'relative', top: '-120px'}} /><sup>2</sup> `CLAUDE_CODE_ENABLE_AUTO_MODE`가 필요합니다. [자동 모드 구성](/ko/auto-mode-config)을 참조하십시오.<br />

204<span id="fn3" style={{display: 'block', position: 'relative', top: '-120px'}} /><sup>3</sup> `/loop every 2 hours`와 같은 명시적 간격은 모든 제공자에서 작동합니다. Bedrock, Vertex AI, Foundry에서는 `/loop`가 자신의 간격을 선택하거나 기본 유지 관리 프롬프트를 제공할 수 없으므로 간격이 없는 프롬프트는 10분마다 실행되고 인수가 없는 `/loop`는 사용 메시지를 표시합니다. [예약된 작업](/ko/scheduled-tasks)을 참조하십시오.<br />204<span id="fn3" style={{display: 'block', position: 'relative', top: '-120px'}} /><sup>3</sup> `/loop every 2 hours`와 같은 명시적 간격은 모든 제공자에서 작동합니다. Amazon Bedrock, Google Cloud의 Agent Platform, Microsoft Foundry에서는 `/loop`가 자신의 간격을 선택하거나 기본 유지 관리 프롬프트를 제공할 수 없으므로 간격이 없는 프롬프트는 10분마다 실행되고 인수가 없는 `/loop`는 사용 메시지를 표시합니다. [예약된 작업](/ko/scheduled-tasks)을 참조하십시오.<br />

205<span id="fn4" style={{display: 'block', position: 'relative', top: '-120px'}} /><sup>4</sup> 클라우드 제공자와의 계약에 따릅니다.<br />205<span id="fn4" style={{display: 'block', position: 'relative', top: '-120px'}} /><sup>4</sup> 클라우드 제공자와의 계약에 따릅니다.<br />

206<span id="fn5" style={{display: 'block', position: 'relative', top: '-120px'}} /><sup>5</sup> 대시보드 및 API만 해당합니다. [기여도 메트릭](/ko/analytics#enable-contribution-metrics)은 claude.ai Team 또는 Enterprise 조직이 필요합니다.206<span id="fn5" style={{display: 'block', position: 'relative', top: '-120px'}} /><sup>5</sup> 대시보드 및 API만 해당합니다. [기여도 메트릭](/ko/analytics#enable-contribution-metrics)은 claude.ai Team 또는 Enterprise 조직이 필요합니다.

207 207

213 제공자별 요약213 제공자별 요약

214</h3>214</h3>

215 215

216각 탭은 해당 제공자에서 사용할 수 없거나 부분적으로 지원되는 기능을 나열하며, 대안이 있는 경우 대안을 제시합니다. 나열되지 않은 모든 기능은 Claude 구독과 동일하게 작동합니다. Bedrock, Vertex AI, Foundry, AWS의 Claude Platform에서는 Anthropic에 대한 오류 보고 및 원격 분석이 기본적으로 꺼져 있습니다. [API 제공자별 기본 동작](/ko/data-usage#default-behaviors-by-api-provider)에서 여전히 Anthropic에 도달하는 트래픽과 옵트아웃 방법을 확인하십시오.216각 탭은 해당 제공자에서 사용할 수 없거나 부분적으로 지원되는 기능을 나열하며, 대안이 있는 경우 대안을 제시합니다. 나열되지 않은 모든 기능은 Claude 구독과 동일하게 작동합니다. Amazon Bedrock, Google Cloud의 Agent Platform, Microsoft Foundry, AWS의 Claude Platform에서는 Anthropic에 대한 오류 보고 및 원격 분석이 기본적으로 꺼져 있습니다. [API 제공자별 기본 동작](/ko/data-usage#default-behaviors-by-api-provider)에서 여전히 Anthropic에 도달하는 트래픽과 옵트아웃 방법을 확인하십시오.

217 217

218<Tabs>218<Tabs>

219 <Tab title="Amazon Bedrock">219 <Tab title="Amazon Bedrock">

221 221

222 **부분 지원:**222 **부분 지원:**

223 223

224 * [Desktop](/ko/desktop): [Cowork on 3P 연구 미리보기](https://claude.com/docs/cowork/3p/overview)를 통해서만224 * [Desktop](/ko/desktop): [Claude Desktop on 3P](https://claude.com/docs/third-party/claude-desktop/overview)를 통해서만

225 * [자동 모드](/ko/auto-mode-config): `CLAUDE_CODE_ENABLE_AUTO_MODE` 설정225 * [자동 모드](/ko/auto-mode-config): `CLAUDE_CODE_ENABLE_AUTO_MODE` 설정

226 * [`/loop`](/ko/scheduled-tasks): 명시적 간격만226 * [`/loop`](/ko/scheduled-tasks): 명시적 간격만

227 * [Zero Data Retention](/ko/zero-data-retention): AWS 계약에 따름227 * [Zero Data Retention](/ko/zero-data-retention): AWS 계약에 따름

237 **대안:** 스케줄링의 경우 `/schedule` 대신 [`/loop`](/ko/scheduled-tasks)를 사용하십시오. 클라우드 세션의 경우 [GitHub Actions](/ko/github-actions) 또는 [GitLab CI/CD](/ko/gitlab-ci-cd)를 사용하십시오.237 **대안:** 스케줄링의 경우 `/schedule` 대신 [`/loop`](/ko/scheduled-tasks)를 사용하십시오. 클라우드 세션의 경우 [GitHub Actions](/ko/github-actions) 또는 [GitLab CI/CD](/ko/gitlab-ci-cd)를 사용하십시오.

238 </Tab>238 </Tab>

239 239

240 <Tab title="Google Vertex AI">240 <Tab title="Google Cloud의 Agent Platform">

241 **사용 불가능:** 모든 [Claude 구독이 필요한 기능](#features-that-require-a-claude-subscription), 그리고 [빠른 모드](/ko/fast-mode), [Advisor](/ko/advisor), [Channels](/ko/channels), [분석 대시보드](/ko/analytics), [서버 관리 설정](/ko/server-managed-settings).241 **사용 불가능:** 모든 [Claude 구독이 필요한 기능](#features-that-require-a-claude-subscription), 그리고 [빠른 모드](/ko/fast-mode), [Advisor](/ko/advisor), [Channels](/ko/channels), [분석 대시보드](/ko/analytics), [서버 관리 설정](/ko/server-managed-settings).

242 242

243 **부분 지원:**243 **부분 지원:**

244 244

245 * [Desktop](/ko/desktop): [관리되는 설정](https://support.claude.com/en/articles/12622667-enterprise-configuration) 또는 [Cowork on 3P 연구 미리보기](https://claude.com/docs/cowork/3p/overview)를 통해245 * [Desktop](/ko/desktop): [관리되는 설정](https://support.claude.com/en/articles/12622667-enterprise-configuration) 또는 [Claude Desktop on 3P](https://claude.com/docs/third-party/claude-desktop/overview)를 통해

246 * [웹 검색](/ko/tools-reference#websearch-tool-behavior): Claude 4 모델 이상246 * [웹 검색](/ko/tools-reference#websearch-tool-behavior): Claude 4 모델 이상

247 * [자동 모드](/ko/auto-mode-config): `CLAUDE_CODE_ENABLE_AUTO_MODE` 설정247 * [자동 모드](/ko/auto-mode-config): `CLAUDE_CODE_ENABLE_AUTO_MODE` 설정

248 * [`/loop`](/ko/scheduled-tasks): 명시적 간격만248 * [`/loop`](/ko/scheduled-tasks): 명시적 간격만

256 256

257 **부분 지원:**257 **부분 지원:**

258 258

259 * [Desktop](/ko/desktop): [Cowork on 3P 연구 미리보기](https://claude.com/docs/cowork/3p/overview)를 통해서만259 * [Desktop](/ko/desktop): [Claude Desktop on 3P](https://claude.com/docs/third-party/claude-desktop/overview)를 통해서만

260 * [자동 모드](/ko/auto-mode-config): `CLAUDE_CODE_ENABLE_AUTO_MODE` 설정260 * [자동 모드](/ko/auto-mode-config): `CLAUDE_CODE_ENABLE_AUTO_MODE` 설정

261 * [`/loop`](/ko/scheduled-tasks): 명시적 간격만261 * [`/loop`](/ko/scheduled-tasks): 명시적 간격만

262 * [Zero Data Retention](/ko/zero-data-retention): Azure 계약에 따름262 * [Zero Data Retention](/ko/zero-data-retention): Azure 계약에 따름

275 구독 플랜별 가용성275 구독 플랜별 가용성

276</h2>276</h2>

277 277

278Bedrock, Vertex AI, Foundry 또는 Anthropic Console API 키를 통해 인증하는 경우 이 섹션은 적용되지 않습니다. claude.ai 계정으로 로그인하면 플랜에 따라 아래 기능의 가용성이 결정됩니다.278Amazon Bedrock, Google Cloud의 Agent Platform, Microsoft Foundry 또는 Anthropic Console API 키를 통해 인증하는 경우 이 섹션은 적용되지 않습니다. claude.ai 계정으로 로그인하면 플랜에 따라 아래 기능의 가용성이 결정됩니다.

279 279

280| 기능 | Pro | Max | Team | Enterprise |280| 기능 | Pro | Max | Team | Enterprise |

281| :-------------------------------------------------------------------------------------- | :-- | :-- | :------ | :-------------------------------- |281| :-------------------------------------------------------------------------------------- | :-- | :-- | :------ | :-------------------------------- |

303 모델 가용성303 모델 가용성

304</h2>304</h2>

305 305

306제공자 및 지역별로 사용 가능한 Claude 모델 및 컨텍스트 윈도우 크기는 [모델 구성](/ko/model-config) 및 [모델 개요](https://platform.claude.com/docs/en/about-claude/models/overview)를 참조하십시오. Vision, PDF 입력, 확장 사고는 Claude Code 기능이 아닌 모델 기능이며 모델을 제공하는 모든 제공자에서 작동합니다. [Prompt caching](/ko/prompt-caching)은 대부분의 제공자에서 동일하게 작동합니다. Bedrock에서는 모델별로 지원이 다릅니다.306제공자 및 지역별로 사용 가능한 Claude 모델 및 컨텍스트 윈도우 크기는 [모델 구성](/ko/model-config) 및 [모델 개요](https://platform.claude.com/docs/en/about-claude/models/overview)를 참조하십시오. Vision, PDF 입력, 확장 사고는 Claude Code 기능이 아닌 모델 기능이며 모델을 제공하는 모든 제공자에서 작동합니다. [Prompt caching](/ko/prompt-caching)은 대부분의 제공자에서 동일하게 작동합니다. Amazon Bedrock에서는 모델별로 지원이 다릅니다.

307 307

308<h2 id="related-resources">308<h2 id="related-resources">

309 관련 리소스309 관련 리소스

310</h2>310</h2>

311 311

312* [엔터프라이즈 배포 개요](/ko/third-party-integrations): 제공자 간 인증, 청구, 지역 비교312* [엔터프라이즈 배포 개요](/ko/third-party-integrations): 제공자 간 인증, 청구, 지역 비교

313* 제공자 설정 가이드: [Amazon Bedrock](/ko/amazon-bedrock), [AWS의 Claude Platform](/ko/claude-platform-on-aws), [Google Vertex AI](/ko/google-vertex-ai), [Microsoft Foundry](/ko/microsoft-foundry)313* 제공자 설정 가이드: [Amazon Bedrock](/ko/amazon-bedrock), [AWS의 Claude Platform](/ko/claude-platform-on-aws), [Google Cloud의 Agent Platform](/ko/google-vertex-ai), [Microsoft Foundry](/ko/microsoft-foundry)

314* [플랫폼 및 통합](/ko/platforms): CLI, Desktop, IDE 확장, 웹, 모바일, CI/CD를 포함한 Claude Code가 실행되는 위치314* [플랫폼 및 통합](/ko/platforms): CLI, Desktop, IDE 확장, 웹, 모바일, CI/CD를 포함한 Claude Code가 실행되는 위치

fullscreen.md +3 −1

Details

170 170

171전체 화면 렌더링은 iTerm2의 tmux 통합 모드와 호환되지 않습니다. 이는 `tmux -CC`로 들어가는 모드입니다. 통합 모드에서 iTerm2는 각 tmux 창을 tmux가 터미널에 그리도록 하는 대신 기본 분할로 렌더링합니다. 대체 화면 버퍼와 마우스 추적이 제대로 작동하지 않습니다: 마우스 휠이 작동하지 않고 더블 클릭이 터미널 상태를 손상시킬 수 있습니다. `tmux -CC` 세션에서 전체 화면 렌더링을 활성화하지 마십시오. `-CC` 없이 iTerm2 내부의 일반 tmux는 정상적으로 작동합니다.171전체 화면 렌더링은 iTerm2의 tmux 통합 모드와 호환되지 않습니다. 이는 `tmux -CC`로 들어가는 모드입니다. 통합 모드에서 iTerm2는 각 tmux 창을 tmux가 터미널에 그리도록 하는 대신 기본 분할로 렌더링합니다. 대체 화면 버퍼와 마우스 추적이 제대로 작동하지 않습니다: 마우스 휠이 작동하지 않고 더블 클릭이 터미널 상태를 손상시킬 수 있습니다. `tmux -CC` 세션에서 전체 화면 렌더링을 활성화하지 마십시오. `-CC` 없이 iTerm2 내부의 일반 tmux는 정상적으로 작동합니다.

172 172

173tmux는 동기화된 출력을 지원하지 않으므로 Claude Code를 터미널에서 직접 실행할 때보다 다시 그리는 동안 더 많은 깜박임이 보일 수 있습니다. 특히 SSH를 통해 깜박임이 눈에 띄는 경우 Claude Code를 tmux 외부의 자체 터미널 탭에서 실행합니다.173모든 tmux 버전이 애플리케이션의 동기화된 출력을 적용하지는 않으므로 Claude Code를 터미널에서 직접 실행할 때보다 tmux 내에서 다시 그리는 동안 더 많은 깜박임이 보일 수 있습니다. 특히 SSH를 통해 깜박임이 눈에 띄는 경우 최신 tmux로 업그레이드하거나 Claude Code를 tmux 외부의 자체 터미널 탭에서 실행합니다. `tmux -V`로 tmux 버전을 확인합니다.

174

175{/* min-version: 2.1.200 */}Claude Code는 `TERM_PROGRAM_VERSION` 변수에서 tmux 3.4 이상을 감지할 때 동기화된 출력을 자동으로 켜고, 버전을 확인할 수 없을 때 동기화된 출력 지원에 대해 터미널에 직접 쿼리하도록 폴백합니다. 다시 그리기가 실제로 원자적이 되는지 여부는 동기화된 출력을 준수하는 tmux 버전에 따라 달라집니다. tmux 3.4 이상에서 여전히 깜박임이 보이면 최신 tmux로 업그레이드합니다. 이 감지에는 Claude Code v2.1.200 이상이 필요합니다.

174 176

175<h2 id="keep-native-text-selection">177<h2 id="keep-native-text-selection">

176 기본 텍스트 선택 유지178 기본 텍스트 선택 유지

github-actions.md +24 −24

Details

51<Note>51<Note>

52 * GitHub 앱을 설치하고 시크릿을 추가하려면 저장소 관리자여야 합니다52 * GitHub 앱을 설치하고 시크릿을 추가하려면 저장소 관리자여야 합니다

53 * GitHub 앱은 Contents, Issues 및 Pull requests에 대한 읽기 및 쓰기 권한을 요청합니다53 * GitHub 앱은 Contents, Issues 및 Pull requests에 대한 읽기 및 쓰기 권한을 요청합니다

54 * 이 빠른 시작 방법은 직접 Claude API 사용자만 사용할 수 있습니다. Amazon Bedrock 또는 Google Vertex AI를 사용 중인 경우 [Amazon Bedrock & Google Vertex AI 사용](#using-with-amazon-bedrock-%26-google-vertex-ai) 섹션을 참조하십시오.54 * 이 빠른 시작 방법은 직접 Claude API 사용자만 사용할 수 있습니다. Amazon Bedrock 또는 Google Cloud의 Agent Platform을 사용 중인 경우 [Amazon Bedrock 및 Google Cloud 사용](#using-with-amazon-bedrock-and-google-cloud) 섹션을 참조하십시오.

55</Note>55</Note>

56 56

57<h2 id="manual-setup">57<h2 id="manual-setup">

320 이슈 또는 PR 댓글에 응답할 때 Claude는 자동으로 @claude 멘션에 응답합니다. 다른 이벤트의 경우 `prompt` 파라미터를 사용하여 지침을 제공합니다.320 이슈 또는 PR 댓글에 응답할 때 Claude는 자동으로 @claude 멘션에 응답합니다. 다른 이벤트의 경우 `prompt` 파라미터를 사용하여 지침을 제공합니다.

321</Tip>321</Tip>

322 322

323<h2 id="using-with-amazon-bedrock--google-vertex-ai">323<h2 id="using-with-amazon-bedrock-and-google-cloud">

324 Amazon Bedrock & Google Vertex AI 사용324 Amazon Bedrock 및 Google Cloud 사용

325</h2>325</h2>

326 326

327엔터프라이즈 환경의 경우 자신의 클라우드 인프라와 함께 Claude Code GitHub Actions를 사용할 수 있습니다. 이 접근 방식은 동일한 기능을 유지하면서 데이터 거주지 및 청구에 대한 제어를 제공합니다.327엔터프라이즈 환경의 경우 자신의 클라우드 인프라와 함께 Claude Code GitHub Actions를 사용할 수 있습니다. 이 접근 방식은 동일한 기능을 유지하면서 데이터 거주지 및 청구에 대한 제어를 제공합니다.

332 332

333클라우드 공급자와 함께 Claude Code GitHub Actions를 설정하기 전에 다음이 필요합니다:333클라우드 공급자와 함께 Claude Code GitHub Actions를 설정하기 전에 다음이 필요합니다:

334 334

335<h4 id="for-google-cloud-vertex-ai">335<h4 id="for-google-cloud’s-agent-platform">

336 Google Cloud Vertex AI의 경우:336 Google Cloud의 Agent Platform의 경우:

337</h4>337</h4>

338 338

3391. Vertex AI가 활성화된 Google Cloud 프로젝트3391. Google Cloud의 Agent Platform이 활성화된 Google Cloud 프로젝트

3402. GitHub Actions에 대해 구성된 Workload Identity Federation3402. GitHub Actions에 대해 구성된 Workload Identity Federation

3413. 필요한 권한이 있는 서비스 계정3413. 필요한 권한이 있는 서비스 계정

3424. GitHub 앱(권장) 또는 기본 GITHUB\_TOKEN 사용3424. GitHub 앱(권장) 또는 기본 GITHUB\_TOKEN 사용

347 347

3481. Amazon Bedrock이 활성화된 AWS 계정3481. Amazon Bedrock이 활성화된 AWS 계정

3492. AWS에서 구성된 GitHub OIDC Identity Provider3492. AWS에서 구성된 GitHub OIDC Identity Provider

3503. Bedrock 권한이 있는 IAM 역할3503. Amazon Bedrock 권한이 있는 IAM 역할

3514. GitHub 앱(권장) 또는 기본 GITHUB\_TOKEN 사용3514. GitHub 앱(권장) 또는 기본 GITHUB\_TOKEN 사용

352 352

353<Steps>353<Steps>

354 <Step title="사용자 정의 GitHub 앱 생성 (3P 공급자에 권장)">354 <Step title="사용자 정의 GitHub 앱 생성 (3P 공급자에 권장)">

355 Vertex AI 또는 Bedrock과 같은 3P 공급자를 사용할 때 최상의 제어 및 보안을 위해 자신의 GitHub 앱을 생성하는 것이 좋습니다:355 Google Cloud의 Agent Platform 또는 Amazon Bedrock과 같은 3P 공급자를 사용할 때 최상의 제어 및 보안을 위해 자신의 GitHub 앱을 생성하는 것이 좋습니다:

356 356

357 1. [https://github.com/settings/apps/new로](https://github.com/settings/apps/new로) 이동합니다357 1. [https://github.com/settings/apps/new로](https://github.com/settings/apps/new로) 이동합니다

358 2. 기본 정보를 입력합니다:358 2. 기본 정보를 입력합니다:

428 자세한 OIDC 설정 지침은 [AWS 설명서](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_providers_create_oidc.html)를 참조하십시오.428 자세한 OIDC 설정 지침은 [AWS 설명서](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_providers_create_oidc.html)를 참조하십시오.

429 </Accordion>429 </Accordion>

430 430

431 <Accordion title="Google Vertex AI">431 <Accordion title="Google Cloud의 Agent Platform">

432 **자격 증명을 저장하지 않고 GitHub Actions가 안전하게 인증할 수 있도록 Google Cloud를 구성합니다.**432 **자격 증명을 저장하지 않고 GitHub Actions가 안전하게 인증할 수 있도록 Google Cloud를 구성합니다.**

433 433

434 > **보안 참고**: 저장소별 구성을 사용하고 최소 필요 권한만 부여합니다.434 > **보안 참고**: 저장소별 구성을 사용하고 최소 필요 권한만 부여합니다.

438 1. **Google Cloud 프로젝트에서 API 활성화**:438 1. **Google Cloud 프로젝트에서 API 활성화**:

439 * IAM Credentials API439 * IAM Credentials API

440 * Security Token Service (STS) API440 * Security Token Service (STS) API

441 * Vertex AI API441 * Google Cloud의 Agent Platform API

442 442

443 2. **Workload Identity Federation 리소스 생성**:443 2. **Workload Identity Federation 리소스 생성**:

444 * Workload Identity Pool 생성444 * Workload Identity Pool 생성

483 * `APP_ID`: GitHub 앱의 ID483 * `APP_ID`: GitHub 앱의 ID

484 * `APP_PRIVATE_KEY`: 개인 키 (.pem) 내용484 * `APP_PRIVATE_KEY`: 개인 키 (.pem) 내용

485 485

486 #### Google Cloud Vertex AI의 경우486 #### Google Cloud의 Agent Platform의 경우

487 487

488 1. **GCP 인증의 경우**:488 1. **GCP 인증의 경우**:

489 * `GCP_WORKLOAD_IDENTITY_PROVIDER`489 * `GCP_WORKLOAD_IDENTITY_PROVIDER`

504 </Step>504 </Step>

505 505

506 <Step title="워크플로우 파일 생성">506 <Step title="워크플로우 파일 생성">

507 클라우드 공급자와 통합되는 GitHub Actions 워크플로우 파일을 생성합니다. 아래 예제는 Amazon Bedrock 및 Google Vertex AI 모두에 대한 완전한 구성을 보여줍니다:507 클라우드 공급자와 통합되는 GitHub Actions 워크플로우 파일을 생성합니다. 아래 예제는 Amazon Bedrock 및 Google Cloud의 Agent Platform 모두에 대한 완전한 구성을 보여줍니다:

508 508

509 <AccordionGroup>509 <AccordionGroup>

510 <Accordion title="Amazon Bedrock 워크플로우">510 <Accordion title="Amazon Bedrock 워크플로우">

512 512

513 * Amazon Bedrock 액세스가 Claude 모델 권한으로 활성화됨513 * Amazon Bedrock 액세스가 Claude 모델 권한으로 활성화됨

514 * GitHub가 AWS에서 OIDC ID 공급자로 구성됨514 * GitHub가 AWS에서 OIDC ID 공급자로 구성됨

515 * GitHub Actions를 신뢰하는 Bedrock 권한이 있는 IAM 역할515 * GitHub Actions를 신뢰하는 Amazon Bedrock 권한이 있는 IAM 역할

516 516

517 **필수 GitHub 시크릿:**517 **필수 GitHub 시크릿:**

518 518

519 | 시크릿 이름 | 설명 |519 | 시크릿 이름 | 설명 |

520 | -------------------- | ------------------------ |520 | -------------------- | ------------------------------- |

524 524

573 ```573 ```

574 574

575 <Tip>575 <Tip>

576 Bedrock의 모델 ID 형식에는 지역 접두사가 포함됩니다 (예: `us.anthropic.claude-sonnet-4-6`).576 Amazon Bedrock의 모델 ID 형식에는 지역 접두사가 포함됩니다 (예: `us.anthropic.claude-sonnet-4-6`).

577 </Tip>577 </Tip>

578 </Accordion>578 </Accordion>

579 579

580 <Accordion title="Google Vertex AI 워크플로우">580 <Accordion title="Google Cloud의 Agent Platform 워크플로우">

581 **필수 조건:**581 **필수 조건:**

582 582

583 * GCP 프로젝트에서 Vertex AI API 활성화됨583 * GCP 프로젝트에서 Google Cloud의 Agent Platform API 활성화됨

584 * GitHub에 대해 구성된 Workload Identity Federation584 * GitHub에 대해 구성된 Workload Identity Federation

585 * Vertex AI 권한이 있는 서비스 계정585 * Google Cloud의 Agent Platform 권한이 있는 서비스 계정

586 586

587 **필수 GitHub 시크릿:**587 **필수 GitHub 시크릿:**

588 588

589 | 시크릿 이름 | 설명 |589 | 시크릿 이름 | 설명 |

590 | -------------------------------- | --------------------------------- |590 | -------------------------------- | -------------------------------------------------- |

595 595

675 인증 오류675 인증 오류

676</h3>676</h3>

677 677

678API 키가 유효하고 충분한 권한이 있는지 확인합니다. Bedrock/Vertex의 경우 자격 증명 구성을 확인하고 시크릿이 워크플로우에서 올바르게 명명되었는지 확인합니다.678API 키가 유효하고 충분한 권한이 있는지 확인합니다. Amazon Bedrock 또는 Google Cloud의 Agent Platform의 경우 자격 증명 구성을 확인하고 시크릿이 워크플로우에서 올바르게 명명되었는지 확인합니다.

679 679

680<h2 id="advanced-configuration">680<h2 id="advanced-configuration">

681 고급 구성681 고급 구성

697| `github_token` | API 액세스용 GitHub 토큰 | 아니오 |697| `github_token` | API 액세스용 GitHub 토큰 | 아니오 |

698| `trigger_phrase` | 사용자 정의 트리거 구문 (기본값: "@claude") | 아니오 |698| `trigger_phrase` | 사용자 정의 트리거 구문 (기본값: "@claude") | 아니오 |

699| `use_bedrock` | Claude API 대신 Amazon Bedrock 사용 | 아니오 |699| `use_bedrock` | Claude API 대신 Amazon Bedrock 사용 | 아니오 |

700| `use_vertex` | Claude API 대신 Google Vertex AI 사용 | 아니오 |700| `use_vertex` | Claude API 대신 Google Cloud의 Agent Platform 사용 | 아니오 |

701 701

702\*프롬프트는 선택 사항입니다. 이슈/PR 댓글에서 생략하면 Claude는 트리거 구문에 응답합니다\702\*프롬프트는 선택 사항입니다. 이슈/PR 댓글에서 생략하면 Claude는 트리거 구문에 응답합니다\

703\*\*직접 Claude API에 필수이며, Bedrock/Vertex에는 필수가 아닙니다703\*\*직접 Claude API에 필수이며, Amazon Bedrock 또는 Google Cloud의 Agent Platform에는 필수가 아닙니다

704 704

705<h4 id="pass-cli-arguments">705<h4 id="pass-cli-arguments">

706 CLI 인수 전달706 CLI 인수 전달

github-enterprise-server.md +62 −27

Details

10 GitHub Enterprise Server 지원은 Team 및 Enterprise 플랜에서 사용 가능합니다.10 GitHub Enterprise Server 지원은 Team 및 Enterprise 플랜에서 사용 가능합니다.

11</Note>11</Note>

12 12

13GitHub Enterprise Server(GHES) 지원을 통해 조직은 github.com 대신 자체 관리되는 GitHub 인스턴스에 호스팅된 저장소와 함께 Claude Code를 사용할 수 있습니다. 관리자가 GHES 인스턴스를 연결하면 개발자는 저장소별 구성 없이 웹 세션을 실행하고, 자동화된 코드 리뷰를 받으며, 내부 마켓플레이스에서 플러그인을 설치할 수 있습니다.13GitHub Enterprise Server(GHES) 지원을 통해 조직은 github.com 대신 자체 관리되는 GitHub 인스턴스에 호스팅된 저장소와 함께 Claude Code를 사용할 수 있습니다. 관리자가 GHES 인스턴스를 연결하면 개발자는 저장소별 구성 없이 웹 세션을 실행하고 자동화된 코드 리뷰를 받을 수 있습니다. 인스턴스에 호스팅된 플러그인 마켓플레이스도 지원되며, 자격 증명 요구 사항은 [GHES의 플러그인 마켓플레이스](#plugin-marketplaces-on-ghes)에 설명된 대로 표면에 따라 다릅니다.

14 14

15github.com의 저장소의 경우 [웹에서 Claude Code](/ko/claude-code-on-the-web) 및 [코드 리뷰](/ko/code-review)를 참조하십시오. 자신의 CI 인프라에서 Claude를 실행하려면 [GitHub Actions](/ko/github-actions)를 참조하십시오.15github.com의 저장소의 경우 [웹에서 Claude Code](/ko/claude-code-on-the-web) 및 [코드 리뷰](/ko/code-review)를 참조하십시오. 자신의 CI 인프라에서 Claude를 실행하려면 [GitHub Actions](/ko/github-actions)를 참조하십시오.

16 16

21아래 표는 Claude Code의 어떤 기능이 GHES를 지원하는지 및 github.com 동작과의 차이점을 보여줍니다.21아래 표는 Claude Code의 어떤 기능이 GHES를 지원하는지 및 github.com 동작과의 차이점을 보여줍니다.

22 22

23| 기능 | GHES 지원 | 참고 |23| 기능 | GHES 지원 | 참고 |

~~24| :-------------- | :-------- | :------------------------------------------------------------------------------------------------------ |~~24| :-------------- | :-------- | :----------------------------------------------------------------------------------------------------- |

25| 웹에서 Claude Code | ✅ 지원됨 | 관리자가 GHES 인스턴스를 한 번 연결하면 개발자는 평소처럼 `claude --remote` 또는 [claude.ai/code](https://claude.ai/code)를 사용합니다 |25| 웹에서 Claude Code | ✅ 지원됨 | 관리자가 GHES 인스턴스를 한 번 연결하면 개발자는 `claude --cloud` 또는 [claude.ai/code](https://claude.ai/code)를 평소처럼 사용합니다 |

26| 코드 리뷰 | ✅ 지원됨 | github.com과 동일한 자동화된 PR 리뷰 |26| 코드 리뷰 | ✅ 지원됨 | github.com과 동일한 자동화된 PR 리뷰 |

27| Claude Security | ✅ 지원됨 | Enterprise 플랜의 공개 베타에서 [claude.ai/security](https://claude.ai/security)에서 사용 가능 |27| Claude Security | ✅ 지원됨 | Enterprise 플랜의 공개 베타에서 [claude.ai/security](https://claude.ai/security)에서 사용 가능 |

28| Teleport 세션 | ✅ 지원됨 | `--teleport`를 사용하여 웹과 터미널 간에 세션 이동 |28| Teleport 세션 | ✅ 지원됨 | `--teleport`를 사용하여 웹과 터미널 간에 세션 이동 |

~~29| 플러그인 마켓플레이스 | ✅ 지원됨 | `owner/repo` 단축형 대신 전체 git URL 사용 |~~29| 플러그인 마켓플레이스 | ✅ 지원됨 | 표면별로 자격증명 요구사항이 다릅니다. [GHES의 플러그인 마켓플레이스](#plugin-marketplaces-on-ghes)를 참조하세요 |

30| 기여도 메트릭 | ✅ 지원됨 | [분석 대시보드](/ko/analytics)로 웹훅을 통해 전달됨 |30| 기여도 메트릭 | ✅ 지원됨 | [분석 대시보드](/ko/analytics)로 웹훅을 통해 전달됨 |

31| GitHub Actions | ✅ 지원됨 | 수동 워크플로우 설정 필요; `/install-github-app`은 github.com 전용 |31| GitHub Actions | ✅ 지원됨 | 수동 워크플로우 설정 필요; `/install-github-app`은 github.com 전용 |

107그런 다음 웹 세션을 시작합니다. Claude는 git 원격에서 GHES 호스트를 감지하고 세션을 조직의 구성된 인스턴스를 통해 라우팅합니다:107그런 다음 웹 세션을 시작합니다. Claude는 git 원격에서 GHES 호스트를 감지하고 세션을 조직의 구성된 인스턴스를 통해 라우팅합니다:

108 108

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

110claude --remote "Add retry logic to the payment webhook handler"110claude --cloud "Add retry logic to the payment webhook handler"

111```111```

112 112

113세션은 Anthropic 인프라에서 실행되고, GHES에서 저장소를 복제하며, 변경 사항을 분기로 다시 푸시합니다. `/tasks`를 사용하거나 [claude.ai/code](https://claude.ai/code)에서 진행 상황을 모니터링합니다. diff 리뷰, 자동 수정 및 루틴을 포함한 전체 클라우드 세션 워크플로우는 [웹에서 Claude Code](/ko/claude-code-on-the-web)를 참조하십시오.113세션은 Anthropic 인프라에서 실행되고, GHES에서 저장소를 복제하며, 변경 사항을 분기로 다시 푸시합니다. `/tasks`를 사용하거나 [claude.ai/code](https://claude.ai/code)에서 진행 상황을 모니터링합니다. diff 리뷰, 자동 수정 및 루틴을 포함한 전체 클라우드 세션 워크플로우는 [웹에서 Claude Code](/ko/claude-code-on-the-web)를 참조하십시오.

122 GHES의 플러그인 마켓플레이스122 GHES의 플러그인 마켓플레이스

123</h2>123</h2>

124 124

125조직 전체에 내부 도구를 배포하기 위해 GHES 인스턴스에서 플러그인 마켓플레이스를 호스팅합니다. 마켓플레이스 구조는 github.com 호스팅 마켓플레이스와 동일합니다. 유일한 차이점은 이를 참조하는 방식입니다.125조직 전체에 내부 도구를 배포하기 위해 GHES 인스턴스에서 플러그인 마켓플레이스를 호스팅합니다. 마켓플레이스 구조는 github.com 호스팅 마켓플레이스와 동일하지만, 마켓플레이스를 추가하는 위치에 따라 설치 방식이 다르며, 표면에 따라 자격 증명이 다릅니다:

126

127| 표면 | 설치 방식 | 각 사용자가 필요한 것 |

128| :--------------------------------- | :--------------------------------------------------------------------------------------------------------------------- | :--------------------------------------------------------------------------------------------------------------------- |

129| Claude Code CLI 및 데스크톱 | Claude Code는 머신의 기존 git 자격 증명을 사용하여 마켓플레이스 저장소를 복제합니다 | 머신에서 GHES 호스트에 대한 Git 액세스 |

130| 관리되는 설정 (`extraKnownMarketplaces`) | Claude Code는 항목을 등록하고 머신의 기존 git 자격 증명을 사용하여 저장소를 복제합니다 | 머신에서 GHES 호스트에 대한 Git 액세스 |

131| claude.ai 조직 플러그인 설정 | 소유자가 GHES 인스턴스를 소스로 선택합니다. Anthropic의 백엔드는 [관리자 설정](#admin-setup)의 GitHub App을 사용하여 저장소를 가져오고 동기화합니다 | 추가된 후 사용자당 필요한 것이 없습니다. 이를 추가하는 소유자는 액세스 확인으로 자신의 GitHub Enterprise 계정을 연결해야 하며, GitHub App은 마켓플레이스 저장소에 설치되어야 합니다 |

132| claude.ai 사용자 설정 | Anthropic의 백엔드는 제출하는 사용자의 GitHub Enterprise 연결을 사용하여 저장소를 가져옵니다 | Claude에 연결된 자신의 GitHub Enterprise 계정 |

133| 웹의 Claude Code | 클라우드 세션은 세션 샌드박스 내에서 마켓플레이스를 복제합니다. 샌드박스는 세션의 저장소가 동일한 인스턴스에 있을 때만 GHES 인스턴스에 도달할 수 있으며, git 자격 증명은 세션의 저장소로 범위가 지정됩니다 | GHES 호스팅 마켓플레이스에는 신뢰할 수 없습니다: 세션의 저장소와 다른 호스트는 도달할 수 없으며, 동일한 인스턴스 설치도 실패할 수 있습니다. 대신 CLI, 관리되는 설정 또는 claude.ai를 사용합니다 |

134

135<Warning>

136 claude.ai의 GitHub Enterprise 연결은 사용자 설정에서 마켓플레이스를 추가할 때 사용자별입니다. [관리자 설정](#admin-setup)은 GHES 인스턴스를 조직에 연결하지만 개별 사용자 계정은 연결하지 않습니다: 자신의 설정에서 GHES 마켓플레이스를 추가하는 각 사용자는 먼저 자신의 GitHub Enterprise 계정을 연결해야 하며, 소유자를 포함한 한 사용자의 연결은 다른 사람을 포함하지 않습니다. 조직 플러그인 설정에서 소유자가 추가한 마켓플레이스는 지속적인 가져오기가 조직의 GitHub App을 사용하기 때문에 사용자에게 이 요구 사항을 부과하지 않습니다. 마켓플레이스를 추가하는 소유자는 여전히 추가 시간에 자신의 GitHub Enterprise 계정을 연결해야 합니다.

137</Warning>

126 138

127<h3 id="add-a-ghes-marketplace">139<h3 id="add-a-ghes-marketplace">

128 GHES 마켓플레이스 추가140 GHES 마켓플레이스 추가

129</h3>141</h3>

130 142

131`owner/repo` 단축형은 항상 github.com으로 확인됩니다. GHES 호스팅 마켓플레이스의 경우 전체 git URL을 사용합니다:143`owner/repo` 단축형은 항상 github.com으로 확인됩니다. GHES 호스팅 마켓플레이스의 경우 전체 git URL을 사용합니다. HTTPS URL이 권장됩니다:

132 144

133```bash theme={null}145```bash theme={null}

134/plugin marketplace add git@github.example.com:platform/claude-plugins.git146/plugin marketplace add https://github.example.com/platform/claude-plugins.git

135```147```

136 148

137HTTPS URL도 작동합니다:149머신이 이미 GHES 호스트를 신뢰하는 경우 SSH URL이 작동합니다:

138 150

139```bash theme={null}151```bash theme={null}

140/plugin marketplace add https://github.example.com/platform/claude-plugins.git152/plugin marketplace add git@github.example.com:platform/claude-plugins.git

153```

154

155Claude Code는 git을 비대화형으로 실행하며 머신의 `known_hosts` 파일에 없는 호스트에 대한 SSH 연결을 거부합니다. git 자격 증명 도우미가 있는 HTTPS URL은 `known_hosts` 요구 사항을 피합니다.

156

157마켓플레이스 구축에 대한 전체 가이드는 [플러그인 마켓플레이스 만들기 및 배포](/ko/plugin-marketplaces)를 참조합니다.

158

159<h3 id="pre-register-ghes-marketplaces-with-managed-settings">

160 관리되는 설정으로 GHES 마켓플레이스 사전 등록

161</h3>

162

163`extraKnownMarketplaces` 설정은 마켓플레이스를 사전 등록하여 개발자가 수동 설정 없이 이를 얻을 수 있습니다. 이는 저장소의 `.claude/settings.json`을 포함한 [모든 설정 파일](/ko/settings#extraknownmarketplaces)에서 작동합니다. 관리되는 설정은 조직 전체에 이를 제공합니다:

164

165```json theme={null}

166{

167 "extraKnownMarketplaces": {

168 "internal-tools": {

169 "source": {

170 "source": "git",

171 "url": "https://github.example.com/platform/claude-plugins.git"

172 }

173 }

174 }

175}

141```176```

142 177

143마켓플레이스 구축에 대한 전체 가이드는 [플러그인 마켓플레이스 만들기 및 배포](/ko/plugin-marketplaces)를 참조하십시오.178Claude Code는 이러한 마켓플레이스를 로컬로 설치합니다: 각 항목을 등록하고 머신의 기존 git 자격 증명으로 저장소를 복제합니다. 이 경로는 claude.ai를 거치지 않으므로 사용자별 GitHub Enterprise 연결이 필요하지 않습니다. 성공적인 배포를 위해:

179

180* **전체 git URL을 사용합니다.** `owner/repo` 단축형은 항상 github.com으로 확인되며 GHES 호스트를 참조할 수 없습니다.

181* **HTTPS URL을 선호합니다.** SSH 복제는 이미 GHES 호스트 키를 신뢰하지 않는 머신에서 실패합니다. 조직의 표준 git 자격 증명 도우미가 있는 HTTPS URL은 자격 증명이 구성된 모든 머신에서 작동합니다.

182* **각 머신이 GHES 호스트에서 복제할 수 있는지 확인합니다.** 머신에 자격 증명이 없으면 마켓플레이스는 등록되지만 설치되지 않으며, 플러그인은 자격 증명을 요청하는 대신 찾을 수 없음으로 보고됩니다.

183* **설정이 각 머신에 도달하는지 확인합니다.** 관리되는 설정 파일은 배포되는 머신에만 적용됩니다(예: 장치 관리 시스템을 통해). 파일 위치는 [관리되는 설정](/ko/settings#settings-files)을 참조합니다.

144 184

145<h3 id="allowlist-ghes-marketplaces-in-managed-settings">185<h3 id="allowlist-ghes-marketplaces-in-managed-settings">

146 관리되는 설정에서 GHES 마켓플레이스 허용 목록186 관리되는 설정에서 GHES 마켓플레이스 허용 목록

159}199}

160```200```

161 201

162개발자를 위해 마켓플레이스를 미리 등록하여 수동 설정 없이 표시되도록 할 수도 있습니다. 이 예제는 내부 도구 마켓플레이스를 조직 전체에서 사용 가능하게 만듭니다:

~~163~~

164```json theme={null}

165{

166 "extraKnownMarketplaces": {

167 "internal-tools": {

168 "source": {

169 "source": "git",

170 "url": "git@github.example.com:platform/claude-plugins.git"

171 }

172 }

173 }

174}

175```

~~176~~

177전체 스키마는 [strictKnownMarketplaces](/ko/settings#strictknownmarketplaces) 및 [extraKnownMarketplaces](/ko/settings#extraknownmarketplaces) 설정 참조를 참조하십시오.202전체 스키마는 [strictKnownMarketplaces](/ko/settings#strictknownmarketplaces) 및 [extraKnownMarketplaces](/ko/settings#extraknownmarketplaces) 설정 참조를 참조하십시오.

178 203

179<h2 id="limitations">204<h2 id="limitations">

193 웹 세션이 저장소 복제에 실패함218 웹 세션이 저장소 복제에 실패함

194</h3>219</h3>

195 220

196`claude --remote`가 복제 오류로 실패하면 Owner가 GHES 인스턴스에 대한 설정을 완료했는지 확인하고 GitHub App이 작업 중인 저장소에 설치되어 있는지 확인합니다. 인스턴스를 연결한 Owner에게 Claude 설정에 등록된 호스트명이 git 원격의 호스트명과 일치하는지 확인하도록 요청합니다.221`claude --cloud`가 복제 오류로 실패하면 Owner가 GHES 인스턴스에 대한 설정을 완료했는지 확인하고 GitHub App이 작업 중인 저장소에 설치되어 있는지 확인합니다. 인스턴스를 연결한 Owner에게 Claude 설정에 등록된 호스트명이 git 원격의 호스트명과 일치하는지 확인하도록 요청합니다.

197 222

198<h3 id="marketplace-add-fails-with-a-policy-error">223<h3 id="marketplace-add-fails-with-a-policy-error">

199 마켓플레이스 추가가 정책 오류로 실패함224 마켓플레이스 추가가 정책 오류로 실패함

201 226

202GHES URL에 대해 `/plugin marketplace add`가 차단되면 조직이 마켓플레이스 소스를 제한했습니다. 관리자에게 [관리되는 설정](#allowlist-ghes-marketplaces-in-managed-settings)에서 GHES 호스트명에 대한 `hostPattern` 항목을 추가하도록 요청합니다.227GHES URL에 대해 `/plugin marketplace add`가 차단되면 조직이 마켓플레이스 소스를 제한했습니다. 관리자에게 [관리되는 설정](#allowlist-ghes-marketplaces-in-managed-settings)에서 GHES 호스트명에 대한 `hostPattern` 항목을 추가하도록 요청합니다.

203 228

229<h3 id="marketplace-add-on-claude-ai-fails-with-a-github-access-error">

230 claude.ai에서 마켓플레이스 추가가 GitHub 액세스 오류로 실패함

231</h3>

232

233사용자 설정에서 GHES 마켓플레이스를 추가하는 것이 "마켓플레이스를 추가할 수 없음"과 같은 일반적인 오류로 실패하면 먼저 GitHub Enterprise 연결을 확인합니다. 이는 조직의 GHES 인스턴스가 구성되어 있고 다른 사용자가 연결되어 있더라도 자신의 GitHub Enterprise 계정이 Claude에 연결되지 않았을 때 나타나는 현상입니다. 대화 상자는 GitHub Enterprise 연결 흐름을 가리키지 않으며, Browse 탭의 "GitHub에 연결" 옵션은 github.com에 로그인하므로 GHES 저장소에 대한 액세스 권한을 부여하지 않습니다.

234

235GitHub Enterprise 계정을 연결하려면: [claude.ai/code](https://claude.ai/code)의 저장소 선택기가 각 구성된 GHES 인스턴스에 대한 연결 옵션을 제공하며, Owner는 [Claude Code 관리자 설정](https://claude.ai/admin-settings/claude-code)의 GitHub Enterprise 섹션에서도 연결할 수 있습니다. 그런 다음 마켓플레이스를 다시 추가합니다. 또는 Owner에게 조직 플러그인 설정에서 마켓플레이스를 추가하도록 요청하면 사용자별 연결 요구 사항이 제거됩니다.

236

237다른 claude.ai 표면에서 GHES 마켓플레이스의 "저장소를 찾을 수 없습니다. 비공개인 경우 GitHub 액세스가 필요합니다" 오류는 일반적으로 동일한 누락된 연결을 나타냅니다. 위의 경로 중 하나를 통해 GitHub Enterprise 계정을 연결한 다음 다시 시도합니다.

238

204<h3 id="ghes-instance-not-reachable">239<h3 id="ghes-instance-not-reachable">

205 GHES 인스턴스에 도달할 수 없음240 GHES 인스턴스에 도달할 수 없음

206</h3>241</h3>

gitlab-ci-cd.md +30 −30

Details

24* **자동화된 구현**: 단일 명령 또는 언급으로 이슈를 작동하는 코드로 변환합니다24* **자동화된 구현**: 단일 명령 또는 언급으로 이슈를 작동하는 코드로 변환합니다

25* **프로젝트 인식**: Claude는 `CLAUDE.md` 지침과 기존 코드 패턴을 따릅니다25* **프로젝트 인식**: Claude는 `CLAUDE.md` 지침과 기존 코드 패턴을 따릅니다

26* **간단한 설정**: `.gitlab-ci.yml`에 하나의 작업과 마스킹된 CI/CD 변수를 추가합니다26* **간단한 설정**: `.gitlab-ci.yml`에 하나의 작업과 마스킹된 CI/CD 변수를 추가합니다

~~27* **엔터프라이즈 준비**: Claude API, Amazon Bedrock 또는 Google Vertex AI를 선택하여 데이터 거주지 및 조달 요구 사항을 충족합니다~~27* **엔터프라이즈 준비**: Claude API, Amazon Bedrock 또는 Google Cloud의 Agent Platform을 선택하여 데이터 거주지 및 조달 요구 사항을 충족합니다

28* **기본적으로 안전**: GitLab 러너에서 실행되며 브랜치 보호 및 승인이 적용됩니다28* **기본적으로 안전**: GitLab 러너에서 실행되며 브랜치 보호 및 승인이 적용됩니다

29 29

30<h2 id="how-it-works">30<h2 id="how-it-works">

382. **공급자 추상화**: 환경에 맞는 공급자를 사용합니다:382. **공급자 추상화**: 환경에 맞는 공급자를 사용합니다:

39 * Claude API (SaaS)39 * Claude API (SaaS)

40 * Amazon Bedrock (IAM 기반 액세스, 교차 지역 옵션)40 * Amazon Bedrock (IAM 기반 액세스, 교차 지역 옵션)

~~41 * Google Vertex AI (GCP 네이티브, Workload Identity Federation)~~41 * Google Cloud의 Agent Platform (GCP 네이티브, Workload Identity Federation)

42 42

433. **샌드박스 실행**: 각 상호 작용은 엄격한 네트워크 및 파일 시스템 규칙이 있는 컨테이너에서 실행됩니다. Claude Code는 쓰기를 제한하기 위해 작업 공간 범위 권한을 적용합니다. 모든 변경 사항은 MR을 통해 흐르므로 검토자가 diff를 보고 승인이 여전히 적용됩니다.433. **샌드박스 실행**: 각 상호 작용은 엄격한 네트워크 및 파일 시스템 규칙이 있는 컨테이너에서 실행됩니다. Claude Code는 쓰기를 제한하기 위해 작업 공간 범위 권한을 적용합니다. 모든 변경 사항은 MR을 통해 흐르므로 검토자가 diff를 보고 승인이 여전히 적용됩니다.

44 44

108작업과 `ANTHROPIC_API_KEY` 변수를 추가한 후 **CI/CD** → **파이프라인**에서 작업을 수동으로 실행하여 테스트하거나, MR에서 트리거하여 Claude가 브랜치에서 업데이트를 제안하고 필요한 경우 MR을 열도록 합니다.108작업과 `ANTHROPIC_API_KEY` 변수를 추가한 후 **CI/CD** → **파이프라인**에서 작업을 수동으로 실행하여 테스트하거나, MR에서 트리거하여 Claude가 브랜치에서 업데이트를 제안하고 필요한 경우 MR을 열도록 합니다.

109 109

110<Note>110<Note>

111 Claude API 대신 Amazon Bedrock 또는 Google Vertex AI에서 실행하려면 아래의 [Amazon Bedrock & Google Vertex AI 사용](#using-with-amazon-bedrock-%26-google-vertex-ai) 섹션을 참조하여 인증 및 환경 설정을 확인하세요.111 Claude API 대신 Amazon Bedrock 또는 Google Cloud의 Agent Platform에서 실행하려면 아래의 [Amazon Bedrock 및 Google Cloud 사용](#using-with-amazon-bedrock-and-google-cloud) 섹션을 참조하여 인증 및 환경 설정을 확인하세요.

112</Note>112</Note>

113 113

114<h3 id="manual-setup-recommended-for-production">114<h3 id="manual-setup-recommended-for-production">

119 119

1201. **공급자 액세스 구성**:1201. **공급자 액세스 구성**:

121 * **Claude API**: `ANTHROPIC_API_KEY`를 생성하고 마스킹된 CI/CD 변수로 저장합니다121 * **Claude API**: `ANTHROPIC_API_KEY`를 생성하고 마스킹된 CI/CD 변수로 저장합니다

122 * **Amazon Bedrock**: **GitLab 구성** → **AWS OIDC**를 구성하고 Bedrock용 IAM 역할을 생성합니다122 * **Amazon Bedrock**: **GitLab 구성** → **AWS OIDC**를 구성하고 Amazon Bedrock용 IAM 역할을 생성합니다

123 * **Google Vertex AI**: **GitLab용 Workload Identity Federation 구성** → **GCP**123 * **Google Cloud의 Agent Platform**: **GitLab용 Workload Identity Federation 구성** → **GCP**

124 124

1252. **GitLab API 작업을 위한 프로젝트 자격 증명 추가**:1252. **GitLab API 작업을 위한 프로젝트 자격 증명 추가**:

126 * 기본적으로 `CI_JOB_TOKEN`을 사용하거나 `api` 범위가 있는 프로젝트 액세스 토큰을 생성합니다126 * 기본적으로 `CI_JOB_TOKEN`을 사용하거나 `api` 범위가 있는 프로젝트 액세스 토큰을 생성합니다

172 172

173Claude는 버그를 찾고, 수정을 구현하고, 브랜치를 업데이트하거나 새 MR을 엽니다.173Claude는 버그를 찾고, 수정을 구현하고, 브랜치를 업데이트하거나 새 MR을 엽니다.

174 174

175<h2 id="using-with-amazon-bedrock--google-vertex-ai">175<h2 id="using-with-amazon-bedrock-and-google-cloud">

176 Amazon Bedrock & Google Vertex AI 사용176 Amazon Bedrock 및 Google Cloud 사용

177</h2>177</h2>

178 178

179엔터프라이즈 환경의 경우 동일한 개발자 경험으로 클라우드 인프라에서 완전히 Claude Code를 실행할 수 있습니다.179엔터프라이즈 환경의 경우 동일한 개발자 경험으로 클라우드 인프라에서 완전히 Claude Code를 실행할 수 있습니다.

186 186

187 1. 원하는 Claude 모델에 대한 Amazon Bedrock 액세스가 있는 AWS 계정187 1. 원하는 Claude 모델에 대한 Amazon Bedrock 액세스가 있는 AWS 계정

188 2. AWS IAM에서 OIDC 자격 증명 공급자로 구성된 GitLab188 2. AWS IAM에서 OIDC 자격 증명 공급자로 구성된 GitLab

189 3. Bedrock 권한이 있는 IAM 역할 및 GitLab 프로젝트/참조로 제한된 신뢰 정책189 3. Amazon Bedrock 권한이 있는 IAM 역할 및 GitLab 프로젝트/참조로 제한된 신뢰 정책

190 4. 역할 가정을 위한 GitLab CI/CD 변수:190 4. 역할 가정을 위한 GitLab CI/CD 변수:

191 * `AWS_ROLE_TO_ASSUME` (역할 ARN)191 * `AWS_ROLE_TO_ASSUME` (역할 ARN)

192 * `AWS_REGION` (Bedrock 지역)192 * `AWS_REGION` (Amazon Bedrock 지역)

193 193

194 ### 설정 지침194 ### 설정 지침

195 195

200 1. Amazon Bedrock을 활성화하고 대상 Claude 모델에 대한 액세스를 요청합니다200 1. Amazon Bedrock을 활성화하고 대상 Claude 모델에 대한 액세스를 요청합니다

201 2. 아직 없는 경우 GitLab용 IAM OIDC 공급자를 생성합니다201 2. 아직 없는 경우 GitLab용 IAM OIDC 공급자를 생성합니다

202 3. GitLab OIDC 공급자를 신뢰하고 프로젝트 및 보호된 참조로 제한된 IAM 역할을 생성합니다202 3. GitLab OIDC 공급자를 신뢰하고 프로젝트 및 보호된 참조로 제한된 IAM 역할을 생성합니다

203 4. Bedrock 호출 API에 대한 최소 권한 권한을 연결합니다203 4. Amazon Bedrock 호출 API에 대한 최소 권한 권한을 연결합니다

204 204

205 **CI/CD 변수에 저장할 필수 값:**205 **CI/CD 변수에 저장할 필수 값:**

206 206

218 위의 Amazon Bedrock 작업 예제를 사용하여 런타임에 GitLab 작업 토큰을 임시 AWS 자격 증명으로 교환합니다.218 위의 Amazon Bedrock 작업 예제를 사용하여 런타임에 GitLab 작업 토큰을 임시 AWS 자격 증명으로 교환합니다.

219 </Tab>219 </Tab>

220 220

221 <Tab title="Google Vertex AI">221 <Tab title="Google Cloud의 Agent Platform">

222 ### 필수 조건222 ### 필수 조건

223 223

224 Google Vertex AI로 Claude Code를 설정하기 전에 다음이 필요합니다:224 Google Cloud의 Agent Platform으로 Claude Code를 설정하기 전에 다음이 필요합니다:

225 225

226 1. 다음이 포함된 Google Cloud 프로젝트:226 1. 다음이 포함된 Google Cloud 프로젝트:

227 * Vertex AI API 활성화됨227 * Google Cloud의 Agent Platform API 활성화됨

228 * GitLab OIDC를 신뢰하도록 구성된 Workload Identity Federation228 * GitLab OIDC를 신뢰하도록 구성된 Workload Identity Federation

229 2. 필요한 Vertex AI 역할만 있는 전용 서비스 계정229 2. 필요한 Google Cloud의 Agent Platform 역할만 있는 전용 서비스 계정

230 3. WIF용 GitLab CI/CD 변수:230 3. WIF용 GitLab CI/CD 변수:

231 * `GCP_WORKLOAD_IDENTITY_PROVIDER` (전체 리소스 이름)231 * `GCP_WORKLOAD_IDENTITY_PROVIDER` (전체 리소스 이름)

232 * `GCP_SERVICE_ACCOUNT` (서비스 계정 이메일)232 * `GCP_SERVICE_ACCOUNT` (서비스 계정 이메일)

237 237

238 **필수 설정:**238 **필수 설정:**

239 239

240 1. IAM Credentials API, STS API 및 Vertex AI API 활성화240 1. IAM Credentials API, STS API 및 Google Cloud의 Agent Platform API 활성화

241 2. GitLab OIDC용 Workload Identity Pool 및 공급자 생성241 2. GitLab OIDC용 Workload Identity Pool 및 공급자 생성

242 3. Vertex AI 역할이 있는 전용 서비스 계정 생성242 3. Google Cloud의 Agent Platform 역할이 있는 전용 서비스 계정 생성

243 4. WIF 주체에 서비스 계정을 가장할 수 있는 권한 부여243 4. WIF 주체에 서비스 계정을 가장할 수 있는 권한 부여

244 244

245 **CI/CD 변수에 저장할 필수 값:**245 **CI/CD 변수에 저장할 필수 값:**

250 설정 → CI/CD → 변수에서 변수를 추가합니다:250 설정 → CI/CD → 변수에서 변수를 추가합니다:

251 251

252 ```yaml theme={null}252 ```yaml theme={null}

253 # Google Vertex AI의 경우:253 # Google Cloud의 Agent Platform의 경우:

254 - GCP_WORKLOAD_IDENTITY_PROVIDER254 - GCP_WORKLOAD_IDENTITY_PROVIDER

255 - GCP_SERVICE_ACCOUNT255 - GCP_SERVICE_ACCOUNT

256 - CLOUD_ML_REGION (예: us-east5)256 - CLOUD_ML_REGION (예: us-east5)

257 ```257 ```

258 258

259 위의 Google Vertex AI 작업 예제를 사용하여 키를 저장하지 않고 인증합니다.259 위의 Google Cloud의 Agent Platform 작업 예제를 사용하여 키를 저장하지 않고 인증합니다.

260 </Tab>260 </Tab>

261</Tabs>261</Tabs>

262 262

305 305

306* Amazon Bedrock이 활성화되고 선택한 Claude 모델에 액세스 가능306* Amazon Bedrock이 활성화되고 선택한 Claude 모델에 액세스 가능

307* GitLab OIDC가 AWS에 구성되고 GitLab 프로젝트 및 참조를 신뢰하는 역할307* GitLab OIDC가 AWS에 구성되고 GitLab 프로젝트 및 참조를 신뢰하는 역할

308* Bedrock 권한이 있는 IAM 역할 (최소 권한 권장)308* Amazon Bedrock 권한이 있는 IAM 역할 (최소 권한 권장)

309 309

310**필수 CI/CD 변수:**310**필수 CI/CD 변수:**

311 311

312* `AWS_ROLE_TO_ASSUME`: Bedrock 액세스용 IAM 역할의 ARN312* `AWS_ROLE_TO_ASSUME`: Amazon Bedrock 액세스용 IAM 역할의 ARN

313* `AWS_REGION`: Bedrock 지역 (예: `us-west-2`)313* `AWS_REGION`: Amazon Bedrock 지역 (예: `us-west-2`)

314 314

315```yaml theme={null}315```yaml theme={null}

316claude-bedrock:316claude-bedrock:

347```347```

348 348

349<Note>349<Note>

350 Bedrock의 모델 ID에는 지역별 접두사가 포함됩니다 (예: `us.anthropic.claude-sonnet-4-6`). 워크플로우에서 지원하는 경우 작업 구성 또는 프롬프트를 통해 원하는 모델을 전달합니다.350 Amazon Bedrock의 모델 ID에는 지역별 접두사가 포함됩니다 (예: `us.anthropic.claude-sonnet-4-6`). 워크플로우에서 지원하는 경우 작업 구성 또는 프롬프트를 통해 원하는 모델을 전달합니다.

351</Note>351</Note>

352 352

353<h3 id="google-vertex-ai-job-example-workload-identity-federation">353<h3 id="agent-platform-job-example-workload-identity-federation">

354 Google Vertex AI 작업 예제 (Workload Identity Federation)354 Agent Platform 작업 예제 (Workload Identity Federation)

355</h3>355</h3>

356 356

357**필수 조건:**357**필수 조건:**

358 358

359* GCP 프로젝트에서 Vertex AI API 활성화됨359* GCP 프로젝트에서 Google Cloud의 Agent Platform API 활성화됨

360* GitLab OIDC를 신뢰하도록 구성된 Workload Identity Federation360* GitLab OIDC를 신뢰하도록 구성된 Workload Identity Federation

361* Vertex AI 권한이 있는 서비스 계정361* Google Cloud의 Agent Platform 권한이 있는 서비스 계정

362 362

363**필수 CI/CD 변수:**363**필수 CI/CD 변수:**

364 364

365* `GCP_WORKLOAD_IDENTITY_PROVIDER`: 전체 공급자 리소스 이름365* `GCP_WORKLOAD_IDENTITY_PROVIDER`: 전체 공급자 리소스 이름

366* `GCP_SERVICE_ACCOUNT`: 서비스 계정 이메일366* `GCP_SERVICE_ACCOUNT`: 서비스 계정 이메일

367* `CLOUD_ML_REGION`: Vertex 지역 (예: `us-east5`)367* `CLOUD_ML_REGION`: Google Cloud의 Agent Platform 지역 (예: `us-east5`)

368 368

369```yaml theme={null}369```yaml theme={null}

370claude-vertex:370claude-vertex:

490</h3>490</h3>

491 491

492* **Claude API의 경우**: `ANTHROPIC_API_KEY`가 유효하고 만료되지 않았는지 확인합니다492* **Claude API의 경우**: `ANTHROPIC_API_KEY`가 유효하고 만료되지 않았는지 확인합니다

493* **Bedrock/Vertex의 경우**: OIDC/WIF 구성, 역할 가장 및 비밀 이름을 확인합니다. 지역 및 모델 가용성을 확인합니다493* **Amazon Bedrock 또는 Google Cloud의 Agent Platform의 경우**: OIDC/WIF 구성, 역할 가장 및 비밀 이름을 확인합니다. 지역 및 모델 가용성을 확인합니다

494 494

495<h2 id="advanced-configuration">495<h2 id="advanced-configuration">

496 고급 구성496 고급 구성

505* `prompt` / `prompt_file`: 인라인 (`-p`) 또는 파일을 통해 지침을 제공합니다505* `prompt` / `prompt_file`: 인라인 (`-p`) 또는 파일을 통해 지침을 제공합니다

506* `max_turns`: 왕복 반복 횟수를 제한합니다506* `max_turns`: 왕복 반복 횟수를 제한합니다

507* `timeout_minutes`: 총 실행 시간을 제한합니다507* `timeout_minutes`: 총 실행 시간을 제한합니다

508* `ANTHROPIC_API_KEY`: Claude API에 필요합니다 (Bedrock/Vertex에는 사용되지 않음)508* `ANTHROPIC_API_KEY`: Claude API에 필요합니다 (Amazon Bedrock 또는 Google Cloud의 Agent Platform에는 사용되지 않음)

509* 공급자별 환경: `AWS_REGION`, Vertex용 프로젝트/지역 변수509* 공급자별 환경: `AWS_REGION`, Google Cloud의 Agent Platform용 프로젝트/지역 변수

510 510

511<Note>511<Note>

512 정확한 플래그 및 매개변수는 `@anthropic-ai/claude-code` 버전에 따라 다를 수 있습니다. 작업에서 `claude --help`를 실행하여 지원되는 옵션을 확인합니다.512 정확한 플래그 및 매개변수는 `@anthropic-ai/claude-code` 버전에 따라 다를 수 있습니다. 작업에서 `claude --help`를 실행하여 지원되는 옵션을 확인합니다.

glossary.md +3 −1

Details

262 262

263세션의 기본 승인 동작입니다. CLI에서 `Shift+Tab`으로 순환하거나 VS Code, Desktop 및 claude.ai의 모드 선택기를 사용합니다. 사용 가능한 모드는 `default`, `acceptEdits`, `plan`, `auto`, `dontAsk` 및 `bypassPermissions`입니다.263세션의 기본 승인 동작입니다. CLI에서 `Shift+Tab`으로 순환하거나 VS Code, Desktop 및 claude.ai의 모드 선택기를 사용합니다. 사용 가능한 모드는 `default`, `acceptEdits`, `plan`, `auto`, `dontAsk` 및 `bypassPermissions`입니다.

264 264

265`default` 모드는 CLI 및 VS Code와 JetBrains 확장에서 Manual로 표시되며, Claude Code는 값에 대한 `manual`의 별칭을 허용합니다.

266

265자세히 알아보기: [권한 모드 선택](/ko/permission-modes)267자세히 알아보기: [권한 모드 선택](/ko/permission-modes)

266 268

267<h3 id="permission-rule">269<h3 id="permission-rule">

388 Teleport390 Teleport

389</h3>391</h3>

390 392

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

392 394

393자세히 알아보기: [웹에서 터미널로](/ko/claude-code-on-the-web#from-web-to-terminal)395자세히 알아보기: [웹에서 터미널로](/ko/claude-code-on-the-web#from-web-to-terminal)

394 396

google-vertex-ai.md +38 −38

Details

2> Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt2> Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt

3> Use this file to discover all available pages before exploring further.3> Use this file to discover all available pages before exploring further.

4 4

~~5# Google Vertex AI에서 Claude Code 사용하기~~5# Google Cloud의 Agent Platform에서 Claude Code 사용하기

6 6

~~7> Google Vertex AI를 통해 Claude Code를 구성하는 방법을 알아봅니다. 설정, IAM 구성 및 문제 해결을 포함합니다.~~7> Google Cloud의 Agent Platform(이전 Vertex AI)을 통해 Claude Code를 구성하는 방법을 알아봅니다. 설정, IAM 구성 및 문제 해결을 포함합니다.

8 8

9export const ContactSalesCard = ({surface}) => {9export const ContactSalesCard = ({surface}) => {

10 const utm = content => `utm_source=claude_code&utm_medium=docs&utm_content=${surface}_${content}`;10 const utm = content => `utm_source=claude_code&utm_medium=docs&utm_content=${surface}_${content}`;

82 필수 요구사항82 필수 요구사항

83</h2>83</h2>

84 84

~~85Vertex AI를 사용하여 Claude Code를 구성하기 전에 다음을 확인하십시오:~~85Google Cloud의 Agent Platform(이전의 Vertex AI)을 사용하여 Claude Code를 구성하기 전에 다음을 확인하십시오:

86 86

87* 청구가 활성화된 Google Cloud Platform(GCP) 계정87* 청구가 활성화된 Google Cloud Platform(GCP) 계정

~~88* Vertex AI API가 활성화된 GCP 프로젝트~~88* Google Cloud의 Agent Platform API가 활성화된 GCP 프로젝트

89* 원하는 Claude 모델에 대한 액세스(예: Claude Sonnet 4.6)89* 원하는 Claude 모델에 대한 액세스(예: Claude Sonnet 4.6)

90* Google Cloud SDK(`gcloud`) 설치 및 구성90* Google Cloud SDK(`gcloud`) 설치 및 구성

91* 원하는 GCP 지역에 할당된 할당량91* 원하는 GCP 지역에 할당된 할당량

92 92

93자신의 Vertex AI 자격증명으로 로그인하려면 아래의 [Vertex AI로 로그인](#sign-in-with-vertex-ai)을 따르십시오. 팀 전체에 Claude Code를 배포하려면 [수동 설정](#set-up-manually) 단계를 사용하고 롤아웃 전에 [모델 버전을 고정](#5-pin-model-versions)하십시오.93자신의 Google Cloud의 Agent Platform 자격증명으로 로그인하려면 아래의 [Google Cloud의 Agent Platform으로 로그인](#sign-in-with-agent-platform)을 따르십시오. 팀 전체에 Claude Code를 배포하려면 [수동 설정](#set-up-manually) 단계를 사용하고 롤아웃 전에 [모델 버전을 고정](#5-pin-model-versions)하십시오.

94 94

~~95<h2 id="sign-in-with-vertex-ai">~~95<h2 id="sign-in-with-agent-platform">

~~96 Vertex AI로 로그인~~96 Agent Platform으로 로그인

97</h2>97</h2>

98 98

99Google Cloud 자격증명이 있고 Vertex AI를 통해 Claude Code 사용을 시작하려면 로그인 마법사가 이를 안내합니다. GCP 측 필수 요구사항을 프로젝트당 한 번 완료하면 마법사가 Claude Code 측을 처리합니다.99Google Cloud 자격증명이 있고 Google Cloud의 Agent Platform을 통해 Claude Code 사용을 시작하려면 로그인 마법사가 이를 안내합니다. GCP 측 필수 요구사항을 프로젝트당 한 번 완료하면 마법사가 Claude Code 측을 처리합니다.

100 100

101<Note>101<Note>

102 Vertex AI 설정 마법사는 Claude Code v2.1.98 이상이 필요합니다. `claude --version`을 실행하여 확인하십시오.102 Google Cloud의 Agent Platform 설정 마법사는 Claude Code v2.1.98 이상이 필요합니다. `claude --version`을 실행하여 확인하십시오.

103</Note>103</Note>

104 104

105<Steps>105<Steps>

106 <Step title="GCP 프로젝트에서 Claude 모델 활성화">106 <Step title="GCP 프로젝트에서 Claude 모델 활성화">

107 프로젝트에 대해 [Vertex AI API를 활성화](#1-enable-vertex-ai-api)한 다음 [Vertex AI Model Garden](https://console.cloud.google.com/vertex-ai/model-garden)에서 원하는 Claude 모델에 대한 액세스를 요청합니다. 계정에 필요한 권한은 [IAM 구성](#iam-configuration)을 참조하십시오.107 프로젝트에 대해 [Google Cloud의 Agent Platform API 활성화](#1-enable-agent-platform-api)한 다음 [Google Cloud의 Agent Platform Model Garden](https://console.cloud.google.com/vertex-ai/model-garden)에서 원하는 Claude 모델에 대한 액세스를 요청합니다. 계정에 필요한 권한은 [IAM 구성](#iam-configuration)을 참조하십시오.

108 </Step>108 </Step>

109 109

110 <Step title="Claude Code를 시작하고 Vertex AI 선택">110 <Step title="Claude Code를 시작하고 Google Cloud의 Agent Platform 선택">

111 `claude`를 실행합니다. 로그인 프롬프트에서 **3rd-party platform**을 선택한 다음 **Google Vertex AI**를 선택합니다.111 `claude`를 실행합니다. 로그인 프롬프트에서 **3rd-party platform**을 선택한 다음 **Google Vertex AI**를 선택합니다. 이는 로그인 프롬프트가 Google Cloud의 Agent Platform에 대해 여전히 사용하는 레이블입니다.

112 </Step>112 </Step>

113 113

114 <Step title="마법사 프롬프트 따르기">114 <Step title="마법사 프롬프트 따르기">

122 지역 구성122 지역 구성

123</h2>123</h2>

124 124

125Claude Code는 Vertex AI [전역](https://cloud.google.com/blog/products/ai-machine-learning/global-endpoint-for-claude-models-generally-available-on-vertex-ai), 다중 지역 및 지역 엔드포인트를 지원합니다. `CLOUD_ML_REGION`을 `global`, `eu` 또는 `us`와 같은 다중 지역 위치 또는 `us-east5`와 같은 특정 지역으로 설정합니다. Claude Code는 `aiplatform.eu.rep.googleapis.com` 및 `aiplatform.us.rep.googleapis.com` 호스트를 포함한 다중 지역 위치에 대해 각 형식에 맞는 올바른 Vertex AI 호스트명을 선택합니다.125Claude Code는 Google Cloud의 Agent Platform [전역](https://cloud.google.com/blog/products/ai-machine-learning/global-endpoint-for-claude-models-generally-available-on-vertex-ai), 다중 지역 및 지역 엔드포인트를 지원합니다. `CLOUD_ML_REGION`을 `global`, `eu` 또는 `us`와 같은 다중 지역 위치 또는 `us-east5`와 같은 특정 지역으로 설정합니다. Claude Code는 `aiplatform.eu.rep.googleapis.com` 및 `aiplatform.us.rep.googleapis.com` 호스트를 포함한 다중 지역 위치에 대해 각 형식에 맞는 올바른 Google Cloud의 Agent Platform 호스트명을 선택합니다.

126 126

127<Note>127<Note>

128 Vertex AI는 모든 엔드포인트 유형에서 Claude Code 기본 모델을 지원하지 않을 수 있습니다. 모델 가용성은 [특정 지역](https://cloud.google.com/vertex-ai/generative-ai/docs/learn/locations#genai-partner-models), 다중 지역 위치 및 [전역 엔드포인트](https://cloud.google.com/vertex-ai/generative-ai/docs/partner-models/use-partner-models#supported_models)에 따라 다릅니다. 지원되는 위치로 전환하거나 지원되는 모델을 지정해야 할 수 있습니다.128 Google Cloud의 Agent Platform은 모든 엔드포인트 유형에서 Claude Code 기본 모델을 지원하지 않을 수 있습니다. 모델 가용성은 [특정 지역](https://cloud.google.com/vertex-ai/generative-ai/docs/learn/locations#genai-partner-models), 다중 지역 위치 및 [전역 엔드포인트](https://cloud.google.com/vertex-ai/generative-ai/docs/partner-models/use-partner-models#supported_models)에 따라 다릅니다. 지원되는 위치로 전환하거나 지원되는 모델을 지정해야 할 수 있습니다.

129</Note>129</Note>

130 130

131<h2 id="set-up-manually">131<h2 id="set-up-manually">

132 수동 설정132 수동 설정

133</h2>133</h2>

134 134

135마법사 대신 환경 변수를 통해 Vertex AI를 구성하려면(예: CI 또는 스크립트된 엔터프라이즈 롤아웃의 경우) 아래 단계를 따르십시오.135Google Cloud의 Agent Platform을 마법사 대신 환경 변수를 통해 구성하려면(예: CI 또는 스크립트된 엔터프라이즈 롤아웃의 경우) 아래 단계를 따르십시오.

136 136

137<h3 id="1-enable-vertex-ai-api">137<h3 id="1-enable-agent-platform-api">

138 1. Vertex AI API 활성화138 1. Agent Platform API 활성화

139</h3>139</h3>

140 140

141GCP 프로젝트에서 Vertex AI API를 활성화합니다:141GCP 프로젝트에서 Google Cloud의 Agent Platform API를 활성화합니다:

142 142

143```bash theme={null}143```bash theme={null}

144# 프로젝트 ID 설정144# 프로젝트 ID 설정

145gcloud config set project YOUR-PROJECT-ID145gcloud config set project YOUR-PROJECT-ID

146 146

147# Vertex AI API 활성화147# Agent Platform API 활성화

148gcloud services enable aiplatform.googleapis.com148gcloud services enable aiplatform.googleapis.com

149```149```

150 150

152 2. 모델 액세스 요청152 2. 모델 액세스 요청

153</h3>153</h3>

154 154

155Vertex AI에서 Claude 모델에 대한 액세스를 요청합니다:155Google Cloud의 Agent Platform에서 Claude 모델에 대한 액세스를 요청합니다:

156 156

1571. [Vertex AI Model Garden](https://console.cloud.google.com/vertex-ai/model-garden)으로 이동합니다1571. [Google Cloud의 Agent Platform Model Garden](https://console.cloud.google.com/vertex-ai/model-garden)으로 이동합니다

1582. "Claude" 모델을 검색합니다1582. "Claude" 모델을 검색합니다

1593. 원하는 Claude 모델에 대한 액세스를 요청합니다(예: Claude Sonnet 4.6)1593. 원하는 Claude 모델에 대한 액세스를 요청합니다(예: Claude Sonnet 4.6)

1604. 승인을 기다립니다(24-48시간이 소요될 수 있습니다)1604. 승인을 기다립니다(24-48시간이 소요될 수 있습니다)

170Claude Code v2.1.121 이상은 동일한 Application Default Credentials 체인을 통해 [X.509 인증서 기반 Workload Identity Federation](https://cloud.google.com/iam/docs/workload-identity-federation-with-x509-certificates)을 지원합니다. `GOOGLE_APPLICATION_CREDENTIALS`를 자격증명 구성 파일의 경로로 설정합니다.170Claude Code v2.1.121 이상은 동일한 Application Default Credentials 체인을 통해 [X.509 인증서 기반 Workload Identity Federation](https://cloud.google.com/iam/docs/workload-identity-federation-with-x509-certificates)을 지원합니다. `GOOGLE_APPLICATION_CREDENTIALS`를 자격증명 구성 파일의 경로로 설정합니다.

171 171

172<Note>172<Note>

173 Claude Code는 Vertex AI 요청에 대해 `ANTHROPIC_VERTEX_PROJECT_ID`를 프로젝트 ID로 사용합니다. `GCLOUD_PROJECT` 및 `GOOGLE_CLOUD_PROJECT` 환경 변수와 `GOOGLE_APPLICATION_CREDENTIALS`에서 참조하는 자격증명 파일이 이를 우선합니다. 이 중 어느 것도 설정되지 않으면 프로젝트 ID는 `gcloud` 구성 또는 연결된 서비스 계정에서 확인됩니다.173 Claude Code는 Google Cloud의 Agent Platform 요청에 대해 `ANTHROPIC_VERTEX_PROJECT_ID`를 프로젝트 ID로 사용합니다. `GCLOUD_PROJECT` 및 `GOOGLE_CLOUD_PROJECT` 환경 변수와 `GOOGLE_APPLICATION_CREDENTIALS`에서 참조하는 자격증명 파일이 이를 우선합니다. 이 중 어느 것도 설정되지 않으면 프로젝트 ID는 `gcloud` 구성 또는 연결된 서비스 계정에서 확인됩니다.

174</Note>174</Note>

175 175

176<h4 id="advanced-credential-configuration">176<h4 id="advanced-credential-configuration">

197다음 환경 변수를 설정합니다:197다음 환경 변수를 설정합니다:

198 198

199```bash theme={null}199```bash theme={null}

200# Vertex AI 통합 활성화200# Agent Platform 통합 활성화

201export CLAUDE_CODE_USE_VERTEX=1201export CLAUDE_CODE_USE_VERTEX=1

202export CLOUD_ML_REGION=global202export CLOUD_ML_REGION=global

203export ANTHROPIC_VERTEX_PROJECT_ID=YOUR-PROJECT-ID203export ANTHROPIC_VERTEX_PROJECT_ID=YOUR-PROJECT-ID

204 204

205# 선택사항: 사용자 정의 엔드포인트 또는 게이트웨이를 위해 Vertex 엔드포인트 URL 재정의205# 선택사항: 사용자 정의 엔드포인트 또는 게이트웨이를 위해 Agent Platform 엔드포인트 URL 재정의

206# export ANTHROPIC_VERTEX_BASE_URL=https://aiplatform.googleapis.com206# export ANTHROPIC_VERTEX_BASE_URL=https://aiplatform.googleapis.com

207 207

208# 선택사항: 필요한 경우 prompt caching 비활성화208# 선택사항: 필요한 경우 prompt caching 비활성화

216export VERTEX_REGION_CLAUDE_4_6_SONNET=europe-west1216export VERTEX_REGION_CLAUDE_4_6_SONNET=europe-west1

217```217```

218 218

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

220 220

221[Prompt caching](/ko/prompt-caching)은 자동으로 활성화됩니다. 이를 비활성화하려면 `DISABLE_PROMPT_CACHING=1`을 설정하십시오. 기본 5분 대신 1시간 캐시 TTL을 요청하려면 `ENABLE_PROMPT_CACHING_1H=1`을 설정하십시오. 1시간 TTL을 사용한 캐시 쓰기는 더 높은 요금으로 청구됩니다. 높은 속도 제한을 위해 Google Cloud 지원팀에 문의하십시오. Vertex AI를 사용할 때 `/logout` 명령은 Google Cloud 자격증명을 통해 인증이 처리되므로 사용할 수 없습니다.221[Prompt caching](/ko/prompt-caching)은 자동으로 활성화됩니다. 이를 비활성화하려면 `DISABLE_PROMPT_CACHING=1`을 설정하십시오. 기본 5분 대신 1시간 캐시 TTL을 요청하려면 `ENABLE_PROMPT_CACHING_1H=1`을 설정하십시오. 1시간 TTL을 사용한 캐시 쓰기는 더 높은 요금으로 청구됩니다. 높은 속도 제한을 위해 Google Cloud 지원팀에 문의하십시오. Google Cloud의 Agent Platform을 사용할 때 `/logout` 명령은 Google Cloud 자격증명을 통해 인증이 처리되므로 사용할 수 없습니다.

222 222

223Claude Code는 [MCP tool search](/ko/mcp#scale-with-mcp-tool-search)를 Vertex AI에서 기본적으로 비활성화합니다. 따라서 모든 MCP 도구 정의는 미리 로드됩니다. Vertex AI는 Claude Sonnet 4.5 이상 및 Claude Opus 4.5 이상에 대해 도구 검색을 지원합니다. 이러한 모델에서 도구 검색을 활성화하려면 `ENABLE_TOOL_SEARCH=true`를 설정하십시오. Vertex AI의 이전 모델은 필요한 베타 헤더를 허용하지 않으며, 이러한 모델에서 도구 검색을 활성화하면 요청이 실패합니다.223Claude Code는 [MCP tool search](/ko/mcp#scale-with-mcp-tool-search)를 Google Cloud의 Agent Platform에서 기본적으로 비활성화합니다. 따라서 모든 MCP 도구 정의는 미리 로드됩니다. Google Cloud의 Agent Platform은 Claude Sonnet 4.5 이상 및 Claude Opus 4.5 이상에 대해 도구 검색을 지원합니다. 이러한 모델에서 도구 검색을 활성화하려면 `ENABLE_TOOL_SEARCH=true`를 설정하십시오. Google Cloud의 Agent Platform의 이전 모델은 필요한 베타 헤더를 허용하지 않으며, 이러한 모델에서 도구 검색을 활성화하면 요청이 실패합니다.

224 224

225<h3 id="5-pin-model-versions">225<h3 id="5-pin-model-versions">

226 5. 모델 버전 고정226 5. 모델 버전 고정

227</h3>227</h3>

228 228

229<Warning>229<Warning>

230 여러 사용자에게 배포할 때 특정 모델 버전을 고정합니다. 고정하지 않으면 `sonnet` 및 `opus`와 같은 모델 별칭이 Claude Code의 Vertex AI용 기본 제공 기본값으로 확인되며, 이는 최신 릴리스보다 뒤떨어질 수 있고 프로젝트에서 아직 활성화되지 않았을 수 있습니다. Claude Code는 기본값을 사용할 수 없을 때 시작 시 [이전 버전으로 폴백](#startup-model-checks)하지만, 고정하면 사용자가 새 모델로 이동하는 시기를 제어할 수 있습니다.230 여러 사용자에게 배포할 때 특정 모델 버전을 고정합니다. 고정하지 않으면 `sonnet` 및 `opus`와 같은 모델 별칭이 Claude Code의 Google Cloud의 Agent Platform용 기본 제공 기본값으로 확인되며, 이는 최신 릴리스보다 뒤떨어질 수 있고 프로젝트에서 아직 활성화되지 않았을 수 있습니다. Claude Code는 기본값을 사용할 수 없을 때 시작 시 [이전 버전으로 폴백](#startup-model-checks)하지만, 고정하면 사용자가 새 모델로 이동하는 시기를 제어할 수 있습니다.

231</Warning>231</Warning>

232 232

233이러한 환경 변수를 특정 Vertex AI 모델 ID로 설정합니다.233이러한 환경 변수를 특정 Google Cloud의 Agent Platform 모델 ID로 설정합니다.

234 234

235`ANTHROPIC_DEFAULT_OPUS_MODEL`이 없으면 Vertex의 `opus` 별칭이 Opus 4.6으로 확인됩니다. 최신 모델을 사용하려면 Opus 4.8 ID로 설정합니다:235`ANTHROPIC_DEFAULT_OPUS_MODEL`이 없으면 Google Cloud의 Agent Platform의 `opus` 별칭이 Opus 4.6으로 확인됩니다. 최신 모델을 사용하려면 Opus 4.8 ID로 설정합니다:

236 236

237```bash theme={null}237```bash theme={null}

238export ANTHROPIC_DEFAULT_OPUS_MODEL='claude-opus-4-8'238export ANTHROPIC_DEFAULT_OPUS_MODEL='claude-opus-4-8'

249| 주 모델 | `claude-sonnet-4-5@20250929` |249| 주 모델 | `claude-sonnet-4-5@20250929` |

250| 소형/빠른 모델 | 주 모델과 동일 |250| 소형/빠른 모델 | 주 모델과 동일 |

251 251

252백그라운드 작업(예: 세션 제목 생성)은 소형/빠른 모델(일반적으로 Haiku 클래스 모델)을 사용합니다. Vertex AI에서 Claude Code는 모든 프로젝트 또는 지역에서 Haiku가 활성화되지 않을 수 있으므로 이를 주 모델로 기본 설정합니다. 백그라운드 작업에 Haiku를 사용하려면 `ANTHROPIC_DEFAULT_HAIKU_MODEL`을 프로젝트에서 사용 가능한 모델 ID로 설정합니다.252백그라운드 작업(예: 세션 제목 생성)은 소형/빠른 모델(일반적으로 Haiku 클래스 모델)을 사용합니다. Google Cloud의 Agent Platform에서 Claude Code는 모든 프로젝트 또는 지역에서 Haiku가 활성화되지 않을 수 있으므로 이를 주 모델로 기본 설정합니다. 백그라운드 작업에 Haiku를 사용하려면 `ANTHROPIC_DEFAULT_HAIKU_MODEL`을 프로젝트에서 사용 가능한 모델 ID로 설정합니다.

253 253

254모델을 추가로 사용자 정의하려면:254모델을 추가로 사용자 정의하려면:

255 255

262 시작 모델 확인262 시작 모델 확인

263</h2>263</h2>

264 264

265Claude Code가 Vertex AI로 구성되어 시작할 때 사용하려는 모델이 프로젝트에서 액세스 가능한지 확인합니다. 이 확인에는 Claude Code v2.1.98 이상이 필요합니다.265Claude Code가 Google Cloud의 Agent Platform으로 구성되어 시작할 때 사용하려는 모델이 프로젝트에서 액세스 가능한지 확인합니다. 이 확인에는 Claude Code v2.1.98 이상이 필요합니다.

266 266

267현재 Claude Code 기본값보다 오래된 모델 버전을 고정했고 프로젝트가 최신 버전을 호출할 수 있으면 Claude Code는 고정을 업데이트하라는 메시지를 표시합니다. 수락하면 새 모델 ID를 [사용자 설정 파일](/ko/settings)에 쓰고 Claude Code를 다시 시작합니다. 거절하면 다음 기본 버전 변경까지 기억됩니다.267현재 Claude Code 기본값보다 오래된 모델 버전을 고정했고 프로젝트가 최신 버전을 호출할 수 있으면 Claude Code는 고정을 업데이트하라는 메시지를 표시합니다. 수락하면 새 모델 ID를 [사용자 설정 파일](/ko/settings)에 쓰고 Claude Code를 다시 시작합니다. 거절하면 다음 기본 버전 변경까지 기억됩니다.

268 268

280 280

281더 제한적인 권한의 경우 위의 권한만 포함하는 사용자 정의 역할을 만듭니다.281더 제한적인 권한의 경우 위의 권한만 포함하는 사용자 정의 역할을 만듭니다.

282 282

283자세한 내용은 [Vertex IAM 설명서](https://cloud.google.com/vertex-ai/docs/general/access-control)를 참조하십시오.283자세한 내용은 [Google Cloud의 Agent Platform IAM 설명서](https://cloud.google.com/vertex-ai/docs/general/access-control)를 참조하십시오.

284 284

285<Note>285<Note>

286 비용 추적 및 액세스 제어를 단순화하기 위해 Claude Code용 전용 GCP 프로젝트를 만듭니다.286 비용 추적 및 액세스 제어를 단순화하기 위해 Claude Code용 전용 GCP 프로젝트를 만듭니다.

290 1M 토큰 context window290 1M 토큰 context window

291</h2>291</h2>

292 292

293Claude Sonnet 5, Opus 4.6 이상 및 Sonnet 4.6은 Vertex AI에서 [1M 토큰 context window](https://platform.claude.com/docs/ko/build-with-claude/context-windows#1m-token-context-window)를 지원합니다. Sonnet 5는 항상 1M 윈도우로 실행되며, 선택할 `[1m]` 변형이 없습니다. 다른 모델의 경우, Claude Code는 1M 모델 변형을 선택할 때 확장된 context window를 자동으로 활성화합니다.293Claude Sonnet 5, Opus 4.6 이상 및 Sonnet 4.6은 Google Cloud의 Agent Platform에서 [1M 토큰 context window](https://platform.claude.com/docs/ko/build-with-claude/context-windows#1m-token-context-window)를 지원합니다. Sonnet 5는 항상 1M 윈도우로 실행되며, 선택할 `[1m]` 변형이 없습니다. 다른 모델의 경우, Claude Code는 1M 모델 변형을 선택할 때 확장된 context window를 자동으로 활성화합니다.

294 294

295[설정 마법사](#sign-in-with-vertex-ai)는 모델을 고정할 때 1M context 옵션을 제공합니다. 수동으로 고정된 모델에 대해 대신 활성화하려면 모델 ID에 `[1m]`을 추가합니다. 자세한 내용은 [타사 배포를 위한 모델 고정](/ko/model-config#pin-models-for-third-party-deployments)을 참조하십시오.295[설정 마법사](#sign-in-with-agent-platform)는 모델을 고정할 때 1M context 옵션을 제공합니다. 수동으로 고정된 모델에 대해 대신 활성화하려면 모델 ID에 `[1m]`을 추가합니다. 자세한 내용은 [타사 배포를 위한 모델 고정](/ko/model-config#pin-models-for-third-party-deployments)을 참조하십시오.

296 296

297<h2 id="troubleshooting">297<h2 id="troubleshooting">

298 문제 해결298 문제 해결

325 추가 리소스325 추가 리소스

326</h2>326</h2>

327 327

328* [Vertex AI 설명서](https://cloud.google.com/vertex-ai/docs)328* [Google Cloud의 Agent Platform 설명서](https://cloud.google.com/vertex-ai/docs)

329* [Vertex AI 가격](https://cloud.google.com/vertex-ai/pricing)329* [Google Cloud의 Agent Platform 가격](https://cloud.google.com/vertex-ai/pricing)

330* [Vertex AI 할당량 및 제한](https://cloud.google.com/vertex-ai/docs/quotas)330* [Google Cloud의 Agent Platform 할당량 및 제한](https://cloud.google.com/vertex-ai/docs/quotas)

headless.md +11 −5

Details

56| 사용자 정의 에이전트 | `--agents <json>` |56| 사용자 정의 에이전트 | `--agents <json>` |

57| 플러그인 | `--plugin-dir <path>`, `--plugin-url <url>` |57| 플러그인 | `--plugin-dir <path>`, `--plugin-url <url>` |

58 58

59베어 모드는 OAuth 및 키체인 읽기를 건너뜁니다. Anthropic 인증은 `ANTHROPIC_API_KEY` 또는 `--settings`에 전달된 JSON의 `apiKeyHelper`에서 가져와야 합니다. Bedrock, Vertex 및 Foundry는 일반적인 공급자 자격 증명을 사용합니다.59베어 모드는 OAuth 및 키체인 읽기를 건너뜁니다. Anthropic 인증은 `ANTHROPIC_API_KEY` 또는 `--settings`에 전달된 JSON의 `apiKeyHelper`에서 가져와야 합니다. Amazon Bedrock, Google Cloud의 Agent Platform 및 Microsoft Foundry는 일반적인 공급자 자격 증명을 사용합니다.

60 60

61<Note>61<Note>

62 `--bare`는 스크립트 및 SDK 호출에 권장되는 모드이며 향후 릴리스에서 `-p`의 기본값이 될 것입니다.62 `--bare`는 스크립트 및 SDK 호출에 권장되는 모드이며 향후 릴리스에서 `-p`의 기본값이 될 것입니다.

136 --json-schema '{"type":"object","properties":{"functions":{"type":"array","items":{"type":"string"}}},"required":["functions"]}'136 --json-schema '{"type":"object","properties":{"functions":{"type":"array","items":{"type":"string"}}},"required":["functions"]}'

137```137```

138 138

139JSON Schema가 유효하지 않으면 `claude`는 `Error: --json-schema is not a valid JSON Schema`와 함께 종료되고 검증자의 진단이 뒤따릅니다. Claude Code는 `format` 키워드를 사용하는 스키마(예: `"format": "email"`)를 허용하지만 `format`을 주석으로 취급하고 이를 적용하지 않습니다. v2.1.205 이전에는 Claude Code가 유효하지 않은 스키마를 자동으로 무시하고 구조화되지 않은 텍스트를 반환했으며, `format`을 포함하는 모든 스키마를 유효하지 않은 것으로 취급했습니다.

140

139<Tip>141<Tip>

140 [jq](https://jqlang.github.io/jq/)와 같은 도구를 사용하여 응답을 구문 분석하고 특정 필드를 추출합니다:142 [jq](https://jqlang.github.io/jq/)와 같은 도구를 사용하여 응답을 구문 분석하고 특정 필드를 추출합니다:

141 143

182| `uuid` | 문자열 | 고유 이벤트 식별자 |184| `uuid` | 문자열 | 고유 이벤트 식별자 |

183| `session_id` | 문자열 | 이벤트가 속한 세션 |185| `session_id` | 문자열 | 이벤트가 속한 세션 |

184 186

185`system/init` 이벤트는 모델, 도구, MCP 서버 및 로드된 플러그인을 포함한 세션 메타데이터를 보고합니다. [`CLAUDE_CODE_SYNC_PLUGIN_INSTALL`](/ko/env-vars)이 설정되지 않은 경우 스트림의 첫 번째 이벤트이며, 이 경우 `plugin_install` 이벤트가 앞에 옵니다. 플러그인 필드를 사용하여 플러그인이 로드되지 않았을 때 CI를 실패하게 합니다:187`system/init` 이벤트는 모델, 도구, MCP 서버 및 로드된 플러그인을 포함한 세션 메타데이터를 보고합니다. [`CLAUDE_CODE_SYNC_PLUGIN_INSTALL`](/ko/env-vars)이 설정되지 않은 경우 스트림의 첫 번째 이벤트이며, 이 경우 `plugin_install` 이벤트가 앞에 옵니다.

188

189이 이벤트는 또한 이 Claude Code 버전이 구현하는 프로토콜 동작의 이름을 지정하는 선택적 `capabilities` 문자열 배열을 전달합니다(예: `interrupt_receipt_v1`). 버전 문자열을 비교하는 대신 기능을 감지하는 데 사용하고 인식하지 못하는 값은 무시합니다. 이 필드는 Claude Code v2.1.205 이상이 필요하며 이전 버전에는 없습니다. 기능 목록은 [`SDKSystemMessage`](/ko/agent-sdk/typescript#sdksystemmessage)를 참조하십시오.

190

191플러그인 필드를 사용하여 플러그인이 로드되지 않았을 때 CI를 실패하게 합니다:

186 192

187| 필드 | 유형 | 설명 |193| 필드 | 유형 | 설명 |

188| --------------- | -- | ---------------------------------------------------------------------------------------------------------------------------- |194| --------------- | -- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |

189| `plugins` | 배열 | 성공적으로 로드된 플러그인, 각각 `name` 및 `path` 포함 |195| `plugins` | 배열 | 성공적으로 로드된 플러그인, 각각 `name` 및 `path` 포함 |

190| `plugin_errors` | 배열 | 만족하지 않은 종속성 버전과 같은 플러그인 로드 시간 오류, 각각 `plugin`, `type` 및 `message` 포함. 영향을 받는 플러그인은 강등되고 `plugins`에서 제외됩니다. 오류가 없을 때 키는 생략됩니다 |196| `plugin_errors` | 배열 | 만족하지 않은 종속성 버전 및 `--plugin-dir` 로드 실패(예: 누락된 경로 또는 유효하지 않은 아카이브)와 같은 플러그인 로드 시간 오류, 각각 `plugin`, `type` 및 `message` 포함. 영향을 받는 플러그인은 강등되고 `plugins`에서 제외됩니다. 오류가 없을 때 키는 생략됩니다 |

191 197

192[`CLAUDE_CODE_SYNC_PLUGIN_INSTALL`](/ko/env-vars)이 설정되면 Claude Code는 첫 번째 턴 전에 마켓플레이스 플러그인이 설치되는 동안 `system/plugin_install` 이벤트를 내보냅니다. 이를 사용하여 자신의 UI에서 설치 진행 상황을 표시합니다.198[`CLAUDE_CODE_SYNC_PLUGIN_INSTALL`](/ko/env-vars)이 설정되면 Claude Code는 첫 번째 턴 전에 마켓플레이스 플러그인이 설치되는 동안 `system/plugin_install` 이벤트를 내보냅니다. 이를 사용하여 자신의 UI에서 설치 진행 상황을 표시합니다.

193 199

234`--allowedTools` 플래그는 [권한 규칙 구문](/ko/settings#permission-rule-syntax)을 사용합니다. 뒤의 ` *`는 접두사 일치를 활성화하므로 `Bash(git diff *)`는 `git diff`로 시작하는 모든 명령을 허용합니다. 공백이 중요합니다: 없으면 `Bash(git diff*)`도 `git diff-index`와 일치합니다.240`--allowedTools` 플래그는 [권한 규칙 구문](/ko/settings#permission-rule-syntax)을 사용합니다. 뒤의 ` *`는 접두사 일치를 활성화하므로 `Bash(git diff *)`는 `git diff`로 시작하는 모든 명령을 허용합니다. 공백이 중요합니다: 없으면 `Bash(git diff*)`도 `git diff-index`와 일치합니다.

235 241

236<Note>242<Note>

237 사용자가 호출한 [skills](/ko/skills) 및 사용자 정의 명령은 `-p` 모드에서 작동합니다: 프롬프트 문자열에 `/skill-name`을 포함하면 Claude Code가 실행하기 전에 이를 확장합니다. `/login`과 같은 대화형 대화를 열어주는 기본 제공 명령은 `-p` 모드에서 사용할 수 없습니다. {/* min-version: 2.1.181 */}`-p` 호출에서 설정을 변경하려면 `/config`에 `key=value`를 전달합니다. 예를 들어 `/config thinking=false`.243 사용자가 호출한 [skills](/ko/skills) 및 사용자 정의 명령은 `-p` 모드에서 작동합니다: 프롬프트 문자열에 `/skill-name`을 포함하면 Claude Code가 실행하기 전에 이를 확장합니다. `/login`과 같은 대화형 대화를 열어주는 기본 제공 명령은 `-p` 모드에서 사용할 수 없습니다. {/* min-version: 2.1.205 */}`/model`, `/effort`, `/fast`, `/color` 및 `/rename`은 값을 인수로 받습니다(예: `/model sonnet`). `/mcp`는 인수 없이 서버 상태의 텍스트 요약을 출력합니다. 이러한 형식은 Claude Code v2.1.205 이상이 필요하며 각 명령의 [가용성 참고 사항](/ko/commands#all-commands)을 따릅니다. {/* min-version: 2.1.181 */}`-p` 호출에서 설정을 변경하려면 `/config`에 `key=value`를 전달합니다(예: `/config thinking=false`).

238</Note>244</Note>

239 245

240<h3 id="customize-the-system-prompt">246<h3 id="customize-the-system-prompt">

hooks.md +16 −10

Details

282 282

283정확한 일치 집합의 하이픈은 Claude Code v2.1.195 이상이 필요합니다. 이전 버전에서는 `mcp__brave-search`와 같은 bare 하이픈이 있는 접두사가 앵커 없는 정규식으로 평가되고 해당 서버의 모든 도구와 일치합니다. `mcp__brave-search__.*` 형식은 모든 버전에서 작동합니다.283정확한 일치 집합의 하이픈은 Claude Code v2.1.195 이상이 필요합니다. 이전 버전에서는 `mcp__brave-search`와 같은 bare 하이픈이 있는 접두사가 앵커 없는 정규식으로 평가되고 해당 서버의 모든 도구와 일치합니다. `mcp__brave-search__.*` 형식은 모든 버전에서 작동합니다.

284 284

285[plugin 번들 MCP 서버](/ko/mcp#plugin-provided-mcp-servers)의 도구는 plugin 이름을 포함하는 범위가 지정된 서버 세그먼트를 사용합니다: `mcp__plugin_<plugin-name>_<server-name>__<tool>`. bare 서버 키에 대해 작성된 matcher는 이러한 도구에 대해 발생하지 않습니다. `my-plugin`이라는 plugin이 `db` 키 아래에 서버를 번들하는 경우 `query` 도구는 `mcp__plugin_my-plugin_db__query`로 나타나므로 해당 서버의 모든 도구에 대한 matcher는 `mcp__plugin_my-plugin_db__.*`입니다. 핸들러의 [`if` 필드](#common-fields)에서 동일한 범위가 지정된 도구 이름을 사용합니다. 범위가 지정된 이름이 구축되는 방식에 대해서는 [Plugin 제공 MCP 서버](/ko/mcp#plugin-provided-mcp-servers)를 참조하세요.

286

285이 예제는 모든 memory 서버 작업을 기록하고 모든 MCP 서버의 쓰기 작업을 검증합니다:287이 예제는 모든 memory 서버 작업을 기록하고 모든 MCP 서버의 쓰기 작업을 검증합니다:

286 288

287```json theme={null}289```json theme={null}

458[공통 필드](#common-fields) 외에도 MCP 도구 hook은 이러한 필드를 허용합니다:460[공통 필드](#common-fields) 외에도 MCP 도구 hook은 이러한 필드를 허용합니다:

459 461

460| 필드 | 필수 | 설명 |462| 필드 | 필수 | 설명 |

461| :------- | :-- | :----------------------------------------------------------------------------------------------------------------- |463| :------- | :-- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

462| `server` | 예 | 구성된 MCP 서버의 이름. 서버는 이미 연결되어 있어야 합니다. hook은 OAuth 또는 연결 흐름을 트리거하지 않습니다 |464| `server` | 예 | 구성된 MCP 서버의 이름. [plugin 번들 서버](/ko/mcp#plugin-provided-mcp-servers)의 경우 범위가 지정된 이름 `plugin:<plugin-name>:<server-name>` (예: `plugin:my-plugin:db`)이며 bare 서버 키가 아닙니다. 서버는 이미 연결되어 있어야 합니다. hook은 OAuth 또는 연결 흐름을 트리거하지 않습니다 |

463| `tool` | 예 | 해당 서버에서 호출할 도구의 이름 |465| `tool` | 예 | 해당 서버에서 호출할 도구의 이름 |

464| `input` | 아니오 | 도구에 전달되는 인수. 문자열 값은 hook의 [JSON 입력](#hook-input-and-output)에서 `${path}` 치환을 지원합니다 (예: `"${tool_input.file_path}"`) |466| `input` | 아니오 | 도구에 전달되는 인수. 문자열 값은 hook의 [JSON 입력](#hook-input-and-output)에서 `${path}` 치환을 지원합니다 (예: `"${tool_input.file_path}"`) |

465 467

640| :---------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |642| :---------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

642| `prompt_id` | 현재 처리 중인 사용자 프롬프트를 식별하는 UUID입니다. [OpenTelemetry 이벤트의 `prompt.id` 속성](/ko/monitoring-usage#event-correlation-attributes)과 일치하므로 hook 출력을 단일 프롬프트의 원격 분석과 연관시킬 수 있습니다. 첫 번째 사용자 입력까지 없습니다. {/* min-version: 2.1.196 */}Claude Code v2.1.196 이상 필요 |644| `prompt_id` | 현재 처리 중인 사용자 프롬프트를 식별하는 UUID입니다. [OpenTelemetry 이벤트의 `prompt.id` 속성](/ko/monitoring-usage#event-correlation-attributes)과 일치하므로 hook 출력을 단일 프롬프트의 원격 분석과 연관시킬 수 있습니다. 첫 번째 사용자 입력까지 없습니다. {/* min-version: 2.1.196 */}Claude Code v2.1.196 이상 필요 |

643| `transcript_path` | 대화 JSON 경로 |645| `transcript_path` | 대화 JSON 경로입니다. 트랜스크립트 파일은 비동기적으로 기록되며 메모리 내 대화보다 뒤떨어질 수 있으므로 hook이 발생할 때 현재 턴의 가장 최근 메시지를 아직 포함하지 않을 수 있습니다. 현재 턴의 최종 어시스턴트 텍스트가 필요한 hook은 트랜스크립트를 읽는 대신 [Stop](#stop) 및 [SubagentStop](#subagentstop)에서 `last_assistant_message`를 사용해야 합니다 |

644| `cwd` | hook이 호출될 때의 현재 작업 디렉토리 |646| `cwd` | hook이 호출될 때의 현재 작업 디렉토리 |

645| `permission_mode` | 현재 [권한 모드](/ko/permissions#permission-modes): `"default"`, `"plan"`, `"acceptEdits"`, `"auto"`, `"dontAsk"` 또는 `"bypassPermissions"`. 모든 이벤트가 이 필드를 받는 것은 아닙니다: 각 이벤트의 JSON 예제를 확인하세요 |647| `permission_mode` | 현재 [권한 모드](/ko/permissions#permission-modes): `"default"`, `"plan"`, `"acceptEdits"`, `"auto"`, `"dontAsk"` 또는 `"bypassPermissions"`. **수동**으로 표시된 모드는 `"default"`로 도착하며 `"manual"`로 도착하지 않으므로 `"default"`와 일치하는 스크립트는 계속 작동합니다. 모든 이벤트가 이 필드를 받는 것은 아닙니다. 각 [hook 이벤트](#hook-events) 섹션의 JSON 예제를 확인하세요 |

646| `effort` | 활성 [노력 수준](/ko/model-config#adjust-effort-level)을 보유하는 `level` 필드가 있는 객체: `"low"`, `"medium"`, `"high"`, `"xhigh"` 또는 `"max"`. 요청된 모델 노력이 현재 모델이 지원하는 것을 초과하면 이는 모델이 실제로 사용한 다운그레이드된 수준입니다. Ultracode는 별개의 수준이 아니며 `"xhigh"`로 보고됩니다. 객체는 [상태 줄](/ko/statusline#available-data) `effort` 필드와 일치합니다. `PreToolUse`, `PostToolUse`, `Stop`, `SubagentStop`과 같은 도구 사용 컨텍스트 내에서 발생하는 이벤트에 대해 현재 모델이 노력 매개변수를 지원할 때 존재합니다. 수준은 `$CLAUDE_EFFORT` 환경 변수로 hook 명령 및 Bash 도구에서도 사용 가능합니다. |648| `effort` | 활성 [노력 수준](/ko/model-config#adjust-effort-level)을 보유하는 `level` 필드가 있는 객체: `"low"`, `"medium"`, `"high"`, `"xhigh"` 또는 `"max"`. 요청된 모델 노력이 현재 모델이 지원하는 것을 초과하면 이는 모델이 실제로 사용한 다운그레이드된 수준입니다. Ultracode는 별개의 수준이 아니며 `"xhigh"`로 보고됩니다. 객체는 [상태 줄](/ko/statusline#available-data) `effort` 필드와 일치합니다. `PreToolUse`, `PostToolUse`, `Stop`, `SubagentStop`과 같은 도구 사용 컨텍스트 내에서 발생하는 이벤트에 대해 현재 모델이 노력 매개변수를 지원할 때 존재합니다. 수준은 `$CLAUDE_EFFORT` 환경 변수로 hook 명령 및 Bash 도구에서도 사용 가능합니다. |

648 650

1081 Setup1083 Setup

1082</h3>1084</h3>

1083 1085

1084`--init-only`로 Claude Code를 시작하거나 비대화형 모드(/ko/headless)에서 `-p` 플래그와 함께 `--init` 또는 `--maintenance`로 시작할 때만 발생합니다. 일반 시작 시에는 발생하지 않습니다. 일회성 종속성 설치 또는 CI 또는 스크립트에서 명시적으로 트리거하는 예약된 정리에 사용합니다. 일반 세션 시작과 별도입니다. 세션별 초기화의 경우 [SessionStart](#sessionstart)를 대신 사용합니다.1086`--init-only`로 Claude Code를 시작하거나 [비대화형 모드](/ko/headless)에서 `-p` 플래그와 함께 `--init` 또는 `--maintenance`로 시작할 때만 발생합니다. 일반 시작 시에는 발생하지 않습니다. 일회성 종속성 설치 또는 CI 또는 스크립트에서 명시적으로 트리거하는 예약된 정리에 사용합니다. 일반 세션 시작과 별도입니다. 세션별 초기화의 경우 [SessionStart](#sessionstart)를 대신 사용합니다.

1085 1087

1086matcher 값은 hook을 트리거한 CLI 플래그에 해당합니다:1088matcher 값은 hook을 트리거한 CLI 플래그에 해당합니다:

1087 1089

1593 ExitPlanMode1595 ExitPlanMode

1594</h5>1596</h5>

1595 1597

1596Claude가 [plan 모드](/ko/permission-modes#analyze-before-you-edit-with-plan-mode)를 떠나기 전에 계획을 제시하고 사용자에게 승인을 요청합니다. Claude는 도구를 호출하기 전에 계획을 파일에 디스크에 작성하므로 모델의 리터럴 `tool_input`은 `allowedPrompts`만 전달합니다. Claude Code는 hook에 전달하기 전에 계획 내용과 파일 경로를 주입합니다.1598Claude가 [plan 모드](/ko/permission-modes#analyze-before-you-edit-with-plan-mode)를 떠나기 전에 계획을 제시하고 사용자에게 승인을 요청합니다. Claude는 도구를 호출하기 전에 계획을 파일에 디스크에 작성하므로 모델의 리터럴 `tool_input`은 일반적으로 비어 있습니다. Claude Code는 hook에 전달하기 전에 계획 내용과 파일 경로를 주입합니다.

1597 1599

1598| 필드 | 유형 | 예제 | 설명 |1600| 필드 | 유형 | 예제 | 설명 |

1599| :--------------- | :-- | :------------------------------------------ | :----------------------------------------------------------------------------- |1601| :--------------- | :-- | :------------------------------------------ | :---------------------------------------------------------------------------------------------------------------------------------- |

1602| `allowedPrompts` | 배열 | `[{"tool": "Bash", "prompt": "run tests"}]` | 선택적. Claude가 계획을 구현하기 위해 요청하는 prompt 기반 권한, 각각 `tool` 이름과 작업 범주를 설명하는 `prompt` |1604| `allowedPrompts` | 배열 | `[{"tool": "Bash", "prompt": "run tests"}]` | {/* min-version: 2.1.205 */}더 이상 사용되지 않음. Claude Code는 필드를 수락하지만 무시합니다. v2.1.205 이전에는 Claude가 계획을 구현하기 위해 요청하는 prompt 기반 권한을 전달했습니다 |

1603 1605

1604`PostToolUse`에서 `tool_response`는 승인된 계획을 보유하는 `plan` 및 `filePath` 필드가 있는 객체이며, 내부 상태 플래그도 있습니다. 디스크에서 파일을 다시 읽는 대신 `tool_response.plan`에서 계획 내용을 읽으세요.1606`PostToolUse`에서 `tool_response`는 승인된 계획을 보유하는 `plan` 및 `filePath` 필드가 있는 객체이며, 내부 상태 플래그도 있습니다. 디스크에서 파일을 다시 읽는 대신 `tool_response.plan`에서 계획 내용을 읽으세요.

1605 1607

1759`updatedPermissions` 출력 필드와 [`permission_suggestions` 입력 필드](#permissionrequest-input) 모두 동일한 항목 객체 배열을 사용합니다. 각 항목에는 다른 필드를 결정하는 `type`과 변경이 작성되는 위치를 제어하는 `destination`이 있습니다.1761`updatedPermissions` 출력 필드와 [`permission_suggestions` 입력 필드](#permissionrequest-input) 모두 동일한 항목 객체 배열을 사용합니다. 각 항목에는 다른 필드를 결정하는 `type`과 변경이 작성되는 위치를 제어하는 `destination`이 있습니다.

1760 1762

1761| `type` | 필드 | 효과 |1763| `type` | 필드 | 효과 |

1762| :------------------ | :--------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------- |1764| :------------------ | :--------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

1763| `addRules` | `rules`, `behavior`, `destination` | 권한 규칙을 추가합니다. `rules`는 `{toolName, ruleContent?}` 객체의 배열입니다. 전체 도구와 일치하려면 `ruleContent`를 생략합니다. `behavior`는 `"allow"`, `"deny"` 또는 `"ask"`입니다 |1765| `addRules` | `rules`, `behavior`, `destination` | 권한 규칙을 추가합니다. `rules`는 `{toolName, ruleContent?}` 객체의 배열입니다. 전체 도구와 일치하려면 `ruleContent`를 생략합니다. `behavior`는 `"allow"`, `"deny"` 또는 `"ask"`입니다 |

1766| `setMode` | `mode`, `destination` | 권한 모드를 변경합니다. 유효한 모드는 `default`, `auto`, `acceptEdits`, `dontAsk`, `bypassPermissions`, `plan`입니다 |1768| `setMode` | `mode`, `destination` | 권한 모드를 변경합니다. 유효한 모드는 `default`, `auto`, `acceptEdits`, `dontAsk`, `bypassPermissions`, `plan`, {/* min-version: 2.1.200 */}`manual` (기본값의 별칭)입니다. `manual` 별칭은 Claude Code v2.1.200 이상이 필요합니다 |

1769 1771

2701 2703

2702hook이 실패하거나 경로를 생성하지 않으면 worktree 생성이 오류로 실패합니다.2704hook이 실패하거나 경로를 생성하지 않으면 worktree 생성이 오류로 실패합니다.

2703 2705

2706Claude Code는 hook이 실행된 디렉토리에 대해 상대 경로를 해결합니다. 결과 경로가 Claude Code가 들어갈 수 있는 디렉토리가 아니면 세션은 경로를 이름으로 지정하는 오류를 인쇄하고 코드 1로 종료됩니다. v2.1.205 이전에는 상대 경로 또는 디스크에 존재하지 않는 경로가 세션 시작 시 충돌했고, `-p`를 사용하면 약 30초 동안 정지한 후 코드 0으로 종료되었습니다.

2707

2704<h3 id="worktreeremove">2708<h3 id="worktreeremove">

2705 WorktreeRemove2709 WorktreeRemove

2706</h3>2710</h3>

3220 3224

3221백그라운드 프로세스가 종료된 후 hook이 `additionalContext` 필드가 있는 JSON 응답을 생성한 경우 해당 콘텐츠는 다음 대화 턴에서 Claude에 컨텍스트로 전달됩니다. `systemMessage` 필드는 Claude가 아닌 사용자에게 표시됩니다.3225백그라운드 프로세스가 종료된 후 hook이 `additionalContext` 필드가 있는 JSON 응답을 생성한 경우 해당 콘텐츠는 다음 대화 턴에서 Claude에 컨텍스트로 전달됩니다. `systemMessage` 필드는 Claude가 아닌 사용자에게 표시됩니다.

3222 3226

3227Claude Code는 JSON 응답을 동기 hook과 동일한 [출력 스키마](#json-output)에 대해 검증하고, `systemMessage`가 문자열이 아닌 경우와 같이 값의 유형이 잘못된 필드를 전달하지 않고 삭제합니다. `--debug`로 실행하여 삭제된 각 필드의 이름을 지정하는 경고를 확인합니다. v2.1.202 이전에는 비동기 hook의 잘못된 형식의 JSON 출력이 세션을 충돌시킬 수 있었고, 세션이 재개될 때마다 충돌이 반복되었습니다.

3228

3223비동기 hook 완료 알림은 기본적으로 억제됩니다. 보려면 `Ctrl+O`로 자세한 모드를 활성화하거나 `--verbose`로 Claude Code를 시작합니다.3229비동기 hook 완료 알림은 기본적으로 억제됩니다. 보려면 `Ctrl+O`로 자세한 모드를 활성화하거나 `--verbose`로 Claude Code를 시작합니다.

3224 3230

3225<h3 id="run-tests-after-file-changes">3231<h3 id="run-tests-after-file-changes">

how-claude-code-works.md +1 −1

Details

210내장 명령도 설정을 안내합니다:210내장 명령도 설정을 안내합니다:

211 211

212* `/init`은 프로젝트를 위한 CLAUDE.md 생성을 안내합니다212* `/init`은 프로젝트를 위한 CLAUDE.md 생성을 안내합니다

213* `/doctor`는 설치의 일반적인 문제를 진단합니다213* `/doctor`는 설치 및 구성 문제를 진단하고 수정할 수 있습니다

214 214

215<h3 id="it’s-a-conversation">215<h3 id="it’s-a-conversation">

216 대화형입니다216 대화형입니다

interactive-mode.md +5 −3

Details

27</h3>27</h3>

28 28

29| 단축키 | 설명 | 컨텍스트 |29| 단축키 | 설명 | 컨텍스트 |

30| :------------------------------------------------------ | :----------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |30| :------------------------------------------------------ | :----------------------------------------------------------------------------------------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

42| `Up/Down 화살표` 또는 `Ctrl+P`/`Ctrl+N` | 커서 이동 또는 명령 기록 탐색 | 입력이 여러 시각적 줄에 걸쳐 있을 때(줄 바꿈 또는 여러 줄 여부), 먼저 프롬프트 내에서 커서를 이동합니다. 커서가 첫 번째 또는 마지막 시각적 줄에 있으면 다시 누르면 명령 기록을 탐색합니다. {/* min-version: 2.1.169 */}v2.1.169부터 줄 바꿈된 단일 줄 입력은 여러 줄과 동일하게 작동합니다 |42| `Up/Down 화살표` 또는 `Ctrl+P`/`Ctrl+N` | 커서 이동 또는 명령 기록 탐색 | 입력이 여러 시각적 줄에 걸쳐 있을 때(줄 바꿈 또는 여러 줄 여부), 먼저 프롬프트 내에서 커서를 이동합니다. 커서가 첫 번째 또는 마지막 시각적 줄에 있으면 다시 누르면 명령 기록을 탐색합니다. {/* min-version: 2.1.169 */}v2.1.169부터 줄 바꿈된 단일 줄 입력은 여러 줄과 동일하게 작동합니다 |

43| `Esc` | Claude 중단 | 현재 응답 또는 도구 호출을 중간에 중지하여 리다이렉트할 수 있습니다. Claude는 지금까지 수행한 작업을 유지합니다 |43| `Esc` | Claude 중단 또는 대화 상자 닫기 | 현재 응답 또는 도구 호출을 중간에 중지하여 리다이렉트할 수 있습니다. Claude는 지금까지 수행한 작업을 유지합니다. 권한 프롬프트와 같은 대화 상자가 열려 있으면 `Esc`는 Claude를 중단하는 대신 대화 상자를 닫습니다. {/* min-version: 2.1.202 */}v2.1.202 이전에는 일부 대화 상자에서 `Esc`가 Claude를 중단하고 대화 상자를 열린 상태로 두었습니다 |

44| `Esc` + `Esc` | 입력 초안 지우기 또는 되돌리기 | 프롬프트 입력에 텍스트가 포함되어 있으면 이중 `Esc`는 이를 지우고 초안을 기록에 저장하여 `Up`으로 회수할 수 있습니다. 입력이 비어 있으면 이중 `Esc`는 [되돌리기 메뉴](/ko/checkpointing)를 열어 이전 지점에서 코드 및 대화를 복원하거나 요약합니다 |44| `Esc` + `Esc` | 입력 초안 지우기 또는 되돌리기 | 프롬프트 입력에 텍스트가 포함되어 있으면 이중 `Esc`는 이를 지우고 초안을 기록에 저장하여 `Up`으로 회수할 수 있습니다. 입력이 비어 있으면 이중 `Esc`는 [되돌리기 메뉴](/ko/checkpointing)를 열어 이전 지점에서 코드 및 대화를 복원하거나 요약합니다 |

45| `Shift+Tab` 또는 `Alt+M` (일부 구성) | 권한 모드 순환 | `default`, `acceptEdits`, `plan` 및 `auto` 또는 `bypassPermissions`와 같이 활성화한 모든 모드를 순환합니다. [권한 모드](/ko/permission-modes)를 참조하세요. |45| `Shift+Tab` 또는 `Alt+M` (일부 구성) | 권한 모드 순환 | `default`(모드 표시기에서 Manual로 표시됨), `acceptEdits`, `plan` 및 `auto` 또는 `bypassPermissions`와 같이 활성화한 모든 모드를 순환합니다. [권한 모드](/ko/permission-modes)를 참조하세요. |

47| `Option+T` (macOS) 또는 `Alt+T` (Windows/Linux) | 확장 사고 토글 | 확장 사고 모드를 활성화 또는 비활성화합니다. Fable 5에는 영향을 주지 않으며, 항상 확장 사고를 사용합니다. {/* min-version: 2.1.132 */}v2.1.132부터 이 단축키는 macOS에서 Option을 Meta로 구성하지 않고도 작동합니다 |47| `Option+T` (macOS) 또는 `Alt+T` (Windows/Linux) | 확장 사고 토글 | 확장 사고 모드를 활성화 또는 비활성화합니다. Fable 5에는 영향을 주지 않으며, 항상 확장 사고를 사용합니다. {/* min-version: 2.1.132 */}v2.1.132부터 이 단축키는 macOS에서 Option을 Meta로 구성하지 않고도 작동합니다 |

270 270

271검색은 선택한 범위에서 가장 최근의 고유한 프롬프트 100개를 로드하며, 중복은 가장 최신 항목으로 축소됩니다. 일치하는 프롬프트는 검색어가 강조된 상태로 표시되므로 이전 입력을 찾아 재사용할 수 있습니다.271검색은 선택한 범위에서 가장 최근의 고유한 프롬프트 100개를 로드하며, 중복은 가장 최신 항목으로 축소됩니다. 일치하는 프롬프트는 검색어가 강조된 상태로 표시되므로 이전 입력을 찾아 재사용할 수 있습니다.

272 272

273일치를 수락하거나 검색을 취소하면 Claude Code가 여전히 기록을 로드 중이더라도 즉시 적용됩니다. v2.1.202 이전에는 로드 중에 수락하거나 취소하면 내부 오류가 보고될 수 있었습니다.

274

273<h2 id="background-bash-commands">275<h2 id="background-bash-commands">

274 백그라운드 Bash 명령276 백그라운드 Bash 명령

275</h2>277</h2>

keybindings.md +14 −15

Details

71| `Select` | 일반 선택/목록 구성 요소 |71| `Select` | 일반 선택/목록 구성 요소 |

72| `Plugin` | 플러그인 대화 상자(찾아보기, 발견, 관리) |72| `Plugin` | 플러그인 대화 상자(찾아보기, 발견, 관리) |

73| `Scroll` | 전체 화면 모드에서 대화 스크롤 및 텍스트 선택 |73| `Scroll` | 전체 화면 모드에서 대화 스크롤 및 텍스트 선택 |

~~74| `Doctor` | `/doctor` 진단 화면 |~~74

75{/* max-version: 2.1.204 */}v2.1.205 이전에는 `/doctor` 진단 화면에 대한 `Doctor` 컨텍스트와 `doctor:fix` 작업이 존재했습니다.

75 76

76<h2 id="available-actions">77<h2 id="available-actions">

77 사용 가능한 작업78 사용 가능한 작업

358 359

359<h3 id="doctor-actions">

360 Doctor 작업

361</h3>

~~362~~

363`Doctor` 컨텍스트에서 사용 가능한 작업:

~~364~~

365| 작업 | 기본값 | 설명 |

366| :----------- | :-- | :-------------------------------------------------- |

367| `doctor:fix` | F | 진단 보고서를 Claude에 보내 보고된 문제를 해결합니다. 문제가 발견되었을 때만 활성화됨 |

~~368~~

369<h3 id="voice-actions">360<h3 id="voice-actions">

370 음성 작업361 음성 작업

371</h3>362</h3>

373[음성 받아쓰기](/ko/voice-dictation)가 활성화되었을 때 `Chat` 컨텍스트에서 사용 가능한 작업:364[음성 받아쓰기](/ko/voice-dictation)가 활성화되었을 때 `Chat` 컨텍스트에서 사용 가능한 작업:

374 365

375| 작업 | 기본값 | 설명 |366| 작업 | 기본값 | 설명 |

376| :----------------- | :---- | :------------------- |367| :----------------- | :---- | :--------- |

378 369

379<h3 id="scroll-actions">370<h3 id="scroll-actions">

380 스크롤 작업371 스크롤 작업

477}468}

478```469```

479 470

480이는 코드 바인딩에도 작동합니다. 접두사를 공유하는 모든 코드를 바인딩 해제하면 해당 접두사를 단일 키 바인딩으로 사용할 수 있습니다:471이는 코드 바인딩에도 작동합니다. 접두사를 공유하는 모든 코드를 바인딩 해제하면 해당 접두사를 단일 키 바인딩으로 사용할 수 있습니다. 모든 활성 컨텍스트의 코드는 해당 접두사를 예약된 상태로 유지하므로 해당 코드를 정의하는 컨텍스트에서 각 코드를 바인딩 해제해야 합니다.

472

473기본 `Ctrl+X` 패밀리는 두 개의 컨텍스트에 걸쳐 있습니다: `Chat`의 `ctrl+x ctrl+k`와 `ctrl+x ctrl+e`, 그리고 `Task`의 `ctrl+x ctrl+b`. `ctrl+x` 자체를 단일 키 바인딩으로 되찾으려면 모두 바인딩 해제합니다:

481 474

482```json theme={null}475```json theme={null}

483{476{

484 "bindings": [477 "bindings": [

478 {

479 "context": "Task",

480 "bindings": {

481 "ctrl+x ctrl+b": null

482 }

483 },

485 {484 {

486 "context": "Chat",485 "context": "Chat",

487 "bindings": {486 "bindings": {

546* 터미널 멀티플렉서 충돌545* 터미널 멀티플렉서 충돌

547* 동일한 컨텍스트의 중복 바인딩546* 동일한 컨텍스트의 중복 바인딩

548 547

549`/doctor`를 실행하여 키바인딩 경고를 확인합니다.548Claude Code는 파일이 로드될 때 경고를 보고하며 각각을 디버그 로그에 기록합니다. [`--debug`](/ko/cli-reference#cli-flags)를 사용하여 Claude Code를 시작하면 세부 정보를 확인할 수 있습니다.

legal-and-compliance.md +1 −1

Details

23 상용 계약23 상용 계약

24</h3>24</h3>

25 25

26Claude API를 직접 사용하든(1P) Amazon Bedrock 또는 Google Vertex를 통해 접근하든(3P), 기존 상용 계약이 Claude Code 사용에 적용되며, 달리 상호 합의하지 않는 한 그러합니다.26Claude API를 직접 사용하든(1P) Amazon Bedrock 또는 Google Cloud의 Agent Platform을 통해 접근하든(3P), 기존 상용 계약이 Claude Code 사용에 적용되며, 달리 상호 합의하지 않는 한 그러합니다.

27 27

28<h2 id="compliance">28<h2 id="compliance">

29 규정 준수29 규정 준수

llm-gateway-connect.md +8 −6

Details

209 데스크톱 앱209 데스크톱 앱

210</h3>210</h3>

211 211

212데스크톱 앱은 `ANTHROPIC_BASE_URL` 또는 `settings.json`이 아닌 [관리자 배포 구성](https://claude.com/docs/cowork/3p/gateway)에서 게이트웨이 라우팅을 읽습니다. 조직이 이를 배포했다면, 데스크톱 앱은 설정 없이 게이트웨이를 통해 라우팅됩니다. 그렇지 않으면 게이트웨이 세션에 터미널 CLI 또는 VS Code 확장을 사용합니다. 관리자는 [조직 배포](/ko/llm-gateway-rollout#distribute-through-managed-settings)에 설명된 대로 구성을 배포합니다.212데스크톱 앱은 `ANTHROPIC_BASE_URL` 또는 `settings.json`이 아닌 [관리자 배포 구성](https://claude.com/docs/third-party/claude-desktop/gateway)에서 게이트웨이 라우팅을 읽습니다. 조직이 이를 배포했다면, 데스크톱 앱은 설정 없이 게이트웨이를 통해 라우팅됩니다. 그렇지 않으면 게이트웨이 세션에 터미널 CLI 또는 VS Code 확장을 사용합니다. 관리자는 [조직 배포](/ko/llm-gateway-rollout#distribute-through-managed-settings)에 설명된 대로 구성을 배포합니다.

213 213

214데스크톱 앱이 `Gateway was unreachable`을 표시하면, 앱이 시작 시 구성된 기본 URL에 도달할 수 없었습니다. 위의 [curl 테스트](#verify-the-connection)로 URL과 네트워크 경로를 확인합니다.214데스크톱 앱이 `Gateway was unreachable`을 표시하면, 앱이 시작 시 구성된 기본 URL에 도달할 수 없었습니다. 위의 [curl 테스트](#verify-the-connection)로 URL과 네트워크 경로를 확인합니다.

215 215

287 287

288[Remote Control](/ko/remote-control) 및 [음성 받아쓰기](/ko/voice-dictation)는 모두 claude.ai 신원에 의존합니다: Remote Control은 라이브 세션을 계정과 쌍으로 만들고, 음성 받아쓰기는 claude.ai 전사 엔드포인트에 도달합니다. `ANTHROPIC_API_KEY`, `ANTHROPIC_AUTH_TOKEN` 또는 `apiKeyHelper`가 활성화되어 있는 동안은 사용할 수 없습니다. {/* min-version: 2.1.196 */}v2.1.196부터 Remote Control은 `ANTHROPIC_BASE_URL`이 Anthropic이 아닌 호스트를 가리킬 때도 비활성화되므로, claude.ai로 로그인하는 것만으로는 충분하지 않습니다.288[Remote Control](/ko/remote-control) 및 [음성 받아쓰기](/ko/voice-dictation)는 모두 claude.ai 신원에 의존합니다: Remote Control은 라이브 세션을 계정과 쌍으로 만들고, 음성 받아쓰기는 claude.ai 전사 엔드포인트에 도달합니다. `ANTHROPIC_API_KEY`, `ANTHROPIC_AUTH_TOKEN` 또는 `apiKeyHelper`가 활성화되어 있는 동안은 사용할 수 없습니다. {/* min-version: 2.1.196 */}v2.1.196부터 Remote Control은 `ANTHROPIC_BASE_URL`이 Anthropic이 아닌 호스트를 가리킬 때도 비활성화되므로, claude.ai로 로그인하는 것만으로는 충분하지 않습니다.

289 289

290기능을 복원하려면 claude.ai로 로그인하고 확인하는 게이트웨이 변수를 설정 해제합니다. `/doctor`는 설정 해제할 자격 증명 변수를 명시합니다.290기능을 복원하려면 claude.ai로 로그인하고 확인하는 게이트웨이 변수를 설정 해제합니다. Remote Control 섹션의 `claude doctor`는 설정 해제할 자격 증명 변수를 명시합니다.

291 291

292* 음성 받아쓰기: 게이트웨이 자격 증명 설정 해제292* 음성 받아쓰기: 게이트웨이 자격 증명 설정 해제

293* Remote Control: 게이트웨이 자격 증명 및 `ANTHROPIC_BASE_URL` 설정 해제293* Remote Control: 게이트웨이 자격 증명 및 `ANTHROPIC_BASE_URL` 설정 해제

393 게이트웨이를 통해 클라우드 제공자로 라우팅393 게이트웨이를 통해 클라우드 제공자로 라우팅

394</h3>394</h3>

395 395

396이러한 구성은 Claude Code를 `ANTHROPIC_BASE_URL` 대신 제공자 관련 기본 URL 변수를 통해 게이트웨이로 가리킵니다. Bedrock 및 Agent Platform 게이트웨이는 이러한 제공자의 기본 요청 형식을 허용합니다. Foundry 및 AWS의 Claude Platform 게이트웨이는 Anthropic Messages 형식을 허용하고 어느 기본 URL 변수가 이에 도달하는지에서만 다릅니다.396이러한 구성은 Claude Code를 `ANTHROPIC_BASE_URL` 대신 제공자 관련 기본 URL 변수를 통해 게이트웨이로 가리킵니다. Amazon Bedrock 및 Google Cloud의 Agent Platform 게이트웨이는 이러한 제공자의 기본 요청 형식을 허용합니다. Microsoft Foundry 및 AWS의 Claude Platform 게이트웨이는 Anthropic Messages 형식을 허용하고 어느 기본 URL 변수가 이에 도달하는지에서만 다릅니다.

397 397

398게이트웨이 팀이 Bedrock, Agent Platform, Foundry 또는 AWS의 Claude Platform을 구체적으로 명시한 경우에만 하나를 사용합니다. 위의 [확인 요청](#verify-the-connection)이 JSON을 반환했다면 이 섹션을 건너뛸 수 있습니다.398게이트웨이 팀이 Amazon Bedrock, Google Cloud의 Agent Platform, Microsoft Foundry 또는 AWS의 Claude Platform을 구체적으로 명시한 경우에만 하나를 사용합니다. 위의 [확인 요청](#verify-the-connection)이 JSON을 반환했다면 이 섹션을 건너뛸 수 있습니다.

399 399

400게이트웨이 팀이 명시한 제공자에 대한 블록을 설정합니다. skip-auth 변수는 게이트웨이가 이를 보유하므로 Claude Code가 제공자 자격 증명으로 요청에 서명하지 않도록 합니다. 게이트웨이가 자체 토큰이 필요하면, 블록 후에 `ANTHROPIC_AUTH_TOKEN`을 추가합니다. Foundry는 표시된 대로 `ANTHROPIC_FOUNDRY_API_KEY`를 사용합니다.400게이트웨이 팀이 명시한 제공자에 대한 블록을 설정합니다. skip-auth 변수는 게이트웨이가 이를 보유하므로 Claude Code가 제공자 자격 증명으로 요청에 서명하지 않도록 합니다. 게이트웨이가 자체 토큰이 필요하면, 블록 후에 `ANTHROPIC_AUTH_TOKEN`을 추가합니다. Microsoft Foundry는 표시된 대로 `ANTHROPIC_FOUNDRY_API_KEY`를 사용합니다. {/* min-version: 2.1.203 */}Bearer 토큰을 예상하는 Microsoft Foundry 게이트웨이는 [`ANTHROPIC_FOUNDRY_AUTH_TOKEN`](/ko/env-vars)을 대신 사용할 수 있습니다. 둘 다 설정된 경우 `ANTHROPIC_FOUNDRY_AUTH_TOKEN`이 `ANTHROPIC_FOUNDRY_API_KEY`보다 우선합니다. `ANTHROPIC_FOUNDRY_AUTH_TOKEN`에는 Claude Code v2.1.203 이상이 필요합니다.

401 401

402<h4 id="amazon-bedrock">402<h4 id="amazon-bedrock">

403 Amazon Bedrock403 Amazon Bedrock

451 Microsoft Foundry451 Microsoft Foundry

452</h4>452</h4>

453 453

454게이트웨이의 자격 증명을 `ANTHROPIC_FOUNDRY_API_KEY`에 넣습니다. `x-api-key` 헤더로 게이트웨이에 전송됩니다. `CLAUDE_CODE_SKIP_FOUNDRY_AUTH`는 여기에 적용되지 않습니다. API 키 없으면 Foundry 클라이언트는 머신을 떠나기 전에 모든 요청을 실패합니다.454게이트웨이의 자격 증명을 `ANTHROPIC_FOUNDRY_API_KEY`에 넣습니다. `x-api-key` 헤더로 게이트웨이에 전송됩니다. {/* min-version: 2.1.203 */}Bearer 토큰을 예상하는 게이트웨이는 [`ANTHROPIC_FOUNDRY_AUTH_TOKEN`](/ko/env-vars)을 대신 사용할 수 있습니다. Claude Code는 해당 값을 `Authorization: Bearer` 헤더로 전송하며, 둘 다 설정된 경우 `ANTHROPIC_FOUNDRY_API_KEY`보다 우선합니다. Claude Code v2.1.203 이상이 필요합니다.

455

456자체 `Authorization` 헤더를 주입하는 게이트웨이의 경우, `CLAUDE_CODE_SKIP_FOUNDRY_AUTH=1`을 설정하고 두 자격 증명 변수를 모두 설정하지 않은 상태로 둡니다. Claude Code는 Azure 자격 증명 없이 요청을 전송하고 `ANTHROPIC_CUSTOM_HEADERS`를 통해 제공하는 것과 같이 사용자가 제공하는 `Authorization` 헤더를 보존합니다. {/* min-version: 2.1.203 */}v2.1.203 이전에는 API 키 없이 `CLAUDE_CODE_SKIP_FOUNDRY_AUTH`를 사용하면 Microsoft Foundry 클라이언트가 요청을 전송할 수 없었습니다.

455 457

456<Tabs>458<Tabs>

457 <Tab title="Bash 또는 Zsh">459 <Tab title="Bash 또는 Zsh">

llm-gateway-protocol.md +13 −13

Details

34 API 형식34 API 형식

35</h2>35</h2>

36 36

37게이트웨이는 Claude Code 클라이언트에 다음 API 형식 중 최소 하나를 노출해야 합니다. Claude Code가 사용하는 형식은 클라이언트의 구성에 의해 결정됩니다. 아래 표의 선택 기준 열의 변수는 Claude Code를 해당 형식의 게이트웨이로 지정합니다. Agent Platform은 Google Cloud의 Claude 엔드포인트이며, 이전에는 Vertex AI였습니다. 변수 이름은 `VERTEX` 철자를 유지합니다.37게이트웨이는 Claude Code 클라이언트에 다음 API 형식 중 최소 하나를 노출해야 합니다. Claude Code가 사용하는 형식은 클라이언트의 구성에 의해 결정됩니다. 아래 표의 선택 기준 열의 변수는 Claude Code를 해당 형식의 게이트웨이로 지정합니다. Google Cloud의 Agent Platform은 Google Cloud의 Claude 엔드포인트이며, 이전에는 Vertex AI였습니다. 변수 이름은 `VERTEX` 철자를 유지합니다.

38 38

39| 형식 | 선택 기준 | 엔드포인트 | 변경 없이 전달 |39| 형식 | 선택 기준 | 엔드포인트 | 변경 없이 전달 |

40| :------------------------ | :------------------------------------------------------------ | :-------------------------------------------------------------------- | :--------------------------------------------------------------------------- |40| :-------------------------------------- | :------------------------------------------------------------ | :-------------------------------------------------------------------- | :--------------------------------------------------------------------------- |

42| Bedrock InvokeModel | `ANTHROPIC_BEDROCK_BASE_URL` with `CLAUDE_CODE_USE_BEDROCK=1` | `/model/{model}/invoke`, `/model/{model}/invoke-with-response-stream` | `anthropic_beta` 및 `anthropic_version` 요청 본문 필드 |42| Amazon Bedrock InvokeModel | `ANTHROPIC_BEDROCK_BASE_URL` with `CLAUDE_CODE_USE_BEDROCK=1` | `/model/{model}/invoke`, `/model/{model}/invoke-with-response-stream` | `anthropic_beta` 및 `anthropic_version` 요청 본문 필드 |

43| Agent Platform rawPredict | `ANTHROPIC_VERTEX_BASE_URL` with `CLAUDE_CODE_USE_VERTEX=1` | `:rawPredict`, `:streamRawPredict`, `count-tokens:rawPredict` (선택 사항) | `anthropic-beta` 및 `anthropic-version` 요청 헤더, 및 `anthropic_version` 요청 본문 필드 |43| Google Cloud의 Agent Platform rawPredict | `ANTHROPIC_VERTEX_BASE_URL` with `CLAUDE_CODE_USE_VERTEX=1` | `:rawPredict`, `:streamRawPredict`, `count-tokens:rawPredict` (선택 사항) | `anthropic-beta` 및 `anthropic-version` 요청 헤더, 및 `anthropic_version` 요청 본문 필드 |

44 44

45<h3 id="foundry-and-claude-platform-on-aws">45<h3 id="foundry-and-claude-platform-on-aws">

46 Foundry 및 AWS의 Claude Platform46 Foundry 및 AWS의 Claude Platform

52 선택 사항 엔드포인트 및 시작 트래픽52 선택 사항 엔드포인트 및 시작 트래픽

53</h3>53</h3>

54 54

55토큰 계산 엔드포인트는 유일한 선택 사항입니다. 이들이 없을 때 Claude Code는 컨텍스트 사용을 로컬에서 추정합니다. 추론 요청은 `/v1/messages?beta=true`로 게시되므로 전체 URL이 아닌 경로와 일치합니다. Agent Platform 메서드 접미사는 게시자 모델 경로에 첨부됩니다. 예: `/projects/{project}/locations/{location}/publishers/anthropic/models/{model}:streamRawPredict`.55토큰 계산 엔드포인트는 유일한 선택 사항입니다. 이들이 없을 때 Claude Code는 컨텍스트 사용을 로컬에서 추정합니다. 추론 요청은 `/v1/messages?beta=true`로 게시되므로 전체 URL이 아닌 경로와 일치합니다. Google Cloud의 Agent Platform 메서드 접미사는 게시자 모델 경로에 첨부됩니다. 예: `/projects/{project}/locations/{location}/publishers/anthropic/models/{model}:streamRawPredict`.

56 56

57게이트웨이는 또한 아무것도 손상시키지 않고 거부할 수 있는 최선의 노력 시작 트래픽을 봅니다: `HEAD /` 연결 프로브, 및 Bedrock 형식 게이트웨이에서 `GET /inference-profiles?type=SYSTEM_DEFINED` 요청.57게이트웨이는 또한 아무것도 손상시키지 않고 거부할 수 있는 최선의 노력 시작 트래픽을 봅니다: `HEAD /` 연결 프로브, 및 Amazon Bedrock 형식 게이트웨이에서 `GET /inference-profiles?type=SYSTEM_DEFINED` 요청.

58 58

59<h3 id="streaming">59<h3 id="streaming">

60 스트리밍60 스트리밍

68 68

69클라이언트가 사용하는 형식은 게이트웨이가 수신하는 것을 결정합니다. 일반적인 실패 모드는 클라이언트가 게이트웨이로 전송하는 형식과 뒤에 있는 업스트림 제공자가 수락하는 형식 간의 불일치입니다.69클라이언트가 사용하는 형식은 게이트웨이가 수신하는 것을 결정합니다. 일반적인 실패 모드는 클라이언트가 게이트웨이로 전송하는 형식과 뒤에 있는 업스트림 제공자가 수락하는 형식 간의 불일치입니다.

70 70

~~71* 클라이언트가 Bedrock 또는 Agent Platform 형식을 사용할 때, Claude Code는 해당 제공자가 수락하는 전체 기능 집합의 부분 집합만 전송합니다.~~71* 클라이언트가 Amazon Bedrock 또는 Google Cloud의 Agent Platform 형식을 사용할 때, Claude Code는 해당 제공자가 수락하는 전체 기능 집합의 부분 집합만 전송합니다.

72* 클라이언트가 Anthropic Messages 형식을 사용할 때, Claude Code는 게이트웨이가 Bedrock 또는 Agent Platform 업스트림으로 전달하더라도 전체 집합을 전송합니다.72* 클라이언트가 Anthropic Messages 형식을 사용할 때, Claude Code는 게이트웨이가 Amazon Bedrock 또는 Google Cloud의 Agent Platform 업스트림으로 전달하더라도 전체 집합을 전송합니다.

73 73

74그 차이를 연결하는 것은 게이트웨이의 작업입니다. [기능 통과](#feature-pass-through)는 그렇지 않을 때 손상되는 것을 설명합니다.74그 차이를 연결하는 것은 게이트웨이의 작업입니다. [기능 통과](#feature-pass-through)는 그렇지 않을 때 손상되는 것을 설명합니다.

75 75

82| 헤더 | 설명 |82| 헤더 | 설명 |

83| :------------------------------ | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |83| :------------------------------ | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

84| `Authorization`, `x-api-key` | 개발자의 게이트웨이 자격 증명. 설정한 [자격 증명 변수](/ko/llm-gateway-connect#set-the-credential-variable)에 따라 하나 또는 두 헤더 모두에 포함됨 |84| `Authorization`, `x-api-key` | 개발자의 게이트웨이 자격 증명. 설정한 [자격 증명 변수](/ko/llm-gateway-connect#set-the-credential-variable)에 따라 하나 또는 두 헤더 모두에 포함됨 |

85| `anthropic-version` | API 버전. 현재 `2023-06-01`. Bedrock 및 Agent Platform 형식 요청은 또한 `anthropic_version` 본문 필드를 전달하며, 그 값은 이 헤더의 값이 아닌 제공자 방언 문자열입니다. |85| `anthropic-version` | API 버전. 현재 `2023-06-01`. Amazon Bedrock 및 Google Cloud의 Agent Platform 형식 요청은 또한 `anthropic_version` 본문 필드를 전달하며, 그 값은 이 헤더의 값이 아닌 제공자 방언 문자열입니다. |

86| `anthropic-beta` | 요청에 대한 쉼표로 구분된 기능 값. 헤더를 그대로 전달합니다. 개별 값을 허용 목록에 추가하지 마십시오. Claude Code 릴리스에 따라 집합이 변경되기 때문입니다. 개발자가 claude.ai 로그인으로 인증할 때 (이는 `ANTHROPIC_BASE_URL`이 게이트웨이 자격 증명 변수 없이 설정될 때 가능함), 이 헤더는 또한 업스트림이 요구하는 OAuth 기능을 전달하며, 이를 제거하면 해당 요청이 `401`로 실패합니다. |86| `anthropic-beta` | 요청에 대한 쉼표로 구분된 기능 값. 헤더를 그대로 전달합니다. 개별 값을 허용 목록에 추가하지 마십시오. Claude Code 릴리스에 따라 집합이 변경되기 때문입니다. 개발자가 claude.ai 로그인으로 인증할 때 (이는 `ANTHROPIC_BASE_URL`이 게이트웨이 자격 증명 변수 없이 설정될 때 가능함), 이 헤더는 또한 업스트림이 요구하는 OAuth 기능을 전달하며, 이를 제거하면 해당 요청이 `401`로 실패합니다. |

88| `x-claude-code-agent-id` | 요청을 발급한 [서브에이전트](/ko/sub-agents)의 식별자. 세션 내에서 Claude Code가 생성한 에이전트의 요청에만 존재합니다. 세션 ID와 함께 사용하여 병렬 에이전트에 비용을 속성화합니다. |88| `x-claude-code-agent-id` | 요청을 발급한 [서브에이전트](/ko/sub-agents)의 식별자. 세션 내에서 Claude Code가 생성한 에이전트의 요청에만 존재합니다. 세션 ID와 함께 사용하여 병렬 에이전트에 비용을 속성화합니다. |

100 100

101Anthropic 형식 업스트림으로 전달할 때, 오늘 보는 것들을 허용 목록에 추가하기보다는 `anthropic-*` 요청 헤더 및 요청 본문 필드를 변경 없이 통과시킵니다. 관찰된 목록에 고정된 게이트웨이는 다음 기능의 헤더 또는 필드를 제거하고 이를 도입하는 릴리스에서 손상시킵니다.101Anthropic 형식 업스트림으로 전달할 때, 오늘 보는 것들을 허용 목록에 추가하기보다는 `anthropic-*` 요청 헤더 및 요청 본문 필드를 변경 없이 통과시킵니다. 관찰된 목록에 고정된 게이트웨이는 다음 기능의 헤더 또는 필드를 제거하고 이를 도입하는 릴리스에서 손상시킵니다.

102 102

103예외는 Bedrock 또는 Agent Platform과 같은 비 Anthropic 업스트림입니다. 여기서 스키마 차이를 연결하는 것은 게이트웨이의 작업입니다. [기능 통과](#feature-pass-through)를 참조하십시오.103예외는 Amazon Bedrock 또는 Google Cloud의 Agent Platform과 같은 비 Anthropic 업스트림입니다. 여기서 스키마 차이를 연결하는 것은 게이트웨이의 작업입니다. [기능 통과](#feature-pass-through)를 참조하십시오.

104 104

105<h2 id="system-prompt-attribution-block">105<h2 id="system-prompt-attribution-block">

106 시스템 프롬프트 속성 블록106 시스템 프롬프트 속성 블록

129세분화된 도구 스트리밍은 직접 연결 기본값 중 하나입니다. 요청이 사용자 정의 기본 URL을 통해 라우팅될 때마다 기본적으로 꺼져 있으며, 개발자가 [`CLAUDE_CODE_ENABLE_FINE_GRAINED_TOOL_STREAMING=1`](/ko/env-vars)을 설정할 때 게이트웨이가 이를 수신합니다.129세분화된 도구 스트리밍은 직접 연결 기본값 중 하나입니다. 요청이 사용자 정의 기본 URL을 통해 라우팅될 때마다 기본적으로 꺼져 있으며, 개발자가 [`CLAUDE_CODE_ENABLE_FINE_GRAINED_TOOL_STREAMING=1`](/ko/env-vars)을 설정할 때 게이트웨이가 이를 수신합니다.

130 130

132| :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | :----------------------------------------------------------------------------------------------------------------------------------- | :--------------------------------------------------------------------------------------------------- | :----------------------------------------------------------------------------------------------------- |132| :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | :----------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------ | :----------------------------------------------------------------------------------------------------- |

133| [적응형 추론](/ko/model-config#adjust-effort-level) | 베타 헤더 없음. Claude Code는 Claude 4.6 이상에 대해 `thinking: {"type": "adaptive"}`를 전송하고, 게이트웨이 별칭과 같이 인식하지 못하는 모델 이름을 현재 모델로 취급하여 필드를 수신합니다. | 업스트림 모델 빌드가 이를 수락하지 않을 때 `thinking` 필드 또는 `adaptive` 태그의 이름을 지정하는 `400` | 업스트림을 업그레이드합니다. Opus 4.6 및 Sonnet 4.6에서 개발자는 대신 `CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING=1`을 설정할 수 있습니다. |133| [적응형 추론](/ko/model-config#adjust-effort-level) | 베타 헤더 없음. Claude Code는 Claude 4.6 이상에 대해 `thinking: {"type": "adaptive"}`를 전송하고, 게이트웨이 별칭과 같이 인식하지 못하는 모델 이름을 현재 모델로 취급하여 필드를 수신합니다. | 업스트림 모델 빌드가 이를 수락하지 않을 때 `thinking` 필드 또는 `adaptive` 태그의 이름을 지정하는 `400` | 업스트림을 업그레이드합니다. Opus 4.6 및 Sonnet 4.6에서 개발자는 대신 `CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING=1`을 설정할 수 있습니다. |

134| [컨텍스트 관리](https://platform.claude.com/docs/en/build-with-claude/context-management) | 컨텍스트 관리 베타 헤더는 `context_management` 본문 필드와 쌍을 이룹니다. | `Extra inputs are not permitted`를 포함한 `400`. 게이트웨이가 Anthropic 형식 요청을 수락하지만 Bedrock으로 전달할 때 일반적입니다. | 둘 다 전달하거나 [`CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1`](/ko/env-vars) |134| [컨텍스트 관리](https://platform.claude.com/docs/en/build-with-claude/context-management) | 컨텍스트 관리 베타 헤더는 `context_management` 본문 필드와 쌍을 이룹니다. | `Extra inputs are not permitted`를 포함한 `400`. 게이트웨이가 Anthropic 형식 요청을 수락하지만 Amazon Bedrock으로 전달할 때 일반적입니다. | 둘 다 전달하거나 [`CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1`](/ko/env-vars) |

135| [확장 컨텍스트](https://platform.claude.com/docs/en/build-with-claude/context-windows#1m-token-context-window) 및 [인터리브된 사고](https://platform.claude.com/docs/en/build-with-claude/extended-thinking#interleaved-thinking) | 베타 헤더만, 본문 필드 없음 | 헤더가 제거될 때 조용히 사용 불가능. 업스트림은 기능 요청을 보지 못합니다. | `anthropic-beta`를 그대로 전달합니다. |135| [확장 컨텍스트](https://platform.claude.com/docs/en/build-with-claude/context-windows#1m-token-context-window) 및 [인터리브된 사고](https://platform.claude.com/docs/en/build-with-claude/extended-thinking#interleaved-thinking) | 베타 헤더만, 본문 필드 없음 | 헤더가 제거될 때 조용히 사용 불가능. 업스트림은 기능 요청을 보지 못합니다. | `anthropic-beta`를 그대로 전달합니다. |

136| 베타 [도구 필드](https://platform.claude.com/docs/en/agents-and-tools/tool-use/overview) | 도구 관련 베타 헤더는 `strict` 및 `defer_loading`과 같은 도구 스키마 필드와 쌍을 이룹니다. | 본문이 헤더 없이 통과할 때 인식되지 않는 도구 스키마 필드의 이름을 지정하는 `400` | 둘 다 전달하거나 `CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1` |136| 베타 [도구 필드](https://platform.claude.com/docs/en/agents-and-tools/tool-use/overview) | 도구 관련 베타 헤더는 `strict` 및 `defer_loading`과 같은 도구 스키마 필드와 쌍을 이룹니다. | 본문이 헤더 없이 통과할 때 인식되지 않는 도구 스키마 필드의 이름을 지정하는 `400` | 둘 다 전달하거나 `CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1` |

137| [노력](https://platform.claude.com/docs/en/build-with-claude/effort) 및 [구조화된 출력](https://platform.claude.com/docs/en/build-with-claude/structured-outputs) | `output_config` 본문 필드는 노력, 구조화된 출력 형식 및 작업 예산 설정을 전달합니다. 각각은 자체 베타 헤더와 쌍을 이룹니다. | Bedrock 및 Agent Platform 업스트림에서 `output_config`의 이름을 지정하는 `400`. 종종 `Extra inputs are not permitted` | 필드와 헤더를 함께 전달합니다. |137| [노력](https://platform.claude.com/docs/en/build-with-claude/effort) 및 [구조화된 출력](https://platform.claude.com/docs/en/build-with-claude/structured-outputs) | `output_config` 본문 필드는 노력, 구조화된 출력 형식 및 작업 예산 설정을 전달합니다. 각각은 자체 베타 헤더와 쌍을 이룹니다. | Amazon Bedrock 및 Google Cloud의 Agent Platform 업스트림에서 `output_config`의 이름을 지정하는 `400`. 종종 `Extra inputs are not permitted` | 필드와 헤더를 함께 전달합니다. |

139 139

140`ANTHROPIC_DEFAULT_*_MODEL_SUPPORTED_CAPABILITIES` [변수](/ko/model-config)는 제공자 구성에서만 모델 기능을 선언합니다: `CLAUDE_CODE_USE_BEDROCK`, `CLAUDE_CODE_USE_VERTEX`, `CLAUDE_CODE_USE_FOUNDRY`, 및 [`CLAUDE_CODE_USE_MANTLE`](/ko/amazon-bedrock#use-the-mantle-endpoint). 이들은 `ANTHROPIC_BASE_URL` 게이트웨이 뒤에서 효과가 없습니다.140`ANTHROPIC_DEFAULT_*_MODEL_SUPPORTED_CAPABILITIES` [변수](/ko/model-config)는 제공자 구성에서만 모델 기능을 선언합니다: `CLAUDE_CODE_USE_BEDROCK`, `CLAUDE_CODE_USE_VERTEX`, `CLAUDE_CODE_USE_FOUNDRY`, 및 [`CLAUDE_CODE_USE_MANTLE`](/ko/amazon-bedrock#use-the-mantle-endpoint). 이들은 `ANTHROPIC_BASE_URL` 게이트웨이 뒤에서 효과가 없습니다.

llm-gateway-rollout.md +4 −4

Details

180어느 경로를 선택하든 동일한 변수 집합이 적용됩니다. 대부분의 롤아웃은 `ANTHROPIC_BASE_URL`과 자격증명만 필요합니다. 게이트웨이 설정에서 필요한 경우 조건부 행을 포함하십시오.180어느 경로를 선택하든 동일한 변수 집합이 적용됩니다. 대부분의 롤아웃은 `ANTHROPIC_BASE_URL`과 자격증명만 필요합니다. 게이트웨이 설정에서 필요한 경우 조건부 행을 포함하십시오.

181 181

183| :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |183| :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

184| `ANTHROPIC_BASE_URL` | Claude Code의 API 요청을 `api.anthropic.com` 대신 게이트웨이로 전송합니다. | 항상 |184| `ANTHROPIC_BASE_URL` | Claude Code의 API 요청을 `api.anthropic.com` 대신 게이트웨이로 전송합니다. | 항상 |

185| `apiKeyHelper` 또는 `ANTHROPIC_AUTH_TOKEN` 또는 `ANTHROPIC_API_KEY`의 자격증명 | 게이트웨이에 대한 각 요청을 인증합니다. 도우미는 키를 가져오는 명령을 실행합니다. 변수는 각각 `Authorization: Bearer` 및 `x-api-key`로 전송되는 정적 키를 보유합니다. | 항상; 3개 중 1개 |185| `apiKeyHelper` 또는 `ANTHROPIC_AUTH_TOKEN` 또는 `ANTHROPIC_API_KEY`의 자격증명 | 게이트웨이에 대한 각 요청을 인증합니다. 도우미는 키를 가져오는 명령을 실행합니다. 변수는 각각 `Authorization: Bearer` 및 `x-api-key`로 전송되는 정적 키를 보유합니다. | 항상; 3개 중 1개 |

188| `CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS` | Claude Code가 사전 릴리스 기능 헤더 및 본문 필드를 전송하지 않도록 중지합니다. | 게이트웨이가 베타 필드를 거부하는 Bedrock 또는 Agent Platform 업스트림으로 전달하는 경우. [게이트웨이 요구사항](#gateway-requirements) 참조 |188| `CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS` | Claude Code가 사전 릴리스 기능 헤더 및 본문 필드를 전송하지 않도록 중지합니다. | 게이트웨이가 베타 필드를 거부하는 Amazon Bedrock 또는 Google Cloud의 Agent Platform 업스트림으로 전달하는 경우. [게이트웨이 요구사항](#gateway-requirements) 참조 |

189| `ANTHROPIC_MODEL` 또는 [`ANTHROPIC_DEFAULT_HAIKU_MODEL`](/ko/model-config) | Claude Code가 주 세션 및 백그라운드 트래픽에 대해 요청하는 모델 이름을 설정합니다. | 게이트웨이가 Claude Code의 기본값과 일치하지 않는 모델 이름을 라우팅하거나 [백그라운드 기능](/ko/costs#background-token-usage)을 다른 모델로 라우팅하는 경우. 게이트웨이에서 재정의 이름과 Claude Code의 기본 이름을 모두 라우팅하십시오. 일부 하위 호출은 재정의와 관계없이 기본 이름을 요청할 수 있기 때문입니다. [모델 구성](/ko/model-config)은 세션의 각 부분이 사용하는 모델을 다룹니다. |189| `ANTHROPIC_MODEL` 또는 [`ANTHROPIC_DEFAULT_HAIKU_MODEL`](/ko/model-config) | Claude Code가 주 세션 및 백그라운드 트래픽에 대해 요청하는 모델 이름을 설정합니다. | 게이트웨이가 Claude Code의 기본값과 일치하지 않는 모델 이름을 라우팅하거나 [백그라운드 기능](/ko/costs#background-token-usage)을 다른 모델로 라우팅하는 경우. 게이트웨이에서 재정의 이름과 Claude Code의 기본 이름을 모두 라우팅하십시오. 일부 하위 호출은 재정의와 관계없이 기본 이름을 요청할 수 있기 때문입니다. [모델 구성](/ko/model-config)은 세션의 각 부분이 사용하는 모델을 다룹니다. |

190| `ANTHROPIC_BEDROCK_BASE_URL`, `ANTHROPIC_VERTEX_BASE_URL`, `ANTHROPIC_FOUNDRY_BASE_URL` 또는 `ANTHROPIC_AWS_BASE_URL`과 [해당 공급자의 변수](/ko/llm-gateway-connect#route-to-a-cloud-provider-through-a-gateway) | Claude Code를 게이트웨이를 통해 공급자별 기본 URL로 가리킵니다. Bedrock 및 Agent Platform은 해당 공급자의 기본 요청 형식으로도 전환합니다. | 게이트웨이가 Bedrock, Agent Platform, Foundry 또는 AWS의 Claude Platform을 앞에 두는 경우. [API 형식](/ko/llm-gateway-protocol#api-formats) 참조 |190| `ANTHROPIC_BEDROCK_BASE_URL`, `ANTHROPIC_VERTEX_BASE_URL`, `ANTHROPIC_FOUNDRY_BASE_URL` 또는 `ANTHROPIC_AWS_BASE_URL`과 [해당 공급자의 변수](/ko/llm-gateway-connect#route-to-a-cloud-provider-through-a-gateway) | Claude Code를 게이트웨이를 통해 공급자별 기본 URL로 가리킵니다. Amazon Bedrock 및 Google Cloud의 Agent Platform은 해당 공급자의 기본 요청 형식으로도 전환합니다. | 게이트웨이가 Amazon Bedrock, Google Cloud의 Agent Platform, Microsoft Foundry 또는 AWS의 Claude Platform을 앞에 두는 경우. [API 형식](/ko/llm-gateway-protocol#api-formats) 참조 |

191 191

192<h4 id="distribute-through-managed-settings">192<h4 id="distribute-through-managed-settings">

193 관리되는 설정을 통해 배포193 관리되는 설정을 통해 배포

214 214

215일부 환경에는 별도의 배포가 필요합니다.215일부 환경에는 별도의 배포가 필요합니다.

216 216

217* 데스크톱 앱은 MDM 배포 타사 추론 구성에서만 게이트웨이 라우팅을 읽습니다. 데스크톱 세션도 게이트웨이를 통해 라우팅되도록 관리되는 설정과 함께 해당 파일을 배포하십시오. [데스크톱 타사 구성 문서](https://claude.com/docs/cowork/3p/configuration) 및 [데스크톱 게이트웨이 문서](https://claude.com/docs/cowork/3p/gateway)를 참조하십시오.217* 데스크톱 앱은 MDM 배포 타사 추론 구성에서만 게이트웨이 라우팅을 읽습니다. 데스크톱 세션도 게이트웨이를 통해 라우팅되도록 관리되는 설정과 함께 해당 파일을 배포하십시오. [데스크톱 타사 구성 문서](https://claude.com/docs/third-party/claude-desktop/configuration) 및 [데스크톱 게이트웨이 문서](https://claude.com/docs/third-party/claude-desktop/gateway)를 참조하십시오.

218* CI 러너는 [러너의 환경](/ko/llm-gateway-connect#configure-each-surface)에서 `ANTHROPIC_BASE_URL` 및 자격증명을 설정해야 합니다.218* CI 러너는 [러너의 환경](/ko/llm-gateway-connect#configure-each-surface)에서 `ANTHROPIC_BASE_URL` 및 자격증명을 설정해야 합니다.

219* 관리되는 Windows 머신의 WSL은 [`wslInheritsWindowsSettings`](/ko/settings#available-settings)가 `true`일 때만 Windows 관리 설정을 읽습니다.219* 관리되는 Windows 머신의 WSL은 [`wslInheritsWindowsSettings`](/ko/settings#available-settings)가 `true`일 때만 Windows 관리 설정을 읽습니다.

220 220

mcp.md +29 −14

Details

85 85

86`.mcp.json`, `~/.claude.json` 또는 `claude mcp add-json`을 통해 JSON으로 MCP 서버를 구성할 때, `type` 필드는 `http`의 별칭으로 `streamable-http`를 허용합니다. MCP 사양은 이 전송에 대해 `streamable-http`라는 이름을 사용하므로 서버 설명서에서 복사한 구성이 수정 없이 작동합니다.86`.mcp.json`, `~/.claude.json` 또는 `claude mcp add-json`을 통해 JSON으로 MCP 서버를 구성할 때, `type` 필드는 `http`의 별칭으로 `streamable-http`를 허용합니다. MCP 사양은 이 전송에 대해 `streamable-http`라는 이름을 사용하므로 서버 설명서에서 복사한 구성이 수정 없이 작동합니다.

87 87

88`url`은 있지만 `type`이 없는 JSON 항목은 구성 오류입니다. Claude Code는 `type`이 없는 항목을 stdio 서버로 읽기 때문입니다. Claude Code는 해당 서버를 건너뛰고 `MCP server "<name>" has a "url" but no "type"; add "type": "http" (or "sse" / "ws") to this entry`를 보고합니다. v2.1.202 이전에는 Claude Code가 이 잘못된 구성을 `command: expected string, received undefined`로 보고했습니다.

88<h3 id="option-2-add-a-remote-sse-server">90<h3 id="option-2-add-a-remote-sse-server">

89 옵션 2: 원격 SSE 서버 추가91 옵션 2: 원격 SSE 서버 추가

90</h3>92</h3>

113 115

114Claude Code는 생성된 서버의 환경에서 `CLAUDE_PROJECT_DIR`을 프로젝트 루트로 설정하므로 서버는 작업 디렉터리에 의존하지 않고 프로젝트 상대 경로를 확인할 수 있습니다. 이는 hooks가 `CLAUDE_PROJECT_DIR` 변수에서 받는 것과 동일한 디렉터리입니다. 서버 프로세스 내에서 읽으세요. 예를 들어 Node에서는 `process.env.CLAUDE_PROJECT_DIR` 또는 Python에서는 `os.environ["CLAUDE_PROJECT_DIR"]`입니다.116Claude Code는 생성된 서버의 환경에서 `CLAUDE_PROJECT_DIR`을 프로젝트 루트로 설정하므로 서버는 작업 디렉터리에 의존하지 않고 프로젝트 상대 경로를 확인할 수 있습니다. 이는 hooks가 `CLAUDE_PROJECT_DIR` 변수에서 받는 것과 동일한 디렉터리입니다. 서버 프로세스 내에서 읽으세요. 예를 들어 Node에서는 `process.env.CLAUDE_PROJECT_DIR` 또는 Python에서는 `os.environ["CLAUDE_PROJECT_DIR"]`입니다.

115 117

116서버는 또한 MCP `roots/list` 요청을 호출할 수 있으며, 이는 Claude Code가 시작된 디렉터리를 반환합니다.118`CLAUDE_PROJECT_DIR`은 안정적인 프로젝트 루트이며 세션 중에 작업 디렉터리를 추가하거나 제거할 때 변경되지 않습니다. 자신의 파일 시스템 액세스를 허용된 디렉터리 집합으로 제한하는 서버는 대신 MCP `roots/list` 요청을 구현해야 합니다. Claude Code는 `roots/list`에 세션의 시작 디렉터리와 `--add-dir`, `/add-dir` 또는 `additionalDirectories` 설정으로 부여한 모든 [추가 작업 디렉터리](/ko/permissions#working-directories)로 응답합니다. Claude Code는 해당 집합이 변경될 때 `notifications/roots/list_changed`를 보냅니다. v2.1.203 이전에는 `roots/list`가 시작 디렉터리만 반환했고 Claude Code는 `notifications/roots/list_changed`를 보내지 않았습니다.

117 119

118이 변수는 Claude Code 자체의 환경이 아닌 서버의 환경에 설정되므로 프로젝트 또는 사용자 범위의 `.mcp.json` `command` 또는 `args`에서 `${VAR}` 확장을 통해 참조하려면 `${CLAUDE_PROJECT_DIR:-.}`와 같은 기본값이 필요합니다. 플러그인 제공 MCP 구성은 `${CLAUDE_PROJECT_DIR}`을 직접 대체하며 기본값이 필요하지 않습니다.120이 변수는 Claude Code 자체의 환경이 아닌 서버의 환경에 설정되므로 프로젝트 또는 사용자 범위의 `.mcp.json` `command` 또는 `args`에서 `${VAR}` 확장을 통해 참조하려면 `${CLAUDE_PROJECT_DIR:-.}`와 같은 기본값이 필요합니다. 플러그인 제공 MCP 구성은 `${CLAUDE_PROJECT_DIR}`을 직접 대체하며 기본값이 필요하지 않습니다.

119 121

191 193

192`/mcp` 패널은 각 연결된 서버 옆에 도구 개수를 표시하고 도구 기능을 광고하지만 도구를 노출하지 않는 서버에 플래그를 지정합니다.194`/mcp` 패널은 각 연결된 서버 옆에 도구 개수를 표시하고 도구 기능을 광고하지만 도구를 노출하지 않는 서버에 플래그를 지정합니다.

193 195

194요청이 백그라운드에서 아직 연결 중인 서버의 도구가 필요한 경우 Claude는 해당 서버가 연결될 때까지 기다립니다. [도구 검색](#scale-with-mcp-tool-search)이 활성화되어 있으면 (기본값), 대기는 `ToolSearch` 호출 내에서 발생합니다. Vertex AI, 사용자 정의 `ANTHROPIC_BASE_URL` 또는 `ENABLE_TOOL_SEARCH=false`와 같이 도구 검색이 없는 구성에서는 Claude가 대신 `WaitForMcpServers` 도구를 사용합니다.196요청이 백그라운드에서 아직 연결 중인 서버의 도구가 필요한 경우 Claude는 해당 서버가 연결될 때까지 기다립니다. [도구 검색](#scale-with-mcp-tool-search)이 활성화되어 있으면 (기본값), 대기는 `ToolSearch` 호출 내에서 발생합니다. Google Cloud의 Agent Platform, 사용자 정의 `ANTHROPIC_BASE_URL` 또는 `ENABLE_TOOL_SEARCH=false`와 같이 도구 검색이 없는 구성에서는 Claude가 대신 `WaitForMcpServers` 도구를 사용합니다.

197

198일부 서버 이름은 Claude Code의 기본 제공 서버용으로 예약되어 있습니다: `workspace`, `claude-in-chrome`, `computer-use`, `Claude Preview`, 및 `Claude Browser`. 구성에서 예약된 이름의 서버를 정의하면 Claude Code는 로드 시 이를 건너뛰고 이름을 바꾸도록 요청하는 경고를 표시합니다. `claude mcp add`는 예약된 이름을 오류로 거부합니다.

195 199

196서버 이름 `workspace`는 내부 사용을 위해 예약되어 있습니다. 구성에서 해당 이름의 서버를 정의하면 Claude Code는 로드 시 이를 건너뛰고 이름을 바꾸도록 요청하는 경고를 표시합니다.200`Claude Preview` 및 `Claude Browser`는 모두 [Claude Code 데스크톱 앱의 미리보기 창](/ko/desktop#preview-your-app)이 사용하는 기본 제공 서버의 이름입니다. v2.1.205 이전에는 `Claude Browser`가 예약되지 않았으므로 사용자 구성 서버가 해당 이름으로 등록될 수 있었습니다.

197 201

198<h3 id="dynamic-tool-updates">202<h3 id="dynamic-tool-updates">

199 동적 도구 업데이트203 동적 도구 업데이트

209 213

210HTTP 또는 SSE 서버가 시작 시 초기 연결에 실패할 때도 동일한 백오프가 적용됩니다. v2.1.121부터 Claude Code는 5xx 응답, 연결 거부 또는 시간 초과와 같은 일시적 오류에 대해 초기 연결을 최대 3번 재시도한 후, 여전히 연결할 수 없으면 서버를 실패로 표시합니다. 인증 및 찾을 수 없음 오류는 해결하기 위해 구성 변경이 필요하므로 재시도되지 않습니다.214HTTP 또는 SSE 서버가 시작 시 초기 연결에 실패할 때도 동일한 백오프가 적용됩니다. v2.1.121부터 Claude Code는 5xx 응답, 연결 거부 또는 시간 초과와 같은 일시적 오류에 대해 초기 연결을 최대 3번 재시도한 후, 여전히 연결할 수 없으면 서버를 실패로 표시합니다. 인증 및 찾을 수 없음 오류는 해결하기 위해 구성 변경이 필요하므로 재시도되지 않습니다.

211 215

216구성된 서버가 연결에 실패하면 Claude Code는 Claude에 어느 서버가 실패했는지와 연결 오류를 알립니다. 이는 일치하는 도구를 찾지 못한 `ToolSearch` 결과를 포함합니다. 따라서 Claude는 응답에서 연결 실패를 보고합니다. [도구 검색](#scale-with-mcp-tool-search)이 필요합니다. 이는 기본적으로 활성화됩니다. 사용자 정의 `ANTHROPIC_BASE_URL`, `ENABLE_TOOL_SEARCH=false` 또는 Haiku 모델과 같이 도구 검색이 없는 구성에서, 그리고 Amazon Bedrock, Google Cloud의 Agent Platform 및 Microsoft Foundry에서는 Claude Code가 실패한 서버 연결을 Claude에 보고하지 않습니다. v2.1.205 이전에는 Claude Code가 연결 오류를 Claude에 전달하지 않았으며, Claude는 실패한 서버의 도구가 구성되지 않은 것처럼 응답할 수 있었습니다.

217

212v2.1.191부터 성공적인 연결 후 실행되는 기능 검색 요청(예: `tools/list`, `prompts/list`, `resources/list`)도 일시적 네트워크 및 서버 오류를 짧은 백오프로 최대 3번 재시도합니다. 인증 오류, 4xx 응답 및 요청 시간 초과는 재시도되지 않습니다.218v2.1.191부터 성공적인 연결 후 실행되는 기능 검색 요청(예: `tools/list`, `prompts/list`, `resources/list`)도 일시적 네트워크 및 서버 오류를 짧은 백오프로 최대 3번 재시도합니다. 인증 오류, 4xx 응답 및 요청 시간 초과는 재시도되지 않습니다.

213 219

214<h3 id="push-messages-with-channels">220<h3 id="push-messages-with-channels">

220<Tip>226<Tip>

221 팁:227 팁:

222 228

223 * `--scope` 플래그를 사용하여 구성이 저장되는 위치를 지정하세요:229 * `-s` 또는 `--scope` 플래그를 사용하여 구성이 저장되는 위치를 지정하세요:

224 * `local` (기본값): 현재 프로젝트에서만 사용자에게만 사용 가능. 이전 버전에서는 이 범위를 `project`라고 불렀습니다230 * `local` (기본값): 현재 프로젝트에서만 사용자에게만 사용 가능. 이전 버전에서는 이 범위를 `project`라고 불렀습니다

225 * `project`: `.mcp.json` 파일을 통해 프로젝트의 모든 사람과 공유231 * `project`: `.mcp.json` 파일을 통해 프로젝트의 모든 사람과 공유

226 * `user`: 모든 프로젝트에서 사용자에게 사용 가능. 이전 버전에서는 이 범위를 `global`이라고 불렀습니다232 * `user`: 모든 프로젝트에서 사용자에게 사용 가능. 이전 버전에서는 이 범위를 `global`이라고 불렀습니다

227 * `--env` 플래그로 환경 변수를 설정하세요 (예: `--env KEY=value`)233 * `-e` 또는 `--env` 플래그로 환경 변수를 설정하세요 (예: `-e KEY=value`)

234 * `--transport` 및 `--header` 플래그는 `-t` 및 `-H` 단축형도 허용합니다

228 * `MCP_TIMEOUT` 환경 변수를 사용하여 MCP 서버 시작 시간 초과를 구성하세요 (예: `MCP_TIMEOUT=10000 claude`는 10초 시간 초과를 설정)235 * `MCP_TIMEOUT` 환경 변수를 사용하여 MCP 서버 시작 시간 초과를 구성하세요 (예: `MCP_TIMEOUT=10000 claude`는 10초 시간 초과를 설정)

229 * 서버당 도구 실행 시간 초과를 설정하려면 해당 서버의 `.mcp.json` 항목에 밀리초 단위의 `timeout` 필드를 추가하세요. 예를 들어 10분의 경우 `"timeout": 600000`입니다. 이는 해당 서버에만 `MCP_TOOL_TIMEOUT` 환경 변수를 재정의합니다236 * 서버당 도구 실행 시간 초과를 설정하려면 해당 서버의 `.mcp.json` 항목에 밀리초 단위의 `timeout` 필드를 추가하세요. 예를 들어 10분의 경우 `"timeout": 600000`입니다. 이는 해당 서버에만 `MCP_TOOL_TIMEOUT` 환경 변수를 재정의합니다

230 * Claude Code는 MCP 도구 출력이 10,000 토큰을 초과할 때 경고를 표시합니다. 이 제한을 늘리려면 `MAX_MCP_OUTPUT_TOKENS` 환경 변수를 설정하세요 (예: `MAX_MCP_OUTPUT_TOKENS=50000`)237 * Claude Code는 MCP 도구 출력이 10,000 토큰을 초과할 때 경고를 표시합니다. 이 제한을 늘리려면 `MAX_MCP_OUTPUT_TOKENS` 환경 변수를 설정하세요 (예: `MAX_MCP_OUTPUT_TOKENS=50000`)

233 240

234서버당 `timeout`은 도구 호출당 하드 월클록 제한이며, 서버의 진행 알림은 이를 연장하지 않습니다. 1000 미만의 값은 무시되고 `MCP_TOOL_TIMEOUT`으로 넘어가거나, 해당 변수가 설정되지 않은 경우 약 28시간의 기본값으로 넘어갑니다. {/* min-version: 2.1.162 */}v2.1.162 이전에는 1000 미만의 값이 1초로 내림되었습니다.241서버당 `timeout`은 도구 호출당 하드 월클록 제한이며, 서버의 진행 알림은 이를 연장하지 않습니다. 1000 미만의 값은 무시되고 `MCP_TOOL_TIMEOUT`으로 넘어가거나, 해당 변수가 설정되지 않은 경우 약 28시간의 기본값으로 넘어갑니다. {/* min-version: 2.1.162 */}v2.1.162 이전에는 1000 미만의 값이 1초로 내림되었습니다.

235 242

243서버당 최소 1000의 `timeout`은 또한 아래에 설명된 유휴 시간 초과의 하한으로 작동합니다: Claude Code는 서버당 `timeout`보다 더 빨리 유휴 상태로 인해 해당 서버의 도구 호출을 중단하지 않습니다. Claude Code v2.1.203 이상이 필요합니다.

244

236HTTP 및 SSE 서버의 경우, 요청당 fetch 첫 바이트 예산은 60초 최소값을 가집니다.245HTTP 및 SSE 서버의 경우, 요청당 fetch 첫 바이트 예산은 60초 최소값을 가집니다.

237 246

238v2.1.187부터 원격 HTTP, SSE, WebSocket 또는 [claude.ai 커넥터](#use-mcp-servers-from-claude-ai) 서버에 대한 도구 호출이 5분 동안 응답 및 진행 알림을 보내지 않으면 월클록 제한을 기다리는 대신 오류로 중단됩니다. [`CLAUDE_CODE_MCP_TOOL_IDLE_TIMEOUT`](/ko/env-vars) 환경 변수를 밀리초 단위로 설정하여 유휴 윈도우를 변경하거나, `0`으로 설정하여 확인을 비활성화하세요. Stdio 서버는 로컬 프로세스이며 유휴 시간 초과의 대상이 아닙니다.247MCP 서버에 대한 도구 호출이 유휴 윈도우 동안 응답 및 진행 알림을 보내지 않으면 월클록 제한을 기다리는 대신 오류로 중단됩니다. 유휴 시간 초과에는 Claude Code v2.1.187 이상이 필요합니다. {/* min-version: 2.1.203 */}IDE 서버 및 SDK 인프로세스 서버를 제외한 모든 서버 유형에 적용됩니다. 유휴 윈도우는 HTTP, SSE, WebSocket 및 [claude.ai 커넥터](#use-mcp-servers-from-claude-ai) 서버의 경우 기본값 5분, stdio 서버의 경우 30분입니다. v2.1.203 이전에는 stdio 서버가 유휴 시간 초과에서 제외되었습니다.

248

249[`CLAUDE_CODE_MCP_TOOL_IDLE_TIMEOUT`](/ko/env-vars) 환경 변수를 밀리초 단위로 설정하여 유휴 윈도우를 변경하거나, `0`으로 설정하여 확인을 비활성화하세요.

239 250

240<h3 id="plugin-provided-mcp-servers">251<h3 id="plugin-provided-mcp-servers">

241 플러그인 제공 MCP 서버252 플러그인 제공 MCP 서버

306mcp__plugin_my-plugin_database-tools__query317mcp__plugin_my-plugin_database-tools__query

307```318```

308 319

309[권한 규칙](/ko/permissions)에서 도구를 참조할 때, 스킬의 `allowed-tools` 목록에서, 또는 [서브에이전트의 `tools` 필드](/ko/sub-agents#available-tools)에서 이 전체 이름을 사용하세요.320[권한 규칙](/ko/permissions)에서 도구를 참조할 때, 스킬의 `allowed-tools` 목록에서, [서브에이전트의 `tools` 필드](/ko/sub-agents#available-tools)에서, 또는 [hook matcher](/ko/hooks#match-mcp-tools)에서 이 전체 이름을 사용하세요. `mcp__database-tools__.*`와 같은 베어 서버 키에 대해 작성된 hook matcher는 플러그인 번들 서버에 대해 절대 실행되지 않습니다.

321

322서버 자체는 `plugin:<plugin-name>:<server-name>` (예: `plugin:my-plugin:database-tools`)과 같은 범위 지정 이름으로 등록됩니다. 구성된 서버 이름이 예상되는 위치(예: [`mcp_tool` hook의 `server` 필드](/ko/hooks#mcp-tool-hook-fields))에서 해당 이름을 사용하세요.

310 323

311**플러그인 MCP 서버의 이점**:324**플러그인 MCP 서버의 이점**:

312 325

860 </Step>873 </Step>

861</Steps>874</Steps>

862 875

876`claude mcp` 명령을 통해 추가된 서버 이름은 문자, 숫자, 하이픈 및 언더스코어만 포함할 수 있습니다. Claude Desktop은 해당 제한을 적용하지 않으므로 공백과 같은 다른 문자를 포함하는 이름의 Claude Desktop 서버는 가져올 수 없습니다. 가져오기는 거부된 각 이름을 보고하며 선택한 다른 서버는 계속 가져옵니다. v2.1.205 이전에는 첫 번째 잘못된 이름이 가져오기를 중지했으며 선택한 서버 중 어느 것도 추가되지 않았습니다.

877

863<Tip>878<Tip>

864 팁:879 팁:

865 880

866 * 이 기능은 macOS 및 Windows Subsystem for Linux (WSL)에서만 작동합니다881 * 이 기능은 macOS 및 Windows Subsystem for Linux (WSL)에서만 작동합니다

867 * 이러한 플랫폼의 표준 위치에서 Claude Desktop 구성 파일을 읽습니다882 * 이러한 플랫폼의 표준 위치에서 Claude Desktop 구성 파일을 읽습니다

868 * `--scope user` 플래그를 사용하여 사용자 구성에 서버를 추가합니다883 * `--scope user` 플래그를 사용하여 사용자 구성에 서버를 추가합니다

869 * 가져온 서버는 Claude Desktop과 동일한 이름을 갖습니다884 * 가져온 서버는 이름에 문자, 숫자, 하이픈 및 언더스코어만 포함될 때 Claude Desktop과 동일한 이름을 유지합니다. Claude Code는 다른 문자를 포함하는 이름의 서버를 보고하고 건너뜁니다

870 * 동일한 이름의 서버가 이미 존재하면 숫자 접미사가 붙습니다 (예: `server_1`)885 * 동일한 이름의 서버가 이미 존재하면 숫자 접미사가 붙습니다 (예: `server_1`)

871</Tip>886</Tip>

872 887

898 913

899v2.1.161부터 이전에 로그인한 적이 없는 커넥터는 claude.ai 섹션 끝의 `Show unused connectors` 행 뒤에 축소되므로 조직에서 프로비저닝한 목록이 패널을 채우지 않습니다. 행을 선택하여 확장합니다. 이전에 로그인한 커넥터는 현재 재인증이 필요한 경우에도 계속 표시됩니다.914v2.1.161부터 이전에 로그인한 적이 없는 커넥터는 claude.ai 섹션 끝의 `Show unused connectors` 행 뒤에 축소되므로 조직에서 프로비저닝한 목록이 패널을 채우지 않습니다. 행을 선택하여 확장합니다. 이전에 로그인한 커넥터는 현재 재인증이 필요한 경우에도 계속 표시됩니다.

900 915

901Claude.ai 커넥터는 활성 [인증 방법](/ko/authentication#authentication-precedence)이 Claude.ai 구독인 경우에만 가져옵니다. `ANTHROPIC_API_KEY`, `ANTHROPIC_AUTH_TOKEN`, `apiKeyHelper` 또는 Bedrock이나 Vertex와 같은 타사 공급자가 활성화되어 있으면 로드되지 않습니다. 이전에 `/login`을 실행했더라도 마찬가지입니다. `/mcp`에 추가한 커넥터가 나열되지 않으면 `/status`를 실행하여 활성화된 인증 방법을 확인하고, 해당 환경 변수를 설정 해제하거나 `apiKeyHelper` 설정을 제거한 후 `/login`을 실행하여 Claude.ai 계정을 선택합니다.916Claude.ai 커넥터는 활성 [인증 방법](/ko/authentication#authentication-precedence)이 Claude.ai 구독인 경우에만 가져옵니다. `ANTHROPIC_API_KEY`, `ANTHROPIC_AUTH_TOKEN`, `apiKeyHelper` 또는 Amazon Bedrock이나 Google Cloud의 Agent Platform과 같은 타사 공급자가 활성화되어 있으면 로드되지 않습니다. 이전에 `/login`을 실행했더라도 마찬가지입니다. `/mcp`에 추가한 커넥터가 나열되지 않으면 `/status`를 실행하여 활성화된 인증 방법을 확인하고, 해당 환경 변수를 설정 해제하거나 `apiKeyHelper` 설정을 제거한 후 `/login`을 실행하여 Claude.ai 계정을 선택합니다.

902 917

903Claude Code에서 추가한 서버는 동일한 URL을 가리키는 claude.ai 커넥터보다 [우선순위](#scope-hierarchy-and-precedence)를 갖습니다. 이 경우 `/mcp`는 커넥터를 숨김으로 표시하고 커넥터를 사용하려는 경우 중복을 제거하는 방법을 표시합니다.918Claude Code에서 추가한 서버는 동일한 URL을 가리키는 claude.ai 커넥터보다 [우선순위](#scope-hierarchy-and-precedence)를 갖습니다. 이 경우 `/mcp`는 커넥터를 숨김으로 표시하고 커넥터를 사용하려는 경우 중복을 제거하는 방법을 표시합니다.

904 919

1174 Tool Search 구성1189 Tool Search 구성

1175</h3>1190</h3>

1176 1191

1177Tool Search는 기본적으로 활성화됩니다: MCP 도구는 연기되고 필요에 따라 검색됩니다. Claude Code는 Vertex AI에서 기본적으로 비활성화합니다. `ANTHROPIC_BASE_URL`이 비 자사 호스트를 가리킬 때도 비활성화됩니다(대부분의 프록시가 `tool_reference` 블록을 전달하지 않기 때문). 폴백을 재정의하려면 `ENABLE_TOOL_SEARCH`를 명시적으로 설정합니다.1192Tool Search는 기본적으로 활성화됩니다: MCP 도구는 연기되고 필요에 따라 검색됩니다. Claude Code는 Google Cloud의 Agent Platform에서 기본적으로 비활성화합니다. `ANTHROPIC_BASE_URL`이 비 자사 호스트를 가리킬 때도 비활성화됩니다(대부분의 프록시가 `tool_reference` 블록을 전달하지 않기 때문). 폴백을 재정의하려면 `ENABLE_TOOL_SEARCH`를 명시적으로 설정합니다.

1178 1193

1179Tool Search는 `tool_reference` 블록을 지원하는 모델이 필요합니다. Haiku 모델은 이를 지원하지 않습니다. Vertex AI에서는 Claude Sonnet 4.5 이상 및 Claude Opus 4.5 이상에서 Tool Search가 지원됩니다.1194Tool Search는 `tool_reference` 블록을 지원하는 모델이 필요합니다. Haiku 모델은 이를 지원하지 않습니다. Google Cloud의 Agent Platform에서는 Claude Sonnet 4.5 이상 및 Claude Opus 4.5 이상에서 Tool Search가 지원됩니다.

1180 1195

1181`ENABLE_TOOL_SEARCH` 환경 변수로 Tool Search 동작을 제어합니다:1196`ENABLE_TOOL_SEARCH` 환경 변수로 Tool Search 동작을 제어합니다:

1182 1197

1183| 값 | 동작 |1198| 값 | 동작 |

1184| :-------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------ |1199| :-------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

1186| `true` | 모든 MCP 도구 연기. Claude Code는 Vertex AI 및 프록시를 통해서도 베타 헤더를 전송합니다. Vertex AI의 Sonnet 4.5 또는 Opus 4.5보다 이전 모델에서 요청이 실패하거나 `tool_reference` 블록을 지원하지 않는 프록시에서 실패합니다 |1201| `true` | 모든 MCP 도구 연기. Claude Code는 Google Cloud의 Agent Platform 및 프록시를 통해서도 베타 헤더를 전송합니다. Google Cloud의 Agent Platform의 Sonnet 4.5 또는 Opus 4.5보다 이전 모델에서 요청이 실패하거나 `tool_reference` 블록을 지원하지 않는 프록시에서 실패합니다 |

mcp-quickstart.md +1 −1

Details

315 Claude Code가 현재 디렉토리에 대한 서버를 찾지 못했습니다. 가장 일반적인 원인:315 Claude Code가 현재 디렉토리에 대한 서버를 찾지 못했습니다. 가장 일반적인 원인:

316 316

317 * 다른 프로젝트에서 `claude mcp add`를 실행했습니다. 로컬 범위 서버는 추가한 프로젝트에 연결됩니다: 저장소 루트 또는 git 저장소에 없는 경우 정확한 디렉토리입니다. 현재 있는 프로젝트에서 서버를 다시 추가하거나 프로젝트에 연결되지 않도록 `--scope user`로 추가합니다.317 * 다른 프로젝트에서 `claude mcp add`를 실행했습니다. 로컬 범위 서버는 추가한 프로젝트에 연결됩니다: 저장소 루트 또는 git 저장소에 없는 경우 정확한 디렉토리입니다. 현재 있는 프로젝트에서 서버를 다시 추가하거나 프로젝트에 연결되지 않도록 `--scope user`로 추가합니다.

318 * 잘못된 경로에서 구성 파일을 편집했습니다. 올바른 파일은 `~/.claude.json` 및 `<project>/.mcp.json`입니다. Claude Code는 `~/.claude/config/mcp.json`, `~/.claude/mcp.json` 또는 `%APPDATA%\Claude\mcp.json`과 같은 경로를 읽지 않습니다.318 * 잘못된 경로에서 구성 파일을 편집했습니다. 올바른 파일은 `~/.claude.json` 및 `<project>/.mcp.json`입니다. Claude Code는 `~/.claude/.mcp.json`, `~/.claude/config/mcp.json`, `~/.claude/mcp.json` 또는 `%APPDATA%\Claude\mcp.json`과 같은 경로를 읽지 않습니다. 사용자 범위 서버의 경우 `claude mcp add --scope user`를 실행하여 `~/.claude.json`의 `mcpServers` 키에 쓰고, 프로젝트 범위 서버의 경우 프로젝트 루트의 `.mcp.json`을 편집합니다.

319 </Accordion>319 </Accordion>

320 320

321 <Accordion title="Status shows Failed to connect or Connection error">321 <Accordion title="Status shows Failed to connect or Connection error">

microsoft-foundry.md +18 −6

Details

113 2) Azure 자격 증명 구성113 2) Azure 자격 증명 구성

114</h3>114</h3>

115 115

116Claude Code는 Microsoft Foundry에 대해 두 가지 인증 방법을 지원합니다. 보안 요구 사항에 가장 적합한 방법을 선택하세요.116Claude Code는 Microsoft Foundry에 대해 세 가지 인증 방법을 지원합니다. 보안 요구 사항에 가장 적합한 방법을 선택하세요.

117 117

118**옵션 A: API 키 인증**118**옵션 A: API 키 인증**

119 119

128 128

129**옵션 B: Microsoft Entra ID 인증**129**옵션 B: Microsoft Entra ID 인증**

130 130

131`ANTHROPIC_FOUNDRY_API_KEY`가 설정되지 않으면 Claude Code는 자동으로 Azure SDK [기본 자격 증명 체인](https://learn.microsoft.com/en-us/azure/developer/javascript/sdk/authentication/credential-chains#defaultazurecredential-overview)을 사용합니다.131`ANTHROPIC_FOUNDRY_API_KEY`와 `ANTHROPIC_FOUNDRY_AUTH_TOKEN`이 모두 설정되지 않으면 Claude Code는 자동으로 Azure SDK [기본 자격 증명 체인](https://learn.microsoft.com/en-us/azure/developer/javascript/sdk/authentication/credential-chains#defaultazurecredential-overview)을 사용합니다.

132이는 로컬 및 원격 워크로드를 인증하기 위한 다양한 방법을 지원합니다.132이는 로컬 및 원격 워크로드를 인증하기 위한 다양한 방법을 지원합니다.

133 133

134로컬 환경에서는 일반적으로 Azure CLI를 사용할 수 있습니다:134로컬 환경에서는 일반적으로 Azure CLI를 사용할 수 있습니다:

137az login137az login

138```138```

139 139

140**옵션 C: Bearer 토큰 인증**

141

142{/* min-version: 2.1.203 */}Claude Code는 모든 요청에서 `ANTHROPIC_FOUNDRY_AUTH_TOKEN`의 값을 `Authorization: Bearer` 헤더로 전송합니다. 호스트 애플리케이션이나 로그인 스크립트와 같은 다른 프로세스가 이미 액세스 토큰을 얻은 경우 이 옵션을 사용합니다. Claude Code v2.1.203 이상이 필요합니다.

143

144변수를 Microsoft Entra ID가 리소스에 대해 발급한 bearer 토큰으로 설정합니다:

145

146```bash theme={null}

147export ANTHROPIC_FOUNDRY_AUTH_TOKEN=your-entra-access-token

148```

149

150`ANTHROPIC_FOUNDRY_AUTH_TOKEN`은 `ANTHROPIC_FOUNDRY_API_KEY`보다 우선하며 기본 자격 증명 체인보다 우선합니다.

151

140<Note>152<Note>

141 Microsoft Foundry를 사용할 때 `/logout` 명령은 Azure 자격 증명을 통해 인증이 처리되므로 사용할 수 없습니다.153 Microsoft Foundry를 사용할 때 `/logout` 명령은 Azure 자격 증명을 통해 인증이 처리되므로 사용할 수 없습니다.

142</Note>154</Note>

162</h3>174</h3>

163 175

164<Warning>176<Warning>

165 모든 배포에 대해 특정 모델 버전을 고정합니다. 고정하지 않으면 `sonnet` 및 `opus`와 같은 모델 별칭이 Claude Code의 Foundry용 기본 제공 기본값으로 확인되며, 이는 최신 릴리스보다 뒤떨어질 수 있고 계정에서 아직 사용할 수 없을 수 있습니다. Foundry는 시작 모델 확인이 없으므로 기본값을 사용할 수 없을 때 요청이 실패합니다. Azure 배포를 만들 때 "최신으로 자동 업데이트" 대신 특정 모델 버전을 선택합니다.177 모든 배포에 대해 특정 모델 버전을 고정합니다. 고정하지 않으면 `sonnet` 및 `opus`와 같은 모델 별칭이 Claude Code의 Microsoft Foundry용 기본 제공 기본값으로 확인되며, 이는 최신 릴리스보다 뒤떨어질 수 있고 계정에서 아직 사용할 수 없을 수 있습니다. Microsoft Foundry는 시작 모델 확인이 없으므로 기본값을 사용할 수 없을 때 요청이 실패합니다. Azure 배포를 만들 때 "최신으로 자동 업데이트" 대신 특정 모델 버전을 선택합니다.

166</Warning>178</Warning>

167 179

168모델 변수를 1단계에서 만든 배포 이름과 일치하도록 설정합니다.180모델 변수를 1단계에서 만든 배포 이름과 일치하도록 설정합니다.

169 181

170`ANTHROPIC_DEFAULT_OPUS_MODEL`이 없으면 Foundry의 `opus` 별칭은 Opus 4.6으로 확인됩니다. 최신 모델을 사용하려면 Opus 4.8 ID로 설정합니다:182`ANTHROPIC_DEFAULT_OPUS_MODEL`이 없으면 Microsoft Foundry의 `opus` 별칭은 Opus 4.6으로 확인됩니다. 최신 모델을 사용하려면 Opus 4.8 ID로 설정합니다:

171 183

172```bash theme={null}184```bash theme={null}

173export ANTHROPIC_DEFAULT_OPUS_MODEL='claude-opus-4-8'185export ANTHROPIC_DEFAULT_OPUS_MODEL='claude-opus-4-8'

175export ANTHROPIC_DEFAULT_HAIKU_MODEL='claude-haiku-4-5'187export ANTHROPIC_DEFAULT_HAIKU_MODEL='claude-haiku-4-5'

176```188```

177 189

178세션 제목 생성과 같은 백그라운드 작업은 일반적으로 Haiku 클래스 모델인 소형/빠른 모델을 사용합니다. Foundry에서 Claude Code는 모든 계정이 Haiku 배포를 가지고 있지 않기 때문에 기본 모델로 기본 설정됩니다. 백그라운드 작업에 Haiku를 사용하려면 위에 표시된 대로 `ANTHROPIC_DEFAULT_HAIKU_MODEL`을 계정에서 사용 가능한 Haiku 배포로 설정합니다.190세션 제목 생성과 같은 백그라운드 작업은 일반적으로 Haiku 클래스 모델인 소형/빠른 모델을 사용합니다. Microsoft Foundry에서 Claude Code는 모든 계정이 Haiku 배포를 가지고 있지 않기 때문에 기본 모델로 기본 설정됩니다. 백그라운드 작업에 Haiku를 사용하려면 위에 표시된 대로 `ANTHROPIC_DEFAULT_HAIKU_MODEL`을 계정에서 사용 가능한 Haiku 배포로 설정합니다.

179 191

180현재 및 레거시 모델 ID는 [모델 개요](https://platform.claude.com/docs/en/about-claude/models/overview)를 참조하세요. 전체 환경 변수 목록은 [모델 구성](/ko/model-config#pin-models-for-third-party-deployments)을 참조하세요.192현재 및 레거시 모델 ID는 [모델 개요](https://platform.claude.com/docs/en/about-claude/models/overview)를 참조하세요. 전체 환경 변수 목록은 [모델 구성](/ko/model-config#pin-models-for-third-party-deployments)을 참조하세요.

181 193

195claude207claude

196```208```

197 209

198Claude Code는 환경에서 `CLAUDE_CODE_USE_FOUNDRY` 및 기타 Foundry 변수를 읽고 첫 번째 프롬프트에서 Azure 리소스에 연결합니다. Bedrock 및 Vertex AI와 달리 Foundry는 대화형 설정 마법사가 없으므로 3단계와 4단계의 환경 변수가 유일한 구성 경로입니다.210Claude Code는 환경에서 `CLAUDE_CODE_USE_FOUNDRY` 및 기타 Microsoft Foundry 변수를 읽고 첫 번째 프롬프트에서 Azure 리소스에 연결합니다. Amazon Bedrock 및 Google Cloud의 Agent Platform과 달리 Microsoft Foundry는 대화형 설정 마법사가 없으므로 3단계와 4단계의 환경 변수가 유일한 구성 경로입니다.

199 211

200<h2 id="azure-rbac-configuration">212<h2 id="azure-rbac-configuration">

201 Azure RBAC 구성213 Azure RBAC 구성

model-config.md +84 −31

Details

15* **모델 별칭**15* **모델 별칭**

16* **모델 이름**16* **모델 이름**

17 * Anthropic API: 전체 **[모델 이름](https://platform.claude.com/docs/ko/about-claude/models/overview)**17 * Anthropic API: 전체 **[모델 이름](https://platform.claude.com/docs/ko/about-claude/models/overview)**

~~18 * Bedrock: 추론 프로필 ARN~~18 * Amazon Bedrock: 추론 프로필 ARN

~~19 * Foundry: 배포 이름~~19 * Microsoft Foundry: 배포 이름

~~20 * Vertex: 버전 이름~~20 * Google Cloud의 Agent Platform: 버전 이름

21 21

22<Note>22<Note>

23 `ANTHROPIC_BASE_URL`은 요청이 전송되는 위치를 변경하며, 어느 모델이 응답하는지는 변경하지 않습니다. Claude를 LLM 게이트웨이를 통해 라우팅하려면 [LLM 게이트웨이](/ko/llm-gateway)를 참조하세요.23 `ANTHROPIC_BASE_URL`은 요청이 전송되는 위치를 변경하며, 어느 모델이 응답하는지는 변경하지 않습니다. Claude를 LLM 게이트웨이를 통해 라우팅하려면 [LLM 게이트웨이](/ko/llm-gateway)를 참조하세요.

41| **`opus[1m]`** | 긴 세션을 위해 [100만 토큰 컨텍스트 윈도우](https://platform.claude.com/docs/ko/build-with-claude/context-windows#1m-token-context-window)를 사용하는 Opus를 사용합니다 |41| **`opus[1m]`** | 긴 세션을 위해 [100만 토큰 컨텍스트 윈도우](https://platform.claude.com/docs/ko/build-with-claude/context-windows#1m-token-context-window)를 사용하는 Opus를 사용합니다 |

43 43

44Anthropic API에서 `opus`는 Opus 4.8로, `sonnet`은 Sonnet 5로 확인됩니다. [Claude Platform on AWS](/ko/claude-platform-on-aws)에서 `opus`는 Opus 4.7로, `sonnet`은 Sonnet 4.6으로 확인됩니다. Bedrock, Vertex 및 Foundry에서 `opus`는 Opus 4.6으로, `sonnet`은 Sonnet 4.5로 확인됩니다. 더 새로운 모델은 전체 모델 이름을 명시적으로 선택하거나 `ANTHROPIC_DEFAULT_OPUS_MODEL` 또는 `ANTHROPIC_DEFAULT_SONNET_MODEL`을 설정하여 해당 제공자에서 사용할 수 있습니다.44Anthropic API에서 `opus`는 Opus 4.8로, `sonnet`은 Sonnet 5로 확인됩니다. [Claude Platform on AWS](/ko/claude-platform-on-aws)에서 `opus`는 Opus 4.7로, `sonnet`은 Sonnet 4.6으로 확인됩니다. Amazon Bedrock, Google Cloud의 Agent Platform 및 Microsoft Foundry에서 `opus`는 Opus 4.6으로, `sonnet`은 Sonnet 4.5로 확인됩니다. 더 새로운 모델은 전체 모델 이름을 명시적으로 선택하거나 `ANTHROPIC_DEFAULT_OPUS_MODEL` 또는 `ANTHROPIC_DEFAULT_SONNET_MODEL`을 설정하여 해당 제공자에서 사용할 수 있습니다.

45 45

46별칭은 제공자에 대한 권장 버전을 가리키며 시간이 지남에 따라 업데이트됩니다. 특정 버전으로 고정하려면 전체 모델 이름(예: `claude-opus-4-8`)을 사용하거나 `ANTHROPIC_DEFAULT_OPUS_MODEL`과 같은 해당 환경 변수를 설정합니다.46별칭은 제공자에 대한 권장 버전을 가리키며 시간이 지남에 따라 업데이트됩니다. 특정 버전으로 고정하려면 전체 모델 이름(예: `claude-opus-4-8`)을 사용하거나 `ANTHROPIC_DEFAULT_OPUS_MODEL`과 같은 해당 환경 변수를 설정합니다.

47 47

84* `Enter`: 모델을 전환하고 기본값으로 저장합니다84* `Enter`: 모델을 전환하고 기본값으로 저장합니다

85* `s`: 이 세션에만 모델을 전환합니다85* `s`: 이 세션에만 모델을 전환합니다

86 86

87`/model <name>`을 직접 입력하면 `Enter`처럼 동작합니다. 프로젝트 및 관리되는 설정은 여전히 우선순위를 가지며 다음 실행 시 다시 적용됩니다. {/* min-version: 2.1.196 */}관리자가 구성한 [조직 기본 모델](#organization-default-model)도 다음 실행 시 다시 적용됩니다.87`/model <name>`을 직접 입력하면 `Enter`처럼 동작합니다. {/* min-version: 2.1.205 */}[비대화형 모드](/ko/headless)에서 `-p` 플래그를 사용하여 `/model`로 설정된 모델은 현재 세션에만 적용되며 기본값으로 저장되지 않습니다. 프로젝트 및 관리되는 설정은 여전히 우선순위를 가지며 다음 실행 시 다시 적용됩니다. {/* min-version: 2.1.196 */}관리자가 구성한 [조직 기본 모델](#organization-default-model)도 다음 실행 시 다시 적용됩니다.

88 88

89v2.1.144부터 v2.1.152까지는 `/model`이 현재 세션에만 적용되었으며 선택기에서 `d`가 기본값을 저장했습니다.89v2.1.144부터 v2.1.152까지는 `/model`이 현재 세션에만 적용되었으며 선택기에서 `d`가 기본값을 저장했습니다.

90 90

96 96

97시작 시 활성 모델이 자신의 선택이 아닌 프로젝트 또는 관리되는 설정에서 나온 경우, 시작 헤더는 어느 설정 파일이 이를 설정했는지 표시합니다. `/model`을 실행하여 재정의합니다. 프로젝트 또는 관리되는 설정은 다음 실행 시 다시 적용됩니다.97시작 시 활성 모델이 자신의 선택이 아닌 프로젝트 또는 관리되는 설정에서 나온 경우, 시작 헤더는 어느 설정 파일이 이를 설정했는지 표시합니다. `/model`을 실행하여 재정의합니다. 프로젝트 또는 관리되는 설정은 다음 실행 시 다시 적용됩니다.

98 98

99[Agent SDK](/ko/agent-sdk/overview) `setModel()` 메서드 또는 Claude Code CLI를 실행하는 [Desktop app](/ko/desktop)과 같은 앱을 통해 모델 전환이 요청될 때, Claude Code는 문자열이 인식하는 것인지 확인한 후 저장합니다. 이 확인에는 Claude Code v2.1.200 이상이 필요합니다. Anthropic API에서 Claude Code는 다음을 인식합니다:

100

101* 모델 별칭

102* `/model` 선택기의 항목

103* `claude-`로 시작하는 모든 이름

104* [사용자 정의 모델 옵션](#add-a-custom-model-option)으로 구성하거나 [`modelOverrides`](#override-model-ids-per-version)에서 구성한 값

105

106Claude Code는 인식되지 않는 문자열을 `Model "<name>" is not a recognized model id.`로 거부하며 세션은 현재 모델을 유지합니다. 문자열을 저장하고 다음 요청에서 실패하는 대신입니다. 복구 단계는 [오류 참조](/ko/errors#model-is-not-a-recognized-model-id)를 참조하세요.

107

108확인은 Anthropic API에서만 실행됩니다. Amazon Bedrock, Google Cloud의 Agent Platform, Microsoft Foundry, [Claude Platform on AWS](/ko/claude-platform-on-aws) 및 [LLM 게이트웨이](/ko/llm-gateway) 뒤 또는 사용자 정의 `ANTHROPIC_BASE_URL` 뒤에서는 제공자 또는 게이트웨이가 모델 이름을 정의하므로 Claude Code는 확인 없이 모든 문자열을 통과시킵니다. 확인은 또한 `--model` 플래그, `ANTHROPIC_MODEL` 환경 변수 또는 `model` 설정을 포함하지 않습니다. 잘못된 값은 첫 번째 요청 대신 [선택한 모델에 문제가 있습니다](/ko/errors#there%E2%80%99s-an-issue-with-the-selected-model)를 생성합니다.

109

99요청된 모델에 예정된 중단 날짜가 있거나 자동으로 최신 버전으로 재매핑될 때, Claude Code는 요청된 모델의 이름을 지정하는 경고를 표시합니다. 대화형 세션은 이를 시작 알림으로 표시합니다. v2.1.182부터 [비대화형 모드](/ko/headless)에서 기본 텍스트 출력 형식을 사용할 때 동일한 경고가 stderr에 기록됩니다. 확인은 [서브에이전트 프론트매터](/ko/sub-agents)에 설정된 `model`도 포함합니다. stderr 경고는 `--output-format json` 및 `stream-json`에 대해 억제됩니다. [결과 메시지](/ko/headless#get-structured-output)의 `modelUsage` 필드에서 실제 모델을 읽으세요.110요청된 모델에 예정된 중단 날짜가 있거나 자동으로 최신 버전으로 재매핑될 때, Claude Code는 요청된 모델의 이름을 지정하는 경고를 표시합니다. 대화형 세션은 이를 시작 알림으로 표시합니다. v2.1.182부터 [비대화형 모드](/ko/headless)에서 기본 텍스트 출력 형식을 사용할 때 동일한 경고가 stderr에 기록됩니다. 확인은 [서브에이전트 프론트매터](/ko/sub-agents)에 설정된 `model`도 포함합니다. stderr 경고는 `--output-format json` 및 `stream-json`에 대해 억제됩니다. [결과 메시지](/ko/headless#get-structured-output)의 `modelUsage` 필드에서 실제 모델을 읽으세요.

100 111

101사용 예시:112사용 예시:

135* **어드바이저 모델**: 구성된 [`advisorModel`](/ko/advisor) 설정 및 `--advisor` 플래그146* **어드바이저 모델**: 구성된 [`advisorModel`](/ko/advisor) 설정 및 `--advisor` 플래그

136* **백그라운드 에이전트 모델**: [디스패치 선택기](/ko/agent-view)에서 선택된 모델147* **백그라운드 에이전트 모델**: [디스패치 선택기](/ko/agent-view)에서 선택된 모델

137 148

138`/model`로 차단된 모델로 전환하면 오류로 거부되고, 차단된 `--model` 플래그, `ANTHROPIC_MODEL` 또는 `model` 설정 값은 시작 시 요청된 모델과 대체된 모델을 모두 이름 지은 경고와 함께 대체되며 세션은 기본 모델에서 시작됩니다. 차단된 서브에이전트, 스킬 또는 명령 재정의는 요청을 실패하지 않고 상속되거나 기본 모델로 폴백됩니다. 차단된 `advisorModel` 설정은 세션에 대해 어드바이저를 비활성화하고, 차단된 `--advisor` 플래그 값은 시작 시 오류로 종료됩니다. 제외된 모델은 `/model` 선택기에서 숨겨집니다. {/* min-version: 2.1.199 */}v2.1.199부터 목록의 전체 모델 ID(예: 목록이 고정하는 이전 버전)에 기본 제공 선택기 행이 없으면 `/model` 선택기에 자신의 레이블이 지정된 행으로 나타납니다. 이전 버전에서는 그러한 ID는 `/model <id>`를 입력하여만 선택 가능합니다.149Anthropic API 및 [AWS의 Claude Platform](/ko/claude-platform-on-aws)에서 모델 패밀리 별칭인 `opus`, `sonnet`, `haiku` 또는 `fable`은 허용 목록이 허용하는 해당 패밀리의 최신 버전으로 확인됩니다. 허용 목록이 특정 버전을 고정할 때(예: `["sonnet", "claude-opus-4-6"]`), `/model opus` 및 `--model opus` 모두 허용된 최신 Opus인 Claude Opus 4.6을 선택하고 요청된 모델과 대체된 모델을 모두 이름 지은 알림을 표시합니다. v2.1.205 이전에는 최신 릴리스된 버전이 목록 외부에 있는 별칭은 목록이 이전 버전을 허용했을 때도 다른 차단된 선택처럼 거부되거나 대체되었습니다.

150

151Amazon Bedrock, Google Cloud의 Agent Platform, Microsoft Foundry 및 [Mantle](/ko/amazon-bedrock#use-the-mantle-endpoint)은 Anthropic 모델 ID가 아닌 제공자별 배포 ID를 사용하므로 차단된 별칭은 아래의 거부 및 대체 동작을 따릅니다.

139 152

140자동 모델 변경은 동일한 방식으로 확인됩니다: [폴백 모델 체인](#fallback-model-chains)의 허용 목록 외부 요소는 삭제되고, [`opusplan`](#opusplan-model-setting)과 같은 계획 모드 업그레이드는 제외된 모델로 건너뛰어 계획이 세션의 모델에서 계속되며, 대상이 제외된 [자동 모델 폴백](#automatic-model-fallback)은 실행되지 않으므로 플래그된 요청은 거부로 끝납니다. [빠른 모드](/ko/fast-mode)를 활성화하면 세션이 실행될 모델이 허용 목록 외부에 있을 때 거부됩니다.153Claude Code는 모델이 설정된 위치에 따라 다른 차단된 선택을 처리합니다:

154

155* **`/model`**: 전환이 오류로 거부됩니다

156* **`--model` 플래그, `ANTHROPIC_MODEL` 또는 `model` 설정**: 값은 시작 시 요청된 모델과 대체된 모델을 모두 이름 지은 경고와 함께 기본 모델로 대체되며 세션은 기본 모델에서 시작됩니다

157* **서브에이전트, 스킬 또는 명령 재정의**: 재정의는 요청을 실패하지 않고 상속되거나 기본 모델로 폴백됩니다

158* **`advisorModel` 설정**: 어드바이저는 세션에 대해 비활성화됩니다

159* **`--advisor` 플래그**: Claude Code는 시작 시 오류로 종료됩니다

160

161제외된 모델은 `/model` 선택기에서 숨겨집니다. {/* min-version: 2.1.199 */}}목록의 전체 모델 ID(예: 목록이 고정하는 이전 버전)에 기본 제공 선택기 행이 없으면 `/model` 선택기에 자신의 레이블이 지정된 행으로 나타납니다. v2.1.199 이전에는 그러한 ID는 `/model <id>`를 입력하여만 선택 가능합니다.

162

163Claude Code가 사용자를 대신하여 수행하는 모델 변경은 동일한 방식으로 확인됩니다:

164

165* **[폴백 모델 체인](#fallback-model-chains)**: 허용 목록 외부의 요소는 삭제됩니다

166* **계획 모드 업그레이드**: Anthropic API 및 AWS의 Claude Platform에서 [`opusplan`](#opusplan-model-setting)과 같은 업그레이드는 제외된 모델로 업그레이드할 때 업그레이드 패밀리의 최신 허용 버전을 사용합니다. 제공자별 모델 ID가 있는 제공자에서 그리고 허용된 버전이 없을 때 업그레이드는 건너뛰어지고 계획이 세션의 모델에서 계속됩니다

167* **[자동 모델 폴백](#automatic-model-fallback)**: 대상이 제외된 폴백은 실행되지 않으므로 플래그된 요청은 거부로 끝납니다

168* **[빠른 모드](/ko/fast-mode)**: 세션이 그 후에 실행될 모델이 허용 목록 외부에 있을 때 빠른 모드를 활성화하는 것이 거부됩니다

141 169

142```json theme={null}170```json theme={null}

143{171{

158 186

159* 클라우드 세션은 [Claude Code on the web](/ko/claude-code-on-the-web) 또는 데스크톱 앱에서 Anthropic 관리 VM에서 실행됩니다: 장치에 배포된 설정은 이에 도달하지 않으므로 서버 관리 설정을 통해 허용 목록을 전달합니다. 클라우드 세션의 중간 세션 모델 전환은 요청된 모델이 허용 목록에 의해 제외될 때 거부됩니다. 세션 생성 시 서버 측 거부는 `availableModels` 설정 키가 아닌 [조직 모델 제한](#organization-model-restrictions)에 적용됩니다.187* 클라우드 세션은 [Claude Code on the web](/ko/claude-code-on-the-web) 또는 데스크톱 앱에서 Anthropic 관리 VM에서 실행됩니다: 장치에 배포된 설정은 이에 도달하지 않으므로 서버 관리 설정을 통해 허용 목록을 전달합니다. 클라우드 세션의 중간 세션 모델 전환은 요청된 모델이 허용 목록에 의해 제외될 때 거부됩니다. 세션 생성 시 서버 측 거부는 `availableModels` 설정 키가 아닌 [조직 모델 제한](#organization-model-restrictions)에 적용됩니다.

160* Cowork는 Claude 데스크톱 앱의 에이전트 작업 탭이며 설계상 서버 관리 설정을 수신하지 않습니다. 관리 설정 파일은 세션이 실행되는 위치에 있을 때 Cowork 세션에 적용됩니다. 원격 Cowork 세션은 Anthropic 관리 VM에서 실행되며, 여기서 장치 배포 파일이 없습니다.188* Cowork는 Claude 데스크톱 앱의 에이전트 작업 탭이며 설계상 서버 관리 설정을 수신하지 않습니다. 관리 설정 파일은 세션이 실행되는 위치에 있을 때 Cowork 세션에 적용됩니다. 원격 Cowork 세션은 Anthropic 관리 VM에서 실행되며, 여기서 장치 배포 파일이 없습니다.

161* [Bedrock, Vertex AI, Foundry 및 Claude Platform on AWS](/ko/claude-platform-on-aws)와 같은 [타사 제공자](/ko/server-managed-settings#platform-availability)의 세션은 서버 관리 설정을 수신하지 않으므로 MDM 또는 관리 설정 파일을 통해 허용 목록을 전달합니다.189* [Amazon Bedrock, Google Cloud의 Agent Platform, Microsoft Foundry 및 Claude Platform on AWS](/ko/claude-platform-on-aws)와 같은 [타사 제공자](/ko/server-managed-settings#platform-availability)의 세션은 서버 관리 설정을 수신하지 않으므로 MDM 또는 관리 설정 파일을 통해 허용 목록을 전달합니다.

162* 서버 관리 전달은 또한 세션이 조직 로그인 또는 직접 구성된 API 키로 인증해야 합니다. [`apiKeyHelper`](/ko/settings#available-settings) 스크립트를 통해서만 키를 생성하는 플릿은 MDM 또는 관리 설정 파일을 통해 허용 목록을 전달해야 합니다.190* 서버 관리 전달은 또한 세션이 조직 로그인 또는 직접 구성된 API 키로 인증해야 합니다. [`apiKeyHelper`](/ko/settings#available-settings) 스크립트를 통해서만 키를 생성하는 플릿은 MDM 또는 관리 설정 파일을 통해 허용 목록을 전달해야 합니다.

163* 데스크톱 Code 탭은 또한 [SSH 세션](/ko/desktop#ssh-sessions)을 호스팅하며, 이는 실행되는 원격 호스트에서 관리 설정 파일을 읽습니다. [데스크톱 관리 설정](/ko/desktop#managed-settings)을 참조하세요.191* 데스크톱 Code 탭은 또한 [SSH 세션](/ko/desktop#ssh-sessions)을 호스팅하며, 이는 실행되는 원격 호스트에서 관리 설정 파일을 읽습니다. [데스크톱 관리 설정](/ko/desktop#managed-settings)을 참조하세요.

164* claude.ai 및 데스크톱 앱의 모델 선택기는 조직의 허용 목록에 의해 제외된 모델을 숨기거나 회색으로 표시합니다. 선택기 상태는 사용자를 위한 편의입니다. 적용은 세션에서 발생합니다.192* claude.ai 및 데스크톱 앱의 모델 선택기는 조직의 허용 목록에 의해 제외된 모델을 숨기거나 회색으로 표시합니다. 선택기 상태는 사용자를 위한 편의입니다. 적용은 세션에서 발생합니다.

184}212}

185```213```

186 214

187사용자의 계정 유형에 대한 기본 모델이 허용 목록에 없으면 Default 옵션은 대신 허용되고 사용 가능한 모델을 이름 지은 첫 번째 `availableModels` 항목으로 확인되며, `/model` 선택기의 Default 행은 해당 모델을 표시합니다. 이는 기본값에 도달하는 모든 위치에 적용됩니다: 세션 시작, `/model`에서 Default 선택, [폴백 모델 체인](#fallback-model-chains)의 `"default"` 키워드 및 제외된 선택이 삭제될 때 사용되는 폴백입니다.215계정 유형에 대한 기본 모델이 허용 목록에 없으면 Default 옵션은 대신 허용되고 사용 가능한 모델을 이름 지은 첫 번째 `availableModels` 항목으로 확인되며, `/model` 선택기의 Default 행은 해당 모델을 표시합니다. 이는 기본값에 도달하는 모든 위치에 적용됩니다: 세션 시작, `/model`에서 Default 선택, [폴백 모델 체인](#fallback-model-chains)의 `"default"` 키워드 및 제외된 선택이 삭제될 때 사용되는 폴백입니다.

188 216

189`enforceAvailableModels`은 `availableModels`이 설정되지 않거나 비어 있을 때 효과가 없습니다: `availableModels: []`인 경우 계정 유형에 대한 Default 모델은 사용 가능하므로 설정이 사용자를 모든 모델에서 잠글 수 없습니다. `availableModels`이 비어 있지 않지만 허용되고 사용 가능한 모델을 확인하는 항목이 없으면 강제가 저하되고 Default는 계정 유형 기본값으로 폴스루되며, `--debug` 아래에서만 표시되는 경고가 있습니다. 이를 피하려면 목록에 최소한 하나의 보장된 사용 가능 항목을 유지합니다.217`enforceAvailableModels`은 `availableModels`이 설정되지 않거나 비어 있을 때 효과가 없습니다: `availableModels: []`인 경우 계정 유형에 대한 Default 모델은 사용 가능하므로 설정이 사용자를 모든 모델에서 잠글 수 없습니다. `availableModels`이 비어 있지 않지만 허용되고 사용 가능한 모델을 확인하는 항목이 없으면 강제가 저하되고 Default는 계정 유형 기본값으로 폴스루되며, `--debug` 아래에서만 표시되는 경고가 있습니다. 이를 피하려면 목록에 최소한 하나의 보장된 사용 가능 항목을 유지합니다.

190 218

230 Mantle 모델 ID258 Mantle 모델 ID

231</h3>259</h3>

232 260

233[Bedrock Mantle 엔드포인트](/ko/amazon-bedrock#use-the-mantle-endpoint)가 활성화되면 `anthropic.`으로 시작하는 `availableModels`의 항목이 `/model` 선택기에 사용자 정의 옵션으로 추가되고 Mantle 엔드포인트로 라우팅됩니다. 이는 [타사 배포를 위한 모델 고정](#pin-models-for-third-party-deployments)에 설명된 별칭 일치에 대한 예외입니다. 설정은 여전히 선택기를 나열된 항목으로 제한하며, Mantle ID는 패밀리 이름을 포함하므로 특정 항목으로 계산되고 해당 패밀리의 와일드카드를 비활성화합니다: 모든 Mantle ID와 함께 유지하려는 버전 접두사 또는 전체 ID를 나열합니다. [병합 동작](#merge-behavior)을 참조하세요.261[Amazon Bedrock Mantle 엔드포인트](/ko/amazon-bedrock#use-the-mantle-endpoint)가 활성화되면 `anthropic.`으로 시작하는 `availableModels`의 항목이 `/model` 선택기에 사용자 정의 옵션으로 추가되고 Mantle 엔드포인트로 라우팅됩니다. 이는 [타사 배포를 위한 모델 고정](#pin-models-for-third-party-deployments)에 설명된 별칭 일치에 대한 예외입니다. 설정은 여전히 선택기를 나열된 항목으로 제한하며, Mantle ID는 패밀리 이름을 포함하므로 특정 항목으로 계산되고 해당 패밀리의 와일드카드를 비활성화합니다: 모든 Mantle ID와 함께 유지하려는 버전 접두사 또는 전체 ID를 나열합니다. [병합 동작](#merge-behavior)을 참조하세요.

234 262

235<h3 id="organization-model-restrictions">263<h3 id="organization-model-restrictions">

236 조직 모델 제한264 조직 모델 제한

244 272

245제한된 모델은 `/model` 선택기에서 숨겨집니다. `--model`, `ANTHROPIC_MODEL` 환경 변수 또는 `model` 설정으로 이름으로 선택하면 `Model "<name>" is restricted by your organization's settings. Using <model> instead.` 알림이 표시되고 세션은 허용된 모델에서 시작됩니다. 제한된 모델에 대해 `/model <name>`을 입력하면 `Model '<name>' is restricted by your organization's settings. Run /model to choose a different model.`로 거부되고 세션은 현재 모델을 유지합니다.273제한된 모델은 `/model` 선택기에서 숨겨집니다. `--model`, `ANTHROPIC_MODEL` 환경 변수 또는 `model` 설정으로 이름으로 선택하면 `Model "<name>" is restricted by your organization's settings. Using <model> instead.` 알림이 표시되고 세션은 허용된 모델에서 시작됩니다. 제한된 모델에 대해 `/model <name>`을 입력하면 `Model '<name>' is restricted by your organization's settings. Run /model to choose a different model.`로 거부되고 세션은 현재 모델을 유지합니다.

246 274

247두 제한은 함께 적용됩니다: 모델은 `availableModels`에 의해 허용되고 조직에 의해 제한되지 않을 때만 선택 가능합니다. 조직 제한은 Anthropic API 및 [LLM 게이트웨이](/ko/llm-gateway) 배포의 세션에 전달됩니다. Bedrock, Vertex AI, Foundry 및 Claude Platform on AWS의 세션은 이를 수신하지 않으므로 대신 해당 제공자에서 `availableModels`을 사용합니다.275`opus`, `sonnet`, `haiku` 또는 `fable`과 같은 [모델 패밀리 별칭](#restrict-model-selection)은 조직이 허용하는 해당 패밀리의 최신 버전으로 확인되며, 동일한 대체 알림이 표시됩니다. `/model <alias>`는 해당 패밀리의 모든 버전이 제한될 때만 거부됩니다. `--model`, `ANTHROPIC_MODEL` 또는 `model` 설정으로 설정된 별칭은 그 경우에도 시작 시 대체됩니다. v2.1.205 이전에는 최신 릴리스된 버전이 제한된 패밀리 별칭은 목록이 이전 버전을 허용했을 때도 다른 차단된 선택처럼 대체되거나 거부되었습니다.

276

277제한은 조직 전체 또는 역할별로 적용됩니다:

278

279* 조직 수준에서 모델을 비활성화하면 모든 구성원에게서 제거됩니다.

280* 역할 수준 액세스는 다양한 사용자 정의 역할에 다양한 모델을 부여하며, 여러 역할을 보유한 구성원은 자신의 역할 중 하나가 부여하는 모든 모델을 사용할 수 있습니다.

281* Haiku 모델은 항상 사용 가능하며 비활성화할 수 없으므로 모든 구성원은 최소한 하나의 사용 가능한 모델을 유지합니다.

282* 액세스 변경은 약 1분 내에 새 요청에 적용됩니다. `/model` 선택기는 다음 번 세션이 시작될 때 이를 반영합니다.

283

284두 제한은 함께 적용됩니다: 모델은 `availableModels`에 의해 허용되고 조직에 의해 제한되지 않을 때만 선택 가능합니다. 조직 제한은 Anthropic API 및 [LLM 게이트웨이](/ko/llm-gateway) 배포의 세션에 전달됩니다. Amazon Bedrock, Google Cloud의 Agent Platform, Microsoft Foundry 및 Claude Platform on AWS의 세션은 이를 수신하지 않으므로 대신 해당 제공자에서 `availableModels`을 사용합니다.

248 285

249<h2 id="organization-default-model">286<h2 id="organization-default-model">

250 조직 기본 모델287 조직 기본 모델

303* **Max, Team Premium, Enterprise 종량제 및 Anthropic API**: Opus 4.8로 기본값 설정340* **Max, Team Premium, Enterprise 종량제 및 Anthropic API**: Opus 4.8로 기본값 설정

304* **AWS의 Claude Platform**: Opus 4.7로 기본값 설정341* **AWS의 Claude Platform**: Opus 4.7로 기본값 설정

305* **Pro, Team Standard 및 Enterprise 구독 시트**: Sonnet 5로 기본값 설정342* **Pro, Team Standard 및 Enterprise 구독 시트**: Sonnet 5로 기본값 설정

306* **Bedrock, Vertex 및 Foundry**: Sonnet 4.5로 기본값 설정343* **Amazon Bedrock, Google Cloud의 Agent Platform 및 Microsoft Foundry**: Sonnet 4.5로 기본값 설정

307 344

308Enterprise 종량제는 구독 시트가 아닌 사용량으로 청구되는 Enterprise 조직을 의미합니다.345Enterprise 종량제는 구독 시트가 아닌 사용량으로 청구되는 Enterprise 조직을 의미합니다.

309 346

326 363

327Plan Mode Opus 단계는 `opus` 모델 설정과 동일한 컨텍스트 윈도우를 사용합니다. Opus가 [자동으로 1M 컨텍스트로 업그레이드](#extended-context)되는 구독 계층에서 `opusplan`은 Plan Mode에서도 업그레이드를 받습니다. 자동 업그레이드 계층이 아닌 경우 두 단계 모두에 1M 컨텍스트를 강제하려면 모델을 `opusplan[1m]`으로 설정합니다.364Plan Mode Opus 단계는 `opus` 모델 설정과 동일한 컨텍스트 윈도우를 사용합니다. Opus가 [자동으로 1M 컨텍스트로 업그레이드](#extended-context)되는 구독 계층에서 `opusplan`은 Plan Mode에서도 업그레이드를 받습니다. 자동 업그레이드 계층이 아닌 경우 두 단계 모두에 1M 컨텍스트를 강제하려면 모델을 `opusplan[1m]`으로 설정합니다.

328 365

329[`availableModels`](#restrict-model-selection)이 Opus를 제외할 때 `opusplan`은 전환하는 대신 Plan Mode에서 Sonnet에 유지됩니다. 마찬가지로 Sonnet이 제외될 때 일반적으로 Plan Mode에서 Sonnet으로 업그레이드되는 Haiku 세션도 Haiku에 유지됩니다.366[`availableModels`](#restrict-model-selection)이 최신 Opus를 제외하지만 이전 버전(예: `["sonnet", "claude-opus-4-6"]`)을 허용할 때 `opusplan`은 계획을 위해 허용된 최신 Opus를 사용하고 모든 Opus가 제외될 때만 Sonnet에 유지됩니다. 일반적으로 Plan Mode에서 Sonnet으로 업그레이드되는 Haiku 세션도 마찬가지로 허용된 최신 Sonnet을 사용하고 모든 Sonnet이 제외될 때만 Haiku에 유지됩니다. v2.1.205 이전에는 허용 목록이 이전 버전을 허용했더라도 업그레이드 제품군의 최신 버전이 제외될 때마다 Plan Mode가 세션의 모델에 유지되었습니다.

367

368이전 허용 버전의 대체는 Anthropic API 및 [Claude Platform on AWS](/ko/claude-platform-on-aws)에 적용됩니다. Amazon Bedrock, Google Cloud의 Agent Platform, Microsoft Foundry 및 Mantle에서는 배포가 공급자별 모델 ID를 사용하므로 업그레이드 모델이 제외될 때마다 Plan Mode가 세션의 모델에 유지됩니다.

330 369

331Claude가 Plan 경계에서 전환하는 대신 작업 중간에 두 번째 모델을 참고할 시기를 결정하는 하이브리드 접근 방식은 [advisor tool](/ko/advisor)을 참조하세요.370Claude가 Plan 경계에서 전환하는 대신 작업 중간에 두 번째 모델을 참고할 시기를 결정하는 하이브리드 접근 방식은 [advisor tool](/ko/advisor)을 참조하세요.

332 371

392* [비대화형 모드](/ko/cli-reference#cli-flags) 및 프롬프트를 표시할 수 없는 SDK 통합에서 플래그가 지정된 요청은 거부로 턴을 종료합니다.431* [비대화형 모드](/ko/cli-reference#cli-flags) 및 프롬프트를 표시할 수 없는 SDK 통합에서 플래그가 지정된 요청은 거부로 턴을 종료합니다.

393* 폴백 대상이 [`availableModels`](#restrict-model-selection)에 의해 차단되면 프롬프트가 표시되지 않습니다. 플래그가 지정된 요청은 거부로 종료되며, 대상이 차단될 때 자동 폴백과 동일합니다.432* 폴백 대상이 [`availableModels`](#restrict-model-selection)에 의해 차단되면 프롬프트가 표시되지 않습니다. 플래그가 지정된 요청은 거부로 종료되며, 대상이 차단될 때 자동 폴백과 동일합니다.

394 433

395<h4 id="enable-fallback-on-bedrock-vertex-ai-and-foundry">434<h4 id="enable-fallback-on-bedrock-agent-platform-and-foundry">

396 Bedrock, Vertex AI 및 Foundry에서 폴백 활성화435 Bedrock, Agent Platform 및 Foundry에서 폴백 활성화

397</h4>436</h4>

398 437

399[Amazon Bedrock](/ko/amazon-bedrock), [Google Vertex AI](/ko/google-vertex-ai) 및 [Microsoft Foundry](/ko/microsoft-foundry)에서 모델 ID는 공급자별로 다르므로 자동 폴백은 Claude Code가 관련된 두 모델을 식별할 수 있을 때만 작동합니다:438[Amazon Bedrock](/ko/amazon-bedrock), [Google Cloud의 Agent Platform](/ko/google-vertex-ai) 및 [Microsoft Foundry](/ko/microsoft-foundry)에서 모델 ID는 공급자별로 다르므로 자동 폴백은 Claude Code가 관련된 두 모델을 식별할 수 있을 때만 작동합니다:

400 439

401* Claude Code는 현재 모델을 Fable 5로 인식해야 합니다: 모델 ID에 `claude-fable-5`가 포함되거나 `ANTHROPIC_DEFAULT_FABLE_MODEL`의 값과 일치하거나 [`modelOverrides`](#override-model-ids-per-version)로 매핑됩니다.440* Claude Code는 현재 모델을 Fable 5로 인식해야 합니다: 모델 ID에 `claude-fable-5`가 포함되거나 `ANTHROPIC_DEFAULT_FABLE_MODEL`의 값과 일치하거나 [`modelOverrides`](#override-model-ids-per-version)로 매핑됩니다.

402* 폴백 대상은 Opus 모델로 확인되어야 합니다: `ANTHROPIC_DEFAULT_OPUS_MODEL`의 값(설정된 경우) 또는 공급자의 모델 목록의 Opus 4.8 항목입니다.441* 폴백 대상은 Opus 모델로 확인되어야 합니다: `ANTHROPIC_DEFAULT_OPUS_MODEL`의 값(설정된 경우) 또는 공급자의 모델 목록의 Opus 4.8 항목입니다.

429 468

430기본 노력은 Fable 5, Sonnet 5, Opus 4.8, Opus 4.6 및 Sonnet 4.6에서 `high`이고 Opus 4.7에서 `xhigh`입니다.469기본 노력은 Fable 5, Sonnet 5, Opus 4.8, Opus 4.6 및 Sonnet 4.6에서 `high`이고 Opus 4.7에서 `xhigh`입니다.

431 470

432Fable 5, Opus 4.8 또는 Opus 4.7을 처음 실행할 때 Claude Code는 이전에 다른 모델에 대해 다른 수준을 설정했더라도 해당 모델의 기본 노력을 적용합니다: Fable 5 및 Opus 4.8에서 `high`, Opus 4.7에서 `xhigh`. 전환 후 다른 수준을 선택하려면 `/effort`를 다시 실행하세요.471Fable 5, Opus 4.8 또는 Opus 4.7을 처음 실행할 때 Claude Code는 이전에 다른 모델에 대해 다른 수준을 설정했더라도 해당 모델의 기본 노력을 적용합니다: Fable 5 및 Opus 4.8에서 `high`, Opus 4.7에서 `xhigh`. 전환 후 다른 수준을 선택하려면 `/effort`를 다시 실행하세요. 해당 기본값은 명시적 노력 선택(예: 대화형 세션에서 `/effort` 실행 또는 `--effort`로 시작)을 할 때까지 세션 전체에 유지됩니다.

472

473`low`, `medium`, `high` 및 `xhigh`는 대화형 세션에서 설정할 때 세션 전체에 유지됩니다. {/* min-version: 2.1.205 */}[비대화형 모드](/ko/headless)에서 `/effort`로 설정된 수준은 `-p` 플래그를 사용하여 현재 세션에만 적용되며 기본값으로 저장되지 않습니다. 비대화형 `/effort`는 또한 위의 모델 기본값 보유를 해제할 수 없습니다: Fable 5, Opus 4.8 및 Opus 4.7에서 `Not applied`를 보고하고 세션은 모델의 기본 노력에 유지되므로 대신 시작 시 `--effort`를 전달하세요. `max`는 토큰 지출에 제약이 없어 가장 깊은 추론을 제공하며 현재 세션에만 적용됩니다. 단, `CLAUDE_CODE_EFFORT_LEVEL` 환경 변수를 통해 설정된 경우는 예외입니다.

474

475`/effort` 메뉴는 또한 `ultracode`를 제공합니다. Ultracode는 모델 노력 수준이 아닌 Claude Code 설정입니다: 모델에 `xhigh`를 전송하고 추가로 Claude가 실질적인 작업을 위해 [동적 워크플로우](/ko/workflows)를 조율하도록 합니다. 현재 세션에만 적용됩니다.

433 476

434`low`, `medium`, `high` 및 `xhigh`는 세션 전체에 유지됩니다. `max`는 토큰 지출에 제약이 없어 가장 깊은 추론을 제공하며 현재 세션에만 적용됩니다. 단, `CLAUDE_CODE_EFFORT_LEVEL` 환경 변수를 통해 설정된 경우는 예외입니다.477다음 중 하나를 통해 ultracode를 켤 수 있습니다:

435 478

436`/effort` 메뉴는 또한 `ultracode`를 제공합니다. Ultracode는 모델 노력 수준이 아닌 Claude Code 설정입니다: 모델에 `xhigh`를 전송하고 추가로 Claude가 실질적인 작업을 위해 [동적 워크플로우](/ko/workflows)를 조율하도록 합니다. 현재 세션에만 적용됩니다. `/effort`를 통해 설정하거나, `--settings`를 통해 `"ultracode": true`를 전달하거나, Agent SDK 제어 요청을 통해 설정합니다. 이는 `effortLevel` 설정, `--effort` 플래그 또는 `CLAUDE_CODE_EFFORT_LEVEL`의 일부가 아닙니다.479* **`/effort`**: `/effort ultracode`를 실행하거나 메뉴에서 선택

480* **`--effort` 플래그**: `claude --effort ultracode`로 시작하면 `xhigh` 노력으로 세션을 시작하고 ultracode를 켭니다

481* **`--settings` 또는 Agent SDK 제어 요청**: `"ultracode": true`를 전달합니다. [`applyFlagSettings()`](/ko/agent-sdk/typescript#applyflagsettings) 요청도 `effortLevel: "ultracode"`를 허용합니다

482

483`--effort` 플래그 또는 Agent SDK `effortLevel` 값에 `ultracode`를 전달하려면 Claude Code v2.1.203 이상이 필요합니다. v2.1.203 이전에는 `--effort ultracode`가 `Unknown --effort value 'ultracode'`를 출력했고 세션이 기본 노력으로 시작되었습니다.

484

485유지된 `effortLevel` 설정 및 `CLAUDE_CODE_EFFORT_LEVEL` 환경 변수는 `ultracode`를 허용하지 않습니다.

486

487ultracode를 사용할 수 없을 때(예: [워크플로우가 꺼져 있을 때](/ko/workflows#turn-workflows-off)) `--effort ultracode`는 `xhigh` 노력만 설정합니다.

437 488

438<h4 id="choose-an-effort-level">489<h4 id="choose-an-effort-level">

439 노력 수준 선택490 노력 수준 선택

590 타사 배포를 위한 모델 고정641 타사 배포를 위한 모델 고정

591</h3>642</h3>

592 643

593[Bedrock](/ko/amazon-bedrock), [Vertex AI](/ko/google-vertex-ai), [Foundry](/ko/microsoft-foundry) 또는 [Claude Platform on AWS](/ko/claude-platform-on-aws)를 통해 Claude Code를 배포할 때 사용자에게 롤아웃하기 전에 모델 버전을 고정합니다.644[Amazon Bedrock](/ko/amazon-bedrock), [Google Cloud의 Agent Platform](/ko/google-vertex-ai), [Microsoft Foundry](/ko/microsoft-foundry) 또는 [Claude Platform on AWS](/ko/claude-platform-on-aws)를 통해 Claude Code를 배포할 때 사용자에게 롤아웃하기 전에 모델 버전을 고정합니다.

594 645

595고정하지 않으면 Claude Code는 `fable`, `opus`, `sonnet`, `haiku`와 같은 모델 별칭을 사용하며, 이는 각 제공자에 대한 기본 제공 기본 모델 ID로 확인됩니다. 해당 기본값은 최신 Anthropic 릴리스보다 뒤떨어질 수 있으며, 가리키는 모델이 사용자 계정에서 아직 활성화되지 않았을 수 있습니다. 기본값을 사용할 수 없으면 Bedrock 및 Vertex AI 사용자는 공지를 보고 해당 세션에 대해 이전 버전으로 폴백되며, Foundry 사용자는 Foundry에 동등한 시작 확인이 없기 때문에 오류를 봅니다.646고정하지 않으면 Claude Code는 `fable`, `opus`, `sonnet`, `haiku`와 같은 모델 별칭을 사용하며, 이는 각 제공자에 대한 기본 제공 기본 모델 ID로 확인됩니다. 해당 기본값은 최신 Anthropic 릴리스보다 뒤떨어질 수 있으며, 가리키는 모델이 사용자 계정에서 아직 활성화되지 않았을 수 있습니다. 기본값을 사용할 수 없으면 Amazon Bedrock 및 Google Cloud의 Agent Platform 사용자는 공지를 보고 해당 세션에 대해 이전 버전으로 폴백되며, Microsoft Foundry 사용자는 Microsoft Foundry에 동등한 시작 확인이 없기 때문에 오류를 봅니다.

596 647

597<Warning>648<Warning>

598 초기 설정의 일부로 모델 환경 변수를 특정 버전 ID로 설정합니다. 고정하면 사용자가 새 모델로 이동할 시기를 제어할 수 있습니다.649 초기 설정의 일부로 모델 환경 변수를 특정 버전 ID로 설정합니다. 고정하면 사용자가 새 모델로 이동할 시기를 제어할 수 있습니다.

601제공자에 대한 버전별 모델 ID와 함께 다음 환경 변수를 사용합니다:652제공자에 대한 버전별 모델 ID와 함께 다음 환경 변수를 사용합니다:

602 653

603| 제공자 | 예시 |654| 제공자 | 예시 |

604| :-------- | :------------------------------------------------------------------- |655| :--------------------------- | :------------------------------------------------------------------- |

608 659

609`ANTHROPIC_DEFAULT_FABLE_MODEL`, `ANTHROPIC_DEFAULT_SONNET_MODEL`, `ANTHROPIC_DEFAULT_HAIKU_MODEL`에 대해 동일한 패턴을 적용합니다. 모든 제공자의 현재 및 레거시 모델 ID는 [모델 개요](https://platform.claude.com/docs/en/about-claude/models/overview)를 참조하세요. 사용자를 새 모델 버전으로 업그레이드하려면 이러한 환경 변수를 업데이트하고 다시 배포합니다.660`ANTHROPIC_DEFAULT_FABLE_MODEL`, `ANTHROPIC_DEFAULT_SONNET_MODEL`, `ANTHROPIC_DEFAULT_HAIKU_MODEL`에 대해 동일한 패턴을 적용합니다. 모든 제공자의 현재 및 레거시 모델 ID는 [모델 개요](https://platform.claude.com/docs/en/about-claude/models/overview)를 참조하세요. 사용자를 새 모델 버전으로 업그레이드하려면 이러한 환경 변수를 업데이트하고 다시 배포합니다.

610 661

618 669

619* Claude Code는 모델 ID를 제공자에게 보내기 전에 접미사를 제거합니다.670* Claude Code는 모델 ID를 제공자에게 보내기 전에 접미사를 제거합니다.

620* 기본 모델이 1M 컨텍스트를 [지원할 때만](https://platform.claude.com/docs/en/build-with-claude/context-windows#1m-token-context-window) `[1m]`을 추가합니다.671* 기본 모델이 1M 컨텍스트를 [지원할 때만](https://platform.claude.com/docs/en/build-with-claude/context-windows#1m-token-context-window) `[1m]`을 추가합니다.

621* 접미사는 모델별이 아닌 변수별로 읽혀집니다. Bedrock, Vertex 및 Foundry에서 한 변수의 `[1m]` 없는 모델 ID는 다른 변수가 접미사와 함께 동일한 모델을 설정하더라도 200K 컨텍스트를 사용합니다. Sonnet 5는 항상 이러한 제공자에서 1M 윈도우로 실행되며 접미사가 필요하지 않습니다.672* 접미사는 모델별이 아닌 변수별로 읽혀집니다. Amazon Bedrock, Google Cloud의 Agent Platform 및 Microsoft Foundry에서 한 변수의 `[1m]` 없는 모델 ID는 다른 변수가 접미사와 함께 동일한 모델을 설정하더라도 200K 컨텍스트를 사용합니다. Sonnet 5는 항상 이러한 제공자에서 1M 윈도우로 실행되며 접미사가 필요하지 않습니다.

622 673

623<Note>674<Note>

624 `availableModels` 허용 목록은 타사 제공자를 사용할 때도 적용됩니다. [MDM 또는 관리 설정 파일](/ko/settings#settings-files)을 통해 전달된 `availableModels` 허용 목록은 여전히 타사 제공자를 사용할 때 적용됩니다. [서버 관리 설정은 그곳에 전달되지 않습니다](/ko/server-managed-settings#platform-availability). 필터링은 `opus`와 같은 모델 별칭, `claude-opus-4-8`과 같은 버전 접두사 또는 전체 제공자 형식 모델 ID와 일치합니다. `us.anthropic.`과 같은 제공자별 접두사는 제거되지 않으므로 특정 모델을 허용하려면 선택기가 표시하는 것과 동일한 제공자 형식 ID를 나열하거나 [`modelOverrides`](#override-model-ids-per-version)를 통해 매핑합니다. 모든 `[1m]` 접미사는 허용 목록 항목과 요청된 모델 모두에서 제거되어 일치합니다.675 `availableModels` 허용 목록은 타사 제공자를 사용할 때도 적용됩니다. [MDM 또는 관리 설정 파일](/ko/settings#settings-files)을 통해 전달된 `availableModels` 허용 목록은 여전히 타사 제공자를 사용할 때 적용됩니다. [서버 관리 설정은 그곳에 전달되지 않습니다](/ko/server-managed-settings#platform-availability). 필터링은 `opus`와 같은 모델 별칭, `claude-opus-4-8`과 같은 버전 접두사 또는 전체 제공자 형식 모델 ID와 일치합니다. `us.anthropic.`과 같은 제공자별 접두사는 제거되지 않으므로 특정 모델을 허용하려면 선택기가 표시하는 것과 동일한 제공자 형식 ID를 나열하거나 [`modelOverrides`](#override-model-ids-per-version)를 통해 매핑합니다. 모든 `[1m]` 접미사는 허용 목록 항목과 요청된 모델 모두에서 제거되어 일치합니다.

630 681

631타사 제공자에서 모델을 고정하면 제공자별 ID가 `/model` 선택기에 그대로 나타나고 Claude Code는 모델이 지원하는 기능을 인식하지 못할 수 있습니다. 각 고정된 모델에 대한 동반 환경 변수로 표시 이름과 기능을 선언할 수 있습니다.682타사 제공자에서 모델을 고정하면 제공자별 ID가 `/model` 선택기에 그대로 나타나고 Claude Code는 모델이 지원하는 기능을 인식하지 못할 수 있습니다. 각 고정된 모델에 대한 동반 환경 변수로 표시 이름과 기능을 선언할 수 있습니다.

632 683

633이러한 변수는 Bedrock, Vertex AI 및 Foundry와 같은 타사 제공자에서 적용됩니다. `_NAME` 및 `_DESCRIPTION` 변수는 `ANTHROPIC_BASE_URL`이 [LLM gateway](/ko/llm-gateway)를 가리킬 때도 적용됩니다. `api.anthropic.com`에 직접 연결할 때는 영향을 주지 않습니다.684이러한 변수는 Amazon Bedrock, Google Cloud의 Agent Platform 및 Microsoft Foundry와 같은 타사 제공자에서 적용됩니다. `_NAME` 및 `_DESCRIPTION` 변수는 `ANTHROPIC_BASE_URL`이 [LLM gateway](/ko/llm-gateway)를 가리킬 때도 적용됩니다. `api.anthropic.com`에 직접 연결할 때는 영향을 주지 않습니다.

634 685

635| 환경 변수 | 설명 |686| 환경 변수 | 설명 |

636| ----------------------------------------------------- | ------------------------------------------------------------------------------ |687| ----------------------------------------------------- | ------------------------------------------------------------------------------ |

640 691

641동일한 `_NAME`, `_DESCRIPTION` 및 `_SUPPORTED_CAPABILITIES` 접미사는 `ANTHROPIC_DEFAULT_SONNET_MODEL`, `ANTHROPIC_DEFAULT_HAIKU_MODEL`, `ANTHROPIC_DEFAULT_FABLE_MODEL` 및 `ANTHROPIC_CUSTOM_MODEL_OPTION`에 사용 가능합니다.692동일한 `_NAME`, `_DESCRIPTION` 및 `_SUPPORTED_CAPABILITIES` 접미사는 `ANTHROPIC_DEFAULT_SONNET_MODEL`, `ANTHROPIC_DEFAULT_HAIKU_MODEL`, `ANTHROPIC_DEFAULT_FABLE_MODEL` 및 `ANTHROPIC_CUSTOM_MODEL_OPTION`에 사용 가능합니다.

642 693

643Claude Code는 모델 ID를 알려진 패턴과 비교하여 [노력 수준](#adjust-effort-level) 및 [확장 사고](#extended-thinking)와 같은 기능을 활성화합니다. Bedrock ARN 또는 사용자 정의 배포 이름과 같은 제공자별 ID는 종종 이러한 패턴과 일치하지 않아 지원되는 기능이 비활성화됩니다. `_SUPPORTED_CAPABILITIES`를 설정하여 Claude Code에 모델이 실제로 지원하는 기능을 알립니다:694Claude Code는 모델 ID를 알려진 패턴과 비교하여 [노력 수준](#adjust-effort-level) 및 [확장 사고](#extended-thinking)와 같은 기능을 활성화합니다. Amazon Bedrock ARN 또는 사용자 정의 배포 이름과 같은 제공자별 ID는 종종 이러한 패턴과 일치하지 않아 지원되는 기능이 비활성화됩니다. `_SUPPORTED_CAPABILITIES`를 설정하여 Claude Code에 모델이 실제로 지원하는 기능을 알립니다:

644 695

645| 기능 값 | 활성화 |696| 기능 값 | 활성화 |

646| ---------------------- | -------------------------------------------- |697| ---------------------- | -------------------------------------------- |

653 704

654`_SUPPORTED_CAPABILITIES`가 설정되면 나열된 기능이 활성화되고 나열되지 않은 기능은 일치하는 고정된 모델에 대해 비활성화됩니다. 변수가 설정되지 않으면 Claude Code는 모델 ID를 기반으로 한 기본 제공 감지로 폴백합니다.705`_SUPPORTED_CAPABILITIES`가 설정되면 나열된 기능이 활성화되고 나열되지 않은 기능은 일치하는 고정된 모델에 대해 비활성화됩니다. 변수가 설정되지 않으면 Claude Code는 모델 ID를 기반으로 한 기본 제공 감지로 폴백합니다.

655 706

656이 예시는 Opus를 Bedrock 사용자 정의 모델 ARN에 고정하고, 친화적인 이름을 설정하며, 기능을 선언합니다:707이 예시는 Opus를 Amazon Bedrock 사용자 정의 모델 ARN에 고정하고, 친화적인 이름을 설정하며, 기능을 선언합니다:

657 708

658```bash theme={null}709```bash theme={null}

659export ANTHROPIC_DEFAULT_OPUS_MODEL='arn:aws:bedrock:us-east-1:123456789012:custom-model/abc'710export ANTHROPIC_DEFAULT_OPUS_MODEL='arn:aws:bedrock:us-east-1:123456789012:custom-model/abc'

670 721

671`modelOverrides`는 개별 Anthropic 모델 ID를 Claude Code가 제공자의 API에 보내는 제공자별 문자열에 매핑합니다. 사용자가 `/model` 선택기에서 매핑된 모델을 선택하면 Claude Code는 기본 제공 기본값 대신 구성된 값을 사용합니다.722`modelOverrides`는 개별 Anthropic 모델 ID를 Claude Code가 제공자의 API에 보내는 제공자별 문자열에 매핑합니다. 사용자가 `/model` 선택기에서 매핑된 모델을 선택하면 Claude Code는 기본 제공 기본값 대신 구성된 값을 사용합니다.

672 723

673이를 통해 엔터프라이즈 관리자는 거버넌스, 비용 할당 또는 지역 라우팅을 위해 각 모델 버전을 특정 Bedrock 추론 프로필 ARN, Vertex AI 버전 이름 또는 Foundry 배포 이름으로 라우팅할 수 있습니다.724이를 통해 엔터프라이즈 관리자는 거버넌스, 비용 할당 또는 지역 라우팅을 위해 각 모델 버전을 특정 Amazon Bedrock 추론 프로필 ARN, Google Cloud의 Agent Platform 버전 이름 또는 Microsoft Foundry 배포 이름으로 라우팅할 수 있습니다.

674 725

675[설정 파일](/ko/settings#settings-files)에서 `modelOverrides`를 설정합니다:726[설정 파일](/ko/settings#settings-files)에서 `modelOverrides`를 설정합니다:

676 727

686 737

687키는 [모델 개요](https://platform.claude.com/docs/en/about-claude/models/overview)에 나열된 Anthropic 모델 ID여야 합니다. 날짜가 지정된 모델 ID의 경우 날짜 접미사를 정확히 표시된 대로 포함합니다. 알 수 없는 키는 무시됩니다.738키는 [모델 개요](https://platform.claude.com/docs/en/about-claude/models/overview)에 나열된 Anthropic 모델 ID여야 합니다. 날짜가 지정된 모델 ID의 경우 날짜 접미사를 정확히 표시된 대로 포함합니다. 알 수 없는 키는 무시됩니다.

688 739

689재정의는 `/model` 선택기의 각 항목을 지원하는 기본 제공 모델 ID를 대체합니다. Bedrock에서 재정의는 Claude Code가 시작 시 자동으로 발견하는 모든 추론 프로필보다 우선합니다. `ANTHROPIC_MODEL`, `--model` 또는 `ANTHROPIC_DEFAULT_*_MODEL` 환경 변수를 통해 직접 제공하는 값은 제공자에게 그대로 전달되며 `modelOverrides`로 변환되지 않습니다.740재정의는 `/model` 선택기의 각 항목을 지원하는 기본 제공 모델 ID를 대체합니다. Amazon Bedrock에서 `modelOverrides` 항목은 Claude Code가 시작 시 자동으로 발견하는 모든 추론 프로필보다 우선합니다. Claude Code는 Amazon Bedrock, Google Cloud의 Agent Platform 및 [Mantle](/ko/amazon-bedrock#use-the-mantle-endpoint)에서 `modelOverrides` 항목이 없는 Anthropic 모델 ID를 제공자가 해당 버전을 지원할 때 `/model` 선택기 행과 동일한 제공자별 ID로 확인합니다. Mantle은 버전의 부분 집합을 지원합니다. 해당 부분 집합 외의 Anthropic 모델 ID의 경우 Claude Code는 `modelOverrides` 항목이 이를 포함하지 않는 한 원본 ID를 Mantle에 보냅니다. v2.1.200 이전에는 `--model` 및 환경 변수 값이 재정의 맵을 거치지 않고 제공자에게 그대로 도달했습니다.

690 741

691`modelOverrides`는 `availableModels`과 함께 작동합니다. 허용 목록은 재정의 값이 아닌 Anthropic 모델 ID에 대해 평가되므로 `availableModels`의 `"opus"`와 같은 항목은 Opus 버전이 ARN에 매핑되어도 계속 일치합니다. `enforceAvailableModels`이 관리 설정에서 설정되면 강제된 기본값은 [가장 높은 우선순위 관리 소스](/ko/server-managed-settings#settings-precedence)에서만 `modelOverrides`를 통해 확인됩니다. 추론 프로필 ARN에 고정된 버전과 같은 관리자의 매핑이 강제된 기본값에서 인정됩니다. 사용자 또는 프로젝트 설정의 재정의는 이에 영향을 주지 않습니다.742`modelOverrides`는 `availableModels`과 함께 작동합니다. 허용 목록은 재정의 값이 아닌 Anthropic 모델 ID에 대해 평가되므로 `availableModels`의 `"opus"`와 같은 항목은 Opus 버전이 ARN에 매핑되어도 계속 일치합니다. `enforceAvailableModels`이 관리 설정에서 설정되면 강제된 기본값은 [가장 높은 우선순위 관리 소스](/ko/server-managed-settings#settings-precedence)에서만 `modelOverrides`를 통해 확인됩니다. 추론 프로필 ARN에 고정된 버전과 같은 관리자의 매핑이 강제된 기본값에서 인정됩니다. 사용자 또는 프로젝트 설정의 재정의는 이에 영향을 주지 않습니다.

692 743

744{/* min-version: 2.1.200 */}`availableModels`이 [관리 설정](/ko/settings#settings-files)에서 설정되면 `--model` 또는 위의 환경 변수를 통해 직접 전달된 Anthropic 모델 ID에는 해당 관리 소스의 `modelOverrides`만 적용됩니다. Claude Code는 사용자 또는 프로젝트 설정의 해당 ID에 대한 재정의를 무시하며, 관리 목록이 제외하는 ID를 어떤 설정 소스의 `modelOverrides`를 통해서도 확인하지 않습니다. 이 관리 소스 제한은 Claude Code v2.1.200 이상이 필요합니다. 차단된 ID가 처리되는 방식은 [모델 선택 제한](#restrict-model-selection)을 참조하세요.

745

693<h3 id="prompt-caching-configuration">746<h3 id="prompt-caching-configuration">

694 Prompt caching 구성747 Prompt caching 구성

695</h3>748</h3>

monitoring-usage.md +12 −6

Details

191**`claude_code.llm_request`**191**`claude_code.llm_request`**

192 192

193| 속성 | 설명 | 게이트 대상 |193| 속성 | 설명 | 게이트 대상 |

194| -------------------------------- | ---------------------------------------------------------------------------------------------------------- | ------ |194| -------------------------------- | ---------------------------------------------------------------------------------------------------------- | ----------------------- |

201| `workflow.run_id` | 이 에이전트를 생성한 [Workflow](/ko/workflows) 도구 실행의 실행 식별자 (접두사 `wf_`). 워크플로우에 의해 생성되지 않은 에이전트의 경우 없음 | |

202| `workflow.name` | 이 에이전트를 생성한 워크플로우의 이름. 사용자 작성 이름은 게이트가 설정되지 않으면 `custom`으로 대체됩니다 | `OTEL_LOG_TOOL_DETAILS` |

233| `workflow.run_id` | 이 에이전트를 생성한 Workflow 도구 실행의 실행 식별자 (접두사 `wf_`). 워크플로우에 의해 생성되지 않은 에이전트의 경우 없음 | |

234| `workflow.name` | 이 에이전트를 생성한 워크플로우의 이름. 사용자 작성 이름은 게이트가 설정되지 않으면 `custom`으로 대체됩니다 | `OTEL_LOG_TOOL_DETAILS` |

231| `tool_use_id` | 이 호출에 대한 모델의 `tool_use` 블록 ID. [tool\_result](#tool-result-event) 및 [tool\_decision](#tool-decision-event) 이벤트의 `tool_use_id`와 훅 페이로드의 `tool_use_id`와 일치하므로 스팬을 해당 레코드에 조인할 수 있습니다 | |235| `tool_use_id` | 이 호출에 대한 모델의 `tool_use` 블록 ID. [tool\_result](#tool-result-event) 및 [tool\_decision](#tool-decision-event) 이벤트의 `tool_use_id`와 훅 페이로드의 `tool_use_id`와 일치하므로 스팬을 해당 레코드에 조인할 수 있습니다 | |

309 313

310도우미가 실패하거나 이러한 요구 사항을 충족하지 않는 출력을 인쇄하면 Claude Code는 다음에서 오류를 보고합니다:314도우미가 실패하거나 이러한 요구 사항을 충족하지 않는 출력을 인쇄하면 Claude Code는 다음에서 오류를 보고합니다:

311 315

312* `/doctor` 출력316* `/status` 출력

313* [`--debug`](/ko/cli-reference#cli-flags)로 실행하거나 세션에서 `/debug`를 실행한 후의 디버그 로그317* [`--debug`](/ko/cli-reference#cli-flags)로 실행하거나 세션에서 `/debug`를 실행한 후의 디버그 로그

314* `-p`로 시작된 비대화형 세션의 stderr318* `-p`로 시작된 비대화형 세션의 stderr

315 319

443 447

444* `prompt.id`: 사용자 프롬프트를 다음 프롬프트까지의 모든 후속 이벤트와 상관시키는 UUID입니다. [이벤트 상관 속성](#event-correlation-attributes)을 참조하세요.448* `prompt.id`: 사용자 프롬프트를 다음 프롬프트까지의 모든 후속 이벤트와 상관시키는 UUID입니다. [이벤트 상관 속성](#event-correlation-attributes)을 참조하세요.

445* `workspace.host_paths`: 데스크톱 앱에서 선택한 호스트 작업 공간 디렉토리 (문자열 배열)449* `workspace.host_paths`: 데스크톱 앱에서 선택한 호스트 작업 공간 디렉토리 (문자열 배열)

450* `workflow.run_id`: API 및 [Workflow](/ko/workflows) 도구 실행에 속하는 에이전트가 내보낸 도구 이벤트의 실행 식별자 (접두사 `wf_`). 하나의 `workflow.run_id`로 이벤트를 필터링하면 해당 실행의 API 요청 및 도구 결과를 재구성합니다. 식별자는 워크플로우 스크립트가 생성하는 에이전트 및 이들이 차례로 생성하는 모든 에이전트 (예: 스킬 호출)를 포함합니다. Workflow 도구 결과에서 보고된 실행 식별자와 일치합니다. 다른 모든 이벤트에는 없습니다. {/* min-version: 2.1.202 */}Claude Code v2.1.202 이상 필요

451* `workflow.name`: 워크플로우의 이름 (스크립트의 `meta.name`), `workflow.run_id`와 함께 내보내집니다. 기본 제공 워크플로우 이름은 수정되지 않은 기본 제공 스크립트를 실행할 때 그대로 나타납니다. 기본 제공 스크립트의 편집된 복사본을 포함한 사용자 작성 이름은 `OTEL_LOG_TOOL_DETAILS=1`이 설정되지 않으면 `custom`으로 대체됩니다. {/* min-version: 2.1.202 */}Claude Code v2.1.202 이상 필요

446 452

447<h3 id="metrics">453<h3 id="metrics">

448 메트릭454 메트릭

884 내부 오류 이벤트890 내부 오류 이벤트

885</h4>891</h4>

886 892

887Claude Code가 예상치 못한 내부 오류를 포착할 때 기록됩니다. 오류 클래스 이름과 errno 스타일 코드만 기록됩니다. 오류 메시지 및 스택 추적은 포함되지 않습니다. 이 이벤트는 Bedrock, Vertex 또는 Foundry에 대해 실행하거나 `DISABLE_ERROR_REPORTING`이 설정되어 있을 때는 내보내지지 않습니다.893Claude Code가 예상치 못한 내부 오류를 포착할 때 기록됩니다. 오류 클래스 이름과 errno 스타일 코드만 기록됩니다. 오류 메시지 및 스택 추적은 포함되지 않습니다. 이 이벤트는 Amazon Bedrock, Google Cloud의 Agent Platform 또는 Microsoft Foundry에 대해 실행하거나 `DISABLE_ERROR_REPORTING`이 설정되어 있을 때는 내보내지지 않습니다.

888 894

889**이벤트 이름**: `claude_code.internal_error`895**이벤트 이름**: `claude_code.internal_error`

890 896

1163* `skill.name`, `plugin.name` 및 `agent.name` 속성을 통해 특정 스킬, 플러그인 또는 서브에이전트 유형에 지출 귀속1169* `skill.name`, `plugin.name` 및 `agent.name` 속성을 통해 특정 스킬, 플러그인 또는 서브에이전트 유형에 지출 귀속

1164 1170

1165<Note>1171<Note>

1166 비용 메트릭은 근사값입니다. 공식 청구 데이터는 API 제공자(Claude Console, Amazon Bedrock 또는 Google Cloud Vertex)를 참조하세요.1172 비용 메트릭은 근사값입니다. 공식 청구 데이터는 API 제공자(Claude Console, Amazon Bedrock 또는 Google Cloud의 Agent Platform)를 참조하세요.

1167</Note>1173</Note>

1168 1174

1169<h3 id="alerting-and-segmentation">1175<h3 id="alerting-and-segmentation">

1217 1223

1218MCP 도구 호출, Bash 명령 및 파일 편집은 따라서 세션을 시작한 개발자에게 귀속됩니다. Claude Code는 별도의 서비스 계정으로 작동하지 않습니다. 각 이벤트에 기록된 ID는 개발자 자신의 Claude 계정이거나 [Claude 앱 게이트웨이](/ko/claude-apps-gateway) 세션의 개발자 IdP 신원입니다.1224MCP 도구 호출, Bash 명령 및 파일 편집은 따라서 세션을 시작한 개발자에게 귀속됩니다. Claude Code는 별도의 서비스 계정으로 작동하지 않습니다. 각 이벤트에 기록된 ID는 개발자 자신의 Claude 계정이거나 [Claude 앱 게이트웨이](/ko/claude-apps-gateway) 세션의 개발자 IdP 신원입니다.

1219 1225

1220Claude Code가 직접 API 키로 인증하거나 Bedrock, Vertex AI 또는 Microsoft Foundry에 대해 인증할 때 세션에 Claude 계정이 없으며 `user.id` 및 `session.id`만 채워집니다. 이러한 배포에서는 `OTEL_RESOURCE_ATTRIBUTES`를 사용하여 사용자 ID를 직접 첨부하고, [관리 설정](#administrator-configuration) 파일 또는 시작 래퍼를 통해 사용자별로 설정합니다. Claude 앱 게이트웨이 세션은 이 중 어느 것도 필요하지 않습니다: CLI는 [표준 속성](#standard-attributes)에 설명된 대로 IdP 신원을 자동으로 스탬프합니다.1226Claude Code가 직접 API 키로 인증하거나 Amazon Bedrock, Google Cloud의 Agent Platform 또는 Microsoft Foundry에 대해 인증할 때 세션에 Claude 계정이 없으며 `user.id` 및 `session.id`만 채워집니다. 이러한 배포에서는 `OTEL_RESOURCE_ATTRIBUTES`를 사용하여 사용자 ID를 직접 첨부하고, [관리 설정](#administrator-configuration) 파일 또는 시작 래퍼를 통해 사용자별로 설정합니다. Claude 앱 게이트웨이 세션은 이 중 어느 것도 필요하지 않습니다: CLI는 [표준 속성](#standard-attributes)에 설명된 대로 IdP 신원을 자동으로 스탬프합니다.

1221 1227

1222```bash theme={null}1228```bash theme={null}

1223export OTEL_RESOURCE_ATTRIBUTES="enduser.id=jdoe@example.com,enduser.directory_id=S-1-5-21-..."1229export OTEL_RESOURCE_ATTRIBUTES="enduser.id=jdoe@example.com,enduser.directory_id=S-1-5-21-..."

1352 Amazon Bedrock에서 Claude Code 모니터링1358 Amazon Bedrock에서 Claude Code 모니터링

1353</h2>1359</h2>

1354 1360

1355Amazon Bedrock의 Claude Code 사용 모니터링에 대한 자세한 지침은 [Claude Code 모니터링 구현 (Bedrock)](https://github.com/aws-solutions-library-samples/guidance-for-claude-code-with-amazon-bedrock/blob/main/assets/docs/MONITORING.md)을 참조하세요.1361Amazon Bedrock의 Claude Code 사용 모니터링에 대한 자세한 지침은 [Claude Code 모니터링 구현 (Amazon Bedrock)](https://github.com/aws-solutions-library-samples/guidance-for-claude-code-with-amazon-bedrock/blob/main/assets/docs/MONITORING.md)을 참조하세요.

network-config.md +3 −1

Details

110export CLAUDE_CODE_CLIENT_KEY_PASSPHRASE="your-passphrase"110export CLAUDE_CODE_CLIENT_KEY_PASSPHRASE="your-passphrase"

111```111```

112 112

113Claude Code는 시작 시 인증서 및 키 파일을 읽고, 설정을 적용할 때마다 다시 읽습니다. 여기에는 세션 중에 설정이 변경될 때도 포함됩니다. 인증서 및 키를 회전하려면 동일한 경로의 파일을 교체하면 됩니다.

114

113<h2 id="network-access-requirements">115<h2 id="network-access-requirements">

114 네트워크 액세스 요구 사항116 네트워크 액세스 요구 사항

115</h2>117</h2>

131 133

132Claude Code는 기본적으로 선택적 운영 원격 분석을 전송하며, 환경 변수를 사용하여 이를 비활성화할 수 있습니다. 허용 목록을 최종 확정하기 전에 원격 분석을 비활성화하는 방법은 [원격 분석 서비스](/ko/data-usage#telemetry-services)를 참조하십시오.134Claude Code는 기본적으로 선택적 운영 원격 분석을 전송하며, 환경 변수를 사용하여 이를 비활성화할 수 있습니다. 허용 목록을 최종 확정하기 전에 원격 분석을 비활성화하는 방법은 [원격 분석 서비스](/ko/data-usage#telemetry-services)를 참조하십시오.

133 135

134[Amazon Bedrock](/ko/amazon-bedrock), [Google Vertex AI](/ko/google-vertex-ai), [Microsoft Foundry](/ko/microsoft-foundry) 또는 로그인한 [Claude 앱 게이트웨이](/ko/claude-apps-gateway) 세션을 사용할 때 모델 트래픽 및 인증은 `api.anthropic.com`, `claude.ai` 또는 `platform.claude.com` 대신 공급자 또는 게이트웨이로 이동합니다. WebFetch 도구는 [설정](/ko/settings)에서 `skipWebFetchPreflight: true`를 설정하지 않는 한 [도메인 안전 검사](/ko/data-usage#webfetch-domain-safety-check)를 위해 여전히 `api.anthropic.com`을 호출합니다.136[Amazon Bedrock](/ko/amazon-bedrock), [Google Cloud의 Agent Platform](/ko/google-vertex-ai), [Microsoft Foundry](/ko/microsoft-foundry) 또는 로그인한 [Claude 앱 게이트웨이](/ko/claude-apps-gateway) 세션을 사용할 때 모델 트래픽 및 인증은 `api.anthropic.com`, `claude.ai` 또는 `platform.claude.com` 대신 공급자 또는 게이트웨이로 이동합니다. WebFetch 도구는 [설정](/ko/settings)에서 `skipWebFetchPreflight: true`를 설정하지 않는 한 [도메인 안전 검사](/ko/data-usage#webfetch-domain-safety-check)를 위해 여전히 `api.anthropic.com`을 호출합니다.

135 137

136[웹의 Claude Code](/ko/claude-code-on-the-web) 및 [Code Review](/ko/code-review)는 Anthropic 관리 인프라에서 리포지토리에 연결합니다. GitHub Enterprise Cloud 조직이 IP 주소로 액세스를 제한하는 경우 [설치된 GitHub Apps에 대한 IP 허용 목록 상속 활성화](https://docs.github.com/en/enterprise-cloud@latest/organizations/keeping-your-organization-secure/managing-security-settings-for-your-organization/managing-allowed-ip-addresses-for-your-organization#allowing-access-by-github-apps)를 수행하십시오. Claude GitHub App은 IP 범위를 등록하므로 이 설정을 활성화하면 수동 구성 없이 액세스할 수 있습니다. 대신 [범위를 허용 목록에 수동으로 추가](https://docs.github.com/en/enterprise-cloud@latest/organizations/keeping-your-organization-secure/managing-security-settings-for-your-organization/managing-allowed-ip-addresses-for-your-organization#adding-an-allowed-ip-address)하거나 다른 방화벽을 구성하려면 [Anthropic API IP 주소](https://platform.claude.com/docs/en/api/ip-addresses)를 참조하십시오.138[웹의 Claude Code](/ko/claude-code-on-the-web) 및 [Code Review](/ko/code-review)는 Anthropic 관리 인프라에서 리포지토리에 연결합니다. GitHub Enterprise Cloud 조직이 IP 주소로 액세스를 제한하는 경우 [설치된 GitHub Apps에 대한 IP 허용 목록 상속 활성화](https://docs.github.com/en/enterprise-cloud@latest/organizations/keeping-your-organization-secure/managing-security-settings-for-your-organization/managing-allowed-ip-addresses-for-your-organization#allowing-access-by-github-apps)를 수행하십시오. Claude GitHub App은 IP 범위를 등록하므로 이 설정을 활성화하면 수동 구성 없이 액세스할 수 있습니다. 대신 [범위를 허용 목록에 수동으로 추가](https://docs.github.com/en/enterprise-cloud@latest/organizations/keeping-your-organization-secure/managing-security-settings-for-your-organization/managing-allowed-ip-addresses-for-your-organization#adding-an-allowed-ip-address)하거나 다른 방화벽을 구성하려면 [Anthropic API IP 주소](https://platform.claude.com/docs/en/api/ip-addresses)를 참조하십시오.

137 139

overview.md +2 −2

Details

12 시작하기12 시작하기

13</h2>13</h2>

14 14

15환경을 선택하여 시작하세요. 대부분의 환경에는 [Claude 구독](https://claude.com/pricing?utm_source=claude_code\&utm_medium=docs\&utm_content=overview_pricing) 또는 [Anthropic Console](https://console.anthropic.com/) 계정이 필요합니다. Terminal CLI 및 VS Code는 [타사 제공자](/ko/third-party-integrations)도 지원합니다.15Claude Code는 터미널, IDE 확장 프로그램, 데스크톱 앱 및 웹을 포함한 여러 환경에서 실행됩니다. 아래 탭에서 하나를 선택하여 시작하세요. 대부분의 환경에는 [Claude 구독](https://claude.com/pricing?utm_source=claude_code\&utm_medium=docs\&utm_content=overview_pricing) 또는 [Anthropic Console](https://console.anthropic.com/) 계정이 필요합니다. Terminal CLI 및 VS Code는 [타사 제공자](/ko/third-party-integrations)도 지원합니다.

16 16

17<Tabs>17<Tabs>

18 <Tab title="Terminal">18 <Tab title="Terminal">

221 모든 곳에서 Claude Code 사용221 모든 곳에서 Claude Code 사용

222</h2>222</h2>

223 223

224각 환경은 동일한 기본 Claude Code 엔진에 연결되므로 CLAUDE.md 파일, 설정 및 MCP 서버가 모든 환경에서 작동합니다.224각 [환경](/ko/glossary#surface)은 동일한 기본 Claude Code 엔진에 연결되므로 CLAUDE.md 파일, 설정 및 MCP 서버가 모든 환경에서 작동합니다.

225 225

226위의 [Terminal](/ko/quickstart), [VS Code](/ko/vs-code), [JetBrains](/ko/jetbrains), [Desktop](/ko/desktop) 및 [Web](/ko/claude-code-on-the-web) 환경 외에도 Claude Code는 CI/CD, 채팅 및 브라우저 워크플로우와 통합됩니다:226위의 [Terminal](/ko/quickstart), [VS Code](/ko/vs-code), [JetBrains](/ko/jetbrains), [Desktop](/ko/desktop) 및 [Web](/ko/claude-code-on-the-web) 환경 외에도 Claude Code는 CI/CD, 채팅 및 브라우저 워크플로우와 통합됩니다:

227 227

permission-modes.md +44 −18

Details

6 6

7> Claude가 파일을 편집하거나 명령을 실행하기 전에 승인을 요청하는지 여부를 제어합니다. CLI에서 Shift+Tab으로 모드를 순환하거나 VS Code, Desktop, claude.ai의 모드 선택기를 사용합니다.7> Claude가 파일을 편집하거나 명령을 실행하기 전에 승인을 요청하는지 여부를 제어합니다. CLI에서 Shift+Tab으로 모드를 순환하거나 VS Code, Desktop, claude.ai의 모드 선택기를 사용합니다.

8 8

9Claude가 파일을 편집하거나 셸 명령을 실행하거나 네트워크 요청을 할 때, 작업을 승인하도록 일시 중지하고 요청합니다. 권한 모드는 해당 일시 중지가 얼마나 자주 발생하는지를 제어합니다. 선택한 모드는 세션의 흐름을 형성합니다. 기본 모드는 각 작업을 검토하도록 하는 반면, 더 느슨한 모드는 Claude가 더 길게 중단 없이 작업하고 완료되면 보고하도록 합니다. 민감한 작업에는 더 많은 감시를 선택하거나, 방향을 신뢰할 때는 더 적은 중단을 선택합니다.9Claude가 파일을 편집하거나 셸 명령을 실행하거나 네트워크 요청을 할 때, 작업을 승인하도록 일시 중지하고 요청합니다. 권한 모드는 해당 일시 중지가 얼마나 자주 발생하는지를 제어합니다. 선택한 모드는 세션의 흐름을 형성합니다. 수동 모드는 각 작업을 검토하도록 하는 반면, 더 느슨한 모드는 Claude가 더 길게 중단 없이 작업하고 완료되면 보고하도록 합니다. 민감한 작업에는 더 많은 감시를 선택하거나, 방향을 신뢰할 때는 더 적은 중단을 선택합니다.

10 10

11<h2 id="available-modes">11<h2 id="available-modes">

12 사용 가능한 모드12 사용 가능한 모드

16 16

17| 모드 | 묻지 않고 실행되는 작업 | 최적 사용 사례 |17| 모드 | 묻지 않고 실행되는 작업 | 최적 사용 사례 |

18| :------------------------------------------------------------------ | :-------------------------------------------------------- | :----------------- |18| :------------------------------------------------------------------ | :-------------------------------------------------------- | :----------------- |

21| [`plan`](#analyze-before-you-edit-with-plan-mode) | 읽기만 | 변경하기 전에 코드베이스 탐색 |21| [`plan`](#analyze-before-you-edit-with-plan-mode) | 읽기만 | 변경하기 전에 코드베이스 탐색 |

25 25

26모든 작업을 검토하는 모드는 CLI, `claude --help`, VS Code 및 JetBrains 확장에서 **Manual**로 명명됩니다. 해당 구성 값은 `default`이며, 이는 hooks 및 SDK 통합이 사용하는 값입니다. CLI는 값을 입력하는 모든 곳에서 `manual`을 별칭으로 허용합니다. 예를 들어 `claude --permission-mode manual` 또는 `"defaultMode": "manual"`입니다. Manual 레이블과 `manual` 별칭은 Claude Code v2.1.200 이상이 필요합니다.

26`bypassPermissions`를 제외한 모든 모드에서 [보호된 경로](#protected-paths)에 대한 쓰기는 절대 자동 승인되지 않으며, 리포지토리 상태와 Claude의 자체 구성을 우발적인 손상으로부터 보호합니다.28`bypassPermissions`를 제외한 모든 모드에서 [보호된 경로](#protected-paths)에 대한 쓰기는 절대 자동 승인되지 않으며, 리포지토리 상태와 Claude의 자체 구성을 우발적인 손상으로부터 보호합니다.

27 29

28모드는 기본선을 설정합니다. 특정 도구를 사전 승인하거나 차단하기 위해 [권한 규칙](/ko/permissions#manage-permissions)을 위에 계층화합니다. 거부 규칙과 명시적 요청 규칙은 `bypassPermissions`를 포함한 모든 모드에서 적용됩니다. 허용 규칙은 다른 모든 것이 이미 승인되었기 때문에 해당 모드에서는 효과가 없습니다.30모드는 기본선을 설정합니다. 특정 도구를 사전 승인하거나 차단하기 위해 [권한 규칙](/ko/permissions#manage-permissions)을 위에 계층화합니다. 거부 규칙과 명시적 요청 규칙은 `bypassPermissions`를 포함한 모든 모드에서 적용됩니다. 허용 규칙은 다른 모든 것이 이미 승인되었기 때문에 해당 모드에서는 효과가 없습니다.

35 37

36<Tabs>38<Tabs>

37 <Tab title="CLI">39 <Tab title="CLI">

38 **세션 중**: `Shift+Tab`을 눌러 `default` → `acceptEdits` → `plan`을 순환합니다. 현재 모드는 상태 표시줄에 나타납니다. 모든 모드가 기본 순환에 있는 것은 아닙니다:40 **세션 중**: `Shift+Tab`을 눌러 `default` → `acceptEdits` → `plan`을 순환합니다. 현재 모드는 상태 표시줄에 나타납니다. {/* min-version: 2.1.203 */}수동 모드인 `default`는 순환에서 회색 `⏸ manual mode on` 배지를 표시합니다. v2.1.203 이전에는 상태 표시줄이 수동 모드에서 배지를 표시하지 않았습니다.

42 모든 모드가 기본 순환에 있는 것은 아닙니다:

39 43

40 * `auto`: 계정이 [자동 모드 요구 사항](#eliminate-prompts-with-auto-mode)을 충족할 때 나타나며, 자동 모드로 순환하면 확인 프롬프트 없이 모드를 전환합니다44 * `auto`: 계정이 [자동 모드 요구 사항](#eliminate-prompts-with-auto-mode)을 충족할 때 나타나며, 자동 모드로 순환하면 확인 프롬프트 없이 모드를 전환합니다

41 * `bypassPermissions`: `--permission-mode bypassPermissions`, `--dangerously-skip-permissions` 또는 `--allow-dangerously-skip-permissions`로 시작한 후 나타나며, `--allow-` 변형은 활성화하지 않고 순환에 모드를 추가합니다45 * `bypassPermissions`: `--permission-mode bypassPermissions`, `--dangerously-skip-permissions` 또는 `--allow-dangerously-skip-permissions`로 시작한 후 나타나며, `--allow-` 변형은 활성화하지 않고 순환에 모드를 추가합니다

70 모드 표시기는 이러한 레이블을 표시하며, 각각이 적용되는 모드에 매핑됩니다:74 모드 표시기는 이러한 레이블을 표시하며, 각각이 적용되는 모드에 매핑됩니다:

71 75

72 | UI 레이블 | 모드 |76 | UI 레이블 | 모드 |

~~73 | :------- | :------------------ |~~77 | :------ | :------------------ |

~~74 | 편집 전에 요청 | `default` |~~78 | 수동 | `default` |

75 | 자동으로 편집 | `acceptEdits` |79 | 자동으로 편집 | `acceptEdits` |

76 | 계획 모드 | `plan` |80 | 계획 모드 | `plan` |

77 | 자동 모드 | `auto` |81 | 자동 모드 | `auto` |

78 | 권한 무시 | `bypassPermissions` |82 | 권한 무시 | `bypassPermissions` |

79 83

84 v2.1.205 이전에는 확장이 `plan`을 계획 모드로, `auto`를 자동 모드로 레이블 지정했습니다.

80 자동 모드는 계정이 [자동 모드 섹션](#eliminate-prompts-with-auto-mode)에 나열된 모든 요구 사항을 충족할 때 모드 표시기에 나타납니다. `claudeCode.initialPermissionMode` 설정은 `auto`를 허용하지 않습니다. 기본적으로 자동 모드로 시작하려면 대신 [사용자 설정](/ko/settings#settings-files)에서 `defaultMode`를 설정합니다. Claude Code는 프로젝트 및 로컬 설정에서 `defaultMode: "auto"`를 무시합니다.86 자동 모드는 계정이 [자동 모드 섹션](#eliminate-prompts-with-auto-mode)에 나열된 모든 요구 사항을 충족할 때 모드 표시기에 나타납니다. `claudeCode.initialPermissionMode` 설정은 `auto`를 허용하지 않습니다. 기본적으로 자동 모드로 시작하려면 대신 [사용자 설정](/ko/settings#settings-files)에서 `defaultMode`를 설정합니다. Claude Code는 프로젝트 및 로컬 설정에서 `defaultMode: "auto"`를 무시합니다.

81 87

82 권한 무시는 모드 표시기에 나타나기 전에 확장 설정에서 **위험하게 권한 건너뛰기 허용** 토글이 필요합니다.88 권한 무시는 모드 표시기에 나타나기 전에 확장 설정에서 **위험하게 권한 건너뛰기 허용** 토글이 필요합니다.

95 <Tab title="Web and mobile">101 <Tab title="Web and mobile">

96 [claude.ai/code](https://claude.ai/code)의 프롬프트 상자 옆 모드 드롭다운 또는 모바일 앱을 사용합니다. 권한 프롬프트는 승인을 위해 claude.ai에 나타납니다. 어떤 모드가 나타나는지는 세션이 실행되는 위치에 따라 다릅니다:102 [claude.ai/code](https://claude.ai/code)의 프롬프트 상자 옆 모드 드롭다운 또는 모바일 앱을 사용합니다. 권한 프롬프트는 승인을 위해 claude.ai에 나타납니다. 어떤 모드가 나타나는지는 세션이 실행되는 위치에 따라 다릅니다:

97 103

98 * **[Claude Code on the web](/ko/claude-code-on-the-web)의 클라우드 세션**: 편집 자동 수락, 계획 모드 및 자동 모드. 편집 자동 수락은 `default` 모드에 해당합니다: 클라우드 환경은 모드에 관계없이 파일 편집을 사전 승인하므로, 드롭다운은 권한 요청 대신 편집 자동 수락을 표시합니다. 설정의 `defaultMode: "acceptEdits"`는 여전히 적용됩니다. 자동 모드는 조직이 허용하고 선택한 모델이 지원할 때만 나타납니다. 권한 무시는 사용할 수 없습니다.104 * **[Claude Code on the web](/ko/claude-code-on-the-web)의 클라우드 세션**: 편집 수락, 계획 모드 및 자동 모드. 편집 수락은 `default` 모드에 해당합니다: 클라우드 환경은 모드에 관계없이 파일 편집을 사전 승인하므로, 드롭다운은 수동 대신 편집 수락을 표시합니다. 클라우드 세션은 여전히 설정의 `defaultMode: "acceptEdits"`를 준수합니다. 자동 모드는 조직이 허용하고 선택한 모델이 지원할 때만 나타납니다. 권한 무시는 사용할 수 없습니다.

~~99 * **로컬 머신의 [원격 제어](/ko/remote-control) 세션**: 권한 요청, 편집 자동 수락 및 계획 모드. 자동 및 권한 무시는 사용할 수 없습니다.~~105 * **로컬 머신의 [원격 제어](/ko/remote-control) 세션**: 수동, 편집 수락 및 계획 모드. 앱에서 자동 또는 권한 무시를 선택할 수 없습니다. {/* min-version: 2.1.202 */}드롭다운은 로컬 세션이 있는 모드(터미널에서 설정된 모드 포함)를 표시하며, 앱 또는 터미널에서 모드가 변경될 때 업데이트됩니다. 한 가지 예외는 권한 무시입니다: 세션은 해당 모드를 claude.ai에 보고하지 않으므로, 터미널에서 전환해도 드롭다운이 표시하는 내용이 변경되지 않습니다. v2.1.202 이전에는 `/remote-control` 또는 `claude --remote-control`로 연결된 세션이 모드를 전혀 보고하지 않았으므로, claude.ai 및 모바일 앱이 세션이 있지 않은 모드를 표시할 수 있었습니다. 불일치는 레이블에만 영향을 미쳤습니다: Claude Code는 세션의 실제 모드에서 권한 프롬프트를 생성했으며 여전히 승인을 위해 앱에 나타났습니다.

100 106

101 원격 제어의 경우, 호스트를 시작할 때 시작 모드를 설정할 수도 있습니다:107 원격 제어의 경우, 호스트를 시작할 때 시작 모드를 설정할 수도 있습니다:

102 108

188 194

189* **플랜**: 모든 플랜.195* **플랜**: 모든 플랜.

190* **소유자**: Team 및 Enterprise에서, 소유자는 사용자가 켜기 전에 [Claude Code 관리자 설정](https://claude.ai/admin-settings/claude-code)에서 이를 활성화해야 합니다. 관리자는 [관리 설정](/ko/permissions#managed-settings)에서 `permissions.disableAutoMode`를 `"disable"`로 설정하여 이를 잠금할 수도 있습니다.196* **소유자**: Team 및 Enterprise에서, 소유자는 사용자가 켜기 전에 [Claude Code 관리자 설정](https://claude.ai/admin-settings/claude-code)에서 이를 활성화해야 합니다. 관리자는 [관리 설정](/ko/permissions#managed-settings)에서 `permissions.disableAutoMode`를 `"disable"`로 설정하여 이를 잠금할 수도 있습니다.

191* **모델**: Anthropic API에서 Claude Opus 4.6 이상 또는 Sonnet 4.6 이상. Amazon Bedrock, Google Cloud Vertex AI, Microsoft Foundry, 그리고 로그인한 [Claude 앱 게이트웨이](/ko/claude-apps-gateway) 세션에서는 Claude Sonnet 5, Opus 4.7, 및 Opus 4.8만 해당합니다. Sonnet 4.5, Opus 4.5, Haiku, claude-3 모델을 포함한 이전 모델은 어떤 제공자에서도 지원되지 않습니다.197* **모델**: Anthropic API에서 Claude Opus 4.6 이상 또는 Sonnet 4.6 이상. Amazon Bedrock, Google Cloud의 Agent Platform, Microsoft Foundry, 그리고 로그인한 [Claude 앱 게이트웨이](/ko/claude-apps-gateway) 세션에서는 Claude Sonnet 5, Opus 4.7, 및 Opus 4.8만 해당합니다. Sonnet 4.5, Opus 4.5, Haiku, claude-3 모델을 포함한 이전 모델은 어떤 제공자에서도 지원되지 않습니다.

192* **제공자**: Anthropic API에서 기본적으로 사용 가능합니다. Amazon Bedrock, Google Cloud Vertex AI, Microsoft Foundry, 그리고 로그인한 Claude 앱 게이트웨이 세션에서는 [`CLAUDE_CODE_ENABLE_AUTO_MODE`를 설정](#enable-auto-mode-on-bedrock-vertex-ai-or-foundry)할 때까지 자동 모드가 꺼져 있습니다.198* **제공자**: Anthropic API에서 기본적으로 사용 가능합니다. Amazon Bedrock, Google Cloud의 Agent Platform, Microsoft Foundry, 그리고 로그인한 Claude 앱 게이트웨이 세션에서는 [`CLAUDE_CODE_ENABLE_AUTO_MODE`를 설정](#enable-auto-mode-on-bedrock-agent-platform-or-foundry)할 때까지 자동 모드가 꺼져 있습니다.

193 199

194Claude Code가 자동 모드를 사용할 수 없다고 보고하면, 이러한 요구 사항 중 하나가 충족되지 않은 것입니다. 이는 일시적인 중단이 아닙니다. 모델을 이름으로 지정하고 자동 모드가 작업의 안전을 "결정할 수 없다"고 말하는 별도의 메시지는 일시적인 분류기 중단입니다. [오류 참조](/ko/errors#auto-mode-cannot-determine-the-safety-of-an-action)를 참조합니다.200Claude Code가 자동 모드를 사용할 수 없다고 보고하면, 이러한 요구 사항 중 하나가 충족되지 않은 것입니다. 이는 일시적인 중단이 아닙니다. 모델을 이름으로 지정하고 자동 모드가 작업의 안전을 "결정할 수 없다"고 말하는 별도의 메시지는 일시적인 분류기 중단입니다. [오류 참조](/ko/errors#auto-mode-cannot-determine-the-safety-of-an-action)를 참조합니다.

195 201

196[설정](/ko/settings#available-settings)에서 `defaultMode: "auto"`를 설정했는데 세션이 오류 없이 `default` 모드로 시작하면, 설정이 `.claude/settings.json` 또는 `.claude/settings.local.json`에 있을 가능성이 높습니다. Claude Code v2.1.142 이상은 이러한 파일의 `auto`를 무시하므로 리포지토리가 자신에게 자동 모드를 부여할 수 없습니다. 이를 `~/.claude/settings.json`으로 이동합니다.202[설정](/ko/settings#available-settings)에서 `defaultMode: "auto"`를 설정했는데 세션이 오류 없이 `default` 모드로 시작하면, 설정이 `.claude/settings.json` 또는 `.claude/settings.local.json`에 있을 가능성이 높습니다. Claude Code v2.1.142 이상은 이러한 파일의 `auto`를 무시하므로 리포지토리가 자신에게 자동 모드를 부여할 수 없습니다. 이를 `~/.claude/settings.json`으로 이동합니다.

197 203

198<h3 id="enable-auto-mode-on-bedrock-vertex-ai-or-foundry">204<h3 id="enable-auto-mode-on-bedrock-agent-platform-or-foundry">

199 Bedrock, Vertex AI, Foundry에서 자동 모드 활성화205 Bedrock, Agent Platform, Foundry에서 자동 모드 활성화

200</h3>206</h3>

201 207

202[Amazon Bedrock](/ko/amazon-bedrock), [Google Cloud Vertex AI](/ko/google-vertex-ai), [Microsoft Foundry](/ko/microsoft-foundry), 그리고 로그인한 [Claude 앱 게이트웨이](/ko/claude-apps-gateway) 세션에서는 `CLAUDE_CODE_ENABLE_AUTO_MODE`가 `1`로 설정될 때까지 자동 모드가 `Shift+Tab` 사이클에 나타나지 않습니다. 변수는 Claude Code v2.1.158 이상에서 작동합니다. 이러한 제공자에서는 Claude Sonnet 5, Opus 4.7, 및 Opus 4.8만 지원됩니다.208[Amazon Bedrock](/ko/amazon-bedrock), [Google Cloud의 Agent Platform](/ko/google-vertex-ai), [Microsoft Foundry](/ko/microsoft-foundry), 그리고 로그인한 [Claude 앱 게이트웨이](/ko/claude-apps-gateway) 세션에서는 `CLAUDE_CODE_ENABLE_AUTO_MODE`가 `1`로 설정될 때까지 자동 모드가 `Shift+Tab` 사이클에 나타나지 않습니다. 변수는 Claude Code v2.1.158 이상에서 작동합니다. 이러한 제공자에서는 Claude Sonnet 5, Opus 4.7, 및 Opus 4.8만 지원됩니다.

203 209

204한 명의 개발자에게 이를 활성화하려면, `~/.claude/settings.json`의 `env` 블록에 변수를 추가합니다:210한 명의 개발자에게 이를 활성화하려면, `~/.claude/settings.json`의 `env` 블록에 변수를 추가합니다:

205 211

223 분류기가 기본적으로 차단하는 항목229 분류기가 기본적으로 차단하는 항목

224</h3>230</h3>

225 231

226분류기는 작업 디렉토리와 리포지토리의 구성된 원격을 신뢰합니다. 다른 모든 것은 [신뢰할 수 있는 인프라를 구성](/ko/auto-mode-config)할 때까지 외부로 취급됩니다.232분류기는 작업 디렉토리와 세션이 시작될 때 구성된 원격을 신뢰합니다. {/* min-version: 2.1.200 */}세션 중에 `git remote add` 또는 `git remote set-url`로 추가되거나 재지정된 원격은 신뢰되지 않으며, [신뢰할 수 있는 인프라를 구성](/ko/auto-mode-config)할 때까지 다른 모든 것은 외부로 취급됩니다. v2.1.200 이전에는 세션 중에 추가된 원격도 신뢰되었습니다.

227 233

228**기본적으로 차단됨**:234**기본적으로 차단됨**:

229 235

234* IAM 또는 리포지토리 권한 부여240* IAM 또는 리포지토리 권한 부여

235* 공유 인프라 수정241* 공유 인프라 수정

236* 세션 시작 전에 존재했던 파일을 되돌릴 수 없게 삭제242* 세션 시작 전에 존재했던 파일을 되돌릴 수 없게 삭제

237* 강제 푸시 또는 `main`에 직접 푸시243* 강제 푸시

244* {/* min-version: 2.1.203 */}기본 분기로 푸시할 때 푸시가 비밀 또는 개인 또는 신뢰할 수 있는 데이터와 같은 민감한 콘텐츠를 전달하거나, 요청한 내용과 비교하여 숨겨지거나 잘못 설명된 변경 사항을 전달하거나, 리포지토리 외부에서 포팅되거나 처음 읽은 콘텐츠를 전달하거나, 요청한 풀 요청, 검토, 또는 검사를 우회하는 경우. 기본 분기로의 일반 푸시는 자체적으로 차단되지 않으며, 플래그된 푸시를 지우려면 플래그된 콘텐츠 또는 우회된 검토를 이름으로 지정해야 하며, 푸시만으로는 충분하지 않습니다. 분류기는 한 계층입니다: [`permissions.deny` 규칙](/ko/permissions#manage-permissions)은 모든 모드에서 적용되며 기본 분기로의 푸시를 완전히 차단할 수 있으며, 원격의 자체 분기 보호는 여전히 적용됩니다. v2.1.203 이전에는 기본 분기로의 모든 직접 푸시가 차단되었습니다

238* {/* min-version: 2.1.182 */}`git reset --hard`, `git checkout -- .`, `git restore .`, `git clean -fd`, `git stash drop`, 또는 `git stash clear`. 분류기는 이들이 커밋되지 않은 변경 사항을 삭제할 것으로 추정합니다245* {/* min-version: 2.1.182 */}`git reset --hard`, `git checkout -- .`, `git restore .`, `git clean -fd`, `git stash drop`, 또는 `git stash clear`. 분류기는 이들이 커밋되지 않은 변경 사항을 삭제할 것으로 추정합니다

239* `git commit --amend` (HEAD의 커밋이 이 세션에서 생성되지 않은 경우)246* `git commit --amend` (HEAD의 커밋이 이 세션에서 생성되지 않은 경우)

240* {/* min-version: 2.1.198 */}}v2.1.198부터, `git commit --amend` (HEAD의 커밋이 이미 푸시된 경우). 메시지 전용 리워드는 차단되지 않습니다: `--amend -m` (새로 스테이징된 것이 없음, Claude가 이 세션 중에 생성한 커밋)247* {/* min-version: 2.1.198 */}}v2.1.198부터, `git commit --amend` (HEAD의 커밋이 이미 푸시된 경우). 메시지 전용 리워드는 차단되지 않습니다: `--amend -m` (새로 스테이징된 것이 없음, Claude가 이 세션 중에 생성한 커밋)

261Claude Code v2.1.198 이상은 또한 기본적으로 다음을 차단합니다:268Claude Code v2.1.198 이상은 또한 기본적으로 다음을 차단합니다:

262 269

263* 와일드카드, glob, 또는 나이 필터가 아닌 특정 명명된 경로로 `/tmp`, `$TMPDIR`, 또는 다른 공유 스크래치 또는 캐시 디렉토리의 파일 삭제270* 와일드카드, glob, 또는 나이 필터가 아닌 특정 명명된 경로로 `/tmp`, `$TMPDIR`, 또는 다른 공유 스크래치 또는 캐시 디렉토리의 파일 삭제

264* 자신의 메시지가 해당 수신자에게 해당 세부 정보를 승인하지 않은 경우, 전송, 업로드, 게시, 또는 다른 사람이나 공유 시스템에 작성된 콘텐츠에 민감한 세부 정보 포함271* 자신의 메시지가 해당 수신자에게 해당 세부 정보를 승인하지 않은 경우, 전송, 업로드, 게시, 또는 다른 사람이나 공유 시스템에 작성된 콘텐츠에 민감한 세부 정보 포함. {/* min-version: 2.1.200 */}PR 및 이슈 본문, 커밋 메시지, 및 댓글은 리포지토리가 신뢰 경계 외부이거나 공개인 경우 이러한 종류의 아웃바운드 콘텐츠로 계산됩니다. 조직의 자체 공개 리포지토리 포함; 내부 파일 경로, 코드명, 라이브 API 응답 데이터(예: 이메일 또는 계정 식별자), 및 인프라 식별자는 민감한 세부 정보로 계산됩니다. PR, 이슈, 및 커밋 메시지 범위 지정은 Claude Code v2.1.200 이상이 필요합니다. {/* min-version: 2.1.203 */}}PR 또는 이슈 본문의 라이브 개인 데이터(예: 이메일 주소, 계정 또는 조직 식별자, 또는 사용 메트릭)는 리포지토리의 가시성 또는 신뢰 경계와 관계없이 해당 세부 정보와 수신자를 이름으로 지정해야 합니다. 이 검사는 Claude Code v2.1.203 이상이 필요합니다

265* Claude Code의 자체 tmux 창으로 키스트로크 전송하여 자체 인터페이스를 구동하는 것. 분류기는 이를 Claude가 자체 권한 또는 감시를 변경하는 것으로 취급합니다272* Claude Code의 자체 tmux 창으로 키스트로크 전송하여 자체 인터페이스를 구동하는 것. 분류기는 이를 Claude가 자체 권한 또는 감시를 변경하는 것으로 취급합니다

266 273

274Claude Code v2.1.200 이상은 또한 기본적으로 다음을 차단합니다:

275

276* 보안 동작을 보호하는 테스트 또는 어설션(예: 인증, 액세스 제어, 입력 검증, 또는 샌드박싱)을 주석 처리, 삭제, 또는 강제 통과

277* 세션에서 Claude가 생성하지 않은 상태 저장 리소스 삭제 또는 해제. 더 구체적인 삭제 규칙이 적용되지 않고 해당 리소스를 이름으로 지정하지 않은 경우

278* API 기본 URL, 프록시 엔드포인트, 웹훅 수신자, 또는 레지스트리 미러를 작업에 맞지 않는 제3자 호스트로 재지정. `.env.example`과 같은 예제 파일 포함

279* `git remote set-url` 또는 `git remote add`로 푸시가 가는 위치 변경. 새 원격을 이름으로 지정하지 않은 경우

280* 공개로 알려진 리포지토리로 비밀 또는 개인 또는 신뢰할 수 있는 데이터 푸시, 또는 해당 리포지토리의 자체 작업의 일부가 아닌 기밀 자료 푸시. {/* min-version: 2.1.203 */}}dotfiles 리포지토리의 자체 주제는 개인 또는 신뢰할 수 있는 데이터의 유일한 예외이며, 개인 리포지토리에서 나오는 콘텐츠가 공개 표면에 도달하는 것은 동일한 방식으로 차단됩니다. 두 개선 사항 모두 Claude Code v2.1.203 이상이 필요합니다. v2.1.203 이전에는 개인 데이터가 기밀 자료와 함께 그룹화되었으며 해당 리포지토리의 자체 작업의 일부가 아닌 경우에만 차단되었습니다. 리포지토리의 가시성이 확립되지 않은 경우, 분류기는 그것만으로는 차단하지 않습니다. 대신 다른 규칙에 대해 콘텐츠를 판단합니다

281* 다른 리포지토리 또는 조직에 대한 풀 요청 열기, `gh repo fork`로 포킹, 또는 제3자 리포지토리로 푸시. 해당 외부 대상을 이름으로 지정하지 않은 경우

282

283Claude Code v2.1.203 이상은 또한 기본적으로 다음을 차단합니다:

284

285* 민감한 로컬 저장소의 콘텐츠, 또는 이름, 경로, 또는 유형이 민감한 것으로 표시된 파일의 콘텐츠가 커밋, 푸시, PR 또는 이슈 텍스트, gist 또는 paste, 또는 패키지 게시에 들어가는 경우. 소스와 대상을 모두 이름으로 지정하지 않은 경우. 세션 기록 및 대화 로그, 자격 증명 및 구성 dot-폴더(예: SSH 키, 클라우드 자격 증명, 브라우저 프로필, 셸 기록), 및 사용자 데이터 내보내기 모두 계산되며, 리포지토리가 개인이라는 것이 이를 지우지 않습니다

286

287Claude Code v2.1.205 이상은 또한 기본적으로 다음을 차단합니다:

288

289* Claude Code 세션 기록, `~/.claude/projects/` 아래의 `.jsonl` 기록 파일 또는 구성된 구성 디렉토리에 직접 또는 셸 명령을 통해 쓰기. 규칙은 또한 Claude Code가 자체 검사를 위해 각 기록 항목에 추가하는 메타데이터 줄을 포함합니다. 기록은 Claude Code가 작성하는 세션 상태이며 작업 파일이 아니며, 변조된 항목은 세션을 재개하면 모든 나중 검사에 도달하므로, 자동 모드는 심층 방어로 이러한 쓰기를 차단합니다. 기록 읽기는 차단되지 않습니다

290* `rm -rf "$VAR"` 또는 `Remove-Item -Recurse -Force $dir`과 같은 재귀적 강제 삭제. 대상이 분류기가 보는 대화의 어디에도 할당되지 않은 셸 변수 또는 하나에 근거한 glob인 경우. 값은 분류기가 절대 받지 않는 이전 명령 출력에서만 나왔으므로, 분류기는 삭제를 다른 삭제 규칙에 대해 확인할 수 없습니다. 분류기는 명령 출력이 아닌 대화를 읽으므로, 대신 호출을 차단합니다. 블록은 삭제되는 정확한 경로를 이름으로 지정하거나 Claude가 해결된 리터럴 경로가 명령에 작성된 삭제를 다시 실행할 때 지워집니다. 분류기가 대상을 해결할 수 있는 삭제는 영향을 받지 않습니다

291

267**기본적으로 허용됨**:292**기본적으로 허용됨**:

268 293

269* 작업 디렉토리의 로컬 파일 작업294* 작업 디렉토리의 로컬 파일 작업

280* [`environment`](/ko/auto-mode-config#define-trusted-infrastructure)에 나열한 신뢰할 수 있는 도메인, 버킷, 서비스로 데이터 전송. 이는 같은 인프라에 대한 파괴적이거나 자격 증명 작업이 아닌 데이터 흐름만 포함합니다305* [`environment`](/ko/auto-mode-config#define-trusted-infrastructure)에 나열한 신뢰할 수 있는 도메인, 버킷, 서비스로 데이터 전송. 이는 같은 인프라에 대한 파괴적이거나 자격 증명 작업이 아닌 데이터 흐름만 포함합니다

281* [Chrome의 Claude](/ko/chrome)를 신뢰할 수 있는 내부 도메인, localhost, 또는 이름을 지정한 URL로 탐색306* [Chrome의 Claude](/ko/chrome)를 신뢰할 수 있는 내부 도메인, localhost, 또는 이름을 지정한 URL로 탐색

282 307

283샌드박스 네트워크 액세스 요청은 기본적으로 허용되는 대신 분류기를 통해 라우팅됩니다. {/* min-version: 2.1.198 */}v2.1.198부터 분류기는 모든 연결에서 다시 실행하는 대신 네트워크 호스트 및 포트에 대한 판정을 재사용합니다:308샌드박스 네트워크 액세스 요청은 기본적으로 허용되는 대신 분류기를 통해 라우팅됩니다. {/* min-version: 2.1.198 */}}v2.1.198부터 분류기는 모든 연결에서 다시 실행하는 대신 네트워크 호스트 및 포트에 대한 판정을 재사용합니다:

284 309

285* 허용은 새 콘텐츠가 대화에 들어올 때까지 재사용되며, 그 시점에서 해당 호스트가 다시 확인됩니다310* 허용은 새 콘텐츠가 대화에 들어올 때까지 재사용되며, 그 시점에서 해당 호스트가 다시 확인됩니다

286* 대화형 CLI에서, 거부는 턴이 끝날 때 삭제됩니다311* 대화형 CLI에서, 거부는 턴이 끝날 때 삭제됩니다

315 340

316 1. [허용 또는 거부 규칙](/ko/permissions#manage-permissions)과 일치하는 작업은 즉시 해결됩니다. [보호된 경로](#protected-paths)에 대한 쓰기는 제외되며, 허용 규칙이 일치하더라도 분류기로 라우팅됩니다341 1. [허용 또는 거부 규칙](/ko/permissions#manage-permissions)과 일치하는 작업은 즉시 해결됩니다. [보호된 경로](#protected-paths)에 대한 쓰기는 제외되며, 허용 규칙이 일치하더라도 분류기로 라우팅됩니다

317 2. 읽기 전용 작업 및 작업 디렉토리의 파일 편집은 자동 승인됩니다. [보호된 경로](#protected-paths)에 대한 쓰기는 제외됩니다342 2. 읽기 전용 작업 및 작업 디렉토리의 파일 편집은 자동 승인됩니다. [보호된 경로](#protected-paths)에 대한 쓰기는 제외됩니다

318 3. 다른 모든 것은 분류기로 이동합니다. {/* min-version: 2.1.199 */}v2.1.199부터, [`_meta["anthropic/requiresUserInteraction"]`](/ko/mcp#require-approval-for-a-specific-tool)로 표시된 MCP 도구는 분류기를 건너뛰고 직접 프롬프트하므로, 동의 단계는 도구 작성자를 대신하여 자동 승인되지 않습니다343 3. 다른 모든 것은 분류기로 이동합니다. {/* min-version: 2.1.199 */}}v2.1.199부터, [`_meta["anthropic/requiresUserInteraction"]`](/ko/mcp#require-approval-for-a-specific-tool)로 표시된 MCP 도구는 분류기를 건너뛰고 직접 프롬프트하므로, 동의 단계는 도구 작성자를 대신하여 자동 승인되지 않습니다

319 4. 분류기가 차단하면, Claude는 이유를 받고 대체 방법을 시도합니다344 4. 분류기가 차단하면, Claude는 이유를 받고 대체 방법을 시도합니다

320 345

321 자동 모드에 들어가면, 임의의 코드 실행을 부여하는 광범위한 허용 규칙이 삭제됩니다:346 자동 모드에 들어가면, 임의의 코드 실행을 부여하는 광범위한 허용 규칙이 삭제됩니다:

337 2. 서브에이전트가 실행되는 동안, 각 작업은 부모 세션과 동일한 규칙으로 분류기를 통해 이동하며, 서브에이전트의 프론트매터의 모든 `permissionMode`는 무시됩니다.362 2. 서브에이전트가 실행되는 동안, 각 작업은 부모 세션과 동일한 규칙으로 분류기를 통해 이동하며, 서브에이전트의 프론트매터의 모든 `permissionMode`는 무시됩니다.

338 3. 서브에이전트가 완료되면, 분류기는 전체 작업 기록을 검토합니다. 반환 검사가 우려 사항에 플래그를 지정하면, 보안 경고가 서브에이전트의 결과에 앞에 붙습니다.363 3. 서브에이전트가 완료되면, 분류기는 전체 작업 기록을 검토합니다. 반환 검사가 우려 사항에 플래그를 지정하면, 보안 경고가 서브에이전트의 결과에 앞에 붙습니다.

339 364

365 {/* min-version: 2.1.178 */}}

340 1단계는 Claude Code v2.1.178 이상이 필요합니다. 이전 버전은 2단계와 3단계에서 분류기를 적용했지만, 서브에이전트가 시작되기 전에 작업 설명을 평가하지 않았습니다.366 1단계는 Claude Code v2.1.178 이상이 필요합니다. 이전 버전은 2단계와 3단계에서 분류기를 적용했지만, 서브에이전트가 시작되기 전에 작업 설명을 평가하지 않았습니다.

341 </Accordion>367 </Accordion>

342 368

343 <Accordion title="비용 및 지연">369 <Accordion title="비용 및 지연">

344 분류기는 `/model` 선택과 독립적인 서버 구성 모델에서 실행되므로, 모델을 전환해도 분류기 가용성이 변경되지 않습니다. 분류기 호출은 토큰 사용량으로 계산됩니다. 각 검사는 기록의 일부와 보류 중인 작업을 전송하여 실행 전에 왕복을 추가합니다. 읽기 및 보호된 경로 외의 작업 디렉토리 편집은 분류기를 건너뛰므로, 오버헤드는 주로 셸 명령 및 네트워크 작업에서 발생합니다. {/* min-version: 2.1.198 */}v2.1.198부터 호스트 및 포트에 대한 샌드박스 네트워크 판정은 모든 연결에서 다시 분류되는 대신 재사용되므로, 같은 호스트에 대한 반복된 연결은 각각 검사를 추가하지 않습니다. [분류기가 기본적으로 차단하는 항목](#what-the-classifier-blocks-by-default)은 허용 및 거부가 지속되는 기간을 설명합니다.370 분류기는 `/model` 선택과 독립적인 서버 구성 모델에서 실행되므로, 모델을 전환해도 분류기 가용성이 변경되지 않습니다. 분류기 호출은 토큰 사용량으로 계산됩니다. 각 검사는 기록의 일부와 보류 중인 작업을 전송하여 실행 전에 왕복을 추가합니다. 읽기 및 보호된 경로 외의 작업 디렉토리 편집은 분류기를 건너뛰므로, 오버헤드는 주로 셸 명령 및 네트워크 작업에서 발생합니다. {/* min-version: 2.1.198 */}}v2.1.198부터 호스트 및 포트에 대한 샌드박스 네트워크 판정은 모든 연결에서 다시 분류되는 대신 재사용되므로, 같은 호스트에 대한 반복된 연결은 각각 검사를 추가하지 않습니다. [분류기가 기본적으로 차단하는 항목](#what-the-classifier-blocks-by-default)은 허용 및 거부가 지속되는 기간을 설명합니다.

345 </Accordion>371 </Accordion>

346</AccordionGroup>372</AccordionGroup>

347 373

permissions.md +32 −6

Details

47Claude Code는 도구 승인 방식을 제어하는 여러 권한 모드를 지원합니다. [권한 모드](/ko/permission-modes)에서 각 모드를 사용할 시기를 확인합니다. [설정 파일](/ko/settings#settings-files)에서 `defaultMode`를 설정합니다:47Claude Code는 도구 승인 방식을 제어하는 여러 권한 모드를 지원합니다. [권한 모드](/ko/permission-modes)에서 각 모드를 사용할 시기를 확인합니다. [설정 파일](/ko/settings#settings-files)에서 `defaultMode`를 설정합니다:

48 48

49| 모드 | 설명 |49| 모드 | 설명 |

~~50| :------------------ | :------------------------------------------------------------------------------------------------------------------------------------ |~~50| :------------------ | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

51| `default` | 표준 동작: 각 도구를 처음 사용할 때 권한을 요청합니다 |51| `default` | 표준 동작: 각 도구를 처음 사용할 때 권한을 요청합니다. {/* min-version: 2.1.200 */}CLI 및 VS Code와 JetBrains 확장에서 Manual로 표시되며, Claude Code는 `manual`을 별칭으로 허용합니다. 레이블과 별칭은 Claude Code v2.1.200 이상이 필요합니다 |

52| `acceptEdits` | 작업 디렉토리 또는 `additionalDirectories`의 경로에 대해 파일 편집 및 일반적인 파일 시스템 명령(`mkdir`, `touch`, `mv`, `cp` 등)을 자동으로 수락합니다 |52| `acceptEdits` | 작업 디렉토리 또는 `additionalDirectories`의 경로에 대해 파일 편집 및 일반적인 파일 시스템 명령(`mkdir`, `touch`, `mv`, `cp` 등)을 자동으로 수락합니다 |

56| `bypassPermissions` | 명시적 `ask` 규칙으로 강제되는 권한 프롬프트를 제외한 모든 권한 프롬프트를 건너뜁니다. 파일 시스템 루트 또는 홈 디렉토리 제거(예: `rm -rf /` 및 `rm -rf ~`)는 모델 오류에 대한 회로 차단기로 여전히 프롬프트합니다 |56| `bypassPermissions` | 명시적 `ask` 규칙으로 강제되는 권한 프롬프트를 제외한 모든 권한 프롬프트를 건너뜁니다. 파일 시스템 루트 또는 홈 디렉토리 제거(예: `rm -rf /` 및 `rm -rf ~`)는 모델 오류에 대한 회로 차단기로 여전히 프롬프트합니다 |

215 215

216따옴표 없는 glob 패턴은 모든 플래그가 읽기 전용인 명령에 대해 허용되므로 `ls *.ts` 및 `wc -l src/*.py`는 프롬프트 없이 실행됩니다. `find`, `sort`, `sed` 및 `git`과 같이 쓰기 가능하거나 실행 가능한 플래그가 있는 명령은 glob이 `-delete`와 같은 플래그로 확장될 수 있으므로 따옴표 없는 glob이 있을 때 여전히 프롬프트합니다.216따옴표 없는 glob 패턴은 모든 플래그가 읽기 전용인 명령에 대해 허용되므로 `ls *.ts` 및 `wc -l src/*.py`는 프롬프트 없이 실행됩니다. `find`, `sort`, `sed` 및 `git`과 같이 쓰기 가능하거나 실행 가능한 플래그가 있는 명령은 glob이 `-delete`와 같은 플래그로 확장될 수 있으므로 따옴표 없는 glob이 있을 때 여전히 프롬프트합니다.

217 217

218작업 디렉토리 또는 [추가 디렉토리](#working-directories) 내의 경로로의 `cd`도 읽기 전용입니다. `cd packages/api && ls`와 같은 복합 명령은 각 부분이 자체적으로 적격일 때 프롬프트 없이 실행됩니다. 하나의 복합 명령에서 `cd`와 `git`을 결합하면 대상 디렉토리와 관계없이 항상 프롬프트합니다.218작업 디렉토리 또는 [추가 디렉토리](#working-directories) 내의 경로로의 `cd`도 읽기 전용입니다. `cd packages/api && ls`와 같은 복합 명령은 각 부분이 자체적으로 적격일 때 프롬프트 없이 실행됩니다. 하나의 복합 명령에서 `cd`와 `git`을 결합하면 `cd`가 다른 디렉토리로 변경될 때 프롬프트합니다. 새 디렉토리에서 `git`을 실행하면 해당 디렉토리의 훅을 실행할 수 있기 때문입니다. 대상이 현재 작업 디렉토리로 해결되는 `cd`는 작동하지 않으며 이 프롬프트를 트리거하지 않습니다.

219 219

220<Warning>220<Warning>

221 명령 인수를 제약하려고 시도하는 Bash 권한 패턴은 취약합니다. 예를 들어, `Bash(curl http://github.com/ *)`는 curl을 GitHub URL로 제한하려고 하지만 다음과 같은 변형과는 일치하지 않습니다:221 명령 인수를 제약하려고 시도하는 Bash 권한 패턴은 취약합니다. 예를 들어, `Bash(curl http://github.com/ *)`는 curl을 GitHub URL로 제한하려고 하지만 다음과 같은 변형과는 일치하지 않습니다:

293 293

294deny 규칙(예: 사용자 설정의 `Read(/secrets//**)`)은 프로젝트의 `secrets` 디렉토리가 아니라 `~/.claude/secrets/**`를 차단합니다. 모든 프로젝트 내에서 적용되는 사용자 설정의 규칙을 작성하려면 `//` 절대 경로 또는 `~/` 홈 상대 경로를 대신 사용합니다.294deny 규칙(예: 사용자 설정의 `Read(/secrets/**)`)은 프로젝트의 `secrets` 디렉토리가 아니라 `~/.claude/secrets/**`를 차단합니다. 모든 프로젝트 내에서 적용되는 사용자 설정의 규칙을 작성하려면 `//` 절대 경로 또는 `~/` 홈 상대 경로를 대신 사용합니다.

295 295

296Windows에서 경로는 일치하기 전에 POSIX 형식으로 정규화됩니다. `C:\Users\alice`는 `/c/Users/alice`가 되므로 `//c/**/.env`를 사용하여 해당 드라이브의 어디든 `.env` 파일과 일치시킵니다. 모든 드라이브에서 일치시키려면 `//**/.env`를 사용합니다.296Windows에서 경로는 일치하기 전에 POSIX 형식으로 정규화됩니다. `C:\Users\alice`는 `/c/Users/alice`가 되므로 `//c/**/.env`를 사용하여 해당 드라이브의 어디든 `.env` 파일과 일치시킵니다. 모든 드라이브에서 일치시키려면 `//**/.env`를 사용합니다.

297 297

313 gitignore 패턴에서 `*`는 단일 디렉토리의 파일과 일치하고 `**`는 디렉토리 전체에서 재귀적으로 일치합니다. 모든 파일 액세스를 허용하려면 괄호 없이 도구 이름만 사용합니다: `Read`, `Edit` 또는 `Write`.313 gitignore 패턴에서 `*`는 단일 디렉토리의 파일과 일치하고 `**`는 디렉토리 전체에서 재귀적으로 일치합니다. 모든 파일 액세스를 허용하려면 괄호 없이 도구 이름만 사용합니다: `Read`, `Edit` 또는 `Write`.

314</Note>314</Note>

315 315

316"예, 다시 묻지 않기"로 파일 경로를 승인하면 Claude Code는 `[`, `]` 및 `*`와 같은 gitignore 패턴 문자를 해당 경로에서 이스케이프하므로 생성된 규칙은 승인한 리터럴 경로와만 일치합니다. 직접 작성한 규칙은 이스케이프되지 않습니다. v2.1.202 이전에는 Claude Code가 경로를 이스케이프되지 않은 상태로 저장했으므로 `[2024-06] Reports`라는 이름의 디렉토리에 대해 생성된 규칙이 자신의 경로와 일치하지 않거나 의도하지 않은 형제 디렉토리와 일치할 수 있었습니다.

317

316Claude가 심볼릭 링크에 액세스할 때 권한 규칙은 두 경로를 확인합니다: 심볼릭 링크 자체와 이것이 해결되는 파일입니다. Allow 및 deny 규칙은 해당 쌍을 다르게 취급합니다: allow 규칙은 프롬프트로 폴백하고 deny 규칙은 즉시 차단합니다.318Claude가 심볼릭 링크에 액세스할 때 권한 규칙은 두 경로를 확인합니다: 심볼릭 링크 자체와 이것이 해결되는 파일입니다. Allow 및 deny 규칙은 해당 쌍을 다르게 취급합니다: allow 규칙은 프롬프트로 폴백하고 deny 규칙은 즉시 차단합니다.

317 319

318* **Allow 규칙**: 심볼릭 링크 경로와 해당 대상이 모두 일치할 때만 적용됩니다. 허용된 디렉토리 내의 심볼릭 링크가 외부를 가리키면 여전히 프롬프트합니다.320* **Allow 규칙**: 심볼릭 링크 경로와 해당 대상이 모두 일치할 때만 적용됩니다. 허용된 디렉토리 내의 심볼릭 링크가 외부를 가리키면 여전히 프롬프트합니다.

330* `WebFetch(domain:*.example.com)`은 `api.example.com` 또는 `a.b.example.com`과 같은 모든 깊이의 모든 서브도메인과 일치하지만 `example.com` 자체는 일치하지 않습니다332* `WebFetch(domain:*.example.com)`은 `api.example.com` 또는 `a.b.example.com`과 같은 모든 깊이의 모든 서브도메인과 일치하지만 `example.com` 자체는 일치하지 않습니다

331* `WebFetch(domain:*)`는 모든 도메인과 일치하며 베어 `WebFetch` 규칙과 동등합니다333* `WebFetch(domain:*)`는 모든 도메인과 일치하며 베어 `WebFetch` 규칙과 동등합니다

332 334

333`*`는 선행 `*.` 또는 전체 패턴으로서만 `.`을 가로질러 일치합니다. 다른 곳에서는 하나의 레이블 내에 머물므로 `WebFetch(domain:github.*)`는 `github.io`와 일치하지만 공격자가 등록할 수 있는 도메인인 `github.evil.com`과는 일치하지 않습니다.335선행 `*.` 또는 베어 `*`가 아닌 다른 위치에서 와일드카드는 두 점 사이의 텍스트와만 일치합니다. `WebFetch(domain:example.*)`는 `example.org`과 일치합니다. 여기서 `*`는 `org`가 되지만 `example.evil.com`과는 일치하지 않습니다. 여기서 `*`는 `evil.com`이 되어야 하고 점을 넘어야 합니다. 이는 후행 와일드카드가 공격자가 등록할 수 있는 도메인과 일치하는 것을 방지합니다.

334 336

335<h3 id="mcp">337<h3 id="mcp">

336 MCP338 MCP

505 507

506Embedding hosts는 [`parentSettingsBehavior`](/ko/settings#settings-precedence)가 `"merge"`로 설정되어 있을 때 SDK `managedSettings` 옵션을 통해 추가 관리형 정책을 제공할 수 있습니다. Embedder 값은 정책을 강화할 수 있지만 완화할 수는 없습니다.508Embedding hosts는 [`parentSettingsBehavior`](/ko/settings#settings-precedence)가 `"merge"`로 설정되어 있을 때 SDK `managedSettings` 옵션을 통해 추가 관리형 정책을 제공할 수 있습니다. Embedder 값은 정책을 강화할 수 있지만 완화할 수는 없습니다.

507 509

510<h2 id="project-allow-rules-and-workspace-trust">

511 프로젝트 허용 규칙 및 워크스페이스 신뢰

512</h2>

513

514프로젝트의 `.claude/settings.json`에 있는 `permissions.allow` 규칙과 `permissions.additionalDirectories` 항목은 기능을 부여하므로, Claude Code는 해당 워크스페이스에 대해 [워크스페이스 신뢰 대화상자](/ko/security#additional-safeguards)를 수락한 후에만 이를 적용합니다. 그 전까지는 Claude Code가 규칙을 읽지만 적용하지 않습니다. 신뢰 대화상자는 폴더가 부여할 허용 규칙과 추가 디렉터리를 나열하므로 수락하기 전에 검토할 수 있습니다. `deny` 및 `ask` 규칙은 영향을 받지 않습니다. 이들은 제한만 하기 때문입니다.

515

516Claude Code는 워크스페이스별로 신뢰를 저장하며, git 저장소 루트를 기준으로 하거나, 저장소 외부에서는 Claude Code를 시작한 디렉터리를 기준으로 합니다. 홈 디렉터리에서 시작하면 신뢰는 현재 세션에만 유지되며 디스크에 기록되지 않습니다. [추가 보안 조치](/ko/security#additional-safeguards) 참고를 참조하세요. 상위 디렉터리를 신뢰해도 중첩된 프로젝트의 허용 규칙은 적용되지 않습니다.

517

518`.claude/settings.local.json`은 사용자 자신의 파일이므로 워크스페이스 신뢰 확인이 일반적으로 적용되지 않습니다. 저장소가 파일을 제공할 수 있는 경우(예: git에 커밋되었거나 `.claude`가 심볼릭 링크인 경우) 해당 허용 규칙과 추가 디렉터리는 프로젝트 설정처럼 신뢰 확인을 거칩니다.

519

520`.claude/settings.local.json`의 허용 규칙과 추가 디렉터리는 두 가지 경우에 워크스페이스 신뢰 없이도 적용됩니다:

521

522* Claude Code를 시작한 디렉터리가 git 저장소 내부에 있지 않은 경우.

523* 세션이 사용자 자신의 구성 홈에서 실행되는 경우: 홈 디렉터리 또는 `.claude` 하위 디렉터리를 [`CLAUDE_CONFIG_DIR`](/ko/env-vars)로 설정한 모든 디렉터리.

524

525두 경우 모두 파일은 저장소가 제공할 수 있는 파일이 아니라 사용자가 만든 파일이며, 저장소에 커밋된 `.claude/settings.local.json`은 여전히 워크스페이스 신뢰가 필요합니다. 버전 2.1.196부터 2.1.199까지는 해당 워크스페이스에서 파일을 저장소 제공 파일로 취급하고 허용 규칙을 무시했으며 stderr에 [`this workspace has not been trusted`](/ko/errors#workspace-has-not-been-trusted) 경고를 출력했습니다. 위의 두 가지 예외는 v2.1.195 이전 버전과 일치하며 v2.1.200에서 복원되었습니다.

526

527또한 v2.1.200부터 허용 규칙이나 추가 디렉터리가 여전히 적용되지 않지만 상위 디렉터리가 이미 신뢰되어 신뢰 대화상자를 표시하지 않은 워크스페이스는 다음에 대화형으로 Claude Code를 시작할 때 대화상자를 표시합니다. 대화상자는 두 가지 선택지를 제공합니다:

528

529* **Yes, I trust this folder**: 해당 워크스페이스에 대한 신뢰를 저장하고 같은 세션에서 규칙을 적용합니다.

530* **No, continue without these permissions**: 해당 규칙을 무시한 상태로 계속 작동합니다. 대화상자는 다음 세션에 다시 나타납니다.

531

532[비대화형 모드](/ko/headless)에서 `-p`를 사용하면 대화상자가 나타나지 않고 규칙은 무시된 상태로 유지됩니다.

533

508<h2 id="example-configurations">534<h2 id="example-configurations">

509 예시 구성535 예시 구성

510</h2>536</h2>

platforms.md +1 −1

Details

24| Mobile | 컴퓨터에서 멀리 떨어져 있을 때 작업 시작 및 모니터링 | iOS 및 Android용 Claude 앱의 클라우드 세션, 로컬 세션용 [Remote Control](/ko/remote-control), Pro 및 Max의 Desktop으로 [Dispatch](/ko/desktop#sessions-from-dispatch) |24| Mobile | 컴퓨터에서 멀리 떨어져 있을 때 작업 시작 및 모니터링 | iOS 및 Android용 Claude 앱의 클라우드 세션, 로컬 세션용 [Remote Control](/ko/remote-control), Pro 및 Max의 Desktop으로 [Dispatch](/ko/desktop#sessions-from-dispatch) |

25 25

26CLI는 터미널 기반 작업을 위한 가장 완전한 플랫폼입니다. 스크립팅 및 Agent SDK는 CLI 전용입니다. 타사 제공자는 [VS Code](/ko/vs-code#use-third-party-providers)에서도 작동합니다. Enterprise [Desktop](/ko/desktop) 배포는 Vertex AI 및 게이트웨이 제공자를 지원합니다. Bedrock 또는 Foundry의 경우 CLI 또는 VS Code를 사용하거나, 해당 제공자에서 Code 탭을 실행하는 [Cowork on 3P research preview](https://claude.com/docs/cowork/3p/overview)를 사용합니다. Desktop과 IDE 확장 프로그램은 일부 CLI 전용 기능을 포기하는 대신 시각적 검토와 더 긴밀한 편집기 통합을 제공합니다. 웹은 Anthropic의 클라우드에서 실행되므로 연결을 해제한 후에도 작업이 계속됩니다. Mobile은 동일한 클라우드 세션으로의 씬 클라이언트이거나 Remote Control을 통한 로컬 세션으로의 씬 클라이언트이며, Dispatch를 통해 Desktop으로 작업을 보낼 수 있습니다.26CLI는 터미널 기반 작업을 위한 가장 완전한 플랫폼입니다. 스크립팅 및 Agent SDK는 CLI 전용입니다. 타사 제공자는 [VS Code](/ko/vs-code#use-third-party-providers)에서도 작동합니다. Enterprise [Desktop](/ko/desktop) 배포는 Google Cloud의 Agent Platform 및 게이트웨이 제공자를 지원합니다. Amazon Bedrock 또는 Microsoft Foundry의 경우 CLI 또는 VS Code를 사용하거나, 해당 제공자에서 Code 탭을 실행하는 [Claude Desktop on 3P](https://claude.com/docs/third-party/claude-desktop/overview)를 사용합니다. Desktop과 IDE 확장 프로그램은 일부 CLI 전용 기능을 포기하는 대신 시각적 검토와 더 긴밀한 편집기 통합을 제공합니다. 웹은 Anthropic의 클라우드에서 실행되므로 연결을 해제한 후에도 작업이 계속됩니다. Mobile은 동일한 클라우드 세션으로의 씬 클라이언트이거나 Remote Control을 통한 로컬 세션으로의 씬 클라이언트이며, Dispatch를 통해 Desktop으로 작업을 보낼 수 있습니다.

27 27

28동일한 프로젝트에서 여러 플랫폼을 혼합하여 사용할 수 있습니다. 구성, 프로젝트 메모리 및 MCP 서버는 로컬 플랫폼 간에 공유됩니다.28동일한 프로젝트에서 여러 플랫폼을 혼합하여 사용할 수 있습니다. 구성, 프로젝트 메모리 및 MCP 서버는 로컬 플랫폼 간에 공유됩니다.

29 29

plugin-dependencies.md +2 −2

Details

125| `~2.1` | `~3.0` | 플러그인 B 설치가 `range-conflict`로 실패합니다. 플러그인 A와 종속성은 그대로 유지됩니다. |125| `~2.1` | `~3.0` | 플러그인 B 설치가 `range-conflict`로 실패합니다. 플러그인 A와 종속성은 그대로 유지됩니다. |

126| `=2.1.0` | none | 종속성은 `2.1.0`에 머물러 있습니다. 플러그인 A가 설치된 동안 자동 업데이트는 최신 버전을 건너뜁니다. |126| `=2.1.0` | none | 종속성은 `2.1.0`에 머물러 있습니다. 플러그인 A가 설치된 동안 자동 업데이트는 최신 버전을 건너뜁니다. |

127 127

128자동 업데이트는 마켓플레이스의 최신 버전이 아닌 모든 설치된 플러그인의 범위를 만족하는 가장 높은 git 태그에서 제약된 종속성을 가져오므로, 종속성은 허용된 범위 내에서 계속 업데이트를 받습니다. 모든 범위를 만족하는 태그가 없으면 업데이트를 건너뛰고 건너뛴 메시지는 `/doctor`에 나타나며 `/plugin` 오류 탭에서 제약 플러그인의 이름을 지정합니다.128자동 업데이트는 마켓플레이스의 최신 버전이 아닌 모든 설치된 플러그인의 범위를 만족하는 가장 높은 git 태그에서 제약된 종속성을 가져오므로, 종속성은 허용된 범위 내에서 계속 업데이트를 받습니다. 모든 범위를 만족하는 태그가 없으면 자동 업데이트는 해당 종속성을 건너뛰고 `/plugin` 오류 탭에서 건너뛴 내용을 나열하며 제약 플러그인의 이름을 지정합니다.

129 129

130종속성을 제약하는 마지막 플러그인을 제거하면 종속성은 더 이상 유지되지 않으며 다음 업데이트에서 마켓플레이스 항목 추적을 재개합니다.130종속성을 제약하는 마지막 플러그인을 제거하면 종속성은 더 이상 유지되지 않으며 다음 업데이트에서 마켓플레이스 항목 추적을 재개합니다.

131 131

181 종속성 오류 해결181 종속성 오류 해결

182</h2>182</h2>

183 183

184종속성 문제는 `claude plugin list`, `/plugin` 인터페이스 및 `/doctor`에 표시됩니다. 영향을 받는 플러그인은 오류를 해결할 때까지 비활성화됩니다. 가장 일반적인 오류와 해결 방법은 아래에 나열되어 있습니다.184종속성 문제는 `claude plugin list` 및 `/plugin` 인터페이스에 표시됩니다. Claude Code는 오류를 해결할 때까지 영향을 받는 플러그인을 비활성화합니다. 아래 표에는 가장 일반적인 오류와 해결 방법이 나열되어 있습니다.

185 185

186| 오류 | 의미 | 해결 방법 |186| 오류 | 의미 | 해결 방법 |

187| :------------------------------- | :-------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------ |187| :------------------------------- | :-------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------ |

plugin-marketplaces.md +3 −1

Details

171 171

172<Note>172<Note>

173 **예약된 이름**: 다음 마켓플레이스 이름은 공식 Anthropic 사용을 위해 예약되어 있으며 타사 마켓플레이스에서 사용할 수 없습니다: `claude-code-marketplace`, `claude-code-plugins`, `claude-plugins-official`, `claude-plugins-community`, `claude-community`, `anthropic-marketplace`, `anthropic-plugins`, `agent-skills`, `anthropic-agent-skills`, `knowledge-work-plugins`, `life-sciences`, `claude-for-legal`, `claude-for-financial-services`, `financial-services-plugins`. 공식 마켓플레이스를 사칭하는 이름(예: `official-claude-plugins` 또는 `anthropic-tools-v2`)도 차단됩니다.173 **예약된 이름**: 다음 마켓플레이스 이름은 공식 Anthropic 사용을 위해 예약되어 있으며 타사 마켓플레이스에서 사용할 수 없습니다: `claude-code-marketplace`, `claude-code-plugins`, `claude-plugins-official`, `claude-plugins-community`, `claude-community`, `anthropic-marketplace`, `anthropic-plugins`, `agent-skills`, `anthropic-agent-skills`, `knowledge-work-plugins`, `life-sciences`, `claude-for-legal`, `claude-for-financial-services`, `financial-services-plugins`, `first-party-plugins`, `healthcare`. 공식 마켓플레이스를 사칭하는 이름(예: `official-claude-plugins` 또는 `anthropic-plugins-v2`)도 차단됩니다. 이러한 이름을 예약하면 타사 마켓플레이스가 자신을 Anthropic 게시 소스로 제시하는 것을 방지합니다.

174

175 Claude Code는 마켓플레이스를 추가할 때뿐만 아니라 마켓플레이스를 로드할 때마다 예약된 이름을 다시 확인합니다. 이름이 예약되기 전에 이러한 이름 중 하나로 등록된 마켓플레이스는 로드를 중지하고 [신뢰할 수 없는 소스에서 등록됨](/ko/errors#marketplace-is-registered-from-an-untrusted-source)을 보고합니다. 해당 마켓플레이스를 제거하고 공식 Anthropic 소스에서 다시 추가하세요. 새로 예약된 이름의 영향을 받는 타사 마켓플레이스는 다른 이름으로 다시 추가하는 즉시 다시 로드됩니다. v2.1.205 이전에는 `first-party-plugins` 및 `healthcare`가 예약되지 않았으며, 예약된 이름으로 이미 등록된 마켓플레이스는 계속 로드되었습니다.

174</Note>176</Note>

175 177

176<h3 id="owner-fields">178<h3 id="owner-fields">

plugins.md +2 −0

Details

203 203

204<Warning>204<Warning>

205 **일반적인 실수**: `commands/`, `agents/`, `skills/`, `hooks/`를 `.claude-plugin/` 디렉토리 내에 넣지 마세요. `.claude-plugin/` 내에는 `plugin.json`만 들어갑니다. 다른 모든 디렉토리는 플러그인 루트 수준에 있어야 합니다.205 **일반적인 실수**: `commands/`, `agents/`, `skills/`, `hooks/`를 `.claude-plugin/` 디렉토리 내에 넣지 마세요. `.claude-plugin/` 내에는 `plugin.json`만 들어갑니다. 다른 모든 디렉토리는 플러그인 루트 수준에 있어야 합니다.

206

207 플러그인 루트는 개별 플러그인의 자체 디렉토리입니다: `.claude-plugin/plugin.json`을 포함하는 디렉토리입니다. 절대 `~/.claude/`가 아닙니다. 예를 들어, Claude Code는 `~/.claude/.mcp.json`에 배치된 `.mcp.json`을 읽지 않습니다.

206</Warning>208</Warning>

207 209

208| 디렉토리 | 위치 | 목적 |210| 디렉토리 | 위치 | 목적 |

plugins-reference.md +17 −3

Details

159* `prompt`: LLM으로 프롬프트 평가 (컨텍스트에 대해 `$ARGUMENTS` 플레이스홀더 사용)159* `prompt`: LLM으로 프롬프트 평가 (컨텍스트에 대해 `$ARGUMENTS` 플레이스홀더 사용)

160* `agent`: 복잡한 검증 작업을 위해 도구가 있는 에이전트 검증자 실행160* `agent`: 복잡한 검증 작업을 위해 도구가 있는 에이전트 검증자 실행

161 161

162플러그인의 자체 [번들 MCP server](#mcp-servers)를 대상으로 하는 Hooks는 범위가 지정된 이름을 사용해야 합니다. 도구 매처 및 `if` 필드는 범위가 지정된 도구 이름 `mcp__plugin_<plugin-name>_<server-name>__<tool>`을 사용하고, `mcp_tool` hook의 `server` 필드는 `plugin:<plugin-name>:<server-name>`을 사용합니다. 베어 서버 키에 대해 작성된 매처는 절대 실행되지 않습니다. [MCP 도구 매칭](/ko/hooks#match-mcp-tools) 및 [플러그인 제공 MCP servers](/ko/mcp#plugin-provided-mcp-servers)를 참조하세요.

163

162<h3 id="mcp-servers">164<h3 id="mcp-servers">

163 MCP servers165 MCP servers

164</h3>166</h3>

258**선택사항 필드:**260**선택사항 필드:**

259 261

260| 필드 | 설명 |262| 필드 | 설명 |

261| :---------------------- | :------------------------------------------------------------------------------------- |263| :---------------------- | :------------------------------------------------------------------------------------------ |

264| `env` | 서버 시작 시 설정할 환경 변수 |266| `env` | 서버 시작 시 설정할 환경 변수 |

271| `shutdownTimeout` | 정상 종료를 기다릴 최대 시간 (밀리초). 시간 초과가 경과하면 Claude Code가 서버 프로세스를 종료합니다. 설정하지 않으면 시간 초과가 적용되지 않습니다. |

272| `restartOnCrash` | 서버가 충돌한 후 다시 시작할지 여부. 기본값은 `true`입니다. 충돌한 서버를 다시 시작하지 않고 중지된 상태로 두려면 `false`로 설정하세요. |

271 275

276`restartOnCrash` 및 `shutdownTimeout`은 Claude Code v2.1.205 이상이 필요합니다. v2.1.205 이전에는 구성 스키마가 두 옵션을 모두 허용했지만 둘 중 하나를 설정하면 Claude Code가 시작 시 해당 LSP 서버를 완전히 건너뛰었으며, 그 이유는 `claude --debug` 출력에서만 볼 수 있었습니다.

277

278**동일한 확장자에 대한 여러 서버**: 하나 이상의 활성화된 LSP 서버가 `extensionToLanguage`에서 동일한 파일 확장자를 선언할 때, 서버가 하나의 플러그인에서 오든 다른 플러그인에서 오든, 첫 번째로 등록된 서버가 해당 확장자의 파일을 처리하고 다른 서버는 절대 시작되지 않습니다. `/plugin` 인터페이스는 활성 서버인 플러그인의 이름을 지정하는 경고를 표시합니다.

279

280**초기화에 실패한 서버**: Claude Code는 구성이 유효하지 않은 서버 (예: `command` 또는 `extensionToLanguage`가 누락된 서버)를 건너뛰고, 다른 구성된 서버는 여전히 시작됩니다. `claude --debug`를 실행하여 서버가 건너뛴 이유를 확인하세요.

281

282건너뛴 서버는 파일 확장자를 요청하지 않으므로, 동일한 확장자를 선언하는 다른 유효한 서버 (동일한 플러그인 또는 다른 플러그인에서)가 여전히 해당 파일을 처리합니다. v2.1.205 이전에는 초기화에 실패한 서버가 여전히 확장자를 요청했고 동일한 확장자에 대한 다른 유효한 서버를 차단했습니다.

283

272<Warning>284<Warning>

273 **언어 서버 바이너리를 별도로 설치해야 합니다.** LSP 플러그인은 Claude Code가 언어 서버에 연결하는 방법을 구성하지만, 서버 자체는 포함하지 않습니다. `/plugin` Errors 탭에서 `Executable not found in $PATH`를 보면 언어에 필요한 바이너리를 설치하세요.285 **언어 서버 바이너리를 별도로 설치해야 합니다.** LSP 플러그인은 Claude Code가 언어 서버에 연결하는 방법을 구성하지만, 서버 자체는 포함하지 않습니다. `/plugin` Errors 탭에서 `Executable not found in $PATH`를 보면 언어에 필요한 바이너리를 설치하세요.

274</Warning>286</Warning>

635* **기본값에 추가**: `skills`. 기본 `skills/` 디렉토리는 항상 스캔되며, `skills`에 나열된 디렉토리는 함께 로드됩니다. 예외: [소스가 마켓플레이스 루트로 확인되는 마켓플레이스 항목](/ko/plugin-marketplaces#advanced-plugin-entries)의 경우 특정 서브디렉토리를 선언하면 기본 `skills/` 스캔을 대체합니다.647* **기본값에 추가**: `skills`. 기본 `skills/` 디렉토리는 항상 스캔되며, `skills`에 나열된 디렉토리는 함께 로드됩니다. 예외: [소스가 마켓플레이스 루트로 확인되는 마켓플레이스 항목](/ko/plugin-marketplaces#advanced-plugin-entries)의 경우 특정 서브디렉토리를 선언하면 기본 `skills/` 스캔을 대체합니다.

636* **자체 병합 규칙**: [hooks](#hooks), [MCP servers](#mcp-servers) 및 [LSP servers](#lsp-servers). 각 섹션에서 여러 소스가 어떻게 결합되는지 참조하세요.648* **자체 병합 규칙**: [hooks](#hooks), [MCP servers](#mcp-servers) 및 [LSP servers](#lsp-servers). 각 섹션에서 여러 소스가 어떻게 결합되는지 참조하세요.

637 649

638플러그인에 기본 폴더와 일치하는 매니페스트 키가 모두 있으면 Claude Code v2.1.140 이상은 `/doctor`, `claude plugin list` 및 `/plugin` 상세 보기에서 무시된 폴더에 플래그를 지정합니다. 플러그인은 여전히 매니페스트 경로를 사용하여 로드됩니다. 매니페스트 키가 기본 폴더를 가리킬 때는 경고가 표시되지 않습니다 (예: `"commands": ["./commands/deploy.md"]`). 이 경우 폴더가 명시적으로 처리되기 때문입니다.650플러그인에 기본 폴더와 일치하는 매니페스트 키가 모두 있으면 Claude Code v2.1.140 이상은 `claude plugin list` 및 `/plugin` 상세 보기에서 무시된 폴더에 플래그를 지정합니다. 플러그인은 여전히 매니페스트 경로를 사용하여 로드됩니다. 매니페스트 키가 기본 폴더를 가리킬 때는 경고가 표시되지 않습니다 (예: `"commands": ["./commands/deploy.md"]`). 이 경우 폴더가 명시적으로 처리되기 때문입니다.

639 651

640모든 경로 필드의 경우:652모든 경로 필드의 경우:

641 653

673 685

674**`${CLAUDE_PLUGIN_DATA}`**: 업데이트 후에도 유지되는 플러그인 상태를 위한 영구 디렉토리입니다. `node_modules` 또는 Python 가상 환경과 같은 설치된 종속성, 생성된 코드, 캐시 및 플러그인 버전 전체에서 유지되어야 하는 기타 파일에 사용하세요. 이 변수가 처음 참조될 때 디렉토리가 자동으로 생성됩니다.686**`${CLAUDE_PLUGIN_DATA}`**: 업데이트 후에도 유지되는 플러그인 상태를 위한 영구 디렉토리입니다. `node_modules` 또는 Python 가상 환경과 같은 설치된 종속성, 생성된 코드, 캐시 및 플러그인 버전 전체에서 유지되어야 하는 기타 파일에 사용하세요. 이 변수가 처음 참조될 때 디렉토리가 자동으로 생성됩니다.

675 687

676**`${CLAUDE_PROJECT_DIR}`**: 프로젝트 루트입니다. 이는 hook이 `CLAUDE_PROJECT_DIR` 변수에서 받는 것과 동일한 디렉토리입니다. 프로젝트 로컬 스크립트 또는 구성 파일을 참조하는 데 사용하세요. 공백이 있는 경로를 처리하기 위해 따옴표로 감싸세요 (예: `"${CLAUDE_PROJECT_DIR}/scripts/server.sh"`). MCP 서버는 MCP `roots/list` 요청을 호출할 수도 있으며, 이는 Claude Code가 시작된 디렉토리를 반환합니다.688**`${CLAUDE_PROJECT_DIR}`**: 프로젝트 루트입니다. 이는 hook이 `CLAUDE_PROJECT_DIR` 변수에서 받는 것과 동일한 디렉토리입니다. 프로젝트 로컬 스크립트 또는 구성 파일을 참조하는 데 사용하세요. 공백이 있는 경로를 처리하기 위해 따옴표로 감싸세요 (예: `"${CLAUDE_PROJECT_DIR}/scripts/server.sh"`).

689

690MCP 서버는 또한 `roots/list` 요청을 호출하여 런타임에 세션의 작업 디렉토리를 읽을 수 있습니다. [`roots/list`가 반환하는 것과 Claude Code가 서버에 변경을 알리는 시기](/ko/mcp#option-3-add-a-local-stdio-server)를 참조하세요.

677 691

678```json theme={null}692```json theme={null}

679{693{

prompt-caching.md +5 −5

Details

50캐싱은 서버 측에서 발생하며, 모델을 제공하는 인프라에서 발생합니다. 그 위치는 인증 방식에 따라 다릅니다:50캐싱은 서버 측에서 발생하며, 모델을 제공하는 인프라에서 발생합니다. 그 위치는 인증 방식에 따라 다릅니다:

51 51

52* **API 키, Claude 구독 또는 [Claude Platform on AWS](/ko/claude-platform-on-aws)**: 캐시는 Anthropic의 인프라에 있으며 [Claude API](https://platform.claude.com/docs)를 통해 액세스됩니다.52* **API 키, Claude 구독 또는 [Claude Platform on AWS](/ko/claude-platform-on-aws)**: 캐시는 Anthropic의 인프라에 있으며 [Claude API](https://platform.claude.com/docs)를 통해 액세스됩니다.

~~53* **Bedrock 또는 Vertex AI**: 캐시는 클라우드 제공자의 제공 인프라에 있습니다.~~53* **Amazon Bedrock 또는 Google Cloud의 Agent Platform**: 캐시는 클라우드 제공자의 제공 인프라에 있습니다.

~~54* **Foundry**: 요청은 Anthropic의 인프라로 라우팅됩니다.~~54* **Microsoft Foundry**: 요청은 Anthropic의 인프라로 라우팅됩니다.

55* **사용자 정의 `ANTHROPIC_BASE_URL` 또는 [LLM gateway](/ko/llm-gateway)**: 캐시는 요청이 전달되는 위치에 있으며, 캐싱이 작동하는지 여부는 게이트웨이에 따라 다릅니다.55* **사용자 정의 `ANTHROPIC_BASE_URL` 또는 [LLM gateway](/ko/llm-gateway)**: 캐시는 요청이 전달되는 위치에 있으며, 캐싱이 작동하는지 여부는 게이트웨이에 따라 다릅니다.

56 56

57각 제공자가 저장하고 처리하는 내용은 [데이터 사용](/ko/data-usage)을 참조하세요. 캐시가 어디에 있든 항목은 비활성 기간 후에 만료되며, 아래의 [캐시 수명](#cache-lifetime)에서 TTL과 연장 방법을 다룹니다.57각 제공자가 저장하고 처리하는 내용은 [데이터 사용](/ko/data-usage)을 참조하세요. 캐시가 어디에 있든 항목은 비활성 기간 후에 만료되며, 아래의 [캐시 수명](#cache-lifetime)에서 TTL과 연장 방법을 다룹니다.

106도구 정의는 시스템 프롬프트 계층에 있으므로 요청 간에 도구 정의 집합이 변경되면 캐시가 무효화됩니다. [advisor 도구](/ko/advisor)를 토글하는 것은 예외입니다: 해당 정의는 캐시 중단점 이후에 있으므로 `/advisor`를 활성화 또는 비활성화하면 캐시된 프리픽스가 그대로 유지됩니다. [MCP 서버](/ko/mcp) 변경이 이를 수행하는지 여부는 해당 도구가 [도구 검색](/ko/mcp#scale-with-mcp-tool-search)으로 연기되는지 또는 프리픽스에 로드되는지에 따라 달라집니다:106도구 정의는 시스템 프롬프트 계층에 있으므로 요청 간에 도구 정의 집합이 변경되면 캐시가 무효화됩니다. [advisor 도구](/ko/advisor)를 토글하는 것은 예외입니다: 해당 정의는 캐시 중단점 이후에 있으므로 `/advisor`를 활성화 또는 비활성화하면 캐시된 프리픽스가 그대로 유지됩니다. [MCP 서버](/ko/mcp) 변경이 이를 수행하는지 여부는 해당 도구가 [도구 검색](/ko/mcp#scale-with-mcp-tool-search)으로 연기되는지 또는 프리픽스에 로드되는지에 따라 달라집니다:

107 107

108* **연기된 도구**, 지원되는 모델의 기본값: 서버 연결, 연결 해제 또는 도구 목록 변경은 새로운 콘텐츠만 추가하고 이미 캐시된 항목을 방해하지 않습니다.108* **연기된 도구**, 지원되는 모델의 기본값: 서버 연결, 연결 해제 또는 도구 목록 변경은 새로운 콘텐츠만 추가하고 이미 캐시된 항목을 방해하지 않습니다.

109* **프리픽스에 로드된 도구**: 이에 대한 모든 변경은 캐시를 무효화합니다. 이는 [도구 검색을 사용할 수 없거나 비활성화](/ko/mcp#configure-tool-search)된 경우(예: Haiku 모델, Vertex AI 또는 사용자 정의 `ANTHROPIC_BASE_URL` 게이트웨이)에 발생합니다. 또한 [`alwaysLoad`](/ko/mcp#exempt-a-server-from-deferral)로 표시된 서버 또는 도구, 그리고 [임계값 기반 로딩](/ko/mcp#configure-tool-search)으로 유지되는 정의에 대해서도 발생합니다.109* **프리픽스에 로드된 도구**: 이에 대한 모든 변경은 캐시를 무효화합니다. 이는 [도구 검색을 사용할 수 없거나 비활성화](/ko/mcp#configure-tool-search)된 경우(예: Haiku 모델, Google Cloud의 Agent Platform 또는 사용자 정의 `ANTHROPIC_BASE_URL` 게이트웨이)에 발생합니다. 또한 [`alwaysLoad`](/ko/mcp#exempt-a-server-from-deferral)로 표시된 서버 또는 도구, 그리고 [임계값 기반 로딩](/ko/mcp#configure-tool-search)으로 유지되는 정의에 대해서도 발생합니다.

110 110

111도구가 프리픽스에 로드될 때 무효화의 가장 일반적인 원인은 세션 중에 서버가 연결 또는 연결 해제되는 것입니다. 이는 사용자의 조치 없이 발생할 수 있습니다: stdio 서버의 프로세스가 종료되거나, HTTP 세션이 만료되거나, 서버가 [일시적 오류 후 자동으로 재연결](/ko/mcp#automatic-reconnection)됩니다. 연결된 서버는 도구 목록을 변경하는 [동적 도구 업데이트](/ko/mcp#dynamic-tool-updates)를 푸시할 수도 있습니다.111도구가 프리픽스에 로드될 때 무효화의 가장 일반적인 원인은 세션 중에 서버가 연결 또는 연결 해제되는 것입니다. 이는 사용자의 조치 없이 발생할 수 있습니다: stdio 서버의 프로세스가 종료되거나, HTTP 세션이 만료되거나, 서버가 [일시적 오류 후 자동으로 재연결](/ko/mcp#automatic-reconnection)됩니다. 연결된 서버는 도구 목록을 변경하는 [동적 도구 업데이트](/ko/mcp#dynamic-tool-updates)를 푸시할 수도 있습니다.

112 112

235 API 키 또는 타사 제공자에서235 API 키 또는 타사 제공자에서

236</h3>236</h3>

237 237

238API 키, Bedrock, Vertex, Foundry 또는 AWS의 Claude Platform에서 토큰당 요금을 지불하므로 TTL은 기본적으로 더 저렴한 5분으로 유지됩니다. [1시간 TTL](https://platform.claude.com/docs/en/build-with-claude/prompt-caching#1-hour-cache-duration)을 선택하려면 `ENABLE_PROMPT_CACHING_1H=1`을 설정합니다.238API 키, Amazon Bedrock, Google Cloud의 Agent Platform, Microsoft Foundry 또는 AWS의 Claude Platform에서 토큰당 요금을 지불하므로 TTL은 기본적으로 더 저렴한 5분으로 유지됩니다. [1시간 TTL](https://platform.claude.com/docs/en/build-with-claude/prompt-caching#1-hour-cache-duration)을 선택하려면 `ENABLE_PROMPT_CACHING_1H=1`을 설정합니다.

239 239

240Bedrock에서 프롬프트 캐싱 지원, 최소 캐시 가능 프리픽스 길이 및 1시간 TTL 가용성은 모두 모델에 따라 다릅니다. 캐시 토큰 수가 0으로 유지되면 Bedrock 설명서에서 [지원되는 모델, 지역 및 제한](https://docs.aws.amazon.com/bedrock/latest/userguide/prompt-caching.html#prompt-caching-models)을 확인하세요.240Amazon Bedrock에서 프롬프트 캐싱 지원, 최소 캐시 가능 프리픽스 길이 및 1시간 TTL 가용성은 모두 모델에 따라 다릅니다. 캐시 토큰 수가 0으로 유지되면 Amazon Bedrock 설명서에서 [지원되는 모델, 지역 및 제한](https://docs.aws.amazon.com/bedrock/latest/userguide/prompt-caching.html#prompt-caching-models)을 확인하세요.

241 241

242<h3 id="override-the-ttl">242<h3 id="override-the-ttl">

243 TTL 재정의243 TTL 재정의

quickstart.md +1 −1

Details

105 105

106* [Claude Pro, Max, Team 또는 Enterprise](https://claude.com/pricing?utm_source=claude_code\&utm_medium=docs\&utm_content=quickstart_login) (권장)106* [Claude Pro, Max, Team 또는 Enterprise](https://claude.com/pricing?utm_source=claude_code\&utm_medium=docs\&utm_content=quickstart_login) (권장)

107* [Claude Console](https://console.anthropic.com/) (선불 크레딧이 있는 API 액세스). 처음 로그인할 때 비용 추적을 위해 Console에서 "Claude Code" 워크스페이스가 자동으로 생성됩니다.107* [Claude Console](https://console.anthropic.com/) (선불 크레딧이 있는 API 액세스). 처음 로그인할 때 비용 추적을 위해 Console에서 "Claude Code" 워크스페이스가 자동으로 생성됩니다.

108* [Amazon Bedrock, Google Vertex AI 또는 Microsoft Foundry](/ko/third-party-integrations) (엔터프라이즈 클라우드 제공자)108* [Amazon Bedrock, Google Cloud의 Agent Platform 또는 Microsoft Foundry](/ko/third-party-integrations) (엔터프라이즈 클라우드 제공자)

109* 조직에서 운영하는 자체 호스팅 [Claude 앱 게이트웨이](/ko/claude-apps-gateway): 관리자가 게이트웨이 URL을 미리 구성하고, `/login`을 입력하면 **Cloud gateway** 화면에서 직접 열려 기업 SSO로 로그인할 수 있습니다.109* 조직에서 운영하는 자체 호스팅 [Claude 앱 게이트웨이](/ko/claude-apps-gateway): 관리자가 게이트웨이 URL을 미리 구성하고, `/login`을 입력하면 **Cloud gateway** 화면에서 직접 열려 기업 SSO로 로그인할 수 있습니다.

110 110

111로그인하면 자격 증명이 저장되고 다시 로그인할 필요가 없습니다.111로그인하면 자격 증명이 저장되고 다시 로그인할 필요가 없습니다.

remote-control.md +19 −4

Details

16 16

17* **전체 로컬 환경을 원격으로 사용**: 파일 시스템, [MCP servers](/ko/mcp), 도구 및 프로젝트 구성이 모두 사용 가능하게 유지되며, `@`를 입력하면 로컬 프로젝트의 파일 경로가 자동 완성됩니다17* **전체 로컬 환경을 원격으로 사용**: 파일 시스템, [MCP servers](/ko/mcp), 도구 및 프로젝트 구성이 모두 사용 가능하게 유지되며, `@`를 입력하면 로컬 프로젝트의 파일 경로가 자동 완성됩니다

18* **두 표면에서 동시에 작업**: 대화가 모든 연결된 기기에서 동기화되므로 터미널, 브라우저 및 휴대폰에서 메시지를 교대로 보낼 수 있습니다18* **두 표면에서 동시에 작업**: 대화가 모든 연결된 기기에서 동기화되므로 터미널, 브라우저 및 휴대폰에서 메시지를 교대로 보낼 수 있습니다

19* **휴대폰 또는 브라우저에서 이미지 및 파일 전송**: Claude 앱 또는 claude.ai/code에서 첨부 파일을 추가하면 Claude Code가 이를 컴퓨터에 다운로드하고 캡션 유무와 관계없이 `@` 파일 참조로 Claude에 전달합니다. {/* min-version: 2.1.202 */}v2.1.202 이전에는 Claude Code가 캡션 없이 전송된 첨부 파일을 세션에 도달하기 전에 삭제할 수 있었습니다.

19* **중단 극복**: 노트북이 절전 모드로 전환되거나 네트워크가 끊어지면 컴퓨터가 다시 온라인 상태가 될 때 세션이 자동으로 다시 연결됩니다20* **중단 극복**: 노트북이 절전 모드로 전환되거나 네트워크가 끊어지면 컴퓨터가 다시 온라인 상태가 될 때 세션이 자동으로 다시 연결됩니다

20 21

21클라우드 인프라에서 실행되는 [웹의 Claude Code](/ko/claude-code-on-the-web)와 달리 Remote Control 세션은 컴퓨터에서 직접 실행되며 로컬 파일 시스템과 상호 작용합니다. 웹 및 모바일 인터페이스는 단지 해당 로컬 세션의 창일 뿐입니다.22클라우드 인프라에서 실행되는 [웹의 Claude Code](/ko/claude-code-on-the-web)와 달리 Remote Control 세션은 컴퓨터에서 직접 실행되며 로컬 파일 시스템과 상호 작용합니다. 웹 및 모바일 인터페이스는 단지 해당 로컬 세션의 창일 뿐입니다.

34 35

35* **구독**: Pro, Max, Team 및 Enterprise 요금제에서 사용 가능합니다. API 키는 지원되지 않습니다. Team 및 Enterprise의 경우 Owner가 먼저 [Claude Code 관리자 설정](https://claude.ai/admin-settings/claude-code)에서 Remote Control 토글을 활성화해야 합니다.36* **구독**: Pro, Max, Team 및 Enterprise 요금제에서 사용 가능합니다. API 키는 지원되지 않습니다. Team 및 Enterprise의 경우 Owner가 먼저 [Claude Code 관리자 설정](https://claude.ai/admin-settings/claude-code)에서 Remote Control 토글을 활성화해야 합니다.

36* **인증**: `claude`를 실행하고 아직 로그인하지 않았다면 `/login`을 사용하여 claude.ai를 통해 로그인하세요.37* **인증**: `claude`를 실행하고 아직 로그인하지 않았다면 `/login`을 사용하여 claude.ai를 통해 로그인하세요.

37* **API 엔드포인트**: Amazon Bedrock, Google Vertex AI 또는 Microsoft Foundry에서는 사용할 수 없습니다. {/* min-version: 2.1.196 */}v2.1.196부터 [`ANTHROPIC_BASE_URL`](/ko/env-vars)이 `api.anthropic.com` 이외의 호스트(예: [LLM gateway](/ko/llm-gateway) 또는 프록시)를 가리킬 때도 Remote Control이 비활성화됩니다. Remote Control을 사용하려면 변수를 설정 해제하세요.38* **API 엔드포인트**: Amazon Bedrock, Google Cloud의 Agent Platform 또는 Microsoft Foundry에서는 사용할 수 없습니다. {/* min-version: 2.1.196 */}v2.1.196부터 [`ANTHROPIC_BASE_URL`](/ko/env-vars)이 `api.anthropic.com` 이외의 호스트(예: [LLM gateway](/ko/llm-gateway) 또는 프록시)를 가리킬 때도 Remote Control이 비활성화됩니다. Remote Control을 사용하려면 변수를 설정 해제하세요.

38* **작업 공간 신뢰**: 작업 공간 신뢰 대화를 수락하려면 프로젝트 디렉토리에서 최소한 한 번 `claude`를 실행하세요.39* **작업 공간 신뢰**: 작업 공간 신뢰 대화를 수락하려면 프로젝트 디렉토리에서 최소한 한 번 `claude`를 실행하세요.

39 40

40<h2 id="start-a-remote-control-session">41<h2 id="start-a-remote-control-session">

59 | ----------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |60 | ----------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

61 | `--remote-control-session-name-prefix <prefix>` | 명시적 이름이 설정되지 않았을 때 자동 생성된 세션 이름의 접두사입니다. 기본값은 컴퓨터의 호스트 이름이며, `myhost-graceful-unicorn`과 같은 이름을 생성합니다. 동일한 효과를 위해 `CLAUDE_REMOTE_CONTROL_SESSION_NAME_PREFIX`를 설정하세요. |62 | `--remote-control-session-name-prefix <prefix>` | 명시적 이름이 설정되지 않았을 때 자동 생성된 세션 이름의 접두사입니다. 기본값은 컴퓨터의 호스트 이름이며, `myhost-graceful-unicorn`과 같은 이름을 생성합니다. 동일한 효과를 위해 `CLAUDE_REMOTE_CONTROL_SESSION_NAME_PREFIX`를 설정하세요. |

63 | `-c`, `--continue` | {/* min-version: 2.1.200 */}이 디렉토리에서 시작한 가장 최근의 Remote Control 세션을 재개하여 새로운 세션을 만드는 대신 사용합니다. `--session-id`, `--spawn`, `--capacity` 또는 `--create-session-in-dir`과 함께 사용할 수 없습니다. Claude Code v2.1.200 이상이 필요하며, 이전 버전은 이 플래그를 알 수 없는 인수로 거부합니다. |

64 | `--session-id <id>` | {/* min-version: 2.1.200 */}ID로 특정 Remote Control 세션을 재개합니다. `--continue`, `--spawn`, `--capacity` 또는 `--create-session-in-dir`과 함께 사용할 수 없습니다. Claude Code v2.1.200 이상이 필요하며, 이전 버전은 이 플래그를 알 수 없는 인수로 거부합니다. |

62 | `--spawn <mode>` | 서버가 세션을 생성하는 방식입니다.<br />• `same-dir` (기본값): 모든 세션이 현재 작업 디렉토리를 공유하므로 동일한 파일을 편집할 때 충돌할 수 있습니다.<br />• `worktree`: 각 온디맨드 세션은 자체 [git worktree](/ko/worktrees)를 가져옵니다. git 저장소가 필요합니다.<br />• `session`: 단일 세션 모드입니다. 정확히 하나의 세션을 제공하고 추가 연결을 거부합니다. 시작 시에만 설정합니다.<br />런타임에 `w`를 눌러 `same-dir`과 `worktree` 사이를 전환하세요. |65 | `--spawn <mode>` | 서버가 세션을 생성하는 방식입니다.<br />• `same-dir` (기본값): 모든 세션이 현재 작업 디렉토리를 공유하므로 동일한 파일을 편집할 때 충돌할 수 있습니다.<br />• `worktree`: 각 온디맨드 세션은 자체 [git worktree](/ko/worktrees)를 가져옵니다. git 저장소가 필요합니다.<br />• `session`: 단일 세션 모드입니다. 정확히 하나의 세션을 제공하고 추가 연결을 거부합니다. 시작 시에만 설정합니다.<br />런타임에 `w`를 눌러 `same-dir`과 `worktree` 사이를 전환하세요. |

67 | `--[no-]create-session-in-dir` | 서버가 시작할 때 현재 디렉토리에 하나의 세션을 미리 생성하여 즉시 입력할 수 있는 위치를 제공합니다. `worktree` 모드에서 이 세션은 현재 디렉토리에 유지되고 온디맨드 세션은 격리된 worktree를 가져옵니다. 기본적으로 켜져 있으며, `--no-create-session-in-dir`을 전달하여 아무것도 없이 시작할 수 있습니다. |

66 </Tab>70 </Tab>

149 모든 세션에 대해 Remote Control 활성화153 모든 세션에 대해 Remote Control 활성화

150</h3>154</h3>

151 155

152기본적으로 Remote Control은 `claude remote-control`, `claude --remote-control` 또는 `/remote-control`을 명시적으로 실행할 때만 활성화됩니다. 모든 대화형 세션에 대해 자동으로 활성화하려면 Claude Code 내에서 `/config`를 실행하고 **모든 세션에 대해 Remote Control 활성화**를 `true`로 설정하세요. 비활성화하려면 `false`로 설정하거나, 조직의 기본값을 따르려면 설정하지 않은 상태로 두세요. Desktop 앱에서는 **설정 → Claude Code → 기본적으로 원격 제어 활성화**에서도 전환할 수 있습니다.156Remote Control은 `claude remote-control`, `claude --remote-control` 또는 `/remote-control`을 명시적으로 실행할 때만 활성화되며, 자동 연결이 켜져 있지 않으면 활성화되지 않습니다. 모든 대화형 세션에 대해 자동으로 활성화하려면 Claude Code 내에서 `/config`를 실행하고 **모든 세션에 대해 Remote Control 활성화**를 `true`로 설정하세요. 비활성화하려면 `false`로 설정하거나, 조직의 기본값을 따르려면 설정하지 않은 상태로 두세요. Desktop 앱에서는 **설정 → Claude Code → 기본적으로 원격 제어 활성화**에서도 전환할 수 있습니다. {/* min-version: 2.1.203 */}[VS Code 확장](/ko/vs-code#use-the-prompt-box)에서는 동일한 토글이 명령 메뉴의 설정 섹션에 **모든 세션에 대해 Remote Control 활성화**로 나타나며, Claude Code v2.1.203 이상이 필요합니다.

153 157

154이 설정이 켜져 있으면 각 대화형 Claude Code 프로세스는 하나의 원격 세션을 등록합니다. 여러 인스턴스를 실행하면 각각 자체 환경 및 세션을 가져옵니다. 단일 프로세스에서 여러 동시 세션을 실행하려면 [서버 모드](#start-a-remote-control-session)를 대신 사용하세요.158이 설정이 켜져 있으면 각 대화형 Claude Code 프로세스는 하나의 원격 세션을 등록합니다. 여러 인스턴스를 실행하면 각각 자체 환경 및 세션을 가져옵니다. 단일 프로세스에서 여러 동시 세션을 실행하려면 [서버 모드](#start-a-remote-control-session)를 대신 사용하세요.

155 159

280* **로컬 프로세스는 계속 실행되어야 함**: Remote Control은 로컬 프로세스로 실행됩니다. 터미널을 닫거나, VS Code를 종료하거나, 다른 방식으로 `claude` 프로세스를 중지하면 세션이 종료됩니다.284* **로컬 프로세스는 계속 실행되어야 함**: Remote Control은 로컬 프로세스로 실행됩니다. 터미널을 닫거나, VS Code를 종료하거나, 다른 방식으로 `claude` 프로세스를 중지하면 세션이 종료됩니다.

281* **장시간 네트워크 중단**: 컴퓨터가 켜져 있지만 약 10분 이상 네트워크에 도달할 수 없으면 세션이 시간 초과되고 프로세스가 종료됩니다. `claude remote-control`을 다시 실행하여 새 세션을 시작하세요.285* **장시간 네트워크 중단**: 컴퓨터가 켜져 있지만 약 10분 이상 네트워크에 도달할 수 없으면 세션이 시간 초과되고 프로세스가 종료됩니다. `claude remote-control`을 다시 실행하여 새 세션을 시작하세요.

282* **Ultraplan이 Remote Control 연결 해제**: [ultraplan](/ko/ultraplan) 세션을 시작하면 활성 Remote Control 세션이 연결 해제됩니다. 두 기능 모두 claude.ai/code 인터페이스를 차지하고 한 번에 하나만 연결될 수 있기 때문입니다.286* **Ultraplan이 Remote Control 연결 해제**: [ultraplan](/ko/ultraplan) 세션을 시작하면 활성 Remote Control 세션이 연결 해제됩니다. 두 기능 모두 claude.ai/code 인터페이스를 차지하고 한 번에 하나만 연결될 수 있기 때문입니다.

283* **일부 명령은 로컬 전용**: `/plugin` 또는 `/resume`과 같이 터미널에서 대화형 선택기를 여는 명령은 로컬 CLI에서만 작동합니다. 다음은 모바일 및 웹에서 작동합니다:287* **일부 명령은 로컬 전용**: `/plugin` 또는 `/resume`과 같이 터미널 인터페이스에서만 실행되는 명령은 인수를 전달하는지 여부와 관계없이 로컬 CLI에서만 작동합니다. 다음은 모바일 및 웹에서 작동합니다:

284 * 텍스트 출력 명령: `/compact`, `/clear`, `/context`, `/usage`, `/exit`, `/usage-credits`, `/recap`, `/reload-plugins`288 * 텍스트 출력 명령: `/compact`, `/clear`, `/context`, `/usage`, `/exit`, `/usage-credits`, `/recap`, `/reload-plugins`

289 * `/model`, `/effort`, `/fast`, `/color`, `/rename`: 값을 인수로 전달합니다. 예를 들어 `/model sonnet` 또는 `/effort high`입니다. 모바일 및 웹에서 `/model`과 `/effort`는 터미널 선택기 또는 슬라이더 대신 인수를 사용합니다.

285 * {/* min-version: 2.1.166 */}`/mcp`, v2.1.166부터: 선택기를 열지 않고 서버 상태의 텍스트 요약을 반환하며, `reconnect`, `enable`, `disable` [하위 명령](/ko/commands#all-commands)을 허용합니다. 로컬 CLI와 달리, 서버 이름 없이 `/mcp reconnect`를 실행하면 실패했거나 인증이 필요한 모든 서버를 다시 연결합니다.290 * {/* min-version: 2.1.166 */}`/mcp`, v2.1.166부터: 선택기를 열지 않고 서버 상태의 텍스트 요약을 반환하며, `reconnect`, `enable`, `disable` [하위 명령](/ko/commands#all-commands)을 허용합니다. 로컬 CLI와 달리, 서버 이름 없이 `/mcp reconnect`를 실행하면 실패했거나 인증이 필요한 모든 서버를 다시 연결합니다.

286 * {/* min-version: 2.1.181 */}`/config`, v2.1.181부터: `key=value`를 전달하여 설정을 지정하거나, 인수 없이 실행하여 설정할 수 있는 키를 나열합니다.291 * {/* min-version: 2.1.181 */}`/config`, v2.1.181부터: `key=value`를 전달하여 설정을 지정하거나, 인수 없이 실행하여 설정할 수 있는 키를 나열합니다.

287 292

323 "Remote Control은 api.anthropic.com을 통해 Claude를 사용할 때만 사용 가능합니다"328 "Remote Control은 api.anthropic.com을 통해 Claude를 사용할 때만 사용 가능합니다"

324</h3>329</h3>

325 330

326세션이 Anthropic API와 직접 통신하지 않으므로 페어링할 claude.ai 백엔드가 없습니다. 이는 Amazon Bedrock, Google Vertex AI, Microsoft Foundry에서 발생합니다. {/* min-version: 2.1.196 */}v2.1.196부터는 [`ANTHROPIC_BASE_URL`](/ko/env-vars)이 `api.anthropic.com` 이외의 호스트(예: [LLM 게이트웨이](/ko/llm-gateway) 또는 프록시)를 가리킬 때도 발생하며, claude.ai로 로그인한 경우에도 마찬가지입니다. `ANTHROPIC_BASE_URL`을 설정 해제하고 세션을 다시 시작하여 Remote Control을 사용하세요.331세션이 Anthropic API와 직접 통신하지 않으므로 페어링할 claude.ai 백엔드가 없습니다. 이는 Amazon Bedrock, Google Cloud의 Agent Platform, Microsoft Foundry에서 발생합니다. {/* min-version: 2.1.196 */}v2.1.196부터는 [`ANTHROPIC_BASE_URL`](/ko/env-vars)이 `api.anthropic.com` 이외의 호스트(예: [LLM 게이트웨이](/ko/llm-gateway) 또는 프록시)를 가리킬 때도 발생하며, claude.ai로 로그인한 경우에도 마찬가지입니다. `ANTHROPIC_BASE_URL`을 설정 해제하고 세션을 다시 시작하여 Remote Control을 사용하세요.

327 332

328<h3 id="remote-control-is-disabled-by-your-organization’s-policy">333<h3 id="remote-control-is-disabled-by-your-organization’s-policy">

329 "Remote Control은 조직의 정책에 의해 비활성화되었습니다"334 "Remote Control은 조직의 정책에 의해 비활성화되었습니다"

352* 네트워크 또는 프록시 문제: 방화벽 또는 프록시가 아웃바운드 HTTPS 요청을 차단할 수 있습니다. Remote Control은 포트 443의 Anthropic API에 대한 액세스가 필요합니다.357* 네트워크 또는 프록시 문제: 방화벽 또는 프록시가 아웃바운드 HTTPS 요청을 차단할 수 있습니다. Remote Control은 포트 443의 Anthropic API에 대한 액세스가 필요합니다.

353* 세션 생성 실패: `Session creation failed — see debug log`도 표시되면 설정 초기에 실패가 발생했습니다. 구독이 활성 상태인지 확인하세요.358* 세션 생성 실패: `Session creation failed — see debug log`도 표시되면 설정 초기에 실패가 발생했습니다. 구독이 활성 상태인지 확인하세요.

354 359

360<h3 id="couldn’t-reconnect-to-your-remote-control-session">

361 "Remote Control 세션에 다시 연결할 수 없습니다"

362</h3>

363

364`claude --resume` 또는 `claude --continue`로 대화를 재개할 때 Claude Code는 해당 대화에 기록된 Remote Control 세션에 다시 연결합니다. 이 메시지는 네트워크 중단 또는 서버 오류와 같이 일시적일 수 있는 이유로 재연결이 실패했음을 의미하므로 Claude Code는 원격 세션이 여전히 존재하는지 확인할 수 없습니다. 서버가 이전 세션이 더 이상 존재하지 않음을 확인하면 Claude Code는 이 메시지를 표시하지 않고 새 Remote Control 세션을 생성합니다.

365

366로컬 세션은 Remote Control 없이 계속 실행됩니다. `/remote-control`을 실행하여 연결을 다시 시도하거나 `--resume` 없이 Claude Code를 시작하여 새 Remote Control 세션을 생성하세요.

367

368{/* min-version: 2.1.200 */}v2.1.200 이전에는 재연결 실패로 인해 이 메시지를 표시하는 대신 새 Remote Control 세션이 생성되었으며, 이로 인해 claude.ai/code의 세션 목록에 추가 세션이 남겨졌습니다.

369

355<h3 id="your-organization-requires-trusted-devices-for-remote-control-but-this-device-is-not-enrolled">370<h3 id="your-organization-requires-trusted-devices-for-remote-control-but-this-device-is-not-enrolled">

356 "조직에서 Remote Control에 신뢰할 수 있는 기기를 요구하지만 이 기기는 등록되지 않았습니다"371 "조직에서 Remote Control에 신뢰할 수 있는 기기를 요구하지만 이 기기는 등록되지 않았습니다"

357</h3>372</h3>

routines.md +1 −1

Details

416 416

417CLI는 요구 사항 중 하나가 충족되지 않으면 `/schedule`을 숨깁니다. 따라서 명령 메뉴는 입력 중에 `명령이 일치하지 않음 "/schedule"`을 표시하고, 제출하면 `알 수 없는 명령: /schedule`을 반환합니다. 원인은 일반적으로 다음 중 하나입니다.417CLI는 요구 사항 중 하나가 충족되지 않으면 `/schedule`을 숨깁니다. 따라서 명령 메뉴는 입력 중에 `명령이 일치하지 않음 "/schedule"`을 표시하고, 제출하면 `알 수 없는 명령: /schedule`을 반환합니다. 원인은 일반적으로 다음 중 하나입니다.

418 418

419* Console API 키 또는 Bedrock, Vertex, Foundry와 같은 클라우드 공급자로 인증되어 있습니다. `/schedule`은 claude.ai 구독 로그인이 필요합니다. 셸에서 `ANTHROPIC_API_KEY` 또는 `ANTHROPIC_AUTH_TOKEN`이 설정되어 있거나 `settings.json`에서 `apiKeyHelper`가 설정되어 있으면 먼저 제거하세요. 이들이 claude.ai 로그인보다 우선하기 때문입니다.419* Console API 키 또는 Amazon Bedrock, Google Cloud의 Agent Platform, Microsoft Foundry와 같은 클라우드 공급자로 인증되어 있습니다. `/schedule`은 claude.ai 구독 로그인이 필요합니다. 셸에서 `ANTHROPIC_API_KEY` 또는 `ANTHROPIC_AUTH_TOKEN`이 설정되어 있거나 `settings.json`에서 `apiKeyHelper`가 설정되어 있으면 먼저 제거하세요. 이들이 claude.ai 로그인보다 우선하기 때문입니다.

420* `DISABLE_TELEMETRY`, `DO_NOT_TRACK`, `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC` 또는 `DISABLE_GROWTHBOOK`이 셸 환경 또는 [`settings.json` 파일](/ko/settings#available-settings)의 `env` 블록에 설정되어 있습니다. 이들은 `/schedule`이 의존하는 기능 플래그 가져오기를 비활성화합니다.420* `DISABLE_TELEMETRY`, `DO_NOT_TRACK`, `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC` 또는 `DISABLE_GROWTHBOOK`이 셸 환경 또는 [`settings.json` 파일](/ko/settings#available-settings)의 `env` 블록에 설정되어 있습니다. 이들은 `/schedule`이 의존하는 기능 플래그 가져오기를 비활성화합니다.

421* Claude Code 웹 세션 내부에 있습니다. 대신 [웹 UI](https://claude.ai/code/routines)에서 루틴을 관리하세요.421* Claude Code 웹 세션 내부에 있습니다. 대신 [웹 UI](https://claude.ai/code/routines)에서 루틴을 관리하세요.

422* {/* min-version: 2.1.81 */}CLI가 v2.1.81보다 오래되었습니다. `claude update`를 실행하세요.422* {/* min-version: 2.1.81 */}CLI가 v2.1.81보다 오래되었습니다. `claude update`를 실행하세요.

sandboxing.md +1 −1

Details

237 237

238`mask`를 사용하면 샌드박싱된 명령은 실제 값 대신 세션별 센티널 값을 봅니다. 요청이 자격증명의 `injectHosts` 중 하나에 대해 샌드박스를 떠날 때 [샌드박스 프록시](#network-isolation)는 센티널을 실제 값으로 바꿉니다. 명령과 이것이 기록하는 모든 것은 실제 자격증명을 보유하지 않지만 요청은 여전히 인증됩니다.238`mask`를 사용하면 샌드박싱된 명령은 실제 값 대신 세션별 센티널 값을 봅니다. 요청이 자격증명의 `injectHosts` 중 하나에 대해 샌드박스를 떠날 때 [샌드박스 프록시](#network-isolation)는 센티널을 실제 값으로 바꿉니다. 명령과 이것이 기록하는 모든 것은 실제 자격증명을 보유하지 않지만 요청은 여전히 인증됩니다.

239 239

240프록시는 요청 내용 내에서 자격증명을 대체하므로 이를 봐야 합니다. [`network.tlsTerminate`](/ko/settings#sandbox-settings)를 설정하여 프록시가 HTTPS 자체를 종료하도록 합니다. 이 없이는 마스킹이 폐쇄 상태로 실패합니다: 명령은 여전히 센티널만 보지만 센티널이 변경되지 않은 상태로 서버에 도달하고 인증이 실패합니다. Claude Code는 시작 시 및 `/doctor`에서 이 잘못된 구성을 보고합니다.240프록시는 요청 내용 내에서 자격증명을 대체하므로 이를 봐야 합니다. [`network.tlsTerminate`](/ko/settings#sandbox-settings)를 설정하여 프록시가 TLS 자체를 종료하도록 합니다. 이 없이는 마스킹이 폐쇄 상태로 실패합니다: 명령은 여전히 센티널만 보지만 센티널이 변경되지 않은 상태로 서버에 도달하고 인증이 실패합니다. Claude Code는 시작 시 이 잘못된 구성을 보고합니다.

241 241

242아래 예제는 두 개의 토큰을 마스킹합니다. `GH_TOKEN`은 `api.github.com`에 대한 요청에서만 대체되고, `NPM_TOKEN`은 `injectHosts`가 없으며 `network.allowedDomains`의 모든 호스트에 대한 요청에서 대체됩니다. 각 `injectHosts` 항목은 자체적으로 `network.allowedDomains`로 커버되어야 합니다.242아래 예제는 두 개의 토큰을 마스킹합니다. `GH_TOKEN`은 `api.github.com`에 대한 요청에서만 대체되고, `NPM_TOKEN`은 `injectHosts`가 없으며 `network.allowedDomains`의 모든 호스트에 대한 요청에서 대체됩니다. 각 `injectHosts` 항목은 자체적으로 `network.allowedDomains`로 커버되어야 합니다.

243 243

scheduled-tasks.md +6 −4

Details

86동적으로 스케줄된 루프는 다른 작업처럼 [스케줄된 작업 목록](#manage-scheduled-tasks)에 나타나므로 동일한 방식으로 나열하거나 취소할 수 있습니다. [지터 규칙](#jitter)은 적용되지 않지만 [7일 만료](#seven-day-expiry)는 적용됩니다. 루프는 시작 후 7일 후 자동으로 종료됩니다.86동적으로 스케줄된 루프는 다른 작업처럼 [스케줄된 작업 목록](#manage-scheduled-tasks)에 나타나므로 동일한 방식으로 나열하거나 취소할 수 있습니다. [지터 규칙](#jitter)은 적용되지 않지만 [7일 만료](#seven-day-expiry)는 적용됩니다. 루프는 시작 후 7일 후 자동으로 종료됩니다.

87 87

88<Note>88<Note>

~~89 Bedrock, Vertex AI, Microsoft Foundry에서는 간격이 없는 프롬프트가 고정 10분 스케줄로 실행됩니다.~~89 Amazon Bedrock, Google Cloud의 Agent Platform, Microsoft Foundry에서는 간격이 없는 프롬프트가 고정 10분 스케줄로 실행됩니다.

90</Note>90</Note>

91 91

92<h3 id="run-the-built-in-maintenance-prompt">92<h3 id="run-the-built-in-maintenance-prompt">

108단순한 `/loop`는 [동적으로 선택된 간격](#let-claude-choose-the-interval)에서 이 프롬프트를 실행합니다. 고정 스케줄에서 실행하려면 `/loop 15m`과 같이 간격을 추가하세요. 내장 프롬프트를 자신의 기본값으로 바꾸려면 [loop.md로 기본 프롬프트 사용자 정의하기](#customize-the-default-prompt-with-loop-md)를 참조하세요.108단순한 `/loop`는 [동적으로 선택된 간격](#let-claude-choose-the-interval)에서 이 프롬프트를 실행합니다. 고정 스케줄에서 실행하려면 `/loop 15m`과 같이 간격을 추가하세요. 내장 프롬프트를 자신의 기본값으로 바꾸려면 [loop.md로 기본 프롬프트 사용자 정의하기](#customize-the-default-prompt-with-loop-md)를 참조하세요.

109 109

110<Note>110<Note>

111 Bedrock, Vertex AI, Microsoft Foundry에서는 프롬프트가 없는 `/loop`가 유지보수 프롬프트를 실행하는 대신 사용 메시지를 출력합니다.111 Amazon Bedrock, Google Cloud의 Agent Platform, Microsoft Foundry에서는 프롬프트가 없는 `/loop`가 유지보수 프롬프트를 실행하는 대신 사용 메시지를 출력합니다.

112</Note>112</Note>

113 113

114<h3 id="customize-the-default-prompt-with-loop-md">114<h3 id="customize-the-default-prompt-with-loop-md">

136`loop.md`에 대한 편집은 다음 반복에서 적용되므로 루프가 실행 중인 동안 지침을 개선할 수 있습니다. 두 위치 중 어디에도 `loop.md`가 없으면 루프는 내장 유지보수 프롬프트로 폴백됩니다. 파일을 간결하게 유지하세요. 25,000바이트를 초과하는 내용은 잘립니다.136`loop.md`에 대한 편집은 다음 반복에서 적용되므로 루프가 실행 중인 동안 지침을 개선할 수 있습니다. 두 위치 중 어디에도 `loop.md`가 없으면 루프는 내장 유지보수 프롬프트로 폴백됩니다. 파일을 간결하게 유지하세요. 25,000바이트를 초과하는 내용은 잘립니다.

137 137

138<Note>138<Note>

139 Bedrock, Vertex AI, Microsoft Foundry에서는 `loop.md`가 읽혀지지 않으며 프롬프트가 없는 `/loop`가 유지보수 프롬프트를 실행하는 대신 사용 메시지를 출력합니다.139 Amazon Bedrock, Google Cloud의 Agent Platform, Microsoft Foundry에서는 `loop.md`가 읽혀지지 않으며 프롬프트가 없는 `/loop`가 유지보수 프롬프트를 실행하는 대신 사용 메시지를 출력합니다.

140</Note>140</Note>

141 141

142<h3 id="stop-a-loop">142<h3 id="stop-a-loop">

145 145

146`/loop`가 다음 반복을 기다리는 동안 중지하려면 `Esc`를 누르세요. 이는 보류 중인 웨이크업을 지우므로 루프가 다시 실행되지 않습니다. [Claude에게 직접 요청](#manage-scheduled-tasks)하여 스케줄한 작업은 `Esc`의 영향을 받지 않으며 삭제할 때까지 유지됩니다.146`/loop`가 다음 반복을 기다리는 동안 중지하려면 `Esc`를 누르세요. 이는 보류 중인 웨이크업을 지우므로 루프가 다시 실행되지 않습니다. [Claude에게 직접 요청](#manage-scheduled-tasks)하여 스케줄한 작업은 `Esc`의 영향을 받지 않으며 삭제할 때까지 유지됩니다.

147 147

148[자기 속도 모드](#let-claude-choose-the-interval)에서 Claude는 작업이 명백히 완료되면 다음 웨이크업을 스케줄하지 않음으로써 루프를 직접 종료할 수도 있습니다. 고정 간격의 루프는 중지하거나 [7일이 경과](#seven-day-expiry)할 때까지 계속 실행됩니다.148[자기 속도 모드](#let-claude-choose-the-interval)에서 Claude는 작업이 완료되면 루프를 직접 종료할 수도 있습니다. Claude는 `stop: true`로 [`ScheduleWakeup` tool](/ko/tools-reference)을 호출하여 보류 중인 웨이크업을 즉시 취소합니다. 반복이 재스케줄링이나 중지 없이 끝나면 Claude Code는 약 20분 후에 하나의 폴백 웨이크업을 스케줄하고 해당 반복이 재스케줄링하지 않으면 루프를 종료합니다. v2.1.202 이전에는 재스케줄링하지 않는 것이 Claude가 루프를 직접 종료할 수 있는 유일한 방법이었습니다.

149

150고정 간격의 루프는 중지하거나 [7일이 경과](#seven-day-expiry)할 때까지 계속 실행됩니다.

149 151

150<h2 id="set-a-one-time-reminder">152<h2 id="set-a-one-time-reminder">

151 일회성 알림 설정하기153 일회성 알림 설정하기

security-guidance.md +1 −1

Details

219/plugin uninstall security-guidance@claude-plugins-official219/plugin uninstall security-guidance@claude-plugins-official

220```220```

221 221

222플러그인이 프로젝트의 `.claude/settings.json`을 통해 활성화된 경우 `/plugin`에서 비활성화하면 체크인된 파일을 편집하지 않고 `.claude/settings.local.json`에 재정의를 기록하므로 플러그인이 사용자에게는 꺼져 있고 팀원은 영향을 받지 않습니다. [관리 설정](/ko/admin-setup)을 통해 활성화된 경우 관리자만 비활성화할 수 있습니다.222플러그인이 프로젝트의 `.claude/settings.json`을 통해 활성화된 경우 `/plugin`에서 비활성화하면 체크인된 파일을 편집하지 않고 `.claude/settings.local.json`에 재정의를 기록하므로 플러그인이 사용자에게는 꺼져 있고 팀원은 영향을 받지 않습니다. {/* min-version: 2.1.203 */}동일한 대화 상자는 공유 `.claude/settings.json`에서 제거하여 모든 사용자를 위해 플러그인을 제거할 수 있는 옵션도 제공합니다. 이 옵션은 Claude Code v2.1.203 이상이 필요합니다. [관리 설정](/ko/admin-setup)을 통해 활성화된 경우 관리자만 비활성화할 수 있습니다.

223 223

224<h2 id="how-the-plugin-integrates-with-claude-code">224<h2 id="how-the-plugin-integrates-with-claude-code">

225 플러그인이 Claude Code와 통합되는 방식225 플러그인이 Claude Code와 통합되는 방식

server-managed-settings.md +2 −2

Details

249서버 관리 설정은 타사 모델 공급자를 사용할 때는 사용할 수 없습니다:249서버 관리 설정은 타사 모델 공급자를 사용할 때는 사용할 수 없습니다:

250 250

251* Amazon Bedrock251* Amazon Bedrock

252* Google Vertex AI252* Google Cloud의 Agent Platform

253* Microsoft Foundry253* Microsoft Foundry

254* [Claude Platform on AWS](/ko/claude-platform-on-aws)254* [Claude Platform on AWS](/ko/claude-platform-on-aws)

255* `ANTHROPIC_BASE_URL` 또는 타사 [LLM gateways](/ko/llm-gateway)를 통한 사용자 정의 API 엔드포인트255* `ANTHROPIC_BASE_URL` 또는 타사 [LLM gateways](/ko/llm-gateway)를 통한 사용자 정의 API 엔드포인트

256 256

257Bedrock, Vertex AI 및 Foundry 배포의 경우, 자체 호스팅 [Claude apps gateway](/ko/claude-apps-gateway)는 동등한 원격 관리 설정 전달을 제공합니다. 게이트웨이에 로그인한 클라이언트는 `api.anthropic.com` 대신 게이트웨이에서 관리 설정을 가져옵니다. 시작 시 실패 의미론이 다릅니다. 게이트웨이에 도달할 수 없는 게이트웨이 클라이언트는 캐시된 설정으로 폴백하는 대신 오류로 종료되지만, 시간별 백그라운드 새로 고침은 두 채널 모두에서 실패 개방입니다.257Amazon Bedrock, Google Cloud의 Agent Platform 및 Microsoft Foundry 배포의 경우, 자체 호스팅 [Claude apps gateway](/ko/claude-apps-gateway)는 동등한 원격 관리 설정 전달을 제공합니다. 게이트웨이에 로그인한 클라이언트는 `api.anthropic.com` 대신 게이트웨이에서 관리 설정을 가져옵니다. 시작 시 실패 의미론이 다릅니다. 게이트웨이에 도달할 수 없는 게이트웨이 클라이언트는 캐시된 설정으로 폴백하는 대신 오류로 종료되지만, 시간별 백그라운드 새로 고침은 두 채널 모두에서 실패 개방입니다.

258 258

259<h2 id="audit-logging">259<h2 id="audit-logging">

260 감사 로깅260 감사 로깅

settings.md +35 −30

Details

95* **프로젝트 설정**은 프로젝트 디렉토리에 저장됩니다:95* **프로젝트 설정**은 프로젝트 디렉토리에 저장됩니다:

96 * 소스 제어에 체크인되고 팀과 공유되는 설정을 위한 `.claude/settings.json`96 * 소스 제어에 체크인되고 팀과 공유되는 설정을 위한 `.claude/settings.json`

97 * 체크인되지 않은 설정을 위한 `.claude/settings.local.json`으로, 개인 설정 및 실험에 유용합니다. Claude Code는 `.claude/settings.local.json`이 생성될 때 git을 구성하여 이를 무시하도록 합니다. 파일을 직접 생성하는 경우 gitignore에 수동으로 추가합니다.97 * 체크인되지 않은 설정을 위한 `.claude/settings.local.json`으로, 개인 설정 및 실험에 유용합니다. Claude Code는 `.claude/settings.local.json`이 생성될 때 git을 구성하여 이를 무시하도록 합니다. 파일을 직접 생성하는 경우 gitignore에 수동으로 추가합니다.

99 이 파일은 저장소가 아닌 사용자의 파일이므로 `allow` 권한 규칙이 `.claude/settings.json` 허용 규칙이 요구하는 [작업 공간 신뢰](/ko/permissions#project-allow-rules-and-workspace-trust) 단계 없이 적용됩니다. 저장소가 파일을 제공하는 경우 (예: 커밋하여) 작업 공간 신뢰가 여전히 적용됩니다.

98* **Managed 설정**: 중앙 집중식 제어가 필요한 조직의 경우 Claude Code는 managed 설정을 위한 여러 전달 메커니즘을 지원합니다. 모두 동일한 JSON 형식을 사용하며 사용자 또는 프로젝트 설정으로 재정의할 수 없습니다:100* **Managed 설정**: 중앙 집중식 제어가 필요한 조직의 경우 Claude Code는 managed 설정을 위한 여러 전달 메커니즘을 지원합니다. 모두 동일한 JSON 형식을 사용하며 사용자 또는 프로젝트 설정으로 재정의할 수 없습니다:

99 101

100 * **서버 관리 설정**: Anthropic의 서버에서 Claude.ai 관리 콘솔을 통해 또는 자체 호스팅 [Claude apps gateway](/ko/claude-apps-gateway)에서 원격으로 전달됩니다. [서버 관리 설정](/ko/server-managed-settings)을 참조하세요.102 * **서버 관리 설정**: Anthropic의 서버에서 claude.ai 관리 콘솔을 통해 또는 자체 호스팅 [Claude apps gateway](/ko/claude-apps-gateway)에서 원격으로 전달됩니다. [서버 관리 설정](/ko/server-managed-settings)을 참조하세요.

101 * **MDM/OS 수준 정책**: macOS 및 Windows의 기본 장치 관리를 통해 전달됩니다:103 * **MDM/OS 수준 정책**: macOS 및 Windows의 기본 장치 관리를 통해 전달됩니다:

102 * macOS: `com.anthropic.claudecode` managed preferences domain. plist의 최상위 키는 `managed-settings.json`을 반영하며, 중첩된 설정은 딕셔너리이고 배열은 plist 배열입니다. Jamf, Iru (Kandji) 또는 유사한 MDM 도구의 구성 프로필을 통해 배포합니다.104 * macOS: `com.anthropic.claudecode` managed preferences domain. plist의 최상위 키는 `managed-settings.json`을 반영하며, 중첩된 설정은 딕셔너리이고 배열은 plist 배열입니다. Jamf, Iru (Kandji) 또는 유사한 MDM 도구의 구성 프로필을 통해 배포합니다.

103 * Windows: `HKLM\SOFTWARE\Policies\ClaudeCode` 레지스트리 키와 JSON을 포함하는 `Settings` 값 (REG\_SZ 또는 REG\_EXPAND\_SZ) (그룹 정책 또는 Intune을 통해 배포)105 * Windows: `HKLM\SOFTWARE\Policies\ClaudeCode` 레지스트리 키와 JSON을 포함하는 `Settings` 값 (REG\_SZ 또는 REG\_EXPAND\_SZ) (그룹 정책 또는 Intune을 통해 배포)

211`settings.json`은 여러 옵션을 지원합니다:213`settings.json`은 여러 옵션을 지원합니다:

212 214

213| 키 | 설명 | 예제 |215| 키 | 설명 | 예제 |

214| :-------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------ |216| :-------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | :------------------------------------------------------------------------------------------------------------------------------ |

215| `advisorModel` | {/* min-version: 2.1.98 */}서버 측 [advisor 도구](/ko/advisor)를 위한 모델입니다. `"opus"`, `"sonnet"` 또는 `"fable"` ({/* min-version: 2.1.170 */}v2.1.170+)과 같은 모델 별칭 또는 전체 모델 ID를 허용합니다. `/advisor`를 실행할 때 자동으로 작성됩니다. Advisor를 비활성화하려면 설정 해제합니다. Claude Code v2.1.98 이상이 필요합니다 | `"opus"` |217| `advisorModel` | {/* min-version: 2.1.98 */}서버 측 [advisor 도구](/ko/advisor)를 위한 모델입니다. `"opus"`, `"sonnet"` 또는 `"fable"` ({/* min-version: 2.1.170 */}v2.1.170+)과 같은 모델 별칭 또는 전체 모델 ID를 허용합니다. `/advisor`를 실행할 때 자동으로 작성됩니다. Advisor를 비활성화하려면 설정 해제합니다. Claude Code v2.1.98 이상이 필요합니다 | `"opus"` |

216| `agent` | 메인 스레드를 명명된 subagent로 실행하고 `claude agents`에서 디스패치된 세션의 기본 에이전트를 설정합니다. 해당 subagent의 시스템 프롬프트, 도구 제한 및 모델을 적용합니다. [subagents 명시적으로 호출](/ko/sub-agents#invoke-subagents-explicitly)을 참조하세요 | `"code-reviewer"` |218| `agent` | 메인 스레드를 명명된 subagent로 실행하고 `claude agents`에서 디스패치된 세션의 기본 에이전트를 설정합니다. 해당 subagent의 시스템 프롬프트, 도구 제한 및 모델을 적용합니다. [subagents 명시적으로 호출](/ko/sub-agents#invoke-subagents-explicitly)을 참조하세요 | `"code-reviewer"` |

217| `agentPushNotifEnabled` | {/* min-version: 2.1.119 */}**기본값**: `false`. [Remote Control](/ko/remote-control)이 연결되어 있을 때 Claude가 장시간 작업이 완료될 때와 같이 휴대폰에 사전 예방적 푸시 알림을 보낼 수 있도록 허용합니다. `/config`에 **Claude가 결정할 때 푸시**로 표시됩니다. [모바일 푸시 알림](/ko/remote-control#mobile-push-notifications)을 참조하세요. Claude Code v2.1.119 이상이 필요합니다 | `true` |219| `agentPushNotifEnabled` | {/* min-version: 2.1.119 */}**기본값**: `false`. [Remote Control](/ko/remote-control)이 연결되어 있을 때 Claude가 장시간 작업이 완료될 때와 같이 휴대폰에 사전 예방적 푸시 알림을 보낼 수 있도록 허용합니다. `/config`에 **Claude가 결정할 때 푸시**로 표시됩니다. [모바일 푸시 알림](/ko/remote-control#mobile-push-notifications)을 참조하세요. Claude Code v2.1.119 이상이 필요합니다 | `true` |

224| `allowManagedPermissionRulesOnly` | (Managed 설정만) 사용자 및 프로젝트 설정이 `allow`, `ask` 또는 `deny` 권한 규칙을 정의하는 것을 방지합니다. Managed 설정의 규칙만 적용됩니다. [Managed 전용 설정](/ko/permissions#managed-only-settings)을 참조하세요 | `true` |226| `allowManagedPermissionRulesOnly` | (Managed 설정만) 사용자 및 프로젝트 설정이 `allow`, `ask` 또는 `deny` 권한 규칙을 정의하는 것을 방지합니다. Managed 설정의 규칙만 적용됩니다. [Managed 전용 설정](/ko/permissions#managed-only-settings)을 참조하세요 | `true` |

225| `alwaysThinkingEnabled` | 모든 세션에 대해 기본적으로 [확장 사고](/ko/model-config#extended-thinking)를 활성화합니다. 일반적으로 직접 편집하기보다는 `/config` 명령을 통해 구성됩니다. 사고를 강제로 끄려면 `env`에서 [`MAX_THINKING_TOKENS=0`](/ko/env-vars)을 설정합니다. 이는 Anthropic API에서 사고를 비활성화합니다. Fable 5는 제외되며, 이는 사고를 끌 수 없습니다. [제3자 공급자](/ko/third-party-integrations)에서 이는 `thinking` 매개변수를 생략하며, 적응형 추론 모델은 여전히 사고할 수 있습니다 | `true` |227| `alwaysThinkingEnabled` | 모든 세션에 대해 기본적으로 [확장 사고](/ko/model-config#extended-thinking)를 활성화합니다. 일반적으로 직접 편집하기보다는 `/config` 명령을 통해 구성됩니다. 사고를 강제로 끄려면 `env`에서 [`MAX_THINKING_TOKENS=0`](/ko/env-vars)을 설정합니다. 이는 Anthropic API에서 사고를 비활성화합니다. Fable 5는 제외되며, 이는 사고를 끌 수 없습니다. [제3자 공급자](/ko/third-party-integrations)에서 이는 `thinking` 매개변수를 생략하며, 적응형 추론 모델은 여전히 사고할 수 있습니다 | `true` |

226| `apiKeyHelper` | 시스템 셸 (`/bin/sh` on macOS and Linux, `cmd` on Windows)을 통해 실행될 사용자 정의 명령으로 인증 값을 생성합니다. 이 값은 모델 요청에 대해 `X-Api-Key` 및 `Authorization: Bearer` 헤더로 전송됩니다. [`CLAUDE_CODE_API_KEY_HELPER_TTL_MS`](/ko/env-vars)로 새로고침 간격을 설정합니다 | `/bin/generate_temp_api_key.sh` |228| `apiKeyHelper` | 시스템 셸 (`/bin/sh` on macOS and Linux, `cmd` on Windows)을 통해 실행될 사용자 정의 명령으로 인증 값을 생성합니다. 이 값은 모델 요청에 대해 `X-Api-Key` 및 `Authorization: Bearer` 헤더로 전송됩니다. [`CLAUDE_CODE_API_KEY_HELPER_TTL_MS`](/ko/env-vars)로 새로고침 간격을 설정합니다 | `/bin/generate_temp_api_key.sh` |

229| `askUserQuestionTimeout` | {/* min-version: 2.1.200 */}**기본값**: `"never"`. 답변되지 않은 [`AskUserQuestion`](/ko/tools-reference) 대화가 이미 선택한 옵션으로 자동 계속되기 전의 유휴 시간입니다. `"60s"`, `"5m"`, `"10m"` 또는 `"never"`를 허용합니다. 기본값을 사용하면 질문은 답변할 때까지 기다립니다. `/config`에 **질문 자동 계속 시간 초과**로 표시됩니다. 프로젝트 또는 local 설정에서는 읽지 않습니다. Claude Code v2.1.200 이상이 필요합니다 | `"5m"` |

227| `attribution` | git 커밋 및 pull request에 대한 attribution을 사용자 정의합니다. [Attribution 설정](#attribution-settings)을 참조하세요 | `{"commit": "🤖 Generated with Claude Code", "pr": ""}` |230| `attribution` | git 커밋 및 pull request에 대한 attribution을 사용자 정의합니다. [Attribution 설정](#attribution-settings)을 참조하세요 | `{"commit": "🤖 Generated with Claude Code", "pr": ""}` |

228| `autoCompactEnabled` | {/* min-version: 2.1.119 */}**기본값**: `true`. 컨텍스트가 한계에 접근할 때 자동으로 대화를 압축합니다. `/config`에 **자동 압축**으로 표시됩니다. 환경 변수로 비활성화하려면 `env`에서 [`DISABLE_AUTO_COMPACT`](/ko/env-vars)를 설정합니다 | `false` |231| `autoCompactEnabled` | {/* min-version: 2.1.119 */}**기본값**: `true`. 컨텍스트가 한계에 접근할 때 자동으로 대화를 압축합니다. `/config`에 **자동 압축**으로 표시됩니다. 환경 변수로 비활성화하려면 `env`에서 [`DISABLE_AUTO_COMPACT`](/ko/env-vars)를 설정합니다 | `false` |

229| `autoMemoryDirectory` | [자동 메모리](/ko/memory#storage-location) 저장소를 위한 사용자 정의 디렉토리입니다. 절대 경로 또는 `~/` 접두사 경로를 허용합니다. 프로젝트 또는 local 설정에서 이는 작업 공간 신뢰 대화를 수락한 후에만 적용됩니다. 복제된 저장소가 이 파일을 제공할 수 있기 때문입니다 | `"~/my-memory-dir"` |232| `autoMemoryDirectory` | [자동 메모리](/ko/memory#storage-location) 저장소를 위한 사용자 정의 디렉토리입니다. 절대 경로 또는 `~/` 접두사 경로를 허용합니다. 프로젝트 또는 local 설정에서 이는 작업 공간 신뢰 대화를 수락한 후에만 적용됩니다. 복제된 저장소가 이 파일을 제공할 수 있기 때문입니다 | `"~/my-memory-dir"` |

238| `awsCredentialExport` | AWS 자격 증명이 포함된 JSON을 출력하는 사용자 정의 스크립트 ([고급 자격 증명 구성](/ko/amazon-bedrock#advanced-credential-configuration) 참조) | `/bin/generate_aws_grant.sh` |241| `awsCredentialExport` | AWS 자격 증명이 포함된 JSON을 출력하는 사용자 정의 스크립트 ([고급 자격 증명 구성](/ko/amazon-bedrock#advanced-credential-configuration) 참조) | `/bin/generate_aws_grant.sh` |

239| `axScreenReader` | {/* min-version: 2.1.181 */}화면 판독기 친화적 출력을 렌더링합니다: 장식적 테두리나 애니메이션 없는 평면 텍스트. 화면 판독기 모드는 항상 클래식 렌더러를 사용하므로 활성화되어 있는 동안 `tui` 설정은 영향을 주지 않습니다. [`CLAUDE_AX_SCREEN_READER`](/ko/env-vars) 환경 변수 및 [`--ax-screen-reader`](/ko/cli-reference#cli-flags) 플래그가 우선합니다. Claude Code v2.1.181 이상이 필요합니다 | `true` |242| `axScreenReader` | {/* min-version: 2.1.181 */}화면 판독기 친화적 출력을 렌더링합니다: 장식적 테두리나 애니메이션 없는 평면 텍스트. 화면 판독기 모드는 항상 클래식 렌더러를 사용하므로 활성화되어 있는 동안 `tui` 설정은 영향을 주지 않습니다. [`CLAUDE_AX_SCREEN_READER`](/ko/env-vars) 환경 변수 및 [`--ax-screen-reader`](/ko/cli-reference#cli-flags) 플래그가 우선합니다. Claude Code v2.1.181 이상이 필요합니다 | `true` |

240| `blockedMarketplaces` | (Managed 설정만) 마켓플레이스 소스의 차단 목록입니다. 마켓플레이스 추가 및 플러그인 설치, 업데이트, 새로고침 및 자동 업데이트에 적용되므로 정책이 설정되기 전에 추가된 마켓플레이스는 플러그인을 가져오는 데 사용할 수 없습니다. 차단된 소스는 다운로드 전에 확인되므로 파일 시스템에 닿지 않습니다. [Managed 마켓플레이스 제한](/ko/plugin-marketplaces#managed-marketplace-restrictions)을 참조하세요 | `[{ "source": "github", "repo": "untrusted/plugins" }]` |243| `blockedMarketplaces` | (Managed 설정만) 마켓플레이스 소스의 차단 목록입니다. 마켓플레이스 추가 및 플러그인 설치, 업데이트, 새로고침 및 자동 업데이트에 적용되므로 정책이 설정되기 전에 추가된 마켓플레이스는 플러그인을 가져오는 데 사용할 수 없습니다. 차단된 소스는 다운로드 전에 확인되므로 파일 시스템에 닿지 않습니다. [Managed 마켓플레이스 제한](/ko/plugin-marketplaces#managed-marketplace-restrictions)을 참조하세요 | `[{ "source": "github", "repo": "untrusted/plugins" }]` |

244| `browserExternalPageTools` | (Managed 설정만) 데스크톱 앱의 [Browser 창](/ko/desktop#browse-external-sites)에서 외부 페이지를 읽거나 작용하기 위해 Claude가 도구를 사용하는 것을 방지하려면 `"disabled"`로 설정합니다. 사용자는 여전히 외부 사이트로 직접 이동할 수 있으며 local dev 서버 미리보기는 영향을 받지 않습니다 | `"disabled"` |

241| `channelsEnabled` | (Managed 설정만) 조직을 위해 [channels](/ko/channels)를 허용합니다. Claude.ai Team 및 Enterprise 플랜에서 설정되지 않거나 `false`이면 채널이 차단됩니다. [Anthropic Console](/ko/authentication#claude-console-authentication) 계정이 API 키 인증을 사용하는 경우 조직이 managed 설정을 배포하지 않으면 기본적으로 채널이 허용되며, 이 경우 이 키를 `true`로 설정해야 합니다 | `true` |245| `channelsEnabled` | (Managed 설정만) 조직을 위해 [channels](/ko/channels)를 허용합니다. Claude.ai Team 및 Enterprise 플랜에서 설정되지 않거나 `false`이면 채널이 차단됩니다. [Anthropic Console](/ko/authentication#claude-console-authentication) 계정이 API 키 인증을 사용하는 경우 조직이 managed 설정을 배포하지 않으면 기본적으로 채널이 허용되며, 이 경우 이 키를 `true`로 설정해야 합니다 | `true` |

242| `claudeMd` | (Managed 설정만) 조직 관리 메모리로 주입된 CLAUDE.md 스타일 지침입니다. Managed 또는 정책 설정에서 설정된 경우에만 적용되며 사용자, 프로젝트 및 local 설정에서는 무시됩니다. [조직 전체 CLAUDE.md](/ko/memory#deploy-organization-wide-claude-md)를 참조하세요 | `"Always run make lint before committing."` |246| `claudeMd` | (Managed 설정만) 조직 관리 메모리로 주입된 CLAUDE.md 스타일 지침입니다. Managed 또는 정책 설정에서 설정된 경우에만 적용되며 사용자, 프로젝트 및 local 설정에서는 무시됩니다. [조직 전체 CLAUDE.md](/ko/memory#deploy-organization-wide-claude-md)를 참조하세요 | `"Always run make lint before committing."` |

243| `claudeMdExcludes` | [메모리](/ko/memory)를 로드할 때 건너뛸 `CLAUDE.md` 파일의 Glob 패턴 또는 절대 경로입니다. 패턴은 절대 파일 경로와 일치합니다. 사용자, 프로젝트 및 local 메모리에만 적용됩니다. managed 정책 파일은 제외할 수 없습니다 | `["**/vendor/**/CLAUDE.md"]` |247| `claudeMdExcludes` | [메모리](/ko/memory)를 로드할 때 건너뛸 `CLAUDE.md` 파일의 Glob 패턴 또는 절대 경로입니다. 패턴은 절대 파일 경로와 일치합니다. 사용자, 프로젝트 및 local 메모리에만 적용됩니다. managed 정책 파일은 제외할 수 없습니다 | `["**/vendor/**/CLAUDE.md"]` |

244| `cleanupPeriodDays` | **기본값**: `30`일, 최소 `1`. 이 기간보다 오래된 세션 파일은 시작 시 삭제됩니다. `0`으로 설정하면 검증 오류가 발생합니다. 또한 시작 시 [고아 subagent worktrees](/ko/worktrees#clean-up-worktrees)의 자동 제거에 대한 나이 기준을 제어합니다. 트랜스크립트 쓰기를 완전히 비활성화하려면 [`CLAUDE_CODE_SKIP_PROMPT_HISTORY`](/ko/env-vars) 환경 변수를 설정하거나 비대화형 모드 (`-p`)에서 `--no-session-persistence` 플래그 또는 `persistSession: false` SDK 옵션을 사용합니다. | `20` |248| `cleanupPeriodDays` | **기본값**: `30`일, 최소 `1`. Claude Code는 이 기간보다 오래된 [세션 파일 및 기타 애플리케이션 데이터](/ko/claude-directory#cleaned-up-automatically)를 시작 시 삭제합니다. `0`으로 설정하면 검증 오류가 발생합니다. 또한 시작 시 [고아 worktrees](/ko/worktrees#clean-up-worktrees)의 자동 제거에 대한 나이 기준을 제어합니다. {/* min-version: 2.1.203 */}Claude Code가 설정 파일을 읽거나 파싱할 수 없으면 보존 정리 스윕을 일시 중단하고 파일을 수정할 때까지 `/status`에 경고를 표시합니다. 단, [managed 설정](/ko/server-managed-settings)이 `cleanupPeriodDays`를 제공하는 경우 스윕은 managed 값에서 실행됩니다. v2.1.203 이전에는 정리가 해당 상태에서 30일 기본값으로 실행되었고 더 긴 `cleanupPeriodDays`가 유지하려던 트랜스크립트를 삭제할 수 있었습니다. 30일보다 최신인 파일은 절대 제거되지 않았습니다. 트랜스크립트 쓰기를 완전히 비활성화하려면 [`CLAUDE_CODE_SKIP_PROMPT_HISTORY`](/ko/env-vars) 환경 변수를 설정합니다. 비대화형 모드에서 `-p`와 함께 `--no-session-persistence`를 전달하거나 Agent SDK에서 `persistSession: false`를 설정합니다. | `20` |

246| `defaultShell` | **기본값**: `"bash"`, 또는 Bash를 사용할 수 없을 때 Windows에서 `"powershell"`. 입력 상자 `!` 명령의 기본 셸입니다. `"bash"` 또는 `"powershell"`을 허용합니다. `"powershell"`을 설정하면 Windows에서 대화형 `!` 명령을 PowerShell을 통해 라우팅합니다. `CLAUDE_CODE_USE_POWERSHELL_TOOL=1`이 필요합니다. [PowerShell 도구](/ko/tools-reference#powershell-tool)를 참조하세요 | `"powershell"` |250| `defaultShell` | **기본값**: `"bash"`, 또는 Bash를 사용할 수 없을 때 Windows에서 `"powershell"`. 입력 상자 `!` 명령의 기본 셸입니다. `"bash"` 또는 `"powershell"`을 허용합니다. `"powershell"`을 설정하면 Windows에서 대화형 `!` 명령을 PowerShell을 통해 라우팅합니다. `CLAUDE_CODE_USE_POWERSHELL_TOOL=1`이 필요합니다. [PowerShell 도구](/ko/tools-reference#powershell-tool)를 참조하세요 | `"powershell"` |

247| `deniedMcpServers` | Managed 설정에서 설정되면 명시적으로 차단된 MCP 서버의 거부 목록입니다. Managed 서버를 포함한 모든 범위에 적용됩니다. 거부 목록이 허용 목록보다 우선합니다. [Managed MCP 구성](/ko/managed-mcp)을 참조하세요 | `[{ "serverName": "filesystem" }]` |251| `deniedMcpServers` | Managed 설정에서 설정되면 명시적으로 차단된 MCP 서버의 거부 목록입니다. Managed 서버를 포함한 모든 범위에 적용됩니다. 거부 목록이 허용 목록보다 우선합니다. [Managed MCP 구성](/ko/managed-mcp)을 참조하세요 | `[{ "serverName": "filesystem" }]` |

250| `disableArtifact` | [Artifact](/ko/artifacts) 도구를 비활성화하려면 `true`로 설정합니다. 이는 세션 출력을 claude.ai의 비공개 웹 페이지로 게시합니다. `CLAUDE_CODE_DISABLE_ARTIFACT`를 `1`로 설정하는 것과 동일합니다 | `true` |254| `disableArtifact` | [Artifact](/ko/artifacts) 도구를 비활성화하려면 `true`로 설정합니다. 이는 세션 출력을 claude.ai의 비공개 웹 페이지로 게시합니다. `CLAUDE_CODE_DISABLE_ARTIFACT`를 `1`로 설정하는 것과 동일합니다 | `true` |

251| `disableAutoMode` | [자동 모드](/ko/permission-modes#eliminate-prompts-with-auto-mode)가 활성화되는 것을 방지하려면 `"disable"`로 설정합니다. `Shift+Tab` 순환에서 `auto`를 제거하고 시작 시 `--permission-mode auto`를 거부합니다. [managed 설정](/ko/permissions#managed-settings)에서 사용자가 재정의할 수 없을 때 가장 유용합니다 | `"disable"` |255| `disableAutoMode` | [자동 모드](/ko/permission-modes#eliminate-prompts-with-auto-mode)가 활성화되는 것을 방지하려면 `"disable"`로 설정합니다. `Shift+Tab` 순환에서 `auto`를 제거하고 시작 시 `--permission-mode auto`를 거부합니다. [managed 설정](/ko/permissions#managed-settings)에서 사용자가 재정의할 수 없을 때 가장 유용합니다 | `"disable"` |

252| `disableBundledSkills` | [skills](/ko/skills) 및 Claude Code와 함께 제공되는 워크플로우를 비활성화하려면 `true`로 설정합니다: 번들 skills 및 워크플로우는 완전히 제거되고, `/init`과 같은 기본 제공 슬래시 명령은 입력 가능하지만 모델에서 숨겨집니다. 플러그인의 skills, `.claude/skills/` 및 `.claude/commands/`는 영향을 받지 않습니다. `CLAUDE_CODE_DISABLE_BUNDLED_SKILLS`를 `1`로 설정하는 것과 동일합니다 | `true` |256| `disableBundledSkills` | [skills](/ko/skills) 및 Claude Code와 함께 제공되는 워크플로우를 비활성화하려면 `true`로 설정합니다: 번들 skills 및 워크플로우는 완전히 제거되고, `/init`과 같은 기본 제공 슬래시 명령은 입력 가능하지만 모델에서 숨겨집니다. `/doctor`는 기본 제공 명령처럼 입력 가능하지만 [`DISABLE_DOCTOR_COMMAND`](/ko/env-vars)로 숨깁니다. 플러그인의 skills, `.claude/skills/` 및 `.claude/commands/`는 영향을 받지 않습니다. `CLAUDE_CODE_DISABLE_BUNDLED_SKILLS`를 `1`로 설정하는 것과 동일합니다 | `true` |

253| `disableClaudeAiConnectors` | {/* min-version: 2.1.182 */}[claude.ai MCP 커넥터](/ko/mcp#use-mcp-servers-from-claude-ai)를 비활성화하여 자동 가져오기 또는 연결되지 않도록 합니다. 모든 설정 범위에서 설정합니다. 모든 소스에서 `true`가 우선하므로 체크인된 프로젝트 `.claude/settings.json`이 저장소를 클라우드 커넥터에서 제외할 수 있지만 프로젝트 수준 `false`는 사용자 또는 정책 수준 `true`를 재정의할 수 없습니다. `--mcp-config`를 통해 명시적으로 전달된 서버는 영향을 받지 않습니다. 모든 커넥터를 거부하는 대신 개별 커넥터를 거부하려면 [`deniedMcpServers`](/ko/managed-mcp)를 사용합니다. Claude Code v2.1.182 이상이 필요합니다 | `true` |257| `disableClaudeAiConnectors` | {/* min-version: 2.1.182 */}[claude.ai MCP 커넥터](/ko/mcp#use-mcp-servers-from-claude-ai)를 비활성화하여 자동 가져오기 또는 연결되지 않도록 합니다. 모든 설정 범위에서 설정합니다. 모든 소스에서 `true`가 우선하므로 체크인된 프로젝트 `.claude/settings.json`이 저장소를 클라우드 커넥터에서 제외할 수 있지만 프로젝트 수준 `false`는 사용자 또는 정책 수준 `true`를 재정의할 수 없습니다. `--mcp-config`를 통해 명시적으로 전달된 서버는 영향을 받지 않습니다. 모든 커넥터를 거부하는 대신 개별 커넥터를 거부하려면 [`deniedMcpServers`](/ko/managed-mcp)를 사용합니다. Claude Code v2.1.182 이상이 필요합니다 | `true` |

254| `disableDeepLinkRegistration` | Claude Code가 시작 시 운영 체제에 `claude-cli://` 프로토콜 핸들러를 등록하는 것을 방지하려면 `"disable"`로 설정합니다. [Deep links](/ko/deep-links)를 사용하면 외부 도구가 사전 채워진 프롬프트로 Claude Code 세션을 열 수 있습니다. 프로토콜 핸들러 등록이 제한되거나 별도로 관리되는 환경에서 유용합니다 | `"disable"` |258| `disableDeepLinkRegistration` | Claude Code가 시작 시 운영 체제에 `claude-cli://` 프로토콜 핸들러를 등록하는 것을 방지하려면 `"disable"`로 설정합니다. [Deep links](/ko/deep-links)를 사용하면 외부 도구가 사전 채워진 프롬프트로 Claude Code 세션을 열 수 있습니다. 프로토콜 핸들러 등록이 제한되거나 별도로 관리되는 환경에서 유용합니다 | `"disable"` |

262| `enableAllProjectMcpServers` | 프로젝트 `.mcp.json` 파일에 정의된 모든 MCP 서버를 자동으로 승인합니다. {/* min-version: 2.1.196 */}v2.1.196부터 `claude mcp list` 및 `claude mcp get`은 [저장소에 체크인되지 않은 설정 파일](/ko/mcp#managing-your-servers)에서만 신뢰할 수 없는 폴더에서 이 키를 존중합니다 | `true` |266| `enableAllProjectMcpServers` | 프로젝트 `.mcp.json` 파일에 정의된 모든 MCP 서버를 자동으로 승인합니다. {/* min-version: 2.1.196 */}v2.1.196부터 `claude mcp list` 및 `claude mcp get`은 [저장소에 체크인되지 않은 설정 파일](/ko/mcp#managing-your-servers)에서만 신뢰할 수 없는 폴더에서 이 키를 존중합니다 | `true` |

263| `enableArtifact` | {/* min-version: 2.1.196 */}이 사용자에 대해 [Artifact](/ko/artifacts) 도구를 활성화하거나 비활성화합니다. 설정되지 않으면 기본값은 계정의 기능 [가용성](/ko/artifacts#availability)을 따릅니다. `/config`의 **Artifacts** 행이 이 키를 작성합니다. Managed `disableArtifact` 및 조직의 [관리자 설정](/ko/artifacts#manage-artifacts-for-your-organization)이 우선하며, 키는 프로젝트 및 local 설정 (`.claude/settings.json`, `.claude/settings.local.json`)에서 무시됩니다. 저장소가 이를 커밋할 수 있기 때문입니다. Claude Code v2.1.196 이상이 필요합니다 | `true` |267| `enableArtifact` | {/* min-version: 2.1.196 */}이 사용자에 대해 [Artifact](/ko/artifacts) 도구를 활성화하거나 비활성화합니다. 설정되지 않으면 기본값은 계정의 기능 [가용성](/ko/artifacts#availability)을 따릅니다. `/config`의 **Artifacts** 행이 이 키를 작성합니다. Managed `disableArtifact` 및 조직의 [관리자 설정](/ko/artifacts#manage-artifacts-for-your-organization)이 우선하며, 키는 프로젝트 및 local 설정 (`.claude/settings.json`, `.claude/settings.local.json`)에서 무시됩니다. 저장소가 이를 커밋할 수 있기 때문입니다. Claude Code v2.1.196 이상이 필요합니다 | `true` |

264| `enabledMcpjsonServers` | `.mcp.json` 파일에서 승인할 특정 MCP 서버 목록입니다. {/* min-version: 2.1.196 */}v2.1.196부터 `claude mcp list` 및 `claude mcp get`은 [저장소에 체크인되지 않은 설정 파일](/ko/mcp#managing-your-servers)에서만 신뢰할 수 없는 폴더에서 이 키를 존중합니다 | `["memory", "github"]` |268| `enabledMcpjsonServers` | `.mcp.json` 파일에서 승인할 특정 MCP 서버 목록입니다. {/* min-version: 2.1.196 */}v2.1.196부터 `claude mcp list` 및 `claude mcp get`은 [저장소에 체크인되지 않은 설정 파일](/ko/mcp#managing-your-servers)에서만 신뢰할 수 없는 폴더에서 이 키를 존중합니다 | `["memory", "github"]` |

265| `enforceAvailableModels` | {/* min-version: 2.1.175 */}}`true`이고 `availableModels`가 managed 또는 정책 설정의 비어있지 않은 목록일 때 기본 모델도 허용 목록으로 제한됩니다. 기본 옵션이 허용 목록의 첫 번째 사용 가능한 항목으로 폴백됩니다. `availableModels`가 설정되지 않거나 비어있을 때는 영향을 주지 않습니다. [모델 선택 제한](/ko/model-config#restrict-model-selection)을 참조하세요. Claude Code v2.1.175 이상이 필요합니다 | `true` |269| `enforceAvailableModels` | {/* min-version: 2.1.175 */}}`true`이고 `availableModels`가 managed 또는 정책 설정의 비어있지 않은 목록일 때 기본 모델도 허용 목록으로 제한됩니다. 기본 옵션이 허용 목록의 첫 번째 사용 가능한 항목으로 폴백됩니다. 단, 기본값이 허용 목록에 있으면 그대로 유지됩니다. `availableModels`가 설정되지 않거나 비어있을 때는 영향을 주지 않습니다. [모델 선택 제한](/ko/model-config#restrict-model-selection)을 참조하세요. Claude Code v2.1.175 이상이 필요합니다 | `true` |

266| `env` | 모든 세션에 적용될 환경 변수 및 Claude Code가 생성하는 하위 프로세스에 적용됩니다. {/* min-version: 2.1.143 */}v2.1.143부터 여기에 설정된 `NO_COLOR` 및 `FORCE_COLOR`는 하위 프로세스로 전달되지만 Claude Code 자체 인터페이스 색상은 변경하지 않습니다. Claude를 시작하기 전에 셸에서 이를 설정하여 인터페이스 색상을 변경합니다. {/* min-version: 2.1.195 */}v2.1.195부터 Claude Code의 호스팅 환경이 설정하는 `CLAUDE_CODE_REMOTE` 및 `CLAUDE_CODE_ACCOUNT_UUID`와 같은 ID 변수는 여기에 설정되면 무시됩니다 | `{"FOO": "bar"}` |270| `env` | 모든 세션에 적용될 환경 변수 및 Claude Code가 생성하는 하위 프로세스에 적용됩니다. {/* min-version: 2.1.143 */}v2.1.143부터 여기에 설정된 `NO_COLOR` 및 `FORCE_COLOR`는 하위 프로세스로 전달되지만 Claude Code 자체 인터페이스 색상은 변경하지 않습니다. Claude를 시작하기 전에 셸에서 이를 설정하여 인터페이스 색상을 변경합니다. {/* min-version: 2.1.195 */}v2.1.195부터 Claude Code의 호스팅 환경이 설정하는 `CLAUDE_CODE_REMOTE` 및 `CLAUDE_CODE_ACCOUNT_UUID`와 같은 ID 변수는 여기에 설정되면 무시됩니다 | `{"FOO": "bar"}` |

267| `fallbackModel` | 기본 모델이 과부하이거나 사용할 수 없을 때 순서대로 시도할 폴백 모델입니다. Claude Code는 턴의 나머지 부분에 대해 체인의 다음 사용 가능한 모델로 전환하고 알림을 표시합니다. `"default"`는 기본 모델로 확장됩니다. 체인은 3개 모델로 제한되며 추가 항목은 무시됩니다. 대부분의 배열 설정과 달리 이 키는 설정 파일 전체에서 병합되지 않습니다: 이를 정의하는 최고 우선순위 파일이 전체 체인을 제공합니다. [`--fallback-model`](/ko/cli-reference#cli-flags) 플래그는 한 세션에 대해 이를 재정의합니다. [폴백 모델 체인](/ko/model-config#fallback-model-chains)을 참조하세요 | `["claude-sonnet-5", "claude-haiku-4-5"]` |271| `fallbackModel` | 기본 모델이 과부하이거나 사용할 수 없을 때 순서대로 시도할 폴백 모델입니다. Claude Code는 턴의 나머지 부분에 대해 체인의 다음 사용 가능한 모델로 전환하고 알림을 표시합니다. `"default"`는 기본 모델로 확장됩니다. 체인은 3개 모델로 제한되며 추가 항목은 무시됩니다. 대부분의 배열 설정과 달리 이 키는 설정 파일 전체에서 병합되지 않습니다: 이를 정의하는 최고 우선순위 파일이 전체 체인을 제공합니다. [`--fallback-model`](/ko/cli-reference#cli-flags) 플래그는 한 세션에 대해 이를 재정의합니다. [폴백 모델 체인](/ko/model-config#fallback-model-chains)을 참조하세요 | `["claude-sonnet-5", "claude-haiku-4-5"]` |

268| `fastModePerSessionOptIn` | `true`일 때 빠른 모드는 세션 간에 지속되지 않습니다. 각 세션은 빠른 모드가 꺼진 상태로 시작되며 사용자가 `/fast`로 활성화해야 합니다. 사용자의 빠른 모드 설정은 여전히 저장됩니다. [세션별 옵트인 필요](/ko/fast-mode#require-per-session-opt-in)를 참조하세요 | `true` |272| `fastModePerSessionOptIn` | `true`일 때 빠른 모드는 세션 간에 지속되지 않습니다. 각 세션은 빠른 모드가 꺼진 상태로 시작되며 사용자가 `/fast`로 활성화해야 합니다. 사용자의 빠른 모드 설정은 여전히 저장됩니다. [세션별 옵트인 필요](/ko/fast-mode#require-per-session-opt-in)를 참조하세요 | `true` |

269| `feedbackSurveyRate` | [세션 품질 설문조사](/ko/data-usage#session-quality-surveys)가 적격일 때 나타날 확률 (0–1). 완전히 억제하려면 `0`으로 설정하거나 `env`에서 [`CLAUDE_CODE_DISABLE_FEEDBACK_SURVEY`](/ko/env-vars)를 설정합니다. Bedrock, Vertex 또는 Foundry를 사용할 때 유용하며 기본 샘플 레이트가 적용되지 않습니다 | `0.05` |273| `feedbackSurveyRate` | [세션 품질 설문조사](/ko/data-usage#session-quality-surveys)가 적격일 때 나타날 확률 (0–1). 완전히 억제하려면 `0`으로 설정하거나 `env`에서 [`CLAUDE_CODE_DISABLE_FEEDBACK_SURVEY`](/ko/env-vars)를 설정합니다. Amazon Bedrock, Google Cloud의 Agent Platform 또는 Microsoft Foundry를 사용할 때 유용하며 기본 샘플 레이트가 적용되지 않습니다 | `0.05` |

270| `fileCheckpointingEnabled` | {/* min-version: 2.1.119 */}**기본값**: `true`. 각 편집 전에 파일을 스냅샷하여 [`/rewind`](/ko/checkpointing)가 이를 복원할 수 있도록 합니다. `/config`에 \*\*코드 되감기 (체크포인트)\*\*로 표시됩니다. 환경 변수로 비활성화하려면 `env`에서 [`CLAUDE_CODE_DISABLE_FILE_CHECKPOINTING`](/ko/env-vars)를 설정합니다 | `false` |274| `fileCheckpointingEnabled` | {/* min-version: 2.1.119 */}**기본값**: `true`. 각 편집 전에 파일을 스냅샷하여 [`/rewind`](/ko/checkpointing)가 이를 복원할 수 있도록 합니다. `/config`에 \*\*코드 되감기 (체크포인트)\*\*로 표시됩니다. 환경 변수로 비활성화하려면 `env`에서 [`CLAUDE_CODE_DISABLE_FILE_CHECKPOINTING`](/ko/env-vars)를 설정합니다 | `false` |

271| `fileSuggestion` | `@` 파일 자동 완성을 위한 사용자 정의 스크립트를 구성합니다. [파일 제안 설정](#file-suggestion-settings)을 참조하세요 | `{"type": "command", "command": "~/.claude/file-suggestion.sh"}` |275| `fileSuggestion` | `@` 파일 자동 완성을 위한 사용자 정의 스크립트를 구성합니다. [파일 제안 설정](#file-suggestion-settings)을 참조하세요 | `{"type": "command", "command": "~/.claude/file-suggestion.sh"}` |

272| `footerLinksRegexes` | {/* min-version: 2.1.176 */}정규식이 턴 출력과 일치할 때 바닥글에 클릭 가능한 배지를 렌더링합니다. 각 항목에는 `pattern`, 명명된 캡처 그룹에서 채워진 `{name}` 자리 표시자가 있는 `url` 템플릿 및 선택적 `label`이 있습니다. 사용자, `--settings` 플래그 및 managed 설정에서만 읽습니다. [바닥글 링크 배지](#footer-link-badges)에서 URL 제약, 스키마 허용 목록 및 제한을 참조하세요. Claude Code v2.1.176 이상이 필요합니다 | `[{"type": "regex", "pattern": "\\b(?<key>PROJ-\\d+)\\b", "url": "https://issues.example.com/browse/{key}", "label": "{key}"}]` |276| `footerLinksRegexes` | {/* min-version: 2.1.176 */}정규식이 턴 출력과 일치할 때 바닥글에 클릭 가능한 배지를 렌더링합니다. 각 항목에는 `pattern`, 명명된 캡처 그룹에서 채워진 `{name}` 자리 표시자가 있는 `url` 템플릿 및 선택적 `label`이 있습니다. 사용자, `--settings` 플래그 및 managed 설정에서만 읽습니다. [바닥글 링크 배지](#footer-link-badges)에서 URL 제약, 스키마 허용 목록 및 제한을 참조하세요. Claude Code v2.1.176 이상이 필요합니다 | `[{"type": "regex", "pattern": "\\b(?<key>PROJ-\\d+)\\b", "url": "https://issues.example.com/browse/{key}", "label": "{key}"}]` |

273| `forceLoginMethod` | `claudeai`를 사용하여 Claude.ai 계정으로만 로그인을 제한하거나, `console`을 사용하여 Claude Console 계정으로만 제한하거나, `gateway`를 사용하여 클라우드 게이트웨이로만 제한합니다. [Claude apps gateway](/ko/claude-apps-gateway)를 참조하세요. Managed 설정에서 설정되면 `ANTHROPIC_API_KEY`, `ANTHROPIC_AUTH_TOKEN` 또는 `apiKeyHelper`로 인증된 세션은 시작 시 차단됩니다. 어느 값도 먼저 자사 OAuth 없이 만족할 수 없기 때문입니다. Bedrock, Vertex 및 Foundry와 같은 제3자 공급자 세션은 차단되지 않습니다: 이들은 Anthropic이 아닌 클라우드 공급자에 대해 인증합니다 | `claudeai` |277| `forceLoginMethod` | `claudeai`를 사용하여 Claude.ai 계정으로만 로그인을 제한하거나, `console`을 사용하여 Claude Console 계정으로만 제한하거나, `gateway`를 사용하여 클라우드 게이트웨이로만 제한합니다. [Claude apps gateway](/ko/claude-apps-gateway)를 참조하세요. Managed 설정에서 설정되면 `ANTHROPIC_API_KEY`, `ANTHROPIC_AUTH_TOKEN` 또는 `apiKeyHelper`로 인증된 세션은 시작 시 차단됩니다. 어느 값도 먼저 자사 OAuth 없이 만족할 수 없기 때문입니다. Amazon Bedrock, Google Cloud의 Agent Platform 및 Microsoft Foundry와 같은 제3자 공급자 세션은 차단되지 않습니다: 이들은 Anthropic이 아닌 클라우드 공급자에 대해 인증합니다 | `claudeai` |

274| `forceLoginGatewayUrl` | `/login` 클라우드 게이트웨이 화면에서 게이트웨이 URL을 사전 채우고 잠급니다. 이 키 또는 `forceLoginMethod: "gateway"` 중 하나가 해당 화면을 표시합니다. URL이 채워지도록 둘 다 설정합니다. Managed 정책 계층에서만 적용됩니다. 사용자 및 프로젝트 설정에서는 무시됩니다. [Claude apps gateway](/ko/claude-apps-gateway#set-the-gateway-url)를 참조하세요 | `"https://claude-gateway.example.com"` |278| `forceLoginGatewayUrl` | `/login` 클라우드 게이트웨이 화면에서 게이트웨이 URL을 사전 채우고 잠급니다. 이 키 또는 `forceLoginMethod: "gateway"` 중 하나가 해당 화면을 표시합니다. URL이 채워지도록 둘 다 설정합니다. Managed 정책 계층에서만 적용됩니다. 사용자 및 프로젝트 설정에서는 무시됩니다. [Claude apps gateway](/ko/claude-apps-gateway#set-the-gateway-url)를 참조하세요 | `"https://claude-gateway.example.com"` |

275| `forceLoginOrgUUID` | 로그인이 특정 Anthropic 조직에 속하도록 요구합니다. 단일 UUID 문자열을 허용하며, 이는 로그인 중에 해당 조직을 사전 선택하거나, 나열된 조직이 사전 선택 없이 허용되는 UUID 배열을 허용합니다. Managed 설정에서 설정되면 인증된 계정이 나열된 조직에 속하지 않으면 로그인이 실패합니다. `ANTHROPIC_API_KEY`, `ANTHROPIC_AUTH_TOKEN` 또는 `apiKeyHelper`로 인증된 세션은 시작 시 차단됩니다. 조직 멤버십을 확인할 수 없기 때문입니다. Bedrock, Vertex 및 Foundry와 같은 제3자 공급자 세션은 차단되지 않습니다: 클라우드 IAM을 사용하여 사용할 수 있는 클라우드 계정을 제한합니다. 빈 배열은 실패하고 잘못된 구성 메시지로 로그인을 차단합니다 | `"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"` 또는 `["xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "yyyyyyyy-yyyy-yyyy-yyyy-yyyyyyyyyyyy"]` |279| `forceLoginOrgUUID` | 로그인이 특정 Anthropic 조직에 속하도록 요구합니다. 단일 UUID 문자열을 허용하며, 이는 로그인 중에 해당 조직을 사전 선택하거나, 나열된 조직이 사전 선택 없이 허용되는 UUID 배열을 허용합니다. Managed 설정에서 설정되면 인증된 계정이 나열된 조직에 속하지 않으면 로그인이 실패합니다. `ANTHROPIC_API_KEY`, `ANTHROPIC_AUTH_TOKEN` 또는 `apiKeyHelper`로 인증된 세션은 시작 시 차단됩니다. 조직 멤버십을 확인할 수 없기 때문입니다. Amazon Bedrock, Google Cloud의 Agent Platform 및 Microsoft Foundry와 같은 제3자 공급자 세션은 차단되지 않습니다: 클라우드 IAM을 사용하여 사용할 수 있는 클라우드 계정을 제한합니다. 빈 배열은 실패하고 잘못된 구성 메시지로 로그인을 차단합니다 | `"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"` 또는 `["xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "yyyyyyyy-yyyy-yyyy-yyyy-yyyyyyyyyyyy"]` |

276| `forceRemoteSettingsRefresh` | (Managed 설정만) 원격 managed 설정이 서버에서 새로 가져올 때까지 CLI 시작을 차단합니다. 가져오기가 실패하면 캐시된 또는 설정 없이 계속하는 대신 CLI가 종료됩니다. 설정되지 않으면 시작이 원격 설정을 기다리지 않고 계속됩니다. [실패 폐쇄 적용](/ko/server-managed-settings#enforce-fail-closed-startup)을 참조하세요 | `true` |280| `forceRemoteSettingsRefresh` | (Managed 설정만) 원격 managed 설정이 서버에서 새로 가져올 때까지 CLI 시작을 차단합니다. 가져오기가 실패하면 캐시된 또는 설정 없이 계속하는 대신 CLI가 종료됩니다. 설정되지 않으면 시작이 원격 설정을 기다리지 않고 계속됩니다. [실패 폐쇄 적용](/ko/server-managed-settings#enforce-fail-closed-startup)을 참조하세요 | `true` |

277| `gcpAuthRefresh` | GCP Application Default Credentials가 만료되거나 로드할 수 없을 때 새로고침하는 사용자 정의 스크립트입니다. [고급 자격 증명 구성](/ko/google-vertex-ai#advanced-credential-configuration)을 참조하세요 | `gcloud auth application-default login` |281| `gcpAuthRefresh` | GCP Application Default Credentials가 만료되거나 로드할 수 없을 때 새로고침하는 사용자 정의 스크립트입니다. [고급 자격 증명 구성](/ko/google-vertex-ai#advanced-credential-configuration)을 참조하세요 | `gcloud auth application-default login` |

279| `httpHookAllowedEnvVars` | HTTP hooks가 헤더에 보간할 수 있는 환경 변수 이름의 허용 목록입니다. 설정되면 각 hook의 유효한 `allowedEnvVars`는 이 설정과의 교집합입니다. 정의되지 않음 = 제한 없음. 배열은 설정 소스 전체에서 병합됩니다. [Hook 구성](#hook-configuration)을 참조하세요 | `["MY_TOKEN", "HOOK_SECRET"]` |283| `httpHookAllowedEnvVars` | HTTP hooks가 헤더에 보간할 수 있는 환경 변수 이름의 허용 목록입니다. 설정되면 각 hook의 유효한 `allowedEnvVars`는 이 설정과의 교집합입니다. 정의되지 않음 = 제한 없음. 배열은 설정 소스 전체에서 병합됩니다. [Hook 구성](#hook-configuration)을 참조하세요 | `["MY_TOKEN", "HOOK_SECRET"]` |

280| `includeGitInstructions` | **기본값**: `true`. Claude의 시스템 프롬프트에 기본 제공 커밋 및 PR 워크플로우 지침 및 git 상태 스냅샷을 포함합니다. 예를 들어 자신의 git 워크플로우 skills을 사용할 때 이를 `false`로 설정하여 둘 다 제거합니다. `CLAUDE_CODE_DISABLE_GIT_INSTRUCTIONS` 환경 변수가 설정되면 이 설정보다 우선합니다 | `false` |284| `includeGitInstructions` | **기본값**: `true`. Claude의 시스템 프롬프트에 기본 제공 커밋 및 PR 워크플로우 지침 및 git 상태 스냅샷을 포함합니다. 예를 들어 자신의 git 워크플로우 skills을 사용할 때 이를 `false`로 설정하여 둘 다 제거합니다. `CLAUDE_CODE_DISABLE_GIT_INSTRUCTIONS` 환경 변수가 설정되면 이 설정보다 우선합니다 | `false` |

281| `inputNeededNotifEnabled` | {/* min-version: 2.1.119 */}}**기본값**: `false`. [Remote Control](/ko/remote-control)이 연결되어 있을 때 권한 프롬프트 또는 질문이 입력을 기다리고 있을 때 휴대폰에 푸시 알림을 보냅니다. `/config`에 **작업이 필요할 때 푸시**로 표시됩니다. [모바일 푸시 알림](/ko/remote-control#mobile-push-notifications)을 참조하세요. Claude Code v2.1.119 이상이 필요합니다 | `true` |285| `inputNeededNotifEnabled` | {/* min-version: 2.1.119 */}**기본값**: `false`. [Remote Control](/ko/remote-control)이 연결되어 있을 때 권한 프롬프트 또는 질문이 입력을 기다리고 있을 때 휴대폰에 푸시 알림을 보냅니다. `/config`에 **작업이 필요할 때 푸시**로 표시됩니다. [모바일 푸시 알림](/ko/remote-control#mobile-push-notifications)을 참조하세요. Claude Code v2.1.119 이상이 필요합니다 | `true` |

282| `language` | Claude의 선호 응답 언어를 구성합니다 (예: `"japanese"`, `"spanish"`, `"french"`). Claude는 기본적으로 이 언어로 응답합니다. 또한 [음성 받아쓰기](/ko/voice-dictation#change-the-dictation-language) 언어를 설정합니다. {/* min-version: 2.1.176 */}v2.1.176부터 설정되지 않으면 세션 제목이 대화의 언어와 일치합니다 | `"japanese"` |286| `language` | Claude의 선호 응답 언어를 구성합니다 (예: `"japanese"`, `"spanish"`, `"french"`). Claude는 기본적으로 이 언어로 응답합니다. 또한 [음성 받아쓰기](/ko/voice-dictation#change-the-dictation-language) 언어를 설정합니다. {/* min-version: 2.1.176 */}v2.1.176부터 설정되지 않으면 세션 제목이 대화의 언어와 일치합니다 | `"japanese"` |

283| `minimumVersion` | 배경 자동 업데이트 및 `claude update`가 이 버전 아래로 설치되는 것을 방지하는 하한입니다. `"latest"` 채널에서 `"stable"`로 전환할 때 `/config`를 통해 현재 버전에 머물기 또는 다운그레이드를 허용하라는 메시지가 표시됩니다. 머물기를 선택하면 이 값이 설정됩니다. 또한 [managed 설정](/ko/permissions#managed-settings)에서 조직 전체 최소값을 고정하는 데 유용합니다. 시작을 완전히 차단하는 하드 플로어는 `requiredMinimumVersion`을 참조하세요 | `"2.1.100"` |287| `minimumVersion` | 배경 자동 업데이트 및 `claude update`가 이 버전 아래로 설치되는 것을 방지하는 하한입니다. `"latest"` 채널에서 `"stable"`로 전환할 때 `/config`를 통해 현재 버전에 머물기 또는 다운그레이드를 허용하라는 메시지가 표시됩니다. 머물기를 선택하면 이 값이 설정됩니다. 또한 [managed 설정](/ko/permissions#managed-settings)에서 조직 전체 최소값을 고정하는 데 유용합니다. 시작을 완전히 차단하는 하드 플로어는 `requiredMinimumVersion`을 참조하세요 | `"2.1.100"` |

285| `modelOverrides` | Anthropic 모델 ID를 Bedrock 추론 프로필 ARN과 같은 공급자 특정 모델 ID로 매핑합니다. 각 모델 선택기 항목은 공급자 API를 호출할 때 매핑된 값을 사용합니다. [버전별 모델 ID 재정의](/ko/model-config#override-model-ids-per-version)를 참조하세요 | `{"claude-opus-4-6": "arn:aws:bedrock:..."}` |289| `modelOverrides` | Anthropic 모델 ID를 Amazon Bedrock 추론 프로필 ARN과 같은 공급자 특정 모델 ID로 매핑합니다. 각 모델 선택기 항목은 공급자 API를 호출할 때 매핑된 값을 사용합니다. [버전별 모델 ID 재정의](/ko/model-config#override-model-ids-per-version)를 참조하세요 | `{"claude-opus-4-6": "arn:aws:bedrock:..."}` |

286| `otelHeadersHelper` | 동적 OpenTelemetry 헤더를 생성하는 스크립트입니다. 시작 시 및 주기적으로 실행됩니다. [`CLAUDE_CODE_OTEL_HEADERS_HELPER_DEBOUNCE_MS`](/ko/env-vars)로 새로고침 간격을 설정합니다. [동적 헤더](/ko/monitoring-usage#dynamic-headers)를 참조하세요 | `/bin/generate_otel_headers.sh` |290| `otelHeadersHelper` | 동적 OpenTelemetry 헤더를 생성하는 스크립트입니다. 시작 시 및 주기적으로 실행됩니다. [`CLAUDE_CODE_OTEL_HEADERS_HELPER_DEBOUNCE_MS`](/ko/env-vars)로 새로고침 간격을 설정합니다. [동적 헤더](/ko/monitoring-usage#dynamic-headers)를 참조하세요 | `/bin/generate_otel_headers.sh` |

288| `parentSettingsBehavior` | {/* min-version: 2.1.133 */}}(Managed 설정만) **기본값**: `"first-wins"`. Agent SDK 또는 IDE 확장과 같은 embedding host 프로세스에 의해 프로그래밍 방식으로 제공되는 managed 설정이 관리자 배포 managed 계층도 있을 때 적용되는지 여부를 제어합니다. `"first-wins"`: 부모 제공 설정이 삭제되고 관리자 계층만 적용됩니다. `"merge"`: 부모 제공 설정이 관리자 계층 아래에 적용되며, 정책을 강화할 수 있지만 완화할 수 없도록 필터링됩니다. 관리자 계층이 배포되지 않으면 영향을 주지 않습니다. Claude Code v2.1.133 이상이 필요합니다 | `"merge"` |292| `parentSettingsBehavior` | {/* min-version: 2.1.133 */}}(Managed 설정만) **기본값**: `"first-wins"`. Agent SDK 또는 IDE 확장과 같은 embedding host 프로세스에 의해 프로그래밍 방식으로 제공되는 managed 설정이 관리자 배포 managed 계층도 있을 때 적용되는지 여부를 제어합니다. `"first-wins"`: 부모 제공 설정이 삭제되고 관리자 계층만 적용됩니다. `"merge"`: 부모 제공 설정이 관리자 계층 아래에 적용되며, 정책을 강화할 수 있지만 완화할 수 없도록 필터링됩니다. 관리자 계층이 배포되지 않으면 영향을 주지 않습니다. Claude Code v2.1.133 이상이 필요합니다 | `"merge"` |

298| `requiredMaximumVersion` | Managed 설정만. 시작할 수 있는 최대 Claude Code 버전입니다. 실행 중인 버전이 더 최신이면 Claude Code는 시작 시 종료되고 사용자에게 조직의 승인된 방법을 통해 승인된 버전을 설치하도록 지시합니다. `claude install <version>`도 작동할 수 있습니다. 배경 자동 업데이트 및 `claude update`는 천장 위의 버전을 건너뜁니다. 범위 내 설치는 범위 내로 유지됩니다. `claude update`, `claude install` 및 `claude doctor`는 사용자가 복구할 수 있도록 천장 위에서 계속 작동합니다. 이 설정보다 먼저 나온 버전은 무시합니다 | `"2.1.150"` |302| `requiredMaximumVersion` | Managed 설정만. 시작할 수 있는 최대 Claude Code 버전입니다. 실행 중인 버전이 더 최신이면 Claude Code는 시작 시 종료되고 사용자에게 조직의 승인된 방법을 통해 승인된 버전을 설치하도록 지시합니다. `claude install <version>`도 작동할 수 있습니다. 배경 자동 업데이트 및 `claude update`는 천장 위의 버전을 건너뜁니다. 범위 내 설치는 범위 내로 유지됩니다. `claude update`, `claude install` 및 `claude doctor`는 사용자가 복구할 수 있도록 천장 위에서 계속 작동합니다. 이 설정보다 먼저 나온 버전은 무시합니다 | `"2.1.150"` |

299| `requiredMinimumVersion` | Managed 설정만. 시작하는 데 필요한 최소 Claude Code 버전입니다. 실행 중인 버전이 더 오래되면 Claude Code는 시작 시 종료되고 사용자에게 조직의 승인된 방법을 통해 업데이트하도록 지시합니다. `claude update`, `claude install` 및 `claude doctor`는 사용자가 복구할 수 있도록 바닥 아래에서 계속 작동합니다. 시작을 차단하지 않지만 다운그레이드를 방지하는 `minimumVersion`과 다릅니다. 이 설정보다 먼저 나온 버전은 무시합니다 | `"2.1.150"` |303| `requiredMinimumVersion` | Managed 설정만. 시작하는 데 필요한 최소 Claude Code 버전입니다. 실행 중인 버전이 더 오래되면 Claude Code는 시작 시 종료되고 사용자에게 조직의 승인된 방법을 통해 업데이트하도록 지시합니다. `claude update`, `claude install` 및 `claude doctor`는 사용자가 복구할 수 있도록 바닥 아래에서 계속 작동합니다. 시작을 차단하지 않지만 다운그레이드를 방지하는 `minimumVersion`과 다릅니다. 이 설정보다 먼저 나온 버전은 무시합니다 | `"2.1.150"` |

301| `respondToBashCommands` | {/* min-version: 2.1.186 */}}**기본값**: `true`. 입력 상자 `!` 셸 명령이 실행된 후 Claude가 응답할지 여부입니다. 응답 없이 명령 출력을 컨텍스트에 추가하려면 `false`로 설정합니다. [접두사 `!`를 사용한 셸 모드](/ko/interactive-mode#shell-mode-with-prefix)를 참조하세요. Claude Code v2.1.186 이상이 필요합니다 | `false` |305| `respondToBashCommands` | {/* min-version: 2.1.186 */}**기본값**: `true`. 입력 상자 `!` 셸 명령이 실행된 후 Claude가 응답할지 여부입니다. 응답 없이 명령 출력을 컨텍스트에 추가하려면 `false`로 설정합니다. [접두사 `!`를 사용한 셸 모드](/ko/interactive-mode#shell-mode-with-prefix)를 참조하세요. Claude Code v2.1.186 이상이 필요합니다 | `false` |

303| `showThinkingSummaries` | **기본값**: `false`. 대화형 세션에서 [확장 사고](/ko/model-config#extended-thinking) 요약을 표시합니다. 설정되지 않거나 `false`일 때 사고 블록은 API에 의해 편집되고 축소된 스텁으로 표시됩니다. 편집은 표시되는 내용만 변경하고 모델이 생성하는 내용은 변경하지 않습니다. 사고 지출을 줄이려면 [예산을 낮추거나 사고를 비활성화](/ko/model-config#extended-thinking)하세요. 이 설정은 비대화형 모드 (`-p`), Agent SDK 또는 VS Code와 같은 IDE 확장에서는 영향을 주지 않습니다 | `true` |307| `showThinkingSummaries` | **기본값**: `false`. 대화형 세션에서 [확장 사고](/ko/model-config#extended-thinking) 요약을 표시합니다. 설정되지 않거나 `false`일 때 사고 블록은 API에 의해 편집되고 축소된 스텁으로 표시됩니다. 편집은 표시되는 내용만 변경하고 모델이 생성하는 내용은 변경하지 않습니다. 사고 지출을 줄이려면 [예산을 낮추거나 사고를 비활성화](/ko/model-config#extended-thinking)하세요. 이 설정은 비대화형 모드 (`-p`), Agent SDK 또는 VS Code와 같은 IDE 확장에서는 영향을 주지 않습니다 | `true` |

305| `skillListingBudgetFraction` | {/* min-version: 2.1.105 */}}**기본값**: `0.01` (1%). Claude가 각 턴에 보는 [skill 목록](/ko/skills#skill-descriptions-are-cut-short)을 위해 예약된 모델의 컨텍스트 윈도우의 분수입니다. 목록이 예산을 초과하면 가장 적게 사용되는 skills의 설명이 베어 이름으로 축소되어 Claude가 여전히 호출할 수 있지만 이유를 보지 못합니다. 더 많은 설명을 보이려면 높이고 턴당 더 많은 컨텍스트를 사용합니다. 더 많은 skills을 [`skillListingMaxDescChars`](#available-settings) 아래에 맞추려면 낮춥니다. `/doctor`는 현재 잘림 수와 영향을 받는 skills를 표시합니다. Claude Code v2.1.105 이상이 필요합니다 | `0.02` |309| `skillListingBudgetFraction` | {/* min-version: 2.1.105 */}}**기본값**: `0.01` (1%). Claude가 각 턴에 보는 [skill 목록](/ko/skills#skill-descriptions-are-cut-short)을 위해 예약된 모델의 컨텍스트 윈도우의 분수입니다. 목록이 예산을 초과하면 가장 적게 사용되는 skills의 설명이 베어 이름으로 축소되어 Claude가 여전히 호출할 수 있지만 이유를 보지 못합니다. 더 많은 설명을 보이려면 높이고 턴당 더 많은 컨텍스트를 사용합니다. 더 많은 skills을 [`skillListingMaxDescChars`](#available-settings) 아래에 맞추려면 낮춥니다. `/doctor`는 현재 잘림 수와 영향을 받는 skills를 표시합니다. Claude Code v2.1.105 이상이 필요합니다 | `0.02` |

306| `skillListingMaxDescChars` | {/* min-version: 2.1.105 */}}**기본값**: `1536`. Claude가 각 턴에 보는 [skill 목록](/ko/skills#skill-descriptions-are-cut-short)의 결합된 `description` 및 `when_to_use` 텍스트에 대한 skill별 문자 제한입니다. 이 길이보다 긴 텍스트는 잘립니다. 더 긴 설명을 유지하려면 높이고 턴당 더 많은 컨텍스트를 사용합니다. 더 많은 skills을 [`skillListingBudgetFraction`](#available-settings)에 맞추려면 낮춥니다. Claude Code v2.1.105 이상이 필요합니다 | `2048` |310| `skillListingMaxDescChars` | {/* min-version: 2.1.105 */}}**기본값**: `1536`. Claude가 각 턴에 보는 [skill 목록](/ko/skills#skill-descriptions-are-cut-short)의 결합된 `description` 및 `when_to_use` 텍스트에 대한 skill별 문자 제한입니다. 이 길이보다 긴 텍스트는 잘립니다. 더 긴 설명을 유지하려면 높이고 턴당 더 많은 컨텍스트를 사용합니다. 더 많은 skills을 [`skillListingBudgetFraction`](#available-settings)에 맞추려면 낮춥니다. Claude Code v2.1.105 이상이 필요합니다 | `2048` |

307| `skillOverrides` | {/* min-version: 2.1.129 */}}skill 이름으로 키가 지정된 skill별 가시성 재정의입니다. 값은 `"on"`, `"name-only"`, `"user-invocable-only"` 또는 `"off"`입니다. SKILL.md를 편집하지 않고 skill을 숨기거나 축소할 수 있습니다. 플러그인 skills에는 적용되지 않으며, 이는 `/plugin`을 통해 관리됩니다. `/skills` 메뉴는 이를 `.claude/settings.local.json`에 작성합니다. [설정에서 skill 가시성 재정의](/ko/skills#override-skill-visibility-from-settings)를 참조하세요. Claude Code v2.1.129 이상이 필요합니다 | `{"legacy-context": "name-only", "deploy": "off"}` |311| `skillOverrides` | {{/* min-version: 2.1.129 */}}skill 이름으로 키가 지정된 skill별 가시성 재정의입니다. 값은 `"on"`, `"name-only"`, `"user-invocable-only"` 또는 `"off"`입니다. SKILL.md를 편집하지 않고 skill을 숨기거나 축소할 수 있습니다. 플러그인 skills에는 적용되지 않으며, 이는 `/plugin`을 통해 관리됩니다. `/skills` 메뉴는 이를 `.claude/settings.local.json`에 작성합니다. [설정에서 skill 가시성 재정의](/ko/skills#override-skill-visibility-from-settings)를 참조하세요. Claude Code v2.1.129 이상이 필요합니다 | `{"legacy-context": "name-only", "deploy": "off"}` |

308| `skipWebFetchPreflight` | [WebFetch 도메인 안전 검사](/ko/data-usage#webfetch-domain-safety-check)를 건너뜁니다. 이 검사는 각 요청된 호스트명을 가져오기 전에 `api.anthropic.com`으로 전송합니다. Bedrock, Vertex AI 또는 Foundry 배포와 같이 Anthropic으로의 트래픽을 차단하는 환경에서 `true`로 설정합니다. 건너뛰면 WebFetch는 차단 목록을 참조하지 않고 모든 URL을 시도합니다 | `true` |312| `skipWebFetchPreflight` | [WebFetch 도메인 안전 검사](/ko/data-usage#webfetch-domain-safety-check)를 건너뜁니다. 이 검사는 각 요청된 호스트명을 가져오기 전에 `api.anthropic.com`으로 전송합니다. Amazon Bedrock, Google Cloud의 Agent Platform 또는 Microsoft Foundry 배포와 같이 Anthropic으로의 트래픽을 차단하는 환경에서 `true`로 설정합니다. 건너뛰면 WebFetch는 차단 목록을 참조하지 않고 모든 URL을 시도합니다 | `true` |

310| `spinnerTipsOverride` | 사용자 정의 문자열로 스피너 팁을 재정의합니다. `tips`: 팁 문자열 배열. `excludeDefault`: `true`이면 사용자 정의 팁만 표시하고, `false`이거나 없으면 사용자 정의 팁이 기본 제공 팁과 병합됩니다 | `{ "excludeDefault": true, "tips": ["Use our internal tool X"] }` |314| `spinnerTipsOverride` | 사용자 정의 문자열로 스피너 팁을 재정의합니다. `tips`: 팁 문자열 배열. `excludeDefault`: `true`이면 사용자 정의 팁만 표시하고, `false`이거나 없으면 사용자 정의 팁이 기본 제공 팁과 병합됩니다 | `{ "excludeDefault": true, "tips": ["Use our internal tool X"] }` |

311| `spinnerVerbs` | 스피너에 표시되는 작업 동사를 사용자 정의합니다. `mode`를 `"replace"`로 설정하여 동사만 사용하거나 `"append"`로 설정하여 기본값에 추가합니다 | `{"mode": "append", "verbs": ["Pondering", "Crafting"]}` |315| `spinnerVerbs` | 스피너에 표시되는 작업 동사를 사용자 정의합니다. `mode`를 `"replace"`로 설정하여 동사만 사용하거나 `"append"`로 설정하여 기본값에 추가합니다 | `{"mode": "append", "verbs": ["Pondering", "Crafting"]}` |

317| `teammateMode` | **기본값**: `in-process`. [에이전트 팀](/ko/agent-teams) 팀원이 표시되는 방식입니다. `in-process`, `auto` (tmux 또는 iTerm2에서 분할 창 선택, 그 외에는 in-process), `tmux` (tmux 또는 iTerm2를 사용하여 분할 창 선택, 터미널에서 감지됨) 또는 {/* min-version: 2.1.186 */}}`iterm2` (iTerm2 기본 분할 창 via `it2` CLI, v2.1.186에서 추가됨)를 허용합니다. 기본값은 v2.1.179에서 `auto`에서 변경되었습니다. `--teammate-mode`은 한 세션에 대해 이를 재정의합니다. [디스플레이 모드 선택](/ko/agent-teams#choose-a-display-mode)을 참조하세요 | `"auto"` |321| `teammateMode` | **기본값**: `in-process`. [에이전트 팀](/ko/agent-teams) 팀원이 표시되는 방식입니다. `in-process`, `auto` (tmux 또는 iTerm2에서 분할 창 선택, 그 외에는 in-process), `tmux` (tmux 또는 iTerm2를 사용하여 분할 창 선택, 터미널에서 감지됨) 또는 {/* min-version: 2.1.186 */}}`iterm2` (iTerm2 기본 분할 창 via `it2` CLI, v2.1.186에서 추가됨)를 허용합니다. 기본값은 v2.1.179에서 `auto`에서 변경되었습니다. `--teammate-mode`은 한 세션에 대해 이를 재정의합니다. [디스플레이 모드 선택](/ko/agent-teams#choose-a-display-mode)을 참조하세요 | `"auto"` |

319| `theme` | {/* min-version: 2.1.119 */}}**기본값**: `"dark"`. 인터페이스의 색상 테마입니다. `"auto"`, `"dark"`, `"light"`, `"dark-daltonized"`, `"light-daltonized"`, `"dark-ansi"`, `"light-ansi"` 또는 `"custom:<slug>"` 또는 `"custom:<plugin-name>:<slug>"`과 같은 사용자 정의 테마 참조를 허용합니다. [사용자 정의 테마 만들기](/ko/terminal-config#create-a-custom-theme)를 참조하세요. `/config`에 **테마**로 표시됩니다 | `"dark"` |323| `theme` | {{/* min-version: 2.1.119 */}}**기본값**: `"dark"`. 인터페이스의 색상 테마입니다. `"auto"`, `"dark"`, `"light"`, `"dark-daltonized"`, `"light-daltonized"`, `"dark-ansi"`, `"light-ansi"` 또는 `"custom:<slug>"` 또는 `"custom:<plugin-name>:<slug>"`과 같은 사용자 정의 테마 참조를 허용합니다. [사용자 정의 테마 만들기](/ko/terminal-config#create-a-custom-theme)를 참조하세요. `/config`에 **테마**로 표시됩니다 | `"dark"` |

320| `tui` | 터미널 UI 렌더러입니다. 깜박임 없는 [alt-screen 렌더러](/ko/fullscreen)가 있는 가상화된 스크롤백을 위해 `"fullscreen"`을 사용합니다. 클래식 메인 화면 렌더러를 위해 `"default"`를 사용합니다. `/tui`를 통해 설정합니다. [`CLAUDE_CODE_NO_FLICKER`](/ko/env-vars) 환경 변수도 설정할 수 있습니다. [에이전트 보기](/ko/agent-view)에서 열린 배경 세션은 이 설정과 관계없이 항상 fullscreen 렌더러를 사용합니다 | `"fullscreen"` |324| `tui` | 터미널 UI 렌더러입니다. 깜박임 없는 [alt-screen 렌더러](/ko/fullscreen)가 있는 가상화된 스크롤백을 위해 `"fullscreen"`을 사용합니다. 클래식 메인 화면 렌더러를 위해 `"default"`를 사용합니다. `/tui`를 통해 설정합니다. [`CLAUDE_CODE_NO_FLICKER`](/ko/env-vars) 환경 변수도 설정할 수 있습니다. [에이전트 보기](/ko/agent-view)에서 열린 배경 세션은 이 설정과 관계없이 항상 fullscreen 렌더러를 사용합니다 | `"fullscreen"` |

321| `ultracode` | 세션에 대해 [ultracode](/ko/workflows#let-claude-decide-with-ultracode)를 켭니다. 세션 전용이며 `settings.json`에서 읽지 않습니다. `/effort ultracode`, `--settings` 또는 Agent SDK 제어 요청을 통해 설정합니다 | `true` |325| `ultracode` | 세션에 대해 [ultracode](/ko/workflows#let-claude-decide-with-ultracode)를 켭니다. 세션 전용이며 `settings.json`에서 읽지 않습니다. `/effort ultracode`, `--settings` 또는 Agent SDK 제어 요청을 통해 설정합니다. {/* min-version: 2.1.203 */}ultracode를 이미 켜진 상태로 세션을 시작하려면 `claude --effort ultracode`로 시작합니다. Claude Code v2.1.203 이상이 필요합니다 | `true` |

323| `verbose` | {/* min-version: 2.1.119 */}}**기본값**: `false`. 잘린 요약 대신 전체 도구 출력을 표시합니다. `/config`에 **상세 출력**으로 표시됩니다. `--verbose` 플래그는 한 세션에 대해 이를 재정의합니다 | `true` |327| `verbose` | {{/* min-version: 2.1.119 */}}**기본값**: `false`. 잘린 요약 대신 전체 도구 출력을 표시합니다. `/config`에 **상세 출력**으로 표시됩니다. `--verbose` 플래그는 한 세션에 대해 이를 재정의합니다 | `true` |

324| `viewMode` | 시작 시 기본 트랜스크립트 보기 모드입니다. `"default"`, `"verbose"` 또는 `"focus"`를 허용합니다. 설정되면 sticky `/focus` 선택을 재정의합니다. `--verbose` 플래그는 한 세션에 대해 이를 재정의합니다 | `"verbose"` |328| `viewMode` | 시작 시 기본 트랜스크립트 보기 모드입니다. `"default"`, `"verbose"` 또는 `"focus"`를 허용합니다. 설정되면 sticky `/focus` 선택을 재정의합니다. `--verbose` 플래그는 한 세션에 대해 이를 재정의합니다 | `"verbose"` |

325| `voice` | [음성 받아쓰기](/ko/voice-dictation) 설정입니다. `enabled`는 받아쓰기를 켜고, `mode`는 `"hold"` 또는 `"tap"`을 선택하고, `autoSubmit`은 hold 모드에서 키 릴리스 시 프롬프트를 전송합니다. `/voice`를 실행할 때 자동으로 작성됩니다. Claude.ai 계정이 필요합니다 | `{ "enabled": true, "mode": "tap" }` |329| `voice` | [음성 받아쓰기](/ko/voice-dictation) 설정입니다. `enabled`는 받아쓰기를 켜고, `mode`는 `"hold"` 또는 `"tap"`을 선택하고, `autoSubmit`은 hold 모드에서 키 릴리스 시 프롬프트를 전송합니다. `/voice`를 실행할 때 자동으로 작성됩니다. Claude.ai 계정이 필요합니다 | `{ "enabled": true, "mode": "tap" }` |

327| `wheelScrollAccelerationEnabled` | {/* min-version: 2.1.174 */}}**기본값**: `true`. [fullscreen 렌더링](/ko/fullscreen#mouse-wheel-scrolling)에서 빠른 스크롤 중에 마우스 휠 스크롤 속도를 가속화합니다. 휠 노치당 일정한 스크롤 속도를 원하면 `false`로 설정합니다. Claude Code v2.1.174 이상이 필요합니다 | `false` |331| `wheelScrollAccelerationEnabled` | {{/* min-version: 2.1.174 */}}**기본값**: `true`. [fullscreen 렌더링](/ko/fullscreen#mouse-wheel-scrolling)에서 빠른 스크롤 중에 마우스 휠 스크롤 속도를 가속화합니다. 휠 노치당 일정한 스크롤 속도를 원하면 `false`로 설정합니다. Claude Code v2.1.174 이상이 필요합니다 | `false` |

328| `workflowKeywordTriggerEnabled` | {/* min-version: 2.1.157 */}}**기본값**: `true`. 프롬프트의 단어 `ultracode`이 [동적 워크플로우](/ko/workflows#ask-for-a-workflow-in-your-prompt)를 트리거할지 여부입니다. 하나를 트리거하지 않고 단어를 입력하려면 `false`로 설정합니다. `ultracode` 노력 설정, `/workflows` 및 저장된 워크플로우 명령은 영향을 받지 않습니다. `/config`에 **Ultracode 키워드 트리거**로 표시됩니다. v2.1.157에서 추가됨; v2.1.160 이전에 트리거 키워드는 `workflow`였습니다 | `false` |332| `workflowKeywordTriggerEnabled` | {{/* min-version: 2.1.157 */}}**기본값**: `true`. 프롬프트의 단어 `ultracode`이 [동적 워크플로우](/ko/workflows#ask-for-a-workflow-in-your-prompt)를 트리거할지 여부입니다. 하나를 트리거하지 않고 단어를 입력하려면 `false`로 설정합니다. `ultracode` 노력 설정, `/workflows` 및 저장된 워크플로우 명령은 영향을 받지 않습니다. `/config`에 **Ultracode 키워드 트리거**로 표시됩니다. v2.1.157에서 추가됨; v2.1.160 이전에 트리거 키워드는 `workflow`였습니다 | `false` |

329| `wslInheritsWindowsSettings` | (Windows managed 설정만) `true`일 때 WSL의 Claude Code는 `/etc/claude-code`에 추가하여 Windows 정책 체인에서 managed 설정을 읽으며 Windows 소스가 우선합니다. Windows 관리자가 작성해야 하는 HKLM 레지스트리 키 또는 `C:\Program Files\ClaudeCode\managed-settings.json`에서 설정된 경우에만 적용됩니다. HKCU 정책도 WSL에 적용되려면 플래그를 HKCU 자체에도 설정해야 합니다. 기본 Windows에는 영향을 주지 않습니다 | `true` |333| `wslInheritsWindowsSettings` | (Windows managed 설정만) `true`일 때 WSL의 Claude Code는 `/etc/claude-code`에 추가하여 Windows 정책 체인에서 managed 설정을 읽으며 Windows 소스가 우선합니다. Windows 관리자가 작성해야 하는 HKLM 레지스트리 키 또는 `C:\Program Files\ClaudeCode\managed-settings.json`에서 설정된 경우에만 적용됩니다. HKCU 정책도 WSL에 적용되려면 플래그를 HKCU 자체에도 설정해야 합니다. 기본 Windows에는 영향을 주지 않습니다 | `true` |

330 334

331<h3 id="global-config-settings">335<h3 id="global-config-settings">

339</Note>343</Note>

340 344

341| 키 | 설명 | 예제 |345| 키 | 설명 | 예제 |

342| :------------------------ | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :--------- |346| :------------------------ | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :--------- |

343| `autoConnectIde` | **기본값**: `false`. Claude Code가 외부 터미널에서 시작될 때 실행 중인 IDE에 자동으로 연결합니다. VS Code 또는 JetBrains 터미널 외부에서 실행할 때 `/config`에 \*\*IDE에 자동 연결 (외부 터미널)\*\*로 표시됩니다. [`CLAUDE_CODE_AUTO_CONNECT_IDE`](/ko/env-vars) 환경 변수가 설정되면 이를 재정의합니다 | `true` |347| `autoConnectIde` | **기본값**: `false`. Claude Code가 외부 터미널에서 시작될 때 실행 중인 IDE에 자동으로 연결합니다. VS Code 또는 JetBrains 터미널 외부에서 실행할 때 `/config`에 \*\*IDE에 자동 연결 (외부 터미널)\*\*로 표시됩니다. [`CLAUDE_CODE_AUTO_CONNECT_IDE`](/ko/env-vars) 환경 변수가 설정되면 이를 재정의합니다 | `true` |

344| `autoInstallIdeExtension` | **기본값**: `true`. VS Code 터미널에서 실행할 때 Claude Code IDE 확장을 자동으로 설치합니다. VS Code 또는 JetBrains 터미널 내에서 실행할 때 `/config`에 **IDE 확장 자동 설치**로 표시됩니다. [`CLAUDE_CODE_IDE_SKIP_AUTO_INSTALL`](/ko/env-vars) 환경 변수도 설정할 수 있습니다 | `false` |348| `autoInstallIdeExtension` | **기본값**: `true`. VS Code 터미널에서 실행할 때 Claude Code IDE 확장을 자동으로 설치합니다. VS Code 또는 JetBrains 터미널 내에서 실행할 때 `/config`에 **IDE 확장 자동 설치**로 표시됩니다. [`CLAUDE_CODE_IDE_SKIP_AUTO_INSTALL`](/ko/env-vars) 환경 변수도 설정할 수 있습니다 | `false` |

346| `teammateDefaultModel` | [에이전트 팀](/ko/agent-teams) 팀원을 위한 기본 모델로 spawn 프롬프트가 하나를 지정하지 않을 때 사용됩니다. `"sonnet"`과 같은 모델 별칭으로 설정하거나 lead의 현재 `/model` 선택을 상속하려면 `null`로 설정합니다. `/config`에 **기본 팀원 모델**로 표시됩니다 | `"sonnet"` |350| `teammateDefaultModel` | [에이전트 팀](/ko/agent-teams) 팀원을 위한 기본 모델로 spawn 프롬프트가 하나를 지정하지 않을 때 사용됩니다. `"sonnet"`과 같은 모델 별칭으로 설정하거나 lead의 현재 `/model` 선택을 상속하려면 `null`로 설정합니다. `/config`에 **기본 팀원 모델**로 표시됩니다 | `"sonnet"` |

351| `workflowSizeGuideline` | {{/* min-version: 2.1.202 */}}**기본값**: `unrestricted`, 이는 지침을 보내지 않습니다. 동적 워크플로우가 작성하는 [에이전트 수를 목표로 설정](/ko/workflows#set-a-size-guideline)합니다. Claude Code는 값을 Claude에 조언으로 보내며 적용된 상한이 아닙니다. `unrestricted`, `small`, `medium` 또는 `large`를 허용합니다. `/config`에 **동적 워크플로우 크기**로 표시됩니다. `/config workflowSizeGuideline=small`으로 직접 설정할 수도 있습니다. Claude Code v2.1.202 이상이 필요합니다. {/* min-version: 2.1.203 */}지침의 에이전트 수는 [`Large workflow` 경고](/ko/workflows#cost)의 기본 임계값도 대체합니다. 이 동작은 Claude Code v2.1.203 이상이 필요합니다 | `"small"` |

347 352

348<h3 id="worktree-settings">353<h3 id="worktree-settings">

349 Worktree 설정354 Worktree 설정

352`--worktree`가 git worktrees를 생성하고 관리하는 방식을 구성합니다.357`--worktree`가 git worktrees를 생성하고 관리하는 방식을 구성합니다.

353 358

354| 키 | 설명 | 예제 |359| 키 | 설명 | 예제 |

355| :---------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | :------------------------------------ |360| :---------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------ |

356| `worktree.baseRef` | 새 worktrees가 분기하는 ref입니다. `"fresh"` (기본값)은 깨끗한 트리와 일치하는 원격에 대해 `origin/<default-branch>`에서 분기합니다. `"head"`는 현재 local `HEAD`에서 분기하므로 푸시되지 않은 커밋 및 feature-branch 상태가 worktree에 있습니다. `--worktree`, `EnterWorktree` 도구 및 subagent 격리에 적용됩니다 | `"head"` |361| `worktree.baseRef` | 새 worktrees가 분기하는 ref입니다. `"fresh"` (기본값)은 깨끗한 트리와 일치하는 원격에 대해 `origin/<default-branch>`에서 분기합니다. `"head"`는 현재 local `HEAD`에서 분기하므로 푸시되지 않은 커밋 및 feature-branch 상태가 worktree에 있습니다. `--worktree`, `EnterWorktree` 도구 및 subagent 격리에 적용됩니다 | `"head"` |

359| `worktree.bgIsolation` | {/* min-version: 2.1.143 */}}[배경 세션](/ko/agent-view#how-file-edits-are-isolated)의 격리 모드입니다. `"worktree"` (기본값)은 `EnterWorktree`가 호출될 때까지 메인 체크아웃에서 `Edit`/`Write`를 차단합니다. `"none"`은 배경 작업이 작업 복사본을 직접 편집하도록 허용합니다. Claude Code v2.1.143 이상이 필요합니다 | `"none"` |364| `worktree.bgIsolation` | {{/* min-version: 2.1.143 */}}[배경 세션](/ko/agent-view#how-file-edits-are-isolated)의 격리 모드입니다. `"worktree"` (기본값)은 `EnterWorktree`가 호출될 때까지 메인 체크아웃에서 `Edit`/`Write`를 차단합니다. {/* min-version: 2.1.203 */}}git 저장소 외부에서 실패하는 [`WorktreeCreate` hook](/ko/worktrees#non-git-version-control)이 블록을 해제하여 세션이 작업 디렉토리를 제자리에서 편집할 수 있도록 합니다. Claude Code v2.1.203 이상이 필요합니다. `"none"`은 배경 작업이 작업 복사본을 직접 편집하도록 허용합니다. Claude Code v2.1.143 이상이 필요합니다 | `"none"` |

360 365

361worktrees에 `.env`와 같은 gitignored 파일을 복사하려면 설정 대신 프로젝트 루트의 [`.worktreeinclude` 파일](/ko/worktrees#copy-gitignored-files-into-worktrees)을 사용합니다.366worktrees에 `.env`와 같은 gitignored 파일을 복사하려면 설정 대신 프로젝트 루트의 [`.worktreeinclude` 파일](/ko/worktrees#copy-gitignored-files-into-worktrees)을 사용합니다.

362 367

365</h3>370</h3>

366 371

367| 키 | 설명 | 예제 |372| 키 | 설명 | 예제 |

368| :---------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :--------------------------------------------------------------------- |373| :---------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :--------------------------------------------------------------------- |

369| `allow` | 도구 사용을 허용하는 권한 규칙 배열입니다. 도구 이름 globs는 `mcp__<server>__get_*`과 같이 리터럴 `mcp__<server>__` 접두사 뒤의 도구 위치에서만 지원됩니다. 서버 세그먼트는 glob 없어야 합니다. 패턴 매칭 세부 사항은 아래 [권한 규칙 구문](#permission-rule-syntax)을 참조하세요 | `[ "Bash(git diff *)" ]` |374| `allow` | 도구 사용을 허용하는 권한 규칙 배열입니다. 도구 이름 globs는 `mcp__<server>__get_*`과 같이 리터럴 `mcp__<server>__` 접두사 뒤의 도구 위치에서만 지원됩니다. 서버 세그먼트는 glob 없어야 합니다. 패턴 매칭 세부 사항은 아래 [권한 규칙 구문](#permission-rule-syntax)을 참조하세요 | `[ "Bash(git diff *)" ]` |

370| `ask` | 도구 사용 시 확인을 요청하는 권한 규칙 배열입니다. 패턴 매칭 세부 사항은 아래 [권한 규칙 구문](#permission-rule-syntax)을 참조하세요 | `[ "Bash(git push *)" ]` |375| `ask` | 도구 사용 시 확인을 요청하는 권한 규칙 배열입니다. 패턴 매칭 세부 사항은 아래 [권한 규칙 구문](#permission-rule-syntax)을 참조하세요 | `[ "Bash(git push *)" ]` |

371| `deny` | 도구 사용을 거부하는 권한 규칙 배열입니다. 이를 사용하여 Claude Code 액세스에서 민감한 파일을 제외합니다. 도구 이름은 glob 패턴을 허용합니다: `"*"`는 모든 도구를 거부하고 `"mcp__*"`는 모든 MCP 도구를 거부합니다. [권한 규칙 구문](#permission-rule-syntax) 및 [Bash 권한 제한](/ko/permissions#tool-specific-permission-rules)을 참조하세요 | `[ "WebFetch", "Bash(curl *)", "Read(./.env)", "Read(./secrets/**)" ]` |376| `deny` | 도구 사용을 거부하는 권한 규칙 배열입니다. 이를 사용하여 Claude Code 액세스에서 민감한 파일을 제외합니다. 도구 이름은 glob 패턴을 허용합니다: `"*"`는 모든 도구를 거부하고 `"mcp__*"`는 모든 MCP 도구를 거부합니다. [권한 규칙 구문](#permission-rule-syntax) 및 [Bash 권한 제한](/ko/permissions#tool-specific-permission-rules)을 참조하세요 | `[ "WebFetch", "Bash(curl *)", "Read(./.env)", "Read(./secrets/**)" ]` |

372| `additionalDirectories` | Claude가 액세스할 수 있는 추가 [작업 디렉토리](/ko/permissions#working-directories)입니다. 대부분의 `.claude/` 구성은 이러한 디렉토리에서 [발견되지 않습니다](/ko/permissions#additional-directories-grant-file-access-not-configuration) | `[ "../docs/" ]` |377| `additionalDirectories` | Claude가 액세스할 수 있는 추가 [작업 디렉토리](/ko/permissions#working-directories)입니다. 대부분의 `.claude/` 구성은 이러한 디렉토리에서 [발견되지 않습니다](/ko/permissions#additional-directories-grant-file-access-not-configuration) | `[ "../docs/" ]` |

373| `defaultMode` | Claude Code를 열 때 기본 [권한 모드](/ko/permission-modes)입니다. 유효한 값: `default`, `acceptEdits`, `plan`, `auto`, `dontAsk`, `bypassPermissions`. {/* min-version: 2.1.142 */}Claude Code v2.1.142부터 프로젝트 또는 local 설정 (`.claude/settings.json`, `.claude/settings.local.json`)에서 설정되면 `auto`가 무시되므로 저장소가 자신에게 자동 모드를 부여할 수 없습니다. 대신 `~/.claude/settings.json`에서 설정합니다. `--permission-mode` CLI 플래그는 단일 세션에 대해 이 설정을 재정의합니다 | `"acceptEdits"` |378| `defaultMode` | Claude Code를 열 때 기본 [권한 모드](/ko/permission-modes)입니다. 유효한 값: `default`, `acceptEdits`, `plan`, `auto`, `dontAsk`, `bypassPermissions`, 그리고 {{/* min-version: 2.1.200 */}}`manual` (CLI 및 VS Code와 JetBrains 확장에서 Manual로 표시되는 모드의 별칭). `manual` 별칭은 Claude Code v2.1.200 이상이 필요합니다. {{/* min-version: 2.1.142 */}}v2.1.142부터 프로젝트 또는 local 설정 (`.claude/settings.json`, `.claude/settings.local.json`)에서 설정되면 `auto`가 무시되므로 저장소가 자신에게 자동 모드를 부여할 수 없습니다. 대신 `~/.claude/settings.json`에서 설정합니다. `--permission-mode` CLI 플래그는 단일 세션에 대해 이 설정을 재정의합니다 | `"acceptEdits"` |

374| `disableBypassPermissionsMode` | `bypassPermissions` 모드가 활성화되는 것을 방지하려면 `"disable"`로 설정합니다. 이는 `--dangerously-skip-permissions` 명령줄 플래그를 비활성화합니다. 일반적으로 [managed 설정](/ko/permissions#managed-settings)에 배치되어 조직 정책을 적용하지만 모든 범위에서 작동합니다 | `"disable"` |379| `disableBypassPermissionsMode` | `bypassPermissions` 모드가 활성화되는 것을 방지하려면 `"disable"`로 설정합니다. 이는 `--dangerously-skip-permissions` 명령줄 플래그를 비활성화합니다. 일반적으로 [managed 설정](/ko/permissions#managed-settings)에 배치되어 조직 정책을 적용하지만 모든 범위에서 작동합니다 | `"disable"` |

375| `skipDangerousModePermissionPrompt` | `--dangerously-skip-permissions` 또는 `defaultMode: "bypassPermissions"`를 통해 bypass permissions 모드에 들어가기 전에 표시되는 확인 프롬프트를 건너뜁니다. 신뢰할 수 없는 저장소가 프롬프트를 자동으로 우회하는 것을 방지하기 위해 프로젝트 설정 (`.claude/settings.json`)에서 설정되면 무시됩니다 | `true` |380| `skipDangerousModePermissionPrompt` | `--dangerously-skip-permissions` 또는 `defaultMode: "bypassPermissions"`를 통해 bypass permissions 모드에 들어가기 전에 표시되는 확인 프롬프트를 건너뜁니다. 신뢰할 수 없는 저장소가 프롬프트를 자동으로 우회하는 것을 방지하기 위해 프로젝트 설정 (`.claude/settings.json`)에서 설정되면 무시됩니다 | `true` |

376 381

398고급 샌드박싱 동작을 구성합니다. 샌드박싱은 bash 명령을 파일 시스템 및 네트워크에서 격리합니다. 자세한 내용은 [Sandboxing](/ko/sandboxing)을 참조하세요.403고급 샌드박싱 동작을 구성합니다. 샌드박싱은 bash 명령을 파일 시스템 및 네트워크에서 격리합니다. 자세한 내용은 [Sandboxing](/ko/sandboxing)을 참조하세요.

399 404

400| 키 | 설명 | 예제 |405| 키 | 설명 | 예제 |

401| :------------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :--------------------------------------------------- |406| :------------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :--------------------------------------------------- |

403| `failIfUnavailable` | `sandbox.enabled`가 true이지만 샌드박스를 시작할 수 없는 경우 (종속성 누락, 지원되지 않는 플랫폼) 시작 시 오류로 종료합니다. false (기본값)일 때 경고가 표시되고 명령이 샌드박싱되지 않은 상태로 실행됩니다. Managed 설정 배포에서 샌드박싱을 하드 게이트로 요구하는 경우를 위한 것입니다 | `true` |408| `failIfUnavailable` | `sandbox.enabled`가 true이지만 샌드박스를 시작할 수 없는 경우 (종속성 누락, 지원되지 않는 플랫폼) 시작 시 오류로 종료합니다. false (기본값)일 때 경고가 표시되고 명령이 샌드박싱되지 않은 상태로 실행됩니다. Managed 설정 배포에서 샌드박싱을 하드 게이트로 요구하는 경우를 위한 것입니다 | `true` |

410| `filesystem.allowRead` | `denyRead` 영역 내에서 읽기를 다시 허용할 경로입니다. `denyRead`보다 우선합니다. 배열은 모든 설정 범위에서 병합됩니다. 이를 사용하여 작업 공간 전용 읽기 액세스 패턴을 만듭니다. | `["."]` |415| `filesystem.allowRead` | `denyRead` 영역 내에서 읽기를 다시 허용할 경로입니다. `denyRead`보다 우선합니다. 배열은 모든 설정 범위에서 병합됩니다. 이를 사용하여 작업 공간 전용 읽기 액세스 패턴을 만듭니다. | `["."]` |

412| `credentials.files` | {/* min-version: 2.1.187 */}샌드박싱된 명령이 읽을 수 없는 자격 증명 파일 또는 디렉토리입니다. `filesystem.denyRead`와 동일한 읽기 블록을 적용합니다. 별도의 키는 자격 증명 경로를 `credentials.envVars`와 함께 그룹화하고 일반 파일 시스템 규칙과 분리합니다. 각 항목은 `{ "path": "...", "mode": "deny" }`입니다. 경로는 `filesystem.*` 설정과 동일한 [접두사](#sandbox-path-prefixes)를 사용합니다. 배열은 모든 설정 범위에서 병합됩니다. `deny`만 지원됩니다. Claude Code v2.1.187 이상이 필요합니다. | `[{ "path": "~/.aws/credentials", "mode": "deny" }]` |417| `credentials.files` | {{/* min-version: 2.1.187 */}}샌드박싱된 명령이 읽을 수 없는 자격 증명 파일 또는 디렉토리입니다. `filesystem.denyRead`와 동일한 읽기 블록을 적용합니다. 별도의 키는 자격 증명 경로를 `credentials.envVars`와 함께 그룹화하고 일반 파일 시스템 규칙과 분리합니다. 각 항목은 `{ "path": "...", "mode": "deny" }`입니다. 경로는 `filesystem.*` 설정과 동일한 [접두사](#sandbox-path-prefixes)를 사용합니다. 배열은 모든 설정 범위에서 병합됩니다. `deny`만 지원됩니다. Claude Code v2.1.187 이상이 필요합니다. | `[{ "path": "~/.aws/credentials", "mode": "deny" }]` |

413| `credentials.envVars` | {/* min-version: 2.1.187 */}샌드박싱된 명령을 실행하기 전에 설정 해제할 환경 변수입니다. 각 항목은 `{ "name": "...", "mode": "deny" }`입니다. 배열은 모든 설정 범위에서 병합됩니다. `deny`만 지원됩니다. Claude Code v2.1.187 이상이 필요합니다. | `[{ "name": "GITHUB_TOKEN", "mode": "deny" }]` |418| `credentials.envVars` | {{/* min-version: 2.1.187 */}}[샌드박싱된 명령에서 보호](/ko/sandboxing#protect-credentials)할 환경 변수입니다. 각 항목에는 `name` 및 `mode`가 있습니다. 이름은 문자 또는 밑줄로 시작하고 문자, 숫자 및 밑줄만 포함해야 합니다. `deny`는 샌드박싱된 명령의 환경에서 변수를 제거합니다. Claude Code v2.1.187 이상이 필요합니다. {{/* min-version: 2.1.199 */}}`mask`는 샌드박스 내에서 변수를 세션별 sentinel 값으로 바꾸고 샌드박스 프록시는 해당 항목의 `injectHosts`에 대한 아웃바운드 요청에서 실제 값을 대체합니다. `network.tlsTerminate`가 필요하고 Claude Code v2.1.199 이상이 필요합니다. `mask` 항목은 사용자, managed 또는 CLI `--settings` 설정에서만 적용되며 `.claude/settings.json` 또는 `.claude/settings.local.json`에서는 적용되지 않습니다. 배열은 모든 설정 범위에서 병합되고 동일한 변수가 두 모드로 나타날 때 `deny`가 우선합니다. | `[{ "name": "GITHUB_TOKEN", "mode": "deny" }]` |

414| `credentials.envVars[].injectHosts` | {/* min-version: 2.1.199 */}샌드박스 프록시가 실제 값을 대체할 호스트입니다. 각 호스트는 `network.allowedDomains`에서도 정확히 또는 와일드카드로 포함되어야 합니다. 설정되지 않으면 프록시가 `network.allowedDomains`의 모든 호스트에 대해 값을 대체합니다. `mode`가 `deny`일 때 허용되지만 무시됩니다. Claude Code v2.1.199 이상이 필요합니다. | `["api.github.com"]` |419| `credentials.envVars[].injectHosts` | 샌드박스 프록시가 `mask` 항목의 실제 값을 대체할 호스트입니다. 각 호스트는 `network.allowedDomains`에서도 정확히 또는 와일드카드로 포함되어야 합니다. 설정되지 않으면 프록시가 `network.allowedDomains`의 모든 호스트에 대해 값을 대체합니다. `mode`가 `deny`일 때 허용되지만 무시됩니다. Claude Code v2.1.199 이상이 필요합니다. {{/* min-version: 2.1.199 */}} | `["api.github.com"]` |

415| `credentials.allowPlaintextInject` | {/* min-version: 2.1.199 */}}일반 HTTP 요청뿐만 아니라 TLS 종료 HTTPS에서 `mask` 대체를 허용합니다. 일반 HTTP에서 업스트림 ID는 확인되지 않고 자격 증명은 평문으로 이동하므로 신뢰할 수 있는 테스트 네트워크 외부에서는 이를 끕니다. 사용자, managed 또는 CLI `--settings` 설정에서만 적용되며 `.claude/settings.json` 또는 `.claude/settings.local.json`에서는 적용되지 않습니다. 기본값: false. Claude Code v2.1.199 이상이 필요합니다. | `true` |420| `credentials.allowPlaintextInject` | 일반 HTTP 요청뿐만 아니라 TLS 종료 HTTPS에서 `mask` 대체를 허용합니다. 일반 HTTP에서 업스트림 ID는 확인되지 않고 자격 증명은 평문으로 이동하므로 신뢰할 수 있는 테스트 네트워크 외부에서는 이를 끕니다. 사용자, managed 또는 CLI `--settings` 설정에서만 적용되며 `.claude/settings.json` 또는 `.claude/settings.local.json`에서는 적용되지 않습니다. 기본값: false. Claude Code v2.1.199 이상이 필요합니다. {{/* min-version: 2.1.199 */}} | `true` |

416| `network.allowUnixSockets` | (macOS만) Unix 소켓 경로 샌드박스에서 액세스 가능. Linux 및 WSL2에서는 무시되며, seccomp 필터가 소켓 경로를 검사할 수 없습니다. 대신 `allowAllUnixSockets`를 사용합니다. | `["~/.ssh/agent-socket"]` |421| `network.allowUnixSockets` | (macOS만) Unix 소켓 경로 샌드박스에서 액세스 가능. Linux 및 WSL2에서는 무시되며, seccomp 필터가 소켓 경로를 검사할 수 없습니다. 대신 `allowAllUnixSockets`를 사용합니다. | `["~/.ssh/agent-socket"]` |

417| `network.allowAllUnixSockets` | 샌드박스에서 모든 Unix 소켓 연결을 허용합니다. Linux 및 WSL2에서 이는 `socket(AF_UNIX, ...)` 호출을 차단하는 seccomp 필터를 건너뛰므로 Unix 소켓을 허용하는 유일한 방법입니다. 기본값: false | `true` |422| `network.allowAllUnixSockets` | 샌드박스에서 모든 Unix 소켓 연결을 허용합니다. Linux 및 WSL2에서 이는 `socket(AF_UNIX, ...)` 호출을 차단하는 seccomp 필터를 건너뛰므로 Unix 소켓을 허용하는 유일한 방법입니다. 기본값: false | `true` |

422| `network.allowManagedDomainsOnly` | (Managed 설정만) Managed 설정의 `allowedDomains` 및 `WebFetch(domain:...)` 허용 규칙만 존중됩니다. 사용자, 프로젝트 및 local 설정의 도메인은 무시됩니다. 허용되지 않은 도메인은 사용자에게 메시지를 표시하지 않고 자동으로 차단됩니다. 거부된 도메인은 여전히 모든 소스에서 존중됩니다. 기본값: false | `true` |427| `network.allowManagedDomainsOnly` | (Managed 설정만) Managed 설정의 `allowedDomains` 및 `WebFetch(domain:...)` 허용 규칙만 존중됩니다. 사용자, 프로젝트 및 local 설정의 도메인은 무시됩니다. 허용되지 않은 도메인은 사용자에게 메시지를 표시하지 않고 자동으로 차단됩니다. 거부된 도메인은 여전히 모든 소스에서 존중됩니다. 기본값: false | `true` |

423| `network.httpProxyPort` | 자신의 프록시를 가져오려는 경우 사용되는 HTTP 프록시 포트입니다. 지정되지 않으면 Claude가 자신의 프록시를 실행합니다. | `8080` |428| `network.httpProxyPort` | 자신의 프록시를 가져오려는 경우 사용되는 HTTP 프록시 포트입니다. 지정되지 않으면 Claude가 자신의 프록시를 실행합니다. | `8080` |

424| `network.socksProxyPort` | 자신의 프록시를 가져오려는 경우 사용되는 SOCKS5 프록시 포트입니다. 지정되지 않으면 Claude가 자신의 프록시를 실행합니다. | `8081` |429| `network.socksProxyPort` | 자신의 프록시를 가져오려는 경우 사용되는 SOCKS5 프록시 포트입니다. 지정되지 않으면 Claude가 자신의 프록시를 실행합니다. | `8081` |

425| `network.tlsTerminate` | {/* min-version: 2.1.199 */}}실험적입니다. 샌드박스 프록시 내에서 TLS를 종료하여 HTTPS 요청의 내용을 읽을 수 있습니다. `mask` [자격 증명 대체](/ko/sandboxing#protect-credentials)에 필요합니다. 세션에 대한 임시 인증 기관을 생성하려면 `{}`로 설정하거나 자신의 것을 사용하려면 `caCertPath` 및 `caKeyPath`로 설정합니다. 사용자, managed 또는 CLI `--settings` 설정에서만 적용되며 `.claude/settings.json` 또는 `.claude/settings.local.json`에서는 적용되지 않습니다. Claude Code v2.1.199 이상이 필요합니다. | `{}` |430| `network.tlsTerminate` | {{/* min-version: 2.1.199 */}}실험적입니다. 샌드박스 프록시 내에서 TLS를 종료하여 HTTPS 요청의 내용을 읽을 수 있습니다. `mask` [자격 증명 대체](/ko/sandboxing#protect-credentials)에 필요합니다. 세션에 대한 임시 인증 기관을 생성하려면 `{}`로 설정하거나 자신의 것을 사용하려면 `caCertPath` 및 `caKeyPath`로 설정합니다. 사용자, managed 또는 CLI `--settings` 설정에서만 적용되며 `.claude/settings.json` 또는 `.claude/settings.local.json`에서는 적용되지 않습니다. Claude Code v2.1.199 이상이 필요합니다. {{/* min-version: 2.1.199 */}} | `{}` |

427| `enableWeakerNetworkIsolation` | (macOS만) 샌드박스에서 시스템 TLS 신뢰 서비스 (`com.apple.trustd.agent`)에 대한 액세스를 허용합니다. MITM 프록시 및 사용자 정의 CA를 사용하는 `httpProxyPort`를 사용할 때 `gh`, `gcloud` 및 `terraform`과 같은 Go 기반 도구가 TLS 인증서를 확인하는 데 필요합니다. **보안을 감소시킵니다** 잠재적 데이터 유출 경로를 열어서. 기본값: false | `true` |432| `enableWeakerNetworkIsolation` | (macOS만) 샌드박스에서 시스템 TLS 신뢰 서비스 (`com.apple.trustd.agent`)에 대한 액세스를 허용합니다. MITM 프록시 및 사용자 정의 CA를 사용하는 `httpProxyPort`를 사용할 때 `gh`, `gcloud` 및 `terraform`과 같은 Go 기반 도구가 TLS 인증서를 확인하는 데 필요합니다. **보안을 감소시킵니다** 잠재적 데이터 유출 경로를 열어서. 기본값: false | `true` |

428| `allowAppleEvents` | (macOS만) 샌드박싱된 명령이 Apple Events를 보낼 수 있도록 허용합니다. `open`, `osascript` 및 URL을 브라우저에서 열 수 있는 도구에 필요하며, 그렇지 않으면 오류 `-600`으로 실패합니다. **코드 실행 격리를 제거합니다.** 샌드박싱된 명령은 사용자 프롬프트 없이 다른 애플리케이션을 샌드박싱되지 않은 상태로 시작할 수 있습니다. 또한 Terminal과 같은 실행 중인 애플리케이션에 AppleScript 명령을 보낼 수 있으며, 이는 앱별 macOS 자동화 동의 프롬프트 (TCC)의 대상입니다. 사용자, managed 또는 CLI 설정에서만 적용되며 프로젝트 설정에서는 적용되지 않습니다. 기본값: false | `true` |433| `allowAppleEvents` | (macOS만) 샌드박싱된 명령이 Apple Events를 보낼 수 있도록 허용합니다. `open`, `osascript` 및 URL을 브라우저에서 열 수 있는 도구에 필요하며, 그렇지 않으면 오류 `-600`으로 실패합니다. **코드 실행 격리를 제거합니다.** 샌드박싱된 명령은 사용자 프롬프트 없이 다른 애플리케이션을 샌드박싱되지 않은 상태로 시작할 수 있습니다. 또한 Terminal과 같은 실행 중인 애플리케이션에 AppleScript 명령을 보낼 수 있으며, 이는 앱별 macOS 자동화 동의 프롬프트 (TCC)의 대상입니다. 사용자, managed 또는 CLI 설정에서만 적용되며 프로젝트 설정에서는 적용되지 않습니다. 기본값: false | `true` |

683예를 들어 사용자 설정이 `permissions.defaultMode`를 `acceptEdits`로 설정하지만 프로젝트의 공유 설정이 이를 `default`로 설정하면 프로젝트 값이 적용됩니다. 아래 예제는 배열 값 설정 (예: 권한 규칙)이 대신 어떻게 결합되는지를 다룹니다.688예를 들어 사용자 설정이 `permissions.defaultMode`를 `acceptEdits`로 설정하지만 프로젝트의 공유 설정이 이를 `default`로 설정하면 프로젝트 값이 적용됩니다. 아래 예제는 배열 값 설정 (예: 권한 규칙)이 대신 어떻게 결합되는지를 다룹니다.

684 689

685<Note>690<Note>

686 **배열 설정은 범위 전체에서 병합됩니다.** 동일한 배열 값 설정 (예: `sandbox.filesystem.allowWrite` 또는 `permissions.allow`)이 여러 범위에 나타나면 배열은 **연결되고 중복 제거되며** 대체되지 않습니다. 이는 낮은 우선순위 범위가 높은 우선순위 범위에서 설정한 항목을 재정의하지 않고 항목을 추가할 수 있음을 의미하며 그 반대도 마찬가지입니다. 예를 들어 managed 설정이 `allowWrite`를 `["/opt/company-tools"]`로 설정하고 사용자가 `["~/.kube"]`를 추가하면 두 경로 모두 최종 구성에 포함됩니다. 두 가지 예외가 있습니다: [`fallbackModel`](#available-settings)은 위치가 의미를 가지는 순서가 지정된 체인입니다: 이를 정의하는 최고 우선순위 파일이 전체 값을 제공합니다. [`availableModels`](#available-settings): {/* min-version: 2.1.175 */}[최고 우선순위 managed 소스](/ko/server-managed-settings#settings-precedence)가 이를 정의할 때 해당 목록이 그대로 적용되고 사용자, 프로젝트 및 local 항목은 이를 확장할 수 없습니다. 비 managed 범위 전체에서 배열은 평소대로 병합됩니다. [병합 동작](/ko/model-config#merge-behavior)을 참조하세요.691 **배열 설정은 범위 전체에서 병합됩니다.** 동일한 배열 값 설정 (예: `sandbox.filesystem.allowWrite` 또는 `permissions.allow`)이 여러 범위에 나타나면 배열은 **연결되고 중복 제거되며** 대체되지 않습니다. 이는 낮은 우선순위 범위가 높은 우선순위 범위에서 설정한 항목을 재정의하지 않고 항목을 추가할 수 있음을 의미하며 그 반대도 마찬가지입니다. 예를 들어 managed 설정이 `allowWrite`를 `["/opt/company-tools"]`로 설정하고 사용자가 `["~/.kube"]`를 추가하면 두 경로 모두 최종 구성에 포함됩니다. 두 가지 예외가 있습니다: [`fallbackModel`](#available-settings)은 위치가 의미를 가지는 순서가 지정된 체인입니다: 이를 정의하는 최고 우선순위 파일이 전체 값을 제공합니다. [`availableModels`](#available-settings): {{/* min-version: 2.1.175 */}}[최고 우선순위 managed 소스](/ko/server-managed-settings#settings-precedence)가 이를 정의할 때 해당 목록이 그대로 적용되고 사용자, 프로젝트 및 local 항목은 이를 확장할 수 없습니다. 비 managed 범위 전체에서 배열은 평소대로 병합됩니다. [병합 동작](/ko/model-config#merge-behavior)을 참조하세요.

687</Note>692</Note>

688 693

689<h3 id="verify-active-settings">694<h3 id="verify-active-settings">

setup.md +9 −3

Details

188 인증188 인증

189</h2>189</h2>

190 190

191Claude Code는 Pro, Max, Team, Enterprise 또는 Console 계정이 필요합니다. 무료 Claude.ai 플랜에는 Claude Code 액세스가 포함되지 않습니다. [Amazon Bedrock](/ko/amazon-bedrock), [Google Vertex AI](/ko/google-vertex-ai) 또는 [Microsoft Foundry](/ko/microsoft-foundry)와 같은 타사 API 제공자와 함께 Claude Code를 사용할 수도 있습니다.191Claude Code는 Pro, Max, Team, Enterprise 또는 Console 계정이 필요합니다. 무료 Claude.ai 플랜에는 Claude Code 액세스가 포함되지 않습니다. [Amazon Bedrock](/ko/amazon-bedrock), [Google Cloud의 Agent Platform](/ko/google-vertex-ai) 또는 [Microsoft Foundry](/ko/microsoft-foundry)와 같은 타사 API 제공자와 함께 Claude Code를 사용할 수도 있습니다.

192 192

193설치 후 `claude`를 실행하고 브라우저 프롬프트를 따라 로그인하세요. 모든 계정 유형 및 팀 설정 옵션은 [인증](/ko/authentication)을 참조하세요.193설치 후 `claude`를 실행하고 브라우저 프롬프트를 따라 로그인하세요. 모든 계정 유형 및 팀 설정 옵션은 [인증](/ko/authentication)을 참조하세요.

194 194

376 376

377<Tabs>377<Tabs>

378 <Tab title="apt">378 <Tab title="apt">

379 Debian 및 Ubuntu용입니다. 다음 명령은 `stable` 채널을 구성합니다:379 Debian 및 Ubuntu용입니다. 설치 명령은 아래에서 `curl`로 서명 키를 다운로드합니다. 새로운 Debian 및 Ubuntu 설치에는 `curl`이 포함되지 않을 수 있습니다. 다운로드가 `sudo: curl: command not found`로 실패하면 먼저 curl을 설치하세요:

380

381 ```bash theme={null}

382 sudo apt install curl

383 ```

384

385 다음 명령은 `stable` 채널을 구성합니다:

380 386

381 ```bash theme={null}387 ```bash theme={null}

382 sudo install -d -m 0755 /etc/apt/keyrings388 sudo install -d -m 0755 /etc/apt/keyrings

526 </Step>532 </Step>

527 533

528 <Step title="바이너리를 매니페스트와 비교">534 <Step title="바이너리를 매니페스트와 비교">

529 다운로드한 바이너리의 SHA256 체크섬을 `manifest.json`의 `platforms.<platform>.checksum` 아래에 나열된 값과 비교합니다.535 현재 디렉터리의 `claude` 바이너리의 SHA256 체크섬을 `manifest.json`의 `platforms.<platform>.checksum` 아래에 나열된 값과 비교합니다. 설치된 네이티브 바이너리를 대신 확인하려면 `~/.local/share/claude/versions/VERSION`에 대해 명령을 실행하고 VERSION을 단계 2에서 설정한 릴리스로 바꾸세요.

530 536

531 <Tabs>537 <Tabs>

532 <Tab title="Linux">538 <Tab title="Linux">

skills.md +13 −5

Details

22 번들 skills22 번들 skills

23</h2>23</h2>

24 24

25Claude Code에는 모든 세션에서 사용 가능한 번들 skills 세트가 포함되어 있으며, [`disableBundledSkills`](/ko/settings#available-settings) 설정으로 비활성화하지 않는 한 `/code-review`, `/batch`, `/debug`, `/loop`, `/claude-api`를 포함합니다. 고정 로직을 직접 실행하는 대부분의 기본 제공 명령어와 달리, 번들 skills는 프롬프트 기반입니다: Claude에 상세한 지시사항을 제공하고 도구를 사용하여 작업을 조율하도록 합니다. 다른 skill과 동일한 방식으로 호출합니다: `/` 다음에 skill 이름을 입력합니다.25Claude Code에는 모든 세션에서 사용 가능한 번들 skills 세트가 포함되어 있으며, [`disableBundledSkills`](/ko/settings#available-settings) 설정으로 비활성화하지 않는 한 `/doctor`, `/code-review`, `/batch`, `/debug`, `/loop`, `/claude-api`를 포함합니다. 고정 로직을 직접 실행하는 대부분의 기본 제공 명령어와 달리, 번들 skills는 프롬프트 기반입니다: Claude에 상세한 지시사항을 제공하고 도구를 사용하여 작업을 조율하도록 합니다. 다른 skill과 동일한 방식으로 호출합니다: `/` 다음에 skill 이름을 입력합니다.

27[`/doctor`](/ko/commands#all-commands) 설정 점검은 Claude Code v2.1.205 이상에서 `disableBundledSkills`의 예외입니다: 설정이 켜져 있을 때도 입력 가능합니다. 이를 숨기려면 `DISABLE_DOCTOR_COMMAND` 환경 변수를 설정하거나 [`skillOverrides`](#override-skill-visibility-from-settings) 항목에서 `"doctor": "off"`를 설정합니다. v2.1.205 이전에는 `/doctor`가 번들 skill이 아닌 기본 제공 명령어였습니다.

26 28

27번들 skills는 [명령어 참조](/ko/commands)에 나열되어 있으며, 목적 열에 **Skill**로 표시됩니다.29번들 skills는 [명령어 참조](/ko/commands)에 나열되어 있으며, 목적 열에 **Skill**로 표시됩니다.

28 30

129 131

130`/deploy`를 입력하면 프로젝트 루트 skill이 실행됩니다. 중첩된 변형을 명시적으로 실행하려면 한정된 이름 `/apps/web:deploy`를 입력합니다.132`/deploy`를 입력하면 프로젝트 루트 skill이 실행됩니다. 중첩된 변형을 명시적으로 실행하려면 한정된 이름 `/apps/web:deploy`를 입력합니다.

131 133

134한정되지 않은 이름을 호출하거나 Claude가 호출할 때, 프로젝트 루트 skill이 로드되고, Claude Code는 디렉토리 한정 변형 목록을 해당 콘텐츠에 추가하며, Claude가 작업 중인 파일을 보유한 변형도 호출하도록 지시합니다. 따라서 중첩된 skill은 한정되지 않은 이름만 호출할 때도 해당 디렉토리의 작업에 계속 적용됩니다. Claude Code v2.1.203 이상이 필요합니다.

135

132`<skill-name>` 항목이 enterprise, personal 또는 project 위치에 있을 수 있으며, 디스크의 다른 곳에 있는 디렉토리로의 symlink일 수 있습니다. Claude Code는 symlink를 따라가고 대상 디렉토리에서 `SKILL.md`를 읽으며, 같은 대상에 둘 이상의 위치에서 도달할 수 있으면 Claude Code는 skill을 한 번만 로드합니다. Plugin skills는 symlinks를 다르게 처리합니다. [마켓플레이스 내에서 symlinks를 사용하여 파일 공유](/ko/plugins-reference#share-files-within-a-marketplace-with-symlinks)를 참조하세요.136`<skill-name>` 항목이 enterprise, personal 또는 project 위치에 있을 수 있으며, 디스크의 다른 곳에 있는 디렉토리로의 symlink일 수 있습니다. Claude Code는 symlink를 따라가고 대상 디렉토리에서 `SKILL.md`를 읽으며, 같은 대상에 둘 이상의 위치에서 도달할 수 있으면 Claude Code는 skill을 한 번만 로드합니다. Plugin skills는 symlinks를 다르게 처리합니다. [마켓플레이스 내에서 symlinks를 사용하여 파일 공유](/ko/plugins-reference#share-files-within-a-marketplace-with-symlinks)를 참조하세요.

133 137

134<Note>138<Note>

175 179

176`--add-dir` 플래그와 `/add-dir` 명령어는 [파일 액세스를 부여](/ko/permissions#additional-directories-grant-file-access-not-configuration)하지만 구성 검색은 하지 않습니다. 그러나 skills는 예외입니다: 추가된 디렉토리 내의 `.claude/skills/`는 자동으로 로드됩니다. 이 예외는 `--add-dir`과 `/add-dir`에만 적용됩니다. `settings.json`의 `permissions.additionalDirectories` 설정은 파일 액세스만 부여하며 skills를 로드하지 않습니다. [라이브 변경 감지](#live-change-detection)를 참조하여 세션 중에 편집이 어떻게 선택되는지 확인하세요.180`--add-dir` 플래그와 `/add-dir` 명령어는 [파일 액세스를 부여](/ko/permissions#additional-directories-grant-file-access-not-configuration)하지만 구성 검색은 하지 않습니다. 그러나 skills는 예외입니다: 추가된 디렉토리 내의 `.claude/skills/`는 자동으로 로드됩니다. 이 예외는 `--add-dir`과 `/add-dir`에만 적용됩니다. `settings.json`의 `permissions.additionalDirectories` 설정은 파일 액세스만 부여하며 skills를 로드하지 않습니다. [라이브 변경 감지](#live-change-detection)를 참조하여 세션 중에 편집이 어떻게 선택되는지 확인하세요.

177 181

178다른 `.claude/` 구성(예: subagents, 명령어 및 출력 스타일)은 추가 디렉토리에서 로드되지 않습니다. 로드되는 항목과 로드되지 않는 항목의 전체 목록과 프로젝트 간 구성을 공유하는 권장 방법은 [예외 표](/ko/permissions#additional-directories-grant-file-access-not-configuration)를 참조하세요.182다른 `.claude/` 구성(예: 명령어 및 출력 스타일)은 추가 디렉토리에서 로드되지 않습니다. 로드되는 항목과 로드되지 않는 항목의 전체 목록과 프로젝트 간 구성을 공유하는 권장 방법은 [예외 표](/ko/permissions#additional-directories-grant-file-access-not-configuration)를 참조하세요.

179 183

180<Note>184<Note>

181 `--add-dir` 디렉토리의 CLAUDE.md 파일은 기본적으로 로드되지 않습니다. 로드하려면 `CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1`을 설정하세요. [추가 디렉토리에서 로드](/ko/memory#load-from-additional-directories)를 참조하세요.185 `--add-dir` 디렉토리의 CLAUDE.md 파일은 기본적으로 로드되지 않습니다. 로드하려면 `CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1`을 설정하세요. [추가 디렉토리에서 로드](/ko/memory#load-from-additional-directories)를 참조하세요.

390 394

391사용자 또는 Claude가 skill을 호출하면, 렌더링된 `SKILL.md` 콘텐츠는 대화에 단일 메시지로 들어가고 세션의 나머지 부분 동안 그대로 유지됩니다. Claude Code는 나중의 턴에서 skill 파일을 다시 읽지 않으므로, 작업 전체에 적용되어야 하는 지침을 일회성 단계가 아닌 상시 지침으로 작성합니다.395사용자 또는 Claude가 skill을 호출하면, 렌더링된 `SKILL.md` 콘텐츠는 대화에 단일 메시지로 들어가고 세션의 나머지 부분 동안 그대로 유지됩니다. Claude Code는 나중의 턴에서 skill 파일을 다시 읽지 않으므로, 작업 전체에 적용되어야 하는 지침을 일회성 단계가 아닌 상시 지침으로 작성합니다.

392 396

397렌더링된 콘텐츠가 이미 컨텍스트에 있는 복사본과 동일한 skill을 Claude가 다시 호출할 때, Claude Code는 콘텐츠의 두 번째 복사본 대신 skill이 이미 로드되었다는 짧은 메모를 추가합니다. 렌더링된 콘텐츠가 다를 때(인수가 변경되었거나 [동적 컨텍스트](#inject-dynamic-context) 명령어가 새로운 출력을 생성했기 때문에), Claude Code는 전체 콘텐츠를 다시 추가합니다. v2.1.202 이전에는 모든 재호출이 skill의 지침의 또 다른 전체 복사본을 추가했습니다.

398

393[자동 압축](/ko/how-claude-code-works#when-context-fills-up)은 토큰 예산 내에서 호출된 skills를 전달합니다. 대화가 요약되어 컨텍스트를 확보하면, Claude Code는 요약 후 각 skill의 가장 최근 호출을 다시 첨부하여 처음 5,000토큰을 유지합니다. 다시 첨부된 skills는 25,000토큰의 결합 예산을 공유합니다. Claude Code는 가장 최근에 호출된 skill부터 시작하여 이 예산을 채우므로, 한 세션에서 많은 skills를 호출한 경우 압축 후 이전 skills가 완전히 삭제될 수 있습니다.399[자동 압축](/ko/how-claude-code-works#when-context-fills-up)은 토큰 예산 내에서 호출된 skills를 전달합니다. 대화가 요약되어 컨텍스트를 확보하면, Claude Code는 요약 후 각 skill의 가장 최근 호출을 다시 첨부하여 처음 5,000토큰을 유지합니다. 다시 첨부된 skills는 25,000토큰의 결합 예산을 공유합니다. Claude Code는 가장 최근에 호출된 skill부터 시작하여 이 예산을 채우므로, 한 세션에서 많은 skills를 호출한 경우 압축 후 이전 skills가 완전히 삭제될 수 있습니다.

394 400

395skill이 첫 번째 응답 후 동작에 영향을 미치지 않는 것처럼 보이면, 콘텐츠는 일반적으로 여전히 존재하며 모델이 다른 도구나 접근 방식을 선택하고 있습니다. skill의 `description` 및 지침을 강화하여 모델이 계속 선호하도록 하거나, [hooks](/ko/hooks)를 사용하여 동작을 결정론적으로 적용합니다. skill이 크거나 그 후에 다른 여러 skills를 호출한 경우, 압축 후 전체 콘텐츠를 복원하려면 다시 호출합니다.401skill이 첫 번째 응답 후 동작에 영향을 미치지 않는 것처럼 보이면, 콘텐츠는 일반적으로 여전히 존재하며 모델이 다른 도구나 접근 방식을 선택하고 있습니다. skill의 `description` 및 지침을 강화하여 모델이 계속 선호하도록 하거나, [hooks](/ko/hooks)를 사용하여 동작을 결정론적으로 적용합니다. skill이 크거나 그 후에 다른 여러 skills를 호출한 경우, 압축 후 전체 콘텐츠를 복원하려면 다시 호출합니다.

906 Skill 설명이 잘림912 Skill 설명이 잘림

907</h3>913</h3>

908 914

909Skill 설명은 Claude가 사용 가능한 항목을 알 수 있도록 컨텍스트에 로드됩니다. 모든 skill 이름은 항상 포함되지만, 많은 skills가 있으면 설명이 단축되어 문자 예산에 맞출 수 있으며, 이는 Claude가 요청과 일치하는 데 필요한 키워드를 제거할 수 있습니다. 예산은 모델의 컨텍스트 윈도우의 1%에서 확장됩니다. 예산이 초과되면, 가장 적게 호출하는 skills의 설명이 먼저 삭제되므로 실제로 사용하는 skills는 전체 텍스트를 유지합니다. `/doctor`를 실행하여 얼마나 많은 skill 설명이 단축되거나 삭제되었는지, 어떤 skills가 영향을 받는지 확인합니다.915Claude Code는 skill 이름과 설명 목록을 컨텍스트에 로드하여 Claude가 사용 가능한 항목을 알 수 있도록 합니다. 목록에는 항상 모든 skill 이름이 포함되지만, skill이 많으면 Claude Code는 설명을 단축하여 목록의 문자 예산에 맞추며, 이는 Claude가 요청과 일치하는 데 필요한 키워드를 제거할 수 있습니다. 예산은 모델의 컨텍스트 윈도우의 1%에서 확장됩니다. 목록이 예산을 초과하면, Claude Code는 가장 적게 호출하는 skill부터 설명을 삭제하므로 가장 자주 사용하는 skill은 전체 텍스트를 유지합니다.

916

917`/doctor`를 실행하여 목록의 컨텍스트 비용 추정치와 가장 큰 기여자를 확인합니다. 목록이 예산을 초과하면, Claude Code는 [`--debug`](/ko/cli-reference#cli-flags)로 볼 수 있는 디버그 로그에 경고를 작성합니다.

910 918

911v2.1.196부터 `/context`의 Skills 행은 예산이 적용된 후의 목록 크기를 보고하므로 모델이 수신하는 것과 일치합니다. 이전 버전은 모든 설명의 전체 텍스트를 계산했으므로 행이 예산 `/doctor`가 보고하는 값보다 몇 배 더 큰 값을 표시할 수 있습니다.919`/context`의 Skills 행은 예산이 적용된 후의 목록 크기를 보고하므로 모델이 수신하는 것과 일치합니다. v2.1.196 이전에는 행이 모든 설명의 전체 텍스트를 계산했으므로 구성된 예산보다 몇 배 더 큰 값을 표시할 수 있었습니다.

912 920

913예산을 높이려면 [`skillListingBudgetFraction`](/ko/settings#available-settings) 설정(예: `0.02` = 2%)을 설정하거나 `SLASH_COMMAND_TOOL_CHAR_BUDGET` 환경 변수를 고정 문자 수로 설정합니다. 다른 skills를 위해 예산을 확보하려면 [`skillOverrides`](#override-skill-visibility-from-settings)에서 낮은 우선순위 항목을 `"name-only"`로 설정하여 설명 없이 나열되도록 합니다. 또한 소스에서 `description` 및 `when_to_use` 텍스트를 자를 수 있습니다: 주요 사용 사례를 먼저 배치합니다. 각 항목의 결합된 텍스트는 예산과 관계없이 1,536자로 제한되기 때문입니다. 이 제한은 [`skillListingMaxDescChars`](/ko/settings#available-settings)로 구성할 수 있습니다.921예산을 높이려면 [`skillListingBudgetFraction`](/ko/settings#available-settings) 설정(예: `0.02` = 2%)을 설정하거나 `SLASH_COMMAND_TOOL_CHAR_BUDGET` 환경 변수를 고정 문자 수로 설정합니다. 다른 skill을 위해 예산을 확보하려면 [`skillOverrides`](#override-skill-visibility-from-settings)에서 낮은 우선순위 항목을 `"name-only"`로 설정하여 설명 없이 나열되도록 합니다. 또한 소스에서 `description` 및 `when_to_use` 텍스트를 자를 수 있습니다: 주요 사용 사례를 먼저 배치합니다. 각 항목의 결합된 텍스트는 예산과 관계없이 1,536자로 제한되기 때문입니다. 이 제한은 [`skillListingMaxDescChars`](/ko/settings#available-settings)로 구성할 수 있습니다.

914 922

915<h2 id="related-resources">923<h2 id="related-resources">

916 관련 리소스924 관련 리소스

statusline.md +3 −1

Details

1044}1044}

1045```1045```

1046 1046

1047명령은 새로 고침 틱마다 한 번 실행되며 모든 표시 가능한 서브에이전트 행이 stdin의 단일 JSON 객체로 전달됩니다. 입력에는 [기본 훅 필드](/ko/hooks#common-input-fields)와 `columns`(사용 가능한 행 너비) 및 `tasks` 배열이 포함되며, 각 작업에는 `id`, `name`, `type`, `status`, `description`, `label`, `startTime`, `tokenCount`, `tokenSamples` 및 `cwd`가 있습니다.1047명령은 새로 고침 틱마다 한 번 실행되며 모든 표시 가능한 서브에이전트 행이 stdin의 단일 JSON 객체로 전달됩니다. 입력에는 [기본 훅 필드](/ko/hooks#common-input-fields), `columns` 필드(사용 가능한 행 너비 포함) 및 `tasks` 배열이 포함됩니다. 각 작업에는 `id`, `name`, `type`, `status`, `description`, `label`, `startTime`, `model`, `contextWindowSize`, `tokenCount`, `tokenSamples` 및 `cwd`가 있습니다.

1048

1049작업별 `model` 필드는 작업이 실행되는 확인된 모델 ID입니다. `contextWindowSize`는 해당 모델의 컨텍스트 윈도우(토큰 단위)이며, 메인 상태 표시줄의 `context_window.context_window_size`와 동일한 방식으로 계산되므로 `tokenCount`에서 행별 백분율을 렌더링할 수 있습니다. 두 필드 모두 Claude Code v2.1.205 이상이 필요하며 모델이 아직 확인되지 않은 작업의 경우 생략됩니다.

1048 1050

1049재정의하려는 각 행에 대해 stdout에 한 줄의 JSON을 작성합니다: `{"id": "<task id>", "content": "<row body>"}`. `content` 문자열은 ANSI 색상 및 OSC 8 하이퍼링크를 포함하여 그대로 렌더링됩니다. 작업의 `id`를 생략하여 해당 행의 기본 렌더링을 유지합니다. 빈 `content` 문자열을 내보내 숨깁니다.1051재정의하려는 각 행에 대해 stdout에 한 줄의 JSON을 작성합니다: `{"id": "<task id>", "content": "<row body>"}`. `content` 문자열은 ANSI 색상 및 OSC 8 하이퍼링크를 포함하여 그대로 렌더링됩니다. 작업의 `id`를 생략하여 해당 행의 기본 렌더링을 유지합니다. 빈 `content` 문자열을 내보내 숨깁니다.

1050 1052

sub-agents.md +15 −7

Details

183 183

184Claude Code는 `.claude/agents/` 및 `~/.claude/agents/`를 재귀적으로 스캔하므로 `agents/review/` 또는 `agents/research/`와 같은 하위 폴더로 정의를 구성할 수 있습니다. 하위 디렉토리 경로는 subagent가 식별되거나 호출되는 방식에 영향을 주지 않습니다. 왜냐하면 ID는 `name` frontmatter 필드에서만 나오기 때문입니다.184Claude Code는 `.claude/agents/` 및 `~/.claude/agents/`를 재귀적으로 스캔하므로 `agents/review/` 또는 `agents/research/`와 같은 하위 폴더로 정의를 구성할 수 있습니다. 하위 디렉토리 경로는 subagent가 식별되거나 호출되는 방식에 영향을 주지 않습니다. 왜냐하면 ID는 `name` frontmatter 필드에서만 나오기 때문입니다.

185 185

186전체 트리에서 `name` 값을 고유하게 유지합니다: 한 범위 내의 두 파일이 같은 이름을 선언하면 Claude Code는 하나만 로드합니다. {/* min-version: 2.1.196 */}v2.1.196부터 `/doctor`를 실행하면 동일한 범위의 중복 에이전트 이름을 보고하고 활성 정의를 표시합니다.186전체 트리에서 `name` 값을 고유하게 유지합니다: 동일한 `.claude/agents/` 디렉토리 내의 두 파일이 (하위 폴더 포함) 동일한 이름을 선언하면 Claude Code는 하나만 로드하며, 파일시스템 읽기 순서가 아닌 문서화된 우선순위에 따라 선택됩니다. 중첩된 프로젝트 디렉토리 간에는 작업 디렉토리에 가장 가까운 정의가 우선합니다 (위에서 설명한 대로). {/* min-version: 2.1.205 */}[`/doctor`](/ko/commands#all-commands) 설정 점검은 동일한 디렉토리에서 이름을 공유하는 파일을 보고하고 하나를 제외한 모두의 이름을 바꾸거나 제거할 것을 제안합니다. v2.1.205 이전에는 `/doctor`가 진단 화면을 열어 중복을 나열하고 활성 정의를 표시했습니다.

187 187

188플러그인 `agents/` 디렉토리도 재귀적으로 스캔됩니다. 프로젝트 및 사용자 범위와 달리 플러그인의 `agents/` 디렉토리 내의 하위 폴더는 [범위가 지정된 식별자](#invoke-subagents-explicitly)의 일부가 됩니다: 플러그인 `my-plugin`의 `agents/review/security.md`에 있는 파일은 `my-plugin:review:security`로 등록됩니다.188플러그인 `agents/` 디렉토리도 재귀적으로 스캔됩니다. 프로젝트 및 사용자 범위와 달리 플러그인의 `agents/` 디렉토리 내의 하위 폴더는 [범위가 지정된 식별자](#invoke-subagents-explicitly)의 일부가 됩니다: 플러그인 `my-plugin`의 `agents/review/security.md`에 있는 파일은 `my-plugin:review:security`로 등록됩니다.

189 189

268 268

269Frontmatter는 subagent의 메타데이터와 구성을 정의합니다. 본문은 subagent의 동작을 안내하는 시스템 프롬프트가 됩니다. Subagent는 이 시스템 프롬프트만 받습니다(작업 디렉토리와 같은 기본 환경 세부 정보 포함). 전체 Claude Code 시스템 프롬프트는 받지 않습니다.269Frontmatter는 subagent의 메타데이터와 구성을 정의합니다. 본문은 subagent의 동작을 안내하는 시스템 프롬프트가 됩니다. Subagent는 이 시스템 프롬프트만 받습니다(작업 디렉토리와 같은 기본 환경 세부 정보 포함). 전체 Claude Code 시스템 프롬프트는 받지 않습니다.

270 270

271{/* min-version: 2.1.205 */}}[비대화형 모드](/ko/headless)에서 [`--append-subagent-system-prompt`](/ko/cli-reference#cli-flags) 플래그는 중첩된 subagent를 포함하여 모든 subagent의 시스템 프롬프트 끝에 제공하는 텍스트를 추가합니다. Claude Code v2.1.205 이상이 필요합니다.

272

271Subagent는 주 대화의 현재 작업 디렉토리에서 시작합니다. Subagent 내에서 `cd` 명령은 Bash 또는 PowerShell 도구 호출 간에 유지되지 않으며 주 대화의 작업 디렉토리에 영향을 주지 않습니다. Subagent에 저장소의 격리된 복사본을 제공하려면 [`isolation: worktree`](#supported-frontmatter-fields)를 설정합니다.273Subagent는 주 대화의 현재 작업 디렉토리에서 시작합니다. Subagent 내에서 `cd` 명령은 Bash 또는 PowerShell 도구 호출 간에 유지되지 않으며 주 대화의 작업 디렉토리에 영향을 주지 않습니다. Subagent에 저장소의 격리된 복사본을 제공하려면 [`isolation: worktree`](#supported-frontmatter-fields)를 설정합니다.

272 274

275{/* min-version: 2.1.203 */}}`isolation: worktree`를 사용하는 subagent는 해당 worktree 내에서 Bash 및 PowerShell 명령을 실행합니다. 예를 들어 subagent가 실행 중일 때 worktree 디렉토리가 제거되었기 때문에 작업 디렉토리가 주 체크아웃으로 해결되는 명령은 오류로 실패합니다. v2.1.203 이전에는 이러한 명령이 주 체크아웃에서 실행될 수 있었습니다.

276

273<h4 id="supported-frontmatter-fields">277<h4 id="supported-frontmatter-fields">

274 지원되는 frontmatter 필드278 지원되는 frontmatter 필드

275</h4>279</h4>

277다음 필드를 YAML frontmatter에서 사용할 수 있습니다. `name`과 `description`만 필수입니다.281다음 필드를 YAML frontmatter에서 사용할 수 있습니다. `name`과 `description`만 필수입니다.

278 282

279| 필드 | 필수 | 설명 |283| 필드 | 필수 | 설명 |

280| :---------------- | :-- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |284| :---------------- | :-- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

281| `name` | 예 | 소문자 및 하이픈을 사용한 고유 식별자. [Hooks](/ko/hooks#subagentstart)는 이 값을 `agent_type`으로 받습니다. 파일 이름이 일치할 필요는 없습니다 |285| `name` | 예 | 소문자 및 하이픈을 사용한 고유 식별자. [Hooks](/ko/hooks#subagentstart)는 이 값을 `agent_type`으로 받습니다. 파일 이름이 일치할 필요는 없습니다 |

282| `description` | 예 | Claude가 이 subagent에 위임해야 할 때 |286| `description` | 예 | Claude가 이 subagent에 위임해야 할 때 |

283| `tools` | 아니오 | [도구](#available-tools) subagent가 사용할 수 있습니다. 생략하면 모든 도구 상속. Skills를 컨텍스트에 미리 로드하려면 여기에 `Skill`을 나열하는 대신 `skills` 필드를 사용합니다 |287| `tools` | 아니오 | [도구](#available-tools) subagent가 사용할 수 있습니다. 생략하면 모든 도구 상속. Skills를 컨텍스트에 미리 로드하려면 여기에 `Skill`을 나열하는 대신 `skills` 필드를 사용합니다 |

284| `disallowedTools` | 아니오 | 거부할 도구, 상속되거나 지정된 목록에서 제거됨 |288| `disallowedTools` | 아니오 | 거부할 도구, 상속되거나 지정된 목록에서 제거됨 |

285| `model` | 아니오 | 사용할 [모델](#choose-a-model): `sonnet`, `opus`, `haiku`, `fable`, 전체 모델 ID (예: `claude-opus-4-8`), 또는 `inherit`. 기본값: `inherit` |289| `model` | 아니오 | 사용할 [모델](#choose-a-model): `sonnet`, `opus`, `haiku`, `fable`, 전체 모델 ID (예: `claude-opus-4-8`), 또는 `inherit`. 기본값: `inherit` |

286| `permissionMode` | 아니오 | [권한 모드](#permission-modes): `default`, `acceptEdits`, `auto`, `dontAsk`, `bypassPermissions`, 또는 `plan`. [플러그인 subagent](#choose-the-subagent-scope)에서는 무시됨 |290| `permissionMode` | 아니오 | [권한 모드](#permission-modes): `default`, `acceptEdits`, `auto`, `dontAsk`, `bypassPermissions`, `plan`, 또는 {/* min-version: 2.1.200 */}}`manual` (기본값의 별칭). `manual` 별칭은 Claude Code v2.1.200 이상이 필요합니다. [플러그인 subagent](#choose-the-subagent-scope)에서는 무시됨 |

287| `maxTurns` | 아니오 | Subagent가 중지되기 전의 최대 에이전트 턴 수 |291| `maxTurns` | 아니오 | Subagent가 중지되기 전의 최대 에이전트 턴 수 |

288| `skills` | 아니오 | 시작 시 subagent의 컨텍스트에 로드할 [Skills](/ko/skills). 전체 skill 콘텐츠가 주입되며, 호출 가능하게 만들어지는 것이 아닙니다. Subagent는 여전히 Skill 도구를 통해 나열되지 않은 프로젝트, 사용자, 플러그인 skills를 호출할 수 있습니다 |292| `skills` | 아니오 | 시작 시 subagent의 컨텍스트에 로드할 [Skills](/ko/skills). 전체 skill 콘텐츠가 주입되며, 호출 가능하게 만들어지는 것이 아닙니다. Subagent는 여전히 Skill 도구를 통해 나열되지 않은 프로젝트, 사용자, 플러그인 skills를 호출할 수 있습니다 |

289| `mcpServers` | 아니오 | 이 subagent에서 사용 가능한 [MCP servers](/ko/mcp). 각 항목은 이미 구성된 서버를 참조하는 서버 이름 (예: `"slack"`) 또는 서버 이름을 키로 하고 전체 [MCP server config](/ko/mcp#installing-mcp-servers)를 값으로 하는 인라인 정의입니다. [플러그인 subagent](#choose-the-subagent-scope)에서는 무시됨 |293| `mcpServers` | 아니오 | 이 subagent에서 사용 가능한 [MCP servers](/ko/mcp). 각 항목은 이미 구성된 서버를 참조하는 서버 이름 (예: `"slack"`) 또는 서버 이름을 키로 하고 전체 [MCP server config](/ko/mcp#installing-mcp-servers)를 값으로 하는 인라인 정의입니다. [플러그인 subagent](#choose-the-subagent-scope)에서는 무시됨 |

290| `hooks` | 아니오 | 이 subagent로 범위가 지정된 [라이프사이클 hooks](#define-hooks-for-subagents). [플러그인 subagent](#choose-the-subagent-scope)에서는 무시됨 |294| `hooks` | 아니오 | 이 subagent로 범위가 지정된 [라이프사이클 hooks](#define-hooks-for-subagents). [플러그인 subagent](#choose-the-subagent-scope)에서는 무시됨 |

291| `memory` | 아니오 | [지속적 메모리 범위](#enable-persistent-memory): `user`, `project`, 또는 `local`. 교차 세션 학습 활성화 |295| `memory` | 아니오 | [지속적 메모리 범위](#enable-persistent-memory): `user`, `project`, 또는 `local`. 교차 세션 학습 활성화 |

292| `background` | 아니오 | 이 subagent를 항상 [background task](#run-subagents-in-foreground-or-background)로 실행하려면 `true`로 설정합니다. 설정하지 않으면 Claude가 선택하고, {/* min-version: 2.1.198 */}v2.1.198부터 기본적으로 subagent를 백그라운드에서 실행합니다 |296| `background` | 아니오 | 이 subagent를 항상 [background task](#run-subagents-in-foreground-or-background)로 실행하려면 `true`로 설정합니다. 설정하지 않으면 Claude가 선택하고, {/* min-version: 2.1.198 */}}v2.1.198부터 기본적으로 subagent를 백그라운드에서 실행합니다 |

293| `effort` | 아니오 | 이 subagent가 활성화될 때의 노력 수준. 세션 노력 수준을 재정의합니다. 기본값: 세션에서 상속. 옵션: `low`, `medium`, `high`, `xhigh`, `max` (사용 가능한 수준은 모델에 따라 다름) |297| `effort` | 아니오 | 이 subagent가 활성화될 때의 노력 수준. 세션 노력 수준을 재정의합니다. 기본값: 세션에서 상속. 옵션: `low`, `medium`, `high`, `xhigh`, `max` (사용 가능한 수준은 모델에 따라 다름) |

294| `isolation` | 아니오 | Subagent를 임시 [git worktree](/ko/worktrees)에서 실행하려면 `worktree`로 설정하여 저장소의 격리된 복사본을 제공합니다. 기본적으로 [기본 분기](/ko/worktrees#choose-the-base-branch)에서 분기되며, 부모 세션의 `HEAD`가 아닙니다. Subagent가 변경 사항을 만들지 않으면 worktree가 자동으로 정리됩니다 |298| `isolation` | 아니오 | Subagent를 임시 [git worktree](/ko/worktrees)에서 실행하려면 `worktree`로 설정하여 저장소의 격리된 복사본을 제공합니다. 기본적으로 [기본 분기](/ko/worktrees#choose-the-base-branch)에서 분기되며, 부모 세션의 `HEAD`가 아닙니다. Subagent가 변경 사항을 만들지 않으면 worktree가 자동으로 정리됩니다 |

295| `color` | 아니오 | 작업 목록 및 트랜스크립트에서 subagent의 표시 색상입니다. `red`, `blue`, `green`, `yellow`, `purple`, `orange`, `pink`, 또는 `cyan`을 허용합니다 |299| `color` | 아니오 | 작업 목록 및 트랜스크립트에서 subagent의 표시 색상입니다. `red`, `blue`, `green`, `yellow`, `purple`, `orange`, `pink`, 또는 `cyan`을 허용합니다 |

3133. Subagent 정의의 `model` frontmatter3173. Subagent 정의의 `model` frontmatter

3144. 주 대화의 모델3184. 주 대화의 모델

315 319

316{/* min-version: 2.1.196 */}v2.1.196부터 `CLAUDE_CODE_SUBAGENT_MODEL`을 `inherit`로 설정하는 것은 설정하지 않은 것과 동일합니다: 해결은 호출별 `model` 매개변수로 계속되고 frontmatter로 계속됩니다. 이전 버전에서는 `inherit`이 subagent를 주 대화의 모델로 강제하고 이 두 소스를 모두 무시했습니다.320{/* min-version: 2.1.196 */}}v2.1.196부터 `CLAUDE_CODE_SUBAGENT_MODEL`을 `inherit`로 설정하는 것은 설정하지 않은 것과 동일합니다: 해결은 호출별 `model` 매개변수로 계속되고 frontmatter로 계속됩니다. 이전 버전에서는 `inherit`이 subagent를 주 대화의 모델로 강제하고 이 두 소스를 모두 무시했습니다.

317 321

318Claude Code는 환경 변수, 호출별 매개변수, frontmatter 값을 조직의 [`availableModels`](/ko/model-config#restrict-model-selection) 허용 목록에 대해 확인합니다. 제외된 모델로 해결되는 값은 사용되지 않으며 subagent는 상속된 모델에서 대신 실행됩니다.322Claude Code는 환경 변수, 호출별 매개변수, frontmatter 값을 조직의 [`availableModels`](/ko/model-config#restrict-model-selection) 허용 목록에 대해 확인합니다. 제외된 모델로 해결되는 값은 사용되지 않으며 subagent는 상속된 모델에서 대신 실행됩니다.

319 323

320{/* min-version: 2.1.198 */}v2.1.198부터 subagent는 주 대화의 [extended thinking](/ko/model-config#extended-thinking) 구성도 상속합니다: 세션에서 thinking이 켜져 있으면 subagent에서도 켜져 있고, 꺼져 있으면 꺼진 상태로 유지됩니다. subagent별 thinking 설정은 없습니다. v2.1.198 이전에는 주 대화의 설정에 관계없이 subagent가 extended thinking을 비활성화한 상태로 실행되었습니다.324{/* min-version: 2.1.198 */}}v2.1.198부터 subagent는 주 대화의 [extended thinking](/ko/model-config#extended-thinking) 구성도 상속합니다: 세션에서 thinking이 켜져 있으면 subagent에서도 켜져 있고, 꺼져 있으면 꺼진 상태로 유지됩니다. subagent별 thinking 설정은 없습니다. v2.1.198 이전에는 주 대화의 설정에 관계없이 subagent가 extended thinking을 비활성화한 상태로 실행되었습니다.

321 325

322<h3 id="control-subagent-capabilities">326<h3 id="control-subagent-capabilities">

323 Subagent 기능 제어327 Subagent 기능 제어

435 439

436MCP 서버를 주 대화에서 완전히 분리하고 도구 설명이 컨텍스트를 소비하지 않도록 하려면 `.mcp.json`이 아닌 여기에 인라인으로 정의합니다. Subagent는 도구를 얻고 부모 대화는 그렇지 않습니다.440MCP 서버를 주 대화에서 완전히 분리하고 도구 설명이 컨텍스트를 소비하지 않도록 하려면 `.mcp.json`이 아닌 여기에 인라인으로 정의합니다. Subagent는 도구를 얻고 부모 대화는 그렇지 않습니다.

437 441

442{/* min-version: 2.1.153 */}}

438v2.1.153부터 주 세션에 적용되는 MCP 제한은 subagent frontmatter에서 선언된 서버도 포함합니다:443v2.1.153부터 주 세션에 적용되는 MCP 제한은 subagent frontmatter에서 선언된 서버도 포함합니다:

439 444

440* [`--strict-mcp-config`](/ko/cli-reference) 및 [`--bare`](/ko/cli-reference)445* [`--strict-mcp-config`](/ko/cli-reference) 및 [`--bare`](/ko/cli-reference)

689}694}

690```695```

691 696

697{/* min-version: 2.1.195 */}}

692하이픈이 있는 matcher (예: `db-agent`)는 Claude Code v2.1.195 이상에서 정확하게 일치합니다. 이전 버전에서는 고정되지 않은 정규식으로 평가되며 `prod-db-agent`와 같이 포함하는 모든 에이전트 유형에 대해서도 발생합니다. 이러한 버전에서는 `^db-agent$`로 고정합니다.698하이픈이 있는 matcher (예: `db-agent`)는 Claude Code v2.1.195 이상에서 정확하게 일치합니다. 이전 버전에서는 고정되지 않은 정규식으로 평가되며 `prod-db-agent`와 같이 포함하는 모든 에이전트 유형에 대해서도 발생합니다. 이러한 버전에서는 `^db-agent$`로 고정합니다.

693 699

694전체 hook 구성 형식은 [Hooks](/ko/hooks)를 참조하세요.700전체 hook 구성 형식은 [Hooks](/ko/hooks)를 참조하세요.

792 798

793{/* min-version: 2.1.199 */}v2.1.199부터 API 오류 (예: 사용 제한 또는 반복된 서버 오류)로 인해 실행이 종료된 subagent는 오류 텍스트를 subagent의 결과인 것처럼 반환하는 대신 해당 실패를 Claude에 보고합니다. Claude가 받는 내용은 subagent가 실행된 위치에 따라 다릅니다:799{/* min-version: 2.1.199 */}v2.1.199부터 API 오류 (예: 사용 제한 또는 반복된 서버 오류)로 인해 실행이 종료된 subagent는 오류 텍스트를 subagent의 결과인 것처럼 반환하는 대신 해당 실패를 Claude에 보고합니다. Claude가 받는 내용은 subagent가 실행된 위치에 따라 다릅니다:

794 800

795* **Foreground**: 속도 제한, 과부하 또는 서버 오류가 이미 출력을 생성한 subagent를 중단하면 Agent 도구는 해당 부분 출력을 subagent가 중단되었으며 작업을 완료하지 못했다는 메모와 함께 반환합니다. 그렇지 않으면 도구 호출이 [`Agent terminated early due to an API error`](/ko/errors#agent-terminated-early-due-to-an-api-error)로 실패하고 오류 세부 정보가 뒤따릅니다.801* **Foreground**: 속도 제한, 과부하 또는 서버 오류가 이미 출력을 생성한 subagent를 중단하면 Agent 도구는 해당 부분 출력을 subagent가 중단되었으며 작업을 완료하지 못했다는 메모와 함께 반환합니다. {/* min-version: 2.1.200 */}아무것도 생성하지 않았거나 유일한 출력이 도구 호출이었던 subagent는 [`Agent terminated early due to an API error`](/ko/errors#agent-terminated-early-due-to-an-api-error)로 실패하고 오류 세부 정보가 뒤따릅니다. v2.1.199에서는 도구 호출만 있는 형태를 중단한 속도 제한, 과부하 또는 서버 오류가 중단 메모만 포함하는 빈 부분 결과를 반환했습니다.

796* **Background**: subagent는 실패로 표시되며 Claude가 종료될 때 받는 메시지는 API 오류의 이름을 지정하고 subagent의 마지막 출력을 포함하므로 부분 작업이 손실되지 않습니다.802* **Background**: subagent는 실패로 표시되며 Claude가 종료될 때 받는 메시지는 API 오류의 이름을 지정하고 subagent의 마지막 출력을 포함하므로 부분 작업이 손실되지 않습니다.

797 803

798기본 API 오류가 해결되면 Claude에 작업을 다시 시도하거나 [subagent를 재개](#resume-subagents)하도록 요청합니다.804기본 API 오류가 해결되면 Claude에 작업을 다시 시도하거나 [subagent를 재개](#resume-subagents)하도록 요청합니다.

924 930

925중단된 subagent가 `SendMessage`를 받으면 새로운 `Agent` 호출 없이 background에서 자동으로 재개됩니다.931중단된 subagent가 `SendMessage`를 받으면 새로운 `Agent` 호출 없이 background에서 자동으로 재개됩니다.

926 932

933재개는 동일한 ID 아래에서 에이전트의 새로운 실행을 시작하므로 이미 실패했거나 완료된 subagent는 작업 목록 및 Agent SDK의 작업 이벤트에서 다시 실행 중으로 표시됩니다. v2.1.205 이전에는 재개된 실행이 작동하는 동안 이전의 실패했거나 완료된 상태를 계속 표시했습니다.

934

927{/* min-version: 2.1.199 */}v2.1.199부터 `SendMessage`는 이름이 여전히 대화에서 이전에 도달한 동일한 에이전트를 참조하는지 확인합니다. 더 새로운 에이전트가 이름을 가져간 경우 (예: 이름을 재사용한 다시 생성된 background 에이전트), Claude Code는 잘못된 에이전트에 전달하는 대신 전송을 거부하며 오류는 이름이 현재 도달하는 에이전트를 보고하므로 Claude가 재대상화할 수 있습니다. 여전히 실행 중인 이전 에이전트에 도달하려면 Claude는 생성 결과의 에이전트 ID로 주소를 지정합니다. 확인은 현재 대화로 범위가 지정되며 `/clear`에서 재설정됩니다.935{/* min-version: 2.1.199 */}v2.1.199부터 `SendMessage`는 이름이 여전히 대화에서 이전에 도달한 동일한 에이전트를 참조하는지 확인합니다. 더 새로운 에이전트가 이름을 가져간 경우 (예: 이름을 재사용한 다시 생성된 background 에이전트), Claude Code는 잘못된 에이전트에 전달하는 대신 전송을 거부하며 오류는 이름이 현재 도달하는 에이전트를 보고하므로 Claude가 재대상화할 수 있습니다. 여전히 실행 중인 이전 에이전트에 도달하려면 Claude는 생성 결과의 에이전트 ID로 주소를 지정합니다. 확인은 현재 대화로 범위가 지정되며 `/clear`에서 재설정됩니다.

928 936

929{/* min-version: 2.1.198 */}v2.1.198부터 subagent는 이를 시작한 에이전트의 메시지를 일반적인 작업 지시로 취급하며, 중간 작업 과정 수정을 포함하고 자신의 권한 설정 내에서 작동합니다. 메시지를 보낸 사람과 관계없이 두 가지 제한이 여전히 유지됩니다: 어떤 에이전트의 메시지도 보류 중인 권한 프롬프트에 대한 승인으로 계산되지 않으며, 어떤 에이전트 메시지도 subagent의 권한 설정, `CLAUDE.md` 또는 구성을 변경할 수 없습니다. 권한 시스템 또는 자신의 메시지만 승인을 부여할 수 있습니다.937{/* min-version: 2.1.198 */}v2.1.198부터 subagent는 이를 시작한 에이전트의 메시지를 일반적인 작업 지시로 취급하며, 중간 작업 과정 수정을 포함하고 자신의 권한 설정 내에서 작동합니다. 메시지를 보낸 사람과 관계없이 두 가지 제한이 여전히 유지됩니다: 어떤 에이전트의 메시지도 보류 중인 권한 프롬프트에 대한 승인으로 계산되지 않으며, 어떤 에이전트 메시지도 subagent의 권한 설정, `CLAUDE.md` 또는 구성을 변경할 수 없습니다. 권한 시스템 또는 자신의 메시지만 승인을 부여할 수 있습니다.

third-party-integrations.md +14 −14

Details

102 <th>Anthropic Console</th>102 <th>Anthropic Console</th>

103 <th>Amazon Bedrock</th>103 <th>Amazon Bedrock</th>

104 <th>Claude Platform on AWS</th>104 <th>Claude Platform on AWS</th>

105 <th>Google Vertex AI</th>105 <th>Google Cloud의 Agent Platform, 이전의 Vertex AI</th>

106 <th>Microsoft Foundry</th>106 <th>Microsoft Foundry</th>

107 </tr>107 </tr>

108 </thead>108 </thead>

196 196

197* [Claude for Teams 또는 Enterprise](/ko/authentication#claude-for-teams-or-enterprise)197* [Claude for Teams 또는 Enterprise](/ko/authentication#claude-for-teams-or-enterprise)

198* [Anthropic Console](/ko/authentication#claude-console-authentication)198* [Anthropic Console](/ko/authentication#claude-console-authentication)

199* [Claude 앱 게이트웨이](/ko/claude-apps-gateway), Amazon Bedrock, Google Vertex AI, Microsoft Foundry 또는 Anthropic API 앞에 IdP 로그인을 추가하는 자체 호스팅 게이트웨이199* [Claude 앱 게이트웨이](/ko/claude-apps-gateway), Amazon Bedrock, Claude Platform on AWS, Google Cloud의 Agent Platform, Microsoft Foundry 또는 Anthropic API 앞에 IdP 로그인을 추가하는 자체 호스팅 게이트웨이

200* [Amazon Bedrock](/ko/amazon-bedrock)200* [Amazon Bedrock](/ko/amazon-bedrock)

201* [Claude Platform on AWS](/ko/claude-platform-on-aws)201* [Claude Platform on AWS](/ko/claude-platform-on-aws)

202* [Google Vertex AI](/ko/google-vertex-ai)202* [Google Cloud의 Agent Platform](/ko/google-vertex-ai)

203* [Microsoft Foundry](/ko/microsoft-foundry)203* [Microsoft Foundry](/ko/microsoft-foundry)

204 204

205<h2 id="configure-proxies-and-gateways">205<h2 id="configure-proxies-and-gateways">

219 219

220<Tabs>220<Tabs>

221 <Tab title="회사 프록시">221 <Tab title="회사 프록시">

222 다음 [환경 변수](/ko/env-vars)를 설정하여 Bedrock 트래픽을 회사 프록시를 통해 라우팅합니다:222 다음 [환경 변수](/ko/env-vars)를 설정하여 Amazon Bedrock 트래픽을 회사 프록시를 통해 라우팅합니다:

223 223

224 ```bash theme={null}224 ```bash theme={null}

225 # Bedrock 활성화225 # Bedrock 활성화

232 </Tab>232 </Tab>

233 233

234 <Tab title="LLM 게이트웨이">234 <Tab title="LLM 게이트웨이">

235 다음 [환경 변수](/ko/env-vars)를 설정하여 Bedrock 트래픽을 LLM 게이트웨이를 통해 라우팅합니다:235 다음 [환경 변수](/ko/env-vars)를 설정하여 Amazon Bedrock 트래픽을 LLM 게이트웨이를 통해 라우팅합니다:

236 236

237 ```bash theme={null}237 ```bash theme={null}

238 # Bedrock 활성화238 # Bedrock 활성화

251 251

252<Tabs>252<Tabs>

253 <Tab title="회사 프록시">253 <Tab title="회사 프록시">

254 다음 [환경 변수](/ko/env-vars)를 설정하여 Foundry 트래픽을 회사 프록시를 통해 라우팅합니다:254 다음 [환경 변수](/ko/env-vars)를 설정하여 Microsoft Foundry 트래픽을 회사 프록시를 통해 라우팅합니다:

255 255

256 ```bash theme={null}256 ```bash theme={null}

257 # Microsoft Foundry 활성화257 # Microsoft Foundry 활성화

265 </Tab>265 </Tab>

266 266

267 <Tab title="LLM 게이트웨이">267 <Tab title="LLM 게이트웨이">

268 다음 [환경 변수](/ko/env-vars)를 설정하여 Foundry 트래픽을 LLM 게이트웨이를 통해 라우팅합니다:268 다음 [환경 변수](/ko/env-vars)를 설정하여 Microsoft Foundry 트래픽을 LLM 게이트웨이를 통해 라우팅합니다:

269 269

270 ```bash theme={null}270 ```bash theme={null}

271 # Microsoft Foundry 활성화271 # Microsoft Foundry 활성화

278 </Tab>278 </Tab>

279</Tabs>279</Tabs>

280 280

281<h3 id="google-vertex-ai">281<h3 id="google-cloud’s-agent-platform">

282 Google Vertex AI282 Google Cloud's Agent Platform

283</h3>283</h3>

284 284

285<Tabs>285<Tabs>

286 <Tab title="회사 프록시">286 <Tab title="회사 프록시">

287 다음 [환경 변수](/ko/env-vars)를 설정하여 Vertex AI 트래픽을 회사 프록시를 통해 라우팅합니다:287 다음 [환경 변수](/ko/env-vars)를 설정하여 Google Cloud's Agent Platform 트래픽을 회사 프록시를 통해 라우팅합니다:

288 288

289 ```bash theme={null}289 ```bash theme={null}

290 # Vertex 활성화290 # Agent Platform 활성화

291 export CLAUDE_CODE_USE_VERTEX=1291 export CLAUDE_CODE_USE_VERTEX=1

292 export CLOUD_ML_REGION=us-east5292 export CLOUD_ML_REGION=us-east5

293 export ANTHROPIC_VERTEX_PROJECT_ID=your-project-id293 export ANTHROPIC_VERTEX_PROJECT_ID=your-project-id

298 </Tab>298 </Tab>

299 299

300 <Tab title="LLM 게이트웨이">300 <Tab title="LLM 게이트웨이">

301 다음 [환경 변수](/ko/env-vars)를 설정하여 Vertex AI 트래픽을 LLM 게이트웨이를 통해 라우팅합니다:301 다음 [환경 변수](/ko/env-vars)를 설정하여 Google Cloud's Agent Platform 트래픽을 LLM 게이트웨이를 통해 라우팅합니다:

302 302

303 ```bash theme={null}303 ```bash theme={null}

304 # Vertex 활성화304 # Agent Platform 활성화

305 export CLAUDE_CODE_USE_VERTEX=1305 export CLAUDE_CODE_USE_VERTEX=1

306 306

307 # LLM 게이트웨이 구성307 # LLM 게이트웨이 구성

348 클라우드 제공자를 위한 모델 버전 고정348 클라우드 제공자를 위한 모델 버전 고정

349</h3>349</h3>

350 350

351[Bedrock](/ko/amazon-bedrock), [Vertex AI](/ko/google-vertex-ai), [Foundry](/ko/microsoft-foundry) 또는 [Claude Platform on AWS](/ko/claude-platform-on-aws)를 통해 배포하는 경우 `ANTHROPIC_DEFAULT_FABLE_MODEL`, `ANTHROPIC_DEFAULT_OPUS_MODEL`, `ANTHROPIC_DEFAULT_SONNET_MODEL` 및 `ANTHROPIC_DEFAULT_HAIKU_MODEL`을 사용하여 특정 모델 버전을 고정합니다. 고정하지 않으면 모델 별칭이 Claude Code의 해당 제공자에 대한 기본 제공 기본값으로 확인되며, 이는 최신 릴리스보다 뒤떨어질 수 있고 계정에서 아직 활성화되지 않았을 수 있습니다. 고정하면 사용자가 새 모델로 이동하는 시기를 제어할 수 있습니다. 각 제공자가 기본값을 사용할 수 없을 때 수행하는 작업에 대해서는 [모델 구성](/ko/model-config#pin-models-for-third-party-deployments)을 참조하십시오.351[Amazon Bedrock](/ko/amazon-bedrock), [Google Cloud의 Agent Platform](/ko/google-vertex-ai), [Microsoft Foundry](/ko/microsoft-foundry) 또는 [Claude Platform on AWS](/ko/claude-platform-on-aws)를 통해 배포하는 경우 `ANTHROPIC_DEFAULT_FABLE_MODEL`, `ANTHROPIC_DEFAULT_OPUS_MODEL`, `ANTHROPIC_DEFAULT_SONNET_MODEL` 및 `ANTHROPIC_DEFAULT_HAIKU_MODEL`을 사용하여 특정 모델 버전을 고정합니다. 고정하지 않으면 모델 별칭이 Claude Code의 해당 제공자에 대한 기본 제공 기본값으로 확인되며, 이는 최신 릴리스보다 뒤떨어질 수 있고 계정에서 아직 활성화되지 않았을 수 있습니다. 고정하면 사용자가 새 모델로 이동하는 시기를 제어할 수 있습니다. 각 제공자가 기본값을 사용할 수 없을 때 수행하는 작업에 대해서는 [모델 구성](/ko/model-config#pin-models-for-third-party-deployments)을 참조하십시오.

352 352

353<h3 id="configure-security-policies">353<h3 id="configure-security-policies">

354 보안 정책 구성354 보안 정책 구성

tools-reference.md +13 −13

Details

11사용자 정의 도구를 추가하려면 [MCP 서버](/ko/mcp)를 연결합니다. Claude를 재사용 가능한 프롬프트 기반 워크플로우로 확장하려면 [skill](/ko/skills)을 작성합니다. 이는 새로운 도구 항목을 추가하는 대신 기존 `Skill` 도구를 통해 실행됩니다.11사용자 정의 도구를 추가하려면 [MCP 서버](/ko/mcp)를 연결합니다. Claude를 재사용 가능한 프롬프트 기반 워크플로우로 확장하려면 [skill](/ko/skills)을 작성합니다. 이는 새로운 도구 항목을 추가하는 대신 기존 `Skill` 도구를 통해 실행됩니다.

12 12

13| 도구 | 설명 | 필요한 권한 |13| 도구 | 설명 | 필요한 권한 |

14| :--------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :----- |14| :--------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :----- |

15| `Agent` | 작업을 처리하기 위해 자체 context window를 가진 [subagent](/ko/sub-agents)를 생성합니다. [Agent 도구 동작](#agent-tool-behavior) 참조 | 아니오 |15| `Agent` | 작업을 처리하기 위해 자체 context window를 가진 [subagent](/ko/sub-agents)를 생성합니다. [Agent 도구 동작](#agent-tool-behavior) 참조 | 아니오 |

16| `Artifact` | HTML 또는 Markdown 파일을 [artifact](/ko/artifacts)로 게시합니다: claude.ai의 비공개 대화형 페이지입니다. Team 및 Enterprise 플랜에서는 조직 내에서 공유할 수 있습니다. {/* plan-availability: feature=artifacts plans=pro,max,team,enterprise providers=anthropic */}Pro, Max, Team 또는 Enterprise 플랜이 필요하며 `/login` 인증이 필요합니다. [가용성](/ko/artifacts#availability) 참조 | 예 |16| `Artifact` | HTML 또는 Markdown 파일을 [artifact](/ko/artifacts)로 게시합니다: claude.ai의 비공개 대화형 페이지입니다. Team 및 Enterprise 플랜에서는 조직 내에서 공유할 수 있습니다. {/* plan-availability: feature=artifacts plans=pro,max,team,enterprise providers=anthropic */}Pro, Max, Team 또는 Enterprise 플랜이 필요하며 `/login` 인증이 필요합니다. [가용성](/ko/artifacts#availability) 참조 | 예 |

17| `AskUserQuestion` | 요구사항을 수집하거나 모호함을 명확히 하기 위해 객관식 질문을 합니다. {/* min-version: 2.1.198 */}v2.1.198부터 60초 이내에 응답하지 않으면 대화 상자가 자동으로 닫힙니다: 이미 선택한 옵션을 제출하고 Claude에게 키보드에서 멀어질 수 있음을 알리므로 Claude는 자체 판단으로 진행하고 나중에 다시 질문할 수 있습니다. 마지막 20초 동안 카운트다운이 나타납니다. 모든 키 입력은 대화 상자를 열린 상태로 유지하며, 포커스를 보고하는 터미널의 포커스된 창도 마찬가지입니다. [`CLAUDE_AFK_TIMEOUT_MS`](/ko/env-vars#variables) 환경 변수를 설정하여 Claude Code가 대기하는 시간을 변경하거나 24시간인 `86400000`과 같은 큰 값으로 설정하여 자리를 비웠을 때 질문을 열린 상태로 유지할 수 있습니다. 이 타임아웃은 `AskUserQuestion`의 객관식 질문에만 적용되며, 플랜 승인을 포함한 권한 프롬프트는 유휴 상태에서 자동으로 해결되지 않습니다 | 아니오 |17| `AskUserQuestion` | 요구사항을 수집하거나 모호함을 명확히 하기 위해 객관식 질문을 합니다. {/* min-version: 2.1.200 */}질문은 사용자가 답변할 때까지 열려 있으며 기본적으로 유휴 타임아웃이 없습니다. 유휴 대화 상자가 자동으로 계속되도록 하려면 사용자 `settings.json`에서 또는 `/config`의 **Question auto-continue timeout** 행에서 [`askUserQuestionTimeout`](/ko/settings#available-settings) 설정을 `60s`, `5m` 또는 `10m`으로 설정합니다. 선택한 유휴 시간이 입력 없이 경과하면 대화 상자가 자동으로 닫힙니다: 이미 선택한 옵션을 제출하고 Claude에게 키보드에서 멀어질 수 있음을 알리므로 Claude는 자체 판단으로 진행하고 나중에 다시 질문할 수 있습니다. 마지막 20초 동안 카운트다운이 나타납니다. 모든 키 입력은 타이머를 다시 시작하며, 포커스를 보고하는 터미널의 포커스된 창도 마찬가지입니다. 타임아웃은 `AskUserQuestion`의 객관식 질문에만 적용되며, 플랜 승인을 포함한 권한 프롬프트는 유휴 상태에서 자동으로 해결되지 않습니다. v2.1.198 및 v2.1.199에서는 대화 상자가 기본적으로 60초의 유휴 후 자동으로 계속되었으며, [`CLAUDE_AFK_TIMEOUT_MS`](/ko/env-vars#variables)가 이를 변경하는 유일한 방법이었습니다 | 아니오 |

18| `Bash` | 환경에서 shell 명령을 실행합니다. [Bash 도구 동작](#bash-tool-behavior) 참조 | 예 |18| `Bash` | 환경에서 shell 명령을 실행합니다. [Bash 도구 동작](#bash-tool-behavior) 참조 | 예 |

19| `CronCreate` | 현재 세션 내에서 반복 또는 일회성 프롬프트를 예약합니다. 작업은 세션 범위이며 `--resume` 또는 `--continue`에서 만료되지 않으면 복원됩니다. [예약된 작업](/ko/scheduled-tasks) 참조 | 아니오 |19| `CronCreate` | 현재 세션 내에서 반복 또는 일회성 프롬프트를 예약합니다. 작업은 세션 범위이며 `--resume` 또는 `--continue`에서 만료되지 않으면 복원됩니다. [예약된 작업](/ko/scheduled-tasks) 참조 | 아니오 |

20| `CronDelete` | ID로 예약된 작업을 취소합니다 | 아니오 |20| `CronDelete` | ID로 예약된 작업을 취소합니다 | 아니오 |

21| `CronList` | 세션의 모든 예약된 작업을 나열합니다 | 아니오 |21| `CronList` | 세션의 모든 예약된 작업을 나열합니다 | 아니오 |

22| `Edit` | 특정 파일에 대한 대상 편집을 수행합니다. [Edit 도구 동작](#edit-tool-behavior) 참조 | 예 |22| `Edit` | 특정 파일에 대한 대상 편집을 수행합니다. [Edit 도구 동작](#edit-tool-behavior) 참조 | 예 |

23| `EnterPlanMode` | Plan Mode로 전환하여 코딩 전에 접근 방식을 설계합니다 | 아니오 |23| `EnterPlanMode` | Plan Mode로 전환하여 코딩 전에 접근 방식을 설계합니다 | 아니오 |

24| `EnterWorktree` | 격리된 [git worktree](/ko/worktrees)를 생성하고 전환합니다. 새로운 worktree를 생성하는 대신 현재 저장소의 기존 worktree로 전환하려면 `path`를 전달합니다. worktree 세션 내에서 또는 [`isolation: worktree`](/ko/sub-agents#supported-frontmatter-fields)와 같이 고정된 작업 디렉토리를 가진 subagent에서는 `path` 형식만 사용 가능하며 대상은 `.claude/worktrees/` 아래에 있어야 합니다 | 아니오 |24| `EnterWorktree` | 격리된 [git worktree](/ko/worktrees)를 생성하고 전환합니다. 새로운 worktree를 생성하는 대신 기존 worktree로 전환하려면 `path`를 전달합니다. {/* min-version: 2.1.203 */}처음 진입할 때 대상은 현재 저장소의 worktree이거나, 다중 저장소 작업 공간에서 그 안에 중첩된 저장소의 worktree일 수 있습니다. v2.1.203 이전에는 중첩된 저장소의 worktree가 거부되었습니다. worktree 세션 내에서 또는 [`isolation: worktree`](/ko/sub-agents#supported-frontmatter-fields)와 같이 고정된 작업 디렉토리를 가진 subagent에서는 `path` 형식만 사용 가능하며 대상은 세션의 저장소의 `.claude/worktrees/` 아래에 있어야 합니다 | 아니오 |

25| `ExitPlanMode` | 승인을 위한 계획을 제시하고 Plan Mode를 종료합니다 | 예 |25| `ExitPlanMode` | 승인을 위한 계획을 제시하고 Plan Mode를 종료합니다 | 예 |

26| `ExitWorktree` | worktree 세션을 종료하고 원래 디렉토리로 돌아갑니다. [`isolation: worktree`](/ko/sub-agents#supported-frontmatter-fields)와 같이 자체 작업 디렉토리에서 이미 실행되는 subagent에서는 사용할 수 없습니다 | 아니오 |26| `ExitWorktree` | worktree 세션을 종료하고 원래 디렉토리로 돌아갑니다. [`isolation: worktree`](/ko/sub-agents#supported-frontmatter-fields)와 같이 자체 작업 디렉토리에서 이미 실행되는 subagent에서는 사용할 수 없습니다 | 아니오 |

27| `Glob` | 패턴 매칭을 기반으로 파일을 찾습니다. [Glob 도구 동작](#glob-tool-behavior) 참조 | 아니오 |27| `Glob` | 패턴 매칭을 기반으로 파일을 찾습니다. [Glob 도구 동작](#glob-tool-behavior) 참조 | 아니오 |

31| `Monitor` | 백그라운드에서 명령을 실행하고 각 출력 라인을 Claude에 다시 전달하므로, Claude는 로그 항목, 파일 변경 또는 대화 중 폴링된 상태에 반응할 수 있습니다. WebSocket을 열고 각 수신 메시지를 이벤트로 처리할 수도 있습니다. [Monitor 도구](#monitor-tool) 참조 | 예 |31| `Monitor` | 백그라운드에서 명령을 실행하고 각 출력 라인을 Claude에 다시 전달하므로, Claude는 로그 항목, 파일 변경 또는 대화 중 폴링된 상태에 반응할 수 있습니다. WebSocket을 열고 각 수신 메시지를 이벤트로 처리할 수도 있습니다. [Monitor 도구](#monitor-tool) 참조 | 예 |

32| `NotebookEdit` | Jupyter 노트북 셀을 수정합니다. [NotebookEdit 도구 동작](#notebookedit-tool-behavior) 참조 | 예 |32| `NotebookEdit` | Jupyter 노트북 셀을 수정합니다. [NotebookEdit 도구 동작](#notebookedit-tool-behavior) 참조 | 예 |

33| `PowerShell` | PowerShell 명령을 기본적으로 실행합니다. [PowerShell 도구](#powershell-tool) 참조 | 예 |33| `PowerShell` | PowerShell 명령을 기본적으로 실행합니다. [PowerShell 도구](#powershell-tool) 참조 | 예 |

34| `PushNotification` | 데스크톱 알림을 보내고, [Remote Control](/ko/remote-control)이 연결되었을 때 휴대폰 푸시를 보내므로, 장기 실행 작업 또는 [예약된 작업](/ko/scheduled-tasks)이 사용자가 자리를 떠났을 때 연락할 수 있습니다. {/* plan-availability: feature=push-notifications providers=anthropic */}푸시 전달은 Amazon Bedrock, Google Vertex AI 또는 Microsoft Foundry에서 접근할 수 없는 Anthropic 호스팅 인프라를 통해 실행됩니다 | 아니오 |34| `PushNotification` | 데스크톱 알림을 보내고, [Remote Control](/ko/remote-control)이 연결되었을 때 휴대폰 푸시를 보내므로, 장기 실행 작업 또는 [예약된 작업](/ko/scheduled-tasks)이 사용자가 자리를 떠났을 때 연락할 수 있습니다. {/* plan-availability: feature=push-notifications providers=anthropic */}푸시 전달은 Amazon Bedrock, Google Cloud의 Agent Platform 또는 Microsoft Foundry에서 접근할 수 없는 Anthropic 호스팅 인프라를 통해 실행됩니다 | 아니오 |

35| `Read` | 파일의 내용을 읽습니다. [Read 도구 동작](#read-tool-behavior) 참조 | 아니오 |35| `Read` | 파일의 내용을 읽습니다. [Read 도구 동작](#read-tool-behavior) 참조 | 아니오 |

36| `ReadMcpResourceTool` | URI로 특정 MCP 리소스를 읽습니다 | 아니오 |36| `ReadMcpResourceTool` | URI로 특정 MCP 리소스를 읽습니다 | 아니오 |

37| `RemoteTrigger` | claude.ai에서 [Routines](/ko/routines)를 생성, 업데이트, 실행 및 나열합니다. `/schedule` 명령을 지원합니다. {/* plan-availability: feature=routines plans=pro,max,team,enterprise providers=anthropic */}Routines는 claude.ai에 있으며 Pro, Max, Team 또는 Enterprise 플랜이 필요하므로, 이 도구는 Amazon Bedrock, Google Vertex AI 또는 Microsoft Foundry에서 접근할 수 없습니다 | 아니오 |37| `RemoteTrigger` | claude.ai에서 [Routines](/ko/routines)를 생성, 업데이트, 실행 및 나열합니다. `/schedule` 명령을 지원합니다. {/* plan-availability: feature=routines plans=pro,max,team,enterprise providers=anthropic */}Routines는 claude.ai에 있으며 Pro, Max, Team 또는 Enterprise 플랜이 필요하므로, 이 도구는 Amazon Bedrock, Google Cloud의 Agent Platform 또는 Microsoft Foundry에서 접근할 수 없습니다 | 아니오 |

38| `ReportFindings` | 코드 리뷰 결과를 구조화된 목록으로 보고하며, 각 결과마다 파일, 요약 및 실패 시나리오를 포함하므로 Claude Code가 텍스트로 인쇄하는 대신 렌더링할 수 있습니다. Claude는 활성 코드 리뷰 지침이 이를 수행하도록 지시할 때 호출합니다. {/* min-version: 2.1.196 */}Claude Code v2.1.196 이상이 필요합니다. {/* min-version: 2.1.199 */}v2.1.199부터 결과는 `correctness` 또는 `test-coverage`와 같은 선택적 `category` 슬러그를 포함할 수 있으며, 렌더링된 목록에서 파일 위치 옆에 표시됩니다 | 아니오 |38| `ReportFindings` | 코드 리뷰 결과를 구조화된 목록으로 보고하며, 각 결과마다 파일, 요약 및 실패 시나리오를 포함하므로 Claude Code가 텍스트로 인쇄하는 대신 렌더링할 수 있습니다. Claude는 활성 코드 리뷰 지침이 이를 수행하도록 지시할 때 호출합니다. {/* min-version: 2.1.196 */}Claude Code v2.1.196 이상이 필요합니다. {/* min-version: 2.1.199 */}v2.1.199부터 결과는 `correctness` 또는 `test-coverage`와 같은 선택적 `category` 슬러그를 포함할 수 있으며, 렌더링된 목록에서 파일 위치 옆에 표시됩니다 | 아니오 |

39| `ScheduleWakeup` | [자체 속도 `/loop`](/ko/scheduled-tasks#let-claude-choose-the-interval)의 다음 반복을 다시 예약합니다. Claude는 각 반복이 끝날 때 이를 호출하여 다음 반복이 실행될 시간을 선택합니다(1분에서 1시간 사이). 사용자가 직접 호출하지는 않습니다. 대기 중인 wakeup은 [Stop hook input](/ko/hooks#stop-input)의 `session_crons`에 나타납니다. {/* plan-availability: feature=loop-dynamic providers=anthropic */}Amazon Bedrock, Google Vertex AI 또는 Microsoft Foundry에서는 사용할 수 없으며, 여기서 간격이 없는 `/loop` 프롬프트는 고정 일정으로 실행됩니다 | 아니오 |39| `ScheduleWakeup` | [자체 속도 `/loop`](/ko/scheduled-tasks#let-claude-choose-the-interval)의 다음 반복을 다시 예약합니다. Claude는 각 반복이 끝날 때 이를 호출하여 다음 반복이 실행될 시간을 선택합니다(1분에서 1시간 사이). 사용자가 직접 호출하지는 않습니다. 루프를 종료하는 대신 Claude는 `stop: true`로 이를 호출하여 대기 중인 wakeup을 취소합니다. {/* min-version: 2.1.202 */}}`stop` 필드는 Claude Code v2.1.202 이상이 필요합니다. 대기 중인 wakeup은 [Stop hook input](/ko/hooks#stop-input)의 `session_crons`에 나타납니다. {/* plan-availability: feature=loop-dynamic providers=anthropic */}Amazon Bedrock, Google Cloud의 Agent Platform 또는 Microsoft Foundry에서는 사용할 수 없으며, 여기서 간격이 없는 `/loop` 프롬프트는 고정 일정으로 실행됩니다 | 아니오 |

40| `SendMessage` | [agent team](/ko/agent-teams) 팀원에게 메시지를 보내거나, agent ID 또는 이름으로 [subagent를 재개합니다](/ko/sub-agents#resume-subagents). 중지된 subagent는 백그라운드에서 자동으로 재개됩니다. 구조화된 팀 프로토콜 메시지는 agent team이 필요합니다. {/* min-version: 2.1.198 */}v2.1.198부터 subagent는 이를 시작한 agent로부터의 메시지를 피어 요청이 아닌 일반 작업 지시로 취급합니다. {/* min-version: 2.1.199 */}v2.1.199부터 대화 초반에 해결된 이름과 다른 agent로 현재 해결되는 이름으로의 전송은 전달되는 대신 거부됩니다. [subagent 재개](/ko/sub-agents#resume-subagents) 참조 | 아니오 |40| `SendMessage` | [agent team](/ko/agent-teams) 팀원에게 메시지를 보내거나, agent ID 또는 이름으로 [subagent를 재개합니다](/ko/sub-agents#resume-subagents). 중지된 subagent는 백그라운드에서 자동으로 재개됩니다. 구조화된 팀 프로토콜 메시지는 agent team이 필요합니다. 다른 agent로부터의 메시지는 사용자의 동의 또는 승인으로 취급되지 않습니다. {/* min-version: 2.1.198 */}v2.1.198부터 subagent는 이를 시작한 agent로부터의 메시지를 피어 요청이 아닌 일반 작업 지시로 취급합니다. {/* min-version: 2.1.199 */}v2.1.199부터 대화 초반에 해결된 이름과 다른 agent로 현재 해결되는 이름으로의 전송은 전달되는 대신 거부됩니다. [subagent 재개](/ko/sub-agents#resume-subagents) 참조 | 아니오 |

41| `SendUserFile` | 선택적 캡션과 함께 세션에서 파일을 사용자에게 보내므로, 생성된 보고서, 다이어그램, 스크린샷 또는 빌드된 아티팩트가 트랜스크립트에서만 언급되는 대신 사용자의 기기에 도달합니다. {/* min-version: 2.1.196 */}v2.1.196부터 선택적 `display` 입력은 프레젠테이션을 제어합니다: `render`는 클라이언트에서 파일을 인라인으로 열고, `attach`는 다운로드 카드만 표시하며, 설정되지 않으면 클라이언트가 파일 타입에 따라 결정합니다. [Remote Control](/ko/remote-control) 클라이언트가 연결되었거나 세션이 [Claude Code on the web](/ko/claude-code-on-the-web)과 같은 관리형 클라우드 환경에서 실행될 때 사용 가능합니다. 전달은 Anthropic 호스팅 인프라를 통해 실행되므로, 이 도구는 Amazon Bedrock, Google Vertex AI 또는 Microsoft Foundry에서 사용할 수 없습니다 | 아니오 |41| `SendUserFile` | 선택적 캡션과 함께 세션에서 파일을 사용자에게 보내므로, 생성된 보고서, 다이어그램, 스크린샷 또는 빌드된 아티팩트가 트랜스크립트에서만 언급되는 대신 사용자의 기기에 도달합니다. {/* min-version: 2.1.196 */}v2.1.196부터 선택적 `display` 입력은 프레젠테이션을 제어합니다: `render`는 클라이언트에서 파일을 인라인으로 열고, `attach`는 다운로드 카드만 표시하며, 설정되지 않으면 클라이언트가 파일 타입에 따라 결정합니다. [Remote Control](/ko/remote-control) 클라이언트가 연결되었거나 세션이 [Claude Code on the web](/ko/claude-code-on-the-web)과 같은 관리형 클라우드 환경에서 실행될 때 사용 가능합니다. 전달은 Anthropic 호스팅 인프라를 통해 실행되므로, 이 도구는 Amazon Bedrock, Google Cloud의 Agent Platform 또는 Microsoft Foundry에서 사용할 수 없습니다 | 아니오 |

42| `ShareOnboardingGuide` | {/* plan-availability: feature=onboarding-guide-share plans=pro,max,team,enterprise providers=anthropic */}}`ONBOARDING.md`를 업로드하고 팀원이 Claude Code에서 열 수 있는 공유 링크를 반환합니다. 가이드가 작성된 후 `/team-onboarding`에서 호출됩니다. Pro, Max, Team 및 Enterprise 플랜의 claude.ai 구독자가 사용 가능합니다 | 예 |42| `ShareOnboardingGuide` | {/* plan-availability: feature=onboarding-guide-share plans=pro,max,team,enterprise providers=anthropic */}}`ONBOARDING.md`를 업로드하고 팀원이 Claude Code에서 열 수 있는 공유 링크를 반환합니다. 가이드가 작성된 후 `/team-onboarding`에서 호출됩니다. Pro, Max, Team 및 Enterprise 플랜의 claude.ai 구독자가 사용 가능합니다 | 예 |

43| `Skill` | 주 대화 내에서 [skill](/ko/skills#control-who-invokes-a-skill)을 실행합니다 | 예 |43| `Skill` | 주 대화 내에서 [skill](/ko/skills#control-who-invokes-a-skill)을 실행합니다 | 예 |

44| `TaskCreate` | 작업 목록에 새 작업을 생성합니다 | 아니오 |44| `TaskCreate` | 작업 목록에 새 작업을 생성합니다 | 아니오 |

45| `TaskGet` | 특정 작업의 전체 세부 정보를 검색합니다 | 아니오 |45| `TaskGet` | 특정 작업의 전체 세부 정보를 검색합니다 | 아니오 |

46| `TaskList` | 현재 상태와 함께 모든 작업을 나열합니다 | 아니오 |46| `TaskList` | 현재 상태와 함께 모든 작업을 나열합니다 | 아니오 |

47| `TaskOutput` | (더 이상 사용되지 않음) 백그라운드 작업에서 출력을 검색합니다. 작업의 출력 파일 경로에서 `Read`를 사용하는 것을 권장합니다 | 아니오 |47| `TaskOutput` | 백그라운드 작업에서 출력을 검색합니다. `Read`를 작업의 출력 파일 경로에서 사용하는 것을 권장합니다. {/* min-version: 2.1.203 */}}ID와 일치하는 작업이 없으면 오류는 실행 중인 백그라운드 agent를 ID 및 설명으로 나열합니다. v2.1.203 이전에는 오류가 누락된 ID만 명명했습니다 | 아니오 |

48| `TaskStop` | ID로 실행 중인 백그라운드 작업을 종료합니다. {/* min-version: 2.1.198 */}v2.1.198부터 [agent team 팀원](/ko/agent-teams) 또는 agent ID 또는 이름으로 명명된 백그라운드 agent도 허용합니다 | 아니오 |48| `TaskStop` | ID로 실행 중인 백그라운드 작업을 종료합니다. {/* min-version: 2.1.198 */}}또한 [agent team 팀원](/ko/agent-teams) 또는 agent ID 또는 이름으로 명명된 백그라운드 agent도 허용합니다. v2.1.198 이전에는 백그라운드 작업 ID만 허용했습니다. {/* min-version: 2.1.203 */}}ID와 일치하는 작업이 없으면 오류는 실행 중인 백그라운드 agent를 ID 및 설명으로 나열하며, 다른 agent가 생성한 agent도 포함합니다. v2.1.203 이전에는 오류가 실행 중인 팀원 및 명명된 agent를 나열했지만 다른 agent가 생성한 백그라운드 agent는 나열하지 않았으므로 주 대화에서 식별하거나 중지할 수 없었습니다 | 아니오 |

49| `TaskUpdate` | 작업 상태, 종속성, 세부 정보를 업데이트하거나 작업을 삭제합니다 | 아니오 |49| `TaskUpdate` | 작업 상태, 종속성, 세부 정보를 업데이트하거나 작업을 삭제합니다 | 아니오 |

50| `TodoWrite` | {/* min-version: 2.1.142 */}세션 작업 체크리스트를 관리합니다. v2.1.142부터 기본적으로 비활성화되어 있으며 `TaskCreate`, `TaskGet`, `TaskList`, `TaskUpdate`를 선호합니다. `CLAUDE_CODE_ENABLE_TASKS=0`을 설정하여 다시 활성화합니다 | 아니오 |50| `TodoWrite` | {/* min-version: 2.1.142 */}}세션 작업 체크리스트를 관리합니다. v2.1.142부터 기본적으로 비활성화되어 있으며 `TaskCreate`, `TaskGet`, `TaskList`, `TaskUpdate`를 선호합니다. `CLAUDE_CODE_ENABLE_TASKS=0`을 설정하여 다시 활성화합니다 | 아니오 |

51| `ToolSearch` | [tool search](/ko/mcp#scale-with-mcp-tool-search)가 활성화되었을 때 지연된 도구를 검색하고 로드합니다 | 아니오 |51| `ToolSearch` | [tool search](/ko/mcp#scale-with-mcp-tool-search)가 활성화되었을 때 지연된 도구를 검색하고 로드합니다 | 아니오 |

52| `WaitForMcpServers` | 백그라운드에서 여전히 연결 중인 하나 이상의 [MCP 서버](/ko/mcp)를 기다리므로, 요청이 세션을 다시 시작하지 않고도 해당 도구를 사용할 수 있습니다. Claude는 필요한 서버가 아직 연결되지 않았을 때 이를 호출합니다. [tool search](/ko/mcp#scale-with-mcp-tool-search)가 비활성화되었을 때만 나타나며, `ToolSearch`가 활성화되었을 때는 대기를 처리합니다 | 아니오 |52| `WaitForMcpServers` | 백그라운드에서 여전히 연결 중인 하나 이상의 [MCP 서버](/ko/mcp)를 기다리므로, 요청이 세션을 다시 시작하지 않고도 해당 도구를 사용할 수 있습니다. Claude는 필요한 서버가 아직 연결되지 않았을 때 이를 호출합니다. [tool search](/ko/mcp#scale-with-mcp-tool-search)가 비활성화되었을 때만 나타나며, `ToolSearch`가 활성화되었을 때는 대기를 처리합니다 | 아니오 |

53| `WebFetch` | 지정된 URL에서 콘텐츠를 가져옵니다. [WebFetch 도구 동작](#webfetch-tool-behavior) 참조 | 예 |53| `WebFetch` | 지정된 URL에서 콘텐츠를 가져옵니다. [WebFetch 도구 동작](#webfetch-tool-behavior) 참조 | 예 |

220 220

221Monitor가 명령을 실행할 때, [Bash와 동일한 권한 규칙](/ko/permissions#tool-specific-permission-rules)을 사용하므로, Bash에 대해 설정한 `allow` 및 `deny` 패턴이 여기에도 적용됩니다. [WebSocket 소스](#websocket-source)는 자체 승인 프롬프트를 가집니다.221Monitor가 명령을 실행할 때, [Bash와 동일한 권한 규칙](/ko/permissions#tool-specific-permission-rules)을 사용하므로, Bash에 대해 설정한 `allow` 및 `deny` 패턴이 여기에도 적용됩니다. [WebSocket 소스](#websocket-source)는 자체 승인 프롬프트를 가집니다.

222 222

223이 도구는 Amazon Bedrock, Google Vertex AI 또는 Microsoft Foundry에서 사용할 수 없습니다. `DISABLE_TELEMETRY` 또는 `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC`이 설정되었을 때도 사용할 수 없습니다.223이 도구는 Amazon Bedrock, Google Cloud의 Agent Platform 또는 Microsoft Foundry에서 사용할 수 없습니다. `DISABLE_TELEMETRY` 또는 `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC`이 설정되었을 때도 사용할 수 없습니다.

224 224

225플러그인은 Claude에 시작하도록 요청하는 대신 플러그인이 활성화될 때 자동으로 시작되는 모니터를 선언할 수 있습니다. [플러그인 모니터](/ko/plugins-reference#monitors)를 참조합니다.225플러그인은 Claude에 시작하도록 요청하는 대신 플러그인이 활성화될 때 자동으로 시작되는 모니터를 선언할 수 있습니다. [플러그인 모니터](/ko/plugins-reference#monitors)를 참조합니다.

226 226

369WebSearch 권한 규칙은 specifier를 사용하지 않습니다. `allow` 또는 `deny`의 단순 `WebSearch` 항목이 유일한 형식입니다.369WebSearch 권한 규칙은 specifier를 사용하지 않습니다. `allow` 또는 `deny`의 단순 `WebSearch` 항목이 유일한 형식입니다.

370 370

371<Note>371<Note>

372 WebSearch는 Claude API, [AWS의 Claude Platform](/ko/claude-platform-on-aws) 및 Microsoft Foundry에서 사용 가능합니다. Google Cloud Vertex AI에서는 Opus, Sonnet 및 Haiku를 포함한 Claude 4 이상 모델과 함께 작동합니다. Amazon Bedrock은 서버 측 web search 도구를 노출하지 않습니다.372 WebSearch는 Claude API, [AWS의 Claude Platform](/ko/claude-platform-on-aws) 및 Microsoft Foundry에서 사용 가능합니다. Google Cloud의 Agent Platform에서는 Opus, Sonnet 및 Haiku를 포함한 Claude 4 이상 모델과 함께 작동합니다. Amazon Bedrock은 서버 측 web search 도구를 노출하지 않습니다.

373</Note>373</Note>

374 374

375<h2 id="write-tool-behavior">375<h2 id="write-tool-behavior">

troubleshoot-install.md +17 −14

Details

15표시되는 오류 메시지 또는 증상을 수정 사항과 일치시키세요:15표시되는 오류 메시지 또는 증상을 수정 사항과 일치시키세요:

16 16

17| 표시되는 내용 | 해결책 |17| 표시되는 내용 | 해결책 |

~~18| :------------------------------------------------------------------------------------------ | :--------------------------------------------------------------------------------------------- |~~18| :------------------------------------------------------------------------------------------ | :----------------------------------------------------------------------------------------------------------------------------------- |

21| `curl: (22) The requested URL returned error: 403` | [설치 스크립트가 HTML 반환](#install-script-returns-html-instead-of-a-shell-script) |21| `curl: (22) The requested URL returned error: 403` | [설치 스크립트가 HTML 반환](#install-script-returns-html-instead-of-a-shell-script) |

22| `curl: (23)` 또는 `curl: (56) Failure writing output to destination` | [연결성 확인 또는 대체 설치 프로그램 사용](#curl-56-failure-writing-output-to-destination) |22| `curl: (23)` 또는 `curl: (56) Failure writing output to destination` | [연결성 확인 또는 대체 설치 프로그램 사용](#curl-56-failure-writing-output-to-destination) |

39| `App unavailable in region` | Claude Code는 귀국에서 사용할 수 없습니다. [지원되는 국가](https://www.anthropic.com/supported-countries)를 참조하세요. |39| `App unavailable in region` | Claude Code는 귀국에서 사용할 수 없습니다. [지원되는 국가](https://www.anthropic.com/supported-countries)를 참조하세요. |

42| `Could not load the default credentials` 또는 `Could not load credentials from any providers` | [Bedrock, Vertex 또는 Foundry 자격증명](#bedrock-vertex-or-foundry-credentials-not-loading) |42| `Could not load the default credentials` 또는 `Could not load credentials from any providers` | [Amazon Bedrock, Google Cloud의 Agent Platform 또는 Microsoft Foundry 자격증명](#bedrock-agent-platform-or-foundry-credentials-not-loading) |

43| `ChainedTokenCredential authentication failed` 또는 `CredentialUnavailableError` | [Bedrock, Vertex 또는 Foundry 자격증명](#bedrock-vertex-or-foundry-credentials-not-loading) |43| `ChainedTokenCredential authentication failed` 또는 `CredentialUnavailableError` | [Amazon Bedrock, Google Cloud의 Agent Platform 또는 Microsoft Foundry 자격증명](#bedrock-agent-platform-or-foundry-credentials-not-loading) |

45 45

46문제가 나열되지 않은 경우 아래의 진단 검사를 수행하여 원인을 좁혀보세요.46문제가 나열되지 않은 경우 아래의 진단 검사를 수행하여 원인을 좁혀보세요.

538 저메모리 Linux 서버에서 설치 중단538 저메모리 Linux 서버에서 설치 중단

539</h3>539</h3>

540 540

541VPS 또는 클라우드 인스턴스에서 설치 중에 `Killed`가 표시되면:541설치 중에 `Killed` 메시지가 표시되면 일반적으로 Linux OOM(메모리 부족) killer가 시스템이 메모리 부족으로 인해 `claude install` 단계를 종료했음을 의미합니다. 이는 작은 VPS 및 클라우드 인스턴스에서 일반적입니다. 설치 스크립트는 원인을 보고하고 종료 코드 137로 종료됩니다:

542 542

543```text theme={null}543```text theme={null}

544Setting up Claude Code...544Setting up Claude Code...

545Installing Claude Code native build latest...

546bash: line 142: 34803 Killed "$binary_path" install ${TARGET:+"$TARGET"}545bash: line 142: 34803 Killed "$binary_path" install ${TARGET:+"$TARGET"}

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

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

547```548```

548 549

549Linux OOM killer는 시스템이 메모리 부족으로 인해 프로세스를 종료했습니다. Claude Code는 최소 4GB의 사용 가능한 RAM이 필요합니다.550v2.1.200 이전에는 스크립트가 설명 없이 셸의 단순 `Killed` 줄로만 종료되었습니다.

551

552설치에는 대략 512MB의 여유 메모리가 필요하며 Claude Code를 실행하려면 더 많은 메모리가 필요합니다. [시스템 요구사항](/ko/setup#system-requirements)을 참조하세요.

550 553

551**해결책:**554**해결책:**

552 555

781`@anthropic-ai/claude-code` npm 패키지는 `@anthropic-ai/claude-code-darwin-arm64`와 같은 플랫폼별 선택적 종속성을 통해 네이티브 바이너리를 가져옵니다. 설치 후 `claude`를 실행하면 `Could not find native binary package "@anthropic-ai/claude-code-<platform>"`이 인쇄되면 다음 원인을 확인하세요:784`@anthropic-ai/claude-code` npm 패키지는 `@anthropic-ai/claude-code-darwin-arm64`와 같은 플랫폼별 선택적 종속성을 통해 네이티브 바이너리를 가져옵니다. 설치 후 `claude`를 실행하면 `Could not find native binary package "@anthropic-ai/claude-code-<platform>"`이 인쇄되면 다음 원인을 확인하세요:

782 785

783* **선택적 종속성이 비활성화됨.** npm 설치 명령에서 `--omit=optional`을 제거하고 pnpm에서 `--no-optional`을 제거하고 yarn에서 `--ignore-optional`을 제거하고 `.npmrc`가 `optional=false`를 설정하지 않는지 확인하세요. 그런 다음 다시 설치하세요. 네이티브 바이너리는 선택적 종속성으로만 제공되므로 건너뛰면 JavaScript 폴백이 없습니다.786* **선택적 종속성이 비활성화됨.** npm 설치 명령에서 `--omit=optional`을 제거하고 pnpm에서 `--no-optional`을 제거하고 yarn에서 `--ignore-optional`을 제거하고 `.npmrc`가 `optional=false`를 설정하지 않는지 확인하세요. 그런 다음 다시 설치하세요. 네이티브 바이너리는 선택적 종속성으로만 제공되므로 건너뛰면 JavaScript 폴백이 없습니다.

784* **지원되지 않는 플랫폼.** 미리 빌드된 바이너리는 `darwin-arm64`, `darwin-x64`, `linux-x64`, `linux-arm64`, `linux-x64-musl`, `linux-arm64-musl`, `win32-x64` 및 `win32-arm64`에 대해 게시됩니다. Claude Code는 다른 플랫폼에 대한 바이너리를 제공하지 않습니다. [시스템 요구사항](/ko/setup#system-requirements)을 참조하세요.787* **지원되지 않는 플랫폼.** 미리 빌드된 바이너리는 `darwin-arm64`, `darwin-x64`, `linux-x64`, `linux-arm64`, `linux-x64-musl`, `linux-arm64-musl`, `win32-x64` 및 `win32-arm64`에 대해 게시됩니다. Claude Code는 다른 플랫폼에 대한 바이너리를 제공하지 않습니다. [시스템 요구사항](/ko/setup#system-requirements)을 참조하세요. {/* min-version: 2.1.205 */}FreeBSD에서 설치 프로그램은 플랫폼을 지원되지 않음으로 보고합니다. v2.1.205 이전에는 FreeBSD를 Linux로 취급하고 실행할 수 없는 바이너리를 다운로드했습니다.

785* **회사 npm 미러가 플랫폼 패키지를 누락함.** 레지스트리가 메타 패키지 외에도 8개의 `@anthropic-ai/claude-code-*` 플랫폼 패키지를 모두 미러링하는지 확인하세요.788* **회사 npm 미러가 플랫폼 패키지를 누락함.** 레지스트리가 메타 패키지 외에도 8개의 `@anthropic-ai/claude-code-*` 플랫폼 패키지를 모두 미러링하는지 확인하세요.

786 789

787`--ignore-scripts`로 설치하면 이 오류가 트리거되지 않습니다. 바이너리를 제자리에 연결하는 postinstall 단계를 건너뛰므로 Claude Code는 각 시작 시 플랫폼 바이너리를 찾아 생성하는 래퍼로 폴백합니다. 이는 작동하지만 더 느리게 시작됩니다. 직접 실행을 위해 스크립트를 활성화하여 다시 설치하세요.790`--ignore-scripts`로 설치하면 이 오류가 트리거되지 않습니다. 바이너리를 제자리에 연결하는 postinstall 단계를 건너뛰므로 Claude Code는 각 시작 시 플랫폼 바이너리를 찾아 생성하는 래퍼로 폴백합니다. 이는 작동하지만 더 느리게 시작됩니다. 직접 실행을 위해 스크립트를 활성화하여 다시 설치하세요.

876 879

877macOS에서 Keychain이 잠겨 있거나 암호가 계정 암호와 동기화되지 않으면 로그인이 실패할 수도 있으며, 이는 Claude Code가 자격증명을 저장하지 못하게 합니다. `claude doctor`를 실행하여 Keychain 액세스를 확인하세요. Keychain을 수동으로 잠금 해제하려면 `security unlock-keychain ~/Library/Keychains/login.keychain-db`를 실행하세요. 잠금 해제가 도움이 되지 않으면 Keychain Access를 열고 `login` keychain을 선택한 다음 편집 > Keychain "login"의 암호 변경을 선택하여 계정 암호와 다시 동기화하세요.880macOS에서 Keychain이 잠겨 있거나 암호가 계정 암호와 동기화되지 않으면 로그인이 실패할 수도 있으며, 이는 Claude Code가 자격증명을 저장하지 못하게 합니다. `claude doctor`를 실행하여 Keychain 액세스를 확인하세요. Keychain을 수동으로 잠금 해제하려면 `security unlock-keychain ~/Library/Keychains/login.keychain-db`를 실행하세요. 잠금 해제가 도움이 되지 않으면 Keychain Access를 열고 `login` keychain을 선택한 다음 편집 > Keychain "login"의 암호 변경을 선택하여 계정 암호와 다시 동기화하세요.

878 881

879<h3 id="bedrock-vertex-or-foundry-credentials-not-loading">882<h3 id="bedrock-agent-platform-or-foundry-credentials-not-loading">

880 Bedrock, Vertex 또는 Foundry 자격증명이 로드되지 않음883 Bedrock, Agent Platform 또는 Foundry 자격증명이 로드되지 않음

881</h3>884</h3>

882 885

883Claude Code를 클라우드 공급자를 사용하도록 구성했고 Bedrock에서 `Could not load credentials from any providers`, Vertex에서 `Could not load the default credentials` 또는 Foundry에서 `ChainedTokenCredential authentication failed`가 표시되면 클라우드 공급자 CLI가 현재 셸에서 인증되지 않았을 가능성이 높습니다.886Claude Code를 클라우드 공급자를 사용하도록 구성했고 Amazon Bedrock에서 `Could not load credentials from any providers`, Google Cloud의 Agent Platform에서 `Could not load the default credentials` 또는 Microsoft Foundry에서 `ChainedTokenCredential authentication failed`가 표시되면 클라우드 공급자 CLI가 현재 셸에서 인증되지 않았을 가능성이 높습니다.

884 887

885Bedrock의 경우 AWS 자격증명이 유효한지 확인하세요:888Amazon Bedrock의 경우 AWS 자격증명이 유효한지 확인하세요:

886 889

887```bash theme={null}890```bash theme={null}

888aws sts get-caller-identity891aws sts get-caller-identity

889```892```

890 893

891Vertex AI의 경우 `ANTHROPIC_VERTEX_PROJECT_ID` 및 `CLOUD_ML_REGION`이 셸에 설정되어 있는지 확인한 다음 애플리케이션 기본 자격증명을 설정하세요:894Google Cloud의 Agent Platform의 경우 `ANTHROPIC_VERTEX_PROJECT_ID` 및 `CLOUD_ML_REGION`이 셸에 설정되어 있는지 확인한 다음 애플리케이션 기본 자격증명을 설정하세요:

892 895

893```bash theme={null}896```bash theme={null}

894gcloud auth application-default login897gcloud auth application-default login

902 905

903자격증명이 터미널에서 작동하지만 VS Code 또는 JetBrains 확장에서 작동하지 않으면 IDE 프로세스가 셸 환경을 상속하지 않았을 가능성이 높습니다. IDE의 자체 설정에서 공급자 환경 변수를 설정하거나 이미 내보낸 터미널에서 IDE를 시작하세요.906자격증명이 터미널에서 작동하지만 VS Code 또는 JetBrains 확장에서 작동하지 않으면 IDE 프로세스가 셸 환경을 상속하지 않았을 가능성이 높습니다. IDE의 자체 설정에서 공급자 환경 변수를 설정하거나 이미 내보낸 터미널에서 IDE를 시작하세요.

904 907

905전체 공급자 설정은 [Amazon Bedrock](/ko/amazon-bedrock), [Google Vertex AI](/ko/google-vertex-ai) 또는 [Microsoft Foundry](/ko/microsoft-foundry)를 참조하세요.908전체 공급자 설정은 [Amazon Bedrock](/ko/amazon-bedrock), [Google Cloud의 Agent Platform](/ko/google-vertex-ai) 또는 [Microsoft Foundry](/ko/microsoft-foundry)를 참조하세요.

906 909

907<h2 id="still-stuck">910<h2 id="still-stuck">

908 여전히 막혔습니다911 여전히 막혔습니다

troubleshooting.md +6 −5

Details

9이 페이지는 Claude Code가 실행 중일 때의 성능, 안정성 및 검색 문제를 다룹니다. 다른 문제의 경우 문제가 있는 위치와 일치하는 페이지부터 시작하세요:9이 페이지는 Claude Code가 실행 중일 때의 성능, 안정성 및 검색 문제를 다룹니다. 다른 문제의 경우 문제가 있는 위치와 일치하는 페이지부터 시작하세요:

10 10

11| 증상 | 이동 |11| 증상 | 이동 |

~~12| :--------------------------------------------------------------------------------------- | :------------------------------------------------------------------- |~~12| :---------------------------------------------------------------------------------------------------------------------------------- | :---------------------------------------------------------------------- |

14| 로그인 루프, OAuth 오류, `403 Forbidden`, "organization disabled", Bedrock/Vertex/Foundry 자격 증명 | [설치 및 로그인 문제 해결](/ko/troubleshoot-install#login-and-authentication) |14| `The connection dropped while downloading the update` 또는 `aborted`로 업데이트 또는 설치 다운로드 실패 | [오류 참조](/ko/errors#the-connection-dropped-while-downloading-the-update) |

15| 로그인 루프, OAuth 오류, `403 Forbidden`, "organization disabled", Amazon Bedrock, Google Cloud의 Agent Platform 또는 Microsoft Foundry 자격 증명 | [설치 및 로그인 문제 해결](/ko/troubleshoot-install#login-and-authentication) |

15| 설정이 적용되지 않음, hooks가 실행되지 않음, MCP 서버가 로드되지 않음 | [구성 디버깅](/ko/debug-your-config) |16| 설정이 적용되지 않음, hooks가 실행되지 않음, MCP 서버가 로드되지 않음 | [구성 디버깅](/ko/debug-your-config) |

19| JetBrains 플러그인 또는 IDE가 감지되지 않음 | [JetBrains 통합](/ko/jetbrains#troubleshooting) |20| JetBrains 플러그인 또는 IDE가 감지되지 않음 | [JetBrains 통합](/ko/jetbrains#troubleshooting) |

20| 높은 CPU 또는 메모리, 느린 응답, 중단, 검색이 파일을 찾지 못함 | [성능 및 안정성](#performance-and-stability) 아래 |21| 높은 CPU 또는 메모리, 느린 응답, 중단, 검색이 파일을 찾지 못함 | [성능 및 안정성](#performance-and-stability) 아래 |

21 22

22어떤 것이 적용되는지 확실하지 않으면 Claude Code 내에서 `/doctor`를 실행하여 설치, 설정, MCP 서버 및 컨텍스트 사용을 자동으로 확인하세요. `claude`가 전혀 시작되지 않으면 셸에서 `claude doctor`를 대신 실행하세요.23어떤 것이 적용되는지 확실하지 않으면 Claude Code 내에서 `/doctor`를 실행하여 설치, 설정, 확장 및 컨텍스트 사용을 자동으로 확인하세요. 이 도구는 확인 후 적용할 수 있는 수정 사항을 제안합니다. `claude`가 전혀 시작되지 않으면 셸에서 `claude doctor`를 대신 실행하세요. `/mcp`를 실행하여 MCP 서버 상태를 확인하세요.

23 24

24<h2 id="performance-and-stability">25<h2 id="performance-and-stability">

25 성능 및 안정성26 성능 및 안정성

119[WSL에서 파일 시스템 간 작업](https://learn.microsoft.com/en-us/windows/wsl/filesystems)할 때 디스크 읽기 성능 저하로 인해 WSL에서 Claude Code를 사용할 때 예상보다 적은 일치 항목이 발생할 수 있습니다. 검색은 여전히 작동하지만 네이티브 파일 시스템보다 적은 결과를 반환합니다.120[WSL에서 파일 시스템 간 작업](https://learn.microsoft.com/en-us/windows/wsl/filesystems)할 때 디스크 읽기 성능 저하로 인해 WSL에서 Claude Code를 사용할 때 예상보다 적은 일치 항목이 발생할 수 있습니다. 검색은 여전히 작동하지만 네이티브 파일 시스템보다 적은 결과를 반환합니다.

120 121

121<Note>122<Note>

122 이 경우 `/doctor`는 검색을 OK로 표시합니다.123 `claude doctor`는 이 경우 검색을 OK로 표시합니다.

123</Note>124</Note>

124 125

125**해결책:**126**해결책:**

136 137

137여기에 다루지 않은 문제가 발생하는 경우:138여기에 다루지 않은 문제가 발생하는 경우:

138 139

1391. `/doctor`를 실행하여 설치 상태, 설정 유효성, MCP 구성 및 컨텍스트 사용을 한 번에 확인하세요1401. `/doctor`를 실행하여 설치 상태를 확인하고 `/mcp`를 사용하여 MCP 서버 상태를 확인하세요

1402. Claude Code 내에서 `/feedback` 명령을 사용하여 Anthropic에 문제를 직접 보고하세요1412. Claude Code 내에서 `/feedback` 명령을 사용하여 Anthropic에 문제를 직접 보고하세요

1413. [GitHub 저장소](https://github.com/anthropics/claude-code)에서 알려진 문제를 확인하세요1423. [GitHub 저장소](https://github.com/anthropics/claude-code)에서 알려진 문제를 확인하세요

1424. Claude에게 직접 기능 및 특징에 대해 물어보세요. Claude는 문서에 대한 기본 제공 액세스 권한이 있습니다.1434. Claude에게 직접 기능 및 특징에 대해 물어보세요. Claude는 문서에 대한 기본 제공 액세스 권한이 있습니다.

ultraplan.md +1 −1

Details

18* **자동 초안 작성**: 계획이 원격으로 생성되므로 터미널이 다른 작업을 위해 자유로워집니다18* **자동 초안 작성**: 계획이 원격으로 생성되므로 터미널이 다른 작업을 위해 자유로워집니다

19* **유연한 실행**: 웹에서 실행하고 풀 요청을 열도록 계획을 승인하거나 터미널로 다시 보냅니다19* **유연한 실행**: 웹에서 실행하고 풀 요청을 열도록 계획을 승인하거나 터미널로 다시 보냅니다

20 20

21Ultraplan은 [웹의 Claude Code](/ko/claude-code-on-the-web) 계정과 GitHub 저장소가 필요합니다. Anthropic의 클라우드 인프라에서 실행되므로 Amazon Bedrock, Google Cloud Vertex AI 또는 Microsoft Foundry를 사용할 때는 사용할 수 없습니다. 클라우드 세션은 계정의 기본 [클라우드 환경](/ko/claude-code-on-the-web#the-cloud-environment)에서 실행됩니다. 아직 클라우드 환경이 없으면 ultraplan이 처음 시작할 때 자동으로 생성합니다.21Ultraplan은 [웹의 Claude Code](/ko/claude-code-on-the-web) 계정과 GitHub 저장소가 필요합니다. Anthropic의 클라우드 인프라에서 실행되므로 Amazon Bedrock, Google Cloud의 Agent Platform 또는 Microsoft Foundry를 사용할 때는 사용할 수 없습니다. 클라우드 세션은 계정의 기본 [클라우드 환경](/ko/claude-code-on-the-web#the-cloud-environment)에서 실행됩니다. 아직 클라우드 환경이 없으면 ultraplan이 처음 시작할 때 자동으로 생성합니다.

22 22

23<h2 id="launch-ultraplan-from-the-cli">23<h2 id="launch-ultraplan-from-the-cli">

24 CLI에서 ultraplan 시작하기24 CLI에서 ultraplan 시작하기

ultrareview.md +4 −4

Details

15로컬 `/code-review` 또는 `/review`와 비교하여 ultrareview는 다음을 제공합니다:15로컬 `/code-review` 또는 `/review`와 비교하여 ultrareview는 다음을 제공합니다:

16 16

17* **더 높은 신호**: 보고된 모든 발견 사항이 독립적으로 재현되고 검증되므로 결과는 스타일 제안보다는 실제 버그에 초점을 맞춥니다17* **더 높은 신호**: 보고된 모든 발견 사항이 독립적으로 재현되고 검증되므로 결과는 스타일 제안보다는 실제 버그에 초점을 맞춥니다

18* **더 광범위한 범위**: 더 큰 리뷰어 에이전트 플릿이 변경 사항을 병렬로 탐색하므로 중간 정도의 노력이 필요한 로컬 리뷰에서 놓칠 수 있는 문제를 표면화합니다18* **더 광범위한 범위**: 더 큰 리뷰어 에이전트 플릿이 변경 사항을 병렬로 탐색하므로 로컬 리뷰에서 놓칠 수 있는 문제를 표면화합니다

19* **로컬 리소스 사용 없음**: 리뷰가 원격 샌드박스에서 완전히 실행되므로 실행 중에 터미널이 다른 작업을 위해 자유로워집니다19* **로컬 리소스 사용 없음**: 리뷰가 원격 샌드박스에서 완전히 실행되므로 실행 중에 터미널이 다른 작업을 위해 자유로워집니다

20 20

21Ultrareview는 Claude Code 웹 인프라에서 실행되기 때문에 Claude.ai 계정으로 인증이 필요합니다. API 키만으로 로그인한 경우 `/login`을 실행하고 먼저 Claude.ai로 인증하세요. Ultrareview는 Amazon Bedrock, Google Cloud Vertex AI 또는 Microsoft Foundry와 함께 Claude Code를 사용할 때 사용할 수 없으며, Zero Data Retention을 활성화한 조직에서도 사용할 수 없습니다.21Ultrareview는 Claude Code 웹 인프라에서 실행되기 때문에 Claude.ai 계정으로 인증이 필요합니다. API 키만으로 로그인한 경우 `/login`을 실행하고 먼저 Claude.ai로 인증하세요. Ultrareview는 Amazon Bedrock, Google Cloud의 Agent Platform 또는 Microsoft Foundry와 함께 Claude Code를 사용할 때 사용할 수 없으며, Zero Data Retention을 활성화한 조직에서도 사용할 수 없습니다.

22 22

23<h2 id="run-ultrareview-from-the-cli">23<h2 id="run-ultrareview-from-the-cli">

24 CLI에서 ultrareview 실행24 CLI에서 ultrareview 실행

107| ----- | -------------- | -------------------- | ---------------------------- |107| ----- | -------------- | -------------------- | ---------------------------- |

108| 대상 | 작업 중인 diff | GitHub 풀 요청 | 작업 중인 diff 또는 풀 요청 |108| 대상 | 작업 중인 diff | GitHub 풀 요청 | 작업 중인 diff 또는 풀 요청 |

109| 실행 | 세션에서 로컬로 | 세션에서 로컬로 | 클라우드 샌드박스에서 원격으로 |109| 실행 | 세션에서 로컬로 | 세션에서 로컬로 | 클라우드 샌드박스에서 원격으로 |

110| 깊이 | 노력 인수에 따라 확장 | 중간 `/code-review` 엔진 | 독립적 검증이 있는 다중 에이전트 플릿 |110| 깊이 | 노력 인수에 따라 확장 | 세션의 노력 수준에서 단일 패스 검토 | 독립적 검증이 있는 다중 에이전트 플릿 |

111| 기간 | 몇 초에서 몇 분 | 몇 분 | 대략 5\~10분 |111| 기간 | 몇 초에서 몇 분 | 몇 초에서 몇 분 | 대략 5\~10분 |

112| 비용 | 일반 사용량으로 계산됨 | 일반 사용량으로 계산됨 | 무료 실행, 그 후 대략 $5~$20 사용량 크레딧 |112| 비용 | 일반 사용량으로 계산됨 | 일반 사용량으로 계산됨 | 무료 실행, 그 후 대략 $5~$20 사용량 크레딧 |

114 114

voice-dictation.md +3 −2

Details

20 20

21음성 받아쓰기는 기록된 오디오를 Anthropic의 서버로 스트리밍하여 전사합니다. 오디오는 로컬에서 처리되지 않습니다. 다음 모든 항목이 필요합니다:21음성 받아쓰기는 기록된 오디오를 Anthropic의 서버로 스트리밍하여 전사합니다. 오디오는 로컬에서 처리되지 않습니다. 다음 모든 항목이 필요합니다:

22 22

23* **Claude.ai 계정**: 음성 텍스트 변환 서비스는 Claude.ai 계정으로 인증할 때만 사용 가능하며, Claude Code가 Anthropic API 키, Amazon Bedrock, Google Vertex AI 또는 Microsoft Foundry를 직접 사용하도록 구성된 경우에는 사용할 수 없습니다.23* **Claude.ai 계정**: 음성 텍스트 변환 서비스는 Claude.ai 계정으로 인증할 때만 사용 가능하며, Claude Code가 Anthropic API 키, Amazon Bedrock, Google Cloud의 Agent Platform 또는 Microsoft Foundry를 직접 사용하도록 구성된 경우에는 사용할 수 없습니다.

24* **HIPAA 규정 준수가 활성화되지 않은 조직**: 이 제한이 적용되면 `/voice`에 `Voice mode is disabled by your organization's policy`가 표시됩니다.24* **HIPAA 규정 준수가 활성화되지 않은 조직**: 이 제한이 적용되면 `/voice`에 `Voice mode is disabled by your organization's policy`가 표시됩니다.

25* **로컬 마이크**: 음성 받아쓰기는 [웹의 Claude Code](/ko/claude-code-on-the-web) 또는 SSH 세션과 같은 원격 환경에서는 작동하지 않습니다.25* **로컬 마이크**: 음성 받아쓰기는 [웹의 Claude Code](/ko/claude-code-on-the-web) 또는 SSH 세션과 같은 원격 환경에서는 작동하지 않습니다.

26* **WSL에서 Claude Code를 실행하는 경우 WSLg**: WSLg는 Windows 10 또는 11의 Microsoft Store에서 설치된 WSL2에 포함되어 있습니다. WSLg를 사용할 수 없는 경우(예: WSL1), 대신 기본 Windows에서 Claude Code를 실행하세요.26* **WSL에서 Claude Code를 실행하는 경우 WSLg**: WSLg는 Windows 10 또는 11의 Microsoft Store에서 설치된 WSL2에 포함되어 있습니다. WSLg를 사용할 수 없는 경우(예: WSL1), 대신 기본 Windows에서 Claude Code를 실행하세요.

183* **Linux에서 `No audio recording tool found`**: 네이티브 오디오 모듈을 로드할 수 없고 폴백이 설치되지 않았습니다. 오류 메시지에 표시된 명령으로 SoX를 설치하세요. 예: `sudo apt-get install sox`.183* **Linux에서 `No audio recording tool found`**: 네이티브 오디오 모듈을 로드할 수 없고 폴백이 설치되지 않았습니다. 오류 메시지에 표시된 명령으로 SoX를 설치하세요. 예: `sudo apt-get install sox`.

184* **`Voice mode requires a microphone, but SoX could not open an audio capture device`**: SoX가 설치되어 있지만 호스트에 오디오 캡처 장치가 없습니다. 예를 들어 헤드리스 서버 또는 컨테이너입니다. 마이크가 있는 머신에서 Claude Code를 실행하세요. {/* min-version: 2.1.195 */}v2.1.195부터 Linux의 Claude Code는 이 상황에서 이 메시지를 보고합니다. 이전 버전은 SoX가 이미 설치되어 있어도 설치하도록 요청했습니다.184* **`Voice mode requires a microphone, but SoX could not open an audio capture device`**: SoX가 설치되어 있지만 호스트에 오디오 캡처 장치가 없습니다. 예를 들어 헤드리스 서버 또는 컨테이너입니다. 마이크가 있는 머신에서 Claude Code를 실행하세요. {/* min-version: 2.1.195 */}v2.1.195부터 Linux의 Claude Code는 이 상황에서 이 메시지를 보고합니다. 이전 버전은 SoX가 이미 설치되어 있어도 설치하도록 요청했습니다.

185* **`Voice mode could not find a working audio recorder in WSL`**: WSLg는 ALSA 장치가 아닌 PulseAudio를 통해 오디오를 라우팅하므로 SoX는 PulseAudio 백엔드가 명시적으로 설치되어야 합니다. `sudo apt install sox libsox-fmt-pulse`를 실행하세요. `sox`만 설치하면 ALSA 백엔드가 함께 설치되는데, WSL에서는 `/dev/snd` 장치가 없기 때문에 녹음할 수 없습니다.185* **`Voice mode could not find a working audio recorder in WSL`**: WSLg는 ALSA 장치가 아닌 PulseAudio를 통해 오디오를 라우팅하므로 SoX는 PulseAudio 백엔드가 명시적으로 설치되어야 합니다. `sudo apt install sox libsox-fmt-pulse`를 실행하세요. `sox`만 설치하면 ALSA 백엔드가 함께 설치되는데, WSL에서는 `/dev/snd` 장치가 없기 때문에 녹음할 수 없습니다.

186* **`Voice input is failing repeatedly and has been paused`**: 음성 받아쓰기가 여러 번 시작 실패를 겪었고 하나가 성공할 때까지 새 세션 시도를 중단했습니다. 이는 일반적으로 이 호스트의 마이크 또는 오디오 스택이 오디오를 캡처할 수 없음을 의미합니다. 예를 들어 헤드리스 서버, 오디오 패스스루가 없는 원격 셸 또는 거부된 마이크 권한이 있습니다. 작동하는 입력 장치를 확인하고 위의 항목에서 근본 원인을 해결한 다음 음성을 다시 트리거하세요.186* **`Voice input is failing repeatedly and has been paused`**: 음성 받아쓰기가 여러 캡처 실패를 겪었고 하나가 성공할 때까지 새 세션 시도를 중단했습니다. 마이크가 시작되지 않거나 레코더가 시작되었다가 오디오를 생성하지 않고 중지되는지 여부에 관계없이 실패가 계산됩니다. 이는 일반적으로 이 호스트의 마이크 또는 오디오 스택이 오디오를 캡처할 수 없음을 의미합니다. 예를 들어 헤드리스 서버, 오디오 패스스루가 없는 원격 셸 또는 거부된 마이크 권한이 있습니다. 작동하는 입력 장치를 확인하고 위의 항목에서 근본 원인을 해결한 다음 음성을 다시 트리거하세요. {/* min-version: 2.1.202 */}v2.1.202 이전에는 시작 실패만 일시 중지로 계산되었습니다.

187* **누르고 있기 모드에서 `Space`를 누르고 있어도 아무것도 일어나지 않음**: 누르고 있는 동안 프롬프트 입력을 봅니다. 공백이 계속 누적되면 음성 받아쓰기가 꺼져 있을 가능성이 높습니다. `/voice hold`를 실행하여 활성화하세요. 1\~2개의 공백만 나타나고 그 다음 아무것도 없으면 음성 받아쓰기는 켜져 있지만 누르고 있기 감지가 트리거되지 않습니다. 누르고 있기 감지는 터미널이 키 반복 이벤트를 보내야 하므로 OS 수준에서 키 반복이 비활성화되면 누르고 있는 키를 감지할 수 없습니다. 키 반복 요구 사항을 피하려면 `/voice tap`으로 탭 모드로 전환하세요.187* **누르고 있기 모드에서 `Space`를 누르고 있어도 아무것도 일어나지 않음**: 누르고 있는 동안 프롬프트 입력을 봅니다. 공백이 계속 누적되면 음성 받아쓰기가 꺼져 있을 가능성이 높습니다. `/voice hold`를 실행하여 활성화하세요. 1\~2개의 공백만 나타나고 그 다음 아무것도 없으면 음성 받아쓰기는 켜져 있지만 누르고 있기 감지가 트리거되지 않습니다. 누르고 있기 감지는 터미널이 키 반복 이벤트를 보내야 하므로 OS 수준에서 키 반복이 비활성화되면 누르고 있는 키를 감지할 수 없습니다. 키 반복 요구 사항을 피하려면 `/voice tap`으로 탭 모드로 전환하세요.

188* **탭 모드에서 `Space`를 탭하면 녹음 대신 공백을 입력함**: 첫 번째 탭은 프롬프트 입력이 비어 있을 때만 녹음을 시작합니다. 먼저 입력을 지우거나 `/voice tap`을 실행하여 탭 모드에 있는지 확인하세요.188* **탭 모드에서 `Space`를 탭하면 녹음 대신 공백을 입력함**: 첫 번째 탭은 프롬프트 입력이 비어 있을 때만 녹음을 시작합니다. 먼저 입력을 지우거나 `/voice tap`을 실행하여 탭 모드에 있는지 확인하세요.

189* **`No audio detected from microphone`**: 녹음이 시작되었지만 침묵을 캡처했습니다. 올바른 입력 장치가 시스템 기본값으로 설정되어 있고 입력 수준이 음소거되거나 0에 가깝지 않은지 확인하세요. Windows에서는 설정 → 시스템 → 사운드 → 입력을 열고 마이크를 선택하세요. macOS에서는 시스템 설정 → 사운드 → 입력을 열어보세요.189* **`No audio detected from microphone`**: 녹음이 시작되었지만 침묵을 캡처했습니다. 올바른 입력 장치가 시스템 기본값으로 설정되어 있고 입력 수준이 음소거되거나 0에 가깝지 않은지 확인하세요. Windows에서는 설정 → 시스템 → 사운드 → 입력을 열고 마이크를 선택하세요. macOS에서는 시스템 설정 → 사운드 → 입력을 열어보세요.

190* **`Voice connection failed`**: 연결이 실패했기 때문에 녹음이 전사 서비스에 도달하지 않았습니다. 네트워크를 확인하고 다시 시도하세요. {/* min-version: 2.1.200 */}오디오를 캡처하지 않는 녹음은 이 메시지 대신 `No audio detected from microphone`을 보고합니다. v2.1.200 이전에는 침묵한 마이크가 연결 실패를 보고할 수 있었으며, 이는 실제 문제가 입력 장치일 때 네트워크 문제를 시사했습니다.

190* **`No speech detected`**: 오디오가 전사 서비스에 도달했지만 단어가 인식되지 않았습니다. 마이크에 더 가깝게 말하고, 배경 소음을 줄이고, [받아쓰기 언어](#change-the-dictation-language)가 말하는 언어와 일치하는지 확인하세요.191* **`No speech detected`**: 오디오가 전사 서비스에 도달했지만 단어가 인식되지 않았습니다. 마이크에 더 가깝게 말하고, 배경 소음을 줄이고, [받아쓰기 언어](#change-the-dictation-language)가 말하는 언어와 일치하는지 확인하세요.

191* **전사가 왜곡되었거나 잘못된 언어임**: 받아쓰기는 기본적으로 영어입니다. 다른 언어로 받아쓰기하는 경우 먼저 `/config`에서 설정하세요. [받아쓰기 언어 변경](#change-the-dictation-language)을 참조하세요.192* **전사가 왜곡되었거나 잘못된 언어임**: 받아쓰기는 기본적으로 영어입니다. 다른 언어로 받아쓰기하는 경우 먼저 `/config`에서 설정하세요. [받아쓰기 언어 변경](#change-the-dictation-language)을 참조하세요.

192 193

vs-code.md +19 −15

Details

19설치하기 전에 다음을 확인하십시오:19설치하기 전에 다음을 확인하십시오:

20 20

21* VS Code 1.98.0 이상21* VS Code 1.98.0 이상

22* Anthropic 계정: 모든 유료 Claude 구독(Pro, Max, Team 또는 Enterprise) 또는 Claude Console 계정이 작동하며, API 키가 필요하지 않습니다. 확장 프로그램을 처음 열 때 이 계정으로 [로그인](/ko/authentication#log-in-to-claude-code)합니다. Amazon Bedrock이나 Google Vertex AI와 같은 타사 공급자를 통해 Claude에 액세스하는 경우 설정 지침은 [타사 공급자 사용](#use-third-party-providers)을 참조하십시오.22* Anthropic 계정: 모든 유료 Claude 구독(Pro, Max, Team 또는 Enterprise) 또는 Claude Console 계정이 작동하며, API 키가 필요하지 않습니다. 확장 프로그램을 처음 열 때 이 계정으로 [로그인](/ko/authentication#log-in-to-claude-code)합니다. Amazon Bedrock이나 Google Cloud의 Agent Platform과 같은 타사 공급자를 통해 Claude에 액세스하는 경우 설정 지침은 [타사 공급자 사용](#use-third-party-providers)을 참조하십시오.

23 23

24<Tip>24<Tip>

25 확장 프로그램에는 채팅 패널용 CLI(명령줄 인터페이스)의 자체 복사본이 포함되어 있습니다. VS Code의 통합 터미널에서 `claude`를 실행하려면 [독립 실행형 CLI 설치](/ko/setup)도 필요합니다. 자세한 내용은 [VS Code 확장 프로그램 vs. Claude Code CLI](#vs-code-extension-vs-claude-code-cli)를 참조하십시오.25 확장 프로그램에는 채팅 패널용 CLI(명령줄 인터페이스)의 자체 복사본이 포함되어 있습니다. VS Code의 통합 터미널에서 `claude`를 실행하려면 [독립 실행형 CLI 설치](/ko/setup)도 필요합니다. 자세한 내용은 [VS Code 확장 프로그램 vs. Claude Code CLI](#vs-code-extension-vs-claude-code-cli)를 참조하십시오.

102 102

103프롬프트 상자는 여러 기능을 지원합니다:103프롬프트 상자는 여러 기능을 지원합니다:

104 104

105* **권한 모드**: 프롬프트 상자 하단의 모드 표시기를 클릭하여 모드를 전환합니다. 일반 모드에서 Claude는 각 작업 전에 권한을 요청합니다. Plan Mode에서 Claude는 수행할 작업을 설명하고 변경을 수행하기 전에 승인을 기다립니다. VS Code는 자동으로 계획을 전체 markdown 문서로 열어서 Claude가 시작하기 전에 피드백을 제공하기 위해 인라인 주석을 추가할 수 있습니다. 자동 수락 모드에서 Claude는 요청 없이 편집을 수행합니다. VS Code 설정의 `claudeCode.initialPermissionMode`에서 기본값을 설정합니다.105* **권한 모드**: 프롬프트 상자 하단의 모드 표시기를 클릭하여 모드를 전환하거나 VS Code 설정의 `claudeCode.initialPermissionMode`에서 기본값을 설정합니다. 표시기가 제공하는 모든 모드는 [권한 모드](/ko/permission-modes#switch-permission-modes)를 참조하십시오.

106* **명령 메뉴**: `/`를 클릭하거나 입력하여 명령 메뉴를 엽니다. 옵션에는 파일 첨부, 모델 전환, 확장 사고 토글, 계획 사용량 보기(`/usage`) 및 [Remote Control](/ko/remote-control) 세션 시작(`/remote-control`)이 포함됩니다. 사용자 정의 섹션은 MCP 서버, hooks, 메모리, 권한 및 플러그인에 대한 액세스를 제공합니다. 터미널 아이콘이 있는 항목은 통합 터미널에서 열립니다.106 * **Manual**: Claude는 각 작업 전에 권한을 요청합니다.

107 * **Plan**: Claude는 수행할 작업을 설명하고 변경을 수행하기 전에 승인을 기다립니다. VS Code는 자동으로 계획을 전체 Markdown 문서로 열어서 Claude가 시작하기 전에 피드백을 제공하기 위해 인라인 주석을 추가할 수 있습니다.

108 * **Edit automatically**: Claude는 요청 없이 편집을 수행합니다.

109* **명령 메뉴**: `/`를 클릭하거나 입력하여 명령 메뉴를 엽니다. 옵션에는 파일 첨부, 모델 전환, 확장 사고 토글, 계획 사용량 보기(`/usage`) 및 [Remote Control](/ko/remote-control) 세션 시작(`/remote-control`)이 포함됩니다. Customize 섹션은 MCP 서버, hooks, 메모리, 권한 및 플러그인에 대한 액세스를 제공합니다. 터미널 아이콘이 있는 항목은 통합 터미널에서 열립니다.

110 * {/* min-version: 2.1.203 */}Settings 섹션에는 **Enable Remote Control for all sessions**이 포함되어 있으며, 이는 [`remoteControlAtStartup`](/ko/settings#available-settings)을 설정하므로 [모든 새로운 대화형 세션이 Remote Control에 자동으로 연결됩니다](/ko/remote-control#enable-remote-control-for-all-sessions). Claude Code v2.1.203 이상이 필요합니다.

107* **컨텍스트 표시기**: 프롬프트 상자는 Claude의 context window를 얼마나 사용하고 있는지 표시합니다. Claude는 필요할 때 자동으로 압축하거나 `/compact`를 수동으로 실행할 수 있습니다.111* **컨텍스트 표시기**: 프롬프트 상자는 Claude의 context window를 얼마나 사용하고 있는지 표시합니다. Claude는 필요할 때 자동으로 압축하거나 `/compact`를 수동으로 실행할 수 있습니다.

108* **확장 사고**: Claude가 복잡한 문제를 추론하는 데 더 많은 시간을 소비할 수 있습니다. 명령 메뉴(`/`)를 통해 켭니다. Claude의 추론은 대화에 축소된 블록으로 나타납니다: 블록을 클릭하여 읽거나 `Ctrl+O`를 눌러 세션의 모든 사고 블록을 확장하거나 축소합니다. 자세한 내용은 [확장 사고](/ko/model-config#extended-thinking)를 참조하십시오.112* **확장 사고**: Claude가 복잡한 문제를 추론하는 데 더 많은 시간을 소비할 수 있습니다. 명령 메뉴(`/`)를 통해 켭니다. Claude의 추론은 대화에 축소된 블록으로 나타납니다: 블록을 클릭하여 읽거나 `Ctrl+O`를 눌러 세션의 모든 사고 블록을 확장하거나 축소합니다. 자세한 내용은 [확장 사고](/ko/model-config#extended-thinking)를 참조하십시오.

109* **여러 줄 입력**: `Shift+Enter`를 눌러 보내지 않고 새 줄을 추가합니다. 이것은 질문 대화의 "기타" 자유 텍스트 입력에서도 작동합니다.113* **여러 줄 입력**: `Shift+Enter`를 눌러 보내지 않고 새 줄을 추가합니다. 이것은 질문 대화의 "Other" 자유 텍스트 입력에서도 작동합니다.

110 114

111<h3 id="reference-files-and-folders">115<h3 id="reference-files-and-folders">

112 파일 및 폴더 참조116 파일 및 폴더 참조

129 과거 대화 재개133 과거 대화 재개

130</h3>134</h3>

131 135

132Claude Code 패널 상단의 **세션 기록** 버튼을 클릭하여 대화 기록에 액세스합니다. 키워드로 검색하거나 시간별로 찾아볼 수 있습니다(오늘, 어제, 지난 7일 등). 대화를 클릭하여 전체 메시지 기록으로 재개합니다. 새 세션은 첫 번째 메시지를 기반으로 AI가 생성한 제목을 받습니다. 세션 위에 마우스를 올려 이름 바꾸기 및 제거 작업을 표시합니다: 설명적인 제목으로 이름을 바꾸거나 목록에서 삭제하려면 제거합니다. 세션 재개에 대한 자세한 내용은 [세션 관리](/ko/sessions)를 참조하십시오.136Claude Code 패널 상단의 **Session history** 버튼을 클릭하여 대화 기록에 액세스합니다. 키워드로 검색하거나 시간별로 찾아볼 수 있습니다(Today, Yesterday, Last 7 days 등). 대화를 클릭하여 전체 메시지 기록으로 재개합니다. 새 세션은 첫 번째 메시지를 기반으로 AI가 생성한 제목을 받습니다. 세션 위에 마우스를 올려 이름 바꾸기 및 제거 작업을 표시합니다: 설명적인 제목으로 이름을 바꾸거나 목록에서 삭제하려면 제거합니다. 세션 재개에 대한 자세한 내용은 [세션 관리](/ko/sessions)를 참조하십시오.

133 137

134<h3 id="resume-cloud-sessions-from-claude-ai">138<h3 id="resume-cloud-sessions-from-claude-ai">

135 Claude.ai에서 원격 세션 재개139 Claude.ai에서 원격 세션 재개

139 143

140<Steps>144<Steps>

141 <Step title="세션 기록 열기">145 <Step title="세션 기록 열기">

142 Claude Code 패널 상단의 **세션 기록** 버튼을 클릭합니다.146 Claude Code 패널 상단의 **Session history** 버튼을 클릭합니다.

143 </Step>147 </Step>

144 148

145 <Step title="원격 탭 선택">149 <Step title="Remote 탭 선택">

146 대화 상자에는 로컬 및 원격의 두 탭이 표시됩니다. **원격**을 클릭하여 claude.ai의 세션을 봅니다.150 대화 상자에는 Local 및 Remote의 두 탭이 표시됩니다. **Remote**를 클릭하여 claude.ai의 세션을 봅니다.

147 </Step>151 </Step>

148 152

149 <Step title="재개할 세션 선택">153 <Step title="재개할 세션 선택">

159 계정 및 사용량 확인163 계정 및 사용량 확인

160</h3>164</h3>

161 165

162명령 메뉴에서 `/usage`를 실행하여 계정 및 사용량 대화 상자를 엽니다. 로그인한 계정, 요금제 및 현재 세션과 주간 사용량 막대를 표시하며 각 제한이 재설정될 때까지의 시간을 보여줍니다.166명령 메뉴에서 `/usage`를 실행하여 Account & usage 대화 상자를 엽니다. 로그인한 계정, 요금제 및 현재 세션과 주간 사용량 막대를 표시하며 각 제한이 재설정될 때까지의 시간을 보여줍니다.

163 167

164대화 상자는 또한 요금제 제한에 기여하는 것을 분석합니다. 캐시 미스, 긴 컨텍스트, 서브에이전트 집약적 또는 고도로 병렬 세션 등 최근 사용량의 10% 이상을 차지하는 동작에 플래그를 지정하며, 각각에 대해 이를 줄이기 위한 팁을 제공합니다. 속성 테이블은 각 스킬, 서브에이전트, 플러그인 및 MCP 서버에서 얼마나 많은 사용량이 발생했는지 보여줍니다. Claude Code v2.1.174 이상이 필요합니다.168대화 상자는 또한 요금제 제한에 기여하는 것을 분석합니다. 캐시 미스, 긴 컨텍스트, 서브에이전트 집약적 또는 고도로 병렬 세션 등 최근 사용량의 10% 이상을 차지하는 동작에 플래그를 지정하며, 각각에 대해 이를 줄이기 위한 팁을 제공합니다. Attribution 테이블은 각 skill, subagent, plugin 및 MCP 서버에서 얼마나 많은 사용량이 발생했는지 보여줍니다. Claude Code v2.1.174 이상이 필요합니다.

165 169

166일일 및 주간 토글을 사용하여 지난 24시간과 지난 7일 사이를 전환합니다. 수치는 대략적이며 이 컴퓨터의 로컬 세션에서 계산되므로 다른 기기 또는 claude.ai의 사용량은 포함되지 않습니다. 사용량 추적 및 감소에 대한 자세한 내용은 [비용 추적](/ko/costs#track-your-costs)을 참조하십시오.170Day 및 Week 토글을 사용하여 지난 24시간과 지난 7일 사이를 전환합니다. 수치는 대략적이며 이 컴퓨터의 로컬 세션에서 계산되므로 다른 기기 또는 claude.ai의 사용량은 포함되지 않습니다. 사용량 추적 및 감소에 대한 자세한 내용은 [비용 추적](/ko/costs#track-your-costs)을 참조하십시오.

167 171

168<h2 id="customize-your-workflow">172<h2 id="customize-your-workflow">

169 워크플로우 사용자 정의173 워크플로우 사용자 정의

356</h3>360</h3>

357 361

358| 설정 | 기본값 | 설명 |362| 설정 | 기본값 | 설명 |

359| ----------------------------------- | --------- | -------------------------------------------------------------------------------------------------------------------------------- |363| ----------------------------------- | --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

361| `initialPermissionMode` | `default` | 새 대화에 대한 승인 프롬프트 제어: `default`, `plan`, `acceptEdits` 또는 `bypassPermissions`. [권한 모드](/ko/permission-modes)를 참조하십시오. |365| `initialPermissionMode` | `default` | 새 대화에 대한 승인 프롬프트 제어: `default`, `plan`, `acceptEdits` 또는 `bypassPermissions`. {/* min-version: 2.1.200 */}`manual`은 `default`의 별칭이며 모드 표시기에서 **Manual**로 표시된 모드를 선택합니다. Claude Code v2.1.200 이상이 필요합니다. [권한 모드](/ko/permission-modes)를 참조하십시오. |

479 타사 공급자 사용483 타사 공급자 사용

480</h2>484</h2>

481 485

482기본적으로 Claude Code는 Anthropic의 API에 직접 연결됩니다. 조직에서 Amazon Bedrock, Google Vertex AI 또는 Microsoft Foundry를 사용하여 Claude에 액세스하는 경우 대신 공급자를 사용하도록 확장 프로그램을 구성합니다:486기본적으로 Claude Code는 Anthropic의 API에 직접 연결됩니다. 조직에서 Amazon Bedrock, Google Cloud의 Agent Platform 또는 Microsoft Foundry를 사용하여 Claude에 액세스하는 경우 대신 공급자를 사용하도록 확장 프로그램을 구성합니다:

483 487

484<Steps>488<Steps>

485 <Step title="로그인 프롬프트 비활성화">489 <Step title="로그인 프롬프트 비활성화">

492 공급자에 대한 설정 가이드를 따릅니다:496 공급자에 대한 설정 가이드를 따릅니다:

493 497

494 * [Amazon Bedrock의 Claude Code](/ko/amazon-bedrock)498 * [Amazon Bedrock의 Claude Code](/ko/amazon-bedrock)

495 * [Google Vertex AI의 Claude Code](/ko/google-vertex-ai)499 * [Google Cloud의 Agent Platform의 Claude Code](/ko/google-vertex-ai)

496 * [Microsoft Foundry의 Claude Code](/ko/microsoft-foundry)500 * [Microsoft Foundry의 Claude Code](/ko/microsoft-foundry)

497 501

498 이 가이드는 `~/.claude/settings.json`에서 공급자를 구성하는 방법을 다루며, 이는 VS Code 확장 프로그램과 CLI 간에 설정이 공유되도록 합니다.502 이 가이드는 `~/.claude/settings.json`에서 공급자를 구성하는 방법을 다루며, 이는 VS Code 확장 프로그램과 CLI 간에 설정이 공유되도록 합니다.

web-quickstart.md +7 −7

Details

43Claude Code는 모든 곳에서 동일하게 작동합니다. 변경되는 것은 코드가 실행되는 위치와 로컬 구성을 사용할 수 있는지 여부입니다. Desktop 앱은 로컬 및 클라우드 세션을 모두 제공하므로, 아래의 답변은 선택한 것에 따라 달라집니다:43Claude Code는 모든 곳에서 동일하게 작동합니다. 변경되는 것은 코드가 실행되는 위치와 로컬 구성을 사용할 수 있는지 여부입니다. Desktop 앱은 로컬 및 클라우드 세션을 모두 제공하므로, 아래의 답변은 선택한 것에 따라 달라집니다:

44 44

45| | 웹에서 | Remote Control | Terminal CLI | Desktop 앱 |45| | 웹에서 | Remote Control | Terminal CLI | Desktop 앱 |

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

49| **로컬 구성 사용** | 아니오, 저장소만 | 예 | 예 | 로컬의 경우 예, 클라우드의 경우 아니오 |49| **로컬 구성 사용** | 아니오, 저장소만 | 예 | 예 | 로컬의 경우 예, 클라우드의 경우 아니오 |

50| **GitHub 필요** | 예, 또는 `--remote`를 통해 [로컬 저장소 번들](/ko/claude-code-on-the-web#send-local-repositories-without-github) | 아니오 | 아니오 | 클라우드 세션의 경우만 |50| **GitHub 필요** | 예, 또는 `--cloud`를 통해 [로컬 저장소 번들](/ko/claude-code-on-the-web#send-local-repositories-without-github) | 아니오 | 아니오 | 클라우드 세션의 경우만 |

51| **연결 해제 시 계속 실행** | 예 | 터미널이 열려 있는 동안 | 아니오 | 세션 유형에 따라 다름 |51| **연결 해제 시 계속 실행** | 예 | 터미널이 열려 있는 동안 | 아니오 | 세션 유형에 따라 다름 |

54 54

55[터미널 빠른 시작](/ko/quickstart), [Desktop 앱](/ko/desktop) 또는 [Remote Control](/ko/remote-control) 문서를 참조하여 설정합니다.55[터미널 빠른 시작](/ko/quickstart), [Desktop 앱](/ko/desktop) 또는 [Remote Control](/ko/remote-control) 문서를 참조하여 설정합니다.

113 /web-setup113 /web-setup

114 ```114 ```

115 115

116 이는 `gh` 토큰을 Claude 계정과 동기화합니다. 아직 클라우드 환경이 없는 경우, `/web-setup`은 Trusted 네트워크 접근 및 설정 스크립트 없이 환경을 생성합니다. 나중에 [환경을 편집하거나 변수를 추가](/ko/claude-code-on-the-web#configure-your-environment)할 수 있습니다. `/web-setup`이 완료되면, 터미널에서 [`--remote`](/ko/claude-code-on-the-web#from-terminal-to-web)를 사용하여 클라우드 세션을 시작하거나 [`/schedule`](/ko/routines)을 사용하여 반복 작업을 설정할 수 있습니다.116 이는 `gh` 토큰을 Claude 계정과 동기화합니다. 아직 클라우드 환경이 없는 경우, `/web-setup`은 Trusted 네트워크 접근 및 설정 스크립트 없이 환경을 생성합니다. 나중에 [환경을 편집하거나 변수를 추가](/ko/claude-code-on-the-web#configure-your-environment)할 수 있습니다. `/web-setup`이 완료되면, 터미널에서 [`--cloud`](/ko/claude-code-on-the-web#from-terminal-to-web)를 사용하여 클라우드 세션을 시작하거나 [`/schedule`](/ko/routines)을 사용하여 반복 작업을 설정할 수 있습니다.

117 </Step>117 </Step>

118</Steps>118</Steps>

119 119

129 </Step>129 </Step>

130 130

131 <Step title="권한 모드 선택">131 <Step title="권한 모드 선택">

132 입력 옆의 모드 드롭다운은 기본값으로 **편집 자동 수락**이며, Claude는 승인을 기다리지 않고 변경 사항을 만들고 브랜치를 푸시합니다. Claude가 접근 방식을 제안하고 파일을 편집하기 전에 승인을 기다리도록 하려면 **Plan Mode**로 전환합니다. 클라우드 세션은 Ask 권한 또는 Bypass 권한을 제공하지 않습니다. 전체 목록은 [권한 모드](/ko/permission-modes)를 참조합니다.132 입력 옆의 모드 드롭다운은 기본값으로 **편집 자동 수락**이며, Claude는 승인을 기다리지 않고 변경 사항을 만들고 브랜치를 푸시합니다. Claude가 접근 방식을 제안하고 파일을 편집하기 전에 승인을 기다리도록 하려면 **Plan Mode**로 전환합니다. 클라우드 세션은 Manual 또는 Bypass 권한을 제공하지 않습니다. 각 권한 모드가 허용하는 사항에 대해서는 [권한 모드의 전체 목록](/ko/permission-modes#available-modes)을 참조합니다.

133 </Step>133 </Step>

134 134

135 <Step title="작업 설명 및 제출">135 <Step title="작업 설명 및 제출">

216 216

217Claude Code 내부에 입력했는데 명령 메뉴에 `No commands match "/web-setup"`이 표시되거나 제출하면 `Unknown command: /web-setup`이 반환되면, 요구 사항이 충족되지 않아 명령이 숨겨져 있습니다. 원인은 보통 CLI가 v2.1.80보다 오래되었거나 API 키 또는 타사 공급자 대신 claude.ai 구독으로 인증되었기 때문입니다. `claude update`를 실행한 다음, `/login`을 실행하여 claude.ai 계정으로 로그인합니다.217Claude Code 내부에 입력했는데 명령 메뉴에 `No commands match "/web-setup"`이 표시되거나 제출하면 `Unknown command: /web-setup`이 반환되면, 요구 사항이 충족되지 않아 명령이 숨겨져 있습니다. 원인은 보통 CLI가 v2.1.80보다 오래되었거나 API 키 또는 타사 공급자 대신 claude.ai 구독으로 인증되었기 때문입니다. `claude update`를 실행한 다음, `/login`을 실행하여 claude.ai 계정으로 로그인합니다.

218 218

219<h3 id="could-not-create-a-cloud-environment-or-no-cloud-environment-available-when-using-remote-or-ultraplan">219<h3 id="could-not-create-a-cloud-environment-or-no-cloud-environment-available-when-using-cloud-or-ultraplan">

220 `--remote` 또는 ultraplan 사용 시 "클라우드 환경을 생성할 수 없음" 또는 "사용 가능한 클라우드 환경 없음"220 `--cloud` 또는 ultraplan 사용 시 "클라우드 환경을 생성할 수 없음" 또는 "사용 가능한 클라우드 환경 없음"

221</h3>221</h3>

222 222

223원격 세션 기능은 아직 없는 경우 기본 클라우드 환경을 자동으로 생성합니다. "클라우드 환경을 생성할 수 없음"이 표시되면, 자동 생성이 실패했습니다. {/* max-version: 2.1.100 */}"사용 가능한 클라우드 환경 없음"이 표시되면, CLI가 자동 생성보다 앞서 있습니다. 어느 경우든, Claude Code CLI에서 `/web-setup`을 실행하여 수동으로 생성하거나, [claude.ai/code](https://claude.ai/code)를 방문하고 위의 **환경 생성** 단계를 따릅니다.223원격 세션 기능은 아직 없는 경우 기본 클라우드 환경을 자동으로 생성합니다. "클라우드 환경을 생성할 수 없음"이 표시되면, 자동 생성이 실패했습니다. {/* max-version: 2.1.100 */}"사용 가능한 클라우드 환경 없음"이 표시되면, CLI가 자동 생성보다 앞서 있습니다. 어느 경우든, Claude Code CLI에서 `/web-setup`을 실행하여 수동으로 생성하거나, [claude.ai/code](https://claude.ai/code)를 방문하고 위의 **환경 생성** 단계를 따릅니다.

whats-new.md +1 −1

Details

33</Update>33</Update>

34 34

35<Update label="Week 23" description="2026년 6월 1–5일" tags={["v2.1.158–v2.1.165"]}>35<Update label="Week 23" description="2026년 6월 1–5일" tags={["v2.1.158–v2.1.165"]}>

36 **Bedrock, Vertex, 그리고 Foundry의 Auto mode**: auto mode는 이제 Opus 4.7 및 Opus 4.8에 대해 타사 제공자에서 사용 가능하며, 권한 프롬프트를 백그라운드 안전 검사로 대체합니다.36 **Amazon Bedrock, Google Cloud의 Agent Platform, 그리고 Microsoft Foundry의 Auto mode**: auto mode는 이제 Opus 4.7 및 Opus 4.8에 대해 타사 제공자에서 사용 가능하며, 권한 프롬프트를 백그라운드 안전 검사로 대체합니다.

37 37

38 이번 주의 다른 기능들: **더 안전한 자동 편집**은 `acceptEdits` 모드에서 코드를 실행할 수 있는 파일을 작성하기 전에 프롬프트를 표시합니다; \*\*`/plugin list`\*\*는 설치된 플러그인을 인라인으로 출력합니다; 그리고 **version requirements**는 관리되는 배포에서 승인된 Claude Code 버전 범위를 요구할 수 있습니다.38 이번 주의 다른 기능들: **더 안전한 자동 편집**은 `acceptEdits` 모드에서 코드를 실행할 수 있는 파일을 작성하기 전에 프롬프트를 표시합니다; \*\*`/plugin list`\*\*는 설치된 플러그인을 인라인으로 출력합니다; 그리고 **version requirements**는 관리되는 배포에서 승인된 Claude Code 버전 범위를 요구할 수 있습니다.

39 39

whats-new/2026-w15.md +2 −2

Details

102 102

103 <div className="digest-wins-grid">103 <div className="digest-wins-grid">

104 <div>포커스 보기: 깜박임 없는 모드에서 <code>Ctrl+O</code>를 눌러 보기를 마지막 프롬프트, 한 줄 도구 요약(diffstats 포함) 및 Claude의 최종 응답으로 축소합니다</div>104 <div>포커스 보기: 깜박임 없는 모드에서 <code>Ctrl+O</code>를 눌러 보기를 마지막 프롬프트, 한 줄 도구 요약(diffstats 포함) 및 Claude의 최종 응답으로 축소합니다</div>

105 <div>로그인 화면의 가이드 <a href="/ko/docs/amazon-bedrock">Bedrock</a> 및 <a href="/ko/docs/google-vertex-ai">Vertex AI</a> 설정 마법사: 단계별 인증, 지역, 자격 증명 확인 및 모델 고정을 위해 "3rd-party platform"을 선택합니다</div>105 <div>로그인 화면의 가이드 <a href="/ko/docs/amazon-bedrock">Amazon Bedrock</a> 및 <a href="/ko/docs/google-vertex-ai">Google Cloud의 Agent Platform</a> 설정 마법사: 단계별 인증, 지역, 자격 증명 확인 및 모델 고정을 위해 "3rd-party platform"을 선택합니다</div>

106 <div><code>/agents</code>는 탭 레이아웃을 가집니다. Running 탭은 <code>● N running</code> 카운트가 있는 라이브 서브에이전트를 표시하고, Library 탭에서 Run agent 및 View running instance 작업을 수행합니다</div>106 <div><code>/agents</code>는 탭 레이아웃을 가집니다. Running 탭은 <code>● N running</code> 카운트가 있는 라이브 서브에이전트를 표시하고, Library 탭에서 Run agent 및 View running instance 작업을 수행합니다</div>

107 <div>기본 노력 수준은 이제 API 키, Bedrock, Vertex, Foundry, Team 및 Enterprise 사용자의 경우 <code>high</code>입니다(<code>/effort</code>로 제어)</div>107 <div>기본 노력 수준은 이제 API 키, Amazon Bedrock, Google Cloud의 Agent Platform, Microsoft Foundry, Team 및 Enterprise 사용자의 경우 <code>high</code>입니다(<code>/effort</code>로 제어)</div>

108 <div><code>/cost</code>는 구독 사용자를 위한 모델별 및 캐시 히트 분석을 표시합니다</div>108 <div><code>/cost</code>는 구독 사용자를 위한 모델별 및 캐시 히트 분석을 표시합니다</div>

109 <div><code>/release-notes</code>는 이제 대화형 버전 선택기입니다</div>109 <div><code>/release-notes</code>는 이제 대화형 버전 선택기입니다</div>

110 <div>상태 줄: 새로운 <code>refreshInterval</code> 설정은 N초마다 명령을 다시 실행하고, JSON 입력에서 <code>workspace.git\_worktree</code>를 사용합니다</div>110 <div>상태 줄: 새로운 <code>refreshInterval</code> 설정은 N초마다 명령을 다시 실행하고, JSON 입력에서 <code>workspace.git\_worktree</code>를 사용합니다</div>

whats-new/2026-w16.md +1 −1

Details

123 <div><code>/fewer-permission-prompts</code>는 트랜스크립트에서 일반적인 읽기 전용 Bash 및 MCP 호출을 스캔하고 <code>.claude/settings.json</code>에 대한 허용 목록을 제안합니다</div>123 <div><code>/fewer-permission-prompts</code>는 트랜스크립트에서 일반적인 읽기 전용 Bash 및 MCP 호출을 스캔하고 <code>.claude/settings.json</code>에 대한 허용 목록을 제안합니다</div>

124 <div>Claude는 이제 스킬 도구를 통해 <code>/init</code>, <code>/review</code>, <code>/security-review</code>와 같은 기본 제공 명령을 발견하고 실행할 수 있습니다</div>124 <div>Claude는 이제 스킬 도구를 통해 <code>/init</code>, <code>/review</code>, <code>/security-review</code>와 같은 기본 제공 명령을 발견하고 실행할 수 있습니다</div>

125 <div><code>PreCompact</code> 훅은 코드 2로 종료하거나 <code>{"{"}"decision":"block"{"}"}</code>를 반환하여 압축을 차단할 수 있습니다</div>125 <div><code>PreCompact</code> 훅은 코드 2로 종료하거나 <code>{"{"}"decision":"block"{"}"}</code>를 반환하여 압축을 차단할 수 있습니다</div>

126 <div><code>ENABLE\_PROMPT\_CACHING\_1H</code>는 API 키, Bedrock, Vertex 및 Foundry 사용자를 1시간 프롬프트 캐시 TTL로 옵트인합니다</div>126 <div><code>ENABLE\_PROMPT\_CACHING\_1H</code>는 API 키, Amazon Bedrock, Google Cloud의 Agent Platform, Microsoft Foundry 사용자를 1시간 프롬프트 캐시 TTL로 옵트인합니다</div>

127 <div><code>sandbox.network.deniedDomains</code> 설정은 더 광범위한 <code>allowedDomains</code> 와일드카드에서 특정 도메인을 제외합니다</div>127 <div><code>sandbox.network.deniedDomains</code> 설정은 더 광범위한 <code>allowedDomains</code> 와일드카드에서 특정 도메인을 제외합니다</div>

128 <div><code>/undo</code>는 이제 <code>/rewind</code>의 별칭이며, <code>/proactive</code>는 <code>/loop</code>의 별칭입니다</div>128 <div><code>/undo</code>는 이제 <code>/rewind</code>의 별칭이며, <code>/proactive</code>는 <code>/loop</code>의 별칭입니다</div>

129 <div>강화된 Bash 권한: 거부 규칙은 이제 <code>env</code>/<code>sudo</code>/<code>watch</code> 래퍼를 통해 일치하며, <code>Bash(find:\*)</code> 허용 규칙은 더 이상 <code>-exec</code> 또는 <code>-delete</code>를 자동으로 승인하지 않습니다</div>129 <div>강화된 Bash 권한: 거부 규칙은 이제 <code>env</code>/<code>sudo</code>/<code>watch</code> 래퍼를 통해 일치하며, <code>Bash(find:\*)</code> 허용 규칙은 더 이상 <code>-exec</code> 또는 <code>-delete</code>를 자동으로 승인하지 않습니다</div>

whats-new/2026-w18.md +2 −2

Details

103 <div>`--dangerously-skip-permissions`은 이제 `.claude/`, `.git/`, `.vscode/`, 셸 설정 파일 및 기타 이전에 보호된 경로에 대한 쓰기 프롬프트를 우회하며, 치명적인 제거 명령은 안전망으로 계속 프롬프트합니다</div>103 <div>`--dangerously-skip-permissions`은 이제 `.claude/`, `.git/`, `.vscode/`, 셸 설정 파일 및 기타 이전에 보호된 경로에 대한 쓰기 프롬프트를 우회하며, 치명적인 제거 명령은 안전망으로 계속 프롬프트합니다</div>

104 <div>`/model` 선택기는 `ANTHROPIC_BASE_URL`이 Anthropic 호환 게이트웨이를 가리킬 때 게이트웨이의 `/v1/models` 엔드포인트에서 모델을 나열할 수 있습니다. v2.1.129 이후 `CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY=1`로 옵트인하세요</div>104 <div>`/model` 선택기는 `ANTHROPIC_BASE_URL`이 Anthropic 호환 게이트웨이를 가리킬 때 게이트웨이의 `/v1/models` 엔드포인트에서 모델을 나열할 수 있습니다. v2.1.129 이후 `CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY=1`로 옵트인하세요</div>

105 <div>시작 중에 일시적 오류가 발생한 MCP 서버는 이제 연결 해제 상태로 유지되지 않고 최대 3회까지 자동으로 재시도합니다</div>105 <div>시작 중에 일시적 오류가 발생한 MCP 서버는 이제 연결 해제 상태로 유지되지 않고 최대 3회까지 자동으로 재시도합니다</div>

106 <div>`ANTHROPIC_BEDROCK_SERVICE_TIER`는 Bedrock 서비스 계층을 선택합니다: `default`, `flex` 또는 `priority`</div>106 <div>`ANTHROPIC_BEDROCK_SERVICE_TIER`는 Amazon Bedrock 서비스 계층을 선택합니다: `default`, `flex` 또는 `priority`</div>

107 <div>`/terminal-setup`은 iTerm2의 클립보드 액세스 설정을 활성화하여 `/copy`가 작동하도록 합니다(tmux 포함)</div>107 <div>`/terminal-setup`은 iTerm2의 클립보드 액세스 설정을 활성화하여 `/copy`가 작동하도록 합니다(tmux 포함)</div>

108 <div>Vertex AI는 이제 X.509 인증서 기반 Workload Identity Federation(mTLS ADC)을 지원합니다</div>108 <div>Google Cloud의 Agent Platform은 이제 X.509 인증서 기반 Workload Identity Federation(mTLS ADC)을 지원합니다</div>

109 <div>중요한 메모리 누수 수정: 이미지가 많은 세션, 큰 트랜스크립트 히스토리에서의 `/usage`, 진행 이벤트 없는 장시간 실행 도구</div>109 <div>중요한 메모리 누수 수정: 이미지가 많은 세션, 큰 트랜스크립트 히스토리에서의 `/usage`, 진행 이벤트 없는 장시간 실행 도구</div>

110 </div>110 </div>

111</div>111</div>

whats-new/2026-w21.md +1 −1

Details

37 <div>새로운 <a href="/ko/code-review"><code>/code-review</code></a> 명령은 <code>/code-review high</code>와 같은 선택한 노력 수준에서 정확성 버그를 보고하며, <code>--comment</code>는 결과를 인라인 GitHub PR 댓글로 게시합니다. <code>/simplify</code>는 별도의 정리 전용 검토로 유지됩니다.</div>37 <div>새로운 <a href="/ko/code-review"><code>/code-review</code></a> 명령은 <code>/code-review high</code>와 같은 선택한 노력 수준에서 정확성 버그를 보고하며, <code>--comment</code>는 결과를 인라인 GitHub PR 댓글로 게시합니다. <code>/simplify</code>는 별도의 정리 전용 검토로 유지됩니다.</div>

38 <div>백그라운드 세션은 이제 <code>/resume</code>에 대화형 세션과 함께 나타나며 <code>bg</code>로 표시되고, <code>claude agents</code>에서 <code>Ctrl+T</code>로 고정된 세션은 유휴 상태일 때도 유지됩니다</div>38 <div>백그라운드 세션은 이제 <code>/resume</code>에 대화형 세션과 함께 나타나며 <code>bg</code>로 표시되고, <code>claude agents</code>에서 <code>Ctrl+T</code>로 고정된 세션은 유휴 상태일 때도 유지됩니다</div>

39 <div><code>claude agents --json</code>은 상태 표시줄 및 세션 선택기와 같은 스크립팅을 위해 라이브 세션을 JSON으로 나열합니다</div>39 <div><code>claude agents --json</code>은 상태 표시줄 및 세션 선택기와 같은 스크립팅을 위해 라이브 세션을 JSON으로 나열합니다</div>

40 <div>PowerShell 도구는 이제 Bedrock, Vertex 및 Foundry 사용자를 위해 Windows에서 기본적으로 활성화되며, <code>CLAUDE\_CODE\_USE\_POWERSHELL\_TOOL=0</code>으로 옵트아웃할 수 있습니다</div>40 <div>PowerShell 도구는 이제 Amazon Bedrock, Google Cloud의 Agent Platform 및 Microsoft Foundry 사용자를 위해 Windows에서 기본적으로 활성화되며, <code>CLAUDE\_CODE\_USE\_POWERSHELL\_TOOL=0</code>으로 옵트아웃할 수 있습니다</div>

41 <div><code>claude plugin disable</code>은 이제 다른 활성화된 플러그인이 대상에 의존할 때 거부하며, <code>claude plugin enable</code>은 전이적 종속성을 강제로 활성화합니다</div>41 <div><code>claude plugin disable</code>은 이제 다른 활성화된 플러그인이 대상에 의존할 때 거부하며, <code>claude plugin enable</code>은 전이적 종속성을 강제로 활성화합니다</div>

42 <div><code>/plugin</code> 마켓플레이스 찾아보기 창은 예상 컨텍스트 비용을 표시하며, Discover 및 Browse 화면은 설치 전에 플러그인의 명령, 에이전트, 스킬, 훅 및 MCP/LSP 서버를 나열합니다</div>42 <div><code>/plugin</code> 마켓플레이스 찾아보기 창은 예상 컨텍스트 비용을 표시하며, Discover 및 Browse 화면은 설치 전에 플러그인의 명령, 에이전트, 스킬, 훅 및 MCP/LSP 서버를 나열합니다</div>

43 <div>새로운 <code>worktree.bgIsolation: "none"</code> 설정을 사용하면 백그라운드 세션이 <code>EnterWorktree</code> 없이 작업 복사본을 직접 편집할 수 있으며, worktree가 비실용적인 저장소의 경우입니다</div>43 <div>새로운 <code>worktree.bgIsolation: "none"</code> 설정을 사용하면 백그라운드 세션이 <code>EnterWorktree</code> 없이 작업 복사본을 직접 편집할 수 있으며, worktree가 비실용적인 저장소의 경우입니다</div>

whats-new/2026-w22.md +2 −2

Details

109 <div>Claude Code는 이제 기본 모델을 찾을 수 없을 때 모든 요청에 실패하는 대신 구성된 <code>--fallback-model</code>로 세션의 나머지 부분에 대해 전환합니다.</div>109 <div>Claude Code는 이제 기본 모델을 찾을 수 없을 때 모든 요청에 실패하는 대신 구성된 <code>--fallback-model</code>로 세션의 나머지 부분에 대해 전환합니다.</div>

110 <div>플러그인은 <code>plugin.json</code> 또는 마켓플레이스 항목에서 <code>defaultEnabled: false</code>를 선언할 수 있으므로 활성화할 때까지 켜지 않고 설치됩니다.</div>110 <div>플러그인은 <code>plugin.json</code> 또는 마켓플레이스 항목에서 <code>defaultEnabled: false</code>를 선언할 수 있으므로 활성화할 때까지 켜지 않고 설치됩니다.</div>

111 <div>Vim 모드: NORMAL 모드에서 <code>/</code>는 역방향 히스토리 검색을 열며, Bash 및 Zsh vi-mode와 일치합니다.</div>111 <div>Vim 모드: NORMAL 모드에서 <code>/</code>는 역방향 히스토리 검색을 열며, Bash 및 Zsh vi-mode와 일치합니다.</div>

112 <div>스트리밍 도구 실행은 이제 항상 활성화되어 있으며, 원격 측정이 비활성화되고 Bedrock, Vertex 및 Foundry에서도 포함됩니다.</div>112 <div>스트리밍 도구 실행은 이제 항상 활성화되어 있으며, 원격 측정이 비활성화되고 Amazon Bedrock, Google Cloud의 Agent Platform 및 Microsoft Foundry에서도 포함됩니다.</div>

113 <div>에이전트 보기를 열기 위해 <code>←←</code>는 이제 Bedrock, Vertex, Foundry 및 원격 측정이 비활성화된 상태에서 작동합니다.</div>113 <div>에이전트 보기를 열기 위해 <code>←←</code>는 이제 Amazon Bedrock, Google Cloud의 Agent Platform, Microsoft Foundry 및 원격 측정이 비활성화된 상태에서 작동합니다.</div>

114 <div>Chrome의 Claude: <code>/chrome</code> → "Select browser…"를 통해 사용할 연결된 브라우저를 선택하거나, 여러 개가 연결된 브라우저 작업이 실행될 때 채팅 내에서 선택합니다.</div>114 <div>Chrome의 Claude: <code>/chrome</code> → "Select browser…"를 통해 사용할 연결된 브라우저를 선택하거나, 여러 개가 연결된 브라우저 작업이 실행될 때 채팅 내에서 선택합니다.</div>

115 <div><code>claude mcp list</code> 및 <code>claude mcp get</code>은 이제 승인되지 않은 <code>.mcp.json</code> 서버를 자동 승인 및 연결 대신 승인 대기 중으로 표시합니다(출력이 파이프될 때).</div>115 <div><code>claude mcp list</code> 및 <code>claude mcp get</code>은 이제 승인되지 않은 <code>.mcp.json</code> 서버를 자동 승인 및 연결 대신 승인 대기 중으로 표시합니다(출력이 파이프될 때).</div>

116 </div>116 </div>

whats-new/2026-w23.md +4 −4

Details

4 4

5# 23주차 · 2026년 6월 1–5일5# 23주차 · 2026년 6월 1–5일

6 6

7> Bedrock, Vertex, Foundry에서 자동 모드 실행, acceptEdits 모드에서 코드를 실행할 수 있는 파일 작성 전 프롬프트 표시, /plugin list로 설치된 플러그인 나열, 관리형 배포를 위한 승인된 버전 범위 필수.7> Amazon Bedrock, Google Cloud의 Agent Platform, Microsoft Foundry에서 자동 모드 실행, acceptEdits 모드에서 코드를 실행할 수 있는 파일 작성 전 프롬프트 표시, /plugin list로 설치된 플러그인 나열, 관리형 배포를 위한 승인된 버전 범위 필수.

8 8

9<div className="digest-meta">9<div className="digest-meta">

10 <span>릴리스 <a href="/ko/docs/changelog#2-1-158">v2.1.158 → v2.1.165</a></span>10 <span>릴리스 <a href="/ko/docs/changelog#2-1-158">v2.1.158 → v2.1.165</a></span>

13 13

14<div className="digest-feature">14<div className="digest-feature">

15 <div className="digest-feature-header">15 <div className="digest-feature-header">

~~16 <span className="digest-feature-title">Bedrock, Vertex, Foundry에서 자동 모드</span>~~16 <span className="digest-feature-title">Amazon Bedrock, Google Cloud의 Agent Platform, Microsoft Foundry에서 자동 모드</span>

17 <span className="digest-feature-pill">v2.1.158</span>17 <span className="digest-feature-pill">v2.1.158</span>

18 </div>18 </div>

19 19

20 <p className="digest-feature-lede">자동 모드는 이제 Opus 4.7 및 Opus 4.8용 Bedrock, Vertex, Foundry에서 사용 가능하며, 권한 프롬프트를 타사 제공자의 백그라운드 안전 검사로 대체합니다. <code>CLAUDE\_CODE\_ENABLE\_AUTO\_MODE=1</code>을 설정하여 옵트인합니다.</p>20 <p className="digest-feature-lede">자동 모드는 이제 Opus 4.7 및 Opus 4.8용 Amazon Bedrock, Google Cloud의 Agent Platform, Microsoft Foundry에서 사용 가능하며, 권한 프롬프트를 타사 제공자의 백그라운드 안전 검사로 대체합니다. <code>CLAUDE\_CODE\_ENABLE\_AUTO\_MODE=1</code>을 설정하여 옵트인합니다.</p>

21 21

22 <p className="digest-feature-try">타사 제공자에서 옵트인한 후 Shift+Tab으로 자동 모드로 전환합니다:</p>22 <p className="digest-feature-try">타사 제공자에서 옵트인한 후 Shift+Tab으로 자동 모드로 전환합니다:</p>

23 23

25 export CLAUDE_CODE_ENABLE_AUTO_MODE=125 export CLAUDE_CODE_ENABLE_AUTO_MODE=1

26 ```26 ```

27 27

~~28 <a className="digest-feature-link" href="/ko/docs/permission-modes#enable-auto-mode-on-bedrock-vertex-ai-or-foundry">타사 제공자에서 자동 모드 활성화</a>~~28 <a className="digest-feature-link" href="/ko/docs/permission-modes#enable-auto-mode-on-bedrock-agent-platform-or-foundry">Bedrock, Agent Platform 또는 Foundry에서 자동 모드 활성화</a>

29</div>29</div>

30 30

31<div className="digest-feature">31<div className="digest-feature">

workflows.md +28 −2

Details

9{/* plan-availability: feature=workflows plans=pro,max,team,enterprise providers=all */}9{/* plan-availability: feature=workflows plans=pro,max,team,enterprise providers=all */}

10 10

11<Note>11<Note>

12 동적 워크플로우는 Claude Code v2.1.154 이상이 필요하며 모든 유료 요금제, Anthropic API 액세스, Amazon Bedrock, Google Cloud Vertex AI, Microsoft Foundry에서 사용 가능합니다. Pro에서는 `/config`의 동적 워크플로우 행에서 활성화하십시오.12 동적 워크플로우는 Claude Code v2.1.154 이상이 필요하며 모든 유료 요금제, Anthropic API 액세스, Amazon Bedrock, Google Cloud의 Agent Platform, Microsoft Foundry에서 사용 가능합니다. Pro에서는 `/config`의 동적 워크플로우 행에서 활성화하십시오.

13</Note>13</Note>

14 14

15동적 워크플로우는 대규모로 [서브에이전트](/ko/sub-agents)를 조율하는 JavaScript 스크립트입니다. Claude는 설명한 작업에 대한 스크립트를 작성하고, 런타임이 백그라운드에서 실행하는 동안 세션은 응답성을 유지합니다.15동적 워크플로우는 대규모로 [서브에이전트](/ko/sub-agents)를 조율하는 JavaScript 스크립트입니다. Claude는 설명한 작업에 대한 스크립트를 작성하고, 런타임이 백그라운드에서 실행하는 동안 세션은 응답성을 유지합니다.

148/effort ultracode148/effort ultracode

149```149```

150 150

151ultracode가 이미 활성화된 상태로 세션을 시작하려면 `claude --effort ultracode`로 실행하십시오. Claude Code v2.1.203 이상이 필요합니다.

152

151ultracode가 활성화되면 Claude는 작업이 워크플로우를 보증하는지 결정합니다. 단일 요청은 여러 워크플로우로 변할 수 있습니다: 코드를 이해하기 위한 하나, 변경을 수행하기 위한 하나, 검증하기 위한 하나입니다. 이는 세션의 모든 작업에 적용되므로 각 요청은 더 낮은 노력 수준보다 더 많은 토큰을 사용하고 더 오래 걸립니다.153ultracode가 활성화되면 Claude는 작업이 워크플로우를 보증하는지 결정합니다. 단일 요청은 여러 워크플로우로 변할 수 있습니다: 코드를 이해하기 위한 하나, 변경을 수행하기 위한 하나, 검증하기 위한 하나입니다. 이는 세션의 모든 작업에 적용되므로 각 요청은 더 낮은 노력 수준보다 더 많은 토큰을 사용하고 더 오래 걸립니다.

152 154

153Ultracode는 현재 세션 동안 지속되며 새 세션을 시작할 때 재설정됩니다. 일상적인 작업으로 돌아갈 때 `/effort high`로 내려갑니다. `xhigh` [노력](/ko/model-config#adjust-effort-level)을 지원하는 모델에서 사용 가능합니다; 다른 모델에서는 `/effort` 메뉴가 이를 제공하지 않습니다.155Ultracode는 현재 세션 동안 지속되며 새 세션을 시작할 때 재설정됩니다. 일상적인 작업으로 돌아갈 때 `/effort high`로 내려갑니다. `xhigh` [노력](/ko/model-config#adjust-effort-level)을 지원하는 모델에서 사용 가능합니다; 다른 모델에서는 `/effort` 메뉴가 이를 제공하지 않습니다.

346 348

347워크플로우는 많은 에이전트를 생성하므로 단일 실행은 대화에서 같은 작업을 수행하는 것보다 의미 있게 더 많은 토큰을 사용할 수 있습니다. 실행은 다른 세션과 마찬가지로 요금제의 사용량 및 속도 제한에 포함됩니다.349워크플로우는 많은 에이전트를 생성하므로 단일 실행은 대화에서 같은 작업을 수행하는 것보다 의미 있게 더 많은 토큰을 사용할 수 있습니다. 실행은 다른 세션과 마찬가지로 요금제의 사용량 및 속도 제한에 포함됩니다.

348 350

349대규모 작업에 커밋하기 전에 지출을 측정하려면 먼저 작은 부분에서 워크플로우를 실행합니다: 전체 저장소 대신 한 디렉토리, 또는 광범위한 질문 대신 좁은 질문입니다. `/workflows` 보기는 실행이 진행되면서 각 에이전트의 토큰 사용량을 표시하며, 완료된 작업을 잃지 않고 언제든지 실행을 중지할 수 있습니다. 런타임의 [에이전트 상한](#behavior-and-limits)은 단일 실행이 생성할 수 있는 에이전트 수를 제한하여 폭주 스크립트의 비용을 제한합니다.351대규모 작업에 커밋하기 전에 지출을 측정하려면 먼저 작은 부분에서 워크플로우를 실행합니다: 전체 저장소 대신 한 디렉토리, 또는 광범위한 질문 대신 좁은 질문입니다. `/workflows` 보기는 실행이 진행되면서 각 에이전트의 토큰 사용량을 표시하며, 완료된 작업을 잃지 않고 언제든지 실행을 중지할 수 있습니다. 런타임의 [에이전트 상한](#behavior-and-limits)은 단일 실행이 생성할 수 있는 에이전트 수를 제한하여 폭주 스크립트의 비용을 제한합니다. 모든 실행을 기본적으로 더 작게 유지하려면 `/config`에서 [크기 지침을 설정](#set-a-size-guideline)합니다.

352

353Claude Code는 또한 비정상적으로 커지는 실행에 플래그를 지정합니다. 워크플로우가 25개 이상의 에이전트를 예약하거나 예상 토큰 총계가 150만을 초과하면 입력 상자 아래의 작업 패널에서 진행 상황 줄에 `Large workflow` 경고가 표시됩니다. 경고는 실행을 중지할 수 있는 [`/workflows`](#watch-the-run)를 가리킵니다. Claude Code v2.1.203 이상이 필요합니다.

354

355경고는 권고사항입니다: 실행을 일시 중지하거나 제한하지 않습니다. 경고를 볼 때 두 가지 설정이 변경됩니다:

356

357* [크기 지침을 설정](#set-a-size-guideline)하면 지침의 에이전트 수가 25개 에이전트 임계값을 대체합니다.

358* [ultracode](#let-claude-decide-with-ultracode)가 켜진 세션은 경고를 표시하지 않습니다. ultracode를 켜는 것이 이미 대규모 실행에 동의했기 때문입니다.

350 359

351워크플로우의 모든 에이전트는 스크립트가 단계를 다른 것으로 라우팅하지 않는 한 세션의 모델을 사용합니다. 모델 비용을 제어하려면:360워크플로우의 모든 에이전트는 스크립트가 단계를 다른 것으로 라우팅하지 않는 한 세션의 모델을 사용합니다. 모델 비용을 제어하려면:

352 361

353* 일상적인 작업을 위해 일반적으로 더 작은 모델로 전환하는 경우 대규모 실행 전에 `/model`을 확인합니다362* 일상적인 작업을 위해 일반적으로 더 작은 모델로 전환하는 경우 대규모 실행 전에 `/model`을 확인합니다

354* 작업을 설명할 때 Claude에게 가장 강력한 것이 필요하지 않은 단계에 더 작은 모델을 사용하도록 요청합니다363* 작업을 설명할 때 Claude에게 가장 강력한 것이 필요하지 않은 단계에 더 작은 모델을 사용하도록 요청합니다

355 364

365<h3 id="set-a-size-guideline">

366 크기 지침 설정

367</h3>

368

369`/config`의 동적 워크플로우 크기 설정은 Claude가 작성하는 워크플로우를 기본적으로 더 작은 규모로 유지합니다. Claude Code는 설정을 Claude에 조언으로 보내므로 다른 규모를 요구하는 프롬프트는 여전히 이를 무시할 수 있습니다. Claude Code v2.1.202 이상이 필요합니다.

370

371각 값은 Claude가 작성하는 스크립트에서 목표로 하는 에이전트 수를 설정합니다.

372

373| 값 | Claude에 전송된 지침 |

374| :------------- | :--------------------- |

375| `unrestricted` | 지침 없음. 이것이 기본값입니다. |

376| `small` | 5개 미만의 에이전트를 목표로 합니다. |

377| `medium` | 15개 미만의 에이전트를 목표로 합니다. |

378| `large` | 50개 미만의 에이전트를 목표로 합니다. |

379

380변경 사항은 다음 프롬프트에서 적용됩니다. [런타임 에이전트 상한](#behavior-and-limits)은 설정에 관계없이 여전히 적용됩니다.

381

356<h3 id="turn-workflows-off">382<h3 id="turn-workflows-off">

357 워크플로우 끄기383 워크플로우 끄기

358</h3>384</h3>

worktrees.md +6 −0

Details

40 40

41처음으로 디렉터리에서 `--worktree`를 사용하기 전에 해당 디렉터리에서 `claude`를 한 번 실행하여 작업 공간 신뢰 대화를 수락합니다. 신뢰가 아직 수락되지 않았으면 `--worktree`는 오류와 함께 종료되고 먼저 디렉터리에서 `claude`를 실행하도록 요청합니다. `-p`를 사용한 비대화형 실행은 [신뢰 확인](/ko/security)을 건너뛰므로 `claude -p --worktree`는 이를 수행하지 않고 진행됩니다.41처음으로 디렉터리에서 `--worktree`를 사용하기 전에 해당 디렉터리에서 `claude`를 한 번 실행하여 작업 공간 신뢰 대화를 수락합니다. 신뢰가 아직 수락되지 않았으면 `--worktree`는 오류와 함께 종료되고 먼저 디렉터리에서 `claude`를 실행하도록 요청합니다. `-p`를 사용한 비대화형 실행은 [신뢰 확인](/ko/security)을 건너뛰므로 `claude -p --worktree`는 이를 수행하지 않고 진행됩니다.

42 42

43{/* min-version: 2.1.205 */}Claude Code가 시작 시 worktree 디렉터리에 들어갈 수 없는 경우, 예를 들어 [`WorktreeCreate` 훅](/ko/hooks#worktreecreate)이 생성한 디렉터리 이외의 다른 것을 출력했거나 설정 후 디렉터리가 삭제된 경우, Claude Code는 경로를 명시하는 오류를 출력하고 코드 1로 종료됩니다. v2.1.205 이전에는 이로 인해 세션이 충돌했으며, `-p`를 사용하면 약 30초 동안 정지한 후 코드 0으로 종료되었습니다.

45{/* min-version: 2.1.200 */}[프로젝트 범위](/ko/plugins-reference#plugin-installation-scopes)에서 메인 체크아웃에서 설치된 플러그인도 동일한 저장소의 worktree에 로드되므로 worktree마다 다시 설치할 필요가 없습니다. 이는 `--worktree` 또는 `git worktree add`로 worktree를 생성하든 적용됩니다. Claude Code v2.1.200 이상이 필요합니다.

43<Tip>47<Tip>

44 `.claude/worktrees/`를 `.gitignore`에 추가하여 worktree 내용이 메인 체크아웃에서 추적되지 않은 파일로 나타나지 않도록 합니다.48 `.claude/worktrees/`를 `.gitignore`에 추가하여 worktree 내용이 메인 체크아웃에서 추적되지 않은 파일로 나타나지 않도록 합니다.

45</Tip>49</Tip>

106 110

107에이전트가 실행 중인 동안 Claude는 해당 worktree에서 `git worktree lock`을 실행하여 동시 정리가 이를 제거할 수 없도록 합니다. 에이전트가 완료되면 잠금이 해제됩니다. 스윕이 유지하는 worktree를 정리하려면 `git worktree remove`를 실행하고, worktree에 커밋되지 않은 변경 사항이나 추적되지 않은 파일이 있으면 `--force`를 추가합니다.111에이전트가 실행 중인 동안 Claude는 해당 worktree에서 `git worktree lock`을 실행하여 동시 정리가 이를 제거할 수 없도록 합니다. 에이전트가 완료되면 잠금이 해제됩니다. 스윕이 유지하는 worktree를 정리하려면 `git worktree remove`를 실행하고, worktree에 커밋되지 않은 변경 사항이나 추적되지 않은 파일이 있으면 `--force`를 추가합니다.

108 112

113Windows에서 worktree를 제거하기 전에 Claude Code는 링크 항목으로서 그 안의 모든 깊이에 있는 NTFS 접합점 또는 디렉토리 심볼릭 링크를 제거하므로 worktree를 제거해도 링크가 가리키는 파일이 삭제되지 않습니다. v2.1.205 이전에는 Claude Code가 최상위 링크만 링크 항목으로 제거했으며, 서브디렉토리에 중첩된 접합점이 있는 worktree를 제거하면 worktree 외부의 링크가 가리키는 디렉토리의 내용이 삭제될 수 있었습니다.

114

109<h2 id="manage-worktrees-manually">115<h2 id="manage-worktrees-manually">

110 worktree 수동 관리116 worktree 수동 관리

111</h2>117</h2>

zero-data-retention.md +1 −1

Details

19* [서버 관리 설정](/ko/server-managed-settings)19* [서버 관리 설정](/ko/server-managed-settings)

20* 감사 로그20* 감사 로그

21 21

22Claude for Enterprise의 Claude Code에 대한 ZDR은 Anthropic의 직접 플랫폼에만 적용됩니다. Amazon Bedrock, Google Vertex AI 또는 Microsoft Foundry의 Claude 배포의 경우 해당 플랫폼의 데이터 보존 정책을 참조하세요.22Claude for Enterprise의 Claude Code에 대한 ZDR은 Anthropic의 직접 플랫폼에만 적용됩니다. Amazon Bedrock, Google Cloud의 Agent Platform 또는 Microsoft Foundry의 Claude 배포의 경우 해당 플랫폼의 데이터 보존 정책을 참조하세요.

23 23

24<h2 id="zdr-scope">24<h2 id="zdr-scope">

25 ZDR 범위25 ZDR 범위

Documentation 2026-07-09 23:58 UTC to 2026-07-10 17:00 UTC