Documentation — Spybara

admin-setup.md +7 −7

Details

46 설정이 기기에 도달하는 방식 결정46 설정이 기기에 도달하는 방식 결정

47</h2>47</h2>

48 48

49관리 설정은 조직 정책을 정의합니다. Claude Code는 아래 표의 네 가지 소스를 우선순위 순서대로 확인합니다. [Claude Code가 관리 소스를 결합하는 방식](/docs/ko/managed-settings#precedence-within-the-managed-tier)에서는 어떤 소스가 적용되는지, 정책 도우미가 무엇을 변경하는지, 모든 소스를 구성하는 방법을 설명합니다. 표는 의사결정 맵입니다.49관리형 설정은 조직 정책을 정의합니다. Claude Code는 아래 표의 네 가지 소스를 우선순위 순서대로 확인합니다. [Claude Code가 관리형 소스를 결합하는 방식](/docs/ko/managed-settings#precedence-within-the-managed-tier)에서는 어떤 소스가 적용되는지, 정책 도우미가 무엇을 변경하는지, 모든 소스를 구성하는 방법을 설명합니다. 표는 의사결정 맵입니다.

50 50

51| 메커니즘 | 전달 | 우선순위 | 플랫폼 |51| 메커니즘 | 전달 | 우선순위 | 플랫폼 |

52| :- | :- | :- | :- |52| :- | :- | :- | :- |

57 57

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

59 59

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

61 61

62plist 및 HKLM 레지스트리 위치는 모든 제공자와 함께 작동하며 관리자 권한이 필요하므로 변조에 저항합니다. HKCU의 Windows 사용자 레지스트리는 상승 권한 없이 쓸 수 있으므로 시행 채널이 아닌 편의 기본값으로 취급하세요.62plist 및 HKLM 레지스트리 위치는 모든 제공자와 함께 작동하며 관리자 권한이 필요하므로 변조에 저항합니다. HKCU의 Windows 사용자 레지스트리는 상승 권한 없이 쓸 수 있으므로 시행 채널이 아닌 편의 기본값으로 취급하세요.

63 63

64기본적으로 WSL은 `/etc/claude-code`의 Linux 파일 경로만 읽습니다. Windows 레지스트리 및 `C:\Program Files\ClaudeCode` 정책을 같은 머신의 WSL로 확장하려면 관리자 전용 Windows 소스 중 하나에서 [`wslInheritsWindowsSettings: true`](/docs/ko/settings-reference#wslinheritswindowssettings)를 설정하세요.64기본적으로 WSL은 `/etc/claude-code`의 Linux 파일 경로만 읽습니다. Windows 레지스트리 및 `C:\Program Files\ClaudeCode` 정책을 같은 머신의 WSL로 확장하려면 관리자 전용 Windows 소스 중 하나에서 [`wslInheritsWindowsSettings: true`](/docs/ko/settings-reference#wslinheritswindowssettings)를 설정하세요.

65 65

66선택한 메커니즘이 무엇이든 관리 값은 사용자 및 프로젝트 설정보다 우선합니다. 단, 몇 가지 보안에 민감한 [예외](/docs/ko/settings#exceptions-to-managed-settings-precedence)가 있습니다. `permissions.allow` 및 `permissions.deny`와 같은 배열 설정은 모든 소스의 항목을 병합하므로 개발자는 관리 목록을 확장할 수 있지만 제거할 수는 없습니다. `fallbackModel`, `availableModels` 및 [`modelPicker`](/docs/ko/settings-reference#modelpicker)의 경우 관리 값은 하위 계층을 병합하지 않고 대체합니다.66선택한 메커니즘이 무엇이든 관리형 값은 사용자 및 프로젝트 설정보다 우선합니다. 단, 몇 가지 보안에 민감한 [예외](/docs/ko/settings#exceptions-to-managed-settings-precedence)가 있습니다. `permissions.allow` 및 `permissions.deny`와 같은 배열 설정은 모든 소스의 항목을 병합하므로 개발자는 관리형 목록을 확장할 수 있지만 제거할 수는 없습니다. `fallbackModel`, `availableModels` 및 [`modelPicker`](/docs/ko/settings-reference#modelpicker)의 경우 관리형 값은 하위 계층을 병합하지 않고 대체합니다.

67 67

68<h3 id="wsl-sessions-in-claude-code-desktop">68<h3 id="wsl-sessions-in-claude-code-desktop">

69 Claude Code Desktop의 WSL 세션69 Claude Code Desktop의 WSL 세션

70</h3>70</h3>

71 71

72Windows에서 [Claude Code Desktop은 WSL 2 배포판 내부에서 Code 세션을 실행할 수 있습니다](/docs/ko/desktop-wsl). 세션의 Claude Code 프로세스는 배포판 내부에서 실행되므로 위의 WSL 검색 경로를 통해 관리 설정을 확인합니다. Windows 전용 소스는 `wslInheritsWindowsSettings: true`가 배포되지 않으면 이에 도달하지 않습니다.72Windows에서 [Claude Code Desktop은 WSL 2 배포판 내부에서 Code 세션을 실행할 수 있습니다](/docs/ko/desktop-wsl). 세션의 Claude Code 프로세스는 배포판 내부에서 실행되므로 위의 WSL 검색 경로를 통해 관리형 설정을 확인합니다. Windows 전용 소스는 `wslInheritsWindowsSettings: true`가 배포되지 않으면 이에 도달하지 않습니다.

73 73

74Claude Desktop은 조직에서 관리하는 것으로 감지된 기기(예: `C:\Program Files\ClaudeCode\managed-settings.json`이 존재하는 경우)에서 기본적으로 WSL 세션을 끕니다. 이를 켜려면 Windows 레지스트리 정책을 배포하세요. 이는 Claude Desktop v1.19367.0 이상이 필요합니다:74Claude Desktop은 조직에서 관리하는 것으로 감지된 기기(예: `C:\Program Files\ClaudeCode\managed-settings.json`이 존재하는 경우)에서 기본적으로 WSL 세션을 끕니다. 이를 켜려면 Windows 레지스트리 정책을 배포하세요. 이는 Claude Desktop v1.19367.0 이상이 필요합니다:

75 75

76* `HKLM\SOFTWARE\Policies\Claude` 아래에 `disableWslSessions`라는 값을 만들고 `REG_SZ` 문자열 `false` 또는 `REG_DWORD` `0`으로 설정합니다. 이 값은 관리 설정을 전달하는 `ClaudeCode` 키와 별도로 Claude Desktop 정책 키 아래에 있습니다. HKLM 아래에 값을 배포하세요. 이는 관리자 권한이 필요합니다. HKCU 아래의 값은 WSL 세션을 활성화하지 않습니다.76* `HKLM\SOFTWARE\Policies\Claude` 아래에 `disableWslSessions`라는 값을 만들고 `REG_SZ` 문자열 `false` 또는 `REG_DWORD` `0`으로 설정합니다. 이 값은 관리형 설정을 전달하는 `ClaudeCode` 키와 별도로 Claude Desktop 정책 키 아래에 있습니다. HKLM 아래에 값을 배포하세요. 이는 관리자 권한이 필요합니다. HKCU 아래의 값은 WSL 세션을 활성화하지 않습니다.

77* `C:\Program Files\ClaudeCode\managed-settings.json`을 배포하는 경우 제자리에 두세요. `disableWslSessions`이 HKLM 아래에서 `false`가 되면 Desktop은 해당 파일이 있어도 WSL 세션을 허용합니다.77* `C:\Program Files\ClaudeCode\managed-settings.json`을 배포하는 경우 제자리에 두세요. `disableWslSessions`이 HKLM 아래에서 `false`가 되면 Desktop은 해당 파일이 있어도 WSL 세션을 허용합니다.

78 78

79Desktop은 WSL 세션이 시작될 때마다 정책을 읽으므로 배포 후 앱을 다시 시작할 필요가 없습니다.79Desktop은 WSL 세션이 시작될 때마다 정책을 읽으므로 배포 후 앱을 다시 시작할 필요가 없습니다.

80 80

81기기가 여전히 WSL 세션을 거부하는 경우 해당 기기의 Claude Desktop에서 **Help > Troubleshooting > Show Logs in Explorer**를 열어 로그 폴더의 복사본을 다운로드에 저장합니다. 해당 복사본의 `main.log`에서 `[wslPolicyGate] denying WSL session`을 검색합니다. 거부 이유는 괄호 안에 따라옵니다(예: `(cli-file-present)`). Claude Desktop이 `.exe` 설치 프로그램으로 설치된 경우 `%APPDATA%\Claude\logs\main.log`에서 라이브 파일을 읽을 수도 있습니다.81기기가 여전히 WSL 세션을 거부하는 경우 해당 기기의 Claude Desktop에서 **Help > Troubleshooting > Show Logs in File Explorer**를 열어 로그 폴더의 복사본을 다운로드에 저장합니다. 해당 복사본의 `main.log`에서 `[wslPolicyGate] denying WSL session`을 검색합니다. 거부 이유는 괄호 안에 따라옵니다(예: `(cli-file-present)`).

82 82

~~83WSL 세션이 활성화된 후 관리 설정을 확장합니다:~~83WSL 세션이 활성화된 후 관리형 설정을 확장합니다:

84 84

85* HKLM 레지스트리 또는 `C:\Program Files\ClaudeCode` 파일을 통해 `wslInheritsWindowsSettings: true`를 배포하여 WSL 세션이 호스트 세션과 동일한 정책을 상속하도록 합니다.85* HKLM 레지스트리 또는 `C:\Program Files\ClaudeCode` 파일을 통해 `wslInheritsWindowsSettings: true`를 배포하여 WSL 세션이 호스트 세션과 동일한 정책을 상속하도록 합니다.

86* WSL 세션 내에서 `/status`를 실행하여 확인하고 `Setting sources` 줄을 읽습니다. 이를 해석하려면 [/status에서 소스 읽기](/docs/ko/managed-settings#read-the-source-in-/status)를 참조하세요.86* WSL 세션 내에서 `/status`를 실행하여 확인하고 `Setting sources` 줄을 읽습니다. 이를 해석하려면 [/status에서 소스 읽기](/docs/ko/managed-settings#read-the-source-in-/status)를 참조하세요.

advisor.md +8 −8

Details

87Claude Code는 해당 세션에 대해 `advisorModel` 설정 대신 플래그를 사용합니다. `claude --help`에 `--advisor`를 나열하지 않습니다. Claude Code는 다음의 경우 시작 시 오류로 종료됩니다:87Claude Code는 해당 세션에 대해 `advisorModel` 설정 대신 플래그를 사용합니다. `claude --help`에 `--advisor`를 나열하지 않습니다. Claude Code는 다음의 경우 시작 시 오류로 종료됩니다:

88 88

89* 세션의 주 모델이 조언자를 지원하지 않음89* 세션의 주 모델이 조언자를 지원하지 않음

~~90* Haiku와 같은 요청된 모델이 조언자로 작동할 수 없음~~90* Haiku 4.5와 같은 요청된 모델이 조언자로 작동할 수 없음

91* 조직의 [`availableModels`](/docs/ko/model-config#restrict-model-selection) 허용 목록이 요청된 모델을 제외함91* 조직의 [`availableModels`](/docs/ko/model-config#restrict-model-selection) 허용 목록이 요청된 모델을 제외함

92* Fable을 요청했고 계정이 여전히 [사용량 크레딧 동의](#fable-advisor-and-usage-credits)를 필요로 함92* Fable을 요청했고 계정이 여전히 [사용량 크레딧 동의](#fable-advisor-and-usage-credits)를 필요로 함

93 93

103 103

104| 주 모델 | 허용되는 조언자 |104| 주 모델 | 허용되는 조언자 |

105| - | - |105| - | - |

106| Haiku 4.5 | Fable, Opus, Sonnet |106| Haiku 4.5 | Fable, Opus, Sonnet, Haiku 5.5 |

107| Sonnet 4.6 | Fable, Opus, Sonnet |107| Sonnet 4.6 | Fable, Opus, Sonnet, Haiku 5.5 |

108| Opus 4.6 | Fable, Opus, Sonnet 5 이상 |108| Opus 4.6 | Fable, Opus, Sonnet 5 이상, Haiku 5.5 |

109| Sonnet 5 | Fable, Opus 4.7 이상, Sonnet 5 이상 |109| Sonnet 5 또는 Haiku 5.5 | Fable, Opus 4.7 이상, Sonnet 5 이상, Haiku 5.5 |

110| Opus 4.7 또는 Opus 4.8 | Fable, Opus 4.7 이상, Sonnet 5.5 |110| Opus 4.7 또는 Opus 4.8 | Fable, Opus 4.7 이상, Sonnet 5.5 |

111| Sonnet 5.5 | Fable, Opus 5 이상, Sonnet 5.5 |111| Sonnet 5.5 | Fable, Opus 5 이상, Sonnet 5.5 |

112| Opus 5 또는 Opus 5.5 | Fable, Opus 5 이상 |112| Opus 5 또는 Opus 5.5 | Fable, Opus 5 이상 |

113| Fable 5 | Fable 5.1 또는 Fable 5 |113| Fable 5 | Fable 5.1 또는 Fable 5 |

114| Fable 5.1 | Fable 5.1 |114| Fable 5.1 | Fable 5.1 |

115 115

116Fable 5.1은 Claude Code v2.1.257 이상이 필요합니다. Fable 모델은 [Fable 액세스](/docs/ko/model-config#work-with-fable)가 필요합니다. Opus 4.7 또는 Opus 4.8 주 모델의 조언자로 Sonnet 5.5를 사용하려면 Claude Code v2.1.287 이상이 필요합니다.116Fable 5.1은 Claude Code v2.1.257 이상이 필요합니다. Fable 모델은 [Fable 액세스](/docs/ko/model-config#work-with-fable)가 필요합니다. Opus 4.7 또는 Opus 4.8 주 모델의 조언자로 Sonnet 5.5를 사용하려면 Claude Code v2.1.287 이상이 필요합니다. Haiku 5.5를 주 모델 또는 조언자로 사용하려면 Claude Code v2.1.293 이상이 필요합니다.

117 117

118조언자를 `fable`, `opus`, 또는 `sonnet`으로 설정하세요. 이러한 별칭은 각 모델 제품군에 대한 Claude Code의 [기본 제공 기본 버전](/docs/ko/model-config#model-aliases)으로 확인되며, 새로운 Claude Code 릴리스와 함께 업데이트됩니다. `claude-opus-5-5`와 같은 전체 모델 ID를 전달할 수도 있습니다. Haiku는 조언자를 호출할 수 있지만 조언자로 작동할 수는 없습니다.118조언자를 `fable`, `opus`, 또는 `sonnet`으로 설정하세요. 이러한 별칭은 각 모델 제품군에 대한 Claude Code의 [기본 제공 기본 버전](/docs/ko/model-config#model-aliases)으로 확인되며, 새로운 Claude Code 릴리스와 함께 업데이트됩니다. `claude-opus-5-5` 또는 `claude-haiku-5-5`와 같은 전체 모델 ID를 전달할 수도 있습니다. Haiku 4.5는 조언자를 호출할 수 있지만 조언자로 작동할 수는 없습니다.

119 119

120하위 에이전트는 구성된 조언자를 상속하고 자신의 모델에 대해 동일한 쌍 확인을 적용합니다.120하위 에이전트는 구성된 조언자를 상속하고 자신의 모델에 대해 동일한 쌍 확인을 적용합니다.

121 121

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

203 203

204* **Anthropic API만**: 조언자는 서버 실행 도구입니다. Amazon Bedrock, Claude Platform on AWS, Google Cloud의 Agent Platform 또는 Microsoft Foundry에서는 사용할 수 없습니다. `ANTHROPIC_BASE_URL`로 구성된 [LLM 게이트웨이](/docs/ko/llm-gateway)를 통해 가용성은 게이트웨이가 요청을 Anthropic API로 그대로 전달하는지 여부에 따라 달라집니다. 게이트웨이 또는 그 업스트림이 조언자 도구를 인식하지 못하는 경우 Claude Code가 응답하는 방식에 대해 [자동 재시도 및 오류 전달](/docs/ko/llm-gateway-protocol#automatic-retry-and-error-forwarding)을 참조하십시오.204* **Anthropic API만**: 조언자는 서버 실행 도구입니다. Amazon Bedrock, Claude Platform on AWS, Google Cloud의 Agent Platform 또는 Microsoft Foundry에서는 사용할 수 없습니다. `ANTHROPIC_BASE_URL`로 구성된 [LLM 게이트웨이](/docs/ko/llm-gateway)를 통해 가용성은 게이트웨이가 요청을 Anthropic API로 그대로 전달하는지 여부에 따라 달라집니다. 게이트웨이 또는 그 업스트림이 조언자 도구를 인식하지 못하는 경우 Claude Code가 응답하는 방식에 대해 [자동 재시도 및 오류 전달](/docs/ko/llm-gateway-protocol#automatic-retry-and-error-forwarding)을 참조하십시오.

205* **지원되는 주 모델**: Fable, Opus 4.6 이상, Sonnet 4.6 이상 또는 Haiku 4.5. [조언자 모델 선택](#choose-an-advisor-model)을 참조하여 각 조언자가 어떤 모델을 지원하는지 확인하십시오.205* **지원되는 주 모델**: Fable, Opus 4.6 이상, Sonnet 4.6 이상, Haiku 4.5 또는 Haiku 5.5. 각 모델이 어떤 조언자를 허용하는지는 [조언자 모델 선택](#choose-an-advisor-model)을 참조하십시오.

206* **기능 플래그 가져오기**: Claude Code는 Anthropic에서 가져온 기능 플래그를 통해 조언자를 켭니다. `DISABLE_TELEMETRY`와 같이 플래그 가져오기를 끄는 변수가 설정된 세션에서는 조언자가 꺼진 상태로 유지됩니다. [기능 플래그 가져오기가 필요한 기능](/docs/ko/env-vars#features-that-need-feature-flag-fetching)을 참조하십시오.206* **기능 플래그 가져오기**: Claude Code는 Anthropic에서 가져온 기능 플래그를 통해 조언자를 켭니다. `DISABLE_TELEMETRY`와 같이 플래그 가져오기를 끄는 변수가 설정된 세션에서는 조언자가 꺼진 상태로 유지됩니다. [기능 플래그 가져오기가 필요한 기능](/docs/ko/env-vars#features-that-need-feature-flag-fetching)을 참조하십시오.

207 207

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

agent-sdk/hooks.md +10 −10

Details

140 ```140 ```

141</CodeGroup>141</CodeGroup>

142 142

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

144 144

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

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

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

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

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

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

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

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

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

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

220 220

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

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

223 223

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

225 매처225 Matcher

226</h3>226</h3>

227 227

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

259 259

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

261 261

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

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

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

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

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

267 267

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

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

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

842 842

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

844 844

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

846 846

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

879</h3>879</h3>

880 880

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

882 882

883<CodeGroup>883<CodeGroup>

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

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

916</h3>916</h3>

917 917

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

919 919

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

921 921

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

923 923

agent-sdk/python.md +52 −51

Details

194 `ToolAnnotations`194 `ToolAnnotations`

195</h4>195</h4>

196 196

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

198 198

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

200 200

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

922| `allowed_tools` | `list[str]` | `[]` | 프롬프트 없이 자동 승인할 도구. 이것은 Claude를 이 도구로만 제한하지 않습니다. [작업 추적 도구](/docs/ko/agent-sdk/todo-tracking#model-availability) 중 하나를 여기에 명명하면 Claude Code도 세션을 옵트인합니다. 나열되지 않은 도구는 `permission_mode` 및 `can_use_tool`로 넘어갑니다. `disallowed_tools`를 사용하여 도구를 차단합니다. [권한](/docs/ko/agent-sdk/permissions#allow-and-deny-rules) 참조 |922| `allowed_tools` | `list[str]` | `[]` | 프롬프트 없이 자동 승인할 도구. 이것은 Claude를 이 도구로만 제한하지 않습니다. [작업 추적 도구](/docs/ko/agent-sdk/todo-tracking#model-availability) 중 하나를 여기에 명명하면 Claude Code도 세션을 옵트인합니다. 나열되지 않은 도구는 `permission_mode` 및 `can_use_tool`로 넘어갑니다. `disallowed_tools`를 사용하여 도구를 차단합니다. [권한](/docs/ko/agent-sdk/permissions#allow-and-deny-rules) 참조 |

923| `system_prompt` | `str \| SystemPromptPreset \| SystemPromptCustom \| SystemPromptFile \| None` | `None` | 시스템 프롬프트 구성. 사용자 정의 프롬프트의 경우 문자열을 전달하거나, Claude Code의 시스템 프롬프트를 위해 선택적 `"append"`와 함께 `{"type": "preset", "preset": "claude_code"}`를 사용하거나, 사용자 정의 프롬프트를 위해 `{"type": "custom", "prompt": "..."}` 형식으로 `"snapshot"`도 설정할 수 있거나, 디스크에서 큰 프롬프트를 로드하기 위해 `{"type": "file", "path": "..."}` 형식을 사용합니다. [`SystemPromptPreset`](#systempromptpreset), [`SystemPromptCustom`](#systempromptcustom) 및 [`SystemPromptFile`](#systempromptfile) 참조 |923| `system_prompt` | `str \| SystemPromptPreset \| SystemPromptCustom \| SystemPromptFile \| None` | `None` | 시스템 프롬프트 구성. 사용자 정의 프롬프트의 경우 문자열을 전달하거나, Claude Code의 시스템 프롬프트를 위해 선택적 `"append"`와 함께 `{"type": "preset", "preset": "claude_code"}`를 사용하거나, 사용자 정의 프롬프트를 위해 `{"type": "custom", "prompt": "..."}` 형식으로 `"snapshot"`도 설정할 수 있거나, 디스크에서 큰 프롬프트를 로드하기 위해 `{"type": "file", "path": "..."}` 형식을 사용합니다. [`SystemPromptPreset`](#systempromptpreset), [`SystemPromptCustom`](#systempromptcustom) 및 [`SystemPromptFile`](#systempromptfile) 참조 |

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

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

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

937| `output_format` | `dict[str, Any] \| None` | `None` | 구조화된 응답을 위한 출력 형식 (예: `{"type": "json_schema", "schema": {...}}`). 자세한 내용은 [구조화된 출력](/docs/ko/agent-sdk/structured-outputs) 참조 |937| `output_format` | `dict[str, Any] \| None` | `None` | 구조화된 응답을 위한 출력 형식 (예: `{"type": "json_schema", "schema": {...}}`). 자세한 내용은 [구조화된 출력](/docs/ko/agent-sdk/structured-outputs) 참조 |

939| `cwd` | `str \| Path \| None` | `None` | 현재 작업 디렉토리 |939| `cwd` | `str \| Path \| None` | `None` | 현재 작업 디렉터리 |

942| `add_dirs` | `list[str \| Path]` | `[]` | Claude가 접근할 수 있는 추가 디렉토리. SDK는 각 항목을 Claude Code에 `--add-dir`로 전달하므로, `project` 설정 소스를 사용하면 Claude Code도 [디렉토리의 스킬, 명령 및 서브에이전트를 로드합니다](/docs/ko/permissions#additional-directories-grant-file-access-not-configuration) |942| `add_dirs` | `list[str \| Path]` | `[]` | Claude가 접근할 수 있는 추가 디렉터리. SDK는 각 항목을 Claude Code에 `--add-dir`로 전달하므로, `project` 설정 소스를 사용하면 Claude Code도 [디렉터리의 스킬, 명령 및 서브에이전트를 로드합니다](/docs/ko/permissions#additional-directories-grant-file-access-not-configuration) |

943| `env` | `dict[str, str]` | `{}` | 상속된 프로세스 환경 위에 병합된 환경 변수. 기본 CLI가 읽는 변수는 [환경 변수](/docs/ko/env-vars) 참조. 시간 초과 관련 변수는 [느리거나 정지된 API 응답 처리](#handle-slow-or-stalled-api-responses) 참조. `CLAUDE_AGENT_SDK_CLIENT_APP`을 설정하여 User-Agent 헤더에서 앱을 식별합니다 |943| `env` | `dict[str, str]` | `{}` | 상속된 프로세스 환경 위에 병합된 환경 변수. 기본 CLI가 읽는 변수는 [환경 변수](/docs/ko/env-vars) 참조. 타임아웃 관련 변수는 [느리거나 정지된 API 응답 처리](#handle-slow-or-stalled-api-responses) 참조. `CLAUDE_AGENT_SDK_CLIENT_APP`을 설정하여 User-Agent 헤더에서 앱을 식별합니다 |

944| `extra_args` | `dict[str, str \| None]` | `{}` | CLI에 직접 전달할 추가 CLI 인수 |944| `extra_args` | `dict[str, str \| None]` | `{}` | CLI에 직접 전달할 추가 CLI 인수 |

948| `can_use_tool` | [`CanUseTool`](#canusetool) ` \| None` | `None` | 도구 권한 콜백. [권한 흐름](/docs/ko/agent-sdk/permissions#how-permissions-are-evaluated)이 프롬프트로 넘어갈 때만 호출됩니다. `allowed_tools`, 허용 규칙 또는 `permission_mode`로 자동 승인된 호출에 대해서는 호출되지 않습니다. 허용 규칙이 일치하더라도 [모든 모드가 자동 승인하지 않는 작업](/docs/ko/permission-modes#actions-no-mode-auto-approves)에 도달합니다. [`CanUseTool`](#canusetool)에서 자세한 내용 참조 |948| `can_use_tool` | [`CanUseTool`](#canusetool) ` \| None` | `None` | 도구 권한 콜백. [권한 흐름](/docs/ko/agent-sdk/permissions#how-permissions-are-evaluated)이 프롬프트로 넘어갈 때만 호출됩니다. `allowed_tools`, 허용 규칙 또는 `permission_mode`로 자동 승인된 호출에 대해서는 호출되지 않습니다. 허용 규칙은 [어떤 모드도 자동 승인하지 않는 작업](/docs/ko/permission-modes#actions-no-mode-auto-approves)을 사전 승인하지 않습니다. [`CanUseTool`](#canusetool)에서 자세한 내용 참조 |

953| `forward_subagent_text` | `bool` | `False` | 메시지 스트림에서 서브에이전트 텍스트 및 생각 블록을 전달합니다. 이 옵션 없이 Claude Code는 서브에이전트 `tool_use` 및 `tool_result` 블록을 내보내지만 텍스트 또는 생각은 내보내지 않습니다. Python Agent SDK 0.2.140 이상 필요 |953| `forward_subagent_text` | `bool` | `False` | 메시지 스트림에서 서브에이전트 텍스트 및 thinking 블록을 전달합니다. 이 옵션이 없으면 Claude Code는 [포그라운드](/docs/ko/sub-agents#run-subagents-in-foreground-or-background)에서 실행되는 서브에이전트의 텍스트 및 thinking 블록을 생략합니다. 중첩된 서브에이전트, `context: fork`가 있는 스킬, 그리고 각각에 필요한 Claude Code 버전은 [서브에이전트 메시지 따라가기](/docs/ko/headless#follow-subagent-messages)를 참조하십시오. Python Agent SDK 0.2.140 이상 필요 |

954| `verbatim_prompts` | `bool` | `False` | 모든 프롬프트를 작성된 대로 전달합니다. SDK는 각 사용자 메시지를 `client_composed`가 `True`로 설정되어 전송합니다. Claude Code가 이 메시지에서 건너뛰는 것은 [`client_composed`](/docs/ko/agent-sdk/typescript#sdkusermessage)를 참조하십시오. 프롬프트 텍스트에 최종 사용자가 입력하지 않은 콘텐츠가 포함될 때 이 옵션을 사용합니다. 턴별 제어를 위해 이를 끄고 대신 스트리밍된 메시지에서 개별적으로 `"client_composed": True`를 설정합니다. 옵션이 켜져 있는 동안 SDK는 설정한 모든 `client_composed` 값을 덮어씁니다. Python Agent SDK 0.2.158 이상 및 Claude Code v2.1.248 이상 필요. 이 SDK 버전과 함께 번들된 CLI는 Claude Code 요구사항을 충족합니다 |954| `verbatim_prompts` | `bool` | `False` | 모든 프롬프트를 작성된 대로 전달합니다. SDK는 각 사용자 메시지를 `client_composed`가 `True`로 설정되어 전송합니다. Claude Code가 이 메시지에서 건너뛰는 것은 [`client_composed`](/docs/ko/agent-sdk/typescript#sdkusermessage)를 참조하십시오. 프롬프트 텍스트에 최종 사용자가 입력하지 않은 콘텐츠가 포함될 때 이 옵션을 사용합니다. 턴별 제어를 위해 이를 끄고 대신 스트리밍된 메시지에서 개별적으로 `"client_composed": True`를 설정합니다. 옵션이 켜져 있는 동안 SDK는 설정한 모든 `client_composed` 값을 덮어씁니다. Python Agent SDK 0.2.158 이상 및 Claude Code v2.1.248 이상 필요. 이 SDK 버전과 함께 번들된 CLI는 Claude Code 요구사항을 충족합니다 |

961| `setting_sources` | `list[SettingSource] \| None` | `None` (CLI 기본값: 모든 소스) | 로드할 파일 시스템 설정을 제어합니다. 사용자, 프로젝트 및 로컬 설정을 비활성화하려면 `[]`를 전달합니다. `skills` 설정 및 이 필드 미설정 시 사용자 및 프로젝트 소스만 로드됩니다. 로컬 설정을 유지하려면 `setting_sources`를 명시적으로 설정합니다. 엔드포인트 관리 정책은 어쨌든 로드됩니다. 서버 관리 설정은 [적격 구성](/docs/ko/server-managed-settings#platform-availability)에서 조직 자격증명으로 세션이 인증될 때 가져옵니다. 이 옵션이 제어하지 않는 입력은 [Claude Code 기능 사용](/docs/ko/agent-sdk/claude-code-features#what-settingsources-does-not-control) 참조 |961| `setting_sources` | `list[SettingSource] \| None` | `None` (CLI 기본값: 모든 소스) | 로드할 파일 시스템 설정을 제어합니다. 사용자, 프로젝트 및 로컬 설정을 비활성화하려면 `[]`를 전달합니다. `skills` 설정 및 이 필드 미설정 시 사용자 및 프로젝트 소스만 로드됩니다. 로컬 설정을 유지하려면 `setting_sources`를 명시적으로 설정합니다. 엔드포인트 관리 정책은 어쨌든 로드됩니다. 서버 관리 설정은 [적격 구성](/docs/ko/server-managed-settings#platform-availability)에서 조직 자격 증명으로 세션이 인증될 때 가져옵니다. 이 옵션과 관계없이 읽히는 입력은 [settingSources가 제어하지 않는 항목](/docs/ko/agent-sdk/claude-code-features#what-settingsources-does-not-control) 참조 |

962| `skills` | `list[str] \| Literal["all"] \| None` | `None` | 세션에서 사용 가능한 스킬. 모든 발견된 스킬을 활성화하려면 `"all"`을 전달하거나, 스킬 이름 목록을 전달합니다. 정확한 이름만 전달합니다. SDK는 형식이 잘못되고 와일드카드 형식의 이름을 거부합니다. 이 검사는 Python Agent SDK 0.2.129 이상 필요합니다. 설정하면 SDK는 `allowed_tools`에 Skill 도구를 자동으로 추가합니다. `tools`도 전달하는 경우 해당 목록에 `"Skill"`을 포함합니다. [스킬](/docs/ko/agent-sdk/skills) 참조 |962| `skills` | `list[str] \| Literal["all"] \| None` | `None` | 세션에서 사용 가능한 스킬. 모든 발견된 스킬을 활성화하려면 `"all"`을 전달하거나, 스킬 이름 목록을 전달합니다. 정확한 이름만 전달합니다. SDK는 Claude Code 프로세스를 시작하기 전에 형식이 잘못되거나 와일드카드 형식인 이름을 `ValueError`로 거부합니다. 이 검사는 Python Agent SDK 0.2.129 이상이 필요합니다. 설정하면 SDK는 `allowed_tools`에 Skill 도구를 자동으로 추가합니다. `tools`도 전달하는 경우 해당 목록에 `"Skill"`을 포함합니다. [스킬](/docs/ko/agent-sdk/skills) 참조 |

967| `session_store_flush` | `Literal["batched", "eager"]` | `"batched"` | `session_store`에 미러링된 기록 항목을 플러시할 시기. `"batched"`는 턴당 한 번 또는 버퍼가 가득 찰 때 플러시합니다. `"eager"`는 모든 프레임 후에 백그라운드 플러시를 트리거합니다. `session_store`가 `None`일 때 무시됩니다 |967| `session_store_flush` | `Literal["batched", "eager"]` | `"batched"` | `session_store`에 미러링된 트랜스크립트 항목을 플러시할 시기. `"batched"`는 턴당 한 번 또는 버퍼가 가득 찰 때 플러시합니다. `"eager"`는 모든 프레임 후에 백그라운드 플러시를 트리거합니다. `session_store`가 `None`일 때 무시됩니다 |

968| `load_timeout_ms` | `int` | `60000` | 재개 구체화 중 `session_store.load()` 및 `list_subkeys()`에 대한 호출당 시간 초과 (밀리초) |968| `load_timeout_ms` | `int` | `60000` | 재개 구체화 중 `session_store.load()` 및 `list_subkeys()`에 대한 호출당 타임아웃 (밀리초) |

969| `task_budget` | `TaskBudget \| None` | `None` | API 측 토큰 예산. `task-budgets-2026-03-13` 베타 헤더와 함께 `output_config.task_budget`으로 전송됩니다. `{"total": <int>}`를 전달합니다. |969| `task_budget` | `TaskBudget \| None` | `None` | API 측 토큰 예산. `task-budgets-2026-03-13` 베타 헤더와 함께 `output_config.task_budget`으로 전송됩니다. `{"total": <int>}`를 전달합니다. |

970 970

971<h4 id="handle-slow-or-stalled-api-responses">971<h4 id="handle-slow-or-stalled-api-responses">

972 느리거나 정지된 API 응답 처리972 느리거나 정지된 API 응답 처리

973</h4>973</h4>

974 974

975CLI 서브프로세스는 API 시간 초과 및 정지 감지를 제어하는 여러 환경 변수를 읽습니다. `ClaudeAgentOptions.env`를 통해 전달합니다:975CLI 서브프로세스는 API 타임아웃 및 정지 감지를 제어하는 여러 환경 변수를 읽습니다. `ClaudeAgentOptions.env`를 통해 전달합니다:

976 976

977```python theme={null}977```python theme={null}

978from claude_agent_sdk import ClaudeAgentOptions978from claude_agent_sdk import ClaudeAgentOptions

986)986)

987```987```

988 988

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

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

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

992 992

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

994* `CLAUDE_ENABLE_STREAM_WATCHDOG` with `CLAUDE_STREAM_IDLE_TIMEOUT_MS`: 헤더가 도착했지만 응답 본문이 스트리밍을 중지할 때 요청을 중단하는 스트림 감시견. 감시견은 모든 공급자에 대해 기본적으로 켜져 있습니다. `CLAUDE_ENABLE_STREAM_WATCHDOG=0`으로 설정하여 비활성화합니다. `CLAUDE_STREAM_IDLE_TIMEOUT_MS`는 기본값 `300000`이고 해당 최소값으로 제한됩니다. 중단 후 [자동 재시도](/docs/ko/errors#automatic-retries)는 응답이 얼마나 진행되었는지에 따라 Claude Code가 수행하는 작업을 다룹니다.994* `CLAUDE_ENABLE_STREAM_WATCHDOG` 및 `CLAUDE_STREAM_IDLE_TIMEOUT_MS`: 헤더가 도착했지만 응답 본문이 스트리밍을 중지할 때 요청을 중단하는 스트림 감시견. 감시견은 모든 공급자에 대해 기본적으로 켜져 있습니다. `CLAUDE_ENABLE_STREAM_WATCHDOG=0`으로 설정하여 비활성화합니다. `CLAUDE_STREAM_IDLE_TIMEOUT_MS`는 기본값 `300000`이고 해당 최소값으로 제한됩니다. 중단 후 [자동 재시도](/docs/ko/errors#automatic-retries)는 응답이 얼마나 진행되었는지에 따라 Claude Code가 수행하는 작업을 다룹니다.

995 995

996 감시견이 `ANTHROPIC_BASE_URL` 뒤의 게이트웨이가 keep-alive ping으로 열어 두는 응답을 기다리는 동안, `include_partial_messages`를 설정한 호스트는 계속 `ping` [`StreamEvent`](#streamevent) 메시지를 수신합니다. 이 프레임을 세션 침묵으로 시간 초과하는 대신 생존성으로 읽습니다. v2.1.257 이전에는 마지막 실제 스트림 이벤트 후 5분 후에 프레임이 중지되었습니다.996 감시견이 `ANTHROPIC_BASE_URL` 뒤의 게이트웨이가 keep-alive ping으로 열어 두는 응답을 기다리는 동안, `include_partial_messages`를 설정한 호스트는 계속 `ping` [`StreamEvent`](#streamevent) 메시지를 수신합니다. 이 프레임을 침묵으로 인해 세션을 시간 초과시키는 대신 생존 신호로 읽습니다. v2.1.257 이전에는 마지막 실제 스트림 이벤트 후 5분 후에 프레임이 중지되었습니다.

997 997

998<h3 id="outputformat">998<h3 id="outputformat">

999 `OutputFormat`999 `OutputFormat`

1035| `preset` | 예 | Claude Code의 시스템 프롬프트를 사용하려면 `"claude_code"`이어야 합니다 |1035| `preset` | 예 | Claude Code의 시스템 프롬프트를 사용하려면 `"claude_code"`이어야 합니다 |

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

1037| `exclude_dynamic_sections` | 아니오 | 사용자별 컨텍스트 (예: 자동 메모리 위치)를 시스템 프롬프트에서 첫 사용자 메시지로 이동합니다. 사용자 및 머신 간 프롬프트 캐시 재사용을 개선합니다. [시스템 프롬프트 수정](/docs/ko/agent-sdk/modifying-system-prompts#improve-prompt-caching-across-users-and-machines) 참조 |1037| `exclude_dynamic_sections` | 아니오 | 사용자별 컨텍스트 (예: 자동 메모리 위치)를 시스템 프롬프트에서 첫 사용자 메시지로 이동합니다. 사용자 및 머신 간 프롬프트 캐시 재사용을 개선합니다. [시스템 프롬프트 수정](/docs/ko/agent-sdk/modifying-system-prompts#improve-prompt-caching-across-users-and-machines) 참조 |

1038| `snapshot` | 아니오 | `False`로 설정하여 [세션이 첫 요청에서 기록한 프롬프트를 재사용](/docs/ko/agent-sdk/modifying-system-prompts#change-the-prompt-of-an-existing-session) 대신 모든 요청에서 시스템 프롬프트를 다시 빌드합니다. Python Agent SDK 0.2.153 이상 필요 |1038| `snapshot` | 아니오 | `False`로 설정하여 [세션이 첫 요청에서 기록한 프롬프트를 재사용](/docs/ko/agent-sdk/modifying-system-prompts#change-the-prompt-of-an-existing-session)하는 대신 모든 요청에서 시스템 프롬프트를 다시 빌드합니다. `claude-agent-sdk` v0.2.153 이상 필요 |

1039 1039

1040<h3 id="systempromptcustom">1040<h3 id="systempromptcustom">

1041 `SystemPromptCustom`1041 `SystemPromptCustom`

1042</h3>1042</h3>

1043 1043

1044시스템 프롬프트를 문자열로 전달하는 것과 동등한 객체 형식의 사용자 정의 시스템 프롬프트이며, `snapshot`도 설정할 수 있습니다. Python Agent SDK 0.2.153 이상 필요합니다.1044`system_prompt`로 문자열을 전달하는 것과 동등한 객체 형식의 사용자 정의 시스템 프롬프트이며, `snapshot`도 설정할 수 있습니다. `claude-agent-sdk` v0.2.153 이상이 필요합니다.

1045 1045

1046```python theme={null}1046```python theme={null}

1047class SystemPromptCustom(TypedDict):1047class SystemPromptCustom(TypedDict):

1060 `SystemPromptFile`1060 `SystemPromptFile`

1061</h3>1061</h3>

1062 1062

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

1064 1064

1065```python theme={null}1065```python theme={null}

1066class SystemPromptFile(TypedDict):1066class SystemPromptFile(TypedDict):

1087| :- | :- | :- |1087| :- | :- | :- |

1091 1091

1092<h4 id="default-behavior">1092<h4 id="default-behavior">

1093 기본 동작1093 기본 동작

1094</h4>1094</h4>

1095 1095

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

1097 1097

1098<h4 id="why-use-setting_sources">1098<h4 id="why-use-setting_sources">

1099 setting\_sources를 사용하는 이유1099 setting\_sources를 사용하는 이유

1219| `tools` | 아니오 | 허용된 도구 이름의 배열. 생략하면 [서브에이전트가 사용할 수 있는 모든 도구](/docs/ko/sub-agents#available-tools)를 상속합니다 |1219| `tools` | 아니오 | 허용된 도구 이름의 배열. 생략하면 [서브에이전트가 사용할 수 있는 모든 도구](/docs/ko/sub-agents#available-tools)를 상속합니다 |

1220| `disallowedTools` | 아니오 | 에이전트의 도구 세트에서 제거할 도구 이름의 배열. MCP 서버 수준 패턴도 허용됩니다: `mcp__server` 또는 `mcp__server__*`는 해당 서버의 모든 도구를 제거하고, `mcp__*`는 모든 서버의 모든 MCP 도구를 제거합니다 |1220| `disallowedTools` | 아니오 | 에이전트의 도구 세트에서 제거할 도구 이름의 배열. MCP 서버 수준 패턴도 허용됩니다: `mcp__server` 또는 `mcp__server__*`는 해당 서버의 모든 도구를 제거하고, `mcp__*`는 모든 서버의 모든 MCP 도구를 제거합니다 |

1221| `model` | 아니오 | 이 에이전트의 모델 재정의. `"sonnet"`, `"opus"`, `"haiku"`, `"inherit"` 같은 별칭 또는 전체 모델 ID를 허용합니다. 생략하면 Claude Code는 [서브에이전트 모델 순서](/docs/ko/sub-agents#choose-a-model)에서 모델을 선택합니다 |1221| `model` | 아니오 | 이 에이전트의 모델 재정의. `"sonnet"`, `"opus"`, `"haiku"`, `"inherit"` 같은 별칭 또는 전체 모델 ID를 허용합니다. 생략하면 Claude Code는 [서브에이전트 모델 순서](/docs/ko/sub-agents#choose-a-model)에서 모델을 선택합니다 |

1222| `skills` | 아니오 | 이 에이전트가 사용할 수 있는 스킬 이름 목록 |1222| `skills` | 아니오 | 시작 시 에이전트의 컨텍스트에 미리 로드할 스킬 이름 목록. 나열되지 않은 스킬도 Skill 도구를 통해 계속 호출할 수 있습니다 |

1223| `memory` | 아니오 | 이 에이전트의 메모리 소스: `"user"`, `"project"`, 또는 `"local"` |1223| `memory` | 아니오 | 이 에이전트의 메모리 소스: `"user"`, `"project"`, 또는 `"local"` |

1224| `mcpServers` | 아니오 | 이 에이전트가 사용할 수 있는 MCP 서버. 각 항목은 서버 이름 또는 인라인 `{name: config}` dict입니다 |1224| `mcpServers` | 아니오 | 이 에이전트가 사용할 수 있는 MCP 서버. 각 항목은 서버 이름 또는 인라인 `{name: config}` dict입니다 |

1225| `initialPrompt` | 아니오 | 이 에이전트가 주 스레드 에이전트로 실행될 때 첫 사용자 턴으로 자동 제출됨 |1225| `initialPrompt` | 아니오 | 이 에이전트가 주 스레드 에이전트로 실행될 때 첫 사용자 턴으로 자동 제출됨 |

1226| `maxTurns` | 아니오 | 에이전트가 중지되기 전의 최대 에이전트 턴 수 |1226| `maxTurns` | 아니오 | 에이전트가 중지되기 전의 최대 에이전트 턴 수 |

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

1228| `effort` | 아니오 | 이 에이전트의 추론 노력 수준. 명명된 수준 또는 정수를 허용합니다. [`EffortLevel`](#effortlevel) 참조 |1228| `effort` | 아니오 | 이 에이전트의 추론 effort 수준. 명명된 수준 또는 정수를 허용합니다. [`EffortLevel`](#effortlevel) 참조 |

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

1230 1230

1231<Note>1231<Note>

1253 `EffortLevel`1253 `EffortLevel`

1254</h3>1254</h3>

1255 1255

1256생각 깊이를 안내하기 위한 노력 수준입니다.1256사고 깊이를 안내하기 위한 effort 수준입니다.

1257 1257

1258```python theme={null}1258```python theme={null}

1259EffortLevel = Literal[1259EffortLevel = Literal[

1285 1285

1286`PermissionResult` (`PermissionResultAllow` 또는 `PermissionResultDeny`)를 반환합니다.1286`PermissionResult` (`PermissionResultAllow` 또는 `PermissionResultDeny`)를 반환합니다.

1287 1287

1288콜백은 대화형 권한 프롬프트의 SDK 대체입니다: [권한 평가 흐름](/docs/ko/agent-sdk/permissions#how-permissions-are-evaluated)이 프롬프트로 해결될 때만 호출됩니다. `allowed_tools` 항목, 설정 허용 규칙 또는 `acceptEdits` 또는 `bypassPermissions`와 같은 권한 모드로 이미 승인된 도구 호출은 이를 호출하지 않습니다. 모든 도구 호출을 제어하려면 [`PreToolUse` hook](/docs/ko/agent-sdk/hooks)을 대신 사용합니다.1288콜백은 대화형 권한 프롬프트의 SDK 대체입니다: [권한 평가 흐름](/docs/ko/agent-sdk/permissions#how-permissions-are-evaluated)이 프롬프트로 해결될 때만 호출됩니다. `allowed_tools` 항목, 설정 허용 규칙 또는 `acceptEdits` 또는 `bypassPermissions`와 같은 권한 모드로 이미 승인된 도구 호출은 이를 호출하지 않습니다. 모든 도구 호출을 제어하려면 [`PreToolUse` 훅](/docs/ko/agent-sdk/hooks)을 대신 사용합니다.

1289 1289

1290허용 규칙이 일치하더라도 [모든 모드가 자동 승인하지 않는 작업](/docs/ko/permission-modes#actions-no-mode-auto-approves)에 도달합니다. [권한 평가 방식](/docs/ko/agent-sdk/permissions#how-permissions-are-evaluated)에서 콜백에 도달하는 것과 `dontAsk` 및 `auto` 모드에서 발생하는 일을 참조하십시오.1290허용 규칙은 [어떤 모드도 자동 승인하지 않는 작업](/docs/ko/permission-modes#actions-no-mode-auto-approves)을 사전 승인하지 않습니다. 이 중 어떤 작업이 콜백에 도달하는지, 그리고 `dontAsk` 및 `auto` 모드에서 어떤 일이 발생하는지는 [권한 평가 방식](/docs/ko/agent-sdk/permissions#how-permissions-are-evaluated)을 참조하십시오.

1291 1291

1292<h3 id="toolpermissioncontext">1292<h3 id="toolpermissioncontext">

1293 `ToolPermissionContext`1293 `ToolPermissionContext`

1313| :- | :- | :- |1313| :- | :- | :- |

1315| `suggestions` | `list[PermissionUpdate]` | CLI의 권한 업데이트 제안. Bash 프롬프트는 `localSettings` 대상이 있는 제안을 포함하므로, `updated_permissions`에서 반환하면 규칙을 `.claude/settings.local.json`에 쓰고 세션 간에 유지합니다. |1315| `suggestions` | `list[PermissionUpdate]` | CLI의 권한 업데이트 제안. Bash 프롬프트는 `localSettings` 대상이 있는 제안을 포함하므로, `updated_permissions`에서 반환하면 규칙을 `.claude/settings.local.json`에 쓰고 세션 간에 유지합니다. |

1408 1408

1409<h3 id="permissionrulevalue">1409<h3 id="permissionrulevalue">

1435 `ThinkingConfig`1435 `ThinkingConfig`

1436</h3>1436</h3>

1437 1437

1438확장된 생각 동작을 제어합니다. 세 가지 구성의 합집합입니다:1438확장 사고 동작을 제어합니다. 세 가지 구성의 합집합입니다:

1439 1439

1440```python theme={null}1440```python theme={null}

1441ThinkingDisplay = Literal["summarized", "omitted"]1441ThinkingDisplay = Literal["summarized", "omitted"]

1461 1461

1462| 변형 | 필드 | 설명 |1462| 변형 | 필드 | 설명 |

1463| :- | :- | :- |1463| :- | :- | :- |

1467 1467

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

1469 1469

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

1471 1471

1485 `TaskBudget`1485 `TaskBudget`

1486</h3>1486</h3>

1487 1487

1488`ClaudeAgentOptions`의 `task_budget` 필드와 함께 사용되는 토큰의 API 측 작업 예산입니다.1488`ClaudeAgentOptions`의 `task_budget` 필드와 함께 사용되는 토큰 단위의 API 측 작업 예산입니다.

1489 1489

1490```python theme={null}1490```python theme={null}

1491class TaskBudget(TypedDict):1491class TaskBudget(TypedDict):

1660 apiUsage: NotRequired[dict[str, Any] | None]1660 apiUsage: NotRequired[dict[str, Any] | None]

1661```1661```

1662 1662

1663각 `ContextUsageCategory` 항목은 `name`, `tokens`, `color` 및 선택적 `isDeferred` 플래그를 포함합니다. `totalTokens`는 세션의 현재 컨텍스트 사용량이고, `maxTokens`는 사용량이 측정되는 윈도우입니다. 해당 윈도우는 모델의 컨텍스트 윈도우이거나, 적용되는 자동 압축 윈도우이며, `rawMaxTokens`는 `maxTokens`와 동일한 값을 포함합니다. `apiUsage`는 세션의 실행 총계가 아닌 최신 API 응답의 사용량을 보유합니다. Claude Code는 선택적 `deferredBuiltinTools`, `systemTools` 및 `systemPromptSections` 키를 설정하지 않으므로, 타입이 이를 선언하더라도 이들이 없을 것으로 예상합니다.1663각 `ContextUsageCategory` 항목은 `name`, `tokens`, `color` 및 선택적 `isDeferred` 플래그를 포함합니다. `totalTokens`는 세션의 현재 컨텍스트 사용량이고, `maxTokens`는 사용량이 측정되는 윈도우입니다. 해당 윈도우는 모델의 컨텍스트 윈도우이거나, 적용되는 경우 더 작은 자동 압축 윈도우이며, `rawMaxTokens`는 `maxTokens`와 동일한 값을 포함합니다. `apiUsage`는 세션의 실행 총계가 아닌 최신 API 응답의 사용량을 보유합니다. Claude Code는 선택적 `deferredBuiltinTools`, `systemTools` 및 `systemPromptSections` 키를 설정하지 않으므로, 타입이 이를 선언하더라도 이들이 없을 것으로 예상합니다.

1664 1664

1665<h3 id="sdkpluginconfig">1665<h3 id="sdkpluginconfig">

1666 `SdkPluginConfig`1666 `SdkPluginConfig`

1677| 필드 | 타입 | 설명 |1677| 필드 | 타입 | 설명 |

1678| :- | :- | :- |1678| :- | :- | :- |

1680| `path` | `str` | 플러그인 디렉토리의 절대 또는 상대 경로 |1680| `path` | `str` | 플러그인 디렉터리의 절대 또는 상대 경로 |

1681 1681

1682**예제:**1682**예제:**

1683 1683

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

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

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

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

1878 1879

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

1880 `StreamEvent`1881 `StreamEvent`

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

2167```2168```

2168 2169

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

2170 2171

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

2172 `CLINotFoundError`2173 `CLINotFoundError`

2216 `ResultError`2217 `ResultError`

2217</h3>2218</h3>

2218 2219

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

2220 2221

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

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

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

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

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

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

2653 2654

2654 2655

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

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

2768</h2>2769</h2>

2769 2770

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

2771 2772

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

2773 2774

agent-sdk/structured-outputs.md +2 −2

Details

60 60

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

62 62

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

64 64

65<CodeGroup>65<CodeGroup>

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

388 오류 처리388 오류 처리

389</h2>389</h2>

390 390

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

392 392

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

394 394

agent-sdk/typescript.md +197 −189

Details

6 6

7> TypeScript Agent SDK의 완전한 API 참조로, 모든 함수, 타입 및 인터페이스를 포함합니다.7> TypeScript Agent SDK의 완전한 API 참조로, 모든 함수, 타입 및 인터페이스를 포함합니다.

8 8

~~9<script src="/docs/components/typescript-sdk-type-links.js" defer />~~

11<h2 id="installation">9<h2 id="installation">

12 설치10 설치

13</h2>11</h2>

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

187});185});

188 186

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

188 for await (const message of claimedQuery) {

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

190 }

191} catch (error) {

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

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

191}194}

192```195```

193 196

538 541

539| 속성 | 타입 | 기본값 | 설명 |542| 속성 | 타입 | 기본값 | 설명 |

540| :- | :- | :- | :- |543| :- | :- | :- | :- |

542| `additionalDirectories` | `string[]` | `[]` | Claude가 접근할 수 있는 추가 디렉터리입니다. SDK는 각 항목을 `--add-dir`로 Claude Code에 전달하므로, `project` 설정 소스를 사용하면 Claude Code는 [해당 디렉터리의 스킬, 명령, 서브에이전트도 로드합니다](/docs/ko/permissions#additional-directories-grant-file-access-not-configuration) |545| `additionalDirectories` | `string[]` | `[]` | Claude가 액세스할 수 있는 추가 디렉터리입니다. SDK는 각 항목을 `--add-dir`로 Claude Code에 전달하므로, `project` 설정 소스를 사용하면 Claude Code는 [해당 디렉터리의 스킬, 명령, 서브에이전트도 로드합니다](/docs/ko/permissions#additional-directories-grant-file-access-not-configuration) |

546| `allowDangerouslySkipPermissions` | `boolean` | `false` | 권한 우회를 활성화합니다. 시작 시 또는 이후 `setPermissionMode()`를 통해 `permissionMode: 'bypassPermissions'`를 사용할 때 필요합니다. `permissionMode: 'plan'`과의 상호작용은 [플랜 모드](/docs/ko/agent-sdk/permissions#plan-mode-plan)를 참조하세요 |549| `allowDangerouslySkipPermissions` | `boolean` | `false` | 권한 우회를 활성화합니다. 시작 시 또는 이후 `setPermissionMode()`를 통해 `permissionMode: 'bypassPermissions'`를 사용할 때 필요합니다. `permissionMode: 'plan'`과의 상호 작용 방식은 [플랜 모드](/docs/ko/agent-sdk/permissions#plan-mode-plan)를 참조하세요 |

547| `allowedTools` | `string[]` | `[]` | 확인 요청 없이 자동 승인할 도구입니다. Claude가 이 도구만 사용하도록 제한하지는 않습니다. 여기에 [작업 추적 도구](/docs/ko/agent-sdk/todo-tracking#model-availability) 중 하나를 지정하면 Claude Code는 해당 세션에서도 이를 활성화합니다. 목록에 없는 다른 도구는 `permissionMode`와 `canUseTool`로 넘어갑니다. 도구를 차단하려면 `disallowedTools`를 사용하세요. [권한](/docs/ko/agent-sdk/permissions#allow-and-deny-rules)을 참조하세요 |550| `allowedTools` | `string[]` | `[]` | 확인을 요청하지 않고 자동 승인할 도구입니다. Claude가 이 도구만 사용하도록 제한하지는 않습니다. 여기에 [작업 추적 도구](/docs/ko/agent-sdk/todo-tracking#model-availability) 중 하나를 지정하면 Claude Code는 세션에서도 해당 기능을 활성화합니다. 목록에 없는 다른 도구는 `permissionMode`와 `canUseTool`로 넘어갑니다. 도구를 차단하려면 `disallowedTools`를 사용하세요. [권한](/docs/ko/agent-sdk/permissions#allow-and-deny-rules)을 참조하세요 |

549| `canUseTool` | [`CanUseTool`](#canusetool) | `undefined` | 사용자 지정 권한 함수로, [권한 흐름](/docs/ko/agent-sdk/permissions#how-permissions-are-evaluated)이 프롬프트로 넘어갈 때만 호출됩니다. `allowedTools`, 허용 규칙 또는 `permissionMode`로 자동 승인된 호출에는 호출되지 않습니다. 허용 규칙은 [어떤 모드도 자동 승인하지 않는 작업](/docs/ko/permission-modes#actions-no-mode-auto-approves)을 사전 승인하지 않습니다. 자세한 내용은 [`CanUseTool`](#canusetool)을 참조하세요 |552| `canUseTool` | [`CanUseTool`](#canusetool) | `undefined` | 사용자 지정 권한 함수로, [권한 흐름](/docs/ko/agent-sdk/permissions#how-permissions-are-evaluated)이 프롬프트로 넘어갈 때만 호출됩니다. `allowedTools`, 허용 규칙 또는 `permissionMode`에 의해 자동 승인된 호출에는 호출되지 않습니다. 허용 규칙은 [어떤 모드도 자동 승인하지 않는 작업](/docs/ko/permission-modes#actions-no-mode-auto-approves)을 미리 승인하지 않습니다. 자세한 내용은 [`CanUseTool`](#canusetool)을 참조하세요 |

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

557| `env` | `Record<string, string \| undefined>` | `process.env` | 환경 변수입니다. 설정하면 `process.env`와 병합되는 대신 하위 프로세스 환경을 대체하므로, `PATH`와 같은 상속된 변수를 유지하려면 `{ ...process.env, YOUR_VAR: 'value' }`를 전달하세요. 이 패턴의 예시는 [느리거나 멈춘 API 응답 처리](#handle-slow-or-stalled-api-responses)를, 기본 CLI가 읽는 변수는 [환경 변수](/docs/ko/env-vars)를 참조하세요. User-Agent 헤더에서 앱을 식별하려면 `CLAUDE_AGENT_SDK_CLIENT_APP`을 설정하세요 |560| `env` | `Record<string, string \| undefined>` | `process.env` | 환경 변수입니다. 설정하면 `process.env`와 병합되는 대신 하위 프로세스 환경을 대체하므로, `PATH`와 같은 상속된 변수를 유지하려면 `{ ...process.env, YOUR_VAR: 'value' }`를 전달하세요. 이 패턴의 예는 [느리거나 멈춘 API 응답 처리](#handle-slow-or-stalled-api-responses)를, 기본 CLI가 읽는 변수는 [환경 변수](/docs/ko/env-vars)를 참조하세요. User-Agent 헤더에서 앱을 식별하려면 `CLAUDE_AGENT_SDK_CLIENT_APP`을 설정하세요 |

560| `extraArgs` | `Record<string, string \| null>` | `{}` | 추가 인수 |563| `extraArgs` | `Record<string, string \| null>` | `{}` | 추가 인수입니다 |

561| `fallbackModel` | `string` | `undefined` | 기본 모델이 실패할 경우 사용할 모델입니다. 쉼표로 구분된 목록을 허용합니다. 순서와 상한은 [폴백 모델 체인](/docs/ko/model-config#fallback-model-chains)을 참조하세요. 안내는 [모델 선택](/docs/ko/agent-sdk/configuration#choose-a-model)을 참조하세요 |564| `fallbackModel` | `string` | `undefined` | 기본 모델이 실패할 경우 사용할 모델입니다. 쉼표로 구분된 목록을 허용합니다. 순서와 상한은 [폴백 모델 체인](/docs/ko/model-config#fallback-model-chains)을 참조하세요. 가이드는 [모델 선택](/docs/ko/agent-sdk/configuration#choose-a-model)을 참조하세요 |

563| `forwardSubagentText` | `boolean` | `false` | 서브에이전트의 텍스트 및 thinking 블록을 `parent_tool_use_id`가 설정된 어시스턴트 및 사용자 메시지로 전달하여, 소비자가 중첩된 트랜스크립트를 렌더링할 수 있도록 합니다. 이 옵션이 없으면 Claude Code는 서브에이전트의 `tool_use` 및 `tool_result` 블록은 내보내지만 텍스트나 사고는 내보내지 않습니다. Claude Code v2.1.219 이상에서는 모든 중첩 깊이의 서브에이전트 메시지가 전달되며, v2.1.219 이전에는 깊이 1 서브에이전트의 메시지만 표시되었습니다. 포크된 스킬이 생성한 서브에이전트와 중첩된 포크 스킬의 메시지는 v2.1.275 이상이 필요합니다 |566| `forwardSubagentText` | `boolean` | `false` | 서브에이전트의 텍스트 및 thinking 블록을 `parent_tool_use_id`가 설정된 assistant 및 user 메시지로 전달하여, 소비자가 중첩된 트랜스크립트를 렌더링할 수 있게 합니다. 이 옵션이 없으면 Claude Code는 [포그라운드](/docs/ko/sub-agents#run-subagents-in-foreground-or-background)에서 실행되는 서브에이전트의 텍스트 및 thinking 블록을 생략합니다. 중첩된 서브에이전트, `context: fork`가 있는 스킬, 그리고 각각에 필요한 Claude Code 버전은 [서브에이전트 메시지 따라가기](/docs/ko/headless#follow-subagent-messages)를 참조하세요 |

564| `hooks` | `Partial<Record<`[`HookEvent`](#hookevent)`, `[`HookCallbackMatcher`](#hookcallbackmatcher)`[]>>` | `{}` | 이벤트에 대한 훅 콜백 |567| `hooks` | `Partial<Record<`[`HookEvent`](#hookevent)`, `[`HookCallbackMatcher`](#hookcallbackmatcher)`[]>>` | `{}` | 이벤트에 대한 훅 콜백입니다 |

565| `includeHookEvents` | `boolean` | `false` | 훅 수명 주기 이벤트를 [`SDKHookStartedMessage`](#sdkhookstartedmessage), [`SDKHookProgressMessage`](#sdkhookprogressmessage), [`SDKHookResponseMessage`](#sdkhookresponsemessage)로 메시지 스트림에 포함합니다. `SessionStart` 및 `Setup` 훅의 수명 주기 이벤트는 항상 포함되며 이 옵션이 필요하지 않습니다. `Notification`, `SessionEnd`, `PreCompact`, `PostCompact`와 같은 일부 훅 이벤트는 이 옵션을 사용해도 `SDKHookStartedMessage`를 생성하지 않습니다. 이러한 이벤트의 경우에도 Claude Code는 1초 이상 실행되는 명령 훅이 출력을 생성하는 동안 `SDKHookProgressMessage`를 내보내며, [백그라운드에서 실행되는](/docs/ko/hooks#run-hooks-in-the-background) 훅이 완료될 때만 `SDKHookResponseMessage`를 내보냅니다 |568| `includeHookEvents` | `boolean` | `false` | 훅 라이프사이클 이벤트를 [`SDKHookStartedMessage`](#sdkhookstartedmessage), [`SDKHookProgressMessage`](#sdkhookprogressmessage), [`SDKHookResponseMessage`](#sdkhookresponsemessage)로 메시지 스트림에 포함합니다. `SessionStart` 및 `Setup` 훅의 라이프사이클 이벤트는 항상 포함되며 이 옵션이 필요하지 않습니다. `Notification`, `SessionEnd`, `PreCompact`, `PostCompact`와 같은 일부 훅 이벤트는 이 옵션을 사용하더라도 `SDKHookStartedMessage`를 생성하지 않습니다. 이러한 이벤트의 경우에도 Claude Code는 1초 이상 실행되는 명령 훅이 출력을 생성하는 동안 `SDKHookProgressMessage`를 내보내며, [백그라운드에서 실행되는](/docs/ko/hooks#run-hooks-in-the-background) 훅이 완료될 때만 `SDKHookResponseMessage`를 내보냅니다 |

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

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

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

574| `onElicitation` | `(request: ElicitationRequest, options: { signal: AbortSignal }) => Promise<ElicitationResult>` | `undefined` | MCP elicitation 요청을 처리하는 콜백입니다. MCP 서버가 사용자 입력을 요청하고 이를 먼저 처리하는 훅이 없을 때 호출됩니다. 제공되지 않으면 처리되지 않은 elicitation 요청은 자동으로 거절됩니다 |577| `onElicitation` | `(request: ElicitationRequest, options: { signal: AbortSignal }) => Promise<ElicitationResult>` | `undefined` | MCP elicitation 요청을 처리하는 콜백입니다. MCP 서버가 사용자 입력을 요청하고 이를 먼저 처리하는 훅이 없을 때 호출됩니다. 제공되지 않으면 처리되지 않은 elicitation 요청은 자동으로 거부됩니다 |

575| `outputFormat` | `{ type: 'json_schema', schema: JSONSchema }` | `undefined` | 에이전트 결과의 출력 형식을 정의합니다. 자세한 내용은 [구조화된 출력](/docs/ko/agent-sdk/structured-outputs)을 참조하세요 |578| `outputFormat` | `{ type: 'json_schema', schema: JSONSchema }` | `undefined` | 에이전트 결과의 출력 형식을 정의합니다. 자세한 내용은 [구조화된 출력](/docs/ko/agent-sdk/structured-outputs)을 참조하세요 |

576| `outputStyle` | `string` | `undefined` | `Options` 필드가 아닙니다. 대신 인라인 [`settings`](/docs/ko/settings) 객체나 설정 파일에서 `outputStyle`을 설정하세요. [출력 스타일 활성화](/docs/ko/agent-sdk/modifying-system-prompts#activate-an-output-style)를 참조하세요 |579| `outputStyle` | `string` | `undefined` | `Options` 필드가 아닙니다. 대신 인라인 [`settings`](/docs/ko/settings) 객체나 설정 파일에서 `outputStyle`을 설정하세요. [출력 스타일 활성화](/docs/ko/agent-sdk/modifying-system-prompts#activate-an-output-style)를 참조하세요 |

578| `permissionMode` | [`PermissionMode`](#permissionmode) | `undefined` | 세션의 권한 모드입니다. 생략하면 세션이 자동 모드로 시작될 수 있습니다. Claude Code가 시작 권한 모드를 선택하는 방법은 [권한 모드](/docs/ko/agent-sdk/permissions#permission-modes)를 참조하세요 |581| `permissionMode` | [`PermissionMode`](#permissionmode) | `undefined` | 세션의 권한 모드입니다. 생략하면 세션이 자동 모드로 시작될 수 있습니다. Claude Code가 시작 권한 모드를 선택하는 방식은 [권한 모드](/docs/ko/agent-sdk/permissions#permission-modes)를 참조하세요 |

580| `permissionPrompts` | `'host' \| 'none'` | `'host'` | 권한 프롬프트에 응답하는 주체입니다. `'host'`는 프롬프트를 [`canUseTool`](#canusetool) 콜백 또는 `permissionPromptToolName` 도구로 라우팅하고, `'none'`은 [프롬프트가 표시되었을 호출을 거부합니다](/docs/ko/agent-sdk/permissions#how-permissions-are-evaluated). Claude Code v2.1.259 이상이 필요합니다 |583| `permissionPrompts` | `'host' \| 'none'` | `'host'` | 권한 프롬프트에 응답하는 주체입니다. `'host'`는 프롬프트를 [`canUseTool`](#canusetool) 콜백 또는 `permissionPromptToolName` 도구로 라우팅하고, `'none'`은 [프롬프트를 표시했을 호출을 거부합니다](/docs/ko/agent-sdk/permissions#how-permissions-are-evaluated). Claude Code v2.1.259 이상이 필요합니다 |

584| `projectConfigRoot` | `string` | `undefined` | `cwd`가 worktree로 속한 신뢰할 수 있는 체크아웃의 절대 경로입니다. Claude Code는 프로젝트 설정, `.mcp.json`, 프로젝트의 `.claude/` 명령, 에이전트, 스킬, 워크플로, 루틴, 출력 스타일을 `cwd` 대신 이 디렉터리에서 읽고, `CLAUDE_PROJECT_DIR`을 이 경로로 설정합니다. 훅, `apiKeyHelper`와 같은 헬퍼 스크립트, stdio MCP 서버는 이 디렉터리를 작업 디렉터리로 하여 시작됩니다. `CLAUDE.md` 파일과 `.claude/rules/`는 여전히 `cwd`에서 로드됩니다. Claude Code v2.1.275 이상이 필요합니다 |587| `projectConfigRoot` | `string` | `undefined` | `cwd`를 worktree로 두는 신뢰할 수 있는 체크아웃의 절대 경로입니다. Claude Code는 프로젝트 설정, `.mcp.json`, 프로젝트의 `.claude/` 명령, 에이전트, 스킬, 워크플로, 루틴, 출력 스타일을 `cwd` 대신 이 디렉터리에서 읽고, `CLAUDE_PROJECT_DIR`을 이 디렉터리로 설정합니다. 훅, `apiKeyHelper`와 같은 헬퍼 스크립트, stdio MCP 서버는 이 디렉터리를 작업 디렉터리로 하여 시작됩니다. `CLAUDE.md` 파일과 `.claude/rules/`는 여전히 `cwd`에서 로드됩니다. Claude Code v2.1.275 이상이 필요합니다 |

585| `promptSuggestions` | `boolean` | `false` | 프롬프트 제안을 활성화합니다. 턴이 끝난 후 Claude Code는 예측된 다음 사용자 프롬프트를 담은 `prompt_suggestion` 메시지를 내보냅니다. 계정이 사용 한도에 가깝거나 도달한 경우와 같이 일부 턴에서는 Claude Code가 제안을 생성하지 않습니다. [Claude Code가 제안을 건너뛰는 경우](/docs/ko/interactive-mode#when-claude-code-skips-suggestions)를 참조하세요 |588| `promptSuggestions` | `boolean` | `false` | 프롬프트 제안을 활성화합니다. 턴이 끝나면 Claude Code는 예측된 다음 사용자 프롬프트를 담은 `prompt_suggestion` 메시지를 내보냅니다. 계정이 사용 한도에 가까워졌거나 도달한 경우와 같이 일부 턴에서는 Claude Code가 제안을 생성하지 않습니다. [Claude Code가 제안을 건너뛰는 경우](/docs/ko/interactive-mode#when-claude-code-skips-suggestions)를 참조하세요 |

587| `resumeDropsTurn` | `string` | `undefined` | `resumeSessionAt`과 함께 사용: 잘라내는 재개가 폐기하려는 턴의 프롬프트 UUID입니다. 폐기 범위에 흡수된 대기 메시지나 작업 알림처럼 해당 턴에 귀속되지 않는 항목이 포함되어 있으면 Claude Code는 재개를 거부하고, 거부 메시지에 `--resume-drops-turn` 플래그를 명시합니다. Agent SDK와 print 모드 재개만 이 쌍을 읽습니다. Claude Code v2.1.223 이상이 필요합니다 |590| `resumeDropsTurn` | `string` | `undefined` | `resumeSessionAt`과 함께 사용합니다. 잘라내는 재개가 버리려는 턴의 프롬프트 UUID입니다. 버려지는 범위에 흡수된 대기 메시지나 작업 알림처럼 해당 턴에 귀속되지 않는 항목이 포함되어 있으면 Claude Code는 재개를 거부하고, 거부 메시지에 `--resume-drops-turn` 플래그를 명시합니다. 이 쌍은 Agent SDK 및 print 모드 재개에서만 읽습니다. Claude Code v2.1.223 이상이 필요합니다 |

591| `sessionStore` | [`SessionStore`](/docs/ko/agent-sdk/session-storage#the-sessionstore-interface) | `undefined` | 다른 호스트가 재개할 수 있도록 세션 트랜스크립트를 외부 백엔드에 미러링합니다. [외부 스토리지에 세션 영속화](/docs/ko/agent-sdk/session-storage)를 참조하세요 |594| `sessionStore` | [`SessionStore`](/docs/ko/agent-sdk/session-storage#the-sessionstore-interface) | `undefined` | 다른 호스트가 재개할 수 있도록 세션 트랜스크립트를 외부 백엔드에 미러링합니다. [외부 스토리지에 세션 유지](/docs/ko/agent-sdk/session-storage)를 참조하세요 |

594| `settingSources` | [`SettingSource`](#settingsource)`[]` | CLI 기본값(모든 소스) | 로드할 파일 시스템 설정을 제어합니다. 사용자, 프로젝트, 로컬 설정을 비활성화하려면 `[]`를 전달하세요. [엔드포인트 관리 정책](/docs/ko/managed-settings#delivery-mechanisms)은 관계없이 로드되며, 서버 관리 설정은 세션이 [적격 구성](/docs/ko/server-managed-settings#platform-availability)에서 조직 자격 증명으로 인증할 때 가져옵니다. [Claude Code 기능 사용](/docs/ko/agent-sdk/claude-code-features#what-settingsources-does-not-control)을 참조하세요 |597| `settingSources` | [`SettingSource`](#settingsource)`[]` | CLI 기본값(모든 소스) | 로드할 파일 시스템 설정을 제어합니다. 사용자, 프로젝트, 로컬 설정을 비활성화하려면 `[]`를 전달하세요. [엔드포인트 관리형 정책](/docs/ko/managed-settings#delivery-mechanisms)은 이와 관계없이 로드되며, 서버 관리형 설정은 세션이 [적격 구성](/docs/ko/server-managed-settings#platform-availability)에서 조직 자격 증명으로 인증할 때 가져옵니다. [Claude Code 기능 사용](/docs/ko/agent-sdk/claude-code-features#what-settingsources-does-not-control)을 참조하세요 |

595| `skills` | `string[] \| 'all'` | `undefined` | 세션에서 사용할 수 있는 스킬입니다. 발견된 모든 스킬을 활성화하려면 `'all'`을, 또는 스킬 이름 목록을 전달하세요. 정확한 이름만 전달하세요. Agent SDK v0.3.221 이상에서 SDK는 Claude Code 프로세스를 시작하기 전에 잘못된 형식 및 와일드카드 형식의 이름을 오류와 함께 거부합니다. 설정하면 SDK가 Skill 도구를 `allowedTools`에 자동으로 추가합니다. `tools`도 전달하는 경우 해당 목록에 `'Skill'`을 포함하세요. [스킬](/docs/ko/agent-sdk/skills)을 참조하세요 |598| `skills` | `string[] \| 'all'` | `undefined` | 세션에서 사용할 수 있는 스킬입니다. 발견된 모든 스킬을 활성화하려면 `'all'`을 전달하고, 그렇지 않으면 스킬 이름 목록을 전달하세요. 정확한 이름만 전달하세요. Agent SDK v0.3.221 이상에서는 SDK가 Claude Code 프로세스를 시작하기 전에 잘못된 형식 및 와일드카드 형식의 이름을 오류와 함께 거부합니다. 설정하면 SDK가 Skill 도구를 `allowedTools`에 자동으로 추가합니다. `tools`도 전달하는 경우 해당 목록에 `'Skill'`을 포함하세요. [스킬](/docs/ko/agent-sdk/skills)을 참조하세요 |

599| `systemPrompt` | `string \| string[] \| { type: 'custom'; prompt: string \| string[]; snapshot?: boolean } \| { type: 'preset'; preset: 'claude_code'; append?: string; excludeDynamicSections?: boolean; snapshot?: boolean }` | `undefined` (최소 프롬프트) | 시스템 프롬프트 구성입니다. 사용자 지정 프롬프트에는 문자열을, Claude Code의 시스템 프롬프트를 사용하려면 `{ type: 'preset', preset: 'claude_code' }`를 전달하세요. 정적 부분과 요청별 부분 사이에 내보낸 `SYSTEM_PROMPT_DYNAMIC_BOUNDARY` 상수를 넣은 문자열 배열을 전달하면 [사용자 지정 프롬프트의 정적 부분을 캐시](/docs/ko/agent-sdk/modifying-system-prompts#cache-the-static-part-of-a-custom-prompt)할 수 있습니다. 프리셋 객체 형식을 사용할 때 `append`를 추가하여 추가 지침으로 확장하고, `excludeDynamicSections: true`를 설정하여 세션별 컨텍스트를 첫 번째 사용자 메시지로 옮기면 [머신 간 프롬프트 캐시 재사용을 개선](/docs/ko/agent-sdk/modifying-system-prompts#improve-prompt-caching-across-users-and-machines)할 수 있습니다. [세션이 첫 요청에서 기록한 프롬프트를 재사용](/docs/ko/agent-sdk/modifying-system-prompts#change-the-prompt-of-an-existing-session)하는 대신 매 요청마다 프롬프트를 다시 빌드하려면 `snapshot: false`를 설정하세요. 사용자 지정 프롬프트에 `snapshot`을 설정하려면 `{ type: 'custom', prompt }` 형식을 전달하세요. `{ type: 'custom' }` 형식과 `snapshot` 필드는 TypeScript Agent SDK v0.3.257 이상이 필요합니다 |602| `systemPrompt` | `string \| string[] \| { type: 'custom'; prompt: string \| string[]; snapshot?: boolean } \| { type: 'preset'; preset: 'claude_code'; append?: string; excludeDynamicSections?: boolean; snapshot?: boolean }` | `undefined` (최소 프롬프트) | 시스템 프롬프트 구성입니다. 사용자 지정 프롬프트에는 문자열을 전달하고, Claude Code의 시스템 프롬프트를 사용하려면 `{ type: 'preset', preset: 'claude_code' }`를 전달하세요. [사용자 지정 프롬프트의 정적 부분을 캐시하려면](/docs/ko/agent-sdk/modifying-system-prompts#cache-the-static-part-of-a-custom-prompt) 정적 부분과 요청별 부분 사이에 내보낸 `SYSTEM_PROMPT_DYNAMIC_BOUNDARY` 상수를 둔 문자열 배열을 전달하세요. 프리셋 객체 형식을 사용할 때는 `append`를 추가하여 추가 지침으로 확장할 수 있으며, `excludeDynamicSections: true`를 설정하면 세션별 컨텍스트를 첫 번째 사용자 메시지로 옮겨 [머신 간 프롬프트 캐시 재사용을 개선](/docs/ko/agent-sdk/modifying-system-prompts#improve-prompt-caching-across-users-and-machines)할 수 있습니다. [세션이 첫 요청에서 기록한 프롬프트를 재사용하는](/docs/ko/agent-sdk/modifying-system-prompts#change-the-prompt-of-an-existing-session) 대신 모든 요청에서 프롬프트를 다시 빌드하려면 `snapshot: false`를 설정하세요. 사용자 지정 프롬프트에 `snapshot`을 설정하려면 `{ type: 'custom', prompt }` 형식을 전달하세요. `{ type: 'custom' }` 형식과 `snapshot` 필드에는 TypeScript Agent SDK v0.3.257 이상이 필요합니다 |

600| `taskBudget` | `{ total: number }` | `undefined` | *Alpha.* 토큰 단위의 API 측 작업 예산입니다. 설정하면 모델에 남은 토큰 예산이 전달되어 도구 사용 속도를 조절하고 한도 전에 마무리할 수 있습니다 |603| `taskBudget` | `{ total: number }` | `undefined` | *알파.* 토큰 단위의 API 측 작업 예산입니다. 설정하면 모델에 남은 토큰 예산이 전달되어, 모델이 도구 사용 속도를 조절하고 한도에 도달하기 전에 작업을 마무리할 수 있습니다 |

601| `thinking` | [`ThinkingConfig`](#thinkingconfig) | 지원되는 모델의 경우 `{ type: 'adaptive' }` | Claude의 사고/추론 동작을 제어합니다. 옵션은 [`ThinkingConfig`](#thinkingconfig)를 참조하세요 |604| `thinking` | [`ThinkingConfig`](#thinkingconfig) | 지원되는 모델의 경우 `{ type: 'adaptive' }` | Claude의 사고/추론 동작을 제어합니다. 옵션은 [`ThinkingConfig`](#thinkingconfig)를 참조하세요 |

603| `toolAliases` | `Record<string, string>` | `undefined` | 기본 제공 도구 이름을 MCP 도구 이름에 매핑하여 Claude가 기본 제공 도구 대신 사용자의 MCP 구현을 호출하도록 합니다. 예: `{ Bash: 'mcp__workspace__bash' }` |606| `toolAliases` | `Record<string, string>` | `undefined` | Claude가 기본 제공 도구 대신 사용자의 MCP 구현을 호출하도록 기본 제공 도구 이름을 MCP 도구 이름에 매핑합니다. 예: `{ Bash: 'mcp__workspace__bash' }` |

605| `tools` | `string[] \| { type: 'preset'; preset: 'claude_code' }` | `undefined` | 도구 구성입니다. 도구 이름 배열을 전달하거나 프리셋을 사용하여 Claude Code의 기본 도구를 가져옵니다 |608| `tools` | `string[] \| { type: 'preset'; preset: 'claude_code' }` | `undefined` | 도구 구성입니다. 도구 이름 배열을 전달하거나, 프리셋을 사용하여 Claude Code의 기본 도구를 가져옵니다 |

606| `verbatimPrompts` | `boolean` | `false` | 모든 프롬프트를 작성된 그대로 전달합니다. SDK는 각 사용자 메시지를 `client_composed: true`와 함께 보냅니다. 해당 메시지에서 Claude Code가 건너뛰는 항목은 [`client_composed`](#sdkusermessage)를 참조하세요. 프롬프트 텍스트에 최종 사용자가 입력하지 않은 콘텐츠가 포함된 경우 이 옵션을 사용하세요. 턴별로 제어하려면 이 옵션을 끄고 대신 개별 스트리밍 메시지에 `client_composed`를 설정하세요. TypeScript Agent SDK v0.3.280 이상과 Claude Code v2.1.248 이상이 필요하며, 해당 SDK 버전에 번들된 Claude Code 버전은 Claude Code 요구 사항을 충족합니다 |609| `verbatimPrompts` | `boolean` | `false` | 모든 프롬프트를 작성된 그대로 전달합니다. SDK는 각 사용자 메시지를 `client_composed: true`와 함께 보냅니다. 해당 메시지에서 Claude Code가 건너뛰는 항목은 [`client_composed`](#sdkusermessage)를 참조하세요. 프롬프트 텍스트에 최종 사용자가 입력하지 않은 콘텐츠가 포함된 경우 이 옵션을 사용하세요. 턴별로 제어하려면 이 옵션을 끈 상태로 두고 대신 개별 스트리밍 메시지에 `client_composed`를 설정하세요. TypeScript Agent SDK v0.3.280 이상 및 Claude Code v2.1.248 이상이 필요하며, 해당 SDK 버전에 번들된 Claude Code 버전은 Claude Code 요구 사항을 충족합니다 |

607 610

608<h4 id="handle-slow-or-stalled-api-responses">611<h4 id="handle-slow-or-stalled-api-responses">

609 느리거나 멈춘 API 응답 처리612 느리거나 멈춘 API 응답 처리

610</h4>613</h4>

611 614

612CLI 하위 프로세스는 API 타임아웃과 정체 감지를 제어하는 여러 환경 변수를 읽습니다. `env` 옵션을 통해 전달하세요:615CLI 하위 프로세스는 API 타임아웃과 멈춤 감지를 제어하는 여러 환경 변수를 읽습니다. 이 변수들을 `env` 옵션으로 전달하세요.

613 616

614```typescript theme={null}617```typescript theme={null}

615import { query } from "@anthropic-ai/claude-agent-sdk";618import { query } from "@anthropic-ai/claude-agent-sdk";

628```631```

629 632

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

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

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

633 636

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

635* `CLAUDE_ENABLE_STREAM_WATCHDOG`와 `CLAUDE_STREAM_IDLE_TIMEOUT_MS`: 헤더는 도착했지만 응답 본문의 스트리밍이 멈췄을 때 요청을 중단하는 스트림 감시기입니다. 감시기는 모든 제공자에서 기본적으로 켜져 있으며, 비활성화하려면 `CLAUDE_ENABLE_STREAM_WATCHDOG=0`을 설정하세요. `CLAUDE_STREAM_IDLE_TIMEOUT_MS`의 기본값은 `300000`이며 이 최솟값으로 고정됩니다. 중단 후 Claude Code가 응답 진행 정도에 따라 무엇을 하는지는 [자동 재시도](/docs/ko/errors#automatic-retries)에서 다룹니다.638* `CLAUDE_ENABLE_STREAM_WATCHDOG`과 `CLAUDE_STREAM_IDLE_TIMEOUT_MS`: 헤더는 도착했지만 응답 본문 스트리밍이 멈췄을 때 요청을 중단하는 스트림 감시기입니다. 감시기는 모든 제공업체에서 기본적으로 켜져 있으며, 비활성화하려면 `CLAUDE_ENABLE_STREAM_WATCHDOG=0`을 설정하세요. `CLAUDE_STREAM_IDLE_TIMEOUT_MS`의 기본값은 `300000`이며 이 값보다 작게 설정할 수 없습니다. 중단 후 Claude Code가 응답 진행 정도에 따라 수행하는 작업은 [자동 재시도](/docs/ko/errors#automatic-retries)에서 다룹니다.

636 639

637 `ANTHROPIC_BASE_URL` 뒤의 게이트웨이가 keep-alive 핑으로 열어 둔 응답을 감시기가 기다리는 동안, `includePartialMessages`를 설정한 호스트는 `ping` [스트림 이벤트](#sdkpartialassistantmessage)를 계속 수신하므로, 무응답을 이유로 세션을 타임아웃시키는 대신 이 프레임을 활성 상태 신호로 읽으세요. v2.1.257 이전에는 마지막 실제 스트림 이벤트 후 5분이 지나면 이 프레임이 중단되었습니다.640 `ANTHROPIC_BASE_URL` 뒤의 게이트웨이가 keep-alive ping으로 열어 둔 응답을 감시기가 기다리는 동안, `includePartialMessages`를 설정한 호스트는 `ping` [스트림 이벤트](#sdkpartialassistantmessage)를 계속 수신합니다. 따라서 응답이 없다고 세션을 타임아웃 처리하지 말고 이러한 프레임을 활성 상태 신호로 읽으세요. v2.1.257 이전에는 마지막 실제 스트림 이벤트 후 5분이 지나면 프레임이 중단되었습니다.

638 641

639<h3 id="query-object">642<h3 id="query-object">

640 `Query` 객체643 `Query` 객체

696 699

697| 메서드 | 설명 |700| 메서드 | 설명 |

698| :- | :- |701| :- | :- |

699| `interrupt()` | 쿼리를 중단합니다. 스트리밍 입력 모드에서만 사용할 수 있습니다. CLI가 [`SDKSystemMessage.capabilities`](#sdksystemmessage)에서 `interrupt_receipt_v1` 기능을 알리면, 중단이 도착했을 때 대기 중이던 메시지를 나열하는 [`SDKControlInterruptResponse`](#sdkcontrolinterruptresponse)로 resolve됩니다. v2.1.205 이전 CLI에서는 `undefined`로 resolve됩니다 |702| `interrupt()` | 쿼리를 중단합니다. 스트리밍 입력 모드에서만 사용할 수 있습니다. CLI가 [`SDKSystemMessage.capabilities`](#sdksystemmessage)에서 `interrupt_receipt_v1` 기능을 알리는 경우, 중단 시점에 대기 중이던 메시지를 나열하는 [`SDKControlInterruptResponse`](#sdkcontrolinterruptresponse)로 resolve됩니다. v2.1.205 이전 CLI에서는 `undefined`로 resolve됩니다 |

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

702| `setModel()` | 모델을 변경합니다(스트리밍 입력 모드에서만 사용 가능). `undefined` 또는 문자열 `"default"`를 전달하면 [Claude Code의 기본 모델](/docs/ko/model-config)로 재설정됩니다 |705| `setModel()` | 모델을 변경합니다(스트리밍 입력 모드에서만 사용 가능). `undefined` 또는 문자열 `"default"`를 전달하면 [Claude Code의 기본 모델](/docs/ko/model-config)로 재설정됩니다 |

703| `setMaxThinkingTokens()` | *Deprecated:* 대신 `thinking` 옵션을 사용하세요. 최대 사고 토큰 수를 변경합니다. `null`을 전달하면 사고가 세션 기본값으로 재설정됩니다. 세션 중 재정의는 지워지며, 사고가 비활성화된 세션에서는 사고가 계속 꺼진 상태로 유지됩니다 |706| `setMaxThinkingTokens()` | *지원 중단:* 대신 `thinking` 옵션을 사용하세요. 최대 사고 토큰 수를 변경합니다. `null`을 전달하면 사고가 세션 기본값으로 재설정됩니다. 세션 중 재정의는 지워지며, 사고가 비활성화된 세션에서는 계속 꺼진 상태로 유지됩니다 |

704| `applyFlagSettings(settings)` | 런타임에 세션의 플래그 설정 계층에 설정을 병합합니다(스트리밍 입력 모드에서만 사용 가능). [`applyFlagSettings()`](#applyflagsettings)를 참조하세요 |707| `applyFlagSettings(settings)` | 런타임에 세션의 플래그 설정 계층에 설정을 병합합니다(스트리밍 입력 모드에서만 사용 가능). [`applyFlagSettings()`](#applyflagsettings)를 참조하세요 |

705| `updateSettings(source, settings)` | 허용 목록에 있는 키 하나를 프로젝트의 로컬 설정 파일 또는 사용자 설정 파일에 기록하여 이후 세션에서도 값이 유지되도록 합니다. [`updateSettings()`](#updatesettings)를 참조하세요. Claude Code v2.1.257이 번들된 TypeScript SDK v0.3.257 이상이 필요합니다 |708| `updateSettings(source, settings)` | 허용 목록에 있는 키 하나를 프로젝트의 로컬 설정 파일 또는 사용자 설정 파일에 기록하여, 이후 세션에서도 값이 유지되도록 합니다. [`updateSettings()`](#updatesettings)를 참조하세요. Claude Code v2.1.257이 번들된 TypeScript SDK v0.3.257 이상이 필요합니다 |

707| `reinitialize()` | 실행 중인 CLI에 `initialize` 제어 요청을 다시 보내고, 캐시된 최초 연결 결과 대신 새로운 결과를 반환합니다. 연결 끊김 후 세션에 다시 연결하는 경우처럼 전송 공백이 생긴 뒤에 사용하면, 대기 중인 권한 요청이 `canUseTool` 콜백에 다시 도달합니다. 응답이 유실된 요청은 다시 전달되므로 콜백을 요청 ID별로 멱등하게 만드세요. Claude Code v2.1.195 이상이 필요합니다 |710| `reinitialize()` | 실행 중인 CLI에 `initialize` 제어 요청을 다시 보내고, 캐시된 첫 연결 결과 대신 새 결과를 반환합니다. 연결이 끊긴 후 세션에 다시 연결하는 경우와 같이 전송 공백이 발생한 후에 사용하면, 대기 중인 권한 요청이 `canUseTool` 콜백에 다시 전달됩니다. 응답이 유실된 요청은 다시 전달되므로 콜백을 요청 ID별로 멱등하게 만드세요. Claude Code v2.1.195 이상이 필요합니다 |

708| `supportedCommands()` | 사용 가능한 명령을 반환합니다. Agent SDK v0.3.216부터 목록에 세션 중 명령 변경 사항이 반영됩니다. [`SDKCommandsChangedMessage`](#sdkcommandschangedmessage)를 참조하세요 |711| `supportedCommands()` | 사용 가능한 명령을 반환합니다. Agent SDK v0.3.216부터 이 목록에는 세션 중 명령 변경 사항이 반영됩니다. [`SDKCommandsChangedMessage`](#sdkcommandschangedmessage)를 참조하세요 |

712| `getContextUsage(opts?)` | 세션의 컨텍스트 윈도우 사용량을 카테고리, 스킬, 도구별로 분류한 [`SDKControlGetContextUsageResponse`](#sdkcontrolgetcontextusageresponse)를 반환합니다. 기본 `detail`에서는 대화형 세션에서 `/context`가 보여 주는 것과 동일한 데이터이며, 메시지 스트림에 나타나지 않는 토큰 계산 API 요청으로 계산됩니다. [이러한 요청이 처리되는 방식](#sdkcontrolgetcontextusageresponse)을 참조하세요. [`detail` 옵션](#sdkcontrolgetcontextusageresponse)은 Agent SDK v0.3.257 이상이 필요합니다 |715| `getContextUsage(opts?)` | 세션의 컨텍스트 윈도우 사용량을 카테고리, 스킬, 도구별로 분류한 [`SDKControlGetContextUsageResponse`](#sdkcontrolgetcontextusageresponse)를 반환합니다. 기본 `detail`을 사용하면 대화형 세션에서 `/context`가 표시하는 것과 동일한 데이터이며, 메시지 스트림에 나타나지 않는 토큰 계산 API 요청으로 계산됩니다. [이러한 요청이 처리되는 방식](#sdkcontrolgetcontextusageresponse)을 참조하세요. [`detail` 옵션](#sdkcontrolgetcontextusageresponse)에는 Agent SDK v0.3.257 이상이 필요합니다 |

713| `readFile(path, options?)` | 세션의 파일 시스템에서 파일을 읽습니다. Claude Code는 경로를 `cwd` 기준으로 확인하며, 제공하는 파일 목록은 [`readFile()`이 읽을 수 있는 항목](#what-readfile-can-read)에 나와 있습니다. 읽기 상한을 변경하려면 `{ maxBytes }`를(기본값 1 MB, 최대 10 MB), 이미지와 같은 바이너리 파일에는 `{ encoding: 'base64' }`를 전달하세요. [`SDKControlReadFileResponse`](#sdkcontrolreadfileresponse)로 resolve되며, 권한 거부, 파일 없음 또는 전송 오류 시에는 `null`로 resolve됩니다. TypeScript SDK v0.2.121 이상이 필요합니다 |716| `readFile(path, options?)` | 세션의 파일 시스템에서 파일을 읽습니다. Claude Code는 `cwd`를 기준으로 경로를 확인하며, 제공하는 파일은 [`readFile()`이 읽을 수 있는 파일](#what-readfile-can-read)에 나열되어 있습니다. 읽기 상한을 변경하려면 `{ maxBytes }`를 전달하고(기본값 1 MB, 최대 10 MB), 이미지와 같은 바이너리 파일에는 `{ encoding: 'base64' }`를 전달하세요. [`SDKControlReadFileResponse`](#sdkcontrolreadfileresponse)로 resolve되며, 권한 거부, 파일 없음 또는 전송 오류 시에는 `null`로 resolve됩니다. TypeScript SDK v0.2.121 이상이 필요합니다 |

714| `reloadPlugins(options?)` | 디스크에서 플러그인을 다시 로드하여, 세션 중에 설치하거나 편집한 플러그인이 실행 중인 세션에 반영되도록 합니다. 세션의 명령, 서브에이전트, 플러그인, MCP 서버 상태를 나열하는 [`SDKControlReloadPluginsResponse`](#sdkcontrolreloadpluginsresponse)로 resolve됩니다. Agent SDK v0.2.85 이상이 필요합니다. [`holdOnCacheImpact` 옵션](#sdkcontrolreloadpluginsresponse)은 Agent SDK v0.3.268 이상이 필요합니다 |717| `reloadPlugins(options?)` | 디스크에서 플러그인을 다시 로드하여, 세션 중에 설치하거나 편집한 플러그인이 실행 중인 세션에 반영되도록 합니다. 세션의 명령, 서브에이전트, 플러그인, MCP 서버 상태를 나열하는 [`SDKControlReloadPluginsResponse`](#sdkcontrolreloadpluginsresponse)로 resolve됩니다. Agent SDK v0.2.85 이상이 필요합니다. [`holdOnCacheImpact` 옵션](#sdkcontrolreloadpluginsresponse)에는 Agent SDK v0.3.268 이상이 필요합니다 |

715| `reloadSkills()` | 디스크에서 스킬을 다시 로드하여, 세션 중에 추가하거나 편집한 스킬을 실행 중인 세션에서 사용할 수 있도록 합니다. 다시 로드한 후 사용 가능한 스킬을 나열하는 [`SDKControlReloadSkillsResponse`](#sdkcontrolreloadskillsresponse)로 resolve됩니다. Agent SDK v0.3.163 이상이 필요합니다 |718| `reloadSkills()` | 디스크에서 스킬을 다시 로드하여, 세션 중에 추가하거나 편집한 스킬을 실행 중인 세션에서 사용할 수 있게 합니다. 다시 로드한 후 사용 가능한 스킬을 나열하는 [`SDKControlReloadSkillsResponse`](#sdkcontrolreloadskillsresponse)로 resolve됩니다. Agent SDK v0.3.163 이상이 필요합니다 |

716| `reloadOutputStyles()` | 디스크에서 [출력 스타일](/docs/ko/output-styles)을 다시 읽어, 세션 중에 추가하거나 편집한 스타일 파일을 실행 중인 세션에서 사용할 수 있도록 합니다. 다시 로드한 후 사용 가능한 스타일 이름을 나열하는 [`SDKControlReloadOutputStylesResponse`](#sdkcontrolreloadoutputstylesresponse)로 resolve됩니다. Agent SDK v0.3.261 이상이 필요합니다 |719| `reloadOutputStyles()` | 디스크에서 [출력 스타일](/docs/ko/output-styles)을 다시 읽어, 세션 중에 추가하거나 편집한 스타일 파일을 실행 중인 세션에서 사용할 수 있게 합니다. 다시 로드한 후 사용 가능한 스타일 이름을 나열하는 [`SDKControlReloadOutputStylesResponse`](#sdkcontrolreloadoutputstylesresponse)로 resolve됩니다. Agent SDK v0.3.261 이상이 필요합니다 |

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

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

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

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

727 `applyFlagSettings()`730 `applyFlagSettings()`

728</h4>731</h4>

729 732

730쿼리를 다시 시작하지 않고 실행 중인 세션의 [설정](/docs/ko/settings)을 변경합니다. 에이전트가 신뢰할 수 없는 입력을 읽은 후 `permissions`를 강화하는 경우처럼, 전용 setter가 없는 설정을 세션 중에 변경해야 할 때 사용하세요. `setModel()`과 `setPermissionMode()`는 해당 두 키의 전용 setter이며, `applyFlagSettings()`는 설정 키의 임의 부분 집합을 받는 일반 형식입니다. 여기서 `model`을 전달하면 `setModel()`과 동일하게 동작합니다.733쿼리를 다시 시작하지 않고 실행 중인 세션의 [설정](/docs/ko/settings)을 변경합니다. 에이전트가 신뢰할 수 없는 입력을 읽은 후 `permissions`를 강화하는 경우처럼, 전용 setter가 없는 설정을 세션 중에 변경해야 할 때 사용하세요. `setModel()`과 `setPermissionMode()`는 해당 두 키의 전용 setter이며, `applyFlagSettings()`는 설정 키의 어떤 하위 집합이든 허용하는 일반 형식입니다. 여기에 `model`을 전달하면 `setModel()`과 동일하게 동작합니다.

731 734

732일부 키만 세션 중에 적용됩니다:735일부 키만 세션 중에 적용됩니다.

733 736

734* **다음 턴에 적용**: `effortLevel`, `ultracode`, `permissions`, `hooks`, `skillOverrides`, `fastMode`, `agent`. `agent`를 전환하면 해당 에이전트의 모델 재정의와 훅도 다음 턴에 적용됩니다. 시스템 프롬프트는 다음 턴에 적용되거나, [기록된 시스템 프롬프트를 재사용하는](/docs/ko/agent-sdk/modifying-system-prompts#change-the-prompt-of-an-existing-session) 세션에서는 세션이 압축된 후에 적용됩니다.737* **다음 턴에 적용**: `effortLevel`, `ultracode`, `permissions`, `hooks`, `skillOverrides`, `fastMode`, `agent`. `agent`를 전환하면 해당 에이전트의 모델 재정의와 훅도 다음 턴에 적용됩니다. 에이전트의 시스템 프롬프트는 다음 턴에 적용되거나, [기록된 시스템 프롬프트를 재사용하는](/docs/ko/agent-sdk/modifying-system-prompts#change-the-prompt-of-an-existing-session) 세션에서는 세션이 압축된 후에 적용됩니다.

735* **현재 턴 중에 적용**: `model`. Claude가 턴을 처리하는 도중 `model`을 전환하면, Claude가 이미 생성 중인 응답은 이전 모델로 완료되고, Claude Code가 모델에 보내는 다음 호출부터 턴의 나머지는 새 모델을 사용합니다. 서브에이전트는 자체 모델을 유지합니다. v2.1.212 이전에는 턴 중 전환이 다음 턴까지 기다렸습니다.738* **현재 턴 중에 적용**: `model`. Claude가 턴을 처리하는 동안 `model`을 전환하면, Claude가 이미 생성 중인 응답은 이전 모델로 완료되고, Claude Code가 모델에 보내는 다음 호출부터 턴의 나머지 부분은 새 모델을 사용합니다. 서브에이전트는 자체 모델을 유지합니다. v2.1.212 이전에는 턴 중간의 전환이 다음 턴까지 대기했습니다.

736* **세션 중 효과 없음**: 시스템 프롬프트 옵션. 이 옵션은 시작 시 한 번 확인되므로, 호출이 성공하더라도 실행 중인 세션은 원래 값을 유지합니다. 변경하려면 새 세션을 시작하세요.739* **세션 중에는 효과 없음**: 시스템 프롬프트 옵션. 이 옵션은 시작 시 한 번만 확인되므로, 호출이 성공하더라도 실행 중인 세션은 원래 값을 유지합니다. 변경하려면 새 세션을 시작하세요.

737 740

738`effortLevel`은 [effort 수준](/docs/ko/model-config#adjust-effort-level) 이름을 받습니다. 또한 [ultracode](/docs/ko/workflows#let-claude-decide-with-ultracode)를 켠 상태로 `xhigh` effort를 요청하는 `"ultracode"`도 받습니다. `applyFlagSettings()`는 해당 값 없이 `effortLevel`을 선언하므로, TypeScript에서 같은 결과를 얻으려면 `{ ultracode: true, effortLevel: "xhigh" }`를 전달하거나, 세션의 현재 effort 수준에서 ultracode를 켜려면 [`ultracode`](/docs/ko/settings-reference#ultracode) 키만 전달하세요. `ultracode` 값은 Claude Code v2.1.203 이상이 필요하며, 설정 파일의 `effortLevel` 키가 아니라 `applyFlagSettings()`에서만 허용됩니다. v2.1.284 이전에는 `ultracode` 키만 전달해도 수준이 `xhigh`로 설정되었습니다.741`effortLevel`은 [effort 수준](/docs/ko/model-config#adjust-effort-level) 이름을 허용합니다. 또한 `"ultracode"`도 허용하는데, 이는 [ultracode](/docs/ko/workflows#let-claude-decide-with-ultracode)를 켠 상태에서 `xhigh` effort를 요청합니다. `applyFlagSettings()`는 이 값 없이 `effortLevel`을 선언하므로, TypeScript에서 동일한 결과를 얻으려면 `{ ultracode: true, effortLevel: "xhigh" }`를 전달하거나, 세션의 현재 effort 수준에서 ultracode를 켜려면 [`ultracode`](/docs/ko/settings-reference#ultracode) 키만 전달하세요. `ultracode` 값에는 Claude Code v2.1.203 이상이 필요하며, 설정 파일의 `effortLevel` 키가 아닌 `applyFlagSettings()`에서만 허용됩니다. v2.1.284 이전에는 `ultracode` 키만 전달해도 수준이 `xhigh`로 설정되었습니다.

739 742

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

741 744

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

743 746

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

745 748

746`model` 외에 세 가지 키는 폴백하는 대신 세션 상태를 재설정합니다:749`model` 외에 세 개의 키는 폴백하는 대신 세션 상태를 재설정합니다.

747 750

748* `effortLevel: null`은 `query()`의 `effort` 옵션이나 설정 파일의 `effortLevel`이 아니라 모델의 기본 effort 수준으로 세션을 되돌립니다.751* `effortLevel: null`은 `query()`의 `effort` 옵션이나 설정 파일의 `effortLevel`이 아닌, 모델의 기본 effort 수준으로 세션을 되돌립니다.

749* `agent: null`은 `query()`의 `agent` 옵션이나 설정 파일의 `agent`를 복원하는 대신, 다음 턴부터 에이전트 없이 메인 스레드를 실행합니다. 지워진 에이전트가 자체 모델을 적용했다면 세션은 시작 시 확인한 모델로 돌아갑니다.752* `agent: null`은 `query()`의 `agent` 옵션이나 설정 파일의 `agent`를 복원하는 대신, 다음 턴부터 에이전트 없이 메인 스레드를 실행합니다. 지워진 에이전트가 자체 모델을 적용했었다면 세션은 시작 시 확인된 모델로 돌아갑니다.

750* `ultracode: null`은 설정 파일의 `ultracode` 값을 복원하는 대신 `false`처럼 ultracode를 끕니다. 세션은 현재 effort 수준을 유지하므로, 변경하려면 같은 호출에서 `effortLevel`을 전달하세요.753* `ultracode: null`은 설정 파일의 `ultracode` 값을 복원하는 대신 `false`와 마찬가지로 ultracode를 끕니다. 세션은 현재 effort 수준을 유지하므로, 변경하려면 같은 호출에서 `effortLevel`을 전달하세요.

751 754

752`setModel()` 및 `setPermissionMode()`와 동일한 제약으로, 스트리밍 입력 모드에서만 사용할 수 있습니다.755`setModel()` 및 `setPermissionMode()`와 동일한 제약으로, 스트리밍 입력 모드에서만 사용할 수 있습니다.

753 756

754아래 예시는 세션 중에 활성 모델을 전환한 다음, 재정의를 지워 모델이 [Claude Code의 기본 모델](/docs/ko/model-config)로 재설정되도록 합니다.757아래 예시는 세션 중에 활성 모델을 전환한 다음, 재정의를 지워 모델을 [Claude Code의 기본 모델](/docs/ko/model-config)로 재설정합니다.

755 758

756```typescript theme={null}759```typescript theme={null}

757import { query } from "@anthropic-ai/claude-agent-sdk";760import { query } from "@anthropic-ai/claude-agent-sdk";

766```769```

767 770

768<Note>771<Note>

769 `applyFlagSettings()`는 TypeScript 전용입니다. Python SDK는 이에 상응하는 메서드를 제공하지 않습니다.772 `applyFlagSettings()`는 TypeScript 전용입니다. Python SDK에는 이에 해당하는 메서드가 없습니다.

770</Note>773</Note>

771 774

772<h4 id="updatesettings">775<h4 id="updatesettings">

773 `updateSettings()`776 `updateSettings()`

774</h4>777</h4>

775 778

776허용 목록에 있는 키 하나를 디스크의 설정 파일에 기록하여, 해당 소스를 로드하는 이후 세션에서도 값이 유지되도록 합니다. 각 소스는 문자열 값을 가진 키 하나를 받습니다:779허용 목록에 있는 키 하나를 디스크의 설정 파일에 기록하여, 해당 소스를 로드하는 이후 세션에서도 값이 유지되도록 합니다. 각 소스는 문자열 값을 가진 키 하나를 허용합니다.

777 780

778* **`"localSettings"`**: `outputStyle`을 받아 프로젝트의 로컬 설정 파일인 `.claude/settings.local.json`에 병합합니다. 새 스타일은 세션의 다음 요청부터 적용됩니다.781* **`"localSettings"`**: `outputStyle`을 허용하며, 이를 프로젝트의 로컬 설정 파일인 `.claude/settings.local.json`에 병합합니다. 새 스타일은 세션의 다음 요청부터 적용됩니다.

779* **`"userSettings"`**: `effortLevel`을 받아 사용자 설정 파일의 [`modelSettings`](/docs/ko/settings-reference#modelsettings) 아래에 세션의 현재 모델에 대한 기본 [effort 수준](/docs/ko/model-config#adjust-effort-level)으로 저장합니다. `max`는 세션 전용이므로 `max`를 전달하면 아무것도 기록되지 않습니다. 어느 경우든 실행 중인 세션은 현재 effort 수준을 유지하므로, 이것도 변경하려면 [`applyFlagSettings()`](#applyflagsettings)를 호출하세요. 이 소스는 Claude Code v2.1.277이 번들된 TypeScript SDK v0.3.277 이상이 필요합니다.782* **`"userSettings"`**: `effortLevel`을 허용하며, 이를 사용자 설정 파일의 [`modelSettings`](/docs/ko/settings-reference#modelsettings) 아래에 세션의 현재 모델에 대한 기본 [effort 수준](/docs/ko/model-config#adjust-effort-level)으로 저장합니다. `max`는 세션 전용이므로 `max`를 전달하면 아무것도 기록되지 않습니다. 어느 경우든 실행 중인 세션은 현재 effort 수준을 유지하므로, 이것도 변경하려면 [`applyFlagSettings()`](#applyflagsettings)를 호출하세요. 이 소스에는 Claude Code v2.1.277이 번들된 TypeScript SDK v0.3.277 이상이 필요합니다.

780 783

781요청에 다른 키가 포함된 경우, 세션이 원격 전송으로 실행되는 경우, 세션의 [`settingSources`](#options)가 지정한 소스를 제외하는 경우 호출이 거부됩니다. 키 삭제는 지원되지 않습니다.784요청에 다른 키가 포함된 경우, 세션이 원격 전송을 통해 실행되는 경우, 세션의 [`settingSources`](#options)가 지정한 소스를 제외하는 경우에는 호출이 거부됩니다. 키 삭제는 지원되지 않습니다.

782 785

783<h4 id="togglemcpserver">786<h4 id="togglemcpserver">

784 `toggleMcpServer()`787 `toggleMcpServer()`

785</h4>788</h4>

786 789

787서버를 비활성화하면 연결이 끊기고 세션에서 해당 도구가 제거됩니다. 세션 중에 추가한 서버와 인프로세스 서버의 경우 Claude Code 버전에 따라 달라집니다:790서버를 비활성화하면 연결이 끊기고 해당 도구가 세션에서 제거됩니다. 세션 중에 추가한 서버와 프로세스 내 서버의 경우, 이는 Claude Code 버전에 따라 달라집니다.

788 791

789* `setMcpServers()`로 세션 중에 추가한 stdio, SSE 또는 HTTP 서버: 해당 도구를 제거하려면 Claude Code v2.1.285 이상이 필요합니다.792* 세션 중에 `setMcpServers()`로 추가한 stdio, SSE 또는 HTTP 서버: 해당 도구를 제거하려면 Claude Code v2.1.285 이상이 필요합니다.

790* `mcpServers`로 전달했든 `setMcpServers()`로 전달했든 [`createSdkMcpServer()`](#createsdkmcpserver)로 생성한 인프로세스 서버: 연결을 끊고 해당 도구를 제거하려면 Claude Code v2.1.286 이상이 필요합니다. 이러한 서버를 비활성화하면 아직 실행 중인 도구 호출도 실패하므로, Claude는 핸들러가 반환될 때까지 기다리지 않고 각 호출에 대한 오류 결과를 즉시 받습니다.793* [`createSdkMcpServer()`](#createsdkmcpserver)로 생성한 프로세스 내 서버(`mcpServers`로 전달했든 `setMcpServers()`로 전달했든): 연결을 끊고 해당 도구를 제거하려면 Claude Code v2.1.286 이상이 필요합니다. 이러한 서버를 비활성화하면 아직 실행 중인 해당 서버의 도구 호출도 실패 처리되므로, Claude는 핸들러가 반환될 때까지 기다리지 않고 각 호출에 대한 오류 결과를 즉시 받습니다.

791 794

792<h3 id="warmquery">795<h3 id="warmquery">

793 `WarmQuery`796 `WarmQuery`

794</h3>797</h3>

795 798

796[`startup()`](#startup)이 반환하는 핸들입니다. 하위 프로세스가 이미 생성되고 초기화되어 있으므로, 이 핸들에서 `query()`를 호출하면 시작 지연 없이 준비된 프로세스에 프롬프트가 직접 기록됩니다.799[`startup()`](#startup)이 반환하는 핸들입니다. 하위 프로세스가 이미 생성되고 초기화되어 있으므로, 이 핸들에서 `query()`를 호출하면 시작 지연 없이 준비된 프로세스에 프롬프트를 직접 기록합니다.

797 800

798```typescript theme={null}801```typescript theme={null}

799interface WarmQuery extends AsyncDisposable {802interface WarmQuery extends AsyncDisposable {

809| 메서드 | 설명 |812| 메서드 | 설명 |

810| :- | :- |813| :- | :- |

813 816

814`WarmQuery`는 `AsyncDisposable`을 구현하므로 자동 정리를 위해 `await using`과 함께 사용할 수 있습니다.817`WarmQuery`는 `AsyncDisposable`을 구현하므로, 자동 정리를 위해 `await using`과 함께 사용할 수 있습니다.

815 818

816<h3 id="spareprocess">819<h3 id="spareprocess">

817 `SpareProcess`820 `SpareProcess`

818</h3>821</h3>

819 822

820*Alpha.* [`prewarm()`](#prewarm)이 반환하는 핸들로, 아직 세션에 바인딩되지 않았으며 한 번 클레임할 수 있는 시작된 Claude Code 프로세스입니다. TypeScript Agent SDK v0.3.282 이상이 필요합니다.823*알파.* [`prewarm()`](#prewarm)이 반환하는 핸들로, 아직 세션에 바인딩되지 않았으며 한 번 claim할 수 있는 시작된 Claude Code 프로세스입니다. TypeScript Agent SDK v0.3.282 이상이 필요합니다.

821 824

822```typescript theme={null}825```typescript theme={null}

823interface SpareProcess extends AsyncDisposable {826interface SpareProcess extends AsyncDisposable {

838| 멤버 | 설명 |841| 멤버 | 설명 |

839| :- | :- |842| :- | :- |

840| `claim({ prompt, options })` | 예비 프로세스를 `options.cwd`의 세션에 바인딩하고 첫 번째 메시지를 보냅니다. `query()`와 마찬가지로 [`Query`](#query-object)를 동기적으로 반환합니다. 한 번만 호출할 수 있습니다 |843| `claim({ prompt, options })` | 예비 프로세스를 `options.cwd`의 세션에 바인딩하고 첫 번째 메시지를 보냅니다. `query()`와 마찬가지로 [`Query`](#query-object)를 동기적으로 반환합니다. 한 번만 호출할 수 있습니다 |

841| `claimed` | Claude Code가 클레임을 수락하면 세션의 작업 디렉터리와 ID로 resolve됩니다. Claude Code가 클레임을 거부하는 경우, 프로세스가 먼저 종료되었거나 닫힌 경우, 그리고 요청한 `model` 또는 `maxThinkingTokens` 없이 세션이 실행 중인 경우(`option_not_applied`로 시작하는 메시지와 함께) reject됩니다 |844| `claimed` | Claude Code가 claim을 수락하면 세션의 작업 디렉터리와 ID로 resolve됩니다. Claude Code가 claim을 거부하는 경우, 프로세스가 먼저 종료되었거나 닫힌 경우에 reject되며, 요청한 `model` 또는 `maxThinkingTokens` 없이 세션이 실행되는 경우에는 `option_not_applied`로 시작하는 메시지와 함께 reject됩니다 |

844 847

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

846 849

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

848 851

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

850 `SDKControlInitializeResponse`853 `SDKControlInitializeResponse`

874};877};

875```878```

876 879

877`hooks_applied`는 Claude Code가 `initialize` 요청에 포함된 `hooks`를 등록했는지 여부를 보고합니다. SDK는 세션이 시작될 때 한 번, 그리고 각 [`reinitialize()`](#query-object) 호출마다 이 요청을 보냅니다. 이 필드는 Agent SDK v0.3.238 이상이 필요합니다.880`hooks_applied`는 `initialize` 요청에 포함된 `hooks`를 Claude Code가 등록했는지 여부를 보고합니다. SDK는 세션이 시작될 때 이 요청을 한 번 보내고, [`reinitialize()`](#query-object)를 호출할 때마다 다시 보냅니다. 이 필드에는 Agent SDK v0.3.238 이상이 필요합니다.

878 881

879요청에 훅이 없으면 Claude Code는 이 필드를 생략합니다. 요청에 훅이 포함된 경우, 값은 해당 요청이 세션의 첫 번째 initialize인지, 그리고 반복된 요청이라면 세션에 어떻게 도달했는지에 따라 달라집니다:882요청에 훅이 포함되지 않은 경우 Claude Code는 이 필드를 생략합니다. 요청에 훅이 포함된 경우, 값은 해당 요청이 세션의 첫 번째 initialize인지, 그리고 반복된 요청이라면 어떤 경로로 세션에 도달했는지에 따라 달라집니다.

880 883

881* `true`: Claude Code가 훅을 등록했습니다. 세션의 첫 번째 initialize는 이 값을 반환합니다. CLI의 stdin으로 전송된 반복 initialize도 `true`를 반환합니다. 이 경우 새 요청의 훅이 이전에 등록된 훅을 대체합니다.884* `true`: Claude Code가 훅을 등록했습니다. 세션의 첫 번째 initialize는 이 값을 반환합니다. CLI의 stdin을 통해 전송된 반복 initialize도 `true`를 반환합니다. 이 경우 새 요청의 훅이 이전에 등록된 훅을 대체합니다.

882* `false`: Claude Code가 훅을 무시했습니다. 원격 세션으로 전송된 반복 initialize는 이 값을 반환하므로, 세션에 참여하는 두 번째 클라이언트는 첫 번째 클라이언트가 등록한 훅을 대체할 수 없습니다.885* `false`: Claude Code가 훅을 무시했습니다. 원격 세션으로 전송된 반복 initialize는 이 값을 반환하므로, 세션에 참여하는 두 번째 클라이언트가 첫 번째 클라이언트가 등록한 훅을 대체할 수 없습니다.

883 886

884Agent SDK v0.3.238 이전에는 응답에 이 필드가 없었고, Claude Code는 모든 반복 initialize에서 `hooks`를 무시했습니다.887Agent SDK v0.3.238 이전에는 응답에 이 필드가 포함되지 않았으며, Claude Code는 반복되는 모든 initialize에서 `hooks`를 무시했습니다.

885 888

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

887 890

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

889 892

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

891 894

892이 배열은 이 Claude Code 프로세스가 발행했지만 아직 해결되지 않은 권한 요청을 나열합니다. SDK는 배열을 대신 읽어 각 항목을 [`canUseTool`](#canusetool) 콜백으로 전달하며, 이는 전송 공백 이후 [`reinitialize()`](#query-object)가 트리거하는 것과 동일한 재전달입니다. 항목이 연결 끊김 전에 콜백이 이미 받은 요청을 반복할 수 있으므로, 반복된 요청 ID를 멱등하게 처리하세요.895이 배열은 이 Claude Code 프로세스가 발행했지만 아직 해결되지 않은 권한 요청을 나열합니다. SDK는 이 배열을 대신 읽고 각 항목을 [`canUseTool`](#canusetool) 콜백으로 전달하며, 이는 전송 공백 후 [`reinitialize()`](#query-object)가 트리거하는 것과 동일한 재전달입니다. 항목이 연결이 끊기기 전에 콜백이 이미 받은 요청을 반복할 수 있으므로, 반복되는 요청 ID를 멱등하게 처리하세요.

893 896

894이 배열은 성공적인 `initialize` 응답에 항상 존재하며, 이 프로세스에 해결되지 않은 권한 요청이 없으면 비어 있습니다. Claude Code v2.1.268 이상이 필요합니다. 이전 버전에서는 이 필드가 생략될 수 있으므로, 와이어 프로토콜을 직접 파싱하는 경우 필드가 없으면 대기 중인 것이 없다는 증거가 아니라 이전 CLI로 간주하세요.897이 배열은 성공한 `initialize` 응답에 항상 존재하며, 이 프로세스에 해결되지 않은 권한 요청이 없으면 비어 있습니다. Claude Code v2.1.268 이상이 필요합니다. 이전 버전에서는 이 필드가 생략될 수 있으므로, 와이어 프로토콜을 직접 파싱하는 경우 필드가 없으면 대기 중인 항목이 없다는 증거가 아니라 이전 CLI로 간주하세요.

895 898

896<h3 id="sdkcontrolinterruptresponse">899<h3 id="sdkcontrolinterruptresponse">

897 `SDKControlInterruptResponse`900 `SDKControlInterruptResponse`

898</h3>901</h3>

899 902

900중단 영수증: [`SDKSystemMessage.capabilities`](#sdksystemmessage)에서 `interrupt_receipt_v1` 기능을 알리는 CLI에서 [`interrupt()`](#query-object)가 resolve하는 값입니다. Claude Code v2.1.205 이상이 필요합니다. 이전 CLI는 빈 성공 페이로드로 중단에 응답하므로 `interrupt()`는 `undefined`로 resolve됩니다.903중단 확인 영수증으로, [`SDKSystemMessage.capabilities`](#sdksystemmessage)에서 `interrupt_receipt_v1` 기능을 알리는 CLI에서 [`interrupt()`](#query-object)가 resolve되는 값입니다. Claude Code v2.1.205 이상이 필요합니다. 이전 CLI는 빈 성공 페이로드로 중단에 응답하므로 `interrupt()`는 `undefined`로 resolve됩니다.

901 904

902```typescript theme={null}905```typescript theme={null}

903type SDKControlInterruptResponse = {906type SDKControlInterruptResponse = {

906};909};

907```910```

908 911

909`still_queued`는 중단이 도착했을 때 대기 중이던 사용자 메시지의 UUID를 나열합니다. 여기에는 아직 큐에 있는 메시지와, Claude Code가 다음 턴을 위해 이미 큐에서 꺼낸 메시지가 포함됩니다. 세션의 첫 번째 턴이 시작된 후에는 먼저 취소하지 않는 한 Claude Code가 중단 이후 나열된 메시지를 처리하며, 여러 메시지를 하나의 턴으로 병합할 수 있습니다. 첫 번째 턴이 시작되기 전에 중단하면 Claude Code는 해당 턴이 시작되자마자 중단하며, 그 턴에 나열된 메시지는 응답을 받지 못합니다.912`still_queued`는 중단 시점에 대기 중이던 사용자 메시지의 UUID를 나열합니다. 여기에는 아직 큐에 있는 메시지와, Claude Code가 다음 턴을 위해 이미 큐에서 꺼낸 메시지가 포함됩니다. 세션의 첫 번째 턴이 시작된 후에는, 먼저 취소하지 않는 한 Claude Code가 중단 후 나열된 메시지를 처리하며 여러 메시지를 하나의 턴으로 병합할 수 있습니다. 첫 번째 턴이 시작되기 전에 중단하면 Claude Code는 해당 턴이 시작되자마자 중단하며, 그 턴에 나열된 메시지는 응답을 받지 못합니다.

910 913

911영수증을 사용하여 무언가를 다시 보낼지 결정하세요. 취소하지 않은 나열된 메시지는 응답을 받든 받지 않든 대화에 들어가므로, 다시 보내면 Claude에 두 번 전달됩니다.914영수증을 사용하여 다시 보낼 항목이 있는지 결정하세요. 취소하지 않은 나열된 메시지는 응답을 받든 받지 않든 대화에 포함되므로, 다시 보내면 Claude에게 두 번 전달됩니다.

912 915

913다음 주의 사항을 고려하여 목록을 해석하세요:916다음 주의 사항을 고려하여 목록을 해석하세요.

914 917

915* UUID와 함께 큐에 추가된 메시지만 나타납니다. 빈 배열이라고 해서 다른 것이 실행되지 않는다는 의미는 아닙니다.918* UUID와 함께 큐에 추가된 메시지만 나타납니다. 빈 배열이 다른 어떤 것도 실행되지 않는다는 의미는 아닙니다.

916* 메인 스레드 메시지만 나열됩니다. 서브에이전트에 전달된 메시지는 범위에 포함되지 않습니다.919* 메인 스레드 메시지만 나열됩니다. 서브에이전트에 전달되는 메시지는 범위에 포함되지 않습니다.

917* 목록에는 [예약 작업](/docs/ko/scheduled-tasks) 트리거처럼 클라이언트가 보내지 않은 UUID가 포함될 수 있습니다. 인식하지 못하는 UUID는 오류로 처리하지 말고 무시하세요.920* 목록에는 [예약 작업](/docs/ko/scheduled-tasks) 트리거와 같이 클라이언트가 보내지 않은 UUID가 포함될 수 있습니다. 인식하지 못하는 UUID는 오류로 처리하지 말고 무시하세요.

918 921

919`interrupt()`를 통하지 않고 CLI의 제어 프로토콜을 직접 구동하는 클라이언트는 `interrupt` 제어 요청에 `cancel_queued: true`를 설정할 수 있습니다. Claude Code v2.1.219 이상은 [`SDKSystemMessage.capabilities`](#sdksystemmessage)의 `interrupt_cancel_queued_v1` 기능으로 지원을 알리며, 이전 CLI는 이 필드를 무시하고 대기 중인 메시지를 평소처럼 실행합니다. 이러한 중단은 원래 `still_queued` 아래에 나열되었을 모든 메시지도 취소합니다. 영수증은 이들을 대신 `cancelled` 아래에 나열하고, `still_queued`는 비어 있으며, 그중 어느 것도 실행되지 않습니다.922`interrupt()`를 사용하지 않고 CLI의 제어 프로토콜을 직접 구동하는 클라이언트는 `interrupt` 제어 요청에 `cancel_queued: true`를 설정할 수 있습니다. Claude Code v2.1.219 이상은 [`SDKSystemMessage.capabilities`](#sdksystemmessage)의 `interrupt_cancel_queued_v1` 기능으로 지원 여부를 알리며, 이전 CLI는 이 필드를 무시하고 대기 중인 메시지를 평소처럼 실행합니다. 이러한 중단은 원래 `still_queued`에 나열되었을 모든 메시지도 취소합니다. 영수증은 대신 이 메시지들을 `cancelled`에 나열하고, `still_queued`는 비어 있으며, 해당 메시지는 하나도 실행되지 않습니다.

920 923

921`cancelled` 목록에는 `still_queued`와 동일한 주의 사항이 적용됩니다. `interrupt()` 메서드는 `cancel_queued`를 보내지 않으므로, 이 메서드가 resolve하는 영수증에는 `cancelled`가 포함되지 않습니다.924`cancelled` 목록에는 `still_queued`와 동일한 주의 사항이 적용됩니다. `interrupt()` 메서드는 `cancel_queued`를 보내지 않으므로, 이 메서드가 resolve하는 영수증에는 `cancelled`가 포함되지 않습니다.

922 925

923영수증은 중단이 처리되는 순간의 스냅샷이며, 정상적인 중단에서는 중단된 턴의 [`SDKResultMessage`](#sdkresultmessage)보다 먼저 도착합니다. 해당 결과 이후에 큐를 검사하지 말고 영수증을 읽으세요. 루프는 다음 대기 턴을 즉시 시작하므로 결과 이후에 검사하는 큐는 이미 변경되어 있습니다.926영수증은 중단이 처리되는 시점에 찍은 스냅샷이며, 정상적인 중단에서는 중단된 턴의 [`SDKResultMessage`](#sdkresultmessage)보다 먼저 도착합니다. 해당 결과 이후에 큐를 검사하지 말고 영수증을 읽으세요. 루프는 다음 대기 턴을 즉시 시작하므로, 결과 이후에 검사하는 큐는 이미 변경된 상태입니다.

924 927

925<h3 id="sdkcontrolgetcontextusageresponse">928<h3 id="sdkcontrolgetcontextusageresponse">

926 `SDKControlGetContextUsageResponse`929 `SDKControlGetContextUsageResponse`

927</h3>930</h3>

928 931

929[`getContextUsage()`](#query-object)의 반환 타입입니다. 기본 `detail`에서는 Claude Code가 대화형 세션에서 `/context` 명령에 대해 렌더링하는 것과 동일한 페이로드이므로, 토큰 수와 함께 Claude Code가 `/context` 사용량 그리드를 그리는 데 사용하는 `color` 및 `gridRows`와 같은 표시 필드를 포함합니다.932[`getContextUsage()`](#query-object)의 반환 타입입니다. 기본 `detail`을 사용하면 대화형 세션에서 Claude Code가 `/context` 명령에 대해 렌더링하는 것과 동일한 페이로드이므로, 토큰 수와 함께 Claude Code가 `/context` 사용량 그리드를 그리는 데 사용하는 `color` 및 `gridRows`와 같은 표시용 필드도 포함합니다.

930 933

931메서드의 선택적 `detail` 인수는 Claude Code가 각 카테고리를 계산하는 방식을 선택합니다. `detail` 인수는 Agent SDK v0.3.257 이상이 필요합니다.934메서드의 선택적 `detail` 인수는 Claude Code가 각 카테고리를 계산하는 방식을 선택합니다. `detail` 인수에는 Agent SDK v0.3.257 이상이 필요합니다.

932 935

933* **`'full'`**: 기본값입니다. Claude Code는 [토큰 계산](https://platform.claude.com/docs/en/build-with-claude/token-counting) API 요청으로 각 카테고리를 계산합니다. 이러한 요청은 메시지 스트림에 나타나지 않으므로, 스트림을 읽는 비용 추적에서는 보이지 않습니다. Anthropic API에서 토큰 계산은 과금되지 않습니다.936* **`'full'`**: 기본값입니다. Claude Code는 [토큰 계산](https://platform.claude.com/docs/en/build-with-claude/token-counting) API 요청으로 각 카테고리를 계산합니다. 이러한 요청은 메시지 스트림에 나타나지 않으므로, 스트림을 읽는 비용 추적에서는 이를 볼 수 없습니다. Anthropic API에서는 토큰 계산에 요금이 청구되지 않습니다.

934* **`'summary'`**: `{ detail: 'summary' }`를 전달하면 대신 마지막 응답의 사용량과 로컬 추정치로 답을 얻습니다. 토큰 계산 요청이 전송되지 않으며, 카테고리별 수치는 근사치입니다.937* **`'summary'`**: 대신 마지막 응답의 사용량과 로컬 추정치로 답을 얻으려면 `{ detail: 'summary' }`를 전달하세요. 토큰 계산 요청이 전송되지 않으며, 카테고리별 수치는 근삿값입니다.

935 938

936메서드를 호출하는 대신 `/context`를 프롬프트로 보내면, Claude Code는 결과를 전달하는 어시스턴트 메시지의 `context_usage` 필드에 [`SDKContextUsage`](#sdkcontextusage) 페이로드를 첨부합니다. 이 필드는 Agent SDK v0.3.232 이상이 필요합니다.939메서드를 호출하는 대신 `/context`를 프롬프트로 보내면, Claude Code는 결과를 전달하는 assistant 메시지의 `context_usage` 필드에 [`SDKContextUsage`](#sdkcontextusage) 페이로드를 첨부합니다. 이 필드에는 Agent SDK v0.3.232 이상이 필요합니다.

937 940

938```typescript theme={null}941```typescript theme={null}

939type SDKControlGetContextUsageResponse = {942type SDKControlGetContextUsageResponse = {

1030};1033};

1031```1034```

1032 1035

1033컬렉션 필드에서 토큰 귀속을 읽으세요:1036토큰 귀속 정보는 컬렉션 필드에서 읽으세요.

1034 1037

1035* `categories`는 카테고리별 합계를 담고 있습니다. 각 항목의 `kind`는 [`SDKContextUsageCategory`](#sdkcontextusagecategory)와 동일한 값으로 행을 분류합니다. 표시용 `name`이 아니라 이 필드로 행을 분류하세요. 이 필드는 Agent SDK v0.3.268 이상이 필요합니다.1038* `categories`는 카테고리별 합계를 담습니다. 각 항목의 `kind`는 [`SDKContextUsageCategory`](#sdkcontextusagecategory)와 동일한 값으로 행을 분류합니다. 표시용 `name`이 아닌 이 필드를 기준으로 행을 분류하세요. 이 필드에는 Agent SDK v0.3.268 이상이 필요합니다.

1036* `mcpTools`와 `agents`는 토큰을 개별 MCP 도구와 서브에이전트에 귀속합니다.1039* `mcpTools`와 `agents`는 개별 MCP 도구와 서브에이전트에 토큰을 귀속합니다.

1037* `memoryFiles`는 로드된 각 메모리 파일과 그 비용을 나열합니다.1040* `memoryFiles`는 로드된 각 메모리 파일과 그 비용을 나열합니다.

1038* `skills.skillFrontmatter`는 스킬 목록의 토큰을 포함된 각 스킬에 귀속합니다. 스킬별 수치는 Claude Code가 실제로 보내는 각 스킬의 목록 항목을 측정하며, 이는 스킬의 전체 frontmatter보다 짧을 수 있습니다. 발견된 모든 스킬이 목록에 포함되었는지 확인하려면 `skills.totalSkills`와 `skills.includedSkills`를 비교하세요.1041* `skills.skillFrontmatter`는 스킬 목록의 토큰을 포함된 각 스킬에 귀속합니다. 스킬별 수치는 Claude Code가 실제로 보내는 각 스킬의 목록 항목을 측정하며, 이는 스킬의 전체 frontmatter보다 짧을 수 있습니다. 발견된 모든 스킬이 목록에 포함되었는지 확인하려면 `skills.totalSkills`와 `skills.includedSkills`를 비교하세요.

1039 1042

1040`totalTokens`는 세션의 현재 컨텍스트 사용량이고, `maxTokens`는 해당 사용량을 측정하는 기준 윈도우입니다. 이 윈도우는 모델의 컨텍스트 윈도우이거나, 해당되는 경우 더 낮은 자동 압축 윈도우입니다. `rawMaxTokens`는 `maxTokens`와 같은 값을 담고 있으며, `percentage`는 해당 윈도우 대비 `totalTokens`를 반올림한 백분율입니다. `apiUsage`는 세션의 누적 합계가 아니라 최신 API 응답의 사용량을 담고 있습니다.1043`totalTokens`는 세션의 현재 컨텍스트 사용량이고, `maxTokens`는 해당 사용량을 측정하는 기준 윈도우입니다. 이 윈도우는 모델의 컨텍스트 윈도우이거나, 적용되는 경우 더 낮은 자동 압축 윈도우입니다. `rawMaxTokens`는 `maxTokens`와 동일한 값을 가지며, `percentage`는 해당 윈도우에 대한 `totalTokens`의 반올림된 백분율입니다. `apiUsage`는 세션의 누적 합계가 아니라 최신 API 응답의 사용량을 담습니다.

1041 1044

1042Claude Code는 선택적 진단 필드인 `deferredBuiltinTools`, `systemTools`, `systemPromptSections`를 설정하지 않으므로, 타입에 선언되어 있더라도 없을 것으로 예상하세요.1045Claude Code는 선택적 진단 필드인 `deferredBuiltinTools`, `systemTools`, `systemPromptSections`를 설정하지 않으므로, 타입에 선언되어 있더라도 이 필드들은 없을 것으로 예상하세요.

1043 1046

1044<h3 id="sdkcontrolreadfileresponse">1047<h3 id="sdkcontrolreadfileresponse">

1045 `SDKControlReadFileResponse`1048 `SDKControlReadFileResponse`

1056};1059};

1057```1060```

1058 1061

1059`contents`는 파일 텍스트를 담고 있으며, `encoding: 'base64'`를 요청한 경우 base64 데이터를 담습니다. 이 경우 응답의 `encoding` 필드는 `'base64'`로 설정됩니다. `absPath`는 확인된 절대 경로입니다. `truncated`는 파일이 `maxBytes` 상한보다 길어 내용이 그 한도에서 잘린 경우에 설정됩니다.1062`contents`는 파일 텍스트를 담으며, `encoding: 'base64'`를 요청한 경우에는 base64 데이터를 담습니다. 이 경우 응답의 `encoding` 필드는 `'base64'`로 설정됩니다. `absPath`는 확인된 절대 경로입니다. `truncated`는 파일이 `maxBytes` 상한보다 길어서 내용이 해당 한도에서 잘린 경우에 설정됩니다.

1060 1063

1061<h4 id="what-readfile-can-read">1064<h4 id="what-readfile-can-read">

1062 `readFile()`이 읽을 수 있는 항목1065 `readFile()`이 읽을 수 있는 파일

1063</h4>1066</h4>

1064 1067

1065`readFile()`은 Read 도구보다 좁은 범위의 파일을 제공합니다:1068`readFile()`은 Read 도구보다 좁은 범위의 파일을 제공합니다.

1066 1069

1067* `cwd` 및 `additionalDirectories`와 같은 세션의 작업 디렉터리 중 하나에 있는 일반 파일1070* `cwd` 및 `additionalDirectories`와 같은 세션의 작업 디렉터리 중 하나에 있는 일반 파일

1068* 도구 결과와 같이 세션에 대한 Claude Code 자체 파일 일부1071* 도구 결과와 같이 세션에 대한 Claude Code 자체 파일 일부

1069 1072

1070`Read` 거부 및 확인 규칙은 여전히 일치하는 경로를 차단하며, 광범위한 `Read` 허용 규칙이 나머지 파일 시스템을 `readFile()`에 열어 주지는 않습니다. 그 외의 경우 호출은 `null`로 resolve됩니다.1073`Read` 거부 및 확인 요청 규칙은 여전히 일치하는 경로를 차단하며, 광범위한 `Read` 허용 규칙이 나머지 파일 시스템을 `readFile()`에 개방하지는 않습니다. 그 외의 경우 호출은 `null`로 resolve됩니다.

1071 1074

1072<h3 id="sdkcontrolreloadpluginsresponse">1075<h3 id="sdkcontrolreloadpluginsresponse">

1073 `SDKControlReloadPluginsResponse`1076 `SDKControlReloadPluginsResponse`

1096};1099};

1097```1100```

1098 1101

1099컬렉션 필드는 호출 이후의 세션을 설명합니다:1102컬렉션 필드는 호출 후의 세션을 설명합니다.

1100 1103

1101* `commands`, `agents`, `mcpServers`: `supportedCommands()`, `supportedAgents()`, `mcpServerStatus()`가 반환하는 것과 동일한 형태의 세션 명령, 서브에이전트, MCP 서버 상태입니다. `supportedAgents()`는 초기화 시 캡처된 목록을 계속 반환하므로, 다시 로드한 후의 집합은 여기의 `agents`를 읽으세요1104* `commands`, `agents`, `mcpServers`: 세션의 명령, 서브에이전트, MCP 서버 상태로, `supportedCommands()`, `supportedAgents()`, `mcpServerStatus()`가 반환하는 것과 동일한 형태입니다. `supportedAgents()`는 초기화 시 캡처된 목록을 계속 반환하므로, 다시 로드한 후의 집합은 여기의 `agents`에서 읽으세요

1102* `plugins`: 로드된 각 플러그인과 그 `name` 및 설치 `path`입니다. `version`은 플러그인 매니페스트에 선언된 내용을 반복하며 플러그인 작성자가 제어하므로, 신뢰하기 전에 검증하세요. 매니페스트에 선언된 것이 없으면 생략됩니다1105* `plugins`: 로드된 각 플러그인과 그 `name` 및 설치 `path`입니다. `version`은 플러그인 매니페스트가 선언한 내용을 그대로 반영하며 플러그인 작성자가 제어하므로, 신뢰하기 전에 검증하세요. 매니페스트에 선언이 없으면 생략됩니다

1103* `error_count`: 플러그인 로드 중 발생한 오류 수1106* `error_count`: 플러그인 로드 중 발생한 오류 수입니다

1104 1107

1105대화의 프롬프트 캐시를 무효화할 다시 로드를 적용하는 대신 보류하려면 `reloadPlugins()`에 `{ holdOnCacheImpact: true }`를 전달하세요. Claude Code는 대화형 `/reload-plugins` 명령이 [캐시 비용에 대해 경고](/docs/ko/prompt-caching#enabling-or-disabling-a-plugin)하기 전에 수행하는 검사를 실행합니다. 이 옵션은 Agent SDK v0.3.268 이상이 필요합니다. `pathToClaudeCodeExecutable`로 지정한 실행 파일처럼 v2.1.268보다 오래된 Claude Code 실행 파일은 이 옵션을 무시하고 다시 로드를 적용합니다.1108대화의 프롬프트 캐시를 무효화할 다시 로드를 적용하는 대신 보류하려면 `reloadPlugins()`에 `{ holdOnCacheImpact: true }`를 전달하세요. Claude Code는 대화형 `/reload-plugins` 명령이 [캐시 비용에 대해 경고하기](/docs/ko/prompt-caching#enabling-or-disabling-a-plugin) 전에 수행하는 검사를 실행합니다. 이 옵션에는 Agent SDK v0.3.268 이상이 필요합니다. `pathToClaudeCodeExecutable`로 지정한 실행 파일처럼 v2.1.268보다 오래된 Claude Code 실행 파일은 이 옵션을 무시하고 다시 로드를 적용합니다.

1106 1109

1107옵션을 전달한 경우 `held`를 읽어 결과를 확인하세요:1110이 옵션을 전달한 경우 `held`를 읽어 결과를 확인하세요.

1108 1111

1109* `true`: 다시 로드가 적용되지 않았으며, 컬렉션 필드는 현재 그대로의 세션을 설명합니다. `cache_impact`는 적용 시 무엇이 변경될지를 알려 줍니다. 그래도 적용하려면 옵션 없이 `reloadPlugins()`를 다시 호출하세요.1112* `true`: 다시 로드가 적용되지 않았으며, 컬렉션 필드는 여전히 현재 상태의 세션을 설명합니다. `cache_impact`는 적용 시 무엇이 변경되는지 알려 줍니다. 그래도 적용하려면 옵션 없이 `reloadPlugins()`를 다시 호출하세요.

1110* `false`: 검사에서 캐시 영향이 발견되지 않았으며 다시 로드가 적용되었습니다.1113* `false`: 검사에서 캐시 영향이 발견되지 않았으며, 다시 로드가 적용되었습니다.

1111* 없음: 옵션을 전달하지 않았거나, Claude Code 실행 파일이 v2.1.268보다 오래되어 다시 로드를 적용했습니다.1114* 없음: 옵션을 전달하지 않았거나, Claude Code 실행 파일이 v2.1.268보다 오래되어 다시 로드를 적용했습니다.

1112 1115

1113`cache_impact`는 `held: true`와 함께일 때만 존재합니다. `mcp_servers_added`와 `mcp_servers_removed`는 다시 로드가 등록하거나 제거할 플러그인 MCP 서버를 범위가 지정된 `plugin:<plugin>:<server>` 이름으로 나타냅니다. 이름은 플러그인 작성자가 정하므로 표시하기 전에 검증하세요. `lsp_tool_change`는 적용 시 LSP 도구가 추가되는지 제거되는지를 나타내며, 둘 다 아니면 `null`입니다. `may-` 형식은 검사가 대기 중인 플러그인 집합을 완전히 파악하지 못했음을 의미합니다.1116`cache_impact`는 `held: true`와 함께 있을 때만 존재합니다. `mcp_servers_added`와 `mcp_servers_removed`는 다시 로드가 등록하거나 제거할 플러그인 MCP 서버를 범위가 지정된 `plugin:<plugin>:<server>` 이름으로 나타냅니다. 이 이름은 플러그인 작성자가 정하므로 표시하기 전에 검증하세요. `lsp_tool_change`는 적용 시 LSP 도구가 추가되는지 제거되는지를 나타내며, 둘 다 아니면 `null`입니다. `may-` 형식은 검사가 대기 중인 플러그인 집합을 완전히 파악할 수 없었음을 의미합니다.

1114 1117

1115<h3 id="sdkcontrolreloadskillsresponse">1118<h3 id="sdkcontrolreloadskillsresponse">

1116 `SDKControlReloadSkillsResponse`1119 `SDKControlReloadSkillsResponse`

1144 `SDKControlMcpReadResourceResponse`1147 `SDKControlMcpReadResourceResponse`

1145</h3>1148</h3>

1146 1149

1147[`readMcpResource()`](#query-object)의 반환 타입으로, MCP 서버의 `resources/read` 결과를 담고 있습니다. TypeScript Agent SDK v0.3.280 이상이 필요합니다.1150[`readMcpResource()`](#query-object)의 반환 타입으로, MCP 서버의 `resources/read` 결과를 담습니다. TypeScript Agent SDK v0.3.280 이상이 필요합니다.

1148 1151

1149```typescript theme={null}1152```typescript theme={null}

1150type SDKControlMcpReadResourceResponse = {1153type SDKControlMcpReadResourceResponse = {

1158};1161};

1159```1162```

1160 1163

1161`readMcpResource()`에는 `mcpServerStatus()`가 보고하는 서버 이름과, 도구가 [`_meta`](#mcpserverstatus)에 선언한 `ui.resourceUri`와 같은 `ui://` URI를 전달하세요. 다른 URI 스킴, 애플리케이션이 직접 호스팅하는 [SDK MCP 서버](#createsdkmcpserver), 연결되지 않은 서버에 대해서는 호출이 거부됩니다. init 메시지의 [`capabilities`](#sdksystemmessage)에 `mcp_read_resource_v1`이 포함된 경우 사용할 수 있습니다.1164`readMcpResource()`에는 `mcpServerStatus()`가 보고하는 서버 이름과, 도구가 [`_meta`](#mcpserverstatus)에서 선언하는 `ui.resourceUri`와 같은 `ui://` URI를 전달하세요. 다른 URI 스킴, 애플리케이션이 직접 호스팅하는 [SDK MCP 서버](#createsdkmcpserver), 연결되지 않은 서버에 대해서는 호출이 거부됩니다. init 메시지의 [`capabilities`](#sdksystemmessage)에 `mcp_read_resource_v1`이 포함된 경우에 사용할 수 있습니다.

1162 1165

1163각 `contents` 항목은 서버가 보낸 그대로의 콘텐츠 항목 하나이며, Claude Code용으로 예약된 `com.anthropic/` 접두사 아래의 `_meta` 키는 제외됩니다. `blob`은 바이너리 항목의 base64 데이터를 담고, `_meta`는 항목 자체의 `_meta`로, MCP Apps 서버가 리소스의 `ui.csp`와 `ui.permissions`를 넣는 곳입니다.1166각 `contents` 항목은 서버가 보낸 콘텐츠 항목 하나이며, Claude Code용으로 예약된 `com.anthropic/` 접두사 아래의 `_meta` 키는 제외됩니다. `blob`은 바이너리 항목의 base64 데이터를 담고, `_meta`는 항목 자체의 `_meta`로, MCP Apps 서버가 리소스의 `ui.csp`와 `ui.permissions`를 넣는 곳입니다.

1164 1167

1165콘텐츠는 신뢰할 수 없는 서드파티 HTML이므로 샌드박스에서 렌더링하세요.1168콘텐츠는 신뢰할 수 없는 서드파티 HTML이므로 샌드박스에서 렌더링하세요.

1166 1169

1192 1195

1193| 필드 | 필수 | 설명 |1196| 필드 | 필수 | 설명 |

1194| :- | :- | :- |1197| :- | :- | :- |

1195| `description` | 예 | 이 에이전트를 언제 사용해야 하는지에 대한 자연어 설명 |1198| `description` | 예 | 이 에이전트를 언제 사용해야 하는지에 대한 자연어 설명입니다 |

1196| `tools` | 아니요 | 허용된 도구 이름의 배열입니다. 생략하면 [서브에이전트가 사용할 수 있는 모든 도구](/docs/ko/sub-agents#available-tools)를 상속합니다. 에이전트의 컨텍스트에 스킬을 미리 로드하려면 여기에 `'Skill'`을 나열하는 대신 `skills` 필드를 사용하세요 |1199| `tools` | 아니요 | 허용되는 도구 이름의 배열입니다. 생략하면 [서브에이전트가 사용할 수 있는 모든 도구](/docs/ko/sub-agents#available-tools)를 상속합니다. 에이전트의 컨텍스트에 스킬을 미리 로드하려면 여기에 `'Skill'`을 나열하지 말고 `skills` 필드를 사용하세요 |

1197| `disallowedTools` | 아니요 | 이 에이전트에 대해 명시적으로 허용하지 않을 도구 이름의 배열입니다. MCP 서버 수준 패턴도 허용됩니다. `mcp__server` 또는 `mcp__server__*`는 해당 서버의 모든 도구를 제거하고, `mcp__*`는 모든 서버의 모든 MCP 도구를 제거합니다 |1200| `disallowedTools` | 아니요 | 이 에이전트에 대해 명시적으로 허용하지 않을 도구 이름의 배열입니다. MCP 서버 수준 패턴도 허용됩니다. `mcp__server` 또는 `mcp__server__*`는 해당 서버의 모든 도구를 제거하고, `mcp__*`는 모든 서버의 모든 MCP 도구를 제거합니다 |

1198| `prompt` | 예 | 에이전트의 시스템 프롬프트 |1201| `prompt` | 예 | 에이전트의 시스템 프롬프트입니다 |

1199| `model` | 아니요 | 이 에이전트의 모델 재정의입니다. `'fable'`, `'opus'`, `'sonnet'`, `'haiku'`, `'inherit'`와 같은 별칭 또는 전체 모델 ID를 받습니다. `'inherit'`는 메인 모델을 사용합니다. 생략하면 Claude Code가 [서브에이전트 모델 순서](/docs/ko/sub-agents#choose-a-model)에 따라 모델을 선택합니다 |1202| `model` | 아니요 | 이 에이전트의 모델 재정의입니다. `'fable'`, `'opus'`, `'sonnet'`, `'haiku'`, `'inherit'`와 같은 별칭 또는 전체 모델 ID를 허용합니다. `'inherit'`는 메인 모델을 사용합니다. 생략하면 Claude Code는 [서브에이전트 모델 순서](/docs/ko/sub-agents#choose-a-model)에 따라 모델을 선택합니다 |

1200| `mcpServers` | 아니요 | 이 에이전트의 MCP 서버 사양 |1203| `mcpServers` | 아니요 | 이 에이전트의 MCP 서버 사양입니다 |

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

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

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

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

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

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

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

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

1209| `criticalSystemReminder_EXPERIMENTAL` | 아니요 | 실험적 기능: 시스템 프롬프트에 추가되는 중요 알림 |1212| `criticalSystemReminder_EXPERIMENTAL` | 아니요 | 실험적 기능: 시스템 프롬프트에 추가되는 중요 알림입니다 |

1210 1213

1211<h3 id="agentmcpserverspec">1214<h3 id="agentmcpserverspec">

1212 `AgentMcpServerSpec`1215 `AgentMcpServerSpec`

1213</h3>1216</h3>

1214 1217

1215서브에이전트가 사용할 수 있는 MCP 서버를 지정합니다. 서버 이름(상위의 `mcpServers` 구성에 있는 서버를 참조하는 문자열) 또는 서버 이름을 구성에 매핑하는 인라인 서버 구성 레코드일 수 있습니다.1218서브에이전트에서 사용할 수 있는 MCP 서버를 지정합니다. 서버 이름(상위의 `mcpServers` 구성에 있는 서버를 참조하는 문자열)이거나, 서버 이름을 구성에 매핑하는 인라인 서버 구성 레코드일 수 있습니다.

1216 1219

1217```typescript theme={null}1220```typescript theme={null}

1218type AgentMcpServerSpec = string | Record<string, McpServerConfigForProcessTransport>;1221type AgentMcpServerSpec = string | Record<string, McpServerConfigForProcessTransport>;

1224 `SettingSource`1227 `SettingSource`

1225</h3>1228</h3>

1226 1229

1227SDK가 설정을 로드할 파일 시스템 기반 구성 소스를 제어합니다.1230SDK가 설정을 로드하는 파일 시스템 기반 구성 소스를 제어합니다.

1228 1231

1229```typescript theme={null}1232```typescript theme={null}

1230type SettingSource = "user" | "project" | "local";1233type SettingSource = "user" | "project" | "local";

1234| :- | :- | :- |1237| :- | :- | :- |

1238 1241

1239<h4 id="default-behavior">1242<h4 id="default-behavior">

1240 기본 동작1243 기본 동작

1241</h4>1244</h4>

1242 1245

1243`settingSources`를 생략하거나 `undefined`로 두면 `query()`는 Claude Code CLI와 동일한 파일 시스템 설정(user, project, local)을 로드합니다. 이 옵션과 관계없이 읽히는 입력과 이를 비활성화하는 방법은 [settingSources가 제어하지 않는 항목](/docs/ko/agent-sdk/claude-code-features#what-settingsources-does-not-control)을 참조하세요.1246`settingSources`가 생략되거나 `undefined`인 경우, `query()`는 Claude Code CLI와 동일한 파일 시스템 설정(user, project, local)을 로드합니다. 이 옵션과 관계없이 읽히는 입력과 이를 비활성화하는 방법은 [settingSources가 제어하지 않는 항목](/docs/ko/agent-sdk/claude-code-features#what-settingsources-does-not-control)을 참조하세요.

1244 1247

1245<h4 id="why-use-settingsources">1248<h4 id="why-use-settingsources">

1246 settingSources를 사용하는 이유1249 settingSources를 사용하는 이유

1278 설정 우선순위1281 설정 우선순위

1279</h4>1282</h4>

1280 1283

1281여러 소스가 로드되면 설정은 다음 우선순위(높은 순에서 낮은 순)로 병합됩니다.1284여러 소스가 로드되면 설정은 다음 우선순위(높은 순에서 낮은 순)에 따라 병합됩니다.

1282 1285

12831. 로컬 설정(`.claude/settings.local.json`)12861. 로컬 설정(`.claude/settings.local.json`)

12842. 프로젝트 설정(`.claude/settings.json`)12872. 프로젝트 설정(`.claude/settings.json`)

12853. 사용자 설정(`~/.claude/settings.json`)12883. 사용자 설정(`~/.claude/settings.json`)

1286 1289

1287`agents`, `allowedTools`, `settings`와 같은 프로그래밍 방식 옵션은 사용자, 프로젝트, 로컬 파일 시스템 설정을 재정의합니다. 관리형 정책 설정은 프로그래밍 방식 옵션보다 우선합니다.1290`agents`, `allowedTools`, `settings` 같은 프로그래밍 방식 옵션은 user, project, local 파일 시스템 설정을 재정의합니다. 관리형 정책 설정은 프로그래밍 방식 옵션보다 우선합니다.

1288 1291

1289<h3 id="permissionmode">1292<h3 id="permissionmode">

1290 `PermissionMode`1293 `PermissionMode`

1306 1309

1307도구 사용을 제어하기 위한 사용자 정의 권한 함수 타입입니다.1310도구 사용을 제어하기 위한 사용자 정의 권한 함수 타입입니다.

1308 1311

1309이 함수는 대화형 권한 프롬프트를 대체하는 SDK 기능으로, [권한 평가 흐름](/docs/ko/agent-sdk/permissions#how-permissions-are-evaluated)이 프롬프트로 귀결될 때만 호출됩니다. `allowedTools` 항목, 설정의 허용 규칙, 또는 `acceptEdits`나 `bypassPermissions` 같은 권한 모드로 이미 승인된 도구 호출은 이 함수를 호출하지 않습니다. 모든 도구 호출을 제어하려면 대신 [`PreToolUse` 훅](/docs/ko/agent-sdk/hooks)을 사용하세요.1312이 함수는 대화형 권한 프롬프트를 대체하는 SDK 기능으로, [권한 평가 흐름](/docs/ko/agent-sdk/permissions#how-permissions-are-evaluated)이 프롬프트로 귀결될 때만 호출됩니다. `allowedTools` 항목, 설정의 allow 규칙, 또는 `acceptEdits`나 `bypassPermissions` 같은 권한 모드에 의해 이미 승인된 도구 호출은 이 함수를 호출하지 않습니다. 모든 도구 호출을 제어하려면 대신 [`PreToolUse` 훅](/docs/ko/agent-sdk/hooks)을 사용하세요.

1310 1313

1311허용 규칙은 [어떤 모드도 자동 승인하지 않는 작업](/docs/ko/permission-modes#actions-no-mode-auto-approves)을 사전 승인하지 않습니다. 이러한 작업 중 어떤 것이 콜백에 도달하는지, 그리고 `dontAsk` 및 `auto` 모드에서 어떻게 처리되는지는 [권한 평가 방식](/docs/ko/agent-sdk/permissions#how-permissions-are-evaluated)을 참조하세요.1314allow 규칙은 [어떤 모드에서도 자동 승인되지 않는 작업](/docs/ko/permission-modes#actions-no-mode-auto-approves)을 사전 승인하지 않습니다. 그중 어떤 작업이 콜백에 도달하는지, 그리고 `dontAsk` 및 `auto` 모드에서 어떻게 처리되는지는 [권한 평가 방식](/docs/ko/agent-sdk/permissions#how-permissions-are-evaluated)을 참조하세요.

1312 1315

1313```typescript theme={null}1316```typescript theme={null}

1314type CanUseTool = (1317type CanUseTool = (

1331 1334

1332| 옵션 | 타입 | 설명 |1335| 옵션 | 타입 | 설명 |

1333| :- | :- | :- |1336| :- | :- | :- |

1335| `suggestions` | [`PermissionUpdate`](#permissionupdate)`[]` | 이 도구에 대해 사용자에게 다시 확인을 요청하지 않도록 제안된 권한 업데이트. Bash 프롬프트에는 `localSettings` [대상](#permissionupdatedestination)이 포함된 제안이 있으므로, 이를 `updatedPermissions`로 반환하면 규칙이 `.claude/settings.local.json`에 기록되어 세션 간에 유지됩니다. |1338| `suggestions` | [`PermissionUpdate`](#permissionupdate)`[]` | 이 도구에 대해 사용자에게 다시 확인을 요청하지 않도록 하는 권한 업데이트 제안입니다. Bash 프롬프트에는 `localSettings` [대상](#permissionupdatedestination)을 가진 제안이 포함되므로, 이를 `updatedPermissions`로 반환하면 규칙이 `.claude/settings.local.json`에 기록되어 세션 간에 유지됩니다. |

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

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

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

1344 1347

1345콜백은 일반적으로 [`PermissionResult`](#permissionresult)를 반환하여 요청을 처리하며, SDK는 이를 `control_response`로서 자체 전송 계층을 통해 다시 기록합니다. 애플리케이션이 `requestId`를 포함하여 자체 채널로 이 요청에 대한 `control_response`를 이미 보낸 경우에만 `null`을 반환하세요. 그러면 SDK는 전송 계층에 응답을 기록하는 것을 건너뜁니다. 그 외의 경우에 `null`을 반환하면 `control_response`가 전혀 전송되지 않고 권한 프롬프트는 시간 초과되지 않으므로, 도구 호출이 무기한 차단된 상태로 남습니다.1348콜백은 일반적으로 [`PermissionResult`](#permissionresult)를 반환하여 요청을 처리하며, SDK는 이를 자체 전송 계층을 통해 `control_response`로 다시 기록합니다. 애플리케이션이 `requestId`를 포함하여 자체 채널로 이 요청에 대한 `control_response`를 이미 보낸 경우에만 `null`을 반환하세요. 그러면 SDK는 전송 계층에 응답을 기록하는 작업을 건너뜁니다. 그 외의 경우에 `null`을 반환하면 `control_response`가 전송되지 않고 권한 프롬프트는 시간 초과되지 않으므로 도구 호출이 무기한 차단됩니다.

1346 1349

1347`requestId` 옵션과 `null` 반환 값은 Claude Code v2.1.199 이상이 필요합니다.1350`requestId` 옵션과 `null` 반환 값은 Claude Code v2.1.199 이상이 필요합니다.

1348 1351

1350 `PermissionResult`1353 `PermissionResult`

1351</h3>1354</h3>

1352 1355

1353권한 확인 결과입니다.1356권한 확인의 결과입니다.

1354 1357

1355```typescript theme={null}1358```typescript theme={null}

1356type PermissionResult =1359type PermissionResult =

1372 `ToolConfig`1375 `ToolConfig`

1373</h3>1376</h3>

1374 1377

1375내장 도구 동작에 대한 구성입니다.1378기본 제공 도구 동작에 대한 구성입니다.

1376 1379

1377```typescript theme={null}1380```typescript theme={null}

1378type ToolConfig = {1381type ToolConfig = {

1478 1481

1479| 필드 | 타입 | 설명 |1482| 필드 | 타입 | 설명 |

1480| :- | :- | :- |1483| :- | :- | :- |

1483| `skipMcpDiscovery` | `boolean` | `true`이면 SDK는 이 플러그인에서 스킬, 훅, 에이전트, 명령을 로드하지만 `.mcp.json`이나 매니페스트의 `mcpServers`는 읽지 않습니다. 애플리케이션이 플러그인의 MCP 연결을 직접 관리하는 경우 이 값을 설정하세요. |1486| `skipMcpDiscovery` | `boolean` | `true`인 경우, SDK는 이 플러그인에서 스킬, 훅, 에이전트, 명령을 로드하지만 `.mcp.json`이나 매니페스트의 `mcpServers`는 읽지 않습니다. 애플리케이션이 플러그인의 MCP 연결을 직접 관리하는 경우 이 값을 설정하세요. |

1484 1487

1485**예시:**1488**예시:**

1486 1489

1491];1494];

1492```1495```

1493 1496

1494플러그인 생성 및 사용에 대한 전체 정보는 [플러그인](/docs/ko/agent-sdk/plugins)을 참조하세요.1497플러그인 생성 및 사용에 대한 자세한 내용은 [플러그인](/docs/ko/agent-sdk/plugins)을 참조하세요.

1495 1498

1496<h2 id="message-types">1499<h2 id="message-types">

1497 메시지 타입1500 메시지 타입

3786};3789};

3787```3790```

3788 3791

3789코드 검토 결과를 구조화된 목록으로 보고하여 Claude Code가 텍스트로 인쇄하는 대신 렌더링할 수 있습니다. `level`은 검토가 실행된 노력 수준입니다. 결과는 가장 심각한 것부터 정렬되며 호출당 최대 32개이고, 배열은 생존한 것이 없을 때 비어 있습니다. Claude Code v2.1.196 이상이 필요합니다.3792코드 리뷰 결과를 구조화된 목록으로 보고하여 Claude Code가 텍스트로 인쇄하는 대신 렌더링할 수 있습니다. 결과는 가장 심각한 것부터 정렬되며 호출당 최대 32개이고, 배열은 남은 결과가 없을 때 비어 있습니다. Claude Code v2.1.196 이상이 필요합니다.

3793

3794`level`은 선택 사항이며 Claude가 리뷰에 대해 보고하는 effort 수준을 담습니다. Claude Code는 이를 리뷰가 실행된 수준과 비교하지 않으므로 두 값이 다를 수 있습니다.

3790 3795

3791각 결과는 다음 필드를 전달합니다:3796각 결과는 다음 필드를 전달합니다:

3792 3797

4836};4841};

4837```4842```

4838 4843

4839보고된 결과의 수, 검토가 실행된 노력 수준, 결과 본문에 대해 에코백된 결과를 반환합니다. Claude Code v2.1.196 이상이 필요합니다. 에코백된 `short_summary` 필드는 Claude Code v2.1.212 이상이 필요합니다.4844보고된 결과의 수, Claude가 전달한 `level` 값, 결과 본문을 위해 에코백된 결과를 반환합니다. Claude Code v2.1.196 이상이 필요합니다. 에코백된 `short_summary` 필드는 Claude Code v2.1.212 이상이 필요합니다.

4840 4845

4841<h3 id="artifact-2">4846<h3 id="artifact-2">

4842 Artifact4847 Artifact

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

5458```5463```

5459 5464

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

5461 5466

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

5463 `SpawnedProcess`5468 `SpawnedProcess`

5528 5533

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

5530 5535

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

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

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

5534 5539

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

5849 tasks: {5854 tasks: {

5850 task_id: string;5855 task_id: string;

5851 task_type: string;5856 task_type: string;

5857 subagent_type?: string;

5852 description: string;5858 description: string;

5853 ambient?: boolean;5859 ambient?: boolean;

5854 }[];5860 }[];

5857};5863};

5858```5864```

5859 5865

5866`subagent_type`은 [`task_type`](#sdktaskstartedmessage)이 `"local_agent"`인 항목에서 서브에이전트 타입의 이름을 지정합니다. 예를 들어 `general-purpose` 또는 사용자 정의 서브에이전트의 이름입니다. 필드는 Agent SDK v0.3.293 이상이 필요합니다.

5867

5860<h3 id="sdkthinkingtokensmessage">5868<h3 id="sdkthinkingtokensmessage">

5861 `SDKThinkingTokensMessage`5869 `SDKThinkingTokensMessage`

5862</h3>5870</h3>

agent-view.md +1 −0

Details

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

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

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

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

823 824

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

agents.md +1 −1

Details

20 20

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

22 22

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

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

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

26 26

amazon-bedrock.md +2 −2

Details

188 188

189캐시는 공급자 체인을 사용하지 않는 Amazon Bedrock API 키를 제외한 위의 모든 자격 증명 옵션을 포함합니다. 대신 모든 요청에서 체인을 해결하려면 [`CLAUDE_CODE_SKIP_AWS_CRED_CACHE=1`](/docs/ko/env-vars)을 설정합니다.189캐시는 공급자 체인을 사용하지 않는 Amazon Bedrock API 키를 제외한 위의 모든 자격 증명 옵션을 포함합니다. 대신 모든 요청에서 체인을 해결하려면 [`CLAUDE_CODE_SKIP_AWS_CRED_CACHE=1`](/docs/ko/env-vars)을 설정합니다.

190 190

191체인의 각 해결은 60초 후 시간 초과됩니다. 체인의 단계가 정지되면(예: 받을 수 없는 입력을 기다리는 `credential_process` 도우미), 요청은 [`AWS default-chain credential resolve timed out`](/docs/ko/errors#aws-default-chain-credential-resolve-timed-out)으로 실패합니다. 체인이 `aws-vault`와 같은 래퍼를 통한 MFA가 있는 브라우저 기반 SSO와 같이 합법적으로 더 오래 필요한 대화형 로그인을 실행하는 경우 [`CLAUDE_CODE_AWS_CHAIN_RESOLVE_TIMEOUT_MS`](/docs/ko/env-vars)를 사용하여 밀리초 단위로 제한을 높입니다. v2.1.207 이전에는 정지된 자격 증명 해결로 인해 요청이 무한정 대기했습니다.191캐시를 채우는 해결은 60초 후 시간 초과됩니다. 체인의 단계가 정지되면(예: 받을 수 없는 입력을 기다리는 `credential_process` 도우미), 요청은 [`AWS default-chain credential resolve timed out`](/docs/ko/errors#aws-default-chain-credential-resolve-timed-out)으로 실패합니다. 체인이 `aws-vault`와 같은 래퍼를 통한 MFA가 있는 브라우저 기반 SSO와 같이 합법적으로 더 오래 필요한 대화형 로그인을 실행하는 경우 [`CLAUDE_CODE_AWS_CHAIN_RESOLVE_TIMEOUT_MS`](/docs/ko/env-vars)를 사용하여 밀리초 단위로 제한을 높입니다. `CLAUDE_CODE_SKIP_AWS_CRED_CACHE=1`이 설정된 경우 각 API 요청은 이 제한 없이 체인을 해결합니다.

192 192

193Amazon Bedrock API 키로 인증하는 경우를 제외하고, [설정 마법사](#sign-in-with-bedrock)는 자격 증명을 확인하는 동안 수행하는 각 AWS 호출과 각 모델 확인 전의 자격 증명 조회에 동일한 제한을 적용합니다. 자격 증명 확인 중에 제한을 초과하는 확인은 [`Timed out after 60s waiting for AWS`](/docs/ko/errors#bedrock-setup-verification-timed-out-waiting-for-aws)로 실패합니다.193Amazon Bedrock API 키로 인증하는 경우를 제외하고, [설정 마법사](#sign-in-with-bedrock)는 자격 증명을 확인하는 동안 수행하는 각 AWS 호출과 각 모델 확인 전의 자격 증명 조회에 동일한 제한을 적용합니다. 자격 증명 확인 중에 제한을 초과하는 확인은 [`Timed out after 60s waiting for AWS`](/docs/ko/errors#bedrock-setup-verification-timed-out-waiting-for-aws)로 실패합니다.

194 194

682 682

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

684 684

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

686 686

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

688 688

authentication.md +1 −1

Details

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

13</h2>13</h2>

14 14

15[Claude Code를 설치](/docs/ko/setup#install-claude-code)한 후 터미널에서 `claude`를 실행합니다. 처음 실행할 때 Claude Code는 로그인할 수 있도록 브라우저 창을 엽니다. `ANTHROPIC_API_KEY` 환경 변수를 설정한 경우 Claude Code는 로그인 프롬프트를 건너뛰고 대신 키를 승인하도록 요청합니다.15[Claude Code를 설치](/docs/ko/setup#install-claude-code)한 후 터미널에서 `claude`를 실행합니다. 처음 실행할 때 Claude Code는 로그인할 수 있도록 브라우저 창을 엽니다. `ANTHROPIC_API_KEY` 환경 변수를 설정했고 Claude Code가 해당 키를 사용할지 물을 때 키를 승인하면 Claude Code는 로그인 프롬프트를 건너뜁니다.

16 16

17브라우저가 자동으로 열리지 않으면 `c`를 눌러 로그인 URL을 클립보드에 복사한 후 브라우저에 붙여넣습니다.17브라우저가 자동으로 열리지 않으면 `c`를 눌러 로그인 URL을 클립보드에 복사한 후 브라우저에 붙여넣습니다.

18 18

auto-mode-config.md +1 −1

Details

351}351}

352```352```

353 353

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

355 355

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

357claude auto-mode critique357claude auto-mode critique

chrome.md +1 −1

Details

343 343

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

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

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

claude-apps-gateway.md +15 −13

Details

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

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

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

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

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

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

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

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

83 83

91 </Step>91 </Step>

92 92

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

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

95 </Step>95 </Step>

96 96

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

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

118 118

119 store:119 store:

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

121 121

122 upstreams:122 upstreams:

123 - provider: bedrock123 - provider: bedrock

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

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

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

127 127

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

132 auto_include_builtin_models: true132 auto_include_builtin_models: true

133 ```133 ```

134 134

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

136 136

137 <Note>137 <Note>

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

139 139

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

141 </Note>141 </Note>

142 </Step>142 </Step>

143 143

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

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

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

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

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

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

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

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

173 ```173 ```

174 174

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

176 176

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

178

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

178 180

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

180 182

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

188 ```190 ```

189 191

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

191 193

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

193 195

253 </Step>255 </Step>

254 256

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

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

257 </Step>259 </Step>

258</Steps>260</Steps>

259 261

claude-apps-gateway-config.md +53 −12

Details

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

159 159

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

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

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

163 163

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

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

227 227

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

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

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

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

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

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

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

314</h5>314</h5>

315 315

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

317 317

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

319 319

376| 다른 곳 | `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY` 및 `AWS_SESSION_TOKEN` 환경 변수를 통해 자격 증명을 전달하거나 `${VAR}` 확장으로 `auth:`에서 명시적으로 설정합니다. |376| 다른 곳 | `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY` 및 `AWS_SESSION_TOKEN` 환경 변수를 통해 자격 증명을 전달하거나 `${VAR}` 확장으로 `auth:`에서 명시적으로 설정합니다. |

377| 지역 | `region:`은 API 엔드포인트 지역입니다. 교차 지역 추론 프로필은 선택한 지역과 무관하게 지역(US, EU, APAC)을 통해 라우팅합니다. 비 US 지역 또는 프로비저닝된 처리량 ARN의 경우 올바른 업스트림별 ID를 사용하여 [`models:`](#models) 블록을 추가합니다. |377| 지역 | `region:`은 API 엔드포인트 지역입니다. 교차 지역 추론 프로필은 선택한 지역과 무관하게 지역(US, EU, APAC)을 통해 라우팅합니다. 비 US 지역 또는 프로비저닝된 처리량 ARN의 경우 올바른 업스트림별 ID를 사용하여 [`models:`](#models) 블록을 추가합니다. |

378 378

379<a id="apply-an-amazon-bedrock-guardrail" />

380

379<h5 id="apply-an-amazon-bedrock-guardrail">381<h5 id="apply-an-amazon-bedrock-guardrail">

380 Amazon Bedrock 가드레일 적용382 Amazon Bedrock 가드레일 적용

381</h5>383</h5>

413 415

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

415 417

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

417 419

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

419upstreams:421upstreams:

470 472

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

472 474

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

474 476

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

476upstreams:478upstreams:

586 588

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

588 590

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

590 592

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

592| - | - |594| - | - |

921 923

922 두 가지 전파 주기가 적용됩니다:924 두 가지 전파 주기가 적용됩니다:

923 925

924 * **정책 내용**: 정책을 편집하고 재배포하면 연결된 클라이언트의 다음 관리형 설정 폴링 시, 1시간 이내에 반영됩니다. 단, [다음 실행 시에만 적용되는 변경](/docs/ko/server-managed-settings#fetch-and-caching-behavior)은 제외됩니다.926 * **정책 내용**: 정책을 편집하고 재배포하면 연결된 Claude Code 클라이언트의 다음 관리형 설정 폴링 시, 1시간 이내에 반영됩니다. 단, [다음 실행 시에만 적용되는 변경](/docs/ko/server-managed-settings#fetch-and-caching-behavior)은 제외됩니다.

925 * **그룹 멤버십**: 사용자의 그룹 멤버십을 변경하면 해당 사용자와 일치하는 정책이 바뀝니다. 이는 다음 세션 재발급, 즉 다음 자동 새로고침 시 적용되며 `session.ttl_hours`로 제한됩니다.927 * **그룹 멤버십**: 사용자의 그룹 멤버십을 변경하면 해당 사용자와 일치하는 정책이 바뀝니다. 이는 다음 세션 재발급, 즉 다음 자동 새로고침 시 적용되며 `session.ttl_hours`로 제한됩니다.

928

929 Claude Desktop은 [자체 일정](#when-a-policy-change-reaches-claude-desktop)을 따릅니다.

926</Note>930</Note>

927 931

928<h4 id="start-sessions-on-a-model-the-policy-allows">932<h4 id="start-sessions-on-a-model-the-policy-allows">

1086 게이트웨이 서버에 Claude Code v2.1.203 이상이 필요하며 명시적 옵트인이 필요합니다. 사용자와 일치하는 정책에 `desktop` 키가 없으면 `/user/bootstrap`은 404를 반환합니다. 빈 `desktop: {}`으로 정책을 옵트인할 수 있으며, `match: {}` 기본 계층의 `desktop` 키는 이를 상속하는 모든 정책을 옵트인합니다. 감사 로그는 각 요청을 `desktop_bootstrap.serve` 또는 `desktop_bootstrap.denied`로 기록합니다.1090 게이트웨이 서버에 Claude Code v2.1.203 이상이 필요하며 명시적 옵트인이 필요합니다. 사용자와 일치하는 정책에 `desktop` 키가 없으면 `/user/bootstrap`은 404를 반환합니다. 빈 `desktop: {}`으로 정책을 옵트인할 수 있으며, `match: {}` 기본 계층의 `desktop` 키는 이를 상속하는 모든 정책을 옵트인합니다. 감사 로그는 각 요청을 `desktop_bootstrap.serve` 또는 `desktop_bootstrap.denied`로 기록합니다.

1087</Note>1091</Note>

1088 1092

1089게이트웨이는 응답의 상당 부분을 일치하는 정책의 `cli` 블록과 최상위 게이트웨이 구성에서 도출합니다:1093Claude Desktop을 배포하지 않는다면 정책에서 `desktop`을 완전히 생략합니다. 그러면 게이트웨이는 모든 사용자에 대해 `/user/bootstrap`에서 404를 반환합니다.

1094

1095<h5 id="settings-the-gateway-derives-for-claude-desktop">

1096 게이트웨이가 Claude Desktop용으로 도출하는 설정

1097</h5>

1098

1099게이트웨이는 부트스트랩 응답의 상당 부분을 일치하는 정책의 `cli` 블록과 최상위 게이트웨이 구성에서 도출합니다:

1090 1100

1091* 모델 목록은 `availableModels`에서 도출합니다. 각 모델의 1M 컨텍스트 옵션은 [Claude Desktop의 확장 컨텍스트](#extended-context-in-claude-desktop)에서 다룹니다1101* 모델 목록은 `availableModels`에서 도출합니다. 각 모델의 1M 컨텍스트 옵션은 [Claude Desktop의 확장 컨텍스트](#extended-context-in-claude-desktop)에서 다룹니다

1092* 비활성화된 도구는 도구 이름만 있는 `permissions.deny` 항목에서 도출합니다. 정책의 `desktop` 블록에서 `disabledBuiltinTools`를 설정하면 게이트웨이는 해당 값과 도출된 목록의 합집합을 제공하므로, 이 방식으로 도구를 더 비활성화할 수는 있지만 `permissions.deny`로 비활성화한 도구를 다시 활성화할 수는 없습니다1102* 비활성화된 도구는 도구 이름만 있는 `permissions.deny` 항목에서 도출합니다. 정책의 `desktop` 블록에서 `disabledBuiltinTools`를 설정하면 게이트웨이는 해당 값과 도출된 목록의 합집합을 제공하므로, 이 방식으로 도구를 더 비활성화할 수는 있지만 `permissions.deny`로 비활성화한 도구를 다시 활성화할 수는 없습니다

1099 1109

1100게이트웨이는 `hooks`나 `Bash(npm *)`와 같은 범위 지정 권한 규칙처럼 Claude Desktop에 대응하는 항목이 없는 키를 부트스트랩 응답에서 생략합니다.1110게이트웨이는 `hooks`나 `Bash(npm *)`와 같은 범위 지정 권한 규칙처럼 Claude Desktop에 대응하는 항목이 없는 키를 부트스트랩 응답에서 생략합니다.

1101 1111

1102Claude Desktop 설정을 직접 지정하려면 `cli` 옆에 선택적 `desktop` 블록을 추가합니다. Claude Desktop의 [관리형 구성 참조](https://claude.com/docs/third-party/claude-desktop/configuration)에 있는 설정을 평면 키 이름으로 작성합니다. `bootstrapUrl`처럼 Claude Desktop이 MDM이나 로컬 파일에서만 읽는 키는 생략합니다. 게이트웨이는 부팅 시 이러한 키를 거부합니다. v2.1.232 이전에는 게이트웨이가 `chatTabEnabled` 및 `disableAutoUpdates`와 같은 11개의 고정된 기능 게이트 키만 허용하고 나머지 모든 키는 부팅 시 거부했습니다. v2.1.227 이전에는 게이트웨이가 부팅 시 `chatTabEnabled` 및 `chatAdvancedFileAnalysisEnabled`도 거부했습니다.1112<h5 id="set-claude-desktop-settings-directly">

1113 Claude Desktop 설정 직접 지정

1114</h5>

1115

1116Claude Desktop 설정을 직접 지정하려면 `cli` 옆에 선택적 `desktop` 블록을 추가합니다. Claude Desktop의 [관리형 구성 참조](https://claude.com/docs/third-party/claude-desktop/configuration)에 있는 설정을 평면 키 이름으로 작성합니다. `bootstrapUrl`처럼 Claude Desktop이 MDM이나 로컬 파일에서만 읽는 키는 생략합니다. 게이트웨이는 부팅 시 이러한 키를 거부합니다.

1117

1118이 예제는 `eng-contractors` 그룹에 대해 `cli` 설정과 함께 세 가지 Claude Desktop 키를 설정합니다:

1103 1119

1104```yaml theme={null}1120```yaml theme={null}

1105managed:1121managed:

1114 banner: { text: "Contractor build: internal use only" }1130 banner: { text: "Contractor build: internal use only" }

1115```1131```

1116 1132

1117모든 키는 선택 사항이며, 생략한 키에는 Claude Desktop이 자체 기본값을 적용합니다. 게이트웨이는 부팅 시 Claude Desktop 자체가 사용하는 구성 스키마로 각 `desktop` 블록을 검증하므로, 실수가 연결된 모든 데스크톱에 전달되는 대신 게이트웨이 시작 시 해당 키를 명시하는 오류로 드러납니다. 블록에 다음이 포함되면 게이트웨이는 부팅에 실패합니다:1133모든 키는 선택 사항이며, 생략한 키에는 Claude Desktop이 자체 기본값을 적용합니다.

1134

1135<h5 id="what-the-gateway-rejects-at-boot">

1136 게이트웨이가 부팅 시 거부하는 항목

1137</h5>

1138

1139게이트웨이는 부팅 시 Claude Desktop 자체가 사용하는 구성 스키마로 각 `desktop` 블록을 검증하므로, 실수가 연결된 모든 데스크톱에 전달되는 대신 게이트웨이 시작 시 해당 키를 명시하는 오류로 드러납니다. 블록에 다음이 포함되면 게이트웨이는 부팅에 실패합니다:

1118 1140

1119* 알 수 없는 키1141* 알 수 없는 키

1120* Claude Desktop이 거부하거나 조용히 무시할 값을 가진 인식된 키. 예를 들어 빈 값이나 중첩된 항목 내부의 철자가 틀린 하위 키입니다. v2.1.260 이전에는 게이트웨이가 `managedMcpServers` 또는 `orgPluginSettings` 항목의 중첩된 객체 내부에 있는 철자가 틀린 필드를 부팅 실패 대신 조용히 무시했습니다.1142* Claude Desktop이 거부하거나 조용히 무시할 값을 가진 인식된 키. 예를 들어 빈 값이나 중첩된 항목 내부의 철자가 틀린 하위 키입니다. v2.1.260 이전에는 게이트웨이가 `managedMcpServers` 또는 `orgPluginSettings` 항목의 중첩된 객체 내부에 있는 철자가 틀린 필드를 부팅 실패 대신 조용히 무시했습니다.

1123 1145

1124`transport`가 없는 `managedMcpServers` 항목처럼 deprecated 값이나 항목 형태를 사용하면, 게이트웨이는 시작되며 대체 항목을 안내하는 경고를 로그에 기록합니다.1146`transport`가 없는 `managedMcpServers` 항목처럼 deprecated 값이나 항목 형태를 사용하면, 게이트웨이는 시작되며 대체 항목을 안내하는 경고를 로그에 기록합니다.

1125 1147

1148v2.1.232 이전에는 게이트웨이가 `chatTabEnabled` 및 `disableAutoUpdates`와 같은 11개의 고정된 기능 게이트 키만 허용하고 나머지 모든 키는 부팅 시 거부했습니다. v2.1.227 이전에는 게이트웨이가 부팅 시 `chatTabEnabled` 및 `chatAdvancedFileAnalysisEnabled`도 거부했습니다.

1149

1150<h5 id="keys-that-need-a-later-gateway-or-claude-desktop-version">

1151 더 새로운 게이트웨이 또는 Claude Desktop 버전이 필요한 키

1152</h5>

1153

1126게이트웨이는 `cli` 블록과 마찬가지로 설치된 버전에 번들된 스키마로 `desktop` 블록을 검증합니다. 더 새로운 Claude Desktop 릴리스에서 도입된 설정을 전달하려면 먼저 게이트웨이를 업그레이드합니다. 예를 들어 `userPluginMarketplacesEnabled` 및 `userPluginUploadsEnabled`에는 게이트웨이 서버의 Claude Code v2.1.260 이상과 구성원 머신의 Claude Desktop 1.37937.0 이상이 필요합니다.1154게이트웨이는 `cli` 블록과 마찬가지로 설치된 버전에 번들된 스키마로 `desktop` 블록을 검증합니다. 더 새로운 Claude Desktop 릴리스에서 도입된 설정을 전달하려면 먼저 게이트웨이를 업그레이드합니다. 예를 들어 `userPluginMarketplacesEnabled` 및 `userPluginUploadsEnabled`에는 게이트웨이 서버의 Claude Code v2.1.260 이상과 구성원 머신의 Claude Desktop 1.37937.0 이상이 필요합니다.

1127 1155

1128`blockReadsOutsideWorkingDirectories`, `disableBypassPermissionsMode`, `configRecheckIntervalMinutes` 및 `sshClientPath`에는 게이트웨이 서버의 Claude Code v2.1.281 이상이 필요합니다. `microsoftAuthBroker`의 `required` 값과 Microsoft 365 `managedMcpServers` 항목의 `continuousAccessEvaluation` 필드도 마찬가지입니다. `required` 값이 도입되기 이전의 Claude Desktop 릴리스는 이를 `disabled`로 읽으므로, 모든 구성원의 Claude Desktop이 이를 지원한 후에만 `required`를 설정합니다. 각 키를 처음 읽는 릴리스는 Claude Desktop의 [관리형 구성 참조](https://claude.com/docs/third-party/claude-desktop/configuration)에 나와 있습니다.1156`blockReadsOutsideWorkingDirectories`, `disableBypassPermissionsMode`, `configRecheckIntervalMinutes` 및 `sshClientPath`에는 게이트웨이 서버의 Claude Code v2.1.281 이상이 필요합니다. `microsoftAuthBroker`의 `required` 값과 Microsoft 365 `managedMcpServers` 항목의 `continuousAccessEvaluation` 필드도 마찬가지입니다. `required` 값이 도입되기 이전의 Claude Desktop 릴리스는 이를 `disabled`로 읽으므로, 모든 구성원의 Claude Desktop이 이를 지원한 후에만 `required`를 설정합니다. 각 키를 처음 읽는 릴리스는 Claude Desktop의 [관리형 구성 참조](https://claude.com/docs/third-party/claude-desktop/configuration)에 나와 있습니다.

1129 1157

1130정책의 `desktop` 블록에서 `orgPluginSettings`를 설정하면, 게이트웨이는 Claude Desktop 1.15200.0 이상이 읽는 배열 형태로 이를 제공합니다. 이전 데스크톱은 배열을 무시하고 플러그인 도구 정책을 강제하지 않으므로, 이에 의존하기 전에 구성원을 1.15200.0 이상으로 업데이트합니다.1158정책의 `desktop` 블록에서 `orgPluginSettings`를 설정하면, 게이트웨이는 Claude Desktop 1.15200.0 이상이 읽는 배열 형태로 이를 제공합니다. 이전 데스크톱은 배열을 무시하고 플러그인 도구 정책을 강제하지 않으므로, 이에 의존하기 전에 구성원을 1.15200.0 이상으로 업데이트합니다.

1131 1159

1160<h5 id="how-a-role-policy-inherits-the-base-desktop-block">

1161 역할 정책이 기본 `desktop` 블록을 상속하는 방식

1162</h5>

1163

1132게이트웨이는 정책의 `desktop` 블록이 설정하지 않은 키를 `match: {}` 캐치올의 `desktop` 블록에서 채우며, 이는 정책의 `cli` 블록을 기본값에서 채우는 것과 같은 방식입니다. 기본값과 역할 정책 모두에서 `disabledBuiltinTools` 또는 `builtinToolPolicy`를 설정하면, 게이트웨이는 기본값의 제한을 유지합니다:1164게이트웨이는 정책의 `desktop` 블록이 설정하지 않은 키를 `match: {}` 캐치올의 `desktop` 블록에서 채우며, 이는 정책의 `cli` 블록을 기본값에서 채우는 것과 같은 방식입니다. 기본값과 역할 정책 모두에서 `disabledBuiltinTools` 또는 `builtinToolPolicy`를 설정하면, 게이트웨이는 기본값의 제한을 유지합니다:

1133 1165

1134* `disabledBuiltinTools`: 게이트웨이는 기본값의 목록과 정책의 목록의 합집합을 사용합니다1166* `disabledBuiltinTools`: 게이트웨이는 기본값의 목록과 정책의 목록의 합집합을 사용합니다

1136 1168

1137그 밖의 모든 키는 역할 정책에서 설정하면 게이트웨이가 역할 정책의 값을 사용합니다. 게이트웨이는 배열이나 `banner`와 같은 중첩 객체를 통째로 대체하므로, 역할 정책에서 `banner.text`를 설정하면 기본값의 `banner.backgroundColor`는 제거됩니다.1169그 밖의 모든 키는 역할 정책에서 설정하면 게이트웨이가 역할 정책의 값을 사용합니다. 게이트웨이는 배열이나 `banner`와 같은 중첩 객체를 통째로 대체하므로, 역할 정책에서 `banner.text`를 설정하면 기본값의 `banner.backgroundColor`는 제거됩니다.

1138 1170

1139Claude Desktop을 배포하지 않는다면 정책에서 `desktop`을 완전히 생략합니다. 그러면 게이트웨이는 모든 사용자에 대해 `/user/bootstrap`에서 404를 반환합니다.1171<h5 id="when-a-policy-change-reaches-claude-desktop">

1172 정책 변경이 Claude Desktop에 반영되는 시점

1173</h5>

1174

1175변경된 정책으로 게이트웨이를 재배포한 후, Claude Desktop은 대부분의 설정을 다음에 시작할 때만 적용합니다:

1176

1177* **닫혀 있는 경우**: Claude Desktop은 시작할 때 부트스트랩 응답을 가져오므로, 변경 사항은 다음 시작부터 적용됩니다

1178* **열려 있는 경우**: Claude Desktop은 기본적으로 10분마다 응답이 변경되었는지 확인하며, 일부 설정은 재시작 없이 적용합니다. [`skillCreationEnabled`](https://claude.com/docs/third-party/claude-desktop/configuration#skillcreationenabled)와 같은 나머지 설정의 경우, 사용자는 사이드바에서 **Relaunch Claude Desktop** 카드를 보게 되며 앱을 재시작할 때까지 이전 구성을 유지합니다. 기본적으로 24시간이 지나면 Claude Desktop은 재시작 대화 상자를 표시하고, 2분 동안 활동이 없으면 스스로 재시작합니다

1179

118024시간을 단축하려면 정책의 `desktop` 블록에서 [`relaunchEnforcementHours`](https://claude.com/docs/third-party/claude-desktop/configuration#relaunchenforcementhours)를 설정합니다. 게이트웨이 서버에 Claude Code v2.1.260 이상이, 구성원 머신에 Claude Desktop 1.40609.0 이상이 필요합니다. `0`으로 설정하면 Claude Desktop이 변경을 발견하는 즉시 대화 상자가 나타납니다.

1140 1181

1141<h4 id="extended-context-in-claude-desktop">1182<h4 id="extended-context-in-claude-desktop">

1142 Claude Desktop의 확장 컨텍스트1183 Claude Desktop의 확장 컨텍스트

claude-apps-gateway-deploy.md +7 −3

Details

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

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

223 223

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

~~225~~

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

227 225

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

251 Postgres249 Postgres

252</h3>250</h3>

253 251

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

253

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

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

256

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

255 258

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

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

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

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

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

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

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

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

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

claude-apps-gateway-on-aws.md +20 −13

Details

169 </Step>169 </Step>

170 170

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

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

173 173

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

175 175

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

202 ```202 ```

203 203

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

205 205

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

207 207

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

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

222 222

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

224 224

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

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

227 227

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

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

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

246 userinfo_fallback: true246 userinfo_fallback: true

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

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

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

249 250

250 session:251 session:

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

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

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

253 255

254 store:256 store:

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

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

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

257 260

258 upstreams:261 upstreams:

259 - provider: bedrock262 - provider: bedrock

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

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

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

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

262 ```267 ```

263 268

264 <Note>269 <Note>

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

308 ```313 ```

309 314

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

311 316

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

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

396 401

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

398 403

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

400 405

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

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

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

421 ```426 ```

422 427

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

429

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

424 431

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

426 433

471 </Step>478 </Step>

472 479

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

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

475 </Step>482 </Step>

476</Steps>483</Steps>

477 484

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

Details

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

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

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

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

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

421 421

422<h2 id="troubleshooting">422<h2 id="troubleshooting">

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

443 443

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

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

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

447 447

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

449

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

449 451

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

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

claude-directory.md +10 −12

Details

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

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

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

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

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

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

40 40

164 icon: 'folder',164 icon: 'folder',

165 color: '#9B7BC4',165 color: '#9B7BC4',

166 oneLiner: 'Topic-scoped instructions, optionally gated by file paths',166 oneLiner: 'Topic-scoped instructions, optionally gated by file paths',

167 when: <>Rules without <C>paths:</C> load at session start. Rules with <C>paths:</C> load when a matching file enters context</>,167 when: <>Rules without <C>paths:</C> load at session start. Rules with <C>paths:</C> load when Claude reads, writes, or edits a matching file</>,

168 description: [<>Project instructions split into topic files that can load conditionally based on file paths. A rule without <C>paths:</C> frontmatter loads at session start like CLAUDE.md; a rule with <C>paths:</C> loads only when Claude reads, writes, or edits a matching file.</>, <>Like CLAUDE.md, rules are guidance Claude reads, not configuration Claude Code enforces. For guaranteed behavior use <A href="/docs/en/hooks">hooks</A> or <A href="/docs/en/permissions">permissions</A>.</>],168 description: [<>Project instructions split into topic files that can load conditionally based on file paths. A rule without <C>paths:</C> frontmatter loads at session start like CLAUDE.md; a rule with <C>paths:</C> loads only when Claude reads, writes, or edits a matching file.</>, <>Like CLAUDE.md, rules are guidance Claude reads, not configuration Claude Code enforces. For guaranteed behavior use <A href="/docs/en/hooks">hooks</A> or <A href="/docs/en/permissions">permissions</A>.</>],

169 tips: [<>Use <C>paths:</C> frontmatter with globs to scope rules to directories or file types</>, <>Subdirectories work: <C>.claude/rules/frontend/react.md</C> is discovered automatically</>, 'When CLAUDE.md approaches 200 lines, start splitting into rules'],169 tips: [<>Use <C>paths:</C> frontmatter with globs to scope rules to directories or file types</>, <>Subdirectories work: <C>.claude/rules/frontend/react.md</C> is discovered automatically</>, 'When CLAUDE.md approaches 200 lines, start splitting into rules'],

170 docsLink: '/en/memory#organize-rules-with-claude/rules/',170 docsLink: '/en/memory#organize-rules-with-claude/rules/',

176 color: '#9B7BC4',176 color: '#9B7BC4',

177 badge: 'committed',177 badge: 'committed',

178 oneLiner: 'Test conventions scoped to test files',178 oneLiner: 'Test conventions scoped to test files',

179 when: <>Loaded when Claude reads a file matching the <C>paths:</C> globs below</>,179 when: <>Loaded when Claude reads, writes, or edits a file matching the <C>paths:</C> globs below</>,

180 description: <>An example rule that only loads when Claude is working on test files. The <C>paths:</C> globs in the frontmatter define which files trigger it; here, anything ending in .test.ts or .test.tsx. For other files, this rule is not loaded into context.</>,180 description: <>An example rule that only loads when Claude is working on test files. The <C>paths:</C> globs in the frontmatter define which files trigger it; here, anything ending in .test.ts or .test.tsx. For other files, this rule is not loaded into context.</>,

181 example: `---181 example: `---

182paths:182paths:

197 color: '#9B7BC4',197 color: '#9B7BC4',

198 badge: 'committed',198 badge: 'committed',

199 oneLiner: 'API conventions scoped to backend code',199 oneLiner: 'API conventions scoped to backend code',

200 when: <>Loaded when Claude reads a file matching the <C>paths:</C> glob below</>,200 when: <>Loaded when Claude reads, writes, or edits a file matching the <C>paths:</C> glob below</>,

201 description: <>A second example showing a rule scoped to backend code. The <C>paths:</C> glob matches files under src/api/, so these conventions load only when Claude is editing API routes.</>,201 description: <>A second example showing a rule scoped to backend code. The <C>paths:</C> glob matches files under src/api/, so these conventions load only when Claude is working on API routes.</>,

202 example: `---202 example: `---

203paths:203paths:

204 - "src/api/**/*.ts"204 - "src/api/**/*.ts"

605 icon: 'folder',605 icon: 'folder',

606 color: '#9B7BC4',606 color: '#9B7BC4',

607 oneLiner: 'User-level rules that apply to every project',607 oneLiner: 'User-level rules that apply to every project',

608 when: <>Rules without <C>paths:</C> load at session start. Rules with <C>paths:</C> load when a matching file enters context</>,608 when: <>Rules without <C>paths:</C> load at session start. Rules with <C>paths:</C> load when Claude reads, writes, or edits a matching file</>,

609 description: 'Same as project .claude/rules/ but applies everywhere. Use this for conventions you want across all your work, like personal code style or commit message format.',609 description: 'Same as project .claude/rules/ but applies everywhere. Use this for conventions you want across all your work, like personal code style or commit message format.',

610 docsLink: '/en/memory#organize-rules-with-claude/rules/',610 docsLink: '/en/memory#organize-rules-with-claude/rules/',

611 children: []611 children: []

1434 1434

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

1436 1436

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

1438 1438

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

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

1452 1452

1453| 파일 | 위치 | 목적 |1453| 파일 | 위치 | 목적 |

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

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

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

1459 1459

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

1487<Note>1487<Note>

1488 이 파일에 입력한 내용을 재정의할 수 있는 여러 가지가 있습니다.1488 이 파일에 입력한 내용을 재정의할 수 있는 여러 가지가 있습니다.

1489 1489

1490 * 조직에서 배포한 [관리 설정](/docs/ko/server-managed-settings)이 모든 것보다 우선합니다. [설정 우선순위의 예외](/docs/ko/settings#exceptions-to-managed-settings-precedence) 제외1490 * 조직에서 배포한 [관리형 설정](/docs/ko/server-managed-settings)은 [설정 우선순위의 예외](/docs/ko/settings#exceptions-to-managed-settings-precedence)를 제외하고 모든 설정 파일과 `--settings` 값보다 우선합니다.

1491 * `--permission-mode` 또는 `--settings`와 같은 CLI 플래그는 해당 세션에 대해 `settings.json`을 재정의합니다.1491 * `--permission-mode` 또는 `--settings`와 같은 CLI 플래그는 해당 세션에 대해 `settings.json`을 재정의합니다.

1492 * 일부 환경 변수는 동등한 설정보다 우선하지만, 이는 다양합니다. 각각에 대해 [환경 변수 참조](/docs/ko/env-vars)를 확인하세요.1492 * 일부 환경 변수는 동등한 설정보다 우선하지만, 이는 다양합니다. 각각에 대해 [환경 변수 참조](/docs/ko/env-vars)를 확인하세요.

1493 1493

1708 1708

1709경로 대신 `--all`을 전달하여 한 번에 모든 프로젝트의 상태를 purge합니다. 이는 `history.jsonl`을 필터링하는 대신 완전히 삭제합니다. `-i`를 전달하여 삭제 계획을 한 번에 하나씩 단계별로 진행합니다.1709경로 대신 `--all`을 전달하여 한 번에 모든 프로젝트의 상태를 purge합니다. 이는 `history.jsonl`을 필터링하는 대신 완전히 삭제합니다. `-i`를 전달하여 삭제 계획을 한 번에 하나씩 단계별로 진행합니다.

1710 1710

1711스크립트에서는 종료 상태만 보지 말고 출력을 확인하세요. 계획의 모든 항목을 삭제한 실행은 `Purged N item(s)`로 끝납니다. 이 줄을 성공의 표시로 간주하세요.

~~1712~~

1713명령은 `shell-snapshots/` 및 `backups/`를 그대로 두는데, 이는 프로젝트 범위가 아니기 때문이며 계획 출력에서 이에 대해 경고합니다. 누군가 해당 머신에서 [`/heapdump`](/docs/ko/troubleshooting#high-cpu-or-memory-usage)를 실행했다면 그것이 작성한 `.heapsnapshot` 파일도 삭제하세요. 힙 스냅샷에는 전체 대화와 프로세스가 보유했던 모든 자격 증명이 포함되며, 보존 스윕과 purge 모두 이를 건드리지 않습니다.1711명령은 `shell-snapshots/` 및 `backups/`를 그대로 두는데, 이는 프로젝트 범위가 아니기 때문이며 계획 출력에서 이에 대해 경고합니다. 누군가 해당 머신에서 [`/heapdump`](/docs/ko/troubleshooting#high-cpu-or-memory-usage)를 실행했다면 그것이 작성한 `.heapsnapshot` 파일도 삭제하세요. 힙 스냅샷에는 전체 대화와 프로세스가 보유했던 모든 자격 증명이 포함되며, 보존 스윕과 purge 모두 이를 건드리지 않습니다.

1714 1712

1715위의 [애플리케이션 데이터 경로](#state-files-to-keep)를 제외한 모든 경로를 직접 삭제할 수도 있습니다. 새 세션은 영향을 받지 않습니다. 아래 표는 과거 세션에서 손실되는 것을 보여줍니다.1713위의 [애플리케이션 데이터 경로](#state-files-to-keep)를 제외한 모든 경로를 직접 삭제할 수도 있습니다. 새 세션은 영향을 받지 않습니다. 아래 표는 과거 세션에서 손실되는 것을 보여줍니다.

claude-projects.md +5 −5

Details

60 * 프로젝트의 저장소와 파일, 그리고 [지침과 메모리](#give-a-project-standing-context)60 * 프로젝트의 저장소와 파일, 그리고 [지침과 메모리](#give-a-project-standing-context)

61 * [프로젝트의 각 저장소](#what-threads-pick-up-from-your-repositories)의 `CLAUDE.md`와 스킬, 그리고 하나의 저장소를 가진 프로젝트에서는 그 저장소의 권한 규칙과 훅도 포함61 * [프로젝트의 각 저장소](#what-threads-pick-up-from-your-repositories)의 `CLAUDE.md`와 스킬, 그리고 하나의 저장소를 가진 프로젝트에서는 그 저장소의 권한 규칙과 훅도 포함

62 * claude.ai 계정의 [커넥터](#get-skills-plugins-connectors-and-tools-into-threads)62 * claude.ai 계정의 [커넥터](#get-skills-plugins-connectors-and-tools-into-threads)

~~63 * 네트워크 액세스, 환경 변수, API 자격 증명, 설치된 도구를 설정하는 [클라우드 환경](#choose-an-environment-for-threads)~~63 * 네트워크 액세스, 환경 변수, 네트워크 시크릿, 설치된 도구를 설정하는 [클라우드 환경](#choose-an-environment-for-threads)

64* **개요 창**: [모든 스레드를 한 번에 보고](#see-what-needs-you-in-overview) 어느 것이 사용자를 필요로 하는지 보는 곳입니다. 다른 탭은 추가한 파일과 스레드가 생성한 파일을 위한 **라이브러리**, 스레드가 열은 풀 리퀘스트를 위한 **풀 리퀘스트**, 프로젝트의 예약된 작업을 위한 **루틴**입니다.64* **개요 창**: [모든 스레드를 한 번에 보고](#see-what-needs-you-in-overview) 어느 것이 사용자를 필요로 하는지 보는 곳입니다. 다른 탭은 추가한 파일과 스레드가 생성한 파일을 위한 **라이브러리**, 스레드가 열은 풀 리퀘스트를 위한 **풀 리퀘스트**, 프로젝트의 예약된 작업을 위한 **루틴**입니다.

65 65

66클라우드 스레드는 자신의 머신에 있는 Claude Code 설정에서 아무것도 선택하지 않습니다. [스레드에 스킬, 플러그인, 커넥터, 도구 가져오기](#get-skills-plugins-connectors-and-tools-into-threads)는 그들이 다른 방법으로 누락될 것들을 어떻게 제공하는지 다룹니다.66클라우드 스레드는 자신의 머신에 있는 Claude Code 설정에서 아무것도 선택하지 않습니다. [스레드에 스킬, 플러그인, 커넥터, 도구 가져오기](#get-skills-plugins-connectors-and-tools-into-threads)는 그들이 다른 방법으로 누락될 것들을 어떻게 제공하는지 다룹니다.

92 92

93* **플랜**: Pro 또는 Max를 사용 중이며 사이드바에 **프로젝트**가 표시됩니다.93* **플랜**: Pro 또는 Max를 사용 중이며 사이드바에 **프로젝트**가 표시됩니다.

94* **GitHub(프로젝트가 코드에서 작업할 경우)**: 코드가 GitHub Enterprise Server, GitLab 또는 Bitbucket이 아닌 github.com에 있고, 연결된 GitHub 계정이 코드에 대한 푸시 액세스 권한을 가지고 있으며, Claude GitHub App이 설치되어 있습니다. [`/web-setup`](/docs/ko/web-quickstart#connect-from-your-terminal)으로 GitHub를 연결한 경우, 해당 토큰을 사용하면 다른 클라우드 세션이 리포지토리에 도달할 수 있지만 Claude GitHub App이 필요한 프로젝트의 클라우드 스레드에는 충분하지 않습니다. [GitHub 액세스 설정하기](#set-up-github-access)에 단계가 나와 있습니다.94* **GitHub(프로젝트가 코드에서 작업할 경우)**: 코드가 GitHub Enterprise Server, GitLab 또는 Bitbucket이 아닌 github.com에 있고, 연결된 GitHub 계정이 코드에 대한 푸시 액세스 권한을 가지고 있으며, Claude GitHub App이 설치되어 있습니다. [`/web-setup`](/docs/ko/web-quickstart#connect-from-your-terminal)으로 GitHub를 연결한 경우, 해당 토큰을 사용하면 다른 클라우드 세션이 리포지토리에 도달할 수 있지만 Claude GitHub App이 필요한 프로젝트의 클라우드 스레드에는 충분하지 않습니다. [GitHub 액세스 설정하기](#set-up-github-access)에 단계가 나와 있습니다.

95* **네트워크, 자격 증명 및 도구**: 클라우드 스레드의 경우, 이들은 프로젝트의 [클라우드 환경](#choose-an-environment-for-threads)에서 제공됩니다. 기본 환경은 이미 [일반적인 패키지 레지스트리](/docs/ko/cloud-environments#default-allowed-domains)에 도달하므로, 작업이 다른 도메인, 시크릿 또는 사전 설치되지 않은 도구가 필요한 경우에만 확인하세요. 작업이 MCP 서버가 필요한 경우, [claude.ai 커넥터](https://claude.ai/customize/connectors)에서 연결된 것으로 표시되는지 확인하세요.95* **네트워크, 시크릿 및 도구**: 클라우드 스레드의 경우, 이들은 프로젝트의 [클라우드 환경](#choose-an-environment-for-threads)에서 제공됩니다. 기본 환경은 이미 [일반적인 패키지 레지스트리](/docs/ko/cloud-environments#default-allowed-domains)에 도달하므로, 작업이 다른 도메인, 시크릿 또는 사전 설치되지 않은 도구가 필요한 경우에만 확인하세요. 작업이 MCP 서버가 필요한 경우, [claude.ai 커넥터](https://claude.ai/customize/connectors)에서 연결된 것으로 표시되는지 확인하세요.

96 96

97<h3 id="start-a-new-project-from-scratch">97<h3 id="start-a-new-project-from-scratch">

98 처음부터 새 프로젝트 시작하기98 처음부터 새 프로젝트 시작하기

396 스레드의 환경 선택하기396 스레드의 환경 선택하기

397</h3>397</h3>

398 398

399모든 새로운 클라우드 스레드는 프로젝트의 [클라우드 환경](/docs/ko/cloud-environments)에서 시작합니다. 환경은 스레드가 도달할 수 있는 도메인, 스레드가 가진 환경 변수, 요청에 추가되는 API 자격증명, 그리고 Claude가 시작하기 전에 설정 스크립트가 설치하는 것을 설정합니다. 클라우드 스레드는 **프로젝트 설정 > 환경**에서 선택할 때까지 기본 Anthropic 호스팅 환경을 사용합니다.399모든 새로운 클라우드 스레드는 프로젝트의 [클라우드 환경](/docs/ko/cloud-environments)에서 시작합니다. 환경은 스레드가 도달할 수 있는 도메인, 스레드가 가진 환경 변수, 요청에 추가되는 네트워크 시크릿, 그리고 Claude가 시작하기 전에 설정 스크립트가 설치하는 것을 설정합니다. 클라우드 스레드는 **프로젝트 설정 > 환경**에서 선택할 때까지 기본 Anthropic 호스팅 환경을 사용합니다.

400 400

401클라우드 스레드가 내부 API 또는 프라이빗 패키지 레지스트리에 도달해야 하거나 머신이 일반적으로 보유한 토큰이 필요하면, 프로젝트가 아닌 환경을 변경하세요: [네트워크 액세스](/docs/ko/cloud-environments#network-access), [API 자격증명 추가](/docs/ko/cloud-environments#add-api-credentials), [설정 스크립트](/docs/ko/cloud-environments#setup-scripts)를 참조하세요.401클라우드 스레드가 내부 API 또는 프라이빗 패키지 레지스트리에 도달해야 하거나 머신이 일반적으로 보유한 토큰이 필요하면, 프로젝트가 아닌 환경을 변경하세요: [네트워크 액세스](/docs/ko/cloud-environments#network-access), [네트워크 시크릿 추가](/docs/ko/cloud-environments#add-api-credentials), [설정 스크립트](/docs/ko/cloud-environments#setup-scripts)를 참조하세요.

402 402

403<h3 id="get-skills-plugins-connectors-and-tools-into-threads">403<h3 id="get-skills-plugins-connectors-and-tools-into-threads">

404 스킬, 플러그인, 커넥터, 도구를 스레드에 가져오기404 스킬, 플러그인, 커넥터, 도구를 스레드에 가져오기

590</h2>590</h2>

591 591

592* [클라우드에서 Claude Code 사용](/docs/ko/claude-code-on-the-web): 각 클라우드 스레드 뒤의 클라우드 세션이 어떻게 작동하는지, GitHub 액세스 옵션 및 풀 요청의 자동 수정 포함592* [클라우드에서 Claude Code 사용](/docs/ko/claude-code-on-the-web): 각 클라우드 스레드 뒤의 클라우드 세션이 어떻게 작동하는지, GitHub 액세스 옵션 및 풀 요청의 자동 수정 포함

593* [클라우드 환경 구성](/docs/ko/cloud-environments): 클라우드 스레드가 네트워크에서 도달할 수 있는 것을 변경하고, 환경 변수 및 API 자격 증명을 제공하고, 설정 스크립트로 도구를 설치합니다593* [클라우드 환경 구성](/docs/ko/cloud-environments): 클라우드 스레드가 네트워크에서 도달할 수 있는 것을 변경하고, 환경 변수 및 네트워크 시크릿을 제공하고, 설정 스크립트로 도구를 설치합니다

594* [루틴으로 작업 자동화](/docs/ko/routines): 일정, 트리거 및 루틴 관리, 프로젝트에서 Claude가 생성하는 것 포함594* [루틴으로 작업 자동화](/docs/ko/routines): 일정, 트리거 및 루틴 관리, 프로젝트에서 Claude가 생성하는 것 포함

595* [에이전트 보기로 여러 에이전트 관리](/docs/ko/agent-view): 작업이 머신만 도달할 수 있는 도구 또는 서비스가 필요할 때 머신에서 여러 세션을 실행하고 추적합니다595* [에이전트 보기로 여러 에이전트 관리](/docs/ko/agent-view): 작업이 머신만 도달할 수 있는 도구 또는 서비스가 필요할 때 머신에서 여러 세션을 실행하고 추적합니다

596* [Projects redesigned: from folder to conversation](https://claude.com/blog/projects-redesigned): 출시 공지, 프로젝트를 Claude와의 대화로 만드는 생각 포함596* [Projects redesigned: from folder to conversation](https://claude.com/blog/projects-redesigned): 출시 공지, 프로젝트를 Claude와의 대화로 만드는 생각 포함

cli-reference.md +3 −1

Details

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

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

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

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

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

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

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

95| `--fallback-model` | 기본 모델이 과부하되거나 사용할 수 없을 때(예: 폐기된 모델) 지정된 모델로 자동 폴백을 활성화합니다. 순서대로 시도되는 쉼표로 구분된 목록을 허용합니다. [폴백 모델 체인](/docs/ko/model-config#fallback-model-chains)을 참조하세요. 세션 간에 체인을 유지하려면 이 플래그가 재정의하는 [`fallbackModel` 설정](/docs/ko/settings-reference#fallbackmodel)을 사용합니다 | `claude --fallback-model sonnet,haiku` |97| `--fallback-model` | 기본 모델이 과부하되거나 사용할 수 없을 때(예: 폐기된 모델) 지정된 모델로 자동 폴백을 활성화합니다. 순서대로 시도되는 쉼표로 구분된 목록을 허용합니다. [폴백 모델 체인](/docs/ko/model-config#fallback-model-chains)을 참조하세요. 세션 간에 체인을 유지하려면 이 플래그가 재정의하는 [`fallbackModel` 설정](/docs/ko/settings-reference#fallbackmodel)을 사용합니다 | `claude --fallback-model sonnet,haiku` |

97| `--forward-subagent-text` | [서브에이전트](/docs/ko/sub-agents) 텍스트 및 사고 블록을 `parent_tool_use_id` 설정된 `assistant` 및 `user` 메시지로 출력 스트림에 내보내므로 각 서브에이전트의 트랜스크립트를 재구성할 수 있습니다. 이 플래그 없이 Claude Code는 [포그라운드](/docs/ko/sub-agents#run-subagents-in-foreground-or-background)에서 실행되는 서브에이전트의 텍스트 및 사고 블록을 생략합니다. `--print` 및 `--output-format stream-json`이 필요합니다. Claude Code는 또한 [중첩된 서브에이전트](/docs/ko/sub-agents#let-subagents-spawn-their-own-subagents)의 메시지를 전달하며, 각 메시지를 생성한 Agent 또는 Skill 도구 호출의 ID로 `parent_tool_use_id`를 설정합니다. 이는 Claude Code v2.1.219 이상이 필요합니다. 포크된 스킬이 생성한 서브에이전트의 메시지와 중첩된 포크된 스킬의 메시지는 v2.1.275 이상이 필요합니다. [`CLAUDE_CODE_FORWARD_SUBAGENT_TEXT`](/docs/ko/env-vars) 환경 변수는 동일한 동작을 활성화합니다. Claude Code v2.1.211 이상이 필요합니다 | `claude -p --output-format stream-json --verbose --forward-subagent-text "query"` |99| `--forward-subagent-text` | [서브에이전트](/docs/ko/sub-agents) 텍스트 및 사고 블록을 `parent_tool_use_id` 설정된 `assistant` 및 `user` 메시지로 출력 스트림에 내보내므로 각 서브에이전트의 트랜스크립트를 재구성할 수 있습니다. 이 플래그 없이 Claude Code는 [포그라운드](/docs/ko/sub-agents#run-subagents-in-foreground-or-background)에서 실행되는 서브에이전트의 텍스트 및 사고 블록을 생략합니다. `--print` 및 `--output-format stream-json`이 필요합니다. 중첩된 서브에이전트, 포크된 스킬 및 각각에 필요한 버전은 [서브에이전트 메시지 따라가기](/docs/ko/headless#follow-subagent-messages)를 참조하세요. [`CLAUDE_CODE_FORWARD_SUBAGENT_TEXT`](/docs/ko/env-vars) 환경 변수는 동일한 동작을 활성화합니다. Claude Code v2.1.211 이상이 필요합니다 | `claude -p --output-format stream-json --verbose --forward-subagent-text "query"` |

98| `--from-pr` | 특정 풀 요청에 연결된 세션으로 필터링된 세션 선택기를 엽니다. PR 번호, GitHub 또는 GitHub Enterprise PR URL, GitLab 병합 요청 URL 또는 Bitbucket 풀 요청 URL을 허용합니다. Claude가 풀 요청을 만들 때 세션이 자동으로 연결됩니다 | `claude --from-pr 123` |100| `--from-pr` | 특정 풀 요청에 연결된 세션으로 필터링된 세션 선택기를 엽니다. PR 번호, GitHub 또는 GitHub Enterprise PR URL, GitLab 병합 요청 URL 또는 Bitbucket 풀 요청 URL을 허용합니다. Claude가 풀 요청을 만들 때 세션이 자동으로 연결됩니다 | `claude --from-pr 123` |

99| `--ide` | 정확히 하나의 유효한 IDE를 사용할 수 있는 경우 시작 시 IDE에 자동으로 연결합니다 | `claude --ide` |101| `--ide` | 정확히 하나의 유효한 IDE를 사용할 수 있는 경우 시작 시 IDE에 자동으로 연결합니다 | `claude --ide` |

cloud-environments.md +79 −63

Details

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

11</Note>11</Note>

12 12

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

14 14

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

16 16

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

59 **Cloud**를 선택하여 환경을 나열합니다. 그런 다음 **Add cloud environment**를 선택하거나, 기존 환경 위에 마우스를 올리고 오른쪽에 나타나는 설정 아이콘을 선택합니다.59 **Cloud**를 선택하여 환경을 나열합니다. 그런 다음 **Add cloud environment**를 선택하거나, 기존 환경 위에 마우스를 올리고 오른쪽에 나타나는 설정 아이콘을 선택합니다.

60 60

61 대화 상자에는 이름, 네트워크 액세스 수준, 환경 변수 및 설정 스크립트가 포함됩니다. Pro 또는 Max 플랜에서 기존 클라우드 환경을 편집할 때 대화 상자에는 [API 자격 증명](#add-api-credentials)도 포함됩니다.61 대화 상자에는 이름, 네트워크 액세스 수준, 환경 변수 및 설정 스크립트가 포함됩니다. Pro 또는 Max 플랜에서 기존 클라우드 환경을 편집할 때 대화 상자에는 [네트워크 시크릿](#add-api-credentials)도 포함됩니다.

62 62

63 <Frame>63 <Frame>

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

91 91

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

93 93

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

95 95

96<h3 id="add-api-credentials">96<h3 id="add-api-credentials">

~~97 API 자격 증명 추가~~97 네트워크 시크릿 추가

98</h3>98</h3>

99 99

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

101 101

102API 자격 증명은 Pro 및 Max 플랜에서 사용 가능합니다. Team 또는 Enterprise 플랜에서는 아직 사용할 수 없으므로 **API credentials** 섹션이 해당 플랜의 환경 대화 상자에 나타나지 않습니다.102네트워크 시크릿은 Pro 및 Max 플랜에서 사용 가능합니다. Team 또는 Enterprise 플랜에서는 아직 사용할 수 없으므로 **Network secrets** 섹션이 해당 플랜의 환경 대화 상자에 나타나지 않습니다.

103 103

104<h4 id="requirements">104<h4 id="requirements">

105 요구 사항105 요구 사항

106</h4>106</h4>

107 107

108이 중 두 개는 자격 증명을 추가할 수 있는지 여부를 결정하고, 두 개는 추가된 후 에이전트 프록시가 사용할 수 있는지 여부를 결정합니다.108다음 요구 사항에 따라 시크릿을 추가할 수 있는지, 그리고 추가된 후 에이전트 프록시가 이를 사용할 수 있는지가 결정됩니다.

109 109

110* **Role**: claude.ai 조직의 조직 관리자 역할110* **Role**: claude.ai 조직의 조직 관리자 역할

111 * Team 및 Enterprise에서는 Owner가 보유하고 Admin은 보유하지 않습니다.111 * Team 및 Enterprise에서는 Owner가 보유하고 Admin은 보유하지 않습니다.

112 * Pro 및 Max에서는 자신의 조직에서 보유합니다.112 * Pro 및 Max에서는 자신의 조직에서 보유합니다.

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

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

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

116 116

117<h4 id="add-a-credential">117<h4 id="add-a-credential">

118 자격 증명 추가118 시크릿 추가

119</h4>119</h4>

120 120

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

122 122

123<Steps>123<Steps>

124 <Step title="환경의 API 자격 증명 열기">124 <Step title="환경의 네트워크 시크릿 열기">

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

126 </Step>126 </Step>

127 127

128 <Step title="자격 증명 추가">128 <Step title="시크릿 추가">

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

130 130

131 * **Name**: `Internal billing API`와 같은 자격 증명의 레이블131 * **Name**: `Internal billing API`와 같은 시크릿의 레이블

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

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

134 134

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

136 </Step>136 </Step>

137 137

138 <Step title="자격 증명 저장">138 <Step title="시크릿 저장">

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

140 </Step>140 </Step>

141</Steps>141</Steps>

142 142

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

144 144

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

146 자격 증명을 받는 요청146 시크릿을 받는 요청

147</h4>147</h4>

148 148

149에이전트 프록시는 요청의 호스트가 해당 자격 증명에 나열한 호스트 중 하나와 일치할 때 자격 증명을 요청에 첨부합니다. 세션은 환경의 [네트워크 액세스 수준](#access-levels)이 그렇지 않으면 허용하지 않을 때에도 해당 호스트에 도달할 수 있습니다. 단, [자격 증명을 받지 않는 호스트](#requests-that-never-get-the-credential)는 제외됩니다. 자격 증명은 삭제할 때까지 환경에서 실행되는 모든 세션에 적용되며, 누가 시작했는지는 상관없습니다.149에이전트 프록시는 요청의 호스트가 해당 시크릿에 나열한 호스트 중 하나와 일치할 때 시크릿을 요청에 첨부합니다. 세션은 환경의 [네트워크 액세스 수준](#access-levels)이 그렇지 않으면 허용하지 않을 때에도 해당 호스트에 도달할 수 있습니다. 단, [시크릿을 받지 않는 호스트](#requests-that-never-get-the-credential)는 제외됩니다. 시크릿은 삭제할 때까지 환경에서 실행되는 모든 세션에 적용되며, 누가 시작했는지는 상관없습니다.

150 150

151<h4 id="requests-that-never-get-the-credential">151<h4 id="requests-that-never-get-the-credential">

152 자격 증명을 받지 않는 요청152 시크릿을 받지 않는 요청

153</h4>153</h4>

154 154

155에이전트 프록시는 다음 요청에 추가한 자격 증명을 첨부하지 않습니다.155에이전트 프록시는 다음 요청에 추가한 시크릿을 첨부하지 않습니다.

156 156

157* **GitHub**: [GitHub 프록시](#github-proxy)가 대신 GitHub에 대한 요청을 인증하므로 GitHub에 대한 API 자격 증명이 필요하지 않습니다.157* **GitHub**: [GitHub 프록시](#github-proxy)가 대신 GitHub에 대한 요청을 인증하므로 GitHub에 대한 네트워크 시크릿이 필요하지 않습니다.

158* **Anthropic API 및 공개 패키지 레지스트리**: `api.anthropic.com`, `registry.npmjs.org`, `jsr.io`, `npm.jsr.io`, `pypi.org`, `files.pythonhosted.org`, `index.crates.io`, 및 `proxy.golang.org`158* **Anthropic API 및 공개 패키지 레지스트리**: `api.anthropic.com`, `registry.npmjs.org`, `jsr.io`, `npm.jsr.io`, `pypi.org`, `files.pythonhosted.org`, `index.crates.io`, 및 `proxy.golang.org`

159* **Setup script 요청**: Claude Code는 [설정 스크립트](#setup-scripts)가 실행된 후 시작할 때 에이전트 프록시에 연결합니다.159* **Setup script 요청**: Claude Code는 [설정 스크립트](#setup-scripts)가 실행된 후 시작할 때 에이전트 프록시에 연결합니다.

160* **Claude Code의 텔레메트리 내보내기**: Claude Code는 자신의 [텔레메트리 내보내기](/docs/ko/monitoring-usage#telemetry-from-cloud-sessions-and-claude-tag)를 실행하는 명령이 아닌 자체적으로 보내며, 해당 요청은 에이전트 프록시를 통과하지 않습니다.160* **Claude Code의 텔레메트리 내보내기**: Claude Code는 자신의 [텔레메트리 내보내기](/docs/ko/monitoring-usage#telemetry-from-cloud-sessions-and-claude-tag)를 실행하는 명령이 아닌 자체적으로 보내며, 해당 요청은 에이전트 프록시를 통과하지 않습니다.

179 179

180* 환경에서 이미 실행 중인 세션은 계속 작동합니다.180* 환경에서 이미 실행 중인 세션은 계속 작동합니다.

181* 환경이 선택기 및 `/remote-env`에서 사라지므로 새 세션에 대해 선택할 수 없습니다.181* 환경이 선택기 및 `/remote-env`에서 사라지므로 새 세션에 대해 선택할 수 없습니다.

182* 환경의 API 자격 증명은 실행 중인 세션에 첨부된 상태로 유지됩니다. 보관하기 전에 더 이상 원하지 않는 항목을 삭제합니다.182* 환경의 네트워크 시크릿은 실행 중인 세션에 첨부된 상태로 유지됩니다. 보관하기 전에 더 이상 원하지 않는 항목을 삭제합니다.

183* 보관된 환경에서는 어떤 표면에서도 새 세션을 시작할 수 없습니다. 환경이 저장된 [CLI 기본값](#select-an-environment-from-the-cli)이었다면, 목록에 Anthropic 호스팅 환경이 있을 때 Claude Code는 CLI 클라우드 세션을 해당 환경에서 시작하고, 그렇지 않으면 [Remote Control 브리지 환경](#the-default-environment)이 아닌 목록의 첫 번째 환경에서 시작합니다. [루틴](/docs/ko/routines#environments-and-network-access)과 같이 환경으로 명시적으로 구성된 모든 항목은 새 세션을 시작할 수 없습니다. 다른 환경을 가리키도록 합니다.183* 보관된 환경에서는 어떤 표면에서도 새 세션을 시작할 수 없습니다. 환경이 저장된 [CLI 기본값](#select-an-environment-from-the-cli)이었다면, 목록에 Anthropic 호스팅 환경이 있을 때 Claude Code는 CLI 클라우드 세션을 해당 환경에서 시작하고, 그렇지 않으면 [Remote Control 브리지 환경](#the-default-environment)이 아닌 목록의 첫 번째 환경에서 시작합니다. [루틴](/docs/ko/routines#environments-and-network-access)과 같이 환경으로 명시적으로 구성된 모든 항목은 새 세션을 시작할 수 없습니다. 다른 환경을 가리키도록 합니다.

184 184

185<h3 id="organization-shared-environments">185<h3 id="organization-shared-environments">

197 197

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

199 199

200모든 구성원의 공유 환경의 세션은 해당 변수를 읽으므로 비밀을 포함하지 마십시오. [자격 증명을 읽을 수 없는 세션을 제공하는 API 자격 증명](#add-api-credentials)은 Team 또는 Enterprise 플랜에서 아직 사용할 수 없습니다.200모든 구성원의 공유 환경 세션은 해당 변수를 읽으므로 비밀 정보를 포함하지 마십시오. 세션에 읽을 수 없는 키를 제공하는 [네트워크 시크릿](#add-api-credentials)은 Team 또는 Enterprise 플랜에서 아직 사용할 수 없습니다.

201 201

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

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

239 239

240* GitHub([별도의 프록시](#github-proxy)를 통해)240* GitHub([별도의 프록시](#github-proxy)를 통해)

241* 활성화한 [MCP 커넥터](#network-access)(트래픽이 Anthropic의 서버를 통해 이동)241* 활성화한 [MCP 커넥터](#network-access)(트래픽이 Anthropic의 서버를 통해 이동)

242* 환경의 [API 자격 증명](#add-api-credentials)에 나열한 호스트([에이전트 프록시가 건너뛰는 호스트](#requests-that-never-get-the-credential) 제외)242* 환경의 [네트워크 시크릿](#add-api-credentials)에 나열한 호스트([시크릿을 받지 않는 호스트](#requests-that-never-get-the-credential) 제외)

243* Anthropic API(Claude Code의 자체 요청의 경우, [보안 및 격리](/docs/ko/claude-code-on-the-web#security-and-isolation) 아래에 언급된 대로 **None**에서도)243* Anthropic API(Claude Code의 자체 요청의 경우, [보안 및 격리](/docs/ko/claude-code-on-the-web#security-and-isolation) 아래에 언급된 대로 **None**에서도)

244 244

245<h3 id="allow-specific-domains">245<h3 id="allow-specific-domains">

254registry.example.com254registry.example.com

255```255```

256 256

257이 환경의 세션은 이제 `api.example.com`, `internal.example.com`의 모든 하위 도메인 및 `registry.example.com`에 도달할 수 있으며 세션의 네트워크를 통해 다른 도메인에는 도달할 수 없습니다. [GitHub 트래픽](#github-proxy), [MCP 커넥터 트래픽](#network-access) 및 환경의 [API 자격 증명](#add-api-credentials)의 호스트에 대한 요청([에이전트 프록시가 건너뛰는 호스트](#requests-that-never-get-the-credential) 제외)은 이 허용 목록을 통과하지 않습니다. 선행 `*.`은 모든 하위 도메인과 일치합니다. [Trusted 도메인](#default-allowed-domains)도 유지하려면 **Also include default list of common package managers**를 확인합니다. 나열한 것만 허용하려면 선택 해제합니다.257이 환경의 세션은 이제 `api.example.com`, `internal.example.com`의 모든 하위 도메인 및 `registry.example.com`에 도달할 수 있으며 세션의 네트워크를 통해 다른 도메인에는 도달할 수 없습니다. [GitHub 트래픽](#github-proxy), [MCP 커넥터 트래픽](#network-access) 및 환경의 [네트워크 시크릿](#add-api-credentials)의 호스트에 대한 요청([시크릿을 받지 않는 호스트](#requests-that-never-get-the-credential) 제외)은 이 허용 목록을 통과하지 않습니다. 선행 `*.`은 모든 하위 도메인과 일치합니다. [Trusted 도메인](#default-allowed-domains)도 유지하려면 **Also include default list of common package managers**를 확인합니다. 나열한 것만 허용하려면 선택 해제합니다.

258 258

259조직이 [아티팩트](/docs/ko/artifacts#availability)를 사용하는 경우 세션이 이를 읽기 위해 목록에 `*.frame.claudeusercontent.com`이 필요하지 않습니다. 목록이 해당 호스트를 생략하면 Claude Code는 세션의 Anthropic 연결을 통해 아티팩트 콘텐츠를 읽습니다. 두 가지 상황에서 호스트를 허용 목록에 유지합니다:259조직이 [아티팩트](/docs/ko/artifacts#availability)를 사용하는 경우 세션이 이를 읽기 위해 목록에 `*.frame.claudeusercontent.com`이 필요하지 않습니다. 목록이 해당 호스트를 생략하면 Claude Code는 세션의 Anthropic 연결을 통해 아티팩트 콘텐츠를 읽습니다. 두 가지 상황에서 호스트를 허용 목록에 유지합니다:

260 260

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

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

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

275* **리포지토리 범위**: GitHub API 및 릴리스 자산 요청은 세션에 연결된 리포지토리에만 도달하므로 연결되지 않은 리포지토리에서 릴리스 자산을 다운로드하는 설정 스크립트는 403을 받습니다.275* **저장소 범위**: 프록시는 세션에 연결된 저장소에 대한 GitHub API 요청을 처리합니다. 다른 저장소에 대한 API 요청은 `GitHub access to`로 시작하고 `is not enabled for this session`을 포함하는 메시지와 함께 403을 받습니다.

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

277 277

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

279 279

285 285

286* 악의적인 요청으로부터의 보호286* 악의적인 요청으로부터의 보호

287* 속도 제한 및 남용 방지287* 속도 제한 및 남용 방지

288* 향상된 보안을 위한 콘텐츠 필터링

289* 요청된 호스트 이름의 DNS 수준 감사 추적

290 288

291<h2 id="what’s-available-in-cloud-sessions">289<h2 id="what’s-available-in-cloud-sessions">

292 클라우드 세션에서 사용 가능한 항목290 클라우드 세션에서 사용 가능한 항목

293</h2>291</h2>

294 292

295Anthropic 호스팅 환경에서 각 세션은 자신의 운영 체제와 CPU 아키텍처에 관계없이 x86\_64에서 Ubuntu 24.04를 실행하는 새로운 가상 머신(VM)을 받으며, 리포지토리가 복제되고 일반적인 도구 체인이 사전 설치됩니다. 종속성이 사전 컴파일된 바이너리를 제공할 때(예: 네이티브 확장이 있는 Ruby gem 또는 사전 빌드된 Python 휠) x86\_64 Linux 빌드를 사용하여 VM과 일치합니다. 이 섹션은 Anthropic 호스팅 기본값, 기본 제공 GitHub 도구, [테스트 및 서비스 실행](#run-tests-start-services-and-add-packages) 방법, [리소스 제한](#resource-limits) 각 VM이 받는 항목, 그리고 [시간 제한](#time-limits) 장기 실행 작업에 대한 항목을 다룹니다.293Anthropic 호스팅 환경에서 각 세션은 자신의 운영 체제와 CPU 아키텍처에 관계없이 x86\_64에서 Ubuntu 24.04를 실행하는 새로운 가상 머신(VM)을 받으며, 저장소가 복제되고 일반적인 도구 체인이 사전 설치됩니다. 의존성이 사전 컴파일된 바이너리를 제공할 때(예: 네이티브 확장이 있는 Ruby gem 또는 사전 빌드된 Python 휠) VM과 일치하도록 x86\_64 Linux 빌드를 사용합니다. 이 섹션에서는 Anthropic 호스팅 기본값, 기본 제공 GitHub 도구, [테스트 및 서비스 실행](#run-tests-start-services-and-add-packages) 방법, 각 VM이 받는 [리소스 제한](#resource-limits), 그리고 장기 실행 작업에 대한 [시간 제한](#time-limits)을 다룹니다.

296 294

297<Note>295<Note>

298 조직이 [자체 호스팅 환경](/docs/ko/self-hosted-environments)으로 라우팅하는 세션은 자신의 러너에서 실행되며 러너 이미지가 제공하는 도구를 사용합니다.296 조직이 [자체 호스팅 환경](/docs/ko/self-hosted-environments)으로 라우팅하는 세션은 자신의 러너에서 실행되며 러너 이미지가 제공하는 도구를 사용합니다.

302 설정에서 전달되는 항목300 설정에서 전달되는 항목

303</h3>301</h3>

304 302

305클라우드 세션은 리포지토리의 새로운 복제본에서 시작됩니다. 리포지토리에 커밋한 모든 항목을 사용할 수 있습니다. 자신의 머신에만 설치하거나 구성한 항목은 세션에서 사용할 수 없습니다. 조직의 정책은 [서버 관리 설정](/docs/ko/server-managed-settings)을 통해 별도로 도착합니다.303클라우드 세션은 저장소의 새로운 복제본에서 시작됩니다. 저장소에 커밋한 모든 항목을 사용할 수 있습니다. 자신의 머신에만 설치하거나 구성한 항목은 세션에서 사용할 수 없습니다. 조직의 정책은 [서버 관리형 설정](/docs/ko/server-managed-settings)을 통해 별도로 도착합니다.

306 304

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

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

309| 리포지토리의 `CLAUDE.md` | 예 | 복제본의 일부 |307| 저장소의 `CLAUDE.md` | 예 | 복제본의 일부 |

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

312| 리포지토리의 `.claude/rules/` | 예 | 복제본의 일부 |310| 저장소의 `.claude/rules/` | 예 | 복제본의 일부 |

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

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

315| 조직의 [서버 관리 설정](/docs/ko/server-managed-settings) | 예, [Claude Tag](https://claude.com/docs/claude-tag/overview) 세션 제외 | 세션이 시작될 때 Anthropic의 서버에서 가져옵니다. 클라우드 세션에서 `availableModels`이 적용되는 방식은 [표면 범위](/docs/ko/model-config#surface-coverage)를 참조하세요. MDM 또는 관리 설정 파일을 통해 장치에 배포된 설정은 세션이 Anthropic 관리 VM에서 실행되기 때문에 적용되지 않습니다. [자체 호스팅 환경](/docs/ko/self-hosted-environments)에서 세션은 [Claude Code가 관리 소스를 결합하는 방식](/docs/ko/managed-settings#how-claude-code-combines-managed-sources)에 따라 러너 이미지의 관리 설정 파일도 읽습니다 |313| 조직의 [서버 관리형 설정](/docs/ko/server-managed-settings) | 예, [Claude Tag](https://claude.com/docs/claude-tag/overview) 세션 제외 | 세션이 시작될 때 Anthropic의 서버에서 가져옵니다. 클라우드 세션에서 `availableModels`이 적용되는 방식은 [사용 환경 범위](/docs/ko/model-config#surface-coverage)를 참조하세요. MDM 또는 관리형 설정 파일을 통해 장치에 배포된 설정은 세션이 Anthropic 관리 VM에서 실행되기 때문에 적용되지 않습니다. [자체 호스팅 환경](/docs/ko/self-hosted-environments)에서 세션은 [Claude Code가 관리형 소스를 결합하는 방식](/docs/ko/managed-settings#how-claude-code-combines-managed-sources)에 따라 러너 이미지의 관리형 설정 파일도 읽습니다 |

316| 사용자 `~/.claude/CLAUDE.md` | 아니오 | 리포지토리가 아닌 머신에 있습니다 |314| 사용자 `~/.claude/CLAUDE.md` | 아니오 | 저장소가 아닌 머신에 있습니다. [저장소에 커밋하지 않고 개인 기본 설정 추가](#add-personal-preferences-without-committing-to-the-repo)를 참조하세요 |

317| 사용자 `~/.claude/skills/`, `~/.claude/agents/`, `~/.claude/commands/` | 아니오 | 리포지토리가 아닌 머신에 있습니다. 대신 리포지토리의 `.claude/` 디렉토리에 커밋합니다. 클라우드 세션은 claude.ai에서 활성화한 기술을 자동으로 로드합니다 |315| 사용자 `~/.claude/skills/`, `~/.claude/agents/`, `~/.claude/commands/` | 아니오 | 저장소가 아닌 머신에 있습니다. 대신 저장소의 `.claude/` 디렉터리에 커밋합니다. 클라우드 세션은 claude.ai에서 활성화한 스킬을 자동으로 로드합니다 |

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

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

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

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

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

323 321

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

325 323

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

325

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

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

328</h4>

329

330Anthropic 호스팅 환경에서는 공유 저장소에 넣고 싶지 않은 기본 설정을 위해 `~/.claude/CLAUDE.md`를 작성하는 [설정 스크립트](#setup-scripts)를 추가합니다. Claude Code는 세션에서 해당 파일을 [사용자 지침](/docs/ko/memory#choose-where-to-put-claude-md-files)으로 로드합니다. 다음 예시는 커밋 메시지 기본 설정을 지정합니다:

331

332```bash theme={null}

333#!/bin/bash

334mkdir -p ~/.claude

335cat > ~/.claude/CLAUDE.md <<'EOF'

336Use conventional commit messages.

337EOF

338```

339

340스크립트는 [공유 환경](#organization-shared-environments)이 아닌 자신의 환경 중 하나에 추가합니다.

341

342다음 클라우드 세션에서 `/context`를 실행하고 **Memory files** 아래에 `/root/.claude/CLAUDE.md`가 표시되는지 확인합니다.

327 343

328<h3 id="installed-tools">344<h3 id="installed-tools">

329 설치된 도구345 설치된 도구

347 363

348¹ Bun이 설치되어 있지만 패키지 페칭에 대해 알려진 [프록시 호환성 문제](#install-dependencies-with-a-sessionstart-hook)가 있습니다.364¹ Bun이 설치되어 있지만 패키지 페칭에 대해 알려진 [프록시 호환성 문제](#install-dependencies-with-a-sessionstart-hook)가 있습니다.

349 365

350이 표의 대부분의 도구 버전을 얻으려면 Claude에게 클라우드 세션에서 `check-tools`를 실행하도록 요청합니다. 이는 슬래시 명령이 아닌 세션 VM에 설치된 셸 명령입니다. [Claude가 모든 VM 명령을 실행](#run-tests-start-services-and-add-packages)하기 때문에 요청합니다. 이를 보고하지 않는 도구(예: Ruby, PHP, bun, PostgreSQL 또는 Redis)의 경우 Claude에게 도구의 자체 버전 명령을 실행하도록 요청합니다(예: `psql --version`).366이 표의 대부분의 도구 버전을 얻으려면 Claude에게 클라우드 세션에서 `check-tools`를 실행하도록 요청합니다. 이는 `/`로 입력하는 명령이 아니라 세션 VM에 설치된 셸 명령입니다. [Claude가 모든 VM 명령을 실행](#run-tests-start-services-and-add-packages)하기 때문에 Claude에게 요청합니다. 이를 보고하지 않는 도구(예: Ruby, PHP, bun, PostgreSQL 또는 Redis)의 경우 Claude에게 도구의 자체 버전 명령을 실행하도록 요청합니다(예: `psql --version`).

351 367

352Node.js 버전은 `/opt/node20`, `/opt/node21` 및 `/opt/node22`에 설치되며, 기본적으로 22가 `PATH`에 있습니다. 다른 버전으로 작업하려면 Claude에게 해당 버전의 `bin` 디렉토리(예: `/opt/node20/bin`)를 `PATH`에 앞에 추가하도록 요청합니다.368Node.js 버전은 `/opt/node20`, `/opt/node21` 및 `/opt/node22`에 설치되며, 기본적으로 22가 `PATH`에 있습니다. 다른 버전으로 작업하려면 Claude에게 해당 버전의 `bin` 디렉터리(예: `/opt/node20/bin`)를 `PATH` 앞에 추가하도록 요청합니다.

353 369

354.NET SDK와 같은 이 목록 외의 도구 체인은 패키지 레지스트리가 [기본 허용 목록](#default-allowed-domains)에 있더라도 사전 설치되지 않습니다. [설정 스크립트](#setup-scripts)로 설치합니다.370.NET SDK와 같은 이 목록 외의 도구 체인은 패키지 레지스트리가 [기본 허용 목록](#default-allowed-domains)에 있더라도 사전 설치되지 않습니다. [설정 스크립트](#setup-scripts)로 설치합니다.

355 371

356<h3 id="work-with-github-issues-and-pull-requests">372<h3 id="work-with-github-issues-and-pull-requests">

357 GitHub 이슈 및 풀 요청 작업373 GitHub 이슈 및 풀 리퀘스트 작업

358</h3>374</h3>

359 375

360클라우드 세션에는 Claude가 이슈를 읽고, 풀 요청을 나열하고, 차이를 가져오고, 설정 없이 댓글을 게시할 수 있는 기본 제공 GitHub 도구가 포함됩니다. 이러한 도구는 [GitHub 프록시](#github-proxy)를 통해 인증하며, [GitHub 인증 옵션](/docs/ko/claude-code-on-the-web#github-authentication-options) 아래에서 구성한 방법을 사용하므로 토큰이 컨테이너에 들어가지 않습니다.376클라우드 세션에는 Claude가 별도 설정 없이 이슈를 읽고, 풀 리퀘스트를 나열하고, diff를 가져오고, 댓글을 게시할 수 있는 기본 제공 GitHub 도구가 포함됩니다. 이러한 도구는 [GitHub 프록시](#github-proxy)를 통해 인증하며, [GitHub 인증 옵션](/docs/ko/claude-code-on-the-web#github-authentication-options) 아래에서 구성한 방법을 사용하므로 토큰이 컨테이너에 들어가지 않습니다.

361 377

362[환경 설정](#set-environment-variables)에서 `GH_TOKEN` 또는 `GITHUB_TOKEN`을 직접 설정하거나 둘 다 설정하지 않고 [GitHub 프록시](#github-proxy)가 인증을 처리하도록 할 수 있습니다:378[환경 설정](#set-environment-variables)에서 `GH_TOKEN` 또는 `GITHUB_TOKEN`을 직접 설정하거나 둘 다 설정하지 않고 [GitHub 프록시](#github-proxy)가 인증을 처리하도록 할 수 있습니다:

363 379

364* 토큰을 설정하면 컨테이너에 변경되지 않고 전달되므로 스크립트 및 GitHub의 [`gh` CLI](https://cli.github.com)가 직접 사용합니다.380* 토큰을 설정하면 컨테이너에 변경되지 않고 전달되므로 스크립트 및 GitHub의 [`gh` CLI](https://cli.github.com)가 직접 사용합니다.

365* 둘 다 설정하지 않고 [GitHub 프록시](#github-proxy)가 세션에 대한 인증을 처리하는 경우 두 변수 모두 Claude가 실행하는 명령에서 자리 표시자 문자열 `proxy-injected`로 읽으며, 프록시는 아웃바운드 GitHub 요청에서 실제 자격 증명을 대체합니다. `gh`는 자신의 토큰 없이 작동하지만 `GITHUB_TOKEN`을 직접 읽는 스크립트는 사용 가능한 토큰이 아닌 자리 표시자를 받습니다.381* 둘 다 설정하지 않고 [GitHub 프록시](#github-proxy)가 세션에 대한 인증을 처리하는 경우 두 변수 모두 Claude가 실행하는 명령에서 자리 표시자 문자열 `proxy-injected`로 읽히며, 프록시는 아웃바운드 GitHub 요청에서 실제 자격 증명으로 대체합니다. 연결된 저장소에 대한 `gh api` 호출은 자신의 토큰 없이 작동하지만 `GITHUB_TOKEN`을 직접 읽는 스크립트는 사용 가능한 토큰이 아닌 자리 표시자를 받습니다.

366 382

367설정한 토큰은 일반 환경 변수이므로 환경을 사용하는 모든 사람이 읽을 수 있습니다. 프록시 경로는 자격 증명을 환경 구성 및 세션 VM 외부에 유지합니다.383설정한 토큰은 일반 환경 변수이므로 환경을 사용하는 모든 사람이 읽을 수 있습니다. 프록시 경로는 자격 증명을 환경 구성 및 세션 VM 외부에 유지합니다.

368 384

369세션에 어느 경우가 적용되는지 확인하려면 Claude에게 `echo $GH_TOKEN`을 실행하도록 요청합니다.385세션에 어느 경우가 적용되는지 확인하려면 Claude에게 `echo $GH_TOKEN`을 실행하도록 요청합니다.

370 386

371GitHub의 [`gh` CLI](https://cli.github.com)는 사전 설치됩니다. 기본 제공 도구가 다루지 않는 `gh release` 또는 `gh workflow run`과 같은 `gh` 명령이 필요한 경우 Claude에게 실행하도록 요청합니다. `gh`는 `GH_TOKEN`을 자동으로 읽으므로 `gh auth login`을 실행할 필요가 없습니다.387GitHub의 [`gh` CLI](https://cli.github.com)는 사전 설치됩니다. 기본 제공 도구가 다루지 않는 GitHub 작업이 필요한 경우 Claude에게 `gh api`로 REST API를 호출하도록 요청합니다. `gh workflow list`와 같이 REST API를 사용하는 `gh` 하위 명령도 작동합니다. 프록시는 `gh pr` 및 `gh issue`와 같이 [GraphQL을 사용하는 하위 명령을 거부](#github-proxy)합니다. `gh`는 `GH_TOKEN`을 자동으로 읽으므로 `gh auth login`을 실행할 필요가 없습니다.

372 388

373<h3 id="link-output-back-to-the-session">389<h3 id="link-output-back-to-the-session">

374 출력을 세션에 다시 연결390 출력을 세션에 다시 연결

388 테스트 실행, 서비스 시작 및 패키지 추가404 테스트 실행, 서비스 시작 및 패키지 추가

389</h3>405</h3>

390 406

391세션 VM에 셸이 없습니다. Claude가 모든 명령을 실행하므로 이 섹션의 작업을 프롬프트의 요청으로 표현합니다.407세션 VM에 셸로 접속할 수 없습니다. Claude가 모든 명령을 실행하므로 이 섹션의 작업을 프롬프트의 요청으로 표현합니다.

392 408

393<h4 id="run-tests">409<h4 id="run-tests">

394 테스트 실행410 테스트 실행

395</h4>411</h4>

396 412

397Claude는 작업을 수행하는 과정에서 테스트를 실행합니다. 프롬프트에서 "fix the failing tests in `tests/`" 또는 "run pytest after each change"와 같이 요청합니다. pytest 및 cargo test와 같은 [사전 설치된 도구 체인](#installed-tools)과 함께 제공되는 테스트 러너는 추가 설정 없이 작동합니다. jest와 같이 프로젝트가 종속성으로 선언하는 러너는 종속성과 함께 설치됩니다.413Claude는 작업을 수행하는 과정에서 테스트를 실행합니다. 프롬프트에서 "fix the failing tests in `tests/`" 또는 "run pytest after each change"와 같이 요청합니다. pytest 및 cargo test와 같은 [사전 설치된 도구 체인](#installed-tools)과 함께 제공되는 테스트 러너는 추가 설정 없이 작동합니다. jest와 같이 프로젝트가 의존성으로 선언하는 러너는 의존성과 함께 설치됩니다.

398 414

399<h4 id="start-services">415<h4 id="start-services">

400 서비스 시작416 서비스 시작

401</h4>417</h4>

402 418

403PostgreSQL 및 Redis는 사전 설치되어 있지만 기본적으로 실행되지 않습니다. 필요한 것을 시작하도록 Claude에게 요청합니다. 실행하는 명령은:419PostgreSQL 및 Redis는 사전 설치되어 있지만 기본적으로 실행되지 않습니다. 필요한 것을 시작하도록 Claude에게 요청합니다. 실행하는 명령은 다음과 같습니다:

404 420

405```bash theme={null}421```bash theme={null}

406service postgresql start422service postgresql start

430* 16GB의 RAM446* 16GB의 RAM

431* 30GB의 디스크447* 30GB의 디스크

432 448

433VM은 대규모 빌드 작업 또는 메모리 집약적인 테스트와 같이 훨씬 더 많은 메모리가 필요한 작업을 중지할 수 있습니다. 이러한 제한을 초과하는 워크로드의 경우 [Remote Control](/docs/ko/remote-control)을 사용하여 자신의 하드웨어에서 Claude Code를 실행하거나 조직이 운영하는 컴퓨팅에서 [자체 호스팅 환경](/docs/ko/self-hosted-environments)에서 클라우드 세션을 실행합니다.449VM은 대규모 빌드 작업 또는 메모리 집약적인 테스트와 같이 훨씬 더 많은 메모리가 필요한 작업을 중지할 수 있습니다. 이러한 제한을 초과하는 워크로드의 경우 [Remote Control](/docs/ko/remote-control)을 사용하여 자신의 하드웨어에서 Claude Code를 실행하거나 조직이 운영하는 컴퓨팅의 [자체 호스팅 환경](/docs/ko/self-hosted-environments)에서 클라우드 세션을 실행합니다.

434 450

435<h3 id="time-limits">451<h3 id="time-limits">

436 시간 제한452 시간 제한

438 454

439Anthropic 호스팅 환경에서 이러한 시간 제한은 빌드, 설치 또는 테스트 실행과 같은 클라우드 세션의 장기 실행 작업에 적용됩니다. 각 항목은 제한을 정의하는 섹션으로 연결됩니다.455Anthropic 호스팅 환경에서 이러한 시간 제한은 빌드, 설치 또는 테스트 실행과 같은 클라우드 세션의 장기 실행 작업에 적용됩니다. 각 항목은 제한을 정의하는 섹션으로 연결됩니다.

440 456

441* **Claude가 실행하는 명령**: 클라우드 환경은 자신의 명령 타임아웃을 설정하지 않으므로 Bash 도구의 기본값이 적용됩니다. Claude는 기본적으로 명령을 2분 동안 기다리며 최대 10분까지 요청할 수 있습니다.457* **Claude가 실행하는 명령**: 클라우드 환경은 자체 명령 타임아웃을 설정하지 않으므로 Bash 도구의 기본값이 적용됩니다. Claude는 기본적으로 포그라운드 명령을 2분 동안 기다리며 최대 10분까지 요청할 수 있습니다.

442 458

443 명령이 [타임아웃](/docs/ko/tools-reference#timeout-and-output-limits)에 도달하면 Claude Code는 명령이 `sleep`으로 시작하지 않는 한 명령을 중지하는 대신 [백그라운드로 이동](/docs/ko/tools-reference#foreground-commands-that-move-to-the-background)합니다. 이런 방식으로 이동된 명령은 Claude Code가 [백그라운드 시간 제한](/docs/ko/tools-reference#time-limit-for-background-commands)에서 중지하기 전에 최대 30분 더 실행될 수 있습니다. `BASH_DEFAULT_TIMEOUT_MS`를 `1800000` 밀리초 이상으로 설정하면 해당 제한과 포그라운드 기본값이 모두 길어집니다.459 명령이 [타임아웃](/docs/ko/tools-reference#timeout-and-output-limits)에 도달하면 Claude Code는 명령이 `sleep`으로 시작하지 않는 한 명령을 중지하는 대신 [백그라운드로 이동](/docs/ko/tools-reference#foreground-commands-that-move-to-the-background)합니다. 이런 방식으로 이동된 명령은 Claude Code가 [백그라운드 시간 제한](/docs/ko/tools-reference#time-limit-for-background-commands)에서 중지하기 전에 최대 30분 더 실행될 수 있습니다. `BASH_DEFAULT_TIMEOUT_MS`를 `1800000` 밀리초 이상으로 설정하면 해당 제한과 포그라운드 기본값이 모두 길어집니다.

444* **SessionStart 훅**: Claude Code는 [`timeout`](/docs/ko/hooks#common-fields)을 초 단위로 설정하지 않으면 600초 후 `command` 훅을 취소합니다. Claude Code는 [`async: true`](/docs/ko/hooks#run-hooks-in-the-background)로 실행하는 훅에 타임아웃을 적용하지 않습니다.460* **SessionStart 훅**: Claude Code는 훅 항목에 [`timeout`](/docs/ko/hooks#common-fields)을 초 단위로 설정하지 않으면 600초 후 `command` 훅을 취소합니다. Claude Code는 [`async: true`](/docs/ko/hooks#run-hooks-in-the-background)로 실행하는 훅에 타임아웃을 적용하지 않습니다.

445* **설정 스크립트**: 대략 5분 이상 걸리는 스크립트는 캐시되지 않습니다. [스크립트 요구 사항](#script-requirements)은 그 이하로 유지하는 방법을 다룹니다.461* **설정 스크립트**: 대략 5분 이상 걸리는 스크립트는 캐시되지 않습니다. [스크립트 요구 사항](#script-requirements)은 그 이하로 유지하는 방법을 다룹니다.

446* **유휴 세션**: 몇 분 동안 활동이 없으면 세션의 VM이 파일이 저장된 상태로 일시 중지되고, 일시 중지된 VM은 나중에 회수될 수 있습니다. [환경 변수 설정](#set-environment-variables)은 각 경우에 세션이 선택하는 항목을 설명하고, [Environment expired](/docs/ko/claude-code-on-the-web#environment-expired)는 VM이 회수된 세션을 다시 여는 방법을 다룹니다.462* **유휴 세션**: 몇 분 동안 활동이 없으면 세션의 VM이 파일이 저장된 상태로 일시 중지되고, 일시 중지된 VM은 나중에 회수될 수 있습니다. [환경 변수 설정](#set-environment-variables)은 각 경우에 세션이 반영하는 항목을 설명하고, [Environment expired](/docs/ko/claude-code-on-the-web#environment-expired)는 VM이 회수된 세션을 다시 여는 방법을 다룹니다.

447 463

448환경의 세션에 대한 명령 타임아웃을 높이려면 [`BASH_DEFAULT_TIMEOUT_MS` 및 `BASH_MAX_TIMEOUT_MS`](/docs/ko/env-vars#variables)를 [환경 변수](#set-environment-variables)에 추가합니다. 둘 다 밀리초를 사용합니다. 예를 들어 `BASH_DEFAULT_TIMEOUT_MS=600000`은 10분을 기본값으로 만듭니다.464환경의 세션에 대한 명령 타임아웃을 높이려면 [`BASH_DEFAULT_TIMEOUT_MS` 및 `BASH_MAX_TIMEOUT_MS`](/docs/ko/env-vars#variables)를 해당 환경의 [환경 변수](#set-environment-variables)에 추가합니다. 둘 다 밀리초 단위입니다. 예를 들어 `BASH_DEFAULT_TIMEOUT_MS=600000`은 10분을 기본값으로 만듭니다.

449 465

450<h2 id="setup-scripts">466<h2 id="setup-scripts">

451 설정 스크립트467 설정 스크립트

code-review.md +1 −1

Details

379 노력 및 인수 조정379 노력 및 인수 조정

380</h3>380</h3>

381 381

382[노력 수준](/docs/ko/model-config#adjust-effort-level)을 전달하여 범위와 신뢰도를 교환합니다. `low` 및 `medium`에서 검토는 가장 확신하는 결과만 보고하므로 거짓 양성이 적습니다. `high`부터 `max`까지는 범위를 확대하며 검토가 덜 확신하는 결과를 포함할 수 있습니다.382[effort 수준](/docs/ko/model-config#adjust-effort-level)을 전달하여 범위와 신뢰도를 교환합니다. `low`에서 검토는 가장 확신하는 결과를 보고하므로 거짓 양성이 적습니다. `medium`부터 `max`까지는 검토가 범위를 확대합니다.

383 383

384수준을 입력하지 않으면, 검토는 이전 세션에서도 입력한 `low`부터 `max`까지의 마지막 수준을 재사용하며, Claude Code는 `Reusing high effort, the level you typed last time`과 같은 알림을 표시합니다. `/code-review high`와 같은 수준을 입력하여 나중에 실행이 재사용할 내용을 변경합니다. 비대화형 `-p` 실행에서 전달하는 수준은 이를 업데이트하지 않습니다. `ultra`는 기억된 수준을 업데이트하거나 사용하지 않습니다. 수준을 입력한 적이 없으면, 검토는 세션의 현재 노력을 사용합니다. v2.1.223 이전에는 수준 없는 `/code-review`는 항상 세션의 현재 노력을 사용했습니다.384수준을 입력하지 않으면, 검토는 이전 세션에서도 입력한 `low`부터 `max`까지의 마지막 수준을 재사용하며, Claude Code는 `Reusing high effort, the level you typed last time`과 같은 알림을 표시합니다. `/code-review high`와 같은 수준을 입력하여 나중에 실행이 재사용할 내용을 변경합니다. 비대화형 `-p` 실행에서 전달하는 수준은 이를 업데이트하지 않습니다. `ultra`는 기억된 수준을 업데이트하거나 사용하지 않습니다. 수준을 입력한 적이 없으면, 검토는 세션의 현재 노력을 사용합니다. v2.1.223 이전에는 수준 없는 `/code-review`는 항상 세션의 현재 노력을 사용했습니다.

385 385

context-window.md +7 −7

Details

1586 1586

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

1588 1588

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

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

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

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

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

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

1605| [Git 상태 스냅샷](/docs/ko/settings-reference#includegitinstructions) | Claude Code가 저장소에서 새로운 것을 읽음 |1605| [Git 상태 스냅샷](/docs/ko/settings-reference#includegitinstructions) | Claude Code가 저장소에서 새로운 것을 읽음 |

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

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

1609| Claude가 읽거나 편집한 파일 | Claude Code가 최대 5개를 다시 읽음, 가장 최근에 수정된 것부터 |1609| Claude가 읽거나 편집한 파일 | Claude Code가 최대 5개를 다시 읽음, 가장 최근에 수정된 것부터 |

1610| 호출된 스킬 본문 | 다시 주입됨, 스킬당 5,000 토큰 및 총 25,000 토큰으로 제한됨; 가장 오래된 것부터 삭제됨 |1610| 호출된 스킬 본문 | 다시 주입됨, 스킬당 5,000 토큰 및 총 25,000 토큰으로 제한됨; 가장 오래된 것부터 삭제됨 |

1611| [Background commands](/docs/ko/interactive-mode#background-bash-commands) 및 background [subagents](/docs/ko/sub-agents#run-subagents-in-foreground-or-background) | 계속 실행됨. Claude Code는 Claude에게 어떤 것이 여전히 실행 중인지 상기시켜 중복을 시작하지 않도록 함 |1611| [백그라운드 명령](/docs/ko/interactive-mode#background-bash-commands) 및 백그라운드 [서브에이전트](/docs/ko/sub-agents#run-subagents-in-foreground-or-background) | 계속 실행됨. Claude Code는 Claude에게 어떤 것이 여전히 실행 중인지 상기시켜 중복을 시작하지 않도록 함 |

1612| 훅이 이전에 추가한 컨텍스트 | 대화의 나머지 부분과 함께 요약됨 |1612| 훅이 이전에 추가한 컨텍스트 | 대화의 나머지 부분과 함께 요약됨 |

1613| `compact` 소스와 일치하는 [SessionStart hooks](/docs/ko/hooks-guide#re-inject-context-after-compaction) | Claude Code가 실행하고 압축된 컨텍스트에 출력을 추가함 |1613| `compact` 소스와 일치하는 [SessionStart 훅](/docs/ko/hooks-guide#re-inject-context-after-compaction) | Claude Code가 실행하고 압축된 컨텍스트에 출력을 추가함 |

1614 1614

1615압축 직후, Claude Code는 세션에서 Claude가 읽거나 편집한 파일 중 최대 5개를 다시 읽으며, 가장 최근에 수정된 파일을 선택합니다. 5,000 토큰을 초과하는 파일은 경로 참조로 돌아오며 내용 없이 `Referenced file`로 표시됩니다.1615압축 직후, Claude Code는 세션에서 Claude가 읽거나 편집한 파일 중 최대 5개를 다시 읽으며, 가장 최근에 수정된 파일을 선택합니다. 5,000 토큰을 초과하는 파일은 내용 없이 경로 참조로 돌아오며, `Read` 대신 `Referenced file`로 표시됩니다.

1616 1616

1617경로 범위 규칙 및 중첩 CLAUDE.md 파일은 트리거 파일을 읽을 때 메시지 기록에 로드되므로 압축은 다른 모든 것과 함께 이들을 요약합니다. 규칙이 압축 전체에서 유지되어야 하는 경우 `paths:` 프론트매터를 삭제하거나 프로젝트 루트 CLAUDE.md로 이동하세요.1617경로 범위 규칙 및 중첩 CLAUDE.md 파일은 Claude가 트리거 파일을 읽거나, 쓰거나, 편집할 때 메시지 기록에 로드되므로 압축은 다른 모든 것과 함께 이들을 요약합니다. 규칙이 압축 전체에서 유지되어야 하는 경우 `paths:` frontmatter를 삭제하거나 프로젝트 루트 CLAUDE.md로 이동하세요.

1618 1618

1619스킬 본문은 압축 후 다시 주입되지만 큰 스킬은 스킬당 제한에 맞게 잘리고, 총 예산을 초과하면 가장 오래된 호출된 스킬이 삭제됩니다. 잘림은 파일의 시작을 유지하므로 `SKILL.md`의 맨 위에 가장 중요한 지시사항을 배치하세요.1619스킬 본문은 압축 후 다시 주입되지만 큰 스킬은 스킬당 제한에 맞게 잘리고, 총 예산을 초과하면 가장 오래된 호출된 스킬이 삭제됩니다. 잘림은 파일의 시작을 유지하므로 `SKILL.md`의 맨 위에 가장 중요한 지시사항을 배치하세요.

1620 1620

1632* **작업 간 지우기**: 관련 없는 작업으로 전환할 때 `/clear`를 실행하세요. 오래된 대화는 다음에 필요한 파일을 밀어내고 모든 메시지에서 토큰을 소비합니다.1632* **작업 간 지우기**: 관련 없는 작업으로 전환할 때 `/clear`를 실행하세요. 오래된 대화는 다음에 필요한 파일을 밀어내고 모든 메시지에서 토큰을 소비합니다.

1633* **대용량 읽기 위임**: 연구를 [서브에이전트](/docs/ko/sub-agents)에 보내 파일 콘텐츠가 사용자의 컨텍스트 윈도우가 아닌 서브에이전트의 컨텍스트 윈도우에 유지되도록 하세요.1633* **대용량 읽기 위임**: 연구를 [서브에이전트](/docs/ko/sub-agents)에 보내 파일 콘텐츠가 사용자의 컨텍스트 윈도우가 아닌 서브에이전트의 컨텍스트 윈도우에 유지되도록 하세요.

1634 1634

1635더 작은 대화보다 더 큰 윈도우가 필요한 경우 Fable 모델, Sonnet 5 이상, Opus 4.6 이상, Sonnet 4.6은 100만 토큰 컨텍스트 윈도우를 지원합니다. 플랜별 가용성 및 `[1m]` 모델 변형을 선택하는 방법은 [확장 컨텍스트](/docs/ko/model-config#extended-context)를 참조하세요. 압축은 더 큰 제한에서도 동일한 방식으로 작동합니다.1635더 작은 대화보다 더 큰 윈도우가 필요한 경우 Fable 모델, Sonnet 5 이상, Haiku 5.5, Opus 4.6 이상, Sonnet 4.6은 100만 토큰 컨텍스트 윈도우를 지원합니다. 플랜별 가용성 및 `[1m]` 모델 변형을 선택하는 방법은 [확장 컨텍스트](/docs/ko/model-config#extended-context)를 참조하세요. 압축은 더 큰 제한에서도 동일한 방식으로 작동합니다.

1636 1636

1637Sonnet 5.5 및 Sonnet 5는 1M 컨텍스트 윈도우로 실행되며 선택할 `[1m]` 변형이 없습니다. [Sonnet 5.5 및 Sonnet 5 컨텍스트 윈도우](/docs/ko/model-config#sonnet-5-5-and-sonnet-5-context-window)에서 자동 압축 임계값을 참조하고, [게이트웨이 뒤의 컨텍스트 윈도우](/docs/ko/model-config#context-window-behind-a-gateway)에서 `ANTHROPIC_BASE_URL`을 [LLM 게이트웨이](/docs/ko/llm-gateway)로 설정할 때 Claude Code가 윈도우 크기를 조정하는 방법을 참조하세요.1637Sonnet 5.5 및 Sonnet 5는 1M 컨텍스트 윈도우로 실행되며 선택할 `[1m]` 변형이 없습니다. [Sonnet 5.5 및 Sonnet 5 컨텍스트 윈도우](/docs/ko/model-config#sonnet-5-5-and-sonnet-5-context-window)에서 자동 압축 임계값을 참조하고, [게이트웨이 뒤의 컨텍스트 윈도우](/docs/ko/model-config#context-window-behind-a-gateway)에서 `ANTHROPIC_BASE_URL`을 [LLM 게이트웨이](/docs/ko/llm-gateway)로 설정할 때 Claude Code가 윈도우 크기를 조정하는 방법을 참조하세요.

1638 1638

costs.md +28 −28

Details

252 토큰 사용량 감소252 토큰 사용량 감소

253</h2>253</h2>

254 254

255토큰 비용은 컨텍스트 크기에 따라 확장됩니다. Claude가 처리하는 컨텍스트가 많을수록 더 많은 토큰을 사용합니다. Claude Code는 [prompt caching](/docs/ko/prompt-caching)(시스템 프롬프트와 같은 반복되는 콘텐츠의 비용을 줄임)과 auto-compaction(컨텍스트 한도에 접근할 때 대화 기록을 요약함)을 통해 비용을 자동으로 최적화합니다.255토큰 비용은 컨텍스트 크기에 따라 확장됩니다. Claude가 처리하는 컨텍스트가 많을수록 더 많은 토큰을 사용합니다. Claude Code는 [프롬프트 캐싱](/docs/ko/prompt-caching)(시스템 프롬프트와 같은 반복되는 콘텐츠의 비용을 줄임)과 자동 압축(컨텍스트 한도에 접근할 때 대화 기록을 요약함)을 통해 비용을 자동으로 최적화합니다.

256 256

257다음 전략은 컨텍스트를 작게 유지하고 메시지당 비용을 줄이는 데 도움이 됩니다.257다음 전략은 컨텍스트를 작게 유지하고 메시지당 비용을 줄이는 데 도움이 됩니다.

258 258

260 컨텍스트를 사전에 관리하기260 컨텍스트를 사전에 관리하기

261</h3>261</h3>

262 262

263`/usage`를 사용하여 현재 토큰 사용량을 확인하거나, [상태 줄을 구성](/docs/ko/statusline#context-window-usage)하여 지속적으로 표시하십시오.263`/usage`를 사용하여 현재 토큰 사용량을 확인하거나, [상태줄을 구성](/docs/ko/statusline#context-window-usage)하여 지속적으로 표시하십시오.

264 264

265* **작업 간 지우기**: 관련 없는 작업으로 전환할 때 `/clear`를 사용하여 새로 시작하십시오. 오래된 컨텍스트는 이후의 모든 메시지에서 토큰을 낭비합니다. 지우기 전에 `/rename`을 사용하여 나중에 세션을 쉽게 찾을 수 있도록 한 다음, `/resume`을 사용하여 돌아가십시오.265* **작업 간 지우기**: 관련 없는 작업으로 전환할 때 `/clear`를 사용하여 새로 시작하십시오. 오래된 컨텍스트는 이후의 모든 메시지에서 토큰을 낭비합니다. 지우기 전에 `/rename`을 사용하여 나중에 세션을 쉽게 찾을 수 있도록 한 다음, `/resume`을 사용하여 돌아가십시오.

266* **사용자 정의 compaction 지침 추가**: `/compact Focus on code samples and API usage`는 Claude에게 요약 중에 보존할 내용을 알려줍니다.266* **사용자 정의 압축 지침 추가**: `/compact Focus on code samples and API usage`는 Claude에게 요약 중에 보존할 내용을 알려줍니다.

267 267

268프로젝트의 루트에 있는 CLAUDE.md 파일에서 compaction 동작을 사용자 정의할 수도 있습니다:268프로젝트의 루트에 있는 CLAUDE.md 파일에서 압축 동작을 사용자 정의할 수도 있습니다:

269 269

270```markdown theme={null}270```markdown theme={null}

271# Compact instructions271# Compact instructions

277 올바른 모델 선택277 올바른 모델 선택

278</h3>278</h3>

279 279

280Sonnet은 대부분의 코딩 작업을 잘 처리하며 Opus보다 비용이 적습니다. 복잡한 아키텍처 결정이나 다단계 추론을 위해 Opus를 예약하십시오. `/model`을 사용하여 세션 중간에 모델을 전환하거나, `/config`에서 기본값을 설정하십시오. Opus로 전환하면 [세션의 모델을 상속하는 subagents](/docs/ko/model-config#setting-your-model)에도 적용됩니다. 간단한 subagent 작업의 경우, [subagent 구성](/docs/ko/sub-agents#choose-a-model)에서 `model: haiku`를 지정하십시오.280Sonnet은 대부분의 코딩 작업을 잘 처리하며 Opus보다 비용이 적습니다. 복잡한 아키텍처 결정이나 다단계 추론을 위해 Opus를 예약하십시오. `/model`을 사용하여 세션 중간에 모델을 전환하거나, `/config`에서 기본값을 설정하십시오. Opus로 전환하면 [세션의 모델을 상속하는 서브에이전트](/docs/ko/model-config#setting-your-model)에도 적용됩니다. 간단한 서브에이전트 작업의 경우, [서브에이전트 구성](/docs/ko/sub-agents#choose-a-model)에서 `model: haiku`를 지정하십시오.

281 281

282<h3 id="reduce-mcp-server-overhead">282<h3 id="reduce-mcp-server-overhead">

283 MCP server 오버헤드 감소283 MCP 서버 오버헤드 감소

284</h3>284</h3>

285 285

286MCP 도구 정의는 [기본적으로 연기됩니다](/docs/ko/mcp#scale-with-mcp-tool-search). 따라서 Claude가 특정 도구를 사용할 때까지 도구 이름과 server 지침만 컨텍스트에 들어갑니다. `/context`를 실행하여 공간을 소비하는 것을 확인하십시오.286MCP 도구 정의는 [기본적으로 연기됩니다](/docs/ko/mcp#scale-with-mcp-tool-search). 따라서 Claude가 특정 도구를 사용할 때까지 도구 이름과 서버 지침만 컨텍스트에 들어갑니다. `/context`를 실행하여 공간을 소비하는 것을 확인하십시오.

287 287

288* **사용 가능한 경우 CLI 도구 선호**: `gh`, `aws`, `gcloud`, `sentry-cli`와 같은 도구는 도구별 목록을 추가하지 않기 때문에 MCP server보다 컨텍스트 효율적입니다. Claude는 CLI 명령을 직접 실행할 수 있습니다.288* **사용 가능한 경우 CLI 도구 선호**: `gh`, `aws`, `gcloud`, `sentry-cli`와 같은 도구는 도구별 목록을 추가하지 않기 때문에 여전히 MCP 서버보다 컨텍스트 효율적입니다. Claude는 CLI 명령을 직접 실행할 수 있습니다.

289* **사용하지 않는 server 비활성화**: `/mcp`를 실행하여 구성된 server를 확인하고 적극적으로 사용하지 않는 것을 비활성화하십시오.289* **사용하지 않는 서버 비활성화**: `/mcp`를 실행하여 구성된 서버를 확인하고 적극적으로 사용하지 않는 것을 비활성화하십시오.

290 290

291<h3 id="install-code-intelligence-plugins-for-typed-languages">291<h3 id="install-code-intelligence-plugins-for-typed-languages">

292 타입 언어를 위한 코드 인텔리전스 플러그인 설치292 타입 언어를 위한 코드 인텔리전스 플러그인 설치

295[코드 인텔리전스 플러그인](/docs/ko/plugins/code-intelligence)은 Claude에게 텍스트 기반 검색 대신 정확한 기호 탐색을 제공하여 낯선 코드를 탐색할 때 불필요한 파일 읽기를 줄입니다. 단일 "정의로 이동" 호출은 grep 다음에 여러 후보 파일을 읽는 것을 대체합니다. 설치된 언어 서버는 편집 후 자동으로 타입 오류를 보고하므로 Claude는 컴파일러를 실행하지 않고도 실수를 포착합니다.295[코드 인텔리전스 플러그인](/docs/ko/plugins/code-intelligence)은 Claude에게 텍스트 기반 검색 대신 정확한 기호 탐색을 제공하여 낯선 코드를 탐색할 때 불필요한 파일 읽기를 줄입니다. 단일 "정의로 이동" 호출은 grep 다음에 여러 후보 파일을 읽는 것을 대체합니다. 설치된 언어 서버는 편집 후 자동으로 타입 오류를 보고하므로 Claude는 컴파일러를 실행하지 않고도 실수를 포착합니다.

296 296

297<h3 id="offload-processing-to-hooks-and-skills">297<h3 id="offload-processing-to-hooks-and-skills">

298 hooks 및 skills로 처리 오프로드298 훅 및 스킬로 처리 오프로드

299</h3>299</h3>

300 300

301사용자 정의 [hooks](/docs/ko/hooks)는 Claude가 보기 전에 데이터를 전처리할 수 있습니다. Claude가 10,000줄 로그 파일을 읽어 오류를 찾는 대신, hook은 `ERROR`를 grep하고 일치하는 줄만 반환하여 컨텍스트를 수만 개의 토큰에서 수백 개로 줄일 수 있습니다.301사용자 정의 [훅](/docs/ko/hooks)은 Claude가 보기 전에 데이터를 전처리할 수 있습니다. Claude가 10,000줄 로그 파일을 읽어 오류를 찾는 대신, 훅은 `ERROR`를 grep하고 일치하는 줄만 반환하여 컨텍스트를 수만 개의 토큰에서 수백 개로 줄일 수 있습니다.

302 302

303[skill](/docs/ko/skills)은 Claude에게 도메인 지식을 제공하여 탐색할 필요가 없도록 할 수 있습니다. 예를 들어, "codebase-overview" skill은 프로젝트의 아키텍처, 주요 디렉토리 및 명명 규칙을 설명할 수 있습니다. Claude가 skill을 호출하면, 구조를 이해하기 위해 여러 파일을 읽는 데 토큰을 소비하는 대신 즉시 이 컨텍스트를 얻습니다.303[스킬](/docs/ko/skills)은 Claude에게 도메인 지식을 제공하여 탐색할 필요가 없도록 할 수 있습니다. 예를 들어, "codebase-overview" 스킬은 프로젝트의 아키텍처, 주요 디렉토리 및 명명 규칙을 설명할 수 있습니다. Claude가 스킬을 호출하면, 구조를 이해하기 위해 여러 파일을 읽는 데 토큰을 소비하는 대신 즉시 이 컨텍스트를 얻습니다.

304 304

305예를 들어, 이 PreToolUse hook은 테스트 출력을 필터링하여 실패만 표시합니다:305예를 들어, 이 PreToolUse 훅은 테스트 출력을 필터링하여 실패만 표시합니다:

306 306

307<Tabs>307<Tabs>

308 <Tab title="settings.json">308 <Tab title="settings.json">

309 이를 [settings.json](/docs/ko/settings#where-settings-live)에 추가하여 모든 Bash 명령 전에 hook을 실행하십시오:309 이를 [settings.json](/docs/ko/settings#where-settings-live)에 추가하여 모든 Bash 명령 전에 훅을 실행하십시오:

310 310

311 ```json theme={null}311 ```json theme={null}

312 {312 {

328 </Tab>328 </Tab>

329 329

330 <Tab title="filter-test-output.sh">330 <Tab title="filter-test-output.sh">

331 hook은 이 스크립트를 호출합니다. `mkdir -p ~/.claude/hooks`로 폴더를 만들고, 아래 스크립트를 `~/.claude/hooks/filter-test-output.sh`로 저장한 다음, `chmod +x ~/.claude/hooks/filter-test-output.sh`로 실행 가능하게 만드십시오. 명령이 테스트 러너인지 확인하고 실패만 표시하도록 수정합니다:331 훅은 이 스크립트를 호출합니다. `mkdir -p ~/.claude/hooks`로 폴더를 만들고, 아래 스크립트를 `~/.claude/hooks/filter-test-output.sh`로 저장한 다음, `chmod +x ~/.claude/hooks/filter-test-output.sh`로 실행 가능하게 만드십시오. 명령이 테스트 러너인지 확인하고 실패만 표시하도록 수정합니다:

332 332

333 ```bash theme={null}333 ```bash theme={null}

334 #!/bin/bash334 #!/bin/bash

347 </Tab>347 </Tab>

348</Tabs>348</Tabs>

349 349

350설정을 확인하려면 `/hooks`를 실행하고 hook이 PreToolUse 아래에 나타나는지 확인하십시오. `claude --debug-file ./claude-debug.txt`로 Claude Code를 시작하고 Claude에게 `npm test`를 실행하도록 요청할 수도 있습니다. hook이 명령을 다시 쓸 때, 해당 로그 파일에는 `command`와 다른 Bash 입력 필드를 나열하는 `modified tool input keys` 줄이 포함됩니다.350설정을 확인하려면 `/hooks`를 실행하고 훅이 PreToolUse 아래에 나타나는지 확인하십시오. `claude --debug-file ./claude-debug.txt`로 Claude Code를 시작하고 Claude에게 `npm test`를 실행하도록 요청할 수도 있습니다. 훅이 명령을 다시 쓸 때, 해당 로그 파일에는 `command`와 다른 Bash 입력 필드를 나열하는 `modified tool input keys` 줄이 포함됩니다.

351 351

352<h3 id="move-instructions-from-claude-md-to-skills">352<h3 id="move-instructions-from-claude-md-to-skills">

353 CLAUDE.md에서 skills로 지침 이동353 CLAUDE.md에서 스킬로 지침 이동

354</h3>354</h3>

355 355

356[CLAUDE.md](/docs/ko/memory) 파일은 세션 시작 시 컨텍스트에 로드됩니다. PR 검토 또는 데이터베이스 마이그레이션과 같은 특정 워크플로우에 대한 자세한 지침이 포함되어 있으면, 관련 없는 작업을 수행할 때도 해당 토큰이 존재합니다. [Skills](/docs/ko/skills)는 호출될 때만 필요에 따라 로드되므로, 특화된 지침을 skills로 이동하면 기본 컨텍스트를 더 작게 유지합니다. CLAUDE.md를 필수 항목만 포함하여 약 200줄 이하로 유지하십시오.356[CLAUDE.md](/docs/ko/memory) 파일은 세션 시작 시 컨텍스트에 로드됩니다. PR 검토 또는 데이터베이스 마이그레이션과 같은 특정 워크플로에 대한 자세한 지침이 포함되어 있으면, 관련 없는 작업을 수행할 때도 해당 토큰이 존재합니다. [스킬](/docs/ko/skills)은 호출될 때만 필요에 따라 로드되므로, 특화된 지침을 스킬로 이동하면 기본 컨텍스트를 더 작게 유지합니다. CLAUDE.md를 필수 항목만 포함하여 200줄 이하로 유지하십시오.

357 357

358<h3 id="adjust-extended-thinking">358<h3 id="adjust-extended-thinking">

359 확장 사고 조정359 확장 사고 조정

360</h3>360</h3>

361 361

362확장 사고는 기본적으로 활성화되어 있습니다. 복잡한 계획 및 추론 작업의 성능을 크게 향상시키기 때문입니다. 사고 토큰은 출력 토큰으로 청구되며, 기본 예산은 모델에 따라 수만 개의 토큰이 될 수 있습니다.362확장 사고는 기본적으로 활성화되어 있습니다. 복잡한 계획 및 추론 작업의 성능을 크게 향상시키기 때문입니다. 사고 토큰은 출력 토큰으로 청구되며, 기본 예산은 모델에 따라 요청당 수만 개의 토큰이 될 수 있습니다.

363 363

364더 간단한 작업에서 깊은 추론이 필요하지 않은 경우, `/effort`를 사용하거나 `/model`에서 [노력 수준](/docs/ko/model-config#adjust-effort-level)을 낮추거나, `/config`에서 사고를 비활성화하여 비용을 줄일 수 있습니다. Opus 5.5, Sonnet 5.5 또는 Fable 모델에서는 사고를 끌 수 없으며, 항상 확장 사고를 사용합니다.364더 간단한 작업에서 깊은 추론이 필요하지 않은 경우, `/effort`를 사용하거나 `/model`에서 [effort 수준](/docs/ko/model-config#adjust-effort-level)을 낮추거나, `/config`에서 사고를 비활성화하여 비용을 줄일 수 있습니다. Opus 5.5, Sonnet 5.5, Haiku 5.5 또는 Fable 모델에서는 사고를 끌 수 없으며, 항상 확장 사고를 사용합니다.

365 365

366[고정 사고 예산](/docs/ko/model-config#adaptive-reasoning-and-fixed-thinking-budgets)이 있는 모델에서는 `MAX_THINKING_TOKENS` [환경 변수](/docs/ko/env-vars)를 설정하여 예산을 낮출 수도 있습니다(예: `MAX_THINKING_TOKENS=8000`). 적응형 추론 모델은 0이 아닌 예산을 무시하므로 대신 노력 수준을 사용하십시오.366[고정 사고 예산](/docs/ko/model-config#adaptive-reasoning-and-fixed-thinking-budgets)이 있는 모델에서는 `MAX_THINKING_TOKENS` [환경 변수](/docs/ko/env-vars)를 설정하여 예산을 낮출 수도 있습니다(예: `MAX_THINKING_TOKENS=8000`). 적응형 추론 모델은 0이 아닌 예산을 무시하므로 대신 effort 수준을 사용하십시오.

367 367

368<h3 id="delegate-verbose-operations-to-subagents">368<h3 id="delegate-verbose-operations-to-subagents">

369 자세한 작업을 subagents에 위임369 자세한 작업을 서브에이전트에 위임

370</h3>370</h3>

371 371

372테스트 실행, 문서 가져오기 또는 로그 파일 처리는 상당한 컨텍스트를 소비할 수 있습니다. 이를 [subagents](/docs/ko/sub-agents#isolate-high-volume-operations)에 위임하여 자세한 출력이 subagent의 컨텍스트에 유지되는 동안 요약만 주 대화로 반환되도록 하십시오.372테스트 실행, 문서 가져오기 또는 로그 파일 처리는 상당한 컨텍스트를 소비할 수 있습니다. 이를 [서브에이전트](/docs/ko/sub-agents#isolate-high-volume-operations)에 위임하여 자세한 출력이 서브에이전트의 컨텍스트에 유지되는 동안 요약만 주 대화로 반환되도록 하십시오.

373 373

374subagent의 자체 요청은 여전히 사용량을 소비합니다. 이에 대한 지출을 줄이려면, [subagent에 더 작은 모델을 선택](/docs/ko/sub-agents#choose-a-model)하거나 [모든 subagent를 하나의 모델에서 실행](/docs/ko/sub-agents#run-every-subagent-on-one-model)하십시오.374서브에이전트의 자체 요청은 여전히 사용량을 소비합니다. 이에 대한 지출을 줄이려면, [서브에이전트에 더 작은 모델을 선택](/docs/ko/sub-agents#choose-a-model)하거나 [모든 서브에이전트를 하나의 모델에서 실행](/docs/ko/sub-agents#run-every-subagent-on-one-model)하십시오.

375 375

376<h3 id="manage-agent-team-costs">376<h3 id="manage-agent-team-costs">

377 에이전트 팀 비용 관리377 에이전트 팀 비용 관리

378</h3>378</h3>

379 379

380에이전트 팀은 팀원이 plan mode에서 실행될 때 표준 세션보다 약 7배 더 많은 토큰을 사용합니다. 각 팀원은 자체 컨텍스트 윈도우를 유지하고 별도의 Claude 인스턴스로 실행되기 때문입니다. 팀 작업을 작고 자체 포함되도록 유지하여 팀원당 토큰 사용량을 제한하십시오. 자세한 내용은 [에이전트 팀](/docs/ko/agent-teams)을 참조하십시오.380에이전트 팀은 팀원이 플랜 모드에서 실행될 때 표준 세션보다 약 7배 더 많은 토큰을 사용합니다. 각 팀원은 자체 컨텍스트 윈도우를 유지하고 별도의 Claude 인스턴스로 실행되기 때문입니다. 팀 작업을 작고 자체 포함되도록 유지하여 팀원당 토큰 사용량을 제한하십시오. 자세한 내용은 [에이전트 팀](/docs/ko/agent-teams)을 참조하십시오.

381 381

382<h3 id="write-specific-prompts">382<h3 id="write-specific-prompts">

383 구체적인 프롬프트 작성383 구체적인 프롬프트 작성

391 391

392더 길거나 복잡한 작업의 경우, 이러한 습관은 잘못된 경로로 인한 낭비된 토큰을 피하는 데 도움이 됩니다:392더 길거나 복잡한 작업의 경우, 이러한 습관은 잘못된 경로로 인한 낭비된 토큰을 피하는 데 도움이 됩니다:

393 393

394* **복잡한 작업에 plan mode 사용**: Shift+Tab을 눌러 구현 전에 [plan mode](/docs/ko/permission-modes#analyze-before-you-edit-with-plan-mode)에 들어가십시오. Claude는 코드베이스를 탐색하고 승인을 위한 접근 방식을 제안하여, 초기 방향이 잘못되었을 때 비용이 많이 드는 재작업을 방지합니다.394* **복잡한 작업에 플랜 모드 사용**: Shift+Tab을 눌러 구현 전에 [플랜 모드](/docs/ko/permission-modes#analyze-before-you-edit-with-plan-mode)에 들어가십시오. Claude는 코드베이스를 탐색하고 승인을 위한 접근 방식을 제안하여, 초기 방향이 잘못되었을 때 비용이 많이 드는 재작업을 방지합니다.

395* **조기에 방향 수정**: Claude가 잘못된 방향으로 가기 시작하면, Escape를 눌러 즉시 중지하십시오. `/rewind`를 사용하거나 Escape를 두 번 눌러 대화 및 코드를 이전 checkpoint로 복원하십시오.395* **조기에 방향 수정**: Claude가 잘못된 방향으로 가기 시작하면, Escape를 눌러 즉시 중지하십시오. `/rewind`를 사용하거나 Escape를 두 번 눌러 대화 및 코드를 이전 체크포인트로 복원하십시오.

396* **검증 대상 제공**: 테스트 케이스를 포함하고, 스크린샷을 붙여넣거나, 프롬프트에서 예상 출력을 정의하십시오. Claude가 자신의 작업을 검증할 수 있으면, 수정을 요청해야 하기 전에 문제를 포착합니다.396* **검증 대상 제공**: 테스트 케이스를 포함하고, 스크린샷을 붙여넣거나, 프롬프트에서 예상 출력을 정의하십시오. Claude가 자신의 작업을 검증할 수 있으면, 수정을 요청해야 하기 전에 문제를 포착합니다.

397* **증분적으로 테스트**: 한 파일을 작성하고, 테스트한 다음, 계속하십시오. 이는 문제가 저렴하게 수정될 수 있을 때 조기에 포착합니다.397* **증분적으로 테스트**: 한 파일을 작성하고, 테스트한 다음, 계속하십시오. 이렇게 하면 문제를 조기에 포착할 수 있습니다.

398 398

399<h2 id="background-token-usage">399<h2 id="background-token-usage">

400 백그라운드 토큰 사용량400 백그라운드 토큰 사용량

deep-links.md +7 −1

Details

176 176

177핸들러는 감지된 터미널 에뮬레이터에서 Claude Code를 시작합니다. macOS에서 Claude Code는 가장 최근의 대화형 세션에서 터미널을 기억하고 재사용하며, iTerm2, Ghostty, kitty, Alacritty, WezTerm 및 Terminal.app을 지원합니다. Linux에서는 `$TERMINAL` 환경 변수를 준수한 다음 `x-terminal-emulator`, 그 다음 일반적인 에뮬레이터 목록을 준수합니다. Windows에서는 Windows Terminal을 선호한 다음 PowerShell, 그 다음 `cmd.exe`를 선호합니다.177핸들러는 감지된 터미널 에뮬레이터에서 Claude Code를 시작합니다. macOS에서 Claude Code는 가장 최근의 대화형 세션에서 터미널을 기억하고 재사용하며, iTerm2, Ghostty, kitty, Alacritty, WezTerm 및 Terminal.app을 지원합니다. Linux에서는 `$TERMINAL` 환경 변수를 준수한 다음 `x-terminal-emulator`, 그 다음 일반적인 에뮬레이터 목록을 준수합니다. Windows에서는 Windows Terminal을 선호한 다음 PowerShell, 그 다음 `cmd.exe`를 선호합니다.

178 178

179등록을 완전히 방지하려면 `settings.json`에서 [`disableDeepLinkRegistration`](/docs/ko/settings-reference#disabledeeplinkregistration)을 `"disable"`로 설정합니다. 조직 전체에 이를 적용하여 사용자가 다시 활성화할 수 없도록 하려면 [관리되는 설정](/docs/ko/server-managed-settings)에서 대신 설정합니다.179등록을 완전히 방지하려면 `settings.json`에서 [`disableDeepLinkRegistration`](/docs/ko/settings-reference#disabledeeplinkregistration)을 `"disable"`로 설정합니다. 조직 전체에 이를 적용하여 사용자가 다시 활성화할 수 없도록 하려면 [관리형 설정](/docs/ko/server-managed-settings)에서 대신 설정합니다. Claude Code의 `disableDeepLinkRegistration` 설정은 `claude-cli://` 링크에만 적용됩니다.

180 180

181<h2 id="open-a-vs-code-tab-instead-of-a-terminal">181<h2 id="open-a-vs-code-tab-instead-of-a-terminal">

182 터미널 대신 VS Code 탭 열기182 터미널 대신 VS Code 탭 열기

184 184

185VS Code 확장은 `vscode://anthropic.claude-code/open`에서 자체 핸들러를 등록하며, 이는 터미널 창 대신 Claude Code 편집기 탭을 엽니다. 해당 URL의 매개변수는 [다른 도구에서 VS Code 탭 시작하기](/docs/ko/vs-code#launch-a-vs-code-tab-from-other-tools)를 참조하세요.185VS Code 확장은 `vscode://anthropic.claude-code/open`에서 자체 핸들러를 등록하며, 이는 터미널 창 대신 Claude Code 편집기 탭을 엽니다. 해당 URL의 매개변수는 [다른 도구에서 VS Code 탭 시작하기](/docs/ko/vs-code#launch-a-vs-code-tab-from-other-tools)를 참조하세요.

186 186

187<h2 id="open-a-claude-desktop-session-on-an-ssh-connection">

188 SSH 연결에서 Claude Desktop 세션 열기

189</h2>

190

191Claude Desktop은 자체 `claude://` 링크를 처리합니다. SSH를 통해 원격 머신에서 Desktop 세션을 열려면 [링크에서 SSH 세션 열기](/docs/ko/desktop#open-an-ssh-session-from-a-link)를 참조하세요.

192

187<h2 id="troubleshooting">193<h2 id="troubleshooting">

188 문제 해결194 문제 해결

189</h2>195</h2>

desktop.md +59 −8

Details

108 자동 모드 사용 가능 여부108 자동 모드 사용 가능 여부

109</h4>109</h4>

110 110

111자동 모드는 Anthropic API의 모든 사용자에게 제공되며 Claude Opus 4.6 이상, Sonnet 4.6 이상, 또는 [Fable 모델](/docs/ko/model-config#work-with-fable)이 필요합니다. 조직 관리자는 [관리형 설정](#managed-settings)에서 `disableAutoMode` 키를 사용하여 자동 모드를 끌 수 있습니다.111자동 모드는 Anthropic API의 모든 사용자에게 제공되며 Claude Opus 4.6 이상, Sonnet 4.6 이상, Haiku 5.5, 또는 [Fable 모델](/docs/ko/model-config#work-with-fable)이 필요합니다. 조직 관리자는 [관리형 설정](#managed-settings)에서 `disableAutoMode` 키를 사용하여 자동 모드를 끌 수 있습니다.

112 112

113Desktop을 Google Cloud의 Agent Platform으로 라우팅하는 Enterprise 배포에서도 자동 모드는 기본적으로 사용 가능합니다. 지원되는 모델은 [Bedrock, Agent Platform, 또는 Foundry에서 자동 모드 활성화](/docs/ko/permission-modes#enable-auto-mode-on-bedrock-agent-platform-or-foundry)를 참조하세요.113Desktop을 Google Cloud의 Agent Platform으로 라우팅하는 Enterprise 배포에서도 자동 모드는 기본적으로 사용 가능합니다. 지원되는 모델은 [Bedrock, Agent Platform, 또는 Foundry에서 자동 모드 활성화](/docs/ko/permission-modes#enable-auto-mode-on-bedrock-agent-platform-or-foundry)를 참조하세요.

114 114

225 터미널에서 명령 실행하기225 터미널에서 명령 실행하기

226</h3>226</h3>

227 227

228통합 터미널을 사용하면 다른 앱으로 전환하지 않고 세션과 함께 명령을 실행할 수 있습니다. 세션 제목 표시줄에서 **Terminal**을 클릭하거나 macOS 또는 Windows에서 \*\*Ctrl+\`\*\*를 누릅니다. 터미널은 세션의 작업 디렉터리에서 열리고 Claude와 동일한 환경을 공유하므로 `npm test` 또는 `git status`와 같은 명령은 Claude가 편집하는 것과 동일한 파일을 봅니다. 두 번째 터미널 탭을 열려면 터미널 패널 헤더의 \*\*+\*\*를 클릭하거나 채팅의 폴더를 마우스 오른쪽 버튼으로 클릭하여 **Open in terminal**을 선택합니다. 터미널은 로컬 세션에서만 사용 가능합니다.228통합 터미널을 사용하면 다른 앱으로 전환하지 않고 세션과 함께 명령을 실행할 수 있습니다. 세션 제목 표시줄에서 **Terminal**을 클릭하거나 macOS 또는 Windows에서 \*\*Ctrl+\`\*\*를 누릅니다. 터미널은 세션의 작업 디렉터리에서 열리고 Claude와 동일한 환경을 공유하므로 `npm test` 또는 `git status`와 같은 명령은 Claude가 편집하는 것과 동일한 파일을 봅니다. 두 번째 터미널 탭을 열려면 터미널 패널 헤더의 \*\*+\*\*를 클릭하거나 채팅의 폴더를 마우스 오른쪽 버튼으로 클릭하여 **Open in terminal**을 선택합니다. 터미널은 로컬 및 [SSH](#ssh-sessions) 세션에서 사용 가능합니다.

229 229

230<h3 id="open-and-edit-files">230<h3 id="open-and-edit-files">

231 파일 열기 및 편집하기231 파일 열기 및 편집하기

743 743

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

745 745

746[Extended thinking](/docs/ko/model-config#extended-thinking)은 기본적으로 활성화되어 있으며, 복잡한 추론 작업의 성능을 향상시키지만 추가 토큰을 사용합니다. Anthropic API에서 생각을 비활성화하려면 로컬 환경 편집기에서 `MAX_THINKING_TOKENS`을 `0`으로 설정합니다. 이는 Opus 5.5, Sonnet 5.5 또는 Fable 모델에는 영향을 주지 않으며, 이들은 항상 extended thinking을 사용합니다. Anthropic API에서 생각을 비활성화한 상태에서 Claude Code는 [해당 조합을 허용하지 않는](/docs/ko/errors#effort-isnt-available-with-thinking-turned-off) Opus 5와 같은 모델에 더 높은 수준 대신 노력 `high`를 보냅니다.746[확장 사고](/docs/ko/model-config#extended-thinking)는 기본적으로 활성화되어 있으며, 복잡한 추론 작업의 성능을 향상시키지만 추가 토큰을 사용합니다. Anthropic API에서 사고를 끄려면 로컬 환경 편집기에서 `MAX_THINKING_TOKENS`을 `0`으로 설정합니다. 이는 Opus 5.5, Sonnet 5.5, Haiku 5.5 또는 Fable 모델에는 영향을 주지 않으며, 이들은 항상 확장 사고를 사용합니다. Anthropic API에서 사고를 끈 상태에서 Claude Code는 [해당 조합을 허용하지 않는](/docs/ko/errors#effort-isnt-available-with-thinking-turned-off) Opus 5와 같은 모델에 더 높은 수준 대신 노력 `high`를 보냅니다.

747 747

748[적응형 추론](/docs/ko/model-config#adjust-effort-level)이 있는 모델에서는 적응형 추론이 사고 깊이를 제어하기 때문에 Claude Code가 양수 `MAX_THINKING_TOKENS` 값의 숫자 자체를 무시합니다. Opus 4.6 및 Sonnet 4.6에서는 `CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING`을 `1`로 설정하여 고정 사고 예산을 사용합니다. Fable 모델, Sonnet 5 이상, Opus 4.7 이상은 항상 적응형 추론을 사용하며 고정 예산 모드가 없습니다.748[적응형 추론](/docs/ko/model-config#adjust-effort-level)이 있는 모델에서는 적응형 추론이 사고 깊이를 제어하기 때문에 Claude Code가 양수 `MAX_THINKING_TOKENS` 값의 숫자 자체를 무시합니다. Opus 4.6 및 Sonnet 4.6에서는 `CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING`을 `1`로 설정하여 고정 사고 예산을 사용합니다. Fable 모델, Sonnet 5 이상, Haiku 5.5, Opus 4.7 이상은 항상 적응형 추론을 사용하며 고정 예산 모드가 없습니다.

749 749

750<h4 id="local-sessions-on-managed-devices">750<h4 id="local-sessions-on-managed-devices">

751 관리되는 디바이스의 로컬 세션751 관리되는 디바이스의 로컬 세션

783 783

784원격 머신은 Linux 또는 macOS를 실행해야 합니다. 데스크톱은 처음 연결할 때 원격 머신에 Claude Code를 자동으로 설치합니다. 연결되면 SSH 세션은 권한 모드, 커넥터, 플러그인 및 MCP 서버를 지원합니다.784원격 머신은 Linux 또는 macOS를 실행해야 합니다. 데스크톱은 처음 연결할 때 원격 머신에 Claude Code를 자동으로 설치합니다. 연결되면 SSH 세션은 권한 모드, 커넥터, 플러그인 및 MCP 서버를 지원합니다.

785 785

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

787 링크에서 SSH 세션 열기

788</h4>

789

790`claude://code/new` 링크는 Desktop의 새 세션 페이지를 열며, SSH 연결을 지정할 수 있습니다. 이러한 링크를 런북, 대시보드 또는 위키 페이지에 넣어 두면 적절한 머신과 폴더로 설정된 상태로 Desktop을 열 수 있습니다. 이러한 링크를 제거하는 플랫폼의 경우 [링크가 클릭할 수 없는 일반 텍스트로 표시됨](/docs/ko/deep-links#the-link-renders-as-plain-text-instead-of-being-clickable)을 참조하세요.

791

792SSH 링크를 사용하려면 Claude Desktop v2.110.0 이상이 필요합니다.

793

794다음 링크는 `build.example.com`의 사용자 `dev`, 포트 2222, 폴더 `/srv/payments`를 지정하고 프롬프트를 채웁니다:

795

796```text theme={null}

797claude://code/new?ssh_host=dev%40build.example.com&ssh_port=2222&ssh_folder=/srv/payments&q=Investigate%20the%20failed%20deploy

798```

799

800SSH 링크는 다음 매개변수를 사용하며, `ssh_host`만 필수입니다:

801

802| 매개변수 | 값 |

803| :- | :- |

804| `ssh_host` | **SSH host** 필드에 쓰는 것과 같은 형식의 `host` 또는 `user@host`. 값은 `-`로 시작할 수 없으며, 호스트 부분에는 문자, 숫자, `.`, `_`, `:`, `-`만 사용할 수 있습니다 |

805| `ssh_port` | 1부터 65535까지의 포트 번호 |

806| `ssh_folder` | 원격 머신의 폴더. `/` 또는 `~/`로 시작하거나 `~`를 사용합니다 |

807| `q` | 프롬프트 상자에 들어갈 URL 인코딩된 텍스트 |

808

809`~/.ssh/config`의 별칭은 해당 항목이 있는 사용자에게만 `ssh_host`로 작동합니다. 사용자가 이미 가지고 있는 연결과 일치시키려면 링크에 해당 연결과 동일한 사용자, 호스트, 포트를 지정합니다.

810

811링크를 열면 Desktop은 연결을 선택하기 전에 확인을 요청합니다:

812

813* **이미 가지고 있는 연결**: 호스트, 사용자, 포트가 기존 연결 중 하나와 일치하면 Desktop은 해당 연결을 사용할지 묻고, 연결의 이름과 호스트, 그리고 링크에 폴더가 지정된 경우 폴더를 표시합니다.

814* **새 연결**: 그렇지 않으면 Desktop은 SSH 연결 추가 대화 상자를 엽니다. 연결을 추가하면 Desktop은 아무것도 저장하기 전에 연결할지 묻고, 링크의 호스트와 링크에 지정된 경우 포트 및 폴더를 표시합니다.

815

816확인하기 전까지 Desktop은 링크의 호스트, 포트 또는 폴더를 저장하지 않으며, 이를 사용하여 연결을 선택하거나 열지 않습니다. SSH 연결이 이미 선택되어 있는 경우 새 세션 페이지는 링크가 동일한 호스트를 지정하더라도 링크가 없을 때와 마찬가지로 해당 연결에 자체적으로 연결할 수 있습니다. 링크에는 키 파일, 비밀번호 또는 명령을 포함할 수 없습니다.

817

818누구나 링크를 작성할 수 있으므로 링크가 채운 내용을 확인하세요:

819

820* **확인하기 전**: 호스트와 폴더를 확인합니다.

821* **보내기 전**: 프롬프트와 선택된 환경을 확인합니다.

822

823Desktop은 링크가 열릴 때 보내지 않은 텍스트를 대체하여 프롬프트를 채우며, 절대 자동으로 보내지 않습니다. 프롬프트를 일반 텍스트로 처리하므로 앞에 오는 `/` 또는 `!`와 `@` 파일 멘션은 명령이나 멘션으로 작동하지 않습니다. 취소하면 프롬프트는 상자에 그대로 남아 있고 선택했던 환경은 변경되지 않습니다.

824

825링크는 [`sshHostAllowlist`](#restrict-which-ssh-hosts-users-can-connect-to)를 우회하지 않습니다. Desktop은 연결할 때 허용 목록을 확인합니다.

826

827링크가 연결에 대한 대화 상자 없이 Desktop을 여는 경우 다음 원인 중 하나를 확인하세요:

828

829* **로그아웃된 상태**: 로그인한 다음 링크를 다시 엽니다.

830* **다른 대화 상자가 열려 있음**: 해당 대화 상자를 닫은 다음 링크를 다시 엽니다.

831* **링크가 유효하지 않음**: Desktop은 수정할 내용을 알려 주는 메시지를 표시하며 프롬프트를 채우지 않습니다.

832* **Desktop이 v2.110.0보다 오래됨**: 이전 버전은 SSH 매개변수를 무시하고 프롬프트만 포함된 새 세션 페이지를 엽니다.

833* **SSH 세션이 꺼져 있음**: 관리자가 허용 목록을 빈 배열로 설정한 경우 Desktop은 SSH 링크를 거부합니다.

834

786<h4 id="pre-configure-ssh-connections-for-your-team">835<h4 id="pre-configure-ssh-connections-for-your-team">

787 팀을 위해 SSH 연결을 미리 구성합니다836 팀을 위해 SSH 연결을 미리 구성합니다

788</h4>837</h4>

805}854}

806```855```

807 856

808각 항목에는 `id`, `name`, `sshHost`가 필요합니다. `sshPort` 및 `sshIdentityFile` 필드는 선택 사항입니다. 사용자는 자신의 `~/.claude/settings.json`에 `sshConfigs`를 추가할 수도 있습니다. 이는 대화 상자를 통해 추가된 연결이 저장되는 위치입니다.857각 항목에는 `id`, `name`, `sshHost`가 필요합니다. `sshPort` 및 `sshIdentityFile` 필드는 선택 사항입니다. 사용자는 자신의 `~/.claude/settings.json`에 `sshConfigs`를 추가할 수도 있습니다.

809 858

810<h4 id="restrict-which-ssh-hosts-users-can-connect-to">859<h4 id="restrict-which-ssh-hosts-users-can-connect-to">

811 SSH 호스트 연결을 제한하여 사용자가 연결할 수 있는 호스트를 제한합니다860 SSH 호스트 연결을 제한하여 사용자가 연결할 수 있는 호스트를 제한합니다

866| `sshConfigs` | 환경 드롭다운에 나타나는 [SSH 연결](#pre-configure-ssh-connections-for-your-team)을 사전 구성합니다. 사용자는 관리형 연결을 편집하거나 삭제할 수 없습니다. |915| `sshConfigs` | 환경 드롭다운에 나타나는 [SSH 연결](#pre-configure-ssh-connections-for-your-team)을 사전 구성합니다. 사용자는 관리형 연결을 편집하거나 삭제할 수 없습니다. |

867| `sshHostAllowlist` | [SSH 세션](#restrict-which-ssh-hosts-users-can-connect-to)을 확인된 호스트명이 이러한 패턴 중 하나와 일치하는 호스트로 제한합니다. 빈 배열은 SSH 세션을 비활성화합니다. 관리형 설정에서만 읽습니다. |916| `sshHostAllowlist` | [SSH 세션](#restrict-which-ssh-hosts-users-can-connect-to)을 확인된 호스트명이 이러한 패턴 중 하나와 일치하는 호스트로 제한합니다. 빈 배열은 SSH 세션을 비활성화합니다. 관리형 설정에서만 읽습니다. |

868| `disableDesktopLocalSessions` | [장치에서 실행되는 Code 세션](#local-sessions-on-managed-devices)을 끄려면 `true`로 설정하여 다른 호스트로의 SSH 세션과 클라우드 세션을 사용 가능하게 유지합니다. 값은 JSON 부울 `true`여야 합니다. 관리형 설정에서만 읽습니다. Claude Desktop v1.37937.0 이상이 필요합니다. |917| `disableDesktopLocalSessions` | [장치에서 실행되는 Code 세션](#local-sessions-on-managed-devices)을 끄려면 `true`로 설정하여 다른 호스트로의 SSH 세션과 클라우드 세션을 사용 가능하게 유지합니다. 값은 JSON 부울 `true`여야 합니다. 관리형 설정에서만 읽습니다. Claude Desktop v1.37937.0 이상이 필요합니다. |

918| `disableSshSavedPasswords` | Desktop이 SSH 비밀번호 저장을 제안하지 않고 이전에 저장한 비밀번호를 사용하거나 표시하지 않도록 하려면 `true`로 설정합니다. 이 설정을 켜도 저장된 비밀번호는 삭제되지 않습니다. 관리형 설정에서만 읽습니다. Claude Desktop v1.49585.0 이상이 필요합니다. |

869| `managedMcpServers` | 모든 사용자에게 MCP 서버 구성을 푸시합니다. 타사(3P) Desktop 배포에서만 사용 가능합니다. 각 항목에서 `"http"`, `"sse"`, 또는 `"stdio"`의 전송, 연결 세부 정보, 그리고 선택적으로 해당 서버의 어떤 도구를 사용자가 호출할 수 있는지 제한하는 `toolPolicy` 맵을 설정합니다. 타사 배포는 관리자 콘솔 설정을 받지 않으므로 관리형 설정 파일, MDM, 또는 Claude apps gateway 정책의 [`desktop` 블록](/docs/ko/claude-apps-gateway-config#claude-desktop-overlay)을 통해 전달합니다. 게이트웨이를 통해 전달하려면 게이트웨이 서버에 Claude Code v2.1.232 이상이 필요합니다. 이것은 데스크톱 앱 자체의 키입니다. Claude Code는 다른 항목 형태를 가진 [같은 이름의 관리형 설정](/docs/ko/managed-mcp#provide-servers-through-managed-settings)을 읽습니다. |919| `managedMcpServers` | 모든 사용자에게 MCP 서버 구성을 푸시합니다. 타사(3P) Desktop 배포에서만 사용 가능합니다. 각 항목에서 `"http"`, `"sse"`, 또는 `"stdio"`의 전송, 연결 세부 정보, 그리고 선택적으로 해당 서버의 어떤 도구를 사용자가 호출할 수 있는지 제한하는 `toolPolicy` 맵을 설정합니다. 타사 배포는 관리자 콘솔 설정을 받지 않으므로 관리형 설정 파일, MDM, 또는 Claude apps gateway 정책의 [`desktop` 블록](/docs/ko/claude-apps-gateway-config#claude-desktop-overlay)을 통해 전달합니다. 게이트웨이를 통해 전달하려면 게이트웨이 서버에 Claude Code v2.1.232 이상이 필요합니다. 이것은 데스크톱 앱 자체의 키입니다. Claude Code는 다른 항목 형태를 가진 [같은 이름의 관리형 설정](/docs/ko/managed-mcp#provide-servers-through-managed-settings)을 읽습니다. |

870 920

871Desktop 세션이 어느 위치에서 실행되는지에 따라 어떤 관리형 설정이 Desktop 세션에 도달하는지가 결정됩니다. [`availableModels`](/docs/ko/model-config#restrict-model-selection)과 같은 모델 제한은 터미널 CLI와 동일한 방식으로 Desktop의 Claude Code 세션에서 적용됩니다. [사용 환경 범위](/docs/ko/model-config#surface-coverage)를 참조하세요.921Desktop 세션이 어느 위치에서 실행되는지에 따라 어떤 관리형 설정이 Desktop 세션에 도달하는지가 결정됩니다. [`availableModels`](/docs/ko/model-config#restrict-model-selection)과 같은 모델 제한은 터미널 CLI와 동일한 방식으로 Desktop의 Claude Code 세션에서 적용됩니다. [사용 환경 범위](/docs/ko/model-config#surface-coverage)를 참조하세요.

872 922

873* **이 머신의 로컬 세션**: 디스크에 배포된 관리형 설정 파일이 적용됩니다. 관리자 콘솔을 통해 원격으로 푸시된 관리형 설정도 세션이 [적격 로그인 또는 키](/docs/ko/server-managed-settings#platform-availability)로 인증할 때 Anthropic의 API에서 이러한 세션에 도달하며, 터미널 CLI와 동일한 [설정 우선순위](/docs/ko/settings#settings-precedence)를 따릅니다.923* **이 머신의 로컬 세션**: 디스크에 배포된 관리형 설정 파일이 적용됩니다. 관리자 콘솔을 통해 원격으로 푸시된 관리형 설정도 세션이 [적격 로그인 또는 키](/docs/ko/server-managed-settings#platform-availability)로 인증할 때 Anthropic의 API에서 이러한 세션에 도달하며, 터미널 CLI와 동일한 [설정 우선순위](/docs/ko/settings#settings-precedence)를 따릅니다.

874* **[클라우드 세션](#cloud-sessions)**: [서버 관리형 설정](/docs/ko/server-managed-settings)을 수신합니다. 장치 배포 파일은 Anthropic이 관리하는 VM에서 실행되므로 이들에게 도달하지 않습니다. [자체 호스팅 환경](/docs/ko/self-hosted-environments)으로 라우팅된 세션도 러너 이미지의 관리형 설정 파일을 읽습니다. [Claude Code가 관리형 소스를 결합하는 방법](/docs/ko/managed-settings#how-claude-code-combines-managed-sources)은 해당 파일이 적용되는 시기를 설명합니다.924* **[클라우드 세션](#cloud-sessions)**: [서버 관리형 설정](/docs/ko/server-managed-settings)을 수신합니다. 장치 배포 파일은 Anthropic이 관리하는 VM에서 실행되므로 이들에게 도달하지 않습니다. [자체 호스팅 환경](/docs/ko/self-hosted-environments)으로 라우팅된 세션도 러너 이미지의 관리형 설정 파일을 읽습니다. [Claude Code가 관리형 소스를 결합하는 방법](/docs/ko/managed-settings#how-claude-code-combines-managed-sources)은 해당 파일이 적용되는 시기를 설명합니다.

875* **[SSH 세션](#ssh-sessions)**: 세션은 원격 호스트에서 관리형 설정 파일을 읽습니다. Desktop 자체는 로컬 머신의 관리형 설정에서 `sshConfigs`, `sshHostAllowlist`, 및 `disableDesktopLocalSessions`을 읽습니다.925* **[SSH 세션](#ssh-sessions)**: 세션은 원격 호스트에서 관리형 설정 파일을 읽습니다. Desktop 자체는 로컬 머신의 관리형 설정에서 `sshConfigs`, `sshHostAllowlist`, `disableSshSavedPasswords`, 및 `disableDesktopLocalSessions`을 읽습니다.

876* **[Cowork](https://claude.com/docs/cowork/overview) 세션**: 이 머신의 Cowork 세션에서 Claude Code는 사용자가 Team 또는 Enterprise 계정으로 로그인할 때에도 관리자 콘솔 설정을 가져오지 않으며, Claude Desktop 구성이 `requireCoworkFullVmSandbox`를 설정하지 않는 한 머신에 배포된 정책을 읽습니다. 원격 Cowork 세션은 둘 다 수신하지 않습니다. 어떤 장치 파일이 Cowork에 도달하는지는 [정책이 적용되는 위치와 시기](/docs/ko/managed-settings#where-and-when-a-policy-applies)를 참조하고, `Bash` 및 `WebFetch` 규칙이 Cowork의 도구에 어떻게 적용되는지는 [MCP 권한 규칙](/docs/ko/permissions#mcp)을 참조하세요.926* **[Cowork](https://claude.com/docs/cowork/overview) 세션**: 이 머신의 Cowork 세션에서 Claude Code는 사용자가 Team 또는 Enterprise 계정으로 로그인할 때에도 관리자 콘솔 설정을 가져오지 않으며, Claude Desktop 구성이 `requireCoworkFullVmSandbox`를 설정하지 않는 한 머신에 배포된 정책을 읽습니다. 원격 Cowork 세션은 둘 다 수신하지 않습니다. 어떤 장치 파일이 Cowork에 도달하는지는 [정책이 적용되는 위치와 시기](/docs/ko/managed-settings#where-and-when-a-policy-applies)를 참조하고, `Bash` 및 `WebFetch` 규칙이 Cowork의 도구에 어떻게 적용되는지는 [MCP 권한 규칙](/docs/ko/permissions#mcp)을 참조하세요.

877 927

878로컬 및 SSH 세션에서 데스크톱 앱은 각 사용자의 연결된 claude.ai 커넥터를 Claude Code에 직접 전달합니다. 어떤 설정 소스 또는 파일 위치를 사용하든 MCP 설정 또는 `managed-mcp.json`은 이러한 커넥터에 도달하지 않습니다. 이러한 세션에서 커넥터의 도구를 차단하려면 조직의 [커넥터 도구 컨트롤](/docs/ko/mcp#organization-controls-on-connector-tools)을 사용하세요. [커넥터가 Claude Code에 도달하는 방법](/docs/ko/mcp#how-connectors-reach-claude-code)은 각 종류의 세션에서 어떤 설정이 커넥터를 관리하는지 보여줍니다.928로컬 및 SSH 세션에서 데스크톱 앱은 각 사용자의 연결된 claude.ai 커넥터를 Claude Code에 직접 전달합니다. 어떤 설정 소스 또는 파일 위치를 사용하든 MCP 설정 또는 `managed-mcp.json`은 이러한 커넥터에 도달하지 않습니다. 이러한 세션에서 커넥터의 도구를 차단하려면 조직의 [커넥터 도구 컨트롤](/docs/ko/mcp#organization-controls-on-connector-tools)을 사용하세요. [커넥터가 Claude Code에 도달하는 방법](/docs/ko/mcp#how-connectors-reach-claude-code)은 각 종류의 세션에서 어떤 설정이 커넥터를 관리하는지 보여줍니다.

885 장치 관리 정책935 장치 관리 정책

886</h3>936</h3>

887 937

888IT 팀은 macOS의 MDM 또는 Windows의 그룹 정책을 통해 데스크톱 앱을 관리할 수 있습니다. 사용 가능한 정책에는 Claude Code 기능 활성화 또는 비활성화, 자동 업데이트 제어, 사용자 정의 배포 URL 설정이 포함됩니다.938IT 팀은 macOS의 MDM, Windows의 그룹 정책 또는 Linux의 정책 파일을 통해 데스크톱 앱을 관리할 수 있습니다. 사용 가능한 정책에는 Claude Code 기능 활성화 또는 비활성화, macOS 및 Windows의 자동 업데이트 제어, 사용자 정의 배포 URL 설정이 포함됩니다.

889 939

890* **macOS**: Jamf 또는 Kandji와 같은 도구를 사용하여 `com.anthropic.claudefordesktop` 기본 설정 도메인을 통해 구성합니다940* **macOS**: Jamf 또는 Kandji와 같은 도구를 사용하여 `com.anthropic.claudefordesktop` 기본 설정 도메인을 통해 구성합니다

891* **Windows**: `SOFTWARE\Policies\Claude`의 레지스트리를 통해 구성합니다941* **Windows**: `SOFTWARE\Policies\Claude`의 레지스트리를 통해 구성합니다

942* **Linux**: root가 소유한 `/etc/claude-desktop/managed-settings.json` 파일을 통해 구성하며, 이 파일은 정책 키를 JSON 객체로 담습니다. root 이외의 사용자가 이 파일이나 해당 폴더에 쓸 수 있으면 Desktop은 이 파일을 거부합니다. 이 파일은 Claude Code의 [관리형 설정 파일](/docs/ko/managed-settings)과는 다른 파일입니다.

892 943

893<h3 id="network-access-requirements">944<h3 id="network-access-requirements">

894 네트워크 액세스 요구 사항945 네트워크 액세스 요구 사항

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

1093 1144

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

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

1096 1147

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

1098 1149

desktop-ios-simulator.md +1 −1

Details

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

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

94 94

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

96 96

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

98 98

env-vars.md +299 −295

Details

93}93}

94```94```

95 95

96Claude Code는 이 값들을 작성된 그대로 환경에 복사합니다. 셸이 값을 처리하지 않으므로 `~`나 `$HOME` 같은 축약 표기는 입력한 그대로 유지됩니다. `CLAUDE_CONFIG_DIR`처럼 경로를 받는 변수에는 절대 경로를 작성합니다: `"CLAUDE_CONFIG_DIR": "/home/you/.claude-work"`.

96선택한 파일은 변수가 적용되는 대상을 제어합니다:98선택한 파일은 변수가 적용되는 대상을 제어합니다:

97 99

98| 파일 | 적용 대상 |100| 파일 | 적용 대상 |

124 변수126 변수

125</h2>127</h2>

126 128

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

128 130

129<Note>131<Note>

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

131 133

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

133 135

134 * `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC`136 * `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC`

135 * `DISABLE_TELEMETRY`137 * `DISABLE_TELEMETRY`

138 * `FALLBACK_FOR_ALL_PRIMARY_MODELS`140 * `FALLBACK_FOR_ALL_PRIMARY_MODELS`

139 * `IS_DEMO`141 * `IS_DEMO`

140 142

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

142</Note>144</Note>

143 145

144| 변수 | 용도 |146| 변수 | 용도 |

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

295| `CLAUDE_CODE_ENABLE_FINE_GRAINED_TOOL_STREAMING` | Claude가 도구 호출 입력을 생성하는 동안 API에서 이를 스트리밍할지 여부를 제어합니다. 이 기능이 꺼져 있으면 긴 파일 쓰기와 같은 큰 도구 입력은 Claude가 생성을 마친 후에야 도착하므로 멈춘 것처럼 보일 수 있습니다. Anthropic API에서는 기본적으로 활성화됩니다. Amazon Bedrock과 Google Cloud's Agent Platform에서는 배포된 컨테이너가 지원하는 모델별로 활성화됩니다. 사용하지 않으려면 `0`으로 설정합니다. `ANTHROPIC_BASE_URL`, `ANTHROPIC_VERTEX_BASE_URL` 또는 `ANTHROPIC_BEDROCK_BASE_URL`을 통해 프록시로 라우팅할 때 강제로 켜려면 `1`로 설정합니다. Microsoft Foundry 및 [게이트웨이](/docs/ko/llm-gateway) 연결에서는 기본적으로 꺼져 있습니다 |297| `CLAUDE_CODE_ENABLE_FINE_GRAINED_TOOL_STREAMING` | Claude가 도구 호출 입력을 생성하는 동안 API에서 스트리밍할지 여부를 제어합니다. 이 기능이 꺼져 있으면 긴 파일 쓰기와 같은 큰 도구 입력은 Claude가 생성을 마친 후에야 도착하므로 멈춘 것처럼 보일 수 있습니다. Anthropic API에서는 기본적으로 활성화되어 있습니다. Amazon Bedrock 및 Google Cloud의 Agent Platform에서는 배포된 컨테이너가 지원하는 경우 모델별로 활성화됩니다. 옵트아웃하려면 `0`으로 설정합니다. `ANTHROPIC_BASE_URL`, `ANTHROPIC_VERTEX_BASE_URL` 또는 `ANTHROPIC_BEDROCK_BASE_URL`을 통해 프록시로 라우팅할 때 강제로 켜려면 `1`로 설정합니다. Microsoft Foundry 및 [게이트웨이](/docs/ko/llm-gateway) 연결에서는 기본적으로 꺼져 있습니다 |

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

297| `CLAUDE_CODE_ENABLE_OPUS_4_7_FAST_MODE` | [빠른 모드](/docs/ko/fast-mode) 기본값이 Opus 4.6에서 Opus 4.7로 변경되면서 v2.1.142에서 제거되었습니다 |299| `CLAUDE_CODE_ENABLE_OPUS_4_7_FAST_MODE` | [빠른 모드](/docs/ko/fast-mode) 기본값이 Opus 4.6에서 Opus 4.7로 변경된 v2.1.142에서 제거되었습니다 |

298| `CLAUDE_CODE_ENABLE_PROMPT_SUGGESTION` | 프롬프트 입력란에 회색으로 표시되는 예측인 프롬프트 제안을 끄려면 `false`로 설정합니다. `/config`의 **Prompt suggestions** 토글이 기록하는 [`promptSuggestionEnabled`](/docs/ko/settings-reference#promptsuggestionenabled) 설정보다 우선합니다. Claude Code는 또한 [계정이 사용 한도에 가까워지거나 도달하면 제안을 일시 중지합니다](/docs/ko/interactive-mode#when-claude-code-skips-suggestions). 한도에 도달할 때까지 제안을 계속 표시하려면 `true`로 설정합니다. Claude Code v2.1.238 이상이 필요합니다. [프롬프트 제안](/docs/ko/interactive-mode#prompt-suggestions)을 참조하세요 |300| `CLAUDE_CODE_ENABLE_PROMPT_SUGGESTION` | `false`로 설정하면 프롬프트 입력에 회색으로 표시되는 예측인 프롬프트 제안을 끕니다. `/config`의 **Prompt suggestions** 토글이 기록하는 [`promptSuggestionEnabled`](/docs/ko/settings-reference#promptsuggestionenabled) 설정보다 우선합니다. 또한 Claude Code는 [계정이 사용 한도에 가까워지거나 도달하면 제안을 일시 중지합니다](/docs/ko/interactive-mode#when-claude-code-skips-suggestions). 한도에 도달할 때까지 제안을 계속 켜 두려면 `true`로 설정합니다. Claude Code v2.1.238 이상이 필요합니다. [프롬프트 제안](/docs/ko/interactive-mode#prompt-suggestions)을 참조하세요 |

299| `CLAUDE_CODE_ENABLE_TASKS` | [작업 추적 도구가 있는 세션](/docs/ko/tools-reference#task-tool-availability)에서 Claude Code가 제공하는 작업 추적 도구를 선택합니다. 기본적으로 Claude Code는 Task 도구인 `TaskCreate`, `TaskUpdate`, `TaskGet`, `TaskList`를 제공합니다. 대신 레거시 `TodoWrite` 도구를 사용하려면 `0`으로 설정합니다. [작업 목록](/docs/ko/interactive-mode#task-list)을 참조하세요 |301| `CLAUDE_CODE_ENABLE_TASKS` | [해당 도구가 있는 세션](/docs/ko/tools-reference#task-tool-availability)에서 Claude Code가 제공하는 작업 추적 도구를 선택합니다. 기본적으로 Claude Code는 Task 도구인 `TaskCreate`, `TaskUpdate`, `TaskGet`, `TaskList`를 제공합니다. 대신 레거시 `TodoWrite` 도구를 사용하려면 `0`으로 설정합니다. [작업 목록](/docs/ko/interactive-mode#task-list)을 참조하세요 |

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

301| `CLAUDE_CODE_ENABLE_TODO_TOOLS` | 모든 모델에서 작업 추적 도구를 사용하려면 `1`로 설정합니다. 이 변수가 없으면 Claude Code는 [Task 도구 사용 가능 여부](/docs/ko/tools-reference#task-tool-availability)에 나열된 모델에서만 기본적으로 이 도구를 제공합니다. `CLAUDE_CODE_ENABLE_TASKS`는 여전히 Task 도구 또는 `TodoWrite`를 선택합니다. Claude Code v2.1.233 이상이 필요합니다 |303| `CLAUDE_CODE_ENABLE_TODO_TOOLS` | `1`로 설정하면 모든 모델에서 작업 추적 도구를 사용할 수 있습니다. 이 변수가 없으면 Claude Code는 [Task 도구 가용성](/docs/ko/tools-reference#task-tool-availability)에 나열된 모델에서만 기본적으로 이 도구를 제공합니다. `CLAUDE_CODE_ENABLE_TASKS`는 여전히 Task 도구 또는 `TodoWrite`를 선택합니다. Claude Code v2.1.233 이상이 필요합니다 |

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

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

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

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

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

308| `CLAUDE_CODE_FORCE_SYNC_OUTPUT` | 터미널이 DEC private mode 2026 [동기화 출력](https://gist.github.com/christianparpart/d8a62cc1ab659194337d73e399004036)을 지원하지만 자동 감지되지 않는 경우 이를 강제로 활성화하려면 `1`로 설정합니다. BSU/ESU를 구현하지만 기능 프로브에 응답하지 않는 Emacs `eat` 같은 에뮬레이터에 유용합니다. tmux에서는 효과가 없습니다. [전체 화면 렌더링](/docs/ko/fullscreen)으로 전환하는 `CLAUDE_CODE_NO_FLICKER`와 달리 렌더러를 변경하지 않습니다 |310| `CLAUDE_CODE_FORCE_SYNC_OUTPUT` | 터미널이 DEC private mode 2026 [동기화된 출력](https://gist.github.com/christianparpart/d8a62cc1ab659194337d73e399004036)을 지원하지만 자동 감지되지 않는 경우 이를 강제로 활성화하려면 `1`로 설정합니다. BSU/ESU를 구현하지만 기능 프로브에 응답하지 않는 Emacs `eat` 같은 에뮬레이터에 유용합니다. tmux에서는 효과가 없습니다. [전체 화면 렌더링](/docs/ko/fullscreen)으로 전환하는 `CLAUDE_CODE_NO_FLICKER`와 달리 이 변수는 렌더러를 변경하지 않습니다 |

309| `CLAUDE_CODE_FORK_SUBAGENT` | Claude가 직접 [포크된 서브에이전트](/docs/ko/sub-agents#fork-the-current-conversation)를 생성할 수 있게 하는 [포크 모드](/docs/ko/sub-agents#turn-fork-mode-on-or-off)를 제어하며, 포크 모드는 대화형 세션에서만 기본적으로 켜져 있습니다. `claude -p`와 Agent SDK에서도 켜려면 `1`로, 모든 종류의 세션에서 끄려면 `0`으로 설정합니다. `/subtask`는 포크 모드가 켜져 있는지 여부와 관계없이 실행할 수 있습니다. 대화형 기본값에는 Claude Code v2.1.232 이상이 필요하며, 이전 버전에서는 포크 모드를 켜려면 변수를 `1`로 설정합니다 |311| `CLAUDE_CODE_FORK_SUBAGENT` | Claude가 직접 [포크된 서브에이전트](/docs/ko/sub-agents#fork-the-current-conversation)를 생성할 수 있게 하는 [포크 모드](/docs/ko/sub-agents#turn-fork-mode-on-or-off)를 제어하며, 포크 모드는 대화형 세션에서만 기본적으로 켜져 있습니다. `claude -p`와 Agent SDK에서도 켜려면 `1`로, 모든 종류의 세션에서 끄려면 `0`으로 설정합니다. `/subtask`는 포크 모드 여부와 관계없이 실행할 수 있습니다. 대화형 기본값에는 Claude Code v2.1.232 이상이 필요하며, 이전 버전에서는 변수를 `1`로 설정해야 포크 모드가 켜집니다 |

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

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

312| `CLAUDE_CODE_GATEWAY_MODEL_DISCOVERY_TIMEOUT_MS` | `CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY`가 켜는 [게이트웨이 모델 검색](/docs/ko/llm-gateway-protocol#model-discovery) 요청의 타임아웃(밀리초)입니다(기본값: `3000`). 게이트웨이가 시작 시 `/v1/models`에 응답하는 데 3초보다 오래 걸리면 값을 높입니다. 숫자만 허용되며, `0`, 음수 및 기타 표기는 기본값을 유지합니다. Claude Code v2.1.269 이상이 필요합니다 |314| `CLAUDE_CODE_GATEWAY_MODEL_DISCOVERY_TIMEOUT_MS` | `CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY`가 켜는 [게이트웨이 모델 검색](/docs/ko/llm-gateway-protocol#model-discovery) 요청의 타임아웃(밀리초)입니다(기본값: `3000`). 게이트웨이가 시작 시 `/v1/models`에 응답하는 데 3초보다 오래 걸리는 경우 값을 늘립니다. 숫자만 허용되며, `0`, 음수 값 및 기타 표기는 기본값을 유지합니다. Claude Code v2.1.269 이상이 필요합니다 |

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

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

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

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

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

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

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

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

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

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

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

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

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

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

329| `CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH` | 메인 대화 아래에 허용되는 [서브에이전트 계층](/docs/ko/sub-agents#let-subagents-spawn-their-own-subagents) 수입니다 (기본값: 3). 기본값에서는 서브에이전트가 자체 서브에이전트를 생성할 수 있으며, 세 번째 계층의 서브에이전트는 더 이상 생성할 수 없습니다. 중첩을 끄려면 `1`로 설정합니다. v2.1.217부터 v2.1.218까지는 기본값이 1이었으므로 제한을 높이지 않으면 서브에이전트가 자체 서브에이전트를 생성할 수 없었으며, v2.1.219에서 기본값이 3으로 높아졌습니다. 숫자로 된 양의 정수를 허용하며, 그 외의 값은 무시되므로 제한을 조정할 수는 있지만 제거할 수는 없습니다. Claude Code v2.1.217 이상이 필요합니다 |331| `CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH` | 메인 대화 아래에 허용되는 [서브에이전트 계층](/docs/ko/sub-agents#let-subagents-spawn-their-own-subagents) 수입니다 (기본값: 3). 기본값에서는 서브에이전트가 자체 서브에이전트를 생성할 수 있으며, 세 번째 계층의 서브에이전트는 더 이상 생성할 수 없습니다. 중첩을 끄려면 `1`로 설정합니다. v2.1.217부터 v2.1.218까지는 기본값이 1이었으므로 제한을 높이지 않으면 서브에이전트가 자체 서브에이전트를 생성할 수 없었으며, v2.1.219에서 기본값이 3으로 높아졌습니다. 숫자로만 된 양의 정수를 허용하며, 그 외 값은 무시되므로 제한을 조정할 수는 있지만 제거할 수는 없습니다. Claude Code v2.1.217 이상이 필요합니다 |

330| `CLAUDE_CODE_MAX_TOOL_USE_CONCURRENCY` | 병렬로 실행할 수 있는 읽기 전용 도구 및 서브에이전트의 최대 수입니다(기본값: 10). 값이 높을수록 병렬 처리가 늘어나지만 더 많은 리소스를 소비합니다 |332| `CLAUDE_CODE_MAX_TOOL_USE_CONCURRENCY` | 병렬로 실행할 수 있는 읽기 전용 도구 및 서브에이전트의 최대 수입니다(기본값: 10). 값이 클수록 병렬 처리가 늘어나지만 더 많은 리소스를 사용합니다 |

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

332| `CLAUDE_CODE_MAX_WEB_SEARCHES_PER_SESSION` | 한 세션에서 수행할 수 있는 [WebSearch](/docs/ko/tools-reference#websearch-tool-behavior) 호출 총수의 상한입니다(기본값: 200). Claude가 상한에 도달하면 이후 WebSearch 호출은 이미 수집한 정보로 계속 진행하라는 알림을 반환합니다. 최대값 없이 양의 정수를 허용합니다. 그 외의 값은 무시되고 기본값이 적용되므로 상한을 높일 수는 있지만 끌 수는 없습니다. Claude Code v2.1.212 이상이 필요합니다 |334| `CLAUDE_CODE_MAX_WEB_SEARCHES_PER_SESSION` | 한 세션에서 수행할 수 있는 [WebSearch](/docs/ko/tools-reference#websearch-tool-behavior) 호출의 총 수 상한입니다(기본값: 200). Claude가 상한에 도달하면 이후 WebSearch 호출은 이미 수집한 정보로 계속 진행하라는 알림을 반환합니다. 상한이 없는 양의 정수를 허용합니다. 그 외 값은 무시되고 기본값이 적용되므로 상한을 높일 수는 있지만 끌 수는 없습니다. Claude Code v2.1.212 이상이 필요합니다 |

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

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

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

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

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

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

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

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

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

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

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

345| `CLAUDE_CODE_OAUTH_SCOPES` | 리프레시 토큰 발급 시 사용된 공백으로 구분된 OAuth 범위입니다(예: `"user:profile user:inference user:sessions:claude_code"`). `CLAUDE_CODE_OAUTH_REFRESH_TOKEN`이 설정된 경우 필요합니다 |347| `CLAUDE_CODE_OAUTH_SCOPES` | 새로 고침 토큰 발급 시 사용된 공백으로 구분된 OAuth 범위입니다(예: `"user:profile user:inference user:sessions:claude_code"`). `CLAUDE_CODE_OAUTH_REFRESH_TOKEN`이 설정된 경우 필요합니다 |

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

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

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

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

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

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

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

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

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

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

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

357| `CLAUDE_CODE_PLUGIN_GIT_TIMEOUT_MS` | 플러그인 마켓플레이스를 복제하거나 새로 고치기 위한 타임아웃(밀리초)입니다(기본값: 120000). 큰 저장소나 느린 네트워크 연결의 경우 이 값을 늘립니다. [Git clone timed out](/docs/ko/plugins/troubleshooting#git-clone-timed-out-after-120s)을 참조하세요 |359| `CLAUDE_CODE_PLUGIN_DIR_WATCH` | mod의 파일이 변경될 때 Claude Code가 [mod](/docs/ko/plugins/mods/overview)를 다시 로드할지 여부를 제어합니다. 다시 로드는 `--plugin-dir`로 디렉터리에서 로드하는 mod에 적용되며, 대화형 세션에서는 기본적으로 켜져 있습니다. 비대화형 세션에서도 켜려면 `1`로, 모든 세션에서 끄려면 `0`으로 설정합니다. Claude Code v2.1.287 이상이 필요합니다. [mod 설정 및 환경 변수](/docs/ko/plugins/mods/reference#settings-and-environment-variables)를 참조하세요 |

358| `CLAUDE_CODE_PLUGIN_KEEP_MARKETPLACE_ON_FAILURE` | 마켓플레이스 새로 고침이 원격에 연결하거나 인증할 수 없을 때 다시 복제를 시도하지 않고 기존 마켓플레이스 체크아웃을 계속 사용하려면 `1`로 설정합니다. 다시 복제해도 같은 방식으로 실패할 오프라인 또는 에어갭 환경에서 유용합니다. [오프라인 환경에서 마켓플레이스 업데이트 실패](/docs/ko/plugins/troubleshooting#marketplace-updates-keep-failing-offline)를 참조하세요 |360| `CLAUDE_CODE_PLUGIN_GIT_TIMEOUT_MS` | 플러그인 마켓플레이스를 복제하거나 새로 고칠 때의 타임아웃(밀리초)입니다(기본값: 120000). 큰 저장소나 느린 네트워크 연결에서는 이 값을 늘립니다. [Git clone timed out](/docs/ko/plugins/troubleshooting#git-clone-timed-out-after-120s)을 참조하세요 |

359| `CLAUDE_CODE_PLUGIN_PREFER_HTTPS` | GitHub `owner/repo` 약식 소스를 SSH 대신 HTTPS로 복제하려면 `1`로 설정합니다. 플러그인 설치 및 업데이트와 `/plugin marketplace add` 및 `update`에 적용됩니다. CI 러너, 컨테이너 또는 `github.com`용 SSH 키가 구성되지 않은 모든 환경에서 유용합니다 |361| `CLAUDE_CODE_PLUGIN_KEEP_MARKETPLACE_ON_FAILURE` | `1`로 설정하면 마켓플레이스 새로 고침이 원격에 연결하거나 인증할 수 없을 때 재복제 시도를 건너뛰고 기존 마켓플레이스 체크아웃을 계속 사용합니다. 재복제가 같은 방식으로 실패하는 오프라인 또는 에어갭 환경에서 유용합니다. [오프라인 환경에서 마켓플레이스 업데이트 실패](/docs/ko/plugins/troubleshooting#marketplace-updates-keep-failing-offline)를 참조하세요 |

360| `CLAUDE_CODE_PLUGIN_SEED_DIR` | 하나 이상의 읽기 전용 플러그인 시드 디렉터리 경로로, Unix에서는 `:`, Windows에서는 `;`로 구분합니다. 미리 채워진 플러그인 디렉터리를 컨테이너 이미지에 번들로 포함할 때 사용합니다. Claude Code는 시작 시 이러한 디렉터리에서 마켓플레이스를 등록하고, 다시 복제하지 않고 미리 캐시된 플러그인을 사용합니다. [컨테이너용 플러그인 미리 채우기](/docs/ko/plugins/org#seed-containers-and-ci)를 참조하세요 |362| `CLAUDE_CODE_PLUGIN_PREFER_HTTPS` | `1`로 설정하면 GitHub `owner/repo` 축약형 소스를 SSH 대신 HTTPS로 복제합니다. 플러그인 설치 및 업데이트, `/plugin marketplace add` 및 `update`에 적용됩니다. CI 러너, 컨테이너 또는 `github.com`용 SSH 키가 구성되지 않은 모든 환경에서 유용합니다 |

361| `CLAUDE_CODE_POWERSHELL_RESPECT_EXECUTION_POLICY` | 도구 호출, 훅, 상태줄 명령을 위해 PowerShell을 생성할 때 Claude Code가 `-ExecutionPolicy Bypass`를 전달하지 않고 대신 머신의 유효 실행 정책을 따르도록 하려면 `1`로 설정합니다. 기본적으로 Claude Code는 프로세스 범위에서 실행 정책을 우회하므로 기본값이 Restricted인 Windows 설치에서도 `.ps1` 스크립트와 모듈 가져오기가 작동합니다. 이 설정과 관계없이 프로세스 범위 우회는 그룹 정책 `MachinePolicy` 또는 `UserPolicy`를 재정의하지 않습니다 |363| `CLAUDE_CODE_PLUGIN_SEED_DIR` | 하나 이상의 읽기 전용 플러그인 시드 디렉터리 경로로, Unix에서는 `:`, Windows에서는 `;`로 구분합니다. 미리 채워진 플러그인 디렉터리를 컨테이너 이미지에 번들로 포함할 때 사용합니다. Claude Code는 시작 시 이 디렉터리에서 마켓플레이스를 등록하고 재복제 없이 미리 캐시된 플러그인을 사용합니다. [컨테이너용 플러그인 미리 채우기](/docs/ko/plugins/org#seed-containers-and-ci)를 참조하세요 |

362| `CLAUDE_CODE_PRINT_BG_WAIT_CEILING_MS` | `-p` 플래그를 사용하는 [비대화형 모드](/docs/ko/headless#background-tasks-at-exit)에서 마지막 턴 이후 서브에이전트 및 워크플로 같은 백그라운드 작업을 유휴 대기하는 시간의 상한(밀리초)입니다. Claude가 백그라운드 결과를 처리하기 위해 턴을 수행할 때마다 유휴 대기가 다시 시작됩니다. 기본값: `600000`, 즉 10분. 유휴 대기가 상한에 도달하면 Claude Code는 남은 백그라운드 작업을 기다리지 않고 종료합니다. 무기한 대기하려면 `0`으로 설정합니다. 이 상한은 일반 백그라운드 셸에 적용되는 5초 유예 기간과는 별개입니다. Claude Code v2.1.182 이상이 필요합니다 |364| `CLAUDE_CODE_POWERSHELL_RESPECT_EXECUTION_POLICY` | `1`로 설정하면 Claude Code가 도구 호출, 훅, 상태줄 명령을 위해 PowerShell을 생성할 때 `-ExecutionPolicy Bypass`를 전달하지 않고 대신 머신의 유효 실행 정책을 따릅니다. 기본적으로 Claude Code는 기본값이 Restricted인 Windows 설치에서 `.ps1` 스크립트와 모듈 가져오기가 작동하도록 프로세스 범위에서 실행 정책을 우회합니다. 프로세스 범위 우회는 이 설정과 관계없이 그룹 정책 `MachinePolicy` 또는 `UserPolicy`를 재정의하지 않습니다 |

363| `CLAUDE_CODE_PROCESS_WRAPPER` | [에이전트 뷰](/docs/ko/agent-view) 세션을 호스팅하는 백그라운드 서비스처럼 Claude Code가 자체 바이너리에서 시작하는 프로세스를 `/opt/corp/launcher` 같은 argv 접두사로 지정한 회사 런처를 통해 실행합니다. 분리된 백그라운드 서비스가 상속할 수 있도록 셸 export가 아닌 사용자 설정 또는 [관리형 설정](/docs/ko/managed-settings)의 `env` 블록에서 설정합니다. 프로젝트 및 로컬 설정에서는 설정할 수 없습니다. Claude Code v2.1.210 이상이 필요한 [`processWrapper` 설정](/docs/ko/settings-reference#processwrapper)과 같으며, 둘 다 설정된 경우 이 변수가 우선합니다. VS Code 확장 프로그램은 자체 `claudeProcessWrapper` 설정을 통해 런처를 별도로 구성합니다. Windows에서는 무시됩니다. 값 형식, 런처가 적용되는 범위, 런처가 충족해야 하는 계약은 [회사 런처 뒤에서 Claude Code 실행](/docs/ko/corporate-launcher)을 참조하세요. Claude Code v2.1.208 이상이 필요합니다 |365| `CLAUDE_CODE_PRINT_BG_WAIT_CEILING_MS` | `-p` 플래그를 사용하는 [비대화형 모드](/docs/ko/headless#background-tasks-at-exit)에서 마지막 턴 이후 서브에이전트 및 워크플로 같은 백그라운드 작업을 유휴 대기하는 시간의 상한(밀리초)입니다. 유휴 대기는 Claude가 백그라운드 결과를 처리하기 위해 턴을 진행할 때마다 다시 시작됩니다. 기본값: `600000`, 즉 10분. 유휴 대기가 상한에 도달하면 Claude Code는 남은 백그라운드 작업을 기다리지 않고 종료합니다. 무기한 대기하려면 `0`으로 설정합니다. 이 상한은 일반 백그라운드 셸에 적용되는 5초 유예 기간과는 별개입니다. Claude Code v2.1.182 이상이 필요합니다 |

364| `CLAUDE_CODE_PROJECT_DIR_NAME` | `CLAUDE_CONFIG_DIR`과 함께 설정하여, 작업 디렉터리 경로에서 파생된 이름 대신 Claude Code가 해당 세션의 트랜스크립트와 자동 메모리를 저장하는 `projects/` 디렉터리 이름을 선택합니다. 예를 들어 `CLAUDE_CONFIG_DIR=/srv/tenant-a CLAUDE_CODE_PROJECT_DIR_NAME=work claude`로 Claude Code를 시작하면 `/srv/tenant-a/projects/work/` 아래에 저장됩니다. `CLAUDE_CONFIG_DIR`이 설정되지 않으면 Claude Code는 이 변수를 무시하며, `claude`를 시작하는 환경에서만 읽고 [설정 파일 `env` 블록](#in-settings-files)에서는 읽지 않습니다. [프로젝트 디렉터리 이름 직접 지정](/docs/ko/sessions#name-the-project-directory-yourself)을 참조하세요. Claude Code v2.1.234 이상이 필요합니다 |366| `CLAUDE_CODE_PROCESS_WRAPPER` | [에이전트 뷰](/docs/ko/agent-view) 세션을 호스팅하는 백그라운드 서비스처럼 Claude Code가 자체 바이너리에서 시작하는 프로세스를 `/opt/corp/launcher` 같은 argv 접두사로 지정한 기업 런처를 통해 실행합니다. 분리된 백그라운드 서비스가 상속하도록 셸 export가 아닌 사용자 설정 또는 [관리형 설정](/docs/ko/managed-settings)의 `env` 블록에서 설정합니다. 프로젝트 및 로컬 설정에서는 설정할 수 없습니다. Claude Code v2.1.210 이상이 필요한 [`processWrapper` 설정](/docs/ko/settings-reference#processwrapper)과 동일하며, 둘 다 설정된 경우 이 변수가 우선합니다. VS Code 확장은 `claudeProcessWrapper` 설정을 통해 자체 런처를 별도로 구성합니다. Windows에서는 무시됩니다. 값 형식, 런처가 다루는 범위, 런처가 충족해야 하는 계약은 [기업 런처 뒤에서 Claude Code 실행](/docs/ko/corporate-launcher)을 참조하세요. Claude Code v2.1.208 이상이 필요합니다 |

365| `CLAUDE_CODE_PROMPT_CACHE_TTL` | Claude Code가 허용하는 유일한 값인 `5m` 또는 `1h`로 설정하여 메인 대화의 [프롬프트 캐시 TTL](/docs/ko/prompt-caching#cache-lifetime)을 선택합니다. 메인 대화에는 대화형, `-p`, SDK 턴과 이와 함께 인라인으로 실행되는 도우미가 포함됩니다. `promptCacheTtl` 설정 및 `ENABLE_PROMPT_CACHING_1H`보다 우선하며, `FORCE_PROMPT_CACHING_5M`이 이를 재정의합니다. API는 1시간 캐시 쓰기에 더 높은 요율을 청구합니다. Claude Code v2.1.242 이상이 필요합니다 |367| `CLAUDE_CODE_PROJECT_DIR_NAME` | `CLAUDE_CONFIG_DIR`과 함께 설정하면 작업 디렉터리 경로에서 파생된 이름 대신, Claude Code가 해당 세션의 트랜스크립트와 자동 메모리를 저장하는 `projects/` 디렉터리 이름을 선택할 수 있습니다. 예를 들어 `CLAUDE_CONFIG_DIR=/srv/tenant-a CLAUDE_CODE_PROJECT_DIR_NAME=work claude`로 Claude Code를 시작하면 `/srv/tenant-a/projects/work/` 아래에 저장됩니다. Claude Code는 `CLAUDE_CONFIG_DIR`이 설정되지 않은 경우 이 변수를 무시하며, [설정 파일 `env` 블록](#in-settings-files)이 아닌 `claude`를 시작하는 환경에서만 읽습니다. [프로젝트 디렉터리 이름 직접 지정](/docs/ko/sessions#name-the-project-directory-yourself)을 참조하세요. Claude Code v2.1.234 이상이 필요합니다 |

366| `CLAUDE_CODE_PROPAGATE_TRACEPARENT` | `ANTHROPIC_BASE_URL`이 사용자 지정 프록시를 가리킬 때 W3C 추적 컨텍스트를 전파하려면 `1`로 설정합니다. 전파 대상은 모델 및 HTTP MCP 요청의 `traceparent` 헤더와 Bash, PowerShell, 훅 하위 프로세스의 `TRACEPARENT` 환경 변수입니다. 기본적으로 전파는 Anthropic API에 직접 연결된 경우에만 활성화됩니다. v2.1.152에서 추가되었습니다. [트레이스(베타)](/docs/ko/monitoring-usage#traces-beta)를 참조하세요 |368| `CLAUDE_CODE_PROMPT_CACHE_TTL` | Claude Code가 허용하는 유일한 값인 `5m` 또는 `1h`로 설정하여 메인 대화의 [프롬프트 캐시 TTL](/docs/ko/prompt-caching#cache-lifetime)을 선택합니다. 메인 대화에는 대화형, `-p`, SDK 턴과 이들과 함께 인라인으로 실행되는 헬퍼가 포함됩니다. `promptCacheTtl` 설정과 `ENABLE_PROMPT_CACHING_1H`보다 우선하며, `FORCE_PROMPT_CACHING_5M`이 이를 재정의합니다. API는 1시간 캐시 쓰기에 더 높은 요금을 청구합니다. Claude Code v2.1.242 이상이 필요합니다 |

367| `CLAUDE_CODE_PROVIDER_MANAGED_BY_HOST` | Claude Code를 내장하고 모델 공급자 라우팅을 대신 관리하는 호스트 플랫폼이 설정합니다. 설정되면 Claude Code는 설정 파일의 `CLAUDE_CODE_USE_BEDROCK`, `ANTHROPIC_BASE_URL`, `ANTHROPIC_API_KEY` 같은 공급자 선택, 엔드포인트, 인증 변수를 무시하므로 사용자 설정이 호스트의 라우팅을 재정의할 수 없습니다. 또한 Claude Code는 [관리형 설정](/docs/ko/managed-settings)의 `model`, `fallbackModel`, `modelOverrides` 같은 모델 선택 키를 어떤 관리 소스에서 전달되든 무시하므로, 호스트의 모델 구성이 오래된 관리형 모델 고정보다 우선합니다. 또한 Claude Code는 관리형 `env` 블록의 `ANTHROPIC_MODEL` 및 `ANTHROPIC_DEFAULT_*_MODEL` 계열 같은 모델 선택 변수도 무시합니다. 관리형 설정의 [`availableModels`](/docs/ko/model-config#restrict-model-selection) 허용 목록은 호스트가 자체 목록을 제공하지 않는 한 계속 적용됩니다. 또한 Claude Code는 Amazon Bedrock, Claude Platform on AWS, Google Cloud's Agent Platform, Microsoft Foundry 같은 타사 공급자에서 적용하는 자동 텔레메트리 옵트아웃을 건너뛰므로, 텔레메트리는 표준 `DISABLE_TELEMETRY` 옵트아웃을 따릅니다. [API 공급자별 기본 동작](/docs/ko/data-usage#default-behaviors-by-api-provider)을 참조하세요 |369| `CLAUDE_CODE_PROPAGATE_TRACEPARENT` | `ANTHROPIC_BASE_URL`이 사용자 지정 프록시를 가리킬 때 W3C 트레이스 컨텍스트를 전파하려면 `1`로 설정합니다. 전파 대상에는 모델 및 HTTP MCP 요청의 `traceparent` 헤더와 Bash, PowerShell, 훅 하위 프로세스의 `TRACEPARENT` 환경 변수가 포함됩니다. 기본적으로 전파는 Anthropic API에 직접 연결된 경우에만 활성화됩니다. v2.1.152에서 추가되었습니다. [트레이스(베타)](/docs/ko/monitoring-usage#traces-beta)를 참조하세요 |

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

369| `CLAUDE_CODE_REMOTE` | Claude Code가 [클라우드 세션](/docs/ko/claude-code-on-the-web)으로 실행될 때 자동으로 `true`로 설정됩니다. 훅이나 설정 스크립트에서 이 값을 읽어 클라우드 세션인지 감지합니다 |371| `CLAUDE_CODE_PROXY_RESOLVES_HOSTS` | `1`로 설정하면 호출자 대신 프록시가 DNS 확인을 수행하도록 허용합니다. 프록시가 호스트 이름 확인을 처리해야 하는 환경을 위한 옵트인입니다 |

370| `CLAUDE_CODE_REMOTE_SESSION_ID` | [클라우드 세션](/docs/ko/claude-code-on-the-web)에서 현재 세션의 ID로 자동 설정됩니다. 이 값을 읽어 세션 트랜스크립트로 돌아가는 링크를 구성합니다. [출력을 세션에 다시 연결](/docs/ko/cloud-environments#link-output-back-to-the-session)을 참조하세요 |372| `CLAUDE_CODE_REMOTE` | Claude Code가 [클라우드 세션](/docs/ko/claude-code-on-the-web)으로 실행될 때 자동으로 `true`로 설정됩니다. 훅이나 설정 스크립트에서 이 값을 읽어 클라우드 세션에서 실행 중인지 감지합니다 |

371| `CLAUDE_CODE_RESTRICTED` | [`--restricted`](/docs/ko/cli-reference#cli-flags)를 전달하는 것과 같이 제한 모드로 세션을 시작하려면 `1`로 설정합니다. Claude Code는 설정 파일의 `env` 블록에 있는 이 변수를 무시합니다. Claude Code v2.1.248 이상이 필요합니다 |373| `CLAUDE_CODE_REMOTE_SESSION_ID` | [클라우드 세션](/docs/ko/claude-code-on-the-web)에서 현재 세션의 ID로 자동 설정됩니다. 이 값을 읽어 세션 트랜스크립트로 돌아가는 링크를 만듭니다. [출력을 세션에 다시 연결](/docs/ko/cloud-environments#link-output-back-to-the-session)을 참조하세요 |

372| `CLAUDE_CODE_RESUME_INTERRUPTED_TURN` | 이전 세션이 턴 도중에 종료된 경우 자동으로 재개하려면 `1`로 설정합니다. SDK 모드에서 사용되며, SDK가 프롬프트를 다시 보내지 않아도 모델이 계속 진행합니다. 끄려면 변수를 설정 해제하거나 `0`으로 설정합니다. VS Code 채팅 패널의 경우 [다시 로드 후 대화 계속하기](/docs/ko/vs-code#continue-conversations-after-a-reload)를 참조하세요 |374| `CLAUDE_CODE_RESTRICTED` | `1`로 설정하면 [`--restricted`](/docs/ko/cli-reference#cli-flags)를 전달하는 것과 마찬가지로 제한 모드에서 세션을 시작합니다. Claude Code는 설정 파일의 `env` 블록에 있는 이 변수를 무시합니다. Claude Code v2.1.248 이상이 필요합니다 |

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

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

375| `CLAUDE_CODE_RETRY_WATCHDOG` | 평가 하네스, CI 작업, 원격 워커 같은 무인 세션에서 `1`로 설정합니다. `429` 및 `529` 용량 오류를 `CLAUDE_CODE_MAX_RETRIES`회 시도 후 실패하는 대신 무기한 재시도합니다. 표준 속도 요청이 지출 한도나 소진된 사용량 크레딧을 보고하는 `429`를 받으면, 일정에 따라 재설정되는 [게이트웨이 지출 상한](/docs/ko/errors#spend-limit-reached)에서 온 경우라도 Claude Code는 즉시 실패합니다. v2.1.239 이전에는 워치독이 이를 무기한 재시도했습니다. 빠른 모드 요청의 경우 [속도 제한 처리](/docs/ko/fast-mode#handle-rate-limits)를 참조하세요. 워치독은 시도 사이에 최대 5분까지, 또는 응답에 속도 제한 재설정 시간이 포함된 경우 제한이 재설정될 때까지 대기하므로, 사용 한도에 도달한 세션은 남은 기간이 지날 때까지 기다립니다. v2.1.199 이상에서는 서버 오류, 타임아웃, 연결 끊김 같은 기타 일시적 오류에 대한 기본 재시도 횟수도 약 3시간의 백오프에 해당하는 300으로 높이며, `CLAUDE_CODE_MAX_RETRIES`를 명시적으로 설정한 경우 15인 상한을 제거합니다. Claude Code v2.1.186 이상이 필요합니다 |377| `CLAUDE_CODE_RESUME_PROMPT` | `CLAUDE_CODE_RESUME_INTERRUPTED_TURN`이 프롬프트를 다시 보내는 대신 중단된 턴을 계속할 때, 또는 `-p`로 [지연된 도구 호출](/docs/ko/hooks#defer-a-tool-call-for-later)을 재개할 때 Claude Code가 Claude에게 보내는 계속 메시지를 재정의합니다. 기본값은 `Continue from where you left off.`입니다. 빈 문자열은 기본값을 사용합니다 |

376| `CLAUDE_CODE_SAFE_MODE` | 안전 모드로 시작하려면 `1`로 설정합니다. 손상된 구성의 문제 해결을 위해 CLAUDE.md, 스킬, 플러그인, 훅, MCP 서버, 사용자 지정 명령 및 에이전트, 출력 스타일, 워크플로, 사용자 지정 테마, 사용자 지정 키보드 단축키, 상태줄 및 파일 제안 명령, LSP 서버, 자동 메모리가 로드되지 않습니다. 정책으로 구성된 훅, 상태줄, 파일 제안 명령을 포함하여 관리형 설정 정책은 계속 적용되지만, 관리형 플러그인, 관리형 스킬, 관리형 CLAUDE.md, 정책으로 구성된 MCP 서버는 적용되지 않습니다. [`--safe-mode`](/docs/ko/cli-reference#cli-flags)를 전달하는 것과 같습니다. 직접 생성된 자식 프로세스는 이 변수를 상속합니다 |378| `CLAUDE_CODE_RETRY_WATCHDOG` | eval 하네스, CI 작업, 원격 워커 같은 무인 세션에서 `1`로 설정합니다. `429` 및 `529` 용량 오류를 `CLAUDE_CODE_MAX_RETRIES`회 시도 후 실패하는 대신 무기한 재시도합니다. 표준 속도 요청이 지출 한도나 소진된 사용량 크레딧을 보고하는 `429`를 받으면, 일정에 따라 재설정되는 [게이트웨이 지출 한도](/docs/ko/errors#spend-limit-reached)에서 온 것이라도 Claude Code는 즉시 실패합니다. v2.1.239 이전에는 워치독이 이러한 오류를 무기한 재시도했습니다. 빠른 모드 요청의 경우 [속도 제한 처리](/docs/ko/fast-mode#handle-rate-limits)를 참조하세요. 워치독은 시도 사이에 최대 5분까지 백오프하거나, 응답에 속도 제한 재설정 시간이 포함된 경우 제한이 재설정될 때까지 대기하므로, 사용 한도에 도달한 세션은 남은 기간 동안 대기합니다. v2.1.199 이상에서는 서버 오류, 타임아웃, 끊긴 연결 같은 기타 일시적 오류의 기본 재시도 횟수도 약 3시간의 백오프에 해당하는 300으로 늘리며, `CLAUDE_CODE_MAX_RETRIES`를 명시적으로 설정한 경우 15회 상한을 제거합니다. Claude Code v2.1.186 이상이 필요합니다 |

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

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

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

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

381| `CLAUDE_CODE_SESSION_ID` | Bash 및 PowerShell 도구 하위 프로세스, [훅 명령](/docs/ko/hooks) 하위 프로세스, stdio [MCP 서버](/docs/ko/mcp) 하위 프로세스에서 현재 세션 ID로 자동 설정됩니다. Bash, PowerShell, 훅의 경우 이 값은 훅 JSON 입력의 `session_id` 필드와 일치하며 `/clear` 시 업데이트됩니다. MCP 서버 하위 프로세스는 생성될 때의 ID를 유지합니다. `--resume <session-id>`에서는 재개된 ID를 받으므로 훅 및 Bash와 일치합니다. 명시적 ID 없이 `--continue` 또는 `--resume`을 사용하면 대신 초기 시작 ID를 받을 수 있습니다. 스크립트와 외부 도구를 이를 실행한 Claude Code 세션과 연결하는 데 사용합니다 |383| `CLAUDE_CODE_SESSIONEND_HOOKS_TIMEOUT_MS` | [SessionEnd](/docs/ko/hooks#sessionend) 훅의 시간 예산(밀리초)을 재정의합니다. 이 값은 자체 `timeout`을 설정하지 않은 각 훅의 타임아웃이기도 합니다. 세션 종료, `/clear`, 대화형 `/resume`을 통한 세션 전환에 적용됩니다. 기본 예산은 1.5초이며, 설정 파일에 구성된 가장 높은 훅별 `timeout`까지 최대 60초로 자동 증가합니다. 플러그인이 제공하는 훅의 타임아웃은 예산을 늘리지 않습니다 |

382| `CLAUDE_CODE_SHELL` | Claude Code가 Bash 도구 명령을 실행하는 데 사용하는 셸을 설정합니다. `/opt/homebrew/bin/bash`처럼 `bash` 또는 `zsh` 바이너리 경로를 허용합니다. `fish` 같은 다른 셸은 지원되지 않습니다. 값이 작동하는 `bash` 또는 `zsh` 경로가 아니면 Claude Code는 이를 무시하고 자동 감지로 폴백합니다. 자동 감지는 `$SHELL`이 `bash` 또는 `zsh`를 가리키면 이를 사용하고, 그렇지 않으면 `PATH`와 표준 설치 위치에서 처음 발견되는 작동하는 `zsh`, 그다음 `bash`를 선택합니다 |384| `CLAUDE_CODE_SESSION_ID` | Bash 및 PowerShell 도구 하위 프로세스, [훅 명령](/docs/ko/hooks) 하위 프로세스, stdio [MCP 서버](/docs/ko/mcp) 하위 프로세스에서 현재 세션 ID로 자동 설정됩니다. Bash, PowerShell, 훅의 경우 이 값은 훅 JSON 입력의 `session_id` 필드와 일치하며 `/clear` 시 업데이트됩니다. MCP 서버 하위 프로세스는 생성될 때의 ID를 유지합니다. `--resume <session-id>`에서는 재개된 ID를 받아 훅 및 Bash와 일치합니다. 명시적 ID 없이 `--continue` 또는 `--resume`을 사용하면 대신 초기 시작 ID를 받을 수 있습니다. 스크립트 및 외부 도구를 이를 실행한 Claude Code 세션과 연관시키는 데 사용합니다 |

383| `CLAUDE_CODE_SHELL_PREFIX` | Claude Code가 생성하는 셸 명령을 감싸는 명령 접두사입니다. 대상은 Bash 도구 호출, [훅](/docs/ko/hooks) 명령, [상태줄](/docs/ko/statusline) 명령, stdio [MCP 서버](/docs/ko/mcp) 시작 명령입니다. PowerShell 훅과 exec 형식 훅은 접두사 없이 실행됩니다. 로깅이나 감사에 유용합니다. `/path/to/logger.sh` 같은 단순 실행 파일 경로를 설정하면 각 명령이 `/path/to/logger.sh '<command>'`로 실행됩니다. 래퍼는 명령줄을 `$1`에 셸 인용된 단일 인수로 받으므로, `exec bash -c "$1"`처럼 셸로 `$1`을 다시 평가해야 합니다. `$1`을 단순 실행 파일 경로로 취급하면 `npx -y <package>` 같은 인수를 전달하는 stdio MCP 서버가 작동하지 않습니다. Bash 도구 호출의 경우 `$1`에는 Claude가 실행한 명령만이 아니라 환경 설정을 포함하여 Claude Code가 조립한 전체 셸 호출이 들어 있습니다 |385| `CLAUDE_CODE_SHELL` | Claude Code가 Bash 도구 명령을 실행하는 데 사용하는 셸을 설정합니다. `bash` 또는 `zsh` 바이너리 경로를 허용합니다(예: `/opt/homebrew/bin/bash`). `fish` 같은 다른 셸은 지원되지 않습니다. 값이 작동하는 `bash` 또는 `zsh` 경로가 아니면 Claude Code는 이를 무시하고 자동 감지로 폴백합니다. 자동 감지는 `$SHELL`이 `bash` 또는 `zsh`를 가리키면 이를 사용하고, 그렇지 않으면 `PATH`와 표준 설치 위치에서 처음 발견되는 작동하는 `zsh`, 그다음 `bash`를 선택합니다 |

384| `CLAUDE_CODE_SIMPLE` | 최소한의 시스템 프롬프트와 Bash, 파일 읽기, 파일 편집 도구만으로 실행하려면 `1`로 설정합니다. `--mcp-config`의 MCP 도구는 계속 사용할 수 있습니다. 훅, 스킬, 사용자 지정 명령, 서브에이전트, 설치된 플러그인, MCP 서버, 자동 메모리, CLAUDE.md의 자동 검색을 비활성화합니다. `--add-dir`로 전달한 디렉터리의 스킬은 계속 로드됩니다. OAuth 토큰과 키체인 자격 증명을 읽지 않으므로 Anthropic 인증은 `ANTHROPIC_API_KEY` 또는 `--settings`의 `apiKeyHelper`를 통해 제공되어야 합니다. [`--bare`](/docs/ko/headless#start-faster-with-bare-mode)를 전달하는 것과 같습니다 |386| `CLAUDE_CODE_SHELL_PREFIX` | Claude Code가 생성하는 셸 명령을 래핑하는 명령 접두사입니다. 대상에는 Bash 도구 호출, [훅](/docs/ko/hooks) 명령, [상태줄](/docs/ko/statusline) 명령, stdio [MCP 서버](/docs/ko/mcp) 시작 명령이 포함됩니다. PowerShell 훅과 exec 형식 훅은 접두사 없이 실행됩니다. 로깅 또는 감사에 유용합니다. `/path/to/logger.sh` 같은 단순 실행 파일 경로를 설정하면 각 명령이 `/path/to/logger.sh '<command>'`로 실행됩니다. 래퍼는 명령줄을 `$1`에 셸 인용된 단일 인수로 받으므로, 래퍼는 `exec bash -c "$1"`처럼 셸로 `$1`을 다시 평가해야 합니다. `$1`을 단순 실행 파일 경로로 취급하면 `npx -y <package>` 같은 인수를 전달하는 stdio MCP 서버가 작동하지 않습니다. Bash 도구 호출의 경우 `$1`에는 Claude가 실행한 명령뿐만 아니라 환경 설정을 포함하여 Claude Code가 조립한 전체 셸 호출이 들어 있습니다 |

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

388| `CLAUDE_CODE_SIMPLE_SYSTEM_PROMPT` | `1`로 설정하면 모든 모델에서 더 짧은 시스템 프롬프트와 축약된 도구 설명을 사용합니다. `0`, `false`, `no` 또는 `off`로 설정하면 실험이나 서버 구성에 의해 활성화되는 모델에서도 옵트아웃합니다. 전체 도구 세트, 훅, MCP 서버, CLAUDE.md 검색은 계속 활성화됩니다 |

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

533| `VERTEX_REGION_CLAUDE_HAIKU_5_5` | Google Cloud's Agent Platform 사용 시 Claude Haiku 5.5의 리전을 재정의합니다. v2.1.293에서 추가되었습니다 |

530 534

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

532 536

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

534 538

535<h2 id="what-the-subprocess-environment-scrub-removes">539<h2 id="what-the-subprocess-environment-scrub-removes">

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

errors.md +4 −5

Details

131| `403` with `x-deny-reason: host_not_allowed` in a cloud or routine session | [네트워크](#host-not-allowed-in-a-cloud-session) |131| `403` with `x-deny-reason: host_not_allowed` in a cloud or routine session | [네트워크](#host-not-allowed-in-a-cloud-session) |

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

409 410

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

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

2299 2300

2300**할 일:**2301**할 일:**

2301 2302

2302* 붙여넣기 전에 이미지 크기를 조정합니다. API는 단일 이미지의 경우 가장 긴 변 기준 최대 8000픽셀, 많은 이미지가 컨텍스트에 있을 때는 2000픽셀까지의 이미지를 허용합니다.2303* 붙여넣기 전에 이미지 크기를 조정합니다. API는 단일 이미지의 경우 가장 긴 변 기준 최대 8000픽셀, 컨텍스트에 이미지가 20개를 초과할 때는 3000픽셀까지의 이미지를 허용합니다.

2303* 전체 화면 대신 관련 영역만 더 좁게 스크린샷을 찍습니다.2304* 전체 화면 대신 관련 영역만 더 좁게 스크린샷을 찍습니다.

2304 2305

2305<h3 id="unable-to-resize-image">2306<h3 id="unable-to-resize-image">

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

2906```2907```

2907 2908

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

~~2909~~

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

2911 2910

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

fast-mode.md +1 −1

Details

88 88

89빠른 모드 가격은 전체 1M 토큰 컨텍스트 윈도우에 걸쳐 고정입니다. 표준 Opus 요금을 비교하려면 [Claude 가격 책정 참고](https://platform.claude.com/docs/ko/about-claude/pricing)를 참조하십시오.89빠른 모드 가격은 전체 1M 토큰 컨텍스트 윈도우에 걸쳐 고정입니다. 표준 Opus 요금을 비교하려면 [Claude 가격 책정 참고](https://platform.claude.com/docs/ko/about-claude/pricing)를 참조하십시오.

90 90

91대화 중간에 빠른 모드를 처음 활성화하면 전체 대화 컨텍스트에 대해 전체 빠른 모드 캐시되지 않은 입력 토큰 가격을 지불합니다. 대화가 진행될수록 비용이 더 많이 들므로, 처음부터 빠른 모드를 활성화하는 것이 더 저렴합니다. 비용은 대화당 한 번만 적용되므로, 나중에 빠른 모드를 끄고 다시 켜도 반복되지 않습니다. 메커니즘에 대해서는 [빠른 모드가 프롬프트 캐시와 상호작용하는 방식](/docs/ko/prompt-caching#turning-on-fast-mode)을 참조하십시오.91대화에서 빠른 모드를 처음 활성화하면 전체 대화 컨텍스트에 대해 빠른 모드의 캐시되지 않은 입력 토큰 전체 가격을 지불합니다. 대화가 깊어질수록 이 비용이 커지므로, 대화를 시작할 때 빠른 모드를 활성화하면 요금이 가장 적습니다. 비용은 대화당 한 번만 적용되므로, 나중에 빠른 모드를 끄고 다시 켜도 반복되지 않습니다. 메커니즘에 대해서는 [빠른 모드가 프롬프트 캐시와 상호작용하는 방식](/docs/ko/prompt-caching#turning-on-fast-mode)을 참조하십시오.

92 92

93<h3 id="see-where-fast-mode-spend-appears">93<h3 id="see-where-fast-mode-spend-appears">

94 빠른 모드 지출이 표시되는 위치 확인94 빠른 모드 지출이 표시되는 위치 확인

feature-availability.md +5 −5

Details

220</table>220</table>

221 221

222<span id="fn1" style={{display: 'block', position: 'relative', top: '-120px'}} /><sup>1</sup> Google Cloud의 Agent Platform에서는 Claude 4 모델 이상에서 웹 검색을 사용할 수 있습니다.<br />222<span id="fn1" style={{display: 'block', position: 'relative', top: '-120px'}} /><sup>1</sup> Google Cloud의 Agent Platform에서는 Claude 4 모델 이상에서 웹 검색을 사용할 수 있습니다.<br />

223<span id="fn2" style={{display: 'block', position: 'relative', top: '-120px'}} /><sup>2</sup> 이러한 제공자에서 자동 모드는 Claude Sonnet 5 이상, Opus 4.7 이상, Fable 모델만 지원합니다. [자동 모드 구성](/docs/ko/auto-mode-config)을 참조하십시오. 이러한 제공자의 세션이 시작되는 권한 모드는 어떤 모드인지에 대해서는 [세션이 시작되는 모드](/docs/ko/permission-modes#which-mode-a-session-starts-in)를 참조하십시오. v2.1.158부터 v2.1.206까지 이러한 제공자의 자동 모드는 `CLAUDE_CODE_ENABLE_AUTO_MODE=1` 설정도 필요했습니다. v2.1.207은 이 요구 사항을 제거했습니다.<br />223<span id="fn2" style={{display: 'block', position: 'relative', top: '-120px'}} /><sup>2</sup> 이러한 제공자에서 자동 모드는 Claude Sonnet 5 이상, Opus 4.7 이상, Haiku 5.5, Fable 모델만 지원합니다. [자동 모드 구성](/docs/ko/auto-mode-config)을 참조하십시오. 이러한 제공자의 세션이 시작되는 권한 모드는 어떤 모드인지에 대해서는 [세션이 시작되는 모드](/docs/ko/permission-modes#which-mode-a-session-starts-in)를 참조하십시오. v2.1.158부터 v2.1.206까지 이러한 제공자의 자동 모드는 `CLAUDE_CODE_ENABLE_AUTO_MODE=1` 설정도 필요했습니다. v2.1.207은 이 요구 사항을 제거했습니다.<br />

224<span id="fn3" style={{display: 'block', position: 'relative', top: '-120px'}} /><sup>3</sup> 클라우드 제공자와의 계약에 따릅니다.<br />224<span id="fn3" style={{display: 'block', position: 'relative', top: '-120px'}} /><sup>3</sup> 클라우드 제공자와의 계약에 따릅니다.<br />

225<span id="fn4" style={{display: 'block', position: 'relative', top: '-120px'}} /><sup>4</sup> 대시보드 및 API만 해당합니다. [기여도 메트릭](/docs/ko/analytics#enable-contribution-metrics)은 claude.ai Team 또는 Enterprise 조직이 필요합니다.<br />225<span id="fn4" style={{display: 'block', position: 'relative', top: '-120px'}} /><sup>4</sup> 대시보드 및 API만 해당합니다. [기여도 메트릭](/docs/ko/analytics#enable-contribution-metrics)은 claude.ai Team 또는 Enterprise 조직이 필요합니다.<br />

226<span id="fn5" style={{display: 'block', position: 'relative', top: '-120px'}} /><sup>5</sup> macOS 및 Linux에서 Claude Code v2.1.224 이상 필요합니다. WSL 2 내부의 Linux 포함. 네이티브 Windows에서는 Claude Code v2.1.234 이상 필요합니다. API 키 인증을 사용하면 메시징은 같은 머신만 가능합니다. Amazon Bedrock, AWS의 Claude Platform, Google Cloud의 Agent Platform, Microsoft Foundry에서는 메시징이 같은 머신만 가능하며 Claude Code v2.1.248 이상 필요합니다. Claude는 [Remote Control](/docs/ko/remote-control)에 연결된 세션에서만 [웹의 Claude Code](/docs/ko/claude-code-on-the-web) 세션과 다른 머신의 세션을 찾을 수 있습니다. 연결하려면 claude.ai 로그인과 다른 [Remote Control 요구 사항](/docs/ko/remote-control#requirements)이 필요합니다. [다른 머신의 세션 메시징](/docs/ko/cross-session-messaging#message-sessions-on-other-machines)을 참조하십시오.226<span id="fn5" style={{display: 'block', position: 'relative', top: '-120px'}} /><sup>5</sup> macOS 및 Linux(WSL 2 내부의 Linux 포함)에서 Claude Code v2.1.224 이상이 필요합니다. 네이티브 Windows에서는 Claude Code v2.1.234 이상이 필요합니다. API 키 인증을 사용하면 메시징은 같은 머신에서만 가능합니다. Amazon Bedrock, AWS의 Claude Platform, Google Cloud의 Agent Platform, Microsoft Foundry에서는 메시징이 같은 머신에서만 가능하며 Claude Code v2.1.248 이상이 필요합니다. Claude는 [Remote Control](/docs/ko/remote-control)에 연결된 세션에서만 [클라우드 세션](/docs/ko/claude-code-on-the-web)과 다른 머신의 세션을 찾을 수 있습니다. 연결하려면 claude.ai 로그인과 다른 [Remote Control 요구 사항](/docs/ko/remote-control#requirements)이 필요합니다. [다른 머신의 세션 메시징](/docs/ko/cross-session-messaging#message-sessions-on-other-machines)을 참조하십시오.

227 227

228<Note>228<Note>

229 [LLM 게이트웨이](/docs/ko/llm-gateway)를 통해 인증하는 경우 기능 가용성은 게이트웨이가 전달하는 기본 제공자와 일치합니다. 단, Claude Code 자체가 끄는 기능은 제외됩니다. `ANTHROPIC_BASE_URL`이 `api.anthropic.com` 이외의 호스트를 가리킬 때마다 Claude Code는 게이트웨이가 전달하는 것과 관계없이 [Remote Control](/docs/ko/remote-control#requirements) 및 [서버 관리 설정](/docs/ko/server-managed-settings#platform-availability)과 같은 기능을 끕니다. [Advisor](/docs/ko/advisor)와 같은 일부 Anthropic 전용 기능은 게이트웨이가 요청을 Anthropic API로 그대로 전달하는 경우에만 작동합니다.229 [LLM 게이트웨이](/docs/ko/llm-gateway)를 통해 인증하는 경우 기능 가용성은 게이트웨이가 전달하는 기본 제공자와 일치합니다. 단, Claude Code 자체가 끄는 기능은 제외됩니다. `ANTHROPIC_BASE_URL`이 `api.anthropic.com` 이외의 호스트를 가리킬 때마다 Claude Code는 게이트웨이가 전달하는 것과 관계없이 [Remote Control](/docs/ko/remote-control#requirements) 및 [서버 관리 설정](/docs/ko/server-managed-settings#platform-availability)과 같은 기능을 끕니다. [Advisor](/docs/ko/advisor)와 같은 일부 Anthropic 전용 기능은 게이트웨이가 요청을 Anthropic API로 그대로 전달하는 경우에만 작동합니다.

244 **부분 지원:**244 **부분 지원:**

245 245

246 * [Desktop](/docs/ko/desktop): [Claude Desktop on 3P](https://claude.com/docs/third-party/claude-desktop/overview)를 통해서만246 * [Desktop](/docs/ko/desktop): [Claude Desktop on 3P](https://claude.com/docs/third-party/claude-desktop/overview)를 통해서만

247 * [자동 모드](/docs/ko/auto-mode-config): Sonnet 5 이상, Opus 4.7 이상, Fable 모델만247 * [자동 모드](/docs/ko/auto-mode-config): Sonnet 5 이상, Opus 4.7 이상, Haiku 5.5, Fable 모델만

248 * [교차 세션 메시징](/docs/ko/cross-session-messaging): 이 머신의 세션 간만 <sup><a href="#fn5">5</a></sup>248 * [교차 세션 메시징](/docs/ko/cross-session-messaging): 이 머신의 세션 간만 <sup><a href="#fn5">5</a></sup>

249 * [Zero Data Retention](/docs/ko/zero-data-retention): AWS 계약에 따름249 * [Zero Data Retention](/docs/ko/zero-data-retention): AWS 계약에 따름

250 250

270 270

271 * [Desktop](/docs/ko/desktop): [관리되는 설정](https://claude.com/docs/third-party/claude-desktop/configuration) 또는 [Claude Desktop on 3P](https://claude.com/docs/third-party/claude-desktop/overview)를 통해271 * [Desktop](/docs/ko/desktop): [관리되는 설정](https://claude.com/docs/third-party/claude-desktop/configuration) 또는 [Claude Desktop on 3P](https://claude.com/docs/third-party/claude-desktop/overview)를 통해

272 * [웹 검색](/docs/ko/tools-reference#websearch-tool-behavior): Claude 4 모델 이상272 * [웹 검색](/docs/ko/tools-reference#websearch-tool-behavior): Claude 4 모델 이상

273 * [자동 모드](/docs/ko/auto-mode-config): Sonnet 5 이상, Opus 4.7 이상, Fable 모델만273 * [자동 모드](/docs/ko/auto-mode-config): Sonnet 5 이상, Opus 4.7 이상, Haiku 5.5, Fable 모델만

274 * [교차 세션 메시징](/docs/ko/cross-session-messaging): 이 머신의 세션 간만 <sup><a href="#fn5">5</a></sup>274 * [교차 세션 메시징](/docs/ko/cross-session-messaging): 이 머신의 세션 간만 <sup><a href="#fn5">5</a></sup>

275 * [Zero Data Retention](/docs/ko/zero-data-retention): Google Cloud 계약에 따름275 * [Zero Data Retention](/docs/ko/zero-data-retention): Google Cloud 계약에 따름

276 276

284 284

285 * [Desktop](/docs/ko/desktop): [Claude Desktop on 3P](https://claude.com/docs/third-party/claude-desktop/overview)를 통해서만285 * [Desktop](/docs/ko/desktop): [Claude Desktop on 3P](https://claude.com/docs/third-party/claude-desktop/overview)를 통해서만

286 * [웹 검색](/docs/ko/tools-reference#websearch-tool-behavior): [Anthropic에서 호스팅되는 배포](https://platform.claude.com/docs/en/build-with-claude/claude-in-microsoft-foundry#hosting-options)만286 * [웹 검색](/docs/ko/tools-reference#websearch-tool-behavior): [Anthropic에서 호스팅되는 배포](https://platform.claude.com/docs/en/build-with-claude/claude-in-microsoft-foundry#hosting-options)만

287 * [자동 모드](/docs/ko/auto-mode-config): Sonnet 5 이상, Opus 4.7 이상, Fable 모델만287 * [자동 모드](/docs/ko/auto-mode-config): Sonnet 5 이상, Opus 4.7 이상, Haiku 5.5, Fable 모델만

288 * [교차 세션 메시징](/docs/ko/cross-session-messaging): 이 머신의 세션 간만 <sup><a href="#fn5">5</a></sup>288 * [교차 세션 메시징](/docs/ko/cross-session-messaging): 이 머신의 세션 간만 <sup><a href="#fn5">5</a></sup>

289 * [Zero Data Retention](/docs/ko/zero-data-retention): Azure 계약에 따름289 * [Zero Data Retention](/docs/ko/zero-data-retention): Azure 계약에 따름

290 290

glossary.md +12 −12

Details

130 130

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

132 132

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

134 134

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

136 136

196 Effort level196 Effort level

197</h3>197</h3>

198 198

199각 턴에서 모델이 적응형 추론을 사용할지 여부와 얼마나 사용할지를 제어하는 설정입니다. 더 높은 노력은 더 많은 사고 토큰과 더 깊은 추론을 의미합니다. 더 낮은 노력은 더 빠르고 저렴합니다. Effort는 Fable 모델, Opus 4.6 이상 및 Sonnet 4.6 이상에서 지원됩니다.199적응형 추론을 제어하는 설정으로, 모델이 각 단계에서 사고할지 여부와 얼마나 사고할지를 스스로 결정하도록 합니다. effort가 높을수록 더 많은 사고 토큰과 더 깊은 추론을 의미하며, effort가 낮을수록 더 빠르고 저렴합니다. Effort는 Fable 모델, Opus 4.6 이상, Sonnet 4.6 이상 및 Haiku 5.5에서 지원됩니다.

200 200

201자세히 알아보기: [노력 수준 조정](/docs/ko/model-config#adjust-effort-level)201자세히 알아보기: [노력 수준 조정](/docs/ko/model-config#adjust-effort-level)

202 202

380 Sandboxing380 Sandboxing

381</h3>381</h3>

382 382

383Bash 도구에 대한 OS 수준 파일 시스템 및 네트워크 격리입니다. 명령은 미리 정의한 경계 내에서 실행되므로 Claude는 명령별 승인 프롬프트 없이 자유롭게 작업할 수 있습니다. 샌드박싱은 [권한 규칙](#permission-rule)과 별개의 계층입니다.383Bash 도구에 대한 OS 수준 파일 시스템 및 네트워크 격리입니다. 명령은 미리 정의한 경계 내에서 실행되므로 Claude는 명령별 승인 프롬프트 없이 그 안에서 자유롭게 작업할 수 있습니다. 샌드박싱은 [권한 규칙](#permission-rule)과 별개의 계층입니다.

384 384

385자세히 알아보기: [샌드박싱](/docs/ko/sandboxing)385자세히 알아보기: [샌드박싱](/docs/ko/sandboxing)

386 386

388 Session388 Session

389</h3>389</h3>

390 390

391현재 디렉토리에 연결된 대화이며, 자신의 독립적인 [컨텍스트 윈도우](#context-window)를 가집니다. 세션은 `claude -c`로 재개할 수 있고, `--fork-session`으로 포크하여 새 세션 ID 아래에 기록을 보존하거나, 터미널 전체에서 병렬로 실행할 수 있습니다. `/clear`를 실행하면 새 세션이 시작됩니다. 이전 세션은 저장된 상태로 유지되며 `/resume`을 통해 사용 가능합니다. 각 세션의 기록은 `~/.claude/projects/` 아래에 저장됩니다.391현재 디렉토리에 연결된 대화이며, 자신의 독립적인 [컨텍스트 윈도우](#context-window)를 가집니다. 세션은 `claude -c`로 재개할 수 있고, `--fork-session`으로 포크하여 새 세션 ID 아래에 기록을 보존하거나, 여러 터미널에서 병렬로 실행할 수 있습니다. `/clear`를 실행하면 새 세션이 시작됩니다. 이전 세션은 저장된 상태로 유지되며 `/resume`을 통해 사용할 수 있습니다. 각 세션의 트랜스크립트는 `~/.claude/projects/` 아래에 저장됩니다.

392 392

393자세히 알아보기: [세션으로 작업](/docs/ko/how-claude-code-works#work-with-sessions)393자세히 알아보기: [세션으로 작업](/docs/ko/how-claude-code-works#work-with-sessions)

394 394

396 Settings layers396 Settings layers

397</h3>397</h3>

398 398

399Claude Code가 구성을 읽는 계층 구조이며, 우선 순위 순서는 높음에서 낮음입니다: [관리 정책](#managed-settings), 명령줄 인수, `.claude/settings.local.json`의 로컬 설정, `.claude/settings.json`의 프로젝트 설정, 그 다음 `~/.claude/settings.json`의 사용자 설정. 배열은 계층 전체에서 병합됩니다. 스칼라는 더 높은 계층에서 더 낮은 계층을 재정의합니다. [설정 우선 순위](/docs/ko/settings#settings-precedence)를 참조하십시오.399Claude Code가 구성을 읽는 계층 구조이며, 우선순위가 높은 것부터 낮은 순서로 다음과 같습니다: [관리형 정책](#managed-settings), `--settings` 플래그로 전달하는 설정, `.claude/settings.local.json`의 로컬 설정, `.claude/settings.json`의 프로젝트 설정, 그 다음 `~/.claude/settings.json`의 사용자 설정. 배열은 계층 전체에서 병합되며, 스칼라는 더 높은 계층의 값이 더 낮은 계층의 값을 재정의합니다. [설정 우선순위](/docs/ko/settings#settings-precedence)를 참조하십시오.

400 400

401자세히 알아보기: [설정 파일](/docs/ko/settings#where-settings-live)401자세히 알아보기: [설정 파일](/docs/ko/settings#where-settings-live)

402 402

404 Skill404 Skill

405</h3>405</h3>

406 406

407지침, 지식 또는 Claude가 도구 키트에 추가하는 워크플로우를 포함하는 `SKILL.md` 파일입니다. Claude는 관련이 있을 때 스킬을 자동으로 로드하거나 `/skill-name`으로 직접 호출합니다. 스킬은 Agent Skills 개방형 표준을 따릅니다. Claude Code는 호출 제어 및 서브에이전트 실행으로 확장합니다.407지침, 지식 또는 Claude가 도구 키트에 추가하는 워크플로를 포함하는 `SKILL.md` 파일입니다. Claude는 관련이 있을 때 스킬을 자동으로 로드하며, 사용자가 `/skill-name`으로 직접 호출할 수도 있습니다. 스킬은 Agent Skills 개방형 표준을 따르며, Claude Code는 이를 호출 제어 및 서브에이전트 실행으로 확장합니다.

408 408

409스킬은 사용자 정의 명령의 권장 후속입니다. `.claude/commands/deploy.md`의 파일과 `.claude/skills/deploy/SKILL.md`의 파일은 모두 `/deploy`를 생성하고 동일하게 작동합니다. 기존 명령 파일은 계속 작동합니다.409스킬은 사용자 정의 명령의 권장 후속 기능입니다. `.claude/commands/deploy.md`의 파일과 `.claude/skills/deploy/SKILL.md`의 파일은 모두 `/deploy`를 생성하고 동일하게 작동합니다. 기존 명령 파일은 계속 작동합니다.

410 410

411자세히 알아보기: [스킬로 Claude 확장](/docs/ko/skills)411자세히 알아보기: [스킬로 Claude 확장](/docs/ko/skills)

412 412

424 Surface424 Surface

425</h3>425</h3>

426 426

427Claude Code에 액세스하는 모든 장소입니다: CLI, VS Code, JetBrains, Desktop 또는 claude.ai. 모든 표면은 동일한 엔진을 공유합니다. 컴퓨터의 세션은 로컬 CLAUDE.md, 설정 및 스킬을 읽습니다. [클라우드 세션](/docs/ko/cloud-environments#what-carries-over-from-your-setup)은 저장소의 새로운 클론에서 시작되며 컴퓨터의 `~/.claude/`를 읽지 않습니다. Slack 및 Chrome 확장 프로그램은 표면 자체가 아니라 표면에 연결하는 통합입니다.427Claude Code에 액세스하는 모든 장소입니다: CLI, VS Code, JetBrains, Desktop 또는 claude.ai. 모든 사용 환경은 동일한 엔진을 공유합니다. 컴퓨터의 세션은 로컬 CLAUDE.md, 설정 및 스킬을 읽습니다. [클라우드 세션](/docs/ko/cloud-environments#what-carries-over-from-your-setup)은 저장소의 새로운 클론에서 시작되며 컴퓨터의 `~/.claude/`를 읽지 않습니다. Slack 및 Chrome 확장 프로그램은 사용 환경 자체가 아니라 사용 환경에 연결되는 통합입니다.

428 428

429자세히 알아보기: [플랫폼 및 통합](/docs/ko/platforms)429자세히 알아보기: [플랫폼 및 통합](/docs/ko/platforms)

430 430

434 434

435Claude Code가 모든 요청에서 대화 앞에 보내는 지침으로, Claude가 도구를 사용하는 방법, 안전하게 작동하는 방법 및 응답 형식을 지정합니다. `--append-system-prompt`로 시스템 프롬프트에 추가하거나 `--system-prompt`로 바꿀 수 있습니다. 시스템 프롬프트는 [프롬프트 캐시](/docs/ko/prompt-caching#how-the-cache-is-organized)의 첫 번째 계층입니다.435Claude Code가 모든 요청에서 대화 앞에 보내는 지침으로, Claude가 도구를 사용하는 방법, 안전하게 작동하는 방법 및 응답 형식을 지정합니다. `--append-system-prompt`로 시스템 프롬프트에 추가하거나 `--system-prompt`로 바꿀 수 있습니다. 시스템 프롬프트는 [프롬프트 캐시](/docs/ko/prompt-caching#how-the-cache-is-organized)의 첫 번째 계층입니다.

436 436

437[CLAUDE.md](#claude-md) 파일과 [출력 스타일](#output-style)의 지침은 시스템 프롬프트의 일부가 아닙니다. Claude Code는 [시스템 알림](#system-reminder)으로 대화에 전달합니다.437[CLAUDE.md](#claude-md) 파일과 [출력 스타일](#output-style)의 지침은 시스템 프롬프트의 일부가 아닙니다. Claude Code는 이를 [시스템 리마인더](#system-reminder)로 대화에 전달합니다.

438 438

439자세히 알아보기: [시스템 프롬프트 플래그](/docs/ko/cli-reference#system-prompt-flags)439자세히 알아보기: [시스템 프롬프트 플래그](/docs/ko/cli-reference#system-prompt-flags)

440 440

442 System reminder442 System reminder

443</h3>443</h3>

444 444

445Claude Code가 [에이전트 하네스](#agentic-harness)로서 대화에 추가하여 Claude에 컨텍스트를 제공하는 메시지입니다. 시스템 알림을 직접 보내지 않습니다. Claude Code는 세션이 실행될 때 삽입합니다. 예를 들어 세션이 시작될 때, 훅이 텍스트를 반환할 때 또는 파일이 디스크에서 변경될 때입니다. Claude는 메시지와 함께 시스템 알림을 읽습니다. 다음 모두 Claude에 시스템 알림으로 도달합니다:445Claude Code가 [에이전틱 하네스](#agentic-harness)로서 대화에 추가하여 Claude에 컨텍스트를 제공하는 메시지입니다. 시스템 리마인더는 사용자가 직접 보내지 않습니다. Claude Code는 세션이 실행되는 동안 이를 삽입합니다. 예를 들어 세션이 시작될 때, 훅이 텍스트를 반환할 때 또는 파일이 디스크에서 변경될 때입니다. Claude는 사용자의 메시지와 함께 시스템 리마인더를 읽습니다. 다음은 모두 시스템 리마인더로 Claude에 전달됩니다:

446 446

447* [CLAUDE.md](#claude-md) 파일447* [CLAUDE.md](#claude-md) 파일

448* [출력 스타일](#output-style)의 지침448* [출력 스타일](#output-style)의 지침

449* [훅](#hook)이 `additionalContext`로 반환하는 텍스트449* [훅](#hook)이 `additionalContext`로 반환하는 텍스트

450* 사용 가능한 [스킬](#skill)의 목록450* 사용 가능한 [스킬](#skill)의 목록

451* Claude가 이전에 읽은 파일이 디스크에서 변경되었다는 메모451* Claude가 이전에 읽은 파일이 디스크에서 변경되었다는 메모

452* 커밋 및 풀 요청 속성 라인452* 커밋 및 풀 리퀘스트 속성 라인

453 453

454로깅된 API 요청에서 시스템 알림은 사용자 메시지 내의 `<system-reminder>` 태그로 래핑되거나 일부 모델에서는 `system` 역할을 가진 별도의 메시지로 나타납니다.454로깅된 API 요청에서 시스템 리마인더는 사용자 메시지 내의 `<system-reminder>` 태그로 래핑되거나 일부 모델에서는 `system` 역할을 가진 별도의 메시지로 나타납니다.

455 455

456자세히 알아보기: [시스템 프롬프트 외부에서 Claude Code가 추가하는 컨텍스트](/docs/ko/agent-sdk/modifying-system-prompts#context-claude-code-adds-outside-the-system-prompt)456자세히 알아보기: [시스템 프롬프트 외부에서 Claude Code가 추가하는 컨텍스트](/docs/ko/agent-sdk/modifying-system-prompts#context-claude-code-adds-outside-the-system-prompt)

457 457

google-vertex-ai.md +2 −2

Details

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

211```211```

212 212

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

214 214

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

216 216

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

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

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

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

370 370

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

372 372

headless.md +31 −21

Details

219 서브에이전트 메시지 따라가기219 서브에이전트 메시지 따라가기

220</h4>220</h4>

221 221

222[서브에이전트](/docs/ko/sub-agents)의 메시지는 스트림에 `assistant` 및 `user` 메시지로 나타나며, 이들의 `parent_tool_use_id` 필드는 서브에이전트를 생성한 도구 호출의 ID입니다. 주 대화의 메시지는 해당 필드에 `null`을 포함합니다.222[서브에이전트](/docs/ko/sub-agents)의 메시지와 [서브에이전트에서 실행되는](/docs/ko/skills#run-skills-in-a-subagent) 스킬의 메시지는 스트림에 `assistant` 및 `user` 메시지로 나타납니다. 이들의 `parent_tool_use_id` 필드는 각 메시지가 어느 실행에 속하는지 나타냅니다. 주 대화의 메시지는 해당 필드에 `null`을 포함합니다.

223 223

224[포그라운드](/docs/ko/sub-agents#run-subagents-in-foreground-or-background)에서 실행 중인 서브에이전트의 첫 번째 메시지는 이를 구동하는 프롬프트를 전달하는 `user` 메시지입니다. 첫 번째 메시지 이후 Claude Code는 다음을 내보냅니다:224포크된 스킬 또는 [포그라운드](/docs/ko/sub-agents#run-subagents-in-foreground-or-background)에서 실행 중인 서브에이전트의 첫 번째 메시지는 이를 구동하는 프롬프트 또는 스킬 콘텐츠를 전달하는 `user` 메시지입니다. 첫 번째 메시지 이후 Claude Code는 다음을 내보냅니다:

225 225

226* **기본값**: 서브에이전트의 `tool_use` 및 `tool_result` 블록.226* **기본값**: 실행의 `tool_use` 및 `tool_result` 블록.

227* **[`--forward-subagent-text`](/docs/ko/cli-reference#cli-flags) 또는 [`CLAUDE_CODE_FORWARD_SUBAGENT_TEXT`](/docs/ko/env-vars) 사용**: 서브에이전트의 텍스트 및 사고 블록도 포함되므로 각 서브에이전트의 트랜스크립트를 재구성할 수 있습니다. 이는 Claude Code v2.1.211 이상이 필요합니다.227* **[`--forward-subagent-text`](/docs/ko/cli-reference#cli-flags) 또는 [`CLAUDE_CODE_FORWARD_SUBAGENT_TEXT`](/docs/ko/env-vars) 사용**: 실행의 텍스트 및 사고 블록도 포함되므로 각 실행의 트랜스크립트를 재구성할 수 있습니다.

228 228

229두 옵션 중 하나를 활성화하면 Claude Code는 [모든 중첩 깊이의 서브에이전트](/docs/ko/sub-agents#let-subagents-spawn-their-own-subagents)에서 메시지를 전달합니다. 각 서브에이전트가 Agent 도구 또는 [포크된 스킬](/docs/ko/skills#run-skills-in-a-subagent)로 시작되었는지 여부와 관계없이 메시지를 전달합니다. 포크된 스킬이 생성하는 서브에이전트의 메시지와 서브에이전트 또는 다른 포크된 스킬 내에서 시작된 포크된 스킬의 메시지는 Claude Code v2.1.275 이상이 필요합니다. `parent_tool_use_id`에서 중첩된 서브에이전트의 메시지는 이를 시작한 Agent 또는 Skill 도구 호출의 ID를 포함하므로 이러한 ID를 따라 전체 중첩 트리를 재구성할 수 있습니다. v2.1.219 이전에는 중첩된 서브에이전트의 메시지가 스트림에 나타나지 않았습니다.229두 옵션 중 하나를 활성화하면 Claude Code는 각 서브에이전트가 Agent 도구로 생성되었는지 포크된 스킬로 시작되었는지와 관계없이 [모든 중첩 깊이의 서브에이전트](/docs/ko/sub-agents#let-subagents-spawn-their-own-subagents)에서 메시지를 전달합니다. `parent_tool_use_id`에서 중첩된 서브에이전트의 메시지는 이를 시작한 Agent 또는 Skill 도구 호출의 ID를 포함하므로 이러한 ID를 따라 전체 중첩 트리를 재구성할 수 있습니다.

230 230

231[서브에이전트에서 실행되는](/docs/ko/skills#run-skills-in-a-subagent) 스킬은 스트림에 동일한 방식으로 나타납니다: 포크된 스킬의 첫 번째 메시지는 실행을 구동하는 스킬 콘텐츠를 전달하는 `user` 메시지입니다. 두 옵션 중 하나를 활성화하면 스트림은 포크된 스킬의 텍스트 및 사고 블록도 포함합니다. v2.1.265 이전에는 포크된 스킬의 `tool_use` 및 `tool_result` 블록만 스트림에 나타났습니다.231Claude가 도구 호출로 시작한 실행은 해당 도구 호출의 ID를 포함합니다. `/<skill-name>`을 프롬프트로 전달하여 시작한 포크된 스킬에는 도구 호출이 없으므로, 그 메시지는 대신 `forked-command-` 값을 포함하며 스킬이 완료된 후에 도착합니다. 첫 번째 열에서 실행이 시작된 방식을 찾으십시오:

232

233| 실행이 시작되는 방식 | `parent_tool_use_id` | 메시지가 도착하는 시점 |

234| :- | :- | :- |

235| Claude가 주 대화에서 Agent 도구를 호출 | 해당 Agent `tool_use` 블록의 ID | 서브에이전트가 작업하는 동안 |

236| Claude가 주 대화에서 포크된 스킬에 대해 Skill 도구를 호출 | 해당 Skill `tool_use` 블록의 ID | 포크된 스킬이 작업하는 동안 |

237| 사용자가 `/<skill-name>`을 프롬프트로 전달 | `forked-command-`로 시작하는 값 | 포크된 스킬이 완료된 후 한꺼번에 순서대로 |

238

239프롬프트에서 시작된 포크된 스킬의 경우 `parent_tool_use_id`를 `forked-command-` 접두사로 일치시키십시오. 그 뒤의 이름은 입력한 이름과 다를 수 있기 때문입니다.

240

241이러한 메시지 중 일부가 스트림에서 누락된 경우 Claude Code 버전이 다음 최소 버전을 충족하는지 확인하십시오:

242

243* **`--forward-subagent-text` 및 `CLAUDE_CODE_FORWARD_SUBAGENT_TEXT`**: v2.1.211 이상

244* **모든 중첩 깊이에서의 전달**: v2.1.219 이상

245* **Claude가 주 대화에서 Skill 도구로 시작하는 포크된 스킬**: `tool_use` 및 `tool_result` 블록은 v2.1.86 이상, 첫 번째 `user` 메시지와 텍스트 및 사고 블록은 v2.1.265 이상

246* **포크된 스킬이 생성하는 서브에이전트의 메시지, 그리고 서브에이전트 또는 다른 포크된 스킬 내에서 시작된 포크된 스킬의 메시지**: v2.1.275 이상

247* **`/<skill-name>`을 프롬프트로 전달하여 시작하는 포크된 스킬의 메시지**: v2.1.287 이상

232 248

233<h4 id="handle-api-retries">249<h4 id="handle-api-retries">

234 API 재시도 처리250 API 재시도 처리

269| 필드 | 유형 | 설명 |285| 필드 | 유형 | 설명 |

270| - | - | - |286| - | - | - |

271| `plugins` | 배열 | 성공적으로 로드된 플러그인, 각각 `name` 및 `path` 포함 |287| `plugins` | 배열 | 성공적으로 로드된 플러그인, 각각 `name` 및 `path` 포함 |

272| `plugin_errors` | 배열 | 플러그인 로드 시간 오류, 각각 `plugin`, `type` 및 `message` 포함. 만족하지 않은 종속성 버전 및 누락된 경로 또는 유효하지 않은 아카이브와 같은 `--plugin-dir` 로드 실패를 포함합니다. 영향을 받은 플러그인은 `plugins`에서 없습니다. 오류가 없으면 키가 생략됩니다 |288| `plugin_errors` | 배열 | 플러그인 로드 시간 오류, 각각 `plugin`, `type` 및 `message` 포함. 만족하지 않은 의존성 버전 및 누락된 경로 또는 유효하지 않은 아카이브와 같은 `--plugin-dir` 로드 실패를 포함합니다. 로드되지 않은 플러그인은 `plugins`에 없습니다. 오류가 없으면 키가 생략됩니다 |

273 289

274`--plugin-dir` 디렉토리 또는 아카이브 자체가 로드되지 않으면 해당 `plugin_errors` 항목은 해결된 절대 경로를 `path`로 포함합니다. 여러 `--plugin-dir` 값 중 어느 것이 실패했는지 알려줍니다. `path` 필드는 Claude Code v2.1.283 이상이 필요합니다.290`--plugin-dir` 디렉터리 또는 아카이브 자체가 로드되지 않으면 해당 `plugin_errors` 항목은 해결된 절대 경로를 `path`로 포함합니다. 이를 사용하여 여러 `--plugin-dir` 값 중 어느 것이 실패했는지 확인할 수 있습니다. `path` 필드는 Claude Code v2.1.283 이상이 필요합니다.

275 291

276MCP 서버 필드도 동일한 방식으로 사용합니다. 292MCP 서버 필드도 동일한 방식으로 사용합니다. `-p`와 함께 [`--mcp-config`](/docs/ko/cli-reference#cli-flags)를 전달하면 Claude Code는 첫 번째 턴을 실행하기 전에 여전히 대기 중인 서버를 기다리며, [`MCP_TIMEOUT`](/docs/ko/env-vars) 시작 타임아웃(기본값 30초)까지 기다립니다. [캐시된 도구 목록](/docs/ko/agent-sdk/mcp#connection-timing)이 있는 원격 서버는 대기를 건너뛰고 `system/init`에서 `pending`을 표시하며 첫 번째 도구 호출에서 연결합니다. 대기는 Claude Code v2.1.221 이상이 필요합니다.

277`-p`와 함께 [`--mcp-config`](/docs/ko/cli-reference#cli-flags)를 전달하면 Claude Code는 첫 번째 턴을 실행하기 전에 여전히 대기 중인 서버를 기다리며, [`MCP_TIMEOUT`](/docs/ko/env-vars) 시작 시간 초과(기본값 30초)까지 기다립니다. [캐시된 도구 목록](/docs/ko/agent-sdk/mcp#connection-timing)이 있는 원격 서버는 대기를 건너뛰고 `system/init`에서 `pending`을 표시하며 첫 번째 도구 호출에서 연결합니다. 대기는 Claude Code v2.1.221 이상이 필요합니다.

278 293

279Claude Code는 시작 시 각 `--mcp-config` 항목을 검증하고 검증에 실패한 항목을 건너뜁니다(예: `type`이 없는 `url` 항목). 실행이 계속되고 깔끔하게 종료되므로 이러한 필드를 확인하여 로드되지 않은 서버를 포착합니다:294Claude Code는 시작 시 각 `--mcp-config` 항목을 검증하고 검증에 실패한 항목을 건너뜁니다(예: `type`이 없는 `url` 항목). 실행이 계속되고 깔끔하게 종료되므로 이러한 필드를 확인하여 로드되지 않은 서버를 포착합니다:

280 295

315전체 세션에 대한 기준선을 설정하려면 개별 도구를 나열하는 대신 [권한 모드](/docs/ko/permission-modes)를 전달합니다. 권한 모드를 설정하지 않는 실행은 [기본 제공 시작 권한 모드](/docs/ko/permission-modes#which-mode-a-session-starts-in)를 사용하며, 이는 `auto`일 수 있으므로 원하는 권한 모드를 전달합니다:330전체 세션에 대한 기준선을 설정하려면 개별 도구를 나열하는 대신 [권한 모드](/docs/ko/permission-modes)를 전달합니다. 권한 모드를 설정하지 않는 실행은 [기본 제공 시작 권한 모드](/docs/ko/permission-modes#which-mode-a-session-starts-in)를 사용하며, 이는 `auto`일 수 있으므로 원하는 권한 모드를 전달합니다:

316 331

317* **`auto`**: `--permission-mode auto`를 전달하여 분류기가 대부분의 작업을 검토하도록 합니다332* **`auto`**: `--permission-mode auto`를 전달하여 분류기가 대부분의 작업을 검토하도록 합니다

318* **`dontAsk`**: Claude Code는 그렇지 않으면 프롬프트할 모든 호출을 거부하며, 이는 잠긴 CI 실행에 유용합니다. Manual 모드에서 승인이 필요하지 않은 작업(예: 작업 디렉토리의 파일 읽기 및 [읽기 전용 명령 집합](/docs/ko/permissions#read-only-commands))과 `--allowedTools` 항목 또는 `permissions.allow` 규칙이 적용되는 작업은 여전히 실행됩니다. `AskUserQuestion`, 조직이 [`ask`](/docs/ko/mcp#organization-controls-on-connector-tools)로 설정한 커넥터 도구 및 [`requiresUserInteraction`](/docs/ko/mcp#require-approval-for-a-specific-tool)으로 표시된 MCP 도구는 허용 규칙이 일치해도 거부됩니다333* **`dontAsk`**: Claude Code는 그렇지 않으면 프롬프트할 모든 호출을 거부하며, 이는 잠긴 CI 실행에 유용합니다. Manual 모드에서 승인이 필요하지 않은 작업(예: 작업 디렉터리의 파일 읽기 및 [읽기 전용 명령 집합](/docs/ko/permissions#read-only-commands))과 `--allowedTools` 항목 또는 `permissions.allow` 규칙이 적용되는 작업은 여전히 실행됩니다. `AskUserQuestion`, [조직이 `ask`로 설정한](/docs/ko/mcp#organization-controls-on-connector-tools) 커넥터 도구 및 [`requiresUserInteraction`](/docs/ko/mcp#require-approval-for-a-specific-tool)으로 표시된 MCP 도구는 허용 규칙이 일치해도 거부됩니다

319* **`acceptEdits`**: Claude는 프롬프트 없이 파일을 작성하고 Claude Code는 `mkdir`, `touch`, `mv` 및 `cp`와 같은 일반적인 파일 시스템 명령을 자동 승인합니다. [모드가 자동 승인하지 않는 작업](/docs/ko/permission-modes#actions-no-mode-auto-approves)은 여전히 적용됩니다. 읽기 전용 명령 집합을 제외하고 다른 셸 명령 및 네트워크 요청은 여전히 `--allowedTools` 항목 또는 `permissions.allow` 규칙이 필요합니다. [`acceptEdits`가 자동 승인하는 것](/docs/ko/permission-modes#auto-approve-file-edits-with-acceptedits-mode)의 전체 목록을 참조하십시오334* **`acceptEdits`**: Claude는 프롬프트 없이 파일을 작성하고 Claude Code는 `mkdir`, `touch`, `mv` 및 `cp`와 같은 일반적인 파일 시스템 명령을 자동 승인합니다. [모드가 자동 승인하지 않는 작업](/docs/ko/permission-modes#actions-no-mode-auto-approves)은 여전히 적용됩니다. 읽기 전용 명령 집합을 제외하고 다른 셸 명령 및 네트워크 요청은 여전히 `--allowedTools` 항목 또는 `permissions.allow` 규칙이 필요합니다. [`acceptEdits`가 자동 승인하는 것](/docs/ko/permission-modes#auto-approve-file-edits-with-acceptedits-mode)의 전체 목록을 참조하십시오

320 335

321이 예제는 `acceptEdits`를 기준선으로 하여 린트 수정을 적용합니다:336이 예제는 `acceptEdits`를 기준선으로 하여 린트 수정을 적용합니다:

357 --allowedTools "Bash(git diff *),Bash(git log *),Bash(git status *),Bash(git commit *)"372 --allowedTools "Bash(git diff *),Bash(git log *),Bash(git status *),Bash(git commit *)"

358```373```

359 374

360`--allowedTools` 플래그는 [권한 규칙 구문](/docs/ko/settings-reference#permission-rule-syntax)을 사용합니다. 뒤의 ` *`는 접두사 일치를 활성화하므로 `Bash(git diff *)`는 `git diff`로 시작하는 모든 명령을 허용합니다. 공백은 중요합니다: 없으면 `Bash(git diff*)`는 `git diff-index`도 일치합니다.375`--allowedTools` 플래그는 [권한 규칙 구문](/docs/ko/settings-reference#permission-rule-syntax)을 사용합니다. 뒤의 ` *`는 접두사 일치를 활성화하므로 `Bash(git diff *)`는 `git diff`로 시작하는 모든 명령을 허용합니다. `*` 앞의 공백은 중요합니다: 없으면 `Bash(git diff*)`는 `git diff-index`도 일치합니다.

361 376

362<Note>377<Note>

363 명령 지원은 `-p` 모드에서 다릅니다:378 명령 지원은 `-p` 모드에서 다릅니다:

364 379

365 * 사용자 호출 [스킬](/docs/ko/skills) 및 사용자 정의 명령이 작동합니다. 프롬프트 문자열에 `/skill-name`을 포함하고 Claude Code는 실행하기 전에 이를 확장합니다.380 * 사용자 호출 [스킬](/docs/ko/skills) 및 사용자 정의 명령이 작동합니다. 프롬프트 문자열에 `/skill-name`을 포함하고 Claude Code는 실행하기 전에 이를 확장합니다.

366 * 터미널 인터페이스에서만 실행되는 `/login`과 같은 기본 제공 명령은 사용할 수 없습니다.381 * 터미널 인터페이스에서만 실행되는 `/login`과 같은 기본 제공 명령은 사용할 수 없습니다.

367 *382 * `/model`, `/effort`, `/fast`, `/color` 및 `/rename`은 값을 인수로 허용합니다(예: `/model sonnet`). `/mcp`는 인수 없이 서버 상태의 텍스트 요약을 인쇄합니다. 이러한 형식은 Claude Code v2.1.205 이상이 필요하며 각 명령의 [가용성 참고 사항](/docs/ko/commands#all-commands)을 따릅니다.

~~368~~

369 `/model`, `/effort`, `/fast`, `/color` 및 `/rename`은 값을 인수로 허용합니다(예: `/model sonnet`). `/mcp`는 인수 없이 서버 상태의 텍스트 요약을 인쇄합니다. 이러한 형식은 Claude Code v2.1.205 이상이 필요하며 각 명령의 [가용성 참고 사항](/docs/ko/commands#all-commands)을 따릅니다.

~~370~~

371 * 설정을 변경하려면 `/config`에 `key=value`를 전달합니다(예: `/config thinking=false`).383 * 설정을 변경하려면 `/config`에 `key=value`를 전달합니다(예: `/config thinking=false`).

372 *384 * `/output-style <style>`은 [출력 스타일](/docs/ko/output-styles)을 전환하고 `/output-style`만으로 이들을 나열합니다. Claude Code v2.1.269 이상이 필요합니다.

~~373~~

374 `/output-style <style>`은 [출력 스타일](/docs/ko/output-styles)을 전환하고 `/output-style`만으로 이들을 나열합니다. Claude Code v2.1.269 이상이 필요합니다.

375</Note>385</Note>

376 386

377<h3 id="customize-the-system-prompt">387<h3 id="customize-the-system-prompt">

394 대화 계속404 대화 계속

395</h3>405</h3>

396 406

397`--continue`를 사용하여 가장 최근 대화를 계속하거나 `--resume`을 세션 ID와 함께 사용하여 특정 대화를 계속합니다. Claude Code v2.1.257 이상에서 `--continue`를 전달하면 Claude Code는 완료되었지만 여전히 실행 중이 아닌 [백그라운드 세션](/docs/ko/sessions#resume-a-session)을 엽니다. 이 예제는 검토를 실행한 다음 후속 프롬프트를 보냅니다:407`--continue`를 사용하여 가장 최근 대화를 계속하거나 `--resume`을 세션 ID와 함께 사용하여 특정 대화를 계속합니다. Claude Code v2.1.257 이상에서 `--continue`를 전달하면 Claude Code는 완료된 [백그라운드 세션](/docs/ko/sessions#resume-a-session)은 열지만 아직 실행 중인 세션은 열지 않습니다. 이 예제는 검토를 실행한 다음 후속 프롬프트를 보냅니다:

398 408

399```bash theme={null}409```bash theme={null}

400# 첫 번째 요청410# 첫 번째 요청

412claude -p "Continue that review" --resume "$session_id"422claude -p "Continue that review" --resume "$session_id"

413```423```

414 424

415두 명령을 다른 디렉토리에서 실행할 수 있습니다: Claude Code는 [세션 ID로 세션을 찾습니다](/docs/ko/sessions#resume-a-session) 이 머신의 모든 프로젝트에서. v2.1.223 이전에는 Claude Code가 현재 프로젝트 디렉토리 및 git worktrees에서만 ID를 찾았으므로 두 명령을 같은 디렉토리에서 실행해야 했습니다.425두 명령을 서로 다른 디렉터리에서 실행할 수 있습니다: Claude Code는 이 머신의 모든 프로젝트에서 [세션 ID로 세션을 찾습니다](/docs/ko/sessions#resume-a-session). v2.1.223 이전에는 Claude Code가 현재 프로젝트 디렉터리 및 git worktree에서만 ID를 찾았으므로 두 명령을 같은 디렉터리에서 실행해야 했습니다.

416 426

417세션 ID 대신 `--resume`에 세션의 `.jsonl` [트랜스크립트 파일](/docs/ko/sessions#where-transcripts-are-stored)의 절대 경로를 전달할 수 있으며 Claude Code는 해당 파일에 저장된 대화를 계속합니다.427세션 ID 대신 `--resume`에 세션의 `.jsonl` [트랜스크립트 파일](/docs/ko/sessions#where-transcripts-are-stored)의 절대 경로를 전달할 수 있으며 Claude Code는 해당 파일에 저장된 대화를 계속합니다.

418 428

hooks.md +8 −6

Details

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

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

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

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

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

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

3274 WorktreeRemove3274 WorktreeRemove

3275</h3>3275</h3>

3276 3276

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

3278 3278

3279* `--worktree` 세션을 종료하면서 제거를 선택한 경우3279* 대화형 [worktree 세션](/docs/ko/worktrees#start-claude-in-a-worktree)을 종료하면서 Claude Code가 확인을 요청할 때 worktree 제거를 선택한 경우

3280* `isolation: "worktree"`가 설정된 서브에이전트가 완료된 경우3280* [이름을 지정](/docs/ko/sessions#name-your-sessions)하지 않은 대화형 worktree 세션을 종료했을 때 Claude Code가 변경되었거나 추적되지 않는 파일을 찾지 못해 확인 요청 없이 worktree를 제거하는 경우

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

3282

3283Claude Code는 git을 사용해 변경되었거나 추적되지 않는 파일을 찾으므로, git 체크아웃이 아니거나 git 체크아웃 내부에 있지 않은 worktree에서는 디렉터리에 커밋되지 않은 작업이 있더라도 아무것도 찾지 못합니다. WorktreeRemove 훅에서 무언가를 삭제하기 전에 그러한 작업이 있는지 확인하십시오.

3282 3284

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

3284 3286

3285* **WorktreeRemove 훅이 없는 경우**: `--worktree` 세션을 종료하면서 제거를 선택하면 Claude Code는 WorktreeCreate 훅이 반환한 경로에 대해 `git worktree remove --force`로 폴백하므로, git이 인식하는 worktree는 제거됩니다. git이 인식하지 못하는 워크트리(예: 훅이 git이 아닌 버전 관리 시스템으로 생성한 워크트리)는 디스크에 남습니다. [백그라운드 세션](/docs/ko/agent-view#what-deleting-a-session-removes)을 삭제할 때 훅이 생성한 워크트리가 어떻게 처리되는지는 에이전트 뷰의 삭제 규칙을 참조하십시오.3287* **WorktreeRemove 훅이 없는 경우**: worktree 세션을 종료하면서 Claude Code가 worktree를 제거할 때, WorktreeCreate 훅이 반환한 경로에 대해 `git worktree remove --force`로 폴백하므로 git이 인식하는 worktree는 제거됩니다. git이 인식하지 못하는 worktree(예: 훅이 git이 아닌 버전 관리 시스템으로 생성한 worktree)는 디스크에 남습니다. [백그라운드 세션](/docs/ko/agent-view#what-deleting-a-session-removes) 삭제 시 훅이 생성한 worktree가 어떻게 처리되는지는 에이전트 뷰의 삭제 규칙을 참조하십시오.

3286* **훅이 0으로 종료되는 경우**: 워크트리가 제거된 것으로 간주됩니다. Claude Code는 훅에서 다른 내용을 읽지 않으므로 훅이 디렉터리를 실제로 삭제했는지 확인하십시오.3288* **훅이 0으로 종료되는 경우**: 워크트리가 제거된 것으로 간주됩니다. Claude Code는 훅에서 다른 내용을 읽지 않으므로 훅이 디렉터리를 실제로 삭제했는지 확인하십시오.

3287* **훅이 0이 아닌 코드로 종료되는 경우**: 이후에도 `worktree_path`의 디렉터리가 여전히 존재하면 제거가 실패하고, 워크트리는 git 폴백 없이 디스크에 남습니다. 0이 아닌 코드로 종료하기 전에 디렉터리를 삭제한 훅은 제거된 것으로 간주됩니다. 실패가 보고되는 방식은 [WorktreeRemove 입력](#worktreeremove-input)을 참조하십시오.3289* **훅이 0이 아닌 코드로 종료되는 경우**: 이후에도 `worktree_path`의 디렉터리가 여전히 존재하면 제거가 실패하고, 워크트리는 git 폴백 없이 디스크에 남습니다. 0이 아닌 코드로 종료하기 전에 디렉터리를 삭제한 훅은 제거된 것으로 간주됩니다. 실패가 보고되는 방식은 [WorktreeRemove 입력](#worktreeremove-input)을 참조하십시오.

3288 3290

hooks-guide.md +1 −1

Details

how-claude-code-works.md +1 −1

Details

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

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

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

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

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

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

82 82

interactive-mode.md +1 −1

Details

42| `Ctrl+Enter` 또는 `Ctrl+X Ctrl+S` | 대기 중인 메시지 지금 보내기 | [대기 중인 메시지](#queue-messages-while-claude-works)와 초안을 지금 바로 보냅니다. [Claude Code가 대기 중인 메시지를 보낼 때](#when-claude-code-sends-what-you-queued)는 Claude가 작업 중인 턴에 어떤 일이 발생하는지 설명합니다. [셸 모드](#shell-mode-with-prefix)에서 키는 명령만 대기열에 넣습니다. 확장 키를 보고하지 않는 터미널에서 `Ctrl+Enter`는 일반 `Enter`로 도착합니다. `Ctrl+X Ctrl+S`는 모든 터미널에서 작동합니다. Claude Code v2.1.275 이상 필요 |42| `Ctrl+Enter` 또는 `Ctrl+X Ctrl+S` | 대기 중인 메시지 지금 보내기 | [대기 중인 메시지](#queue-messages-while-claude-works)와 초안을 지금 바로 보냅니다. [Claude Code가 대기 중인 메시지를 보낼 때](#when-claude-code-sends-what-you-queued)는 Claude가 작업 중인 턴에 어떤 일이 발생하는지 설명합니다. [셸 모드](#shell-mode-with-prefix)에서 키는 명령만 대기열에 넣습니다. 확장 키를 보고하지 않는 터미널에서 `Ctrl+Enter`는 일반 `Enter`로 도착합니다. `Ctrl+X Ctrl+S`는 모든 터미널에서 작동합니다. Claude Code v2.1.275 이상 필요 |

43| `Shift+Tab` 또는 Node 또는 Bun 런타임이 VT 입력 모드를 활성화하지 않을 때 Windows의 `Alt+M` | 권한 모드 순환 | `default` (모드 표시기에서 Manual로 표시됨), `acceptEdits`, `plan` 및 사용 가능할 때 `bypassPermissions` 및 `auto`를 순환합니다. `auto`에서 첫 번째 누름은 `default`로 전환합니다. [권한 모드](/docs/ko/permission-modes)를 참조하세요. 파일 권한 프롬프트에서 동일한 키는 열린 [주석 필드](/docs/ko/permissions#add-a-comment-when-you-answer-a-permission-prompt)를 닫습니다. 필드가 열려 있지 않으면 프롬프트가 나머지 세션에 대해 작업을 허용하는 옵션을 선택합니다 |43| `Shift+Tab` 또는 Node 또는 Bun 런타임이 VT 입력 모드를 활성화하지 않을 때 Windows의 `Alt+M` | 권한 모드 순환 | `default` (모드 표시기에서 Manual로 표시됨), `acceptEdits`, `plan` 및 사용 가능할 때 `bypassPermissions` 및 `auto`를 순환합니다. `auto`에서 첫 번째 누름은 `default`로 전환합니다. [권한 모드](/docs/ko/permission-modes)를 참조하세요. 파일 권한 프롬프트에서 동일한 키는 열린 [주석 필드](/docs/ko/permissions#add-a-comment-when-you-answer-a-permission-prompt)를 닫습니다. 필드가 열려 있지 않으면 프롬프트가 나머지 세션에 대해 작업을 허용하는 옵션을 선택합니다 |

45| `Option+T` (macOS) 또는 `Alt+T` (Windows/Linux) | 확장 사고 전환 | 확장 사고 모드를 활성화하거나 비활성화합니다. Opus 5.5, Sonnet 5.5 또는 Fable 모델에는 영향을 주지 않으며, 이들은 항상 확장 사고를 사용합니다. Option을 Meta로 구성하지 않고도 macOS에서 작동합니다 |45| `Option+T` (macOS) 또는 `Alt+T` (Windows/Linux) | 확장 사고 전환 | 확장 사고 모드를 활성화하거나 비활성화합니다. Opus 5.5, Sonnet 5.5, Haiku 5.5 또는 Fable 모델에는 영향을 주지 않으며, 이들은 항상 확장 사고를 사용합니다. Option을 Meta로 구성하지 않고도 macOS에서 작동합니다 |

47 47

48<h3 id="text-editing">48<h3 id="text-editing">

keybindings.md +3 −2

Details

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

306| `footer:close` | x | 선택한 [에이전트](/docs/ko/sub-agents#observe-and-steer-running-forks) 또는 [워크플로](/docs/ko/workflows#manage-runs)를 중지하거나, 더 이상 실행 중이 아니면 해당 행을 닫습니다 |

307 308

308바닥글 항목이 선택되어 있을 때(예: 프롬프트 아래의 에이전트 패널의 행) `Enter`는 `Chat` 컨텍스트에서 `Enter`를 `chat:queueSubmit` 또는 `chat:newline`으로 다시 바인딩한 경우에도 열립니다.309바닥글 항목이 선택되어 있을 때(예: 프롬프트 아래의 에이전트 패널의 행) `Enter`는 `Chat` 컨텍스트에서 `Enter`를 `chat:queueSubmit` 또는 `chat:newline`으로 다시 바인딩한 경우에도 열립니다.

llm-gateway-connect.md +8 −1

Details

216* **관리자가 배포함**: 조직이 [구성을 배포](/docs/ko/llm-gateway-rollout#distribute-through-managed-settings)한 경우, 데스크톱 앱은 설정 없이 게이트웨이를 통해 라우팅합니다216* **관리자가 배포함**: 조직이 [구성을 배포](/docs/ko/llm-gateway-rollout#distribute-through-managed-settings)한 경우, 데스크톱 앱은 설정 없이 게이트웨이를 통해 라우팅합니다

217* **로컬로 구성됨**: 관리자가 배포한 구성이 없는 기기의 경우, 도움말 → 문제 해결 → 개발자 모드 활성화를 열면 앱이 개발자 메뉴와 함께 다시 시작됩니다. 그런 다음 개발자 → 타사 추론 구성을 열고 게이트웨이 기본 URL을 입력합니다. 관리자가 배포한 구성이 우선하며 이 양식을 읽기 전용으로 만듭니다217* **로컬로 구성됨**: 관리자가 배포한 구성이 없는 기기의 경우, 도움말 → 문제 해결 → 개발자 모드 활성화를 열면 앱이 개발자 메뉴와 함께 다시 시작됩니다. 그런 다음 개발자 → 타사 추론 구성을 열고 게이트웨이 기본 URL을 입력합니다. 관리자가 배포한 구성이 우선하며 이 양식을 읽기 전용으로 만듭니다

218 218

219게이트웨이 구성이 활성화되면, 데스크톱 앱은 로컬 머신에서만 세션을 실행합니다: 환경 선택기는 SSH 세션이나 Anthropic 호스팅 클라우드 환경을 제공하지 않으며, [Remote Control](/docs/ko/remote-control)은 사용할 수 없습니다. 게이트웨이를 통해 원격 호스트에서 Claude Code를 사용하려면, [`ANTHROPIC_BASE_URL` 및 게이트웨이 자격 증명](#set-the-base-url-and-credential)이 설정된 해당 호스트에서 CLI를 실행합니다.219게이트웨이 구성이 활성화되면 환경 선택기는 Anthropic 호스팅 클라우드 환경을 제공하지 않으며, [Remote Control](/docs/ko/remote-control)은 사용할 수 없습니다.

220

221게이트웨이 구성에서 SSH 세션은 베타로 제공되며 Claude Desktop v1.40609.0 이상이 필요합니다. 연결하기 전에 허용 목록과 게이트웨이 주소를 확인하세요:

222

223* **허용된 호스트**: SSH 세션은 기본적으로 꺼져 있습니다. 이를 켜려면 사용자 또는 관리자가 타사 추론 구성의 [`sshHostAllowlist`](https://claude.com/docs/third-party/claude-desktop/configuration#sshhostallowlist) 키에 허용된 호스트를 나열합니다

224* **게이트웨이 주소**: 원격 머신이 게이트웨이에 직접 연결하므로, 사용자 컴퓨터의 `localhost`에 있는 게이트웨이는 SSH 세션에서 작동하지 않습니다

225

226[3P 환경의 Claude Desktop에서 SSH 원격 세션](https://claude.com/docs/third-party/claude-desktop/ssh-remote-sessions)을 참조하세요. 원격 호스트에 [`ANTHROPIC_BASE_URL` 및 게이트웨이 자격 증명](#set-the-base-url-and-credential)을 설정하고 해당 호스트에서 CLI를 실행할 수도 있습니다.

220 227

221데스크톱 앱이 `Gateway was unreachable`을 표시하면, 앱이 시작 시 구성된 기본 URL에 도달할 수 없었습니다. 위의 [curl 테스트](#verify-the-connection)로 URL과 네트워크 경로를 확인합니다.228데스크톱 앱이 `Gateway was unreachable`을 표시하면, 앱이 시작 시 구성된 기본 URL에 도달할 수 없었습니다. 위의 [curl 테스트](#verify-the-connection)로 URL과 네트워크 경로를 확인합니다.

222 229

managed-mcp.md +17 −5

Details

347 `serverUrl` 항목 일치 방식347 `serverUrl` 항목 일치 방식

348</h4>348</h4>

349 349

350URL은 스키마를 포함하여 패턴의 어디든 `*` 와일드카드를 지원합니다. 호스트명 일치는 대소문자를 구분하지 않으며 후행 FQDN 점을 무시하므로 `https://Mcp.Example.com/*`은 `https://mcp.example.com/api`와 일치합니다. 경로는 대소문자를 구분합니다.350URL은 스킴 전체로 사용하는 `*`를 포함하여 `*` 와일드카드를 지원합니다. 호스트명 일치는 대소문자를 구분하지 않으며 후행 FQDN 점을 무시하므로 `https://Mcp.Example.com/*`은 `https://mcp.example.com/api`와 일치합니다. 경로는 대소문자를 구분합니다. 포트를 지정하지 않으면 호스트명을 작성하는 방식에 따라 패턴이 스킴의 기본 포트에만 일치하는지 모든 포트에 일치하는지가 결정됩니다.

351

352* **호스트명을 완전히 작성한 경우**: 기본 포트에만 일치하며, `https`는 443, `http`는 80입니다

353* **호스트명에 `*`가 포함된 경우**: 모든 포트에 일치합니다

351 354

352아래 표는 일반적인 패턴이 허용하는 대상을 보여줍니다.355아래 표는 일반적인 패턴이 허용하는 대상을 보여줍니다.

353 356

354| 패턴 | 허용 |357| 패턴 | 허용 |

355| :- | :- |358| :- | :- |

356| `https://mcp.example.com/*` | 특정 도메인의 모든 경로 |359| `https://mcp.example.com/*` | 특정 도메인의 모든 경로, 포트 443에서만 |

358| `https://*.example.com/*` | `example.com`의 모든 하위 도메인 |361| `https://mcp.example.com:8443/*` | 해당 도메인의 모든 경로, 포트 8443에서만 |

362| `https://mcp.example.com:*/*` | 해당 도메인의 모든 경로, 443을 포함한 모든 포트에서 |

363| `https://*.example.com/*` | `example.com`의 모든 하위 도메인, 모든 포트에서 |

359| `http://localhost:*/*` | localhost의 모든 포트 |364| `http://localhost:*/*` | localhost의 모든 포트 |

360| `*://mcp.example.com/*` | 특정 도메인으로의 모든 스키마 |365| `*://mcp.example.com/*` | 특정 도메인으로의 모든 스킴, 각 스킴의 기본 포트에서만 |

366

367`deniedMcpServers`의 항목도 같은 방식으로 포트와 일치하므로, 차단해야 하는 포트와 스킴에 따라 `staging.example.com`에 대한 항목을 선택합니다.

368

369* `https://staging.example.com/*`: 해당 호스트의 포트 443에 있는 `https` 서버만 차단하므로 `https://staging.example.com:8443/api`의 서버는 차단하지 않습니다

370* `https://staging.example.com:*/*`: 해당 호스트의 모든 포트에 있는 `https` 서버를 차단합니다

371* `*://staging.example.com:*/*`: 모든 스킴과 모든 포트에서 해당 호스트를 차단합니다

361 372

362<h4 id="how-policy-entries-expand">373<h4 id="how-policy-entries-expand">

363 `serverCommand` 및 `serverUrl` 항목의 환경 변수374 `serverCommand` 및 `serverUrl` 항목의 환경 변수

529 | :- | :- |540 | :- | :- |

543 | `https://staging.example.com:8443/api`의 HTTP 서버 | 허용됨: 허용 목록 URL 패턴과 일치, [이 포트에서는 거부 목록 일치 없음](#how-serverurl-entries-match) |

533</Accordion>545</Accordion>

534 546

memory.md +2 −2

Details

8 8

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

10 10

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

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

13 13

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

15 15

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

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

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

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

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

mobile.md +1 −1

Details

89모바일 클라이언트는 세션이 필요한 대부분의 것을 다루지만 몇 가지 제한 사항이 있습니다.89모바일 클라이언트는 세션이 필요한 대부분의 것을 다루지만 몇 가지 제한 사항이 있습니다.

90 90

91* **로컬 전용 명령**: `/plugin` 및 `/resume`과 같이 터미널 인터페이스에서만 실행되는 명령은 앱에서 작동하지 않습니다. [Remote Control 제한 사항](/docs/ko/remote-control#limitations)은 모바일에서 작동하는 명령과 동작이 어떻게 다른지 나열합니다.91* **로컬 전용 명령**: `/plugin` 및 `/resume`과 같이 터미널 인터페이스에서만 실행되는 명령은 앱에서 작동하지 않습니다. [Remote Control 제한 사항](/docs/ko/remote-control#limitations)은 모바일에서 작동하는 명령과 동작이 어떻게 다른지 나열합니다.

92* **권한 모드**: 클라우드 세션은 모드 드롭다운에서 편집 수락, Plan 및 Auto를 제공하고, Remote Control 세션은 Manual, 편집 수락 및 Plan을 제공합니다. 두 경우 모두 앱에서 Bypass 권한을 선택할 수 없으며, Remote Control 세션에 대해 Auto를 선택할 수 없습니다. [권한 모드 전환](/docs/ko/permission-modes#switch-permission-modes)을 참조하세요.92* **권한 모드**: 클라우드 세션은 편집 수락, Plan 및 Auto를 제공하고, Remote Control 세션은 Manual, 편집 수락, Plan 및 Auto를 제공합니다. 두 경우 모두 앱에서 Bypass 권한을 선택할 수 없습니다. Auto를 사용할 수 있는 경우는 [권한 모드 전환](/docs/ko/permission-modes#switch-permission-modes)을 참조하세요.

93* **Dispatch 플랜**: Dispatch는 Pro 또는 Max 플랜이 필요하며 Team 또는 Enterprise에서는 사용할 수 없습니다.93* **Dispatch 플랜**: Dispatch는 Pro 또는 Max 플랜이 필요하며 Team 또는 Enterprise에서는 사용할 수 없습니다.

94 94

95<h2 id="related-resources">95<h2 id="related-resources">

model-config.md +36 −23

Details

43| **`opus[1m]`** | 긴 세션을 위해 [100만 토큰 컨텍스트 윈도우](https://platform.claude.com/docs/en/build-with-claude/context-windows#context-window-sizes-by-model)를 가진 Opus를 사용합니다 |43| **`opus[1m]`** | 긴 세션을 위해 [100만 토큰 컨텍스트 윈도우](https://platform.claude.com/docs/en/build-with-claude/context-windows#context-window-sizes-by-model)를 가진 Opus를 사용합니다 |

44| **`opusplan`** | 계획 모드 중에 `opus`를 사용한 다음 실행을 위해 `sonnet`으로 전환하는 특수 모드입니다 |44| **`opusplan`** | 계획 모드 중에 `opus`를 사용한 다음 실행을 위해 `sonnet`으로 전환하는 특수 모드입니다 |

45 45

~~46`opus` 및 `sonnet` 별칭이 확인되는 버전은 공급자에 따라 다릅니다:~~46`opus`, `sonnet`, `haiku` 별칭은 Anthropic API에서는 최신 버전으로 확인되고, 일부 다른 공급자에서는 이전 버전으로 확인됩니다:

47 47

~~48| 공급자 | `opus` | `sonnet` |~~48| 공급자 | `opus` | `sonnet` | `haiku` |

~~49| :- | :- | :- |~~49| :- | :- | :- | :- |

54 54

55<span id="fable-alias-resolution" />55<span id="fable-alias-resolution" />

56 56

58 58

59`claude-fable-5-1`을 제공하도록 구성되지 않은 게이트웨이는 해당 모델에 대한 요청을 거부합니다. 이를 제공하는 게이트웨이를 통해 Fable 5.1을 사용하려면 `/model claude-fable-5-1`로 선택합니다.59`claude-fable-5-1`을 제공하도록 구성되지 않은 게이트웨이는 해당 모델에 대한 요청을 거부합니다. 이를 제공하는 게이트웨이를 통해 Fable 5.1을 사용하려면 `/model claude-fable-5-1`로 선택합니다.

60 60

61별칭이 이전 모델로 확인되는 경우, 전체 모델 이름을 명시적으로 선택하거나 `ANTHROPIC_DEFAULT_OPUS_MODEL` 또는 `ANTHROPIC_DEFAULT_SONNET_MODEL`을 설정하여 최신 모델을 사용할 수 있습니다.61`opus` 또는 `sonnet`이 이전 모델로 확인되는 경우, 전체 모델 이름을 명시적으로 선택하거나 `ANTHROPIC_DEFAULT_OPUS_MODEL` 또는 `ANTHROPIC_DEFAULT_SONNET_MODEL`을 설정하여 최신 모델을 사용할 수 있습니다.

62 62

63이전 버전은 이러한 별칭을 이전 모델로 확인합니다. 각 별칭이 변경된 버전은 [버전 기록](#version-history)을 참조하십시오.63이전 버전은 이러한 별칭을 이전 모델로 확인합니다. 각 별칭이 변경된 버전은 [버전 기록](#version-history)을 참조하십시오.

64 64

65별칭은 공급자의 권장 버전을 가리키며 시간이 지남에 따라 업데이트됩니다. 특정 버전으로 고정하려면 전체 모델 이름(예: `claude-opus-5-5`)을 사용하거나 `ANTHROPIC_DEFAULT_OPUS_MODEL`과 같은 해당 환경 변수를 설정합니다.65별칭은 공급자의 권장 버전을 가리키며 시간이 지남에 따라 업데이트됩니다. 특정 버전으로 고정하려면 전체 모델 이름(예: `claude-opus-5-5`)을 사용하거나 `ANTHROPIC_DEFAULT_OPUS_MODEL`과 같은 해당 환경 변수를 설정합니다.

66 66

67<Note>67<Note>

68 Sonnet 5.5는 Claude Code v2.1.284 이상이 필요하고, Opus 5.5는 v2.1.280 이상이 필요합니다. 이전 버전의 요청이 실패하면 [Claude Code는 이 모델을 지원하지 않습니다](/docs/ko/errors#claude-code-does-not-support-this-model)를 참조하십시오. `claude update`를 실행하여 업그레이드합니다.68 Sonnet 5.5는 Claude Code v2.1.284 이상이 필요하고, Opus 5.5는 v2.1.280 이상이 필요합니다. 이전 버전에서 이들 중 하나에 대한 요청이 실패하면 [Claude Code는 이 모델을 지원하지 않습니다](/docs/ko/errors#claude-code-does-not-support-this-model)를 참조하십시오. Haiku 5.5에는 v2.1.293 이상을 사용합니다. `claude update`를 실행하여 업그레이드합니다.

69</Note>69</Note>

70 70

71<h3 id="work-with-fable">71<h3 id="work-with-fable">

156 156

157`/model` 선택기의 가격은 Claude Code가 Anthropic API와 직접 또는 [LLM 게이트웨이](/docs/ko/llm-gateway)를 통해 프록시할 때 나타나며, 행의 가격은 해당 행이 선택하는 모델의 가격입니다. Amazon Bedrock과 같은 [타사 공급자](/docs/ko/third-party-integrations)에서 및 [Claude 앱 게이트웨이](/docs/ko/claude-apps-gateway)에서 공급자 또는 게이트웨이가 지불하는 금액을 결정하므로 선택기 행은 가격을 표시하지 않습니다. 가격은 표시 레이블일 뿐이며, 행이 선택하는 모델이나 공급자가 청구하는 금액에 영향을 주지 않습니다. v2.1.206 이전에는 [AWS의 Claude Platform](/docs/ko/claude-platform-on-aws) 및 게이트웨이 세션이 Anthropic 정가를 표시했으며, 행은 선택하는 모델과 다른 모델의 가격을 표시할 수 있었습니다.157`/model` 선택기의 가격은 Claude Code가 Anthropic API와 직접 또는 [LLM 게이트웨이](/docs/ko/llm-gateway)를 통해 프록시할 때 나타나며, 행의 가격은 해당 행이 선택하는 모델의 가격입니다. Amazon Bedrock과 같은 [타사 공급자](/docs/ko/third-party-integrations)에서 및 [Claude 앱 게이트웨이](/docs/ko/claude-apps-gateway)에서 공급자 또는 게이트웨이가 지불하는 금액을 결정하므로 선택기 행은 가격을 표시하지 않습니다. 가격은 표시 레이블일 뿐이며, 행이 선택하는 모델이나 공급자가 청구하는 금액에 영향을 주지 않습니다. v2.1.206 이전에는 [AWS의 Claude Platform](/docs/ko/claude-platform-on-aws) 및 게이트웨이 세션이 Anthropic 정가를 표시했으며, 행은 선택하는 모델과 다른 모델의 가격을 표시할 수 있었습니다.

158 158

159`claude --resume`, `--continue` 또는 `/resume` 선택기로 시작된 재개된 세션은 현재 `model` 설정에 관계없이 트랜스크립트가 저장되었을 때 사용 중이던 모델을 유지합니다. 복원된 모델이 폐기되었거나 [`availableModels`](#restrict-model-selection)에 의해 제외되면 세션은 정상 우선순위 순서로 폴백됩니다. 이는 다른 세션의 `/model` 선택이 재개 시 모델을 변경하는 것을 방지합니다. Amazon Bedrock, Google Cloud의 Agent Platform, Microsoft Foundry와 같이 Anthropic 모델 ID 대신 공급자별 배포 ID를 사용하는 공급자에서는 트랜스크립트 모델이 전혀 복원되지 않으며 세션은 정상 우선순위 순서를 통해 모델을 확인합니다.159`claude --resume`, `--continue` 또는 `/resume` 선택기로 시작된 재개된 세션은 트랜스크립트가 저장되었을 때 사용 중이던 모델을 유지합니다. 복원된 모델이 폐기되었거나 [`availableModels`](#restrict-model-selection)에 의해 제외되면 세션은 정상 우선순위 순서로 폴백됩니다. Amazon Bedrock, Google Cloud의 Agent Platform, Microsoft Foundry와 같이 Anthropic 모델 ID 대신 공급자별 배포 ID를 사용하는 공급자에서는 트랜스크립트 모델이 전혀 복원되지 않으며 세션은 정상 우선순위 순서를 통해 모델을 확인합니다.

160

161`model` 설정이 `haiku`인 경우, Haiku 모델에서 저장된 세션은 현재 `haiku`가 확인되는 모델에서 재개됩니다. 예를 들어 `haiku`가 Haiku 5.5로 확인되면, Haiku 4.5에서 저장된 세션은 Haiku 5.5에서 재개됩니다.

160 162

161새 시작을 위해 `--model` 또는 `ANTHROPIC_MODEL`로 선택한 모델은 여전히 복원된 모델보다 우선순위를 가집니다. v2.1.195부터 [`ANTHROPIC_DEFAULT_OPUS_MODEL`](#environment-variables) 패밀리 변수도 마찬가지입니다. [`ANTHROPIC_DEFAULT_MODEL`](#set-a-default-model-for-new-sessions)도 해당 섹션에 나열된 조건 하에서 가능합니다.163새 시작을 위해 `--model` 또는 `ANTHROPIC_MODEL`로 선택한 모델은 여전히 복원된 모델보다 우선순위를 가집니다. v2.1.195부터 [`ANTHROPIC_DEFAULT_OPUS_MODEL`](#environment-variables) 패밀리 변수도 마찬가지입니다. [`ANTHROPIC_DEFAULT_MODEL`](#set-a-default-model-for-new-sessions)도 해당 섹션에 나열된 조건 하에서 가능합니다.

162 164

645| 모델 | 수준 |647| 모델 | 수준 |

646| :- | :- |648| :- | :- |

650 652

651활성 모델이 지원하지 않는 수준을 설정하면, Claude Code는 설정한 수준 이하의 지원되는 최고 수준으로 폴백합니다. 예를 들어, `xhigh`는 Opus 4.6에서 `high`로 실행됩니다. 조직 또는 자신의 설정도 모델이 제공하는 수준을 제한할 수 있습니다. [조직 노력 제한](#organization-effort-limits)을 참조하세요.653활성 모델이 지원하지 않는 수준을 설정하면, Claude Code는 설정한 수준 이하의 지원되는 최고 수준으로 폴백합니다. 예를 들어, `xhigh`는 Opus 4.6에서 `high`로 실행됩니다. 조직 또는 자신의 설정도 모델이 제공하는 수준을 제한할 수 있습니다. [조직 노력 제한](#organization-effort-limits)을 참조하세요.

654 656

6551. 명시적 선택: [`CLAUDE_CODE_EFFORT_LEVEL`](/docs/ko/env-vars#variables) 환경 변수, `--effort`로 시작하거나, 세션에서 `/effort` ([비대화형 `/effort`는 더 좁은 효과를 가짐](#non-interactive-effort))6571. 명시적 선택: [`CLAUDE_CODE_EFFORT_LEVEL`](/docs/ko/env-vars#variables) 환경 변수, `--effort`로 시작하거나, 세션에서 `/effort` ([비대화형 `/effort`는 더 좁은 효과를 가짐](#non-interactive-effort))

6562. 설정: 모델에 대해 저장한 수준 또는 [`effortLevel`](/docs/ko/settings-reference#effortlevel) 키, [`modelSettings`](/docs/ko/settings-reference#modelsettings)에 명시된 우선순위6582. 설정: 모델에 대해 저장한 수준 또는 [`effortLevel`](/docs/ko/settings-reference#effortlevel) 키, [`modelSettings`](/docs/ko/settings-reference#modelsettings)에 명시된 우선순위

6573. 모델의 기본 effort: effort를 지원하는 모든 모델에서 `high`, 단 Opus 5.5 및 Sonnet 5.5는 `medium`으로 기본값, Opus 4.7은 `xhigh`로 기본값이며, 조직이 [조직 기본 모델](#organization-default-model)에 대한 기본 effort 수준을 설정할 때, 해당 모델을 실행할 때 그 수준이 기본값입니다. 자동 모델 폴백 후 적용되는 수준은 [폴백 후 effort 수준](#effort-level-after-a-fallback)을 참조하세요.6593. 모델의 기본 effort: effort를 지원하는 모든 모델에서 `high`, 단 Opus 5.5, Sonnet 5.5 및 Haiku 5.5는 `medium`으로 기본값, Opus 4.7은 `xhigh`로 기본값이며, 조직이 [조직 기본 모델](#organization-default-model)에 대한 기본 effort 수준을 설정할 때, 해당 모델을 실행할 때 그 수준이 기본값입니다. 자동 모델 폴백 후 적용되는 수준은 [폴백 후 effort 수준](#effort-level-after-a-fallback)을 참조하세요.

658 660

659Opus 5.5는 위의 소스 중 하나가 수준을 설정하지 않으면 `medium`에서 시작하고, 사용자 설정 파일의 최상위 `effortLevel`은 Opus 5.5에 대해 계산되지 않습니다. 해당 키는 Claude Code가 모델별로 수준을 저장하기 전에 `/effort`가 작성한 이전 형식입니다: 이전에 적용된 곳에 계속 적용되며, Opus 5, Fable 5.1 및 이전 모델에서, Opus 5.5 및 이후 릴리스된 모델은 `/effort` 또는 `/model` 선택기로 수준을 선택할 때까지 자신의 기본값에서 시작합니다. 프로젝트, 로컬 또는 관리되는 설정의 최상위 `effortLevel` 또는 `--settings`로 전달된 것은 모든 모델에 적용됩니다.661Opus 5.5는 위의 소스 중 하나가 수준을 설정하지 않으면 `medium`에서 시작하고, 사용자 설정 파일의 최상위 `effortLevel`은 Opus 5.5에 대해 계산되지 않습니다. 해당 키는 Claude Code가 모델별로 수준을 저장하기 전에 `/effort`가 작성한 이전 형식입니다: 이전에 적용된 곳에 계속 적용되며, Opus 5, Fable 5.1 및 이전 모델에서, Opus 5.5 및 이후 릴리스된 모델은 `/effort` 또는 `/model` 선택기로 수준을 선택할 때까지 자신의 기본값에서 시작합니다. 프로젝트, 로컬 또는 관리되는 설정의 최상위 `effortLevel` 또는 `--settings`로 전달된 것은 모든 모델에 적용됩니다.

660 662

709| 수준 | 사용 시기 |711| 수준 | 사용 시기 |

710| :- | :- |712| :- | :- |

711| `low` | 각 결과를 검토하는 빠른 교환(예: 브레인스토밍, 첫 번째 스케치 또는 이름 바꾸기와 같은 작은 변경) |713| `low` | 각 결과를 검토하는 빠른 교환(예: 브레인스토밍, 첫 번째 스케치 또는 이름 바꾸기와 같은 작은 변경) |

712| `medium` | Opus 5.5 및 Sonnet 5.5의 기본값이며, 명확한 범위의 일상적인 엔지니어링 작업(예: 새 기능 구현)에 적합합니다. 다른 모델에서는 일부 지능을 거래할 수 있는 비용 민감한 작업의 토큰 사용을 줄입니다. |714| `medium` | Opus 5.5, Sonnet 5.5 및 Haiku 5.5의 기본값입니다. Opus 5.5 및 Sonnet 5.5에서는 명확한 범위의 일상적인 엔지니어링 작업(예: 새 기능 구현)에 적합합니다. 기본값이 더 높은 모델에서는 일부 지능을 양보할 수 있는 비용 민감한 작업의 토큰 사용을 줄입니다 |

715| `max` | Claude가 당신 없이 작업하기를 원하는 어려운 문제(예: 보안 취약점 찾기). `max`는 수익 감소를 보일 수 있고 과도한 생각에 취약하므로, 광범위하게 채택하기 전에 테스트하세요. |717| `max` | Claude가 당신 없이 작업하기를 원하는 어려운 문제(예: 보안 취약점 찾기). `max`는 수익 감소를 보일 수 있고 과도한 생각에 취약하므로, 광범위하게 채택하기 전에 테스트하세요. |

753 755

754적응형 추론은 각 단계에서 생각을 선택 사항으로 만들므로, Claude는 일상적인 프롬프트에 더 빠르게 응답하고 이점을 얻는 단계를 위해 더 깊은 생각을 예약할 수 있습니다. 현재 수준이 생성하는 것보다 Claude가 더 자주 또는 덜 자주 생각하기를 원하면, 프롬프트 또는 `CLAUDE.md`에서 직접 말할 수 있습니다. 모델은 노력 설정 내에서 해당 지침에 응답합니다.756적응형 추론은 각 단계에서 생각을 선택 사항으로 만들므로, Claude는 일상적인 프롬프트에 더 빠르게 응답하고 이점을 얻는 단계를 위해 더 깊은 생각을 예약할 수 있습니다. 현재 수준이 생성하는 것보다 Claude가 더 자주 또는 덜 자주 생각하기를 원하면, 프롬프트 또는 `CLAUDE.md`에서 직접 말할 수 있습니다. 모델은 노력 설정 내에서 해당 지침에 응답합니다.

755 757

756Fable 모델, Sonnet 5 이상 및 Opus 4.7 이상은 항상 적응형 추론을 사용합니다. 고정 생각 예산 모드 및 `CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING`은 이들에게 적용되지 않습니다.758Fable 모델, Sonnet 5 이상, Haiku 5.5 및 Opus 4.7 이상은 항상 적응형 추론을 사용합니다. 고정 사고 예산 모드 및 `CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING`은 이들에게 적용되지 않습니다.

757 759

758Opus 4.6 및 Sonnet 4.6에서는 `CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING=1`을 설정하여 `MAX_THINKING_TOKENS`로 제어되는 이전 고정 생각 예산으로 되돌릴 수 있습니다. [환경 변수](/docs/ko/env-vars)를 참조하세요.760Opus 4.6 및 Sonnet 4.6에서는 `CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING=1`을 설정하여 `MAX_THINKING_TOKENS`로 제어되는 이전 고정 생각 예산으로 되돌릴 수 있습니다. [환경 변수](/docs/ko/env-vars)를 참조하세요.

759 761

767| :- | :- |769| :- | :- |

770| 환경 변수를 통해 비활성화 | [`MAX_THINKING_TOKENS=0`](/docs/ko/env-vars)을 설정하면 Opus 5.5, Sonnet 5.5 및 Fable 모델을 제외하고 Anthropic API에서 사고가 꺼집니다. [서드파티 제공자](/docs/ko/third-party-integrations)에서는 Claude Code가 대신 `thinking` 매개변수를 생략하며, 적응형 추론 모델은 여전히 사고할 수 있습니다 |772| 환경 변수를 통해 비활성화 | [`MAX_THINKING_TOKENS=0`](/docs/ko/env-vars)을 설정하면 Opus 5.5, Sonnet 5.5, Haiku 5.5 및 Fable 모델을 제외하고 Anthropic API에서 사고가 꺼집니다. [서드파티 제공자](/docs/ko/third-party-integrations)에서는 Claude Code가 대신 `thinking` 매개변수를 생략하며, 적응형 추론 모델은 여전히 사고할 수 있습니다 |

771 773

772Opus 5.5, Sonnet 5.5 또는 Fable 모델에서 생각을 끌 수 없습니다. 세션 토글 및 `/config` 행은 스위치를 제공하는 대신 이 모델들에 대해 `Thinking can't be turned off`를 표시하고, 저장된 `alwaysThinkingEnabled: false` 또는 `MAX_THINKING_TOKENS=0`은 여기에 영향을 주지 않습니다. 이 모델들에서, 모델은 노력 수준에 따라 각 단계에서 얼마나 생각할지 결정합니다. 저장된 설정은 이를 허용하는 모델로 전환할 때 다시 적용됩니다.774Opus 5.5, Sonnet 5.5, Haiku 5.5 또는 Fable 모델에서는 사고를 끌 수 없습니다. 세션 토글 및 `/config` 행은 스위치를 제공하는 대신 이 모델들에 대해 `Thinking can't be turned off`를 표시하고, 저장된 `alwaysThinkingEnabled: false` 또는 `MAX_THINKING_TOKENS=0`은 여기에 영향을 주지 않습니다. 이 모델들에서는 모델이 effort 수준에 따라 각 단계에서 얼마나 사고할지 결정합니다. 저장된 설정은 이를 허용하는 모델로 전환할 때 다시 적용됩니다.

773 775

774Claude Code는 기본적으로 생각 출력을 축소합니다. `Ctrl+O`를 눌러 상세 모드를 토글하고 회색 기울임꼴 텍스트로 추론을 봅니다. Anthropic API의 대화형 세션은 기본적으로 편집된 생각 블록을 수신하므로, 확장할 때 전체 요약을 사용 가능하게 하려면 [설정](/docs/ko/settings)에서 `showThinkingSummaries: true`를 설정하세요. 축소되거나 편집된 경우에도 생성된 모든 생각 토큰에 대해 청구됩니다.776Claude Code는 기본적으로 생각 출력을 축소합니다. `Ctrl+O`를 눌러 상세 모드를 토글하고 회색 기울임꼴 텍스트로 추론을 봅니다. Anthropic API의 대화형 세션은 기본적으로 편집된 생각 블록을 수신하므로, 확장할 때 전체 요약을 사용 가능하게 하려면 [설정](/docs/ko/settings)에서 `showThinkingSummaries: true`를 설정하세요. 축소되거나 편집된 경우에도 생성된 모든 생각 토큰에 대해 청구됩니다.

775 777

779 확장 컨텍스트781 확장 컨텍스트

780</h3>782</h3>

781 783

782Fable 5.1, Fable 5, Sonnet 5 이상, Opus 4.6 이상 및 Sonnet 4.6은 큰 코드베이스가 있는 긴 세션을 위해 [1백만 토큰 컨텍스트 윈도우](https://platform.claude.com/docs/en/build-with-claude/context-windows#context-window-sizes-by-model)를 지원합니다.784Fable 5.1, Fable 5, Sonnet 5 이상, Haiku 5.5, Opus 4.6 이상 및 Sonnet 4.6은 큰 코드베이스가 있는 긴 세션을 위해 [1백만 토큰 컨텍스트 윈도우](https://platform.claude.com/docs/en/build-with-claude/context-windows#context-window-sizes-by-model)를 지원합니다.

783 785

784Anthropic API에서, Fable 5.1, Fable 5, Sonnet 5 이상 및 Opus 4.7 이상은 Pro를 포함한 모든 플랜에서 1M 윈도우로 실행됩니다. 이 모델들에서 `[1m]` 변형을 선택하거나 1M 윈도우에 대해 사용 크레딧을 켤 필요가 없습니다. Fable 사용 자체는 일부 플랜에서 사용 크레딧으로 청구될 수 있습니다. [Fable 및 사용 크레딧](#fable-and-usage-credits)을 참조하세요.786Anthropic API에서, Fable 5.1, Fable 5, Sonnet 5 이상, Haiku 5.5 및 Opus 4.7 이상은 Pro를 포함한 모든 플랜에서 1M 윈도우로 실행됩니다. 이 모델들에서 `[1m]` 변형을 선택하거나 1M 윈도우에 대해 사용량 크레딧을 켤 필요가 없습니다. Fable 사용 자체는 일부 플랜에서 사용량 크레딧으로 청구될 수 있습니다. [Fable 및 사용량 크레딧](#fable-and-usage-credits)을 참조하세요.

785 787

786Opus 4.6 및 Sonnet 4.6은 `[1m]` 변형을 통해서만 1M에 도달하며, 해당 변형에 대한 액세스는 플랜에 따라 다릅니다. Max, Team 및 Enterprise 플랜(Team Standard 및 Team Premium 좌석 모두 포함)에서, 1M 컨텍스트가 있는 Opus 4.6은 구독에 포함됩니다. 1M 컨텍스트가 있는 Sonnet 4.6은 모든 구독 플랜(Max 포함)에서 [사용 크레딧](https://support.claude.com/en/articles/12429409-extra-usage-for-paid-claude-plans)이 필요합니다.788Opus 4.6 및 Sonnet 4.6은 `[1m]` 변형을 통해서만 1M에 도달하며, 해당 변형에 대한 액세스는 플랜에 따라 다릅니다. Max, Team 및 Enterprise 플랜(Team Standard 및 Team Premium 좌석 모두 포함)에서, 1M 컨텍스트가 있는 Opus 4.6은 구독에 포함됩니다. 1M 컨텍스트가 있는 Sonnet 4.6은 모든 구독 플랜(Max 포함)에서 [사용 크레딧](https://support.claude.com/en/articles/12429409-extra-usage-for-paid-claude-plans)이 필요합니다.

787 789

795 797

796<span id="context-window-behind-a-gateway" />798<span id="context-window-behind-a-gateway" />

797 799

798`ANTHROPIC_BASE_URL`을 [LLM 게이트웨이](/docs/ko/llm-gateway) 또는 다른 프록시로 설정하면, Claude Code는 인식하는 각 모델에 Anthropic API에서 해당 모델이 가진 것과 동일한 컨텍스트 윈도우를 제공합니다. Fable 5.1, Fable 5, Sonnet 5 이상 및 Opus 4.7 이상은 선택할 `[1m]` 변형 없이 1M 윈도우를 얻고, Opus 4.6과 같이 `[1m]` 변형을 통해서만 1M에 도달하는 모델은 해당 변형 없이는 200K에서 실행됩니다. Claude Code는 게이트웨이 또는 그 뒤의 서버가 적용하는 더 낮은 제한을 감지할 수 없습니다. 게이트웨이가 200K 토큰을 초과하는 요청을 거부하면, Claude Code를 시작하는 환경에서 [`CLAUDE_CODE_AUTO_COMPACT_WINDOW=200000`](/docs/ko/env-vars)을 설정하여 모든 모델의 세션이 [해당 경계에서 압축](#set-the-auto-compact-window)되도록 하세요.800`ANTHROPIC_BASE_URL`을 [LLM 게이트웨이](/docs/ko/llm-gateway) 또는 다른 프록시로 설정하면, Claude Code는 인식하는 각 모델에 Anthropic API에서 해당 모델이 가진 것과 동일한 컨텍스트 윈도우를 제공합니다. Fable 5.1, Fable 5, Sonnet 5 이상, Haiku 5.5 및 Opus 4.7 이상은 선택할 `[1m]` 변형 없이 1M 윈도우를 얻고, Opus 4.6과 같이 `[1m]` 변형을 통해서만 1M에 도달하는 모델은 해당 변형 없이는 200K에서 실행됩니다. Claude Code는 게이트웨이 또는 그 뒤의 서버가 적용하는 더 낮은 제한을 감지할 수 없습니다. 게이트웨이가 200K 토큰을 초과하는 요청을 거부하면, Claude Code를 시작하는 환경에서 [`CLAUDE_CODE_AUTO_COMPACT_WINDOW=200000`](/docs/ko/env-vars)을 설정하여 모든 모델의 세션이 [해당 경계에서 압축](#set-the-auto-compact-window)되도록 하세요.

799 801

8001M 컨텍스트를 끄려면, `CLAUDE_CODE_DISABLE_1M_CONTEXT=1`을 설정하세요. Claude Code는 모델 선택기에서 1M 모델 변형을 제거합니다. Sonnet 5 및 Fable 모델과 같이 기본 1M 윈도우가 있는 모델에서, 모델을 200K 컨텍스트 윈도우로 취급합니다:8021M 컨텍스트를 끄려면, `CLAUDE_CODE_DISABLE_1M_CONTEXT=1`을 설정하세요. Claude Code는 모델 선택기에서 1M 모델 변형을 제거합니다. Sonnet 5 및 Fable 모델과 같이 기본 1M 윈도우가 있는 모델에서, 모델을 200K 컨텍스트 윈도우로 취급합니다:

801 803

804 806

805v2.1.223 이전에는 Claude Code가 Sonnet 5, Opus 4.8 및 Opus 5 세션만 200K로 유지했습니다. [환경 변수](/docs/ko/env-vars)를 참조하세요.807v2.1.223 이전에는 Claude Code가 Sonnet 5, Opus 4.8 및 Opus 5 세션만 200K로 유지했습니다. [환경 변수](/docs/ko/env-vars)를 참조하세요.

806 808

8071M 컨텍스트 윈도우는 200K를 초과하는 토큰에 대한 프리미엄 없이 표준 모델 가격을 사용합니다. 확장 컨텍스트가 구독에 포함된 플랜의 경우, 사용은 구독으로 계속 적용됩니다. 확장 컨텍스트에 사용 크레딧을 통해 액세스하는 플랜의 경우, 토큰은 사용 크레딧으로 청구됩니다.8091M 컨텍스트 윈도우는 200K를 초과하는 토큰에 대한 프리미엄 없이 표준 모델 가격을 사용합니다. 단, Haiku 5.5는 [100K 토큰보다 긴 프롬프트에서 비용이 더 높습니다](#haiku-5-5-context-window-and-pricing). 확장 컨텍스트가 구독에 포함된 플랜의 경우, 사용은 계속 구독에 포함됩니다. 사용량 크레딧을 통해 확장 컨텍스트에 액세스하는 플랜의 경우, 토큰은 사용량 크레딧으로 청구됩니다.

808 810

809계정이 1M 컨텍스트를 지원하면, 옵션이 최신 버전의 Claude Code의 `/model` 선택기에 나타납니다. 보이지 않으면, 세션을 다시 시작하고, 제3자 제공자에서 배포가 `ANTHROPIC_DEFAULT_*_MODEL` 변수로 [모델을 고정](#pin-models-for-third-party-deployments)했는지 확인하세요.811계정이 1M 컨텍스트를 지원하면, 옵션이 최신 버전의 Claude Code의 `/model` 선택기에 나타납니다. 보이지 않으면, 세션을 다시 시작하고, 제3자 제공자에서 배포가 `ANTHROPIC_DEFAULT_*_MODEL` 변수로 [모델을 고정](#pin-models-for-third-party-deployments)했는지 확인하세요.

810 812

831 833

832* **`CLAUDE_CODE_DISABLE_1M_CONTEXT=1`**: 기본 1M 윈도우가 있는 모든 모델의 세션을 200K 윈도우로 유지합니다. [확장 컨텍스트](#extended-context)에서 보류가 적용되는 방식을 참조하세요. 컨텍스트를 제한해야 하는 배포에 유용합니다.834* **`CLAUDE_CODE_DISABLE_1M_CONTEXT=1`**: 기본 1M 윈도우가 있는 모든 모델의 세션을 200K 윈도우로 유지합니다. [확장 컨텍스트](#extended-context)에서 보류가 적용되는 방식을 참조하세요. 컨텍스트를 제한해야 하는 배포에 유용합니다.

833 835

836<h4 id="haiku-5-5-context-window-and-pricing">

837 Haiku 5.5 컨텍스트 윈도우 및 가격

838</h4>

839

840Anthropic API에서, Haiku 5.5는 모든 플랜에서 1M 컨텍스트 윈도우로 실행되며, 선택할 `[1m]` 접미사가 없습니다. 모델 ID는 `claude-haiku-5-5`입니다. 사용하려면 세션에서 `/model claude-haiku-5-5`를 실행하거나, 셸에서 `claude --model claude-haiku-5-5`로 Claude Code를 시작하세요.

841

842Haiku 5.5 요청은 프롬프트가 100K 토큰보다 길면 토큰당 비용이 더 높습니다. 두 요금은 [Anthropic 가격](https://platform.claude.com/docs/en/about-claude/pricing)을 참조하세요.

843

844세션은 기본적으로 약 967K 토큰에서 자동 압축됩니다. 더 일찍 압축하려면, 해당 모델에 대해 [더 작은 자동 압축 윈도우를 설정](#set-the-auto-compact-window)하세요.

845

834<h2 id="context-window-and-auto-compaction">846<h2 id="context-window-and-auto-compaction">

835 컨텍스트 윈도우 및 자동 압축847 컨텍스트 윈도우 및 자동 압축

836</h2>848</h2>

865* [클라우드 세션](/docs/ko/claude-code-on-the-web)은 대화가 모델 제한에 접근할 때 압축합니다.877* [클라우드 세션](/docs/ko/claude-code-on-the-web)은 대화가 모델 제한에 접근할 때 압축합니다.

866* Sonnet 4.6 및 Opus 4.6([확장 컨텍스트](#extended-context) 없음)은 200K 경계에서 압축하며, Opus 4.8 및 이후 버전도 Amazon Bedrock, Google Cloud의 Agent Platform, Microsoft Foundry와 같은 200K 컨텍스트 윈도우로 실행할 때 압축합니다.878* Sonnet 4.6 및 Opus 4.6([확장 컨텍스트](#extended-context) 없음)은 200K 경계에서 압축하며, Opus 4.8 및 이후 버전도 Amazon Bedrock, Google Cloud의 Agent Platform, Microsoft Foundry와 같은 200K 컨텍스트 윈도우로 실행할 때 압축합니다.

867* [`CLAUDE_CODE_DISABLE_1M_CONTEXT=1`](/docs/ko/env-vars)을 설정하면 Sonnet 5 및 Fable 모델과 같이 기본 1M 윈도우가 있는 모델은 200K 경계에서 압축합니다.879* [`CLAUDE_CODE_DISABLE_1M_CONTEXT=1`](/docs/ko/env-vars)을 설정하면 Sonnet 5 및 Fable 모델과 같이 기본 1M 윈도우가 있는 모델은 200K 경계에서 압축합니다.

868* 기본 1M 윈도우로 실행되는 모델은 윈도우가 채워지기 전에 압축되며, 기본적으로 약 967K 토큰에서 압축됩니다. Anthropic API에서는 Sonnet 5, Fable 모델, Opus 4.7 이상이 포함됩니다. Amazon Bedrock, Google Cloud의 Agent Platform, Microsoft Foundry에서는 [타사 배포를 위한 모델 고정](#pin-models-for-third-party-deployments)에서 해당 윈도우로 실행되는 모델을 참조하십시오. 사용자 정의 `ANTHROPIC_BASE_URL` 뒤에서는 [게이트웨이 뒤의 컨텍스트 윈도우](#context-window-behind-a-gateway)를 참조하십시오.880* 기본 1M 윈도우로 실행되는 모델은 윈도우가 채워지기 전에 압축되며, 기본적으로 약 967K 토큰에서 압축됩니다. Anthropic API에서는 Sonnet 5, Haiku 5.5, Fable 모델, Opus 4.7 이상이 포함됩니다. Amazon Bedrock, Google Cloud의 Agent Platform, Microsoft Foundry에서는 [타사 배포를 위한 모델 고정](#pin-models-for-third-party-deployments)에서 해당 윈도우로 실행되는 모델을 참조하십시오. 사용자 정의 `ANTHROPIC_BASE_URL` 뒤에서는 [게이트웨이 뒤의 컨텍스트 윈도우](#context-window-behind-a-gateway)를 참조하십시오.

869* Claude Code가 인식하지 못하는 모델 ID(예: [LLM 게이트웨이](/docs/ko/llm-gateway) 별칭)의 세션은 Claude Code가 ID에 대해 가정하는 컨텍스트 윈도우에서 압축합니다. [게이트웨이 또는 사용자 정의 모델 ID의 윈도우 수정](#correct-the-window-for-a-gateway-or-custom-model-id)을 참조하십시오.881* Claude Code가 인식하지 못하는 모델 ID(예: [LLM 게이트웨이](/docs/ko/llm-gateway) 별칭)의 세션은 Claude Code가 ID에 대해 가정하는 컨텍스트 윈도우에서 압축합니다. [게이트웨이 또는 사용자 정의 모델 ID의 윈도우 수정](#correct-the-window-for-a-gateway-or-custom-model-id)을 참조하십시오.

870 882

871<h3 id="correct-the-window-for-a-gateway-or-custom-model-id">883<h3 id="correct-the-window-for-a-gateway-or-custom-model-id">

1093 1105

1094| 버전 | 변경 사항 |1106| 버전 | 변경 사항 |

1095| :- | :- |1107| :- | :- |

1108| v2.1.293 | `haiku`는 Anthropic API에서 Haiku 5.5로 해석됩니다 |

1096| v2.1.284 | `sonnet`은 Anthropic API에서 Sonnet 5.5로 해석됩니다 |1109| v2.1.284 | `sonnet`은 Anthropic API에서 Sonnet 5.5로 해석됩니다 |

1097| v2.1.280 | `opus`는 Anthropic API, AWS의 Claude Platform, Amazon Bedrock 및 Google Cloud의 Agent Platform에서 Opus 5.5로 해석됩니다 |1110| v2.1.280 | `opus`는 Anthropic API, AWS의 Claude Platform, Amazon Bedrock 및 Google Cloud의 Agent Platform에서 Opus 5.5로 해석됩니다 |

1098| v2.1.257 | `fable`은 Claude 앱 게이트웨이 세션을 제외하고 Fable 5.1로 해석됩니다 |1111| v2.1.257 | `fable`은 Claude 앱 게이트웨이 세션을 제외하고 Fable 5.1로 해석됩니다 |

1100| v2.1.207 | `opus`는 AWS의 Claude Platform, Amazon Bedrock 및 Agent Platform에서 Opus 4.8로 해석됩니다 |1113| v2.1.207 | `opus`는 AWS의 Claude Platform, Amazon Bedrock 및 Agent Platform에서 Opus 4.8로 해석됩니다 |

1101| v2.1.197 | `sonnet`은 Anthropic API에서 Sonnet 5로 해석됩니다 |1114| v2.1.197 | `sonnet`은 Anthropic API에서 Sonnet 5로 해석됩니다 |

1102| v2.1.154 | `opus`는 Anthropic API에서 Opus 4.8로 해석됩니다 |1115| v2.1.154 | `opus`는 Anthropic API에서 Opus 4.8로 해석됩니다 |

1103| 이전 버전 | `opus`는 AWS의 Claude Platform에서 Opus 4.7로, Amazon Bedrock 및 Agent Platform에서 Opus 4.6으로 해석됩니다. `fable`은 모든 제공자에서 Fable 5로 해석됩니다 |1116| 이전 버전 | `opus`는 AWS의 Claude Platform에서 Opus 4.7로, Amazon Bedrock 및 Agent Platform에서 Opus 4.6으로 해석됩니다. 모든 제공자에서 `fable`은 Fable 5로, `haiku`는 Haiku 4.5로 해석됩니다 |

monitoring-usage.md +1 −1

Details

551* **서버 관리 설정**: 조직의 [서버 관리 설정](/docs/ko/server-managed-settings)의 `env` 블록에 추가합니다. Claude Code는 [서버 관리 설정이 적용되는](/docs/ko/model-config#surface-coverage) 모든 곳(사용자의 머신 및 Claude Tag 채널 세션 이외의 클라우드 세션 포함)에서 시작 시 해당 설정을 가져옵니다. Claude Tag 세션은 서버 관리 설정을 받지 않으므로, 이 방법은 이들을 구성하지 않습니다.551* **서버 관리 설정**: 조직의 [서버 관리 설정](/docs/ko/server-managed-settings)의 `env` 블록에 추가합니다. Claude Code는 [서버 관리 설정이 적용되는](/docs/ko/model-config#surface-coverage) 모든 곳(사용자의 머신 및 Claude Tag 채널 세션 이외의 클라우드 세션 포함)에서 시작 시 해당 설정을 가져옵니다. Claude Tag 세션은 서버 관리 설정을 받지 않으므로, 이 방법은 이들을 구성하지 않습니다.

552* **환경의 변수**: 클라우드 환경의 [환경 변수](/docs/ko/cloud-environments#set-environment-variables)에 추가하여 해당 환경에서 실행되는 세션만 구성합니다. 이것이 Claude Tag 세션에 도달하는 방법입니다.552* **환경의 변수**: 클라우드 환경의 [환경 변수](/docs/ko/cloud-environments#set-environment-variables)에 추가하여 해당 환경에서 실행되는 세션만 구성합니다. 이것이 Claude Tag 세션에 도달하는 방법입니다.

553 553

554환경을 사용하는 모든 사람이 해당 변수를 읽을 수 있으므로, 수집기 토큰(예: `OTEL_EXPORTER_OTLP_HEADERS`)과 같은 자격 증명을 거기에 넣지 마십시오. 환경의 [API 자격 증명](/docs/ko/cloud-environments#add-api-credentials)도 도움이 되지 않습니다. Claude Code의 자체 텔레메트리 내보내기는 [자격 증명을 받지 않는 요청](/docs/ko/cloud-environments#requests-that-never-get-the-credential) 중 하나이기 때문입니다. 수집기에 자격 증명이 필요한 경우, 서버 관리 설정을 통해 전체 내보내기를 구성하십시오. 자격 증명을 설정하면 [Claude Code는 관리 설정 외부에서 설정된 엔드포인트 변수를 제거합니다](#how-managed-settings-lock-the-otlp-destination).554환경을 사용하는 모든 사람이 해당 변수를 읽을 수 있으므로, 수집기 토큰(예: `OTEL_EXPORTER_OTLP_HEADERS`)과 같은 자격 증명을 거기에 넣지 마십시오. 환경의 [네트워크 시크릿](/docs/ko/cloud-environments#add-api-credentials)도 도움이 되지 않습니다. Claude Code의 자체 텔레메트리 내보내기는 [시크릿을 받지 않는 요청](/docs/ko/cloud-environments#requests-that-never-get-the-credential) 중 하나이기 때문입니다. 수집기에 자격 증명이 필요한 경우, 서버 관리 설정을 통해 전체 내보내기를 구성하십시오. 거기에 자격 증명을 설정하면 [Claude Code는 관리형 설정 외부에서 설정된 엔드포인트 변수를 제거합니다](#how-managed-settings-lock-the-otlp-destination).

555 555

556클라우드 세션에 대한 텔레메트리를 구성할 때 다음 제약 사항을 염두에 두십시오:556클라우드 세션에 대한 텔레메트리를 구성할 때 다음 제약 사항을 염두에 두십시오:

557 557

overview.md +8 −6

Details

28 curl -fsSL https://claude.ai/install.sh | bash28 curl -fsSL https://claude.ai/install.sh | bash

29 ```29 ```

30 30

31 Windows에서 PowerShell에 있을 때는 프롬프트에 `PS C:\`가 표시되고, CMD에 있을 때는 `PS` 없이 `C:\`만 표시됩니다.

31 **Windows PowerShell:**33 **Windows PowerShell:**

32 34

33 ```powershell theme={null}35 ```powershell theme={null}

42 44

43 설치 프로그램이 완료되면 새 터미널 창을 열고 `claude --version`을 실행하십시오. 설치가 제대로 되었으면 버전 번호가 출력됩니다. 셸에서 `claude`를 찾을 수 없거나 인식되지 않는다고 표시되면 설치 디렉토리가 아직 PATH에 없는 것입니다. [PATH 수정](/docs/ko/troubleshoot-install#command-not-found-claude-after-installation)을 참조하십시오.45 설치 프로그램이 완료되면 새 터미널 창을 열고 `claude --version`을 실행하십시오. 설치가 제대로 되었으면 버전 번호가 출력됩니다. 셸에서 `claude`를 찾을 수 없거나 인식되지 않는다고 표시되면 설치 디렉토리가 아직 PATH에 없는 것입니다. [PATH 수정](/docs/ko/troubleshoot-install#command-not-found-claude-after-installation)을 참조하십시오.

44 46

45 `The token '&&' is not a valid statement separator` 오류가 표시되면 CMD가 아닌 PowerShell에 있는 것입니다. `'irm' is not recognized as an internal or external command` 오류가 표시되면 PowerShell이 아닌 CMD에 있는 것입니다. PowerShell에 있을 때는 프롬프트에 `PS C:\`가 표시되고, CMD에 있을 때는 `PS` 없이 `C:\`만 표시됩니다.47 `The token '&&' is not a valid statement separator` 오류가 표시되면 CMD가 아닌 PowerShell에 있는 것입니다. `'irm' is not recognized as an internal or external command` 오류가 표시되면 PowerShell이 아닌 CMD에 있는 것입니다.

46 48

47 설치 명령이 `syntax error near unexpected token '<'`, `403` 또는 다른 curl 오류로 실패하면 [설치 문제 해결](/docs/ko/troubleshoot-install#find-your-error)을 참조하여 오류를 수정 방법과 일치시키고 대체 설치 방법을 확인하십시오.49 설치 명령이 `syntax error near unexpected token '<'`, `403` 또는 다른 오류로 실패하면 [설치 문제 해결](/docs/ko/troubleshoot-install#find-your-error)을 참조하여 오류를 수정 방법과 일치시키고 대체 설치 방법을 확인하십시오.

48 50

49 [Git for Windows](https://git-scm.com/downloads/win)는 Claude Code가 Bash 도구를 사용할 수 있도록 기본 Windows에서 권장됩니다. Git for Windows가 설치되지 않은 경우 Claude Code는 대신 PowerShell을 셸 도구로 사용합니다. WSL 설정에는 Git for Windows가 필요하지 않습니다.51 [Git for Windows](https://git-scm.com/downloads/win)는 Claude Code가 Bash 도구를 사용할 수 있도록 기본 Windows에서 권장됩니다. Git for Windows가 설치되지 않은 경우 Claude Code는 대신 PowerShell을 셸 도구로 사용합니다. WSL 설정에는 Git for Windows가 필요하지 않습니다.

50 52

85 claude87 claude

86 ```88 ```

87 89

88 처음 사용할 때 로그인하라는 메시지가 표시됩니다. `ANTHROPIC_API_KEY` 환경 변수를 설정한 경우 Claude Code는 로그인 프롬프트를 건너뛰고 대신 키를 승인하도록 요청합니다. 이제 끝입니다! [빠른 시작으로 계속하기 →](/docs/ko/quickstart)90 Claude Code는 처음 사용할 때 로그인을 요청합니다. `ANTHROPIC_API_KEY` 환경 변수를 설정했고 Claude Code가 키 사용 여부를 물을 때 키를 승인하면 Claude Code는 로그인 프롬프트를 건너뜁니다. [빠른 시작으로 계속하기 →](/docs/ko/quickstart)

89 91

90 <Tip>92 <Tip>

91 [고급 설정](/docs/ko/setup)에서 설치 옵션, 수동 업데이트 또는 제거 지침을 참조하세요. 문제가 발생하면 [설치 문제 해결](/docs/ko/troubleshoot-install)을 방문하세요.93 [고급 설정](/docs/ko/setup)에서 설치 옵션, 수동 업데이트 또는 제거 지침을 참조하세요. 문제가 발생하면 [설치 문제 해결](/docs/ko/troubleshoot-install)을 방문하세요.

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

164 ```166 ```

165 167

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

167 </Accordion>169 </Accordion>

168 170

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

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

171 </Accordion>173 </Accordion>

172 174

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

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

175 177

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

177 179

permission-modes.md +5 −5

Details

233 </Tab>233 </Tab>

234 234

235 <Tab title="Web and mobile">235 <Tab title="Web and mobile">

236 [claude.ai/code](https://claude.ai/code)의 모드 드롭다운 또는 모바일 앱의 프롬프트 상자 옆을 사용합니다. 권한 프롬프트는 승인을 위해 claude.ai에 나타납니다. 나타나는 모드는 세션이 실행되는 위치에 따라 달라집니다:236 [claude.ai/code](https://claude.ai/code)에서는 프롬프트 상자 옆의 모드 드롭다운을 사용합니다. 모바일 앱에서는 프롬프트 상자의 **+** 버튼을 탭한 다음 **Permission**을 탭합니다. 클라우드 세션과 Remote Control 세션은 서로 다른 권한 모드를 제공합니다:

237 237

238 * **[Claude Code on the web](/docs/ko/claude-code-on-the-web)의 클라우드 세션**: Accept edits, Plan, and Auto. Accept edits는 `default` 모드에 해당합니다: 클라우드 세션은 모드에 관계없이 파일 편집을 사전 승인하므로 드롭다운은 Manual 대신 Accept edits를 표시합니다. 클라우드 세션은 여전히 설정의 `defaultMode: "acceptEdits"`를 준수합니다. Auto mode는 조직이 허용하고 선택한 모델이 지원할 때만 나타납니다. Bypass permissions는 사용할 수 없습니다.238 * **[클라우드 세션](/docs/ko/claude-code-on-the-web)**: Accept edits, Plan, Auto. Accept edits는 `default` 모드에 해당합니다: 클라우드 세션은 모드에 관계없이 파일 편집을 사전 승인하므로 드롭다운은 Manual 대신 Accept edits를 표시합니다. 클라우드 세션은 여전히 설정의 `defaultMode: "acceptEdits"`를 준수합니다. 자동 모드는 조직이 허용하고 선택한 모델이 지원할 때만 나타납니다. Bypass permissions는 사용할 수 없습니다.

239 * **로컬 머신의 [Remote Control](/docs/ko/remote-control) 세션**: 자신이 시작한 세션의 경우 Manual, Accept edits, and Plan이며, 앱에서 Auto 또는 Bypass permissions를 선택할 수 없습니다. 컴퓨터에서 실행 중인 프로젝트 스레드의 경우 [자신의 컴퓨터에서 스레드 실행](/docs/ko/claude-projects#run-a-thread-on-your-own-computer)을 참조하세요.239 * **로컬 머신의 [Remote Control](/docs/ko/remote-control) 세션**: 직접 시작한 세션의 경우 Manual, Accept edits, Plan, Auto이며, 앱에서 Bypass permissions를 선택할 수 없습니다. Auto를 사용하려면 세션이 자동 모드 [사용 가능 요건](#eliminate-prompts-with-auto-mode)을 충족해야 합니다. 컴퓨터에서 실행 중인 프로젝트 스레드의 경우 [자신의 컴퓨터에서 스레드 실행](/docs/ko/claude-projects#run-a-thread-on-your-own-computer)을 참조하세요.

240 * Bypass permissions 제외, 드롭다운은 터미널에서 설정된 모드를 포함하여 로컬 세션이 있는 권한 모드를 표시합니다. 앱 또는 터미널에서 권한 모드가 변경될 때 업데이트됩니다.240 * Bypass permissions 제외, 드롭다운은 터미널에서 설정된 모드를 포함하여 로컬 세션이 있는 권한 모드를 표시합니다. 앱 또는 터미널에서 권한 모드가 변경될 때 업데이트됩니다.

241 * [desktop app](/docs/ko/desktop) 또는 [VS Code extension](/docs/ko/vs-code)이 호스팅하는 세션은 터미널에서 호스팅하는 세션과 동일하게 발생할 때 claude.ai에 권한 모드 변경을 보고합니다.241 * [desktop app](/docs/ko/desktop) 또는 [VS Code extension](/docs/ko/vs-code)이 호스팅하는 세션은 터미널에서 호스팅하는 세션과 동일하게 발생할 때 claude.ai에 권한 모드 변경을 보고합니다.

242 * v2.1.202 이전에는 `/remote-control` 또는 `claude --remote-control`로 연결된 세션이 모드를 전혀 보고하지 않았으므로 claude.ai 및 모바일 앱이 세션이 실제로 있지 않은 권한 모드를 표시할 수 있었습니다. 불일치는 레이블에만 영향을 미쳤습니다. Claude Code는 세션의 실제 권한 모드에서 권한 프롬프트를 생성했으며, 여전히 승인을 위해 앱에 나타났습니다.242 * v2.1.202 이전에는 `/remote-control` 또는 `claude --remote-control`로 연결된 세션이 모드를 전혀 보고하지 않았으므로 claude.ai 및 모바일 앱이 세션이 실제로 있지 않은 권한 모드를 표시할 수 있었습니다. 불일치는 레이블에만 영향을 미쳤습니다. Claude Code는 세션의 실제 권한 모드에서 권한 프롬프트를 생성했으며, 여전히 승인을 위해 앱에 나타났습니다.

333 333

334* **플랜**: 모든 플랜.334* **플랜**: 모든 플랜.

335* **조직**: Team 및 Enterprise에서는 자동 모드를 기본적으로 사용할 수 있습니다. 관리자는 [관리형 설정](/docs/ko/managed-settings)에서 `permissions.disableAutoMode`를 `"disable"`로 설정하여 조직에 대해 이를 끌 수 있습니다.335* **조직**: Team 및 Enterprise에서는 자동 모드를 기본적으로 사용할 수 있습니다. 관리자는 [관리형 설정](/docs/ko/managed-settings)에서 `permissions.disableAutoMode`를 `"disable"`로 설정하여 조직에 대해 이를 끌 수 있습니다.

336* **모델**: Anthropic API 및 [AWS의 Claude Platform](/docs/ko/claude-platform-on-aws)에서는 Claude Opus 4.6 이상, Sonnet 4.6 이상 또는 [Fable 모델](/docs/ko/model-config#work-with-fable). Amazon Bedrock, Google Cloud의 Agent Platform, Microsoft Foundry 및 로그인한 [Claude 앱 게이트웨이](/docs/ko/claude-apps-gateway) 세션에서는 Claude Sonnet 5 이상, Opus 4.7 이상 및 Fable 모델만 해당합니다. Sonnet 4.5, Opus 4.5, Haiku 및 claude-3 모델을 포함한 이전 모델은 어떤 제공자에서도 지원되지 않습니다.336* **모델**: Anthropic API 및 [AWS의 Claude Platform](/docs/ko/claude-platform-on-aws)에서는 Claude Opus 4.6 이상, Sonnet 4.6 이상, Haiku 5.5 또는 [Fable 모델](/docs/ko/model-config#work-with-fable). Amazon Bedrock, Google Cloud의 Agent Platform, Microsoft Foundry 및 로그인한 [Claude 앱 게이트웨이](/docs/ko/claude-apps-gateway) 세션에서는 Claude Sonnet 5 이상, Opus 4.7 이상, Haiku 5.5 및 Fable 모델만 해당합니다. Sonnet 4.5, Opus 4.5, Haiku 4.5 및 claude-3 모델을 포함한 이전 모델은 어떤 제공자에서도 지원되지 않습니다.

337* **제공자**: Anthropic API, AWS의 Claude Platform, Amazon Bedrock, Google Cloud의 Agent Platform, Microsoft Foundry 및 로그인한 Claude 앱 게이트웨이 세션에서 기본적으로 사용 가능합니다.337* **제공자**: Anthropic API, AWS의 Claude Platform, Amazon Bedrock, Google Cloud의 Agent Platform, Microsoft Foundry 및 로그인한 Claude 앱 게이트웨이 세션에서 기본적으로 사용 가능합니다.

338 338

339Claude Code가 자동 모드를 사용할 수 없다고 보고하면 먼저 이러한 요구 사항과 설정 파일이 [`disableAutoMode`](/docs/ko/settings-reference#disableautomode)를 설정하는지 확인하세요. Anthropic은 또한 서버 측에서 자동 모드를 끄거나 서버가 계정에 대해 자동 모드를 거부했을 수 있습니다. 어느 한 답변을 받은 세션은 세션이 끝날 때까지 자동 모드를 끈 상태로 유지하므로 나중에 새 세션을 시작하세요.339Claude Code가 자동 모드를 사용할 수 없다고 보고하면 먼저 이러한 요구 사항과 설정 파일이 [`disableAutoMode`](/docs/ko/settings-reference#disableautomode)를 설정하는지 확인하세요. Anthropic은 또한 서버 측에서 자동 모드를 끄거나 서버가 계정에 대해 자동 모드를 거부했을 수 있습니다. 어느 한 답변을 받은 세션은 세션이 끝날 때까지 자동 모드를 끈 상태로 유지하므로 나중에 새 세션을 시작하세요.

348 348

349[Amazon Bedrock](/docs/ko/amazon-bedrock), [Google Cloud의 Agent Platform](/docs/ko/google-vertex-ai), [Microsoft Foundry](/docs/ko/microsoft-foundry) 및 로그인한 [Claude 앱 게이트웨이](/docs/ko/claude-apps-gateway) 세션에서는 자동 모드를 기본적으로 사용할 수 있습니다. 다른 것이 권한 모드를 설정하지 않으면 해당 섹션의 테이블이 나열하는 버전에서도 [기본 제공 시작 권한 모드](#which-mode-a-session-starts-in)입니다. 시작 권한 모드를 직접 선택하려면 [다른 권한 모드에서 시작](#start-in-a-different-mode)이 설명하는 대로 `permissions.defaultMode`를 설정하거나 VS Code 확장의 모드 표시기에서 권한 모드를 선택하세요.349[Amazon Bedrock](/docs/ko/amazon-bedrock), [Google Cloud의 Agent Platform](/docs/ko/google-vertex-ai), [Microsoft Foundry](/docs/ko/microsoft-foundry) 및 로그인한 [Claude 앱 게이트웨이](/docs/ko/claude-apps-gateway) 세션에서는 자동 모드를 기본적으로 사용할 수 있습니다. 다른 것이 권한 모드를 설정하지 않으면 해당 섹션의 테이블이 나열하는 버전에서도 [기본 제공 시작 권한 모드](#which-mode-a-session-starts-in)입니다. 시작 권한 모드를 직접 선택하려면 [다른 권한 모드에서 시작](#start-in-a-different-mode)이 설명하는 대로 `permissions.defaultMode`를 설정하거나 VS Code 확장의 모드 표시기에서 권한 모드를 선택하세요.

350 350

351이러한 제공자에서는 Claude Sonnet 5 이상, Opus 4.7 이상 및 Fable 모델만 지원됩니다. 다른 모델에서는 세션이 Manual로 시작됩니다.351이러한 제공자에서는 Claude Sonnet 5 이상, Opus 4.7 이상, Haiku 5.5 및 Fable 모델만 지원됩니다. 다른 모델에서는 세션이 Manual로 시작됩니다. 이러한 제공자에서 Haiku 5.5로 자동 모드를 사용하려면 Claude Code v2.1.293 이상이 필요합니다.

352 352

353개발자가 자동 모드를 사용하지 못하도록 하려면 [관리형 설정](/docs/ko/managed-settings)에서 `disableAutoMode`를 `"disable"`로 설정하세요. 이렇게 하면 `Shift+Tab` 사이클에서 `auto`가 제거되고, `--permission-mode auto`로 시작된 세션은 Manual로 시작됩니다. 이미 자동 모드로 실행 중인 세션은 설정이 [관리자 배포 소스](/docs/ko/managed-settings#which-managed-source-claude-code-uses)에서 해당 세션에 도달할 때 이를 떠나고 `auto mode disabled by settings`를 표시합니다. v2.1.251 이전에는 실행 중인 세션이 끝날 때까지 자동 모드를 유지했습니다.353개발자가 자동 모드를 사용하지 못하도록 하려면 [관리형 설정](/docs/ko/managed-settings)에서 `disableAutoMode`를 `"disable"`로 설정하세요. 이렇게 하면 `Shift+Tab` 사이클에서 `auto`가 제거되고, `--permission-mode auto`로 시작된 세션은 Manual로 시작됩니다. 이미 자동 모드로 실행 중인 세션은 설정이 [관리자 배포 소스](/docs/ko/managed-settings#which-managed-source-claude-code-uses)에서 해당 세션에 도달할 때 이를 떠나고 `auto mode disabled by settings`를 표시합니다. v2.1.251 이전에는 실행 중인 세션이 끝날 때까지 자동 모드를 유지했습니다.

354 354

plugin-evals.md +7 −3

Details

67 67

68* Claude Code v2.1.269 이상 및 기타 [요구사항](#requirements)68* Claude Code v2.1.269 이상 및 기타 [요구사항](#requirements)

69* 플러그인의 루트 디렉토리에서 열린 터미널, `plugin.json` 또는 `.claude-plugin/plugin.json`을 포함하는 디렉토리69* 플러그인의 루트 디렉토리에서 열린 터미널, `plugin.json` 또는 `.claude-plugin/plugin.json`을 포함하는 디렉토리

~~70* 테스트하려는 플러그인의 스킬 하나, 그리고 사용자가 입력할 요청으로 스킬을 트리거해야 합니다.~~70* 테스트하려는 플러그인의 스킬 하나, 그리고 해당 스킬을 트리거해야 하는, 사용자가 입력할 만한 요청

71 71

72<Steps>72<Steps>

73 <Step title="케이스 만들기">73 <Step title="케이스 만들기">

77 claude plugin eval init77 claude plugin eval init

78 ```78 ```

79 79

80 Claude Code가 이 디렉토리를 아직 신뢰하지 않으면 먼저 `Trust this plugin directory?`를 묻습니다. `y`로 답합니다. 그러면 대화형 Claude Code 세션이 열립니다. Claude는 플러그인을 읽고 좋은 결과가 무엇인지 묻고, 플러그인을 트리거해야 하고 트리거하지 않아야 하는 프롬프트를 제안하고, 각각에 대해 채점자를 설계하고, 한 번 시도하여 동작을 확인하고, 프롬프트 이름을 따서 `evals/` 아래에 케이스 디렉토리를 작성합니다. Claude가 모음이 준비되었다고 말하면 `/exit` 또는 Ctrl+D로 해당 세션을 종료하여 셸로 돌아갑니다.80 Claude Code가 이 디렉토리를 아직 신뢰하지 않으면 먼저 `Trust this plugin directory?`를 묻습니다. `y`로 답합니다.

82 그러면 대화형 Claude Code 세션이 열립니다. Claude는 플러그인을 읽고 좋은 결과가 무엇인지 묻고, 플러그인을 트리거해야 하고 트리거하지 않아야 하는 프롬프트를 제안하고, 각각에 대해 채점자를 설계하고, 시험 삼아 한 번 실행하여 동작을 확인한 다음, `evals/` 아래에 프롬프트마다 하나씩 프롬프트 이름을 딴 케이스 디렉토리를 작성합니다.

84 Claude가 모음이 준비되었다고 말하면 `/exit` 또는 Ctrl+D로 해당 세션을 종료하여 셸로 돌아갑니다.

81 85

82 플러그인 루트에서 이미 Claude Code 세션이 열려 있으면 대신 Claude에게 `claude plugin eval init`을 실행하도록 요청할 수 있습니다. Claude는 명령을 실행한 다음 해당 대화에서 동일한 질문을 합니다.86 플러그인 루트에서 이미 Claude Code 세션이 열려 있으면 대신 Claude에게 `claude plugin eval init`을 실행하도록 요청할 수 있습니다. Claude는 명령을 실행한 다음 해당 대화에서 동일한 질문을 합니다.

83 87

116 120

117 가장 일반적인 첫 번째 발견은 `Δ`가 0에 가깝고 케이스의 `tool_used: Skill` 채점자가 실패하는 것입니다. 이는 Claude가 자연스러운 표현에서 스킬을 선택하지 않음을 의미합니다. 스킬의 [`description`](/docs/ko/skills#frontmatter-reference)을 조정하고, `claude plugin eval .`을 다시 실행하고, 비교합니다.121 가장 일반적인 첫 번째 발견은 `Δ`가 0에 가깝고 케이스의 `tool_used: Skill` 채점자가 실패하는 것입니다. 이는 Claude가 자연스러운 표현에서 스킬을 선택하지 않음을 의미합니다. 스킬의 [`description`](/docs/ko/skills#frontmatter-reference)을 조정하고, `claude plugin eval .`을 다시 실행하고, 비교합니다.

118 122

119 하나의 케이스를 저렴하게 반복하려면 단일 arm을 한 번 실행합니다. 단일 실행은 노이즈가 많으므로 신뢰하기 전에 기본 3번 실행에서 변경을 확인합니다. 하나의 arm으로 표는 `WITH`, `W/OUT`, `Δ` 열 대신 `SCORE`와 `PASS%` 열을 표시합니다.123 더 적은 실행 횟수로 하나의 케이스를 반복하려면 단일 arm을 한 번 실행합니다. 단일 실행은 노이즈가 많으므로 신뢰하기 전에 기본 3번 실행에서 변경을 확인합니다. 하나의 arm으로 표는 `WITH`, `W/OUT`, `Δ` 열 대신 `SCORE`와 `PASS%` 열을 표시합니다.

120 124

121 ```bash theme={null}125 ```bash theme={null}

122 claude plugin eval . --case <case-name> --runs 1 --ablation none126 claude plugin eval . --case <case-name> --runs 1 --ablation none

plugins/components.md +1 −1

Details

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

734```734```

735 735

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

737 737

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

739 739

plugins/mods/interface.md +5 −3

Details

428 428

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

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

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

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

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

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

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

564 564

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

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

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

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

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

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

571```571```

572 572

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

574

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

574 576

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

plugins/mods/reference.md +23 −2

Details

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

243 243

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

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

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

247 247

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

255 255

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

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

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

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

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

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

270 270

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

272 272

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

274 `Box` 테두리 스타일

275</h3>

276

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

278

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

280| :- | :- | :- |

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

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

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

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

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

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

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

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

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

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

291

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

293

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

274 제한295 제한

275</h2>296</h2>

plugins/troubleshooting.md +1 −0

Details

17 17

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

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

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

20</Note>21</Note>

21 22

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

prompt-caching.md +20 −20

Details

32 32

33대화 계층의 변경은 시스템 프롬프트와 프로젝트 컨텍스트를 캐시된 상태로 유지합니다. 시스템 프롬프트의 변경은 모든 것을 무효화합니다. 왜냐하면 이제 모든 이후 콘텐츠가 다른 프리픽스 뒤에 있기 때문입니다. 세 번째 열은 완전한 목록이 아닌 일반적인 트리거를 제공하며, 아래 섹션에서 전체 집합을 다룹니다.33대화 계층의 변경은 시스템 프롬프트와 프로젝트 컨텍스트를 캐시된 상태로 유지합니다. 시스템 프롬프트의 변경은 모든 것을 무효화합니다. 왜냐하면 이제 모든 이후 콘텐츠가 다른 프리픽스 뒤에 있기 때문입니다. 세 번째 열은 완전한 목록이 아닌 일반적인 트리거를 제공하며, 아래 섹션에서 전체 집합을 다룹니다.

34 34

35프리픽스 일치 규칙은 이 페이지의 대부분의 동작을 설명합니다. 예를 들어 [Plan Mode](/docs/ko/permission-modes#analyze-before-you-edit-with-plan-mode)와 [skill loading](/docs/ko/skills)은 지침을 대화 메시지로 추가하므로 캐시된 프리픽스는 그대로 유지됩니다.35프리픽스 일치 규칙은 이 페이지의 대부분의 동작을 설명합니다. 예를 들어 [플랜 모드](/docs/ko/permission-modes#analyze-before-you-edit-with-plan-mode)와 [스킬 로딩](/docs/ko/skills)은 지침을 대화 메시지로 추가하므로 캐시된 프리픽스는 그대로 유지됩니다.

36 36

37두 가지 설정은 계층 표에 나타나지 않지만 여전히 캐시된 상태에 영향을 미칩니다:37두 가지 설정은 계층 표에 나타나지 않지만 여전히 캐시된 상태에 영향을 미칩니다:

38 38

39* **모델**: 각 모델은 자체 캐시를 가집니다. 모델을 전환하면 콘텐츠가 동일한 경우에도 전체 요청이 다시 계산됩니다. 아래의 [모델 전환](#switching-models)을 참조하세요.39* **모델**: 각 모델은 자체 캐시를 가집니다. 모델을 전환하면 콘텐츠가 동일한 경우에도 전체 요청이 다시 계산됩니다. 아래의 [모델 전환](#switching-models)을 참조하세요.

40* **노력 수준**: 대부분의 모델에서 각 노력 수준은 자체 캐시를 가지므로 세션 중에 노력을 변경하면 전체 요청이 다시 계산됩니다. API 키 또는 Claude 구독이 있는 Opus 5.5, Sonnet 5.5 및 Fable 5.1에서는 기본적으로 캐시가 그대로 유지됩니다. 아래의 [노력 수준 변경](#changing-effort-level)을 참조하세요.40* **effort 수준**: 대부분의 모델에서 각 effort 수준은 자체 캐시를 가지므로 세션 중에 effort를 변경하면 전체 요청이 다시 계산됩니다. API 키 또는 Claude 구독이 있는 Opus 5.5, Sonnet 5.5, Haiku 5.5 및 Fable 5.1에서는 기본적으로 캐시가 그대로 유지됩니다. 아래의 [effort 수준 변경](#changing-effort-level)을 참조하세요.

41 41

42<Tip>42<Tip>

43 세션 시작 시 모델과 노력 수준을 선택한 다음 작업 간의 자연스러운 중단점을 위해 `/compact`를 저장하세요. 작업 중에 변경을 적게 할수록 캐시 히트율이 높아집니다.43 세션 시작 시 모델과 effort 수준을 선택한 다음 작업 간의 자연스러운 중단점을 위해 `/compact`를 저장하세요. 작업 중에 변경을 적게 할수록 캐시 히트율이 높아집니다.

44</Tip>44</Tip>

45 45

46<h3 id="where-the-cache-lives">46<h3 id="where-the-cache-lives">

73다음 작업들은 다음 요청이 캐시의 일부 또는 전부를 놓치게 할 수 있습니다. 한 번 느리고 비용이 더 많이 드는 턴을 보게 되며, 그 후 새로운 접두사가 캐시됩니다. 대부분은 작업 중간에 비용이 있다는 것을 알면 피할 수 있습니다. 모델 전환은 뒤따르는 느린 턴을 알아차릴 때까지 자유로워 보일 수 있습니다.73다음 작업들은 다음 요청이 캐시의 일부 또는 전부를 놓치게 할 수 있습니다. 한 번 느리고 비용이 더 많이 드는 턴을 보게 되며, 그 후 새로운 접두사가 캐시됩니다. 대부분은 작업 중간에 비용이 있다는 것을 알면 피할 수 있습니다. 모델 전환은 뒤따르는 느린 턴을 알아차릴 때까지 자유로워 보일 수 있습니다.

74 74

75* [모델 전환](#switching-models)75* [모델 전환](#switching-models)

~~76* [노력 수준 변경](#changing-effort-level)~~76* [effort 수준 변경](#changing-effort-level)

77* [빠른 모드 켜기](#turning-on-fast-mode)77* [빠른 모드 켜기](#turning-on-fast-mode)

78* [MCP 서버 연결 또는 제거](#connecting-or-removing-an-mcp-server)78* [MCP 서버 연결 또는 제거](#connecting-or-removing-an-mcp-server)

79* [플러그인 활성화 또는 비활성화](#enabling-or-disabling-a-plugin)79* [플러그인 활성화 또는 비활성화](#enabling-or-disabling-a-plugin)

94 94

95[PreModelSwitch 훅](/docs/ko/hooks#premodelswitch-decision-control)으로 이 확인을 요구하거나 건너뛸 수도 있습니다.95[PreModelSwitch 훅](/docs/ko/hooks#premodelswitch-decision-control)으로 이 확인을 요구하거나 건너뛸 수도 있습니다.

96 96

97[`opusplan` 모델 설정](/docs/ko/model-config#opusplan-model-setting)은 계획 모드 중에는 Opus로, 실행 중에는 Sonnet으로 확인되므로 각 계획 모드 토글은 모델 전환이며 새로운 캐시를 시작합니다.97[`opusplan` 모델 설정](/docs/ko/model-config#opusplan-model-setting)은 플랜 모드 중에는 Opus로, 실행 중에는 Sonnet으로 확인되므로 각 플랜 모드 토글은 모델 전환이며 새로운 캐시를 시작합니다.

98 98

99Fable 모델, Opus 5.5, Sonnet 5.5, Opus 5의 [자동 모델 폴백](/docs/ko/model-config#automatic-model-fallback)도 모델 전환입니다. 안전 분류기가 폴백 모델이 있는 카테고리의 요청에 플래그를 지정하면 Claude Code는 해당 모델에서 요청을 다시 실행하고 세션이 계속됩니다.99Fable 모델, Opus 5.5, Sonnet 5.5, Opus 5의 [자동 모델 폴백](/docs/ko/model-config#automatic-model-fallback)도 모델 전환입니다. 안전 분류기가 폴백 모델이 있는 카테고리의 요청에 플래그를 지정하면 Claude Code는 해당 모델에서 요청을 다시 실행하고 세션이 계속됩니다.

100 100

101스킬 또는 명령의 프론트매터가 세션의 현재 모델이 아닌 다른 [`model`](/docs/ko/skills#frontmatter-reference)을 지정하면 해당 턴도 모델 전환입니다. 다음 요청은 캐시 히트 없이 전체 대화 기록을 읽습니다. 세션 모델은 다음 프롬프트에서 재개됩니다. `context: fork` 스킬은 [포크된 서브에이전트의 모델](/docs/ko/skills#run-skills-in-a-subagent)을 대신 설정합니다.101스킬 또는 명령의 frontmatter가 세션의 현재 모델이 아닌 다른 [`model`](/docs/ko/skills#frontmatter-reference)을 지정하면 해당 턴도 모델 전환입니다. 다음 요청은 캐시 히트 없이 전체 대화 기록을 읽습니다. 세션 모델은 다음 프롬프트에서 재개됩니다. `context: fork` 스킬은 [포크된 서브에이전트의 모델](/docs/ko/skills#run-skills-in-a-subagent)을 대신 설정합니다.

102 102

103<h3 id="changing-effort-level">103<h3 id="changing-effort-level">

104 노력 수준 변경104 effort 수준 변경

105</h3>105</h3>

106 106

107대부분의 모델에서 세션 중간에 [노력 수준](/docs/ko/model-config#adjust-effort-level)을 변경하면 다음 요청이 캐시 히트 없이 전체 대화 기록을 읽습니다. 캐시가 여전히 따뜻한 동안 Claude Code는 먼저 변경을 확인하도록 요청합니다.107대부분의 모델에서 세션 중간에 [effort 수준](/docs/ko/model-config#adjust-effort-level)을 변경하면 다음 요청이 캐시 히트 없이 전체 대화 기록을 읽습니다. 캐시가 여전히 따뜻한 동안 Claude Code는 먼저 변경을 확인하도록 요청합니다.

108 108

109API 키 또는 Claude 구독이 있는 Opus 5.5, Sonnet 5.5, Fable 5.1에서는 노력 수준을 변경해도 캐시가 유지되며 Claude Code는 묻지 않고 새 수준을 적용합니다. 이는 Amazon Bedrock, Google Cloud의 Agent Platform, [Claude 앱 게이트웨이](/docs/ko/claude-apps-gateway)에는 적용되지 않으며, [`CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS`](/docs/ko/llm-gateway-protocol#disable-pre-release-capabilities)를 설정했거나 조직에 HIPAA 구성이 있을 때도 적용되지 않습니다.109API 키 또는 Claude 구독이 있는 Opus 5.5, Sonnet 5.5, Haiku 5.5, Fable 5.1에서는 effort를 변경해도 캐시가 유지되며 Claude Code는 묻지 않고 새 수준을 적용합니다. 이는 Amazon Bedrock, Google Cloud의 Agent Platform, [Claude 앱 게이트웨이](/docs/ko/claude-apps-gateway)에는 적용되지 않으며, [`CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS`](/docs/ko/llm-gateway-protocol#disable-pre-release-capabilities)를 설정했거나 조직에 HIPAA 구성이 있을 때도 적용되지 않습니다.

110 110

111v2.1.260 이전에는 API 키 또는 Claude 구독이 있는 Fable 5.1에서 노력 수준을 변경해도 캐시가 무효화되었습니다.111v2.1.260 이전에는 API 키 또는 Claude 구독이 있는 Fable 5.1에서 effort를 변경해도 캐시가 무효화되었습니다.

112 112

113<h3 id="turning-on-fast-mode">113<h3 id="turning-on-fast-mode">

114 빠른 모드 켜기114 빠른 모드 켜기

116 116

117[빠른 모드](/docs/ko/fast-mode)를 활성화하면 캐시 키의 일부인 요청 헤더가 추가되므로 Claude Code가 빠른 모드를 켜고 보내는 첫 번째 요청은 캐시 히트 없이 전체 대화 기록을 읽습니다. Claude Code는 턴이 시작될 때 해당 헤더를 한 번 설정하고 전체 턴 동안 유지하므로 Claude가 작업 중일 때 빠른 모드를 켜면 헤더로 인한 캐시 미스가 다음 턴의 첫 번째 요청에서 발생합니다. 캐시되지 않은 입력 토큰은 [빠른 모드 요금](/docs/ko/fast-mode#understand-the-cost-tradeoff)으로 청구되므로 세션 시작 시 켜는 것이 긴 세션 깊숙이 켜는 것보다 비용이 적습니다. 현재 모델이 빠른 모드를 지원하지 않으면 빠른 모드를 활성화하면 [모델도 전환](#switching-models)되며, 그 전환은 실행 중인 턴의 다음 요청부터 자체적으로 새로운 캐시를 시작합니다.117[빠른 모드](/docs/ko/fast-mode)를 활성화하면 캐시 키의 일부인 요청 헤더가 추가되므로 Claude Code가 빠른 모드를 켜고 보내는 첫 번째 요청은 캐시 히트 없이 전체 대화 기록을 읽습니다. Claude Code는 턴이 시작될 때 해당 헤더를 한 번 설정하고 전체 턴 동안 유지하므로 Claude가 작업 중일 때 빠른 모드를 켜면 헤더로 인한 캐시 미스가 다음 턴의 첫 번째 요청에서 발생합니다. 캐시되지 않은 입력 토큰은 [빠른 모드 요금](/docs/ko/fast-mode#understand-the-cost-tradeoff)으로 청구되므로 세션 시작 시 켜는 것이 긴 세션 깊숙이 켜는 것보다 비용이 적습니다. 현재 모델이 빠른 모드를 지원하지 않으면 빠른 모드를 활성화하면 [모델도 전환](#switching-models)되며, 그 전환은 실행 중인 턴의 다음 요청부터 자체적으로 새로운 캐시를 시작합니다.

118 118

119비용은 대화당 한 번 적용됩니다. 첫 번째 빠른 모드 턴 후 Claude Code는 계속 헤더를 보내고 캐시 키의 일부가 아닌 요청의 속도 설정만 변합니다. 빠른 모드를 끄기, [속도 제한 후 표준 속도로 자동 폴백](/docs/ko/fast-mode#handle-rate-limits), 나중에 다시 켜기는 모두 캐시를 유지합니다. [사용 크레딧이 부족](/docs/ko/fast-mode#handle-rate-limits)하면 Claude Code는 거부된 각 빠른 모드 요청을 같은 방식으로 표준 속도에서 다시 시도하므로 이 폴백도 캐시를 유지합니다. `/clear`와 `/compact`는 어쨌든 그 지점에서 캐시를 다시 빌드하므로 이를 재설정합니다.119비용은 대화당 한 번 적용됩니다. 첫 번째 빠른 모드 턴 후 Claude Code는 계속 헤더를 보내고 캐시 키의 일부가 아닌 요청의 속도 설정만 변합니다. 빠른 모드를 끄기, [속도 제한 후 표준 속도로 자동 폴백](/docs/ko/fast-mode#handle-rate-limits), 나중에 다시 켜기는 모두 캐시를 유지합니다. 세션 중간에 [사용량 크레딧이 소진](/docs/ko/fast-mode#handle-rate-limits)되면 Claude Code는 거부된 각 빠른 모드 요청을 같은 방식으로 표준 속도에서 재시도하므로 이 폴백도 캐시를 유지합니다. `/clear`와 `/compact`는 어쨌든 그 지점에서 캐시를 다시 빌드하므로 이를 재설정합니다.

120 120

121<h3 id="connecting-or-removing-an-mcp-server">121<h3 id="connecting-or-removing-an-mcp-server">

122 MCP 서버 연결 또는 제거122 MCP 서버 연결 또는 제거

125도구 정의는 시스템 프롬프트 레이어에 있으므로 요청의 도구 정의 집합이 턴 사이에 변경되면 캐시가 무효화됩니다. [어드바이저 도구](/docs/ko/advisor)를 토글하는 것은 예외입니다. 그 정의는 캐시 중단점 이후에 있으므로 `/advisor`를 활성화하거나 비활성화해도 캐시된 접두사가 그대로 유지됩니다. [MCP 서버](/docs/ko/mcp) 변경이 이를 수행하는지 여부는 [도구 검색](/docs/ko/mcp#scale-with-mcp-tool-search)이 세션의 MCP 도구를 지연하는지에 따라 달라집니다. 지원되는 모델의 기본값입니다.125도구 정의는 시스템 프롬프트 레이어에 있으므로 요청의 도구 정의 집합이 턴 사이에 변경되면 캐시가 무효화됩니다. [어드바이저 도구](/docs/ko/advisor)를 토글하는 것은 예외입니다. 그 정의는 캐시 중단점 이후에 있으므로 `/advisor`를 활성화하거나 비활성화해도 캐시된 접두사가 그대로 유지됩니다. [MCP 서버](/docs/ko/mcp) 변경이 이를 수행하는지 여부는 [도구 검색](/docs/ko/mcp#scale-with-mcp-tool-search)이 세션의 MCP 도구를 지연하는지에 따라 달라집니다. 지원되는 모델의 기본값입니다.

126 126

127* **도구 지연됨**: Claude Code는 대화의 첫 번째 요청에서 도구 목록을 유지하므로 세션 중간에 서버가 연결되거나 연결 해제되어도 이미 캐시된 것을 방해하지 않습니다. 첫 번째 요청 후 연결을 마치는 서버는 Claude가 필요에 따라 로드하는 지연된 정의로 해당 도구를 제공합니다.127* **도구 지연됨**: Claude Code는 대화의 첫 번째 요청에서 도구 목록을 유지하므로 세션 중간에 서버가 연결되거나 연결 해제되어도 이미 캐시된 것을 방해하지 않습니다. 첫 번째 요청 후 연결을 마치는 서버는 Claude가 필요에 따라 로드하는 지연된 정의로 해당 도구를 제공합니다.

128* **도구 접두사에 로드됨**: 정의 추가는 캐시를 무효화하며, 의도적으로 제거하는 것도 마찬가지입니다. 이는 [도구 검색을 사용할 수 없거나 비활성화](/docs/ko/mcp#configure-tool-search)된 경우입니다. 예를 들어 Claude 4.5 세대보다 이전의 Google Cloud의 Agent Platform 모델, 사용자 정의 `ANTHROPIC_BASE_URL` 게이트웨이, 또는 Claude Code가 배포가 도구 검색을 거부한다는 것을 감지한 Microsoft Foundry [Azure에서 호스팅되는 배포](https://platform.claude.com/docs/en/build-with-claude/claude-in-microsoft-foundry#hosting-options)에서입니다.128* **도구 사전 로드됨**: 정의를 추가하면 캐시가 무효화되며, 의도적으로 제거하는 것도 마찬가지입니다. 이는 도구 검색이 [`auto` 임계값 미만이거나, 비활성화되었거나, 사용할 수 없는](/docs/ko/mcp#configure-tool-search) 경우에 적용됩니다. 예를 들어 Claude 4.5 세대보다 이전의 Google Cloud의 Agent Platform 모델, 사용자 정의 `ANTHROPIC_BASE_URL` 게이트웨이, 또는 Claude Code가 배포에서 도구 검색을 거부한다는 것을 감지한 이후의 Microsoft Foundry [Azure에서 호스팅되는 배포](https://platform.claude.com/docs/en/build-with-claude/claude-in-microsoft-foundry#hosting-options)가 이에 해당합니다.

129 129

130도구 검색 없이 세션 중간 서버 변경이 캐시를 무효화하는지 여부는 변경된 내용에 따라 달라집니다. 각 변경에 대해 이 표는 캐시가 유지되는지 여부와 다음 요청에서 도구 정의에 어떤 일이 발생하는지를 나타냅니다.130도구 검색 없이 세션 중간 서버 변경이 캐시를 무효화하는지 여부는 변경된 내용에 따라 달라집니다. 각 변경에 대해 이 표는 캐시가 유지되는지 여부와 다음 요청에서 도구 정의에 어떤 일이 발생하는지를 나타냅니다.

131 131

172 172

173* `command` 소스가 있는 플러그인의 경우 Claude Code는 [플러그인 자체를 다시 로드](/docs/ko/plugins/loading#when-a-command-source-re-runs)할 수 있습니다.173* `command` 소스가 있는 플러그인의 경우 Claude Code는 [플러그인 자체를 다시 로드](/docs/ko/plugins/loading#when-a-command-source-re-runs)할 수 있습니다.

174* [`/plugin` 인터페이스에서 플러그인을 설치](/docs/ko/plugins/install#install-a-plugin)할 때 Claude Code는 설치 중에 활성화할 수 있습니다. 설치 요약은 활성화했는지 여부를 알려줍니다.174* [`/plugin` 인터페이스에서 플러그인을 설치](/docs/ko/plugins/install#install-a-plugin)할 때 Claude Code는 설치 중에 활성화할 수 있습니다. 설치 요약은 활성화했는지 여부를 알려줍니다.

175* v2.1.246 이상에서 [`/cd`로 세션을 이동](/docs/ko/permissions#move-the-session-to-another-directory)할 때 Claude Code는 새 디렉토리의 설정이 활성화하는 플러그인을 이동의 일부로 적용하며, `/reload-plugins`를 보유하는 전체 다시 읽기 경고 없이 적용합니다.175* v2.1.246 이상에서 [`/cd`로 세션을 이동](/docs/ko/permissions#move-the-session-to-another-directory)할 때 Claude Code는 새 디렉토리의 설정이 활성화하는 플러그인을 이동의 일부로 적용하며, `/reload-plugins`를 보류시키는 전체 다시 읽기 경고 없이 적용합니다.

176* 대화형 세션에서 `--plugin-dir`으로 전달한 [플러그인 폴더](/docs/ko/plugins/create#load-a-directory-or-archive-for-one-session)에서 플러그인을 추가하거나 제거할 때 변경이 즉시 적용됩니다. 적용하면 전체 다시 읽기가 트리거되면 Claude Code는 변경을 대신 보유하고 `/reload-plugins`를 실행하라는 공지를 표시합니다. Claude Code v2.1.265 이상이 필요합니다.176* 대화형 세션에서 `--plugin-dir`으로 전달한 [플러그인 폴더](/docs/ko/plugins/create#load-a-directory-or-archive-for-one-session)에서 플러그인을 추가하거나 제거할 때 변경이 즉시 적용됩니다. 적용하면 전체 다시 읽기가 트리거되는 경우 Claude Code는 대신 변경을 보류하고 `/reload-plugins`를 실행하라는 공지를 표시합니다. Claude Code v2.1.265 이상이 필요합니다.

177 177

178`/reload-plugins`가 실행되고 다시 로드가 전체 다시 읽기를 트리거하면 Claude Code는 경고를 표시하고 다시 로드를 적용하지 않습니다. `/reload-plugins --force`를 실행하여 어쨌든 적용합니다.178`/reload-plugins`가 실행되고 다시 로드가 전체 다시 읽기를 트리거하면 Claude Code는 경고를 표시하고 다시 로드를 적용하지 않습니다. 그래도 적용하려면 `/reload-plugins --force`를 실행합니다.

179 179

180`/reload-plugins`는 또한 데스크톱 앱, Agent SDK, [비대화형 모드](/docs/ko/headless)와 `-p`를 포함한 대화형 터미널이 없는 세션에서 실행되며, 세션에 직접 입력할 때 실행됩니다. Claude Code v2.1.260 이상이 필요합니다.180`/reload-plugins`는 데스크톱 앱, Agent SDK, `-p`를 사용하는 [비대화형 모드](/docs/ko/headless)처럼 대화형 터미널이 없는 세션에서도 세션에 직접 입력하면 실행됩니다. Claude Code v2.1.260 이상이 필요합니다.

181 181

182이러한 세션에서 다시 로드는 플러그인 MCP 서버 변경을 제외한 모든 것을 적용하며, [다음 세션에서 적용](/docs/ko/plugins/cli-reference#reload-plugins)되므로 세션 중간에 전체 다시 읽기 비용이 발생하지 않습니다.182이러한 세션에서 다시 로드는 플러그인 MCP 서버 변경을 제외한 모든 것을 적용하며, 플러그인 MCP 서버 변경은 [다음 세션에서 적용](/docs/ko/plugins/cli-reference#reload-plugins)되므로 세션 중간에 전체 다시 읽기 비용이 발생하지 않습니다.

183 183

184<h4 id="plugins-you-enable-and-then-disable-in-one-session">184<h4 id="plugins-you-enable-and-then-disable-in-one-session">

185 한 세션에서 활성화한 후 비활성화하는 플러그인185 한 세션에서 활성화한 후 비활성화하는 플러그인

201 대화 압축201 대화 압축

202</h3>202</h3>

203 203

204[압축](/docs/ko/context-window#what-survives-compaction)은 메시지 기록을 요약으로 바꿉니다. 설계상 이는 대화 레이어를 무효화합니다. 다음 요청에는 이전 것과 접두사를 공유하지 않는 새로운 더 짧은 기록이 있기 때문입니다. Claude Code는 대화가 [시스템 프롬프트를 유지하면서 재개되지 않는 한](#resuming-a-session) 시스템 프롬프트 레이어를 재사용합니다. 그 경우 첫 번째 압축은 현재 프롬프트로 전환되고 해당 레이어는 한 번 다시 빌드됩니다. 디스크에서 프로젝트 컨텍스트를 다시 로드하며, 세션 시작 이후 CLAUDE.md 및 메모리가 변경되지 않은 경우에만 캐시 히트합니다.204[압축](/docs/ko/context-window#what-survives-compaction)은 메시지 기록을 요약으로 바꿉니다. 설계상 이는 대화 레이어를 무효화합니다. 다음 요청에는 이전 것과 접두사를 공유하지 않는 새로운 더 짧은 기록이 있기 때문입니다. Claude Code는 대화가 [그렇지 않았다면 변경되었을 시스템 프롬프트를 유지하면서 재개된 경우](#resuming-a-session)가 아니라면 시스템 프롬프트 레이어를 재사용합니다. 그 경우 첫 번째 압축은 현재 프롬프트로 전환되고 해당 레이어는 한 번 다시 빌드됩니다. 디스크에서 프로젝트 컨텍스트를 다시 로드하며, 세션 시작 이후 CLAUDE.md 및 메모리가 변경되지 않은 경우에만 캐시 히트합니다.

205 205

206요약을 생성하기 위해 Claude Code는 대화와 같은 시스템 프롬프트, 도구, 기록을 가진 별도의 요청을 보내고 최종 사용자 메시지로 요약 지침을 추가합니다. 캐시가 따뜻한 동안 해당 요청은 캐시에서 접두사를 읽으므로 세션 중간 `/compact`는 컨텍스트 크기가 제안하는 것의 일부 비용이 들고 대부분의 시간을 요약 생성에 소비합니다.206요약을 생성하기 위해 Claude Code는 대화와 같은 시스템 프롬프트, 도구, 기록을 가진 별도의 요청을 보내고 최종 사용자 메시지로 요약 지침을 추가합니다. 캐시가 따뜻한 동안 해당 요청은 캐시에서 접두사를 읽으므로 세션 중간 `/compact`는 컨텍스트 크기가 제안하는 것의 일부 비용이 들고 대부분의 시간을 요약 생성에 소비합니다.

207 207

208[캐시 수명](#cache-lifetime)보다 긴 휴식 후에는 읽을 캐시가 남아 있지 않으므로 요약 요청은 전체 기록을 캐시되지 않은 입력으로 다시 처리합니다. 이것이 [이전 세션을 재개](/docs/ko/sessions#resume-from-a-summary)할 때 `/compact`의 비용이 가장 많이 드는 이유입니다. 따뜻한 경우와 차가운 경우 모두에서 압축 후 턴은 훨씬 더 짧은 요약에 대해서만 대화 캐시를 다시 빌드하므로 해당 턴이 느린 부분이 아닙니다.208[캐시 수명](#cache-lifetime)보다 긴 휴식 후에는 읽을 캐시가 남아 있지 않으므로 요약 요청은 전체 기록을 캐시되지 않은 입력으로 다시 처리합니다. 이것이 [이전 세션을 재개](/docs/ko/sessions#resume-from-a-summary)할 때 `/compact`의 비용이 가장 많이 드는 이유입니다. 따뜻한 경우와 차가운 경우 모두에서 압축 후 턴은 훨씬 더 짧은 요약에 대해서만 대화 캐시를 다시 빌드하므로 해당 턴이 느린 부분이 아닙니다.

209 209

210<Tip>210<Tip>

211 압축은 더 이상 필요하지 않은 콘텐츠를 버릴 때 유리합니다. 오버헤드가 발생하는 시기를 선택하려면 작업 중간에 자동 압축이 트리거되기를 기다리는 대신 작업 간 자연스러운 휴식 시간에 `/compact`를 실행합니다. 완전히 포기하고 싶은 경로를 따라가면 대신 [이전 턴으로 `rewinding`](#rewinding-the-conversation)합니다. 되감기는 압축이 수행하는 것처럼 새로운 것을 빌드하는 대신 이미 캐시된 접두사로 다시 자릅니다.211 압축은 더 이상 필요하지 않은 콘텐츠를 버릴 때 유리합니다. 오버헤드가 발생하는 시기를 선택하려면 작업 중간에 자동 압축이 트리거되기를 기다리는 대신 작업 간 자연스러운 휴식 시간에 `/compact`를 실행합니다. 완전히 포기하고 싶은 경로로 들어섰다면 대신 [`/rewind`](#rewinding-the-conversation)로 이전 턴으로 되돌아갑니다. 되감기는 압축처럼 새 접두사를 빌드하는 대신 이미 캐시된 접두사로 다시 잘라냅니다.

212</Tip>212</Tip>

213 213

214<h3 id="accumulating-many-images">214<h3 id="accumulating-many-images">

328| 메인 대화 | 1시간 | 5분 |328| 메인 대화 | 1시간 | 5분 |

329| 기타 모든 것 | 5분, 서버 제어 도우미 요청 제외(1시간 받음) | 5분 |329| 기타 모든 것 | 5분, 서버 제어 도우미 요청 제외(1시간 받음) | 5분 |

330 330

331플랜의 사용량 한도를 초과하고 Claude Code가 [사용 크레딧](https://support.claude.com/en/articles/12429409-extra-usage-for-paid-claude-plans)을 사용하기 시작하면 해당 사용량에 대해 청구되므로 Claude Code는 메인 대화를 더 저렴한 5분 TTL로 낮춥니다. 메인 대화에서 1시간 TTL을 유지하려면 [TTL을 직접 선택하세요](#choose-the-ttl-yourself).331플랜의 사용 한도를 초과하고 Claude Code가 [사용량 크레딧](https://support.claude.com/en/articles/12429409-extra-usage-for-paid-claude-plans)을 사용하기 시작하면 해당 사용량에 대해 청구되므로 Claude Code는 메인 대화를 캐시 쓰기 요금이 더 낮은 5분 TTL로 낮춥니다. 메인 대화에서 1시간 TTL을 유지하려면 [TTL을 직접 선택하세요](#choose-the-ttl-yourself).

332 332

333<h3 id="choose-the-ttl-yourself">333<h3 id="choose-the-ttl-yourself">

334 TTL을 직접 선택하세요334 TTL을 직접 선택하세요

prompt-library.md +1 −1

Details

1342 },1342 },

1343 "review-your-changes-before": {1343 "review-your-changes-before": {

1344 title: "커밋하기 전에 변경 사항 검토",1344 title: "커밋하기 전에 변경 사항 검토",

1345 teaches: "여전히 수정하기 저렴할 때 문제를 포착하십시오. Claude가 diff 줄만이 아닌 변경된 파일 전체를 읽으므로 빠른 자체 검토가 놓칠 문제를 발견합니다.",1345 teaches: "수정하는 데 드는 작업이 적을 때 문제를 포착하십시오. Claude가 diff 줄만이 아닌 변경된 파일 전체를 읽으므로 빠른 자체 검토가 놓칠 문제를 발견합니다.",

1346 next: "한 명령으로 동일한 확인을 위해 `/code-review`를 실행하십시오",1346 next: "한 명령으로 동일한 확인을 위해 `/code-review`를 실행하십시오",

1347 prompt: "커밋하기 전에 커밋되지 않은 변경 사항을 리뷰하고 위험해 보이는 부분을 알려 주세요"1347 prompt: "커밋하기 전에 커밋되지 않은 변경 사항을 리뷰하고 위험해 보이는 부분을 알려 주세요"

1348 },1348 },

quickstart.md +69 −103

Details

4 4

5# 빠른 시작5# 빠른 시작

6 6

~~7> Claude Code에 오신 것을 환영합니다!~~7> 터미널에 Claude Code를 설치하고 로그인한 후, CLI를 사용하여 코드베이스를 탐색하고 첫 번째 코드 변경을 수행합니다.

8 8

9이 빠른 시작 가이드를 통해 몇 분 안에 AI 기반 코딩 지원을 사용할 수 있습니다. 이 가이드를 마치면 일반적인 개발 작업에 Claude Code를 사용하는 방법을 이해하게 됩니다.9이 빠른 시작 가이드에서는 터미널에서 Claude Code를 사용하는 방법을 다룹니다. CLI 설치, 첫 세션에서의 로그인, 그리고 자체 프로젝트에서 일반적인 개발 작업에 활용하는 방법을 설명합니다.

10 10

11<h2 id="before-you-begin">11<h2 id="before-you-begin">

12 시작하기 전에12 시작하기 전에

15다음을 확인하십시오:15다음을 확인하십시오:

16 16

17* 열려 있는 터미널 또는 명령 프롬프트17* 열려 있는 터미널 또는 명령 프롬프트

~~18 * 터미널을 처음 사용하는 경우 [터미널 가이드](/docs/ko/terminal-guide)를 확인하십시오~~

19* 작업할 코드 프로젝트18* 작업할 코드 프로젝트

20* [Claude 구독](https://claude.com/pricing?utm_source=claude_code\&utm_medium=docs\&utm_content=quickstart_prereq) (Pro, Max, Team 또는 Enterprise), [Claude Console](https://platform.claude.com/) 계정 또는 [지원되는 클라우드 제공자](/docs/ko/third-party-integrations)를 통한 액세스19* [Claude 구독](https://claude.com/pricing?utm_source=claude_code\&utm_medium=docs\&utm_content=quickstart_prereq) (Pro, Max, Team 또는 Enterprise), [Claude Console](https://platform.claude.com/) 계정 또는 [지원되는 클라우드 제공자](/docs/ko/third-party-integrations)를 통한 액세스

21 20

22<Note>21<Note>

23 이 가이드는 터미널 CLI를 다룹니다. Claude Code는 [웹](https://claude.ai/code), [데스크톱 앱](/docs/ko/desktop), [VS Code](/docs/ko/vs-code) 및 [JetBrains IDE](/docs/ko/jetbrains), [Slack](/docs/ko/slack), [GitHub Actions](/docs/ko/github-actions) 및 [GitLab](/docs/ko/gitlab-ci-cd)의 CI/CD에서도 사용할 수 있습니다. [모든 인터페이스](/docs/ko/overview#use-claude-code-everywhere)를 참조하십시오.22 다음 경우는 다른 페이지에서 다룹니다:

24 * **터미널을 처음 사용하는 경우**: [터미널 가이드](/docs/ko/terminal-guide)부터 시작하십시오

25 * **터미널이 아닌 다른 곳에서 Claude Code를 사용하려는 경우**: Claude Code는 [웹](https://claude.ai/code), [데스크톱 앱](/docs/ko/desktop), [VS Code](/docs/ko/vs-code) 및 [JetBrains IDE](/docs/ko/jetbrains), [Slack](/docs/ko/slack), [GitHub Actions](/docs/ko/github-actions) 및 [GitLab](/docs/ko/gitlab-ci-cd)의 CI/CD에서도 사용할 수 있습니다. [모든 인터페이스](/docs/ko/overview#use-claude-code-everywhere)를 참조하십시오.

24</Note>26</Note>

25 27

26<h2 id="step-1-install-claude-code">28<h2 id="step-1-install-claude-code">

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

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

35 37

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

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

38 ```40 ```

39 41

42 Windows에서 PowerShell에 있을 때는 프롬프트에 `PS C:\`가 표시되고, CMD에 있을 때는 `PS` 없이 `C:\`만 표시됩니다.

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

41 45

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

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

44 ```48 ```

45 49

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

47 51

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

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

50 ```54 ```

51 55

52 설치 프로그램이 완료되면 새 터미널 창을 열고 `claude --version`을 실행하십시오. 설치가 제대로 되었으면 버전 번호가 출력됩니다. 셸에서 `claude`를 찾을 수 없거나 인식되지 않는다고 표시되면 설치 디렉토리가 아직 PATH에 없는 것입니다. [PATH 수정](/docs/ko/troubleshoot-install#command-not-found-claude-after-installation)을 참조하십시오.56 설치 프로그램이 완료되면 새 터미널 창을 열고 `claude --version`을 실행하십시오. 설치가 제대로 되었으면 버전 번호가 출력됩니다. 셸에서 `claude`를 찾을 수 없거나 인식되지 않는다고 표시되면 설치 디렉토리가 아직 PATH에 없는 것입니다. [PATH 수정](/docs/ko/troubleshoot-install#command-not-found-claude-after-installation)을 참조하십시오.

53 57

54 `The token '&&' is not a valid statement separator` 오류가 표시되면 CMD가 아닌 PowerShell에 있는 것입니다. `'irm' is not recognized as an internal or external command` 오류가 표시되면 PowerShell이 아닌 CMD에 있는 것입니다. PowerShell에 있을 때는 프롬프트에 `PS C:\`가 표시되고, CMD에 있을 때는 `PS` 없이 `C:\`만 표시됩니다.58 `The token '&&' is not a valid statement separator` 오류가 표시되면 CMD가 아닌 PowerShell에 있는 것입니다. `'irm' is not recognized as an internal or external command` 오류가 표시되면 PowerShell이 아닌 CMD에 있는 것입니다.

55 59

56 설치 명령이 `syntax error near unexpected token '<'`, `403` 또는 다른 curl 오류로 실패하면 [설치 문제 해결](/docs/ko/troubleshoot-install#find-your-error)을 참조하여 오류를 수정 방법과 일치시키고 대체 설치 방법을 확인하십시오.60 설치 명령이 `syntax error near unexpected token '<'`, `403` 또는 다른 오류로 실패하면 [설치 문제 해결](/docs/ko/troubleshoot-install#find-your-error)을 참조하여 오류를 수정 방법과 일치시키고 대체 설치 방법을 확인하십시오.

57 61

58 [Git for Windows](https://git-scm.com/downloads/win)는 Claude Code가 Bash 도구를 사용할 수 있도록 기본 Windows에서 권장됩니다. Git for Windows가 설치되지 않은 경우 Claude Code는 대신 PowerShell을 셸 도구로 사용합니다. WSL 설정에는 Git for Windows가 필요하지 않습니다.62 [Git for Windows](https://git-scm.com/downloads/win)는 Claude Code가 Bash 도구를 사용할 수 있도록 기본 Windows에서 권장됩니다. Git for Windows가 설치되지 않은 경우 Claude Code는 대신 PowerShell을 셸 도구로 사용합니다. WSL 설정에는 Git for Windows가 필요하지 않습니다.

59 63

63 </Tab>67 </Tab>

64 68

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

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

67 brew install --cask claude-code71 brew install --cask claude-code

68 ```72 ```

69 73

75 </Tab>79 </Tab>

76 80

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

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

79 winget install Anthropic.ClaudeCode83 winget install Anthropic.ClaudeCode

80 ```84 ```

81 85

95 99

96이 명령어는 버전 번호 다음에 `(Claude Code)`를 출력합니다.100이 명령어는 버전 번호 다음에 `(Claude Code)`를 출력합니다.

97 101

~~98<h2 id="step-2-log-in-to-your-account">~~102<h2 id="step-2-start-your-first-session">

~~99 단계 2: 계정에 로그인~~103 2단계: 첫 번째 세션 시작하기

100</h2>104</h2>

101 105

102Claude Code를 사용하려면 계정이 필요합니다. `claude` 명령으로 대화형 세션을 시작하면 처음 사용할 때 로그인하라는 메시지가 표시됩니다:106아무 프로젝트 디렉터리에서 터미널을 열고 Claude Code를 시작합니다:

103 107

104```bash theme={null}108```bash theme={null}

109cd /path/to/your/project

105claude110claude

106```111```

107 112

108Claude 구독 또는 Console 계정의 경우 프롬프트를 따라 브라우저에서 인증을 완료하십시오. `ANTHROPIC_API_KEY` 환경 변수를 설정한 경우 Claude Code는 로그인 프롬프트를 건너뛰고 대신 키를 승인하도록 요청합니다. 나중에 계정을 전환하거나 다시 인증하려면 실행 중인 세션 내에서 `/login`을 입력하십시오:113`/path/to/your/project`를 작업하려는 프로젝트의 경로로 바꿉니다.

~~109~~

110```text wrap theme={null}

111/login

112```

113 114

114다음 계정 유형 중 하나를 사용하여 로그인할 수 있습니다:115Claude Code는 처음 사용할 때 로그인을 요청합니다. Claude 구독 또는 Console 계정의 경우 안내에 따라 브라우저에서 인증을 완료합니다. `ANTHROPIC_API_KEY` 환경 변수를 설정했고 Claude Code가 해당 키를 사용할지 물을 때 승인하면 Claude Code는 로그인 프롬프트를 건너뜁니다.

115 116

116* [Claude Pro, Max, Team 또는 Enterprise](https://claude.com/pricing?utm_source=claude_code\&utm_medium=docs\&utm_content=quickstart_login) (권장)117다음 계정 유형 중 하나로 로그인할 수 있습니다:

117* [Claude Console](https://platform.claude.com/) (선불 크레딧이 있는 API 액세스). 처음 로그인할 때 비용 추적을 위해 Console에서 "Claude Code" 워크스페이스가 자동으로 생성됩니다.

118* [Amazon Bedrock, Google Cloud의 Agent Platform 또는 Microsoft Foundry](/docs/ko/third-party-integrations) (엔터프라이즈 클라우드 제공자)

119* 조직에서 운영하는 자체 호스팅 [Claude 앱 게이트웨이](/docs/ko/claude-apps-gateway): 관리자가 게이트웨이 URL을 미리 구성하고, `/login`을 입력하면 **Cloud gateway** 화면에서 직접 열려 기업 SSO로 로그인할 수 있습니다.

120 118

121로그인하면 자격 증명이 저장되고 다시 로그인할 필요가 없습니다. [자격 증명 관리](/docs/ko/authentication#credential-management)에서 자세히 알아보십시오.119* [Claude Pro, Max, Team 또는 Enterprise](https://claude.com/pricing?utm_source=claude_code\&utm_medium=docs\&utm_content=quickstart_login)(권장)

~~122~~ 120* [Claude Console](https://platform.claude.com/)(선불 크레딧을 사용하는 API 액세스). 처음 로그인하면 중앙 집중식 비용 추적을 위해 Console에 "Claude Code" 워크스페이스가 자동으로 생성됩니다.

123<h2 id="step-3-start-your-first-session">121* [Amazon Bedrock, Google Cloud의 Agent Platform 또는 Microsoft Foundry](/docs/ko/third-party-integrations)(엔터프라이즈 클라우드 제공업체)

124 단계 3: 첫 번째 세션 시작122* 조직에서 운영하는 경우 자체 호스팅 [Claude apps gateway](/docs/ko/claude-apps-gateway): 관리자가 게이트웨이 URL을 미리 구성하며, `/login`을 실행하면 바로 **Cloud gateway** 화면이 열려 회사 SSO로 로그인할 수 있습니다

125</h2>

~~126~~

127프로젝트 디렉토리에서 터미널을 열고 Claude Code를 시작하십시오:

~~128~~

129```bash theme={null}

130cd /path/to/your/project

131claude

132```

133 123

134`/path/to/your/project`를 작업하려는 프로젝트의 경로로 바꾸십시오.124로그인하면 자격 증명이 저장되므로 다시 로그인할 필요가 없습니다. 자세한 내용은 [자격 증명 관리](/docs/ko/authentication#credential-management)를 참조하세요.

135 125

136버전, 현재 모델 및 작업 디렉토리가 표시된 Claude Code 프롬프트가 나타납니다. 사용 가능한 명령을 보려면 `/help`를 입력하거나 이전 대화를 계속하려면 `/resume`을 입력하십시오.126Claude Code 프롬프트가 나타나며, 그 위에 버전, 현재 모델, 작업 디렉터리가 표시됩니다. 사용 가능한 명령을 보려면 `/help`를, 이전 대화를 이어가려면 `/resume`을 입력합니다. 나중에 계정을 전환하거나 다시 인증하려면 실행 중인 세션 안에서 `/login`을 입력합니다.

137 127

138<h2 id="step-4-ask-your-first-question">128<h2 id="step-3-ask-your-first-question">

139 단계 4: 첫 번째 질문 하기129 3단계: 첫 번째 질문하기

140</h2>130</h2>

141 131

142코드베이스를 이해하는 것부터 시작하겠습니다. 다음 명령 중 하나를 시도하십시오:132다음 명령 중 하나를 시도해 보세요:

143 133

144```text wrap theme={null}134```text wrap theme={null}

145what does this project do?135what does this project do?

159explain the folder structure149explain the folder structure

160```150```

161 151

162Claude의 기능에 대해 물어볼 수도 있습니다:152Claude에게 Claude 자체의 기능에 대해 물어볼 수도 있습니다:

163 153

164```text wrap theme={null}154```text wrap theme={null}

165what can Claude Code do?155what can Claude Code do?

174```164```

175 165

176<Note>166<Note>

177 Claude Code는 필요에 따라 프로젝트 파일을 읽습니다. 수동으로 컨텍스트를 추가할 필요가 없습니다.167 Claude Code는 필요에 따라 프로젝트 파일을 읽습니다. 컨텍스트를 수동으로 추가할 필요가 없습니다.

178</Note>168</Note>

179 169

180<h2 id="step-5-make-your-first-code-change">170<h2 id="step-4-make-your-first-code-change">

181 단계 5: 첫 번째 코드 변경 수행171 4단계: 첫 번째 코드 변경하기

182</h2>172</h2>

183 173

184이제 Claude Code가 실제 코딩을 하도록 해봅시다. 간단한 작업을 시도하십시오:174간단한 작업을 시도해 보세요:

185 175

186```text wrap theme={null}176```text wrap theme={null}

187주 파일에 hello world 함수 추가177add a hello world function to the main file

188```178```

189 179

190Claude Code는 적절한 파일을 찾고 변경 사항을 보여줍니다. 변경하기 전에 묻는 경우 **예**를 선택하여 승인하십시오.180Claude Code가 적절한 파일을 찾아 변경 사항을 보여 줍니다. 변경하기 전에 확인을 요청하면 **Yes**를 선택하여 승인합니다.

191 181

192Claude Code v2.1.283 이상에서는 자동 모드가 대화형 터미널 세션에 대한 [기본 제공 시작 권한 모드](/docs/ko/permission-modes#eliminate-prompts-with-auto-mode)입니다. 분류기가 사용자 대신 작업을 검토하며, Claude는 대부분의 파일을 편집하고 대부분의 명령을 묻지 않고 실행합니다. 이전 버전에서는 자동 모드가 Pro, Max 및 Team 플랜에서만 기본 제공 시작 권한 모드입니다. 설치 또는 업그레이드 직후에 시작하는 세션의 경우 [설치 또는 업그레이드 후 첫 번째 세션](/docs/ko/env-vars#first-session-after-an-install-or-upgrade)을 참조하십시오.182세션의 [권한 모드](/docs/ko/permission-modes)는 Claude가 먼저 묻지 않고 수행할 수 있는 작업을 결정합니다. 언제든지 `Shift+Tab`을 눌러 현재 세션의 권한 모드를 전환할 수 있습니다.

~~193~~

194<Note>

195 사용자의 설정 또는 조직에서 다른 시작 권한 모드를 설정할 수 있습니다. [세션이 시작되는 권한 모드](/docs/ko/permission-modes#which-mode-a-session-starts-in)에서 어떤 모드인지 확인할 수 있습니다. 언제든지 `Shift+Tab`을 눌러 현재 세션의 권한 모드를 전환할 수 있습니다.

196</Note>

197 183

198<h2 id="step-6-use-git-with-claude-code">184<h2 id="step-5-use-git-with-claude-code">

199 단계 6: Claude Code와 함께 Git 사용185 5단계: Claude Code로 Git 사용하기

200</h2>186</h2>

201 187

202Claude Code는 Git 작업을 대화형으로 만듭니다:188Claude Code를 사용하면 대화하듯이 Git 작업을 수행할 수 있습니다:

203 189

204```text wrap theme={null}190```text wrap theme={null}

205어떤 파일을 변경했나요?191what files have I changed?

206```192```

207 193

208```text wrap theme={null}194```text wrap theme={null}

209설명적인 메시지로 변경 사항 커밋195commit my changes with a descriptive message

210```196```

211 197

212더 복잡한 Git 작업을 요청할 수도 있습니다:198더 복잡한 Git 작업을 요청할 수도 있습니다:

213 199

214```text wrap theme={null}200```text wrap theme={null}

215feature/quickstart라는 새 브랜치 생성201create a new branch called feature/quickstart

216```202```

217 203

218```text wrap theme={null}204```text wrap theme={null}

219마지막 5개의 커밋 표시205show me the last 5 commits

220```206```

221 207

222```text wrap theme={null}208```text wrap theme={null}

223병합 충돌을 해결하는 데 도움을 주세요209help me resolve merge conflicts

224```210```

225 211

226<h2 id="step-7-fix-a-bug-or-add-a-feature">212<h2 id="step-6-fix-a-bug-or-add-a-feature">

227 단계 7: 버그 수정 또는 기능 추가213 6단계: 버그 수정 또는 기능 추가

228</h2>214</h2>

229 215

230Claude는 디버깅 및 기능 구현에 능숙합니다.216원하는 작업을 자연어로 설명합니다:

~~231~~

232자연어로 원하는 것을 설명하십시오:

233 217

234```text wrap theme={null}218```text wrap theme={null}

235사용자 등록 양식에 입력 유효성 검사 추가219add input validation to the user registration form

236```220```

237 221

238또는 기존 문제를 수정하십시오:222또는 기존 문제를 수정합니다:

239 223

240```text wrap theme={null}224```text wrap theme={null}

241사용자가 빈 양식을 제출할 수 있는 버그가 있습니다 - 수정하세요225there's a bug where users can submit empty forms - fix it

242```226```

243 227

244Claude Code는 다음을 수행합니다:228<h2 id="step-7-test-out-other-common-workflows">

~~245~~ 229 7단계: 다른 일반적인 워크플로 테스트하기

246* 관련 코드 찾기

247* 컨텍스트 이해

248* 솔루션 구현

249* 사용 가능한 경우 테스트 실행

~~250~~

251<h2 id="step-8-test-out-other-common-workflows">

252 단계 8: 다른 일반적인 워크플로우 시도

253</h2>230</h2>

254 231

255Claude와 함께 작업하는 여러 가지 방법이 있습니다:232Claude와 함께 작업하는 방법은 다양합니다.

256 233

257**코드 리팩토링**234**코드 리팩터링**

258 235

259```text wrap theme={null}236```text wrap theme={null}

260인증 모듈을 콜백 대신 async/await를 사용하도록 리팩토링237refactor the authentication module to use async/await instead of callbacks

261```238```

262 239

263**테스트 작성**240**테스트 작성**

264 241

265```text wrap theme={null}242```text wrap theme={null}

266계산기 함수에 대한 단위 테스트 작성243write unit tests for the calculator functions

267```244```

268 245

269**문서 업데이트**246**문서 업데이트**

270 247

271```text wrap theme={null}248```text wrap theme={null}

272설치 지침으로 README 업데이트249update the README with installation instructions

273```250```

274 251

275**코드 검토**252**코드 리뷰**

276 253

277```text wrap theme={null}254```text wrap theme={null}

278내 변경 사항을 검토하고 개선 사항을 제안해주세요255review my changes and suggest improvements

279```256```

280 257

281<Tip>258<Tip>

282 도움이 되는 동료처럼 Claude와 대화하십시오. 달성하고 싶은 것을 설명하면 도움을 드릴 것입니다.259 유능한 동료에게 말하듯이 Claude에게 말해 보세요. 달성하고 싶은 목표를 설명하면 Claude가 그 목표에 도달할 수 있도록 도와줍니다.

283</Tip>260</Tip>

284 261

285<h2 id="essential-commands">262<h2 id="essential-commands">

357 334

358이제 기본 사항을 배웠으므로 더 고급 기능을 살펴보십시오:335이제 기본 사항을 배웠으므로 더 고급 기능을 살펴보십시오:

359 336

360<CardGroup cols={2}>337* [Claude Code 작동 방식](/docs/ko/how-claude-code-works): 에이전틱 루프, 기본 제공 도구 및 Claude Code가 프로젝트와 상호 작용하는 방식 이해

361 <Card title="Claude Code 작동 방식" icon="microchip" href="/docs/ko/how-claude-code-works">338* [모범 사례](/docs/ko/best-practices): 효과적인 프롬프팅 및 프로젝트 설정으로 더 나은 결과 얻기

362 에이전트 루프, 기본 제공 도구 및 Claude Code가 프로젝트와 상호 작용하는 방식 이해339* [일반적인 워크플로](/docs/ko/common-workflows): 일반적인 작업에 대한 단계별 가이드

363 </Card>340* [Claude Code 확장](/docs/ko/features-overview): CLAUDE.md, 스킬, 훅, MCP 등으로 사용자 정의

~~364~~

365 <Card title="모범 사례" icon="star" href="/docs/ko/best-practices">

366 효과적인 프롬프팅 및 프로젝트 설정으로 더 나은 결과 얻기

367 </Card>

~~368~~

369 <Card title="일반적인 워크플로우" icon="graduation-cap" href="/docs/ko/common-workflows">

370 일반적인 작업에 대한 단계별 가이드

371 </Card>

372 341

373 <Card title="Claude Code 확장" icon="puzzle-piece" href="/docs/ko/features-overview">342설치 옵션, 수동 업데이트 또는 제거 방법은 [고급 설정](/docs/ko/setup)을 참조하십시오.

374 CLAUDE.md, skills, hooks, MCP 등으로 사용자 정의

375 </Card>

376</CardGroup>

377 343

378<h2 id="getting-help">344<h2 id="getting-help">

379 도움 받기345 도움 받기

380</h2>346</h2>

381 347

382* **Claude Code에서**: `/help`를 입력하거나 "어떻게..."를 물어보기348* **Claude Code에서**: `/help`를 입력하거나 "어떻게..."를 물어보기

383* **문서**: 여기 있습니다! 다른 가이드 찾아보기349* **문서**: 이 사이트의 다른 가이드 찾아보기

384* **강좌**: [Claude Code 101](https://academy.claude.com/courses/claude-code-101)을 수강하고 [Claude Academy](https://academy.claude.com/)에서 다른 무료 자습형 강좌를 수강하기350* **강좌**: [Claude Code 101](https://academy.claude.com/courses/claude-code-101)을 수강하고 [Claude Academy](https://academy.claude.com/)에서 다른 무료 자습형 강좌를 수강하기

385* **커뮤니티**: 팁과 지원을 위해 [Discord 서버](https://www.anthropic.com/discord)에 참여하기351* **커뮤니티**: 팁과 지원을 위해 [Discord 서버](https://www.anthropic.com/discord)에 참여하기

remote-control.md +1 −1

Details

365</h2>365</h2>

366 366

367* **대화형 프로세스당 하나의 원격 세션**: 서버 모드 외에는 각 Claude Code 인스턴스가 한 번에 하나의 원격 세션을 지원합니다. [서버 모드](#start-a-remote-control-session)를 사용하여 단일 프로세스에서 여러 개의 동시 세션을 실행하십시오.367* **대화형 프로세스당 하나의 원격 세션**: 서버 모드 외에는 각 Claude Code 인스턴스가 한 번에 하나의 원격 세션을 지원합니다. [서버 모드](#start-a-remote-control-session)를 사용하여 단일 프로세스에서 여러 개의 동시 세션을 실행하십시오.

368* **로컬 프로세스는 계속 실행되어야 함**: Remote Control은 로컬 프로세스로 실행됩니다. 터미널을 닫거나, Desktop 앱 또는 VS Code를 종료하거나, 그 외 다른 방식으로 `claude` 프로세스를 중지하면 [다시 시작](#resume-sessions-after-stopping-the-server)할 때까지 세션이 오프라인 상태가 됩니다. SSH에서 연결을 해제한 후 원격 머신에서 세션을 계속 실행하려면 `tmux` 또는 `screen` 내에서 시작하십시오.368* **로컬 프로세스가 계속 실행되어야 함**: Remote Control은 로컬 프로세스로 실행됩니다. 터미널을 닫거나, Desktop 앱 또는 VS Code를 종료하거나, 그 밖의 방법으로 `claude` 프로세스를 중지하면 [다시 시작](#resume-sessions-after-stopping-the-server)할 때까지 세션이 오프라인 상태가 됩니다. 원격 머신의 터미널에서 `claude`를 실행하는 경우 SSH 연결을 끊은 후에도 세션이 계속 실행되도록 `tmux` 또는 `screen` 안에서 시작합니다.

369* **서버 모드에서 충돌한 세션**: `claude remote-control`로 제공되는 세션이 충돌하면 연결된 디바이스에서 메시지를 보내십시오. Claude Code가 다시 제공합니다. 서버를 다시 시작할 필요가 없습니다. Claude Code v2.1.238 이상이 필요합니다.369* **서버 모드에서 충돌한 세션**: `claude remote-control`로 제공되는 세션이 충돌하면 연결된 디바이스에서 메시지를 보내십시오. Claude Code가 다시 제공합니다. 서버를 다시 시작할 필요가 없습니다. Claude Code v2.1.238 이상이 필요합니다.

370* **연결된 세션에서 HTTP 403 거부**: 대화형 세션이 연결되면 Claude Code는 VPN 또는 네트워크 변경 후 발생할 수 있는 것처럼 머신과 Anthropic의 서버 사이의 무언가가 HTTP 403으로 응답할 때 최대 3분 동안 재시도를 계속합니다. 거부가 더 오래 지속되면 Claude Code는 연결을 해제하고 거부한 대상을 명시합니다: 네트워크 엣지 또는 자신의 네트워크의 프록시, VPN 또는 방화벽.370* **연결된 세션에서 HTTP 403 거부**: 대화형 세션이 연결되면 Claude Code는 VPN 또는 네트워크 변경 후 발생할 수 있는 것처럼 머신과 Anthropic의 서버 사이의 무언가가 HTTP 403으로 응답할 때 최대 3분 동안 재시도를 계속합니다. 거부가 더 오래 지속되면 Claude Code는 연결을 해제하고 거부한 대상을 명시합니다: 네트워크 엣지 또는 자신의 네트워크의 프록시, VPN 또는 방화벽.

371* **확장된 네트워크 중단**: 머신이 켜져 있지만 네트워크에 도달할 수 없는 경우 다음 작업은 모드에 따라 달라집니다:371* **확장된 네트워크 중단**: 머신이 켜져 있지만 네트워크에 도달할 수 없는 경우 다음 작업은 모드에 따라 달라집니다:

routines.md +1 −1

Details

93 루틴에 대해 [클라우드 환경](/docs/ko/cloud-environments)을 선택합니다. 환경은 클라우드 세션이 액세스할 수 있는 것을 제어합니다:93 루틴에 대해 [클라우드 환경](/docs/ko/cloud-environments)을 선택합니다. 환경은 클라우드 세션이 액세스할 수 있는 것을 제어합니다:

94 94

95 * **Network access**: 각 실행 중에 사용 가능한 인터넷 액세스 수준을 설정합니다95 * **Network access**: 각 실행 중에 사용 가능한 인터넷 액세스 수준을 설정합니다

96 * **Environment variables**: Claude가 각 실행 중에 사용할 수 있는 값을 제공합니다. 이들은 [환경을 사용하는 모든 사람에게 표시](/docs/ko/cloud-environments#what-carries-over-from-your-setup)되므로, Pro 및 Max 플랜에서는 Claude가 실행 중에 호출하는 API의 키를 [API credentials](/docs/ko/cloud-environments#add-api-credentials)로 저장합니다. 해당 섹션에는 자격 증명을 받지 않는 요청도 나열됩니다96 * **Environment variables**: Claude가 각 실행 중에 사용할 수 있는 값을 제공합니다. 이들은 [환경을 사용하는 모든 사람에게 표시](/docs/ko/cloud-environments#what-carries-over-from-your-setup)되므로, Pro 및 Max 플랜에서는 Claude가 실행 중에 호출하는 API의 키를 대신 [네트워크 시크릿](/docs/ko/cloud-environments#add-api-credentials)으로 저장합니다. 해당 섹션에는 시크릿을 받지 않는 요청도 나열됩니다

97 * **Setup script**: 루틴이 필요로 하는 종속성 및 도구를 설치합니다. 결과는 [캐시됩니다](/docs/ko/cloud-environments#environment-caching)이므로 스크립트는 모든 세션에서 다시 실행되지 않습니다97 * **Setup script**: 루틴이 필요로 하는 종속성 및 도구를 설치합니다. 결과는 [캐시됩니다](/docs/ko/cloud-environments#environment-caching)이므로 스크립트는 모든 세션에서 다시 실행되지 않습니다

98 98

99 **Default** 환경은 **Trusted** 네트워크 액세스와 함께 제공되며, 이는 세션의 네트워크를 통해 [기본 허용 목록](/docs/ko/cloud-environments#default-allowed-domains)의 패키지 레지스트리, 클라우드 제공자 API, 컨테이너 레지스트리 및 일반적인 개발 도메인만 허용합니다. 루틴에 추가하는 커넥터는 Anthropic의 서버를 통해 해당 서비스에 도달하므로 허용 목록 변경이 필요하지 않습니다. 루틴이 자신의 서비스에 직접 도달해야 하거나 해당 목록 외의 도메인에 도달해야 하는 경우, 실행하기 전에 환경의 [network access](/docs/ko/cloud-environments#network-access)를 편집합니다. 별도의 환경을 사용하려면 먼저 [하나를 만듭니다](/docs/ko/cloud-environments#configure-your-environment).99 **Default** 환경은 **Trusted** 네트워크 액세스와 함께 제공되며, 이는 세션의 네트워크를 통해 [기본 허용 목록](/docs/ko/cloud-environments#default-allowed-domains)의 패키지 레지스트리, 클라우드 제공자 API, 컨테이너 레지스트리 및 일반적인 개발 도메인만 허용합니다. 루틴에 추가하는 커넥터는 Anthropic의 서버를 통해 해당 서비스에 도달하므로 허용 목록 변경이 필요하지 않습니다. 루틴이 자신의 서비스에 직접 도달해야 하거나 해당 목록 외의 도메인에 도달해야 하는 경우, 실행하기 전에 환경의 [network access](/docs/ko/cloud-environments#network-access)를 편집합니다. 별도의 환경을 사용하려면 먼저 [하나를 만듭니다](/docs/ko/cloud-environments#configure-your-environment).

self-hosted-environments-testing.md +1 −1

Details

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

105</h2>105</h2>

106 106

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

108 108

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

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

server-managed-settings.md +2 −2

Details

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

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

45 45

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

47 </Step>47 </Step>

48 48

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

149 설정 우선순위149 설정 우선순위

150</h3>150</h3>

151 151

152서버 관리 설정과 [엔드포인트 관리 설정](/docs/ko/managed-settings#delivery-mechanisms)은 모두 Claude Code [설정 계층](/docs/ko/settings#settings-precedence)의 최상위 계층을 차지합니다. [관리 설정 우선순위의 예외](/docs/ko/settings#exceptions-to-managed-settings-precedence)를 제외하고는 명령줄 인수를 포함한 다른 설정 수준이 이들을 재정의할 수 없습니다.152서버 관리형 설정과 [엔드포인트 관리형 설정](/docs/ko/managed-settings#delivery-mechanisms)은 모두 Claude Code [설정 계층](/docs/ko/settings#settings-precedence)의 최상위 계층을 차지합니다. 여기에서 설정한 키는 사용자 자체 설정 파일이나 `--settings` 값에 있는 같은 키보다 우선 적용됩니다. 단, [관리형 설정 우선순위의 예외](/docs/ko/settings#exceptions-to-managed-settings-precedence)는 제외됩니다.

153 153

154관리 계층 내에서 Claude Code는 기본적으로 최소 하나의 정책 키를 전달하는 첫 번째 소스를 사용하며, 서버 관리 설정을 먼저 확인한 후 엔드포인트 관리 설정을 확인합니다. 단, [다음에서 다루는 예외 키](#per-key-exceptions-across-managed-sources)는 제외됩니다. [Claude Code가 관리 소스를 결합하는 방식](/docs/ko/managed-settings#precedence-within-the-managed-tier)에는 전체 순위, 제어 키에 대한 예외, 모든 소스에 적용되는 옵트인이 있습니다.154관리 계층 내에서 Claude Code는 기본적으로 최소 하나의 정책 키를 전달하는 첫 번째 소스를 사용하며, 서버 관리 설정을 먼저 확인한 후 엔드포인트 관리 설정을 확인합니다. 단, [다음에서 다루는 예외 키](#per-key-exceptions-across-managed-sources)는 제외됩니다. [Claude Code가 관리 소스를 결합하는 방식](/docs/ko/managed-settings#precedence-within-the-managed-tier)에는 전체 순위, 제어 키에 대한 예외, 모든 소스에 적용되는 옵트인이 있습니다.

155 155

sessions.md +24 −22

Details

14 세션 재개14 세션 재개

15</h2>15</h2>

16 16

17세션은 작업할 때 [로컬 대화 기록 파일](#export-and-locate-session-data)에 지속적으로 저장되므로 종료하거나 `/clear`를 실행한 후에 세션으로 돌아갈 수 있습니다. 다음 진입점을 사용합니다:17세션은 작업할 때 [로컬 트랜스크립트 파일](#export-and-locate-session-data)에 지속적으로 저장되므로 종료하거나 `/clear`를 실행한 후에 세션으로 돌아갈 수 있습니다. 다음 진입점을 사용합니다:

18 18

19| 명령 | 기능 |19| 명령 | 기능 |

20| :- | :- |20| :- | :- |

21| `claude --continue` | 현재 디렉토리에서 가장 최근 대화를 다시 엽니다 |21| `claude --continue` | 현재 디렉토리에서 가장 최근 대화를 다시 엽니다 |

22| `claude --resume` | [세션 선택기](#use-the-session-picker)를 엽니다 |22| `claude --resume` | [세션 선택기](#use-the-session-picker)를 엽니다 |

23| `claude --resume <name>` | 지정된 이름의 세션을 직접 재개합니다 |23| `claude --resume <name>` | 지정된 이름의 세션을 직접 재개합니다 |

26| `/resume` | 활성 세션 내에서 다른 대화로 전환합니다 |26| `/resume` | 활성 세션 내에서 다른 대화로 전환합니다 |

27 27

28Claude Code는 [`claude -p`](/docs/ko/headless) 또는 [Agent SDK](/docs/ko/agent-sdk/overview)로 생성된 세션을 세션 선택기 및 `claude --continue`에서 제외합니다. 세션 ID를 `claude --resume <session-id>`에 전달하여 여전히 재개할 수 있습니다. `claude --continue`를 사용하면 Claude Code는 [첫 번째 프롬프트가 `/loop`인 세션](#where-the-session-picker-looks)도 건너뜁니다. [`claude -p --continue`](/docs/ko/headless#continue-conversations)를 실행하면 Claude Code는 `-p`, SDK 및 `/loop` 세션을 포함합니다.28Claude Code는 [`claude -p`](/docs/ko/headless) 또는 [Agent SDK](/docs/ko/agent-sdk/overview)로 생성된 세션을 세션 선택기 및 `claude --continue`에서 제외합니다. 세션 ID를 `claude --resume <session-id>`에 전달하여 여전히 재개할 수 있습니다. `claude --continue`를 사용하면 Claude Code는 [첫 번째 프롬프트가 `/loop`인 세션](#where-the-session-picker-looks)도 건너뜁니다. [`claude -p --continue`](/docs/ko/headless#continue-conversations)를 실행하면 Claude Code는 `-p`, SDK 및 `/loop` 세션을 포함합니다.

44 44

45`claude --resume` 또는 `/resume`으로 재개하는 대화가 여전히 실행 중인 [백그라운드 세션](/docs/ko/agent-view)에 속하면 Claude Code는 실행 중인 세션 자체를 엽니다. 명령줄에서 `--bg`를 사용하면 재개는 대신 [백그라운드 디스패치](/docs/ko/agent-view#from-your-shell)로 수행됩니다. v2.1.285 이전에는 Claude Code가 거부하고 `claude attach <id>`로 세션을 열거나 먼저 `claude stop <id>`로 중지하도록 안내했습니다.45`claude --resume` 또는 `/resume`으로 재개하는 대화가 여전히 실행 중인 [백그라운드 세션](/docs/ko/agent-view)에 속하면 Claude Code는 실행 중인 세션 자체를 엽니다. 명령줄에서 `--bg`를 사용하면 재개는 대신 [백그라운드 디스패치](/docs/ko/agent-view#from-your-shell)로 수행됩니다. v2.1.285 이전에는 Claude Code가 거부하고 `claude attach <id>`로 세션을 열거나 먼저 `claude stop <id>`로 중지하도록 안내했습니다.

46 46

47* **셸에서**: `claude --resume <session>`은 대화 기록 자체를 로드하는 대신 같은 터미널에서 해당 세션에 대해 [`claude attach`](/docs/ko/agent-view#attach-to-a-session)를 실행합니다. `claude --resume <session> "check the tests too"`와 같이 명령줄에서 전달하는 프롬프트는 먼저 세션의 다음 턴으로 이동하고 Claude Code는 `Sent your prompt to the background session (<id>); opening it…`를 출력한 후 연결합니다. 터미널에서 입력한 `claude -p --resume <session> "prompt"`도 동일하게 작동하므로 `-p`는 해당 실행을 비대화형으로 유지하지 않습니다.47* **셸에서**: `claude --resume <session>`은 트랜스크립트 자체를 로드하는 대신 같은 터미널에서 해당 세션에 대해 [`claude attach`](/docs/ko/agent-view#attach-to-a-session)를 실행합니다. `claude --resume <session> "check the tests too"`와 같이 명령줄에서 전달하는 프롬프트는 먼저 세션의 다음 턴으로 이동하고 Claude Code는 `Sent your prompt to the background session (<id>); opening it…`를 출력한 후 연결합니다. 터미널에서 입력한 `claude -p --resume <session> "prompt"`도 동일하게 작동하므로 `-p`는 해당 실행을 비대화형으로 유지하지 않습니다.

48 48

49 Claude Code는 명령줄에 다음 중 하나가 있으면 세션을 열지 않습니다:49 Claude Code는 명령줄에 다음 중 하나가 있으면 세션을 열지 않습니다:

50 50

62 재개된 세션이 복원하는 것62 재개된 세션이 복원하는 것

63</h3>63</h3>

64 64

~~65Claude Code가 대화 기록에서 대화를 로드할 때 재개된 세션은 대화와 함께 저장된 상태를 복원합니다:~~65Claude Code가 트랜스크립트에서 대화를 로드할 때 재개된 세션은 대화와 함께 저장된 상태를 복원합니다:

66 66

67* 대화 기록: 도구 호출 및 결과를 포함한 전체 기록입니다. 이전 프로세스가 종료될 때(예: 충돌) 여전히 실행 중이던 도구는 재개할 때 완료되거나 다시 실행되지 않습니다. Claude는 호출이 결과가 기록되기 전에 중단된 것으로 표시되고 다시 실행하기 전에 효과가 있었는지 확인하도록 지시받으며, [`CLAUDE_CODE_RESUME_INTERRUPTED_TURN`](/docs/ko/env-vars#variables)이 설정되지 않은 경우입니다. v2.1.281 이전에는 Claude Code가 중단된 호출을 대화에서 삭제하거나 사용자가 중단한 것으로 Claude에게 표시했습니다.67* 대화 기록: 도구 호출 및 결과를 포함한 전체 기록입니다. 이전 프로세스가 종료될 때(예: 충돌) 여전히 실행 중이던 도구는 재개할 때 완료되거나 다시 실행되지 않습니다. [`CLAUDE_CODE_RESUME_INTERRUPTED_TURN`](/docs/ko/env-vars#variables)이 설정되지 않은 경우, Claude는 결과가 기록되기 전에 중단된 것으로 표시된 호출을 보게 되며 다시 실행하기 전에 효과가 있었는지 확인하도록 지시받습니다. v2.1.281 이전에는 Claude Code가 중단된 호출을 대화에서 삭제하거나 사용자가 중단한 것으로 Claude에게 표시했습니다.

68* 모델: 세션은 사용 중이던 모델에서 계속됩니다. 모델이 폐기되었거나 `availableModels`에서 허용되지 않을 때, 시작 시 `--model` 플래그 또는 `ANTHROPIC_MODEL` 계열 환경 변수가 모델을 선택할 때, 또는 [Amazon Bedrock, Google Cloud의 Agent Platform 및 Microsoft Foundry](/docs/ko/third-party-integrations)와 같이 공급자별 배포 ID를 사용하는 공급자에서는 모델이 복원되지 않습니다. [모델 구성](/docs/ko/model-config#setting-your-model)에서 해결 순서를 참조하세요.68* 모델: 세션은 사용 중이던 모델에서 계속됩니다. 단, [모델 설정](/docs/ko/model-config#setting-your-model)에 설명된 경우는 제외됩니다.

69* 에이전트: [`--agent`](/docs/ko/sub-agents#invoke-subagents-explicitly) 또는 `agent` 설정으로 시작된 세션은 해당 에이전트로 계속되며 도구 제한 및 모델을 유지합니다. 재개할 때 `--agent`를 전달하여 다른 에이전트를 선택합니다. 두 경우 모두 시스템 프롬프트는 [재개된 대화의 시스템 프롬프트 플래그](/docs/ko/cli-reference#system-prompt-flags-in-resumed-conversations)를 참조하세요. Claude Code는 두 위치에서 에이전트를 찾습니다: 세션의 원본 디렉토리(해당 워크스페이스를 [신뢰](/docs/ko/permissions#project-allow-rules-and-workspace-trust)한 경우) 및 재개하는 디렉토리이므로 프로젝트 범위 에이전트는 다른 디렉토리에서 재개할 때도 로드됩니다. Claude Code가 두 위치 모두에서 에이전트를 찾지 못하면 세션은 기본 도구로 재개되고 [에이전트 이름을 지정하는 경고](/docs/ko/errors#session-agent-no-longer-available)를 표시합니다.69* 에이전트: [`--agent`](/docs/ko/sub-agents#invoke-subagents-explicitly) 또는 `agent` 설정으로 시작된 세션은 해당 에이전트로 계속되며 도구 제한 및 모델을 유지합니다. 재개할 때 `--agent`를 전달하여 다른 에이전트를 선택합니다. 두 경우 모두 시스템 프롬프트는 [재개된 대화의 시스템 프롬프트 플래그](/docs/ko/cli-reference#system-prompt-flags-in-resumed-conversations)를 참조하세요. Claude Code는 두 위치에서 에이전트를 찾습니다: 세션의 원본 디렉토리(해당 워크스페이스를 [신뢰](/docs/ko/permissions#project-allow-rules-and-workspace-trust)한 경우) 및 재개하는 디렉토리이므로 프로젝트 범위 에이전트는 다른 디렉토리에서 재개할 때도 로드됩니다. Claude Code가 두 위치 모두에서 에이전트를 찾지 못하면 세션은 기본 도구로 재개되고 [에이전트 이름을 지정하는 경고](/docs/ko/errors#session-agent-no-longer-available)를 표시합니다.

70* 권한 모드: 터미널에서 `claude --continue`, `claude --resume <session-id>` 또는 이름이 한 세션과 일치할 때 `-p` 없이 `claude --resume <name>`으로 재개하면 Claude Code는 세션이 있던 권한 모드를 복원합니다. 단, [재개 시 권한 모드](#permission-mode-on-resume)의 경우는 제외되며, 이는 세션 선택기, `/resume` 및 `claude -p`로 재개하는 경우도 포함합니다. `--permission-mode` 또는 `--dangerously-skip-permissions`를 전달하여 복원된 모드를 재정의합니다.70* 권한 모드: 터미널에서 `claude --continue`, `claude --resume <session-id>` 또는 이름이 한 세션과 일치할 때 `-p` 없이 `claude --resume <name>`으로 재개하면 Claude Code는 세션이 있던 권한 모드를 복원합니다. 단, [재개 시 권한 모드](#permission-mode-on-resume)의 경우는 제외되며, 이는 세션 선택기, `/resume` 및 `claude -p`로 재개하는 경우도 포함합니다. `--permission-mode` 또는 `--dangerously-skip-permissions`를 전달하여 복원된 모드를 재정의합니다.

71* 활성 목표: 세션이 종료될 때 여전히 활성이던 [목표](/docs/ko/goal#resume-with-an-active-goal)는 이월됩니다. 해당 턴 수, 타이머 및 토큰 지출 기준선이 재설정됩니다.71* 활성 목표: 세션이 종료될 때 여전히 활성이던 [목표](/docs/ko/goal#resume-with-an-active-goal)는 이월됩니다. 해당 턴 수, 타이머 및 토큰 지출 기준선이 재설정됩니다.

~~72* 예약된 작업: [만료되지 않은 작업](/docs/ko/scheduled-tasks#limitations)이 복원됩니다. 백그라운드 Bash 및 모니터 작업은 복원되지 않습니다.~~72* 예약 작업: [만료되지 않은 작업](/docs/ko/scheduled-tasks#limitations)이 복원됩니다. 백그라운드 Bash 및 모니터 작업은 복원되지 않습니다.

73* 백그라운드 작업: [백그라운드 서브에이전트](/docs/ko/sub-agents#run-subagents-in-foreground-or-background), 백그라운드 Bash 명령 또는 이전 프로세스로 끝난 [워크플로우](/docs/ko/workflows)는 재개된 대화 기록에 완료되지 않았다는 메모로 표시됩니다. Claude Code는 이러한 메모에서 턴을 시작하지 않습니다. Claude는 다음 프롬프트와 함께 이를 읽습니다.73* 백그라운드 작업: [백그라운드 서브에이전트](/docs/ko/sub-agents#run-subagents-in-foreground-or-background), 백그라운드 Bash 명령 또는 이전 프로세스로 끝난 [워크플로](/docs/ko/workflows)는 재개된 트랜스크립트에 완료되지 않았다는 메모로 표시됩니다. Claude Code는 이러한 메모에서 턴을 시작하지 않습니다. Claude는 다음 프롬프트와 함께 이를 읽습니다.

74 74

75원본 시작의 모든 구성 플래그가 복원되는 것은 아닙니다. 세션이 `--mcp-config`, `--settings`, `--plugin-dir`, `--fallback-model` 또는 `--add-dir`로 추가된 디렉토리에 의존하는 경우 재개할 때 다시 전달합니다. 세션 중간에 `/add-dir`로 추가된 디렉토리도 복원되지 않지만 세션 선택기는 여전히 이를 사용하여 세션을 찾습니다. `settings.json` 및 `settings.local.json`과 같은 표준 설정 파일은 시작 시 다시 읽히므로 이들 파일에 있는 구성은 다시 전달할 필요가 없습니다. `--system-prompt` 및 `--append-system-prompt`는 [재개된 대화의 시스템 프롬프트 플래그](/docs/ko/cli-reference#system-prompt-flags-in-resumed-conversations)를 참조하세요.75원본 시작의 모든 구성 플래그가 복원되는 것은 아닙니다. 세션이 `--mcp-config`, `--settings`, `--plugin-dir`, `--fallback-model` 또는 `--add-dir`로 추가된 디렉토리에 의존하는 경우 재개할 때 다시 전달합니다. 세션 중간에 `/add-dir`로 추가된 디렉토리도 복원되지 않지만 세션 선택기는 여전히 이를 사용하여 세션을 찾습니다. `settings.json` 및 `settings.local.json`과 같은 표준 설정 파일은 시작 시 다시 읽히므로 이들 파일에 있는 구성은 다시 전달할 필요가 없습니다. `--system-prompt` 및 `--append-system-prompt`는 [재개된 대화의 시스템 프롬프트 플래그](/docs/ko/cli-reference#system-prompt-flags-in-resumed-conversations)를 참조하세요.

76 76

78 재개 시 권한 모드78 재개 시 권한 모드

79</h4>79</h4>

80 80

81Claude Code가 재개된 세션을 시작하는 권한 모드는 재개 방식에 따라 달라집니다. 아래 경우는 Claude Code가 대화 기록에서 대화를 로드할 때 적용됩니다. [여전히 실행 중인 백그라운드 세션을 열 때](#resume-a-running-background-session)는 해당 세션이 있는 권한 모드를 유지합니다.81Claude Code가 재개된 세션을 시작하는 권한 모드는 재개 방식에 따라 달라집니다. 아래 경우는 Claude Code가 트랜스크립트에서 대화를 로드할 때 적용됩니다. [여전히 실행 중인 백그라운드 세션을 열 때](#resume-a-running-background-session)는 해당 세션이 있는 권한 모드를 유지합니다.

82 82

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

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

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

86* 시작 시 세션 선택기: `claude --resume` 단독, `claude --from-pr` 또는 이름이 여러 세션과 일치할 때 [세션 선택기](#use-the-session-picker)에서 선택한 세션입니다. Claude Code는 저장된 권한 모드를 복원하지 않습니다. 동일한 명령줄에서 새 세션을 시작할 권한 모드로 세션을 시작합니다.86* 시작 시 세션 선택기: `claude --resume` 단독, `claude --from-pr` 또는 여러 세션과 일치하는 이름 중 어느 방법으로 열었든 [세션 선택기](#use-the-session-picker)에서 선택한 세션입니다. Claude Code는 동일한 명령줄에서 새 세션을 시작할 권한 모드로 세션을 시작합니다. 단, 플랜 모드에서 종료된 세션은 `--permission-mode`, `--dangerously-skip-permissions` 또는 `--fork-session`을 전달하지 않는 한 플랜 모드로 재개됩니다. 그 외의 저장된 권한 모드는 복원되지 않습니다.

87* 세션 내 `/resume`(인수 있음 또는 없음): Claude Code는 저장된 권한 모드를 복원하지 않습니다. 전환하는 대화는 현재 세션이 있는 권한 모드에서 계속됩니다.87* 세션 내 `/resume`(인수 있음 또는 없음): 전환하는 대화는 현재 세션이 있는 권한 모드에서 계속됩니다. 단, 플랜 모드에서 종료된 대화는 `--permission-mode` 또는 `--dangerously-skip-permissions`로 Claude Code를 시작했더라도 플랜 모드로 재개됩니다. 해당 대화가 이번 Claude Code 실행에서 이미 열린 적이 있다면(예: 처음 시작한 대화나 `/clear` 또는 `/resume`으로 떠난 대화) 대신 현재 권한 모드에서 계속됩니다.

88 88

89비대화형 및 VS Code 경로에서 계획 모드 복원은 Claude Code v2.1.246 이상이 필요합니다. 각 행은 세션이 종료된 권한 모드, 재개하는 터미널, 비대화형 및 VS Code 경로 중 어느 것인지, 그리고 Claude Code가 재개된 세션을 시작하는 권한 모드를 나타냅니다.89비대화형 및 VS Code 경로에서 플랜 모드 복원은 Claude Code v2.1.246 이상이 필요합니다. 각 행은 세션이 종료된 권한 모드, 재개하는 터미널, 비대화형 및 VS Code 경로 중 어느 것인지, 그리고 Claude Code가 재개된 세션을 시작하는 권한 모드를 나타냅니다.

90 90

92| :- | :- | :- |92| :- | :- | :- |

93| `bypassPermissions` | 터미널 | 새 세션이 시작될 권한 모드입니다. [권한을 다시 우회](/docs/ko/permission-modes#skip-all-checks-with-bypasspermissions-mode)하려면 시작 시 해당 플래그 중 하나 또는 [사용자, `--settings` 또는 관리 설정](/docs/ko/settings-reference#permissions-defaultmode)의 `permissions.defaultMode: "bypassPermissions"`로 활성화합니다 |93| `bypassPermissions` | 터미널 | 새 세션이 시작될 권한 모드입니다. [권한을 다시 우회](/docs/ko/permission-modes#skip-all-checks-with-bypasspermissions-mode)하려면 시작 시 해당 플래그 중 하나 또는 [사용자, `--settings` 또는 관리형 설정](/docs/ko/settings-reference#permissions-defaultmode)의 `permissions.defaultMode: "bypassPermissions"`로 활성화합니다 |

~~94| `plan` | 터미널 | 새 세션이 시작될 권한 모드입니다 |~~94| `plan` | 터미널 | 플랜 모드입니다. `--fork-session`을 사용하면 새 세션이 시작될 권한 모드입니다 |

95| `auto` | 터미널 | `auto`(계정이 여전히 [자동 모드 요구 사항](/docs/ko/permission-modes#eliminate-prompts-with-auto-mode)을 충족하는 경우에만) |95| `auto` | 터미널 | `auto`(계정이 여전히 [자동 모드 요구 사항](/docs/ko/permission-modes#eliminate-prompts-with-auto-mode)을 충족하는 경우에만) |

96| Manual | 터미널 | 새 세션이 [기본 제공 기본값](/docs/ko/permission-modes#which-mode-a-session-starts-in)에서 자동 모드로 시작될 때 수동입니다. 설정 파일의 `defaultMode`가 [적용](/docs/ko/permission-modes#which-mode-a-session-starts-in)되면 Claude Code는 재개된 세션을 해당 모드로 시작합니다 |96| Manual | 터미널 | 새 세션이 [기본 제공 기본값](/docs/ko/permission-modes#which-mode-a-session-starts-in)에서 자동 모드로 시작될 때 수동입니다. 설정 파일의 `defaultMode`가 [적용](/docs/ko/permission-modes#which-mode-a-session-starts-in)되면 Claude Code는 재개된 세션을 해당 모드로 시작합니다 |

100

101<a id="resume-in-plan-mode-with-p" />

100 102

101<h5 id="resume-in-plan-mode-with-p">103<h5 id="resume-in-plan-mode-with-p">

102 `-p`로 계획 모드에서 재개104 `-p`로 플랜 모드에서 재개

103</h5>105</h5>

104 106

105`claude -p --resume` 또는 `claude -p --continue` 실행은 네 가지 조건이 모두 충족될 때만 계획 모드에서 재개됩니다:107`claude -p --resume` 또는 `claude -p --continue` 실행은 다음 조건이 모두 충족될 때만 플랜 모드에서 재개됩니다:

106 108

107* [`--permission-prompt-tool`](/docs/ko/cli-reference#cli-flags)을 전달하고 [`--permission-prompts none`](/docs/ko/headless#turn-off-permission-prompts-in-unattended-runs)을 전달하지 않아서 Claude Code가 승인을 위해 계획을 제시할 수 있습니다109* [`--permission-prompt-tool`](/docs/ko/cli-reference#cli-flags)을 전달하고 [`--permission-prompts none`](/docs/ko/headless#turn-off-permission-prompts-in-unattended-runs)을 전달하지 않아서 Claude Code가 승인을 위해 계획을 제시할 수 있습니다

108* `--permission-mode` 또는 `--dangerously-skip-permissions`를 전달하지 않습니다110* `--permission-mode` 또는 `--dangerously-skip-permissions`를 전달하지 않습니다

136 138

137첫 번째 프롬프트가 [`/loop`](/docs/ko/scheduled-tasks#run-a-prompt-repeatedly-with-%2Floop) 명령인 세션은 선택기에 나타나지 않으며 `claude --continue`도 이를 건너뜁니다. 대화 후반에 `/loop`를 실행해도 세션이 숨겨지지 않습니다. v2.1.211 이전에는 대화 초반에 `/loop` 실행이 선택기에서 세션을 영구적으로 숨겼습니다.139첫 번째 프롬프트가 [`/loop`](/docs/ko/scheduled-tasks#run-a-prompt-repeatedly-with-%2Floop) 명령인 세션은 선택기에 나타나지 않으며 `claude --continue`도 이를 건너뜁니다. 대화 후반에 `/loop`를 실행해도 세션이 숨겨지지 않습니다. v2.1.211 이전에는 대화 초반에 `/loop` 실행이 선택기에서 세션을 영구적으로 숨겼습니다.

138 140

139[`/cd`](/docs/ko/commands)로 세션을 이동하면 새 디렉토리의 프로젝트 저장소로 재배치되므로 이후 해당 디렉토리의 선택기에 나타납니다. v2.1.196부터 이동된 세션은 충돌이나 강제 종료 후에도 이전 디렉토리의 선택기에서 제외된 상태로 유지됩니다. 이전 버전에서는 언더스코어와 같은 특수 문자가 포함된 이전 경로가 있을 때 깔끔하지 않은 종료 후 이전 디렉토리의 목록에 다시 나타날 수 있습니다.141[`/cd`](/docs/ko/commands)로 세션을 이동하면 새 디렉토리의 프로젝트 스토리지로 재배치되므로 이후 해당 디렉토리의 선택기에 나타납니다. v2.1.196부터 이동된 세션은 충돌이나 강제 종료 후에도 이전 디렉토리의 선택기에서 제외된 상태로 유지됩니다. 이전 버전에서는 언더스코어와 같은 특수 문자가 포함된 이전 경로가 있을 때 깔끔하지 않은 종료 후 이전 디렉토리의 목록에 다시 나타날 수 있습니다.

140 142

141같은 저장소의 다른 worktree에서 세션을 선택하면 그 위치에서 재개됩니다. 세션의 자체 worktree가 더 이상 존재하지 않으면 Claude Code는 [현재 디렉토리에서 재개](/docs/ko/worktrees#resume-a-worktree-session)합니다. 관련 없는 프로젝트에서 세션을 선택하면 Claude Code는 `cd` 및 재개 명령을 클립보드에 복사합니다. 해당 프로젝트의 디렉토리가 더 이상 존재하지 않으면 Claude Code는 실패할 `cd` 명령을 복사하는 대신 현재 디렉토리에서 세션을 재개합니다.143같은 저장소의 다른 worktree에서 세션을 선택하면 그 위치에서 재개됩니다. 세션의 자체 worktree가 더 이상 존재하지 않으면 Claude Code는 [현재 디렉토리에서 재개](/docs/ko/worktrees#resume-a-worktree-session)합니다. 관련 없는 프로젝트에서 세션을 선택하면 Claude Code는 `cd` 및 재개 명령을 클립보드에 복사합니다. 해당 프로젝트의 디렉토리가 더 이상 존재하지 않으면 Claude Code는 실패할 `cd` 명령을 복사하는 대신 현재 디렉토리에서 세션을 재개합니다.

142 144

settings.md +33 −31

Details

411 411

412파일 열에서 `~/.claude`는 홈 디렉토리의 `.claude` 폴더이고, 단순 `.claude`는 프로젝트 내부의 `.claude` 폴더입니다.412파일 열에서 `~/.claude`는 홈 디렉토리의 `.claude` 폴더이고, 단순 `.claude`는 프로젝트 내부의 `.claude` 폴더입니다.

413 413

659 659

660순서대로, 가장 높은 우선순위부터:660순서대로, 가장 높은 우선순위부터:

661 661

6621. **관리되는 설정**: 조직이 배포하는 설정으로, `managed-settings.json` 파일, MDM 정책, 또는 claude.ai 콘솔의 [서버 관리 설정](/docs/ko/server-managed-settings)입니다. 사용자가 설정한 것은 이를 재정의할 수 없습니다. `--settings`로 전달한 키는 동일한 관리되는 키를 재정의하지 않으며, `--model`과 같은 플래그는 조직이 허용하는 모델에서만 선택합니다. 관리되는 `model`은 각 세션이 시작되는 모델을 설정하며, `/model`로 전환할 수 있습니다. 잠금은 [`availableModels`](/docs/ko/settings-reference#availablemodels)이며, 이는 `/model`, `--model`, 및 자신의 파일의 `model` 키를 제한합니다. 조직이 둘 이상의 관리되는 소스를 제공할 때, [관리되는 계층 내 우선순위](/docs/ko/managed-settings#precedence-within-the-managed-tier)의 규칙은 Claude Code가 각각에서 읽는 것을 나타냅니다.6621. **관리형 설정**: 조직이 배포하는 설정으로, `managed-settings.json` 파일, MDM 정책, 또는 claude.ai 콘솔의 [서버 관리형 설정](/docs/ko/server-managed-settings)입니다. 자신의 설정 파일이나 `--settings`의 어떤 것도 관리형 키를 재정의하지 않으며, `--model`과 같은 플래그는 조직이 허용하는 모델 중에서만 선택합니다. 관리형 [`model`](/docs/ko/settings-reference#model)은 시작 기본값일 뿐 잠금이 아닙니다. 잠금은 [`availableModels`](/docs/ko/settings-reference#availablemodels)와 [`deniedModels`](/docs/ko/settings-reference#deniedmodels)입니다. 조직이 둘 이상의 관리형 소스를 제공할 때, [관리형 계층 내 우선순위](/docs/ko/managed-settings#precedence-within-the-managed-tier)의 규칙은 Claude Code가 각각에서 읽는 것을 나타냅니다.

6632. **명령줄 인수**: 터미널에서 `claude`를 시작할 때 전달하는 플래그로, 한 세션 동안 적용됩니다. [한 세션 동안 설정 변경](#change-a-setting-for-one-session)을 참조하세요. Claude Code는 `--settings <file-or-json>`으로 전달한 JSON을 다른 수준과 동일한 규칙으로 설정 파일과 병합합니다. 여기서 설정한 키를 로컬, 프로젝트 또는 사용자 설정의 동일한 키보다 우선하며, 생략한 키에 대해서는 낮은 수준의 값을 유지합니다.6632. **명령줄**: `claude`를 시작할 때 `--settings <file-or-json>`으로 전달하는 JSON으로, 해당 세션에만 적용됩니다. [한 세션 동안 설정 변경](#change-a-setting-for-one-session)을 참조하세요. 여기서 설정한 키는 프로젝트 및 사용자 설정 파일의 동일한 키를 재정의하며, 생략한 키는 해당 파일의 값을 유지합니다. `--model`과 같은 다른 플래그는 세션에 대해 한 가지를 설정하며 이 스택에 포함되지 않습니다. [설정 참조](/docs/ko/settings-reference)의 키 항목은 어떤 플래그가 해당 키를 재정의하는지 나타냅니다.

6643. **프로젝트 로컬 설정** (`.claude/settings.local.json`): 이 프로젝트에 대한 개인 설정입니다.6643. **프로젝트 로컬 설정** (`.claude/settings.local.json`): 이 프로젝트에 대한 개인 설정입니다.

6654. **공유 프로젝트 설정** (`.claude/settings.json`): 팀이 소스 제어에 체크인하는 설정입니다.6654. **공유 프로젝트 설정** (`.claude/settings.json`): 팀이 소스 제어에 체크인하는 설정입니다.

6665. **사용자 설정** (`~/.claude/settings.json`): 모든 프로젝트에 대한 개인 설정입니다.6665. **사용자 설정** (`~/.claude/settings.json`): 모든 프로젝트에 대한 개인 설정입니다.

667 667

668환경 변수는 이 스택의 수준이 아닙니다. 동작에 셸 변수와 설정 키가 모두 있을 때, 어느 것이 적용되는지는 수준이 아닌 쌍별로 결정됩니다. 셸에서 내보낸 `ANTHROPIC_MODEL`은 모든 파일의 `model` 키보다 우선하지만, `ANTHROPIC_DEFAULT_MODEL`은 파일이 `model`을 설정하지 않을 때만 적용됩니다. [환경 변수 참조](/docs/ko/env-vars#precedence)는 어느 키가 쌍을 가지고 있으며 Claude Code가 먼저 읽는 것을 나타냅니다. 설정 파일 내의 `env` 블록은 일반 키이며 위의 수준을 따릅니다.668환경 변수는 이 스택의 수준이 아닙니다. 동작에 셸 변수와 설정 키가 모두 있을 때, 어느 것이 적용되는지는 수준이 아닌 쌍별로 결정됩니다. 셸에서 내보낸 `ANTHROPIC_MODEL`은 모든 파일의 `model` 키보다 우선하지만, `ANTHROPIC_DEFAULT_MODEL`은 파일이 `model`을 설정하지 않을 때만 적용됩니다. [환경 변수 참조](/docs/ko/env-vars#precedence)는 어느 키가 쌍을 가지고 있으며 Claude Code가 먼저 읽는 것을 나타냅니다. 설정 파일 내의 `env` 블록은 일반 키이며 위의 수준을 따릅니다.

669 669

670몇 가지 보안에 민감한 키의 경우, Claude Code는 관리되는 값보다 낮은 수준의 더 엄격한 값을 준수합니다. [관리되는 설정 우선순위의 예외](#exceptions-to-managed-settings-precedence)에 이를 나열합니다.670몇 가지 보안에 민감한 키의 경우, Claude Code는 관리형 값보다 낮은 수준의 더 엄격한 값을 준수합니다. [관리형 설정 우선순위의 예외](#exceptions-to-managed-settings-precedence)에 이를 나열합니다.

671 671

672<h3 id="lists-merge-instead-of-overriding">672<h3 id="lists-merge-instead-of-overriding">

673 목록은 재정의 대신 병합됩니다673 목록은 재정의 대신 병합됩니다

676`permissions.allow`와 같은 동일한 목록 키를 둘 이상의 파일에서 설정할 때, Claude Code는 하나를 선택하는 대신 목록을 결합하므로 각 파일은 다른 파일의 항목을 제거하지 않고 항목을 추가할 수 있습니다. 모델 목록 또는 모델별 항목을 보유하는 네 가지 키는 자신의 규칙을 따릅니다.676`permissions.allow`와 같은 동일한 목록 키를 둘 이상의 파일에서 설정할 때, Claude Code는 하나를 선택하는 대신 목록을 결합하므로 각 파일은 다른 파일의 항목을 제거하지 않고 항목을 추가할 수 있습니다. 모델 목록 또는 모델별 항목을 보유하는 네 가지 키는 자신의 규칙을 따릅니다.

677 677

678* [`fallbackModel`](/docs/ko/settings-reference#fallbackmodel)은 위치가 의미를 갖는 정렬된 체인이므로, Claude Code는 이를 정의하는 가장 높은 우선순위 파일의 전체 값을 사용합니다.678* [`fallbackModel`](/docs/ko/settings-reference#fallbackmodel)은 위치가 의미를 갖는 정렬된 체인이므로, Claude Code는 이를 정의하는 가장 높은 우선순위 파일의 전체 값을 사용합니다.

679* [`modelPicker`](/docs/ko/settings-reference#modelpicker)는 하나의 정렬된 행 목록과 교체 플래그를 보유하므로, Claude Code는 두 소스의 행을 병합하지 않습니다. 이를 정의하는 관리되는 설정, `--settings`, 및 사용자 설정 중 가장 높은 것의 전체 값을 사용하며, 프로젝트 및 로컬 설정의 키를 무시합니다. Claude Code v2.1.242 이상이 필요합니다.679* [`modelPicker`](/docs/ko/settings-reference#modelpicker)는 하나의 정렬된 행 목록과 교체 플래그를 보유하므로, Claude Code는 두 소스의 행을 병합하지 않습니다. 이를 정의하는 관리형 설정, `--settings`, 및 사용자 설정 중 가장 높은 것의 전체 값을 사용하며, 프로젝트 및 로컬 설정의 키를 무시합니다. Claude Code v2.1.242 이상이 필요합니다.

680* [`availableModels`](/docs/ko/settings-reference#availablemodels): Claude Code가 적용하는 관리되는 설정이 이를 정의할 때, Claude Code는 해당 목록을 그대로 적용하고 사용자, 프로젝트 또는 로컬 설정에서 추가하는 항목을 무시합니다. 단, Claude Code를 포함하는 앱이 자신의 모델 목록을 제공하는 경우는 제외합니다. [관리되는 설정 우선순위의 예외](#exceptions-to-managed-settings-precedence)를 참조하세요. 관리되는 소스 전체에서 목록은 병합되지 않습니다. [Claude Code가 관리되는 소스를 결합하는 방법](/docs/ko/managed-settings#how-claude-code-combines-managed-sources)은 어느 소스의 목록이 적용되는지 나타냅니다. 관리되지 않는 범위 전체에서 Claude Code는 일반적으로 배열을 병합합니다.680* [`availableModels`](/docs/ko/settings-reference#availablemodels): Claude Code가 적용하는 관리형 설정이 이를 정의할 때, Claude Code는 해당 목록을 그대로 적용하고 사용자, 프로젝트 또는 로컬 설정에서 추가하는 항목을 무시합니다. 단, Claude Code를 포함하는 앱이 자신의 모델 목록을 제공하는 경우는 제외합니다. [관리형 설정 우선순위의 예외](#exceptions-to-managed-settings-precedence)를 참조하세요. 관리형 소스 전체에서 목록은 병합되지 않습니다. [Claude Code가 관리형 소스를 결합하는 방법](/docs/ko/managed-settings#how-claude-code-combines-managed-sources)은 어느 소스의 목록이 적용되는지 나타냅니다. 관리형이 아닌 범위 전체에서 Claude Code는 일반적으로 배열을 병합합니다.

681* [`modelSettings`](/docs/ko/settings-reference#modelsettings): Claude Code는 [`effortLevel`](/docs/ko/settings-reference#effortlevel)과 함께 한 번에 하나의 모델로 이를 해결합니다. `modelSettings` 항목은 어느 파일의 값이 모델에 적용되는지 나타냅니다.681* [`modelSettings`](/docs/ko/settings-reference#modelsettings): Claude Code는 [`effortLevel`](/docs/ko/settings-reference#effortlevel)과 함께 한 번에 하나의 모델로 이를 해결합니다. `modelSettings` 항목은 어느 파일의 값이 모델에 적용되는지 나타냅니다.

682 682

683<span id="examples" />683<span id="examples" />

700 조직 설정이 모든 것을 재정의합니다700 조직 설정이 모든 것을 재정의합니다

701</h4>701</h4>

702 702

703조직의 관리되는 설정이 이를 `true`로 설정합니다. 사용자, 프로젝트 또는 로컬 설정에 넣은 것도 팁을 끌 수 없으며, `--settings`도 마찬가지입니다. 관리되는 것이 최상위 수준입니다.703조직의 관리형 설정이 이를 `true`로 설정합니다. 사용자, 프로젝트 또는 로컬 설정에 넣은 것도 팁을 끌 수 없으며, `--settings`도 마찬가지입니다. 관리형이 최상위 수준입니다.

704 704

705값을 다시 얻을 수 없습니다. `/status`를 실행하여 어느 관리되는 소스가 적용되는지 확인하고, 정책을 변경해야 하는지 관리자에게 문의합니다.705값을 다시 얻을 수 없습니다. `/status`를 실행하여 어느 관리형 소스가 적용되는지 확인하고, 정책을 변경해야 하는지 관리자에게 문의합니다.

706 706

707<h4 id="the-command-line-overrides-your-files-for-one-session">707<h4 id="the-command-line-overrides-your-files-for-one-session">

708 명령줄이 한 세션 동안 파일을 재정의합니다708 명령줄이 한 세션 동안 파일을 재정의합니다

709</h4>709</h4>

710 710

711`claude --settings '{"spinnerTipsEnabled": true}'`로 세션을 시작했습니다. 명령줄은 관리되는 것을 제외한 모든 파일 위에 있으므로, 파일이 `false`라고 말해도 해당 세션은 팁을 표시합니다.711`claude --settings '{"spinnerTipsEnabled": true}'`로 세션을 시작했습니다. 명령줄은 관리형을 제외한 모든 파일 위에 있으므로, 파일이 `false`라고 말해도 해당 세션은 팁을 표시합니다.

712 712

713다음 세션에서 값을 다시 얻습니다. `--settings`는 한 세션 동안만 지속되며 파일에 쓰지 않습니다.713다음 세션에서 값을 다시 얻습니다. `--settings`는 한 세션 동안만 지속되며 파일에 쓰지 않습니다.

714 714

740 740

741다른 것이 동일한 키를 설정하거나, 파일이 해당 값을 설정할 수 없거나, 파일이 로드되지 않았습니다.741다른 것이 동일한 키를 설정하거나, 파일이 해당 값을 설정할 수 없거나, 파일이 로드되지 않았습니다.

742 742

743* **더 높은 수준이 이를 설정합니다.** 다른 설정 파일, `--settings` 플래그, 또는 관리되는 소스가 키를 위에서 설정합니다. [스택](#settings-precedence)은 어느 것인지 나타냅니다. 플래그 또는 환경 변수도 키별로 결정되는 키를 자체적으로 재정의할 수 있습니다. [설정 참조](/docs/ko/settings-reference)의 키 항목은 Claude Code가 어느 것을 사용하는지 나타내며, [`env` 항목](/docs/ko/settings-reference#env)은 관리되는 `env` 값 대 셸 내보내기를 다룹니다.743* **더 높은 수준이 이를 설정합니다.** 다른 설정 파일, `--settings` 플래그, 또는 관리형 소스가 키를 위에서 설정합니다. [스택](#settings-precedence)은 어느 것인지 나타냅니다. 플래그 또는 환경 변수도 키별로 결정되는 키를 자체적으로 재정의할 수 있습니다. [설정 참조](/docs/ko/settings-reference)의 키 항목은 Claude Code가 어느 것을 사용하는지 나타내며, [`env` 항목](/docs/ko/settings-reference#env)은 관리형 `env` 값 대 셸 내보내기를 다룹니다.

744* **보안 키가 엄격한 값을 유지합니다.** 몇 가지 키의 경우 Claude Code는 모든 파일의 제한적인 값을 준수하므로, 프로젝트 `true`는 [`disableClaudeAiConnectors`](/docs/ko/settings-reference#disableclaudeaiconnectors)에 대해 켜진 상태로 유지됩니다. [관리되는 설정 우선순위의 예외](#exceptions-to-managed-settings-precedence)를 참조하세요.744* **보안 키가 엄격한 값을 유지합니다.** 몇 가지 키의 경우 Claude Code는 모든 파일의 제한적인 값을 준수하므로, 프로젝트 `true`는 [`disableClaudeAiConnectors`](/docs/ko/settings-reference#disableclaudeaiconnectors)에 대해 켜진 상태로 유지됩니다. [관리형 설정 우선순위의 예외](#exceptions-to-managed-settings-precedence)를 참조하세요.

745* **파일이 해당 값을 설정할 수 없습니다.** [`permissions.defaultMode`](/docs/ko/settings-reference#permissions-defaultmode) 값 `auto`와 `bypassPermissions`은 프로젝트 또는 로컬 설정에서 적용되지 않습니다. 대신 사용자 또는 관리되는 설정에서 설정하거나, 한 세션 동안 `--permission-mode`를 전달합니다. v2.1.257 이전에는 `bypassPermissions`이 모든 파일에서 적용되었습니다.745* **파일이 해당 값을 설정할 수 없습니다.** [`permissions.defaultMode`](/docs/ko/settings-reference#permissions-defaultmode) 값 `auto`와 `bypassPermissions`은 프로젝트 또는 로컬 설정에서 적용되지 않습니다. 대신 사용자 또는 관리형 설정에서 설정하거나, 한 세션 동안 `--permission-mode`를 전달합니다. v2.1.257 이전에는 `bypassPermissions`이 모든 파일에서 적용되었습니다.

746 746

747 설정 파일 내의 [`env`](/docs/ko/settings-reference#env) 블록의 원격 분석 내보내기 변수도 프로젝트 또는 로컬 설정에서 적용되지 않습니다. 몇 가지 끄기 값은 제외합니다. [Claude Code가 `env`에서 무시하는 변수](/docs/ko/settings-reference#variables-claude-code-ignores-in-env)는 변수와 해당 값을 나열합니다.747 [`env`](/docs/ko/settings-reference#env) 블록의 텔레메트리 내보내기 변수도 프로젝트 또는 로컬 설정에서 적용되지 않습니다. 몇 가지 끄기 값은 제외합니다. [Claude Code가 `env`에서 무시하는 변수](/docs/ko/settings-reference#variables-claude-code-ignores-in-env)는 변수와 해당 값을 나열합니다.

748* **파일이 손상되었습니다.** 잘못된 JSON 또는 거부된 값은 Claude Code가 파일 또는 항목을 건너뜁니다. [손상된 설정 파일 수정](#fix-a-broken-settings-file)을 참조하세요.748* **파일이 손상되었습니다.** 잘못된 JSON 또는 거부된 값은 Claude Code가 파일 또는 항목을 건너뜁니다. [손상된 설정 파일 수정](#fix-a-broken-settings-file)을 참조하세요.

749 749

750<h4 id="a-change-you-made-in-claude-code-is-lost-in-new-sessions">750<h4 id="a-change-you-made-in-claude-code-is-lost-in-new-sessions">

756파일에 쓸 수 있고 변경 사항이 여전히 지속되지 않으면, 변경 사항이 [한 세션 동안만](#change-a-setting-for-one-session) 또는 [더 높은 수준이 동일한 키를 설정](#a-value-you-set-is-ignored)했는지 확인합니다. `model` 키의 경우, [새 세션이 선택한 것과 다른 모델에서 시작됩니다](/docs/ko/model-config#a-new-session-starts-on-a-different-model-than-you-picked)는 더 많은 원인을 나열합니다.756파일에 쓸 수 있고 변경 사항이 여전히 지속되지 않으면, 변경 사항이 [한 세션 동안만](#change-a-setting-for-one-session) 또는 [더 높은 수준이 동일한 키를 설정](#a-value-you-set-is-ignored)했는지 확인합니다. `model` 키의 경우, [새 세션이 선택한 것과 다른 모델에서 시작됩니다](/docs/ko/model-config#a-new-session-starts-on-a-different-model-than-you-picked)는 더 많은 원인을 나열합니다.

757 757

758<h4 id="a-managed-change-hasn’t-reached-you">758<h4 id="a-managed-change-hasn’t-reached-you">

759 관리되는 변경 사항이 도달하지 않았습니다759 관리형 변경 사항이 도달하지 않았습니다

760</h4>760</h4>

761 761

762관리되는 소스는 [전달 테이블](/docs/ko/managed-settings#choose-a-delivery-mechanism)의 일정에 따라 실행 중인 세션에 도달하므로, 먼저 세션을 다시 시작합니다. `/status`가 관리자가 변경한 것과 다른 소스를 나타내면, 더 높은 우선순위 소스가 적용됩니다. [Claude Code가 관리되는 소스를 결합하는 방법](/docs/ko/managed-settings#how-claude-code-combines-managed-sources)은 순서를 제공합니다.762관리형 소스는 [전달 테이블](/docs/ko/managed-settings#choose-a-delivery-mechanism)의 일정에 따라 실행 중인 세션에 도달하므로, 먼저 세션을 다시 시작합니다. `/status`가 관리자가 변경한 것과 다른 소스를 나타내면, 더 높은 우선순위 소스가 적용됩니다. [Claude Code가 관리형 소스를 결합하는 방법](/docs/ko/managed-settings#how-claude-code-combines-managed-sources)은 순서를 제공합니다.

763 763

764<h4 id="a-committed-key-doesn’t-reach-teammates">764<h4 id="a-committed-key-doesn’t-reach-teammates">

765 커밋된 키가 팀원에게 도달하지 않습니다765 커밋된 키가 팀원에게 도달하지 않습니다

767 767

768두 가지가 `.claude/settings.json`의 키가 이를 복제하는 모든 사람에게 적용되는 것을 방지합니다.768두 가지가 `.claude/settings.json`의 키가 이를 복제하는 모든 사람에게 적용되는 것을 방지합니다.

769 769

770* **Claude Code는 저장소 파일의 키를 무시합니다.** [설정 인덱스](/docs/ko/settings-reference#settings-index)의 범위 열에서 `User, local, or managed`, `User or managed`, `Managed`, 또는 `Global config`를 찾습니다. 이러한 키는 공유 파일에서 적용되지 않습니다. 저장소 파일은 여전히 키를 끌 수 있습니다. `Global config` 키는 `~/.claude.json`에서만 적용됩니다.770* **Claude Code는 저장소 파일의 키를 무시합니다.** [설정 인덱스](/docs/ko/settings-reference#settings-index)의 범위 열에서 `User, local, or managed`, `User or managed`, `Managed`, 또는 `Global config`를 찾습니다. 이러한 키는 공유 파일에서 적용되지 않으며, 저장소 파일이 여전히 끌 수 있는 몇 가지 키만 예외입니다. 해당 항목은 각각 범위 줄에 이를 명시합니다. `Global config` 키는 `~/.claude.json`에서만 적용됩니다.

771 771

772 `env` 키 내에서, 원격 분석 내보내기 변수는 공유 파일에서 적용되지 않습니다. 몇 가지 끄기 값은 제외합니다. [Claude Code가 `env`에서 무시하는 변수](/docs/ko/settings-reference#variables-claude-code-ignores-in-env)를 참조하세요.772 `env` 키 내에서, 텔레메트리 내보내기 변수도 공유 파일에서 적용되지 않습니다. 몇 가지 끄기 값은 제외합니다. [Claude Code가 `env`에서 무시하는 변수](/docs/ko/settings-reference#variables-claude-code-ignores-in-env)를 참조하세요.

773* **키가 신뢰를 기다립니다.** `permissions.allow` 규칙, `permissions.additionalDirectories`, `extraKnownMarketplaces`, 및 대부분의 [`env`](/docs/ko/settings-reference#env) 값은 각 팀원이 [폴더를 신뢰](/docs/ko/permissions#project-allow-rules-and-workspace-trust)한 후에만 적용됩니다. 그때까지 그들은 여전히 프롬프트를 보고 파일이 선언하는 마켓플레이스에서 플러그인을 얻지 못합니다. `deny`와 `ask` 규칙은 즉시 적용됩니다.773* **키가 신뢰를 기다립니다.** `permissions.allow` 규칙, `permissions.additionalDirectories`, `extraKnownMarketplaces`, 및 대부분의 [`env`](/docs/ko/settings-reference#env) 값은 각 팀원이 [폴더를 신뢰](/docs/ko/permissions#project-allow-rules-and-workspace-trust)한 후에만 적용됩니다. 그때까지 그들은 여전히 프롬프트를 보고 파일이 선언하는 마켓플레이스에서 플러그인을 얻지 못합니다. `deny`와 `ask` 규칙은 즉시 적용됩니다.

774 774

775<h4 id="permission-rules-combine-differently-than-you-expected">775<h4 id="permission-rules-combine-differently-than-you-expected">

776 권한 규칙이 예상과 다르게 결합됩니다776 권한 규칙이 예상과 다르게 결합됩니다

777</h4>777</h4>

778 778

779* **권한 프롬프트에서 "Yes, and don't ask again"을 선택했지만 여전히 동일한 도구에 대해 프롬프트를 받습니다.** 해당 선택은 `allow` 규칙을 로컬 파일에 저장했으며, 로컬 파일의 `allow` 규칙은 프로젝트 또는 관리되는 파일의 `ask` 규칙을 능가하지 않습니다. [권한 규칙이 결합되는 방법](/docs/ko/permissions#settings-precedence)은 순서를 설명합니다. VS Code 확장에서 승인 카드는 프로젝트의 공유 파일을 포함한 대상 파일을 선택할 수 있으며, 이는 모든 사람을 위한 규칙을 변경합니다. CLI에서 Claude Code는 로컬 파일에만 씁니다.779* **권한 프롬프트에서 "Yes, and don't ask again"을 선택했지만 여전히 동일한 도구에 대해 프롬프트를 받습니다.** 해당 선택은 `allow` 규칙을 로컬 파일에 저장했으며, 로컬 파일의 `allow` 규칙은 프로젝트 또는 관리형 파일의 `ask` 규칙을 능가하지 않습니다. [권한 규칙이 결합되는 방법](/docs/ko/permissions#settings-precedence)은 순서를 설명합니다. VS Code 확장에서 승인 카드는 프로젝트의 공유 파일을 포함한 대상 파일을 선택할 수 있으며, 이는 모든 사람을 위한 규칙을 변경합니다. CLI에서 Claude Code는 로컬 파일에만 씁니다.

780* **조직의 허용 규칙이 여전히 사용자의 규칙과 함께 적용됩니다.** 이는 예상된 것입니다. Claude Code는 조직이 [`allowManagedPermissionRulesOnly`](/docs/ko/settings-reference#allowmanagedpermissionrulesonly)를 설정하지 않는 한 범위 전체에서 [`permissions.allow`](/docs/ko/settings-reference#permissions-allow)를 병합합니다.780* **조직의 허용 규칙이 여전히 사용자의 규칙과 함께 적용됩니다.** 이는 예상된 것입니다. Claude Code는 조직이 [`allowManagedPermissionRulesOnly`](/docs/ko/settings-reference#allowmanagedpermissionrulesonly)를 설정하지 않는 한 범위 전체에서 [`permissions.allow`](/docs/ko/settings-reference#permissions-allow)를 병합합니다.

781 781

782<span id="security-keys-where-the-stricter-value-applies" />782<span id="security-keys-where-the-stricter-value-applies" />

783 783

784<h3 id="exceptions-to-managed-settings-precedence">784<h3 id="exceptions-to-managed-settings-precedence">

785 관리되는 설정 우선순위의 예외785 관리형 설정 우선순위의 예외

786</h3>786</h3>

787 787

788값이 세션을 제한하는 몇 가지 키의 경우, Claude Code는 관리되는 설정을 재정의할 수 없는 범위의 제한적인 값을 준수합니다. 이 표에서 키를 찾아 어느 값을 준수하는지 그리고 어디서 준수하는지 확인합니다.788값이 세션을 제한하는 몇 가지 키의 경우, Claude Code는 관리형 설정을 재정의할 수 없는 범위의 제한적인 값을 준수합니다. 이 표에서 키를 찾아 어느 값을 준수하는지 그리고 어디서 준수하는지 확인합니다.

789 789

790| 키 | Claude Code가 준수하는 값 | 참고 |790| 키 | Claude Code가 준수하는 값 | 참고 |

791| :- | :- | :- |791| :- | :- | :- |

793| [`enableArtifact`](/docs/ko/settings-reference#enableartifact) | 모든 범위의 `false`, 그리고 모든 범위의 `disableArtifact: true` | 관리되는 소스가 `true`를 설정할 때도 준수됩니다. 아무것도 [Artifact 도구](/docs/ko/artifacts#disable-artifacts)를 다시 켤 수 없습니다. Claude Code v2.1.242 이상이 필요합니다 |793| [`enableArtifact`](/docs/ko/settings-reference#enableartifact) | 모든 범위의 `false`, 그리고 모든 범위의 `disableArtifact: true` | 관리형 소스가 `true`를 설정할 때도 준수됩니다. 아무것도 [Artifact 도구](/docs/ko/artifacts#disable-artifacts)를 다시 켤 수 없습니다. Claude Code v2.1.242 이상이 필요합니다 |

795| [`remoteControlAtStartup`](/docs/ko/settings-reference#remotecontrolatstartup) | `.claude/settings.json` 또는 `.claude/settings.local.json`의 `false` | 관리되는 소스가 `true`를 설정할 때도 준수됩니다. 프로젝트 또는 로컬 `true`는 무시됩니다 |795| [`permissions.blockReadsOutsideWorkingDirectories`](/docs/ko/settings-reference#permissions-blockreadsoutsideworkingdirectories) | 모든 범위의 `true` | 관리형 소스가 `false`를 설정할 때도 준수됩니다. Claude Code v2.1.257 이상이 필요합니다 |

796| [`crossSessionInbound`](/docs/ko/settings-reference#crosssessioninbound) | `.claude/settings.json` 또는 `.claude/settings.local.json`의 더 엄격한 값, `accept` \< `hold` \< `refuse` 사다리에서 | 관리되는, `--settings`, 및 사용자 값보다 준수됩니다. 더 엄격하지 않은 프로젝트 또는 로컬 값은 무시됩니다 |796| [`autoMode.classifyAllShell`](/docs/ko/settings-reference#automode-classifyallshell) | `~/.claude/settings.json` 또는 `--settings`의 `true` | 관리형 소스가 `false`를 설정할 때도 준수됩니다 |

797| [`useAutoModeDuringPlan`](/docs/ko/settings-reference#useautomodeduringplan) | 모든 관리되는 소스, `--settings`, `~/.claude/settings.json`, 또는 `.claude/settings.local.json`의 `false` | 승리한 관리되는 소스가 `true`를 설정할 때도 준수됩니다. `.claude/settings.json`의 `false`는 무시됩니다 |797| [`remoteControlAtStartup`](/docs/ko/settings-reference#remotecontrolatstartup) | `.claude/settings.json` 또는 `.claude/settings.local.json`의 `false` | 관리형 소스가 `true`를 설정할 때도 준수됩니다. 프로젝트 또는 로컬 `true`는 무시됩니다 |

798| [`syncClaudeAiSkills`](/docs/ko/settings-reference#syncclaudeaiskills) | 모든 관리되는 소스, `--settings`, `~/.claude/settings.json`, 또는 `.claude/settings.local.json`의 `false` | 승리한 관리되는 소스가 `true`를 설정할 때도 준수됩니다. `.claude/settings.json`의 `false`는 무시됩니다 |798| [`crossSessionInbound`](/docs/ko/settings-reference#crosssessioninbound) | `.claude/settings.json` 또는 `.claude/settings.local.json`의 더 엄격한 값, `accept` \< `hold` \< `refuse` 사다리에서 | 관리형, `--settings`, 및 사용자 값보다 준수됩니다. 더 엄격하지 않은 프로젝트 또는 로컬 값은 무시됩니다 |

799| [`syncClaudeAiPlugins`](/docs/ko/settings-reference#syncclaudeaiplugins) | 모든 관리되는 소스, `--settings`, `~/.claude/settings.json`, 또는 `.claude/settings.local.json`의 `false` | 승리한 관리되는 소스가 `true`를 설정할 때도 준수됩니다. `.claude/settings.json`의 `false`는 무시됩니다 |799| [`useAutoModeDuringPlan`](/docs/ko/settings-reference#useautomodeduringplan) | 모든 관리형 소스, `--settings`, `~/.claude/settings.json`, 또는 `.claude/settings.local.json`의 `false` | 승리한 관리형 소스가 `true`를 설정할 때도 준수됩니다. `.claude/settings.json`의 `false`는 무시됩니다 |

800| [`maxEffortLevel`](/docs/ko/settings-reference#maxeffortlevel) | `--settings`를 포함한 모든 범위의 더 낮은 상한 | Claude Code가 적용하는 관리되는 설정이 더 높은 상한을 설정할 때도 준수됩니다. 가장 낮은 상한이 적용됩니다. Claude Code v2.1.267 이상이 필요합니다 |800| [`syncClaudeAiSkills`](/docs/ko/settings-reference#syncclaudeaiskills) | 모든 관리형 소스, `--settings`, `~/.claude/settings.json`, 또는 `.claude/settings.local.json`의 `false` | 승리한 관리형 소스가 `true`를 설정할 때도 준수됩니다. `.claude/settings.json`의 `false`는 무시됩니다 |

~~801~~ 801| [`syncClaudeAiPlugins`](/docs/ko/settings-reference#syncclaudeaiplugins) | 모든 관리형 소스, `--settings`, `~/.claude/settings.json`, 또는 `.claude/settings.local.json`의 `false` | 승리한 관리형 소스가 `true`를 설정할 때도 준수됩니다. `.claude/settings.json`의 `false`는 무시됩니다 |

802[`CLAUDE_CODE_PROVIDER_MANAGED_BY_HOST`](/docs/ko/env-vars)를 설정하고 Claude Code를 자신 내부에서 실행하는 앱도 예외입니다. Claude Code는 모든 관리되는 소스의 `model`, `fallbackModel`, `modelPicker`, 및 `modelOverrides` 키보다, 그리고 관리되는 `env` 블록의 모델 선택 변수(예: `ANTHROPIC_MODEL` 및 `ANTHROPIC_DEFAULT_*_MODEL` 계열)보다 해당 앱의 모델 구성을 사용합니다. Claude Code는 앱이 자신의 것을 제공하지 않는 한 관리되는 [`availableModels`](/docs/ko/settings-reference#availablemodels) 허용 목록을 적용 중으로 유지합니다.802| [`maxEffortLevel`](/docs/ko/settings-reference#maxeffortlevel) | `--settings`를 포함한 모든 범위의 더 낮은 상한 | Claude Code가 적용하는 관리형 설정이 더 높은 상한을 설정할 때도 준수됩니다. 가장 낮은 상한이 적용됩니다. Claude Code v2.1.267 이상이 필요합니다 |

803

804[`CLAUDE_CODE_PROVIDER_MANAGED_BY_HOST`](/docs/ko/env-vars)를 설정하고 Claude Code를 자신 내부에서 실행하는 앱도 예외입니다. Claude Code는 모든 관리형 소스의 `model`, `fallbackModel`, `modelPicker`, 및 `modelOverrides` 키보다, 그리고 관리형 `env` 블록의 모델 선택 변수(예: `ANTHROPIC_MODEL` 및 `ANTHROPIC_DEFAULT_*_MODEL` 계열)보다 해당 앱의 모델 구성을 사용합니다. Claude Code는 앱이 자신의 것을 제공하지 않는 한 관리형 [`availableModels`](/docs/ko/settings-reference#availablemodels) 허용 목록을 적용 중으로 유지합니다.

803 805

804<h2 id="settings-in-cloud-sessions">806<h2 id="settings-in-cloud-sessions">

805 클라우드 세션의 설정807 클라우드 세션의 설정

settings-reference.md +1 −1

Details

870 870

871이 값을 `false`로 설정하면 모든 세션에서 [확장 사고](/docs/ko/model-config#extended-thinking)를 끕니다. 사고는 기본적으로 켜져 있으므로 `true`는 아무것도 바꾸지 않습니다. 대부분 파일을 편집하는 대신 `/config`를 통해 설정합니다.871이 값을 `false`로 설정하면 모든 세션에서 [확장 사고](/docs/ko/model-config#extended-thinking)를 끕니다. 사고는 기본적으로 켜져 있으므로 `true`는 아무것도 바꾸지 않습니다. 대부분 파일을 편집하는 대신 `/config`를 통해 설정합니다.

872 872

873Opus 5.5, Sonnet 5.5, Fable 모델처럼 항상 사고하는 모델에서는 `false`가 효과가 없습니다. [서드파티 공급자](/docs/ko/third-party-integrations)에서는 Claude Code가 사고를 끄는 대신 `thinking` 매개변수를 생략하므로 적응형 추론 모델은 여전히 사고할 수 있습니다. Anthropic API에서 사고를 끈 상태에서는, Opus 5처럼 [해당 조합을 허용하지 않는](/docs/ko/errors#effort-isnt-available-with-thinking-turned-off) 것으로 알려진 모델에 Claude Code가 더 높은 수준 대신 effort `high`를 보냅니다.873Opus 5.5, Sonnet 5.5, Haiku 5.5, Fable 모델처럼 항상 사고하는 모델에서는 `false`가 효과가 없습니다. [서드파티 공급자](/docs/ko/third-party-integrations)에서는 Claude Code가 사고를 끄는 대신 `thinking` 매개변수를 생략하므로 적응형 추론 모델은 여전히 사고할 수 있습니다. Anthropic API에서 사고를 끈 상태에서는, Opus 5처럼 [해당 조합을 허용하지 않는](/docs/ko/errors#effort-isnt-available-with-thinking-turned-off) 것으로 알려진 모델에 Claude Code가 더 높은 수준 대신 effort `high`를 보냅니다.

874 874

875* **범위**: [`Any file`](#scopes)875* **범위**: [`Any file`](#scopes)

876* **유형**: Boolean876* **유형**: Boolean

setup.md +5 −3

Details

49 curl -fsSL https://claude.ai/install.sh | bash49 curl -fsSL https://claude.ai/install.sh | bash

50 ```50 ```

51 51

52 Windows에서 PowerShell에 있을 때는 프롬프트에 `PS C:\`가 표시되고, CMD에 있을 때는 `PS` 없이 `C:\`만 표시됩니다.

52 **Windows PowerShell:**54 **Windows PowerShell:**

53 55

54 ```powershell theme={null}56 ```powershell theme={null}

63 65

64 설치 프로그램이 완료되면 새 터미널 창을 열고 `claude --version`을 실행하십시오. 설치가 제대로 되었으면 버전 번호가 출력됩니다. 셸에서 `claude`를 찾을 수 없거나 인식되지 않는다고 표시되면 설치 디렉토리가 아직 PATH에 없는 것입니다. [PATH 수정](/docs/ko/troubleshoot-install#command-not-found-claude-after-installation)을 참조하십시오.66 설치 프로그램이 완료되면 새 터미널 창을 열고 `claude --version`을 실행하십시오. 설치가 제대로 되었으면 버전 번호가 출력됩니다. 셸에서 `claude`를 찾을 수 없거나 인식되지 않는다고 표시되면 설치 디렉토리가 아직 PATH에 없는 것입니다. [PATH 수정](/docs/ko/troubleshoot-install#command-not-found-claude-after-installation)을 참조하십시오.

65 67

66 `The token '&&' is not a valid statement separator` 오류가 표시되면 CMD가 아닌 PowerShell에 있는 것입니다. `'irm' is not recognized as an internal or external command` 오류가 표시되면 PowerShell이 아닌 CMD에 있는 것입니다. PowerShell에 있을 때는 프롬프트에 `PS C:\`가 표시되고, CMD에 있을 때는 `PS` 없이 `C:\`만 표시됩니다.68 `The token '&&' is not a valid statement separator` 오류가 표시되면 CMD가 아닌 PowerShell에 있는 것입니다. `'irm' is not recognized as an internal or external command` 오류가 표시되면 PowerShell이 아닌 CMD에 있는 것입니다.

67 69

68 설치 명령이 `syntax error near unexpected token '<'`, `403` 또는 다른 curl 오류로 실패하면 [설치 문제 해결](/docs/ko/troubleshoot-install#find-your-error)을 참조하여 오류를 수정 방법과 일치시키고 대체 설치 방법을 확인하십시오.70 설치 명령이 `syntax error near unexpected token '<'`, `403` 또는 다른 오류로 실패하면 [설치 문제 해결](/docs/ko/troubleshoot-install#find-your-error)을 참조하여 오류를 수정 방법과 일치시키고 대체 설치 방법을 확인하십시오.

69 71

70 [Git for Windows](https://git-scm.com/downloads/win)는 Claude Code가 Bash 도구를 사용할 수 있도록 기본 Windows에서 권장됩니다. Git for Windows가 설치되지 않은 경우 Claude Code는 대신 PowerShell을 셸 도구로 사용합니다. WSL 설정에는 Git for Windows가 필요하지 않습니다.72 [Git for Windows](https://git-scm.com/downloads/win)는 Claude Code가 Bash 도구를 사용할 수 있도록 기본 Windows에서 권장됩니다. Git for Windows가 설치되지 않은 경우 Claude Code는 대신 PowerShell을 셸 도구로 사용합니다. WSL 설정에는 Git for Windows가 필요하지 않습니다.

71 73

204 206

205Claude Code는 Pro, Max, Team, Enterprise 또는 Console 계정이 필요합니다. 무료 claude.ai 플랜에는 Claude Code 액세스가 포함되지 않습니다. [Amazon Bedrock](/docs/ko/amazon-bedrock), [Google Cloud의 Agent Platform](/docs/ko/google-vertex-ai) 또는 [Microsoft Foundry](/docs/ko/microsoft-foundry)와 같은 타사 API 제공자와 함께 Claude Code를 사용할 수도 있습니다.207Claude Code는 Pro, Max, Team, Enterprise 또는 Console 계정이 필요합니다. 무료 claude.ai 플랜에는 Claude Code 액세스가 포함되지 않습니다. [Amazon Bedrock](/docs/ko/amazon-bedrock), [Google Cloud의 Agent Platform](/docs/ko/google-vertex-ai) 또는 [Microsoft Foundry](/docs/ko/microsoft-foundry)와 같은 타사 API 제공자와 함께 Claude Code를 사용할 수도 있습니다.

206 208

207설치 후 `claude`를 실행하고 브라우저 프롬프트를 따라 로그인하세요. `ANTHROPIC_API_KEY` 환경 변수가 설정된 경우, Claude Code는 브라우저를 열지 않고 키를 승인하도록 한 번 프롬프트합니다. 모든 계정 유형 및 팀 설정 옵션은 [인증](/docs/ko/authentication)을 참조하세요.209설치 후 `claude`를 실행하고 브라우저 프롬프트를 따라 로그인하세요. `ANTHROPIC_API_KEY` 환경 변수가 설정되어 있고 Claude Code가 해당 키를 사용할지 물을 때 키를 승인하면, Claude Code는 로그인 프롬프트를 건너뜁니다. 모든 계정 유형 및 팀 설정 옵션은 [인증](/docs/ko/authentication)을 참조하세요.

208 210

209<h2 id="update-claude-code">211<h2 id="update-claude-code">

210 Claude Code 업데이트212 Claude Code 업데이트

skills.md +7 −2

Details

237 237

238Cowork 또는 클라우드 세션에서 Claude Code는 claude.ai 계정에 대해 활성화된 스킬을 로드하며 [Cowork 및 클라우드 세션에서 스킬](#skills-in-cowork-and-cloud-sessions)은 해당 세션이 어떤 스킬을 얻는지 선택하는 방법을 설명합니다.238Cowork 또는 클라우드 세션에서 Claude Code는 claude.ai 계정에 대해 활성화된 스킬을 로드하며 [Cowork 및 클라우드 세션에서 스킬](#skills-in-cowork-and-cloud-sessions)은 해당 세션이 어떤 스킬을 얻는지 선택하는 방법을 설명합니다.

239 239

240터미널에서 Claude Code는 claude.ai 계정으로 로그인한 세션에서 해당 스킬을 동기화합니다. 세션이 시작되면 Claude Code는 계정의 스킬을 백그라운드에서 `~/.claude/skills/synced/`로 다운로드한 다음 세션이 실행되는 동안 약 10분마다 claude.ai에서 변경 사항을 확인합니다. 확인 결과 스킬이 claude.ai에서 추가, 편집 또는 비활성화되었음을 발견하면 Claude Code는 재시작 없이 실행 중인 세션에서 이를 추가, 업데이트 또는 제거합니다. 터미널 세션에서의 동기화에는 Claude Code v2.1.273 이상이 필요합니다.240터미널에서 Claude Code는 claude.ai 계정으로 로그인한 세션에서 해당 스킬을 동기화합니다. 세션이 시작되면 Claude Code는 계정의 스킬을 백그라운드에서 `~/.claude/skills/synced/`로 다운로드한 다음 세션이 실행되는 동안 claude.ai에서 변경 사항을 확인합니다. 확인 결과 스킬이 claude.ai에서 추가, 편집 또는 비활성화되었음을 발견하면 Claude Code는 재시작 없이 실행 중인 세션에서 이를 추가, 업데이트 또는 제거합니다. 터미널 세션에서의 동기화에는 Claude Code v2.1.273 이상이 필요합니다.

241 241

242동기화는 스킬을 호출할 때만 스킬의 다운로드를 기다리기 때문에 시작을 지연시키지 않습니다. 짧은 [비대화형](/docs/ko/headless) 실행은 새로 추가된 스킬이 다운로드되기 전에 완료될 수 있으며, 이 경우 나중 세션이 이를 다운로드합니다. 비대화형 실행이 스킬을 다운로드하고 프롬프트에 답하기 전에 목록을 기다리도록 하려면 [`CLAUDE_CODE_SYNC_SKILLS`](/docs/ko/env-vars#variables)를 `1`로 설정하세요.242세션이 유휴 상태인 동안에는 확인 빈도가 줄어듭니다:

243

244* **사용자나 Claude가 세션에서 작업하는 동안**: 약 10분마다 확인합니다.

245* **세션이 유휴 상태인 동안**: 약 40분마다 확인합니다. 세션에 다시 입력하면 마지막 확인이 10분 이상 전인 경우 Claude Code가 몇 분 이내에 확인합니다.

246

247동기화는 스킬을 호출할 때만 스킬의 다운로드를 기다리기 때문에 시작을 지연시키지 않습니다. 짧은 [비대화형](/docs/ko/headless) 실행은 새로 추가된 스킬이 다운로드되기 전에 완료될 수 있으며, 이 경우 나중 세션이 이를 다운로드합니다. 비대화형 실행이 스킬을 다운로드하고 프롬프트에 답하기 전에 목록을 기다리도록 하려면 [`CLAUDE_CODE_SYNC_SKILLS`](/docs/ko/env-vars#variables)를 `1`로 설정하세요. v2.1.273 이전에는 터미널 세션이 이 변수를 설정한 `-p` 실행에서만 스킬을 다운로드했습니다.

243 248

244Claude Code는 claude.ai 계정으로 로그인하고 [Anthropic에서 기능 플래그를 가져오는](/docs/ko/env-vars#features-that-need-feature-flag-fetching) 세션에서만 동기화합니다. 이러한 세션에서는 동기화하지 않습니다:249Claude Code는 claude.ai 계정으로 로그인하고 [Anthropic에서 기능 플래그를 가져오는](/docs/ko/env-vars#features-that-need-feature-flag-fetching) 세션에서만 동기화합니다. 이러한 세션에서는 동기화하지 않습니다:

245 250

sub-agents.md +4 −4

Details

310 310

311| 필드 | 필수 | 설명 |311| 필드 | 필수 | 설명 |

312| :- | :- | :- |312| :- | :- | :- |

313| `name` | 예 | `code-reviewer` 또는 `reviewer-v2`와 같은 고유 식별자. [Hooks](/docs/ko/hooks#subagentstart)는 이 값을 `agent_type`으로 받습니다. 파일 이름이 일치할 필요는 없습니다. 이름은 `:`를 포함할 수 없습니다. `:`는 `my-plugin:reviewer`와 같은 [플러그인 범위 식별자](/docs/ko/plugins/overview)에 예약되어 있습니다. Claude Code는 이름을 포함하는 파일을 로드하지 않고 디버그 로그에 오류를 기록합니다. v2.1.218 이전에는 이러한 이름이 허용되었습니다 |313| `name` | 예 | `code-reviewer` 또는 `reviewer-v2`와 같은 최대 256자의 고유 식별자. [훅](/docs/ko/hooks#subagentstart)은 이 값을 `agent_type`으로 받습니다. 파일 이름이 일치할 필요는 없습니다. 이름은 `:`를 포함할 수 없습니다. `:`는 `my-plugin:reviewer`와 같은 [플러그인 범위 식별자](/docs/ko/plugins/overview)에 예약되어 있습니다 |

314| `description` | 예 | Claude가 이 서브에이전트에 위임해야 할 때 |314| `description` | 예 | Claude가 이 서브에이전트에 위임해야 할 때 |

315| `tools` | 아니오 | 서브에이전트가 사용할 수 있는 [도구](#available-tools). `Read, Grep, Bash`와 같은 쉼표로 구분된 문자열 또는 YAML 목록입니다. 생략하면 서브에이전트가 사용 가능한 모든 도구를 상속합니다. 목록의 항목이 도구로 확인되지 않으면, 서브에이전트는 일반적으로 항목을 이름 지정하는 오류로 [시작에 실패](/docs/ko/errors#agent-would-be-spawned-with-zero-tools)합니다. 스킬을 컨텍스트에 미리 로드하려면 여기에 `Skill`을 나열하는 대신 `skills` 필드를 사용하세요 |315| `tools` | 아니오 | 서브에이전트가 사용할 수 있는 [도구](#available-tools). `Read, Grep, Bash`와 같은 쉼표로 구분된 문자열 또는 YAML 목록입니다. 생략하면 서브에이전트가 사용 가능한 모든 도구를 상속합니다. 목록의 항목이 도구로 확인되지 않으면, 서브에이전트는 일반적으로 항목을 이름 지정하는 오류로 [시작에 실패](/docs/ko/errors#agent-would-be-spawned-with-zero-tools)합니다. 스킬을 컨텍스트에 미리 로드하려면 여기에 `Skill`을 나열하는 대신 `skills` 필드를 사용하세요 |

316| `disallowedTools` | 아니오 | 거부할 도구. 상속되거나 지정된 목록에서 제거됩니다. `tools`와 동일한 형식입니다. `Bash(git push *)`와 같은 지정자가 있는 항목은 여전히 [전체 도구를 제거합니다](#available-tools) |316| `disallowedTools` | 아니오 | 거부할 도구. 상속되거나 지정된 목록에서 제거됩니다. `tools`와 동일한 형식입니다. `Bash(git push *)`와 같은 지정자가 있는 항목은 여전히 [전체 도구를 제거합니다](#available-tools) |

348 348

349* **`name` 없음**: Claude Code는 파일을 에이전트 옆에 보관된 문서로 취급합니다.349* **`name` 없음**: Claude Code는 파일을 에이전트 옆에 보관된 문서로 취급합니다.

350* **파일의 첫 번째 줄이 아닌 여는 `---`**: Claude Code는 파일을 프론트매터가 없는 것으로 읽고 문서로 취급합니다.350* **파일의 첫 번째 줄이 아닌 여는 `---`**: Claude Code는 파일을 프론트매터가 없는 것으로 읽고 문서로 취급합니다.

351* **`-`로 시작하거나 `:`를 포함하는 `name`**: Claude Code는 파일을 건너뛰고 디버그 로그에 오류를 씁니다. 위의 `name` 행을 참조하세요.351* **`-`로 시작하거나, `:`를 포함하거나, 256자보다 긴 `name`**: Claude Code는 파일을 건너뛰고 디버그 로그에 오류를 기록합니다.

352* **`name`이지만 `description` 없음**: Claude Code는 파일을 건너뛰고 이유를 디버그 로그에 씁니다.352* **`name`이지만 `description` 없음**: Claude Code는 파일을 건너뛰고 이유를 디버그 로그에 씁니다.

353* **파싱되지 않는 YAML**: Claude Code는 파일에서 필드를 읽지 않고, 건너뛰고, 파싱 오류를 디버그 로그에 씁니다.353* **파싱되지 않는 YAML**: Claude Code는 파일에서 필드를 읽지 않고, 건너뛰고, 파싱 오류를 디버그 로그에 씁니다.

354 354

1164 1164

1165* 서브에이전트가 완료되면 Claude는 에이전트 ID를 받습니다.1165* 서브에이전트가 완료되면 Claude는 에이전트 ID를 받습니다.

1166* 기본 제공 Explore 및 Plan 에이전트는 일회성이며 에이전트 ID를 반환하지 않으므로 Claude는 재개할 수 없습니다. 작업을 계속해야 할 때 `general-purpose` 또는 사용자 정의 서브에이전트를 사용합니다.1166* 기본 제공 Explore 및 Plan 에이전트는 일회성이며 에이전트 ID를 반환하지 않으므로 Claude는 재개할 수 없습니다. 작업을 계속해야 할 때 `general-purpose` 또는 사용자 정의 서브에이전트를 사용합니다.

1167* 서브에이전트가 [`maxTurns`](#supported-frontmatter-fields) 제한에서 중지되면 Claude Code는 반환된 출력을 부분으로 표시합니다. 에이전트 ID를 반환하는 서브에이전트의 경우 Claude Code는 또한 Claude가 중단한 위치에서 계속하도록 서브에이전트에 메시지를 보낼 수 있음을 결과에 기록합니다.1167* 서브에이전트가 [`maxTurns`](#supported-frontmatter-fields) 제한에서 중지되면 Claude Code는 반환된 출력을 부분으로 표시하며, Claude는 서브에이전트를 재개하여 작업을 계속할 수 있습니다.

1168 1168

1169Claude는 에이전트의 ID 또는 이름을 `to` 필드로 하여 `SendMessage` 도구를 사용하여 재개합니다. `SendMessage`는 [에이전트 팀](/docs/ko/agent-teams)이 활성화되어야 하지 않습니다. `shutdown_request` 및 `plan_approval_response`와 같은 구조화된 팀 프로토콜 메시지만 필요합니다. 서브에이전트 및 팀원 외에도 교차 세션 메시징이 활성화된 세션에서 Claude는 동일한 도구를 사용하여 [다른 Claude Code 세션](/docs/ko/cross-session-messaging)에 메시지를 보낼 수 있으며 이 컴퓨터 또는 [그 이상](/docs/ko/cross-session-messaging#message-sessions-on-other-machines)에 있습니다.1169Claude는 에이전트의 ID 또는 이름을 `to` 필드로 하여 `SendMessage` 도구를 사용하여 재개합니다. `SendMessage`는 [에이전트 팀](/docs/ko/agent-teams)이 활성화되어야 하지 않습니다. `shutdown_request` 및 `plan_approval_response`와 같은 구조화된 팀 프로토콜 메시지만 필요합니다. 서브에이전트 및 팀원 외에도 교차 세션 메시징이 활성화된 세션에서 Claude는 동일한 도구를 사용하여 [다른 Claude Code 세션](/docs/ko/cross-session-messaging)에 메시지를 보낼 수 있으며 이 컴퓨터 또는 [그 이상](/docs/ko/cross-session-messaging#message-sessions-on-other-machines)에 있습니다.

1170 1170

1279| 권한 | 프롬프트가 터미널에 표시됨 | [Background에서 실행 중일 때 프롬프트가 주 세션에 표시됨](#run-subagents-in-foreground-or-background) |1279| 권한 | 프롬프트가 터미널에 표시됨 | [Background에서 실행 중일 때 프롬프트가 주 세션에 표시됨](#run-subagents-in-foreground-or-background) |

1281 1281

1282포크의 시스템 프롬프트 및 도구 정의가 부모와 동일하기 때문에 첫 번째 요청은 부모의 [프롬프트 캐시](/docs/ko/prompt-caching#subagents-and-the-cache)를 재사용합니다. 이렇게 하면 동일한 컨텍스트가 필요한 작업에 대해 새로운 subagent를 생성하는 것보다 포크가 더 저렴합니다.1282포크의 시스템 프롬프트 및 도구 정의가 부모와 동일하기 때문에 첫 번째 요청은 부모의 [프롬프트 캐시](/docs/ko/prompt-caching#subagents-and-the-cache)를 재사용합니다. 이렇게 하면 동일한 컨텍스트가 필요한 작업에 대해 새로운 서브에이전트를 생성하는 것보다 포크가 더 저렴합니다.

1283 1283

1284Claude가 Agent 도구를 통해 포크를 생성할 때 `isolation: "worktree"`를 전달하여 포크의 파일 편집이 체크아웃 대신 별도의 git worktree에 기록되도록 할 수 있습니다. 포크는 추가 포크를 생성할 수 없습니다.1284Claude가 Agent 도구를 통해 포크를 생성할 때 `isolation: "worktree"`를 전달하여 포크의 파일 편집이 체크아웃 대신 별도의 git worktree에 기록되도록 할 수 있습니다. 포크는 추가 포크를 생성할 수 없습니다.

1285 1285

vs-code.md +21 −6

Details

40 40

41확장 프로그램은 Devin Desktop 또는 Kiro와 같은 다른 VS Code 포크에도 설치됩니다. 편집기의 확장 프로그램 보기에서 "Claude Code"를 검색하거나 [Open VSX 레지스트리](https://open-vsx.org/extension/Anthropic/claude-code)에서 설치합니다. 편집기에서 확장 프로그램을 설치할 수 없는 경우 [CLI](/docs/ko/quickstart)를 설치하고 통합 터미널에서 `claude`를 실행합니다. CLI는 모든 터미널에서 작동합니다.41확장 프로그램은 Devin Desktop 또는 Kiro와 같은 다른 VS Code 포크에도 설치됩니다. 편집기의 확장 프로그램 보기에서 "Claude Code"를 검색하거나 [Open VSX 레지스트리](https://open-vsx.org/extension/Anthropic/claude-code)에서 설치합니다. 편집기에서 확장 프로그램을 설치할 수 없는 경우 [CLI](/docs/ko/quickstart)를 설치하고 통합 터미널에서 `claude`를 실행합니다. CLI는 모든 터미널에서 작동합니다.

42 42

43dev 컨테이너 내에서 Claude Code를 실행하려면 [개발 컨테이너](/docs/ko/devcontainer)를 참조하세요.

43<Note>설치 후 확장 프로그램이 나타나지 않으면 VS Code를 다시 시작하거나 명령 팔레트에서 "Developer: Reload Window"를 실행합니다.</Note>45<Note>설치 후 확장 프로그램이 나타나지 않으면 VS Code를 다시 시작하거나 명령 팔레트에서 "Developer: Reload Window"를 실행합니다.</Note>

44 46

45<h2 id="get-started">47<h2 id="get-started">

606| `environmentVariables` | `[]` | Claude 프로세스에 대한 환경 변수를 설정합니다. 공유 구성의 경우 Claude Code 설정을 대신 사용합니다. [`CLAUDE_CONFIG_DIR`](/docs/ko/env-vars) 항목은 값이 절대 경로인 경우에만 적용됩니다. 확장 프로그램은 `~`를 확장하지 않으며 상대 경로 값은 무시합니다. |608| `environmentVariables` | `[]` | Claude 프로세스에 대한 환경 변수를 설정합니다. 공유 구성의 경우 Claude Code 설정을 대신 사용합니다. [`CLAUDE_CONFIG_DIR`](/docs/ko/env-vars) 항목은 값이 절대 경로인 경우에만 적용됩니다. 확장 프로그램은 `~`를 확장하지 않으며 상대 경로 값은 무시합니다. |

609| `claudeProcessWrapper` | - | Claude 프로세스를 실행하는 데 사용되는 실행 파일입니다. 번들된 바이너리 경로는 존재할 때 인수로 전달됩니다. 확장 프로그램 빌드가 플랫폼에 포함되지 않은 경우 별도로 설치된 `claude` 바이너리로 설정합니다. 래핑된 설정에서는 `initialPermissionMode`를 설정하거나 이전 대화에서 Manual, Edit automatically 또는 Auto를 선택하지 않는 한 대화가 Manual 모드에서 시작됩니다. 확장 프로그램이 설정 및 기본 제공 기본값 단계를 건너뛰기 때문입니다. [권한 모드 전환](/docs/ko/permission-modes#switch-permission-modes)을 참조하세요. 활성화 시 "Unsupported platform" 오류는 플랫폼에 번들된 바이너리가 없음을 의미합니다. [어떤 플랫폼에 미리 빌드된 바이너리가 있는지](/docs/ko/troubleshoot-install#native-binary-not-found-after-npm-install) 참조하세요. |611| `claudeProcessWrapper` | - | Claude 프로세스를 실행하는 데 사용되는 실행 파일입니다. 번들된 바이너리 경로는 존재할 때 인수로 전달됩니다. 확장 프로그램 빌드에 해당 플랫폼용 바이너리가 포함되어 있지 않은 경우 별도로 설치된 `claude` 바이너리로 설정합니다. |

610 612

611<h2 id="use-a-screen-reader">613<h2 id="use-a-screen-reader">

612 화면 읽기 프로그램 사용614 화면 읽기 프로그램 사용

781 783

782사용자의 코드는 비공개로 유지됩니다. Claude Code는 코드를 처리하여 지원을 제공하지만 모델 학습에 사용하지 않습니다. 데이터 처리 및 로깅 거부 방법에 대한 자세한 내용은 [데이터 및 개인정보 보호](/docs/ko/data-usage)를 참조하십시오.784사용자의 코드는 비공개로 유지됩니다. Claude Code는 코드를 처리하여 지원을 제공하지만 모델 학습에 사용하지 않습니다. 데이터 처리 및 로깅 거부 방법에 대한 자세한 내용은 [데이터 및 개인정보 보호](/docs/ko/data-usage)를 참조하십시오.

783 785

784자동 편집 권한이 활성화되면 Claude Code는 VS Code가 자동으로 실행할 수 있는 VS Code 구성 파일(예: `settings.json` 또는 `tasks.json`)을 수정할 수 있습니다. 신뢰할 수 없는 코드로 작업할 때 위험을 줄이려면:786자동 편집 권한이 활성화되면 Claude Code는 VS Code가 자동으로 실행할 수 있는 VS Code 설정 파일(예: `settings.json` 또는 `tasks.json`)을 수정할 수 있습니다. 신뢰할 수 없는 코드로 작업할 때 위험을 줄이려면:

785 787

786* 신뢰할 수 없는 작업 공간에 대해 [VS Code 제한 모드](https://code.visualstudio.com/docs/editor/workspace-trust#_restricted-mode)를 활성화하십시오788* 신뢰할 수 없는 워크스페이스에 대해 [VS Code 제한 모드](https://code.visualstudio.com/docs/editor/workspace-trust#_restricted-mode)를 활성화하십시오

787* 자동 편집 또는 자동 편집 대신 수동 모드를 사용하십시오789* 편집에는 Edit automatically 또는 Auto 대신 Manual 모드를 사용하십시오

788* 변경 사항을 수락하기 전에 신중하게 검토하십시오790* 변경 사항을 수락하기 전에 신중하게 검토하십시오

789 791

790<h3 id="the-built-in-ide-mcp-server">792<h3 id="the-built-in-ide-mcp-server">

805 807

806**전송 및 인증.** 서버는 10000–65535 범위의 임의 포트에서 `127.0.0.1`에 바인딩되며 포트는 구성할 수 없습니다. 전송은 암호화되지 않은 `ws://`입니다. 소켓이 루프백 전용이므로 트래픽을 캡처할 수 있는 모든 프로세스는 잠금 파일에서 토큰을 읽을 수도 있으므로 TLS는 보호를 추가하지 않습니다. 각 확장 프로그램 활성화는 새로운 임의 인증 토큰을 생성하고 `~/.claude/ide/<port>.lock`의 잠금 파일에 기록하며 CLI는 이를 `X-Claude-Code-Ide-Authorization` 헤더로 제시하여 연결해야 합니다. 잠금 파일은 `0700` 디렉터리에서 `0600` 권한을 가지므로 VS Code를 실행하는 사용자만 읽을 수 있습니다. `CLAUDE_CONFIG_DIR`이 설정되면 잠금 파일은 대신 `$CLAUDE_CONFIG_DIR/ide/`에 기록됩니다.808**전송 및 인증.** 서버는 10000–65535 범위의 임의 포트에서 `127.0.0.1`에 바인딩되며 포트는 구성할 수 없습니다. 전송은 암호화되지 않은 `ws://`입니다. 소켓이 루프백 전용이므로 트래픽을 캡처할 수 있는 모든 프로세스는 잠금 파일에서 토큰을 읽을 수도 있으므로 TLS는 보호를 추가하지 않습니다. 각 확장 프로그램 활성화는 새로운 임의 인증 토큰을 생성하고 `~/.claude/ide/<port>.lock`의 잠금 파일에 기록하며 CLI는 이를 `X-Claude-Code-Ide-Authorization` 헤더로 제시하여 연결해야 합니다. 잠금 파일은 `0700` 디렉터리에서 `0600` 권한을 가지므로 VS Code를 실행하는 사용자만 읽을 수 있습니다. `CLAUDE_CONFIG_DIR`이 설정되면 잠금 파일은 대신 `$CLAUDE_CONFIG_DIR/ide/`에 기록됩니다.

807 809

808**모델에 노출된 도구.** 서버는 약 12개의 도구를 호스팅하지만 모델에는 2개만 표시됩니다. 나머지는 CLI가 자체 UI(diff 열기, 선택 항목 읽기, 파일 저장)에 사용하는 내부 RPC이며 도구 목록이 Claude에 도달하기 전에 필터링됩니다.810**모델에 노출된 도구.** 서버는 약 12개의 도구를 호스팅하지만 모델에는 2개만 표시됩니다. 나머지는 CLI가 자체 UI(diff 열기, 선택 항목 읽기, 파일 저장 등)에 사용하는 내부 RPC입니다. 이들은 도구 목록이 Claude에 도달하기 전에 필터링됩니다.

809 811

810| 도구 이름(훅에서 보이는 대로) | 기능 | 읽기 전용 |812| 도구 이름(훅에서 보이는 대로) | 기능 | 읽기 전용 |

811| - | - | - |813| - | - | - |

831 833

832`Read` 거부 규칙은 두 도구 중 어느 것에도 적용되지 않으므로, 예시처럼 [거부 규칙](/docs/ko/permissions#mcp)을 사용하여 이름으로 차단하십시오.834`Read` 거부 규칙은 두 도구 중 어느 것에도 적용되지 않으므로, 예시처럼 [거부 규칙](/docs/ko/permissions#mcp)을 사용하여 이름으로 차단하십시오.

833 835

834**Jupyter 실행은 항상 먼저 묻습니다.** `mcp__ide__executeCode`는 아무것도 자동으로 실행할 수 없습니다. 각 호출 시 코드는 활성 노트북의 끝에 새 셀로 삽입되고 VS Code는 이를 보기로 스크롤하며 기본 Quick Pick에서 **실행** 또는 **취소**를 요청합니다. 취소하거나 `Esc`로 선택기를 닫으면 Claude에 오류가 반환되고 아무것도 실행되지 않습니다. 이 도구는 활성 노트북이 없을 때, Jupyter 확장 프로그램(`ms-toolsai.jupyter`)이 설치되지 않았을 때 또는 커널이 Python이 아닐 때 완전히 거부합니다.836**Jupyter 실행은 항상 먼저 묻습니다.** `mcp__ide__executeCode`는 아무것도 자동으로 실행할 수 없습니다. 각 호출 시 코드는 활성 노트북의 끝에 새 셀로 삽입되고 VS Code는 이를 보기로 스크롤하며 기본 Quick Pick에서 **Execute** 또는 **Cancel**을 선택하도록 묻습니다. 취소하거나 `Esc`로 선택기를 닫으면 Claude에 오류가 반환되고 아무것도 실행되지 않습니다. 이 도구는 활성 노트북이 없을 때, Jupyter 확장 프로그램(`ms-toolsai.jupyter`)이 설치되지 않았을 때 또는 커널이 Python이 아닐 때 완전히 거부합니다.

835 837

836<Note>838<Note>

837 Quick Pick 확인은 `PreToolUse` 훅과 별개입니다. `mcp__ide__executeCode`에 대한 허용 목록 항목을 사용하면 Claude가 셀 실행을 *제안*할 수 있습니다. VS Code 내의 Quick Pick은 실제로 *실행*할 수 있게 해주는 것입니다.839 Quick Pick 확인은 `PreToolUse` 훅과 별개입니다. `mcp__ide__executeCode`에 대한 허용 목록 항목을 사용하면 Claude가 셀 실행을 *제안*할 수 있습니다. VS Code 내의 Quick Pick은 실제로 *실행*할 수 있게 해주는 것입니다.

843 일반적인 문제 해결845 일반적인 문제 해결

844</h2>846</h2>

845 847

848로그인, 네트워크, 실행 오류는 설치 문제 해결 페이지와 오류 참조 페이지에 각각 별도의 항목으로 정리되어 있습니다. 표에서 표시된 내용을 찾은 다음 링크를 따라가세요.

849

850| 표시되는 내용 | 참고할 곳 |

851| - | - |

852| 로그인 후 `API Error: 403 Request not allowed` 표시 | [로그인 후 403 Forbidden](/docs/ko/troubleshoot-install#403-forbidden-after-login) |

853| 이미 로그인했는데 다시 로그인하라는 요청을 받음 | [로그인되지 않았거나 토큰이 만료됨](/docs/ko/troubleshoot-install#not-logged-in-or-token-expired) |

854| 클라우드 공급자 자격 증명이 터미널에서는 작동하지만 확장 프로그램에서는 작동하지 않음 | [Bedrock, Agent Platform 또는 Foundry 자격 증명이 로드되지 않음](/docs/ko/troubleshoot-install#bedrock-agent-platform-or-foundry-credentials-not-loading) |

855| `SSL certificate verification failed` 또는 `Self-signed certificate detected` | [SSL 인증서 오류](/docs/ko/errors#ssl-certificate-errors) |

856| `Claude Code process exited with code 1` 또는 다른 코드 | [Claude Code process exited with code N](/docs/ko/errors#claude-code-process-exited-with-code-n) |

857| `Could not locate the Claude CLI on PATH` | [Could not locate the Claude CLI on PATH](/docs/ko/errors#could-not-locate-the-claude-cli-on-path) |

858| `The connection to Claude Code ended before this message completed` | [The connection to Claude Code ended before this message completed](/docs/ko/errors#the-connection-to-claude-code-ended-before-this-message-completed) |

859| VS Code의 통합 터미널에서 `claude`를 찾을 수 없음 | [VS Code에서 CLI 실행](#run-cli-in-vs-code) |

860

846<h3 id="extension-won’t-install">861<h3 id="extension-won’t-install">

847 확장 프로그램이 설치되지 않음862 확장 프로그램이 설치되지 않음

848</h3>863</h3>

web-quickstart.md +2 −2

Details

50| **로컬 구성 사용** | 아니오, 저장소만 | 예 | 예 |50| **로컬 구성 사용** | 아니오, 저장소만 | 예 | 예 |

51| **GitHub 필요** | 예, 또는 `--cloud`를 통해 [로컬 저장소 번들](/docs/ko/claude-code-on-the-web#send-local-repositories-without-github) | 아니오 | 아니오 |51| **GitHub 필요** | 예, 또는 `--cloud`를 통해 [로컬 저장소 번들](/docs/ko/claude-code-on-the-web#send-local-repositories-without-github) | 아니오 | 아니오 |

52| **연결 해제 시 계속 실행** | 예 | 아니오 | 머신에서 세션이 열려 있는 동안 |52| **연결 해제 시 계속 실행** | 예 | 아니오 | 머신에서 세션이 열려 있는 동안 |

55 55

56로컬 세션을 설정하려면 [터미널 빠른 시작](/docs/ko/quickstart), [Desktop 앱](/docs/ko/desktop), 또는 [Remote Control](/docs/ko/remote-control) 문서를 참조하십시오.56로컬 세션을 설정하려면 [터미널 빠른 시작](/docs/ko/quickstart), [Desktop 앱](/docs/ko/desktop), 또는 [Remote Control](/docs/ko/remote-control) 문서를 참조하십시오.

150 </Step>150 </Step>

151 151

152 <Step title="권한 모드 선택">152 <Step title="권한 모드 선택">

153 입력 옆의 모드 드롭다운은 세션이 실행될 모드를 표시합니다:153 [권한 모드 컨트롤](/docs/ko/permission-modes#switch-permission-modes)은 세션이 실행될 권한 모드를 표시합니다:

154 154

155 * **Auto**: 분류기가 사용자에게 묻는 대신 Claude의 작업을 검토합니다. 조직에서 자동 모드를 허용하고 선택한 모델이 이를 지원할 때 나타납니다155 * **Auto**: 분류기가 사용자에게 묻는 대신 Claude의 작업을 검토합니다. 조직에서 자동 모드를 허용하고 선택한 모델이 이를 지원할 때 나타납니다

156 * **Accept edits**: Claude는 승인을 기다리지 않고 변경 사항을 만들고 브랜치를 푸시합니다156 * **Accept edits**: Claude는 승인을 기다리지 않고 변경 사항을 만들고 브랜치를 푸시합니다

workflows.md +6 −1

Details

522 522

523전체 조직을 위해 워크플로우를 끄려면 [관리 설정](/docs/ko/server-managed-settings)에서 `"disableWorkflows": true`를 설정하거나 [Claude Code 관리 설정](https://claude.ai/admin-settings/claude-code) 페이지의 토글을 사용합니다.523전체 조직을 위해 워크플로우를 끄려면 [관리 설정](/docs/ko/server-managed-settings)에서 `"disableWorkflows": true`를 설정하거나 [Claude Code 관리 설정](https://claude.ai/admin-settings/claude-code) 페이지의 토글을 사용합니다.

524 524

525워크플로우가 비활성화되면 번들된 워크플로우 명령과 `/workflow-authoring` 스킬을 사용할 수 없으며, `ultracode` 키워드는 더 이상 실행을 트리거하지 않으며, **Ultracode** 토글은 `/effort`에서 제거됩니다. 이미 진행 중인 실행은 계속 진행됩니다.525워크플로가 비활성화되면:

526

527* `/workflows`, 워크플로 명령, `/workflow-authoring` 스킬을 사용할 수 없습니다

528* `ultracode` 키워드가 더 이상 실행을 트리거하지 않으며, **Ultracode** 토글이 `/effort`에서 제거됩니다

529

530이미 진행 중인 실행은 계속 진행됩니다.

526 531

527워크플로우를 끄면 [ultracode](#let-claude-decide-with-ultracode)도 사용할 수 없게 됩니다. ultracode만 제외하는 관리 설정은 없습니다: [사용 가능한](/docs/ko/model-config#when-ultracode-is-available) 곳이면 사용자는 `/effort ultracode`로 켤 수 있습니다. [노력 상한](/docs/ko/model-config#organization-effort-limits)은 ultracode가 켜진 세션이 실행하는 노력 수준을 낮추지만 ultracode를 끄지는 않습니다.532워크플로우를 끄면 [ultracode](#let-claude-decide-with-ultracode)도 사용할 수 없게 됩니다. ultracode만 제외하는 관리 설정은 없습니다: [사용 가능한](/docs/ko/model-config#when-ultracode-is-available) 곳이면 사용자는 `/effort ultracode`로 켤 수 있습니다. [노력 상한](/docs/ko/model-config#organization-effort-limits)은 ultracode가 켜진 세션이 실행하는 노력 수준을 낮추지만 ultracode를 끄지는 않습니다.

528 533

worktrees.md +3 −1

Details

6 6

7> git worktree에서 병렬 Claude Code 세션을 격리하여 변경 사항이 충돌하지 않도록 합니다. `--worktree` 플래그, 서브에이전트 격리, `.worktreeinclude`, 정리 및 비git VCS 훅을 다룹니다.7> git worktree에서 병렬 Claude Code 세션을 격리하여 변경 사항이 충돌하지 않도록 합니다. `--worktree` 플래그, 서브에이전트 격리, `.worktreeinclude`, 정리 및 비git VCS 훅을 다룹니다.

8 8

9[git worktree](https://git-scm.com/docs/git-worktree)는 자체 파일과 브랜치를 가진 별도의 작업 디렉토리이며, 메인 체크아웃과 동일한 저장소 히스토리 및 원격을 공유합니다. 각 Claude Code 세션을 자체 worktree에서 실행하면 한 세션의 편집이 다른 세션의 파일을 건드리지 않으므로, 한 세션이 기능을 구축하는 동안 두 번째 세션이 버그를 수정할 수 있습니다.9[git worktree](https://git-scm.com/docs/git-worktree)는 자체 파일과 브랜치를 가진 별도의 작업 디렉터리이며, 메인 체크아웃과 동일한 저장소 히스토리 및 원격을 공유합니다. 각 Claude Code 세션을 자체 worktree에서 실행하면 세션마다 편집할 파일의 별도 사본이 주어지므로, 한 세션이 기능을 구축하는 동안 두 번째 세션이 버그를 수정할 수 있습니다.

10 10

11<Note>11<Note>

12 Worktree는 git 저장소가 필요합니다. 다른 버전 관리 시스템의 경우 [훅을 구성하여 git 로직을 대체](#non-git-version-control)합니다. [데스크톱 앱](/docs/ko/desktop#work-in-parallel-with-sessions)에서는 세션을 시작할 때 **worktree** 옵션을 선택하여 자체 worktree를 제공합니다.12 Worktree는 git 저장소가 필요합니다. 다른 버전 관리 시스템의 경우 [훅을 구성하여 git 로직을 대체](#non-git-version-control)합니다. [데스크톱 앱](/docs/ko/desktop#work-in-parallel-with-sessions)에서는 세션을 시작할 때 **worktree** 옵션을 선택하여 자체 worktree를 제공합니다.

104* **Git 리다이렉트**: Claude Code는 git을 메인 체크아웃으로 리다이렉트하는 Bash 또는 Monitor 명령을 차단합니다. 리다이렉트는 `git -C`, `--git-dir`, `GIT_DIR` 또는 `GIT_WORK_TREE` 변수, 또는 git을 실행하기 전에 메인 체크아웃으로 `cd`를 통해 올 수 있습니다.104* **Git 리다이렉트**: Claude Code는 git을 메인 체크아웃으로 리다이렉트하는 Bash 또는 Monitor 명령을 차단합니다. 리다이렉트는 `git -C`, `--git-dir`, `GIT_DIR` 또는 `GIT_WORK_TREE` 변수, 또는 git을 실행하기 전에 메인 체크아웃으로 `cd`를 통해 올 수 있습니다.

105* **명령 형태**: Claude Code는 명령 텍스트에서 명령이 실행하는 모든 git이 worktree 내부에 머물러 있는지 확인할 수 없을 때 Bash 또는 Monitor 명령을 차단합니다. 예를 들어 명령 이름이 런타임에 계산되거나 구문을 파싱할 수 없거나 `${!name}` 또는 `${ command; }`와 같은 확장이 텍스트에서 명시하지 않은 명령을 실행할 수 있을 때 발생합니다. Claude Code는 Claude에게 거부된 명령을 다시 작성하는 방법을 알려줍니다. 예를 들어 이를 일반 별도 명령으로 분할합니다. 이 확인을 끌 수 없습니다.105* **명령 형태**: Claude Code는 명령 텍스트에서 명령이 실행하는 모든 git이 worktree 내부에 머물러 있는지 확인할 수 없을 때 Bash 또는 Monitor 명령을 차단합니다. 예를 들어 명령 이름이 런타임에 계산되거나 구문을 파싱할 수 없거나 `${!name}` 또는 `${ command; }`와 같은 확장이 텍스트에서 명시하지 않은 명령을 실행할 수 있을 때 발생합니다. Claude Code는 Claude에게 거부된 명령을 다시 작성하는 방법을 알려줍니다. 예를 들어 이를 일반 별도 명령으로 분할합니다. 이 확인을 끌 수 없습니다.

106 106

107이러한 확인은 편집이 대상으로 하는 경로, 명령이 실행되는 디렉터리, 명령의 텍스트를 읽습니다. 어느 확인도 셸 명령이 어떤 파일에 쓰는지는 추적하지 않으므로, `cp`나 셸 리다이렉트처럼 메인 체크아웃에서 git을 실행하지 않고 메인 체크아웃에 쓰는 명령은 이 확인으로 거부되지 않습니다. Claude Code는 이러한 명령을 다른 셸 명령과 동일하게 취급하므로, 명령이 실행되는지 또는 확인을 요청하는지는 [권한 모드](/docs/ko/permission-modes)와 규칙에 따라 달라집니다.

108

107확인은 Claude Code를 실행한 저장소에 적용됩니다. 또한 연결된 worktree가 연결된 메인 체크아웃도 포함합니다. PowerShell 명령의 경우 Claude Code는 작업 디렉토리 확인만 적용합니다.109확인은 Claude Code를 실행한 저장소에 적용됩니다. 또한 연결된 worktree가 연결된 메인 체크아웃도 포함합니다. PowerShell 명령의 경우 Claude Code는 작업 디렉토리 확인만 적용합니다.

108 110

109Claude는 각 거부를 worktree의 이름을 지정하고 진행 방법을 설명하는 도구 오류로 봅니다. 거부된 명령의 경우 [거부 메시지의 의미와 이를 해결하는 방법](/docs/ko/errors#command-blocked-by-the-worktree-isolation-checks)을 참조하세요.111Claude는 각 거부를 worktree의 이름을 지정하고 진행 방법을 설명하는 도구 오류로 봅니다. 거부된 명령의 경우 [거부 메시지의 의미와 이를 해결하는 방법](/docs/ko/errors#command-blocked-by-the-worktree-isolation-checks)을 참조하세요.

Documentation 2026-10-06 23:59 UTC to 2026-10-07 21:59 UTC