Documentation — Spybara

admin-setup.md +2 −2

Details

137 연결된 GitHub 계정137 연결된 GitHub 계정

138</h3>138</h3>

139 139

140Team 및 Enterprise 플랜에서 [**관리자 설정 > GitHub**](https://claude.ai/admin-settings/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 조직에서 관리자 역할이 필요합니다.140Team 및 Enterprise 플랜에서 [**조직 설정 > GitHub**](https://claude.ai/admin-settings/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 조직에서 관리자 역할이 필요합니다.

141 141

142관리자 또는 구성원이 계정을 연결할 수 있습니다:142관리자 또는 구성원이 계정을 연결할 수 있습니다:

143 143

162| Analytics dashboard | Teams / Enterprise의 채택 및 기여도 메트릭(리더보드 포함); Console의 사용자별 사용량 및 지출 메트릭 | Teams / Enterprise at [claude.ai/analytics](https://claude.ai/analytics/claude-code), Console at [platform.claude.com/claude-code](https://platform.claude.com/claude-code) | [Analytics](/docs/ko/analytics) |162| Analytics dashboard | Teams / Enterprise의 채택 및 기여도 메트릭(리더보드 포함); Console의 사용자별 사용량 및 지출 메트릭 | Teams / Enterprise at [claude.ai/analytics](https://claude.ai/analytics/claude-code), Console at [platform.claude.com/claude-code](https://platform.claude.com/claude-code) | [Analytics](/docs/ko/analytics) |

163| Programmatic reporting | API를 통한 사용자별 사용량 및 비용 데이터 | Enterprise의 경우 [Enterprise Analytics API](https://platform.claude.com/docs/en/api/admin/analytics), Console의 경우 [Claude Code Analytics API](https://platform.claude.com/docs/en/build-with-claude/claude-code-analytics-api) | [Costs](/docs/ko/costs#manage-costs-for-your-organization) |163| Programmatic reporting | API를 통한 사용자별 사용량 및 비용 데이터 | Enterprise의 경우 [Enterprise Analytics API](https://platform.claude.com/docs/en/api/admin/analytics), Console의 경우 [Claude Code Analytics API](https://platform.claude.com/docs/en/build-with-claude/claude-code-analytics-api) | [Costs](/docs/ko/costs#manage-costs-for-your-organization) |

164| Spend controls | 지출 제한 및 속도 제한 | Teams / Enterprise의 관리자 설정, Console의 워크스페이스 제한; 타사 클라우드의 경우, 클라우드 예산 제어 또는 사용자별 [지출 제한](/docs/ko/claude-apps-gateway-spend-limits)이 있는 [Claude apps gateway](/docs/ko/claude-apps-gateway) | [Costs](/docs/ko/costs#manage-costs-for-your-organization) |164| Spend controls | 지출 제한 및 속도 제한 | Teams / Enterprise의 조직 설정, Console의 워크스페이스 제한; 타사 클라우드의 경우, 클라우드 예산 제어 또는 사용자별 [지출 제한](/docs/ko/claude-apps-gateway-spend-limits)이 있는 [Claude apps gateway](/docs/ko/claude-apps-gateway) | [Costs](/docs/ko/costs#manage-costs-for-your-organization) |

165 165

166Teams 및 Enterprise에서 사용자별 사용량 및 지출 수치는 분석 대시보드가 아닌 조직의 분석 설정에 있는 [지출 보고서](https://support.claude.com/en/articles/12883420-view-usage-analytics-for-team-and-enterprise-plans)에서 제공됩니다. 클라우드 제공자는 AWS Cost Explorer, GCP Billing 또는 Azure Cost Management를 통해 지출을 노출합니다. Claude 채팅, Claude Code 및 Cowork 전반에 걸쳐 엔터프라이즈 예산을 계획하려면 [Claude Enterprise 소비 가이드](https://support.claude.com/en/articles/14782391-claude-enterprise-consumption-guide)를 참조하세요.166Teams 및 Enterprise에서 사용자별 사용량 및 지출 수치는 분석 대시보드가 아닌 조직의 분석 설정에 있는 [지출 보고서](https://support.claude.com/en/articles/12883420-view-usage-analytics-for-team-and-enterprise-plans)에서 제공됩니다. 클라우드 제공자는 AWS Cost Explorer, GCP Billing 또는 Azure Cost Management를 통해 지출을 노출합니다. Claude 채팅, Claude Code 및 Cowork 전반에 걸쳐 엔터프라이즈 예산을 계획하려면 [Claude Enterprise 소비 가이드](https://support.claude.com/en/articles/14782391-claude-enterprise-consumption-guide)를 참조하세요.

167 167

agent-sdk/mcp.md +14 −0

Details

919 ```919 ```

920</CodeGroup>920</CodeGroup>

921 921

922<h3 id="a-tool-is-missing-from-an-sdk-mcp-server">

923 SDK MCP 서버에서 도구가 누락됨

924</h3>

925

926TypeScript SDK에서 도구의 입력 스키마를 JSON Schema로 변환할 수 없는 경우, [`createSdkMcpServer()`](/docs/ko/agent-sdk/typescript#createsdkmcpserver)로 생성한 서버는 도구 목록을 나열할 때 해당 도구를 제외합니다. 이 시점에 SDK는 경고를 내보냅니다. Node.js에서 이 경고는 코드가 `CLAUDE_SDK_MCP_TOOL_SCHEMA_UNCONVERTIBLE`인 프로세스 경고이며, 다음 텍스트로 시작합니다:

927

928```text theme={null}

929Tool "<name>" on SDK MCP server "<server>" was left out of the server's tool list, because its input schema cannot be converted to JSON Schema

930```

931

932경고의 나머지 부분은 변환 오류 메시지가 있는 경우 이를 제공한 다음, 무엇을 확인하고 변경해야 하는지 알려줍니다.

933

934TypeScript Agent SDK v0.3.286 이전에는 변환할 수 없는 스키마 하나로 인해 이 경고 없이 서버의 전체 도구 목록 나열이 실패했으므로, 해당 서버의 도구가 하나도 Claude에 전달되지 않았습니다.

935

922<h3 id="connection-timeouts">936<h3 id="connection-timeouts">

923 연결 시간 초과937 연결 시간 초과

924</h3>938</h3>

agent-sdk/troubleshooting.md +1 −1

Details

13| 증상 | 이동 |13| 증상 | 이동 |

14| :- | :- |14| :- | :- |

15| Skills를 찾을 수 없음, skill이 사용되지 않음, `Invalid skill name` 오류 | [Skills 문제 해결](/docs/ko/agent-sdk/skills#troubleshooting) |15| Skills를 찾을 수 없음, skill이 사용되지 않음, `Invalid skill name` 오류 | [Skills 문제 해결](/docs/ko/agent-sdk/skills#troubleshooting) |

16| MCP 서버가 `failed` 상태를 표시, 도구가 호출되지 않음, 연결 시간 초과, 최대 허용 토큰을 초과하는 도구 출력 | [MCP 문제 해결](/docs/ko/agent-sdk/mcp#troubleshooting) |16| MCP 서버가 `failed` 상태를 표시, 도구가 호출되지 않음, SDK MCP 서버에서 도구가 누락됨, 연결 시간 초과, 최대 허용 토큰을 초과하는 도구 출력 | [MCP 문제 해결](/docs/ko/agent-sdk/mcp#troubleshooting) |

17| Plugin이 로드되지 않음, plugin skills이 나타나지 않음 | [Plugins 문제 해결](/docs/ko/agent-sdk/plugins#troubleshooting) |17| Plugin이 로드되지 않음, plugin skills이 나타나지 않음 | [Plugins 문제 해결](/docs/ko/agent-sdk/plugins#troubleshooting) |

18| Claude가 subagents로 위임하지 않음, 파일 시스템 기반 agents가 로드되지 않음 | [Subagents 문제 해결](/docs/ko/agent-sdk/subagents#troubleshooting) |18| Claude가 subagents로 위임하지 않음, 파일 시스템 기반 agents가 로드되지 않음 | [Subagents 문제 해결](/docs/ko/agent-sdk/subagents#troubleshooting) |

19| Checkpointing 옵션이 인식되지 않음, UUID 없는 사용자 메시지, `No file checkpoint found`, `File rewinding is not enabled`, `ProcessTransport is not ready for writing` | [File checkpointing 문제 해결](/docs/ko/agent-sdk/file-checkpointing#troubleshooting) |19| Checkpointing 옵션이 인식되지 않음, UUID 없는 사용자 메시지, `No file checkpoint found`, `File rewinding is not enabled`, `ProcessTransport is not ready for writing` | [File checkpointing 문제 해결](/docs/ko/agent-sdk/file-checkpointing#troubleshooting) |

agent-sdk/typescript.md +436 −424

Details

527```527```

528 528

529<h2 id="types">529<h2 id="types">

530 유형530 타입

531</h2>531</h2>

532 532

533<h3 id="options">533<h3 id="options">

536 536

537`query()` 함수의 구성 객체입니다.537`query()` 함수의 구성 객체입니다.

538 538

539| 속성 | 유형 | 기본값 | 설명 |539| 속성 | 타입 | 기본값 | 설명 |

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

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

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

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

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

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

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

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

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

563| `forwardSubagentText` | `boolean` | `false` | 서브에이전트 텍스트 및 사고 블록을 `parent_tool_use_id`가 설정된 어시스턴트 및 사용자 메시지로 전달하여 소비자가 중첩된 대화를 렌더링할 수 있도록 합니다. 이 옵션이 없으면 Claude Code는 서브에이전트 `tool_use` 및 `tool_result` 블록을 내보내지만 텍스트나 사고는 내보내지 않습니다. Claude Code v2.1.219 이상에서는 모든 중첩 깊이의 서브에이전트 메시지가 전달됩니다. v2.1.219 이전에는 깊이 1의 서브에이전트 메시지만 나타났습니다. 포크된 스킬이 생성하는 서브에이전트의 메시지 및 중첩된 포크된 스킬은 v2.1.275 이상이 필요합니다 |563| `forwardSubagentText` | `boolean` | `false` | 서브에이전트의 텍스트 및 thinking 블록을 `parent_tool_use_id`가 설정된 어시스턴트 및 사용자 메시지로 전달하여, 소비자가 중첩된 트랜스크립트를 렌더링할 수 있도록 합니다. 이 옵션이 없으면 Claude Code는 서브에이전트의 `tool_use` 및 `tool_result` 블록은 내보내지만 텍스트나 사고는 내보내지 않습니다. Claude Code v2.1.219 이상에서는 모든 중첩 깊이의 서브에이전트 메시지가 전달되며, v2.1.219 이전에는 깊이 1 서브에이전트의 메시지만 표시되었습니다. 포크된 스킬이 생성한 서브에이전트와 중첩된 포크 스킬의 메시지는 v2.1.275 이상이 필요합니다 |

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

607 607

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

609 느리거나 정지된 API 응답 처리609 느리거나 멈춘 API 응답 처리

610</h4>610</h4>

611 611

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

613 613

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

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

627});627});

628```628```

629 629

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

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

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

633 633

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

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

636 636

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

638 638

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

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

641</h3>641</h3>

642 642

643`query()` 함수에서 반환하는 인터페이스입니다.643`query()` 함수가 반환하는 인터페이스입니다.

644 644

645```typescript theme={null}645```typescript theme={null}

646interface Query extends AsyncGenerator<SDKMessage, void> {646interface Query extends AsyncGenerator<SDKMessage, void> {

696 696

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

720| `setMcpServers(servers)` | 이 세션의 MCP 서버 집합을 동적으로 대체합니다. 추가되고 제거된 서버를 명시하고 오류가 있는 [`McpSetServersResult`](#mcpsetserversresult)로 해결합니다 |720| `setMcpServers(servers)` | 이 세션의 MCP 서버 집합을 동적으로 교체합니다. 추가 및 제거된 서버와 오류를 알려 주는 [`McpSetServersResult`](#mcpsetserversresult)로 resolve됩니다 |

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

725 725

726<h4 id="applyflagsettings">726<h4 id="applyflagsettings">

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

728</h4>728</h4>

729 729

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

731 731

732일부 키만 중간 세션에서 적용됩니다:732일부 키만 세션 중에 적용됩니다:

733 733

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

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

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

737 737

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

739 739

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

741 741

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

743 743

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

745 745

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

747 747

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

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

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

751 751

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

753 753

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

755 755

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

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

766```766```

767 767

768<Note>768<Note>

769 `applyFlagSettings()`는 TypeScript 전용입니다. Python SDK는 동등한 메서드를 노출하지 않습니다.769 `applyFlagSettings()`는 TypeScript 전용입니다. Python SDK는 이에 상응하는 메서드를 제공하지 않습니다.

770</Note>770</Note>

771 771

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

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

774</h4>774</h4>

775 775

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

777 777

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

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

780 780

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

782 782

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

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

785</h4>785</h4>

786 786

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

788 788

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

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

791 791

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

793 `WarmQuery`793 `WarmQuery`

794</h3>794</h3>

795 795

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

797 797

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

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

808 808

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

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

813 813

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

815 815

817 `SpareProcess`817 `SpareProcess`

818</h3>818</h3>

819 819

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

821 821

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

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

837 837

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

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

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

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

844 844

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

846 846

847Claude Code는 청구를 거부할 수 있습니다. 예를 들어 존재하지 않는 폴더나 프로젝트 설정이 `env`, `agent` 또는 `model`을 설정하는 폴더의 경우입니다. `claimed`가 `option_not_applied`로 시작하는 메시지와 함께 거부할 때, 세션은 요청한 `model` 또는 `maxThinkingTokens` 없이 실행 중입니다. 다른 거부 후 프롬프트가 실행되지 않았으므로 대신 `query()`로 세션을 시작합니다.847Claude Code는 존재하지 않는 폴더나 프로젝트 설정에서 `env`, `agent` 또는 `model`을 설정하는 폴더 등에 대해 클레임을 거부할 수 있습니다. `claimed`가 `option_not_applied`로 시작하는 메시지와 함께 reject되면, 세션은 요청한 `model` 또는 `maxThinkingTokens` 없이 실행 중입니다. 그 외의 거부 이후에는 프롬프트가 실행되지 않았으므로, 대신 `query()`로 세션을 시작하세요.

848 848

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

850 `SDKControlInitializeResponse`850 `SDKControlInitializeResponse`

851</h3>851</h3>

852 852

853`initializationResult()`의 반환 유형입니다. 세션 초기화 데이터를 포함합니다.853`initializationResult()`의 반환 타입입니다. 세션 초기화 데이터를 포함합니다.

854 854

855```typescript theme={null}855```typescript theme={null}

856type SDKControlInitializeResponse = {856type SDKControlInitializeResponse = {

863 fast_mode_state?: "off" | "cooldown" | "on";863 fast_mode_state?: "off" | "cooldown" | "on";

864 fast_mode_disabled_reason?: FastModeDisabledReason;864 fast_mode_disabled_reason?: FastModeDisabledReason;

865 hooks_applied?: boolean;865 hooks_applied?: boolean;

866 sdk_mcp_manifests_parked?: Record<

867 string,

868 | "parked"

869 | "already_connected"

870 | "protocol_version_mismatch"

871 | "malformed"

872 | "not_honoured"

873 >;

866};874};

867```875```

868 876

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

878

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

870 880

871요청이 훅을 전달하지 않으면 Claude Code는 필드를 생략합니다. 요청이 훅을 전달할 때, 값은 요청이 세션의 첫 번째 초기화인지, 반복된 요청의 경우 세션에 도달한 방식에 따라 달라집니다:881* `true`: Claude Code가 훅을 등록했습니다. 세션의 첫 번째 initialize는 이 값을 반환합니다. CLI의 stdin으로 전송된 반복 initialize도 `true`를 반환합니다. 이 경우 새 요청의 훅이 이전에 등록된 훅을 대체합니다.

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

872 883

873* `true`: Claude Code가 훅을 등록했습니다. 세션의 첫 번째 초기화는 이 값을 반환합니다. CLI의 stdin을 통해 전송된 반복 초기화도 `true`를 반환합니다. 이 경우 새 요청의 훅이 이전에 등록된 훅을 대체합니다.884Agent SDK v0.3.238 이전에는 응답에 이 필드가 없었고, Claude Code는 모든 반복 initialize에서 `hooks`를 무시했습니다.

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

875 885

876Agent SDK v0.3.238 이전에는 응답이 필드를 전달하지 않았고, Claude Code는 모든 반복 초기화에서 `hooks`를 무시했습니다.886요청의 `sdkMcpServerManifests` 필드와 응답의 `sdk_mcp_manifests_parked` 필드는 [`createSdkMcpServer()`](#createsdkmcpserver)로 생성한 인프로세스 [SDK MCP 서버](/docs/ko/agent-sdk/custom-tools)용입니다. 애플리케이션은 두 필드 모두 설정하거나 읽지 않습니다.

877 887

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

879 889

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

881 891

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

883 893

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

885 895

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

887 `SDKControlInterruptResponse`897 `SDKControlInterruptResponse`

888</h3>898</h3>

889 899

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

891 901

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

893type SDKControlInterruptResponse = {903type SDKControlInterruptResponse = {

896};906};

897```907```

898 908

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

900 910

901수신을 사용하여 다시 보낼 것을 결정합니다. 나열된 메시지를 취소하지 않으면 응답을 받는지 여부와 관계없이 대화에 들어가므로 다시 보내면 Claude에 두 번 전달됩니다.911영수증을 사용하여 무언가를 다시 보낼지 결정하세요. 취소하지 않은 나열된 메시지는 응답을 받든 받지 않든 대화에 들어가므로, 다시 보내면 Claude에 두 번 전달됩니다.

902 912

903이러한 주의사항으로 목록을 해석합니다:913다음 주의 사항을 고려하여 목록을 해석하세요:

904 914

905* UUID로 대기열에 들어간 메시지만 나타납니다. 빈 배열은 다른 것이 실행되지 않음을 의미하지 않습니다.915* UUID와 함께 큐에 추가된 메시지만 나타납니다. 빈 배열이라고 해서 다른 것이 실행되지 않는다는 의미는 아닙니다.

906* 메인 스레드 메시지만 나열됩니다. 서브에이전트로 주소 지정된 메시지는 범위를 벗어납니다.916* 메인 스레드 메시지만 나열됩니다. 서브에이전트에 전달된 메시지는 범위에 포함되지 않습니다.

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

908 918

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

910 920

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

912 922

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

914 924

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

916 `SDKControlGetContextUsageResponse`926 `SDKControlGetContextUsageResponse`

917</h3>927</h3>

918 928

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

920 930

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

922 932

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

924* **`'summary'`**: 대신 마지막 응답의 사용량 및 로컬 추정에서 답변을 얻으려면 `{ detail: 'summary' }`를 전달합니다. 토큰 계산 요청이 나가지 않으며 카테고리별 숫자는 대략적입니다.934* **`'summary'`**: `{ detail: 'summary' }`를 전달하면 대신 마지막 응답의 사용량과 로컬 추정치로 답을 얻습니다. 토큰 계산 요청이 전송되지 않으며, 카테고리별 수치는 근사치입니다.

925 935

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

927 937

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

929type SDKControlGetContextUsageResponse = {939type SDKControlGetContextUsageResponse = {

1020};1030};

1021```1031```

1022 1032

1023토큰 귀속을 수집 필드에서 읽습니다:1033컬렉션 필드에서 토큰 귀속을 읽으세요:

1024 1034

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

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

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

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

1029 1039

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

1031 1041

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

1033 1043

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

1035 `SDKControlReadFileResponse`1045 `SDKControlReadFileResponse`

1036</h3>1046</h3>

1037 1047

1038[`readFile()`](#query-object)의 반환 유형입니다.1048[`readFile()`](#query-object)의 반환 타입입니다.

1039 1049

1040```typescript theme={null}1050```typescript theme={null}

1041type SDKControlReadFileResponse = {1051type SDKControlReadFileResponse = {

1046};1056};

1047```1057```

1048 1058

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

1050 1060

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

1052 readFile()이 읽을 수 있는 것1062 `readFile()`이 읽을 수 있는 항목

1053</h4>1063</h4>

1054 1064

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

1056 1066

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

1058* 세션의 도구 결과 같은 Claude Code 자체의 몇 가지 파일1068* 도구 결과와 같이 세션에 대한 Claude Code 자체 파일 일부

1059 1069

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

1061 1071

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

1063 `SDKControlReloadPluginsResponse`1073 `SDKControlReloadPluginsResponse`

1064</h3>1074</h3>

1065 1075

1066[`reloadPlugins()`](#query-object)의 반환 유형입니다.1076[`reloadPlugins()`](#query-object)의 반환 타입입니다.

1067 1077

1068```typescript theme={null}1078```typescript theme={null}

1069type SDKControlReloadPluginsResponse = {1079type SDKControlReloadPluginsResponse = {

1086};1096};

1087```1097```

1088 1098

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

1090 1100

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

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

1093* `error_count`: 플러그인 로드의 오류 수1103* `error_count`: 플러그인 로드 중 발생한 오류 수

1094 1104

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

1096 1106

1097옵션을 전달하면 `held`를 읽어 무슨 일이 일어났는지 알아봅니다:1107옵션을 전달한 경우 `held`를 읽어 결과를 확인하세요:

1098 1108

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

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

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

1102 1112

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

1104 1114

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

1106 `SDKControlReloadSkillsResponse`1116 `SDKControlReloadSkillsResponse`

1107</h3>1117</h3>

1108 1118

1109[`reloadSkills()`](#query-object)의 반환 유형입니다.1119[`reloadSkills()`](#query-object)의 반환 타입입니다.

1110 1120

1111```typescript theme={null}1121```typescript theme={null}

1112type SDKControlReloadSkillsResponse = {1122type SDKControlReloadSkillsResponse = {

1114};1124};

1115```1125```

1116 1126

1117`skills`는 다시 로드 후 사용 가능한 스킬을 `supportedCommands()`가 반환하는 것과 동일한 [`SlashCommand`](#slashcommand) 형태로 나열합니다.1127`skills`는 다시 로드한 후 사용 가능한 스킬을 `supportedCommands()`가 반환하는 것과 동일한 [`SlashCommand`](#slashcommand) 형태로 나열합니다.

1118 1128

1119<h3 id="sdkcontrolreloadoutputstylesresponse">1129<h3 id="sdkcontrolreloadoutputstylesresponse">

1120 `SDKControlReloadOutputStylesResponse`1130 `SDKControlReloadOutputStylesResponse`

1121</h3>1131</h3>

1122 1132

1123[`reloadOutputStyles()`](#query-object)의 반환 유형입니다.1133[`reloadOutputStyles()`](#query-object)의 반환 타입입니다.

1124 1134

1125```typescript theme={null}1135```typescript theme={null}

1126type SDKControlReloadOutputStylesResponse = {1136type SDKControlReloadOutputStylesResponse = {

1128};1138};

1129```1139```

1130 1140

1131`available_output_styles`는 다시 로드 후 사용 가능한 기본 제공 및 사용자 정의 출력 스타일의 이름을 나열합니다.1141`available_output_styles`는 다시 로드한 후 사용 가능한 기본 제공 및 사용자 지정 출력 스타일의 이름을 나열합니다.

1132 1142

1133<h3 id="sdkcontrolmcpreadresourceresponse">1143<h3 id="sdkcontrolmcpreadresourceresponse">

1134 `SDKControlMcpReadResourceResponse`1144 `SDKControlMcpReadResourceResponse`

1135</h3>1145</h3>

1136 1146

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

1138 1148

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

1140type SDKControlMcpReadResourceResponse = {1150type SDKControlMcpReadResourceResponse = {

1148};1158};

1149```1159```

1150 1160

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

1152 1162

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

1154 1164

1155콘텐츠는 신뢰할 수 없는 제3자 HTML이므로 샌드박스에서 렌더링합니다.1165콘텐츠는 신뢰할 수 없는 서드파티 HTML이므로 샌드박스에서 렌더링하세요.

1156 1166

1157<h3 id="agentdefinition">1167<h3 id="agentdefinition">

1158 `AgentDefinition`1168 `AgentDefinition`

1182 1192

1183| 필드 | 필수 | 설명 |1193| 필드 | 필수 | 설명 |

1184| :- | :- | :- |1194| :- | :- | :- |

1185| `description` | 예 | 이 에이전트를 사용할 때를 설명하는 자연어 |1195| `description` | 예 | 이 에이전트를 언제 사용해야 하는지에 대한 자연어 설명 |

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

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

1188| `prompt` | 예 | 에이전트의 시스템 프롬프트 |1198| `prompt` | 예 | 에이전트의 시스템 프롬프트 |

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

1190| `mcpServers` | 아니오 | 이 에이전트의 MCP 서버 사양 |1200| `mcpServers` | 아니요 | 이 에이전트의 MCP 서버 사양 |

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

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

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

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

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

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

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

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

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

1200 1210

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

1202 `AgentMcpServerSpec`1212 `AgentMcpServerSpec`

1203</h3>1213</h3>

1204 1214

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

1206 1216

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

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

1214 `SettingSource`1224 `SettingSource`

1215</h3>1225</h3>

1216 1226

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

1218 1228

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

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

1223| 값 | 설명 | 위치 |1233| 값 | 설명 | 위치 |

1224| :- | :- | :- |1234| :- | :- | :- |

1228 1238

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

1230 기본 동작1240 기본 동작

1231</h4>1241</h4>

1232 1242

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

1234 1244

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

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

1262});1272});

1263```1273```

1264 1274

1265CLAUDE.md 프로젝트 지침을 로드하려면 `settingSources`에 `"project"`를 포함합니다. CLAUDE.md 로드가 시스템 프롬프트 옵션과 상호작용하는 방식은 [시스템 프롬프트 수정](/docs/ko/agent-sdk/modifying-system-prompts#claude-md-files-for-project-level-instructions)을 참조하세요.1275CLAUDE.md 프로젝트 지침을 로드하려면 `settingSources`에 `"project"`를 포함하세요. CLAUDE.md 로딩이 시스템 프롬프트 옵션과 어떻게 상호 작용하는지는 [시스템 프롬프트 수정](/docs/ko/agent-sdk/modifying-system-prompts#claude-md-files-for-project-level-instructions)을 참조하세요.

1266 1276

1267<h4 id="settings-precedence">1277<h4 id="settings-precedence">

1268 설정 우선순위1278 설정 우선순위

1269</h4>1279</h4>

1270 1280

1271여러 소스가 로드될 때 설정은 이 우선순위(높음에서 낮음)로 병합됩니다:1281여러 소스가 로드되면 설정은 다음 우선순위(높은 순에서 낮은 순)로 병합됩니다.

1272 1282

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

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

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

1276 1286

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

1278 1288

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

1280 `PermissionMode`1290 `PermissionMode`

1282 1292

1283```typescript theme={null}1293```typescript theme={null}

1284type PermissionMode =1294type PermissionMode =

1285 | "default" // 표준 권한 동작1295 | "default" // Standard permission behavior

1286 | "acceptEdits" // 파일 편집 자동 수락1296 | "acceptEdits" // Auto-accept file edits

1287 | "bypassPermissions" // 권한 검사 우회; 명시적 요청 규칙은 여전히 프롬프트1297 | "bypassPermissions" // Bypass permission checks; explicit ask rules still prompt

1288 | "plan" // 계획 모드 - 편집 없이 탐색1298 | "plan" // Planning mode - explore without editing

1289 | "dontAsk" // 권한에 대해 프롬프트하지 않음, 사전 승인되지 않으면 거부1299 | "dontAsk" // Don't prompt for permissions, deny if not pre-approved

1290 | "auto"; // 모델 분류자가 셸 명령어 및 네트워크 요청 같은 작업을 검토1300 | "auto"; // A model classifier reviews actions such as shell commands and network requests

1291```1301```

1292 1302

1293<h3 id="canusetool">1303<h3 id="canusetool">

1294 `CanUseTool`1304 `CanUseTool`

1295</h3>1305</h3>

1296 1306

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

1298 1308

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

1300 1310

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

1302 1312

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

1304type CanUseTool = (1314type CanUseTool = (

1319) => Promise<PermissionResult | null>;1329) => Promise<PermissionResult | null>;

1320```1330```

1321 1331

1322| 옵션 | 유형 | 설명 |1332| 옵션 | 타입 | 설명 |

1323| :- | :- | :- |1333| :- | :- | :- |

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

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

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

1333| `requestId` | `string` | `control_request` 봉투의 `request_id`입니다. 애플리케이션이 자신의 채널(예: 서명된 HTTP POST)을 통해 보내는 `control_response`는 이 값을 에코해야 하므로 Claude Code 프로세스가 회신을 요청과 일치시킬 수 있습니다 |1343| `requestId` | `string` | `control_request` 엔벨로프의 `request_id`. 서명된 HTTP POST처럼 애플리케이션이 SDK 외부에서 보내는 `control_response`는 Claude Code 프로세스가 응답을 요청과 매칭할 수 있도록 이 값을 그대로 포함해야 합니다 |

~~1334~~ 1344

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

1336 1346

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

1338 1348

1340 `PermissionResult`1350 `PermissionResult`

1341</h3>1351</h3>

1342 1352

1343권한 검사의 결과입니다.1353권한 확인 결과입니다.

1344 1354

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

1346type PermissionResult =1356type PermissionResult =

1362 `ToolConfig`1372 `ToolConfig`

1363</h3>1373</h3>

1364 1374

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

1366 1376

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

1368type ToolConfig = {1378type ToolConfig = {

1372};1382};

1373```1383```

1374 1384

1375| 필드 | 유형 | 설명 |1385| 필드 | 타입 | 설명 |

1376| :- | :- | :- |1386| :- | :- | :- |

1378 1388

1379<h3 id="mcpserverconfig">1389<h3 id="mcpserverconfig">

1380 `McpServerConfig`1390 `McpServerConfig`

1381</h3>1391</h3>

1382 1392

1383MCP 서버의 구성입니다.1393MCP 서버에 대한 구성입니다.

1384 1394

1385```typescript theme={null}1395```typescript theme={null}

1386type McpServerConfig =1396type McpServerConfig =

1466};1476};

1467```1477```

1468 1478

1469| 필드 | 유형 | 설명 |1479| 필드 | 타입 | 설명 |

1470| :- | :- | :- |1480| :- | :- | :- |

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

1474 1484

1475**예제:**1485**예시:**

1476 1486

1477```typescript theme={null}1487```typescript theme={null}

1478plugins: [1488plugins: [

1481];1491];

1482```1492```

1483 1493

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

1485 1495

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

1487 메시지 타입1497 메시지 타입

1491 `SDKMessage`1501 `SDKMessage`

1492</h3>1502</h3>

1493 1503

1494쿼리에서 반환되는 모든 가능한 메시지의 합집합 타입입니다.1504쿼리가 반환할 수 있는 모든 메시지의 유니온 타입입니다.

1495 1505

1496```typescript theme={null}1506```typescript theme={null}

1497type SDKMessage =1507type SDKMessage =

1556};1566};

1557```1567```

1558 1568

1559`message` 필드는 Anthropic SDK의 [`BetaMessage`](https://platform.claude.com/docs/en/api/messages/create)입니다. `id`, `content`, `model`, `stop_reason`, `usage` 같은 필드를 포함합니다.1569`message` 필드는 Anthropic SDK의 [`BetaMessage`](https://platform.claude.com/docs/en/api/messages/create)입니다. 여기에는 `id`, `content`, `model`, `stop_reason`, `usage` 같은 필드가 포함됩니다.

1560 1570

1561`SDKAssistantMessageError`는 다음 중 하나입니다: `'authentication_failed'`, `'oauth_org_not_allowed'`, `'account_on_hold'`, `'billing_error'`, `'rate_limit'`, `'overloaded'`, `'invalid_request'`, `'model_not_found'`, `'server_error'`, `'max_output_tokens'`, `'cloud_credential_error'`, 또는 `'unknown'`. 이 중 네 개의 값은 이름이 나타내는 것보다 더 많은 의미를 가집니다:1571`SDKAssistantMessageError`는 `'authentication_failed'`, `'oauth_org_not_allowed'`, `'account_on_hold'`, `'billing_error'`, `'rate_limit'`, `'overloaded'`, `'invalid_request'`, `'model_not_found'`, `'server_error'`, `'max_output_tokens'`, `'cloud_credential_error'`, `'unknown'` 중 하나입니다. 이 중 네 가지 값은 이름보다 더 많은 의미를 가집니다.

1562 1572

1563* `'model_not_found'`: 선택한 모델이 존재하지 않거나 계정이나 배포에서 사용할 수 없음1573* `'model_not_found'`: 선택한 모델이 존재하지 않거나 사용자의 계정 또는 배포에서 사용할 수 없습니다

1564* `'overloaded'`: API가 서버가 용량에 도달했기 때문에 529를 반환했으며, 할당량에 대한 429인 `'rate_limit'`과는 다름1574* `'overloaded'`: 서버 용량이 가득 차서 API가 529를 반환했습니다. 이는 할당량에 대한 429인 `'rate_limit'`과 구별됩니다

1565* `'account_on_hold'`: [계정이 보류 중](/docs/ko/errors#your-account-is-on-hold)1575* `'account_on_hold'`: [계정이 보류 상태입니다](/docs/ko/errors#your-account-is-on-hold)

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

1567 1577

1568`aborted`는 중단이나 중지가 스트림이 완료되기 전에 어시스턴트 메시지를 자를 때 `true`입니다: 메시지에는 `stop_reason`이 없고 콘텐츠가 단어 중간에 끝날 수 있습니다. 이 필드는 정상적으로 완료된 메시지에는 없습니다. Agent SDK v0.3.214 이상이 필요합니다.1578`aborted`는 인터럽트 또는 중단으로 인해 스트림이 완료되기 전에 어시스턴트 메시지가 잘렸을 때 `true`입니다. 이 경우 메시지에는 `stop_reason`이 없으며 콘텐츠가 단어 중간에서 끝날 수 있습니다. 정상적으로 완료된 메시지에는 이 필드가 없습니다. Agent SDK v0.3.214 이상이 필요합니다.

1569 1579

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

1571 1581

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

1573 1583

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

1575 1585

1576<h3 id="sdkusermessage">1586<h3 id="sdkusermessage">

1577 `SDKUserMessage`1587 `SDKUserMessage`

1597};1607};

1598```1608```

1599 1609

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

1601 1611

1602`message.content` 중 사용자가 직접 입력하지 않고 붙여넣은 부분을 Claude Code에 알리려면 `inline_pastes`를 설정하세요. 붙여넣기 한 번당 문자열 하나입니다. 프롬프트 텍스트는 사용자가 둔 위치에 그대로 유지됩니다. Claude Code는 나열된 각 붙여넣기를 해당 위치에서 `<pasted_content>` 태그로 감쌀 수 있으므로, Claude는 붙여넣은 내용과 사용자가 직접 작성한 내용을 구별할 수 있습니다. 프롬프트의 마지막 텍스트 블록에 있는 붙여넣기만 감싸집니다. TypeScript Agent SDK v0.3.280 이상이 필요합니다.1612`message.content` 중 사용자가 입력하지 않고 붙여 넣은 부분을 Claude Code에 알리려면 `inline_pastes`를 설정합니다. 붙여 넣기 한 번당 하나의 문자열입니다. 프롬프트 텍스트는 사용자가 넣은 위치에 그대로 유지됩니다. Claude Code는 나열된 각 붙여 넣기를 해당 위치에서 `<pasted_content>` 태그로 감쌀 수 있으므로, Claude는 붙여 넣은 자료와 사용자가 직접 쓴 말을 구별할 수 있습니다. 프롬프트의 마지막 텍스트 블록에 있는 붙여 넣기만 감싸집니다. TypeScript Agent SDK v0.3.280 이상이 필요합니다.

1603 1613

1604보내는 메시지를 Claude Code가 처리하는 방식을 바꾸려면 `shouldQuery`, `client_composed` 또는 `priority`를 설정하세요.1614보내는 메시지를 Claude Code가 처리하는 방식을 바꾸려면 `shouldQuery`, `client_composed`, 또는 `priority`를 설정합니다.

1605 1615

1606* `shouldQuery`: 어시스턴트 턴을 트리거하지 않고 메시지를 트랜스크립트에 추가하려면 `false`로 설정하세요. 메시지는 보류되고 턴을 트리거하는 다음 사용자 메시지로 병합됩니다. 이를 사용하여 모델 호출을 소비하지 않고 대역 외에서 실행한 명령의 출력과 같은 컨텍스트를 주입하세요.1616* `shouldQuery`: `false`로 설정하면 어시스턴트 턴을 트리거하지 않고 메시지를 트랜스크립트에 추가합니다. 메시지는 보류되었다가 턴을 트리거하는 다음 사용자 메시지에 병합됩니다. 별도로 실행한 명령의 출력처럼 모델 호출을 소비하지 않고 컨텍스트를 주입할 때 사용합니다.

1607* `client_composed`: Claude Code가 작성된 대로 메시지 텍스트를 전달하도록 하려면 `true`로 설정하세요. Claude Code는 `@path` 또는 [`@server:resource`](/docs/ko/mcp#use-mcp-resources) 언급을 확장하지 않으며, `/`로 시작하는 텍스트를 명령으로 실행하지 않습니다. [`verbatimPrompts`](#options) 옵션이 켜져 있는 동안 SDK는 모든 메시지에 필드를 설정합니다. TypeScript Agent SDK v0.3.280 이상과 Claude Code v2.1.248 이상이 필요합니다.1617* `client_composed`: `true`로 설정하면 Claude Code가 메시지 텍스트를 작성된 그대로 전달합니다. 이 경우 Claude Code는 `@path` 또는 [`@server:resource`](/docs/ko/mcp#use-mcp-resources) 멘션을 확장하지 않으며, `/`로 시작하는 텍스트를 명령으로 실행하지 않습니다. [`verbatimPrompts`](#options) 옵션이 켜져 있는 동안에는 SDK가 모든 메시지에 이 필드를 설정합니다. TypeScript Agent SDK v0.3.280 이상과 Claude Code v2.1.248 이상이 필요합니다.

1608* `priority`: 실행 중인 턴 동안 보낸 메시지가 언제 Claude에 도달하는지 제어합니다.1618* `priority`: 턴이 실행 중일 때 보낸 메시지가 Claude에 도달하는 시점을 제어합니다.

1609 * `'next'` 또는 `priority` 필드 없음: Claude는 실행 중인 도구 호출이 끝나는 즉시 같은 턴에서 메시지를 읽습니다. 턴이 먼저 끝나면 메시지가 다음 턴을 시작합니다.1619 * `'next'` 또는 `priority` 필드 없음: Claude는 실행 중인 도구 호출이 끝나는 즉시 같은 턴에서 메시지를 읽습니다. 턴이 먼저 끝나면 메시지가 다음 턴을 시작합니다.

1610 * `'later'`: Claude Code는 턴이 끝날 때까지 메시지를 보류한 다음 새 턴으로 보냅니다.1620 * `'later'`: Claude Code는 턴이 끝날 때까지 메시지를 보류했다가 새 턴으로 보냅니다.

1611 * [`origin: { kind: "human" }`](#sdkmessageorigin)과 함께 `'now'`: Claude Code v2.1.286 이상에서는 백그라운드에서 계속할 수 있는 작업이 백그라운드로 이동하고, Claude는 같은 턴에서 메시지를 읽습니다. 이동할 수 있는 작업에는 셸 명령, 서브에이전트, MCP 도구 호출이 포함됩니다. v2.1.287 이상에서는 WebFetch 및 WebSearch 호출도 포함됩니다. Claude가 응답만 작성 중이거나 실행 중인 작업을 이동할 수 없으면, Claude Code는 대신 턴을 인터럽트하고 Claude는 다음으로 메시지를 읽습니다.1621 * [`origin: { kind: "human" }`](#sdkmessageorigin)과 함께 `'now'`: Claude Code v2.1.286 이상에서는 백그라운드에서 계속될 수 있는 작업이 백그라운드로 이동하고, Claude는 같은 턴에서 메시지를 읽습니다. 이동할 수 있는 작업에는 셸 명령, 서브에이전트, MCP 도구 호출이 포함됩니다. v2.1.287 이상에서는 WebFetch 및 WebSearch 호출도 포함됩니다. Claude가 응답만 작성 중이거나 실행 중인 작업을 이동할 수 없는 경우, Claude Code는 대신 턴을 인터럽트하고 Claude가 다음으로 메시지를 읽습니다.

1612 * 해당 origin 없이 `'now'`: Claude Code는 턴을 인터럽트하고 Claude는 다음으로 메시지를 읽습니다.1622 * 해당 origin 없이 `'now'`: Claude Code가 턴을 인터럽트하고 Claude가 다음으로 메시지를 읽습니다.

1613 1623

1614턴이 실행 중일 때 보낸 다음 메시지는 아직 실행 중인 셸 명령을 잃지 않고 Claude에게 방향을 바꾸도록 요청합니다.1624턴이 실행 중일 때 보내는 다음 메시지는 아직 실행 중인 셸 명령을 잃지 않고 방향을 바꾸도록 Claude에 요청합니다.

1615 1625

1616```typescript theme={null}1626```typescript theme={null}

1617const message: SDKUserMessage = {1627const message: SDKUserMessage = {

1623};1633};

1624```1634```

1625 1635

1626`tool_result` 블록을 포함하는 메시지에서 `tool_use_result`는 모델에 전송된 텍스트가 아닌 도구의 구조화된 출력 객체입니다. 그 형태는 대응하는 `tool_use` 블록이 가리키는 도구에 따라 달라지므로 필드 타입은 `unknown`입니다. 내장 형태는 [Tool Output Types](#tool-output-types)에 나열되어 있습니다. 다음 결과는 나열된 형태 이상의 처리가 필요합니다.1636`tool_result` 블록을 포함한 메시지에서 `tool_use_result`는 모델에 전송된 텍스트가 아니라 도구의 구조화된 출력 객체입니다. 그 형태는 대응하는 `tool_use` 블록이 지정한 도구에 따라 달라지므로 이 필드는 `unknown` 타입입니다. 기본 제공 형태는 [도구 출력 타입](#tool-output-types)에 나열되어 있습니다. 다음 결과는 나열된 형태 이상의 처리가 필요합니다.

1627 1637

1628* `Agent` 도구: `tool_use_result`는 [`AgentOutput`](#agent-2)입니다. `tool_result` 텍스트를 파싱하지 말고 이 값을 기반으로 렌더링하세요. `completed` 결과의 `content`에는 서브에이전트의 보고서가 담기며, 보고서를 `SubagentHandback` 도구 호출로 전달하는 서브에이전트의 경우에는 보고서 대신 해당 전달에 대한 짧은 안내가 담깁니다. Claude Code v2.1.271 이상의 [자동 모드](/docs/ko/permission-modes#eliminate-prompts-with-auto-mode)에서는 [포크](/docs/ko/sub-agents#fork-the-current-conversation)가 아닌 한 `completed` 결과를 생성하는 모든 서브에이전트가 이 방식으로 보고하며, Claude는 서브에이전트로부터 별도의 메시지로 보고서를 받습니다.1638* `Agent` 도구: `tool_use_result`는 [`AgentOutput`](#agent-2)입니다. `tool_result` 텍스트를 파싱하지 말고 이 값으로 렌더링하세요. `completed` 결과의 `content`에는 서브에이전트의 보고서가 담기며, 보고서를 `SubagentHandback` 도구 호출로 전달하는 서브에이전트의 경우에는 보고서 대신 해당 인계에 대한 짧은 메모가 담깁니다. Claude Code v2.1.271 이상의 [자동 모드](/docs/ko/permission-modes#eliminate-prompts-with-auto-mode)에서는 [포크](/docs/ko/sub-agents#fork-the-current-conversation)가 아닌 한 `completed` 결과를 생성하는 모든 서브에이전트가 그런 방식으로 보고하며, Claude는 서브에이전트로부터 별도의 메시지로 보고서를 받습니다.

1629* `'now'` 메시지를 전달하기 위해 Claude Code가 백그라운드로 이동한 WebFetch 또는 WebSearch 호출: 해당 호출의 `tool_result`를 담은 사용자 메시지는 `tool_use_result`가 `{ detachedToolCall: true }`로 설정됩니다. 호출은 여전히 실행 중이며, 완료되면 Claude가 결과를 받습니다. 해당 `tool_use_id`에 대한 두 번째 `tool_result`는 뒤따르지 않으므로, 애플리케이션이 도구 호출마다 행을 그린다면 이 메시지가 도착할 때 해당 행을 백그라운드로 이동된 것으로 표시하세요. Claude Code v2.1.287 이상이 필요합니다.1639* `'now'` 메시지를 전달하기 위해 Claude Code가 백그라운드로 이동한 WebFetch 또는 WebSearch 호출: 해당 호출의 `tool_result`를 담은 사용자 메시지에서 `tool_use_result`는 `{ detachedToolCall: true }`로 설정됩니다. 호출은 계속 실행 중이며, Claude는 호출이 끝나면 결과를 받습니다. 해당 `tool_use_id`에 대한 두 번째 `tool_result`는 뒤따르지 않으므로, 애플리케이션에서 도구 호출마다 행을 그린다면 이 메시지가 도착할 때 해당 행을 백그라운드로 이동됨으로 표시하세요. Claude Code v2.1.287 이상이 필요합니다.

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

1631* [`structuredContent`](#calltoolresult)를 반환하는 MCP 도구: `tool_use_result`는 `structuredContent` 멤버에 서버가 보낸 내용을, `content` 멤버에 [`McpOutput`](#mcpoutput) 값을 담은 객체입니다. 서브에이전트의 결과에는 `structuredContent`가 포함되지 않습니다.1641* [`structuredContent`](#calltoolresult)를 반환하는 MCP 도구: `tool_use_result`는 `structuredContent` 멤버에 서버가 보낸 내용을, `content` 멤버에 [`McpOutput`](#mcpoutput) 값을 담은 객체입니다. 서브에이전트의 결과에는 `structuredContent`가 포함되지 않습니다.

1632* `structuredContent`가 JSON으로 직렬화했을 때 1,048,576자를 초과하는 MCP 도구: Claude Code는 `tool_use_result`에서 `structuredContent`를 제외하고 대신 `structuredContentOmitted: true`를 설정하므로, 애플리케이션은 삭제된 객체와 아무것도 보내지 않은 도구를 구별할 수 있습니다. `content`, `resourceLinks` 같은 다른 멤버는 유지되며, Claude가 받는 내용은 바뀌지 않습니다. [인프로세스 SDK 서버](/docs/ko/agent-sdk/custom-tools)의 도구와 `tools/list` 항목에 [MCP Apps `_meta.ui` 리소스](#mcpserverstatus)를 선언한 도구는 예외이며 객체 전체를 전달합니다. Claude Code v2.1.287 이상에서 이 상한이 적용됩니다.1642* `structuredContent`가 1,048,576자를 초과하는 JSON으로 직렬화되는 MCP 도구: Claude Code는 `tool_use_result`에서 `structuredContent`를 제외하고 그 자리에 `structuredContentOmitted: true`를 설정하므로, 애플리케이션은 누락된 객체와 아무것도 보내지 않은 도구를 구별할 수 있습니다. `content`와 `resourceLinks` 같은 다른 멤버는 유지되며, Claude가 받는 내용은 변하지 않습니다. [프로세스 내 SDK 서버](/docs/ko/agent-sdk/custom-tools)의 도구와 `tools/list` 항목에서 [MCP Apps `_meta.ui` 리소스](#mcpserverstatus)를 선언한 도구는 예외이며 객체 전체를 전달합니다. Claude Code v2.1.287 이상에서 이 상한이 적용됩니다.

1633 1643

1634<h3 id="sdkusermessagereplay">1644<h3 id="sdkusermessagereplay">

1635 `SDKUserMessageReplay`1645 `SDKUserMessageReplay`

1652};1662};

1653```1663```

1654 1664

1655세션 외부에서 주입된 사용자 턴(해당 [`origin`](#sdkmessageorigin) 종류가 `peer` 또는 `channel`인 경우)은 활성 턴 중에 전달되었는지 또는 세션이 유휴 상태일 때 새 턴을 시작했는지 여부에 관계없이 재생으로 스트림에 도달합니다. v2.1.207 이전에는 세션이 유휴 상태일 때 전달된 주입된 턴이 스트림에 메시지를 생성하지 않았으며 트랜스크립트를 다시 읽을 때만 나타났습니다.1665세션 외부에서 주입된 사용자 턴, 즉 [`origin`](#sdkmessageorigin) kind가 `peer` 또는 `channel`인 턴은 활성 턴 중에 전달되었든 세션이 유휴 상태일 때 새 턴을 시작했든 재생 메시지로 스트림에 도달합니다. v2.1.207 이전에는 세션이 유휴 상태일 때 전달된 주입 턴이 스트림에 메시지를 생성하지 않았으며, 트랜스크립트를 다시 읽을 때만 나타났습니다.

1656 1666

1657<h3 id="sdkresultmessage">1667<h3 id="sdkresultmessage">

1658 `SDKResultMessage`1668 `SDKResultMessage`

1736 };1746 };

1737```1747```

1738 1748

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

~~1740~~ 1750

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

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

1743* `ttft_stream_ms`: 응답 스트림이 열릴 때 첫 번째 `message_start` 스트림 이벤트까지의 밀리초 단위 시간입니다. `ttft_ms`보다 낮습니다. 두 값 사이의 차이는 첫 번째 메시지를 스트리밍하는 데 소요된 시간입니다. 성공 분기에만 있습니다.1753* `ttft_stream_ms`: 응답 스트림이 열리는 첫 번째 `message_start` 스트림 이벤트까지의 시간(밀리초)입니다. `ttft_ms`보다 작으며, 둘 사이의 차이는 첫 번째 메시지를 스트리밍하는 데 걸린 시간입니다. success 분기에만 있습니다.

1744* `user_message_uuid`: 이 턴이 답변한 메시지의 `uuid`입니다. 어느 결과가 이를 전달하는지는 [`user_message_uuid`](#user_message_uuid)를 참조하세요.1754* `user_message_uuid`: 이 턴이 응답한, 사용자가 보낸 메시지의 `uuid`입니다. 어떤 결과에 포함되는지는 [`user_message_uuid`](#user_message_uuid)를 참조하세요.

1745* `user_message_uuids`: Claude Code가 이 턴에서 답변한 모든 메시지의 `uuid`입니다. [`user_message_uuids`](#user_message_uuids)를 참조하세요.1755* `user_message_uuids`: 이 턴에서 Claude Code가 응답한, 사용자가 보낸 모든 메시지의 `uuid`입니다. [`user_message_uuids`](#user_message_uuids)를 참조하세요.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

~~1760~~ 1770

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

1762 1772

1763| 이유 코드 | 의미 |1773| 이유 코드 | 의미 |

1764| - | - |1774| - | - |

1768| `network_error` | [가용성 검사](/docs/ko/fast-mode#use-fast-mode-behind-proxies-and-llm-gateways)가 `api.anthropic.com`에 도달할 수 없음 |1778| `network_error` | [가용성 검사](/docs/ko/fast-mode#use-fast-mode-behind-proxies-and-llm-gateways)가 `api.anthropic.com`에 연결하지 못했습니다 |

1772| `model_not_allowed` | 빠른 모드 Opus 모델이 조직의 [`availableModels`](/docs/ko/model-config#restrict-model-selection) 허용 목록에 없음 |1782| `model_not_allowed` | 빠른 모드 Opus 모델이 조직의 [`availableModels`](/docs/ko/model-config#restrict-model-selection) 허용 목록에 없습니다 |

1773| `sdk_opt_in_required` | 세션이 빠른 모드에 옵트인하지 않음: [`settings`](#options) 옵션 또는 [`applyFlagSettings()`](#applyflagsettings)를 통해 `fastMode: true`를 전달하세요 |1783| `sdk_opt_in_required` | 세션이 빠른 모드를 옵트인하지 않았습니다. [`settings`](#options) 옵션 또는 [`applyFlagSettings()`](#applyflagsettings)를 통해 `fastMode: true`를 전달하세요 |

1775 1785

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

1777 1787

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

1779 1789

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

1781 1791

1782필드는 시작 오류 같은 사용자 턴 전에 내보낸 결과에는 없습니다.1792시작 오류처럼 사용자 턴 이전에 발생한 결과에는 이 필드가 없습니다.

1783 1793

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

1785 1795

1786<h4 id="user_message_uuid">1796<h4 id="user_message_uuid">

1787 `user_message_uuid`1797 `user_message_uuid`

1788</h4>1798</h4>

1789 1799

1790턴이 답변하는 [`SDKUserMessage`](#sdkusermessage)의 `uuid`이며, Claude Code의 회신을 보낸 메시지와 일치시킬 수 있도록 에코됩니다. Claude Code는 메시지에 설정한 경우에만 `uuid`를 에코합니다. 필드는 `SDKUserMessage`에서 선택 사항이며, `query()`에 전달된 문자열 프롬프트는 이를 전달하지 않습니다.1800턴이 응답하는 [`SDKUserMessage`](#sdkusermessage)의 `uuid`로, Claude Code의 응답을 사용자가 보낸 메시지와 매칭할 수 있도록 그대로 반환됩니다. Claude Code는 메시지에 `uuid`를 설정한 경우에만 이를 반환합니다. 이 필드는 `SDKUserMessage`에서 선택 사항이며, `query()`에 전달된 문자열 프롬프트에는 포함되지 않습니다.

1791 1801

1792턴이 답변하는 메시지는 턴이 시작된 방식에 따라 다릅니다:1802턴이 어떤 메시지에 응답하는지는 턴이 시작된 방식에 따라 다릅니다.

1793 1803

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

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

1796* **Claude Code가 [`CLAUDE_CODE_RESUME_INTERRUPTED_TURN`](/docs/ko/env-vars) 아래에서 중단된 턴을 다시 실행하기 위해 생성하는 프롬프트**: 중단된 턴의 마지막 프롬프트가 보낸 일반 메시지일 때, 턴을 열었는지 또는 Claude Code가 턴 중에 선택했는지 여부에 관계없이, 다시 실행은 처음에 해당 메시지에 답변합니다. [`resume_reason`](#resume_reason)은 다시 실행의 프레임을 중단된 시도의 프레임과 구별해 줍니다. 마지막 프롬프트가 보낸 일반 메시지가 아닐 때, 다시 실행은 처음에 보낸 메시지에 답변하지 않습니다. Claude Code가 도구 호출 사이에 일반 메시지를 선택하면, 턴은 그 이후로 선택된 메시지에 답변합니다. 중단된 턴의 프롬프트를 에코하려면 Agent SDK v0.3.268 이상이 필요합니다.1806* **[`CLAUDE_CODE_RESUME_INTERRUPTED_TURN`](/docs/ko/env-vars)에 따라 중단된 턴을 다시 실행하기 위해 Claude Code가 생성한 프롬프트**: 중단된 턴의 마지막 프롬프트가 사용자가 보낸 일반 메시지인 경우, 그것이 턴을 시작했든 Claude Code가 턴 중에 받아들였든 재실행은 처음에 해당 메시지에 응답합니다. [`resume_reason`](#resume_reason)으로 재실행의 프레임과 중단된 시도의 프레임을 구별할 수 있습니다. 마지막 프롬프트가 사용자의 일반 메시지가 아니면, 재실행은 처음에 사용자의 어떤 메시지에도 응답하지 않습니다. Claude Code가 도구 호출 사이에 사용자의 일반 메시지를 받아들이면, 그때부터 턴은 받아들인 메시지에 응답합니다. 중단된 턴의 프롬프트를 반환하려면 Agent SDK v0.3.268 이상이 필요합니다.

1797* **Claude Code가 자체적으로 생성한 다른 프롬프트**: 턴은 처음에 보낸 메시지에 답변하지 않으며 프레임은 에코를 전달하지 않습니다. Claude Code가 도구 호출 사이에 일반 메시지를 선택하면, 턴은 그 이후로 해당 메시지에 답변합니다. 선택 에코는 Agent SDK v0.3.265 이상이 필요합니다. 이전 버전은 이러한 턴에서 아무것도 에코하지 않습니다.1807* **Claude Code가 자체적으로 생성한 기타 프롬프트**: 턴은 처음에 사용자의 어떤 메시지에도 응답하지 않으며 프레임에 반환 값이 없습니다. Claude Code가 도구 호출 사이에 사용자의 일반 메시지를 받아들이면, 그때부터 턴은 해당 메시지에 응답합니다. 받아들인 메시지의 반환에는 Agent SDK v0.3.265 이상이 필요하며, 이전 버전은 이러한 턴에서 아무것도 반환하지 않습니다.

1798 1808

1799Claude Code는 세 가지 종류의 프레임에서 답변된 메시지의 `uuid`를 에코합니다:1809Claude Code는 응답한 메시지의 `uuid`를 세 종류의 프레임에 반환합니다.

1800 1810

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

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

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

1804 1814

1805Claude Code는 다음 경우에 필드를 생략합니다:1815Claude Code는 다음 경우에 이 필드를 생략합니다.

1806 1816

1807* 첫 번째 회신 이외의 회신 프레임1817* 위의 첫 번째 응답 이외의 응답 프레임

1808* 서브에이전트 프레임1818* 서브에이전트 프레임

1809* 보낸 메시지에 답변하지 않거나 `uuid` 없이 보낸 메시지에 답변하는 턴1819* 사용자의 어떤 메시지에도 응답하지 않거나, `uuid` 없이 보낸 메시지에 응답하는 턴

1810* 충돌한 워커 프로세스 후 0으로 설정된 결과 같은 보낸 메시지에 답변하지 않는 결과1820* 충돌한 워커 프로세스 이후의 0으로 초기화된 결과처럼, 사용자가 보낸 어떤 메시지에도 응답하지 않는 결과

1811 1821

1812<h4 id="user_message_uuids">1822<h4 id="user_message_uuids">

1813 `user_message_uuids`1823 `user_message_uuids`

1814</h4>1824</h4>

1815 1825

1816Claude Code가 이 턴에서 답변한 모든 메시지의 `uuid`입니다. 여러 메시지를 가깝게 보낼 때, Claude Code는 이를 하나의 턴으로 병합할 수 있으며, `user_message_uuid`는 마지막 메시지만 명명합니다. 병합된 메시지 중 하나와 회신을 일치시키려면, 이 목록의 어디든 해당 메시지의 `uuid`를 찾으세요. Agent SDK v0.3.259 이상이 필요합니다.1826이 턴에서 Claude Code가 응답한, 사용자가 보낸 모든 메시지의 `uuid`입니다. 여러 메시지를 짧은 간격으로 보내면 Claude Code가 이를 하나의 턴으로 병합할 수 있으며, 이때 `user_message_uuid`는 그중 마지막 메시지만 나타냅니다. 병합된 메시지 중 어느 것과든 응답을 매칭하려면 이 목록에서 해당 메시지의 `uuid`를 찾으세요. Agent SDK v0.3.259 이상이 필요합니다.

1817 1827

1818Claude Code는 해당 필드를 전달하는 각 회신 프레임과 결과에서 `user_message_uuid`와 함께 목록을 설정합니다. 답변된 메시지의 `uuid`를 에코하는 턴 프레임의 전체 집합과 각각이 필요로 하는 버전은 [`user_message_uuid`](#user_message_uuid)를 참조하세요. 목록은 항상 `user_message_uuid`를 포함하며 최대 64개 항목을 보유합니다.1828Claude Code는 `user_message_uuid` 필드를 가진 각 응답 프레임과 결과에 이 목록을 함께 설정합니다. 응답한 메시지의 `uuid`를 반환하는 턴 프레임의 전체 목록과 각각에 필요한 버전은 [`user_message_uuid`](#user_message_uuid)를 참조하세요. 목록에는 항상 `user_message_uuid`가 포함되며 최대 64개 항목을 담습니다.

1819 1829

1820Claude Code가 턴이 실행되는 동안 보낸 일반 메시지를 선택할 때, 해당 메시지의 `uuid`를 결과의 목록에 추가합니다.1830턴이 실행 중일 때 사용자가 보낸 일반 메시지를 Claude Code가 받아들이면, 해당 메시지의 `uuid`를 결과의 목록에 추가합니다.

1821 1831

1822첫 번째 회신이나 결과가 목록 없이 `user_message_uuid`를 전달할 때, 이전 Claude Code 버전에서 나온 것이므로 단일 필드로 대체하세요.1832첫 번째 응답이나 결과에 목록 없이 `user_message_uuid`만 있다면 이전 Claude Code 버전에서 온 것이므로 단일 필드를 사용하세요.

1823 1833

1824<h4 id="resume_reason">1834<h4 id="resume_reason">

1825 `resume_reason`1835 `resume_reason`

1826</h4>1836</h4>

1827 1837

1828Claude Code가 재시작 후 이 턴을 다시 실행한 이유입니다. Claude Code는 [`CLAUDE_CODE_RESUME_INTERRUPTED_TURN`](/docs/ko/env-vars) 아래에서 다시 실행한 턴에 이 필드를 설정하므로 다시 실행의 회신과 결과를 중단된 시도와 구별할 수 있습니다. Agent SDK v0.3.268 이상이 필요합니다.1838재시작 후 Claude Code가 이 턴을 다시 실행한 이유입니다. Claude Code는 [`CLAUDE_CODE_RESUME_INTERRUPTED_TURN`](/docs/ko/env-vars)에 따라 다시 실행한 턴에 이 필드를 설정하므로, 재실행의 응답과 결과를 중단된 시도의 것과 구별할 수 있습니다. Agent SDK v0.3.268 이상이 필요합니다.

1829 1839

1830Claude Code는 두 가지 종류의 프레임에 필드를 설정합니다:1840Claude Code는 두 종류의 프레임에 이 필드를 설정합니다.

1831 1841

1832* **다시 실행의 결과**: 성공 및 오류 팔 모두에서, 결과가 `user_message_uuid`를 전달하는지 여부에 관계없이.1842* **재실행의 결과**: 결과에 `user_message_uuid`가 있든 없든 success와 error 분기 모두에 설정합니다.

1833* **다시 실행의 회신 프레임**: [`user_message_uuid`](#user_message_uuid)를 전달하는 것들.1843* **재실행의 응답 프레임**: [`user_message_uuid`](#user_message_uuid)를 가진 프레임입니다.

1834 1844

1835값은 `interrupted_turn` 같이 턴이 다시 실행된 이유를 명명하는 짧은 소문자 토큰입니다. 필드는 다른 모든 턴에는 없습니다.1845값은 턴이 다시 실행된 이유를 나타내는 짧은 소문자 토큰이며, `interrupted_turn` 등이 있습니다. 다른 모든 턴에는 이 필드가 없습니다.

1836 1846

1837<h4 id="queued_turn_count">1847<h4 id="queued_turn_count">

1838 `queued_turn_count`1848 `queued_turn_count`

1839</h4>1849</h4>

1840 1850

1841Claude Code가 결과를 생성했을 때 [`origin: { kind: "human" }`](#sdkmessageorigin)으로 보낸 메시지 중 명령 큐에서 여전히 대기 중인 메시지의 수입니다. Agent SDK v0.3.242 이상이 필요합니다.1851Claude Code가 결과를 생성한 시점에 명령 대기열에서 아직 대기 중인, 사용자가 [`origin: { kind: "human" }`](#sdkmessageorigin)으로 보낸 메시지의 수입니다. Agent SDK v0.3.242 이상이 필요합니다.

1842 1852

1843`0`과 없는 필드가 무엇을 의미하는지:1853`0`과 필드가 없는 경우의 의미는 다음과 같습니다.

1844 1854

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

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

1847 1857

1848<h4 id="startup_failure_reason">1858<h4 id="startup_failure_reason">

1849 `startup_failure_reason`1859 `startup_failure_reason`

1850</h4>1860</h4>

1851 1861

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

1853 1863

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

1855 1865

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

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

1858 1868

1859```typescript theme={null}1869```typescript theme={null}

1860type SDKStartupFailureReason =1870type SDKStartupFailureReason =

1877 | "bypass_root";1887 | "bypass_root";

1878```1888```

1879 1889

1880각 값은 하나의 거부를 명명합니다:1890각 값은 하나의 거부 사유를 나타냅니다.

1881 1891

1882| 값 | 세션을 중지한 것 |1892| 값 | 세션을 중단시킨 원인 |

1883| :- | :- |1893| :- | :- |

1884| `org_pin_api_key_conflict` | 관리형 설정이 [퍼스트 파티 또는 Cloud 게이트웨이 로그인](/docs/ko/authentication#restrict-login-to-your-organization)을 요구하며, Anthropic API 키, 인증 토큰, 또는 `apiKeyHelper`가 대신 구성됨 |1894| `org_pin_api_key_conflict` | 관리형 설정이 [퍼스트 파티 또는 Cloud 게이트웨이 로그인을 요구](/docs/ko/authentication#restrict-login-to-your-organization)하는데, 대신 Anthropic API 키, 인증 토큰 또는 `apiKeyHelper`가 구성되어 있습니다 |

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

1888| `managed_settings_invalid` | 관리형 정책 설정을 읽을 수 없음, 핀이 조직을 명명하지 않음, 또는 [관리형 모델 제한](/docs/ko/errors#managed-settings-block-the-default-model)이 기본 옵션에 대해 허용된 모델을 남기지 않음 |1898| `managed_settings_invalid` | 관리형 정책 설정을 읽을 수 없거나, 고정값에 조직이 지정되지 않았거나, [관리형 모델 제한](/docs/ko/errors#managed-settings-block-the-default-model)으로 인해 Default 옵션에 허용되는 모델이 없습니다 |

1891| `gateway_access_denied` | Cloud 게이트웨이에 대한 관리형 설정 요청이 403으로 돌아옴(게이트웨이의 [문제 해결 테이블](/docs/ko/claude-apps-gateway-deploy#troubleshooting)이 다룸) |1901| `gateway_access_denied` | Cloud 게이트웨이에 대한 관리형 설정 요청이 403으로 반환되었으며, 이는 게이트웨이의 [문제 해결 표](/docs/ko/claude-apps-gateway-deploy#troubleshooting)에서 다룹니다 |

1895| `shell_tool_missing` | Windows에서 사용 가능한 셸 도구가 없음: Git Bash가 없으며, PowerShell이 없거나 `CLAUDE_CODE_USE_POWERSHELL_TOOL`로 꺼짐 |1905| `shell_tool_missing` | Windows에서 사용할 수 있는 셸 도구가 없습니다. Git Bash가 없고, PowerShell이 없거나 `CLAUDE_CODE_USE_POWERSHELL_TOOL`로 꺼져 있습니다 |

1897| `worktree_resume_refused` | 세션의 워크트리가 안전 검사에 실패했거나, 재개가 워크트리 내부에서 시작됨. `errors`는 동일한 재개를 다시 실행하면 워크트리 없이 계속되는지 알려줌 |1907| `worktree_resume_refused` | 세션의 worktree가 안전 검사에 실패했거나, 재개가 worktree 내부에서 시작되었습니다. 같은 재개를 다시 실행하면 worktree 없이 계속되는지 여부는 `errors`에 나옵니다 |

1901 1911

1902<h3 id="sdksystemmessage">1912<h3 id="sdksystemmessage">

1903 `SDKSystemMessage`1913 `SDKSystemMessage`

1942};1952};

1943```1953```

1944 1954

1945`fast_mode_state`는 세션의 [빠른 모드](/docs/ko/fast-mode) 상태를 보고합니다. 빠른 모드를 차단하는 것이 있을 때, `fast_mode_disabled_reason`은 차단한 검사의 이름을 지정합니다. 필드는 Claude Code v2.1.219 이상이 필요합니다. 이유 코드와 의미는 결과 메시지의 [`fast_mode_disabled_reason`](#sdkresultmessage)을 참조하세요.1955`fast_mode_state`는 세션의 [빠른 모드](/docs/ko/fast-mode) 상태를 보고합니다. 빠른 모드를 막는 것이 있으면 `fast_mode_disabled_reason`이 이를 막은 검사를 나타내며, 이 필드에는 Claude Code v2.1.219 이상이 필요합니다. 이유 코드와 그 의미는 결과 메시지의 [`fast_mode_disabled_reason`](#sdkresultmessage)을 참조하세요.

1946 1956

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

1948 1958

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

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

1951 1961

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

1953 1963

1954| 기능 | 의미 |1964| Capability | 의미 |

1955| - | - |1965| - | - |

1956| `interrupt_receipt_v1` | [`interrupt()`](#query-object)는 중단이 도착했을 때 보류 중이던 메시지를 나열하는 [`SDKControlInterruptResponse`](#sdkcontrolinterruptresponse) 영수증으로 해결됨 |1966| `interrupt_receipt_v1` | [`interrupt()`](#query-object)가 인터럽트 도착 시점에 보류 중이던 메시지를 나열하는 [`SDKControlInterruptResponse`](#sdkcontrolinterruptresponse) 영수증으로 resolve됩니다 |

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

1968| `sdk_mcp_manifests` | `initialize` 제어 요청이 프로세스 내 [SDK MCP 서버](/docs/ko/agent-sdk/custom-tools)에서 캡처한 MCP 핸드셰이크 결과인 `sdkMcpServerManifests`를 받습니다. Claude Code는 v2.1.286 이상에서 이 capability를 알립니다 |

1969| `sdk_mcp_tools_list_changed` | [SDK MCP 서버](/docs/ko/agent-sdk/custom-tools)의 `tools/list_changed` 알림이 Claude Code가 해당 서버의 도구를 다시 나열하게 하므로, 서버가 세션 도중 추가한 도구가 Claude에 도달합니다. Claude Code는 v2.1.286 이상에서 이 capability를 알립니다 |

1958 1970

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

1960 1972

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

1962 1974

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

1964 1976

1965| 필드 | 타입 | 설명 |1977| 필드 | 타입 | 설명 |

1966| - | - | - |1978| - | - | - |

1971 1983

1972<h3 id="sdkpartialassistantmessage">1984<h3 id="sdkpartialassistantmessage">

1973 `SDKPartialAssistantMessage`1985 `SDKPartialAssistantMessage`

1974</h3>1986</h3>

1975 1987

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

1977 1989

1978```typescript theme={null}1990```typescript theme={null}

1979type SDKPartialAssistantMessage = {1991type SDKPartialAssistantMessage = {

1989};2001};

1990```2002```

1991 2003

1992Claude Code는 [`user_message_uuid`](#user_message_uuid)의 조건에 따라 턴의 첫 번째 비핑 스트림 이벤트에 `user_message_uuid`와 `user_message_uuids`를 설정하며, 턴이 답변하는 메시지가 변경될 때 다시 설정합니다. Claude Code가 재시작으로 중단된 턴을 다시 실행할 때, 이러한 필드를 전달하는 다시 실행된 스트림 이벤트도 [`resume_reason`](#resume_reason)을 전달합니다.2004Claude Code는 [`user_message_uuid`](#user_message_uuid)에 설명된 조건에 따라 턴의 ping이 아닌 첫 번째 스트림 이벤트에, 그리고 턴이 응답하는 메시지가 바뀔 때 다시 `user_message_uuid`와 `user_message_uuids`를 설정합니다. 재시작으로 중단된 턴을 Claude Code가 다시 실행할 때, 해당 필드를 가진 재실행의 스트림 이벤트에는 [`resume_reason`](#resume_reason)도 포함됩니다.

1993 2005

1994<h3 id="sdkcompactboundarymessage">2006<h3 id="sdkcompactboundarymessage">

1995 `SDKCompactBoundaryMessage`2007 `SDKCompactBoundaryMessage`

2014 `SDKInformationalMessage`2026 `SDKInformationalMessage`

2015</h3>2027</h3>

2016 2028

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

2018 2030

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

2020 2032

2021`content`를 주어진 `level`에서 평문으로 렌더링하세요.2033`content`를 주어진 `level`에 맞춰 일반 텍스트로 렌더링하세요.

2022 2034

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

2024type SDKInformationalMessage = {2036type SDKInformationalMessage = {

2037 `SDKWorkerShuttingDownMessage`2049 `SDKWorkerShuttingDownMessage`

2038</h3>2050</h3>

2039 2051

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

2041 2053

2042```typescript theme={null}2054```typescript theme={null}

2043type SDKWorkerShuttingDownMessage = {2055type SDKWorkerShuttingDownMessage = {

2053 `SDKPluginInstallMessage`2065 `SDKPluginInstallMessage`

2054</h3>2066</h3>

2055 2067

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

2057 2069

2058```typescript theme={null}2070```typescript theme={null}

2059type SDKPluginInstallMessage = {2071type SDKPluginInstallMessage = {

2071 `SDKPermissionDeniedMessage`2083 `SDKPermissionDeniedMessage`

2072</h3>2084</h3>

2073 2085

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

2075 2087

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

2077* **둘 다 없는 경우**: 단순 `-p` 실행 또는 `canUseTool`과 `permissionPromptToolName` 중 어느 것도 설정하지 않은 `query()`는 [`PermissionRequest` 훅](/docs/ko/hooks-guide#limitations)이 허용하지 않는 한 확인을 요청했을 도구 호출을 모두 거부하며, 이 이벤트는 이러한 거부와 Claude Code가 자체적으로 결정한 거부를 모두 보고합니다. v2.1.223 이전에는 콜백이 없는 실행에서 Claude Code가 이 이벤트를 생성하지 않았습니다.2089* **둘 다 없는 경우**: 단순 `-p` 실행, 또는 `canUseTool`과 `permissionPromptToolName`을 모두 설정하지 않은 `query()`는 [`PermissionRequest` 훅](/docs/ko/hooks-guide#limitations)이 허용하지 않는 한 프롬프트가 필요했을 모든 도구 호출을 거부하며, 이 이벤트는 Claude Code가 자체적으로 결정한 거부와 함께 이러한 거부도 보고합니다. v2.1.223 이전에는 콜백이 없는 실행에서 Claude Code가 이 이벤트를 내보내지 않았습니다.

2078* **MCP 프롬프트 도구**(`permissionPromptToolName` 또는 [`--permission-prompt-tool`](/docs/ko/cli-reference#cli-flags) 플래그로 설정)와 기본 `permissionPrompts: 'host'`: Claude Code는 자체적으로 결정한 규칙 거부에 대해서도 이 이벤트를 전혀 내보내지 않습니다.2090* **MCP 프롬프트 도구**를 `permissionPromptToolName` 또는 [`--permission-prompt-tool`](/docs/ko/cli-reference#cli-flags) 플래그로 설정하고 기본값 `permissionPrompts: 'host'`를 사용하는 경우: Claude Code는 자체적으로 결정한 규칙 거부를 포함하여 이 이벤트를 전혀 내보내지 않습니다.

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

2080 2092

2081모든 구성에서 이 이벤트는 `PreToolUse` 훅 경로에서 결정된 거부를 건너뜁니다. 훅이 호출을 직접 거부했는지 또는 거부 규칙이 훅의 허용 또는 요청 결정을 재정의했는지는 관계없습니다. 이벤트는 또한 최선의 노력 방식입니다: 가끔 Claude Code는 이 이벤트를 내보내지 않고 거부를 기록하므로 [결과 메시지](#sdkresultmessage)의 `permission_denials`이 권위 있는 기록입니다.2093모든 구성에서 이 이벤트는 `PreToolUse` 훅 경로에서 결정된 거부를 건너뜁니다. 훅이 호출 자체를 거부했든, 거부 규칙이 훅의 allow 또는 ask 결정을 재정의했든 마찬가지입니다. 또한 이 이벤트는 최선의 노력 방식으로 제공됩니다. 간혹 Claude Code가 이 이벤트를 내보내지 않고 거부를 기록할 수 있으므로, [결과 메시지](#sdkresultmessage)의 `permission_denials`가 공식적인 기록입니다.

2082 2094

2083```typescript theme={null}2095```typescript theme={null}

2084type SDKPermissionDeniedMessage = {2096type SDKPermissionDeniedMessage = {

2097 2109

2098| 필드 | 타입 | 설명 |2110| 필드 | 타입 | 설명 |

2099| - | - | - |2111| - | - | - |

2106 2118

2107<h3 id="sdkpermissiondenial">2119<h3 id="sdkpermissiondenial">

2108 `SDKPermissionDenial`2120 `SDKPermissionDenial`

2122 `SDKContextUsage`2134 `SDKContextUsage`

2123</h3>2135</h3>

2124 2136

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

2126 2138

2127```typescript theme={null}2139```typescript theme={null}

2128type SDKContextUsage = {2140type SDKContextUsage = {

2159};2171};

2160```2172```

2161 2173

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

2163 2175

2164| 필드 | 타입 | 설명 |2176| 필드 | 타입 | 설명 |

2165| - | - | - |2177| - | - | - |

2168| `raw_max_tokens` | `number` | 모델의 컨텍스트 윈도우 또는 적용되는 경우 더 낮은 [자동 압축 윈도우](/docs/ko/model-config#context-window-and-auto-compaction)(예: 직접 설정한 것 또는 1M 토큰 윈도우가 있는 일부 모델에 Claude Code가 적용하는 200K 경계). Claude Code는 `total_tokens`를 이 윈도우에 대해 측정 |2180| `raw_max_tokens` | `number` | 모델의 컨텍스트 윈도우이며, 더 낮은 [자동 압축 윈도우](/docs/ko/model-config#context-window-and-auto-compaction)가 적용되는 경우 그 값입니다. 예를 들어 사용자가 설정한 값이나, 1M 토큰 윈도우를 가진 일부 모델에 Claude Code가 적용하는 200K 경계가 있습니다. Claude Code는 이 윈도우를 기준으로 `total_tokens`를 측정합니다 |

2176 2188

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

2178 2190

2179* `hard_limit`: 윈도우는 Claude Code가 모델 자체의 제한이라고 판단한 것이며, 이를 넘으면 API가 요청을 거부함2191* `hard_limit`: 윈도우가 Claude Code가 판단하는 모델 자체의 한도이며, 이를 넘으면 API가 요청을 거부합니다

2180* `compaction_window`: 윈도우는 압축 정책 윈도우이며, 모델의 제한과 일치할 수도 있고 아닐 수도 있음2192* `compaction_window`: 윈도우가 압축 정책 윈도우이며, 모델의 한도와 일치할 수도 있고 그렇지 않을 수도 있습니다

2181 2193

2182Claude Code는 기존 필드를 재구성하는 대신 새 데이터를 선택적 필드로 추가하는 방식으로 타입을 점진적으로 발전시킵니다. 알고 있는 필드를 읽고 인식하지 못하는 필드는 무시하세요.2194Claude Code는 기존 필드의 형태를 바꾸는 대신 새 데이터를 선택적 필드로 추가하는 방식으로 이 타입을 확장합니다. 알고 있는 필드를 읽고 인식하지 못하는 필드는 무시하세요.

2183 2195

2184<h3 id="sdkcontextusagecategory">2196<h3 id="sdkcontextusagecategory">

2185 `SDKContextUsageCategory`2197 `SDKContextUsageCategory`

2186</h3>2198</h3>

2187 2199

2188`/context` 범주별 사용량 분석의 한 행입니다.2200`/context` 범주별 사용량 세부 내역의 한 행입니다.

2189 2201

2190```typescript theme={null}2202```typescript theme={null}

2191type SDKContextUsageCategory = {2203type SDKContextUsageCategory = {

2195};2207};

2196```2208```

2197 2209

2198테이블은 행의 각 필드에 Claude Code가 넣는 것을 나열합니다.2210다음 표는 Claude Code가 행의 각 필드에 넣는 내용을 나열합니다.

2199 2211

2200| 필드 | 타입 | 설명 |2212| 필드 | 타입 | 설명 |

2201| - | - | - |2213| - | - | - |

2205 2217

2206각 `kind` 값은 행의 토큰이 무엇인지 나타냅니다:2218각 `kind` 값은 행의 토큰이 무엇인지를 나타냅니다.

2207 2219

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

2209* `free`: 남은 윈도우2221* `free`: 남은 윈도우

2210* `buffer`: 압축 예비 공간2222* `buffer`: 압축 예비 공간

2211* `deferred`: Claude Code가 윈도우 밖에 보유하고 사용량 계산에서 제외하는 도구 스키마이며, 참고용으로 나열됨2223* `deferred`: Claude Code가 윈도우 밖에 보관하고 사용량 계산에서 제외하는 도구 스키마로, 참고용으로 나열됩니다

2212 2224

2213<h3 id="sdkmessageorigin">2225<h3 id="sdkmessageorigin">

2214 `SDKMessageOrigin`2226 `SDKMessageOrigin`

2215</h3>2227</h3>

2216 2228

2217사용자 역할 메시지의 출처입니다. 이는 [`SDKUserMessage`](#sdkusermessage)에서 `origin`으로 나타나며 해당 [`SDKResultMessage`](#sdkresultmessage)로 전달되므로 주어진 턴을 무엇이 트리거했는지 알 수 있습니다.2229사용자 역할 메시지의 출처입니다. 이는 [`SDKUserMessage`](#sdkusermessage)에 `origin`으로 나타나며, 해당하는 [`SDKResultMessage`](#sdkresultmessage)로 전달되므로 특정 턴을 무엇이 트리거했는지 알 수 있습니다.

2218 2230

2219```typescript theme={null}2231```typescript theme={null}

2220type SDKMessageOrigin =2232type SDKMessageOrigin =

2242 2254

2243| `kind` | 의미 |2255| `kind` | 의미 |

2244| - | - |2256| - | - |

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

2247| `peer` | 다른 에이전트의 메시지: 프로세스 내 [팀원](/docs/ko/agent-teams) 또는 [교차 세션 피어](/docs/ko/cross-session-messaging), 즉 다른 Claude Code 세션. 필드별 의미와 신뢰 모델은 [피어 origin 필드](#peer-origin-fields)를 참조하세요. |2259| `peer` | 다른 에이전트의 메시지입니다. 프로세스 내 [팀원](/docs/ko/agent-teams) 또는 사용자의 다른 Claude Code 세션인 [세션 간 피어](/docs/ko/cross-session-messaging)가 해당합니다. 필드별 의미와 신뢰 모델은 [피어 origin 필드](#peer-origin-fields)를 참조하세요. |

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

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

2252 2264

2253<h3 id="task-notification-subkinds">2265<h3 id="task-notification-subkinds">

2254 작업 알림 서브종류2266 Task-notification 하위 유형

2255</h3>2267</h3>

2256 2268

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

2258 2270

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

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

2261 2273

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

2263 2275

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

2265 2277

2266<h4 id="declare-a-scheduled-run">2278<h4 id="declare-a-scheduled-run">

2267 예약된 실행 선언2279 예약 실행 선언

2268</h4>2280</h4>

2269 2281

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

2271 2283

2272<h3 id="peer-origin-fields">2284<h3 id="peer-origin-fields">

2273 피어 origin 필드2285 Peer origin 필드

2274</h3>2286</h3>

2275 2287

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

2277 2289

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

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

2280* `senderTaskId`: 팀원의 작업 ID. 교차 세션 피어에는 없습니다.2292* `senderTaskId`: 팀원의 작업 ID입니다. cross-session peer의 경우에는 존재하지 않습니다.

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

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

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

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

2285 2297

2286<h2 id="hook-types">2298<h2 id="hook-types">

2287 훅 타입2299 훅 타입

agent-view.md +5 −2

Details

347 347

348필터를 결합하려면 `a:`, `s:`, `n:` 또는 `o:`로 시작하고 공백으로 구분하여 더 추가합니다. 목록은 모든 필터와 일치하는 세션을 표시합니다. 예를 들어 `s:blocked a:reviewer`는 입력을 기다리는 `reviewer` 세션을 나열합니다.348필터를 결합하려면 `a:`, `s:`, `n:` 또는 `o:`로 시작하고 공백으로 구분하여 더 추가합니다. 목록은 모든 필터와 일치하는 세션을 표시합니다. 예를 들어 `s:blocked a:reviewer`는 입력을 기다리는 `reviewer` 세션을 나열합니다.

349 349

350필터가 활성화된 동안 축소한 그룹은 일치 항목을 표시하도록 펼쳐지고 첫 번째 일치 항목이 선택되므로 `Enter`를 누르면 이를 엽니다. 입력을 지우면 필터가 제거되고 해당 그룹은 다시 축소됩니다.350필터가 활성화된 동안 축소한 그룹은 일치 항목을 표시하도록 펼쳐지고 일치 항목이 선택되므로 `Enter`를 누르면 이를 엽니다. 입력을 지우면 필터가 제거되고 해당 그룹은 다시 축소됩니다.

351 351

352<h3 id="keyboard-shortcuts">352<h3 id="keyboard-shortcuts">

353 키보드 단축키353 키보드 단축키

369| `Tab` | 빈 입력에서 모든 서브에이전트 검색. 그 외에는 강조된 제안 적용 |369| `Tab` | 빈 입력에서 모든 서브에이전트 검색. 그 외에는 강조된 제안 적용 |

372| `Ctrl+F` | [`n:` 필터](#filter-sessions)로 이름으로 세션 찾기 |

373| `Alt+↑` / `Alt+↓` | 이전 또는 다음 그룹 헤더로 이동 |

379| `?` | 모든 단축키 표시 |381| `?` | 모든 단축키 표시 |

380 382

381`Ctrl+S`, `Ctrl+T` 및 `Ctrl+G`는 [`keybindings.json`](/docs/ko/keybindings)을 따릅니다. [`Agents` 컨텍스트](/docs/ko/keybindings#agents-actions)의 `agents:switchView` 및 `agents:togglePin` 작업으로 `Ctrl+S` 및 `Ctrl+T`를 다시 바인딩하거나 바인딩 해제하고, `Chat` 컨텍스트의 `chat:externalEditor` 바인딩을 통해 `Ctrl+G`를 다시 바인딩합니다. 표의 다른 단축키는 다시 바인딩할 수 없습니다.383[`Agents` 컨텍스트](/docs/ko/keybindings#agents-actions)에 작업이 있는 단축키는 [`keybindings.json`](/docs/ko/keybindings)을 따릅니다. `Ctrl+G`도 `Chat` 컨텍스트의 `chat:externalEditor` 바인딩을 통해 마찬가지로 따릅니다.

382 384

383<h2 id="dispatch-new-agents">385<h2 id="dispatch-new-agents">

384 새로운 에이전트 디스패치386 새로운 에이전트 디스패치

1087 1089

1088| 버전 | 변경 사항 |1090| 버전 | 변경 사항 |

1089| - | - |1091| - | - |

1092| v2.1.288 | `Ctrl+F`는 이름으로 세션을 찾고, `Alt+↑` / `Alt+↓`는 그룹 헤더 사이를 이동합니다. 이 두 가지와 `Ctrl+R`은 [다시 바인딩](/docs/ko/keybindings#agents-actions)할 수 있습니다. |

1090| v2.1.287 | [`n:<text>` 필터](#filter-sessions)는 이름이나 첫 프롬프트로 세션을 찾습니다. 필터가 활성화되어 있는 동안에는 접어 둔 그룹이 펼쳐져 일치 항목을 표시하고 첫 번째 일치 항목이 선택되므로 `Enter`로 바로 열 수 있습니다. |1093| v2.1.287 | [`n:<text>` 필터](#filter-sessions)는 이름이나 첫 프롬프트로 세션을 찾습니다. 필터가 활성화되어 있는 동안에는 접어 둔 그룹이 펼쳐져 일치 항목을 표시하고 첫 번째 일치 항목이 선택되므로 `Enter`로 바로 열 수 있습니다. |

1091| v2.1.287 | [엿보기 회신](#peek-and-reply)으로 보낸 명령은 세션의 현재 턴이 끝날 때 실행되며, 세션 자체 프롬프트에서 입력하는 즉시 실행되는 명령도 마찬가지입니다. 정확히 `/stop`인 회신은 세션을 즉시 중지합니다. |1094| v2.1.287 | [엿보기 회신](#peek-and-reply)으로 보낸 명령은 세션의 현재 턴이 끝날 때 실행되며, 세션 자체 프롬프트에서 입력하는 즉시 실행되는 명령도 마찬가지입니다. 정확히 `/stop`인 회신은 세션을 즉시 중지합니다. |

1092| v2.1.281 | [`--setting-sources`](/docs/ko/cli-reference#cli-flags) 제한이 `←` 또는 `/bg`로 백그라운드하는 세션과 에이전트 뷰에서 디스패치하는 세션으로 [이월](#what-carries-over-when-you-background)됩니다. 이 릴리스 이전에는 생성된 세션이 모든 설정 소스를 로드했습니다. |1095| v2.1.281 | [`--setting-sources`](/docs/ko/cli-reference#cli-flags) 제한이 `←` 또는 `/bg`로 백그라운드하는 세션과 에이전트 뷰에서 디스패치하는 세션으로 [이월](#what-carries-over-when-you-background)됩니다. 이 릴리스 이전에는 생성된 세션이 모든 설정 소스를 로드했습니다. |

amazon-bedrock.md +17 −0

Details

386 386

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

388 388

389<h3 id="when-your-organization-enforces-a-model-allowlist">

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

391</h3>

392

393관리형 설정에서 [`enforceAvailableModels`](/docs/ko/model-config#enforce-the-allowlist-for-the-default-model)를 설정하면, 시작 모델 확인은 `availableModels` 목록에서 허용하는 모델만 사용합니다. 이는 Amazon Bedrock Invoke API에 적용되며 Claude Code v2.1.287 이상이 필요합니다. `enforceAvailableModels`가 없는 목록은 이러한 확인을 제한하지 않습니다.

394

395확인 과정에서는 각 항목을 전송할 추론 프로필 ID([리전 접두사](#cross-region-inference-profile-prefixes) 포함)와 비교하므로, 목록을 해당 ID로 작성합니다. 다음 예시는 모델이 `us.` 프로필로 확인되는 배포에서 Opus 4.8과 Sonnet 4.5를 허용합니다.

396

397```json theme={null}

398{

399 "availableModels": ["us.anthropic.claude-opus-4-8", "us.anthropic.claude-sonnet-4-5-20250929-v1:0"],

400 "enforceAvailableModels": true

401}

402```

403

404별칭, 버전 접두사 및 `modelOverrides` 항목에 대해서는 [타사 배포를 위한 모델 고정](/docs/ko/model-config#pin-models-for-third-party-deployments)을 참조하세요.

405

389<h3 id="when-a-model-is-disabled-mid-session">406<h3 id="when-a-model-is-disabled-mid-session">

390 세션 중에 모델이 비활성화될 때407 세션 중에 모델이 비활성화될 때

391</h3>408</h3>

artifacts.md +3 −1

Details

156 Claude가 댓글에 자동으로 답변하도록 허용156 Claude가 댓글에 자동으로 답변하도록 허용

157</h3>157</h3>

158 158

159세션이 아티팩트를 게시한 후 Claude Code는 세션이 실행되는 동안 해당 아티팩트의 댓글을 감시합니다. 아티팩트를 편집할 수 있는 사람이 Claude에게 댓글을 보내면 즉시 세션에 도달하고, Claude는 스레드를 읽고 당신이 요청하지 않아도 답변할 수 있습니다.159세션이 아티팩트를 게시한 후 Claude Code는 해당 아티팩트의 댓글을 감시합니다. 아티팩트를 편집할 수 있는 사람이 Claude에게 댓글을 보내면 즉시 세션에 도달하고, Claude는 사용자가 요청하지 않아도 스레드를 읽고 답변할 수 있습니다.

160 160

161Claude Code v2.1.228 이상이 필요합니다. [기능 플래그 가져오기](/docs/ko/env-vars#features-that-need-feature-flag-fetching)를 끄면 Claude Code는 댓글을 감시하지 않습니다.161Claude Code v2.1.228 이상이 필요합니다. [기능 플래그 가져오기](/docs/ko/env-vars#features-that-need-feature-flag-fetching)를 끄면 Claude Code는 댓글을 감시하지 않습니다.

162 162

174* **`/tasks`에서 작업을 중지합니다**: Claude는 당신이 해당 아티팩트에서 답변을 재개하도록 요청할 때까지 해당 아티팩트에 답변하는 것을 중지합니다. 아티팩트를 다시 게시해도 답변이 다시 시작되지 않으며, 세션을 재개할 때도 중지가 계속 적용됩니다.174* **`/tasks`에서 작업을 중지합니다**: Claude는 당신이 해당 아티팩트에서 답변을 재개하도록 요청할 때까지 해당 아티팩트에 답변하는 것을 중지합니다. 아티팩트를 다시 게시해도 답변이 다시 시작되지 않으며, 세션을 재개할 때도 중지가 계속 적용됩니다.

175* **3초 내에 `Ctrl+X Ctrl+K`를 두 번 누릅니다**: [모든 실행 중인 백그라운드 서브에이전트를 중지](/docs/ko/interactive-mode#general-controls)하는 코드는 또한 Claude가 세션의 나머지 기간 동안 모든 아티팩트에 답변하는 것을 중지합니다. Claude에게 답변을 재개하도록 요청해도 이 중지는 취소되지 않습니다.175* **3초 내에 `Ctrl+X Ctrl+K`를 두 번 누릅니다**: [모든 실행 중인 백그라운드 서브에이전트를 중지](/docs/ko/interactive-mode#general-controls)하는 코드는 또한 Claude가 세션의 나머지 기간 동안 모든 아티팩트에 답변하는 것을 중지합니다. Claude에게 답변을 재개하도록 요청해도 이 중지는 취소되지 않습니다.

176 176

177Claude Code가 자동으로 시작한 감시는 아티팩트에 몇 시간 동안 활동이 없으면 종료될 수 있습니다. 감시를 다시 시작하려면 아티팩트를 다시 게시하거나 Claude에게 감시하도록 요청하십시오.

178

177댓글을 전달하는 서비스를 사용할 수 없거나 응답을 중지하면 Claude Code는 한동안 다시 연결을 시도한 후 세션이 감시 중이던 각 아티팩트 감시를 중지합니다.179댓글을 전달하는 서비스를 사용할 수 없거나 응답을 중지하면 Claude Code는 한동안 다시 연결을 시도한 후 세션이 감시 중이던 각 아티팩트 감시를 중지합니다.

178 180

179<h2 id="pull-live-data-with-mcp-connectors">181<h2 id="pull-live-data-with-mcp-connectors">

best-practices.md +21 −22

Details

486</h3>486</h3>

487 487

488<Tip>488<Tip>

489 CI, pre-commit hooks 또는 스크립트에서 `claude -p "prompt"`를 사용하십시오. 스트리밍 JSON 출력의 경우 `--output-format stream-json --verbose`를 추가하십시오.489 CI, pre-commit 훅 또는 스크립트에서 `claude -p "prompt"`를 사용하십시오. 스트리밍 JSON 출력의 경우 `--output-format stream-json --verbose`를 추가하십시오.

490</Tip>490</Tip>

491 491

492`claude -p "your prompt"`를 사용하면 대화형 프롬프트 없이 비대화형으로 Claude를 실행할 수 있습니다. 실행은 `--no-session-persistence`를 전달하지 않는 한 여전히 재개 가능한 세션을 생성합니다. [비대화형 모드](/docs/ko/headless)는 Claude를 CI 파이프라인, pre-commit hooks 또는 자동화된 워크플로우에 통합하는 방법입니다. 출력 형식을 사용하면 결과를 프로그래밍 방식으로 구문 분석할 수 있습니다: 일반 텍스트, JSON 또는 스트리밍 JSON.492`claude -p "your prompt"`를 사용하면 대화형 프롬프트 없이 비대화형으로 Claude를 실행할 수 있습니다. 실행은 `--no-session-persistence`를 전달하지 않는 한 여전히 재개 가능한 세션을 생성합니다. [비대화형 모드](/docs/ko/headless)는 Claude를 CI 파이프라인, pre-commit 훅 또는 자동화된 워크플로에 통합하는 방법입니다. 출력 형식을 사용하면 결과를 프로그래밍 방식으로 구문 분석할 수 있습니다: 일반 텍스트, JSON 또는 스트리밍 JSON.

493 493

494```bash theme={null}494```bash theme={null}

495# 일회성 쿼리495# 일회성 쿼리

509</h3>509</h3>

510 510

511<Tip>511<Tip>

512 개발 속도를 높이거나, 격리된 실험을 실행하거나, 복잡한 워크플로우를 시작하기 위해 여러 Claude 세션을 병렬로 실행하십시오.512 개발 속도를 높이거나, 격리된 실험을 실행하거나, 복잡한 워크플로를 시작하기 위해 여러 Claude 세션을 병렬로 실행하십시오.

513</Tip>513</Tip>

514 514

515조정하고 싶은 정도에 맞는 병렬 접근 방식을 선택하고, 세션이 서로 발견 사항을 전달해야 할 때 메시징을 추가하십시오:515조정하고 싶은 정도에 맞는 병렬 접근 방식을 선택하고, 세션이 서로 발견 사항을 전달해야 할 때 메시징을 추가하십시오:

516 516

517* [Worktrees](/docs/ko/worktrees): 격리된 git 체크아웃에서 별도의 CLI 세션을 실행하여 편집이 충돌하지 않도록 합니다517* [Worktrees](/docs/ko/worktrees): 격리된 git 체크아웃에서 별도의 CLI 세션을 실행하여 편집이 충돌하지 않도록 합니다

518* [Cross-session messaging](/docs/ko/cross-session-messaging): 직접 실행하는 세션이 서로 발견 사항을 전달할 수 있도록 합니다518* [Cross-session messaging](/docs/ko/cross-session-messaging): 직접 실행하는 세션이 서로 발견 사항을 전달할 수 있도록 합니다

519* [데스크톱 앱](/docs/ko/desktop#work-in-parallel-with-sessions): 여러 로컬 세션을 시각적으로 관리하십시오. 각 세션은 자신의 worktree에 있습니다519* [데스크톱 앱](/docs/ko/desktop#work-in-parallel-with-sessions): 여러 로컬 세션을 시각적으로 관리합니다. 선택적으로 각 세션을 자체 worktree에서 실행할 수 있습니다

520* [웹의 Claude Code](/docs/ko/claude-code-on-the-web): 클라우드에서 세션을 실행하십시오. 기본적으로 Anthropic이 관리하는 인프라에서 실행됩니다520* [클라우드에서 Claude Code 사용하기](/docs/ko/claude-code-on-the-web): 기본적으로 Anthropic이 관리하는 인프라에서 세션을 실행합니다

521* [Agent view](/docs/ko/agent-view): 연구 미리보기입니다. `claude agents`를 실행하여 백그라운드에서 계속 실행되는 세션을 디스패치하고 한 화면에서 감시합니다521* [Agent view](/docs/ko/agent-view): 리서치 프리뷰입니다. `claude agents`를 실행하여 백그라운드에서 계속 실행되는 세션을 디스패치하고 한 화면에서 감시합니다

522* [Agent teams](/docs/ko/agent-teams): 실험적이며 기본적으로 비활성화되어 있습니다. 공유 작업, 메시징, 팀 리더를 사용한 여러 세션의 자동 조정522* [에이전트 팀](/docs/ko/agent-teams): 실험적이며 기본적으로 비활성화되어 있습니다. 공유 작업, 메시징, 팀 리더를 사용한 여러 세션의 자동 조정

523 523

524작업을 병렬화하는 것 외에도 여러 세션은 품질 중심 워크플로우를 활성화합니다. 새로운 context는 Claude가 방금 작성한 코드에 편향되지 않으므로 코드 검토를 개선합니다.524작업을 병렬화하는 것 외에도 여러 세션은 품질 중심 워크플로를 활성화합니다. 새로운 컨텍스트는 Claude가 방금 작성한 코드에 편향되지 않으므로 코드 리뷰를 개선합니다.

525 525

526예를 들어 Writer/Reviewer 패턴을 사용하십시오:526예를 들어 Writer/Reviewer 패턴을 사용하십시오:

527 527

538</h3>538</h3>

539 539

540<Tip>540<Tip>

541 각각에 대해 `claude -p`를 호출하는 루프를 통해 작업을 분배하십시오. 배치 작업의 경우 `--allowedTools`를 사용하여 권한을 범위 지정하십시오.541 각각에 대해 `claude -p`를 호출하는 루프를 통해 작업을 분배하십시오. 배치 작업의 경우 `--allowedTools`를 사용하여 도구를 사전 승인하십시오.

542</Tip>542</Tip>

543 543

544대규모 마이그레이션 또는 분석의 경우 많은 병렬 Claude 호출 전체에 작업을 분배할 수 있습니다. [`/batch <instruction>`](/docs/ko/commands#all-commands)을 실행하여 Claude가 5\~30개의 subagent 전체에 변경을 분할하도록 합니다. 각 subagent는 자신의 worktree에서 작업합니다. 대신 자신의 스크립트에서 fan-out을 구동하려면 `claude -p`를 통해 루프하십시오:544대규모 마이그레이션 또는 분석의 경우 많은 병렬 Claude 호출 전체에 작업을 분배할 수 있습니다. [`/batch <instruction>`](/docs/ko/commands#all-commands)을 실행하여 Claude가 5\~30개의 서브에이전트 전체에 변경을 분할하도록 합니다. 각 서브에이전트는 자신의 worktree에서 작업합니다. 대신 자신의 스크립트에서 fan-out을 구동하려면 `claude -p`를 통해 루프하십시오:

545 545

546<Steps>546<Steps>

547 <Step title="작업 목록 생성">547 <Step title="작업 목록 생성">

552 ```bash theme={null}552 ```bash theme={null}

553 for file in $(cat files.txt); do553 for file in $(cat files.txt); do

554 claude -p "Python 2에서 Python 3로 $file 마이그레이션. OK 또는 FAIL 반환." \554 claude -p "Python 2에서 Python 3로 $file 마이그레이션. OK 또는 FAIL 반환." \

555 --allowedTools "Edit,Bash(git commit *)"555 --allowedTools "Edit,Bash(git commit *)" \

556 --permission-mode dontAsk

556 done557 done

557 ```558 ```

558 </Step>559 </Step>

559 560

560 <Step title="몇 개 파일에서 테스트한 다음 모든 파일에서 실행">561 <Step title="몇 개 파일에서 테스트한 다음 모든 파일에서 실행">

561 처음 2-3개 파일에서 잘못된 것을 기반으로 프롬프트를 개선한 다음 전체 집합에서 실행하십시오. `--allowedTools` 플래그는 Claude가 할 수 있는 작업을 제한하며, 이는 무인 상태에서 실행할 때 중요합니다.562 처음 2-3개 파일에서 잘못된 것을 기반으로 프롬프트를 개선한 다음 전체 집합에서 실행하십시오. `--allowedTools` 플래그는 마이그레이션에 필요한 도구를 사전 승인하고, [`--permission-mode dontAsk`](/docs/ko/permission-modes#allow-only-pre-approved-tools-with-dontask-mode)는 승인이 필요한 그 밖의 모든 작업을 거부합니다. 이는 무인 상태에서 실행할 때 중요합니다.

562 </Step>563 </Step>

563</Steps>564</Steps>

564 565

569```570```

570 571

571<h3 id="run-autonomously-with-auto-mode">572<h3 id="run-autonomously-with-auto-mode">

572 auto mode로 자율적으로 실행하기573 자동 모드로 자율적으로 실행하기

573</h3>574</h3>

574 575

575<Tip>576중단 없는 실행과 백그라운드 안전 검사를 위해 [자동 모드](/docs/ko/permission-modes#eliminate-prompts-with-auto-mode)를 사용하십시오. 분류기 모델이 명령을 실행하기 전에 검토하여 범위 확대, 알 수 없는 인프라, 적대적 콘텐츠 기반 작업을 차단하면서 일상적인 작업이 프롬프트 없이 진행되도록 합니다.

576 중단 없는 실행과 백그라운드 안전 검사를 위해 [auto mode](/docs/ko/permission-modes#eliminate-prompts-with-auto-mode)를 사용하십시오. 분류기 모델이 명령을 실행하기 전에 검토하여 범위 확대, 알 수 없는 인프라, 적대적 콘텐츠 기반 작업을 차단하면서 일상적인 작업이 프롬프트 없이 진행되도록 합니다.

577</Tip>

578 577

579```bash theme={null}578```bash theme={null}

580claude --permission-mode auto -p "fix all lint errors"579claude --permission-mode auto -p "fix all lint errors"

581```580```

582 581

583분류기가 `-p` 플래그가 있는 비대화형 실행에서 반복적으로 작업을 차단할 때 Claude Code는 실행을 중지하지 않습니다. [auto mode가 폴백할 때](/docs/ko/permission-modes#when-auto-mode-falls-back)를 참조하여 대신 어떤 일이 발생하는지 및 임계값을 확인하십시오.582분류기가 `-p` 플래그가 있는 비대화형 실행에서 반복적으로 작업을 차단할 때 Claude Code는 실행을 중지하지 않습니다. [자동 모드가 폴백할 때](/docs/ko/permission-modes#when-auto-mode-falls-back)를 참조하여 대신 어떤 일이 발생하는지 및 임계값을 확인하십시오.

584 583

585<h3 id="add-an-adversarial-review-step">584<h3 id="add-an-adversarial-review-step">

586 적대적 검토 단계 추가하기585 적대적 검토 단계 추가하기

587</h3>586</h3>

588 587

589<Tip>588<Tip>

590 작업을 완료된 것으로 취급하기 전에 subagent가 새로운 context에서 diff를 검토하고 누락된 부분을 보고하도록 하십시오.589 작업을 완료된 것으로 취급하기 전에 서브에이전트가 새로운 컨텍스트에서 diff를 검토하고 누락된 부분을 보고하도록 하십시오.

591</Tip>590</Tip>

592 591

593Claude가 무인 상태에서 작업할수록 작업을 완료된 것으로 간주하기 전에 독립적인 검사가 더 중요합니다. 새로운 [subagent](/docs/ko/sub-agents) context에서 실행되는 검토자는 변경을 생성한 추론이 아닌 diff와 제공한 기준만 보므로 자체 조건에 따라 결과를 평가합니다.592Claude가 무인 상태에서 작업할수록 작업을 완료된 것으로 간주하기 전에 독립적인 검사가 더 중요합니다. 새로운 [서브에이전트](/docs/ko/sub-agents) 컨텍스트에서 실행되는 검토자는 변경을 생성한 추론이 아닌 diff와 제공한 기준만 보므로 자체 조건에 따라 결과를 평가합니다.

594 593

595정확성 검사의 경우 번들된 [`/code-review` skill](/docs/ko/commands)을 실행하십시오. 이는 새로운 subagent에서 현재 diff를 버그에 대해 검토하고 발견 사항을 세션에 반환합니다. 대신 diff를 계획과 비교하여 검사하려면 검토 프롬프트를 직접 작성하십시오. 검사할 작업, 검사할 계획, 발견으로 간주되는 것을 이름 지으십시오:594정확성 검사의 경우 번들된 [`/code-review` 스킬](/docs/ko/commands)을 실행하십시오. 이는 새로운 서브에이전트에서 현재 diff를 버그에 대해 검토하고 발견 사항을 세션에 반환합니다. 대신 diff를 계획과 비교하여 검사하려면 검토 프롬프트를 직접 작성하십시오. 검사할 작업, 검사할 계획, 발견으로 간주되는 것을 명시하십시오:

596 595

597```text wrap theme={null}596```text wrap theme={null}

598subagent를 사용하여 PLAN.md에 대해 속도 제한기 diff를 검토하십시오. 모든 요구 사항이 구현되었는지, 나열된 엣지 케이스에 테스트가 있는지, 작업 범위 외의 것이 변경되지 않았는지 확인하십시오. 스타일 선호도가 아닌 누락된 부분을 보고하십시오.597서브에이전트를 사용하여 PLAN.md에 대해 속도 제한기 diff를 검토하십시오. 모든 요구 사항이 구현되었는지, 나열된 엣지 케이스에 테스트가 있는지, 작업 범위 외의 것이 변경되지 않았는지 확인하십시오. 스타일 선호도가 아닌 누락된 부분을 보고하십시오.

599```598```

600 599

601검토자가 subagent로 실행되므로 구현 세션은 누락된 부분을 직접 받고 창 간에 발견 사항을 복사하지 않고도 수정하고 다시 검토할 수 있습니다.600검토자가 서브에이전트로 실행되므로 구현 세션은 누락된 부분을 직접 받고 창 간에 발견 사항을 복사하지 않고도 수정하고 다시 검토할 수 있습니다.

602 601

603<Callout>602<Callout>

604 누락된 부분을 찾도록 프롬프트된 검토자는 작업이 건전할 때도 일반적으로 일부를 보고합니다. 왜냐하면 그것이 요청받은 것이기 때문입니다. 모든 발견을 추적하면 과도한 엔지니어링으로 이어집니다: 추가 추상화 계층, 방어적 코드, 발생할 수 없는 경우에 대한 테스트. 검토자에게 정확성 또는 명시된 요구 사항에 영향을 미치는 누락된 부분만 플래그하도록 지시하고 나머지는 선택 사항으로 취급하십시오.603 누락된 부분을 찾도록 프롬프트된 검토자는 작업이 건전할 때도 일반적으로 일부를 보고합니다. 왜냐하면 그것이 요청받은 것이기 때문입니다. 모든 발견을 추적하면 과도한 엔지니어링으로 이어집니다: 추가 추상화 계층, 방어적 코드, 발생할 수 없는 경우에 대한 테스트. 검토자에게 정확성 또는 명시된 요구 사항에 영향을 미치는 누락된 부분만 플래그하도록 지시하고 나머지는 선택 사항으로 취급하십시오.

channels.md +1 −1

Details

326 조직에 대해 채널 활성화326 조직에 대해 채널 활성화

327</h3>327</h3>

328 328

329조직에 대해 채널을 활성화하려면 소유자 역할이 필요한 [**claude.ai → Admin settings → Claude Code → Channels**](https://claude.ai/admin-settings/claude-code)에서 활성화하거나 관리 설정에서 `channelsEnabled`를 `true`로 설정합니다.329조직에 대해 채널을 활성화하려면 Owner 역할이 필요한 [**Organization settings > Claude Code > Channels**](https://claude.ai/admin-settings/claude-code)에서 활성화하거나 관리형 설정에서 `channelsEnabled`를 `true`로 설정합니다.

330 330

331활성화되면 조직의 사용자는 `--channels`를 사용하여 개별 세션에 채널 서버를 옵트인할 수 있습니다. 설정이 비활성화되었거나 설정되지 않은 경우 MCP 서버는 여전히 연결되고 해당 도구가 작동하지만 채널 메시지는 도착하지 않습니다. 시작 경고는 사용자에게 관리자가 설정을 활성화하도록 합니다.331활성화되면 조직의 사용자는 `--channels`를 사용하여 개별 세션에 채널 서버를 옵트인할 수 있습니다. 설정이 비활성화되었거나 설정되지 않은 경우 MCP 서버는 여전히 연결되고 해당 도구가 작동하지만 채널 메시지는 도착하지 않습니다. 시작 경고는 사용자에게 관리자가 설정을 활성화하도록 합니다.

332 332

claude-apps-gateway.md +102 −97

Details

261 개발자 연결261 개발자 연결

262</h2>262</h2>

263 263

264개발자는 자신의 노트북에서 한 번의 브라우저 로그인으로 회사 업무 계정을 사용하여 연결합니다. 요청이 조직의 업스트림 자격증명을 사용하여 게이트웨이를 통해 모델로 가기 때문에 claude.ai 계정, API 키 또는 구독이 필요하지 않습니다. 연결은 MDM을 통해 푸시하는 [클라이언트 측 관리 설정](/docs/ko/claude-apps-gateway-config#client-side-managed-settings)에 의해 구동되므로, 개발자 측에는 수동 설정이 없습니다; 이 섹션은 관리자가 구성하는 것을 다룹니다.264개발자는 자신의 노트북에서 한 번의 브라우저 로그인으로 회사 업무 계정을 사용하여 연결합니다. 모델에 대한 요청이 조직의 업스트림 자격 증명을 사용하여 게이트웨이를 거치기 때문에 claude.ai 계정, API 키 또는 구독이 필요하지 않습니다. 연결은 MDM을 통해 푸시하는 [클라이언트 측 관리형 설정](/docs/ko/claude-apps-gateway-config#client-side-managed-settings)에 의해 구동되므로 개발자 측에서 수동으로 설정할 것이 없습니다. 이 섹션에서는 관리자가 구성하는 내용을 다룹니다.

265 265

266CLI는 첫 연결 시 게이트웨이의 TLS 리프 인증서를 지문 처리하고 호스트명별로 고정합니다. 로그인 중, 자동 세션 새로 고침 중, 관리 설정 가져오기 중에 해당 핀을 다시 확인하는 반면, 추론 요청은 핀 없이 표준 TLS 검증을 사용합니다. HTTPS 프록시를 통해 라우팅된 요청은 핀 검사를 건너뛰므로, 게이트웨이 호스트를 `NO_PROXY`에 추가하여 직접 연결을 유지하세요.266CLI는 첫 연결 시 게이트웨이의 TLS 리프 인증서 지문을 생성하고 호스트명별로 고정합니다. 로그인 중, 자동 세션 새로 고침 중, 관리형 설정 가져오기 중에 해당 핀을 다시 확인하며, 추론 요청은 핀 없이 표준 TLS 검증을 사용합니다. HTTPS 프록시를 통해 라우팅된 요청은 핀 검사를 건너뛰므로, 게이트웨이 호스트를 `NO_PROXY`에 추가하여 직접 연결을 유지하세요.

267 267

268예상 SHA-256 지문을 게이트웨이 URL과 함께 게시하여 개발자가 비교할 것이 있도록 하세요. `/login` 프롬프트는 지문의 처음 16자를 소문자 16진수로 콜론 없이 표시합니다. 인증서 파일에서 해당 형식의 전체 지문을 인쇄하려면 다음을 실행하세요:268개발자가 비교할 수 있도록 예상 SHA-256 지문을 게이트웨이 URL과 함께 게시하세요. `/login` 프롬프트는 지문의 처음 16자를 콜론 없는 소문자 16진수로 표시합니다. 인증서 파일에서 해당 형식의 전체 지문을 출력하려면 다음을 실행하세요.

269 269

270```bash theme={null}270```bash theme={null}

272```272```

273 273

274인증서가 회전하면 모든 개발자가 신뢰 프롬프트를 다시 보므로, 회전을 계획된 이벤트로 취급하고 지문을 다시 게시하세요. 게이트웨이 정책에 [승인이 필요한 설정](/docs/ko/server-managed-settings#security-approval-dialogs)이 포함되어 있으면, 개발자는 새 인증서를 수락한 후 승인 대화상자를 다시 보게 됩니다. Claude Code는 [승인 메모리](/docs/ko/server-managed-settings#approval-memory)를 고정된 인증서에 키 지정하기 때문입니다.274인증서가 교체되면 모든 개발자에게 신뢰 프롬프트가 다시 표시되므로, 교체를 계획된 이벤트로 취급하고 지문을 다시 게시하세요. 게이트웨이 정책에 [승인이 필요한 설정](/docs/ko/server-managed-settings#security-approval-dialogs)이 포함되어 있으면, 개발자는 새 인증서를 수락한 후 해당 승인 대화상자도 다시 보게 됩니다. Claude Code가 [승인 메모리](/docs/ko/server-managed-settings#approval-memory)를 고정된 인증서에 연결하기 때문입니다.

275 275

276게이트웨이는 토큰 응답에서 선택적 `email` 필드를 반환하여 로그인이 사용한 계정의 이름을 지정할 수 있습니다. 이렇게 하면, 개발자는 Claude Code가 자격증명을 저장하기 전에 계정을 확인합니다. 확인된 로그인 후, `/status`는 계정을 표시합니다.276게이트웨이는 토큰 응답에서 선택적 `email` 필드를 반환하여 로그인에 사용된 계정을 지정할 수 있습니다. 이 경우 개발자는 Claude Code가 자격 증명을 저장하기 전에 계정을 확인합니다. 확인된 로그인 후에는 `/status`에 해당 계정이 표시됩니다.

277 277

278확인은 개발자 머신의 Claude Code v2.1.275 이상이 필요합니다; 해당 버전 아래의 클라이언트는 필드를 무시합니다. `claude` 바이너리의 게이트웨이 서버는 필드를 반환하지 않으므로, 해당 로그인은 확인 없이 완료됩니다.278이 확인에는 개발자 머신에 Claude Code v2.1.275 이상이 필요하며, 그보다 낮은 버전의 클라이언트는 이 필드를 무시합니다. `claude` 바이너리의 게이트웨이 서버는 이 필드를 반환하지 않으므로, 해당 서버를 통한 로그인은 확인 없이 완료됩니다.

279 279

280개발자가 로그인하면, [모델 선택기](/docs/ko/model-config)는 개발자의 `availableModels` 허용 목록의 모델을 표시합니다. 관리 설정은 시작 시 적용되고 매시간 새로 고쳐지며, 텔레메트리는 수집기로 라우팅됩니다.280개발자가 로그인하면 [모델 선택기](/docs/ko/model-config)에 개발자의 `availableModels` 허용 목록에 있는 모델이 표시됩니다. 관리형 설정은 시작 시 적용되고 매시간 새로 고쳐지며, 텔레메트리는 수집기로 라우팅됩니다.

281 281

282세션은 `ttl_hours` 만료 전에 자동으로 새로 고쳐집니다. IdP 프로비저닝 해제 후 새로 고침이 실패하면, Claude Code는 개발자에게 다시 로그인하도록 프롬프트합니다.282세션은 `ttl_hours` 만료 전에 자동으로 새로 고쳐집니다. IdP 프로비저닝 해제 후 새로 고침이 실패하면 Claude Code는 개발자에게 다시 로그인하라고 요청합니다.

283 283

284<h3 id="set-the-gateway-url">284<h3 id="set-the-gateway-url">

285 게이트웨이 URL 설정285 게이트웨이 URL 설정

286</h3>286</h3>

287 287

288MDM을 통해 또는 디스크에 직접 배포하는 OS별 [관리 설정 파일](/docs/ko/managed-settings#delivery-mechanisms)에 세 개의 키가 들어갑니다. `forceLoginMethod`와 `forceLoginGatewayUrl`은 URL이 채워진 **Cloud gateway** 화면에서 직접 `/login`을 열고, `parentSettingsBehavior: "merge"`는 Claude Desktop이 게이트웨이의 송신 허용 목록을 시작하는 Claude Code 세션에 전달하도록 하며, 이는 [Claude Desktop 세션에 정책 전달](#deliver-policy-to-claude-desktop-sessions)에서 설명합니다:288MDM을 통해 또는 디스크에 직접 배포하는 OS별 [관리형 설정 파일](/docs/ko/managed-settings#delivery-mechanisms)에 세 개의 키가 들어갑니다. `forceLoginMethod`와 `forceLoginGatewayUrl`은 URL이 채워진 **Cloud gateway** 화면에서 `/login`을 바로 열고, `parentSettingsBehavior: "merge"`는 Claude Desktop이 게이트웨이의 송신 허용 목록을 자신이 시작하는 Claude Code 세션에 전달할 수 있게 합니다. 이는 [Claude Desktop 세션에 정책 전달](#deliver-policy-to-claude-desktop-sessions)에서 설명합니다.

289 289

290```json theme={null}290```json theme={null}

291{291{

295}295}

296```296```

297 297

298개발자는 Enter를 눌러 연결합니다. [첫 연결 TLS 지문 프롬프트](#connect-developers)는 여전히 나타납니다. 파일이 머신에 있으면, 게이트웨이 로그인을 완료하지 않은 개발자는 [Administrator policy requires a Cloud gateway sign-in](/docs/ko/errors#administrator-policy-requires-a-cloud-gateway-sign-in)에서 설명한 메시지 중 하나를 봅니다. `CLAUDE_CODE_USE_BEDROCK` 같은 환경 변수를 통해 클라우드 제공자를 선택하는 개발자는 게이트웨이 로그인이 필요하지 않습니다.298개발자는 Enter를 눌러 연결합니다. [첫 연결 TLS 지문 프롬프트](#connect-developers)는 여전히 나타납니다. 파일이 머신에 배포되면, 게이트웨이 로그인을 완료하지 않은 개발자는 [Administrator policy requires a Cloud gateway sign-in](/docs/ko/errors#administrator-policy-requires-a-cloud-gateway-sign-in)에 설명된 메시지 중 하나를 보게 됩니다. `CLAUDE_CODE_USE_BEDROCK` 같은 환경 변수를 통해 클라우드 제공자를 선택하는 개발자는 게이트웨이 로그인이 필요하지 않습니다.

299 299

300개발자가 수동으로 이를 설정할 수 없습니다. 로그인 선택기에는 게이트웨이 옵션이 없으며, `forceLoginGatewayUrl`은 개발자의 자신의 설정 파일에서 무시됩니다. `forceLoginMethod`만, URL 없이, 개발자를 "IT 관리자에게 문의하세요" 메시지에 남깁니다. 로그인 키는 머신으로 푸시하는 파일에 속하며, 게이트웨이의 `managed.policies[].cli` 블록에는 속하지 않습니다. 이 블록은 이미 연결된 클라이언트에만 도달합니다.300개발자는 이를 수동으로 설정할 수 없습니다. 로그인 선택기에는 게이트웨이 옵션이 없으며, `forceLoginGatewayUrl`은 개발자 자신의 설정 파일에서는 무시됩니다. URL 없이 `forceLoginMethod`만 설정하면 개발자에게 "IT 관리자에게 문의하세요" 메시지만 표시됩니다. 로그인 키는 머신에 푸시하는 파일에 넣어야 하며, 이미 연결된 클라이언트에만 도달하는 게이트웨이의 `managed.policies[].cli` 블록에 넣으면 안 됩니다.

301 301

302<h3 id="allow-a-gateway-on-public-address-space-you-own">302<h3 id="allow-a-gateway-on-public-address-space-you-own">

303 공개 주소 공간에서 소유한 게이트웨이 허용303 소유한 공인 주소 공간의 게이트웨이 허용

304</h3>304</h3>

305 305

306일부 조직은 자신이 소유한 공개 IPv4 블록(예: 통신사의 자신의 주소 공간 또는 레거시 `/8`)에서 내부 네트워크를 번호 지정하므로, 게이트웨이는 개인 주소를 가질 수 없습니다. 이러한 블록을 `gatewayInternalNetworks` 관리 설정에 나열하세요. `/login`은 개발자의 머신이 동일한 블록 내의 주소에서 연결할 때 나열된 블록 내의 게이트웨이를 수락합니다. 이는 개발자 머신의 Claude Code v2.1.268 이상이 필요합니다; 이전 버전은 키를 무시하고 개인 주소 규칙을 적용합니다.306일부 조직은 통신사 자체 주소 공간이나 레거시 `/8`처럼 자신이 소유한 공인 IPv4 블록으로 내부 네트워크 주소를 할당하므로, 게이트웨이가 사설 주소를 가질 수 없습니다. 이러한 블록을 `gatewayInternalNetworks` 관리형 설정에 나열하세요. 그러면 `/login`은 개발자 머신이 나열된 블록 내의 주소에서 동일한 블록 내의 게이트웨이에 연결할 때 해당 게이트웨이를 수락합니다. 이를 위해서는 개발자 머신에 Claude Code v2.1.268 이상이 필요하며, 이전 버전은 이 키를 무시하고 사설 주소 규칙을 적용합니다.

307 307

308<Warning>308<Warning>

309 `gatewayInternalNetworks`는 공개 주소 공간에서 번호 지정되는 내부 네트워크용입니다. 게이트웨이를 인터넷에 노출하는 것을 안전하게 만들지 않습니다: 신뢰할 수 있는 게이트웨이는 개발자 머신에서 명령을 실행하는 설정을 푸시할 수 있습니다.309 `gatewayInternalNetworks`는 공인 주소 공간으로 번호가 지정된 내부 네트워크를 위한 것입니다. 이 설정이 게이트웨이를 인터넷에 노출하는 것을 안전하게 만들지는 않습니다. 신뢰된 게이트웨이는 개발자 머신에서 명령을 실행하는 설정을 푸시할 수 있습니다.

310 310

311 방화벽 또는 로드 밸런서 규칙으로 게이트웨이를 네트워크 외부에서 도달할 수 없게 유지하세요. 게이트웨이의 [`access_control.allow_cidrs`](/docs/ko/claude-apps-gateway-config#http-tuning)를 여기에서 선언한 동일한 블록으로 설정하여 게이트웨이 자체가 다른 곳의 클라이언트를 거부하도록 하세요. 로드 밸런서 또는 수신 뒤에서, 게이트웨이가 개발자의 주소가 아닌 프론트 엔드의 자신의 주소에 대해 `allow_cidrs`를 일치시키기 때문에 `listen.trusted_proxies`를 해당 프론트 엔드로 설정하세요.311 방화벽 또는 로드 밸런서 규칙으로 게이트웨이가 네트워크 외부에서 접근할 수 없도록 유지하세요. 게이트웨이의 [`access_control.allow_cidrs`](/docs/ko/claude-apps-gateway-config#http-tuning)를 여기에서 선언한 것과 동일한 블록으로 설정하여 게이트웨이 자체가 다른 곳의 클라이언트를 거부하도록 하세요. 로드 밸런서나 인그레스 뒤에서는 `listen.trusted_proxies`도 해당 프런트 엔드로 설정하세요. 그렇지 않으면 게이트웨이가 개발자의 주소가 아니라 프런트 엔드 자체의 주소를 `allow_cidrs`와 대조하기 때문입니다.

312</Warning>312</Warning>

313 313

314키를 로그인 키와 동일한 관리 설정 소스에 추가하세요: 관리 설정 파일, MDM 프로필 또는 레지스트리 정책. Claude Code는 사용자, 프로젝트, 서버 관리 설정에서 이를 무시합니다.314이 키는 로그인 키와 동일한 관리형 설정 소스, 즉 관리형 설정 파일, MDM 프로필 또는 레지스트리 정책에 추가하세요. Claude Code는 사용자, 프로젝트, 서버 관리형 설정에 있는 이 키를 무시합니다.

315 315

316이 예제는 하나의 블록을 선언합니다. `203.0.113.0/24`를 자신의 블록으로 바꾸세요. 이는 문서 범위이며, Claude Code는 이를 거부합니다.316이 예제는 하나의 블록을 선언합니다. `203.0.113.0/24`를 자신의 블록으로 바꾸세요. 이 주소는 문서용 범위이며, Claude Code는 문서용 범위를 거부합니다.

317 317

318```json theme={null}318```json theme={null}

319{319{

321}321}

322```322```

323 323

324Claude Code는 게이트웨이에 연결하기 전에 `/login`에서 목록을 검증합니다:324Claude Code는 게이트웨이에 연결하기 전에 `/login`에서 목록을 검증합니다.

325 325

326* 각 항목은 첫 주소와 `/8`에서 `/32` 사이의 접두사로 작성된 IPv4 블록입니다.326* 각 항목은 첫 번째 주소와 `/8`에서 `/32` 사이의 접두사로 작성된 IPv4 블록입니다.

327* 목록은 최대 4개의 블록을 보유하며, 2개는 겹치지 않습니다.327* 목록에는 최대 4개의 블록을 넣을 수 있으며, 서로 겹치는 블록이 없어야 합니다.

328* 블록은 개인 주소 공간과 겹치지 않습니다: `10.0.0.0/8`, `172.16.0.0/12`, `192.168.0.0/16`, `127.0.0.0/8`, `169.254.0.0/16`, `100.64.0.0/10`. `/login`은 이미 이 키 없이 거기에서 게이트웨이를 수락합니다.328* 어떤 블록도 사설 주소 공간 `10.0.0.0/8`, `172.16.0.0/12`, `192.168.0.0/16`, `127.0.0.0/8`, `169.254.0.0/16`, `100.64.0.0/10`과 겹치지 않아야 합니다. `/login`은 이 키 없이도 해당 공간의 게이트웨이를 이미 수락합니다.

329* 블록은 조직의 네트워크가 될 수 없는 공간과 겹치지 않습니다: VPN 및 NAT64 클라이언트가 로컬 주소로 보유하는 `198.18.0.0/15` 및 `192.0.0.0/24`; 문서 범위 `192.0.2.0/24`, `198.51.100.0/24`, `203.0.113.0/24`; 예약된 범위 `0.0.0.0/8`, `192.88.99.0/24`, 멀티캐스트 `224.0.0.0/4`. `240.0.0.0/4` 내의 블록을 선언할 수 있으며, 일부 대규모 네트워크는 이를 내부 유니캐스트 공간으로 사용합니다.329* 어떤 블록도 조직의 네트워크가 될 수 없는 공간과 겹치지 않아야 합니다. 여기에는 VPN 및 NAT64 클라이언트가 로컬 주소로 사용하는 `198.18.0.0/15` 및 `192.0.0.0/24`, 문서용 범위 `192.0.2.0/24`, `198.51.100.0/24`, `203.0.113.0/24`, 예약 범위 `0.0.0.0/8`, `192.88.99.0/24`, 멀티캐스트 `224.0.0.0/4`가 포함됩니다. 일부 대규모 네트워크가 내부 유니캐스트 공간으로 사용하는 `240.0.0.0/4` 내의 블록은 선언할 수 있습니다.

330 330

331`managed-settings.json` 및 해당 `managed-settings.d/` 드롭인 파일의 블록은 하나의 목록으로 결합되며, 이러한 제한은 결합된 목록에 적용됩니다. 블록을 좁히려면, 드롭인에서 두 번째 겹치는 항목을 추가하는 대신 항목을 바꾸세요; `/login`은 겹침을 거부합니다.331`managed-settings.json`과 해당 `managed-settings.d/` 드롭인 파일의 블록은 하나의 목록으로 결합되며, 이러한 제한은 결합된 목록에 적용됩니다. 블록을 좁히려면 드롭인에 겹치는 두 번째 항목을 추가하지 말고 기존 항목을 교체하세요. `/login`은 겹침을 거부합니다.

332 332

333항목이 규칙을 위반하거나 값이 문자열 목록이 아니면, Claude Code는 해당 머신에서 모든 새 게이트웨이 로그인을 거부하고 메시지에서 문제를 지정합니다. 개인 주소의 게이트웨이로 로그인도 실패하며, 기존 로그인은 계속 작동합니다. 배포하기 전에 한 머신에서 값을 시도하세요. Claude Code는 또한 잘못 입력된 값을 [보고하는 잘못된 관리 설정](/docs/ko/managed-settings#keys-that-fail-closed) 중에 나열합니다.333항목이 규칙을 위반하거나 값이 문자열 목록이 아니면, Claude Code는 해당 머신에서 새로운 모든 게이트웨이 로그인을 거부하고 메시지에 문제를 명시합니다. 사설 주소에 있는 게이트웨이로의 로그인도 실패하며, 기존 로그인은 계속 작동합니다. 배포하기 전에 한 머신에서 값을 시험해 보세요. Claude Code는 잘못된 타입의 값도 [보고하는 잘못된 관리형 설정](/docs/ko/managed-settings#keys-that-fail-closed) 목록에 포함합니다.

334 334

335유효한 목록으로, `/login`은 주소가 나열된 블록 내에 있는 게이트웨이에 3가지 검사를 적용합니다:335목록이 유효하면, `/login`은 주소가 나열된 블록 내에 있는 게이트웨이에 세 가지 검사를 적용합니다.

336 336

337* 게이트웨이의 호스트명이 확인하는 모든 주소는 해당 하나의 블록 내에 있습니다. Claude Code는 개인 및 IPv6 주소를 포함하여 블록 외부에도 레코드가 있는 이름을 거부합니다.337* 게이트웨이의 호스트명이 확인되는 모든 주소가 해당 하나의 블록 내에 있어야 합니다. Claude Code는 사설 주소와 IPv6 주소를 포함하여 블록 외부에도 레코드가 있는 이름을 거부합니다.

338* 개발자의 머신은 동일한 블록 내의 주소에서 연결합니다. Claude Code는 NAT 뒤, 컨테이너 또는 WSL2 내, 주소 풀이 블록 외부에 있는 VPN의 머신을 거부하고, 머신이 연결한 주소를 지정합니다.338* 개발자 머신이 동일한 블록 내에서 연결해야 합니다. Claude Code는 NAT 뒤, 컨테이너 또는 WSL2 내부, 주소 풀이 블록 외부에 있는 VPN에 있는 머신을 거부하고, 머신이 연결한 주소를 명시합니다.

339* 연결은 직접입니다. `HTTPS_PROXY`가 게이트웨이 호스트에 적용되면, `/login`은 거부하고 추가할 `NO_PROXY` 항목을 지정합니다.339* 연결이 직접 연결이어야 합니다. `HTTPS_PROXY`가 게이트웨이 호스트에 적용되면 `/login`은 거부하고 추가해야 할 `NO_PROXY` 항목을 명시합니다.

340 340

3413가지 모두 통과하면, [신뢰 프롬프트](#connect-developers)는 머신의 주소, 게이트웨이의 주소, 둘 다를 포함하는 선언된 블록을 지정하는 줄을 추가합니다.341세 가지를 모두 통과하면 [신뢰 프롬프트](#connect-developers)에 머신의 주소, 게이트웨이의 주소, 그리고 둘을 모두 포함하는 선언된 블록을 명시하는 줄이 추가됩니다.

342 342

343키는 다른 게이트웨이에 대해 아무것도 변경하지 않습니다: 개인 주소의 게이트웨이로 로그인은 이전처럼 작동하며, 모든 나열된 블록 외부의 공개 주소의 게이트웨이로 로그인은 이전처럼 거부됩니다.343이 키는 다른 게이트웨이에는 아무 영향도 주지 않습니다. 사설 주소에 있는 게이트웨이로의 로그인은 이전처럼 작동하며, 나열된 모든 블록 외부의 공인 주소에 있는 게이트웨이로의 로그인은 이전처럼 거부됩니다.

344 344

345선언된 블록은 누가 로그인할 수 있는지를 좁히지만 머신이 어디에 있는지를 증명하지 않으므로, 조직이 제어하는 주소 공간만 선언하세요. 클라우드 제공자의 공개 범위와 같이 다른 테넌트와 공유되는 블록은 이를 통과하는 누구나 동일한 검사를 통과하도록 합니다.345선언된 블록은 로그인할 수 있는 대상을 좁히지만 머신의 위치를 증명하지는 않으므로, 조직이 제어하는 주소 공간만 선언하세요. 클라우드 제공자의 공인 범위처럼 다른 테넌트와 공유되는 블록을 선언하면, 그 안의 누구나 동일한 검사를 통과할 수 있습니다.

346 346

347<h3 id="deliver-policy-to-claude-desktop-sessions">347<h3 id="deliver-policy-to-claude-desktop-sessions">

348 Claude Desktop 세션에 정책 전달348 Claude Desktop 세션에 정책 전달

349</h3>349</h3>

350 350

351Claude Desktop은 Cowork 및 Code 탭과 Chat 탭(활성화한 경우)을 포함된 Claude Code 세션에서 실행하고 해당 모델 요청을 게이트웨이를 통해 보냅니다. 게이트웨이가 `/user/bootstrap`에서 제공하는 구성에서 구축된 정책을 각 세션에 전달합니다: 모델 허용 목록, 비활성화된 도구, 일치하는 정책의 `cli` 블록에서 파생된 송신 허용 목록, 그리고 [`desktop` 오버레이](/docs/ko/claude-apps-gateway-config#claude-desktop-overlay).351Claude Desktop은 Cowork 및 Code 탭과, 활성화한 경우 Chat 탭을 내장된 Claude Code 세션에서 실행하고, 해당 모델 요청을 게이트웨이를 통해 보냅니다. Claude Desktop은 게이트웨이가 `/user/bootstrap`에서 제공하는 구성으로 만든 정책을 각 세션에 전달합니다. 여기에는 일치하는 정책의 `cli` 블록에서 파생된 모델 허용 목록, 비활성화된 도구, 송신 허용 목록과 [`desktop` 오버레이](/docs/ko/claude-apps-gateway-config#claude-desktop-overlay)가 포함됩니다.

352 352

353hooks, `env`, `Bash(npm *)` 같은 범위가 지정된 권한 규칙 등 다른 `cli` 키는 `/login`을 통해 로그인하는 클라이언트에만 도달합니다. Claude Desktop은 게이트웨이 URL을 자신의 관리 구성에서 읽고 [게이트웨이 URL 설정](#set-the-gateway-url)의 `forceLoginMethod` 및 `forceLoginGatewayUrl` 키와 별개인 자신의 흐름으로 로그인합니다.353훅, `env`, `Bash(npm *)` 같은 범위 지정 권한 규칙 등 다른 `cli` 키는 `/login`을 통해 로그인하는 클라이언트에만 도달합니다. Claude Desktop은 게이트웨이 URL을 자체 관리형 구성에서 읽고, [게이트웨이 URL 설정](#set-the-gateway-url)의 `forceLoginMethod` 및 `forceLoginGatewayUrl` 키와는 별개인 자체 흐름으로 로그인합니다.

354 354

355시작 프로세스에서 전달된 설정은 부모 설정입니다. Claude Code는 정책을 전달하는 [소스](/docs/ko/managed-settings#which-managed-source-claude-code-uses)가 `parentSettingsBehavior: "merge"`를 설정하지 않는 한, 관리 배포된 관리 소스가 있는 모든 머신에서 부모 설정을 무시합니다.355시작하는 프로세스가 전달하는 설정은 부모 설정입니다. Claude Code는 [정책을 전달하는 소스](/docs/ko/managed-settings#which-managed-source-claude-code-uses)가 `parentSettingsBehavior: "merge"`를 설정하지 않는 한, 관리자가 배포한 관리형 소스가 있는 모든 머신에서 부모 설정을 무시합니다.

356 356

357<h4 id="which-machines-need-the-opt-in">357<h4 id="which-machines-need-the-opt-in">

358 옵트인이 필요한 머신358 옵트인이 필요한 머신

359</h4>359</h4>

360 360

361Claude Desktop만 실행하는 머신에는 옵트인이 필요합니다. Claude Desktop은 모델 목록과 비활성화된 도구 목록을 포함된 세션에 자체적으로 적용하지만, 송신 허용 목록은 `WebFetch` 도메인 규칙 및 샌드박스 네트워크 규칙 형태의 부모 설정으로만 도달합니다. 옵트인 없이, 이러한 세션은 송신 제한 없이 실행되며, 아무것도 경고하지 않습니다. 게이트웨이는 여전히 정책이 부여하지 않는 모델에 대한 추론 요청을 거부합니다.361Claude Desktop만 실행하는 머신에는 옵트인이 필요합니다. Claude Desktop은 모델 목록과 비활성화된 도구 목록을 내장된 세션에 직접 적용하지만, 송신 허용 목록은 `WebFetch` 도메인 규칙과 샌드박스 네트워크 규칙 형태의 부모 설정으로만 도달합니다. 옵트인이 없으면 이러한 세션은 송신 제한 없이 실행되며, 아무런 경고도 표시되지 않습니다. 게이트웨이는 여전히 정책이 허용하지 않는 모델에 대한 추론 요청을 거부합니다.

362 362

363플러그인 마켓플레이스 허용 목록도 포함된 세션에만 부모 설정으로 도달합니다. Claude Desktop의 관리 구성에서 사용자 추가 플러그인 마켓플레이스를 끄면, Claude Desktop 2.16120.0 이상은 조직이 프로비저닝하지 않은 마켓플레이스를 숨기고 이들로부터의 설치를 거부합니다. 포함된 세션이 이러한 마켓플레이스에서 이미 설치된 플러그인을 로드하는 것을 중지하려면, 부모 설정으로 `strictKnownMarketplaces` 목록을 보냅니다. 옵트인 없이, Claude Code는 해당 목록을 무시하고, 이러한 플러그인은 계속 로드됩니다.363플러그인 마켓플레이스 허용 목록도 부모 설정으로만 내장된 세션에 도달합니다. Claude Desktop의 관리형 구성에서 사용자 추가 플러그인 마켓플레이스를 끄면, Claude Desktop 2.16120.0 이상은 조직이 프로비저닝하지 않은 마켓플레이스를 숨기고 해당 마켓플레이스에서의 설치를 거부합니다. 내장된 세션이 해당 마켓플레이스에서 이미 설치된 플러그인을 로드하지 못하도록, Claude Desktop은 `strictKnownMarketplaces` 목록을 부모 설정으로 보냅니다. 옵트인이 없으면 Claude Code는 해당 목록을 무시하고, 이러한 플러그인은 계속 로드됩니다.

364 364

365개발자가 `/login`을 통해 로그인하는 머신에는 옵트인이 필요하지 않습니다; 각 Claude Code 세션은 게이트웨이에서 정책을 가져옵니다.365개발자가 `/login`을 통해 로그인하는 머신에는 옵트인이 필요하지 않습니다. 각 Claude Code 세션이 게이트웨이에서 정책을 가져옵니다.

366 366

367[`policyHelper`](/docs/ko/settings-reference#policyhelper)가 관리 설정을 제공하는 플릿은 이를 사용할 수 없습니다: Claude Code는 도우미의 출력에서만 관리 설정을 읽기 때문에 이러한 플릿에서 부모 설정을 병합하지 않습니다.367[`policyHelper`](/docs/ko/settings-reference#policyhelper)가 관리형 설정을 제공하는 플릿은 이를 사용할 수 없습니다. Claude Code는 헬퍼의 출력에서만 관리형 설정을 읽기 때문에, 해당 플릿에서는 부모 설정을 병합하지 않습니다.

368 368

369<h4 id="set-the-opt-in">369<h4 id="set-the-opt-in">

370 옵트인 설정370 옵트인 설정

371</h4>371</h4>

372 372

373[게이트웨이 URL 설정](#set-the-gateway-url)에서 관리 설정 스니펫을 배포하고, 파일을 능가하는 모든 클라이언트 측 소스로 미러링한 다음, 확인하세요.373[게이트웨이 URL 설정](#set-the-gateway-url)의 관리형 설정 스니펫을 배포하고, 파일보다 우선하는 모든 클라이언트 측 소스에 미러링한 다음 확인하세요.

374 374

375<Steps>375<Steps>

376 <Step title="관리 설정 파일에 옵트인 배포">376 <Step title="관리형 설정 파일에 옵트인 배포">

377 [위의 스니펫](#set-the-gateway-url)은 이미 `parentSettingsBehavior: "merge"`를 포함하므로, 머신으로 푸시하는 파일이 이를 전달합니다.377 [위의 스니펫](#set-the-gateway-url)에는 이미 `parentSettingsBehavior: "merge"`가 포함되어 있으므로, 머신에 푸시하는 파일에 이 설정이 포함됩니다.

378 </Step>378 </Step>

379 379

380 <Step title="파일을 능가하는 모든 소스로 스니펫 미러링">380 <Step title="파일보다 우선하는 모든 소스에 스니펫 미러링">

381 Claude Code는 [선택된 소스](/docs/ko/managed-settings#which-managed-source-claude-code-uses)에서만 `parentSettingsBehavior`를 읽습니다. 클라이언트 측 소스에 정책 키를 추가하면 해당 소스가 선택된 소스가 될 수 있으므로, `parentSettingsBehavior`만이 아닌 전체 스니펫을 미러링하세요. [클라이언트 측 관리 설정](/docs/ko/claude-apps-gateway-config#client-side-managed-settings)은 Group Policy 또는 구성 프로필을 통해 정책을 전달하는 플릿을 다룹니다. macOS의 관리 기본 설정 plist 또는 Windows의 HKLM 정책은 `managed-settings.json` 파일을 능가하며, 게이트웨이의 자체 원격 관리 설정은 둘 다를 능가하므로, 게이트웨이에 로그인하는 머신에서도 게이트웨이 정책의 [`cli` 블록](/docs/ko/claude-apps-gateway-config#managed)에서 `parentSettingsBehavior`를 설정하세요.381 Claude Code는 [선택된 소스](/docs/ko/managed-settings#which-managed-source-claude-code-uses)에서만 `parentSettingsBehavior`를 읽습니다. 어떤 소스에든 정책 키를 추가하면 해당 소스가 선택된 소스가 될 수 있으므로, 클라이언트 측 소스에는 `parentSettingsBehavior`만이 아니라 전체 스니펫을 미러링하세요. [클라이언트 측 관리형 설정](/docs/ko/claude-apps-gateway-config#client-side-managed-settings)에서는 Group Policy 또는 구성 프로필을 통해 정책을 전달하는 플릿을 다룹니다. macOS의 관리형 기본 설정 plist나 Windows의 HKLM 정책은 `managed-settings.json` 파일보다 우선하며, 게이트웨이 자체의 원격 관리형 설정은 둘 모두보다 우선합니다. 따라서 게이트웨이에 로그인하는 머신의 경우 게이트웨이 정책의 [`cli` 블록](/docs/ko/claude-apps-gateway-config#managed)에도 `parentSettingsBehavior`를 설정하세요.

382 </Step>382 </Step>

383 383

384 <Step title="선택된 소스 확인">384 <Step title="선택된 소스 확인">

385 Claude Desktop만 실행하는 머신에서 Agent SDK의 [`resolveSettings()`](/docs/ko/agent-sdk/typescript#resolvesettings)를 호출하고 `sources` 목록의 `managed` 항목에서 `policyOrigin`을 읽으세요. 값은 선택된 클라이언트 측 소스인 `plist`, `hklm` 또는 `file`의 이름을 지정하며, 이는 스니펫을 전달해야 하는 소스입니다. Claude Desktop의 포함된 세션은 게이트웨이 정책을 가져오지 않으므로, 게이트웨이의 `cli` 블록은 이들에 대해 선택된 소스로 계산되지 않습니다.385 Claude Desktop만 실행하는 머신에서 Agent SDK의 [`resolveSettings()`](/docs/ko/agent-sdk/typescript#resolvesettings)를 호출하고, `sources` 목록의 `managed` 항목에서 `policyOrigin`을 읽으세요. 이 값은 선택된 클라이언트 측 소스인 `plist`, `hklm` 또는 `file`을 나타내며, 이 소스에 스니펫이 있어야 합니다. Claude Desktop의 내장된 세션은 게이트웨이 정책을 가져오지 않으므로, 게이트웨이의 `cli` 블록은 이 세션에 대해 선택된 소스로 간주되지 않습니다.

386 </Step>386 </Step>

387</Steps>387</Steps>

388 388

390 부모 설정 제한390 부모 설정 제한

391</h3>391</h3>

392 392

393`parentSettingsBehavior: "merge"`를 배포하면, Claude Desktop뿐만 아니라 Agent SDK 애플리케이션 또는 IDE 확장도 Claude Code를 시작하는 모든 호스트 프로세스가 부모 설정을 제공할 수 있습니다.393`parentSettingsBehavior: "merge"`를 배포하면 Claude Desktop뿐 아니라 Agent SDK 애플리케이션이나 IDE 확장 등 Claude Code를 시작하는 모든 호스트 프로세스가 부모 설정을 제공할 수 있습니다.

394 394

395Claude Code는 부모 설정을 제한적 키의 허용 목록에 대해 필터링하지만, 일부 허용된 키는 제한하기보다는 액세스를 부여할 수 있습니다. `allowManaged*Only` 잠금을 설정하지 않으면, 호스트에서 제공한 권한 허용 규칙 및 샌드박스 허용 목록이 여전히 적용됩니다. 정책의 거부 및 요청 규칙은 어느 쪽이든 적용됩니다; [이들은 모든 허용 규칙 전에 평가됩니다](/docs/ko/permissions#manage-permissions).395Claude Code는 제한적인 키의 허용 목록을 기준으로 부모 설정을 필터링하지만, 허용된 일부 키는 제한하는 대신 액세스를 부여할 수 있습니다. `allowManaged*Only` 잠금을 설정하지 않으면 호스트가 제공한 권한 허용 규칙과 샌드박스 허용 목록이 여전히 적용됩니다. 정책의 거부 및 확인 규칙은 어느 경우에나 유효합니다. [이 규칙은 모든 허용 규칙보다 먼저 평가됩니다](/docs/ko/permissions#manage-permissions).

396 396

397Claude Code는 부모 제공 [`sandbox.credentials`](/docs/ko/settings-reference#sandbox-credentials) 항목을 제거된 형태로 전달합니다:397Claude Code는 부모가 제공한 [`sandbox.credentials`](/docs/ko/settings-reference#sandbox-credentials) 항목을 축소된 형태로 전달합니다.

398 398

399* **`deny` 항목**: `path` 또는 `name`과 모드만으로 전달됩니다.399* **`deny` 항목**: `path` 또는 `name`과 모드만 전달됩니다.

400* **[`mode: mask`](/docs/ko/sandboxing#mask-credential-files)가 있는 파일 항목**: 전체 파일 마스크로 센티널만 전달되며, `injectHosts`는 빈 목록이므로, 프록시는 모든 플랫폼에서 부모 제공 항목에 대해 실제 값을 대체하지 않습니다. 모든 구조화된 마스킹 필드도 삭제되므로, 부모 제공 추출 패턴은 다른 소스가 동일한 경로에 대해 설정한 더 엄격한 마스크를 대체할 수 없습니다.400* **[`mode: mask`](/docs/ko/sandboxing#mask-credential-files)가 있는 파일 항목**: `injectHosts`가 빈 목록인 전체 파일 마스크로서 센티널 전용으로 전달되므로, 어떤 플랫폼에서도 프록시가 부모 제공 항목에 실제 값을 대입하지 않습니다. 모든 구조화된 마스킹 필드도 삭제되므로, 부모가 제공한 추출 패턴이 다른 소스가 동일한 경로에 설정한 더 엄격한 마스크를 대체할 수 없습니다.

401* **`mode: mask`가 있는 `envVars` 항목**: 전달되지 않습니다. `deny`는 부모 채널이 `envVars` 항목을 통해 표현할 수 있는 유일한 제한입니다.401* **`mode: mask`가 있는 `envVars` 항목**: 전달되지 않습니다. 부모 채널이 `envVars` 항목을 통해 표현할 수 있는 제한은 `deny`뿐입니다.

402* **[`awsPairs` 및 `sigv4`](/docs/ko/sandboxing#re-sign-aws-requests)**: 제한만 전달됩니다. `sigv4`에서는 `deny` 값만 유지되며, 부모가 `sigv4` 블록을 정의하면 세 가지 요청 형식 모두 `streaming`, `presigned`, `sigv4a`를 `deny`로 고정합니다. `awsPairs` 쌍은 다시 서명할 수 있는 형태로 전달되지 않습니다; 기존 AWS 변수 중 하나의 이름을 지정하는 쌍은 `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, `AWS_SESSION_TOKEN`의 자동 쌍 지정을 억제된 상태로 유지하는 비활성 항목으로 대체됩니다.402* **[`awsPairs` 및 `sigv4`](/docs/ko/sandboxing#re-sign-aws-requests)**: 제한 전용으로 전달됩니다. `sigv4`에서는 `deny` 값만 유지되며, 부모가 `sigv4` 블록을 정의하기만 하면 세 가지 요청 형식 `streaming`, `presigned`, `sigv4a`가 모두 `deny`로 고정됩니다. `awsPairs` 쌍은 재서명할 수 있는 형태로는 전달되지 않습니다. 관례적인 AWS 변수 중 하나를 지정하는 쌍은 `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, `AWS_SESSION_TOKEN`의 자동 쌍 지정을 억제된 상태로 유지하는 비활성 항목으로 대체됩니다.

403 403

404<h4 id="deploy-the-locks">404<h4 id="deploy-the-locks">

405 잠금 배포405 잠금 배포

406</h4>406</h4>

407 407

408부모 설정을 필터가 지원하는 제한만큼 가깝게 유지하려면, 다섯 개의 `allowManaged*Only` 잠금과 이들이 관리하는 허용 목록을 모두 병합 옵트인과 동일한 소스에 추가하세요:408부모 설정을 필터가 지원하는 범위 내에서 최대한 제한 전용에 가깝게 유지하려면, 다섯 개의 `allowManaged*Only` 잠금과 이들이 관리하는 허용 목록을 모두 병합 옵트인과 동일한 소스에 추가하세요.

409 409

410```json theme={null}410```json theme={null}

411{411{

430}430}

431```431```

432 432

433OS 정책(예: HKLM 레지스트리 정책 또는 관리 기본 설정 plist)은 이 파일을 능가하므로, 파일 대신 전체 스니펫을 통해 전달하세요. 게이트웨이의 원격 관리 설정은 OS 정책 및 파일 소스를 능가하지만 연결된 클라이언트에만 도달합니다. 잠금, 허용 목록, 병합 옵트인을 정책의 [`cli` 블록](/docs/ko/claude-apps-gateway-config#managed)으로 미러링하고 이 파일을 배포된 상태로 유지하세요. 연결되지 않은 머신(Claude Desktop만 실행하는 머신 포함)은 파일에서만 정책을 가져옵니다.433HKLM 레지스트리 정책이나 관리형 기본 설정 plist 같은 OS 정책은 이 파일보다 우선하므로, 파일 대신 해당 OS 정책을 통해 전체 스니펫을 전달하세요. 게이트웨이의 원격 관리형 설정은 OS 정책 및 파일 소스보다 우선하지만 연결된 클라이언트에만 도달합니다. 잠금, 허용 목록, 병합 옵트인을 정책의 [`cli` 블록](/docs/ko/claude-apps-gateway-config#managed)에 미러링하고 이 파일도 배포된 상태로 유지하세요. Claude Desktop만 실행하는 머신을 포함하여 연결되지 않는 머신은 이 파일에서만 정책을 가져오기 때문입니다.

434 434

435<h4 id="lock-behavior-across-sources">435<h4 id="lock-behavior-across-sources">

436 소스 전체의 잠금 동작436 소스 간 잠금 동작

437</h4>437</h4>

438 438

439한 잠금을 설정해도 다른 잠금을 제한하지 않습니다; 각 키는 [설정 참조](/docs/ko/settings-reference#all-settings)에 문서화되어 있습니다. 우승자 아래의 관리 소스에서, 두 샌드박스 잠금은 여전히 적용되며, `allowManagedPermissionRulesOnly`는 여전히 부모 제공 허용 규칙 및 `additionalDirectories`를 차단합니다. Claude Code v2.1.273 이상에서, MCP 서버 잠금도 우승자 아래의 소스에서 적용되며, 이것이 켜져 있는 동안 관리 `allowedMcpServers` 목록은 하나를 설정하는 가장 높은 우선순위 관리 소스에서 나옵니다.439한 잠금을 설정해도 다른 잠금이 제한되지는 않습니다. 각 키는 [설정 참조](/docs/ko/settings-reference#all-settings)에 문서화되어 있습니다.

440 440

441hooks 잠금과 `allowManagedPermissionRulesOnly`의 개발자 자신의 규칙에 대한 영향은 기본적으로 우승 소스가 필요합니다; [Claude Code가 관리 소스를 결합하는 방법](/docs/ko/managed-settings#how-claude-code-combines-managed-sources)의 `managedSourcesBehavior` 병합 옵트인에서, Claude Code는 모든 잠금에 대해 모든 소스가 설정하는 가장 엄격한 값을 적용합니다. [`policyHelper`](/docs/ko/settings-reference#policyhelper) 플릿에서, Claude Code는 도우미의 출력에서만 잠금을 읽습니다.441우선 소스보다 낮은 관리자 소스에서도 두 샌드박스 잠금은 여전히 적용되며, `allowManagedPermissionRulesOnly`는 여전히 부모가 제공한 허용 규칙과 `additionalDirectories`를 차단합니다. Claude Code v2.1.273 이상에서는 MCP 서버 잠금도 우선 소스보다 낮은 소스에서 적용되며, 이 잠금이 켜져 있는 동안 관리형 `allowedMcpServers` 목록은 이를 설정하는 가장 높은 우선순위의 관리자 소스에서 가져옵니다.

442 442

443각 잠금은 Claude Code가 해당 설정에 대한 개발자의 자신의 항목을 무시하도록 하므로, 조직의 허용 목록을 잠금 옆에 포함하세요:443훅 잠금과, 개발자 자신의 규칙에 대한 `allowManagedPermissionRulesOnly`의 효과는 기본적으로 우선 소스에 설정되어야 합니다. [Claude Code가 관리형 소스를 결합하는 방법](/docs/ko/managed-settings#how-claude-code-combines-managed-sources)의 `managedSourcesBehavior` 병합 옵트인에서는 Claude Code가 모든 잠금에 대해 어느 소스든 설정한 가장 엄격한 값을 적용합니다. [`policyHelper`](/docs/ko/settings-reference#policyhelper) 플릿에서는 Claude Code가 헬퍼의 출력에서만 잠금을 읽습니다.

444 444

445* **네트워크 도메인**: 빈 관리 도메인 목록으로 잠그면 모든 샌드박스 아웃바운드 트래픽이 차단됩니다.445각 잠금은 Claude Code가 해당 설정에 대한 개발자 자신의 항목을 무시하게 하므로, 조직의 허용 목록을 잠금과 함께 포함하세요.

446* **MCP 서버**: 관리되거나 부모 제공 `allowedMcpServers` 없이 잠그면 `deniedMcpServers`가 차단하지 않는 모든 서버가 로드됩니다.446

447* **읽기 경로**: `allowRead` 항목은 `denyRead` 영역 내의 경로만 다시 허용하므로, 관리 `denyRead`와 쌍을 이루세요.447* **네트워크 도메인**: 관리형 도메인 목록이 비어 있는 상태로 잠그면 샌드박스의 모든 아웃바운드 트래픽이 차단됩니다.

448* **MCP 서버**: 어떤 관리자 소스에도, 부모가 제공한 설정에도 `allowedMcpServers`가 없는 상태로 잠그면 `deniedMcpServers`가 차단하지 않는 모든 서버가 로드됩니다.

449* **읽기 경로**: `allowRead` 항목은 `denyRead` 영역 내의 경로만 다시 허용하므로, 관리형 `denyRead`와 함께 사용하세요.

448 450

449<h4 id="settings-the-locks-don’t-cover">451<h4 id="settings-the-locks-don’t-cover">

450 잠금이 다루지 않는 설정452 잠금이 다루지 않는 설정

451</h4>453</h4>

452 454

453여섯 개의 부모 제공 설정은 다섯 개의 잠금이 모두 설정되어도 필터를 통과합니다. 기본 첫 번째 우승 설정에서, 부모를 차단하는 관리 값은 가장 높은 우선순위 관리 소스의 값입니다. [MCP 서버 잠금](#lock-behavior-across-sources)이 켜져 있는 동안 `allowedMcpServers` 제외. `managedSourcesBehavior` 병합 옵트인에서, [Claude Code가 관리 소스를 결합하는 방법](/docs/ko/managed-settings#how-claude-code-combines-managed-sources)은 대신 어느 소스의 값이 적용되는지 말합니다.455다음 부모 제공 설정은 다섯 개의 잠금을 모두 설정해도 필터를 통과합니다.

456

457* **`forceLoginOrgUUID`**: 가장 높은 우선순위의 관리자 소스가 조직 UUID를 설정하지 않으면 Claude Code는 부모가 제공한 값을 따릅니다. 게이트웨이 로그인은 이 키를 확인하지 않습니다. 가장 높은 우선순위의 관리자 소스에 있는 조직 UUID는 부모의 값을 차단하며, Claude Code가 적용하는 값이 됩니다.

458* **`allowedMcpServers`**: 유효한 관리자 목록이 없으면 Claude Code는 부모가 제공한 허용 목록을 따릅니다. `allowManagedMcpServersOnly`는 이를 차단하지 않습니다. 이 잠금은 우선하는 목록을 관리형 값으로 적용하며, 관리자 소스가 목록을 제공하지 않으면 부모가 제공한 목록도 여기에 포함되기 때문입니다. 가장 높은 우선순위의 관리자 소스에 있는 목록은 부모의 목록을 차단하며 Claude Code가 적용하는 목록이 되므로, 해당 소스에 잠금과 함께 `allowedMcpServers`를 설정하세요. v2.1.223 이전에는 어느 관리자 소스에든 두 키 중 하나의 값이 있으면 부모의 값이 차단되었습니다.

459* **`availableModels`**: 우선하는 관리형 소스가 모델 목록을 설정하지 않으면 Claude Code는 부모가 제공한 모델 목록을 따릅니다. 플릿에서 모델을 제한한다면 우선 소스에 `availableModels`를 설정하세요.

460* **`allowedProviders`**: 우선하는 관리형 소스가 API 제공자 허용 목록을 설정하지 않으면 Claude Code는 부모가 제공한 API 제공자 허용 목록을 따릅니다. 플릿에서 개발자가 사용할 수 있는 API 제공자를 제한한다면 우선 소스에 `allowedProviders`를 설정하세요. Claude Code v2.1.285 이상이 필요합니다.

461* **`strictKnownMarketplaces`**: 우선하는 관리형 소스가 플러그인 마켓플레이스 허용 목록을 설정하지 않으면 Claude Code는 부모가 제공한 플러그인 마켓플레이스 허용 목록을 따릅니다. Claude Desktop 2.16120.0 이상은 관리형 구성에서 사용자 추가 플러그인 마켓플레이스를 끄면 이 목록을 보냅니다. 플릿에서 마켓플레이스를 제한한다면 우선 소스에 `strictKnownMarketplaces`를 설정하세요. Claude Code v2.1.282 이상이 필요합니다.

462* **`blockedMarketplaces`**: 부모가 제공한 마켓플레이스 차단 목록은 필터를 통과하며, 관리형 소스가 설정한 차단 목록에 추가됩니다. 차단 목록은 제한을 더할 수만 있기 때문입니다. Claude Code v2.1.282 이상이 필요합니다.

463* **`strictPluginOnlyCustomization`**: 이 키는 어떤 잠금과도 관계없이 필터를 통과하며, Claude Code가 보호용 훅을 포함한 개발자 자신의 사용자 정의를 무시하게 합니다. 이를 차단하는 잠금은 없습니다.

454 464

455* **`forceLoginOrgUUID`**: 가장 높은 우선순위 관리 소스가 조직 UUID를 설정하지 않을 때 Claude Code는 부모 제공 값을 준수합니다. 게이트웨이 로그인은 이 키를 확인하지 않습니다. 가장 높은 우선순위 관리 소스의 조직 UUID는 부모의 값을 차단하며 Claude Code가 적용하는 값입니다.465기본 first-wins 설정에서는 관리자 값이 가장 높은 우선순위의 관리자 소스에 있을 때만 부모의 값을 차단합니다. 단, [MCP 서버 잠금](#lock-behavior-across-sources)이 켜져 있는 동안의 `allowedMcpServers`는 예외입니다. `managedSourcesBehavior` 병합 옵트인에서는 [Claude Code가 관리형 소스를 결합하는 방법](/docs/ko/managed-settings#how-claude-code-combines-managed-sources)에 따라 어느 소스의 값이 적용되는지가 결정됩니다.

456* **`allowedMcpServers`**: 가장 높은 우선순위 관리 소스가 허용 목록을 설정하지 않을 때 Claude Code는 부모 제공 허용 목록을 준수하며, `allowManagedMcpServersOnly`는 이를 차단하지 않습니다. 잠금은 우승 목록을 관리 값으로 적용하기 때문입니다. 가장 높은 우선순위 관리 소스의 목록은 부모의 목록을 차단하며 Claude Code가 적용하는 목록이므로, 잠금 옆에 거기에 `allowedMcpServers`를 설정하세요. v2.1.223 이전에는, 모든 관리 소스의 어느 키에 대한 값이든 부모의 값을 차단했습니다.

457* **`availableModels`**: Claude Code는 우승 관리 소스가 모델 목록을 설정하지 않을 때 부모 제공 모델 목록을 준수합니다. 플릿이 모델을 제한하면, 우승 소스에 `availableModels`를 설정하세요.

458* **`strictKnownMarketplaces`**: Claude Code는 우승 관리 소스가 플러그인 마켓플레이스 허용 목록을 설정하지 않을 때 부모 제공 플러그인 마켓플레이스 허용 목록을 준수합니다. Claude Desktop 2.16120.0 이상은 관리 구성이 사용자 추가 플러그인 마켓플레이스를 끌 때 하나를 보냅니다. 플릿이 마켓플레이스를 제한하면, 우승 소스에 `strictKnownMarketplaces`를 설정하세요. Claude Code v2.1.282 이상이 필요합니다.

459* **`blockedMarketplaces`**: 부모 제공 마켓플레이스 차단 목록은 통과하고 관리 소스가 설정한 모든 차단 목록에 추가됩니다. 차단 목록은 더 제한할 수만 있기 때문입니다. Claude Code v2.1.282 이상이 필요합니다.

460* **`strictPluginOnlyCustomization`**: 이 키는 모든 잠금과 관계없이 필터를 통과하며, Claude Code가 개발자의 자신의 사용자 정의(보호 hooks 포함)를 무시하도록 합니다. 이를 차단하는 잠금이 없습니다.

461 466

462<h3 id="connect-claude-desktop">467<h3 id="connect-claude-desktop">

463 Claude Desktop 연결468 Claude Desktop 연결

464</h3>469</h3>

465 470

466[Claude Desktop](/docs/ko/desktop)은 다른 MDM 키를 통해 동일한 게이트웨이에 연결합니다: Claude Desktop의 [관리 구성](https://claude.com/docs/third-party/claude-desktop/configuration)에서 `bootstrapUrl`을 `<listen.public_url>/user/bootstrap`으로 설정하고, 사용자의 정책을 `desktop` 키로 옵트인하세요. [Claude Desktop 오버레이](/docs/ko/claude-apps-gateway-config#claude-desktop-overlay)는 둘 다를 다룹니다. 게이트웨이 서버에서 Claude Code v2.1.203 이상이 필요합니다.471[Claude Desktop](/docs/ko/desktop)은 다른 MDM 키를 통해 동일한 게이트웨이에 연결합니다. Claude Desktop의 [관리형 구성](https://claude.com/docs/third-party/claude-desktop/configuration)에서 `bootstrapUrl`을 `<listen.public_url>/user/bootstrap`으로 설정하고, `desktop` 키로 사용자의 정책을 옵트인하세요. [Claude Desktop 오버레이](/docs/ko/claude-apps-gateway-config#claude-desktop-overlay)에서 두 부분을 모두 다룹니다. 게이트웨이 서버에 Claude Code v2.1.203 이상이 필요합니다.

467 472

468Claude Desktop은 동일한 브라우저 SSO 단계로 게이트웨이의 ID 제공자를 통해 개발자에게 로그인하고, Anthropic 대신 게이트웨이에서 구성을 가져옵니다. 모델 액세스 및 정책은 CLI와 동일한 그룹별 규칙을 따릅니다. CLI와 Claude Desktop을 모두 사용하는 개발자는 각각에 별도로 로그인합니다; 게이트웨이 세션은 이들 사이에 공유되지 않습니다.473Claude Desktop은 동일한 브라우저 SSO 단계로 게이트웨이의 ID 제공자를 통해 개발자를 로그인시킨 다음, Anthropic 대신 게이트웨이에서 구성을 가져옵니다. 모델 액세스와 정책은 CLI와 동일한 그룹별 규칙을 따릅니다. CLI와 Claude Desktop을 모두 사용하는 개발자는 각각 별도로 로그인하며, 게이트웨이 세션은 둘 사이에 공유되지 않습니다.

469 474

470연결되면, Claude Desktop은 활성화된 모든 탭에서 모델 요청을 게이트웨이를 통해 보냅니다. 기본적으로 Cowork 및 Code 탭을 표시합니다. Chat 탭도 켜려면, Claude Desktop의 [관리 구성](https://claude.com/docs/third-party/claude-desktop/configuration)에서 `chatTabEnabled`를 `true`로 설정하거나, Claude Code v2.1.227 이상을 실행하는 게이트웨이의 정책 [`desktop` 블록](/docs/ko/claude-apps-gateway-config#claude-desktop-overlay)에서 설정하세요.475연결되면 Claude Desktop은 활성화된 모든 탭의 모델 요청을 게이트웨이를 통해 보냅니다. 기본적으로 Cowork 및 Code 탭이 표시됩니다. Chat 탭도 켜려면 Claude Desktop의 [관리형 구성](https://claude.com/docs/third-party/claude-desktop/configuration)에서 `chatTabEnabled`를 `true`로 설정하거나, Claude Code v2.1.227 이상을 실행하는 게이트웨이에서 정책의 [`desktop` 블록](/docs/ko/claude-apps-gateway-config#claude-desktop-overlay)에 설정하세요.

471 476

472<h3 id="ci-pipelines-and-remote-machines">477<h3 id="ci-pipelines-and-remote-machines">

473 CI 파이프라인 및 원격 머신478 CI 파이프라인 및 원격 머신

474</h3>479</h3>

475 480

476무인 파이프라인을 위한 서비스 토큰 흐름이 없습니다. 게이트웨이 로그인은 항상 브라우저 장치 흐름을 실행하므로, 로그인을 승인할 개발자가 없는 CI 작업은 인증할 수 없습니다; 제공자에 대해 직접 구성하세요.481무인 파이프라인을 위한 서비스 토큰 흐름은 없습니다. 게이트웨이 로그인은 항상 브라우저 디바이스 흐름을 실행하므로, 로그인을 승인할 개발자가 없는 CI 작업은 인증할 수 없습니다. 이러한 작업은 제공자에 직접 연결하도록 구성하세요.

477 482

478개발자가 로그인하면, 해당 머신의 모든 Claude Code 세션은 게이트웨이 세션을 사용하며, 비대화형 `claude -p` 실행 및 Agent SDK에서 시작된 세션을 포함합니다. Claude Code는 [게이트웨이 정책](/docs/ko/claude-apps-gateway-config#managed)을 각각에 적용합니다.483개발자가 로그인하면 해당 머신의 각 Claude Code 세션은 비대화형 `claude -p` 실행과 Agent SDK에서 시작된 세션을 포함하여 게이트웨이 세션을 사용합니다. Claude Code는 각 세션에 [게이트웨이 정책](/docs/ko/claude-apps-gateway-config#managed)을 적용합니다.

479 484

480장치 흐름은 폴링 CLI를 승인하는 브라우저에서 분리하므로, 디스플레이가 없는 원격 개발 상자도 작동합니다: 개발자는 원격 머신에서 SSH를 통해 `/login`을 실행하고 노트북의 브라우저에서 확인 링크를 엽니다.485디바이스 흐름은 폴링하는 CLI와 승인하는 브라우저를 분리하므로, 디스플레이가 없는 원격 개발 머신에서도 작동합니다. 개발자는 원격 머신에서 SSH를 통해 `/login`을 실행하고 노트북의 브라우저에서 확인 링크를 엽니다.

481 486

482<h3 id="whats-enforced-on-developers">487<h3 id="whats-enforced-on-developers">

483 개발자에게 적용되는 것488 개발자에게 적용되는 사항

484</h3>489</h3>

485 490

486이러한 보장은 `/login`을 통해 로그인한 모든 세션에 적용됩니다. Claude Desktop이 시작하는 포함된 세션은 [Claude Desktop 세션에 정책 전달](#deliver-policy-to-claude-desktop-sessions)에서 설명한 대로 정책을 가져오며, 텔레메트리 글머리 기호는 내보내기가 어디로 가는지 말합니다.491다음 보장 사항은 `/login`을 통해 로그인한 모든 세션에 적용됩니다. Claude Desktop이 시작하는 내장된 세션은 [Claude Desktop 세션에 정책 전달](#deliver-policy-to-claude-desktop-sessions)에 설명된 방식으로 정책을 가져오며, 텔레메트리 항목에 해당 세션의 내보내기가 어디로 가는지 설명되어 있습니다.

~~487~~ 492

488* **모델 액세스**: 정책이 부여하지 않는 모델에 대한 요청은 400을 반환하고, `/model` 선택기는 정책의 `availableModels` 허용 목록으로 필터링됩니다. 정책에서 [`enforceAvailableModels: true`](/docs/ko/model-config#default-model-behavior)를 설정하여 Default 옵션이 `availableModels` 내의 모델로 확인되도록 하세요. 없으면 Default는 선택 가능하게 유지되고 해당 모델이 부여되지 않으면 요청 시 거부됩니다.493* **모델 액세스**: 정책이 허용하지 않는 모델에 대한 요청은 400을 반환하며, `/model` 선택기는 정책의 `availableModels` 허용 목록으로 필터링됩니다. 여기에는 개발자가 모델을 선택하기 전에 세션이 시작될 때 사용하는 모델도 포함됩니다. [정책이 허용하는 모델로 세션 시작](/docs/ko/claude-apps-gateway-config#start-sessions-on-a-model-the-policy-allows)을 참조하세요.

489* **텔레메트리 대상**: `/login`을 통해 로그인한 세션에서, CLI는 로컬로 설정된 `OTEL_EXPORTER_OTLP_ENDPOINT`와 관계없이 OTLP/HTTP 내보내기를 게이트웨이로 보내며, 정책이 [수집기를 엔드포인트로 지정](/docs/ko/claude-apps-gateway-config#export-directly-to-your-collector)하지 않는 한, 게이트웨이는 이들을 [`telemetry.forward_to`](/docs/ko/claude-apps-gateway-config#telemetry)의 대상으로 중계합니다.494* **텔레메트리 대상**: `/login`을 통해 로그인한 세션에서 CLI는 정책이 [수집기를 엔드포인트로 지정](/docs/ko/claude-apps-gateway-config#export-directly-to-your-collector)하지 않는 한, 로컬에 설정된 `OTEL_EXPORTER_OTLP_ENDPOINT`가 아니라 게이트웨이로 OTLP/HTTP 내보내기를 보냅니다. 게이트웨이는 받은 내보내기를 [`telemetry.forward_to`](/docs/ko/claude-apps-gateway-config#telemetry)의 대상으로 중계합니다.

490 * [Claude Desktop이 시작하는](#connect-claude-desktop) 포함된 세션에서, CLI는 구성된 `OTEL_EXPORTER_OTLP_ENDPOINT`로 내보내기를 보냅니다. CLI는 해당 엔드포인트가 게이트웨이 자체를 가리킬 때만 이러한 내보내기에 게이트웨이 세션 토큰을 첨부합니다.495 * [Claude Desktop이 시작하는](#connect-claude-desktop) 내장된 세션에서 CLI는 구성된 `OTEL_EXPORTER_OTLP_ENDPOINT`로 내보내기를 보냅니다. CLI는 해당 엔드포인트가 게이트웨이 자체를 가리킬 때만 이러한 내보내기에 게이트웨이 세션 토큰을 첨부합니다.

491 * 신호에 대해 구성된 대상이 없으면, 게이트웨이는 이를 수락하고 폐기합니다.496 * 신호에 대해 구성된 대상이 없으면 게이트웨이는 이를 수락한 후 폐기합니다.

492 * 이미 Claude Code 텔레메트리를 직접 수집하면, 수집기를 `forward_to` 대상으로 추가하거나, 정책에서 이를 엔드포인트로 지정하여 중계를 건너뛰세요.497 * 이미 Claude Code 텔레메트리를 직접 수집하고 있다면, 수집기를 `forward_to` 대상으로 추가하거나 정책에서 수집기를 지정하여 중계를 건너뛰세요.

493* **자격증명**: 게이트웨이 토큰은 세션의 유일한 자격증명입니다. [Anthropic 프로필](/docs/ko/authentication#anthropic-profiles-and-federation-credentials) 및 이전 claude.ai 로그인은 로그인 중에 무시되므로, 개발자는 먼저 claude.ai에서 로그아웃할 필요가 없습니다. 구성된 `ANTHROPIC_API_KEY`, `ANTHROPIC_AUTH_TOKEN`, 또는 `apiKeyHelper` 자격증명의 경우, [Administrator policy requires a Cloud gateway sign-in](/docs/ko/errors#administrator-policy-requires-a-cloud-gateway-sign-in)을 참조하세요.498* **자격 증명**: 게이트웨이 토큰이 세션의 유일한 자격 증명입니다. 로그인된 동안에는 [Anthropic 프로필](/docs/ko/authentication#anthropic-profiles-and-federation-credentials)과 이전의 모든 claude.ai 로그인이 무시되므로, 개발자가 먼저 claude.ai에서 로그아웃할 필요가 없습니다. 구성된 `ANTHROPIC_API_KEY`, `ANTHROPIC_AUTH_TOKEN` 또는 `apiKeyHelper` 자격 증명, 또는 이전 Claude Console 로그인으로 저장된 API 키에 대해서는 [Administrator policy requires a Cloud gateway sign-in](/docs/ko/errors#administrator-policy-requires-a-cloud-gateway-sign-in)을 참조하세요.

494* **관리 설정**: 잠긴 키는 로컬로 재정의될 수 없습니다. CLI는 시작 시 정책을 적용하고 각 시간별 폴에서 변경을 적용하며, [다음 시작에만 적용되는 변경](/docs/ko/server-managed-settings#fetch-and-caching-behavior)은 제외합니다.499* **관리형 설정**: 잠긴 키는 로컬에서 재정의할 수 없습니다. CLI는 시작 시 정책을 적용하고 매시간 폴링할 때마다 변경 사항을 적용하며, [다음 실행 시에만 적용되는 변경 사항](/docs/ko/server-managed-settings#fetch-and-caching-behavior)은 예외입니다.

495* **게이트웨이에 도달할 수 없는 상태에서 시작**: 로그인한 세션은 설정 없이 시작하는 대신 약 10초 후 시작 시 오류로 종료됩니다.500* **게이트웨이에 연결할 수 없는 상태에서 시작**: 로그인된 세션은 설정 없이 시작하는 대신 약 10초 후 오류와 함께 시작 시 종료됩니다.

496* **게이트웨이가 세션을 종료한 후 시작**: [실패 폐쇄 시작 적용](/docs/ko/server-managed-settings#enforce-fail-closed-startup)을 참조하여 어느 시작이 게이트웨이에서 로그아웃된 상태로 열리고 어느 시작이 게이트웨이가 `401`로 응답할 때 종료되는지 확인하세요.501* **게이트웨이가 세션을 종료한 후 시작**: 게이트웨이에서 로그아웃된 상태로 열리는 실행과 게이트웨이가 `401`로 응답할 때 종료되는 실행에 대해서는 [실패 시 차단 시작 적용](/docs/ko/server-managed-settings#enforce-fail-closed-startup)을 참조하세요.

497* **프로비저닝 해제**: 사용자가 IdP에서 비활성화된 세션은 다음 새로 고침이 실패할 때 `ttl_hours` 내에 만료됩니다.502* **프로비저닝 해제**: IdP에서 사용자가 비활성화된 세션은 다음 새로 고침이 실패하면 `ttl_hours` 내에 만료됩니다.

498* **로그아웃**: `/logout`은 개발자의 머신에서 게이트웨이 자격증명을 삭제합니다.503* **로그아웃**: `/logout`은 개발자 머신에서 게이트웨이 자격 증명을 삭제합니다.

499 * 게이트웨이의 검색 문서가 게이트웨이 URL의 자신의 스킴, 호스트, 포트에서 `revocation_endpoint`를 광고할 때, `/logout`은 또한 저장된 토큰을 해당 엔드포인트로 보내므로 게이트웨이가 자신의 측에서 세션을 종료할 수 있습니다. 요청은 최선의 노력이므로, 엔드포인트가 응답하는지 여부와 관계없이 로그아웃은 개발자의 머신에서 완료됩니다. 취소는 개발자 머신의 Claude Code v2.1.275 이상이 필요합니다.504 * 게이트웨이의 검색 문서가 게이트웨이 URL과 동일한 스킴, 호스트, 포트의 `revocation_endpoint`를 알리면, `/logout`은 저장된 토큰을 해당 엔드포인트로도 보내 게이트웨이가 자체적으로 세션을 종료할 수 있게 합니다. 이 요청은 최선 노력 방식이므로, 엔드포인트의 응답 여부와 관계없이 개발자 머신에서 로그아웃이 완료됩니다. 이 토큰 취소에는 개발자 머신에 Claude Code v2.1.275 이상이 필요합니다.

500 * `claude` 바이너리의 게이트웨이 서버는 광고하지 않으므로, 로그아웃은 개발자의 머신에서만 세션을 종료합니다. 서버 측에서 세션을 강제로 종료하려면, [JWT 비밀 회전](/docs/ko/claude-apps-gateway-deploy#jwt-secret-rotation)을 참조하세요.505 * `claude` 바이너리의 게이트웨이 서버는 이 엔드포인트를 알리지 않으므로, 해당 서버에서의 로그아웃은 개발자 머신에서만 세션을 종료합니다. 서버 측에서 세션을 강제로 종료하려면 [JWT 비밀 교체](/docs/ko/claude-apps-gateway-deploy#jwt-secret-rotation)를 참조하세요.

501 506

502<h3 id="what-the-organization-can-see">507<h3 id="what-the-organization-can-see">

503 조직이 볼 수 있는 것508 조직이 볼 수 있는 정보

504</h3>509</h3>

505 510

506사용 현황 텔레메트리는 개발자의 신원, 토큰 수, 모델 및 지연 시간을 조직의 수집기로 전달합니다. 게이트웨이는 프롬프트 또는 완료 콘텐츠를 기록하거나 저장하지 않습니다. 명령 및 파일 경로를 포함할 수 있는 로그 및 추적과 같은 더 풍부한 텔레메트리를 수집할지 여부는 조직의 [대상별 선택](/docs/ko/claude-apps-gateway-config#telemetry)입니다.511사용량 텔레메트리는 개발자의 신원, 토큰 수, 모델, 지연 시간을 조직의 수집기로 전달합니다. 게이트웨이는 프롬프트나 완성 콘텐츠를 로그에 기록하거나 저장하지 않습니다. 명령과 파일 경로를 포함할 수 있는 로그 및 트레이스 같은 더 풍부한 텔레메트리를 수집할지 여부는 조직의 [대상별 선택](/docs/ko/claude-apps-gateway-config#telemetry)에 달려 있습니다.

507 512

508<h2 id="availability-and-limitations">513<h2 id="availability-and-limitations">

509 가용성 및 제한사항514 가용성 및 제한사항

515 520

516| 기능 | 상태 | 참고 |521| 기능 | 상태 | 참고 |

517| - | - | - |522| - | - | - |

518| 추론 전달 (Amazon Bedrock, Claude Platform on AWS, Google Cloud의 Agent Platform, Microsoft Foundry, Anthropic) | 사용 가능 | 업스트림별 모델 변환 및 장애 조치 포함. Amazon Bedrock 업스트림은 `bedrock-runtime` 엔드포인트 및 AWS 기본 자격증명 체인을 사용합니다; Amazon Bedrock [Mantle 엔드포인트](/docs/ko/amazon-bedrock#use-the-mantle-endpoint)는 지원되는 업스트림이 아닙니다. [Claude Platform on AWS 업스트림](/docs/ko/claude-apps-gateway-config#claude-platform-on-aws)은 게이트웨이 서버에서 Claude Code v2.1.198 이상이 필요합니다. |523| 추론 전달 (Amazon Bedrock, Claude Platform on AWS, Google Cloud의 Agent Platform, Microsoft Foundry, Anthropic) | 사용 가능 | 업스트림별 모델 변환 및 장애 조치 포함. Amazon Bedrock 업스트림은 `bedrock-runtime` 엔드포인트 및 AWS 기본 자격 증명 체인을 사용합니다. [Amazon Bedrock Mantle 업스트림](/docs/ko/claude-apps-gateway-config#amazon-bedrock-mantle-endpoint)은 게이트웨이 서버에서 Claude Code v2.1.283 이상이 필요하며, [Claude Platform on AWS 업스트림](/docs/ko/claude-apps-gateway-config#claude-platform-on-aws)은 v2.1.198 이상이 필요합니다. |

520| Claude Desktop | 옵트인 가능 | 게이트웨이는 정책이 [`desktop` 키로 옵트인](/docs/ko/claude-apps-gateway-config#claude-desktop-overlay)하면 `/user/bootstrap`에서 Claude Desktop의 구성을 제공하며, Claude Desktop은 Cowork 및 Code 탭에서, 그리고 Chat 탭에서 활성화할 때 게이트웨이를 통해 모델 요청을 보냅니다. Chat 탭을 켜려면 [Claude Desktop 연결](#connect-claude-desktop)을 참조하세요. 게이트웨이 서버에서 Claude Code v2.1.203 이상이 필요합니다. |525| Claude Desktop | 옵트인 가능 | 게이트웨이는 정책이 [`desktop` 키로 옵트인](/docs/ko/claude-apps-gateway-config#claude-desktop-overlay)하면 `/user/bootstrap`에서 Claude Desktop의 구성을 제공하며, Claude Desktop은 Cowork 및 Code 탭에서, 그리고 Chat 탭에서 활성화할 때 게이트웨이를 통해 모델 요청을 보냅니다. Chat 탭을 켜려면 [Claude Desktop 연결](#connect-claude-desktop)을 참조하세요. 게이트웨이 서버에서 Claude Code v2.1.203 이상이 필요합니다. |

527| `/import` 및 `claude import`와 같은 기능 플래그 가져오기가 필요한 기능 | 사용 불가능 | CLI는 게이트웨이 세션에서 플래그 가져오기를 건너뜁니다. [기능 플래그 가져오기가 필요한 기능](/docs/ko/env-vars#features-that-need-feature-flag-fetching)은 이것이 비활성화하는 것을 나열합니다. |532| `/import` 및 `claude import`와 같은 기능 플래그 가져오기가 필요한 기능 | 사용 불가능 | CLI는 게이트웨이 세션에서 플래그 가져오기를 건너뜁니다. [기능 플래그 가져오기가 필요한 기능](/docs/ko/env-vars#features-that-need-feature-flag-fetching)은 이것이 비활성화하는 것을 나열합니다. |

528| 표준 프롬프트 캐싱 | 사용 가능 | 게이트웨이는 `cache_control` 중단점을 모든 업스트림으로 전달합니다. [캐시가 있는 위치](/docs/ko/prompt-caching#where-the-cache-lives)는 CLI가 표시하는 블록을 다룹니다. 여기에는 대화 중간에 추가하는 시스템 컨텍스트가 포함됩니다. |533| 표준 프롬프트 캐싱 | 사용 가능 | 게이트웨이는 `cache_control` 중단점을 모든 업스트림으로 전달합니다. [캐시가 있는 위치](/docs/ko/prompt-caching#where-the-cache-lives)는 CLI가 표시하는 블록을 다룹니다. 여기에는 대화 중간에 추가하는 시스템 컨텍스트가 포함됩니다. |

530| Auto 모드 | 사용 가능 | [타사 제공자 규칙](/docs/ko/permission-modes#enable-auto-mode-on-bedrock-agent-platform-or-foundry)을 따릅니다: 타사 제공자에서 적격인 모델만 사용할 수 있습니다. v2.1.207 이전에는 게이트웨이 세션의 auto 모드에서 `CLAUDE_CODE_ENABLE_AUTO_MODE=1` 설정이 필요했으며, 관리 정책 `env` 블록을 통해 전달 가능했습니다. |535| 자동 모드 | 사용 가능 | [타사 제공자 규칙](/docs/ko/permission-modes#enable-auto-mode-on-bedrock-agent-platform-or-foundry)을 따릅니다: 타사 제공자에서 적격인 모델만 사용할 수 있습니다. v2.1.207 이전에는 게이트웨이 세션의 자동 모드에서 `CLAUDE_CODE_ENABLE_AUTO_MODE=1` 설정이 필요했으며, 관리형 정책 `env` 블록을 통해 전달 가능했습니다. |

538 543

539<h2 id="next-steps">544<h2 id="next-steps">

540 다음 단계545 다음 단계

claude-apps-gateway-config.md +98 −24

Details

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

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

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

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

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

234| `connect_timeout_seconds` | 아니오 | 게이트웨이가 Postgres 연결을 열 때 대기하는 초입니다. `1`에서 `60` 사이의 정수이고 기본값은 `5`입니다. 새 게이트웨이 인스턴스가 시작될 때 연결 시도가 시간 초과되면 이를 높입니다. 게이트웨이 서버에서 Claude Code v2.1.274 이상이 필요합니다. 이전 버전은 키가 설정되면 시작을 거부합니다. |234| `connect_timeout_seconds` | 아니오 | 게이트웨이가 Postgres 연결을 열 때 대기하는 초입니다. `1`에서 `60` 사이의 정수이고 기본값은 `5`입니다. 새 게이트웨이 인스턴스가 시작될 때 연결 시도가 시간 초과되면 이를 높입니다. 게이트웨이 서버에서 Claude Code v2.1.274 이상이 필요합니다. 이전 버전은 키가 설정되면 시작을 거부합니다. |

235| `readiness_grace_seconds` | 아니오 | Postgres가 응답을 중지한 후 `/readyz`가 준비 상태를 계속 보고하는 초입니다. `0`에서 `3600` 사이의 정수이고 기본값은 `0`입니다. 값을 선택하는 방법은 [중단 동작](/docs/ko/claude-apps-gateway-deploy#outage-behavior)을 참조하세요. 게이트웨이 서버에서 Claude Code v2.1.282 이상이 필요합니다. 이전 버전은 키가 설정되면 시작을 거부합니다. |235| `readiness_grace_seconds` | 아니오 | Postgres가 응답을 중지한 후 `/readyz`가 준비 상태를 계속 보고하는 초입니다. `0`에서 `3600` 사이의 정수이고 기본값은 `0`입니다. 값을 선택하는 방법은 [중단 동작](/docs/ko/claude-apps-gateway-deploy#outage-behavior)을 참조하세요. 게이트웨이 서버에서 Claude Code v2.1.282 이상이 필요합니다. 이전 버전은 키가 설정되면 시작을 거부합니다. |

242 242

243`upstreams`는 정렬된 목록입니다. 게이트웨이는 요청된 모델을 해석하는 첫 번째 업스트림으로 추론을 전달합니다.243`upstreams`는 정렬된 목록입니다. 게이트웨이는 요청된 모델을 해석하는 첫 번째 업스트림으로 추론을 전달합니다.

244 244

245`5xx`, `429`, `401`, `403`, `404` 또는 시간 초과 시 게이트웨이는 다음 업스트림으로 장애 조치합니다. 다른 `4xx`는 그렇지 않습니다. 이 오류는 업스트림이 아닌 요청에 기인하기 때문입니다. `401` 또는 `403`은 게이트웨이가 해당 업스트림에 대해 사용한 자격증명이 실패했음을 의미합니다. `404`는 해당 업스트림이 요청된 모델을 제공하지 않으므로 목록의 나중 업스트림이 여전히 할 수 있음을 의미합니다.245`5xx`, `429`, `401`, `403`, `404` 또는 시간 초과 시 게이트웨이는 다음 업스트림으로 장애 조치합니다. 다른 `4xx`는 그렇지 않습니다. 이 오류는 업스트림이 아닌 요청에 기인하기 때문입니다. `401` 또는 `403`은 업스트림이 게이트웨이가 사용한 자격 증명을 거부했거나, 예를 들어 요청된 모델에 대한 액세스를 거부했음을 의미합니다. `404`는 해당 업스트림이 요청된 모델을 제공하지 않으므로 목록의 나중 업스트림이 여전히 할 수 있음을 의미합니다.

246 246

247업스트림에 `forward_user_identity: true`를 설정하면 개발자의 이메일을 전달한 요청에 반환하는 `429`는 장애 조치하지 않습니다. [프록시를 실행하는 경우 사용자별 제한 거부가 개발자에게 도달하는 방법](#per-user-identity-headers-for-a-proxy-you-run)을 참조하세요.247업스트림에 `forward_user_identity: true`를 설정하면 개발자의 이메일을 전달한 요청에 반환하는 `429`는 장애 조치하지 않습니다. [프록시를 실행하는 경우 사용자별 제한 거부가 개발자에게 도달하는 방법](#per-user-identity-headers-for-a-proxy-you-run)을 참조하세요.

248 248

250 250

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

252 252

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

254 254

255<h4 id="upstream-error-messages">255<h4 id="upstream-error-messages">

256 업스트림 오류 메시지256 업스트림 오류 메시지

289 # base_url: https://api.anthropic.com # default; override for a forward proxy289 # base_url: https://api.anthropic.com # default; override for a forward proxy

290```290```

291 291

292두 자격증명 형식은 전송하는 헤더에서 다릅니다:292두 자격 증명 형식은 전송하는 헤더에서 다릅니다:

293 293

294* **`api_key`**: `x-api-key`를 보냅니다. Claude 콘솔에서 회전하고 환경 변수를 업데이트합니다.294* **`api_key`**: `x-api-key`를 보냅니다. Claude 콘솔에서 회전하고 환경 변수를 업데이트합니다.

295* **`oauth_token`**: `Authorization: Bearer`를 보냅니다. 조직이 장기 API 키 대신 단기 토큰을 발행할 때 베어러 형식을 사용합니다. 베어러는 시작 시 한 번 읽혀지므로 비밀을 다시 마운트하고 재시작하여 새로 고칩니다.295* **`oauth_token`**: `Authorization: Bearer`를 보냅니다. 조직이 장기 API 키 대신 단기 토큰을 발행할 때 베어러 형식을 사용합니다. 베어러는 시작 시 한 번 읽혀지므로 비밀을 다시 마운트하고 재시작하여 새로 고칩니다.

363 # base_url: https://bedrock-runtime-fips.us-east-1.amazonaws.com363 # base_url: https://bedrock-runtime-fips.us-east-1.amazonaws.com

364```364```

365 365

366빈 `auth` 블록은 AWS SDK의 기본 자격증명 체인을 사용합니다: 환경 변수, `~/.aws/credentials`, ECS 작업 역할, EC2 인스턴스 메타데이터 또는 EKS의 IRSA. 프로덕션에서는 컨테이너 이미지에 정적 키를 포함하는 대신 게이트웨이 포드에 IAM 역할을 제공합니다.366빈 `auth` 블록은 AWS SDK의 기본 자격 증명 체인을 사용합니다: 환경 변수, `~/.aws/credentials`, ECS 작업 역할, EC2 인스턴스 메타데이터 또는 EKS의 IRSA. 프로덕션에서는 컨테이너 이미지에 정적 키를 포함하는 대신 게이트웨이 포드에 IAM 역할을 제공합니다.

367 367

368명시적 자격증명은 완전해야 합니다: `aws_access_key_id`와 `aws_secret_access_key`가 함께 설정되지 않거나 `aws_session_token`이 이들 없이 설정되면 게이트웨이는 부팅 시 실패합니다. v2.1.207 이전에는 부분 `auth:` 블록이 검증을 통과했습니다.368명시적 자격 증명은 완전해야 합니다: `aws_access_key_id`와 `aws_secret_access_key`가 함께 설정되지 않거나 `aws_session_token`이 이들 없이 설정되면 게이트웨이는 부팅 시 실패합니다. v2.1.207 이전에는 부분 `auth:` 블록이 검증을 통과했습니다.

369 369

370| 설정 | 방법 |370| 설정 | 방법 |

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

373| 모델 액세스 | Amazon Bedrock은 상용 지역에서 기본적으로 모델 액세스를 활성화합니다. 남은 계정 수준 게이트는 Anthropic의 일회용 사용 사례 양식입니다: AWS 계정의 아무도 제출하지 않았으면 Amazon Bedrock 콘솔을 열고 모델 카탈로그에서 Anthropic 모델을 선택하고 양식을 완료합니다. AWS Organizations 양식 및 제출자가 필요한 권한은 [사용 사례 세부 정보 제출](/docs/ko/amazon-bedrock#1-submit-use-case-details)을 참조하세요. |373| 모델 액세스 | Amazon Bedrock은 상용 지역에서 기본적으로 모델 액세스를 활성화합니다. 남은 계정 수준 게이트는 Anthropic의 일회용 사용 사례 양식입니다: AWS 계정의 아무도 제출하지 않았으면 Amazon Bedrock 콘솔을 열고 모델 카탈로그에서 Anthropic 모델을 선택하고 양식을 완료합니다. AWS Organizations 양식 및 제출자가 필요한 권한은 [사용 사례 세부 정보 제출](/docs/ko/amazon-bedrock#1-submit-use-case-details)을 참조하세요. |

374| EKS(IRSA) | 위의 정책과 클러스터의 OIDC 공급자에 대한 신뢰 정책이 있는 IAM 역할을 만듭니다. 게이트웨이의 서비스 계정으로 범위가 지정됩니다. 서비스 계정에 `eks.amazonaws.com/role-arn: arn:aws:iam::<acct>:role/claude-gateway`로 주석을 답니다. `auth: {}`가 이를 선택합니다. |374| EKS(IRSA) | 위의 정책과 클러스터의 OIDC 공급자에 대한 신뢰 정책이 있는 IAM 역할을 만듭니다. 게이트웨이의 서비스 계정으로 범위가 지정됩니다. 서비스 계정에 `eks.amazonaws.com/role-arn: arn:aws:iam::<acct>:role/claude-gateway`로 주석을 답니다. `auth: {}`가 이를 선택합니다. |

375| ECS / EC2 | IAM 역할을 작업 정의 또는 인스턴스 프로필에 연결합니다. `auth: {}`가 이를 선택합니다. |375| ECS / EC2 | IAM 역할을 작업 정의 또는 인스턴스 프로필에 연결합니다. `auth: {}`가 이를 선택합니다. |

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

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

378 378

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

401 401

402모든 `bedrock` 업스트림에 `guardrail`을 설정하거나 아무것도 설정하지 않습니다. 게이트웨이는 혼합에서 시작을 거부합니다. [장애 조치](#multiple-upstreams)가 요청을 가드레일이 없는 Bedrock 업스트림으로 보낼 수 있기 때문입니다.402모든 `bedrock` 업스트림에 `guardrail`을 설정하거나 아무것도 설정하지 않습니다. 게이트웨이는 혼합에서 시작을 거부합니다. [장애 조치](#multiple-upstreams)가 요청을 가드레일이 없는 Bedrock 업스트림으로 보낼 수 있기 때문입니다.

403 403

404가드레일은 Bedrock 업스트림만 적용합니다. `upstreams`에 다른 공급자를 나열하면 게이트웨이는 가드레일 없이 해당 공급자에 요청을 보냅니다.404가드레일은 Bedrock 업스트림만 적용합니다. `upstreams`에 다른 공급자를 나열하면 게이트웨이는 가드레일 없이 해당 공급자에 요청을 보내거나, 해당 공급자가 [`mantle`](#amazon-bedrock-mantle-endpoint)인 경우 시작을 거부합니다.

405 405

406`amazon-bedrock-*` 필드(예: `amazon-bedrock-guardrailConfig`)를 전달하는 `/v1/messages` 요청이 `guardrail`이 설정된 Bedrock 업스트림에 도달하면 게이트웨이는 전달하는 대신 400으로 응답합니다.406`amazon-bedrock-*` 필드(예: `amazon-bedrock-guardrailConfig`)를 전달하는 `/v1/messages` 요청이 `guardrail`이 설정된 Bedrock 업스트림에 도달하면 게이트웨이는 전달하는 대신 400으로 응답합니다.

407 407

411 다른 AWS 계정의 Bedrock411 다른 AWS 계정의 Bedrock

412</h5>412</h5>

413 413

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

415 415

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

417 417

448}448}

449```449```

450 450

451* STS가 거부하거나 도달할 수 없으면 게이트웨이는 업스트림의 자체 자격증명으로 요청을 보내지 않습니다. STS 오류를 기록하고 확인할 내용을 기록한 후 나열한 다음 업스트림을 시도합니다. [업스트림 오류 메시지](#upstream-error-messages)는 업스트림이 성공하지 못할 때 클라이언트가 받는 것을 다룹니다. `assume_role` 없는 나중 업스트림은 자체 자격증명으로 요청을 제공하므로 원하는 경우에만 나열합니다.451* STS가 거부하거나 도달할 수 없으면 게이트웨이는 업스트림의 자체 자격 증명으로 요청을 보내지 않습니다. STS 오류를 기록하고 확인할 내용을 기록한 후 나열한 다음 업스트림을 시도합니다. [업스트림 오류 메시지](#upstream-error-messages)는 업스트림이 성공하지 못할 때 클라이언트가 받는 것을 다룹니다. `assume_role` 없는 나중 업스트림은 자체 자격 증명으로 요청을 제공하므로 원하는 경우에만 나열합니다.

452* 게이트웨이는 지역 STS 엔드포인트 `sts.<region>.amazonaws.com`을 호출합니다. 네트워크가 도달해야 합니다. FIPS 엔드포인트의 경우 AWS 구성 파일의 `use_fips_endpoint` 대신 게이트웨이의 환경에서 `AWS_USE_FIPS_ENDPOINT=true`를 설정합니다.452* 게이트웨이는 지역 STS 엔드포인트 `sts.<region>.amazonaws.com`을 호출합니다. 네트워크가 도달해야 합니다. FIPS 엔드포인트의 경우 AWS 구성 파일의 `use_fips_endpoint` 대신 게이트웨이의 환경에서 `AWS_USE_FIPS_ENDPOINT=true`를 설정합니다.

453* `assume_role`은 `provider: bedrock`에만 적용되고 SigV4 소스 자격증명이 필요합니다: 게이트웨이는 `aws_bearer_token` 옆에 설정되면 시작을 거부합니다.453* `assume_role`은 `provider: bedrock`에만 적용되고 SigV4 소스 자격 증명이 필요합니다: 게이트웨이는 `aws_bearer_token` 옆에 설정되면 시작을 거부합니다.

454* 게이트웨이가 허용하는 모든 개발자는 이 업스트림을 사용할 수 있습니다. [`managed`](#managed)는 어느 개발자가 어느 모델을 사용할 수 있는지를 제어합니다. 역할을 통해 제공되는 모델이 다른 계정에서도 제공되지 않도록 하려면 `upstream_model` 맵이 이 업스트림의 이름만 가지는 사용자 정의 ID를 제공합니다. 이러한 ID의 경우 게이트웨이는 다른 모든 업스트림을 건너뜁니다. 따라서 요청도 포기된 요청의 토큰 계산도 다른 계정으로 장애 조치할 수 없습니다. 기본 제공 모델 이름은 여전히 순서대로 모든 업스트림에서 시도되고 이 이름에 도달하는 요청은 동일한 역할로 서명되므로 계정도 이를 제공해야 하지 않으면 이 업스트림을 마지막에 나열합니다.454* 게이트웨이가 허용하는 모든 개발자는 이 업스트림을 사용할 수 있습니다. [`managed`](#managed)는 어느 개발자가 어느 모델을 사용할 수 있는지를 제어합니다. 역할을 통해 제공되는 모델이 다른 계정에서도 제공되지 않도록 하려면 `upstream_model` 맵이 이 업스트림의 이름만 가지는 사용자 정의 ID를 제공합니다. 이러한 ID의 경우 게이트웨이는 다른 모든 업스트림을 건너뜁니다. 따라서 요청도 포기된 요청의 토큰 계산도 다른 계정으로 장애 조치할 수 없습니다. 기본 제공 모델 이름에 대한 요청은 여전히 [이 업스트림에 도달](#multiple-upstreams)할 수 있으며 게이트웨이는 동일한 역할로 이에 서명합니다. 해당 계정도 이 모델을 제공해야 하는 경우가 아니면 이 업스트림을 마지막에 나열합니다.

455 455

456이 예제는 격리된 업스트림만 제공하는 사용자 정의 ID를 가진 하나의 모델을 제공합니다:456이 예제는 격리된 업스트림만 제공하는 사용자 정의 ID를 가진 하나의 모델을 제공합니다:

457 457

468 개발자별 AWS 비용 기인468 개발자별 AWS 비용 기인

469</h5>469</h5>

470 470

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

472 472

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

474 474

488 488

489게이트웨이는 또한 이 역할에 대해 하나의 호출을 만듭니다: 클라이언트가 포기한 요청의 토큰 계산입니다. 따라서 [지출 제한](/docs/ko/claude-apps-gateway-spend-limits)이 정확하게 유지됩니다. 해당 계산 및 [일회용 폴백 요청](#amazon-bedrock)은 공유 `claude-apps-gateway` 세션으로 서명되므로 AWS는 폴백을 개발자가 아닌 `claude-apps-gateway`에 기인합니다.489게이트웨이는 또한 이 역할에 대해 하나의 호출을 만듭니다: 클라이언트가 포기한 요청의 토큰 계산입니다. 따라서 [지출 제한](/docs/ko/claude-apps-gateway-spend-limits)이 정확하게 유지됩니다. 해당 계산 및 [일회용 폴백 요청](#amazon-bedrock)은 공유 `claude-apps-gateway` 세션으로 서명되므로 AWS는 폴백을 개발자가 아닌 `claude-apps-gateway`에 기인합니다.

490 490

491엄격한 개발자별 기인의 경우 나열하는 모든 Bedrock 업스트림에 `session_name`을 사용하여 `assume_role`을 설정합니다. 이것 없는 업스트림은 자체 자격증명으로 제공하는 요청에 서명합니다.491엄격한 개발자별 기인의 경우 나열하는 모든 Bedrock 업스트림에 `session_name`을 사용하여 `assume_role`을 설정합니다. 이것 없는 업스트림은 자체 자격 증명으로 제공하는 요청에 서명합니다.

492

493<h4 id="amazon-bedrock-mantle-endpoint">

494 Amazon Bedrock Mantle 엔드포인트

495</h4>

496

497`mantle` 공급자는 추론을 Amazon Bedrock의 [Mantle 엔드포인트](/docs/ko/amazon-bedrock#use-the-mantle-endpoint)로 보냅니다. 게이트웨이 서버에서 Claude Code v2.1.283 이상이 필요합니다. 이전 게이트웨이 릴리스는 부팅 시 이를 거부하므로 추가하기 전에 모든 복제본을 업그레이드합니다.

498

499아래 예제는 Mantle을 첫 번째에 두고, 그 뒤에 `models` 필드가 제외하는 모든 모델을 제공할 Amazon Bedrock 업스트림을 둡니다:

500

501```yaml theme={null}

502upstreams:

503 - provider: mantle

504 region: us-east-1

505 models: [claude-opus-4-7, claude-haiku-4-5] # required

506 auth: {} # AWS default credential chain

507 - provider: bedrock

508 region: us-east-1

509 auth: {}

510```

511

512아래 표는 `mantle` 업스트림에 특정한 필드를 나열합니다.

513

514| 필드 | 필수 | 설명 |

515| - | - | - |

516| `region` | 예 | AWS 지역입니다. 게이트웨이는 이로부터 엔드포인트를 `https://bedrock-mantle.<region>.api.aws/anthropic`로 파생시킵니다. |

517| `models` | 예 | AWS 계정이 Mantle에서 부여받은 모델로, `claude-haiku-4-5`처럼 클라이언트가 보내는 이름으로 지정합니다. 이 모델만 이 업스트림으로 이동하고 다른 모든 모델은 다음 업스트림으로 건너뜁니다. |

518| `auth` | 아니오 | [Amazon Bedrock](#amazon-bedrock) 업스트림의 `auth` 블록과 동일한 키를 동일한 규칙에 따라 사용합니다. |

519| `base_url` | 아니오 | 파생된 엔드포인트를 재정의합니다. 끝에 `/anthropic` 경로를 유지합니다. |

520

521업스트림의 AWS 신원에 [Mantle 엔드포인트 사용](/docs/ko/amazon-bedrock#use-the-mantle-endpoint)에 나열된, 추론 및 토큰 계산을 위한 Mantle 자체 IAM 작업을 부여합니다.

522

523게이트웨이가 모르는 Mantle 모델 ID의 경우 최상위 [`models:`](#models) 블록에 `upstream_model`이 이 업스트림의 이름을 해당 ID에 매핑하는 항목을 추가합니다. 그런 다음 해당 항목의 `id`를 이 업스트림의 `models` 필드에도 넣습니다.

524

525`bedrock` 업스트림의 `guardrail` 및 `assume_role` 설정은 Mantle이 제공하는 요청으로 확장되지 않습니다:

526

527* **`guardrail`**: 게이트웨이는 Mantle로 보내는 요청에 [Bedrock 가드레일](#apply-an-amazon-bedrock-guardrail)을 적용하지 않으므로 `bedrock` 업스트림 중 하나라도 `guardrail`을 설정한 상태에서 `mantle` 업스트림이 나열되면 시작을 거부합니다.

528* **`assume_role`**: `mantle` 업스트림은 [`assume_role`](#bedrock-in-another-aws-account)을 사용하지 않습니다. Mantle이 제공하는 요청은 `mantle` 업스트림 자체의 `auth` 자격 증명으로 전송되며 [개발자별로 기인](#per-developer-aws-cost-attribution)되지 않습니다.

529

530Mantle 자체 오류 응답의 의미는 [Mantle 엔드포인트 오류](/docs/ko/amazon-bedrock#mantle-endpoint-errors)를 참조하세요.

492 531

493<h4 id="claude-platform-on-aws">532<h4 id="claude-platform-on-aws">

494 Claude Platform on AWS533 Claude Platform on AWS

515 # base_url: https://aws-external-anthropic.us-east-1.api.aws554 # base_url: https://aws-external-anthropic.us-east-1.api.aws

516```555```

517 556

518플랫폼은 Amazon Bedrock과 다른 AWS 계정에서 실행되고 자체 서비스 이름 `aws-external-anthropic`에 대해 SigV4 요청에 서명하므로 Bedrock 범위 IAM 역할은 이를 인증하지 않습니다. `auth.api_key`의 API 키는 SigV4 자격증명도 설정되면 우선합니다. 빈 `auth` 블록은 AWS SDK의 기본 자격증명 체인을 사용합니다. [Amazon Bedrock](#amazon-bedrock) 업스트림이 사용하는 동일한 체인입니다.557플랫폼은 Amazon Bedrock과 다른 AWS 계정에서 실행되고 자체 서비스 이름 `aws-external-anthropic`에 대해 SigV4 요청에 서명하므로 Bedrock 범위 IAM 역할은 이를 인증하지 않습니다. `auth.api_key`의 API 키는 SigV4 자격 증명도 설정되면 우선합니다. 빈 `auth` 블록은 AWS SDK의 기본 자격 증명 체인을 사용합니다. [Amazon Bedrock](#amazon-bedrock) 업스트림이 사용하는 동일한 체인입니다.

519 558

520| 필드 | 필수 | 설명 |559| 필드 | 필수 | 설명 |

521| - | - | - |560| - | - | - |

522| `region` | 예 | AWS 지역입니다. 소문자, 숫자 및 하이픈입니다. 게이트웨이는 `https://aws-external-anthropic.<region>.api.aws`로 엔드포인트를 파생시킵니다. |561| `region` | 예 | AWS 지역입니다. 소문자, 숫자 및 하이픈입니다. 게이트웨이는 `https://aws-external-anthropic.<region>.api.aws`로 엔드포인트를 파생시킵니다. |

523| `workspace_id` | 예 | 모든 요청에서 헤더로 전송됩니다. 플랫폼이 필요합니다. |562| `workspace_id` | 예 | 모든 요청에서 헤더로 전송됩니다. 플랫폼이 필요합니다. |

524| `auth.api_key` | 아니오 | 플랫폼의 API 키입니다. `x-api-key`로 전송됩니다. 베어러 토큰이 아닙니다: 두 인증 모드는 API 키 또는 SigV4입니다. |563| `auth.api_key` | 아니오 | 플랫폼의 API 키입니다. `x-api-key`로 전송됩니다. 베어러 토큰이 아닙니다: 두 인증 모드는 API 키 또는 SigV4입니다. |

525| `auth.aws_access_key_id` / `auth.aws_secret_access_key` | 아니오 | 명시적 SigV4 자격증명입니다. 하나를 다른 것 없이 설정하면 부팅 시 실패합니다. `auth.aws_session_token`은 이들과 함께 수락됩니다. |564| `auth.aws_access_key_id` / `auth.aws_secret_access_key` | 아니오 | 명시적 SigV4 자격 증명입니다. 하나를 다른 것 없이 설정하면 부팅 시 실패합니다. `auth.aws_session_token`은 이들과 함께 수락됩니다. |

526| `base_url` | 아니오 | 파생된 엔드포인트를 재정의합니다. |565| `base_url` | 아니오 | 파생된 엔드포인트를 재정의합니다. |

527 566

528플랫폼이 첫 번째 당사자 모델 ID를 해석하므로 기본 제공 카탈로그는 [`models:`](#models) 블록 없이 이를 라우팅합니다. `models:` 목록을 큐레이션할 때 항목을 `anthropicAws:`로 첫 번째 당사자 ID로 키합니다.567플랫폼이 첫 번째 당사자 모델 ID를 해석하므로 기본 제공 카탈로그는 [`models:`](#models) 블록 없이 이를 라우팅합니다. `models:` 목록을 큐레이션할 때 항목을 `anthropicAws:`로 첫 번째 당사자 ID로 키합니다.

573 # api_key: ${FOUNDRY_API_KEY}612 # api_key: ${FOUNDRY_API_KEY}

574```613```

575 614

576`use_azure_ad: true`는 `DefaultAzureCredential`을 통해 해석합니다: AKS, ACI 또는 App Service의 Managed Identity, Azure CLI 또는 환경 자격증명. API 키는 작동하지만 프로젝트 전체이고 자동으로 회전하지 않습니다. Microsoft Foundry의 엔드포인트는 `resource:`에서 파생됩니다. Azure Government 같은 주권 클라우드에 대해 선택적 `base_url`을 설정하여 재정의합니다.615`use_azure_ad: true`는 `DefaultAzureCredential`을 통해 해석합니다: AKS, ACI 또는 App Service의 Managed Identity, Azure CLI 또는 환경 자격 증명. API 키는 작동하지만 프로젝트 전체이고 자동으로 회전하지 않습니다. Microsoft Foundry의 엔드포인트는 `resource:`에서 파생됩니다. Azure Government 같은 주권 클라우드에 대해 선택적 `base_url`을 설정하여 재정의합니다.

577 616

578| 설정 | 방법 |617| 설정 | 방법 |

579| - | - |618| - | - |

634 여러 업스트림673 여러 업스트림

635</h4>674</h4>

636 675

637동일한 공급자는 고유한 `name:`을 사용하여 두 번 이상 나타날 수 있습니다. 이는 다른 지역, 다른 자격증명 체인을 통한 다른 계정, 프로비저닝된 처리량 대 온디맨드 및 교차 공급자 장애 조치를 다룹니다.676동일한 공급자는 고유한 `name:`을 사용하여 두 번 이상 나타날 수 있습니다. 이는 다른 지역, 다른 자격 증명 체인을 통한 다른 계정, 프로비저닝된 처리량 대 온디맨드 및 교차 공급자 장애 조치를 다룹니다.

638 677

639게이트웨이는 순서대로 업스트림을 시도합니다. `5xx`, `429`, `401`, `403`, `404`, 시간 초과 및 누락된 엔드포인트(`501`)는 장애 조치합니다. 다른 `4xx`는 그렇지 않습니다.678게이트웨이는 순서대로 업스트림을 시도합니다. `5xx`, `429`, `401`, `403`, `404`, 시간 초과 및 누락된 엔드포인트(`501`)는 장애 조치합니다. 다른 `4xx`는 그렇지 않습니다.

640 679

689| 레버 | 방법 |728| 레버 | 방법 |

690| - | - |729| - | - |

691| 다른 지역 | 각각 자신의 `region:`을 가진 지역당 하나의 Amazon Bedrock 업스트림입니다. [`auto_include_builtin_models: true`](#models)를 사용하면 교차 지역 추론 프로필이 자동으로 라우팅됩니다. 지역 고정 배포의 경우 `models:` 블록을 사용합니다. |730| 다른 지역 | 각각 자신의 `region:`을 가진 지역당 하나의 Amazon Bedrock 업스트림입니다. [`auto_include_builtin_models: true`](#models)를 사용하면 교차 지역 추론 프로필이 자동으로 라우팅됩니다. 지역 고정 배포의 경우 `models:` 블록을 사용합니다. |

692| 다른 계정 | 계정당 하나의 Amazon Bedrock 업스트림입니다. 기본 체인(`auth: {}`)은 포드의 신원을 사용합니다. 두 번째 계정의 경우 [`assume_role`](#bedrock-in-another-aws-account)을 추가하여 단기 자격증명으로 도달하거나 `auth:`에서 명시적 자격증명 또는 베어러 토큰을 설정합니다. |731| 다른 계정 | 계정당 하나의 Amazon Bedrock 업스트림입니다. 기본 체인(`auth: {}`)은 포드의 신원을 사용합니다. 두 번째 계정의 경우 [`assume_role`](#bedrock-in-another-aws-account)을 추가하여 단기 자격 증명으로 도달하거나 `auth:`에서 명시적 자격 증명 또는 베어러 토큰을 설정합니다. |

695| 모델 범위 라우팅 | 기본 제공 Claude 모델이 아닌 사용자 정의 모델 `id`만 `upstream_model:` 맵에 없는 업스트림을 건너뜁니다. 게이트웨이는 순서대로 모든 업스트림에서 기본 제공 모델을 시도하고 맵에 항목이 없는 경우 공급자의 기본 ID를 사용하므로 기본 제공 모델의 경우 맵은 업스트림이 시도되는지 여부가 아니라 업스트림이 받는 ID를 변경합니다. ID를 거부하는 업스트림은 다른 업스트림 오류와 동일한 [장애 조치 규칙](#upstreams)을 따릅니다. |734| 모델 범위 라우팅 | 기본 제공 Claude 모델이 아닌 사용자 정의 모델 `id`만 `upstream_model:` 맵에 없는 업스트림을 건너뜁니다. `mantle` 업스트림은 해당 [`models` 필드](#amazon-bedrock-mantle-endpoint)에 나열된 모델에 대해서만 시도됩니다. 다른 모든 업스트림에서 게이트웨이는 기본 제공 모델을 순서대로 시도하고 맵에 항목이 없는 경우 공급자의 기본 ID를 사용하므로 기본 제공 모델의 경우 맵은 업스트림이 시도되는지 여부가 아니라 업스트림이 받는 ID를 변경합니다. ID를 거부하는 업스트림은 다른 업스트림 오류와 동일한 [장애 조치 규칙](#upstreams)을 따릅니다. |

696 735

697클라우드 공급자 간 또는 직접 Anthropic API로 장애 조치하면 요청을 제어하는 계약, 지역 및 기타 약관이 변경됩니다.736클라우드 공급자 간 또는 직접 Anthropic API로 장애 조치하면 요청을 제어하는 계약, 지역 및 기타 약관이 변경됩니다.

698 737

848 - match: {}887 - match: {}

849 cli:888 cli:

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

890 # /model의 Default 옵션이 각 정책의 목록 안에서 해석되도록

891 # 합니다. eng-contractors 정책은 enforceAvailableModels를 상속합니다.

892 enforceAvailableModels: true

851```893```

852 894

853관례적으로 마지막에 나열되는 `match: {}` 캐치올은 기본 계층으로 처리됩니다. 다른 모든 정책은 자신이 설정하지 않은 키를 캐치올에서 상속하므로, 역할별 항목은 조직 기본값과 다른 부분만 나열하면 됩니다. 병합 규칙은 키 유형에 따라 다릅니다:895관례적으로 마지막에 나열되는 `match: {}` 캐치올은 기본 계층으로 처리됩니다. 다른 모든 정책은 자신이 설정하지 않은 키를 캐치올에서 상속하므로, 역할별 항목은 조직 기본값과 다른 부분만 나열하면 됩니다. 병합 규칙은 키 유형에 따라 다릅니다:

856* **거부 목록 및 훅 배열**: `permissions.deny`, `permissions.ask`, `disabledMcpjsonServers`, `deniedMcpServers`, `blockedMarketplaces` 및 모든 `hooks` 이벤트 유형 배열입니다. 이들은 기본값과 정책의 합집합을 취하므로, 조직 전체의 거부 규칙이나 감사 훅이 역할별 재정의로 인해 실수로 누락되지 않습니다.898* **거부 목록 및 훅 배열**: `permissions.deny`, `permissions.ask`, `disabledMcpjsonServers`, `deniedMcpServers`, `blockedMarketplaces` 및 모든 `hooks` 이벤트 유형 배열입니다. 이들은 기본값과 정책의 합집합을 취하므로, 조직 전체의 거부 규칙이나 감사 훅이 역할별 재정의로 인해 실수로 누락되지 않습니다.

857* **레코드 유형 키**: `env`, `modelOverrides` 및 `skillOverrides`입니다. 이들은 얕게 병합되므로, 역할별 `env` 블록은 자신이 설정한 키를 재정의하고 나머지는 기본값에서 상속합니다.899* **레코드 유형 키**: `env`, `modelOverrides` 및 `skillOverrides`입니다. 이들은 얕게 병합되므로, 역할별 `env` 블록은 자신이 설정한 키를 재정의하고 나머지는 기본값에서 상속합니다.

858 900

859`availableModels`는 `/v1/messages`에서 서버 측으로도 강제되므로, 거부된 모델은 클라이언트가 무엇을 보내든 `400`을 반환합니다.901`availableModels`는 `/v1/messages`에서 서버 측으로도 강제되므로, 거부된 모델은 클라이언트가 무엇을 보내든 `400`을 반환합니다. 빈 목록은 모든 모델을 거부합니다. 이 확인은 개발자가 모델을 선택하기 전에 세션이 시작되는 모델에도 적용되므로, [정책이 허용하는 모델로 세션을 시작](#start-sessions-on-a-model-the-policy-allows)하도록 설정하세요.

860 902

861게이트웨이는 요청을 중계하기 전에 `model` 값 자체를 검증하므로, 잘못된 형식의 값은 업스트림에 도달하지 않습니다. 다음 두 가지 경우 `400`으로 요청을 거부합니다:903게이트웨이는 요청을 중계하기 전에 `model` 값 자체를 검증하므로, 잘못된 형식의 값은 업스트림에 도달하지 않습니다. 다음 두 가지 경우 `400`으로 요청을 거부합니다:

862 904

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

884</Note>926</Note>

885 927

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

929 정책이 허용하는 모델로 세션 시작

930</h4>

931

932`availableModels`에 Claude Code의 기본 모델이 빠져 있으면, 개발자가 `/model` 등으로 목록에 있는 모델을 선택할 때까지 세션은 `400` 응답을 받습니다. 게이트웨이 세션에서 기본 모델은 `opus` 별칭이 가리키는 Opus 모델이며, `availableModels`만으로는 이를 변경하지 않습니다.

933

934이를 해결하려면 같은 `cli` 블록에서 [`enforceAvailableModels: true`](/docs/ko/model-config#enforce-the-allowlist-for-the-default-model)를 설정한 다음, 목록에 어떤 종류의 항목이 있는지 확인합니다:

935

936* **`sonnet`과 같은 별칭 또는 `claude-sonnet-4-6`과 같은 기본 제공 ID**: 세션이 해당 모델 중 하나로 시작되며, `/model`의 Default 옵션도 그 모델로 해석됩니다

937* **목록에 별칭이나 기본 제공 ID가 없음**: 세션이 계속 기본 제공 기본 모델로 시작될 수 있으므로, 해당 정책의 `cli` 블록에서 [`model`](/docs/ko/model-config#control-the-model-users-run-on)도 목록에 있는 ID 중 하나로 설정합니다

938

939이 정책은 [`models`](#models)에서 정의한 사용자 정의 ID 하나를 나열하고, 세션을 해당 ID로 시작합니다:

940

941```yaml theme={null}

942managed:

943 policies:

944 - match: { groups: [restricted-projects] }

945 cli:

946 availableModels: [claude-opus-restricted]

947 enforceAvailableModels: true

948 model: claude-opus-restricted

949```

950

886<h4 id="matcher-values-that-stop-the-gateway-at-boot">951<h4 id="matcher-values-that-stop-the-gateway-at-boot">

887 게이트웨이 부팅을 중지시키는 matcher 값952 게이트웨이 부팅을 중지시키는 matcher 값

888</h4>953</h4>

920 cli:985 cli:

921 # 모델 액세스(/v1/messages에서도 서버 측으로 강제됨)986 # 모델 액세스(/v1/messages에서도 서버 측으로 강제됨)

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

988 enforceAvailableModels: true # Default가 목록 안에서 해석됨

923 989

924 # 권한 정책990 # 권한 정책

925 permissions:991 permissions:

1041 - match: { groups: [eng-contractors] }1107 - match: { groups: [eng-contractors] }

1042 cli:1108 cli:

1043 availableModels: [claude-sonnet-4-6]1109 availableModels: [claude-sonnet-4-6]

1110 enforceAvailableModels: true

1044 desktop:1111 desktop:

1045 isLocalDevMcpEnabled: false1112 isLocalDevMcpEnabled: false

1046 disableAutoUpdates: true1113 disableAutoUpdates: true

1434 # region: us-east-11501 # region: us-east-1

1435 # auth: {}1502 # auth: {}

1436 1503

1504 # - provider: mantle

1505 # region: us-east-1

1506 # models: [claude-opus-4-8, claude-opus-4-7, claude-haiku-4-5]

1507 # auth: {}

1508

1437 # - provider: anthropicAws1509 # - provider: anthropicAws

1438 # region: us-east-11510 # region: us-east-1

1439 # workspace_id: wrkspc_...1511 # workspace_id: wrkspc_...

1456 upstream_model:1528 upstream_model:

1457 anthropic: claude-opus-4-81529 anthropic: claude-opus-4-8

1458 # bedrock: us.anthropic.claude-opus-4-81530 # bedrock: us.anthropic.claude-opus-4-8

1531 # mantle: anthropic.claude-opus-4-8

1459 # anthropicAws: claude-opus-4-81532 # anthropicAws: claude-opus-4-8

1460 # vertex: claude-opus-4-81533 # vertex: claude-opus-4-8

1461 # foundry: <your-opus-deployment-name>1534 # foundry: <your-opus-deployment-name>

1473 - match: { groups: [contractors] }1546 - match: { groups: [contractors] }

1474 cli:1547 cli:

1475 availableModels: [claude-haiku-4-5]1548 availableModels: [claude-haiku-4-5]

1476 # 기본 선택기 옵션을 availableModels로 제한하여 계약자가

1477 # 기본값에 400을 얻지 않도록 합니다.

1478 enforceAvailableModels: true

1479 # allow는 이 도구를 자동 승인합니다. 나머지를 차단하지 않습니다.1549 # allow는 이 도구를 자동 승인합니다. 나머지를 차단하지 않습니다.

1480 # 도구를 제한하려면 거부 규칙을 추가합니다.1550 # 도구를 제한하려면 거부 규칙을 추가합니다.

1481 permissions: { allow: [Read, Grep] }1551 permissions: { allow: [Read, Grep] }

1482 - match: {}1552 - match: {}

1483 cli:1553 cli:

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

1555 # 기본 선택기 옵션을 기본 제공 기본값 대신 각 정책의 availableModels로

1556 # 제한하여 어떤 역할도 기본값에서 400을 받지 않도록 합니다.

1557 # 계약자 정책은 이 키를 상속합니다.

1558 enforceAvailableModels: true

1485 permissions:1559 permissions:

1486 allow: [Read, Grep, Bash, Edit]1560 allow: [Read, Grep, Bash, Edit]

1487 deny: ["WebFetch"]1561 deny: ["WebFetch"]

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

Details

431 431

432게이트웨이는 요청 헤더의 합계가 256 KiB를 초과하거나, [`limits.max_request_header_bytes`](/docs/ko/claude-apps-gateway-config#http-tuning)를 설정한 경우 그 값을 초과하면 `431`로 응답합니다. 이러한 요청에 대해서는 로그 줄이나 감사 이벤트를 기록하지 않습니다. v2.1.284 이전의 게이트웨이 버전은 16 KiB를 초과하면 `431`로 응답합니다.432게이트웨이는 요청 헤더의 합계가 256 KiB를 초과하거나, [`limits.max_request_header_bytes`](/docs/ko/claude-apps-gateway-config#http-tuning)를 설정한 경우 그 값을 초과하면 `431`로 응답합니다. 이러한 요청에 대해서는 로그 줄이나 감사 이벤트를 기록하지 않습니다. v2.1.284 이전의 게이트웨이 버전은 16 KiB를 초과하면 `431`로 응답합니다.

433 433

434변경할 사항은 게이트웨이의 버전과 구성에 따라 다릅니다:434다음 중 게이트웨이에 해당하는 첫 번째 항목부터 시작하세요:

435 435

436* **v2.1.284보다 이전의 게이트웨이**: 게이트웨이를 업그레이드하세요436* **v2.1.284보다 이전의 게이트웨이**: 게이트웨이를 업그레이드하세요

437* **`limits.max_request_header_bytes`가 설정됨**: 값을 높이거나 키를 제거하세요437* **`limits.max_request_header_bytes`가 설정됨**: 값을 높이거나 키를 제거하세요

438* **둘 다 해당하지 않거나, 이후에도 `431`이 계속됨**: IdP가 더 적은 그룹을 내보내도록 하세요. Okta, Microsoft Entra ID, Google Workspace가 그룹을 제공하는 방법은 [Identity provider setup](#identity-provider-setup)에서 다룹니다438* **둘 다 해당하지 않거나, 이후에도 `431`이 계속됨**: IdP가 더 적은 그룹을 내보내도록 하세요. Okta, Microsoft Entra ID, Google Workspace가 그룹을 제공하는 방법은 [Identity provider setup](#identity-provider-setup)에서 다룹니다

439 439

440groups 클레임을 줄일 때는 다음 설정에 지정한 그룹을 유지하세요. 이 설정들은 개발자의 액세스, 정책, 지출 한도를 결정합니다:

441

442* **[`oidc.allowed_groups`](/docs/ko/claude-apps-gateway-config#oidc)**: 로그인할 수 있는 사용자를 결정합니다

443* **[`admin.admin_groups`](/docs/ko/claude-apps-gateway-config#admin)**: 게이트웨이 세션으로 관리자 API를 호출할 수 있는 사용자를 결정합니다

444* **[`managed.policies`](/docs/ko/claude-apps-gateway-config#managed)의 `match.groups`**: 개발자에게 적용되는 정책을 결정합니다

445* **`rbac_group` [지출 한도](/docs/ko/claude-apps-gateway-spend-limits)**: 개발자에게 적용되는 그룹 한도를 결정합니다

446

440<h2 id="related">447<h2 id="related">

441 관련448 관련

442</h2>449</h2>

claude-code-on-the-web.md +103 −63

Details

12 12

13클라우드 세션은 사용자의 머신 대신 클라우드 인프라에서 실행되는 Claude Code 세션입니다. 기본적으로 Anthropic이 관리하는 인프라에서 실행되거나, 라우팅될 때 조직의 [자체 호스팅 환경](/docs/ko/self-hosted-environments)에서 실행됩니다. 세션은 노트북을 닫은 후에도 계속 실행되며, 모든 기기에서 확인하거나 조종할 수 있습니다.13클라우드 세션은 사용자의 머신 대신 클라우드 인프라에서 실행되는 Claude Code 세션입니다. 기본적으로 Anthropic이 관리하는 인프라에서 실행되거나, 라우팅될 때 조직의 [자체 호스팅 환경](/docs/ko/self-hosted-environments)에서 실행됩니다. 세션은 노트북을 닫은 후에도 계속 실행되며, 모든 기기에서 확인하거나 조종할 수 있습니다.

14 14

15클라우드 세션이 GitHub에서 코드를 클론하고 브랜치를 푸시할 수 있도록 하려면 [GitHub 연결 방법](#github-authentication-options) 중 하나로 GitHub를 연결하십시오. 저장소가 GitLab, Bitbucket 또는 기타 호스트에 있는 경우 [플랫폼 제한](#limitations)에서 지원되는 기능을 확인하십시오.

15다음 중 어느 곳에서나 클라우드 세션을 시작할 수 있습니다:17다음 중 어느 곳에서나 클라우드 세션을 시작할 수 있습니다:

16 18

17* **브라우저**: [claude.ai/code](https://claude.ai/code), 웹에서 Claude Code라고도 불림19* **브라우저**: [claude.ai/code](https://claude.ai/code), 웹에서 Claude Code라고도 불림

20* **터미널**: [`claude --cloud`](#from-terminal-to-cloud)22* **터미널**: [`claude --cloud`](#from-terminal-to-cloud)

21* **루틴**: [예약 및 트리거된 실행](/docs/ko/routines)은 각각 클라우드 세션으로 실행됨23* **루틴**: [예약 및 트리거된 실행](/docs/ko/routines)은 각각 클라우드 세션으로 실행됨

22 24

23한 본문의 작업에 대해 Claude가 많은 클라우드 세션을 시작하고 추적하도록 하려면 [프로젝트](/docs/ko/claude-projects)를 사용하십시오. 터미널, IDE 또는 **Local**이 선택된 데스크톱 앱의 세션은 사용자의 머신에서 실행됩니다. 휴대폰이나 브라우저에서 이러한 로컬 세션을 조종하려면 [원격 제어](/docs/ko/remote-control)를 사용하세요.25설정이 완료되면 이 페이지를 참고하여 터미널과 클라우드 간에 작업을 이동하고, 세션을 관리 및 공유하고, 풀 리퀘스트 자동 수정을 켜고, 문제를 해결하십시오.

~~25<Tip>~~

~~26 클라우드 세션을 처음 사용하시나요? [시작하기](/docs/ko/web-quickstart)에서 GitHub 계정을 연결하고 첫 번째 작업을 제출하세요.~~

~~27</Tip>~~

28 26

~~29이 페이지에서 다루는 내용:~~27<Note>

28 다음 사례는 다른 페이지에서 다룹니다:

30 29

~~31* [클라우드 환경](#cloud-environments): 세션이 실행되는 위치 및 구성 방법~~30 * **첫 번째 클라우드 세션 시작하기**: [클라우드 세션 시작하기](/docs/ko/web-quickstart)에서 GitHub를 연결하고 브라우저에서 작업을 진행하는 과정을 안내합니다

~~32* [GitHub 인증 옵션](#github-authentication-options): GitHub를 연결하는 두 가지 방법~~31 * **한 본문의 작업을 위한 여러 클라우드 세션**: [프로젝트](/docs/ko/claude-projects)를 사용하면 Claude가 세션을 대신 시작하고 추적합니다

~~33* [터미널과 클라우드 간에 작업 이동](#move-tasks-between-terminal-and-cloud): `--cloud` 및 `--teleport` 사용~~32 * **다른 기기에서 로컬 세션 조종하기**: 터미널, IDE 또는 **Local**이 선택된 데스크톱 앱의 세션은 사용자의 머신에서 실행되며, [Remote Control](/docs/ko/remote-control)을 사용하면 휴대폰이나 브라우저에서 이러한 세션에 접근할 수 있습니다

~~34* [세션 작업](#work-with-sessions): 권한 모드, 검토, 공유, 보관, 삭제~~33</Note>

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

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

~~37* [제한 사항](#limitations): 속도 제한 및 플랫폼 제한~~

38 34

39<h2 id="cloud-environments">35<h2 id="cloud-environments">

40 클라우드 환경36 클라우드 환경

41</h2>37</h2>

42 38

43모든 클라우드 세션은 [클라우드 환경](/docs/ko/cloud-environments)에서 실행되며, 이는 네트워크 액세스, 환경 변수 및 설정 스크립트를 제어하는 저장된 구성입니다. 아직 환경이 없으면 온보딩이 [**신뢰할 수 있는** 네트워크 액세스](/docs/ko/cloud-environments#access-levels)를 사용하여 **기본** 환경을 설정합니다. 이는 사용자를 위해 생성하거나 사용자가 생성하도록 요청합니다. 플랜에서 어느 것이 발생하는지 및 둘 이상의 환경이 있을 때 세션이 환경을 선택하는 방법은 [기본 환경](/docs/ko/cloud-environments#the-default-environment)을 참조하세요.39모든 클라우드 세션은 [클라우드 환경](/docs/ko/cloud-environments)에서 실행되며, 이는 네트워크 액세스, 환경 변수 및 설정 스크립트를 제어하는 저장된 구성입니다.

44 40

45동일한 환경이 클라우드 세션을 시작하는 모든 위치에 적용됩니다: 웹, 터미널, [Claude Tag](https://claude.com/docs/claude-tag/overview), [routines](/docs/ko/routines) 및 모바일 및 Desktop 앱. Claude Tag 채널 세션은 조직 수준 환경만 사용하며, [공유 환경](/docs/ko/cloud-environments#organization-shared-environments) 또는 [자체 호스팅 환경](/docs/ko/self-hosted-environments)입니다.41* **첫 번째 환경**: 아직 환경이 없으면 온보딩이 [**신뢰할 수 있는** 네트워크 액세스](/docs/ko/cloud-environments#access-levels)를 사용하여 **기본** 환경을 설정합니다. 이는 사용자를 위해 생성하거나 사용자가 생성하도록 요청합니다. 플랜에서 어느 것이 발생하는지는 [기본 환경](/docs/ko/cloud-environments#the-default-environment)을 참조하세요

46 42* **세션이 사용하는 환경**: 둘 이상의 환경이 있을 때 세션이 환경을 선택하는 방법은 [기본 환경](/docs/ko/cloud-environments#the-default-environment)을 참조하세요

47환경이 허용하는 것을 변경하고, 변수를 설정하거나, 설정 스크립트를 추가하려면 [클라우드 환경 구성](/docs/ko/cloud-environments)을 참조하세요. 구성 없이 세션에 포함되는 것은 [설치된 도구](/docs/ko/cloud-environments#installed-tools)를 참조하세요.43* **세션이 접근하거나 시작 시 실행할 수 있는 항목 변경**: [클라우드 환경 구성](/docs/ko/cloud-environments)을 참조하세요

44* **구성 없이 설치되어 있는 항목**: [설치된 도구](/docs/ko/cloud-environments#installed-tools)를 참조하세요

48 45

49<h2 id="github-authentication-options">46<h2 id="github-authentication-options">

50 GitHub 인증 옵션47 GitHub 인증 옵션

59 56

~~60저장소에 Claude GitHub App을 설치하면 해당 저장소의 풀 요청에 대해 [자동 수정](#auto-fix-pull-requests)도 활성화됩니다.~~57다음 기능은 저장소에 Claude GitHub App이 설치되어 있어야 합니다:

61 58

62[프로젝트](/docs/ko/claude-projects)의 스레드는 연결 방법에 관계없이 복제하는 각 저장소에 Claude GitHub App이 설치되어 있어야 합니다. [GitHub 액세스 설정](/docs/ko/claude-projects#set-up-github-access)을 참조하세요.59* **자동 수정**: 저장소에 Claude GitHub App을 설치하면 해당 저장소의 풀 리퀘스트에 대해 [자동 수정](#auto-fix-pull-requests)도 활성화됩니다

60* **프로젝트**: [프로젝트](/docs/ko/claude-projects)의 스레드는 연결 방법에 관계없이 복제하는 각 저장소에 Claude GitHub App이 설치되어 있어야 합니다. [GitHub 액세스 설정](/docs/ko/claude-projects#set-up-github-access)을 참조하세요

63 61

64Anthropic 호스팅 환경에서는 GitHub 자격 증명이 Anthropic 서버에 암호화되어 저장되며 세션의 VM에 절대 들어가지 않습니다. VM의 GitHub 작업은 [GitHub 프록시](/docs/ko/cloud-environments#github-proxy)를 통해 진행되며, 이는 서버 측에서 자격 증명을 첨부합니다.62Anthropic 호스팅 환경에서는 GitHub 자격 증명이 Anthropic 서버에 암호화되어 저장되며 세션의 VM에 절대 들어가지 않습니다. VM의 GitHub 작업은 [GitHub 프록시](/docs/ko/cloud-environments#github-proxy)를 통해 진행되며, 이는 서버 측에서 자격 증명을 첨부합니다.

65 63

66`/schedule`이 루틴을 생성하기 전에 저장소 액세스를 확인하는 방법은 [저장소 및 분기 권한](/docs/ko/routines#repositories-and-branch-permissions)을 참조하세요. `/web-setup` 안내(포함된 내용 및 제거 방법 포함)는 [터미널에서 연결](/docs/ko/web-quickstart#connect-from-your-terminal)을 참조하세요.64`/web-setup` 안내(`/web-setup`이 저장하는 내용 및 제거 방법 포함)는 [터미널에서 연결](/docs/ko/web-quickstart#connect-from-your-terminal)을 참조하세요.

68빠른 웹 설정은 구성원이 `/web-setup`으로 GitHub를 연결할 수 있게 하고, 브라우저 온보딩 중에 Claude GitHub App 설치 프롬프트를 건너뛰고, 환경 양식을 표시하는 대신 브라우저 온보딩이 [**기본** 환경](/docs/ko/cloud-environments#the-default-environment)을 생성하도록 하는 조직 설정입니다. Team 및 Enterprise 플랜에서는 기본적으로 꺼져 있으며, 이는 `/web-setup`을 숨깁니다. [Owner](/docs/ko/server-managed-settings#access-control)는 [**Admin settings > Claude Code**](https://claude.ai/admin-settings/claude-code)의 **Quick web setup** 토글로 켭니다.

69 65

70<Note>66<Note>

71 [Zero Data Retention](/docs/ko/zero-data-retention)이 활성화된 조직은 `/web-setup` 또는 기타 클라우드 세션 기능을 사용할 수 없습니다.67 [Zero Data Retention](/docs/ko/zero-data-retention)이 활성화된 조직은 `/web-setup` 또는 기타 클라우드 세션 기능을 사용할 수 없습니다.

72</Note>68</Note>

73 69

70<h3 id="quick-setup-for-team-and-enterprise">

71 Team 및 Enterprise용 빠른 설정

72</h3>

74빠른 설정은 구성원의 GitHub 및 환경 설정 단계를 줄여 주는 조직 설정입니다. Team 및 Enterprise 플랜에서는 기본적으로 꺼져 있습니다.

76이 설정을 켜면 구성원에게 다음과 같은 변화가 있습니다:

78* **`/web-setup`**: 구성원이 `/web-setup`으로 GitHub를 연결할 수 있습니다. 설정이 꺼져 있는 동안에는 이 명령이 숨겨집니다

79* **GitHub App 프롬프트**: 브라우저 온보딩에서 Claude GitHub App 설치 프롬프트를 건너뜁니다

80* **첫 번째 환경**: 브라우저 온보딩이 환경 양식을 표시하는 대신 구성원을 위해 [**기본** 환경](/docs/ko/cloud-environments#the-default-environment)을 생성합니다

82[Owner](/docs/ko/server-managed-settings#access-control)는 [**Organization settings > Claude Code**](https://claude.ai/admin-settings/claude-code)의 **Quick setup** 토글로 이 설정을 켭니다.

74<h2 id="move-tasks-between-terminal-and-cloud">84<h2 id="move-tasks-between-terminal-and-cloud">

75 터미널과 클라우드 간 작업 이동85 터미널과 클라우드 간 작업 이동

76</h2>86</h2>

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

79 89

80<Note>90<Note>

81 CLI에서 세션 핸드오프는 일방향입니다. `--teleport`를 사용하여 클라우드 세션을 터미널로 가져올 수 있지만, 기존 터미널 세션을 클라우드로 푸시할 수는 없습니다. 작업 설명과 함께 `--cloud` 플래그는 현재 저장소에 대한 새로운 클라우드 세션을 생성합니다. `-p`와 세션 ID 또는 claude.ai/code URL을 사용하면 대신 [해당 기존 세션에 메시지를 큐에 넣습니다](/docs/ko/claude-code-on-the-web#send-follow-ups-from-the-cli). [Desktop 앱](/docs/ko/desktop#continue-in-another-surface)은 로컬 세션을 클라우드로 보낼 수 있는 **Continue in** 메뉴를 제공합니다.91 CLI에서 세션 핸드오프는 일방향입니다. `--teleport`를 사용하여 클라우드 세션을 터미널로 가져올 수 있지만, 기존 터미널 세션을 클라우드로 푸시할 수는 없습니다. 작업 설명과 함께 `--cloud` 플래그는 현재 저장소에 대한 새로운 클라우드 세션을 생성합니다. `-p`와 세션 ID 또는 claude.ai/code URL을 사용하면 대신 [해당 기존 세션에 메시지를 큐에 넣습니다](/docs/ko/claude-code-on-the-web#send-follow-ups-from-the-cli). [Desktop 앱](/docs/ko/desktop#continue-in-another-surface)은 **Open in** 메뉴에서 Code 탭의 로컬 세션을 클라우드로 보낼 수 있습니다.

82</Note>92</Note>

83 93

84<h3 id="from-terminal-to-cloud">94<h3 id="from-terminal-to-cloud">

173 CLI에서 후속 메시지 보내기183 CLI에서 후속 메시지 보내기

174</h3>184</h3>

175 185

176클라우드 세션이 실행 중이면, 어디서 실행되든 `claude auth login`으로 로그인한 모든 머신의 `claude` CLI에서 후속 메시지를 보낼 수 있습니다. CLI는 Anthropic 계정 자격 증명으로 인증하고 로컬 세션 상태를 보내지 않으므로, 명령은 세션을 시작한 머신에서 실행할 필요가 없으며, PowerShell을 포함한 모든 셸에서 동일합니다.186클라우드 세션이 실행 중이면, 어디서 실행되든 `claude auth login`으로 로그인한 모든 머신의 `claude` CLI에서 후속 메시지를 보낼 수 있습니다. CLI는 Anthropic 계정 자격 증명으로 인증하고 로컬 세션 상태를 보내지 않으므로, 명령은 세션을 시작한 머신에서 실행할 필요가 없습니다.

177 187

178명령은 하나의 메시지를 게시하고 종료합니다:188명령은 하나의 메시지를 게시하고 종료합니다:

179 189

189 `--cloud`는 Anthropic 계정이 필요합니다. Claude Code가 Amazon Bedrock, Google Cloud의 Agent Platform 또는 다른 타사 제공자로 구성된 경우 사용할 수 없습니다. `ANTHROPIC_BASE_URL`을 통해서만 구성된 [LLM gateway](/docs/ko/llm-gateway)는 이 확인에서 타사 제공자로 간주되지 않지만, 여전히 `claude auth login`으로 로그인해야 합니다. 조직의 `allow_remote_sessions` 정책도 활성화되어야 합니다. 소유자는 claude.ai/admin-settings/claude-code의 Claude Code 관리 설정에서 이를 켤 수 있습니다.199 `--cloud`는 Anthropic 계정이 필요합니다. Claude Code가 Amazon Bedrock, Google Cloud의 Agent Platform 또는 다른 타사 제공자로 구성된 경우 사용할 수 없습니다. `ANTHROPIC_BASE_URL`을 통해서만 구성된 [LLM gateway](/docs/ko/llm-gateway)는 이 확인에서 타사 제공자로 간주되지 않지만, 여전히 `claude auth login`으로 로그인해야 합니다. 조직의 `allow_remote_sessions` 정책도 활성화되어야 합니다. 소유자는 claude.ai/admin-settings/claude-code의 Claude Code 관리 설정에서 이를 켤 수 있습니다.

190</Note>200</Note>

191 201

192<h4 id="output-and-errors">202<h4 id="output">

193 출력 및 오류203 출력

194</h4>204</h4>

195 205

196성공하면 명령은 세션 ID와 세션을 보기 위한 링크를 인쇄합니다:206성공하면 명령은 세션 ID와 세션을 보기 위한 링크를 인쇄합니다:

203 213

204`--output-format json`을 전달하여 머신이 읽을 수 있는 결과를 얻습니다: 성공 시 `{ok, session_id, url}`, 또는 세션이 누락되거나 보관된 경우와 같이 전송이 실패할 때 `{ok: false, session_id, error}`입니다. 지원되지 않는 제공자 또는 비활성화된 조직 정책과 같은 구성 오류는 JSON 없이 stderr에 인쇄됩니다. `--output-format stream-json`은 `--cloud <session-id>`에서 지원되지 않습니다.214`--output-format json`을 전달하여 머신이 읽을 수 있는 결과를 얻습니다: 성공 시 `{ok, session_id, url}`, 또는 세션이 누락되거나 보관된 경우와 같이 전송이 실패할 때 `{ok: false, session_id, error}`입니다. 지원되지 않는 제공자 또는 비활성화된 조직 정책과 같은 구성 오류는 JSON 없이 stderr에 인쇄됩니다. `--output-format stream-json`은 `--cloud <session-id>`에서 지원되지 않습니다.

205 215

206CLI는 오류 앞에 `Error: `를 붙입니다. 실패한 전달은 `failed to send message to cloud session <id>: <reason>`으로 래핑됩니다.216전송이 실패하면 [클라우드 세션으로 전송할 때의 오류](#errors-when-sending-to-a-cloud-session)를 참조하십시오.

~~207~~

208| 메시지 | 의미 |

209| - | - |

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

211| `Cloud sessions are disabled by your organization's policy. Contact your organization admin to enable them.` | `allow_remote_sessions` 조직 정책이 꺼져 있습니다. |

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

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

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

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

216 217

217<h3 id="from-cloud-to-terminal">218<h3 id="from-cloud-to-terminal">

218 클라우드에서 터미널로219 클라우드에서 터미널로

239| 요구 사항 | 세부 사항 |240| 요구 사항 | 세부 사항 |

240| - | - |241| - | - |

241| 깨끗한 git 상태 | 작업 디렉토리에 커밋되지 않은 변경 사항이 없어야 합니다. Teleport는 필요한 경우 변경 사항을 stash하라는 메시지를 표시합니다. |242| 깨끗한 git 상태 | 작업 디렉토리에 커밋되지 않은 변경 사항이 없어야 합니다. Teleport는 필요한 경우 변경 사항을 stash하라는 메시지를 표시합니다. |

242| 올바른 저장소 | 포크가 아닌 동일한 저장소의 체크아웃에서 `--teleport`를 실행해야 합니다. 다른 저장소의 체크아웃에서 실행하면 Claude Code는 세션의 저장소와 체크아웃의 이름을 모두 지정하는 오류를 표시합니다. v2.1.219 이전에는 오류가 체크아웃의 저장소 이름을 지정하지 않았습니다. Claude Code가 원격을 호스트 이름으로 파싱할 수 없으면(예: `git@work:owner/repo.git`과 같은 SSH 호스트 별칭), 확인을 요청하고 원격의 소유자 및 저장소 이름이 세션의 저장소와 일치할 때 체크아웃을 수락합니다. |243| 올바른 저장소 | 포크가 아닌 동일한 저장소의 체크아웃에서 `--teleport`를 실행해야 합니다. 다른 저장소의 체크아웃에서 실행하면 Claude Code는 세션의 저장소와 체크아웃의 저장소 이름을 모두 표시하는 오류를 보여줍니다. Claude Code가 원격을 호스트 이름으로 파싱할 수 없으면(예: `git@work:owner/repo.git`과 같은 SSH 호스트 별칭), 확인을 요청하고 원격의 소유자 및 저장소 이름이 세션의 저장소와 일치할 때 체크아웃을 수락합니다. |

243| 사용 가능한 브랜치 | 클라우드 세션의 브랜치를 원격으로 푸시해야 합니다. Teleport는 자동으로 가져와 체크아웃합니다. |244| 사용 가능한 브랜치 | 클라우드 세션의 브랜치를 원격으로 푸시해야 합니다. Teleport는 자동으로 가져와 체크아웃합니다. |

244| 동일한 계정 | 클라우드 세션에서 사용된 동일한 claude.ai 계정으로 인증해야 합니다. |245| 동일한 계정 | 클라우드 세션에서 사용된 동일한 claude.ai 계정으로 인증해야 합니다. |

245 246

249 `--teleport`를 사용할 수 없음250 `--teleport`를 사용할 수 없음

250</h4>251</h4>

251 252

252Teleport는 claude.ai 구독 인증이 필요합니다. API 키를 통해 인증된 경우 `/login`을 실행하여 대신 claude.ai 계정으로 로그인합니다. 오류가 제공자의 이름을 지정하면 클라우드 세션을 타사 제공자를 통해 사용할 수 없습니다. [오류 테이블](#output-and-errors)을 참조하십시오. 이미 claude.ai를 통해 로그인했는데 `--teleport`를 여전히 사용할 수 없으면, 조직이 클라우드 세션을 비활성화했을 수 있습니다.253Teleport는 claude.ai 구독 인증이 필요합니다. 해당하는 경우를 찾으십시오:

254

255* **API 키를 통해 인증된 경우**: `/login`을 실행하여 대신 claude.ai 계정으로 로그인합니다

256* **오류가 제공자의 이름을 표시하는 경우**: 클라우드 세션은 타사 제공자를 통해 사용할 수 없습니다. [오류 테이블](#errors-when-sending-to-a-cloud-session)을 참조하십시오

257* **이미 claude.ai를 통해 로그인한 경우**: 조직이 클라우드 세션을 비활성화했을 수 있습니다

253 258

254<h2 id="work-with-sessions">259<h2 id="work-with-sessions">

255 세션 작업260 세션 작업

257 262

258세션은 claude.ai/code의 사이드바에 나타납니다. 여기서 변경 사항을 검토하고, 팀원과 공유하고, 완료된 작업을 보관하거나, 세션을 영구적으로 삭제할 수 있습니다.263세션은 claude.ai/code의 사이드바에 나타납니다. 여기서 변경 사항을 검토하고, 팀원과 공유하고, 완료된 작업을 보관하거나, 세션을 영구적으로 삭제할 수 있습니다.

259 264

260<h3 id="take-back-a-queued-message">265<h3 id="permission-modes-in-cloud-sessions">

261 대기 중인 메시지 되돌리기266 클라우드 세션의 권한 모드

262</h3>267</h3>

263 268

264Claude가 작업 중일 때 메시지를 보내면 Claude가 읽을 때까지 메시지가 대기합니다. 대기 중인 메시지를 되돌리려면 메시지의 ✕를 클릭하세요. 텍스트가 메시지 상자로 돌아가므로 편집하거나 다른 내용을 보낼 수 있습니다.269클라우드 세션의 [권한 모드](/docs/ko/permission-modes)는 작업을 생성할 때와 세션이 실행되는 동안 모두 [모드 드롭다운](/docs/ko/permission-modes#switch-permission-modes)에서 선택합니다.

265 270

266Claude가 이미 메시지를 읽었다면 메시지는 대화에 남아 있습니다.271다음 중 하나를 수행하면 Claude Code는 세션이 있던 권한 모드에서 세션을 재개합니다:

272

273* Anthropic 호스팅 [환경이 만료된](#environment-expired) 세션을 다시 열기

274* 자체 호스팅 runner가 [유휴 상태일 때 해제한](/docs/ko/self-hosted-environments-reference#runner-cli-flags) 세션에 메시지 보내기

275

276<h3 id="review-changes">

277 변경 사항 검토

278</h3>

279

280각 세션은 추가 및 제거된 줄을 표시하는 diff 표시기를 표시합니다(예: `+42 -18`). 이를 선택하여 diff 보기를 열고, 특정 줄에 인라인 주석을 남기고, 다음 메시지로 Claude에 보내세요.

281

282diff 보기는 기본적으로 세션의 변경 사항을 해당 기본 브랜치와 비교합니다. 저장소의 다른 브랜치와 비교하려면 **Compare against**를 선택하고 브랜치를 하나 고르세요.

283

284Claude Code는 이러한 diff를 raw git blob 콘텐츠에서 계산하므로 저장소에 구성된 diff 드라이버 및 `textconv` 필터는 적용되지 않습니다.

285

286다음 단계는 다른 곳에서 다룹니다:

287

288* **PR 생성을 포함한 전체 안내**: [검토 및 반복](/docs/ko/web-quickstart#review-and-iterate)을 참조하세요

289* **Claude가 PR을 모니터링하여 CI 실패 및 검토 주석에 자동으로 대응하도록 하기**: [풀 리퀘스트 자동 수정](#auto-fix-pull-requests)을 참조하세요

267 290

268<h3 id="manage-context">291<h3 id="manage-context">

269 컨텍스트 관리292 컨텍스트 관리

291 314

292[Agent teams](/docs/ko/agent-teams)는 기본적으로 꺼져 있지만 [환경 변수](/docs/ko/cloud-environments#set-environment-variables)에 `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1`을 추가하여 활성화할 수 있습니다.315[Agent teams](/docs/ko/agent-teams)는 기본적으로 꺼져 있지만 [환경 변수](/docs/ko/cloud-environments#set-environment-variables)에 `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1`을 추가하여 활성화할 수 있습니다.

293 316

294<h3 id="permission-modes-in-cloud-sessions">317<h3 id="take-back-a-queued-message">

295 클라우드 세션의 권한 모드318 대기 중인 메시지 되돌리기

296</h3>

~~297~~

298[권한 모드](/docs/ko/permission-modes)는 [모드 드롭다운](/docs/ko/permission-modes#switch-permission-modes)에서 클라우드 세션을 생성할 때와 세션이 실행되는 동안 선택합니다. Anthropic 호스팅 [환경이 만료된](#environment-expired) 세션을 다시 열거나 자체 호스팅 runner가 [유휴 상태일 때 해제한](/docs/ko/self-hosted-environments-reference#runner-cli-flags) 세션에 메시지를 보내면 Claude Code는 세션이 있던 권한 모드에서 세션을 재개합니다.

~~299~~

300<h3 id="review-changes">

301 변경 사항 검토

302</h3>319</h3>

303 320

304각 세션은 추가 및 제거된 줄을 표시하는 diff 표시기를 표시합니다(예: `+42 -18`). 이를 선택하여 diff 보기를 열고, 특정 줄에 인라인 주석을 남기고, 다음 메시지로 Claude에 보내세요.321Claude가 작업 중일 때 메시지를 보내면 Claude가 읽을 때까지 메시지가 대기합니다. 대기 중인 메시지를 되돌리려면 메시지의 ✕를 클릭하세요. 텍스트가 메시지 상자로 돌아가므로 편집하거나 다른 내용을 보낼 수 있습니다.

~~305~~

306diff 보기는 따로 선택하지 않으면 세션의 변경 사항을 해당 기본 분기와 비교합니다. 저장소의 다른 분기와 비교하려면 **Compare against**를 선택하고 분기를 하나 고르세요.

~~307~~

308Claude Code는 이러한 diffs(Claude가 편집할 때 표시되는 파일별 diffs 포함)를 raw git blob 콘텐츠에서 계산하므로 저장소에 구성된 diff 드라이버 및 `textconv` 필터는 적용되지 않습니다. 세션의 자체 체크아웃 중 하나가 아닌 저장소의 파일(예: 세션 중에 워크스페이스 내에 복제된 파일)의 경우 파일별 diff는 git 비교가 아니라 Claude의 편집 자체를 표시합니다.

309 322

310PR 생성을 포함한 전체 안내는 [검토 및 반복](/docs/ko/web-quickstart#review-and-iterate)을 참조하세요. Claude가 PR을 모니터링하여 CI 실패 및 검토 주석에 자동으로 응답하도록 하려면 [Pull request 자동 수정](#auto-fix-pull-requests)을 참조하세요.323Claude가 이미 메시지를 읽었다면 메시지는 대화에 남아 있습니다.

311 324

312<h3 id="share-sessions">325<h3 id="share-sessions">

313 세션 공유326 세션 공유

319 Enterprise 또는 Team 계정에서 공유332 Enterprise 또는 Team 계정에서 공유

320</h4>333</h4>

321 334

322Enterprise 및 Team 계정의 경우 두 가지 가시성 옵션은 **Private** 및 **Team**입니다. Team 가시성은 claude.ai 조직의 다른 구성원에게 세션을 표시합니다. [Claude in Slack](/docs/ko/slack) 세션은 자동으로 Team 가시성으로 공유됩니다.335Enterprise 및 Team 계정의 공유는 다음과 같이 작동합니다:

323 336

324저장소 액세스 확인은 기본적으로 수신자의 계정에 연결된 GitHub 계정을 기반으로 활성화됩니다. 계정의 표시 이름은 액세스 권한이 있는 모든 수신자에게 표시됩니다.337* **가시성 옵션**: **Private** 및 **Team**. Team 가시성은 claude.ai 조직의 다른 구성원에게 세션을 표시합니다

338* **저장소 액세스**: 수신자의 계정에 연결된 GitHub 계정을 기반으로 확인이 기본적으로 활성화됩니다

339* **사용자 이름**: 계정의 표시 이름은 액세스 권한이 있는 모든 수신자에게 표시됩니다

340* **Slack 세션**: [Claude in Slack](/docs/ko/slack) 세션은 자동으로 Team 가시성으로 공유됩니다

325 341

326<h4 id="share-from-a-max-or-pro-account">342<h4 id="share-from-a-max-or-pro-account">

327 Max 또는 Pro 계정에서 공유343 Max 또는 Pro 계정에서 공유

328</h4>344</h4>

329 345

330Max 및 Pro 계정의 경우 두 가지 가시성 옵션은 **Private** 및 **Public**입니다. Public 가시성은 claude.ai에 로그인한 모든 사용자에게 세션을 표시합니다.346Max 및 Pro 계정의 공유는 다음과 같이 작동합니다:

331 347

332공유하기 전에 민감한 내용이 있는지 세션을 확인하세요. 세션에는 개인 GitHub 저장소의 코드 및 자격 증명이 포함될 수 있습니다. 저장소 액세스 확인은 기본적으로 활성화되지 않습니다.348* **가시성 옵션**: **Private** 및 **Public**. Public 가시성은 claude.ai에 로그인한 모든 사용자에게 세션을 표시합니다

349* **저장소 액세스**: 확인은 기본적으로 활성화되지 않습니다

350* **민감한 내용**: 공유하기 전에 세션을 확인하세요. 세션에는 개인 GitHub 저장소의 코드 및 자격 증명이 포함될 수 있습니다

333 351

334저장소 액세스를 요구하거나 공유 세션에서 이름을 숨기려면 [**Settings > Claude Code > Sharing settings**](https://claude.ai/settings/claude-code)로 이동하세요.352저장소 액세스를 요구하거나 공유 세션에서 이름을 숨기려면 [**Settings > Claude Code > Sharing settings**](https://claude.ai/settings/claude-code)로 이동하세요.

335 353

421 조직 UUID를 가져올 수 없음439 조직 UUID를 가져올 수 없음

422</h3>440</h3>

423 441

424`claude --cloud` 및 `claude --teleport`는 claude.ai 계정으로 로그인해야 합니다. API 키로 인증하거나 저장된 계정 세부 정보가 오래된 경우 이러한 명령은 `Unable to get organization UUID` 또는 API 키 인증이 충분하지 않다는 메시지로 실패합니다. API 키 인증 또는 오래된 계정 세부 정보를 사용하면 세션 ID 없이 `claude --teleport`를 실행하면 세션 선택기에 `Error loading Claude Code sessions`이 표시되고 동일한 수정이 적용됩니다.442`claude --cloud` 및 `claude --teleport`는 claude.ai 계정으로 로그인해야 합니다. API 키로 인증하거나 저장된 계정 세부 정보가 오래된 경우 다음 중 하나가 표시됩니다.

443

444* `Unable to get organization UUID`

445* API 키 인증이 충분하지 않다는 메시지

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

425 447

426`/login`을 실행하여 claude.ai 계정으로 로그인한 다음 명령을 다시 시도하세요. 오류가 제공자의 이름을 지정하면 [오류 표](#output-and-errors)를 참조하세요: 클라우드 세션을 타사 제공자를 통해 사용할 수 없습니다.448`/login`을 실행하여 claude.ai 계정으로 로그인한 다음 명령을 다시 시도하세요. 오류가 제공자의 이름을 지정하면 [오류 표](#errors-when-sending-to-a-cloud-session)를 참조하세요: 클라우드 세션을 타사 제공자를 통해 사용할 수 없습니다.

427 449

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

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

435* 세션을 소유한 동일한 계정으로 로그인했는지 확인하세요457* 세션을 소유한 동일한 계정으로 로그인했는지 확인하세요

436* `Remote Control may not be available for this organization`이 표시되면 Owner가 조직에 대해 클라우드 세션을 활성화하지 않았습니다458* `Remote Control may not be available for this organization`이 표시되면 Owner가 조직에 대해 클라우드 세션을 활성화하지 않았습니다

437 459

460<h3 id="errors-when-sending-to-a-cloud-session">

461 클라우드 세션으로 전송 시 오류

462</h3>

463

464이러한 오류는 `-p` 사용 여부와 관계없이 [`--cloud <session-id>`](#send-follow-ups-from-the-cli)와 함께 `claude`를 실행할 때 발생합니다. CLI는 오류 앞에 `Error: `를 붙입니다. 전달에 실패하면 `failed to send message to cloud session <id>: <reason>` 형식으로 감싸서 표시됩니다.

465

466| 메시지 | 의미 |

467| - | - |

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

469| `Cloud sessions are disabled by your organization's policy. Contact your organization admin to enable them.` | `allow_remote_sessions` 조직 정책이 꺼져 있습니다. |

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

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

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

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

474

438<h3 id="environment-expired">475<h3 id="environment-expired">

439 환경 만료476 환경 만료

440</h3>477</h3>

441 478

442클라우드 세션은 비활성 기간 후 중지되고 세션의 VM이 회수됩니다. 세션은 [MCP connector](/docs/ko/cloud-environments#network-access) 도구 호출을 승인하거나 MCP 서버에 로그인하기를 기다리는 동안 비활성으로 간주되며 해당 대기 중에 만료될 수 있습니다.479클라우드 세션은 비활성 기간 후 중지되고 세션의 VM이 회수됩니다. 세션은 [MCP connector](/docs/ko/cloud-environments#network-access) 도구 호출을 승인하거나 MCP 서버에 로그인하기를 기다리는 동안 비활성으로 간주되며 해당 대기 중에 만료될 수 있습니다.

443 480

444[claude.ai/code](https://claude.ai/code)에서 세션을 다시 열어 대화 기록이 복원된 새로운 VM을 프로비저닝하세요. VM이 회수되었을 때 여전히 실행 중이던 백그라운드 작업(예: subagents 및 셸 명령)은 복원되지 않습니다.481[claude.ai/code](https://claude.ai/code)에서 세션을 다시 열어 새로운 VM을 프로비저닝하세요.

482

483* **복원됨**: 대화 기록

484* **복원되지 않음**: VM이 회수되었을 때 여전히 실행 중이던 백그라운드 작업(예: 서브에이전트 및 셸 명령)

445 485

446<h2 id="limitations">486<h2 id="limitations">

447 제한 사항487 제한 사항

claude-directory.md +4 −4

Details

429 badge: 'local',429 badge: 'local',

430 oneLiner: 'App state and UI preferences',430 oneLiner: 'App state and UI preferences',

431 when: <>Read at session start for your preferences and MCP servers. Claude Code writes back to it when you change settings in <C>/config</C> or approve trust prompts</>,431 when: <>Read at session start for your preferences and MCP servers. Claude Code writes back to it when you change settings in <C>/config</C> or approve trust prompts</>,

432 description: <>Holds state that does not belong in settings.json: theme, OAuth session, per-project trust decisions, your personal MCP servers, and UI toggles. Mostly managed through <C>/config</C> rather than editing directly.</>,432 description: <>Holds state that does not belong in settings.json: OAuth session, per-project trust decisions, your personal MCP servers, and UI toggles. Mostly managed through <C>/config</C> rather than editing directly.</>,

433 tips: [<>IDE toggles like <C>autoConnectIde</C> and <C>externalEditorContext</C> live here, not in settings.json</>, <>The <C>projects</C> key tracks per-project state like trust-dialog acceptance and last-session metrics. Permission rules you approve in-session go to <C>.claude/settings.local.json</C> instead</>, <>MCP servers here are yours only: user scope applies across all projects, local scope is per-project but not committed. Team-shared servers go in <C>.mcp.json</C> at the project root instead</>],433 tips: [<>IDE toggles like <C>autoConnectIde</C> and <C>externalEditorContext</C> live here, not in settings.json</>, <>The <C>projects</C> key tracks per-project state like trust-dialog acceptance and last-session metrics. Permission rules you approve in-session go to <C>.claude/settings.local.json</C> instead</>, <>MCP servers here are yours only: user scope applies across all projects, local scope is per-project but not committed. Team-shared servers go in <C>.mcp.json</C> at the project root instead</>],

434 example: `{434 example: `{

435 "autoConnectIde": true,435 "autoConnectIde": true,

497 oneLiner: 'Custom keyboard shortcuts',497 oneLiner: 'Custom keyboard shortcuts',

498 when: 'Read at session start and hot-reloaded when you edit the file',498 when: 'Read at session start and hot-reloaded when you edit the file',

499 description: <>Rebind keyboard shortcuts in the interactive CLI. Run <C>/keybindings</C> to create or open this file with a schema reference. Ctrl+C, Ctrl+D, Ctrl+M, and Caps Lock are reserved and cannot be rebound.</>,499 description: <>Rebind keyboard shortcuts in the interactive CLI. Run <C>/keybindings</C> to create or open this file with a schema reference. Ctrl+C, Ctrl+D, Ctrl+M, and Caps Lock are reserved and cannot be rebound.</>,

500 exampleIntro: <>This example binds <C>Ctrl+E</C> to open your external editor and unbinds <C>Ctrl+U</C> by setting it to <C>null</C>. The <C>context</C> field scopes bindings to a specific part of the CLI, here the main chat input.</>,500 exampleIntro: <>This example binds <C>Ctrl+E</C> to open your external editor and unbinds <C>Ctrl+S</C> by setting it to <C>null</C>. The <C>context</C> field scopes bindings to a specific part of the CLI, here the main chat input.</>,

501 example: `{501 example: `{

502 "$schema": "https://www.schemastore.org/claude-code-keybindings.json",502 "$schema": "https://www.schemastore.org/claude-code-keybindings.json",

503 "$docs": "https://code.claude.com/docs/en/keybindings",503 "$docs": "https://code.claude.com/docs/en/keybindings",

506 "context": "Chat",506 "context": "Chat",

507 "bindings": {507 "bindings": {

508 "ctrl+e": "chat:externalEditor",508 "ctrl+e": "chat:externalEditor",

509 "ctrl+u": null509 "ctrl+s": null

510 }510 }

511 }511 }

512 ]512 ]

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

1457| `AGENTS.md` | 프로젝트 루트, `.claude/`, 또는 모든 디렉터리 | AI 코딩 에이전트를 위해 작성하는 프로젝트 지침입니다. Claude Code는 [이를 로드](/docs/ko/memory#agents-md)할 수 있으며, `CLAUDE.md`와 함께 로드할 수도 있습니다. |1457| `AGENTS.md` | 프로젝트 루트, `.claude/`, 또는 모든 디렉터리 | AI 코딩 에이전트를 위해 작성하는 프로젝트 지침입니다. Claude Code는 [이를 로드](/docs/ko/memory#agents-md)할 수 있으며, `CLAUDE.md`와 함께 로드할 수도 있습니다. |

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

1459 1459

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

1461 1461

cloud-environments.md +1 −1

Details

26 26

27* **`/web-setup`과 같은 CLI 흐름**: **Default**를 생성합니다27* **`/web-setup`과 같은 CLI 흐름**: **Default**를 생성합니다

28* **Pro 및 Max의 웹 온보딩**: **Default**를 생성합니다28* **Pro 및 Max의 웹 온보딩**: **Default**를 생성합니다

29* **Team 및 Enterprise의 웹 온보딩**: Owner가 [빠른 웹 설정](/docs/ko/claude-code-on-the-web#github-authentication-options)을 켜지 않은 한 **첫 번째 클라우드 환경 생성** 양식을 표시합니다. 양식의 기본값을 유지하고 **생성 및 완료**를 클릭하여 동일한 **Default** 환경을 얻습니다29* **Team 및 Enterprise의 웹 온보딩**: Owner가 [빠른 설정](/docs/ko/claude-code-on-the-web#quick-setup-for-team-and-enterprise)을 켜지 않은 한 **첫 번째 클라우드 환경 생성** 양식을 표시합니다. 양식의 기본값을 유지하고 **생성 및 완료**를 클릭하여 동일한 **Default** 환경을 얻습니다

30 30

31**Default**는 자체 구성을 수행하지 않습니다:31**Default**는 자체 구성을 수행하지 않습니다:

32 32

costs.md +2 −2

Details

111| 역할 | `/usage-credits`가 수행하는 작업 |111| 역할 | `/usage-credits`가 수행하는 작업 |

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

113| Pro 또는 Max 구독자 | 브라우저에서 claude.ai의 [**Settings > Usage**](https://claude.ai/settings/usage)를 엽니다. **Usage credits** 섹션에서 사용량 크레딧을 켜거나 끌 수 있으며 크레딧 잔액, 이번 달의 지출 및 월간 지출 한도를 확인할 수 있습니다 |113| Pro 또는 Max 구독자 | 브라우저에서 claude.ai의 [**Settings > Usage**](https://claude.ai/settings/usage)를 엽니다. **Usage credits** 섹션에서 사용량 크레딧을 켜거나 끌 수 있으며 크레딧 잔액, 이번 달의 지출 및 월간 지출 한도를 확인할 수 있습니다 |

114| 청구 액세스 권한이 있는 Team 또는 Enterprise 구성원 | 브라우저에서 조직의 사용량 설정인 [**Admin settings > Usage**](https://claude.ai/admin-settings/usage)를 엽니다 |114| 청구 액세스 권한이 있는 Team 또는 Enterprise 구성원 | 브라우저에서 조직의 사용량 설정인 [**Organization settings > Usage**](https://claude.ai/admin-settings/usage)를 엽니다 |

115| 청구 액세스 권한이 없는 Team 또는 Enterprise 구성원 | 확인을 요청한 후 조직의 관리자에게 요청을 보냅니다. v2.1.211 이전에는 Claude Code가 확인 단계 없이 요청을 보냈습니다 |115| 청구 액세스 권한이 없는 Team 또는 Enterprise 구성원 | 확인을 요청한 후 조직의 관리자에게 요청을 보냅니다. v2.1.211 이전에는 Claude Code가 확인 단계 없이 요청을 보냈습니다 |

116 116

117청구 액세스 권한이 없는 Team 및 Enterprise 구성원의 경우, 확인은 대화형 세션에서만 나타납니다: `-p` 플래그가 있는 비대화형 모드 및 [Remote Control](/docs/ko/remote-control)에서 명령은 요청을 보내지 않으며 대화형 세션에서 실행하도록 지시합니다.117청구 액세스 권한이 없는 Team 및 Enterprise 구성원의 경우, 확인은 대화형 세션에서만 나타납니다: `-p` 플래그가 있는 비대화형 모드 및 [Remote Control](/docs/ko/remote-control)에서 명령은 요청을 보내지 않으며 대화형 세션에서 실행하도록 지시합니다.

229* **"세션 한도에 도달했습니다" 또는 "주간 한도에 도달했습니다"**: 구독 플랜의 시트 기반 사용 윈도우이며, 모든 모델에서 공유되므로 개발자는 `/model`로 모델을 전환하여 액세스를 복원할 수 없습니다. 메시지는 윈도우가 재설정될 때를 표시합니다. 모델별 "Opus 한도에 도달했습니다" 또는 "Sonnet 한도에 도달했습니다" 메시지 후에는 `/model`로 해당 제품군 외의 모델로 전환하면 개발자가 계속 작업할 수 있습니다. [사용 한도 오류](/docs/ko/errors#youve-hit-your-session-limit)를 참조하십시오. 개발자가 그 동안 할 수 있는 작업:229* **"세션 한도에 도달했습니다" 또는 "주간 한도에 도달했습니다"**: 구독 플랜의 시트 기반 사용 윈도우이며, 모든 모델에서 공유되므로 개발자는 `/model`로 모델을 전환하여 액세스를 복원할 수 없습니다. 메시지는 윈도우가 재설정될 때를 표시합니다. 모델별 "Opus 한도에 도달했습니다" 또는 "Sonnet 한도에 도달했습니다" 메시지 후에는 `/model`로 해당 제품군 외의 모델로 전환하면 개발자가 계속 작업할 수 있습니다. [사용 한도 오류](/docs/ko/errors#youve-hit-your-session-limit)를 참조하십시오. 개발자가 그 동안 할 수 있는 작업:

230 * [사용 크레딧](https://support.claude.com/en/articles/12429409-extra-usage-for-paid-claude-plans)이 활성화된 경우 `/usage-credits`를 실행하여 할당량을 초과하는 사용을 요청하십시오.230 * [사용 크레딧](https://support.claude.com/en/articles/12429409-extra-usage-for-paid-claude-plans)이 활성화된 경우 `/usage-credits`를 실행하여 할당량을 초과하는 사용을 요청하십시오.

231 * Claude Code v2.1.234 이상에서 [재설정 후 중단된 작업을 자동으로 계속 대기](/docs/ko/interactive-mode#wait-for-a-usage-limit-to-reset); 해당 섹션에는 Claude Code가 자동으로 대기를 시작하는 시기와 개발자가 `/rate-limit-options`에서 선택하는 시기가 나열되어 있습니다. 플릿에 대해 Claude Code가 자동으로 해당 대기를 시작하는지 제어하려면 [관리 설정](/docs/ko/settings#settings-precedence)에서 [`autoContinueAtUsageLimit`](/docs/ko/settings-reference#autocontinueatusagelimit)을 설정하십시오.231 * Claude Code v2.1.234 이상에서 [재설정 후 중단된 작업을 자동으로 계속 대기](/docs/ko/interactive-mode#wait-for-a-usage-limit-to-reset); 해당 섹션에는 Claude Code가 자동으로 대기를 시작하는 시기와 개발자가 `/rate-limit-options`에서 선택하는 시기가 나열되어 있습니다. 플릿에 대해 Claude Code가 자동으로 해당 대기를 시작하는지 제어하려면 [관리 설정](/docs/ko/settings#settings-precedence)에서 [`autoContinueAtUsageLimit`](/docs/ko/settings-reference#autocontinueatusagelimit)을 설정하십시오.

232* **"개별 지출 한도에 도달했습니다", "조직의 월간 지출 한도" 또는 "팀의 공유 예산"**: 개발자의 요청이 사용 크레딧으로 청구되며, 이러한 크레딧이 설정한 지출 한도에 도달했습니다. 개발자가 계속하도록 허용하려면 [**관리 설정 > 사용**](https://claude.ai/admin-settings/usage)으로 이동하여 메시지가 명시한 한도를 높이십시오. 메시지가 플랜 재설정 시간도 명시하는 경우, 개발자는 대신 그때까지 기다릴 수 있습니다. 각 변형에 대해 [오류 참고](/docs/ko/errors#youve-hit-your-monthly-spend-limit)를 참조하십시오.232* **"You've hit your individual spend limit", "org's monthly spend limit" 또는 "team's shared budget"**: 개발자의 요청이 사용량 크레딧으로 청구되며, 이러한 크레딧이 설정한 지출 한도에 도달했습니다. 개발자가 계속하도록 허용하려면 [**Organization settings > Usage**](https://claude.ai/admin-settings/usage)로 이동하여 메시지가 명시한 한도를 높이십시오. 메시지가 플랜 재설정 시간도 명시하는 경우, 개발자는 대신 그때까지 기다릴 수 있습니다. 각 변형에 대해서는 [오류 참고 자료](/docs/ko/errors#youve-hit-your-monthly-spend-limit)를 참조하십시오.

233* **[Claude apps gateway](/docs/ko/claude-apps-gateway)의 지출 한도 메시지**: 개발자가 자체 호스팅된 게이트웨이에서 설정한 지출 상한선을 초과했으며, 게이트웨이는 기간이 재설정되거나 상한선을 높일 때까지 요청을 차단합니다. [게이트웨이 지출 한도](/docs/ko/claude-apps-gateway-spend-limits)에서 상한선, 재설정 일정 및 개발자가 보는 메시지를 참조하십시오.233* **[Claude apps gateway](/docs/ko/claude-apps-gateway)의 지출 한도 메시지**: 개발자가 자체 호스팅된 게이트웨이에서 설정한 지출 상한선을 초과했으며, 게이트웨이는 기간이 재설정되거나 상한선을 높일 때까지 요청을 차단합니다. [게이트웨이 지출 한도](/docs/ko/claude-apps-gateway-spend-limits)에서 상한선, 재설정 일정 및 개발자가 보는 메시지를 참조하십시오.

234* **컨텍스트 또는 자동 압축 경고**: 사용 한도가 아닙니다. 대화가 세션의 [자동 압축 윈도우](/docs/ko/model-config#set-the-auto-compact-window)에 가까워졌으며, Claude Code가 공간을 확보하기 위해 이전 기록을 요약하는 임계값입니다. 개발자를 [토큰 사용량 감소](#reduce-token-usage)로 안내하십시오.234* **컨텍스트 또는 자동 압축 경고**: 사용 한도가 아닙니다. 대화가 세션의 [자동 압축 윈도우](/docs/ko/model-config#set-the-auto-compact-window)에 가까워졌으며, Claude Code가 공간을 확보하기 위해 이전 기록을 요약하는 임계값입니다. 개발자를 [토큰 사용량 감소](#reduce-token-usage)로 안내하십시오.

235* **API 또는 클라우드 제공자 플랜에서 예상치 못한 높은 지출**: 일반적으로 절대 지워지지 않은 긴 세션 또는 기본 모델로 남겨진 Opus로 추적됩니다. 공유할 가장 영향력 있는 습관은 관련 없는 작업 간 지우기 및 작업에 맞는 모델 선택이며, 둘 다 [토큰 사용량 감소](#reduce-token-usage)에서 다룹니다.235* **API 또는 클라우드 제공자 플랜에서 예상치 못한 높은 지출**: 일반적으로 절대 지워지지 않은 긴 세션 또는 기본 모델로 남겨진 Opus로 추적됩니다. 공유할 가장 영향력 있는 습관은 관련 없는 작업 간 지우기 및 작업에 맞는 모델 선택이며, 둘 다 [토큰 사용량 감소](#reduce-token-usage)에서 다룹니다.

cross-session-messaging.md +1 −0

Details

192다음 중 하나가 전체 텍스트를 표시합니다:192다음 중 하나가 전체 텍스트를 표시합니다:

193 193

194* `Ctrl+O`를 눌러 [대화 기록 뷰어](/docs/ko/interactive-mode#transcript-viewer)를 열고 발신자의 세션 이름 아래에서 전체 텍스트를 읽습니다.194* `Ctrl+O`를 눌러 [대화 기록 뷰어](/docs/ko/interactive-mode#transcript-viewer)를 열고 발신자의 세션 이름 아래에서 전체 텍스트를 읽습니다.

195* [전체 화면 렌더링](/docs/ko/fullscreen#use-the-mouse)에서 메시지 일부가 생략된 미리보기 줄을 클릭하면 해당 위치에서 확장됩니다.

195* [`--verbose`](/docs/ko/cli-reference#cli-flags)로 시작한 세션에서, Claude Code는 미리보기 대신 전체 텍스트를 표시합니다.196* [`--verbose`](/docs/ko/cli-reference#cli-flags)로 시작한 세션에서, Claude Code는 미리보기 대신 전체 텍스트를 표시합니다.

196 197

197미리보기는 표시되는 것만 단축합니다. 확장하든 안 하든, Claude는 전체 메시지를 읽습니다.198미리보기는 표시되는 것만 단축합니다. 확장하든 안 하든, Claude는 전체 메시지를 읽습니다.

desktop.md +20 −20

Details

244 보기 모드 전환하기244 보기 모드 전환하기

245</h3>245</h3>

246 246

247보기 모드는 채팅 기록에 나타나는 세부 정보의 양을 제어합니다. 전송 버튼 옆의 **Transcript view** 드롭다운에서 모드를 전환하거나 macOS 또는 Windows에서 **Ctrl+O**를 눌러 모드를 순환합니다. Thinking 모드는 Claude가 보고 있는 세션에서 thinking을 생성한 후에만 드롭다운에 나타납니다.247보기 모드는 채팅 트랜스크립트에 나타나는 세부 정보의 양을 제어합니다. 보기 모드를 전환하려면 세션 제목 옆의 캐럿에서 세션 메뉴를 열고 **Transcript view**를 선택하거나, macOS 또는 Windows에서 **Ctrl+O**를 눌러 모드를 순환합니다. Thinking 모드는 보고 있는 세션에서 Claude가 사고를 생성한 후에만 메뉴에 나타납니다.

248 248

249| 모드 | 표시되는 것 |249| 모드 | 표시되는 것 |

250| - | - |250| - | - |

382 382

383두 세션을 동시에 보려면 macOS에서 **Cmd**를 누르거나 Windows에서 **Ctrl**을 누르고 사이드바의 세션을 클릭합니다. 세션이 이미 열려 있는 창 옆에 두 번째 창에서 열립니다. 분할이 활성화되어 있는 동안 다른 사이드바 세션을 클릭하면 포커스가 있는 창을 바꿉니다. macOS에서 \*\*Cmd+\\\*\*를 누르거나 Windows에서 \*\*Ctrl+\\\*\*를 눌러 포커스된 창을 닫고 단일 세션으로 돌아갑니다.383두 세션을 동시에 보려면 macOS에서 **Cmd**를 누르거나 Windows에서 **Ctrl**을 누르고 사이드바의 세션을 클릭합니다. 세션이 이미 열려 있는 창 옆에 두 번째 창에서 열립니다. 분할이 활성화되어 있는 동안 다른 사이드바 세션을 클릭하면 포커스가 있는 창을 바꿉니다. macOS에서 \*\*Cmd+\\\*\*를 누르거나 Windows에서 \*\*Ctrl+\\\*\*를 눌러 포커스된 창을 닫고 단일 세션으로 돌아갑니다.

384 384

385Worktrees는 기본적으로 `<project-root>/.claude/worktrees/`에 저장됩니다. Settings → Claude Code의 "Worktree location"에서 사용자 정의 디렉토리로 변경할 수 있습니다. 또한 모든 worktree 브랜치 이름 앞에 추가되는 브랜치 접두사를 설정할 수 있으며, 이는 Claude가 만든 브랜치를 정리하는 데 유용합니다. 완료되면 사이드바의 세션 위에 마우스를 올리고 아카이브 아이콘을 클릭하여 worktree를 제거합니다. PR이 병합되거나 닫힌 후 세션이 자동으로 아카이브되도록 하려면 Settings → Claude Code에서 **Auto-archive after PR merge or close**를 켭니다. 자동 아카이브는 실행을 완료한 로컬 세션에만 적용됩니다.385Worktrees는 기본적으로 `<project-root>/.claude/worktrees/`에 저장됩니다. Settings → Claude Code의 "Worktree location"에서 사용자 정의 디렉토리로 변경할 수 있습니다. 또한 모든 worktree 브랜치 이름 앞에 추가되는 브랜치 접두사를 설정할 수 있으며, 이는 Claude가 만든 브랜치를 정리하는 데 유용합니다. 완료되면 사이드바의 세션 위에 마우스를 올리고 아카이브 아이콘을 클릭하여 worktree를 제거합니다. 풀 리퀘스트가 병합되거나 닫힌 후 세션이 자동으로 아카이브되도록 하려면 Settings → Claude Code에서 **Auto-archive after PR merge or close**를 켭니다. 자동 아카이브는 실행을 완료한 로컬 세션에만 적용됩니다.

386 386

387gitignored 파일 (예: `.env`)을 새 worktrees에 포함하려면 프로젝트 루트에 [`.worktreeinclude` 파일](/docs/ko/worktrees#copy-gitignored-files-into-worktrees)을 만듭니다.387gitignored 파일 (예: `.env`)을 새 worktrees에 포함하려면 프로젝트 루트에 [`.worktreeinclude` 파일](/docs/ko/worktrees#copy-gitignored-files-into-worktrees)을 만듭니다.

388 388

410 백그라운드 작업 보기410 백그라운드 작업 보기

411</h3>411</h3>

412 412

413작업 패널은 현재 세션 내에서 실행 중인 백그라운드 작업을 표시합니다: 서브에이전트, 백그라운드 셸 명령, [동적 워크플로우](/docs/ko/workflows). **Views** 메뉴에서 열거나 레이아웃으로 드래그합니다.413작업 패널은 현재 세션 내에서 실행 중인 백그라운드 작업을 표시합니다: 서브에이전트, 백그라운드 셸 명령, [동적 워크플로](/docs/ko/workflows). **Views** 메뉴에서 열거나 레이아웃으로 드래그합니다.

414 414

415모든 항목을 클릭하여 서브에이전트 패널에서 출력을 보거나 중지합니다. 다른 세션이 수행하는 작업을 보려면 [사이드바](#work-in-parallel-with-sessions)를 사용하거나 Claude에게 [당신을 대신해 확인하도록](#work-across-sessions) 요청합니다.415모든 항목을 클릭하여 서브에이전트 패널에서 출력을 보거나 중지합니다. 다른 세션이 수행하는 작업을 보려면 [사이드바](#work-in-parallel-with-sessions)를 사용하거나 Claude에게 [대신 확인하도록](#work-across-sessions) 요청합니다.

416 416

417<h3 id="work-across-sessions">417<h3 id="work-across-sessions">

418 세션 간에 작업하기418 세션 간에 작업하기

420 420

421Claude는 다른 Code 탭 세션을 나열하고, 각 세션이 수행한 작업을 읽고, 세션 간에 메시지를 보낼 수 있습니다. 일반 언어로 요청합니다: "어느 세션이 auth 리팩토링을 건드렸나?", "API 세션은 무엇을 결론지었나?", 또는 "payments 세션에 스키마가 변경되었다고 알려주세요". Claude에게 세션 이름을 바꾸거나 아카이브하도록 요청할 수도 있습니다. Claude는 사이드바의 아카이브 아이콘과 동일한 방식으로 세션을 아카이브하므로 PR이 병합된 세션을 정리하도록 요청합니다.421Claude는 다른 Code 탭 세션을 나열하고, 각 세션이 수행한 작업을 읽고, 세션 간에 메시지를 보낼 수 있습니다. 일반 언어로 요청합니다: "어느 세션이 auth 리팩토링을 건드렸나?", "API 세션은 무엇을 결론지었나?", 또는 "payments 세션에 스키마가 변경되었다고 알려주세요". Claude에게 세션 이름을 바꾸거나 아카이브하도록 요청할 수도 있습니다. Claude는 사이드바의 아카이브 아이콘과 동일한 방식으로 세션을 아카이브하므로 PR이 병합된 세션을 정리하도록 요청합니다.

422 422

423이 표면을 통해 Claude는 데스크톱 앱이 자체적으로 실행하는 세션만 봅니다: 로컬, [SSH](#ssh-sessions), Code 탭의 [WSL](/docs/ko/desktop-wsl) 세션. Claude는 클라우드 세션이나 터미널 CLI 또는 VS Code 확장에서 시작한 세션을 보지 못합니다. 같은 프로젝트의 worktrees에 있더라도 9개의 터미널 worktrees가 열려 있고 2개의 데스크톱 세션이 있으면 Claude가 그 중 하나에서 답변할 때 다른 하나의 데스크톱 세션을 보고합니다. Claude는 요청하는 세션을 나열하지 않습니다. 기본적으로 가장 최근에 활성화된 20개 세션을 보고 아카이브된 세션을 건너뜁니다. 요청하지 않는 한 [교차 세션 메시징](/docs/ko/cross-session-messaging)은 Claude가 [다른 Claude Code 세션](/docs/ko/cross-session-messaging#see-which-sessions-claude-can-reach)에 메시지를 보낼 수 있게 하며, 터미널 세션도 포함합니다.423이 사용 환경을 통해 Claude는 데스크톱 앱이 자체적으로 실행하는 세션만 봅니다: Code 탭의 로컬, [SSH](#ssh-sessions), [WSL](/docs/ko/desktop-wsl) 세션. Claude는 클라우드 세션이나 터미널 CLI 또는 VS Code 확장에서 시작한 세션을 같은 프로젝트의 worktrees에 있더라도 보지 못합니다. 따라서 9개의 터미널 worktrees와 2개의 데스크톱 세션이 열려 있으면 그 중 한 데스크톱 세션에서 답변하는 Claude는 나머지 하나의 데스크톱 세션만 보고합니다. Claude는 요청하는 세션을 나열하지 않습니다. 기본적으로 가장 최근에 활성화된 20개 세션을 보며, 요청하지 않는 한 아카이브된 세션은 건너뜁니다. [교차 세션 메시징](/docs/ko/cross-session-messaging)은 이와 별도로 Claude가 터미널 세션을 포함한 [다른 Claude Code 세션](/docs/ko/cross-session-messaging#see-which-sessions-claude-can-reach)에 메시지를 보낼 수 있게 합니다.

424 424

425Claude가 이 표면을 통해 다른 세션에 메시지를 보낼 때 Claude Code는 보내는 세션의 제목과 다시 링크된 카드로 표시하므로 항상 메시지가 어디서 왔는지 알 수 있습니다. 수신 세션이 작업 중이면 Claude Code는 메시지를 보류하고 Claude는 현재 작업이 완료되면 읽습니다. 수신 Claude는 회신할 수 있으며 Claude Code는 회신을 이 표면을 통해 다시 전달합니다. Claude는 아카이브된 세션에 전달할 수 없으며 메시지가 전달되지 않을 때 알려줍니다.425Claude가 이 사용 환경을 통해 다른 세션에 메시지를 보낼 때 Claude Code는 보내는 세션의 제목과 다시 돌아가는 링크가 표시된 카드로 보여 주므로 항상 메시지가 어디서 왔는지 알 수 있습니다. 수신 세션이 작업 중이면 Claude Code는 메시지를 보류하고 Claude는 현재 작업이 완료되면 읽습니다. 수신 Claude는 회신할 수 있으며 Claude Code는 회신을 이 사용 환경을 통해 다시 전달합니다. Claude는 아카이브된 세션에 전달할 수 없으며 메시지가 전달되지 않을 때 알려줍니다.

426 426

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

428 428

429* 세션을 아카이브하기 전에 Claude는 먼저 요청합니다. Auto 및 Bypass 권한을 포함한 모든 권한 모드에서 승인 카드를 봅니다.429* 세션을 아카이브하기 전에 Claude는 먼저 묻습니다. Auto 및 Bypass 권한을 포함한 모든 권한 모드에서 승인 카드가 표시됩니다.

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

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

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

433 433

434Claude는 또한 새 세션을 제안할 수 있습니다. 현재 작업의 범위를 벗어나지만 수정할 가치가 있는 것을 발견하면 작업을 채팅의 작업 칩으로 제공합니다. 칩을 클릭하여 자신의 worktree를 가진 새 세션에서 해당 작업을 시작합니다. Claude는 현재 세션을 중단 없이 계속합니다.434Claude는 또한 새 세션을 제안할 수 있습니다. 현재 작업의 범위를 벗어나지만 수정할 가치가 있는 것을 발견하면 작업을 채팅의 작업 칩으로 제공합니다. 칩을 클릭하여 자신의 worktree를 가진 새 세션에서 해당 작업을 시작합니다. Claude는 현재 세션을 중단 없이 계속합니다.

435 435

441 441

442클라우드 세션은 또한 여러 저장소를 지원합니다. 클라우드 환경을 선택한 후 선택된 저장소 옆의 **+** 버튼을 클릭하여 세션에 추가 저장소를 추가합니다. 각 저장소는 자신의 브랜치 선택기를 가집니다. 이는 공유 라이브러리와 그 소비자를 업데이트하는 것과 같이 여러 코드베이스에 걸친 작업에 유용합니다.442클라우드 세션은 또한 여러 저장소를 지원합니다. 클라우드 환경을 선택한 후 선택된 저장소 옆의 **+** 버튼을 클릭하여 세션에 추가 저장소를 추가합니다. 각 저장소는 자신의 브랜치 선택기를 가집니다. 이는 공유 라이브러리와 그 소비자를 업데이트하는 것과 같이 여러 코드베이스에 걸친 작업에 유용합니다.

443 443

444클라우드 세션이 작동하는 방식에 대한 자세한 내용은 [웹의 Claude Code](/docs/ko/claude-code-on-the-web)를 참조하세요. 한 가지 작업이 많은 클라우드 세션이 필요할 때 사이드바에서 **Projects**를 선택하여 [프로젝트](/docs/ko/claude-projects)를 만들고, Claude가 한 대화에서 세션을 시작하고 추적하도록 합니다.444클라우드 세션이 작동하는 방식에 대한 자세한 내용은 [클라우드에서 Claude Code 사용하기](/docs/ko/claude-code-on-the-web)를 참조하세요. 한 가지 작업이 많은 클라우드 세션이 필요할 때 사이드바에서 **Projects**를 선택하여 [프로젝트](/docs/ko/claude-projects)를 만들고, Claude가 한 대화에서 세션을 시작하고 추적하도록 합니다.

445 445

446<h3 id="continue-in-another-surface">446<h3 id="continue-in-another-surface">

447 다른 표면에서 계속하기447 다른 사용 환경에서 계속하기

448</h3>448</h3>

449 449

450세션 도구 모음의 오른쪽 아래에 있는 VS Code 아이콘에서 액세스할 수 있는 **Continue in** 메뉴를 사용하면 세션을 다른 표면으로 이동할 수 있습니다:450세션을 다른 곳에서 계속하려면 세션 제목 옆의 캐럿 또는 사이드바의 세션 행에서 세션 메뉴를 열고 **Open in**을 선택합니다:

451 451

452* **Claude Code on the Web**: 로컬 세션을 클라우드에서 계속 실행하도록 보냅니다. Desktop은 브랜치를 푸시하고, 대화 요약을 생성하고, 전체 컨텍스트를 사용하여 새 클라우드 세션을 만듭니다. 그 후 로컬 세션을 아카이브하거나 유지하도록 선택할 수 있습니다. 이는 깨끗한 작업 트리가 필요하며 SSH 세션에는 사용할 수 없습니다.452* **Cloud**를 선택하면 대화가 요약으로 이어진 상태로 세션을 [클라우드 세션](/docs/ko/claude-code-on-the-web)으로 계속합니다. 확인하기 전에 대화 상자에 파일도 함께 이동하는지, 그리고 클라우드 세션이 준비되면 이 세션이 아카이브되는지가 표시됩니다. [SSH](#ssh-sessions)를 통해 실행되거나 [WSL](/docs/ko/desktop-wsl)에서 실행되는 세션은 이 방식으로 이동할 수 없습니다.

453* **Your IDE**: 현재 작업 디렉토리에서 지원되는 IDE에서 프로젝트를 엽니다.453* 설치된 편집기나 파일 관리자를 선택하면 디스크에 있는 세션의 폴더를 해당 앱에서 엽니다.

454 454

455<h3 id="sessions-from-dispatch">455<h3 id="sessions-from-dispatch">

456 Dispatch에서 세션456 Dispatch에서 시작한 세션

457</h3>457</h3>

458 458

459[Dispatch](https://support.claude.com/en/articles/13947068)는 [Cowork](https://claude.com/product/cowork) 탭에 있는 Claude와의 지속적인 대화입니다. Dispatch에 작업을 메시지하면 처리 방법을 결정합니다.459[Dispatch](https://support.claude.com/en/articles/13947068)는 [Cowork](https://claude.com/product/cowork) 탭에 있는 Claude와의 지속적인 대화입니다. Dispatch에 작업을 메시지하면 처리 방법을 결정합니다.

460 460

461작업은 두 가지 방법으로 Code 세션이 될 수 있습니다: 직접 요청하는 경우 (예: "Claude Code 세션을 열고 로그인 버그를 수정하세요") 또는 Dispatch가 작업이 개발 작업이라고 결정하고 자동으로 하나를 생성하는 경우입니다. 일반적으로 Code로 라우팅되는 작업에는 버그 수정, 종속성 업데이트, 테스트 실행 또는 pull request 열기가 포함됩니다. 연구, 문서 편집, 스프레드시트 작업은 Cowork에 남아 있습니다.461작업은 두 가지 방법으로 Code 세션이 될 수 있습니다: 직접 요청하는 경우 (예: "Claude Code 세션을 열고 로그인 버그를 수정하세요") 또는 Dispatch가 작업이 개발 작업이라고 결정하고 자동으로 하나를 생성하는 경우입니다. 일반적으로 Code로 라우팅되는 작업에는 버그 수정, 의존성 업데이트, 테스트 실행 또는 풀 리퀘스트 열기가 포함됩니다. 연구, 문서 편집, 스프레드시트 작업은 Cowork에 남아 있습니다.

462 462

463어느 쪽이든 Code 세션은 **Dispatch** 배지가 있는 Code 탭의 사이드바에 나타납니다. 완료되거나 승인이 필요할 때 휴대폰에서 푸시 알림을 받습니다.463어느 쪽이든 Code 세션은 **Dispatch** 배지가 있는 Code 탭의 사이드바에 나타납니다. 완료되거나 승인이 필요할 때 휴대폰에서 푸시 알림을 받습니다.

464 464

465[컴퓨터 사용](#let-claude-use-your-computer)이 활성화되어 있으면 Dispatch 생성 Code 세션도 사용할 수 있습니다. 이러한 세션의 앱 승인은 30분 후 만료되고 다시 프롬프트하며, 일반 Code 세션처럼 전체 세션 동안 지속되지 않습니다.465[컴퓨터 사용](#let-claude-use-your-computer)이 활성화되어 있으면 Dispatch 생성 Code 세션도 사용할 수 있습니다. 이러한 세션의 앱 승인은 30분 후 만료되고 다시 확인을 요청하며, 일반 Code 세션처럼 전체 세션 동안 지속되지 않습니다.

466 466

467설정, 페어링, Dispatch 설정은 [Dispatch 도움말 문서](https://support.claude.com/en/articles/13947068)를 참조하세요. Dispatch는 Pro 또는 Max 계획이 필요하며 Team 또는 Enterprise 계획에서는 사용할 수 없습니다.467설정, 페어링, Dispatch 설정은 [Dispatch 도움말 문서](https://support.claude.com/en/articles/13947068)를 참조하세요. Dispatch는 Pro 또는 Max 계획이 필요하며 Team 또는 Enterprise 계획에서는 사용할 수 없습니다.

468 468

739 739

740[Extended thinking](/docs/ko/model-config#extended-thinking)은 기본적으로 활성화되어 있으며, 복잡한 추론 작업의 성능을 향상시키지만 추가 토큰을 사용합니다. Anthropic API에서 생각을 비활성화하려면 로컬 환경 편집기에서 `MAX_THINKING_TOKENS`을 `0`으로 설정합니다. 이는 Opus 5.5, Sonnet 5.5 또는 Fable 모델에는 영향을 주지 않으며, 이들은 항상 extended thinking을 사용합니다. Anthropic API에서 생각을 비활성화한 상태에서 Claude Code는 [해당 조합을 허용하지 않는](/docs/ko/errors#effort-isnt-available-with-thinking-turned-off) Opus 5와 같은 모델에 더 높은 수준 대신 노력 `high`를 보냅니다.740[Extended thinking](/docs/ko/model-config#extended-thinking)은 기본적으로 활성화되어 있으며, 복잡한 추론 작업의 성능을 향상시키지만 추가 토큰을 사용합니다. Anthropic API에서 생각을 비활성화하려면 로컬 환경 편집기에서 `MAX_THINKING_TOKENS`을 `0`으로 설정합니다. 이는 Opus 5.5, Sonnet 5.5 또는 Fable 모델에는 영향을 주지 않으며, 이들은 항상 extended thinking을 사용합니다. Anthropic API에서 생각을 비활성화한 상태에서 Claude Code는 [해당 조합을 허용하지 않는](/docs/ko/errors#effort-isnt-available-with-thinking-turned-off) Opus 5와 같은 모델에 더 높은 수준 대신 노력 `high`를 보냅니다.

741 741

742[적응형 추론](/docs/ko/model-config#adjust-effort-level)이 있는 모델에서는 적응형 추론이 생각 깊이를 제어하기 때문에 `0`이 아닌 `MAX_THINKING_TOKENS` 값은 무시됩니다. Opus 4.6 및 Sonnet 4.6에서는 `CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING`을 `1`로 설정하여 고정 생각 예산을 사용합니다. Fable 모델, Sonnet 5 이상, Opus 4.7 이상은 항상 적응형 추론을 사용하며 고정 예산 모드가 없습니다.742[적응형 추론](/docs/ko/model-config#adjust-effort-level)이 있는 모델에서는 적응형 추론이 사고 깊이를 제어하기 때문에 Claude Code가 양수 `MAX_THINKING_TOKENS` 값의 숫자 자체를 무시합니다. Opus 4.6 및 Sonnet 4.6에서는 `CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING`을 `1`로 설정하여 고정 사고 예산을 사용합니다. Fable 모델, Sonnet 5 이상, Opus 4.7 이상은 항상 적응형 추론을 사용하며 고정 예산 모드가 없습니다.

743 743

744<h4 id="local-sessions-on-managed-devices">744<h4 id="local-sessions-on-managed-devices">

745 관리되는 디바이스의 로컬 세션745 관리되는 디바이스의 로컬 세션

1005| `--dangerously-skip-permissions` | 권한 모드 무시. Pro 및 Max 플랜에서는 설정 → Claude Code → "권한 모드 무시 허용"에서 활성화합니다. Team 및 Enterprise 플랜에서는 조직 정책이 제어합니다 |1005| `--dangerously-skip-permissions` | 권한 모드 무시. Pro 및 Max 플랜에서는 설정 → Claude Code → "권한 모드 무시 허용"에서 활성화합니다. Team 및 Enterprise 플랜에서는 조직 정책이 제어합니다 |

desktop-ios-simulator.md +1 −1

Details

92* **Cmd+S**로 스크린샷 또는 **Cmd+R**로 화면 녹화 저장 (창의 캡처 버튼 또는 단축키 사용, 파일은 Desktop에 저장됨)92* **Cmd+S**로 스크린샷 또는 **Cmd+R**로 화면 녹화 저장 (창의 캡처 버튼 또는 단축키 사용, 파일은 Desktop에 저장됨)

93* **Detach simulator**를 클릭하여 기기 스트리밍 중지 (종료하지 않음), 창을 **Attach simulator** 상태로 반환93* **Detach simulator**를 클릭하여 기기 스트리밍 중지 (종료하지 않음), 창을 **Attach simulator** 상태로 반환

94 94

95기기 이름 아래의 행은 시뮬레이터의 비디오 스트림을 조정합니다. Mac에 부담이 되면 **Frame rate** 또는 **Resolution**을 낮추고, **Encoding**을 H.264와 JPEG 사이에서 전환하거나, **FPS**를 확인하여 창이 받는 프레임 레이트를 표시합니다. 이 설정은 창이 기기를 표시하는 방식을 변경하며, 앱 실행 방식은 변경하지 않습니다.95시뮬레이터의 비디오 스트림을 조정하려면 창의 **Display** 메뉴를 엽니다. Mac에 부담이 되면 **Frame rate** 또는 **Resolution**을 낮춥니다. 두 설정 모두 창이 기기를 표시하는 방식을 변경하며, 앱 실행 방식은 변경하지 않습니다.

96 96

97사용자와 Claude가 동일한 기기를 제어하므로 탭이 Claude가 보는 앱 상태를 변경합니다. Claude가 특정 화면을 확인하도록 하려면 탭하여 이동한 후 요청합니다. Claude가 기기를 제어하는 동안 창은 화면 위에 **Claude is using this device** 배지를 표시합니다. 배지가 사라질 때까지 탭을 기다려 결과가 입력이 아닌 앱을 반영하도록 합니다.97사용자와 Claude가 동일한 기기를 제어하므로 탭이 Claude가 보는 앱 상태를 변경합니다. Claude가 특정 화면을 확인하도록 하려면 탭하여 이동한 후 요청합니다. Claude가 기기를 제어하는 동안 창은 화면 위에 **Claude is using this device** 배지를 표시합니다. 배지가 사라질 때까지 탭을 기다려 결과가 입력이 아닌 앱을 반영하도록 합니다.

98 98

desktop-quickstart.md +1 −1

Details

135 135

136**Claude를 일정에 따라 실행.** [예약된 작업](/docs/ko/desktop-scheduled-tasks)을 설정하여 Claude를 정기적으로 자동으로 실행합니다: 매일 아침 일일 코드 검토, 주간 종속성 감사 또는 연결된 도구에서 정보를 가져오는 브리핑입니다.136**Claude를 일정에 따라 실행.** [예약된 작업](/docs/ko/desktop-scheduled-tasks)을 설정하여 Claude를 정기적으로 자동으로 실행합니다: 매일 아침 일일 코드 검토, 주간 종속성 감사 또는 연결된 도구에서 정보를 가져오는 브리핑입니다.

137 137

138**준비가 되면 확장.** 사이드바에서 [병렬 세션](/docs/ko/desktop#work-in-parallel-with-sessions)을 열어 여러 작업을 동시에 수행하고, 필요에 따라 각각 자체 Git worktree에서 실행하고, [작업 창](/docs/ko/desktop#watch-background-tasks)을 열어 세션이 실행 중인 서브에이전트 및 백그라운드 명령어를 봅니다. [사이드 채팅](/docs/ko/desktop#ask-a-side-question-without-derailing-the-session)을 열어 메인 스레드를 방해하지 않고 질문을 할 수 있습니다. [장기 실행 작업을 클라우드로 전송](/docs/ko/desktop#run-long-running-tasks-in-the-cloud)하여 앱을 닫아도 계속 실행되도록 하거나, 작업이 예상보다 오래 걸리면 [웹 또는 IDE에서 세션을 계속](/docs/ko/desktop#continue-in-another-surface)할 수 있습니다. [GitHub, Slack 및 Linear와 같은 외부 도구를 연결](/docs/ko/desktop#extend-claude-code)하여 워크플로우를 통합합니다.138**준비가 되면 확장.** 사이드바에서 [병렬 세션](/docs/ko/desktop#work-in-parallel-with-sessions)을 열어 여러 작업을 동시에 수행하고, 필요에 따라 각각 자체 Git worktree에서 실행하고, [작업 창](/docs/ko/desktop#watch-background-tasks)을 열어 세션이 실행 중인 서브에이전트 및 백그라운드 명령을 봅니다. [사이드 채팅](/docs/ko/desktop#ask-a-side-question-without-derailing-the-session)을 열어 메인 스레드를 방해하지 않고 질문을 할 수 있습니다. [장기 실행 작업을 클라우드로 전송](/docs/ko/desktop#run-long-running-tasks-in-the-cloud)하여 앱을 닫아도 계속 실행되도록 하거나, 작업이 예상보다 오래 걸리면 [이미 시작한 세션을 클라우드로 이동](/docs/ko/desktop#continue-in-another-surface)할 수 있습니다. [GitHub, Slack 및 Linear와 같은 외부 도구를 연결](/docs/ko/desktop#extend-claude-code)하여 워크플로를 통합합니다.

139 139

140<h2 id="what’s-next">140<h2 id="what’s-next">

141 다음 단계141 다음 단계

env-vars.md +363 −324

Details

124 변수124 변수

125</h2>125</h2>

126 126

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

128 128

129<Note>129<Note>

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

131 131

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

133 133

134 * `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC`134 * `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC`

135 * `DISABLE_TELEMETRY`135 * `DISABLE_TELEMETRY`

138 * `FALLBACK_FOR_ALL_PRIMARY_MODELS`138 * `FALLBACK_FOR_ALL_PRIMARY_MODELS`

139 * `IS_DEMO`139 * `IS_DEMO`

140 140

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

142</Note>142</Note>

143 143

144| 변수 | 용도 |144| 변수 | 용도 |

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

183| `ANTHROPIC_FOUNDRY_RESOURCE` | Microsoft Foundry 리소스 이름입니다(예: `my-resource`). Claude Code는 [URL이나 호스트 이름을 거부합니다](/docs/ko/errors#anthropic-foundry-resource-must-be-a-foundry-resource-name). `ANTHROPIC_FOUNDRY_BASE_URL`이 설정되지 않은 경우 필수입니다([Microsoft Foundry](/docs/ko/microsoft-foundry) 참조) |183| `ANTHROPIC_FOUNDRY_RESOURCE` | Microsoft Foundry 리소스 이름입니다(예: `my-resource`). Claude Code는 [URL이나 호스트 이름을 거부합니다](/docs/ko/errors#anthropic-foundry-resource-must-be-a-foundry-resource-name). `ANTHROPIC_FOUNDRY_BASE_URL`이 설정되지 않은 경우 필수입니다([Microsoft Foundry](/docs/ko/microsoft-foundry) 참조) |

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

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

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

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

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

191| `ANTHROPIC_WORKSPACE_ID` | [워크로드 아이덴티티 페더레이션](https://platform.claude.com/docs/en/manage-claude/workload-identity-federation)용 워크스페이스 ID입니다. 페더레이션 규칙의 범위가 둘 이상의 워크스페이스인 경우, 토큰 교환 시 대상 워크스페이스를 알 수 있도록 이 값을 설정하십시오 |191| `ANTHROPIC_WORKSPACE_ID` | [워크로드 아이덴티티 페더레이션](https://platform.claude.com/docs/en/manage-claude/workload-identity-federation)의 워크스페이스 ID입니다. 페더레이션 규칙의 범위가 둘 이상의 워크스페이스인 경우 토큰 교환이 대상 워크스페이스를 알 수 있도록 이 값을 설정합니다 |

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

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

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

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

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

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

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

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

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

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

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

203| `CLAUDE_AGENT_SDK_DISABLE_BUILTIN_AGENTS` | `1`로 설정하면 Explore, Plan과 같은 모든 기본 제공 [서브에이전트](/docs/ko/sub-agents) 유형을 비활성화합니다. 비대화형 모드(`-p` 플래그)에서만 적용됩니다. 빈 상태에서 시작하려는 SDK 사용자에게 유용합니다. 이 설정은 Agent 도구 호출에서 `subagent_type`이 생략되었을 때 Claude Code가 실행하는 서브에이전트인 `general-purpose`도 제거합니다. 이 경우 해당 호출은 [`subagent_type is required`](/docs/ko/errors#subagent-type-is-required) 오류로 실패합니다 |203| `CLAUDE_AGENT_SDK_DISABLE_BUILTIN_AGENTS` | `1`로 설정하면 Explore, Plan 등 모든 기본 제공 [서브에이전트](/docs/ko/sub-agents) 유형을 비활성화합니다. 비대화형 모드(`-p` 플래그)에서만 적용됩니다. 빈 상태에서 시작하려는 SDK 사용자에게 유용합니다. 이 변수는 Agent 도구 호출에서 `subagent_type`을 생략했을 때 Claude Code가 실행하는 서브에이전트인 `general-purpose`도 제거합니다. 그러면 이러한 호출은 [`subagent_type is required`](/docs/ko/errors#subagent-type-is-required) 오류와 함께 실패합니다 |

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

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

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

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

208| `CLAUDE_AX_PREPARK_MS` | [스크린 리더 모드](/docs/ko/accessibility)에서 Claude Code가 새 줄이나 변경된 줄을 쓰기 전에 대기하는 시간(밀리초)입니다. 기본값은 `0`이므로 Claude Code는 대기하지 않습니다. v2.1.287 이전에는 기본값이 `50`이었습니다. Claude Code는 대기 시간의 상한을 `5000`으로 제한합니다. Claude Code v2.1.233 이상이 필요합니다 |208| `CLAUDE_AX_PREPARK_MS` | [스크린 리더 모드](/docs/ko/accessibility)에서 Claude Code가 새 줄이나 변경된 줄을 쓰기 전에 대기하는 시간(밀리초)입니다. 기본값은 `0`이므로 Claude Code는 대기하지 않습니다. v2.1.287 이전에는 기본값이 `50`이었습니다. Claude Code는 대기 시간의 상한을 `5000`으로 제한합니다. Claude Code v2.1.233 이상이 필요합니다 |

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

210| `CLAUDE_AX_STARTUP_QUIET_MS` | [스크린 리더 모드](/docs/ko/accessibility)에서 시작 확인 줄 이후 Claude Code가 첫 인터페이스 렌더링을 보류하는 시간(밀리초)으로, 새 출력이 끼어들기 전에 스크린 리더가 해당 줄을 끝까지 읽을 수 있게 합니다. 기본값은 `3000`입니다. 즉시 렌더링하려면 `0`으로 설정하십시오. Claude Code는 보류 시간의 상한을 `600000`(10분)으로 제한합니다. 첫 키 입력 시 보류가 일찍 종료됩니다. Claude Code v2.1.217 이상이 필요합니다 |210| `CLAUDE_AX_STARTUP_QUIET_MS` | [스크린 리더 모드](/docs/ko/accessibility)에서 시작 확인 줄 이후 Claude Code가 첫 인터페이스 렌더링을 보류하는 시간(밀리초)으로, 새 출력이 끼어들기 전에 스크린 리더가 해당 줄을 끝까지 읽을 수 있게 합니다. 기본값은 `3000`입니다. 즉시 렌더링하려면 `0`으로 설정합니다. Claude Code는 보류 시간의 상한을 `600000`(10분)으로 제한합니다. 첫 키 입력이 있으면 보류가 일찍 종료됩니다. Claude Code v2.1.217 이상이 필요합니다 |

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

248| `CLAUDE_CODE_DISABLE_AUTH_REFRESH_LOCK` | `1`로 설정하면 Claude Code 프로세스가 다른 프로세스가 [`gcpAuthRefresh`](/docs/ko/settings-reference#gcpauthrefresh) 또는 [`awsAuthRefresh`](/docs/ko/settings-reference#awsauthrefresh) 명령을 실행하는 동안 기다리지 않고 직접 실행합니다. Claude Code v2.1.286 이상이 필요합니다 |248| `CLAUDE_CODE_DISABLE_AUTH_REFRESH_LOCK` | `1`로 설정하면 Claude Code 프로세스가 다른 프로세스가 실행하는 동안 기다리는 대신 [`gcpAuthRefresh`](/docs/ko/settings-reference#gcpauthrefresh) 또는 [`awsAuthRefresh`](/docs/ko/settings-reference#awsauthrefresh) 명령을 직접 실행합니다. Claude Code v2.1.286 이상이 필요합니다 |

249| `CLAUDE_CODE_DISABLE_AUTO_MEMORY` | `1`로 설정하면 [자동 메모리](/docs/ko/memory#auto-memory)를 비활성화합니다. `--bare` 모드나 [`autoMemoryEnabled: false`](/docs/ko/settings-reference#automemoryenabled)로 인해 비활성화되는 경우에도 자동 메모리를 강제로 켜려면 `0`으로 설정하십시오. 비활성화되면 Claude는 자동 메모리 파일을 생성하거나 로드하지 않습니다 |249| `CLAUDE_CODE_DISABLE_AUTO_MEMORY` | `1`로 설정하면 [자동 메모리](/docs/ko/memory#auto-memory)를 비활성화합니다. `0`으로 설정하면 `--bare` 모드나 [`autoMemoryEnabled: false`](/docs/ko/settings-reference#automemoryenabled)로 인해 비활성화되는 경우에도 자동 메모리를 강제로 켭니다. 비활성화하면 Claude는 자동 메모리 파일을 생성하거나 로드하지 않습니다 |

250| `CLAUDE_CODE_DISABLE_BACKGROUND_TASKS` | `1`로 설정하면 Bash 및 서브에이전트 도구의 `run_in_background` 매개변수, 자동 백그라운드 전환, Ctrl+B 단축키를 포함한 모든 백그라운드 작업 기능을 비활성화합니다 |250| `CLAUDE_CODE_DISABLE_BACKGROUND_TASKS` | `1`로 설정하면 Bash 및 서브에이전트 도구의 `run_in_background` 파라미터, 자동 백그라운드 전환, Ctrl+B 단축키를 포함한 모든 백그라운드 작업 기능을 비활성화합니다 |

251| `CLAUDE_CODE_DISABLE_BEDROCK_CONTENT_TYPE_DEFAULT` | `1`로 설정하면 Claude Code가 `Content-Type` 헤더가 없거나 비어 있는 [Amazon Bedrock](/docs/ko/amazon-bedrock) 스트리밍 응답을 Amazon Bedrock의 바이너리 이벤트 스트림으로 취급하지 않습니다. 기본적으로 Claude Code는 게이트웨이가 그 외에는 수정되지 않은 응답에서 헤더만 누락했다고 가정하므로, 본문을 디코딩하여 스트리밍이 계속 작동합니다. 스트림을 server-sent events로 다시 내보내는 게이트웨이에서만 이 변수를 설정하십시오. 그러면 Claude Code는 헤더가 없는 본문을 대신 server-sent events로 읽습니다. Claude Code v2.1.239 이상이 필요합니다 |251| `CLAUDE_CODE_DISABLE_BEDROCK_CONTENT_TYPE_DEFAULT` | `1`로 설정하면 `Content-Type` 헤더가 없거나 비어 있는 [Amazon Bedrock](/docs/ko/amazon-bedrock) 스트리밍 응답을 Claude Code가 Amazon Bedrock의 바이너리 이벤트 스트림으로 취급하지 않습니다. 기본적으로 Claude Code는 게이트웨이가 그 외에는 수정되지 않은 응답에서 헤더만 제거했다고 가정하므로, 본문을 디코딩하여 스트리밍이 계속 작동합니다. 스트림을 서버 전송 이벤트로 다시 내보내는 게이트웨이에 대해서만 이 변수를 설정합니다. 그러면 Claude Code는 헤더 없는 본문을 서버 전송 이벤트로 읽습니다. Claude Code v2.1.239 이상이 필요합니다 |

252| `CLAUDE_CODE_DISABLE_BEDROCK_CONTENT_TYPE_GUARD` | `1`로 설정하면 [Amazon Bedrock](/docs/ko/amazon-bedrock) 스트리밍 응답이 `application/vnd.amazon.eventstream` content-type을 갖는지 확인하는 검사를 건너뜁니다. 이 변수가 없으면 응답에 다른 content-type이 있을 때 Claude Code는 해당 유형을 명시하는 오류와 함께 요청을 실패시키며, 이는 [게이트웨이나 프록시가 응답을 변환하고 있음](/docs/ko/amazon-bedrock#streaming-errors-behind-a-gateway-or-proxy)을 의미합니다. 이 변수를 설정하는 대신 게이트웨이가 `Content-Type` 헤더와 본문을 수정 없이 전달하도록 구성하십시오. Claude Code v2.1.208 이상이 필요합니다 |252| `CLAUDE_CODE_DISABLE_BEDROCK_CONTENT_TYPE_GUARD` | `1`로 설정하면 [Amazon Bedrock](/docs/ko/amazon-bedrock) 스트리밍 응답이 `application/vnd.amazon.eventstream` content-type을 포함하는지 확인하는 검사를 건너뜁니다. 이 변수가 없으면 응답이 다른 content-type을 포함할 때 Claude Code는 해당 유형을 명시하는 오류와 함께 요청을 실패시키며, 이는 [게이트웨이나 프록시가 응답을 변환하고 있다](/docs/ko/amazon-bedrock#streaming-errors-behind-a-gateway-or-proxy)는 의미입니다. 이 변수를 설정하기보다는 `Content-Type` 헤더와 본문을 수정하지 않고 전달하도록 게이트웨이를 구성합니다. Claude Code v2.1.208 이상이 필요합니다 |

253| `CLAUDE_CODE_DISABLE_BG_EXIT_HANDOFF` | `1`로 설정하면 [슈퍼바이저](/docs/ko/agent-view#the-supervisor-process)가 [백그라운드 세션](/docs/ko/agent-view)의 프로세스를 중지, 재시작 또는 업데이트할 때, 해당 세션에서 실행 중인 백그라운드 셸 명령, 동적 워크플로, 그리고 v2.1.198부터는 백그라운드 서브에이전트를 세션의 다음 프로세스로 넘기지 않고 중지합니다. 이 인계에만 영향을 줍니다. `←`나 [`/background`](/docs/ko/agent-view#from-inside-a-session)로 세션을 백그라운드로 전환하면 진행 중인 작업이 여전히 이어지며, `CLAUDE_DISABLE_ADOPT`는 두 가지를 모두 끕니다. Claude Code v2.1.196 이상이 필요합니다 |253| `CLAUDE_CODE_DISABLE_BG_EXIT_HANDOFF` | `1`로 설정하면 [슈퍼바이저](/docs/ko/agent-view#the-supervisor-process)가 [백그라운드 세션](/docs/ko/agent-view)의 프로세스를 중지, 재시작 또는 업데이트할 때 해당 세션에서 실행 중인 백그라운드 셸 명령, 동적 워크플로, 그리고 v2.1.198부터는 백그라운드 서브에이전트를 세션의 다음 프로세스로 넘기지 않고 중지합니다. 이 인계에만 영향을 줍니다. `←` 또는 [`/background`](/docs/ko/agent-view#from-inside-a-session)로 세션을 백그라운드로 전환하면 진행 중인 작업이 여전히 이어지며, `CLAUDE_DISABLE_ADOPT`는 둘 다 끕니다. Claude Code v2.1.196 이상이 필요합니다 |

254| `CLAUDE_CODE_DISABLE_BG_SHELL_PRESSURE_REAP` | `1`로 설정하면 메모리 압박 상황에서 Claude Code가 [백그라운드 셸 명령](/docs/ko/interactive-mode#background-bash-commands)을 종료하지 않습니다. 기본적으로 macOS와 Linux에서 Claude Code는 운영 체제가 심각한 메모리 압박을 보고하고, 세션이 실행 중인 턴이나 서브에이전트 없이 30분간 유휴 상태일 때 백그라운드 셸을 종료합니다. Windows에는 메모리 압박 신호가 없으므로 이 변수는 효과가 없습니다. Claude Code v2.1.193 이상이 필요합니다 |254| `CLAUDE_CODE_DISABLE_BG_SHELL_PRESSURE_REAP` | `1`로 설정하면 메모리 부족 상황에서 Claude Code가 [백그라운드 셸 명령](/docs/ko/interactive-mode#background-bash-commands)을 종료하지 않습니다. 기본적으로 macOS와 Linux에서 Claude Code는 운영 체제가 심각한 메모리 부족을 보고하고 세션이 턴이나 서브에이전트 실행 없이 30분 동안 유휴 상태였을 때 백그라운드 셸을 종료합니다. Windows에는 메모리 부족 신호가 없으므로 이 변수는 효과가 없습니다. Claude Code v2.1.193 이상이 필요합니다 |

255| `CLAUDE_CODE_DISABLE_BUNDLED_SKILLS` | `1`로 설정하면 Claude Code에 포함된 [스킬](/docs/ko/skills)과 워크플로를 비활성화합니다. 번들 스킬과 워크플로는 완전히 제거되며, `/init`과 같은 기본 제공 명령은 계속 입력할 수 있지만 모델에게는 숨겨집니다. `/doctor`는 기본 제공 명령처럼 계속 입력할 수 있으며, 숨기려면 대신 `DISABLE_DOCTOR_COMMAND`를 사용하십시오. 플러그인, `.claude/skills/`, `.claude/commands/`의 스킬은 영향을 받지 않습니다. [`disableBundledSkills`](/docs/ko/settings-reference#disablebundledskills) 설정과 동일합니다 |255| `CLAUDE_CODE_DISABLE_BUNDLED_SKILLS` | `1`로 설정하면 Claude Code에 포함된 [스킬](/docs/ko/skills)과 워크플로를 비활성화합니다. 번들 스킬과 워크플로는 완전히 제거되고, `/init`과 같은 기본 제공 명령은 계속 입력할 수 있지만 모델에게는 숨겨집니다. `/doctor`는 기본 제공 명령처럼 계속 입력할 수 있으며, 숨기려면 대신 `DISABLE_DOCTOR_COMMAND`를 사용합니다. 플러그인, `.claude/skills/`, `.claude/commands/`의 스킬은 영향을 받지 않습니다. [`disableBundledSkills`](/docs/ko/settings-reference#disablebundledskills) 설정과 동일합니다 |

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

258| `CLAUDE_CODE_DISABLE_CRON` | `1`로 설정하면 [예약 작업](/docs/ko/scheduled-tasks)을 비활성화합니다. `/loop` 스킬과 cron 도구를 사용할 수 없게 되며, 세션 도중 이미 실행 중인 작업을 포함해 이미 예약된 작업이 더 이상 실행되지 않습니다 |258| `CLAUDE_CODE_DISABLE_CRON` | `1`로 설정하면 [예약 작업](/docs/ko/scheduled-tasks)을 비활성화합니다. `/loop` 스킬과 cron 도구를 사용할 수 없게 되고, 세션 도중 이미 실행 중인 작업을 포함하여 이미 예약된 작업의 실행이 중지됩니다 |

259| `CLAUDE_CODE_DISABLE_DANGEROUS_RM_TIMEOUT` | `1`로 설정하면 [중요 경로 삭제](/docs/ko/permission-modes#critical-paths) 프롬프트의 시간 제한을 끕니다. 그러면 `auto` 모드에서는 Claude Code가 이러한 삭제를 대신 분류기로 보내고, `bypassPermissions` 모드에서는 프롬프트가 사용자의 응답을 기다립니다. Claude Code는 설정 `env` 블록을 통해 전달된 값을 무시하므로, Claude Code를 실행하는 환경에서 설정하십시오. Claude Code v2.1.281 이상이 필요합니다 |259| `CLAUDE_CODE_DISABLE_DANGEROUS_RM_TIMEOUT` | `1`로 설정하면 [중요 경로 삭제](/docs/ko/permission-modes#critical-paths) 프롬프트의 시간 제한을 끕니다. 그러면 `auto` 모드에서는 Claude Code가 이러한 삭제를 대신 분류기로 보내고, `bypassPermissions` 모드에서는 프롬프트가 사용자의 응답을 기다립니다. Claude Code는 설정의 `env` 블록을 통해 전달된 값을 무시하므로 Claude Code를 실행하는 환경에서 설정합니다. Claude Code v2.1.281 이상이 필요합니다 |

260| `CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS` | `1`로 설정하면 API 요청에서 출시 전 `anthropic-beta` 요청 헤더, 이와 짝을 이루는 본문 필드, `defer_loading` 및 `eager_input_streaming`과 같은 베타 도구 스키마 필드를 제거합니다. 프록시 게이트웨이가 `anthropic-beta` 헤더에 대해 `Unexpected value(s)` 오류나 `Extra inputs are not permitted` 오류로 요청을 거부할 때 사용하십시오. [출시 전 기능 비활성화](/docs/ko/llm-gateway-protocol#disable-pre-release-capabilities)에 [MCP 도구 검색](/docs/ko/mcp#scale-with-mcp-tool-search)을 포함해 이 변수가 제거하는 항목과 Claude Code가 계속 전송하는 항목이 나와 있습니다 |260| `CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS` | `1`로 설정하면 API 요청에서 사전 릴리스 `anthropic-beta` 요청 헤더, 이와 짝을 이루는 본문 필드, `defer_loading` 및 `eager_input_streaming`과 같은 베타 도구 스키마 필드를 제거합니다. 프록시 게이트웨이가 `anthropic-beta` 헤더에 대해 `Unexpected value(s)` 오류 또는 `Extra inputs are not permitted` 오류로 요청을 거부할 때 사용합니다. [사전 릴리스 기능 비활성화](/docs/ko/llm-gateway-protocol#disable-pre-release-capabilities)에 [MCP 도구 검색](/docs/ko/mcp#scale-with-mcp-tool-search)을 포함하여 이 변수가 제거하는 항목과 Claude Code가 계속 전송하는 항목이 나와 있습니다 |

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

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

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

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

266| `CLAUDE_CODE_DISABLE_LEGACY_MODEL_REMAP` | `1`로 설정하면 Anthropic API에서 Opus 4.0 및 4.1이 현재 Opus 버전으로 자동 재매핑되지 않습니다. 의도적으로 이전 모델을 고정하려는 경우 사용하십시오. 재매핑은 Amazon Bedrock, Google Cloud's Agent Platform, Microsoft Foundry에서는 실행되지 않습니다 |266| `CLAUDE_CODE_DISABLE_INLINE_SHELL_RM_PROMPT` | `1`로 설정하면 Claude Code가 `bash -c 'rm -rf ~'`처럼 `-c`로 셸에 전달된 스크립트에서 [중요 경로](/docs/ko/permission-modes#removals-inside-nested-commands-and-inline-scripts) 삭제를 읽지 않습니다. Claude Code는 이러한 스크립트의 셸 변수 및 위치 매개변수 대상은 계속 확인하며, 다른 중요 경로 검사도 계속 실행됩니다. Claude Code는 설정의 `env` 블록을 통해 전달된 값을 무시하므로 Claude Code를 실행하는 환경에서 설정합니다. Claude Code v2.1.288 이상이 필요합니다 |

267| `CLAUDE_CODE_DISABLE_MODEL_ACCESS_FALLBACK` | `1`로 설정하면 [Amazon Bedrock](/docs/ko/amazon-bedrock#when-a-model-is-disabled-mid-session) 및 [Google Cloud's Agent Platform](/docs/ko/google-vertex-ai#when-a-model-is-disabled-mid-session)에서 세션 도중 계정이 세션 모델에 대한 액세스를 잃었을 때 Claude Code가 이전 모델로 전환하지 않으며, 거부된 요청은 즉시 실패합니다. 직접 구성한 [폴백 모델 체인](/docs/ko/model-config#fallback-model-chains)은 해당 거부 시에도 여전히 전환되며, [시작 시 모델 검사](/docs/ko/amazon-bedrock#startup-model-checks)도 실행 시점에 여전히 폴백합니다. Claude Code v2.1.285 이상이 필요합니다 |267| `CLAUDE_CODE_DISABLE_LEGACY_MODEL_REMAP` | `1`로 설정하면 Anthropic API에서 Opus 4.0 및 4.1이 현재 Opus 버전으로 자동 재매핑되지 않도록 합니다. 의도적으로 이전 모델을 고정하려는 경우 사용합니다. 재매핑은 Amazon Bedrock, Google Cloud's Agent Platform, Microsoft Foundry에서는 실행되지 않습니다 |

268| `CLAUDE_CODE_DISABLE_MOUSE` | `1`로 설정하면 [전체 화면 렌더링](/docs/ko/fullscreen)에서 마우스 추적을 비활성화합니다. `PgUp`과 `PgDn`을 사용한 키보드 스크롤은 계속 작동합니다. 터미널의 기본 선택 시 복사 동작을 유지하려면 이 변수를 사용하십시오 |268| `CLAUDE_CODE_DISABLE_MODEL_ACCESS_FALLBACK` | `1`로 설정하면 [Amazon Bedrock](/docs/ko/amazon-bedrock#when-a-model-is-disabled-mid-session)과 [Google Cloud's Agent Platform](/docs/ko/google-vertex-ai#when-a-model-is-disabled-mid-session)에서 세션 도중 계정이 세션 모델에 대한 액세스 권한을 잃었을 때 Claude Code가 이전 모델로 전환하지 않으며, 거부된 요청이 즉시 실패합니다. 직접 구성한 [폴백 모델 체인](/docs/ko/model-config#fallback-model-chains)은 해당 거부 시 여전히 전환되며, [시작 시 모델 확인](/docs/ko/amazon-bedrock#startup-model-checks)은 실행 시점에 여전히 폴백합니다. Claude Code v2.1.285 이상이 필요합니다 |

269| `CLAUDE_CODE_DISABLE_MOUSE_CLICKS` | `1`로 설정하면 [전체 화면 렌더링](/docs/ko/fullscreen)에서 마우스 휠 스크롤은 유지하면서 클릭, 드래그, 호버 처리를 비활성화합니다. Claude Code 내에서 휠 스크롤은 작동하되 클릭으로 커서를 배치하거나 도구 출력을 펼치거나 링크를 열지 않도록 하려는 경우 사용하십시오. 둘 다 설정되면 `CLAUDE_CODE_DISABLE_MOUSE`가 우선합니다. Claude Code v2.1.195 이상이 필요합니다 |269| `CLAUDE_CODE_DISABLE_MOUSE` | `1`로 설정하면 [전체 화면 렌더링](/docs/ko/fullscreen)에서 마우스 추적을 비활성화합니다. `PgUp`과 `PgDn`을 사용한 키보드 스크롤은 계속 작동합니다. 터미널의 기본 선택 시 복사 동작을 유지하려면 이 변수를 사용합니다 |

270| `CLAUDE_CODE_DISABLE_MOUSE_CLICKS` | `1`로 설정하면 [전체 화면 렌더링](/docs/ko/fullscreen)에서 마우스 휠 스크롤은 유지하면서 클릭, 드래그, 호버 처리를 비활성화합니다. Claude Code 안에서 휠 스크롤은 작동하되 클릭으로 커서를 배치하거나 도구 출력을 펼치거나 링크를 열지 않으려는 경우 사용합니다. 둘 다 설정된 경우 `CLAUDE_CODE_DISABLE_MOUSE`가 우선합니다. Claude Code v2.1.195 이상이 필요합니다 |

270| `CLAUDE_CODE_DISABLE_MTLS_RELOAD_ON_STALE_CONNECTION` | `1`로 설정하면 연결 재설정이나 TLS 핸드셰이크 오류와 같은 연결 수준 오류로 API 요청이 실패할 때 Claude Code가 [mTLS 클라이언트 인증서와 키](/docs/ko/network-config#mtls-authentication)를 다시 읽지 않습니다. 다시 읽기가 비활성화되면 Claude Code는 다음에 설정을 적용할 때나 다음 시작 시에만 교체된 파일을 로드합니다. Claude Code v2.1.232 이상이 필요합니다 |271| `CLAUDE_CODE_DISABLE_MTLS_RELOAD_ON_STALE_CONNECTION` | `1`로 설정하면 연결 재설정이나 TLS 핸드셰이크 오류와 같은 연결 수준 오류로 API 요청이 실패할 때 Claude Code가 [mTLS 클라이언트 인증서와 키](/docs/ko/network-config#mtls-authentication)를 다시 읽지 않습니다. 다시 읽기가 비활성화되면 Claude Code는 다음에 설정을 적용할 때나 다음 시작 시에만 교체된 파일을 로드합니다. Claude Code v2.1.232 이상이 필요합니다 |

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

272| `CLAUDE_CODE_DISABLE_NONSTREAMING_FALLBACK` | `1`로 설정하면 스트리밍 요청이 스트림 도중 실패할 때 비스트리밍 폴백을 비활성화합니다. 스트리밍 오류는 대신 재시도 계층으로 전파됩니다. 프록시나 게이트웨이로 인해 폴백이 도구를 중복 실행하는 경우에 유용합니다 |273| `CLAUDE_CODE_DISABLE_NONSTREAMING_FALLBACK` | `1`로 설정하면 스트리밍 요청이 스트림 도중 실패할 때의 비스트리밍 폴백을 비활성화합니다. 대신 스트리밍 오류가 재시도 계층으로 전파됩니다. 프록시나 게이트웨이로 인해 폴백이 도구를 중복 실행하는 경우에 유용합니다 |

273| `CLAUDE_CODE_DISABLE_NOTIFICATION_PRESENCE_CHECK` | `1`로 설정하면 사용자가 터미널에서 입력 중이거나 터미널에 포커스가 있는 동안에도 `PushNotification` 도구의 데스크톱 알림을 전송합니다. 기본적으로 이 도구는 최근 키보드 활동이나 터미널 포커스를 감지하면 데스크톱 알림과 [모바일 푸시](/docs/ko/remote-control#mobile-push-notifications)를 모두 건너뜁니다. 이 변수는 해당 로컬 검사만 비활성화하므로, 서버는 사용자가 활동 중임을 감지하면 여전히 모바일 푸시를 억제할 수 있습니다. Claude Code v2.1.193 이상이 필요합니다 |274| `CLAUDE_CODE_DISABLE_NOTIFICATION_PRESENCE_CHECK` | `1`로 설정하면 터미널에서 입력 중이거나 터미널에 포커스가 있는 동안에도 `PushNotification` 도구의 데스크톱 알림을 전송합니다. 기본적으로 이 도구는 최근 키보드 활동이나 터미널 포커스를 감지하면 데스크톱 알림과 [모바일 푸시](/docs/ko/remote-control#mobile-push-notifications)를 모두 건너뜁니다. 이 변수는 해당 로컬 검사만 비활성화하므로, 서버는 사용자가 활동 중임을 감지하면 여전히 모바일 푸시를 억제할 수 있습니다. Claude Code v2.1.193 이상이 필요합니다 |

274| `CLAUDE_CODE_DISABLE_OFFICIAL_MARKETPLACE_AUTOINSTALL` | `1`로 설정하면 공식 플러그인 마켓플레이스의 자동 등록을 비활성화합니다. Claude Code는 마켓플레이스를 등록하려는 시점, 보통 컴퓨터에서 처음 대화형으로 실행할 때 이 변수를 읽습니다. 그 시점에 변수가 설정되어 있으면 Claude Code는 등록을 영구적으로 건너뜁니다. 나중에 변수를 설정 해제해도 건너뛴 상태는 되돌려지지 않습니다. 언제든지 마켓플레이스를 등록하려면 `claude plugin marketplace add anthropics/claude-plugins-official`을 실행하십시오 |275| `CLAUDE_CODE_DISABLE_OFFICIAL_MARKETPLACE_AUTOINSTALL` | `1`로 설정하면 공식 플러그인 마켓플레이스의 자동 등록을 비활성화합니다. Claude Code는 마켓플레이스를 등록하려는 시점, 보통 머신의 첫 대화형 실행 중에 이 변수를 읽습니다. 그 시점에 변수가 설정되어 있으면 Claude Code는 등록을 영구적으로 건너뜁니다. 나중에 변수를 설정 해제해도 건너뛴 것이 취소되지 않습니다. 언제든지 마켓플레이스를 등록하려면 `claude plugin marketplace add anthropics/claude-plugins-official`을 실행합니다 |

275| `CLAUDE_CODE_DISABLE_PERMISSION_PROMPT_NOTIFY_HOOKS` | `1`로 설정하면 Claude Code가 권한 요청을 Agent SDK의 `canUseTool` 콜백으로 보내는 세션(Claude Desktop과 VS Code 확장 프로그램이 Claude Code를 호스팅하는 방식)에서 [응답하지 않은 권한 요청에 대한 `Notification` 훅](/docs/ko/hooks#notification)을 실행하지 않습니다. 터미널 세션에서는 효과가 없습니다. Claude Code v2.1.233 이상이 필요합니다 |276| `CLAUDE_CODE_DISABLE_PERMISSION_PROMPT_NOTIFY_HOOKS` | `1`로 설정하면 Claude Code가 권한 요청을 Agent SDK의 `canUseTool` 콜백으로 보내는 세션에서 [응답하지 않은 권한 요청에 대한 `Notification` 훅](/docs/ko/hooks#notification)을 실행하지 않습니다. Claude Desktop과 VS Code 확장 프로그램이 이 방식으로 Claude Code를 호스팅합니다. 터미널 세션에서는 효과가 없습니다. Claude Code v2.1.233 이상이 필요합니다 |

276| `CLAUDE_CODE_DISABLE_POLICY_SKILLS` | `1`로 설정하면 시스템 전체 관리형 스킬 디렉터리에서 스킬을 로드하지 않습니다. 운영자가 프로비저닝한 스킬을 로드하지 않아야 하는 컨테이너 또는 CI 세션에 유용합니다 |277| `CLAUDE_CODE_DISABLE_POLICY_SKILLS` | `1`로 설정하면 시스템 전체 관리형 스킬 디렉터리에서 스킬을 로드하지 않습니다. 운영자가 프로비저닝한 스킬을 로드하지 않아야 하는 컨테이너 또는 CI 세션에 유용합니다 |

277| `CLAUDE_CODE_DISABLE_POWERSHELL_CMD_RM_DENY` | `1`로 설정하면 드라이브 루트나 홈 디렉터리와 같은 [시스템 경로](/docs/ko/permission-modes#remove-item-in-powershell)에서 `cmd` 내장 명령 `rd`, `rmdir`, `del`, `erase`를 거부하는 [PowerShell 도구](/docs/ko/tools-reference#powershell-tool) 검사를 끕니다. Claude Code는 설정 파일의 `env` 블록에 있는 이 변수를 무시합니다. Claude Code v2.1.283 이상이 필요합니다 |278| `CLAUDE_CODE_DISABLE_POWERSHELL_CMD_RM_DENY` | `1`로 설정하면 드라이브 루트나 홈 디렉터리와 같은 [시스템 경로](/docs/ko/permission-modes#remove-item-in-powershell)에서 `cmd` 기본 제공 명령 `rd`, `rmdir`, `del`, `erase`를 거부하는 [PowerShell 도구](/docs/ko/tools-reference#powershell-tool) 검사를 끕니다. Claude Code는 설정 파일의 `env` 블록에 있는 이 변수를 무시합니다. Claude Code v2.1.283 이상이 필요합니다 |

278| `CLAUDE_CODE_DISABLE_STRUCTURED_OUTPUTS` | `1`로 설정하면 업스트림이 구조화된 출력 `output_config.format` 필드와 이와 짝을 이루는 `anthropic-beta` 값을 거부하는 [LLM 게이트웨이](/docs/ko/llm-gateway-protocol#feature-pass-through)를 위해 Claude Code가 이를 전송하지 않습니다. [`CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS`](/docs/ko/llm-gateway-protocol#disable-pre-release-capabilities)가 끄는 다른 출시 전 기능은 켜진 상태로 유지됩니다. Claude Code v2.1.288 이상이 필요합니다 |279| `CLAUDE_CODE_DISABLE_REFUSAL_FALLBACK` | `1`로 설정하면 [`switchModelsOnFlag`](/docs/ko/settings-reference#switchmodelsonflag) 설정이 제어하는 동작인 [안전 분류기가 요청을 플래그할 때의 자동 모델 전환](/docs/ko/model-config#automatic-model-fallback)을 끕니다 |

279| `CLAUDE_CODE_DISABLE_SUBSTITUTION_RM_PROMPT` | `1`로 설정하면 `rm -rf "$(pwd)"`처럼 대상 전체가 명령 치환의 출력인 재귀적 `rm`에 대한 [중요 경로](/docs/ko/permission-modes#critical-paths) 검사를 끕니다. 다른 중요 경로 검사는 계속 실행됩니다. Claude Code는 설정 `env` 블록을 통해 전달된 값을 무시하므로, Claude Code를 실행하는 환경에서 설정하십시오. Claude Code v2.1.281 이상이 필요합니다 |280| `CLAUDE_CODE_DISABLE_STRUCTURED_OUTPUTS` | `1`로 설정하면 업스트림이 구조화된 출력 `output_config.format` 필드와 이와 짝을 이루는 `anthropic-beta` 값을 거부하는 [LLM 게이트웨이](/docs/ko/llm-gateway-protocol#feature-pass-through)를 위해 Claude Code가 이들을 전송하지 않습니다. [`CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS`](/docs/ko/llm-gateway-protocol#disable-pre-release-capabilities)가 끄는 다른 사전 릴리스 기능은 켜진 상태로 유지됩니다. Claude Code v2.1.288 이상이 필요합니다 |

280| `CLAUDE_CODE_DISABLE_TERMINAL_TITLE` | `1`로 설정하면 대화 컨텍스트에 기반한 터미널 제목 자동 업데이트를 비활성화합니다. 이 설정은 [세션 제목을 생성하는](/docs/ko/sessions#name-your-sessions) 백그라운드 small/fast 모델 요청도 건너뜁니다 |281| `CLAUDE_CODE_DISABLE_SUBSTITUTION_RM_PROMPT` | `1`로 설정하면 `rm -rf "$(pwd)"`처럼 대상 전체가 명령 치환의 출력인 재귀 `rm`에 대한 [중요 경로](/docs/ko/permission-modes#critical-paths) 검사를 끕니다. 다른 중요 경로 검사는 계속 실행됩니다. Claude Code는 설정의 `env` 블록을 통해 전달된 값을 무시하므로 Claude Code를 실행하는 환경에서 설정합니다. Claude Code v2.1.281 이상이 필요합니다 |

281| `CLAUDE_CODE_DISABLE_THINKING` | `1`로 설정하면 API 요청에서 `thinking` 매개변수를 완전히 생략합니다. 이는 해당 매개변수를 거부하는 프록시와 게이트웨이를 위한 호환성 옵션입니다. 기본적으로 사고하는 모델에서는 매개변수를 생략해도 모델이 여전히 사고할 수 있습니다. Anthropic API에서 [확장 사고](https://platform.claude.com/docs/en/build-with-claude/extended-thinking)를 명시적으로 비활성화하려면 대신 `MAX_THINKING_TOKENS=0`을 사용하십시오. 사고를 끌 수 없는 Opus 5.5, Sonnet 5.5, Fable 모델에서는 두 변수 모두 사고를 끄지 않습니다. [서드파티 제공업체](/docs/ko/third-party-integrations)에서는 `MAX_THINKING_TOKENS=0`도 마찬가지로 매개변수를 생략하므로, 두 변수가 동일하게 동작합니다 |282| `CLAUDE_CODE_DISABLE_TERMINAL_TITLE` | `1`로 설정하면 대화 컨텍스트에 기반한 자동 터미널 제목 업데이트를 비활성화합니다. [세션 제목을 생성하는](/docs/ko/sessions#name-your-sessions) 백그라운드 small/fast 모델 요청도 건너뜁니다 |

282| `CLAUDE_CODE_DISABLE_UNKNOWN_MODEL_WINDOW_ENFORCEMENT` | `1`로 설정하면 [LLM 게이트웨이](/docs/ko/llm-gateway) 별칭처럼 Claude Code가 모델 ID를 인식하지 못할 때 선제적 [자동 압축](/docs/ko/costs#reduce-token-usage)을 건너뜁니다. 이 변수가 없으면 Claude Code는 해당 ID에 대해 가정한 컨텍스트 윈도우에서 압축합니다. 대신 `CLAUDE_CODE_MAX_CONTEXT_TOKENS`로 가정된 윈도우를 수정할 수 있습니다. 각 변수가 적용되는 경우는 [게이트웨이 또는 사용자 지정 모델 ID의 윈도우 수정](/docs/ko/model-config#correct-the-window-for-a-gateway-or-custom-model-id)을 참조하십시오. Claude Code v2.1.223 이상이 필요합니다 |283| `CLAUDE_CODE_DISABLE_THINKING` | `1`로 설정하면 API 요청에서 `thinking` 파라미터를 완전히 생략합니다. 이 파라미터를 거부하는 프록시와 게이트웨이를 위한 호환성 옵션입니다. 기본적으로 사고하는 모델에서는 파라미터를 생략해도 모델이 여전히 사고할 수 있습니다. Anthropic API에서 [확장 사고](https://platform.claude.com/docs/en/build-with-claude/extended-thinking)를 명시적으로 비활성화하려면 대신 `MAX_THINKING_TOKENS=0`을 사용합니다. 사고를 끌 수 없는 Opus 5.5, Sonnet 5.5, Fable 모델에서는 어느 변수도 사고를 끄지 않습니다. [서드 파티 공급자](/docs/ko/third-party-integrations)에서는 `MAX_THINKING_TOKENS=0`도 마찬가지로 파라미터를 생략하므로, 두 변수가 동일하게 동작합니다 |

283| `CLAUDE_CODE_DISABLE_VIRTUAL_SCROLL` | `1`로 설정하면 [전체 화면 렌더링](/docs/ko/fullscreen)에서 가상 스크롤을 비활성화하고 트랜스크립트의 모든 메시지를 렌더링합니다. 전체 화면 모드에서 스크롤할 때 메시지가 표시되어야 할 곳에 빈 영역이 나타나는 경우 사용하십시오 |284| `CLAUDE_CODE_DISABLE_UNKNOWN_MODEL_WINDOW_ENFORCEMENT` | `1`로 설정하면 [LLM 게이트웨이](/docs/ko/llm-gateway) 별칭처럼 Claude Code가 모델 ID를 인식하지 못할 때 선제적 [자동 압축](/docs/ko/costs#reduce-token-usage)을 건너뜁니다. 이 변수가 없으면 Claude Code는 해당 ID에 대해 가정한 컨텍스트 윈도우에서 압축합니다. 대신 `CLAUDE_CODE_MAX_CONTEXT_TOKENS`로 가정된 윈도우를 보정할 수 있습니다. 각 변수가 적용되는 경우는 [게이트웨이 또는 사용자 지정 모델 ID의 윈도우 보정](/docs/ko/model-config#correct-the-window-for-a-gateway-or-custom-model-id)을 참조하세요. Claude Code v2.1.223 이상이 필요합니다 |

285| `CLAUDE_CODE_DISABLE_VIRTUAL_SCROLL` | `1`로 설정하면 [전체 화면 렌더링](/docs/ko/fullscreen)에서 가상 스크롤을 비활성화하고 트랜스크립트의 모든 메시지를 렌더링합니다. 전체 화면 모드에서 스크롤할 때 메시지가 표시되어야 할 위치에 빈 영역이 보이면 이 변수를 사용합니다 |

284| `CLAUDE_CODE_DISABLE_WEB_FETCH` | `1`로 설정하면 [WebFetch](/docs/ko/tools-reference#webfetch-tool-behavior) 도구를 끕니다. [WebSearch](/docs/ko/tools-reference#websearch-tool-behavior) 도구는 계속 사용할 수 있습니다. Claude Code v2.1.285 이상이 필요합니다 |286| `CLAUDE_CODE_DISABLE_WEB_FETCH` | `1`로 설정하면 [WebFetch](/docs/ko/tools-reference#webfetch-tool-behavior) 도구를 끕니다. [WebSearch](/docs/ko/tools-reference#websearch-tool-behavior) 도구는 계속 사용할 수 있습니다. Claude Code v2.1.285 이상이 필요합니다 |

285| `CLAUDE_CODE_DISABLE_WINDOWS_SHELL_LAUNCHER` | `1`로 설정하면 Windows에서 [PowerShell 도구](/docs/ko/tools-reference#powershell-tool) 명령을 `cmd.exe` 런처를 거치지 않고 직접 시작합니다. 기본적으로 런처는 [세션을 백그라운드로 전환](/docs/ko/agent-view#from-inside-a-session)할 때처럼 [백그라운드에서 실행 중인](/docs/ko/tools-reference#background-commands) PowerShell 명령이 [세션의 다음 프로세스로 이어지도록](/docs/ko/agent-view#the-supervisor-process) 합니다. 이 변수를 설정하면 백그라운드로 전환된 PowerShell 명령은 세션의 프로세스가 종료될 때 중지됩니다. Bash 명령은 영향을 받지 않습니다. Claude Code v2.1.269 이상이 필요합니다 |287| `CLAUDE_CODE_DISABLE_WINDOWS_SHELL_LAUNCHER` | `1`로 설정하면 Windows에서 [PowerShell 도구](/docs/ko/tools-reference#powershell-tool) 명령을 `cmd.exe` 런처를 거치지 않고 직접 시작합니다. 기본적으로 런처는 [세션을 백그라운드로 전환](/docs/ko/agent-view#from-inside-a-session)할 때처럼 [백그라운드에서 실행 중인](/docs/ko/tools-reference#background-commands) PowerShell 명령이 [세션의 다음 프로세스로 이어지도록](/docs/ko/agent-view#the-supervisor-process) 합니다. 이 변수를 설정하면 백그라운드로 전환된 PowerShell 명령은 세션의 프로세스가 종료될 때 중지됩니다. Bash 명령은 영향을 받지 않습니다. Claude Code v2.1.269 이상이 필요합니다 |

286| `CLAUDE_CODE_DISABLE_WORKFLOWS` | `1`로 설정하면 [워크플로](/docs/ko/workflows#turn-workflows-off)를 비활성화합니다. [`disableWorkflows`](/docs/ko/settings-reference#disableworkflows) 설정과 동일합니다 |288| `CLAUDE_CODE_DISABLE_WORKFLOWS` | `1`로 설정하면 [워크플로](/docs/ko/workflows#turn-workflows-off)를 비활성화합니다. [`disableWorkflows`](/docs/ko/settings-reference#disableworkflows) 설정과 동일합니다 |

287| `CLAUDE_CODE_EFFORT_LEVEL` | 지원되는 모델의 effort 수준을 설정합니다. 값: `low`, `medium`, `high`, `xhigh`, `max`, 또는 모델 기본값을 사용하려면 `auto`. 사용 가능한 수준은 모델에 따라 다릅니다. `--effort`, `/effort`, `modelSettings` 및 `effortLevel` 설정보다 우선합니다. [`maxEffortLevel`](/docs/ko/settings-reference#maxeffortlevel) 상한은 계속 적용됩니다. [effort 수준 조정](/docs/ko/model-config#adjust-effort-level)을 참조하십시오 |289| `CLAUDE_CODE_EFFORT_LEVEL` | 지원되는 모델의 effort 수준을 설정합니다. 값: `low`, `medium`, `high`, `xhigh`, `max`, 또는 모델 기본값을 사용하려면 `auto`. 사용 가능한 수준은 모델에 따라 다릅니다. `--effort`, `/effort`, `modelSettings` 및 `effortLevel` 설정보다 우선합니다. [`maxEffortLevel`](/docs/ko/settings-reference#maxeffortlevel) 상한은 여전히 적용됩니다. [effort 수준 조정](/docs/ko/model-config#adjust-effort-level)을 참조하세요 |

288| `CLAUDE_CODE_ENABLE_AUTO_MODE` | 이전 릴리스와의 호환성을 위해 허용되며 효과는 없습니다. 자동 모드는 Amazon Bedrock, Google Cloud's Agent Platform, Microsoft Foundry, 로그인한 [Claude apps gateway](/docs/ko/claude-apps-gateway) 세션을 포함한 모든 제공업체에서 기본적으로 사용할 수 있습니다. v2.1.158부터 v2.1.206까지는 해당 제공업체에서 [자동 모드](/docs/ko/permission-modes#eliminate-prompts-with-auto-mode)를 사용하려면 이 값을 `1`로 설정해야 했습니다 |290| `CLAUDE_CODE_ENABLE_AUTO_MODE` | 이전 릴리스와의 호환성을 위해 허용되며 아무 효과가 없습니다. 자동 모드는 Amazon Bedrock, Google Cloud's Agent Platform, Microsoft Foundry, 로그인된 [Claude apps gateway](/docs/ko/claude-apps-gateway) 세션을 포함한 모든 공급자에서 기본적으로 사용할 수 있습니다. v2.1.158부터 v2.1.206까지는 해당 공급자에서 [자동 모드](/docs/ko/permission-modes#eliminate-prompts-with-auto-mode)를 사용하려면 이 값을 `1`로 설정해야 했습니다 |

289| `CLAUDE_CODE_ENABLE_AWAY_SUMMARY` | [세션 요약](/docs/ko/interactive-mode#session-recap) 사용 가능 여부를 재정의합니다. `/config` 토글과 관계없이 요약을 강제로 끄려면 `0`으로 설정하십시오. [`awaySummaryEnabled`](/docs/ko/settings-reference#awaysummaryenabled)가 `false`일 때 요약을 강제로 켜려면 `1`로 설정하십시오. 해당 설정과 `/config` 토글보다 우선합니다 |291| `CLAUDE_CODE_ENABLE_AWAY_SUMMARY` | [세션 요약](/docs/ko/interactive-mode#session-recap) 사용 여부를 재정의합니다. `/config` 토글과 관계없이 요약을 강제로 끄려면 `0`으로 설정합니다. [`awaySummaryEnabled`](/docs/ko/settings-reference#awaysummaryenabled)가 `false`일 때 요약을 강제로 켜려면 `1`로 설정합니다. 설정 및 `/config` 토글보다 우선합니다 |

290| `CLAUDE_CODE_ENABLE_BACKGROUND_PLUGIN_REFRESH` | 백그라운드 설치가 완료된 후 [비대화형 모드](/docs/ko/headless)에서 턴 경계마다 플러그인 상태를 새로 고치려면 `1`로 설정합니다. 새로 고침이 세션 도중에 시스템 프롬프트를 변경하여 해당 턴의 [프롬프트 캐싱](/docs/ko/prompt-caching)을 무효화하므로 기본적으로 꺼져 있습니다 |292| `CLAUDE_CODE_ENABLE_BACKGROUND_PLUGIN_REFRESH` | 백그라운드 설치가 완료된 후 [비대화형 모드](/docs/ko/headless)에서 턴 경계마다 플러그인 상태를 새로 고치려면 `1`로 설정합니다. 새로 고침은 세션 도중 시스템 프롬프트를 변경하여 해당 턴의 [프롬프트 캐싱](/docs/ko/prompt-caching)을 무효화하므로 기본적으로 꺼져 있습니다 |

291| `CLAUDE_CODE_ENABLE_FEEDBACK_SURVEY_FOR_OTEL` | Anthropic으로 향하는 필수적이지 않은 트래픽이 차단된 경우 "How is Claude doing?" 세션 품질 설문을 자체 [OpenTelemetry 수집기](/docs/ko/monitoring-usage)로 라우팅하려면 `1`로 설정합니다. 설문 평가는 구성된 수집기에 OTEL 이벤트로만 내보내집니다. 이 모드에서는 설문 데이터가 Anthropic으로 전송되지 않습니다. `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC`, `DISABLE_TELEMETRY` 또는 `DO_NOT_TRACK`이 설정된 경우에 적용되며, 그 외에는 효과가 없습니다. `CLAUDE_CODE_DISABLE_FEEDBACK_SURVEY`와 조직의 제품 피드백 정책이 우선합니다 |293| `CLAUDE_CODE_ENABLE_FEEDBACK_SURVEY_FOR_OTEL` | Anthropic으로 향하는 필수가 아닌 트래픽이 차단된 경우 "How is Claude doing?" 세션 품질 설문을 자체 [OpenTelemetry 수집기](/docs/ko/monitoring-usage)로 라우팅하려면 `1`로 설정합니다. 설문 평가는 구성된 수집기로 OTEL 이벤트로만 전송됩니다. 이 모드에서는 설문 데이터가 Anthropic으로 전송되지 않습니다. `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC`, `DISABLE_TELEMETRY` 또는 `DO_NOT_TRACK`이 설정된 경우에 적용되며, 그 외에는 효과가 없습니다. `CLAUDE_CODE_DISABLE_FEEDBACK_SURVEY`와 조직의 제품 피드백 정책이 우선합니다 |

292| `CLAUDE_CODE_ENABLE_FINE_GRAINED_TOOL_STREAMING` | Claude가 도구 호출 입력을 생성하는 동안 API에서 해당 입력을 스트리밍할지 여부를 제어합니다. 이 기능이 꺼져 있으면 긴 파일 쓰기와 같은 큰 도구 입력은 Claude가 생성을 마친 후에야 도착하므로 멈춘 것처럼 보일 수 있습니다. Anthropic API에서는 기본적으로 활성화됩니다. Amazon Bedrock과 Google Cloud의 Agent Platform에서는 배포된 컨테이너가 지원하는 모델별로 활성화됩니다. 옵트아웃하려면 `0`으로 설정합니다. `ANTHROPIC_BASE_URL`, `ANTHROPIC_VERTEX_BASE_URL` 또는 `ANTHROPIC_BEDROCK_BASE_URL`을 통해 프록시로 라우팅할 때 강제로 켜려면 `1`로 설정합니다. Microsoft Foundry 및 [게이트웨이](/docs/ko/llm-gateway) 연결에서는 기본적으로 꺼져 있습니다 |294| `CLAUDE_CODE_ENABLE_FINE_GRAINED_TOOL_STREAMING` | Claude가 도구 호출 입력을 생성하는 동안 API에서 스트리밍할지 여부를 제어합니다. 이 기능이 꺼져 있으면 긴 파일 쓰기와 같은 큰 도구 입력은 Claude가 생성을 마친 후에야 도착하므로 멈춘 것처럼 보일 수 있습니다. Anthropic API에서는 기본적으로 활성화되어 있습니다. Amazon Bedrock과 Google Cloud's Agent Platform에서는 배포된 컨테이너가 지원하는 모델별로 활성화됩니다. 사용하지 않으려면 `0`으로 설정합니다. `ANTHROPIC_BASE_URL`, `ANTHROPIC_VERTEX_BASE_URL` 또는 `ANTHROPIC_BEDROCK_BASE_URL`을 통해 프록시로 라우팅할 때 강제로 켜려면 `1`로 설정합니다. Microsoft Foundry 및 [게이트웨이](/docs/ko/llm-gateway) 연결에서는 기본적으로 꺼져 있습니다 |

293| `CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY` | `ANTHROPIC_BASE_URL`이 LiteLLM, Kong 또는 내부 프록시와 같은 Anthropic 호환 게이트웨이를 가리킬 때 게이트웨이의 `/v1/models` 엔드포인트에서 `/model` 선택기를 채우려면 `1`로 설정합니다. 그렇지 않으면 공유 API 키를 사용하는 게이트웨이가 해당 키로 접근할 수 있는 모든 모델을 모든 사용자에게 보여 주게 되므로 기본적으로 꺼져 있습니다. 검색된 모델은 여전히 세션이 받는 [`availableModels`](/docs/ko/settings-reference#availablemodels) 허용 목록으로 필터링됩니다. [게이트웨이 구성에서는 서버 관리형 전달을 사용할 수 없으므로](/docs/ko/server-managed-settings#platform-availability) [MDM 또는 관리형 설정 파일](/docs/ko/managed-settings#delivery-mechanisms)을 통해 목록을 전달합니다 |295| `CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY` | `ANTHROPIC_BASE_URL`이 LiteLLM, Kong 또는 내부 프록시와 같은 Anthropic 호환 게이트웨이를 가리킬 때 게이트웨이의 `/v1/models` 엔드포인트에서 `/model` 선택기를 채우려면 `1`로 설정합니다. 공유 API 키를 사용하는 게이트웨이에서는 키가 접근할 수 있는 모든 모델이 모든 사용자에게 표시되므로 기본적으로 꺼져 있습니다. 검색된 모델은 여전히 세션이 받는 [`availableModels`](/docs/ko/settings-reference#availablemodels) 허용 목록으로 필터링됩니다. [게이트웨이 구성에서는 서버 관리형 전달을 사용할 수 없으므로](/docs/ko/server-managed-settings#platform-availability) [MDM 또는 관리형 설정 파일](/docs/ko/managed-settings#delivery-mechanisms)을 통해 목록을 전달하십시오 |

295| `CLAUDE_CODE_ENABLE_PROMPT_SUGGESTION` | 프롬프트 입력에 회색으로 표시되는 예측인 프롬프트 제안을 끄려면 `false`로 설정합니다. `/config`의 **Prompt suggestions** 토글이 기록하는 [`promptSuggestionEnabled`](/docs/ko/settings-reference#promptsuggestionenabled) 설정보다 우선합니다. Claude Code는 또한 [계정이 사용 한도에 가까워지거나 도달하면 제안을 일시 중지합니다](/docs/ko/interactive-mode#when-claude-code-skips-suggestions). 한도에 도달할 때까지 제안을 계속 표시하려면 `true`로 설정합니다. Claude Code v2.1.238 이상이 필요합니다. [프롬프트 제안](/docs/ko/interactive-mode#prompt-suggestions)을 참조하세요 |297| `CLAUDE_CODE_ENABLE_PROMPT_SUGGESTION` | 프롬프트 입력란에 회색으로 표시되는 예측인 프롬프트 제안을 끄려면 `false`로 설정합니다. `/config`의 **Prompt suggestions** 토글이 기록하는 [`promptSuggestionEnabled`](/docs/ko/settings-reference#promptsuggestionenabled) 설정보다 우선합니다. Claude Code는 또한 [계정이 사용 한도에 가까워지거나 도달하면 제안을 일시 중지합니다](/docs/ko/interactive-mode#when-claude-code-skips-suggestions). 한도에 도달할 때까지 제안을 계속 표시하려면 `true`로 설정합니다. Claude Code v2.1.238 이상이 필요합니다. [프롬프트 제안](/docs/ko/interactive-mode#prompt-suggestions)을 참조하십시오 |

296| `CLAUDE_CODE_ENABLE_TASKS` | [작업 추적 도구가 있는 세션](/docs/ko/tools-reference#task-tool-availability)에서 Claude Code가 제공하는 작업 추적 도구를 선택합니다. 기본적으로 Claude Code는 Task 도구인 `TaskCreate`, `TaskUpdate`, `TaskGet`, `TaskList`를 제공합니다. 대신 레거시 `TodoWrite` 도구를 사용하려면 `0`으로 설정합니다. [작업 목록](/docs/ko/interactive-mode#task-list)을 참조하세요 |298| `CLAUDE_CODE_ENABLE_TASKS` | [작업 추적 도구가 있는 세션](/docs/ko/tools-reference#task-tool-availability)에서 Claude Code가 제공할 작업 추적 도구를 선택합니다. 기본적으로 Claude Code는 Task 도구인 `TaskCreate`, `TaskUpdate`, `TaskGet`, `TaskList`를 제공합니다. 대신 레거시 `TodoWrite` 도구를 사용하려면 `0`으로 설정합니다. [작업 목록](/docs/ko/interactive-mode#task-list)을 참조하십시오 |

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

298| `CLAUDE_CODE_ENABLE_TODO_TOOLS` | 모든 모델에서 작업 추적 도구를 사용하려면 `1`로 설정합니다. 이 변수가 없으면 Claude Code는 [Task 도구 가용성](/docs/ko/tools-reference#task-tool-availability)에 나열된 모델에서만 기본적으로 이 도구를 제공합니다. `CLAUDE_CODE_ENABLE_TASKS`는 여전히 Task 도구 또는 `TodoWrite`를 선택합니다. Claude Code v2.1.233 이상이 필요합니다 |300| `CLAUDE_CODE_ENABLE_TODO_TOOLS` | 모든 모델에서 작업 추적 도구를 사용하려면 `1`로 설정합니다. 이 변수가 없으면 Claude Code는 [Task 도구 사용 가능 여부](/docs/ko/tools-reference#task-tool-availability)에 나열된 모델에서만 기본적으로 이 도구를 제공합니다. `CLAUDE_CODE_ENABLE_TASKS`는 여전히 Task 도구와 `TodoWrite` 중 하나를 선택합니다. Claude Code v2.1.233 이상이 필요합니다 |

299| `CLAUDE_CODE_EXIT_AFTER_STOP_DELAY` | 쿼리 루프가 유휴 상태가 된 후 자동으로 종료하기 전에 대기할 시간(밀리초)입니다. SDK 모드를 사용하는 자동화된 워크플로 및 스크립트에 유용합니다 |301| `CLAUDE_CODE_EXIT_AFTER_STOP_DELAY` | 쿼리 루프가 유휴 상태가 된 후 자동으로 종료하기 전까지 대기할 시간(밀리초)입니다. SDK 모드를 사용하는 자동화된 워크플로 및 스크립트에 유용합니다 |

300| `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS` | [에이전트 팀](/docs/ko/agent-teams)을 활성화하려면 `1`로 설정합니다. 에이전트 팀은 실험적 기능이며 기본적으로 비활성화되어 있습니다 |302| `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS` | [에이전트 팀](/docs/ko/agent-teams)을 활성화하려면 `1`로 설정합니다. 에이전트 팀은 실험적 기능이며 기본적으로 비활성화되어 있습니다 |

301| `CLAUDE_CODE_EXTRA_BODY` | 모든 API 요청 본문의 최상위 수준에 병합할 JSON 객체입니다. Claude Code가 직접 노출하지 않는 공급자별 매개변수를 전달하는 데 유용합니다. 셸에서 export한 값은 `claude agents` 또는 `--bg`로 디스패치하는 [백그라운드 세션](/docs/ko/agent-view)에도 적용됩니다. v2.1.206 이전에는 백그라운드 세션이 셸에서 export한 값을 무시하고 백그라운드 감독자 프로세스가 상속한 값을 사용했습니다 |303| `CLAUDE_CODE_EXTRA_BODY` | 모든 API 요청 본문의 최상위 수준에 병합할 JSON 객체입니다. Claude Code가 직접 노출하지 않는 공급자별 매개변수를 전달하는 데 유용합니다. 셸에서 export한 값은 `claude agents` 또는 `--bg`로 디스패치하는 [백그라운드 세션](/docs/ko/agent-view)에도 적용됩니다. v2.1.206 이전에는 백그라운드 세션이 셸에서 export한 값을 무시하고 백그라운드 감독 프로세스가 상속한 값을 사용했습니다 |

303| `CLAUDE_CODE_FORCE_SESSION_PERSISTENCE` | 이 `claude`가 다른 Claude Code 세션 내부에서 실행된 경우에도 트랜스크립트 유지, 프롬프트 기록, `claude agents` 등록을 강제하려면 `1`로 설정합니다. 예를 들어 `screen` 세션이나 Claude Code의 Bash 도구가 처음 시작한 백그라운드 런처에서 상속된 `CLAUDE_CODE_CHILD_SESSION` 값으로 인해 실제 최상위 세션이 중첩 세션으로 잘못 분류될 때 사용합니다. v2.1.178부터 Claude Code는 tmux의 경우를 자동으로 감지하고 상속된 마커를 무시하므로 tmux에서는 더 이상 이 변수가 필요하지 않습니다. v2.1.169 이하에서도 적용되며, 이 변수가 재정의하는 중첩 세션 감지가 제거된 v2.1.170 및 v2.1.171에서는 효과가 없습니다 |305| `CLAUDE_CODE_FORCE_SESSION_PERSISTENCE` | 이 `claude`가 다른 Claude Code 세션 내부에서 실행된 경우에도 트랜스크립트 저장, 프롬프트 기록, `claude agents` 등록을 강제하려면 `1`로 설정합니다. 예를 들어 `screen` 세션이나 Claude Code의 Bash 도구가 처음 시작한 백그라운드 런처에서 상속된 `CLAUDE_CODE_CHILD_SESSION` 값 때문에 실제 최상위 세션이 중첩 세션으로 잘못 분류될 때 사용합니다. v2.1.178부터 Claude Code는 tmux의 경우를 자동으로 감지하고 상속된 마커를 무시하므로 tmux에서는 더 이상 이 변수가 필요하지 않습니다. v2.1.169 이하에서도 적용되며, 이 변수가 재정의하는 중첩 세션 감지가 제거된 v2.1.170 및 v2.1.171에서는 효과가 없습니다 |

304| `CLAUDE_CODE_FORCE_STRIKETHROUGH` | 터미널이 취소선을 지원하지만 자동 감지되지 않는 경우(예: `TERM_PROGRAM`이 전달되지 않은 SSH 환경) Claude의 응답에서 `~~text~~`에 취소선 렌더링을 강제하려면 `1`로 설정합니다. 이 설정이 없으면 감지되지 않은 터미널은 텍스트를 취소선으로 렌더링하는 대신 `~~` 마커를 그대로 표시합니다. Claude Code v2.1.186 이상이 필요합니다 |306| `CLAUDE_CODE_FORCE_STRIKETHROUGH` | 터미널이 취소선을 지원하지만 자동 감지되지 않는 경우(예: `TERM_PROGRAM`이 전달되지 않은 SSH 연결) Claude 응답의 `~~text~~`를 강제로 취소선으로 렌더링하려면 `1`로 설정합니다. 이 설정이 없으면 감지되지 않은 터미널에서는 텍스트를 취소선으로 렌더링하는 대신 `~~` 마커가 그대로 표시됩니다. Claude Code v2.1.186 이상이 필요합니다 |

305| `CLAUDE_CODE_FORCE_SYNC_OUTPUT` | 터미널이 DEC private mode 2026 [동기화된 출력](https://gist.github.com/christianparpart/d8a62cc1ab659194337d73e399004036)을 지원하지만 자동 감지되지 않을 때 이를 강제로 활성화하려면 `1`로 설정합니다. BSU/ESU를 구현하지만 기능 프로브에 응답하지 않는 Emacs `eat`과 같은 에뮬레이터에 유용합니다. tmux에서는 효과가 없습니다. [전체 화면 렌더링](/docs/ko/fullscreen)으로 전환하는 `CLAUDE_CODE_NO_FLICKER`와 달리 이 변수는 렌더러를 변경하지 않습니다 |307| `CLAUDE_CODE_FORCE_SYNC_OUTPUT` | 터미널이 DEC private mode 2026 [동기화된 출력](https://gist.github.com/christianparpart/d8a62cc1ab659194337d73e399004036)을 지원하지만 자동 감지되지 않을 때 이를 강제로 활성화하려면 `1`로 설정합니다. BSU/ESU를 구현하지만 기능 탐지에 응답하지 않는 Emacs `eat`와 같은 에뮬레이터에 유용합니다. tmux에서는 효과가 없습니다. [전체 화면 렌더링](/docs/ko/fullscreen)으로 전환하는 `CLAUDE_CODE_NO_FLICKER`와 달리 렌더러를 변경하지 않습니다 |

306| `CLAUDE_CODE_FORK_SUBAGENT` | Claude가 [포크된 서브에이전트](/docs/ko/sub-agents#fork-the-current-conversation)를 직접 생성할 수 있게 하는 [포크 모드](/docs/ko/sub-agents#turn-fork-mode-on-or-off)를 제어하며, 포크 모드는 대화형 세션에서만 기본적으로 켜져 있습니다. `claude -p`와 Agent SDK에서도 켜려면 `1`로, 모든 종류의 세션에서 끄려면 `0`으로 설정합니다. `/subtask`는 포크 모드가 켜져 있는지 여부와 관계없이 실행할 수 있습니다. 대화형 기본값은 Claude Code v2.1.232 이상이 필요하며, 이전 버전에서는 포크 모드를 켜려면 변수를 `1`로 설정합니다 |308| `CLAUDE_CODE_FORK_SUBAGENT` | Claude가 직접 [포크된 서브에이전트](/docs/ko/sub-agents#fork-the-current-conversation)를 생성할 수 있게 하는 [포크 모드](/docs/ko/sub-agents#turn-fork-mode-on-or-off)를 제어하며, 포크 모드는 대화형 세션에서만 기본적으로 켜져 있습니다. `claude -p`와 Agent SDK에서도 켜려면 `1`로, 모든 종류의 세션에서 끄려면 `0`으로 설정합니다. `/subtask`는 포크 모드 여부와 관계없이 실행할 수 있습니다. 대화형 기본값은 Claude Code v2.1.232 이상이 필요합니다. 이전 버전에서는 포크 모드를 켜려면 변수를 `1`로 설정하십시오 |

307| `CLAUDE_CODE_FORWARD_SUBAGENT_TEXT` | `claude -p --output-format stream-json` 출력에 [서브에이전트](/docs/ko/sub-agents) 텍스트 및 thinking 블록을 내보내려면 `1`로 설정합니다. [`--forward-subagent-text`](/docs/ko/cli-reference#cli-flags) 플래그와 동일한 동작입니다. 하네스가 `claude`를 호출하며 플래그를 직접 전달할 수 없을 때 이 변수를 사용합니다. stream-json 출력을 사용하는 비대화형 모드 외부에서 오류와 함께 종료되는 플래그와 달리, 이 변수는 그런 경우 무시되므로 프로세스 전체에 설정되어 있어도 중첩 호출이 계속 작동합니다. Claude Code v2.1.211 이상이 필요합니다 |309| `CLAUDE_CODE_FORWARD_SUBAGENT_TEXT` | [`--forward-subagent-text`](/docs/ko/cli-reference#cli-flags) 플래그와 동일하게, `claude -p --output-format stream-json` 출력에 [서브에이전트](/docs/ko/sub-agents) 텍스트와 thinking 블록을 내보내려면 `1`로 설정합니다. 하네스가 `claude`를 호출하면서 플래그를 직접 전달할 수 없을 때 이 변수를 사용합니다. stream-json 출력을 사용하는 비대화형 모드 외부에서 오류와 함께 종료되는 플래그와 달리, 이 변수는 그러한 환경에서 무시되므로 프로세스 전체에 설정해도 중첩된 호출이 계속 작동합니다. Claude Code v2.1.211 이상이 필요합니다 |

308| `CLAUDE_CODE_GATEWAY_HINT_HEADERS` | 사용자 지정 프록시 또는 Amazon Bedrock이나 Claude Platform on AWS와 같은 타사 공급자에서 `x-claude-code-request-class` 및 `x-claude-code-compaction`과 같은 [게이트웨이 힌트 헤더](/docs/ko/llm-gateway-protocol#gateway-hint-headers)를 보내려면 `1`로 설정합니다. Claude Code가 기본적으로 헤더를 보내는 Anthropic API 직접 연결을 포함한 모든 연결에서 헤더 전송을 중지하려면 `0`으로 설정합니다. Claude Code v2.1.273 이상이 필요합니다 |310| `CLAUDE_CODE_GATEWAY_HINT_HEADERS` | 사용자 지정 프록시나 Amazon Bedrock 또는 Claude Platform on AWS와 같은 타사 공급자에서 `x-claude-code-request-class`, `x-claude-code-compaction`과 같은 [게이트웨이 힌트 헤더](/docs/ko/llm-gateway-protocol#gateway-hint-headers)를 전송하려면 `1`로 설정합니다. Claude Code가 기본적으로 전송하는 Anthropic API 직접 연결을 포함하여 모든 연결에서 전송을 중단하려면 `0`으로 설정합니다. Claude Code v2.1.273 이상이 필요합니다 |

309| `CLAUDE_CODE_GATEWAY_MODEL_DISCOVERY_TIMEOUT_MS` | `CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY`가 켜는 [게이트웨이 모델 검색](/docs/ko/llm-gateway-protocol#model-discovery) 요청의 타임아웃(밀리초)입니다(기본값: `3000`). 게이트웨이가 시작 시 `/v1/models`에 응답하는 데 3초보다 오래 걸리면 값을 늘립니다. 일반 숫자만 허용되며, `0`, 음수 값 및 기타 표기는 기본값을 유지합니다. Claude Code v2.1.269 이상이 필요합니다 |311| `CLAUDE_CODE_GATEWAY_MODEL_DISCOVERY_TIMEOUT_MS` | `CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY`가 켜는 [게이트웨이 모델 검색](/docs/ko/llm-gateway-protocol#model-discovery) 요청의 타임아웃(밀리초)입니다(기본값: `3000`). 게이트웨이가 시작 시 `/v1/models`에 응답하는 데 3초보다 오래 걸리면 값을 높이십시오. 숫자만 허용되며, `0`, 음수 및 기타 표기는 기본값을 유지합니다. Claude Code v2.1.269 이상이 필요합니다 |

310| `CLAUDE_CODE_GIT_BASH_PATH` | Windows 전용: Git Bash 실행 파일(`bash.exe`)의 경로입니다. Git Bash가 설치되어 있지만 PATH에 없을 때 사용합니다. 경로가 존재하지 않거나 파일 이름이 `bash.exe`, `sh.exe`, `bash`, `sh`가 아니면 Claude Code는 변수를 무시하고 설정되지 않은 것처럼 Git Bash를 자동 감지하며, `--debug`로 볼 수 있는 경고를 로그에 기록합니다. v2.1.219 이전에는 경로가 존재하지 않으면 Claude Code가 시작 시 종료되었고, 기존 파일이면 bash 또는 sh인지 확인하지 않고 셸로 사용했습니다. [Windows 설정](/docs/ko/setup#set-up-on-windows)을 참조하세요 |312| `CLAUDE_CODE_GIT_BASH_PATH` | Windows 전용: Git Bash 실행 파일(`bash.exe`)의 경로입니다. Git Bash가 설치되어 있지만 PATH에 없을 때 사용합니다. 경로가 존재하지 않거나 파일 이름이 `bash.exe`, `sh.exe`, `bash` 또는 `sh`가 아니면 Claude Code는 이 변수를 무시하고 설정되지 않은 것처럼 Git Bash를 자동 감지하며, `--debug`로 볼 수 있는 경고를 로그에 기록합니다. v2.1.219 이전에는 경로가 존재하지 않으면 Claude Code가 시작 시 종료되었고, 존재하는 파일이면 bash 또는 sh인지 확인하지 않고 셸로 사용했습니다. [Windows 설정](/docs/ko/setup#set-up-on-windows)을 참조하십시오 |

311| `CLAUDE_CODE_GLOB_HIDDEN` | Claude가 [Glob 도구](/docs/ko/tools-reference#glob-tool-behavior)를 호출할 때 결과에서 dotfile을 제외하려면 `false`로 설정합니다. 기본적으로 포함됩니다. `@` 파일 자동 완성, `ls`, Grep 또는 Read에는 영향을 주지 않습니다 |313| `CLAUDE_CODE_GLOB_HIDDEN` | Claude가 [Glob 도구](/docs/ko/tools-reference#glob-tool-behavior)를 호출할 때 결과에서 dotfile을 제외하려면 `false`로 설정합니다. 기본적으로 포함됩니다. `@` 파일 자동 완성, `ls`, Grep 또는 Read에는 영향을 주지 않습니다 |

312| `CLAUDE_CODE_GLOB_NO_IGNORE` | [Glob 도구](/docs/ko/tools-reference#glob-tool-behavior)가 `.gitignore` 패턴을 따르도록 하려면 `false`로 설정합니다. 기본적으로 Glob은 gitignore된 파일을 포함하여 일치하는 모든 파일을 반환합니다. 자체 [`respectGitignore` 설정](/docs/ko/settings-reference#respectgitignore)이 있는 `@` 파일 자동 완성에는 영향을 주지 않습니다 |314| `CLAUDE_CODE_GLOB_NO_IGNORE` | [Glob 도구](/docs/ko/tools-reference#glob-tool-behavior)가 `.gitignore` 패턴을 따르도록 하려면 `false`로 설정합니다. 기본적으로 Glob은 gitignore된 파일을 포함하여 일치하는 모든 파일을 반환합니다. 자체 [`respectGitignore` 설정](/docs/ko/settings-reference#respectgitignore)이 있는 `@` 파일 자동 완성에는 영향을 주지 않습니다 |

314| `CLAUDE_CODE_GOAL_CHECKIN_MINUTES` | 백그라운드 작업이 활성 목표를 대기시킬 수 있는 시간(분)으로, 이 시간이 지나면 Claude Code가 [Claude에게 목표를 확인하도록 요청합니다](/docs/ko/goal#background-work-defers-evaluation). 기본값은 `30`입니다. 확인을 끄려면 `0`으로 설정합니다. 분 단위의 정수를 일반 숫자로 지정하며, 최댓값은 1주에 해당하는 `10080`입니다. Claude Code는 그 외의 값을 설정되지 않은 것으로 처리하고 기본값을 사용합니다. Claude Code v2.1.234 이상이 필요합니다 |316| `CLAUDE_CODE_GOAL_CHECKIN_MINUTES` | 백그라운드 작업이 활성 목표를 대기시킬 수 있는 시간(분)으로, 이 시간이 지나면 Claude Code가 [Claude에게 확인을 요청합니다](/docs/ko/goal#background-work-defers-evaluation). 기본값은 `30`입니다. 확인을 끄려면 `0`으로 설정합니다. 정수 분 단위로 숫자만 입력하며, 최대값은 1주에 해당하는 `10080`입니다. Claude Code는 그 외의 값을 설정되지 않은 것으로 처리하고 기본값을 사용합니다. Claude Code v2.1.234 이상이 필요합니다 |

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

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

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

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

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

321| `CLAUDE_CODE_MAX_MCP_DESCRIPTION_LENGTH` | Claude Code가 모델에 보내는 각 MCP 도구 설명 및 각 MCP 서버 지침의 최대 길이(문자 수)입니다(기본값: 2048). Claude Code는 [더 긴 텍스트를 잘라냅니다](/docs/ko/mcp#for-mcp-server-authors). 양의 정수를 일반 숫자로 허용합니다. 그 외의 값은 무시되고 기본값이 적용됩니다. Claude Code v2.1.280 이상이 필요합니다 |323| `CLAUDE_CODE_MAX_MCP_DESCRIPTION_LENGTH` | Claude Code가 모델에 전송하는 각 MCP 도구 설명과 각 MCP 서버 지침의 최대 길이(문자 수)입니다(기본값: 2048). Claude Code는 [더 긴 텍스트를 잘라냅니다](/docs/ko/mcp#for-mcp-server-authors). 숫자로만 된 양의 정수를 허용합니다. 그 외의 값은 무시되고 기본값이 적용됩니다. Claude Code v2.1.280 이상이 필요합니다 |

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

323| `CLAUDE_CODE_MAX_RETRIES` | 실패한 API 요청의 재시도 횟수를 재정의합니다(기본값: 10). v2.1.186부터 최대 15로 제한되며, v2.1.199부터는 `CLAUDE_CODE_RETRY_WATCHDOG`가 기본값을 높이고 상한을 제거합니다. 더 긴 장애를 기다려야 하는 무인 세션에는 대신 `CLAUDE_CODE_RETRY_WATCHDOG`를 설정합니다 |325| `CLAUDE_CODE_MAX_RETRIES` | 실패한 API 요청을 재시도하는 횟수를 재정의합니다(기본값: 10). v2.1.186부터 상한은 15입니다. v2.1.199부터는 `CLAUDE_CODE_RETRY_WATCHDOG`가 기본값을 높이고 상한을 제거합니다. 더 긴 장애를 견디며 대기해야 하는 무인 세션에서는 대신 `CLAUDE_CODE_RETRY_WATCHDOG`를 설정하십시오 |

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

325| `CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH` | 주 대화 아래에 허용되는 [서브에이전트 계층](/docs/ko/sub-agents#let-subagents-spawn-their-own-subagents) 수 (기본값: 3)입니다. 기본값에서는 서브에이전트가 자체 서브에이전트를 생성할 수 있으며, 세 번째 계층의 서브에이전트는 더 이상 생성할 수 없습니다. 중첩을 끄려면 `1`로 설정합니다. v2.1.217부터 v2.1.218까지는 기본값이 1이었으므로 제한을 높이지 않으면 서브에이전트가 자체 서브에이전트를 생성할 수 없었으며, v2.1.219에서 기본값이 3으로 높아졌습니다. 양의 정수를 일반 숫자로 허용하며, 그 외의 값은 무시되므로 제한을 조정할 수는 있지만 제거할 수는 없습니다. Claude Code v2.1.217 이상이 필요합니다 |327| `CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH` | 메인 대화 아래에 허용되는 [서브에이전트 계층](/docs/ko/sub-agents#let-subagents-spawn-their-own-subagents) 수입니다 (기본값: 3). 기본값에서는 서브에이전트가 자체 서브에이전트를 생성할 수 있으며, 세 번째 계층의 서브에이전트는 더 이상 생성할 수 없습니다. 중첩을 끄려면 `1`로 설정합니다. v2.1.217부터 v2.1.218까지는 기본값이 1이었으므로 제한을 높이지 않는 한 서브에이전트가 자체 서브에이전트를 생성할 수 없었으며, v2.1.219에서 기본값이 3으로 높아졌습니다. 숫자로만 된 양의 정수를 허용하며, 그 외의 값은 무시되므로 제한을 조정할 수는 있지만 제거할 수는 없습니다. Claude Code v2.1.217 이상이 필요합니다 |

326| `CLAUDE_CODE_MAX_TOOL_USE_CONCURRENCY` | 병렬로 실행할 수 있는 읽기 전용 도구 및 서브에이전트의 최대 수입니다(기본값: 10). 값이 클수록 병렬성이 높아지지만 더 많은 리소스를 사용합니다 |328| `CLAUDE_CODE_MAX_TOOL_USE_CONCURRENCY` | 병렬로 실행할 수 있는 읽기 전용 도구 및 서브에이전트의 최대 수입니다(기본값: 10). 값이 클수록 병렬성은 높아지지만 리소스를 더 많이 소비합니다 |

327| `CLAUDE_CODE_MAX_TURNS` | 명시적 제한이 전달되지 않을 때 에이전트 턴 수의 상한을 지정합니다. [`--max-turns`](/docs/ko/cli-reference#cli-flags)를 전달하는 것과 동일하며, 둘 다 설정된 경우 플래그가 우선합니다. 양의 정수가 아닌 값은 상한 없음으로 처리되지 않고 시작 시 오류와 함께 거부됩니다 |329| `CLAUDE_CODE_MAX_TURNS` | 명시적인 제한이 전달되지 않았을 때 에이전트 턴 수를 제한합니다. [`--max-turns`](/docs/ko/cli-reference#cli-flags)를 전달하는 것과 같으며, 둘 다 설정된 경우 `--max-turns`가 우선합니다. 양의 정수가 아닌 값은 제한 없음으로 처리되지 않고 시작 시 오류와 함께 거부됩니다 |

328| `CLAUDE_CODE_MAX_WEB_SEARCHES_PER_SESSION` | 한 세션에서 수행할 수 있는 [WebSearch](/docs/ko/tools-reference#websearch-tool-behavior) 호출 총 수의 상한입니다(기본값: 200). Claude가 상한에 도달하면 이후 WebSearch 호출은 이미 수집한 정보로 계속 진행하라는 알림을 반환합니다. 상한이 없는 양의 정수를 허용합니다. 그 외의 값은 무시되고 기본값이 적용되므로 상한을 높일 수는 있지만 끌 수는 없습니다. Claude Code v2.1.212 이상이 필요합니다 |330| `CLAUDE_CODE_MAX_WEB_SEARCHES_PER_SESSION` | 한 세션에서 수행할 수 있는 [WebSearch](/docs/ko/tools-reference#websearch-tool-behavior) 호출의 총 횟수 상한입니다(기본값: 200). Claude가 상한에 도달하면 이후의 WebSearch 호출은 이미 수집한 정보로 계속 진행하라는 알림을 반환합니다. 상한이 없는 양의 정수를 허용합니다. 그 외의 값은 무시되고 기본값이 적용되므로 상한을 높일 수는 있지만 끌 수는 없습니다. Claude Code v2.1.212 이상이 필요합니다 |

330| `CLAUDE_CODE_MCP_AUTO_BACKGROUND_MS` | 아직 실행 중인 MCP 도구 호출이 [백그라운드 작업으로 이동하기](/docs/ko/mcp#automatic-backgrounding-of-long-tool-calls) 전까지의 경과 시간(밀리초)입니다(기본값: 120000, 즉 2분). 자동 백그라운드 전환을 끄려면 `0`으로 설정합니다. Claude Code v2.1.212 이상이 필요합니다 |332| `CLAUDE_CODE_MCP_AUTO_BACKGROUND_MS` | 아직 실행 중인 MCP 도구 호출이 [백그라운드 작업으로 전환](/docs/ko/mcp#automatic-backgrounding-of-long-tool-calls)되기까지의 경과 시간(밀리초)입니다(기본값: 120000, 즉 2분). 자동 백그라운드 전환을 끄려면 `0`으로 설정합니다. Claude Code v2.1.212 이상이 필요합니다 |

331| `CLAUDE_CODE_MCP_STARTUP_WAIT_MS` | [비대화형](/docs/ko/headless) 세션의 첫 번째 턴이 아직 연결 중인 MCP 서버를 기다리는 시간(밀리초)으로, 기본 [첫 번째 턴 대기](/docs/ko/agent-sdk/mcp#connection-timing) 대신 사용됩니다. 설정하면 대기 시간이 보류 중인 모든 서버에 적용됩니다. 대기를 건너뛰려면 `0`으로 설정합니다. [`--permission-prompt-tool`](/docs/ko/cli-reference#cli-flags) 서버는 값과 관계없이 자체 `MCP_TIMEOUT` 대기를 유지합니다. Claude Code v2.1.274 이상이 필요합니다 |333| `CLAUDE_CODE_MCP_STARTUP_WAIT_MS` | [비대화형](/docs/ko/headless) 세션의 첫 번째 턴이 아직 연결 중인 MCP 서버를 기다리는 시간(밀리초)으로, 기본 [첫 턴 대기](/docs/ko/agent-sdk/mcp#connection-timing)를 대체합니다. 설정하면 대기가 보류 중인 모든 서버에 적용됩니다. 대기를 건너뛰려면 `0`으로 설정합니다. [`--permission-prompt-tool`](/docs/ko/cli-reference#cli-flags) 서버는 값과 관계없이 자체 `MCP_TIMEOUT` 대기를 유지합니다. Claude Code v2.1.274 이상이 필요합니다 |

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

333| `CLAUDE_CODE_MESSAGING_SOCKET` | 사용자가 아닌 Claude Code가 설정합니다. [받은 편지함 소켓](/docs/ko/cross-session-messaging#the-sessions-inbox-socket)을 바인딩하는 세션에서 Claude Code는 소켓을 바인딩할 때 해당 소켓의 경로를 훅과 Bash 명령에 내보냅니다. 메시징이 켜진 상태로 시작하는 세션에서는 Claude Code가 훅이 실행되기 전에 소켓을 바인딩합니다. 머신의 다른 세션은 이 경로로 메시지를 전달합니다. 각 세션은 부모에게서 상속한 소켓이 아닌 자체 소켓을 내보내며, 이 소켓으로 도착하는 메시지는 세션의 [수신 제어](/docs/ko/cross-session-messaging#control-inbound-messages)를 거칩니다. 설정의 `env` 블록으로는 설정할 수 없습니다. Claude Code v2.1.224 이상이 필요합니다 |335| `CLAUDE_CODE_MESSAGING_SOCKET` | 사용자가 아닌 Claude Code가 설정합니다. [인박스 소켓](/docs/ko/cross-session-messaging#the-sessions-inbox-socket)을 바인딩하는 세션에서 Claude Code는 소켓을 바인딩할 때 해당 소켓의 경로를 훅과 Bash 명령에 export합니다. 메시징이 켜진 상태로 시작하는 세션에서는 Claude Code가 훅이 실행되기 전에 소켓을 바인딩합니다. 머신의 다른 세션은 이 경로로 메시지를 전달합니다. 각 세션은 부모로부터 상속된 소켓이 아닌 자체 소켓을 export하며, 이 소켓으로 도착한 메시지는 세션의 [인바운드 제어](/docs/ko/cross-session-messaging#control-inbound-messages)를 거칩니다. 설정의 `env` 블록에서는 설정할 수 없습니다. Claude Code v2.1.224 이상이 필요합니다 |

334| `CLAUDE_CODE_MESSAGING_TOKEN` | 사용자가 아닌 Claude Code가 설정합니다. [받은 편지함 소켓](/docs/ko/cross-session-messaging#the-sessions-inbox-socket)을 바인딩하는 세션에서 Claude Code는 이 세션별 토큰을 `CLAUDE_CODE_MESSAGING_SOCKET`과 함께 훅과 Bash 명령에 내보냅니다. 소켓에 게시하는 스크립트는 첫 번째 줄로 `{"type":"auth","token":"<token>"}`를 보내 해당 세션에 속함을 증명할 수 있습니다. 네이티브 Windows에서는 Claude Code가 이 줄을 요구하며, 유효한 줄로 시작하지 않는 연결은 모두 닫습니다. [자체 자식 규칙](/docs/ko/cross-session-messaging#the-sessions-inbox-socket)에서 Claude Code가 토큰을 참조하는 시점을 설명합니다. 각 세션은 부모 세션에서 상속한 토큰이 아닌 자체 토큰을 내보냅니다. 설정의 `env` 블록으로는 설정할 수 없습니다. Claude Code v2.1.228 이상이 필요합니다 |336| `CLAUDE_CODE_MESSAGING_TOKEN` | 사용자가 아닌 Claude Code가 설정합니다. [인박스 소켓](/docs/ko/cross-session-messaging#the-sessions-inbox-socket)을 바인딩하는 세션에서 Claude Code는 이 세션별 토큰을 `CLAUDE_CODE_MESSAGING_SOCKET`과 함께 훅과 Bash 명령에 export합니다. 소켓에 게시하는 스크립트는 첫 줄로 `{"type":"auth","token":"<token>"}`을 전송하여 해당 세션에 속함을 증명할 수 있습니다. 네이티브 Windows에서는 Claude Code가 이 줄을 필수로 요구하며, 유효한 줄로 시작하지 않는 연결은 닫습니다. [자체 자식 규칙](/docs/ko/cross-session-messaging#the-sessions-inbox-socket)은 Claude Code가 언제 토큰을 참조하는지 설명합니다. 각 세션은 자체 토큰을 export하며, 부모 세션에서 상속된 토큰은 절대 사용하지 않습니다. 설정의 `env` 블록에서는 설정할 수 없습니다. Claude Code v2.1.228 이상이 필요합니다 |

336| `CLAUDE_CODE_NEW_INIT` | `/init`이 대화형 설정 흐름을 실행하도록 하려면 `1`로 설정합니다. 이 흐름은 코드베이스를 탐색하고 파일을 작성하기 전에 CLAUDE.md, 스킬, 훅을 포함하여 생성할 파일을 묻습니다. 이 변수가 없으면 `/init`은 묻지 않고 CLAUDE.md를 자동으로 생성합니다 |338| `CLAUDE_CODE_NEW_INIT` | `/init`이 대화형 설정 흐름을 실행하도록 하려면 `1`로 설정합니다. 이 흐름은 코드베이스를 탐색하고 파일을 작성하기 전에 CLAUDE.md, 스킬, 훅을 포함하여 생성할 파일을 묻습니다. 이 변수가 없으면 `/init`은 묻지 않고 CLAUDE.md를 자동으로 생성합니다 |

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

338| `CLAUDE_CODE_NONSTREAMING_TIMEOUT_RETRIES` | 시간 초과된 [비스트리밍 요청](/docs/ko/errors#streaming-response-ended-before-any-complete-data-was-received)을 Claude Code가 다시 보내는 횟수를 제한합니다. `0`이면 첫 번째 시간 초과에서 요청이 실패합니다. 기본적으로 설정되어 있지 않으므로 `CLAUDE_CODE_MAX_RETRIES`가 이러한 재전송을 제한합니다. 타임아웃에 대해서는 [재시도 동작 조정](/docs/ko/errors#tune-retry-behavior)을 참조하세요. Claude Code v2.1.285 이상이 필요합니다 |340| `CLAUDE_CODE_NONSTREAMING_TIMEOUT_RETRIES` | 시간 초과된 [비스트리밍 요청](/docs/ko/errors#streaming-response-ended-before-any-complete-data-was-received)을 Claude Code가 다시 전송하는 횟수를 제한합니다. `0`이면 첫 번째 시간 초과에서 요청이 실패합니다. 기본적으로 설정되어 있지 않으므로 `CLAUDE_CODE_MAX_RETRIES`가 이러한 재전송을 제한합니다. 타임아웃에 대해서는 [재시도 동작 조정](/docs/ko/errors#tune-retry-behavior)을 참조하십시오. Claude Code v2.1.285 이상이 필요합니다 |

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

340| `CLAUDE_CODE_OAUTH_REFRESH_TOKEN` | Claude.ai 인증을 위한 OAuth 새로 고침 토큰입니다. 설정하면 `claude auth login`이 브라우저를 여는 대신 이 토큰을 직접 교환합니다. `CLAUDE_CODE_OAUTH_SCOPES`가 필요합니다. 자동화된 환경에서 인증을 프로비저닝하는 데 유용합니다 |342| `CLAUDE_CODE_OAUTH_REFRESH_TOKEN` | Claude.ai 인증을 위한 OAuth 갱신 토큰입니다. 설정하면 `claude auth login`이 브라우저를 여는 대신 이 토큰을 직접 교환합니다. `CLAUDE_CODE_OAUTH_SCOPES`가 필요합니다. 자동화된 환경에서 인증을 프로비저닝하는 데 유용합니다 |

341| `CLAUDE_CODE_OAUTH_SCOPES` | 새로 고침 토큰이 발급될 때 사용된 공백으로 구분된 OAuth 범위입니다(예: `"user:profile user:inference user:sessions:claude_code"`). `CLAUDE_CODE_OAUTH_REFRESH_TOKEN`이 설정된 경우 필요합니다 |343| `CLAUDE_CODE_OAUTH_SCOPES` | 갱신 토큰이 발급된 OAuth 범위를 공백으로 구분한 목록입니다(예: `"user:profile user:inference user:sessions:claude_code"`). `CLAUDE_CODE_OAUTH_REFRESH_TOKEN`이 설정된 경우 필요합니다 |

342| `CLAUDE_CODE_OAUTH_TOKEN` | claude.ai 인증을 위한 OAuth 액세스 토큰입니다. SDK 및 자동화된 환경에서 `/login` 대신 사용할 수 있습니다. 키체인에 저장된 자격 증명보다 우선합니다. [`claude setup-token`](/docs/ko/authentication#generate-a-long-lived-token)으로 생성합니다. [`/login`](/docs/ko/authentication#authentication-precedence)을 실행하지 않는 한 Claude Code는 설정한 토큰을 세션 전체에서 사용합니다. 만료된 토큰을 교체하려면 새 토큰을 생성하고 다시 시작합니다 |344| `CLAUDE_CODE_OAUTH_TOKEN` | claude.ai 인증을 위한 OAuth 액세스 토큰입니다. SDK 및 자동화된 환경에서 `/login`의 대안입니다. 키체인에 저장된 자격 증명보다 우선합니다. [`claude setup-token`](/docs/ko/authentication#generate-a-long-lived-token)으로 생성합니다. [`/login`](/docs/ko/authentication#authentication-precedence)을 실행하지 않는 한 Claude Code는 설정한 토큰을 세션 전체에서 사용합니다. 만료된 토큰을 교체하려면 새 토큰을 생성하고 다시 시작하십시오 |

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

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

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

346| `CLAUDE_CODE_OTEL_FLUSH_TIMEOUT_MS` | 보류 중인 OpenTelemetry 스팬을 플러시하는 타임아웃(밀리초)입니다(기본값: 5000). [모니터링](/docs/ko/monitoring-usage)을 참조하세요 |348| `CLAUDE_CODE_OTEL_FLUSH_TIMEOUT_MS` | 보류 중인 OpenTelemetry span을 플러시하는 타임아웃(밀리초)입니다(기본값: 5000). [모니터링](/docs/ko/monitoring-usage)을 참조하십시오 |

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

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

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

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

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

352| `CLAUDE_CODE_PLUGIN_DIRS` | 세션에 로드할 플러그인 디렉터리로, 각 디렉터리는 [`--plugin-dir`](/docs/ko/plugins/cli-reference#flags-that-load-a-plugin-for-one-session) 플래그와 같은 방식으로 로드됩니다. 여러 경로는 Unix에서는 `:`, Windows에서는 `;`로 구분합니다. Claude Code는 상대 경로를 건너뛰므로 각 경로를 절대 경로로 지정하거나 `~`로 시작합니다. Claude Code v2.1.280 이상이 필요합니다. [한 세션에 플러그인 로드](/docs/ko/plugins/create#load-a-directory-or-archive-for-one-session)를 참조하세요 |354| `CLAUDE_CODE_PLUGIN_DIRS` | 세션에 로드할 플러그인 디렉터리로, 각각 [`--plugin-dir`](/docs/ko/plugins/cli-reference#flags-that-load-a-plugin-for-one-session) 플래그가 로드하는 방식으로 로드됩니다. 여러 경로는 Unix에서는 `:`, Windows에서는 `;`로 구분합니다. Claude Code는 상대 경로를 건너뛰므로 각 경로는 절대 경로로 지정하거나 `~`로 시작하십시오. Claude Code v2.1.280 이상이 필요합니다. [한 세션에 플러그인 로드](/docs/ko/plugins/create#load-a-directory-or-archive-for-one-session)를 참조하십시오 |

353| `CLAUDE_CODE_PLUGIN_GIT_TIMEOUT_MS` | 플러그인 마켓플레이스를 복제하거나 새로 고치는 타임아웃(밀리초)입니다(기본값: 120000). 대용량 저장소나 느린 네트워크 연결의 경우 이 값을 늘립니다. [Git clone timed out](/docs/ko/plugins/troubleshooting#git-clone-timed-out-after-120s)을 참조하세요 |355| `CLAUDE_CODE_PLUGIN_GIT_TIMEOUT_MS` | 플러그인 마켓플레이스를 복제하거나 새로 고치는 타임아웃(밀리초)입니다(기본값: 120000). 큰 저장소나 느린 네트워크 연결에서는 이 값을 늘리십시오. [Git clone 시간 초과](/docs/ko/plugins/troubleshooting#git-clone-timed-out-after-120s)를 참조하십시오 |

354| `CLAUDE_CODE_PLUGIN_KEEP_MARKETPLACE_ON_FAILURE` | 마켓플레이스 새로 고침이 원격에 연결하거나 인증할 수 없을 때 재복제 시도를 건너뛰고 기존 마켓플레이스 체크아웃을 계속 사용하려면 `1`로 설정합니다. 재복제도 같은 방식으로 실패할 오프라인 또는 에어갭 환경에서 유용합니다. [오프라인 환경에서 마켓플레이스 업데이트 실패](/docs/ko/plugins/troubleshooting#marketplace-updates-keep-failing-offline)를 참조하세요 |356| `CLAUDE_CODE_PLUGIN_KEEP_MARKETPLACE_ON_FAILURE` | 마켓플레이스 새로 고침이 원격에 연결하거나 인증할 수 없을 때 다시 복제를 시도하지 않고 기존 마켓플레이스 체크아웃을 계속 사용하려면 `1`로 설정합니다. 다시 복제해도 같은 방식으로 실패할 오프라인 또는 에어갭 환경에서 유용합니다. [오프라인 환경에서 마켓플레이스 업데이트 실패](/docs/ko/plugins/troubleshooting#marketplace-updates-keep-failing-offline)를 참조하십시오 |

355| `CLAUDE_CODE_PLUGIN_PREFER_HTTPS` | GitHub `owner/repo` 축약형 소스를 SSH 대신 HTTPS로 복제하려면 `1`로 설정합니다. 플러그인 설치 및 업데이트와 `/plugin marketplace add` 및 `update`에 적용됩니다. CI 러너, 컨테이너 또는 `github.com`용 SSH 키가 구성되지 않은 모든 환경에서 유용합니다 |357| `CLAUDE_CODE_PLUGIN_PREFER_HTTPS` | GitHub `owner/repo` 약식 소스를 SSH 대신 HTTPS로 복제하려면 `1`로 설정합니다. 플러그인 설치 및 업데이트, 그리고 `/plugin marketplace add` 및 `update`에 적용됩니다. CI 러너, 컨테이너 또는 `github.com`용 SSH 키가 구성되지 않은 환경에서 유용합니다 |

356| `CLAUDE_CODE_PLUGIN_SEED_DIR` | Unix에서는 `:`, Windows에서는 `;`로 구분된 하나 이상의 읽기 전용 플러그인 시드 디렉터리 경로입니다. 미리 채워진 플러그인 디렉터리를 컨테이너 이미지에 번들로 포함할 때 사용합니다. Claude Code는 시작 시 이 디렉터리에서 마켓플레이스를 등록하고 미리 캐시된 플러그인을 재복제 없이 사용합니다. [컨테이너용 플러그인 미리 채우기](/docs/ko/plugins/org#seed-containers-and-ci)를 참조하세요 |358| `CLAUDE_CODE_PLUGIN_SEED_DIR` | 하나 이상의 읽기 전용 플러그인 시드 디렉터리 경로로, Unix에서는 `:`, Windows에서는 `;`로 구분합니다. 미리 채워진 플러그인 디렉터리를 컨테이너 이미지에 번들로 포함할 때 사용합니다. Claude Code는 시작 시 이 디렉터리에서 마켓플레이스를 등록하고 다시 복제하지 않고 미리 캐시된 플러그인을 사용합니다. [컨테이너용 플러그인 미리 채우기](/docs/ko/plugins/org#seed-containers-and-ci)를 참조하십시오 |

357| `CLAUDE_CODE_POWERSHELL_RESPECT_EXECUTION_POLICY` | 도구 호출, 훅, 상태줄 명령을 위해 PowerShell을 생성할 때 Claude Code가 `-ExecutionPolicy Bypass`를 전달하지 않고 대신 머신의 유효 실행 정책을 따르도록 하려면 `1`로 설정합니다. 기본적으로 Claude Code는 프로세스 범위에서 실행 정책을 우회하므로 기본값이 Restricted인 Windows 설치에서도 `.ps1` 스크립트와 모듈 가져오기가 작동합니다. 프로세스 범위 우회는 이 설정과 관계없이 그룹 정책 `MachinePolicy` 또는 `UserPolicy`를 재정의하지 않습니다 |359| `CLAUDE_CODE_POWERSHELL_RESPECT_EXECUTION_POLICY` | 도구 호출, 훅, 상태줄 명령을 위해 PowerShell을 생성할 때 Claude Code가 `-ExecutionPolicy Bypass`를 전달하지 않고 대신 머신의 유효 실행 정책을 따르도록 하려면 `1`로 설정합니다. 기본적으로 Claude Code는 기본값이 Restricted인 Windows 설치에서도 `.ps1` 스크립트와 모듈 가져오기가 작동하도록 프로세스 범위에서 실행 정책을 우회합니다. 이 설정과 관계없이 프로세스 범위 우회는 그룹 정책 `MachinePolicy` 또는 `UserPolicy`를 재정의하지 않습니다 |

358| `CLAUDE_CODE_PRINT_BG_WAIT_CEILING_MS` | `-p` 플래그를 사용하는 [비대화형 모드](/docs/ko/headless#background-tasks-at-exit)에서 마지막 턴 이후 백그라운드 서브에이전트와 워크플로를 유휴 상태로 기다리는 시간의 상한(밀리초)입니다. 유휴 대기는 Claude가 백그라운드 결과를 처리하기 위해 턴을 수행할 때마다 다시 시작됩니다. 기본값: `600000`, 즉 10분. 유휴 대기가 상한에 도달하면 Claude Code는 남은 백그라운드 작업 대기를 중단하고 종료합니다. 무기한 대기하려면 `0`으로 설정합니다. 이 상한은 일반 백그라운드 셸에 적용되는 5초 유예 기간과 별개입니다. Claude Code v2.1.182 이상이 필요합니다 |360| `CLAUDE_CODE_PRINT_BG_WAIT_CEILING_MS` | `-p` 플래그를 사용하는 [비대화형 모드](/docs/ko/headless#background-tasks-at-exit)에서 마지막 턴 이후 백그라운드 서브에이전트와 워크플로를 유휴 상태로 기다리는 시간의 상한(밀리초)입니다. Claude가 백그라운드 결과를 처리하기 위해 턴을 수행할 때마다 유휴 대기가 다시 시작됩니다. 기본값: `600000`, 즉 10분. 유휴 대기가 상한에 도달하면 Claude Code는 남은 백그라운드 작업을 더 이상 기다리지 않고 종료합니다. 무기한 기다리려면 `0`으로 설정합니다. 이 상한은 일반 백그라운드 셸에 적용되는 5초 유예 기간과는 별개입니다. Claude Code v2.1.182 이상이 필요합니다 |

359| `CLAUDE_CODE_PROCESS_WRAPPER` | [에이전트 뷰](/docs/ko/agent-view) 세션을 호스팅하는 백그라운드 서비스처럼 Claude Code가 자체 바이너리에서 시작하는 프로세스를 `/opt/corp/launcher`와 같은 argv 접두사로 지정한 회사 런처를 통해 실행합니다. 분리된 백그라운드 서비스가 상속하도록 셸 export가 아닌 사용자 설정 또는 [관리형 설정](/docs/ko/managed-settings)의 `env` 블록에서 설정합니다. 프로젝트 및 로컬 설정에서는 설정할 수 없습니다. [`processWrapper` 설정](/docs/ko/settings-reference#processwrapper)과 동일하며, 이 설정은 Claude Code v2.1.210 이상이 필요합니다. 둘 다 설정된 경우 이 변수가 우선합니다. VS Code 확장은 `claudeProcessWrapper` 설정을 통해 자체 런처를 별도로 구성합니다. Windows에서는 무시됩니다. 값 형식, 런처가 다루는 범위, 런처가 충족해야 하는 계약은 [회사 런처 뒤에서 Claude Code 실행](/docs/ko/corporate-launcher)을 참조하세요. Claude Code v2.1.208 이상이 필요합니다 |361| `CLAUDE_CODE_PROCESS_WRAPPER` | [에이전트 뷰](/docs/ko/agent-view) 세션을 호스팅하는 백그라운드 서비스와 같이 Claude Code가 자체 바이너리에서 시작하는 프로세스를 `/opt/corp/launcher`와 같은 argv 접두사로 지정한 기업용 런처를 통해 실행합니다. 분리된 백그라운드 서비스가 상속할 수 있도록 셸 export가 아닌 사용자 설정 또는 [관리형 설정](/docs/ko/managed-settings)의 `env` 블록에서 설정하십시오. 프로젝트 및 로컬 설정에서는 설정할 수 없습니다. Claude Code v2.1.210 이상이 필요한 [`processWrapper` 설정](/docs/ko/settings-reference#processwrapper)과 동일하며, 둘 다 설정된 경우 이 변수가 우선합니다. VS Code 확장은 자체 `claudeProcessWrapper` 설정을 통해 런처를 별도로 구성합니다. Windows에서는 무시됩니다. 값 형식, 런처가 적용되는 범위, 런처가 충족해야 하는 규약에 대해서는 [기업용 런처 뒤에서 Claude Code 실행](/docs/ko/corporate-launcher)을 참조하십시오. Claude Code v2.1.208 이상이 필요합니다 |

360| `CLAUDE_CODE_PROJECT_DIR_NAME` | `CLAUDE_CONFIG_DIR`와 함께 설정하여, 작업 디렉터리 경로에서 파생된 이름 대신 Claude Code가 해당 세션의 트랜스크립트와 자동 메모리를 저장할 `projects/` 디렉터리 이름을 선택합니다. 예를 들어 `CLAUDE_CONFIG_DIR=/srv/tenant-a CLAUDE_CODE_PROJECT_DIR_NAME=work claude`로 Claude Code를 시작하면 `/srv/tenant-a/projects/work/` 아래에 저장됩니다. `CLAUDE_CONFIG_DIR`가 설정되지 않은 경우 Claude Code는 이 변수를 무시하며, [설정 파일 `env` 블록](#in-settings-files)이 아닌 `claude`를 시작하는 환경에서만 읽습니다. [프로젝트 디렉터리 이름 직접 지정](/docs/ko/sessions#name-the-project-directory-yourself)을 참조하세요. Claude Code v2.1.234 이상이 필요합니다 |362| `CLAUDE_CODE_PROJECT_DIR_NAME` | `CLAUDE_CONFIG_DIR`와 함께 설정하여, Claude Code가 해당 세션의 트랜스크립트와 자동 메모리를 저장하는 `projects/` 디렉터리 이름을 작업 디렉터리 경로에서 파생된 이름 대신 직접 선택합니다. 예를 들어 `CLAUDE_CONFIG_DIR=/srv/tenant-a CLAUDE_CODE_PROJECT_DIR_NAME=work claude`로 Claude Code를 시작하면 `/srv/tenant-a/projects/work/` 아래에 저장됩니다. `CLAUDE_CONFIG_DIR`가 설정되지 않으면 Claude Code는 이 변수를 무시하며, `claude`를 시작하는 환경에서만 읽고 [설정 파일 `env` 블록](#in-settings-files)에서는 절대 읽지 않습니다. [프로젝트 디렉터리 이름 직접 지정](/docs/ko/sessions#name-the-project-directory-yourself)을 참조하십시오. Claude Code v2.1.234 이상이 필요합니다 |

361| `CLAUDE_CODE_PROMPT_CACHE_TTL` | Claude Code가 허용하는 유일한 값인 `5m` 또는 `1h`로 설정하여 주 대화의 [프롬프트 캐시 TTL](/docs/ko/prompt-caching#cache-lifetime)을 선택합니다. 주 대화에는 대화형, `-p`, SDK 턴과 이와 함께 인라인으로 실행되는 헬퍼가 포함됩니다. `promptCacheTtl` 설정과 `ENABLE_PROMPT_CACHING_1H`보다 우선하며, `FORCE_PROMPT_CACHING_5M`이 이 변수를 재정의합니다. API는 1시간 캐시 쓰기에 더 높은 요율을 청구합니다. Claude Code v2.1.242 이상이 필요합니다 |363| `CLAUDE_CODE_PROMPT_CACHE_TTL` | Claude Code가 허용하는 유일한 값인 `5m` 또는 `1h`로 설정하여 메인 대화의 [프롬프트 캐시 TTL](/docs/ko/prompt-caching#cache-lifetime)을 선택합니다. 메인 대화에는 대화형, `-p`, SDK 턴과 이와 함께 인라인으로 실행되는 헬퍼가 포함됩니다. `promptCacheTtl` 설정과 `ENABLE_PROMPT_CACHING_1H`보다 우선하며, `FORCE_PROMPT_CACHING_5M`이 이 변수를 재정의합니다. API는 1시간 캐시 쓰기에 더 높은 요금을 청구합니다. Claude Code v2.1.242 이상이 필요합니다 |

362| `CLAUDE_CODE_PROPAGATE_TRACEPARENT` | `ANTHROPIC_BASE_URL`이 사용자 지정 프록시를 가리킬 때 W3C 추적 컨텍스트를 전파하려면 `1`로 설정합니다. 전파 대상은 모델 및 HTTP MCP 요청의 `traceparent` 헤더와 Bash, PowerShell, 훅 하위 프로세스의 `TRACEPARENT` 환경 변수입니다. 기본적으로 전파는 Anthropic API에 직접 연결된 경우에만 활성화됩니다. v2.1.152에서 추가되었습니다. [트레이스(베타)](/docs/ko/monitoring-usage#traces-beta)를 참조하세요 |364| `CLAUDE_CODE_PROPAGATE_TRACEPARENT` | `ANTHROPIC_BASE_URL`이 사용자 지정 프록시를 가리킬 때 W3C 트레이스 컨텍스트를 전파하려면 `1`로 설정합니다. 전파 대상은 모델 및 HTTP MCP 요청의 `traceparent` 헤더와 Bash, PowerShell, 훅 하위 프로세스의 `TRACEPARENT` 환경 변수입니다. 기본적으로 전파는 Anthropic API에 직접 연결된 경우에만 활성화됩니다. v2.1.152에서 추가되었습니다. [트레이스(베타)](/docs/ko/monitoring-usage#traces-beta)를 참조하십시오 |

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

364| `CLAUDE_CODE_PROXY_RESOLVES_HOSTS` | 호출자 대신 프록시가 DNS 확인을 수행하도록 허용하려면 `1`로 설정합니다. 프록시가 호스트 이름 확인을 처리해야 하는 환경을 위한 옵트인 설정입니다 |366| `CLAUDE_CODE_PROXY_RESOLVES_HOSTS` | 호출자 대신 프록시가 DNS 확인을 수행하도록 허용하려면 `1`로 설정합니다. 프록시가 호스트 이름 확인을 처리해야 하는 환경을 위한 옵트인 설정입니다 |

365| `CLAUDE_CODE_REMOTE` | Claude Code가 [클라우드 세션](/docs/ko/claude-code-on-the-web)으로 실행될 때 자동으로 `true`로 설정됩니다. 훅이나 설정 스크립트에서 이 값을 읽어 클라우드 세션 여부를 감지합니다 |367| `CLAUDE_CODE_REMOTE` | Claude Code가 [클라우드 세션](/docs/ko/claude-code-on-the-web)으로 실행될 때 자동으로 `true`로 설정됩니다. 훅이나 설정 스크립트에서 이 값을 읽어 클라우드 세션인지 감지할 수 있습니다 |

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

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

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

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

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

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

372| `CLAUDE_CODE_SAFE_MODE` | 손상된 구성의 문제 해결을 위해 안전 모드로 시작하려면 `1`로 설정합니다. 안전 모드에서는 CLAUDE.md, 스킬, 플러그인, 훅, MCP 서버, 사용자 지정 명령 및 에이전트, 출력 스타일, 워크플로, 사용자 지정 테마, 사용자 지정 키보드 단축키, 상태줄 및 파일 제안 명령, LSP 서버, 자동 메모리가 로드되지 않습니다. 정책으로 구성된 훅, 상태줄, 파일 제안 명령을 포함한 관리형 설정 정책은 계속 적용되지만, 관리형 플러그인, 관리형 스킬, 관리형 CLAUDE.md, 정책으로 구성된 MCP 서버는 적용되지 않습니다. [`--safe-mode`](/docs/ko/cli-reference#cli-flags)를 전달하는 것과 동일합니다. 직접 생성된 자식 프로세스는 이 변수를 상속합니다 |374| `CLAUDE_CODE_SAFE_MODE` | 손상된 구성의 문제 해결을 위해 안전 모드로 시작하려면 `1`로 설정합니다. 안전 모드에서는 CLAUDE.md, 스킬, 플러그인, 훅, MCP 서버, 사용자 지정 명령 및 에이전트, 출력 스타일, 워크플로, 사용자 지정 테마, 사용자 지정 키보드 단축키, 상태줄 및 파일 제안 명령, LSP 서버, 자동 메모리가 로드되지 않습니다. 정책으로 구성된 훅, 상태줄, 파일 제안 명령을 포함한 관리형 설정 정책은 계속 적용되지만, 관리형 플러그인, 관리형 스킬, 관리형 CLAUDE.md, 정책으로 구성된 MCP 서버는 적용되지 않습니다. [`--safe-mode`](/docs/ko/cli-reference#cli-flags)를 전달하는 것과 같습니다. 직접 생성된 자식 프로세스는 이 변수를 상속합니다 |

373| `CLAUDE_CODE_SCRIPT_CAPS` | `CLAUDE_CODE_SUBPROCESS_ENV_SCRUB`가 설정된 경우 특정 스크립트를 세션당 호출할 수 있는 횟수를 제한하는 JSON 객체입니다. 키는 명령 텍스트와 대조되는 하위 문자열이고, 값은 정수 호출 제한입니다. 예를 들어 `{"deploy.sh": 2}`는 `deploy.sh`를 최대 두 번까지 호출할 수 있도록 허용합니다. 일치는 하위 문자열 기반이므로 `./scripts/deploy.sh $(evil)`과 같은 셸 확장 기법도 상한에 포함됩니다. `xargs` 또는 `find -exec`를 통한 런타임 팬아웃은 감지되지 않으며, 이는 심층 방어 제어입니다 |375| `CLAUDE_CODE_SCRIPT_CAPS` | `CLAUDE_CODE_SUBPROCESS_ENV_SCRUB`이 설정된 경우 특정 스크립트를 세션당 호출할 수 있는 횟수를 제한하는 JSON 객체입니다. 키는 명령 텍스트와 비교되는 부분 문자열이고, 값은 정수 호출 제한입니다. 예를 들어 `{"deploy.sh": 2}`는 `deploy.sh`를 최대 두 번까지 호출할 수 있도록 허용합니다. 부분 문자열 기반으로 일치하므로 `./scripts/deploy.sh $(evil)`과 같은 셸 확장 트릭도 상한에 포함됩니다. `xargs` 또는 `find -exec`를 통한 런타임 팬아웃은 감지되지 않습니다. 이는 심층 방어 제어입니다 |

374| `CLAUDE_CODE_SCROLL_SPEED` | [전체 화면 렌더링](/docs/ko/fullscreen#mouse-wheel-scrolling)에서 마우스 휠 스크롤 배율을 설정합니다. 20 이하의 모든 양수 값을 허용하며, 이미 휠 이벤트를 증폭하는 터미널에서 가속된 트랙패드 및 휠 스크롤을 늦추기 위한 `0.5`와 같은 1 미만의 소수 값도 허용합니다. 터미널이 증폭 없이 노치당 하나의 휠 이벤트를 보내는 경우 `vim`과 맞추려면 `3`으로 설정합니다. Claude Code가 자체 스크롤 처리를 사용하는 JetBrains IDE 터미널에서는 무시됩니다 |376| `CLAUDE_CODE_SCROLL_SPEED` | [전체 화면 렌더링](/docs/ko/fullscreen#mouse-wheel-scrolling)에서 마우스 휠 스크롤 배율을 설정합니다. 최대 20까지의 양수 값을 허용하며, 이미 휠 이벤트를 증폭하는 터미널에서 가속된 트랙패드 및 휠 스크롤을 느리게 하려면 `0.5`와 같이 1 미만의 소수 값도 사용할 수 있습니다. 터미널이 증폭 없이 한 칸당 하나의 휠 이벤트를 보내는 경우 `vim`과 맞추려면 `3`으로 설정합니다. Claude Code가 자체 스크롤 처리를 사용하는 JetBrains IDE 터미널에서는 무시됩니다 |

375| `CLAUDE_CODE_SEND_FEEDBACK` | 세션에서 [Claude가 작성하는 피드백](/docs/ko/tools-reference#sendfeedback-tool-behavior)을 끄려면 `0`으로 설정합니다. 계정에 이미 액세스 권한이 있는 경우 켜려면 `1`로 설정합니다. 이 변수 자체로는 액세스 권한을 부여할 수 없으며, `DISABLE_FEEDBACK_COMMAND` 및 [`feedbackDrafts`](/docs/ko/settings-reference#feedbackdrafts) 설정의 `off` 값과 같이 피드백을 끄는 다른 스위치는 계속 적용됩니다 |377| `CLAUDE_CODE_SEND_FEEDBACK` | 세션에서 [Claude가 작성하는 피드백](/docs/ko/tools-reference#sendfeedback-tool-behavior)을 끄려면 `0`으로 설정합니다. 계정에 이미 접근 권한이 있는 경우 켜려면 `1`로 설정합니다. 이 변수 자체로는 접근 권한을 부여할 수 없으며, `DISABLE_FEEDBACK_COMMAND` 및 [`feedbackDrafts`](/docs/ko/settings-reference#feedbackdrafts) 설정의 `off` 값과 같이 피드백을 끄는 다른 스위치는 계속 적용됩니다 |

376| `CLAUDE_CODE_SESSIONEND_HOOKS_TIMEOUT_MS` | [SessionEnd](/docs/ko/hooks#sessionend) 훅의 시간 예산(밀리초)을 재정의합니다. 이 값은 자체 `timeout`을 설정하지 않은 각 훅의 타임아웃이기도 합니다. 세션 종료, `/clear`, 대화형 `/resume`을 통한 세션 전환에 적용됩니다. 기본 예산은 1.5초이며, 설정 파일에 구성된 훅별 `timeout` 중 가장 높은 값으로 최대 60초까지 자동으로 늘어납니다. 플러그인이 제공하는 훅의 타임아웃은 예산을 늘리지 않습니다 |378| `CLAUDE_CODE_SESSIONEND_HOOKS_TIMEOUT_MS` | [SessionEnd](/docs/ko/hooks#sessionend) 훅의 시간 예산(밀리초)을 재정의합니다. 이 값은 자체 `timeout`을 설정하지 않은 각 훅의 타임아웃이기도 합니다. 세션 종료, `/clear`, 대화형 `/resume`을 통한 세션 전환에 적용됩니다. 기본 예산은 1.5초이며, 설정 파일에 구성된 훅별 `timeout` 중 가장 높은 값으로 최대 60초까지 자동으로 높아집니다. 플러그인이 제공하는 훅의 타임아웃은 예산을 높이지 않습니다 |

377| `CLAUDE_CODE_SESSION_ID` | Bash 및 PowerShell 도구 하위 프로세스, [훅 명령](/docs/ko/hooks) 하위 프로세스, stdio [MCP 서버](/docs/ko/mcp) 하위 프로세스에서 현재 세션 ID로 자동 설정됩니다. Bash, PowerShell, 훅의 경우 이 값은 훅 JSON 입력의 `session_id` 필드와 일치하며 `/clear` 시 업데이트됩니다. MCP 서버 하위 프로세스는 생성될 때의 ID를 유지합니다. `--resume <session-id>`에서는 재개된 ID를 받아 훅 및 Bash와 일치합니다. 명시적 ID 없이 `--continue` 또는 `--resume`을 사용하면 대신 초기 시작 ID를 받을 수 있습니다. 스크립트와 외부 도구를 이를 실행한 Claude Code 세션과 연관시키는 데 사용합니다 |379| `CLAUDE_CODE_SESSION_ID` | Bash 및 PowerShell 도구 하위 프로세스, [훅 명령](/docs/ko/hooks) 하위 프로세스, stdio [MCP 서버](/docs/ko/mcp) 하위 프로세스에서 현재 세션 ID로 자동 설정됩니다. Bash, PowerShell, 훅의 경우 이 값은 훅 JSON 입력의 `session_id` 필드와 일치하며 `/clear` 시 업데이트됩니다. MCP 서버 하위 프로세스는 생성될 때의 ID를 유지합니다. `--resume <session-id>`에서는 훅 및 Bash와 일치하는 재개된 ID를 받습니다. 명시적 ID 없이 `--continue` 또는 `--resume`을 사용하면 대신 초기 시작 ID를 받을 수 있습니다. 스크립트와 외부 도구를 이를 실행한 Claude Code 세션과 연관시키는 데 사용합니다 |

378| `CLAUDE_CODE_SHELL` | Claude Code가 Bash 도구 명령을 실행하는 데 사용하는 셸을 설정합니다. `bash` 또는 `zsh` 바이너리 경로를 허용합니다(예: `/opt/homebrew/bin/bash`). `fish`와 같은 다른 셸은 지원되지 않습니다. 값이 작동하는 `bash` 또는 `zsh` 경로가 아니면 Claude Code는 이를 무시하고 자동 감지로 폴백합니다. 자동 감지는 `$SHELL`이 `bash` 또는 `zsh`를 가리키면 이를 사용하고, 그렇지 않으면 `PATH`와 표준 설치 위치에서 찾은 첫 번째로 작동하는 `zsh`, 그다음 `bash`를 선택합니다 |380| `CLAUDE_CODE_SHELL` | Claude Code가 Bash 도구 명령을 실행하는 데 사용하는 셸을 설정합니다. `/opt/homebrew/bin/bash`와 같은 `bash` 또는 `zsh` 바이너리 경로를 허용합니다. `fish`와 같은 다른 셸은 지원되지 않습니다. 값이 작동하는 `bash` 또는 `zsh` 경로가 아니면 Claude Code는 이를 무시하고 자동 감지로 폴백합니다. 자동 감지는 `$SHELL`이 `bash` 또는 `zsh`를 가리키면 이를 사용하고, 그렇지 않으면 `PATH`와 표준 설치 위치에서 찾은 첫 번째 작동하는 `zsh`, 그다음 `bash`를 선택합니다 |

379| `CLAUDE_CODE_SHELL_PREFIX` | Claude Code가 생성하는 셸 명령을 감싸는 명령 접두사입니다. 대상은 Bash 도구 호출, [훅](/docs/ko/hooks) 명령, [상태줄](/docs/ko/statusline) 명령, stdio [MCP 서버](/docs/ko/mcp) 시작 명령입니다. PowerShell 훅과 exec 형식 훅은 접두사 없이 실행됩니다. 로깅이나 감사에 유용합니다. `/path/to/logger.sh`와 같은 단순 실행 파일 경로를 설정하면 각 명령이 `/path/to/logger.sh '<command>'`로 실행됩니다. 래퍼는 명령줄을 `$1`에 단일 셸 인용 인수로 받으므로, 래퍼는 `exec bash -c "$1"`처럼 셸로 `$1`을 다시 평가해야 합니다. `$1`을 단순 실행 파일 경로로 취급하면 `npx -y <package>`와 같은 인수를 전달하는 stdio MCP 서버가 작동하지 않습니다. Bash 도구 호출의 경우 `$1`에는 Claude가 실행한 명령뿐 아니라 환경 설정을 포함하여 Claude Code가 조합한 전체 셸 호출이 포함됩니다 |381| `CLAUDE_CODE_SHELL_PREFIX` | Claude Code가 생성하는 셸 명령을 감싸는 명령 접두사입니다. Bash 도구 호출, [훅](/docs/ko/hooks) 명령, [상태줄](/docs/ko/statusline) 명령, stdio [MCP 서버](/docs/ko/mcp) 시작 명령에 적용됩니다. PowerShell 훅과 exec 형식 훅은 접두사 없이 실행됩니다. 로깅이나 감사에 유용합니다. `/path/to/logger.sh`와 같은 실행 파일 경로만 설정하면 각 명령이 `/path/to/logger.sh '<command>'`로 실행됩니다. 래퍼는 명령줄을 `$1`에 셸 인용된 단일 인수로 받으므로, 래퍼는 `exec bash -c "$1"`처럼 셸로 `$1`을 다시 평가해야 합니다. `$1`을 단순 실행 파일 경로로 취급하면 `npx -y <package>`와 같은 인수를 전달하는 stdio MCP 서버가 작동하지 않습니다. Bash 도구 호출의 경우 `$1`에는 Claude가 실행한 명령뿐 아니라 환경 설정을 포함하여 Claude Code가 조합한 전체 셸 호출이 들어 있습니다 |

380| `CLAUDE_CODE_SIMPLE` | 최소한의 시스템 프롬프트와 Bash, 파일 읽기, 파일 편집 도구만으로 실행하려면 `1`로 설정합니다. `--mcp-config`의 MCP 도구는 계속 사용할 수 있습니다. 훅, 스킬, 사용자 지정 명령, 서브에이전트, 설치된 플러그인, MCP 서버, 자동 메모리, CLAUDE.md의 자동 검색을 비활성화합니다. `--add-dir`로 전달한 디렉터리의 스킬은 계속 로드됩니다. OAuth 토큰과 키체인 자격 증명을 읽지 않으므로 Anthropic 인증은 `ANTHROPIC_API_KEY` 또는 `--settings`의 `apiKeyHelper`에서 제공되어야 합니다. [`--bare`](/docs/ko/headless#start-faster-with-bare-mode)를 전달하는 것과 동일합니다 |382| `CLAUDE_CODE_SIMPLE` | 최소한의 시스템 프롬프트와 Bash, 파일 읽기, 파일 편집 도구만으로 실행하려면 `1`로 설정합니다. `--mcp-config`의 MCP 도구는 계속 사용할 수 있습니다. 훅, 스킬, 사용자 지정 명령, 서브에이전트, 설치된 플러그인, MCP 서버, 자동 메모리, CLAUDE.md의 자동 검색을 비활성화합니다. `--add-dir`로 전달한 디렉터리의 스킬은 계속 로드됩니다. OAuth 토큰과 키체인 자격 증명을 읽지 않으므로 Anthropic 인증은 `ANTHROPIC_API_KEY` 또는 `--settings`의 `apiKeyHelper`에서 제공되어야 합니다. [`--bare`](/docs/ko/headless#start-faster-with-bare-mode)를 전달하는 것과 같습니다 |

381| `CLAUDE_CODE_SIMPLE_SYSTEM_PROMPT` | 모든 모델에서 더 짧은 시스템 프롬프트와 축약된 도구 설명을 사용하려면 `1`로 설정합니다. 실험이나 서버 구성에 의해 활성화되는 모델에서도 옵트아웃하려면 `0`, `false`, `no` 또는 `off`로 설정합니다. 전체 도구 세트, 훅, MCP 서버, CLAUDE.md 검색은 계속 활성화됩니다 |383| `CLAUDE_CODE_SIMPLE_SYSTEM_PROMPT` | 모든 모델에서 더 짧은 시스템 프롬프트와 축약된 도구 설명을 사용하려면 `1`로 설정합니다. 실험이나 서버 구성에 의해 활성화될 모델에서도 사용하지 않으려면 `0`, `false`, `no` 또는 `off`로 설정합니다. 전체 도구 세트, 훅, MCP 서버, CLAUDE.md 검색은 활성화된 상태로 유지됩니다 |

382| `CLAUDE_CODE_SKIP_ANTHROPIC_AWS_AUTH` | 요청에 직접 서명하는 게이트웨이를 위해 [Claude Platform on AWS](/docs/ko/claude-platform-on-aws)의 클라이언트 측 인증을 건너뜁니다 |384| `CLAUDE_CODE_SKIP_ANTHROPIC_AWS_AUTH` | 요청에 자체적으로 서명하는 게이트웨이를 위해 [Claude Platform on AWS](/docs/ko/claude-platform-on-aws)의 클라이언트 측 인증을 건너뜁니다 |

383| `CLAUDE_CODE_SKIP_AWS_CRED_CACHE` | AWS 기본 자격 증명 공급자 체인에서 확인된 자격 증명의 프로세스 내 캐시를 끄려면 `1`로 설정합니다. 그러면 Claude Code가 모든 API 요청에서 체인을 확인합니다. 캐시가 꺼져 있으면 SSO 기반 프로필은 모든 요청에서 IAM Identity Center에 자격 증명을 요청합니다. [자격 증명 캐싱 및 확인 타임아웃](/docs/ko/amazon-bedrock#credential-caching-and-resolution-timeout)을 참조하세요. Claude Code v2.1.207 이상이 필요합니다 |385| `CLAUDE_CODE_SKIP_AWS_CRED_CACHE` | AWS 기본 자격 증명 공급자 체인에서 확인한 자격 증명의 인프로세스 캐시를 끄려면 `1`로 설정합니다. 그러면 Claude Code가 모든 API 요청마다 체인을 확인합니다. 캐시가 꺼져 있으면 SSO 기반 프로필은 요청마다 IAM Identity Center에 자격 증명을 요청합니다. [자격 증명 캐싱 및 확인 타임아웃](/docs/ko/amazon-bedrock#credential-caching-and-resolution-timeout)을 참조하십시오. Claude Code v2.1.207 이상이 필요합니다 |

385| `CLAUDE_CODE_SKIP_FAST_MODE_NETWORK_ERRORS` | 검사의 `api.anthropic.com` 직접 요청을 차단하는 네트워크를 위해, 실패한 [빠른 모드](/docs/ko/fast-mode#use-fast-mode-behind-proxies-and-llm-gateways) 가용성 검사를 사용 가능으로 처리하려면 `1`로 설정합니다. Claude Code는 "disabled by your organization" 응답은 여전히 따릅니다 |387| `CLAUDE_CODE_SKIP_FAST_MODE_NETWORK_ERRORS` | 검사의 `api.anthropic.com` 직접 요청을 차단하는 네트워크를 위해, 실패한 [빠른 모드](/docs/ko/fast-mode#use-fast-mode-behind-proxies-and-llm-gateways) 사용 가능 여부 검사를 사용 가능으로 처리하려면 `1`로 설정합니다. Claude Code는 "disabled by your organization" 응답은 계속 따릅니다 |

386| `CLAUDE_CODE_SKIP_FAST_MODE_ORG_CHECK` | 검사 요청을 거부하지 않고 가로채는 프록시를 위해 클라이언트 측 [빠른 모드](/docs/ko/fast-mode#use-fast-mode-behind-proxies-and-llm-gateways) 가용성 검사를 건너뛰려면 `1`로 설정합니다. 조직에서 빠른 모드를 비활성화한 경우 API는 여전히 빠른 모드 요청을 거부합니다 |388| `CLAUDE_CODE_SKIP_FAST_MODE_ORG_CHECK` | 검사 요청을 거부하지 않고 가로채는 프록시를 위해, 클라이언트 측 [빠른 모드](/docs/ko/fast-mode#use-fast-mode-behind-proxies-and-llm-gateways) 사용 가능 여부 검사를 건너뛰려면 `1`로 설정합니다. 조직에서 빠른 모드가 비활성화된 경우 API는 여전히 빠른 모드 요청을 거부합니다 |

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

389| `CLAUDE_CODE_SKIP_MODEL_ACCESS_MEMORY` | [Amazon Bedrock](/docs/ko/amazon-bedrock) 및 [Google Cloud의 Agent Platform](/docs/ko/google-vertex-ai)의 [시작 모델 검사](/docs/ko/amazon-bedrock#startup-model-checks)는 계정이 호출할 수 없는 것으로 확인된 모델을 최대 하루 동안 이 머신에 기억합니다. 이 기억 기능을 끄려면 `1`로 설정합니다. Claude Code v2.1.285 이상이 필요합니다 |391| `CLAUDE_CODE_SKIP_MODEL_ACCESS_MEMORY` | [Amazon Bedrock](/docs/ko/amazon-bedrock) 및 [Google Cloud's Agent Platform](/docs/ko/google-vertex-ai)의 [시작 모델 검사](/docs/ko/amazon-bedrock#startup-model-checks)는 계정이 호출할 수 없는 것으로 확인된 모델을 이 머신에 최대 하루 동안 기억합니다. 이 기억 기능을 끄려면 `1`로 설정합니다. Claude Code v2.1.285 이상이 필요합니다 |

390| `CLAUDE_CODE_SKIP_PROMPT_HISTORY` | 프롬프트 기록과 세션 트랜스크립트를 디스크에 쓰지 않으려면 `1`로 설정합니다. 이 변수를 설정한 상태로 시작한 세션은 `--resume`, `--continue` 또는 위쪽 화살표 기록에 표시되지 않습니다. 일회성 스크립트 세션에 유용합니다 |392| `CLAUDE_CODE_SKIP_PROMPT_HISTORY` | 프롬프트 기록과 세션 트랜스크립트를 디스크에 쓰지 않으려면 `1`로 설정합니다. 이 변수가 설정된 상태로 시작한 세션은 `--resume`, `--continue` 또는 위쪽 화살표 기록에 나타나지 않습니다. 일회성 스크립트 세션에 유용합니다 |

392| `CLAUDE_CODE_STARTUP_FAILURE_RESULTS` | `--output-format stream-json`으로 시작한 세션이, 그렇지 않으면 stderr 출력만으로 끝나는 시작 실패에 대해 [Claude Code가 시작을 거부한 이유를 명시하는 결과 메시지](/docs/ko/agent-sdk/typescript#startup_failure_reason)를 쓰도록 하려면 `1`로 설정합니다. Claude Code v2.1.274 이상이 필요합니다 |394| `CLAUDE_CODE_STARTUP_FAILURE_RESULTS` | `--output-format stream-json`으로 시작한 세션이, 그렇지 않으면 stderr 출력만으로 끝나는 시작 실패에 대해 [Claude Code가 시작을 거부한 이유를 명시하는 결과 메시지](/docs/ko/agent-sdk/typescript#startup_failure_reason)를 쓰도록 하려면 `1`로 설정합니다. Claude Code v2.1.274 이상이 필요합니다 |

393| `CLAUDE_CODE_STOP_HOOK_BLOCK_CAP` | Claude Code가 [Stop](/docs/ko/hooks#stop) 또는 [SubagentStop](/docs/ko/hooks#subagentstop) 훅을 무시하고 턴을 종료하기 전까지, 해당 훅이 턴 종료를 연속으로 차단할 수 있는 최대 횟수입니다(기본값: 8). 상한을 비활성화하려면 `0`으로 설정합니다. 훅이 해결을 위해 실제로 더 많은 반복이 필요하다면 이 값을 늘립니다 |395| `CLAUDE_CODE_STOP_HOOK_BLOCK_CAP` | Claude Code가 이를 무시하고 턴을 종료하기 전까지 [Stop](/docs/ko/hooks#stop) 또는 [SubagentStop](/docs/ko/hooks#subagentstop) 훅이 턴 종료를 연속으로 차단할 수 있는 최대 횟수입니다(기본값: 8). 상한을 비활성화하려면 `0`으로 설정합니다. 훅이 해결하는 데 정당하게 더 많은 반복이 필요한 경우 이 값을 높이십시오 |

394| `CLAUDE_CODE_SUBAGENT_MODEL` | 다른 방식으로 모델이 할당되지 않은 [서브에이전트](/docs/ko/sub-agents#choose-a-model), [에이전트 팀](/docs/ko/agent-teams#specify-teammates-and-models) 팀원, [워크플로](/docs/ko/workflows) 에이전트의 기본 모델입니다. `haiku`와 같은 별칭이나 전체 모델 이름을 허용합니다. 두 가지 소스가 이 변수보다 우선합니다. Claude가 에이전트를 생성할 때 전달하는 모델과, `inherit`을 포함한 에이전트 정의의 `model` 필드입니다. 이를 변경하려면 [`CLAUDE_CODE_SUBAGENT_MODEL_FORCE`](/docs/ko/sub-agents#run-every-subagent-on-one-model)를 설정합니다. 전체 순서는 [모델 선택](/docs/ko/sub-agents#choose-a-model)을 참조하세요. `inherit`으로 설정하는 것은 설정하지 않는 것과 같습니다. v2.1.251 이전에는 이 변수가 호출별 모델과 정의의 `model` 필드를 모두 재정의했습니다 |396| `CLAUDE_CODE_SUBAGENT_MODEL` | 다른 방법으로 모델이 지정되지 않은 [서브에이전트](/docs/ko/sub-agents#choose-a-model), [에이전트 팀](/docs/ko/agent-teams#specify-teammates-and-models) 팀원, [워크플로](/docs/ko/workflows) 에이전트의 기본 모델입니다. `haiku`와 같은 별칭 또는 전체 모델 이름을 허용합니다. 두 가지 소스가 이 변수보다 우선합니다. Claude가 에이전트를 생성할 때 전달하는 모델과, `inherit`를 포함한 에이전트 정의의 `model` 필드입니다. 이를 변경하려면 [`CLAUDE_CODE_SUBAGENT_MODEL_FORCE`](/docs/ko/sub-agents#run-every-subagent-on-one-model)를 설정하십시오. 전체 순서는 [모델 선택](/docs/ko/sub-agents#choose-a-model)을 참조하십시오. `inherit`로 설정하는 것은 설정하지 않는 것과 같습니다. v2.1.251 이전에는 이 변수가 호출별 모델과 정의의 `model` 필드를 모두 재정의했습니다 |

395| `CLAUDE_CODE_SUBAGENT_MODEL_FORCE` | 서브에이전트, 팀원, 워크플로 에이전트에 하나의 모델을 강제하려면 `1`로 설정합니다. 어떤 모델인지는 [모든 서브에이전트를 하나의 모델로 실행](/docs/ko/sub-agents#run-every-subagent-on-one-model)에서 설명합니다. Claude Code v2.1.257 이상이 필요합니다 |397| `CLAUDE_CODE_SUBAGENT_MODEL_FORCE` | 서브에이전트, 팀원, 워크플로 에이전트에 하나의 모델을 강제로 적용하려면 `1`로 설정합니다. 해당 모델이 무엇인지는 [모든 서브에이전트를 하나의 모델로 실행](/docs/ko/sub-agents#run-every-subagent-on-one-model)에서 설명합니다. Claude Code v2.1.257 이상이 필요합니다 |

396| `CLAUDE_CODE_SUBAGENT_PROMPT_CACHE_TTL` | Claude Code가 허용하는 유일한 값인 `5m` 또는 `1h`로 설정하여 [서브에이전트](/docs/ko/sub-agents), 워크플로, 백그라운드 작업과 같이 주 대화 외부의 요청에 대한 [프롬프트 캐시 TTL](/docs/ko/prompt-caching#cache-lifetime)을 선택합니다. `subagentPromptCacheTtl` 설정과 `ENABLE_PROMPT_CACHING_1H`보다 우선하며, `FORCE_PROMPT_CACHING_5M`이 이 변수를 재정의합니다. API는 1시간 캐시 쓰기에 더 높은 요율을 청구합니다. Claude Code v2.1.242 이상이 필요합니다 |398| `CLAUDE_CODE_SUBAGENT_PROMPT_CACHE_TTL` | Claude Code가 허용하는 유일한 값인 `5m` 또는 `1h`로 설정하여 [서브에이전트](/docs/ko/sub-agents), 워크플로, 백그라운드 작업과 같이 메인 대화 외부의 요청에 대한 [프롬프트 캐시 TTL](/docs/ko/prompt-caching#cache-lifetime)을 선택합니다. `subagentPromptCacheTtl` 설정과 `ENABLE_PROMPT_CACHING_1H`보다 우선하며, `FORCE_PROMPT_CACHING_5M`이 이 변수를 재정의합니다. API는 1시간 캐시 쓰기에 더 높은 요금을 청구합니다. Claude Code v2.1.242 이상이 필요합니다 |

397| `CLAUDE_CODE_SUBPROCESS_ENV_SCRUB` | 하위 프로세스 환경(Bash 도구, 훅, MCP stdio 서버)에서 자격 증명을 제거하려면 `1`로 설정합니다. 제거 대상은 Anthropic 및 클라우드 공급자 자격 증명, Claude Code가 자격 증명으로 인식하는 기타 모든 변수, 패키지 레지스트리 URL에 포함된 자격 증명입니다. 부모 Claude 프로세스는 API 호출을 위해 이러한 자격 증명을 유지하지만 자식 프로세스는 이를 읽을 수 없으므로, 셸 확장을 통해 비밀을 유출하려는 프롬프트 인젝션 공격에 대한 노출이 줄어듭니다. v2.1.251 이상에서는 Claude Code 자체의 구성 스토어 포인터 변수(예: `CLAUDE_CONFIG_DIR`)도 제거하므로, 자식 프로세스가 위치가 변경된 구성 디렉터리를 찾을 수 없습니다. 하위 프로세스에 이러한 변수가 필요하면 이 변수를 설정하지 않습니다. Linux에서는 Bash 하위 프로세스를 격리된 PID 네임스페이스에서 실행하여 `/proc`를 통해 호스트 프로세스 환경을 읽을 수 없도록 합니다. 부작용으로 `ps`, `pgrep`, `kill`은 호스트 프로세스를 보거나 신호를 보낼 수 없습니다. `claude-code-action`은 `allowed_non_write_users`가 구성되면 이 변수를 자동으로 설정합니다 |399| `CLAUDE_CODE_SUBPROCESS_ENV_SCRUB` | Bash 명령, 훅, stdio MCP 서버와 같이 Claude Code가 시작하는 하위 프로세스의 환경에서 자격 증명을 제거하려면 `1`로 설정합니다. 이 정리 기능은 변수 이름이나 값으로 자격 증명을 인식하며, GitHub 토큰과 프록시 설정은 그대로 둡니다. [하위 프로세스 환경 정리가 제거하는 항목](#what-the-subprocess-environment-scrub-removes)을 참조하십시오. `allowed_non_write_users`가 구성된 경우 `claude-code-action`이 이 값을 자동으로 설정합니다 |

398| `CLAUDE_CODE_SYNC_PLUGIN_INSTALL` | 비대화형 모드(`-p` 플래그)에서 첫 번째 쿼리 전에 플러그인 설치가 완료될 때까지 기다리려면 `1`로 설정합니다. 이 설정이 없으면 플러그인이 백그라운드에서 설치되어 첫 번째 턴에서 사용하지 못할 수 있습니다. 대기 시간을 제한하려면 `CLAUDE_CODE_SYNC_PLUGIN_INSTALL_TIMEOUT_MS`와 함께 사용합니다 |400| `CLAUDE_CODE_SYNC_PLUGIN_INSTALL` | 비대화형 모드(`-p` 플래그)에서 첫 번째 쿼리 전에 플러그인 설치가 완료될 때까지 기다리려면 `1`로 설정합니다. 이 설정이 없으면 플러그인은 백그라운드에서 설치되며 첫 번째 턴에서 사용하지 못할 수 있습니다. 대기 시간을 제한하려면 `CLAUDE_CODE_SYNC_PLUGIN_INSTALL_TIMEOUT_MS`와 함께 사용하십시오 |

399| `CLAUDE_CODE_SYNC_PLUGIN_INSTALL_TIMEOUT_MS` | 동기식 플러그인 설치의 타임아웃(밀리초)입니다. 초과하면 Claude Code는 플러그인 없이 진행하고 오류를 로그에 기록합니다. 기본값 없음: 이 변수가 없으면 동기식 설치는 완료될 때까지 기다립니다 |401| `CLAUDE_CODE_SYNC_PLUGIN_INSTALL_TIMEOUT_MS` | 동기식 플러그인 설치의 타임아웃(밀리초)입니다. 초과하면 Claude Code는 플러그인 없이 진행하고 오류를 로그에 기록합니다. 기본값이 없습니다. 이 변수가 없으면 동기식 설치는 완료될 때까지 기다립니다 |

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

401| `CLAUDE_CODE_SYNC_SKILLS_INSTALL_TIMEOUT_MS` | [Agent SDK](/docs/ko/agent-sdk/typescript#query-object)로 빌드된 앱이 스킬을 다시 로드할 때 세션 도중 실행되는 스킬 재동기화의 타임아웃(밀리초)입니다(기본값: 30000). 초과하면 다시 로드는 도착한 스킬로 계속 진행되고, 나머지 다운로드는 백그라운드에서 완료됩니다 |403| `CLAUDE_CODE_SYNC_SKILLS_INSTALL_TIMEOUT_MS` | [Agent SDK](/docs/ko/agent-sdk/typescript#query-object) 기반 앱이 스킬을 다시 로드할 때 세션 도중 실행되는 스킬 재동기화의 타임아웃(밀리초)입니다(기본값: 30000). 초과하면 도착한 스킬로 다시 로드가 계속되며, 나머지 다운로드는 백그라운드에서 완료됩니다 |

402| `CLAUDE_CODE_SYNC_SKILLS_WAIT_TIMEOUT_MS` | `CLAUDE_CODE_SYNC_SKILLS`가 설정된 경우 첫 번째 쿼리가 초기 스킬 목록을 기다리는 타임아웃(밀리초)입니다(기본값: 5000). 초과하면 첫 번째 쿼리는 도착한 스킬로 실행됩니다. 어느 경우든 다운로드는 백그라운드에서 완료되며, Claude는 스킬을 호출할 때 해당 스킬의 다운로드를 기다립니다 |404| `CLAUDE_CODE_SYNC_SKILLS_WAIT_TIMEOUT_MS` | `CLAUDE_CODE_SYNC_SKILLS`가 설정된 경우 첫 번째 쿼리가 초기 스킬 목록을 기다리는 타임아웃(밀리초)입니다(기본값: 5000). 초과하면 첫 번째 쿼리는 도착한 스킬로 실행됩니다. 어느 경우든 다운로드는 백그라운드에서 완료되며, Claude는 스킬을 호출할 때 해당 스킬의 다운로드를 기다립니다 |

403| `CLAUDE_CODE_SYNTAX_HIGHLIGHT` | diff 출력에서 구문 강조를 비활성화하려면 `false`로 설정합니다. 색상이 터미널 설정을 방해할 때 유용합니다. 코드 블록과 파일 미리 보기에서도 강조를 비활성화하려면 [`syntaxHighlightingDisabled`](/docs/ko/settings-reference#syntaxhighlightingdisabled) 설정을 사용합니다 |405| `CLAUDE_CODE_SYNTAX_HIGHLIGHT` | diff 출력에서 구문 강조를 비활성화하려면 `false`로 설정합니다. 색상이 터미널 설정과 충돌할 때 유용합니다. 코드 블록과 파일 미리보기에서도 강조를 비활성화하려면 [`syntaxHighlightingDisabled`](/docs/ko/settings-reference#syntaxhighlightingdisabled) 설정을 사용하십시오 |

404| `CLAUDE_CODE_TASK_LIST_ID` | 세션 간에 작업 목록을 공유합니다. [Task 도구가 있는 세션](/docs/ko/tools-reference#task-tool-availability)에서 여러 Claude Code 인스턴스에 동일한 ID를 설정하여 공유 작업 목록으로 협업합니다. [작업 목록](/docs/ko/interactive-mode#task-list)을 참조하세요 |406| `CLAUDE_CODE_TASK_LIST_ID` | 세션 간에 작업 목록을 공유합니다. [Task 도구가 있는 세션](/docs/ko/tools-reference#task-tool-availability)에서 여러 Claude Code 인스턴스에 동일한 ID를 설정하여 공유 작업 목록으로 협업합니다. [작업 목록](/docs/ko/interactive-mode#task-list)을 참조하십시오 |

405| `CLAUDE_CODE_TEAM_TEARDOWN_PARK_TIMEOUT_MS` | 비대화형 세션이 종료 시 [에이전트 팀](/docs/ko/agent-teams) 해체가 완료될 때까지 기다리는 시간을 밀리초 단위로 재정의합니다. 1000에서 60000까지 허용하며, 범위를 벗어난 값은 무시되고 기본값 10000이 적용됩니다. Claude Code v2.1.206 이상이 필요합니다 |407| `CLAUDE_CODE_TEAM_TEARDOWN_PARK_TIMEOUT_MS` | 비대화형 세션이 종료 시 [에이전트 팀](/docs/ko/agent-teams)의 해체가 완료될 때까지 기다리는 시간을 밀리초 단위로 재정의합니다. 1000에서 60000까지 허용되며, 범위를 벗어난 값은 무시되고 기본값 10000이 적용됩니다. Claude Code v2.1.206 이상이 필요합니다 |

406| `CLAUDE_CODE_TMPDIR` | 내부 임시 파일에 사용되는 임시 디렉터리를 재정의합니다. Claude Code는 Unix에서는 이 경로에 `/claude-{uid}/`를, Windows에서는 `/claude/`를 추가합니다. 기본값: macOS에서는 `/tmp`, Linux와 Windows에서는 `os.tmpdir()`. macOS와 Linux에서 재정의 값이 긴 경로이면 [샌드박스된](/docs/ko/sandboxing) Bash 하위 프로세스는 시스템 기본값 아래의 짧은 폴백 `$TMPDIR`을 받습니다. 일부 도구는 임시 경로가 너무 길면 실패하기 때문입니다. 샌드박스되지 않은 Bash 명령은 셸의 `$TMPDIR`이 설정되어 있으면 이를 상속합니다. 네이티브 Windows에서 셸이 `$TMPDIR`을 설정하지 않으면, `$TMPDIR`을 참조하는 Bash 명령은 재정의 값을 받거나, 재정의 값을 설정하지 않은 경우 `%TEMP%`를 받습니다. Claude Code 자체의 임시 파일은 항상 재정의 값을 사용합니다. 셸, 사용자 설정 또는 관리형 설정에서 설정합니다. [프로젝트 및 로컬 설정](/docs/ko/settings-reference#variables-claude-code-ignores-in-env)에서는 무시됩니다 |408| `CLAUDE_CODE_TMPDIR` | 내부 임시 파일에 사용되는 임시 디렉터리를 재정의합니다. Claude Code는 Unix에서는 이 경로에 `/claude-{uid}/`를, Windows에서는 `/claude/`를 추가합니다. 기본값: macOS에서는 `/tmp`, Linux와 Windows에서는 `os.tmpdir()`. macOS와 Linux에서 재정의 값이 긴 경로인 경우, 일부 도구는 임시 경로가 너무 길면 실패하므로 [샌드박스된](/docs/ko/sandboxing) Bash 하위 프로세스는 시스템 기본값 아래의 짧은 대체 `$TMPDIR`을 받습니다. 샌드박스되지 않은 Bash 명령은 셸의 `$TMPDIR`이 설정되어 있으면 이를 상속합니다. 네이티브 Windows에서 셸이 `$TMPDIR`을 설정하지 않으면, `$TMPDIR`을 참조하는 Bash 명령은 재정의 값을 받으며, 재정의 값을 설정하지 않은 경우 `%TEMP%`를 받습니다. Claude Code 자체 임시 파일은 항상 재정의 값을 사용합니다. 셸, 사용자 설정 또는 관리형 설정에서 설정합니다. [프로젝트 및 로컬 설정](/docs/ko/settings-reference#variables-claude-code-ignores-in-env)에서는 무시됩니다 |

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

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

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

410| `CLAUDE_CODE_USER_DIALOG_TIMEOUT_MS` | Claude Code가 [Remote Control](/docs/ko/remote-control) 또는 SDK 호스트와 같은 원격 클라이언트로 전달하는 대화 상자나, [보류된 세션 간 메시지](/docs/ko/cross-session-messaging#control-inbound-messages)의 승인 대화 상자를 취소하기 전까지의 기한(밀리초)입니다. 권한 프롬프트와 `AskUserQuestion` 질문은 자체 흐름을 사용하며 이 변수의 적용을 받지 않습니다. Claude Code v2.1.236 이상에서는 무인으로 실행될 수 있는 세션에서 세션 도중의 [Fable 사용량 크레딧 동의 프롬프트](/docs/ko/model-config#fable-and-usage-credits)에도 기한을 적용합니다. 기한이 적용되지 않는 경우를 포함한 보류 메시지 만료 규칙 전체는 [수신 메시지 제어](/docs/ko/cross-session-messaging#control-inbound-messages)와 [비대화형 세션](/docs/ko/cross-session-messaging#non-interactive-sessions)에서 다룹니다. [`dialogExpiry`](/docs/ko/settings-reference#dialogexpiry) 설정을 재정의합니다. `0` 또는 음수 값은 기한을 비활성화합니다 |412| `CLAUDE_CODE_TRANSCRIPT_LOCAL_GC` | 긴 `-p` 또는 Agent SDK 세션의 [트랜스크립트 파일](/docs/ko/sessions#where-transcripts-are-stored)이 커지는 크기를 제한하려면 `1`로 설정합니다. 각 압축 후 파일이 5MB보다 크면 Claude Code는 해당 압축 이전의 기록을 제거합니다. 세션을 재개하면 파일이 잘렸는지와 관계없이 동일한 대화가 복원됩니다. 설정의 `env` 블록으로는 켤 수 없으므로 Claude Code를 시작하는 환경에서 설정하십시오. Claude Code v2.1.287 이상이 필요합니다 |

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

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

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

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

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

420| `CLAUDE_CODE_WORKFLOW_MAX_CONCURRENT_AGENTS` | 단일 [워크플로](/docs/ko/workflows) 실행이 동시에 실행하는 에이전트 수로, `1`부터 `256`까지 지정할 수 있습니다. 기본적으로 한 번의 실행은 최대 16개의 에이전트를 동시에 실행하며, Claude Code가 사용할 수 있는 CPU가 더 적으면 그보다 적게 실행합니다. 대기 중인 `agent()` 호출은 빈 슬롯이 생길 때까지 기다립니다. 실행 중인 각 에이전트의 트랜스크립트는 Claude Code의 메모리에 유지되므로 값이 높을수록 메모리 사용량이 늘어납니다. 숫자만 허용되며, 범위를 벗어난 값이나 다른 표기는 기본값을 유지합니다. Claude Code v2.1.269 이상이 필요합니다 |423| `CLAUDE_CODE_WORKER_CHECKIN_SCHEDULE` | `CLAUDE_AUTO_BACKGROUND_TASKS`가 `1`로 설정된 경우, 아직 실행 중인 [백그라운드 서브에이전트](/docs/ko/sub-agents#run-subagents-in-foreground-or-background)를 확인하도록 Claude에게 알림을 보내기 전에 Claude Code가 각각 기다리는 시간입니다. `1`부터 `86400`까지의 정수 초 단위 대기 시간을 하나 이상 쉼표로 구분하여 지정합니다(예: `600` 또는 `600,1800,3600`). 각 값은 다음 알림 전의 대기 시간이며, 마지막 값이 반복됩니다. 숫자만 허용되며, 다른 값이나 표기는 설정되지 않은 것으로 간주됩니다. 설정하지 않으면 알림이 없습니다. Claude Code v2.1.283 이상이 필요합니다 |

421| `CLAUDE_CODE_WORKFLOW_PREFIX_STAGGER_MS` | [워크플로](/docs/ko/workflows) 에이전트가 자신의 첫 요청을 보내기 전에 동일한 프리픽스를 가진 형제 에이전트의 첫 응답이 시작되기를 기다리는 시간의 상한(밀리초)입니다. 팬아웃이 [프롬프트 캐시 프리픽스](/docs/ko/workflows#prompt-caching-in-a-fan-out)를 공유하는 여러 에이전트를 시작하면, Claude Code는 첫 번째 에이전트를 제외한 나머지를 최대 이 시간만큼 대기시켜 각 에이전트가 프리픽스를 캐시 없이 처리하는 대신 캐시된 프리픽스를 읽도록 합니다. 기본값은 `5000`입니다. 대기를 비활성화하려면 `0`으로 설정합니다. `DISABLE_PROMPT_CACHING`이 설정되어 있으면 에이전트는 대기하지 않습니다. Claude Code v2.1.229 이상이 필요합니다 |424| `CLAUDE_CODE_WORKFLOW_MAX_CONCURRENT_AGENTS` | 단일 [워크플로](/docs/ko/workflows) 실행이 동시에 실행하는 에이전트 수로, `1`부터 `256`까지입니다. 기본적으로 한 번의 실행은 최대 16개의 에이전트를 동시에 실행하며, Claude Code가 사용할 수 있는 CPU가 더 적으면 그보다 적게 실행합니다. 대기 중인 `agent()` 호출은 빈 슬롯을 기다립니다. 실행 중인 각 에이전트의 트랜스크립트는 Claude Code의 메모리에 유지되므로 값이 높을수록 메모리 사용량이 늘어납니다. 숫자만 허용되며, 범위를 벗어난 값과 다른 표기는 기본값을 유지합니다. Claude Code v2.1.269 이상이 필요합니다 |

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

453| `DISABLE_PROMPT_CACHING_OPUS` | [기본 Opus 모델](/docs/ko/prompt-caching#disable-prompt-caching)에 대해 프롬프트 캐싱을 비활성화하려면 `1`로 설정합니다 |457| `DISABLE_PROMPT_CACHING_OPUS` | [기본 Opus 모델](/docs/ko/prompt-caching#disable-prompt-caching)에 대해 프롬프트 캐싱을 비활성화하려면 `1`로 설정합니다 |

454| `DISABLE_PROMPT_CACHING_SONNET` | [기본 Sonnet 모델](/docs/ko/prompt-caching#disable-prompt-caching)에 대해 프롬프트 캐싱을 비활성화하려면 `1`로 설정합니다 |458| `DISABLE_PROMPT_CACHING_SONNET` | [기본 Sonnet 모델](/docs/ko/prompt-caching#disable-prompt-caching)에 대해 프롬프트 캐싱을 비활성화하려면 `1`로 설정합니다 |

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

456| `DISABLE_UPDATES` | 수동 `claude update` 및 `claude install`을 포함한 모든 업데이트를 차단하려면 `1`로 설정합니다. `DISABLE_AUTOUPDATER`보다 엄격합니다. 자체 채널을 통해 Claude Code를 배포하며 사용자가 직접 업데이트해서는 안 되는 경우에 사용합니다 |460| `DISABLE_UPDATES` | 수동 `claude update` 및 `claude install`을 포함한 모든 업데이트를 차단하려면 `1`로 설정합니다. `DISABLE_AUTOUPDATER`보다 엄격합니다. 자체 채널을 통해 Claude Code를 배포하며 사용자가 직접 업데이트하면 안 되는 경우에 사용합니다 |

458| `DO_NOT_TRACK` | 텔레메트리를 옵트아웃하려면 `1`로 설정합니다. [기능 플래그 가져오기](#features-that-need-feature-flag-fetching)에 대한 영향을 포함해 `DISABLE_TELEMETRY`와 동일한 효과가 있습니다. Claude Code는 이 변수를 표준 불리언으로 읽으므로 `0`이면 텔레메트리가 켜진 상태로 유지되며, 많은 개발자 CLI가 인식하는 도구 간 공통 규약으로서 이 변수를 준수합니다 |462| `DO_NOT_TRACK` | 텔레메트리를 거부하려면 `1`로 설정합니다. [기능 플래그 가져오기](#features-that-need-feature-flag-fetching)를 포함해 `DISABLE_TELEMETRY`와 같은 효과를 냅니다. Claude Code는 이 변수를 표준 불리언으로 읽으므로 `0`은 텔레메트리를 켠 상태로 두며, 많은 개발자 CLI가 인식하는 도구 간 공통 규약으로서 이 변수를 따릅니다 |

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

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

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

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

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

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

467| `FORCE_PROMPT_CACHING_5M` | 1시간 TTL이 적용되는 경우에도 5분 프롬프트 캐시 TTL을 강제하려면 `1`로 설정합니다. `CLAUDE_CODE_PROMPT_CACHE_TTL`, `CLAUDE_CODE_SUBAGENT_PROMPT_CACHE_TTL`, `ENABLE_PROMPT_CACHING_1H`, 그리고 `promptCacheTtl` 및 `subagentPromptCacheTtl` 설정을 재정의합니다 |471| `FORCE_PROMPT_CACHING_5M` | 1시간 TTL이 적용될 상황에서도 5분 프롬프트 캐시 TTL을 강제하려면 `1`로 설정합니다. `CLAUDE_CODE_PROMPT_CACHE_TTL`, `CLAUDE_CODE_SUBAGENT_PROMPT_CACHE_TTL`, `ENABLE_PROMPT_CACHING_1H`, 그리고 `promptCacheTtl` 및 `subagentPromptCacheTtl` 설정을 재정의합니다 |

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

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

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

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

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

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

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

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

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

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

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

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

482| `MCP_PROTOCOL_NEGOTIATION` | [v2 MCP 클라이언트 런타임](/docs/ko/mcp#mcp-client-runtimes)에서만 적용되며, Claude Code가 서버에 대해 MCP 프로토콜 리비전 2026-07-28을 프로브할지 여부를 지정합니다. HTTP, claude.ai 커넥터, stdio 서버를 프로브하려면 `auto`, 아무 서버도 프로브하지 않으려면 `legacy`로 설정합니다. 변수를 설정하지 않으면 Claude Code는 [MCP 클라이언트 런타임](/docs/ko/mcp#mcp-client-runtimes)에 설명된 서버를 프로브합니다. 그 밖의 값은 디버그 로그에 경고를 남기고 무시됩니다. Claude Code v2.1.221 이상이 필요합니다 |486| `MCP_PROTOCOL_NEGOTIATION` | [v2 MCP 클라이언트 런타임](/docs/ko/mcp#mcp-client-runtimes)에서만, Claude Code가 서버에 MCP 프로토콜 리비전 2026-07-28을 탐색할지 여부입니다. HTTP, claude.ai 커넥터, stdio 서버를 탐색하려면 `auto`, 아무것도 탐색하지 않으려면 `legacy`로 설정합니다. 변수를 설정하지 않으면 Claude Code는 [MCP 클라이언트 런타임](/docs/ko/mcp#mcp-client-runtimes)에 설명된 서버를 탐색합니다. 다른 값은 디버그 로그에 경고와 함께 무시됩니다. Claude Code v2.1.221 이상이 필요합니다 |

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

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

489| `OTEL_ATTRIBUTE_VALUE_LENGTH_LIMIT` | 속성 값 길이에 대한 표준 OpenTelemetry SDK 제한입니다. Claude Code는 잘림 표시가 SDK 제한 내에 머물도록, 콘텐츠를 포함하는 텔레메트리 속성을 이 값과 `CLAUDE_CODE_OTEL_CONTENT_MAX_LENGTH` 중 작은 값으로 제한합니다. Claude Code는 `OTEL_LOGRECORD_ATTRIBUTE_VALUE_LENGTH_LIMIT` 및 `OTEL_SPAN_ATTRIBUTE_VALUE_LENGTH_LIMIT` 변형도 같은 방식으로 읽으며, 설정된 값 중 가장 작은 값이 모든 시그널에 적용됩니다. Claude Code v2.1.214 이상이 필요합니다. [모니터링](/docs/ko/monitoring-usage#common-configuration-variables)을 참조하세요 |493| `OTEL_ATTRIBUTE_VALUE_LENGTH_LIMIT` | 속성 값 길이에 대한 표준 OpenTelemetry SDK 제한입니다. Claude Code는 콘텐츠를 담은 텔레메트리 속성을 이 값과 `CLAUDE_CODE_OTEL_CONTENT_MAX_LENGTH` 중 작은 값으로 제한하여, 잘림 표시가 SDK 제한 내에 유지되도록 합니다. Claude Code는 `OTEL_LOGRECORD_ATTRIBUTE_VALUE_LENGTH_LIMIT` 및 `OTEL_SPAN_ATTRIBUTE_VALUE_LENGTH_LIMIT` 변형도 같은 방식으로 읽으며, 설정된 값 중 가장 작은 값이 모든 신호에 적용됩니다. Claude Code v2.1.214 이상이 필요합니다. [모니터링](/docs/ko/monitoring-usage#common-configuration-variables)을 참조하세요 |

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

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

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

493| `OTEL_LOG_TOOL_CONTENT` | `tool.output` OpenTelemetry 스팬 이벤트에 도구 콘텐츠를 포함하려면 `1`로 설정합니다. 스팬 속성은 [자체 게이트](/docs/ko/monitoring-usage#new-context-gates)에 따라 도구 콘텐츠를 포함합니다. [트레이싱](/docs/ko/monitoring-usage#traces-beta)이 필요합니다. 민감한 데이터를 보호하기 위해 기본적으로 비활성화되어 있습니다. 셸, 사용자 설정 또는 관리형 설정에서 설정합니다. [프로젝트 및 로컬 설정](/docs/ko/settings-reference#variables-claude-code-ignores-in-env)에서는 해당 섹션에서 설명하는 끄기 값을 제외하고 무시됩니다. [모니터링](/docs/ko/monitoring-usage#tool-output-span-event)을 참조하세요 |497| `OTEL_LOG_TOOL_CONTENT` | `tool.output` OpenTelemetry span 이벤트에 도구 콘텐츠를 포함하려면 `1`로 설정합니다. span 속성은 [자체 게이트](/docs/ko/monitoring-usage#new-context-gates)에 따라 도구 콘텐츠를 담습니다. [트레이싱](/docs/ko/monitoring-usage#traces-beta)이 필요합니다. 민감한 데이터를 보호하기 위해 기본적으로 비활성화되어 있습니다. 셸, 사용자 설정 또는 관리형 설정에서 설정합니다. 해당 섹션에 설명된 끄기 값을 제외하고 [프로젝트 및 로컬 설정](/docs/ko/settings-reference#variables-claude-code-ignores-in-env)에서는 무시됩니다. [모니터링](/docs/ko/monitoring-usage#tool-output-span-event)을 참조하세요 |

494| `OTEL_LOG_TOOL_DETAILS` | 도구 입력 인수, MCP 서버 이름, 사용자가 작성한 워크플로 이름, 도구 실패 시의 원시 오류 문자열, `api_refusal` 이벤트의 거부 `category`, [비용 및 토큰 메트릭](/docs/ko/monitoring-usage#cost-counter)의 실제 에이전트, 스킬, 플러그인, MCP 서버 이름, 그리고 기타 도구 세부 정보를 OpenTelemetry 메트릭, 트레이스, 로그에 포함하려면 `1`로 설정합니다. PII를 보호하기 위해 기본적으로 비활성화되어 있습니다. 셸, 사용자 설정 또는 관리형 설정에서 설정합니다. [프로젝트 및 로컬 설정](/docs/ko/settings-reference#variables-claude-code-ignores-in-env)에서는 해당 섹션에서 설명하는 끄기 값을 제외하고 무시됩니다. [모니터링](/docs/ko/monitoring-usage)을 참조하세요 |498| `OTEL_LOG_TOOL_DETAILS` | OpenTelemetry 메트릭, 트레이스, 로그에 도구 입력 인수, MCP 서버 이름, 사용자가 작성한 워크플로 이름, 도구 실패 시의 원시 오류 문자열, `api_refusal` 이벤트의 거부 `category`, [비용 및 토큰 메트릭](/docs/ko/monitoring-usage#cost-counter)의 실제 에이전트, 스킬, 플러그인, MCP 서버 이름, 기타 도구 세부 정보를 포함하려면 `1`로 설정합니다. PII 보호를 위해 기본적으로 비활성화되어 있습니다. 셸, 사용자 설정 또는 관리형 설정에서 설정합니다. 해당 섹션에 설명된 끄기 값을 제외하고 [프로젝트 및 로컬 설정](/docs/ko/settings-reference#variables-claude-code-ignores-in-env)에서는 무시됩니다. [모니터링](/docs/ko/monitoring-usage)을 참조하세요 |

495| `OTEL_LOG_USER_PROMPTS` | OpenTelemetry 트레이스와 로그에 사용자 프롬프트 텍스트를 포함하려면 `1`로 설정합니다. 기본적으로 비활성화되어 있습니다(프롬프트가 마스킹됨). 셸, 사용자 설정 또는 관리형 설정에서 설정합니다. [프로젝트 및 로컬 설정](/docs/ko/settings-reference#variables-claude-code-ignores-in-env)에서는 해당 섹션에서 설명하는 끄기 값을 제외하고 무시됩니다. [모니터링](/docs/ko/monitoring-usage)을 참조하세요 |499| `OTEL_LOG_USER_PROMPTS` | OpenTelemetry 트레이스와 로그에 사용자 프롬프트 텍스트를 포함하려면 `1`로 설정합니다. 기본적으로 비활성화되어 있습니다(프롬프트가 가려짐). 셸, 사용자 설정 또는 관리형 설정에서 설정합니다. 해당 섹션에 설명된 끄기 값을 제외하고 [프로젝트 및 로컬 설정](/docs/ko/settings-reference#variables-claude-code-ignores-in-env)에서는 무시됩니다. [모니터링](/docs/ko/monitoring-usage)을 참조하세요 |

496| `OTEL_METRICS_INCLUDE_ACCOUNT_UUID` | 메트릭 속성에서 계정 UUID를 제외하려면 `false`로 설정합니다(기본값: 포함). [모니터링](/docs/ko/monitoring-usage)을 참조하세요 |500| `OTEL_METRICS_INCLUDE_ACCOUNT_UUID` | 메트릭 속성에서 계정 UUID를 제외하려면 `false`로 설정합니다(기본값: 포함). [모니터링](/docs/ko/monitoring-usage)을 참조하세요 |

497| `OTEL_METRICS_INCLUDE_ENTRYPOINT` | 메트릭 속성에 세션 진입점을 포함하려면 `true`로 설정합니다(기본값: 제외). v2.1.152에서 추가되었습니다. [모니터링](/docs/ko/monitoring-usage)을 참조하세요 |501| `OTEL_METRICS_INCLUDE_ENTRYPOINT` | 메트릭 속성에 세션 진입점을 포함하려면 `true`로 설정합니다(기본값: 제외). v2.1.152에서 추가되었습니다. [모니터링](/docs/ko/monitoring-usage)을 참조하세요 |

498| `OTEL_METRICS_INCLUDE_REPOSITORY` | 세션의 저장소를 식별하는 `vcs.*` 속성으로 OpenTelemetry 메트릭과 이벤트에 태그를 지정하려면 `true`로 설정합니다(기본값: 제외). Claude Code v2.1.269 이상이 필요합니다. [저장소 속성](/docs/ko/monitoring-usage#repository-attributes)을 참조하세요 |502| `OTEL_METRICS_INCLUDE_REPOSITORY` | OpenTelemetry 메트릭과 이벤트에 세션의 저장소를 식별하는 `vcs.*` 속성을 태그하려면 `true`로 설정합니다(기본값: 제외). Claude Code v2.1.269 이상이 필요합니다. [저장소 속성](/docs/ko/monitoring-usage#repository-attributes)을 참조하세요 |

499| `OTEL_METRICS_INCLUDE_RESOURCE_ATTRIBUTES` | v2.1.161부터 Claude Code는 `OTEL_RESOURCE_ATTRIBUTES` 키를 메트릭 데이터포인트 레이블에 첨부합니다. 이를 제외하려면 `false`로 설정합니다(기본값: 포함). [모니터링](/docs/ko/monitoring-usage#multi-team-organization-support)을 참조하세요 |503| `OTEL_METRICS_INCLUDE_RESOURCE_ATTRIBUTES` | v2.1.161부터 Claude Code는 `OTEL_RESOURCE_ATTRIBUTES` 키를 메트릭 데이터 포인트 레이블에 첨부합니다. 이를 제외하려면 `false`로 설정합니다(기본값: 포함). [모니터링](/docs/ko/monitoring-usage#multi-team-organization-support)을 참조하세요 |

500| `OTEL_METRICS_INCLUDE_SESSION_ID` | 메트릭 속성에서 세션 ID를 제외하려면 `false`로 설정합니다(기본값: 포함). [모니터링](/docs/ko/monitoring-usage)을 참조하세요 |504| `OTEL_METRICS_INCLUDE_SESSION_ID` | 메트릭 속성에서 세션 ID를 제외하려면 `false`로 설정합니다(기본값: 포함). [모니터링](/docs/ko/monitoring-usage)을 참조하세요 |

501| `OTEL_METRICS_INCLUDE_VERSION` | 메트릭 속성에 Claude Code 버전을 포함하려면 `true`로 설정합니다(기본값: 제외). [모니터링](/docs/ko/monitoring-usage)을 참조하세요 |505| `OTEL_METRICS_INCLUDE_VERSION` | 메트릭 속성에 Claude Code 버전을 포함하려면 `true`로 설정합니다(기본값: 제외). [모니터링](/docs/ko/monitoring-usage)을 참조하세요 |

502| `SLASH_COMMAND_TOOL_CHAR_BUDGET` | [Skill 도구](/docs/ko/skills#control-who-invokes-a-skill)에 표시되는 스킬 메타데이터의 문자 예산을 재정의합니다. 예산은 컨텍스트 윈도우의 1%로 동적으로 조정되며, 폴백 값은 8,000자입니다. 하위 호환성을 위해 레거시 이름을 유지합니다 |506| `SLASH_COMMAND_TOOL_CHAR_BUDGET` | [Skill 도구](/docs/ko/skills#control-who-invokes-a-skill)에 표시되는 스킬 메타데이터의 문자 예산을 재정의합니다. 예산은 컨텍스트 윈도우의 1%로 동적으로 조정되며, 폴백 값은 8,000자입니다. 이전 버전과의 호환성을 위해 기존 이름을 유지합니다 |

503| `TASK_MAX_OUTPUT_LENGTH` | v2.1.277에서 이 변수가 크기를 지정하던 `TaskOutput` 도구와 함께 제거되었으며 이제 아무 효과가 없습니다. 이전에는 `TaskOutput` 도구가 보관하는 [백그라운드 작업](/docs/ko/tools-reference#background-commands) 출력의 최대 문자 수를 설정했습니다. 이제 Claude는 대신 `Read`로 백그라운드 작업의 출력 파일을 읽습니다 |507| `TASK_MAX_OUTPUT_LENGTH` | v2.1.277에서 이 변수가 크기를 정하던 `TaskOutput` 도구와 함께 제거되어 이제 아무 효과가 없습니다. 이전에는 `TaskOutput` 도구가 보관하는 [백그라운드 작업](/docs/ko/tools-reference#background-commands) 출력의 최대 문자 수를 설정했습니다. 이제 Claude는 대신 `Read`로 백그라운드 작업의 출력 파일을 읽습니다 |

524 528

525표준 OpenTelemetry 익스포터 변수(`OTEL_METRICS_EXPORTER`, `OTEL_LOGS_EXPORTER`, `OTEL_EXPORTER_OTLP_ENDPOINT`, `OTEL_EXPORTER_OTLP_PROTOCOL`, `OTEL_EXPORTER_OTLP_HEADERS`, `OTEL_METRIC_EXPORT_INTERVAL`, `OTEL_RESOURCE_ATTRIBUTES` 및 시그널별 변형)도 지원됩니다. 구성 세부 정보는 [모니터링](/docs/ko/monitoring-usage)을 참조하세요.529표준 OpenTelemetry 익스포터 변수(`OTEL_METRICS_EXPORTER`, `OTEL_LOGS_EXPORTER`, `OTEL_EXPORTER_OTLP_ENDPOINT`, `OTEL_EXPORTER_OTLP_PROTOCOL`, `OTEL_EXPORTER_OTLP_HEADERS`, `OTEL_METRIC_EXPORT_INTERVAL`, `OTEL_RESOURCE_ATTRIBUTES` 및 신호별 변형)도 지원됩니다. 구성 세부 정보는 [모니터링](/docs/ko/monitoring-usage)을 참조하세요.

526 530

527`CLAUDE_CODE_ENABLE_TELEMETRY`와, 내보내기를 켜거나 내보낼 대상을 선택하거나 콘텐츠를 캡처하는 OpenTelemetry 변수는 셸, 사용자 설정 또는 관리형 설정에서 설정하세요. Claude Code는 해당 섹션에서 설명하는 끄기 값을 제외하고 [프로젝트 및 로컬 설정에서 이러한 변수를 무시합니다](/docs/ko/settings-reference#variables-claude-code-ignores-in-env). `OTEL_RESOURCE_ATTRIBUTES`와 `OTEL_METRIC_EXPORT_INTERVAL` 같은 내보내기 간격, 타임아웃, 압축 변수는 프로젝트 및 로컬 설정에서도 계속 적용됩니다.531`CLAUDE_CODE_ENABLE_TELEMETRY`와 내보내기를 켜거나, 대상을 선택하거나, 콘텐츠를 캡처하는 OpenTelemetry 변수는 셸, 사용자 설정 또는 관리형 설정에서 설정하세요. Claude Code는 해당 섹션에 설명된 끄기 값을 제외하고 [프로젝트 및 로컬 설정에서 이들을 무시합니다](/docs/ko/settings-reference#variables-claude-code-ignores-in-env). `OTEL_RESOURCE_ATTRIBUTES`와 `OTEL_METRIC_EXPORT_INTERVAL` 같은 내보내기 간격, 타임아웃, 압축 변수는 프로젝트 및 로컬 설정에서도 계속 적용됩니다.

532

533<h2 id="what-the-subprocess-environment-scrub-removes">

534 하위 프로세스 환경 정리가 제거하는 항목

535</h2>

536

537[`CLAUDE_CODE_SUBPROCESS_ENV_SCRUB`](#variables)를 `1`로 설정하면 Claude Code는 Bash 명령, 훅, stdio MCP 서버 등 자신이 시작하는 하위 프로세스의 환경에서 자격 증명을 제거합니다. 이를 통해 프롬프트 인젝션 공격이 셸 확장을 통해 읽을 수 있는 정보가 줄어듭니다. Claude Code 프로세스는 자체 API 호출을 위해 자격 증명을 유지합니다.

538

539환경 정리는 변수 이름이나 값의 형태로 자격 증명을 식별하므로, 유일한 통제 수단이 아니라 범위를 좁게 지정한 [권한 규칙](/docs/ko/permissions)과 함께 하나의 보안 계층으로 사용하십시오.

540

541다음 표는 예시 변수에 대해 환경 정리가 수행하는 작업을 보여 줍니다.

542

543| 예시 변수 | 환경 정리가 수행하는 작업 |

544| :- | :- |

545| `ANTHROPIC_API_KEY`, `AWS_SECRET_ACCESS_KEY` | 제거합니다 |

546| `NPM_TOKEN`, `DB_PASSWORD` | 이름이 자격 증명처럼 보이므로 제거합니다 |

547| 비밀번호가 포함된 `DATABASE_URL` | 값이 자격 증명처럼 보이므로 제거합니다 |

548| 비밀번호가 포함된 `PIP_INDEX_URL` 또는 `NPM_CONFIG_REGISTRY` | URL은 유지하고 사용자 이름과 비밀번호만 잘라 냅니다 |

549| `CLAUDE_CONFIG_DIR` | 제거합니다. Claude Code v2.1.251 이상이 필요합니다 |

550| `GITHUB_TOKEN`, `GH_TOKEN`, `GH_ENTERPRISE_TOKEN`, `GITHUB_ENTERPRISE_TOKEN` | `gh` 및 GitHub API를 호출하는 스크립트가 계속 작동하도록 그대로 둡니다 |

551| `HTTP_PROXY`, `HTTPS_PROXY` | [URL에 포함된 사용자 이름과 비밀번호](/docs/ko/network-config#basic-authentication)를 포함하여 그대로 둡니다. [샌드박스](/docs/ko/sandboxing#network-isolation)는 샌드박스 처리된 명령에 대해 이러한 변수를 직접 설정할 수 있습니다 |

552| `GIT_CONFIG_COUNT`, `GIT_CONFIG_KEY_<n>`, `GIT_CONFIG_VALUE_<n>` | 어떤 값을 담고 있든 그대로 둡니다 |

553| 변수 이름과 값이 자격 증명처럼 보이지 않는 비밀 값 | 그대로 둡니다 |

554

555환경 정리는 `GITHUB_TOKEN`을 그대로 두므로, GitHub Actions 작업에는 필요한 최소한의 `permissions`만 부여하십시오. 샌드박스 처리된 Bash 명령에서 GitHub 토큰을 제거하려면 [`sandbox.credentials`](/docs/ko/sandboxing#protect-credentials) 아래에 `deny` 항목을 추가하십시오.

556

557하위 프로세스에 제거 대상 변수 중 하나가 필요한 경우에는 환경 정리를 설정하지 마십시오.

558

559Linux에서는 환경 정리가 Bash 하위 프로세스를 격리된 PID 네임스페이스에서 실행하므로, 하위 프로세스가 `/proc`를 통해 호스트 프로세스의 환경을 읽을 수 없습니다. 그 부수 효과로 `ps`, `pgrep`, `kill`은 호스트 프로세스를 확인하거나 호스트 프로세스에 시그널을 보낼 수 없습니다.

528 560

529<h2 id="features-that-need-feature-flag-fetching">561<h2 id="features-that-need-feature-flag-fetching">

530 기능 플래그 가져오기가 필요한 기능562 기능 플래그 가져오기가 필요한 기능

531</h2>563</h2>

532 564

533Claude Code는 Anthropic에서 가져오는 기능 플래그를 통해 일부 기능을 활성화합니다. Claude Code는 다음 세션에서 해당 가져오기를 건너뜁니다:565Claude Code는 Anthropic에서 가져오는 기능 플래그를 통해 일부 기능을 켭니다. Claude Code는 다음 세션에서는 이 가져오기를 건너뜁니다.

~~534~~ 566

535* `DISABLE_GROWTHBOOK`, `DISABLE_TELEMETRY`, `DO_NOT_TRACK` 또는 `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC`을 설정한 세션입니다. [변수 테이블](#variables)의 각 변수 행에서 어떤 값이 가져오기를 비활성화하는지 나타냅니다567* `DISABLE_GROWTHBOOK`, `DISABLE_TELEMETRY`, `DO_NOT_TRACK` 또는 `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC`을 설정한 세션. 어떤 값이 가져오기를 끄는지는 [변수 표](#variables)의 각 변수 행에 나와 있습니다

536* Amazon Bedrock, Claude Platform on AWS, Google Cloud의 Agent Platform 또는 Microsoft Foundry와 같은 [타사 제공자](/docs/ko/third-party-integrations)의 세션입니다. 단, Claude Code를 포함하는 호스트 플랫폼이 `CLAUDE_CODE_PROVIDER_MANAGED_BY_HOST`를 설정한 경우는 제외합니다568* Amazon Bedrock, Claude Platform on AWS, Google Cloud의 Agent Platform 또는 Microsoft Foundry와 같은 [서드파티 제공자](/docs/ko/third-party-integrations)를 사용하는 세션. 단, Claude Code를 내장한 호스트 플랫폼이 `CLAUDE_CODE_PROVIDER_MANAGED_BY_HOST`를 설정한 경우는 예외입니다

537* [Claude 앱 게이트웨이](/docs/ko/claude-apps-gateway) 세션569* [Claude apps 게이트웨이](/docs/ko/claude-apps-gateway) 세션

~~538~~ 570

539가져오기가 비활성화되면 다음을 수행할 수 없습니다:571가져오기가 꺼져 있으면 다음 작업을 할 수 없습니다.

~~540~~ 572

541* [`/auto-mode-setup`](/docs/ko/auto-mode-config#generate-environment-entries)을 실행하여 `autoMode.environment` 항목을 작성할 수 없습니다573* [`/auto-mode-setup`](/docs/ko/auto-mode-config#generate-environment-entries)을 실행하여 `autoMode.environment` 항목 초안 작성

542* [원격 제어](/docs/ko/remote-control)를 `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC` 또는 `DISABLE_GROWTHBOOK`이 설정된 상태에서 사용할 수 없습니다. `DISABLE_TELEMETRY` 및 `DO_NOT_TRACK`의 경우 [원격 제어 요구사항](/docs/ko/remote-control#requirements)을 참조하세요574* `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC` 또는 `DISABLE_GROWTHBOOK`이 설정된 상태에서 [Remote Control](/docs/ko/remote-control) 사용. `DISABLE_TELEMETRY` 및 `DO_NOT_TRACK`에 대해서는 [Remote Control 요구 사항](/docs/ko/remote-control#requirements)을 참조하십시오

543* [원격 제어](/docs/ko/remote-control#requirements)를 사용할 수 없을 때 [이 머신 외의 세션에 메시지를 보낼 수 없습니다](/docs/ko/cross-session-messaging#message-sessions-on-other-machines). 이 머신의 세션 간 메시징은 가져오기가 비활성화된 상태에서 작동합니다575* [Remote Control](/docs/ko/remote-control#requirements)을 사용할 수 없을 때 [이 머신 외부의 세션에 메시지 보내기](/docs/ko/cross-session-messaging#message-sessions-on-other-machines). 이 머신의 세션 간 메시지 전송은 가져오기가 꺼져 있어도 작동합니다

544* [`claude import` 또는 `/import` 명령](/docs/ko/cli-reference#cli-commands)을 실행할 수 없습니다576* [`claude import` 또는 `/import` 명령](/docs/ko/cli-reference#cli-commands) 실행

545* [`/skill-doctor`](/docs/ko/skills#find-unused-skills)를 실행하거나 `/plugin` **Stats** 탭에서 해당 보고서를 열 수 없습니다577* [`/skill-doctor`](/docs/ko/skills#find-unused-skills) 실행 또는 `/plugin` **Stats** 탭에서 해당 보고서 열기

546* claude.ai 계정에 대해 활성화된 [기술](/docs/ko/skills#where-synced-skills-load) 및 [플러그인](/docs/ko/plugins/loading#synced-plugins)을 터미널 세션에 동기화할 수 없습니다578* claude.ai 계정에서 활성화된 [스킬](/docs/ko/skills#where-synced-skills-load) 및 [플러그인](/docs/ko/plugins/loading#synced-plugins)을 터미널 세션에 동기화

547* [어드바이저 도구](/docs/ko/advisor#requirements)를 사용할 수 없습니다579* [advisor 도구](/docs/ko/advisor#requirements) 사용

548* [아티팩트의 댓글](/docs/ko/artifacts#collect-comments-on-an-artifact)을 읽거나 답글을 달 수 없습니다580* [아티팩트의 댓글](/docs/ko/artifacts#collect-comments-on-an-artifact) 읽기 또는 답글 달기

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

550* Claude Code가 `MCP_PROTOCOL_NEGOTIATION=auto`를 설정하지 않는 한 [MCP 프로토콜 개정 2026-07-28](/docs/ko/mcp#mcp-client-runtimes)에 대해 claude.ai 커넥터 서버 또는 stdio 서버를 조사할 수 없습니다582* `MCP_PROTOCOL_NEGOTIATION=auto`를 설정하지 않은 경우, Claude Code가 claude.ai 커넥터 서버 또는 stdio 서버에 대해 [MCP 프로토콜 개정판 2026-07-28](/docs/ko/mcp#mcp-client-runtimes) 지원 여부를 확인하도록 하기

551* Git Bash가 설치된 Windows의 claude.ai 및 Console 계정에 대해 기본적으로 [PowerShell 도구](/docs/ko/tools-reference#powershell-tool)를 가져올 수 없습니다. Claude Code는 `CLAUDE_CODE_USE_POWERSHELL_TOOL=1`을 설정하지 않는 한 셸 명령을 Git Bash를 통해 라우팅합니다. Git Bash가 없는 Windows에서는 도구가 활성화된 상태로 유지됩니다583* Git Bash가 설치된 Windows에서 claude.ai 및 Console 계정에 기본적으로 [PowerShell 도구](/docs/ko/tools-reference#powershell-tool) 제공받기. `CLAUDE_CODE_USE_POWERSHELL_TOOL=1`을 설정하지 않으면 Claude Code는 셸 명령을 Git Bash를 통해 실행합니다. Git Bash가 없는 Windows에서는 이 도구가 계속 켜져 있습니다

552* [Claude가 작성한 피드백](/docs/ko/tools-reference#sendfeedback-tool-behavior)을 가져올 수 없습니다. Claude Code는 가져온 플래그를 통해 이를 활성화합니다584* [Claude가 초안을 작성한 피드백](/docs/ko/tools-reference#sendfeedback-tool-behavior) 받기. 이 기능은 Claude Code가 가져온 플래그를 통해 켭니다

553* Claude가 [대용량 붙여넣기를 입력된 텍스트가 아닌 붙여넣은 텍스트로 처리할 수 없습니다](/docs/ko/terminal-config#how-claude-treats-pasted-text). `[Pasted text #N]` 자리 표시자 뒤의 콘텐츠는 표시되지 않은 상태로 Claude에 도달합니다585* Claude가 [큰 붙여넣기를 입력한 텍스트가 아닌 붙여넣은 텍스트로 취급](/docs/ko/terminal-config#how-claude-treats-pasted-text)하도록 하기. `[Pasted text #N]` 플레이스홀더 뒤의 내용은 표시 없이 Claude에 전달됩니다

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

555 587

556<h3 id="first-session-after-an-install-or-upgrade">588<h3 id="first-session-after-an-install-or-upgrade">

557 설치 또는 업그레이드 후 첫 번째 세션589 설치 또는 업그레이드 후 첫 세션

558</h3>590</h3>

559 591

560Claude Code를 설치한 후 또는 기능을 추가하는 버전으로 업그레이드한 후 첫 번째 세션에서 [플래그 제어 기능](#features-that-need-feature-flag-fetching)이 누락될 수 있습니다. 해당 세션은 또한 이후 세션과 다른 [권한 모드](/docs/ko/permission-modes#which-mode-a-session-starts-in)에서 시작할 수 있습니다. Claude Code는 해당 세션 중에 플래그를 가져오므로 다음 세션에서는 기능과 일반적인 시작 권한 모드가 있습니다.592Claude Code를 설치한 후 또는 새 기능이 추가된 버전으로 업그레이드한 후 첫 세션에서는 [플래그로 제어되는 기능](#features-that-need-feature-flag-fetching)이 누락될 수 있습니다. 또한 해당 세션은 이후 세션과 다른 [권한 모드](/docs/ko/permission-modes#which-mode-a-session-starts-in)로 시작될 수 있습니다. Claude Code가 해당 세션 중에 플래그를 가져오면 이를 머신에 저장하므로, 해당 머신의 다음 세션에서는 기능이 제공되고 평소의 시작 권한 모드가 적용됩니다.

593

594새로 설치한 후 `claude -p`, Agent SDK 또는 VS Code 확장 프로그램과 같은 비대화형 세션에서는 Claude Code가 [시작 권한 모드를 선택](/docs/ko/permission-modes#which-mode-a-session-starts-in)하기 전에 플래그를 가져올 수 있지만, 항상 플래그를 기다리지는 않습니다.

595

596다음과 같은 구성에서는 첫 세션 이후의 세션도 새로 가져온 플래그 없이 시작됩니다.

597

598* **매 실행마다 깨끗한 환경**: 각 실행이 CI 컨테이너 또는 이전 세션이 저장한 플래그가 없는 다른 환경에서 시작되는 경우, 모든 실행이 첫 세션이 됩니다

599* **API 키 없는 게이트웨이 토큰**: API 키 없이 `ANTHROPIC_AUTH_TOKEN`으로 인증하고 `ANTHROPIC_BASE_URL`이 [LLM 게이트웨이](/docs/ko/llm-gateway)와 같이 Anthropic이 아닌 호스트를 가리키는 경우, Claude Code에는 플래그를 가져오는 데 사용할 자격 증명이 없습니다

561 600

562새로 설치한 후 `claude -p`, Agent SDK 또는 VS Code 확장과 같은 비대화형 세션에서 Claude Code는 [시작 권한 모드를 선택하기](/docs/ko/permission-modes#which-mode-a-session-starts-in) 전에 플래그를 선택할 수 있습니다.601이러한 구성에서 세션이 시작될 권한 모드를 선택하려면 [다른 권한 모드로 시작하기](/docs/ko/permission-modes#start-in-a-different-mode)를 참조하십시오.

563 602

564<h2 id="see-also">603<h2 id="see-also">

565 참고 항목604 참고 항목

errors.md +19 −1

Details

369| `Denying Bash also turns off the PowerShell tool, so Claude has neither` | [구성 경고](#denying-bash-also-turns-off-the-powershell-tool) |

846**해결 방법:**847**해결 방법:**

847 848

848* Pro 및 Max에서는 claude.ai의 [**Settings > Usage**](https://claude.ai/settings/usage)에서 월간 지출 한도를 늘리거나 `/usage-credits`를 실행합니다849* Pro 및 Max에서는 claude.ai의 [**Settings > Usage**](https://claude.ai/settings/usage)에서 월간 지출 한도를 늘리거나 `/usage-credits`를 실행합니다

849* Team 및 Enterprise에서는 청구를 관리하는 경우 [**Admin settings > Usage**](https://claude.ai/admin-settings/usage)에서 한도를 늘리거나 관리자에게 요청합니다. `/usage-credits`를 실행하면 해당 요청이 관리자에게 전송됩니다850* Team 및 Enterprise에서는 청구를 관리하는 경우 [**Organization settings > Usage**](https://claude.ai/admin-settings/usage)에서 한도를 늘리거나 관리자에게 요청합니다. `/usage-credits`를 실행하면 해당 요청이 관리자에게 전송됩니다

850* 채널 한도의 경우 조직 소유자나 채널 관리자에게 claude.ai에서 한도를 늘려 달라고 요청합니다. Claude Tag 문서의 [채널별 한도](https://claude.com/docs/claude-tag/admins/set-spend-limit#per-channel-limits)를 참조하세요851* 채널 한도의 경우 조직 소유자나 채널 관리자에게 claude.ai에서 한도를 늘려 달라고 요청합니다. Claude Tag 문서의 [채널별 한도](https://claude.com/docs/claude-tag/admins/set-spend-limit#per-channel-limits)를 참조하세요

851* 메시지에 플랜 윈도우의 재설정 시간이 표시된 경우 그때까지 기다릴 수도 있습니다852* 메시지에 플랜 윈도우의 재설정 시간이 표시된 경우 그때까지 기다릴 수도 있습니다

852* `/usage`를 실행하여 플랜의 윈도우와 각 윈도우의 재설정 시간을 확인합니다853* `/usage`를 실행하여 플랜의 윈도우와 각 윈도우의 재설정 시간을 확인합니다

5636 5637

5637[백그라운드 세션](/docs/ko/agent-view)에서 또는 `--output-format json`이나 `stream-json`을 사용하는 경우, Claude Code는 기계가 읽는 출력을 깨끗하게 유지하기 위해 경고를 stderr 대신 디버그 로그에 기록합니다. `--debug`로 실행하면 `~/.claude/debug/<session-id>.txt`에서 확인할 수 있습니다. v2.1.246 이전에는 Claude Code가 경고 없이 이러한 규칙을 수락했습니다.5638[백그라운드 세션](/docs/ko/agent-view)에서 또는 `--output-format json`이나 `stream-json`을 사용하는 경우, Claude Code는 기계가 읽는 출력을 깨끗하게 유지하기 위해 경고를 stderr 대신 디버그 로그에 기록합니다. `--debug`로 실행하면 `~/.claude/debug/<session-id>.txt`에서 확인할 수 있습니다. v2.1.246 이전에는 Claude Code가 경고 없이 이러한 규칙을 수락했습니다.

5638 5639

5640<h3 id="denying-bash-also-turns-off-the-powershell-tool">

5641 Bash를 거부하면 PowerShell 도구도 꺼짐

5642</h3>

5643

5644예를 들어 `--disallowedTools Bash`를 사용하거나 설정 파일 중 하나에 `Bash` 또는 `Bash(*)`만 있는 [거부 규칙](/docs/ko/permissions#match-all-uses-of-a-tool)을 사용하여 Bash 도구 전체를 제거했습니다. Git Bash가 설치된 Windows에서는 [Bash를 거부하면 PowerShell 도구도 꺼지므로](/docs/ko/tools-reference#bash-deny-rules-also-turn-off-the-powershell-tool) 세션이 셸 도구 없이 시작됩니다. Claude Code는 시작 시 다음 경고를 출력합니다:

5645

5646```text theme={null}

5647Denying Bash also turns off the PowerShell tool, so Claude has neither. To use PowerShell, set CLAUDE_CODE_USE_POWERSHELL_TOOL=1.

5648```

5649

5650**할 일:**

5651

5652* Claude가 PowerShell을 사용하도록 하려면 [PowerShell 도구 활성화](/docs/ko/tools-reference#enable-the-powershell-tool)에 나온 대로 환경 또는 설정 파일의 `env` 블록에서 [`CLAUDE_CODE_USE_POWERSHELL_TOOL`](/docs/ko/env-vars)을 `1`로 설정하세요. 그러면 PowerShell 도구는 Bash 거부 규칙과 함께 켜진 상태로 유지됩니다.

5653* 도구 전체 대신 특정 명령을 차단하려면 같은 설정 파일 또는 플래그에서 `Bash`만 있는 항목을 `Bash(git push *)` 같은 범위가 지정된 규칙으로 바꾸세요. Claude는 Bash 도구를 유지하며, PowerShell 도구는 변수를 설정하거나 범위가 지정된 [`PowerShell` 권한 규칙](/docs/ko/permissions#powershell)을 추가할 때까지 꺼진 상태로 유지됩니다.

5654

5655[백그라운드 세션](/docs/ko/agent-view)에서 또는 `--output-format json`이나 `stream-json`을 사용하는 경우, Claude Code는 경고를 stderr 대신 디버그 로그에 기록합니다. `--debug`로 실행하면 `~/.claude/debug/<session-id>.txt`에서 확인할 수 있습니다. v2.1.287 이전에는 Claude Code가 경고를 출력하지 않고 같은 방식으로 PowerShell 도구를 껐습니다.

5656

5639<h3 id="crosssessioninbound-must-be-one-of-accept-hold-refuse">5657<h3 id="crosssessioninbound-must-be-one-of-accept-hold-refuse">

5640 crossSessionInbound는 accept, hold, refuse 중 하나여야 함5658 crossSessionInbound는 accept, hold, refuse 중 하나여야 함

5641</h3>5659</h3>

fast-mode.md +4 −4

Details

136빠른 모드는 다음 모두를 필요로 합니다:136빠른 모드는 다음 모두를 필요로 합니다:

137 137

138* **Anthropic API 또는 구독만 해당**: 빠른 모드는 Anthropic Console API 및 사용 크레딧을 사용하는 Claude 구독 요금제를 통해 사용할 수 있습니다. Amazon Bedrock, Google Cloud의 Agent Platform, Microsoft Foundry 또는 AWS의 Claude Platform에서는 사용할 수 없습니다. Console 조직은 또한 [빠른 모드 액세스가 프로비저닝](#enable-fast-mode-for-your-organization)되어 있어야 합니다.138* **Anthropic API 또는 구독만 해당**: 빠른 모드는 Anthropic Console API 및 사용 크레딧을 사용하는 Claude 구독 요금제를 통해 사용할 수 있습니다. Amazon Bedrock, Google Cloud의 Agent Platform, Microsoft Foundry 또는 AWS의 Claude Platform에서는 사용할 수 없습니다. Console 조직은 또한 [빠른 모드 액세스가 프로비저닝](#enable-fast-mode-for-your-organization)되어 있어야 합니다.

139* **구독 요금제에 대해 사용 크레딧 활성화**: Pro, Max, Team 또는 Enterprise 요금제에서 계정에 [사용 크레딧](/docs/ko/costs#add-usage-credits-to-your-subscription)이 활성화되어 있어야 하며, 이를 통해 요금제의 포함된 사용량을 초과하여 청구할 수 있습니다. 활성화될 때까지 `/fast`는 "Fast mode requires usage credits"를 표시합니다. 활성화하는 방법은 요금제에 따라 다릅니다:139* **구독 요금제에 대해 사용량 크레딧 활성화**: Pro, Max, Team 또는 Enterprise 요금제에서 계정에 [사용량 크레딧](/docs/ko/costs#add-usage-credits-to-your-subscription)이 활성화되어 있어야 하며, 이를 통해 요금제의 포함된 사용량을 초과하여 청구할 수 있습니다. 활성화될 때까지 `/fast`는 "Fast mode requires usage credits"를 표시합니다. 활성화하는 방법은 요금제에 따라 다릅니다:

140 * Pro 및 Max에서는 claude.ai의 [**설정 > 사용**](https://claude.ai/settings/usage)의 **사용 크레딧** 섹션에서 활성화하거나 `/usage-credits`를 실행하여 해당 페이지를 엽니다.140 * Pro 및 Max에서는 claude.ai의 [**설정 > 사용**](https://claude.ai/settings/usage)의 **사용량 크레딧** 섹션에서 활성화하거나 `/usage-credits`를 실행하여 해당 페이지를 엽니다.

141 * Team 및 Enterprise에서는 청구 액세스 권한이 있는 구성원이 [**관리자 설정 > 사용**](https://claude.ai/admin-settings/usage)에서 조직에 대해 활성화하고, 액세스 권한이 없는 구성원은 `/usage-credits`를 실행하여 조직의 관리자에게 요청을 보냅니다.141 * Team 및 Enterprise에서는 청구 액세스 권한이 있는 구성원이 [**조직 설정 > 사용**](https://claude.ai/admin-settings/usage)에서 조직에 대해 활성화하고, 액세스 권한이 없는 구성원은 `/usage-credits`를 실행하여 조직의 관리자에게 요청을 보냅니다.

142 142

143<Note>143<Note>

144 빠른 모드 사용량은 요금제에 남은 사용량이 있더라도 사용 크레딧에서 직접 인출됩니다.144 빠른 모드 사용량은 요금제에 남은 사용량이 있더라도 사용 크레딧에서 직접 인출됩니다.

165* **Console** (API 고객): 관리자가 [Claude Code 기본 설정](https://platform.claude.com/claude-code/preferences)에서 활성화합니다. 빠른 모드는 [연구 미리보기](#research-preview)에 있으므로 조직은 빠른 모드 요청이 성공하기 전에 빠른 모드 액세스가 프로비저닝되어 있어야 합니다. 액세스를 얻으려면 계정 관리자에게 문의하거나 [Claude API의 빠른 모드](https://platform.claude.com/docs/en/build-with-claude/fast-mode)에 설명된 대로 대기 목록에 참여합니다.165* **Console** (API 고객): 관리자가 [Claude Code 기본 설정](https://platform.claude.com/claude-code/preferences)에서 활성화합니다. 빠른 모드는 [연구 미리보기](#research-preview)에 있으므로 조직은 빠른 모드 요청이 성공하기 전에 빠른 모드 액세스가 프로비저닝되어 있어야 합니다. 액세스를 얻으려면 계정 관리자에게 문의하거나 [Claude API의 빠른 모드](https://platform.claude.com/docs/en/build-with-claude/fast-mode)에 설명된 대로 대기 목록에 참여합니다.

166 166

167 프로비저닝된 액세스가 없으면 API는 각 빠른 모드 요청을 429로 거부하고, Claude Code는 각 거부를 [빠른 모드 속도 제한](#handle-rate-limits)으로 처리합니다. 속도 제한의 쿨다운과 달리 거부는 액세스가 프로비저닝될 때까지 계속됩니다.167 프로비저닝된 액세스가 없으면 API는 각 빠른 모드 요청을 429로 거부하고, Claude Code는 각 거부를 [빠른 모드 속도 제한](#handle-rate-limits)으로 처리합니다. 속도 제한의 쿨다운과 달리 거부는 액세스가 프로비저닝될 때까지 계속됩니다.

168* **Claude AI** (Team 및 Enterprise): 관리자가 [관리자 설정 > Claude Code](https://claude.ai/admin-settings/claude-code)에서 활성화합니다168* **Claude AI** (Team 및 Enterprise): Owner가 [**조직 설정 > Claude Code**](https://claude.ai/admin-settings/claude-code)에서 활성화합니다

169 169

170빠른 모드를 완전히 비활성화하는 또 다른 옵션은 `CLAUDE_CODE_DISABLE_FAST_MODE=1`을 설정하는 것입니다. [환경 변수](/docs/ko/env-vars)를 참조합니다.170빠른 모드를 완전히 비활성화하는 또 다른 옵션은 `CLAUDE_CODE_DISABLE_FAST_MODE=1`을 설정하는 것입니다. [환경 변수](/docs/ko/env-vars)를 참조합니다.

171 171

features-overview.md +3 −3

Details

248| **Subagents** | 생성 시 | 지정된 skill이 있는 신선한 컨텍스트, 또는 [포크](/docs/ko/sub-agents#fork-the-current-conversation)의 부모 대화 | 주 세션에서 격리됨 |248| **Subagents** | 생성 시 | 지정된 skill이 있는 신선한 컨텍스트, 또는 [포크](/docs/ko/sub-agents#fork-the-current-conversation)의 부모 대화 | 주 세션에서 격리됨 |

250 250

251\*기본적으로 skill 설명은 세션 시작 시 로드되므로 Claude가 사용할 시기를 결정할 수 있습니다. Skill의 frontmatter에서 `disable-model-invocation: true`를 설정하여 수동으로 호출할 때까지 Claude에서 완전히 숨깁니다. 작성하지 않은 skill의 경우, 파일을 편집하지 않고도 동일한 작업을 수행하도록 설정에서 [`skillOverrides`](/docs/ko/skills#override-skill-visibility-from-settings)를 설정하세요.251\*스킬의 frontmatter에서 [`disable-model-invocation: true`](/docs/ko/skills#control-who-invokes-a-skill)를 설정하면 해당 스킬의 설명이 Claude의 컨텍스트에 포함되지 않습니다. 직접 작성하지 않은 스킬의 경우, 파일을 편집하지 않고도 동일한 작업을 수행하도록 설정에서 [`skillOverrides`](/docs/ko/skills#override-skill-visibility-from-settings)를 설정하세요.

252 252

253<h3 id="understand-how-features-load">253<h3 id="understand-how-features-load">

254 기능이 어떻게 로드되는지 이해하기254 기능이 어떻게 로드되는지 이해하기

278 278

279 **로드되는 내용:** 모델 호출 가능 skill의 경우, Claude는 모든 요청에서 이름과 설명을 봅니다. `/<name>`으로 skill을 호출하거나 Claude가 자동으로 로드할 때, 전체 콘텐츠가 대화에 로드됩니다.279 **로드되는 내용:** 모델 호출 가능 skill의 경우, Claude는 모든 요청에서 이름과 설명을 봅니다. `/<name>`으로 skill을 호출하거나 Claude가 자동으로 로드할 때, 전체 콘텐츠가 대화에 로드됩니다.

280 280

281 **Claude가 skill을 선택하는 방식:** Claude는 작업을 skill 설명과 비교하여 관련성이 있는지 결정합니다. 설명이 모호하거나 겹치면, Claude가 잘못된 skill을 로드하거나 도움이 될 skill을 놓칠 수 있습니다. Claude에게 특정 skill을 사용하도록 지시하려면 `/<name>`으로 호출하세요. `disable-model-invocation: true`가 있는 Skill은 호출할 때까지 Claude에게 보이지 않습니다.281 **Claude가 스킬을 선택하는 방식:** Claude는 작업을 스킬 설명과 비교하여 관련성이 있는지 결정합니다. 설명이 모호하거나 겹치면, Claude가 잘못된 스킬을 로드하거나 도움이 될 스킬을 놓칠 수 있습니다. Claude에게 특정 스킬을 사용하도록 지시하려면 `/<name>`으로 호출하세요.

282 282

283 **컨텍스트 비용:** 사용할 때까지 낮음. 사용자 전용 skill은 호출할 때까지 0 비용입니다.283 **컨텍스트 비용:** 사용할 때까지 낮음. 사용자 전용 skill은 호출할 때까지 0 비용입니다.

284 284

285 **Subagent에서:** Skill은 subagent에서 다르게 작동합니다. 온디맨드 로딩 대신, subagent의 `skills` 필드에 나열된 skill은 시작 시 컨텍스트에 완전히 미리 로드됩니다. Subagent는 여전히 Skill 도구를 통해 나열되지 않은 프로젝트, 사용자 및 플러그인 skill을 검색하고 호출할 수 있습니다.285 **Subagent에서:** Skill은 subagent에서 다르게 작동합니다. 온디맨드 로딩 대신, subagent의 `skills` 필드에 나열된 skill은 시작 시 컨텍스트에 완전히 미리 로드됩니다. Subagent는 여전히 Skill 도구를 통해 나열되지 않은 프로젝트, 사용자 및 플러그인 skill을 검색하고 호출할 수 있습니다.

286 286

287 <Tip>부작용이 있는 skill에 `disable-model-invocation: true`를 사용하세요. 이는 컨텍스트를 절약하고 오직 사용자만 트리거하도록 보장합니다.</Tip>287 <Tip>부작용이 있는 스킬에 `disable-model-invocation: true`를 사용하세요. 이는 컨텍스트를 절약하고 사용자가 이름을 지정할 때만 실행되도록 보장합니다.</Tip>

288 </Tab>288 </Tab>

289 289

290 <Tab title="MCP servers">290 <Tab title="MCP servers">

fullscreen.md +2 −2

Details

108 * 막대 양쪽 끝에 `↑` 및 `↓` 화살표가 있는 경우, 화살표를 클릭하면 한 행씩 스크롤되고, 누르고 있으면 계속 스크롤됩니다. 화살표는 Claude Code v2.1.286 이상이 필요합니다.108 * 막대 양쪽 끝에 `↑` 및 `↓` 화살표가 있는 경우, 화살표를 클릭하면 한 행씩 스크롤되고, 누르고 있으면 계속 스크롤됩니다. 화살표는 Claude Code v2.1.286 이상이 필요합니다.

109* **목록 가장자리의 `↑ N more` 또는 `↓ N more` 행을 클릭**하면 옵션을 선택하지 않고 목록의 해당 끝으로 이동합니다. Claude Code v2.1.286 이상이 필요합니다.109* **목록 가장자리의 `↑ N more` 또는 `↓ N more` 행을 클릭**하면 옵션을 선택하지 않고 목록의 해당 끝으로 이동합니다. Claude Code v2.1.286 이상이 필요합니다.

110* **축소된 도구 결과를 클릭**하여 확장하고 전체 출력을 봅니다. 다시 클릭하면 축소됩니다. 도구 호출과 그 결과가 함께 확장됩니다. 더 표시할 내용이 있는 메시지만 클릭 가능합니다.110* **축소된 도구 결과를 클릭**하여 확장하고 전체 출력을 봅니다. 다시 클릭하면 축소됩니다. 도구 호출과 그 결과가 함께 확장됩니다. 더 표시할 내용이 있는 메시지만 클릭 가능합니다.

111 * 클릭하면 `!` 셸 명령어의 출력도 확장되며, 이는 이전의 잘린 결과이거나 명령어 실행 중인 라이브 진행 행입니다. Claude Code v2.1.257 이상이 필요합니다.111 * 클릭하면 `!` 셸 명령의 출력도 확장되며, 이는 이전의 잘린 결과이거나 명령 실행 중인 라이브 진행 행입니다. Claude Code v2.1.257 이상이 필요합니다.

112 * 클릭하면 발신자가 [팀원](/docs/ko/agent-teams)이거나 세션에서 실행 중인 다른 에이전트일 때 흐릿한 `Message from @<sender>` 행도 확장됩니다. [다른 세션 중 하나](/docs/ko/cross-session-messaging#what-a-message-looks-like)의 메시지 행도 메시지의 첫 번째 행을 표시하며 클릭할 수 없으므로 `Ctrl+o`를 눌러 해당 메시지를 읽습니다.112 * 클릭하면 발신자가 [팀원](/docs/ko/agent-teams)이거나 세션에서 실행 중인 다른 에이전트일 때 흐릿한 `Message from @<sender>` 행도 확장됩니다.

113* **macOS에서 `Cmd`를 누르거나, Linux 및 Windows에서 `Ctrl`을 누르고 URL 또는 파일 경로를 클릭**하여 엽니다. 일반 `http://` 및 `https://` URL은 브라우저에서 열리고, Edit 또는 Write 후에 인쇄된 것과 같은 도구 출력의 파일 경로는 기본 애플리케이션에서 열립니다. 수정자 없이 일반 클릭하면 링크가 열리지 않으며, 이는 기본 터미널 동작과 일치합니다.113* **macOS에서 `Cmd`를 누르거나, Linux 및 Windows에서 `Ctrl`을 누르고 URL 또는 파일 경로를 클릭**하여 엽니다. 일반 `http://` 및 `https://` URL은 브라우저에서 열리고, Edit 또는 Write 후에 인쇄된 것과 같은 도구 출력의 파일 경로는 기본 애플리케이션에서 열립니다. 수정자 없이 일반 클릭하면 링크가 열리지 않으며, 이는 기본 터미널 동작과 일치합니다.

114 * Claude Code는 네트워크(UNC) 경로(예: `\\server\share\file.ts`)를 링크 없는 일반 텍스트로 렌더링합니다. 네트워크 경로를 열면 Windows 자격 증명이 해당 호스트로 전송될 수 있기 때문입니다.114 * Claude Code는 네트워크(UNC) 경로(예: `\\server\share\file.ts`)를 링크 없는 일반 텍스트로 렌더링합니다. 네트워크 경로를 열면 Windows 자격 증명이 해당 호스트로 전송될 수 있기 때문입니다.

115 * 일부 macOS 터미널은 `Cmd`+클릭을 실행 중인 앱으로 전달하며, 터미널 마우스 프로토콜에는 `Cmd` 키를 인코딩할 방법이 없으므로 Claude Code는 일반 클릭을 받습니다. Ghostty 및 macOS의 Warp에서 Claude Code는 이를 감지하고 링크에 대한 일반 클릭으로 열 수 있으며, `Cmd`를 누르고 있으면 여전히 작동합니다.115 * 일부 macOS 터미널은 `Cmd`+클릭을 실행 중인 앱으로 전달하며, 터미널 마우스 프로토콜에는 `Cmd` 키를 인코딩할 방법이 없으므로 Claude Code는 일반 클릭을 받습니다. Ghostty 및 macOS의 Warp에서 Claude Code는 이를 감지하고 링크에 대한 일반 클릭으로 열 수 있으며, `Cmd`를 누르고 있으면 여전히 작동합니다.

google-vertex-ai.md +17 −0

Details

295 295

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

297 297

298<h3 id="when-your-organization-enforces-a-model-allowlist">

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

300</h3>

301

302관리형 설정에서 [`enforceAvailableModels`](/docs/ko/model-config#enforce-the-allowlist-for-the-default-model)를 설정하면 시작 모델 확인은 `availableModels` 목록에서 허용하는 모델만 사용합니다. 이 기능에는 Claude Code v2.1.287 이상이 필요합니다. `enforceAvailableModels`가 없는 목록은 이러한 확인을 제한하지 않습니다.

303

304확인 과정에서는 각 항목을 Agent Platform으로 보낼 모델 ID와 비교하므로, 목록은 해당 ID로 작성합니다. 다음 예시는 Opus 4.8과 Sonnet 4.5를 허용합니다.

305

306```json theme={null}

307{

308 "availableModels": ["claude-opus-4-8", "claude-sonnet-4-5@20250929"],

309 "enforceAvailableModels": true

310}

311```

312

313별칭, 버전 접두사 및 `modelOverrides` 항목에 대해서는 [타사 배포를 위한 모델 고정](/docs/ko/model-config#pin-models-for-third-party-deployments)을 참조하세요.

314

298<h3 id="when-a-model-is-disabled-mid-session">315<h3 id="when-a-model-is-disabled-mid-session">

299 세션 중에 모델이 비활성화될 때316 세션 중에 모델이 비활성화될 때

300</h3>317</h3>

headless.md +1 −1

Details

59| 시스템 프롬프트 추가 | `--append-system-prompt`, `--append-system-prompt-file` |59| 시스템 프롬프트 추가 | `--append-system-prompt`, `--append-system-prompt-file` |

60| 설정 | `--settings <file-or-json>` |60| 설정 | `--settings <file-or-json>` |

61| MCP 서버 | `--mcp-config <file-or-json>` |61| MCP 서버 | `--mcp-config <file-or-json>` |

63| 플러그인 | `--plugin-dir <path>`, `--plugin-url <url>` |63| 플러그인 | `--plugin-dir <path>`, `--plugin-url <url>` |

64 64

65bare 모드는 세션이 실행되는 동안 일어나는 일도 제한합니다:65bare 모드는 세션이 실행되는 동안 일어나는 일도 제한합니다:

hooks.md +46 −10

Details

438| 필드 | 필수 | 설명 |438| 필드 | 필수 | 설명 |

439| :- | :- | :- |439| :- | :- | :- |

440| `type` | 예 | `"command"`, `"http"`, `"mcp_tool"`, `"prompt"` 또는 `"agent"` |440| `type` | 예 | `"command"`, `"http"`, `"mcp_tool"`, `"prompt"` 또는 `"agent"` |

441| `if` | 아니요 | `"Bash(git *)"` 또는 `"Edit(*.ts)"`와 같은 이 hook이 실행되는 시기를 필터링하는 권한 규칙 구문. hook 명령은 도구 호출이 패턴과 일치하는 경우에만 실행됩니다. Bash 패턴이 하위 명령, `$()` 및 백틱에 대해 평가되는 방식에 대해서는 아래의 [Bash 일치 테이블](#bash-if-matching)을 참조하십시오. 도구 이벤트에서만 평가됩니다: `PreToolUse`, `PostToolUse`, `PostToolUseFailure`, `PermissionRequest` 및 `PermissionDenied`. 다른 이벤트에서는 `if`가 설정된 hook이 실행되지 않습니다. [권한 규칙](/docs/ko/permissions)과 동일한 구문을 사용합니다. |441| `if` | 아니요 | `"Bash(git *)"` 또는 `"Edit(*.ts)"`와 같이 이 훅이 실행되는 시기를 필터링하는 [권한 규칙 구문](/docs/ko/permissions#permission-rule-syntax). 훅 명령은 도구 호출이 패턴과 일치하는 경우에만 실행됩니다. Bash 패턴이 하위 명령, `$()` 및 백틱에 대해 평가되는 방식에 대해서는 [Bash 일치 테이블](#bash-if-matching)을 참조하십시오. 도구 이벤트에서만 평가됩니다: `PreToolUse`, `PostToolUse`, `PostToolUseFailure`, `PermissionRequest` 및 `PermissionDenied`. 다른 이벤트에서는 `if`가 설정된 훅이 실행되지 않습니다. |

442| `timeout` | 아니요 | 취소하기 전 초 단위. Claude Code는 [`async: true`](#run-hooks-in-the-background)로 실행하는 명령 hook에 적용하지 않습니다. 기본값: `command`, `http` 및 `mcp_tool`의 경우 600, `prompt`의 경우 30, `agent`의 경우 60. Claude Code는 [`UserPromptSubmit`](#userpromptsubmit), [`PreModelSwitch`](#premodelswitch) 및 [`PostModelSwitch`](#postmodelswitch)에서 `command`, `http` 및 `mcp_tool` 기본값을 30으로 낮추고, [`MessageDisplay`](#messagedisplay)에서 10으로 낮춥니다. [`SessionEnd`](#sessionend) hook은 1.5초 예산을 공유합니다. 설정이 더 긴 hook별 `timeout`을 설정하면 Claude Code는 예산을 일치하도록 올립니다(최대 60초). |442| `timeout` | 아니요 | 취소하기 전 초 단위. Claude Code는 [`async: true`](#run-hooks-in-the-background)로 실행하는 명령 hook에 적용하지 않습니다. 기본값: `command`, `http` 및 `mcp_tool`의 경우 600, `prompt`의 경우 30, `agent`의 경우 60. Claude Code는 [`UserPromptSubmit`](#userpromptsubmit), [`PreModelSwitch`](#premodelswitch) 및 [`PostModelSwitch`](#postmodelswitch)에서 `command`, `http` 및 `mcp_tool` 기본값을 30으로 낮추고, [`MessageDisplay`](#messagedisplay)에서 10으로 낮춥니다. [`SessionEnd`](#sessionend) hook은 1.5초 예산을 공유합니다. 설정이 더 긴 hook별 `timeout`을 설정하면 Claude Code는 예산을 일치하도록 올립니다(최대 60초). |

443| `statusMessage` | 아니요 | hook이 실행되는 동안 표시되는 사용자 정의 스피너 메시지 |443| `statusMessage` | 아니요 | hook이 실행되는 동안 표시되는 사용자 정의 스피너 메시지 |

444| `once` | 아니요 | `true`이면 Claude Code는 첫 번째 성공적인 실행 후 hook을 제거합니다. 실패하거나 종료 코드 2로 차단되거나 시간 초과되는 실행은 hook을 제자리에 두므로 다음 일치 이벤트에서 다시 실행됩니다. [스킬 frontmatter](#hooks-in-skills-and-agents)에서 선언된 hook에만 적용됩니다. 설정 파일 및 에이전트 frontmatter에서는 무시됩니다. |444| `once` | 아니요 | `true`이면 Claude Code는 첫 번째 성공적인 실행 후 hook을 제거합니다. 실패하거나 종료 코드 2로 차단되거나 시간 초과되는 실행은 hook을 제자리에 두므로 다음 일치 이벤트에서 다시 실행됩니다. [스킬 frontmatter](#hooks-in-skills-and-agents)에서 선언된 hook에만 적용됩니다. 설정 파일 및 에이전트 frontmatter에서는 무시됩니다. |

447 447

448파일 도구의 `if` 조건에서 `"Edit(src/**)"` 같은 단일 세그먼트 디렉터리 패턴은 작업 디렉터리의 `src` 디렉터리와 그 아래의 파일만 일치합니다. 모든 깊이에서 `src`라는 디렉터리와 일치하려면 `"Edit(**/src/**)"` 형식으로 작성하십시오. v2.1.214 이전에는 `"Edit(src/**)"`가 작업 디렉터리 아래의 모든 깊이에서 `src`라는 디렉터리와 일치했습니다.448파일 도구의 `if` 조건에서 `"Edit(src/**)"` 같은 단일 세그먼트 디렉터리 패턴은 작업 디렉터리의 `src` 디렉터리와 그 아래의 파일만 일치합니다. 모든 깊이에서 `src`라는 디렉터리와 일치하려면 `"Edit(**/src/**)"` 형식으로 작성하십시오. v2.1.214 이전에는 `"Edit(src/**)"`가 작업 디렉터리 아래의 모든 깊이에서 `src`라는 디렉터리와 일치했습니다.

449 449

450<span id="bash-if-matching" />Bash 패턴의 경우 hook 명령이 실행되는지 여부는 패턴의 형태와 Claude가 호출하는 Bash 명령에 따라 다릅니다. 선행 `VAR=value` 할당은 일치하기 전에 제거됩니다.450<h4 id="bash-if-matching">

451 `if` 패턴이 Bash 명령과 일치하는 방식

452</h4>

453

454[`if` 필드](#common-fields)의 Bash 패턴의 경우, 훅 명령이 실행되는지 여부는 패턴의 형태와 Claude가 호출하는 Bash 명령에 따라 다릅니다. 선행 `VAR=value` 할당은 일치하기 전에 제거됩니다.

451 455

453| :- | :- | :- | :- |457| :- | :- | :- | :- |

1913 1917

1914| 필드 | 타입 | 예시 | 설명 |1918| 필드 | 타입 | 예시 | 설명 |

1915| :- | :- | :- | :- |1919| :- | :- | :- | :- |

1916| `questions` | array | `[{"question": "Which framework?", "header": "Framework", "options": [{"label": "React"}], "multiSelect": false}]` | 표시할 질문. 각 질문에는 `question` 문자열, 짧은 `header`, `options` 배열, 선택적 `multiSelect` 플래그가 있습니다 |1920| `questions` | array | `[{"question": "Which framework?", "header": "Framework", "options": [{"label": "React", "description": "Component library"}, {"label": "Vue", "description": "Progressive framework"}], "multiSelect": false}]` | 제시할 질문으로, 각각 `question` 문자열, 짧은 `header`, `options` 배열, 선택적 `multiSelect` 플래그를 가집니다 |

1917| `answers` | object | `{"Which framework?": "React"}` | 선택 사항. 질문 텍스트를 선택된 옵션 레이블에 매핑합니다. 다중 선택 답변은 레이블을 쉼표로 연결합니다. Claude는 이 필드를 설정하지 않으며, 프로그래밍 방식으로 답하려면 `updatedInput`을 통해 제공합니다 |1921| `answers` | object | `{"Which framework?": "React"}` | 선택 사항. 질문 텍스트를 선택된 옵션 레이블에 매핑합니다. 다중 선택 답변은 레이블을 쉼표로 연결합니다. Claude는 이 필드를 설정하지 않으며, 프로그래밍 방식으로 답하려면 `updatedInput`을 통해 제공합니다 |

1918 1922

1919<h5 id="exitplanmode">1923<h5 id="exitplanmode">

1965}1969}

1966```1970```

1967 1971

1968<span id="allow-with-updatedinput" />1972<Note>

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

1974</Note>

1969 1975

1970`-p` 플래그를 사용하는 [비대화형 모드](/docs/ko/headless)에서 Claude Code는 Agent SDK의 `canUseTool` 콜백처럼 프롬프트를 수신할 [권한 호스트](/docs/ko/headless#turn-off-permission-prompts-in-unattended-runs)가 실행에 있을 때만 `AskUserQuestion`과 `ExitPlanMode`를 제공합니다. 이 도구들은 사용자 상호 작용이 필요합니다. `permissionDecision: "allow"`를 `updatedInput`과 함께 반환하면 이 요구 사항이 충족됩니다. 훅은 stdin에서 도구의 입력을 읽고, 자체 UI를 통해 답변을 수집한 다음, 도구가 프롬프트 없이 실행되도록 `updatedInput`에 답변을 담아 반환합니다. 이 도구들에는 `"allow"`만 반환하는 것으로는 충분하지 않습니다. `AskUserQuestion`의 경우 원래 `questions` 배열을 그대로 반환하고, 각 질문의 텍스트를 선택된 답변에 매핑하는 [`answers`](#askuserquestion) 객체를 추가합니다.1976<h4 id="allow-with-updatedinput">

1977 사용자 상호작용이 필요한 도구

1978</h4>

1971 1979

1972서버가 [`_meta["anthropic/requiresUserInteraction"]`](/docs/ko/mcp#require-approval-for-a-specific-tool)로 표시한 MCP 도구는 더 엄격합니다. 훅은 `updatedInput` 유무와 관계없이 `"allow"`로 승인 프롬프트를 건너뛸 수 없습니다. Claude Code가 훅이 해당 도구에 필요한 상호 작용을 수집했는지 확인할 수 없기 때문입니다.1980`AskUserQuestion`과 `ExitPlanMode`는 사용자 상호작용이 필요합니다. `-p` 플래그를 사용하는 [비대화형 모드](/docs/ko/headless)에서 Claude Code는 Agent SDK `canUseTool` 콜백처럼 프롬프트를 받을 [권한 호스트](/docs/ko/headless#turn-off-permission-prompts-in-unattended-runs)가 실행에 있는 경우에만 이 도구를 제공합니다.

1973 1981

1974<Note>1982`PreToolUse` 훅은 다음을 수행할 때 이 요구 사항을 충족합니다.

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

1976</Note>19841. stdin에서 도구의 입력을 읽습니다

19852. 자체 UI를 통해 답변을 수집합니다

19863. 답변을 담은 `updatedInput`과 함께 `permissionDecision: "allow"`를 반환하여 도구가 확인 요청 없이 실행되게 합니다

1987

1988이 도구에는 `"allow"`만 반환하는 것으로는 충분하지 않습니다.

1989

1990`AskUserQuestion`의 경우 원래 `questions` 배열을 그대로 돌려보내고, 각 질문 텍스트를 선택된 답변에 매핑하는 [`answers`](#askuserquestion) 객체를 추가하십시오. 다음 출력은 한 질문에 `React`로 답합니다.

1991

1992```json theme={null}

1993{

1994 "hookSpecificOutput": {

1995 "hookEventName": "PreToolUse",

1996 "permissionDecision": "allow",

1997 "updatedInput": {

1998 "questions": [

1999 {

2000 "question": "Which framework?",

2001 "header": "Framework",

2002 "options": [{"label": "React", "description": "Component library"}, {"label": "Vue", "description": "Progressive framework"}],

2003 "multiSelect": false

2004 }

2005 ],

2006 "answers": {"Which framework?": "React"}

2007 }

2008 }

2009}

2010```

2011

2012서버가 [`_meta["anthropic/requiresUserInteraction"]`](/docs/ko/mcp#require-approval-for-a-specific-tool)로 표시한 MCP 도구는 더 엄격합니다. 훅은 `updatedInput` 유무와 관계없이 `"allow"`로 승인 프롬프트를 건너뛸 수 없습니다. Claude Code가 훅이 해당 도구에 필요한 상호 작용을 수집했는지 확인할 수 없기 때문입니다.

1977 2013

1978<h4 id="defer-a-tool-call-for-later">2014<h4 id="defer-a-tool-call-for-later">

1979 도구 호출을 나중으로 지연2015 도구 호출을 나중으로 지연

2000 "deferred_tool_use": {2036 "deferred_tool_use": {

2001 "id": "toolu_01abc",2037 "id": "toolu_01abc",

2002 "name": "AskUserQuestion",2038 "name": "AskUserQuestion",

2003 "input": { "questions": [{ "question": "Which framework?", "header": "Framework", "options": [{"label": "React"}, {"label": "Vue"}], "multiSelect": false }] }2039 "input": { "questions": [{ "question": "Which framework?", "header": "Framework", "options": [{"label": "React", "description": "Component library"}, {"label": "Vue", "description": "Progressive framework"}], "multiSelect": false }] }

2004 }2040 }

2005}2041}

2006```2042```

interactive-mode.md +2 −0

Details

470* 계정이 사용량 한도에 가깝거나 도달했습니다. 한계에 도달할 때까지 제안을 계속 표시하려면 [`CLAUDE_CODE_ENABLE_PROMPT_SUGGESTION`](/docs/ko/env-vars)을 `true`로 설정합니다. v2.1.238 이전에는 Claude Code가 변수를 `true`로 설정해도 한계 근처에서 제안을 건너뛰었습니다.470* 계정이 사용량 한도에 가깝거나 도달했습니다. 한계에 도달할 때까지 제안을 계속 표시하려면 [`CLAUDE_CODE_ENABLE_PROMPT_SUGGESTION`](/docs/ko/env-vars)을 `true`로 설정합니다. v2.1.238 이전에는 Claude Code가 변수를 `true`로 설정해도 한계 근처에서 제안을 건너뛰었습니다.

471* [에이전트 팀](/docs/ko/agent-teams)에서 기본적으로 팀원의 세션에서. 리드의 세션은 제안을 표시합니다.471* [에이전트 팀](/docs/ko/agent-teams)에서 기본적으로 팀원의 세션에서. 리드의 세션은 제안을 표시합니다.

472 472

473`Showing fewer prompt suggestions · use one to bring them back` 알림은 연속으로 많은 제안을 사용하지 않고 넘겼기 때문에 Claude Code가 제안을 덜 자주 표시하고 있다는 의미입니다. 평소 빈도로 되돌리려면 제안을 사용하거나 [`CLAUDE_CODE_ENABLE_PROMPT_SUGGESTION`](/docs/ko/env-vars)을 `true`로 설정합니다.

474

473인쇄 모드에서 Claude Code는 기본적으로 제안을 생성하지 않습니다. Claude Code가 각 턴 후에 `prompt_suggestion` 메시지를 내보내도록 하려면 `-p "<prompt>" --output-format stream-json --verbose`와 함께 [`--prompt-suggestions`](/docs/ko/cli-reference#cli-flags)를 전달합니다. 생성기는 여기서도 매우 짧은 대화와 콜드 프롬프트 캐시를 건너뛰므로, 단일 짧은 `-p` 쿼리는 아무것도 내보내지 않을 수 있습니다.475인쇄 모드에서 Claude Code는 기본적으로 제안을 생성하지 않습니다. Claude Code가 각 턴 후에 `prompt_suggestion` 메시지를 내보내도록 하려면 `-p "<prompt>" --output-format stream-json --verbose`와 함께 [`--prompt-suggestions`](/docs/ko/cli-reference#cli-flags)를 전달합니다. 생성기는 여기서도 매우 짧은 대화와 콜드 프롬프트 캐시를 건너뛰므로, 단일 짧은 `-p` 쿼리는 아무것도 내보내지 않을 수 있습니다.

474 476

475<h3 id="turn-prompt-suggestions-off">477<h3 id="turn-prompt-suggestions-off">

keybindings.md +4 −0

Details

464| :- | :- | :- |464| :- | :- | :- |

467| `agents:find` | Ctrl+F | [`n:` 필터](/docs/ko/agent-view#filter-sessions)를 사용하여 이름으로 세션을 찾습니다. v2.1.288 이상 필요 |

468| `agents:rename` | Ctrl+R | 선택한 세션의 [이름을 변경](/docs/ko/agent-view#organize-the-list)합니다. v2.1.288 이상 필요 |

469| `agents:previousGroup` | Ctrl+Up, Meta+Up | 이전 [그룹 헤더](/docs/ko/agent-view#organize-the-list)로 이동합니다. v2.1.288 이상 필요 |

470| `agents:nextGroup` | Ctrl+Down, Meta+Down | 다음 그룹 헤더로 이동합니다. v2.1.288 이상 필요 |

467 471

468에이전트 보기가 열려 있을 때 Claude Code는 `Agents` 컨텍스트가 바인딩하는 모든 키에 대해 `Agents` 바인딩을 사용하고 동일한 키의 `Chat` 또는 `Global` 바인딩을 무시합니다. 예를 들어 에이전트 보기에서 Ctrl+S를 누르면 기본 `chat:stash`를 트리거하는 대신 세션 그룹화를 전환합니다.472에이전트 보기가 열려 있을 때 Claude Code는 `Agents` 컨텍스트가 바인딩하는 모든 키에 대해 `Agents` 바인딩을 사용하고 동일한 키의 `Chat` 또는 `Global` 바인딩을 무시합니다. 예를 들어 에이전트 보기에서 Ctrl+S를 누르면 기본 `chat:stash`를 트리거하는 대신 세션 그룹화를 전환합니다.

469 473

managed-mcp.md +61 −29

Details

282 282

283허용 목록 및 거부 목록은 구성된 서버 중 로드할 수 있는 서버를 필터링합니다. 이들은 레지스트리가 아닙니다. 서버는 사용자, 플러그인 또는 조직에 의해 추가되어야 두 목록 중 하나가 적용됩니다.283허용 목록 및 거부 목록은 구성된 서버 중 로드할 수 있는 서버를 필터링합니다. 이들은 레지스트리가 아닙니다. 서버는 사용자, 플러그인 또는 조직에 의해 추가되어야 두 목록 중 하나가 적용됩니다.

284 284

285조직이 `managedMcpServers`를 통해 제공하는 서버는 허용 목록 항목 없이 로드되며, [서버 평가 방식](#how-a-server-is-evaluated)에서 `managed-mcp.json` 서버를 다룹니다. 거부 목록은 인프로세스 `type: "sdk"` 항목을 제외한 모든 서버에 적용됩니다.285조직이 `managedMcpServers`를 통해 제공하는 서버는 허용 목록 항목 없이 로드되며, [허용 목록 검사를 건너뛰는 서버](#servers-that-skip-the-allowlist-check)에서 `managed-mcp.json` 서버를 다룹니다. 거부 목록은 인프로세스 `type: "sdk"` 항목을 제외하고 출처에 관계없이 모든 서버에 적용됩니다.

286 286

287서버를 사용자에게 배포하려면 [`managed-mcp.json`](#exclusive-control-with-managed-mcp-json) 또는 [`managedMcpServers`](#provide-servers-through-managed-settings)를 사용합니다. 두 목록 모두 [`--mcp-config` CLI 플래그](/docs/ko/cli-reference#cli-flags)로 전달된 서버를 필터링하며, 인프로세스 `type: "sdk"` 항목을 제외합니다. `--strict-mcp-config`는 로드되는 구성 파일을 제한하며 두 목록을 우회하지 않습니다.287서버를 사용자에게 배포하려면 [`managed-mcp.json`](#exclusive-control-with-managed-mcp-json) 또는 [`managedMcpServers`](#provide-servers-through-managed-settings)를 사용합니다. 두 목록 모두 [`--mcp-config` CLI 플래그](/docs/ko/cli-reference#cli-flags)로 전달된 서버를 필터링하며, 인프로세스 `type: "sdk"` 항목을 제외합니다. `--strict-mcp-config`는 로드되는 구성 파일을 제한하며 두 목록을 우회하지 않습니다.

288 288

308| :- | :- | :- |308| :- | :- | :- |

312 312

313`allowedMcpServers`를 설정하지 않는 것은 빈 배열로 설정하는 것과 다릅니다.313`allowedMcpServers`를 설정하지 않는 것은 빈 배열로 설정하는 것과 다릅니다.

314 314

315| 설정 | 설정하지 않음 (기본값) | 빈 배열 `[]` | 채워짐 |315| 설정 | 설정하지 않음 (기본값) | 빈 배열 `[]` | 채워짐 |

316| :- | :- | :- | :- |316| :- | :- | :- | :- |

319 319

320관리 설정의 잘못된 항목에 대해서는 [관리 설정의 잘못된 항목](/docs/ko/managed-settings#invalid-entries-in-managed-settings)을 참조합니다.320관리 설정의 잘못된 항목에 대해서는 [관리 설정의 잘못된 항목](/docs/ko/managed-settings#invalid-entries-in-managed-settings)을 참조합니다.

321 321

322<h4 id="how-servername-entries-match">

323 `serverName` 항목 일치 방식

324</h4>

325

326`serverName` 항목은 와일드카드 없이 사용자가 할당한 레이블과 정확하게 일치합니다.

327

322<Warning>328<Warning>

323 두 목록 중 하나의 `serverName` 항목은 보안 제어가 아닙니다. 이름은 `claude mcp add`를 실행하거나 구성 파일을 편집할 때 사용자가 할당하는 레이블이지 기본 서버가 아니므로 사용자는 모든 서버를 `github`라고 부를 수 있습니다. claude.ai 커넥터의 경우 이름은 claude.ai에서 반환하는 표시 이름이며 변경될 수 있습니다. 실제로 실행되는 서버를 적용하려면 `serverCommand` 또는 `serverUrl` 항목을 추가합니다.329 두 목록 중 하나의 `serverName` 항목은 보안 제어가 아닙니다. 이름은 `claude mcp add`를 실행하거나 구성 파일을 편집할 때 사용자가 할당하는 레이블이지 기본 서버가 아니므로 사용자는 모든 서버를 `github`라고 부를 수 있습니다. claude.ai 커넥터의 경우 이름은 claude.ai에서 반환하는 표시 이름이며 변경될 수 있습니다. 실제로 실행되는 서버를 적용하려면 `serverCommand` 또는 `serverUrl` 항목을 추가합니다.

324</Warning>330</Warning>

330 336

331Claude Code가 자체적으로 가져오는 모든 claude.ai 커넥터를 끄려면 [`disableClaudeAiConnectors`](/docs/ko/mcp#disable-claude-ai-connectors)를 참조합니다.337Claude Code가 자체적으로 가져오는 모든 claude.ai 커넥터를 끄려면 [`disableClaudeAiConnectors`](/docs/ko/mcp#disable-claude-ai-connectors)를 참조합니다.

332 338

333<h3 id="how-a-server-is-evaluated">339<h4 id="how-servercommand-entries-match">

334 서버 평가 방식340 `serverCommand` 항목 일치 방식

335</h3>341</h4>

~~336~~

337서버를 로드하기 전에 `managed-mcp.json`의 서버를 포함하여 Claude Code는 아래의 세 가지 검사를 순서대로 실행합니다. 사용자가 서버를 다시 연결하거나 `/mcp`에서 비활성화된 서버를 다시 켤 때 다시 실행합니다. 인프로세스 `type: "sdk"` 서버는 [세션을 시작한 앱이 등록](/docs/ko/mcp#how-connectors-reach-claude-code)하며 세 가지 모두 건너뜁니다.

~~338~~

3391. **목록 병합.** 모든 설정 범위의 허용 목록 및 거부 목록 항목이 하나의 허용 목록과 하나의 거부 목록으로 결합됩니다. `allowManagedMcpServersOnly`가 `true`일 때 관리 허용 목록만 유지됩니다. 거부 목록은 항상 모든 범위에서 병합됩니다. 둘 이상의 관리 소스가 있을 때 [모든 관리 소스에서 읽은 키](/docs/ko/managed-settings#keys-read-from-every-admin-source)에서 관리 범위의 목록을 제공하는 소스를 설명합니다.

3402. **거부 목록 확인.** URL, 명령 또는 이름으로 거부 목록 항목과 일치하는 서버는 차단됩니다. 거부 목록 일치를 무시하는 것은 없습니다.

3413. **허용 목록 확인.** `allowedMcpServers`가 어디에도 설정되지 않으면 거부 목록을 통과한 모든 서버가 로드됩니다. 설정되면 서버가 일치해야 하는 것은 아래 표에 표시된 유형에 따라 다릅니다.

~~342~~

343 세 그룹의 서버는 이 검사를 건너뜁니다.

344 342

345 * 조직 자체의 서버: 모든 `managedMcpServers` 항목과 값에 `${VAR}` 확장을 사용하지 않는 모든 `managed-mcp.json` 항목입니다.343`serverCommand` 항목은 `{ "serverCommand": ["npx", "-y", "server"] }`처럼 명령과 인수를 하나의 배열로 담습니다. Claude Code는 이 배열을 서버 구성의 명령 및 인수와 비교합니다.

346 * 기본 제공 서버: Chrome의 Claude, Claude Code가 실행 중인 VS Code 또는 JetBrains IDE에 연결하는 `ide` 서버, CLI 자체가 구성하는 서버입니다.

347 * [Claude Tag](/docs/ko/claude-tag) 세션의 Slack 도구: 스레드를 읽고 회신을 게시하는 데 사용하는 서버는 허용 목록 항목 없이 로드됩니다.

348 344

349 명령, 인수, `env`, URL 또는 헤더에서 `${VAR}` 확장을 사용하는 `managed-mcp.json` 서버는 여전히 확인되며, 사용자, 플러그인, claude.ai가 추가하는 모든 서버와 사용자가 `--mcp-config`로 전달하는 모든 서버도 확인됩니다.345* **명령은 정확하게 일치합니다.** 모든 인수, 순서대로. `["npx", "-y", "server"]`는 `["npx", "server"]` 또는 `["npx", "-y", "server", "--flag"]`와 일치하지 않습니다.

346* **`env` 블록은 비교되지 않습니다.** `["node", "server.js"]`는 어떤 `env` 값으로든 해당 명령을 실행하는 서버와 일치합니다. 일부 환경 변수는 시작 시 `node`가 로드하는 항목을 변경합니다. `env` 값을 직접 설정하려면 [`managed-mcp.json`](#exclusive-control-with-managed-mcp-json)에서 서버를 정의합니다.

350 347

351| 서버 유형 | 일치할 때 허용됨 |348<h4 id="how-serverurl-entries-match">

352| :- | :- |349 `serverUrl` 항목 일치 방식

353| 원격 (HTTP 또는 SSE) | `serverUrl` 항목. `serverName` 일치는 허용 목록에 `serverUrl` 항목이 없을 때만 계산됨 |350</h4>

354| Stdio | `serverCommand` 항목. `serverName` 일치는 허용 목록에 `serverCommand` 항목이 없을 때만 계산됨 |

355 351

356이러한 검사 내에서 세 가지 일치 규칙이 적용됩니다.352URL은 스키마를 포함하여 패턴의 어디든 `*` 와일드카드를 지원합니다. 호스트명 일치는 대소문자를 구분하지 않으며 후행 FQDN 점을 무시하므로 `https://Mcp.Example.com/*`은 `https://mcp.example.com/api`와 일치합니다. 경로는 대소문자를 구분합니다.

357 353

358* **명령은 정확하게 일치합니다.** 모든 인수, 순서대로. `["npx", "-y", "server"]`는 `["npx", "server"]` 또는 `["npx", "-y", "server", "--flag"]`와 일치하지 않습니다.354아래 표는 일반적인 패턴이 허용하는 대상을 보여줍니다.

359* **`serverCommand` 및 `serverUrl` 값은 일치 전에 확장됩니다.** 정책 항목과 서버의 구성된 값 모두 [`${VAR}` 및 `${VAR:-default}` 확장](/docs/ko/mcp#environment-variable-expansion-in-mcp-json)을 거치므로 `["${HOME}/bin/server"]`로 작성된 항목은 동일한 참조 또는 확장된 경로를 사용하는 서버 구성과 일치합니다. Windows에서는 `${HOME}` 대신 `${USERPROFILE}`과 같이 설정된 환경 변수를 참조합니다. `serverName` 값은 문자 그대로 일치하며 절대 확장되지 않습니다. 두 쪽은 다른 환경을 읽습니다. [정책 항목 확장 방식](#how-policy-entries-expand)에서 어느 것이고 허용 목록 및 거부 목록 항목이 어떻게 다른지 다룹니다.

360* **URL은 패턴의 어디든 `*` 와일드카드를 지원합니다.** 스키마 포함. 호스트명 일치는 대소문자를 구분하지 않으며 후행 FQDN 점을 무시하므로 `https://Mcp.Example.com/*`은 `https://mcp.example.com/api`와 일치합니다. 경로는 대소문자를 구분합니다.

361 355

362| 패턴 | 허용 |356| 패턴 | 허용 |

363| :- | :- |357| :- | :- |

368| `*://mcp.example.com/*` | 특정 도메인으로의 모든 스키마 |362| `*://mcp.example.com/*` | 특정 도메인으로의 모든 스키마 |

369 363

370<h4 id="how-policy-entries-expand">364<h4 id="how-policy-entries-expand">

371 정책 항목 확장 방식365 `serverCommand` 및 `serverUrl` 항목의 환경 변수

372</h4>366</h4>

373 367

374서버의 구성된 값은 `.mcp.json`의 나머지와 같이 라이브 프로세스 환경에서 확장됩니다. 정책 항목은 고정된 환경에서 확장되므로 프로젝트 또는 사용자 설정 파일에 의해 설정된 변수가 허용 목록 항목의 의미를 변경할 수 없습니다. 정책 항목은 여전히 참조하는 모든 변수에 대해 시작 셸의 값에 따라 달라지므로 적용에 의존하는 항목에는 리터럴 URL 및 명령을 사용합니다.368`serverCommand` 및 `serverUrl` 값은 일치 전에 확장됩니다. 정책 항목과 서버의 구성된 값 모두 [`${VAR}` 및 `${VAR:-default}` 확장](/docs/ko/mcp#environment-variable-expansion-in-mcp-json)을 거치므로 `["${HOME}/bin/server"]`로 작성된 항목은 동일한 참조 또는 확장된 경로를 사용하는 서버 구성과 일치합니다. `serverName` 값은 문자 그대로 일치하며 절대 확장되지 않습니다.

369

370두 쪽은 다른 환경을 읽습니다.

371

372* **서버의 구성된 값**: `.mcp.json`의 나머지와 같이 라이브 프로세스 환경에서 확장됩니다

373* **정책 항목**: 고정된 환경에서 확장되므로 프로젝트 또는 사용자 설정 파일에 의해 설정된 변수가 허용 목록 항목의 의미를 변경할 수 없습니다

374

375정책 항목은 여전히 참조하는 모든 변수에 대해 시작 셸의 값에 따라 달라지므로 적용에 의존하는 항목에는 리터럴 URL 및 명령을 사용합니다.

376

377Windows에서는 `${HOME}` 대신 `${USERPROFILE}`과 같이 해당 환경에 설정된 환경 변수를 참조합니다.

378

379두 목록은 서로 다르게 확장됩니다.

375 380

377| - | - | - |382| - | - | - |

380 385

381Claude Code v2.1.219 이상이 필요합니다.386고정된 환경과 이 표의 규칙을 사용하려면 Claude Code v2.1.219 이상이 필요합니다.

387

388<h3 id="how-a-server-is-evaluated">

389 서버 평가 방식

390</h3>

391

392서버를 로드하기 전에 `managed-mcp.json`의 서버를 포함하여 Claude Code는 아래의 세 가지 검사를 순서대로 실행합니다. 사용자가 서버를 다시 연결하거나 `/mcp`에서 비활성화된 서버를 다시 켤 때 다시 실행합니다. 인프로세스 `type: "sdk"` 서버는 [세션을 시작한 앱이 등록](/docs/ko/mcp#how-connectors-reach-claude-code)하며 세 가지 모두 건너뜁니다.

393

3941. **목록 병합.** 모든 설정 범위의 허용 목록 및 거부 목록 항목이 하나의 허용 목록과 하나의 거부 목록으로 결합됩니다. `allowManagedMcpServersOnly`가 `true`일 때 관리형 허용 목록만 유지됩니다. 거부 목록은 항상 모든 범위에서 병합됩니다. 둘 이상의 관리형 소스가 있을 때 [모든 관리자 소스에서 읽은 키](/docs/ko/managed-settings#keys-read-from-every-admin-source)에서 관리형 범위의 목록을 제공하는 소스를 설명합니다.

3952. **거부 목록 확인.** URL, 명령 또는 이름으로 거부 목록 항목과 일치하는 서버는 차단됩니다. 거부 목록 일치를 무시하는 것은 없습니다.

3963. **허용 목록 확인.** [일부 서버는 이 검사를 건너뜁니다](#servers-that-skip-the-allowlist-check). `allowedMcpServers`가 어디에도 설정되지 않으면 거부 목록을 통과한 모든 서버가 로드됩니다. 설정되면 서버가 일치해야 하는 것은 아래 표에 표시된 유형에 따라 다릅니다.

397

398| 서버 유형 | 일치할 때 허용됨 |

399| :- | :- |

400| 원격 (HTTP 또는 SSE) | `serverUrl` 항목. `serverName` 일치는 허용 목록에 `serverUrl` 항목이 없을 때만 계산됨 |

401| Stdio | `serverCommand` 항목. `serverName` 일치는 허용 목록에 `serverCommand` 항목이 없을 때만 계산됨 |

402

403<h4 id="servers-that-skip-the-allowlist-check">

404 허용 목록 검사를 건너뛰는 서버

405</h4>

406

407[세 가지 검사 모두](#how-a-server-is-evaluated)를 건너뛰는 인프로세스 `type: "sdk"` 서버 외에도 세 그룹의 서버가 허용 목록 검사를 건너뜁니다.

408

409* 조직 자체의 서버: 모든 `managedMcpServers` 항목과 값에 `${VAR}` 확장을 사용하지 않는 모든 `managed-mcp.json` 항목입니다.

410* 기본 제공 서버: Chrome의 Claude, Claude Code가 실행 중인 VS Code 또는 JetBrains IDE에 연결하는 `ide` 서버, CLI 자체가 구성하는 서버입니다.

411* [Claude Tag](/docs/ko/claude-tag) 세션의 Slack 도구: 스레드를 읽고 회신을 게시하는 데 사용하는 서버는 허용 목록 항목 없이 로드됩니다.

412

413명령, 인수, `env`, URL 또는 헤더에서 `${VAR}` 확장을 사용하는 `managed-mcp.json` 서버는 여전히 확인됩니다. Claude Code는 사용자, 플러그인, claude.ai가 추가하는 모든 서버와 사용자가 `--mcp-config`로 전달하는 모든 서버도 확인합니다.

382 414

383<h3 id="example-configuration">415<h3 id="example-configuration">

384 예제 구성416 예제 구성

managed-settings.md +22 −20

Details

149 149

150두 설정 모두 동일한 방식으로 소스의 순위를 지정합니다. 이 섹션에서 반복되는 용어는 다음과 같습니다:150두 설정 모두 동일한 방식으로 소스의 순위를 지정합니다. 이 섹션에서 반복되는 용어는 다음과 같습니다:

151 151

152* **정책 키**: 두 개의 제어 키인 [`wslInheritsWindowsSettings`](/docs/ko/settings-reference#wslinheritswindowssettings)와 [`managedSourcesBehavior`](/docs/ko/settings-reference#managedsourcesbehavior)를 제외한 모든 설정 키입니다. 이 두 키만 포함하는 관리되는 설정 파일이나 MDM 정책은 계산되지 않으며, Claude Code는 다음 소스로 이동합니다.152* **정책 키**: 두 개의 제어 키인 [`wslInheritsWindowsSettings`](/docs/ko/settings-reference#wslinheritswindowssettings)와 [`managedSourcesBehavior`](/docs/ko/settings-reference#managedsourcesbehavior)를 제외한 모든 설정 키입니다. 이 두 키만 포함하는 관리형 설정 파일이나 MDM 정책은 계산되지 않으며, Claude Code는 다음 소스로 이동합니다.

153* **관리 소스**: 아래의 처음 세 소스 중 하나입니다. HKCU 레지스트리는 사용자가 쓸 수 있으므로 관리 소스가 아닙니다.153* **관리 소스**: 아래의 처음 세 소스 중 하나입니다. HKCU 레지스트리는 사용자가 쓸 수 있으므로 관리 소스가 아닙니다.

154 154

155Claude Code는 다음 순서대로 소스를 확인합니다(우선순위가 높은 순서대로):155Claude Code는 다음 순서대로 소스를 확인합니다(우선순위가 높은 순서대로):

156 156

1571. 원격 설정, claude.ai에서 [서버 관리 설정](/docs/ko/server-managed-settings)으로 또는 [Claude 앱 게이트웨이](/docs/ko/claude-apps-gateway)로 제공됩니다. Claude Code는 세션이 [적격 로그인 또는 키](/docs/ko/server-managed-settings#platform-availability)로 Anthropic의 API에 직접 인증하거나 `/login`으로 게이트웨이에 로그인할 때만 이 소스를 가져옵니다. 다른 공급자에서 또는 `ANTHROPIC_BASE_URL`이 Anthropic의 API 이외의 다른 곳을 가리킬 때는 다음 소스에서 시작합니다.1571. 원격 설정, claude.ai에서 [서버 관리 설정](/docs/ko/server-managed-settings)으로 또는 [Claude 앱 게이트웨이](/docs/ko/claude-apps-gateway)로 제공됩니다. Claude Code는 세션이 [적격 로그인 또는 키](/docs/ko/server-managed-settings#platform-availability)로 Anthropic의 API에 직접 인증하거나 `/login`으로 게이트웨이에 로그인할 때만 이 소스를 가져옵니다. 다른 공급자에서 또는 `ANTHROPIC_BASE_URL`이 Anthropic의 API 이외의 다른 곳을 가리킬 때는 다음 소스에서 시작합니다.

1582. MDM 또는 OS 수준 정책: macOS plist 또는 HKLM 레지스트리 키1582. MDM 또는 OS 수준 정책: macOS plist 또는 HKLM 레지스트리 키

1593. 관리되는 설정 파일, `managed-settings.d/*.json` 및 `managed-settings.json`이 함께 병합됨1593. 관리형 설정 파일, `managed-settings.d/*.json` 및 `managed-settings.json`이 함께 병합됨

1604. Windows의 HKCU 레지스트리, WSL에서는 HKLM 레지스트리 또는 Windows 관리형 설정 파일이 [`wslInheritsWindowsSettings`](/docs/ko/settings-reference#wslinheritswindowssettings)를 켜고 HKCU 값도 이를 설정할 때. Claude Code는 [위에 존재하는 관리 문서가 없을 때](#present-admin-documents)와 [호스트 제공 부모 설정](#let-an-embedding-host-add-policy)이 제한적인 키를 제공하지 않을 때만 읽습니다.1604. Windows의 HKCU 레지스트리, WSL에서는 HKLM 레지스트리 또는 Windows 관리형 설정 파일이 [`wslInheritsWindowsSettings`](/docs/ko/settings-reference#wslinheritswindowssettings)를 켜고 HKCU 값도 이를 설정할 때. Claude Code는 [위에 존재하는 관리 문서가 없을 때](#present-admin-documents)와 [호스트 제공 부모 설정](#let-an-embedding-host-add-policy)이 제한적인 키를 제공하지 않을 때만 읽습니다.

161 161

162이 다이어그램은 순위를 보여주며, Claude Code가 두 설정 중 하나에서 처음 세 소스에서 읽는 교차 소스 키의 예를 포함합니다:162이 다이어그램은 순위를 보여주며, Claude Code가 두 설정 중 하나에서 처음 세 소스에서 읽는 교차 소스 키의 예를 포함합니다:

163 163

164<img src="https://mintcdn.com/claude-code/zuWID2B-Rxm8DEC8/images/managed-source-precedence.svg?fit=max&auto=format&n=zuWID2B-Rxm8DEC8&q=85&s=53f6be49f06eff48e01422c8ae1bc2e6" className="dark:hidden" alt="원격 설정에서 상단부터 MDM, 관리 설정 파일, HKCU 레지스트리까지 순위가 지정된 네 개의 관리 설정 소스를 보여주는 다이어그램입니다. 기본적으로 정책 키를 가진 첫 번째 소스가 정책을 제공하고 나머지는 건너뜁니다. managedSourcesBehavior가 merge로 설정되면 정책 키를 가진 모든 관리 소스가 기여하고 키의 종류별로 결합되며 HKCU 레지스트리는 제외됩니다. 측면 패널은 샌드박스 잠금, forceRemoteSettingsRefresh, 변수별 env 병합과 같은 교차 소스 키가 HKCU 레지스트리를 제외하는 모든 관리 소스에서 읽혀짐을 보여줍니다." width="680" height="330" data-path="images/managed-source-precedence.svg" />164<img src="https://mintcdn.com/claude-code/zuWID2B-Rxm8DEC8/images/managed-source-precedence.svg?fit=max&auto=format&n=zuWID2B-Rxm8DEC8&q=85&s=53f6be49f06eff48e01422c8ae1bc2e6" className="dark:hidden" alt="원격 설정에서 상단부터 MDM, 관리형 설정 파일, HKCU 레지스트리까지 순위가 지정된 네 개의 관리형 설정 소스를 보여주는 다이어그램입니다. 기본적으로 정책 키를 가진 첫 번째 소스가 정책을 제공하고 나머지는 건너뜁니다. managedSourcesBehavior가 merge로 설정되면 정책 키를 가진 모든 관리 소스가 기여하고 키의 종류별로 결합되며 HKCU 레지스트리는 제외됩니다. 측면 패널은 샌드박스 잠금, forceRemoteSettingsRefresh, 변수별 env 병합과 같은 교차 소스 키가 HKCU 레지스트리를 제외하는 모든 관리 소스에서 읽혀짐을 보여줍니다." width="680" height="330" data-path="images/managed-source-precedence.svg" />

165 165

166<img src="https://mintcdn.com/claude-code/zuWID2B-Rxm8DEC8/images/managed-source-precedence-dark.svg?fit=max&auto=format&n=zuWID2B-Rxm8DEC8&q=85&s=ae407a9a08a3d680e80cf1a2af845d71" className="hidden dark:block" alt="원격 설정에서 상단부터 MDM, 관리 설정 파일, HKCU 레지스트리까지 순위가 지정된 네 개의 관리 설정 소스를 보여주는 다이어그램입니다. 기본적으로 정책 키를 가진 첫 번째 소스가 정책을 제공하고 나머지는 건너뜁니다. managedSourcesBehavior가 merge로 설정되면 정책 키를 가진 모든 관리 소스가 기여하고 키의 종류별로 결합되며 HKCU 레지스트리는 제외됩니다. 측면 패널은 샌드박스 잠금, forceRemoteSettingsRefresh, 변수별 env 병합과 같은 교차 소스 키가 HKCU 레지스트리를 제외하는 모든 관리 소스에서 읽혀짐을 보여줍니다." width="680" height="330" data-path="images/managed-source-precedence-dark.svg" />166<img src="https://mintcdn.com/claude-code/zuWID2B-Rxm8DEC8/images/managed-source-precedence-dark.svg?fit=max&auto=format&n=zuWID2B-Rxm8DEC8&q=85&s=ae407a9a08a3d680e80cf1a2af845d71" className="hidden dark:block" alt="원격 설정에서 상단부터 MDM, 관리형 설정 파일, HKCU 레지스트리까지 순위가 지정된 네 개의 관리형 설정 소스를 보여주는 다이어그램입니다. 기본적으로 정책 키를 가진 첫 번째 소스가 정책을 제공하고 나머지는 건너뜁니다. managedSourcesBehavior가 merge로 설정되면 정책 키를 가진 모든 관리 소스가 기여하고 키의 종류별로 결합되며 HKCU 레지스트리는 제외됩니다. 측면 패널은 샌드박스 잠금, forceRemoteSettingsRefresh, 변수별 env 병합과 같은 교차 소스 키가 HKCU 레지스트리를 제외하는 모든 관리 소스에서 읽혀짐을 보여줍니다." width="680" height="330" data-path="images/managed-source-precedence-dark.svg" />

167 167

168<h3 id="present-admin-documents">168<h3 id="present-admin-documents">

169 관리 문서가 존재하는 것으로 간주되는 경우169 관리 문서가 존재하는 것으로 간주되는 경우

182 182

183기본 `"first-wins"` 설정에서 Claude Code는 대부분의 키를 [선택한 소스](#how-claude-code-combines-managed-sources)에서만 읽고, 선택한 소스가 해당 키를 설정하지 않은 경우에도 더 낮은 순위의 소스의 값을 무시합니다.183기본 `"first-wins"` 설정에서 Claude Code는 대부분의 키를 [선택한 소스](#how-claude-code-combines-managed-sources)에서만 읽고, 선택한 소스가 해당 키를 설정하지 않은 경우에도 더 낮은 순위의 소스의 값을 무시합니다.

184 184

185몇 가지 키는 다르게 작동합니다. Claude Code는 모든 관리 소스에서 이들을 읽으므로, 선택한 소스가 설정하지 않을 때 더 낮은 순위의 MDM 정책이나 관리 설정 파일이 여전히 이들을 설정할 수 있습니다. Claude Code는 사용자 쓰기 가능한 HKCU 레지스트리를 해당 스캔에서 제외합니다. HKCU가 유일한 소스이고 호스트가 부모 설정을 제공하지 않을 때, HKCU는 선택된 소스처럼 적용됩니다.185몇 가지 키는 다르게 작동합니다. Claude Code는 모든 관리 소스에서 이들을 읽으므로, 선택한 소스가 설정하지 않을 때 더 낮은 순위의 MDM 정책이나 관리형 설정 파일이 여전히 이들을 설정할 수 있습니다. Claude Code는 사용자 쓰기 가능한 HKCU 레지스트리를 해당 스캔에서 제외합니다. HKCU가 유일한 소스이고 호스트가 부모 설정을 제공하지 않을 때, HKCU는 선택된 소스처럼 적용됩니다.

186 186

187교차 소스 키는 다음을 포함합니다:187교차 소스 키는 다음을 포함합니다:

188 188

200* [`useAutoModeDuringPlan`](/docs/ko/settings-reference#useautomodeduringplan), [`syncClaudeAiSkills`](/docs/ko/settings-reference#syncclaudeaiskills), 및 [`syncClaudeAiPlugins`](/docs/ko/settings-reference#syncclaudeaiplugins), 여기서 모든 관리 소스의 `false`가 동작을 끕니다. 개발자의 사용자 또는 로컬 설정의 `false`도 이를 끕니다. 각 키는 거부만 할 수 있습니다.200* [`useAutoModeDuringPlan`](/docs/ko/settings-reference#useautomodeduringplan), [`syncClaudeAiSkills`](/docs/ko/settings-reference#syncclaudeaiskills), 및 [`syncClaudeAiPlugins`](/docs/ko/settings-reference#syncclaudeaiplugins), 여기서 모든 관리 소스의 `false`가 동작을 끕니다. 개발자의 사용자 또는 로컬 설정의 `false`도 이를 끕니다. 각 키는 거부만 할 수 있습니다.

201* [`enableArtifact`](/docs/ko/settings-reference#enableartifact), 여기서 모든 관리 소스의 `false`가 [Artifact 도구](/docs/ko/artifacts)를 끕니다. 개발자의 사용자, 프로젝트 또는 로컬 설정의 `false`도 이를 끕니다. 어떤 소스도 이를 다시 켤 수 없습니다. [어떤 하위 수준 값이 여전히 계산되는지](/docs/ko/settings#exceptions-to-managed-settings-precedence) 참조하세요. Claude Code v2.1.242 이상이 필요합니다.201* [`enableArtifact`](/docs/ko/settings-reference#enableartifact), 여기서 모든 관리 소스의 `false`가 [Artifact 도구](/docs/ko/artifacts)를 끕니다. 개발자의 사용자, 프로젝트 또는 로컬 설정의 `false`도 이를 끕니다. 어떤 소스도 이를 다시 켤 수 없습니다. [어떤 하위 수준 값이 여전히 계산되는지](/docs/ko/settings#exceptions-to-managed-settings-precedence) 참조하세요. Claude Code v2.1.242 이상이 필요합니다.

202* [`maxEffortLevel`](/docs/ko/settings-reference#maxeffortlevel), 여기서 모든 관리 소스의 가장 낮은 상한이 적용됩니다. 개발자가 자신의 설정이나 `--settings`에서 더 낮은 상한을 설정하면 Claude Code가 그것을 적용합니다. 어떤 소스도 상한을 올릴 수 없습니다. Claude Code v2.1.267 이상이 필요합니다.202* [`maxEffortLevel`](/docs/ko/settings-reference#maxeffortlevel), 여기서 모든 관리 소스의 가장 낮은 상한이 적용됩니다. 개발자가 자신의 설정이나 `--settings`에서 더 낮은 상한을 설정하면 Claude Code가 그것을 적용합니다. 어떤 소스도 상한을 올릴 수 없습니다. Claude Code v2.1.267 이상이 필요합니다.

203* `attribution`의 커밋 트레일러 옵트아웃, 또는 더 이상 사용되지 않는 `includeCoAuthoredBy`의 옵트아웃(모든 계층에서)203* `attribution`의 커밋 트레일러 옵트아웃, 또는 deprecated된 `includeCoAuthoredBy`의 옵트아웃(모든 계층에서)

204* [`forceRemoteSettingsRefresh`](/docs/ko/server-managed-settings)204* [`forceRemoteSettingsRefresh`](/docs/ko/server-managed-settings)

205* 관리 소스 전체에서 변수별로 병합된 `env`: 각 변수는 이를 정의하는 가장 높은 우선순위 소스에서 옵니다. 따라서 더 낮은 소스는 더 높은 소스가 설정하지 않은 변수를 채웁니다. 몇 가지 변수는 자신의 규칙을 따릅니다. [관리되는 소스 전체의 키별 예외](/docs/ko/server-managed-settings#per-key-exceptions-across-managed-sources)에서 각각을 나열합니다. Claude Code v2.1.223 이상이 필요합니다. v2.1.223 이전에는 Claude Code가 선택한 소스의 전체 `env` 블록만 적용했습니다.205* 관리 소스 전체에서 변수별로 병합된 `env`: 각 변수는 이를 정의하는 가장 높은 우선순위 소스에서 옵니다. 따라서 더 낮은 소스는 더 높은 소스가 설정하지 않은 변수를 채웁니다. 몇 가지 변수는 자신의 규칙을 따릅니다. [관리되는 소스 전체의 키별 예외](/docs/ko/server-managed-settings#per-key-exceptions-across-managed-sources)에서 각각을 나열합니다. Claude Code v2.1.223 이상이 필요합니다. v2.1.223 이전에는 Claude Code가 선택한 소스의 전체 `env` 블록만 적용했습니다.

206 206

237 도우미 프로그램으로 정책 계산237 도우미 프로그램으로 정책 계산

238</h3>238</h3>

239 239

240[`policyHelper`](/docs/ko/settings-reference#policyhelper)는 MDM 정책이나 관리 설정 파일이 이름을 지정하는 실행 파일이며, Claude Code는 이를 실행하여 시작 시 관리 설정을 계산합니다. 선택한 소스가 하나를 구성하고 도우미가 `managedSettings` 객체를 내보낼 때, 해당 출력은 Claude Code가 읽는 것을 변경합니다:240[`policyHelper`](/docs/ko/settings-reference#policyhelper)는 MDM 정책이나 관리형 설정 파일이 이름을 지정하는 실행 파일이며, Claude Code는 이를 실행하여 시작 시 관리형 설정을 계산합니다. 선택한 소스가 하나를 구성하고 도우미가 `managedSettings` 객체를 내보낼 때, 해당 출력은 Claude Code가 읽는 것을 변경합니다:

241 241

242* **내보낸 `managedSettings` 객체는 세션의 유일한 관리 설정입니다**, [그렇지 않으면 모든 관리 소스에서 읽은 키](#keys-read-from-every-admin-source)를 포함하여, [`forceRemoteSettingsRefresh` 제외(자신의 시작 규칙이 있음)](/docs/ko/settings-reference#forceremotesettingsrefresh)242* **내보낸 `managedSettings` 객체는 세션의 유일한 관리형 설정입니다**, [그렇지 않으면 모든 관리 소스에서 읽은 키](#keys-read-from-every-admin-source)를 포함하여, [`forceRemoteSettingsRefresh` 제외(자신의 시작 규칙이 있음)](/docs/ko/settings-reference#forceremotesettingsrefresh)

243 243

244도우미 실행이 실패하는 경우와 실패할 때 Claude Code가 수행하는 작업은 [도우미 실패](/docs/ko/settings-reference#helper-failures)를 참조하세요.244도우미 실행이 실패하는 경우와 실패할 때 Claude Code가 수행하는 작업은 [도우미 실패](/docs/ko/settings-reference#helper-failures)를 참조하세요.

245 245

253 임베딩 호스트가 정책을 추가하도록 허용253 임베딩 호스트가 정책을 추가하도록 허용

254</h3>254</h3>

255 255

256다른 애플리케이션(예: Claude Desktop, IDE 확장 또는 Agent SDK 앱)이 Claude Code를 시작할 때, 해당 호스트는 SDK `managedSettings` 옵션을 통해 자신의 관리 설정을 전달할 수 있습니다. Claude Code는 이를 부모 설정이라고 부릅니다.256다른 애플리케이션(예: Claude Desktop, IDE 확장 또는 Agent SDK 앱)이 Claude Code를 시작할 때, 해당 호스트는 SDK `managedSettings` 옵션을 통해 자신의 관리형 설정을 전달할 수 있습니다. Claude Code는 이를 부모 설정이라고 부릅니다.

257 257

258기본적으로 Claude Code는 관리 소스가 존재할 때마다 부모 설정을 무시합니다: 서버 관리 설정, MDM 또는 OS 수준 정책, 또는 관리 설정 파일.258기본적으로 Claude Code는 관리 소스가 존재할 때마다 부모 설정을 무시합니다: 서버 관리 설정, MDM 또는 OS 수준 정책, 또는 관리형 설정 파일.

259 259

260부모 설정을 관리 소스와 함께 병합하도록 Claude Code를 하려면 가장 높은 우선순위의 관리 소스에서 [`parentSettingsBehavior`](/docs/ko/settings-reference#parentsettingsbehavior)를 `"merge"`로 설정합니다. Claude Code는 해당 소스에서만 키를 읽습니다.260부모 설정을 관리 소스와 함께 병합하도록 Claude Code를 하려면 가장 높은 우선순위의 관리 소스에서 [`parentSettingsBehavior`](/docs/ko/settings-reference#parentsettingsbehavior)를 `"merge"`로 설정합니다. Claude Code는 해당 소스에서만 키를 읽습니다.

261 261

265 265

266Claude Code는 또한 부모 제공 값에 이러한 확인을 적용합니다:266Claude Code는 또한 부모 제공 값에 이러한 확인을 적용합니다:

267 267

268* 모든 관리 소스가 `allowManagedPermissionRulesOnly`를 설정할 때, Claude Code는 더 높은 우선순위 소스가 키를 설정하지 않은 경우에도 읽을 때 [부모 제공](/docs/ko/claude-apps-gateway#restrict-parent-settings) 권한 허용 규칙과 `additionalDirectories`를 삭제합니다. 키의 효과는 Claude Code가 적용하는 관리 설정이나 병합하도록 선택한 부모 설정에서 나옵니다.268* 모든 관리 소스가 `allowManagedPermissionRulesOnly`를 설정할 때, Claude Code는 더 높은 우선순위 소스가 키를 설정하지 않은 경우에도 읽을 때 [부모 제공](/docs/ko/claude-apps-gateway#restrict-parent-settings) 권한 허용 규칙과 `additionalDirectories`를 삭제합니다. 키의 효과는 Claude Code가 적용하는 관리형 설정이나 병합하도록 선택한 부모 설정에서 나옵니다.

269* Claude Code는 적용하는 관리 설정의 `forceLoginOrgUUID` 또는 `allowedMcpServers` 값을 적용하고 부모 제공 값을 차단합니다. MCP 허용 목록 잠금 외부에서 Claude Code가 적용하지 않는 더 낮은 관리 소스의 값은 적용되지도 차단되지도 않습니다.269* Claude Code는 적용하는 관리형 설정의 `forceLoginOrgUUID` 또는 `allowedMcpServers` 값을 적용하고 부모 제공 값을 차단합니다. MCP 허용 목록 잠금 외부에서 Claude Code가 적용하지 않는 더 낮은 관리 소스의 값은 적용되지도 차단되지도 않습니다.

270 270

271 Claude Code v2.1.273 이상에서 `allowManagedMcpServersOnly`가 켜져 있는 동안 하나를 설정하는 가장 높은 순위의 관리 소스의 `allowedMcpServers` 목록이 적용되고 부모의 것을 차단합니다([교차 소스 키](#keys-read-from-every-admin-source)로). 부모의 목록은 관리 소스가 하나를 설정하지 않을 때만 적용됩니다. [`managedSourcesBehavior`](/docs/ko/settings-reference#managedsourcesbehavior) 항목은 `"merge"` 아래에서 어떤 소스가 각 키를 제공하는지 설명합니다. v2.1.223 이전에는 모든 관리 소스의 값이 부모의 것을 차단했습니다.271 Claude Code v2.1.273 이상에서 `allowManagedMcpServersOnly`가 켜져 있는 동안 하나를 설정하는 가장 높은 순위의 관리 소스의 `allowedMcpServers` 목록이 적용되고 부모의 것을 차단합니다([교차 소스 키](#keys-read-from-every-admin-source)로). 부모의 목록은 관리 소스가 하나를 설정하지 않을 때만 적용됩니다. [`managedSourcesBehavior`](/docs/ko/settings-reference#managedsourcesbehavior) 항목은 `"merge"` 아래에서 어떤 소스가 각 키를 제공하는지 설명합니다. v2.1.223 이전에는 모든 관리 소스의 값이 부모의 것을 차단했습니다.

272* `availableModels`의 경우 Claude Code는 적용하는 관리 설정의 값을 적용하고 부모 제공 목록을 차단합니다.272* `availableModels`의 경우 Claude Code는 적용하는 관리형 설정의 값을 적용하고 부모 제공 목록을 차단합니다.

273* `strictKnownMarketplaces`의 경우 Claude Code는 마찬가지로 적용하는 관리 설정의 목록을 적용하고 부모 제공 목록을 차단합니다. 부모의 목록은 적용된 관리 소스가 하나를 설정하지 않을 때만 적용됩니다. Claude Code v2.1.282 이상이 필요합니다.273* `strictKnownMarketplaces`의 경우 Claude Code는 마찬가지로 적용하는 관리형 설정의 목록을 적용하고 부모 제공 목록을 차단합니다. 부모의 목록은 적용된 관리 소스가 하나를 설정하지 않을 때만 적용됩니다. Claude Code v2.1.282 이상이 필요합니다.

274* `allowedProviders`의 경우 [선택된 관리 소스](#which-managed-source-claude-code-uses)의 목록이 부모 제공 목록을 차단하며, [`managedSourcesBehavior`](/docs/ko/settings-reference#managedsourcesbehavior) `"merge"` 옵트인에서는 모든 관리 소스의 목록이 이를 차단합니다. Claude Code v2.1.285 이상이 필요합니다.

274* 부모 제공 `blockedMarketplaces`는 관리 소스가 설정하는 모든 거부 목록에 추가로 적용됩니다. Claude Code v2.1.282 이상이 필요합니다.275* 부모 제공 `blockedMarketplaces`는 관리 소스가 설정하는 모든 거부 목록에 추가로 적용됩니다. Claude Code v2.1.282 이상이 필요합니다.

275 276

276<h4 id="keep-cowork-folder-access-when-only-managed-rules-apply">277<h4 id="keep-cowork-folder-access-when-only-managed-rules-apply">

279 280

280Claude Desktop 앱의 [Cowork](https://claude.com/docs/cowork/overview)는 Claude Code에서 세션을 실행하고 각 세션에 세션을 시작할 때 제공하는 허용 규칙을 통해 사용자가 연결하는 폴더와 같은 작업 폴더에 대한 액세스 권한을 부여합니다. 관리 정책이 [`allowManagedPermissionRulesOnly`](/docs/ko/settings-reference#allowmanagedpermissionrulesonly)를 설정할 때, Claude Code는 관리 정책의 허용 규칙만 유지합니다: 호스트가 부모 설정으로, `--allowedTools`로, 또는 설정 파일에서 제공하는 허용 규칙을 삭제하므로 해당 폴더에 대한 쓰기는 사전 승인을 잃습니다. 편집 전에 묻는 Cowork 세션에서 Cowork는 프롬프트를 표시할 수 없으며, Claude는 경로가 보호된 위치 또는 연결된 폴더 외부의 경로로 확인되기 때문에 각 쓰기를 차단된 것으로 보고합니다.281Claude Desktop 앱의 [Cowork](https://claude.com/docs/cowork/overview)는 Claude Code에서 세션을 실행하고 각 세션에 세션을 시작할 때 제공하는 허용 규칙을 통해 사용자가 연결하는 폴더와 같은 작업 폴더에 대한 액세스 권한을 부여합니다. 관리 정책이 [`allowManagedPermissionRulesOnly`](/docs/ko/settings-reference#allowmanagedpermissionrulesonly)를 설정할 때, Claude Code는 관리 정책의 허용 규칙만 유지합니다: 호스트가 부모 설정으로, `--allowedTools`로, 또는 설정 파일에서 제공하는 허용 규칙을 삭제하므로 해당 폴더에 대한 쓰기는 사전 승인을 잃습니다. 편집 전에 묻는 Cowork 세션에서 Cowork는 프롬프트를 표시할 수 없으며, Claude는 경로가 보호된 위치 또는 연결된 폴더 외부의 경로로 확인되기 때문에 각 쓰기를 차단된 것으로 보고합니다.

281 282

282쓰기를 복원하려면 Claude Code가 해당 머신에서 [선택](#precedence-within-the-managed-tier)하는 관리 소스에 해당 폴더에 대한 허용 규칙을 추가합니다: MDM 관리 플릿에서 이는 별도의 관리 설정 파일이 아닌 MDM 정책입니다. 이 예는 파일 형식을 사용하며 MDM 정책은 동일한 키를 취합니다. `allowManagedPermissionRulesOnly`를 설정한 상태로 유지하고 각 사용자의 홈 디렉토리에서 `CoworkProjects` 폴더 아래의 편집을 허용합니다. 사용자가 연결하는 폴더로 경로를 바꾸세요:283쓰기를 복원하려면 Claude Code가 해당 머신에서 [선택](#precedence-within-the-managed-tier)하는 관리 소스에 해당 폴더에 대한 허용 규칙을 추가합니다: MDM 관리 플릿에서 이는 별도의 관리형 설정 파일이 아닌 MDM 정책입니다. 이 예는 파일 형식을 사용하며 MDM 정책은 동일한 키를 취합니다. `allowManagedPermissionRulesOnly`를 설정한 상태로 유지하고 각 사용자의 홈 디렉터리에서 `CoworkProjects` 폴더 아래의 편집을 허용합니다. 사용자가 연결하는 폴더로 경로를 바꾸세요:

283 284

284```json managed-settings.json theme={null}285```json managed-settings.json theme={null}

285{286{

301개발자의 자신의 설정 파일, `--settings` 값, 프로젝트 파일은 관리 값을 절대 재정의하지 않습니다. [예외](/docs/ko/settings#exceptions-to-managed-settings-precedence)는 더 엄격한 하위 수준 값만 계산되도록 합니다. 이 경우는 해당 규칙 외부에 있습니다:302개발자의 자신의 설정 파일, `--settings` 값, 프로젝트 파일은 관리 값을 절대 재정의하지 않습니다. [예외](/docs/ko/settings#exceptions-to-managed-settings-precedence)는 더 엄격한 하위 수준 값만 계산되도록 합니다. 이 경우는 해당 규칙 외부에 있습니다:

302 303

303* **세션의 모델**: 관리 `model`은 잠금이 아닌 기본값입니다. `--model` 및 `ANTHROPIC_MODEL`은 여전히 해당 세션의 모델을 선택하므로 [`availableModels`](/docs/ko/settings-reference#availablemodels)를 배포하여 선택을 제한합니다.304* **세션의 모델**: 관리 `model`은 잠금이 아닌 기본값입니다. `--model` 및 `ANTHROPIC_MODEL`은 여전히 해당 세션의 모델을 선택하므로 [`availableModels`](/docs/ko/settings-reference#availablemodels)를 배포하여 선택을 제한합니다.

305* **세션의 자동 압축 윈도우**: 관리 [`autoCompactWindow`](/docs/ko/settings-reference#autocompactwindow)도 기본값입니다. `--autocompact` 플래그와 `CLAUDE_CODE_AUTO_COMPACT_WINDOW` 변수는 여전히 해당 세션의 [자동 압축 윈도우](/docs/ko/model-config#set-the-auto-compact-window)를 설정합니다.

304* **로컬 관리자 권한**: 머신의 관리자인 개발자는 관리 소스 자체를 편집할 수 있으므로 MDM 도구는 프로필이나 파일을 일정에 따라 다시 배포할 수 있으며 HKLM 레지스트리와 macOS 관리 기본 설정 도메인이 존재합니다.306* **로컬 관리자 권한**: 머신의 관리자인 개발자는 관리 소스 자체를 편집할 수 있으므로 MDM 도구는 프로필이나 파일을 일정에 따라 다시 배포할 수 있으며 HKLM 레지스트리와 macOS 관리 기본 설정 도메인이 존재합니다.

305* **서버 관리 캐시**: 서버 관리 설정은 Anthropic의 서버에서 오며, 로컬 캐시에 대한 편집은 [다음 성공적인 가져오기까지만 지속됩니다](/docs/ko/server-managed-settings#security-considerations).307* **서버 관리 캐시**: 서버 관리 설정은 Anthropic의 서버에서 오며, 로컬 캐시에 대한 편집은 [다음 성공적인 가져오기까지만 지속됩니다](/docs/ko/server-managed-settings#security-considerations).

306* **다른 도구**: 관리 설정은 Claude Code만 바인딩합니다. 다른 도구에서 API를 호출하는 개발자는 이들 아래에 있지 않습니다.308* **다른 도구**: 관리형 설정은 Claude Code만 바인딩합니다. 다른 도구에서 API를 호출하는 개발자는 이들 아래에 있지 않습니다.

307 309

308<span id="verify-enforcement" />310<span id="verify-enforcement" />

309 311

313 정책이 적용 중인지 확인315 정책이 적용 중인지 확인

314</h2>316</h2>

315 317

316개발자가 정책이 적용되지 않는다고 보고하거나, 롤아웃이 완료되었는지 확인한 후 전체 시스템에 배포하려는 경우가 있습니다. 해당 머신의 두 가지 명령어로 이를 확인할 수 있습니다. `/status`는 Claude Code가 선택한 관리형 소스를 표시하고, `claude doctor`는 삭제된 항목을 나열합니다.318개발자가 정책이 적용되지 않는다고 보고하거나, 롤아웃이 완료되었는지 확인한 후 전체 시스템에 배포하려는 경우가 있습니다. 해당 머신의 두 가지 명령으로 이를 확인할 수 있습니다. `/status`는 Claude Code가 선택한 관리형 소스를 표시하고, `claude doctor`는 삭제된 항목을 나열합니다.

317 319

318<h3 id="read-the-source-in-/status">320<h3 id="read-the-source-in-/status">

319 /status에서 소스 읽기321 /status에서 소스 읽기

377 폐쇄 상태로 실패하는 키379 폐쇄 상태로 실패하는 키

378</h4>380</h4>

379 381

380관리형 소스가 단일 제한적 값을 가진 최상위 키(예: `allowManagedPermissionRulesOnly`, `disableAutoMode` 또는 `skipDangerousModePermissionPrompt`)를 Claude Code가 읽을 수 없는 것으로 설정하면, 키는 수정될 때까지 해당 값으로 읽힙니다. 보고서는 키가 `was present but invalid`라고 말하고 Claude Code가 이를 처리하는 값의 이름을 지정합니다. `sandbox` 내부의 키는 [Invalid values inside `sandbox`](#invalid-values-inside-sandbox)를 참조합니다.382관리형 소스가 단일 제한적 값을 가진 최상위 키(예: `allowManagedPermissionRulesOnly`, `disableAutoMode` 또는 `skipDangerousModePermissionPrompt`)를 Claude Code가 읽을 수 없는 것으로 설정하면, 키는 수정될 때까지 해당 값으로 읽힙니다. 보고서는 키가 `was present but invalid`라고 말하고 Claude Code가 이를 처리하는 값의 이름을 지정합니다. `sandbox` 내부의 키는 [`sandbox` 내의 유효하지 않은 값](#invalid-values-inside-sandbox)을 참조합니다.

381 383

382이 경우들은 폐쇄 상태로 실패하지 않습니다:384이 경우들은 폐쇄 상태로 실패하지 않습니다:

383 385

398 400

399| 필드 | 존재하지만 유효하지 않을 때의 동작 |401| 필드 | 존재하지만 유효하지 않을 때의 동작 |

400| :- | :- |402| :- | :- |

401| `allowedMcpServers` | 값이 수정될 때까지 빈 허용 목록으로 적용되므로, 사용자가 추가하는 MCP 서버는 허용되지 않습니다. 조직이 [`managedMcpServers`](/docs/ko/settings-reference#managedmcpservers)를 통해 전달하는 서버는 여전히 로드되고, `managed-mcp.json` 서버는 [서버 평가 방법](/docs/ko/managed-mcp#how-a-server-is-evaluated)에 따라 로드됩니다. 개별 유효하지 않은 항목은 제거되고 유효한 부분 집합이 적용됩니다. |403| `allowedMcpServers` | 값이 수정될 때까지 빈 허용 목록으로 적용되므로, 사용자가 추가하는 MCP 서버는 허용되지 않습니다. 조직이 [`managedMcpServers`](/docs/ko/settings-reference#managedmcpservers)를 통해 전달하는 서버는 여전히 로드되고, `managed-mcp.json` 서버는 [허용 목록 검사를 건너뛰는 서버](/docs/ko/managed-mcp#servers-that-skip-the-allowlist-check)에 따라 로드됩니다. 개별 유효하지 않은 항목은 제거되고 유효한 부분 집합이 적용됩니다. |

402| [`allowedProviders`](/docs/ko/settings-reference#allowedproviders) | 값이 수정될 때까지 빈 허용 목록으로 적용되므로, 모든 API 제공자가 거부되고 Claude Code는 머신에서 시작되지 않습니다. 개별 항목만 알려진 제공자 이름이 아니면, Claude Code는 해당 항목을 삭제하고 보고하며 나머지를 적용합니다. |404| [`allowedProviders`](/docs/ko/settings-reference#allowedproviders) | 값이 수정될 때까지 빈 허용 목록으로 적용되므로, 모든 API 제공자가 거부되고 Claude Code는 머신에서 시작되지 않습니다. 개별 항목만 알려진 제공자 이름이 아니면, Claude Code는 해당 항목을 삭제하고 보고하며 나머지를 적용합니다. |

403| `allowedHttpHookUrls` | Claude Code는 값을 수정할 때까지 빈 관리형 [허용 목록](/docs/ko/settings-reference#allowedhttphookurls)을 적용하므로, HTTP 훅은 다른 설정 파일이 해당 URL을 나열하는 경우에만 실행됩니다. 개별 항목만 유효하지 않으면, Claude Code는 해당 항목을 제거하고 나머지를 적용합니다. |405| `allowedHttpHookUrls` | Claude Code는 값을 수정할 때까지 빈 관리형 [허용 목록](/docs/ko/settings-reference#allowedhttphookurls)을 적용하므로, HTTP 훅은 다른 설정 파일이 해당 URL을 나열하는 경우에만 실행됩니다. 개별 항목만 유효하지 않으면, Claude Code는 해당 항목을 제거하고 나머지를 적용합니다. |

404| `httpHookAllowedEnvVars` | Claude Code는 값을 수정할 때까지 빈 관리형 [허용 목록](/docs/ko/settings-reference#httphookallowedenvvars)을 적용하므로, 헤더 변수는 다른 설정 파일이 이름을 지정하는 경우에만 보간됩니다. 개별 항목만 유효하지 않으면, Claude Code는 해당 항목을 제거하고 나머지를 적용합니다. |406| `httpHookAllowedEnvVars` | Claude Code는 값을 수정할 때까지 빈 관리형 [허용 목록](/docs/ko/settings-reference#httphookallowedenvvars)을 적용하므로, 헤더 변수는 다른 설정 파일이 이름을 지정하는 경우에만 보간됩니다. 개별 항목만 유효하지 않으면, Claude Code는 해당 항목을 제거하고 나머지를 적용합니다. |

414| `blockedMarketplaces` | 개별 유효하지 않은 항목은 제거되고 유효한 부분 집합이 적용됩니다. 구문 분석되지만 절대 일치할 수 없는 항목(예: 컴파일되지 않는 `hostPattern` 정규식)은 경고와 함께 유지됩니다. 값이 수정될 때까지 아무것도 차단하지 않지만, [마켓플레이스 제한](/docs/ko/plugins/org#restrict-what-users-can-install)은 활성 상태로 유지됩니다. 완전히 유효하지 않은 값은 경고와 함께 삭제됩니다. 모든 마켓플레이스를 차단하면 정책이 이름을 지정하지 않은 소스를 차단하기 때문입니다. |416| `blockedMarketplaces` | 개별 유효하지 않은 항목은 제거되고 유효한 부분 집합이 적용됩니다. 구문 분석되지만 절대 일치할 수 없는 항목(예: 컴파일되지 않는 `hostPattern` 정규식)은 경고와 함께 유지됩니다. 값이 수정될 때까지 아무것도 차단하지 않지만, [마켓플레이스 제한](/docs/ko/plugins/org#restrict-what-users-can-install)은 활성 상태로 유지됩니다. 완전히 유효하지 않은 값은 경고와 함께 삭제됩니다. 모든 마켓플레이스를 차단하면 정책이 이름을 지정하지 않은 소스를 차단하기 때문입니다. |

415| `sandbox` | 블록 내의 한 값이 유효하지 않으면, Claude Code는 전체 블록을 삭제하지 않습니다. 각 종류의 유효하지 않은 필드에 대해 어떤 일이 발생하는지는 [`sandbox` 내의 유효하지 않은 값](#invalid-values-inside-sandbox)을 참조합니다. |417| `sandbox` | 블록 내의 한 값이 유효하지 않으면, Claude Code는 전체 블록을 삭제하지 않습니다. 각 종류의 유효하지 않은 필드에 대해 어떤 일이 발생하는지는 [`sandbox` 내의 유효하지 않은 값](#invalid-values-inside-sandbox)을 참조합니다. |

416| `sandbox.credentials` | 복구 가능한 유효하지 않은 항목은 경고와 함께 `mode: "deny"`로 저하되고, 복구 불가능한 항목은 제거되며, 유효한 항목은 계속 적용됩니다. [관리형 설정의 유효하지 않은 자격 증명 항목](/docs/ko/settings-reference#invalid-credential-entries-in-managed-settings) 참조 |418| `sandbox.credentials` | 복구 가능한 유효하지 않은 항목은 경고와 함께 `mode: "deny"`로 저하되고, 복구 불가능한 항목은 제거되며, 유효한 항목은 계속 적용됩니다. [관리형 설정의 유효하지 않은 자격 증명 항목](/docs/ko/settings-reference#invalid-credential-entries-in-managed-settings) 참조 |

417| `strictPluginOnlyCustomization` | 값이 부울도 배열도 아닐 때 `true`로 처리되어 네 가지 표면을 모두 잠급니다. 이 버전이 표면으로 인식하지 않는 배열 항목은 아무것도 잠그지 않습니다. 상태 알림은 이러한 항목을 계산하므로 오타를 확인할 수 있습니다. |419| `strictPluginOnlyCustomization` | 값이 부울도 배열도 아닐 때 `true`로 처리되어 네 가지 사용 환경을 모두 잠급니다. 이 버전이 사용 환경으로 인식하지 않는 배열 항목은 아무것도 잠그지 않습니다. 상태 알림은 이러한 항목을 계산하므로 오타를 확인할 수 있습니다. |

419 421

420`allowedHttpHookUrls` 및 `httpHookAllowedEnvVars`는 설정 파일 전체에서 병합되므로, 사용자, 프로젝트 또는 로컬 설정의 항목은 관리형 목록이 비어 있는 동안에도 계속 적용됩니다.422`allowedHttpHookUrls` 및 `httpHookAllowedEnvVars`는 설정 파일 전체에서 병합되므로, 사용자, 프로젝트 또는 로컬 설정의 항목은 관리형 목록이 비어 있는 동안에도 계속 적용됩니다.

model-config.md +2 −1

Details

285* **[자동 모델 폴백](#automatic-model-fallback)**: 대상이 제외된 폴백은 실행되지 않으므로, 플래그된 요청은 거부로 끝납니다285* **[자동 모델 폴백](#automatic-model-fallback)**: 대상이 제외된 폴백은 실행되지 않으므로, 플래그된 요청은 거부로 끝납니다

286* **[자동 모드 분류기](/docs/ko/permission-modes#eliminate-prompts-with-auto-mode)**: 분류기의 Claude Sonnet 5 기본값은 허용 목록이 Sonnet 5를 허용할 때만 적용됩니다. 제외될 때, 분류기는 허용 목록이 이미 관리하는 세션의 모델에서 실행되거나, 세션이 [Fable 모델](#work-with-fable)에서 실행될 때 Opus 모델에서 실행됩니다. Anthropic API 이외의 제공자에서, 해당 Opus 폴백은 허용 목록을 참조하지 않고 `ANTHROPIC_DEFAULT_OPUS_MODEL`에 설정한 모델에서, 설정하지 않은 경우 Opus 5에서 실행됩니다. Claude Code v2.1.210 이상 필요286* **[자동 모드 분류기](/docs/ko/permission-modes#eliminate-prompts-with-auto-mode)**: 분류기의 Claude Sonnet 5 기본값은 허용 목록이 Sonnet 5를 허용할 때만 적용됩니다. 제외될 때, 분류기는 허용 목록이 이미 관리하는 세션의 모델에서 실행되거나, 세션이 [Fable 모델](#work-with-fable)에서 실행될 때 Opus 모델에서 실행됩니다. Anthropic API 이외의 제공자에서, 해당 Opus 폴백은 허용 목록을 참조하지 않고 `ANTHROPIC_DEFAULT_OPUS_MODEL`에 설정한 모델에서, 설정하지 않은 경우 Opus 5에서 실행됩니다. Claude Code v2.1.210 이상 필요

287* **[빠른 모드](/docs/ko/fast-mode)**: 세션이 이후에 실행될 모델이 허용 목록 외부에 있을 때 빠른 모드 활성화가 거부됩니다287* **[빠른 모드](/docs/ko/fast-mode)**: 세션이 이후에 실행될 모델이 허용 목록 외부에 있을 때 빠른 모드 활성화가 거부됩니다

288* **Amazon Bedrock 및 Google Cloud의 Agent Platform의 가용성 폴백**: 세션 도중 계정이 모델에 대한 액세스 권한을 잃으면, 다른 모델로 전환할 때 제외된 모델을 건너뜁니다. [Amazon Bedrock](/docs/ko/amazon-bedrock#when-your-organization-enforces-a-model-allowlist) 및 [Google Cloud의 Agent Platform](/docs/ko/google-vertex-ai#when-your-organization-enforces-a-model-allowlist)의 시작 시 모델 확인은 관리형 설정이 [`enforceAvailableModels`](#enforce-the-allowlist-for-the-default-model)도 설정할 때만 제외된 모델을 건너뜁니다

288 289

289```json theme={null}290```json theme={null}

290{291{

766| :- | :- |767| :- | :- |

769| 환경 변수를 통해 비활성화 | [`MAX_THINKING_TOKENS=0`](/docs/ko/env-vars)을 설정하여 Opus 5.5, Sonnet 5.5 및 Fable 모델을 제외한 Anthropic API에서 생각을 끕니다. [제3자 제공자](/docs/ko/third-party-integrations)에서, Claude Code는 `thinking` 매개변수를 생략하고, 적응형 추론 모델은 여전히 생각할 수 있습니다. 다른 값은 [고정 생각 예산](#adaptive-reasoning-and-fixed-thinking-budgets)에만 적용됩니다. |770| 환경 변수를 통해 비활성화 | [`MAX_THINKING_TOKENS=0`](/docs/ko/env-vars)을 설정하면 Opus 5.5, Sonnet 5.5 및 Fable 모델을 제외하고 Anthropic API에서 사고가 꺼집니다. [서드파티 제공자](/docs/ko/third-party-integrations)에서는 Claude Code가 대신 `thinking` 매개변수를 생략하며, 적응형 추론 모델은 여전히 사고할 수 있습니다 |

770 771

771Opus 5.5, Sonnet 5.5 또는 Fable 모델에서 생각을 끌 수 없습니다. 세션 토글 및 `/config` 행은 스위치를 제공하는 대신 이 모델들에 대해 `Thinking can't be turned off`를 표시하고, 저장된 `alwaysThinkingEnabled: false` 또는 `MAX_THINKING_TOKENS=0`은 여기에 영향을 주지 않습니다. 이 모델들에서, 모델은 노력 수준에 따라 각 단계에서 얼마나 생각할지 결정합니다. 저장된 설정은 이를 허용하는 모델로 전환할 때 다시 적용됩니다.772Opus 5.5, Sonnet 5.5 또는 Fable 모델에서 생각을 끌 수 없습니다. 세션 토글 및 `/config` 행은 스위치를 제공하는 대신 이 모델들에 대해 `Thinking can't be turned off`를 표시하고, 저장된 `alwaysThinkingEnabled: false` 또는 `MAX_THINKING_TOKENS=0`은 여기에 영향을 주지 않습니다. 이 모델들에서, 모델은 노력 수준에 따라 각 단계에서 얼마나 생각할지 결정합니다. 저장된 설정은 이를 허용하는 모델로 전환할 때 다시 적용됩니다.

772 773

monitoring-usage.md +259 −206

Details

305* Read, Edit, Write, Bash, WebFetch, WebSearch 및 MCP 도구 이외의 도구에 대한 호출305* Read, Edit, Write, Bash, WebFetch, WebSearch 및 MCP 도구 이외의 도구에 대한 호출

306* 이미지, PDF 또는 콘텐츠가 변경되지 않은 파일의 재읽기와 같이 파일 텍스트 이외의 것을 반환하는 Read306* 이미지, PDF 또는 콘텐츠가 변경되지 않은 파일의 재읽기와 같이 파일 텍스트 이외의 것을 반환하는 Read

307* `OTEL_LOG_TOOL_DETAILS=1`도 설정하지 않으면 Edit 또는 Write 호출307* `OTEL_LOG_TOOL_DETAILS=1`도 설정하지 않으면 Edit 또는 Write 호출

308* Claude Code가 [즉시 대기열에 있는 메시지를 보내기](/docs/ko/interactive-mode#when-claude-code-sends-what-you-queued) 위해 호출을 실행하는 동안 턴을 중단했기 때문에 백그라운드로 이동한 WebFetch 또는 WebSearch 호출. Claude는 도구 범위가 끝난 후 해당 결과를 나중에 받습니다.308* 대기 중인 메시지가 Claude에 전달될 수 있도록 Claude Code가 실행 중에 백그라운드로 옮긴 WebFetch 또는 WebSearch 호출. 나중에 도착하는 결과도 기록되지 않습니다. Claude Code가 호출을 옮기는 시점은 터미널의 경우 [Claude Code가 대기열에 넣은 항목을 보내는 시점](/docs/ko/interactive-mode#when-claude-code-sends-what-you-queued)을, Agent SDK 세션의 경우 [`priority` 필드](/docs/ko/agent-sdk/typescript#sdkusermessage)를 참조하세요

309 309

310이벤트는 각각 콘텐츠 제한(기본값 60KB)에서 잘린 이러한 속성을 전달합니다. `Gated by`는 `OTEL_LOG_TOOL_CONTENT=1` 위에 속성이 필요한 변수의 이름을 지정하고, Edit 및 Write의 경우 해당 변수는 속성이 아닌 이벤트 자체를 게이트합니다.310이벤트는 각각 콘텐츠 제한(기본값 60KB)에서 잘린 이러한 속성을 전달합니다. `Gated by`는 `OTEL_LOG_TOOL_CONTENT=1` 위에 속성이 필요한 변수의 이름을 지정하고, Edit 및 Write의 경우 해당 변수는 속성이 아닌 이벤트 자체를 게이트합니다.

311 311

358 358

359<span id="new-context-gates" />359<span id="new-context-gates" />

360 360

361**상세 베타 추적의 콘텐츠 속성**

362

361<Note>363<Note>

362 `new_context`, `system_prompt_preview`, `user_system_prompt`, `tool_input` 및 `response.model_output`과 같은 추가 콘텐츠 포함 속성은 상세 베타 추적이 활성화되었을 때만 내보내집니다. 이들은 안정적인 범위 스키마의 일부가 아닙니다.364 `new_context`, `system_reminders`, `system_prompt_preview`, `user_system_prompt`, `tool_input` 및 `response.model_output`과 같은 추가 콘텐츠 포함 속성은 상세 베타 추적이 활성화되었을 때만 내보내집니다. 이들은 안정적인 범위 스키마의 일부가 아닙니다.

365</Note>

363 366

364 `new_context`의 게이트는 이를 전달하는 범위에 따라 다르며, 각 복사본은 콘텐츠 제한(기본값 60KB)에서 잘립니다. `claude_code.tool` 범위에서 도구에 관계없이 해당 도구 호출의 결과를 전달하며 `OTEL_LOG_TOOL_CONTENT=1`이 필요합니다. `claude_code.interaction` 범위에서 사용자 프롬프트를 전달하고, `claude_code.llm_request` 범위에서 해당 요청의 새 사용자 메시지 및 도구 결과를 전달합니다. 둘 다 `OTEL_LOG_USER_PROMPTS=1`이 필요합니다.367이러한 속성은 아래 범위에 나타나며, `Gated by`는 상세 베타 추적 외에 속성에 필요한 변수의 이름을 지정합니다. 콘텐츠 제한(기본값 60KB)보다 긴 값은 잘립니다.

365 368

366 `user_system_prompt`는 추가로 `OTEL_LOG_USER_PROMPTS=1`이 필요합니다. `systemPrompt` SDK 옵션 또는 `--system-prompt` 및 `--append-system-prompt` 플래그를 통해 제공하는 시스템 프롬프트 텍스트만 전달하며, 콘텐츠 제한(기본값 60KB)에서 잘리고, 요청당이 아닌 세션당 한 번 내보내집니다.369| 속성 | 범위 | 설명 | 게이트 |

367</Note>370| - | - | - | - |

379

380`OTEL_LOG_USER_PROMPTS=1`을 설정한 상세 베타 추적에서 Claude Code는 콘텐츠 제한에서 잘린 전체 시스템 프롬프트를 전달하는 `claude_code.system_prompt` 이벤트도 내보냅니다. 이 이벤트는 세션이 각각의 고유한 시스템 프롬프트를 처음 보낼 때 도착하며, 압축 후에 다시 도착합니다.

368 381

369<h3 id="dynamic-headers">382<h3 id="dynamic-headers">

370 동적 헤더383 동적 헤더

584| `OTEL_RESOURCE_ATTRIBUTES`의 키 | 설정한 사용자 정의 속성, 예: `department` 또는 `team.id`. [다중 팀 조직 지원](#multi-team-organization-support) 참조 | `OTEL_METRICS_INCLUDE_RESOURCE_ATTRIBUTES` (기본값: true) |597| `OTEL_RESOURCE_ATTRIBUTES`의 키 | 설정한 사용자 정의 속성, 예: `department` 또는 `team.id`. [다중 팀 조직 지원](#multi-team-organization-support) 참조 | `OTEL_METRICS_INCLUDE_RESOURCE_ATTRIBUTES` (기본값: true) |

585| `vcs.repository.url.full`, `vcs.owner.name`, `vcs.repository.name`, `vcs.provider.name` | 세션 저장소의 ID, `origin` 원격에서 파생됨. [저장소 속성](#repository-attributes) 참조 | `OTEL_METRICS_INCLUDE_REPOSITORY` (기본값: false). Claude Code v2.1.269 이상 필요 |598| `vcs.repository.url.full`, `vcs.owner.name`, `vcs.repository.name`, `vcs.provider.name` | 세션 저장소의 ID, `origin` 원격에서 파생됨. [저장소 속성](#repository-attributes) 참조 | `OTEL_METRICS_INCLUDE_REPOSITORY` (기본값: false). Claude Code v2.1.269 이상 필요 |

586 599

587Claude Code가 [Claude 앱 게이트웨이](/docs/ko/claude-apps-gateway)에 로그인되어 있으면, CLI는 게이트웨이 세션의 인증된 ID로 내보내기를 스탬프합니다: `user.id`는 익명 설치 식별자가 아닌 IdP 주체이고, `user.email`은 로그인한 이메일이며, `user.groups`는 쉼표로 구분된 문자열로 IdP 그룹 멤버십을 전달합니다. 각 내보내기는 또한 `identity.source: gateway-oidc`를 전달합니다. 게이트웨이 ID가 마지막에 적용되므로 `OTEL_RESOURCE_ATTRIBUTES`를 통해 설정된 `user.*` 및 `identity.*` 키는 게이트웨이 세션에서 무시됩니다.600`/login`을 통해 [Claude 앱 게이트웨이](/docs/ko/claude-apps-gateway)에 로그인한 세션에서 CLI는 인증된 ID로 내보내기를 스탬프합니다: `user.id`는 IdP 주체, `user.email`은 로그인한 이메일, `user.groups`는 IdP 그룹 멤버십을 쉼표로 구분된 문자열로 전달합니다. 각 내보내기는 또한 `identity.source: gateway-oidc`를 전달합니다. 게이트웨이 ID가 마지막에 적용되므로 `OTEL_RESOURCE_ATTRIBUTES`를 통해 설정된 `user.*` 및 `identity.*` 키는 해당 세션에서 무시됩니다.

588 601

589이벤트는 추가로 다음 속성을 포함합니다. 이들은 무한 카디널리티를 유발하므로 메트릭에 절대 첨부되지 않습니다:602게이트웨이를 통해 연결되는 Claude Desktop 및 Cowork 세션의 ID 속성에 대해서는 [게이트웨이 `telemetry` 참조](/docs/ko/claude-apps-gateway-config#telemetry)를 참조하세요.

603

604이벤트는 추가로 다음 속성을 포함합니다. 이들은 무제한 카디널리티를 야기할 수 있으므로 메트릭에 절대 첨부되지 않습니다:

590 605

591* `prompt.id`: 사용자 프롬프트를 다음 프롬프트까지의 모든 후속 이벤트와 연관시키는 UUID. [이벤트 상관 속성](#event-correlation-attributes) 참조.606* `prompt.id`: 사용자 프롬프트를 다음 프롬프트까지의 모든 후속 이벤트와 연관시키는 UUID. [이벤트 상관 속성](#event-correlation-attributes) 참조.

592* `workspace.host_paths`: 데스크톱 앱에서 선택한 호스트 작업 공간 디렉토리, 문자열 배열로607* `workspace.host_paths`: 데스크톱 앱에서 선택한 호스트 작업 공간 디렉토리, 문자열 배열로

593* `workflow.run_id`: [Workflow](/docs/ko/workflows) 도구 실행에 속하는 에이전트가 내보낸 API 및 도구 이벤트에서 `wf_` 접두사가 붙은 실행 식별자. 하나의 `workflow.run_id`로 이벤트를 필터링하면 해당 실행의 API 요청 및 도구 결과를 재구성합니다. 식별자는 워크플로우 스크립트가 생성하는 에이전트와 그 에이전트가 차례로 생성하는 모든 에이전트(예: 스킬 호출)를 포함합니다. Workflow 도구 결과에서 보고된 실행 식별자와 일치합니다. 다른 모든 이벤트에는 없습니다. Claude Code v2.1.202 이상 필요608* `workflow.run_id`: 실행 식별자, `wf_` 접두사가 붙음, API 및 [Workflow](/docs/ko/workflows) 도구 실행에 속하는 에이전트가 내보낸 도구 이벤트. 하나의 `workflow.run_id`로 이벤트를 필터링하면 해당 실행의 API 요청 및 도구 결과를 재구성합니다. 식별자는 워크플로우 스크립트가 생성하는 에이전트 및 해당 에이전트가 차례로 생성하는 모든 에이전트(예: 스킬 호출)를 포함합니다. Workflow 도구 결과에서 보고된 실행 식별자와 일치합니다. 다른 모든 이벤트에는 없습니다. Claude Code v2.1.202 이상 필요

594* `workflow.name`: 워크플로우의 이름, 스크립트의 `meta.name`, `workflow.run_id`와 함께 내보냄. 기본 제공 워크플로우 이름은 수정되지 않은 기본 제공 스크립트를 실행할 때 그대로 나타납니다. 사용자 작성 이름(기본 제공 스크립트의 편집된 복사본 포함)은 `OTEL_LOG_TOOL_DETAILS=1`이 설정되지 않으면 `custom`으로 대체됩니다. Claude Code v2.1.202 이상 필요609* `workflow.name`: 워크플로우의 이름, 스크립트의 `meta.name`, `workflow.run_id`와 함께 내보냄. 기본 제공 워크플로우 이름은 수정되지 않은 기본 제공 스크립트를 실행할 때 그대로 나타납니다. 사용자 작성 이름(기본 제공 스크립트의 편집된 복사본 포함)은 `OTEL_LOG_TOOL_DETAILS=1`이 설정되지 않은 경우 `custom`으로 대체됩니다. Claude Code v2.1.202 이상 필요

595 610

596<h4 id="repository-attributes">611<h4 id="repository-attributes">

597 저장소 속성612 저장소 속성

598</h4>613</h4>

599 614

600`OTEL_METRICS_INCLUDE_REPOSITORY=true`를 설정하여 메트릭 및 이벤트에 세션의 저장소 ID를 태그하면, 공유 수집기가 저장소별로 사용량을 속성화할 수 있습니다. Claude Code v2.1.269 이상 필요.615`OTEL_METRICS_INCLUDE_REPOSITORY=true`를 설정하여 메트릭 및 이벤트에 세션의 저장소 ID를 태그하면 공유 수집기가 저장소별 사용량을 속성화할 수 있습니다. Claude Code v2.1.269 이상 필요.

601 616

602Claude Code는 저장소의 `origin` 원격에서 세션당 한 번 이러한 속성을 파생합니다. 저장소의 HTTPS 및 SSH 원격이 GitHub, GitLab, Bitbucket Cloud에서처럼 동일한 호스트와 동일한 경로를 지정할 때, 둘 다 동일한 값을 생성합니다:617Claude Code는 저장소의 `origin` 원격에서 세션당 한 번 이러한 속성을 파생합니다. 저장소의 HTTPS 및 SSH 원격이 GitHub, GitLab, Bitbucket Cloud에서처럼 동일한 호스트와 동일한 경로를 지정할 때 둘 다 동일한 값을 생성합니다:

603 618

604| 속성 | 값 |619| 속성 | 값 |

605| - | - |620| - | - |

609| `vcs.provider.name` | Claude Code가 원격의 호스트 또는 URL 형태를 이러한 공급자 중 하나로 인식할 때 `github`, `gitlab`, `bitbucket`, 또는 `gitea`; 그 외의 경우 생략됨 |624| `vcs.provider.name` | Claude Code가 원격의 호스트 또는 URL 형태를 해당 공급자 중 하나로 인식할 때 `github`, `gitlab`, `bitbucket`, 또는 `gitea`; 그 외의 경우 생략됨 |

610 625

611값은 소문자로 변환되며, 원격 URL의 자격 증명, 쿼리 문자열, 조각은 절대 나타나지 않습니다. 세션에 `origin` 원격이 없거나, 원격이 URL 형태가 아니거나, 유일한 포함 저장소가 홈 디렉토리일 때 속성은 생략됩니다.626값은 소문자로 변환되며, 원격 URL의 자격 증명, 쿼리 문자열, 조각은 절대 나타나지 않습니다. 세션에 `origin` 원격이 없을 때, 원격이 URL 형태가 아닐 때, 또는 유일한 포함 저장소가 홈 디렉토리일 때 속성이 생략됩니다.

612 627

613[클라우드 세션](/docs/ko/claude-code-on-the-web)에서 이러한 속성을 얻으려면, `OTEL_METRICS_INCLUDE_REPOSITORY`를 포함한 원격 측정 변수를 [클라우드 환경](/docs/ko/cloud-environments#set-environment-variables)에 설정합니다. 또한 환경의 [네트워크 액세스](/docs/ko/cloud-environments#network-access)에서 수집기의 도메인을 허용합니다.628[클라우드 세션](/docs/ko/claude-code-on-the-web)에서 이러한 속성을 얻으려면 `OTEL_METRICS_INCLUDE_REPOSITORY`를 포함한 원격 측정 변수를 [클라우드 환경](/docs/ko/cloud-environments#set-environment-variables)에 설정하세요. 또한 환경의 [네트워크 액세스](/docs/ko/cloud-environments#network-access)에서 수집기의 도메인을 허용하세요.

614 629

615[`OTEL_RESOURCE_ATTRIBUTES`](#multi-team-organization-support)에서 선언한 `vcs.*` 키는 해당 키의 파생된 값을 대체합니다. `vcs.repository.url.full`을 선언하면, Claude Code는 절대 원격을 읽지 않으며 선언한 키만 보고합니다.630[`OTEL_RESOURCE_ATTRIBUTES`](#multi-team-organization-support)에서 선언한 `vcs.*` 키는 해당 키의 파생된 값을 대체합니다. `vcs.repository.url.full`을 선언하면 Claude Code는 절대 원격을 읽지 않으며 선언한 키만 보고합니다.

616 631

617HTTPS 및 SSH 클론이 서로 다른 값을 보고하는 경우, 예를 들어 HTTPS 클론 URL이 SSH URL에 없는 경로 접두사를 전달하는 자체 호스팅 설치의 경우, `OTEL_RESOURCE_ATTRIBUTES`에서 `vcs.repository.url.full`을 보고하려는 다른 모든 `vcs.*` 키와 함께 선언합니다. 그러면 모든 클론이 선언한 ID를 보고합니다.632하나의 저장소의 HTTPS 및 SSH 클론이 서로 다른 값을 보고할 경우, 예를 들어 HTTPS 클론 URL이 SSH URL에 없는 경로 접두사를 전달하는 자체 호스팅 설치의 경우, `OTEL_RESOURCE_ATTRIBUTES`에서 `vcs.repository.url.full`을 보고하려는 다른 모든 `vcs.*` 키와 함께 선언하세요. 그러면 모든 클론이 선언한 ID를 보고합니다.

618 633

619속성은 자신의 내보내기로만 흐릅니다; Anthropic의 원격 측정은 모든 `vcs.*` 키를 삭제합니다.634속성은 자신의 내보내기로만 흐릅니다; Anthropic의 원격 측정은 모든 `vcs.*` 키를 삭제합니다.

620 635

622 메트릭637 메트릭

623</h3>638</h3>

624 639

625Claude Code는 다음 메트릭을 내보냅니다. 단위 열은 각 메트릭에 첨부된 OpenTelemetry 단위 문자열을 보여줍니다; 카운트 메트릭은 없습니다.640Claude Code는 다음 메트릭을 내보냅니다. Unit 열은 각 메트릭에 첨부된 OpenTelemetry 단위 문자열을 보여줍니다; 카운트 메트릭은 없습니다.

626 641

627| 메트릭 이름 | 설명 | 단위 |642| 메트릭 이름 | 설명 | 단위 |

628| - | - | - |643| - | - | - |

635| `claude_code.code_edit_tool.decision` | 코드 편집 도구 권한 결정 수 | 없음 |650| `claude_code.code_edit_tool.decision` | 코드 편집 도구 권한 결정 수 | 없음 |

636| `claude_code.active_time.total` | 총 활성 시간 | s |651| `claude_code.active_time.total` | 총 활성 시간 | s |

637 652

638`prometheus`가 `OTEL_METRICS_EXPORTER`에 나열된 유일한 내보내기일 때, Claude Code는 스크래이프가 유효한 Prometheus 텍스트 형식으로 유지되도록 내보낸 메트릭에서 `USD`, `tokens`, `s` 단위를 생략합니다. 메트릭 이름은 변경되지 않으며, `otlp,prometheus`와 같이 내보내기를 결합하는 구성은 단위를 유지합니다. v2.1.216 이전에는 Prometheus 스크래이프에 일부 스크래이퍼가 거부한 OpenMetrics 전용 `# UNIT` 라인이 포함되었습니다.653`prometheus`가 `OTEL_METRICS_EXPORTER`에 나열된 유일한 내보내기일 때 Claude Code는 스크래이프가 유효한 Prometheus 텍스트 형식으로 유지되도록 내보낸 메트릭에서 `USD`, `tokens`, `s` 단위를 생략합니다. 메트릭 이름은 변경되지 않으며, `otlp,prometheus`와 같이 내보내기를 결합하는 구성은 단위를 유지합니다. v2.1.216 이전에는 Prometheus 스크래이프에 일부 스크래이퍼가 거부한 OpenMetrics 전용 `# UNIT` 라인이 포함되었습니다.

639 654

640<h3 id="metric-details">655<h3 id="metric-details">

641 메트릭 세부 정보656 메트릭 세부 정보

652**속성**:667**속성**:

653 668

654* 모든 [표준 속성](#standard-attributes)669* 모든 [표준 속성](#standard-attributes)

655* `start_type`: 세션이 시작된 방식. `"fresh"`, `"resume"`, `"continue"`, 또는 `"agents_view"` 중 하나. `"agents_view"` 값은 `claude agents` 대시보드 프로세스, 대화형 세션이 아닌 사용자 시작 로컬 UI를 식별합니다. 대시보드에서 UI 프로세스 시작을 대화형 세션과 분리하려면 이 값으로 필터링합니다.670* `start_type`: 세션이 시작된 방식. `"fresh"`, `"resume"`, `"continue"`, 또는 `"agents_view"` 중 하나. `"agents_view"` 값은 `claude agents` 대시보드 프로세스, 대화형 세션이 아닌 사용자 시작 로컬 UI를 식별합니다. 대시보드에서 UI 프로세스 시작을 대화형 세션과 분리하려면 이 값으로 필터링하세요.

656 671

657<h4 id="lines-of-code-counter">672<h4 id="lines-of-code-counter">

658 코드 라인 카운터673 코드 라인 카운터

703* `effort`: 요청에 적용된 [노력 수준](/docs/ko/model-config#adjust-effort-level): `"low"`, `"medium"`, `"high"`, `"xhigh"`, 또는 `"max"`. Claude Code가 노력 수준을 보내지 않을 때 없음, 예를 들어 노력을 지원하지 않는 모델에서.718* `effort`: 요청에 적용된 [노력 수준](/docs/ko/model-config#adjust-effort-level): `"low"`, `"medium"`, `"high"`, `"xhigh"`, 또는 `"max"`. Claude Code가 노력 수준을 보내지 않을 때 없음, 예를 들어 노력을 지원하지 않는 모델에서.

704* `agent.name`: 요청을 발급한 하위 에이전트 유형. 기본 제공 에이전트 이름과 공식 마켓플레이스 플러그인의 에이전트는 그대로 나타납니다. 다른 사용자 정의 에이전트 이름은 `"custom"`으로 대체됩니다. 요청이 명명된 하위 에이전트 유형에 의해 발급되지 않았을 때 없음.719* `agent.name`: 요청을 발급한 하위 에이전트 유형. 기본 제공 에이전트 이름과 공식 마켓플레이스 플러그인의 에이전트는 그대로 나타납니다. 다른 사용자 정의 에이전트 이름은 `"custom"`으로 대체됩니다. 요청이 명명된 하위 에이전트 유형에 의해 발급되지 않았을 때 없음.

705* `skill.name`: 요청에 대해 활성화된 스킬, Skill 도구 또는 `/` 명령으로 설정되거나 생성된 하위 에이전트에 의해 상속됨. 기본 제공, 번들, 사용자 정의, 공식 마켓플레이스 플러그인 스킬 이름은 그대로 나타납니다. 타사 플러그인 스킬 이름은 `"third-party"`로 대체됩니다. 활성 스킬이 없을 때 없음.720* `skill.name`: 요청에 대해 활성화된 스킬, Skill 도구 또는 `/` 명령으로 설정되거나 생성된 하위 에이전트에 의해 상속됨. 기본 제공, 번들, 사용자 정의, 공식 마켓플레이스 플러그인 스킬 이름은 그대로 나타납니다. 타사 플러그인 스킬 이름은 `"third-party"`로 대체됩니다. 활성 스킬이 없을 때 없음.

706* `plugin.name`: 활성 스킬 또는 하위 에이전트가 플러그인에 의해 제공될 때 소유 플러그인. 공식 마켓플레이스 플러그인 이름은 그대로 나타납니다. 타사 플러그인 이름은 `"third-party"`로 대체됩니다. 스킬과 하위 에이전트 모두 소유 플러그인을 가지지 않을 때 없음.721* `plugin.name`: 활성 스킬 또는 하위 에이전트가 플러그인에 의해 제공될 때 소유 플러그인. 공식 마켓플레이스 플러그인 이름은 그대로 나타납니다. 타사 플러그인 이름은 `"third-party"`로 대체됩니다. 스킬과 하위 에이전트 모두 소유 플러그인이 없을 때 없음.

707* `marketplace.name`: 소유 플러그인이 설치된 마켓플레이스. `OTEL_LOG_TOOL_DETAILS=1`이 설정되어 있어도 공식 마켓플레이스 플러그인에 대해서만 내보내집니다. 그 외의 경우 없음.722* `marketplace.name`: 소유 플러그인이 설치된 마켓플레이스. `OTEL_LOG_TOOL_DETAILS=1`이 설정되어 있어도 공식 마켓플레이스 플러그인에 대해서만 내보냄. 그 외의 경우 없음.

708* `mcp_server.name`: 이 요청이 소비한 도구 결과의 MCP 서버. 기본 제공, claude.ai 프록시, 공식 레지스트리 서버 이름은 그대로 나타납니다. 사용자 구성 서버 이름은 `"custom"`으로 대체됩니다. 요청이 MCP 도구 결과를 소비하지 않았을 때 없음. v2.1.222 이전에는 Claude Code가 MCP 도구 호출 후 모든 요청에 이 속성을 설정했으며, 도구 결과를 소비한 요청에만 설정하지 않았으므로 이를 집계하는 대시보드는 업그레이드 후 단계 감소를 보입니다.723* `mcp_server.name`: 이 요청이 소비한 도구 결과의 MCP 서버. 기본 제공, claude.ai 프록시, 공식 레지스트리 서버 이름은 그대로 나타납니다. 사용자 구성 서버 이름은 `"custom"`으로 대체됩니다. 요청이 MCP 도구 결과를 소비하지 않았을 때 없음. v2.1.222 이전에는 Claude Code가 MCP 도구 호출 후 모든 요청에 이 속성을 설정했으며, 도구 결과를 소비한 요청에만 설정하지 않았으므로 이를 집계하는 대시보드는 업그레이드 후 단계 감소를 보여줍니다.

709* `mcp_tool.name`: 이 요청이 소비한 도구 결과의 MCP 도구, `mcp_server.name`과 동일한 수정 및 버전 동작. 요청이 MCP 도구 결과를 소비하지 않았을 때 없음.724* `mcp_tool.name`: 이 요청이 소비한 도구 결과의 MCP 도구, `mcp_server.name`과 동일한 수정 및 버전 동작. 요청이 MCP 도구 결과를 소비하지 않았을 때 없음.

710 725

711<h4 id="token-counter">726<h4 id="token-counter">

717**속성**:732**속성**:

718 733

719* 모든 [표준 속성](#standard-attributes)734* 모든 [표준 속성](#standard-attributes)

720* `type`: (`"input"`, `"output"`, `"cacheRead"`, `"cacheCreation"`)735* `type`: (`"input"`, `"output"`, `"cacheRead"`, `"cacheCreation"`). `"input"` 유형은 프롬프트 캐시에서 읽거나 캐시에 쓴 토큰을 제외하며, 이러한 토큰은 `"cacheRead"` 및 `"cacheCreation"`으로 집계됩니다

721* `model`: 모델 식별자 (예: "claude-sonnet-5")736* `model`: 모델 식별자 (예: "claude-sonnet-5")

722* `query_source`: 요청을 발급한 하위 시스템의 범주. `"main"`, `"subagent"`, 또는 `"auxiliary"` 중 하나737* `query_source`: 요청을 발급한 하위 시스템의 범주. `"main"`, `"subagent"`, 또는 `"auxiliary"` 중 하나

723* `speed`: 요청이 빠른 모드를 사용했을 때 `"fast"`. 그 외의 경우 없음738* `speed`: 요청이 빠른 모드를 사용했을 때 `"fast"`. 그 외의 경우 없음

724* `effort`: 요청에 적용된 [노력 수준](/docs/ko/model-config#adjust-effort-level). 세부 정보는 [비용 카운터](#cost-counter) 참조.739* `effort`: 요청에 적용된 [노력 수준](/docs/ko/model-config#adjust-effort-level). 세부 정보는 [비용 카운터](#cost-counter)를 참조하세요.

725* `agent.name`, `skill.name`, `plugin.name`, `marketplace.name`, `mcp_server.name`, `mcp_tool.name`: 요청에 대한 스킬, 플러그인, 에이전트, MCP 속성. 정의 및 수정 동작은 [비용 카운터](#cost-counter) 참조.740* `agent.name`, `skill.name`, `plugin.name`, `marketplace.name`, `mcp_server.name`, `mcp_tool.name`: 요청에 대한 스킬, 플러그인, 에이전트, MCP 속성. 정의 및 수정 동작은 [비용 카운터](#cost-counter)를 참조하세요.

726 741

727<h4 id="code-edit-tool-decision-counter">742<h4 id="code-edit-tool-decision-counter">

728 코드 편집 도구 결정 카운터743 코드 편집 도구 결정 카운터

735* 모든 [표준 속성](#standard-attributes)750* 모든 [표준 속성](#standard-attributes)

736* `tool_name`: 도구 이름 (`"Edit"`, `"Write"`, `"NotebookEdit"`)751* `tool_name`: 도구 이름 (`"Edit"`, `"Write"`, `"NotebookEdit"`)

737* `decision`: 사용자 결정 (`"accept"`, `"reject"`)752* `decision`: 사용자 결정 (`"accept"`, `"reject"`)

738* `source`: 결정이 나온 위치. `"config"`, `"hook"`, `"user_permanent"`, `"user_temporary"`, `"user_abort"`, 또는 `"user_reject"` 중 하나. 각 값의 의미는 [도구 결정 이벤트](#tool-decision-event) 참조.753* `source`: 결정이 나온 위치. `"config"`, `"hook"`, `"user_permanent"`, `"user_temporary"`, `"user_abort"`, 또는 `"user_reject"` 중 하나. 각 값의 의미는 [도구 결정 이벤트](#tool-decision-event)를 참조하세요.

739* `language`: 편집된 파일의 프로그래밍 언어, 예: `"TypeScript"`, `"Python"`, `"JavaScript"`, 또는 `"Markdown"`. 인식되지 않는 파일 확장자의 경우 `"unknown"` 반환.754* `language`: 편집된 파일의 프로그래밍 언어, 예: `"TypeScript"`, `"Python"`, `"JavaScript"`, 또는 `"Markdown"`. 인식되지 않은 파일 확장자에 대해 `"unknown"`을 반환합니다.

740 755

741<h4 id="active-time-counter">756<h4 id="active-time-counter">

742 활성 시간 카운터757 활성 시간 카운터

759 이벤트 상관 속성774 이벤트 상관 속성

760</h4>775</h4>

761 776

762사용자가 프롬프트를 제출하면, Claude Code는 여러 API 호출을 수행하고 여러 도구를 실행할 수 있습니다. `prompt.id` 속성을 사용하면 해당 이벤트를 모두 트리거한 단일 프롬프트에 연결할 수 있습니다.777사용자가 프롬프트를 제출하면 Claude Code는 여러 API 호출을 수행하고 여러 도구를 실행할 수 있습니다. `prompt.id` 속성을 사용하면 해당 이벤트를 모두 트리거한 단일 프롬프트에 연결할 수 있습니다.

763 778

764| 속성 | 설명 |779| 속성 | 설명 |

765| - | - |780| - | - |

768| `message.uuid` | 세션 기록에 유지되는 메시지의 UUID, `~/.claude/projects/*/*.jsonl` 파일. `assistant_response`, `api_response_body`, 및 명령 디스패치를 제외한 `user_prompt`에 존재하며, 이는 0개 이상의 메시지를 생성할 수 있습니다. `assistant_response` 및 `api_response_body`에서 이는 응답의 최종 기록 항목이며, 다음 턴의 `parentUuid`가 이로부터 체인됩니다. Claude Code v2.1.214 이상 필요, 또는 `api_response_body`에서 v2.1.274 이상 |783| `message.uuid` | 세션 기록에 유지되는 메시지의 UUID, `~/.claude/projects/*/*.jsonl` 파일. `assistant_response`, `api_response_body`, 및 명령 디스패치를 제외한 `user_prompt`에 있음, 이는 0개 이상의 메시지를 생성할 수 있음. `assistant_response` 및 `api_response_body`에서 이는 응답의 최종 기록 항목이며, 다음 턴의 `parentUuid`가 이로부터 체인됩니다. Claude Code v2.1.214 이상 필요, 또는 `api_response_body`에서 v2.1.274 이상 |

769| `request_id` | `request-id` 응답 헤더에서 읽은 서버 할당 API 요청 ID, 예: `req_011...`. [Amazon Bedrock](/docs/ko/amazon-bedrock)과 같이 `request-id` 헤더가 없는 응답의 경우, 값은 `x-amzn-requestid` 헤더에서 대신 옵니다. `api_request`, `api_error`, `api_refusal`, `assistant_response`, 및 응답이 헤더 중 하나를 전달할 때 `api_response_body`에 존재합니다. `llm_request` 추적 스팬의 동일한 속성과 일치합니다. `x-amzn-requestid` 소스는 Claude Code v2.1.282 이상 필요 |784| `request_id` | `request-id` 응답 헤더에서 읽은 서버 할당 API 요청 ID, 예: `req_011...`. `request-id` 헤더가 없는 응답의 경우, [Amazon Bedrock](/docs/ko/amazon-bedrock)과 같이 값은 `x-amzn-requestid` 헤더에서 대신 옵니다. `api_request`, `api_error`, `api_refusal`, `assistant_response`, `api_response_body`에 있음, 응답이 헤더 중 하나를 전달할 때. `llm_request` 추적 스팬의 동일한 속성과 일치합니다. `x-amzn-requestid` 소스는 Claude Code v2.1.282 이상 필요 |

770| `client_request_id` | `x-client-request-id` 요청 헤더로 전송된 클라이언트 생성 UUID. 자사 API 연결의 `api_request` 및 `api_error`에 존재; 타사 공급자 백엔드 및 요청이 비스트리밍 폴백을 통해 재시도되었을 때 없음. 요청을 응답과 쌍으로 만들고 타임아웃과 같이 서버 `request_id`를 생성하지 않은 실패에 대해 사용 가능하게 유지합니다. `llm_request` 추적 스팬의 동일한 속성과 일치합니다. Claude Code v2.1.214 이상 필요 |785| `client_request_id` | `x-client-request-id` 요청 헤더로 전송된 클라이언트 생성 UUID. 첫 번째 당사자 API 연결에서 `api_request` 및 `api_error`에 있음; 타사 공급자 백엔드 및 요청이 비스트리밍 폴백을 통해 재시도되었을 때 없음. 요청을 응답과 쌍으로 만들고 서버 `request_id`를 생성하지 않은 시간 초과와 같은 실패에 대해 사용 가능하게 유지합니다. `llm_request` 추적 스팬의 동일한 속성과 일치합니다. Claude Code v2.1.214 이상 필요 |

771 786

772단일 프롬프트로 트리거된 모든 활동을 추적하려면, 특정 `prompt.id` 값으로 이벤트를 필터링합니다. 이는 user\_prompt 이벤트, 모든 api\_request 이벤트, 그리고 해당 프롬프트 처리 중에 발생한 모든 tool\_result 이벤트를 반환합니다.787단일 프롬프트로 트리거된 모든 활동을 추적하려면 특정 `prompt.id` 값으로 이벤트를 필터링하세요. 이는 user\_prompt 이벤트, 모든 api\_request 이벤트, 해당 프롬프트 처리 중에 발생한 모든 tool\_result 이벤트를 반환합니다.

773 788

774`event.sequence`는 Claude Code 프로세스가 시작될 때마다 0에서 시작하고 해당 프로세스의 수명 동안 증가합니다. `/clear`를 통해 계속 계산되며, 이는 새로운 `session.id`를 할당합니다. [세션을 포크하지 않고 재개](/docs/ko/how-claude-code-works#resume-or-fork-sessions)하면, 세션은 `session.id`를 유지하지만 `event.sequence` 값을 재개한 프로세스에서 가져오므로, 한 세션 내에서 나중 이벤트가 이전 이벤트보다 낮은 값을 전달하거나 하나를 반복할 수 있습니다. 세션의 이벤트를 순서대로 정렬하려면, `event.timestamp`로 정렬하고 `event.sequence`를 사용하여 타임스탬프를 공유하는 이벤트를 순서대로 정렬합니다.789`event.sequence`는 Claude Code 프로세스가 시작될 때마다 0에서 시작하고 해당 프로세스의 수명 동안 증가합니다. `/clear`를 통해 계속 계산되며, 이는 새로운 `session.id`를 할당합니다. [세션을 포크하지 않고 재개](/docs/ko/how-claude-code-works#resume-or-fork-sessions)하면 세션은 `session.id`를 유지하지만 `event.sequence` 값을 재개한 프로세스에서 가져오므로 한 세션 내에서 나중 이벤트가 이전 이벤트보다 낮은 값을 전달하거나 반복할 수 있습니다. 세션의 이벤트를 순서대로 정렬하려면 `event.timestamp`로 정렬하고 `event.sequence`를 사용하여 타임스탬프를 공유하는 이벤트를 순서대로 정렬하세요.

775 790

776메시지 수준 재구성의 경우, 각 이벤트 클래스는 세션 기록의 필드와 일치하는 키를 전달합니다. 기록 항목 형식은 [Claude Code 내부](/docs/ko/sessions#where-transcripts-are-stored)이며 버전 간에 변경되므로, 이러한 필드에 조인하는 파이프라인은 모든 릴리스에서 중단될 수 있습니다; 조인을 안정적인 계약이 아닌 버전별 조인으로 취급합니다:791메시지 수준 재구성의 경우 각 이벤트 클래스는 세션 기록의 필드와 일치하는 키를 전달합니다. 기록 항목 형식은 [Claude Code 내부](/docs/ko/sessions#where-transcripts-are-stored)이며 버전 간에 변경되므로 이러한 필드에 조인하는 파이프라인은 모든 릴리스에서 중단될 수 있습니다; 조인을 안정적인 계약이 아닌 버전별 조인으로 취급하세요:

777 792

778* `user_prompt`, `assistant_response`, 및 `api_response_body`의 `message.uuid`793* `user_prompt`, `assistant_response`, `api_response_body`의 `message.uuid`

779* API 이벤트의 `request_id`, 기록의 어시스턴트 항목에 `requestId`로 유지됨794* API 이벤트의 `request_id`, 기록의 어시스턴트 항목에 `requestId`로 유지됨

780* `tool_result` 및 `tool_decision` 이벤트의 `tool_use_id`795* `tool_result` 및 `tool_decision` 이벤트의 `tool_use_id`

781 796

783 사용자 프롬프트 이벤트798 사용자 프롬프트 이벤트

784</h4>799</h4>

785 800

786사용자가 프롬프트를 제출할 때 기록됩니다.801Claude Code가 자체적으로 시작하는 턴을 포함하여 프롬프트가 제출될 때 로그에 기록됩니다.

787 802

788**이벤트 이름**: `claude_code.user_prompt`803**이벤트 이름**: `claude_code.user_prompt`

789 804

792* 모든 [표준 속성](#standard-attributes)807* 모든 [표준 속성](#standard-attributes)

793* `event.name`: `"user_prompt"`808* `event.name`: `"user_prompt"`

794* `event.timestamp`: ISO 8601 타임스탬프809* `event.timestamp`: ISO 8601 타임스탬프

795* `event.sequence`: 이벤트 순서 지정을 위한 프로세스당 카운터, [이벤트 상관 속성](#event-correlation-attributes)에서 설명됨810* `event.sequence`: [이벤트 상관 속성](#event-correlation-attributes)에서 설명한 이벤트 순서 지정을 위한 프로세스당 카운터

796* `prompt_length`: 프롬프트의 길이811* `prompt_length`: 프롬프트의 길이

797* `prompt`: 프롬프트 내용. 기본적으로 수정됨. `OTEL_LOG_USER_PROMPTS=1`을 설정하여 포함812* `prompt`: 프롬프트 내용. 기본적으로 수정됨. `OTEL_LOG_USER_PROMPTS=1`을 설정하여 포함

798* `message.uuid`: 결과 사용자 메시지의 UUID, 유지된 기록 항목과 일치. 명령 디스패치에는 없으며, 이는 0개 이상의 메시지를 생성할 수 있습니다. Claude Code v2.1.214 이상 필요813* `prompt_text`: `prompt`와 동일한 값으로, 동일한 조건에서 가려집니다. 점으로 구분된 속성 이름을 중첩 객체로 저장하는 백엔드는 `prompt.id`를 `prompt`라는 객체 안의 `id`로 읽어 프롬프트 문자열을 잃을 수 있습니다. 이러한 백엔드에서는 `prompt_text`를 대신 읽으세요. Claude Code v2.1.287 이상이 필요합니다

799* `command_name`: 프롬프트가 명령을 호출할 때 명령 이름. `compact` 또는 `debug`와 같은 기본 제공 및 번들 명령 이름은 그대로 내보내집니다; `reset`과 같은 별칭은 정규 이름이 아닌 입력한 대로 내보냅니다. 사용자 정의, 플러그인, MCP 명령 이름은 `OTEL_LOG_TOOL_DETAILS=1`이 설정되지 않으면 `custom` 또는 `mcp`로 축소됩니다814* `message.uuid`: 결과 사용자 메시지의 UUID, 유지된 기록 항목과 일치. 명령 디스패치에서 없음, 0개 이상의 메시지를 생성할 수 있음. Claude Code v2.1.214 이상 필요

800* `command_source`: 명령이 존재할 때 명령의 출처: `builtin`, `custom`, 또는 `mcp`. 플러그인 제공 명령은 `custom`으로 보고합니다815* `command_name`: 프롬프트가 명령을 호출할 때 명령 이름. `compact` 또는 `debug`와 같은 기본 제공 및 번들 명령 이름은 그대로 내보냄; `reset`과 같은 별칭은 정규 이름이 아닌 입력한 대로 내보냄. 사용자 정의, 플러그인, MCP 명령 이름은 `OTEL_LOG_TOOL_DETAILS=1`이 설정되지 않은 경우 `custom` 또는 `mcp`로 축소됨

816* `command_source`: 명령이 있을 때 명령의 출처: `builtin`, `custom`, 또는 `mcp`. 플러그인 제공 명령은 `custom`으로 보고됨

801 817

802<h4 id="assistant-response-event">818<h4 id="assistant-response-event">

803 어시스턴트 응답 이벤트819 어시스턴트 응답 이벤트

812* 모든 [표준 속성](#standard-attributes)828* 모든 [표준 속성](#standard-attributes)

813* `event.name`: `"assistant_response"`829* `event.name`: `"assistant_response"`

814* `event.timestamp`: ISO 8601 타임스탬프830* `event.timestamp`: ISO 8601 타임스탬프

815* `event.sequence`: 이벤트 순서 지정을 위한 프로세스당 카운터, [이벤트 상관 속성](#event-correlation-attributes)에서 설명됨831* `event.sequence`: [이벤트 상관 속성](#event-correlation-attributes)에서 설명한 이벤트 순서 지정을 위한 프로세스당 카운터

816* `response_length`: 응답 텍스트의 문자 길이832* `response_length`: 응답 텍스트의 길이 (문자)

817* `response`: 응답 텍스트, 콘텐츠 제한(기본값 60 KB)에서 잘림. 기본적으로 `<REDACTED>`로 수정됨. `OTEL_LOG_ASSISTANT_RESPONSES=1`을 설정하여 포함. `OTEL_LOG_ASSISTANT_RESPONSES`가 설정되지 않으면, `OTEL_LOG_USER_PROMPTS`가 대신 제어하므로 프롬프트 로깅이 켜져 있는 동안 응답을 수정된 상태로 유지하려면 `OTEL_LOG_ASSISTANT_RESPONSES=0`을 설정합니다833* `response`: 응답 텍스트, 콘텐츠 제한에서 잘림 (기본값 60 KB). 기본적으로 `<REDACTED>`로 수정됨. `OTEL_LOG_ASSISTANT_RESPONSES=1`을 설정하여 포함. `OTEL_LOG_ASSISTANT_RESPONSES`가 설정되지 않으면 `OTEL_LOG_USER_PROMPTS`가 대신 제어하므로 프롬프트 로깅이 켜져 있는 동안 응답을 수정된 상태로 유지하려면 `OTEL_LOG_ASSISTANT_RESPONSES=0`을 설정하세요

818* `model`: 모델 식별자 (예: "claude-sonnet-5")834* `model`: 모델 식별자 (예: "claude-sonnet-5")

819* `request_id`: API 요청 ID, [이벤트 상관 속성](#event-correlation-attributes)에서 설명됨835* `request_id`: [이벤트 상관 속성](#event-correlation-attributes)에서 설명한 API 요청 ID

820* `message.uuid`: 응답의 최종 기록 항목의 UUID. API 응답은 콘텐츠 블록당 하나의 기록 항목으로 유지됩니다; 이는 마지막 항목이며, 다음 턴의 `parentUuid`가 이로부터 체인됩니다. Claude Code v2.1.214 이상 필요836* `message.uuid`: 응답의 최종 기록 항목의 UUID. API 응답은 콘텐츠 블록당 하나의 기록 항목으로 유지됩니다; 이는 마지막 항목이며, 다음 턴의 `parentUuid`가 이로부터 체인됩니다. Claude Code v2.1.214 이상 필요

821* `query_source`: 요청을 발급한 하위 시스템, 예: `"repl_main_thread"`, `"compact"`, 또는 하위 에이전트 이름837* `query_source`: 요청을 발급한 하위 시스템, 예: `"repl_main_thread"`, `"compact"`, 또는 하위 에이전트 이름

822 838

824 도구 결과 이벤트840 도구 결과 이벤트

825</h4>841</h4>

826 842

827도구가 실행을 완료할 때 기록됩니다. 도구 호출이 거부된 경우 내보내지지 않습니다; 거부에 대해서는 [도구 결정 이벤트](#tool-decision-event) 참조.843도구가 실행을 완료할 때 기록됩니다. 도구 호출이 거부된 경우 내보내지지 않습니다; 거부에 대해서는 [도구 결정 이벤트](#tool-decision-event)를 참조하세요.

828 844

829**이벤트 이름**: `claude_code.tool_result`845**이벤트 이름**: `claude_code.tool_result`

830 846

833* 모든 [표준 속성](#standard-attributes)849* 모든 [표준 속성](#standard-attributes)

834* `event.name`: `"tool_result"`850* `event.name`: `"tool_result"`

835* `event.timestamp`: ISO 8601 타임스탬프851* `event.timestamp`: ISO 8601 타임스탬프

836* `event.sequence`: 이벤트 순서 지정을 위한 프로세스당 카운터, [이벤트 상관 속성](#event-correlation-attributes)에서 설명됨852* `event.sequence`: [이벤트 상관 속성](#event-correlation-attributes)에서 설명한 이벤트 순서 지정을 위한 프로세스당 카운터

837* `tool_name`: 도구의 이름853* `tool_name`: 도구의 이름

838* `tool_use_id`: 이 도구 호출의 고유 식별자. 훅에 전달된 `tool_use_id`와 일치하여 OTel 이벤트와 훅 캡처 데이터 간의 상관 관계를 허용합니다.854* `tool_use_id`: 이 도구 호출의 고유 식별자. 훅에 전달된 `tool_use_id`와 일치하여 OTel 이벤트와 훅 캡처 데이터 간의 상관 관계를 허용합니다.

839* `success`: `"true"` 또는 `"false"`855* `success`: `"true"` 또는 `"false"`

840* `duration_ms`: 밀리초 단위의 실행 시간856* `duration_ms`: 실행 시간 (밀리초)

841* `error_type`: 도구가 실패했을 때 오류 범주 문자열, 예: `"Error:ENOENT"` 또는 `"ShellError"`857* `error_type`: 도구가 실패했을 때 오류 범주 문자열, 예: `"Error:ENOENT"` 또는 `"ShellError"`

842* `error` (`OTEL_LOG_TOOL_DETAILS=1`일 때): 도구가 실패했을 때 전체 오류 메시지858* `error` (`OTEL_LOG_TOOL_DETAILS=1`일 때): 도구가 실패했을 때 전체 오류 메시지

843* `decision_type`: 항상 `"accept"`, 이 이벤트는 도구 실행 후에만 내보내지기 때문입니다. 거부된 호출은 도구 결과를 생성하지 않습니다859* `decision_type`: 항상 `"accept"`, 이 이벤트는 도구가 실행된 후에만 내보내지기 때문. 거부된 호출은 도구 결과를 생성하지 않음

844* `decision_source`: 권한 결정이 나온 위치. `"config"`, `"hook"`, `"user_permanent"`, 또는 `"user_temporary"` 중 하나. 각 값의 의미는 [도구 결정 이벤트](#tool-decision-event) 참조. 거부 전용 소스 `"user_abort"` 및 `"user_reject"`는 이 이벤트에 절대 나타나지 않습니다.860* `decision_source`: 권한 결정이 나온 위치. `"config"`, `"hook"`, `"user_permanent"`, 또는 `"user_temporary"` 중 하나. 각 값의 의미는 [도구 결정 이벤트](#tool-decision-event)를 참조하세요. 거부 전용 소스 `"user_abort"` 및 `"user_reject"`는 이 이벤트에 절대 나타나지 않습니다.

845* `tool_input_size_bytes`: JSON 직렬화된 도구 입력의 바이트 크기861* `tool_input_size_bytes`: JSON 직렬화된 도구 입력의 크기 (바이트)

846* `tool_result_size_bytes`: 도구 결과의 바이트 크기862* `tool_result_size_bytes`: 도구 결과의 크기 (바이트)

847* `mcp_server_scope`: MCP 서버 범위 식별자 (MCP 도구의 경우)863* `mcp_server_scope`: MCP 서버 범위 식별자 (MCP 도구의 경우)

848* `vcs.ref.head.revision`, `vcs.ref.head.name`, `vcs.ref.head.type` (`OTEL_LOG_TOOL_DETAILS=1`일 때): Bash 또는 PowerShell 도구에 의해 실행된 성공적인 `git commit`의 커밋 ID. `vcs.ref.head.revision`은 커밋 SHA, `vcs.ref.head.name`은 커밋된 브랜치, `vcs.ref.head.type`은 `branch`. 커밋이 분리된 HEAD에서 이루어진 경우 이름과 유형은 생략됩니다. Claude Code v2.1.269 이상 필요864* `vcs.ref.head.revision`, `vcs.ref.head.name`, `vcs.ref.head.type` (`OTEL_LOG_TOOL_DETAILS=1`일 때): Bash 또는 PowerShell 도구에 의해 실행된 성공적인 `git commit`의 커밋 ID. `vcs.ref.head.revision`은 커밋 SHA, `vcs.ref.head.name`은 커밋된 브랜치, `vcs.ref.head.type`은 `branch`. 커밋이 분리된 HEAD에서 이루어진 경우 이름과 유형이 생략됩니다. Claude Code v2.1.269 이상 필요

849* `tool_parameters` (`OTEL_LOG_TOOL_DETAILS=1`일 때): 도구별 매개변수를 포함하는 JSON 문자열. Claude Desktop의 기본 제공 서버의 경우, Claude Desktop이 소유한 세션에서, `mcp_server_name`/`mcp_tool_name` 쌍은 플래그가 꺼져 있어도 포함되며, [도구 결정 이벤트](#tool-decision-event)와 동일한 호스트 작성 예외입니다, Claude Code v2.1.214 이상 필요. 매개변수는 도구에 따라 다릅니다:865* `tool_parameters` (`OTEL_LOG_TOOL_DETAILS=1`일 때): 도구별 매개변수를 포함하는 JSON 문자열. Claude Desktop의 기본 제공 서버의 경우, Claude Desktop이 소유한 세션에서 `mcp_server_name`/`mcp_tool_name` 쌍은 플래그가 꺼져 있어도 포함되며, [도구 결정 이벤트](#tool-decision-event)와 동일한 호스트 작성 예외, Claude Code v2.1.214 이상 필요. 매개변수는 도구에 따라 다릅니다:

850 * Bash 도구의 경우: `bash_command`, `full_command`, `timeout`, `description`, `dangerouslyDisableSandbox` 포함, 그리고 `git commit` 명령이 성공할 때 `git_commit_id` 및 `git_branch`. `git_commit_id`는 커밋이 세션의 작업 디렉토리의 HEAD일 때 전체 커밋 SHA이고, 그 외의 경우 git의 축약된 SHA입니다. `git_branch`는 커밋된 브랜치이며, 분리된 HEAD에서는 생략됨866 * Bash 도구의 경우: `bash_command`, `full_command`, `timeout`, `description`, `dangerouslyDisableSandbox` 포함, `git commit` 명령이 성공할 때 `git_commit_id` 및 `git_branch`. `git_commit_id`는 커밋이 세션의 작업 디렉토리의 HEAD일 때 전체 커밋 SHA, 그 외의 경우 git의 축약된 SHA. `git_branch`는 커밋된 브랜치, 분리된 HEAD에서 생략됨

851 * 데스크톱 앱의 작업 공간 Bash 도구의 경우, 또한 `tool_name`을 `Bash`로 보고합니다: `bash_command`, `full_command`, `timeout`만 포함867 * 데스크톱 앱의 작업 공간 Bash 도구의 경우, 또한 `tool_name`을 `Bash`로 보고: `bash_command`, `full_command`, `timeout`만 포함

852 * MCP 도구의 경우: `mcp_server_name`, `mcp_tool_name` 포함868 * MCP 도구의 경우: `mcp_server_name`, `mcp_tool_name` 포함

853 * Skill 도구의 경우: `skill_name` 포함869 * Skill 도구의 경우: `skill_name` 포함

854 * Agent 도구 또는 레거시 Task 도구의 경우: `subagent_type` 포함870 * Agent 도구 또는 레거시 Task 도구의 경우: `subagent_type` 포함

855* `tool_input` (`OTEL_LOG_TOOL_DETAILS=1`일 때): JSON 직렬화된 도구 인수. 512자를 초과하는 개별 값은 잘리고, 전체 페이로드는 약 4 K 문자로 제한됩니다. MCP 도구를 포함한 모든 도구에 적용됩니다.871* `tool_input` (`OTEL_LOG_TOOL_DETAILS=1`일 때): JSON 직렬화된 도구 인수. 512자를 초과하는 개별 값은 잘리며, 전체 페이로드는 약 4 K 문자로 제한됩니다. MCP 도구를 포함한 모든 도구에 적용됩니다.

856 872

857<h4 id="api-request-event">873<h4 id="api-request-event">

858 API 요청 이벤트874 API 요청 이벤트

867* 모든 [표준 속성](#standard-attributes)883* 모든 [표준 속성](#standard-attributes)

868* `event.name`: `"api_request"`884* `event.name`: `"api_request"`

869* `event.timestamp`: ISO 8601 타임스탬프885* `event.timestamp`: ISO 8601 타임스탬프

870* `event.sequence`: 이벤트 순서 지정을 위한 프로세스당 카운터, [이벤트 상관 속성](#event-correlation-attributes)에서 설명됨886* `event.sequence`: [이벤트 상관 속성](#event-correlation-attributes)에서 설명한 이벤트 순서 지정을 위한 프로세스당 카운터

871* `model`: 사용된 모델 (예: "claude-sonnet-5")887* `model`: 사용된 모델 (예: "claude-sonnet-5")

872* `cost_usd`: USD 단위의 예상 비용888* `cost_usd`: USD 단위의 예상 비용

873* `cost_usd_micros`: 미국 달러의 백만분의 일 단위의 예상 비용, 정수로 내보내짐889* `cost_usd_micros`: 미국 달러의 백만분의 일 단위의 예상 비용, 정수로 내보냄

874* `duration_ms`: 밀리초 단위의 요청 기간890* `duration_ms`: 요청 지속 시간 (밀리초)

875* `input_tokens`: 입력 토큰 수891* `input_tokens`: 프롬프트 캐시에서 읽거나 캐시에 쓴 토큰을 제외한 입력 토큰 수

876* `output_tokens`: 출력 토큰 수892* `output_tokens`: 출력 토큰 수

877* `cache_read_tokens`: 캐시에서 읽은 토큰 수893* `cache_read_tokens`: 캐시에서 읽은 토큰 수

878* `cache_creation_tokens`: 캐시 생성에 사용된 토큰 수894* `cache_creation_tokens`: 캐시 생성에 사용된 토큰 수

879* `request_id`: `"req_011..."`과 같은 API 요청 ID, [이벤트 상관 속성](#event-correlation-attributes)에서 설명됨.895* `request_id`: `"req_011..."`과 같은 API 요청 ID, [이벤트 상관 속성](#event-correlation-attributes)에서 설명함.

880* `client_request_id`: `x-client-request-id` 요청 헤더로 전송된 클라이언트 생성 UUID; 존재할 때는 [이벤트 상관 속성](#event-correlation-attributes) 테이블 참조. Claude Code v2.1.214 이상 필요896* `client_request_id`: `x-client-request-id` 요청 헤더로 전송된 클라이언트 생성 UUID; 존재할 때는 [이벤트 상관 속성](#event-correlation-attributes) 테이블을 참조하세요. Claude Code v2.1.214 이상 필요

881* `speed`: 빠른 모드가 활성화되었는지 여부를 나타내는 `"fast"` 또는 `"normal"`897* `speed`: `"fast"` 또는 `"normal"`, 빠른 모드가 활성화되었는지 여부를 나타냄

882* `query_source`: 요청을 발급한 하위 시스템, 예: `"repl_main_thread"`, `"compact"`, 또는 하위 에이전트 이름898* `query_source`: 요청을 발급한 하위 시스템, 예: `"repl_main_thread"`, `"compact"`, 또는 하위 에이전트 이름

883* `effort`: 요청에 적용된 [노력 수준](/docs/ko/model-config#adjust-effort-level): `"low"`, `"medium"`, `"high"`, `"xhigh"`, 또는 `"max"`. Claude Code가 노력 수준을 보내지 않을 때 없음, 예를 들어 노력을 지원하지 않는 모델에서.899* `effort`: 요청에 적용된 [노력 수준](/docs/ko/model-config#adjust-effort-level): `"low"`, `"medium"`, `"high"`, `"xhigh"`, 또는 `"max"`. Claude Code가 노력 수준을 보내지 않을 때 없음, 예를 들어 노력을 지원하지 않는 모델에서.

884* `agent.name`, `skill.name`, `plugin.name`, `marketplace.name`, `mcp_server.name`, `mcp_tool.name`: 요청에 대한 스킬, 플러그인, 에이전트, MCP 속성. 정의 및 수정 동작은 [비용 카운터](#cost-counter) 참조.900* `agent.name`, `skill.name`, `plugin.name`, `marketplace.name`, `mcp_server.name`, `mcp_tool.name`: 요청에 대한 스킬, 플러그인, 에이전트, MCP 속성. 정의 및 수정 동작은 [비용 카운터](#cost-counter)를 참조하세요.

885 901

886<h4 id="api-error-event">902<h4 id="api-error-event">

887 API 오류 이벤트903 API 오류 이벤트

896* 모든 [표준 속성](#standard-attributes)912* 모든 [표준 속성](#standard-attributes)

897* `event.name`: `"api_error"`913* `event.name`: `"api_error"`

898* `event.timestamp`: ISO 8601 타임스탬프914* `event.timestamp`: ISO 8601 타임스탬프

899* `event.sequence`: 이벤트 순서 지정을 위한 프로세스당 카운터, [이벤트 상관 속성](#event-correlation-attributes)에서 설명됨915* `event.sequence`: [이벤트 상관 속성](#event-correlation-attributes)에서 설명한 이벤트 순서 지정을 위한 프로세스당 카운터

900* `model`: 사용된 모델 (예: "claude-sonnet-5")916* `model`: 사용된 모델 (예: "claude-sonnet-5")

901* `error`: 오류 메시지917* `error`: 오류 메시지

902* `status_code`: HTTP 상태 코드를 숫자로. 연결 실패와 같은 비 HTTP 오류의 경우 없음.918* `status_code`: HTTP 상태 코드 (숫자). 연결 실패와 같은 비 HTTP 오류의 경우 없음.

903* `duration_ms`: 밀리초 단위의 요청 기간919* `duration_ms`: 요청 지속 시간 (밀리초)

904* `attempt`: 초기 요청을 포함한 총 시도 횟수 (`1`은 재시도가 발생하지 않았음을 의미)920* `attempt`: 초기 요청을 포함한 총 시도 횟수 (`1`은 재시도가 발생하지 않았음을 의미)

905* `request_id`: `"req_011..."`과 같은 API 요청 ID, [이벤트 상관 속성](#event-correlation-attributes)에서 설명됨.921* `request_id`: `"req_011..."`과 같은 API 요청 ID, [이벤트 상관 속성](#event-correlation-attributes)에서 설명함.

906* `client_request_id`: `x-client-request-id` 요청 헤더로 전송된 클라이언트 생성 UUID. 타임아웃 또는 연결 오류와 같은 실패가 서버 `request_id`를 생성하지 않았을 때도 사용 가능; 존재할 때는 [이벤트 상관 속성](#event-correlation-attributes) 테이블 참조. Claude Code v2.1.214 이상 필요922* `client_request_id`: `x-client-request-id` 요청 헤더로 전송된 클라이언트 생성 UUID. 시간 초과 또는 연결 오류와 같은 실패가 서버 `request_id`를 생성하지 않았을 때도 사용 가능; 존재할 때는 [이벤트 상관 속성](#event-correlation-attributes) 테이블을 참조하세요. Claude Code v2.1.214 이상 필요

907* `speed`: 빠른 모드가 활성화되었는지 여부를 나타내는 `"fast"` 또는 `"normal"`923* `speed`: `"fast"` 또는 `"normal"`, 빠른 모드가 활성화되었는지 여부를 나타냄

908* `query_source`: 요청을 발급한 하위 시스템, 예: `"repl_main_thread"`, `"compact"`, 또는 하위 에이전트 이름924* `query_source`: 요청을 발급한 하위 시스템, 예: `"repl_main_thread"`, `"compact"`, 또는 하위 에이전트 이름

909* `effort`: 요청에 적용된 [노력 수준](/docs/ko/model-config#adjust-effort-level). Claude Code가 노력 수준을 보내지 않을 때 없음, 예를 들어 노력을 지원하지 않는 모델에서.925* `effort`: 요청에 적용된 [노력 수준](/docs/ko/model-config#adjust-effort-level). Claude Code가 노력 수준을 보내지 않을 때 없음, 예를 들어 노력을 지원하지 않는 모델에서.

910* `agent.name`, `skill.name`, `plugin.name`, `marketplace.name`, `mcp_server.name`, `mcp_tool.name`: 요청에 대한 스킬, 플러그인, 에이전트, MCP 속성. 정의 및 수정 동작은 [비용 카운터](#cost-counter) 참조.926* `agent.name`, `skill.name`, `plugin.name`, `marketplace.name`, `mcp_server.name`, `mcp_tool.name`: 요청에 대한 스킬, 플러그인, 에이전트, MCP 속성. 정의 및 수정 동작은 [비용 카운터](#cost-counter)를 참조하세요.

911 927

912<h4 id="api-refusal-event">928<h4 id="api-refusal-event">

913 API 거부 이벤트929 API 거부 이벤트

922* 모든 [표준 속성](#standard-attributes)938* 모든 [표준 속성](#standard-attributes)

923* `event.name`: `"api_refusal"`939* `event.name`: `"api_refusal"`

924* `event.timestamp`: ISO 8601 타임스탬프940* `event.timestamp`: ISO 8601 타임스탬프

925* `event.sequence`: 이벤트 순서 지정을 위한 프로세스당 카운터, [이벤트 상관 속성](#event-correlation-attributes)에서 설명됨941* `event.sequence`: [이벤트 상관 속성](#event-correlation-attributes)에서 설명한 이벤트 순서 지정을 위한 프로세스당 카운터

926* `model`: 요청의 모델 식별자942* `model`: 요청의 모델 식별자

927* `request_id`: `"req_011..."`과 같은 API 요청 ID, [이벤트 상관 속성](#event-correlation-attributes)에서 설명됨.943* `request_id`: `"req_011..."`과 같은 API 요청 ID, [이벤트 상관 속성](#event-correlation-attributes)에서 설명함.

928* `query_source`: 요청을 발급한 하위 시스템, 예: `"repl_main_thread"`, `"compact"`, 또는 하위 에이전트 이름. 정의는 [`api_request`](#api-request-event) 참조.944* `query_source`: 요청을 발급한 하위 시스템, 예: `"repl_main_thread"`, `"compact"`, 또는 하위 에이전트 이름. 정의는 [`api_request`](#api-request-event)를 참조하세요.

929* `speed`: [빠른 모드](/docs/ko/fast-mode)가 활성화되었을 때 `"fast"`, 또는 `"normal"`945* `speed`: [빠른 모드](/docs/ko/fast-mode)가 활성화되었을 때 `"fast"`, 또는 `"normal"`

930* `attempt`: 재시도 시도 번호. 첫 번째 시도는 `1`.946* `attempt`: 재시도 시도 번호. 첫 번째 시도는 `1`.

931* `effort`: 요청에 적용된 [노력 수준](/docs/ko/model-config#adjust-effort-level). Claude Code가 노력 수준을 보내지 않을 때 없음, 예를 들어 노력을 지원하지 않는 모델에서.947* `effort`: 요청에 적용된 [노력 수준](/docs/ko/model-config#adjust-effort-level). Claude Code가 노력 수준을 보내지 않을 때 없음, 예를 들어 노력을 지원하지 않는 모델에서.

932* `server_fallback_hop`: API의 서버 측 모델 폴백이 이미 이 거부를 다른 모델에서 재시도했을 때 `true`, 사용자가 이 특정 거부를 보지 못했습니다. 요청이 거부로 끝났을 때 `false`. 단일 턴은 폴백 모델도 거부할 때 나중의 `false` 최종 이벤트와 `true` 홉 이벤트를 모두 내보낼 수 있습니다.948* `server_fallback_hop`: API의 서버 측 모델 폴백이 이미 이 거부를 다른 모델에서 재시도했을 때 `true`, 사용자가 이 특정 거부를 보지 못했습니다. 요청이 거부로 끝났을 때 `false`. 단일 턴은 폴백 모델도 거부할 때 `true` 홉 이벤트와 나중의 `false` 최종 이벤트를 모두 내보낼 수 있습니다.

933* `has_category`: API 응답이 `"cyber"`, `"bio"`, `"frontier_llm"`, 또는 `"reasoning_extraction"`의 `stop_details.category`를 전달했을 때 `true`. 응답이 카테고리를 전달하지 않았거나 해당 집합 외의 값을 전달했을 때 `false`. `server_fallback_hop`이 `true`일 때 없음, 홉 블록은 `stop_details`를 전달하지 않기 때문입니다.949* `has_category`: API 응답이 `"cyber"`, `"bio"`, `"frontier_llm"`, 또는 `"reasoning_extraction"`의 `stop_details.category`를 전달했을 때 `true`. 응답이 카테고리를 전달하지 않았거나 해당 집합 외의 값을 전달했을 때 `false`. `server_fallback_hop`이 `true`일 때 없음, 홉 블록은 `stop_details`를 전달하지 않기 때문.

934* `has_explanation`: API 응답이 `stop_details.explanation`을 전달했을 때 `true`, 그 외의 경우 `false`. `server_fallback_hop`이 `true`일 때 없음.950* `has_explanation`: API 응답이 `stop_details.explanation`을 전달했을 때 `true`, 그 외의 경우 `false`. `server_fallback_hop`이 `true`일 때 없음.

935* `category`: API 응답의 `stop_details.category` 값. `"cyber"`, `"bio"`, `"frontier_llm"`, 또는 `"reasoning_extraction"` 중 하나. `OTEL_LOG_TOOL_DETAILS=1`이 설정되고 `has_category`가 `true`일 때만 존재합니다.951* `category`: API 응답의 `stop_details.category` 값. `"cyber"`, `"bio"`, `"frontier_llm"`, 또는 `"reasoning_extraction"` 중 하나. `OTEL_LOG_TOOL_DETAILS=1`이 설정되고 `has_category`가 `true`일 때만 존재.

936* `agent.name`, `skill.name`, `plugin.name`, `marketplace.name`, `mcp_server.name`, `mcp_tool.name`: 요청에 대한 스킬, 플러그인, 에이전트, MCP 속성. 정의 및 수정 동작은 [비용 카운터](#cost-counter) 참조.952* `agent.name`, `skill.name`, `plugin.name`, `marketplace.name`, `mcp_server.name`, `mcp_tool.name`: 요청에 대한 스킬, 플러그인, 에이전트, MCP 속성. 정의 및 수정 동작은 [비용 카운터](#cost-counter)를 참조하세요.

937 953

938<h4 id="api-request-body-event">954<h4 id="api-request-body-event">

939 API 요청 본문 이벤트955 API 요청 본문 이벤트

940</h4>956</h4>

941 957

942`OTEL_LOG_RAW_API_BODIES`가 설정되었을 때 각 API 요청 시도에 대해 기록됩니다. 조정된 매개변수로 재시도할 때마다 시도당 하나의 이벤트가 내보내집니다.958`OTEL_LOG_RAW_API_BODIES`가 설정되었을 때 각 API 요청 시도에 대해 기록됩니다. 시도당 하나의 이벤트가 내보내지므로 조정된 매개변수로 재시도할 때마다 자신의 이벤트를 생성합니다.

943 959

944**이벤트 이름**: `claude_code.api_request_body`960**이벤트 이름**: `claude_code.api_request_body`

945 961

948* 모든 [표준 속성](#standard-attributes)964* 모든 [표준 속성](#standard-attributes)

949* `event.name`: `"api_request_body"`965* `event.name`: `"api_request_body"`

950* `event.timestamp`: ISO 8601 타임스탬프966* `event.timestamp`: ISO 8601 타임스탬프

951* `event.sequence`: 이벤트 순서 지정을 위한 프로세스당 카운터, [이벤트 상관 속성](#event-correlation-attributes)에서 설명됨967* `event.sequence`: [이벤트 상관 속성](#event-correlation-attributes)에서 설명한 이벤트 순서 지정을 위한 프로세스당 카운터

952* `body`: JSON 직렬화된 Messages API 요청 매개변수, 예: 시스템 프롬프트, 메시지, 도구, 콘텐츠 제한(기본값 60 KB)에서 잘림. 이전 어시스턴트 턴의 확장 사고 콘텐츠는 수정됨. 인라인 모드(`OTEL_LOG_RAW_API_BODIES=1`)에서만 내보내짐.968* `body`: JSON 직렬화된 Messages API 요청 매개변수, 예: 시스템 프롬프트, 메시지, 도구, 콘텐츠 제한에서 잘림 (기본값 60 KB). 이전 어시스턴트 턴의 확장 사고 콘텐츠는 수정됨. 인라인 모드에서만 내보냄 (`OTEL_LOG_RAW_API_BODIES=1`).

953* `body_ref`: 잘리지 않은 본문을 포함하는 `<dir>/<uuid>.request.json` 파일의 절대 경로. 파일 모드(`OTEL_LOG_RAW_API_BODIES=file:<dir>`)에서만 내보내짐.969* `body_ref`: 잘리지 않은 본문을 포함하는 `<dir>/<uuid>.request.json` 파일의 절대 경로. 파일 모드에서만 내보냄 (`OTEL_LOG_RAW_API_BODIES=file:<dir>`).

954* `body_length`: 잘리지 않은 본문 길이. `OTEL_LOG_RAW_API_BODIES=file:<dir>`일 때 UTF-8 바이트, 또는 `=1`일 때 UTF-16 코드 단위970* `body_length`: 잘리지 않은 본문 길이. `OTEL_LOG_RAW_API_BODIES=file:<dir>`일 때 UTF-8 바이트, 또는 `=1`일 때 UTF-16 코드 단위

955* `body_truncated`: 인라인 잘림이 발생했을 때 `"true"`. 파일 모드 및 잘림이 발생하지 않았을 때 없음.971* `body_truncated`: 인라인 잘림이 발생했을 때 `"true"`. 파일 모드 및 잘림이 발생하지 않았을 때 없음.

956* `model`: 요청 매개변수의 모델 식별자972* `model`: 요청 매개변수의 모델 식별자

957* `query_source`: 요청을 발급한 하위 시스템 (예: `"compact"`)973* `query_source`: 요청을 발급한 하위 시스템 (예: `"compact"`)

958* `request_body_id`: 이 시도의 요청 본문을 식별하는 UUID. 성공한 시도의 [`api_response_body` 이벤트](#api-response-body-event)는 동일한 값을 전달하므로, 응답을 생성한 정확한 요청과 쌍으로 만들 수 있습니다. Claude Code v2.1.274 이상 필요974* `request_body_id`: 이 시도의 요청 본문을 식별하는 UUID. 성공한 시도의 [`api_response_body` 이벤트](#api-response-body-event)는 동일한 값을 전달하므로 응답을 생성한 정확한 요청과 쌍으로 만들 수 있습니다. Claude Code v2.1.274 이상 필요

959 975

960<h4 id="api-response-body-event">976<h4 id="api-response-body-event">

961 API 응답 본문 이벤트977 API 응답 본문 이벤트

963 979

964`OTEL_LOG_RAW_API_BODIES`가 설정되었을 때 각 성공적인 API 응답에 대해 기록됩니다.980`OTEL_LOG_RAW_API_BODIES`가 설정되었을 때 각 성공적인 API 응답에 대해 기록됩니다.

965 981

966파일 모드(`OTEL_LOG_RAW_API_BODIES=file:<dir>`)에서, Claude Code는 또한 각 성공적인 응답에 대해 `<dir>/index.jsonl`에 하나의 JSON 라인을 추가하며, `timestamp`, `session_id`, `query_source`, `model`, `request_id`, `message_id`, `message_uuid`, `request_file`, `response_file` 필드를 포함합니다. 이를 읽어 원격 측정 백엔드를 쿼리하지 않고 주어진 기록 메시지 뒤의 요청 및 응답 파일을 찾습니다. 인덱스 파일은 Claude Code v2.1.274 이상 필요.982파일 모드 (`OTEL_LOG_RAW_API_BODIES=file:<dir>`)에서 Claude Code는 또한 각 성공적인 응답에 대해 `<dir>/index.jsonl`에 하나의 JSON 라인을 추가하며, `timestamp`, `session_id`, `query_source`, `model`, `request_id`, `message_id`, `message_uuid`, `request_file`, `response_file` 필드를 포함합니다. 이를 읽어 원격 측정 백엔드를 쿼리하지 않고 주어진 기록 메시지 뒤의 요청 및 응답 파일을 찾으세요. 인덱스 파일은 Claude Code v2.1.274 이상 필요.

967 983

968**이벤트 이름**: `claude_code.api_response_body`984**이벤트 이름**: `claude_code.api_response_body`

969 985

972* 모든 [표준 속성](#standard-attributes)988* 모든 [표준 속성](#standard-attributes)

973* `event.name`: `"api_response_body"`989* `event.name`: `"api_response_body"`

974* `event.timestamp`: ISO 8601 타임스탬프990* `event.timestamp`: ISO 8601 타임스탬프

975* `event.sequence`: 이벤트 순서 지정을 위한 프로세스당 카운터, [이벤트 상관 속성](#event-correlation-attributes)에서 설명됨991* `event.sequence`: [이벤트 상관 속성](#event-correlation-attributes)에서 설명한 이벤트 순서 지정을 위한 프로세스당 카운터

976* `body`: JSON 직렬화된 Messages API 응답, id, 콘텐츠 블록, 사용량, 중지 이유 포함, 콘텐츠 제한(기본값 60 KB)에서 잘림. 확장 사고 콘텐츠는 수정됨. 인라인 모드(`OTEL_LOG_RAW_API_BODIES=1`)에서만 내보내짐.992* `body`: JSON 직렬화된 Messages API 응답, id, 콘텐츠 블록, 사용량, 중지 이유 포함, 콘텐츠 제한에서 잘림 (기본값 60 KB). 확장 사고 콘텐츠는 수정됨. 인라인 모드에서만 내보냄 (`OTEL_LOG_RAW_API_BODIES=1`).

977* `body_ref`: 잘리지 않은 본문을 포함하는 `<dir>/<request_id>.response.json` 파일의 절대 경로. 파일 모드(`OTEL_LOG_RAW_API_BODIES=file:<dir>`)에서만 내보내짐.993* `body_ref`: 잘리지 않은 본문을 포함하는 `<dir>/<request_id>.response.json` 파일의 절대 경로. 파일 모드에서만 내보냄 (`OTEL_LOG_RAW_API_BODIES=file:<dir>`).

978* `body_length`: 잘리지 않은 본문 길이. `OTEL_LOG_RAW_API_BODIES=file:<dir>`일 때 UTF-8 바이트, 또는 `=1`일 때 UTF-16 코드 단위994* `body_length`: 잘리지 않은 본문 길이. `OTEL_LOG_RAW_API_BODIES=file:<dir>`일 때 UTF-8 바이트, 또는 `=1`일 때 UTF-16 코드 단위

979* `body_truncated`: 인라인 잘림이 발생했을 때 `"true"`. 파일 모드 및 잘림이 발생하지 않았을 때 없음.995* `body_truncated`: 인라인 잘림이 발생했을 때 `"true"`. 파일 모드 및 잘림이 발생하지 않았을 때 없음.

980* `model`: 모델 식별자996* `model`: 모델 식별자

981* `query_source`: 요청을 발급한 하위 시스템997* `query_source`: 요청을 발급한 하위 시스템

982* `request_id`: `"req_011..."`과 같은 API 요청 ID, [이벤트 상관 속성](#event-correlation-attributes)에서 설명됨.998* `request_id`: `"req_011..."`과 같은 API 요청 ID, [이벤트 상관 속성](#event-correlation-attributes)에서 설명함.

983* `request_body_id`: 이 응답이 답변하는 [`api_request_body` 이벤트](#api-request-body-event)의 `request_body_id`. Claude Code v2.1.274 이상 필요999* `request_body_id`: 이 응답이 답변하는 [`api_request_body` 이벤트](#api-request-body-event)의 `request_body_id`. Claude Code v2.1.274 이상 필요

984* `message.id`: API가 응답에 할당한 메시지 ID, 응답 본문의 `id` 필드. Claude Code v2.1.274 이상 필요1000* `message.id`: API가 응답에 할당한 메시지 ID, 응답 본문의 `id` 필드. Claude Code v2.1.274 이상 필요

985* `message.uuid`: 응답의 최종 기록 항목의 UUID. `request_body_id`와 함께, 기록 메시지를 뒤의 요청 및 응답 본문에 연결합니다. Claude Code v2.1.274 이상 필요1001* `message.uuid`: 응답의 최종 기록 항목의 UUID. `request_body_id`와 함께 기록 메시지를 뒤의 요청 및 응답 본문에 연결합니다. Claude Code v2.1.274 이상 필요

986 1002

987<h4 id="tool-decision-event">1003<h4 id="tool-decision-event">

988 도구 결정 이벤트1004 도구 결정 이벤트

989</h4>1005</h4>

990 1006

991도구 권한 결정이 내려질 때 기록됩니다 (수락/거부).1007도구 권한 결정이 내려질 때 (수락/거부) 기록됩니다.

992 1008

993**이벤트 이름**: `claude_code.tool_decision`1009**이벤트 이름**: `claude_code.tool_decision`

994 1010

997* 모든 [표준 속성](#standard-attributes)1013* 모든 [표준 속성](#standard-attributes)

998* `event.name`: `"tool_decision"`1014* `event.name`: `"tool_decision"`

999* `event.timestamp`: ISO 8601 타임스탬프1015* `event.timestamp`: ISO 8601 타임스탬프

1000* `event.sequence`: 이벤트 순서 지정을 위한 프로세스당 카운터, [이벤트 상관 속성](#event-correlation-attributes)에서 설명됨1016* `event.sequence`: [이벤트 상관 속성](#event-correlation-attributes)에서 설명한 이벤트 순서 지정을 위한 프로세스당 카운터

1001* `tool_name`: 도구의 이름 (예: "Read", "Edit", "Write", "NotebookEdit")1017* `tool_name`: 도구의 이름 (예: "Read", "Edit", "Write", "NotebookEdit")

1002* `tool_use_id`: 이 도구 호출의 고유 식별자. 훅에 전달된 `tool_use_id`와 일치하여 OTel 이벤트와 훅 캡처 데이터 간의 상관 관계를 허용합니다.1018* `tool_use_id`: 이 도구 호출의 고유 식별자. 훅에 전달된 `tool_use_id`와 일치하여 OTel 이벤트와 훅 캡처 데이터 간의 상관 관계를 허용합니다.

1003* `decision`: `"accept"` 또는 `"reject"`1019* `decision`: `"accept"` 또는 `"reject"`

1004* `tool_source`: 항상 존재합니다. 도구의 출처, CLI 작성 값의 폐쇄 집합으로. Claude Code v2.1.214 이상 필요1020* `tool_source`: 항상 존재. 도구의 출처, CLI 작성 값의 폐쇄 집합으로. Claude Code v2.1.214 이상 필요

1005 * `"builtin"`: CLI 자체의 도구1021 * `"builtin"`: CLI 자체의 도구

1006 * `"mcp"`: 일반적으로 MCP 서버1022 * `"mcp"`: 일반적으로 MCP 서버

1007 * `"sdk_host_builtin_mcp"`: Claude Desktop 자체에 내장된 프로세스 내 서버, Claude Desktop이 소유한 세션에서. Claude Desktop은 자신의 진입점 중 하나에서 시작한 세션을 소유합니다, `claude-desktop`, `claude-desktop-3p`, 또는 `local-agent`, 해당 세션이 중첩된 자식이 아닐 때; 중첩된 세션(Claude Code 자체가 생성하는 세션 포함)은 이러한 서버를 `"mcp"`로 보고합니다1023 * `"sdk_host_builtin_mcp"`: Claude Desktop 자체에 내장된 프로세스 내 서버, Claude Desktop이 소유한 세션에서. Claude Desktop은 자신의 진입점 중 하나에서 시작한 세션을 소유합니다, `claude-desktop`, `claude-desktop-3p`, 또는 `local-agent`, 해당 세션이 중첩된 자식이 아닐 때; 중첩된 세션(Claude Code 자체가 생성하는 세션 포함)은 이러한 서버를 `"mcp"`로 보고합니다

1008* `source`: 결정이 나온 위치:1024* `source`: 결정이 나온 위치:

1009 * `"config"`: 프롬프트 없이 자동으로 결정됨, 프로젝트 설정, 사용자의 개인 설정의 허용 또는 거부 규칙, 엔터프라이즈 관리 정책, `--allowedTools` 또는 `--disallowedTools` 플래그, 활성 권한 모드, 동일한 대화형 CLI 세션의 이전 프롬프트의 세션 범위 권한 부여, 또는 도구가 본질적으로 안전하기 때문에 기반합니다. 이벤트는 이러한 소스 중 어느 것이 일치했는지 나타내지 않습니다. Claude Code는 또한 권한 프롬프트 요청 자체가 실패할 때 `"config"`을 보고합니다, 예를 들어 Agent SDK의 [`canUseTool`](/docs/ko/agent-sdk/typescript#canusetool) 콜백 또는 [`--permission-prompt-tool`](/docs/ko/cli-reference#cli-flags) 도구가 잘못된 결과를 반환할 때, 또는 요청이 보류 중일 때 입력 스트림이 닫힐 때. v2.1.216 이전에는 Claude Code가 이러한 실패를 `"user_reject"`로 보고했습니다.1025 * `"config"`: 프롬프트 없이 자동으로 결정됨, 프로젝트 설정, 사용자의 개인 설정의 허용 또는 거부 규칙, 엔터프라이즈 관리 정책, `--allowedTools` 또는 `--disallowedTools` 플래그, 활성 권한 모드, 동일한 대화형 CLI 세션의 이전 프롬프트에서 세션 범위 부여, 또는 도구가 본질적으로 안전하기 때문에 기반. 이벤트는 이러한 소스 중 어느 것이 일치했는지 나타내지 않습니다. Claude Code는 또한 권한 프롬프트 요청 자체가 실패할 때 `"config"`을 보고합니다, 예를 들어 Agent SDK의 [`canUseTool`](/docs/ko/agent-sdk/typescript#canusetool) 콜백 또는 [`--permission-prompt-tool`](/docs/ko/cli-reference#cli-flags) 도구가 유효하지 않은 결과를 반환할 때, 또는 요청이 보류 중일 때 입력 스트림이 닫힐 때. v2.1.216 이전에는 Claude Code가 이러한 실패를 `"user_reject"`로 보고했습니다.

1010 * `"hook"`: `PreToolUse` 또는 `PermissionRequest` 훅이 결정을 반환했습니다.1026 * `"hook"`: `PreToolUse` 또는 `PermissionRequest` 훅이 결정을 반환했습니다.

1011 * `"user_permanent"`: 사용자가 권한 프롬프트에서 "예, 다시 묻지 마세요 ..." 를 선택했을 때 내보내짐, 이는 개인 설정에 허용 규칙을 저장합니다. 대화형 CLI에서 이는 해당 선택 자체에 대해서만 내보내집니다; 나중에 저장된 규칙과 일치하는 호출은 대신 `"config"`을 내보냅니다. Agent SDK 또는 비대화형 `-p` 세션에서, 초기 선택과 나중의 규칙 일치 모두 `"user_permanent"`를 내보냅니다. 수락으로 취급됩니다.1027 * `"user_permanent"`: 사용자가 권한 프롬프트에서 "Yes, and don't ask again for ..."을 선택했을 때 내보냄, 이는 개인 설정에 허용 규칙을 저장합니다. 대화형 CLI에서 이는 해당 선택 자체에 대해서만 내보냄; 나중의 호출이 저장된 규칙과 일치하면 `"config"`을 대신 내보냅니다. Agent SDK 또는 비대화형 `-p` 세션에서 초기 선택과 나중의 규칙 일치 모두 `"user_permanent"`를 내보냅니다. 수락으로 취급됨.

1012 * `"user_temporary"`: 사용자가 권한 프롬프트에서 "예"를 선택했을 때 내보내짐, 일회성 승인의 경우, 또는 파일 편집 또는 읽기 프롬프트에서 세션의 나머지 부분에 대한 액세스를 부여하는 옵션을 선택했을 때. 대화형 CLI에서 이는 선택 자체에 대해서만 내보내집니다; 나중에 해당 세션 범위 권한 부여와 일치하는 호출은 대신 `"config"`을 내보냅니다. Agent SDK 또는 비대화형 `-p` 세션에서, 선택과 나중의 일치 모두 `"user_temporary"`를 내보냅니다. 수락으로 취급됩니다.1028 * `"user_temporary"`: 사용자가 권한 프롬프트에서 "Yes"를 선택했을 때 또는 파일 편집 또는 읽기 프롬프트에서 세션의 나머지 부분에 대한 액세스를 부여하는 옵션을 선택했을 때 내보냄. 대화형 CLI에서 이는 선택 자체에 대해서만 내보냄; 나중의 호출이 해당 세션 범위 부여와 일치하면 `"config"`을 대신 내보냅니다. Agent SDK 또는 비대화형 `-p` 세션에서 선택과 나중의 일치 모두 `"user_temporary"`를 내보냅니다. 수락으로 취급됨.

1013 * `"user_abort"`: 사용자가 답변 없이 권한 프롬프트를 해제했을 때 내보내짐. Agent SDK 및 비대화형 `-p` 세션에서, 이는 `canUseTool` 또는 `--permission-prompt-tool` 권한 요청이 보류 중일 때 턴을 중단하는 것을 포함합니다; v2.1.216 이전에는 Claude Code가 해당 중단을 `"user_reject"`로 보고했습니다. 거부로 취급됩니다.1029 * `"user_abort"`: 사용자가 답변 없이 권한 프롬프트를 해제했을 때 내보냄. Agent SDK 및 비대화형 `-p` 세션에서 이는 `canUseTool` 또는 `--permission-prompt-tool` 권한 요청이 보류 중일 때 턴을 중단하는 것을 포함합니다; v2.1.216 이전에는 Claude Code가 해당 중단을 `"user_reject"`로 보고했습니다. 거부로 취급됨.

1014 * `"user_reject"`: 사용자가 프롬프트에서 "아니오"를 선택했을 때 내보내짐. 대화형 CLI에서 이는 해당 선택 자체에 대해서만 내보내집니다; 사용자의 개인 설정의 거부 규칙과 일치하는 호출은 대신 `"config"`을 내보냅니다. Agent SDK 또는 비대화형 `-p` 세션에서, 개인 설정의 거부 규칙과 일치하는 호출은 `"user_reject"`를 내보냅니다. 거부로 취급됩니다.1030 * `"user_reject"`: 사용자가 프롬프트에서 "No"를 선택했을 때 내보냄. 대화형 CLI에서 이는 해당 선택 자체에 대해서만 내보냄; 사용자의 개인 설정의 거부 규칙과 일치하는 호출은 `"config"`을 대신 내보냅니다. Agent SDK 또는 비대화형 `-p` 세션에서 개인 설정의 거부 규칙과 일치하는 호출은 `"user_reject"`를 내보냅니다. 거부로 취급됨.

1015* `tool_parameters` (`OTEL_LOG_TOOL_DETAILS=1`일 때): 도구별 매개변수를 포함하는 JSON 문자열. [도구 결과 이벤트](#tool-result-event)와 동일한 형태, `git_commit_id`와 같은 실행 후 필드 제외. 권한 결정이 `updatedInput`을 통해 도구 입력을 다시 쓸 경우 수락된 호출의 `tool_result`와 값이 다를 수 있습니다. 이 속성을 사용하여 `decision`이 `"reject"`일 때 어느 명령이 거부되었는지 확인합니다.1031* `tool_parameters` (`OTEL_LOG_TOOL_DETAILS=1`일 때): 도구별 매개변수를 포함하는 JSON 문자열. [도구 결과 이벤트](#tool-result-event)와 동일한 형태, `git_commit_id`와 같은 실행 후 필드 제외. 수락된 호출의 경우 `tool_result`와 다를 수 있습니다 (권한 결정이 `updatedInput`을 통해 도구 입력을 다시 쓸 경우). 이 속성을 사용하여 `decision`이 `"reject"`일 때 어느 명령이 거부되었는지 확인하세요.

1016 * `"sdk_host_builtin_mcp"` 도구의 경우: `mcp_server_name` 및 `mcp_tool_name`은 `OTEL_LOG_TOOL_DETAILS`가 꺼져 있어도 포함됩니다, 호스트 애플리케이션이 이러한 이름을 정의하기 때문입니다; 이들 없이, 이러한 기본 제공 서버 중 하나에 대한 거부된 호출은 기본 스트림에서 속성화할 수 없습니다. 사용자 구성 MCP 서버의 경우, 이벤트의 `tool_name`은 항상 리터럴 `"mcp_tool"`이고, 서버 및 도구 이름은 플래그가 켜져 있을 때만 `tool_parameters`에 나타납니다; 인수 콘텐츠는 어디서나 플래그가 필요합니다. Claude Code v2.1.214 이상 필요1032 * `"sdk_host_builtin_mcp"` 도구의 경우: `mcp_server_name` 및 `mcp_tool_name`은 `OTEL_LOG_TOOL_DETAILS`가 꺼져 있어도 포함됩니다, 호스트 애플리케이션이 이러한 이름을 정의하기 때문; 이들 없이 이러한 기본 제공 서버 중 하나에 대한 거부된 호출은 기본 스트림에서 속성화할 수 없습니다. 사용자 구성 MCP 서버의 경우 이벤트의 `tool_name`은 항상 리터럴 `"mcp_tool"`이며, 서버 및 도구 이름은 플래그가 켜져 있을 때만 `tool_parameters`에 나타납니다; 인수 콘텐츠는 어디서나 플래그가 필요합니다. Claude Code v2.1.214 이상 필요

1017 * Bash 도구의 경우: `bash_command`, `full_command`, `timeout`, `description`, `dangerouslyDisableSandbox` 포함. 데스크톱 앱의 작업 공간 bash 도구도 `tool_name`을 `Bash`로 보고하지만, `bash_command`, `full_command`, `timeout`만 포함합니다1033 * Bash 도구의 경우: `bash_command`, `full_command`, `timeout`, `description`, `dangerouslyDisableSandbox` 포함. 데스크톱 앱의 작업 공간 bash 도구도 `tool_name`을 `Bash`로 보고하지만 `bash_command`, `full_command`, `timeout`만 포함합니다

1018 * MCP 도구의 경우: `mcp_server_name`, `mcp_tool_name` 포함1034 * MCP 도구의 경우: `mcp_server_name`, `mcp_tool_name` 포함

1019 * Skill 도구의 경우: `skill_name` 포함1035 * Skill 도구의 경우: `skill_name` 포함

1020 * Agent 도구 또는 레거시 Task 도구의 경우: `subagent_type` 포함1036 * Agent 도구 또는 레거시 Task 도구의 경우: `subagent_type` 포함

1032* 모든 [표준 속성](#standard-attributes)1048* 모든 [표준 속성](#standard-attributes)

1033* `event.name`: `"permission_mode_changed"`1049* `event.name`: `"permission_mode_changed"`

1034* `event.timestamp`: ISO 8601 타임스탬프1050* `event.timestamp`: ISO 8601 타임스탬프

1035* `event.sequence`: 이벤트 순서 지정을 위한 프로세스당 카운터, [이벤트 상관 속성](#event-correlation-attributes)에서 설명됨1051* `event.sequence`: [이벤트 상관 속성](#event-correlation-attributes)에서 설명한 이벤트 순서 지정을 위한 프로세스당 카운터

1036* `from_mode`: 이전 권한 모드, 예: `"default"`, `"plan"`, `"acceptEdits"`, `"auto"`, 또는 `"bypassPermissions"`1052* `from_mode`: 이전 권한 모드, 예: `"default"`, `"plan"`, `"acceptEdits"`, `"auto"`, 또는 `"bypassPermissions"`

1037* `to_mode`: 새로운 권한 모드1053* `to_mode`: 새로운 권한 모드

1038* `trigger`: 변경을 유발한 것. `"shift_tab"`, `"exit_plan_mode"`, `"auto_gate_denied"`, 또는 `"auto_opt_in"` 중 하나. SDK 또는 브리지에서 전환이 시작될 때 없음.1054* `trigger`: 변경을 야기한 것. `"shift_tab"`, `"exit_plan_mode"`, `"auto_gate_denied"`, 또는 `"auto_opt_in"` 중 하나. 전환이 SDK 또는 브리지에서 시작될 때 없음.

1039 1055

1040<h4 id="auth-event">1056<h4 id="auth-event">

1041 인증 이벤트1057 인증 이벤트

1050* 모든 [표준 속성](#standard-attributes)1066* 모든 [표준 속성](#standard-attributes)

1051* `event.name`: `"auth"`1067* `event.name`: `"auth"`

1052* `event.timestamp`: ISO 8601 타임스탬프1068* `event.timestamp`: ISO 8601 타임스탬프

1053* `event.sequence`: 이벤트 순서 지정을 위한 프로세스당 카운터, [이벤트 상관 속성](#event-correlation-attributes)에서 설명됨1069* `event.sequence`: [이벤트 상관 속성](#event-correlation-attributes)에서 설명한 이벤트 순서 지정을 위한 프로세스당 카운터

1054* `action`: `"login"` 또는 `"logout"`1070* `action`: `"login"` 또는 `"logout"`

1055* `success`: `"true"` 또는 `"false"`1071* `success`: `"true"` 또는 `"false"`

1056* `auth_method`: 인증 방법, 예: `"oauth"`1072* `auth_method`: 인증 방법, 예: `"oauth"`

1057* `error_category`: 작업이 실패했을 때 범주별 오류 종류. 원시 오류 메시지는 절대 포함되지 않습니다1073* `error_category`: 작업이 실패했을 때 범주별 오류 종류. 원시 오류 메시지는 절대 포함되지 않습니다

1058* `status_code`: 작업이 HTTP 오류로 실패했을 때 HTTP 상태 코드를 문자열로1074* `status_code`: 작업이 HTTP 오류로 실패했을 때 HTTP 상태 코드 (문자열)

1059 1075

1060<h4 id="mcp-server-connection-event">1076<h4 id="mcp-server-connection-event">

1061 MCP 서버 연결 이벤트1077 MCP 서버 연결 이벤트

1070* 모든 [표준 속성](#standard-attributes)1086* 모든 [표준 속성](#standard-attributes)

1071* `event.name`: `"mcp_server_connection"`1087* `event.name`: `"mcp_server_connection"`

1072* `event.timestamp`: ISO 8601 타임스탬프1088* `event.timestamp`: ISO 8601 타임스탬프

1073* `event.sequence`: 이벤트 순서 지정을 위한 프로세스당 카운터, [이벤트 상관 속성](#event-correlation-attributes)에서 설명됨1089* `event.sequence`: [이벤트 상관 속성](#event-correlation-attributes)에서 설명한 이벤트 순서 지정을 위한 프로세스당 카운터

1074* `status`: `"connected"`, `"failed"`, 또는 `"disconnected"`1090* `status`: `"connected"`, `"failed"`, 또는 `"disconnected"`

1075* `transport_type`: 서버 전송, 예: `"stdio"`, `"sse"`, 또는 `"http"`1091* `transport_type`: 서버 전송, 예: `"stdio"`, `"sse"`, 또는 `"http"`

1076* `server_scope`: 서버가 구성된 범위, 예: `"user"`, `"project"`, 또는 `"local"`1092* `server_scope`: 서버가 구성된 범위, 예: `"user"`, `"project"`, 또는 `"local"`

1077* `duration_ms`: 밀리초 단위의 연결 시도 기간1093* `duration_ms`: 연결 시도 지속 시간 (밀리초)

1078* `error_code`: 연결이 실패했을 때 오류 코드1094* `error_code`: 연결이 실패했을 때 오류 코드

1079* `is_plugin`: 서버가 플러그인에 의해 제공될 때 `true`, 그 외의 경우 `false`1095* `is_plugin`: 서버가 플러그인에 의해 제공될 때 `true`, 그 외의 경우 `false`

1080* `plugin_id_hash` (`is_plugin`이 `true`일 때): 플러그인 이름과 마켓플레이스의 안정적인 해시, 이름을 노출하지 않고 플러그인별로 이벤트를 그룹화합니다. Claude Code는 [플러그인 로드 이벤트](#plugin-loaded-event)에서 설명한 대로 계산합니다.1096* `plugin_id_hash` (`is_plugin`이 `true`일 때): 플러그인 이름과 마켓플레이스의 안정적인 해시, 이름을 노출하지 않고 플러그인별 이벤트를 그룹화하기 위해. Claude Code는 [플러그인 로드 이벤트](#plugin-loaded-event)에서 설명한 대로 계산합니다.

1081* `plugin.name` (`is_plugin`이 `true`일 때): 서버를 제공하는 플러그인의 이름. 타사 플러그인의 경우 `OTEL_LOG_TOOL_DETAILS=1`이 아니면 리터럴 문자열 `"third-party"`입니다; 이는 기본적으로 타사 플러그인 이름이 로그에 나타나는 것을 방지합니다. 공식 Anthropic 소스의 플러그인은 항상 이름으로 식별됩니다. `plugin_id_hash` 및 `plugin.name` 속성은 자신의 모니터링 백엔드로 흐르며 Anthropic으로 전송되지 않습니다1097* `plugin.name` (`is_plugin`이 `true`일 때): 서버를 제공하는 플러그인의 이름. 타사 플러그인의 경우 `OTEL_LOG_TOOL_DETAILS=1`이 아닌 경우 리터럴 문자열 `"third-party"`; 이는 기본적으로 로그에 나타나는 타사 플러그인 이름을 보호합니다. 공식 Anthropic 소스의 플러그인은 항상 이름으로 식별됩니다. `plugin_id_hash` 및 `plugin.name` 속성은 자신의 모니터링 백엔드로 흐르며 Anthropic으로 전송되지 않습니다

1082* `server_name` (`OTEL_LOG_TOOL_DETAILS=1`일 때): 구성된 서버 이름1098* `server_name` (`OTEL_LOG_TOOL_DETAILS=1`일 때): 구성된 서버 이름

1083* `error` (`OTEL_LOG_TOOL_DETAILS=1`일 때): 연결이 실패했을 때 전체 오류 메시지1099* `error` (`OTEL_LOG_TOOL_DETAILS=1`일 때): 연결이 실패했을 때 전체 오류 메시지

1084 1100

1095* 모든 [표준 속성](#standard-attributes)1111* 모든 [표준 속성](#standard-attributes)

1096* `event.name`: `"internal_error"`1112* `event.name`: `"internal_error"`

1097* `event.timestamp`: ISO 8601 타임스탬프1113* `event.timestamp`: ISO 8601 타임스탬프

1098* `event.sequence`: 이벤트 순서 지정을 위한 프로세스당 카운터, [이벤트 상관 속성](#event-correlation-attributes)에서 설명됨1114* `event.sequence`: [이벤트 상관 속성](#event-correlation-attributes)에서 설명한 이벤트 순서 지정을 위한 프로세스당 카운터

1099* `error_name`: 오류 클래스 이름, 예: `"TypeError"` 또는 `"SyntaxError"`1115* `error_name`: 오류 클래스 이름, 예: `"TypeError"` 또는 `"SyntaxError"`

1100* `error_code`: 오류에 존재할 때 `"ENOENT"`와 같은 Node.js errno 코드1116* `error_code`: 오류에 있을 때 Node.js errno 코드, 예: `"ENOENT"`

1101 1117

1102<h4 id="plugin-installed-event">1118<h4 id="plugin-installed-event">

1103 플러그인 설치 이벤트1119 플러그인 설치 이벤트

1112* 모든 [표준 속성](#standard-attributes)1128* 모든 [표준 속성](#standard-attributes)

1113* `event.name`: `"plugin_installed"`1129* `event.name`: `"plugin_installed"`

1114* `event.timestamp`: ISO 8601 타임스탬프1130* `event.timestamp`: ISO 8601 타임스탬프

1115* `event.sequence`: 이벤트 순서 지정을 위한 프로세스당 카운터, [이벤트 상관 속성](#event-correlation-attributes)에서 설명됨1131* `event.sequence`: [이벤트 상관 속성](#event-correlation-attributes)에서 설명한 이벤트 순서 지정을 위한 프로세스당 카운터

1116* `marketplace.is_official`: 마켓플레이스가 공식 Anthropic 마켓플레이스이면 `"true"`, 그 외의 경우 `"false"`1132* `marketplace.is_official`: 마켓플레이스가 공식 Anthropic 마켓플레이스일 때 `"true"`, 그 외의 경우 `"false"`

1117* `install.trigger`: `"cli"` 또는 `"ui"`1133* `install.trigger`: `"cli"` 또는 `"ui"`

1118* `plugin.name`: 설치된 플러그인의 이름. 타사 마켓플레이스의 경우 `OTEL_LOG_TOOL_DETAILS=1`일 때만 포함됨1134* `plugin.name`: 설치된 플러그인의 이름. 타사 마켓플레이스의 경우 `OTEL_LOG_TOOL_DETAILS=1`일 때만 포함됨

1119* `plugin.version`: 마켓플레이스 항목에서 선언된 경우 플러그인 버전. 타사 마켓플레이스의 경우 `OTEL_LOG_TOOL_DETAILS=1`일 때만 포함됨1135* `plugin.version`: 마켓플레이스 항목에서 선언된 경우 플러그인 버전. 타사 마켓플레이스의 경우 `OTEL_LOG_TOOL_DETAILS=1`일 때만 포함됨

1123 플러그인 로드 이벤트1139 플러그인 로드 이벤트

1124</h4>1140</h4>

1125 1141

1126세션 시작 시 활성화된 플러그인당 한 번 기록됩니다. 이 이벤트를 사용하여 플릿 전체에서 활성화된 플러그인을 인벤토리하세요, 설치 작업 자체를 기록하는 `plugin_installed`의 보완으로.1142세션 시작 시 활성화된 플러그인당 한 번 기록됩니다. 이 이벤트를 사용하여 설치 작업 자체를 기록하는 `plugin_installed`를 보완하여 플릿 전체에서 활성화된 플러그인을 인벤토리하세요.

1127 1143

1128**이벤트 이름**: `claude_code.plugin_loaded`1144**이벤트 이름**: `claude_code.plugin_loaded`

1129 1145

1132* 모든 [표준 속성](#standard-attributes)1148* 모든 [표준 속성](#standard-attributes)

1133* `event.name`: `"plugin_loaded"`1149* `event.name`: `"plugin_loaded"`

1134* `event.timestamp`: ISO 8601 타임스탬프1150* `event.timestamp`: ISO 8601 타임스탬프

1135* `event.sequence`: 이벤트 순서 지정을 위한 프로세스당 카운터, [이벤트 상관 속성](#event-correlation-attributes)에서 설명됨1151* `event.sequence`: [이벤트 상관 속성](#event-correlation-attributes)에서 설명한 이벤트 순서 지정을 위한 프로세스당 카운터

1136* `plugin.name`: 플러그인의 이름. 공식 마켓플레이스 및 기본 제공 번들 외부의 플러그인의 경우 `OTEL_LOG_TOOL_DETAILS=1`이 아니면 `"third-party"`1152* `plugin.name`: 플러그인의 이름. 공식 마켓플레이스 및 기본 제공 번들 외부의 플러그인의 경우 `OTEL_LOG_TOOL_DETAILS=1`이 아닌 경우 값은 `"third-party"`

1137* `marketplace.name`: 플러그인이 설치된 마켓플레이스, 알려진 경우. `plugin.name`과 동일한 조건에서 `"third-party"`로 수정됨1153* `marketplace.name`: 플러그인이 설치된 마켓플레이스 (알려진 경우). `plugin.name`과 동일한 조건에서 `"third-party"`로 수정됨

1138* `plugin.version`: 플러그인 매니페스트의 버전. 이름이 수정되지 않고 매니페스트가 버전을 선언할 때만 포함됨1154* `plugin.version`: 플러그인 매니페스트의 버전. 이름이 수정되지 않고 매니페스트가 버전을 선언할 때만 포함됨

1139* `plugin.scope`: 플러그인의 출처 범주: `"official"`, `"community"`, `"org"`, `"user-local"`, 또는 `"default-bundle"`1155* `plugin.scope`: 플러그인의 출처 범주: `"official"`, `"community"`, `"org"`, `"user-local"`, 또는 `"default-bundle"`

1140* `enabled_via`: 플러그인이 활성화되는 방식: `"default-enable"`, `"org-policy"`, `"admin-install"`, `"seed-mount"`, 또는 `"user-install"`. `"admin-install"` 값은 플러그인이 [**조직 설정 > 플러그인 & 스킬**](https://claude.ai/admin-settings/skills?tab=inventory)에서 조직에 필수 또는 자동 설치로 설정되어 있음을 의미합니다. v2.1.246 이전에는 Claude Code가 이러한 플러그인을 `"user-install"` 또는 `"seed-mount"`로 보고했습니다1156* `enabled_via`: 플러그인이 활성화되게 된 방식: `"default-enable"`, `"org-policy"`, `"admin-install"`, `"seed-mount"`, 또는 `"user-install"`. `"admin-install"` 값은 플러그인이 [**조직 설정 > 플러그인 & 스킬**](https://claude.ai/admin-settings/skills?tab=inventory)에서 조직에 필수 또는 자동 설치로 설정되어 있음을 의미합니다. v2.1.246 이전에는 Claude Code가 이러한 플러그인을 `"user-install"` 또는 `"seed-mount"`로 보고했습니다

1141* `plugin_id_hash`: 플러그인 이름과 마켓플레이스의 결정적 해시, 구성된 내보내기로만 전송됨. 이름을 기록하지 않고 플릿 전체에서 로드된 서로 다른 플러그인을 계산할 수 있습니다. [claude.ai에서 동기화된 플러그인](/docs/ko/plugins/loading#synced-plugins)의 경우, Claude Code는 플러그인 이름을 claude.ai가 플러그인에 대해 보고하는 마켓플레이스 이름과 함께 해시하거나, 그 외의 경우 `synced`와 함께 해시합니다. v2.1.246 이전에는 Claude Code가 해시에서 claude.ai가 보고하는 마켓플레이스 이름을 사용하지 않았습니다1157* `plugin_id_hash`: 플러그인 이름과 마켓플레이스의 결정적 해시, 구성된 내보내기로만 전송됨. 이름을 기록하지 않고 플릿 전체에서 로드된 서로 다른 타사 플러그인을 계산할 수 있습니다. [claude.ai에서 동기화된 플러그인](/docs/ko/plugins/loading#synced-plugins)의 경우 Claude Code는 플러그인 이름을 claude.ai가 플러그인에 대해 보고하는 마켓플레이스 이름과 함께 해시하거나, 그 외의 경우 `synced`와 함께 해시합니다. v2.1.246 이전에는 Claude Code가 해시에서 claude.ai가 보고하는 마켓플레이스 이름을 사용하지 않았습니다

1142* `has_hooks`: 플러그인이 훅을 제공하는지 여부1158* `has_hooks`: 플러그인이 훅을 제공하는지 여부

1143* `has_mcp`: 플러그인이 MCP 서버를 제공하는지 여부1159* `has_mcp`: 플러그인이 MCP 서버를 제공하는지 여부

1144* `host_owned_mcp`: SDK 호스트가 이 플러그인의 MCP 연결을 관리하고 Claude Code가 플러그인의 MCP 서버 구성 읽기를 건너뛸 때 `true`, 그 외의 경우 `false`. Claude Code v2.1.172 이상 필요1160* `host_owned_mcp`: SDK 호스트가 이 플러그인의 MCP 연결을 관리하고 Claude Code가 플러그인의 MCP 서버 구성 읽기를 건너뛸 때 `true`, 그 외의 경우 `false`. Claude Code v2.1.172 이상 필요

1145* `skill_path_count`: 플러그인이 선언하는 스킬 디렉토리 수1161* `skill_path_count`: 플러그인이 선언하는 스킬 디렉토리 수

1146* `command_path_count`: 플러그인이 선언하는 명령 디렉토리 수1162* `command_path_count`: 플러그인이 선언하는 명령 디렉토리 수

1147* `agent_path_count`: 플러그인이 선언하는 에이전트 디렉토리 수1163* `agent_path_count`: 플러그인이 선언하는 에이전트 디렉토리 수

1148* `safe_mode`: [`--safe-mode`](/docs/ko/cli-reference)로 세션이 시작되었을 때 `"true"`, 그 외의 경우 `"false"`. 안전 모드에서 이 이벤트는 구성된 인벤토리만 보고합니다; 플러그인의 명령, 스킬, 훅, MCP 서버는 로드되지 않습니다. Claude Code v2.1.169 이상 필요1164* `safe_mode`: 세션이 [`--safe-mode`](/docs/ko/cli-reference)로 시작되었을 때 `"true"`, 그 외의 경우 `"false"`. 안전 모드에서 이 이벤트는 구성된 인벤토리만 보고합니다; 플러그인의 명령, 스킬, 훅, MCP 서버는 로드되지 않습니다. Claude Code v2.1.169 이상 필요

1149 1165

1150<h4 id="skill-activated-event">1166<h4 id="skill-activated-event">

1151 스킬 활성화 이벤트1167 스킬 활성화 이벤트

1160* 모든 [표준 속성](#standard-attributes)1176* 모든 [표준 속성](#standard-attributes)

1161* `event.name`: `"skill_activated"`1177* `event.name`: `"skill_activated"`

1162* `event.timestamp`: ISO 8601 타임스탬프1178* `event.timestamp`: ISO 8601 타임스탬프

1163* `event.sequence`: 이벤트 순서 지정을 위한 프로세스당 카운터, [이벤트 상관 속성](#event-correlation-attributes)에서 설명됨1179* `event.sequence`: [이벤트 상관 속성](#event-correlation-attributes)에서 설명한 이벤트 순서 지정을 위한 프로세스당 카운터

1164* `skill.name`: 스킬의 이름. 사용자 정의 및 타사 플러그인 스킬의 경우 `OTEL_LOG_TOOL_DETAILS=1`이 아니면 자리 표시자 `"custom_skill"`1180* `skill.name`: 스킬의 이름. 사용자 정의 및 타사 플러그인 스킬의 경우 `OTEL_LOG_TOOL_DETAILS=1`이 아닌 경우 값은 자리 표시자 `"custom_skill"`

1165* `invocation_trigger`: 스킬이 트리거된 방식 (`"user-slash"`, `"claude-proactive"`, 또는 `"nested-skill"`)1181* `invocation_trigger`: 스킬이 트리거된 방식 (`"user-slash"`, `"claude-proactive"`, 또는 `"nested-skill"`)

1166* `skill.source`: 스킬이 로드된 위치 (예: `"bundled"`, `"userSettings"`, `"projectSettings"`, `"plugin"`)1182* `skill.source`: 스킬이 로드된 위치 (예: `"bundled"`, `"userSettings"`, `"projectSettings"`, `"plugin"`)

1167* `skill.kind`: 스킬이 워크플로우 스킬일 때 `"workflow"`. 그 외의 경우 없음.1183* `skill.kind`: 스킬이 워크플로우 스킬일 때 `"workflow"`. 그 외의 경우 없음.

1181* 모든 [표준 속성](#standard-attributes)1197* 모든 [표준 속성](#standard-attributes)

1182* `event.name`: `"at_mention"`1198* `event.name`: `"at_mention"`

1183* `event.timestamp`: ISO 8601 타임스탬프1199* `event.timestamp`: ISO 8601 타임스탬프

1184* `event.sequence`: 이벤트 순서 지정을 위한 프로세스당 카운터, [이벤트 상관 속성](#event-correlation-attributes)에서 설명됨1200* `event.sequence`: [이벤트 상관 속성](#event-correlation-attributes)에서 설명한 이벤트 순서 지정을 위한 프로세스당 카운터

1185* `mention_type`: 멘션의 유형 (`"file"`, `"directory"`, `"agent"`, `"mcp_resource"`, `"peer"`). `"peer"` 값은 [다른 Claude Code 세션](/docs/ko/cross-session-messaging) 중 하나를 멘션했음을 의미합니다. Claude Code v2.1.232 이상 필요1201* `mention_type`: 멘션의 유형 (`"file"`, `"directory"`, `"agent"`, `"mcp_resource"`, `"peer"`). `"peer"` 값은 [다른 Claude Code 세션](/docs/ko/cross-session-messaging) 중 하나를 멘션했음을 의미합니다. Claude Code v2.1.232 이상 필요

1186* `success`: 멘션이 성공적으로 해결되었는지 여부 (`"true"` 또는 `"false"`)1202* `success`: 멘션이 성공적으로 해결되었는지 여부 (`"true"` 또는 `"false"`)

1187 1203

1189 API 재시도 소진 이벤트1205 API 재시도 소진 이벤트

1190</h4>1206</h4>

1191 1207

1192API 요청이 두 번 이상 시도 후 실패할 때 한 번 기록됩니다. 최종 `api_error` 이벤트와 함께 내보내집니다.1208API 요청이 둘 이상의 시도 후 실패할 때 한 번 기록됩니다. 최종 `api_error` 이벤트와 함께 내보냄.

1193 1209

1194**이벤트 이름**: `claude_code.api_retries_exhausted`1210**이벤트 이름**: `claude_code.api_retries_exhausted`

1195 1211

1198* 모든 [표준 속성](#standard-attributes)1214* 모든 [표준 속성](#standard-attributes)

1199* `event.name`: `"api_retries_exhausted"`1215* `event.name`: `"api_retries_exhausted"`

1200* `event.timestamp`: ISO 8601 타임스탬프1216* `event.timestamp`: ISO 8601 타임스탬프

1201* `event.sequence`: 이벤트 순서 지정을 위한 프로세스당 카운터, [이벤트 상관 속성](#event-correlation-attributes)에서 설명됨1217* `event.sequence`: [이벤트 상관 속성](#event-correlation-attributes)에서 설명한 이벤트 순서 지정을 위한 프로세스당 카운터

1202* `model`: 사용된 모델1218* `model`: 사용된 모델

1203* `error`: 최종 오류 메시지1219* `error`: 최종 오류 메시지

1204* `status_code`: HTTP 상태 코드를 숫자로. 비 HTTP 오류의 경우 없음.1220* `status_code`: HTTP 상태 코드 (숫자). 비 HTTP 오류의 경우 없음.

1205* `total_attempts`: 수행된 총 시도 횟수1221* `total_attempts`: 수행된 총 시도 횟수

1206* `total_retry_duration_ms`: 모든 시도에 걸친 총 벽시계 시간1222* `total_retry_duration_ms`: 모든 시도에 걸친 총 벽시계 시간

1207* `speed`: `"fast"` 또는 `"normal"`1223* `speed`: `"fast"` 또는 `"normal"`

1210 훅 등록 이벤트1226 훅 등록 이벤트

1211</h4>1227</h4>

1212 1228

1213세션 시작 시 구성된 훅당 한 번 기록됩니다. 이 이벤트를 사용하여 플릿 전체에서 활성화된 훅을 인벤토리하세요, 실행별 `hook_execution_start` 및 `hook_execution_complete` 이벤트의 보완으로.1229세션 시작 시 구성된 훅당 한 번 기록됩니다. 이 이벤트를 사용하여 실행별 `hook_execution_start` 및 `hook_execution_complete` 이벤트를 보완하여 플릿 전체에서 활성화된 훅을 인벤토리하세요.

1214 1230

1215**이벤트 이름**: `claude_code.hook_registered`1231**이벤트 이름**: `claude_code.hook_registered`

1216 1232

1219* 모든 [표준 속성](#standard-attributes)1235* 모든 [표준 속성](#standard-attributes)

1220* `event.name`: `"hook_registered"`1236* `event.name`: `"hook_registered"`

1221* `event.timestamp`: ISO 8601 타임스탬프1237* `event.timestamp`: ISO 8601 타임스탬프

1222* `event.sequence`: 이벤트 순서 지정을 위한 프로세스당 카운터, [이벤트 상관 속성](#event-correlation-attributes)에서 설명됨1238* `event.sequence`: [이벤트 상관 속성](#event-correlation-attributes)에서 설명한 이벤트 순서 지정을 위한 프로세스당 카운터

1223* `hook_event`: 훅 이벤트 유형, 예: `"PreToolUse"` 또는 `"PostToolUse"`1239* `hook_event`: 훅 이벤트 유형, 예: `"PreToolUse"` 또는 `"PostToolUse"`

1224* `hook_type`: 훅 구현 유형: `"command"`, `"prompt"`, `"mcp_tool"`, `"http"`, 또는 `"agent"`1240* `hook_type`: 훅 구현 유형: `"command"`, `"prompt"`, `"mcp_tool"`, `"http"`, 또는 `"agent"`

1225* `hook_source`: 훅이 정의된 위치: `"userSettings"`, `"projectSettings"`, `"localSettings"`, `"flagSettings"`, `"policySettings"`, 또는 `"pluginHook"`1241* `hook_source`: 훅이 정의된 위치: `"userSettings"`, `"projectSettings"`, `"localSettings"`, `"flagSettings"`, `"policySettings"`, 또는 `"pluginHook"`

1226* `safe_mode`: [`--safe-mode`](/docs/ko/cli-reference)로 세션이 시작되었을 때 `"true"`, 그 외의 경우 `"false"`. Claude Code v2.1.169 이상 필요1242* `safe_mode`: 세션이 [`--safe-mode`](/docs/ko/cli-reference)로 시작되었을 때 `"true"`, 그 외의 경우 `"false"`. Claude Code v2.1.169 이상 필요

1227* `hook_matcher` (`OTEL_LOG_TOOL_DETAILS=1`일 때): 훅 구성에서 설정된 경우 훅 구성의 매처 문자열1243* `hook_matcher` (`OTEL_LOG_TOOL_DETAILS=1`일 때): 훅 구성에서 설정된 경우 훅 구성의 매처 문자열

1228* `plugin.name` (`hook_source`가 `"pluginHook"`일 때): 기여하는 플러그인의 이름. 공식 마켓플레이스 및 기본 제공 번들 외부의 플러그인의 경우 `OTEL_LOG_TOOL_DETAILS=1`이 아니면 `"third-party"`1244* `plugin.name` (`hook_source`가 `"pluginHook"`일 때): 기여하는 플러그인의 이름. 공식 마켓플레이스 및 기본 제공 번들 외부의 플러그인의 경우 `OTEL_LOG_TOOL_DETAILS=1`이 아닌 경우 값은 `"third-party"`

1229* `plugin_id_hash` (`hook_source`가 `"pluginHook"`일 때): 플러그인 이름과 마켓플레이스의 결정적 해시, 구성된 내보내기로만 전송됨. 이름을 기록하지 않고 기여하는 서로 다른 플러그인을 계산할 수 있습니다. Claude Code는 [플러그인 로드 이벤트](#plugin-loaded-event)에서 설명한 대로 계산합니다1245* `plugin_id_hash` (`hook_source`가 `"pluginHook"`일 때): 플러그인 이름과 마켓플레이스의 결정적 해시, 구성된 내보내기로만 전송됨. 이름을 기록하지 않고 서로 다른 기여 플러그인을 계산할 수 있습니다. Claude Code는 [플러그인 로드 이벤트](#plugin-loaded-event)에서 설명한 대로 계산합니다

1230 1246

1231<h4 id="hook-execution-start-event">1247<h4 id="hook-execution-start-event">

1232 훅 실행 시작 이벤트1248 훅 실행 시작 이벤트

1241* 모든 [표준 속성](#standard-attributes)1257* 모든 [표준 속성](#standard-attributes)

1242* `event.name`: `"hook_execution_start"`1258* `event.name`: `"hook_execution_start"`

1243* `event.timestamp`: ISO 8601 타임스탬프1259* `event.timestamp`: ISO 8601 타임스탬프

1244* `event.sequence`: 이벤트 순서 지정을 위한 프로세스당 카운터, [이벤트 상관 속성](#event-correlation-attributes)에서 설명됨1260* `event.sequence`: [이벤트 상관 속성](#event-correlation-attributes)에서 설명한 이벤트 순서 지정을 위한 프로세스당 카운터

1245* `hook_event`: 훅 이벤트 유형, 예: `"PreToolUse"` 또는 `"PostToolUse"`1261* `hook_event`: 훅 이벤트 유형, 예: `"PreToolUse"` 또는 `"PostToolUse"`

1246* `hook_name`: 매처를 포함한 전체 훅 이름, 예: `"PreToolUse:Write"`1262* `hook_name`: 매처를 포함한 전체 훅 이름, 예: `"PreToolUse:Write"`

1247* `num_hooks`: 일치하는 훅 명령 수1263* `num_hooks`: 일치하는 훅 명령 수

1248* `managed_only`: 관리 정책 훅만 허용될 때 `"true"`1264* `managed_only`: 관리 정책 훅만 허용될 때 `"true"`

1249* `hook_source`: `"policySettings"` 또는 `"merged"`1265* `hook_source`: `"policySettings"` 또는 `"merged"`

1250* `safe_mode`: [`--safe-mode`](/docs/ko/cli-reference)로 세션이 시작되었을 때 `"true"`, 그 외의 경우 `"false"`. Claude Code v2.1.169 이상 필요1266* `safe_mode`: 세션이 [`--safe-mode`](/docs/ko/cli-reference)로 시작되었을 때 `"true"`, 그 외의 경우 `"false"`. Claude Code v2.1.169 이상 필요

1251* `hook_definitions`: JSON 직렬화된 훅 구성. 상세 베타 추적과 `OTEL_LOG_TOOL_DETAILS=1`이 모두 활성화되었을 때만 포함됨1267* `hook_definitions`: 훅 구성의 JSON 직렬화. 상세 베타 추적과 `OTEL_LOG_TOOL_DETAILS=1`이 모두 활성화되었을 때만 포함됨

1252 1268

1253<h4 id="hook-execution-complete-event">1269<h4 id="hook-execution-complete-event">

1254 훅 실행 완료 이벤트1270 훅 실행 완료 이벤트

1263* 모든 [표준 속성](#standard-attributes)1279* 모든 [표준 속성](#standard-attributes)

1264* `event.name`: `"hook_execution_complete"`1280* `event.name`: `"hook_execution_complete"`

1265* `event.timestamp`: ISO 8601 타임스탬프1281* `event.timestamp`: ISO 8601 타임스탬프

1266* `event.sequence`: 이벤트 순서 지정을 위한 프로세스당 카운터, [이벤트 상관 속성](#event-correlation-attributes)에서 설명됨1282* `event.sequence`: [이벤트 상관 속성](#event-correlation-attributes)에서 설명한 이벤트 순서 지정을 위한 프로세스당 카운터

1267* `hook_event`: 훅 이벤트 유형1283* `hook_event`: 훅 이벤트 유형

1268* `hook_name`: 매처를 포함한 전체 훅 이름1284* `hook_name`: 매처를 포함한 전체 훅 이름

1269* `num_hooks`: 일치하는 훅 명령 수1285* `num_hooks`: 일치하는 훅 명령 수

1271* `num_blocking`: 차단 결정을 반환한 수1287* `num_blocking`: 차단 결정을 반환한 수

1272* `num_non_blocking_error`: 차단 없이 실패한 수1288* `num_non_blocking_error`: 차단 없이 실패한 수

1273* `num_cancelled`: 완료 전에 취소된 수1289* `num_cancelled`: 완료 전에 취소된 수

1274* `total_duration_ms`: 모든 일치하는 훅의 벽시계 기간1290* `total_duration_ms`: 모든 일치하는 훅의 벽시계 지속 시간

1275* `stdout_chars`: 성공한 일치하는 훅 전체의 stdout 총 문자 수. Claude Code v2.1.280 이상 필요1291* `stdout_chars`: 성공한 일치하는 훅 전체의 stdout 총 문자 수. Claude Code v2.1.280 이상 필요

1276* `additional_context_chars`: 일치하는 훅이 반환한 `additionalContext`의 총 문자 수. Claude Code v2.1.280 이상 필요1292* `additional_context_chars`: 일치하는 훅이 반환한 `additionalContext`의 총 문자 수. Claude Code v2.1.280 이상 필요

1277* `system_message_chars`: 일치하는 훅이 반환한 `systemMessage`의 총 문자 수. Claude Code v2.1.280 이상 필요1293* `system_message_chars`: 일치하는 훅이 반환한 `systemMessage`의 총 문자 수. Claude Code v2.1.280 이상 필요

1278* `initial_user_message_chars`: 일치하는 훅이 반환한 `initialUserMessage`의 총 문자 수. Claude Code v2.1.280 이상 필요1294* `initial_user_message_chars`: 일치하는 훅이 반환한 `initialUserMessage`의 총 문자 수. Claude Code v2.1.280 이상 필요

1279* `num_outputs_persisted`: [10,000자 상한](/docs/ko/hooks#json-output)을 초과한 훅 출력 수, Claude Code가 파일에 저장했습니다. Claude Code v2.1.280 이상 필요1295* `num_outputs_persisted`: [10,000자 상한](/docs/ko/hooks#json-output)을 초과한 훅 출력 수, Claude Code가 파일에 저장함. Claude Code v2.1.280 이상 필요

1280* `managed_only`: 관리 정책 훅만 허용될 때 `"true"`1296* `managed_only`: 관리 정책 훅만 허용될 때 `"true"`

1281* `hook_source`: `"policySettings"` 또는 `"merged"`1297* `hook_source`: `"policySettings"` 또는 `"merged"`

1282* `safe_mode`: [`--safe-mode`](/docs/ko/cli-reference)로 세션이 시작되었을 때 `"true"`, 그 외의 경우 `"false"`. Claude Code v2.1.169 이상 필요1298* `safe_mode`: 세션이 [`--safe-mode`](/docs/ko/cli-reference)로 시작되었을 때 `"true"`, 그 외의 경우 `"false"`. Claude Code v2.1.169 이상 필요

1283* `hook_definitions`: JSON 직렬화된 훅 구성. 상세 베타 추적과 `OTEL_LOG_TOOL_DETAILS=1`이 모두 활성화되었을 때만 포함됨1299* `hook_definitions`: 훅 구성의 JSON 직렬화. 상세 베타 추적과 `OTEL_LOG_TOOL_DETAILS=1`이 모두 활성화되었을 때만 포함됨

1284 1300

1285<h4 id="hook-plugin-metrics-event">1301<h4 id="hook-plugin-metrics-event">

1286 훅 플러그인 메트릭 이벤트1302 훅 플러그인 메트릭 이벤트

1287</h4>1303</h4>

1288 1304

1289공식 마켓플레이스 플러그인 훅이 호출별 메트릭을 내보낼 때 기록됩니다. 공식 Anthropic 마켓플레이스에서 설치된 플러그인만 이를 내보낼 수 있습니다. 타사 마켓플레이스 플러그인과 사용자 구성 훅은 이 이벤트로 내보내지 않습니다. 이 이벤트를 사용하여 자신의 관찰성 스택에서 찾기 비율, 비용, 기간과 같은 플러그인 동작을 모니터링합니다.1305공식 마켓플레이스 플러그인 훅이 호출별 메트릭을 내보낼 때 기록됩니다. 공식 Anthropic 마켓플레이스에서 설치된 플러그인만 이를 내보낼 수 있습니다. 타사 마켓플레이스 플러그인과 사용자 구성 훅은 이 이벤트로 내보내지 않습니다. 이 이벤트를 사용하여 자신의 관찰성 스택에서 찾기 비율, 비용, 지속 시간과 같은 플러그인 동작을 모니터링하세요.

1290 1306

1291**이벤트 이름**: `claude_code.hook_plugin_metrics`1307**이벤트 이름**: `claude_code.hook_plugin_metrics`

1292 1308

1295* 모든 [표준 속성](#standard-attributes)1311* 모든 [표준 속성](#standard-attributes)

1296* `event.name`: `"hook_plugin_metrics"`1312* `event.name`: `"hook_plugin_metrics"`

1297* `event.timestamp`: ISO 8601 타임스탬프1313* `event.timestamp`: ISO 8601 타임스탬프

1298* `event.sequence`: 이벤트 순서 지정을 위한 프로세스당 카운터, [이벤트 상관 속성](#event-correlation-attributes)에서 설명됨1314* `event.sequence`: [이벤트 상관 속성](#event-correlation-attributes)에서 설명한 이벤트 순서 지정을 위한 프로세스당 카운터

1299* `plugin_id`: `<name>@<marketplace>` 형식의 플러그인 식별자1315* `plugin_id`: `<name>@<marketplace>` 형식의 플러그인 식별자

1300* `hook_event`: 메트릭을 내보낸 훅 이벤트 유형1316* `hook_event`: 메트릭을 내보낸 훅 이벤트 유형

1301* 최대 20개의 플러그인 내보낸 메트릭 키. 이름은 `^[a-z][a-z0-9_]{0,39}$`와 일치합니다. 값은 부울 또는 숫자입니다.1317* 최대 20개의 플러그인 내보낸 메트릭 키. 이름은 `^[a-z][a-z0-9_]{0,39}$`와 일치합니다. 값은 부울 또는 숫자입니다.

1313* 모든 [표준 속성](#standard-attributes)1329* 모든 [표준 속성](#standard-attributes)

1314* `event.name`: `"compaction"`1330* `event.name`: `"compaction"`

1315* `event.timestamp`: ISO 8601 타임스탬프1331* `event.timestamp`: ISO 8601 타임스탬프

1316* `event.sequence`: 이벤트 순서 지정을 위한 프로세스당 카운터, [이벤트 상관 속성](#event-correlation-attributes)에서 설명됨1332* `event.sequence`: [이벤트 상관 속성](#event-correlation-attributes)에서 설명한 이벤트 순서 지정을 위한 프로세스당 카운터

1317* `trigger`: `"auto"` 또는 `"manual"`1333* `trigger`: `"auto"` 또는 `"manual"`

1318* `success`: `"true"` 또는 `"false"`1334* `success`: `"true"` 또는 `"false"`

1319* `duration_ms`: 압축 기간1335* `duration_ms`: 압축 지속 시간

1320* `pre_tokens`: 압축 전 대략적인 토큰 수1336* `pre_tokens`: 압축 전 대략적인 토큰 수

1321* `post_tokens`: 압축 후 대략적인 토큰 수1337* `post_tokens`: 압축 후 대략적인 토큰 수

1322* `error`: 압축이 실패했을 때 오류 메시지1338* `error`: 압축이 실패했을 때 오류 메시지

1323* `precompute_reuse`: `trigger`가 `"manual"`일 때만 설정됩니다. 자동 압축은 컨텍스트 윈도우가 채워지기 전에 백그라운드에서 요약을 준비할 수 있으며, 이 속성은 `/compact`가 해당 준비된 요약을 재사용했는지 기록합니다. `"hit"`은 재사용되었음을 의미합니다; `"miss_custom_instructions"`, `"miss_hook"`, `"miss_not_ready"`는 대신 새로운 요약이 계산된 이유를 제공합니다. Claude Code v2.1.153 이상 필요1339* `precompute_reuse`: `trigger`가 `"manual"`일 때만 설정됨. 자동 압축은 컨텍스트 윈도우가 채워지기 전에 백그라운드에서 요약을 준비할 수 있으며, 이 속성은 `/compact`가 준비된 요약을 재사용했는지 기록합니다. `"hit"`는 재사용되었음을 의미합니다; `"miss_custom_instructions"`, `"miss_hook"`, `"miss_not_ready"`는 대신 새로운 요약이 계산된 이유를 제공합니다. Claude Code v2.1.153 이상 필요

1324 1340

1325<h4 id="subagent-completed-event">1341<h4 id="subagent-completed-event">

1326 하위 에이전트 완료 이벤트1342 하위 에이전트 완료 이벤트

1327</h4>1343</h4>

1328 1344

1329[하위 에이전트](/docs/ko/sub-agents)가 완료되고 결과를 시작한 대화에 반환할 때 기록됩니다. 이를 사용하여 하위 에이전트 유형별로 도구 사용 및 실행 시간을 롤업합니다; 토큰 또는 비용 롤업의 경우, `query_source` `"subagent"`로 필터링된 [토큰 카운터](#token-counter) 및 [비용 카운터](#cost-counter)를 사용합니다, 이 이벤트의 `total_tokens`는 최종 요청만 포함하기 때문입니다. `"subagent"` 범주는 또한 하위 에이전트 이벤트를 내보내지 않는 에이전트 기반 훅의 요청을 계산합니다.1345[하위 에이전트](/docs/ko/sub-agents)가 완료되고 결과를 시작한 대화에 반환할 때 기록됩니다. 하위 에이전트 유형별로 도구 사용 및 실행 시간을 롤업하는 데 사용하세요; 토큰 또는 비용 롤업의 경우 이 이벤트의 `total_tokens`는 최종 요청만 포함하므로 `query_source` `"subagent"`로 필터링된 [토큰 카운터](#token-counter) 및 [비용 카운터](#cost-counter)를 사용하세요. `"subagent"` 범주는 또한 하위 에이전트 이벤트를 내보내지 않는 에이전트 기반 훅의 요청을 계산합니다.

1330 1346

1331**이벤트 이름**: `claude_code.subagent_completed`1347**이벤트 이름**: `claude_code.subagent_completed`

1332 1348

1335* 모든 [표준 속성](#standard-attributes)1351* 모든 [표준 속성](#standard-attributes)

1336* `event.name`: `"subagent_completed"`1352* `event.name`: `"subagent_completed"`

1337* `event.timestamp`: ISO 8601 타임스탬프1353* `event.timestamp`: ISO 8601 타임스탬프

1338* `event.sequence`: 이벤트 순서 지정을 위한 프로세스당 카운터, [이벤트 상관 속성](#event-correlation-attributes)에서 설명됨1354* `event.sequence`: [이벤트 상관 속성](#event-correlation-attributes)에서 설명한 이벤트 순서 지정을 위한 프로세스당 카운터

1339* `agent_type`: 하위 에이전트 유형. 기본 제공 에이전트 이름과 공식 마켓플레이스 플러그인의 에이전트는 그대로 나타납니다; 다른 에이전트 이름은 `OTEL_LOG_TOOL_DETAILS=1`이 설정되지 않으면 `"custom"`으로 대체됩니다1355* `agent_type`: 하위 에이전트 유형. 기본 제공 에이전트 이름과 공식 마켓플레이스 플러그인의 에이전트는 그대로 나타납니다; 다른 에이전트 이름은 `OTEL_LOG_TOOL_DETAILS=1`이 설정되지 않은 경우 `"custom"`으로 대체됩니다

1340* `agent.source`: 에이전트 정의가 나온 위치: `built-in`, `plugin`, 또는 `userSettings` 또는 `projectSettings`와 같은 사용자 정의 에이전트를 정의한 설정 소스1356* `agent.source`: 에이전트 정의가 나온 위치: `built-in`, `plugin`, 또는 사용자 정의 에이전트를 정의한 설정 소스, 예: `userSettings` 또는 `projectSettings`

1341* `is_built_in`: 하위 에이전트가 기본 제공 에이전트 유형인지 여부1357* `is_built_in`: 하위 에이전트가 기본 제공 에이전트 유형인지 여부

1342* `is_async`: 하위 에이전트가 [백그라운드](/docs/ko/sub-agents#run-subagents-in-foreground-or-background)에서 실행되었는지 여부1358* `is_async`: 하위 에이전트가 [백그라운드](/docs/ko/sub-agents#run-subagents-in-foreground-or-background)에서 실행되었는지 여부

1343* `total_tokens`: 하위 에이전트의 최종 API 요청의 토큰 풋프린트: 해당 하나의 요청의 입력, 캐시 생성, 캐시 읽기, 출력 토큰, 대략 완료 시 하위 에이전트의 컨텍스트 크기. 실행 전체에 걸친 합계가 아님1359* `total_tokens`: 하위 에이전트의 최종 API 요청의 토큰 풋프린트: 해당 하나의 요청의 입력, 캐시 생성, 캐시 읽기, 출력 토큰, 대략 완료 시 하위 에이전트의 컨텍스트 크기. 실행 전체에 걸친 합계가 아님

1344* `total_tool_uses`: 하위 에이전트가 전체 실행에 걸쳐 수행한 도구 호출 수1360* `total_tool_uses`: 하위 에이전트가 전체 실행에 걸쳐 수행한 도구 호출 수

1345* `duration_ms`: 밀리초 단위의 실행 시간1361* `duration_ms`: 실행 시간 (밀리초)

1346* `model`: 하위 에이전트가 실행하도록 해결된 모델1362* `model`: 하위 에이전트가 실행하도록 해결된 모델

1347* `final_model`: 하위 에이전트의 최종 응답을 생성한 모델, 폴백과 같은 중간 실행 전환 후 `model`과 다릅니다. Claude Code v2.1.212 이상 필요1363* `final_model`: 하위 에이전트의 최종 응답을 생성한 모델, 폴백과 같은 중간 실행 전환 후 `model`과 다릅니다. Claude Code v2.1.212 이상 필요

1348* `model_swapped`: 둘 이상의 모델이 하위 에이전트의 요청을 제공했는지 여부. Claude Code v2.1.212 이상 필요1364* `model_swapped`: 둘 이상의 모델이 하위 에이전트의 요청을 제공했는지 여부. Claude Code v2.1.212 이상 필요

1349* `plugin_id_hash`, `plugin.name`: 플러그인 제공 에이전트에 대해 존재합니다. 공식 마켓플레이스 플러그인 이름은 그대로 나타납니다; 다른 플러그인 이름은 `OTEL_LOG_TOOL_DETAILS=1`이 설정되지 않으면 `"third-party"`로 대체됩니다1365* `plugin_id_hash`, `plugin.name`: 플러그인 제공 에이전트에 대해 존재. 공식 마켓플레이스 플러그인 이름은 그대로 나타납니다; 다른 플러그인 이름은 `OTEL_LOG_TOOL_DETAILS=1`이 설정되지 않은 경우 `"third-party"`로 대체됩니다

1350 1366

1351<h4 id="feedback-survey-event">1367<h4 id="feedback-survey-event">

1352 피드백 설문 이벤트1368 피드백 설문 이벤트

1353</h4>1369</h4>

1354 1370

1355세션 품질 설문이 표시되거나 답변될 때 기록됩니다. [세션 품질 설문](/docs/ko/data-usage#session-quality-surveys)에서 설문이 수집하는 내용과 제어 방법을 참조합니다.1371세션 품질 설문이 표시되거나 답변될 때 기록됩니다. [세션 품질 설문](/docs/ko/data-usage#session-quality-surveys)에서 설문이 수집하는 내용과 제어 방법을 참조하세요.

1356 1372

1357**이벤트 이름**: `claude_code.feedback_survey`1373**이벤트 이름**: `claude_code.feedback_survey`

1358 1374

1361* 모든 [표준 속성](#standard-attributes)1377* 모든 [표준 속성](#standard-attributes)

1362* `event.name`: `"feedback_survey"`1378* `event.name`: `"feedback_survey"`

1363* `event.timestamp`: ISO 8601 타임스탬프1379* `event.timestamp`: ISO 8601 타임스탬프

1364* `event.sequence`: 이벤트 순서 지정을 위한 프로세스당 카운터, [이벤트 상관 속성](#event-correlation-attributes)에서 설명됨1380* `event.sequence`: [이벤트 상관 속성](#event-correlation-attributes)에서 설명한 이벤트 순서 지정을 위한 프로세스당 카운터

1365* `event_type`: 설문 수명 주기 이벤트, 예: `"appeared"`, `"responded"`, 또는 `"transcript_prompt_appeared"`1381* `event_type`: 설문 수명 주기 이벤트, 예: `"appeared"`, `"responded"`, 또는 `"transcript_prompt_appeared"`

1366* `appearance_id`: 하나의 설문 인스턴스에 대해 내보낸 이벤트를 연결하는 고유 ID1382* `appearance_id`: 하나의 설문 인스턴스에 대해 내보낸 이벤트를 연결하는 고유 ID

1367* `survey_type`: 이벤트를 생성한 설문. `"session"`은 "Claude가 어떻게 하고 있나요?" 평가 프롬프트입니다1383* `survey_type`: 이벤트를 생성한 설문. `"session"`은 "Claude가 어떻게 하고 있나요?" 평가 프롬프트

1368* `response`: `responded` 이벤트의 사용자 선택1384* `response`: `responded` 이벤트의 사용자 선택

1369* `enabled_via_override`: [`CLAUDE_CODE_ENABLE_FEEDBACK_SURVEY_FOR_OTEL`](/docs/ko/env-vars)이 설정되었을 때 `true`. 문자열이 아닌 부울로 내보내집니다. `session` 설문 이벤트에 존재합니다. 이 재정의가 플릿 전체에 적용되는지 확인하려면 이 속성으로 필터링합니다1385* `enabled_via_override`: [`CLAUDE_CODE_ENABLE_FEEDBACK_SURVEY_FOR_OTEL`](/docs/ko/env-vars)이 설정되었을 때 `true`. 부울로 내보냄, 문자열이 아님. `session` 설문 이벤트에 있음. 이 오버라이드가 플릿 전체에 적용되는지 확인하려면 이 속성으로 필터링하세요

1370 1386

1371<h4 id="retention-sweep-event">1387<h4 id="retention-sweep-event">

1372 보존 스윕 이벤트1388 보존 스윕 이벤트

1373</h4>1389</h4>

1374 1390

1375보존 정리 스윕의 실행당 한 번 기록되며, [세션 기록 및 기타 애플리케이션 데이터](/docs/ko/claude-directory#cleaned-up-automatically)를 [`cleanupPeriodDays`](/docs/ko/settings-reference#cleanupperioddays) 설정보다 오래된 것을 삭제합니다. Claude Code는 백그라운드에서 세션당 최대 한 번 스윕을 실행하며, 아무것도 삭제하지 않는 실행도 이벤트를 내보냅니다. Claude Code가 지난 24시간 동안 같은 머신의 모든 세션에서 스윕을 실행했다면, 이 세션의 스윕을 최소 10분 지연시키므로, 더 빨리 종료되는 세션은 아무것도 내보내지 않습니다. `claude -p`를 `--bare`로 실행할 때, Claude Code는 스윕을 실행하지 않으며 아무것도 내보내지 않습니다.1391보존 정리 스윕 실행당 한 번 기록되며, [세션 기록 및 기타 애플리케이션 데이터](/docs/ko/claude-directory#cleaned-up-automatically)를 [`cleanupPeriodDays`](/docs/ko/settings-reference#cleanupperioddays) 설정보다 오래된 것을 삭제합니다. Claude Code는 스윕을 백그라운드에서 세션당 최대 한 번 실행하며, 아무것도 삭제하지 않는 실행도 이벤트를 내보냅니다. Claude Code가 지난 24시간 동안 같은 머신의 모든 세션에서 스윕을 실행했다면 이 세션의 스윕을 최소 10분 이상 지연시키므로 더 빨리 종료되는 세션은 아무것도 내보내지 않습니다. `claude -p`를 `--bare`로 실행하면 Claude Code는 스윕을 실행하지 않으며 아무것도 내보내지 않습니다.

1376 1392

1377모든 OTel 이벤트처럼, 구성한 원격 측정 백엔드로만 이동합니다. Claude Code v2.1.227 이상 필요.1393모든 OTel 이벤트처럼 이 페이지의 이벤트는 구성한 원격 측정 백엔드로만 이동합니다. Claude Code v2.1.227 이상 필요.

1378 1394

1379Claude Code가 보존 기간을 안전하게 결정할 수 없을 때, 스윕을 일시 중지하고 `result`를 `"skipped"`로 설정하고 `skip_reason`을 포함하는 이벤트를 내보냅니다. [관리 설정](/docs/ko/server-managed-settings)이 `cleanupPeriodDays`를 설정할 때, 관리 값은 보존 기간을 고정하고 스윕은 낮은 우선순위 범위의 설정 파일이 손상되거나 유효하지 않을 때도 실행됩니다. `managed-settings.json` 자체를 읽을 수 없을 때, Claude Code는 [관리 계층](/docs/ko/managed-settings#how-claude-code-combines-managed-sources)이 서버 관리 설정과 같은 다른 곳에서 `cleanupPeriodDays`를 제공하지 않으면 스윕을 일시 중지합니다. 손상된 파일 옆의 `managed-settings.d/` 드롭인. 삭제 카운터 속성은 `result`가 `"complete"`일 때만 존재합니다.1395Claude Code가 보존 기간을 안전하게 결정할 수 없을 때 스윕을 일시 중지하고 `result`를 `"skipped"`로 설정하고 `skip_reason`을 포함하는 이벤트를 내보냅니다. [관리 설정](/docs/ko/server-managed-settings)이 `cleanupPeriodDays`를 설정할 때 관리 값은 보존 기간을 고정하고 스윕은 낮은 우선순위 범위의 설정 파일이 손상되거나 유효하지 않을 때도 실행됩니다. `managed-settings.json` 자체를 읽을 수 없을 때 Claude Code는 [관리 계층](/docs/ko/managed-settings#how-claude-code-combines-managed-sources)이 서버 관리 설정과 같은 다른 곳에서 `cleanupPeriodDays`를 제공하지 않는 한 스윕을 일시 중지합니다. 또는 손상된 파일 옆의 `managed-settings.d/` 드롭인. 삭제 카운터 속성은 `result`가 `"complete"`일 때만 존재합니다.

1380 1396

1381**이벤트 이름**: `claude_code.retention_sweep`1397**이벤트 이름**: `claude_code.retention_sweep`

1382 1398

1385* 모든 [표준 속성](#standard-attributes)1401* 모든 [표준 속성](#standard-attributes)

1386* `event.name`: `"retention_sweep"`1402* `event.name`: `"retention_sweep"`

1387* `event.timestamp`: ISO 8601 타임스탬프1403* `event.timestamp`: ISO 8601 타임스탬프

1388* `event.sequence`: 이벤트 순서 지정을 위한 프로세스당 카운터, [이벤트 상관 속성](#event-correlation-attributes)에서 설명됨1404* `event.sequence`: [이벤트 상관 속성](#event-correlation-attributes)에서 설명한 이벤트 순서 지정을 위한 프로세스당 카운터

1389* `result`: 스윕이 실행되었을 때 `"complete"`, Claude Code가 일시 중지했을 때 `"skipped"`1405* `result`: 스윕이 실행되었을 때 `"complete"`, Claude Code가 일시 중지했을 때 `"skipped"`

1390* `period_days`: 병합된 설정의 `cleanupPeriodDays` 값, 일 단위, 또는 소스가 설정하지 않을 때 `30`. 건너뛴 이벤트에서, 스윕이 사용했을 값, Claude Code가 읽을 수 있는 설정 소스에서 계산됨1406* `period_days`: 병합된 설정의 `cleanupPeriodDays` 값 (일), 또는 소스가 설정하지 않을 때 `30`. 건너뛴 이벤트에서 스윕이 사용했을 값, Claude Code가 읽을 수 있는 설정 소스에서 계산됨

1391* `used_default`: 읽을 수 있는 설정 소스가 `cleanupPeriodDays`를 설정하지 않을 때 `"true"`, 그 외의 경우 `"false"`. 완료 이벤트에서, `"true"`는 30일 기본값이 적용되었음을 의미합니다1407* `used_default`: 읽을 수 있는 설정 소스가 `cleanupPeriodDays`를 설정하지 않을 때 `"true"`, 그 외의 경우 `"false"`. 완료 이벤트에서 `"true"`는 30일 기본값이 적용되었음을 의미합니다

1392* `skip_reason`: Claude Code가 스윕을 일시 중지한 이유. `result`가 `"skipped"`일 때만 존재:1408* `skip_reason`: Claude Code가 스윕을 일시 중지한 이유. `result`가 `"skipped"`일 때만 존재:

1393 * `"user_source_disabled"`: 사용자 설정이 제외되었습니다, 예를 들어 [`--setting-sources`](/docs/ko/cli-reference#cli-flags) 플래그 또는 SDK의 [`settingSources`](/docs/ko/agent-sdk/typescript#options) 옵션에 의해, 그리고 활성화된 소스가 `cleanupPeriodDays`를 제공하지 않습니다1409 * `"user_source_disabled"`: 사용자 설정이 제외됨, 예를 들어 [`--setting-sources`](/docs/ko/cli-reference#cli-flags) 플래그 또는 SDK의 [`settingSources`](/docs/ko/agent-sdk/typescript#options) 옵션에 의해, 활성화된 소스가 `cleanupPeriodDays`를 제공하지 않음

1394 * `"settings_unknowable"`: 설정 파일을 읽거나 구문 분석할 수 없어서, `cleanupPeriodDays` 또는 `desktopSessionCleanupPeriodDays`가 Claude Code가 볼 수 없는 값으로 설정될 수 있습니다1410 * `"settings_unknowable"`: 설정 파일을 읽거나 구문 분석할 수 없어 `cleanupPeriodDays` 또는 `desktopSessionCleanupPeriodDays`가 Claude Code가 볼 수 없는 값으로 설정될 수 있음

1395 * `"settings_invalid_key_set"`: 설정에 유효성 검사 오류가 있고 `cleanupPeriodDays` 또는 `desktopSessionCleanupPeriodDays`가 명시적으로 설정되어 있어서, 기본값으로 폴백하면 해당 설정에 대해 파일을 삭제하거나 유지할 수 있습니다1411 * `"settings_invalid_key_set"`: 설정에 유효성 검사 오류가 있고 `cleanupPeriodDays` 또는 `desktopSessionCleanupPeriodDays`가 명시적으로 설정되어 있어 기본값으로 폴백하면 해당 설정에 대해 파일을 삭제하거나 유지할 수 있음

1396* `transcripts_deleted`: 스윕이 삭제한 세션 기록 수, 최상위 `~/.claude/projects/*/*.jsonl` 파일1412* `transcripts_deleted`: 스윕이 삭제한 세션 기록 수, 최상위 `~/.claude/projects/*/*.jsonl` 파일

1397* `transcripts_exempted_desktop`: 보존 기간을 지난 기록 수, 스윕이 [Claude Desktop 및 Cowork 규칙](/docs/ko/claude-directory#cleaned-up-automatically)에 따라 유지했습니다. 이들은 `files_past_cutoff`에 계산되지 않습니다. Claude Code v2.1.248 이상 필요1413* `transcripts_exempted_desktop`: 보존 기간을 초과했지만 스윕이 [Claude Desktop 및 Cowork 규칙](/docs/ko/claude-directory#cleaned-up-automatically)에 따라 유지한 기록 수. 이들은 `files_past_cutoff`에 계산되지 않습니다. Claude Code v2.1.248 이상 필요

1398* `session_files_deleted`: 세션 파일 스윕이 삭제한 항목 수: 기록 및 사이드카, 녹음, 도구 결과와 같은 세션별 동반 파일1414* `session_files_deleted`: 세션 파일 스윕이 삭제한 아티팩트 수: 기록 및 사이드카, 녹음, 도구 결과와 같은 세션별 동반 파일

1399* `artifacts_deleted`: 데이터 디렉토리를 포함하여 스윕이 삭제한 총 항목 수. 일부 스윕은 제거된 전체 디렉토리 트리를 하나의 항목으로 계산하고 몇 가지 정리 통과는 카운터에 기여하지 않으므로, 값을 정확한 파일 수보다는 하한으로 취급합니다1415* `artifacts_deleted`: 데이터 디렉토리 전체에서 스윕이 삭제한 총 항목, 세션 파일 포함. 일부 스윕은 전체 제거된 디렉토리 트리를 하나의 항목으로 계산하고 몇 가지 정리 통과는 카운터에 기여하지 않으므로 값을 정확한 파일 수보다는 하한으로 취급하세요

1400* `files_retained_fresh`: 검사되고 보존 기간 내에 있기 때문에 제자리에 남겨진 파일. 파일별 스윕만 이들을 계산하므로, 값은 하한입니다; 0이 아닌 값은 정상적인 정상 상태입니다1416* `files_retained_fresh`: 검사되고 보존 기간 내에 있기 때문에 제자리에 남겨진 파일. 파일별 스윕만 이들을 계산하므로 값은 하한입니다; 0이 아닌 값은 정상적인 정상 상태입니다

1401* `files_past_cutoff`: 보존 기간보다 오래되었지만 스윕이 삭제하지 못한 파일, 예를 들어 권한 오류 또는 열린 파일 때문에. 0 이상의 값은 파일이 구성된 보존 기간을 초과했음을 의미합니다; 0은 없었다는 증거가 아닙니다, 전체 디렉토리 제거 실패가 대신 `error_count`에 계산되기 때문입니다1417* `files_past_cutoff`: 보존 기간보다 오래되었지만 스윕이 삭제하지 못한 파일, 예를 들어 권한 오류 또는 열린 파일 때문에. 0 이상의 값은 파일이 구성된 보존 기간을 초과했음을 의미합니다; 0은 아무것도 하지 않았다는 증거가 아닙니다, 전체 디렉토리 제거 실패는 대신 `error_count`에 계산되기 때문입니다

1402* `error_count`: 스윕이 파일을 나열하거나 삭제하는 동안 발생한 오류 수1418* `error_count`: 스윕이 파일을 나열하거나 삭제하는 동안 발생한 오류 수

1403 1419

1404<h4 id="managed-settings-resolved-event">1420<h4 id="managed-settings-resolved-event">

1405 관리 설정 해결 이벤트1421 관리 설정 해결 이벤트

1406</h4>1422</h4>

1407 1423

1408세션이 해결한 [관리 설정](/docs/ko/managed-settings)과 함께 기록됩니다: 세션 시작 시 한 번, 관리 설정 또는 [정책 도우미](/docs/ko/managed-settings#compute-the-policy-with-a-helper-program)의 상태가 세션 중에 변경될 때 다시, Claude Code가 이유 중 하나로 시작을 거부하거나 세션을 종료할 때 `error.type` 속성이 나열합니다.1424세션이 해결한 [관리 설정](/docs/ko/managed-settings)과 함께 기록됨: 세션 시작 시 한 번, 관리 설정 또는 [정책 도우미](/docs/ko/managed-settings#compute-the-policy-with-a-helper-program)의 상태가 세션 중에 변경될 때 다시, Claude Code가 거부하거나 `error.type` 속성이 나열하는 이유 중 하나로 세션을 종료할 때.

1409이 이벤트를 사용하여 예상치 못한 관리 소스에서 실행 중인 머신, 정책 도우미가 실패하는 머신, 머신이 시작을 거부한 이유를 찾습니다.1425이 이벤트를 사용하여 예상치 못한 관리 소스에서 실행 중인 머신, 정책 도우미가 실패하는 머신, 머신이 시작을 거부한 이유를 찾으세요.

1410Claude Code v2.1.274 이상 필요.1426Claude Code v2.1.274 이상 필요.

1411 1427

1412기본적으로, 이벤트는 관리 소스와 정책 도우미의 상태를 전달하지만 설정 자체는 전달하지 않습니다. 수정된 `managed_settings.settings` 속성과 `managed_settings.resolved_sha256` 다이제스트를 추가하려면, `OTEL_LOG_MANAGED_SETTINGS=1`을 설정합니다:1428기본적으로 이벤트는 관리 소스와 정책 도우미의 상태를 전달하지만 설정 자체는 전달하지 않습니다. 수정된 `managed_settings.settings` 속성과 `managed_settings.resolved_sha256` 다이제스트를 추가하려면 `OTEL_LOG_MANAGED_SETTINGS=1`을 설정하세요:

1413 1429

1414* 관리 설정, 사용자 설정, `--settings`의 `env` 블록, 또는 Claude Code를 시작하는 환경에서 설정합니다. 프로젝트 또는 로컬 설정의 값은 이를 켜지 않습니다, 복제된 저장소가 이들을 쓸 수 있기 때문입니다.1430* 관리 설정, 사용자 설정, `--settings`의 `env` 블록 또는 Claude Code를 시작하는 환경에서 설정하세요. 프로젝트 또는 로컬 설정의 값은 복제된 저장소가 이들을 쓸 수 있기 때문에 켜지 않습니다.

1415* 서버 관리 설정은 [보안 승인 대화](/docs/ko/server-managed-settings#security-approval-dialogs)를 표시하지 않고 이를 설정할 수 있습니다, 변수는 조직이 이미 받는 이벤트에 조직 자체의 수정된 정책만 추가하기 때문입니다.1431* 서버 관리 설정은 [보안 승인 대화](/docs/ko/server-managed-settings#security-approval-dialogs)를 표시하지 않고 설정할 수 있습니다, 변수는 조직이 이미 받는 이벤트에 조직 자체의 수정된 정책만 추가하기 때문입니다.

1416 1432

1417[신뢰하지 않은](/docs/ko/permissions#what-runs-before-you-trust-a-folder) 폴더의 대화형 세션에서, Claude Code는 거부 이벤트를 내보내지 않습니다.1433[신뢰하지 않은](/docs/ko/permissions#what-runs-before-you-trust-a-folder) 폴더의 대화형 세션에서 Claude Code는 거부 이벤트를 내보내지 않습니다.

1418 1434

1419**이벤트 이름**: `claude_code.managed_settings_resolved`1435**이벤트 이름**: `claude_code.managed_settings_resolved`

1420 1436

1423* 모든 [표준 속성](#standard-attributes)1439* 모든 [표준 속성](#standard-attributes)

1424* `event.name`: `"managed_settings_resolved"`1440* `event.name`: `"managed_settings_resolved"`

1425* `event.timestamp`: ISO 8601 타임스탬프1441* `event.timestamp`: ISO 8601 타임스탬프

1426* `event.sequence`: 이벤트 순서 지정을 위한 프로세스당 카운터, [이벤트 상관 속성](#event-correlation-attributes)에서 설명됨1442* `event.sequence`: [이벤트 상관 속성](#event-correlation-attributes)에서 설명한 이벤트 순서 지정을 위한 프로세스당 카운터

1427* `managed_settings.trigger`: 세션 시작 이벤트의 경우 `"startup"`, 관리 설정 또는 정책 도우미의 상태가 세션 후반에 변경되었을 때 `"change"`, 또는 관리 설정 정책이 세션을 중지했을 때 `"refused"`. Claude Code는 마지막 이벤트와 다른 속성이 있을 때만 `change` 이벤트를 보내며, 변경된 설정 값은 `OTEL_LOG_MANAGED_SETTINGS`가 꺼져 있어도 계산됩니다1443* `managed_settings.trigger`: 세션 시작 이벤트의 경우 `"startup"`, 관리 설정 또는 정책 도우미의 상태가 세션 후반에 변경되었을 때 `"change"`, 또는 관리 설정 정책이 세션을 중지했을 때 `"refused"`. Claude Code는 마지막 이벤트와 다른 속성이 있을 때만 `change` 이벤트를 전송하며, 변경된 설정 값은 `OTEL_LOG_MANAGED_SETTINGS`가 꺼져 있어도 계산됩니다

1428* `error.type`: Claude Code가 세션을 중지한 이유. `refused` 이벤트에만 존재:1444* `error.type`: Claude Code가 세션을 중지한 이유. `refused` 이벤트에만 존재:

1429 * `"helper_failed"`: [정책 도우미 실행이 실패했습니다](/docs/ko/settings-reference#helper-failures)1445 * `"helper_failed"`: [정책 도우미 실행이 실패함](/docs/ko/settings-reference#helper-failures)

1430 * `"policy_invalid"`: 관리 설정에 Claude Code가 시작되지 않도록 하는 오류가 포함되어 있거나, 관리 소스가 로드되지 못해서, Claude Code가 조직 로그인 적용을 확인할 수 없습니다1446 * `"policy_invalid"`: 관리 설정에 Claude Code가 시작하지 못하게 하는 오류가 포함되어 있거나 다른 이유로 관리 소스를 읽지 못해 Claude Code가 조직 로그인 또는 공급자 적용을 확인할 수 없음

1431 * `"consent_rejected"`: 사용자가 서버 관리 설정의 [보안 승인 대화](/docs/ko/server-managed-settings#security-approval-dialogs)를 거부했습니다1447 * `"provider_not_allowed"`: 세션이 API 공급자를 사용하거나 공급자의 트래픽을 관리 [`allowedProviders`](/docs/ko/settings-reference#allowedproviders) 목록이 허용하지 않는 호스트로 보낼 것입니다. Claude Code v2.1.285 이상 필요

1432 * `"force_refresh_failed"`: [`forceRemoteSettingsRefresh`](/docs/ko/settings-reference#forceremotesettingsrefresh)가 필요로 하는 설정 가져오기가 실패했습니다1448 * `"consent_rejected"`: 사용자가 서버 관리 설정의 [보안 승인 대화](/docs/ko/server-managed-settings#security-approval-dialogs)를 거부함

1433 * `"gateway_rejected"`: [Claude 앱 게이트웨이](/docs/ko/claude-apps-gateway)가 관리 설정 로드에 HTTP 403으로 응답했습니다1449 * `"force_refresh_failed"`: [`forceRemoteSettingsRefresh`](/docs/ko/settings-reference#forceremotesettingsrefresh)가 필요로 하는 설정 가져오기가 실패함

1450 * `"gateway_rejected"`: [Claude 앱 게이트웨이](/docs/ko/claude-apps-gateway)가 관리 설정 로드에 HTTP 403으로 답변함

1434 * `"version_below_minimum"`: 이 Claude Code 버전이 [`requiredMinimumVersion`](/docs/ko/settings-reference#requiredminimumversion) 아래이거나 [`requiredMaximumVersion`](/docs/ko/settings-reference#requiredmaximumversion) 위입니다1451 * `"version_below_minimum"`: 이 Claude Code 버전이 [`requiredMinimumVersion`](/docs/ko/settings-reference#requiredminimumversion) 아래이거나 [`requiredMaximumVersion`](/docs/ko/settings-reference#requiredmaximumversion) 위입니다

1435 * `"_OTHER"`: Claude 앱 게이트웨이 관리 설정 로드가 다른 이유로 실패했습니다1452 * `"_OTHER"`: Claude 앱 게이트웨이 관리 설정 로드가 다른 이유로 실패함

1436* `managed_settings.sources`: 최소 하나의 [정책 키](/docs/ko/managed-settings#how-claude-code-combines-managed-sources)를 전달하는 모든 관리 소스, 최고 우선순위 먼저, `first-wins`에서 효과를 갖지 않는 소스 포함. 값은 `"remote"`, MDM 또는 OS 수준 정책의 경우 `"plist"` 또는 `"hklm"`, 관리 설정 파일 및 드롭인의 경우 `"file"`, [포함 호스트](/docs/ko/managed-settings#let-an-embedding-host-add-policy)가 설정을 제공할 때 `"parent"`, [Windows HKCU 레지스트리 값](/docs/ko/managed-settings#where-each-mechanism-stores-the-policy)의 경우 `"hkcu"` Claude Code가 [읽을 때](/docs/ko/managed-settings#how-claude-code-combines-managed-sources). 제어 키만 전달하거나 Claude Code가 읽을 수 없는 소스는 나열되지 않습니다. 문자열 배열로 내보내짐, 관리 소스가 정책 키를 전달하지 않을 때 비어 있음1453* `managed_settings.sources`: 최소 하나의 [정책 키](/docs/ko/managed-settings#how-claude-code-combines-managed-sources)를 전달하는 모든 관리 소스, 최고 우선순위 먼저, `first-wins`에서 효과를 갖지 않는 소스 포함. 값은 `"remote"`, `"plist"` 또는 `"hklm"` (MDM 또는 OS 수준 정책), `"file"` (관리 설정 파일 및 드롭인), `"parent"` ([포함 호스트](/docs/ko/managed-settings#let-an-embedding-host-add-policy)가 설정을 제공할 때), `"hkcu"` ([Windows HKCU 레지스트리 값](/docs/ko/managed-settings#where-each-mechanism-stores-the-policy) Claude Code가 [읽을 때](/docs/ko/managed-settings#how-claude-code-combines-managed-sources)). 정책 키만 전달하거나 Claude Code가 읽을 수 없는 소스는 나열되지 않습니다. 관리 소스가 정책 키를 전달하지 않을 때 빈 배열로 내보냄

1437* `managed_settings.source_behavior`: Claude Code가 읽은 [`managedSourcesBehavior`](/docs/ko/settings-reference#managedsourcesbehavior) 값, `"first-wins"` 또는 `"merge"`. 소스가 키를 설정하지 않을 때 `"first-wins"`1454* `managed_settings.source_behavior`: Claude Code가 읽은 [`managedSourcesBehavior`](/docs/ko/settings-reference#managedsourcesbehavior) 값, `"first-wins"` 또는 `"merge"`. 소스가 키를 설정하지 않을 때 `"first-wins"`

1438* `managed_settings.helper.state`: 선택된 MDM 또는 파일 소스가 구성하는 정책 도우미의 상태:1455* `managed_settings.helper.state`: 선택된 MDM 또는 파일 소스가 구성하는 정책 도우미의 상태:

1439 * `"ok"`: 도우미의 출력이 관리 설정으로 제공됩니다1456 * `"ok"`: 도우미의 출력이 관리 설정으로 제공됨

1440 * `"bad_path"`, `"not_a_file"`, `"exit_nonzero"`, `"timed_out"`, `"oversize"`, `"parse_failed"`, `"envelope_invalid"`, 또는 `"schema_rejected"`: 도우미의 마지막 실행이 실패했습니다. [도우미 실패](/docs/ko/settings-reference#helper-failures)가 경우를 설명합니다1457 * `"bad_path"`, `"not_a_file"`, `"exit_nonzero"`, `"timed_out"`, `"oversize"`, `"parse_failed"`, `"envelope_invalid"`, 또는 `"schema_rejected"`: 도우미의 마지막 실행이 실패함. [도우미 실패](/docs/ko/settings-reference#helper-failures)가 경우를 설명합니다

1441 * `"none"`: 도우미가 구성되지 않았거나, 도우미를 구성하는 소스가 MDM 정책 또는 관리 설정 파일이 아닙니다1458 * `"none"`: 도우미가 구성되지 않았거나 도우미를 구성하는 소스가 MDM 정책 또는 관리 설정 파일이 아님

1442* `managed_settings.helper.applied`: 도우미의 자체 출력이 관리 설정으로 제공될 때 `"output"`, 그렇지 않을 때 `"none"`1459* `managed_settings.helper.applied`: 도우미의 자체 출력이 관리 설정으로 제공될 때 `"output"`, 그렇지 않을 때 `"none"`

1443* `managed_settings.helper.entry`: Claude Code가 [`policyHelper`](/docs/ko/settings-reference#policyhelper)를 선택했을 때 `"policyHelper"`. 도우미를 선택하지 않았을 때 없음1460* `managed_settings.helper.entry`: Claude Code가 [`policyHelper`](/docs/ko/settings-reference#policyhelper)를 선택했을 때 `"policyHelper"`. 도우미를 선택하지 않았을 때 없음

1444* `managed_settings.helper.path`: 도우미의 구성된 [`path`](/docs/ko/settings-reference#policyhelper-path). Claude Code가 도우미를 선택했을 때마다 존재, `OTEL_LOG_MANAGED_SETTINGS`이 설정되었는지 여부와 관계없이1461* `managed_settings.helper.path`: 도우미의 구성된 [`path`](/docs/ko/settings-reference#policyhelper-path). Claude Code가 도우미를 선택했을 때마다 존재, `OTEL_LOG_MANAGED_SETTINGS`이 설정되었는지 여부와 관계없이

1445* `managed_settings.resolved_sha256` (`OTEL_LOG_MANAGED_SETTINGS=1`일 때): 수정 전 해결된 관리 설정의 SHA-256, JSON으로 직렬화되고 키가 재귀적으로 정렬되고 공백이 없습니다. 동일한 다이제스트를 가진 머신은 동일한 정책을 실행합니다. Claude Code는 짧은 정책을 추측 해싱으로 복구할 수 있기 때문에 옵트인으로만 다이제스트를 보냅니다. 관리 설정이 해결되지 않았을 때 없고, `refused` 이벤트에서 없습니다.1462* `managed_settings.resolved_sha256` (`OTEL_LOG_MANAGED_SETTINGS=1`일 때): 수정 전 해결된 관리 설정의 SHA-256, JSON으로 직렬화되고 키가 재귀적으로 정렬되고 공백이 없음. 동일한 다이제스트를 실행하는 머신은 동일한 정책을 실행합니다. Claude Code는 짧은 정책을 추측 해싱으로 복구할 수 있기 때문에 옵트인으로만 다이제스트를 전송합니다. 관리 설정이 해결되지 않았을 때 없고, `refused` 이벤트에서 없음.

1446* `managed_settings.settings` (`OTEL_LOG_MANAGED_SETTINGS=1`일 때): 해결된 관리 설정의 이름과 형태, JSON 문자열로, 값이 수정됨. `refused` 이벤트에서 없습니다. Claude Code는 설정 스키마에서 이를 구축합니다:1463* `managed_settings.settings` (`OTEL_LOG_MANAGED_SETTINGS=1`일 때): 해결된 관리 설정의 이름과 형태, JSON 문자열로, 값이 수정됨. `refused` 이벤트에서 없음. Claude Code는 설정 스키마에서 빌드합니다:

1447 1464

1448 * 스키마가 내보내기를 선언하는 설정 이름, 스키마가 선언하지 않는 키는 생략됨1465 * 스키마가 선언하는 설정 이름은 내보내지고, 스키마가 선언하지 않는 키는 생략됨

1449 * 부울, 숫자, 문자열 값 스키마가 `permissions.defaultMode`와 같은 고정 옵션 집합으로 제한, 그대로 내보내짐. `sandbox.network.httpProxyPort` 및 `sandbox.network.socksProxyPort`는 `"[REDACTED]"`로 내보내짐1466 * 부울, 숫자, 스키마가 `permissions.defaultMode`와 같은 고정 옵션 집합으로 제한하는 문자열 값은 그대로 내보냄. `sandbox.network.httpProxyPort` 및 `sandbox.network.socksProxyPort`는 `"[REDACTED]"`로 내보냄

1450 * 다른 모든 문자열, 예: `model`, `apiKeyHelper`, 모든 `env` 값, 모든 URL, 모든 명령, `"[REDACTED]"`로 내보내짐1467 * 다른 모든 문자열, 예: `model`, `apiKeyHelper`, 모든 `env` 값, 모든 URL, 모든 명령은 `"[REDACTED]"`로 내보냄

1451 * 맵의 항목 이름, 예: `env` 변수 이름 및 플러그인 ID, 그대로 내보내짐. 스키마가 항목을 입력하지 않는 설정, 예: `vimInsertModeRemaps`, 단일 `"[REDACTED]"`로 내보내짐, `sandbox.ignoreViolations`는 명령 패턴 없이 경로 목록 목록으로 내보내짐1468 * 맵의 항목 이름, 예: `env` 변수 이름 및 플러그인 ID는 그대로 내보냄. 스키마가 항목을 입력하지 않는 설정, 예: `vimInsertModeRemaps`는 단일 `"[REDACTED]"`로 내보내지고, `sandbox.ignoreViolations`는 명령 패턴 없이 경로 목록 목록으로 내보냄

1452 * 목록은 길이를 유지하며, 각 항목은 동일한 규칙으로 수정됨1469 * 목록은 길이를 유지하며, 각 항목은 동일한 규칙으로 수정됨

1453 * `permissions.allow`, `permissions.deny`, 또는 `permissions.ask` 규칙은 콘텐츠가 수정된 도구 이름으로 내보내짐, 예: `Read([REDACTED])`, 도구가 이 Claude Code 버전에 기본 제공되거나 `mcp__jira__create_issue`와 같은 `mcp__` 참조일 때. 다른 규칙은 `"[REDACTED]"`로 내보내짐1470 * `permissions.allow`, `permissions.deny`, 또는 `permissions.ask` 규칙은 도구 이름으로 내보내지고 콘텐츠는 수정됨, 예: `Read([REDACTED])`, 도구가 이 Claude Code 버전에 기본 제공되거나 `mcp__jira__create_issue`와 같은 `mcp__` 참조일 때. 다른 규칙은 `"[REDACTED]"`로 내보냄

1454 * 훅은 동일한 규칙을 따르므로, `type` 및 `timeout`과 같은 고정 옵션 및 숫자 필드는 표시되고, 각 명령, URL, `matcher`, `if` 조건은 `"[REDACTED]"`로 내보내짐1471 * 훅은 동일한 규칙을 따르므로 고정 옵션 및 숫자 필드, 예: `type` 및 `timeout`은 표시되고, 각 명령, URL, `matcher`, `if` 조건은 `"[REDACTED]"`로 내보냄

1455 1472

1456 예를 들어, `apiKeyHelper`, 두 개의 `env` 변수, 거부 규칙이 있는 관리 설정은 `{"apiKeyHelper":"[REDACTED]","env":{"HTTPS_PROXY":"[REDACTED]","CLAUDE_CODE_ENABLE_TELEMETRY":"[REDACTED]"},"permissions":{"deny":["Read([REDACTED])"]}}`.1473 예를 들어 `apiKeyHelper`, 두 개의 `env` 변수, 거부 규칙이 있는 관리 설정은 `{"apiKeyHelper":"[REDACTED]","env":{"HTTPS_PROXY":"[REDACTED]","CLAUDE_CODE_ENABLE_TELEMETRY":"[REDACTED]"},"permissions":{"deny":["Read([REDACTED])"]}}`로 내보냄.

1457 1474

1458 Claude Code는 값을 8 KB UTF-8에서 자르며, 자른 값은 유효한 JSON이 아닙니다1475 Claude Code는 값을 8 KB UTF-8에서 자르고, 자른 값은 유효한 JSON이 아님

1459* `managed_settings.settings_truncated` (`managed_settings.settings`가 존재할 때): Claude Code가 `managed_settings.settings`를 8 KB에서 자를 때 `true`, 그 외의 경우 `false`. 부울로 내보내짐, 문자열이 아님1476* `managed_settings.settings_truncated` (`managed_settings.settings`가 있을 때): Claude Code가 `managed_settings.settings`를 8 KB에서 자를 때 `true`, 그 외의 경우 `false`. 부울로 내보냄, 문자열이 아님

1460 1477

1461<h2 id="interpret-metrics-and-events-data">1478<h2 id="interpret-metrics-and-events-data">

1462 메트릭 및 이벤트 데이터 해석1479 메트릭 및 이벤트 데이터 해석

1470 1487

1471| 메트릭 | 분석 기회 |1488| 메트릭 | 분석 기회 |

1472| - | - |1489| - | - |

1532 1549

1533**성능 모니터링**: API 요청 지속 시간 및 도구 실행 시간을 추적하여 성능 병목 현상을 식별합니다.1550**성능 모니터링**: API 요청 지속 시간 및 도구 실행 시간을 추적하여 성능 병목 현상을 식별합니다.

1534 1551

1552<h3 id="map-input-tokens-to-opentelemetry-genai-semantic-conventions">

1553 입력 토큰을 OpenTelemetry GenAI 시맨틱 규칙에 매핑

1554</h3>

1555

1556Claude Code는 입력 토큰 수를 API 응답의 usage 블록에 표시된 그대로 내보내므로, 이 값에는 [프롬프트 캐시](/docs/ko/prompt-caching)에서 읽거나 캐시에 기록한 토큰이 포함되지 않습니다:

1557

1558* [`claude_code.llm_request`](#span-attributes) 스팬과 [`api_request`](#api-request-event) 이벤트의 `input_tokens`

1559* [`claude_code.token.usage`](#token-counter) 메트릭의 `"input"` 유형

1560

1561Claude Code는 `gen_ai.usage.*` 속성을 설정하지 않습니다. [OpenTelemetry GenAI 시맨틱 규칙](https://github.com/open-telemetry/semantic-conventions-genai)에 따르면 `gen_ai.usage.input_tokens`에는 캐시에서 읽거나 캐시에 기록한 토큰이 포함되어야 합니다. 해당 합계를 계산하려면 다음과 같이 합니다:

1562

1563* 스팬 또는 이벤트에서: `input_tokens`, `cache_read_tokens`, `cache_creation_tokens`를 더합니다

1564* `claude_code.token.usage` 메트릭에서: `"input"`, `"cacheRead"`, `"cacheCreation"` 유형을 더합니다

1565

1566이 규칙은 캐시 읽기와 캐시 쓰기에 대한 별도의 속성도 정의합니다:

1567

1568* `cache_read_tokens`는 `gen_ai.usage.cache_read.input_tokens`에 매핑됩니다

1569* `cache_creation_tokens`는 `gen_ai.usage.cache_write.input_tokens`에 매핑됩니다. 이전 버전의 규칙에서는 캐시 쓰기 속성의 이름이 `gen_ai.usage.cache_creation.input_tokens`이므로, 백엔드에서 요구하는 이름을 사용하세요.

1570

1535<h2 id="audit-security-events">1571<h2 id="audit-security-events">

1536 감사 보안 이벤트1572 감사 보안 이벤트

1537</h2>1573</h2>

1542 속성 작업을 사용자에게 연결1578 속성 작업을 사용자에게 연결

1543</h3>1579</h3>

1544 1580

1545각 이벤트의 [표준 속성](#standard-attributes)에는 인증된 사용자의 ID가 포함됩니다: Claude 계정으로 로그인할 때 `user.email`, `user.account_uuid`, `user.account_id` 및 `organization.id`, [클라우드 세션](/docs/ko/claude-code-on-the-web)에서 세션 자체의 자격 증명이 이들을 전달할 때, 그리고 설치 범위 `user.id` 및 세션별 `session.id`. `user.id`는 설치 범위 식별자이며, [Claude 앱 게이트웨이](/docs/ko/claude-apps-gateway) 세션에서는 게이트웨이 발급 토큰의 IdP 주체입니다.1581각 이벤트의 [표준 속성](#standard-attributes)에는 인증된 사용자의 ID가 포함됩니다: Claude 계정으로 로그인할 때 `user.email`, `user.account_uuid`, `user.account_id` 및 `organization.id`, [클라우드 세션](/docs/ko/claude-code-on-the-web)에서 세션 자체의 자격 증명이 이들을 전달할 때, 그리고 설치 범위 `user.id` 및 세션별 `session.id`. `user.id`는 설치 범위 식별자이며, [Claude 앱 게이트웨이](/docs/ko/claude-apps-gateway)를 통해 `/login`으로 로그인한 세션에서는 게이트웨이 발급 토큰의 IdP 주체입니다.

1546 1582

1547개발자가 시작한 세션에서 MCP 도구 호출, Bash 명령 및 파일 편집은 따라서 해당 개발자에게 귀속됩니다. Claude Code는 별도의 서비스 계정으로 작동하지 않습니다. 각 이벤트에 기록된 ID는 개발자 자신의 Claude 계정이거나 [Claude 앱 게이트웨이](/docs/ko/claude-apps-gateway) 세션의 개발자 IdP 신원입니다. Claude Tag 채널 세션에서 Claude는 조직의 [공유 신원](/docs/ko/cloud-environments#set-the-environment-a-claude-tag-channel-uses) 대신 작동합니다.1583개발자가 시작한 세션에서 MCP 도구 호출, Bash 명령 및 파일 편집은 따라서 해당 개발자에게 귀속됩니다. Claude Code는 별도의 서비스 계정으로 작동하지 않습니다. 각 이벤트에 기록된 ID는 개발자 자신의 Claude 계정이거나 [Claude 앱 게이트웨이](/docs/ko/claude-apps-gateway) 세션의 개발자 IdP 신원입니다. Claude Tag 채널 세션에서 Claude는 조직의 [공유 신원](/docs/ko/cloud-environments#set-the-environment-a-claude-tag-channel-uses) 대신 작동합니다.

1548 1584

1549Claude Code가 직접 API 키로 인증하거나 Amazon Bedrock, Google Cloud의 Agent Platform 또는 Microsoft Foundry에 대해 인증할 때 세션에 Claude 계정이 없으며 `user.id` 및 `session.id`만 채워집니다. 이러한 배포에서는 `OTEL_RESOURCE_ATTRIBUTES`를 사용하여 사용자 ID를 직접 첨부하고, [관리 설정](#administrator-configuration) 파일 또는 시작 래퍼를 통해 사용자별로 설정합니다. Claude 앱 게이트웨이 세션은 이 중 어느 것도 필요하지 않습니다: CLI는 [표준 속성](#standard-attributes)에 설명된 대로 IdP 신원을 자동으로 스탬프합니다.1585Claude Code가 직접 API 키로 인증하거나 Amazon Bedrock, Google Cloud의 Agent Platform 또는 Microsoft Foundry에 대해 인증할 때 세션에 Claude 계정이 없으며 `user.id` 및 `session.id`만 채워집니다. 이러한 배포에서는 `OTEL_RESOURCE_ATTRIBUTES`를 사용하여 사용자 ID를 직접 첨부하고, [관리 설정](#administrator-configuration) 파일 또는 시작 래퍼를 통해 사용자별로 설정합니다. Claude 앱 게이트웨이 세션은 이 중 어느 것도 필요하지 않습니다: [표준 속성](#standard-attributes)을 참조하여 해당 내보내기가 전달하는 ID를 확인합니다.

1550 1586

1551```bash theme={null}1587```bash theme={null}

1552export OTEL_RESOURCE_ATTRIBUTES="enduser.id=jdoe@example.com,enduser.directory_id=S-1-5-21-..."1588export OTEL_RESOURCE_ATTRIBUTES="enduser.id=jdoe@example.com,enduser.directory_id=S-1-5-21-..."

1672* OpenTelemetry 내보내기는 선택 사항이며 명시적 구성이 필요합니다. Anthropic의 별도 운영 원격 측정 및 이를 비활성화하는 방법에 대해서는 [데이터 사용](/docs/ko/data-usage#telemetry-services)을 참조하세요1708* OpenTelemetry 내보내기는 선택 사항이며 명시적 구성이 필요합니다. Anthropic의 별도 운영 원격 측정 및 이를 비활성화하는 방법에 대해서는 [데이터 사용](/docs/ko/data-usage#telemetry-services)을 참조하세요

1673* 원본 파일 콘텐츠 및 코드 스니펫은 메트릭 또는 이벤트에 포함되지 않습니다. 추적 스팬은 별도의 데이터 경로입니다: 아래의 `OTEL_LOG_TOOL_CONTENT` 항목을 참조하세요1709* 원본 파일 콘텐츠 및 코드 스니펫은 메트릭 또는 이벤트에 포함되지 않습니다. 추적 스팬은 별도의 데이터 경로입니다: 아래의 `OTEL_LOG_TOOL_CONTENT` 항목을 참조하세요

1674* OAuth를 통해 인증된 경우 `user.email`이 원격 측정 속성에 포함되며, 구성한 OTel 엔드포인트로만 전송되고 Anthropic으로는 절대 전송되지 않습니다. 조직에서 이것이 우려 사항인 경우 원격 측정 백엔드와 함께 작업하여 이 필드를 필터링하거나 수정하세요1710* OAuth를 통해 인증된 경우 `user.email`이 원격 측정 속성에 포함되며, 구성한 OTel 엔드포인트로만 전송되고 Anthropic으로는 절대 전송되지 않습니다. 조직에서 이것이 우려 사항인 경우 원격 측정 백엔드와 함께 작업하여 이 필드를 필터링하거나 수정하세요

1675* 사용자 프롬프트 콘텐츠는 기본적으로 수집되지 않습니다. 프롬프트 길이만 기록됩니다. 프롬프트 콘텐츠를 포함하려면 `OTEL_LOG_USER_PROMPTS=1`을 설정하세요. 상세 베타 추적에서 이 변수는 프롬프트 텍스트보다 더 멀리 도달합니다: 또한 `claude_code.llm_request` 스팬의 도구 결과를 전달하는 [`new_context` 스팬 속성](#new-context-gates)을 제어합니다1711* 사용자 프롬프트 콘텐츠는 기본적으로 수집되지 않습니다. 프롬프트 길이만 기록됩니다. 프롬프트 콘텐츠를 포함하려면 `OTEL_LOG_USER_PROMPTS=1`을 설정하세요. 활성화되면:

1676* 어시스턴트 응답 텍스트는 기본적으로 수집되지 않습니다. 응답 길이만 기록됩니다. 응답 텍스트를 포함하려면 `OTEL_LOG_ASSISTANT_RESPONSES=1`을 설정하세요. Claude Code의 모든 OpenTelemetry 데이터와 마찬가지로 응답 텍스트는 구성한 OTel 엔드포인트로만 전송되며 Anthropic으로는 전송되지 않습니다. 이 변수가 설정되지 않으면 `OTEL_LOG_USER_PROMPTS`가 폴백으로 사용되므로 프롬프트 콘텐츠는 원하지만 응답 콘텐츠는 원하지 않는 경우 `OTEL_LOG_ASSISTANT_RESPONSES=0`을 설정하세요1712 * `user_prompt` 이벤트는 `prompt`와 [`prompt_text`](#user-prompt-event)라는 두 속성에 프롬프트 텍스트를 전달합니다. 수집기에서 속성 이름으로 이벤트의 프롬프트 텍스트를 삭제하거나 마스킹하는 경우 규칙에 두 속성을 모두 지정하세요

1677* 도구 입력 인수 및 매개변수는 기본적으로 기록되지 않습니다. 이를 포함하려면 `OTEL_LOG_TOOL_DETAILS=1`을 설정하세요. Claude Desktop의 기본 제공 서버의 경우, Claude Desktop이 소유한 세션에서 `tool_decision` 및 `tool_result`는 인수 콘텐츠가 아닌 호스트 작성 이름인 `mcp_server_name`/`mcp_tool_name` 쌍을 전달하며, 플래그가 꺼져 있어도 그렇습니다. 이 예외는 Claude Code v2.1.214 이상이 필요합니다. 이 데이터는 구성한 OTEL 엔드포인트로만 전송되며 Anthropic으로는 절대 전송되지 않습니다. 인수에는 여전히 민감한 값이 포함될 수 있으므로 필요에 따라 이러한 속성을 필터링하거나 수정하도록 원격 측정 백엔드를 구성하세요. 활성화되면:1713

1714 다음 OpenTelemetry Collector `attributes` 프로세서는 이를 나열하는 파이프라인에서 두 속성을 모두 삭제합니다:

1715

1716 ```yaml theme={null}

1717 processors:

1718 attributes/drop-prompt-text:

1719 actions:

1720 - key: prompt

1721 action: delete

1722 - key: prompt_text

1723 action: delete

1724 ```

1725

1726 * [추적](#traces-beta)이 켜져 있으면 `claude_code.interaction` 스팬은 `user_prompt` 속성에 프롬프트 텍스트를 전달합니다

1727

1728 * 상세 베타 추적에서는 스팬이 각 요청과 함께 전송되는 새 사용자 메시지, 도구 결과, 시스템 리마인더, 시스템 프롬프트 텍스트 및 모델 출력도 전달합니다. [상세 베타 추적의 콘텐츠 속성](#new-context-gates)에 각 속성이 나열되어 있습니다. `claude_code.system_prompt` 이벤트는 전체 시스템 프롬프트를 전달합니다

1729* 어시스턴트 응답 텍스트는 기본적으로 수집되지 않습니다. 응답 길이만 기록됩니다. 응답 텍스트를 포함하려면 `OTEL_LOG_ASSISTANT_RESPONSES=1`을 설정하세요. Claude Code의 모든 OpenTelemetry 데이터와 마찬가지로 응답 텍스트는 구성한 OTel 엔드포인트로만 전송되며 Anthropic으로는 전송되지 않습니다. 이 변수가 설정되지 않으면 `OTEL_LOG_USER_PROMPTS`가 폴백으로 사용되므로 이벤트에서 프롬프트 콘텐츠는 원하지만 응답 콘텐츠는 원하지 않는 경우 `OTEL_LOG_ASSISTANT_RESPONSES=0`을 설정하세요. 상세 베타 추적에서 `claude_code.llm_request` 스팬은 여전히 [`response.model_output`](#new-context-gates)에 모델 출력을 전달하며, 이는 이 변수가 아닌 `OTEL_LOG_USER_PROMPTS`를 따릅니다

1730* 도구 입력 인수 및 매개변수는 기본적으로 기록되지 않습니다. 이를 포함하려면 `OTEL_LOG_TOOL_DETAILS=1`을 설정하세요. Claude Desktop의 기본 제공 서버의 경우, Claude Desktop이 소유한 세션에서 `tool_decision` 및 `tool_result`는 인수 콘텐츠가 아닌 호스트 작성 이름인 `mcp_server_name`/`mcp_tool_name` 쌍을 전달하며, 플래그가 꺼져 있어도 그렇습니다. 이 예외는 Claude Code v2.1.214 이상이 필요합니다. 이 데이터는 구성한 OTEL 엔드포인트로만 전송되며 Anthropic으로는 절대 전송되지 않습니다. 인수에는 여전히 민감한 값이 포함될 수 있으므로 필요에 따라 이러한 속성을 필터링하거나 수정하도록 텔레메트리 백엔드를 구성하세요. 활성화되면:

1678 * `tool_result` 및 `tool_decision` 이벤트는 Bash 명령, MCP 서버 및 도구 이름, 스킬 이름이 포함된 `tool_parameters` 속성을 포함합니다. `full_command`와 같은 필드는 잘리지 않은 상태로 내보내집니다1731 * `tool_result` 및 `tool_decision` 이벤트는 Bash 명령, MCP 서버 및 도구 이름, 스킬 이름이 포함된 `tool_parameters` 속성을 포함합니다. `full_command`와 같은 필드는 잘리지 않은 상태로 내보내집니다

1679 * `tool_result` 이벤트는 추가로 파일 경로, URL, 검색 패턴 및 기타 인수가 포함된 `tool_input` 속성을 포함합니다. 512자를 초과하는 개별 값은 잘리고 전체는 약 4K 문자로 제한됩니다1732 * `tool_result` 이벤트는 추가로 파일 경로, URL, 검색 패턴 및 기타 인수가 포함된 `tool_input` 속성을 포함합니다. 512자를 초과하는 개별 값은 잘리고 전체는 약 4K 문자로 제한됩니다

1680 * `user_prompt` 이벤트는 사용자 정의, 플러그인 및 MCP 명령의 축자 `command_name`을 포함합니다1733 * `user_prompt` 이벤트는 사용자 정의, 플러그인 및 MCP 명령의 축자 `command_name`을 포함합니다

1681 * [비용 및 토큰 카운터](#cost-counter) 및 `api_request`, `api_error`, `api_refusal` 이벤트는 속성 귀속에서 실제 에이전트, 스킬, 플러그인, MCP 서버 및 도구 이름을 전달합니다1734 * [비용 및 토큰 카운터](#cost-counter) 및 `api_request`, `api_error`, `api_refusal` 이벤트는 속성 귀속에서 실제 에이전트, 스킬, 플러그인, MCP 서버 및 도구 이름을 전달합니다

1682 * 추적 스팬은 동일한 `tool_input` 속성 및 `file_path`와 같은 입력 파생 속성을 포함하며, `tool_input`과 동일한 잘림이 적용됩니다1735 * `claude_code.tool` 스팬은 `file_path`와 같은 입력 파생 속성을 전달합니다. 상세 베타 추적에서는 [`tool_input`](#new-context-gates) 속성도 전달합니다

1683* 도구 콘텐츠는 기본적으로 추적 스팬에 기록되지 않습니다. 이를 포함하려면 `OTEL_LOG_TOOL_CONTENT=1`을 설정하세요. 그러면 `claude_code.tool` 스팬은 원본 파일 콘텐츠, Bash 명령 출력, MCP 도구, WebFetch 및 WebSearch가 반환하는 것이 포함된 [`tool.output` 스팬 이벤트](#tool-output-span-event)를 전달하며, 속성당 콘텐츠 제한(기본값 60KB)에서 잘립니다. MCP 도구, WebFetch 및 WebSearch의 결과는 Claude Code v2.1.283 이상이 필요합니다. 도구 콘텐츠는 또한 [`new_context`를 통해 스팬에 도달하며, 그 제어는 스팬마다 다릅니다](#new-context-gates). 필요에 따라 이러한 속성을 필터링하거나 수정하도록 원격 측정 백엔드를 구성하세요1736* 도구 콘텐츠는 기본적으로 추적 스팬에 기록되지 않습니다. 이를 포함하려면 `OTEL_LOG_TOOL_CONTENT=1`을 설정하세요. 그러면 `claude_code.tool` 스팬은 원본 파일 콘텐츠, Bash 명령 출력, MCP 도구, WebFetch 및 WebSearch가 반환하는 것이 포함된 [`tool.output` 스팬 이벤트](#tool-output-span-event)를 전달하며, 속성당 콘텐츠 제한(기본값 60KB)에서 잘립니다. MCP 도구, WebFetch 및 WebSearch의 결과는 Claude Code v2.1.283 이상이 필요합니다. 도구 콘텐츠는 또한 [`new_context`를 통해 스팬에 도달하며, 그 제어는 스팬마다 다릅니다](#new-context-gates). 필요에 따라 이러한 속성을 필터링하거나 수정하도록 원격 측정 백엔드를 구성하세요

1684* 원본 Anthropic Messages API 요청 및 응답 본문은 기본적으로 기록되지 않습니다. 이를 포함하려면 셸, 사용자 설정 또는 관리 설정에서 `OTEL_LOG_RAW_API_BODIES`를 설정하세요. [프로젝트 및 로컬 설정](/docs/ko/settings-reference#variables-claude-code-ignores-in-env)에서는 무시됩니다. 본문에는 전체 대화 기록(시스템 프롬프트, 모든 이전 사용자 및 어시스턴트 턴, 도구 결과)이 포함되므로 이를 활성화하면 다른 `OTEL_LOG_*` 콘텐츠 플래그가 공개할 모든 것에 동의하는 것을 의미합니다. Claude Code는 다른 설정에 관계없이 항상 이러한 본문에서 Claude의 확장 사고 콘텐츠를 수정합니다. 설정한 값은 Claude Code가 본문을 전달하는 방식을 결정합니다:1737* 원본 Anthropic Messages API 요청 및 응답 본문은 기본적으로 기록되지 않습니다. 이를 포함하려면 셸, 사용자 설정 또는 관리 설정에서 `OTEL_LOG_RAW_API_BODIES`를 설정하세요. [프로젝트 및 로컬 설정](/docs/ko/settings-reference#variables-claude-code-ignores-in-env)에서는 무시됩니다. 본문에는 전체 대화 기록(시스템 프롬프트, 모든 이전 사용자 및 어시스턴트 턴, 도구 결과)이 포함되므로 이를 활성화하면 다른 `OTEL_LOG_*` 콘텐츠 플래그가 공개할 모든 것에 동의하는 것을 의미합니다. Claude Code는 다른 설정에 관계없이 항상 이러한 본문에서 Claude의 확장 사고 콘텐츠를 수정합니다. 설정한 값은 Claude Code가 본문을 전달하는 방식을 결정합니다:

1685 * `=1`일 때 Claude Code는 각 API 호출에 대해 `api_request_body` 및 `api_response_body` 로그 이벤트를 내보냅니다. 이벤트의 `body` 속성은 JSON 직렬화된 페이로드를 전달하며, 콘텐츠 제한(기본값 60KB)에서 잘립니다1738 * `=1`일 때 Claude Code는 각 API 호출에 대해 `api_request_body` 및 `api_response_body` 로그 이벤트를 내보냅니다. 이벤트의 `body` 속성은 JSON 직렬화된 페이로드를 전달하며, 콘텐츠 제한(기본값 60KB)에서 잘립니다

permission-modes.md +8 −6

Details

86| Claude Code를 실행하는 방식 | 기본 제공 시작 권한 모드 |86| Claude Code를 실행하는 방식 | 기본 제공 시작 권한 모드 |

87| :- | :- |87| :- | :- |

88| 모든 설정 파일이 `disableAutoMode`를 `"disable"`로 설정 | `default` |88| 모든 설정 파일이 `disableAutoMode`를 `"disable"`로 설정 | `default` |

89| `claude -p` 또는 [Agent SDK](/docs/ko/agent-sdk/permissions#permission-modes) | [기능 플래그를 가져오는](/docs/ko/env-vars#features-that-need-feature-flag-fetching) 세션에서 `default`. 기능 플래그를 가져오지 않는 세션(예: 타사 공급자 또는 원격 분석 비활성화)에서는 Claude Code v2.1.285 이상에서 `auto`, 이전 버전에서는 `default`. 자동 기본값을 보류하는 정책이 있는 조직의 세션은 대신 `default`에서 시작됩니다. |89| `claude -p` 또는 [Agent SDK](/docs/ko/agent-sdk/permissions#permission-modes) | [기능 플래그를 가져오는](/docs/ko/env-vars#features-that-need-feature-flag-fetching) 세션에서 `default`. 기능 플래그를 가져오지 않는 세션(예: 타사 공급자 또는 텔레메트리 비활성화)에서는 Claude Code v2.1.285 이상에서 `auto`, 이전 버전에서는 `default`. `auto` 기본값을 보류하는 정책이 있는 조직의 세션은 대신 `default`에서 시작됩니다. |

90| 터미널 또는 [VS Code 확장 프로그램](/docs/ko/vs-code)을 통해 | Claude Code v2.1.283 이상에서 `auto`; 이전 버전에서는 [기능 플래그를 가져오는](/docs/ko/env-vars#features-that-need-feature-flag-fetching) 세션에서 Pro, Max 또는 Team 플랜의 `auto`, 그 외에는 `default` |90| 터미널 또는 [VS Code 확장 프로그램](/docs/ko/vs-code)을 통해 | Claude Code v2.1.283 이상에서 `auto`; 이전 버전에서는 [기능 플래그를 가져오는](/docs/ko/env-vars#features-that-need-feature-flag-fetching) 세션에서 Pro, Max 또는 Team 플랜의 `auto`, 그 외에는 `default` |

91 91

92[설치 또는 업그레이드 후 첫 번째 세션](/docs/ko/env-vars#first-session-after-an-install-or-upgrade)에서 Claude Code는 기능 플래그가 도착하기 전에 시작 권한 모드를 선택할 수 있습니다. 해당 세션은 표에서 제공하는 것과 다른 권한 모드에서 시작할 수 있으며, 다음 세션은 표와 일치합니다.92[설치 또는 업그레이드 후 첫 번째 세션](/docs/ko/env-vars#first-session-after-an-install-or-upgrade)에서 Claude Code는 기능 플래그가 도착하기 전에 시작 권한 모드를 선택할 수 있습니다. 해당 세션은 표에서 제공하는 것과 다른 권한 모드에서 시작할 수 있습니다.

93 93

94플래그, 설정 파일 또는 기본 제공 기본값이 `auto`를 선택하지만 자동 모드를 세션에서 사용할 수 없는 경우, Claude Code는 대신 수동 모드에서 세션을 시작합니다. 자동 모드는 세션이 [가용성 요구 사항](#eliminate-prompts-with-auto-mode)을 충족하지 않을 때(예: 설정 파일이 자동 모드를 비활성화하거나 지원하지 않는 모델) 또는 Anthropic이 서버 측에서 임시로 자동 모드를 비활성화했을 때 사용할 수 없습니다.94플래그, 설정 파일 또는 기본 제공 기본값이 `auto`를 선택하지만 자동 모드를 세션에서 사용할 수 없는 경우, Claude Code는 대신 수동 모드에서 세션을 시작합니다. 자동 모드는 세션이 [가용성 요구 사항](#eliminate-prompts-with-auto-mode)을 충족하지 않을 때(예: 설정 파일이 자동 모드를 비활성화하거나 지원하지 않는 모델) 또는 Anthropic이 서버 측에서 임시로 자동 모드를 비활성화했을 때 사용할 수 없습니다.

95 95

104 다른 권한 모드에서 시작104 다른 권한 모드에서 시작

105</h3>105</h3>

106 106

107한 세션에 대해 또는 머신, 프로젝트 또는 조직의 모든 세션에 대한 기본값으로 시작 권한 모드를 설정할 수 있습니다. 둘 이상의 설정 파일이 `permissions.defaultMode`를 설정할 때 [설정 우선순위](/docs/ko/settings#settings-precedence)가 결정하므로, 프로젝트 또는 관리되는 값이 `~/.claude/settings.json`을 능가합니다. 이미 실행 중인 세션의 권한 모드를 변경하려면 [권한 모드 전환](#switch-permission-modes)을 참조하세요.107한 세션에 대해 또는 머신, 프로젝트 또는 조직의 모든 세션에 대한 기본값으로 시작 권한 모드를 설정할 수 있습니다. 둘 이상의 설정 파일이 `permissions.defaultMode`를 설정할 때 [설정 우선순위](/docs/ko/settings#settings-precedence)가 결정하므로, 프로젝트 또는 관리형 값이 `~/.claude/settings.json`을 능가합니다. 이미 실행 중인 세션의 권한 모드를 변경하려면 [권한 모드 전환](#switch-permission-modes)을 참조하세요.

108 108

109| 시작 권한 모드를 설정하는 대상 | 수행할 작업 |109| 시작 권한 모드를 설정하는 대상 | 수행할 작업 |

110| :- | :- |110| :- | :- |

112| 이 머신에서 시작하는 모든 터미널 세션 | `~/.claude/settings.json`에서 `permissions.defaultMode`를 설정합니다. VS Code 확장 프로그램이 읽는 내용은 [권한 모드 전환](#switch-permission-modes)을 참조하세요. |112| 이 머신에서 시작하는 모든 터미널 세션 | `~/.claude/settings.json`에서 `permissions.defaultMode`를 설정합니다. VS Code 확장 프로그램이 읽는 내용은 [권한 모드 전환](#switch-permission-modes)을 참조하세요. |

113| 한 프로젝트에서 시작하는 모든 터미널 세션 | 프로젝트의 `.claude/settings.json`에서 `permissions.defaultMode`를 설정합니다. 터미널에서 시작하는 세션은 `auto` 및 `bypassPermissions`을 제외한 모든 값을 준수합니다. VS Code 확장 프로그램이 시작하는 세션은 시작 권한 모드에 대한 프로젝트 설정을 읽지 않습니다. |113| 한 프로젝트에서 시작하는 모든 터미널 세션 | 프로젝트의 `.claude/settings.json`에서 `permissions.defaultMode`를 설정합니다. 터미널에서 시작하는 세션은 `auto` 및 `bypassPermissions`을 제외한 모든 값을 준수합니다. VS Code 확장 프로그램이 시작하는 세션은 시작 권한 모드에 대한 프로젝트 설정을 읽지 않습니다. |

114| 조직의 모든 터미널 세션 | [관리되는 설정](/docs/ko/managed-settings)에서 `permissions.defaultMode`를 설정합니다. 터미널 세션은 해당 모드에서 시작되며 사용자는 여전히 자동 모드로 전환할 수 있습니다. VS Code 확장 프로그램이 읽는 내용은 [권한 모드 전환](#switch-permission-modes)을 참조하세요. 자동 모드를 제거하여 아무도 선택할 수 없도록 하려면 `permissions.disableAutoMode`를 `"disable"`로 설정합니다. |114| 조직의 모든 터미널 세션 | [관리형 설정](/docs/ko/managed-settings)에서 `permissions.defaultMode`를 설정합니다. 터미널 세션은 해당 모드에서 시작되며 사용자는 여전히 자동 모드로 전환할 수 있습니다. VS Code 확장 프로그램이 읽는 내용은 [권한 모드 전환](#switch-permission-modes)을 참조하세요. 자동 모드를 제거하여 아무도 선택할 수 없도록 하려면 대신 `permissions.disableAutoMode`를 `"disable"`로 설정합니다. |

115 115

116이 예제는 머신의 모든 터미널 세션이 수동 모드(구성 값은 `default`)에서 시작되도록 합니다. `~/.claude/settings.json`에 저장합니다.116이 예제는 머신의 모든 터미널 세션이 수동 모드(구성 값은 `default`)에서 시작되도록 합니다. `~/.claude/settings.json`에 저장합니다.

117 117

676* `.devcontainer`676* `.devcontainer`

677* `.yarn`677* `.yarn`

678* `.mvn`678* `.mvn`

679* `.claude`, `.claude/worktrees` 제외 (Claude가 자신의 git worktrees를 저장하는 위치)679* `.claude`. 단, Claude가 자신의 git worktree를 저장하는 `.claude/worktrees`와, `--restricted` 없이 시작된 세션에서 Claude 자체 [자동 메모리](/docs/ko/memory#storage-location) 디렉토리에 있는 markdown 파일은 제외

680* [`--plugin-dir`](/docs/ko/plugins/mods/create#change-a-mod-with-claude)로 로드한 디렉토리. Claude Code는 파일이 변경될 때 이 디렉토리에서 mod의 코드를 다시 로드하고 실행하기 때문입니다.680* [`--plugin-dir`](/docs/ko/plugins/mods/create#change-a-mod-with-claude)로 로드한 디렉토리. Claude Code는 파일이 변경될 때 이 디렉토리에서 mod의 코드를 다시 로드하고 실행하기 때문입니다.

681 681

682보호된 파일:682보호된 파일:

739Claude Code는 또한 이러한 구성 내부를 살펴봅니다:739Claude Code는 또한 이러한 구성 내부를 살펴봅니다:

740 740

741* **Nested commands**: `(...)`를 사용한 서브셸, `{ ...; }`를 사용한 brace group, `$(...)` 또는 백틱을 사용한 명령 치환, 또는 `<(...)`를 사용한 프로세스 치환. Claude Code는 `(rm -rf ~)` 또는 `echo "$(rm -rf ~)"`처럼 중첩된 형식 내부에 있든 같은 명령의 다른 곳에 있든 critical-path 제거를 찾습니다.741* **Nested commands**: `(...)`를 사용한 서브셸, `{ ...; }`를 사용한 brace group, `$(...)` 또는 백틱을 사용한 명령 치환, 또는 `<(...)`를 사용한 프로세스 치환. Claude Code는 `(rm -rf ~)` 또는 `echo "$(rm -rf ~)"`처럼 중첩된 형식 내부에 있든 같은 명령의 다른 곳에 있든 critical-path 제거를 찾습니다.

742* **Inline scripts**: Claude Code는 `sh -c` 또는 `bash -c`와 같은 셸에 전달된 스크립트에서 셸 변수 및 위치 매개변수 [대상](#other-targets-that-count-as-critical-paths)을 확인합니다.742* **Inline scripts**: `bash -c 'rm -rf ~'`처럼 `-c`와 함께 `sh`, `bash`, `zsh` 또는 유사한 POSIX 셸에 전달된 스크립트.

743 * 스크립트가 이중 인용되면 호출하는 셸이 내부 셸이 스크립트를 받기 전에 변수를 확장합니다. `find . -name '*.tmp' -exec sh -c "rm -rf \"$1\"/*" _ {} \;`에서 명령은 일치마다 한 번씩 파일시스템 루트에서 제거로 확장되고, Claude Code는 이를 critical-path 제거로 취급합니다.743 * 스크립트가 이중 인용되면 호출하는 셸이 내부 셸이 스크립트를 받기 전에 변수를 확장합니다. `find . -name '*.tmp' -exec sh -c "rm -rf \"$1\"/*" _ {} \;`에서 명령은 일치마다 한 번씩 파일시스템 루트에서 제거로 확장되고, Claude Code는 이를 critical-path 제거로 취급합니다.

744 * `sh -c 'rm -rf "$1"/*' _ {}`처럼 `$1`을 실제 값에 바인딩하는 단일 인용 스크립트는 플래그되지 않습니다.744 * `sh -c 'rm -rf "$1"/*' _ {}`처럼 `$1`을 실제 값에 바인딩하는 단일 인용 스크립트는 플래그되지 않습니다.

745 745

746`~`처럼 `-c` 스크립트에 직접 입력된 critical path에 대한 확인을 끄려면 Claude Code를 시작하는 환경에서 [`CLAUDE_CODE_DISABLE_INLINE_SHELL_RM_PROMPT=1`](/docs/ko/env-vars#variables)을 설정합니다.

747

746<h3 id="rewrite-a-flagged-command">748<h3 id="rewrite-a-flagged-command">

747 Rewrite a flagged command749 Rewrite a flagged command

748</h3>750</h3>

plugins/cli-reference.md +6 −2

Details

336| `version` | string | 마켓플레이스 설치의 경우 [Claude Code가 설치 시 계산한](/docs/ko/plugins/loading#versions-and-updates) 버전. 세션 전용, skills-directory, 또는 동기화된 플러그인의 경우 매니페스트의 `version`, 또는 선언하지 않으면 `unknown` |336| `version` | string | 마켓플레이스 설치의 경우 [Claude Code가 설치 시 계산한](/docs/ko/plugins/loading#versions-and-updates) 버전. 세션 전용, skills-directory, 또는 동기화된 플러그인의 경우 매니페스트의 `version`, 또는 선언하지 않으면 `unknown` |

337| `scope` | string | 설치의 경우 `user`, `project`, `local`, 또는 `managed`. skills-directory 플러그인의 경우 `user` 또는 `project`. 세션 전용 플러그인의 경우 `session`. claude.ai에서 동기화된 플러그인의 경우 `synced` |337| `scope` | string | 설치의 경우 `user`, `project`, `local`, 또는 `managed`. skills-directory 플러그인의 경우 `user` 또는 `project`. 세션 전용 플러그인의 경우 `session`. claude.ai에서 동기화된 플러그인의 경우 `synced` |

340| `readFromFolder` | string | 세션이 마켓플레이스 폴더에서 [제자리에서 로드](/docs/ko/plugins/loading#in-place-and-copied-plugins)하는 플러그인의 경우, 해당 폴더 안에 있는 플러그인의 소스 디렉토리. Claude Code v2.1.289 이상 필요 |

341| `folderVersion` | string | `readFromFolder`가 있을 때, Claude Code가 해당 폴더에서 로드한 플러그인의 `version`으로, 위의 `version` 필드와 다를 수 있습니다. 플러그인이 로드되지 않았거나 버전을 선언하지 않으면 없습니다. Claude Code v2.1.289 이상 필요 |

637 * `.claude`라는 디렉토리: 그 안의 `skills`, `agents`, `commands` 디렉토리639 * `.claude`라는 디렉토리: 그 안의 `skills`, `agents`, `commands` 디렉토리

638 * 다른 디렉토리: 그 `.claude` 아래의 이 세 디렉토리640 * 다른 디렉토리: 그 `.claude` 아래의 이 세 디렉토리

639 641

642디렉토리에 `.claude-plugin/marketplace.json`과 `.claude-plugin/plugin.json`이 모두 있으면 Claude Code는 마켓플레이스와 함께 플러그인의 매니페스트 및 컴포넌트 파일도 검증합니다. 이 기능은 Claude Code v2.1.289 이상이 필요합니다.

643

640Claude Code는 이름을 지정한 디렉토리 내의 심볼릭 링크를 따르지 않습니다. 링크가 어디에 있는지에 따라 어떤 일이 발생하는지 다릅니다:644Claude Code는 이름을 지정한 디렉토리 내의 심볼릭 링크를 따르지 않습니다. 링크가 어디에 있는지에 따라 어떤 일이 발생하는지 다릅니다:

641 645

642* **플러그인 또는 `.claude` 루트 아래의 연결된 `skills`, `agents`, 또는 `commands` 디렉토리**: Claude Code는 그 안의 아무것도 읽지 않았다고 경고합니다.646* **플러그인 또는 `.claude` 루트 아래의 연결된 `skills`, `agents`, 또는 `commands` 디렉토리**: Claude Code는 그 안의 아무것도 읽지 않았다고 경고합니다.

647 651

648* **플러그인 루트의 `SKILL.md`**: 플러그인 디렉토리에 대해 `claude plugin validate`를 실행할 때 Claude Code는 플러그인 루트의 `SKILL.md`를 확인하지 않습니다652* **플러그인 루트의 `SKILL.md`**: 플러그인 디렉토리에 대해 `claude plugin validate`를 실행할 때 Claude Code는 플러그인 루트의 `SKILL.md`를 확인하지 않습니다

649* **플러그인 루트의 `CLAUDE.md`**: 플러그인 실행에서 Claude Code는 플러그인 루트의 `CLAUDE.md`에 대해서도 경고합니다653* **플러그인 루트의 `CLAUDE.md`**: 플러그인 실행에서 Claude Code는 플러그인 루트의 `CLAUDE.md`에 대해서도 경고합니다

650* **마켓플레이스 실행의 플러그인 파일**: 마켓플레이스 디렉토리에서 Claude Code는 플러그인의 skill, agent, command, hook 파일이나 번들된 MCP 서버 파일을 열지 않습니다. 이 파일의 오류를 찾으려면 각 플러그인 디렉토리를 검증하세요654* **마켓플레이스 실행의 플러그인 파일**: 마켓플레이스 디렉토리에서 실행할 때 Claude Code는 마켓플레이스가 다른 디렉토리에 나열한 플러그인의 스킬, 에이전트, 명령, 훅 파일이나 그 플러그인에 번들된 MCP 서버 파일을 열지 않습니다. 이 파일의 오류를 찾으려면 각 플러그인 디렉토리를 검증하세요

651 655

652<h4 id="output-and-exit-codes">656<h4 id="output-and-exit-codes">

653 출력 및 종료 코드657 출력 및 종료 코드

plugins/create.md +2 −2

Details

100 Greet the user warmly and ask how you can help them today.100 Greet the user warmly and ask how you can help them today.

101 ```101 ```

102 102

103 `disable-model-invocation: true` 줄은 Claude가 스킬을 자동으로 실행하지 않음을 의미하므로 사용자만 트리거합니다. Claude가 자동으로 실행하려는 스킬에서 해당 줄을 제거하세요. 스킬의 명령은 플러그인 이름과 스킬의 이름을 결합하므로 이것을 `/my-first-plugin:hello`로 실행합니다. 다른 프론트매터 필드는 [스킬 프론트매터 참조](/docs/ko/skills#frontmatter-reference)를 참조하세요.103 `disable-model-invocation: true` 줄은 Claude가 스킬을 자동으로 실행하지 않음을 의미합니다. Claude가 자동으로 실행하려는 스킬에서 해당 줄을 제거하세요. 스킬의 명령은 플러그인 이름과 스킬의 이름을 결합하므로 이것을 `/my-first-plugin:hello`로 실행합니다. 다른 frontmatter 필드는 [스킬 frontmatter 참조](/docs/ko/skills#frontmatter-reference)를 참조하세요.

104 </Step>104 </Step>

105 105

106 <Step title="플러그인 검증">106 <Step title="플러그인 검증">

107 아무것도 실행하기 전에 매니페스트와 스킬의 프론트매터를 확인하세요:107 아무것도 실행하기 전에 매니페스트와 스킬의 frontmatter를 확인하세요:

108 108

109 ```bash theme={null}109 ```bash theme={null}

110 claude plugin validate ./my-first-plugin110 claude plugin validate ./my-first-plugin

plugins/host-marketplace.md +1 −1

Details

215 215

216사용자에게 새 버전을 출시하려면 플러그인의 `version`을 변경합니다. 사용자는 플러그인의 계산된 버전이 보유한 버전과 다를 때만 새 복사본을 받습니다. 해당 버전은 [버전 및 업데이트](/docs/ko/plugins/loading#versions-and-updates)에 따라 먼저 `plugin.json`에서 나온 다음 마켓플레이스 항목에서 나옵니다.216사용자에게 새 버전을 출시하려면 플러그인의 `version`을 변경합니다. 사용자는 플러그인의 계산된 버전이 보유한 버전과 다를 때만 새 복사본을 받습니다. 해당 버전은 [버전 및 업데이트](/docs/ko/plugins/loading#versions-and-updates)에 따라 먼저 `plugin.json`에서 나온 다음 마켓플레이스 항목에서 나옵니다.

217 217

218사용자가 마켓플레이스에 추가한 로컬 디렉터리에서 [제자리에 로드](/docs/ko/plugins/loading#find-plugins-on-disk)하는 플러그인은 `version`으로 제어되지 않습니다. 버전 문자열이 무엇이든 상관없이 모든 세션 시작 시 현재 파일을 로드합니다.218사용자가 로컬 경로에서 추가한 마켓플레이스로부터 [제자리에 로드](/docs/ko/plugins/loading#find-plugins-on-disk)하는 플러그인은 `version`으로 제어되지 않습니다. 버전 문자열이 무엇이든 상관없이 모든 세션 시작 시 현재 파일을 로드합니다.

219 219

220제자리 로드 또는 `command` 소스의 로드를 제외한 모든 설치의 경우 각 릴리스에서 `version`을 증가시키거나 생략합니다:220제자리 로드 또는 `command` 소스의 로드를 제외한 모든 설치의 경우 각 릴리스에서 `version`을 증가시키거나 생략합니다:

221 221

plugins/loading.md +3 −3

Details

208Claude Code는 일부 플러그인을 보관 위치에서 제자리로 로드하고 나머지는 원본에 따라 캐시에 복사합니다:208Claude Code는 일부 플러그인을 보관 위치에서 제자리로 로드하고 나머지는 원본에 따라 캐시에 복사합니다:

209 209

210* **`--plugin-dir` 및 기술 디렉토리 플러그인**: 디렉토리는 제자리로 로드되며 절대 복사되지 않습니다. `--plugin-url` 아카이브 또는 `--plugin-dir` `.zip`은 먼저 세션 임시 디렉토리로 추출됩니다210* **`--plugin-dir` 및 기술 디렉토리 플러그인**: 디렉토리는 제자리로 로드되며 절대 복사되지 않습니다. `--plugin-url` 아카이브 또는 `--plugin-dir` `.zip`은 먼저 세션 임시 디렉토리로 추출됩니다

211* **로컬 디렉토리에서 추가한 마켓플레이스의 상대 경로 플러그인**: 플러그인은 마켓플레이스 폴더 내의 경로에서 제자리로 로드됩니다. 소스 디렉토리에 대한 편집은 다음 세션 시작 또는 `/reload-plugins`에서 적용되며 버전을 증가시킬 필요가 없습니다. 플러그인의 훅 프로세스 및 MCP 및 LSP 서버는 소스 디렉토리를 가리키는 `CLAUDE_PLUGIN_ROOT`를 수신합니다. Node.js 패키지 종속성은 [종속성 설치가 실행되는 경우](#when-the-dependency-install-runs)를 참조합니다211* **로컬 경로에서 추가한 마켓플레이스의 상대 경로 플러그인**: 플러그인은 마켓플레이스 폴더 내의 경로에서 제자리로 로드됩니다. 소스 디렉토리에 대한 편집은 다음 세션 시작 또는 `/reload-plugins`에서 적용되며 버전을 증가시킬 필요가 없습니다. 플러그인의 훅 프로세스 및 MCP 및 LSP 서버는 소스 디렉토리를 가리키는 `CLAUDE_PLUGIN_ROOT`를 수신합니다. Node.js 패키지 의존성은 [의존성 설치가 실행되는 경우](#when-the-dependency-install-runs)를 참조합니다

212* **[링크 모드](/docs/ko/plugins/marketplace-reference#command-plugin-source)의 `command` 소스 플러그인**: 명령이 인쇄한 디렉토리는 캐시 항목의 링크를 통해 제자리로 로드됩니다212* **[링크 모드](/docs/ko/plugins/marketplace-reference#command-plugin-source)의 `command` 소스 플러그인**: 명령이 인쇄한 디렉토리는 캐시 항목의 링크를 통해 제자리로 로드됩니다

213* **다른 모든 마켓플레이스 플러그인**: Claude Code는 플러그인을 설치 시 `cache/<marketplace>/<plugin>/<version>/`에 복사하고 해당 복사본을 로드합니다. 플러그인 디렉토리 외부의 파일은 복사되지 않으므로 복사된 플러그인 내의 스크립트가 플러그인 루트 위의 경로를 읽을 때 (예: `../shared`), 찾지 못합니다213* **다른 모든 마켓플레이스 플러그인**: Claude Code는 플러그인을 설치 시 `cache/<marketplace>/<plugin>/<version>/`에 복사하고 해당 복사본을 로드합니다. 플러그인 디렉토리 외부의 파일은 복사되지 않으므로 복사된 플러그인 내의 스크립트가 플러그인 루트 위의 경로를 읽을 때 (예: `../shared`), 찾지 못합니다

214 214

250* Claude Code가 플러그인을 새 버전으로 업데이트할 때250* Claude Code가 플러그인을 새 버전으로 업데이트할 때

251* 새 머신과 같이 활성화된 플러그인이 아직 캐시되지 않았을 때 세션 시작 시251* 새 머신과 같이 활성화된 플러그인이 아직 캐시되지 않았을 때 세션 시작 시

252 252

253로컬 디렉토리 마켓플레이스에서 [제자리로 로드된](#in-place-and-copied-plugins) 상대 경로 플러그인의 경우 Claude Code는 소스 디렉토리에 종속성을 설치하지 않습니다. 거기에 설치하거나 훅에서 [`${CLAUDE_PLUGIN_DATA}`](/docs/ko/plugins/components#path-variables-and-persistent-data)로 설치합니다.253로컬 경로에서 추가한 마켓플레이스에서 [제자리로 로드된](#in-place-and-copied-plugins) 상대 경로 플러그인의 경우 Claude Code는 소스 디렉토리에 의존성을 설치하지 않습니다. 거기에 직접 설치하거나 훅에서 [`${CLAUDE_PLUGIN_DATA}`](/docs/ko/plugins/components#path-variables-and-persistent-data)로 설치합니다.

254 254

255설치는 플러그인의 루트 디렉토리에 `package.json`과 지원되는 잠금 파일이 모두 포함될 때만 실행됩니다.255설치는 플러그인의 루트 디렉토리에 `package.json`과 지원되는 잠금 파일이 모두 포함될 때만 실행됩니다.

256 256

315 315

316`"version"`을 고정하는 매니페스트는 계산된 버전이 커밋 전체에서 동일하게 유지되는 한 가지 방법입니다. [Claude Code가 버전을 계산하는 방법](#how-claude-code-computes-the-version)을 참조합니다.316`"version"`을 고정하는 매니페스트는 계산된 버전이 커밋 전체에서 동일하게 유지되는 한 가지 방법입니다. [Claude Code가 버전을 계산하는 방법](#how-claude-code-computes-the-version)을 참조합니다.

317 317

318로컬 디렉토리 마켓플레이스에서 [제자리로 로드된](#in-place-and-copied-plugins) 플러그인은 버전 문자열이 무엇이든 모든 세션 시작에서 현재 소스 파일을 로드합니다. [claude.ai에서 호스팅되는 마켓플레이스](/docs/ko/plugins/install#add-from-claude-ai)의 플러그인의 경우 claude.ai가 플러그인에 대해 기록하는 버전이 버전이고 매니페스트의 `version`은 읽지 않습니다.318로컬 경로에서 추가한 마켓플레이스에서 [제자리로 로드된](#in-place-and-copied-plugins) 플러그인은 버전 문자열이 무엇이든 모든 세션 시작에서 현재 소스 파일을 로드합니다. [claude.ai에서 호스팅되는 마켓플레이스](/docs/ko/plugins/install#add-from-claude-ai)의 플러그인의 경우 claude.ai가 플러그인에 대해 기록하는 버전이 버전이고 매니페스트의 `version`은 읽지 않습니다.

319 319

320<h3 id="how-claude-code-computes-the-version">320<h3 id="how-claude-code-computes-the-version">

321 Claude Code가 버전을 계산하는 방법321 Claude Code가 버전을 계산하는 방법

plugins/manifest-reference.md +1 −1

Details

199 `version`199 `version`

200</h3>200</h3>

201 201

202semver에 대해 검사되지 않는 버전 문자열. 설정하면 변경할 때까지 플러그인을 해당 버전에 고정합니다. [버전 및 업데이트](/docs/ko/plugins/loading#versions-and-updates)를 참조하세요. [`command` 소스](/docs/ko/plugins/marketplace-reference)가 있는 플러그인, [claude.ai에서 호스팅되는 마켓플레이스](/docs/ko/plugins/install#add-from-claude-ai)의 플러그인, 그리고 로컬 디렉토리로 추가된 마켓플레이스에서 [제자리에 로드](/docs/ko/plugins/loading#find-plugins-on-disk)된 플러그인은 이 필드로 고정되지 않습니다.202semver에 대해 검사되지 않는 버전 문자열. 설정하면 변경할 때까지 플러그인을 해당 버전에 고정합니다. [버전 및 업데이트](/docs/ko/plugins/loading#versions-and-updates)를 참조하세요. [`command` 소스](/docs/ko/plugins/marketplace-reference)가 있는 플러그인, [claude.ai에서 호스팅되는 마켓플레이스](/docs/ko/plugins/install#add-from-claude-ai)의 플러그인, 그리고 로컬 경로에서 추가된 마켓플레이스에서 [제자리에 로드](/docs/ko/plugins/loading#find-plugins-on-disk)된 플러그인은 이 필드로 고정되지 않습니다.

203 203

204<h3 id="metadata">204<h3 id="metadata">

205 `metadata`205 `metadata`

plugins/mods/interface.md +2 −2

Details

434| `Link`, `Code`, `Markdown` | `href`와 선택적 `label`을 갖는 링크, 코드 블록, 그리고 Claude의 응답과 같은 방식으로 서식이 지정된 텍스트입니다. `Markdown`은 내용을 `children`이 아닌 `text` prop으로 받으며, `onLinkPress`를 전달할 때는 `key`가 필요합니다. | 모든 곳 |434| `Link`, `Code`, `Markdown` | `href`와 선택적 `label`을 갖는 링크, 코드 블록, 그리고 Claude의 응답과 같은 방식으로 서식이 지정된 텍스트입니다. `Markdown`은 내용을 `children`이 아닌 `text` prop으로 받으며, `onLinkPress`를 전달할 때는 `key`가 필요합니다. | 모든 곳 |

436| `Svg` | SVG 문서 | Desktop |436| `Svg` | SVG 문서 | Desktop |

437| `Client` | 애니메이션과 포인터 입력을 위해 별도로 작성한 두 번째 파일이 그리는 영역입니다. 이 파일은 mod API를 사용할 수 없습니다. 훅과는 데이터를 게시하는 방식으로만 통신하며, 게시된 데이터는 `ui.message` 이벤트로 전달됩니다. | 터미널, Desktop |437| `Client` | 애니메이션과 포인터 입력을 위해 별도로 작성한 두 번째 파일이 그리는 영역입니다. 이 파일은 mod API를 사용할 수 없습니다. 훅과는 데이터를 게시하는 방식으로만 통신하며, 게시된 데이터는 `ui.message` 이벤트로 전달됩니다. 이 파일이 로드, 그리기 또는 실행에 실패하면 훅은 [`ui.fault`](/docs/ko/plugins/mods/reference#interface) 이벤트를 받습니다. | 터미널, Desktop |

438| `Raster`, `Image` | [색상 셀 그리드](#draw-a-grid-of-colored-cells)와 이미지 | 터미널 |438| `Raster`, `Image` | [색상 셀 그리드](#draw-a-grid-of-colored-cells)와 이미지 | 터미널 |

439 439

440모듈이 `.tsx` 또는 `.jsx` 파일이라면 트리를 JSX로 작성할 수 있습니다. 먼저 `$.ui.resolve(e)`에서 요소를 구조 분해하십시오.440모듈이 `.tsx` 또는 `.jsx` 파일이라면 트리를 JSX로 작성할 수 있습니다. 먼저 `$.ui.resolve(e)`에서 요소를 구조 분해하십시오.

664 요청 없이 Claude Code가 다시 그리는 경우664 요청 없이 Claude Code가 다시 그리는 경우

665</h3>665</h3>

666 666

667Claude Code는 사이트의 prop이 변경되거나 터미널의 너비가 변경되면 `ui.render` 훅을 다시 실행합니다. 타이머에 따라 훅을 실행하지는 않으며, 모듈 안의 변수가 변경되는 시점을 알 수도 없습니다.667Claude Code는 사이트의 prop이 변경되거나 터미널의 너비가 변경되면 `ui.render` 훅을 다시 실행합니다. 사이트의 `Client`가 실패하고 mod가 [`ui.fault`](/docs/ko/plugins/mods/reference#interface)를 처리하는 경우, Claude Code는 `ui.fault` 훅이 반환된 후 훅을 한 번 더 실행하므로 `ui.render` 훅에서 해당 `Client`를 제외할 수 있습니다. 타이머에 따라 훅을 실행하지는 않으며, 모듈 안의 변수가 변경되는 시점을 알 수도 없습니다.

668 668

669<h3 id="redraw-when-your-data-changes">669<h3 id="redraw-when-your-data-changes">

670 데이터가 변경될 때 다시 그리기670 데이터가 변경될 때 다시 그리기

plugins/mods/reference.md +7 −6

Details

6 6

7> Claude Code mod에 대한 전체 참조: 훅 모듈 레이아웃, 이벤트, mods API 메서드, 렌더링 지점, 사용 환경별 요소, 제한 및 설정.7> Claude Code mod에 대한 전체 참조: 훅 모듈 레이아웃, 이벤트, mods API 메서드, 렌더링 지점, 사용 환경별 요소, 제한 및 설정.

8 8

9v2.1.287 기준 Claude Code CLI 및 Desktop 앱에서 [mod](/docs/ko/plugins/mods/overview)가 처리할 수 있는 이벤트, 호출할 수 있는 mods API 메서드, 그릴 수 있는 렌더링 지점을 찾아볼 수 있습니다. 각 항목에는 이름과 한 줄 설명이 있으며, 이를 설명하는 가이드 섹션이 있는 경우 해당 섹션으로 연결됩니다.9v2.1.289 기준 Claude Code CLI 및 Desktop 앱에서 [mod](/docs/ko/plugins/mods/overview)가 처리할 수 있는 이벤트, 호출할 수 있는 mods API 메서드, 그릴 수 있는 렌더링 지점을 찾아볼 수 있습니다. 각 항목에는 이름과 한 줄 설명이 있으며, 이를 설명하는 가이드 섹션이 있는 경우 해당 섹션으로 연결됩니다.

10 10

11<Note>11<Note>

12 전체 참조는 Claude Code의 [mod용 TypeScript 선언](https://github.com/anthropics/claude-code/blob/main/mods/types/claude-code.d.ts)으로, 모든 이벤트, 메서드, 요소를 예제와 함께 설명합니다. GitHub의 사본은 설치된 Claude Code 버전보다 오래된 것일 수 있습니다. 두 내용이 서로 다를 경우 [Claude Code가 해당 버전에 맞게 작성하는 사본](/docs/ko/plugins/mods/create#get-the-types-for-your-build)을 신뢰하십시오.12 전체 참조는 Claude Code의 [mod용 TypeScript 선언](https://github.com/anthropics/claude-code/blob/main/mods/types/claude-code.d.ts)으로, 모든 이벤트, 메서드, 요소를 예제와 함께 설명합니다. GitHub의 사본은 설치된 Claude Code 버전보다 오래된 것일 수 있습니다. 두 내용이 서로 다를 경우 [Claude Code가 해당 버전에 맞게 작성하는 사본](/docs/ko/plugins/mods/create#get-the-types-for-your-build)을 신뢰하십시오.

128 서브에이전트128 서브에이전트

129</h3>129</h3>

130 130

131서브에이전트 이벤트는 서브에이전트 유형이 Claude에 제공될 때와 서브에이전트가 시작되기 직전에 발생합니다.131서브에이전트 이벤트는 서브에이전트 유형이 Claude에 제공될 때와 서브에이전트 또는 에이전트 팀 팀원이 시작되기 직전에 발생합니다.

132 132

133| 이벤트 | 발생 시점 | 훅이 반환할 수 있는 값 |133| 이벤트 | 발생 시점 | 훅이 반환할 수 있는 값 |

134| :- | :- | :- |134| :- | :- | :- |

135| `agent.offer` | 서브에이전트 유형이 Claude에 제공될 때 | 제공하지 않으려면 `{ isOffered: false }` |135| `agent.offer` | 서브에이전트 유형이 Claude에 제공될 때 | 제공하지 않으려면 `{ isOffered: false }` |

136| `agent.spawn` | 서브에이전트가 시작되기 직전 | `{ model }` 또는 `{ deny: reason }` |136| `agent.spawn` | 서브에이전트 또는 [에이전트 팀](/docs/ko/agent-teams) 팀원이 시작되기 직전. 팀원의 경우 `e.isTeammate`는 `true`입니다. | 모델을 선택하려면 `next({ ...e, model })`, 또는 `{ deny: reason }` |

137 137

138<h3 id="interface">138<h3 id="interface">

139 인터페이스139 인터페이스

152| [`ui.fault`](/docs/ko/plugins/mods/interface#redraw-when-something-changes) | mod가 그린 `Client` 요소가 로드, 그리기 또는 실행에 실패했을 때. `e.phase`는 `load`, `render` 또는 `run`이며, `e.reason`은 오류 메시지입니다. Claude Code v2.1.289 이상이 필요합니다. |

152 153

153<h3 id="other-mods">154<h3 id="other-mods">

154 다른 mod155 다른 mod

192| 네임스페이스 | 메서드 |193| 네임스페이스 | 메서드 |

193| :- | :- |194| :- | :- |

195| [`$.ui`](/docs/ko/plugins/mods/interface#pick-where-to-draw) | `resolve`, `invalidate`, `open`, `close`, `panes`, `focus`, `scroll`, `toast`, `status`, `log`, `notice`, `ask`, `copy`, `blit` |196| [`$.ui`](/docs/ko/plugins/mods/interface#pick-where-to-draw) | `resolve`, `invalidate`, `open`, `close`, `panes`, `focus`, `scroll`, `toast`, `status`, `log`, `notice`, `ask`, `copy`, `selection`, `blit` |

276 277

277| 제한 | 값 |278| 제한 | 값 |

278| :- | :- |279| :- | :- |

279| 하나의 이벤트에 대한 훅 자체의 실행 시간(`next` 내부 시간 또는 `$.clock.sleep`을 제외한 mod API 호출 시간은 포함하지 않음) | 10초 |280| 하나의 이벤트에 대한 훅 자체의 실행 시간(`next` 내부 시간 또는 `$.clock.sleep`을 제외한 mod API 호출 시간은 포함하지 않음) | 10초, `prompt.edit` 훅의 경우 50밀리초 |

280| `.catch` 핸들러의 실행 시간 | 1초 |281| `.catch` 핸들러의 실행 시간 | 1초 |

281| 모든 `session.end` 훅의 합계 | 1.5초 |282| 모든 `session.end` 훅의 합계 | [SessionEnd 훅 예산](/docs/ko/hooks#sessionend-input)만큼(변경하지 않으면 1.5초), 설정의 `SessionEnd` 훅이 완료된 시점부터 계산 |

plugins/troubleshooting.md +1 −1

Details

1016 1016

1017이 순서대로 이러한 원인을 확인합니다:1017이 순서대로 이러한 원인을 확인합니다:

1018 1018

1019* **스킬이 `disable-model-invocation: true`를 설정**: 해당 필드가 설정되면 사용자만 스킬을 호출할 수 있습니다. [첫 번째 플러그인 만들기](/docs/ko/plugins/create#create-your-first-plugin)의 템플릿 스킬이 설정합니다. Claude가 스스로 호출하기를 원하는 스킬에서 해당 줄을 제거합니다. [스킬을 호출할 수 있는 사람 제어](/docs/ko/skills#control-who-invokes-a-skill)는 필드를 다룹니다.1019* **스킬이 `disable-model-invocation: true`를 설정**: [첫 번째 플러그인 만들기](/docs/ko/plugins/create#create-your-first-plugin)의 템플릿 스킬이 설정합니다. Claude가 스스로 호출하기를 원하는 스킬에서 해당 줄을 제거합니다. [스킬을 호출할 수 있는 사람 제어](/docs/ko/skills#control-who-invokes-a-skill)는 필드를 다룹니다.

1020* **설명이 사람들이 요청하는 방식과 일치하지 않음**: [스킬이 트리거되지 않음](/docs/ko/skills#skill-not-triggering)의 확인을 진행합니다.1020* **설명이 사람들이 요청하는 방식과 일치하지 않음**: [스킬이 트리거되지 않음](/docs/ko/skills#skill-not-triggering)의 확인을 진행합니다.

1021* **설명이 잘림**: 많은 스킬이 설치되면 Claude Code가 설명을 단축하여 목록의 문자 예산에 맞추고 Claude가 요청과 일치하는 데 필요한 키워드를 제거할 수 있습니다. [스킬 설명이 짧게 잘림](/docs/ko/skills#skill-descriptions-are-cut-short)을 참조합니다.1021* **설명이 잘림**: 많은 스킬이 설치되면 Claude Code가 설명을 단축하여 목록의 문자 예산에 맞추고 Claude가 요청과 일치하는 데 필요한 키워드를 제거할 수 있습니다. [스킬 설명이 짧게 잘림](/docs/ko/skills#skill-descriptions-are-cut-short)을 참조합니다.

1022 1022

sandboxing.md +1 −1

Details

463 463

464마스킹에는 다음이 필요합니다:464마스킹에는 다음이 필요합니다:

465 465

466* **TLS 종료**: 프록시는 요청 내용 안에서 실제 값을 치환하므로 내용을 볼 수 있어야 합니다. 프록시가 TLS를 직접 종료하도록 [`network.tlsTerminate`](/docs/ko/settings-reference#sandbox-network-tlsterminate)를 설정합니다. 이 설정이 없으면 마스킹은 아무것도 노출하지 않은 채 실패합니다. 명령은 여전히 센티널만 보지만, 센티널이 변경되지 않은 채 서버에 도달하여 인증이 실패합니다. Claude Code는 시작 시 이 잘못된 구성을 보고합니다.466* **TLS 종료**: 프록시는 요청 내용 안에서 실제 값을 치환하므로 내용을 볼 수 있어야 합니다. 프록시가 TLS를 직접 종료하도록 [`network.tlsTerminate`](/docs/ko/settings-reference#sandbox-network-tlsterminate)를 설정합니다. 이 설정이 없으면 마스킹은 아무것도 노출하지 않은 채 실패합니다. 명령은 여전히 센티널만 보지만, 센티널이 변경되지 않은 채 서버에 도달하여 인증이 실패합니다. 이 잘못된 구성을 확인하려면 터미널에서 `claude doctor`를 실행하고 `TLS termination is unavailable` 경고가 있는지 살펴봅니다.

467* **허용된 대상**: 각 `mask` 항목에는 실제 값이 도달할 수 있는 호스트인 `injectHosts`를 나열할 수 있습니다. 프록시는 [도메인 허용 목록](#network-isolation)이 허용하는 연결에만 주입하므로, 각 `injectHosts` 호스트는 `network.allowedDomains`를 통해서도 접근 가능해야 합니다. `injectHosts`가 없는 `mask` 항목의 경우, 프록시는 `network.allowedDomains`의 모든 호스트에 대한 요청에서 실제 값을 치환합니다.467* **허용된 대상**: 각 `mask` 항목에는 실제 값이 도달할 수 있는 호스트인 `injectHosts`를 나열할 수 있습니다. 프록시는 [도메인 허용 목록](#network-isolation)이 허용하는 연결에만 주입하므로, 각 `injectHosts` 호스트는 `network.allowedDomains`를 통해서도 접근 가능해야 합니다. `injectHosts`가 없는 `mask` 항목의 경우, 프록시는 `network.allowedDomains`의 모든 호스트에 대한 요청에서 실제 값을 치환합니다.

468* **신뢰할 수 있는 설정 범위**: 마스킹은 프록시가 실제 자격 증명을 어딘가로 보내도록 승인하므로, Claude Code는 `mask` 항목, `network.tlsTerminate`, [`credentials.allowPlaintextInject`](/docs/ko/settings-reference#sandbox-credentials-allowplaintextinject), `awsPairs`, `sigv4`를 사용자 설정, 관리형 설정, `--settings` 플래그에서만 적용합니다. 저장소의 `.claude/settings.json` 또는 `.claude/settings.local.json`에 있는 이러한 항목은 무시합니다. 관리자가 서버 관리형 설정을 통해 `mask` 항목, `network.tlsTerminate` 또는 `credentials.allowPlaintextInject`를 제공하는 경우, 이는 [승인이 필요한 설정](/docs/ko/server-managed-settings#security-approval-dialogs)으로 간주됩니다.468* **신뢰할 수 있는 설정 범위**: 마스킹은 프록시가 실제 자격 증명을 어딘가로 보내도록 승인하므로, Claude Code는 `mask` 항목, `network.tlsTerminate`, [`credentials.allowPlaintextInject`](/docs/ko/settings-reference#sandbox-credentials-allowplaintextinject), `awsPairs`, `sigv4`를 사용자 설정, 관리형 설정, `--settings` 플래그에서만 적용합니다. 저장소의 `.claude/settings.json` 또는 `.claude/settings.local.json`에 있는 이러한 항목은 무시합니다. 관리자가 서버 관리형 설정을 통해 `mask` 항목, `network.tlsTerminate` 또는 `credentials.allowPlaintextInject`를 제공하는 경우, 이는 [승인이 필요한 설정](/docs/ko/server-managed-settings#security-approval-dialogs)으로 간주됩니다.

469 469

self-hosted-environments-deploy.md +19 −0

Details

195 195

196러너는 또한 등록할 때 Anthropic에 옵트인을 보고하며, 시작 시 `Registering as opted in to Anthropic-managed git (--use-anthropic-git-proxy)`를 출력합니다. 옵트인 보고에는 Claude Code v2.1.267 이상이 필요하며, 이전 버전은 플래그를 수락하지만 이를 보고하거나 해당 라인을 출력하지 않습니다. 옵트인된 러너의 각 세션은 Anthropic 관리 git 또는 세션별 프록시 URL을 사용합니다. 세션이 세션별 프록시 URL을 사용할 때 러너는 그렇게 하는 것을 나타내는 `[runner:warn]` 라인 하나를 기록합니다.196러너는 또한 등록할 때 Anthropic에 옵트인을 보고하며, 시작 시 `Registering as opted in to Anthropic-managed git (--use-anthropic-git-proxy)`를 출력합니다. 옵트인 보고에는 Claude Code v2.1.267 이상이 필요하며, 이전 버전은 플래그를 수락하지만 이를 보고하거나 해당 라인을 출력하지 않습니다. 옵트인된 러너의 각 세션은 Anthropic 관리 git 또는 세션별 프록시 URL을 사용합니다. 세션이 세션별 프록시 URL을 사용할 때 러너는 그렇게 하는 것을 나타내는 `[runner:warn]` 라인 하나를 기록합니다.

197 197

198<h4 id="github-api-access-without-the-github-cli">

199 GitHub CLI 없이 GitHub API 액세스

200</h4>

201

202러너 이미지에 GitHub CLI가 포함되어 있지 않은 경우 Claude Code가 내장 `gh`를 제공할 수 있으므로 Claude는 여전히 풀 리퀘스트를 열고, 댓글을 달고, CI 결과를 읽을 수 있습니다. 내장 `gh`는 Anthropic 관리 git을 사용하는 러너를 위한 것입니다. GitHub의 REST API를 호출하는 `gh api` 명령 하나를 지원합니다. 러너 이미지에 Claude Code v2.1.287 이상이 필요합니다.

203

204다음 명령은 `gh pr create` 대신 풀 리퀘스트를 엽니다. 내장 `gh`는 현재 저장소에 대해 `{owner}` 및 `{repo}`를 채웁니다:

205

206```bash theme={null}

207gh api repos/{owner}/{repo}/pulls -f title='Fix' -f head='my-branch' -f base='main'

208```

209

210* **자격 증명**: 내장 `gh`는 REST 요청을 Anthropic 관리 git을 통해 보내며, Anthropic 관리 git이 Anthropic 측에서 GitHub 자격 증명을 제공하므로 이미지에는 이를 위한 GitHub 토큰이 필요하지 않습니다

211* **어떤 세션이 사용할 수 있는지**: Anthropic은 Anthropic 관리 git이 세션의 `gh`를 제공할지 세션별로 결정합니다. 제공하는 경우 러너가 세션에 대해 기록하는 `[runner:session] governed git ACTIVE` 라인에 `gh_path_shim=true`가 표시됩니다. 제공하지 않는 경우 세션에는 `gh`가 없습니다

212* **`jq`**: `--jq`가 작동하도록 하려면 이미지에 `jq`를 설치하세요

213* **[`CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC`](/docs/ko/env-vars)**: 세션 환경에서 이를 설정하면 Claude Code는 내장 `gh`를 제공하지 않으며 세션에는 `gh`가 없습니다

214

215이미지에 GitHub CLI가 포함되어 있으면 세션은 이를 사용합니다.

216

198<h4 id="trust-a-private-certificate-authority-with-anthropic-managed-git">217<h4 id="trust-a-private-certificate-authority-with-anthropic-managed-git">

199 Anthropic 관리 git으로 개인 인증 기관 신뢰218 Anthropic 관리 git으로 개인 인증 기관 신뢰

200</h4>219</h4>

self-hosted-environments-quickstart.md +1 −1

Details

117claude -p "your message" --cloud <session-id>117claude -p "your message" --cloud <session-id>

118```118```

119 119

120`<session-id>`의 경우, 베어 `session_...` 또는 `cse_...` ID 또는 세션의 claude.ai/code URL을 전달하세요. 성공적인 전송은 세션 ID 및 보기 링크와 함께 `Sent to cloud session.`을 인쇄합니다. 수락된 ID 형식, JSON 출력, 계정 및 정책 요구 사항, 오류 참조는 [CLI에서 후속 메시지 전송](/docs/ko/claude-code-on-the-web#send-follow-ups-from-the-cli)에 있습니다. 명령은 Anthropic 호스팅 세션에 대해 동일하게 작동하기 때문입니다.120`<session-id>`의 경우, 베어 `session_...` 또는 `cse_...` ID 또는 세션의 claude.ai/code URL을 전달하세요. 성공적인 전송은 세션 ID 및 보기 링크와 함께 `Sent to cloud session.`을 인쇄합니다. 수락된 ID 형식, JSON 출력, 계정 및 정책 요구 사항은 [CLI에서 후속 메시지 전송](/docs/ko/claude-code-on-the-web#send-follow-ups-from-the-cli)에 있습니다. 명령은 Anthropic 호스팅 세션에 대해 동일하게 작동하기 때문입니다.

121 121

122<h2 id="what’s-next">122<h2 id="what’s-next">

123 다음 단계123 다음 단계

server-managed-settings.md +4 −4

Details

6 6

7> 기기 관리 인프라 없이 서버 전달 설정을 통해 조직을 위해 Claude Code를 중앙에서 구성합니다.7> 기기 관리 인프라 없이 서버 전달 설정을 통해 조직을 위해 Claude Code를 중앙에서 구성합니다.

8 8

9서버 관리 설정을 통해 조직 소유자는 claude.ai 콘솔의 [**관리자 설정 > Claude Code > 관리 설정**](https://claude.ai/admin-settings/claude-code)에서 Claude Code를 중앙에서 구성할 수 있습니다. Claude Code 클라이언트는 사용자가 적격 자격증명으로 인증하고 서버 관리 전달이 지원되는 플랫폼에서 이러한 설정을 자동으로 가져옵니다. 적격 자격증명 및 플랫폼에 대해서는 [플랫폼 가용성](#platform-availability)을 참조하십시오.9서버 관리형 설정을 통해 조직 소유자는 claude.ai 콘솔의 [**조직 설정 > Claude Code > 관리형 설정**](https://claude.ai/admin-settings/claude-code)에서 Claude Code를 중앙에서 구성할 수 있습니다. Claude Code 클라이언트는 서버 관리형 전달이 지원되는 플랫폼에서 사용자가 적격 자격 증명으로 인증하면 이러한 설정을 자동으로 가져옵니다. 적격 자격 증명 및 플랫폼에 대해서는 [플랫폼 가용성](#platform-availability)을 참조하십시오.

10 10

11<Note>11<Note>

12 서버 관리 설정은 [Claude for Teams](https://claude.com/pricing?utm_source=claude_code\&utm_medium=docs\&utm_content=server_settings_teams#team-&-enterprise) 및 [Claude for Enterprise](https://anthropic.com/contact-sales?utm_source=claude_code\&utm_medium=docs\&utm_content=server_settings_enterprise) 고객에게 제공됩니다.12 서버 관리 설정은 [Claude for Teams](https://claude.com/pricing?utm_source=claude_code\&utm_medium=docs\&utm_content=server_settings_teams#team-&-enterprise) 및 [Claude for Enterprise](https://anthropic.com/contact-sales?utm_source=claude_code\&utm_medium=docs\&utm_content=server_settings_enterprise) 고객에게 제공됩니다.

41 41

42<Steps>42<Steps>

43 <Step title="관리 콘솔 열기">43 <Step title="관리 콘솔 열기">

~~44 claude.ai 콘솔에서 [**관리 설정 > Claude Code > 관리 설정**](https://claude.ai/admin-settings/claude-code)으로 이동합니다.~~44 claude.ai 콘솔에서 [**조직 설정 > Claude Code > 관리형 설정**](https://claude.ai/admin-settings/claude-code)으로 이동합니다.

45 45

46 링크가 Claude Code 페이지 대신 다른 관리 설정 페이지로 리디렉션되면 계정에 필요한 역할이 없습니다. 관리자 및 기타 비 소유자 역할은 관리 설정을 보거나 편집할 수 없으므로 조직의 소유자 또는 주 소유자에게 변경을 요청하십시오. [액세스 제어](#access-control)를 참조하십시오.46 링크가 Claude Code 페이지 대신 다른 조직 설정 페이지로 리디렉션되면 계정에 필요한 역할이 없습니다. Admin 및 Owner가 아닌 기타 역할은 관리형 설정을 보거나 편집할 수 없으므로 조직의 Owner 또는 Primary Owner에게 변경을 요청하십시오. [액세스 제어](#access-control)를 참조하십시오.

47 </Step>47 </Step>

48 48

49 <Step title="설정 정의">49 <Step title="설정 정의">

50 구성을 JSON으로 추가합니다. [`settings.json`에서 사용 가능한 모든 설정](/docs/ko/settings-reference#all-settings)이 지원되며, OS 수준 정책 전달로 제한된 설정을 제외합니다. [현재 제한사항](#current-limitations)에서 해당 짧은 목록을 참조하십시오. 여기에는 [hooks](/docs/ko/hooks), [환경 변수](/docs/ko/env-vars), 및 `allowManagedPermissionRulesOnly`와 같은 [관리 전용 설정](/docs/ko/managed-settings#managed-only-settings)이 포함됩니다.50 구성을 JSON으로 추가합니다. [`settings.json`에서 사용 가능한 모든 설정](/docs/ko/settings-reference#all-settings)이 지원되며, OS 수준 정책 전달로 제한된 설정을 제외합니다. [현재 제한사항](#current-limitations)에서 해당 짧은 목록을 참조하십시오. 여기에는 [훅](/docs/ko/hooks), [환경 변수](/docs/ko/env-vars), 및 `allowManagedPermissionRulesOnly`와 같은 [관리 전용 설정](/docs/ko/managed-settings#managed-only-settings)이 포함됩니다.

51 51

52 이 예제는 권한 거부 목록을 적용하고, 사용자가 권한을 우회하는 것을 방지하며, 권한 규칙을 관리 설정에 정의된 규칙으로만 제한합니다. `Bash(curl *)` 규칙은 `/usr/bin/curl` 또는 `sh -c 'curl …'`이 아닌 [Claude가 작성하는 방식](/docs/ko/permissions#bash-rule-limits)으로 `curl`과 일치합니다. 명령 텍스트에 의존하지 않는 네트워크 적용의 경우 [`sandbox` 블록에 `allowManagedDomainsOnly`](/docs/ko/sandboxing#configure-the-sandbox-for-your-organization)를 추가합니다.52 이 예제는 권한 거부 목록을 적용하고, 사용자가 권한을 우회하는 것을 방지하며, 권한 규칙을 관리 설정에 정의된 규칙으로만 제한합니다. `Bash(curl *)` 규칙은 `/usr/bin/curl` 또는 `sh -c 'curl …'`이 아닌 [Claude가 작성하는 방식](/docs/ko/permissions#bash-rule-limits)으로 `curl`과 일치합니다. 명령 텍스트에 의존하지 않는 네트워크 적용의 경우 [`sandbox` 블록에 `allowManagedDomainsOnly`](/docs/ko/sandboxing#configure-the-sandbox-for-your-organization)를 추가합니다.

53 53

sessions.md +1 −0

Details

288| [Claude Desktop 및 Cowork 기록](/docs/ko/claude-directory#cleaned-up-automatically)에 대한 나이 제한 설정 | [`desktopSessionCleanupPeriodDays`](/docs/ko/settings-reference#desktopsessioncleanupperioddays) | 사용자 설정, 관리 설정 또는 `--settings` |288| [Claude Desktop 및 Cowork 기록](/docs/ko/claude-directory#cleaned-up-automatically)에 대한 나이 제한 설정 | [`desktopSessionCleanupPeriodDays`](/docs/ko/settings-reference#desktopsessioncleanupperioddays) | 사용자 설정, 관리 설정 또는 `--settings` |

289| `-p` 또는 Agent SDK 세션의 트랜스크립트 파일 크기 증가 제한 | [`CLAUDE_CODE_TRANSCRIPT_LOCAL_GC`](/docs/ko/env-vars) | 환경 변수 |

291 292

settings-reference.md +3 −1

Details

990 990

991조직에서 관리형 설정을 배포하는 경우 Claude Code는 관리형 소스에서만 이 키를 읽고 다른 파일의 이 키는 무시합니다.991조직에서 관리형 설정을 배포하는 경우 Claude Code는 관리형 소스에서만 이 키를 읽고 다른 파일의 이 키는 무시합니다.

992 992

993시작 시 모델 검사에 이 키가 어떻게 적용되는지는 [Amazon Bedrock](/docs/ko/amazon-bedrock#when-your-organization-enforces-a-model-allowlist) 및 [Google Cloud의 Agent Platform](/docs/ko/google-vertex-ai#when-your-organization-enforces-a-model-allowlist)을 참조하세요.

994

993* **범위**: [`Any file`](#scopes)995* **범위**: [`Any file`](#scopes)

994* **유형**: Boolean996* **유형**: Boolean

995 * `true`: **Default**가 `availableModels` 밖의 모델로 해석될 경우 Claude Code는 목록에서 처음으로 사용 가능한 모델로 해석합니다997 * `true`: **Default**가 `availableModels` 밖의 모델로 해석될 경우 Claude Code는 목록에서 처음으로 사용 가능한 모델로 해석합니다

3135* [`CLAUDE_CODE_PROJECT_DIR_NAME`](/docs/ko/sessions#name-the-project-directory-yourself)는 Claude Code가 시작 환경에서만 읽으므로 모든 파일에서 무시됩니다. v2.1.234 이상이 필요합니다.3137* [`CLAUDE_CODE_PROJECT_DIR_NAME`](/docs/ko/sessions#name-the-project-directory-yourself)는 Claude Code가 시작 환경에서만 읽으므로 모든 파일에서 무시됩니다. v2.1.234 이상이 필요합니다.

3136* [`CLAUDE_CODE_RESTRICTED`](/docs/ko/env-vars#variables)는 Claude Code가 시작 환경에서만 읽으므로 모든 파일에서 무시됩니다.3138* [`CLAUDE_CODE_RESTRICTED`](/docs/ko/env-vars#variables)는 Claude Code가 시작 환경에서만 읽으므로 모든 파일에서 무시됩니다.

3137* [`CLAUDE_CODE_DISABLE_POWERSHELL_CMD_RM_DENY`](/docs/ko/env-vars#variables)는 Claude Code가 시작 환경에서만 읽으므로 모든 파일에서 무시됩니다. 변수는 Claude Code v2.1.283 이상이 필요합니다.3139* [`CLAUDE_CODE_DISABLE_POWERSHELL_CMD_RM_DENY`](/docs/ko/env-vars#variables)는 Claude Code가 시작 환경에서만 읽으므로 모든 파일에서 무시됩니다. 변수는 Claude Code v2.1.283 이상이 필요합니다.

3138* [`CLAUDE_CODE_DISABLE_DANGEROUS_RM_TIMEOUT` 및 `CLAUDE_CODE_DISABLE_SUBSTITUTION_RM_PROMPT`](/docs/ko/env-vars#variables)는 Claude Code가 시작 환경에서만 읽으므로 모든 파일에서 무시됩니다.3140* [`CLAUDE_CODE_DISABLE_DANGEROUS_RM_TIMEOUT`, `CLAUDE_CODE_DISABLE_SUBSTITUTION_RM_PROMPT` 및 `CLAUDE_CODE_DISABLE_INLINE_SHELL_RM_PROMPT`](/docs/ko/env-vars#variables)는 Claude Code가 시작 환경에서만 읽으므로 모든 파일에서 무시됩니다.

3139 3141

3140<h3 id="filecheckpointingenabled">3142<h3 id="filecheckpointingenabled">

3141 `fileCheckpointingEnabled`3143 `fileCheckpointingEnabled`

skills.md +16 −3

Details

561 561

562기본적으로 사용자와 Claude 모두 모든 스킬을 호출할 수 있습니다. `/skill-name`을 입력하여 직접 호출할 수 있고 Claude는 대화와 관련이 있을 때 자동으로 로드할 수 있습니다. 두 개의 frontmatter 필드를 사용하여 이를 제한할 수 있습니다.562기본적으로 사용자와 Claude 모두 모든 스킬을 호출할 수 있습니다. `/skill-name`을 입력하여 직접 호출할 수 있고 Claude는 대화와 관련이 있을 때 자동으로 로드할 수 있습니다. 두 개의 frontmatter 필드를 사용하여 이를 제한할 수 있습니다.

563 563

564* **`disable-model-invocation: true`**: 사용자만 스킬을 호출할 수 있습니다. `/commit`, `/deploy` 또는 `/send-slack-message`와 같이 부작용이 있거나 타이밍을 제어하려는 워크플로에 사용합니다. 코드가 준비된 것처럼 보인다는 이유로 Claude가 배포를 결정해서는 안 됩니다.564* **`disable-model-invocation: true`**: Claude가 자체적으로 스킬을 호출할 수 없습니다. `/commit`, `/deploy` 또는 `/send-slack-message`와 같이 부작용이 있거나 타이밍을 제어하려는 워크플로에 사용합니다. 코드가 준비된 것처럼 보인다는 이유로 Claude가 배포를 결정해서는 안 됩니다.

565 565

566* **`user-invocable: false`**: Claude만 스킬을 호출할 수 있습니다. 명령으로 실행할 수 없는 배경 지식에 사용합니다. `legacy-system-context` 스킬은 이전 시스템이 어떻게 작동하는지 설명합니다. Claude는 관련이 있을 때 이를 알아야 하지만 `/legacy-system-context`는 사용자가 취할 의미 있는 작업이 아닙니다.566* **`user-invocable: false`**: Claude만 스킬을 호출할 수 있습니다. 명령으로 실행할 수 없는 배경 지식에 사용합니다. `legacy-system-context` 스킬은 이전 시스템이 어떻게 작동하는지 설명합니다. Claude는 관련이 있을 때 이를 알아야 하지만 `/legacy-system-context`는 사용자가 취할 의미 있는 작업이 아닙니다.

567 567

568이 예제는 사용자만 트리거할 수 있는 배포 스킬을 만듭니다. `disable-model-invocation: true`를 설정하면 Claude는 스킬을 자동으로 실행할 수 없습니다.568이 예제는 배포 스킬을 만듭니다. `disable-model-invocation: true`를 설정하면 Claude는 스킬을 자동으로 실행할 수 없습니다.

569 569

570```yaml theme={null}570```yaml theme={null}

571---571---

590| :- | :- | :- | :- |590| :- | :- | :- | :- |

591| (기본값) | 예 | 예 | 설명은 항상 컨텍스트에 있고, 호출될 때 전체 스킬이 로드됨 |591| (기본값) | 예 | 예 | 설명은 항상 컨텍스트에 있고, 호출될 때 전체 스킬이 로드됨 |

592| `disable-model-invocation: true` | 예 | 아니요 | 설명은 컨텍스트에 없고, 사용자가 호출할 때 전체 스킬이 로드됨 |592| `disable-model-invocation: true` | 예 | 자체적으로는 불가 | 설명은 컨텍스트에 없고, 호출될 때 전체 스킬이 로드됨 |

593| `user-invocable: false` | 아니요 | 예 | 설명은 항상 컨텍스트에 있고, 호출될 때 전체 스킬이 로드됨 |593| `user-invocable: false` | 아니요 | 예 | 설명은 항상 컨텍스트에 있고, 호출될 때 전체 스킬이 로드됨 |

594 594

595<Note>595<Note>

596 일반 세션에서 스킬 설명은 Claude가 사용 가능한 것을 알 수 있도록 컨텍스트에 로드되지만 전체 스킬 콘텐츠는 호출될 때만 로드됩니다. [사전 로드된 스킬이 있는 서브에이전트](/docs/ko/sub-agents#preload-skills-into-subagents)는 다르게 작동합니다. 전체 스킬 콘텐츠는 시작 시 주입됩니다.596 일반 세션에서 스킬 설명은 Claude가 사용 가능한 것을 알 수 있도록 컨텍스트에 로드되지만 전체 스킬 콘텐츠는 호출될 때만 로드됩니다. [사전 로드된 스킬이 있는 서브에이전트](/docs/ko/sub-agents#preload-skills-into-subagents)는 다르게 작동합니다. 전체 스킬 콘텐츠는 시작 시 주입됩니다.

597</Note>597</Note>

598 598

599<h4 id="where-you-write-the-skill’s-name">

600 스킬 이름을 작성하는 위치

601</h4>

602

603스킬을 직접 실행하려면 메시지 시작 부분에 스킬 이름을 입력합니다. 일반 텍스트 뒤에 오는 이름은 Claude에게 스킬을 실행할 권한을 부여하지만 스킬을 실행하지는 않습니다.

604

605| 위치 | 예제 | 동작 |

606| :- | :- | :- |

607| 메시지 시작 부분 | `/deploy staging` | Claude Code가 스킬을 직접 실행함 |

608| 일반 텍스트 뒤, 구두점이 붙지 않은 별도의 단어 | `go ahead and /deploy to staging` | 직접 실행되는 것은 없습니다. 이름은 해당 메시지에 대한 사용자의 권한으로 간주됩니다. Claude는 응답하는 동안 스킬을 실행할 수 있으며, 사용자의 표현을 보고 실행을 요청했는지 판단합니다 |

609

610실행을 허용하지 않고 스킬에 대해 언급하려면 슬래시를 생략합니다.

611

599<h3 id="skill-content-lifecycle">612<h3 id="skill-content-lifecycle">

600 스킬 콘텐츠 수명 주기613 스킬 콘텐츠 수명 주기

601</h3>614</h3>

sub-agents.md +1 −1

Details

632 632

633나열된 각 스킬의 전체 내용은 시작 시 서브에이전트의 컨텍스트에 주입됩니다. 이 필드는 서브에이전트가 실행 중에 발견하고 호출할 수 있는 스킬을 제어하지 않습니다. 이 필드는 미리 로드할 스킬을 제어합니다. 이 필드 없이, 서브에이전트는 여전히 실행 중에 스킬 도구를 통해 프로젝트, 사용자, 및 플러그인 스킬을 발견하고 호출할 수 있습니다. 서브에이전트가 스킬을 완전히 호출하지 못하도록 하려면, [`tools`](#available-tools) 목록에서 `Skill`을 생략하거나 `disallowedTools`에 추가하세요.633나열된 각 스킬의 전체 내용은 시작 시 서브에이전트의 컨텍스트에 주입됩니다. 이 필드는 서브에이전트가 실행 중에 발견하고 호출할 수 있는 스킬을 제어하지 않습니다. 이 필드는 미리 로드할 스킬을 제어합니다. 이 필드 없이, 서브에이전트는 여전히 실행 중에 스킬 도구를 통해 프로젝트, 사용자, 및 플러그인 스킬을 발견하고 호출할 수 있습니다. 서브에이전트가 스킬을 완전히 호출하지 못하도록 하려면, [`tools`](#available-tools) 목록에서 `Skill`을 생략하거나 `disallowedTools`에 추가하세요.

634 634

635[`disable-model-invocation: true`](/docs/ko/skills#control-who-invokes-a-skill)를 설정하는 스킬은 미리 로드할 수 없습니다. 미리 로드는 Claude가 호출할 수 있는 동일한 스킬 세트에서 그리기 때문입니다. 여기에는 번들된 `/verify` 스킬이 포함됩니다. 오직 사용자만 실행할 수 있으므로 미리 로드할 수 없습니다.635[`disable-model-invocation: true`](/docs/ko/skills#control-who-invokes-a-skill)를 설정한 스킬은 미리 로드할 수 없습니다. 미리 로드는 Claude가 호출할 수 있는 스킬 세트에서 가져오기 때문입니다. 여기에는 Claude가 스스로 실행할 수 없는 번들 `/verify` 스킬도 포함됩니다.

636 636

637나열된 스킬이 누락되거나 비활성화되면(예: 조직의 정책에 의해), Claude Code는 건너뛰고 디버그 로그에 경고를 기록합니다.637나열된 스킬이 누락되거나 비활성화되면(예: 조직의 정책에 의해), Claude Code는 건너뛰고 디버그 로그에 경고를 기록합니다.

638 638

tools-reference.md +13 −0

Details

487 487

488Claude Code는 프로세스 범위에서만 `-ExecutionPolicy Bypass`를 사용하여 PowerShell을 생성하므로, `.ps1` 스크립트 및 모듈 가져오기는 머신의 정책을 변경하지 않고도 기본 Windows 설치에서 작동합니다. 프로세스 범위 바이패스는 Group Policy `MachinePolicy` 또는 `UserPolicy`를 재정의하지 않으므로, 엔터프라이즈 정책이 여전히 적용됩니다. 머신의 유효한 실행 정책을 대신 존중하려면 `CLAUDE_CODE_POWERSHELL_RESPECT_EXECUTION_POLICY=1`을 설정합니다.488Claude Code는 프로세스 범위에서만 `-ExecutionPolicy Bypass`를 사용하여 PowerShell을 생성하므로, `.ps1` 스크립트 및 모듈 가져오기는 머신의 정책을 변경하지 않고도 기본 Windows 설치에서 작동합니다. 프로세스 범위 바이패스는 Group Policy `MachinePolicy` 또는 `UserPolicy`를 재정의하지 않으므로, 엔터프라이즈 정책이 여전히 적용됩니다. 머신의 유효한 실행 정책을 대신 존중하려면 `CLAUDE_CODE_POWERSHELL_RESPECT_EXECUTION_POLICY=1`을 설정합니다.

489 489

490<h3 id="bash-deny-rules-also-turn-off-the-powershell-tool">

491 Bash 거부 규칙은 PowerShell 도구도 끕니다

492</h3>

493

494Git Bash가 설치된 Windows에서 Bash를 거부하면 해당 세션에서 PowerShell 도구도 꺼집니다. 이는 단독 `Bash`뿐 아니라 `Bash(git push *)`와 같은 범위 지정 규칙에도 적용되며, 설정 파일 중 하나 또는 `--disallowedTools`에서 지정된 규칙에도 적용됩니다. Claude Code가 이렇게 하는 이유는 `Bash` 규칙이 [자체 권한 규칙](/docs/ko/permissions#powershell)을 가진 PowerShell 도구를 제한하지 않기 때문입니다. PowerShell이 켜진 상태로 남아 있으면 Claude는 규칙이 Bash에서 거부하는 작업을 PowerShell에서 실행할 수 있습니다.

495

496Bash 거부 규칙과 함께 PowerShell 도구를 켜 두려면 다음 중 하나를 수행합니다.

497

498* [PowerShell 도구 활성화](#enable-the-powershell-tool)에 표시된 대로 환경 또는 설정 파일의 `env` 블록에서 `CLAUDE_CODE_USE_POWERSHELL_TOOL=1`을 설정합니다.

499* `PowerShell(git push *)` 거부 규칙과 같은 범위 지정 [`PowerShell` 권한 규칙](/docs/ko/permissions#powershell)을 설정 파일에 추가합니다.

500

501이 중 하나가 없으면 범위 지정 Bash 거부 규칙은 Bash 도구를 사용 가능한 상태로 두지만, Claude Code는 경고 없이 PowerShell을 끕니다. Bash 도구 전체를 제거하는 규칙은 해당 세션에서 Claude가 사용할 수 있는 셸 도구를 하나도 남기지 않습니다.

502

490<h3 id="shell-selection-in-settings-hooks-and-skills">503<h3 id="shell-selection-in-settings-hooks-and-skills">

491 설정, hooks 및 skills의 셸 선택504 설정, hooks 및 skills의 셸 선택

492</h3>505</h3>

web-quickstart.md +4 −4

Details

62GitHub 연결은 일회성 단계입니다. 이미 GitHub CLI를 사용하는 경우, 브라우저 대신 [터미널에서 이를 수행](#connect-from-your-terminal)할 수 있습니다.62GitHub 연결은 일회성 단계입니다. 이미 GitHub CLI를 사용하는 경우, 브라우저 대신 [터미널에서 이를 수행](#connect-from-your-terminal)할 수 있습니다.

63 63

64<Note>64<Note>

65 Team 및 Enterprise 플랜에서 **GitHub로 로그인** 단계는 Claude 조직의 [Owner](/docs/ko/server-managed-settings#access-control)가 [**Admin settings > Connectors**](https://claude.ai/admin-settings/connectors)에서 GitHub 커넥터를 켠 후에만 작동합니다. 그때까지 해당 단계는 로그인 버튼 대신 "GitHub access is required for Claude Code on the web"을 표시합니다. 커넥터가 켜진 후 [claude.ai/code](https://claude.ai/code)를 다시 로드하고 첫 번째 단계부터 다시 시작합니다. [**Admin settings > Claude Code**](https://claude.ai/admin-settings/claude-code)의 [Quick web setup](/docs/ko/claude-code-on-the-web#github-authentication-options)이라는 두 번째 토글은 선택 사항입니다. 이를 켜면 `/web-setup`이 작동하고 온보딩이 멤버를 위한 환경을 생성합니다.65 Team 및 Enterprise 플랜에서 **GitHub로 로그인** 단계는 Claude 조직의 [Owner](/docs/ko/server-managed-settings#access-control)가 [**Organization settings > Connectors**](https://claude.ai/admin-settings/connectors)에서 GitHub 커넥터를 켠 후에만 작동합니다. 그때까지 해당 단계는 로그인 버튼 대신 "GitHub access is required for Claude Code cloud sessions"를 표시합니다. 커넥터가 켜진 후 [claude.ai/code](https://claude.ai/code)를 다시 로드하고 첫 번째 단계부터 다시 시작합니다. [**Organization settings > Claude Code**](https://claude.ai/admin-settings/claude-code)의 [Quick setup](/docs/ko/claude-code-on-the-web#quick-setup-for-team-and-enterprise)이라는 두 번째 토글은 선택 사항입니다. 이를 켜면 `/web-setup`이 작동하고 온보딩이 멤버를 위한 환경을 생성합니다.

66</Note>66</Note>

67 67

68<Steps>68<Steps>

84 [cloud environment](/docs/ko/cloud-environments)는 세션 중에 Claude가 가진 네트워크 접근 권한과 세션이 시작될 때 실행되는 것을 제어하는 저장된 구성입니다. GitHub를 연결한 후 발생하는 일은 플랜에 따라 다릅니다:84 [cloud environment](/docs/ko/cloud-environments)는 세션 중에 Claude가 가진 네트워크 접근 권한과 세션이 시작될 때 실행되는 것을 제어하는 저장된 구성입니다. GitHub를 연결한 후 발생하는 일은 플랜에 따라 다릅니다:

85 85

86 * **Pro and Max**: 온보딩이 **Default**라는 환경을 생성합니다.86 * **Pro and Max**: 온보딩이 **Default**라는 환경을 생성합니다.

87 * **Team and Enterprise**: 온보딩이 **Create your first cloud environment** 양식을 표시합니다. 미리 채워진 이름과 네트워크 접근을 변경하지 않고 **Create & finish**를 클릭하여 **Default** 환경을 생성합니다. Owner가 [Quick web setup](/docs/ko/claude-code-on-the-web#github-authentication-options)을 켠 경우 온보딩이 대신 **Default**를 생성합니다.87 * **Team and Enterprise**: 온보딩이 **Create your first cloud environment** 양식을 표시합니다. 미리 채워진 이름과 네트워크 접근을 변경하지 않고 **Create & finish**를 클릭하여 **Default** 환경을 생성합니다. Owner가 [Quick setup](/docs/ko/claude-code-on-the-web#quick-setup-for-team-and-enterprise)을 켠 경우 온보딩이 대신 **Default**를 생성합니다.

88 88

89 **Default**는 [`Trusted` network access](/docs/ko/cloud-environments#access-levels)를 사용합니다: 세션은 [common package registries](/docs/ko/cloud-environments#default-allowed-domains) 및 기타 허용 목록에 있는 도메인에 도달하고 세션의 네트워크를 통해 다른 것에는 도달하지 않습니다. 구성 없이 사용 가능한 것은 [Installed tools](/docs/ko/cloud-environments#installed-tools)를 참조합니다.89 **Default**는 [`Trusted` network access](/docs/ko/cloud-environments#access-levels)를 사용합니다: 세션은 [common package registries](/docs/ko/cloud-environments#default-allowed-domains) 및 기타 허용 목록에 있는 도메인에 도달하고 세션의 네트워크를 통해 다른 것에는 도달하지 않습니다. 구성 없이 사용 가능한 것은 [Installed tools](/docs/ko/cloud-environments#installed-tools)를 참조합니다.

90 90

96 터미널에서 연결96 터미널에서 연결

97</h3>97</h3>

98 98

99이미 GitHub CLI(`gh`)를 사용하는 경우, 터미널에서 클라우드 세션을 위해 GitHub를 연결할 수 있습니다. 이는 [Claude Code CLI](/docs/ko/quickstart)가 필요합니다. Team 및 Enterprise 플랜에서 `/web-setup`은 Owner가 [Quick web setup](/docs/ko/claude-code-on-the-web#github-authentication-options)을 켠 후에만 사용 가능합니다.99이미 GitHub CLI(`gh`)를 사용하는 경우, 터미널에서 클라우드 세션을 위해 GitHub를 연결할 수 있습니다. 이는 [Claude Code CLI](/docs/ko/quickstart)가 필요합니다. Team 및 Enterprise 플랜에서 `/web-setup`은 Owner가 [Quick setup](/docs/ko/claude-code-on-the-web#quick-setup-for-team-and-enterprise)을 켠 후에만 사용 가능합니다.

100 100

101`/web-setup`을 실행하면 Claude Code는 `gh auth token`이 출력하는 토큰을 읽고, 확인을 요청하고, 토큰을 Anthropic으로 보냅니다. Anthropic은 claude.ai 계정으로 암호화하여 저장하고, 클라우드 세션은 [토큰을 제거](#remove-the-web-setup-token)할 때까지 GitHub 접근을 위해 이를 사용합니다. 직접 시작한 클라우드 세션은 그 후 해당 토큰이 접근할 수 있는 모든 저장소에 접근할 수 있으며, Claude GitHub 앱 설치가 필요하지 않습니다. [project](/docs/ko/claude-projects#set-up-github-access)의 스레드는 여전히 Claude GitHub 앱이 필요합니다.101`/web-setup`을 실행하면 Claude Code는 `gh auth token`이 출력하는 토큰을 읽고, 확인을 요청하고, 토큰을 Anthropic으로 보냅니다. Anthropic은 claude.ai 계정으로 암호화하여 저장하고, 클라우드 세션은 [토큰을 제거](#remove-the-web-setup-token)할 때까지 GitHub 접근을 위해 이를 사용합니다. 직접 시작한 클라우드 세션은 그 후 해당 토큰이 접근할 수 있는 모든 저장소에 접근할 수 있으며, Claude GitHub 앱 설치가 필요하지 않습니다. [project](/docs/ko/claude-projects#set-up-github-access)의 스레드는 여전히 Claude GitHub 앱이 필요합니다.

102 102

259 259

260Claude Code 내에서 입력했는데 명령 메뉴에 `"/web-setup"과 일치하는 명령 없음`이 표시되거나 제출하면 `알 수 없는 명령: /web-setup`이 반환되면, 요구 사항이 충족되지 않아 명령이 숨겨져 있습니다. 일반적으로 API 키 또는 타사 제공자로 인증되었으며 claude.ai 구독이 아닌 경우입니다. `/login`을 실행하여 claude.ai 계정으로 로그인하세요.260Claude Code 내에서 입력했는데 명령 메뉴에 `"/web-setup"과 일치하는 명령 없음`이 표시되거나 제출하면 `알 수 없는 명령: /web-setup`이 반환되면, 요구 사항이 충족되지 않아 명령이 숨겨져 있습니다. 일반적으로 API 키 또는 타사 제공자로 인증되었으며 claude.ai 구독이 아닌 경우입니다. `/login`을 실행하여 claude.ai 계정으로 로그인하세요.

261 261

262Team 및 Enterprise 플랜에서는 명령이 기본적으로 숨겨져 있습니다. [빠른 웹 설정 토글](/docs/ko/claude-code-on-the-web#github-authentication-options)은 소유자가 켤 때까지 꺼져 있습니다. 꺼져 있는 동안 [브라우저에서 GitHub 연결](#connect-github)하세요.262Team 및 Enterprise 플랜에서는 명령이 기본적으로 숨겨져 있습니다. [빠른 설정 토글](/docs/ko/claude-code-on-the-web#quick-setup-for-team-and-enterprise)은 소유자가 켤 때까지 꺼져 있습니다. 꺼져 있는 동안에는 대신 [브라우저에서 GitHub 연결](#connect-github)하세요.

263 263

264명령은 다른 두 가지 경우에도 숨겨집니다:264명령은 다른 두 가지 경우에도 숨겨집니다:

265 265

Documentation 2026-10-03 23:57 UTC to 2026-10-04 21:01 UTC