Documentation 2026-11-02 23:57 UTC to 2026-11-03 23:58 UTC

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

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

81 81 

82Claude Desktop의 [`allowedWorkspaceFolders`](https://claude.com/docs/third-party/claude-desktop/configuration#allowedworkspacefolders) 목록이 있는 기기에서 WSL 세션이 시작되면 `~` 항목은 배포판 내부의 홈 디렉터리를 의미합니다.

83 

82WSL 2 유틸리티 VM 내부의 프로세스는 Windows 측 엔드포인트 감지 센서에 표시되지 않습니다. 배포판 내 프로세스 및 파일 활동을 관찰하려면 엔드포인트 감지 공급업체의 WSL 지침에서 배포판 내에서 실행할 수 있는 Linux 센서와 필요한 제외 사항을 확인하세요. Claude Code의 [OpenTelemetry 도구 실행 텔레메트리](https://code.claude.com/docs/ko/monitoring-usage.md)는 WSL 및 네이티브 세션에 대해 동일하게 내보내집니다.84WSL 2 유틸리티 VM 내부의 프로세스는 Windows 측 엔드포인트 감지 센서에 표시되지 않습니다. 배포판 내 프로세스 및 파일 활동을 관찰하려면 엔드포인트 감지 공급업체의 WSL 지침에서 배포판 내에서 실행할 수 있는 Linux 센서와 필요한 제외 사항을 확인하세요. Claude Code의 [OpenTelemetry 도구 실행 텔레메트리](https://code.claude.com/docs/ko/monitoring-usage.md)는 WSL 및 네이티브 세션에 대해 동일하게 내보내집니다.

83 85 

84## 적용할 항목 결정86## 적용할 항목 결정

127 129 

128### 연결된 GitHub 계정130### 연결된 GitHub 계정

129 131 

130Team 및 Enterprise 플랜에서 [**조직 설정 > Git 공급자**](https://claude.ai/admin-settings/source-control)의 GitHub 섹션에는 [Claude GitHub App](https://github.com/apps/claude)을 통해 Claude 조직에 연결된 GitHub 조직과 개인 계정이 나열됩니다. Claude Code, [Claude Tag](https://claude.com/docs/claude-tag/admins/configure-github) 및 Claude Security가 이 목록을 공유합니다. 이 페이지를 열려면 Claude 조직에서 관리자 역할이 필요합니다.132Team 및 Enterprise 플랜에서 [**조직 설정 > Git 공급자**](https://claude.ai/admin-settings/source-control)의 GitHub 섹션에는 [Claude GitHub App](https://github.com/apps/claude)을 통해 Claude 조직에 연결된 GitHub 조직과 개인 계정이 나열됩니다. Claude Code, [Claude Tag](https://claude.com/docs/claude-tag/admins/configure-github) 및 Claude Security가 이 목록을 공유합니다. 이 페이지를 열려면 Claude 조직에서 [Owner 역할](https://code.claude.com/docs/ko/server-managed-settings.md#access-control)이 필요합니다. Admin 역할로는 열 수 없습니다.

131 133 

132관리자 또는 구성원이 계정을 연결할 수 있습니다:134Git 공급자 페이지에서 계정을 연결하거나 GitHub를 Claude에 연결하여 계정을 연결할 수 있습니다:

133 135 

134* **관리자 연결**: 관리자가 해당 섹션에서 **Connect**를 클릭하거나, 계정이 연결된 후에는 **Add organization**을 클릭하고 GitHub 조직에 Claude GitHub App을 설치합니다. 이 방법으로 조직을 연결하려면 GitHub 조직의 소유자이면서 동시에 Claude 조직의 관리자인 사람이 필요합니다.136* **Owner 연결**: Owner가 해당 섹션에서 **Connect**를 클릭하거나, 계정이 연결된 후에는 **Add organization**을 클릭하고 GitHub 조직에 Claude GitHub App을 설치합니다. 이 방법으로 조직을 연결하려면 GitHub 조직도 소유한 Claude 조직의 Owner가 필요합니다.

135* **구성원 연결**: 구성원이 GitHub 계정을 Claude에 연결하면(예: [클라우드 세션 설정](https://code.claude.com/docs/ko/web-quickstart.md#connect-github) 중), Claude는 해당 구성원이 소유하고 Claude GitHub App이 이미 설치된 GitHub 계정을 연결합니다. 여기에는 구성원의 개인 계정과 구성원이 소유한 GitHub 조직이 포함될 수 있습니다.137* **구성원 연결**: 구성원이 GitHub 계정을 Claude에 연결하면(예: [클라우드 세션 설정](https://code.claude.com/docs/ko/web-quickstart.md#connect-github) 중), Claude는 해당 구성원이 소유하고 Claude GitHub App이 이미 설치된 GitHub 계정을 연결합니다. 여기에는 구성원의 개인 계정과 구성원이 소유한 GitHub 조직이 포함될 수 있습니다.

136 138 

137**Not linked**로 표시된 행은 본인의 GitHub 로그인에서 비롯된 것입니다. GitHub에서 볼 수 있으며 Claude GitHub App이 설치된 계정입니다.139**Not linked**로 표시된 행은 본인의 GitHub 로그인에서 비롯된 것입니다. GitHub에서 볼 수 있으며 Claude GitHub App이 설치된 계정입니다.

222>222>

223> `effort`는 각 응답 내에서 지연 시간 및 토큰 비용과 추론 깊이를 맞바꿉니다. [확장 사고](https://platform.claude.com/docs/en/build-with-claude/extended-thinking)는 출력에 `thinking` 블록을 생성하는 별도의 기능이며, [Python](https://code.claude.com/docs/ko/agent-sdk/python.md#thinkingconfig) 또는 [TypeScript](https://code.claude.com/docs/ko/agent-sdk/typescript.md#thinkingconfig)의 `ThinkingConfig`에 있는 `display` 필드가 해당 텍스트를 받을지 여부를 제어합니다. 두 기능은 서로 독립적입니다. 확장 사고를 켠 상태에서 `effort: "low"`를 설정할 수도 있고, 확장 사고를 끈 상태에서 `effort: "max"`를 설정할 수도 있습니다.223> `effort`는 각 응답 내에서 지연 시간 및 토큰 비용과 추론 깊이를 맞바꿉니다. [확장 사고](https://platform.claude.com/docs/en/build-with-claude/extended-thinking)는 출력에 `thinking` 블록을 생성하는 별도의 기능이며, [Python](https://code.claude.com/docs/ko/agent-sdk/python.md#thinkingconfig) 또는 [TypeScript](https://code.claude.com/docs/ko/agent-sdk/typescript.md#thinkingconfig)의 `ThinkingConfig`에 있는 `display` 필드가 해당 텍스트를 받을지 여부를 제어합니다. 두 기능은 서로 독립적입니다. 확장 사고를 켠 상태에서 `effort: "low"`를 설정할 수도 있고, 확장 사고를 끈 상태에서 `effort: "max"`를 설정할 수도 있습니다.

224 224 

225간단하고 범위가 명확한 작업(파일 목록 조회나 단일 grep 실행 등)을 수행하는 에이전트에는 낮은 effort를 사용해 비용과 지연 시간을 줄이세요. 세션 전체에 적용하려면 최상위 `query()` 옵션에서 `effort`를 설정하고, 서브에이전트별로 세션 수준을 재정의하려면 [`AgentDefinition`](https://code.claude.com/docs/ko/agent-sdk/subagents#agentdefinition-configuration)의 `effort` 필드를 사용하세요.225간단하고 범위가 명확한 작업(파일 목록 조회나 단일 grep 실행 등)을 수행하는 에이전트에는 낮은 effort를 사용해 비용과 지연 시간을 줄이세요. [세션](https://code.claude.com/docs/ko/sub-agents.md#choose-an-effort-level) 전체에 적용하려면 최상위 `query()` 옵션에서 `effort`를 설정하고, 서브에이전트별로 세션 수준을 재정의하려면 [`AgentDefinition`](https://code.claude.com/docs/ko/agent-sdk/subagents#agentdefinition-configuration)의 `effort` 필드를 사용하세요.

226 226 

227### 권한 모드227### 권한 모드

228 228 

224| `matcher` | `string` | `undefined` | [설정 파일의 매처 규칙](https://code.claude.com/docs/ko/hooks.md#matcher-patterns)을 따르는 이벤트의 필터 필드와 일치하는 패턴입니다. 도구 훅의 경우 도구 이름입니다. 기본 제공 도구에는 `Bash`, `Read`, `Write`, `Edit`, `Glob`, `Grep`, `WebFetch`, `Agent` 등이 포함됩니다([도구 입력 타입](https://code.claude.com/docs/ko/agent-sdk/typescript.md#tool-input-types)에서 전체 목록 참조). MCP 도구는 `mcp__<server>__<action>` 패턴을 사용합니다. 여기서 `<server>`는 `mcpServers` 구성에서 사용하는 키이며, [도구 명명 규칙](https://code.claude.com/docs/ko/agent-sdk/mcp.md#tool-naming-convention)에 설명된 대로 표기합니다. |224| `matcher` | `string` | `undefined` | [설정 파일의 매처 규칙](https://code.claude.com/docs/ko/hooks.md#matcher-patterns)을 따르는 이벤트의 필터 필드와 일치하는 패턴입니다. 도구 훅의 경우 도구 이름입니다. 기본 제공 도구에는 `Bash`, `Read`, `Write`, `Edit`, `Glob`, `Grep`, `WebFetch`, `Agent` 등이 포함됩니다([도구 입력 타입](https://code.claude.com/docs/ko/agent-sdk/typescript.md#tool-input-types)에서 전체 목록 참조). MCP 도구는 `mcp__<server>__<action>` 패턴을 사용합니다. 여기서 `<server>`는 `mcpServers` 구성에서 사용하는 키이며, [도구 명명 규칙](https://code.claude.com/docs/ko/agent-sdk/mcp.md#tool-naming-convention)에 설명된 대로 표기합니다. |

225| `hooks` | `HookCallback[]` | - | 필수입니다. 패턴이 일치할 때 실행할 콜백 함수의 배열 |225| `hooks` | `HookCallback[]` | - | 필수입니다. 패턴이 일치할 때 실행할 콜백 함수의 배열 |

226| `timeout` | `number` | `undefined` | 초 단위의 타임아웃입니다. 생략하면 Claude Code는 [이벤트의 기본 타임아웃](#hook-timeout)을 적용합니다. SDK 콜백은 `command` 훅 기본값을 따릅니다. |226| `timeout` | `number` | `undefined` | 초 단위의 타임아웃입니다. 생략하면 Claude Code는 [이벤트의 기본 타임아웃](#hook-timeout)을 적용합니다. SDK 콜백은 `command` 훅 기본값을 따릅니다. |

227| `onFailure` | `"continue" \| "block"` | `undefined` | 콜백이 실패했을 때의 동작입니다. [콜백이 실패하면 작업을 차단](#block-the-action-when-a-callback-fails)하려면 `"block"`으로 설정합니다. Python에서는 `on_failure`를 사용합니다. |

227 228 

228가능할 때마다 `matcher` 패턴을 사용하여 특정 도구를 대상으로 합니다. `'Bash'` 매처는 Bash 명령에만 실행되지만 패턴을 생략하면 콜백이 이벤트의 모든 발생에 대해 실행됩니다.229가능할 때마다 `matcher` 패턴을 사용하여 특정 도구를 대상으로 합니다. `'Bash'` 매처는 Bash 명령에만 실행되지만 패턴을 생략하면 콜백이 이벤트의 모든 발생에 대해 실행됩니다.

229 230 

283>284>

284> 비동기 출력은 에이전트가 이미 진행했으므로 차단, 수정 또는 작업에 컨텍스트를 주입할 수 없습니다. 로깅, 메트릭 또는 알림 같은 부작용에만 사용합니다.285> 비동기 출력은 에이전트가 이미 진행했으므로 차단, 수정 또는 작업에 컨텍스트를 주입할 수 없습니다. 로깅, 메트릭 또는 알림 같은 부작용에만 사용합니다.

285 286 

287### 콜백이 실패하면 작업 차단

288 

289대부분의 이벤트에서 콜백이 예외를 발생시키거나 유효성 검사에 실패하는 출력을 반환하면 작업은 그대로 진행되고, 앱은 `tag`가 `hook_callback_failed`인 [`SDKInformationalMessage`](https://code.claude.com/docs/ko/agent-sdk/typescript#sdkinformationalmessage) 경고를 받습니다. 이 경우 충돌한 `PreToolUse` 가드는 도구 호출이 일반 권한 흐름에 도달하도록 허용하게 됩니다. `return`이 없는 경로처럼 아무것도 반환하지 않는 콜백도 실패로 간주됩니다. Python에서는 `SystemMessage.data`에서 `tag`를 읽습니다.

290 

291대신 작업을 차단하려면 matcher에 TypeScript에서는 `onFailure: "block"`, Python에서는 `on_failure="block"`을 설정합니다. TypeScript Agent SDK v0.3.317 이상 또는 Python Agent SDK v0.2.177 이상이 필요합니다. 이 예제는 Python의 `check_policy` 또는 TypeScript의 `checkPolicy`가 실패하면 Bash 호출을 차단합니다:

292 

293```python Python theme={null}

294options = ClaudeAgentOptions(

295 hooks={

296 "PreToolUse": [

297 HookMatcher(matcher="Bash", hooks=[check_policy], on_failure="block")

298 ]

299 }

300)

301```

302 

303```typescript TypeScript theme={null}

304import type { Options } from "@anthropic-ai/claude-agent-sdk";

305 

306const options: Options = {

307 hooks: {

308 PreToolUse: [{ matcher: "Bash", hooks: [checkPolicy], onFailure: "block" }]

309 }

310};

311```

312 

313테스트하려면 콜백이 오류를 발생시키도록 만든 다음 Claude에게 Bash 명령을 실행하도록 요청합니다. 도구 결과에는 `failed; blocking because onFailure is "block"`이 포함되며, Claude는 오류 텍스트를 보지 않습니다.

314 

315콜백이 판단할 것이 없을 때는 `{}`를 반환합니다. `"block"`이 설정된 경우 `return`이 없는 경로는 작업을 차단합니다. 자체 오류를 잡아서 `{}`를 반환하는 콜백은 실패한 것이 아니므로, 가드에서는 오류가 전파되도록 두세요.

316 

317#### 다르게 동작하는 이벤트

318 

319다음 이벤트는 `"block"`이 설정되어 있어도 항상 차단하지는 않습니다:

320 

321* **`Stop`, `SubagentStop`, `TaskCompleted`, `TeammateIdle`**: 이 이벤트는 옵션을 무시하므로 작업이 그대로 진행됩니다.

322* **`PermissionRequest`**: 차단은 `canUseTool` 콜백이 응답하기 전에 도착한 경우에만 유효합니다.

323* **`PostToolUse`**: 도구가 이미 실행되었으므로 Claude는 실패를 피드백으로 받습니다.

324 

325타임아웃을 초과한 콜백은 [훅 타임아웃](#hook-timeout)을 따릅니다. `"block"`이 설정된 경우 타임아웃은 `PreCompact`, `Elicitation`, `WorktreeCreate`도 차단합니다.

326 

327#### `onFailure`의 시작 오류

328 

329`"block"`이 설정된 경우 옵션을 적용할 수 없으면 쿼리는 시작 시 실패하며 프롬프트를 보내지 않습니다:

330 

331* **Claude Code가 옵션을 지원하지 않는 경우**: 오류에 `does not honor`가 포함됩니다. Claude Code를 업데이트하거나 옵션을 제거하세요.

332* **세션이 이미 실행 중이었고 훅을 등록하지 않은 경우**: 오류에 `did not register your hooks`가 포함됩니다. 새 세션을 시작하세요.

333 

286## 예제334## 예제

287 335 

288이 섹션의 여러 예제는 콜백 함수만 보여 줍니다. 예제를 실행하려면 [훅 구성](#configure-hooks)에 나온 것처럼 옵션의 `hooks` 필드에서 해당 이벤트 아래에 콜백을 등록합니다.336이 섹션의 여러 예제는 콜백 함수만 보여 줍니다. 예제를 실행하려면 [훅 구성](#configure-hooks)에 나온 것처럼 옵션의 `hooks` 필드에서 해당 이벤트 아래에 콜백을 등록합니다.

779* `Stop` 및 `SubagentStop`: 타임아웃된 콜백은 결정을 반환하지 않은 것으로 계산됩니다. 에이전트 또는 서브에이전트는 해당 콜백이 이를 허용한 것처럼 중지되며, 이벤트의 다른 훅의 결정은 여전히 적용됩니다. Claude Code v2.1.273 이전에는 타임아웃된 `Stop` 또는 `SubagentStop` 콜백이 실패한 훅 실행으로 계산되었으며, Claude Code는 이벤트의 다른 훅의 결정을 버렸습니다.827* `Stop` 및 `SubagentStop`: 타임아웃된 콜백은 결정을 반환하지 않은 것으로 계산됩니다. 에이전트 또는 서브에이전트는 해당 콜백이 이를 허용한 것처럼 중지되며, 이벤트의 다른 훅의 결정은 여전히 적용됩니다. Claude Code v2.1.273 이전에는 타임아웃된 `Stop` 또는 `SubagentStop` 콜백이 실패한 훅 실행으로 계산되었으며, Claude Code는 이벤트의 다른 훅의 결정을 버렸습니다.

780* `SessionStart`: 타임아웃된 콜백은 출력을 반환하지 않은 것으로 계산되며, 세션은 다른 `SessionStart` 훅의 출력으로 계속됩니다.828* `SessionStart`: 타임아웃된 콜백은 출력을 반환하지 않은 것으로 계산되며, 세션은 다른 `SessionStart` 훅의 출력으로 계속됩니다.

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

782* `Notification`, `PreCompact`, `PostModelSwitch` 같은 다른 이벤트: Claude Code는 실패를 기록하고 계속됩니다.830* `Notification`, `PreCompact`, `PostModelSwitch` 같은 다른 이벤트: Claude Code는 실패를 기록하고 계속됩니다. [`onFailure: "block"`](#block-the-action-when-a-callback-fails)을 사용하면 `PreCompact`, `Elicitation` 또는 `WorktreeCreate`의 타임아웃이 해당 작업을 차단합니다.

783 831 

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

785 833 

2161 None # Timeout in seconds. When omitted, the per-event default applies:2161 None # Timeout in seconds. When omitted, the per-event default applies:

2162 # 600 for most events, 30 for UserPromptSubmit2162 # 600 for most events, 30 for UserPromptSubmit

2163 )2163 )

2164 on_failure: Literal["continue", "block"] | None = (

2165 None # "block" blocks the action when a callback fails

2166 )

2164```2167```

2165 2168 

2169`on_failure`가 적용되는 범위를 판단하려면 [콜백이 실패할 때 작업 차단](https://code.claude.com/docs/ko/agent-sdk/hooks.md#block-the-action-when-a-callback-fails)을 참조하십시오.

2170 

2166### `HookInput`2171### `HookInput`

2167 2172 

2168모든 hook 입력 타입의 합집합 타입입니다. 실제 타입은 `hook_event_name` 필드에 따라 달라집니다.2173모든 hook 입력 타입의 합집합 타입입니다. 실제 타입은 `hook_event_name` 필드에 따라 달라집니다.

2437 2442 

2438#### `HookSpecificOutput`2443#### `HookSpecificOutput`

2439 2444 

2440이벤트 특정 출력 타입의 판별된 합집합입니다. `hookEventName` 필드가 어느 필드가 유효한지 결정합니다. hook 이벤트별 사용 가능한 필드에 대한 전체 세부 정보는 [hooks로 실행 제어](https://code.claude.com/docs/ko/agent-sdk/hooks.md#outputs)를 참조하십시오.2445이벤트별 `TypedDict` 출력 타입의 판별된 합집합입니다. `hookEventName` 필드가 어느 필드가 유효한지 결정합니다. hook 이벤트별 사용 가능한 필드에 대한 전체 세부 정보는 [hooks로 실행 제어](https://code.claude.com/docs/ko/agent-sdk/hooks.md#outputs)를 참조하십시오.

2441 2446 

2442```python theme={null}2447```python theme={null}

2443class PreToolUseHookSpecificOutput(TypedDict):2448class PreToolUseHookSpecificOutput(TypedDict):

2183 level: "info" | "notice" | "suggestion" | "warning";2183 level: "info" | "notice" | "suggestion" | "warning";

2184 tool_use_id?: string;2184 tool_use_id?: string;

2185 prevent_continuation?: boolean;2185 prevent_continuation?: boolean;

2186 tag?: string;

2186 uuid: UUID;2187 uuid: UUID;

2187 session_id: string;2188 session_id: string;

2188};2189};

2558 matcher?: string;2559 matcher?: string;

2559 hooks: HookCallback[];2560 hooks: HookCallback[];

2560 timeout?: number; // 이 매처의 모든 훅에 대한 타임아웃 (초)2561 timeout?: number; // 이 매처의 모든 훅에 대한 타임아웃 (초)

2562 onFailure?: "continue" | "block"; // "block"은 콜백이 실패하면 작업을 차단합니다

2561}2563}

2562```2564```

2563 2565 

2566`onFailure`가 적용되는 범위를 결정하려면 [콜백이 실패할 때 작업 차단](https://code.claude.com/docs/ko/agent-sdk/hooks.md#block-the-action-when-a-callback-fails)을 참조하세요.

2567 

2564### `HookInput`2568### `HookInput`

2565 2569 

2566모든 훅 입력 타입의 합집합 타입입니다.2570모든 훅 입력 타입의 합집합 타입입니다.

158* **`opus`와 같은 패밀리 별칭**: Anthropic API 및 AWS의 Claude Platform에서 Claude Code는 팀원을 허용 목록이 허용하는 해당 패밀리의 최신 버전에서 실행합니다. 제공자별 모델 ID가 있는 제공자에서 [대체가 작동하지 않는](https://code.claude.com/docs/ko/model-config.md#restrict-model-selection) 경우, 차단된 별칭은 다음 글머리 기호에 따라 다른 차단된 값처럼 폴백합니다.158* **`opus`와 같은 패밀리 별칭**: Anthropic API 및 AWS의 Claude Platform에서 Claude Code는 팀원을 허용 목록이 허용하는 해당 패밀리의 최신 버전에서 실행합니다. 제공자별 모델 ID가 있는 제공자에서 [대체가 작동하지 않는](https://code.claude.com/docs/ko/model-config.md#restrict-model-selection) 경우, 차단된 별칭은 다음 글머리 기호에 따라 다른 차단된 값처럼 폴백합니다.

159* **차단된 다른 값(제공자별 대체가 작동하지 않는 제공자의 패밀리 별칭 포함, 또는 패밀리에 허용된 버전이 없는 경우)**: Claude Code는 팀원을 리더의 모델에서 실행합니다. `CLAUDE_CODE_SUBAGENT_MODEL`을 설정한 경우, Claude Code는 이러한 동일한 규칙에 따라 먼저 해당 모델을 시도합니다.159* **차단된 다른 값(제공자별 대체가 작동하지 않는 제공자의 패밀리 별칭 포함, 또는 패밀리에 허용된 버전이 없는 경우)**: Claude Code는 팀원을 리더의 모델에서 실행합니다. `CLAUDE_CODE_SUBAGENT_MODEL`을 설정한 경우, Claude Code는 이러한 동일한 규칙에 따라 먼저 해당 모델을 시도합니다.

160 160 

161기본적으로 팀원들은 리더의 [effort 수준](https://code.claude.com/docs/ko/model-config.md#adjust-effort-level)을 상속합니다. 분할 창 모드에서는 v2.1.186부터 적용됩니다. 이전 버전은 리더의 세션 effort를 분할 창 팀원에게 전달하지 않았습니다.161기본적으로 리더의 모델을 사용하는 팀원은 리더의 [effort 수준](https://code.claude.com/docs/ko/model-config.md#adjust-effort-level)을 상속합니다. 분할 창 모드에서는 v2.1.186부터 적용됩니다. 이전 버전은 리더의 세션 effort를 분할 창 팀원에게 전달하지 않았습니다. 다른 모델을 사용하는 팀원의 경우 [서브에이전트 및 팀원의 effort 수준](https://code.claude.com/docs/ko/model-config.md#effort-level-of-subagents-and-teammates)을 참조합니다.

162 162 

163### 팀원이 구현하기 전에 계획하도록 하기163### 팀원이 구현하기 전에 계획하도록 하기

164 164 

165복잡하거나 위험한 작업의 경우, 팀원들이 구현하기 전에 계획하도록 할 수 있습니다. 리더가 [plan mode](https://code.claude.com/docs/ko/permission-modes.md#analyze-before-you-edit-with-plan-mode)에 있는 동안 Claude가 생성하는 팀원은 계획이 준비될 때까지 읽기 전용 plan mode에서 작동합니다. 먼저 리더를 plan mode로 전환한 후 팀원을 요청합니다:165복잡하거나 위험한 작업의 경우, 팀원들이 구현하기 전에 계획하도록 할 수 있습니다. 리더가 [플랜 모드](https://code.claude.com/docs/ko/permission-modes.md#analyze-before-you-edit-with-plan-mode)에 있는 동안 Claude가 생성하는 팀원도 계획이 준비될 때까지 플랜 모드에서 작동합니다. 먼저 리더를 플랜 모드로 전환한 후 팀원을 요청합니다:

166 166 

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

168Spawn an architect teammate to refactor the authentication module.168Spawn an architect teammate to refactor the authentication module.

169```169```

170 170 

171해당 팀원이 계획을 마치면, 리더에게 계획 승인 요청을 보냅니다. 팀원이 생성된 이후 해당 팀원의 권한 모드를 변경하지 않았다면, Claude Code는 리더의 검토 없이 요청이 도착하는 즉시 계획을 승인합니다. 팀원의 편집 및 명령은 여전히 [Permissions](#permissions)에 설명된 권한 프롬프트를 거칩니다. 승인되면, 팀원은 플랜 모드를 종료하고 구현을 시작합니다.171해당 팀원이 계획을 마치면, 리더에게 계획 승인 요청을 보냅니다. 팀원이 생성된 이후 해당 팀원의 권한 모드를 변경하지 않았다면, Claude Code는 리더의 검토 없이 요청이 도착하는 즉시 계획을 승인합니다. 승인되면, 팀원은 플랜 모드를 종료하고 구현을 시작합니다. Claude Code는 리더의 현재 [권한 모드](#permissions)를 팀원에게 전달하며, 리더의 모드가 플랜 모드인 경우에는 Manual을 전달합니다.

172 172 

173실행 중인 in-process 팀원의 세션을 보는 동안 [`Shift+Tab`](https://code.claude.com/docs/ko/permission-modes#switch-permission-modes)을 눌러 해당 팀원을 플랜 모드로 전환하면, Claude Code가 승인하는 대신 리더가 해당 실행의 계획을 검토합니다. 사용자에게는 승인을 요청하지 않으며, 리더가 계획을 승인하거나 수정을 위해 되돌려 보냅니다.173실행 중인 in-process 팀원의 세션을 보는 동안 [`Shift+Tab`](https://code.claude.com/docs/ko/permission-modes#switch-permission-modes)을 눌러 해당 팀원을 플랜 모드로 전환하면, Claude Code가 승인하는 대신 리더가 해당 실행의 계획을 검토합니다. 사용자에게는 승인을 요청하지 않으며, 리더가 계획을 승인하거나 수정을 위해 되돌려 보냅니다.

174 174 

288 288 

289### 권한289### 권한

290 290 

291팀원들은 리더의 권한 모드로 시작하며, [`dontAsk` 모드](https://code.claude.com/docs/ko/permission-modes#allow-only-pre-approved-tools-with-dontask-mode) 제외하고, 이는 상속하지 않습니다. 리더가 `--dangerously-skip-permissions`로 실행되면, 모든 팀원도 그렇게 합니다. 생성 후, 개별 팀원의 권한 모드를 변경할 수 있지만, 생성 시 팀원별 권한 모드를 설정할 수 없습니다.291실행 중인 팀원의 권한 모드를 순환하려면 [`Shift+Tab`](https://code.claude.com/docs/ko/permission-modes#switch-permission-modes)을 누릅니다. 단, 프로세스 내 팀원은 대신 리더의 모드로 실행될 수 있습니다. 분할 창 팀원의 경우 해당 창에서 누릅니다. [프로세스 내](#choose-a-display-mode) 팀원의 경우 [해당 세션을 보는 동안](#talk-to-teammates-directly) 누르며, 팀원은 다음 턴을 시작할 때 자신의 모드를 확인합니다.

292 

293> [!NOTE]

294>

295> [플랜 모드](#have-teammates-plan-before-implementing)가 아닌 프로세스 내 팀원은 리더가 [`acceptEdits`](https://code.claude.com/docs/ko/permission-modes#auto-approve-file-edits-with-acceptedits-mode), [`auto`](https://code.claude.com/docs/ko/permission-modes#eliminate-prompts-with-auto-mode) 또는 [`bypassPermissions`](https://code.claude.com/docs/ko/permission-modes#skip-all-checks-with-bypasspermissions-mode) 모드에 있는 동안 리더의 모드로 실행됩니다. 팀원을 Manual로 전환해도, 상태 표시줄에 Manual이 표시되더라도 이는 바뀌지 않습니다.

296>

297> 편집하기 전에 묻도록 하려면, 에이전트 패널의 `main` 행에서 Enter를 누르고 리더도 Manual 모드로 전환합니다. 그러면 리더도 묻게 되며, Manual 모드인 다른 모든 팀원도 마찬가지입니다.

298 

299생성 시 팀원별 권한 모드를 설정할 수 없습니다. 새 팀원은 `--dangerously-skip-permissions`가 켜는 `bypassPermissions` 모드를 포함하여 리더의 모드로 시작합니다. 리더가 [`dontAsk` 모드](https://code.claude.com/docs/ko/permission-modes#allow-only-pre-approved-tools-with-dontask-mode)에 있으면, 팀원은 대신 [Manual 모드](https://code.claude.com/docs/ko/permission-modes.md#available-modes)로 시작합니다.

292 300 

293[프로세스 내](#choose-a-display-mode) 팀원은 리더의 실시간 허용 및 거부 규칙에 따라 실행되므로, [`--disallowedTools`](https://code.claude.com/docs/ko/cli-reference#cli-flags), `--tools`, `--allowedTools`가 모두 적용됩니다. 분할 창 팀원의 경우 각 플래그를 확인합니다:301[프로세스 내](#choose-a-display-mode) 팀원은 리더의 실시간 허용 및 거부 규칙에 따라 실행되므로, [`--disallowedTools`](https://code.claude.com/docs/ko/cli-reference#cli-flags), `--tools`, `--allowedTools`가 모두 적용됩니다. 분할 창 팀원의 경우 각 플래그를 확인합니다:

294 302 

488* **중첩된 팀 없음**: 팀원들은 자신의 팀원을 생성할 수 없습니다. 리더만 팀을 관리할 수 있습니다.496* **중첩된 팀 없음**: 팀원들은 자신의 팀원을 생성할 수 없습니다. 리더만 팀을 관리할 수 있습니다.

489* **In-process 팀원의 백그라운드 서브에이전트 없음**: in-process 팀원의 자체 서브에이전트는 포그라운드에서 실행됩니다. 팀원의 백그라운드 작업은 리더의 프로세스보다 오래 지속될 수 없기 때문입니다. Claude Code는 팀원이 정의에 `background: true`가 설정된 서브에이전트를 생성할 때 오류를 반환합니다. 팀원의 `run_in_background: true` 요청도 실패하며, 오류가 발생하거나 포그라운드에서 자동으로 실행됩니다. 주 대화에서 시작된 서브에이전트는 [백그라운드 기본값](https://code.claude.com/docs/ko/sub-agents.md#run-subagents-in-foreground-or-background)을 따릅니다.497* **In-process 팀원의 백그라운드 서브에이전트 없음**: in-process 팀원의 자체 서브에이전트는 포그라운드에서 실행됩니다. 팀원의 백그라운드 작업은 리더의 프로세스보다 오래 지속될 수 없기 때문입니다. Claude Code는 팀원이 정의에 `background: true`가 설정된 서브에이전트를 생성할 때 오류를 반환합니다. 팀원의 `run_in_background: true` 요청도 실패하며, 오류가 발생하거나 포그라운드에서 자동으로 실행됩니다. 주 대화에서 시작된 서브에이전트는 [백그라운드 기본값](https://code.claude.com/docs/ko/sub-agents.md#run-subagents-in-foreground-or-background)을 따릅니다.

490* **리더가 고정됨**: 주 세션은 수명 동안 리더입니다. 팀원을 리더로 승격하거나 리더십을 이전할 수 없습니다.498* **리더가 고정됨**: 주 세션은 수명 동안 리더입니다. 팀원을 리더로 승격하거나 리더십을 이전할 수 없습니다.

491* **생성 시 권한 설정**: 팀원들은 [권한](#permissions) 아래에 설명된 권한 모드로 시작합니다. 생성 후 개별 팀원의 권한 모드를 변경할 수 있지만, 생성 시 팀원별 권한 모드를 설정할 수 없습니다.499* **생성 시 팀원별 권한 모드 없음**: 팀원들은 [권한](#permissions) 아래에 설명된 권한 모드로 시작합니다.

492* **분할 창은 tmux 또는 iTerm2 필요**: 기본 in-process 모드는 모든 터미널에서 작동합니다. 분할 창 모드는 VS Code의 통합 터미널, Windows Terminal, Ghostty에서 지원되지 않습니다.500* **분할 창은 tmux 또는 iTerm2 필요**: 기본 in-process 모드는 모든 터미널에서 작동합니다. 분할 창 모드는 VS Code의 통합 터미널, Windows Terminal, Ghostty에서 지원되지 않습니다.

493 501 

494## 다음 단계502## 다음 단계

442 442 

443`/background` 또는 그 별칭 `/bg`를 실행하여 현재 대화를 백그라운드 세션으로 이동합니다. `/bg run the test suite and fix any failures`와 같은 프롬프트를 전달하면 먼저 지시사항을 하나 더 제공할 수 있습니다. `/bg`를 실행할 때 Claude가 응답 중이면, 응답은 백그라운드 세션에서 계속됩니다.443`/background` 또는 그 별칭 `/bg`를 실행하여 현재 대화를 백그라운드 세션으로 이동합니다. `/bg run the test suite and fix any failures`와 같은 프롬프트를 전달하면 먼저 지시사항을 하나 더 제공할 수 있습니다. `/bg`를 실행할 때 Claude가 응답 중이면, 응답은 백그라운드 세션에서 계속됩니다.

444 444 

445서브에이전트, 백그라운드 셸 명령, 워크플로, 또는 [모니터](https://code.claude.com/docs/ko/tools-reference.md#monitor-tool)와 같은 백그라운드 작업이 여전히 실행 중인 세션을 종료하면, 즉시 종료하는 대신 `Background work is running` 대화 상자가 표시됩니다. `/background`와 동일한 방식으로 세션을 백그라운드로 이동하고 셸로 돌아가려면 `Move to background and exit`를 선택합니다. 에이전트 뷰가 [꺼져 있으면](#turn-off-agent-view) 이 옵션은 표시되지 않습니다.445서브에이전트나 워크플로 같은 일부 종류의 백그라운드 작업이 실행 중일 때 세션을 종료하면, `Background work is running` 대화 상자가 해당 작업이 중지된다고 경고합니다. `/background`와 동일한 방식으로 세션을 백그라운드로 이동하고 셸로 돌아가려면 `Move to background and exit`를 선택합니다. 에이전트 뷰가 [꺼져 있으면](#turn-off-agent-view) 이 옵션은 표시되지 않습니다.

446 446 

447목록의 백그라운드 세션이 이미 대화의 이름을 가지고 있으면, Claude Code는 새 행의 이름에 `my-session (2)`와 같이 번호를 매기고 기존 행의 이름은 그대로 둡니다. 새 행의 이름을 바꾸려면 에이전트 뷰에서 선택하고 `Ctrl+R`을 누릅니다.447목록의 백그라운드 세션이 이미 대화의 이름을 가지고 있으면, Claude Code는 새 행의 이름에 `my-session (2)`와 같이 번호를 매기고 기존 행의 이름은 그대로 둡니다. 새 행의 이름을 바꾸려면 에이전트 뷰에서 선택하고 `Ctrl+R`을 누릅니다.

448 448 

315* [관리형 설정](https://code.claude.com/docs/ko/managed-settings.md)의 `env` 블록에 있는 핀315* [관리형 설정](https://code.claude.com/docs/ko/managed-settings.md)의 `env` 블록에 있는 핀

316* [애플리케이션 추론 프로필 ARN](#map-each-model-version-to-an-inference-profile)을 가리키는 핀(관리자가 관리하므로)316* [애플리케이션 추론 프로필 ARN](#map-each-model-version-to-an-inference-profile)을 가리키는 핀(관리자가 관리하므로)

317 317 

318관리형 설정의 핀에 대해 업데이트 확인 요청이 계속 표시되면 Claude Code를 v2.1.314 이상으로 업데이트합니다. v2.1.314 이전에는 수락한 후에도 관리형 핀이 그대로 적용되어, 다음 시작 시 확인 요청이 다시 표시되었습니다.

319 

318모델을 고정하지 않았으며 현재 기본값을 계정에서 사용할 수 없는 경우, Claude Code는 현재 세션에 대해 폴백하고 알림을 표시합니다. 먼저 기본 모델의 이전 버전을 시도하고, 기본값이 Opus 모델이며 사용 가능한 Opus 버전이 없을 때 기본 Sonnet 모델로 폴백합니다. 폴백은 유지되지 않습니다. Amazon Bedrock 계정에서 최신 모델을 활성화하거나 [버전을 고정](#4-pin-model-versions)하여 선택을 영구적으로 만듭니다.320모델을 고정하지 않았으며 현재 기본값을 계정에서 사용할 수 없는 경우, Claude Code는 현재 세션에 대해 폴백하고 알림을 표시합니다. 먼저 기본 모델의 이전 버전을 시도하고, 기본값이 Opus 모델이며 사용 가능한 Opus 버전이 없을 때 기본 Sonnet 모델로 폴백합니다. 폴백은 유지되지 않습니다. Amazon Bedrock 계정에서 최신 모델을 활성화하거나 [버전을 고정](#4-pin-model-versions)하여 선택을 영구적으로 만듭니다.

319 321 

322### 특정 모델로 세션 시작하기

323 

320특정 Sonnet 또는 Opus 버전에서 세션을 시작할 때(예: `--model`, `ANTHROPIC_MODEL` 또는 [`model` 설정](https://code.claude.com/docs/ko/settings-reference#model)을 사용하여), 해당 버전은 일치하는 `sonnet` 또는 `opus` 별칭에 대한 세션의 고정된 기본값으로 작동합니다. Claude Code는 모델이 대체하는 기본 제공 기본값에 대한 가용성 확인을 건너뛰고 구성한 모델에서 시작하며, 폴백 알림이 없습니다.324특정 Sonnet 또는 Opus 버전에서 세션을 시작할 때(예: `--model`, `ANTHROPIC_MODEL` 또는 [`model` 설정](https://code.claude.com/docs/ko/settings-reference#model)을 사용하여), 해당 버전은 일치하는 `sonnet` 또는 `opus` 별칭에 대한 세션의 고정된 기본값으로 작동합니다. Claude Code는 모델이 대체하는 기본 제공 기본값에 대한 가용성 확인을 건너뛰고 구성한 모델에서 시작하며, 폴백 알림이 없습니다.

321 325 

322다음은 세션을 시작할 때 핀으로 작동하지 않습니다.326다음은 세션을 시작할 때 핀으로 작동하지 않습니다.

324* `opus`와 같은 모델 별칭328* `opus`와 같은 모델 별칭

325* Claude Code가 인식하지 못하는 모델 ID(예: 애플리케이션 추론 프로필 ARN)329* Claude Code가 인식하지 못하는 모델 ID(예: 애플리케이션 추론 프로필 ARN)

326 330 

327이러한 확인에서 계정이 호출할 수 없는 모델을 찾으면, Claude Code는 이 머신에서 최대 하루 동안 거부를 기억하고, 그 시간 동안 기억된 모델을 건너뛰고 Amazon Bedrock에 다시 요청하지 않고 시작합니다. Claude Code는 마지막 확인 이후 10분이 경과하면 현재 기본 모델의 기억된 거부를 시작 시 다시 확인하므로, 관리자가 다시 활성화한 기본값이 돌아옵니다. 메모리를 끄려면 [`CLAUDE_CODE_SKIP_MODEL_ACCESS_MEMORY=1`](https://code.claude.com/docs/ko/env-vars)을 설정합니다.331### 기억된 모델 거부

332 

333시작 모델 확인에서 계정이 호출할 수 없는 모델을 찾으면, Claude Code는 이 머신에서 최대 하루 동안 거부를 기억할 수 있습니다. 마지막 확인 이후 10분이 경과하면 Claude Code는 현재 기본 모델의 기억된 거부를 시작 시 다시 확인합니다. 그러면 관리자가 다시 활성화한 기본값이 돌아옵니다. 메모리를 끄려면 [`CLAUDE_CODE_SKIP_MODEL_ACCESS_MEMORY=1`](https://code.claude.com/docs/ko/env-vars)을 설정합니다.

328 334 

329### 조직에서 모델 허용 목록을 강제하는 경우335### 조직에서 모델 허용 목록을 강제하는 경우

330 336 

458 464 

459## AWS Guardrails465## AWS Guardrails

460 466 

461[Amazon Bedrock Guardrails](https://docs.aws.amazon.com/bedrock/latest/userguide/guardrails.html)를 사용하면 Claude Code에 대한 콘텐츠 필터링을 구현할 수 있습니다. [Amazon Bedrock 콘솔](https://console.aws.amazon.com/bedrock/)에서 Guardrail을 만들고 버전을 게시한 다음 Guardrail 헤더를 [설정 파일](https://code.claude.com/docs/ko/settings.md)에 추가하십시오. 교차 지역 추론 프로필을 사용하는 경우 Guardrail에서 교차 지역 추론을 활성화하십시오.467[Amazon Bedrock Guardrails](https://docs.aws.amazon.com/bedrock/latest/userguide/guardrails.html)를 사용하면 Claude Code에 대한 콘텐츠 필터링을 구현할 수 있습니다. [Amazon Bedrock 콘솔](https://console.aws.amazon.com/bedrock/)에서 Guardrail을 만들고 버전을 게시하십시오. 교차 지역 추론 프로필을 사용하는 경우 Guardrail에서 교차 지역 추론을 활성화하십시오.

462 468 

463예제 구성:469[Claude 앱 게이트웨이](https://code.claude.com/docs/ko/claude-apps-gateway)를 통해 Guardrail을 적용하려면 [Amazon Bedrock guardrail 적용](https://code.claude.com/docs/ko/claude-apps-gateway-config.md#apply-an-amazon-bedrock-guardrail)을 따르십시오. Claude 앱 게이트웨이가 없는 경우 Guardrail 헤더를 [설정 파일](https://code.claude.com/docs/ko/settings.md)에 추가하십시오.

470 

471설정 파일 구성 예제:

464 472 

465```json theme={null}473```json theme={null}

466{474{

470}478}

471```479```

472 480 

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

474 

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

476 482 

477## Mantle 엔드포인트 사용483## Mantle 엔드포인트 사용

2512. `ANTHROPIC_AUTH_TOKEN` 환경 변수. `Authorization: Bearer` 헤더로 전송됩니다. Anthropic API 키가 아닌 베어러 토큰으로 인증하는 [LLM 게이트웨이 또는 프록시](https://code.claude.com/docs/ko/llm-gateway)를 통해 라우팅할 때 사용하세요.2512. `ANTHROPIC_AUTH_TOKEN` 환경 변수. `Authorization: Bearer` 헤더로 전송됩니다. Anthropic API 키가 아닌 베어러 토큰으로 인증하는 [LLM 게이트웨이 또는 프록시](https://code.claude.com/docs/ko/llm-gateway)를 통해 라우팅할 때 사용하세요.

2523. `ANTHROPIC_API_KEY` 환경 변수. `X-Api-Key` 헤더로 전송됩니다. [Claude Console](https://platform.claude.com)의 키를 사용하여 Anthropic API에 직접 액세스할 때 사용하세요. 대화형 모드에서는 키를 승인하거나 거부하도록 한 번 요청받으며, 선택이 기억됩니다. 나중에 변경하려면 `/config`에서 "Use custom API key" 토글을 사용하세요. 토글은 `ANTHROPIC_API_KEY`가 환경에 설정되어 있는 동안에만 나타납니다. 비대화형 모드(`-p`)에서는 키가 있을 때 항상 사용됩니다.2523. `ANTHROPIC_API_KEY` 환경 변수. `X-Api-Key` 헤더로 전송됩니다. [Claude Console](https://platform.claude.com)의 키를 사용하여 Anthropic API에 직접 액세스할 때 사용하세요. 대화형 모드에서는 키를 승인하거나 거부하도록 한 번 요청받으며, 선택이 기억됩니다. 나중에 변경하려면 `/config`에서 "Use custom API key" 토글을 사용하세요. 토글은 `ANTHROPIC_API_KEY`가 환경에 설정되어 있는 동안에만 나타납니다. 비대화형 모드(`-p`)에서는 키가 있을 때 항상 사용됩니다.

2534. [`apiKeyHelper`](https://code.claude.com/docs/ko/settings-reference#apikeyhelper) 스크립트 출력. 자격증명 모음에서 가져온 단기 토큰과 같은 동적 또는 회전 자격증명에 사용하세요.2534. [`apiKeyHelper`](https://code.claude.com/docs/ko/settings-reference#apikeyhelper) 스크립트 출력. 자격증명 모음에서 가져온 단기 토큰과 같은 동적 또는 회전 자격증명에 사용하세요.

2545. `CLAUDE_CODE_OAUTH_TOKEN` 환경 변수. [`claude setup-token`](#generate-a-long-lived-token)으로 생성된 장기 OAuth 토큰. 브라우저 로그인을 사용할 수 없는 CI 파이프라인 및 스크립트에 사용하세요. 변수가 설정된 동안 `/login`을 실행하면, Claude Code는 현재 세션을 새 로그인으로 전환하지만, 셸 프로필이나 [설정 파일](https://code.claude.com/docs/ko/settings.md)의 `env` 블록에서 제거할 때까지 모든 새 세션에서 변수를 다시 읽습니다.2545. `CLAUDE_CODE_OAUTH_TOKEN` 환경 변수. [`claude setup-token`](#generate-a-long-lived-token)으로 생성된 장기 OAuth 토큰. 브라우저 로그인을 사용할 수 없는 CI 파이프라인 및 스크립트에 사용하세요. 변수가 설정된 동안 `/login`을 실행하면, Claude Code는 현재 세션을 새 로그인으로 전환합니다. 새 세션에서도 해당 로그인을 유지하려면 셸 프로필과 사용자 설정과 같은 [변수를 설정할 수 있는 설정 파일](https://code.claude.com/docs/ko/settings-reference.md#variables-claude-code-ignores-in-env)에서 변수를 제거하세요.

2556. Anthropic 프로필 및 페더레이션 자격증명. `ant` CLI 및 Workload Identity Federation이 사용하는 자격증명입니다. `ant auth login`이 작성한 프로필은 `ANTHROPIC_PROFILE`에서 이름을 지정할 때만 여기에 순위가 매겨집니다. 그렇지 않으면 `/login` 아래에 순위가 매겨집니다. [Anthropic 프로필 및 페더레이션 자격증명](#anthropic-profiles-and-federation-credentials)을 참조하세요.2556. Anthropic 프로필 및 페더레이션 자격증명. `ant` CLI 및 Workload Identity Federation이 사용하는 자격증명입니다. `ant auth login`이 작성한 프로필은 `ANTHROPIC_PROFILE`에서 이름을 지정할 때만 여기에 순위가 매겨집니다. 그렇지 않으면 `/login` 아래에 순위가 매겨집니다. [Anthropic 프로필 및 페더레이션 자격증명](#anthropic-profiles-and-federation-credentials)을 참조하세요.

2567. `/login`의 구독 OAuth 자격 증명. 이는 Claude Pro, Max, Ultra, Team, Enterprise 사용자의 기본값입니다.2567. `/login`의 구독 OAuth 자격 증명. 이는 Claude Pro, Max, Ultra, Team, Enterprise 사용자의 기본값입니다.

257 257 

603>603>

604> `claude -p --worktree` 실행은 묻지 않고 종료되므로 직접 정리해야 합니다. `git worktree remove <path>`로 제거하고, 워크트리가 잠겨 있어 git이 거부하면 먼저 `git worktree unlock <path>`를 실행하십시오.604> `claude -p --worktree` 실행은 묻지 않고 종료되므로 직접 정리해야 합니다. `git worktree remove <path>`로 제거하고, 워크트리가 잠겨 있어 git이 거부하면 먼저 `git worktree unlock <path>`를 실행하십시오.

605 605 

606여러 파일에 걸친 하나의 큰 기계적 변경에는 [`/batch migrate every handler to the v2 response helpers`](https://code.claude.com/docs/ko/commands)가 작업을 5\~30개 단위로 나누고 계획을 보여 줍니다. 그런 다음 각 단위를 자체 워크트리에서 실행하고 각각에 대해 PR을 엽니다. 셸에서는 [`claude agents`](https://code.claude.com/docs/ko/agent-view)(아직 리서치 프리뷰)가 머신의 백그라운드에서 실행 중인 모든 것을 한 화면에서 보여 줍니다.606여러 파일에 걸친 하나의 큰 기계적 변경에는 [`/batch migrate every handler to the v2 response helpers`](https://code.claude.com/docs/ko/commands)가 작업을 5\~30개 단위로 나누고 계획을 보여 줍니다. 계획을 승인하면 각 단위가 자체 워크트리를 갖게 되며, PR을 열거나 진행 결과를 보고합니다. 셸에서는 [`claude agents`](https://code.claude.com/docs/ko/agent-view)(아직 리서치 프리뷰)가 머신의 백그라운드에서 실행 중인 모든 것을 한 화면에서 보여 줍니다.

607 607 

608두 번째 세션은 가장 쉽게 얻을 수 있는 독립적인 리뷰어이기도 합니다. 한 세션이 속도 제한기를 작성하고, 다른 세션은 작성 과정을 보지 않은 채 `@src/middleware/rateLimiter.ts`를 리뷰하며, 사용자가 그 결과를 첫 번째 세션에 붙여 넣습니다. `/code-review`와 같은 아이디어이며, 메시지를 사용자가 전달하는 것입니다.608두 번째 세션은 가장 쉽게 얻을 수 있는 독립적인 리뷰어이기도 합니다. 한 세션이 속도 제한기를 작성하고, 다른 세션은 작성 과정을 보지 않은 채 `@src/middleware/rateLimiter.ts`를 리뷰하며, 사용자가 그 결과를 첫 번째 세션에 붙여 넣습니다. `/code-review`와 같은 아이디어이며, 메시지를 사용자가 전달하는 것입니다.

609 609 

85| `--desktop` | [Claude Desktop 앱](https://code.claude.com/docs/ko/desktop.md)을 현재 디렉터리에서 열고 터미널에서 세션을 시작하지 않고 종료합니다. `--continue` 또는 `--resume`을 세션 ID와 함께 추가하여 [대신 Desktop에서 해당 세션을 열 수 있습니다](https://code.claude.com/docs/ko/desktop.md#coming-from-the-cli). 여기서 `--resume`은 세션 ID만 사용하며 이름이나 트랜스크립트 경로는 사용하지 않습니다. 프롬프트와 `--verbose` 및 `--debug` 플래그를 제외한 다른 플래그를 사용하지 않습니다. 앱이 세션을 시작하기 때문입니다. Claude 구독으로 로그인했을 때 macOS 및 x64 Windows에서 사용 가능합니다. Claude Code v2.1.285 이상이 필요합니다 | `claude --desktop` |85| `--desktop` | [Claude Desktop 앱](https://code.claude.com/docs/ko/desktop.md)을 현재 디렉터리에서 열고 터미널에서 세션을 시작하지 않고 종료합니다. `--continue` 또는 `--resume`을 세션 ID와 함께 추가하여 [대신 Desktop에서 해당 세션을 열 수 있습니다](https://code.claude.com/docs/ko/desktop.md#coming-from-the-cli). 여기서 `--resume`은 세션 ID만 사용하며 이름이나 트랜스크립트 경로는 사용하지 않습니다. 프롬프트와 `--verbose` 및 `--debug` 플래그를 제외한 다른 플래그를 사용하지 않습니다. 앱이 세션을 시작하기 때문입니다. Claude 구독으로 로그인했을 때 macOS 및 x64 Windows에서 사용 가능합니다. Claude Code v2.1.285 이상이 필요합니다 | `claude --desktop` |

86| `--disable-slash-commands` | 이 세션에 대해 모든 스킬 및 명령을 비활성화합니다 | `claude --disable-slash-commands` |86| `--disable-slash-commands` | 이 세션에 대해 모든 스킬 및 명령을 비활성화합니다 | `claude --disable-slash-commands` |

87| `--disallowedTools`, `--disallowed-tools` | 거부 규칙입니다. 베어 도구 이름은 Claude의 컨텍스트에서 일치하는 도구를 제거합니다: `"Edit"`는 Edit를 제거하고, `"*"`는 모든 도구를 제거하며, `"mcp__*"`는 모든 MCP 도구를 제거합니다. `Bash(rm *)`와 같은 범위 지정 규칙은 도구를 사용 가능하게 두고 [작성된 대로](https://code.claude.com/docs/ko/permissions.md#bash-rule-limits) 일치하는 호출만 거부합니다. [`EndConversation`](https://code.claude.com/docs/ko/tools-reference#endconversation-tool-behavior)을 이름 지은 규칙은 다른 도구가 남아 있는 동안 제거할 수 없습니다 | `"Bash(git log *)" "Bash(git diff *)" "Edit"` |87| `--disallowedTools`, `--disallowed-tools` | 거부 규칙입니다. 베어 도구 이름은 Claude의 컨텍스트에서 일치하는 도구를 제거합니다: `"Edit"`는 Edit를 제거하고, `"*"`는 모든 도구를 제거하며, `"mcp__*"`는 모든 MCP 도구를 제거합니다. `Bash(rm *)`와 같은 범위 지정 규칙은 도구를 사용 가능하게 두고 [작성된 대로](https://code.claude.com/docs/ko/permissions.md#bash-rule-limits) 일치하는 호출만 거부합니다. [`EndConversation`](https://code.claude.com/docs/ko/tools-reference#endconversation-tool-behavior)을 이름 지은 규칙은 다른 도구가 남아 있는 동안 제거할 수 없습니다 | `"Bash(git log *)" "Bash(git diff *)" "Edit"` |

88| `--effort` | 현재 세션에 대해 [노력 수준](https://code.claude.com/docs/ko/model-config.md#adjust-effort-level)을 설정합니다. 옵션: `low`, `medium`, `high`, `xhigh`, `max` 또는 `ultracode`입니다. 사용 가능한 수준은 모델에 따라 다릅니다. `ultracode`는 [ultracode](https://code.claude.com/docs/ko/workflows.md#let-claude-decide-with-ultracode)가 켜진 상태에서 `xhigh` 노력을 요청하며, Claude Code v2.1.203 이상이 필요합니다. 이 세션에 대해 [`modelSettings`](https://code.claude.com/docs/ko/settings-reference#modelsettings) 및 [`effortLevel`](https://code.claude.com/docs/ko/settings-reference#effortlevel) 설정을 재정의하고 유지되지 않습니다 | `claude --effort high` |88| `--effort` | 현재 세션에 대해 [effort 수준](https://code.claude.com/docs/ko/model-config.md#adjust-effort-level)을 설정합니다. 옵션: `low`, `medium`, `high`, `xhigh`, `max` 또는 `ultracode`입니다. 사용 가능한 수준은 모델에 따라 다릅니다. `ultracode`는 [ultracode](https://code.claude.com/docs/ko/workflows.md#let-claude-decide-with-ultracode)가 켜진 상태에서 `xhigh` effort를 요청하며, Claude Code v2.1.203 이상이 필요합니다. 메인 대화의 모델에서 이 세션에 대해 [`modelSettings`](https://code.claude.com/docs/ko/settings-reference#modelsettings) 및 [`effortLevel`](https://code.claude.com/docs/ko/settings-reference#effortlevel) 설정을 재정의하며 유지되지 않습니다 | `claude --effort high` |

89| `--enable-auto-mode` | v2.1.111에서 제거됨. 자동 모드는 이제 `Shift+Tab` 사이클에 기본적으로 있습니다. `--permission-mode auto`를 사용하여 시작합니다 | `claude --permission-mode auto` |89| `--enable-auto-mode` | v2.1.111에서 제거됨. 자동 모드는 이제 `Shift+Tab` 사이클에 기본적으로 있습니다. `--permission-mode auto`를 사용하여 시작합니다 | `claude --permission-mode auto` |

90| `--environment <environment-id>` | 주어진 ID를 가진 [자체 호스팅 환경](https://code.claude.com/docs/ko/self-hosted-environments)에서 실행되는 새 클라우드 세션을 만듭니다. 환경 ID는 `ccpool_`로 시작합니다. 디스패치 동작 및 거부하는 플래그 조합에 대해 [`--environment` 디스패치 동작](https://code.claude.com/docs/ko/self-hosted-environments-testing#environment-dispatch-behavior)을 참조하세요. Claude Code v2.1.224 이상이 필요합니다 | `claude -p "Fix the login bug" --environment ccpool_abc123` |90| `--environment <environment-id>` | 주어진 ID를 가진 [자체 호스팅 환경](https://code.claude.com/docs/ko/self-hosted-environments)에서 실행되는 새 클라우드 세션을 만듭니다. 환경 ID는 `ccpool_`로 시작합니다. 디스패치 동작 및 거부하는 플래그 조합에 대해 [`--environment` 디스패치 동작](https://code.claude.com/docs/ko/self-hosted-environments-testing#environment-dispatch-behavior)을 참조하세요. Claude Code v2.1.224 이상이 필요합니다 | `claude -p "Fix the login bug" --environment ccpool_abc123` |

91| `--exclude-dynamic-system-prompt-sections` | 자동 메모리 위치와 같은 사용자별 컨텍스트를 시스템 프롬프트에서 첫 번째 사용자 메시지로 이동합니다. 동일한 작업을 실행하는 다양한 사용자 및 머신 간에 프롬프트 캐시 재사용을 개선합니다. 기본 시스템 프롬프트에만 적용됩니다. `--system-prompt` 또는 `--system-prompt-file`이 설정되면 무시됩니다. 스크립트된 다중 사용자 워크로드에 `-p`와 함께 사용합니다 | `claude -p --exclude-dynamic-system-prompt-sections "query"` |91| `--exclude-dynamic-system-prompt-sections` | 자동 메모리 위치와 같은 사용자별 컨텍스트를 시스템 프롬프트에서 첫 번째 사용자 메시지로 이동합니다. 동일한 작업을 실행하는 다양한 사용자 및 머신 간에 프롬프트 캐시 재사용을 개선합니다. 기본 시스템 프롬프트에만 적용됩니다. `--system-prompt` 또는 `--system-prompt-file`이 설정되면 무시됩니다. 스크립트된 다중 사용자 워크로드에 `-p`와 함께 사용합니다 | `claude -p --exclude-dynamic-system-prompt-sections "query"` |

33 33 

34**2. 작업 계속하기**34**2. 작업 계속하기**

35 35 

36리뷰는 자체 컨텍스트 윈도우를 가진 백그라운드 [서브에이전트](https://code.claude.com/docs/ko/sub-agents.md)로 실행되므로 대화를 채우지 않습니다. 리뷰가 완료되면 발견 사항이 대화에 도착합니다.36터미널 세션에서 리뷰는 자체 컨텍스트 윈도우를 가진 백그라운드 [서브에이전트](https://code.claude.com/docs/ko/sub-agents.md)로 실행되므로 대화를 채우지 않습니다. 리뷰가 완료되면 발견 사항이 대화에 도착합니다.

37 37 

38**3. 발견 사항에 대응하기**38**3. 발견 사항에 대응하기**

39 39 

59| `/autocompact [auto\|<tokens>]` | 자동 압축 윈도우, 즉 Claude Code가 자동으로 압축하기 전까지 컨텍스트 윈도우가 얼마나 채워지는지를 설정합니다. `500k`와 같은 크기를 전달하거나, `auto`를 전달하여 모델에 맞게 조정된 윈도우로 되돌립니다. Claude Code는 값을 사용자 설정에 저장하고 현재 세션에 적용합니다. 허용되는 값과 이를 재정의하는 항목은 [자동 압축 윈도우 설정](https://code.claude.com/docs/ko/model-config.md#set-the-auto-compact-window)을 참조하세요. 인수 없이 실행하면 현재 윈도우를 보여주는 대화 상자가 열립니다. Claude Code v2.1.221 이상이 필요합니다 |59| `/autocompact [auto\|<tokens>]` | 자동 압축 윈도우, 즉 Claude Code가 자동으로 압축하기 전까지 컨텍스트 윈도우가 얼마나 채워지는지를 설정합니다. `500k`와 같은 크기를 전달하거나, `auto`를 전달하여 모델에 맞게 조정된 윈도우로 되돌립니다. Claude Code는 값을 사용자 설정에 저장하고 현재 세션에 적용합니다. 허용되는 값과 이를 재정의하는 항목은 [자동 압축 윈도우 설정](https://code.claude.com/docs/ko/model-config.md#set-the-auto-compact-window)을 참조하세요. 인수 없이 실행하면 현재 윈도우를 보여주는 대화 상자가 열립니다. Claude Code v2.1.221 이상이 필요합니다 |

60| `/autofix-pr [prompt]` | 현재 브랜치의 PR을 감시하다가 CI가 실패하거나 리뷰어가 코멘트를 남기면 수정 사항을 푸시하는 [클라우드 세션](https://code.claude.com/docs/ko/claude-code-on-the-web.md#auto-fix-pull-requests)을 생성합니다. `gh pr view`를 사용해 체크아웃된 브랜치에서 열린 PR을 감지하며, 다른 PR을 감시하려면 먼저 해당 브랜치를 체크아웃합니다. 기본적으로 클라우드 세션은 모든 CI 실패와 리뷰 코멘트를 수정하도록 지시받으며, 다른 지침을 주려면 프롬프트를 전달합니다(예: `/autofix-pr only fix lint and type errors`). `gh` CLI와 [클라우드 세션](https://code.claude.com/docs/ko/claude-code-on-the-web.md)에 대한 액세스 권한이 필요합니다 |60| `/autofix-pr [prompt]` | 현재 브랜치의 PR을 감시하다가 CI가 실패하거나 리뷰어가 코멘트를 남기면 수정 사항을 푸시하는 [클라우드 세션](https://code.claude.com/docs/ko/claude-code-on-the-web.md#auto-fix-pull-requests)을 생성합니다. `gh pr view`를 사용해 체크아웃된 브랜치에서 열린 PR을 감지하며, 다른 PR을 감시하려면 먼저 해당 브랜치를 체크아웃합니다. 기본적으로 클라우드 세션은 모든 CI 실패와 리뷰 코멘트를 수정하도록 지시받으며, 다른 지침을 주려면 프롬프트를 전달합니다(예: `/autofix-pr only fix lint and type errors`). `gh` CLI와 [클라우드 세션](https://code.claude.com/docs/ko/claude-code-on-the-web.md)에 대한 액세스 권한이 필요합니다 |

61| `/background [prompt]` | 현재 세션을 분리하여 [백그라운드 에이전트](https://code.claude.com/docs/ko/agent-view.md)로 실행하고 이 터미널을 비웁니다. 분리하기 전에 지침을 하나 더 보내려면 프롬프트를 전달합니다. `claude agents`로 세션을 모니터링합니다. 이 세션을 계속 실행하면서 대화를 새 백그라운드 세션에 복사하려면 `/fork`를 사용합니다. 별칭: `/bg` |61| `/background [prompt]` | 현재 세션을 분리하여 [백그라운드 에이전트](https://code.claude.com/docs/ko/agent-view.md)로 실행하고 이 터미널을 비웁니다. 분리하기 전에 지침을 하나 더 보내려면 프롬프트를 전달합니다. `claude agents`로 세션을 모니터링합니다. 이 세션을 계속 실행하면서 대화를 새 백그라운드 세션에 복사하려면 `/fork`를 사용합니다. 별칭: `/bg` |

62| `/batch <instruction>` | **[스킬](https://code.claude.com/docs/ko/skills.md#bundled-skills).** 코드베이스 전반의 대규모 변경을 병렬로 조율합니다. 코드베이스를 조사하고, 작업을 5\~30개의 독립적인 단위로 분해한 후 계획을 제시합니다. 승인되면 격리된 [worktree](https://code.claude.com/docs/ko/worktrees.md)에서 단위당 하나의 [백그라운드 서브에이전트](https://code.claude.com/docs/ko/sub-agents.md#run-subagents-in-foreground-or-background)를 생성합니다. 각 서브에이전트는 자신의 단위를 구현하고, 테스트를 실행하고, 변경 사항을 게시합니다. git 저장소 또는 worktree를 생성하는 [`WorktreeCreate` 훅](https://code.claude.com/docs/ko/worktrees#non-git-version-control)이 필요합니다. git 저장소 외부에서 `/batch`를 사용하려면 Claude Code v2.1.281 이상이 필요합니다. 예: `/batch migrate src/ from JavaScript to TypeScript` |62| `/batch <instruction>` | **[스킬](https://code.claude.com/docs/ko/skills.md#bundled-skills).** 코드베이스 전반의 대규모 변경을 병렬로 조율합니다. 코드베이스를 조사하고, 작업을 5\~30개의 독립적인 단위로 분해한 후 계획을 제시합니다. 승인되면 격리된 [worktree](https://code.claude.com/docs/ko/worktrees.md)에서 단위당 하나의 [백그라운드 서브에이전트](https://code.claude.com/docs/ko/sub-agents.md#run-subagents-in-foreground-or-background)를 생성합니다. 각 서브에이전트는 자신의 단위를 구현하고, 테스트를 실행한 후, PR을 열거나 진행 결과를 보고합니다. git 저장소 또는 worktree를 생성하는 [`WorktreeCreate` 훅](https://code.claude.com/docs/ko/worktrees#non-git-version-control)이 필요합니다. git 저장소 외부에서 `/batch`를 사용하려면 Claude Code v2.1.281 이상이 필요합니다. 예: `/batch migrate src/ from JavaScript to TypeScript` |

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

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

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

335| `CLAUDE_CODE_NONBLOCKING_STDOUT` | 두 번째 논블로킹 파일 디스크립터를 통해 터미널 출력을 쓰려면 `1`로 설정합니다. 이렇게 하면 일시 중지된 tmux 컨트롤 모드 창이나 멈춘 SSH 연결처럼 읽기를 중단한 터미널이 세션 도중 Claude Code를 멈추게 할 수 없습니다. stdout이 터미널인 경우 macOS, Linux, WSL에서 적용됩니다. Claude Code v2.1.261 이상이 필요합니다 |335| `CLAUDE_CODE_NONBLOCKING_STDOUT` | 두 번째 논블로킹 파일 디스크립터를 통해 터미널 출력을 쓰려면 `1`로 설정합니다. 이렇게 하면 일시 중지된 tmux 컨트롤 모드 창이나 멈춘 SSH 연결처럼 읽기를 중단한 터미널이 세션 도중 Claude Code를 멈추게 할 수 없습니다. stdout이 터미널인 경우 macOS, Linux, WSL에서 적용됩니다. Claude Code v2.1.261 이상이 필요합니다 |

336| `CLAUDE_CODE_NONSTREAMING_TIMEOUT_RETRIES` | 시간 초과된 [비스트리밍 요청](https://code.claude.com/docs/ko/errors.md#streaming-response-ended-before-any-complete-data-was-received)을 Claude Code가 다시 보내는 횟수를 제한합니다. `0`이면 첫 번째 시간 초과에서 요청이 실패합니다. 타임아웃에 대해서는 [재시도 동작 조정](https://code.claude.com/docs/ko/errors.md#tune-retry-behavior)을 참조하세요. Claude Code v2.1.285 이상이 필요합니다 |336| `CLAUDE_CODE_NONSTREAMING_TIMEOUT_RETRIES` | 시간 초과된 [비스트리밍 요청](https://code.claude.com/docs/ko/errors.md#streaming-response-ended-before-any-complete-data-was-received)을 Claude Code가 다시 보내는 횟수를 제한합니다. `0`이면 첫 번째 시간 초과에서 요청이 실패합니다. 타임아웃에 대해서는 [재시도 동작 조정](https://code.claude.com/docs/ko/errors.md#tune-retry-behavior)을 참조하세요. Claude Code v2.1.285 이상이 필요합니다 |

337| `CLAUDE_CODE_NO_FLICKER` | 깜박임을 줄이고 긴 대화에서 메모리 사용량을 일정하게 유지하는 리서치 프리뷰인 [전체 화면 렌더링](https://code.claude.com/docs/ko/fullscreen.md)을 활성화하려면 `1`로 설정합니다. [`tui`](https://code.claude.com/docs/ko/settings-reference#tui) 설정을 재정의하며, `/tui fullscreen`으로도 전환할 수 있습니다 |337| `CLAUDE_CODE_NO_FLICKER` | 깜박임을 줄이고 긴 대화에서 메모리 사용량을 일정하게 유지하는 리서치 프리뷰인 [전체 화면 렌더링](https://code.claude.com/docs/ko/fullscreen.md)을 활성화하려면 `1`로 설정합니다. [`tui`](https://code.claude.com/docs/ko/settings-reference#tui) 설정을 재정의하며, `/tui fullscreen`으로도 전환할 수 있습니다 |

338| `CLAUDE_CODE_OAUTH_REFRESH_TOKEN` | Claude.ai 인증을 위한 OAuth 갱신 토큰입니다. 설정하면 `claude auth login`이 브라우저를 여는 대신 이 토큰을 직접 교환합니다. `CLAUDE_CODE_OAUTH_SCOPES`가 필요합니다. 자동화된 환경에서 인증을 프로비저닝할 때 유용합니다 |338| `CLAUDE_CODE_OAUTH_REFRESH_TOKEN` | claude.ai 인증을 위한 OAuth 리프레시 토큰입니다. 설정하면 `claude auth login`이 브라우저를 여는 대신 이 토큰을 직접 교환합니다. `CLAUDE_CODE_OAUTH_SCOPES`가 필요합니다. 자동화된 환경에서 인증을 프로비저닝할 때 유용합니다. [프로젝트 및 로컬 설정](https://code.claude.com/docs/ko/settings-reference.md#variables-claude-code-ignores-in-env)에서는 무시됩니다 |

339| `CLAUDE_CODE_OAUTH_SCOPES` | 갱신 토큰이 발급될 때의 OAuth 범위를 공백으로 구분한 목록입니다(예: `"user:profile user:inference user:sessions:claude_code"`). `CLAUDE_CODE_OAUTH_REFRESH_TOKEN`이 설정된 경우 필수입니다 |339| `CLAUDE_CODE_OAUTH_SCOPES` | 리프레시 토큰이 발급될 때 사용된 공백으로 구분된 OAuth 범위입니다(예: `"user:profile user:inference user:sessions:claude_code"`). `CLAUDE_CODE_OAUTH_REFRESH_TOKEN`이 설정된 경우 필요합니다. [프로젝트 및 로컬 설정](https://code.claude.com/docs/ko/settings-reference.md#variables-claude-code-ignores-in-env)에서는 무시됩니다 |

340| `CLAUDE_CODE_OAUTH_TOKEN` | claude.ai 인증을 위한 OAuth 액세스 토큰입니다. SDK 및 자동화된 환경에서 `/login`의 대안입니다. 키체인에 저장된 자격 증명보다 우선합니다. [`claude setup-token`](https://code.claude.com/docs/ko/authentication#generate-a-long-lived-token)으로 생성합니다. [`/login`](https://code.claude.com/docs/ko/authentication#authentication-precedence)을 실행하지 않는 한 Claude Code는 세션 전체에서 설정한 토큰을 사용합니다. 만료된 토큰을 교체하려면 새 토큰을 생성하고 다시 시작합니다 |340| `CLAUDE_CODE_OAUTH_TOKEN` | claude.ai 인증을 위한 OAuth 액세스 토큰입니다. SDK 및 자동화된 환경에서 `/login`의 대안으로 사용합니다. [프로젝트 및 로컬 설정](https://code.claude.com/docs/ko/settings-reference.md#variables-claude-code-ignores-in-env)에서는 무시됩니다. 키체인에 저장된 자격 증명보다 우선합니다. [`claude setup-token`](https://code.claude.com/docs/ko/authentication#generate-a-long-lived-token)으로 생성하세요. [`/login`](https://code.claude.com/docs/ko/authentication#authentication-precedence)을 실행하지 않는 한 Claude Code는 세션 전체에서 설정한 토큰을 사용합니다. 만료된 토큰을 교체하려면 새 토큰을 생성하고 다시 시작하세요 |

341| `CLAUDE_CODE_OPUS_4_6_FAST_MODE_OVERRIDE` | v2.1.160에서 제거되었으며 이제 아무 작업도 하지 않습니다. 이전에는 [빠른 모드](https://code.claude.com/docs/ko/fast-mode.md)를 현재 기본값 대신 Claude Opus 4.6으로 고정했습니다. Opus 4.6은 더 이상 빠른 모드를 지원하지 않습니다 |341| `CLAUDE_CODE_OPUS_4_6_FAST_MODE_OVERRIDE` | v2.1.160에서 제거되었으며 이제 아무 작업도 하지 않습니다. 이전에는 [빠른 모드](https://code.claude.com/docs/ko/fast-mode.md)를 현재 기본값 대신 Claude Opus 4.6으로 고정했습니다. Opus 4.6은 더 이상 빠른 모드를 지원하지 않습니다 |

342| `CLAUDE_CODE_OTEL_CONTENT_MAX_LENGTH` | 콘텐츠를 담는 OpenTelemetry 속성(모델 응답, 도구 콘텐츠, 시스템 프롬프트, 원시 API 본문)의 최대 길이로, 잘림 표시를 포함하며 UTF-16 코드 단위로 계산합니다(기본값: 61440, 즉 60 KB). 텔레메트리 백엔드가 64 KB보다 큰 속성 값을 허용하는 경우에만 늘리고, 텔레메트리 양을 줄이려면 낮춥니다. Claude Code v2.1.214 이상이 필요합니다. [모니터링](https://code.claude.com/docs/ko/monitoring-usage.md)을 참조하세요 |342| `CLAUDE_CODE_OTEL_CONTENT_MAX_LENGTH` | 콘텐츠를 담는 OpenTelemetry 속성(모델 응답, 도구 콘텐츠, 시스템 프롬프트, 원시 API 본문)의 최대 길이로, 잘림 표시를 포함하며 UTF-16 코드 단위로 계산합니다(기본값: 61440, 즉 60 KB). 텔레메트리 백엔드가 64 KB보다 큰 속성 값을 허용하는 경우에만 늘리고, 텔레메트리 양을 줄이려면 낮춥니다. Claude Code v2.1.214 이상이 필요합니다. [모니터링](https://code.claude.com/docs/ko/monitoring-usage.md)을 참조하세요 |

343| `CLAUDE_CODE_OTEL_DIAG_STDERR` | OpenTelemetry 익스포터 진단 오류를 stderr에 쓰려면 `1`로 설정합니다. 기본적으로 이러한 오류는 `--debug`에서만 표시되므로, 그렇지 않으면 Prometheus 포트 충돌과 같이 잘못 구성된 익스포터가 조용히 실패합니다. Claude Code v2.1.179 이상이 필요합니다. [모니터링](https://code.claude.com/docs/ko/monitoring-usage.md)을 참조하세요 |343| `CLAUDE_CODE_OTEL_DIAG_STDERR` | OpenTelemetry 익스포터 진단 오류를 stderr에 쓰려면 `1`로 설정합니다. 기본적으로 이러한 오류는 `--debug`에서만 표시되므로, 그렇지 않으면 Prometheus 포트 충돌과 같이 잘못 구성된 익스포터가 조용히 실패합니다. Claude Code v2.1.179 이상이 필요합니다. [모니터링](https://code.claude.com/docs/ko/monitoring-usage.md)을 참조하세요 |

66| `This organization has been disabled` | [인증](#this-organization-has-been-disabled) |66| `This organization has been disabled` | [인증](#this-organization-has-been-disabled) |

67| `Your organization has disabled API key authentication` | [인증](#your-organization-has-disabled-api-key-authentication) |67| `Your organization has disabled API key authentication` | [인증](#your-organization-has-disabled-api-key-authentication) |

68| `Your organization has disabled Claude subscription access` | [인증](#your-organization-has-disabled-claude-subscription-access) |68| `Your organization has disabled Claude subscription access` | [인증](#your-organization-has-disabled-claude-subscription-access) |

69| `Routines are disabled by your organization's policy` | [인증](#routines-are-disabled-by-your-organizations-policy) |69| `Scheduled tasks are off for your organization` | [인증](#routines-are-disabled-by-your-organizations-policy) |

70| `Routines are off for your organization` | [인증](#routines-are-disabled-by-your-organizations-policy) |

70| `Remote Control is only available when using Claude via api.anthropic.com` | [인증](#remote-control-requires-the-anthropic-api) |71| `Remote Control is only available when using Claude via api.anthropic.com` | [인증](#remote-control-requires-the-anthropic-api) |

71| `OAuth token refresh failed — run /login to re-authenticate` | [인증](#remote-control-couldnt-refresh-your-login) |72| `OAuth token refresh failed — run /login to re-authenticate` | [인증](#remote-control-couldnt-refresh-your-login) |

72| `JWT refresh failed: no OAuth token — run /login` | [인증](#remote-control-couldnt-refresh-your-login) |73| `JWT refresh failed: no OAuth token — run /login` | [인증](#remote-control-couldnt-refresh-your-login) |

755Auto mode is unavailable — the server returned no safety verdict for the last 10 responses, so Claude stopped. Send a message to try again, or switch out of auto mode.756Auto mode is unavailable — the server returned no safety verdict for the last 10 responses, so Claude stopped. Send a message to try again, or switch out of auto mode.

756```757```

757 758 

759[훅 또는 mod의 변경으로 인한 거부](#hook-changed-input-after-review)를 포함하여 일부 거부는 10개에 포함되지 않습니다.

760 

758중지 메시지는 각 세션 종류에서 다른 위치에 나타납니다:761중지 메시지는 각 세션 종류에서 다른 위치에 나타납니다:

759 762 

760* 대화형 세션에서 메시지는 트랜스크립트에 경고로 나타나고 턴이 끝납니다763* 대화형 세션에서 메시지는 트랜스크립트에 경고로 나타나고 턴이 끝납니다

774 777 

775v2.1.302 이전에는 Anthropic API에 대한 직접 연결에서 Claude Code가 서버 검사에 비해 너무 길어진 대화를 압축하지 않았습니다.778v2.1.302 이전에는 Anthropic API에 대한 직접 연결에서 Claude Code가 서버 검사에 비해 너무 길어진 대화를 압축하지 않았습니다.

776 779 

780#### `a hook changed this call's input after auto mode reviewed it`

781 

782이 거부는 서버가 검토한 후 훅 또는 mod가 [호출의 입력을 변경](https://code.claude.com/docs/ko/hooks.md#pretooluse-updatedinput-in-auto-mode)했기 때문에 검토가 실제로 실행될 내용을 다루지 않는다는 의미입니다. 작업이 안전하지 않다는 판단이 아닙니다.

783 

784동일한 Claude 응답의 이후 호출도 다음 사유로 거부될 수 있습니다:

785 

786```text theme={null}

787another call in this response was changed by a hook after auto mode reviewed it, or could not be confirmed unchanged

788```

789 

790그러면 Claude는 거부된 각 호출을 다시 발급하여 서버가 검토하도록 할 수 있습니다. 권한 프롬프트가 열리면 응답합니다. Claude가 응답에서 자동 모드가 호출을 검사할 수 없었다고 말하지 않는 한 다른 작업은 필요하지 않습니다. 그런 경우 변경을 중지하거나 호출을 직접 승인한 다음 Claude에게 호출을 다시 시도하도록 요청합니다:

791 

792* **변경 중지**: 해당 호출 또는 동일한 Claude 응답의 이전 호출을 변경한 [훅](https://code.claude.com/docs/ko/hooks.md#disable-or-remove-hooks) 또는 [mod](https://code.claude.com/docs/ko/plugins/mods/overview.md#turn-mods-on-or-off)를 끄거나 관리자에게 끄도록 요청합니다. 훅을 찾으려면 Claude Code 프롬프트에서 [`/hooks`](https://code.claude.com/docs/ko/hooks#the-%2Fhooks-menu)를 실행합니다. 터미널 세션에서는 `/plugin`을 실행하여 활성 mod를 확인합니다.

793* **호출 직접 승인**: [Manual 모드로 전환](https://code.claude.com/docs/ko/permission-modes.md#switch-permission-modes)합니다

794 

777### Was not reviewed and did not run795### Was not reviewed and did not run

778 796 

779`was not reviewed and did not run` 거부는 대화가 너무 길어 [자동 모드](https://code.claude.com/docs/ko/permission-modes.md#eliminate-prompts-with-auto-mode) 분류기가 작업을 검사할 수 없으므로 작업이 실행되지 않았음을 의미합니다. Claude Code는 Claude에게 다음 메시지를 반환합니다:797`was not reviewed and did not run` 거부는 대화가 너무 길어 [자동 모드](https://code.claude.com/docs/ko/permission-modes.md#eliminate-prompts-with-auto-mode) 분류기가 작업을 검사할 수 없으므로 작업이 실행되지 않았음을 의미합니다. Claude Code는 Claude에게 다음 메시지를 반환합니다:

1188* 구독 대신 Console API 키로 인증합니다. 설정 방법은 [Claude Console 인증](https://code.claude.com/docs/ko/authentication.md#claude-console-authentication)을 참조하십시오.1206* 구독 대신 Console API 키로 인증합니다. 설정 방법은 [Claude Console 인증](https://code.claude.com/docs/ko/authentication.md#claude-console-authentication)을 참조하십시오.

1189* 관리자인데 액세스를 활성화하는 옵션이 보이지 않으면 [Anthropic 지원팀](https://support.claude.com)에 문의합니다1207* 관리자인데 액세스를 활성화하는 옵션이 보이지 않으면 [Anthropic 지원팀](https://support.claude.com)에 문의합니다

1190 1208 

1191### 조직 정책에 의해 루틴이 비활성화됨1209### Scheduled tasks are off for your organization

1192 1210 

1193Team 또는 Enterprise 조직의 Owner가 조직 수준에서 [클라우드 예약 작업](https://code.claude.com/docs/ko/routines.md)(이전 명칭: 루틴)을 비활성화했습니다. 이 오류는 예를 들어 [claude.ai/code/routines](https://claude.ai/code/routines)에서 예약 작업을 만들거나 실행하려고 할 때 나타납니다. Claude Code v2.1.227 이상에서는 같은 설정이 CLI의 [`/schedule`도 숨깁니다](https://code.claude.com/docs/ko/routines#troubleshooting).1211조직에서 [클라우드 예약 작업](https://code.claude.com/docs/ko/routines.md)이 꺼져 있으므로 예약 작업을 만들거나 실행할 수 없습니다. claude.ai에서 보내는 메시지는 이를 예약 작업(scheduled tasks) 또는 루틴(routines)이라고 부르며, 뒤에 관리자에 관한 문장이 이어집니다.

1194 1212 

1195```text theme={null}1213```text theme={null}

1196Routines are disabled by your organization's policy.1214Scheduled tasks are off for your organization. …

1215Routines are off for your organization. …

1197```1216```

1198 1217 

1199이는 서버 측 설정이므로 로컬 설정, 환경 변수, CLI 플래그로 재정의할 수 없습니다.1218로컬 설정, 환경 변수 또는 CLI 플래그로는 이 기능을 켤 수 없습니다.

1200 1219 

1201**해결 방법:**1220**해결 방법:**

1202 1221 

1203* 조직의 Owner에게 [**Organization settings > Capabilities > Remote sessions**](https://claude.ai/admin-settings/capabilities)에서 **Scheduled tasks (Was Routines)** 토글을 켜 달라고 요청합니다1222* Team 또는 Enterprise Owner에게 [**Organization settings > Capabilities > Remote sessions**](https://claude.ai/admin-settings/capabilities)에서 **Scheduled tasks (Was Routines)** 또는 **Routines**라는 토글을 켤 수 있는지 문의합니다

1204 1223 

1205### Remote Control에는 Anthropic API가 필요함1224### Remote Control에는 Anthropic API가 필요함

1206 1225 

197* **수락하는 경우**: Claude Code가 새 모델 ID를 [사용자 설정 파일](https://code.claude.com/docs/ko/settings.md)에 쓰고 다시 시작합니다197* **수락하는 경우**: Claude Code가 새 모델 ID를 [사용자 설정 파일](https://code.claude.com/docs/ko/settings.md)에 쓰고 다시 시작합니다

198* **거절하는 경우**: Claude Code가 다음 기본 버전 변경까지 선택을 기억합니다198* **거절하는 경우**: Claude Code가 다음 기본 버전 변경까지 선택을 기억합니다

199 199 

200[관리형 설정](https://code.claude.com/docs/ko/managed-settings.md)의 `env` 블록에 있는 고정에 대해서는 Claude Code가 확인을 실행하지 않으며 프롬프트도 표시하지 않습니다.200[관리형 설정](https://code.claude.com/docs/ko/managed-settings.md)의 `env` 블록에 있는 고정에 대해서는 Claude Code가 확인을 실행하지 않으며 프롬프트도 표시하지 않습니다. 이 고정에 대해 업데이트 프롬프트가 계속 표시되면 Claude Code를 v2.1.314 이상으로 업데이트합니다. v2.1.314 이전에는 수락한 후에도 관리형 고정이 계속 적용되었으므로 다음 시작 시 프롬프트가 다시 표시되었습니다.

201 201 

202모델을 고정하지 않았고 현재 기본값을 프로젝트에서 사용할 수 없으면 Claude Code는 현재 세션에 대해 이전 버전으로 폴백하고 알림을 표시합니다. 기본값이 Opus 모델이고 사용 가능한 Opus 버전이 없으면 기본 Sonnet 모델로 폴백합니다. 폴백은 유지되지 않습니다. [Model Garden](https://console.cloud.google.com/vertex-ai/model-garden)에서 최신 모델을 활성화하거나 [버전을 고정](#5-pin-model-versions)하여 선택을 영구적으로 만듭니다.202모델을 고정하지 않았고 현재 기본값을 프로젝트에서 사용할 수 없으면 Claude Code는 현재 세션에 대해 이전 버전으로 폴백하고 알림을 표시합니다. 기본값이 Opus 모델이고 사용 가능한 Opus 버전이 없으면 기본 Sonnet 모델로 폴백합니다. 폴백은 유지되지 않습니다. [Model Garden](https://console.cloud.google.com/vertex-ai/model-garden)에서 최신 모델을 활성화하거나 [버전을 고정](#5-pin-model-versions)하여 선택을 영구적으로 만듭니다.

203 203 

204### 특정 모델에서 세션 시작하기

205 

204특정 Sonnet 또는 Opus 버전에서 세션을 시작할 때(예: `--model`, `ANTHROPIC_MODEL` 또는 [`model` 설정](https://code.claude.com/docs/ko/settings-reference#model)을 사용하여), 해당 버전은 일치하는 `sonnet` 또는 `opus` 별칭에 대한 세션의 고정된 기본값으로 작동합니다. Claude Code는 모델이 대체하는 기본 제공 기본값에 대한 가용성 확인을 건너뛰고 구성한 모델에서 시작하며 폴백 알림이 없습니다.206특정 Sonnet 또는 Opus 버전에서 세션을 시작할 때(예: `--model`, `ANTHROPIC_MODEL` 또는 [`model` 설정](https://code.claude.com/docs/ko/settings-reference#model)을 사용하여), 해당 버전은 일치하는 `sonnet` 또는 `opus` 별칭에 대한 세션의 고정된 기본값으로 작동합니다. Claude Code는 모델이 대체하는 기본 제공 기본값에 대한 가용성 확인을 건너뛰고 구성한 모델에서 시작하며 폴백 알림이 없습니다.

205 207 

206`opus`와 같은 모델 별칭은 고정으로 작동하지 않으며, Claude Code가 인식하지 못하는 모델 ID도 마찬가지입니다.208`opus`와 같은 모델 별칭이나 Claude Code가 인식하지 못하는 모델 ID로 세션을 시작하면 해당 값은 고정으로 작동하지 않습니다.

209 

210### 기억된 모델 거부

207 211 

208이러한 확인에서 프로젝트가 호출할 수 없는 모델을 찾으면 Claude Code는 이 머신에서 거부를 최대 하루 동안 기억하고, 그 시간 동안 기억된 모델을 건너뛰고 Agent Platform에 다시 묻지 않고 시작합니다. Claude Code는 마지막 확인 이후 10분이 경과한 현재 기본 모델의 거부를 시작할 때 다시 확인하므로, 관리자가 다시 활성화한 기본값이 돌아옵니다. 메모리를 끄려면 [`CLAUDE_CODE_SKIP_MODEL_ACCESS_MEMORY=1`](https://code.claude.com/docs/ko/env-vars)을 설정합니다.212시작 모델 확인에서 프로젝트가 호출할 수 없는 모델을 찾으면 Claude Code는 이 머신에서 거부를 최대 하루 동안 기억할 수 있습니다. 마지막 확인 이후 10분이 경과하면 Claude Code는 시작할 때 현재 기본 모델에 대해 기억된 거부를 다시 확인합니다. 그러면 관리자가 다시 활성화한 기본값이 돌아옵니다. 메모리를 끄려면 [`CLAUDE_CODE_SKIP_MODEL_ACCESS_MEMORY=1`](https://code.claude.com/docs/ko/env-vars)을 설정합니다.

209 213 

210### 조직에서 모델 허용 목록을 적용하는 경우214### 조직에서 모델 허용 목록을 적용하는 경우

211 215 

901 901 

902#### hook이 실패할 때 작업 차단902#### hook이 실패할 때 작업 차단

903 903 

904대부분의 이벤트에서 hook이 실패하거나 시간 초과되어도 Claude Code는 작업을 계속 수행합니다. 그러면 경로가 잘못되었거나 스크립트가 충돌하는 정책 hook은 모든 것을 통과시킵니다. 대신 작업을 차단하려면 `command` 또는 `http` hook에 `"onFailure": "block"`을 설정합니다. Claude Code v2.1.295 이상이 필요합니다.904대부분의 이벤트에서 hook이 실패하거나 시간 초과되어도 Claude Code는 작업을 계속 수행합니다. 그러면 경로가 잘못되었거나 스크립트가 충돌하는 정책 hook은 모든 것을 통과시킵니다. 대신 작업을 차단하려면 `command` 또는 `http` hook에 `"onFailure": "block"`을 설정합니다. Claude Code v2.1.295 이상이 필요합니다. Agent SDK 콜백 hook의 경우 [콜백이 실패할 때 작업 차단](https://code.claude.com/docs/ko/agent-sdk/hooks.md#block-the-action-when-a-callback-fails)을 참조하세요.

905 905 

906> [!NOTE]906> [!NOTE]

907>907>

1960| :- | :- |1960| :- | :- |

1961| `permissionDecision` | `"allow"`는 권한 프롬프트를 건너뜁니다. 단, [어떤 모드에서도 자동 승인되지 않는 작업](https://code.claude.com/docs/ko/permission-modes.md#actions-no-mode-auto-approves)과 [네트워크 경로에서의 읽기](https://code.claude.com/docs/ko/permissions.md#network-paths)는 예외입니다. [권한 모드가 호출을 승인](https://code.claude.com/docs/ko/agent-sdk/typescript.md#permission-modes-that-can-approve-an-always_ask-call)하지 않는 한, [Agent SDK 앱이 `always_ask`로 표시한 도구](https://code.claude.com/docs/ko/agent-sdk/custom-tools#require-approval-for-specific-tools)에 대한 호출의 승인도 건너뛰지 않습니다. `AskUserQuestion`과 `ExitPlanMode`에는 [`"allow"`와 함께 `updatedInput`](#allow-with-updatedinput)이 필요합니다. 플랜 모드에 대해서는 [플랜 모드에서의 훅 승인](https://code.claude.com/docs/ko/permissions.md#hook-approvals-in-plan-mode)을 참조하십시오. `"deny"`는 도구 호출을 막습니다. `"ask"`는 사용자에게 확인을 요청합니다. `"defer"`는 도구를 나중에 재개할 수 있도록 턴을 종료하며, `-p` 플래그를 사용하는 [비대화형 모드](#defer-a-tool-call-for-later)가 필요합니다. 훅이 무엇을 반환하든 [거부 및 확인 규칙](https://code.claude.com/docs/ko/permissions.md#manage-permissions)은 여전히 평가됩니다 |1961| `permissionDecision` | `"allow"`는 권한 프롬프트를 건너뜁니다. 단, [어떤 모드에서도 자동 승인되지 않는 작업](https://code.claude.com/docs/ko/permission-modes.md#actions-no-mode-auto-approves)과 [네트워크 경로에서의 읽기](https://code.claude.com/docs/ko/permissions.md#network-paths)는 예외입니다. [권한 모드가 호출을 승인](https://code.claude.com/docs/ko/agent-sdk/typescript.md#permission-modes-that-can-approve-an-always_ask-call)하지 않는 한, [Agent SDK 앱이 `always_ask`로 표시한 도구](https://code.claude.com/docs/ko/agent-sdk/custom-tools#require-approval-for-specific-tools)에 대한 호출의 승인도 건너뛰지 않습니다. `AskUserQuestion`과 `ExitPlanMode`에는 [`"allow"`와 함께 `updatedInput`](#allow-with-updatedinput)이 필요합니다. 플랜 모드에 대해서는 [플랜 모드에서의 훅 승인](https://code.claude.com/docs/ko/permissions.md#hook-approvals-in-plan-mode)을 참조하십시오. `"deny"`는 도구 호출을 막습니다. `"ask"`는 사용자에게 확인을 요청합니다. `"defer"`는 도구를 나중에 재개할 수 있도록 턴을 종료하며, `-p` 플래그를 사용하는 [비대화형 모드](#defer-a-tool-call-for-later)가 필요합니다. 훅이 무엇을 반환하든 [거부 및 확인 규칙](https://code.claude.com/docs/ko/permissions.md#manage-permissions)은 여전히 평가됩니다 |

1962| `permissionDecisionReason` | `"ask"`의 경우 권한 프롬프트에서 사용자에게 표시됩니다. 아무도 해당 프롬프트에 답할 수 없는 `-p` 실행에서 Claude Code가 [호출을 거부](https://code.claude.com/docs/ko/headless.md#turn-off-permission-prompts-in-unattended-runs)하면, Claude가 대신 도구 결과에서 이유를 읽습니다. `"deny"`의 경우 Claude에게 표시됩니다. `"allow"` 및 `"defer"`의 경우 [디버그 로그](#debug-hooks)에만 기록됩니다 |1962| `permissionDecisionReason` | `"ask"`의 경우 권한 프롬프트에서 사용자에게 표시됩니다. 아무도 해당 프롬프트에 답할 수 없는 `-p` 실행에서 Claude Code가 [호출을 거부](https://code.claude.com/docs/ko/headless.md#turn-off-permission-prompts-in-unattended-runs)하면, Claude가 대신 도구 결과에서 이유를 읽습니다. `"deny"`의 경우 Claude에게 표시됩니다. `"allow"` 및 `"defer"`의 경우 [디버그 로그](#debug-hooks)에만 기록됩니다 |

1963| `updatedInput` | 실행 전에 도구의 입력 매개변수를 수정합니다. 전체 입력 객체를 대체하므로 수정된 필드와 함께 변경되지 않은 필드도 포함하십시오. Claude Code는 권한 규칙과 Bash 명령의 [자동 백그라운드 전환 적격성](https://code.claude.com/docs/ko/tools-reference.md#foreground-commands-that-move-to-the-background)을 Claude가 보낸 입력이 아닌 훅이 반환한 입력을 기준으로 평가합니다. 자동 승인하려면 `"allow"`와, 수정된 입력을 사용자에게 보여주려면 `"ask"`와 함께 사용하십시오. `"defer"`의 경우 무시됩니다 |1963| `updatedInput` | 실행 전에 도구의 입력 매개변수를 수정합니다. 입력 객체 전체를 대체하므로, 수정된 필드와 함께 변경되지 않은 필드도 포함하십시오. Claude Code는 Claude가 보낸 입력이 아니라 훅이 반환한 입력을 기준으로 권한 규칙과 Bash 명령의 [자동 백그라운드 전환 적격성](https://code.claude.com/docs/ko/tools-reference.md#foreground-commands-that-move-to-the-background)을 평가합니다. 자동 승인하려면 `"allow"`와, 수정된 입력을 사용자에게 보여 주려면 `"ask"`와 함께 사용하십시오. `"defer"`의 경우 무시됩니다. `permissionDecision`이 없으면 [자동 모드가 변경된 호출을 거부할 수 있습니다](#pretooluse-updatedinput-in-auto-mode) |

1964| `additionalContext` | 도구 결과와 함께 Claude의 컨텍스트에 추가되는 문자열입니다. `permissionDecision`이 `"defer"`일 때는 무시됩니다. [Claude를 위한 컨텍스트 추가](#add-context-for-claude)를 참조하십시오 |1964| `additionalContext` | 도구 결과와 함께 Claude의 컨텍스트에 추가되는 문자열입니다. `permissionDecision`이 `"defer"`일 때는 무시됩니다. [Claude를 위한 컨텍스트 추가](#add-context-for-claude)를 참조하십시오 |

1965 1965 

1966여러 PreToolUse 훅이 서로 다른 결정을 반환하면 우선순위는 `deny` > `defer` > `ask` > `allow`입니다.1966여러 PreToolUse 훅이 서로 다른 결정을 반환하면 우선순위는 `deny` > `defer` > `ask` > `allow`입니다.

1987>1987>

1988> PreToolUse는 이전에 최상위 `decision` 및 `reason` 필드를 사용했지만, 이 이벤트에서는 deprecated되었습니다. 대신 `hookSpecificOutput.permissionDecision`과 `hookSpecificOutput.permissionDecisionReason`을 사용하십시오. deprecated된 값 `"approve"`와 `"block"`은 각각 `"allow"`와 `"deny"`에 매핑됩니다. PostToolUse와 Stop 같은 다른 이벤트는 현재 형식으로 최상위 `decision`과 `reason`을 계속 사용합니다.1988> PreToolUse는 이전에 최상위 `decision` 및 `reason` 필드를 사용했지만, 이 이벤트에서는 deprecated되었습니다. 대신 `hookSpecificOutput.permissionDecision`과 `hookSpecificOutput.permissionDecisionReason`을 사용하십시오. deprecated된 값 `"approve"`와 `"block"`은 각각 `"allow"`와 `"deny"`에 매핑됩니다. PostToolUse와 Stop 같은 다른 이벤트는 현재 형식으로 최상위 `decision`과 `reason`을 계속 사용합니다.

1989 1989 

1990#### 자동 모드에서의 PreToolUse `updatedInput`

1991 

1992[자동 모드](https://code.claude.com/docs/ko/permission-modes.md#eliminate-prompts-with-auto-mode)에서 훅이 `permissionDecision` 없이 `updatedInput`을 반환하면 Claude Code가 변경된 호출을 거부할 수 있습니다. [서버가 검토한](https://code.claude.com/docs/ko/permission-modes.md#server-side-classifier-review) 것은 훅이 반환한 입력이 아니라 Claude가 작성한 입력이기 때문입니다. Anthropic API에 직접 연결된 대화형 터미널 세션과 VS Code 세션에서는 거부에 다음 텍스트가 포함됩니다.

1993 

1994```text theme={null}

1995a hook changed this call's input after auto mode reviewed it

1996```

1997 

1998이 텍스트와 함께 거부된 후, Claude는 서버가 검토하도록 변경된 호출을 다시 보낼 수 있습니다. Claude가 다음 응답에서 변경된 입력을 정확히 반복하면 훅은 여전히 실행됩니다.

1999 

2000* 훅은 호출을 거부하거나 권한 프롬프트로 보낼 수 있습니다

2001* 훅이 반환하는 `updatedInput`은 버려지므로, 실행되는 것은 서버가 검토한 내용입니다

2002 

2003[Claude가 응답에서 자동 모드가 호출을 확인할 수 없었다고 알리지](https://code.claude.com/docs/ko/errors.md#hook-changed-input-after-review) 않는 한, 이 거부 때문에 훅을 변경할 필요는 없습니다.

2004 

2005이 텍스트가 표시되는 세션에서는 설정이나 플러그인의 훅 파일에 있는 [`command` 훅](#command-hook-fields)이 이 거부 없이 Bash, PowerShell, Monitor, Edit, Write, NotebookEdit 호출을 변경할 수 있습니다. 다만 같은 Claude 응답의 이전 호출을 어떤 훅이 변경했거나 Bash 명령이 샌드박스 밖에서 실행하도록 요청하는 경우처럼 거부가 여전히 나타날 수 있습니다.

2006 

1990#### 자동 모드에서의 PreToolUse `ask` 결정2007#### 자동 모드에서의 PreToolUse `ask` 결정

1991 2008 

1992[자동 모드](https://code.claude.com/docs/ko/permission-modes.md#eliminate-prompts-with-auto-mode)에서 PreToolUse 훅의 `"ask"`는 일반적으로 도구 호출을 권한 프롬프트로 보내며, [분류기](https://code.claude.com/docs/ko/permission-modes.md#how-the-classifier-evaluates-actions)가 결정하지 않습니다. 일부 호출은 다른 경로를 따릅니다.2009[자동 모드](https://code.claude.com/docs/ko/permission-modes.md#eliminate-prompts-with-auto-mode)에서 PreToolUse 훅의 `"ask"`는 일반적으로 도구 호출을 권한 프롬프트로 보내며, [분류기](https://code.claude.com/docs/ko/permission-modes.md#how-the-classifier-evaluates-actions)가 결정하지 않습니다. 일부 호출은 다른 경로를 따릅니다.

287 287 

288### Ctrl+R을 사용한 역방향 검색288### Ctrl+R을 사용한 역방향 검색

289 289 

290`Ctrl+R`을 눌러 명령 기록을 대화형으로 검색합니다. [전체 화면 렌더링](https://code.claude.com/docs/ko/fullscreen.md)에서는 `Ctrl+R`이 검색 대화상자를 열어줍니다: 입력하여 필터링하고, `Up` 및 `Down`을 눌러 일치 항목을 이동하며, `Ctrl+S`를 눌러 범위를 이 세션, 이 프로젝트, 모든 프로젝트를 통해 순환합니다. `Enter` 또는 `Tab`을 눌러 일치 항목을 프롬프트 입력에 배치하거나, `Esc`를 눌러 취소합니다. 아래 단계는 클래식 렌더러의 인라인 검색을 설명합니다:290`Ctrl+R`을 눌러 명령 기록을 대화형으로 검색합니다. [전체 화면 렌더링](https://code.claude.com/docs/ko/fullscreen.md)에서는 `Ctrl+R`이 대신 검색 대화상자를 엽니다. 대화상자에서 입력하여 필터링하고, `Up` 및 `Down`을 눌러 일치 항목 목록을 이동하며, 미리보기 창에는 강조 표시된 일치 항목의 시작 부분이 표시됩니다.

291 

292대화상자에서 `Ctrl+S`를 눌러 범위를 이 세션, 이 프로젝트, 모든 프로젝트 순으로 순환합니다. `Enter` 또는 `Tab`을 눌러 일치 항목을 프롬프트 입력에 배치하거나, `Esc`를 눌러 취소합니다. 아래 단계는 클래식 렌더러의 인라인 검색을 설명합니다:

291 293 

2921. **검색 시작**: `Ctrl+R`을 눌러 역방향 기록 검색을 활성화합니다2941. **검색 시작**: `Ctrl+R`을 눌러 역방향 기록 검색을 활성화합니다

2932. **쿼리 입력**: 이전 명령어에서 검색할 텍스트를 입력합니다. 검색어는 일치하는 결과에서 강조 표시됩니다2952. **쿼리 입력**: 이전 명령에서 검색할 텍스트를 입력합니다. 현재 일치 항목이 프롬프트 입력에 나타납니다.

2943. **일치 항목 탐색**: `Ctrl+R`을 다시 눌러 더 오래된 일치 항목을 순환합니다2963. **일치 항목 탐색**: `Ctrl+R`을 다시 눌러 더 오래된 일치 항목을 순환합니다

2954. **검색 범위**: 인라인 검색은 항상 모든 프로젝트의 프롬프트를 검색합니다2974. **검색 범위**: 인라인 검색은 항상 모든 프로젝트의 프롬프트를 검색합니다

2965. **일치 항목 수락**:2985. **일치 항목 수락**:

300 * `Ctrl+C`를 눌러 취소하고 원래 입력을 복원합니다302 * `Ctrl+C`를 눌러 취소하고 원래 입력을 복원합니다

301 * 빈 검색에서 `Backspace`를 눌러 취소합니다303 * 빈 검색에서 `Backspace`를 눌러 취소합니다

302 304 

303인라인 검색은 전체 프롬프트 기록을 최신 항목부터 검색하며, 중복은 최신 항목으로 축소됩니다. 전체 화면 대화상자는 선택된 범위에서 전체 프롬프트 기록을 최신 항목부터 검색하며, 중복은 최신 항목으로 축소됩니다: 가장 최근의 프롬프트가 즉시 나타나고, 더 오래된 프롬프트의 일치 항목은 Claude Code가 나머지 기록을 로드할 때 채워집니다. 일치하는 프롬프트는 검색어가 강조 표시되어 표시되므로, 이전 입력을 찾아 재사용할 수 있습니다.

304 

305일치 항목을 수락하거나 검색을 취소하면 Claude Code가 여전히 기록을 로드 중이더라도 즉시 적용됩니다.305일치 항목을 수락하거나 검색을 취소하면 Claude Code가 여전히 기록을 로드 중이더라도 즉시 적용됩니다.

306 306 

307## 백그라운드 Bash 명령어307## 백그라운드 Bash 명령어

39 39 

40JetBrains 마켓플레이스에서 [Claude Code 플러그인](https://plugins.jetbrains.com/plugin/27310-claude-code-beta-)을 설치하고 IDE를 다시 시작합니다.40JetBrains 마켓플레이스에서 [Claude Code 플러그인](https://plugins.jetbrains.com/plugin/27310-claude-code-beta-)을 설치하고 IDE를 다시 시작합니다.

41 41 

42> [!NOTE]

43>

44> JetBrains 마켓플레이스는 Anthropic이 보증, 유지 관리 또는 감사하지 않는 서드파티 소프트웨어입니다. Anthropic은 Claude Code 플러그인을 JetBrains 마켓플레이스에 게시하기 위해 제출합니다.

45 

42`claude`가 IDE가 찾을 수 없는 위치에 설치된 경우 플러그인의 [Claude 명령 설정](#general-settings)에서 전체 경로를 설정합니다.46`claude`가 IDE가 찾을 수 없는 위치에 설치된 경우 플러그인의 [Claude 명령 설정](#general-settings)에서 전체 경로를 설정합니다.

43 47 

44Claude Code는 모든 유료 Claude 구독(Pro, Max, Ultra, Team 또는 Enterprise) 또는 Claude Console 계정과 함께 작동하며, API 키가 필요하지 않습니다. `claude`를 처음 실행할 때 [로그인](https://code.claude.com/docs/ko/authentication.md#log-in-to-claude-code)하라는 메시지가 표시됩니다.48Claude Code는 모든 유료 Claude 구독(Pro, Max, Ultra, Team 또는 Enterprise) 또는 Claude Console 계정과 함께 작동하며, API 키가 필요하지 않습니다. `claude`를 처음 실행할 때 [로그인](https://code.claude.com/docs/ko/authentication.md#log-in-to-claude-code)하라는 메시지가 표시됩니다.

278 278 

279v2.1.305 이상에서는 도구 검색을 명시하거나 Claude Code가 원인을 인식하지 못하는 `400` 또는 `422` 이후에, Claude Code가 [`defer_loading` 필드와 `tool_reference` 블록](https://code.claude.com/docs/ko/mcp#tool-search-through-a-gateway) 없이 요청을 다시 전송합니다. 재시도가 성공하면 해당 대화의 이후 요청에서도 이들이 생략됩니다.279v2.1.305 이상에서는 도구 검색을 명시하거나 Claude Code가 원인을 인식하지 못하는 `400` 또는 `422` 이후에, Claude Code가 [`defer_loading` 필드와 `tool_reference` 블록](https://code.claude.com/docs/ko/mcp#tool-search-through-a-gateway) 없이 요청을 다시 전송합니다. 재시도가 성공하면 해당 대화의 이후 요청에서도 이들이 생략됩니다.

280 280 

281게이트웨이를 변경하지 않아도 개발자의 요청은 계속 작동하며, MCP 도구는 미리 로드됩니다. Claude Code가 도구 검색을 다시 시도하면, 게이트웨이는 또 다른 거부된 요청과 그 재시도를 받습니다. 도구 검색 자체를 위해서는 Claude Code는 게이트웨이가 `defer_loading` 필드와 `tool_reference` 블록을 해당 `anthropic-beta` 값과 함께 전달할 것으로 기대합니다.281개발자의 요청은 게이트웨이에서 아무런 변경 없이 계속 작동하며, MCP 도구는 미리 로드됩니다. Claude Code가 도구 검색을 다시 시도하면 게이트웨이에서는 거부된 요청과 그에 이어지는 재시도를 다시 확인할 수 있습니다. 도구 검색 자체를 위해 Claude Code는 게이트웨이가 `defer_loading` 필드와 `tool_reference` 블록을 해당 `anthropic-beta` 값과 함께 전달할 것으로 기대합니다.

282 282 

283### 사전 릴리스 기능 비활성화283### 사전 릴리스 기능 비활성화

284 284 

171* 샌드박스 바이너리 경로 `sandbox.bwrapPath` 및 `sandbox.socatPath`171* 샌드박스 바이너리 경로 `sandbox.bwrapPath` 및 `sandbox.socatPath`

172* 샌드박스 `ripgrep` 바이너리, [`sandbox.ripgrep`](https://code.claude.com/docs/ko/settings-reference#sandbox-ripgrep)172* 샌드박스 `ripgrep` 바이너리, [`sandbox.ripgrep`](https://code.claude.com/docs/ko/settings-reference#sandbox-ripgrep)

173* `sandbox.filesystem.disabled` 및 `sandbox.network.strictAllowlist`173* `sandbox.filesystem.disabled` 및 `sandbox.network.strictAllowlist`

174* [`useAutoModeDuringPlan`](https://code.claude.com/docs/ko/settings-reference#useautomodeduringplan), [`syncClaudeAiSkills`](https://code.claude.com/docs/ko/settings-reference#syncclaudeaiskills), [`syncClaudeAiPlugins`](https://code.claude.com/docs/ko/settings-reference#syncclaudeaiplugins): 어떤 관리자 소스에서든 `false`이면 해당 동작이 꺼집니다. 개발자의 사용자 설정이나 로컬 설정에 있는 `false`도 이를 끕니다. 각 키는 거부만 할 수 있습니다174* [`useAutoModeDuringPlan`](https://code.claude.com/docs/ko/settings-reference#useautomodeduringplan), [`syncClaudeAiSkills`](https://code.claude.com/docs/ko/settings-reference#syncclaudeaiskills), [`syncClaudeAiPlugins`](https://code.claude.com/docs/ko/settings-reference#syncclaudeaiplugins): 어떤 관리자 소스에서든 `false`이면 해당 동작이 꺼집니다. 각 키는 거부만 할 수 있습니다.

175 * 개발자의 사용자 설정이나 로컬 설정에 있는 `false`도 이를 끕니다

176 * `useAutoModeDuringPlan`의 경우, 개발자가 [`--setting-sources`](https://code.claude.com/docs/ko/cli-reference#cli-flags)와 같은 옵션으로 제외한 사용자 또는 로컬 파일에 있는 `false`는 반영되지 않습니다. 제외된 파일을 무시하려면 Claude Code v2.1.314 이상이 필요합니다

175* [`enableArtifact`](https://code.claude.com/docs/ko/settings-reference#enableartifact): 어떤 관리자 소스에서든 `false`이면 [Artifact 도구](https://code.claude.com/docs/ko/artifacts.md)가 꺼집니다. 개발자의 사용자, 프로젝트 또는 로컬 설정에 있는 `false`도 이를 끄며, 어떤 소스도 이를 다시 켤 수 없습니다. [여전히 반영되는 하위 수준 값](https://code.claude.com/docs/ko/settings.md#exceptions-to-managed-settings-precedence)을 참조하세요. Claude Code v2.1.242 이상이 필요합니다177* [`enableArtifact`](https://code.claude.com/docs/ko/settings-reference#enableartifact): 어떤 관리자 소스에서든 `false`이면 [Artifact 도구](https://code.claude.com/docs/ko/artifacts.md)가 꺼집니다. 개발자의 사용자, 프로젝트 또는 로컬 설정에 있는 `false`도 이를 끄며, 어떤 소스도 이를 다시 켤 수 없습니다. [여전히 반영되는 하위 수준 값](https://code.claude.com/docs/ko/settings.md#exceptions-to-managed-settings-precedence)을 참조하세요. Claude Code v2.1.242 이상이 필요합니다

176* [`maxEffortLevel`](https://code.claude.com/docs/ko/settings-reference#maxeffortlevel): 모든 관리자 소스 중 가장 낮은 상한이 적용됩니다. 개발자가 자신의 설정이나 `--settings`로 더 낮은 상한을 설정하면 Claude Code는 그 값을 적용합니다. 어떤 소스도 상한을 높일 수 없습니다. Claude Code v2.1.267 이상이 필요합니다178* [`maxEffortLevel`](https://code.claude.com/docs/ko/settings-reference#maxeffortlevel): 모든 관리자 소스 중 가장 낮은 상한이 적용됩니다. 개발자가 자신의 설정이나 `--settings`로 더 낮은 상한을 설정하면 Claude Code는 그 값을 적용합니다. 어떤 소스도 상한을 높일 수 없습니다. Claude Code v2.1.267 이상이 필요합니다

177* 모든 계층에서 `attribution` 또는 deprecated된 `includeCoAuthoredBy`에 있는 커밋 트레일러 옵트아웃179* 모든 계층에서 `attribution` 또는 deprecated된 `includeCoAuthoredBy`에 있는 커밋 트레일러 옵트아웃

6134. 설정: 모델에 대해 저장한 수준 또는 [`effortLevel`](https://code.claude.com/docs/ko/settings-reference#effortlevel) 키이며, 둘 사이 및 설정 파일 간의 우선순위는 [`modelSettings`](https://code.claude.com/docs/ko/settings-reference#modelsettings)에 명시되어 있습니다6134. 설정: 모델에 대해 저장한 수준 또는 [`effortLevel`](https://code.claude.com/docs/ko/settings-reference#effortlevel) 키이며, 둘 사이 및 설정 파일 간의 우선순위는 [`modelSettings`](https://code.claude.com/docs/ko/settings-reference#modelsettings)에 명시되어 있습니다

6145. 모델의 기본 effort: effort를 지원하는 모든 모델에서 `high`이며, 단 Opus 5.5, Sonnet 5.5 및 Haiku 5.5는 `medium`, Opus 4.7은 `xhigh`가 기본값입니다. 조직이 [조직 기본 모델](#organization-default-model)에 대한 기본 effort 수준을 설정하면, 해당 모델을 실행할 때 그 수준이 기본값입니다.6145. 모델의 기본 effort: effort를 지원하는 모든 모델에서 `high`이며, 단 Opus 5.5, Sonnet 5.5 및 Haiku 5.5는 `medium`, Opus 4.7은 `xhigh`가 기본값입니다. 조직이 [조직 기본 모델](#organization-default-model)에 대한 기본 effort 수준을 설정하면, 해당 모델을 실행할 때 그 수준이 기본값입니다.

615 615 

616자동 모델 폴백 후 적용되는 수준은 [폴백 후 effort 수준](#effort-level-after-a-fallback)을 참조하세요.616자동 모델 폴백 후 적용되는 수준은 [폴백 후 effort 수준](#effort-level-after-a-fallback)을 참조하세요. 서브에이전트 및 팀원의 경우 [서브에이전트 및 팀원의 effort 수준](#effort-level-of-subagents-and-teammates)을 참조하세요.

617 617 

618Opus 5.5는 위의 소스 중 하나가 수준을 설정하지 않으면 `medium`에서 시작하고, 사용자 설정 파일의 최상위 `effortLevel`은 Opus 5.5에 대해 계산되지 않습니다. 해당 키는 Claude Code가 모델별로 수준을 저장하기 전에 `/effort`가 작성한 이전 형식입니다: 이전에 적용된 곳, 즉 Opus 5, Fable 5.1 및 이전 모델에서 계속 적용되며, Opus 5.5 및 이후 릴리스된 모델은 `/effort` 또는 `/model` 선택기로 수준을 선택할 때까지 자신의 기본값에서 시작합니다. 프로젝트, 로컬 또는 관리형 설정의 최상위 `effortLevel` 또는 `--settings`로 전달된 것은 모든 모델에 적용됩니다.618Opus 5.5는 위의 소스 중 하나가 수준을 설정하지 않으면 `medium`에서 시작하고, 사용자 설정 파일의 최상위 `effortLevel`은 Opus 5.5에 대해 계산되지 않습니다. 해당 키는 Claude Code가 모델별로 수준을 저장하기 전에 `/effort`가 작성한 이전 형식입니다: 이전에 적용된 곳, 즉 Opus 5, Fable 5.1 및 이전 모델에서 계속 적용되며, Opus 5.5 및 이후 릴리스된 모델은 `/effort` 또는 `/model` 선택기로 수준을 선택할 때까지 자신의 기본값에서 시작합니다. 프로젝트, 로컬 또는 관리형 설정의 최상위 `effortLevel` 또는 `--settings`로 전달된 것은 모든 모델에 적용됩니다.

619 619 

700 700 

701[`maxEffortLevel`](https://code.claude.com/docs/ko/settings-reference#maxeffortlevel) 또는 [조직 effort 제한](#organization-effort-limits)은 여전히 스킬 또는 서브에이전트가 실행되는 수준을 제한합니다. [관리형 설정](https://code.claude.com/docs/ko/managed-settings.md)에서 `effortLevel`을 설정하면, Claude Code는 [effort 확인 순서](#adjust-effort-level)의 설정 단계에서 적용하고, 사용자는 여전히 `/effort` 또는 `--effort`로 수준을 변경할 수 있습니다. 사용자를 특정 수준 이하로 유지하려면, [`maxEffortLevel`](https://code.claude.com/docs/ko/settings-reference#maxeffortlevel)을 설정하세요.701[`maxEffortLevel`](https://code.claude.com/docs/ko/settings-reference#maxeffortlevel) 또는 [조직 effort 제한](#organization-effort-limits)은 여전히 스킬 또는 서브에이전트가 실행되는 수준을 제한합니다. [관리형 설정](https://code.claude.com/docs/ko/managed-settings.md)에서 `effortLevel`을 설정하면, Claude Code는 [effort 확인 순서](#adjust-effort-level)의 설정 단계에서 적용하고, 사용자는 여전히 `/effort` 또는 `--effort`로 수준을 변경할 수 있습니다. 사용자를 특정 수준 이하로 유지하려면, [`maxEffortLevel`](https://code.claude.com/docs/ko/settings-reference#maxeffortlevel)을 설정하세요.

702 702 

703#### 서브에이전트 및 팀원의 effort 수준

704 

705메인 대화의 모델에서, 자체 `effort`가 없는 [서브에이전트](https://code.claude.com/docs/ko/sub-agents.md#choose-an-effort-level) 또는 [팀원](https://code.claude.com/docs/ko/agent-teams.md#specify-teammates-and-models)은 세션에서 선택하거나 `--effort`로 설정한 수준으로 실행됩니다. 다른 모델에서는 해당 수준이 적용되지 않습니다. 서브에이전트의 수준을 선택하려면 해당 정의에서 `effort`를 설정하세요.

706 

703#### 설정한 effort 수준 확인707#### 설정한 effort 수준 확인

704 708 

705effort 슬라이더는 지원되는 모델이 선택되었을 때 `/model`에 나타납니다. 세션 헤더에 표시되는 수준(예: "with low effort")은 effort 설정에서 온 것이며, Claude가 [아직 이전 수준으로 작업 중](#when-a-new-effort-level-starts)이더라도 마찬가지입니다. 시작 시와 수준을 변경할 때 바닥글에도 세션에 설정된 수준이 잠시 표시됩니다.709effort 슬라이더는 지원되는 모델이 선택되었을 때 `/model`에 나타납니다. 세션 헤더에 표시되는 수준(예: "with low effort")은 effort 설정에서 온 것이며, Claude가 [아직 이전 수준으로 작업 중](#when-a-new-effort-level-starts)이더라도 마찬가지입니다. 시작 시와 수준을 변경할 때 바닥글에도 세션에 설정된 수준이 잠시 표시됩니다.

330 330 

331대화형 CLI 세션에서 상세 베타 트레이싱을 사용하려면 조직이 해당 기능의 허용 목록에 등록되어 있어야 합니다. Agent SDK 및 비대화형 `-p` 세션에는 허용 목록 등록이 필요하지 않습니다.331대화형 CLI 세션에서 상세 베타 트레이싱을 사용하려면 조직이 해당 기능의 허용 목록에 등록되어 있어야 합니다. Agent SDK 및 비대화형 `-p` 세션에는 허용 목록 등록이 필요하지 않습니다.

332 332 

333> [!WARNING]

334>

335> `ENABLE_BETA_TRACING_DETAILED`는 프로덕션 환경이 아닌 디버깅 용도로만 설정하세요. 상세 베타 트레이싱은 내보내기 양이 많으며, 해당 [콘텐츠 속성](#new-context-gates)은 안정적인 스팬 스키마의 일부가 아닙니다.

336 

333| 속성 | 설명 | 게이트 |337| 속성 | 설명 | 게이트 |

334| - | - | - |338| - | - | - |

335| `hook_event` | 훅 이벤트 유형(예: `PreToolUse`) | |339| `hook_event` | 훅 이벤트 유형(예: `PreToolUse`) | |

131 131 

132Claude Code는 세션의 디버그 로그에서 무시된 각 키를 기록합니다.132Claude Code는 세션의 디버그 로그에서 무시된 각 키를 기록합니다.

133 133 

134앱이 공급자 연결을 관리하는 [Claude Desktop](https://code.claude.com/docs/ko/desktop.md) 세션에서, 예를 들어 [타사 공급자](https://code.claude.com/docs/ko/third-party-integrations.md)의 Code 탭 및 Cowork 세션에서 Claude Code는 이러한 변수와 프록시 변수 `HTTP_PROXY`, `HTTPS_PROXY`, 및 `NO_PROXY`를 [관리되는 설정](https://code.claude.com/docs/ko/managed-settings.md) 및 `~/.claude/settings.json`에서만 읽습니다: 저장소의 자체 설정 파일에서는 무시하므로 체크아웃된 저장소는 앱에서 자격 증명이 오는 세션의 TLS 또는 프록시 경로를 리디렉션할 수 없습니다. claude.ai를 통해 로그인한 로컬, SSH 또는 WSL Code 탭 세션에서 앱은 연결을 관리하지 않으며 Claude Code는 모든 터미널 세션처럼 모든 설정 범위에서 이러한 변수를 읽습니다; [클라우드 세션](https://code.claude.com/docs/ko/claude-code-on-the-web.md)은 시작 위치에 관계없이 위의 클라우드 세션 규칙을 따릅니다. v2.1.217 이전에는 앱이 연결을 관리할 때 Claude Code가 모든 설정 파일에서 이러한 변수를 무시했습니다.134앱이 공급자 연결을 관리하는 [Claude Desktop](https://code.claude.com/docs/ko/desktop.md) 세션에서, 예를 들어 [타사 공급자](https://code.claude.com/docs/ko/third-party-integrations.md)의 Code 탭 및 Cowork 세션에서 Claude Code는 `CLAUDE_CODE_OAUTH_SCOPES`를 제외한 이러한 변수와 프록시 변수 `HTTP_PROXY`, `HTTPS_PROXY`, `NO_PROXY`를 [관리형 설정](https://code.claude.com/docs/ko/managed-settings.md) 및 `~/.claude/settings.json`에서만 읽습니다. 저장소의 자체 설정 파일에서는 이를 무시하므로 체크아웃된 저장소는 앱에서 자격 증명이 오는 세션의 TLS 또는 프록시 경로를 리디렉션할 수 없습니다. v2.1.217 이전에는 앱이 연결을 관리할 때 Claude Code가 모든 설정 파일에서 이러한 변수를 무시했습니다.

135 

136claude.ai를 통해 로그인한 로컬, SSH 또는 WSL Code 탭 세션에서는 `CLAUDE_CODE_OAUTH_SCOPES`를 제외하고 이러한 변수와 프록시 변수를 모든 설정 파일에서 설정할 수 있습니다. Desktop은 Code 탭 및 Cowork 세션에서 `CLAUDE_CODE_OAUTH_SCOPES`를 직접 설정하므로 이 변수는 설정할 수 없습니다.

137 

138세션의 실행 환경에서 이미 변수를 설정한 경우 Claude Code는 [설정 파일의 값을 무시](https://code.claude.com/docs/ko/settings-reference.md#how-env-values-interact-with-your-shell)하고 [디버그 로그](https://code.claude.com/docs/ko/debug-your-config.md)에 해당 변수의 이름을 기록합니다. 로컬 세션에서 자체 프록시 또는 인증서 값을 사용하려면 [저장된 로컬 환경에 추가](https://code.claude.com/docs/ko/desktop.md#set-environment-variables-for-local-sessions)합니다. [클라우드 세션](https://code.claude.com/docs/ko/claude-code-on-the-web.md)은 시작 위치에 관계없이 위의 클라우드 세션 규칙을 따릅니다.

135 139 

136## 구성 확인140## 구성 확인

137 141 

383* **서버가 세션을 검토하지 않음**: 응답이 검토 결과 없이 완료되거나, 서버가 이 세션을 검토하지 않는다고 응답합니다. 가장 흔한 원인은 검토 요청이나 결과를 누락시키는 LLM 게이트웨이 또는 프록시, 그리고 아직 서버 측 검사를 지원하지 않는 플랫폼, 리전 또는 자격 증명입니다. Claude Code는 자체 분류기 요청으로 폴백합니다. 이 폴백이 세션의 나머지 기간 동안 유지되면, 해당 요청이 과금되는 계정에서 [분류기 요청 요금에 대한 알림](https://code.claude.com/docs/ko/auto-mode-classifier-billing.md)을 표시합니다.383* **서버가 세션을 검토하지 않음**: 응답이 검토 결과 없이 완료되거나, 서버가 이 세션을 검토하지 않는다고 응답합니다. 가장 흔한 원인은 검토 요청이나 결과를 누락시키는 LLM 게이트웨이 또는 프록시, 그리고 아직 서버 측 검사를 지원하지 않는 플랫폼, 리전 또는 자격 증명입니다. Claude Code는 자체 분류기 요청으로 폴백합니다. 이 폴백이 세션의 나머지 기간 동안 유지되면, 해당 요청이 과금되는 계정에서 [분류기 요청 요금에 대한 알림](https://code.claude.com/docs/ko/auto-mode-classifier-billing.md)을 표시합니다.

384* **서버가 작업에 대한 판정을 내리지 않음**: Claude Code는 검토되지 않은 상태로 실행하는 대신 작업을 거부합니다. 모든 연결에서 이는 검토 결과가 도착하기 전에 응답이 끝나거나, Claude Code가 읽을 수 없는 형식으로 결과가 도착할 때 발생합니다. 응답을 중간에 자르거나 결과를 다시 쓰는 LLM 게이트웨이 또는 프록시가 두 가지 모두의 원인이 될 수 있습니다. Anthropic API에 직접 연결된 경우에는 시간 초과 등으로 해당 작업에 대한 서버 검사가 실패할 때도 발생합니다. [서버가 안전 판정을 반환하지 않음](https://code.claude.com/docs/ko/errors.md#the-server-returned-no-safety-verdict)에서 거부 메시지, 거부가 반복될 때의 동작, 조치 방법을 설명합니다.384* **서버가 작업에 대한 판정을 내리지 않음**: Claude Code는 검토되지 않은 상태로 실행하는 대신 작업을 거부합니다. 모든 연결에서 이는 검토 결과가 도착하기 전에 응답이 끝나거나, Claude Code가 읽을 수 없는 형식으로 결과가 도착할 때 발생합니다. 응답을 중간에 자르거나 결과를 다시 쓰는 LLM 게이트웨이 또는 프록시가 두 가지 모두의 원인이 될 수 있습니다. Anthropic API에 직접 연결된 경우에는 시간 초과 등으로 해당 작업에 대한 서버 검사가 실패할 때도 발생합니다. [서버가 안전 판정을 반환하지 않음](https://code.claude.com/docs/ko/errors.md#the-server-returned-no-safety-verdict)에서 거부 메시지, 거부가 반복될 때의 동작, 조치 방법을 설명합니다.

385 385 

386 [훅](https://code.claude.com/docs/ko/hooks.md#pretooluse-updatedinput-in-auto-mode) 또는 [mod](https://code.claude.com/docs/ko/plugins/mods/overview.md)가 서버 검토 이후에 작업의 입력을 변경하면, Claude Code가 판정 없이 작업을 거부할 수 있습니다. Anthropic API에 직접 연결된 대화형 터미널 및 VS Code 세션에서는 거부 텍스트에 `a hook changed this call's input after auto mode reviewed it`가 포함됩니다. [해당 오류 항목](https://code.claude.com/docs/ko/errors.md#hook-changed-input-after-review)에서 조치 방법을 설명합니다.

387 

386서버 요청을 건너뛰고 항상 Claude Code 자체 분류기 요청을 사용하려면 [`CLAUDE_CODE_AUTO_MODE_SERVER=0`](https://code.claude.com/docs/ko/env-vars)을 설정하십시오. Anthropic API에 직접 연결된 경우 이 변수에는 Claude Code v2.1.281 이상이 필요합니다. 이 환경에서 값을 `1`로 설정하면, `CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1`도 함께 설정하지 않은 한 아직 서버 검토가 적용되지 않은 세션에서 서버 검토가 켜집니다. `CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1`을 설정하고 `CLAUDE_CODE_AUTO_MODE_SERVER`를 설정하지 않으면, [사전 출시 기능 비활성화](https://code.claude.com/docs/ko/llm-gateway-protocol.md#disable-pre-release-capabilities)에 설명된 경우를 제외하고 Claude Code도 서버 요청을 중단합니다.388서버 요청을 건너뛰고 항상 Claude Code 자체 분류기 요청을 사용하려면 [`CLAUDE_CODE_AUTO_MODE_SERVER=0`](https://code.claude.com/docs/ko/env-vars)을 설정하십시오. Anthropic API에 직접 연결된 경우 이 변수에는 Claude Code v2.1.281 이상이 필요합니다. 이 환경에서 값을 `1`로 설정하면, `CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1`도 함께 설정하지 않은 한 아직 서버 검토가 적용되지 않은 세션에서 서버 검토가 켜집니다. `CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1`을 설정하고 `CLAUDE_CODE_AUTO_MODE_SERVER`를 설정하지 않으면, [사전 출시 기능 비활성화](https://code.claude.com/docs/ko/llm-gateway-protocol.md#disable-pre-release-capabilities)에 설명된 경우를 제외하고 Claude Code도 서버 요청을 중단합니다.

387 389 

388### 기본 분류기 모델390### 기본 분류기 모델

557* **차단된 작업**: Claude Code가 알림을 표시하고 `/permissions`의 **Recently blocked** 탭에 작업을 나열하며, 그곳에서 [작업을 승인하여 Claude가 재시도하도록](https://code.claude.com/docs/ko/auto-mode-config.md#review-denials) 할 수 있습니다.559* **차단된 작업**: Claude Code가 알림을 표시하고 `/permissions`의 **Recently blocked** 탭에 작업을 나열하며, 그곳에서 [작업을 승인하여 Claude가 재시도하도록](https://code.claude.com/docs/ko/auto-mode-config.md#review-denials) 할 수 있습니다.

558* **반복된 차단**: 분류기가 작업을 연속 3회 또는 총 20회 차단하면 자동 모드가 일시 중지되고 Claude Code가 다시 확인을 요청합니다. 요청된 작업을 승인하면 자동 모드가 재개됩니다. 차단 횟수를 세는 방식은 [반복 차단 임계값](#repeated-block-thresholds)을 참조하십시오.560* **반복된 차단**: 분류기가 작업을 연속 3회 또는 총 20회 차단하면 자동 모드가 일시 중지되고 Claude Code가 다시 확인을 요청합니다. 요청된 작업을 승인하면 자동 모드가 재개됩니다. 차단 횟수를 세는 방식은 [반복 차단 임계값](#repeated-block-thresholds)을 참조하십시오.

559* **분류기의 판정 없음**: 자동 모드와 별개의 안전 검사가 분류기 자체의 요청을 거부하거나, 분류기의 응답을 파싱할 수 없는 경우, Claude Code는 알림이나 **Recently blocked** 항목 없이 작업을 차단합니다. 각 경우에 표시되는 메시지와 조치 방법은 [Auto mode cannot determine the safety of an action](https://code.claude.com/docs/ko/errors.md#auto-mode-cannot-determine-the-safety-of-an-action)을 참조하십시오.561* **분류기의 판정 없음**: 자동 모드와 별개의 안전 검사가 분류기 자체의 요청을 거부하거나, 분류기의 응답을 파싱할 수 없는 경우, Claude Code는 알림이나 **Recently blocked** 항목 없이 작업을 차단합니다. 각 경우에 표시되는 메시지와 조치 방법은 [Auto mode cannot determine the safety of an action](https://code.claude.com/docs/ko/errors.md#auto-mode-cannot-determine-the-safety-of-an-action)을 참조하십시오.

560* **서버의 판정 없음**: [서버 측 분류기 검토](#server-side-classifier-review)에서 Claude Code는 서버가 판정을 내리지 않은 작업을 거부하며, 판정 없는 응답이 연속 10회 이어지면 턴을 중단합니다. [서버가 안전 판정을 반환하지 않음](https://code.claude.com/docs/ko/errors.md#the-server-returned-no-safety-verdict)을 참조하십시오.562* **서버의 판정 없음**: [서버 측 분류기 검토](#server-side-classifier-review)에서 Claude Code는 서버가 판정을 내리지 않은 작업을 거부하며, 판정 없는 응답이 10번 연속되면 턴을 중지할 수 있습니다. [The server returned no safety verdict](https://code.claude.com/docs/ko/errors.md#the-server-returned-no-safety-verdict)를 참조하십시오.

561* **검사 중 모드 전환**: 분류기 검사가 진행 중일 때 권한 모드를 전환하면, Claude Code는 새 모드에서라면 요청하지 않았을 판정을 폐기합니다. 대신 승인을 요청받거나, [`dontAsk` 모드](#allow-only-pre-approved-tools-with-dontask-mode)에서는 작업이 자동으로 거부됩니다.563* **검사 중 모드 전환**: 분류기 검사가 진행 중일 때 권한 모드를 전환하면, Claude Code는 새 모드에서라면 요청하지 않았을 판정을 폐기합니다. 대신 승인을 요청받거나, [`dontAsk` 모드](#allow-only-pre-approved-tools-with-dontask-mode)에서는 작업이 자동으로 거부됩니다.

562 564 

563#### 반복 차단 임계값565#### 반복 차단 임계값

199 199 

200이 메시지는 Claude에게 기록된 그대로 호출을 한 번 더 실행하도록 지시합니다. 그 호출도 거부된다면 훅이 매번 입력을 변경하고 있는 것이므로, 해당 mod나 훅을 끄거나 자동 모드를 종료하고 호출을 직접 승인해야 합니다.200이 메시지는 Claude에게 기록된 그대로 호출을 한 번 더 실행하도록 지시합니다. 그 호출도 거부된다면 훅이 매번 입력을 변경하고 있는 것이므로, 해당 mod나 훅을 끄거나 자동 모드를 종료하고 호출을 직접 승인해야 합니다.

201 201 

202> [!NOTE]

203>

204> [일부 대화형 터미널 세션 및 VS Code 세션](https://code.claude.com/docs/ko/hooks.md#pretooluse-updatedinput-in-auto-mode)에서는 같은 거부가 `a hook changed this call's input after auto mode reviewed it`이라는 사유로 표시됩니다. 이 경우 반복된 호출에는 mod의 첫 번째 변경 사항이 반영되며 `tool.call` 훅도 여전히 실행되지만, 추가 변경 사항은 적용되지 않습니다. Claude가 응답에서 [자동 모드가 호출을 확인할 수 없었다](https://code.claude.com/docs/ko/errors.md#hook-changed-input-after-review)고 알리지 않는 한 mod를 변경할 필요는 없습니다.

205 

202### 설정의 거부 규칙에 관한 메시지206### 설정의 거부 규칙에 관한 메시지

203 207 

204`tried to lift a deny rule in your settings`와 `the deny rules in your settings could not be checked for this call, so it is refused`는 모두 기본 제공 가드에서 발생하는 메시지입니다.208`tried to lift a deny rule in your settings`와 `the deny rules in your settings could not be checked for this call, so it is refused`는 모두 기본 제공 가드에서 발생하는 메시지입니다.

31>31>

32> 다른 두 기능은 클라우드 대신 사용자의 머신에서 작업을 예약합니다. [데스크톱 예약 작업](https://code.claude.com/docs/ko/desktop-scheduled-tasks.md)과 [`/loop`](https://code.claude.com/docs/ko/scheduled-tasks)입니다. 세 가지 중에서 선택하려면 [예약 옵션 비교](https://code.claude.com/docs/ko/scheduled-tasks.md#compare-scheduling-options)를 참조하십시오.32> 다른 두 기능은 클라우드 대신 사용자의 머신에서 작업을 예약합니다. [데스크톱 예약 작업](https://code.claude.com/docs/ko/desktop-scheduled-tasks.md)과 [`/loop`](https://code.claude.com/docs/ko/scheduled-tasks)입니다. 세 가지 중에서 선택하려면 [예약 옵션 비교](https://code.claude.com/docs/ko/scheduled-tasks.md#compare-scheduling-options)를 참조하십시오.

33 33 

34Team 및 Enterprise Owner는 [**Organization settings > Capabilities > Remote sessions**](https://claude.ai/admin-settings/capabilities)의 **Scheduled tasks (Was Routines)** 토글로 모든 구성원에 대해 예약 작업을 끌 수 있습니다. 토글이 꺼지면 기존 예약 작업의 실행이 중지되고 구성원은 새 예약 작업을 만들 수 없습니다.34Team 및 Enterprise Owner는 [**Organization settings > Capabilities > Remote sessions**](https://claude.ai/admin-settings/capabilities)의 **Scheduled tasks (Was Routines)** 또는 **Routines** 토글로 모든 구성원에 대해 예약 작업을 끌 수 있습니다. 토글이 꺼지면 기존 예약 작업의 실행이 중지되고 구성원은 새 예약 작업을 만들 수 없습니다.

35 35 

36Enterprise 조직에서 [사용자 지정 역할](https://support.claude.com/en/articles/13930452)로 액세스를 관리하는 경우, 예약 작업 권한이 포함된 역할도 필요합니다. Owner는 [**Organization settings > Roles**](https://claude.ai/admin-settings/roles)에서 역할의 **Remote sessions** 섹션에 이 권한을 추가할 수 있습니다.36Enterprise 조직에서 [사용자 지정 역할](https://support.claude.com/en/articles/13930452)로 액세스를 관리하는 경우, 예약 작업 권한이 포함된 역할도 필요합니다. Owner는 [**Organization settings > Roles**](https://claude.ai/admin-settings/roles)에서 역할의 **Remote sessions** 섹션에 이 권한을 추가할 수 있습니다.

37 37 

485* **웹 주소**: `claude.ai/code/routines`485* **웹 주소**: `claude.ai/code/routines`

486* **CLI**: `/schedule`의 별칭인 `/routines`, 명령의 설명, 그리고 작업을 설정하는 동안의 Claude 응답486* **CLI**: `/schedule`의 별칭인 `/routines`, 명령의 설명, 그리고 작업을 설정하는 동안의 Claude 응답

487* **API**: `/fire` 엔드포인트 경로, 베타 헤더, 응답의 `type`, `<routine-fire-payload>` 태그, 그리고 [Trigger a routine through the API](https://platform.claude.com/docs/en/api/claude-code/routines-fire) 참조 페이지487* **API**: `/fire` 엔드포인트 경로, 베타 헤더, 응답의 `type`, `<routine-fire-payload>` 태그, 그리고 [Trigger a routine through the API](https://platform.claude.com/docs/en/api/claude-code/routines-fire) 참조 페이지

488* **조직 설정**: **Scheduled tasks (Was Routines)** 토글488* **조직 설정**: **Scheduled tasks (Was Routines)** 또는 **Routines** 토글

489 489 

490## 문제 해결490## 문제 해결

491 491 

504 504 

505원인이 CLI 로그인 방식이거나 클라우드 세션 안에 있는 것이라면, [claude.ai/code/routines](https://claude.ai/code/routines)에서 여전히 예약 작업을 만들고 관리할 수 있습니다. 이를 위해서는 Pro, Max, Ultra, Team 또는 Enterprise 계정이 필요합니다. 조직에서 예약 작업이나 클라우드 세션이 꺼져 있거나 역할에 포함되어 있지 않으면 웹에서도 만들 수 없습니다.505원인이 CLI 로그인 방식이거나 클라우드 세션 안에 있는 것이라면, [claude.ai/code/routines](https://claude.ai/code/routines)에서 여전히 예약 작업을 만들고 관리할 수 있습니다. 이를 위해서는 Pro, Max, Ultra, Team 또는 Enterprise 계정이 필요합니다. 조직에서 예약 작업이나 클라우드 세션이 꺼져 있거나 역할에 포함되어 있지 않으면 웹에서도 만들 수 없습니다.

506 506 

507### "Routines are disabled by your organization's policy"507### 조직에서 예약 작업이 꺼져 있음

508 508 

509Team 또는 Enterprise 조직의 Owner가 [**Organization settings > Capabilities > Remote sessions**](https://claude.ai/admin-settings/capabilities)의 **Scheduled tasks (Was Routines)** 토글을 껐을 가능성이 높습니다. Claude Code v2.1.227 이상에서는 같은 토글이 CLI의 `/schedule`도 숨깁니다. 이는 서버 측 조직 설정이므로 로컬 구성으로 재정의할 수 없습니다. Owner에게 조직의 예약 작업을 다시 켜 달라고 요청하십시오.509조직에서 클라우드 예약 작업이 꺼져 있으며, 로컬 구성에서는 이를 변경할 수 없습니다. Team 또는 Enterprise Owner에게 [**Organization settings > Capabilities > Remote sessions**](https://claude.ai/admin-settings/capabilities)에서 **Scheduled tasks (Was Routines)** 또는 **Routines** 토글을 켤 수 있는지 문의하십시오.

510 510 

511### "The last run" 경고511### "The last run" 경고

512 512 

1074* **파일시스템 권한 상승**: 과도하게 광범위한 파일시스템 쓰기 권한은 권한 상승 공격을 가능하게 할 수 있습니다. `$PATH`의 실행 파일을 포함하는 디렉토리, 시스템 구성 디렉토리 또는 `.bashrc` 또는 `.zshrc`와 같은 사용자 셸 구성 파일에 대한 쓰기를 허용하면 다른 사용자 또는 시스템 프로세스가 이러한 파일에 액세스할 때 다른 보안 컨텍스트에서 코드 실행으로 이어질 수 있습니다.1074* **파일시스템 권한 상승**: 과도하게 광범위한 파일시스템 쓰기 권한은 권한 상승 공격을 가능하게 할 수 있습니다. `$PATH`의 실행 파일을 포함하는 디렉토리, 시스템 구성 디렉토리 또는 `.bashrc` 또는 `.zshrc`와 같은 사용자 셸 구성 파일에 대한 쓰기를 허용하면 다른 사용자 또는 시스템 프로세스가 이러한 파일에 액세스할 때 다른 보안 컨텍스트에서 코드 실행으로 이어질 수 있습니다.

1075* **Linux 샌드박스 강도**: Linux 구현은 강력한 파일시스템 및 네트워크 격리를 제공하지만 권한 있는 네임스페이스 없이 Docker 환경 내에서 작동할 수 있도록 하는 `enableWeakerNestedSandbox` 모드를 포함합니다. 이 옵션은 보안을 상당히 약화시키며 추가 격리가 다른 방식으로 적용되는 경우에만 사용해야 합니다.1075* **Linux 샌드박스 강도**: Linux 구현은 강력한 파일시스템 및 네트워크 격리를 제공하지만 권한 있는 네임스페이스 없이 Docker 환경 내에서 작동할 수 있도록 하는 `enableWeakerNestedSandbox` 모드를 포함합니다. 이 옵션은 보안을 상당히 약화시키며 추가 격리가 다른 방식으로 적용되는 경우에만 사용해야 합니다.

1076* **macOS의 Apple Events**: macOS 샌드박스는 기본적으로 Apple Events를 차단합니다. `allowAppleEvents` 설정은 이 제한을 해제하여 `open` 및 `osascript`와 같은 도구가 작동하지만 코드 실행 격리를 제거합니다. 샌드박싱된 명령은 사용자 프롬프트 없이 다른 애플리케이션을 샌드박싱되지 않은 상태로 시작할 수 있으며 실행 중인 애플리케이션에 AppleScript 명령을 보낼 수 있습니다. 이는 앱별 macOS 자동화 동의 프롬프트(TCC)의 적용을 받습니다. 이는 사용자, 관리 또는 CLI 설정에서만 적용됩니다. 프로젝트 설정은 이를 활성화할 수 없습니다.1076* **macOS의 Apple Events**: macOS 샌드박스는 기본적으로 Apple Events를 차단합니다. `allowAppleEvents` 설정은 이 제한을 해제하여 `open` 및 `osascript`와 같은 도구가 작동하지만 코드 실행 격리를 제거합니다. 샌드박싱된 명령은 사용자 프롬프트 없이 다른 애플리케이션을 샌드박싱되지 않은 상태로 시작할 수 있으며 실행 중인 애플리케이션에 AppleScript 명령을 보낼 수 있습니다. 이는 앱별 macOS 자동화 동의 프롬프트(TCC)의 적용을 받습니다. 이는 사용자, 관리 또는 CLI 설정에서만 적용됩니다. 프로젝트 설정은 이를 활성화할 수 없습니다.

1077* **macOS의 Mach 및 XPC 서비스**: 샌드박싱된 명령은 [`network.allowMachLookup`](https://code.claude.com/docs/ko/settings-reference#sandbox-network-allowmachlookup)에 나열한 각 서비스에 샌드박스 외부로 접근할 수 있으며, 샌드박스는 해당 서비스가 그 명령을 위해 수행하는 작업을 제한하지 않습니다.

1077* **Linux 및 WSL2의 사용자 네임스페이스**: 기본적으로 샌드박싱된 명령은 사용자 네임스페이스를 생성할 수 없습니다. [`allowNestedUserNamespaces`](https://code.claude.com/docs/ko/settings-reference#sandbox-allownestedusernamespaces)를 `true`로 설정하면 보안 경계를 끄게 됩니다. 샌드박싱된 명령의 코드가 결국 샌드박스 외부에서 실행될 수 있습니다. 이 설정을 켜기 전에 [Linux에서 샌드박스 내 Chromium 또는 rootless Podman이 실패하는 경우](#chromium-or-rootless-podman-fails-inside-the-sandbox-on-linux)의 경고를 읽습니다.1078* **Linux 및 WSL2의 사용자 네임스페이스**: 기본적으로 샌드박싱된 명령은 사용자 네임스페이스를 생성할 수 없습니다. [`allowNestedUserNamespaces`](https://code.claude.com/docs/ko/settings-reference#sandbox-allownestedusernamespaces)를 `true`로 설정하면 보안 경계를 끄게 됩니다. 샌드박싱된 명령의 코드가 결국 샌드박스 외부에서 실행될 수 있습니다. 이 설정을 켜기 전에 [Linux에서 샌드박스 내 Chromium 또는 rootless Podman이 실패하는 경우](#chromium-or-rootless-podman-fails-inside-the-sandbox-on-linux)의 경고를 읽습니다.

1078 1079 

1079### 범위1080### 범위

16 16 

17## 래퍼 스크립트17## 래퍼 스크립트

18 18 

19각 세션이 러너가 자체적으로 수행할 수 없는 설정이 필요할 때 래퍼 스크립트를 사용합니다. 세션 작성자로 범위가 지정된 단기 자격 증명 프로비저닝, 환경별 비밀 내보내기, 언어 도구 체인 준비, 또는 자식 프로세스 주변의 리소스 제한 적용입니다. 러너는 세션당 한 번 Claude Code 바이너리 대신 래퍼를 시작합니다. `$CLAUDE_RUNNER_CLAUDE_BIN`(러너 자체의 바이너리)으로 `exec`하여 래퍼를 종료하면 신호와 종료 코드가 올바르게 전파됩니다.19각 세션에 러너가 자체적으로 수행할 수 없는 설정이 필요할 때 래퍼 스크립트를 사용합니다:

20 

21* 세션 작성자로 범위가 지정된 단기 자격 증명 프로비저닝

22* 환경별 비밀 내보내기

23* 언어 도구 체인 준비

24* 자식 프로세스 주변의 리소스 제한 적용

25 

26러너는 세션이 재개되거나 다시 대기열에 추가될 때를 포함하여 세션을 시작할 때마다 Claude Code 바이너리 대신 래퍼를 시작합니다. `$CLAUDE_RUNNER_CLAUDE_BIN`(러너 자체의 바이너리)으로 `exec`하여 래퍼를 종료하면 신호와 종료 코드가 올바르게 전파됩니다.

20 27 

21러너를 시작할 때 `--exec-path` 또는 `SELF_HOSTED_RUNNER_EXEC_PATH`를 래퍼로 지정하고, [빠른 시작](https://code.claude.com/docs/ko/self-hosted-environments-quickstart.md#set-up-manually)에서 설명한 대로 `<writable-dir>`을 바꿉니다:28러너를 시작할 때 `--exec-path` 또는 `SELF_HOSTED_RUNNER_EXEC_PATH`를 래퍼로 지정하고, [빠른 시작](https://code.claude.com/docs/ko/self-hosted-environments-quickstart.md#set-up-manually)에서 설명한 대로 `<writable-dir>`을 바꿉니다:

22 29 

139 146 

140### checkout147### checkout

141 148 

142저장소마다 한 번씩, 러너의 기본 제공 clone 및 fetch 대신 실행됩니다. 이 훅을 사용하여 HTTPS 또는 SSH로 접근하는 read-through 미러에서 clone하거나, 아카이브에서 작업 트리를 준비하거나, 세션별 git 인증을 적용할 수 있습니다. 러너는 다음 변수를 설정하며, 표에 나열되지 않은 다른 `CLAUDE_RUNNER_` 변수를 설정할 수도 있습니다.149러너가 세션을 시작할 때마다(세션이 재개되거나 다시 대기열에 들어가는 경우 포함) 저장소마다, 러너의 기본 제공 clone 및 fetch 대신 실행됩니다. 이 훅을 사용하여 HTTPS 또는 SSH로 접근하는 read-through 미러에서 clone하거나, 아카이브에서 작업 트리를 준비하거나, 세션별 git 인증을 적용할 수 있습니다.

150 

151러너는 다음 변수를 설정하며, 표에 나열되지 않은 다른 `CLAUDE_RUNNER_` 변수를 설정할 수도 있습니다.

143 152 

144| 변수 | 설명 |153| 변수 | 설명 |

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

179 188 

180### post-session189### post-session

181 190 

182세션마다 한 번씩, Claude Code 자식 프로세스가 종료된 후 러너가 워크스페이스를 해체하기 전에 실행됩니다. 이 훅은 커밋되지 않은 작업을 저장할 수 있는 유일한 기회입니다. `--capacity`가 1보다 크면 러너는 훅이 반환된 직후 세션별 워크트리를 삭제하고, `--capacity 1`에서는 재사용되는 [표준 clone](https://code.claude.com/docs/ko/self-hosted-environments-deploy.md#reuse-a-pre-warmed-checkout)이 다음 세션 시작 시 hard reset되므로, 어느 경우에도 커밋되지 않은 추적 변경 사항은 남지 않습니다. 일반적인 용도는 커밋되지 않은 변경 사항의 스냅샷 브랜치를 push하거나, 로그를 보관하거나, 자체 시스템에 세션 종료 이벤트를 보내는 것입니다.191Claude Code 자식 프로세스가 종료된 후 러너가 워크스페이스를 해체하기 전에 실행됩니다. 커밋되지 않은 추적 변경 사항은 어느 경우에도 남지 않으므로, 이 훅은 커밋되지 않은 작업을 저장할 수 있는 유일한 기회입니다.

192 

193* **`--capacity`가 1보다 큰 경우**: 러너는 훅이 반환된 직후 세션별 워크트리를 삭제합니다

194* **`--capacity 1`인 경우**: 재사용되는 [표준 clone](https://code.claude.com/docs/ko/self-hosted-environments-deploy.md#reuse-a-pre-warmed-checkout)이 다음 세션 시작 시 hard reset됩니다

195 

196일반적인 용도는 커밋되지 않은 변경 사항의 스냅샷 브랜치를 push하거나, 로그를 보관하거나, 자체 시스템에 세션 종료 이벤트를 보내는 것입니다.

183 197 

184이 훅은 자식 프로세스가 생성된 모든 세션 종료 시점에 원인과 관계없이 실행됩니다. 아래의 `CLAUDE_RUNNER_EXIT_REASON` 값이 각 경우를 나열합니다. VM 선점이나 전원 손실처럼 러너가 갑자기 종료되면 훅이 실행될 수 없습니다. 갑작스러운 종료에 대한 보장이 필요하다면 대신 Claude Code `PostToolUse` 훅을 사용하여 세션 내부에서 주기적으로 스냅샷을 만드십시오. 러너는 다음을 설정합니다.198이 훅은 자식 프로세스가 생성된 모든 세션 종료 시점에 원인과 관계없이 실행됩니다. 아래의 `CLAUDE_RUNNER_EXIT_REASON` 값이 각 경우를 나열합니다. VM 선점이나 전원 손실처럼 러너가 갑자기 종료되면 훅이 실행될 수 없습니다. 갑작스러운 종료에 대한 보장이 필요하다면 대신 Claude Code `PostToolUse` 훅을 사용하여 세션 내부에서 주기적으로 스냅샷을 만드십시오. 러너는 다음을 설정합니다.

185 199 

275 289 

276### command290### command

277 291 

278세션마다 한 번씩 checkout 후에 기본 제공 자식 프로세스 생성 대신 실행됩니다. 이 훅은 [래퍼 스크립트](#wrapper-scripts)와 동일한 환경을 받으며, 같은 방식으로 `"$CLAUDE_RUNNER_CLAUDE_BIN"`으로 `exec`해야 합니다. 모든 사용자 정의를 하나의 hooks 디렉터리에 유지하려면 `command` 훅을 사용하고, 래퍼가 다른 곳에 있다면 `--exec-path`를 사용하십시오. `--exec-path`도 설정되어 있으면 플래그가 우선하며 `command` 훅은 무시됩니다.292세션이 시작되거나 재개될 때마다 checkout 후에 기본 제공 자식 프로세스 생성 대신 실행됩니다. 이 훅은 [래퍼 스크립트](#wrapper-scripts)와 동일한 환경을 받으며, 같은 방식으로 `"$CLAUDE_RUNNER_CLAUDE_BIN"`으로 `exec`해야 합니다. 모든 사용자 정의를 하나의 hooks 디렉터리에 유지하려면 `command` 훅을 사용하고, 래퍼가 다른 곳에 있다면 `--exec-path`를 사용하십시오. `--exec-path`도 설정되어 있으면 플래그가 우선하며 `command` 훅은 무시됩니다.

279 293 

280항상 PATH에서 찾은 `claude`가 아니라 러너 자체의 바이너리를 `exec`하십시오. 그렇지 않으면 [버전 고정](https://code.claude.com/docs/ko/self-hosted-environments-deploy.md#pin-the-version)이 무력화됩니다.294항상 PATH에서 찾은 `claude`가 아니라 러너 자체의 바이너리를 `exec`하십시오. 그렇지 않으면 [버전 고정](https://code.claude.com/docs/ko/self-hosted-environments-deploy.md#pin-the-version)이 무력화됩니다.

281 295 

523 537 

524* **메타데이터 엔드포인트**: 세션의 [클라우드 메타데이터 엔드포인트](https://code.claude.com/docs/ko/self-hosted-environments-deploy.md#harden-your-deployment) 접근을 완전히 거부하면, 인스턴스 프로필처럼 이 엔드포인트에서 제공되는 자격 증명도 Claude Code에 도달하지 않습니다. Amazon EKS의 IAM Roles for Service Accounts(IRSA)나 Workload Identity Federation 자격 증명 파일 같은 파일 기반 웹 ID는 이 엔드포인트에 의존하지 않습니다.538* **메타데이터 엔드포인트**: 세션의 [클라우드 메타데이터 엔드포인트](https://code.claude.com/docs/ko/self-hosted-environments-deploy.md#harden-your-deployment) 접근을 완전히 거부하면, 인스턴스 프로필처럼 이 엔드포인트에서 제공되는 자격 증명도 Claude Code에 도달하지 않습니다. Amazon EKS의 IAM Roles for Service Accounts(IRSA)나 Workload Identity Federation 자격 증명 파일 같은 파일 기반 웹 ID는 이 엔드포인트에 의존하지 않습니다.

525* **갱신**: 세션이 자격 증명보다 오래 지속될 수 있으므로, 파일 기반 웹 ID처럼 스스로 갱신되는 방법을 사용하십시오539* **갱신**: 세션이 자격 증명보다 오래 지속될 수 있으므로, 파일 기반 웹 ID처럼 스스로 갱신되는 방법을 사용하십시오

526* **래퍼 스크립트**: 러너는 [래퍼 스크립트](#provision-credentials-scoped-to-the-session-creator)를 세션당 한 번 시작하므로, 래퍼 스크립트가 내보내는 자격 증명은 갱신되지 않습니다. Claude Code는 환경에서 AWS 자격 증명을 읽으므로, 래퍼가 이미 다른 작업을 위해 AWS 자격 증명을 내보내고 있다면 Claude Code가 그 자격 증명으로 모델 요청에 서명할 수 있습니다.540* **래퍼 스크립트**: [래퍼 스크립트](#provision-credentials-scoped-to-the-session-creator)가 내보내는 자격 증명 값은 Claude Code가 실행되는 동안 갱신되지 않으므로, 긴 세션에는 스스로 갱신되는 방법을 사용하십시오. Claude Code는 환경에서 AWS 자격 증명을 읽으므로, 래퍼가 이미 다른 작업을 위해 AWS 자격 증명을 내보내고 있다면 Claude Code가 그 자격 증명으로 모델 요청에 서명할 수 있습니다.

527 541 

528**3. 러너 환경에 하나의 제공업체 변수 설정하기**542**3. 러너 환경에 하나의 제공업체 변수 설정하기**

529 543 

827 827 

828### 일부 세션이 유휴 상태로 계산되지 않음828### 일부 세션이 유휴 상태로 계산되지 않음

829 829 

830백그라운드 작업을 보유한 세션이 완료되지 않으면 유휴 상태로 계산되지 않으므로 `--release-idle-session-min`은 해당 세션의 슬롯을 해제하지 않습니다. 실행 중인 도구 호출 내에서 요청된 승인을 기다리는 세션도 유휴 상태로 계산되지 않습니다. 항상 `--kill-session-after-min`을 함께 설정하여 어떤 세션도 슬롯을 무한정 보유할 수 없도록 하는 하드 백스톱으로 사용합니다.830계속 실행되는 백그라운드 작업을 보유한 세션은 유휴 상태로 계산되지 않으므로 `--release-idle-session-min`은 해당 세션의 슬롯을 해제하지 않습니다. 실행 중인 도구 호출 내에서 요청된 승인을 기다리는 세션도 유휴 상태로 계산되지 않습니다. 하드 백스톱으로 `--kill-session-after-min`을 함께 설정합니다.

831 831 

832`--kill-session-after-min`은 폭주 세션에 대한 백스톱입니다. v2.1.260 이상의 러너에서 제한에 도달한 세션은 즉시 종료되지 않습니다. 러너는 기본값 15분의 유예 기간을 제공하며, [`SELF_HOSTED_RUNNER_MAX_LIFETIME_GRACE_MS`](https://code.claude.com/docs/ko/self-hosted-environments-reference#environment-variable-only-settings)로 변경할 수 있습니다:832`--kill-session-after-min`은 폭주 세션에 대한 백스톱입니다. v2.1.260 이상의 러너에서 제한에 도달한 세션은 즉시 종료되지 않습니다. 러너는 기본값 15분의 유예 기간을 제공하며, [`SELF_HOSTED_RUNNER_MAX_LIFETIME_GRACE_MS`](https://code.claude.com/docs/ko/self-hosted-environments-reference#environment-variable-only-settings)로 변경할 수 있습니다:

833 833 

153}153}

154```154```

155 155 

156사용자 정의 프로브에서 `last_poll_age_ms`를 생존 신호로 사용하세요. 무한정 증가하는 값은 폴 루프가 고착되었음을 나타냅니다. `last_poll_at` 및 `last_poll_age_ms` 모두 첫 번째 폴이 완료될 때까지 `null`입니다.156`last_poll_age_ms`에 대해 경고를 설정하되, 생존성 프로브에는 사용하지 마세요. 생존성 프로브는 HTTP 상태 코드를 기준으로 유지하세요. 이 값은 마지막으로 성공한 폴 이후 경과한 시간이므로, 러너가 Anthropic에 연결할 수 없는 동안에도 증가합니다. `last_poll_at` 및 `last_poll_age_ms` 모두 첫 번째 폴이 성공할 때까지 `null`입니다. 처음부터 실패하는 폴을 포착하려면 [Prometheus 메트릭](#prometheus-metrics)에 나열된 `claude_code_self_hosted_runner_poll_errors_total`에 대해서도 경고를 설정하세요.

157 157 

158상태 포트에서 제공되는 오케스트레이터 자체의 `/healthz`는 항상 `200`을 반환합니다. 본문은 가장 최근 폴이 성공했는지 여부를 보고하는 `connected` 필드와 `queue_counts`의 상태별 스폰 큐 수를 전달합니다. `connected`가 `false`인 이유를 확인하려면 최상위 `last_error` 필드를 읽으세요. 이 필드는 폴이 성공할 때마다 `null`로 재설정됩니다. 상태 코드가 아닌 `connected`에 준비 및 경고를 게이트하세요.158상태 포트에서 제공되는 오케스트레이터 자체의 `/healthz`는 항상 `200`을 반환합니다. 본문은 가장 최근 폴이 성공했는지 여부를 보고하는 `connected` 필드와 `queue_counts`의 상태별 스폰 큐 수를 전달합니다. `connected`가 `false`인 이유를 확인하려면 최상위 `last_error` 필드를 읽으세요. 이 필드는 폴이 성공할 때마다 `null`로 재설정됩니다. 상태 코드가 아닌 `connected`에 준비 및 경고를 게이트하세요.

159 159 

313| [`autoMode.classifyAllShell`](https://code.claude.com/docs/ko/settings-reference#automode-classifyallshell) | `~/.claude/settings.json` 또는 `--settings`의 `true` | 관리형 소스가 `false`를 설정할 때도 준수됩니다 |313| [`autoMode.classifyAllShell`](https://code.claude.com/docs/ko/settings-reference#automode-classifyallshell) | `~/.claude/settings.json` 또는 `--settings`의 `true` | 관리형 소스가 `false`를 설정할 때도 준수됩니다 |

314| [`remoteControlAtStartup`](https://code.claude.com/docs/ko/settings-reference#remotecontrolatstartup) | `.claude/settings.json` 또는 `.claude/settings.local.json`의 `false` | 관리형 소스가 `true`를 설정할 때도 준수됩니다. 프로젝트 또는 로컬 `true`는 무시됩니다 |314| [`remoteControlAtStartup`](https://code.claude.com/docs/ko/settings-reference#remotecontrolatstartup) | `.claude/settings.json` 또는 `.claude/settings.local.json`의 `false` | 관리형 소스가 `true`를 설정할 때도 준수됩니다. 프로젝트 또는 로컬 `true`는 무시됩니다 |

315| [`crossSessionInbound`](https://code.claude.com/docs/ko/settings-reference#crosssessioninbound) | `.claude/settings.json` 또는 `.claude/settings.local.json`의 더 엄격한 값, `accept` \< `hold` \< `refuse` 사다리에서 | 관리형, `--settings`, 및 사용자 값보다 준수됩니다. 더 엄격하지 않은 프로젝트 또는 로컬 값은 무시됩니다 |315| [`crossSessionInbound`](https://code.claude.com/docs/ko/settings-reference#crosssessioninbound) | `.claude/settings.json` 또는 `.claude/settings.local.json`의 더 엄격한 값, `accept` \< `hold` \< `refuse` 사다리에서 | 관리형, `--settings`, 및 사용자 값보다 준수됩니다. 더 엄격하지 않은 프로젝트 또는 로컬 값은 무시됩니다 |

316| [`useAutoModeDuringPlan`](https://code.claude.com/docs/ko/settings-reference#useautomodeduringplan) | 모든 관리형 소스, `--settings`, `~/.claude/settings.json`, 또는 `.claude/settings.local.json`의 `false` | 승리한 관리형 소스가 `true`를 설정할 때도 준수됩니다. `.claude/settings.json`의 `false`는 무시됩니다 |316| [`useAutoModeDuringPlan`](https://code.claude.com/docs/ko/settings-reference#useautomodeduringplan) | 모든 관리형 소스, `--settings`, `~/.claude/settings.json`, 또는 `.claude/settings.local.json`의 `false` | 승리한 관리형 소스가 `true`를 설정할 때도 준수됩니다. `.claude/settings.json`의 `false`는 무시됩니다. 시작 시 제외하는 파일에 대해서는 [해당 키의 항목](https://code.claude.com/docs/ko/settings-reference.md#useautomodeduringplan)을 참조하세요 |

317| [`syncClaudeAiSkills`](https://code.claude.com/docs/ko/settings-reference#syncclaudeaiskills) | 모든 관리형 소스, `--settings`, `~/.claude/settings.json`, 또는 `.claude/settings.local.json`의 `false` | 승리한 관리형 소스가 `true`를 설정할 때도 준수됩니다. `.claude/settings.json`의 `false`는 무시됩니다 |317| [`syncClaudeAiSkills`](https://code.claude.com/docs/ko/settings-reference#syncclaudeaiskills) | 모든 관리형 소스, `--settings`, `~/.claude/settings.json`, 또는 `.claude/settings.local.json`의 `false` | 승리한 관리형 소스가 `true`를 설정할 때도 준수됩니다. `.claude/settings.json`의 `false`는 무시됩니다 |

318| [`syncClaudeAiPlugins`](https://code.claude.com/docs/ko/settings-reference#syncclaudeaiplugins) | 모든 관리형 소스, `--settings`, `~/.claude/settings.json`, 또는 `.claude/settings.local.json`의 `false` | 승리한 관리형 소스가 `true`를 설정할 때도 준수됩니다. `.claude/settings.json`의 `false`는 무시됩니다 |318| [`syncClaudeAiPlugins`](https://code.claude.com/docs/ko/settings-reference#syncclaudeaiplugins) | 모든 관리형 소스, `--settings`, `~/.claude/settings.json`, 또는 `.claude/settings.local.json`의 `false` | 승리한 관리형 소스가 `true`를 설정할 때도 준수됩니다. `.claude/settings.json`의 `false`는 무시됩니다 |

319| [`maxEffortLevel`](https://code.claude.com/docs/ko/settings-reference#maxeffortlevel) | `--settings`를 포함한 모든 범위의 더 낮은 상한 | Claude Code가 적용하는 관리형 설정이 더 높은 상한을 설정할 때도 준수됩니다. 가장 낮은 상한이 적용됩니다. Claude Code v2.1.267 이상이 필요합니다 |319| [`maxEffortLevel`](https://code.claude.com/docs/ko/settings-reference#maxeffortlevel) | `--settings`를 포함한 모든 범위의 더 낮은 상한 | Claude Code가 적용하는 관리형 설정이 더 높은 상한을 설정할 때도 준수됩니다. 가장 낮은 상한이 적용됩니다. Claude Code v2.1.267 이상이 필요합니다 |

925Claude Code가 플랜 모드에서 자동 모드 분류기를 사용해 셸 명령을 검토할지 여부를 선택합니다. 기본값 `true`에서는 자동 모드를 사용할 수 있을 때 계획 중 분류기가 각 명령을 검토하며, [중요 경로 제거](https://code.claude.com/docs/ko/permission-modes.md#critical-paths)를 제외하고는 프롬프트가 표시되지 않습니다. 기본 제공 읽기 전용 집합 외의 모든 명령에 대해 권한 프롬프트를 받으려면 `false`로 설정하십시오. `/config`에는 **Use auto mode during plan**으로 표시됩니다.925Claude Code가 플랜 모드에서 자동 모드 분류기를 사용해 셸 명령을 검토할지 여부를 선택합니다. 기본값 `true`에서는 자동 모드를 사용할 수 있을 때 계획 중 분류기가 각 명령을 검토하며, [중요 경로 제거](https://code.claude.com/docs/ko/permission-modes.md#critical-paths)를 제외하고는 프롬프트가 표시되지 않습니다. 기본 제공 읽기 전용 집합 외의 모든 명령에 대해 권한 프롬프트를 받으려면 `false`로 설정하십시오. `/config`에는 **Use auto mode during plan**으로 표시됩니다.

926 926 

927* **범위**: [`User, local, or managed`](#scopes). 저장소는 사용자를 대신해 이를 끌 수 없습니다.927* **범위**: [`User, local, or managed`](#scopes). 저장소는 사용자를 대신해 이를 끌 수 없습니다.

928 * 이러한 파일 중 하나 또는 `--settings`에서 `false`를 설정하면 꺼집니다. 단, [`--setting-sources`](https://code.claude.com/docs/ko/cli-reference#cli-flags) 같은 옵션으로 해당 사용자 또는 로컬 파일을 제외한 경우는 예외입니다. 제외된 파일을 무시하려면 Claude Code v2.1.314 이상이 필요합니다

928* **타입**: Boolean929* **타입**: Boolean

929 * `true`: 설정되지 않은 경우와 동일합니다. 자동 모드를 사용할 수 있을 때 분류기가 계획 중 각 셸 명령을 검토하며, [중요 경로 제거](https://code.claude.com/docs/ko/permission-modes.md#critical-paths)를 제외하고는 확인을 요청하지 않습니다. 이러한 파일 중 하나라도 `false`를 설정하면 꺼집니다930 * `true`: 설정되지 않은 경우와 동일합니다. 자동 모드를 사용할 수 있을 때 분류기가 계획 중 셸 명령을 검토합니다

930 * `false`: 기본 제공 읽기 전용 집합 외의 모든 명령에 대해 권한 프롬프트가 표시됩니다931 * `false`: 기본 제공 읽기 전용 집합 외의 모든 명령에 대해 권한 프롬프트가 표시됩니다

931* **기본값**: `true`932* **기본값**: `true`

932 933 

2073 2074 

2074### `sandbox.network.allowMachLookup`2075### `sandbox.network.allowMachLookup`

2075 2076 

2076macOS 샌드박스가 조회할 수 있는 추가 XPC 및 Mach 서비스 이름을 나열합니다. iOS 시뮬레이터 또는 Playwright와 같이 XPC를 통해 통신하는 도구는 여기에 서비스를 나열해야 합니다.2077macOS 샌드박스가 조회할 수 있는 추가 XPC 및 Mach 서비스 이름을 나열합니다. iOS Simulator나 Playwright처럼 XPC로 통신하는 도구는 해당 서비스를 여기에 나열해야 합니다. 샌드박스 처리된 명령은 나열한 각 서비스에 샌드박스 밖으로 접근할 수 있으며, 샌드박스는 [이러한 서비스가 해당 명령을 위해 수행하는 작업을 제한하지 않습니다](https://code.claude.com/docs/ko/sandboxing.md#security-limitations).

2077 2078 

2078* **범위**: [`Any file`](#scopes), [프로젝트 및 로컬 설정에 대한 제한](https://code.claude.com/docs/ko/sandboxing.md#repository-settings-under-an-admin-required-sandbox) 있음2079* **범위**: [`Any file`](#scopes), [프로젝트 및 로컬 설정에 대한 제한](https://code.claude.com/docs/ko/sandboxing.md#repository-settings-under-an-admin-required-sandbox) 있음

2079* **유형**: 각각 서비스 이름인 문자열의 배열. 단일 후행 `*`는 접두사와 일치하고, `"*"` 단독으로는 모든 서비스와 일치합니다.2080* **유형**: 각각 서비스 이름인 문자열의 배열. 단일 후행 `*`는 접두사와 일치하고, `"*"` 단독으로는 모든 서비스와 일치합니다.

2422 2423 

2423 프로젝트 및 로컬 설정에서 이 그룹을 무시하려면 Claude Code v2.1.282 이상이 필요합니다.2424 프로젝트 및 로컬 설정에서 이 그룹을 무시하려면 Claude Code v2.1.282 이상이 필요합니다.

2424 * Claude Code가 시작하거나 동기화하는 방식을 변경하는 변수, 예: `CLAUDE_CODE_PROCESS_WRAPPER`, `CLAUDE_CODE_SYNC_SKILLS`, `CLAUDE_CODE_SYNC_PLUGINS`, `CLAUDE_CODE_PLUGIN_CACHE_DIR` 및 `CLAUDE_CODE_PLUGIN_SEED_DIR`.2425 * Claude Code가 시작하거나 동기화하는 방식을 변경하는 변수, 예: `CLAUDE_CODE_PROCESS_WRAPPER`, `CLAUDE_CODE_SYNC_SKILLS`, `CLAUDE_CODE_SYNC_PLUGINS`, `CLAUDE_CODE_PLUGIN_CACHE_DIR` 및 `CLAUDE_CODE_PLUGIN_SEED_DIR`.

2426 * [`CLAUDE_CODE_OAUTH_TOKEN`, `CLAUDE_CODE_OAUTH_REFRESH_TOKEN` 및 `CLAUDE_CODE_OAUTH_SCOPES`](https://code.claude.com/docs/ko/env-vars#variables)와 같이 claude.ai 로그인을 설정하는 변수.

2425 * [화면 낭독기 모드](https://code.claude.com/docs/ko/accessibility.md) 변수 `CLAUDE_AX_SCREEN_READER` 및 [`CLAUDE_AX_STARTUP_QUIET_MS`](https://code.claude.com/docs/ko/env-vars#variables)와 같이 이름이 `CLAUDE_AX_`로 시작하는 기타 변수.2427 * [화면 낭독기 모드](https://code.claude.com/docs/ko/accessibility.md) 변수 `CLAUDE_AX_SCREEN_READER` 및 [`CLAUDE_AX_STARTUP_QUIET_MS`](https://code.claude.com/docs/ko/env-vars#variables)와 같이 이름이 `CLAUDE_AX_`로 시작하는 기타 변수.

2426 * 응답하지 않은 대화 상자의 타이머를 설정하는 [`CLAUDE_CODE_USER_DIALOG_TIMEOUT_MS`](https://code.claude.com/docs/ko/env-vars#variables).2428 * 응답하지 않은 대화 상자의 타이머를 설정하는 [`CLAUDE_CODE_USER_DIALOG_TIMEOUT_MS`](https://code.claude.com/docs/ko/env-vars#variables).

2427 * 첨부 파일 처리를 끄는 [`CLAUDE_CODE_DISABLE_ATTACHMENTS`](https://code.claude.com/docs/ko/env-vars#variables).2429 * 첨부 파일 처리를 끄는 [`CLAUDE_CODE_DISABLE_ATTACHMENTS`](https://code.claude.com/docs/ko/env-vars#variables).

40>40>

41> **macOS, Linux, WSL:**41> **macOS, Linux, WSL:**

42>42>

43> ```bash theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null}43> ```bash theme={null}

44> curl -fsSL https://claude.ai/install.sh | bash44> curl -fsSL https://claude.ai/install.sh | bash

45> ```45> ```

46>46>

48>48>

49> **Windows PowerShell:**49> **Windows PowerShell:**

50>50>

51> ```powershell theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null}51> ```powershell theme={null}

52> irm https://claude.ai/install.ps1 | iex52> irm https://claude.ai/install.ps1 | iex

53> ```53> ```

54>54>

55> **Windows CMD:**55> **Windows CMD:**

56>56>

57> ```batch theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null}57> ```batch theme={null}

58> curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd58> curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd

59> ```59> ```

60>60>

72 72 

73> [tab] Homebrew73> [tab] Homebrew

74>74>

75> ```bash theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null}75> ```bash theme={null}

76> brew install --cask claude-code76> brew install --cask claude-code

77> ```77> ```

78>78>

84 84 

85> [tab] WinGet85> [tab] WinGet

86>86>

87> ```powershell theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null}87> ```powershell theme={null}

88> winget install Anthropic.ClaudeCode88> winget install Anthropic.ClaudeCode

89> ```89> ```

90>90>

416 416 

417Claude에게 포크가 아닌 서브에이전트를 특정 effort 수준으로 실행하도록 요청하면, Claude는 해당 호출에 대해 `effort` 매개변수를 전달할 수도 있습니다. 이 매개변수는 `effort` 필드를 재정의하며 서브에이전트가 [재개](#resume-subagents)될 때도 유지됩니다. [`CLAUDE_CODE_EFFORT_LEVEL`](https://code.claude.com/docs/ko/env-vars#variables) 환경 변수는 둘 다보다 우선합니다. 호출별 매개변수는 Claude Code v2.1.292 이상이 필요합니다.417Claude에게 포크가 아닌 서브에이전트를 특정 effort 수준으로 실행하도록 요청하면, Claude는 해당 호출에 대해 `effort` 매개변수를 전달할 수도 있습니다. 이 매개변수는 `effort` 필드를 재정의하며 서브에이전트가 [재개](#resume-subagents)될 때도 유지됩니다. [`CLAUDE_CODE_EFFORT_LEVEL`](https://code.claude.com/docs/ko/env-vars#variables) 환경 변수는 둘 다보다 우선합니다. 호출별 매개변수는 Claude Code v2.1.292 이상이 필요합니다.

418 418 

419#### 서브에이전트에 `effort` 필드나 매개변수가 없는 경우

420 

421메인 대화의 모델에서는 서브에이전트가 `/effort` 등으로 세션에서 선택하거나 `--effort`로 설정한 수준으로 실행됩니다. 다른 모델에서는 [해당 수준이 적용되지 않습니다](https://code.claude.com/docs/ko/model-config.md#effort-level-of-subagents-and-teammates). 수준을 선택하려면 `effort` 필드를 설정하세요.

422 

419### 서브에이전트 기능 제어423### 서브에이전트 기능 제어

420 424 

421도구 접근, 권한 모드, 조건부 규칙을 통해 서브에이전트가 할 수 있는 작업을 제어할 수 있습니다.425도구 접근, 권한 모드, 조건부 규칙을 통해 서브에이전트가 할 수 있는 작업을 제어할 수 있습니다.

69 69 

70이 연결을 통해 세션은 모든 공개 저장소를 복제할 수 있지만, Claude GitHub 앱이 설치된 경우에만 비공개 저장소에서 작동할 수 있습니다. 사용하려는 비공개 저장소가 있는 각 GitHub 계정 또는 조직에 [Claude GitHub 앱을 설치](https://github.com/apps/claude/installations/new)합니다. GitHub 조직에서는 조직 소유자가 설치를 승인해야 할 수 있습니다. 앱을 설치하면 [Auto-fix](https://code.claude.com/docs/ko/claude-code-on-the-web.md#auto-fix-pull-requests)도 활성화되어 Claude가 CI 실패에 응답하고 해당 저장소의 pull request에 대한 검토 의견에 응답할 수 있습니다.70이 연결을 통해 세션은 모든 공개 저장소를 복제할 수 있지만, Claude GitHub 앱이 설치된 경우에만 비공개 저장소에서 작동할 수 있습니다. 사용하려는 비공개 저장소가 있는 각 GitHub 계정 또는 조직에 [Claude GitHub 앱을 설치](https://github.com/apps/claude/installations/new)합니다. GitHub 조직에서는 조직 소유자가 설치를 승인해야 할 수 있습니다. 앱을 설치하면 [Auto-fix](https://code.claude.com/docs/ko/claude-code-on-the-web.md#auto-fix-pull-requests)도 활성화되어 Claude가 CI 실패에 응답하고 해당 저장소의 pull request에 대한 검토 의견에 응답할 수 있습니다.

71 71 

72연결하면 Claude는 사용자가 소유한 GitHub 계정 중 Claude GitHub 앱이 설치된 계정을 Claude 조직에도 연결합니다. Team 및 Enterprise 플랜에서는 관리자가 [연결된 GitHub 계정 목록](https://code.claude.com/docs/ko/admin-setup.md#connected-github-accounts)에서 해당 계정을 확인할 수 있습니다.72연결하면 Claude는 사용자가 소유한 GitHub 계정 중 Claude GitHub 앱이 설치된 계정을 Claude 조직에도 연결합니다. Team 및 Enterprise 플랜에서는 Claude 조직의 Owner가 [연결된 GitHub 계정 목록](https://code.claude.com/docs/ko/admin-setup.md#connected-github-accounts)에서 해당 계정을 확인할 수 있습니다.

73 73 

74온보딩이 이 시점에서 Claude GitHub 앱을 설치하도록 요청하지만 나중에 설치하려면 **Skip**을 클릭합니다.74온보딩이 이 시점에서 Claude GitHub 앱을 설치하도록 요청하지만 나중에 설치하려면 **Skip**을 클릭합니다.

75 75