Documentation 2026-05-17 01:01 UTC to 2026-05-18 23:59 UTC

111SDK는 Claude Code를 구동하는 동일한 도구를 포함합니다:111SDK는 Claude Code를 구동하는 동일한 도구를 포함합니다:

112 112 

113| 카테고리 | 도구 | 기능 |113| 카테고리 | 도구 | 기능 |

114| :---------- | :----------------------------------------------- | :-------------------------------------- |114| :---------- | :-------------------------------------------------------------- | :-------------------------------------- |

115| **파일 작업** | `Read`, `Edit`, `Write` | 파일 읽기, 수정, 생성 |115| **파일 작업** | `Read`, `Edit`, `Write` | 파일 읽기, 수정, 생성 |

116| **검색** | `Glob`, `Grep` | 패턴으로 파일 찾기, 정규식으로 콘텐츠 검색 |116| **검색** | `Glob`, `Grep` | 패턴으로 파일 찾기, 정규식으로 콘텐츠 검색 |

117| **실행** | `Bash` | 셸 명령, 스크립트, git 작업 실행 |117| **실행** | `Bash` | 셸 명령, 스크립트, git 작업 실행 |

118| **웹** | `WebSearch`, `WebFetch` | 웹 검색, 페이지 가져오기 및 파싱 |118| **웹** | `WebSearch`, `WebFetch` | 웹 검색, 페이지 가져오기 및 파싱 |

119| **검색** | `ToolSearch` | 모든 도구를 미리 로드하는 대신 필요에 따라 도구를 동적으로 찾고 로드 |119| **검색** | `ToolSearch` | 모든 도구를 미리 로드하는 대신 필요에 따라 도구를 동적으로 찾고 로드 |

120| **오케스트레이션** | `Agent`, `Skill`, `AskUserQuestion`, `TodoWrite` | 서브에이전트 생성, 스킬 호출, 사용자에게 질문, 작업 추적 |120| **오케스트레이션** | `Agent`, `Skill`, `AskUserQuestion`, `TaskCreate`, `TaskUpdate` | 서브에이전트 생성, 스킬 호출, 사용자에게 질문, 작업 추적 |

121 121 

122내장 도구 외에도 다음을 수행할 수 있습니다:122내장 도구 외에도 다음을 수행할 수 있습니다:

123 123 

197 197 

198## 컨텍스트 윈도우198## 컨텍스트 윈도우

199 199 

200컨텍스트 윈도우는 세션 중에 Claude가 사용할 수 있는 총 정보량입니다. 세션 내의 턴 사이에 재설정되지 않습니다. 모든 것이 누적됩니다: 시스템 프롬프트, 도구 정의, 대화 기록, 도구 입력, 도구 출력. 턴 전체에서 동일하게 유지되는 콘텐츠(시스템 프롬프트, 도구 정의, CLAUDE.md)는 자동으로 [프롬프트 캐시됩니다](https://platform.claude.com/docs/en/build-with-claude/prompt-caching). 이는 반복된 접두사에 대한 비용과 지연 시간을 줄입니다.200컨텍스트 윈도우는 세션 중에 Claude가 사용할 수 있는 총 정보량입니다. 세션 내의 턴 사이에 재설정되지 않습니다. 모든 것이 누적됩니다: 시스템 프롬프트, 도구 정의, 대화 기록, 도구 입력, 도구 출력. 턴 전체에서 동일하게 유지되는 콘텐츠(시스템 프롬프트, 도구 정의, CLAUDE.md)는 자동으로 [프롬프트 캐시됩니다](https://platform.claude.com/docs/ko/build-with-claude/prompt-caching). 이는 반복된 접두사에 대한 비용과 지연 시간을 줄입니다.

201 201 

202### 컨텍스트를 소비하는 것202### 컨텍스트를 소비하는 것

203 203 

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

205 205 

206| 소스 | 로드 시기 | 영향 |206| 소스 | 로드 시기 | 영향 |

207| :--------------- | :---------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------ |207| :--------------- | :---------------------------------------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

208| **시스템 프롬프트** | 모든 요청 | 작은 고정 비용, 항상 존재 |208| **시스템 프롬프트** | 모든 요청 | 작은 고정 비용, 항상 존재 |

209| **CLAUDE.md 파일** | 세션 시작, [`settingSources`](/ko/agent-sdk/claude-code-features)를 통해 | 모든 요청에서 전체 콘텐츠(프롬프트 캐시되므로 첫 번째 요청만 전체 비용 지불) |209| **CLAUDE.md 파일** | 세션 시작, [`settingSources`](/ko/agent-sdk/claude-code-features)를 통해 | 모든 요청에서 전체 콘텐츠(프롬프트 캐시되므로 첫 번째 요청만 전체 비용 지불) |

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

211| **대화 기록** | 턴에 걸쳐 누적 | 각 턴으로 증가: 프롬프트, 응답, 도구 입력, 도구 출력 |211| **대화 기록** | 턴에 걸쳐 누적 | 각 턴으로 증가: 프롬프트, 응답, 도구 입력, 도구 출력 |

212| **스킬 설명** | 세션 시작, 설정 소스를 통해 | 짧은 요약; 전체 콘텐츠는 호출될 때만 로드 |212| **스킬 설명** | 세션 시작, 설정 소스를 통해 | 짧은 요약; 전체 콘텐츠는 호출될 때만 로드 |

213 213 

244장기 실행 에이전트를 위한 몇 가지 전략:244장기 실행 에이전트를 위한 몇 가지 전략:

245 245 

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

247* **도구를 선택적으로 사용합니다.** 모든 도구 정의는 컨텍스트 공간을 차지합니다. [`AgentDefinition`](/ko/agent-sdk/subagents#agentdefinition-configuration)의 `tools` 필드를 사용하여 서브에이전트를 필요한 최소 세트로 범위를 지정하고, [MCP 도구 검색](/ko/agent-sdk/mcp#mcp-tool-search)을 사용하여 모든 도구를 미리 로드하는 대신 필요에 따라 도구를 로드합니다.247* **도구를 선택적으로 사용합니다.** 모든 도구 정의는 컨텍스트 공간을 차지합니다. [`AgentDefinition`](/ko/agent-sdk/subagents#agentdefinition-configuration)의 `tools` 필드를 사용하여 서브에이전트를 필요한 최소 세트로 범위를 지정합니다.

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

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

250 250 

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

19### 빠른 비교19### 빠른 비교

20 20 

21| 기능 | `query()` | `ClaudeSDKClient` |21| 기능 | `query()` | `ClaudeSDKClient` |

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

23| **세션** | 매번 새 세션 생성 | 동일한 세션 재사용 |23| **세션** | 기본적으로 새 세션 생성 | 동일한 세션 재사용 |

24| **대화** | 단일 교환 | 동일한 컨텍스트에서 여러 교환 |24| **대화** | 단일 교환 | 동일한 컨텍스트에서 여러 교환 |

25| **연결** | 자동으로 관리됨 | 수동 제어 |25| **연결** | 자동으로 관리됨 | 수동 제어 |

26| **스트리밍 입력** | ✅ 지원됨 | ✅ 지원됨 |26| **스트리밍 입력** | ✅ 지원됨 | ✅ 지원됨 |

27| **중단** | ❌ 지원 안 함 | ✅ 지원됨 |27| **중단** | ❌ 지원 안 함 | ✅ 지원됨 |

28| **Hooks** | ✅ 지원됨 | ✅ 지원됨 |28| **Hooks** | ✅ 지원됨 | ✅ 지원됨 |

29| **사용자 정의 도구** | ✅ 지원됨 | ✅ 지원됨 |29| **사용자 정의 도구** | ✅ 지원됨 | ✅ 지원됨 |

30| **대화 계속하기** | ❌ 매번 새 세션 | ✅ 대화 유지 |30| **대화 계속하기** | `continue_conversation` 또는 `resume`을 통한 수동 | ✅ 자동 |

31| **사용 사례** | 일회성 작업 | 지속적인 대화 |31| **사용 사례** | 일회성 작업 | 지속적인 대화 |

32 32 

33### `query()` 사용 시기 (매번 새 세션)33### `query()` 사용 시기 (일회성 작업)

34 34 

35**최적의 경우:**35**최적의 경우:**

36 36 

53 53 

54### `query()`54### `query()`

55 55 

56Claude Code와의 각 상호작용을 위해 새 세션을 생성합니다. 메시지가 도착하면 생성하는 비동기 반복자를 반환합니다. `query()`에 대한 각 호출은 이전 상호작용의 메모리 없이 새로 시작합니다.56Claude Code와의 각 상호작용을 위해 기본적으로 새 세션을 생성합니다. 메시지가 도착하면 생성하는 비동기 반복자를 반환합니다. `query()`에 대한 각 호출은 `continue_conversation=True` 또는 [`ClaudeAgentOptions`](#claudeagentoptions)에서 `resume`을 전달하지 않는 한 이전 상호작용의 메모리 없이 새로 시작합니다. [세션](/ko/agent-sdk/sessions)을 참조하세요.

57 57 

58```python theme={null}58```python theme={null}

59async def query(59async def query(

790 plugins: list[SdkPluginConfig] = field(default_factory=list)790 plugins: list[SdkPluginConfig] = field(default_factory=list)

791 max_thinking_tokens: int | None = None # Deprecated: use thinking instead791 max_thinking_tokens: int | None = None # Deprecated: use thinking instead

792 thinking: ThinkingConfig | None = None792 thinking: ThinkingConfig | None = None

793 effort: Literal["low", "medium", "high", "xhigh", "max"] | None = None793 effort: EffortLevel | None = None

794 enable_file_checkpointing: bool = False794 enable_file_checkpointing: bool = False

795 session_store: SessionStore | None = None795 session_store: SessionStore | None = None

796 session_store_flush: SessionStoreFlushMode = "batched"796 session_store_flush: SessionStoreFlushMode = "batched"

837| `skills` | `list[str] \| Literal["all"] \| None` | `None` | 세션에서 사용 가능한 스킬. 모든 발견된 스킬을 활성화하려면 `"all"`을 전달하거나, 스킬 이름 목록을 전달합니다. 설정하면 SDK는 `allowed_tools`에 나열하지 않고도 Skill 도구를 자동으로 활성화합니다. [스킬](/ko/agent-sdk/skills) 참조 |837| `skills` | `list[str] \| Literal["all"] \| None` | `None` | 세션에서 사용 가능한 스킬. 모든 발견된 스킬을 활성화하려면 `"all"`을 전달하거나, 스킬 이름 목록을 전달합니다. 설정하면 SDK는 `allowed_tools`에 나열하지 않고도 Skill 도구를 자동으로 활성화합니다. [스킬](/ko/agent-sdk/skills) 참조 |

838| `max_thinking_tokens` | `int \| None` | `None` | *Deprecated* - 생각 블록의 최대 토큰. 대신 `thinking` 사용 |838| `max_thinking_tokens` | `int \| None` | `None` | *Deprecated* - 생각 블록의 최대 토큰. 대신 `thinking` 사용 |

839| `thinking` | [`ThinkingConfig`](#thinkingconfig) ` \| None` | `None` | 확장된 생각 동작을 제어합니다. `max_thinking_tokens`보다 우선합니다 |839| `thinking` | [`ThinkingConfig`](#thinkingconfig) ` \| None` | `None` | 확장된 생각 동작을 제어합니다. `max_thinking_tokens`보다 우선합니다 |

840| `effort` | `Literal["low", "medium", "high", "xhigh", "max"] \| None` | `None` | 생각 깊이를 위한 노력 수준 |840| `effort` | [`EffortLevel`](#effortlevel) ` \| None` | `None` | 생각 깊이를 위한 노력 수준 |

841| `session_store` | [`SessionStore`](/ko/agent-sdk/session-storage#the-sessionstore-interface) ` \| None` | `None` | 세션 기록을 외부 백엔드로 미러링하여 모든 호스트가 이를 재개할 수 있도록 합니다. [외부 저장소에 세션 유지](/ko/agent-sdk/session-storage) 참조 |841| `session_store` | [`SessionStore`](/ko/agent-sdk/session-storage#the-sessionstore-interface) ` \| None` | `None` | 세션 기록을 외부 백엔드로 미러링하여 모든 호스트가 이를 재개할 수 있도록 합니다. [외부 저장소에 세션 유지](/ko/agent-sdk/session-storage) 참조 |

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

843 843 

1039 initialPrompt: str | None = None1039 initialPrompt: str | None = None

1040 maxTurns: int | None = None1040 maxTurns: int | None = None

1041 background: bool | None = None1041 background: bool | None = None

1042 effort: Literal["low", "medium", "high", "xhigh", "max"] | int | None = None1042 effort: EffortLevel | int | None = None

1043 permissionMode: PermissionMode | None = None1043 permissionMode: PermissionMode | None = None

1044```1044```

1045 1045 

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

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

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

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

1060| `permissionMode` | 아니오 | 이 에이전트 내의 도구 실행을 위한 권한 모드. [`PermissionMode`](#permissionmode) 참조 |1060| `permissionMode` | 아니오 | 이 에이전트 내의 도구 실행을 위한 권한 모드. [`PermissionMode`](#permissionmode) 참조 |

1061 1061 

1062<Note>1062<Note>

1077]1077]

1078```1078```

1079 1079 

1080### `EffortLevel`

1081 

1082생각 깊이를 안내하기 위한 노력 수준입니다.

1083 

1084```python theme={null}

1085EffortLevel = Literal[

1086 "low", # Minimal thinking, fastest responses

1087 "medium", # Moderate thinking

1088 "high", # Deep reasoning

1089 "xhigh", # Extended reasoning (Opus 4.7 only; falls back to "high" on other models)

1090 "max", # Maximum effort

1091]

1092```

1093 

1080### `CanUseTool`1094### `CanUseTool`

1081 1095 

1082도구 권한 콜백 함수의 타입 별칭입니다.1096도구 권한 콜백 함수의 타입 별칭입니다.

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

1225 1239 

1226```python theme={null}1240```python theme={null}

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

1242 

1243 

1227class ThinkingConfigAdaptive(TypedDict):1244class ThinkingConfigAdaptive(TypedDict):

1228 type: Literal["adaptive"]1245 type: Literal["adaptive"]

1246 display: NotRequired[ThinkingDisplay]

1229 1247 

1230 1248 

1231class ThinkingConfigEnabled(TypedDict):1249class ThinkingConfigEnabled(TypedDict):

1232 type: Literal["enabled"]1250 type: Literal["enabled"]

1233 budget_tokens: int1251 budget_tokens: int

1252 display: NotRequired[ThinkingDisplay]

1234 1253 

1235 1254 

1236class ThinkingConfigDisabled(TypedDict):1255class ThinkingConfigDisabled(TypedDict):

1241```1260```

1242 1261 

1243| 변형 | 필드 | 설명 |1262| 변형 | 필드 | 설명 |

1244| :--------- | :---------------------- | :-------------------------- |1263| :--------- | :--------------------------------- | :-------------------------- |

1245| `adaptive` | `type` | Claude가 생각할 시기를 적응적으로 결정합니다 |1264| `adaptive` | `type`, `display` | Claude가 생각할 시기를 적응적으로 결정합니다 |

1246| `enabled` | `type`, `budget_tokens` | 특정 토큰 예산으로 생각 활성화 |1265| `enabled` | `type`, `budget_tokens`, `display` | 특정 토큰 예산으로 생각 활성화 |

1247| `disabled` | `type` | 생각 비활성화 |1266| `disabled` | `type` | 생각 비활성화 |

1248 1267 

1268선택적 `display` 필드는 생각 텍스트가 `"summarized"` 또는 `"omitted"`로 반환되는지 제어합니다. Claude Opus 4.7 이상에서 API 기본값은 `"omitted"`이므로, [`ThinkingBlock`](#thinkingblock) 출력에서 생각 콘텐츠를 받으려면 `"summarized"`를 설정합니다.

1269 

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

1250 1271 

1251```python theme={null}1272```python theme={null}

2177 hookEventName: Literal["PostToolUse"]2198 hookEventName: Literal["PostToolUse"]

2178 additionalContext: NotRequired[str]2199 additionalContext: NotRequired[str]

2179 updatedToolOutput: NotRequired[Any]2200 updatedToolOutput: NotRequired[Any]

2180 updatedMCPToolOutput: NotRequired[Any]2201 updatedMCPToolOutput: NotRequired[Any] # Deprecated: use updatedToolOutput, which works for all tools

2181 2202 

2182 2203 

2183class PostToolUseFailureHookSpecificOutput(TypedDict):2204class PostToolUseFailureHookSpecificOutput(TypedDict):

2646**도구 이름:** `TodoWrite`2667**도구 이름:** `TodoWrite`

2647 2668 

2648<Note>2669<Note>

2649 `TodoWrite`는 더 이상 사용되지 않으며 향후 릴리스에서 제거될 예정입니다. 대신 `TaskCreate`, `TaskGet`, `TaskUpdate`, `TaskList`를 사용하십시오. `CLAUDE_CODE_ENABLE_TASKS=1`을 설정하여 옵트인하십시오. 모니터링 코드 변경 방법은 [작업 도구로 마이그레이션](/ko/agent-sdk/todo-tracking#migrate-to-task-tools)을 참조하십시오.2670 Claude Code v2.1.142부터 `TodoWrite`는 기본적으로 비활성화되어 있습니다. 대신 `TaskCreate`, `TaskGet`, `TaskUpdate`, `TaskList`를 사용하십시오. 모니터링 코드를 업데이트하는 방법은 [작업 도구로 마이그레이션](/ko/agent-sdk/todo-tracking#migrate-to-task-tools)을 참조하거나, `CLAUDE_CODE_ENABLE_TASKS=0`을 설정하여 `TodoWrite`로 되돌리십시오.

2650</Note>2671</Note>

2651 2672 

2652**입력:**2673**입력:**

96asyncio.run(main())96asyncio.run(main())

97```97```

98 98 

99Python SDK 참조에서 [`ClaudeSDKClient`와 독립형 `query()` 함수를 언제 사용할지](/ko/agent-sdk/python#choosing-between-query-and-claudesdkclient)에 대한 세부 정보를 확인하세요.99[Python SDK 참조](/ko/agent-sdk/python#choosing-between-query-and-claudesdkclient)에서 `ClaudeSDKClient`와 독립형 `query()` 함수를 언제 사용할지에 대한 세부 정보를 확인하세요.

100 100 

101### TypeScript: `continue: true`101### TypeScript: `continue: true`

102 102 

103안정적인 TypeScript SDK (이 문서 전체에서 사용되는 `query()` 함수, 때때로 V1이라고 불림)는 Python의 `ClaudeSDKClient`와 같은 세션 보유 클라이언트 객체가 없습니다. 대신 각 후속 `query()` 호출에서 `continue: true`를 전달하면 SDK가 현재 디렉토리의 가장 최근 세션을 찾아 재개합니다. ID 추적이 필요하지 않습니다.103TypeScript SDK는 Python의 `ClaudeSDKClient`와 같은 세션 보유 클라이언트 객체가 없습니다. 대신 각 후속 `query()` 호출에서 `continue: true`를 전달하면 SDK가 현재 디렉토리의 가장 최근 세션을 찾아 재개합니다. ID 추적이 필요하지 않습니다.

104 104 

105이 예제는 두 개의 별도 `query()` 호출을 수행합니다. 첫 번째는 새 세션을 만들고, 두 번째는 `continue: true`를 설정하여 SDK가 디스크의 가장 최근 세션을 찾아 재개하도록 지시합니다. 에이전트는 첫 번째 호출의 전체 컨텍스트를 가집니다:105이 예제는 두 개의 별도 `query()` 호출을 수행합니다. 첫 번째는 새 세션을 만들고, 두 번째는 `continue: true`를 설정하여 SDK가 디스크의 가장 최근 세션을 찾아 재개하도록 지시합니다. 에이전트는 첫 번째 호출의 전체 컨텍스트를 가집니다:

106 106 

132```132```

133 133 

134<Note>134<Note>

135 `createSession()`을 제공한 실험적 [V2 세션 API](/ko/agent-sdk/typescript-v2-preview)는 `send` / `stream` 패턴으로 더 이상 사용되지 않습니다. V1 `query()` 함수와 이 페이지에 설명된 세션 옵션을 사용하세요.135 실험적 [V2 세션 API](/ko/agent-sdk/typescript-v2-preview)는 `send` / `stream` 패턴을 제공하는 `createSession()`으로 TypeScript Agent SDK 0.3.142에서 제거되었습니다. 이 페이지에 설명된 `query()` 함수와 세션 옵션을 대신 사용하세요.

136</Note>136</Note>

137 137 

138## `query()`와 함께 세션 옵션 사용하기138## `query()`와 함께 세션 옵션 사용하기

8 8 

9할일 추적은 작업을 관리하고 사용자에게 진행 상황을 표시하는 구조화된 방법을 제공합니다. Claude Agent SDK에는 복잡한 워크플로우를 구성하고 사용자에게 작업 진행 상황을 알리는 데 도움이 되는 기본 제공 할일 기능이 포함되어 있습니다.9할일 추적은 작업을 관리하고 사용자에게 진행 상황을 표시하는 구조화된 방법을 제공합니다. Claude Agent SDK에는 복잡한 워크플로우를 구성하고 사용자에게 작업 진행 상황을 알리는 데 도움이 되는 기본 제공 할일 기능이 포함되어 있습니다.

10 10 

11<Note>

12 TypeScript Agent SDK 0.3.142 및 Claude Code v2.1.142부터 세션은 `TodoWrite` 대신 구조화된 Task 도구인 `TaskCreate`, `TaskUpdate`, `TaskGet`, `TaskList`를 사용합니다. 모니터링 코드 변경 방법은 [Task 도구로 마이그레이션](#migrate-to-task-tools)을 참조하십시오. 이 페이지의 예제는 아직 마이그레이션하지 않은 세션에 대해 `TodoWrite`를 계속 표시하기 위해 `CLAUDE_CODE_ENABLE_TASKS=0`을 설정합니다.

13</Note>

14 

11### 할일 생명주기15### 할일 생명주기

12 16 

13할일은 예측 가능한 생명주기를 따릅니다:17할일은 예측 가능한 생명주기를 따릅니다:

36 40 

37 for await (const message of query({41 for await (const message of query({

38 prompt: "Optimize my React app performance and track progress with todos",42 prompt: "Optimize my React app performance and track progress with todos",

39 options: { maxTurns: 15 }43 // Re-enable TodoWrite, which this example monitors. Without it, the SDK uses

44 // Task tools instead and these tool_use blocks never appear.

45 options: { maxTurns: 15, env: { ...process.env, CLAUDE_CODE_ENABLE_TASKS: "0" } }

40 })) {46 })) {

41 // Todo updates are reflected in the message stream47 // Todo updates are reflected in the message stream

42 if (message.type === "assistant") {48 if (message.type === "assistant") {

61 67 

62 async for message in query(68 async for message in query(

63 prompt="Optimize my React app performance and track progress with todos",69 prompt="Optimize my React app performance and track progress with todos",

64 options=ClaudeAgentOptions(max_turns=15),70 # Re-enable TodoWrite, which this example monitors. Without it, the SDK uses

71 # Task tools instead and these tool_use blocks never appear.

72 options=ClaudeAgentOptions(max_turns=15, env={"CLAUDE_CODE_ENABLE_TASKS": "0"}),

65 ):73 ):

66 # Todo updates are reflected in the message stream74 # Todo updates are reflected in the message stream

67 if isinstance(message, AssistantMessage):75 if isinstance(message, AssistantMessage):

112 async trackQuery(prompt: string) {120 async trackQuery(prompt: string) {

113 for await (const message of query({121 for await (const message of query({

114 prompt,122 prompt,

115 options: { maxTurns: 20 }123 // Re-enable TodoWrite, which this tracker watches for.

124 options: { maxTurns: 20, env: { ...process.env, CLAUDE_CODE_ENABLE_TASKS: "0" } }

116 })) {125 })) {

117 if (message.type === "assistant") {126 if (message.type === "assistant") {

118 for (const block of message.message.content) {127 for (const block of message.message.content) {

167 print(f"{i + 1}. {icon} {text}")176 print(f"{i + 1}. {icon} {text}")

168 177 

169 async def track_query(self, prompt: str):178 async def track_query(self, prompt: str):

170 async for message in query(prompt=prompt, options=ClaudeAgentOptions(max_turns=20)):179 async for message in query(

180 prompt=prompt,

181 # Re-enable TodoWrite, which this tracker watches for.

182 options=ClaudeAgentOptions(max_turns=20, env={"CLAUDE_CODE_ENABLE_TASKS": "0"}),

183 ):

171 if isinstance(message, AssistantMessage):184 if isinstance(message, AssistantMessage):

172 for block in message.content:185 for block in message.content:

173 if isinstance(block, ToolUseBlock) and block.name == "TodoWrite":186 if isinstance(block, ToolUseBlock) and block.name == "TodoWrite":

181 ```194 ```

182</CodeGroup>195</CodeGroup>

183 196 

197## Task 도구로 마이그레이션

198 

199Task 도구는 단일 `TodoWrite` 호출을 각 새 항목에 대한 `TaskCreate`와 각 상태 변경에 대한 `TaskUpdate`로 분할하며, `TaskList`와 `TaskGet`은 모델이 현재 목록을 다시 읽을 수 있도록 사용 가능합니다. 모니터링 코드는 여전히 어시스턴트 스트림의 `tool_use` 블록을 검사하지만, 모든 호출에서 전체 목록을 바꾸는 대신 작업 ID로 키가 지정된 맵을 유지합니다. {/* min-version: 2.1.142 */}Task 도구는 TypeScript Agent SDK 0.3.142 및 Claude Code v2.1.142부터 기본값이므로 `options.env` 변경이 필요하지 않습니다.

200 

201| `TodoWrite` 사용 | Task 도구 사용 |

202| ---------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

203| 한 번의 도구 호출로 전체 `todos` 배열을 다시 작성 | `TaskCreate`는 한 항목을 추가하고, `TaskUpdate`는 `taskId`로 한 항목을 패치 |

204| `block.name === "TodoWrite"` 일치 | `block.name === "TaskCreate"` 또는 `"TaskUpdate"` 일치 |

205| 항목 형태: `{ content, status, activeForm }` | `TaskCreate` 입력: `{ subject, description, activeForm?, metadata? }`. `TaskUpdate` 입력: `{ taskId, status?, subject?, description?, activeForm?, addBlocks?, addBlockedBy?, owner?, metadata? }`. `status`는 `"pending"`, `"in_progress"`, 또는 `"completed"`이며, 삭제하려면 `status: "deleted"`를 설정 |

206| `block.input.todos`를 직접 렌더링 | 호출 전체에서 항목을 누적하거나, `TaskList` 도구 결과에서 스냅샷을 읽음 |

207 

208할당된 작업 ID는 `TaskCreate` 입력에 없습니다. 일치하는 `tool_result`에서 `{ task: { id, subject } }`로 반환되므로, 맵을 키로 지정하기 위해 결과 블록에서 캡처합니다. 다음 예제는 [할일 변경 모니터링](#monitoring-todo-changes) 루프에 대한 최소한의 변경을 보여줍니다. 전체 목록을 렌더링하려면 스트림에서 `TaskList` 도구 결과를 감시하거나 `TaskCreate` 결과와 `TaskUpdate` 입력을 맵으로 누적합니다:

209 

210<CodeGroup>

211 ```typescript TypeScript theme={null}

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

213 

214 for await (const message of query({

215 prompt: "Optimize my React app performance",

216 })) {

217 if (message.type !== "assistant") continue;

218 for (const block of message.message.content) {

219 if (block.type !== "tool_use") continue;

220 if (block.name === "TaskCreate") {

221 const input = block.input as { subject: string };

222 console.log(`+ ${input.subject}`);

223 } else if (block.name === "TaskUpdate") {

224 const input = block.input as { taskId: string; status?: string };

225 if (input.status) console.log(` ${input.taskId} -> ${input.status}`);

226 }

227 }

228 }

229 ```

230 

231 ```python Python theme={null}

232 from claude_agent_sdk import query, AssistantMessage, ToolUseBlock

233 

234 async for message in query(

235 prompt="Optimize my React app performance",

236 ):

237 if not isinstance(message, AssistantMessage):

238 continue

239 for block in message.content:

240 if not isinstance(block, ToolUseBlock):

241 continue

242 if block.name == "TaskCreate":

243 print(f"+ {block.input['subject']}")

244 elif block.name == "TaskUpdate" and block.input.get("status"):

245 print(f" {block.input['taskId']} -> {block.input['status']}")

246 ```

247</CodeGroup>

248 

184## 관련 문서249## 관련 문서

185 250 

186* [TypeScript SDK 참고](/ko/agent-sdk/typescript)251* [TypeScript SDK 참고](/ko/agent-sdk/typescript)

414| `skills` | `string[] \| 'all'` | `undefined` | 세션에서 사용 가능한 스킬입니다. 모든 발견된 스킬을 활성화하려면 `'all'`을 전달하거나 스킬 이름 목록을 전달합니다. 설정하면 SDK는 `allowedTools`에 나열하지 않고 Skill 도구를 자동으로 활성화합니다. [스킬](/ko/agent-sdk/skills) 참조 |414| `skills` | `string[] \| 'all'` | `undefined` | 세션에서 사용 가능한 스킬입니다. 모든 발견된 스킬을 활성화하려면 `'all'`을 전달하거나 스킬 이름 목록을 전달합니다. 설정하면 SDK는 `allowedTools`에 나열하지 않고 Skill 도구를 자동으로 활성화합니다. [스킬](/ko/agent-sdk/skills) 참조 |

415| `spawnClaudeCodeProcess` | `(options: SpawnOptions) => SpawnedProcess` | `undefined` | Claude Code 프로세스를 생성하는 사용자 정의 함수입니다. VM, 컨테이너 또는 원격 환경에서 Claude Code를 실행하는 데 사용합니다 |415| `spawnClaudeCodeProcess` | `(options: SpawnOptions) => SpawnedProcess` | `undefined` | Claude Code 프로세스를 생성하는 사용자 정의 함수입니다. VM, 컨테이너 또는 원격 환경에서 Claude Code를 실행하는 데 사용합니다 |

416| `stderr` | `(data: string) => void` | `undefined` | stderr 출력에 대한 콜백 |416| `stderr` | `(data: string) => void` | `undefined` | stderr 출력에 대한 콜백 |

417| `strictMcpConfig` | `boolean` | `false` | 엄격한 MCP 검증 적용 |417| `strictMcpConfig` | `boolean` | `false` | `mcpServers`에 전달된 서버만 사용하고 프로젝트 `.mcp.json`, 사용자 설정 및 플러그인 제공 MCP 서버를 무시합니다 |

418| `systemPrompt` | `string \| { type: 'preset'; preset: 'claude_code'; append?: string; excludeDynamicSections?: boolean }` | `undefined` (최소 프롬프트) | 시스템 프롬프트 구성입니다. 사용자 정의 프롬프트의 경우 문자열을 전달하거나, Claude Code의 시스템 프롬프트를 사용하려면 `{ type: 'preset', preset: 'claude_code' }`를 전달합니다. 프리셋 객체 형식을 사용할 때 `append`를 추가하여 추가 지침으로 확장하고, `excludeDynamicSections: true`를 설정하여 세션별 컨텍스트를 첫 번째 사용자 메시지로 이동하여 [머신 간 프롬프트 캐시 재사용 개선](/ko/agent-sdk/modifying-system-prompts#improve-prompt-caching-across-users-and-machines) |418| `systemPrompt` | `string \| { type: 'preset'; preset: 'claude_code'; append?: string; excludeDynamicSections?: boolean }` | `undefined` (최소 프롬프트) | 시스템 프롬프트 구성입니다. 사용자 정의 프롬프트의 경우 문자열을 전달하거나, Claude Code의 시스템 프롬프트를 사용하려면 `{ type: 'preset', preset: 'claude_code' }`를 전달합니다. 프리셋 객체 형식을 사용할 때 `append`를 추가하여 추가 지침으로 확장하고, `excludeDynamicSections: true`를 설정하여 세션별 컨텍스트를 첫 번째 사용자 메시지로 이동하여 [머신 간 프롬프트 캐시 재사용 개선](/ko/agent-sdk/modifying-system-prompts#improve-prompt-caching-across-users-and-machines) |

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

420| `toolConfig` | [`ToolConfig`](#toolconfig) | `undefined` | 기본 제공 도구 동작의 구성입니다. [`ToolConfig`](#toolconfig) 참조 |420| `toolConfig` | [`ToolConfig`](#toolconfig) | `undefined` | 기본 제공 도구 동작의 구성입니다. [`ToolConfig`](#toolconfig) 참조 |

1847진행 상황을 추적하기 위한 구조화된 작업 목록을 만들고 관리합니다.1847진행 상황을 추적하기 위한 구조화된 작업 목록을 만들고 관리합니다.

1848 1848 

1849<Note>1849<Note>

1850 `TodoWrite`는 더 이상 사용되지 않으며 향후 릴리스에서 제거될 예정입니다. 대신 `TaskCreate`, `TaskGet`, `TaskUpdate` 및 `TaskList`를 사용하세요. `CLAUDE_CODE_ENABLE_TASKS=1`을 설정하여 옵트인합니다. 코드 변경 모니터링 방법은 [작업 도구로 마이그레이션](/ko/agent-sdk/todo-tracking#migrate-to-task-tools)을 참조하세요.1850 TypeScript Agent SDK 0.3.142부터 `TodoWrite`는 기본적으로 비활성화됩니다. 대신 `TaskCreate`, `TaskGet`, `TaskUpdate` 및 `TaskList`를 사용하세요. 모니터링 코드를 업데이트하려면 [작업 도구로 마이그레이션](/ko/agent-sdk/todo-tracking#migrate-to-task-tools)을 참조하거나, `CLAUDE_CODE_ENABLE_TASKS=0`을 설정하여 `TodoWrite`로 되돌립니다.

1851</Note>1851</Note>

1852 1852 

1853### TaskCreate1853### TaskCreate

2344이전 및 업데이트된 작업 목록을 반환합니다.2344이전 및 업데이트된 작업 목록을 반환합니다.

2345 2345 

2346<Note>2346<Note>

2347 `TodoWrite`는 더 이상 사용되지 않으며 향후 릴리스에서 제거될 예정입니다. 대신 `TaskCreate`, `TaskGet`, `TaskUpdate`, `TaskList`를 사용하십시오. `CLAUDE_CODE_ENABLE_TASKS=1`을 설정하여 옵트인합니다. 코드 변경 모니터링 방법은 [작업 도구로 마이그레이션](/ko/agent-sdk/todo-tracking#migrate-to-task-tools)을 참조하십시오.2347 TypeScript Agent SDK 0.3.142부터 `TodoWrite`는 기본적으로 비활성화됩니다. 대신 `TaskCreate`, `TaskGet`, `TaskUpdate`, `TaskList`를 사용하십시오. 모니터링 코드를 업데이트하려면 [작업 도구로 마이그레이션](/ko/agent-sdk/todo-tracking#migrate-to-task-tools)을 참조하거나, `CLAUDE_CODE_ENABLE_TASKS=0`을 설정하여 `TodoWrite`로 되돌립니다.

2348</Note>2348</Note>

2349 2349 

2350### TaskCreate2350### TaskCreate

2739Claude의 사고/추론 동작을 제어합니다. 더 이상 사용되지 않는 `maxThinkingTokens`보다 우선합니다.2739Claude의 사고/추론 동작을 제어합니다. 더 이상 사용되지 않는 `maxThinkingTokens`보다 우선합니다.

2740 2740 

2741```typescript theme={null}2741```typescript theme={null}

2742type ThinkingDisplay = "summarized" | "omitted";

2743 

2742type ThinkingConfig =2744type ThinkingConfig =

2743 | { type: "adaptive" } // 모델이 언제 그리고 얼마나 추론할지 결정합니다 (Opus 4.6+)2745 | { type: "adaptive"; display?: ThinkingDisplay } // 모델이 언제 그리고 얼마나 추론할지 결정합니다 (Opus 4.6+)

2744 | { type: "enabled"; budgetTokens?: number } // 고정 사고 토큰 예산2746 | { type: "enabled"; budgetTokens?: number; display?: ThinkingDisplay } // 고정 사고 토큰 예산

2745 | { type: "disabled" }; // 확장된 사고 없음2747 | { type: "disabled" }; // 확장된 사고 없음

2746```2748```

2747 2749 

2750선택적 `display` 필드는 사고 텍스트가 `"summarized"` 또는 `"omitted"`로 반환되는지 제어합니다. Claude Opus 4.7 이상에서 API 기본값은 `"omitted"`이므로, `thinking` 블록에서 사고 콘텐츠를 받으려면 `"summarized"`를 설정하세요.

2751 

2748### `SpawnedProcess`2752### `SpawnedProcess`

2749 2753 

2750사용자 정의 프로세스 생성을 위한 인터페이스 (`spawnClaudeCodeProcess` 옵션과 함께 사용). `ChildProcess`는 이미 이 인터페이스를 만족합니다.2754사용자 정의 프로세스 생성을 위한 인터페이스 (`spawnClaudeCodeProcess` 옵션과 함께 사용). `ChildProcess`는 이미 이 인터페이스를 만족합니다.

3158```3162```

3159 3163 

3160| 속성 | 타입 | 기본값 | 설명 |3164| 속성 | 타입 | 기본값 | 설명 |

3161| :------------------------ | :--------- | :---------- | :-------------------------------------------------------- |3165| :------------------------ | :--------- | :---------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------- |

3162| `allowedDomains` | `string[]` | `[]` | 샌드박스된 프로세스가 액세스할 수 있는 도메인 이름 |3166| `allowedDomains` | `string[]` | `[]` | 샌드박스된 프로세스가 액세스할 수 있는 도메인 이름 |

3163| `deniedDomains` | `string[]` | `[]` | 샌드박스된 프로세스가 액세스할 수 없는 도메인 이름입니다. `allowedDomains`보다 우선합니다 |3167| `deniedDomains` | `string[]` | `[]` | 샌드박스된 프로세스가 액세스할 수 없는 도메인 이름입니다. `allowedDomains`보다 우선합니다 |

3164| `allowManagedDomainsOnly` | `boolean` | `false` | 네트워크 액세스를 `allowedDomains`의 도메인으로만 제한합니다 |3168| `allowManagedDomainsOnly` | `boolean` | `false` | 관리형 설정 전용입니다. [관리형 설정](/ko/permissions#managed-settings)에서 설정되었을 때 관리형 설정의 `allowedDomains` 항목만 적용되며 사용자, 프로젝트 또는 로컬 설정의 항목은 무시됩니다. SDK 옵션을 통해 설정되었을 때는 효과가 없습니다 |

3165| `allowLocalBinding` | `boolean` | `false` | 프로세스가 로컬 포트에 바인딩하도록 허용합니다 (예: 개발 서버의 경우) |3169| `allowLocalBinding` | `boolean` | `false` | 프로세스가 로컬 포트에 바인딩하도록 허용합니다 (예: 개발 서버의 경우) |

3166| `allowUnixSockets` | `string[]` | `[]` | 프로세스가 액세스할 수 있는 Unix 소켓 경로 (예: Docker 소켓) |3170| `allowUnixSockets` | `string[]` | `[]` | 프로세스가 액세스할 수 있는 Unix 소켓 경로 (예: Docker 소켓) |

3167| `allowAllUnixSockets` | `boolean` | `false` | 모든 Unix 소켓에 대한 액세스 허용 |3171| `allowAllUnixSockets` | `boolean` | `false` | 모든 Unix 소켓에 대한 액세스 허용 |

7> 다중 턴 대화를 위한 세션 기반 send/stream 패턴을 사용하는 지원 중단된 V2 TypeScript Agent SDK 세션 API 참조입니다.7> 다중 턴 대화를 위한 세션 기반 send/stream 패턴을 사용하는 지원 중단된 V2 TypeScript Agent SDK 세션 API 참조입니다.

8 8 

9<Warning>9<Warning>

10 V2 세션 API 함수 `unstable_v2_createSession`, `unstable_v2_resumeSession`, `unstable_v2_prompt`는 지원 중단되었으며 향후 릴리스에서 제거될 예정입니다. 대신 [V1 `query()` API](/ko/agent-sdk/typescript)를 사용하십시오.10 V2 세션 API는 더 이상 지원되지 않습니다. TypeScript Agent SDK 0.3.142는 `unstable_v2_createSession`, `unstable_v2_resumeSession`, `unstable_v2_prompt` 및 `SDKSession`과 `SDKSessionOptions` 타입을 제거합니다.

11 

12 마이그레이션하려면 [`query()` API](/ko/agent-sdk/typescript)와 이를 허용하는 [세션 옵션](/ko/agent-sdk/sessions)을 사용하십시오. 다중 턴 대화의 경우 `AsyncIterable<SDKUserMessage>`를 전달하거나 저장된 세션을 계속하려면 `options.resume`을 사용하십시오. 이 페이지는 Agent SDK 0.2.x 이전 버전의 코드를 유지 관리하는 경우 참조용으로 유지됩니다.

11</Warning>13</Warning>

12 14 

13V2는 비동기 생성기와 yield 조정의 필요성을 제거한 실험적 세션 API였습니다. 턴 전체에서 생성기 상태를 관리하는 대신 각 턴은 별도의 `send()`/`stream()` 사이클이었습니다. API 표면은 세 가지 개념으로 축소되었습니다:15V2는 비동기 생성기와 yield 조정의 필요성을 제거한 실험적 세션 API였습니다. 턴 전체에서 생성기 상태를 관리하는 대신 각 턴은 별도의 `send()`/`stream()` 사이클이었습니다. API 표면은 세 가지 개념으로 축소되었습니다:

18 20 

19## 설치21## 설치

20 22 

21V2 인터페이스는 기존 SDK 패키지에 포함되어 있습니다:23Agent SDK 0.2.x는 V2 인터페이스를 포함하는 마지막 버전입니다. 패키지 버전은 0.2.x에서 0.3.142로 직접 점프했으므로, 위의 제거 버전과 아래의 설치 핀은 동일한 경계를 설명합니다. 마지막 V2 호환 릴리스를 설치하려면 주 버전과 부 버전을 고정하십시오:

22 24 

23```bash theme={null}25```bash theme={null}

24npm install @anthropic-ai/claude-agent-sdk26npm install @anthropic-ai/claude-agent-sdk@0.2

25```27```

26 28 

27<Note>29<Note>

72 72 

73`claude agents`를 실행하여 에이전트 뷰를 엽니다. 전체 터미널을 차지하고 상태별로 그룹화된 모든 세션을 나열하며, 고정된 세션과 입력이 필요한 세션이 맨 위에 있습니다. 각 행은 세션의 이름, 현재 활동 및 마지막 변경 이후 경과 시간을 보여줍니다.73`claude agents`를 실행하여 에이전트 뷰를 엽니다. 전체 터미널을 차지하고 상태별로 그룹화된 모든 세션을 나열하며, 고정된 세션과 입력이 필요한 세션이 맨 위에 있습니다. 각 행은 세션의 이름, 현재 활동 및 마지막 변경 이후 경과 시간을 보여줍니다.

74 74 

75목록은 시작한 모든 백그라운드 세션을 표시하며, 모든 프로젝트에 걸쳐 있습니다. 한 저장소에서 작업하는 세션과 다른 worktree에서 작업하는 세션은 모두 여기에 나타나며, 에이전트 뷰를 연 디렉토리와 관계없이 표시됩니다. 다른 터미널에서 열려 있는 대화형 세션은 [백그라운드로 보낼](#from-inside-a-session) 때까지 나타나지 않습니다. [서브에이전트](/ko/sub-agents)와 [팀원](/ko/agent-teams)은 세션이 생성하는 별도의 행으로 나열되지 않습니다.75기본적으로 목록은 모든 프로젝트에 걸쳐 시작한 모든 백그라운드 세션을 표시합니다. 한 저장소에서 작업하는 세션과 다른 worktree에서 작업하는 세션은 모두 여기에 나타나며, 에이전트 뷰를 연 디렉토리와 관계없이 표시됩니다. 목록을 한 프로젝트로 범위를 지정하려면 `--cwd`를 전달합니다(Claude Code v2.1.141 이상 필요):

76 76 

77뷰를 한 프로젝트로 범위를 지정하려면 `claude agents --cwd <path>`로 시작합니다. 해당 디렉토리 아래에서 시작된 세션만 나타나며, [worktree](/ko/worktrees)에서 실행 중인 모든 세션을 포함합니다.77```bash theme={null}

78claude agents --cwd ~/projects/my-app

79```

80 

81이는 해당 디렉토리 아래에서 시작된 세션만 표시합니다. `~/projects/my-app/.claude/worktrees/` 아래의 [worktree로 이동한](#how-file-edits-are-isolated) 세션은 여전히 `~/projects/my-app`에 속하는 것으로 간주됩니다.

82 

83다른 터미널에서 열려 있는 대화형 세션은 [백그라운드로 보낼](#from-inside-a-session) 때까지 나타나지 않습니다. [서브에이전트](/ko/sub-agents)와 [팀원](/ko/agent-teams)은 세션이 생성하는 별도의 행으로 나열되지 않습니다.

78 84 

79```text theme={null}85```text theme={null}

80고정됨86고정됨

117| `∙` | 프로세스가 종료됨. 여전히 엿보기, 답변 또는 연결할 수 있으며, Claude는 중단된 위치에서 다시 시작 |123| `∙` | 프로세스가 종료됨. 여전히 엿보기, 답변 또는 연결할 수 있으며, Claude는 중단된 위치에서 다시 시작 |

118| `✢` | [`/loop`](/ko/scheduled-tasks) 세션이 반복 사이에 절전 중. 행은 실행 횟수와 카운트다운을 표시 |124| `✢` | [`/loop`](/ko/scheduled-tasks) 세션이 반복 사이에 절전 중. 행은 실행 횟수와 카운트다운을 표시 |

119 125 

126행의 오른쪽 가장자리에 나타날 수 있는 `●`는 [풀 리퀘스트 상태](#pull-request-status) 표시기이며, 상태 아이콘의 일부가 아닙니다. 앞의 숫자는 세션이 열은 풀 리퀘스트의 개수입니다.

127 

120백그라운드 세션은 계속 작동하기 위해 열린 터미널이 필요하지 않습니다. 별도의 [감독자 프로세스](#the-supervisor-process)가 실행하므로 에이전트 뷰를 닫거나, 셸을 닫거나, 새로운 대화형 세션을 시작해도 디스패치된 작업은 계속됩니다.128백그라운드 세션은 계속 작동하기 위해 열린 터미널이 필요하지 않습니다. 별도의 [감독자 프로세스](#the-supervisor-process)가 실행하므로 에이전트 뷰를 닫거나, 셸을 닫거나, 새로운 대화형 세션을 시작해도 디스패치된 작업은 계속됩니다.

121 129 

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

123 131 

124### 행 요약132### 행 요약

125 133 

158 166 

159분리는 백그라운드 세션을 중지하지 않습니다: `←`, `Ctrl+C`, `Ctrl+D`, `Ctrl+Z` 및 `/exit`은 모두 실행 상태로 둡니다. 세션 내에서 세션을 종료하려면 `/stop`을 실행합니다.167분리는 백그라운드 세션을 중지하지 않습니다: `←`, `Ctrl+C`, `Ctrl+D`, `Ctrl+Z` 및 `/exit`은 모두 실행 상태로 둡니다. 세션 내에서 세션을 종료하려면 `/stop`을 실행합니다.

160 168 

161에이전트 뷰에서 디스패치하거나 백그라운드로 보낸 후, 빈 프롬프트에서 `←`를 누르면 에이전트 뷰에서 연결한 세션뿐만 아니라 모든 Claude Code 세션에서 작동합니다. 현재 세션을 백그라운드로 보내고 해당 세션이 미리 선택된 상태로 에이전트 뷰를 열어 터미널을 떠나지 않고 세션을 전환할 수 있습니다. `/config`에서 이 단축키를 끌 수 있습니다.169에이전트 뷰에서 디스패치하거나 백그라운드로 보낸 후, 빈 프롬프트에서 `←`를 누르면 에이전트 뷰에서 연결한 세션뿐만 아니라 모든 Claude Code 세션에서 작동합니다. 현재 세션을 백그라운드로 보내고 해당 행이 선택된 상태로 에이전트 뷰를 열어 터미널을 떠나지 않고 세션을 전환할 수 있습니다. 행은 대화 기록이 없는 새로운 세션에서도 생성되므로 `→`는 이를 반환합니다. 해당 행이 유일한 경우 에이전트 뷰는 아래에 온보딩 힌트를 표시합니다. `/config`에서 이 단축키를 끌 수 있습니다(`leftArrowOpensAgents` 설정).

162 170 

163### 목록 구성171### 목록 구성

164 172 

173 181 

174세션을 목록에서 제거하려면 `Ctrl+X`를 눌러 중지하고 2초 이내에 `Ctrl+X`를 다시 눌러 삭제합니다. 그룹 헤더에서 `Ctrl+X`를 누르면 확인 후 해당 그룹의 모든 세션이 삭제됩니다.182세션을 목록에서 제거하려면 `Ctrl+X`를 눌러 중지하고 2초 이내에 `Ctrl+X`를 다시 눌러 삭제합니다. 그룹 헤더에서 `Ctrl+X`를 누르면 확인 후 해당 그룹의 모든 세션이 삭제됩니다.

175 183 

176삭제하면 세션이 에이전트 뷰에서 제거되고 [worktree](#how-file-edits-are-isolated)를 정리하며, 커밋되지 않은 변경 사항을 포함합니다. 따라서 삭제하기 전에 유지하려는 작업을 푸시하거나 커밋합니다. 대화 트랜스크립트는 디스크에 남아 있으며 `claude --resume`을 통해 사용 가능합니다.184삭제하면 세션이 에이전트 뷰에서 제거되고 대화 트랜스크립트가 제거됩니다. Claude가 세션에 대해 [worktree를 생성](#how-file-edits-are-isolated)한 경우 삭제하면 커밋되지 않은 변경 사항을 포함한 해당 worktree도 제거되므로 유지하려는 작업을 먼저 푸시하거나 커밋합니다. 직접 생성하고 세션을 시작한 worktree는 제자리에 남겨집니다.

177 185 

178오래된 완료된 세션은 목록을 짧게 유지하기 위해 `… N more` 행으로 접힙니다. 실패 및 열린 풀 리퀘스트가 있는 세션은 항상 표시됩니다.186오래된 완료된 세션은 목록을 짧게 유지하기 위해 `… N more` 행으로 접힙니다. 실패 및 열린 풀 리퀘스트가 있는 세션은 항상 표시됩니다.

179 187 

192에이전트 뷰에서 `?`를 눌러 모든 단축키를 확인합니다. 아래 표는 이를 요약합니다.200에이전트 뷰에서 `?`를 눌러 모든 단축키를 확인합니다. 아래 표는 이를 요약합니다.

193 201 

194| 단축키 | 작업 |202| 단축키 | 작업 |

195| :-------------------- | :----------------------------------- |203| :-------------------- | :------------------------------------ |

196| `↑` / `↓` | 행 간 이동 |204| `↑` / `↓` | 행 간 이동 |

197| `Enter` | 선택된 세션에 연결하거나, 입력에 텍스트가 있으면 디스패치 |205| `Enter` | 선택된 세션에 연결하거나, 입력에 텍스트가 있으면 디스패치 |

198| `Space` | 선택된 세션의 엿보기 패널 열기 또는 닫기 |206| `Space` | 선택된 세션의 엿보기 패널 열기 또는 닫기 |

199| `Shift+Enter` | 디스패치하고 즉시 연결 |207| `Shift+Enter` | 디스패치하고 즉시 연결 |

200| `→` | 선택된 세션에 연결 |208| `→` | 선택된 세션에 연결 |

201| `Alt+1`..`Alt+9` | 현재 그룹의 세션 1–9에 연결 |209| `Alt+1`..`Alt+9` | 포커스된 세션의 디렉토리에서 세션 1–9에 연결 |

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

203| `Ctrl+S` | 상태와 디렉토리 간 그룹화 전환 |211| `Ctrl+S` | 상태와 디렉토리 간 그룹화 전환 |

204| `Ctrl+T` | 선택된 세션 고정 또는 고정 해제 |212| `Ctrl+T` | 선택된 세션 고정 또는 고정 해제 |

205| `Ctrl+R` | 선택된 세션 이름 바꾸기 |213| `Ctrl+R` | 선택된 세션 이름 바꾸기 |

206| `Ctrl+G` | `$EDITOR`에서 디스패치 프롬프트 열기 |214| `Ctrl+G` | `$VISUAL` 또는 `$EDITOR`에서 디스패치 프롬프트 열기 |

207| `Ctrl+X` | 세션 중지; 2초 이내에 다시 눌러 삭제 |215| `Ctrl+X` | 세션 중지; 2초 이내에 다시 눌러 삭제 |

208| `Shift+↑` / `Shift+↓` | 선택된 세션 순서 변경 |216| `Shift+↑` / `Shift+↓` | 선택된 세션 순서 변경 |

209| `Esc` | 엿보기 패널 닫기, 입력 지우기 또는 종료 |217| `Esc` | 엿보기 패널 닫기, 입력 지우기 또는 종료 |

251 259 

252대화형 세션에서 백그라운드로 이동하면 저장된 대화에서 재개되는 새로운 프로세스가 시작되므로 서브에이전트, [모니터](/ko/tools-reference#monitor-tool) 및 백그라운드 명령을 실행하는 것이 이동되지 않습니다. Claude는 실행 중인 것이 있을 때 백그라운드로 이동하기 전에 확인을 요청합니다. 백그라운드에 있으면 세션은 새로운 서브에이전트, 모니터 및 백그라운드 명령을 시작할 수 있으며, 이들은 나중의 분리 및 재연결 전체에서 계속 실행됩니다.260대화형 세션에서 백그라운드로 이동하면 저장된 대화에서 재개되는 새로운 프로세스가 시작되므로 서브에이전트, [모니터](/ko/tools-reference#monitor-tool) 및 백그라운드 명령을 실행하는 것이 이동되지 않습니다. Claude는 실행 중인 것이 있을 때 백그라운드로 이동하기 전에 확인을 요청합니다. 백그라운드에 있으면 세션은 새로운 서브에이전트, 모니터 및 백그라운드 명령을 시작할 수 있으며, 이들은 나중의 분리 및 재연결 전체에서 계속 실행됩니다.

253 261 

262원본 실행의 구성 플래그는 백그라운드로 이동된 세션으로 전달되므로 MCP 서버, 설정 및 폴백 모델이 계속 적용됩니다:

263 

264* `--mcp-config` 및 `--strict-mcp-config`

265* `--settings`

266* `--add-dir`

267* `--plugin-dir`

268* `--fallback-model`

269* `--allow-dangerously-skip-permissions`

270 

271`--allow-dangerously-skip-permissions`를 전달하면 백그라운드 세션에서 `bypassPermissions`에 도달할 수 있지만 새로운 것을 부여하지는 않습니다. 이 모드는 여전히 [권한 모드, 모델 및 노력](#permission-mode-model-and-effort)에 설명된 동일한 일회성 대화형 수락이 필요합니다.

272 

254### 셸에서273### 셸에서

255 274 

256`--bg`를 전달하여 백그라운드로 직접 이동하는 세션을 시작합니다:275`--bg`를 전달하여 백그라운드로 직접 이동하는 세션을 시작합니다:

283 302 

284### 파일 편집이 격리되는 방식303### 파일 편집이 격리되는 방식

285 304 

286에이전트 뷰, `/bg` 또는 `claude --bg`에서 시작된 모든 백그라운드 세션은 작업 디렉토리에서 시작됩니다. 파일을 편집하기 전에 Claude는 세션을 `.claude/worktrees/` 아래의 격리된 [git worktree](/ko/worktrees)로 이동하므로 병렬 세션은 동일한 체크아웃을 읽을 수 있지만 각각은 자신의 것에 씁니다. Claude는 세션이 이미 `.claude/worktrees/` 아래에 있을 때, 작업 디렉토리가 git 저장소가 아닐 때, 또는 작업 디렉토리 외부에 쓸 때는 이를 건너뜁니다.305에이전트 뷰, `/bg` 또는 `claude --bg`에서 시작된 모든 백그라운드 세션은 작업 디렉토리에서 시작됩니다. 파일을 편집하기 전에 Claude는 세션을 `.claude/worktrees/` 아래의 격리된 [git worktree](/ko/worktrees)로 이동하므로 병렬 세션은 동일한 체크아웃을 읽을 수 있지만 각각은 자신의 것에 씁니다.

306 

307Claude는 다음의 경우 worktree를 건너뜁니다:

308 

309* 세션이 이미 연결된 git worktree 내부에 있으며, Claude가 `.claude/worktrees/` 아래에 생성했거나 다른 곳에서 `git worktree add`로 생성했는지 여부

310* 작업 디렉토리가 git 저장소가 아님

311* 쓰기가 작업 디렉토리 외부

312 

313git worktree가 비실용적인 저장소에 대해 worktree 격리를 끄려면 [`worktree.bgIsolation`](/ko/settings#worktree-settings)을 `"none"`으로 설정합니다. 백그라운드 세션은 먼저 worktree로 이동하지 않고 작업 복사본을 직접 편집합니다. 프로젝트의 `.claude/settings.json`에 설정을 추가합니다:

314 

315```json theme={null}

316{

317 "worktree": {

318 "bgIsolation": "none"

319 }

320}

321```

322 

323<Note>

324 `worktree.bgIsolation` 설정은 Claude Code v2.1.143 이상이 필요합니다.

325</Note>

287 326 

288git 저장소 외부에서 세션은 작업 디렉토리에 직접 쓰며 서로 격리되지 않으므로 동일한 파일을 편집하는 병렬 세션을 디스패치하지 않도록 합니다.327git 저장소 외부에서 세션은 작업 디렉토리에 직접 쓰며 서로 격리되지 않으므로 동일한 파일을 편집하는 병렬 세션을 디스패치하지 않도록 합니다.

289 328 

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

291 330 

292서브에이전트가 시작된 방식에 관계없이 항상 자체 워크트리에서 실행되도록 하려면 프론트매터에서 [`isolation: worktree`](/ko/sub-agents#supported-frontmatter-fields)를 설정합니다.331세션의 worktree 경로를 찾으려면 세션을 엿보거나 연결하고 작업 디렉토리를 확인합니다.

332 

333서브에이전트가 시작된 방식에 관계없이 항상 자체 worktree에서 실행되도록 하려면 프론트매터에서 [`isolation: worktree`](/ko/sub-agents#supported-frontmatter-fields)를 설정합니다.

293 334 

294### 모델 설정335### 모델 설정

295 336 

307 348 

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

309 350 

351권한 모드는 감독자가 나중에 [세션의 프로세스를 중지하고 다시 시작](#the-supervisor-process)할 때 백그라운드 세션으로 시작한 권한 모드가 유지됩니다. `claude --bg --dangerously-skip-permissions` 또는 `claude --bg --permission-mode bypassPermissions`로 실행한 세션은 디렉토리의 `defaultMode`로 폴백하는 대신 해당 재시작 후 `bypassPermissions`에 유지됩니다.

352 

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

311 354 

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

313claude agents --permission-mode plan --model opus --effort high356claude agents --permission-mode plan --model opus --effort high

314```357```

315 358 

359`claude agents`는 또한 `--dangerously-skip-permissions`를 `--permission-mode bypassPermissions`의 약자로 허용하며, `--allow-dangerously-skip-permissions`를 사용하여 각 디스패치된 세션의 `Shift+Tab` 사이클에서 `bypassPermissions`를 사용 가능하게 만들 수 있습니다. 둘 다 [최상위 CLI 플래그](/ko/cli-reference)와 일치합니다.

360 

316<Note>361<Note>

317 `claude agents`에 `--permission-mode`, `--model` 또는 `--effort`를 전달하려면 Claude Code v2.1.142 이상이 필요합니다. 이전 버전은 이러한 플래그를 unknown-option 오류로 거부합니다.362 `claude agents`에 `--permission-mode`, `--model`, `--effort` 또는 `--dangerously-skip-permissions`를 전달하려면 Claude Code v2.1.142 이상이 필요합니다. `claude agents`의 `--allow-dangerously-skip-permissions`는 v2.1.143 이상이 필요합니다. 이전 버전은 이러한 플래그를 unknown-option 오류로 거부합니다.

318</Note>363</Note>

319 364 

320활성 기본값은 디스패치 입력 아래의 바닥글에 나타납니다.365활성 기본값은 디스패치 입력 아래의 바닥글에 나타납니다.

325 370 

326### 설정, 플러그인 및 MCP 서버371### 설정, 플러그인 및 MCP 서버

327 372 

328에이전트 뷰는 설정, 플러그인, MCP 서버 및 추가 디렉토리를 로드하기 위해 `claude`와 동일한 구성 플래그를 허용합니다. 각 플래그는 에이전트 뷰 자체에 적용되며 디스패치하는 모든 세션에 전달되므로 이러한 방식으로 로드하는 플러그인 또는 MCP 서버는 해당 세션에서도 사용 가능합니다.373에이전트 뷰는 설정, 플러그인, MCP 서버 및 추가 디렉토리를 로드하기 위해 `claude`와 동일한 구성 플래그를 허용합니다. 이러한 플래그는 Claude Code v2.1.142 이상이 필요합니다. 각 플래그는 에이전트 뷰 자체에 적용되며 디스패치하는 모든 세션에 전달되므로 이러한 방식으로 로드하는 플러그인 또는 MCP 서버는 해당 세션에서도 사용 가능합니다.

329 374 

330| 플래그 | 효과 |375| 플래그 | 효과 |

331| :----------------------------------------------------------------------------------------------- | :------------------------------------------ |376| :----------------------------------------------------------------------------------------------- | :------------------------------------------ |

348모든 백그라운드 세션에는 셸에서 사용할 수 있는 짧은 ID가 있습니다. ID는 `claude --bg`로 세션을 시작할 때 출력되며, 각 세션의 ID는 `~/.claude/jobs/` 아래의 디렉터리 이름입니다. 이 명령은 스크립팅이나 에이전트 뷰를 열고 싶지 않을 때 유용합니다.393모든 백그라운드 세션에는 셸에서 사용할 수 있는 짧은 ID가 있습니다. ID는 `claude --bg`로 세션을 시작할 때 출력되며, 각 세션의 ID는 `~/.claude/jobs/` 아래의 디렉터리 이름입니다. 이 명령은 스크립팅이나 에이전트 뷰를 열고 싶지 않을 때 유용합니다.

349 394 

350| 명령 | 목적 |395| 명령 | 목적 |

351| :--------------------- | :------------------------------------------------------ |396| :--------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------- |

352| `claude agents` | 에이전트 뷰 열기. `--cwd <path>`를 전달하여 해당 디렉터리 아래에서 시작된 세션만 나열 |397| `claude agents` | 에이전트 뷰 열기 |

398| `claude agents --cwd <path>` | `<path>` 아래에서 시작된 세션으로 범위가 지정된 에이전트 뷰 열기 |

353| `claude attach <id>` | 이 터미널에서 세션에 연결 |399| `claude attach <id>` | 이 터미널에서 세션에 연결 |

354| `claude logs <id>` | 세션의 최근 출력 인쇄 |400| `claude logs <id>` | 세션의 최근 출력 인쇄 |

355| `claude stop <id>` | 세션 중지. `claude kill`도 허용 |401| `claude stop <id>` | 세션 중지. `claude kill`도 허용 |

356| `claude respawn <id>` | 대화를 유지하면서 중지된 세션 다시 시작 |402| `claude respawn <id>` | 세션을 다시 시작하고, 실행 중이거나 중지된 상태에서 대화를 유지합니다. 예를 들어 업데이트된 Claude Code 바이너리를 선택하기 위해 |

357| `claude respawn --all` | 모든 중지된 세션 다시 시작 |403| `claude respawn --all` | 모든 실행 중인 세션을 다시 시작합니다. 예를 들어 모든 세션을 한 번에 업데이트된 Claude Code 바이너리로 이동하기 위해 |

358| `claude rm <id>` | 목록에서 세션 제거. 커밋되지 않은 변경 사항이 없으면 worktree 정리 |404| `claude rm <id>` | 세션 및 해당 대화 기록 제거. 커밋되지 않은 변경 사항이 없으면 세션을 위해 Claude가 생성한 worktree를 제거합니다. 그렇지 않으면 정리할 수 있도록 worktree 경로를 인쇄합니다. 직접 생성한 worktree는 그대로 둡니다 |

405| `claude daemon status` | [감독자](#the-supervisor-process)의 상태, 버전, 소켓 디렉터리 및 워커 수 인쇄 |

359 406 

360## 백그라운드 세션이 호스팅되는 방식407## 백그라운드 세션이 호스팅되는 방식

361 408 

383| `~/.claude/daemon/roster.json` | 실행 중인 백그라운드 세션 목록, 다시 시작 후 다시 연결하는 데 사용됨 |430| `~/.claude/daemon/roster.json` | 실행 중인 백그라운드 세션 목록, 다시 시작 후 다시 연결하는 데 사용됨 |

384| `~/.claude/jobs/<id>/state.json` | 에이전트 뷰에 표시되는 세션별 상태 |431| `~/.claude/jobs/<id>/state.json` | 에이전트 뷰에 표시되는 세션별 상태 |

385 432 

433파일을 직접 읽지 않고 이 상태를 검사하려면 `claude daemon status`를 실행합니다. 감독자에 도달할 수 있는지 여부, 프로세스 ID 및 버전, 소켓 디렉토리, 그리고 활성 백그라운드 세션의 수를 보고합니다. `/doctor`는 동일한 검사의 요약을 포함합니다. Windows에서 `claude daemon status`는 감독자의 파이프 키 파일이 잠겨 있거나 읽을 수 없을 때 일반적인 연결 실패를 보고하는 대신 기본 파일 오류를 표시합니다.

434 

386### 에이전트 뷰 끄기435### 에이전트 뷰 끄기

387 436 

388백그라운드 에이전트 및 에이전트 뷰를 완전히 끄려면 `disableAgentView` [설정](/ko/settings)을 `true`로 설정하거나 `CLAUDE_CODE_DISABLE_AGENT_VIEW` 환경 변수를 설정합니다. 관리자는 [관리 설정](/ko/permissions#managed-settings)을 통해 이를 적용할 수 있습니다.437백그라운드 에이전트 및 에이전트 뷰를 완전히 끄려면 `disableAgentView` [설정](/ko/settings)을 `true`로 설정하거나 `CLAUDE_CODE_DISABLE_AGENT_VIEW` 환경 변수를 설정합니다. 관리자는 [관리 설정](/ko/permissions#managed-settings)을 통해 이를 적용할 수 있습니다.

397 446 

398### 에이전트 뷰가 세션 없이 열림447### 에이전트 뷰가 세션 없이 열림

399 448 

400에이전트 뷰는 첫 번째 세션을 디스패치할 때까지 비어 있습니다. 하단의 입력에 프롬프트를 입력하고 `Enter`를 누릅니다.449첫 번째 세션을 디스패치하기 전에 에이전트 뷰는 세션 목록 대신 짧은 온보딩 힌트와 예제 프롬프트를 표시합니다. 하단의 입력에 프롬프트를 입력하고 `Enter`를 눌러 첫 번째 세션을 디스패치합니다.

401 450 

402### 백그라운드 작업이 실행 중이어서 에이전트를 열 수 없음451### 백그라운드 작업이 실행 중이어서 에이전트를 열 수 없음

403 452 

407 456 

408디스패치 입력은 대화형 오프닝이 아닌 작업 설명을 예상합니다. 4자 미만의 프롬프트는 `Too short` 힌트와 함께 거부되므로 실수로 누른 키가 세션을 시작하지 않습니다. 세션이 수행할 작업을 설명합니다. 예를 들어 `investigate the flaky checkout test`와 같이 설명합니다.457디스패치 입력은 대화형 오프닝이 아닌 작업 설명을 예상합니다. 4자 미만의 프롬프트는 `Too short` 힌트와 함께 거부되므로 실수로 누른 키가 세션을 시작하지 않습니다. 세션이 수행할 작업을 설명합니다. 예를 들어 `investigate the flaky checkout test`와 같이 설명합니다.

409 458 

410### 머신을 깨운 후 세션이 중지됨으로 표시됨459### 머신 종료 후 세션이 실패로 표시됨

460 

461머신을 종료하거나 재시작하면 실행 중인 백그라운드 세션이 중지되므로, 다음에 에이전트 뷰를 열 때 실패로 표시됩니다. 이들 중 하나에 연결하거나, 엿보거나, 답변하면 세션이 중단된 위치에서 다시 시작됩니다.

411 462 

412백그라운드 세션은 절전 또는 종료를 견디지 못하므로, 실행 중이던 세션은 깨어난 후 중지됨으로 표시됩니다. 이들 중 하나에 연결하거나, 엿보거나, 답변하면 세션이 중단된 위치에서 다시 시작됩니다. 모두 한 번에 다시 시작하려면 `claude respawn --all`을 실행합니다.463절전 상태만으로는 이 문제가 발생하지 않습니다. 세션은 절전 상태에서 보존되며 감독자는 깨어날 때 이들에 다시 연결됩니다.

413 464 

414### 세션이 연결 후 응답이 느림465### 세션이 연결 후 응답이 느림

415 466 

417 468 

418### `.claude/worktrees/`가 채워지고 있음469### `.claude/worktrees/`가 채워지고 있음

419 470 

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

421 472 

422## 제한 사항473## 제한 사항

423 474 

424에이전트 뷰는 연구 미리보기 상태이며 다음과 같은 제한 사항이 있습니다:475에이전트 뷰는 연구 미리보기 상태이며 다음과 같은 제한 사항이 있습니다:

425 476 

426* **속도 제한 적용**: 백그라운드 세션은 대화형 세션과 동일하게 구독 사용량을 소모하므로 10개의 에이전트를 병렬로 실행하면 할당량을 약 10배 빠르게 소모합니다.477* **속도 제한 적용**: 백그라운드 세션은 대화형 세션과 동일하게 구독 사용량을 소모하므로 10개의 에이전트를 병렬로 실행하면 할당량을 약 10배 빠르게 소모합니다.

427* **세션은 로컬입니다**: 백그라운드 세션은 사용자의 머신에서 실행되며 머신이 절전 모드로 전환되거나 종료되면 중지됩니다.478* **세션은 로컬입니다**: 백그라운드 세션은 사용자의 머신에서 실행되며 머신이 절전 모드로 전환되어도 유지되지만 머신이 종료되면 중지됩니다.

428* **워크트리는 세션과 함께 삭제됩니다**: 자체 워크트리에서 파일을 편집한 세션을 삭제하기 전에 변경 사항을 병합하거나 푸시합니다.479* **Claude에서 생성한 워크트리는 에이전트 뷰의 세션과 함께 삭제됩니다**: 자체 워크트리에서 파일을 편집한 세션을 삭제하기 전에 변경 사항을 병합하거나 푸시합니다. `claude rm`은 커밋되지 않은 변경 사항이 있는 워크트리를 유지하며, 사용자가 직접 생성한 워크트리는 그대로 유지됩니다.

429 480 

430## 관련 리소스481## 관련 리소스

431 482 

11이러한 명령어를 사용하여 세션을 시작하고, 콘텐츠를 파이프하고, 대화를 재개하고, 업데이트를 관리할 수 있습니다:11이러한 명령어를 사용하여 세션을 시작하고, 콘텐츠를 파이프하고, 대화를 재개하고, 업데이트를 관리할 수 있습니다:

12 12 

13| 명령어 | 설명 | 예시 |13| 명령어 | 설명 | 예시 |

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

15| `claude` | 대화형 세션 시작 | `claude` |15| `claude` | 대화형 세션 시작 | `claude` |

16| `claude "query"` | 초기 프롬프트로 대화형 세션 시작 | `claude "explain this project"` |16| `claude "query"` | 초기 프롬프트로 대화형 세션 시작 | `claude "explain this project"` |

17| `claude -p "query"` | SDK를 통해 쿼리하고 종료 | `claude -p "explain this function"` |17| `claude -p "query"` | SDK를 통해 쿼리하고 종료 | `claude -p "explain this function"` |

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

25| `claude auth logout` | Anthropic 계정에서 로그아웃합니다 | `claude auth logout` |25| `claude auth logout` | Anthropic 계정에서 로그아웃합니다 | `claude auth logout` |

26| `claude auth status` | 인증 상태를 JSON으로 표시합니다. 사람이 읽을 수 있는 출력을 위해 `--text`를 사용합니다. 로그인된 경우 코드 0으로 종료되고, 로그인되지 않은 경우 1로 종료됩니다 | `claude auth status` |26| `claude auth status` | 인증 상태를 JSON으로 표시합니다. 사람이 읽을 수 있는 출력을 위해 `--text`를 사용합니다. 로그인된 경우 코드 0으로 종료되고, 로그인되지 않은 경우 1로 종료됩니다 | `claude auth status` |

27| `claude agents` | [에이전트 보기](/ko/agent-view)를 열어 병렬 백그라운드 세션을 모니터링하고 디스패치합니다. `--cwd <path>`를 사용하여 해당 디렉토리 아래에서 시작된 세션만 표시합니다 | `claude agents` |27| `claude agents` | [에이전트 보기](/ko/agent-view)를 열어 병렬 백그라운드 세션을 모니터링하고 디스패치합니다. `--cwd <path>`를 사용하여 해당 디렉토리 아래에서 시작된 세션만 표시합니다. `--permission-mode`, `--model`, 또는 `--effort`를 전달하여 [디스패치된 세션의 기본값](/ko/agent-view#permission-mode-model-and-effort)을 설정합니다. 최상위 `claude` 명령어처럼 `--settings`, `--add-dir`, `--plugin-dir`, 및 `--mcp-config`를 허용합니다. 대화형 터미널이 필요합니다 | `claude agents --cwd ~/projects/my-app` |

28| `claude attach <id>` | 이 터미널에서 [백그라운드 세션](/ko/agent-view#manage-sessions-from-the-shell)에 연결합니다 | `claude attach 7c5dcf5d` |28| `claude attach <id>` | 이 터미널에서 [백그라운드 세션](/ko/agent-view#manage-sessions-from-the-shell)에 연결합니다 | `claude attach 7c5dcf5d` |

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

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

30| `claude logs <id>` | [백그라운드 세션](/ko/agent-view#manage-sessions-from-the-shell)의 최근 출력을 인쇄합니다 | `claude logs 7c5dcf5d` |31| `claude logs <id>` | [백그라운드 세션](/ko/agent-view#manage-sessions-from-the-shell)의 최근 출력을 인쇄합니다 | `claude logs 7c5dcf5d` |

31| `claude mcp` | Model Context Protocol (MCP) 서버 구성 | [Claude Code MCP 문서](/ko/mcp) 참조 |32| `claude mcp` | Model Context Protocol (MCP) 서버 구성 | [Claude Code MCP 문서](/ko/mcp) 참조 |

32| `claude plugin` | Claude Code [plugins](/ko/plugins)를 관리합니다. 별칭: `claude plugins`. 하위 명령어는 [plugin 참조](/ko/plugins-reference#cli-commands-reference)를 참조하세요 | `claude plugin install code-review@claude-plugins-official` |33| `claude plugin` | Claude Code [plugins](/ko/plugins)를 관리합니다. 별칭: `claude plugins`. 하위 명령어는 [plugin 참조](/ko/plugins-reference#cli-commands-reference)를 참조하세요 | `claude plugin install code-review@claude-plugins-official` |

33| `claude project purge [path]` | 프로젝트의 모든 로컬 Claude Code 상태를 삭제합니다: 대화 기록, 작업 목록, 디버그 로그, 파일 편집 기록, 프롬프트 기록 라인 및 `~/.claude.json`의 프로젝트 항목. `[path]`를 생략하면 대화형 목록에서 선택할 수 있습니다. 플래그: `--dry-run`으로 미리 보기, `-y`/`--yes`로 확인 건너뛰기, `-i`/`--interactive`로 각 항목 확인, `--all`로 모든 프로젝트. [로컬 데이터 지우기](/ko/claude-directory#clear-local-data) 참조 | `claude project purge ~/work/repo --dry-run` |34| `claude project purge [path]` | 프로젝트의 모든 로컬 Claude Code 상태를 삭제합니다: 대화 기록, 작업 목록, 디버그 로그, 파일 편집 기록, 프롬프트 기록 라인 및 `~/.claude.json`의 프로젝트 항목. `[path]`를 생략하면 대화형 목록에서 선택할 수 있습니다. 플래그: `--dry-run`으로 미리 보기, `-y`/`--yes`로 확인 건너뛰기, `-i`/`--interactive`로 각 항목 확인, `--all`로 모든 프로젝트. [로컬 데이터 지우기](/ko/claude-directory#clear-local-data) 참조 | `claude project purge ~/work/repo --dry-run` |

34| `claude remote-control` | Claude.ai 또는 Claude 앱에서 Claude Code를 제어하기 위한 [Remote Control](/ko/remote-control) 서버를 시작합니다. 서버 모드에서 실행됩니다(로컬 대화형 세션 없음). [서버 모드 플래그](/ko/remote-control#start-a-remote-control-session) 참조 | `claude remote-control --name "My Project"` |35| `claude remote-control` | Claude.ai 또는 Claude 앱에서 Claude Code를 제어하기 위한 [Remote Control](/ko/remote-control) 서버를 시작합니다. 서버 모드에서 실행됩니다(로컬 대화형 세션 없음). [서버 모드 플래그](/ko/remote-control#start-a-remote-control-session) 참조 | `claude remote-control --name "My Project"` |

35| `claude respawn <id>` | 대화를 유지하면서 중지된 [백그라운드 세션](/ko/agent-view#manage-sessions-from-the-shell)을 다시 시작합니다. `--all`을 사용하여 중지된 모든 세션을 다시 시작합니다 | `claude respawn 7c5dcf5d` |36| `claude respawn <id>` | 대화를 유지하면서 실행 중이거나 중지된 [백그라운드 세션](/ko/agent-view#manage-sessions-from-the-shell)을 다시 시작합니다. `--all`을 사용하여 모든 실행 중인 세션을 다시 시작합니다(예: 업데이트된 Claude Code 바이너리를 선택하기 위해) | `claude respawn 7c5dcf5d` |

36| `claude rm <id>` | [백그라운드 세션](/ko/agent-view#manage-sessions-from-the-shell)을 목록에서 제거합니다 | `claude rm 7c5dcf5d` |37| `claude rm <id>` | [백그라운드 세션](/ko/agent-view#manage-sessions-from-the-shell)을 목록에서 제거합니다 | `claude rm 7c5dcf5d` |

37| `claude setup-token` | CI 및 스크립트를 위한 장기 OAuth 토큰을 생성합니다. 토큰을 저장하지 않고 터미널에 인쇄합니다. Claude 구독이 필요합니다. [장기 토큰 생성](/ko/authentication#generate-a-long-lived-token) 참조 | `claude setup-token` |38| `claude setup-token` | CI 및 스크립트를 위한 장기 OAuth 토큰을 생성합니다. 토큰을 저장하지 않고 터미널에 인쇄합니다. Claude 구독이 필요합니다. [장기 토큰 생성](/ko/authentication#generate-a-long-lived-token) 참조 | `claude setup-token` |

38| `claude stop <id>` | [백그라운드 세션](/ko/agent-view#manage-sessions-from-the-shell)을 중지합니다. `claude kill`도 허용됩니다 | `claude stop 7c5dcf5d` |39| `claude stop <id>` | [백그라운드 세션](/ko/agent-view#manage-sessions-from-the-shell)을 중지합니다. `claude kill`도 허용됩니다 | `claude stop 7c5dcf5d` |

68| `--effort` | 현재 세션에 대한 [노력 수준](/ko/model-config#adjust-effort-level)을 설정합니다. 옵션: `low`, `medium`, `high`, `xhigh`, `max`; 사용 가능한 수준은 모델에 따라 다릅니다. [`effortLevel`](/ko/settings#available-settings) 설정을 이 세션에 대해 재정의하며 지속되지 않습니다 | `claude --effort high` |69| `--effort` | 현재 세션에 대한 [노력 수준](/ko/model-config#adjust-effort-level)을 설정합니다. 옵션: `low`, `medium`, `high`, `xhigh`, `max`; 사용 가능한 수준은 모델에 따라 다릅니다. [`effortLevel`](/ko/settings#available-settings) 설정을 이 세션에 대해 재정의하며 지속되지 않습니다 | `claude --effort high` |

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

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

71| `--fallback-model` | 기본 모델이 과부하 상태일 때 지정된 모델로 자동 폴백을 활성화합니다(인쇄 모드만 해당) | `claude -p --fallback-model sonnet "query"` |72| `--fallback-model` | 기본 모델이 과부하 상태일 때 지정된 모델로 자동 폴백을 활성화합니다. 인쇄 모드(`-p`)와 [백그라운드 세션](/ko/agent-view)에서 적용되며, 이는 비대화형으로 실행됩니다. 대화형 세션에서는 무시됩니다 | `claude -p --fallback-model sonnet "query"` |

72| `--fork-session` | 재개할 때 원본을 재사용하는 대신 새 세션 ID를 생성합니다(`--resume` 또는 `--continue`와 함께 사용) | `claude --resume abc123 --fork-session` |73| `--fork-session` | 재개할 때 원본을 재사용하는 대신 새 세션 ID를 생성합니다(`--resume` 또는 `--continue`와 함께 사용) | `claude --resume abc123 --fork-session` |

73| `--from-pr` | 특정 pull request에 연결된 세션을 재개합니다. PR 번호, GitHub 또는 GitHub Enterprise PR URL, GitLab merge request URL 또는 Bitbucket pull request URL을 허용합니다. Claude가 pull request를 생성할 때 세션이 자동으로 연결됩니다 | `claude --from-pr 123` |74| `--from-pr` | 특정 pull request에 연결된 세션을 재개합니다. PR 번호, GitHub 또는 GitHub Enterprise PR URL, GitLab merge request URL 또는 Bitbucket pull request URL을 허용합니다. Claude가 pull request를 생성할 때 세션이 자동으로 연결됩니다 | `claude --from-pr 123` |

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

29 29 

30관리자가 조직에 대해 Code Review를 [활성화](#set-up-code-review)하면 리포지토리의 구성된 동작에 따라 PR이 열릴 때, 모든 푸시 시 또는 수동으로 요청할 때 검토가 트리거됩니다. PR에서 `@claude review`를 [댓글로 작성](#manually-trigger-reviews)하면 모든 모드에서 검토가 시작됩니다.30관리자가 조직에 대해 Code Review를 [활성화](#set-up-code-review)하면 리포지토리의 구성된 동작에 따라 PR이 열릴 때, 모든 푸시 시 또는 수동으로 요청할 때 검토가 트리거됩니다. PR에서 `@claude review`를 [댓글로 작성](#manually-trigger-reviews)하면 모든 모드에서 검토가 시작됩니다.

31 31 

32검토가 실행되면 여러 에이전트가 Anthropic 인프라에서 병렬로 diff 및 주변 코드를 분석합니다. 각 에이전트는 다른 클래스의 문제를 찾고, 검증 단계에서 후보를 실제 코드 동작과 비교하여 거짓 양성을 필터링합니다. 결과는 중복 제거되고 심각도별로 순위가 지정되며 문제가 발견된 특정 라인에 인라인 댓글로 게시됩니다. 문제가 발견되지 않으면 Claude는 PR에 짧은 확인 댓글을 게시합니다.32검토가 실행되면 여러 에이전트가 Anthropic 인프라에서 병렬로 diff 및 주변 코드를 분석합니다. 각 에이전트는 다른 클래스의 문제를 찾고, 검증 단계에서 후보를 실제 코드 동작과 비교하여 거짓 양성을 필터링합니다. 결과는 중복 제거되고 심각도별로 순위가 지정되며 문제가 발견된 특정 라인에 인라인 댓글로 게시됩니다. 문제가 발견되지 않으면 Code Review는 GitHub 확인 실행을 업데이트하여 문제가 감지되지 않았음을 표시합니다. Claude는 또한 PR에 짧은 확인 댓글을 게시할 수 있습니다.

33 33 

34검토는 PR 크기 및 복잡도에 따라 비용이 증가하며 평균 20분 내에 완료됩니다. 관리자는 [분석 대시보드](#view-usage)를 통해 검토 활동 및 지출을 모니터링할 수 있습니다.34검토는 PR 크기 및 복잡도에 따라 비용이 증가하며 평균 20분 내에 완료됩니다. 관리자는 [분석 대시보드](#view-usage)를 통해 검토 활동 및 지출을 모니터링할 수 있습니다.

35 35 

225 225 

226## 가격226## 가격

227 227 

228Code Review는 토큰 사용량을 기반으로 청구됩니다. 각 검토는 평균 \$15-25이며 PR 크기, 코드베이스 복잡도 및 검증이 필요한 문제 수에 따라 확장됩니다. Code Review 사용량은 [추가 사용량](https://support.claude.com/en/articles/12429409-extra-usage-for-paid-claude-plans)을 통해 별도로 청구되며 계획의 포함된 사용량에 포함되지 않습니다.228Code Review는 토큰 사용량을 기반으로 청구됩니다. 각 검토는 평균 \$15-25의 비용이 소요되며, PR 크기, 코드베이스 복잡도 및 검증이 필요한 문제의 수에 따라 확장됩니다. Code Review 사용량은 [사용량 크레딧](https://support.claude.com/ko/articles/12429409-extra-usage-for-paid-claude-plans)을 통해 별도로 청구되며 계획에 포함된 사용량에 포함되지 않습니다.

229 229 

230선택한 검토 트리거는 총 비용에 영향을 미칩니다:230선택한 검토 트리거는 총 비용에 영향을 미칩니다:

231 231 

232* **Once after PR creation**: PR당 한 번 실행됩니다232* **Once after PR creation**: PR당 한 번 실행됩니다

233* **After every push**: 각 푸시에서 실행되어 푸시 수만큼 비용이 증가합니다233* **After every push**: 각 푸시에서 실행되어 푸시 수만큼 비용이 곱해집니다

234* **Manual**: PR에서 누군가 `@claude review`를 댓글로 작성할 때까지 검토가 없습니다234* **Manual**: PR에서 누군가 `@claude review`를 댓글로 작성할 때까지 검토가 없습니다

235 235 

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

62| `/effort [level\|auto]` | 모델 [effort level](/ko/model-config#adjust-effort-level)을 설정합니다. `low`, `medium`, `high`, `xhigh` 또는 `max`를 허용합니다. 사용 가능한 수준은 모델에 따라 다르며 `max`는 세션 전용입니다. `auto`는 모델 기본값으로 재설정합니다. 인수 없이 대화형 슬라이더를 엽니다. 왼쪽 및 오른쪽 화살표를 사용하여 수준을 선택하고 `Enter`를 눌러 적용합니다. 현재 응답이 완료될 때까지 기다리지 않고 즉시 적용됩니다 |62| `/effort [level\|auto]` | 모델 [effort level](/ko/model-config#adjust-effort-level)을 설정합니다. `low`, `medium`, `high`, `xhigh` 또는 `max`를 허용합니다. 사용 가능한 수준은 모델에 따라 다르며 `max`는 세션 전용입니다. `auto`는 모델 기본값으로 재설정합니다. 인수 없이 대화형 슬라이더를 엽니다. 왼쪽 및 오른쪽 화살표를 사용하여 수준을 선택하고 `Enter`를 눌러 적용합니다. 현재 응답이 완료될 때까지 기다리지 않고 즉시 적용됩니다 |

63| `/exit` | CLI를 종료합니다. 연결된 [background session](/ko/agent-view#attach-to-a-session)에서 이 명령어는 분리하고 세션은 계속 실행됩니다. 별칭: `/quit` |63| `/exit` | CLI를 종료합니다. 연결된 [background session](/ko/agent-view#attach-to-a-session)에서 이 명령어는 분리하고 세션은 계속 실행됩니다. 별칭: `/quit` |

64| `/export [filename]` | 현재 대화를 일반 텍스트로 내보냅니다. 파일 이름이 있으면 해당 파일에 직접 작성합니다. 없으면 클립보드에 복사하거나 파일에 저장할 수 있는 대화 상자를 엽니다 |64| `/export [filename]` | 현재 대화를 일반 텍스트로 내보냅니다. 파일 이름이 있으면 해당 파일에 직접 작성합니다. 없으면 클립보드에 복사하거나 파일에 저장할 수 있는 대화 상자를 엽니다 |

65| `/extra-usage` | 속도 제한에 도달했을 때 계속 작업할 수 있도록 추가 사용량을 구성합니다 |

66| `/fast [on\|off]` | [fast mode](/ko/fast-mode)를 켜거나 끕니다 |65| `/fast [on\|off]` | [fast mode](/ko/fast-mode)를 켜거나 끕니다 |

67| `/feedback [report]` | Claude Code에 대한 피드백을 제출합니다. 별칭: `/bug` |66| `/feedback [report]` | Claude Code에 대한 피드백을 제출합니다. 별칭: `/bug` |

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

121| `/theme` | 색상 테마를 변경합니다. 터미널의 어두운 또는 밝은 배경을 따르는 `auto` 옵션, 밝은 색과 어두운 색 변형, 색맹 접근 가능(daltonized) 테마, 터미널의 색상 팔레트를 사용하는 ANSI 테마 및 `~/.claude/themes/` 또는 plugins의 [custom themes](/ko/terminal-config#create-a-custom-theme)를 포함합니다. \*\*New custom theme…\*\*를 선택하여 새로 만듭니다 |120| `/theme` | 색상 테마를 변경합니다. 터미널의 어두운 또는 밝은 배경을 따르는 `auto` 옵션, 밝은 색과 어두운 색 변형, 색맹 접근 가능(daltonized) 테마, 터미널의 색상 팔레트를 사용하는 ANSI 테마 및 `~/.claude/themes/` 또는 plugins의 [custom themes](/ko/terminal-config#create-a-custom-theme)를 포함합니다. \*\*New custom theme…\*\*를 선택하여 새로 만듭니다 |

122| `/tui [default\|fullscreen]` | 터미널 UI 렌더러를 설정하고 대화를 유지하면서 다시 시작합니다. `fullscreen`은 [flicker-free alt-screen renderer](/ko/fullscreen)를 활성화합니다. 인수 없이 활성 렌더러를 인쇄합니다 |121| `/tui [default\|fullscreen]` | 터미널 UI 렌더러를 설정하고 대화를 유지하면서 다시 시작합니다. `fullscreen`은 [flicker-free alt-screen renderer](/ko/fullscreen)를 활성화합니다. 인수 없이 활성 렌더러를 인쇄합니다 |

123| `/ultraplan <prompt>` | [ultraplan](/ko/ultraplan) 세션에서 계획을 작성하고, 브라우저에서 검토한 다음, 원격으로 실행하거나 터미널로 다시 보냅니다 |122| `/ultraplan <prompt>` | [ultraplan](/ko/ultraplan) 세션에서 계획을 작성하고, 브라우저에서 검토한 다음, 원격으로 실행하거나 터미널로 다시 보냅니다 |

124| `/ultrareview [PR]` | [ultrareview](/ko/ultrareview)를 사용하여 클라우드 샌드박스에서 깊은 다중 agent 코드 검토를 실행합니다. Pro 및 Max에서 3회 무료 실행을 포함한 후 [extra usage](https://support.claude.com/en/articles/12429409-extra-usage-for-paid-claude-plans)가 필요합니다 |123| `/ultrareview [PR]` | [ultrareview](/ko/ultrareview)를 사용하여 클라우드 샌드박스에서 깊은 다중 agent 코드 검토를 실행합니다. Pro 및 Max에서 3회 무료 실행을 포함한 후 [usage credits](https://support.claude.com/en/articles/12429409-extra-usage-for-paid-claude-plans)가 필요합니다 |

125| `/upgrade` | 업그레이드 페이지를 열어 더 높은 요금제로 전환합니다 |124| `/upgrade` | 업그레이드 페이지를 열어 더 높은 요금제로 전환합니다 |

126| `/usage` | 세션 비용, 요금제 사용 제한 및 활동 통계를 표시합니다. 구독별 세부 정보는 [cost tracking guide](/ko/costs#using-the-%2Fusage-command)를 참조하세요. `/cost` 및 `/stats`는 별칭입니다 |125| `/usage` | 세션 비용, 요금제 사용 제한 및 활동 통계를 표시합니다. 구독별 세부 정보는 [cost tracking guide](/ko/costs#using-the-%2Fusage-command)를 참조하세요. `/cost` 및 `/stats`는 별칭입니다 |

126| `/usage-credits` | 제한에 도달했을 때 계속 작업할 수 있도록 사용 크레딧을 구성합니다. 이전에는 `/extra-usage` |

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

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

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

87대부분의 구성 놀라움은 작은 위치 및 구문 규칙 집합으로 추적됩니다. 버그라고 가정하기 전에 다음을 확인합니다:87대부분의 구성 놀라움은 작은 위치 및 구문 규칙 집합으로 추적됩니다. 버그라고 가정하기 전에 다음을 확인합니다:

88 88 

89| 증상 | 원인 | 해결 |89| 증상 | 원인 | 해결 |

90| :--------------------------------------------------------- | :------------------------------------------------------------------------------ | :--------------------------------------------------------------------------------------------------------------------------------------------- |90| :--------------------------------------------------------- | :--------------------------------------------------------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

91| 훅이 절대 실행되지 않음 | `matcher`가 문자열 대신 JSON 배열입니다 | 여러 도구를 일치시키기 위해 `\|`를 사용하는 단일 문자열을 사용합니다(예: `"Edit\|Write"`). [매처 패턴](/ko/hooks#matcher-patterns)을 참조합니다. |91| 훅이 절대 실행되지 않음 | `matcher`가 문자열 대신 JSON 배열입니다 | 여러 도구를 일치시키기 위해 `\|`를 사용하는 단일 문자열을 사용합니다(예: `"Edit\|Write"`). [매처 패턴](/ko/hooks#matcher-patterns)을 참조합니다. |

92| 훅이 절대 실행되지 않음 | `matcher` 값이 소문자입니다(예: `"bash"`) | 일치는 대소문자를 구분합니다. 도구 이름은 대문자입니다: `Bash`, `Edit`, `Write`, `Read`. |92| 훅이 절대 실행되지 않음 | `matcher` 값이 소문자입니다(예: `"bash"`) | 일치는 대소문자를 구분합니다. 도구 이름은 대문자입니다: `Bash`, `Edit`, `Write`, `Read`. |

93| 훅이 절대 실행되지 않음 | 훅이 독립 실행형 `.claude/hooks.json` 파일에 있습니다 | 독립 실행형 훅 파일이 없습니다. `settings.json`의 `"hooks"` 키 아래에 훅을 정의합니다. [훅 구성](/ko/hooks)을 참조합니다. |93| 훅이 절대 실행되지 않음 | 훅이 `settings.json` 대신 독립 실행형 파일에 정의되어 있습니다 | 프로젝트 또는 사용자 구성에 대한 독립 실행형 훅 파일이 없습니다. `settings.json`의 `"hooks"` 키 아래에 훅을 정의합니다. [플러그인](/ko/plugins-reference#hooks)만 별도의 `hooks/hooks.json`을 로드합니다. [훅 구성](/ko/hooks)을 참조합니다. |

94| 전역으로 설정된 권한, 훅 또는 env가 무시됩니다 | 구성이 `~/.claude.json`에 추가되었습니다 | `~/.claude.json`은 앱 상태 및 UI 토글을 보유합니다. `permissions`, `hooks` 및 `env`는 `~/.claude/settings.json`에 속합니다. 이는 두 개의 다른 파일입니다. |94| 전역으로 설정된 권한, 훅 또는 env가 무시됩니다 | 구성이 `~/.claude.json`에 추가되었습니다 | `~/.claude.json`은 앱 상태 및 UI 토글을 보유합니다. `permissions`, `hooks` 및 `env`는 `~/.claude/settings.json`에 속합니다. 이는 두 개의 다른 파일입니다. |

95| `settings.json` 값이 무시되는 것처럼 보입니다 | 동일한 키가 `settings.local.json`에 설정되어 있습니다 | `settings.local.json`은 `settings.json`을 재정의하고, 둘 다 `~/.claude/settings.json`을 재정의합니다. [설정 우선순위](/ko/settings#how-scopes-interact)를 참조합니다. |95| `settings.json` 값이 무시되는 것처럼 보입니다 | 동일한 키가 `settings.local.json`에 설정되어 있습니다 | `settings.local.json`은 `settings.json`을 재정의하고, 둘 다 `~/.claude/settings.json`을 재정의합니다. [설정 우선순위](/ko/settings#how-scopes-interact)를 참조합니다. |

96| 스킬이 `/skills`에 나타나지 않습니다 | 스킬 파일이 폴더 대신 `.claude/skills/name.md`에 있습니다 | 내부에 `SKILL.md`가 있는 폴더를 사용합니다: `.claude/skills/name/SKILL.md`. |96| 스킬이 `/skills`에 나타나지 않습니다 | 스킬 파일이 폴더 대신 `.claude/skills/name.md`에 있습니다 | 내부에 `SKILL.md`가 있는 폴더를 사용합니다: `.claude/skills/name/SKILL.md`. |

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

98| 하위 디렉토리 `CLAUDE.md` 명령이 무시되는 것처럼 보입니다 | 하위 디렉토리 파일은 세션 시작 시가 아니라 요청 시 로드됩니다 | Claude가 Read 도구로 해당 디렉토리의 파일을 읽을 때 로드되며, 시작 시가 아니고 파일을 작성하거나 생성할 때도 아닙니다. [CLAUDE.md 파일이 로드되는 방식](/ko/memory#how-claude-md-files-load)을 참조합니다. |98| 하위 디렉토리 `CLAUDE.md` 명령이 무시되는 것처럼 보입니다 | 하위 디렉토리 파일은 세션 시작 시가 아니라 요청 시 로드됩니다 | Claude가 Read 도구로 해당 디렉토리의 파일을 읽을 때 로드되며, 시작 시가 아니고 파일을 작성하거나 생성할 때도 아닙니다. [CLAUDE.md 파일이 로드되는 방식](/ko/memory#how-claude-md-files-load)을 참조합니다. |

99| 서브에이전트가 `CLAUDE.md` 명령을 무시합니다 | 서브에이전트는 항상 프로젝트 메모리를 상속하지 않습니다 | 중요한 규칙을 에이전트 파일 본문에 넣습니다. 이는 서브에이전트의 시스템 프롬프트가 됩니다. [서브에이전트 구성](/ko/sub-agents)을 참조합니다. |99| 서브에이전트가 `CLAUDE.md` 명령을 무시합니다 | 기본 제공 Explore 및 Plan 에이전트는 `CLAUDE.md`를 건너뜁니다. 사용자 정의 서브에이전트는 주 대화와 동일한 방식으로 로드합니다 | Explore 또는 Plan의 경우, 위임 프롬프트에서 명령을 다시 명시합니다. 사용자 정의 서브에이전트의 경우, 중요한 명령을 에이전트 파일 본문에 넣습니다. 이는 에이전트의 시스템 프롬프트가 됩니다. [시작 시 로드되는 항목](/ko/sub-agents#what-loads-at-startup)을 참조합니다. |

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

101| `.mcp.json`의 MCP 서버가 절대 로드되지 않습니다 | 파일이 `.claude/` 아래에 있거나 Claude Desktop의 구성 형식을 사용합니다 | 프로젝트 MCP 구성은 `.claude/` 내부가 아니라 저장소 루트에 `.mcp.json`으로 이동합니다. [MCP 구성](/ko/mcp)을 참조합니다. |101| `.mcp.json`의 MCP 서버가 절대 로드되지 않습니다 | 파일이 `.claude/` 아래에 있거나 Claude Desktop의 구성 형식을 사용합니다 | 프로젝트 MCP 구성은 `.claude/` 내부가 아니라 저장소 루트에 `.mcp.json`으로 이동합니다. [MCP 구성](/ko/mcp)을 참조합니다. |

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

2> Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt2> Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt

3> Use this file to discover all available pages before exploring further.3> Use this file to discover all available pages before exploring further.

4 4 

5# Claude Code Desktop 사용하기5# Desktop 애플리케이션

6 6 

7> Claude Code Desktop을 더 활용하기: Git 격리를 통한 병렬 세션, 드래그 앤 드롭 패널 레이아웃, 통합 터미널 및 파일 편집기, 사이드 채팅, 컴퓨터 사용, 휴대폰에서 Dispatch 세션 전송, 시각적 diff 검토, 앱 미리보기, PR 모니터링, 커넥터, 엔터프라이즈 구성.7> Claude Code Desktop을 더 활용하기: Git 격리를 통한 병렬 세션, 드래그 앤 드롭 패널 레이아웃, 통합 터미널 및 파일 편집기, 사이드 채팅, 컴퓨터 사용, 휴대폰에서 Dispatch 세션 전송, 시각적 diff 검토, 앱 미리보기, PR 모니터링, 커넥터, 엔터프라이즈 구성.

8 8 

707* **Linux**: 데스크톱 앱은 macOS 및 Windows에서만 사용 가능합니다. Linux에서는 [CLI](/ko/quickstart)를 사용합니다.707* **Linux**: 데스크톱 앱은 macOS 및 Windows에서만 사용 가능합니다. Linux에서는 [CLI](/ko/quickstart)를 사용합니다.

708* **Inline code suggestions**: Desktop은 자동 완성 스타일 제안을 제공하지 않습니다. 대화형 프롬프트 및 명시적 코드 변경을 통해 작동합니다.708* **Inline code suggestions**: Desktop은 자동 완성 스타일 제안을 제공하지 않습니다. 대화형 프롬프트 및 명시적 코드 변경을 통해 작동합니다.

709* **Agent teams**: 다중 에이전트 오케스트레이션은 [CLI](/ko/agent-teams) 및 [Agent SDK](/ko/headless)를 통해 사용 가능하며 Desktop에서는 사용할 수 없습니다.709* **Agent teams**: 다중 에이전트 오케스트레이션은 [CLI](/ko/agent-teams) 및 [Agent SDK](/ko/headless)를 통해 사용 가능하며 Desktop에서는 사용할 수 없습니다.

710* **Terminal-dialog commands**: `/permissions`, `/config`, `/agents`, `/doctor`와 같이 터미널에서 대화형 패널을 여는 기본 제공 명령은 Code 탭에서 사용할 수 없으며 `isn't available in this environment`로 응답합니다. [설정 파일](/ko/settings)을 직접 편집하여 권한 규칙 및 구성을 관리하거나 독립 실행형 CLI에서 명령을 실행합니다.

710 711 

711## 문제 해결712## 문제 해결

712 713 

138 </Step>138 </Step>

139 139 

140 <Step title="플러그인 설치">140 <Step title="플러그인 설치">

141 플러그인을 선택하여 세부 정보를 보고 설치 범위를 선택합니다:141 플러그인을 선택하여 세부 정보를 봅니다. {/* min-version: 2.1.143 */}Claude Code v2.1.143 이상에서는 세부 정보 창에 **Context cost** 예상치가 포함되어 있으므로 설치하기 전에 플러그인이 매 턴마다 [컨텍스트 윈도우](/ko/features-overview#understand-context-costs)에 추가할 토큰 수를 확인할 수 있습니다.

142 

143 설치 범위를 선택합니다:

142 144 

143 * **User scope**: 모든 프로젝트에서 자신을 위해 설치145 * **User scope**: 모든 프로젝트에서 자신을 위해 설치

144 * **Project scope**: 이 저장소의 모든 협력자를 위해 설치146 * **Project scope**: 이 저장소의 모든 협력자를 위해 설치

100| `CLAUDE_CODE_ENABLE_FEEDBACK_SURVEY_FOR_OTEL` | Anthropic 바운드 비필수 트래픽이 차단될 때 "Claude가 어떻게 하고 있나요?" 세션 품질 설문조사를 자신의 [OpenTelemetry 수집기](/ko/monitoring-usage)로 라우팅하려면 `1`로 설정합니다. 설문조사 등급은 구성된 수집기에 OTEL 이벤트로만 내보내집니다. 이 모드에서는 설문조사 데이터가 Anthropic으로 전송되지 않습니다. `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC`, `DISABLE_TELEMETRY`, 또는 `DO_NOT_TRACK`이 설정되었을 때 적용되며, 그렇지 않으면 효과가 없습니다. `CLAUDE_CODE_DISABLE_FEEDBACK_SURVEY` 및 조직 제품 피드백 정책이 우선합니다. |100| `CLAUDE_CODE_ENABLE_FEEDBACK_SURVEY_FOR_OTEL` | Anthropic 바운드 비필수 트래픽이 차단될 때 "Claude가 어떻게 하고 있나요?" 세션 품질 설문조사를 자신의 [OpenTelemetry 수집기](/ko/monitoring-usage)로 라우팅하려면 `1`로 설정합니다. 설문조사 등급은 구성된 수집기에 OTEL 이벤트로만 내보내집니다. 이 모드에서는 설문조사 데이터가 Anthropic으로 전송되지 않습니다. `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC`, `DISABLE_TELEMETRY`, 또는 `DO_NOT_TRACK`이 설정되었을 때 적용되며, 그렇지 않으면 효과가 없습니다. `CLAUDE_CODE_DISABLE_FEEDBACK_SURVEY` 및 조직 제품 피드백 정책이 우선합니다. |

101| `CLAUDE_CODE_ENABLE_FINE_GRAINED_TOOL_STREAMING` | 도구 호출 입력이 Claude가 생성할 때 API에서 스트리밍되는지 여부를 제어합니다. 이 없으면 파일 쓰기와 같은 큰 도구 입력이 Claude가 생성을 완료한 후에만 도착하므로 중단된 것처럼 보일 수 있습니다. Anthropic API에 대해 기본적으로 활성화됩니다. Bedrock 및 Vertex에서는 배포된 컨테이너가 지원하는 모델별로 활성화됩니다. 옵트아웃하려면 `0`으로 설정합니다. `ANTHROPIC_BASE_URL`, `ANTHROPIC_VERTEX_BASE_URL` 또는 `ANTHROPIC_BEDROCK_BASE_URL`을 통해 프록시로 라우팅할 때 강제로 활성화하려면 `1`로 설정합니다. Foundry 및 [게이트웨이](/ko/llm-gateway) 연결에는 기본적으로 꺼져 있습니다. |101| `CLAUDE_CODE_ENABLE_FINE_GRAINED_TOOL_STREAMING` | 도구 호출 입력이 Claude가 생성할 때 API에서 스트리밍되는지 여부를 제어합니다. 이 없으면 파일 쓰기와 같은 큰 도구 입력이 Claude가 생성을 완료한 후에만 도착하므로 중단된 것처럼 보일 수 있습니다. Anthropic API에 대해 기본적으로 활성화됩니다. Bedrock 및 Vertex에서는 배포된 컨테이너가 지원하는 모델별로 활성화됩니다. 옵트아웃하려면 `0`으로 설정합니다. `ANTHROPIC_BASE_URL`, `ANTHROPIC_VERTEX_BASE_URL` 또는 `ANTHROPIC_BEDROCK_BASE_URL`을 통해 프록시로 라우팅할 때 강제로 활성화하려면 `1`로 설정합니다. Foundry 및 [게이트웨이](/ko/llm-gateway) 연결에는 기본적으로 꺼져 있습니다. |

102| `CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY` | `ANTHROPIC_BASE_URL`이 LiteLLM, Kong 또는 내부 프록시와 같은 Anthropic 호환 게이트웨이를 가리킬 때 게이트웨이의 `/v1/models` 엔드포인트에서 `/model` 선택기를 채우려면 `1`로 설정합니다. 공유 API 키로 지원되는 게이트웨이는 그렇지 않으면 모든 사용자에게 키가 액세스할 수 있는 모든 모델을 표시하므로 기본적으로 꺼져 있습니다. 검색된 모델은 여전히 [`availableModels`](/ko/settings#available-settings) 허용 목록으로 필터링됩니다. |102| `CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY` | `ANTHROPIC_BASE_URL`이 LiteLLM, Kong 또는 내부 프록시와 같은 Anthropic 호환 게이트웨이를 가리킬 때 게이트웨이의 `/v1/models` 엔드포인트에서 `/model` 선택기를 채우려면 `1`로 설정합니다. 공유 API 키로 지원되는 게이트웨이는 그렇지 않으면 모든 사용자에게 키가 액세스할 수 있는 모든 모델을 표시하므로 기본적으로 꺼져 있습니다. 검색된 모델은 여전히 [`availableModels`](/ko/settings#available-settings) 허용 목록으로 필터링됩니다. |

103| `CLAUDE_CODE_ENABLE_OPUS_4_7_FAST_MODE` | [빠른 모드](/ko/fast-mode)를 Claude Opus 4.7에서 실행하려면 `1`로 설정합니다. Opus 4.6 대신 변수를 설정하면 `/fast`가 Opus 4.7로 전환됩니다. 변수가 없으면 `/fast`는 계속 Opus 4.6을 사용합니다. |103| `CLAUDE_CODE_ENABLE_OPUS_4_7_FAST_MODE` | v2.1.142에서 제거됨. [빠른 모드](/ko/fast-mode)는 기본적으로 Opus 4.7입니다. Opus 4.6을 유지하려면 `CLAUDE_CODE_OPUS_4_6_FAST_MODE_OVERRIDE=1`을 설정합니다. |

104| `CLAUDE_CODE_ENABLE_PROMPT_SUGGESTION` | 프롬프트 제안을 비활성화하려면 `false`로 설정합니다(`/config`의 "프롬프트 제안" 토글). 이는 Claude가 응답한 후 프롬프트 입력에 나타나는 회색으로 표시된 예측입니다. [프롬프트 제안](/ko/interactive-mode#prompt-suggestions) 참조 |104| `CLAUDE_CODE_ENABLE_PROMPT_SUGGESTION` | 프롬프트 제안을 비활성화하려면 `false`로 설정합니다(`/config`의 "프롬프트 제안" 토글). 이는 Claude가 응답한 후 프롬프트 입력에 나타나는 회색으로 표시된 예측입니다. [프롬프트 제안](/ko/interactive-mode#prompt-suggestions) 참조 |

105| `CLAUDE_CODE_ENABLE_TASKS` | 비대화형 모드(`-p` 플래그)에서 작업 추적 시스템을 활성화하려면 `1`로 설정합니다. 작업은 대화형 모드에서 기본적으로 켜져 있습니다. [작업 목록](/ko/interactive-mode#task-list) 참조 |105| `CLAUDE_CODE_ENABLE_TASKS` | 세션이 구조화된 Task 도구(`TaskCreate`, `TaskUpdate`, `TaskGet`, `TaskList`) 또는 레거시 `TodoWrite` 도구를 사용하는지 제어합니다. Claude Code v2.1.142부터 Task 도구는 모든 모드에서 기본값입니다. `TodoWrite`로 되돌리려면 `0`으로 설정합니다. [작업 목록](/ko/interactive-mode#task-list) 및 [Task 도구로 마이그레이션](/ko/agent-sdk/todo-tracking#migrate-to-task-tools) 참조 |

106| `CLAUDE_CODE_ENABLE_TELEMETRY` | 메트릭 및 로깅을 위한 OpenTelemetry 데이터 수집을 활성화하려면 `1`로 설정합니다. OTel 내보내기를 구성하기 전에 필수입니다. [모니터링](/ko/monitoring-usage) 참조 |106| `CLAUDE_CODE_ENABLE_TELEMETRY` | 메트릭 및 로깅을 위한 OpenTelemetry 데이터 수집을 활성화하려면 `1`로 설정합니다. OTel 내보내기를 구성하기 전에 필수입니다. [모니터링](/ko/monitoring-usage) 참조 |

107| `CLAUDE_CODE_EXIT_AFTER_STOP_DELAY` | 쿼리 루프가 유휴 상태가 된 후 자동으로 종료되기 전에 대기할 시간(밀리초). SDK 모드를 사용하는 자동화된 워크플로우 및 스크립트에 유용합니다. |107| `CLAUDE_CODE_EXIT_AFTER_STOP_DELAY` | 쿼리 루프가 유휴 상태가 된 후 자동으로 종료되기 전에 대기할 시간(밀리초). SDK 모드를 사용하는 자동화된 워크플로우 및 스크립트에 유용합니다. |

108| `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS` | [에이전트 팀](/ko/agent-teams)을 활성화하려면 `1`로 설정합니다. 에이전트 팀은 실험적이며 기본적으로 비활성화됩니다. |108| `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS` | [에이전트 팀](/ko/agent-teams)을 활성화하려면 `1`로 설정합니다. 에이전트 팀은 실험적이며 기본적으로 비활성화됩니다. |

130| `CLAUDE_CODE_OAUTH_REFRESH_TOKEN` | Claude.ai 인증용 OAuth 새로 고침 토큰입니다. 설정하면 `claude auth login`이 브라우저를 열지 않고 이 토큰을 직접 교환합니다. `CLAUDE_CODE_OAUTH_SCOPES`가 필요합니다. 자동화된 환경에서 인증을 프로비저닝하는 데 유용합니다. |130| `CLAUDE_CODE_OAUTH_REFRESH_TOKEN` | Claude.ai 인증용 OAuth 새로 고침 토큰입니다. 설정하면 `claude auth login`이 브라우저를 열지 않고 이 토큰을 직접 교환합니다. `CLAUDE_CODE_OAUTH_SCOPES`가 필요합니다. 자동화된 환경에서 인증을 프로비저닝하는 데 유용합니다. |

131| `CLAUDE_CODE_OAUTH_SCOPES` | 새로 고침 토큰이 발급된 공백으로 구분된 OAuth 범위(예: `"user:profile user:inference user:sessions:claude_code"`). `CLAUDE_CODE_OAUTH_REFRESH_TOKEN`이 설정되면 필수입니다. |131| `CLAUDE_CODE_OAUTH_SCOPES` | 새로 고침 토큰이 발급된 공백으로 구분된 OAuth 범위(예: `"user:profile user:inference user:sessions:claude_code"`). `CLAUDE_CODE_OAUTH_REFRESH_TOKEN`이 설정되면 필수입니다. |

132| `CLAUDE_CODE_OAUTH_TOKEN` | Claude.ai 인증용 OAuth 액세스 토큰입니다. `/login`의 대안으로 SDK 및 자동화된 환경에 사용됩니다. 키체인 저장 자격 증명보다 우선합니다. [`claude setup-token`](/ko/authentication#generate-a-long-lived-token)으로 생성합니다. |132| `CLAUDE_CODE_OAUTH_TOKEN` | Claude.ai 인증용 OAuth 액세스 토큰입니다. `/login`의 대안으로 SDK 및 자동화된 환경에 사용됩니다. 키체인 저장 자격 증명보다 우선합니다. [`claude setup-token`](/ko/authentication#generate-a-long-lived-token)으로 생성합니다. |

133| `CLAUDE_CODE_OPUS_4_6_FAST_MODE_OVERRIDE` | [빠른 모드](/ko/fast-mode)를 Claude Opus 4.6에서 유지하려면 `1`로 설정합니다. `CLAUDE_CODE_ENABLE_OPUS_4_7_FAST_MODE`보다 우선하므로, 기본값이 어떻게 변경되든 Opus 4.6을 고정해야 하는 경우 이를 설정합니다. |133| `CLAUDE_CODE_OPUS_4_6_FAST_MODE_OVERRIDE` | [빠른 모드](/ko/fast-mode)를 Claude Opus 4.6에 고정하려면 `1`로 설정합니다. 변수가 설정되면 `/fast`는 Opus 4.6에서 실행됩니다. 없으면 `/fast`는 Opus 4.7에서 실행됩니다. |

134| `CLAUDE_CODE_OTEL_FLUSH_TIMEOUT_MS` | 보류 중인 OpenTelemetry 스팬을 플러시하는 타임아웃(밀리초)(기본값: 5000). [모니터링](/ko/monitoring-usage) 참조 |134| `CLAUDE_CODE_OTEL_FLUSH_TIMEOUT_MS` | 보류 중인 OpenTelemetry 스팬을 플러시하는 타임아웃(밀리초)(기본값: 5000). [모니터링](/ko/monitoring-usage) 참조 |

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

136| `CLAUDE_CODE_OTEL_SHUTDOWN_TIMEOUT_MS` | 종료 시 OpenTelemetry 내보내기가 완료되는 타임아웃(밀리초)(기본값: 2000). 메트릭이 종료 시 삭제되면 증가시킵니다. [모니터링](/ko/monitoring-usage) 참조 |136| `CLAUDE_CODE_OTEL_SHUTDOWN_TIMEOUT_MS` | 종료 시 OpenTelemetry 내보내기가 완료되는 타임아웃(밀리초)(기본값: 2000). 메트릭이 종료 시 삭제되면 증가시킵니다. [모니터링](/ko/monitoring-usage) 참조 |

141| `CLAUDE_CODE_PLUGIN_KEEP_MARKETPLACE_ON_FAILURE` | `git pull`이 실패할 때 기존 마켓플레이스 캐시를 유지하려면 `1`로 설정합니다. 다시 복제하면 같은 방식으로 실패할 오프라인 또는 에어갭 환경에서 유용합니다. [오프라인 환경에서 마켓플레이스 업데이트 실패](/ko/plugin-marketplaces#marketplace-updates-fail-in-offline-environments) 참조 |141| `CLAUDE_CODE_PLUGIN_KEEP_MARKETPLACE_ON_FAILURE` | `git pull`이 실패할 때 기존 마켓플레이스 캐시를 유지하려면 `1`로 설정합니다. 다시 복제하면 같은 방식으로 실패할 오프라인 또는 에어갭 환경에서 유용합니다. [오프라인 환경에서 마켓플레이스 업데이트 실패](/ko/plugin-marketplaces#marketplace-updates-fail-in-offline-environments) 참조 |

142| `CLAUDE_CODE_PLUGIN_PREFER_HTTPS` | GitHub `owner/repo` 플러그인 소스를 SSH 대신 HTTPS를 통해 복제하려면 `1`로 설정합니다. CI 러너, 컨테이너 또는 `github.com`에 대해 구성된 SSH 키가 없는 모든 환경에서 유용합니다. |142| `CLAUDE_CODE_PLUGIN_PREFER_HTTPS` | GitHub `owner/repo` 플러그인 소스를 SSH 대신 HTTPS를 통해 복제하려면 `1`로 설정합니다. CI 러너, 컨테이너 또는 `github.com`에 대해 구성된 SSH 키가 없는 모든 환경에서 유용합니다. |

143| `CLAUDE_CODE_PLUGIN_SEED_DIR` | 하나 이상의 읽기 전용 플러그인 시드 디렉토리의 경로이며, Unix에서는 `:`로, Windows에서는 `;`로 구분됩니다. 이를 사용하여 사전 채워진 플러그인 디렉토리를 컨테이너 이미지에 번들로 제공합니다. Claude Code는 시작 시 이러한 디렉토리에서 마켓플레이스를 등록하고 다시 복제하지 않고 사전 캐시된 플러그인을 사용합니다. [컨테이너용 플러그인 사전 채우기](/ko/plugin-marketplaces#pre-populate-plugins-for-containers) 참조 |143| `CLAUDE_CODE_PLUGIN_SEED_DIR` | 하나 이상의 읽기 전용 플러그인 시드 디렉토리의 경로이며, Unix에서는 `:`로, Windows에서는 `;`로 구분됩니다. 이를 사용하여 사전 채워진 플러그인 디렉토리를 컨테이너 이미지에 번들로 제공합니다. Claude Code는 시작 시 이러한 디렉토리에서 마켓플레이스를 등록하고 다시 복제하지 않고 사전 캐시된 플러그인을 사용합니다. [컨테이너용 플러그인 사전 채우기](/ko/plugin-marketplaces#pre-populate-plugins-for-containers) 참조 |

144| `CLAUDE_CODE_POWERSHELL_RESPECT_EXECUTION_POLICY` | Claude Code가 PowerShell을 생성할 때 `-ExecutionPolicy Bypass`를 전달하지 않으려면 `1`로 설정합니다. 도구 호출, 훅, 상태 줄 명령의 경우 대신 머신의 효과적인 실행 정책을 존중합니다. 기본적으로 Claude Code는 프로세스 범위에서 실행 정책을 우회하므로 `.ps1` 스크립트 및 모듈 가져오기가 기본 제한 Windows 설치에서 작동합니다. 프로세스 범위 우회는 이 설정과 관계없이 Group Policy `MachinePolicy` 또는 `UserPolicy`를 재정의하지 않습니다. |

144| `CLAUDE_CODE_PROVIDER_MANAGED_BY_HOST` | Claude Code를 포함하고 대신 모델 공급자 라우팅을 관리하는 호스트 플랫폼에서 설정합니다. 설정하면 설정 파일의 `CLAUDE_CODE_USE_BEDROCK`, `ANTHROPIC_BASE_URL`, `ANTHROPIC_API_KEY`와 같은 공급자 선택, 엔드포인트, 인증 변수가 무시되므로 사용자 설정이 호스트의 라우팅을 재정의할 수 없습니다. Bedrock, Vertex, Foundry에 대한 자동 원격 분석 옵트아웃도 건너뛰므로 원격 분석은 표준 `DISABLE_TELEMETRY` 옵트아웃을 따릅니다. [API 공급자별 기본 동작](/ko/data-usage#default-behaviors-by-api-provider) 참조 |145| `CLAUDE_CODE_PROVIDER_MANAGED_BY_HOST` | Claude Code를 포함하고 대신 모델 공급자 라우팅을 관리하는 호스트 플랫폼에서 설정합니다. 설정하면 설정 파일의 `CLAUDE_CODE_USE_BEDROCK`, `ANTHROPIC_BASE_URL`, `ANTHROPIC_API_KEY`와 같은 공급자 선택, 엔드포인트, 인증 변수가 무시되므로 사용자 설정이 호스트의 라우팅을 재정의할 수 없습니다. Bedrock, Vertex, Foundry에 대한 자동 원격 분석 옵트아웃도 건너뛰므로 원격 분석은 표준 `DISABLE_TELEMETRY` 옵트아웃을 따릅니다. [API 공급자별 기본 동작](/ko/data-usage#default-behaviors-by-api-provider) 참조 |

145| `CLAUDE_CODE_PROXY_RESOLVES_HOSTS` | 호출자 대신 프록시가 DNS 해석을 수행하도록 허용하려면 `1`로 설정합니다. 프록시가 호스트명 해석을 처리해야 하는 환경에 대해 옵트인합니다. |146| `CLAUDE_CODE_PROXY_RESOLVES_HOSTS` | 호출자 대신 프록시가 DNS 해석을 수행하도록 허용하려면 `1`로 설정합니다. 프록시가 호스트명 해석을 처리해야 하는 환경에 대해 옵트인합니다. |

146| `CLAUDE_CODE_REMOTE` | Claude Code가 [클라우드 세션](/ko/claude-code-on-the-web)으로 실행 중일 때 자동으로 `true`로 설정됩니다. 훅 또는 설정 스크립트에서 이를 읽어 클라우드 환경에 있는지 감지합니다. |147| `CLAUDE_CODE_REMOTE` | Claude Code가 [클라우드 세션](/ko/claude-code-on-the-web)으로 실행 중일 때 자동으로 `true`로 설정됩니다. 훅 또는 설정 스크립트에서 이를 읽어 클라우드 환경에 있는지 감지합니다. |

153| `CLAUDE_CODE_SESSION_ID` | Bash 및 PowerShell 도구 subprocess에서 현재 세션 ID로 자동으로 설정됩니다. [훅](/ko/hooks)에 전달된 `session_id` 필드와 일치합니다. `/clear`에서 업데이트됩니다. 스크립트 및 외부 도구를 Claude Code 세션과 연관시키는 데 사용합니다. |154| `CLAUDE_CODE_SESSION_ID` | Bash 및 PowerShell 도구 subprocess에서 현재 세션 ID로 자동으로 설정됩니다. [훅](/ko/hooks)에 전달된 `session_id` 필드와 일치합니다. `/clear`에서 업데이트됩니다. 스크립트 및 외부 도구를 Claude Code 세션과 연관시키는 데 사용합니다. |

154| `CLAUDE_CODE_SHELL` | 자동 셸 감지를 재정의합니다. 로그인 셸이 선호하는 작업 셸과 다를 때 유용합니다(예: `bash` vs `zsh`). |155| `CLAUDE_CODE_SHELL` | 자동 셸 감지를 재정의합니다. 로그인 셸이 선호하는 작업 셸과 다를 때 유용합니다(예: `bash` vs `zsh`). |

155| `CLAUDE_CODE_SHELL_PREFIX` | Claude Code가 생성하는 모든 셸 명령을 래핑할 명령 접두사: Bash 도구 호출, [훅](/ko/hooks) 명령, stdio [MCP 서버](/ko/mcp) 시작 명령. 로깅 또는 감사에 유용합니다. 예: `/path/to/logger.sh`를 설정하면 각 명령을 `/path/to/logger.sh <command>`로 실행합니다. |156| `CLAUDE_CODE_SHELL_PREFIX` | Claude Code가 생성하는 모든 셸 명령을 래핑할 명령 접두사: Bash 도구 호출, [훅](/ko/hooks) 명령, stdio [MCP 서버](/ko/mcp) 시작 명령. 로깅 또는 감사에 유용합니다. 예: `/path/to/logger.sh`를 설정하면 각 명령을 `/path/to/logger.sh <command>`로 실행합니다. |

156| `CLAUDE_CODE_SIMPLE` | 최소 시스템 프롬프트 및 Bash, 파일 읽기, 파일 편집 도구만으로 실행하려면 `1`로 설정합니다. `--mcp-config`의 MCP 도구는 계속 사용 가능합니다. 훅, skill, 플러그인, MCP 서버, 자동 메모리, CLAUDE.md의 자동 검색을 비활성화합니다. [`--bare`](/ko/headless#start-faster-with-bare-mode) CLI 플래그가 이를 설정합니다. |157| `CLAUDE_CODE_SIMPLE` | 최소 시스템 프롬프트 및 Bash, 파일 읽기, 파일 편집 도구만으로 실행하려면 `1`로 설정합니다. `--mcp-config`의 MCP 도구는 계속 사용 가능합니다. 훅, skill, 플러그인, MCP 서버, 자동 메모리, CLAUDE.md의 자동 검색을 비활성화합니다. OAuth 토큰 및 키체인 자격 증명은 읽지 않으므로 Anthropic 인증은 `ANTHROPIC_API_KEY` 또는 `--settings`의 `apiKeyHelper`에서 와야 합니다. [`--bare`](/ko/headless#start-faster-with-bare-mode) 전달과 동일합니다. |

157| `CLAUDE_CODE_SIMPLE_SYSTEM_PROMPT` | 모든 모델에서 더 짧은 시스템 프롬프트 및 축소된 도구 설명을 사용하려면 `1`로 설정합니다. `0`, `false`, `no`, 또는 `off`로 설정하여 실험 또는 서버 구성이 그렇지 않으면 활성화할 때에도 옵트아웃합니다. 전체 도구 세트, 훅, MCP 서버, CLAUDE.md 검색은 계속 활성화됩니다. |158| `CLAUDE_CODE_SIMPLE_SYSTEM_PROMPT` | 모든 모델에서 더 짧은 시스템 프롬프트 및 축소된 도구 설명을 사용하려면 `1`로 설정합니다. `0`, `false`, `no`, 또는 `off`로 설정하여 실험 또는 서버 구성이 그렇지 않으면 활성화할 때에도 옵트아웃합니다. 전체 도구 세트, 훅, MCP 서버, CLAUDE.md 검색은 계속 활성화됩니다. |

158| `CLAUDE_CODE_SKIP_ANTHROPIC_AWS_AUTH` | [Claude Platform on AWS](/ko/claude-platform-on-aws)에 대한 클라이언트 측 인증을 건너뜁니다. 게이트웨이가 요청에 자체 서명하는 경우 |159| `CLAUDE_CODE_SKIP_ANTHROPIC_AWS_AUTH` | [Claude Platform on AWS](/ko/claude-platform-on-aws)에 대한 클라이언트 측 인증을 건너뜁니다. 게이트웨이가 요청에 자체 서명하는 경우 |

159| `CLAUDE_CODE_SKIP_BEDROCK_AUTH` | Bedrock에 대한 AWS 인증을 건너뜁니다(예: LLM 게이트웨이를 사용할 때). |160| `CLAUDE_CODE_SKIP_BEDROCK_AUTH` | Bedrock에 대한 AWS 인증을 건너뜁니다(예: LLM 게이트웨이를 사용할 때). |

161| `CLAUDE_CODE_SKIP_MANTLE_AUTH` | Bedrock Mantle에 대한 AWS 인증을 건너뜁니다(예: LLM 게이트웨이를 사용할 때). |162| `CLAUDE_CODE_SKIP_MANTLE_AUTH` | Bedrock Mantle에 대한 AWS 인증을 건너뜁니다(예: LLM 게이트웨이를 사용할 때). |

162| `CLAUDE_CODE_SKIP_PROMPT_HISTORY` | 프롬프트 기록 및 세션 트랜스크립트를 디스크에 쓰지 않으려면 `1`로 설정합니다. 이 변수로 시작된 세션은 `--resume`, `--continue` 또는 위쪽 화살표 기록에 나타나지 않습니다. 임시 스크립트 세션에 유용합니다. |163| `CLAUDE_CODE_SKIP_PROMPT_HISTORY` | 프롬프트 기록 및 세션 트랜스크립트를 디스크에 쓰지 않으려면 `1`로 설정합니다. 이 변수로 시작된 세션은 `--resume`, `--continue` 또는 위쪽 화살표 기록에 나타나지 않습니다. 임시 스크립트 세션에 유용합니다. |

163| `CLAUDE_CODE_SKIP_VERTEX_AUTH` | Vertex에 대한 Google 인증을 건너뜁니다(예: LLM 게이트웨이를 사용할 때). |164| `CLAUDE_CODE_SKIP_VERTEX_AUTH` | Vertex에 대한 Google 인증을 건너뜁니다(예: LLM 게이트웨이를 사용할 때). |

165| `CLAUDE_CODE_STOP_HOOK_BLOCK_CAP` | [Stop](/ko/hooks#stop) 또는 [SubagentStop](/ko/hooks#subagentstop) 훅이 턴 종료를 차단할 수 있는 최대 연속 횟수입니다(기본값: 8). Claude Code가 턴을 어쨌든 종료하기 전입니다. `0`으로 설정하여 제한을 비활성화합니다. 훅이 해결하기 위해 더 많은 반복이 필요하면 이를 올립니다. |

164| `CLAUDE_CODE_SUBAGENT_MODEL` | [모델 구성](/ko/model-config) 참조 |166| `CLAUDE_CODE_SUBAGENT_MODEL` | [모델 구성](/ko/model-config) 참조 |

165| `CLAUDE_CODE_SUBPROCESS_ENV_SCRUB` | Anthropic 및 클라우드 공급자 자격 증명을 subprocess 환경(Bash 도구, 훅, MCP stdio 서버)에서 제거하려면 `1`로 설정합니다. 부모 Claude 프로세스는 API 호출을 위해 이러한 자격 증명을 유지하지만 자식 프로세스는 이를 읽을 수 없으므로 셸 확장을 통해 비밀을 유출하려는 프롬프트 주입 공격에 대한 노출을 줄입니다. Linux에서는 Bash subprocess를 격리된 PID 네임스페이스에서도 실행하므로 `/proc`을 통해 호스트 프로세스 환경을 읽을 수 없습니다. 부작용으로 `ps`, `pgrep`, `kill`은 호스트 프로세스를 보거나 신호할 수 없습니다. `allowed_non_write_users`가 구성되면 `claude-code-action`이 자동으로 이를 설정합니다. |167| `CLAUDE_CODE_SUBPROCESS_ENV_SCRUB` | Anthropic 및 클라우드 공급자 자격 증명을 subprocess 환경(Bash 도구, 훅, MCP stdio 서버)에서 제거하려면 `1`로 설정합니다. 부모 Claude 프로세스는 API 호출을 위해 이러한 자격 증명을 유지하지만 자식 프로세스는 이를 읽을 수 없으므로 셸 확장을 통해 비밀을 유출하려는 프롬프트 주입 공격에 대한 노출을 줄입니다. Linux에서는 Bash subprocess를 격리된 PID 네임스페이스에서도 실행하므로 `/proc`을 통해 호스트 프로세스 환경을 읽을 수 없습니다. 부작용으로 `ps`, `pgrep`, `kill`은 호스트 프로세스를 보거나 신호할 수 없습니다. `allowed_non_write_users`가 구성되면 `claude-code-action`이 자동으로 이를 설정합니다. |

166| `CLAUDE_CODE_SYNC_PLUGIN_INSTALL` | 비대화형 모드(`-p` 플래그)에서 첫 번째 쿼리 전에 플러그인 설치가 완료될 때까지 대기하려면 `1`로 설정합니다. 이 없으면 플러그인이 백그라운드에서 설치되고 첫 번째 턴에서 사용하지 못할 수 있습니다. `CLAUDE_CODE_SYNC_PLUGIN_INSTALL_TIMEOUT_MS`와 결합하여 대기를 제한합니다. |168| `CLAUDE_CODE_SYNC_PLUGIN_INSTALL` | 비대화형 모드(`-p` 플래그)에서 첫 번째 쿼리 전에 플러그인 설치가 완료될 때까지 대기하려면 `1`로 설정합니다. 이 없으면 플러그인이 백그라운드에서 설치되고 첫 번째 턴에서 사용하지 못할 수 있습니다. `CLAUDE_CODE_SYNC_PLUGIN_INSTALL_TIMEOUT_MS`와 결합하여 대기를 제한합니다. |

180| `CLAUDE_CONFIG_DIR` | 구성 디렉토리를 재정의합니다(기본값: `~/.claude`). 모든 설정, 자격 증명, 세션 기록 및 플러그인이 이 경로 아래에 저장됩니다. 여러 계정을 나란히 실행하는 데 유용합니다: 예를 들어 `alias claude-work='CLAUDE_CONFIG_DIR=~/.claude-work claude'` |182| `CLAUDE_CONFIG_DIR` | 구성 디렉토리를 재정의합니다(기본값: `~/.claude`). 모든 설정, 자격 증명, 세션 기록 및 플러그인이 이 경로 아래에 저장됩니다. 여러 계정을 나란히 실행하는 데 유용합니다: 예를 들어 `alias claude-work='CLAUDE_CONFIG_DIR=~/.claude-work claude'` |

181| `CLAUDE_EFFORT` | Bash 도구 subprocess 및 훅 명령에서 활성 [노력 수준](/ko/model-config#adjust-effort-level)으로 자동으로 설정됩니다: `low`, `medium`, `high`, `xhigh`, 또는 `max`. [훅](/ko/hooks)에 전달된 `effort.level` 필드와 일치합니다. 현재 모델이 노력 매개변수를 지원할 때만 설정됩니다. |183| `CLAUDE_EFFORT` | Bash 도구 subprocess 및 훅 명령에서 활성 [노력 수준](/ko/model-config#adjust-effort-level)으로 자동으로 설정됩니다: `low`, `medium`, `high`, `xhigh`, 또는 `max`. [훅](/ko/hooks)에 전달된 `effort.level` 필드와 일치합니다. 현재 모델이 노력 매개변수를 지원할 때만 설정됩니다. |

182| `CLAUDE_ENABLE_BYTE_WATCHDOG` | 바이트 수준 스트리밍 유휴 감시견을 강제로 활성화하려면 `1`로 설정하거나, 강제로 비활성화하려면 `0`으로 설정합니다. 설정하지 않으면 감시견은 Anthropic API 연결에 대해 기본적으로 활성화됩니다. 바이트 감시견은 `CLAUDE_STREAM_IDLE_TIMEOUT_MS`로 설정된 기간 동안 와이어에 바이트가 도착하지 않으면 연결을 중단합니다. 최소 5분이며 이벤트 수준 감시견과 독립적입니다. |184| `CLAUDE_ENABLE_BYTE_WATCHDOG` | 바이트 수준 스트리밍 유휴 감시견을 강제로 활성화하려면 `1`로 설정하거나, 강제로 비활성화하려면 `0`으로 설정합니다. 설정하지 않으면 감시견은 Anthropic API 연결에 대해 기본적으로 활성화됩니다. 바이트 감시견은 `CLAUDE_STREAM_IDLE_TIMEOUT_MS`로 설정된 기간 동안 와이어에 바이트가 도착하지 않으면 연결을 중단합니다. 최소 5분이며 이벤트 수준 감시견과 독립적입니다. |

183| `CLAUDE_ENABLE_STREAM_WATCHDOG` | 이벤트 수준 스트리밍 유휴 감시견을 활성화하려면 `1`로 설정합니다. 기본적으로 꺼져 있습니다. Bedrock, Vertex, Foundry의 경우 이것이 유일한 유휴 감시견입니다. `CLAUDE_STREAM_IDLE_TIMEOUT_MS`로 타임아웃을 구성합니다. |185| `CLAUDE_ENABLE_BYTE_WATCHDOG_BEDROCK` | Amazon Bedrock `vnd.amazon.eventstream` 응답에서 바이트 수준 스트리밍 유휴 감시견을 활성화하려면 `1`로 설정합니다. 기본적으로 꺼져 있습니다. `CLAUDE_STREAM_IDLE_TIMEOUT_MS`로 타임아웃을 구성합니다. |

186| `CLAUDE_ENABLE_STREAM_WATCHDOG` | 이벤트 수준 스트리밍 유휴 감시견을 활성화하려면 `1`로 설정합니다. 기본적으로 꺼져 있습니다. 모든 공급자에 적용됩니다(Bedrock 포함). Vertex 및 Foundry의 경우 이것이 유일한 유휴 감시견입니다. Bedrock에서는 `CLAUDE_ENABLE_BYTE_WATCHDOG_BEDROCK`으로 독립적인 바이트 수준 감시견을 활성화할 수도 있습니다. 둘 다 설정하면 함께 실행됩니다. `CLAUDE_STREAM_IDLE_TIMEOUT_MS`로 타임아웃을 구성합니다. |

184| `CLAUDE_ENV_FILE` | Claude Code가 각 Bash 명령 전에 같은 셸 프로세스에서 실행하는 셸 스크립트의 경로이므로 파일의 내보내기가 명령에 표시됩니다. virtualenv 또는 conda 활성화를 명령 간에 유지하는 데 사용합니다. [SessionStart](/ko/hooks#persist-environment-variables), [Setup](/ko/hooks#setup), [CwdChanged](/ko/hooks#cwdchanged), [FileChanged](/ko/hooks#filechanged) 훅으로도 동적으로 채워집니다. |187| `CLAUDE_ENV_FILE` | Claude Code가 각 Bash 명령 전에 같은 셸 프로세스에서 실행하는 셸 스크립트의 경로이므로 파일의 내보내기가 명령에 표시됩니다. virtualenv 또는 conda 활성화를 명령 간에 유지하는 데 사용합니다. [SessionStart](/ko/hooks#persist-environment-variables), [Setup](/ko/hooks#setup), [CwdChanged](/ko/hooks#cwdchanged), [FileChanged](/ko/hooks#filechanged) 훅으로도 동적으로 채워집니다. |

185| `CLAUDE_REMOTE_CONTROL_SESSION_NAME_PREFIX` | 명시적 이름이 제공되지 않을 때 자동 생성된 [Remote Control](/ko/remote-control) 세션 이름의 접두사입니다. 기본값은 머신의 호스트명이며, `myhost-graceful-unicorn`과 같은 이름을 생성합니다. `--remote-control-session-name-prefix` CLI 플래그는 단일 호출에 대해 동일한 값을 설정합니다. |188| `CLAUDE_REMOTE_CONTROL_SESSION_NAME_PREFIX` | 명시적 이름이 제공되지 않을 때 자동 생성된 [Remote Control](/ko/remote-control) 세션 이름의 접두사입니다. 기본값은 머신의 호스트명이며, `myhost-graceful-unicorn`과 같은 이름을 생성합니다. `--remote-control-session-name-prefix` CLI 플래그는 단일 호출에 대해 동일한 값을 설정합니다. |

186| `CLAUDE_STREAM_IDLE_TIMEOUT_MS` | 스트리밍 유휴 감시견이 정체된 연결을 닫기 전의 타임아웃(밀리초). 바이트 수준 및 이벤트 수준 감시견 모두에 대해 기본값 및 최소 `300000`(5분). 낮은 값은 확장 사고 일시 중지 및 프록시 버퍼링을 흡수하도록 자동으로 제한됩니다. 타사 공급자의 경우 `CLAUDE_ENABLE_STREAM_WATCHDOG=1`이 필요합니다. |189| `CLAUDE_STREAM_IDLE_TIMEOUT_MS` | 스트리밍 유휴 감시견이 정체된 연결을 닫기 전의 타임아웃(밀리초). 바이트 수준 및 이벤트 수준 감시견 모두에 대해 기본값 및 최소 `300000`(5분). 낮은 값은 확장 사고 일시 중지 및 프록시 버퍼링을 흡수하도록 자동으로 제한됩니다. 타사 공급자의 경우 `CLAUDE_ENABLE_STREAM_WATCHDOG=1`이 필요합니다. Bedrock에서는 `CLAUDE_ENABLE_BYTE_WATCHDOG_BEDROCK=1`일 때도 적용됩니다. |

187| `DEBUG` | 디버그 모드를 활성화하려면 `1`로 설정합니다. [`--debug`](/ko/cli-reference#cli-flags)로 실행하는 것과 동일합니다. 디버그 로그는 `~/.claude/debug/<session-id>.txt`에 기록되거나 `CLAUDE_CODE_DEBUG_LOGS_DIR`로 설정된 경로에 기록됩니다. `1`, `true`, `yes`, `on`의 참 값만 디버그 모드를 활성화하므로 다른 도구에 대해 설정된 `DEBUG=express:*`와 같은 네임스페이스 패턴은 이를 트리거하지 않습니다. |190| `DEBUG` | 디버그 모드를 활성화하려면 `1`로 설정합니다. [`--debug`](/ko/cli-reference#cli-flags)로 실행하는 것과 동일합니다. 디버그 로그는 `~/.claude/debug/<session-id>.txt`에 기록되거나 `CLAUDE_CODE_DEBUG_LOGS_DIR`로 설정된 경로에 기록됩니다. `1`, `true`, `yes`, `on`의 참 값만 디버그 모드를 활성화하므로 다른 도구에 대해 설정된 `DEBUG=express:*`와 같은 네임스페이스 패턴은 이를 트리거하지 않습니다. |

188| `DISABLE_AUTOUPDATER` | 자동 업데이트를 비활성화하려면 `1`로 설정합니다. 수동 `claude update`는 계속 작동합니다. `DISABLE_UPDATES`를 사용하여 둘 다 차단합니다. |191| `DISABLE_AUTOUPDATER` | 자동 업데이트를 비활성화하려면 `1`로 설정합니다. 수동 `claude update`는 계속 작동합니다. `DISABLE_UPDATES`를 사용하여 둘 다 차단합니다. |

189| `DISABLE_AUTO_COMPACT` | 컨텍스트 제한에 접근할 때 자동 압축을 비활성화하려면 `1`로 설정합니다. 수동 `/compact` 명령은 계속 사용 가능합니다. 압축이 발생하는 시기를 명시적으로 제어하려는 경우 사용합니다. |192| `DISABLE_AUTO_COMPACT` | 컨텍스트 제한에 접근할 때 자동 압축을 비활성화하려면 `1`로 설정합니다. 수동 `/compact` 명령은 계속 사용 가능합니다. 압축이 발생하는 시기를 명시적으로 제어하려는 경우 사용합니다. |

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

192| `DISABLE_DOCTOR_COMMAND` | `/doctor` 명령을 숨기려면 `1`로 설정합니다. 사용자가 설치 진단을 실행하지 않아야 하는 관리형 배포에 유용합니다. |195| `DISABLE_DOCTOR_COMMAND` | `/doctor` 명령을 숨기려면 `1`로 설정합니다. 사용자가 설치 진단을 실행하지 않아야 하는 관리형 배포에 유용합니다. |

193| `DISABLE_ERROR_REPORTING` | Sentry 오류 보고를 거부하려면 `1`로 설정합니다. |196| `DISABLE_ERROR_REPORTING` | Sentry 오류 보고를 거부하려면 `1`로 설정합니다. |

194| `DISABLE_EXTRA_USAGE_COMMAND` | 사용자가 속도 제한을 초과하여 추가 사용량을 구매할 수 있는 `/extra-usage` 명령을 숨기려면 `1`로 설정합니다. |197| `DISABLE_EXTRA_USAGE_COMMAND` | 사용자가 속도 제한을 초과하여 추가 사용량을 구매할 수 있는 `/usage-credits` 명령을 숨기려면 `1`로 설정합니다. |

195| `DISABLE_FEEDBACK_COMMAND` | `/feedback` 명령을 비활성화하려면 `1`로 설정합니다. 이전 이름 `DISABLE_BUG_COMMAND`도 허용됩니다. |198| `DISABLE_FEEDBACK_COMMAND` | `/feedback` 명령을 비활성화하려면 `1`로 설정합니다. 이전 이름 `DISABLE_BUG_COMMAND`도 허용됩니다. |

196| `DISABLE_GROWTHBOOK` | GrowthBook 기능 플래그 가져오기를 비활성화하려면 `1`로 설정합니다. 모든 플래그에 대해 코드 기본값을 사용합니다. 원격 분석 이벤트 로깅은 `DISABLE_TELEMETRY`도 설정되지 않으면 계속됩니다. |199| `DISABLE_GROWTHBOOK` | GrowthBook 기능 플래그 가져오기를 비활성화하려면 `1`로 설정합니다. 모든 플래그에 대해 코드 기본값을 사용합니다. 원격 분석 이벤트 로깅은 `DISABLE_TELEMETRY`도 설정되지 않으면 계속됩니다. |

197| `DISABLE_INSTALLATION_CHECKS` | 설치 경고를 비활성화하려면 `1`로 설정합니다. 표준 설치의 문제를 숨길 수 있으므로 설치 위치를 수동으로 관리할 때만 사용합니다. |200| `DISABLE_INSTALLATION_CHECKS` | 설치 경고를 비활성화하려면 `1`로 설정합니다. 표준 설치의 문제를 숨길 수 있으므로 설치 위치를 수동으로 관리할 때만 사용합니다. |

221| `MAX_STRUCTURED_OUTPUT_RETRIES` | 비대화형 모드(`-p` 플래그)에서 모델의 응답이 [`--json-schema`](/ko/cli-reference#cli-flags)에 대한 유효성 검사에 실패할 때 재시도할 횟수입니다. 기본값은 5입니다. |224| `MAX_STRUCTURED_OUTPUT_RETRIES` | 비대화형 모드(`-p` 플래그)에서 모델의 응답이 [`--json-schema`](/ko/cli-reference#cli-flags)에 대한 유효성 검사에 실패할 때 재시도할 횟수입니다. 기본값은 5입니다. |

222| `MAX_THINKING_TOKENS` | [확장 사고](https://platform.claude.com/docs/en/build-with-claude/extended-thinking) 토큰 예산을 재정의합니다. 상한은 모델의 [최대 출력 토큰](https://platform.claude.com/docs/en/about-claude/models/overview#latest-models-comparison)에서 1을 뺀 값입니다. 사고를 완전히 비활성화하려면 `0`으로 설정합니다. [적응형 추론](/ko/model-config#adjust-effort-level)이 있는 모델에서는 `CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING`을 통해 적응형 추론이 비활성화되지 않으면 예산이 무시됩니다. |225| `MAX_THINKING_TOKENS` | [확장 사고](https://platform.claude.com/docs/en/build-with-claude/extended-thinking) 토큰 예산을 재정의합니다. 상한은 모델의 [최대 출력 토큰](https://platform.claude.com/docs/en/about-claude/models/overview#latest-models-comparison)에서 1을 뺀 값입니다. 사고를 완전히 비활성화하려면 `0`으로 설정합니다. [적응형 추론](/ko/model-config#adjust-effort-level)이 있는 모델에서는 `CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING`을 통해 적응형 추론이 비활성화되지 않으면 예산이 무시됩니다. |

223| `MCP_CLIENT_SECRET` | [사전 구성된 자격 증명](/ko/mcp#use-pre-configured-oauth-credentials)이 필요한 MCP 서버의 OAuth 클라이언트 시크릿입니다. `--client-secret`으로 서버를 추가할 때 대화형 프롬프트를 방지합니다. |226| `MCP_CLIENT_SECRET` | [사전 구성된 자격 증명](/ko/mcp#use-pre-configured-oauth-credentials)이 필요한 MCP 서버의 OAuth 클라이언트 시크릿입니다. `--client-secret`으로 서버를 추가할 때 대화형 프롬프트를 방지합니다. |

224| `MCP_CONNECTION_NONBLOCKING` | 비대화형 모드(`-p`)에서 MCP 연결 대기를 완전히 건너뛰려면 `true`로 설정합니다. MCP 도구가 필요하지 않은 스크립트 파이프라인에 유용합니다. 이 변수가 없으면 첫 번째 쿼리는 `--mcp-config` 서버 연결을 위해 최대 5초 동안 대기합니다. [`alwaysLoad: true`](/ko/mcp#exempt-a-server-from-deferral)로 구성된 서버는 도구가 첫 번째 프롬프트를 빌드할 때 존재해야 하므로 이 변수와 관계없이 항상 시작을 차단합니다. |227| `MCP_CONNECTION_NONBLOCKING` | 시작이 첫 번째 쿼리 전에 MCP 서버 연결을 기다리는지 여부를 제어합니다. Claude Code v2.1.142부터 MCP 시작은 기본적으로 비블로킹입니다: 서버는 백그라운드에서 연결되고 완료되면 도구를 사용할 수 있게 됩니다. `0`으로 설정하여 블로킹 5초 연결 대기를 복원합니다. [`alwaysLoad: true`](/ko/mcp#exempt-a-server-from-deferral)로 구성된 서버는 도구가 첫 번째 프롬프트를 빌드할 때 존재해야 하므로 이 변수와 관계없이 항상 시작을 차단합니다. |

225| `MCP_CONNECT_TIMEOUT_MS` | 첫 번째 쿼리가 MCP 연결 배치를 기다리는 시간(밀리초)을 설정하고 도구 목록을 스냅샷하기 전입니다(기본값: 5000). 마감 시점에 여전히 보류 중인 서버는 백그라운드에서 계속 연결되지만 다음 쿼리까지 나타나지 않습니다. `MCP_TIMEOUT`과 다르며, 이는 개별 서버의 연결 시도를 제한합니다. 단일 쿼리를 발급하고 느리게 연결되는 서버가 표시되어야 하는 비대화형 세션과 가장 관련이 있습니다. |228| `MCP_CONNECT_TIMEOUT_MS` | 블로킹 MCP 시작이 연결 배치를 기다리는 시간(밀리초)을 설정하고 도구 목록을 스냅샷하기 전입니다(기본값: 5000). [`alwaysLoad: true`](/ko/mcp#exempt-a-server-from-deferral)로 표시된 서버에 적용됩니다. 마감 시점에 여전히 보류 중인 서버는 백그라운드에서 계속 연결되지만 다음 쿼리까지 나타나지 않습니다. `MCP_TIMEOUT`과 다르며, 이는 개별 서버의 연결 시도를 제한합니다. |

226| `MCP_OAUTH_CALLBACK_PORT` | [사전 구성된 자격 증명](/ko/mcp#use-pre-configured-oauth-credentials)으로 MCP 서버를 추가할 때 `--callback-port`의 대안으로 OAuth 리디렉션 콜백의 고정 포트입니다. |229| `MCP_OAUTH_CALLBACK_PORT` | [사전 구성된 자격 증명](/ko/mcp#use-pre-configured-oauth-credentials)으로 MCP 서버를 추가할 때 `--callback-port`의 대안으로 OAuth 리디렉션 콜백의 고정 포트입니다. |

227| `MCP_REMOTE_SERVER_CONNECTION_BATCH_SIZE` | 시작 중에 병렬로 연결할 원격 MCP 서버(HTTP/SSE)의 최대 수(기본값: 20) |230| `MCP_REMOTE_SERVER_CONNECTION_BATCH_SIZE` | 시작 중에 병렬로 연결할 원격 MCP 서버(HTTP/SSE)의 최대 수(기본값: 20) |

228| `MCP_SERVER_CONNECTION_BATCH_SIZE` | 시작 중에 병렬로 연결할 로컬 MCP 서버(stdio)의 최대 수(기본값: 3) |231| `MCP_SERVER_CONNECTION_BATCH_SIZE` | 시작 중에 병렬로 연결할 로컬 MCP 서버(stdio)의 최대 수(기본값: 3) |

229| `MCP_TIMEOUT` | MCP 서버 시작의 타임아웃(밀리초)(기본값: 30000, 또는 30초) |232| `MCP_TIMEOUT` | MCP 서버 시작의 타임아웃(밀리초)(기본값: 30000, 또는 30초) |

230| `MCP_TOOL_TIMEOUT` | MCP 도구 실행의 타임아웃(밀리초)(기본값: 100000000, 약 28시간) |233| `MCP_TOOL_TIMEOUT` | MCP 도구 실행의 타임아웃(밀리초)(기본값: 100000000, 약 28시간) |

231| `NO_PROXY` | 프록시를 우회하여 직접 발급될 요청의 도메인 및 IP 목록 |234| `NO_PROXY` | 프록시를 우회하여 직접 발급될 요청의 도메인 및 IP 목록 |

232| `OTEL_LOG_RAW_API_BODIES` | 전체 Anthropic Messages API 요청 및 응답 JSON을 OpenTelemetry 로그 이벤트(`api_request_body`, `api_response_body`)로 내보냅니다. 60KB에서 잘린 인라인 본문의 경우 `1`로 설정하거나, 잘리지 않은 본문을 디스크에 쓰고 `body_ref` 경로를 내보내려면 `file:<dir>`로 설정합니다. 기본적으로 비활성화됩니다. 본문에는 전체 대화 기록이 포함됩니다. [모니터링](/ko/monitoring-usage#api-request-body-event) 참조 |235| `OTEL_LOG_RAW_API_BODIES` | Anthropic Messages API 요청 및 응답 JSON을 `api_request_body` / `api_response_body` 로그 이벤트로 내보냅니다. 60KB에서 잘린 인라인 본문의 경우 `1`로 설정하거나, 잘리지 않은 본문을 디스크에 쓰고 `body_ref` 경로를 내보내려면 `file:<dir>`로 설정합니다. 기본적으로 비활성화됩니다. 본문에는 전체 대화 기록이 포함됩니다. [모니터링](/ko/monitoring-usage#api-request-body-event) 참조 |

233| `OTEL_LOG_TOOL_CONTENT` | 도구 입력 및 출력 내용을 OpenTelemetry 스팬 이벤트에 포함하려면 `1`로 설정합니다. 민감한 데이터를 보호하기 위해 기본적으로 비활성화됩니다. [모니터링](/ko/monitoring-usage) 참조 |236| `OTEL_LOG_TOOL_CONTENT` | 도구 입력 및 출력 내용을 OpenTelemetry 스팬 이벤트에 포함하려면 `1`로 설정합니다. 민감한 데이터를 보호하기 위해 기본적으로 비활성화됩니다. [모니터링](/ko/monitoring-usage) 참조 |

234| `OTEL_LOG_TOOL_DETAILS` | 도구 입력 인수, MCP 서버 이름, 도구 실패 시 원본 오류 문자열, 기타 도구 세부 정보를 OpenTelemetry 추적 및 로그에 포함하려면 `1`로 설정합니다. PII를 보호하기 위해 기본적으로 비활성화됩니다. [모니터링](/ko/monitoring-usage) 참조 |237| `OTEL_LOG_TOOL_DETAILS` | 도구 입력 인수, MCP 서버 이름, 도구 실패 시 원본 오류 문자열, 기타 도구 세부 정보를 OpenTelemetry 추적 및 로그에 포함하려면 `1`로 설정합니다. PII를 보호하기 위해 기본적으로 비활성화됩니다. [모니터링](/ko/monitoring-usage) 참조 |

235| `OTEL_LOG_USER_PROMPTS` | 사용자 프롬프트 텍스트를 OpenTelemetry 추적 및 로그에 포함하려면 `1`로 설정합니다. 기본적으로 비활성화됩니다(프롬프트는 수정됨). [모니터링](/ko/monitoring-usage) 참조 |238| `OTEL_LOG_USER_PROMPTS` | 사용자 프롬프트 텍스트를 OpenTelemetry 추적 및 로그에 포함하려면 `1`로 설정합니다. 기본적으로 비활성화됩니다(프롬프트는 수정됨). [모니터링](/ko/monitoring-usage) 참조 |

162 162 

163이러한 오류는 계정 또는 플랜에 연결된 할당량에 도달했음을 의미합니다. 이는 모든 사람에게 영향을 미치는 [서버 오류](#server-errors)와는 다릅니다.163이러한 오류는 계정 또는 플랜에 연결된 할당량에 도달했음을 의미합니다. 이는 모든 사람에게 영향을 미치는 [서버 오류](#server-errors)와는 다릅니다.

164 164 

165### You've hit your session limit165### 세션 제한에 도달했습니다

166 166 

167구독 플랜에는 롤링 사용 허용량이 포함됩니다. 소진되면 다음 메시지 중 하나가 표시됩니다.167구독 플랜에는 롤링 사용 허용량이 포함됩니다. 소진되면 다음 메시지 중 하나가 표시됩니다.

168 168 

178 178 

179* 오류에 표시된 재설정 시간을 기다립니다.179* 오류에 표시된 재설정 시간을 기다립니다.

180* `/usage`를 실행하여 플랜 제한 및 재설정 시간을 확인합니다.180* `/usage`를 실행하여 플랜 제한 및 재설정 시간을 확인합니다.

181* `/extra-usage`를 실행하여 Pro 및 Max에서 추가 사용을 구매하거나 Team 및 Enterprise에서 관리자에게 요청합니다. [유료 플랜에 대한 추가 사용](https://support.claude.com/en/articles/12429409-extra-usage-for-paid-claude-plans)을 참조하여 청구 방식을 확인하십시오.181* `/usage-credits`를 실행하여 Pro 및 Max에서 추가 사용을 구매하거나 Team 및 Enterprise에서 관리자에게 요청합니다. [유료 플랜에 대한 사용 크레딧](https://support.claude.com/ko/articles/12429409-extra-usage-for-paid-claude-plans)을 참조하여 청구 방식을 확인하십시오.

182* 더 높은 기본 제한을 위해 플랜을 업그레이드하려면 [claude.com/pricing](https://claude.com/pricing)을 참조하십시오.182* 더 높은 기본 제한을 위해 플랜을 업그레이드하려면 [claude.com/pricing](https://claude.com/pricing)을 참조하십시오.

183 183 

184제한에 도달하기 전에 남은 허용량을 확인하려면 `rate_limits` 필드를 [사용자 정의 상태 줄](/ko/statusline#rate-limit-usage)에 추가하거나 데스크톱 앱에서 모델 선택기 옆의 [사용 링](/ko/desktop#check-usage)을 클릭합니다.184제한에 도달하기 전에 남은 허용량을 확인하려면 `rate_limits` 필드를 [사용자 정의 상태 줄](/ko/statusline#rate-limit-usage)에 추가하거나 데스크톱 앱에서 모델 선택기 옆의 [사용 링](/ko/desktop#check-usage)을 클릭합니다.

185 185 

186### Server is temporarily limiting requests186### 서버가 일시적으로 요청을 제한 중입니다

187 187 

188API가 플랜 할당량과 무관한 단기 스로틀을 적용했습니다.188API가 플랜 할당량과 무관한 단기 스로틀을 적용했습니다.

189 189 

198* 잠시 기다린 후 다시 시도합니다.198* 잠시 기다린 후 다시 시도합니다.

199* 지속되면 [status.claude.com](https://status.claude.com)을 확인합니다.199* 지속되면 [status.claude.com](https://status.claude.com)을 확인합니다.

200 200 

201### Request rejected (429)201### 요청 거부됨 (429)

202 202 

203API 키, Amazon Bedrock 프로젝트 또는 Google Vertex AI 프로젝트에 대해 구성된 속도 제한에 도달했습니다.203API 키, Amazon Bedrock 프로젝트 또는 Google Vertex AI 프로젝트에 대해 구성된 속도 제한에 도달했습니다.

204 204 

205```text theme={null}205```text theme={null}

206API Error: Request rejected (429) · this may be a temporary capacity issue206API Error: Request rejected (429) · this may be a temporary capacity issue. If it persists, check status.claude.com.

207```207```

208 208 

209뒤따르는 문장은 서비스 상태를 확인할 위치를 나타내며 제공자에 따라 다릅니다. Bedrock 및 Vertex AI 구성은 Anthropic 상태 페이지 대신 해당 제공자의 서비스 상태를 나타냅니다.

210 

209**할 일:**211**할 일:**

210 212 

211* `/status`를 실행하고 활성 자격 증명이 예상한 것인지 확인합니다. 환경의 잘못된 `ANTHROPIC_API_KEY`가 구독 대신 저가형 키를 통해 요청을 라우팅할 수 있습니다.213* `/status`를 실행하고 활성 자격 증명이 예상한 것인지 확인합니다. 환경의 잘못된 `ANTHROPIC_API_KEY`가 구독 대신 저가형 키를 통해 요청을 라우팅할 수 있습니다.

212* 제공자 콘솔에서 활성 제한을 확인하고 필요한 경우 더 높은 계층을 요청합니다.214* 제공자 콘솔에서 활성 제한을 확인하고 필요한 경우 더 높은 계층을 요청합니다.

213* Anthropic API 키의 경우 [속도 제한 참조](https://platform.claude.com/docs/en/api/rate-limits)에서 계층이 작동하는 방식과 워크스페이스별 상한을 설정하는 방법을 참조하십시오.215* Anthropic API 키의 경우 [속도 제한 참조](https://platform.claude.com/docs/ko/api/rate-limits)에서 계층이 작동하는 방식과 워크스페이스별 상한을 설정하는 방법을 참조하십시오.

214* 동시성 감소: [`CLAUDE_CODE_MAX_TOOL_USE_CONCURRENCY`](/ko/env-vars)를 낮추고, 많은 병렬 서브에이전트 실행을 피하거나, 대량 스크립팅 실행을 위해 `/model`로 더 작은 모델로 전환합니다.216* 동시성 감소: [`CLAUDE_CODE_MAX_TOOL_USE_CONCURRENCY`](/ko/env-vars)를 낮추고, 많은 병렬 서브에이전트 실행을 피하거나, 대량 스크립팅 실행을 위해 `/model`로 더 작은 모델로 전환합니다.

215 217 

216### Credit balance is too low218### 크레딧 잔액이 너무 낮습니다

217 219 

218Console 조직이 선불 크레딧을 모두 사용했습니다.220Console 조직이 선불 크레딧을 모두 사용했습니다.

219 221 

12 12 

13빠른 모드는 Claude Opus를 위한 고속 구성으로, 토큰당 더 높은 비용으로 모델을 2.5배 빠르게 만듭니다. 빠른 반복이나 라이브 디버깅과 같은 대화형 작업에서 속도가 필요할 때 `/fast`로 켜고, 비용이 지연 시간보다 중요할 때 끕니다.13빠른 모드는 Claude Opus를 위한 고속 구성으로, 토큰당 더 높은 비용으로 모델을 2.5배 빠르게 만듭니다. 빠른 반복이나 라이브 디버깅과 같은 대화형 작업에서 속도가 필요할 때 `/fast`로 켜고, 비용이 지연 시간보다 중요할 때 끕니다.

14 14 

15빠른 모드는 다른 모델이 아닙니다. 비용 효율성보다 속도를 우선시하는 다른 API 구성을 사용하는 동일한 Claude Opus를 사용합니다. 동일한 품질과 기능을 얻으며, 응답만 더 빠릅니다. 빠른 모드는 Opus 4.6 및 Opus 4.7에서 지원됩니다. Sonnet, Haiku 또는 다른 모델에서는 사용할 수 없습니다.15빠른 모드는 다른 모델이 아닙니다. 비용 효율성보다 속도를 우선시하는 다른 API 구성을 사용하는 동일한 Claude Opus를 사용합니다. 동일한 품질과 기능을 얻으며, 응답만 더 빠릅니다. 빠른 모드는 Opus 4.7 및 Opus 4.6에서 지원됩니다. Sonnet, Haiku 또는 다른 모델에서는 사용할 수 없습니다.

16 16 

17<Note>17<Note>

18 빠른 모드는 Claude Code v2.1.36 이상이 필요합니다. `claude --version`으로 버전을 확인합니다.18 빠른 모드는 Claude Code v2.1.36 이상이 필요합니다. `claude --version`으로 버전을 확인합니다.

21알아야 할 사항:21알아야 할 사항:

22 22 

23* Claude Code CLI에서 `/fast`를 사용하여 빠른 모드를 전환합니다. Claude Code VS Code 확장 프로그램에서도 `/fast`를 통해 사용할 수 있습니다.23* Claude Code CLI에서 `/fast`를 사용하여 빠른 모드를 전환합니다. Claude Code VS Code 확장 프로그램에서도 `/fast`를 통해 사용할 수 있습니다.

24* 기본적으로 `/fast`는 Opus 4.6에서 실행됩니다. 대신 Opus 4.7에서 빠른 모드를 실행하려면 [`CLAUDE_CODE_ENABLE_OPUS_4_7_FAST_MODE`](#use-fast-mode-on-opus-4-7) 환경 변수를 설정합니다.24* 빠른 모드 가격은 Opus 4.7과 Opus 4.6 모두에서 $30/$150 MTok입니다.

25* 빠른 모드 가격은 Opus 4.6과 Opus 4.7 모두에서 \$30/150 MTok입니다.

26* 구독 요금제(Pro/Max/Team/Enterprise)의 모든 Claude Code 사용자 및 Claude Console에서 사용할 수 있습니다.25* 구독 요금제(Pro/Max/Team/Enterprise)의 모든 Claude Code 사용자 및 Claude Console에서 사용할 수 있습니다.

27* 구독 요금제(Pro/Max/Team/Enterprise)의 Claude Code 사용자의 경우, 빠른 모드는 추가 사용을 통해서만 사용 가능하며 구독 요금제 사용량 제한에 포함되지 않습니다.26* 구독 요금제(Pro/Max/Team/Enterprise)의 Claude Code 사용자의 경우, 빠른 모드는 사용 크레딧을 통해서만 사용 가능하며 구독 요금제 사용량 제한에 포함되지 않습니다.

28 27 

29이 페이지에서는 [빠른 모드 전환](#toggle-fast-mode), [Opus 4.7에서 빠른 모드 사용](#use-fast-mode-on-opus-4-7), [비용 트레이드오프](#understand-the-cost-tradeoff), [빠른 모드 사용 시기](#decide-when-to-use-fast-mode), [요구사항](#requirements), [세션별 옵트인](#require-per-session-opt-in) 및 [속도 제한 처리](#handle-rate-limits)를 다룹니다.28이 페이지에서는 [빠른 모드 전환](#toggle-fast-mode), [비용 트레이드오프](#understand-the-cost-tradeoff), [빠른 모드 사용 시기](#decide-when-to-use-fast-mode), [요구사항](#requirements), [세션별 옵트인](#require-per-session-opt-in) 및 [속도 제한 처리](#handle-rate-limits)를 다룹니다.

30 29 

31## 빠른 모드 전환30## 빠른 모드 전환

32 31 

41 40 

42빠른 모드를 활성화하면:41빠른 모드를 활성화하면:

43 42 

44* 다른 모델을 사용 중인 경우 Claude Code가 자동으로 빠른 모드 모델로 전환됩니다: 기본적으로 Opus 4.6이거나 [`CLAUDE_CODE_ENABLE_OPUS_4_7_FAST_MODE`](#use-fast-mode-on-opus-4-7)가 설정되어 있을 때 Opus 4.7입니다.43* 다른 모델을 사용 중인 경우 Claude Code가 자동으로 Opus로 전환됩니다

45* 확인 메시지가 표시됩니다: "Fast mode ON"44* 확인 메시지가 표시됩니다: "Fast mode ON"

46* 빠른 모드가 활성화되어 있는 동안 프롬프트 옆에 작은 `↯` 아이콘이 나타납니다45* 빠른 모드가 활성화되어 있는 동안 프롬프트 옆에 작은 `↯` 아이콘이 나타납니다

47* 언제든지 `/fast`를 다시 실행하여 빠른 모드가 켜져 있는지 꺼져 있는지 확인합니다46* 언제든지 `/fast`를 다시 실행하여 빠른 모드가 켜져 있는지 꺼져 있는지 확인합니다

48 47 

49`/fast`를 다시 실행하여 빠른 모드를 비활성화하면 빠른 모드가 실행 중이던 동일한 Opus 버전에 유지됩니다. 모델이 이전 모델로 되돌아가지 않습니다. 다른 모델로 전환하려면 `/model`을 사용합니다.48`/fast`를 다시 실행하여 빠른 모드를 비활성화하면 Opus에 유지됩니다. 모델이 이전 모델로 되돌아가지 않습니다. 다른 모델로 전환하려면 `/model`을 사용합니다.

50 49 

51## Opus 4.7에서 빠른 모드 사용50Opus 4.7은 Claude Code v2.1.142 이상에서 빠른 모드 기본값입니다. 대신 빠른 모드를 Opus 4.6에 고정하려면 `CLAUDE_CODE_OPUS_4_6_FAST_MODE_OVERRIDE=1`을 설정합니다.

52 

53<Note>

54 Opus 4.7의 빠른 모드는 Claude Code v2.1.139 이상이 필요합니다.

55</Note>

56 

57Claude Opus 4.7의 빠른 모드는 연구 미리보기입니다. Opus 4.6의 빠른 모드와 동일한 2.5배 속도 및 동일한 가격으로 실행되며, 다른 동작 변경 사항은 없습니다.

58 

59<Note>

60 2026년 5월 14일에 Opus 4.7이 기본 빠른 모드 모델이 됩니다. 그때까지 `CLAUDE_CODE_ENABLE_OPUS_4_7_FAST_MODE=1`을 설정하여 옵트인합니다.

61</Note>

62 

63옵트인하려면 Claude Code를 시작하기 전에 `CLAUDE_CODE_ENABLE_OPUS_4_7_FAST_MODE=1`을 설정합니다. 변수가 설정되면 `/fast`는 Opus 4.7에서 실행됩니다. 설정되지 않으면 `/fast`는 계속 Opus 4.6에서 실행됩니다.

64 

65변수를 셸 내보내기로 설정할 수 있습니다:

66 

67```bash theme={null}

68export CLAUDE_CODE_ENABLE_OPUS_4_7_FAST_MODE=1

69```

70 

71또는 사용자, 프로젝트 및 관리되는 설정을 포함한 모든 Claude Code [설정 파일](/ko/settings#settings-files)에서 옵트인 범위를 지정하려면:

72 

73```json theme={null}

74{

75 "env": {

76 "CLAUDE_CODE_ENABLE_OPUS_4_7_FAST_MODE": "1"

77 }

78}

79```

80 

81Opus 4.6의 빠른 모드는 Opus 4.7과 함께 계속 사용할 수 있습니다. 둘 다 동일한 빠른 모드 속도 제한 풀을 공유합니다: 어느 모델에서든 사용량은 동일한 제한에서 차감됩니다.

82 

83빠른 모드를 Opus 4.6으로 명시적으로 고정하려면 `CLAUDE_CODE_OPUS_4_6_FAST_MODE_OVERRIDE=1`을 설정합니다. 이 변수는 우선순위를 가지므로 `CLAUDE_CODE_ENABLE_OPUS_4_7_FAST_MODE`이 설정되었는지 여부와 관계없이 빠른 모드는 Opus 4.6에서 실행됩니다.

84 51 

85## 비용 트레이드오프 이해52## 비용 트레이드오프 이해

86 53 

87빠른 모드는 표준 Opus보다 토큰당 가격이 높습니다:54빠른 모드는 표준 Opus보다 토큰당 가격이 높습니다:

88 55 

89| 모드 | 입력 (MTok) | 출력 (MTok) |56| 모드 | 입력 (MTok) | 출력 (MTok) |

90| --------------- | --------- | --------- |57| ----- | --------- | --------- |

91| Opus 4.6의 빠른 모드 | \$30 | \$150 |58| 빠른 모드 | \$30 | \$150 |

92| Opus 4.7의 빠른 모드 | \$30 | \$150 |

93 59 

94빠른 모드 가격은 전체 1M 토큰 컨텍스트 윈도우에 걸쳐 고정입니다.60빠른 모드 가격은 전체 1M 토큰 컨텍스트 윈도우에 걸쳐 고정입니다.

95 61 

124 90 

125빠른 모드는 다음 모두를 필요로 합니다:91빠른 모드는 다음 모두를 필요로 합니다:

126 92 

127* **타사 클라우드 제공자에서 사용 불가**: 빠른 모드는 Amazon Bedrock, Google Vertex AI 또는 Microsoft Azure Foundry에서 사용할 수 없습니다. 빠른 모드는 Anthropic Console API 및 추가 사용을 사용하는 Claude 구독 요금제를 통해 사용할 수 있습니다.93* **타사 클라우드 제공자에서 사용 불가**: 빠른 모드는 Amazon Bedrock, Google Vertex AI 또는 Microsoft Azure Foundry에서 사용할 수 없습니다. 빠른 모드는 Anthropic Console API 및 사용 크레딧을 사용하는 Claude 구독 요금제를 통해 사용할 수 있습니다.

128* **추가 사용 활성화**: 계정에 추가 사용이 활성화되어 있어야 하며, 이를 통해 요금제의 포함된 사용량을 초과하여 청구할 수 있습니다. 개인 계정의 경우 [Console 청구 설정](https://platform.claude.com/settings/organization/billing)에서 활성화합니다. Team 및 Enterprise의 경우 관리자가 조직에 대해 추가 사용을 활성화해야 합니다.94* **사용 크레딧 활성화**: 계정에 사용 크레딧이 활성화되어 있어야 하며, 이를 통해 요금제의 포함된 사용량을 초과하여 청구할 수 있습니다. 개인 계정의 경우 [Console 청구 설정](https://platform.claude.com/settings/organization/billing)에서 활성화합니다. Team 및 Enterprise의 경우 관리자가 조직에 대해 사용 크레딧을 활성화해야 합니다.

129 95 

130<Note>96<Note>

131 빠른 모드 사용량은 요금제에 남은 사용량이 있더라도 추가 사용으로 직접 청구됩니다. 이는 빠른 모드 토큰이 요금제의 포함된 사용량에 포함되지 않으며 첫 번째 토큰부터 빠른 모드 요금으로 청구됨을 의미합니다.97 빠른 모드 사용량은 요금제에 남은 사용량이 있더라도 사용 크레딧에서 직접 인출됩니다. 이는 빠른 모드 토큰이 요금제의 포함된 사용량에 포함되지 않으며 첫 번째 토큰부터 빠른 모드 요금으로 청구됨을 의미합니다.

132</Note>98</Note>

133 99 

134* **Team 및 Enterprise의 관리자 활성화**: 빠른 모드는 Team 및 Enterprise 조직에 대해 기본적으로 비활성화됩니다. 사용자가 액세스할 수 있으려면 관리자가 명시적으로 [빠른 모드를 활성화](#enable-fast-mode-for-your-organization)해야 합니다.100* **Team 및 Enterprise의 관리자 활성화**: 빠른 모드는 Team 및 Enterprise 조직에 대해 기본적으로 비활성화됩니다. 사용자가 액세스할 수 있으려면 관리자가 명시적으로 [빠른 모드를 활성화](#enable-fast-mode-for-your-organization)해야 합니다.

160 126 

161## 속도 제한 처리127## 속도 제한 처리

162 128 

163빠른 모드는 표준 Opus와 별도의 속도 제한을 가집니다. Opus 4.6 및 Opus 4.7의 빠른 모드는 동일한 속도 제한 풀을 공유합니다: 어느 모델에서든 사용량은 동일한 제한에서 차감됩니다. 빠른 모드 속도 제한에 도달하거나 추가 사용이 부족할 때:129빠른 모드는 표준 Opus와 별도의 속도 제한을 가집니다. Opus 4.7과 Opus 4.6의 빠른 모드는 동일한 속도 제한 풀을 공유합니다: 어느 모델에서든 사용량은 동일한 제한에서 차감됩니다. 빠른 모드 속도 제한에 도달하거나 사용 크레딧이 부족할 때:

164 130 

1651. 빠른 모드가 자동으로 동일한 Opus 버전의 표준 속도로 폴백됩니다1311. 빠른 모드가 자동으로 표준 속도로 폴백됩니다

1662. `↯` 아이콘이 회색으로 변하여 쿨다운을 나타냅니다1322. `↯` 아이콘이 회색으로 변하여 쿨다운을 나타냅니다

1673. 표준 속도 및 가격으로 계속 작업합니다1333. 표준 속도 및 가격으로 계속 작업합니다

1684. 쿨다운이 만료되면 빠른 모드가 자동으로 다시 활성화됩니다1344. 쿨다운이 만료되면 빠른 모드가 자동으로 다시 활성화됩니다

271 271 

272 **로드되는 내용:** 신선한, 격리된 컨텍스트 포함:272 **로드되는 내용:** 신선한, 격리된 컨텍스트 포함:

273 273 

274 * 시스템 프롬프트(캐시 효율성을 위해 부모와 공유)274 * 에이전트 자신의 시스템 프롬프트, 전체 Claude Code 시스템 프롬프트가 아님

275 * 에이전트의 `skills:` 필드에 나열된 skill의 전체 콘텐츠275 * 에이전트의 `skills:` 필드에 나열된 skill의 전체 콘텐츠

276 * CLAUDE.md 및 git 상태(부모에서 상속)276 * CLAUDE.md 및 git 상태, 내장 Explore 및 Plan 에이전트 [둘 다 생략](/ko/sub-agents#what-loads-at-startup) 제외

277 * 리드 에이전트가 프롬프트에서 전달하는 모든 컨텍스트277 * 리드 에이전트가 프롬프트에서 전달하는 모든 컨텍스트

278 278 

279 **컨텍스트 비용:** 주 세션에서 격리됨. Subagent는 대화 기록이나 호출된 skill을 상속하지 않습니다.279 **컨텍스트 비용:** 주 세션에서 격리됨. Subagent는 대화 기록이나 호출된 skill을 상속하지 않습니다.

732# Notification hook: Claude Code가 주의가 필요할 때 데스크톱을 ping합니다.732# Notification hook: Claude Code가 주의가 필요할 때 데스크톱을 ping합니다.

733input=$(cat)733input=$(cat)

734title="Claude Code'734title="Claude Code'

735body=$(jq -r '.message // 'Needs your attention"' <<<"$input")735body=$(jq -r '.message // 'Needs your attention'' <<<"$input")

736seq=$(printf '\033]777;notify;%s;%s\007' "$title" "$body")736seq=$(printf '\033]777;notify;%s;%s\007' "$title" "$body")

737jq -nc --arg seq "$seq" '{terminalSequence: $seq}'737jq -nc --arg seq "$seq" '{terminalSequence: $seq}'

738```738```

907* JSON이 유효한지 확인합니다(후행 쉼표 및 주석은 허용되지 않음)907* JSON이 유효한지 확인합니다(후행 쉼표 및 주석은 허용되지 않음)

908* 설정 파일이 올바른 위치에 있는지 확인합니다: 프로젝트 hooks의 경우 `.claude/settings.json`, 전역 hooks의 경우 `~/.claude/settings.json`908* 설정 파일이 올바른 위치에 있는지 확인합니다: 프로젝트 hooks의 경우 `.claude/settings.json`, 전역 hooks의 경우 `~/.claude/settings.json`

909 909 

910### Stop hook이 무한 실행됨910### Stop hook이 블록 상한에 도달함

911 911 

912Claude가 무한 루프에서 계속 작업하는 대신 중지합니다.912Claude가 계속 작업하는 대신 중지하고 Stop hook이 너무 많은 횟수를 연속으로 차단했다는 경고로 턴을 종료합니다.

913 913 

914Stop hook 스크립트는 이미 트리거되었는지 확인해야 합니다. JSON 입력에서 `stop_hook_active` 필드를 구문 분석하고 `true`인 경우 조기에 종료합니다:914Claude Code는 Stop hook이 진행 없이 8번 연속으로 차단한 후 재정의합니다. Hook 스크립트는 이미 트리거되었는지 확인해야 합니다. JSON 입력에서 `stop_hook_active` 필드를 구문 분석하고 `true`인 경우 조기에 종료합니다:

915 915 

916```bash theme={null}916```bash theme={null}

917#!/bin/bash917#!/bin/bash

922# ... hook 로직의 나머지922# ... hook 로직의 나머지

923```923```

924 924 

925Hook이 수렴하기 위해 8번 이상의 반복이 필요한 경우 [`CLAUDE_CODE_STOP_HOOK_BLOCK_CAP`](/ko/env-vars)으로 상한을 올립니다.

926 

925### JSON 검증 실패927### JSON 검증 실패

926 928 

927Hook 스크립트가 유효한 JSON을 출력하더라도 Claude Code에 JSON 구문 분석 오류가 표시됩니다.929Hook 스크립트가 유효한 JSON을 출력하더라도 Claude Code에 JSON 구문 분석 오류가 표시됩니다.

928 930 

929Claude Code가 셸 형식 명령 hook(args 없는 hook)을 실행할 때 macOS 및 Linux에서는 기본적으로 `sh -c`를 생성하거나 Windows에서는 Git Bash를 생성합니다. 이 셸은 비대화형이지만 Git Bash 및 일부 구성(예: `BASH_ENV`가 `~/.bashrc`를 가리킴)은 여전히 프로필을 소싱합니다. 해당 프로필에 무조건적인 `echo` 문이 포함되어 있으면 출력이 hook의 JSON에 앞에 붙습니다:931Claude Code가 셸 형식 명령 hook(`args` 없는 hook)을 실행할 때 macOS 및 Linux에서는 기본적으로 `sh -c`를 생성하거나 Windows에서는 Git Bash를 생성합니다. 이 셸은 비대화형이지만 Git Bash 및 일부 구성(예: `BASH_ENV`가 `~/.bashrc`를 가리킴)은 여전히 프로필을 소싱합니다. 해당 프로필에 무조건적인 `echo` 문이 포함되어 있으면 출력이 hook의 JSON에 앞에 붙습니다:

930 932 

931```text theme={null}933```text theme={null}

932Shell ready on arm64934Shell ready on arm64

143 143 

144`/mcp` 패널은 각 연결된 서버 옆에 도구 개수를 표시하고 도구 기능을 광고하지만 도구를 노출하지 않는 서버에 플래그를 지정합니다.144`/mcp` 패널은 각 연결된 서버 옆에 도구 개수를 표시하고 도구 기능을 광고하지만 도구를 노출하지 않는 서버에 플래그를 지정합니다.

145 145 

146요청이 백그라운드에서 아직 연결 중인 서버의 도구가 필요한 경우 Claude는 해당 서버가 연결될 때까지 기다립니다. [도구 검색](#scale-with-mcp-tool-search)이 활성화되어 있으면 (기본값), 대기는 `ToolSearch` 호출 내에서 발생합니다. Vertex AI, 사용자 정의 `ANTHROPIC_BASE_URL` 또는 `ENABLE_TOOL_SEARCH=false`와 같이 도구 검색이 없는 구성에서는 Claude가 대신 `WaitForMcpServers` 도구를 사용합니다.

147 

146서버 이름 `workspace`는 내부 사용을 위해 예약되어 있습니다. 구성에서 해당 이름의 서버를 정의하면 Claude Code는 로드 시 이를 건너뛰고 이름을 바꾸도록 요청하는 경고를 표시합니다.148서버 이름 `workspace`는 내부 사용을 위해 예약되어 있습니다. 구성에서 해당 이름의 서버를 정의하면 Claude Code는 로드 시 이를 건너뛰고 이름을 바꾸도록 요청하는 경고를 표시합니다.

147 149 

148### 동적 도구 업데이트150### 동적 도구 업데이트

1007 1009 

1008`alwaysLoad` 필드는 모든 서버 유형에서 사용 가능하며 Claude Code v2.1.121 이상이 필요합니다. MCP 서버는 도구의 `_meta` 객체에 `"anthropic/alwaysLoad": true`를 포함하여 개별 도구를 항상 로드되도록 표시할 수도 있으며, 이는 해당 도구에만 동일한 효과를 갖습니다.1010`alwaysLoad` 필드는 모든 서버 유형에서 사용 가능하며 Claude Code v2.1.121 이상이 필요합니다. MCP 서버는 도구의 `_meta` 객체에 `"anthropic/alwaysLoad": true`를 포함하여 개별 도구를 항상 로드되도록 표시할 수도 있으며, 이는 해당 도구에만 동일한 효과를 갖습니다.

1009 1011 

1010`alwaysLoad: true`를 설정하면 서버가 연결될 때까지 시작이 차단되며, 표준 5초 연결 타임아웃으로 제한됩니다. 이는 [`MCP_CONNECTION_NONBLOCKING=1`](/ko/env-vars)이 설정된 경우에도 적용됩니다. 첫 번째 프롬프트가 빌드될 때 도구가 있어야 하기 때문입니다. 비차단이 활성화된 경우 다른 서버는 여전히 백그라운드에서 연결됩니다.1012`alwaysLoad: true`를 설정하면 서버가 연결될 때까지 시작이 차단되며, 표준 5초 연결 타임아웃으로 제한됩니다. 이는 MCP 시작이 기본적으로 [비차단](/ko/env-vars)이더라도 적용됩니다. 첫 번째 프롬프트가 빌드될 때 도구가 있어야 하기 때문입니다. 다른 서버는 계속해서 백그라운드에서 연결됩니다.

1011 1013 

1012## MCP 프롬프트를 명령으로 사용1014## MCP 프롬프트를 명령으로 사용

1013 1015 

284다음 환경 변수를 사용할 수 있으며, 이는 별칭이 매핑되는 모델 이름을 제어하기 위해 전체 **모델 이름**(또는 API 제공자에 해당하는 이름)이어야 합니다.284다음 환경 변수를 사용할 수 있으며, 이는 별칭이 매핑되는 모델 이름을 제어하기 위해 전체 **모델 이름**(또는 API 제공자에 해당하는 이름)이어야 합니다.

285 285 

286| 환경 변수 | 설명 |286| 환경 변수 | 설명 |

287| -------------------------------- | --------------------------------------------------------------- |287| -------------------------------- | ----------------------------------------------------------------------------------------------------------------------- |

288| `ANTHROPIC_DEFAULT_OPUS_MODEL` | `opus`에 사용할 모델 또는 Plan Mode가 활성화되었을 때 `opusplan`에 사용할 모델 |288| `ANTHROPIC_DEFAULT_OPUS_MODEL` | `opus`에 사용할 모델 또는 Plan Mode가 활성화되었을 때 `opusplan`에 사용할 모델 |

289| `ANTHROPIC_DEFAULT_SONNET_MODEL` | `sonnet`에 사용할 모델 또는 Plan Mode가 활성화되지 않았을 때 `opusplan`에 사용할 모델 |289| `ANTHROPIC_DEFAULT_SONNET_MODEL` | `sonnet`에 사용할 모델 또는 Plan Mode가 활성화되지 않았을 때 `opusplan`에 사용할 모델 |

290| `ANTHROPIC_DEFAULT_HAIKU_MODEL` | `haiku`에 사용할 모델 또는 [백그라운드 기능](/ko/costs#background-token-usage) |290| `ANTHROPIC_DEFAULT_HAIKU_MODEL` | `haiku`에 사용할 모델 또는 [백그라운드 기능](/ko/costs#background-token-usage) |

291| `CLAUDE_CODE_SUBAGENT_MODEL` | [subagents](/ko/sub-agents)에 사용할 모델 |291| `CLAUDE_CODE_SUBAGENT_MODEL` | 모든 [subagents](/ko/sub-agents#choose-a-model)에 사용할 모델입니다. 호출별 `model` 매개변수와 subagent 정의의 `model` frontmatter를 모두 재정의합니다 |

292 292 

293참고: `ANTHROPIC_SMALL_FAST_MODEL`은 `ANTHROPIC_DEFAULT_HAIKU_MODEL`을 위해 더 이상 사용되지 않습니다.293참고: `ANTHROPIC_SMALL_FAST_MODEL`은 `ANTHROPIC_DEFAULT_HAIKU_MODEL`을 위해 더 이상 사용되지 않습니다.

294 294 

2> Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt2> Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt

3> Use this file to discover all available pages before exploring further.3> Use this file to discover all available pages before exploring further.

4 4 

5# Claude Code 개요5# 개요

6 6 

7> Claude Code는 코드베이스를 읽고, 파일을 편집하고, 명령을 실행하고, 개발 도구와 통합하는 에이전트 코딩 도구입니다. 터미널, IDE, 데스크톱 앱 및 브라우저에서 사용할 수 있습니다.7> Claude Code는 코드베이스를 읽고, 파일을 편집하고, 명령을 실행하고, 개발 도구와 통합하는 에이전트 코딩 도구입니다. 터미널, IDE, 데스크톱 앱 및 브라우저에서 사용할 수 있습니다.

8 8 

73 | 자동 모드 | `auto` |73 | 자동 모드 | `auto` |

74 | 권한 무시 | `bypassPermissions` |74 | 권한 무시 | `bypassPermissions` |

75 75 

76 자동 모드는 확장 설정에서 **위험하게 권한 건너뛰기 허용**을 활성화한 후 모드 표시기에 나타나지만, 계정이 [자동 모드 섹션](#eliminate-prompts-with-auto-mode)에 나열된 모든 요구 사항을 충족할 때까지 사용 불가능한 상태로 유지됩니다. `claudeCode.initialPermissionMode` 설정은 `auto`를 허용하지 않습니다. 기본적으로 자동 모드로 시작하려면 대신 Claude Code [`settings.json`](/ko/settings#settings-files)에서 `defaultMode`를 설정합니다.76 자동 모드는 확장 설정에서 **위험하게 권한 건너뛰기 허용**을 활성화한 후 모드 표시기에 나타나지만, 계정이 [자동 모드 섹션](#eliminate-prompts-with-auto-mode)에 나열된 모든 요구 사항을 충족할 때까지 사용 불가능한 상태로 유지됩니다. `claudeCode.initialPermissionMode` 설정은 `auto`를 허용하지 않습니다. 기본적으로 자동 모드로 시작하려면 대신 [사용자 설정](/ko/settings#settings-files)에서 `defaultMode`를 설정합니다. Claude Code는 프로젝트 및 로컬 설정에서 `defaultMode: "auto"`를 무시합니다.

77 77 

78 권한 무시도 모드 표시기에 나타나기 전에 **위험하게 권한 건너뛰기 허용** 토글이 필요합니다.78 권한 무시도 모드 표시기에 나타나기 전에 **위험하게 권한 건너뛰기 허용** 토글이 필요합니다.

79 79 

179 179 

180Claude Code가 자동 모드를 사용할 수 없다고 보고하면, 이러한 요구 사항 중 하나가 충족되지 않은 것입니다. 이는 일시적인 중단이 아닙니다. 모델을 이름으로 지정하고 자동 모드가 작업의 안전을 "결정할 수 없다"고 말하는 별도의 메시지는 일시적인 분류기 중단입니다. [오류 참조](/ko/errors#auto-mode-cannot-determine-the-safety-of-an-action)를 참조합니다.180Claude Code가 자동 모드를 사용할 수 없다고 보고하면, 이러한 요구 사항 중 하나가 충족되지 않은 것입니다. 이는 일시적인 중단이 아닙니다. 모델을 이름으로 지정하고 자동 모드가 작업의 안전을 "결정할 수 없다"고 말하는 별도의 메시지는 일시적인 분류기 중단입니다. [오류 참조](/ko/errors#auto-mode-cannot-determine-the-safety-of-an-action)를 참조합니다.

181 181 

182[설정](/ko/settings#available-settings)에서 `defaultMode: "auto"`를 설정했는데 세션이 오류 없이 `default` 모드로 시작하면, 설정이 `.claude/settings.json` 또는 `.claude/settings.local.json`에 있을 가능성이 높습니다. Claude Code는 이러한 파일의 `auto`를 무시하므로 리포지토리가 자신에게 자동 모드를 부여할 수 없습니다. 이를 `~/.claude/settings.json`으로 이동합니다.

183 

182### 분류기가 기본적으로 차단하는 항목184### 분류기가 기본적으로 차단하는 항목

183 185 

184분류기는 작업 디렉토리와 리포지토리의 구성된 원격을 신뢰합니다. 다른 모든 것은 [신뢰할 수 있는 인프라를 구성](/ko/auto-mode-config)할 때까지 외부로 취급됩니다.186분류기는 작업 디렉토리와 리포지토리의 구성된 원격을 신뢰합니다. 다른 모든 것은 [신뢰할 수 있는 인프라를 구성](/ko/auto-mode-config)할 때까지 외부로 취급됩니다.

114 114 

115종속성을 제약하는 마지막 플러그인을 제거하면 종속성은 더 이상 유지되지 않으며 다음 업데이트에서 마켓플레이스 항목 추적을 재개합니다.115종속성을 제약하는 마지막 플러그인을 제거하면 종속성은 더 이상 유지되지 않으며 다음 업데이트에서 마켓플레이스 항목 추적을 재개합니다.

116 116 

117## 플러그인 종속성 활성화 또는 비활성화

118 

119플러그인을 활성화하면 이에 종속된 플러그인도 활성화되며, 다른 활성화된 플러그인이 여전히 필요로 하면 플러그인을 비활성화할 수 없습니다. 두 동작 모두 Claude Code v2.1.143 이상이 필요합니다. 이전 버전은 명명된 플러그인만 활성화하거나 비활성화하고 다음 로드에서 `dependency-unsatisfied` 오류를 표시합니다.

120 

121플러그인을 활성화하면 Claude Code는 동일한 범위에서 해당 종속성도 활성화합니다. 종속성에 자체 종속성이 있으면 Claude Code는 이들도 활성화합니다. 성공 메시지는 명명한 플러그인과 함께 활성화된 다른 항목을 나열합니다. 종속성을 활성화할 수 없으면 명령이 거부되고 무엇이 차단하고 있는지, 어떻게 해결할지 알려줍니다:

122 

123| 조건 | 결과 |

124| :--------------------------------------- | :--------------------------------------------------------- |

125| 종속성이 설치되지 않음 | 활성화가 실패하고 누락된 각 종속성에 대해 `claude plugin install` 명령을 인쇄합니다. |

126| 종속성이 조직의 플러그인 정책에 의해 차단됨 | 활성화가 실패하고 차단된 종속성의 이름을 지정합니다. |

127| 종속성이 대상 범위보다 우선 순위가 높은 범위에서 `false`로 설정됨 | 활성화가 실패합니다. 해당 범위에서 종속성을 활성화하거나 `--scope`를 전달하여 거기에 쓰기합니다. |

128| 모든 종속성이 설치되고 허용됨 | 활성화가 성공하고 대상 범위에서 아직 활성화되지 않은 플러그인과 각 종속성에 대해 `true`를 씁니다. |

129 

130플러그인을 비활성화하면 다른 활성화된 플러그인이 여전히 이에 종속되면 Claude Code가 거부합니다. 오류는 이에 종속된 플러그인의 이름을 지정하고 올바른 순서로 비활성화하는 연쇄 명령을 제공하며, 요청한 것으로 끝납니다.

131 

132예를 들어 `deploy-kit`이 `secrets-vault`에 종속되면 `secrets-vault`만 비활성화하면 다음과 유사한 출력으로 실패합니다:

133 

134```text theme={null}

135secrets-vault is still required by deploy-kit. Disable that plugin first, or

136disable everything together: claude plugin disable deploy-kit@acme-tools && claude plugin disable secrets-vault@acme-tools

137```

138 

139오류에서 연쇄 명령을 복사하여 한 단계에서 전체 집합을 비활성화합니다.

140 

117## 고아 자동 설치 종속성 제거141## 고아 자동 설치 종속성 제거

118 142 

119자동 설치된 종속성은 이를 설치한 플러그인이 제거된 후에도 디스크에 남아 있으며, 종속 플러그인을 다시 설치하거나 종속성을 직접 계속 사용하려는 경우를 대비합니다. 이를 정리하려면 `claude plugin prune`을 실행하여 더 이상 설치된 플러그인이 필요로 하지 않는 자동 설치된 종속성을 나열하고 확인 프롬프트 후 제거합니다. 이는 Claude Code v2.1.121 이상이 필요합니다.143자동 설치된 종속성은 이를 설치한 플러그인이 제거된 후에도 디스크에 남아 있으며, 종속 플러그인을 다시 설치하거나 종속성을 직접 계속 사용하려는 경우를 대비합니다. 이를 정리하려면 `claude plugin prune`을 실행하여 더 이상 설치된 플러그인이 필요로 하지 않는 자동 설치된 종속성을 나열하고 확인 프롬프트 후 제거합니다. 이는 Claude Code v2.1.121 이상이 필요합니다.

161| `plugins` | array | 사용 가능한 플러그인 목록 | 아래 참조 |161| `plugins` | array | 사용 가능한 플러그인 목록 | 아래 참조 |

162 162 

163<Note>163<Note>

164 **예약된 이름**: 다음 마켓플레이스 이름은 공식 Anthropic 사용을 위해 예약되어 있으며 타사 마켓플레이스에서 사용할 수 없습니다: `claude-code-marketplace`, `claude-code-plugins`, `claude-plugins-official`, `anthropic-marketplace`, `anthropic-plugins`, `agent-skills`, `knowledge-work-plugins`, `life-sciences`. 공식 마켓플레이스를 사칭하는 이름(예: `official-claude-plugins` 또는 `anthropic-tools-v2`)도 차단됩니다.164 **예약된 이름**: 다음 마켓플레이스 이름은 공식 Anthropic 사용을 위해 예약되어 있으며 타사 마켓플레이스에서 사용할 수 없습니다: `claude-code-marketplace`, `claude-code-plugins`, `claude-plugins-official`, `anthropic-marketplace`, `anthropic-plugins`, `agent-skills`, `anthropic-agent-skills`, `knowledge-work-plugins`, `life-sciences`. 공식 마켓플레이스를 사칭하는 이름(예: `official-claude-plugins` 또는 `anthropic-tools-v2`)도 차단됩니다.

165</Note>165</Note>

166 166 

167### 소유자 필드167### 소유자 필드

200 200 

201| 필드 | 유형 | 설명 |201| 필드 | 유형 | 설명 |

202| :------------ | :------ | :------------------------------------------------------------------------------------------------------------------------------------------------------------------ |202| :------------ | :------ | :------------------------------------------------------------------------------------------------------------------------------------------------------------------ |

203| `displayName` | string | {/* min-version: 2.1.143 */}UI 표면에 표시되는 사람이 읽을 수 있는 이름입니다. 생략하면 `name`으로 돌아갑니다. 공백과 모든 대소문자를 포함할 수 있습니다. 네임스페이싱이나 조회에 사용되지 않습니다. Claude Code v2.1.143 이상이 필요합니다. |

203| `description` | string | 간단한 플러그인 설명 |204| `description` | string | 간단한 플러그인 설명 |

204| `version` | string | 플러그인 버전. 설정된 경우(여기 또는 `plugin.json`에서), 플러그인은 이 문자열로 고정되며 사용자는 변경될 때만 업데이트를 받습니다. 생략하면 git 커밋 SHA로 돌아갑니다. [버전 해석](#version-resolution-and-release-channels)을 참조하세요. |205| `version` | string | 플러그인 버전. 설정된 경우(여기 또는 `plugin.json`에서), 플러그인은 이 문자열로 고정되며 사용자는 변경될 때만 업데이트를 받습니다. 생략하면 git 커밋 SHA로 돌아갑니다. [버전 해석](#version-resolution-and-release-channels)을 참조하세요. |

205| `author` | object | 플러그인 작성자 정보(`name` 필수, `email` 선택) |206| `author` | object | 플러그인 작성자 정보(`name` 필수, `email` 선택) |

20 20 

21플러그인은 Claude Code에 skills를 추가하여 사용자나 Claude가 호출할 수 있는 `/name` 바로가기를 생성합니다.21플러그인은 Claude Code에 skills를 추가하여 사용자나 Claude가 호출할 수 있는 `/name` 바로가기를 생성합니다.

22 22 

23**위치**: 플러그인 루트의 `skills/` 또는 `commands/` 디렉토리23**위치**: 플러그인 루트의 `skills/` 또는 `commands/` 디렉토리, 또는 플러그인 루트의 단일 `SKILL.md` 파일

24 24 

25**파일 형식**: Skills는 `SKILL.md`가 있는 디렉토리이고, commands는 간단한 마크다운 파일입니다.25**파일 형식**: Skills는 `SKILL.md`가 있는 디렉토리이고, commands는 간단한 마크다운 파일입니다.

26 26 

367```json theme={null}367```json theme={null}

368{368{

369 "name": "plugin-name",369 "name": "plugin-name",

370 "displayName": "Plugin Name",

370 "version": "1.2.0",371 "version": "1.2.0",

371 "description": "간단한 플러그인 설명",372 "description": "간단한 플러그인 설명",

372 "author": {373 "author": {

409### 메타데이터 필드410### 메타데이터 필드

410 411 

411| 필드 | 타입 | 설명 | 예시 |412| 필드 | 타입 | 설명 | 예시 |

412| :------------ | :----- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :---------------------------------------------------------------- |413| :------------ | :----- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | :---------------------------------------------------------------- |

413| `$schema` | string | 편집기 자동 완성 및 검증을 위한 JSON Schema URL. Claude Code는 로드 시 이 필드를 무시합니다. | `"https://json.schemastore.org/claude-code-plugin-manifest.json"` |414| `$schema` | string | 편집기 자동 완성 및 검증을 위한 JSON Schema URL. Claude Code는 로드 시 이 필드를 무시합니다. | `"https://json.schemastore.org/claude-code-plugin-manifest.json"` |

414| `version` | string | 선택사항. 의미 있는 버전. 이를 설정하면 플러그인이 해당 버전 문자열로 고정되므로 사용자는 버전을 올릴 때만 업데이트를 받습니다. 생략하면 Claude Code는 git 커밋 SHA로 폴백되므로 모든 커밋이 새 버전으로 취급됩니다. 마켓플레이스 항목에도 설정된 경우 `plugin.json`이 우선합니다. [버전 관리](#version-management)를 참조하세요. | `"2.1.0"` |415| `displayName` | string | {/* min-version: 2.1.143 */}`/plugin` 선택기 및 기타 UI 표면에 표시되는 사람이 읽을 수 있는 이름입니다. 생략하면 `name`으로 폴백됩니다. `name`과 달리 공백과 모든 대소문자를 포함할 수 있습니다. 네임스페이싱 또는 조회에 사용되지 않습니다. Claude Code v2.1.143 이상이 필요합니다. | `"Deployment Tools"` |

416| `version` | string | 선택사항. 의미 있는 버전입니다. 이를 설정하면 플러그인이 해당 버전 문자열로 고정되므로 사용자는 버전을 올릴 때만 업데이트를 받습니다. 생략하면 Claude Code는 git 커밋 SHA로 폴백되므로 모든 커밋이 새 버전으로 취급됩니다. 마켓플레이스 항목에도 설정된 경우 `plugin.json`이 우선합니다. [버전 관리](#version-management)를 참조하세요. | `"2.1.0"` |

415| `description` | string | 플러그인 목적에 대한 간단한 설명 | `"배포 자동화 도구"` |417| `description` | string | 플러그인 목적에 대한 간단한 설명 | `"배포 자동화 도구"` |

416| `author` | object | 작성자 정보 | `{"name": "Dev Team", "email": "dev@company.com"}` |418| `author` | object | 작성자 정보 | `{"name": "Dev Team", "email": "dev@company.com"}` |

417| `homepage` | string | 문서 URL | `"https://docs.example.com"` |419| `homepage` | string | 문서 URL | `"https://docs.example.com"` |

525* 여러 경로를 배열로 지정할 수 있습니다.527* 여러 경로를 배열로 지정할 수 있습니다.

526* skill 경로가 `SKILL.md`를 직접 포함하는 디렉토리를 가리킬 때 (예: 플러그인 루트를 가리키는 `"skills": ["./"]`), frontmatter의 `name` 필드가 skill의 호출 이름을 결정합니다. 이는 설치 디렉토리와 관계없이 안정적인 이름을 제공합니다. `name`이 frontmatter에 설정되지 않으면 디렉토리 basename이 폴백으로 사용됩니다.528* skill 경로가 `SKILL.md`를 직접 포함하는 디렉토리를 가리킬 때 (예: 플러그인 루트를 가리키는 `"skills": ["./"]`), frontmatter의 `name` 필드가 skill의 호출 이름을 결정합니다. 이는 설치 디렉토리와 관계없이 안정적인 이름을 제공합니다. `name`이 frontmatter에 설정되지 않으면 디렉토리 basename이 폴백으로 사용됩니다.

527 529 

530플러그인이 루트에 `SKILL.md`를 가지고 있고, `skills/` 서브디렉토리가 없으며, `skills` 매니페스트 필드가 없으면 Claude Code v2.1.142 이상에서 자동으로 단일 skill 플러그인으로 로드됩니다. 이 레이아웃에 대해 `plugin.json`에서 `"skills": ["./"]`를 설정할 필요가 없습니다. skill의 호출 이름은 위와 동일한 규칙을 따릅니다: frontmatter `name` 필드 또는 디렉토리 basename을 폴백으로 사용합니다.

531 

528**경로 예시**:532**경로 예시**:

529 533 

530```json theme={null}534```json theme={null}

814 818 

815### plugin enable819### plugin enable

816 820 

817비활성화된 플러그인을 활성화합니다.821비활성화된 플러그인을 활성화합니다. 플러그인이 [종속성](/ko/plugin-dependencies)을 선언하면 Claude Code는 동일한 범위에서 이들을 전이적으로 활성화하며, 종속성이 설치되지 않으면 명령어가 실패합니다.

818 822 

819```bash theme={null}823```bash theme={null}

820claude plugin enable <plugin> [options]824claude plugin enable <plugin> [options]

833 837 

834### plugin disable838### plugin disable

835 839 

836플러그인을 제거하지 않고 비활성화합니다.840플러그인을 제거하지 않고 비활성화합니다. 다른 활성화된 플러그인이 대상에 [종속되어](/ko/plugin-dependencies#enable-or-disable-a-plugin-with-dependencies) 있으면 실패합니다. 오류 메시지에는 먼저 모든 종속 플러그인을 비활성화하는 연쇄 명령어가 포함됩니다.

837 841 

838```bash theme={null}842```bash theme={null}

839claude plugin disable <plugin> [options]843claude plugin disable <plugin> [options]

889 893 

890### plugin details894### plugin details

891 895 

892플러그인의 컴포넌트 인벤토리 및 예상 토큰 비용을 표시합니다. 출력은 플러그인이 기여하는 모든 컴포넌트를 Skills(스킬 및 명령어), Agents, Hooks 및 MCP 서버로 그룹화하여 나열하며, 각 세션에 추가되는 토큰 수의 추정치를 함께 표시합니다.896플러그인의 컴포넌트 인벤토리 및 예상 토큰 비용을 표시합니다. 출력은 플러그인이 기여하는 모든 컴포넌트를 Skills, Agents, Hooks, MCP 서버 및 LSP 서버로 그룹화하여 나열하며, 각 세션에 추가되는 토큰 수의 추정치를 함께 표시합니다. Skills 그룹에는 `skills/` 및 `commands/` 항목이 모두 포함됩니다.

893 897 

894```bash theme={null}898```bash theme={null}

895claude plugin details <name>899claude plugin details <name>

922 Agents (0)926 Agents (0)