SpyBara
Go Premium

Documentation 2026-11-09 23:02 UTC to 2026-11-10 21:57 UTC

81 files changed +1,561 −1,258. View all changes and history on the product overview
2026
Thu 12 21:00 Wed 11 22:59 Tue 10 21:57 Mon 9 23:02 Sun 8 22:58 Sat 7 23:58 Fri 6 23:01 Thu 5 23:03 Wed 4 23:59 Tue 3 23:58 Mon 2 23:57 Sun 1 23:57

advisor.md +1 −1

Details

160* **API 청구**: 조언자 토큰에 대해 조언자 모델의 입력 및 출력 요금을 지불합니다160* **API 청구**: 조언자 토큰에 대해 조언자 모델의 입력 및 출력 요금을 지불합니다

161* **구독 계획**: 조언자 사용은 계획의 사용 한도에 포함되며, Fable 조언자가 Fable 사용이 하는 계획에서 [사용 크레딧](https://code.claude.com/docs/ko/model-config.md#fable-and-usage-credits)으로 청구되는 경우는 예외입니다161* **구독 계획**: 조언자 사용은 계획의 사용 한도에 포함되며, Fable 조언자가 Fable 사용이 하는 계획에서 [사용 크레딧](https://code.claude.com/docs/ko/model-config.md#fable-and-usage-credits)으로 청구되는 경우는 예외입니다

162 162 

163계정에 사용 크레딧 동의가 필요한 경우 Fable 조언자는 동의를 제공하기 전까지 비용이 청구되지 않습니다. Claude Code는 그때까지 [선택을 적용하지 않기](#fable-advisor-and-usage-credits) 때문입니다.163Fable 조언자가 사용량 크레딧과 함께 작동하는 방식은 [Fable 조언자 및 사용량 크레딧](#fable-advisor-and-usage-credits)을 참고하세요.

164 164 

165Claude는 모든 턴이 아닌 결정 지점에서 조언자를 호출하므로 더 빠른 주 모델을 더 강력한 조언자와 쌍으로 만드는 것이 일반적으로 전체 강력한 모델을 실행하는 것보다 비용이 적습니다. 조언자 사용은 [`/usage`](https://code.claude.com/docs/ko/costs#track-your-costs)에 표시된 세션 합계에 포함됩니다.165Claude는 모든 턴이 아닌 결정 지점에서 조언자를 호출하므로 더 빠른 주 모델을 더 강력한 조언자와 쌍으로 만드는 것이 일반적으로 전체 강력한 모델을 실행하는 것보다 비용이 적습니다. 조언자 사용은 [`/usage`](https://code.claude.com/docs/ko/costs#track-your-costs)에 표시된 세션 합계에 포함됩니다.

166 166 

Details

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

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

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

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

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

252 252 

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

Details

1858 1858 

1859### `TaskStartedMessage`1859### `TaskStartedMessage`

1860 1860 

1861백그라운드 작업이 시작될 때 발생합니다. 백그라운드 작업은 메인 턴 밖에서 추적되는 모든 것으로, 백그라운드로 실행된 Bash 명령, [Monitor](#monitor) 감시, Agent 도구로 생성된 서브에이전트, 원격 에이전트 등이 있습니다. `task_type` 필드로 어떤 종류인지 알 수 있습니다. 이 이름은 `Task`에서 `Agent`로의 도구 이름 변경과는 관련이 없습니다.1861백그라운드 작업이 시작될 때 발생합니다. 백그라운드 작업은 메인 턴 밖에서 추적되는 모든 것으로, 백그라운드로 실행된 Bash 명령, [Monitor](#monitor) 감시, Agent 도구로 생성된 서브에이전트, 원격 에이전트 등이 있습니다. 이 이름은 `Task`에서 `Agent`로의 도구 이름 변경과는 관련이 없습니다.

1862 1862 

1863```python theme={null}1863```python theme={null}

1864@dataclass1864@dataclass

1878| `uuid` | `str` | 고유 메시지 식별자 |1878| `uuid` | `str` | 고유 메시지 식별자 |

1879| `session_id` | `str` | 세션 식별자 |1879| `session_id` | `str` | 세션 식별자 |

1880| `tool_use_id` | `str \| None` | 연관된 도구 사용 ID |1880| `tool_use_id` | `str \| None` | 연관된 도구 사용 ID |

1881| `task_type` | `str \| None` | 백그라운드 작업의 종류: 백그라운드 Bash 및 Monitor 감시의 경우 `"local_bash"`, `"local_agent"`, 또는 `"remote_agent"` |1881| `task_type` | `str \| None` | 백그라운드 작업의 종류로, 백그라운드 Bash 및 Monitor 감시의 경우 `"local_bash"`, 서브에이전트의 경우 `"local_agent"`, [백그라운드 MCP 도구 호출](https://code.claude.com/docs/ko/mcp.md#automatic-backgrounding-of-long-tool-calls)의 경우 `"mcp_task"`, 또는 `"remote_agent"` 등이 있습니다 |

1882 1882 

1883### `TaskUsage`1883### `TaskUsage`

1884 1884 

Details

10 10 

11완전한 타입 안전성을 위해 [Zod](#type-safe-schemas-with-zod-and-pydantic)(TypeScript) 또는 [Pydantic](#type-safe-schemas-with-zod-and-pydantic)(Python)을 사용하여 스키마를 정의하고 강타입 객체를 반환받습니다.11완전한 타입 안전성을 위해 [Zod](#type-safe-schemas-with-zod-and-pydantic)(TypeScript) 또는 [Pydantic](#type-safe-schemas-with-zod-and-pydantic)(Python)을 사용하여 스키마를 정의하고 강타입 객체를 반환받습니다.

12 12 

13## 구조화된 출력이 필요한 이유?13## 구조화된 출력을 사용하는 이유

14 14 

15에이전트는 기본적으로 자유 형식 텍스트를 반환하므로 채팅에는 적합하지만 출력을 프로그래밍 방식으로 사용해야 할 때는 적합하지 않습니다. 구조화된 출력은 애플리케이션 로직, 데이터베이스 또는 UI 컴포넌트에 직접 전달할 수 있는 타입이 지정된 데이터를 제공합니다.15에이전트는 기본적으로 자유 형식 텍스트를 반환합니다. 이는 채팅에는 적합하지만 출력을 프로그래밍 방식으로 사용해야 하는 경우에는 적합하지 않습니다. 구조화된 출력을 사용하면 애플리케이션 로직, 데이터베이스 또는 UI 컴포넌트에 직접 전달할 수 있는 타입이 지정된 데이터를 얻을 수 있습니다.

16 16 

17에이전트가 웹을 검색하고 레시피를 가져오는 레시피 앱을 생각해 봅시다. 구조화된 출력이 없으면 직접 파싱해야 하는 자유 형식 텍스트를 얻습니다. 구조화된 출력을 사용하면 원하는 형태를 정의하고 앱에서 직접 사용할 수 있는 타입이 지정된 데이터를 얻습니다.17에이전트가 웹을 검색하여 레시피를 가져오는 레시피 앱을 예로 들어 보겠습니다. 구조화된 출력이 없으면 직접 파싱해야 하는 자유 형식 텍스트를 받게 됩니다. 구조화된 출력을 사용하면 원하는 형태를 정의하고 앱에서 바로 사용할 수 있는 타입이 지정된 데이터를 받을 수 있습니다.

18 18 

19> [accordion] 구조화된 출력 없음19> [accordion] 구조화된 출력 없이

20>20>

21> ```text theme={null}21> ```text theme={null}

22> 여기 클래식 초콜릿 칩 쿠키 레시피입니다!22> Here's a classic chocolate chip cookie recipe!

23>23>

24> **초콜릿 칩 쿠키**24> **Chocolate Chip Cookies**

25> 준비 시간: 15분 | 조리 시간: 10분25> Prep time: 15 minutes | Cook time: 10 minutes

26>26>

27> 재료:27> Ingredients:

28> - 2 1/4컵 다목적 밀가루28> - 2 1/4 cups all-purpose flour

29> - 1컵 버터, 부드러워진 상태29> - 1 cup butter, softened

30> ...30> ...

31> ```31> ```

32>32>

33> 이를 앱에서 사용하려면 제목을 파싱하고, "15분"을 숫자로 변환하고, 재료와 지시사항을 분리하고, 응답 전체에서 일관되지 않은 형식을 처리해야 합니다.33> 이를 앱에서 사용하려면 제목을 파싱하고, "15 minutes"를 숫자로 변환하고, 재료와 조리 방법을 분리하고, 응답마다 일관되지 않은 형식을 처리해야 합니다.

34 34 

35> [accordion] 구조화된 출력 포함35> [accordion] 구조화된 출력 사용

36>36>

37> ```jsonc theme={null}37> ```jsonc theme={null}

38> {38> {

39> "name": "초콜릿 칩 쿠키",39> "name": "Chocolate Chip Cookies",

40> "prep_time_minutes": 15,40> "prep_time_minutes": 15,

41> "cook_time_minutes": 10,41> "cook_time_minutes": 10,

42> "ingredients": [42> "ingredients": [

43> { "item": "다목적 밀가루", "amount": 2.25, "unit": "컵" },43> { "item": "all-purpose flour", "amount": 2.25, "unit": "cups" },

44> { "item": "버터, 부드러워진 상태", "amount": 1, "unit": "컵" }44> { "item": "butter, softened", "amount": 1, "unit": "cup" }

45> // ...45> // ...

46> ],46> ],

47> "steps": ["오븐을 375°F로 예열하기", "버터와 설탕 섞기" /* ... */]47> "steps": ["Preheat oven to 375°F", "Cream butter and sugar" /* ... */]

48> }48> }

49> ```49> ```

50>50>

51> UI에서 직접 사용할 수 있는 타입이 지정된 데이터입니다.51> UI에서 바로 사용할 수 있는 타입이 지정된 데이터입니다.

52 52 

53## 빠른 시작53## 빠른 시작

54 54 

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

56 56 

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

58 58 

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

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

61 61 

62// 반환받을 데이터의 형태 정의62// 반환받을 데이터의 형태를 정의합니다

63const schema = {63const schema = {

64 type: "object",64 type: "object",

65 properties: {65 properties: {

72 72 

73try {73try {

74 for await (const message of query({74 for await (const message of query({

75 prompt: "Anthropic을 조사하고 주요 회사 정보를 제공하세요",75 prompt: "Research Anthropic and provide key company information",

76 options: {76 options: {

77 outputFormat: {77 outputFormat: {

78 type: "json_schema",78 type: "json_schema",

80 }80 }

81 }81 }

82 })) {82 })) {

83 // 결과 메시지에는 검증된 데이터가 포함된 structured_output이 포함됩니다83 // 결과 메시지에는 검증된 데이터가 담긴 structured_output이 포함됩니다

84 if (message.type === "result" && message.subtype === "success" && message.structured_output) {84 if (message.type === "result" && message.subtype === "success" && !message.is_error && message.structured_output) {

85 console.log(message.structured_output);85 console.log(message.structured_output);

86 // { company_name: "Anthropic", founded_year: 2021, headquarters: "San Francisco, CA" }86 // { company_name: "Anthropic", founded_year: 2021, headquarters: "San Francisco, CA" }

87 }87 }

88 }88 }

89} catch (error) {89} catch (error) {

90 // 단일 쿼리 query()는 오류 결과(예: error_max_structured_output_retries)를 생성한 후 throw합니다.90 // 단일 실행 query()는 error_max_structured_output_retries와 같은

91 // 오류 처리 섹션을 참조하세요.91 // 오류 결과를 반환한 후 예외를 발생시킵니다. 오류 처리 섹션을 참조하세요.

92 console.error(`세션이 오류로 종료되었습니다: ${error}`);92 console.error(`Session ended with an error: ${error}`);

93}93}

94```94```

95 95 

97import asyncio97import asyncio

98from claude_agent_sdk import query, ClaudeAgentOptions, ResultMessage98from claude_agent_sdk import query, ClaudeAgentOptions, ResultMessage

99 99 

100# 반환받을 데이터의 형태 정의100# 반환받을 데이터의 형태를 정의합니다

101schema = {101schema = {

102 "type": "object",102 "type": "object",

103 "properties": {103 "properties": {

112async def main():112async def main():

113 try:113 try:

114 async for message in query(114 async for message in query(

115 prompt="Anthropic을 조사하고 주요 회사 정보를 제공하세요",115 prompt="Research Anthropic and provide key company information",

116 options=ClaudeAgentOptions(116 options=ClaudeAgentOptions(

117 output_format={"type": "json_schema", "schema": schema}117 output_format={"type": "json_schema", "schema": schema}

118 ),118 ),

119 ):119 ):

120 # 결과 메시지에는 검증된 데이터가 포함된 structured_output이 포함됩니다120 # 결과 메시지에는 검증된 데이터가 담긴 structured_output이 포함됩니다

121 if isinstance(message, ResultMessage) and message.structured_output:121 if (

122 isinstance(message, ResultMessage)

123 and not message.is_error

124 and message.structured_output

125 ):

122 print(message.structured_output)126 print(message.structured_output)

123 # {'company_name': 'Anthropic', 'founded_year': 2021, 'headquarters': 'San Francisco, CA'}127 # {'company_name': 'Anthropic', 'founded_year': 2021, 'headquarters': 'San Francisco, CA'}

124 except Exception as error:128 except Exception as error:

125 # 단일 쿼리 query()는 오류 결과(예: error_max_structured_output_retries)를 생성한 후 raise합니다.129 # 단일 실행 query()는 error_max_structured_output_retries와 같은

126 # 오류 처리 섹션을 참조하세요.130 # 오류 결과를 반환한 후 예외를 발생시킵니다. 오류 처리 섹션을 참조하세요.

127 print(f"세션이 오류로 종료되었습니다: {error}")131 print(f"Session ended with an error: {error}")

128 132 

129 133 

130asyncio.run(main())134asyncio.run(main())

131```135```

132 136 

133## Zod 및 Pydantic을 사용한 타입 안전 스키마137## Zod와 Pydantic을 사용한 타입 안전 스키마

134 138 

135JSON Schema를 직접 작성하는 대신 [Zod](https://zod.dev/)(TypeScript) 또는 [Pydantic](https://docs.pydantic.dev/latest/)(Python)을 사용하여 스키마를 정의할 수 있습니다. 이러한 라이브러리는 JSON Schema를 생성하고 응답을 완전히 타입이 지정된 객체로 파싱하여 자동 완성 및 타입 검사를 통해 코드베이스 전체에서 사용할 수 있습니다.139JSON Schema를 직접 작성하는 대신 [Zod](https://zod.dev/)(TypeScript) 또는 [Pydantic](https://docs.pydantic.dev/latest/)(Python)을 사용하여 스키마를 정의할 수 있습니다. 이러한 라이브러리는 JSON Schema를 자동으로 생성해 주며, 응답을 완전히 타입이 지정된 객체로 파싱하여 자동 완성과 타입 검사를 활용하면서 코드베이스 전체에서 사용할 수 있게 해 줍니다.

136 140 

137아래 예제는 요약, 단계 목록(각각 복잡도 수준 포함) 및 잠재적 위험이 있는 기능 구현 계획에 대한 스키마를 정의합니다. 에이전트는 기능을 계획하고 타입이 지정된 `FeaturePlan` 객체를 반환합니다. 그런 다음 `plan.summary`와 같은 속성에 액세스하고 완전한 타입 안전성으로 `plan.steps`를 반복할 수 있습니다.141아래 예제는 요약, 단계 목록(각 단계에 복잡도 수준 포함), 잠재적 위험 요소로 구성된 기능 구현 계획의 스키마를 정의합니다. 에이전트는 기능을 계획하고 타입이 지정된 `FeaturePlan` 객체를 반환합니다. 이후 완전한 타입 안전성을 유지하면서 `plan.summary`와 같은 속성에 접근하고 `plan.steps`를 순회할 수 있습니다.

138 142 

139SDK는 JSON Schema draft-07로 스키마를 검증하므로 최신 버전을 선언하는 스키마는 거부됩니다. Zod는 기본적으로 draft 2020-12를 대상으로 하므로 스키마를 변환할 때 `target: "draft-7"`을 전달하세요.143SDK는 JSON Schema draft-07로 스키마를 검증하므로, 더 최신 버전을 선언하는 스키마는 거부됩니다. Zod는 기본적으로 draft 2020-12를 대상으로 하므로, 스키마를 변환할 때 `target: "draft-7"`을 전달해야 합니다.

140 144 

141```typescript TypeScript theme={null}145```typescript TypeScript theme={null}

142import { z } from "zod";146import { z } from "zod";

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

144 148 

145// Zod를 사용하여 스키마 정의149// Zod로 스키마 정의

146const FeaturePlan = z.object({150const FeaturePlan = z.object({

147 feature_name: z.string(),151 feature_name: z.string(),

148 summary: z.string(),152 summary: z.string(),

158 162 

159type FeaturePlan = z.infer<typeof FeaturePlan>;163type FeaturePlan = z.infer<typeof FeaturePlan>;

160 164 

161// SDK가 예상하는 draft-07 대상을 사용하여 JSON Schema로 변환165// SDK가 요구하는 draft-07 대상을 사용하여 JSON Schema로 변환

162const schema = z.toJSONSchema(FeaturePlan, { target: "draft-7" });166const schema = z.toJSONSchema(FeaturePlan, { target: "draft-7" });

163 167 

164// 쿼리에서 사용168// query에서 사용

165try {169try {

166 for await (const message of query({170 for await (const message of query({

167 prompt:171 prompt:

168 "React 앱에 다크 모드 지원을 추가하는 방법을 계획하세요. 구현 단계로 나누세요.",172 "Plan how to add dark mode support to a React app. Break it into implementation steps.",

169 options: {173 options: {

170 outputFormat: {174 outputFormat: {

171 type: "json_schema",175 type: "json_schema",

173 }177 }

174 }178 }

175 })) {179 })) {

176 if (message.type === "result" && message.subtype === "success" && message.structured_output) {180 if (message.type === "result" && message.subtype === "success" && !message.is_error && message.structured_output) {

177 // 검증하고 완전히 타입이 지정된 결과 얻기181 // 검증 후 완전히 타입이 지정된 결과 가져오기

178 const parsed = FeaturePlan.safeParse(message.structured_output);182 const parsed = FeaturePlan.safeParse(message.structured_output);

179 if (parsed.success) {183 if (parsed.success) {

180 const plan: FeaturePlan = parsed.data;184 const plan: FeaturePlan = parsed.data;

181 console.log(`기능: ${plan.feature_name}`);185 console.log(`Feature: ${plan.feature_name}`);

182 console.log(`요약: ${plan.summary}`);186 console.log(`Summary: ${plan.summary}`);

183 plan.steps.forEach((step) => {187 plan.steps.forEach((step) => {

184 console.log(`${step.step_number}. [${step.estimated_complexity}] ${step.description}`);188 console.log(`${step.step_number}. [${step.estimated_complexity}] ${step.description}`);

185 });189 });

187 }191 }

188 }192 }

189} catch (error) {193} catch (error) {

190 // 단일 쿼리()는 error_max_structured_output_retries와 같은 오류 결과를 생성한 후 throw합니다.194 // 단일 실행 query()는 error_max_structured_output_retries와 같은 오류 결과를

191 // 오류 처리 섹션을 참조하세요.195 // 반환한 후 예외를 발생시킵니다. 오류 처리 섹션을 참조하세요.

192 console.error(`세션이 오류로 종료되었습니다: ${error}`);196 console.error(`Session ended with an error: ${error}`);

193}197}

194```198```

195 199 

215async def main():219async def main():

216 try:220 try:

217 async for message in query(221 async for message in query(

218 prompt="React 앱에 다크 모드 지원을 추가하는 방법을 계획하세요. 구현 단계로 나누세요.",222 prompt="Plan how to add dark mode support to a React app. Break it into implementation steps.",

219 options=ClaudeAgentOptions(223 options=ClaudeAgentOptions(

220 output_format={224 output_format={

221 "type": "json_schema",225 "type": "json_schema",

223 }227 }

224 ),228 ),

225 ):229 ):

226 if isinstance(message, ResultMessage) and message.structured_output:230 if (

227 # 검증하고 완전히 타입이 지정된 결과 얻기231 isinstance(message, ResultMessage)

232 and not message.is_error

233 and message.structured_output

234 ):

235 # 검증 후 완전히 타입이 지정된 결과 가져오기

228 plan = FeaturePlan.model_validate(message.structured_output)236 plan = FeaturePlan.model_validate(message.structured_output)

229 print(f"기능: {plan.feature_name}")237 print(f"Feature: {plan.feature_name}")

230 print(f"요약: {plan.summary}")238 print(f"Summary: {plan.summary}")

231 for step in plan.steps:239 for step in plan.steps:

232 print(240 print(

233 f"{step.step_number}. [{step.estimated_complexity}] {step.description}"241 f"{step.step_number}. [{step.estimated_complexity}] {step.description}"

234 )242 )

235 except Exception as error:243 except Exception as error:

236 # 단일 쿼리()는 error_max_structured_output_retries와 같은 오류 결과를 생성한 후 raise합니다.244 # 단일 실행 query()는 error_max_structured_output_retries와 같은 오류 결과를

237 # 오류 처리 섹션을 참조하세요.245 # 반환한 후 예외를 발생시킵니다. 오류 처리 섹션을 참조하세요.

238 print(f"세션이 오류로 종료되었습니다: {error}")246 print(f"Session ended with an error: {error}")

239 247 

240 248 

241asyncio.run(main())249asyncio.run(main())

256 264 

257## 예제: TODO 추적 에이전트265## 예제: TODO 추적 에이전트

258 266 

259이 예제는 구조화된 출력이 다중 단계 도구 사용과 어떻게 작동하는지 보여줍니다. 에이전트는 코드베이스에서 TODO 주석을 찾은 다음 각각에 대한 git blame 정보를 조회해야 합니다. 실행 중에 사용할 도구(검색용 Grep, git 명령 실행용 Bash)를 자율적으로 결정하고 결과를 단일 구조화된 응답으로 결합합니다.267이 예제는 구조화된 출력이 다단계 도구 사용과 함께 어떻게 작동하는지 보여 줍니다. 에이전트는 코드베이스에서 TODO 주석을 찾은 다음, 각 주석에 대한 git blame 정보를 조회해야 합니다. 에이전트는 사용할 도구(검색에는 Grep, git 명령 실행에는 Bash)를 자율적으로 결정하고, 그 결과를 하나의 구조화된 응답으로 결합합니다.

260 268 

261스키마에는 모든 파일에 대해 git blame 정보를 사용할 수 없을 수 있으므로 선택적 필드(`author` 및 `date`)가 포함됩니다. 에이전트는 찾을 수 있는 것을 채우고 나머지는 생략합니다.269모든 파일에서 git blame 정보를 사용할 수 있는 것은 아니므로 스키마에는 선택적 필드(`author` 및 `date`)가 포함되어 있습니다. 에이전트는 찾을 수 있는 정보를 채우고 나머지는 생략합니다.

262 270 

263```typescript TypeScript theme={null}271```typescript TypeScript theme={null}

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

286 required: ["todos", "total_count"]294 required: ["todos", "total_count"]

287};295};

288 296 

289// 에이전트는 Grep을 사용하여 TODO를 찾고, Bash를 사용하여 git blame 정보를 얻습니다297// 에이전트는 Grep으로 TODO를 찾고, Bash로 git blame 정보를 가져옵니다

290try {298try {

291 for await (const message of query({299 for await (const message of query({

292 prompt: "이 코드베이스에서 모든 TODO 주석을 찾고 누가 추가했는지 식별하세요",300 prompt: "Find all TODO comments in this codebase and identify who added them",

293 options: {301 options: {

294 outputFormat: {302 outputFormat: {

295 type: "json_schema",303 type: "json_schema",

297 }305 }

298 }306 }

299 })) {307 })) {

300 if (message.type === "result" && message.subtype === "success" && message.structured_output) {308 if (message.type === "result" && message.subtype === "success" && !message.is_error && message.structured_output) {

301 const data = message.structured_output as { total_count: number; todos: Array<{ file: string; line: number; text: string; author?: string; date?: string }> };309 const data = message.structured_output as { total_count: number; todos: Array<{ file: string; line: number; text: string; author?: string; date?: string }> };

302 console.log(`${data.total_count}개의 TODO를 찾았습니다`);310 console.log(`Found ${data.total_count} TODOs`);

303 data.todos.forEach((todo) => {311 data.todos.forEach((todo) => {

304 console.log(`${todo.file}:${todo.line} - ${todo.text}`);312 console.log(`${todo.file}:${todo.line} - ${todo.text}`);

305 if (todo.author) {313 if (todo.author) {

306 console.log(` ${todo.author}가 ${todo.date}에 추가함`);314 console.log(` Added by ${todo.author} on ${todo.date}`);

307 }315 }

308 });316 });

309 }317 }

310 }318 }

311} catch (error) {319} catch (error) {

312 // 단일 쿼리 query()는 오류 결과(예: error_max_structured_output_retries)를 생성한 후 throw합니다. 오류 처리 섹션을 참조하세요.320 // 단일 실행 query()는 error_max_structured_output_retries와 같은 오류 결과를

313 console.error(`세션이 오류로 종료되었습니다: ${error}`);321 // 반환한 후 예외를 발생시킵니다. 오류 처리 섹션을 참조하세요.

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

314}323}

315```324```

316 325 

343 352 

344 353 

345async def main():354async def main():

346 # 에이전트는 Grep을 사용하여 TODO를 찾고, Bash를 사용하여 git blame 정보를 얻습니다355 # 에이전트는 Grep으로 TODO를 찾고, Bash로 git blame 정보를 가져옵니다

347 try:356 try:

348 async for message in query(357 async for message in query(

349 prompt="이 코드베이스에서 모든 TODO 주석을 찾고 누가 추가했는지 식별하세요",358 prompt="Find all TODO comments in this codebase and identify who added them",

350 options=ClaudeAgentOptions(359 options=ClaudeAgentOptions(

351 output_format={"type": "json_schema", "schema": todo_schema}360 output_format={"type": "json_schema", "schema": todo_schema}

352 ),361 ),

353 ):362 ):

354 if isinstance(message, ResultMessage) and message.structured_output:363 if (

364 isinstance(message, ResultMessage)

365 and not message.is_error

366 and message.structured_output

367 ):

355 data = message.structured_output368 data = message.structured_output

356 print(f"{data['total_count']}개의 TODO를 찾았습니다")369 print(f"Found {data['total_count']} TODOs")

357 for todo in data["todos"]:370 for todo in data["todos"]:

358 print(f"{todo['file']}:{todo['line']} - {todo['text']}")371 print(f"{todo['file']}:{todo['line']} - {todo['text']}")

359 if "author" in todo:372 if "author" in todo:

360 print(f" {todo['author']}가 {todo['date']}에 추가함")373 print(f" Added by {todo['author']} on {todo['date']}")

361 except Exception as error:374 except Exception as error:

362 # 단일 쿼리 query()는 오류 결과(예: error_max_structured_output_retries)를 생성한 후 raise합니다. 오류 처리 섹션을 참조하세요.375 # 단일 실행 query()는 error_max_structured_output_retries와 같은 오류 결과를

363 print(f"세션이 오류로 종료되었습니다: {error}")376 # 반환한 후 예외를 발생시킵니다. 오류 처리 섹션을 참조하세요.

377 print(f"Session ended with an error: {error}")

364 378 

365 379 

366asyncio.run(main())380asyncio.run(main())

379 393 

380## 오류 처리394## 오류 처리

381 395 

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

383 397 

384오류가 발생하면 결과 메시지에 무엇이 잘못되었는지 나타내는 `subtype`이 있습니다:398결과 메시지의 `subtype`을 확인합니다.

385 399 

386| Subtype | 의미 |400| Subtype | 의미 |

387| - | - |401| - | - |

388| `success` | 출력이 성공적으로 생성되고 검증됨 |402| `success` | 실행이 오류 subtype 없이 종료되었습니다 |

389| `error_max_structured_output_retries` | 여러 시도 후 유효한 출력이 남지 않음(검증 실패 또는 성공적인 재시도가 없는 모델 폴백 취소) |403| `error_max_structured_output_retries` | 여러 번 시도한 후에도 유효한 출력이 남지 않았습니다(유효성 검사 실패 또는 성공한 재시도가 없는 모델 폴백 철회) |

390 404 

391결과는 `subtype`이 `success`이지만 `structured_output` 값이 없는 경우로도 종료될 수 있습니다. 예를 들어 실행이 에이전트가 구조화된 출력을 생성하지 않고 완료될 때입니다. 이 경우도 실패로 처리하십시오. 문제 해결 항목 [structured\_output is None but the result says success](https://code.claude.com/docs/ko/agent-sdk/troubleshooting.md#structured_output-is-none-but-the-result-says-success)에서 이 경우를 다룹니다. 아래 예제는 `subtype`이 `success`이고 `structured_output`이 있을 때만 결과를 성공으로 처리하며, 다른 모든 결과는 실패로 처리합니다:405`success` subtype만으로는 실행이 답변을 생성했다는 의미가 아닙니다. 결과의 `is_error`가 `true`이거나 `structured_output`이 없는 경우 해당 결과를 실패로 처리하십시오.

406 

407* **결과의 `is_error`가 `true`인 경우**: 예를 들어 최종 모델 요청이 API 오류 또는 거부로 종료된 경우입니다. 이러한 결과의 `structured_output` 값은 사용하지 마십시오.

408* **`structured_output`이 없는 경우**: 원인을 찾으려면 [structured\_output이 None이지만 결과가 success로 표시되는 경우](https://code.claude.com/docs/ko/agent-sdk/troubleshooting.md#structured_output-is-none-but-the-result-says-success)를 참조하십시오.

409 

410아래 예제는 이러한 검사를 적용합니다.

392 411 

393```typescript TypeScript theme={null}412```typescript TypeScript theme={null}

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

413 }432 }

414 })) {433 })) {

415 if (msg.type === "result") {434 if (msg.type === "result") {

416 if (msg.subtype === "success" && msg.structured_output) {435 if (msg.subtype === "success" && !msg.is_error && msg.structured_output) {

417 // 검증된 출력 사용436 // 유효성 검사를 통과한 출력을 사용합니다

418 console.log(msg.structured_output);437 console.log(msg.structured_output);

419 } else if (msg.subtype === "error_max_structured_output_retries") {438 } else if (msg.subtype === "error_max_structured_output_retries") {

420 console.error("유효한 출력을 생성할 수 없습니다");439 console.error("Could not produce valid output");

421 } else {440 } else {

422 console.error("구조화된 출력 없이 실행이 종료되었습니다");441 console.error("Run ended with an error or without a structured output");

423 }442 }

424 }443 }

425 }444 }

426} catch (error) {445} catch (error) {

427 // 단일 query()는 오류 결과를 생성한 후 throw합니다. 실패가446 // 단일 실행 query()는 오류 결과를 생성한 후 예외를 발생시킵니다. 실패가

428 // 오류 결과였다면 위의 오류 subtype 분기가 이미 실행되었습니다.447 // 오류 결과였다면 위의 오류 subtype 분기가 이미 실행되었으며,

429 // 연결 또는 프로세스 실패는 결과 메시지를 생성하지 않습니다.448 // 연결 또는 프로세스 실패는 결과 메시지를 생성하지 않습니다.

430 console.log(`세션이 오류로 종료되었습니다: ${error}`);449 console.log(`Session ended with an error: ${error}`);

431}450}

432```451```

433 452 

454 ),473 ),

455 ):474 ):

456 if isinstance(message, ResultMessage):475 if isinstance(message, ResultMessage):

457 if message.subtype == "success" and message.structured_output:476 if (

458 # 검증된 출력 사용477 message.subtype == "success"

478 and not message.is_error

479 and message.structured_output

480 ):

481 # 유효성 검사를 통과한 출력을 사용합니다

459 print(message.structured_output)482 print(message.structured_output)

460 elif message.subtype == "error_max_structured_output_retries":483 elif message.subtype == "error_max_structured_output_retries":

461 print("유효한 출력을 생성할 수 없습니다")484 print("Could not produce valid output")

462 else:485 else:

463 print("구조화된 출력 없이 실행이 종료되었습니다")486 print("Run ended with an error or without a structured output")

464 except Exception as error:487 except Exception as error:

465 # 단일 query()는 오류 결과를 생성한 후 raise합니다. 실패가488 # 단일 실행 query()는 오류 결과를 생성한 후 예외를 발생시킵니다. 실패가

466 # 오류 결과였다면 위의 오류 subtype 분기가 이미 실행되었습니다.489 # 오류 결과였다면 위의 오류 subtype 분기가 이미 실행되었으며,

467 # 연결 또는 프로세스 실패는 결과 메시지를 생성하지 않습니다.490 # 연결 또는 프로세스 실패는 결과 메시지를 생성하지 않습니다.

468 print(f"세션이 오류로 종료되었습니다: {error}")491 print(f"Session ended with an error: {error}")

469 492 

470 493 

471asyncio.run(main())494asyncio.run(main())

472```495```

473 496 

474**오류 방지 팁:**497**오류를 방지하기 위한 팁:**

475 498 

476* **스키마를 집중적으로 유지하십시오.** 많은 필수 필드가 있는 깊게 중첩된 스키마는 만족하기 어렵습니다. 간단하게 시작하고 필요에 따라 복잡성을 추가하십시오.499* **스키마를 간결하게 유지하십시오.** 필수 필드가 많고 깊게 중첩된 스키마는 충족하기가 더 어렵습니다. 단순하게 시작하고 필요에 따라 복잡성을 추가하십시오.

477* **스키마를 작업과 일치시키십시오.** 작업에 스키마가 요구하는 모든 정보가 없을 수 있으면 해당 필드를 선택적으로 만드십시오.500* **스키마를 작업에 맞추십시오.** 작업에 스키마가 요구하는 모든 정보가 없을 수 있다면 해당 필드를 선택 사항으로 만드십시오.

478* **명확한 프롬프트를 사용하십시오.** 모호한 프롬프트는 에이전트가 생성할 출력을 알기 어렵게 합니다.501* **명확한 프롬프트를 사용하십시오.** 모호한 프롬프트는 에이전트가 어떤 출력을 생성해야 하는지 파악하기 어렵게 만듭니다.

479 502 

480## 관련 리소스503## 관련 리소스

481 504 

Details

142 142 

143결과 메시지는 `subtype: "success"`로 끝날 수 있지만 Python에서 `structured_output`은 `None`이거나 TypeScript에서 `undefined`입니다. 실행이 완료되지만 검증된 출력이 없습니다.143결과 메시지는 `subtype: "success"`로 끝날 수 있지만 Python에서 `structured_output`은 `None`이거나 TypeScript에서 `undefined`입니다. 실행이 완료되지만 검증된 출력이 없습니다.

144 144 

145애플리케이션 코드에서 이 결과를 실패로 취급합니다. `structured_output`을 사용하기 전에 `subtype`이 `success`이고 `structured_output`이 존재하는지 모두 확인합니다. [오류 처리](https://code.claude.com/docs/ko/agent-sdk/structured-outputs.md#error-handling) 섹션은 두 SDK 모두에 대해 이 패턴을 보여줍니다. 그런 다음 다음 원인을 확인합니다.145애플리케이션 코드에서 이 결과를 실패로 취급합니다. [오류 처리](https://code.claude.com/docs/ko/agent-sdk/structured-outputs.md#error-handling) 섹션은 두 SDK 모두에 대해 이 패턴을 보여줍니다. 그런 다음 다음 원인을 확인합니다.

146 146 

147* **Claude가 거부한 요청**: 코드에서 이 경우를 감지하려면 결과 메시지의 `stop_reason`이 `"refusal"`인지 확인합니다. 다음에 시도할 방법은 [Usage Policy refusal](https://code.claude.com/docs/ko/errors.md#usage-policy-refusal)을 참조하세요.147* **Claude가 거부한 요청**: 코드에서 이 경우를 감지하려면 결과 메시지의 `stop_reason`이 `"refusal"`인지 확인합니다. 다음에 시도할 방법은 [Usage Policy refusal](https://code.claude.com/docs/ko/errors.md#usage-policy-refusal)을 참조하세요.

148* **어떤 출력도 만족할 수 없는 스키마**: 예를 들어 `minLength`가 `maxLength`보다 큰 문자열입니다. 올바르다고 생각하는 스키마에서 `structured_output`이 반복적으로 누락되면 서로 모순되는 제약이 있는지 찾아봅니다. 찾지 못한 경우 출력이 검증될 때까지 스키마를 단순화한 다음 제약을 한 번에 하나씩 다시 도입합니다.148* **어떤 출력도 만족할 수 없는 스키마**: 예를 들어 `minLength`가 `maxLength`보다 큰 문자열입니다. 올바르다고 생각하는 스키마에서 `structured_output`이 반복적으로 누락되면 서로 모순되는 제약이 있는지 찾아봅니다. 찾지 못한 경우 출력이 검증될 때까지 스키마를 단순화한 다음 제약을 한 번에 하나씩 다시 도입합니다.

Details

1923| `extra_usage_disabled` | 계정의 사용량 크레딧이 꺼져 있습니다 |1923| `extra_usage_disabled` | 계정의 사용량 크레딧이 꺼져 있습니다 |

1924| `network_error` | [가용성 검사](https://code.claude.com/docs/ko/fast-mode.md#use-fast-mode-behind-proxies-and-llm-gateways)가 `api.anthropic.com`에 연결하지 못했습니다 |1924| `network_error` | [가용성 검사](https://code.claude.com/docs/ko/fast-mode.md#use-fast-mode-behind-proxies-and-llm-gateways)가 `api.anthropic.com`에 연결하지 못했습니다 |

1925| `unknown` | Claude Code가 가용성을 판단하지 못했습니다 |1925| `unknown` | Claude Code가 가용성을 판단하지 못했습니다 |

1926| `not_first_party` | 세션이 Anthropic API 이외의 공급자를 사용합니다 |1926| `not_first_party` | 세션이 빠른 모드를 제공하지 않는 제공자를 사용함 |

1927| `disabled_by_env` | [`CLAUDE_CODE_DISABLE_FAST_MODE`](https://code.claude.com/docs/ko/env-vars)가 설정되어 있습니다 |1927| `disabled_by_env` | [`CLAUDE_CODE_DISABLE_FAST_MODE`](https://code.claude.com/docs/ko/env-vars)가 설정되어 있거나, [Google Cloud의 Agent Platform](https://code.claude.com/docs/ko/fast-mode.md#use-fast-mode-on-agent-platform)에서 모델의 리전이 빠른 모드를 제공하지 않음 |

1928| `model_not_allowed` | 빠른 모드 Opus 모델이 조직의 [`availableModels`](https://code.claude.com/docs/ko/model-config#restrict-model-selection) 허용 목록에 없습니다 |1928| `model_not_allowed` | 빠른 모드 모델이 조직의 [`availableModels`](https://code.claude.com/docs/ko/model-config#restrict-model-selection) 허용 목록에 없거나, 제공자가 세션 모델에 대해 빠른 모드를 거부함 |

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

1930| `pending` | 가용성 검사가 아직 완료되지 않았습니다 |1930| `pending` | 가용성 검사가 아직 완료되지 않았습니다 |

1931 1931 

2007 2007 

2008#### `startup_failure_reason`2008#### `startup_failure_reason`

2009 2009 

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

2011 2011 

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

2013 2013 

5707 5707 

5708### `SDKTaskStartedMessage`5708### `SDKTaskStartedMessage`

5709 5709 

5710작업이 시작될 때 발생합니다. `task_type` 필드는 Bash 명령과 [Monitor](#monitor) 감시의 경우 `"local_bash"`, 서브에이전트의 경우 `"local_agent"`, 또는 `"remote_agent"`입니다.5710작업이 시작될 때 발생합니다. `task_type`은 작업의 종류를 나타내며, Bash 명령과 [Monitor](#monitor) 감시의 경우 `"local_bash"`, 서브에이전트의 경우 `"local_agent"`, [백그라운드 MCP 도구 호출](https://code.claude.com/docs/ko/mcp.md#automatic-backgrounding-of-long-tool-calls)의 경우 `"mcp_task"`, 또는 `"remote_agent"` 등이 있습니다.

5711 5711 

5712```typescript theme={null}5712```typescript theme={null}

5713type SDKTaskStartedMessage = {5713type SDKTaskStartedMessage = {

5916 errorCode?: "credits_required";5916 errorCode?: "credits_required";

5917 canUserPurchaseCredits?: boolean;5917 canUserPurchaseCredits?: boolean;

5918 hasChargeableSavedPaymentMethod?: boolean;5918 hasChargeableSavedPaymentMethod?: boolean;

5919 overageEnabled?: boolean;

5919 };5920 };

5920 uuid: UUID;5921 uuid: UUID;

5921 session_id: string;5922 session_id: string;

5924 5925 

5925`errorCode`가 `"credits_required"`이면 포함된 사용량이 소진된 claude.ai 구독에서 거부된 것이며, 사용자가 사용량 크레딧을 구매할 때까지 세션을 계속할 수 없습니다. `canUserPurchaseCredits`는 인증된 사용자가 계정에 대한 크레딧을 구매할 수 있는지를 나타내고, `hasChargeableSavedPaymentMethod`는 저장된 결제 수단이 등록되어 있는지를 나타냅니다. 크레딧 필요로 인한 거부가 아닌 속도 제한 이벤트에는 세 필드 모두 없습니다. Claude Code v2.1.181 이상이 필요합니다.5926`errorCode`가 `"credits_required"`이면 포함된 사용량이 소진된 claude.ai 구독에서 거부된 것이며, 사용자가 사용량 크레딧을 구매할 때까지 세션을 계속할 수 없습니다. `canUserPurchaseCredits`는 인증된 사용자가 계정에 대한 크레딧을 구매할 수 있는지를 나타내고, `hasChargeableSavedPaymentMethod`는 저장된 결제 수단이 등록되어 있는지를 나타냅니다. 크레딧 필요로 인한 거부가 아닌 속도 제한 이벤트에는 세 필드 모두 없습니다. Claude Code v2.1.181 이상이 필요합니다.

5926 5927 

5928`status`가 `"allowed_warning"`인 플랜 사용 한도 경고에서 `overageEnabled`는 계정에 [사용량 크레딧](https://code.claude.com/docs/ko/costs.md#add-usage-credits-to-your-subscription)이 켜져 있는지를 보고합니다. Claude Code v2.1.295 이상이 필요합니다.

5929 

5927### `SDKLocalCommandOutputMessage`5930### `SDKLocalCommandOutputMessage`

5928 5931 

5929Claude Code는 이 메시지 타입을 내보내지 않습니다. `/context`나 `/usage` 같은 명령을 프롬프트로 보내면 그 출력은 [`SDKAssistantMessage`](#sdkassistantmessage)로 도착합니다.5932Claude Code는 이 메시지 타입을 내보내지 않습니다. `/context`나 `/usage` 같은 명령을 프롬프트로 보내면 그 출력은 [`SDKAssistantMessage`](#sdkassistantmessage)로 도착합니다.

Details

647 647 

648 648 

649def parse_response(response: str, options: list) -> str:649def parse_response(response: str, options: list) -> str:

650 """사용자 입력을 옵션 번호 또는 자유 텍스트로 구문 분석합니다."""650 """Parse user input as option number(s) or free text."""

651 try:651 try:

652 indices = [int(s.strip()) - 1 for s in response.split(",")]652 indices = [int(s.strip()) - 1 for s in response.split(",")]

653 labels = [options[i]["label"] for i in indices if 0 <= i < len(options)]653 labels = [options[i]["label"] for i in indices if 0 <= i < len(options)]

657 657 

658 658 

659async def handle_ask_user_question(input_data: dict) -> PermissionResultAllow:659async def handle_ask_user_question(input_data: dict) -> PermissionResultAllow:

660 """Claude의 질문을 표시하고 사용자 답변을 수집합니다."""660 """Display Claude's questions and collect user answers."""

661 answers = {}661 answers = {}

662 662 

663 for q in input_data.get("questions", []):663 for q in input_data.get("questions", []):

agent-teams.md +13 −13

Details

8 8 

9> [!WARNING]9> [!WARNING]

10>10>

11> 에이전트 팀은 실험적이며 기본적으로 비활성화되어 있습니다. [settings.json](https://code.claude.com/docs/ko/settings.md)이나 환경에 `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1`을 설정하여 활성화합니다. 해당 변수가 없으면 세션 시작 시 팀이 설정되지 않고, 팀 디렉토리가 작성되지 않으며, Claude가 팀원을 생성하거나 제안하지 않습니다. 에이전트 팀은 세션 재개, 작업 조율, 종료 동작 관련 [알려진 제한 사항](#limitations)이 있습니다.11> 에이전트 팀은 실험적이며 기본적으로 비활성화되어 있습니다. [settings.json](https://code.claude.com/docs/ko/settings.md)이나 환경에 `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1`을 설정하여 활성화합니다. 에이전트 팀은 세션 재개, 작업 조율, 종료 동작 관련 [알려진 제한 사항](#limitations)이 있습니다.

12 12 

13에이전트 팀을 사용하면 함께 작동하는 여러 Claude Code 인스턴스를 조율할 수 있습니다. 한 세션이 팀 리더 역할을 하여 작업을 조율하고, 작업을 할당하며, 결과를 종합합니다. 팀원들은 독립적으로 작동하며, 각각 자신의 컨텍스트 윈도우에서 작동하고, 서로 직접 통신합니다. 리더를 거치지 않고 개별 팀원과 직접 상호작용할 수도 있습니다.13에이전트 팀을 사용하면 함께 작동하는 여러 Claude Code 인스턴스를 조율할 수 있습니다. 한 세션이 팀 리더 역할을 하여 작업을 조율하고, 작업을 할당하며, 결과를 종합합니다. 팀원들은 독립적으로 작동하며, 각각 자신의 컨텍스트 윈도우에서 작동하고, 서로 직접 통신합니다. 리더를 거치지 않고 개별 팀원과 직접 상호작용할 수도 있습니다.

14 14 

225 225 

226### Claude가 에이전트 팀을 시작하는 방법226### Claude가 에이전트 팀을 시작하는 방법

227 227 

228팀을 시작하려면 Claude에게 팀원을 요청합니다. Claude는 에이전트 팀이 활성화되어 있는 동안 [Agent 도구](https://code.claude.com/docs/ko/tools-reference.md)를 [`name`](https://code.claude.com/docs/ko/sub-agents#subagent-names)과 함께 호출할 때 팀원을 시작하며, 호출이 [fork](https://code.claude.com/docs/ko/sub-agents.md#fork-the-current-conversation)이거나 호출 자체에서 `isolation`을 전달하지 않는 한입니다. Claude Code는 확인을 요청하지 않습니다.228팀을 시작하려면 Claude에게 팀원을 요청합니다. Claude는 에이전트 팀이 활성화되어 있는 동안 [Agent 도구](https://code.claude.com/docs/ko/tools-reference.md)를 [`name`](https://code.claude.com/docs/ko/sub-agents#subagent-names)과 함께 호출할 때 팀원을 시작합니다. 단, 호출이 [fork](https://code.claude.com/docs/ko/sub-agents.md#fork-the-current-conversation)이거나 호출 자체에서 `isolation`을 전달하는 경우는 제외합니다. Claude Code는 시작 전에 확인을 요청하지 않습니다.

229 229 

230Claude는 또한 일반 subagent에 자동으로 이름을 지정하여 나중에 메시지를 보낼 수 있습니다. 이러한 호출은 동일한 규칙을 따르므로, 팀원을 요청하지 않았을 때도 팀이 형성될 수 있습니다. subagent를 원하면 [에이전트 팀을 끕니다](#claude-spawns-teammates-instead-of-subagents).230Claude는 또한 나중에 메시지를 보낼 수 있도록 일반 서브에이전트에 자체적으로 이름을 지정합니다. 이러한 호출은 동일한 규칙을 따르므로, 팀을 요청하지 않았을 때도 팀이 형성될 수 있습니다. 서브에이전트를 원하면 [에이전트 팀을 끕니다](#claude-spawns-teammates-instead-of-subagents).

231 231 

232### 아키텍처232### 아키텍처

233 233 

244 244 

245Claude Code는 메시지가 일반 텍스트이든 계획 승인이나 종료 요청과 같은 구조화된 프로토콜 메시지이든 수신자의 메일박스 파일에 대한 쓰기가 성공할 때만 메시지를 전송된 것으로 보고합니다. 쓰기가 실패하면(예: 디스크가 가득 찼거나 메일박스 디렉토리를 쓸 수 없는 경우), 전송 에이전트는 오류를 받고 아무것도 전송되지 않습니다. [팀원의 받은편지함에 쓰기 실패](https://code.claude.com/docs/ko/errors.md#failed-to-write-to-a-teammate-inbox)에서 오류 메시지 및 복구 단계를 참조합니다.245Claude Code는 메시지가 일반 텍스트이든 계획 승인이나 종료 요청과 같은 구조화된 프로토콜 메시지이든 수신자의 메일박스 파일에 대한 쓰기가 성공할 때만 메시지를 전송된 것으로 보고합니다. 쓰기가 실패하면(예: 디스크가 가득 찼거나 메일박스 디렉토리를 쓸 수 없는 경우), 전송 에이전트는 오류를 받고 아무것도 전송되지 않습니다. [팀원의 받은편지함에 쓰기 실패](https://code.claude.com/docs/ko/errors.md#failed-to-write-to-a-teammate-inbox)에서 오류 메시지 및 복구 단계를 참조합니다.

246 246 

247Claude Code는 작업 종속성을 자동으로 관리합니다: 팀원이 다른 작업이 종속된 작업을 완료하면, 차단된 작업은 사용자의 조치 없이 차단 해제됩니다.247Claude Code는 작업 의존성을 자동으로 관리합니다: 팀원이 다른 작업이 의존하는 작업을 완료하면, 사용자의 조치 없이 의존하는 작업의 차단이 해제됩니다.

248 248 

249팀과 작업은 세션 파생 이름으로 로컬에 저장됩니다. 이름은 `session-` 뒤에 세션 ID의 처음 8자가 붙습니다:249팀과 작업은 세션 파생 이름으로 로컬에 저장됩니다. 이름은 `session-` 뒤에 세션 ID의 처음 8자가 붙습니다:

250 250 

255 255 

256팀 구성은 세션 ID 및 tmux 창 ID와 같은 런타임 상태를 보유하므로, 수동으로 편집하거나 사전 작성하지 마십시오: 다음 상태 업데이트에서 변경 사항이 덮어씌워집니다.256팀 구성은 세션 ID 및 tmux 창 ID와 같은 런타임 상태를 보유하므로, 수동으로 편집하거나 사전 작성하지 마십시오: 다음 상태 업데이트에서 변경 사항이 덮어씌워집니다.

257 257 

258재사용 가능한 팀원 역할을 정의하려면, 대신 [subagent 정의 사용](#use-subagent-definitions-for-teammates)을 사용합니다.258재사용 가능한 팀원 역할을 정의하려면, 대신 [서브에이전트 정의](#use-subagent-definitions-for-teammates)를 사용합니다.

259 259 

260팀 구성에는 각 팀원의 이름과 에이전트 ID가 있는 `members` 배열이 포함됩니다. 리더의 항목은 항상 에이전트 유형 `team-lead`를 전달합니다. 팀원의 항목은 리더가 팀원을 생성할 때 명명한 에이전트 유형(예: [내장 유형](https://code.claude.com/docs/ko/sub-agents.md#built-in-subagents) 또는 [subagent 정의](#use-subagent-definitions-for-teammates))을 전달하며, 리더가 아무것도 명명하지 않으면 필드를 생략합니다. 팀원들은 이 파일을 읽어 다른 팀 멤버를 발견할 수 있습니다.260팀 구성에는 각 팀원의 이름과 에이전트 ID가 있는 `members` 배열이 포함됩니다. 리더의 항목은 항상 에이전트 유형 `team-lead`를 전달합니다. 팀원의 항목은 리더가 팀원을 생성할 때 명명한 에이전트 유형([내장 유형](https://code.claude.com/docs/ko/sub-agents.md#built-in-subagents) 또는 [서브에이전트 정의](#use-subagent-definitions-for-teammates))을 전달하며, 리더가 아무것도 명명하지 않으면 필드를 생략합니다. 팀원들은 이 파일을 읽어 다른 팀 멤버를 발견할 수 있습니다.

261 261 

262프로젝트 수준의 팀 구성 동등물은 없습니다. 프로젝트 디렉토리의 `.claude/teams/teams.json`과 같은 파일은 구성으로 인식되지 않습니다. Claude는 이를 일반 파일로 취급합니다.262프로젝트 수준의 팀 구성 동등물은 없습니다. 프로젝트 디렉토리의 `.claude/teams/teams.json`과 같은 파일은 구성으로 인식되지 않습니다. Claude는 이를 일반 파일로 취급합니다.

263 263 

264### 팀원을 위해 subagent 정의 사용264### 팀원을 위해 서브에이전트 정의 사용

265 265 

266두 표시 모드에서 팀원을 생성할 때, 프로젝트, 사용자, 관리형 또는 플러그인 [서브에이전트 범위](https://code.claude.com/docs/ko/sub-agents.md#choose-the-subagent-scope)의 [서브에이전트](https://code.claude.com/docs/ko/sub-agents.md) 유형을 참조할 수 있습니다. 이를 통해 보안 검토자 또는 테스트 실행자와 같은 역할을 한 번 정의하고 위임된 서브에이전트와 에이전트 팀 팀원 모두로 재사용할 수 있습니다.266두 표시 모드에서 팀원을 생성할 때, 프로젝트, 사용자, 관리형 또는 플러그인 [서브에이전트 범위](https://code.claude.com/docs/ko/sub-agents.md#choose-the-subagent-scope)의 [서브에이전트](https://code.claude.com/docs/ko/sub-agents.md) 유형을 참조할 수 있습니다. 이를 통해 보안 검토자 또는 테스트 실행자와 같은 역할을 한 번 정의하고 위임된 서브에이전트와 에이전트 팀 팀원 모두로 재사용할 수 있습니다.

267 267 

268subagent 정의를 사용하려면, Claude에게 팀원을 생성하도록 요청할 때 이름으로 언급합니다:268서브에이전트 정의를 사용하려면, Claude에게 팀원을 생성하도록 요청할 때 이름으로 언급합니다:

269 269 

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

271Spawn a teammate using the security-reviewer agent type to audit the auth module.271Spawn a teammate using the security-reviewer agent type to audit the auth module.

272```272```

273 273 

274Claude Code는 명명한 subagent 정의를 읽고 다음 부분을 팀원에게 적용합니다. 부분이 팀원의 [표시 모드](#choose-a-display-mode)에 따라 달라지는 경우, 항목에서 그렇게 표시합니다:274Claude Code는 명명한 서브에이전트 정의를 읽고 다음 부분을 팀원에게 적용합니다. 부분이 팀원의 [표시 모드](#choose-a-display-mode)에 따라 달라지는 경우, 항목에서 그렇게 표시합니다:

275 275 

276* **`tools`**: Claude Code는 팀원을 정의의 `tools` 목록의 도구로 제한합니다. 프로세스 내 팀원의 경우, Claude Code는 해당 목록에 `SendMessage`를 추가하며, [Task 도구가 있는 세션](https://code.claude.com/docs/ko/tools-reference.md#task-tool-availability)에서는 `TaskCreate`, `TaskGet`, `TaskList`, `TaskUpdate`도 추가합니다.276* **`tools`**: Claude Code는 팀원을 정의의 `tools` 목록의 도구로 제한합니다. 프로세스 내 팀원의 경우, Claude Code는 해당 목록에 `SendMessage`를 추가하며, [Task 도구가 있는 세션](https://code.claude.com/docs/ko/tools-reference.md#task-tool-availability)에서는 `TaskCreate`, `TaskGet`, `TaskList`, `TaskUpdate`도 추가합니다.

277* **`model`**: Claude Code는 생성 프롬프트가 모델을 명명하지 않을 때 두 표시 모드에서 정의의 `model`을 사용합니다. [Claude Code가 팀원의 모델을 선택하는 방법](#specify-teammates-and-models)을 참조합니다.277* **`model`**: Claude Code는 생성 프롬프트가 모델을 명명하지 않을 때 두 표시 모드에서 정의의 `model`을 사용합니다. [Claude Code가 팀원의 모델을 선택하는 방법](#specify-teammates-and-models)을 참조합니다.

279* **`effort`**: 프로세스 내 팀원의 경우, Claude Code는 [frontmatter effort 규칙](https://code.claude.com/docs/ko/model-config.md#set-the-effort-level)에 따라 정의의 [`effort`](https://code.claude.com/docs/ko/sub-agents#supported-frontmatter-fields)를 적용합니다.279* **`effort`**: 프로세스 내 팀원의 경우, Claude Code는 [frontmatter effort 규칙](https://code.claude.com/docs/ko/model-config.md#set-the-effort-level)에 따라 정의의 [`effort`](https://code.claude.com/docs/ko/sub-agents#supported-frontmatter-fields)를 적용합니다.

280* **`autoCompactWindow`**: 프로세스 내 팀원의 경우, Claude Code는 [해당 필드의 규칙](https://code.claude.com/docs/ko/sub-agents.md#subagent-auto-compact-window)에 따라 정의의 [`autoCompactWindow`](https://code.claude.com/docs/ko/sub-agents#supported-frontmatter-fields)를 적용합니다. 분할 창 팀원은 이 필드를 무시합니다. Claude Code v2.1.296 이상이 필요합니다.280* **`autoCompactWindow`**: 프로세스 내 팀원의 경우, Claude Code는 [해당 필드의 규칙](https://code.claude.com/docs/ko/sub-agents.md#subagent-auto-compact-window)에 따라 정의의 [`autoCompactWindow`](https://code.claude.com/docs/ko/sub-agents#supported-frontmatter-fields)를 적용합니다. 분할 창 팀원은 이 필드를 무시합니다. Claude Code v2.1.296 이상이 필요합니다.

281* **본문**: 프로세스 내 팀원의 경우, Claude Code는 정의의 본문을 기본 시스템 프롬프트에 추가 지시로 추가합니다. 분할 창 팀원의 경우, Claude Code는 본문을 기본 시스템 프롬프트 대신 사용합니다.281* **본문**: 프로세스 내 팀원의 경우, Claude Code는 정의의 본문을 기본 시스템 프롬프트에 추가 지시로 추가합니다. 분할 창 팀원의 경우, Claude Code는 본문을 기본 시스템 프롬프트 대신 사용합니다.

282* **`skills`**: Claude Code는 두 표시 모드에서 팀원에게 정의의 `skills`을 적용하지 않습니다. 팀원은 프로젝트 및 사용자 설정에서 skills을 로드합니다.282* **`skills`**: Claude Code는 두 표시 모드에서 팀원에게 정의의 `skills`를 적용하지 않습니다. 팀원은 프로젝트 및 사용자 설정에서 스킬을 로드합니다.

283* **`mcpServers`**: 분할 창 팀원의 경우, Claude Code는 [해당 필드의 규칙](https://code.claude.com/docs/ko/sub-agents.md#scope-mcp-servers-to-a-subagent)에 따라 정의의 `mcpServers`를 적용하며, 이는 `--agent`로 시작된 세션도 포함합니다. 프로세스 내 팀원은 필드를 무시하고 프로젝트 및 사용자 설정에서 MCP 서버를 로드합니다.283* **`mcpServers`**: 분할 창 팀원의 경우, Claude Code는 [해당 필드의 규칙](https://code.claude.com/docs/ko/sub-agents.md#scope-mcp-servers-to-a-subagent)에 따라 정의의 `mcpServers`를 적용하며, 이는 `--agent`로 시작된 세션도 포함합니다. 프로세스 내 팀원은 필드를 무시하고 프로젝트 및 사용자 설정에서 MCP 서버를 로드합니다.

284 284 

285Claude가 더 이상 실행 중이지 않은 프로세스 내 팀원에게 메시지를 보낼 때, Claude Code는 동일한 세션에서 팀원을 복구하고, 저장된 대화를 복구하며, 메시지를 다음 프롬프트로 제공합니다. 세션을 재개한 후, 팀원들은 [재개 제한](#limitations)에 따라 이런 방식으로 복구되지 않습니다.285Claude가 더 이상 실행 중이지 않은 프로세스 내 팀원에게 메시지를 보낼 때, Claude Code는 동일한 세션에서 팀원을 복구하고, 저장된 대화를 복구하며, 메시지를 다음 프롬프트로 제공합니다. 세션을 재개한 후, 팀원들은 [재개 제한](#limitations)에 따라 이런 방식으로 복구되지 않습니다.

307 307 

308#### 에이전트 간 메시지308#### 에이전트 간 메시지

309 309 

310한 에이전트가 `SendMessage`를 통해 다른 에이전트에게 메시지를 보낼 때, Claude Code는 수신 에이전트에게 사용자가 아닌 다른 Claude 세션에서 온 것으로 알립니다. 팀원은 권한 프롬프트를 승인하거나 사용자를 대신하여 동의를 제공할 수 없으며, 작업이 거부된 팀원은 이를 다른 팀원에게 전달하여 확인을 우회할 수 없습니다. [팀 전체 외부의 다른 Claude Code 세션](https://code.claude.com/docs/ko/cross-session-messaging.md#how-a-session-treats-an-incoming-message) 중 하나에서 도착한 메시지에도 동일한 규칙이 적용됩니다.310한 에이전트가 `SendMessage`를 통해 다른 에이전트에게 메시지를 보낼 때, Claude Code는 수신 에이전트에게 메시지가 사용자가 아닌 다른 Claude 세션에서 온 것임을 알립니다. 팀원은 권한 프롬프트를 승인하거나 사용자를 대신하여 동의를 제공할 수 없으며, 작업이 거부된 팀원은 이를 다른 팀원에게 전달하여 확인을 우회할 수 없습니다. 팀 외부에 있는 [사용자의 다른 Claude Code 세션](https://code.claude.com/docs/ko/cross-session-messaging.md#how-a-session-treats-an-incoming-message) 중 하나에서 도착한 메시지에도 동일한 규칙이 적용됩니다.

311 311 

312[자동 모드](https://code.claude.com/docs/ko/permission-modes.md#eliminate-prompts-with-auto-mode)에서, 분류기는 에이전트 간 메시지에 두 가지 확인을 적용합니다:312[자동 모드](https://code.claude.com/docs/ko/permission-modes.md#eliminate-prompts-with-auto-mode)에서, 분류기는 에이전트 간 메시지에 두 가지 확인을 적용합니다:

313 313 

316 316 

317### 컨텍스트 및 통신317### 컨텍스트 및 통신

318 318 

319각 팀원은 자신의 컨텍스트 윈도우를 가집니다. 생성될 때, 팀원은 일반 세션과 동일한 프로젝트 컨텍스트를 로드합니다: CLAUDE.md, MCP 서버, skills. [`--setting-sources`](https://code.claude.com/docs/ko/cli-reference#cli-flags)로 리더를 시작하면, 팀원들은 동일한 제한된 소스 목록에서 로드합니다. v2.1.281 이전에는 [분할 창](#choose-a-display-mode) 팀원들이 모든 설정 소스를 로드했습니다.319각 팀원은 자신의 컨텍스트 윈도우를 가집니다. 생성될 때, 팀원은 일반 세션과 동일한 프로젝트 컨텍스트를 로드합니다: CLAUDE.md, MCP 서버, 스킬. [`--setting-sources`](https://code.claude.com/docs/ko/cli-reference#cli-flags)로 리더를 시작하면, 팀원들은 동일한 제한된 소스 목록에서 로드합니다. v2.1.281 이전에는 [분할 창](#choose-a-display-mode) 팀원들이 모든 설정 소스를 로드했습니다.

320 320 

321팀원은 또한 리더의 생성 프롬프트를 받습니다. 리더의 대화 기록은 전달되지 않습니다.321팀원은 또한 리더의 생성 프롬프트를 받습니다. 리더의 대화 기록은 전달되지 않습니다.

322 322 

323**팀원들이 정보를 공유하는 방법:**323**팀원들이 정보를 공유하는 방법:**

324 324 

325* **자동 메시지 전달**: 팀원들이 메시지를 보낼 때, 자동으로 수신자에게 전달됩니다. 리더가 업데이트를 폴링할 필요가 없습니다.325* **자동 메시지 전달**: 팀원들이 메시지를 보낼 때, 자동으로 수신자에게 전달됩니다. 리더가 업데이트를 폴링할 필요가 없습니다.

326* **유휴 알림**: 팀원이 완료되고 중지되면, 자동으로 리더에게 알립니다. 최종 답변을 알림에 포함합니다. API 오류에서 턴이 끝난 팀원은 실패했음을 리더에게 알리고 오류 텍스트를 포함합니다.326* **유휴 알림**: 팀원이 완료되고 중지되면, 자동으로 리더에게 알리며 최종 답변을 알림에 포함합니다. API 오류로 턴이 끝난 팀원은 실패했음을 리더에게 알리고 오류 텍스트를 포함합니다.

327* **공유 작업 목록**: [Task 도구가 있는 에이전트](https://code.claude.com/docs/ko/tools-reference.md#task-tool-availability)는 작업 상태를 보고 사용 가능한 작업을 요청할 수 있습니다.327* **공유 작업 목록**: [Task 도구가 있는 에이전트](https://code.claude.com/docs/ko/tools-reference.md#task-tool-availability)는 작업 상태를 보고 사용 가능한 작업을 요청할 수 있습니다.

328* **팀원 메시징**: 이름으로 특정 팀원 한 명에게 메시지를 보냅니다. 모든 사람에게 도달하려면, 각 수신자에게 하나의 메시지를 보냅니다.328* **팀원 메시징**: 이름으로 특정 팀원 한 명에게 메시지를 보냅니다. 모든 사람에게 도달하려면, 각 수신자에게 하나의 메시지를 보냅니다.

329 329 

agent-view.md +0 −2

Details

892 892 

893명령은 또한 실행 중인 감독자가 호출한 `claude`와 다른 버전에 있을 때 경고하며, 이는 감독자가 아직 다시 시작하지 않은 업데이트 후에 발생합니다. 경고는 두 버전을 모두 표시하고 새 버전을 적용하려면 `claude daemon stop --any`를 실행하도록 안내합니다.893명령은 또한 실행 중인 감독자가 호출한 `claude`와 다른 버전에 있을 때 경고하며, 이는 감독자가 아직 다시 시작하지 않은 업데이트 후에 발생합니다. 경고는 두 버전을 모두 표시하고 새 버전을 적용하려면 `claude daemon stop --any`를 실행하도록 안내합니다.

894 894 

895세션은 이러한 버전 불일치에도 그대로 유지됩니다. 이전 Claude Code 버전이 세션의 `state.json`을 업데이트할 때 인식하지 못하는 필드를 보존하고 세션을 나열된 상태로 유지합니다. `roster.json`의 세션 목록도 동일한 규칙을 따르므로 최신 버전으로 시작한 세션은 도달 가능한 상태로 유지되고 감독자가 다시 시작한 후에도 입력을 계속 받습니다.

896 

897### 에이전트 뷰 끄기895### 에이전트 뷰 끄기

898 896 

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

Details

367| `ap-*` | `apac.` |367| `ap-*` | `apac.` |

368| 기타 모든 지역 | `global.` |368| 기타 모든 지역 | `global.` |

369 369 

370Claude Code가 먼저 시도할 접두사를 선택하려면 `ANTHROPIC_BEDROCK_REGION_PREFIX`를 설정하십시오. Claude Code가 프로필 가용성을 확인할 수 있고 모델에 대해 일치하는 프로필을 찾지 못하면 아래 설명된 확인 순서에 따라 폴백됩니다. 유효한 값은 `us`, `eu`, `apac`, `jp`, `au`, 및 `global`입니다. 예를 들어, 계정에 `global.` 프로필이 활성화되어 있지만 Claude Code가 AWS 지역에서 지역별 프로필을 도출할 때 이를 `global`로 설정하십시오. Claude Code v2.1.224 이상이 필요합니다.370Claude Code가 먼저 시도할 접두사를 선택하려면 `ANTHROPIC_BEDROCK_REGION_PREFIX`를 설정하십시오. 유효한 값은 `us`, `eu`, `apac`, `jp`, `au`, 및 `global`입니다. 예를 들어, 계정에 `global.` 프로필이 활성화되어 있지만 Claude Code가 AWS 지역에서 지역별 프로필을 도출할 때 이를 `global`로 설정하십시오.

371 371 

372이 예제는 기본 모델을 `global.` 프로필을 통해 라우팅합니다:372이 예제는 기본 모델을 `global.` 프로필을 통해 라우팅합니다:

373 373 

artifacts.md +19 −2

Details

64| :- | :- |64| :- | :- |

65| 세션이 [플랜 모드](https://code.claude.com/docs/ko/permission-modes.md#analyze-before-you-edit-with-plan-mode)인 경우 | 각 아티팩트의 첫 번째 게시 전에 확인을 요청합니다 |65| 세션이 [플랜 모드](https://code.claude.com/docs/ko/permission-modes.md#analyze-before-you-edit-with-plan-mode)인 경우 | 각 아티팩트의 첫 번째 게시 전에 확인을 요청합니다 |

66| 게시가 [커넥터 호출](#pull-live-data-with-mcp-connectors) 또는 [파일 다운로드](#offer-a-file-download)와 같은 페이지에 대한 런타임 기능을 선언하는 경우 | 해당 게시 전에 확인을 요청합니다 |66| 게시가 [커넥터 호출](#pull-live-data-with-mcp-connectors) 또는 [파일 다운로드](#offer-a-file-download)와 같은 페이지에 대한 런타임 기능을 선언하는 경우 | 해당 게시 전에 확인을 요청합니다 |

67| 아티팩트를 공개적으로 공유한 경우 | 변경 전에 대화당 한 번 확인을 요청합니다 |67| 아티팩트를 공개적으로 공유한 경우 | 변경 전에 대화당 한 번, 그리고 아티팩트의 댓글에 답글을 달 때마다 그 전에 확인을 요청합니다 |

68| 사용자가 입력한 프롬프트가 아니라 세션에서 실행된 [세션 범위 예약 작업](https://code.claude.com/docs/ko/scheduled-tasks.md)이 시작한 턴에서 Claude가 게시하는 경우 | 각 아티팩트의 첫 번째 게시 전에 확인을 요청합니다 |68| 사용자가 입력한 프롬프트가 아니라 세션에서 실행된 [세션 범위 예약 작업](https://code.claude.com/docs/ko/scheduled-tasks.md)이 시작한 턴에서 Claude가 게시하는 경우 | 각 아티팩트의 첫 번째 게시 전에 확인을 요청합니다 |

69| 사용자의 승인 없이는 Claude가 파일을 읽을 수 없는 경우 | 게시 전에 확인을 요청합니다. `Artifact` 도구에 대한 허용 규칙이 있어도 이 프롬프트는 생략되지 않습니다 |69| 사용자의 승인 없이는 Claude가 파일을 읽을 수 없는 경우 | 게시 전에 확인을 요청합니다. `Artifact` 도구에 대한 허용 규칙이 있어도 이 프롬프트는 생략되지 않습니다 |

70| [Manual](https://code.claude.com/docs/ko/permission-modes.md) 또는 `acceptEdits` 모드에서 Claude가 Manual 모드의 프로젝트 파일처럼 사용자의 승인 없이는 편집할 수 없는 아티팩트 파일에 작은 변경을 하는 경우 | 변경 사항을 게시하기 전에 확인을 요청합니다. 파일 편집에 사용자의 승인이 필요하므로 `Artifact` 도구에 대한 허용 규칙이 있어도 확인을 요청합니다 |70| [Manual](https://code.claude.com/docs/ko/permission-modes.md) 또는 `acceptEdits` 모드에서 Claude가 Manual 모드의 프로젝트 파일처럼 사용자의 승인 없이는 편집할 수 없는 아티팩트 파일에 작은 변경을 하는 경우 | 변경 사항을 게시하기 전에 확인을 요청합니다. 파일 편집에 사용자의 승인이 필요하므로 `Artifact` 도구에 대한 허용 규칙이 있어도 확인을 요청합니다 |

89https://claude.ai/code/artifact/5fbea6f3-...을 오늘의 숫자로 업데이트합니다.89https://claude.ai/code/artifact/5fbea6f3-...을 오늘의 숫자로 업데이트합니다.

90```90```

91 91 

92### 원스텝 아티팩트 업데이트 끄기

93 

94원스텝 업데이트는 Claude가 `Edit` 또는 `Write` 호출을 통하지 않고 게시 과정의 일부로 아티팩트 파일에 적용하는 작은 변경입니다.

95 

96원스텝 업데이트를 끄려면 [`CLAUDE_CODE_ARTIFACT_PUBLISH_EDITS`](https://code.claude.com/docs/ko/env-vars)를 `0`으로 설정합니다. 다음 예시는 `~/.claude/settings.json`의 `env` 블록에 이 변수를 추가합니다.

97 

98```json theme={null}

99{

100 "env": {

101 "CLAUDE_CODE_ARTIFACT_PUBLISH_EDITS": "0"

102 }

103}

104```

105 

106그런 다음 Claude Code를 종료했다가 다시 실행합니다. 실행 중인 세션은 변수를 다시 읽지 않기 때문입니다.

107 

92## 아티팩트 다시 찾기108## 아티팩트 다시 찾기

93 109 

94Claude Code에서 `/artifacts`를 실행하여 소유한 아티팩트와 공유받은 아티팩트를 나열합니다. 현재 세션의 아티팩트가 **This session** 아래에 먼저 표시됩니다.110Claude Code에서 `/artifacts`를 실행하여 소유한 아티팩트와 공유받은 아티팩트를 나열합니다. 현재 세션의 아티팩트가 **This session** 아래에 먼저 표시됩니다.

111공유할 수 있는 대상은 사용자의 플랜에 따라 다릅니다.127공유할 수 있는 대상은 사용자의 플랜에 따라 다릅니다.

112 128 

113* **조직 내**: Team 및 Enterprise 플랜에서는 조직의 특정 사람 또는 모든 사람에게 액세스 권한을 부여할 수 있습니다. 뷰어는 페이지를 보기 위해 조직의 구성원으로 claude.ai에 로그인합니다.129* **조직 내**: Team 및 Enterprise 플랜에서는 조직의 특정 사람 또는 모든 사람에게 액세스 권한을 부여할 수 있습니다. 뷰어는 페이지를 보기 위해 조직의 구성원으로 claude.ai에 로그인합니다.

130* **공유 폴더에 액세스할 수 있는 사람**: Team 및 Enterprise 플랜에서는 사용자가 소유하거나 편집자로 있는 폴더로 아티팩트를 이동할 수 있습니다. 이동은 [아티팩트 페이지](https://claude.ai/artifacts)에서 할 수 있으며, 이 페이지는 claude.ai 채팅을 사용할 수 있는 경우 이용할 수 있습니다. 이동한 후에는 폴더에 액세스할 수 있는 모든 사람이 아티팩트를 열 수 있고, 폴더의 소유자와 편집자는 아티팩트를 변경할 수 있습니다.

114* **공개**: 인터넷의 누구나 열 수 있는 링크를 공유하며, claude.ai 로그인이 필요하지 않습니다. Team 및 Enterprise 플랜에서는 공개 공유가 활성화될 때까지 비활성화되어 있으며, Owner가 [조직에 대해 공개 공유를 활성화](#control-public-sharing)해야 합니다.131* **공개**: 인터넷의 누구나 열 수 있는 링크를 공유하며, claude.ai 로그인이 필요하지 않습니다. Team 및 Enterprise 플랜에서는 공개 공유가 활성화될 때까지 비활성화되어 있으며, Owner가 [조직에 대해 공개 공유를 활성화](#control-public-sharing)해야 합니다.

115 132 

116### 특정 보기로 연결하기133### 특정 보기로 연결하기

178[권한 모드](https://code.claude.com/docs/ko/permission-modes.md)는 보낸 댓글이 도착할 때 Claude가 수행하는 작업을 결정합니다:195[권한 모드](https://code.claude.com/docs/ko/permission-modes.md)는 보낸 댓글이 도착할 때 Claude가 수행하는 작업을 결정합니다:

179 196 

180* **Claude가 자동으로 답변합니다**: 권한 모드가 Claude가 사용자에게 묻지 않고 답변을 게시하도록 허용할 때, Claude는 스레드를 읽고 답변합니다. `Auto-replied to comment thread on Artifact: <name>`이 표시됩니다.197* **Claude가 자동으로 답변합니다**: 권한 모드가 Claude가 사용자에게 묻지 않고 답변을 게시하도록 허용할 때, Claude는 스레드를 읽고 답변합니다. `Auto-replied to comment thread on Artifact: <name>`이 표시됩니다.

181* **Claude가 당신을 기다립니다**: 계획 모드 외부에서 답변 게시에 승인이 필요할 때, `Comments are waiting on Artifact: <name>`이 표시됩니다. Claude는 스레드를 읽을 승인을 요청하고, 다시 답변을 게시할 승인을 요청합니다.198* **Claude가 사용자를 기다립니다**: 플랜 모드 외부에서 답변 게시에 [승인이 필요할 때](#when-claude-code-asks-before-publishing), `Comments are waiting on Artifact: <name>`이 표시됩니다. Claude는 스레드를 읽을 승인을 요청하고, 다시 답변을 게시할 승인을 요청합니다.

182* **Claude가 계획 모드에서 일시 중지됩니다**: `Comments are waiting on Artifact: <name>`이 표시되고, 계획 모드를 종료하고 스레드를 읽고 답변하도록 요청할 때까지 Claude는 답변하지 않습니다.199* **Claude가 계획 모드에서 일시 중지됩니다**: `Comments are waiting on Artifact: <name>`이 표시되고, 계획 모드를 종료하고 스레드를 읽고 답변하도록 요청할 때까지 Claude는 답변하지 않습니다.

183 200 

184Claude는 또한 1시간 내에 해당 아티팩트에서 60개의 보낸 댓글 또는 스레드 활성화를 처리한 후 아티팩트에 자동으로 답변하는 것을 중지합니다. `Comments are waiting on Artifact: <name>`이 한 번 표시되고, Claude는 해당 시간의 댓글이 오래되면서 다시 시작합니다.201Claude는 또한 1시간 내에 해당 아티팩트에서 60개의 보낸 댓글 또는 스레드 활성화를 처리한 후 아티팩트에 자동으로 답변하는 것을 중지합니다. `Comments are waiting on Artifact: <name>`이 한 번 표시되고, Claude는 해당 시간의 댓글이 오래되면서 다시 시작합니다.

Details

34* **요청**: 검사를 통과시키려면 게이트웨이는 `anthropic-beta` 헤더와 `safeguards` 본문 필드를 모두 변경하지 않고 전달해야 합니다. [이 둘은 한 쌍으로 함께 전달되기](https://code.claude.com/docs/ko/llm-gateway-protocol.md#beta-header-and-body-field-pairs) 때문입니다. [Amazon Bedrock InvokeModel 형식](https://code.claude.com/docs/ko/llm-gateway-protocol.md#api-formats)에서는 헤더 대신 `anthropic_beta` 본문 필드를 전달합니다.34* **요청**: 검사를 통과시키려면 게이트웨이는 `anthropic-beta` 헤더와 `safeguards` 본문 필드를 모두 변경하지 않고 전달해야 합니다. [이 둘은 한 쌍으로 함께 전달되기](https://code.claude.com/docs/ko/llm-gateway-protocol.md#beta-header-and-body-field-pairs) 때문입니다. [Amazon Bedrock InvokeModel 형식](https://code.claude.com/docs/ko/llm-gateway-protocol.md#api-formats)에서는 헤더 대신 `anthropic_beta` 본문 필드를 전달합니다.

35* **응답**: 게이트웨이는 필드를 삭제하거나 도구 사용 ID를 다시 작성하지 않고 응답과 스트리밍 이벤트를 반환합니다. 검사 결과를 통과시키려면 `safeguard_results` 필드를 유지합니다.35* **응답**: 게이트웨이는 필드를 삭제하거나 도구 사용 ID를 다시 작성하지 않고 응답과 스트리밍 이벤트를 반환합니다. 검사 결과를 통과시키려면 `safeguard_results` 필드를 유지합니다.

36 36 

37이러한 방식으로 트래픽을 통과시키는 게이트웨이는 이 기능 및 향후 기능과 계속 작동합니다. 그러면 새 세션은 서버의 검사를 다시 사용합니다.37게이트웨이가 이렇게 동작하면 새 세션은 서버의 검사를 다시 사용합니다.

38 38 

39게이트웨이가 서버의 검사를 제공할 수 없다는 것을 이미 알고 있다면, 세션을 시작하기 전에 셸 또는 [`env` 설정 키](https://code.claude.com/docs/ko/settings-reference#env)에서 `CLAUDE_CODE_AUTO_MODE_SERVER`를 `0`으로 설정하여 Claude Code에 그곳에서 검사를 요청하지 않도록 지시하십시오:39게이트웨이가 서버의 검사를 제공할 수 없다는 것을 이미 알고 있다면, 세션을 시작하기 전에 셸 또는 [`env` 설정 키](https://code.claude.com/docs/ko/settings-reference#env)에서 `CLAUDE_CODE_AUTO_MODE_SERVER`를 `0`으로 설정하여 Claude Code에 그곳에서 검사를 요청하지 않도록 지시하십시오:

40 40 

Details

180 180 

181Claude Code는 백그라운드에서 스캔한 다음 초안을 보여줍니다. 초안은 전체 단위로 수락하거나 폐기하므로, 개별 항목을 조정하려면 이후에 `~/.claude/settings.json`을 편집하십시오. 수락하면 Claude Code는 초안을 기록하고 기존 설정과 다음과 같이 조정합니다.181Claude Code는 백그라운드에서 스캔한 다음 초안을 보여줍니다. 초안은 전체 단위로 수락하거나 폐기하므로, 개별 항목을 조정하려면 이후에 `~/.claude/settings.json`을 편집하십시오. 수락하면 Claude Code는 초안을 기록하고 기존 설정과 다음과 같이 조정합니다.

182 182 

183* 초안에 변경되지 않은 기본 제공 항목이 명시적으로 포함되어 있으므로, Claude Code는 `"$defaults"` 없이 `environment` 목록을 기록합니다183* `~/.claude/settings.json`의 `environment` 목록에 추가하기로 선택한 경우 목록에 있는 `"$defaults"` 항목은 유지됩니다. 해당 목록을 교체하기로 선택한 경우 이 항목이 사라지므로, 기본 항목을 사용하려면 `"$defaults"`를 다시 추가하십시오

184* Claude Code는 초안이 항목을 추가하는 `allow`, `soft_deny`, `hard_deny` 목록 각각에 `"$defaults"`를 포함합니다. 단, 사용자가 이미 `"$defaults"` 없이 `allow` 목록을 작성한 경우는 예외입니다. 이를 통해 교체하지 않은 [기본 제공 규칙](#override-the-block-and-allow-rules)이 계속 적용됩니다184* Claude Code는 초안이 항목을 추가하는 `allow`, `soft_deny`, `hard_deny` 목록 각각에 `"$defaults"`를 포함합니다. 단, 사용자가 이미 `"$defaults"` 없이 `allow` 목록을 작성한 경우는 예외입니다. 이를 통해 교체하지 않은 [기본 제공 규칙](#override-the-block-and-allow-rules)이 계속 적용됩니다

185* 저장 후 Claude Code는 `~/.claude/settings.json`에서 자동 모드가 무시하는 `permissions.allow` 규칙(예: `Bash(*)`)이나 파괴적인 명령을 자동 승인하는 규칙을 제거하도록 제안합니다185* 저장 후 Claude Code는 `~/.claude/settings.json`에서 자동 모드가 무시하는 `permissions.allow` 규칙(예: `Bash(*)`)이나 파괴적인 명령을 자동 승인하는 규칙을 제거하도록 제안합니다

186 186 

216 216 

217세 개의 추가 필드를 사용하여 분류기의 기본 제공 규칙 목록을 바꿀 수 있습니다:217세 개의 추가 필드를 사용하여 분류기의 기본 제공 규칙 목록을 바꿀 수 있습니다:

218 218 

219* `autoMode.hard_deny`: 무조건적인 보안 경계219* `autoMode.hard_deny`: 사용자가 요청하더라도 차단할 작업

220* `autoMode.soft_deny`: 사용자 의도로 해제할 수 있는 파괴적인 작업220* `autoMode.soft_deny`: 사용자 의도로 해제할 수 있는 파괴적인 작업

221* `autoMode.allow`: 소프트 블록 규칙의 예외221* `autoMode.allow`: 소프트 블록 규칙의 예외

222 222 

231 231 

232일반적인 요청은 명시적 의도로 계산되지 않습니다. Claude에게 "저장소를 정리해 달라"고 요청하는 것은 강제 푸시를 승인하지 않지만, "이 브랜치를 강제 푸시해 달라"고 요청하는 것은 승인합니다.232일반적인 요청은 명시적 의도로 계산되지 않습니다. Claude에게 "저장소를 정리해 달라"고 요청하는 것은 강제 푸시를 승인하지 않지만, "이 브랜치를 강제 푸시해 달라"고 요청하는 것은 승인합니다.

233 233 

234느슨하게 하려면, 분류기가 기본 예외가 다루지 않는 일상적인 패턴을 반복적으로 플래그할 때 `allow`에 추가하세요. 더 엄격하게 하려면, 기본값이 놓친 환경에 특정한 파괴적 위험에 대해 `soft_deny`에 추가하거나, 절대 넘어서는 안 되는 보안 경계에 대해 `hard_deny`에 추가하세요.234느슨하게 하려면, 분류기가 기본 예외가 다루지 않는 일상적인 패턴을 반복적으로 플래그할 때 `allow`에 추가하세요. 더 엄격하게 하려면, 기본값이 놓친 환경에 특정한 파괴적 위험에 대해 `soft_deny`에 추가하거나, 사용자가 요청하더라도 차단할 작업에 대해 `hard_deny`에 추가하세요.

235 235 

236기본 제공 규칙을 유지하면서 자신의 규칙을 추가하려면 배열에 리터럴 문자열 `"$defaults"`를 포함하세요. 기본 규칙이 해당 위치에 삽입되므로, 사용자 정의 규칙이 앞이나 뒤에 올 수 있으며, 릴리스 전반에 걸쳐 기본 제공 목록이 변경되면서 업데이트를 계속 상속받습니다.236기본 제공 규칙을 유지하면서 자신의 규칙을 추가하려면 배열에 리터럴 문자열 `"$defaults"`를 포함하세요. 기본 규칙이 해당 위치에 삽입되므로, 사용자 정의 규칙이 앞이나 뒤에 올 수 있으며, 릴리스 전반에 걸쳐 기본 제공 목록이 변경되면서 업데이트를 계속 상속받습니다.

237 237 

252 "soft_deny": [252 "soft_deny": [

253 "$defaults",253 "$defaults",

254 "Never run database migrations outside the migrations CLI, even against dev databases",254 "Never run database migrations outside the migrations CLI, even against dev databases",

255 "Never modify files under infra/terraform/prod/: production infrastructure changes go through the review workflow"255 "Running terraform apply in infra/terraform/prod/ needs an explicit request: production infrastructure changes go through the review workflow"

256 ],256 ],

257 "hard_deny": [257 "hard_deny": [

258 "$defaults",258 "$defaults",

Details

322 322 

323다음은 양방향 지원이 있는 완전한 `webhook.ts`입니다. 아웃바운드 회신은 [Server-Sent Events](https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events) (SSE)를 사용하여 `GET /events`를 통해 스트리밍되므로 `curl -N localhost:8788/events`는 실시간으로 볼 수 있습니다. 인바운드 채팅은 `POST /`에 도착합니다:323다음은 양방향 지원이 있는 완전한 `webhook.ts`입니다. 아웃바운드 회신은 [Server-Sent Events](https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events) (SSE)를 사용하여 `GET /events`를 통해 스트리밍되므로 `curl -N localhost:8788/events`는 실시간으로 볼 수 있습니다. 인바운드 채팅은 `POST /`에 도착합니다:

324 324 

325```ts title="회신 도구가 있는 전체 webhook.ts' expandable theme={null}325```ts title="회신 도구가 있는 전체 webhook.ts" expandable theme={null}

326#!/usr/bin/env bun326#!/usr/bin/env bun

327import { Server } from '@modelcontextprotocol/sdk/server/index.js'327import { Server } from '@modelcontextprotocol/sdk/server/index.js'

328import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'328import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'

Details

763. Amazon Bedrock 애플리케이션 추론 프로필 ARN 또는 Microsoft Foundry 배포 이름과 같이 모델 이름을 포함하지 않는 업스트림 문자열에 대해 해당 업스트림 ID에 매핑한 [`models[].id`](https://code.claude.com/docs/ko/claude-apps-gateway-config#models)의 정가입니다. v2.1.218 이상이 필요합니다.763. Amazon Bedrock 애플리케이션 추론 프로필 ARN 또는 Microsoft Foundry 배포 이름과 같이 모델 이름을 포함하지 않는 업스트림 문자열에 대해 해당 업스트림 ID에 매핑한 [`models[].id`](https://code.claude.com/docs/ko/claude-apps-gateway-config#models)의 정가입니다. v2.1.218 이상이 필요합니다.

774. 미알려진 모델 계층인 백만 입력/출력 토큰당 \$5/\$25입니다. 따라서 미터가 배치할 수 없는 ID는 절대 무료가 아닙니다. 게이트웨이는 부팅 시 및 런타임에 ID당 한 번 경고합니다.774. 미알려진 모델 계층인 백만 입력/출력 토큰당 \$5/\$25입니다. 따라서 미터가 배치할 수 없는 ID는 절대 무료가 아닙니다. 게이트웨이는 부팅 시 및 런타임에 ID당 한 번 경고합니다.

78 78 

79어떤 요금이 적용되든 미터는 금액에 [`pricing.multiplier`](https://code.claude.com/docs/ko/claude-apps-gateway-config#pricing)를 곱합니다. 기본값은 `1`입니다.79어떤 요금이 적용되든 미터는 금액에 [`pricing.multiplier`](https://code.claude.com/docs/ko/claude-apps-gateway-config#pricing)를 곱합니다. 기본값은 `1`입니다. Claude Code v2.1.227 이상을 실행하는 게이트웨이 서버가 필요합니다.

80 80 

81클라이언트 중단도 청구됩니다. 스트림이 업스트림의 최종 사용량 프레임 없이 종료되면 미터는 클라이언트로 이미 전송된 텍스트에 대해 출력 토큰당 약 4자의 하한 추정값을 청구합니다. 따라서 요청을 조기에 중단해도 한도를 회피할 수 없습니다.81클라이언트 중단도 청구됩니다. 스트림이 업스트림의 최종 사용량 프레임 없이 종료되면 미터는 클라이언트로 이미 전송된 텍스트에 대해 출력 토큰당 약 4자의 하한 추정값을 청구합니다. 따라서 요청을 조기에 중단해도 한도를 회피할 수 없습니다.

82 82 

Details

205* **`/teleport` 사용**: 기존 CLI 세션 내에서 `/teleport` 또는 `/tp`를 실행하여 Claude Code를 다시 시작하지 않고 동일한 세션 선택기를 엽니다.205* **`/teleport` 사용**: 기존 CLI 세션 내에서 `/teleport` 또는 `/tp`를 실행하여 Claude Code를 다시 시작하지 않고 동일한 세션 선택기를 엽니다.

206* **`/tasks`에서**: `/tasks`를 실행하여 백그라운드 세션을 보고, `t`를 눌러 하나로 teleport합니다.206* **`/tasks`에서**: `/tasks`를 실행하여 백그라운드 세션을 보고, `t`를 눌러 하나로 teleport합니다.

207* **claude.ai/code에서**: 세션 메뉴에서 **Open in > Terminal**을 선택하여 터미널에 붙여넣을 수 있는 명령을 복사합니다.207* **claude.ai/code에서**: 세션 메뉴에서 **Open in > Terminal**을 선택하여 터미널에 붙여넣을 수 있는 명령을 복사합니다.

208* **클라우드 세션 내에서**: `/teleport`를 입력하면 Claude Code가 해당 세션에 대한 정확한 `claude --teleport <session-id>` 명령으로 응답하며, 저장소의 체크아웃에서 실행할 준비가 됩니다. 세션의 환경에서 Claude Code v2.1.223 이상이 필요합니다.208* **클라우드 세션 내에서**: `/teleport`를 입력하면 Claude Code가 해당 세션에 대한 정확한 `claude --teleport <session-id>` 명령으로 응답하며, 저장소의 체크아웃에서 실행할 준비가 됩니다.

209 209 

210세션을 teleport할 때, Claude는 올바른 저장소에 있는지 확인하고, 클라우드 세션에서 브랜치를 가져와 체크아웃하고, 대화를 터미널에 로드합니다.210세션을 teleport할 때, Claude는 올바른 저장소에 있는지 확인하고, 클라우드 세션에서 브랜치를 가져와 체크아웃하고, 대화를 터미널에 로드합니다.

211 211 

499* **저장소 인증**: 동일한 계정으로 인증된 경우에만 클라우드 세션을 터미널로 가져올 수 있습니다.499* **저장소 인증**: 동일한 계정으로 인증된 경우에만 클라우드 세션을 터미널로 가져올 수 있습니다.

500* **플랫폼 제한**: Anthropic 호스팅 환경에서의 저장소 복제 및 풀 리퀘스트 생성에는 GitHub이 필요합니다. 자체 호스팅 [GitHub Enterprise Server](https://code.claude.com/docs/ko/github-enterprise-server.md) 인스턴스는 Team 및 Enterprise 플랜에서 지원됩니다. `CCR_FORCE_BUNDLE=1`을 설정하여 GitLab, Bitbucket 또는 기타 비-GitHub 저장소를 [로컬 번들](#send-local-repositories-without-github)로 클라우드 세션에 전송할 수 있지만, 세션은 결과를 원격으로 다시 푸시할 수 없습니다.500* **플랫폼 제한**: Anthropic 호스팅 환경에서의 저장소 복제 및 풀 리퀘스트 생성에는 GitHub이 필요합니다. 자체 호스팅 [GitHub Enterprise Server](https://code.claude.com/docs/ko/github-enterprise-server.md) 인스턴스는 Team 및 Enterprise 플랜에서 지원됩니다. `CCR_FORCE_BUNDLE=1`을 설정하여 GitLab, Bitbucket 또는 기타 비-GitHub 저장소를 [로컬 번들](#send-local-repositories-without-github)로 클라우드 세션에 전송할 수 있지만, 세션은 결과를 원격으로 다시 푸시할 수 없습니다.

501 * **자체 호스팅 환경**: 다른 git 호스트에 있는 저장소의 경우 [`--environment`로 세션을 시작하기 위한 요구 사항](https://code.claude.com/docs/ko/self-hosted-environments-deploy#start-a-session-on-a-repository-outside-github)을 참조하십시오.501 * **자체 호스팅 환경**: 다른 git 호스트에 있는 저장소의 경우 [`--environment`로 세션을 시작하기 위한 요구 사항](https://code.claude.com/docs/ko/self-hosted-environments-deploy#start-a-session-on-a-repository-outside-github)을 참조하십시오.

502* **조직 IP 허용 목록**: 클라우드 세션은 사용자의 네트워크가 아닌 Anthropic 관리 인프라에서 Anthropic API를 호출하는 반면, [자체 호스팅 환경](https://code.claude.com/docs/ko/self-hosted-environments)의 세션은 사용자의 네트워크에서 호출합니다. 조직에 [IP 허용 목록](https://support.claude.com/en/articles/13200993-restrict-access-to-claude-with-ip-allowlisting)이 활성화되어 있으면 모든 Anthropic 호스팅 클라우드 세션이 인증 오류로 실패합니다.

503 * **Code Review 및 예약 작업**: 이는 [Code Review](https://code.claude.com/docs/ko/code-review.md) 및 Anthropic 호스팅 환경에서 실행되는 [클라우드 예약 작업](https://code.claude.com/docs/ko/routines.md)에도 동일하게 적용됩니다. 자체 호스팅 환경으로 라우팅된 예약 작업은 사용자의 네트워크에서 API를 호출합니다.

504 * **예외 적용 받기**: [Anthropic 지원](https://support.claude.com/)에 문의하여 조직의 IP 허용 목록에서 Anthropic 호스팅 서비스를 제외하십시오.

505 502 

506## 관련 리소스503## 관련 리소스

507 504 

Details

142`sessions/`의 세션 파일, 자동 메모리, Claude Desktop 및 Cowork 트랜스크립트는 각각 자체 보존 규칙을 따릅니다:142`sessions/`의 세션 파일, 자동 메모리, Claude Desktop 및 Cowork 트랜스크립트는 각각 자체 보존 규칙을 따릅니다:

143 143 

144* **`sessions/`**: 실행 중인 각 세션에 대해 하나의 작은 파일을 보유합니다. 동시 세션 및 충돌을 감지하는 데 사용됩니다. 나이 기반 스윕의 일부가 아닙니다: Claude Code는 세션이 종료될 때 각 파일을 제거하고 다음 시작 시 충돌 남은 것을 정리합니다.144* **`sessions/`**: 실행 중인 각 세션에 대해 하나의 작은 파일을 보유합니다. 동시 세션 및 충돌을 감지하는 데 사용됩니다. 나이 기반 스윕의 일부가 아닙니다: Claude Code는 세션이 종료될 때 각 파일을 제거하고 다음 시작 시 충돌 남은 것을 정리합니다.

145* **`seed-admin/`**: Claude Code가 [ultrareview](https://code.claude.com/docs/ko/ultrareview.md) 또는 [클라우드 세션 업로드](https://code.claude.com/docs/ko/claude-code-on-the-web.md#send-local-repositories-without-github)를 위해 저장소를 패키징하는 동안 만드는 임시 git 디렉터리입니다. 업로드가 끝나면, 또는 업로드가 중단된 경우 이후 세션에서, Claude Code는 해당 업로드의 디렉터리를 제거하고 `seed-admin/`은 그대로 둡니다.

145* **자동 메모리**: 스윕은 프로젝트의 [자동 메모리](https://code.claude.com/docs/ko/memory.md#auto-memory) 디렉토리 `projects/<project>/memory/`의 메모리 파일을 삭제하지 않습니다. Claude Code는 전체 보존 기간 동안 비어 있었던 경우에만 해당 디렉토리를 제거합니다. v2.1.228 이전에는 스윕이 메모리 디렉토리 내의 폴더를 세션 데이터로 취급하고 그 아래의 오래된 파일을 삭제할 수 있었습니다.146* **자동 메모리**: 스윕은 프로젝트의 [자동 메모리](https://code.claude.com/docs/ko/memory.md#auto-memory) 디렉토리 `projects/<project>/memory/`의 메모리 파일을 삭제하지 않습니다. Claude Code는 전체 보존 기간 동안 비어 있었던 경우에만 해당 디렉토리를 제거합니다. v2.1.228 이전에는 스윕이 메모리 디렉토리 내의 폴더를 세션 데이터로 취급하고 그 아래의 오래된 파일을 삭제할 수 있었습니다.

146* **Claude Desktop 및 Cowork 트랜스크립트**: Claude Code는 Claude Desktop 또는 Cowork에서 시작하거나 가장 최근에 계속한 세션의 트랜스크립트를 나이에 관계없이 유지합니다. 이 트랜스크립트에 나이 제한을 주려면 [`desktopSessionCleanupPeriodDays`](https://code.claude.com/docs/ko/settings-reference#desktopsessioncleanupperioddays)를 설정하세요. Claude Code v2.1.248 이상 필요; 이전 버전은 `cleanupPeriodDays` 후에 삭제합니다.147* **Claude Desktop 및 Cowork 트랜스크립트**: Claude Code는 Claude Desktop 또는 Cowork에서 시작하거나 가장 최근에 계속한 세션의 트랜스크립트를 나이에 관계없이 유지합니다. 이 트랜스크립트에 나이 제한을 주려면 [`desktopSessionCleanupPeriodDays`](https://code.claude.com/docs/ko/settings-reference#desktopsessioncleanupperioddays)를 설정하세요. Claude Code v2.1.248 이상 필요; 이전 버전은 `cleanupPeriodDays` 후에 삭제합니다.

147 148 

153Claude Code는 다음 경우에 나이 기반 스윕을 건너뜁니다:154Claude Code는 다음 경우에 나이 기반 스윕을 건너뜁니다:

154 155 

155* **Bare mode**: [`--bare`](https://code.claude.com/docs/ko/headless#start-faster-with-bare-mode)로 `claude -p`를 실행할 때, Claude Code는 해당 세션에서 스윕을 실행하지 않습니다.156* **Bare mode**: [`--bare`](https://code.claude.com/docs/ko/headless#start-faster-with-bare-mode)로 `claude -p`를 실행할 때, Claude Code는 해당 세션에서 스윕을 실행하지 않습니다.

156* **일시 중지된 스윕**: Claude Code가 보존 기간을 안전하게 결정할 수 없으면 보존 정리 스윕을 일시 중지합니다. [`retention_sweep` 이벤트](https://code.claude.com/docs/ko/monitoring-usage#retention-sweep-event)는 이를 일시 중지하는 각 구성을 나열합니다. 원인이 읽거나 구문 분석할 수 없는 설정 파일이거나 `cleanupPeriodDays` 또는 `desktopSessionCleanupPeriodDays`가 명시적으로 설정된 설정 오류인 경우, Claude Code는 설정 오류를 수정할 때까지 `/status`에 경고를 표시합니다. [관리 설정](https://code.claude.com/docs/ko/server-managed-settings.md)이 `cleanupPeriodDays`를 제공하면 Claude Code는 어느 경우든 관리 값에서 스윕을 실행합니다.157* **일시 중지된 스윕**: Claude Code가 보존 기간을 안전하게 결정할 수 없으면 스윕을 일시 중지합니다. [`retention_sweep` 이벤트](https://code.claude.com/docs/ko/monitoring-usage#retention-sweep-event)는 이를 일시 중지하는 각 구성을 나열합니다. 원인이 읽거나 구문 분석할 수 없는 설정 파일이거나 `cleanupPeriodDays` 또는 `desktopSessionCleanupPeriodDays`가 설정된 상태에서의 설정 오류인 경우, 원인을 수정할 때까지 `/status`에 경고가 표시됩니다.

158 

159[관리형 설정](https://code.claude.com/docs/ko/managed-settings.md)이 `cleanupPeriodDays`를 제공하면, 우선순위가 낮은 설정 파일에 오류가 있더라도 Claude Code는 관리 값으로 스윕을 실행합니다.

157 160 

158조직의 머신이 설정한 보존 기간으로 스윕을 실행하는지 확인하려면 [보존 스윕 확인](https://code.claude.com/docs/ko/monitoring-usage.md#check-the-retention-sweep)을 참조하세요.161조직의 머신이 설정한 보존 기간으로 스윕을 실행하는지 확인하려면 [보존 스윕 확인](https://code.claude.com/docs/ko/monitoring-usage.md#check-the-retention-sweep)을 참조하세요.

159 162 

claude-projects.md +24 −26

Details

20 20 

21* **한 곳으로 작업 전송**: 버그 보고서, 스택 추적 또는 작업 목록을 대화에 붙여넣으면 Claude가 각 작업에 대한 스레드를 시작하거나 이미 해당 영역에서 작업 중인 스레드로 전달하고 빠른 질문에 즉시 답변합니다.21* **한 곳으로 작업 전송**: 버그 보고서, 스택 추적 또는 작업 목록을 대화에 붙여넣으면 Claude가 각 작업에 대한 스레드를 시작하거나 이미 해당 영역에서 작업 중인 스레드로 전달하고 빠른 질문에 즉시 답변합니다.

22* **컨텍스트를 한 번 설정**: 모든 새 스레드는 프로젝트의 지침으로 시작하므로 대상 분기와 같이 한 번 명시한 규칙이 모든 스레드에 도달합니다.22* **컨텍스트를 한 번 설정**: 모든 새 스레드는 프로젝트의 지침으로 시작하므로 대상 분기와 같이 한 번 명시한 규칙이 모든 스레드에 도달합니다.

23* **떠났다가 완료된 작업으로 돌아오기**: 한 시간 후 또는 다음 아침에 돌아오면 **개요** 창에 어느 스레드가 완료되었는지, 어느 풀 요청이 검토 준비가 되었는지, 어느 스레드가 사용자의 답변을 기다리고 있는지 표시됩니다.23* **떠났다가 완료된 작업으로 돌아오기**: 개요 창에 어느 스레드가 완료되었는지, 어느 풀 리퀘스트가 검토 준비가 되었는지, 어느 스레드가 사용자의 답변을 기다리고 있는지 표시됩니다.

24 24 

25이미 프로젝트가 실행하기를 원하는 작업을 알고 있다면 [프로젝트 생성](#create-a-project)으로 바로 이동하세요.25이미 프로젝트가 실행하기를 원하는 작업을 알고 있다면 [프로젝트 생성](#create-a-project)으로 바로 이동하세요.

26 26 

28 28 

29프로젝트는 한 세션보다 오래 지속되고 계속 작업을 생성하는 목표가 있을 때 생성할 가치가 있습니다. 이러한 종류의 작업이 프로젝트에 적합합니다:29프로젝트는 한 세션보다 오래 지속되고 계속 작업을 생성하는 목표가 있을 때 생성할 가치가 있습니다. 이러한 종류의 작업이 프로젝트에 적합합니다:

30 30 

31* **많은 저장소에 걸친 하나의 목표**: "모든 서비스를 새 lint 구성으로 업그레이드합니다." Claude는 저장소당 하나의 스레드를 실행할 수 있으며, 각각 자체 풀 요청을 가지고 있고, [**Overview** 창](#see-what-needs-you-in-overview)에 어느 것이 검토 준비가 되었는지 표시됩니다.31* **많은 저장소에 걸친 하나의 목표**: "모든 서비스를 새 lint 구성으로 업그레이드합니다." Claude는 저장소당 하나의 스레드를 실행할 수 있으며, 각각 자체 풀 리퀘스트를 가지고 있고, [Overview 창](#see-what-needs-you-in-overview)에 어느 것이 검토 준비가 되었는지 표시됩니다.

32* **계속 공급하는 영역**: 한 서비스에 대한 버그, 스택 추적 및 검토 요청을 대화에 붙여넣으면 도달합니다. 한 수정 후 Claude에게 기억하도록 말한 함정은 다음 수정을 위해 [프로젝트 메모리](#give-a-project-standing-context)에 있습니다.32* **계속 공급하는 영역**: 한 서비스에 대한 버그, 스택 추적 및 검토 요청을 대화에 붙여넣으면 도달합니다. 한 수정 후 Claude에게 기억하도록 말한 함정은 다음 수정을 위해 [프로젝트 메모리](#give-a-project-standing-context)에 있습니다.

33* **세션보다 큰 빌드 또는 마이그레이션**: "`docs/spec.md`가 설명하는 것을 빌드합니다" 또는 "앱을 더 이상 사용되지 않는 ORM에서 이동합니다." 작업은 각각 일부를 수행하는 스레드로 분할되고, Claude에게 초기에 기억하도록 요청한 결정이 나중 스레드에 도달하며, 빌드 중에 발견한 사양 변경 및 버그가 동일한 대화로 이동합니다.33* **세션보다 큰 빌드 또는 마이그레이션**: "`docs/spec.md`가 설명하는 것을 빌드합니다" 또는 "앱을 더 이상 사용되지 않는 ORM에서 이동합니다." 작업은 각각 일부를 수행하는 스레드로 분할되고, Claude에게 초기에 기억하도록 요청한 결정이 나중 스레드에 도달하며, 빌드 중에 발견한 사양 변경 및 버그가 동일한 대화로 이동합니다.

34* **코드가 아닌 작업**: 계약 폴더 또는 지원 티켓 내보내기를 계속 돌아와서 새로운 질문을 하는 경우, 예를 들어 "이 티켓에서 가장 일반적인 10가지 통합 실수를 찾습니다." 저장소를 추가하는 대신 문서를 업로드하고, 스레드는 프로젝트의 [**Library** 탭](#see-what-needs-you-in-overview)에 각 작성물을 파일로 제공합니다.34* **코드가 아닌 작업**: 계약 폴더 또는 지원 티켓 내보내기를 계속 돌아와서 새로운 질문을 하는 경우, 예를 들어 "이 티켓에서 가장 일반적인 10가지 통합 실수를 찾습니다." 저장소를 추가하는 대신 문서를 업로드하고, 스레드는 프로젝트의 [**Library**](#see-what-needs-you-in-overview)에 각 작성물을 파일로 제공합니다.

35 35 

36이 중 어느 것이든 작업 배치를 보내고, Claude에게 확인을 요청하지 않고 시작하도록 말한 뒤 자리를 비울 수 있습니다. 돌아오면 [**Waiting on you**](#see-what-needs-you-in-overview) 아래에서 사용자의 조치가 필요한 스레드를 찾을 수 있습니다. 또한 Claude에게 작업의 일부를 [클라우드 예약 작업](https://code.claude.com/docs/ko/routines.md)으로 일정에 따라 실행하도록 요청할 수도 있습니다. 이 중 하나가 상황이라면 [프로젝트를 생성](#create-a-project)하세요.36이 중 어느 것이든 작업 배치를 보내고, Claude에게 확인을 요청하지 않고 시작하도록 말한 뒤 자리를 비울 수 있습니다. 돌아오면 [**Waiting on you**](#see-what-needs-you-in-overview) 아래에서 사용자의 조치가 필요한 스레드를 찾을 수 있습니다. 또한 Claude에게 작업의 일부를 [클라우드 예약 작업](https://code.claude.com/docs/ko/routines.md)으로 일정에 따라 실행하도록 요청할 수도 있습니다. 이 중 하나가 상황이라면 [프로젝트를 생성](#create-a-project)하세요.

37 37 

57 * [프로젝트의 각 저장소](#what-threads-pick-up-from-your-repositories)에 있는 `CLAUDE.md`(단, 저장소의 스킬, `.claude/settings.json`, `.mcp.json`은 포함되지 않음)57 * [프로젝트의 각 저장소](#what-threads-pick-up-from-your-repositories)에 있는 `CLAUDE.md`(단, 저장소의 스킬, `.claude/settings.json`, `.mcp.json`은 포함되지 않음)

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

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

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

61 61 

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

63 63 

64대화를 통해 사용자에서 작업을 수행하는 스레드까지 이러한 부분들이 어떻게 연결되는지, **개요**가 그들의 상태를 추적하는 방식입니다:64대화를 통해 사용자에서 작업을 수행하는 스레드까지 이러한 부분들이 어떻게 연결되는지, 개요가 그들의 상태를 추적하는 방식입니다:

65 65 

66![프로젝트의 다이어그램입니다. 사용자가 프로젝트 대화에 작성하면 Claude가 답변하거나 스레드를 시작합니다. 각 클라우드 스레드는 자신의 브랜치에서 작업하고 작업이 필요할 때 풀 리퀘스트를 엽니다. 개요 창은 검토 준비 완료, 사용자 대기 중, 작업 중 등의 상태별로 스레드를 나열합니다.](https://mintcdn.com/claude-code/e8CLbxM17eD7cAiv/images/claude-projects-overview.svg?fit=max\&auto=format\&n=e8CLbxM17eD7cAiv\&q=85\&s=dbf446f69f0bbdb9961d21af207cb93b)66![프로젝트의 다이어그램입니다. 사용자가 프로젝트 대화에 작성하면 Claude가 답변하거나 스레드를 시작합니다. 각 클라우드 스레드는 자신의 브랜치에서 작업하고 작업이 필요할 때 풀 리퀘스트를 엽니다. 개요 창은 검토 준비 완료, 사용자 대기 중, 작업 중 등의 상태별로 스레드를 나열합니다.](https://mintcdn.com/claude-code/e8CLbxM17eD7cAiv/images/claude-projects-overview.svg?fit=max\&auto=format\&n=e8CLbxM17eD7cAiv\&q=85\&s=dbf446f69f0bbdb9961d21af207cb93b)

67 67 

96 96 

97* **이름**: **프로젝트** 목록에 프로젝트가 표시되는 방식입니다.97* **이름**: **프로젝트** 목록에 프로젝트가 표시되는 방식입니다.

98* **어떤 작업을 하시겠습니까?** (선택 사항): "p95 API 지연 시간을 200ms 이하로 유지"와 같이 프로젝트의 목표가 되는 한 줄입니다. 대화에서 Claude는 이를 향해 작업합니다. 목표가 없으면 Claude는 사용자가 보내는 작업에서 작업하며, 나중에 **프로젝트 설정 > 일반**에서 목표를 추가할 수 있습니다.98* **어떤 작업을 하시겠습니까?** (선택 사항): "p95 API 지연 시간을 200ms 이하로 유지"와 같이 프로젝트의 목표가 되는 한 줄입니다. 대화에서 Claude는 이를 향해 작업합니다. 목표가 없으면 Claude는 사용자가 보내는 작업에서 작업하며, 나중에 **프로젝트 설정 > 일반**에서 목표를 추가할 수 있습니다.

99* **컨텍스트** (선택 사항): 이 프로젝트가 작업할 GitHub 저장소와 스레드가 읽어야 할 파일, 폴더 또는 Google Drive 폴더입니다. 각각에 대해 **추가**를 클릭합니다. 작업이 만질 수 있는 모든 저장소가 아닌 대부분의 작업이 필요로 하는 저장소를 추가합니다. [추가할 저장소 결정하기](#decide-which-repositories-to-add)에서 선택 사항을 다룹니다. 나중에 **프로젝트 설정 > 환경**에서 더 추가할 수 있습니다.99* **컨텍스트** (선택 사항): 이 프로젝트가 작업할 GitHub 저장소와 스레드가 읽어야 할 파일, 폴더 또는 Google Drive 폴더입니다. 각각에 대해 \*\*+\*\*를 클릭합니다. 작업이 만질 수 있는 모든 저장소가 아닌 대부분의 작업이 필요로 하는 저장소를 추가합니다. [추가할 저장소 결정하기](#decide-which-repositories-to-add)에서 선택 사항을 다룹니다. 나중에 **프로젝트 설정 > 환경**에서 더 추가할 수 있습니다.

100 100 

101스레드가 어떻게 작동해야 하는지에 대한 상시 규칙은 [프로젝트 지침](#give-a-project-standing-context)에 들어가며, 이는 프로젝트가 존재한 후에 설정합니다.101스레드가 어떻게 작동해야 하는지에 대한 상시 규칙은 [프로젝트 지침](#give-a-project-standing-context)에 들어가며, 이는 프로젝트가 존재한 후에 설정합니다.

102 102 

109* 프로젝트에 읽을 수 있는 저장소가 있는 경우, 아무것도 변경하지 않고 저장소를 탐색하며 다음 단계를 제안하는 하나의 스레드를 시작합니다.109* 프로젝트에 읽을 수 있는 저장소가 있는 경우, 아무것도 변경하지 않고 저장소를 탐색하며 다음 단계를 제안하는 하나의 스레드를 시작합니다.

110* 최근 클라우드 세션에서 도출한 **설정 권장 사항**을 게시합니다: 추가할 저장소, 만들 예약 작업 및 시작할 수 있는 스레드입니다. 권장되는 모든 저장소와 예약 작업은 기본적으로 켜져 있습니다. 원하지 않는 것은 끄고 **설정 업데이트**를 클릭하여 나머지를 추가하거나, 권장 사항을 무시하고 직접 작업을 설명합니다.110* 최근 클라우드 세션에서 도출한 **설정 권장 사항**을 게시합니다: 추가할 저장소, 만들 예약 작업 및 시작할 수 있는 스레드입니다. 권장되는 모든 저장소와 예약 작업은 기본적으로 켜져 있습니다. 원하지 않는 것은 끄고 **설정 업데이트**를 클릭하여 나머지를 추가하거나, 권장 사항을 무시하고 직접 작업을 설명합니다.

111 111 

112프로젝트는 이제 사이드바의 **프로젝트** 아래에 나열되고 대화가 열려 있습니다. [첫 번째 배치](#your-first-batch)에서는 작업을 보내기 전에 설정할 사항을 다룹니다.112프로젝트는 이제 사이드바에 표시되고 대화가 열려 있습니다. [첫 번째 배치](#your-first-batch)에서는 작업을 보내기 전에 설정할 사항을 다룹니다.

113 113 

114### 기존 세션에서 시작하기114### 기존 세션에서 시작하기

115 115 

168 168 

169Claude가 원하는 것과 다르게 라우팅하면 그렇게 말합니다. [Claude가 프로젝트를 실행하는 방식 조정](#tune-how-claude-runs-a-project)에는 기존 스레드를 후속 작업에 재사용하거나 스레드를 시작하는 대신 제자리에서 답변하도록 하는 등 알려줄 수 있는 사항이 나열되어 있습니다.169Claude가 원하는 것과 다르게 라우팅하면 그렇게 말합니다. [Claude가 프로젝트를 실행하는 방식 조정](#tune-how-claude-runs-a-project)에는 기존 스레드를 후속 작업에 재사용하거나 스레드를 시작하는 대신 제자리에서 답변하도록 하는 등 알려줄 수 있는 사항이 나열되어 있습니다.

170 170 

171스레드의 전체 결과는 스레드에 남아 있으며, 대화에서 카드를 열어 읽습니다. 스레드가 생성한 파일은 **개요**의 **라이브러리** 탭에도 있습니다.171스레드의 전체 결과는 스레드에 남아 있으며, 대화에서 카드를 열어 읽습니다. 스레드가 생성한 파일은 프로젝트의 [**라이브러리**](#see-what-needs-you-in-overview)에도 있습니다.

172 172 

173때로 Claude는 스레드를 시작하는 대신 **제안된 스레드** 목록에서 스레드를 제안합니다. 제안의 화살표를 클릭하여 해당 스레드를 시작합니다. 여러 개가 나열되면, 목록 아래의 버튼이 모두 시작합니다.173때로 Claude는 스레드를 시작하는 대신 **제안된 스레드** 목록에서 스레드를 제안합니다. 제안의 화살표를 클릭하여 해당 스레드를 시작합니다. 여러 개가 나열되면, 목록 아래의 버튼이 모두 시작합니다.

174 174 

190 190 

191### 개요에서 필요한 것 확인191### 개요에서 필요한 것 확인

192 192 

193대화 옆의 **개요** 창은 프로젝트의 스레드를 추적합니다. 새 프로젝트를 처음 열 때 이미 열려 있습니다. 프로젝트 헤더의 **개요** 버튼은 이를 닫고 다시 열며, 스레드가 사용자를 기다리고 있을 때 점을 표시합니다.193대화 옆의 개요 창은 프로젝트의 스레드를 추적합니다. 새 프로젝트를 처음 열 때 이미 열려 있습니다. 닫은 후 다시 열려면 프로젝트 헤더의 **스레드** 버튼을 클릭합니다. 스레드가 사용자를 기다리고 있으면 이 버튼에 점이 표시됩니다.

194 194 

195데스크톱 앱에서는 Claude가 대화에 게시할 때, 스레드가 오류에 도달할 때, 또는 스레드가 사용자의 입력이 필요할 때 데스크톱 알림도 받으므로, 프로젝트를 열어 두고 있을 필요가 없습니다. 스레드가 턴을 완료할 때마다 알림을 받으려면 또는 프로젝트에 대해 알림을 끄려면, 프로젝트의 사이드바 메뉴에서 **알림**을 선택합니다. 이러한 알림은 데스크톱 전용입니다. 브라우저에서는 **개요** 버튼의 점을 확인합니다.195데스크톱 앱에서는 Claude가 대화에 게시할 때, 스레드에 오류가 발생할 때, 또는 스레드가 사용자의 입력이 필요할 때 기본적으로 알림이 표시됩니다. 프로젝트를 보고 있는 동안에는 알림이 표시되지 않습니다. 스레드가 턴을 완료할 때마다 알림도 받으려면 또는 프로젝트에 대해 알림을 끄려면, 프로젝트의 사이드바 메뉴에서 **알림**을 선택합니다. 브라우저에서는 **스레드** 버튼의 점을 확인합니다.

196 196 

197창의 **스레드** 탭은 스레드를 상태별로 그룹화합니다.197창의 **스레드** 보기는 스레드를 상태별로 그룹화합니다.

198 198 

199| 그룹 | 포함된 내용 |199| 그룹 | 포함된 내용 |

200| :- | :- |200| :- | :- |

205| **유휴** | 완료되었고 아무것도 기다리지 않는 스레드 |205| **유휴** | 완료되었고 아무것도 기다리지 않는 스레드 |

206| **해결됨** | 완료로 표시된 스레드: 스레드의 메뉴에서 사용자가, 풀 요청 병합 등 마지막 단계를 완료한 후 Claude가, 또는 활동이 없는 상태로 1주일 후 자동으로. 같은 메뉴에서 다시 열 수 있습니다. |206| **해결됨** | 완료로 표시된 스레드: 스레드의 메뉴에서 사용자가, 풀 요청 병합 등 마지막 단계를 완료한 후 Claude가, 또는 활동이 없는 상태로 1주일 후 자동으로. 같은 메뉴에서 다시 열 수 있습니다. |

207 207 

208창의 다른 탭은 다음과 같습니다.208프로젝트 헤더에서 프로젝트의 파일과 예약 작업을 창에 열 수 있습니다.

209 209 

210* **라이브러리**: 추가한 파일 및 폴더와 스레드가 생성한 파일210* **라이브러리**: 추가한 파일 및 폴더와 스레드가 생성한 파일입니다. **스레드** 옆의 **라이브러리** 버튼을 클릭합니다.

211* **풀 리퀘스트**: 스레드가 풀 리퀘스트를 연 후에 표시됩니다211* **예약 작업**: 이 프로젝트에서 Claude가 설정한 [클라우드 예약 작업](https://code.claude.com/docs/ko/routines.md)입니다. 헤더의 **⋯** 메뉴에서 선택합니다.

212* **예약 작업**: 이 프로젝트에서 Claude가 설정한 [클라우드 예약 작업](https://code.claude.com/docs/ko/routines.md)

213 212 

214### 제어가 필요할 때 스레드 열기213### 제어가 필요할 때 스레드 열기

215 214 

216대화의 스레드 카드 또는 **개요**의 행을 클릭하여 개요 창에서 스레드의 기록을 엽니다. 거기서 다음을 할 수 있습니다.215대화의 스레드 카드 또는 개요의 행을 클릭하여 개요 창에서 스레드의 트랜스크립트를 엽니다. 거기서 다음을 할 수 있습니다.

217 216 

218* Claude가 한 일을 단계별로 읽습니다.217* Claude가 한 일을 단계별로 읽습니다.

219* 스레드의 자체 메시지 상자에 작성하여 작업을 조정합니다. 거기의 메시지는 해당 스레드로 직접 가고, 프로젝트 대화의 후속은 Claude가 후속을 해당 스레드와 일치시킬 때만 도달합니다.218* 스레드의 자체 메시지 상자에 작성하여 작업을 조정합니다. 거기의 메시지는 해당 스레드로 직접 가고, 프로젝트 대화의 후속은 Claude가 후속을 해당 스레드와 일치시킬 때만 도달합니다.

290| :- | :- | :- |289| :- | :- | :- |

291| 프로젝트 메모리 | Claude가 프로젝트에 대해 유지하는 메모(요구사항, 결정사항, 주의사항 등)로, 파일로 저장됩니다. 모든 클라우드 스레드는 시작할 때 인덱스 파일 `MEMORY.md`를 읽고, 필요할 때 다른 파일을 엽니다 | 프로젝트 대화 또는 모든 클라우드 스레드에서 Claude에게 요구사항, 결정사항, 주의사항을 기억하거나 잊도록 요청합니다. **프로젝트 설정 > 메모리**에서 파일을 읽고, 편집하고, 삭제합니다 |290| 프로젝트 메모리 | Claude가 프로젝트에 대해 유지하는 메모(요구사항, 결정사항, 주의사항 등)로, 파일로 저장됩니다. 모든 클라우드 스레드는 시작할 때 인덱스 파일 `MEMORY.md`를 읽고, 필요할 때 다른 파일을 엽니다 | 프로젝트 대화 또는 모든 클라우드 스레드에서 Claude에게 요구사항, 결정사항, 주의사항을 기억하거나 잊도록 요청합니다. **프로젝트 설정 > 메모리**에서 파일을 읽고, 편집하고, 삭제합니다 |

292| 프로젝트 지침 | 모든 새로운 스레드와 프로젝트 대화의 Claude에게 전송되는 텍스트로, 최대 16,000자입니다. [프로젝트 지침 작성하기](#write-project-instructions)에서 포함할 내용을 다룹니다 | **프로젝트 설정 > 메모리 > 프로젝트 지침**, 또는 Claude에게 지침을 변경하도록 요청합니다 |291| 프로젝트 지침 | 모든 새로운 스레드와 프로젝트 대화의 Claude에게 전송되는 텍스트로, 최대 16,000자입니다. [프로젝트 지침 작성하기](#write-project-instructions)에서 포함할 내용을 다룹니다 | **프로젝트 설정 > 메모리 > 프로젝트 지침**, 또는 Claude에게 지침을 변경하도록 요청합니다 |

293| 저장소, 파일, 환경 | 모든 클라우드 스레드가 복제하는 저장소, 스레드가 `/mnt/project-files` 아래에서 읽을 수 있는 폴더와 파일, 그리고 스레드가 실행되는 클라우드 환경 | **프로젝트 설정 > 환경**의 저장소와 환경, 또는 대화에서 Claude에게 저장소를 프로젝트에 추가하도록 요청합니다. **개요**의 **라이브러리** 탭에서 **추가**를 통해 [파일과 폴더](#add-files-and-folders)를 추가합니다 |292| 저장소, 파일, 환경 | 모든 클라우드 스레드가 복제하는 저장소, 스레드가 `/mnt/project-files` 아래에서 읽을 수 있는 폴더와 파일, 그리고 스레드가 실행되는 클라우드 환경 | **프로젝트 설정 > 환경**의 저장소와 환경, 또는 대화에서 Claude에게 저장소를 프로젝트에 추가하도록 요청합니다. 프로젝트의 [**라이브러리**](#see-what-needs-you-in-overview)에서 **추가**를 통해 [파일과 폴더](#add-files-and-folders)를 추가합니다 |

294 293 

295**프로젝트 설정 > 메모리**는 이러한 파일을 **자동 메모리** 아래에 나열합니다. Claude가 프로젝트에서 작업할 때 자동으로 작성하기 때문입니다. 이는 Claude Code가 머신에서 유지하는 [자동 메모리](https://code.claude.com/docs/ko/memory.md)와는 별개이며, 둘 다 `MEMORY.md` 인덱스를 사용하지만 다릅니다. 프로젝트 메모리는 또한 프로젝트의 저장소에 있는 `CLAUDE.md` 파일과도 별개입니다. 각 클라우드 스레드는 시작할 때 복제본에서 이러한 `CLAUDE.md` 파일을 읽으므로, 저장소에 대한 지침은 해당 `CLAUDE.md`에 넣고 프로젝트에 대한 메모는 프로젝트 메모리에 넣습니다.294**프로젝트 설정 > 메모리**는 이러한 파일을 **자동 메모리** 아래에 나열합니다. Claude가 프로젝트에서 작업할 때 자동으로 작성하기 때문입니다. 이는 Claude Code가 머신에서 유지하는 [자동 메모리](https://code.claude.com/docs/ko/memory.md)와는 별개이며, 둘 다 `MEMORY.md` 인덱스를 사용하지만 다릅니다. 프로젝트 메모리는 또한 프로젝트의 저장소에 있는 `CLAUDE.md` 파일과도 별개입니다. 각 클라우드 스레드는 시작할 때 복제본에서 이러한 `CLAUDE.md` 파일을 읽으므로, 저장소에 대한 지침은 해당 `CLAUDE.md`에 넣고 프로젝트에 대한 메모는 프로젝트 메모리에 넣습니다.

296 295 

297### 프로젝트 지침 작성하기296### 프로젝트 지침 작성하기

298 297 

299프로젝트 지침은 모든 새로운 스레드가 시작하는 기본 지침입니다. 프로젝트 헤더의 톱니바퀴 아이콘을 클릭하여 **프로젝트 설정**을 열고, **메모리 > 프로젝트 지침**으로 이동합니다. 유용한 지침은 다음을 포함합니다:298프로젝트 지침은 모든 새로운 스레드가 시작하는 기본 지침입니다. 프로젝트 헤더의 **⋯** 메뉴에서 **설정**을 선택하여 **프로젝트 설정**을 열고, **메모리 > 프로젝트 지침**으로 이동합니다. 유용한 지침은 다음을 포함합니다:

300 299 

301* 프로젝트의 목적300* 프로젝트의 목적

302* 작업이 진행되는 위치: 어느 저장소, 어느 브랜치에서 시작할지, 풀 리퀘스트의 이름을 어떻게 지을지301* 작업이 진행되는 위치: 어느 저장소, 어느 브랜치에서 시작할지, 풀 리퀘스트의 이름을 어떻게 지을지

324* **프로젝트에 추가합니다**, **새 프로젝트** 대화에서, **프로젝트 설정 > 환경**에서, 또는 대화에서 Claude에게 프로젝트에 추가하도록 요청합니다. 그 이후 모든 클라우드 스레드는 작업이 이를 건드리든 아니든 이를 복제하고 `CLAUDE.md`를 로드하여 시작합니다.323* **프로젝트에 추가합니다**, **새 프로젝트** 대화에서, **프로젝트 설정 > 환경**에서, 또는 대화에서 Claude에게 프로젝트에 추가하도록 요청합니다. 그 이후 모든 클라우드 스레드는 작업이 이를 건드리든 아니든 이를 복제하고 `CLAUDE.md`를 로드하여 시작합니다.

325* **이를 제외하고 스레드가 필요할 때 추가하도록 합니다.** 프로젝트에 없는 저장소가 필요한 작업을 가진 클라우드 스레드는 자신에게 저장소를 추가할 수 있으며, 스레드의 메모는 이 스레드에만 추가되었음을 나타냅니다. 복제는 작업 중간에 발생하므로 해당 저장소의 `CLAUDE.md`는 스레드가 시작할 때 없었습니다. 다음 스레드는 해당 저장소 없이 시작합니다. 이런 방식으로 추가된 저장소는 프로젝트 저장소와 동일한 [사전 요구 사항](#check-the-prerequisites)이 필요합니다: 해당 저장소에 설치된 Claude GitHub App과 GitHub 계정의 푸시 액세스.324* **이를 제외하고 스레드가 필요할 때 추가하도록 합니다.** 프로젝트에 없는 저장소가 필요한 작업을 가진 클라우드 스레드는 자신에게 저장소를 추가할 수 있으며, 스레드의 메모는 이 스레드에만 추가되었음을 나타냅니다. 복제는 작업 중간에 발생하므로 해당 저장소의 `CLAUDE.md`는 스레드가 시작할 때 없었습니다. 다음 스레드는 해당 저장소 없이 시작합니다. 이런 방식으로 추가된 저장소는 프로젝트 저장소와 동일한 [사전 요구 사항](#check-the-prerequisites)이 필요합니다: 해당 저장소에 설치된 Claude GitHub App과 GitHub 계정의 푸시 액세스.

326 325 

327프로젝트에 저장소가 전혀 필요하지 않습니다. 클라우드 스레드는 여전히 조사하고, 문서를 작성하고, 자신의 샌드박스에서 코드를 작성하고 실행할 수 있으며, **라이브러리** 탭에 파일을 전달합니다. 프로젝트의 모든 클라우드 스레드는 작업에 필요할 때 여전히 자신에게 저장소를 추가할 수 있습니다.326프로젝트에 저장소가 전혀 필요하지 않습니다. 클라우드 스레드는 여전히 조사하고, 문서를 작성하고, 자신의 샌드박스에서 코드를 작성하고 실행할 수 있습니다. 클라우드 스레드는 프로젝트의 **라이브러리**에 파일을 전달합니다. 프로젝트의 모든 클라우드 스레드는 작업에 필요할 때 여전히 자신에게 저장소를 추가할 수 있습니다.

328 327 

329프로젝트에 저장소가 있으면, Claude는 프로젝트가 이미 사용하는 GitHub 소유자의 저장소만 추가할 수 있습니다. 프로젝트에 추가하든 스레드가 자신에게 추가하든 상관없습니다. 다른 소유자의 저장소를 가져오려면 **프로젝트 설정 > 환경**에서 직접 프로젝트에 추가하세요.328프로젝트에 저장소가 있으면, Claude는 프로젝트가 이미 사용하는 GitHub 소유자의 저장소만 추가할 수 있습니다. 프로젝트에 추가하든 스레드가 자신에게 추가하든 상관없습니다. 다른 소유자의 저장소를 가져오려면 **프로젝트 설정 > 환경**에서 직접 프로젝트에 추가하세요.

330 329 

332 331 

333### 파일과 폴더 추가하기332### 파일과 폴더 추가하기

334 333 

335**새 프로젝트** 대화의 **맥락** 필드에서, 또는 나중에 **개요**의 **라이브러리** 탭에서 **추가**를 사용하여 스레드가 읽기를 원하는 파일과 폴더를 추가합니다. 추가하는 것에 다음 제한이 적용됩니다:334**새 프로젝트** 대화의 **맥락** 필드에서, 또는 나중에 프로젝트의 [**라이브러리**](#see-what-needs-you-in-overview)에서 **추가**를 사용하여 스레드가 읽기를 원하는 파일과 폴더를 추가합니다. 추가하는 것에 다음 제한이 적용됩니다:

336 335 

337* **라이브러리 탭**: 한 번에 최대 100개 파일과 2GB, 단일 파일은 최대 480MB입니다.336* **claude.ai/code 또는 데스크톱 앱에서 업로드하는 파일**: 한 번에 최대 1,000개 파일과 2GB, 단일 파일은 최대 480MB입니다.

338* **새 프로젝트 대화**: 30MB를 초과하는 파일은 건너뛰므로, 프로젝트를 만든 후 **라이브러리** 탭에서 더 큰 파일을 추가합니다.337* **업로드하는 폴더**: 숨겨진 파일과 `node_modules`는 추가되지 않습니다. 프로젝트는 최대 10개의 폴더와 Google Drive 폴더를 함께 보유할 수 있으며, 단일 파일은 해당 제한에 포함되지 않습니다.

339* **폴더**: 두 곳 중 하나에서 폴더를 추가하면, 프로젝트는 첫 100개 파일의 복사본을 최대 200MB까지 받으며, 30MB를 초과하는 파일, 숨겨진 파일, `node_modules`는 포함되지 않습니다. 프로젝트는 최대 10개의 폴더와 Google Drive 폴더를 함께 보유할 수 있으며, 단일 파일은 해당 제한에 포함되지 않습니다.

340* **업로드 후 변경**: 업로드는 복사본이므로, 나중에 컴퓨터에서 변경한 내용은 파일을 다시 업로드하고 기존 이름에 대해 **바꾸기**를 선택할 때까지 프로젝트에 도달하지 않습니다.338* **업로드 후 변경**: 업로드는 복사본이므로, 나중에 컴퓨터에서 변경한 내용은 파일을 다시 업로드하고 기존 이름에 대해 **바꾸기**를 선택할 때까지 프로젝트에 도달하지 않습니다.

341 339 

342### 저장소에서 스레드가 가져오는 것340### 저장소에서 스레드가 가져오는 것

373 371 

374## 프로젝트 설정 참조372## 프로젝트 설정 참조

375 373 

376프로젝트 설정을 `settings.json`이 아닌 claude.ai/code 또는 데스크톱 앱에서 변경합니다. 프로젝트의 사이드바 메뉴의 **Settings**에서 또는 프로젝트 헤더의 기어 아이콘에서 **Project settings**를 엽니다.374프로젝트 설정을 `settings.json`이 아닌 claude.ai/code 또는 데스크톱 앱에서 변경합니다. 프로젝트의 사이드바 메뉴의 **Settings**에서 또는 프로젝트 헤더의 **⋯** 메뉴에서 **Project settings**를 엽니다.

377 375 

378설정은 변경할 때 저장됩니다. 목표 또는 지침과 같이 편집 중인 텍스트 필드는 떠날 때까지 **Save changes** 및 **Discard**를 표시합니다. **Project settings**의 지침, 저장소, 플러그인 및 환경 변경은 이미 실행 중인 스레드가 아닌 새 스레드에 도달합니다.376설정은 변경할 때 저장됩니다. 목표 또는 지침과 같이 편집 중인 텍스트 필드는 떠날 때까지 **Save changes** 및 **Discard**를 표시합니다. **Project settings**의 지침, 저장소, 플러그인 및 환경 변경은 이미 실행 중인 스레드가 아닌 새 스레드에 도달합니다.

379 377 

434 432 

435 프로젝트는 Pro, Max 및 Ultra에서 사용할 수 있습니다. 프로젝트는 개인 전용입니다: 사용자만 작업을 할당하거나 스레드를 볼 수 있으며, 자신의 GitHub 액세스 및 커넥터를 사용합니다. [Claude Tag가 Cowork 및 Claude Code와 어떻게 다른지](https://claude.com/docs/claude-tag/concepts/how-it-works#how-claude-tag-differs-from-cowork-and-claude-code)에서 나란히 비교한 내용을 확인할 수 있습니다.433 프로젝트는 Pro, Max 및 Ultra에서 사용할 수 있습니다. 프로젝트는 개인 전용입니다: 사용자만 작업을 할당하거나 스레드를 볼 수 있으며, 자신의 GitHub 액세스 및 커넥터를 사용합니다. [Claude Tag가 Cowork 및 Claude Code와 어떻게 다른지](https://claude.com/docs/claude-tag/concepts/how-it-works#how-claude-tag-differs-from-cowork-and-claude-code)에서 나란히 비교한 내용을 확인할 수 있습니다.

436* **클라우드 세션**: 모든 스레드는 Claude에게 머신에서 실행하도록 요청하지 않는 한 [클라우드 세션](https://code.claude.com/docs/ko/claude-code-on-the-web.md)입니다. 어느 쪽이든 사용자 대신 Claude가 세션을 시작하고 추적합니다. 직접 시작한 클라우드 세션의 작업을 프로젝트로 가져올 수도 있습니다: 해당 세션의 사이드바 메뉴에서 [**프로젝트로 이동**](#start-from-an-existing-cloud-session)을 선택합니다.434* **클라우드 세션**: 모든 스레드는 Claude에게 머신에서 실행하도록 요청하지 않는 한 [클라우드 세션](https://code.claude.com/docs/ko/claude-code-on-the-web.md)입니다. 어느 쪽이든 사용자 대신 Claude가 세션을 시작하고 추적합니다. 직접 시작한 클라우드 세션의 작업을 프로젝트로 가져올 수도 있습니다: 해당 세션의 사이드바 메뉴에서 [**프로젝트로 이동**](#start-from-an-existing-cloud-session)을 선택합니다.

437* **예약 작업**: 프로젝트에서 예약된 작업을 요청하면 Claude는 해당 프로젝트의 스레드로 실행되고 해당 프로젝트의 **예약 작업** 탭에 표시되는 [클라우드 예약 작업](https://code.claude.com/docs/ko/routines.md)을 생성합니다. 프로젝트 외부에서 생성한 예약 작업은 계속 독립적으로 작동합니다.435* **예약 작업**: 프로젝트에서 예약된 작업을 요청하면 Claude는 해당 프로젝트의 스레드로 실행되고 해당 프로젝트의 **예약 작업** 보기에 표시되는 [클라우드 예약 작업](https://code.claude.com/docs/ko/routines.md)을 생성합니다. 프로젝트 외부에서 생성한 예약 작업은 계속 독립적으로 작동합니다.

438* **원격 제어**: [원격 제어](https://code.claude.com/docs/ko/remote-control.md)는 claude.ai를 머신에서 실행 중인 Claude Code 세션에 연결합니다. 프로젝트에서 Claude에게 컴퓨터에서 스레드를 실행하도록 요청하면, 프로젝트는 [원격 제어를 사용하여 이를 수행합니다](#run-a-thread-on-your-own-computer).436* **원격 제어**: [원격 제어](https://code.claude.com/docs/ko/remote-control.md)는 claude.ai를 머신에서 실행 중인 Claude Code 세션에 연결합니다. 프로젝트에서 Claude에게 컴퓨터에서 스레드를 실행하도록 요청하면, 프로젝트는 [원격 제어를 사용하여 이를 수행합니다](#run-a-thread-on-your-own-computer).

439* **로컬 세션 및 에이전트 뷰**: 터미널, IDE 또는 데스크톱 앱의 로컬 환경에서 직접 시작한 세션은 프로젝트 외부에 남아 있지만, [해당 세션의 작업을 프로젝트로 가져올](#start-from-an-existing-cloud-session) 수 있습니다. [에이전트 뷰](https://code.claude.com/docs/ko/agent-view.md)는 여러 로컬 세션을 나란히 추적하기 위한 화면이며, 이 경우에도 사용자가 각 세션을 직접 시작하고 작업을 할당합니다.437* **로컬 세션 및 에이전트 뷰**: 터미널, IDE 또는 데스크톱 앱의 로컬 환경에서 직접 시작한 세션은 프로젝트 외부에 남아 있지만, [해당 세션의 작업을 프로젝트로 가져올](#start-from-an-existing-cloud-session) 수 있습니다. [에이전트 뷰](https://code.claude.com/docs/ko/agent-view.md)는 여러 로컬 세션을 나란히 추적하기 위한 화면이며, 이 경우에도 사용자가 각 세션을 직접 시작하고 작업을 할당합니다.

440* **Worktrees**: [worktree](https://code.claude.com/docs/ko/worktrees.md)는 각 로컬 세션에 저장소의 자체 작업 복사본을 제공합니다. 클라우드 스레드는 이를 필요로 하지 않습니다: 각 스레드는 저장소를 자체 클라우드 샌드박스에 복제하고 자체 브랜치에서 작동합니다.438* **Worktrees**: [worktree](https://code.claude.com/docs/ko/worktrees.md)는 각 로컬 세션에 저장소의 자체 작업 복사본을 제공합니다. 클라우드 스레드는 이를 필요로 하지 않습니다: 각 스레드는 저장소를 자체 클라우드 샌드박스에 복제하고 자체 브랜치에서 작동합니다.

466여러 스레드가 잘못된 가정을 하거나, 누락된 액세스를 우회하거나, "blocked" 상태로 멈춘 채 돌아온다면, 원인은 대개 각 작업의 문제라기보다 프로젝트 설정에 있는 동일한 공백입니다. 무엇이든 수정하기 전에 어떤 스레드가 정상인지 먼저 가려냅니다.464여러 스레드가 잘못된 가정을 하거나, 누락된 액세스를 우회하거나, "blocked" 상태로 멈춘 채 돌아온다면, 원인은 대개 각 작업의 문제라기보다 프로젝트 설정에 있는 동일한 공백입니다. 무엇이든 수정하기 전에 어떤 스레드가 정상인지 먼저 가려냅니다.

467 465 

4681. 대화에서 Claude에게 다음과 같이 요청합니다. "열려 있는 모든 스레드에 대해, 각 스레드에 무엇을 하라고 요청했는지, 스레드가 무엇을 가정했거나 무엇에 접근하지 못했는지, 그리고 무엇을 기다리고 있는지 나열해 줘." Claude는 각 스레드를 읽고 대화에서 답변합니다.4661. 대화에서 Claude에게 다음과 같이 요청합니다. "열려 있는 모든 스레드에 대해, 각 스레드에 무엇을 하라고 요청했는지, 스레드가 무엇을 가정했거나 무엇에 접근하지 못했는지, 그리고 무엇을 기다리고 있는지 나열해 줘." Claude는 각 스레드를 읽고 대화에서 답변합니다.

4692. 잘못된 가정에서 시작한 스레드는 **Overview**에서 해당 스레드를 열고 메뉴에서 해결됨으로 표시하거나, 메시지 상자에서 대신 무엇을 해야 하는지 알려 줍니다. 해당 스레드의 브랜치와 풀 리퀘스트는 삭제하기 전까지 GitHub에 남아 있습니다.4672. 잘못된 가정에서 시작한 스레드는 Overview에서 해당 스레드를 열고 메뉴에서 해결됨으로 표시하거나, 대신 무엇을 해야 하는지 알려 줍니다. 해당 스레드의 브랜치와 풀 리퀘스트는 삭제하기 전까지 GitHub에 남아 있습니다.

4703. [프로젝트 지침](#give-a-project-standing-context) 또는 [환경](#choose-an-environment-for-threads)에서 공백을 한 번에 수정한 다음, 나머지 작업을 새 스레드로 다시 보내기 전에 스레드 하나를 먼저 보내 봅니다.4683. [프로젝트 지침](#give-a-project-standing-context) 또는 [환경](#choose-an-environment-for-threads)에서 공백을 한 번에 수정한 다음, 나머지 작업을 새 스레드로 다시 보내기 전에 스레드 하나를 먼저 보내 봅니다.

471 469 

472### Claude hasn't responded470### Claude hasn't responded

Details

71 71 

72**2. 스캔할 항목 선택**72**2. 스캔할 항목 선택**

73 73 

74플러그인이 먼저 저장소를 읽은 후 전체 저장소 또는 집중된 영역을 제공합니다. 각 옵션의 파일 수와 상대 비용이 명시됩니다. 전체 저장소를 선택하거나 "I don't know"라고 답하면 플러그인이 저장소 크기에 맞는 합리적인 기본값을 선택합니다.74플러그인이 먼저 저장소를 읽은 후 전체 저장소 또는 집중된 영역을 제공합니다. 전체 저장소를 선택하거나 "I don't know"라고 답하면 플러그인이 저장소 크기에 맞는 합리적인 기본값을 선택합니다.

75 75 

76**3. 실행 확인**76**3. 실행 확인**

77 77 

87 87 

88**6. 수락한 패치 적용**88**6. 수락한 패치 적용**

89 89 

90셸에서 `git apply`로 각 패치를 자신의 풀 요청에 적용합니다. 패치는 자동으로 적용되지 않습니다.90셸에서 `git apply`로 각 패치를 적용하며, 패치마다 별도의 풀 리퀘스트로 만듭니다. 패치는 자동으로 적용되지 않습니다.

91 91 

92메뉴에서 시작할 필요가 없습니다. 명령에 대한 인수로 작업을 직접 요청할 수 있습니다. 예를 들어 `/claude-security scan my branch` 또는 일반 언어로 "scan commit abc1234"와 같이 요청할 수 있습니다. 플러그인은 [자동 모드](https://code.claude.com/docs/ko/permission-modes.md)에서 가장 잘 작동합니다. 이 모드는 스캔의 에이전트가 각 단계에서 권한 프롬프트 없이 진행할 수 있게 합니다.92메뉴에서 시작할 필요가 없습니다. 명령에 대한 인수로 작업을 직접 요청할 수 있습니다. 예를 들어 `/claude-security scan my branch` 또는 일반 언어로 "scan commit abc1234"와 같이 요청할 수 있습니다. 플러그인은 [자동 모드](https://code.claude.com/docs/ko/permission-modes.md)에서 가장 잘 작동합니다. 이 모드는 스캔의 에이전트가 각 단계에서 권한 프롬프트 없이 진행할 수 있게 합니다.

93 93 

95 95 

96브랜치에 기본이 없는 커밋이 있으면 `/claude-security` 메뉴는 해당 diff만 스캔하도록 제공합니다. 병합하기 전에 브랜치를 확인할 수 있습니다. 열린 풀 요청 중 하나를 스캔하거나 "scan commit abc1234"와 같이 요청하여 단일 커밋을 스캔할 수도 있습니다. 커밋된 변경 사항만 스캔됩니다. 진행 중인 편집을 먼저 커밋하거나 stash하거나 작업 트리를 읽는 전체 스캔을 실행하세요.96브랜치에 기본이 없는 커밋이 있으면 `/claude-security` 메뉴는 해당 diff만 스캔하도록 제공합니다. 병합하기 전에 브랜치를 확인할 수 있습니다. 열린 풀 요청 중 하나를 스캔하거나 "scan commit abc1234"와 같이 요청하여 단일 커밋을 스캔할 수도 있습니다. 커밋된 변경 사항만 스캔됩니다. 진행 중인 편집을 먼저 커밋하거나 stash하거나 작업 트리를 읽는 전체 스캔을 실행하세요.

97 97 

98변경 사항 스캔에는 git 저장소가 필요합니다. 버전 관리되지 않은 디렉토리의 전체 스캔은 여전히 작동합니다. 열린 풀 요청을 찾는 것은 네트워크에 도달하는 유일한 단계이며, 세션이 이미 GitHub CLI를 실행할 권한이 있고 `gh`가 로그인되어 있을 때만 제공됩니다.98변경 사항 스캔에는 git 저장소가 필요합니다. 버전 관리되지 않은 디렉토리의 전체 스캔은 여전히 작동합니다. 열린 풀 리퀘스트 찾기는 세션이 이미 GitHub CLI를 실행할 권한이 있고 `gh`가 로그인되어 있을 때만 제공됩니다.

99 99 

100### 대규모 저장소 범위 지정100### 대규모 저장소 범위 지정

101 101 

120* **`CLAUDE-SECURITY-RESULTS.md`**: 보고서. 각 발견 사항의 ID(예: `F1`), 영향, 악용 시나리오, 심각도, 신뢰도 및 권장 사항 포함120* **`CLAUDE-SECURITY-RESULTS.md`**: 보고서. 각 발견 사항의 ID(예: `F1`), 영향, 악용 시나리오, 심각도, 신뢰도 및 권장 사항 포함

121* **`CLAUDE-SECURITY-RESULTS.jsonl`**: 동일한 발견 사항을 기계 판독 가능한 형식으로 표현. 줄당 하나의 JSON 객체121* **`CLAUDE-SECURITY-RESULTS.jsonl`**: 동일한 발견 사항을 기계 판독 가능한 형식으로 표현. 줄당 하나의 JSON 객체

122* **`CLAUDE-SECURITY-RESULTS.sarif`**: 동일한 발견 사항을 [SARIF 2.1.0](https://docs.oasis-open.org/sarif/sarif/v2.1.0/sarif-v2.1.0.html) 로그로 표현. GitHub 코드 스캔 및 표준을 읽는 다른 도구용입니다. 스캔은 발견 사항을 [CWE](https://cwe.mitre.org/) 약점 범주로 분류합니다.122* **`CLAUDE-SECURITY-RESULTS.sarif`**: 동일한 발견 사항을 [SARIF 2.1.0](https://docs.oasis-open.org/sarif/sarif/v2.1.0/sarif-v2.1.0.html) 로그로 표현. GitHub 코드 스캔 및 표준을 읽는 다른 도구용입니다. 스캔은 발견 사항을 [CWE](https://cwe.mitre.org/) 약점 범주로 분류합니다.

123* **`CLAUDE-SECURITY-REVISION-<commit>.json`**: 수정 스탬프. 스캔된 커밋, 사용된 [스캔 강도](#choose-a-scan-effort), 커밋되지 않은 변경 사항이 스캔된 트리의 일부인지 여부, 실행이 얼마나 철저히 검증되었는지를 기록합니다. 이렇게 하면 보고서가 항상 설명하는 코드에 연결됩니다. 버전 관리 외부의 스캔은 커밋 대신 `UNVERSIONED`를 스탬프합니다.123* **`CLAUDE-SECURITY-REVISION-<commit>.json`**: 수정 스탬프. 스캔된 커밋, 사용된 [스캔 강도](#choose-a-scan-effort), 커밋되지 않은 변경 사항이 스캔된 트리의 일부인지 여부, 실행이 얼마나 철저히 검증되었는지를 기록합니다. 버전 관리 외부의 스캔은 커밋 대신 `UNVERSIONED`를 스탬프합니다.

124 124 

125해당 디렉토리는 스캔이 체크아웃에 수행하는 유일한 변경 사항이며, 자체 `.gitignore`를 포함하므로 실수로 `git add`를 하더라도 보고서가 커밋으로 스윕되지 않습니다. 감사 추적을 위해 보고서를 기록에 유지하려면 해당 `.gitignore` 파일 하나를 삭제하고 다른 디렉토리처럼 디렉토리를 커밋하세요.125해당 디렉토리는 스캔이 체크아웃에 수행하는 유일한 변경 사항이며, 자체 `.gitignore`를 포함하므로 실수로 `git add`를 하더라도 보고서가 커밋으로 스윕되지 않습니다. 감사 추적을 위해 보고서를 기록에 유지하려면 해당 `.gitignore` 파일 하나를 삭제하고 다른 디렉토리처럼 디렉토리를 커밋하세요.

126 126 

127발견 사항은 독립적인 검증자 에이전트가 분석한 후에만 보고서에 나타나므로 보고서가 짧고 읽을 가치가 있습니다. 스캔은 비결정적입니다. 동일한 코드의 두 스캔은 다른 발견 사항을 표시할 수 있습니다. 정기적으로 스캔을 실행하고 수정 스탬프를 사용하여 각 보고서를 다룬 정확한 코드 및 설정에 귀속시키세요.127발견 사항은 독립적인 검증자 에이전트가 분석한 후에만 보고서에 나타나므로 보고서가 짧고 읽을 가치가 있습니다. 스캔은 비결정적입니다. 동일한 코드의 두 스캔은 다른 발견 사항을 표시할 수 있습니다. 정기적으로 스캔을 실행하세요.

128 128 

129## 발견 사항 수정129## 발견 사항 수정

130 130 

Details

102* **역할**: 모든 요금제에서 역할과 관계없이 본인 환경에 시크릿을 추가하고 삭제할 수 있습니다. Team 및 Enterprise에서는 Owner가 claude.ai 조직에서 조직 관리자 역할을 보유하고 Admin은 보유하지 않으며, 이에 따라 다음 경우에 표시되는 내용이 달라집니다.102* **역할**: 모든 요금제에서 역할과 관계없이 본인 환경에 시크릿을 추가하고 삭제할 수 있습니다. Team 및 Enterprise에서는 Owner가 claude.ai 조직에서 조직 관리자 역할을 보유하고 Admin은 보유하지 않으며, 이에 따라 다음 경우에 표시되는 내용이 달라집니다.

103 * **본인 환경**: 조직 관리자 역할이 없으면 **Add secret**을 선택했을 때 [간소화된 양식](#add-a-secret-without-the-role)이 열립니다103 * **본인 환경**: 조직 관리자 역할이 없으면 **Add secret**을 선택했을 때 [간소화된 양식](#add-a-secret-without-the-role)이 열립니다

104 * **공유 환경**: Owner가 관리자 설정에서 [시크릿을 추가하고 삭제](#add-a-credential)합니다. 조직 관리자 역할이 없으면 환경의 대화 상자에 **Network secrets** 섹션이 없으므로 Owner에게 시크릿 추가를 요청하십시오104 * **공유 환경**: Owner가 관리자 설정에서 [시크릿을 추가하고 삭제](#add-a-credential)합니다. 조직 관리자 역할이 없으면 환경의 대화 상자에 **Network secrets** 섹션이 없으므로 Owner에게 시크릿 추가를 요청하십시오

105* **환경 유형**: 이미 존재하는 Anthropic 호스팅 클라우드 환경이어야 합니다. [자체 호스팅 환경](https://code.claude.com/docs/ko/self-hosted-environments)에는 네트워크 시크릿이 없습니다105* **환경 유형**: Anthropic 호스팅 클라우드 환경이어야 합니다. [자체 호스팅 환경](https://code.claude.com/docs/ko/self-hosted-environments)에는 네트워크 시크릿이 없습니다

106* **API 접근성**: 요청이 Anthropic의 네트워크에서 나가므로 API가 인터넷으로부터의 연결을 허용해야 합니다106* **API 접근성**: 요청이 Anthropic의 네트워크에서 나가므로 API가 인터넷으로부터의 연결을 허용해야 합니다

107* **암호화 키**: 조직에서 고객 관리형 암호화 키를 사용하는 경우 네트워크 시크릿을 저장할 수 없습니다107* **암호화 키**: 조직에서 고객 관리형 암호화 키를 사용하는 경우 네트워크 시크릿을 저장할 수 없습니다

108 108 

Details

14>14>

15> GitHub에서 저장소의 모든 풀 리퀘스트를 자동으로 리뷰하려면 Owner가 조직에 대해 켜는 관리형 서비스인 [Code Review](https://code.claude.com/docs/ko/code-review.md)를 참조하세요.15> GitHub에서 저장소의 모든 풀 리퀘스트를 자동으로 리뷰하려면 Owner가 조직에 대해 켜는 관리형 서비스인 [Code Review](https://code.claude.com/docs/ko/code-review.md)를 참조하세요.

16 16 

17`/review`는 `/code-review`의 별칭입니다. v2.1.223 이전에는 `/review`가 GitHub 풀 리퀘스트에 대해 단일 패스, 읽기 전용 리뷰를 실행하는 별도의 명령이었습니다.17`/review`는 `/code-review`의 별칭입니다.

18 18 

19**1. /code-review 실행**19**1. /code-review 실행**

20 20 

91* **`ultra`**: 리뷰는 기억된 수준을 사용하지도 업데이트하지도 않습니다91* **`ultra`**: 리뷰는 기억된 수준을 사용하지도 업데이트하지도 않습니다

92* **수준을 입력한 적 없음**: 리뷰는 세션의 현재 effort를 사용합니다92* **수준을 입력한 적 없음**: 리뷰는 세션의 현재 effort를 사용합니다

93 93 

94v2.1.223 이전에는 수준 없이 실행한 `/code-review`가 항상 세션의 현재 effort를 사용했습니다.

95 

96### GitLab 병합 요청에 발견 사항 게시94### GitLab 병합 요청에 발견 사항 게시

97 95 

98GitLab 병합 요청에 `--comment`를 전달하면 Claude Code는 GitLab의 `glab` CLI를 통해 발견 사항을 게시합니다. Claude Code v2.1.257 이상이 필요합니다. `glab`이 설치되어 있지 않으면 Claude는 대신 터미널에 발견 사항을 출력합니다.96GitLab 병합 요청에 `--comment`를 전달하면 Claude Code는 GitLab의 `glab` CLI를 통해 발견 사항을 게시합니다. Claude Code v2.1.257 이상이 필요합니다. `glab`이 설치되어 있지 않으면 Claude는 대신 터미널에 발견 사항을 출력합니다.

commands.md +2 −2

Details

104| `/install-github-app` | 저장소에 Claude GitHub App을 설치하며, 선택적으로 [GitHub Actions](https://code.claude.com/docs/ko/github-actions.md) 워크플로와 시크릿을 설정하는 단계가 포함됩니다. 저장소 선택과 통합 구성 과정을 안내합니다. github.com 저장소에서만 작동합니다. 저장소의 git 원격이 gitlab.com 또는 bitbucket.org에 있으면 명령이 설정을 시작하지 않고 안내를 출력한 후 종료됩니다. GitLab 파이프라인에서 Claude Code를 실행하려면 [GitLab CI/CD](https://code.claude.com/docs/ko/gitlab-ci-cd.md)를 참조하세요 |104| `/install-github-app` | 저장소에 Claude GitHub App을 설치하며, 선택적으로 [GitHub Actions](https://code.claude.com/docs/ko/github-actions.md) 워크플로와 시크릿을 설정하는 단계가 포함됩니다. 저장소 선택과 통합 구성 과정을 안내합니다. github.com 저장소에서만 작동합니다. 저장소의 git 원격이 gitlab.com 또는 bitbucket.org에 있으면 명령이 설정을 시작하지 않고 안내를 출력한 후 종료됩니다. GitLab 파이프라인에서 Claude Code를 실행하려면 [GitLab CI/CD](https://code.claude.com/docs/ko/gitlab-ci-cd.md)를 참조하세요 |

105| `/install-slack-app` | Claude Slack 앱을 설치합니다. OAuth 흐름을 완료하기 위해 브라우저를 엽니다 |105| `/install-slack-app` | Claude Slack 앱을 설치합니다. OAuth 흐름을 완료하기 위해 브라우저를 엽니다 |

106| `/keybindings` | [키보드 단축키](https://code.claude.com/docs/ko/keybindings.md) 파일을 엽니다 |106| `/keybindings` | [키보드 단축키](https://code.claude.com/docs/ko/keybindings.md) 파일을 엽니다 |

107| `/list-agents` | Claude가 메시지를 보낼 수 있는 서브에이전트, [에이전트 팀](https://code.claude.com/docs/ko/agent-teams.md) 팀원, 기타 Claude Code 세션을 각각 사용할 이름과 함께 나열합니다. [세션 간 메시징](https://code.claude.com/docs/ko/cross-session-messaging.md)을 참조하세요. `/peers`로도 사용할 수 있습니다. Claude Code v2.1.224 이상이 필요하며, 이전 버전에서는 `Unknown command: /list-agents`가 표시됩니다. 팀원 행과 이 세션 자체의 이름을 보여주는 첫 줄은 v2.1.239 이상이 필요합니다. [세션 간 메시징이 활성화된](https://code.claude.com/docs/ko/cross-session-messaging.md#availability) 세션에서만 사용할 수 있습니다 |107| `/list-agents` | Claude가 메시지를 보낼 수 있는 서브에이전트, [에이전트 팀](https://code.claude.com/docs/ko/agent-teams.md) 팀원, 기타 Claude Code 세션을 각각 사용할 이름과 함께 나열합니다. [세션 간 메시징](https://code.claude.com/docs/ko/cross-session-messaging.md)을 참조하세요. `/peers`로도 사용할 수 있습니다. 팀원 행과 이 세션 자체의 이름을 보여주는 첫 줄은 v2.1.239 이상이 필요합니다. [세션 간 메시징이 활성화된](https://code.claude.com/docs/ko/cross-session-messaging.md#availability) 세션에서만 사용할 수 있습니다 |

108| `/login` | Anthropic 계정에 로그인합니다 |108| `/login` | Anthropic 계정에 로그인합니다 |

109| `/logout` | Anthropic 계정에서 로그아웃합니다 |109| `/logout` | Anthropic 계정에서 로그아웃합니다 |

110| `/loop [interval] [prompt]` | **[스킬](https://code.claude.com/docs/ko/skills.md#bundled-skills).** 세션이 열려 있는 동안 프롬프트를 반복 실행합니다. 간격을 생략하면 Claude가 [반복 간격을 스스로 조절](https://code.claude.com/docs/ko/scheduled-tasks.md#let-claude-choose-the-interval)합니다. 프롬프트를 생략하면 Claude가 [기본 제공 유지 관리 프롬프트](https://code.claude.com/docs/ko/scheduled-tasks.md#run-the-built-in-maintenance-prompt) 또는 사용자의 [`loop.md`](https://code.claude.com/docs/ko/scheduled-tasks#customize-the-default-prompt-with-loop-md)를 실행합니다. 예: `/loop 5m check if the deploy finished`. [일정에 따라 프롬프트 실행](https://code.claude.com/docs/ko/scheduled-tasks.md)을 참조하세요. 별칭: `/proactive` |110| `/loop [interval] [prompt]` | **[스킬](https://code.claude.com/docs/ko/skills.md#bundled-skills).** 세션이 열려 있는 동안 프롬프트를 반복 실행합니다. 간격을 생략하면 Claude가 [반복 간격을 스스로 조절](https://code.claude.com/docs/ko/scheduled-tasks.md#let-claude-choose-the-interval)합니다. 프롬프트를 생략하면 Claude가 [기본 제공 유지 관리 프롬프트](https://code.claude.com/docs/ko/scheduled-tasks.md#run-the-built-in-maintenance-prompt) 또는 사용자의 [`loop.md`](https://code.claude.com/docs/ko/scheduled-tasks#customize-the-default-prompt-with-loop-md)를 실행합니다. 예: `/loop 5m check if the deploy finished`. [일정에 따라 프롬프트 실행](https://code.claude.com/docs/ko/scheduled-tasks.md)을 참조하세요. 별칭: `/proactive` |

132| `/rename [name]` | 현재 세션의 이름을 바꾸고 프롬프트 바에 이름을 표시합니다. 이름을 지정하지 않으면 대화 기록에서 자동으로 생성합니다. 비대화형 모드(`-p`)에서도 사용할 수 있습니다. claude.ai와 데스크톱 앱을 포함한 모든 이름 변경 사용 환경에서, Claude Code는 새 이름의 제어 문자와 보이지 않는 문자를 공백으로 바꾸고 이름을 200자로 제한합니다. 보이지 않는 문자를 제거한 후 이름이 비어 있으면 Claude Code는 이를 거부하고 `That name is empty once invisible characters are removed. Usage: /rename <name>`을 표시합니다. 문자 대체와 길이 제한은 Claude Code v2.1.221 이상이 필요합니다 |132| `/rename [name]` | 현재 세션의 이름을 바꾸고 프롬프트 바에 이름을 표시합니다. 이름을 지정하지 않으면 대화 기록에서 자동으로 생성합니다. 비대화형 모드(`-p`)에서도 사용할 수 있습니다. claude.ai와 데스크톱 앱을 포함한 모든 이름 변경 사용 환경에서, Claude Code는 새 이름의 제어 문자와 보이지 않는 문자를 공백으로 바꾸고 이름을 200자로 제한합니다. 보이지 않는 문자를 제거한 후 이름이 비어 있으면 Claude Code는 이를 거부하고 `That name is empty once invisible characters are removed. Usage: /rename <name>`을 표시합니다. 문자 대체와 길이 제한은 Claude Code v2.1.221 이상이 필요합니다 |

133| `/restart` | Claude Code를 다시 시작하고 이 세션을 재개하여 설치된 업데이트를 적용합니다. 업데이트가 설치된 후 하단 바에서 이 명령을 제안하면 실행합니다. Pro, Max 또는 Ultra 플랜과 WSL이 아닌 macOS 또는 Linux의 네이티브 설치가 필요합니다. Claude Code v2.1.288 이상이 필요합니다. 별칭: `/update` |133| `/restart` | Claude Code를 다시 시작하고 이 세션을 재개하여 설치된 업데이트를 적용합니다. 업데이트가 설치된 후 하단 바에서 이 명령을 제안하면 실행합니다. Pro, Max 또는 Ultra 플랜과 WSL이 아닌 macOS 또는 Linux의 네이티브 설치가 필요합니다. Claude Code v2.1.288 이상이 필요합니다. 별칭: `/update` |

134| `/resume [session]` | ID나 이름으로 대화를 재개하거나 세션 선택기를 엽니다. [백그라운드 세션](https://code.claude.com/docs/ko/agent-view.md)은 선택기에 `bg` 표시와 함께 나타납니다. 선택기에서 또는 ID나 이름으로 아직 실행 중인 세션을 재개하면 [해당 세션이 열립니다](https://code.claude.com/docs/ko/sessions.md#resume-a-running-background-session). 현재 대화는 백그라운드로 이동하고 이 터미널은 실행 중인 세션에 연결됩니다. 빈 프롬프트에서 `←`를 누르면 에이전트 보기로 돌아가며, 여기에는 떠나온 대화도 나열됩니다. v2.1.285 이전에는 Claude Code가 이를 거부하고 `claude attach`로 세션을 열거나 먼저 중지하라고 안내했습니다. 별칭: `/continue` |134| `/resume [session]` | ID나 이름으로 대화를 재개하거나 세션 선택기를 엽니다. [백그라운드 세션](https://code.claude.com/docs/ko/agent-view.md)은 선택기에 `bg` 표시와 함께 나타납니다. 선택기에서 또는 ID나 이름으로 아직 실행 중인 세션을 재개하면 [해당 세션이 열립니다](https://code.claude.com/docs/ko/sessions.md#resume-a-running-background-session). 현재 대화는 백그라운드로 이동하고 이 터미널은 실행 중인 세션에 연결됩니다. 빈 프롬프트에서 `←`를 누르면 에이전트 보기로 돌아가며, 여기에는 떠나온 대화도 나열됩니다. v2.1.285 이전에는 Claude Code가 이를 거부하고 `claude attach`로 세션을 열거나 먼저 중지하라고 안내했습니다. 별칭: `/continue` |

135| `/review [low\|medium\|high\|xhigh\|max\|ultra] [--fix] [--comment] [--max-findings n\|all\|default] [pr#\|branch\|path]` | [`/code-review`](https://code.claude.com/docs/ko/code-review-local)의 별칭입니다. 현재 diff 또는 전달한 PR 번호, 브랜치, 경로(예: `/review 1234`)를 리뷰하며, 동일한 effort 수준과 플래그를 받습니다. 수준을 지정하지 않으면 마지막으로 입력한 `low`부터 `max`까지의 수준을 재사용합니다. 정확한 규칙은 [`/code-review`로 로컬에서 리뷰하기](https://code.claude.com/docs/ko/code-review-local)를 참조하세요. 심층 클라우드 리뷰에는 [`/code-review ultra`](https://code.claude.com/docs/ko/ultrareview)를 사용합니다. v2.1.223 이전에는 `/review`가 번호로 지정한 GitHub 풀 리퀘스트에 대해 단일 패스의 읽기 전용 리뷰를 실행하는 별도의 명령이었으며, 인수 없이 실행하면 선택할 수 있도록 열린 PR을 나열했습니다. v2.1.186부터 v2.1.201까지는 `/code-review medium`과 동일한 멀티 에이전트 엔진을 실행했습니다 |135| `/review [low\|medium\|high\|xhigh\|max\|ultra] [--fix] [--comment] [--max-findings n\|all\|default] [pr#\|branch\|path]` | [`/code-review`](https://code.claude.com/docs/ko/code-review-local)의 별칭입니다. 현재 diff 또는 전달한 PR 번호, 브랜치, 경로(예: `/review 1234`)를 리뷰하며, 동일한 effort 수준과 플래그를 받습니다. 수준을 지정하지 않으면 마지막으로 입력한 `low`부터 `max`까지의 수준을 재사용합니다. 정확한 규칙은 [`/code-review`로 로컬에서 리뷰하기](https://code.claude.com/docs/ko/code-review-local)를 참조하세요. 심층 클라우드 리뷰에는 [`/code-review ultra`](https://code.claude.com/docs/ko/ultrareview)를 사용합니다 |

136| `/rewind` | 대화 및/또는 코드를 이전 시점으로 되감거나, 선택한 메시지부터 요약합니다. [체크포인트](https://code.claude.com/docs/ko/checkpointing.md)를 참조하세요. 별칭: `/checkpoint`, `/undo` |136| `/rewind` | 대화 및/또는 코드를 이전 시점으로 되감거나, 선택한 메시지부터 요약합니다. [체크포인트](https://code.claude.com/docs/ko/checkpointing.md)를 참조하세요. 별칭: `/checkpoint`, `/undo` |

137| `/run` | **[스킬](https://code.claude.com/docs/ko/skills.md#bundled-skills).** 테스트 통과뿐 아니라 변경 사항이 실제로 작동하는지 확인하기 위해 프로젝트의 앱을 실행하고 조작합니다. [앱 실행 및 검증](https://code.claude.com/docs/ko/skills.md#run-and-verify-your-app)을 참조하세요 |137| `/run` | **[스킬](https://code.claude.com/docs/ko/skills.md#bundled-skills).** 테스트 통과뿐 아니라 변경 사항이 실제로 작동하는지 확인하기 위해 프로젝트의 앱을 실행하고 조작합니다. [앱 실행 및 검증](https://code.claude.com/docs/ko/skills.md#run-and-verify-your-app)을 참조하세요 |

138| `/run-skill-generator` | **[스킬](https://code.claude.com/docs/ko/skills.md#bundled-skills).** 프로젝트별 [스킬](https://code.claude.com/docs/ko/skills.md#run-and-verify-your-app)을 작성하여 `/run`과 `/verify`가 깨끗한 환경에서 프로젝트의 앱을 빌드하고, 실행하고, 조작하는 방법을 학습하도록 합니다 |138| `/run-skill-generator` | **[스킬](https://code.claude.com/docs/ko/skills.md#bundled-skills).** 프로젝트별 [스킬](https://code.claude.com/docs/ko/skills.md#run-and-verify-your-app)을 작성하여 `/run`과 `/verify`가 깨끗한 환경에서 프로젝트의 앱을 빌드하고, 실행하고, 조작하는 방법을 학습하도록 합니다 |

costs.md +6 −6

Details

292 292 

293사용자 정의 [훅](https://code.claude.com/docs/ko/hooks.md)은 Claude가 보기 전에 데이터를 전처리할 수 있습니다. Claude가 10,000줄 로그 파일을 읽어 오류를 찾는 대신, 훅은 `ERROR`를 grep하고 일치하는 줄만 반환하여 컨텍스트를 수만 개의 토큰에서 수백 개로 줄일 수 있습니다.293사용자 정의 [훅](https://code.claude.com/docs/ko/hooks.md)은 Claude가 보기 전에 데이터를 전처리할 수 있습니다. Claude가 10,000줄 로그 파일을 읽어 오류를 찾는 대신, 훅은 `ERROR`를 grep하고 일치하는 줄만 반환하여 컨텍스트를 수만 개의 토큰에서 수백 개로 줄일 수 있습니다.

294 294 

295[스킬](https://code.claude.com/docs/ko/skills.md)은 Claude에게 도메인 지식을 제공하여 탐색할 필요가 없도록 할 수 있습니다. 예를 들어, "codebase-overview" 스킬은 프로젝트의 아키텍처, 주요 디렉토리 및 명명 규칙을 설명할 수 있습니다. Claude가 스킬을 호출하면, 구조를 이해하기 위해 여러 파일을 읽는 데 토큰을 소비하는 대신 즉시 이 컨텍스트를 얻습니다.295이 PreToolUse 훅은 테스트 출력을 마지막 100줄로 줄입니다:

296 

297예를 들어, 이 PreToolUse 훅은 테스트 출력을 필터링하여 실패만 표시합니다:

298 296 

299> [tab] settings.json297> [tab] settings.json

300>298>

320 318 

321> [tab] filter-test-output.sh319> [tab] filter-test-output.sh

322>320>

323> 훅은 이 스크립트를 호출합니다. `mkdir -p ~/.claude/hooks`로 폴더를 만들고, 아래 스크립트를 `~/.claude/hooks/filter-test-output.sh`로 저장한 다음, `chmod +x ~/.claude/hooks/filter-test-output.sh`로 실행 가능하게 만드십시오. 명령이 테스트 러너인지 확인하고 실패만 표시하도록 수정합니다:321> 훅은 이 스크립트를 호출합니다. `mkdir -p ~/.claude/hooks`로 폴더를 만들고, 아래 스크립트를 `~/.claude/hooks/filter-test-output.sh`로 저장한 다음, `chmod +x ~/.claude/hooks/filter-test-output.sh`로 실행 가능하게 만드십시오. 명령이 테스트 러너인지 확인하고, 그렇다면 출력의 마지막 100줄만 유지합니다:

324>322>

325> ```bash theme={null}323> ```bash theme={null}

326> #!/bin/bash324> #!/bin/bash

327> input=$(cat)325> input=$(cat)

328> cmd=$(echo "$input" | jq -r '.tool_input.command')326> cmd=$(echo "$input" | jq -r '.tool_input.command')

329>327>

330> # If running tests, filter to show only failures328> # If running tests, keep only the last 100 lines

331> pattern='^(npm test|pytest|go test)( [^;&|<>`$#\\[:cntrl:]]*)?$'329> pattern='^(npm test|pytest|go test)( [^;&|<>`$#\\[:cntrl:]]*)?$'

332> if [[ "$cmd" =~ $pattern ]]; then330> if [[ "$cmd" =~ $pattern ]]; then

333> filtered_cmd="$cmd 2>&1 | grep -A 5 -E '(FAIL|ERROR|error:)' | head -100"331> filtered_cmd="$cmd 2>&1 | tail -n 100"

334> echo "$input" | jq --arg filtered "$filtered_cmd" \332> echo "$input" | jq --arg filtered "$filtered_cmd" \

335> '{hookSpecificOutput: {hookEventName: "PreToolUse", updatedInput: (.tool_input + {command: $filtered})}}'333> '{hookSpecificOutput: {hookEventName: "PreToolUse", updatedInput: (.tool_input + {command: $filtered})}}'

336> else334> else

340 338 

341설정을 확인하려면 `/hooks`를 실행하고 훅이 PreToolUse 아래에 나타나는지 확인하십시오. `claude --debug-file ./claude-debug.txt`로 Claude Code를 시작하고 Claude에게 `npm test`를 실행하도록 요청할 수도 있습니다. 훅이 명령을 다시 쓸 때, 해당 로그 파일에는 `command`와 다른 Bash 입력 필드를 나열하는 `modified tool input keys` 줄이 포함됩니다.339설정을 확인하려면 `/hooks`를 실행하고 훅이 PreToolUse 아래에 나타나는지 확인하십시오. `claude --debug-file ./claude-debug.txt`로 Claude Code를 시작하고 Claude에게 `npm test`를 실행하도록 요청할 수도 있습니다. 훅이 명령을 다시 쓸 때, 해당 로그 파일에는 `command`와 다른 Bash 입력 필드를 나열하는 `modified tool input keys` 줄이 포함됩니다.

342 340 

341[스킬](https://code.claude.com/docs/ko/skills.md)은 Claude에게 도메인 지식을 제공하여 탐색할 필요가 없도록 할 수 있습니다. 예를 들어, "codebase-overview" 스킬은 프로젝트의 아키텍처, 주요 디렉토리 및 명명 규칙을 설명할 수 있습니다. Claude가 스킬을 호출하면, 구조를 이해하기 위해 여러 파일을 읽는 데 토큰을 소비하는 대신 즉시 이 컨텍스트를 얻습니다.

342 

343### CLAUDE.md에서 스킬로 지침 이동343### CLAUDE.md에서 스킬로 지침 이동

344 344 

345[CLAUDE.md](https://code.claude.com/docs/ko/memory.md) 파일은 세션 시작 시 컨텍스트에 로드됩니다. PR 검토 또는 데이터베이스 마이그레이션과 같은 특정 워크플로에 대한 자세한 지침이 포함되어 있으면, 관련 없는 작업을 수행할 때도 해당 토큰이 존재합니다. [스킬](https://code.claude.com/docs/ko/skills.md)은 호출될 때만 필요에 따라 로드되므로, 특화된 지침을 스킬로 이동하면 기본 컨텍스트를 더 작게 유지합니다. CLAUDE.md를 필수 항목만 포함하여 200줄 이하로 유지하십시오.345[CLAUDE.md](https://code.claude.com/docs/ko/memory.md) 파일은 세션 시작 시 컨텍스트에 로드됩니다. PR 검토 또는 데이터베이스 마이그레이션과 같은 특정 워크플로에 대한 자세한 지침이 포함되어 있으면, 관련 없는 작업을 수행할 때도 해당 토큰이 존재합니다. [스킬](https://code.claude.com/docs/ko/skills.md)은 호출될 때만 필요에 따라 로드되므로, 특화된 지침을 스킬로 이동하면 기본 컨텍스트를 더 작게 유지합니다. CLAUDE.md를 필수 항목만 포함하여 200줄 이하로 유지하십시오.

Details

56 56 

57### 메시지 전달57### 메시지 전달

58 58 

59수신 Claude는 활성 턴 중에 도구 호출 사이에서 메시지를 읽으므로, 실행 중인 도구는 절대 중단되지 않습니다. 수신 세션이 유휴 상태일 때, Claude Code는 메시지와 함께 새로운 턴을 시작합니다.59수신 Claude는 활성 턴 중에 도구 호출 사이에서 메시지를 읽습니다. 수신 세션이 유휴 상태일 때, Claude Code는 메시지와 함께 새로운 턴을 시작합니다.

60 60 

61다른 세션의 메시지는 일반 텍스트로 도착합니다. 파일이나 [MCP 리소스](https://code.claude.com/docs/ko/mcp.md#use-mcp-resources)를 `@`로 언급하면, Claude는 언급을 작성된 그대로 보고 Claude Code는 메시지가 새로운 턴을 시작하든 기존 턴 중에 도착하든 아무것도 첨부하지 않습니다. Claude는 여전히 수신 컴퓨터에서 언급된 경로를 자신의 도구로 열 수 있으며, 이는 해당 세션의 권한에 따릅니다.61다른 세션의 메시지는 일반 텍스트로 도착합니다. 파일이나 [MCP 리소스](https://code.claude.com/docs/ko/mcp.md#use-mcp-resources)를 `@`로 언급하면, Claude는 언급을 작성된 그대로 보고 Claude Code는 메시지가 새로운 턴을 시작하든 기존 턴 중에 도착하든 아무것도 첨부하지 않습니다. Claude는 여전히 수신 컴퓨터에서 언급된 경로를 자신의 도구로 열 수 있으며, 이는 해당 세션의 권한에 따릅니다.

62 62 

desktop.md +4 −4

Details

256 256 

257### 패널 최소화하기257### 패널 최소화하기

258 258 

259Terminal, Browser 또는 [iOS Simulator](https://code.claude.com/docs/ko/desktop-ios-simulator.md)를 작은 크기로 계속 보이게 하려면 패널 헤더에서 **Minimize**를 클릭합니다. 이 버튼을 사용하려면 Claude Desktop v4.0.0 이상과 [서드파티 제공업체](https://code.claude.com/docs/ko/third-party-integrations.md)가 아닌 Claude 계정이 필요합니다. Browser 패널에서는 로컬 세션에서만 이 버튼을 사용할 수 있습니다.259Terminal, Browser, [iOS Simulator](https://code.claude.com/docs/ko/desktop-ios-simulator.md) 또는 [사이드 채팅](#ask-a-side-question-without-derailing-the-session)을 작은 크기로 계속 보이게 하려면 패널 헤더에서 **Minimize**를 클릭합니다. 이 버튼을 사용하려면 Claude Desktop v4.0.0 이상과 [서드파티 제공업체](https://code.claude.com/docs/ko/third-party-integrations.md)가 아닌 Claude 계정이 필요합니다. Browser 패널에서는 로컬 세션에서만 이 버튼을 사용할 수 있습니다.

260 260 

261최소화된 패널은 [세션 세부 정보 패널](#see-session-details)이 화면에 표시되어 있는 동안에는 그 패널 안에 위치하고, 그렇지 않으면 채팅의 한쪽 모서리에 떠 있습니다:261최소화된 패널은 [세션 세부 정보 패널](#see-session-details)이 화면에 표시되어 있는 동안에는 그 패널 안에 위치하고, 그렇지 않으면 채팅의 한쪽 모서리에 떠 있습니다:

262 262 

1380* **워크플로**: Desktop은 각 새 [워크플로](https://code.claude.com/docs/ko/workflows.md)가 시작되기 전에 이를 확인하므로, Desktop 연결이 끊긴 동안에는 새 워크플로가 최대 10분간 대기한 후 실패합니다1380* **워크플로**: Desktop은 각 새 [워크플로](https://code.claude.com/docs/ko/workflows.md)가 시작되기 전에 이를 확인하므로, Desktop 연결이 끊긴 동안에는 새 워크플로가 최대 10분간 대기한 후 실패합니다

1381* **MCP 서버**: Claude Code가 원격 머신에서 시작하는 MCP 서버는 Desktop을 거치지 않으므로 Claude가 해당 도구를 계속 호출할 수 있습니다. `claude_desktop_config.json`의 서버는 Desktop이 [기본 제공 SSH 클라이언트](#worktree-edits-while-disconnected)를 사용하지 않는 경우에만 여기에 포함됩니다. 그렇지 않은 경우와 [일부 Windows 원격 머신](#windows-remote-machines)에서는 Desktop 연결이 끊긴 동안 Claude가 해당 도구를 호출할 수 없습니다.1381* **MCP 서버**: Claude Code가 원격 머신에서 시작하는 MCP 서버는 Desktop을 거치지 않으므로 Claude가 해당 도구를 계속 호출할 수 있습니다. `claude_desktop_config.json`의 서버는 Desktop이 [기본 제공 SSH 클라이언트](#worktree-edits-while-disconnected)를 사용하지 않는 경우에만 여기에 포함됩니다. 그렇지 않은 경우와 [일부 Windows 원격 머신](#windows-remote-machines)에서는 Desktop 연결이 끊긴 동안 Claude가 해당 도구를 호출할 수 없습니다.

1382 1382 

1383> [accordion] 워크트리의 편집이 계속 작동하는 경우1383> [accordion] worktree의 편집이 계속 작동하는 경우

1384>1384>

1385> Linux 또는 macOS 원격 머신에서는 확인이 Desktop을 거치지 않으므로, Desktop 연결이 끊긴 동안에도 워크트리 내부의 편집이 계속 작동합니다. Claude Desktop v2.37337.0 이전에는 Linux 원격 머신에서만 해당됩니다.1385> Linux 또는 macOS 원격 머신에서는 각 편집에 대한 확인이 Desktop 없이 실행될 수 있으므로, Desktop 연결이 끊긴 동안에도 worktree 내부의 편집이 계속 작동할 수 있습니다. [Claude Desktop v2.37337.0](#check-your-version) 이전에는 Linux 원격 머신에서만 작동합니다.

1386>1386>

1387> 다음을 포함한 일부 경우에는 여전히 편집이 실패합니다:1387> 다음을 포함한 일부 경우에는 여전히 편집이 실패합니다:

1388>1388>

2050 2050 

2051* **이 머신의 로컬 세션**: 디스크에 배포된 관리형 설정 파일이 적용됩니다. 세션이 [적격 로그인](https://code.claude.com/docs/ko/server-managed-settings.md#platform-availability)으로 인증하는 경우, 관리자 콘솔을 통해 원격으로 푸시된 관리형 설정도 Anthropic API를 사용하는 이러한 세션에 적용되며, 터미널 CLI와 동일한 [설정 우선순위](https://code.claude.com/docs/ko/settings.md#settings-precedence)를 따릅니다.2051* **이 머신의 로컬 세션**: 디스크에 배포된 관리형 설정 파일이 적용됩니다. 세션이 [적격 로그인](https://code.claude.com/docs/ko/server-managed-settings.md#platform-availability)으로 인증하는 경우, 관리자 콘솔을 통해 원격으로 푸시된 관리형 설정도 Anthropic API를 사용하는 이러한 세션에 적용되며, 터미널 CLI와 동일한 [설정 우선순위](https://code.claude.com/docs/ko/settings.md#settings-precedence)를 따릅니다.

2052* **[클라우드 세션](#cloud-sessions)**: [서버 관리형 설정](https://code.claude.com/docs/ko/server-managed-settings.md)을 받습니다. 클라우드 세션은 Anthropic이 관리하는 VM에서 실행되므로 기기에 배포된 파일은 적용되지 않습니다. [셀프 호스팅 환경](https://code.claude.com/docs/ko/self-hosted-environments)으로 라우팅된 세션은 러너 이미지의 관리형 설정 파일도 읽습니다. 해당 파일이 언제 적용되는지는 [Claude Code가 관리형 소스를 결합하는 방법](https://code.claude.com/docs/ko/managed-settings.md#how-claude-code-combines-managed-sources)에 설명되어 있습니다.2052* **[클라우드 세션](#cloud-sessions)**: [서버 관리형 설정](https://code.claude.com/docs/ko/server-managed-settings.md)을 받습니다. 클라우드 세션은 Anthropic이 관리하는 VM에서 실행되므로 기기에 배포된 파일은 적용되지 않습니다. [셀프 호스팅 환경](https://code.claude.com/docs/ko/self-hosted-environments)으로 라우팅된 세션은 러너 이미지의 관리형 설정 파일도 읽습니다. 해당 파일이 언제 적용되는지는 [Claude Code가 관리형 소스를 결합하는 방법](https://code.claude.com/docs/ko/managed-settings.md#how-claude-code-combines-managed-sources)에 설명되어 있습니다.

2053* **[SSH 세션](#ssh-sessions)**: 세션은 원격 호스트의 관리형 설정 파일을 읽습니다. Desktop 자체는 로컬 머신에서 `sshConfigs`, `sshHostAllowlist`, `disableSshSavedPasswords`, `disableDesktopLocalSessions`를 읽습니다. 둘 이상의 관리형 소스를 전달하는 경우, Desktop은 [기본적으로 그중 하나](https://code.claude.com/docs/ko/managed-settings.md#how-claude-code-combines-managed-sources)에서 이 키들을 읽습니다.2053* **[SSH 세션](#ssh-sessions)**: 세션은 원격 호스트의 관리형 설정 파일을 읽습니다. Desktop 자체는 로컬 머신에서 `sshConfigs`, `sshHostAllowlist`, `disableSshSavedPasswords`, `disableDesktopLocalSessions`를 읽습니다. 둘 이상의 관리형 소스를 전달하는 경우, Desktop은 [기본적으로 그중 하나](https://code.claude.com/docs/ko/managed-settings.md#how-claude-code-combines-managed-sources)에서 이 키들을 읽습니다. 로컬 머신에 적용 중인 관리형 설정에서 `permissions.disableBypassPermissionsMode` 또는 `disableAutoMode`를 설정하면, 원격 호스트의 설정과 관계없이 SSH 세션의 모드 선택기에 해당 모드가 제공되지 않습니다.

2054* **[Cowork](https://claude.com/docs/cowork/overview) 세션**: 이 머신의 Cowork 세션에서 Claude Code는 사용자가 Team 또는 Enterprise 계정으로 로그인하더라도 관리자 콘솔 설정을 가져오지 않으며, 머신에 배포된 정책을 읽습니다. 단, Claude Desktop 구성에서 `requireCoworkFullVmSandbox`를 설정한 경우에는 이 정책을 읽지 않습니다. 원격 Cowork 세션은 둘 다 받지 않습니다. 어떤 기기 파일이 Cowork에 적용되는지는 [정책이 적용되는 위치와 시점](https://code.claude.com/docs/ko/managed-settings.md#where-and-when-a-policy-applies)을, `Bash` 및 `WebFetch` 규칙이 Cowork의 도구에 적용되는 방식은 [MCP 권한 규칙](https://code.claude.com/docs/ko/permissions.md#mcp)을 참조하십시오.2054* **[Cowork](https://claude.com/docs/cowork/overview) 세션**: 이 머신의 Cowork 세션에서 Claude Code는 사용자가 Team 또는 Enterprise 계정으로 로그인하더라도 관리자 콘솔 설정을 가져오지 않으며, 머신에 배포된 정책을 읽습니다. 단, Claude Desktop 구성에서 `requireCoworkFullVmSandbox`를 설정한 경우에는 이 정책을 읽지 않습니다. 원격 Cowork 세션은 둘 다 받지 않습니다. 어떤 기기 파일이 Cowork에 적용되는지는 [정책이 적용되는 위치와 시점](https://code.claude.com/docs/ko/managed-settings.md#where-and-when-a-policy-applies)을, `Bash` 및 `WebFetch` 규칙이 Cowork의 도구에 적용되는 방식은 [MCP 권한 규칙](https://code.claude.com/docs/ko/permissions.md#mcp)을 참조하십시오.

2055 2055 

2056로컬 세션과 SSH 세션에서는 데스크톱 앱이 각 사용자가 연결한 claude.ai 커넥터를 Claude Code에 직접 전달합니다. 어떤 설정 소스나 파일 위치를 사용하든 MCP 설정이나 `managed-mcp.json`은 이러한 커넥터에 적용되지 않습니다. 이러한 세션에서 커넥터의 도구를 차단하려면 조직의 [커넥터 도구 제어](https://code.claude.com/docs/ko/mcp.md#organization-controls-on-connector-tools)를 사용하십시오. [커넥터가 Claude Code에 전달되는 방식](https://code.claude.com/docs/ko/mcp.md#how-connectors-reach-claude-code)에서 각 세션 유형별로 커넥터를 관리하는 설정을 확인할 수 있습니다.2056로컬 세션과 SSH 세션에서는 데스크톱 앱이 각 사용자가 연결한 claude.ai 커넥터를 Claude Code에 직접 전달합니다. 어떤 설정 소스나 파일 위치를 사용하든 MCP 설정이나 `managed-mcp.json`은 이러한 커넥터에 적용되지 않습니다. 이러한 세션에서 커넥터의 도구를 차단하려면 조직의 [커넥터 도구 제어](https://code.claude.com/docs/ko/mcp.md#organization-controls-on-connector-tools)를 사용하십시오. [커넥터가 Claude Code에 전달되는 방식](https://code.claude.com/docs/ko/mcp.md#how-connectors-reach-claude-code)에서 각 세션 유형별로 커넥터를 관리하는 설정을 확인할 수 있습니다.

Details

8 8 

9> [!NOTE]9> [!NOTE]

10>10>

11> iOS 시뮬레이터 창은 macOS의 Claude Code Desktop에서 공개 베타 상태입니다. Pro, Max, Ultra, Team 및 Enterprise 플랜에서 사용 가능하며, HIPAA 구성이 활성화된 Enterprise 조직은 제외됩니다.11> iOS 시뮬레이터 창은 macOS의 Claude Code Desktop에서 공개 베타 상태입니다. Pro, Max, Ultra, Team 및 Enterprise 플랜에서 사용 가능하며, HIPAA 구성이 활성화된 Enterprise 조직은 제외됩니다. [타사 제공업체](https://code.claude.com/docs/ko/third-party-integrations.md)를 사용하는 경우에는 사용할 수 없습니다.

12 12 

13iOS 시뮬레이터 창은 Claude Code Desktop의 대화 옆에 Apple의 iOS 시뮬레이터에서 실행 중인 앱을 표시합니다. Claude가 시뮬레이터에서 앱을 빌드, 설치, 실행 또는 확인할 때 창이 자동으로 열리고 기기 화면을 실시간으로 스트리밍합니다. Claude가 앱을 실행하고 테스트하는 것을 보거나, Claude가 계속 작업하는 동안 직접 앱을 탭하며 이동할 수 있습니다.13iOS 시뮬레이터 창은 Claude Code Desktop의 대화 옆에 Apple의 iOS 시뮬레이터에서 실행 중인 앱을 표시합니다. Claude가 시뮬레이터에서 앱을 빌드, 설치, 실행 또는 확인할 때 창이 자동으로 열리고 기기 화면을 실시간으로 스트리밍합니다. Claude가 앱을 실행하고 테스트하는 것을 보거나, Claude가 계속 작업하는 동안 직접 앱을 탭하며 이동할 수 있습니다.

14 14 

147* 목표를 명시적으로 표현합니다 (예: "iOS 시뮬레이터에서 앱을 실행하고 가입 흐름을 탭하며 이동").147* 목표를 명시적으로 표현합니다 (예: "iOS 시뮬레이터에서 앱을 실행하고 가입 흐름을 탭하며 이동").

148* Xcode 및 iOS 시뮬레이터가 설치되어 있고 [권장 Xcode 버전](#requirements)을 사용하고 있는지 확인합니다.148* Xcode 및 iOS 시뮬레이터가 설치되어 있고 [권장 Xcode 버전](#requirements)을 사용하고 있는지 확인합니다.

149* 조직이 Claude Code를 관리하면 [시뮬레이터 도구가 정책에 의해 비활성화](#turn-off-simulator-access)될 수 있습니다.149* 조직이 Claude Code를 관리하면 [시뮬레이터 도구가 정책에 의해 비활성화](#turn-off-simulator-access)될 수 있습니다.

150* HIPAA 구성이 활성화된 Enterprise 조직에 속하면 시뮬레이터 창을 사용할 수 없습니다.150* HIPAA 구성이 활성화된 Enterprise 조직에 속하거나 [서드파티 제공업체](https://code.claude.com/docs/ko/third-party-integrations.md)를 사용하는 경우 시뮬레이터 창을 사용할 수 없습니다.

151* 시뮬레이터 창에는 Claude Desktop v1.24012.0 이상이 필요합니다. \*\*Claude > Check for Updates…\*\*를 열고 앱을 다시 시작합니다.151* 시뮬레이터 창에는 Claude Desktop v1.24012.0 이상이 필요합니다. \*\*Claude > Check for Updates…\*\*를 열고 앱을 다시 시작합니다.

152 152 

153### 시뮬레이터 창에 시뮬레이터를 찾을 수 없다고 표시됨153### 시뮬레이터 창에 시뮬레이터를 찾을 수 없다고 표시됨

env-vars.md +5 −5

Details

204| `CLAUDE_CODE_ARTIFACT_AUTO_OPEN` | `0`으로 설정하면 새 [아티팩트](https://code.claude.com/docs/ko/artifacts.md#create-an-artifact)가 게시될 때 Claude Code가 브라우저를 자동으로 열지 않습니다 |204| `CLAUDE_CODE_ARTIFACT_AUTO_OPEN` | `0`으로 설정하면 새 [아티팩트](https://code.claude.com/docs/ko/artifacts.md#create-an-artifact)가 게시될 때 Claude Code가 브라우저를 자동으로 열지 않습니다 |

205| `CLAUDE_CODE_ARTIFACT_COMMENTS` | `0`으로 설정하면 Claude가 [아티팩트의 댓글](https://code.claude.com/docs/ko/artifacts.md#collect-comments-on-an-artifact)을 읽고 답하지 않습니다. `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC`이 [아티팩트를 끈](https://code.claude.com/docs/ko/artifacts.md#availability) 경우에는 효과가 없습니다. Claude Code v2.1.221 이상이 필요합니다 |205| `CLAUDE_CODE_ARTIFACT_COMMENTS` | `0`으로 설정하면 Claude가 [아티팩트의 댓글](https://code.claude.com/docs/ko/artifacts.md#collect-comments-on-an-artifact)을 읽고 답하지 않습니다. `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC`이 [아티팩트를 끈](https://code.claude.com/docs/ko/artifacts.md#availability) 경우에는 효과가 없습니다. Claude Code v2.1.221 이상이 필요합니다 |

206| `CLAUDE_CODE_ARTIFACT_COMMENTS_AUTOREACT` | `0`으로 설정하면 Claude가 [자신에게 전송된 댓글에 스스로 답하지](https://code.claude.com/docs/ko/artifacts.md#let-claude-reply-to-comments-on-its-own) 않습니다. Claude Code v2.1.228 이상이 필요합니다 |206| `CLAUDE_CODE_ARTIFACT_COMMENTS_AUTOREACT` | `0`으로 설정하면 Claude가 [자신에게 전송된 댓글에 스스로 답하지](https://code.claude.com/docs/ko/artifacts.md#let-claude-reply-to-comments-on-its-own) 않습니다. Claude Code v2.1.228 이상이 필요합니다 |

207| `CLAUDE_CODE_ARTIFACT_PUBLISH_EDITS` | `0`으로 설정하면 Claude가 [아티팩트](https://code.claude.com/docs/ko/artifacts.md#update-an-artifact)를 게시하는 과정에서 해당 파일에 작은 변경 사항을 적용하지 않습니다. 대신 Claude는 파일 편집 도구로 파일을 편집한 뒤 별도 단계로 게시합니다. Claude Code v2.1.300 이상이 필요합니다 |207| `CLAUDE_CODE_ARTIFACT_PUBLISH_EDITS` | `0`으로 설정하면 Claude가 아티팩트를 게시하는 과정에서 아티팩트 파일에 [작은 변경 사항을 적용하는 것](https://code.claude.com/docs/ko/artifacts.md#turn-off-one-step-artifact-updates)을 중지합니다. 이 경우 Claude는 파일 편집 도구로 파일을 편집한 후 별도의 단계로 게시합니다. Claude Code v2.1.300 이상이 필요합니다 |

208| `CLAUDE_CODE_ATTRIBUTION_HEADER` | `0`으로 설정하면 클라이언트 버전과 프롬프트 지문을 담은 [출처 표시 블록](https://code.claude.com/docs/ko/llm-gateway-protocol.md#system-prompt-attribution-block)을 시스템 프롬프트 시작 부분에서 생략합니다. Anthropic API에 직접 연결할 때의 캐싱은 어느 쪽이든 영향을 받지 않습니다. 일부 직접 연결 구성에서는 `0`으로 설정하더라도 Claude Code가 [자동 모드](https://code.claude.com/docs/ko/permission-modes.md#eliminate-prompts-with-auto-mode) 분류기 요청에 이 블록을 유지합니다. 이것이 적용되는 연결과 자격 증명은 [시스템 프롬프트 출처 표시 블록](https://code.claude.com/docs/ko/llm-gateway-protocol.md#system-prompt-attribution-block)에서 확인하세요. v2.1.181 이전에는 사용자 지정 기본 URL과 Microsoft Foundry 연결에서 이 블록에 요청별 토큰이 포함되었으므로, 해당 버전에서는 LLM 게이트웨이가 요청 본문을 기준으로 캐시하거나 서드파티 제공자로 요청을 전달하는 경우, 또는 Microsoft Foundry에 직접 연결하는 경우 `0`으로 설정합니다 |208| `CLAUDE_CODE_ATTRIBUTION_HEADER` | `0`으로 설정하면 클라이언트 버전과 프롬프트 지문을 담은 [출처 표시 블록](https://code.claude.com/docs/ko/llm-gateway-protocol.md#system-prompt-attribution-block)을 시스템 프롬프트 시작 부분에서 생략합니다. Anthropic API에 직접 연결할 때의 캐싱은 어느 쪽이든 영향을 받지 않습니다. 일부 직접 연결 구성에서는 `0`으로 설정하더라도 Claude Code가 [자동 모드](https://code.claude.com/docs/ko/permission-modes.md#eliminate-prompts-with-auto-mode) 분류기 요청에 이 블록을 유지합니다. 이것이 적용되는 연결과 자격 증명은 [시스템 프롬프트 출처 표시 블록](https://code.claude.com/docs/ko/llm-gateway-protocol.md#system-prompt-attribution-block)에서 확인하세요. v2.1.181 이전에는 사용자 지정 기본 URL과 Microsoft Foundry 연결에서 이 블록에 요청별 토큰이 포함되었으므로, 해당 버전에서는 LLM 게이트웨이가 요청 본문을 기준으로 캐시하거나 서드파티 제공자로 요청을 전달하는 경우, 또는 Microsoft Foundry에 직접 연결하는 경우 `0`으로 설정합니다 |

209| `CLAUDE_CODE_AUTO_BACKGROUND_WORKER_CHECKIN_SECONDS` | v2.1.283에서 제거되었습니다. 대신 `CLAUDE_CODE_WORKER_CHECKIN_SCHEDULE`을 사용합니다 |209| `CLAUDE_CODE_AUTO_BACKGROUND_WORKER_CHECKIN_SECONDS` | v2.1.283에서 제거되었습니다. 대신 `CLAUDE_CODE_WORKER_CHECKIN_SCHEDULE`을 사용합니다 |

210| `CLAUDE_CODE_AUTO_COMPACT_WINDOW` | 자동 압축 윈도우, 즉 압축 전에 컨텍스트가 얼마나 찰 수 있는지를 `100000`에서 `1000000` 토큰 사이로 설정합니다. `200k`와 같은 접미사 값에는 v2.1.304 이상이 필요합니다. 윈도우를 설정하는 다른 방법과의 우선순위 및 상태줄의 `used_percentage`에 미치는 영향은 [자동 압축 윈도우 설정](https://code.claude.com/docs/ko/model-config.md#set-the-auto-compact-window)을 참조하세요 |210| `CLAUDE_CODE_AUTO_COMPACT_WINDOW` | 자동 압축 윈도우, 즉 압축 전에 컨텍스트가 얼마나 찰 수 있는지를 `100000`에서 `1000000` 토큰 사이로 설정합니다. `200k`와 같은 접미사 값에는 v2.1.304 이상이 필요합니다. 윈도우를 설정하는 다른 방법과의 우선순위 및 상태줄의 `used_percentage`에 미치는 영향은 [자동 압축 윈도우 설정](https://code.claude.com/docs/ko/model-config.md#set-the-auto-compact-window)을 참조하세요 |

502| `OTEL_LOG_TOOL_CONTENT` | `tool.output` OpenTelemetry 스팬 이벤트에 도구 콘텐츠를 포함하려면 `1`로 설정합니다. 스팬 속성은 [자체 게이트](https://code.claude.com/docs/ko/monitoring-usage.md#new-context-gates)에 따라 도구 콘텐츠를 포함합니다. [트레이싱](https://code.claude.com/docs/ko/monitoring-usage.md#traces-beta)이 필요합니다. 민감한 데이터를 보호하기 위해 기본적으로 비활성화되어 있습니다. 셸, 사용자 설정 또는 관리형 설정에서 설정합니다. 해당 섹션에서 설명하는 끄기 값을 제외하고 [프로젝트 및 로컬 설정](https://code.claude.com/docs/ko/settings-reference.md#variables-claude-code-ignores-in-env)에서는 무시됩니다. [모니터링](https://code.claude.com/docs/ko/monitoring-usage.md#tool-output-span-event)을 참조하세요 |502| `OTEL_LOG_TOOL_CONTENT` | `tool.output` OpenTelemetry 스팬 이벤트에 도구 콘텐츠를 포함하려면 `1`로 설정합니다. 스팬 속성은 [자체 게이트](https://code.claude.com/docs/ko/monitoring-usage.md#new-context-gates)에 따라 도구 콘텐츠를 포함합니다. [트레이싱](https://code.claude.com/docs/ko/monitoring-usage.md#traces-beta)이 필요합니다. 민감한 데이터를 보호하기 위해 기본적으로 비활성화되어 있습니다. 셸, 사용자 설정 또는 관리형 설정에서 설정합니다. 해당 섹션에서 설명하는 끄기 값을 제외하고 [프로젝트 및 로컬 설정](https://code.claude.com/docs/ko/settings-reference.md#variables-claude-code-ignores-in-env)에서는 무시됩니다. [모니터링](https://code.claude.com/docs/ko/monitoring-usage.md#tool-output-span-event)을 참조하세요 |

503| `OTEL_LOG_TOOL_DETAILS` | OpenTelemetry 메트릭, 트레이스, 로그에 도구 입력 인수, MCP 서버 이름, 사용자가 작성한 워크플로 이름, 도구 실패 시 원시 오류 문자열, `api_refusal` 이벤트의 거부 `category`, [비용 및 토큰 메트릭](https://code.claude.com/docs/ko/monitoring-usage.md#cost-counter)의 실제 에이전트, 스킬, 플러그인, MCP 서버 이름, 기타 도구 세부 정보를 포함하려면 `1`로 설정합니다. PII를 보호하기 위해 기본적으로 비활성화되어 있습니다. 셸, 사용자 설정 또는 관리형 설정에서 설정합니다. 해당 섹션에서 설명하는 끄기 값을 제외하고 [프로젝트 및 로컬 설정](https://code.claude.com/docs/ko/settings-reference.md#variables-claude-code-ignores-in-env)에서는 무시됩니다. [모니터링](https://code.claude.com/docs/ko/monitoring-usage.md)을 참조하세요 |503| `OTEL_LOG_TOOL_DETAILS` | OpenTelemetry 메트릭, 트레이스, 로그에 도구 입력 인수, MCP 서버 이름, 사용자가 작성한 워크플로 이름, 도구 실패 시 원시 오류 문자열, `api_refusal` 이벤트의 거부 `category`, [비용 및 토큰 메트릭](https://code.claude.com/docs/ko/monitoring-usage.md#cost-counter)의 실제 에이전트, 스킬, 플러그인, MCP 서버 이름, 기타 도구 세부 정보를 포함하려면 `1`로 설정합니다. PII를 보호하기 위해 기본적으로 비활성화되어 있습니다. 셸, 사용자 설정 또는 관리형 설정에서 설정합니다. 해당 섹션에서 설명하는 끄기 값을 제외하고 [프로젝트 및 로컬 설정](https://code.claude.com/docs/ko/settings-reference.md#variables-claude-code-ignores-in-env)에서는 무시됩니다. [모니터링](https://code.claude.com/docs/ko/monitoring-usage.md)을 참조하세요 |

504| `OTEL_LOG_USER_PROMPTS` | OpenTelemetry 트레이스와 로그에 사용자 프롬프트 텍스트를 포함하려면 `1`로 설정합니다. 기본적으로 비활성화되어 있습니다(프롬프트가 가려짐). 셸, 사용자 설정 또는 관리형 설정에서 설정합니다. 해당 섹션에서 설명하는 끄기 값을 제외하고 [프로젝트 및 로컬 설정](https://code.claude.com/docs/ko/settings-reference.md#variables-claude-code-ignores-in-env)에서는 무시됩니다. [모니터링](https://code.claude.com/docs/ko/monitoring-usage.md)을 참조하세요 |504| `OTEL_LOG_USER_PROMPTS` | OpenTelemetry 트레이스와 로그에 사용자 프롬프트 텍스트를 포함하려면 `1`로 설정합니다. 기본적으로 비활성화되어 있습니다(프롬프트가 가려짐). 셸, 사용자 설정 또는 관리형 설정에서 설정합니다. 해당 섹션에서 설명하는 끄기 값을 제외하고 [프로젝트 및 로컬 설정](https://code.claude.com/docs/ko/settings-reference.md#variables-claude-code-ignores-in-env)에서는 무시됩니다. [모니터링](https://code.claude.com/docs/ko/monitoring-usage.md)을 참조하세요 |

505| `OTEL_METRICS_INCLUDE_ACCOUNT_UUID` | 메트릭 속성에서 계정 UUID를 제외하려면 `false`로 설정합니다(기본값: 포함). [모니터링](https://code.claude.com/docs/ko/monitoring-usage.md)을 참조하세요 |505| `OTEL_METRICS_INCLUDE_ACCOUNT_UUID` | `false`로 설정하면 메트릭 및 이벤트 속성에서 계정 UUID를 제외합니다(기본값: 포함). [모니터링](https://code.claude.com/docs/ko/monitoring-usage.md)을 참조하세요 |

506| `OTEL_METRICS_INCLUDE_ENTRYPOINT` | 메트릭 속성에 세션 진입점을 포함하려면 `true`로 설정합니다(기본값: 제외). v2.1.152에서 추가되었습니다. [모니터링](https://code.claude.com/docs/ko/monitoring-usage.md)을 참조하세요 |506| `OTEL_METRICS_INCLUDE_ENTRYPOINT` | `true`로 설정하면 메트릭 및 이벤트 속성에 세션 진입점을 포함합니다(기본값: 제외). v2.1.152에서 추가되었습니다. [모니터링](https://code.claude.com/docs/ko/monitoring-usage.md)을 참조하세요 |

507| `OTEL_METRICS_INCLUDE_REPOSITORY` | 세션의 저장소를 식별하는 `vcs.*` 속성으로 OpenTelemetry 메트릭과 이벤트에 태그를 지정하려면 `true`로 설정합니다(기본값: 제외). Claude Code v2.1.269 이상이 필요합니다. [저장소 속성](https://code.claude.com/docs/ko/monitoring-usage.md#repository-attributes)을 참조하세요 |507| `OTEL_METRICS_INCLUDE_REPOSITORY` | 세션의 저장소를 식별하는 `vcs.*` 속성으로 OpenTelemetry 메트릭과 이벤트에 태그를 지정하려면 `true`로 설정합니다(기본값: 제외). Claude Code v2.1.269 이상이 필요합니다. [저장소 속성](https://code.claude.com/docs/ko/monitoring-usage.md#repository-attributes)을 참조하세요 |

508| `OTEL_METRICS_INCLUDE_RESOURCE_ATTRIBUTES` | v2.1.161부터 Claude Code는 `OTEL_RESOURCE_ATTRIBUTES` 키를 메트릭 데이터 포인트 레이블에 첨부합니다. 이를 제외하려면 `false`로 설정합니다(기본값: 포함). [모니터링](https://code.claude.com/docs/ko/monitoring-usage.md#multi-team-organization-support)을 참조하세요 |508| `OTEL_METRICS_INCLUDE_RESOURCE_ATTRIBUTES` | v2.1.161부터 Claude Code는 `OTEL_RESOURCE_ATTRIBUTES` 키를 메트릭 데이터 포인트 레이블에 첨부합니다. 이를 제외하려면 `false`로 설정합니다(기본값: 포함). [모니터링](https://code.claude.com/docs/ko/monitoring-usage.md#multi-team-organization-support)을 참조하세요 |

509| `OTEL_METRICS_INCLUDE_SESSION_ID` | 메트릭 속성에서 세션 ID를 제외하려면 `false`로 설정합니다(기본값: 포함). [모니터링](https://code.claude.com/docs/ko/monitoring-usage.md)을 참조하세요 |509| `OTEL_METRICS_INCLUDE_SESSION_ID` | `false`로 설정하면 메트릭 및 이벤트 속성에서 세션 ID를 제외합니다(기본값: 포함). [모니터링](https://code.claude.com/docs/ko/monitoring-usage.md)을 참조하세요 |

510| `OTEL_METRICS_INCLUDE_VERSION` | 메트릭 속성에 Claude Code 버전을 포함하려면 `true`로 설정합니다(기본값: 제외). [모니터링](https://code.claude.com/docs/ko/monitoring-usage.md)을 참조하세요 |510| `OTEL_METRICS_INCLUDE_VERSION` | `true`로 설정하면 메트릭 및 이벤트 속성에 Claude Code 버전을 포함합니다(기본값: 제외). [모니터링](https://code.claude.com/docs/ko/monitoring-usage.md)을 참조하세요 |

511| `SLASH_COMMAND_TOOL_CHAR_BUDGET` | [Skill 도구](https://code.claude.com/docs/ko/skills.md#control-who-invokes-a-skill)에 표시되는 스킬 메타데이터의 문자 예산을 재정의합니다. 예산은 컨텍스트 윈도우의 1%로 동적으로 조정되며, 폴백 값은 8,000자입니다. 하위 호환성을 위해 유지되는 레거시 이름입니다 |511| `SLASH_COMMAND_TOOL_CHAR_BUDGET` | [Skill 도구](https://code.claude.com/docs/ko/skills.md#control-who-invokes-a-skill)에 표시되는 스킬 메타데이터의 문자 예산을 재정의합니다. 예산은 컨텍스트 윈도우의 1%로 동적으로 조정되며, 폴백 값은 8,000자입니다. 하위 호환성을 위해 유지되는 레거시 이름입니다 |

512| `TASK_MAX_OUTPUT_LENGTH` | v2.1.277에서 이 변수가 크기를 지정하던 `TaskOutput` 도구와 함께 제거되었으며 이제 아무 작업도 수행하지 않습니다. 이전에는 `TaskOutput` 도구가 유지하는 [백그라운드 작업](https://code.claude.com/docs/ko/tools-reference.md#background-commands) 출력의 최대 문자 수를 설정했습니다. 이제 Claude는 대신 `Read`로 백그라운드 작업의 출력 파일을 읽습니다 |512| `TASK_MAX_OUTPUT_LENGTH` | v2.1.277에서 이 변수가 크기를 지정하던 `TaskOutput` 도구와 함께 제거되었으며 이제 아무 작업도 수행하지 않습니다. 이전에는 `TaskOutput` 도구가 유지하는 [백그라운드 작업](https://code.claude.com/docs/ko/tools-reference.md#background-commands) 출력의 최대 문자 수를 설정했습니다. 이제 Claude는 대신 `Read`로 백그라운드 작업의 출력 파일을 읽습니다 |

513| `USE_BUILTIN_RIPGREP` | Claude Code에 포함된 `rg` 대신 시스템에 설치된 `rg`를 사용하려면 `0`으로 설정합니다 |513| `USE_BUILTIN_RIPGREP` | Claude Code에 포함된 `rg` 대신 시스템에 설치된 `rg`를 사용하려면 `0`으로 설정합니다 |

errors.md +398 −276

Details

104| `Failed to authenticate: OAuth session expired and could not be refreshed` | [인증](#login-expired) |104| `Failed to authenticate: OAuth session expired and could not be refreshed` | [인증](#login-expired) |

105| `Could not refresh your login because another Claude Code process is refreshing it` | [인증](#could-not-refresh-your-login) |105| `Could not refresh your login because another Claude Code process is refreshing it` | [인증](#could-not-refresh-your-login) |

106| `Failed to refresh OAuth token: another Claude Code process is refreshing it or exited mid-refresh` | [인증](#could-not-refresh-your-login) |106| `Failed to refresh OAuth token: another Claude Code process is refreshing it or exited mid-refresh` | [인증](#could-not-refresh-your-login) |

107| `Could not refresh your login: the disk that holds the Claude Code config directory (~/.claude by default), or your disk quota on it, is full` | [인증](#could-not-refresh-your-login-disk-full) |

108| `Failed to refresh OAuth token: the disk that holds the Claude Code config directory (~/.claude by default), or your disk quota on it, is full` | [인증](#could-not-refresh-your-login-disk-full) |

107| `Your account is on hold and can't use Claude Code. View details or appeal: https://claude.ai/restricted` | [인증](#your-account-is-on-hold) |109| `Your account is on hold and can't use Claude Code. View details or appeal: https://claude.ai/restricted` | [인증](#your-account-is-on-hold) |

108| `Your account is on hold and can't sign in to Claude Code. View details or appeal: https://claude.ai/restricted` | [인증](#your-account-is-on-hold) |110| `Your account is on hold and can't sign in to Claude Code. View details or appeal: https://claude.ai/restricted` | [인증](#your-account-is-on-hold) |

109| `Anthropic profile login expired · Re-authenticate your Anthropic profile` | [인증](#anthropic-profile-login-expired) |111| `Anthropic profile login expired · Re-authenticate your Anthropic profile` | [인증](#anthropic-profile-login-expired) |

242| `The current directory no longer exists (it was deleted or moved)` / `Can't read the current directory` | [명령줄 오류](#the-current-directory-no-longer-exists) |244| `The current directory no longer exists (it was deleted or moved)` / `Can't read the current directory` | [명령줄 오류](#the-current-directory-no-longer-exists) |

243| `Temp directory <dir> ... Refusing to use it` / `Claude Code's temporary directory <dir> could not be created` | [명령줄 오류](#temp-directory-refused-or-cannot-be-created) |245| `Temp directory <dir> ... Refusing to use it` / `Claude Code's temporary directory <dir> could not be created` | [명령줄 오류](#temp-directory-refused-or-cannot-be-created) |

244| `ENOSPC: no space left on device, mkdir '<dir>'` | [명령줄 오류](#temp-directory-refused-or-cannot-be-created) |246| `ENOSPC: no space left on device, mkdir '<dir>'` | [명령줄 오류](#temp-directory-refused-or-cannot-be-created) |

247| `Error: Claude Code could not save ... because the disk is full (ENOSPC)` / `because your disk quota is used up (EDQUOT)` | [명령줄 오류](#could-not-save-because-the-disk-is-full) |

245| `couldn't be resolved to a real location, so its skills, commands, and agents weren't loaded` | [명령줄 오류](#directory-couldnt-be-resolved-to-a-real-location) |248| `couldn't be resolved to a real location, so its skills, commands, and agents weren't loaded` | [명령줄 오류](#directory-couldnt-be-resolved-to-a-real-location) |

246| `Error: Workspace not trusted` when starting Remote Control | [명령줄 오류](#workspace-not-trusted-when-starting-remote-control) |249| `Error: Workspace not trusted` when starting Remote Control | [명령줄 오류](#workspace-not-trusted-when-starting-remote-control) |

247| `claude ultrareview` 실행 시 표시되는 `Error: Workspace not trusted` | [명령줄 오류](#workspace-not-trusted-when-running-claude-ultrareview) |250| `claude ultrareview` 실행 시 표시되는 `Error: Workspace not trusted` | [명령줄 오류](#workspace-not-trusted-when-running-claude-ultrareview) |

248| `Ultrareview did not start` | [명령줄 오류](#ultrareview-did-not-start) |251| `Ultrareview did not start` | [명령줄 오류](#ultrareview-did-not-start) |

252| `Remote Control did not start: "<question>" got no answer` | [명령줄 오류](#remote-control-did-not-start-got-no-answer) |

249| `` `<flag>` before `remote-control` is not carried over to the sessions Remote Control starts `` | [명령줄 오류](#not-carried-over-to-the-sessions-remote-control-starts) |253| `` `<flag>` before `remote-control` is not carried over to the sessions Remote Control starts `` | [명령줄 오류](#not-carried-over-to-the-sessions-remote-control-starts) |

250| `--sandbox is not supported by claude remote-control` / `--no-sandbox is not supported by claude remote-control` | [명령줄 오류](#sandbox-is-not-supported-by-claude-remote-control) |254| `--sandbox is not supported by claude remote-control` / `--no-sandbox is not supported by claude remote-control` | [명령줄 오류](#sandbox-is-not-supported-by-claude-remote-control) |

251| `` `claude import` is not yet available in this build `` | [명령줄 오류](#claude-import-is-not-yet-available-in-this-build) |255| `` `claude import` is not yet available in this build `` | [명령줄 오류](#claude-import-is-not-yet-available-in-this-build) |

320| `The packages it lists are not installed` / `The packages it lists were not installed, because` | [플러그인 문제 해결](https://code.claude.com/docs/ko/plugins/troubleshooting.md#the-packages-it-lists-are-not-installed) |324| `The packages it lists are not installed` / `The packages it lists were not installed, because` | [플러그인 문제 해결](https://code.claude.com/docs/ko/plugins/troubleshooting.md#the-packages-it-lists-are-not-installed) |

321| `does not load (...), so Claude Code ignores the whole file` | [플러그인 문제 해결](https://code.claude.com/docs/ko/plugins/troubleshooting.md#does-not-load-so-claude-code-ignores-the-whole-file) |325| `does not load (...), so Claude Code ignores the whole file` | [플러그인 문제 해결](https://code.claude.com/docs/ko/plugins/troubleshooting.md#does-not-load-so-claude-code-ignores-the-whole-file) |

322| `path escapes plugin directory` | [플러그인 오류](#path-escapes-plugin-directory) |326| `path escapes plugin directory` | [플러그인 오류](#path-escapes-plugin-directory) |

327| `path not read: <path> is absolute or has a ".." part` | [플러그인 오류](#server-file-path-not-read) |

323| `Plugin not loaded: its manifest <path> was not read` | [플러그인 오류](#plugin-not-loaded-its-manifest-was-not-read) |328| `Plugin not loaded: its manifest <path> was not read` | [플러그인 오류](#plugin-not-loaded-its-manifest-was-not-read) |

324| `path could not be checked` | [플러그인 오류](#path-could-not-be-checked) |329| `path could not be checked` | [플러그인 오류](#path-could-not-be-checked) |

325| `its marketplace entry path does not stay inside the marketplace directory` | [플러그인 오류](#marketplace-entry-path-does-not-stay-inside-the-marketplace-directory) |330| `its marketplace entry path does not stay inside the marketplace directory` | [플러그인 오류](#marketplace-entry-path-does-not-stay-inside-the-marketplace-directory) |

368| `Refusing to write <path>: where it leads on disk could not be determined` / `Refusing to read <path>: where it leads on disk could not be determined` | [도구 오류](#refusing-after-a-symlink-changed) |373| `Refusing to write <path>: where it leads on disk could not be determined` / `Refusing to read <path>: where it leads on disk could not be determined` | [도구 오류](#refusing-after-a-symlink-changed) |

369| `Refusing to search <path>: a path one of its Read deny rules is written through changed while the search was being prepared` / `Refusing to search <path>: it could not be opened` | [도구 오류](#refusing-after-a-symlink-changed) |374| `Refusing to search <path>: a path one of its Read deny rules is written through changed while the search was being prepared` / `Refusing to search <path>: it could not be opened` | [도구 오류](#refusing-after-a-symlink-changed) |

370| `its permission check expired before it ran (too many concurrent file operations)` / `ripgrep was found only by name on PATH` | [도구 오류](#refusing-after-a-symlink-changed) |375| `its permission check expired before it ran (too many concurrent file operations)` / `ripgrep was found only by name on PATH` | [도구 오류](#refusing-after-a-symlink-changed) |

376| `The search failed, so this is not a "no matches" result: matches may exist` | [도구 오류](#the-search-failed) |

371| `task output swap refused (tasks dir moved or linked)` | [도구 오류](#task-output-swap-refused) |377| `task output swap refused (tasks dir moved or linked)` | [도구 오류](#task-output-swap-refused) |

372| `Command killed: its output file was replaced or could no longer be verified` | [도구 오류](#task-output-swap-refused) |378| `Command killed: its output file was replaced or could no longer be verified` | [도구 오류](#task-output-swap-refused) |

373| `Disk full: this computer's volume holding <dir> (Claude Code's temporary directory) has <n> MB free` / `Nearly out of inodes: this computer's volume holding <dir>` | [도구 오류](#disk-quota-or-temp-filesystem-is-full) |379| `Disk full: this computer's volume holding <dir> (Claude Code's temporary directory) has <n> MB free` / `Nearly out of inodes: this computer's volume holding <dir>` | [도구 오류](#disk-quota-or-temp-filesystem-is-full) |

377| `Command output was lost: the temp filesystem at <dir> is full` / `is out of inodes` | [도구 오류](#disk-quota-or-temp-filesystem-is-full) |383| `Command output was lost: the temp filesystem at <dir> is full` / `is out of inodes` | [도구 오류](#disk-quota-or-temp-filesystem-is-full) |

378| `File is not valid UTF-8. It may use a legacy encoding such as Windows-1252, Shift-JIS or GBK, or be binary` | [도구 오류](#file-is-not-valid-utf-8) |384| `File is not valid UTF-8. It may use a legacy encoding such as Windows-1252, Shift-JIS or GBK, or be binary` | [도구 오류](#file-is-not-valid-utf-8) |

379| `git is not installed on this Mac. To install it, run xcode-select --install, then try again.` | [도구 오류](#git-is-not-installed-on-this-mac) |385| `git is not installed on this Mac. To install it, run xcode-select --install, then try again.` | [도구 오류](#git-is-not-installed-on-this-mac) |

386| `Refusing to apply edits to <path>: a hook is configured for file edits in this session` | [도구 오류](#a-hook-is-configured-for-file-edits) |

380| `the source file is not valid UTF-8 text` / `the source file is not valid UTF-16 text` | [도구 오류](#the-source-file-is-not-valid-utf-8-text) |387| `the source file is not valid UTF-8 text` / `the source file is not valid UTF-16 text` | [도구 오류](#the-source-file-is-not-valid-utf-8-text) |

381| `the source file has the replacement character U+FFFD` | [도구 오류](#the-source-file-is-not-valid-utf-8-text) |388| `the source file has the replacement character U+FFFD` | [도구 오류](#the-source-file-is-not-valid-utf-8-text) |

382| `Not published: that file is on a network share` | [도구 오류](#not-published-that-file-is-on-a-network-share) |389| `Not published: that file is on a network share` | [도구 오류](#not-published-that-file-is-on-a-network-share) |

387| `The safety check for domain ... is rate-limited` | [도구 오류](#webfetch-domain-safety-check-failed) |394| `The safety check for domain ... is rate-limited` | [도구 오류](#webfetch-domain-safety-check-failed) |

388| `The safety check for domain ... is temporarily rate-limited` | [도구 오류](#webfetch-domain-safety-check-failed) |395| `The safety check for domain ... is temporarily rate-limited` | [도구 오류](#webfetch-domain-safety-check-failed) |

389| `Unable to verify if domain ... is safe to fetch` | [도구 오류](#webfetch-domain-safety-check-failed) |396| `Unable to verify if domain ... is safe to fetch` | [도구 오류](#webfetch-domain-safety-check-failed) |

397| `MCP tool "<tool>" on server "<server>" gave no answer that could be read` / `answered without its text` | [MCP 도구 훅의 결과를 읽는 방식](https://code.claude.com/docs/ko/hooks.md#how-the-tools-result-is-read) |

390| `Can't open MCP settings while no terminal is attached to this background session` | [백그라운드 세션 오류](#commands-refused-in-a-background-session) |398| `Can't open MCP settings while no terminal is attached to this background session` | [백그라운드 세션 오류](#commands-refused-in-a-background-session) |

391| `Can't open MCP settings in a background session` | [백그라운드 세션 오류](#commands-refused-in-a-background-session) |399| `Can't open MCP settings in a background session` | [백그라운드 세션 오류](#commands-refused-in-a-background-session) |

392| `blocked because the path is spelled in a form that cannot be safely resolved` | [백그라운드 세션 오류](#write-or-command-blocked-because-the-path-cannot-be-safely-resolved) |400| `blocked because the path is spelled in a form that cannot be safely resolved` | [백그라운드 세션 오류](#write-or-command-blocked-because-the-path-cannot-be-safely-resolved) |

397| `Can't open — this session is running in another terminal` | [백그라운드 세션 오류](#this-session-is-running-in-another-terminal) |405| `Can't open — this session is running in another terminal` | [백그라운드 세션 오류](#this-session-is-running-in-another-terminal) |

398| `This conversation is already open in another running Claude session` | [백그라운드 세션 오류](#this-session-is-running-in-another-terminal) |406| `This conversation is already open in another running Claude session` | [백그라운드 세션 오류](#this-session-is-running-in-another-terminal) |

399| `This session's saved conversation is no longer on disk` | [백그라운드 세션 오류](#this-sessions-saved-conversation-is-no-longer-on-disk) |407| `This session's saved conversation is no longer on disk` | [백그라운드 세션 오류](#this-sessions-saved-conversation-is-no-longer-on-disk) |

408| `This forked session could not be started. Fork the conversation again to retry.` | [백그라운드 세션 오류](#this-forked-session-could-not-be-started) |

400| `Bypass permissions was requested at launch and ignored` | [백그라운드 세션에서 권한 우회가 무시됨](https://code.claude.com/docs/ko/permission-modes.md#bypass-permissions-ignored-in-a-background-session) |409| `Bypass permissions was requested at launch and ignored` | [백그라운드 세션에서 권한 우회가 무시됨](https://code.claude.com/docs/ko/permission-modes.md#bypass-permissions-ignored-in-a-background-session) |

401| `kept <id> — its worktree is still at <path>` | 메시지의 다음 줄에 푸시되지 않은 커밋이 언급된 경우 [백그라운드 세션 오류](#worktree-has-commits-that-are-not-pushed-anywhere), 그렇지 않으면 [세션 삭제 시 제거되는 항목](https://code.claude.com/docs/ko/agent-view.md#what-deleting-a-session-removes) |410| `kept <id> — its worktree is still at <path>` | 메시지의 다음 줄에 푸시되지 않은 커밋이 언급된 경우 [백그라운드 세션 오류](#worktree-has-commits-that-are-not-pushed-anywhere), 그렇지 않으면 [세션 삭제 시 제거되는 항목](https://code.claude.com/docs/ko/agent-view.md#what-deleting-a-session-removes) |

402| `kept <id> — <n> unpushed commits on <branch>` | [백그라운드 세션 오류](#worktree-has-commits-that-are-not-pushed-anywhere) |411| `kept <id> — <n> unpushed commits on <branch>` | [백그라운드 세션 오류](#worktree-has-commits-that-are-not-pushed-anywhere) |

548| [`CLAUDE_CODE_MAX_RETRIES`](https://code.claude.com/docs/ko/env-vars) | 10 | 재시도 횟수입니다. v2.1.186부터 최대 15로 제한됩니다. v2.1.199부터는 `CLAUDE_CODE_RETRY_WATCHDOG`이 기본값을 높이고 상한을 제거합니다. 스크립트에서 실패를 더 빨리 확인하려면 값을 낮추세요. |557| [`CLAUDE_CODE_MAX_RETRIES`](https://code.claude.com/docs/ko/env-vars) | 10 | 재시도 횟수입니다. v2.1.186부터 최대 15로 제한됩니다. v2.1.199부터는 `CLAUDE_CODE_RETRY_WATCHDOG`이 기본값을 높이고 상한을 제거합니다. 스크립트에서 실패를 더 빨리 확인하려면 값을 낮추세요. |

549| [`CLAUDE_CODE_RETRY_WATCHDOG`](https://code.claude.com/docs/ko/env-vars) | 설정 안 됨 | CI 작업과 같은 무인 세션에서 `1`로 설정하면 `CLAUDE_CODE_MAX_RETRIES`회 시도 후 실패하는 대신 `429` 및 `529` 용량 오류를 무기한 재시도합니다. 표준 속도 요청이 지출 한도나 소진된 사용량 크레딧을 보고하는 `429`를 받으면, 일정에 따라 재설정되는 [게이트웨이 지출 한도](#spend-limit-reached)에서 온 것이라도 Claude Code는 즉시 실패합니다. v2.1.239 이전에는 워치독이 이를 무기한 재시도했습니다. 빠른 모드 요청에 대해서는 [속도 제한 처리](https://code.claude.com/docs/ko/fast-mode.md#handle-rate-limits)를 참조하세요. v2.1.199 이상에서는 서버 오류, 시간 초과, 끊어진 연결 등 다른 일시적인 오류의 기본 재시도 횟수도 약 3시간의 백오프에 해당하는 300으로 높이고, `CLAUDE_CODE_MAX_RETRIES`를 명시적으로 설정한 경우 15의 상한을 제거합니다. |558| [`CLAUDE_CODE_RETRY_WATCHDOG`](https://code.claude.com/docs/ko/env-vars) | 설정 안 됨 | CI 작업과 같은 무인 세션에서 `1`로 설정하면 `CLAUDE_CODE_MAX_RETRIES`회 시도 후 실패하는 대신 `429` 및 `529` 용량 오류를 무기한 재시도합니다. 표준 속도 요청이 지출 한도나 소진된 사용량 크레딧을 보고하는 `429`를 받으면, 일정에 따라 재설정되는 [게이트웨이 지출 한도](#spend-limit-reached)에서 온 것이라도 Claude Code는 즉시 실패합니다. v2.1.239 이전에는 워치독이 이를 무기한 재시도했습니다. 빠른 모드 요청에 대해서는 [속도 제한 처리](https://code.claude.com/docs/ko/fast-mode.md#handle-rate-limits)를 참조하세요. v2.1.199 이상에서는 서버 오류, 시간 초과, 끊어진 연결 등 다른 일시적인 오류의 기본 재시도 횟수도 약 3시간의 백오프에 해당하는 300으로 높이고, `CLAUDE_CODE_MAX_RETRIES`를 명시적으로 설정한 경우 15의 상한을 제거합니다. |

550| [`CLAUDE_CODE_RETRY_WATCHDOG_MAX_WAIT_MS`](https://code.claude.com/docs/ko/env-vars) | 설정 안 됨 | `CLAUDE_CODE_RETRY_WATCHDOG`이 설정된 경우 각 API 요청이 `429` 및 `529` 오류가 해소되기를 기다리는 최대 시간(밀리초)입니다. 설정하지 않으면 대기 시간에 제한이 없습니다. Claude Code v2.1.295 이상이 필요합니다. |559| [`CLAUDE_CODE_RETRY_WATCHDOG_MAX_WAIT_MS`](https://code.claude.com/docs/ko/env-vars) | 설정 안 됨 | `CLAUDE_CODE_RETRY_WATCHDOG`이 설정된 경우 각 API 요청이 `429` 및 `529` 오류가 해소되기를 기다리는 최대 시간(밀리초)입니다. 설정하지 않으면 대기 시간에 제한이 없습니다. Claude Code v2.1.295 이상이 필요합니다. |

560| `CLAUDE_CODE_RETRY_WATCHDOG_MAX_USAGE_LIMIT_WAIT_MS` | 상한 없음 | `CLAUDE_CODE_RETRY_WATCHDOG`이 설정된 경우, 하나의 요청이 세션 한도나 주간 한도와 같은 플랜의 [사용 한도](#youve-hit-your-session-limit)가 재설정되기를 기다리는 최대 시간(밀리초)입니다. 재설정 시점이 이 상한보다 더 멀리 있으면 요청은 즉시 실패합니다. 단, 사용량 크레딧에 여유가 있거나 API가 이를 확인할 수 없었던 경우는 예외입니다. 이러한 경우 요청은 재시도되며, 성공하기 전에 상한이 지나면 실패합니다. Claude Code v2.1.301 이상이 필요합니다. |

551| [`CLAUDE_CODE_RETRY_WATCHDOG_USAGE_LIMIT_RECHECK_MS`](https://code.claude.com/docs/ko/env-vars) | 설정 안 됨 | `CLAUDE_CODE_RETRY_WATCHDOG`이 설정된 상태에서 요청이 [사용 한도](#youve-hit-your-session-limit)가 재설정되기를 기다리는 동안, 해당 한도가 이미 해제되었는지 확인하는 검사 사이의 최소 간격(밀리초)입니다. 검사에서 한도가 해제된 것으로 확인되면 요청이 즉시 전송됩니다. `60000`에서 `10800000` 사이의 숫자만 입력하세요. 설정하지 않거나 해당 범위를 벗어나면 검사를 수행하지 않습니다. Claude Code가 이러한 검사를 건너뛰는 경우는 [환경 변수 참조](https://code.claude.com/docs/ko/env-vars.md)를 참조하세요. Claude Code v2.1.305 이상이 필요합니다. |561| [`CLAUDE_CODE_RETRY_WATCHDOG_USAGE_LIMIT_RECHECK_MS`](https://code.claude.com/docs/ko/env-vars) | 설정 안 됨 | `CLAUDE_CODE_RETRY_WATCHDOG`이 설정된 상태에서 요청이 [사용 한도](#youve-hit-your-session-limit)가 재설정되기를 기다리는 동안, 해당 한도가 이미 해제되었는지 확인하는 검사 사이의 최소 간격(밀리초)입니다. 검사에서 한도가 해제된 것으로 확인되면 요청이 즉시 전송됩니다. `60000`에서 `10800000` 사이의 숫자만 입력하세요. 설정하지 않거나 해당 범위를 벗어나면 검사를 수행하지 않습니다. Claude Code가 이러한 검사를 건너뛰는 경우는 [환경 변수 참조](https://code.claude.com/docs/ko/env-vars.md)를 참조하세요. Claude Code v2.1.305 이상이 필요합니다. |

552| [`CLAUDE_CODE_OVERLOADED_RETRY_BASE_DELAY_MS`](https://code.claude.com/docs/ko/env-vars) | 500 | API가 `529` 과부하 오류로 거부한 요청의 재시도 간 백오프 시작 지연 시간(밀리초)입니다. API가 용량 한계에 도달했을 때 재시도를 더 긴 기간에 걸쳐 분산하려면 최대 32000까지 값을 높이세요. `CLAUDE_CODE_RETRY_WATCHDOG`이 `1`로 설정되어 있거나 거부된 요청이 [빠른 모드](https://code.claude.com/docs/ko/fast-mode.md#handle-rate-limits)로 전송된 경우에는 효과가 없습니다. Claude Code v2.1.292 이상이 필요합니다. |562| [`CLAUDE_CODE_OVERLOADED_RETRY_BASE_DELAY_MS`](https://code.claude.com/docs/ko/env-vars) | 500 | API가 `529` 과부하 오류로 거부한 요청의 재시도 간 백오프 시작 지연 시간(밀리초)입니다. API가 용량 한계에 도달했을 때 재시도를 더 긴 기간에 걸쳐 분산하려면 최대 32000까지 값을 높이세요. `CLAUDE_CODE_RETRY_WATCHDOG`이 `1`로 설정되어 있거나 거부된 요청이 [빠른 모드](https://code.claude.com/docs/ko/fast-mode.md#handle-rate-limits)로 전송된 경우에는 효과가 없습니다. Claude Code v2.1.292 이상이 필요합니다. |

553| [`CLAUDE_CODE_OVERLOADED_RETRY_MAX_DELAY_MS`](https://code.claude.com/docs/ko/env-vars) | 32000 | API가 `529` 과부하 오류로 거부한 요청의 재시도 간 백오프 상한(밀리초)입니다. API가 용량 한계에 도달했을 때 이후 재시도 간격이 계속 벌어지도록 하려면 최대 64000까지 값을 높이세요. `CLAUDE_CODE_RETRY_WATCHDOG`이 `1`로 설정되어 있거나 거부된 요청이 [빠른 모드](https://code.claude.com/docs/ko/fast-mode.md#handle-rate-limits)로 전송된 경우에는 효과가 없습니다. Claude Code v2.1.296 이상이 필요합니다. |563| [`CLAUDE_CODE_OVERLOADED_RETRY_MAX_DELAY_MS`](https://code.claude.com/docs/ko/env-vars) | 32000 | API가 `529` 과부하 오류로 거부한 요청의 재시도 간 백오프 상한(밀리초)입니다. API가 용량 한계에 도달했을 때 이후 재시도 간격이 계속 벌어지도록 하려면 최대 64000까지 값을 높이세요. `CLAUDE_CODE_RETRY_WATCHDOG`이 `1`로 설정되어 있거나 거부된 요청이 [빠른 모드](https://code.claude.com/docs/ko/fast-mode.md#handle-rate-limits)로 전송된 경우에는 효과가 없습니다. Claude Code v2.1.296 이상이 필요합니다. |

1436 1446 

1437이는 [OAuth 토큰이 폐기되었거나 만료됨](#oauth-token-revoked-or-expired)과 같은 상태가 아닙니다. 해당 메시지는 API가 반환한 거부를 보고합니다. `Login expired`는 이미 갱신에 실패한 로그인에 대해 Claude Code 자체가 생성하는 메시지이므로 요청을 보내지 않습니다. 로그인이 오래되어서가 아니라 계정 자체가 정지되어 갱신이 실패한 경우, Claude Code는 대신 [계정이 보류 상태임](#your-account-is-on-hold)을 표시합니다.1447이는 [OAuth 토큰이 폐기되었거나 만료됨](#oauth-token-revoked-or-expired)과 같은 상태가 아닙니다. 해당 메시지는 API가 반환한 거부를 보고합니다. `Login expired`는 이미 갱신에 실패한 로그인에 대해 Claude Code 자체가 생성하는 메시지이므로 요청을 보내지 않습니다. 로그인이 오래되어서가 아니라 계정 자체가 정지되어 갱신이 실패한 경우, Claude Code는 대신 [계정이 보류 상태임](#your-account-is-on-hold)을 표시합니다.

1438 1448 

1439API 키, [`CLAUDE_CODE_OAUTH_TOKEN`](https://code.claude.com/docs/ko/env-vars) 또는 타사 공급자로 인증된 세션은 저장된 로그인을 사용하지 않으므로 이 메시지가 표시되지 않습니다.

1440 

1441요청이 실패하기 전에 이 상태를 확인할 수 있습니다. [`/status`](https://code.claude.com/docs/ko/commands)에 `Expired — log in again`이라고 표시된 `Login` 행과 함께, 만료된 로그인에 대해 저장된 조직과 이메일이 표시됩니다. 이 행은 저장된 로그인이 활성 자격 증명이고 더 이상 갱신할 수 없을 때만 나타납니다. 다른 방식으로 인증된 세션에서는 만료된 로그인이 저장되어 있더라도 이 행이 표시되지 않습니다. v2.1.210 이전에는 자격 증명이 삭제되어 보고할 내용이 없었기 때문에, 이 상태에서 `/status`가 로그인이 존재했었다는 어떤 표시도 하지 않았습니다.1449요청이 실패하기 전에 이 상태를 확인할 수 있습니다. [`/status`](https://code.claude.com/docs/ko/commands)에 `Expired — log in again`이라고 표시된 `Login` 행과 함께, 만료된 로그인에 대해 저장된 조직과 이메일이 표시됩니다. 이 행은 저장된 로그인이 활성 자격 증명이고 더 이상 갱신할 수 없을 때만 나타납니다. 다른 방식으로 인증된 세션에서는 만료된 로그인이 저장되어 있더라도 이 행이 표시되지 않습니다. v2.1.210 이전에는 자격 증명이 삭제되어 보고할 내용이 없었기 때문에, 이 상태에서 `/status`가 로그인이 존재했었다는 어떤 표시도 하지 않았습니다.

1442 1450 

1443**해결 방법:**1451**해결 방법:**

1461Failed to refresh OAuth token: another Claude Code process is refreshing it or exited mid-refresh. This is usually transient; retry in a minute, and if it persists close other Claude Code processes or sign in again1469Failed to refresh OAuth token: another Claude Code process is refreshing it or exited mid-refresh. This is usually transient; retry in a minute, and if it persists close other Claude Code processes or sign in again

1462```1470```

1463 1471 

1464API 키, [`CLAUDE_CODE_OAUTH_TOKEN`](https://code.claude.com/docs/ko/env-vars) 또는 타사 공급자로 인증된 세션은 저장된 로그인을 사용하지 않으므로 이 메시지가 표시되지 않습니다.

1465 

1466**해결 방법:**1472**해결 방법:**

1467 1473 

1468* 1분 후에 다시 시도합니다. 다른 프로세스가 먼저 갱신을 완료하면 이 세션은 갱신된 로그인을 사용합니다.1474* 1분 후에 다시 시도합니다. 다른 프로세스가 먼저 갱신을 완료하면 이 세션은 갱신된 로그인을 사용합니다.

1469* 메시지가 계속 나타나면 다른 Claude Code 창과 프로세스를 닫은 다음 재시도합니다.1475* 메시지가 계속 나타나면 다른 Claude Code 창과 프로세스를 닫은 다음 재시도합니다.

1470* 다른 Claude Code 프로세스가 실행되고 있지 않은데도 메시지가 나타나면 `/login`을 실행합니다. 다시 로그인하는 것은 갱신 잠금을 기다리지 않습니다.1476* 다른 Claude Code 프로세스가 실행되고 있지 않은데도 메시지가 나타나면 `/login`을 실행합니다. 다시 로그인하는 것은 갱신 잠금을 기다리지 않습니다.

1471 1477 

1478### Could not refresh your login: the disk that holds the Claude Code config directory is full

1479 

1480Claude Code 구성 디렉터리가 있는 디스크의 공간을 확보한 다음 메시지를 다시 보냅니다. 디스크가 가득 찬 동안에는 새 로그인을 저장할 수 없으므로 다시 로그인해도 도움이 되지 않습니다. [`CLAUDE_CONFIG_DIR`](https://code.claude.com/docs/ko/env-vars)을 설정하지 않았다면 구성 디렉터리는 홈 디렉터리의 `~/.claude`입니다.

1481 

1482```text wrap theme={null}

1483Could not refresh your login: the disk that holds the Claude Code config directory (~/.claude by default), or your disk quota on it, is full · Delete files you no longer need on that disk, then try again · Signing in again won't help

1484```

1485 

1486[비대화형 모드](https://code.claude.com/docs/ko/headless.md)(`-p`)와 [Agent SDK](https://code.claude.com/docs/ko/agent-sdk/overview.md)에서는 메시지가 다음과 같이 표시됩니다:

1487 

1488```text wrap theme={null}

1489Failed to refresh OAuth token: the disk that holds the Claude Code config directory (~/.claude by default), or your disk quota on it, is full. Delete files you no longer need on that disk and retry; signing in again won't help

1490```

1491 

1492**해결 방법:**

1493 

1494* 스크립트의 경우 해당 `claude -p` 명령을 다시 실행합니다

1495* 디스크에 이미 여유 공간이 있다면, 디스크 할당량이나 inode가 부족한 경우에도 같은 메시지가 표시됩니다. 해당 디스크에서 본인의 파일을 삭제합니다. 메시지가 다시 나타나면, 각 파일은 크기와 관계없이 inode를 하나씩 사용하므로 큰 파일 몇 개보다 작은 파일 여러 개를 삭제합니다.

1496 

1472### 로그인을 저장할 수 없음1497### 로그인을 저장할 수 없음

1473 1498 

1474claude.ai로 로그인했지만 Claude Code가 로그인을 자격 증명 저장소에 저장할 수 없어 로그인이 완료되지 않았습니다. macOS에서는 같은 세션 중에 Claude Code가 이미 로그인 키체인에서 자격 증명을 읽거나 저장한 후, 예를 들어 잠자기나 유휴 상태로 인해 키체인이 잠기면 이 문제가 발생할 수 있습니다.1499claude.ai로 로그인했지만 Claude Code가 로그인을 자격 증명 저장소에 저장할 수 없어 로그인이 완료되지 않았습니다. macOS에서는 같은 세션 중에 Claude Code가 이미 로그인 키체인에서 자격 증명을 읽거나 저장한 후, 예를 들어 잠자기나 유휴 상태로 인해 키체인이 잠기면 이 문제가 발생할 수 있습니다.

2442 2467 

2443### 컨텍스트가 토큰 한도를 초과함2468### 컨텍스트가 토큰 한도를 초과함

2444 2469 

2445대화가 모델의 컨텍스트 윈도우를 넘어설 만큼 커지면 `/context`는 출력 상단에 이 경고를 표시합니다. 공간을 확보할 때까지 요청은 [`Prompt is too long`](#prompt-is-too-long)으로 실패합니다. 대화형 세션에서는 이 오류가 `Context limit reached` 줄로 표시됩니다.2470대화가 모델의 컨텍스트 윈도우를 넘어설 만큼 커지면 `/context`는 출력 상단에 다음 경고를 표시합니다:

2446 2471 

2447```text theme={null}2472```text theme={null}

2448Context exceeds the 200k-token limit by 94k tokens — run /compact or /clear to continue.2473Context exceeds the 200k-token limit by 94k tokens — run /compact or /clear to continue.

2449```2474```

2450 2475 

2476`Context exceeds` 경고가 표시된 후, 기본값인 [자동 압축](https://code.claude.com/docs/ko/settings-reference.md#autocompactenabled)이 켜져 있는 동안에는 두 명령 중 어느 것도 실행할 필요가 없습니다:

2477 

2478* **자동 압축 켜짐**: 다음 메시지를 보내세요. 여전히 [`Prompt is too long`](#prompt-is-too-long)으로 실패하면 해당 항목을 참조하세요.

2479* **자동 압축 꺼짐**: 세션에서 경고에 `/compact`가 표시되어 있으면 이를 실행하고, 그렇지 않으면 `/clear`를 실행하여 다시 시작하세요. 둘 중 하나를 실행하기 전까지 메시지는 `Context limit reached`로 실패하며, `-p` 출력에서는 `Prompt is too long`으로 실패합니다.

2480 

2451초과한 한도가 1M 컨텍스트 모델의 200K 경계처럼 압축 윈도우인 경우 경고 문구가 다릅니다. 압축 윈도우는 모델의 컨텍스트 윈도우보다 작을 수 있으므로, 이를 넘어선 요청도 여전히 성공할 수 있습니다.2481초과한 한도가 1M 컨텍스트 모델의 200K 경계처럼 압축 윈도우인 경우 경고 문구가 다릅니다. 압축 윈도우는 모델의 컨텍스트 윈도우보다 작을 수 있으므로, 이를 넘어선 요청도 여전히 성공할 수 있습니다.

2452 2482 

2453```text theme={null}2483```text theme={null}

2458 2488 

2459**해결 방법:**2489**해결 방법:**

2460 2490 

2461* 여러 턴으로 이루어진 대화에서는 `/compact`를 실행하여 이전 턴을 요약하고 공간을 확보하십시오. 대신 새로 시작하려면 `/clear`를 실행하십시오2491* **압축 윈도우 경고 후**: 여러 턴으로 이루어진 대화에서는 `/compact`를 실행하여 이전 턴을 요약하고 공간을 확보하세요. 대신 새로 시작하려면 `/clear`를 실행하세요.

2462* 사용량을 줄이는 더 많은 방법은 [Prompt is too long](#prompt-is-too-long)을 참조하십시오2492* 사용량을 줄이는 더 많은 방법은 [Prompt is too long](#prompt-is-too-long)을 참조하십시오

2463 2493 

2464v2.1.216 이전에는 `/context`가 100%를 넘는 사용량을 표시하면서도 그 의미나 복구 방법을 설명하는 경고 줄을 표시하지 않았습니다.2494v2.1.216 이전에는 `/context`가 100%를 넘는 사용량을 표시하면서도 그 의미나 복구 방법을 설명하는 경고 줄을 표시하지 않았습니다.

3118 3148 

3119## 명령줄 오류3149## 명령줄 오류

3120 3150 

3121이 오류는 `claude` 명령줄과 그 하위 명령, 프롬프트에서 제출한 명령 이름, 그리고 `/security-review`처럼 프롬프트가 실행되기 전에 셸 명령을 실행해 컨텍스트를 수집하는 명령에서 발생합니다. CLI를 다시 시작하는 `/tui`에서도 발생합니다.3151이 오류는 `claude` 명령줄과 그 하위 명령, 프롬프트에서 제출한 명령 이름, 그리고 `/security-review`처럼 프롬프트가 실행되기 전에 셸 명령을 실행하여 컨텍스트를 수집하는 명령에서 발생합니다. CLI를 다시 실행하는 `/tui`에서도 발생합니다.

3122 3152 

3123### `--bg`와 `--print` 간 충돌3153### `--bg`와 `--print` 충돌

3124 3154 

3125이 메시지는 Claude Code v2.1.198 이상에서 나타납니다. 동일한 `claude` 호출에서 `--bg`를 `-p` 또는 `--print`와 함께 사용했습니다. `--bg`는 나중에 `claude agents`로 연결하는 [백그라운드 세션](https://code.claude.com/docs/ko/agent-view.md#from-your-shell)을 시작하는 반면, `--print`는 [비대화형으로](https://code.claude.com/docs/ko/headless.md) 실행되며 `claude agents`가 연결하는 대화형 세션을 시작하지 않습니다. v2.1.198 이전에는 이 조합이 연결할 수 없는 백그라운드 작업을 아무 알림 없이 생성했습니다.3155이 메시지는 Claude Code v2.1.198 이상이 필요합니다. 동일한 `claude` 호출에서 `--bg`를 `-p` 또는 `--print`와 함께 사용했습니다. `--bg`는 나중에 `claude agents`로 연결하는 [백그라운드 세션](https://code.claude.com/docs/ko/agent-view.md#from-your-shell)을 시작하는 반면, `--print`는 [비대화형으로](https://code.claude.com/docs/ko/headless.md) 실행되며 `claude agents`가 연결하는 대화형 세션을 시작하지 않습니다. v2.1.198 이전에는 이 조합이 연결할 수 없는 백그라운드 작업을 조용히 생성했습니다.

3126 3156 

3127```text theme={null}3157```text theme={null}

3128--bg and --print conflict: --print never starts the interactive session that `claude agents` attaches to, so the job would be unattachable. The prompt is the positional — drop --print: `claude --bg '<task>'`.3158--bg and --print conflict: --print never starts the interactive session that `claude agents` attaches to, so the job would be unattachable. The prompt is the positional — drop --print: `claude --bg '<task>'`.

3131**해결 방법:**3161**해결 방법:**

3132 3162 

3133* `-p` 또는 `--print`를 제거합니다. `--bg`는 프롬프트를 위치 인수로 받으므로 `claude --bg "<task>"`가 완전한 명령입니다. [셸에서 새 에이전트 디스패치하기](https://code.claude.com/docs/ko/agent-view.md#from-your-shell)를 참조하세요.3163* `-p` 또는 `--print`를 제거합니다. `--bg`는 프롬프트를 위치 인수로 받으므로 `claude --bg "<task>"`가 완전한 명령입니다. [셸에서 새 에이전트 디스패치하기](https://code.claude.com/docs/ko/agent-view.md#from-your-shell)를 참조하세요.

3134* 백그라운드 세션을 만드는 대신 프롬프트를 비대화형으로 실행하고 결과를 출력하려면 `--bg`를 제거하고 `claude -p "<task>"`를 실행합니다3164* 백그라운드 세션을 생성하는 대신 프롬프트를 비대화형으로 실행하고 결과를 출력하려면 `--bg`를 제거하고 `claude -p "<task>"`를 실행합니다

3135 3165 

3136### Couldn't tell whether `--bg` is a flag or text3166### Couldn't tell whether `--bg` is a flag or text

3137 3167 

3138Claude Code가 백그라운드 플래그인지 텍스트인지 구분할 수 없는 위치에 `--bg` 또는 `--background`를 넣어 `claude`를 실행했습니다. 명령은 아무것도 시작하지 않고 다음 줄을 출력한 뒤 종료 코드 1로 종료되었습니다.3168Claude Code가 백그라운드 플래그로 의도한 것인지 텍스트로 의도한 것인지 구분할 수 없는 위치에 `--bg` 또는 `--background`를 넣어 `claude`를 실행했습니다. 명령은 아무것도 시작하지 않고 다음 줄을 출력한 후 종료 코드 1로 종료되었습니다:

3139 3169 

3140```text theme={null}3170```text theme={null}

3141Couldn't tell whether --bg is a flag or text here, so nothing was started. To start a background session put it first: claude --bg <prompt>3171Couldn't tell whether --bg is a flag or text here, so nothing was started. To start a background session put it first: claude --bg <prompt>

3142```3172```

3143 3173 

3144`--background`를 입력한 경우 이 줄에는 `--background`가 대신 표시됩니다.3174`--background`를 입력한 경우 이 줄에는 대신 `--background`가 표시됩니다.

3145 3175 

3146**해결 방법:**3176**해결 방법:**

3147 3177 

3148* [백그라운드 세션](https://code.claude.com/docs/ko/agent-view.md#from-your-shell)을 시작하려면 셸에서 플래그를 맨 앞에 두고 명령을 다시 실행합니다: `claude --bg --name nightly-audit "<task>"`3178* [백그라운드 세션](https://code.claude.com/docs/ko/agent-view.md#from-your-shell)을 시작하려면 플래그를 맨 앞에 두고 셸에서 명령을 다시 실행합니다: `claude --bg --name nightly-audit "<task>"`

3149 3179 

3150### 시스템 프롬프트 플래그와 파일 형식 간 충돌3180### 시스템 프롬프트 플래그와 파일 형식 플래그 간의 충돌

3151 3181 

3152하나의 `claude` 호출에서 [`--append-subagent-system-prompt`](https://code.claude.com/docs/ko/cli-reference#cli-flags)를 `--append-subagent-system-prompt-file`과 함께 전달했기 때문에 `claude`가 세션을 시작하지 않고 종료 코드 1로 종료됩니다.3182하나의 `claude` 호출에서 [`--append-subagent-system-prompt`](https://code.claude.com/docs/ko/cli-reference#cli-flags)를 `--append-subagent-system-prompt-file`과 함께 전달했으므로, `claude`는 세션을 시작하지 않고 종료 코드 1로 종료됩니다:

3153 3183 

3154```text theme={null}3184```text theme={null}

3155Error: Cannot use both --append-subagent-system-prompt and --append-subagent-system-prompt-file. Please use only one.3185Error: Cannot use both --append-subagent-system-prompt and --append-subagent-system-prompt-file. Please use only one.

3156```3186```

3157 3187 

3158v2.1.283 이전에는 `--system-prompt`와 `--system-prompt-file`, 또는 `--append-system-prompt`와 `--append-system-prompt-file`을 함께 전달해도 `claude`가 같은 방식으로 종료되었습니다. 해당 쌍이 [결합](https://code.claude.com/docs/ko/cli-reference.md#system-prompt-flags)되지 않고 충돌했기 때문입니다. 해당 버전에서는 메시지에 함께 사용한 쌍의 이름이 표시됩니다.3188v2.1.283 이전에는 `--system-prompt`를 `--system-prompt-file`과 함께, 또는 `--append-system-prompt`를 `--append-system-prompt-file`과 함께 전달한 경우에도 `claude`가 같은 방식으로 종료되었습니다. 해당 쌍이 [결합](https://code.claude.com/docs/ko/cli-reference.md#system-prompt-flags)되지 않고 충돌했기 때문입니다. 이러한 버전에서는 메시지에 사용자가 함께 사용한 쌍이 표시됩니다.

3159 3189 

3160**해결 방법:**3190**해결 방법:**

3161 3191 

3162* 플래그 중 한 가지 형식만 남기고 다른 하나는 제거합니다. 고정된 프롬프트 파일과 실행별 텍스트를 결합하려면 두 플래그를 모두 전달하는 대신 실행 전에 텍스트를 파일에 병합합니다3192* 플래그의 한 가지 형식만 유지하고 다른 형식은 제거합니다. 고정된 프롬프트 파일과 실행별 텍스트를 결합하려면 두 플래그를 모두 전달하는 대신 실행하기 전에 텍스트를 파일에 병합합니다

3163 3193 

3164### Invalid `--agents` configuration3194### Invalid `--agents` configuration

3165 3195 

3166`--agents`에 전달한 값이 유효하지 않으므로 `claude`가 세션을 시작하지 않고 종료 코드 1로 종료됩니다. `--safe-mode`를 전달하거나 [`CLAUDE_CODE_SAFE_MODE`](https://code.claude.com/docs/ko/env-vars#variables)를 설정하면 Claude Code는 `--agents`를 완전히 무시합니다. `--resume` 또는 `--continue`를 사용하면 인라인 JSON 값은 검사되지 않고 세션이 시작되지만, 파일에서 읽은 값은 실행할 때마다 검사됩니다. v2.1.242 이전에는 Claude Code가 그대로 세션을 시작했습니다.3196`--agents`에 전달한 값이 유효하지 않으므로 `claude`는 세션을 시작하지 않고 종료 코드 1로 종료됩니다. `--safe-mode`를 전달하거나 [`CLAUDE_CODE_SAFE_MODE`](https://code.claude.com/docs/ko/env-vars#variables)를 설정하면 Claude Code는 `--agents`를 완전히 무시합니다. `--resume` 또는 `--continue`를 사용하면 인라인 JSON 값은 검사되지 않고 세션이 시작되지만, 파일에서 읽은 값은 실행할 때마다 검사됩니다. v2.1.242 이전에는 Claude Code가 그대로 세션을 시작했습니다.

3167 3197 

3168```text theme={null}3198```text theme={null}

3169Error: Invalid --agents configuration:3199Error: Invalid --agents configuration:

3170<what failed>3200<what failed>

3171```3201```

3172 3202 

3173첫 번째 줄 다음에 오는 내용은 값이 실패한 방식에 따라 달라집니다. Claude Code는 다음 검사를 순서대로 실행하며 처음 실패한 검사에서 멈춥니다. 값에 두 종류의 문제가 있으면 첫 번째 문제를 수정한 후에야 두 번째 문제가 표시됩니다.3203첫 번째 줄 다음에 오는 내용은 값이 어떻게 실패했는지에 따라 달라집니다. Claude Code는 다음 검사를 순서대로 실행하고 처음 실패한 검사에서 중단합니다. 값에 두 종류의 문제가 있는 경우 첫 번째 문제를 해결한 후에야 두 번째 문제가 표시됩니다:

3174 3204 

31751. 값이 `{`로 시작하지만 JSON으로 구문 분석되지 않거나 `--agents` 파일의 내용이 구문 분석되지 않으면, Claude Code는 JSON 파서 자체의 메시지가 포함된 `invalid JSON:` 줄 하나를 출력합니다32051. 값이 `{`로 시작하지만 JSON으로 파싱되지 않거나 `--agents` 파일의 내용이 파싱되지 않으면, Claude Code는 JSON 파서 자체의 메시지가 담긴 `invalid JSON:` 줄 하나를 출력합니다

31762. 구문 분석은 되지만 에이전트 정의가 [CLI로 정의한 서브에이전트](https://code.claude.com/docs/ko/sub-agents.md#choose-the-subagent-scope)의 스키마와 일치하지 않으면, Claude Code는 문제마다 한 줄씩 출력합니다32062. 파싱은 되지만 에이전트 정의가 [CLI로 정의된 서브에이전트](https://code.claude.com/docs/ko/sub-agents.md#choose-the-subagent-scope)의 스키마와 일치하지 않으면, Claude Code는 문제마다 한 줄씩 출력합니다

31773. 에이전트 이름이 `-`로 시작하면 Claude Code는 `<name>: agent names must not start with '-'`를 출력합니다32073. 에이전트 이름이 `-`로 시작하면 Claude Code는 `<name>: agent names must not start with '-'`를 출력합니다

3178 3208 

3179문제 줄이 20개를 넘으면 Claude Code는 처음 20개를 출력하고 나머지는 `…and N more`로 대체합니다.3209문제 줄이 20개를 초과하면 Claude Code는 처음 20개를 출력하고 나머지는 `…and N more`로 대체합니다.

3180 3210 

3181`--print`를 사용하면 `--agents`는 인라인 객체 대신 [JSON 파일 경로](https://code.claude.com/docs/ko/sub-agents.md#choose-the-subagent-scope)도 받습니다. v2.1.281 이전에는 `--agents`가 인라인 JSON만 받았으며 파일 경로를 잘못된 JSON으로 처리했습니다. 파일 형식에는 자체 거부 메시지가 있으며, 이 메시지 대신 다음과 같은 메시지가 출력됩니다.3211`--print`와 함께 사용할 때 `--agents`는 인라인 객체 대신 [JSON 파일의 경로](https://code.claude.com/docs/ko/sub-agents.md#choose-the-subagent-scope)도 받습니다. v2.1.281 이전에는 `--agents`가 인라인 JSON만 받았으며 파일 경로를 유효하지 않은 JSON으로 처리했습니다. 파일 형식에는 이 메시지 대신 출력되는 자체 거부 메시지가 있으며, 다음이 포함됩니다:

3182 3212 

3183* **`Error: --agents takes a JSON object, or a file path only with --print (-p)`**: 대화형 세션에서 Claude Code가 값을 파일 경로로 읽었습니다. 정의를 인라인 JSON으로 전달하거나, 파일에서 읽으려면 `-p`를 추가합니다.3213* **`Error: --agents takes a JSON object, or a file path only with --print (-p)`**: Claude Code가 대화형 세션에서 값을 파일 경로로 읽었습니다. 정의를 인라인 JSON으로 전달하거나, 파일에서 읽으려면 `-p`를 추가합니다.

3184* **`Error: --agents file not found: <path>`**: 해당 경로에 파일이 없습니다. `{`로 시작하지 않고 유효한 JSON이 아닌 값은 경로로 읽히므로, 셸이 손상시킨 인라인 JSON도 이런 방식으로 실패할 수 있습니다. 경로나 따옴표 처리를 확인하고 명령을 다시 실행합니다.3214* **`Error: --agents file not found: <path>`**: 해당 경로에 파일이 없습니다. `{`로 시작하지 않고 유효한 JSON이 아닌 값은 경로로 읽히므로, 셸이 손상시킨 인라인 JSON도 이런 방식으로 실패할 수 있습니다. 경로나 따옴표 처리를 확인하고 명령을 다시 실행합니다.

3185 3215 

3186**해결 방법:**3216**해결 방법:**

3187 3217 

3188* 메시지에 나열된 각 문제를 수정한 다음 명령을 다시 실행합니다. [CLI로 정의한 서브에이전트가 받는 필드](https://code.claude.com/docs/ko/sub-agents.md#choose-the-subagent-scope)를 참조하세요.3218* 메시지에 나열된 각 문제를 해결한 다음 명령을 다시 실행합니다. [CLI로 정의된 서브에이전트가 받는 필드](https://code.claude.com/docs/ko/sub-agents.md#choose-the-subagent-scope)를 참조하세요.

3189 3219 

3190### Cloud sessions cannot be created from a `--restricted` session3220### Cloud sessions cannot be created from a `--restricted` session

3191 3221 

3192[`--restricted`](https://code.claude.com/docs/ko/cli-reference#cli-flags)로 세션을 시작하면 Claude Code는 해당 세션에서 [클라우드 세션](https://code.claude.com/docs/ko/claude-code-on-the-web.md#from-terminal-to-cloud)을 만드는 것을 거부합니다. 새 세션은 제한된 프로세스 외부에서 실행되어 제한 모드를 적용하지 않기 때문입니다. Claude Code는 서버에 연결하기 전에 클라이언트에서 거부하므로 클라우드 세션은 생성되지 않습니다.3222[`--restricted`](https://code.claude.com/docs/ko/cli-reference#cli-flags)로 세션을 시작하면, Claude Code는 그 세션에서 [클라우드 세션](https://code.claude.com/docs/ko/claude-code-on-the-web.md#from-terminal-to-cloud)을 생성하는 것을 거부합니다. 새 세션은 제한된 프로세스 밖에서 실행되어 제한 모드를 적용하지 않기 때문입니다. Claude Code는 서버에 연결하기 전에 클라이언트에서 거부하므로 클라우드 세션이 생성되지 않습니다:

3193 3223 

3194```text theme={null}3224```text theme={null}

3195Cloud sessions cannot be created from a --restricted session: they would not enforce it.3225Cloud sessions cannot be created from a --restricted session: they would not enforce it.

3198**해결 방법:**3228**해결 방법:**

3199 3229 

3200* 제한된 세션에서 작업을 로컬로 실행합니다3230* 제한된 세션에서 작업을 로컬로 실행합니다

3201* 세션이 시작되는 방식을 제어할 수 있다면 `--restricted` 없이 새 `claude` 세션을 시작하고 그곳에서 클라우드 세션을 만듭니다3231* 세션이 실행되는 방식을 제어할 수 있다면 `--restricted` 없이 새 `claude` 세션을 시작하고 그곳에서 클라우드 세션을 생성합니다

3202 3232 

3203v2.1.248 이전에는 Claude Code에 `--restricted` 플래그가 없었으며, 이전 버전은 알 수 없는 옵션 오류로 플래그 자체를 거부합니다.3233v2.1.248 이전에는 Claude Code에 `--restricted` 플래그가 없었으며, 이전 버전은 알 수 없는 옵션 오류로 플래그 자체를 거부합니다.

3204 3234 

3205### Cloud sessions are disabled by your organization's policy3235### Cloud sessions are disabled by your organization's policy

3206 3236 

3207조직의 `allow_remote_sessions` 정책이 꺼져 있으므로 [클라우드 세션](https://code.claude.com/docs/ko/claude-code-on-the-web.md)과 이를 사용하는 명령을 사용할 수 없습니다.3237조직의 `allow_remote_sessions` 정책이 꺼져 있으므로 [클라우드 세션](https://code.claude.com/docs/ko/claude-code-on-the-web.md)과 이를 사용하는 명령을 사용할 수 없습니다:

3208 3238 

3209```text theme={null}3239```text theme={null}

3210Cloud sessions are disabled by your organization's policy. Contact your organization admin to enable them.3240Cloud sessions are disabled by your organization's policy. Contact your organization admin to enable them.

3211```3241```

3212 3242 

3213이 메시지는 [터미널에서 클라우드 세션을 만들 때](https://code.claude.com/docs/ko/claude-code-on-the-web.md#from-terminal-to-cloud)와 `/teleport`, `/remote-env`, `/web-setup`처럼 클라우드 세션이 필요한 명령을 제출할 때 나타납니다. v2.1.268 이전에는 이러한 명령을 제출하면 대신 [`Unknown command`](#unknown-command)가 반환되었습니다.3243이 메시지는 [터미널에서 클라우드 세션을 생성할 때](https://code.claude.com/docs/ko/claude-code-on-the-web.md#from-terminal-to-cloud)와 `/teleport`, `/remote-env`, `/web-setup`처럼 클라우드 세션이 필요한 명령을 제출할 때 표시됩니다. v2.1.268 이전에는 이러한 명령 중 하나를 제출하면 대신 [`Unknown command`](#unknown-command)가 반환되었습니다.

3214 3244 

3215메시지에 이 세션이 사용 중인 자격 증명이 표시되고 `Cloud sessions use your claude.ai login.`으로 끝나는 경우 [Cloud sessions use your claude.ai login](#cloud-sessions-use-your-claude-ai-login)을 참조하세요. Claude Code가 조직의 정책을 전혀 불러오지 못한 경우에는 대신 [다른 메시지](#couldnt-verify-your-organizations-policy-for-cloud-sessions)가 표시됩니다.3245메시지가 대신 이 세션에서 사용 중인 자격 증명을 언급하고 `Cloud sessions use your claude.ai login.`으로 끝나는 경우, [Cloud sessions use your claude.ai login](#cloud-sessions-use-your-claude-ai-login)을 참조하세요. Claude Code가 조직의 정책을 전혀 불러오지 못한 경우에는 대신 [다른 메시지](#couldnt-verify-your-organizations-policy-for-cloud-sessions)가 표시됩니다.

3216 3246 

3217**해결 방법:**3247**해결 방법:**

3218 3248 

3219* 조직의 [Owner](https://code.claude.com/docs/ko/server-managed-settings.md#access-control)에게 [claude.ai/admin-settings/claude-code](https://claude.ai/admin-settings/claude-code)의 Claude Code 관리자 설정에서 클라우드 세션을 활성화해 달라고 요청합니다3249* 조직의 [Owner](https://code.claude.com/docs/ko/server-managed-settings.md#access-control)에게 [claude.ai/admin-settings/claude-code](https://claude.ai/admin-settings/claude-code)의 Claude Code 관리자 설정에서 클라우드 세션을 활성화하도록 요청합니다

3220 3250 

3221### Cloud sessions use your claude.ai login3251### Cloud sessions use your claude.ai login

3222 3252 

3223[정책 거부](#cloud-sessions-are-disabled-by-your-organizations-policy) 메시지에 이 세션이 사용 중인 자격 증명이 표시되고 이 문장으로 끝나는 경우, Claude Code는 해당 자격 증명을 발급한 조직의 클라우드 세션 정책을 확인한 것입니다. 이 조직은 claude.ai 로그인이 속한 조직과 다를 수 있습니다.3253[정책 거부 메시지](#cloud-sessions-are-disabled-by-your-organizations-policy)가 이 세션에서 사용 중인 자격 증명을 언급하고 이 문장으로 끝나는 경우, Claude Code는 해당 자격 증명을 발급한 조직의 클라우드 세션 정책을 확인한 것입니다. 그 조직은 claude.ai 로그인이 속한 조직과 다를 수 있습니다:

3224 3254 

3225```text theme={null}3255```text theme={null}

3226Cloud sessions are disabled by your organization's policy. This session is using ANTHROPIC_API_KEY, so Claude Code checked the policy for the organization that key belongs to. Cloud sessions use your claude.ai login.3256Cloud sessions are disabled by your organization's policy. This session is using ANTHROPIC_API_KEY, so Claude Code checked the policy for the organization that key belongs to. Cloud sessions use your claude.ai login.

3227```3257```

3228 3258 

3229마지막 문장은 클라우드 세션이 해당 자격 증명이 아니라 claude.ai 로그인으로 실행된다는 의미입니다. 이 형식은 `--cloud` 또는 `--teleport` 등으로 셸에서 클라우드 세션을 시작하거나, 재개하거나, 메시지를 보낼 때 나타납니다. v2.1.296 이전에는 이 경우에도 Claude Code가 조직 관리자에게 문의하라는 형식을 출력했습니다.3259마지막 문장은 클라우드 세션이 해당 자격 증명이 아닌 claude.ai 로그인으로 실행된다는 의미입니다. 이 형식은 `--cloud` 또는 `--teleport`처럼 셸에서 클라우드 세션을 시작하거나, 재개하거나, 메시지를 보낼 때 표시됩니다. v2.1.296 이전에는 이 경우에도 Claude Code가 조직 관리자에게 문의하라는 형식을 출력했습니다.

3230 3260 

3231### Couldn't verify your organization's policy for cloud sessions3261### Couldn't verify your organization's policy for cloud sessions

3232 3262 

3233이 메시지는 Claude Code가 조직의 정책을 불러오지 못했다는 의미입니다. Claude Code는 [클라우드 세션](https://code.claude.com/docs/ko/claude-code-on-the-web.md)을 만들거나, 재개하거나, 메시지를 보내기 전에 이 정책을 확인합니다. 정책 요청이 아직 완료되지 않은 동안 표시되는 메시지는 다음과 같습니다.3263이 메시지는 Claude Code가 조직의 정책을 불러오지 못했다는 의미입니다. Claude Code는 [클라우드 세션](https://code.claude.com/docs/ko/claude-code-on-the-web.md)을 생성하거나, 재개하거나, 메시지를 보내기 전에 이 정책을 확인합니다. 정책 요청이 완료되지 않은 동안에는 메시지가 다음과 같습니다:

3234 3264 

3235```text theme={null}3265```text theme={null}

3236Couldn't verify your organization's policy for cloud sessions. Check your network connection and try again.3266Couldn't verify your organization's policy for cloud sessions. Check your network connection and try again.

3237```3267```

3238 3268 

3239세션 내에서 `/teleport`나 `/web-setup`처럼 클라우드 세션이 필요한 명령도 이 메시지를 표시합니다. 셸이라면 `Cloud sessions aren't available:` 형식을 출력할 상황에서도 이 메시지가 표시되며, 두 번째 문장은 `Check your network connection, then restart Claude Code and try again.`입니다.3269세션 내에서는 `/teleport` 또는 `/web-setup`처럼 클라우드 세션이 필요한 명령도 이 메시지를 표시합니다. 셸에서라면 `Cloud sessions aren't available:` 형식이 출력될 상황에서도 마찬가지이며, 두 번째 문장은 `Check your network connection, then restart Claude Code and try again.`입니다.

3240 3270 

3241정책 요청이 실패하면 메시지에 실패한 내용이 표시됩니다. 이는 `--cloud` 또는 `--teleport` 같은 플래그로 셸에서 클라우드 세션을 시작하거나, 재개하거나, 메시지를 보낼 때 적용됩니다. API로 가는 경로가 없으면 다음과 같이 표시됩니다.3271정책 요청이 실패하면 메시지에 무엇이 실패했는지 표시됩니다. 이는 `--cloud` 또는 `--teleport` 같은 플래그로 셸에서 클라우드 세션을 시작하거나, 재개하거나, 메시지를 보낼 때 적용됩니다. API로의 경로가 없으면 다음과 같이 표시됩니다:

3242 3272 

3243```text theme={null}3273```text theme={null}

3244Cloud sessions aren't available: couldn't reach api.anthropic.com to load your organization's policy. Check your network or proxy.3274Cloud sessions aren't available: couldn't reach api.anthropic.com to load your organization's policy. Check your network or proxy.

3245```3275```

3246 3276 

3247다른 실패도 같은 시작 부분 뒤에 HTTP 403으로 요청을 거부한 프록시, 서버 오류, API가 받아들이지 않은 자격 증명 등 각각의 원인이 이어집니다. 이 세션이 claude.ai 로그인 대신 사용하는 자격 증명(예: `ANTHROPIC_API_KEY` 환경 변수)을 API가 받아들이지 않은 경우, 메시지에 해당 자격 증명의 이름과 설정을 해제하라는 안내가 표시될 수도 있습니다.3277다른 실패도 같은 시작 문구 뒤에 HTTP 403으로 요청을 거부한 프록시, 서버 오류, API가 받아들이지 않은 자격 증명 등 각자의 원인을 표시합니다. `ANTHROPIC_API_KEY` 환경 변수처럼 이 세션이 claude.ai 로그인 대신 사용하는 자격 증명을 API가 받아들이지 않은 경우, 메시지에 해당 자격 증명이 표시되고 이를 해제하라는 안내가 포함될 수도 있습니다:

3248 3278 

3249```text theme={null}3279```text theme={null}

3250Cloud sessions aren't available: api.anthropic.com didn't accept this session's credentials when Claude Code asked for your organization's policy. Cloud sessions use your claude.ai login. ANTHROPIC_API_KEY is set, so this session is using API-key auth — unset it (or run in a shell without it) to use cloud sessions.3280Cloud sessions aren't available: api.anthropic.com didn't accept this session's credentials when Claude Code asked for your organization's policy. Cloud sessions use your claude.ai login. ANTHROPIC_API_KEY is set, so this session is using API-key auth — unset it (or run in a shell without it) to use cloud sessions.

3255**해결 방법:**3285**해결 방법:**

3256 3286 

3257* `Couldn't verify` 메시지의 경우 네트워크 연결을 확인하고 다시 시도합니다. 세션 내에서는 먼저 Claude Code를 다시 시작합니다3287* `Couldn't verify` 메시지의 경우 네트워크 연결을 확인하고 다시 시도합니다. 세션 내에서는 먼저 Claude Code를 다시 시작합니다

3258* `Cloud sessions aren't available:` 메시지의 경우 프록시 확인이나 메시지에 표시된 자격 증명 설정 해제 등 원인에 맞는 조치를 취한 다음 명령을 다시 실행합니다3288* `Cloud sessions aren't available:` 메시지의 경우 프록시를 확인하거나 메시지에 표시된 자격 증명을 해제하는 등 원인에 맞는 조치를 취한 다음 명령을 다시 실행합니다

3259 3289 

3260### 폴더가 추적 파일을 대체하여 아무것도 stash되지 않음3290### Nothing was stashed because a folder replaced a tracked file

3261 3291 

3262이 메시지는 체크아웃에서 git이 추적하던 파일이나 링크가 있던 위치에 이제 폴더가 있다는 의미입니다. `claude --teleport` 또는 `/teleport` 등으로 [클라우드 세션](https://code.claude.com/docs/ko/claude-code-on-the-web.md#from-cloud-to-terminal)을 터미널로 가져오는 중에 stash 옵션을 선택한 후 나타납니다. 이 상태를 stash하면 폴더 안의 파일이 삭제될 수 있으므로 Claude Code는 stash를 거부하고 체크아웃과 인덱스를 변경하지 않고 그대로 둡니다.3292이 메시지는 체크아웃에서 git이 추적하던 파일이나 링크가 있던 자리에 이제 폴더가 있다는 의미입니다. 예를 들어 `claude --teleport` 또는 `/teleport`로 [클라우드 세션](https://code.claude.com/docs/ko/claude-code-on-the-web.md#from-cloud-to-terminal)을 터미널로 가져오는 동안 stash 옵션을 선택하면 표시됩니다. 이 상태를 stash하면 폴더 안의 파일이 삭제될 수 있으므로, Claude Code는 stash를 거부하고 체크아웃과 인덱스를 변경하지 않은 채로 둡니다:

3263 3293 

3264```text wrap theme={null}3294```text wrap theme={null}

3265Error: Nothing was stashed: "f" is now a folder in place of a tracked file or link, and stashing could delete what's in it for good. Commit the change or move the folder somewhere else, then try again.3295Error: Nothing was stashed: "f" is now a folder in place of a tracked file or link, and stashing could delete what's in it for good. Commit the change or move the folder somewhere else, then try again.

3267 3297 

3268**해결 방법:**3298**해결 방법:**

3269 3299 

3270* 메시지 안내대로 변경 사항을 커밋하거나 폴더를 다른 곳으로 옮긴 다음 teleport를 다시 실행합니다3300* 메시지에 안내된 대로 변경 사항을 커밋하거나 폴더를 다른 곳으로 옮긴 다음 Teleport를 다시 실행합니다

3271 3301 

3272### The `--json-schema` value is not a valid JSON Schema3302### The `--json-schema` value is not a valid JSON Schema

3273 3303 

3274[비대화형 모드](https://code.claude.com/docs/ko/headless.md#get-structured-output)에서 [`--json-schema`](https://code.claude.com/docs/ko/cli-reference#cli-flags)에 전달한 스키마가 JSON Schema 컴파일에 실패했으므로 `claude`가 프롬프트를 실행하지 않고 종료 코드 1로 종료됩니다. v2.1.205 이전에는 잘못된 스키마가 오류 없이 구조화되지 않은 출력을 생성했으며, `format` 키워드를 사용한 스키마는 모두 유효하지 않은 것으로 처리되었습니다.3304[비대화형 모드](https://code.claude.com/docs/ko/headless.md#get-structured-output)에서 [`--json-schema`](https://code.claude.com/docs/ko/cli-reference#cli-flags)에 전달한 스키마가 JSON Schema 컴파일에 실패했으므로, `claude`는 프롬프트를 실행하지 않고 종료 코드 1로 종료됩니다. v2.1.205 이전에는 유효하지 않은 스키마가 오류 없이 구조화되지 않은 출력을 생성했으며, `format` 키워드를 사용하는 모든 스키마는 유효하지 않은 것으로 처리되었습니다.

3275 3305 

3276```text theme={null}3306```text theme={null}

3277Error: --json-schema is not a valid JSON Schema: data/type must be equal to one of the allowed values3307Error: --json-schema is not a valid JSON Schema: data/type must be equal to one of the allowed values

3278```3308```

3279 3309 

3280두 번째 콜론 뒤의 텍스트는 검증기의 진단 메시지이며 실패한 키워드나 위치를 나타냅니다. `"format": "email"`처럼 `format` 키워드를 사용하는 스키마는 유효합니다. Claude Code는 `format`을 주석으로 받아들이며 이를 강제하지 않습니다.3310두 번째 콜론 뒤의 텍스트는 검사기의 진단 메시지이며, 실패한 키워드나 위치를 알려 줍니다. `"format": "email"`처럼 `format` 키워드를 사용하는 스키마는 유효합니다. Claude Code는 `format`을 주석으로 받아들이며 이를 강제하지 않습니다.

3281 3311 

3282Claude Code는 스키마 컴파일 전에 두 가지 검사를 실행합니다. 구문 분석할 수 없는 JSON 값은 `Error: --json-schema is not valid JSON`으로, 객체가 아닌 유효한 JSON은 `Error: --json-schema must be a JSON object`로 거부합니다.3312Claude Code는 스키마 컴파일 전에 두 가지 검사를 실행합니다. 파싱할 수 없는 JSON 값은 `Error: --json-schema is not valid JSON`으로 거부하고, 객체가 아닌 유효한 JSON은 `Error: --json-schema must be a JSON object`로 거부합니다.

3283 3313 

3284**해결 방법:**3314**해결 방법:**

3285 3315 

3286* 진단 메시지가 가리키는 스키마 부분을 수정한 다음 명령을 다시 실행합니다3316* 진단 메시지가 가리키는 스키마 부분을 수정한 다음 명령을 다시 실행합니다

3287* 작동하는 스키마와 명령은 [구조화된 출력 받기](https://code.claude.com/docs/ko/headless.md#get-structured-output)를 참조하세요3317* 동작하는 스키마와 명령은 [구조화된 출력 받기](https://code.claude.com/docs/ko/headless.md#get-structured-output)를 참조하세요

3288 3318 

3289### Settings file exceeds the 2MiB limit3319### Settings file exceeds the 2MiB limit

3290 3320 

3291[`--settings`](https://code.claude.com/docs/ko/cli-reference#cli-flags)에 전달한 파일이 2 MiB보다 크므로 `claude`가 파일을 불러오지 않고 시작 시 종료 코드 1로 종료됩니다. v2.1.214 이전에는 Claude Code가 크기 검사 없이 파일을 읽었기 때문에, 수 기가바이트 크기의 파일이나 `/dev/zero` 같은 장치 파일로 인해 메모리가 한없이 증가했습니다.3321[`--settings`](https://code.claude.com/docs/ko/cli-reference#cli-flags)에 전달한 파일이 2 MiB보다 크므로, `claude`는 파일을 불러오지 않고 시작 시 종료 코드 1로 종료됩니다. v2.1.214 이전에는 Claude Code가 크기 검사 없이 파일을 읽었으며, 수 기가바이트 파일이나 `/dev/zero` 같은 장치 파일로 인해 메모리가 한없이 증가했습니다.

3292 3322 

3293```text theme={null}3323```text theme={null}

3294Error: Settings file exceeds the 2MiB limit: /path/to/settings.json3324Error: Settings file exceeds the 2MiB limit: /path/to/settings.json

3295```3325```

3296 3326 

3297Claude Code는 일반 파일이 아닌 `--settings` 경로도 같은 방식으로 거부합니다. 장치, FIFO, 소켓은 `Error: Cannot use settings file (Not a regular file (device, FIFO, or socket))` 뒤에 경로를 표시하고, 디렉터리는 `EISDIR` 사유를 표시합니다.3327Claude Code는 일반 파일이 아닌 `--settings` 경로도 같은 방식으로 거부합니다. 장치, FIFO 또는 소켓은 `Error: Cannot use settings file (Not a regular file (device, FIFO, or socket))`와 그 뒤에 경로를 표시하고, 디렉터리는 `EISDIR` 사유를 표시합니다.

3298 3328 

3299**해결 방법:**3329**해결 방법:**

3300 3330 

3302 3332 

3303### Configuration error in \~/.claude.json3333### Configuration error in \~/.claude.json

3304 3334 

3305Claude Code가 계정 정보, MCP 서버, 프로젝트별 상태를 저장하는 파일인 `~/.claude.json`을 구문 분석하지 못했습니다. 파일은 변경되지 않았습니다. `claude -p` 같은 [비대화형](https://code.claude.com/docs/ko/headless.md) 시작은 파일을 복구할 때까지 매번 종료 코드 1로 종료됩니다.3335Claude Code가 계정 정보, MCP 서버, 프로젝트별 상태를 담고 있는 파일인 `~/.claude.json`을 파싱하지 못했습니다. `claude -p` 같은 [비대화형](https://code.claude.com/docs/ko/headless.md) 시작은 종료 코드 1로 종료됩니다.

3306 3336 

3307Claude Code가 [백업](https://code.claude.com/docs/ko/claude-directory.md#cleaned-up-automatically)을 찾으면 출력에 백업 이름과 이를 다시 복사하는 `cp` 줄이 표시됩니다.3337Claude Code가 [백업](https://code.claude.com/docs/ko/claude-directory.md#cleaned-up-automatically)을 찾으면, 출력에 해당 백업이 표시되고 이를 다시 복사하는 `cp` 줄이 출력됩니다:

3308 3338 

3309```text wrap theme={null}3339```text wrap theme={null}

3310Claude configuration file at /home/user/.claude.json is corrupted: <JSON parser's message>3340Claude configuration file at /home/user/.claude.json is corrupted: <JSON parser's message>

3317 3347 

3318**해결 방법:**3348**해결 방법:**

3319 3349 

3320* **출력에 `cp` 줄이 있는 경우**: 터미널에서 해당 줄을 실행합니다. Windows에서는 PowerShell에서 실행합니다. 손상된 파일을 `~/.claude.json`의 이전 버전인 백업으로 대체합니다.3350* **출력에 `cp` 줄이 있는 경우**: 해당 줄을 터미널에서 실행합니다. Windows에서는 PowerShell에서 실행합니다.

3321* **출력에 `cp` 줄이 없거나 실행 후에도 오류가 다시 발생하는 경우**: `~/.claude.json`의 JSON을 수정하거나, [`~/.claude/backups/`](https://code.claude.com/docs/ko/claude-directory#cleaned-up-automatically)에 다른 `.claude.json.backup.<timestamp>` 파일이 있으면 그 파일로 덮어쓰거나, 파일 이름을 변경합니다. `~/.claude.json`에 파일이 없으면 Claude Code는 기본 설정으로 시작하며 파일에 있던 내용은 모두 사용되지 않습니다.3351* **출력에 `cp` 줄이 없거나, 실행한 후에도 오류가 다시 나타나는 경우**: `~/.claude.json`에 구성이 아직 남아 있다면 JSON을 수정합니다. 수정할 수 없다면 [`~/.claude/backups/`](https://code.claude.com/docs/ko/claude-directory#cleaned-up-automatically)에 다른 `.claude.json.backup.<timestamp>` 파일이 있을 경우 이를 덮어쓰거나, 파일 이름을 변경합니다. `~/.claude.json`에 파일이 없으면 Claude Code는 기본 설정으로 시작하며 파일에 있던 내용은 모두 사라집니다.

3322 3352* **`~/.claude.json`에 더 이상 구성이 없는 경우**: [`~/.claude/backups/`](https://code.claude.com/docs/ko/claude-directory#cleaned-up-automatically)나 홈 디렉터리에서 구성이 남아 있는 `.claude.json.corrupted.<timestamp>` 파일을 찾습니다. JSON을 수정한 다음 `~/.claude.json` 위에 복사합니다. 해당 파일을 찾거나 수정할 수 없다면, 구성이 남아 있는 `.claude.json.backup.<timestamp>` 파일로 같은 단계를 시도합니다. 그런 파일도 없다면 `~/.claude.json`의 이름을 변경하고 [`claude mcp add`](https://code.claude.com/docs/ko/mcp#installing-mcp-servers)로 MCP 서버를 다시 추가합니다.

3323v2.1.318 이전에는 비대화형 시작에서 이 오류가 출력된 후 `~/.claude.json`이 기본값으로 남아, 다음 시작이 기존 구성 없이 실행되었습니다.

3324 3353 

3325### Claude configuration file was empty and no backup holds anything3354### Claude configuration file was empty and no backup holds anything

3326 3355 

3327시작 시 나타나는 이 메시지는 메시지에 표시된 파일이 비어 있고 해당 파일의 [`.backup` 사본](https://code.claude.com/docs/ko/claude-directory#cleaned-up-automatically)에도 아무 내용이 없다는 의미입니다. Claude Code는 해당 파일이 담는 내용에 대해 기본값으로 시작했습니다. `settings.json` 파일과 `.mcp.json`은 별도의 파일입니다.3356시작 시 이 메시지가 표시되면 메시지에 표시된 파일이 비어 있었고, 해당 파일의 [`.backup` 사본](https://code.claude.com/docs/ko/claude-directory#cleaned-up-automatically) 중 어느 것에도 내용이 없다는 의미입니다. Claude Code는 해당 파일이 담는 내용을 기본값으로 설정하고 시작했습니다. `settings.json` 파일과 `.mcp.json`은 별도의 파일입니다.

3328 3357 

3329```text wrap theme={null}3358```text wrap theme={null}

3330Claude configuration file at /home/user/.claude.json was empty and no backup holds anything: starting with defaults.3359Claude configuration file at /home/user/.claude.json was empty and no backup holds anything: starting with defaults.

3335* 해당 파일에 구성해 두었던 내용을 다시 설정합니다. 예를 들어 터미널에서 `claude mcp add`로 `user` 및 `local` 범위의 [MCP 서버](https://code.claude.com/docs/ko/mcp.md#mcp-installation-scopes)를 추가합니다.3364* 해당 파일에 구성해 두었던 내용을 다시 설정합니다. 예를 들어 터미널에서 `claude mcp add`로 `user` 및 `local` 범위의 [MCP 서버](https://code.claude.com/docs/ko/mcp.md#mcp-installation-scopes)를 추가합니다.

3336* Claude Code가 요청하면 다시 로그인합니다3365* Claude Code가 요청하면 다시 로그인합니다

3337 3366 

3338v2.1.318 이전에는 Claude Code가 백업 없는 빈 파일을 [손상됨](#configuration-error-in-claude-json)으로 보고했습니다.3367v2.1.318 이전에는 Claude Code가 백업이 없는 빈 파일을 [손상된](#configuration-error-in-claude-json) 파일로 보고했습니다.

3339 3368 

3340### The current directory no longer exists3369### The current directory no longer exists

3341 3370 

3342셸이 진입한 후 삭제되거나 이동된 디렉터리(예: 다른 셸이 제거한 worktree나 임시 디렉터리)에서 `claude`를 시작했습니다. Claude Code가 작업 디렉터리를 읽을 수 없으므로 대화형 모드와 [비대화형](https://code.claude.com/docs/ko/headless.md) 모드 모두에서 세션을 시작하기 전에 종료 코드 1로 종료됩니다. v2.1.239 이전에는 이 메시지 대신 Claude Code가 축소된 번들 소스와 원시 `ENOENT ... uv_cwd` 스택을 stderr에 출력하며 충돌했습니다.3371셸이 진입한 후 삭제되거나 이동된 디렉터리(예: 다른 셸이 제거한 worktree 또는 임시 디렉터리)에서 `claude`를 시작했습니다. Claude Code가 작업 디렉터리를 읽을 수 없으므로 대화형 모드와 [비대화형](https://code.claude.com/docs/ko/headless.md) 모드 모두에서 세션을 시작하기 전에 종료 코드 1로 종료됩니다. v2.1.239 이전에는 이 메시지 대신 Claude Code가 축소된 번들 소스와 원시 `ENOENT ... uv_cwd` 스택을 stderr에 출력하며 비정상 종료되었습니다.

3343 3372 

3344```text theme={null}3373```text theme={null}

3345The current directory no longer exists (it was deleted or moved). Start Claude Code from an existing directory.3374The current directory no longer exists (it was deleted or moved). Start Claude Code from an existing directory.

3346error: The current working directory was deleted, so that command didn't work. Please cd into a different directory and try again.3375error: The current working directory was deleted, so that command didn't work. Please cd into a different directory and try again.

3347```3376```

3348 3377 

3349두 형식 모두 원인과 해결 방법은 같습니다.3378두 형식의 원인과 해결 방법은 동일합니다.

3350 3379 

3351권한 변경 등 다른 이유로 Claude Code가 작업 디렉터리를 읽을 수 없으면 메시지에 대신 오류 코드가 표시됩니다: `Can't read the current directory (EACCES). Start Claude Code from a different directory.`3380권한 변경 등 다른 이유로 Claude Code가 작업 디렉터리를 읽을 수 없는 경우, 메시지에는 대신 오류 코드가 표시됩니다: `Can't read the current directory (EACCES). Start Claude Code from a different directory.`

3352 3381 

3353macOS에서 `~/Desktop`, `~/Documents`, `~/Downloads` 또는 iCloud Drive에 있는 디렉터리에 대해 `EPERM`이 발생하면 대개 macOS가 터미널 앱의 해당 폴더 접근을 차단하고 있다는 의미입니다. 해당 폴더를 읽는 다른 명령도 같은 방식으로 실패하며, 그곳에서 `ls`를 실행하면 `sudo`를 사용하더라도 `Operation not permitted`가 표시됩니다.3382macOS에서 `~/Desktop`, `~/Documents`, `~/Downloads` 또는 iCloud Drive의 디렉터리에 대해 `EPERM`이 발생하면, 대개 macOS가 터미널 앱의 해당 폴더 접근을 차단하고 있다는 의미입니다. 해당 폴더를 읽는 다른 명령도 같은 방식으로 실패합니다. 그 위치에서 `ls`를 실행하면 `sudo`를 사용하더라도 `Operation not permitted`가 보고됩니다.

3354 3383 

3355**해결 방법:**3384**해결 방법:**

3356 3385 

3357* 홈 디렉터리나 프로젝트 디렉터리처럼 존재하는 디렉터리로 이동한 다음 `claude`를 다시 실행합니다3386* 홈 디렉터리나 프로젝트 디렉터리처럼 존재하는 디렉터리로 이동한 다음 `claude`를 다시 실행합니다

3358* 디렉터리가 같은 경로에 다시 생성된 경우 셸은 여전히 삭제된 디렉터리를 가리키고 있습니다. `cd "$PWD"`를 실행하거나 디렉터리에서 나갔다가 다시 들어간 다음 `claude`를 다시 실행합니다3387* 디렉터리가 같은 경로에 다시 생성된 경우에도 셸은 여전히 삭제된 디렉터리를 가리키고 있습니다. `cd "$PWD"`를 실행하거나 디렉터리를 나갔다가 다시 들어간 다음 `claude`를 다시 실행합니다

3359* macOS에서 `EPERM`이 발생하면 Cmd+Q로 터미널 앱을 종료하고 다시 연 다음, 해당 폴더로 돌아가 `claude`를 실행합니다. 그래도 해당 폴더에서 `ls`가 실패하면 **System Settings > Privacy & Security > Files and Folders**를 열고 터미널 앱에 대해 해당 폴더를 켠 다음 터미널을 다시 엽니다3388* macOS에서 `EPERM`이 발생하면 Cmd+Q로 터미널 앱을 종료하고, 다시 연 다음 해당 폴더로 돌아가 `claude`를 실행합니다. 해당 폴더에서 `ls`가 여전히 실패하면 **System Settings > Privacy & Security > Files and Folders**를 열고 터미널 앱에 대해 해당 폴더를 켠 다음 터미널을 다시 엽니다

3360 3389 

3361### 임시 디렉터리가 거부되었거나 생성할 수 없음3390### 임시 디렉터리가 거부되었거나 생성할 수 없음

3362 3391 

3363macOS와 Linux에서 Claude Code는 시작 시 시스템 임시 디렉터리 또는 [`CLAUDE_CODE_TMPDIR`](https://code.claude.com/docs/ko/env-vars) 재정의 위치 아래에 전용 임시 디렉터리 `claude-<uid>`를 만듭니다. 디렉터리를 만들 수 없거나 해당 경로에 이미 있는 항목이 안전성 검사를 통과하지 못하면, Claude Code는 세션을 시작하지 않고 실패 내용을 stderr에 출력한 뒤 종료 코드 1로 종료됩니다.3392macOS와 Linux에서 Claude Code는 시작 시 시스템 임시 디렉터리 또는 [`CLAUDE_CODE_TMPDIR`](https://code.claude.com/docs/ko/env-vars) 재정의 위치 아래에 `claude-<uid>`라는 비공개 임시 디렉터리를 생성합니다. 디렉터리를 생성할 수 없거나 해당 경로에 이미 있는 항목이 안전 검사를 통과하지 못하면, Claude Code는 세션을 시작하지 않고 실패 내용을 stderr에 출력한 후 종료 코드 1로 종료됩니다:

3364 3393 

3365```text wrap theme={null}3394```text wrap theme={null}

3366Claude Code's temporary directory /tmp/claude-501 could not be created: the volume holding /tmp is full (ENOSPC). Free space on that volume, or set CLAUDE_CODE_TMPDIR to a directory on another one, then try again.3395Claude Code's temporary directory /tmp/claude-501 could not be created: the volume holding /tmp is full (ENOSPC). Free space on that volume, or set CLAUDE_CODE_TMPDIR to a directory on another one, then try again.

3374 3403 

3375**해결 방법:**3404**해결 방법:**

3376 3405 

3377* `could not be created` 뒤에 `is full (ENOSPC)`가 표시되면 메시지에 표시된 볼륨의 디스크 공간을 확보합니다. 대신 `your disk quota on the volume holding /tmp is used up (EDQUOT)`가 표시되면 해당 볼륨에서 더 이상 필요하지 않은 본인 파일을 삭제합니다3406* `could not be created` 뒤에 `is full (ENOSPC)`가 오는 경우 메시지에 표시된 볼륨의 디스크 공간을 확보합니다. 대신 `your disk quota on the volume holding /tmp is used up (EDQUOT)`가 표시되면 해당 볼륨에서 더 이상 필요하지 않은 본인 파일을 삭제합니다

3378* `Refusing to use it` 형식의 경우 링크가 가리키는 대상이 아니라 메시지에 표시된 항목 자체를 제거하고 Claude Code를 다시 시작합니다. `owned by uid` 형식의 경우 관리자나 해당 사용자만 이를 제거할 수 있습니다3407* `Refusing to use it` 형식의 경우 링크가 가리키는 대상이 아니라 메시지에 표시된 항목 자체를 제거하고 Claude Code를 다시 시작합니다. `owned by uid` 형식의 경우 관리자나 해당 사용자만 이를 제거할 수 있습니다

3379* `is not readable`의 경우 표시된 디렉터리에 `chmod 0700`을 실행하거나, 디렉터리를 제거하고 다시 시작합니다3408* `is not readable`의 경우 표시된 디렉터리에 `chmod 0700`을 실행하거나, 디렉터리를 제거하고 다시 시작합니다

3380* 어떤 경우든 거부된 경로는 그대로 두고 [`CLAUDE_CODE_TMPDIR`](https://code.claude.com/docs/ko/env-vars)를 직접 제어하는 디렉터리로 설정한 다음 Claude Code를 다시 시작할 수 있습니다3409* 어떤 경우든 거부된 경로는 그대로 두고, [`CLAUDE_CODE_TMPDIR`](https://code.claude.com/docs/ko/env-vars)를 직접 제어할 수 있는 디렉터리로 설정한 다음 Claude Code를 다시 시작할 수 있습니다

3381 3410 

3382v2.1.309 이전에는 볼륨이 가득 찼거나 할당량을 모두 사용한 경우 Claude Code가 운영 체제의 오류 텍스트만 출력했습니다. 예를 들면 `ENOSPC: no space left on device, mkdir '/tmp/claude-501'`이며, 같은 단계가 적용됩니다.3411v2.1.309 이전에는 볼륨이 가득 찼거나 할당량을 모두 사용한 경우 Claude Code가 운영 체제의 오류 텍스트만 출력했습니다. 예를 들면 `ENOSPC: no space left on device, mkdir '/tmp/claude-501'`이며, 같은 단계가 적용됩니다.

3383 3412 

3413### Claude Code could not save because the disk is full

3414 

3415[`claude -p`](https://code.claude.com/docs/ko/headless) 실행 후 stderr에 이 줄이 표시되면 디스크가 가득 찼거나 디스크 할당량을 모두 사용하여 Claude Code가 실행 내용을 모두 저장하지 못했다는 의미입니다:

3416 

3417```text wrap theme={null}

3418Error: Claude Code could not save all of this session's transcript under /Users/you/.claude because the disk is full (ENOSPC). If you resume this session, part of the conversation may be missing. Free up space on that disk before the next run.

3419```

3420 

3421텍스트 또는 `json` 출력에서는 실행이 종료 코드 1로 종료되며, 답변은 이미 출력된 상태입니다. `stream-json` 출력에서는 실행이 평소의 종료 코드를 유지하며, 답변도 그대로 전달됩니다.

3422 

3423**해결 방법:**

3424 

3425* **`the disk is full (ENOSPC)`**: 다음 실행 전에 메시지의 경로를 담고 있는 디스크의 공간을 확보합니다

3426* **`your disk quota is used up (EDQUOT)`**: 다음 실행 전에 공간을 확보하거나 더 큰 할당량을 요청합니다

3427 

3384### Directory couldn't be resolved to a real location3428### Directory couldn't be resolved to a real location

3385 3429 

3386작업 디렉터리의 하위 디렉터리에 대해 `/add-dir`을 실행했는데, Claude Code가 해당 디렉터리를 실제 위치로 확인하지 못했습니다.3430작업 디렉터리의 하위 디렉터리에 대해 `/add-dir`을 실행했는데, Claude Code가 디렉터리를 실제 위치로 확인할 수 없었습니다.

3387 3431 

3388작업 디렉터리의 하위 디렉터리에는 이미 파일 접근 권한이 있으므로 `/add-dir`은 해당 디렉터리의 스킬, 명령, 에이전트만 불러옵니다. 이를 불러오기 전에 Claude Code는 심볼릭 링크를 모두 해석한 디렉터리의 실제 위치가 작업 디렉터리 안에 있는지 확인합니다. Claude Code가 해당 위치를 확인할 수 없으면 아무것도 불러오지 않고 다음 메시지를 표시합니다.3432작업 디렉터리의 하위 디렉터리에는 이미 파일 접근 권한이 있으므로 `/add-dir`은 해당 디렉터리의 스킬, 명령, 에이전트만 불러옵니다. 불러오기 전에 Claude Code는 심볼릭 링크를 모두 확인한 디렉터리의 실제 위치가 작업 디렉터리 안에 있는지 검사합니다. Claude Code가 해당 위치를 확인할 수 없으면 아무것도 불러오지 않고 다음 메시지를 표시합니다:

3389 3433 

3390```text theme={null}3434```text theme={null}

3391packages/app couldn't be resolved to a real location, so its skills, commands, and agents weren't loaded. Check that it is a directory inside the working directory and try again.3435packages/app couldn't be resolved to a real location, so its skills, commands, and agents weren't loaded. Check that it is a directory inside the working directory and try again.

3394**해결 방법:**3438**해결 방법:**

3395 3439 

3396* 경로가 작업 디렉터리 안의 실제 디렉터리를 가리키는지 확인한 다음 `/add-dir`을 다시 실행합니다3440* 경로가 작업 디렉터리 안의 실제 디렉터리를 가리키는지 확인한 다음 `/add-dir`을 다시 실행합니다

3397* 이 메시지는 파일 접근 권한을 변경하지 않으며, 디렉터리의 `.claude/` 콘텐츠가 로드되지 않았다는 사실만 알립니다3441* 이 메시지는 파일 접근 권한을 변경하지 않습니다. 디렉터리의 `.claude/` 콘텐츠를 불러오지 않았다는 것만 알려 줍니다

3398 3442 

3399v2.1.261 이전에는 작업 디렉터리가 `/net/<host>` 자동 마운트에 있을 때 모든 `/add-dir <subdirectory>`에 대해 이 메시지가 나타났습니다. 해당 위치에서는 Claude Code가 설계상 경로 확인을 하지 않으므로, 디렉터리에는 문제가 없었고 재시도해도 소용이 없었습니다.3443v2.1.261 이전에는 작업 디렉터리가 `/net/<host>` 자동 마운트에 있을 때 모든 `/add-dir <subdirectory>`에 대해서도 이 메시지가 표시되었습니다. 이 경우 Claude Code는 의도적으로 경로 확인을 하지 않으며, 디렉터리에는 문제가 없고 재시도해도 도움이 되지 않았습니다.

3400 3444 

3401### Workspace not trusted when starting Remote Control3445### Workspace not trusted when starting Remote Control

3402 3446 

3403> [!NOTE]3447> [!NOTE]

3404>3448>

3405> `claude ultrareview`가 `Error: Workspace not trusted`를 출력했다면 대신 [claude ultrareview 실행 시 Workspace not trusted](#workspace-not-trusted-when-running-claude-ultrareview)를 참조하세요.3449> `claude ultrareview`가 `Error: Workspace not trusted`를 출력한 경우에는 대신 [Workspace not trusted when running claude ultrareview](#workspace-not-trusted-when-running-claude-ultrareview)를 참조하세요.

3406 3450 

3407신뢰하지 않은 디렉터리에서 `claude remote-control` 또는 별칭 `claude rc`로 [Remote Control](https://code.claude.com/docs/ko/remote-control.md) 서버 모드를 시작했는데, 명령이 해당 디렉터리를 신뢰할지 물어볼 수 없었습니다. 예를 들어 표준 입력이나 표준 출력 중 하나가 리디렉션되거나 파이프로 연결되어 터미널이 아닌 경우입니다. 명령은 종료 코드 1로 종료됩니다.3451신뢰하지 않은 디렉터리에서 `claude remote-control` 또는 그 별칭인 `claude rc`로 [Remote Control](https://code.claude.com/docs/ko/remote-control.md) 서버 모드를 시작했으며, 명령이 해당 디렉터리를 신뢰할지 물어볼 수 없었습니다. 예를 들어 표준 입력이나 표준 출력 중 하나가 리디렉션되거나 파이프로 연결되어 터미널이 아닌 경우입니다. 명령은 종료 코드 1로 종료됩니다:

3408 3452 

3409```text theme={null}3453```text theme={null}

3410Error: Workspace not trusted. Please run `claude` in /Users/you/project first to review and accept the workspace trust dialog.3454Error: Workspace not trusted. Please run `claude` in /Users/you/project first to review and accept the workspace trust dialog.

3411```3455```

3412 3456 

3413역시 `Error: Workspace not trusted.`로 시작하는 두 가지 변형은 디렉터리를 신뢰했을 때 켜지는 항목을 표시하기에 터미널이 너무 작거나 터미널이 크기를 보고하지 않은 경우에 나타납니다. 창을 키우거나 일반 터미널 창으로 전환한 다음 `claude rc`를 다시 실행합니다.3457역시 `Error: Workspace not trusted.`로 시작하는 두 가지 변형은, 디렉터리를 신뢰하면 켜지는 항목을 표시하기에 너무 작은 터미널이나 크기를 보고하지 않는 터미널에서 표시됩니다. 창을 키우거나 일반 터미널 창으로 전환한 다음 `claude rc`를 다시 실행합니다.

3414 3458 

3415홈 디렉터리에서는 메시지가 다릅니다. 워크스페이스 신뢰 대화 상자는 홈 디렉터리에 대한 신뢰를 절대 저장하지 않으므로, 그곳에서 수락해도 이 검사를 통과할 수 없기 때문입니다. v2.1.214 이전에는 홈 디렉터리에서도 위의 메시지가 표시되었는데, 그 안내는 홈 디렉터리에서는 성공할 수 없습니다.3459홈 디렉터리에서는 메시지가 다릅니다. 워크스페이스 신뢰 대화 상자는 홈 디렉터리에 대한 신뢰를 저장하지 않으므로, 그곳에서 수락해도 이 검사를 통과할 수 없기 때문입니다. v2.1.214 이전에는 홈 디렉터리에서도 위의 메시지가 표시되었는데, 그 안내는 홈 디렉터리에서는 성공할 수 없습니다.

3416 3460 

3417```text theme={null}3461```text theme={null}

3418Error: Workspace not trusted. /Users/you is your home directory, and for security home-directory trust is never saved, so running `claude` here first won't help. Run `claude rc` from a project directory instead (run `claude` there once to accept the trust dialog).3462Error: Workspace not trusted. /Users/you is your home directory, and for security home-directory trust is never saved, so running `claude` here first won't help. Run `claude rc` from a project directory instead (run `claude` there once to accept the trust dialog).

3419```3463```

3420 3464 

3421[`Trust <directory>?` 질문](https://code.claude.com/docs/ko/remote-control#requirements)에 `n`으로 답하거나 Enter를 누르면, 명령은 디렉터리 이름이 포함된 `Remote Control did not start` 메시지를 출력하고 종료 코드 1로 종료됩니다. `y`로 답하려면 `claude rc`를 다시 실행합니다.3465[`Trust <directory>?` 질문](https://code.claude.com/docs/ko/remote-control#requirements)에 `n`으로 답하거나 Enter를 누르면, 명령은 디렉터리를 표시하는 `Remote Control did not start` 메시지를 출력하고 종료 코드 1로 종료됩니다. `claude rc`를 다시 실행하여 `y`로 답합니다.

3422 3466 

3423**해결 방법:**3467**해결 방법:**

3424 3468 

3425* 먼저 터미널에서 디렉터리를 신뢰합니다. 그곳에서 `claude rc`를 실행하고 `y`로 답하거나, `claude`를 실행하고 [워크스페이스 신뢰 대화 상자](https://code.claude.com/docs/ko/permissions.md#project-allow-rules-and-workspace-trust)를 수락한 다음 원래 명령을 다시 실행합니다3469* 먼저 터미널에서 디렉터리를 신뢰합니다. 해당 위치에서 `claude rc`를 실행하고 `y`로 답하거나, `claude`를 실행하고 [워크스페이스 신뢰 대화 상자](https://code.claude.com/docs/ko/permissions.md#project-allow-rules-and-workspace-trust)를 수락한 다음, 원래 명령을 다시 실행합니다

3426* 홈 디렉터리에 있다면 프로젝트 디렉터리로 이동해 그곳에서 Remote Control을 시작합니다3470* 홈 디렉터리에 있는 경우 프로젝트 디렉터리로 이동하여 그곳에서 Remote Control을 시작합니다

3427 3471 

3428v2.1.284 이전에는 터미널에서도 명령이 묻지 않았습니다.3472v2.1.284 이전에는 터미널에서도 명령이 묻지 않았습니다.

3429 3473 

3430### claude ultrareview 실행 시 Workspace not trusted3474### Workspace not trusted when running claude ultrareview

3431 3475 

3432신뢰하지 않은 폴더에서 [`claude ultrareview`](https://code.claude.com/docs/ko/ultrareview#trust-the-folder-before-the-review-runs)가 해당 폴더를 신뢰하는지 물어볼 수 없으면, 리뷰가 시작되기 전에 실행이 종료 코드 1로 종료됩니다.3476신뢰하지 않은 폴더에서 [`claude ultrareview`](https://code.claude.com/docs/ko/ultrareview#trust-the-folder-before-the-review-runs)가 해당 폴더를 신뢰하는지 물어볼 수 없으면, 리뷰가 시작되기 전에 실행이 종료 코드 1로 종료됩니다:

3433 3477 

3434```text theme={null}3478```text theme={null}

3435Error: Workspace not trusted. Please run `claude` in /Users/you/project first to review and accept the workspace trust dialog. Or, in a script or CI job, pass `--trust-workspace` to trust the folder for this run only.3479Error: Workspace not trusted. Please run `claude` in /Users/you/project first to review and accept the workspace trust dialog. Or, in a script or CI job, pass `--trust-workspace` to trust the folder for this run only.

3436```3480```

3437 3481 

3438예를 들어 하위 명령은 표준 입력이나 표준 출력이 터미널이 아니면 물어볼 수 없습니다. `claude ultrareview --json > findings.json`처럼 출력을 파일로 보내면 표준 출력은 터미널이 아닙니다.3482예를 들어 표준 입력이나 표준 출력이 터미널이 아니면 하위 명령이 물어볼 수 없습니다. `claude ultrareview --json > findings.json`처럼 출력을 파일로 보내면 표준 출력은 터미널이 아니게 됩니다.

3439 3483 

3440**해결 방법:**3484**해결 방법:**

3441 3485 

3442* 스크립트나 CI 작업에서는 `--trust-workspace`를 추가해 해당 실행에 대해 폴더를 신뢰합니다: `claude ultrareview --trust-workspace`. 이 경우 git과 Claude Code가 폴더의 git 구성과 프로젝트 설정에 지정된 프로그램을 실행할 수 있으므로, 신뢰하는 코드에 대해서만 추가합니다. 코드를 신뢰하지 않는 풀 리퀘스트라면 [신뢰하는 브랜치에서 리뷰를 실행](https://code.claude.com/docs/ko/ultrareview.md#trust-the-folder-before-the-review-runs)합니다.3486* 스크립트나 CI 작업에서는 `--trust-workspace`를 추가하여 해당 실행에 대해 폴더를 신뢰합니다: `claude ultrareview --trust-workspace`. 이 경우 git과 Claude Code가 폴더의 git 구성과 프로젝트 설정에 지정된 프로그램을 실행할 수 있으므로, 신뢰하는 코드에 대해서만 추가합니다. 코드를 신뢰할 수 없는 풀 리퀘스트의 경우 [신뢰하는 브랜치에서 리뷰를 실행](https://code.claude.com/docs/ko/ultrareview.md#trust-the-folder-before-the-review-runs)합니다.

3443* 자신의 컴퓨터에서는 해당 폴더에서 `claude`를 실행하고 [워크스페이스 신뢰 대화 상자](https://code.claude.com/docs/ko/permissions.md#project-allow-rules-and-workspace-trust)를 수락한 다음 원래 명령을 다시 실행합니다3487* 본인 컴퓨터에서는 해당 폴더에서 `claude`를 실행하고 [워크스페이스 신뢰 대화 상자](https://code.claude.com/docs/ko/permissions.md#project-allow-rules-and-workspace-trust)를 수락한 다음, 원래 명령을 다시 실행합니다

3444 3488 

3445`claude ultrareview`에서 나오는 다음 메시지는 모두 리뷰가 시작되지 않았으며 종료 코드가 1이라는 의미입니다.3489`claude ultrareview`의 다음 메시지는 모두 리뷰가 시작되지 않았으며 종료 코드가 1이라는 의미입니다:

3446 3490 

3447* **`Error: Workspace not trusted. This terminal ...`**: 터미널이 행과 열 수를 보고하지 않았거나, 신뢰 질문과 경고를 표시할 공간이 부족합니다. 터미널을 키우거나 크기를 보고하는 터미널을 사용한 다음 `claude ultrareview`를 다시 실행합니다. 홈 디렉터리 외부라면 해당 폴더에서 `claude`를 한 번 실행하고 신뢰 대화 상자를 수락해 이후 실행에서 묻지 않도록 할 수도 있습니다.3491* **`Error: Workspace not trusted. This terminal ...`**: 터미널이 행과 열 수를 보고하지 않았거나, 신뢰 질문과 경고를 표시할 수 없습니다. 터미널을 키우거나 크기를 보고하는 터미널을 사용한 다음 `claude ultrareview`를 다시 실행합니다. 홈 디렉터리가 아닌 곳에서는 해당 폴더에서 `claude`를 한 번 실행하고 신뢰 대화 상자를 수락하여 이후 실행에서 묻지 않도록 할 수도 있습니다.

3448* **`Error: Workspace not trusted. <folder> is your home directory`**: 홈 디렉터리에 대한 신뢰는 절대 저장되지 않으므로 그곳에서 먼저 `claude`를 실행해도 도움이 되지 않습니다. 대신 프로젝트 디렉터리에서 `claude`를 한 번 실행해 신뢰 대화 상자를 수락한 후 그곳에서 `claude ultrareview`를 실행하거나, `--trust-workspace`를 추가합니다.3492* **`Error: Workspace not trusted. <folder> is your home directory`**: 홈 디렉터리에 대한 신뢰는 저장되지 않으므로, 그곳에서 먼저 `claude`를 실행해도 도움이 되지 않습니다. 대신 프로젝트 디렉터리에서 `claude`를 한 번 실행하여 신뢰 대화 상자를 수락한 후 그곳에서 `claude ultrareview`를 실행하거나, `--trust-workspace`를 추가합니다.

3449* **`No answer in time.` 뒤에 `Error: Workspace not trusted`**: `Trust <folder>? [y/N]` 질문에 5분 동안 응답이 없었습니다. `claude ultrareview`를 다시 실행하고 질문에 답합니다.3493* **`No answer in time.` 다음에 `Error: Workspace not trusted`**: `Trust <folder>? [y/N]` 질문에 5분 동안 응답이 없었습니다. `claude ultrareview`를 다시 실행하고 질문에 답합니다.

3450* **`Ultrareview did not start: <folder> is not trusted`**: `n`으로 답하거나 Enter를 누르는 등 `Trust <folder>? [y/N]` 질문에서 거절했습니다. 리뷰를 시작하려면 `claude ultrareview`를 다시 실행하고 `y`로 답합니다.3494* **`Ultrareview did not start: <folder> is not trusted`**: 예를 들어 `n`으로 답하거나 Enter를 눌러 `Trust <folder>? [y/N]` 질문을 거절했습니다. 리뷰를 시작하려면 `claude ultrareview`를 다시 실행하고 `y`로 답합니다.

3451* **``Ultrareview did not start: `--trust-workspace` takes no value``**: `--trust-workspace` 뒤에 PR 번호나 `false`처럼 플래그가 아닌 것이 옵니다. 폴더를 신뢰하지 않는다면 플래그를 빼세요. 이번 실행에서 신뢰하려면 PR 번호나 기본 브랜치를 플래그 앞에 둡니다: `claude ultrareview 1234 --trust-workspace`.3495* **``Ultrareview did not start: `--trust-workspace` takes no value``**: PR 번호나 `false`처럼 플래그가 아닌 무언가가 `--trust-workspace` 뒤에 왔습니다. 폴더를 신뢰하지 않는다면 플래그를 생략합니다. 이번 실행에 한해 신뢰하려면 PR 번호나 기준 브랜치를 플래그 앞에 둡니다: `claude ultrareview 1234 --trust-workspace`.

3452 3496 

3453v2.1.309 이전에는 `claude ultrareview`가 `--trust-workspace`를 받지 않았습니다.3497v2.1.309 이전에는 `claude ultrareview`가 `--trust-workspace`를 받지 않았습니다.

3454 3498 

3499### Remote Control did not start because a question got no answer

3500 

3501이 메시지는 [`claude remote-control`](https://code.claude.com/docs/ko/remote-control)이 메시지에 인용된 최초 실행 질문을 했지만 응답을 받지 못했다는 의미입니다:

3502 

3503```text theme={null}

3504Remote Control did not start: "Enable Remote Control?" got no answer. Run `claude remote-control` at a terminal and answer y once; it won't ask again.

3505Remote Control did not start: "Choose [1/2] (default: 1):" got no answer. You can run `claude remote-control` and choose, or pass --spawn=same-dir or --spawn=worktree.

3506```

3507 

3508**해결 방법:**

3509 

3510* **`Enable Remote Control?`**: 스크립트나 서비스에서는 누군가 응답하기 전에 표준 입력이 끝납니다. 스크립트나 서비스가 실행되는 사용자로 터미널에서 `claude remote-control`을 한 번 실행하고 `y`로 답합니다.

3511* **`Choose [1/2] (default: 1):`**: `claude remote-control`을 다시 실행하여 [생성 모드를 선택](https://code.claude.com/docs/ko/remote-control.md#set-the-default-spawn-mode-for-a-project)하거나, [`--spawn=same-dir` 또는 `--spawn=worktree`](https://code.claude.com/docs/ko/remote-control#start-a-remote-control-session)를 전달하여 질문을 건너뜁니다

3512 

3455### Not carried over to the sessions Remote Control starts3513### Not carried over to the sessions Remote Control starts

3456 3514 

3457`remote-control` 동사 앞에 Remote Control이 시작하는 세션을 제한하거나 구성하는 전역 `claude` 플래그(예: `--settings`, `--setting-sources`, `--permission-mode`, `--disallowed-tools`, `--mcp-config`)를 넣어 [Remote Control](https://code.claude.com/docs/ko/remote-control.md)을 시작했습니다. 동사 앞에 둔 플래그는 해당 세션에 전달되지 않습니다. 대신 Claude Code는 해당 플래그의 이름을 표시하며 시작을 거부합니다.3515`remote-control` 동사 앞에 전역 `claude` 플래그를 두고 [Remote Control](https://code.claude.com/docs/ko/remote-control.md)을 시작했으며, 그 플래그는 `--settings`, `--setting-sources`, `--permission-mode`, `--disallowed-tools`, `--mcp-config`처럼 Remote Control이 시작하는 세션을 제한하거나 구성하는 플래그입니다. 동사 앞에 둔 플래그는 해당 세션에 전달되지 않습니다. 대신 Claude Code는 플래그 이름을 표시하며 시작을 거부합니다:

3458 3516 

3459```text theme={null}3517```text theme={null}

3460Error: `--settings` before `remote-control` is not carried over to the sessions Remote Control starts, so Remote Control refuses to start rather than drop it — remove it, and give Remote Control's own options after the verb (see `claude remote-control --help`).3518Error: `--settings` before `remote-control` is not carried over to the sessions Remote Control starts, so Remote Control refuses to start rather than drop it — remove it, and give Remote Control's own options after the verb (see `claude remote-control --help`).

3461```3519```

3462 3520 

3463`--verbose`, `--model`, 래퍼가 주입한 `--session-id`나 `--plugin-dir`처럼 버려도 무해한 전역 플래그는 거부하지 않습니다. Claude Code는 이를 무시하고 Remote Control이 시작됩니다.3521`--verbose`, `--model`, 또는 래퍼가 주입한 `--session-id`나 `--plugin-dir`처럼 무시해도 문제없는 전역 플래그는 Claude Code가 거부하지 않습니다. 이러한 플래그는 무시되고 Remote Control이 시작됩니다.

3464 3522 

3465Claude Code는 아직 무해하다고 인식하지 않은 전역 플래그에 대해서도 시작을 거부하므로, 최신 릴리스에서 추가된 플래그는 이후 릴리스에서 무해한 것으로 표시될 때까지 이 메시지에 나타날 수 있습니다.3523Claude Code는 아직 무해하다고 인식하지 못한 전역 플래그에 대해서도 시작을 거부하므로, 새 릴리스에서 추가된 플래그는 이후 릴리스에서 무해한 것으로 표시될 때까지 이 메시지에 나타날 수 있습니다.

3466 3524 

3467**해결 방법:**3525**해결 방법:**

3468 3526 

3469* 동사 앞에서 플래그를 제거하고 [Remote Control 자체 옵션](https://code.claude.com/docs/ko/remote-control.md#start-a-remote-control-session)은 동사 뒤에 전달합니다. `claude remote-control --help`에서 옵션 목록을 확인할 수 있습니다3527* 동사 앞에서 플래그를 제거하고 [Remote Control 자체 옵션](https://code.claude.com/docs/ko/remote-control.md#start-a-remote-control-session)을 동사 뒤에 전달합니다. `claude remote-control --help`에 옵션이 나열되어 있습니다

3470* 거부된 플래그가 `--permission-mode`인 경우 `claude remote-control --permission-mode <mode>`를 실행해 Remote Control이 시작하는 세션의 권한 모드를 설정합니다3528* 거부된 플래그가 `--permission-mode`인 경우 `claude remote-control --permission-mode <mode>`를 실행하여 Remote Control이 시작하는 세션의 권한 모드를 설정합니다

3471 3529 

3472v2.1.248 이전에는 전역 플래그가 먼저 오면 `claude remote-control`이 자체 플래그를 받지 않았고, 명령이 `unknown option` 오류로 실패했습니다.3530v2.1.248 이전에는 전역 플래그가 먼저 오면 `claude remote-control`이 자체 플래그를 받지 않았으며, 명령이 `unknown option` 오류로 실패했습니다.

3473 3531 

3474### `--sandbox` or `--no-sandbox` is not supported by claude remote-control3532### `--sandbox` or `--no-sandbox` is not supported by claude remote-control

3475 3533 

3476이 오류는 [Remote Control](https://code.claude.com/docs/ko/remote-control.md) 서버를 시작하는 명령이 `remote-control` 뒤에 `--sandbox` 또는 `--no-sandbox`를 전달하는데, `claude remote-control`이 두 플래그를 모두 받지 않는다는 의미입니다. 서버는 시작하지 않고 종료 코드 1로 종료됩니다.3534이 오류는 [Remote Control](https://code.claude.com/docs/ko/remote-control.md) 서버를 시작하는 명령이 `remote-control` 뒤에 `--sandbox` 또는 `--no-sandbox`를 전달하는데, `claude remote-control`은 두 플래그 모두 받지 않는다는 의미입니다. 서버는 시작하지 않고 종료 코드 1로 종료됩니다:

3477 3535 

3478```text theme={null}3536```text theme={null}

3479Error: --sandbox is not supported by claude remote-control. The flag had no effect and was removed. To sandbox sessions, set sandbox.enabled to true in settings.3537Error: --sandbox is not supported by claude remote-control. The flag had no effect and was removed. To sandbox sessions, set sandbox.enabled to true in settings.

3482 3540 

3483**해결 방법:**3541**해결 방법:**

3484 3542 

3485* 서버를 대신 시작하는 스크립트나 서비스 정의를 포함해 명령에서 플래그를 제거한 다음 다시 실행합니다3543* 서버를 대신 시작하는 스크립트나 서비스 정의를 포함하여 명령에서 플래그를 제거한 다음 다시 실행합니다

3486* 서버가 시작하는 세션을 샌드박스에서 실행하려면 [설정 파일](https://code.claude.com/docs/ko/settings.md#where-settings-live)에서 [`sandbox.enabled`](https://code.claude.com/docs/ko/settings-reference#sandbox-enabled)를 `true`로 설정해 [샌드박싱](https://code.claude.com/docs/ko/sandboxing.md)을 켭니다3544* 서버가 시작하는 세션을 샌드박스에서 실행하려면 [설정 파일](https://code.claude.com/docs/ko/settings.md#where-settings-live)에서 [`sandbox.enabled`](https://code.claude.com/docs/ko/settings-reference#sandbox-enabled)를 `true`로 설정하여 [샌드박싱](https://code.claude.com/docs/ko/sandboxing.md)을 켭니다

3487 3545 

3488두 플래그는 v2.1.300에서 `claude remote-control`에서 제거되었으므로, 이전 버전용으로 작성된 명령에는 여전히 플래그가 포함되어 있을 수 있습니다.3546두 플래그 모두 v2.1.300에서 `claude remote-control`에서 제거되었으므로, 이전 버전용으로 작성된 명령에는 여전히 둘 중 하나가 포함되어 있을 수 있습니다.

3489 3547 

3490### claude import is not yet available in this build3548### claude import is not yet available in this build

3491 3549 

3492[`claude import`](https://code.claude.com/docs/ko/cli-reference#cli-commands)를 실행했는데 Claude Code가 가져오기 흐름이 꺼져 있음을 확인했으므로, 명령이 가져오기를 시작하지 않고 종료 코드 1로 종료됩니다. v2.1.222 이전에는 가져오기 흐름이 꺼진 빌드에서 `import`를 프롬프트로 처리해 이 메시지를 출력하는 대신 대화형 세션을 시작했습니다.3550[`claude import`](https://code.claude.com/docs/ko/cli-reference#cli-commands)를 실행했는데 Claude Code가 가져오기 흐름이 꺼져 있음을 확인했으므로, 명령은 가져오기를 시작하지 않고 종료 코드 1로 종료됩니다. v2.1.222 이전에는 가져오기 흐름이 꺼진 빌드에서 `import`를 프롬프트로 처리하여 이 메시지를 출력하는 대신 대화형 세션을 시작했습니다.

3493 3551 

3494```text theme={null}3552```text theme={null}

3495`claude import` is not yet available in this build. Run `claude` and use /mcp or edit ~/.claude/settings.json directly.3553`claude import` is not yet available in this build. Run `claude` and use /mcp or edit ~/.claude/settings.json directly.

3496```3554```

3497 3555 

3498Claude Code는 Anthropic에서 가져와 디스크에 캐시하는 기능 플래그를 통해 `claude import`를 켭니다. 이 메시지는 캐시된 값이 꺼져 있다는 의미입니다. 원인은 대개 다음 중 하나입니다.3556Claude Code는 Anthropic에서 가져와 디스크에 캐시하는 기능 플래그를 통해 `claude import`를 켭니다. 이 메시지는 캐시된 값이 꺼져 있다는 의미입니다. 원인은 대개 다음 중 하나입니다:

3499 3557 

3500* 설치 후 아직 세션을 시작하지 않아 Claude Code가 플래그를 가져오지 않았습니다. 기능을 사용할 수 있더라도 첫 번째 `claude import`에서 이 메시지가 출력될 수 있습니다.3558* 설치 후 아직 세션을 시작하지 않아 Claude Code가 플래그를 가져오지 않았습니다. 기능을 사용할 수 있는 경우에도 첫 번째 `claude import`에서 이 메시지가 출력될 수 있습니다.

3501* Amazon Bedrock, Google Cloud의 Agent Platform, Microsoft Foundry, Claude Platform on AWS 또는 [Claude apps 게이트웨이](https://code.claude.com/docs/ko/claude-apps-gateway#availability-and-limitations)를 통해 Claude Code를 사용하고 있습니다. 이러한 세션에서는 Claude Code가 기능 플래그를 가져오지 않으므로 `claude import`를 계속 사용할 수 없습니다.3559* Amazon Bedrock, Google Cloud의 Agent Platform, Microsoft Foundry, Claude Platform on AWS를 통해, 또는 [Claude apps 게이트웨이](https://code.claude.com/docs/ko/claude-apps-gateway#availability-and-limitations)를 통해 Claude Code를 사용합니다. 이러한 세션에서는 Claude Code가 기능 플래그를 가져오지 않으므로 `claude import`를 계속 사용할 수 없습니다.

3502* 기능 플래그 가져오기를 끄는 `DISABLE_TELEMETRY`, `DO_NOT_TRACK`, `DISABLE_GROWTHBOOK` 또는 [`CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC`](https://code.claude.com/docs/ko/env-vars)를 설정했으므로 `claude import`를 계속 사용할 수 없습니다.3560* 기능 플래그 가져오기를 끄는 `DISABLE_TELEMETRY`, `DO_NOT_TRACK`, `DISABLE_GROWTHBOOK` 또는 [`CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC`](https://code.claude.com/docs/ko/env-vars)를 설정했으므로 `claude import`를 계속 사용할 수 없습니다.

3503 3561 

3504**해결 방법:**3562**해결 방법:**

3505 3563 

3506* 새로 설치한 경우 `claude`를 시작하고 세션이 로드될 때까지 기다린 다음 종료하고 `claude import`를 다시 실행합니다3564* 새로 설치한 경우 `claude`를 시작하고 세션이 로드될 때까지 기다린 다음 종료하고 `claude import`를 다시 실행합니다

3507* 기능 플래그 가져오기가 계속 꺼져 있는 환경에서는 직접 구성을 설정합니다. [`claude mcp add`](https://code.claude.com/docs/ko/mcp#installing-mcp-servers)로 MCP 서버를 추가하고, 옮기려는 [`CLAUDE.md` 파일](https://code.claude.com/docs/ko/memory#how-claude-md-files-load), [스킬과 명령](https://code.claude.com/docs/ko/skills.md#where-skills-live), [서브에이전트](https://code.claude.com/docs/ko/sub-agents.md#choose-the-subagent-scope)를 만듭니다. 메시지에는 `~/.claude/settings.json`도 언급되어 있습니다. `claude import`가 옮기는 구성 중 이 파일에 담기는 것은 [권한 모드](https://code.claude.com/docs/ko/settings-reference.md#permission-settings)뿐이며, Claude Code는 이 파일에서 MCP 서버를 읽지 않습니다.3565* 기능 플래그 가져오기가 계속 꺼져 있는 경우 구성을 직접 설정합니다. [`claude mcp add`](https://code.claude.com/docs/ko/mcp#installing-mcp-servers)로 MCP 서버를 추가하고, 가져오려는 [`CLAUDE.md` 파일](https://code.claude.com/docs/ko/memory#how-claude-md-files-load), [스킬과 명령](https://code.claude.com/docs/ko/skills.md#where-skills-live), [서브에이전트](https://code.claude.com/docs/ko/sub-agents.md#choose-the-subagent-scope)를 생성합니다. 메시지에는 `~/.claude/settings.json`도 언급됩니다. `claude import`가 가져오는 구성 중 이 파일에는 [권한 모드](https://code.claude.com/docs/ko/settings-reference.md#permission-settings)만 들어 있으며, Claude Code는 이 파일에서 MCP 서버를 읽지 않습니다.

3508 3566 

3509### Could not read Claude Code config3567### Could not read Claude Code config

3510 3568 

3511Claude Code가 계정 정보와 프로젝트별 상태를 저장하는 파일인 `~/.claude.json`을 구문 분석할 수 없는 상태에서 [`claude import`](https://code.claude.com/docs/ko/cli-reference#cli-commands)를 실행했습니다. 하위 명령은 사용 가능 여부를 확인하기 위해 이 파일을 읽지만 대화형 세션이 표시하는 복구 대화 상자는 표시하지 않으므로 종료 코드 1로 종료됩니다. v2.1.222 이전에는 설정 파일을 읽을 수 없을 때 `claude import`가 대화형 세션을 시작했고, 그 세션의 복구 대화 상자가 파일을 처리했습니다.3569Claude Code가 계정 정보와 프로젝트별 상태를 저장하는 파일인 `~/.claude.json`을 파싱할 수 없는 상태에서 [`claude import`](https://code.claude.com/docs/ko/cli-reference#cli-commands)를 실행했습니다. 이 하위 명령은 사용 가능 여부를 확인하기 위해 해당 파일을 읽지만, 대화형 세션이 표시하는 복구 대화 상자는 표시하지 않으므로 종료 코드 1로 종료됩니다. v2.1.222 이전에는 읽을 수 없는 설정 파일이 있을 때 `claude import`가 대화형 세션을 시작했으며, 그 세션의 복구 대화 상자가 파일을 처리했습니다.

3512 3570 

3513```text theme={null}3571```text theme={null}

3514Could not read Claude Code config — run `claude` with no arguments to recover it.3572Could not read Claude Code config — run `claude` with no arguments to recover it.

3516 3574 

3517**해결 방법:**3575**해결 방법:**

3518 3576 

3519* 인수 없이 `claude`를 실행합니다. Claude Code가 잘못된 파일을 감지하고 초기화를 제안합니다. 그런 다음 `claude import`를 다시 실행합니다.3577* 인수 없이 `claude`를 실행합니다. Claude Code가 유효하지 않은 파일을 감지하고 재설정을 제안합니다. 그런 다음 `claude import`를 다시 실행합니다.

3520* 직접 편집한 내용을 유지하려면 대신 편집기에서 `~/.claude.json`의 JSON 구문을 수정한 다음 `claude import`를 다시 실행합니다3578* 직접 편집한 내용을 유지하려면 대신 편집기에서 `~/.claude.json`의 JSON 구문을 수정한 다음 `claude import`를 다시 실행합니다

3521 3579 

3522### Could not import a server from Claude Desktop3580### Could not import a server from Claude Desktop

3523 3581 

3524Claude Code가 `claude mcp add-from-claude-desktop`에서 선택한 서버 중 하나를 추가하지 못했습니다. 명령은 선택한 다른 서버를 계속 가져오며, 추가하지 못한 서버마다 한 줄씩 출력합니다. v2.1.205 이전에는 처음 실패한 서버에서 가져오기가 중단되었습니다.3582Claude Code가 `claude mcp add-from-claude-desktop`에서 선택한 서버 중 하나를 추가하지 못했습니다. 명령은 선택한 다른 서버는 계속 가져오며, 추가하지 못한 서버마다 한 줄씩 출력합니다. v2.1.205 이전에는 처음 실패한 서버에서 가져오기가 중단되었습니다.

3525 3583 

3526```text theme={null}3584```text theme={null}

3527Could not import my server: Invalid name my server. Names can only contain letters, numbers, hyphens, and underscores.3585Could not import my server: Invalid name my server. Names can only contain letters, numbers, hyphens, and underscores.

3528```3586```

3529 3587 

3530서버 이름 뒤의 텍스트가 사유입니다. 가장 흔한 사유는 이름 검사입니다. Claude Desktop은 서버 이름에 공백이나 마침표 같은 문자를 허용하지만 `claude mcp`는 문자, 숫자, 하이픈, 밑줄로 제한합니다. 그 밖의 사유로는 검증에 실패한 서버 구성과 조직의 [MCP 정책](https://code.claude.com/docs/ko/managed-mcp.md)에 의해 차단된 서버가 있습니다.3588서버 이름 뒤의 텍스트가 사유입니다. 가장 흔한 사유는 이름 검사입니다. Claude Desktop은 서버 이름에 공백이나 마침표 같은 문자를 허용하지만, `claude mcp`는 문자, 숫자, 하이픈, 밑줄로 제한합니다. 그 밖의 사유로는 검증에 실패한 서버 구성과 조직의 [MCP 정책](https://code.claude.com/docs/ko/managed-mcp.md)에 의해 차단된 서버가 있습니다.

3531 3589 

3532**해결 방법:**3590**해결 방법:**

3533 3591 

3534* `claude_desktop_config.json`에서 서버 이름을 문자, 숫자, 하이픈, 밑줄만 사용하도록 변경한 다음 `claude mcp add-from-claude-desktop`을 다시 실행합니다3592* `claude_desktop_config.json`에서 서버 이름을 문자, 숫자, 하이픈, 밑줄만 사용하도록 변경한 다음 `claude mcp add-from-claude-desktop`을 다시 실행합니다

3535* 유효한 이름으로 `claude mcp add` 또는 `claude mcp add-json`을 사용해 해당 서버를 직접 추가합니다. [Claude Desktop에서 MCP 서버 가져오기](https://code.claude.com/docs/ko/mcp.md#import-mcp-servers-from-claude-desktop)를 참조하세요.3593* 또는 유효한 이름으로 `claude mcp add` 또는 `claude mcp add-json`을 사용하여 해당 서버를 직접 추가합니다. [Claude Desktop에서 MCP 서버 가져오기](https://code.claude.com/docs/ko/mcp.md#import-mcp-servers-from-claude-desktop)를 참조하세요.

3536 3594 

3537### Cannot add MCP server to the managed scope3595### Cannot add MCP server to the managed scope

3538 3596 

3539`--scope managed`로 `claude mcp add` 또는 `claude mcp add-json`을 실행했습니다. 이 범위는 조직이 [`managedMcpServers`](https://code.claude.com/docs/ko/settings-reference#managedmcpservers) 관리형 설정을 통해 제공하는 서버를 담습니다. Claude Code는 이를 관리형 설정에서만 읽으므로 명령이 이 범위에 서버를 기록할 수 없습니다.3597`--scope managed`로 `claude mcp add` 또는 `claude mcp add-json`을 실행했습니다. 이 범위에는 조직이 [`managedMcpServers`](https://code.claude.com/docs/ko/settings-reference#managedmcpservers) 관리형 설정을 통해 제공하는 서버가 들어 있습니다. Claude Code는 이 서버를 관리형 설정에서만 읽으므로, 명령으로 이 범위에 서버를 기록할 수 없습니다.

3540 3598 

3541```text theme={null}3599```text theme={null}

3542Cannot add MCP server to scope: managed3600Cannot add MCP server to scope: managed

3544 3602 

3545**해결 방법:**3603**해결 방법:**

3546 3604 

3547* 기록할 수 있는 범위인 `local`, `user`, `project`에 서버를 추가합니다. `--scope`가 없으면 명령은 `local`을 사용합니다. [MCP 설치 범위](https://code.claude.com/docs/ko/mcp.md#mcp-installation-scopes)를 참조하세요3605* 기록할 수 있는 범위인 `local`, `user` 또는 `project`에 서버를 추가합니다. `--scope` 없이 실행하면 명령은 `local`을 사용합니다. [MCP 설치 범위](https://code.claude.com/docs/ko/mcp.md#mcp-installation-scopes)를 참조하세요

3548* 조직의 모든 사용자에게 서버를 제공하려면 배포하는 관리형 설정의 [`managedMcpServers`](https://code.claude.com/docs/ko/settings-reference#managedmcpservers)에 추가합니다3606* 조직의 모든 사용자에게 서버를 제공하려면 배포하는 관리형 설정의 [`managedMcpServers`](https://code.claude.com/docs/ko/settings-reference#managedmcpservers)에 추가합니다

3549 3607 

3550### 관리형 설정이 플러그인 서버만 허용하는 경우 MCP 서버를 추가할 수 없음3608### Cannot add MCP server when managed settings allow only plugin servers

3551 3609 

3552조직의 관리형 설정이 [`strictPluginOnlyCustomization`](https://code.claude.com/docs/ko/settings-reference#strictpluginonlycustomization)을 `true` 또는 `mcp`가 포함된 목록으로 설정한 상태에서 `claude mcp add` 또는 `claude mcp add-json`을 실행했습니다. 이 설정이 있으면 Claude Code는 `~/.claude.json`이나 `.mcp.json`에서 MCP 서버를 로드하지 않으므로, 명령은 절대 로드되지 않을 서버를 저장하는 대신 종료 코드 1로 종료됩니다.3610조직의 관리형 설정이 [`strictPluginOnlyCustomization`](https://code.claude.com/docs/ko/settings-reference#strictpluginonlycustomization)을 `true`로 설정하거나 `mcp`를 포함하는 목록으로 설정한 상태에서 `claude mcp add` 또는 `claude mcp add-json`을 실행했습니다. 이 설정이 적용되면 Claude Code는 `~/.claude.json`이나 `.mcp.json`에서 MCP 서버를 불러오지 않으므로, 명령은 절대 불러와지지 않을 서버를 저장하는 대신 종료 코드 1로 종료됩니다:

3553 3611 

3554```text theme={null}3612```text theme={null}

3555Cannot add MCP server: your organization's managed settings allow only MCP servers that plugins provide. Install a plugin that provides this server, or ask your administrator to make it available.3613Cannot add MCP server: your organization's managed settings allow only MCP servers that plugins provide. Install a plugin that provides this server, or ask your administrator to make it available.

3556```3614```

3557 3615 

3558`claude mcp add-from-claude-desktop`은 선택한 각 서버를 가져오지 못한 것으로 보고하며 이 메시지를 사유로 표시합니다. [`/import`](https://code.claude.com/docs/ko/commands#all-commands)는 추가하려는 각 MCP 서버에 대해 이 메시지를 보고하고, 찾은 다른 항목은 계속 가져옵니다.3616`claude mcp add-from-claude-desktop`은 선택한 각 서버를 가져오지 못한 것으로 보고하며, 이 메시지를 사유로 표시합니다. [`/import`](https://code.claude.com/docs/ko/commands#all-commands)는 추가하려는 각 MCP 서버에 대해 이 메시지를 보고하며, 찾은 다른 항목은 계속 가져옵니다.

3559 3617 

3560v2.1.284 이전에는 이 명령들이 서버를 저장하고 성공을 보고했지만, 서버는 절대 로드되지 않았습니다.3618v2.1.284 이전에는 이러한 명령이 서버를 저장하고 성공을 보고했지만, 서버는 절대 불러와지지 않았습니다.

3561 3619 

3562**해결 방법:**3620**해결 방법:**

3563 3621 

3564* 해당 서버를 제공하는 [플러그인](https://code.claude.com/docs/ko/plugins/install.md)을 설치합니다3622* 서버를 제공하는 [플러그인](https://code.claude.com/docs/ko/plugins/install.md)을 설치합니다

3565* 관리자에게 [플러그인](https://code.claude.com/docs/ko/plugins/org.md)으로 서버를 배포하거나, 원격 HTTP 또는 SSE 서버인 경우 [`managedMcpServers`](https://code.claude.com/docs/ko/settings-reference#managedmcpservers)를 통해 제공해 달라고 요청합니다3623* 관리자에게 서버를 [플러그인](https://code.claude.com/docs/ko/plugins/org.md)으로 배포하도록 요청하거나, 원격 HTTP 또는 SSE 서버인 경우 [`managedMcpServers`](https://code.claude.com/docs/ko/settings-reference#managedmcpservers)를 통해 제공하도록 요청합니다

3566 3624 

3567### Can't read .mcp.json3625### Can't read .mcp.json

3568 3626 

3569`--scope project`를 사용한 `claude mcp add` 또는 `claude mcp add-json`, 또는 `claude mcp remove`처럼 프로젝트의 [`.mcp.json`](https://code.claude.com/docs/ko/mcp#project-scope)을 읽는 명령이 현재 디렉터리의 파일이 일반 파일이 아니거나 2 MiB보다 큰 것을 발견했으므로, 파일을 읽는 대신 이 오류와 함께 종료됩니다.3627`--scope project`를 사용한 `claude mcp add` 또는 `claude mcp add-json`이나 `claude mcp remove`처럼 프로젝트의 [`.mcp.json`](https://code.claude.com/docs/ko/mcp#project-scope)을 읽는 명령이 현재 디렉터리의 파일이 일반 파일이 아니거나 2 MiB보다 크다는 것을 발견했으므로, 파일을 읽지 않고 이 오류와 함께 종료됩니다.

3570 3628 

3571```text theme={null}3629```text theme={null}

3572Can't read .mcp.json: it isn't a regular file or is larger than 2097152 bytes. Fix or remove it, then run the command again.3630Can't read .mcp.json: it isn't a regular file or is larger than 2097152 bytes. Fix or remove it, then run the command again.

3573```3631```

3574 3632 

3575v2.1.257 이전에는 `.mcp.json` 위치의 FIFO로 인해 명령이 출력 없이 무한정 대기했고, `/dev/zero` 같은 장치 파일에 대한 심볼릭 링크는 프로세스가 강제 종료될 때까지 메모리를 증가시켰습니다.3633v2.1.257 이전에는 `.mcp.json` 위치의 FIFO로 인해 명령이 출력 없이 영원히 대기했으며, `/dev/zero` 같은 장치 파일을 가리키는 심볼릭 링크로 인해 프로세스가 종료될 때까지 메모리가 증가했습니다.

3576 3634 

3577**해결 방법:**3635**해결 방법:**

3578 3636 

3579* 현재 디렉터리의 `.mcp.json` 위치에 무엇이 있는지 확인합니다. [프로젝트 범위 형식](https://code.claude.com/docs/ko/mcp.md#project-scope)의 일반 JSON 파일로 대체하거나 삭제한 다음 명령을 다시 실행합니다.3637* 현재 디렉터리의 `.mcp.json`에 무엇이 있는지 확인합니다. [프로젝트 범위 형식](https://code.claude.com/docs/ko/mcp.md#project-scope)의 일반 JSON 파일로 대체하거나 삭제한 다음 명령을 다시 실행합니다.

3580 3638 

3581### MCP server was not saved or removed3639### MCP server was not saved or removed

3582 3640 

3591**해결 방법:**3649**해결 방법:**

3592 3650 

3593* **다른 Claude Code 프로세스가 실행 중인 경우**: 명령은 파일 잠금을 약 10\~20초 동안 기다린 후 기록하지 않고 포기합니다. [`CLAUDE_CODE_CONFIG_LOCK_WAIT_MS`](https://code.claude.com/docs/ko/env-vars#variables)를 `60000`처럼 더 긴 대기 시간(밀리초)으로 설정하여 같은 명령을 다시 실행합니다.3651* **다른 Claude Code 프로세스가 실행 중인 경우**: 명령은 파일 잠금을 약 10\~20초 동안 기다린 후 기록하지 않고 포기합니다. [`CLAUDE_CODE_CONFIG_LOCK_WAIT_MS`](https://code.claude.com/docs/ko/env-vars#variables)를 `60000`처럼 더 긴 대기 시간(밀리초)으로 설정하여 같은 명령을 다시 실행합니다.

3594* **파일이 읽기 전용이거나 샌드박스로 보호되는 경우**: 메시지에 명시된 파일을 쓰기 가능하게 만들고 같은 add 또는 remove 명령을 다시 실행하거나, 샌드박스 밖에서 해당 명령을 실행합니다.3652* **파일이 읽기 전용이거나 샌드박스로 보호된 경우**: 메시지에 표시된 파일을 쓰기 가능하게 만들고 같은 추가 또는 제거 명령을 다시 실행하거나, 해당 명령을 샌드박스 밖에서 실행합니다.

3595 3653 

3596v2.1.283 이전에는 변경 사항이 파일에 반영되지 않았을 때도 `claude mcp add`, `claude mcp add-json`, `claude mcp remove`가 성공을 보고했습니다. v2.1.318 이전에는 메시지에 잠금이 언급되지 않았고, Claude Code가 [`CLAUDE_CODE_CONFIG_LOCK_WAIT_MS`](https://code.claude.com/docs/ko/env-vars#variables)를 읽지 않았습니다.3654v2.1.283 이전에는 변경 사항이 파일에 반영되지 않은 경우에도 `claude mcp add`, `claude mcp add-json`, `claude mcp remove`가 성공을 보고했습니다. v2.1.318 이전에는 메시지에 잠금이 언급되지 않았으며, Claude Code가 [`CLAUDE_CODE_CONFIG_LOCK_WAIT_MS`](https://code.claude.com/docs/ko/env-vars#variables)를 읽지 않았습니다.

3597 3655 

3598### MCP server may not have been saved or removed3656### MCP server may not have been saved or removed

3599 3657 

3600`user` 또는 `local` [범위](https://code.claude.com/docs/ko/mcp.md#mcp-installation-scopes)의 서버에 대해 `claude mcp add`, `claude mcp add-json`, `claude mcp remove`를 실행했는데, Claude Code가 변경 사항을 확인하기 위해 `~/.claude.json`을 다시 읽지 못한 경우입니다. 변경 사항이 디스크에 반영되었을 수도 있고 아닐 수도 있습니다. `to confirm the change` 뒤의 괄호 안에 사유가 표시됩니다.3658`user` 또는 `local` [범위](https://code.claude.com/docs/ko/mcp.md#mcp-installation-scopes)의 서버에 대해 `claude mcp add`, `claude mcp add-json` 또는 `claude mcp remove`를 실행했는데, Claude Code가 변경 사항을 확인하기 위해 `~/.claude.json`을 다시 읽을 수 없었습니다. 변경 사항이 디스크에 반영되었을 수도 있고 그렇지 않을 수도 있습니다. `to confirm the change` 뒤의 괄호 안에 사유가 표시됩니다.

3601 3659 

3602```text theme={null}3660```text theme={null}

3603MCP server "example" may not have been saved: /home/user/.claude.json could not be read to confirm the change (EACCES: permission denied, open '/home/user/.claude.json'). Run `claude mcp get example` to check, then add the server again if it is missing.3661MCP server "example" may not have been saved: /home/user/.claude.json could not be read to confirm the change (EACCES: permission denied, open '/home/user/.claude.json'). Run `claude mcp get example` to check, then add the server again if it is missing.

3605 3663 

3606제거 후에는 메시지에 `may not have been removed`가 표시되고 `then remove the server again if it is still listed`로 끝납니다. 사유가 `the file was not found`인 경우 서버가 여전히 구성되어 있을 수 있습니다.3664제거 후에는 메시지에 `may not have been removed`가 표시되고 `then remove the server again if it is still listed`로 끝납니다. 사유가 `the file was not found`인 경우 서버가 여전히 구성되어 있을 수 있습니다.

3607 3665 

3608v2.1.283 이전에는 변경 사항을 확인할 수 없어도 명령이 성공을 보고했습니다.3666v2.1.283 이전에는 변경 사항을 확인할 수 없는 경우에도 명령이 성공을 보고했습니다.

3609 3667 

3610**해결 방법:**3668**해결 방법:**

3611 3669 

3612* `claude mcp get <name>`을 실행해 변경 사항이 디스크에 반영되었는지 확인합니다. `local` 범위 서버의 경우 로컬 범위는 프로젝트별이므로 서버가 속한 프로젝트 디렉터리에서 실행합니다.3670* `claude mcp get <name>`을 실행하여 변경 사항이 디스크에 반영되었는지 확인합니다. `local` 범위 서버의 경우 로컬 범위는 프로젝트별이므로 서버가 속한 프로젝트 디렉터리에서 실행합니다.

3613* 추가 후 서버가 없거나 제거 후에도 여전히 목록에 있으면 같은 추가 또는 제거 명령을 다시 실행합니다.3671* 추가 후에 서버가 없거나 제거 후에도 여전히 나열되어 있으면 같은 추가 또는 제거 명령을 다시 실행합니다.

3614 3672 

3615### Server is Anthropic-hosted and doesn't support local OAuth3673### Server is Anthropic-hosted and doesn't support local OAuth

3616 3674 

3617타사 ID 공급자를 통해 인증하는 Anthropic 호스팅 커넥터 호스트를 URL로 가리키는 MCP 서버에 대해 로그인을 시작했습니다. 이러한 호스트에는 `microsoft365.mcp.claude.com`, `gmail.mcp.claude.com`, `gcal.mcp.claude.com`이 포함됩니다. [이 호스트의 로그인은 claude.ai를 통해서만 작동하므로](https://code.claude.com/docs/ko/mcp.md#use-mcp-servers-from-claude-ai) Claude Code는 `/mcp` 패널과 `claude mcp login` 모두에서 이러한 호스트에 대한 로컬 OAuth 흐름 시작을 거부합니다.3675URL이 서드 파티 ID 공급자를 통해 인증하는 Anthropic 호스팅 커넥터 호스트를 가리키는 MCP 서버에 대해 로그인을 시작했습니다. 이러한 호스트에는 `microsoft365.mcp.claude.com`, `gmail.mcp.claude.com`, `gcal.mcp.claude.com`이 포함됩니다. [이러한 호스트의 로그인은 claude.ai를 통해서만 동작](https://code.claude.com/docs/ko/mcp.md#use-mcp-servers-from-claude-ai)하므로, Claude Code는 `/mcp` 패널과 `claude mcp login` 모두에서 이러한 호스트에 대한 로컬 OAuth 흐름 시작을 거부합니다.

3618 3676 

3619```text theme={null}3677```text theme={null}

3620"gmail" is Anthropic-hosted and doesn't support local OAuth. Connect it via Settings → Connectors on claude.ai (requires `claude login`), then it'll be available here automatically.3678"gmail" is Anthropic-hosted and doesn't support local OAuth. Connect it via Settings → Connectors on claude.ai (requires `claude login`), then it'll be available here automatically.

3622 3680 

3623**해결 방법:**3681**해결 방법:**

3624 3682 

3625* 같은 URL의 claude.ai 커넥터를 가리지 않도록 `claude mcp remove <name>`으로 해당 항목을 제거합니다3683* 같은 URL의 claude.ai 커넥터를 가리지 않도록 `claude mcp remove <name>`으로 항목을 제거합니다

3626* 제거한 후 Claude Code에서 사용하는 계정으로 로그인한 상태에서 [claude.ai/customize/connectors](https://claude.ai/customize/connectors)에서 서비스를 연결합니다. 연결되면 활성 인증 방법이 claude.ai 구독 로그인인 경우 [커넥터가 Claude Code에 자동으로 나타납니다](https://code.claude.com/docs/ko/mcp.md#use-mcp-servers-from-claude-ai)3684* 제거한 후 Claude Code에서 사용하는 계정으로 로그인한 상태에서 [claude.ai/customize/connectors](https://claude.ai/customize/connectors)에서 서비스를 연결합니다. 연결되면 활성 인증 방식이 claude.ai 구독 로그인인 경우 [커넥터가 Claude Code에 자동으로 표시](https://code.claude.com/docs/ko/mcp.md#use-mcp-servers-from-claude-ai)됩니다

3627 3685 

3628### Server rejected the Authorization header minted by the configured headersHelper3686### Server rejected the Authorization header minted by the configured headersHelper

3629 3687 

3630[`headersHelper`](https://code.claude.com/docs/ko/mcp#use-dynamic-headers-for-custom-authentication)가 `Authorization` 헤더를 제공하는 MCP 서버가 연결에 HTTP 401 또는 403으로 응답했으므로 Claude Code는 연결 실패를 보고합니다. 헬퍼가 `Authorization` 헤더를 제공하므로 Claude Code는 해당 서버에 대해 [OAuth로 폴백하지 않습니다](https://code.claude.com/docs/ko/mcp.md#authenticate-with-remote-mcp-servers).3688[`headersHelper`](https://code.claude.com/docs/ko/mcp#use-dynamic-headers-for-custom-authentication)가 `Authorization` 헤더를 제공하는 MCP 서버가 연결에 HTTP 401 또는 403으로 응답했으므로, Claude Code는 연결이 실패한 것으로 보고합니다. 헬퍼가 `Authorization` 헤더를 제공하므로 Claude Code는 해당 서버에 대해 [OAuth로 폴백하지 않습니다](https://code.claude.com/docs/ko/mcp.md#authenticate-with-remote-mcp-servers):

3631 3689 

3632```text theme={null}3690```text theme={null}

3633Server rejected the Authorization header minted by the configured headersHelper (HTTP 401). Check that the helper command returns a valid credential for this MCP endpoint — OAuth fallback is disabled when the helper supplies Authorization.3691Server rejected the Authorization header minted by the configured headersHelper (HTTP 401). Check that the helper command returns a valid credential for this MCP endpoint — OAuth fallback is disabled when the helper supplies Authorization.

3634```3692```

3635 3693 

3636Claude Code는 연결을 시도할 때마다 헬퍼를 다시 실행하므로, 토큰 교체 경합 같은 일시적인 거부 후 재시도하면 새 자격 증명으로 성공할 수 있습니다.3694Claude Code는 연결을 시도할 때마다 헬퍼를 다시 실행하므로, 토큰 교체 경합 같은 일시적인 거부 후에는 재시도 시 새 자격 증명으로 성공할 수 있습니다.

3637 3695 

3638**해결 방법:**3696**해결 방법:**

3639 3697 

3640* Claude Code가 실행하는 방식 그대로 `headersHelper` 명령을 직접 실행합니다. 즉, [Claude Code가 실행하는 디렉터리](https://code.claude.com/docs/ko/mcp.md#where-the-helper-runs)에서 [Claude Code가 설정하는 환경 변수](https://code.claude.com/docs/ko/mcp.md#use-dynamic-headers-for-custom-authentication)와 함께 실행하고, 프로젝트 `.mcp.json`, 플러그인 또는 프로젝트 에이전트 파일에서 온 서버라면 [Claude Code가 제거하는 자격 증명 변수](https://code.claude.com/docs/ko/mcp.md#which-variables-a-helper-can-read) 없이 실행합니다. 서버의 엔드포인트가 받아들이는 `Authorization` 값을 출력하는지 확인합니다3698* Claude Code가 실행하는 방식 그대로 `headersHelper` 명령을 직접 실행합니다. 즉, [Claude Code가 헬퍼를 실행하는 디렉터리](https://code.claude.com/docs/ko/mcp.md#where-the-helper-runs)에서, [Claude Code가 설정하는 환경 변수](https://code.claude.com/docs/ko/mcp.md#use-dynamic-headers-for-custom-authentication)와 함께, 그리고 프로젝트 `.mcp.json`, 플러그인 또는 프로젝트 에이전트 파일의 서버라면 [Claude Code가 제거하는 자격 증명 변수](https://code.claude.com/docs/ko/mcp.md#which-variables-a-helper-can-read) 없이 실행합니다. 서버의 엔드포인트가 받아들이는 `Authorization` 값을 출력하는지 확인합니다

3641* 헬퍼나 자격 증명 소스를 수정한 후 `/mcp`에서 서버를 선택하고 **Reconnect**를 선택합니다3699* 헬퍼나 자격 증명 소스를 수정한 후 `/mcp`에서 서버를 선택하고 **Reconnect**를 선택합니다

3642 3700 

3643v2.1.248 이전에는 헬퍼가 `Authorization` 헤더를 제공하는 서버에 대해서도 Claude Code가 OAuth 검색을 실행했습니다. 이 검색은 거부된 자격 증명을 보고하는 대신 `Incompatible auth server: does not support dynamic client registration`으로 실패할 수 있었습니다.3701v2.1.248 이전에는 헬퍼가 `Authorization` 헤더를 제공하는 서버에 대해 Claude Code가 OAuth 검색을 실행했습니다. 그 검색은 거부된 자격 증명을 보고하는 대신 `Incompatible auth server: does not support dynamic client registration`으로 실패할 수 있었습니다.

3644 3702 

3645### MCP server rejected the elicitation capability3703### MCP server rejected the elicitation capability

3646 3704 

3647Java MCP SDK 0.11.0부터 0.17.0까지로 빌드된 MCP 서버가 연결을 거부했습니다. 해당 SDK 버전은 Claude Code가 핸드셰이크에서 선언하는 `form` 및 `url` [elicitation 모드](https://code.claude.com/docs/ko/mcp.md#elicitation-modes-claude-code-declares)를 구문 분석하지 못합니다. 메시지는 다음과 같습니다.3705Java MCP SDK 0.11.0\~0.17.0으로 빌드된 MCP 서버가 연결을 거부했습니다. 이러한 SDK 버전은 Claude Code가 핸드셰이크에서 선언하는 `form` 및 `url` [elicitation 모드](https://code.claude.com/docs/ko/mcp.md#elicitation-modes-claude-code-declares)를 파싱할 수 없습니다. 메시지는 다음과 같습니다:

3648 3706 

3649```text theme={null}3707```text theme={null}

3650This server (Java MCP SDK 0.17.0 or older) rejected Claude Code's elicitation capability. Set "bareElicitationCapability": true for it, or upgrade to Java MCP SDK 0.17.1+ (Spring AI 1.0.7+ or 1.1.6+).3708This server (Java MCP SDK 0.17.0 or older) rejected Claude Code's elicitation capability. Set "bareElicitationCapability": true for it, or upgrade to Java MCP SDK 0.17.1+ (Spring AI 1.0.7+ or 1.1.6+).

3655* 서버를 Java MCP SDK 0.17.1 이상 또는 메시지에 표시된 Spring AI 릴리스 중 하나로 업그레이드합니다3713* 서버를 Java MCP SDK 0.17.1 이상 또는 메시지에 표시된 Spring AI 릴리스 중 하나로 업그레이드합니다

3656* 또는 MCP 구성에서 해당 서버 항목에 `"bareElicitationCapability": true`를 추가한 다음 Claude Code를 다시 시작합니다. 이 필드는 stdio, `sse`, `http`, `ws` 항목에서 사용할 수 있으며 Claude Code v2.1.281 이상이 필요합니다3714* 또는 MCP 구성에서 해당 서버 항목에 `"bareElicitationCapability": true`를 추가한 다음 Claude Code를 다시 시작합니다. 이 필드는 stdio, `sse`, `http`, `ws` 항목에서 사용할 수 있으며 Claude Code v2.1.281 이상이 필요합니다

3657 3715 

3658다음 `.mcp.json` 항목은 하나의 HTTP 서버에 이 필드를 설정합니다.3716다음 `.mcp.json` 항목은 하나의 HTTP 서버에 대해 이 필드를 설정합니다:

3659 3717 

3660```json theme={null}3718```json theme={null}

3661{3719{

3669}3727}

3670```3728```

3671 3729 

3672다시 시작한 후 `/mcp`에 서버가 연결됨으로 표시됩니다. Claude Code는 해당 서버에만 form 모드를 선언하므로, 서버를 업그레이드하면 이 필드를 제거합니다.3730다시 시작한 후 `/mcp`에 서버가 연결된 것으로 표시됩니다. Claude Code는 해당 서버에만 form 모드를 선언하므로, 서버를 업그레이드한 후에는 이 필드를 제거합니다.

3673 3731 

3674서버가 `Unrecognized field "form"`이 포함된 오류처럼 자체 오류 텍스트로 실패할 수도 있습니다. 같은 해결 방법이 적용됩니다.3732서버가 `Unrecognized field "form"`을 포함하는 메시지처럼 자체 오류 텍스트와 함께 실패할 수도 있습니다. 같은 해결 방법이 적용됩니다.

3675 3733 

3676### MCP permission prompt tool not found3734### MCP permission prompt tool not found

3677 3735 

3678[`--permission-prompt-tool`](https://code.claude.com/docs/ko/cli-reference#cli-flags)에 전달한 도구가 실행에서 처음 권한 결정이 필요했을 때 연결된 MCP 도구 중에 없었습니다. 서버가 연결되지 않았거나, 연결된 서버 중 해당 이름의 도구를 노출하는 서버가 없기 때문입니다. Claude Code는 여전히 프롬프트를 전송합니다. [비대화형](https://code.claude.com/docs/ko/headless.md) 실행은 첫 번째 도구 호출에서 이 오류와 종료 코드 1로 종료되므로, 요청은 이루어졌지만 응답은 생성되지 않습니다. 첫 번째 프롬프트 전에 Claude Code는 [`MCP_TIMEOUT`](https://code.claude.com/docs/ko/env-vars)으로 설정된 서버별 연결 타임아웃인 최대 30초 동안 해당 서버가 연결되기를 기다립니다. v2.1.206 이전에는 시작 시 서버 연결 완료를 기다리지 않았으므로, 시작이 느리지만 정상적인 서버에서도 이 오류가 발생했습니다.3736[`--permission-prompt-tool`](https://code.claude.com/docs/ko/cli-reference#cli-flags)에 전달한 도구가 실행에서 처음 권한 결정이 필요한 시점에 연결된 MCP 도구 중에 없었습니다. 서버가 연결되지 않았거나, 연결된 서버 중 해당 이름의 도구를 노출하는 서버가 없기 때문입니다. Claude Code는 여전히 프롬프트를 전송합니다. [비대화형](https://code.claude.com/docs/ko/headless.md) 실행은 첫 번째 도구 호출에서 이 오류와 종료 코드 1로 종료되므로, 요청이 이루어졌지만 답변은 생성되지 않습니다. 첫 번째 프롬프트 전에 Claude Code는 [`MCP_TIMEOUT`](https://code.claude.com/docs/ko/env-vars)으로 설정되는 서버별 연결 타임아웃인 30초까지 해당 서버의 연결을 기다립니다. v2.1.206 이전에는 시작 시 서버 연결이 완료되기를 기다리지 않았으므로, 시작이 느리지만 정상인 서버에서도 이 오류가 발생했습니다.

3679 3737 

3680```text theme={null}3738```text theme={null}

3681Error: MCP tool mcp__permissions__approve (passed via --permission-prompt-tool) not found. Available MCP tools: none3739Error: MCP tool mcp__permissions__approve (passed via --permission-prompt-tool) not found. Available MCP tools: none

3682```3740```

3683 3741 

3684`Available MCP tools:` 뒤의 목록은 연결되어 있던 MCP 도구를 나타냅니다.3742`Available MCP tools:` 뒤의 목록에는 연결된 MCP 도구가 표시됩니다.

3685 3743 

3686**해결 방법:**3744**해결 방법:**

3687 3745 

3688* 서버가 시작되고 연결이 유지되는지 확인합니다. 같은 디렉터리에서 `claude mcp list`를 실행하고 서버가 연결됨으로 표시되는지 확인합니다3746* 서버가 시작되고 연결 상태를 유지하는지 확인합니다. 같은 디렉터리에서 `claude mcp list`를 실행하여 서버가 연결된 것으로 나열되는지 확인합니다

3689* 도구 이름이 서버가 노출하는 `mcp__<server>__<tool>` 이름과 일치하는지 확인합니다3747* 도구 이름이 서버가 노출하는 `mcp__<server>__<tool>` 이름과 일치하는지 확인합니다

3690* 서버 시작에 30초보다 오래 걸리면 [`MCP_TIMEOUT`](https://code.claude.com/docs/ko/env-vars)을 늘립니다3748* 서버가 시작하는 데 30초보다 오래 걸리면 [`MCP_TIMEOUT`](https://code.claude.com/docs/ko/env-vars)을 늘립니다

3691 3749 

3692### OAuth callback port is already in use3750### OAuth callback port is already in use

3693 3751 

3694OAuth로 원격 MCP 서버에 로그인하면 Claude Code는 로그인 콜백을 받기 위해 로컬 리스너를 시작합니다. 리스너에 필요한 포트를 다른 프로세스가 점유하고 있으면 로그인이 이 메시지와 함께 실패합니다. Claude Code는 고정 포트가 없으면 사용 가능한 포트를 선택하므로, 이 문제는 주로 [`MCP_OAUTH_CALLBACK_PORT`](https://code.claude.com/docs/ko/env-vars) 변수나 `--callback-port`로 설정한 [고정 콜백 포트](https://code.claude.com/docs/ko/mcp.md#use-a-fixed-oauth-callback-port)에서 발생합니다.3752OAuth로 원격 MCP 서버에 로그인하면 Claude Code는 로그인 콜백을 받기 위해 로컬 리스너를 시작합니다. 리스너에 필요한 포트를 다른 프로세스가 점유하고 있으면 로그인이 이 메시지와 함께 실패합니다. 이는 주로 [`MCP_OAUTH_CALLBACK_PORT`](https://code.claude.com/docs/ko/env-vars) 변수나 `--callback-port`로 [고정 콜백 포트](https://code.claude.com/docs/ko/mcp.md#use-a-fixed-oauth-callback-port)를 설정한 경우에 발생합니다. 고정 포트가 없으면 Claude Code가 사용 가능한 포트를 선택하기 때문입니다.

3695 3753 

3696```text theme={null}3754```text theme={null}

3697OAuth callback port <port> is already in use — another process may be holding it. Run `lsof -ti:<port> -sTCP:LISTEN` to find it.3755OAuth callback port <port> is already in use — another process may be holding it. Run `lsof -ti:<port> -sTCP:LISTEN` to find it.

3701 3759 

3702**해결 방법:**3760**해결 방법:**

3703 3761 

3704* 메시지의 명령을 실행해 포트를 점유한 프로세스를 찾고, 이를 중지하거나 완료될 때까지 기다립니다3762* 메시지의 명령을 실행하여 포트를 점유한 프로세스를 찾고, 해당 프로세스를 중지하거나 종료될 때까지 기다립니다

3705* 다른 프로그램이 해당 포트를 계속 사용해야 한다면 서버에 다른 리디렉션 URI를 등록하고, 사용 중인 방식에 따라 `MCP_OAUTH_CALLBACK_PORT` 또는 `--callback-port`로 해당 포트를 설정합니다3763* 다른 프로그램이 해당 포트를 계속 필요로 하는 경우, 서버에 다른 리디렉션 URI를 등록하고 사용 중인 `MCP_OAUTH_CALLBACK_PORT` 또는 `--callback-port`로 해당 포트를 설정합니다

3706* 그런 다음 `/mcp`에서 서버를 선택하는 등의 방법으로 로그인을 다시 시작합니다3764* 그런 다음 `/mcp`에서 서버를 선택하는 등의 방법으로 로그인을 다시 시작합니다

3707 3765 

3708### No available ports for OAuth redirect3766### No available ports for OAuth redirect

3709 3767 

3710[OAuth](https://code.claude.com/docs/ko/mcp.md#authenticate-with-remote-mcp-servers)로 원격 MCP 서버에 로그인하면 Claude Code는 로그인 콜백을 받기 위해 로컬 리스너를 시작합니다. Claude Code가 이를 위한 로컬 포트를 바인딩할 수 없으면 로그인이 이 메시지와 함께 실패합니다. 보안 소프트웨어나 로컬 리스너를 거부하는 샌드박스 정책 등 컴퓨터의 무언가가 `127.0.0.1`에서의 수신을 막고 있습니다.3768[OAuth](https://code.claude.com/docs/ko/mcp.md#authenticate-with-remote-mcp-servers)로 원격 MCP 서버에 로그인하면 Claude Code는 로그인 콜백을 받기 위해 로컬 리스너를 시작합니다. Claude Code가 이를 위한 로컬 포트를 바인딩할 수 없으면 로그인이 이 메시지와 함께 실패합니다. 컴퓨터의 무언가가 `127.0.0.1`에서의 수신 대기를 막고 있는 것으로, 예를 들어 로컬 리스너를 거부하는 보안 소프트웨어나 샌드박스 정책이 있습니다.

3711 3769 

3712```text theme={null}3770```text theme={null}

3713No available ports for OAuth redirect3771No available ports for OAuth redirect

3714```3772```

3715 3773 

3716v2.1.268 이전에는 Claude Code가 운영 체제가 할당한 포트로 폴백하지 않았으므로, 자체적으로 선택한 포트만 바인딩할 수 없는 경우에도 이 메시지가 나타났습니다. 이는 Hyper-V가 Claude Code가 선택하는 포트를 포함하는 포트 범위를 예약하는 Windows 호스트에서 발생할 수 있습니다.3774v2.1.268 이전에는 Claude Code가 운영 체제가 할당하는 포트로 폴백하지 않았으므로, 자체적으로 선택한 포트만 바인딩할 수 없는 경우에도 이 메시지가 표시되었습니다. 이는 Hyper-V가 Claude Code가 선택하는 포트 범위를 포함하는 포트 범위를 예약하는 Windows 호스트에서 발생할 수 있습니다.

3717 3775 

3718**해결 방법:**3776**해결 방법:**

3719 3777 

3720* 보안 소프트웨어나 샌드박스 정책이 프로세스의 `127.0.0.1` 수신을 차단하는지 확인하고, Claude Code가 로컬 포트를 바인딩할 수 있도록 허용합니다3778* 보안 소프트웨어나 샌드박스 정책이 프로세스의 `127.0.0.1` 수신 대기를 차단하는지 확인하고, Claude Code가 로컬 포트를 바인딩하도록 허용합니다

3721* 그런 다음 `/mcp`에서 서버를 선택하는 등의 방법으로 로그인을 다시 시작합니다3779* 그런 다음 `/mcp`에서 서버를 선택하는 등의 방법으로 로그인을 다시 시작합니다

3722 3780 

3723### origin/HEAD가 없으면 /security-review가 실패함3781### origin/HEAD가 없어 /security-review 실패

3724 3782 

3725[`/security-review`](https://code.claude.com/docs/ko/commands#all-commands)는 `origin` 원격의 기본 브랜치가 무엇인지 기록하는 로컬 참조인 `origin/HEAD`와 현재 브랜치를 비교한 diff로 리뷰 컨텍스트를 구성합니다. 이 참조가 없으면 diff를 수집하는 git 명령이 실패하고, 리뷰는 시작되기 전에 중단됩니다.3783[`/security-review`](https://code.claude.com/docs/ko/commands#all-commands)는 `origin` 원격의 기본 브랜치를 기록하는 로컬 ref인 `origin/HEAD`와 현재 브랜치의 diff를 구하여 리뷰 컨텍스트를 구성합니다. 해당 ref가 없으면 diff를 수집하는 git 명령이 실패하고 리뷰가 시작되기 전에 중단됩니다.

3726 3784 

3727```text theme={null}3785```text theme={null}

3728Error: Shell command failed for pattern "!`git diff --name-only origin/HEAD...`": [stderr]3786Error: Shell command failed for pattern "!`git diff --name-only origin/HEAD...`": [stderr]

3731'git <command> [<revision>...] -- [<file>...]'3789'git <command> [<revision>...] -- [<file>...]'

3732```3790```

3733 3791 

3734메시지에 `git log`나 다른 `git diff`가 대신 인용될 수도 있습니다. Git은 원격이 기본 브랜치를 알리고 fetch refspec이 이를 포함할 때만 `origin/HEAD`를 만들며, 커밋이 있는 원격을 전체 `git clone`하면 이 조건이 충족됩니다. 다음 구성에서는 ref가 없습니다.3792메시지에는 대신 `git log`나 다른 `git diff`가 인용될 수도 있습니다. Git은 원격이 기본 브랜치를 알리고 fetch refspec이 이를 포함하는 경우에만 `origin/HEAD`를 생성하며, 커밋이 있는 원격을 전체 `git clone`하면 이 조건이 충족됩니다. 다음과 같은 설정에서는 ref가 없습니다:

3735 3793 

3736* 너무 좁은 refspec을 fetch하는 단일 브랜치 또는 CI 체크아웃3794* 너무 좁은 refspec을 가져오는 단일 브랜치 또는 CI 체크아웃

3737* 서버 측 HEAD가 아무도 푸시하지 않은 브랜치를 가리키는 원격3795* 서버 측 HEAD가 아무도 푸시하지 않은 브랜치를 가리키는 원격

3738* `origin` 원격이 없거나 한 번도 fetch하지 않은 저장소3796* `origin` 원격이 없거나 한 번도 fetch하지 않은 저장소

3739 3797 

3740Claude Code는 [동적 컨텍스트를 주입하는](https://code.claude.com/docs/ko/skills.md#when-an-injected-command-fails) 모든 스킬에 대해 같은 오류를 표시하며, 주입된 명령이 실패하면 해당 스킬의 호출이 중단됩니다.3798Claude Code는 [동적 컨텍스트를 주입](https://code.claude.com/docs/ko/skills.md#when-an-injected-command-fails)하는 모든 스킬에 대해 같은 오류를 표시하며, 주입된 명령이 실패하면 해당 스킬의 호출이 중단됩니다.

3741 3799 

3742명령이 실행되기 전에 발생하는 관련 메시지도 있습니다.3800다음 관련 메시지는 명령이 실행되기도 전에 표시됩니다:

3743 3801 

3744* `Shell command permission check failed for pattern "..."`: 명령의 권한 검사가 이를 허용하지 않았습니다. [주입된 명령의 권한 검사](https://code.claude.com/docs/ko/skills.md#permission-checks-on-injected-commands)에서 각 권한 모드에서 어떤 결과가 중단으로 이어지는지, 그리고 `allowed-tools`로 명령을 사전 승인하는 방법을 다룹니다3802* `Shell command permission check failed for pattern "..."`: 명령의 권한 검사가 이를 허용하지 않았습니다. [주입된 명령의 권한 검사](https://code.claude.com/docs/ko/skills.md#permission-checks-on-injected-commands)에서 각 권한 모드에서 어떤 결과가 중단되는지와 `allowed-tools`로 명령을 사전 승인하는 방법을 다룹니다

3745* ``Skill <name> requires bash (`shell: bash` in frontmatter) but Git Bash was not found``: 스킬의 frontmatter가 bash가 없는 컴퓨터에서 bash를 요구합니다. Git for Windows를 설치하거나 frontmatter를 `shell: powershell`로 변경합니다. [주입된 명령이 실행되는 방식](https://code.claude.com/docs/ko/skills.md#how-injected-commands-run)을 참조하세요3803* ``Skill <name> requires bash (`shell: bash` in frontmatter) but Git Bash was not found``: 스킬의 frontmatter가 bash가 없는 컴퓨터에서 bash를 요구합니다. Git for Windows를 설치하거나 frontmatter를 `shell: powershell`로 변경합니다. [주입된 명령이 실행되는 방식](https://code.claude.com/docs/ko/skills.md#how-injected-commands-run)을 참조하세요

3746 3804 

3747**해결 방법:**3805**해결 방법:**

3748 3806 

3749* 원격의 기본 브랜치를 지정해 ref를 만듭니다: `git remote set-head origin <default-branch>`. 이 방법은 로컬 추적 ref `origin/<default-branch>`가 있으면 항상 작동합니다. 단일 브랜치 클론처럼 해당 ref가 없으면 먼저 브랜치를 fetch합니다. `git remote set-branches --add origin <branch>`를 실행한 다음 `git fetch origin`을 실행하고, set-head 명령을 다시 실행합니다. 그런 다음 `/security-review`를 다시 실행합니다.3807* 원격의 기본 브랜치를 지정하여 ref를 생성합니다: `git remote set-head origin <default-branch>`. 이 방법은 로컬 추적 ref `origin/<default-branch>`가 있으면 항상 동작합니다. 단일 브랜치 클론처럼 해당 ref가 없으면 먼저 브랜치를 fetch합니다. `git remote set-branches --add origin <branch>`를 실행하고, 이어서 `git fetch origin`을 실행한 다음, set-head 명령을 다시 실행합니다. 그리고 `/security-review`를 다시 실행합니다.

3750* 브랜치 이름을 지정하고 싶지 않다면 `git fetch origin`을 실행한 다음 `git remote set-head origin --auto`를 실행합니다. 이 명령은 원격에 기본 브랜치를 묻습니다. 원격이 비어 있거나 HEAD가 아무도 푸시하지 않은 브랜치를 가리켜 기본 브랜치를 알리지 않으면 `error: Cannot determine remote HEAD`로 실패하므로, 이 경우 브랜치를 명시적으로 지정합니다. 클론이 해당 브랜치를 fetch하지 않으면 `error: Not a valid ref`로 실패하므로, 먼저 위와 같이 refspec을 넓힙니다.3808* 브랜치를 지정하지 않으려면 `git fetch origin`을 실행한 다음 `git remote set-head origin --auto`를 실행합니다. 이 명령은 원격에 기본 브랜치를 묻습니다. 원격이 비어 있거나 HEAD가 아무도 푸시하지 않은 브랜치를 가리켜 기본 브랜치를 알리지 않으면 `error: Cannot determine remote HEAD`로 실패하며, 이 경우 대신 브랜치를 명시적으로 지정합니다. 클론이 해당 브랜치를 fetch하지 않으면 `error: Not a valid ref`로 실패하며, 이 경우 먼저 위와 같이 refspec을 넓힙니다.

3751* 저장소에 원격이 없으면 `git remote add origin <url>`로 원격을 추가하고 ref를 만들기 전에 fetch합니다. 원격이 비어 있으면 먼저 `git push -u origin HEAD`로 브랜치를 푸시하고 set-head 명령에 해당 브랜치를 지정합니다. 그러면 `origin/HEAD`가 방금 푸시한 브랜치를 가리키므로, 브랜치가 여기서 갈라질 때까지 `/security-review`에는 빈 diff가 표시됩니다.3809* 저장소에 원격이 없으면 `git remote add origin <url>`로 원격을 추가하고 ref를 생성하기 전에 fetch합니다. 원격이 비어 있으면 먼저 `git push -u origin HEAD`로 브랜치를 푸시하고 set-head 명령에 해당 브랜치를 지정합니다. 그러면 `origin/HEAD`가 방금 푸시한 브랜치를 가리키므로, 브랜치가 분기되기 전까지 `/security-review`에는 빈 diff가 표시됩니다.

3752 3810 

3753### No shell command in a skill or command was run3811### No shell command in a skill or command was run

3754 3812 

3755`No shell command in <name> was run`은 해당 스킬 또는 명령 파일의 `` !`<command>` `` [동적 컨텍스트 명령](https://code.claude.com/docs/ko/skills.md#inject-dynamic-context)에 Bash 또는 PowerShell 도구가 거부하는 문자가 포함되어 있다는 의미입니다.3813`No shell command in <name> was run`은 해당 스킬 또는 명령 파일의 `` !`<command>` `` [동적 컨텍스트 명령](https://code.claude.com/docs/ko/skills.md#inject-dynamic-context)에 Bash 또는 PowerShell 도구가 거부하는 문자가 포함되어 있다는 의미입니다:

3756 3814 

3757* **두 도구 모두**: 탭이나 줄 바꿈이 아닌 원시 제어 문자3815* **두 도구 모두**: 탭이나 줄바꿈이 아닌 원시 제어 문자

3758* **PowerShell 도구**: 추가로 U+FEFF 또는 U+180E3816* **PowerShell 도구**: 추가로 U+FEFF 또는 U+180E

3759 3817 

3760메시지는 거부된 명령으로 끝나며, 거부된 각 문자는 다음 Bash 도구 예시처럼 `�`로 표시됩니다.3818메시지는 거부된 명령으로 끝나며, 다음 Bash 도구 예시처럼 거부된 각 문자를 `�`로 표시합니다:

3761 3819 

3762```text theme={null}3820```text theme={null}

3763No shell command in /my-skill was run, because the Bash tool does not accept one of them: command contains control characters that would be hidden in the approval dialog. Unprintable characters are shown as � below: remove them from the skill or command file, or from the arguments or options substituted into it.3821No shell command in /my-skill was run, because the Bash tool does not accept one of them: command contains control characters that would be hidden in the approval dialog. Unprintable characters are shown as � below: remove them from the skill or command file, or from the arguments or options substituted into it.

3766 3824 

3767**해결 방법:**3825**해결 방법:**

3768 3826 

3769* 메시지 끝에 인용된 명령에서 각 `�`를 찾습니다. 해당 문자를 [스킬 또는 명령 파일](https://code.claude.com/docs/ko/skills.md#where-skills-live)에서, 또는 파일에 대입된 인수나 [옵션](https://code.claude.com/docs/ko/plugins/manifest-reference.md#user-configuration)에서 제거합니다.3827* 메시지 끝에 인용된 명령에서 각 `�`를 찾습니다. 해당 문자를 [스킬 또는 명령 파일](https://code.claude.com/docs/ko/skills.md#where-skills-live)에서, 또는 파일에 대입되는 인수나 [옵션](https://code.claude.com/docs/ko/plugins/manifest-reference.md#user-configuration)에서 제거합니다.

3770 3828 

3771### Input must be provided when using `--print`3829### Input must be provided when using `--print`

3772 3830 

3773인수 없는 `claude`는 대화형 UI를 시작하려면 stdout이 터미널이어야 합니다. stdout이 리디렉션되었거나 PowerShell ISE나 일부 IDE 출력 창처럼 콘솔이 실제 터미널이 아니면, `claude`는 대신 [비대화형으로](https://code.claude.com/docs/ko/headless.md) 실행됩니다. 이는 프롬프트가 필요한 `claude -p`와 같은 모드이므로, 플래그를 전달하지 않았어도 메시지에 `--print`가 표시됩니다. 프롬프트 없이 stdin으로 아무것도 파이프하지 않은 채 `-p`/`--print`를 전달해도 어디서든 같은 오류가 발생합니다.3831인수 없는 `claude`가 대화형 UI를 시작하려면 stdout이 터미널이어야 합니다. stdout이 리디렉션되었거나, PowerShell ISE나 일부 IDE 출력 창처럼 콘솔이 실제 터미널이 아니면 `claude`는 대신 [비대화형으로](https://code.claude.com/docs/ko/headless.md) 실행됩니다. 이는 프롬프트가 필요한 `claude -p`와 같은 모드이므로, 플래그를 전달하지 않았더라도 메시지에 `--print`가 표시됩니다. 프롬프트 없이, stdin으로 아무것도 파이프하지 않고 `-p`/`--print`를 전달하면 어디에서든 같은 오류가 발생합니다.

3774 3832 

3775```text theme={null}3833```text theme={null}

3776Error: Input must be provided either through stdin or as a prompt argument when using --print3834Error: Input must be provided either through stdin or as a prompt argument when using --print

3783 3841 

3784### Claude Code can't read the keyboard here3842### Claude Code can't read the keyboard here

3785 3843 

3786[`-p`](https://code.claude.com/docs/ko/headless) 없이 `claude`를 실행해 [대화형 세션](https://code.claude.com/docs/ko/interactive-mode.md)을 시작했지만, 표준 입력이 터미널이 아닙니다. 무언가가 입력을 파이프하거나 리디렉션했거나, `claude`를 실행한 프로그램이 자체 입력 스트림을 제공했습니다.3844[대화형 세션](https://code.claude.com/docs/ko/interactive-mode.md)을 시작하는 [`-p`](https://code.claude.com/docs/ko/headless) 없이 `claude`를 실행했지만, 표준 입력이 터미널이 아닙니다. 무언가가 파이프로 연결하거나 리디렉션했거나, `claude`를 실행한 프로그램이 자체 입력 스트림을 제공했습니다.

3787 3845 

3788대화형 세션은 키 입력을 읽을 터미널이 필요하며, 터미널이 없을 때 Claude Code의 동작은 플랫폼에 따라 다릅니다.3846대화형 세션은 키 입력을 읽을 터미널이 필요하며, 터미널이 없을 때 Claude Code의 동작은 플랫폼에 따라 다릅니다:

3789 3847 

3790* **Windows**: Claude Code는 인터페이스를 시작하지 않고 메시지를 stderr에 출력한 뒤 종료 코드 1로 종료됩니다3848* **Windows**: Claude Code는 인터페이스를 시작하지 않고 메시지를 stderr에 출력한 후 종료 코드 1로 종료됩니다

3791* **macOS 및 Linux**: Claude Code는 `/dev/tty`에서 키 입력을 읽고 세션을 시작하며, 파이프된 텍스트가 있으면 첫 번째 프롬프트로 사용합니다. `/dev/tty`를 열 수 없을 때 메시지가 표시되며, 첫 번째 줄에는 Windows 문구 대신 `/dev/tty`가 표시됩니다.3849* **macOS 및 Linux**: Claude Code는 `/dev/tty`에서 키 입력을 읽고 세션을 시작하며, 파이프된 텍스트가 있으면 첫 번째 프롬프트로 사용합니다. `/dev/tty`를 열 수 없으면 메시지가 표시되며, 첫 번째 줄에는 Windows 문구 대신 `/dev/tty`가 표시됩니다.

3792 3850 

3793Windows에서 메시지는 다음과 같습니다.3851Windows에서 메시지는 다음과 같습니다:

3794 3852 

3795```text theme={null}3853```text theme={null}

3796Claude Code can't read the keyboard here: stdin is not a terminal (it is piped, redirected, or supplied by the program that launched claude), and on Windows it can't fall back to the console for input yet.3854Claude Code can't read the keyboard here: stdin is not a terminal (it is piped, redirected, or supplied by the program that launched claude), and on Windows it can't fall back to the console for input yet.

3800 3858 

3801**해결 방법:**3859**해결 방법:**

3802 3860 

3803* 대화형으로 작업하려면 입력을 파이프하거나 리디렉션하지 않고 터미널에서 직접 `claude`를 실행합니다3861* 대화형으로 작업하려면 입력을 파이프하거나 리디렉션하지 않고 터미널에서 `claude`를 직접 실행합니다

3804* 스크립트 등에서 대화형 인터페이스 없이 응답을 받으려면 `-p`를 추가하고 `claude -p "your question"` 또는 `echo "your question" | claude -p`처럼 프롬프트를 인수나 stdin으로 전달합니다. `--continue` 및 `--resume <session-id>`에서도 같은 방식이 작동합니다.3862* 스크립트 등에서 대화형 인터페이스 없이 답변을 받으려면 `-p`를 추가하고 `claude -p "your question"` 또는 `echo "your question" | claude -p`처럼 프롬프트를 인수로 또는 stdin으로 전달합니다. `--continue` 및 `--resume <session-id>`에서도 같은 방식이 동작합니다.

3805 3863 

3806v2.1.287 이전에는 Claude Code가 이 메시지를 출력하는 대신 인터페이스를 시작했으며, 화면에 아무것도 표시하지 않거나 `Raw mode is not supported`가 포함된 오류로 실패했습니다.3864v2.1.287 이전에는 Claude Code가 이 메시지를 출력하는 대신 인터페이스를 시작한 다음, 화면에 아무것도 표시하지 않거나 `Raw mode is not supported`를 포함하는 오류로 실패했습니다.

3807 3865 

3808`claude install` 중에 `Raw mode is not supported`가 표시되는 경우에는 [설치 중 `Raw mode is not supported`](https://code.claude.com/docs/ko/troubleshoot-install#raw-mode-is-not-supported-during-install)를 참조하세요.3866대신 `claude install` 중에 `Raw mode is not supported`가 표시되면 [설치 중 `Raw mode is not supported`](https://code.claude.com/docs/ko/troubleshoot-install#raw-mode-is-not-supported-during-install)를 참조하세요.

3809 3867 

3810### Input contained only whitespace3868### Input contained only whitespace

3811 3869 

3812[비대화형 모드](https://code.claude.com/docs/ko/headless.md)에서 Claude Code는 공백, 탭, 줄 바꿈으로만 이루어진 프롬프트를 전송하지 않고 거부합니다. API가 보이는 텍스트가 없는 메시지를 거부하기 때문입니다. 표시되는 메시지는 빈 프롬프트가 어디서 왔는지에 따라 다릅니다.3870[비대화형 모드](https://code.claude.com/docs/ko/headless.md)에서 Claude Code는 공백, 탭 또는 줄 바꿈으로만 이루어진 프롬프트를 전송하지 않고 거부합니다. API가 보이는 텍스트가 없는 메시지를 거부하기 때문입니다. 표시되는 메시지는 빈 프롬프트가 어디에서 왔는지에 따라 다릅니다.

3813 3871 

3814* **`claude -p`의 프롬프트 인수 또는 파이프된 stdin**: `claude`가 `Error: Input contained only whitespace. Provide a prompt with text through stdin or as a prompt argument when using --print`와 함께 종료됩니다3872* **`claude -p`의 프롬프트 인수 또는 파이프된 stdin**: `claude`가 `Error: Input contained only whitespace. Provide a prompt with text through stdin or as a prompt argument when using --print` 메시지와 함께 종료됩니다

3815* **실행 중인 `--input-format stream-json` 또는 [Agent SDK](https://code.claude.com/docs/ko/agent-sdk/overview.md) 세션에 제출된 메시지**: Claude Code는 모델을 호출하지 않고 턴을 종료하며 세션은 계속 사용할 수 있습니다. 거부 내용은 정보 메시지와 턴의 결과 텍스트로 전달됩니다: `Blank prompt — the message was only whitespace, so nothing was sent to the model.`3873* **실행 중인 `--input-format stream-json` 또는 [Agent SDK](https://code.claude.com/docs/ko/agent-sdk/overview.md) 세션에 제출된 메시지**: Claude Code는 모델을 호출하지 않고 턴을 종료하며, 세션은 계속 사용할 수 있습니다. 거부 내용은 정보 메시지와 해당 턴의 결과 텍스트로 전달됩니다: `Blank prompt — the message was only whitespace, so nothing was sent to the model.`

3816 3874 

3817v2.1.229 이전에는 Claude Code가 공백만 있는 메시지를 API로 전송했고, API가 400 오류로 요청을 거부했습니다.3875v2.1.229 이전에는 Claude Code가 공백만 있는 메시지를 API로 전송했고, API는 400 오류로 요청을 거부했습니다.

3818 3876 

3819**해결 방법:**3877**해결 방법:**

3820 3878 

3821* 프롬프트에 보이는 텍스트를 포함합니다. 스크립트가 변수나 파일에서 프롬프트를 구성하는 경우 Claude Code를 호출하기 전에 소스가 비어 있지 않은지 확인합니다.3879* 프롬프트에 보이는 텍스트를 포함합니다. 스크립트가 변수나 파일로 프롬프트를 구성하는 경우, Claude Code를 호출하기 전에 원본이 비어 있지 않은지 확인합니다.

3822 3880 

3823### stream-json input carried over 256M characters with no newline3881### stream-json input carried over 256M characters with no newline

3824 3882 

3825프로그램이 `claude -p --input-format stream-json` 실행에 줄 바꿈 없이 268,435,456자를 초과하는 입력을 stdin으로 보냈으므로, Claude Code는 입력을 더 버퍼링하지 않고 이 오류를 stderr에 출력한 뒤 종료 코드 1로 종료됩니다. 메시지에서는 이 한도를 `256M`으로 표시합니다. v2.1.257 이전에는 Claude Code가 이러한 입력을 제한 없이 버퍼링해 프로세스가 충돌하거나 강제 종료될 때까지 메모리가 증가했습니다.3883프로그램이 `claude -p --input-format stream-json` 실행에 줄 바꿈 없이 268,435,456자를 초과하는 문자를 stdin으로 보냈기 때문에, Claude Code는 입력을 더 버퍼링하는 대신 이 오류를 stderr에 출력하고 코드 1로 종료합니다. 메시지에서는 이 한도를 `256M`으로 표시합니다. v2.1.257 이전에는 Claude Code가 이러한 입력을 제한 없이 버퍼링했기 때문에, 프로세스가 충돌하거나 강제 종료될 때까지 메모리 사용량이 계속 증가했습니다.

3826 3884 

3827```text theme={null}3885```text theme={null}

3828Error: stream-json input carried over 256M characters with no newline. Each stream-json message must be a single newline-terminated JSON line: either the producer is not newline-terminating its messages, or one message exceeded this budget.3886Error: stream-json input carried over 256M characters with no newline. Each stream-json message must be a single newline-terminated JSON line: either the producer is not newline-terminating its messages, or one message exceeded this budget.

3829```3887```

3830 3888 

3831줄 바꿈 없이 이렇게 긴 입력은 대개 실수로 파이프된 바이너리 파일이나 일반 로그 출력처럼 생산자가 애초에 stream-json 생산자가 아니라는 의미입니다. 한도를 초과하는 단일 메시지도 같은 검사에서 실패합니다.3889줄 바꿈 없이 이렇게 긴 입력은 대개 입력을 생성하는 쪽이 애초에 stream-json 생성기가 아니라는 뜻입니다. 예를 들어 실수로 파이프된 바이너리 파일이나 일반 로그 출력이 이에 해당합니다. 한도를 초과하는 단일 메시지도 같은 검사에서 실패합니다.

3832 3890 

3833**해결 방법:**3891**해결 방법:**

3834 3892 

3835* stdin으로 무엇이 파이프되는지 확인합니다. [`--input-format stream-json`](https://code.claude.com/docs/ko/cli-reference#cli-flags)을 사용하면 모든 메시지는 줄 바꿈으로 끝나는 JSON 한 줄이어야 합니다3893* stdin으로 무엇이 파이프되는지 확인합니다. [`--input-format stream-json`](https://code.claude.com/docs/ko/cli-reference#cli-flags)을 사용할 때는 모든 메시지가 줄 바꿈으로 끝나는 한 줄의 JSON이어야 합니다

3836* 대신 일반 텍스트를 보내려면 `--input-format stream-json`을 제거합니다. `claude -p`는 기본적으로 stdin에서 일반 텍스트 프롬프트를 읽습니다3894* 대신 일반 텍스트를 보내려면 `--input-format stream-json`을 제거합니다. `claude -p`는 기본적으로 stdin에서 일반 텍스트 프롬프트를 읽습니다

3837 3895 

3838### Unknown command3896### Unknown command

3839 3897 

3840대화형 터미널 세션에서 이 세션의 어떤 명령과도 일치하지 않는 `/` 이름을 제출했기 때문에, Claude Code가 아무것도 실행하지 않고 해당 이름을 보고합니다:3898대화형 터미널 세션에서 이 세션의 어떤 명령과도 일치하지 않는 `/` 이름을 제출했기 때문에, Claude Code는 아무것도 실행하지 않고 해당 이름을 보고합니다.

3841 3899 

3842```text theme={null}3900```text theme={null}

3843Unknown command: /hepl. Did you mean /help?3901Unknown command: /hepl. Did you mean /help?

3844```3902```

3845 3903 

3846Claude Code는 이 세션에서 메뉴에 나열된 명령 이름 또는 별칭 중 가장 가까운 것을 제안합니다. 가까운 것이 없으면 메시지는 이름 뒤에서 끝납니다. 원인은 보통 다음 중 하나입니다:3904Claude Code는 이 세션의 메뉴에 나열된 명령 이름이나 별칭 중 가장 가까운 것을 제안합니다. 가까운 것이 없으면 메시지는 이름 뒤에서 끝납니다. 원인은 대개 다음 중 하나입니다.

3847 3905 

3848* `/help` 대신 `/hepl`을 입력한 것과 같은 오타. 제출하기 전에 가까운 일치 항목을 고르는 방법은 [명령 메뉴가 입력 내용과 일치시키는 방식](https://code.claude.com/docs/ko/commands.md#how-the-command-menu-matches-what-you-type)에서 다룹니다3906* `/help` 대신 `/hepl`처럼 입력한 오타. 제출하기 전에 가까운 항목을 선택하는 방법은 [명령 메뉴가 입력한 내용과 일치시키는 방식](https://code.claude.com/docs/ko/commands.md#how-the-command-menu-matches-what-you-type)에서 다룹니다

3849* 존재하지만 플랫폼, 플랜, 인증 방법 등의 요구 사항이 충족되지 않아 이 세션에서 사용할 수 없는 명령. [`/web-setup`](https://code.claude.com/docs/ko/web-quickstart#web-setup-shows-no-commands-match-or-unknown-command), [`/schedule`](https://code.claude.com/docs/ko/routines#schedule-returns-unknown-command), [`/auto-mode-setup`](https://code.claude.com/docs/ko/auto-mode-config#auto-mode-setup-returns-unknown-command) 항목을 참조하십시오. 일부 명령은 조직의 정책으로 비활성화된 경우 [`Cloud sessions are disabled by your organization's policy`](#cloud-sessions-are-disabled-by-your-organizations-policy)와 같은 자체 메시지로 응답합니다3907* 존재하지만 플랫폼, 요금제 또는 인증 방법 등의 요구 사항이 충족되지 않아 이 세션에서 사용할 수 없는 명령. [`/web-setup`](https://code.claude.com/docs/ko/web-quickstart#web-setup-shows-no-commands-match-or-unknown-command), [`/schedule`](https://code.claude.com/docs/ko/routines#schedule-returns-unknown-command) 또는 [`/auto-mode-setup`](https://code.claude.com/docs/ko/auto-mode-config#auto-mode-setup-returns-unknown-command) 항목을 참조하세요. 일부 명령은 조직의 정책으로 비활성화된 경우 [`Cloud sessions are disabled by your organization's policy`](#cloud-sessions-are-disabled-by-your-organizations-policy)처럼 자체 메시지로 응답합니다

3850* 이 세션에 설치되지 않았거나 연결되지 않은 [플러그인](https://code.claude.com/docs/ko/plugins/overview.md) 또는 [MCP 서버](https://code.claude.com/docs/ko/mcp.md#use-mcp-prompts-as-commands)의 명령3908* 이 세션에 설치되거나 연결되지 않은 [플러그인](https://code.claude.com/docs/ko/plugins/overview.md) 또는 [MCP 서버](https://code.claude.com/docs/ko/mcp.md#use-mcp-prompts-as-commands)의 명령

3851 3909 

3852Claude Code는 대화형 터미널 세션에서만 일치하지 않는 `/` 이름에 이런 방식으로 응답합니다. 그 외의 모든 세션에서는 프롬프트를 일반 메시지로 Claude에 보내며, 명령이 실행되지 않았다는 안내와 세션에서 Claude가 실행할 수 있는 명령 목록을 함께 보냅니다. 해당 세션은 다음과 같습니다:3910Claude Code는 대화형 터미널 세션에서만 일치하지 않는 `/` 이름에 이런 방식으로 응답합니다. 그 외의 모든 세션에서는 명령이 실행되지 않았다는 안내와 해당 세션에서 Claude가 실행할 수 있는 명령 목록을 덧붙여, 프롬프트를 일반 메시지로 Claude에게 보냅니다. 이러한 세션은 다음과 같습니다.

3853 3911 

3854* `-p` 실행3912* `-p` 실행

3855* [Agent SDK](https://code.claude.com/docs/ko/agent-sdk/overview.md) 애플리케이션3913* [Agent SDK](https://code.claude.com/docs/ko/agent-sdk/overview.md) 애플리케이션

3857* [VS Code 확장 프로그램](https://code.claude.com/docs/ko/vs-code.md)의 채팅 패널3915* [VS Code 확장 프로그램](https://code.claude.com/docs/ko/vs-code.md)의 채팅 패널

3858* [클라우드 세션](https://code.claude.com/docs/ko/claude-code-on-the-web.md) 및 [클라우드 예약 작업](https://code.claude.com/docs/ko/routines.md)3916* [클라우드 세션](https://code.claude.com/docs/ko/claude-code-on-the-web.md) 및 [클라우드 예약 작업](https://code.claude.com/docs/ko/routines.md)

3859 3917 

3860이러한 세션 중 하나에서 실행할 수 없는 기본 제공 명령의 경우, Claude Code는 여전히 Claude에 보내지 않고 해당 명령을 사용할 수 없다고 응답합니다. v2.1.274 이전에는 클라우드 세션과 클라우드 예약 작업만 일치하지 않는 이름을 Claude에 보냈습니다. v2.1.273 이전에는 이들도 `Unknown command`로 응답했습니다.3918이러한 세션 중 하나에서 실행할 수 없는 기본 제공 명령의 경우, Claude Code는 여전히 명령을 Claude에게 보내지 않고 해당 명령을 사용할 수 없다고 응답합니다. v2.1.274 이전에는 클라우드 세션과 클라우드 예약 작업만 일치하지 않는 이름을 Claude에게 보냈습니다. v2.1.273 이전에는 이들도 `Unknown command`로 응답했습니다.

3861 3919 

3862Claude Code는 `/`로 시작하는 모든 프롬프트를 명령으로 처리하지 않습니다. `/` 뒤의 첫 단어가 Lean 문서 주석을 여는 `/--`처럼 구두점으로 시작하거나 `/var/log/syslog`와 같은 경로인 경우, 프롬프트를 일반 메시지로 Claude에 보냅니다.3920Claude Code는 `/`로 시작하는 모든 프롬프트를 명령으로 취급하지는 않습니다. `/` 뒤의 첫 단어가 Lean 문서 주석을 여는 `/--`처럼 구두점으로 시작하거나 `/var/log/syslog` 같은 경로인 경우, 프롬프트를 일반 메시지로 Claude에게 보냅니다.

3863 3921 

3864v2.1.236 이전에는 명령 메뉴에 입력한 이름과 가까운 항목이 나열된 상태에서 `Enter`를 누르면 Claude Code가 해당 항목을 실행했기 때문에, `/hepl`과 같은 오타는 이 메시지를 표시하는 대신 `/help`를 실행했습니다.3922v2.1.236 이전에는 입력한 이름과 비슷한 항목이 명령 메뉴에 나열된 상태에서 `Enter`를 누르면 Claude Code가 그 항목을 실행했기 때문에, `/hepl` 같은 오타는 이 메시지를 표시하는 대신 `/help`를 실행했습니다.

3865 3923 

3866**해결 방법:**3924**해결 방법:**

3867 3925 

3868* 제안된 이름을 실행하거나, `/` 뒤에 이름의 일부를 입력하여 이 세션에서 사용할 수 있는 명령을 확인합니다3926* 제안된 이름을 실행하거나, `/` 뒤에 이름의 일부를 입력하여 이 세션에서 사용할 수 있는 명령을 확인합니다

3869* Claude Code가 문서화된 명령을 알 수 없다고 보고하는 경우, [명령 참조](https://code.claude.com/docs/ko/commands.md)에서 해당 명령의 행을 확인하여 명시된 요구 사항을 확인합니다3927* 문서에 있는 명령을 Claude Code가 알 수 없는 명령으로 보고하는 경우, [명령 레퍼런스](https://code.claude.com/docs/ko/commands.md)에서 해당 명령의 행에 명시된 요구 사항을 확인합니다

3870 3928 

3871### Diff is too large for ultrareview3929### Diff is too large for ultrareview

3872 3930 

3873커밋되지 않은 변경 사항과 스테이징된 변경 사항을 포함하여 현재 브랜치와 기본 브랜치 간의 diff가 [ultrareview](https://code.claude.com/docs/ko/ultrareview.md)의 크기 제한을 초과하므로, `/code-review ultra`와 `claude ultrareview` 하위 명령은 클라우드 세션이 시작되기 전에 리뷰를 거부합니다. 거부된 리뷰는 무료 실행 횟수를 사용하지 않으며 사용량 크레딧도 청구되지 않습니다. 메시지에는 적용 중인 제한, diff의 크기, 변경된 줄 수가 가장 많은 파일이 표시됩니다. v2.1.216 이전에는 메시지에 원시 diff 통계만 표시되었습니다.3931커밋되지 않은 변경 사항과 스테이징된 변경 사항을 포함한 현재 브랜치와 기본 브랜치 간의 diff가 [ultrareview](https://code.claude.com/docs/ko/ultrareview.md)의 크기 제한을 초과하므로, `/code-review ultra`와 `claude ultrareview` 하위 명령은 클라우드 세션이 시작되기 전에 리뷰를 거부합니다. 거부된 리뷰는 무료 실행 횟수를 사용하지 않으며 사용량 크레딧도 청구되지 않습니다. 메시지에는 적용 중인 제한, diff의 크기, 변경된 줄이 가장 많은 파일이 표시됩니다. v2.1.216 이전에는 메시지에 원시 diff 통계만 표시되었습니다.

3874 3932 

3875```text theme={null}3933```text theme={null}

3876Diff is too large for ultrareview: 812 files, 96,410 lines changed (limits: 500 files, 8,000 lines). Largest files: package-lock.json (41,904 lines), dist/bundle.js (18,210 lines), src/generated/api.ts (9,876 lines). Pass a closer base branch (`/code-review ultra <branch>`) to narrow the scope, or split the change.3934Diff is too large for ultrareview: 812 files, 96,410 lines changed (limits: 500 files, 8,000 lines). Largest files: package-lock.json (41,904 lines), dist/bundle.js (18,210 lines), src/generated/api.ts (9,876 lines). Pass a closer base branch (`/code-review ultra <branch>`) to narrow the scope, or split the change.

3877```3935```

3878 3936 

3879풀 리퀘스트를 리뷰할 때도 동일한 제한이 적용됩니다. 이 경우 메시지는 `PR #<N> is too large for ultrareview`로 시작하며 PR의 파일 수와 줄 수를 표시합니다.3937풀 리퀘스트를 리뷰할 때도 같은 제한이 적용됩니다. 이 경우 메시지는 `PR #<N> is too large for ultrareview`로 시작하며 PR의 파일 수와 줄 수를 표시합니다.

3880 3938 

3881**해결 방법:**3939**해결 방법:**

3882 3940 

3883* `/code-review ultra develop`처럼 작업에 더 가까운 기본 브랜치를 전달하여, 리뷰가 해당 브랜치와의 diff만 다루도록 합니다3941* `/code-review ultra develop`처럼 작업에 더 가까운 기본 브랜치를 전달하여, 리뷰가 해당 브랜치에 대한 diff만 다루도록 합니다

3884* 변경 사항을 더 작은 브랜치로 나누고 각각 리뷰합니다. 메시지에 표시된 파일이 변경된 줄 수가 가장 많으므로, 먼저 해당 파일을 별도의 브랜치로 옮기십시오.3942* 변경 사항을 더 작은 브랜치로 나누고 각각 리뷰합니다. 메시지에 표시된 파일이 변경된 줄을 가장 많이 차지하므로, 먼저 해당 파일들을 별도의 브랜치로 옮깁니다.

3885 3943 

3886### Could not find merge-base with the base branch3944### Could not find merge-base with the base branch

3887 3945 

3888`/code-review ultra`와 `claude ultrareview` 하위 명령은 현재 브랜치와 기본 브랜치 간의 diff를 리뷰하며, 이를 위해서는 두 브랜치가 공유하는 커밋이 필요합니다. `git merge-base`가 공유 커밋을 찾지 못하면 Claude Code는 클라우드 세션이 시작되기 전에 리뷰를 거부합니다. Claude Code가 완전하다고 확인할 수 있고 브랜치가 하나 이상 있는 클론에서는 거부하는 대신 [추적되는 모든 파일을 리뷰하는 방식](https://code.claude.com/docs/ko/ultrareview.md#diff-limits-and-fallbacks)으로 대체합니다. 기본 브랜치를 전혀 찾을 수 없는 경우, Claude Code가 클론이 완전한지 확인할 수 없는 경우, 또는 SHA-256 객체 형식처럼 전체 트리 diff가 불가능한 드문 저장소에서 이 거부 메시지가 표시됩니다.3946`/code-review ultra`와 `claude ultrareview` 하위 명령은 현재 브랜치와 기본 브랜치 간의 diff를 리뷰하며, 이를 위해서는 두 브랜치가 공유하는 커밋이 필요합니다. `git merge-base`가 공유 커밋을 찾지 못하면 Claude Code는 클라우드 세션이 시작되기 전에 리뷰를 거부합니다. Claude Code가 완전한 클론임을 확인할 수 있고 브랜치가 하나 이상 있는 경우에는 거부하는 대신 [추적 중인 모든 파일을 리뷰](https://code.claude.com/docs/ko/ultrareview.md#diff-limits-and-fallbacks)하는 방식으로 대체합니다. 이 거부는 기본 브랜치를 전혀 찾을 수 없을 때, Claude Code가 클론이 완전한지 확인할 수 없을 때, 또는 SHA-256 객체 형식처럼 전체 트리 diff가 불가능한 드문 저장소에서 표시됩니다.

3889 3947 

3890```text theme={null}3948```text theme={null}

3891Could not find merge-base with main. Pass the base branch explicitly (e.g. `/code-review ultra develop`) or make sure you're in a git repo with a main branch.3949Could not find merge-base with main. Pass the base branch explicitly (e.g. `/code-review ultra develop`) or make sure you're in a git repo with a main branch.

3892```3950```

3893 3951 

3894첫 번째 문장 뒤의 힌트는 Claude Code가 확인한 내용에 따라 달라집니다:3952첫 문장 뒤의 힌트는 Claude Code가 확인한 상황에 따라 달라집니다.

3895 3953 

3896* **기본 브랜치를 전달하지 않은 경우**: Claude Code는 저장소의 기본 브랜치와 비교했으며, 위 예시처럼 기본 브랜치를 명시적으로 전달하도록 제안합니다3954* **기본 브랜치를 전달하지 않은 경우**: Claude Code는 저장소의 기본 브랜치와 비교했으며, 위 예시처럼 기본 브랜치를 명시적으로 전달하도록 제안합니다

3897* **이미 클론에 있는 기본 브랜치를 전달한 경우**: 힌트는 ``Make sure <branch> exists locally or on origin (try `git fetch origin <branch>`)``입니다3955* **클론에 이미 있던 기본 브랜치를 전달한 경우**: 힌트는 ``Make sure <branch> exists locally or on origin (try `git fetch origin <branch>`)``입니다

3898* **클론에 없는 기본 브랜치를 전달한 경우**: Claude Code는 비교하기 전에 origin에서 해당 브랜치를 가져왔습니다. 힌트는 ``<branch> was fetched from origin but shares no history with HEAD. If another branch is your real base, pass it explicitly (`/code-review ultra <branch>`)``입니다. Claude Code가 클론이 shallow 클론인지 판단할 수 없는 경우에는 대신 `git fetch --unshallow origin`을 제안합니다. v2.1.221 이전에는 가져온 모든 기본 브랜치에 대해 `git fetch --unshallow origin`을 제안했으며, 완전한 클론에서는 이 명령이 `fatal: --unshallow on a complete repository does not make sense`와 함께 실패했습니다.3956* **클론에 없던 기본 브랜치를 전달한 경우**: Claude Code는 비교하기 전에 origin에서 해당 브랜치를 가져왔습니다. 힌트는 ``<branch> was fetched from origin but shares no history with HEAD. If another branch is your real base, pass it explicitly (`/code-review ultra <branch>`)``이며, Claude Code가 클론이 shallow인지 판단할 수 없는 경우에는 대신 `git fetch --unshallow origin`을 제안합니다. v2.1.221 이전에는 가져온 모든 기본 브랜치에 대해 힌트가 `git fetch --unshallow origin`을 제안했으며, 완전한 클론에서는 이 명령이 `fatal: --unshallow on a complete repository does not make sense`와 함께 실패합니다.

3899 3957 

3900**해결 방법:**3958**해결 방법:**

3901 3959 

3902* 다른 브랜치가 실제 기본 브랜치라면 명시적으로 전달합니다: `/code-review ultra <branch>`3960* 다른 브랜치가 실제 기본 브랜치라면 `/code-review ultra <branch>`로 명시적으로 전달합니다

3903* 클론에 전체 기록이 없을 수 있다면 `git fetch --unshallow origin`을 실행하고 리뷰를 다시 실행합니다3961* 클론에 전체 기록이 없을 수 있다면 `git fetch --unshallow origin`을 실행하고 리뷰를 다시 실행합니다

3904 3962 

3905### Your checkout has no branches3963### Your checkout has no branches

3906 3964 

3907체크아웃에 커밋은 있지만 브랜치가 없을 수 있습니다. `git init`을 실행한 후 `git fetch <url>`과 `git checkout FETCH_HEAD`를 실행하면 ref가 없는 detached HEAD 상태가 됩니다. Claude Code는 [ultrareview](https://code.claude.com/docs/ko/ultrareview.md)를 위해 저장소를 git 번들로 패키징하여 업로드하는데, 브랜치나 다른 ref가 없는 저장소는 번들로 만들 수 없으므로 `/code-review ultra`와 `claude ultrareview` 하위 명령은 클라우드 세션이 시작되기 전에 리뷰를 거부합니다.3965체크아웃에는 커밋이 있지만 브랜치가 없을 수 있습니다. `git init`을 실행한 후 `git fetch <url>`과 `git checkout FETCH_HEAD`를 실행하면 ref가 없는 detached HEAD 상태가 됩니다. Claude Code는 [ultrareview](https://code.claude.com/docs/ko/ultrareview.md)를 위해 저장소를 업로드할 때 git 번들로 패키징하는데, 브랜치나 다른 ref가 없는 저장소는 번들로 만들 수 없으므로 `/code-review ultra`와 `claude ultrareview` 하위 명령은 클라우드 세션이 시작되기 전에 리뷰를 거부합니다.

3908 3966 

3909```text theme={null}3967```text theme={null}

3910Your checkout has no branches (detached HEAD only), which cloud review can't bundle. Create one first — `git checkout -b <name>` — then rerun /code-review ultra.3968Your checkout has no branches (detached HEAD only), which cloud review can't bundle. Create one first — `git checkout -b <name>` — then rerun /code-review ultra.

3911```3969```

3912 3970 

3913v2.1.221 이전에는 Claude Code가 이 체크아웃에서 추적되는 모든 파일을 리뷰하려고 시도했으며, 업로드가 실패했습니다.3971v2.1.221 이전에는 Claude Code가 이 체크아웃에서 추적 중인 모든 파일을 리뷰하려고 시도했고, 업로드가 실패했습니다.

3914 3972 

3915**해결 방법:**3973**해결 방법:**

3916 3974 

3918 3976 

3919### No GitHub account is connected to your Claude account3977### No GitHub account is connected to your Claude account

3920 3978 

3921`/code-review ultra <PR#>` 또는 `claude ultrareview <PR#>`을 실행하면, Claude Code는 클라우드 세션을 만들기 전에 [Claude 계정에 연결된 GitHub 계정](https://code.claude.com/docs/ko/ultrareview.md#review-a-pull-request)이 PR의 저장소에 접근할 수 있는지 서버에 확인합니다. 연결된 계정이 없거나 연결이 만료된 경우 클라우드 클론이 실패할 것이므로 Claude Code는 실행을 거부합니다. 거부된 실행에 대해서는 무료 실행 횟수를 사용하지 않으며 사용량 크레딧도 청구하지 않습니다.3979`/code-review ultra <PR#>` 또는 `claude ultrareview <PR#>`을 실행하면, Claude Code는 클라우드 세션을 만들기 전에 [Claude 계정에 연결된 GitHub 계정](https://code.claude.com/docs/ko/ultrareview.md#review-a-pull-request)이 PR의 저장소에 접근할 수 있는지 서버에 확인합니다. 연결된 계정이 없거나 연결이 만료되어 클라우드 클론이 실패할 것이므로 Claude Code가 실행을 거부합니다. 거부된 실행에 대해서는 무료 실행 횟수를 사용하거나 사용량 크레딧을 청구하지 않습니다.

3922 3980 

3923```text theme={null}3981```text theme={null}

3924Ultrareview clones <owner>/<repo> in the cloud with the GitHub account connected to your Claude account, and none is connected (or the connection expired). To fix: run /web-setup to reuse your GitHub CLI login, or connect an account at https://claude.ai/connect-github — then re-run /code-review ultra 1234 (allow a minute after connecting).3982Ultrareview clones <owner>/<repo> in the cloud with the GitHub account connected to your Claude account, and none is connected (or the connection expired). To fix: run /web-setup to reuse your GitHub CLI login, or connect an account at https://claude.ai/connect-github — then re-run /code-review ultra 1234 (allow a minute after connecting).

3925```3983```

3926 3984 

3927세션에서 [`/web-setup`](https://code.claude.com/docs/ko/web-quickstart#connect-from-your-terminal)을 사용할 수 없는 경우 메시지에는 claude.ai 링크만 표시됩니다.3985세션에서 [`/web-setup`](https://code.claude.com/docs/ko/web-quickstart#connect-from-your-terminal)을 사용할 수 없는 경우, 메시지에는 claude.ai 링크만 표시됩니다.

3928 3986 

3929**해결 방법:**3987**해결 방법:**

3930 3988 

3931* `/web-setup`을 실행하여 GitHub CLI 로그인을 Claude 계정에 연결하거나, [claude.ai/connect-github](https://claude.ai/connect-github)에서 계정을 연결합니다3989* `/web-setup`을 실행하여 GitHub CLI 로그인을 Claude 계정에 연결하거나, [claude.ai/connect-github](https://claude.ai/connect-github)에서 계정을 연결합니다

3932* 연결하고 1분 후에 리뷰를 다시 실행합니다3990* 연결하고 1분 정도 지난 후 리뷰를 다시 실행합니다

3933 3991 

3934v2.1.248 이전에는 Claude Code가 실행 전에 이를 확인하지 않았습니다.3992v2.1.248 이전에는 Claude Code가 실행 전에 이를 확인하지 않았습니다.

3935 3993 

3936### Your connected GitHub account can't see the repository3994### Your connected GitHub account can't see the repository

3937 3995 

3938`/code-review ultra <PR#>` 또는 `claude ultrareview <PR#>`을 실행했지만 [Claude 계정에 연결된 GitHub 계정](https://code.claude.com/docs/ko/ultrareview.md#review-a-pull-request)이 PR의 저장소를 읽을 수 없으므로, 클라우드 클론이 실패할 것이어서 Claude Code가 실행을 거부합니다. 거부된 실행에 대해서는 무료 실행 횟수를 사용하지 않으며 사용량 크레딧도 청구하지 않습니다.3996`/code-review ultra <PR#>` 또는 `claude ultrareview <PR#>`을 실행했지만 [Claude 계정에 연결된 GitHub 계정](https://code.claude.com/docs/ko/ultrareview.md#review-a-pull-request)이 PR의 저장소를 읽을 수 없어 클라우드 클론이 실패할 것이므로 Claude Code가 실행을 거부합니다. 거부된 실행에 대해서는 무료 실행 횟수를 사용하거나 사용량 크레딧을 청구하지 않습니다.

3939 3997 

3940```text theme={null}3998```text theme={null}

3941Your connected GitHub account can't see <owner>/<repo> — usually the Claude GitHub app isn't installed on <owner> or wasn't granted this repo (web-connected accounts need it for private repos), or a different GitHub account is connected. To fix: run /web-setup to reuse your GitHub CLI login, or install the app at https://github.com/apps/claude/installations/new — then re-run /code-review ultra 1234.3999Your connected GitHub account can't see <owner>/<repo> — usually the Claude GitHub app isn't installed on <owner> or wasn't granted this repo (web-connected accounts need it for private repos), or a different GitHub account is connected. To fix: run /web-setup to reuse your GitHub CLI login, or install the app at https://github.com/apps/claude/installations/new — then re-run /code-review ultra 1234.

3942```4000```

3943 4001 

3944세션에서 [`/web-setup`](https://code.claude.com/docs/ko/web-quickstart#connect-from-your-terminal)을 사용할 수 없는 경우 메시지에는 앱 설치만 표시됩니다.4002세션에서 [`/web-setup`](https://code.claude.com/docs/ko/web-quickstart#connect-from-your-terminal)을 사용할 수 없는 경우, 메시지에는 앱 설치 안내만 표시됩니다.

3945 4003 

3946**해결 방법:**4004**해결 방법:**

3947 4005 

3952 4010 

3953### The GitHub App preflight failed transiently4011### The GitHub App preflight failed transiently

3954 4012 

3955로컬 저장소에서 [클라우드 세션](https://code.claude.com/docs/ko/claude-code-on-the-web.md)을 시작했는데 두 단계가 함께 실패했습니다. Claude Code가 저장소의 번들을 빌드하거나 업로드할 수 없었습니다. 업로드 전에 Claude Code는 클라우드 서비스가 GitHub에서 저장소를 클론할 수 있는지 확인했는데, 이 확인이 명확한 답을 얻지 못하고 네트워크 오류, 시간 초과, 일시적인 서버 오류처럼 재시도하면 해소될 수 있는 오류로 끝났습니다. 전체 메시지는 `Could not upload repo bundle (<error>)`처럼 번들을 중단시킨 원인으로 시작하고, 사전 확인 문장으로 끝납니다:4013로컬 저장소에서 [클라우드 세션](https://code.claude.com/docs/ko/claude-code-on-the-web.md)을 시작했는데 두 단계가 함께 실패했습니다. Claude Code가 저장소의 번들을 빌드하거나 업로드하지 못했습니다. 업로드 전에 Claude Code는 클라우드 서비스가 GitHub에서 저장소를 클론할 수 있는지 확인했는데, 이 확인이 명확한 결과 대신 네트워크 오류, 시간 초과, 일시적인 서버 오류처럼 재시도하면 해결될 수 있는 오류로 끝났습니다. 전체 메시지는 `Could not upload repo bundle (<error>)`처럼 번들을 중단시킨 원인으로 시작하고 사전 확인에 관한 문장으로 끝납니다.

3956 4014 

3957```text theme={null}4015```text theme={null}

3958Could not upload repo bundle (<error>). The GitHub App preflight failed transiently (network or service hiccup) — retry in a moment to start from GitHub instead4016Could not upload repo bundle (<error>). The GitHub App preflight failed transiently (network or service hiccup) — retry in a moment to start from GitHub instead

3960 4018 

3961**해결 방법:**4019**해결 방법:**

3962 4020 

3963* 잠시 후 명령을 다시 실행합니다. GitHub 확인이 통과하면 Claude Code가 GitHub 클론에서 세션을 시작할 수 있으므로, 실패한 업로드가 더 이상 실행을 막지 않습니다4021* 잠시 후 명령을 다시 실행합니다. GitHub 확인을 통과하면 Claude Code가 GitHub 클론에서 세션을 시작할 수 있으므로, 실패한 업로드가 더 이상 실행을 막지 않습니다

3964* 재시도가 계속 실패하면 메시지의 시작 부분에 업로드를 중단시킨 원인이 표시됩니다. 해당 원인이 직접 해결할 수 있는 것이라면 해결하여 세션이 로컬 저장소에서 시작될 수 있도록 합니다4022* 재시도해도 계속 실패한다면 메시지의 앞부분에 업로드를 중단시킨 원인이 표시됩니다. 그 원인이 해결할 수 있는 것이라면 해결하여 세션이 로컬 저장소에서 시작될 수 있도록 합니다

3965 4023 

3966v2.1.251 이전에는 GitHub 확인이 일시적으로만 실패한 경우에도 Claude Code가 메시지를 `Please set up GitHub on https://claude.ai/code`로 끝냈는데, 설정 안내로는 일시적인 실패를 해결할 수 없습니다.4024v2.1.251 이전에는 GitHub 확인이 일시적으로만 실패한 경우에도 Claude Code가 메시지를 `Please set up GitHub on https://claude.ai/code`로 끝냈으며, 설정 안내로는 일시적인 실패를 해결할 수 없습니다.

3967 4025 

3968### The repository upload can't follow a git setting4026### 저장소 업로드가 git 설정을 따를 수 없음

3969 4027 

3970[로컬 저장소를 업로드하는 클라우드 세션](https://code.claude.com/docs/ko/claude-code-on-the-web.md#send-local-repositories-without-github) 또는 브랜치의 [ultrareview](https://code.claude.com/docs/ko/ultrareview.md)를 시작했는데, 파일에 적용되는 attribute 규칙을 결정하는 git 설정 중 하나를 업로드가 따를 수 없습니다. 업로드를 그대로 진행하여 규칙을 놓치면, clean 필터가 암호화하는 파일처럼 git이 저장 전에 변환하는 파일이 디스크에 있는 그대로 클라우드에 전송될 수 있습니다. 그래서 Claude Code는 업로드를 거부하며, 아무것도 업로드되지 않습니다:4028[로컬 저장소를 업로드하는 클라우드 세션](https://code.claude.com/docs/ko/claude-code-on-the-web.md#send-local-repositories-without-github) 또는 브랜치의 [ultrareview](https://code.claude.com/docs/ko/ultrareview.md)를 시작했는데, 업로드가 파일에 적용될 attribute 규칙을 결정하는 git 설정 중 하나를 따를 수 없습니다. 업로드를 진행하면서 규칙을 놓치면, clean 필터가 암호화하는 파일처럼 git이 저장하기 전에 변환하는 파일이 디스크에 있는 그대로 클라우드에 전송될 수 있습니다. 따라서 Claude Code는 업로드를 거부하며, 아무것도 업로드되지 않습니다.

3971 4029 

3972```text theme={null}4030```text theme={null}

3973Not uploading this working tree: core.ignoreCase (which decides whether .gitattributes patterns match file names regardless of letter case) is set in <file>, and the upload cannot follow that setting, so a file git would change before storing it (to encrypt it, for example) could be uploaded as it is on disk. Move the core.ignoreCase line into this repository’s .git/config or directly into your ~/.gitconfig, then retry.4031Not uploading this working tree: core.ignoreCase (which decides whether .gitattributes patterns match file names regardless of letter case) is set in <file>, and the upload cannot follow that setting, so a file git would change before storing it (to encrypt it, for example) could be uploaded as it is on disk. Move the core.ignoreCase line into this repository’s .git/config or directly into your ~/.gitconfig, then retry.

3974```4032```

3975 4033 

3976메시지에는 해당 설정과 설정된 위치가 표시되며, 해당 사례에 맞는 해결 방법으로 끝납니다. `core.attributesFile`과 `attr.tree`에 대해서도 각각의 해결 방법과 함께 동일한 거부 메시지가 표시됩니다.4034메시지에는 해당 설정과 설정된 위치가 표시되며, 발생한 경우에 맞는 해결 방법으로 끝납니다. `core.attributesFile`과 `attr.tree`에 대해서도 각각의 해결 방법과 함께 같은 거부가 표시됩니다.

3977 4035 

3978메시지에는 git 구성이 `include` 또는 `includeIf` 지시문을 통해 불러오는 설정 파일이 표시될 수 있으며, 이는 해당 지시문의 조건이 이 저장소에 적용되지 않는 경우에도 마찬가지입니다.4036메시지에 표시되는 설정 파일은 git 구성이 `include` 또는 `includeIf` 지시문으로 가져오는 파일일 수 있으며, 해당 지시문의 조건이 이 저장소에 적용되지 않는 경우에도 마찬가지입니다.

3979 4037 

3980**해결 방법:**4038**해결 방법:**

3981 4039 

3983 4041 

3984### GitHub isn't connected to your Claude account4042### GitHub isn't connected to your Claude account

3985 4043 

3986예를 들어 `/autofix-pr`로 로컬 저장소에서 [클라우드 세션](https://code.claude.com/docs/ko/claude-code-on-the-web.md)을 시작했습니다. Claude 계정에 연결된 GitHub 계정이 없거나 연결이 만료되었으므로 Claude Code가 실행을 거부합니다:4044예를 들어 `/autofix-pr`로 로컬 저장소에서 [클라우드 세션](https://code.claude.com/docs/ko/claude-code-on-the-web.md)을 시작했습니다. Claude 계정에 연결된 GitHub 계정이 없거나 연결이 만료되었으므로 Claude Code가 실행을 거부합니다.

3987 4045 

3988```text theme={null}4046```text theme={null}

3989GitHub isn't connected to your Claude account, so this repository can't be cloned in the cloud. Run /web-setup to connect with your GitHub CLI login, or connect on the web at https://claude.ai/connect-github4047GitHub isn't connected to your Claude account, so this repository can't be cloned in the cloud. Run /web-setup to connect with your GitHub CLI login, or connect on the web at https://claude.ai/connect-github

3990```4048```

3991 4049 

3992[`/schedule`](https://code.claude.com/docs/ko/routines)로 클라우드 예약 작업을 만들 때는 동일한 메시지가 저장소 이름을 포함한 설정 안내로 표시되며, 이 안내는 작업 생성을 막지 않습니다.4050[`/schedule`](https://code.claude.com/docs/ko/routines)로 클라우드 예약 작업을 만들 때는 같은 메시지가 저장소 이름을 포함한 설정 안내로 표시되며, 이 안내는 작업 생성을 막지 않습니다.

3993 4051 

3994**해결 방법:**4052**해결 방법:**

3995 4053 

3996* `/web-setup`을 실행하여 GitHub CLI 로그인을 Claude 계정에 연결하거나, [claude.ai/connect-github](https://claude.ai/connect-github)에서 계정을 연결합니다. 두 방법의 차이는 [GitHub 인증 옵션](https://code.claude.com/docs/ko/claude-code-on-the-web.md#github-authentication-options)을 참조하십시오.4054* `/web-setup`을 실행하여 GitHub CLI 로그인을 Claude 계정에 연결하거나, [claude.ai/connect-github](https://claude.ai/connect-github)에서 계정을 연결합니다. 두 방법의 차이는 [GitHub 인증 옵션](https://code.claude.com/docs/ko/claude-code-on-the-web.md#github-authentication-options)을 참조하세요.

3997* 연결하고 1분 후에 명령을 다시 실행합니다4055* 연결하고 1분 정도 지난 후 명령을 다시 실행합니다

3998 4056 

3999v2.1.268 이전에는 Claude Code가 이를 Claude GitHub App 확인의 일시적인 실패로 보고하고 재시도나 앱 설치를 제안했지만, 어느 쪽도 GitHub 계정을 연결하지 않습니다.4057v2.1.268 이전에는 Claude Code가 이를 Claude GitHub App 확인의 일시적인 실패로 보고하고 재시도하거나 앱을 설치하도록 제안했지만, 어느 쪽도 GitHub 계정을 연결하지 않습니다.

4000 4058 

4001### A GitHub organization policy is blocking Claude4059### GitHub 조직 정책이 Claude를 차단함

4002 4060 

4003Claude Code 프롬프트에서 [`/autofix-pr`](https://code.claude.com/docs/ko/claude-code-on-the-web#auto-fix-pull-requests)처럼 클라우드 세션을 시작하는 명령을 실행했습니다. Claude Code는 세션을 만들기 전에 GitHub에서 Claude의 저장소 접근 권한을 확인하는데, GitHub 조직에 Claude를 차단하는 정책이 있어 GitHub가 이를 거부했습니다. Claude Code는 여기서 중단하고 해당 정책을 명시한 메시지를 표시합니다.4061Claude Code 프롬프트에서 [`/autofix-pr`](https://code.claude.com/docs/ko/claude-code-on-the-web#auto-fix-pull-requests)처럼 클라우드 세션을 시작하는 명령을 실행했습니다. Claude Code는 세션을 만들기 전에 GitHub에서 Claude의 저장소 접근 권한을 확인하는데, GitHub 조직에 Claude를 차단하는 정책이 있어 GitHub가 이를 거부했습니다. Claude Code는 여기서 중단하고 해당 정책을 명시한 메시지를 표시합니다.

4004 4062 

4005IP 허용 목록이 접근을 차단하는 경우 메시지는 다음과 같습니다:4063IP 허용 목록이 접근을 차단하는 경우 메시지는 다음과 같습니다.

4006 4064 

4007```text theme={null}4065```text theme={null}

4008Your GitHub organization has an IP allowlist that is blocking Claude. Add Claude's IP ranges to your GitHub allowlist.4066Your GitHub organization has an IP allowlist that is blocking Claude. Add Claude's IP ranges to your GitHub allowlist.

4009```4067```

4010 4068 

4011싱글 사인온이 차단하는 경우 메시지는 다음과 같습니다:4069싱글 사인온이 차단하는 경우 메시지는 다음과 같습니다.

4012 4070 

4013```text theme={null}4071```text theme={null}

4014Your GitHub organization requires single sign-on. Disconnect and reconnect GitHub on the Connectors page in Claude on the web, click Authorize next to your organization when GitHub asks, then try again.4072Your GitHub organization requires single sign-on. Disconnect and reconnect GitHub on the Connectors page in Claude on the web, click Authorize next to your organization when GitHub asks, then try again.

4015```4073```

4016 4074 

4017Microsoft Entra ID 조건부 액세스 정책이 차단하는 경우 메시지는 다음과 같습니다:4075Microsoft Entra ID 조건부 액세스 정책이 차단하는 경우 메시지는 다음과 같습니다.

4018 4076 

4019```text theme={null}4077```text theme={null}

4020Your GitHub organization's identity provider (Microsoft Entra ID) has a Conditional Access policy that is blocking Claude. Ask your GitHub Enterprise or Entra ID admin to allow Claude in that policy.4078Your GitHub organization's identity provider (Microsoft Entra ID) has a Conditional Access policy that is blocking Claude. Ask your GitHub Enterprise or Entra ID admin to allow Claude in that policy.

4022 4080 

4023**해결 방법:**4081**해결 방법:**

4024 4082 

4025* **IP 허용 목록**: GitHub 조직 또는 엔터프라이즈의 소유자에게 Anthropic의 아웃바운드 IP 주소를 허용하도록 요청합니다. 주소와 변경할 GitHub 설정은 [GitHub 허용 목록 및 방화벽](https://code.claude.com/docs/ko/network-config.md#github-allow-lists-and-firewalls)을 참조하십시오.4083* **IP 허용 목록**: GitHub 조직 또는 엔터프라이즈의 소유자에게 Anthropic의 아웃바운드 IP 주소를 허용하도록 요청합니다. 주소와 변경할 GitHub 설정은 [GitHub 허용 목록 및 방화벽](https://code.claude.com/docs/ko/network-config.md#github-allow-lists-and-firewalls)을 참조하세요.

4026* **싱글 사인온**: [claude.ai/customize/connectors](https://claude.ai/customize/connectors)에서 GitHub 연결을 해제한 다음 다시 연결합니다. GitHub가 요청하면 조직 옆의 **Authorize**를 클릭하여 새 연결이 해당 조직의 싱글 사인온에 대해 인가되도록 합니다.4084* **싱글 사인온**: [claude.ai/customize/connectors](https://claude.ai/customize/connectors)에서 GitHub 연결을 해제한 다음 다시 연결합니다. GitHub가 요청하면 조직 옆의 **Authorize**를 클릭하여 새 연결이 해당 조직의 싱글 사인온에 대해 인가되도록 합니다.

4027* **조건부 액세스 정책**: GitHub Enterprise 또는 Microsoft Entra ID 관리자에게 해당 정책에서 Claude를 허용하도록 요청합니다4085* **조건부 액세스 정책**: GitHub Enterprise 또는 Microsoft Entra ID 관리자에게 해당 정책에서 Claude를 허용하도록 요청합니다

4028* 변경한 후 명령을 다시 실행합니다4086* 변경한 후 명령을 다시 실행합니다

4029 4087 

4030### Single sign-on authorization needed4088### Single sign-on authorization needed

4031 4089 

4032[`/install-github-app`](https://code.claude.com/docs/ko/github-actions#quick-setup)을 실행하고 SAML 싱글 사인온을 적용하는 조직의 저장소를 선택했습니다. Claude Code는 설정 전에 GitHub CLI로 저장소에 대한 접근 권한을 확인하는데, `gh` 토큰이 아직 해당 조직에 대해 인가되지 않았기 때문에 GitHub가 이 확인을 거부했습니다. 마법사는 인가 단계와 함께 경고를 표시합니다:4090[`/install-github-app`](https://code.claude.com/docs/ko/github-actions#quick-setup)을 실행하고 SAML 싱글 사인온을 적용하는 조직의 저장소를 선택했습니다. 설정 전에 Claude Code는 GitHub CLI로 저장소 접근 권한을 확인하는데, `gh` 토큰이 아직 해당 조직에 대해 인가되지 않았기 때문에 GitHub가 이 확인을 거부했습니다. 마법사는 인가 절차와 함께 다음 경고를 표시합니다.

4033 4091 

4034```text theme={null}4092```text theme={null}

4035Single sign-on authorization needed4093Single sign-on authorization needed

4039**해결 방법:**4097**해결 방법:**

4040 4098 

4041* `gh auth refresh -h github.com -s repo,workflow`를 실행하여 `repo` 및 `workflow` 범위로 GitHub CLI 로그인을 다시 인가하고, GitHub가 싱글 사인온을 요청하면 조직을 인가합니다4099* `gh auth refresh -h github.com -s repo,workflow`를 실행하여 `repo` 및 `workflow` 범위로 GitHub CLI 로그인을 다시 인가하고, GitHub가 싱글 사인온을 요청하면 조직을 인가합니다

4042* `GH_TOKEN`의 개인 액세스 토큰으로 인증하는 경우 [github.com/settings/tokens](https://github.com/settings/tokens)를 열고 토큰에서 **Configure SSO**를 선택한 다음 조직을 인가합니다4100* `GH_TOKEN`에 개인 액세스 토큰을 사용해 인증하는 경우, [github.com/settings/tokens](https://github.com/settings/tokens)를 열고 해당 토큰에서 **Configure SSO**를 선택한 다음 조직을 인가합니다

4043* `/install-github-app`을 다시 실행합니다4101* `/install-github-app`을 다시 실행합니다

4044 4102 

4045v2.1.273 이전에는 이 상황에서 Claude Code가 대신 `Admin permissions required` 경고를 표시했습니다.4103v2.1.273 이전에는 이 상황에서 Claude Code가 대신 `Admin permissions required` 경고를 표시했습니다.

4046 4104 

4047### Failed to resume the conversation4105### Failed to resume the conversation

4048 4106 

4049Claude Code가 [`claude --resume` 선택기](https://code.claude.com/docs/ko/sessions#use-the-session-picker)에서 선택한 세션의 저장된 트랜스크립트를 읽거나 처리할 수 없어, 부분적으로 로드된 상태로 계속하는 대신 프로세스를 종료합니다. 메시지에는 재시도할 명령이 포함됩니다:4107Claude Code가 [`claude --resume` 선택기](https://code.claude.com/docs/ko/sessions#use-the-session-picker)에서 선택한 세션의 저장된 트랜스크립트를 읽거나 처리할 수 없으므로, 부분적으로 로드된 상태로 계속하는 대신 프로세스를 종료합니다. 메시지에는 재시도할 명령이 포함됩니다.

4050 4108 

4051```text theme={null}4109```text theme={null}

4052Failed to resume the conversation.4110Failed to resume the conversation.

4053Run claude --resume <session-id> to retry, or claude to start a new session.4111Run claude --resume <session-id> to retry, or claude to start a new session.

4054```4112```

4055 4113 

4056Claude Code는 메시지를 표시한 후 코드 1로 종료합니다. 실행 중인 세션 내의 `/resume` 선택기는 대신 대화에 `Failed to resume conversation`을 보고하며, 현재 세션은 계속 실행됩니다. v2.1.216 이전에는 `claude --resume` 선택기에서 재개가 실패하면 이 메시지를 표시하는 대신 `Resuming conversation…` 스피너에 무기한 머물렀습니다.4114Claude Code는 메시지를 표시한 후 코드 1로 종료합니다. 실행 중인 세션 내부의 `/resume` 선택기에서는 대신 대화에 `Failed to resume conversation`이 표시되며, 현재 세션은 계속 실행됩니다. v2.1.216 이전에는 `claude --resume` 선택기에서 재개에 실패하면 이 메시지를 표시하는 대신 `Resuming conversation…` 스피너가 무한히 표시되었습니다.

4057 4115 

4058**해결 방법:**4116**해결 방법:**

4059 4117 

4060* 메시지의 세션 ID로 `claude --resume <session-id>`를 실행하여 재시도합니다4118* 메시지에 있는 세션 ID로 `claude --resume <session-id>`를 실행하여 재시도합니다

4061* v2.1.285 이전 버전에서 재시도가 같은 방식으로 실패하면 `claude update`를 실행하고 다시 재개합니다. 해당 버전은 저장된 트랜스크립트에 읽을 수 없는 항목이 포함되어 있으면 재개에 실패합니다.4119* v2.1.285 이전 버전에서 재시도가 같은 방식으로 실패하면 `claude update`를 실행하고 다시 재개합니다. 해당 버전들은 저장된 트랜스크립트에 읽을 수 없는 항목이 있으면 재개에 실패합니다.

4062* 재시도가 다시 실패하면 `claude`를 실행하여 새 세션을 시작합니다4120* 재시도가 다시 실패하면 `claude`를 실행하여 새 세션을 시작합니다

4063 4121 

4064### No conversation found with the session ID4122### No conversation found with the session ID

4065 4123 

4066`claude --resume <session-id>`에 세션 ID를 전달했지만 일치하는 저장된 트랜스크립트가 없습니다:4124`claude --resume <session-id>`에 세션 ID를 전달했지만 일치하는 저장된 트랜스크립트가 없습니다.

4067 4125 

4068```text theme={null}4126```text theme={null}

4069No conversation found with session ID: <session-id>4127No conversation found with session ID: <session-id>

4070```4128```

4071 4129 

4072Claude Code는 메시지를 표시한 후 코드 1로 종료합니다. Claude Code는 [현재 프로젝트를 먼저 검색한 다음 이 머신의 다른 모든 프로젝트](https://code.claude.com/docs/ko/sessions.md#where-the-session-picker-looks)에서 ID를 검색합니다. v2.1.223 이전에는 현재 프로젝트 디렉터리와 해당 git worktree에서만 검색했으므로, 세션이 마지막으로 작업한 디렉터리에서 재개해야 했습니다.4130Claude Code는 메시지를 표시한 후 코드 1로 종료합니다. Claude Code는 [현재 프로젝트를 먼저 검색한 다음, 이 머신의 다른 모든 프로젝트](https://code.claude.com/docs/ko/sessions.md#where-the-session-picker-looks)에서 해당 ID를 검색합니다. v2.1.223 이전에는 현재 프로젝트 디렉터리와 그 git worktree까지만 검색했으므로, 세션이 마지막으로 작업한 디렉터리에서 재개해야 했습니다.

4073 4131 

4074일반적인 원인:4132일반적인 원인:

4075 4133 

4076* **잘못 입력한 ID**: 비대화형 실행의 경우 ID는 [`--output-format json` 출력](https://code.claude.com/docs/ko/headless#get-structured-output)의 `session_id` 필드입니다4134* **잘못 입력한 ID**: 비대화형 실행의 경우 ID는 [`--output-format json` 출력](https://code.claude.com/docs/ko/headless#get-structured-output)의 `session_id` 필드입니다

4077* **삭제된 트랜스크립트**: Claude Code는 [보존 정리 규칙](https://code.claude.com/docs/ko/claude-directory.md#cleaned-up-automatically)에 따라 [보존 기간](https://code.claude.com/docs/ko/sessions.md#where-transcripts-are-stored)(기본값 30일)이 지나면 트랜스크립트를 제거합니다4135* **삭제된 트랜스크립트**: Claude Code는 [보존 정리 규칙](https://code.claude.com/docs/ko/claude-directory.md#cleaned-up-automatically)에 따라 [보존 기간](https://code.claude.com/docs/ko/sessions.md#where-transcripts-are-stored)(기본값 30일)이 지난 트랜스크립트를 제거합니다

4078* **다른 머신**: Claude Code는 트랜스크립트를 로컬에 저장하므로, 세션이 실행된 머신에서 재개해야 합니다4136* **다른 머신**: Claude Code는 트랜스크립트를 로컬에 저장하므로, 세션이 실행된 머신에서 재개해야 합니다

4079* **중복 사본**: `~/.claude/projects` 아래의 프로젝트 디렉터리를 복사하여 두 트랜스크립트가 같은 ID를 가지게 된 경우, Claude Code는 임의로 한 사본을 재개하지 않고 이 메시지를 보고합니다4137* **중복 사본**: `~/.claude/projects` 아래의 프로젝트 디렉터리를 복사하여 두 트랜스크립트가 같은 ID를 갖게 된 경우, Claude Code는 임의로 한 사본을 재개하는 대신 이 메시지를 표시합니다

4080 4138 

4081**해결 방법:**4139**해결 방법:**

4082 4140 

4085 4143 

4086### Windows reported an error (EBADF) when Claude Code read this session's transcript file4144### Windows reported an error (EBADF) when Claude Code read this session's transcript file

4087 4145 

4088Windows에서 세션을 재개했는데, 저장된 [트랜스크립트 파일](https://code.claude.com/docs/ko/sessions.md#where-transcripts-are-stored)이 정상적으로 열린 후 읽기가 시스템 오류 EBADF로 실패했습니다. 시스템 오류는 읽기가 실패한 이유를 알려주지 않으므로, 메시지는 가능성 있는 원인과 시도해 볼 방법을 제안합니다:4146Windows에서 세션을 재개했는데, 저장된 [트랜스크립트 파일](https://code.claude.com/docs/ko/sessions.md#where-transcripts-are-stored)은 정상적으로 열렸지만 이후 읽기가 시스템 오류 EBADF로 실패했습니다. 시스템 오류만으로는 읽기가 실패한 이유를 알 수 없으므로, 메시지는 가능성 있는 원인과 시도해 볼 방법을 제안합니다.

4089 4147 

4090```text theme={null}4148```text theme={null}

4091Windows reported an error (EBADF) when Claude Code read this session's transcript file, although the file had opened normally. This can happen when other software intercepts file reads — security, encryption or endpoint-management tools, for example. If it keeps happening for this conversation, try excluding the folder that holds Claude Code's session transcripts from such software (the .claude folder in your user profile, unless the app or CLAUDE_CONFIG_DIR points Claude Code elsewhere), or adding Claude Code to its allowed applications, then resume again.4149Windows reported an error (EBADF) when Claude Code read this session's transcript file, although the file had opened normally. This can happen when other software intercepts file reads — security, encryption or endpoint-management tools, for example. If it keeps happening for this conversation, try excluding the folder that holds Claude Code's session transcripts from such software (the .claude folder in your user profile, unless the app or CLAUDE_CONFIG_DIR points Claude Code elsewhere), or adding Claude Code to its allowed applications, then resume again.

4092```4150```

4093 4151 

4094이 메시지는 `Failed to resume session <session-id>`와 같은 명령 자체의 실패 줄 뒤에 표시됩니다. `claude --resume` 또는 [`claude -p`](https://code.claude.com/docs/ko/headless) 명령은 메시지를 표시한 후 코드 1로 종료합니다. 세션 내에서 `/resume`을 실행한 경우에는 현재 세션이 계속 실행됩니다.4152이 메시지는 `Failed to resume session <session-id>`처럼 명령 자체의 실패 줄 다음에 표시됩니다. `claude --resume` 또는 [`claude -p`](https://code.claude.com/docs/ko/headless) 명령은 메시지를 표시한 후 코드 1로 종료합니다. 세션 내부에서 `/resume`을 실행한 경우에는 현재 세션이 계속 실행됩니다.

4095 4153 

4096**해결 방법:**4154**해결 방법:**

4097 4155 

4098* 보안, 암호화, 엔드포인트 관리 도구처럼 파일 읽기를 검사하거나 가로채는 소프트웨어에서 세션 트랜스크립트가 저장된 폴더를 제외합니다. 트랜스크립트는 기본적으로 `%USERPROFILE%\.claude\projects` 아래에 있거나, [`CLAUDE_CONFIG_DIR`](https://code.claude.com/docs/ko/env-vars)가 지정하는 디렉터리 아래에 있습니다4156* 보안, 암호화, 엔드포인트 관리 도구처럼 파일 읽기를 검사하거나 가로채는 소프트웨어에서 세션 트랜스크립트가 있는 폴더를 제외합니다. 트랜스크립트는 기본적으로 `%USERPROFILE%\.claude\projects` 아래에 있으며, [`CLAUDE_CONFIG_DIR`](https://code.claude.com/docs/ko/env-vars)이 지정된 경우 해당 디렉터리 아래에 있습니다

4099* 제외 항목을 추가할 수 없다면, 대신 해당 소프트웨어의 허용된 애플리케이션에 Claude Code를 추가합니다4157* 제외 항목을 추가할 수 없다면 대신 해당 소프트웨어의 허용된 애플리케이션에 Claude Code를 추가합니다

4100* 세션을 다시 재개합니다4158* 세션을 다시 재개합니다

4101 4159 

4102v2.1.282 이전에는 실패에 대한 설명이 없었습니다. `claude --resume <session-id>`는 `Failed to resume session <session-id>`에서 끝났고, `-p` 실행은 `Failed to resume session: EBADF: bad file descriptor, read`와 같은 시스템 오류 텍스트만 출력했습니다.4160v2.1.282 이전에는 실패에 대한 설명이 없었습니다. `claude --resume <session-id>`는 `Failed to resume session <session-id>`에서 끝났고, `-p` 실행은 `Failed to resume session: EBADF: bad file descriptor, read`처럼 시스템 오류 텍스트만 출력했습니다.

4103 4161 

4104### Cannot switch renderers in this session4162### Cannot switch renderers in this session

4105 4163 

4106렌더러를 전환하면 Claude Code는 프로세스를 다시 시작합니다. Claude Code가 다시 시작하기를 거부하는 세션에서 [`/tui`](https://code.claude.com/docs/ko/fullscreen#enable-fullscreen-rendering)를 실행했으므로, 전환하지 않으며 아무것도 저장하지 않습니다. 표시되는 메시지로 원인을 알 수 있습니다:4164렌더러를 전환하면 Claude Code가 프로세스를 다시 시작합니다. Claude Code가 다시 시작하지 않기로 한 세션에서 [`/tui`](https://code.claude.com/docs/ko/fullscreen#enable-fullscreen-rendering)를 실행했으므로, 전환하지 않고 아무것도 저장하지 않습니다. 표시되는 메시지로 원인을 알 수 있습니다.

4107 4165 

4108* `Cannot switch renderers while work is running in the background`: 백그라운드 셸이나 서브에이전트처럼 다시 시작하면 중단될 백그라운드 작업이 실행 중입니다. 작업이 끝날 때까지 기다리거나 [`/tasks`](https://code.claude.com/docs/ko/commands)로 중지한 다음 `/tui fullscreen` 또는 `/tui default`를 다시 실행합니다4166* `Cannot switch renderers while work is running in the background`: 백그라운드 셸이나 서브에이전트처럼 다시 시작하면 중단될 백그라운드 작업이 실행 중입니다. 작업이 끝날 때까지 기다리거나 [`/tasks`](https://code.claude.com/docs/ko/commands)로 작업을 중지한 다음 `/tui fullscreen` 또는 `/tui default`를 다시 실행합니다

4109* `Cannot switch renderers in this session`: 세션에 Claude Code가 다시 시작된 프로세스로 전달할 수 없는 제한이 있습니다. v2.1.234 이전에는 Claude Code가 그래도 다시 시작했고, 다시 실행된 세션은 해당 제한 없이 실행되었습니다4167* `Cannot switch renderers in this session`: 세션에 Claude Code가 다시 시작된 프로세스로 전달할 수 없는 제한이 있습니다. v2.1.234 이전에는 Claude Code가 그래도 다시 시작했고, 다시 실행된 세션은 해당 제한 없이 실행되었습니다

4110 4168 

4111제한 관련 메시지에서 괄호 안의 부분은 Claude Code가 발견한 제한을 나타냅니다:4169제한 관련 메시지에서 괄호 안의 부분은 Claude Code가 발견한 제한을 나타냅니다.

4112 4170 

4113```text theme={null}4171```text theme={null}

4114Cannot switch renderers in this session — it has restrictions a restart can't carry over (permission rules set for this session only). Nothing was changed. Running /tui fullscreen in a session started without them switches every later session too.4172Cannot switch renderers in this session — it has restrictions a restart can't carry over (permission rules set for this session only). Nothing was changed. Running /tui fullscreen in a session started without them switches every later session too.

4115```4173```

4116 4174 

4117메시지의 괄호 안에 표시될 수 있는 각 이유:4175메시지의 괄호 안에 표시될 수 있는 각 이유는 다음과 같습니다.

4118 4176 

4119* `launch flags: a custom system prompt, a tool allowlist, or restricted settings`: Claude Code가 다시 시작된 프로세스로 다시 전달하지 않는 플래그로 세션을 시작했습니다. 이러한 플래그에는 [`--system-prompt`](https://code.claude.com/docs/ko/cli-reference#cli-flags), `--system-prompt-file`, `--append-system-prompt-file`, [`--tools`](https://code.claude.com/docs/ko/cli-reference#cli-flags) 허용 목록, [`--setting-sources`](https://code.claude.com/docs/ko/cli-reference#cli-flags), [`--permission-prompt-tool`](https://code.claude.com/docs/ko/cli-reference#cli-flags)이 포함됩니다4177* `launch flags: a custom system prompt, a tool allowlist, or restricted settings`: Claude Code가 다시 시작된 프로세스로 전달하지 않는 플래그로 세션을 시작했습니다. 이러한 플래그에는 [`--system-prompt`](https://code.claude.com/docs/ko/cli-reference#cli-flags), `--system-prompt-file`, `--append-system-prompt-file`, [`--tools`](https://code.claude.com/docs/ko/cli-reference#cli-flags) 허용 목록, [`--setting-sources`](https://code.claude.com/docs/ko/cli-reference#cli-flags), [`--permission-prompt-tool`](https://code.claude.com/docs/ko/cli-reference#cli-flags)이 포함됩니다

4120* `permission rules set for this session only`: 훅이나 SDK 호출자의 [권한 업데이트](https://code.claude.com/docs/ko/hooks.md#permission-update-entries)가 `session` 대상으로 거부 또는 확인 규칙을 추가했습니다. 세션 범위의 허용 규칙은 거부를 유발하지 않습니다. 다시 시작하면 허용 규칙이 사라지고, Claude Code가 대신 다시 확인을 요청합니다4178* `permission rules set for this session only`: 훅 또는 SDK 호출자의 [권한 업데이트](https://code.claude.com/docs/ko/hooks.md#permission-update-entries)가 `session` 대상으로 거부 또는 확인 규칙을 추가했습니다. 세션 범위의 허용 규칙은 거부를 유발하지 않습니다. 다시 시작하면 허용 규칙은 삭제되고, Claude Code가 대신 다시 확인을 요청합니다

4121* `ask-before-running rules with no command-line form`: 훅이나 SDK 호출자의 권한 업데이트가 Claude Code가 `--allowed-tools` 및 `--disallowed-tools`로 다시 전달하는 규칙과 함께 확인 규칙을 추가했습니다. 확인 규칙에 해당하는 플래그는 없습니다4179* `ask-before-running rules with no command-line form`: 훅 또는 SDK 호출자의 권한 업데이트가 Claude Code가 `--allowed-tools` 및 `--disallowed-tools`로 다시 전달하는 규칙과 함께 확인 규칙을 추가했습니다. 확인 규칙에 해당하는 플래그는 없습니다

4122* `permission rules a command line cannot carry intact` 및 `added directories a command line cannot carry intact`: 권한 업데이트가 세션 도중에 규칙 또는 디렉터리 경로를 추가했습니다. 다시 시작된 프로세스의 명령줄은 해당 텍스트를 같은 값으로 전달할 수 없습니다4180* `permission rules a command line cannot carry intact` 및 `added directories a command line cannot carry intact`: 권한 업데이트가 세션 도중에 규칙 또는 디렉터리 경로를 추가했습니다. 다시 시작된 프로세스의 명령줄은 해당 텍스트를 동일한 값으로 전달할 수 없습니다

4123 4181 

4124**해결 방법:**4182**해결 방법:**

4125 4183 

4126* 이러한 제한 없이 시작된 세션에서 `/tui fullscreen`을 실행하거나, 다시 전환하려면 `/tui default`를 실행합니다. Claude Code는 해당 세션에서 [`tui` 설정](https://code.claude.com/docs/ko/settings-reference#tui)을 저장합니다4184* 해당 제한 없이 시작한 세션에서 `/tui fullscreen`을 실행하거나, 되돌리려면 `/tui default`를 실행합니다. Claude Code는 그 세션에서 [`tui` 설정](https://code.claude.com/docs/ko/settings-reference#tui)을 저장합니다

4127 4185 

4128### Can't restart while work is running or Remote Control is connected4186### Can't restart while work is running or Remote Control is connected

4129 4187 

4130Claude Code가 다시 시작되지 않았으며, 세션은 그대로 계속 실행됩니다. 메시지에 있는 해결 방법을 따르십시오.4188Claude Code가 다시 시작되지 않았으며, 세션은 그대로 계속 실행됩니다. 메시지에 있는 해결 방법을 따릅니다.

4131 4189 

4132### Claude Code couldn't restart4190### Claude Code couldn't restart

4133 4191 

4134이 메시지에 대화가 저장되었다고 표시되면, 대화는 디스크에 있으며 중단된 지점부터 이어서 진행할 수 있습니다. Claude Code가 예를 들어 [`/tui`](https://code.claude.com/docs/ko/fullscreen#enable-fullscreen-rendering)를 실행한 후 전체 화면 렌더링으로 전환하거나 해제하기 위해 스스로 다시 시작하던 중 새 프로세스를 시작하지 못하여 상태 1로 종료했습니다:4192이 메시지에 대화가 저장되었다고 표시되면, 대화는 디스크에 있으며 중단된 지점부터 이어서 진행할 수 있습니다. Claude Code가 예를 들어 [`/tui`](https://code.claude.com/docs/ko/fullscreen#enable-fullscreen-rendering) 실행 후 전체 화면 렌더링으로 전환하거나 전환을 해제하기 위해 스스로 다시 시작하던 중 새 프로세스를 시작하지 못해 상태 1로 종료했습니다.

4135 4193 

4136```text theme={null}4194```text theme={null}

4137Claude Code couldn't restart. Your conversation is saved. Start Claude Code again and run /resume to pick it up.4195Claude Code couldn't restart. Your conversation is saved. Start Claude Code again and run /resume to pick it up.

4138```4196```

4139 4197 

4140예를 들어 `/tui`가 새 세션의 첫 입력이었기 때문에 다시 시작할 때 다시 열 대화가 없었던 경우, 메시지는 `Claude Code couldn't restart. Start Claude Code again.`입니다.4198예를 들어 `/tui`가 새 세션의 첫 입력이어서 다시 시작할 때 다시 열 대화가 없었던 경우, 메시지는 `Claude Code couldn't restart. Start Claude Code again.`입니다.

4141 4199 

4142**해결 방법:**4200**해결 방법:**

4143 4201 

4144* 셸에서 `claude`를 다시 실행합니다. 메시지에 대화가 저장되었다고 표시되었다면, 새 세션에서 [`/resume`](https://code.claude.com/docs/ko/sessions#resume-a-session)을 실행하고 대화를 선택합니다. 목록에 없다면 [세션 선택기의 범위를 넓힙니다](https://code.claude.com/docs/ko/sessions.md#where-the-session-picker-looks)4202* 셸에서 `claude`를 다시 실행합니다. 메시지에 대화가 저장되었다고 표시되었다면 새 세션에서 [`/resume`](https://code.claude.com/docs/ko/sessions#resume-a-session)을 실행하고 대화를 선택합니다. 목록에 없다면 [세션 선택기의 범위를 넓힙니다](https://code.claude.com/docs/ko/sessions.md#where-the-session-picker-looks)

4145* 다시 시작이 계속 실패하면 셸에서 [`claude --debug-file claude-debug.log`](https://code.claude.com/docs/ko/cli-reference#cli-flags)로 Claude Code를 시작합니다. 해당 세션에서 다시 시작이 실패하면, 시작한 디렉터리의 `claude-debug.log`에 운영 체제의 오류가 포함된 `Failed to relaunch:` 줄이 기록됩니다. [문제를 보고](#report-an-error)할 때 해당 줄을 포함하십시오4203* 다시 시작이 계속 실패하면 셸에서 [`claude --debug-file claude-debug.log`](https://code.claude.com/docs/ko/cli-reference#cli-flags)로 Claude Code를 시작합니다. 해당 세션에서 다시 시작이 실패하면, 시작한 디렉터리의 `claude-debug.log`에 운영 체제의 오류와 함께 `Failed to relaunch:` 줄이 기록됩니다. [문제를 보고](#report-an-error)할 때 해당 줄을 포함합니다

4146 4204 

4147### Couldn't open Claude Desktop4205### Couldn't open Claude Desktop

4148 4206 

4149세션에서 [`/desktop`](https://code.claude.com/docs/ko/desktop#coming-from-the-cli) 또는 그 별칭인 `/app`을 실행했거나 셸에서 [`claude --desktop`](https://code.claude.com/docs/ko/cli-reference#cli-flags)을 실행했는데, Claude Code가 Claude Desktop을 여는 데 사용하는 시스템 명령이 실패했습니다. `/desktop` 후에는 세션이 터미널에 그대로 유지됩니다. `claude --desktop`은 `Error:` 접두사 없이 메시지를 출력하고 상태 1로 종료합니다.4207세션에서 [`/desktop`](https://code.claude.com/docs/ko/desktop#coming-from-the-cli) 또는 그 별칭인 `/app`을 실행했거나 셸에서 [`claude --desktop`](https://code.claude.com/docs/ko/cli-reference#cli-flags)을 실행했는데, Claude Code가 Claude Desktop을 여는 데 사용하는 시스템 명령이 실패했습니다. `/desktop` 실행 후에는 세션이 터미널에 그대로 남으며, `claude --desktop`은 `Error:` 접두사 없이 메시지를 출력하고 상태 1로 종료합니다.

4150 4208 

4151괄호 안의 텍스트는 실패한 명령을 나타내며, 종료 상태와 오류 출력의 첫 줄이 있는 경우 함께 표시됩니다. macOS에서는 이 예시처럼 해당 명령이 `open`이며, Windows에서는 `rundll32`입니다:4209괄호 안의 텍스트는 실패한 명령을 나타내며, 종료 상태와 오류 출력의 첫 줄이 있는 경우 함께 표시됩니다. macOS에서는 이 예시처럼 해당 명령이 `open`이며, Windows에서는 `rundll32`입니다.

4152 4210 

4153```text theme={null}4211```text theme={null}

4154Error: Couldn't open Claude Desktop (`open` exited 1: LSOpenURLsWithRole() failed for the URL claude://resume?session=<session-id> with error -10814). Open Claude Desktop and try again.4212Error: Couldn't open Claude Desktop (`open` exited 1: LSOpenURLsWithRole() failed for the URL claude://resume?session=<session-id> with error -10814). Open Claude Desktop and try again.

4161 4219 

4162v2.1.285 이전에는 메시지가 `Open Claude Desktop and run /desktop again.`으로 끝났습니다. v2.1.275 이전에는 메시지가 `Failed to open Claude Desktop. Please try opening it manually.`였으며 무엇이 실패했는지 알려주지 않았습니다.4220v2.1.285 이전에는 메시지가 `Open Claude Desktop and run /desktop again.`으로 끝났습니다. v2.1.275 이전에는 메시지가 `Failed to open Claude Desktop. Please try opening it manually.`였으며 무엇이 실패했는지 알려주지 않았습니다.

4163 4221 

4164### /terminal-setup left your Zed keymap unchanged4222### /terminal-setup이 Zed 키맵을 변경하지 않음

4165 4223 

4166Zed에서 [`/terminal-setup`](https://code.claude.com/docs/ko/terminal-config#enter-multiline-prompts)을 실행했는데, Claude Code가 Zed `keymap.json` 업데이트를 완료할 수 없어 파일을 그대로 두었습니다.4224Zed에서 [`/terminal-setup`](https://code.claude.com/docs/ko/terminal-config#enter-multiline-prompts)을 실행했는데, Claude Code가 Zed `keymap.json` 업데이트를 완료하지 못해 파일을 그대로 두었습니다.

4167 4225 

4168각 메시지에는 키맵 경로가 표시되며, 직접 추가할 키보드 단축키 블록으로 끝납니다:4226각 메시지에는 키맵 경로가 표시되며, 직접 추가할 키보드 단축키 블록으로 끝납니다.

4169 4227 

4170```text theme={null}4228```text theme={null}

4171Couldn't update your Zed keymap, so it was left unchanged.4229Couldn't update your Zed keymap, so it was left unchanged.

4173{ "context": "Terminal", "bindings": { "shift-enter": ["terminal::SendText", "\u001b\r"] } }4231{ "context": "Terminal", "bindings": { "shift-enter": ["terminal::SendText", "\u001b\r"] } }

4174```4232```

4175 4233 

4176메시지의 첫 줄에 원인이 표시됩니다:4234메시지의 첫 줄은 원인을 나타냅니다.

4177 4235 

4178* `Couldn't read your Zed keymap, so it was left unchanged.`: 파일 권한 등의 이유로 Claude Code가 파일을 읽을 수 없었습니다4236* `Couldn't read your Zed keymap, so it was left unchanged.`: 파일 권한 등의 이유로 Claude Code가 파일을 읽을 수 없었습니다

4179* `Your Zed keymap isn't a readable list of keybindings, so it was left unchanged.`: 파일은 정상적으로 읽었지만, `//` 주석과 후행 쉼표를 허용하더라도 키보드 단축키 블록의 배열로 파싱되지 않습니다4237* `Your Zed keymap isn't a readable list of keybindings, so it was left unchanged.`: 파일은 정상적으로 읽었지만, `//` 주석과 후행 쉼표를 허용하더라도 키보드 단축키 블록의 배열로 파싱되지 않습니다

4180* `Couldn't back up your Zed keymap; not modifying it.`: Claude Code가 파일을 옆에 있는 `.bak` 백업으로 복사할 수 없었으므로 아무것도 변경하지 않았습니다4238* `Couldn't back up your Zed keymap; not modifying it.`: Claude Code가 파일을 옆에 `.bak` 백업으로 복사할 수 없어 아무것도 변경하지 않았습니다

4181* `Couldn't update your Zed keymap, so it was left unchanged.`: 병합된 결과가 해당 단축키를 포함한 유효한 키맵으로 확인되지 않아, Claude Code가 쓰지 않고 폐기했습니다. 중복된 키가 있는 키보드 단축키 블록이 원인일 수 있습니다4239* `Couldn't update your Zed keymap, so it was left unchanged.`: 병합된 결과가 해당 단축키를 포함한 유효한 키맵으로 검증되지 않아, Claude Code가 쓰지 않고 폐기했습니다. 키가 중복된 키보드 단축키 블록이 원인일 수 있습니다

4182 4240 

4183**해결 방법:**4241**해결 방법:**

4184 4242 

4185* 메시지에 있는 블록을 복사하여 메시지에 표시된 경로의 `keymap.json` 최상위 배열에 추가합니다4243* 메시지의 블록을 복사하여 메시지에 표시된 경로의 `keymap.json` 최상위 배열에 넣습니다

4186* `isn't a readable list of keybindings`의 경우 구문 오류를 수정하거나 파일의 최상위 값을 배열로 만든 다음 `/terminal-setup`을 다시 실행합니다4244* `isn't a readable list of keybindings`의 경우 구문 오류를 수정하거나 파일의 최상위 값을 배열로 만든 다음 `/terminal-setup`을 다시 실행합니다

4187 4245 

4188v2.1.247 이전에는 `/terminal-setup`이 `//` 주석이나 후행 쉼표를 사용하는 Zed 키맵을 파싱할 수 없었으며, 전체 파일을 자체 단축키만 포함하도록 교체하면서 단축키가 설치되었다고 보고했습니다. 이전 버전이 교체한 키맵을 복원하려면 [여러 줄 프롬프트 입력](https://code.claude.com/docs/ko/terminal-config.md#enter-multiline-prompts)에 설명된 `.bak` 백업 파일을 사용하십시오.4246v2.1.247 이전에는 `/terminal-setup`이 `//` 주석이나 후행 쉼표를 사용하는 Zed 키맵을 파싱할 수 없었으며, 단축키가 설치되었다고 보고하면서 전체 파일을 자체 단축키만으로 교체했습니다. 이전 버전이 교체한 키맵을 복원하려면 [여러 줄 프롬프트 입력](https://code.claude.com/docs/ko/terminal-config.md#enter-multiline-prompts)에 설명된 `.bak` 백업 파일을 사용합니다.

4189 4247 

4190### Skill usage reports are not available on this connection4248### Skill usage reports are not available on this connection

4191 4249 

4192휴대폰이나 브라우저에서 [Remote Control](https://code.claude.com/docs/ko/remote-control.md)을 통해 [`/skill-doctor`](https://code.claude.com/docs/ko/skills#find-unused-skills)를 실행했습니다. Claude Code는 Remote Control을 통해 스킬 사용 보고서를 보내지 않으며, 대신 다음 메시지로 응답합니다:4250휴대폰이나 브라우저에서 [Remote Control](https://code.claude.com/docs/ko/remote-control.md)을 통해 [`/skill-doctor`](https://code.claude.com/docs/ko/skills#find-unused-skills)를 실행했습니다. Claude Code는 Remote Control을 통해 스킬 사용 보고서를 보내지 않으며, 대신 다음 메시지로 응답합니다.

4193 4251 

4194```text theme={null}4252```text theme={null}

4195Skill usage reports are not available on this connection.4253Skill usage reports are not available on this connection.

4201 4259 

4202### Custom output styles can't be selected over Remote Control4260### Custom output styles can't be selected over Remote Control

4203 4261 

4204[Remote Control](https://code.claude.com/docs/ko/remote-control.md)을 통해 모바일 앱이나 웹에서 [`/output-style`](https://code.claude.com/docs/ko/output-styles#change-your-output-style)을 실행했거나, 세션으로 전달된 메시지에 해당 명령이 포함되어 있었습니다. 이러한 턴은 계정 소유자에게서 온 것이 아닐 수 있으므로, Claude Code는 해당 턴에서 [기본 제공 스타일](https://code.claude.com/docs/ko/output-styles.md#built-in-output-styles)만 나열하고 선택하며, 명령이 스타일을 나열하거나 입력한 이름을 인식하지 못할 때마다 이 안내를 추가합니다. [사용자 지정 스타일](https://code.claude.com/docs/ko/output-styles.md#create-a-custom-output-style) 이름에는 존재하지 않는 이름과 같은 응답이 표시됩니다:4262[Remote Control](https://code.claude.com/docs/ko/remote-control.md)을 통해 모바일 앱이나 웹에서 [`/output-style`](https://code.claude.com/docs/ko/output-styles#change-your-output-style)을 실행했거나, 세션으로 릴레이된 메시지에 명령이 포함되어 있었습니다. 이러한 턴은 계정 소유자가 보낸 것이 아닐 수 있으므로, Claude Code는 해당 턴에서 [기본 제공 스타일](https://code.claude.com/docs/ko/output-styles.md#built-in-output-styles)만 나열하고 선택하며, 명령이 스타일을 나열하거나 지정한 이름을 인식하지 못할 때마다 이 안내를 덧붙입니다. [사용자 지정 스타일](https://code.claude.com/docs/ko/output-styles.md#create-a-custom-output-style) 이름에는 존재하지 않는 이름과 같은 응답이 표시됩니다.

4205 4263 

4206```text theme={null}4264```text theme={null}

4207Custom output styles can't be selected over Remote Control or from a relayed message. Select one in the session itself, or pick a built-in style here.4265Custom output styles can't be selected over Remote Control or from a relayed message. Select one in the session itself, or pick a built-in style here.

4209 4267 

4210**해결 방법:**4268**해결 방법:**

4211 4269 

4212* 기본 제공 스타일을 선택합니다. 예: `/output-style concise`4270* `/output-style concise`처럼 기본 제공 스타일을 선택합니다

4213* 사용자 지정 스타일을 사용하려면 프로젝트의 `.claude/settings.local.json`에서 [`outputStyle`](https://code.claude.com/docs/ko/settings-reference#outputstyle)을 설정하거나, 세션 자체 터미널이 있는 경우 해당 터미널에서 `/output-style <style>`을 실행합니다4271* 사용자 지정 스타일을 사용하려면 프로젝트의 `.claude/settings.local.json`에서 [`outputStyle`](https://code.claude.com/docs/ko/settings-reference#outputstyle)을 설정하거나, 세션 자체의 터미널이 있다면 그곳에서 `/output-style <style>`을 실행합니다

4214 4272 

4215### Output styles are saved to local settings which this session doesn't load4273### Output styles are saved to local settings which this session doesn't load

4216 4274 

4217설정 소스에서 `local`이 제외된 세션에서 `/output-style <style>` 또는 `/config outputStyle=<style>`로 [출력 스타일](https://code.claude.com/docs/ko/output-styles.md)을 전환하려고 했습니다. 예를 들어 [`settingSources`](https://code.claude.com/docs/ko/agent-sdk/typescript#options)에서 `"local"`이 빠진 [Agent SDK](https://code.claude.com/docs/ko/agent-sdk/typescript.md) 세션이나, `local`이 빠진 [`--setting-sources`](https://code.claude.com/docs/ko/cli-reference#cli-flags) 값으로 시작한 CLI 세션이 있습니다. 두 명령 모두 스타일을 `.claude/settings.local.json`에 저장하는데, 이러한 세션은 이 파일을 다시 읽지 않으므로 Claude Code는 효과가 없을 설정을 쓰는 대신 거부합니다:4275설정 소스에서 `local`을 제외한 세션에서 `/output-style <style>` 또는 `/config outputStyle=<style>`로 [출력 스타일](https://code.claude.com/docs/ko/output-styles.md)을 전환하려고 했습니다. 예를 들어 [`settingSources`](https://code.claude.com/docs/ko/agent-sdk/typescript#options)에서 `"local"`을 제외한 [Agent SDK](https://code.claude.com/docs/ko/agent-sdk/typescript.md) 세션이나, `local`을 제외한 [`--setting-sources`](https://code.claude.com/docs/ko/cli-reference#cli-flags) 값으로 시작한 CLI 세션이 있습니다. 두 명령 모두 스타일을 `.claude/settings.local.json`에 저장하는데, 이러한 세션은 이 파일을 다시 읽지 않으므로 Claude Code는 아무 효과가 없을 설정을 쓰는 대신 거부합니다.

4218 4276 

4219```text theme={null}4277```text theme={null}

4220Output styles are saved to local settings (.claude/settings.local.json), which this session doesn't load, so the style can't be changed here.4278Output styles are saved to local settings (.claude/settings.local.json), which this session doesn't load, so the style can't be changed here.

4223**해결 방법:**4281**해결 방법:**

4224 4282 

4225* 세션의 설정 소스에 `local`을 추가하고 다시 전환합니다4283* 세션의 설정 소스에 `local`을 추가하고 다시 전환합니다

4226* 프로젝트의 `.claude/settings.json`이나 `~/.claude/settings.json`처럼 세션이 로드하는 설정 파일에서 [`outputStyle`](https://code.claude.com/docs/ko/settings-reference#outputstyle) 키를 설정합니다. TypeScript SDK에서는 대신 인라인 `settings` 객체 안에서 `outputStyle`을 설정합니다. [출력 스타일 활성화](https://code.claude.com/docs/ko/agent-sdk/modifying-system-prompts.md#activate-an-output-style)를 참조하십시오4284* 프로젝트의 `.claude/settings.json` 또는 `~/.claude/settings.json`처럼 세션이 로드하는 설정 파일에서 [`outputStyle`](https://code.claude.com/docs/ko/settings-reference#outputstyle) 키를 설정합니다. TypeScript SDK에서는 대신 인라인 `settings` 객체 안에 `outputStyle`을 설정합니다. [출력 스타일 활성화](https://code.claude.com/docs/ko/agent-sdk/modifying-system-prompts.md#activate-an-output-style)를 참조하세요

4227 4285 

4228### /recap only runs when you ask for it yourself4286### /recap only runs when you ask for it yourself

4229 4287 

4230[`/recap`](https://code.claude.com/docs/ko/interactive-mode#session-recap) 요청이 사용자 자신의 입력에서 온 것이 아닙니다. Slack, Teams 또는 [프로젝트](https://code.claude.com/docs/ko/claude-projects.md) 스레드에서 세션으로 전달된 메시지로 도착했거나, [클라우드 예약 작업](https://code.claude.com/docs/ko/routines.md)이나 다른 프로그램이 보낸 프롬프트로 도착했습니다.4288[`/recap`](https://code.claude.com/docs/ko/interactive-mode#session-recap) 요청이 사용자 본인의 입력에서 오지 않았습니다. Slack, Teams 또는 [프로젝트](https://code.claude.com/docs/ko/claude-projects.md) 스레드에서 세션으로 릴레이된 메시지나, [클라우드 예약 작업](https://code.claude.com/docs/ko/routines.md) 또는 다른 프로그램이 보낸 프롬프트에 포함되어 도착했습니다.

4231 4289 

4232전달된 메시지는 사용자가 직접 작성한 경우에도 이 안내를 받습니다. Claude Code는 전달되거나 자동화된 메시지가 세션을 실행하는 계정의 소유자에게서 왔는지 판단할 수 없으므로, 요약 대신 이 안내로 응답합니다:4290릴레이된 메시지는 사용자가 직접 작성한 경우에도 이 안내를 받습니다. Claude Code는 릴레이되거나 자동화된 메시지가 세션을 실행하는 계정의 소유자에게서 왔는지 알 수 없으므로, 요약 대신 다음 안내로 응답합니다.

4233 4291 

4234```text theme={null}4292```text theme={null}

4235/recap only runs when you ask for it yourself in this session: from the terminal, the Claude app or claude.ai/code, or over Remote Control. A message relayed from Slack, Teams or a project thread, or sent by a routine or another program, can't request it.4293/recap only runs when you ask for it yourself in this session: from the terminal, the Claude app or claude.ai/code, or over Remote Control. A message relayed from Slack, Teams or a project thread, or sent by a routine or another program, can't request it.

4236```4294```

4237 4295 

4238`claude -p`에 전달하는 `/recap`이나, 자체 [Agent SDK](https://code.claude.com/docs/ko/agent-sdk/overview.md) 애플리케이션이 자신이 시작한 세션에 보내는 `/recap`은 사용자 자신의 입력으로 간주됩니다.4296`claude -p`에 전달한 `/recap`이나, 사용자의 [Agent SDK](https://code.claude.com/docs/ko/agent-sdk/overview.md) 애플리케이션이 자신이 시작한 세션으로 보내는 `/recap`은 사용자 본인의 입력으로 간주됩니다.

4239 4297 

4240**해결 방법:**4298**해결 방법:**

4241 4299 

4242* 세션을 직접 열고 해당 세션의 터미널, [Desktop 앱](https://code.claude.com/docs/ko/desktop.md) 또는 [모바일 앱](https://code.claude.com/docs/ko/mobile.md), [claude.ai/code](https://claude.ai/code), 또는 [Remote Control](https://code.claude.com/docs/ko/remote-control.md)을 통해 `/recap`을 실행합니다4300* 세션을 직접 열고 그곳에서 `/recap`을 실행합니다. 세션의 터미널, [Desktop 앱](https://code.claude.com/docs/ko/desktop.md) 또는 [모바일 앱](https://code.claude.com/docs/ko/mobile.md), [claude.ai/code](https://claude.ai/code), 또는 [Remote Control](https://code.claude.com/docs/ko/remote-control.md)을 통해 실행할 수 있습니다

4243* 클라우드 예약 작업이나 다른 프로그램이 보낸 경우 해당 프롬프트에서 `/recap`을 제거합니다4301* 클라우드 예약 작업이나 다른 프로그램이 보낸 경우 해당 프롬프트에서 `/recap`을 제거합니다

4244 4302 

4245### /feedback is disabled by your organization's policy4303### /feedback is disabled by your organization's policy

4246 4304 

4247이 메시지는 제품 피드백이 꺼져 있어 입력한 명령이 피드백 대화 상자를 열지 않는다는 의미입니다. 조직 정책과 이전 거부 모두 이 메시지를 발생시킵니다.4305이 메시지는 제품 피드백이 꺼져 있어 입력한 명령이 피드백 대화 상자를 열지 않는다는 뜻입니다. 조직의 정책과 이전의 거부 모두 이 메시지를 발생시킵니다.

4248 4306 

4249* **조직 정책**: 조직 정책에서 Claude Code의 제품 피드백을 허용하지 않습니다. `/feedback`, `/bug`, `/share` 모두 이 메시지로 응답합니다.4307* **조직 정책**: 조직의 정책이 Claude Code에서의 제품 피드백을 허용하지 않습니다. `/feedback`, `/bug`, `/share` 모두 이 메시지로 응답합니다.

4250* **이전 거부**: 피드백 서비스가 [`Couldn't send feedback: Feedback has not been enabled for your organization.`](#couldnt-send-feedback) 등으로 보낸 보고서를 거부했습니다. 이후 `/feedback`과 `/bug`가 이 메시지로 응답할 수 있습니다. 이 상태는 이 컴퓨터에서 해당 거부 시점부터 7일간 유지됩니다. Pro 및 Max를 포함한 모든 플랜에 적용됩니다.4308* **이전의 거부**: 예를 들어 [`Couldn't send feedback: Feedback has not been enabled for your organization.`](#couldnt-send-feedback)처럼 피드백 서비스가 보낸 보고서를 거부했습니다. 이후 `/feedback`과 `/bug`가 이 메시지로 응답할 수 있습니다. 이 상태는 이 머신에서 해당 거부 시점부터 7일간 유지됩니다. 이는 Pro와 Max를 포함한 모든 요금제에 적용됩니다.

4251 4309 

4252메시지에는 Claude Code 프롬프트에서 입력한 명령이 표시됩니다.4310메시지에는 Claude Code 프롬프트에서 입력한 명령이 표시됩니다.

4253 4311 

4255/feedback is disabled by your organization's policy. To report a bug, open an issue at https://github.com/anthropics/claude-code/issues. Issues are public, so leave out anything confidential.4313/feedback is disabled by your organization's policy. To report a bug, open an issue at https://github.com/anthropics/claude-code/issues. Issues are public, so leave out anything confidential.

4256```4314```

4257 4315 

4258메시지가 첫 번째 문장만으로 표시될 수도 있습니다.4316메시지가 첫 문장만으로 표시될 수도 있습니다.

4259 4317 

4260**해결 방법:**4318**해결 방법:**

4261 4319 

4262* 버그를 보고하려면 [github.com/anthropics/claude-code/issues](https://github.com/anthropics/claude-code/issues)에서 이슈를 엽니다. 이곳의 이슈는 누구나 읽을 수 있으므로 코드, 트랜스크립트 및 기타 기밀 정보는 포함하지 마십시오.4320* 버그를 보고하려면 [github.com/anthropics/claude-code/issues](https://github.com/anthropics/claude-code/issues)에서 이슈를 엽니다. 이곳의 이슈는 누구나 읽을 수 있으므로 코드, 트랜스크립트 및 기타 기밀 정보는 포함하지 않습니다.

4263* 이전 거부 후에는 7일이 지날 때까지 기다린 후, 보고서를 다시 보내 서비스가 여전히 거부하는지 확인합니다4321* 이전의 거부 이후라면 7일이 지날 때까지 기다린 다음 보고서를 다시 보내 서비스가 여전히 거부하는지 확인합니다

4264 4322 

4265v2.1.319 이전에는 이전 거부가 이 메시지를 발생시키지 않았습니다.4323v2.1.319 이전에는 이전의 거부가 이 메시지를 발생시키지 않았습니다.

4266 4324 

4267v2.1.302 이전에는 전체 메시지가 `/feedback is disabled by your organization's policy. Contact your organization admin to enable it.`였습니다.4325v2.1.302 이전에는 전체 메시지가 `/feedback is disabled by your organization's policy. Contact your organization admin to enable it.`였습니다.

4268 4326 

4457* 메시지가 `EACCES`로 끝나면 경로가 지정하는 파일 또는 폴더로 이어지는 모든 디렉터리에 대한 실행 권한을 복원하십시오. 경로 위의 디렉터리를 확인한 다음 도달하는 각 심볼릭 링크를 따라가 그것이 가리키는 위치로 이어지는 디렉터리를 확인하십시오. 다른 오류 코드의 경우 [확인할 수 없는 경로의 원인 및 단계](#path-could-not-be-checked)에서 찾아보십시오.4515* 메시지가 `EACCES`로 끝나면 경로가 지정하는 파일 또는 폴더로 이어지는 모든 디렉터리에 대한 실행 권한을 복원하십시오. 경로 위의 디렉터리를 확인한 다음 도달하는 각 심볼릭 링크를 따라가 그것이 가리키는 위치로 이어지는 디렉터리를 확인하십시오. 다른 오류 코드의 경우 [확인할 수 없는 경로의 원인 및 단계](#path-could-not-be-checked)에서 찾아보십시오.

4458* 동일한 마켓플레이스의 다른 플러그인과 파일을 공유하려면 플러그인 디렉터리 내의 심볼릭 링크로 연결하고 [심볼릭 링크 규칙](https://code.claude.com/docs/ko/plugins/host-marketplace.md#share-files-within-a-marketplace-with-symlinks)을 따르십시오.4516* 동일한 마켓플레이스의 다른 플러그인과 파일을 공유하려면 플러그인 디렉터리 내의 심볼릭 링크로 연결하고 [심볼릭 링크 규칙](https://code.claude.com/docs/ko/plugins/host-marketplace.md#share-files-within-a-marketplace-with-symlinks)을 따르십시오.

4459 4517 

4518### Server file path not read

4519 

4520`path not read` 메시지는 Claude Code가 플러그인이 지정한 MCP 또는 LSP 서버 파일을 해당 파일의 경로 때문에 읽지 않았음을 의미합니다. 플러그인의 나머지 부분은 해당 파일이 정의하는 서버 없이 로드됩니다.

4521 

4522다음 예와 같이 경로가 플러그인 내부에 머물러 있더라도 `..` 부분이 있으면 거부 대상이 됩니다:

4523 

4524```text theme={null}

4525mcp-servers path not read: ./sub/../x.json is absolute or has a ".." part

4526```

4527 

4528**수행할 작업:**

4529 

4530* 플러그인을 설치했지만 유지 관리하지 않는 경우 메시지를 작성자에게 보고하십시오.

4531* 플러그인을 유지 관리하는 경우 서버 파일을 플러그인 디렉터리 내부에 두십시오. 매니페스트 또는 마켓플레이스 항목에서 `./`로 시작하고 `..`가 없는 경로로 지정하십시오. 예: `./servers/x.json`

4532* 동일한 마켓플레이스의 플러그인 간에 하나의 서버 파일을 공유하려면 [심볼릭 링크 규칙](https://code.claude.com/docs/ko/plugins/host-marketplace.md#share-files-within-a-marketplace-with-symlinks)에 따라 심볼릭 링크로 각 플러그인에 파일을 연결하십시오.

4533 

4460### Plugin not loaded: its manifest was not read4534### Plugin not loaded: its manifest was not read

4461 4535 

4462Claude Code는 `.claude-plugin/plugin.json`에 있는 마켓플레이스 플러그인의 [매니페스트](https://code.claude.com/docs/ko/plugins/manifest-reference.md)가 플러그인 내부에 있는지 확인할 수 없었으므로 해당 플러그인에서 아무것도 로드하지 않습니다. [로컬 마켓플레이스](https://code.claude.com/docs/ko/plugins/loading.md#in-place-and-copied-plugins)의 플러그인의 경우 Claude Code는 매니페스트가 해당 마켓플레이스 내부에 있는지도 확인할 수 없었습니다. 메시지는 `/plugin` **Errors** 탭에 나타나며, 끝부분의 이유는 Claude Code가 발견한 내용을 알려 줍니다.4536Claude Code는 `.claude-plugin/plugin.json`에 있는 마켓플레이스 플러그인의 [매니페스트](https://code.claude.com/docs/ko/plugins/manifest-reference.md)가 플러그인 내부에 있는지 확인할 수 없었으므로 해당 플러그인에서 아무것도 로드하지 않습니다. [로컬 마켓플레이스](https://code.claude.com/docs/ko/plugins/loading.md#in-place-and-copied-plugins)의 플러그인의 경우 Claude Code는 매니페스트가 해당 마켓플레이스 내부에 있는지도 확인할 수 없었습니다. 메시지는 `/plugin` **Errors** 탭에 나타나며, 끝부분의 이유는 Claude Code가 발견한 내용을 알려 줍니다.

5065 5139 

5066v2.1.280 이전에는 `where it leads on disk could not be determined` 거부가 표시되지 않았습니다.5140v2.1.280 이전에는 `where it leads on disk could not be determined` 거부가 표시되지 않았습니다.

5067 5141 

5142### The search failed, so this is not a "no matches" result

5143 

5144Claude가 실행한 [Grep](https://code.claude.com/docs/ko/tools-reference.md#grep-tool-behavior) 또는 [Glob](https://code.claude.com/docs/ko/tools-reference.md#glob-tool-behavior) 검색이 결과를 반환하기 전에 실패했으므로, 일치 항목이 있는지 알 수 없습니다. Claude가 결과 대신 받는 메시지는 다음과 같이 시작합니다.

5145 

5146```text wrap theme={null}

5147The search failed, so this is not a "no matches" result: matches may exist. What happened to the search program (ripgrep) is not known, and no results were read. Run the search once more. If it fails again, tell the user that searches are failing.

5148```

5149 

5150**조치 방법:**

5151 

5152* **처음 나타난 경우**: 조치할 필요가 없습니다. 메시지가 Claude에게 먼저 다시 검색하라고 요청합니다.

5153* **Claude가 검색이 실패하고 있다고 알리는 경우**: 버그 보고를 위해 ripgrep의 오류를 수집합니다.

5154 1. 셸에서 검색이 실패한 세션과 같은 플래그에 [`--debug-file claude-debug.log`](https://code.claude.com/docs/ko/cli-reference#cli-flags)를 추가하여 세션을 시작합니다

5155 2. 검색 실패로 이어진 요청을 Claude에게 보냅니다

5156 3. 검색이 다시 실패하면 `claude-debug.log`에서 `rg error (signal=`이 포함된 줄을 찾습니다

5157 4. [문제를 보고할](#report-an-error) 때 해당 줄을 포함합니다

5158 

5068### Task output swap refused5159### Task output swap refused

5069 5160 

5070Claude Code는 각 Bash 명령의 출력을 임시 디렉터리 아래의 파일에 저장합니다. 이러한 파일을 열 때마다 심볼릭 링크, 추가 하드 링크 또는 이동된 디렉터리가 경로를 리디렉션하지 않고 경로가 여전히 자신이 만든 파일로 이어지는지 확인합니다. 이 메시지는 해당 검사가 실패했다는 뜻이므로, Claude Code는 그 경로를 통해 출력을 쓰거나 읽는 대신 작업을 거부했습니다. 메시지는 Bash 도구 결과에 표시됩니다.5161Claude Code는 각 Bash 명령의 출력을 임시 디렉터리 아래의 파일에 저장합니다. 이러한 파일을 열 때마다 심볼릭 링크, 추가 하드 링크 또는 이동된 디렉터리가 경로를 리디렉션하지 않고 경로가 여전히 자신이 만든 파일로 이어지는지 확인합니다. 이 메시지는 해당 검사가 실패했다는 뜻이므로, Claude Code는 그 경로를 통해 출력을 쓰거나 읽는 대신 작업을 거부했습니다. 메시지는 Bash 도구 결과에 표시됩니다.

5153 5244 

5154v2.1.296 이전에는 Edit과 NotebookEdit이 이러한 편집을 적용하고 디코딩할 수 없는 모든 바이트를 `U+FFFD`로 저장했습니다. 해당 버전을 사용 중이라면 Claude Code를 업데이트합니다.5245v2.1.296 이전에는 Edit과 NotebookEdit이 이러한 편집을 적용하고 디코딩할 수 없는 모든 바이트를 `U+FFFD`로 저장했습니다. 해당 버전을 사용 중이라면 Claude Code를 업데이트합니다.

5155 5246 

5247### Refusing to apply edits: a hook is configured for file edits in this session

5248 

5249Claude가 [한 단계 업데이트](https://code.claude.com/docs/ko/artifacts.md#turn-off-one-step-artifact-updates)로 [아티팩트](https://code.claude.com/docs/ko/artifacts.md)를 게시하려 했지만 Claude Code가 거부했습니다. 한 단계 업데이트는 게시에 포함된 아티팩트 파일의 작은 변경입니다. 아무것도 게시되지 않았으며 파일은 변경되지 않았습니다. 메시지는 Artifact 도구 결과에 표시됩니다.

5250 

5251```text wrap theme={null}

5252Refusing to apply edits to <path>: a hook is configured for file edits in this session, so a publish can't apply edits here. Edit the file, then publish it without edits. Nothing was published.

5253```

5254 

5255Claude Code는 세션에 `Edit` 또는 `Write`에 대한 [`PreToolUse` 훅](https://code.claude.com/docs/ko/hooks#pretooluse)이나 [mod](https://code.claude.com/docs/ko/plugins/mods/overview.md)가 있는 동안에는 한 단계 업데이트를 허용하지 않습니다.

5256 

5257**조치 방법:**

5258 

5259* Claude가 이어서 파일을 편집하고 게시했다면 조치할 필요가 없습니다

5260* Claude가 메시지에서 멈췄다면 Claude에게 파일을 편집하고 게시하도록 요청합니다

5261* 메시지가 계속 나타난다면 Claude Code를 종료하고 다시 실행합니다

5262* 다시 실행한 후에도 메시지가 나타난다면 [한 단계 업데이트를 끕니다](https://code.claude.com/docs/ko/artifacts.md#turn-off-one-step-artifact-updates)

5263 

5156### The source file is not valid UTF-8 text5264### The source file is not valid UTF-8 text

5157 5265 

5158Claude가 바이트를 텍스트로 디코딩할 수 없거나 텍스트에 이미 대체 문자 `U+FFFD`가 포함된 파일에서 [아티팩트](https://code.claude.com/docs/ko/artifacts.md)를 게시하려 했기 때문에, Claude Code가 아무것도 업로드하기 전에 게시를 거부했습니다. 메시지는 Artifact 도구 결과에 표시되며 수정해야 할 첫 번째 위치를 알려 줍니다.5266Claude가 바이트를 텍스트로 디코딩할 수 없거나 텍스트에 이미 대체 문자 `U+FFFD`가 포함된 파일에서 [아티팩트](https://code.claude.com/docs/ko/artifacts.md)를 게시하려 했기 때문에, Claude Code가 아무것도 업로드하기 전에 게시를 거부했습니다. 메시지는 Artifact 도구 결과에 표시되며 수정해야 할 첫 번째 위치를 알려 줍니다.

5623 5731 

5624* 메시지가 명시하는 디렉터리를 다시 만들거나 존재하는 디렉터리에서 디스패치한 다음 다시 시도합니다.5732* 메시지가 명시하는 디렉터리를 다시 만들거나 존재하는 디렉터리에서 디스패치한 다음 다시 시도합니다.

5625 5733 

5734### This forked session could not be started

5735 

5736claude.ai에서 [Remote Control 세션을 분기](https://code.claude.com/docs/ko/remote-control.md#fork-a-session-from-your-browser)했으며, Claude Code가 머신에서 분기된 세션을 실행하는 [백그라운드 세션](https://code.claude.com/docs/ko/agent-view.md)의 시작을 완료할 수 없었습니다. 이 알림은 분기된 세션의 트랜스크립트에 나타납니다:

5737 

5738```text theme={null}

5739This forked session could not be started. Fork the conversation again to retry.

5740```

5741 

5742분기한 원래 세션은 계속 실행됩니다.

5743 

5744**할 일:**

5745 

5746* 분기한 원래 세션으로 돌아가 세션이 유휴 상태가 되면 다시 분기합니다.

5747 

5626### 백그라운드 세션을 디스패치할 때 워크스페이스를 신뢰하지 않음5748### 백그라운드 세션을 디스패치할 때 워크스페이스를 신뢰하지 않음

5627 5749 

5628[신뢰하지 않은](https://code.claude.com/docs/ko/permissions.md#project-allow-rules-and-workspace-trust) 디렉터리에서 [백그라운드 세션](https://code.claude.com/docs/ko/agent-view.md)을 시작하거나 다시 시작했으며, 워크스페이스 신뢰 대화 상자가 나타나 확인을 요청할 수 없었습니다. Claude Code는 세션을 시작하지 않습니다:5750[신뢰하지 않은](https://code.claude.com/docs/ko/permissions.md#project-allow-rules-and-workspace-trust) 디렉터리에서 [백그라운드 세션](https://code.claude.com/docs/ko/agent-view.md)을 시작하거나 다시 시작했으며, 워크스페이스 신뢰 대화 상자가 나타나 확인을 요청할 수 없었습니다. Claude Code는 세션을 시작하지 않습니다:

fast-mode.md +40 −18

Details

12 12 

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

14 14 

15빠른 모드는 비용 효율성보다 속도를 우선시하는 다른 API 구성으로 동일한 모델을 사용하므로, 품질과 기능은 동일하게 유지됩니다. 빠른 모드는 Fable 5.2, Opus 5.5, Opus 5 및 Opus 4.8에서 지원됩니다. Sonnet, Haiku 또는 다른 모델에서는 사용할 수 없습니다.15빠른 모드는 비용 효율성보다 속도를 우선시하는 다른 API 구성으로 동일한 모델을 사용하므로, 품질과 기능은 동일하게 유지됩니다. Anthropic API에서 빠른 모드는 Fable 5.2, Opus 5.5, Opus 5 및 Opus 4.8에서 지원되며, Sonnet, Haiku 또는 다른 모델에서는 지원되지 않습니다. Google Cloud의 Agent Platform에서 제공되는 모델에 대해서는 [Agent Platform에서 빠른 모드 사용](#use-fast-mode-on-agent-platform)을 참조하십시오.

16 16 

17> [!WARNING]17> [!WARNING]

18>18>

25 25 

26알아야 할 사항:26알아야 할 사항:

27 27 

28* Claude Code CLI에서 `/fast`를 사용하여 빠른 모드를 전환합니다. [VS Code 확장 프로그램](https://code.claude.com/docs/ko/vs-code.md)은 선택한 모델이 빠른 모드를 지원할 때 **빠른 모드 전환** 명령을 제공합니다. Claude Code는 해당 전환을 [`fastMode` 설정](#toggle-fast-mode)에 저장합니다.28* Claude Code CLI에서 `/fast`를 사용하여 빠른 모드를 전환합니다. [VS Code 확장 프로그램](https://code.claude.com/docs/ko/vs-code.md)은 선택한 모델이 빠른 모드를 지원할 때 **빠른 모드 전환** 명령을 제공합니다. Anthropic API에서는 Claude Code가 해당 전환을 [`fastMode` 설정](#toggle-fast-mode)에 저장합니다.

29* 빠른 모드 가격은 MTok 입력/출력당 Fable 5.2에서 \$16/\$80, Opus 5.5에서 \$8/\$40, Opus 5 및 Opus 4.8에서 \$10/\$50입니다.29* Anthropic의 빠른 모드 가격은 MTok 입력/출력당 Fable 5.2에서 \$16/\$80, Opus 5.5에서 \$8/\$40, Opus 5 및 Opus 4.8에서 \$10/\$50입니다.

30* 구독 요금제(Pro/Max/Ultra/Team/Enterprise)의 Claude Code 사용자 및 Claude Console에서 사용할 수 있습니다. Team 및 Enterprise 조직은 먼저 소유자가 활성화해야 하며, Console 조직은 Opus 5 또는 Opus 4.8에서 사용하려면 먼저 액세스를 프로비저닝해야 합니다. 두 가지 모두 [요구 사항](#requirements)에 설명되어 있습니다.30* 구독 요금제(Pro/Max/Ultra/Team/Enterprise)의 Claude Code 사용자, Claude Console, 그리고 [조건부로](#use-fast-mode-on-agent-platform) Google Cloud의 Agent Platform에서 사용할 수 있습니다. Team 및 Enterprise 조직은 먼저 소유자가 활성화해야 하며, Console 조직은 Opus 5 또는 Opus 4.8에서 사용하려면 먼저 액세스를 프로비저닝해야 합니다. 두 가지 모두 [요구 사항](#requirements)에 설명되어 있습니다.

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

32 32 

33## 빠른 모드 전환33## 빠른 모드 전환

34 34 

35Agent Platform에서는 `/fast`와 `fastMode` 설정이 다르게 작동하므로, 대신 [Agent Platform에서 빠른 모드 사용](#use-fast-mode-on-agent-platform)을 따릅니다.

36 

35CLI에서 다음 중 한 가지 방법으로 빠른 모드를 전환합니다:37CLI에서 다음 중 한 가지 방법으로 빠른 모드를 전환합니다:

36 38 

37* `/fast`를 입력하고 Space를 눌러 켜거나 끕니다. 그 다음 Enter를 눌러 확인합니다39* `/fast`를 입력하고 Space를 눌러 켜거나 끕니다. 그 다음 Enter를 눌러 확인합니다

38* 빠른 모드를 지원하는 모델에서 [사용자 설정 파일](https://code.claude.com/docs/ko/settings.md)에 `"fastMode": true`를 설정합니다. 다른 모델에서 이를 설정하면 해당 모델이 그대로 유지되며 빠른 모드는 꺼진 상태로 남습니다. Fable 5.2에서는 Fable 5.2를 사용하는 동안 `/fast`를 실행하기 전까지 이 설정만으로는 효과가 없습니다.40* 빠른 모드를 지원하는 모델에서 [사용자 설정 파일](https://code.claude.com/docs/ko/settings.md)에 `"fastMode": true`를 설정합니다. 다른 모델에서 이를 설정하면 해당 모델이 그대로 유지되며 빠른 모드는 꺼진 상태로 남습니다. Fable 5.2에서는 Fable 5.2를 사용하는 동안 `/fast`를 실행하기 전까지 이 설정만으로는 효과가 없습니다.

39 41 

40기본적으로 빠른 모드는 대화형 세션에서 켜면 지원되는 모델에서 세션 간에 유지됩니다. Fable 5.2에서는 [Fable 5.2를 사용하는 동안 켠](#switch-models-while-fast-mode-is-on) 경우에만 유지됩니다. 빠른 모드를 각 세션마다 재설정하도록 구성할 수 있습니다. 자세한 내용은 [세션별 옵트인 필요](#require-per-session-opt-in)를 참조합니다.42Anthropic API에서는 기본적으로 대화형 세션에서 켠 빠른 모드가 지원되는 모델에서 세션 간에 유지됩니다. Fable 5.2에서는 [Fable 5.2를 사용하는 동안 켠](#switch-models-while-fast-mode-is-on) 경우에만 유지됩니다. 빠른 모드를 각 세션마다 재설정하도록 구성할 수 있습니다. 자세한 내용은 [세션별 옵트인 필요](#require-per-session-opt-in)를 참조합니다.

41 43 

42[클라우드 세션](#use-fast-mode-in-cloud-sessions) 외부에서 [비대화형 모드](https://code.claude.com/docs/ko/headless.md)에서 `-p` 플래그를 사용하면, `/fast`는 [`--settings`](https://code.claude.com/docs/ko/cli-reference#cli-flags) 값에 빠른 모드가 켜져 있는 상태로 시작된 세션에서만 작동합니다. 예를 들어 `claude -p --settings '{"fastMode": true}'`와 같이 사용하면, 토글이 해당 세션에만 적용되며 기본값으로 저장되지 않습니다. `-p` 형식은 Claude Code v2.1.205 이상이 필요합니다. 비대화형 모드의 다른 곳에서는 빠른 모드를 사용할 수 없다는 명령 보고가 나타납니다.44[클라우드 세션](#use-fast-mode-in-cloud-sessions) 외부에서 [비대화형 모드](https://code.claude.com/docs/ko/headless.md)에서 `-p` 플래그를 사용하면, `/fast`는 [`--settings`](https://code.claude.com/docs/ko/cli-reference#cli-flags) 값에 빠른 모드가 켜져 있는 상태로 시작된 세션에서만 작동합니다. 예를 들어 `claude -p --settings '{"fastMode": true}'`와 같이 사용하면, 토글이 해당 세션에만 적용되며 기본값으로 저장되지 않습니다. `-p` 형식은 Claude Code v2.1.205 이상이 필요합니다. 비대화형 모드의 다른 곳에서는 빠른 모드를 사용할 수 없다는 명령 보고가 나타납니다.

43 45 

47 49 

48`/fast`로 빠른 모드를 활성화하면:50`/fast`로 빠른 모드를 활성화하면:

49 51 

50* 현재 모델이 빠른 모드를 지원하지 않으면 Claude Code가 Opus로 전환합니다52* Anthropic API에서 현재 모델이 빠른 모드를 지원하지 않으면 Claude Code가 Opus로 전환합니다

51* Fable 5.2에서 빠른 모드를 사용하려면 Claude Code v2.1.321 이상이 필요합니다53* Fable 5.2에서 빠른 모드를 사용하려면 Claude Code v2.1.321 이상이 필요합니다

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

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

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

55 57 

56Opus 5.5는 Claude Code v2.1.280 이상에서 빠른 모드 기본값입니다. v2.1.280 이전에는 v2.1.219부터 Opus 5로 기본 설정되었습니다.58Anthropic API에서는 Claude Code v2.1.280 이상에서 Opus 5.5가 빠른 모드 기본값입니다. v2.1.280 이전에는 v2.1.219부터 Opus 5로 기본 설정되었습니다.

57 59 

58`/fast`를 다시 실행하여 빠른 모드를 비활성화하면 현재 모델이 유지됩니다. 다른 모델로 전환하려면 `/model`을 사용합니다.60`/fast`를 다시 실행하여 빠른 모드를 비활성화하면 현재 모델이 유지됩니다. 다른 모델로 전환하려면 `/model`을 사용합니다.

59 61 

63 65 

64* **전환**: 빠른 모드를 지원하지 않는 모델로 전환하면 Claude Code가 빠른 모드를 끕니다. 여기에는 Opus 4.7이 포함됩니다. v2.1.221 이전에는 Opus 4.7로 전환한 후에도 빠른 모드가 켜져 있었고 API가 요청을 거부했습니다.66* **전환**: 빠른 모드를 지원하지 않는 모델로 전환하면 Claude Code가 빠른 모드를 끕니다. 여기에는 Opus 4.7이 포함됩니다. v2.1.221 이전에는 Opus 4.7로 전환한 후에도 빠른 모드가 켜져 있었고 API가 요청을 거부했습니다.

65* **다시 전환**: 저장된 기본 설정이 켜져 있으면 지원되는 Opus 모델에서 빠른 모드가 다시 켜집니다. [세션별 옵트인](#require-per-session-opt-in)을 사용하는 경우에는 대신 `/fast`를 실행합니다.67* **다시 전환**: 저장된 기본 설정이 켜져 있으면 지원되는 Opus 모델에서 빠른 모드가 다시 켜집니다. [세션별 옵트인](#require-per-session-opt-in)을 사용하는 경우에는 대신 `/fast`를 실행합니다.

66* **Fable 5.2로 전환**: Fable 5.2를 사용하는 동안 켠 경우가 아니면 빠른 모드가 꺼집니다. 켜려면 Fable 5.2에서 `/fast`를 실행합니다. [세션별 옵트인](#require-per-session-opt-in)을 설정하지 않은 경우, 끄거나 다른 모델에서 켜기 전까지 이 상태가 세션 간에 유지됩니다.68* **Fable 5.2로 전환**: Fable 5.2를 사용하는 동안 켠 경우가 아니면 빠른 모드가 꺼집니다. 켜려면 Fable 5.2에서 `/fast`를 실행합니다. [세션별 옵트인](#require-per-session-opt-in)을 설정하지 않은 경우, 빠른 모드를 끄거나 다른 모델에서 켜기 전까지 이 선택이 Anthropic API에서 세션 간에 유지됩니다.

67 69 

68모델 전환이 빠른 모드를 켜거나 끌 때마다 Claude Code는 `Fast mode ON` 또는 `Fast mode OFF` 확인을 표시하며, 빠른 모드가 켜져 있는 동안 `↯` 아이콘이 나타납니다. 이는 `/model`로 전환하든, [`/config model=<model>`](https://code.claude.com/docs/ko/settings)로 전환하든, [원격 제어](https://code.claude.com/docs/ko/remote-control.md)를 통해 연결된 기기에서 전환하든 적용됩니다.70모델 전환이 빠른 모드를 켜거나 끌 때마다 Claude Code는 `Fast mode ON` 또는 `Fast mode OFF` 확인을 표시하며, 빠른 모드가 켜져 있는 동안 `↯` 아이콘이 나타납니다. 이는 `/model`로 전환하든, [`/config model=<model>`](https://code.claude.com/docs/ko/settings)로 전환하든, [원격 제어](https://code.claude.com/docs/ko/remote-control.md)를 통해 연결된 기기에서 전환하든 적용됩니다.

69 71 

70Claude Code는 모델 전환, 재연결 또는 실패한 [가용성 확인](#use-fast-mode-behind-proxies-and-llm-gateways) 후 Remote Control을 통해 연결된 기기에 세션의 빠른 모드 상태를 다시 전송합니다.

71 

72### 클라우드 세션에서 빠른 모드 사용72### 클라우드 세션에서 빠른 모드 사용

73 73 

74빠른 모드는 [클라우드 세션](https://code.claude.com/docs/ko/claude-code-on-the-web.md)에서 계정에서 사용 가능할 때 작동합니다. 세션이 Anthropic 관리 인프라에서 실행되든 [자체 호스팅 실행기](https://code.claude.com/docs/ko/self-hosted-environments)에서 실행되든 상관없습니다. 세션의 환경에서 Claude Code v2.1.271 이상이 필요합니다.74빠른 모드는 [클라우드 세션](https://code.claude.com/docs/ko/claude-code-on-the-web.md)에서 계정에서 사용 가능할 때 작동합니다. 세션이 Anthropic 관리 인프라에서 실행되든 Anthropic API의 [자체 호스팅 실행기](https://code.claude.com/docs/ko/self-hosted-environments)에서 실행되든 상관없습니다. 세션의 환경에서 Claude Code v2.1.271 이상이 필요합니다.

75 75 

76세션에서 `/fast on`을 입력하여 빠른 모드를 켭니다. 해당 세션에만 켜져 있으며 기본값으로 저장되지 않습니다. [요구 사항](#requirements)은 클라우드 세션에도 적용됩니다.76세션에서 `/fast on`을 입력하여 빠른 모드를 켭니다. 해당 세션에만 켜져 있으며 기본값으로 저장되지 않습니다. [요구 사항](#requirements)은 클라우드 세션에도 적용됩니다.

77 77 

79 79 

80## 비용 트레이드오프 이해80## 비용 트레이드오프 이해

81 81 

82빠른 모드는 표준 속도보다 토큰당 가격이 높습니다:82빠른 모드는 표준 속도보다 토큰당 가격이 높습니다. Anthropic의 요금은 다음과 같습니다:

83 83 

84| 모델 | 입력 (MTok) | 출력 (MTok) |84| 모델 | 입력 (MTok) | 출력 (MTok) |

85| - | - | - |85| - | - | - |

129 129 

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

131 131 

132* **Anthropic API 또는 구독만 해당**: 빠른 모드는 Anthropic Console API 및 사용량 크레딧을 사용하는 Claude 구독 요금제를 통해 사용할 수 있습니다. Amazon Bedrock, Google Cloud의 Agent Platform, Microsoft Foundry 또는 AWS의 Claude Platform에서는 사용할 수 없습니다. Console 조직이 Opus 5 또는 Opus 4.8에서 빠른 모드를 사용하려면 [빠른 모드 액세스가 프로비저닝](#enable-fast-mode-for-your-organization)되어 있어야 합니다.132* **지원되는 제공업체**: 빠른 모드는 Anthropic Console API, 사용량 크레딧을 사용하는 Claude 구독 요금제, 그리고 [조건부로](#use-fast-mode-on-agent-platform) Google Cloud의 Agent Platform에서 사용할 수 있습니다. Amazon Bedrock, Microsoft Foundry 또는 AWS의 Claude Platform에서는 사용할 수 없으며, 이러한 제공업체에서 `/fast`는 "Fast mode is not available on this provider"를 표시합니다. Console 조직이 Opus 5 또는 Opus 4.8에서 빠른 모드를 사용하려면 [빠른 모드 액세스도 프로비저닝](#enable-fast-mode-for-your-organization)되어 있어야 합니다.

133* **구독 요금제에 대해 사용량 크레딧 활성화**: Pro, Max, Ultra, Team 또는 Enterprise 요금제에서 계정에 [사용량 크레딧](https://code.claude.com/docs/ko/costs.md#add-usage-credits-to-your-subscription)이 활성화되어 있어야 하며, 이를 통해 요금제의 포함된 사용량을 초과하여 청구할 수 있습니다. 활성화될 때까지 `/fast`는 "Fast mode requires usage credits"를 표시합니다. 활성화하는 방법은 요금제에 따라 다릅니다:133* **구독 요금제에 대해 사용량 크레딧 활성화**: Pro, Max, Ultra, Team 또는 Enterprise 요금제에서 계정에 [사용량 크레딧](https://code.claude.com/docs/ko/costs.md#add-usage-credits-to-your-subscription)이 활성화되어 있어야 하며, 이를 통해 요금제의 포함된 사용량을 초과하여 청구할 수 있습니다. 활성화될 때까지 `/fast`는 "Fast mode requires usage credits"를 표시합니다. 활성화하는 방법은 요금제에 따라 다릅니다:

134 * Pro, Max 및 Ultra에서는 claude.ai의 [**설정 > 사용**](https://claude.ai/settings/usage)의 **사용량 크레딧** 섹션에서 활성화하거나 `/usage-credits`를 실행하여 해당 페이지를 엽니다.134 * Pro, Max 및 Ultra에서는 claude.ai의 [**설정 > 사용**](https://claude.ai/settings/usage)의 **사용량 크레딧** 섹션에서 활성화하거나 `/usage-credits`를 실행하여 해당 페이지를 엽니다.

135 * Team 및 Enterprise에서는 청구 액세스 권한이 있는 구성원이 [**조직 설정 > 사용**](https://claude.ai/admin-settings/usage)에서 조직에 대해 활성화하고, 액세스 권한이 없는 구성원은 `/usage-credits`를 실행하여 조직의 관리자에게 요청을 보냅니다.135 * Team 및 Enterprise에서는 청구 액세스 권한이 있는 구성원이 [**조직 설정 > 사용**](https://claude.ai/admin-settings/usage)에서 조직에 대해 활성화하고, 액세스 권한이 없는 구성원은 `/usage-credits`를 실행하여 조직의 관리자에게 요청을 보냅니다.

150> * **빠른 모드가 활성화되지 않음**: 조직에 대해 빠른 모드가 활성화되지 않은 경우 `/fast`로 빠른 모드를 켜면 "Fast mode has been disabled by your organization."이 표시됩니다.150> * **빠른 모드가 활성화되지 않음**: 조직에 대해 빠른 모드가 활성화되지 않은 경우 `/fast`로 빠른 모드를 켜면 "Fast mode has been disabled by your organization."이 표시됩니다.

151> * **관리 설정에 의해 빠른 모드가 꺼짐**: 조직이 [`fastMode: false`](https://code.claude.com/docs/ko/settings-reference#fastmode)를 설정하는 [관리 설정](https://code.claude.com/docs/ko/managed-settings.md)을 배포하는 경우 `/fast`로 빠른 모드를 켜면 동일한 "Fast mode has been disabled by your organization" 메시지가 표시됩니다.151> * **관리 설정에 의해 빠른 모드가 꺼짐**: 조직이 [`fastMode: false`](https://code.claude.com/docs/ko/settings-reference#fastmode)를 설정하는 [관리 설정](https://code.claude.com/docs/ko/managed-settings.md)을 배포하는 경우 `/fast`로 빠른 모드를 켜면 동일한 "Fast mode has been disabled by your organization" 메시지가 표시됩니다.

152> * **세션별 옵트인 필요**: [`fastModePerSessionOptIn: true`](#require-per-session-opt-in)를 설정하는 관리 설정은 대화형 터미널 세션을 제외한 모든 곳에서 `/fast on`을 동일한 메시지로 거부합니다.152> * **세션별 옵트인 필요**: [`fastModePerSessionOptIn: true`](#require-per-session-opt-in)를 설정하는 관리 설정은 대화형 터미널 세션을 제외한 모든 곳에서 `/fast on`을 동일한 메시지로 거부합니다.

153> * **빠른 모드 모델이 허용되지 않음**: 조직의 [`availableModels`](https://code.claude.com/docs/ko/model-config#restrict-model-selection) 허용 목록이 빠른 모드 Opus 모델을 제외하는 경우 빠른 모드를 켜려고 하면 "is not in your organization's allowed models"로 거부됩니다. 빠른 모드를 지원하는 허용된 모델에서 이미 실행 중인 세션에서는 `/fast`가 모델을 전환하는 대신 현재 모델에서 빠른 모드를 활성화합니다.153> * **빠른 모드 모델이 허용되지 않음**: 조직의 [`availableModels`](https://code.claude.com/docs/ko/model-config#restrict-model-selection) 허용 목록이 `/fast`가 전환하는 모델을 제외하는 경우 빠른 모드를 켜려고 하면 "is not in your organization's allowed models"로 거부됩니다. 빠른 모드를 지원하는 허용된 모델에서 이미 실행 중인 세션에서는 `/fast`가 모델을 전환하는 대신 현재 모델에서 빠른 모드를 활성화합니다.

154 154 

155### 조직에 대해 빠른 모드 활성화155### 조직에 대해 빠른 모드 활성화

156 156 

163 163 

164빠른 모드를 완전히 비활성화하는 또 다른 옵션은 `CLAUDE_CODE_DISABLE_FAST_MODE=1`을 설정하는 것입니다. [환경 변수](https://code.claude.com/docs/ko/env-vars.md)를 참조합니다.164빠른 모드를 완전히 비활성화하는 또 다른 옵션은 `CLAUDE_CODE_DISABLE_FAST_MODE=1`을 설정하는 것입니다. [환경 변수](https://code.claude.com/docs/ko/env-vars.md)를 참조합니다.

165 165 

166### Agent Platform에서 빠른 모드 사용

167 

168[Google Cloud의 Agent Platform](https://code.claude.com/docs/ko/google-vertex-ai.md)에서는 대화형 세션에서 `/fast`를 사용하거나 [비대화형 모드](https://code.claude.com/docs/ko/headless.md)에서 실행 플래그를 사용하여 Fable 5.2에 대해 빠른 모드를 켤 수 있습니다. Claude Code v2.1.322 이상이 필요합니다.

169 

170빠른 모드를 사용하려면 Fable 5.2의 [리전](https://code.claude.com/docs/ko/google-vertex-ai.md#region-configuration)이 `global`, `us` 또는 `eu`여야 합니다. 다른 리전에서는 `/fast`가 `Fast mode needs Vertex region global, us or eu`를 표시하고, `claude -p`는 표준 속도로 실행됩니다. Claude Code를 시작하기 전에 셸에서 리전을 설정합니다. 예를 들어 `global`로 설정하려면 다음과 같습니다:

171 

172```bash theme={null}

173export VERTEX_REGION_CLAUDE_FABLE_5_2=global

174```

175 

176그런 다음 빠른 모드를 켭니다:

177 

178* **대화형 세션에서**: `/fast`를 실행합니다. Opus 모델이나 Agent Platform에서 빠른 모드를 지원하지 않는 다른 모델에서 Fable 5.2로 전환됩니다. 빠른 모드는 기본값으로 저장되지 않습니다.

179* **비대화형 모드에서**: Fable 5.2를 [`--model`](https://code.claude.com/docs/ko/cli-reference#cli-flags)로, 빠른 모드를 [`--settings`](https://code.claude.com/docs/ko/cli-reference#cli-flags)로 전달합니다. 예: `claude -p "Summarize this project" --model claude-fable-5-2 --settings '{"fastMode": true}'`

180 

181Agent Platform에서는 사용자, 프로젝트, 로컬 또는 관리형 설정의 `"fastMode": true`가 아무런 효과가 없습니다.

182 

183Agent Platform이 빠른 모드를 거부하면 Claude Code는 표준 속도로 대체됩니다. 그러면 대화형 세션에 다음 터미널 메시지 중 하나가 표시됩니다:

184 

185* `Using standard speed on Fable 5.2 · fast mode wasn't available`: 빠른 모드를 다시 시도하려면 `/fast on`을 실행합니다

186* `Fast mode was refused for this project · trying again in 30m`: Agent Platform이 빠른 모드 요청에 403 또는 404 오류로 응답했습니다. 더 빨리 다시 시도하려면 `/fast on`을 실행합니다.

187 

166### 프록시 및 LLM 게이트웨이 뒤에서 빠른 모드 사용188### 프록시 및 LLM 게이트웨이 뒤에서 빠른 모드 사용

167 189 

168빠른 모드를 제공하기 전에 Claude Code는 `api.anthropic.com`에 직접 요청하여 조직의 빠른 모드 가용성을 확인합니다. 확인은 [`ANTHROPIC_BASE_URL`](https://code.claude.com/docs/ko/llm-gateway-connect#set-the-base-url-and-credential)을 따르지 않으므로, Claude 트래픽을 [LLM 게이트웨이](https://code.claude.com/docs/ko/llm-gateway)를 통해 라우팅하고 `api.anthropic.com`에 대한 직접 송신을 차단하는 네트워크에서는 추론 요청이 작동하더라도 확인이 실패합니다. 확인은 구성된 [HTTP 프록시](https://code.claude.com/docs/ko/network-config.md#proxy-configuration)를 사용하므로 네트워크 차단은 프록시를 통해서도 `api.anthropic.com`에 도달할 수 없는 경우에만 확인을 실패합니다.190Anthropic API에서 빠른 모드를 제공하기 전에 Claude Code는 `api.anthropic.com`에 직접 요청하여 조직의 빠른 모드 가용성을 확인합니다. 확인은 [`ANTHROPIC_BASE_URL`](https://code.claude.com/docs/ko/llm-gateway-connect#set-the-base-url-and-credential)을 따르지 않으므로, Claude 트래픽을 [LLM 게이트웨이](https://code.claude.com/docs/ko/llm-gateway)를 통해 라우팅하고 `api.anthropic.com`에 대한 직접 송신을 차단하는 네트워크에서는 추론 요청이 작동하더라도 확인이 실패합니다.

169 191 

170조직에서 빠른 모드가 활성화되어 있는데 `/fast`가 다르게 표시하는 경우, 다음 사례 중에서 표시된 메시지를 찾습니다.192확인은 구성된 [HTTP 프록시](https://code.claude.com/docs/ko/network-config.md#proxy-configuration)를 사용하므로 네트워크 차단은 프록시를 통해서도 `api.anthropic.com`에 도달할 수 없는 경우에만 확인을 실패합니다. 조직에서 빠른 모드가 활성화되어 있는데 `/fast`가 다르게 표시하는 경우, 다음 사례 중에서 표시된 메시지를 찾습니다.

171 193 

172#### Fast mode unavailable due to network connectivity issues194#### Fast mode unavailable due to network connectivity issues

173 195 

199 221 

200### 세션별 옵트인 필요222### 세션별 옵트인 필요

201 223 

202기본적으로 사용자가 대화형 세션에서 켠 빠른 모드는 지원되는 모델에서 세션 간에 유지됩니다. Fable 5.2에서는 사용자가 [Fable 5.2를 사용하는 동안 켠](#switch-models-while-fast-mode-is-on) 경우에만 유지됩니다.224Anthropic API에서는 기본적으로 사용자가 대화형 세션에서 켠 빠른 모드가 지원되는 모델에서 세션 간에 유지됩니다. Fable 5.2에서는 사용자가 [Fable 5.2를 사용하는 동안 켠](#switch-models-while-fast-mode-is-on) 경우에만 유지됩니다.

203 225 

204모든 세션이 빠른 모드가 꺼진 상태로 시작되도록 하려면 [설정 파일](https://code.claude.com/docs/ko/settings.md#where-settings-live)에서 `fastModePerSessionOptIn`을 `true`로 설정합니다. 그러면 사용자는 각 세션에서 `/fast`로 빠른 모드를 활성화합니다. [Team](https://claude.com/pricing?utm_source=claude_code\&utm_medium=docs\&utm_content=fast_mode_teams#team-&-enterprise) 또는 [Enterprise](https://anthropic.com/contact-sales?utm_source=claude_code\&utm_medium=docs\&utm_content=fast_mode_enterprise) 요금제의 Owner는 [서버 관리 설정](https://code.claude.com/docs/ko/server-managed-settings.md)을 통해 조직 전체에 배포할 수 있습니다.226모든 세션이 빠른 모드가 꺼진 상태로 시작되도록 하려면 [설정 파일](https://code.claude.com/docs/ko/settings.md#where-settings-live)에서 `fastModePerSessionOptIn`을 `true`로 설정합니다. 그러면 사용자는 각 세션에서 `/fast`로 빠른 모드를 활성화합니다. [Team](https://claude.com/pricing?utm_source=claude_code\&utm_medium=docs\&utm_content=fast_mode_teams#team-&-enterprise) 또는 [Enterprise](https://anthropic.com/contact-sales?utm_source=claude_code\&utm_medium=docs\&utm_content=fast_mode_enterprise) 요금제의 Owner는 [서버 관리 설정](https://code.claude.com/docs/ko/server-managed-settings.md)을 통해 조직 전체에 배포할 수 있습니다.

205 227 

227세션 중에 사용 크레딧이 부족하면 Claude Code는 거부된 각 빠른 모드 요청을 표준 속도 및 가격으로 재시도하므로 계속 작업할 수 있으며 쿨다운이 없습니다. 거부 사항을 보는 방식은 세션 유형에 따라 다릅니다:249세션 중에 사용 크레딧이 부족하면 Claude Code는 거부된 각 빠른 모드 요청을 표준 속도 및 가격으로 재시도하므로 계속 작업할 수 있으며 쿨다운이 없습니다. 거부 사항을 보는 방식은 세션 유형에 따라 다릅니다:

228 250 

229* 대화형 세션에서 Claude Code는 "Fast mode disabled · Out of usage credits" 알림을 표시하고 빠른 모드를 끕니다. 저장된 빠른 모드 기본 설정은 변경되지 않습니다. `/fast`를 실행하여 빠른 모드를 다시 켭니다.251* 대화형 세션에서 Claude Code는 "Fast mode disabled · Out of usage credits" 알림을 표시하고 빠른 모드를 끕니다. 저장된 빠른 모드 기본 설정은 변경되지 않습니다. `/fast`를 실행하여 빠른 모드를 다시 켭니다.

230* [비대화형 모드](https://code.claude.com/docs/ko/headless.md)에서 `--output-format stream-json`을 사용하고 Agent SDK를 통해 Claude Code는 메시지 스트림에서 `system` 메시지로 동일한 텍스트를 subtype `notification`으로 내보내며, 사용 크레딧이 부족한 동안 턴당 한 번씩 표시됩니다. 빠른 모드는 켜진 상태로 유지됩니다. Claude Code v2.1.221 이상이 필요합니다.252* `--output-format stream-json`을 사용하는 [비대화형 모드](https://code.claude.com/docs/ko/headless.md)와 Agent SDK를 통해서는 Claude Code가 메시지 스트림에서 동일한 텍스트를 subtype이 `notification`인 `system` 메시지로 내보냅니다. 이 메시지는 사용량 크레딧이 부족한 동안 턴당 한 번씩 전달됩니다. 빠른 모드는 켜진 상태로 유지됩니다.

231 253 

232## 연구 미리보기254## 연구 미리보기

233 255 

Details

93 <td>✓ (Opus 5 및 4.8은 프로비저닝 필요)</td>93 <td>✓ (Opus 5 및 4.8은 프로비저닝 필요)</td>

94 <td>✗</td>94 <td>✗</td>

95 <td>✗</td>95 <td>✗</td>

96 <td>✗</td>96 <td>✓ ([Fable 5.2, 조건부](https://code.claude.com/docs/ko/fast-mode.md#use-fast-mode-on-agent-platform))</td>

97 <td>✗</td>97 <td>✗</td>

98 </tr>98 </tr>

99 99 

256 256 

257> [tab] Google Cloud의 Agent Platform257> [tab] Google Cloud의 Agent Platform

258>258>

259> **사용 불가능:** 모든 [Claude 구독이 필요한 기능](#features-that-require-a-claude-subscription), 그리고 [빠른 모드](https://code.claude.com/docs/ko/fast-mode.md), [Advisor](https://code.claude.com/docs/ko/advisor.md), [Channels](https://code.claude.com/docs/ko/channels.md), [분석 대시보드](https://code.claude.com/docs/ko/analytics.md), [서버 관리 설정](https://code.claude.com/docs/ko/server-managed-settings.md), [`/design-sync` 및 `/import` 명령](https://code.claude.com/docs/ko/commands#all-commands).259> **사용 불가능:** 모든 [Claude 구독이 필요한 기능](#features-that-require-a-claude-subscription), 그리고 [Advisor](https://code.claude.com/docs/ko/advisor.md), [채널](https://code.claude.com/docs/ko/channels.md), [분석 대시보드](https://code.claude.com/docs/ko/analytics.md), [서버 관리 설정](https://code.claude.com/docs/ko/server-managed-settings.md), [`/design-sync` 및 `/import` 명령](https://code.claude.com/docs/ko/commands#all-commands).

260>260>

261> **부분 지원:**261> **부분 지원:**

262>262>

263> * [Desktop](https://code.claude.com/docs/ko/desktop.md): [관리되는 설정](https://claude.com/docs/third-party/claude-desktop/configuration) 또는 [Claude Desktop on 3P](https://claude.com/docs/third-party/claude-desktop/overview)를 통해263> * [Desktop](https://code.claude.com/docs/ko/desktop.md): [관리되는 설정](https://claude.com/docs/third-party/claude-desktop/configuration) 또는 [Claude Desktop on 3P](https://claude.com/docs/third-party/claude-desktop/overview)를 통해

264> * [웹 검색](https://code.claude.com/docs/ko/tools-reference.md#websearch-tool-behavior): Opus 4, Sonnet 4, Haiku 4.5 및 이후 모델264> * [웹 검색](https://code.claude.com/docs/ko/tools-reference.md#websearch-tool-behavior): Opus 4, Sonnet 4, Haiku 4.5 및 이후 모델

265> * [빠른 모드](https://code.claude.com/docs/ko/fast-mode.md#use-fast-mode-on-agent-platform): `global`, `us`, `eu` 리전의 Fable 5.2, 또는 Agent Platform이 빠른 모드를 거부하는 경우 표준 속도

265> * [자동 모드](https://code.claude.com/docs/ko/auto-mode-config.md): Sonnet 5 이상, Opus 4.7 이상, Haiku 5.5, Fable 모델만266> * [자동 모드](https://code.claude.com/docs/ko/auto-mode-config.md): Sonnet 5 이상, Opus 4.7 이상, Haiku 5.5, Fable 모델만

266> * [교차 세션 메시징](https://code.claude.com/docs/ko/cross-session-messaging.md): 이 머신의 세션 간만 <sup>[5](#fn5)</sup>267> * [교차 세션 메시징](https://code.claude.com/docs/ko/cross-session-messaging.md): 이 머신의 세션 간만 <sup>[5](#fn5)</sup>

267> * [Zero Data Retention](https://code.claude.com/docs/ko/zero-data-retention.md): Google Cloud 계약에 따름268> * [Zero Data Retention](https://code.claude.com/docs/ko/zero-data-retention.md): Google Cloud 계약에 따름

gateways.md +1 −1

Details

50 50 

51## 구독 및 게이트웨이51## 구독 및 게이트웨이

52 52 

53개발자가 게이트웨이 자격 증명을 사용하여 게이트웨이를 통해 연결할 때, 사용량은 API 요금으로 조직의 제공자 계정에 청구되며, 해당 claude.ai 구독은 사용되거나 청구되지 않습니다. 실행 중인 게이트웨이에 대해 [`ANTHROPIC_AUTH_TOKEN`](https://code.claude.com/docs/ko/env-vars)을 설정하거나 `/login`을 사용하여 Claude 앱 게이트웨이에 로그인하면 해당 세션에 대한 구독 로그인이 비활성화됩니다. 해당 자격 증명으로 전달된 모든 요청은 게이트웨이의 제공자 자격 증명 뒤의 계정에 청구됩니다.53개발자가 게이트웨이 자격 증명을 사용하여 게이트웨이를 통해 연결할 때, 사용량은 API 요금으로 조직의 제공자 계정에 청구되며, 해당 claude.ai 구독은 사용되거나 청구되지 않습니다. 해당 자격 증명으로 전달된 모든 요청은 게이트웨이의 제공자 자격 증명 뒤의 계정에 청구됩니다.

54 54 

55예외는 게이트웨이 자격 증명 없이 `ANTHROPIC_BASE_URL`만 설정하는 경우입니다. 요청은 여전히 게이트웨이를 통해 라우팅되지만, 저장된 claude.ai 로그인은 활성 자격 증명으로 유지되므로 구독의 사용량 제한 및 청구가 적용됩니다. [다른 LLM 게이트웨이](https://code.claude.com/docs/ko/llm-gateway#subscriptions-and-gateways)에서 해당 구성 및 작동하기 위해 게이트웨이가 전달해야 할 사항을 다룹니다.55예외는 게이트웨이 자격 증명 없이 `ANTHROPIC_BASE_URL`만 설정하는 경우입니다. 요청은 여전히 게이트웨이를 통해 라우팅되지만, 저장된 claude.ai 로그인은 활성 자격 증명으로 유지되므로 구독의 사용량 제한 및 청구가 적용됩니다. [다른 LLM 게이트웨이](https://code.claude.com/docs/ko/llm-gateway#subscriptions-and-gateways)에서 해당 구성 및 작동하기 위해 게이트웨이가 전달해야 할 사항을 다룹니다.

56 56 

Details

135| Merge queues | 읽기 |135| Merge queues | 읽기 |

136| Metadata | 읽기 |136| Metadata | 읽기 |

137| Pull requests | 읽기 및 쓰기 |137| Pull requests | 읽기 및 쓰기 |

138| Repository creation | 읽기 및 쓰기 |

138| Repository hooks | 읽기 및 쓰기 |139| Repository hooks | 읽기 및 쓰기 |

139| Statuses | 읽기 |140| Statuses | 읽기 |

140| Workflows | 읽기 및 쓰기 |141| Workflows | 읽기 및 쓰기 |

Details

190몇 가지 기능은 GHES에서 github.com과 다르게 동작합니다. [기능 표](#what-works-with-github-enterprise-server)는 지원을 요약합니다. 이 섹션에서는 해결 방법을 다룹니다.190몇 가지 기능은 GHES에서 github.com과 다르게 동작합니다. [기능 표](#what-works-with-github-enterprise-server)는 지원을 요약합니다. 이 섹션에서는 해결 방법을 다룹니다.

191 191 

192* **`/install-github-app` 명령**: claude.ai에서 [관리자 설정](#admin-setup) 흐름을 따릅니다. GHES에서 GitHub Actions 워크플로우도 원하는 경우 [예제 워크플로우](https://github.com/anthropics/claude-code-action/blob/main/examples/claude.yml)를 수동으로 조정합니다.192* **`/install-github-app` 명령**: claude.ai에서 [관리자 설정](#admin-setup) 흐름을 따릅니다. GHES에서 GitHub Actions 워크플로우도 원하는 경우 [예제 워크플로우](https://github.com/anthropics/claude-code-action/blob/main/examples/claude.yml)를 수동으로 조정합니다.

193* **GitHub MCP 서버**: 대신 GHES 호스트에 대해 구성된 `gh` CLI를 사용합니다. `gh auth login --hostname github.example.com`을 실행하여 인증한 다음 Claude는 세션에서 `gh` 명령을 사용할 수 있습니다.193* **GitHub MCP 서버**: 자신의 머신에서 실행하는 세션에서는 대신 GHES 호스트에 대해 구성된 `gh` CLI를 사용합니다. `gh auth login --hostname github.example.com`을 실행하여 인증하면 Claude가 해당 세션에서 `gh` 명령을 사용할 수 있습니다.

194 194 

195## 문제 해결195## 문제 해결

196 196 

goal.md +3 −2

Details

131 131 

132#### 수정해야 하는 오류가 목표를 지웁니다132#### 수정해야 하는 오류가 목표를 지웁니다

133 133 

134턴이 수정할 때까지 지워지지 않는 오류로 실패하면 Claude Code는 목표를 지우고 원인을 명시하는 경고를 출력합니다. 경고는 `Goal cleared after an unrecoverable error`로 시작하고 `Run /goal again to continue`로 끝납니다. 원인을 수정한 후 `/goal <condition>`으로 [목표를 다시 설정](#set-a-goal)하십시오. 네 가지 종류의 실패가 목표를 지웁니다:134턴이 수정할 때까지 지워지지 않는 오류로 실패하면 Claude Code는 목표를 지우고 원인을 명시하는 경고를 출력합니다. 경고는 `Goal cleared after an unrecoverable error`로 시작하고 `Run /goal again to continue`로 끝납니다. 원인을 수정한 후 `/goal <condition>`으로 [목표를 다시 설정](#set-a-goal)하십시오. 목표를 지우는 실패에는 다음이 포함됩니다:

135 135 

136* Claude Code가 자체 자격 증명을 관리할 때의 인증 실패입니다. 데스크톱 앱 또는 [클라우드 세션](https://code.claude.com/docs/ko/claude-code-on-the-web.md)과 같이 호스트가 자격 증명을 관리하는 경우 Claude Code는 호스트가 자체적으로 액세스를 복원하기 때문에 목표를 활성 상태로 유지합니다.136* Claude Code가 자체 자격 증명을 관리할 때의 인증 실패입니다. 데스크톱 앱 또는 [클라우드 세션](https://code.claude.com/docs/ko/claude-code-on-the-web.md)과 같이 호스트가 자격 증명을 관리하는 경우 Claude Code는 호스트가 자체적으로 액세스를 복원하기 때문에 목표를 활성 상태로 유지합니다.

137* Claude Code가 자체 자격 증명을 관리할 때 디스크가 가득 차서 Claude Code가 claude.ai 로그인을 갱신할 수 없는 경우입니다. 경고에 `(disk full)`이 표시됩니다. [Claude Code 구성 디렉터리가 있는 디스크의 공간을 확보하십시오](https://code.claude.com/docs/ko/errors.md#could-not-refresh-your-login-disk-full).

137* 소진된 크레딧 잔액138* 소진된 크레딧 잔액

138* [자동 압축](https://code.claude.com/docs/ko/model-config.md#set-the-auto-compact-window)이 지울 수 없는 컨텍스트 오버플로우139* [자동 압축](https://code.claude.com/docs/ko/model-config.md#set-the-auto-compact-window)이 지울 수 없는 컨텍스트 오버플로우

139* 사용할 수 없는 모델140* 사용할 수 없는 모델

178 179 

179## 요구 사항180## 요구 사항

180 181 

181Claude Code는 평가자가 hooks 시스템의 일부이기 때문에 [`settings 파일의 hooks와 동일한 워크스페이스 신뢰 규칙`](https://code.claude.com/docs/ko/permissions#what-runs-before-you-trust-a-folder)에서 `/goal`을 사용 가능하게 합니다. [`disableAllHooks`](https://code.claude.com/docs/ko/hooks#disable-or-remove-hooks)가 설정 우선순위 적용 후 `true`이거나 관리 설정에서 [`allowManagedHooksOnly`](https://code.claude.com/docs/ko/settings-reference#allowmanagedhooksonly)가 설정되면 `/goal`도 사용할 수 없습니다. 각 경우에 명령은 조용히 아무것도 하지 않는 대신 이유를 알려줍니다.182Claude Code는 평가자가 훅 시스템의 일부이기 때문에 [설정 파일의 훅과 동일한 워크스페이스 신뢰 규칙](https://code.claude.com/docs/ko/permissions.md#what-runs-before-you-trust-a-folder)에 따라 `/goal`을 사용할 수 있게 합니다. [`disableAllHooks`](https://code.claude.com/docs/ko/hooks#disable-or-remove-hooks)가 설정 우선순위 적용 후 `true`이거나 관리형 설정에서 [`allowManagedHooksOnly`](https://code.claude.com/docs/ko/settings-reference#allowmanagedhooksonly)가 설정된 경우에도 `/goal`을 사용할 수 없습니다.

182 183 

183## 참고 항목184## 참고 항목

184 185 

Details

134 134 

135요금 한도를 높이려면 Google Cloud 지원팀에 문의합니다. Google Cloud의 Agent Platform을 사용할 때 `/logout` 명령은 Google Cloud 자격증명을 통해 인증이 처리되므로 사용할 수 없습니다.135요금 한도를 높이려면 Google Cloud 지원팀에 문의합니다. Google Cloud의 Agent Platform을 사용할 때 `/logout` 명령은 Google Cloud 자격증명을 통해 인증이 처리되므로 사용할 수 없습니다.

136 136 

137Claude Code는 [MCP 도구 검색](https://code.claude.com/docs/ko/mcp.md#scale-with-mcp-tool-search)과 사전 로딩 중에서 모델 생성에 따라 결정합니다:137Claude Code는 [MCP 도구 검색](https://code.claude.com/docs/ko/mcp.md#scale-with-mcp-tool-search)과 사전 로딩 중에서 모델 세대에 따라 결정합니다:

138 138 

139* **Claude Opus 4.5, Sonnet 4.5, Haiku 4.5 및 이후 버전**: Claude Code는 기본적으로 도구 검색을 활성화합니다.139* **Claude Opus 4.5, Sonnet 4.5, Haiku 4.5 및 이후 버전**: Claude Code는 기본적으로 도구 검색을 활성화합니다.

140* **이전 모델**: Claude Code는 필요한 베타 헤더를 거부하는 Agent Platform 서빙 스택 때문에 MCP 도구 정의를 사전에 로드합니다. `ENABLE_TOOL_SEARCH=true`를 설정해도 이를 재정의하지 않습니다.140* **이전 모델**: Claude Code는 필요한 베타 헤더를 거부하는 Agent Platform 서빙 스택 때문에 MCP 도구 정의를 사전에 로드합니다. `ENABLE_TOOL_SEARCH=true`를 설정해도 이를 재정의하지 않습니다.

141 141 

142모든 모델에서 도구 검색을 비활성화하려면 `ENABLE_TOOL_SEARCH=false`를 설정합니다. v2.1.221 이전에는 Claude Code가 `ENABLE_TOOL_SEARCH=true`를 설정하지 않는 한 Google Cloud의 Agent Platform의 모든 모델에 대해 도구 검색을 비활성화했습니다.142모든 모델에서 도구 검색을 비활성화하려면 `ENABLE_TOOL_SEARCH=false`를 설정합니다.

143 143 

144### 모델 버전 고정144### 모델 버전 고정

145 145 

hooks.md +28 −4

Details

572 572 

573Claude Code는 도구의 텍스트 콘텐츠를 명령 훅 stdout과 동일한 방식으로 읽으며, [종료 코드 0 아래의 파싱 규칙](#exit-code-0)을 따릅니다. 도구가 `isError: true`를 반환하면 훅은 차단하지 않는 오류를 생성하고 실행이 계속됩니다.573Claude Code는 도구의 텍스트 콘텐츠를 명령 훅 stdout과 동일한 방식으로 읽으며, [종료 코드 0 아래의 파싱 규칙](#exit-code-0)을 따릅니다. 도구가 `isError: true`를 반환하면 훅은 차단하지 않는 오류를 생성하고 실행이 계속됩니다.

574 574 

575훅 오류에 다음 메시지 중 하나가 포함되어 있으면 Claude Code가 도구의 응답을 읽을 수 없었던 것이므로 훅은 판정을 내리지 않았습니다:

576 

577```text theme={null}

578MCP tool "security_scan" on server "my_server" gave no answer that could be read, because a message from the server was too large, so this hook gave no verdict. If this keeps happening, the tool must send a smaller answer.

579MCP tool "security_scan" on server "my_server" answered without its text, which happens when a result is too large, so this hook gave no verdict. If this keeps happening, the tool must send a smaller answer.

580```

581 

582`PreToolUse`에서는 Claude Code가 훅이 검사하던 도구 호출을 거부합니다. `UserPromptSubmit`, `PostToolUse`, `Stop`과 같은 다른 이벤트에서는 이 오류가 차단하지 않는 오류입니다.

583 

584오류가 계속 나타나면 도구에서 반환하는 데이터를 줄이거나, 응답이 더 작아지도록 훅의 [`tool` 또는 `input`](#mcp-tool-hook-fields)을 변경하십시오.

585 

575##### 서버가 아직 연결 중일 때586##### 서버가 아직 연결 중일 때

576 587 

577`PreToolUse` 또는 `Stop`과 같이 훅이 결과를 차단하거나 변경할 수 있는 이벤트에서 Claude Code는 도구를 호출하기 전에 연결 중인 서버를 최대 [`MCP_TIMEOUT`](https://code.claude.com/docs/ko/env-vars)까지, 그리고 훅 자체의 [`timeout`](#common-fields) 내에서 기다립니다. `Notification` 또는 `SessionEnd`와 같은 관찰용 이벤트에서는 기다리지 않습니다.588`PreToolUse` 또는 `Stop`과 같이 훅이 결과를 차단하거나 변경할 수 있는 이벤트에서 Claude Code는 도구를 호출하기 전에 연결 중인 서버를 최대 [`MCP_TIMEOUT`](https://code.claude.com/docs/ko/env-vars)까지, 그리고 훅 자체의 [`timeout`](#common-fields) 내에서 기다립니다. `Notification` 또는 `SessionEnd`와 같은 관찰용 이벤트에서는 기다리지 않습니다.

892 903 

893#### 백그라운드 프로세스를 시작하는 hook904#### 백그라운드 프로세스를 시작하는 hook

894 905 

906hook은 개발 서버와 같이 오래 실행되는 프로그램을 시작하고, 세션이 계속되는 동안 실행 상태로 둘 수 있습니다. hook의 스크립트 또는 [셸 형식](#exec-form-and-shell-form) 명령에서 다음을 수행합니다:

907 

908* 프로그램을 백그라운드에서 실행합니다

909* 프로그램의 stdout과 stderr을 리디렉션합니다. 예를 들어 Bash 명령 `npm run dev > dev-server.log 2>&1 &`은 둘 다 파일로 보냅니다. 리디렉션하지 않으면 [async](#run-hooks-in-the-background)가 아닌 hook은 자체 프로세스가 종료된 후 완료되기까지 최대 10초가 걸립니다.

910 

895명령 hook이 백그라운드 프로세스에서 결정을 내리고 종료하는 경우, Claude Code가 읽기를 멈춘 후에 해당 프로세스가 출력하는 거부는 도구 호출을 차단하지 않습니다. [async](#run-hooks-in-the-background)가 아닌 hook의 경우 Claude Code는 hook 자체 프로세스가 종료된 직후 hook의 출력 읽기를 마칩니다.911명령 hook이 백그라운드 프로세스에서 결정을 내리고 종료하는 경우, Claude Code가 읽기를 멈춘 후에 해당 프로세스가 출력하는 거부는 도구 호출을 차단하지 않습니다. [async](#run-hooks-in-the-background)가 아닌 hook의 경우 Claude Code는 hook 자체 프로세스가 종료된 직후 hook의 출력 읽기를 마칩니다.

896 912 

897백그라운드 프로세스를 시작하기 전에 결정을 출력하고, 해당 프로세스의 stdout과 stderr을 리디렉션합니다. 스크립트가 허용을 출력한 다음 해당 프로세스의 stdout과 stderr을 리디렉션하지 않고 백그라운드 프로세스를 시작하면 Claude Code는 도구 호출을 차단합니다. hook 오류에는 `refusing to honor the suspect capture`가 포함됩니다.913백그라운드 프로세스를 시작하기 전에 결정을 출력하고, 해당 프로세스의 stdout과 stderr을 리디렉션합니다. 스크립트가 허용을 출력한 다음 해당 프로세스의 stdout과 stderr을 리디렉션하지 않고 백그라운드 프로세스를 시작하면 Claude Code는 도구 호출을 차단합니다. hook 오류에는 `stdio went quiet`와 `refusing to honor the suspect capture`가 포함됩니다.

898 914 

899이 `PreToolUse` hook 스크립트는 `policy-check.sh`로 결정을 출력한 다음 백그라운드에서 메트릭을 업로드합니다:915이 `PreToolUse` hook 스크립트는 `policy-check.sh`로 결정을 출력한 다음 백그라운드에서 메트릭을 업로드합니다:

900 916 

1193 1209 

1194* `PreToolUse`: `hookSpecificOutput` 바로 아래의 `updatedInput`은 실행 전에 도구의 인수를 대체합니다. [PreToolUse 결정 제어](#pretooluse-decision-control) 참조1210* `PreToolUse`: `hookSpecificOutput` 바로 아래의 `updatedInput`은 실행 전에 도구의 인수를 대체합니다. [PreToolUse 결정 제어](#pretooluse-decision-control) 참조

1195* `PermissionRequest`: `decision` 객체 내의 `updatedInput`. [PermissionRequest 결정 제어](#permissionrequest-decision-control) 참조1211* `PermissionRequest`: `decision` 객체 내의 `updatedInput`. [PermissionRequest 결정 제어](#permissionrequest-decision-control) 참조

1196* `PostToolUse`: `updatedToolOutput`은 도구의 결과를 대체합니다. [PostToolUse 결정 제어](#posttooluse-decision-control) 참조1212* `PostToolUse`: `updatedToolOutput`은 도구의 결과를 대체합니다. [Cowork](https://claude.com/docs/cowork/overview) 클라우드 세션에서는 도구가 `AskUserQuestion` 또는 `ExitPlanMode`일 때 Claude Code가 `updatedToolOutput`을 무시하며, Claude는 원래 답변 또는 계획을 읽습니다. [PostToolUse 결정 제어](#posttooluse-decision-control) 참조

1197* `UserPromptSubmit`: 프롬프트를 대체할 수 없으며, 프롬프트와 함께 `additionalContext`를 주입하기만 합니다1213* `UserPromptSubmit`: 프롬프트를 대체할 수 없으며, 프롬프트와 함께 `additionalContext`를 주입하기만 합니다

1198 1214 

1199민감 정보 제거나 변환 사용 사례의 경우 나가는 도구 입력은 `PreToolUse`에서, 들어오는 도구 결과는 `PostToolUse`에서 가로채세요.1215민감 정보 제거나 변환 사용 사례의 경우 나가는 도구 입력은 `PreToolUse`에서, 들어오는 도구 결과는 `PostToolUse`에서 가로채세요.

2210| `addDirectories` | `directories`, `destination` | 작업 디렉터리를 추가합니다. `directories`는 경로 문자열의 배열입니다 |2226| `addDirectories` | `directories`, `destination` | 작업 디렉터리를 추가합니다. `directories`는 경로 문자열의 배열입니다 |

2211| `removeDirectories` | `directories`, `destination` | 작업 디렉터리를 제거합니다 |2227| `removeDirectories` | `directories`, `destination` | 작업 디렉터리를 제거합니다 |

2212 2228 

2229`rules`에서, `Tool(specifier)` 형식으로 작성된 [권한 규칙](https://code.claude.com/docs/ko/permissions.md#permission-rule-syntax)의 경우 `toolName`은 도구의 이름이고 `ruleContent`는 지정자입니다.

2230 

2231* `Bash(npm test)`: `{ "toolName": "Bash", "ruleContent": "npm test" }`

2232* `Bash` 또는 `Bash(*)`: 둘 다 도구 전체와 매칭되므로 `{ "toolName": "Bash" }`

2233* `mcp__github__get_issue`: `{ "toolName": "mcp__github__get_issue" }`

2234 

2235[MCP 도구](https://code.claude.com/docs/ko/permissions.md#mcp)에 대한 허용 규칙에서는 `ruleContent`를 생략합니다. 추가하면 해당 규칙은 어떤 호출과도 매칭되지 않습니다.

2236 

2213> [!NOTE]2237> [!NOTE]

2214>2238>

2215> `bypassPermissions`를 지정한 `setMode`는 우회 모드를 이미 사용할 수 있는 상태로 세션을 시작한 경우에만 적용됩니다. 즉 `--dangerously-skip-permissions`, `--permission-mode bypassPermissions`, `--allow-dangerously-skip-permissions`, 또는 [사용자, `--settings` 또는 관리형 설정](https://code.claude.com/docs/ko/settings-reference#permissions-defaultmode)의 `permissions.defaultMode: "bypassPermissions"`를 사용한 경우입니다. 그렇지 않으면 업데이트는 아무 효과가 없습니다. [`permissions.disableBypassPermissionsMode`](https://code.claude.com/docs/ko/permissions#managed-settings)가 해당 모드를 비활성화한 경우나 세션이 [제한 모드](https://code.claude.com/docs/ko/cli-reference.md#cli-flags)로 시작된 경우에도 업데이트는 아무 효과가 없습니다.2239> `bypassPermissions`를 지정한 `setMode`는 우회 모드를 이미 사용할 수 있는 상태로 세션을 시작한 경우에만 적용됩니다. 즉 `--dangerously-skip-permissions`, `--permission-mode bypassPermissions`, `--allow-dangerously-skip-permissions`, 또는 [사용자, `--settings` 또는 관리형 설정](https://code.claude.com/docs/ko/settings-reference#permissions-defaultmode)의 `permissions.defaultMode: "bypassPermissions"`를 사용한 경우입니다. 그렇지 않으면 업데이트는 아무 효과가 없습니다. [`permissions.disableBypassPermissionsMode`](https://code.claude.com/docs/ko/permissions#managed-settings)가 해당 모드를 비활성화한 경우나 세션이 [제한 모드](https://code.claude.com/docs/ko/cli-reference.md#cli-flags)로 시작된 경우에도 업데이트는 아무 효과가 없습니다.

2289| `reason` | `decision`이 `"block"`일 때 Claude에게 표시되는 설명입니다 |2313| `reason` | `decision`이 `"block"`일 때 Claude에게 표시되는 설명입니다 |

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

2291| `classifierContext` | Claude가 아닌 [자동 모드](https://code.claude.com/docs/ko/permission-modes.md#eliminate-prompts-with-auto-mode) 분류기를 위한, 이 호출 결과에 대한 짧은 메모입니다. [자동 모드 분류기를 위한 결과 주석 달기](#annotate-a-result-for-the-auto-mode-classifier)를 참조하십시오. Claude Code v2.1.236 이상이 필요합니다 |2315| `classifierContext` | Claude가 아닌 [자동 모드](https://code.claude.com/docs/ko/permission-modes.md#eliminate-prompts-with-auto-mode) 분류기를 위한, 이 호출 결과에 대한 짧은 메모입니다. [자동 모드 분류기를 위한 결과 주석 달기](#annotate-a-result-for-the-auto-mode-classifier)를 참조하십시오. Claude Code v2.1.236 이상이 필요합니다 |

2292| `updatedToolOutput` | Claude에게 전송되기 전에 도구의 출력을 제공된 값으로 대체합니다. 값은 도구의 출력 형태와 일치해야 합니다 |2316| `updatedToolOutput` | Claude에게 전송되기 전에 도구의 출력을 제공된 값으로 대체합니다. 값은 도구의 출력 형태와 일치해야 합니다. [Cowork](https://claude.com/docs/cowork/overview) 클라우드 세션에서 도구가 `AskUserQuestion` 또는 `ExitPlanMode`인 경우 Claude Code는 이 필드를 무시하며, Claude는 원래 답변이나 플랜을 읽습니다 |

2293| `updatedMCPToolOutput` | [MCP 도구](#match-mcp-tools)에 대해서만 출력을 대체합니다. 모든 도구에서 작동하는 `updatedToolOutput`을 사용하는 것이 좋습니다 |2317| `updatedMCPToolOutput` | [MCP 도구](#match-mcp-tools)에 대해서만 출력을 대체합니다. 내장 도구에서도 작동하는 `updatedToolOutput`을 사용하는 것이 좋습니다 |

2294 2318 

2295아래 예시는 `Bash` 호출의 출력을 대체합니다. 대체 값은 `Bash` 도구의 출력 형태와 일치합니다.2319아래 예시는 `Bash` 호출의 출력을 대체합니다. 대체 값은 `Bash` 도구의 출력 형태와 일치합니다.

2296 2320 

hooks-guide.md +1 −1

Details

964 964 

965> [!NOTE]965> [!NOTE]

966>966>

967> 머신에 [관리형 설정](https://code.claude.com/docs/ko/settings.md#check-what-your-organization-enforces)이 없고 세션이 Team 또는 Enterprise 플랜의 [`/login` 자격 증명](https://code.claude.com/docs/ko/authentication#authentication-precedence)을 사용하지 않는 경우, [mod](https://code.claude.com/docs/ko/plugins/mods/overview.md)가 `PreToolUse` 훅이 차단한 호출을 승인할 수 있습니다. 대신 API 키나 장기 [`CLAUDE_CODE_OAUTH_TOKEN`](https://code.claude.com/docs/ko/authentication#generate-a-long-lived-token)으로 실행되는 세션은 해당 로그인이 저장되어 있더라도 그 로그인을 사용하지 않는 것입니다.967> 머신에 [관리형 설정](https://code.claude.com/docs/ko/settings.md#check-what-your-organization-enforces)과 [`managed-mcp.json` 파일](https://code.claude.com/docs/ko/managed-mcp#deploy-managed-mcp-json)이 없고, 세션이 Team 또는 Enterprise 플랜의 [`/login` 자격 증명](https://code.claude.com/docs/ko/authentication#authentication-precedence)을 사용하지 않을 수 있습니다. 이러한 환경에서는 [mod](https://code.claude.com/docs/ko/plugins/mods/overview.md)가 `PreToolUse` 훅이 차단한 호출을 승인할 수 있습니다. 대신 API 키나 장기 [`CLAUDE_CODE_OAUTH_TOKEN`](https://code.claude.com/docs/ko/authentication#generate-a-long-lived-token)으로 실행되는 세션은 해당 로그인이 저장되어 있더라도 그 로그인을 사용하지 않는 것입니다.

968>968>

969> 플랜 모드에서 mod는 이렇게 차단된 호출이 읽기 전용인 경우에만 승인할 수 있으므로 파일 편집은 승인할 수 없습니다. mod의 승인이 규칙과 훅을 넘어서지 못하는 경우는 [훅으로 권한 확장](https://code.claude.com/docs/ko/permissions.md#precedence-among-rules-hooks-and-mods)을 참조하십시오.969> 플랜 모드에서 mod는 이렇게 차단된 호출이 읽기 전용인 경우에만 승인할 수 있으므로 파일 편집은 승인할 수 없습니다. mod의 승인이 규칙과 훅을 넘어서지 못하는 경우는 [훅으로 권한 확장](https://code.claude.com/docs/ko/permissions.md#precedence-among-rules-hooks-and-mods)을 참조하십시오.

970 970 

Details

251| `d`/`x` | 선택 삭제 |251| `d`/`x` | 선택 삭제 |

252| `y` | 선택 야앙크 |252| `y` | 선택 야앙크 |

253| `c`/`s` | 선택 변경 |253| `c`/`s` | 선택 변경 |

254| `p` | 선택을 레지스터 내용으로 바꾸기 |254| `p`/`P` | 선택을 레지스터 내용으로 바꾸기 |

255| `r{char}` | 선택된 모든 문자를 `{char}`로 바꾸기 |255| `r{char}` | 선택된 모든 문자를 `{char}`로 바꾸기 |

256| `~`/`u`/`U` | 선택 전환, 소문자 또는 대문자 |256| `~`/`u`/`U` | 선택 전환, 소문자 또는 대문자 |

257| `>`/`<` | 선택된 줄 들여쓰기 또는 내어쓰기 |257| `>`/`<` | 선택된 줄 들여쓰기 또는 내어쓰기 |

304 304 

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

306 306 

307오류 로그처럼 길게 붙여넣은 내용만 기억나는 이전 프롬프트를 찾으려면 `Ctrl+R`을 누르고 붙여넣은 내용에 있던 단어를 입력합니다. Claude Code v2.1.314 이상이 필요합니다.

308 

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

308 310 

309Claude Code는 백그라운드에서 Bash 명령어를 실행할 수 있으므로, 오래 걸리는 프로세스가 실행되는 동안 계속 작업할 수 있습니다.311Claude Code는 백그라운드에서 Bash 명령어를 실행할 수 있으므로, 오래 걸리는 프로세스가 실행되는 동안 계속 작업할 수 있습니다.

keybindings.md +8 −8

Details

10 10 

11## 구성 파일11## 구성 파일

12 12 

13keybindings 구성 파일은 `bindings` 배열이 있는 객체입니다. 각 블록은 컨텍스트와 키 입력을 작업에 매핑하는 맵을 지정합니다.13키보드 단축키 구성 파일은 `bindings` 배열을 가진 객체입니다. 각 블록은 컨텍스트와, 키 입력을 작업에 매핑하는 맵을 지정합니다.

14 14 

15> [!NOTE]15> [!NOTE]

16>16>

17> keybindings 파일의 변경 사항은 자동으로 감지되고 Claude Code를 다시 시작하지 않고도 적용됩니다.17> 키보드 단축키 파일의 변경 사항은 Claude Code를 다시 시작하지 않아도 자동으로 감지되어 적용됩니다.

18 18 

19| 필드 | 설명 |19| 필드 | 설명 |

20| :- | :- |20| :- | :- |

21| `$schema` | 편집기 자동 완성을 위한 선택적 JSON Schema URL |21| `$schema` | 편집기 자동 완성을 위한 선택적 JSON 스키마 URL |

22| `$docs` | 선택적 설명서 URL |22| `$docs` | 선택적 문서 URL |

23| `bindings` | 컨텍스트별 바인딩 블록 배열 |23| `bindings` | 컨텍스트별 바인딩 블록의 배열 |

24 24 

25이 예제는 채팅 컨텍스트에서 `Ctrl+E`를 외부 편집기를 열기에 바인딩하고 `Ctrl+S`를 바인딩 해제합니다:25다음 예시는 채팅 컨텍스트에서 외부 편집기를 여는 작업에 `Ctrl+E`를 바인딩하고, `Ctrl+S`의 바인딩을 해제합니다.

26 26 

27```json theme={null}27```json theme={null}

28{28{

29 "$schema": "https://www.schemastore.org/claude-code-keybindings.json",29 "$schema": "https://www.schemastore.org/claude-code-keybindings.json",

30 "$docs": "https://code.claude.com/docs/ko/keybindings",30 "$docs": "https://code.claude.com/docs/en/keybindings",

31 "bindings": [31 "bindings": [

32 {32 {

33 "context": "Chat",33 "context": "Chat",

305 305 

306### 차이 작업306### 차이 작업

307 307 

308이 작업들은 `/plugin`에서 [`cc-plugin-diff` mod](https://code.claude.com/docs/ko/plugins/mods/overview#mods-built-into-claude-code)를 비활성화한 후 [전체 화면 렌더링](https://code.claude.com/docs/ko/fullscreen.md) 외부에서 `/diff`가 여는 Claude Code의 이전 diff 뷰어에서만 작동합니다. 해당 mod가 활성화되어 있는 동안에는 `/diff`가 대신 [diff 대화 상자](https://code.claude.com/docs/ko/interactive-mode.md#diff-dialog)를 엽니다. 이 작업들을 지정하는 `keybindings.json`은 어느 경우든 오류 없이 로드됩니다.308이 작업들은 `/plugin`에서 [`cc-plugin-diff` mod](https://code.claude.com/docs/ko/plugins/mods/overview#mods-built-into-claude-code)를 비활성화한 후 [전체 화면 렌더링](https://code.claude.com/docs/ko/fullscreen.md) 외부에서 `/diff`가 여는 Claude Code의 이전 diff 뷰어에서만 작동합니다. 해당 mod가 활성화되어 있는 동안에는 `/diff`가 대신 [diff 대화 상자](https://code.claude.com/docs/ko/interactive-mode.md#diff-dialog)를 엽니다.

309 309 

310`DiffDialog` 컨텍스트에서 사용 가능한 작업:310`DiffDialog` 컨텍스트에서 사용 가능한 작업:

311 311 

Details

197* `Marketplace "claude-plugins-official" not found`: `/plugin marketplace add anthropics/claude-plugins-official`로 마켓플레이스를 추가한 후 설치를 다시 시도합니다.197* `Marketplace "claude-plugins-official" not found`: `/plugin marketplace add anthropics/claude-plugins-official`로 마켓플레이스를 추가한 후 설치를 다시 시도합니다.

198* `Plugin "<name>" not found in marketplace "claude-plugins-official"`: 로컬에 있는 마켓플레이스 카탈로그 사본이 오래되었을 수 있습니다. `/plugin marketplace update claude-plugins-official`로 카탈로그를 새로 고친 후 설치를 다시 시도합니다. 재시도 시에도 같은 메시지가 출력되면 [Plugin not found in marketplace](https://code.claude.com/docs/ko/plugins/troubleshooting.md#plugin-not-found-in-marketplace)를 참조하세요.198* `Plugin "<name>" not found in marketplace "claude-plugins-official"`: 로컬에 있는 마켓플레이스 카탈로그 사본이 오래되었을 수 있습니다. `/plugin marketplace update claude-plugins-official`로 카탈로그를 새로 고친 후 설치를 다시 시도합니다. 재시도 시에도 같은 메시지가 출력되면 [Plugin not found in marketplace](https://code.claude.com/docs/ko/plugins/troubleshooting.md#plugin-not-found-in-marketplace)를 참조하세요.

199 199 

200본인만 설치하는 대신 저장소의 모든 사람을 위해 플러그인을 활성화하려면, [`enabledPlugins` 프로젝트 설정](https://code.claude.com/docs/ko/settings-reference#plugin-settings)에 추가합니다.200저장소의 모든 사람을 위해 플러그인을 켜려면 [`enabledPlugins` 프로젝트 설정](https://code.claude.com/docs/ko/settings-reference#plugin-settings)에 추가합니다. 그래도 각 사용자가 [직접 설치해야 합니다](https://code.claude.com/docs/ko/plugins/loading.md#enabled-in-project-settings-but-not-installed).

201 201 

202코드 인텔리전스 플러그인은 각 개발자의 머신에 언어의 언어 서버 바이너리가 필요합니다. [각 언어가 필요로 하는 바이너리](https://code.claude.com/docs/ko/plugins/code-intelligence.md)를 참조하세요. 공식 마켓플레이스에서 설치하려면 마켓플레이스가 호스팅되는 GitHub에 대한 네트워크 액세스가 필요합니다. 제한된 네트워크에서는 대신 [내부 Git 호스트 또는 로컬 경로에서 마켓플레이스를 추가](https://code.claude.com/docs/ko/plugins/install.md#add-a-marketplace)합니다.202코드 인텔리전스 플러그인은 각 개발자의 머신에 언어의 언어 서버 바이너리가 필요합니다. [각 언어가 필요로 하는 바이너리](https://code.claude.com/docs/ko/plugins/code-intelligence.md)를 참조하세요. 공식 마켓플레이스에서 설치하려면 마켓플레이스가 호스팅되는 GitHub에 대한 네트워크 액세스가 필요합니다. 제한된 네트워크에서는 대신 [내부 Git 호스트 또는 로컬 경로에서 마켓플레이스를 추가](https://code.claude.com/docs/ko/plugins/install.md#add-a-marketplace)합니다.

203 203 

235 235 

236`sparsePaths`에 개별 파일이 아닌 디렉토리를 나열하십시오. `package.json`, `tsconfig.base.json`, 잠금 파일과 같은 루트 수준 파일은 나열한 디렉토리와 함께 항상 체크아웃됩니다. 루트 수준 디렉토리는 그렇지 않으므로 워크트리 내에서 저장소 루트의 `.claude/settings.json` 또는 `.claude/rules/`를 사용 가능하게 하려면 목록에 `.claude`를 포함하십시오. 프로젝트 스킬, 에이전트, 명령에 대해서는 [워크트리가 주 체크아웃과 공유하는 것](https://code.claude.com/docs/ko/worktrees.md#what-worktrees-share-with-the-main-checkout)을 참조하십시오.236`sparsePaths`에 개별 파일이 아닌 디렉토리를 나열하십시오. `package.json`, `tsconfig.base.json`, 잠금 파일과 같은 루트 수준 파일은 나열한 디렉토리와 함께 항상 체크아웃됩니다. 루트 수준 디렉토리는 그렇지 않으므로 워크트리 내에서 저장소 루트의 `.claude/settings.json` 또는 `.claude/rules/`를 사용 가능하게 하려면 목록에 `.claude`를 포함하십시오. 프로젝트 스킬, 에이전트, 명령에 대해서는 [워크트리가 주 체크아웃과 공유하는 것](https://code.claude.com/docs/ko/worktrees.md#what-worktrees-share-with-the-main-checkout)을 참조하십시오.

237 237 

238Sparse checkout을 사용하려면 git이 sparse 워크트리가 존재하는 동안 저장소의 공유 `.git/config`에서 `extensions.worktreeConfig`를 활성화해야 합니다. Claude Code는 마지막 워크트리가 제거된 후 해당 항목을 제거하지만, Claude Code가 추가한 경우에만 제거합니다. 직접 설정한 값은 절대 제거하지 않습니다.238> [!NOTE]

239>

240> Sparse checkout을 사용하려면 git이 sparse 워크트리가 존재하는 동안 저장소의 공유 `.git/config`에서 `extensions.worktreeConfig`를 활성화해야 합니다. Claude Code는 마지막 워크트리가 제거된 후 해당 항목을 제거하지만, Claude Code가 추가한 경우에만 제거합니다.

239 241 

240`node_modules`와 같은 대규모 디렉토리를 워크트리 전체에 중복되지 않도록 하려면 동일한 `.claude/settings.json`에서 `sparsePaths`를 `symlinkDirectories`와 쌍으로 지정하십시오:242`node_modules`와 같은 대규모 디렉토리를 워크트리 전체에 중복되지 않도록 하려면 동일한 `.claude/settings.json`에서 `sparsePaths`를 `symlinkDirectories`와 쌍으로 지정하십시오:

241 243 

Details

156 156 

157### 기존 로그인과의 충돌157### 기존 로그인과의 충돌

158 158 

159게이트웨이 자격 증명 변수는 저장된 claude.ai 로그인 또는 Console 키보다 우선합니다. claude.ai 로그인은 변수가 설정된 동안 저장되고 사용되지 않습니다. 변수를 설정 해제하면 Claude Code는 이로 돌아갑니다. `ANTHROPIC_AUTH_TOKEN`을 사용하면 변수가 즉시 우선합니다. `ANTHROPIC_API_KEY`를 사용하면 대화형 모드에서 키가 인수하기 전에 한 번 승인하도록 요청받습니다.159게이트웨이 자격 증명 변수는 저장된 claude.ai 로그인 또는 Console 키보다 우선합니다. `ANTHROPIC_AUTH_TOKEN`을 사용하면 변수가 즉시 우선합니다. `ANTHROPIC_API_KEY`를 사용하면 대화형 모드에서 키가 인수하기 전에 한 번 승인하도록 요청받습니다.

160 160 

161`/status`를 실행하여 어떤 자격 증명 소스가 활성화되어 있는지 확인합니다. 시작 시 두 소스를 명시하는 인증 충돌 경고가 표시되면, [문제 해결 표](#troubleshoot-gateway-errors)의 첫 번째 행을 참조하여 어느 것을 제거할지 확인합니다. 저장된 로그인을 지워 게이트웨이 자격 증명만 남기려면 `/logout`을 실행합니다.161`/status`를 실행하여 어떤 자격 증명 소스가 활성화되어 있는지 확인합니다. 시작 시 두 소스를 명시하는 인증 충돌 경고가 표시되면, [문제 해결 표](#troubleshoot-gateway-errors)의 첫 번째 행을 참조하여 어느 것을 제거할지 확인합니다. 저장된 로그인을 지워 게이트웨이 자격 증명만 남기려면 `/logout`을 실행합니다.

162 162 

378변수를 설정하면 다음과 같은 효과와 제한이 있습니다:378변수를 설정하면 다음과 같은 효과와 제한이 있습니다:

379 379 

380* 자동 업데이트를 비활성화하므로 패키지 관리자 또는 관리되는 배포와 같은 다른 업데이트 경로를 계획합니다.380* 자동 업데이트를 비활성화하므로 패키지 관리자 또는 관리되는 배포와 같은 다른 업데이트 경로를 계획합니다.

381* [빠른 모드](https://code.claude.com/docs/ko/fast-mode.md) 가용성 확인을 억제합니다. 이전 확인이 이미 머신에서 빠른 모드를 활성화하지 않은 한, `/fast`는 빠른 모드를 사용할 수 없다고 보고합니다.381* [빠른 모드](https://code.claude.com/docs/ko/fast-mode.md) 가용성 확인을 억제합니다. Anthropic API에서 이후 `/fast`가 빠른 모드를 사용할 수 없다고 보고하면, [프록시 및 LLM 게이트웨이 뒤에서 빠른 모드 사용](https://code.claude.com/docs/ko/fast-mode.md#use-fast-mode-behind-proxies-and-llm-gateways)을 참조하여 빠른 모드를 복원하세요.

382* [게이트웨이 모델 검색](#add-gateway-models-to-the-model-picker)에 영향을 주지 않으며, 이는 게이트웨이만 쿼리합니다. v2.1.257 이전에는 변수가 검색이 새로 고쳐지는 것도 중단했으므로 선택기는 이전에 캐시된 목록을 유지했습니다.382* [게이트웨이 모델 검색](#add-gateway-models-to-the-model-picker)에 영향을 주지 않으며, 이는 게이트웨이만 쿼리합니다. v2.1.257 이전에는 변수가 검색이 새로 고쳐지는 것도 중단했으므로 선택기는 이전에 캐시된 목록을 유지했습니다.

383* WebFetch 도구의 [도메인 안전 확인](https://code.claude.com/docs/ko/data-usage.md#webfetch-domain-safety-check)은 영향을 받지 않으며 여전히 `api.anthropic.com`을 호출합니다. 네트워크가 해당 호스트를 차단하는 경우 [설정](https://code.claude.com/docs/ko/settings.md)에서 `skipWebFetchPreflight: true`로 별도로 끕니다.383* WebFetch 도구의 [도메인 안전 확인](https://code.claude.com/docs/ko/data-usage.md#webfetch-domain-safety-check)은 영향을 받지 않으며 여전히 `api.anthropic.com`을 호출합니다. 네트워크가 해당 호스트를 차단하는 경우 [설정](https://code.claude.com/docs/ko/settings.md)에서 `skipWebFetchPreflight: true`로 별도로 끕니다.

384* 각 원격 분석 스트림 및 이를 제어하는 변수는 [원격 분석 서비스](https://code.claude.com/docs/ko/data-usage.md#telemetry-services)를 참조하세요.384* 각 원격 분석 스트림 및 이를 제어하는 변수는 [원격 분석 서비스](https://code.claude.com/docs/ko/data-usage.md#telemetry-services)를 참조하세요.

Details

251 251 

252* 로그인 프롬프트는 자격증명 간격을 의미합니다. `/status`를 실행하고 **Status** 탭을 엽니다. `Setting sources` 줄에 관리되는 설정이 포함되지 않으면 배포가 머신에 도달하지 않았습니다. 포함되면 개발자 자격증명이 배포되지 않았으므로 `ANTHROPIC_AUTH_TOKEN` 또는 `apiKeyHelper`를 설정하십시오.252* 로그인 프롬프트는 자격증명 간격을 의미합니다. `/status`를 실행하고 **Status** 탭을 엽니다. `Setting sources` 줄에 관리되는 설정이 포함되지 않으면 배포가 머신에 도달하지 않았습니다. 포함되면 개발자 자격증명이 배포되지 않았으므로 `ANTHROPIC_AUTH_TOKEN` 또는 `apiKeyHelper`를 설정하십시오.

253* `Failed to authenticate` 오류는 게이트웨이가 요청을 거부함을 의미합니다. 로그는 어느 자격증명이 실패했는지 나타냅니다. 게이트웨이가 자체 로그하는 거부는 개발자 키를 명명하는 반면, `api.anthropic.com` 또는 공급자의 엔드포인트의 `401`은 게이트웨이가 보유한 공급자 자격증명이 거부되었음을 의미합니다.253* `Failed to authenticate` 오류는 게이트웨이가 요청을 거부함을 의미합니다. 로그는 어느 자격증명이 실패했는지 나타냅니다. 게이트웨이가 자체 로그하는 거부는 개발자 키를 명명하는 반면, `api.anthropic.com` 또는 공급자의 엔드포인트의 `401`은 게이트웨이가 보유한 공급자 자격증명이 거부되었음을 의미합니다.

254* 게이트웨이가 `x-api-key` 헤더에서 키를 예상할 때 `ANTHROPIC_API_KEY`로 설정된 키에 대한 일회성 승인 프롬프트는 예상됩니다. `ANTHROPIC_AUTH_TOKEN`을 사용하면 프롬프트가 나타나지 않고 변수가 자동으로 인수합니다. 이전에 저장된 claude.ai 로그인은 해당 세션에 대해 비활성입니다.254* 게이트웨이가 `x-api-key` 헤더에서 키를 예상하여 `ANTHROPIC_API_KEY`로 설정한 경우, 처음 사용할 때 키에 대한 일회성 승인 프롬프트가 나타나는 것은 정상입니다.

255 255 

256조직이 [빠른 모드](https://code.claude.com/docs/ko/fast-mode.md)를 사용하는 경우 여기서 `/fast`도 실행하십시오. 가용성 확인은 게이트웨이 기본 URL을 따르지 않고 `api.anthropic.com`을 직접 호출하므로 게이트웨이 라우팅 세션은 추론이 작동하더라도 빠른 모드를 사용할 수 없거나 비활성화된 것으로 보고할 수 있습니다. [프록시 및 LLM 게이트웨이 뒤에서 빠른 모드 사용](https://code.claude.com/docs/ko/fast-mode.md#use-fast-mode-behind-proxies-and-llm-gateways)은 각 메시지를 복원하는 변수에 매핑하고, [구성의 나머지 부분](#distribute-the-configuration)과 함께 배포됩니다.256조직이 [빠른 모드](https://code.claude.com/docs/ko/fast-mode.md)를 사용하는 경우 여기서 `/fast`도 실행하십시오. 가용성 확인은 게이트웨이 기본 URL을 따르지 않고 `api.anthropic.com`을 직접 호출하므로 게이트웨이 라우팅 세션은 추론이 작동하더라도 빠른 모드를 사용할 수 없거나 비활성화된 것으로 보고할 수 있습니다. [프록시 및 LLM 게이트웨이 뒤에서 빠른 모드 사용](https://code.claude.com/docs/ko/fast-mode.md#use-fast-mode-behind-proxies-and-llm-gateways)은 각 메시지를 복원하는 변수에 매핑하고, [구성의 나머지 부분](#distribute-the-configuration)과 함께 배포됩니다.

257 257 

managed-mcp.md +1 −1

Details

187 187 

188* `type`은 `http` 또는 `sse`입니다. `.mcp.json`에서와 같이 `streamable-http`는 `http`의 별칭으로 허용됩니다.188* `type`은 `http` 또는 `sse`입니다. `.mcp.json`에서와 같이 `streamable-http`는 `http`의 별칭으로 허용됩니다.

189* `url`은 `https://` URL입니다. Claude Code는 `localhost`를 가리키는 것을 포함하여 일반 `http://` URL을 거부합니다.189* `url`은 `https://` URL입니다. Claude Code는 `localhost`를 가리키는 것을 포함하여 일반 `http://` URL을 거부합니다.

190* 항목에 `command`, `args`, `env` 또는 `headersHelper` 멤버가 없으므로, 관리되는 설정 문서는 사용자의 머신에서 실행할 프로그램을 절대 지정하지 않습니다.190* 항목에 `command`, `args`, `env` 또는 `headersHelper` 멤버가 없습니다.

191* 어떤 값도 `${VAR}` 참조를 포함하지 않습니다. Claude Code는 이러한 항목에서 환경 변수를 확장하지 않으므로 리터럴 값을 작성합니다.191* 어떤 값도 `${VAR}` 참조를 포함하지 않습니다. Claude Code는 이러한 항목에서 환경 변수를 확장하지 않으므로 리터럴 값을 작성합니다.

192* 서버 이름은 문자, 숫자, 하이픈 및 밑줄만 포함하고, 어떤 키나 값도 제어 또는 보이지 않는 서식 문자를 포함하지 않습니다.192* 서버 이름은 문자, 숫자, 하이픈 및 밑줄만 포함하고, 어떤 키나 값도 제어 또는 보이지 않는 서식 문자를 포함하지 않습니다.

193 193 

mcp.md +262 −264

Details

60 60 

61## MCP 서버 설치61## MCP 서버 설치

62 62 

63MCP 서버는 필요에 따라 여러 가지 방식으로 구성할 수 있습니다:63MCP 서버는 필요에 따라 여러 방법으로 구성할 수 있습니다.

64 64 

65### 옵션 1: 원격 HTTP 서버 추가65### 옵션 1: 원격 HTTP 서버 추가

66 66 

67HTTP 서버는 원격 MCP 서버에 연결하기 위한 권장 옵션입니다. 이는 클라우드 기반 서비스에 가장 널리 지원되는 전송 방식입니다.67HTTP 서버는 원격 MCP 서버에 연결할 때 권장되는 옵션입니다. 클라우드 기반 서비스에서 가장 널리 지원되는 전송 방식입니다.

68 68 

69```bash theme={null}69```bash theme={null}

70# 기본 구문70# Basic syntax

71claude mcp add --transport http <name> <url>71claude mcp add --transport http <name> <url>

72 72 

73# 실제 예: Notion에 연결73# Real example: Connect to Notion

74claude mcp add --transport http notion https://mcp.notion.com/mcp74claude mcp add --transport http notion https://mcp.notion.com/mcp

75 75 

76# Bearer 토큰을 사용한 예76# Example with Bearer token

77claude mcp add --transport http secure-api https://api.example.com/mcp \77claude mcp add --transport http secure-api https://api.example.com/mcp \

78 --header "Authorization: Bearer your-token"78 --header "Authorization: Bearer your-token"

79```79```

80 80 

81`.mcp.json`, `~/.claude.json` 또는 `claude mcp add-json`을 통해 JSON으로 MCP 서버를 구성할 때, `type` 필드는 `http`의 별칭으로 `streamable-http`를 허용합니다. MCP 사양은 이 전송에 대해 `streamable-http`라는 이름을 사용하므로 서버 설명서에서 복사한 구성이 수정 없이 작동합니다.81`.mcp.json`, `~/.claude.json` 또는 `claude mcp add-json`에서 JSON으로 MCP 서버를 구성할 때 `type` 필드는 `http`의 별칭으로 `streamable-http`를 허용합니다. MCP 사양에서는 이 전송 방식을 `streamable-http`라는 이름으로 부르므로, 서버 문서에서 복사한 구성을 수정 없이 그대로 사용할 수 있습니다.

82 82 

83`url`은 있지만 `type`이 없는 JSON 항목은 구성 오류입니다. Claude Code는 `type`이 없는 항목을 stdio 서버로 읽기 때문입니다. Claude Code는 해당 서버를 건너뛰고 `MCP server "<name>" has a "url" but no "type"; add "type": "http" (or "sse" / "ws") to this entry`를 보고합니다.83`url`은 있지만 `type`이 없는 JSON 항목은 구성 오류입니다. Claude Code는 `type`이 없는 항목을 stdio 서버로 읽기 때문입니다. Claude Code는 해당 서버를 건너뛰고 `MCP server "<name>" has a "url" but no "type"; add "type": "http" (or "sse" / "ws") to this entry`를 보고합니다.

84 84 

85SDK 호스트 애플리케이션 (예: [Agent SDK](https://code.claude.com/docs/ko/agent-sdk/mcp.md) 애플리케이션 또는 [데스크톱 앱](https://code.claude.com/docs/ko/desktop.md))만 인프로세스 `"type": "sdk"` 서버를 등록할 수 있습니다. Claude Code는 `.mcp.json`, `~/.claude.json` 또는 설정의 `"type": "sdk"` 항목을 건너뛰고 `Skipped — MCP server "<name>" declares type "sdk", which only an SDK host application can register`를 보고합니다.85[Agent SDK](https://code.claude.com/docs/ko/agent-sdk/mcp.md) 애플리케이션이나 [데스크톱 앱](https://code.claude.com/docs/ko/desktop.md)과 같은 SDK 호스트 애플리케이션만 인프로세스 `"type": "sdk"` 서버를 등록할 수 있습니다. Claude Code는 `.mcp.json`, `~/.claude.json` 또는 설정에 있는 `"type": "sdk"` 항목을 건너뛰고 `Skipped — MCP server "<name>" declares type "sdk", which only an SDK host application can register`를 보고합니다.

86 86 

87> [!NOTE]87> [!NOTE]

88>88>

89> `--output-format stream-json` 실행에서는 Claude Code가 건너뛴 `--mcp-config` 항목을 `system/init` 이벤트의 [`mcp_server_errors` 필드](https://code.claude.com/docs/ko/headless#stream-responses)에도 보고하므로, 스크립트에서 서버가 로드되지 않았음을 감지할 수 있습니다.89> `--output-format stream-json` 실행에서 Claude Code는 건너뛴 `--mcp-config` 항목을 `system/init` 이벤트의 [`mcp_server_errors` 필드](https://code.claude.com/docs/ko/headless#stream-responses)에도 보고하므로, 스크립트에서 서버가 로드되지 않았음을 감지할 수 있습니다.

90 90 

91### 옵션 2: 원격 SSE 서버 추가91### 옵션 2: 원격 SSE 서버 추가

92 92 

93> [!WARNING]93> [!WARNING]

94>94>

95> SSE (Server-Sent Events) 전송은 더 이상 사용되지 않습니다. 가능한 경우 HTTP 서버를 사용하세요.95> SSE(Server-Sent Events) 전송 방식은 deprecated되었습니다. 가능한 경우 HTTP 서버를 대신 사용하십시오.

96 96 

97일부 서비스는 여전히 SSE 엔드포인트만 노출합니다. [HTTP 서버](#option-1-add-a-remote-http-server)와 동일한 `claude mcp add --transport http <name> <url>` 명령으로 추가하세요. Claude Code는 HTTP 전송을 먼저 시도하고 서버가 이를 허용하지 않을 때 SSE로 전환합니다. 자동 전환에는 Claude Code v2.1.265 이상이 필요합니다.97일부 서비스는 여전히 SSE 엔드포인트만 제공합니다. 이러한 서비스는 [HTTP 서버](#option-1-add-a-remote-http-server)와 동일한 `claude mcp add --transport http <name> <url>` 명령으로 추가합니다. Claude Code는 먼저 HTTP 전송 방식을 시도하고, 서버가 이를 허용하지 않으면 SSE로 전환합니다. 자동 전환에는 Claude Code v2.1.265 이상이 필요합니다.

98 98 

99이전 버전에서 또는 SSE를 통해 직접 연결하려면 대신 `--transport sse`를 전달하세요:99이전 버전을 사용하거나 SSE로 직접 연결하려면 대신 `--transport sse`를 전달합니다.

100 100 

101```bash theme={null}101```bash theme={null}

102# 기본 구문102# Basic syntax

103claude mcp add --transport sse <name> <url>103claude mcp add --transport sse <name> <url>

104 104 

105# 실제 예: Asana에 연결105# Real example: Connect to Asana

106claude mcp add --transport sse asana https://mcp.asana.com/sse106claude mcp add --transport sse asana https://mcp.asana.com/sse

107 107 

108# 인증 헤더를 사용한 예108# Example with authentication header

109claude mcp add --transport sse private-api https://api.company.com/sse \109claude mcp add --transport sse private-api https://api.company.com/sse \

110 --header "X-API-Key: your-key-here"110 --header "X-API-Key: your-key-here"

111```111```

112 112 

113### 옵션 3: 로컬 stdio 서버 추가113### 옵션 3: 로컬 stdio 서버 추가

114 114 

115Stdio 서버는 컴퓨터에서 로컬 프로세스로 실행됩니다. 시스템에 직접 액세스하거나 사용자 정의 스크립트가 필요한 도구에 이상적입니다.115stdio 서버는 사용자 컴퓨터에서 로컬 프로세스로 실행됩니다. 직접적인 시스템 접근이 필요한 도구나 사용자 정의 스크립트에 적합합니다.

116 116 

117Claude Code는 생성된 서버의 환경에서 `CLAUDE_PROJECT_DIR`을 프로젝트 루트로 설정하므로 서버는 작업 디렉터리에 의존하지 않고 프로젝트 상대 경로를 확인할 수 있습니다. 이는 훅이 `CLAUDE_PROJECT_DIR` 변수에서 받는 것과 동일한 디렉터리입니다. 서버 프로세스 내에서 읽으세요. 예를 들어 Node에서는 `process.env.CLAUDE_PROJECT_DIR` 또는 Python에서는 `os.environ["CLAUDE_PROJECT_DIR"]`입니다.117Claude Code는 생성된 서버의 환경에 `CLAUDE_PROJECT_DIR`을 프로젝트 루트로 설정하므로, 서버는 작업 디렉터리에 의존하지 않고 프로젝트 기준 상대 경로를 확인할 수 있습니다. 이는 훅이 `CLAUDE_PROJECT_DIR` 변수로 받는 디렉터리와 동일합니다. 서버 프로세스 내부에서 읽으면 되며, 예를 들어 Node에서는 `process.env.CLAUDE_PROJECT_DIR`, Python에서는 `os.environ["CLAUDE_PROJECT_DIR"]`을 사용합니다.

118 118 

119`CLAUDE_PROJECT_DIR`은 안정적인 프로젝트 루트이며 세션 중에 작업 디렉터리를 추가하거나 제거할 때 변경되지 않습니다. 자신의 파일 시스템 액세스를 허용된 디렉터리 집합으로 제한하는 서버는 대신 MCP `roots/list` 요청을 구현해야 합니다. Claude Code는 `roots/list`에 세션의 시작 디렉터리와 `--add-dir`, `/add-dir` 또는 `additionalDirectories` 설정으로 부여한 모든 [추가 작업 디렉터리](https://code.claude.com/docs/ko/permissions.md#working-directories)로 응답합니다. Claude Code는 해당 집합이 변경될 때 `notifications/roots/list_changed`를 보냅니다.119`CLAUDE_PROJECT_DIR`은 고정된 프로젝트 루트이며, 세션 도중 작업 디렉터리를 추가하거나 제거해도 변경되지 않습니다. 자체 파일 시스템 접근을 허용된 디렉터리 집합으로 제한하는 서버는 대신 MCP `roots/list` 요청을 구현해야 합니다. Claude Code는 `roots/list`에 세션의 시작 디렉터리와 `--add-dir`, `/add-dir` 또는 `additionalDirectories` 설정으로 허용한 모든 [추가 작업 디렉터리](https://code.claude.com/docs/ko/permissions.md#working-directories)를 함께 응답합니다. 해당 집합이 변경되면 Claude Code는 `notifications/roots/list_changed`를 보냅니다.

120 120 

121이 변수는 Claude Code 자체의 환경이 아닌 서버의 환경에 설정되므로 프로젝트 범위 `.mcp.json` 항목 또는 `~/.claude.json`의 로컬 범위 또는 사용자 범위 서버 항목의 `command` 또는 `args`에서 `${VAR}` 확장을 통해 참조하려면 `${CLAUDE_PROJECT_DIR:-.}`와 같은 기본값이 필요합니다. 플러그인 제공 MCP 구성은 `${CLAUDE_PROJECT_DIR}`을 직접 대체하며 기본값이 필요하지 않습니다.121이 변수는 Claude Code 자체의 환경이 아니라 서버의 환경에 설정됩니다. 따라서 프로젝트 범위 `.mcp.json` 항목이나 `~/.claude.json`의 로컬 또는 사용자 범위 서버 항목의 `command` 또는 `args`에서 `${VAR}` 확장으로 참조하려면 `${CLAUDE_PROJECT_DIR:-.}`와 같은 기본값이 필요합니다. 플러그인이 제공하는 MCP 구성은 `${CLAUDE_PROJECT_DIR}`을 직접 치환하므로 기본값이 필요하지 않습니다.

122 122 

123```bash theme={null}123```bash theme={null}

124# 기본 구문124# Basic syntax

125claude mcp add [options] <name> -- <command> [args...]125claude mcp add [options] <name> -- <command> [args...]

126 126 

127# 실제 예: Airtable 서버 추가127# Real example: Add Airtable server

128claude mcp add --env AIRTABLE_API_KEY=YOUR_KEY --transport stdio airtable \128claude mcp add --env AIRTABLE_API_KEY=YOUR_KEY --transport stdio airtable \

129 -- npx -y airtable-mcp-server129 -- npx -y airtable-mcp-server

130```130```

131 131 

132> [!NOTE]132> [!NOTE]

133>133>

134> Stdio 서버의 경우, `--` (이중 대시)는 Claude의 자체 옵션(예: `--transport`, `--env`, `--scope`)과 서버를 실행하는 명령 및 인수를 구분합니다. `--` 이후의 모든 것은 서버에 그대로 전달됩니다.134> stdio 서버의 경우 `--`(이중 대시)는 `--transport`, `--env`, `--scope`와 같은 Claude 자체 옵션을 서버를 실행하는 명령 및 인수와 구분합니다. `--` 뒤의 모든 내용은 그대로 서버에 전달됩니다.

135>135>

136> 예를 들어:136> 예시:

137>137>

138> * `claude mcp add --transport stdio myserver -- npx server` → `npx server` 실행138> * `claude mcp add --transport stdio myserver -- npx server` → `npx server` 실행

139> * `claude mcp add --env KEY=value --transport stdio myserver -- python server.py --port 8080` → 환경에서 `KEY=value`를 사용하여 `python server.py --port 8080` 실행139> * `claude mcp add --env KEY=value --transport stdio myserver -- python server.py --port 8080` → 환경에 `KEY=value`를 설정하고 `python server.py --port 8080` 실행

140>140>

141> `--`가 없으면 Claude Code는 위의 `--port`와 같은 서버의 플래그를 자신의 옵션으로 구문 분석하려고 시도합니다.141> `--`가 없으면 Claude Code는 위의 `--port`와 같은 서버의 플래그를 자체 옵션으로 파싱하려고 합니다.

142>142>

143> `--env`는 여러 `KEY=value` 쌍을 허용합니다. 서버 이름이 `--env` 직후에 오면 CLI는 이름을 다른 쌍으로 읽고 거부하므로 `--env`와 서버 이름 사이에 최소한 하나의 다른 옵션(예: `--transport stdio`)을 배치하세요.143> `--env`는 여러 개의 `KEY=value` 쌍을 허용합니다. 서버 이름이 `--env` 바로 뒤에 오면 CLI는 이름을 또 다른 쌍으로 읽고 거부하므로, `--env`와 서버 이름 사이에 `--transport stdio`와 같은 다른 옵션을 하나 이상 배치하십시오.

144 144 

145#### Claude Code가 stdio 서버를 중지하는 방법145#### Claude Code가 stdio 서버를 중지하는 방법

146 146 

147Claude Code는 세션이 종료될 때와 같이 stdio 서버의 연결을 끊을 때 서버 프로세스에 신호를 보내고, 강제로 중지하기 전에 프로세스가 종료될 때까지 잠시 기다립니다. 서버가 종료 시 상태를 저장하거나 잠금 파일을 제거하는 경우 플랫폼에 맞는 신호를 처리하고 그 시간 내에 완료하세요:147Claude Code가 stdio 서버 연결을 해제할 때(예: 세션이 종료될 때) 서버 프로세스에 신호를 보내고, 강제로 중지하기 전에 프로세스가 종료되기를 잠시 기다립니다. 서버가 종료 시 상태를 저장하거나 잠금 파일을 제거한다면, 플랫폼에 맞는 신호를 처리하고 해당 시간 내에 완료해야 합니다.

148 148 

149* **macOS 및 Linux**: Claude Code는 `SIGINT`를 보내고, 100밀리초 후에도 프로세스가 실행 중이면 `SIGTERM`을, 그로부터 400밀리초가 더 지나면 `SIGKILL`을 보냅니다.149* **macOS 및 Linux**: Claude Code는 `SIGINT`를 보내고, 100밀리초 후에도 프로세스가 실행 중이면 `SIGTERM`을, 그 후 400밀리초가 더 지나면 `SIGKILL`을 보냅니다.

150* **Windows**: Claude Code는 서버의 stdin을 닫고, 300밀리초 후에도 프로세스가 실행 중이면 서버의 프로세스 트리를 종료합니다.150* **Windows**: Claude Code는 서버의 stdin을 닫고, 300밀리초 후에도 프로세스가 실행 중이면 서버의 프로세스 트리를 종료합니다.

151 151 

152v2.1.296 이전에는 Windows의 Claude Code가 stdin을 먼저 닫거나 기다리지 않고 서버의 프로세스 트리를 즉시 종료했습니다.152v2.1.296 이전에는 Windows의 Claude Code가 stdin을 먼저 닫거나 기다리지 않고 서버의 프로세스 트리를 즉시 종료했습니다.

153 153 

154### 옵션 4: 원격 WebSocket 서버 추가154### 옵션 4: 원격 WebSocket 서버 추가

155 155 

156WebSocket 서버는 지속적인 양방향 연결을 유지하므로 Claude에 예고 없이 이벤트를 푸시하는 원격 MCP 서버에 적합합니다. 서버가 요청에만 응답하는 경우 HTTP를 대신 사용하세요. HTTP는 OAuth 및 `claude mcp add --transport` 플래그를 지원하지만 WebSocket은 둘 다 지원하지 않습니다.156WebSocket 서버는 지속적인 양방향 연결을 유지하므로, 요청 없이 Claude에 이벤트를 푸시하는 원격 MCP 서버에 적합합니다. 서버가 요청에만 응답한다면 HTTP를 대신 사용하십시오. HTTP는 OAuth와 `claude mcp add --transport` 플래그를 지원하지만, WebSocket은 둘 다 지원하지 않습니다.

157 157 

158`.mcp.json` 또는 `claude mcp add-json`으로 WebSocket 서버를 구성하세요:158WebSocket 서버는 `.mcp.json` 또는 `claude mcp add-json`으로 구성합니다.

159 159 

160```bash theme={null}160```bash theme={null}

161claude mcp add-json events-server \161claude mcp add-json events-server \

162 '{"type":"ws","url":"wss://mcp.example.com/socket","headers":{"Authorization":"Bearer YOUR_TOKEN"}}'162 '{"type":"ws","url":"wss://mcp.example.com/socket","headers":{"Authorization":"Bearer YOUR_TOKEN"}}'

163```163```

164 164 

165`type: "ws"` 항목은 `http`와 동일한 `url`, `headers`, `headersHelper`, `timeout` 및 `alwaysLoad` 필드를 허용합니다. 인증은 헤더 전용이므로 `headers`에 정적 토큰을 전달하거나 [`headersHelper`](#use-dynamic-headers-for-custom-authentication)를 사용하여 연결 시 토큰을 생성하세요. `claude mcp add --transport` 플래그는 `ws`를 허용하지 않습니다.165`type: "ws"` 항목은 `http`와 동일한 `url`, `headers`, `headersHelper`, `timeout`, `alwaysLoad` 필드를 허용합니다. 인증은 헤더로만 가능하므로, `headers`에 정적 토큰을 전달하거나 [`headersHelper`](#use-dynamic-headers-for-custom-authentication)로 연결 시점에 토큰을 생성합니다. `claude mcp add --transport` 플래그는 `ws`를 허용하지 않습니다.

166 166 

167### 다른 클라이언트용으로 작성된 설정 지침에서 서버 추가167### 다른 클라이언트용 설정 안내에서 서버 추가

168 168 

169MCP 서버는 Claude Code에만 해당하지 않으므로 서버의 설정 지침은 Claude Desktop, Cursor 또는 다른 MCP 클라이언트용으로 작성될 수 있으며 `claude mcp add` 명령을 제공하지 않을 수 있습니다. 어쨌든 서버를 추가하려면 해당 지침에서 URL, 시작 명령 또는 JSON 블록을 찾으세요:169MCP 서버는 Claude Code 전용이 아니므로, 서버의 설정 안내가 Claude Desktop, Cursor 또는 다른 MCP 클라이언트용으로 작성되어 `claude mcp add` 명령을 제공하지 않을 수 있습니다. 그래도 서버를 추가하려면 해당 안내에서 URL, 실행 명령 또는 JSON 블록을 찾으십시오.

170 170 

171* **URL** (예: `https://mcp.example.com/mcp`): 서버는 원격입니다.171* **URL**(예: `https://mcp.example.com/mcp`): 원격 서버입니다.

172* **시작 명령** (예: `npx -y @example/mcp-server`): 서버는 컴퓨터에서 실행됩니다.172* **실행 명령**(예: `npx -y @example/mcp-server`): 서버가 사용자 컴퓨터에서 실행됩니다.

173* **`mcpServers` JSON 블록**: 다른 클라이언트의 설정 파일용으로 작성된 구성입니다.173* **`mcpServers` JSON 블록**: 다른 클라이언트의 설정 파일용으로 작성된 구성입니다.

174 174 

175각각은 [MCP 서버 설치](#installing-mcp-servers)의 네 가지 옵션 중 하나가 취하는 입력 중 하나입니다. 아래에서 보유한 형태를 찾아 Claude Code가 허용하는 명령으로 변환하세요. 각 명령은 `--scope project` 또는 `--scope user`를 추가하지 않는 한 [로컬 범위](#local-scope)에 씁니다.175각각은 [MCP 서버 설치](#installing-mcp-servers)의 네 가지 옵션이 받는 입력 중 하나입니다. 아래에서 가지고 있는 형태를 찾아 Claude Code가 허용하는 명령으로 변환하십시오. 각 명령은 `--scope project` 또는 `--scope user`를 추가하지 않는 한 [로컬 범위](#local-scope)에 기록됩니다.

176 176 

177#### URL에서 서버 추가177#### URL에서 서버 추가

178 178 

179URL은 서버가 원격임을 의미합니다. `https://` 엔드포인트의 경우 `--transport http`로 추가하거나, 지침에서 엔드포인트가 SSE를 사용한다고 말할 때 [옵션 2](#option-2-add-a-remote-sse-server)를 따르세요. `wss://` 엔드포인트의 경우 `--transport`가 `ws`를 허용하지 않으므로 대신 [옵션 4](#option-4-add-a-remote-websocket-server)를 사용하세요:179URL이 있다면 원격 서버입니다. `https://` 엔드포인트는 `--transport http`로 추가하거나, 안내에서 엔드포인트가 SSE를 사용한다고 하면 [옵션 2](#option-2-add-a-remote-sse-server)를 따르십시오. `wss://` 엔드포인트는 `--transport`가 `ws`를 허용하지 않으므로 대신 [옵션 4](#option-4-add-a-remote-websocket-server)를 사용하십시오.

180 180 

181```bash theme={null}181```bash theme={null}

182claude mcp add --transport http example https://mcp.example.com/mcp182claude mcp add --transport http example https://mcp.example.com/mcp

183```183```

184 184 

185지침에서 API 키 또는 토큰 헤더도 제공하면 [옵션 1](#option-1-add-a-remote-http-server)에 표시된 대로 `--header`로 전달하세요.185안내에 API 키나 토큰 헤더도 제공되어 있다면 [옵션 1](#option-1-add-a-remote-http-server)에 나온 것처럼 `--header`로 전달하십시오.

186 186 

187#### `npx`, `uvx` 또는 바이너리 명령에서 서버 추가187#### `npx`, `uvx` 또는 바이너리 명령에서 서버 추가

188 188 

189시작 명령은 서버가 로컬 stdio 프로세스로 실행됨을 의미합니다. 전체 명령을 `--` 뒤에 배치하여 Claude Code가 `-y`와 같은 플래그를 서버를 시작하는 명령에 전달하도록 하고 자신의 옵션으로 읽지 않도록 하세요. 지침에서 요청하는 환경 변수를 `--env`로 전달하세요. 서버 이름 뒤에 `--` 앞에:189실행 명령이 있다면 서버는 로컬 stdio 프로세스로 실행됩니다. 전체 명령을 `--` 뒤에 배치하여, Claude Code가 `-y`와 같은 플래그를 자체 옵션으로 읽지 않고 서버를 시작하는 명령에 전달하도록 하십시오. 안내에서 요구하는 환경 변수는 서버 이름 뒤, `--` 앞에 `--env`로 전달합니다.

190 190 

191```bash theme={null}191```bash theme={null}

192claude mcp add example --env API_KEY=your-key -- npx -y @example/mcp-server192claude mcp add example --env API_KEY=your-key -- npx -y @example/mcp-server

193```193```

194 194 

195[옵션 3](#option-3-add-a-local-stdio-server)은 `--` 구분자를 완전히 다룹니다.195`--` 구분자에 대한 전체 설명은 [옵션 3](#option-3-add-a-local-stdio-server)을 참조하십시오.

196 196 

197#### `mcpServers` JSON 블록에서 서버 추가197#### `mcpServers` JSON 블록에서 서버 추가

198 198 

199Claude Desktop과 같은 다른 MCP 클라이언트용으로 작성된 `mcpServers` 블록은 Claude Code가 읽는 래퍼 키와 항목 형태를 사용합니다. `claude mcp add-json`에 `mcpServers` 내부의 객체를 전달하세요. 래퍼는 아닙니다. 두 항목은 먼저 수리가 필요합니다:199Claude Desktop과 같은 다른 MCP 클라이언트용으로 작성된 `mcpServers` 블록은 Claude Code가 읽는 것과 동일한 래퍼 키와 항목 형태를 사용합니다. `claude mcp add-json`에는 래퍼가 아니라 `mcpServers` 내부의 객체를 전달하십시오. 다음 두 가지 항목은 먼저 수정해야 합니다.

200 200 

201* **`type`이 없는 `url`**: 엔드포인트와 일치하도록 `"type": "http"`, `"type": "sse"` 또는 `"type": "ws"`를 추가하세요. Claude Code는 `type`이 없는 항목을 stdio 서버로 읽으므로 `type`이 없는 `url` 항목은 실패합니다.201* **`type`이 없는 `url`**: 엔드포인트에 맞게 `"type": "http"`, `"type": "sse"` 또는 `"type": "ws"`를 추가하십시오. Claude Code는 `type`이 없는 항목을 stdio 서버로 읽으므로, `type`이 없는 `url` 항목은 실패합니다.

202* **문자, 숫자, 하이픈 및 밑줄 이외의 문자가 있는 키**: 해당 문자만 사용하는 서버 이름을 선택하세요. 그렇지 않으면 키가 서버 이름입니다.202* **문자, 숫자, 하이픈, 밑줄 이외의 문자가 포함된 키**: 해당 문자만 사용하는 서버 이름을 선택하십시오. 그 외의 경우 키가 서버 이름이 됩니다.

203 203 

204예를 들어, 이 블록:204예를 들어 다음 블록은:

205 205 

206```json theme={null}206```json theme={null}

207{207{

214}214}

215```215```

216 216 

217이 명령이 됩니다:217다음 명령이 됩니다.

218 218 

219```bash theme={null}219```bash theme={null}

220claude mcp add-json example '{"command":"npx","args":["-y","@example/mcp-server"]}'220claude mcp add-json example '{"command":"npx","args":["-y","@example/mcp-server"]}'

221```221```

222 222 

223[JSON 구성에서 MCP 서버 추가](#add-mcp-servers-from-json-configuration)는 셸 이스케이프 및 `add-json`의 `--scope` 플래그를 다룹니다. 대신 팀과 공유하려면 `--scope project`를 추가하거나 프로젝트 루트의 `.mcp.json`에서 `mcpServers` 아래에 항목을 추가하고 커밋하세요. [프로젝트 범위](#project-scope)는 Claude Code가 해당 파일을 로드하고 승인하는 방법을 다룹니다.223셸 이스케이프와 `add-json`의 `--scope` 플래그에 대해서는 [JSON 구성에서 MCP 서버 추가](#add-mcp-servers-from-json-configuration)를 참조하십시오. 대신 팀과 서버를 공유하려면 `--scope project`를 추가하거나, 프로젝트 루트의 `.mcp.json`에 있는 `mcpServers` 아래에 항목을 추가하고 커밋하십시오. Claude Code가 해당 파일을 로드하고 승인하는 방법은 [프로젝트 범위](#project-scope)를 참조하십시오.

224 224 

225각 `claude mcp add` 및 `claude mcp add-json` 명령은 성공 시 `Added ...` 줄을 인쇄합니다. Claude Code가 연결되었는지 확인하려면 `claude mcp get <name>`을 실행하세요. [서버 상태](#server-status)는 표시되는 상태 및 `.mcp.json` 서버의 승인 단계를 다룹니다.225각 `claude mcp add` 및 `claude mcp add-json` 명령은 성공 시 `Added ...` 줄을 출력합니다. Claude Code가 연결되었는지 확인하려면 `claude mcp get <name>`을 실행하십시오. 이 명령이 표시하는 상태와 `.mcp.json` 서버의 승인 단계는 [서버 상태](#server-status)를 참조하십시오.

226 226 

227### 서버 관리227### 서버 관리

228 228 

229구성한 후에는 다음 명령으로 MCP 서버를 관리할 수 있습니다:229구성이 완료되면 다음 명령으로 MCP 서버를 관리할 수 있습니다.

230 230 

231```bash theme={null}231```bash theme={null}

232# 구성된 모든 서버 나열232# List all configured servers

233claude mcp list233claude mcp list

234 234 

235# 특정 서버의 세부 정보 가져오기235# Get details for a specific server

236claude mcp get notion236claude mcp get notion

237 237 

238# 서버 제거238# Remove a server

239claude mcp remove notion239claude mcp remove notion

240 240 

241# (Claude Code 내에서) 서버 상태 확인241# (within Claude Code) Check server status

242/mcp242/mcp

243```243```

244 244 

245원격 서버를 제거하면 Claude Code는 해당 서버에 대해 저장한 OAuth 토큰과 클라이언트 등록 정보도 삭제합니다. Claude Code는 토큰을 발급한 인가 서버에서 토큰을 폐기하지는 않습니다. 인가 서버가 폐기를 지원하는 경우 토큰을 폐기하려면 `claude mcp remove <name>` 전에 셸에서 [`claude mcp logout <name>`](#authenticate-from-the-command-line)을 실행하십시오.245원격 서버를 제거하면 Claude Code는 해당 서버에 대해 저장한 OAuth 토큰과 클라이언트 등록도 삭제합니다. Claude Code는 토큰을 발급한 인가 서버에서 토큰을 폐기하지는 않습니다. 인가 서버가 폐기를 지원하는 경우 토큰을 폐기하려면, `claude mcp remove <name>` 전에 셸에서 [`claude mcp logout <name>`](#authenticate-from-the-command-line)을 실행하십시오.

246 246 

247#### 서버 상태247#### 서버 상태

248 248 

249`claude mcp add`는 `Added ...` 줄을 인쇄하여 성공적인 추가를 확인합니다. 이는 구성이 작성되었음을 의미합니다. 명령이 `was not saved` 메시지를 인쇄하면 [MCP 서버가 저장되지 않았거나 제거됨](https://code.claude.com/docs/ko/errors.md#mcp-server-was-not-saved-or-removed)을 참조하세요. `may not have been saved` 메시지의 경우 [MCP 서버가 저장되지 않았거나 제거되었을 수 있음](https://code.claude.com/docs/ko/errors.md#mcp-server-may-not-have-been-saved-or-removed)을 참조하세요.249`claude mcp add`는 추가에 성공하면 `Added ...` 줄을 출력하며, 이는 구성이 기록되었음을 의미합니다. 대신 `was not saved` 메시지가 출력되면 [MCP server was not saved or removed](https://code.claude.com/docs/ko/errors.md#mcp-server-was-not-saved-or-removed)를 참조하고, `may not have been saved` 메시지가 출력되면 [MCP server may not have been saved or removed](https://code.claude.com/docs/ko/errors.md#mcp-server-may-not-have-been-saved-or-removed)를 참조하십시오.

250 250 

251`claude mcp list`는 나열하는 각 서버 옆에 `✔ Connected`, `! Needs authentication` 또는 `✘ Failed to connect`와 같은 상태를 표시합니다. 실패 상태는 Claude Code가 해당 서버에 연결할 수 없음을 의미하며, list 명령이 실패했음을 의미하지 않습니다.251`claude mcp list`는 나열하는 각 서버 옆에 `✔ Connected`, `! Needs authentication`, `✘ Failed to connect`와 같은 상태를 표시합니다. 실패 상태는 Claude Code가 해당 서버에 연결하지 못했다는 의미이며, list 명령이 실패했다는 의미가 아닙니다.

252 252 

253이 목록의 상태는 연결 시도가 아닌 구성 결정을 보고하므로 Claude Code는 서버에 연결하지 않고 인쇄합니다:253다음 목록의 상태는 연결 시도가 아니라 구성상의 결정을 보고하므로, Claude Code는 서버에 연결하지 않고 이를 출력합니다.

254 254 

255* ``⏸ Pending approval (run `claude` to approve)``: 아직 승인하지 않은 `.mcp.json`의 프로젝트 범위 서버입니다. Claude Code는 `claude mcp list`와 `claude mcp get <name>` 모두에 이를 표시합니다. `claude`를 대화형으로 실행하여 검토하고 승인하십시오.255* ``⏸ Pending approval (run `claude` to approve)``: 아직 승인하지 않은 `.mcp.json`의 프로젝트 범위 서버입니다. Claude Code는 `claude mcp list`와 `claude mcp get <name>` 모두에 이를 표시합니다. `claude`를 대화형으로 실행하여 검토하고 승인하십시오.

256* `✘ Rejected (see disabledMcpjsonServers in settings)`: [`disabledMcpjsonServers`](https://code.claude.com/docs/ko/settings-reference#disabledmcpjsonservers) 항목이 거부하는 `.mcp.json` 서버입니다. Claude Code는 `claude mcp get <name>`에만 표시합니다.256* `✘ Rejected (see disabledMcpjsonServers in settings)`: [`disabledMcpjsonServers`](https://code.claude.com/docs/ko/settings-reference#disabledmcpjsonservers) 항목이 거부하는 `.mcp.json` 서버입니다. Claude Code는 `claude mcp get <name>`에만 이를 표시합니다.

257* `⊘ Disabled for this project (re-enable via /mcp)`: 프로젝트의 [`disabledMcpServers`](#disable-a-server-without-removing-it) 목록이 이름을 지정하는 서버입니다. Claude Code는 `claude mcp list` 및 `claude mcp get <name>` 모두에 표시합니다. `/mcp` 패널에서 서버를 다시 켜세요.257* `⊘ Disabled for this project (re-enable via /mcp)`: 프로젝트의 [`disabledMcpServers`](#disable-a-server-without-removing-it) 목록에 이름이 있는 서버입니다. Claude Code는 `claude mcp list`와 `claude mcp get <name>` 모두에 이를 표시합니다. `/mcp` 패널에서 서버를 다시 켜십시오.

258* `✘ Blocked by enterprise managed policy`: 조직의 정책 중 하나가 거부한 서버입니다. Claude Code는 이 상태를 `claude mcp list`와 `claude mcp get <name>` 모두에 표시합니다. [관리형 MCP 구성](https://code.claude.com/docs/ko/managed-mcp.md#how-restrictions-appear-to-users)의 허용 목록, 거부 목록 또는 기타 제한으로 차단된 서버는 이 상태로 표시되지 않고 두 명령 모두에서 숨겨집니다. 어떤 정책이 서버를 차단하는지 관리자에게 문의하십시오.258* `✘ Blocked by enterprise managed policy`: 조직의 정책 중 하나가 거부하는 서버입니다. Claude Code는 `claude mcp list`와 `claude mcp get <name>` 모두에 이를 표시합니다. [관리형 MCP 구성](https://code.claude.com/docs/ko/managed-mcp.md#how-restrictions-appear-to-users)의 허용 목록, 거부 목록 또는 기타 제한으로 차단된 서버는 이 상태로 표시되지 않고 두 명령 모두에서 숨겨집니다. 어떤 정책이 서버를 차단하는지 관리자에게 문의하십시오.

259 259 

260#### 프로젝트 서버 승인 및 워크스페이스 신뢰260#### 프로젝트 서버 승인과 워크스페이스 신뢰

261 261 

262`claude mcp list` 및 `claude mcp get`은 `claude`를 실행하고 워크스페이스 신뢰 대화 상자를 수락하여 워크스페이스를 신뢰할 때까지 `.mcp.json` 승인을 저장소에 체크인되지 않은 설정 파일에서만 읽습니다. 복제된 저장소는 자신의 서버를 승인할 수 없습니다: 프로젝트의 `.claude/settings.json`에 커밋된 [`enableAllProjectMcpServers`](https://code.claude.com/docs/ko/settings-reference#enableallprojectmcpservers) 또는 [`enabledMcpjsonServers`](https://code.claude.com/docs/ko/settings-reference#enabledmcpjsonservers)는 신뢰할 수 없는 폴더에서 무시되며, 서버는 연결되고 상태 확인되는 대신 `⏸ Pending approval`으로 유지됩니다.262`claude mcp list`와 `claude mcp get`은 워크스페이스에서 `claude`를 실행하고 워크스페이스 신뢰 대화 상자를 수락하여 워크스페이스를 신뢰하기 전까지는, 저장소에 체크인되지 않은 설정 파일에서만 `.mcp.json` 승인을 읽습니다. 복제된 저장소는 자체 서버를 승인할 수 없습니다. 프로젝트의 `.claude/settings.json`에 커밋된 [`enableAllProjectMcpServers`](https://code.claude.com/docs/ko/settings-reference#enableallprojectmcpservers) 또는 [`enabledMcpjsonServers`](https://code.claude.com/docs/ko/settings-reference#enabledmcpjsonservers)는 신뢰되지 않은 폴더에서 무시되며, 서버는 연결 및 상태 확인되지 않고 `⏸ Pending approval` 상태로 유지됩니다.

263 263 

264이러한 소스의 승인은 신뢰할 수 없는 폴더에서도 적용됩니다:264다음 출처의 승인은 신뢰되지 않은 폴더에서도 적용됩니다.

265 265 

266* 사용자 `~/.claude/settings.json`266* 사용자의 `~/.claude/settings.json`

267* 관리형 설정267* 관리형 설정

268* `--settings`로 전달된 설정268* `--settings`로 전달된 설정

269 269 

270Claude Code는 또한 추적되지 않은 `.claude/settings.local.json`의 승인을 적용하지만, git을 실행하여 파일이 추적되는지 확인하며, [신뢰할 수 있는 폴더](https://code.claude.com/docs/ko/permissions.md#project-allow-rules-and-workspace-trust)에서만 해당 확인을 실행합니다. 신뢰한 적이 없는 폴더에서 Claude Code는 파일의 승인을 적용하기 전에 신뢰 대화 상자를 기다립니다. 단, 폴더가 자신의 구성 홈인 경우는 제외됩니다: 홈 디렉터리 또는 `.claude`를 [`CLAUDE_CONFIG_DIR`](https://code.claude.com/docs/ko/env-vars)으로 설정한 디렉터리입니다. v2.1.207 이전에는 Claude Code가 신뢰한 적이 없는 폴더에서도 추적되지 않은 `.claude/settings.local.json`의 승인을 적용했습니다.270Claude Code는 추적되지 않는 `.claude/settings.local.json`의 승인도 적용하지만, 파일이 추적되는지 확인하기 위해 git을 실행하며 이 확인은 [신뢰된 폴더](https://code.claude.com/docs/ko/permissions.md#project-allow-rules-and-workspace-trust)에서만 실행합니다. 한 번도 신뢰한 적 없는 폴더에서는 Claude Code가 신뢰 대화 상자를 기다린 후 파일의 승인을 적용합니다. 단, 해당 폴더가 사용자 자신의 구성 홈, 즉 홈 디렉터리이거나 `.claude`를 [`CLAUDE_CONFIG_DIR`](https://code.claude.com/docs/ko/env-vars)로 설정한 디렉터리인 경우는 예외입니다. v2.1.207 이전에는 Claude Code가 한 번도 신뢰한 적 없는 폴더에서도 추적되지 않는 `.claude/settings.local.json`의 승인을 적용했습니다.

271 271 

272모든 설정 파일의 `disabledMcpjsonServers` 항목은 여전히 서버를 거부합니다.272어떤 설정 파일에든 `disabledMcpjsonServers` 항목이 있으면 여전히 서버를 거부합니다.

273 273 

274#### 서버 상태 세부 정보274#### 서버 상태 세부 정보

275 275 

276`/mcp`에서 (서버의 메뉴 포함) 및 [`/plugin`](https://code.claude.com/docs/ko/plugins/install) 관리자에서, 이전에 사용한 원격 HTTP 또는 SSE 서버는 `cached 2h ago · connects on first use · 5 tools`와 같은 `cached` 상태를 표시할 수 있습니다. Claude Code는 이전 세션에서 저장된 검색 캐시에서 서버의 도구 목록을 로드했으며, Claude Code는 Claude가 서버의 도구 중 하나를 처음 호출할 때 서버에 연결합니다. 도구는 첫 번째 메시지부터 사용 가능하므로 아무것도 할 필요가 없습니다. 검색 캐시 및 `cached` 상태에는 Claude Code v2.1.221 이상이 필요합니다.276`/mcp`(서버 메뉴 포함)와 [`/plugin`](https://code.claude.com/docs/ko/plugins/install) 관리자에서, 이전에 사용한 원격 HTTP 또는 SSE 서버는 `cached 2h ago · connects on first use · 5 tools`와 같은 `cached` 상태를 표시할 수 있습니다. Claude Code는 시작 시 연결하는 대신 이전 세션에서 저장된 검색 캐시에서 서버의 도구 목록을 로드했으며, Claude가 서버의 도구 중 하나를 처음 호출할 때 서버에 연결합니다. 도구는 첫 메시지부터 사용할 수 있으므로 별도로 조치할 필요가 없습니다. 검색 캐시와 `cached` 상태에는 Claude Code v2.1.221 이상이 필요합니다.

277 277 

278검색 캐시는 기본적으로 꺼져 있으며, 점진적 롤아웃이 계정에 대해 활성화하지 않는 한 꺼져 있습니다. [`MCP_DISCOVERY_CACHE=1`](https://code.claude.com/docs/ko/env-vars)을 설정하여 켜거나, 롤아웃이 활성화했을 때도 꺼진 상태로 유지하려면 `0`으로 설정하세요. v2.1.238 이전에는 캐시가 기본적으로 켜져 있었습니다.278검색 캐시는 점진적 출시로 계정에 활성화되지 않은 한 기본적으로 꺼져 있습니다. 켜려면 [`MCP_DISCOVERY_CACHE=1`](https://code.claude.com/docs/ko/env-vars)을 설정하고, 출시로 활성화되었더라도 끈 상태로 유지하려면 `0`을 설정하십시오. v2.1.238 이전에는 캐시가 기본적으로 켜져 있었습니다.

279 279 

280`/mcp`의 서버 메뉴에서 **Disable** 또는 **Clear authentication**을 선택하면 Claude Code는 해당 서버의 캐시 항목도 삭제합니다. **Reconnect**는 연결되거나 실패한 서버에서도 삭제합니다. `cached` 서버에서 **Reconnect**는 지금 서버에 연결하고 항목을 유지합니다. 항목을 삭제한 후 Claude Code가 서버에 다시 연결할 때, 캐시 대신 서버에서 서버의 도구 목록을 가져옵니다.280`/mcp`의 서버 메뉴에서 **Disable** 또는 **Clear authentication**을 선택하면 Claude Code는 해당 서버의 캐시 항목도 삭제합니다. **Reconnect**도 연결되었거나 실패한 서버에서는 캐시 항목을 삭제하지만, `cached` 서버에서는 **Reconnect**가 서버에 즉시 연결하고 항목을 유지합니다. 항목을 삭제한 후 다음에 Claude Code가 서버에 연결하면 캐시가 아닌 서버에서 도구 목록을 가져옵니다.

281 281 

282##### 연결 실패와 구성되지 않은 서버282##### 연결 실패와 구성되지 않은 서버

283 283 

284서버 상태가 `✘ Failed to connect`이면 `claude mcp list`는 해당 상태줄에 실패 세부 정보를 덧붙이고, `claude mcp get <name>`은 이를 `Issue:` 줄에 표시합니다. 세부 정보는 HTTP 상태 또는 오류 코드와 서버가 반환한 오류 텍스트입니다. `/mcp`의 서버 세부 보기도 `Issue:` 행에 동일한 서버 보고 텍스트를 포함합니다.284서버 상태가 `✘ Failed to connect`이면 `claude mcp list`는 해당 상태 줄에 실패 세부 정보를 덧붙이고, `claude mcp get <name>`은 이를 `Issue:` 줄에 표시합니다. 세부 정보는 HTTP 상태 또는 오류 코드와 서버가 반환한 오류 텍스트입니다. `/mcp`의 서버 세부 정보 보기에도 `Issue:` 행에 서버가 보고한 동일한 텍스트가 포함됩니다.

285 285 

286Claude Code는 이 세부 정보에서 자격 증명처럼 보이는 텍스트를 가리며, 비밀 정보를 포함할 수 있는 확장된 서버 URL은 절대 포함하지 않습니다. `✘ Connection error` 상태에는 세부 정보를 덧붙이지 않는데, 그곳에 출력될 예외 텍스트에 해당 URL이 포함될 수 있기 때문입니다.286Claude Code는 이 세부 정보에서 자격 증명처럼 보이는 텍스트를 가리며, 비밀 정보를 포함할 수 있는 확장된 서버 URL은 절대 포함하지 않습니다. Claude Code는 `✘ Connection error` 상태에는 세부 정보를 덧붙이지 않습니다. 그곳에 출력될 예외 텍스트에 해당 URL이 포함될 수 있기 때문입니다.

287 287 

288`/mcp`에서 인증을 완료하고 연결이 여전히 HTTP 상태 또는 전송 오류 코드로 실패하면 Claude Code는 시도한 후 인쇄하는 메시지에 해당 코드와 서버 URL의 원점을 추가합니다. 원점은 스킴 및 호스트, 그리고 URL이 포트를 지정할 때 포트입니다. 예: `https://mcp.example.com`.288`/mcp`에서 인증을 완료했는데도 HTTP 상태나 전송 오류 코드와 함께 연결이 실패하면, Claude Code는 시도 후 출력하는 메시지에 해당 코드와 서버 URL의 오리진을 추가합니다. 오리진은 스킴과 호스트이며, URL에 포트가 지정된 경우 포트도 포함됩니다(예: `https://mcp.example.com`).

289 289 

290* 경로 및 쿼리는 해당 메시지에 나타나지 않습니다.290* 경로와 쿼리는 해당 메시지에 절대 표시되지 않습니다.

291* 로컬, 프로젝트, 사용자 [범위](#mcp-installation-scopes) 또는 관리형 MCP 구성의 서버의 경우, 원점은 해당 구성에 작성된 호스트를 표시하므로 호스트의 `${VAR}` 참조는 메시지에서 확장되지 않습니다.291* 로컬, 프로젝트 또는 사용자 [범위](#mcp-installation-scopes)나 관리형 MCP 구성에 있는 서버의 경우, 오리진은 해당 구성에 작성된 그대로 호스트를 표시하므로 호스트의 `${VAR}` 참조는 메시지에서 확장되지 않습니다.

292* 상태 또는 오류 코드가 없는 실패의 경우 Claude Code는 원점 없이 오류 텍스트를 표시합니다.292* 상태나 오류 코드가 없는 실패의 경우 Claude Code는 오리진 없이 오류 텍스트만 표시합니다.

293 293 

294구성의 `url`이 비어 있는 원격 서버는 `/mcp`, `claude mcp list` 및 [`/plugin`](https://code.claude.com/docs/ko/plugins/install) 관리자에서 `not configured`로 표시되며, Claude Code는 연결을 시도하지 않습니다. 플러그인은 나중에 구성할 커넥터를 위해 이와 같은 자리 표시자 항목을 포함할 수 있으므로 Claude Code는 이를 오류 또는 설정 문제로 보고하지 않습니다. `/mcp`의 서버 세부 정보 보기에는 `No URL configured for this server`가 표시됩니다. 연결하려면 항목의 `url`을 설정하세요.294구성의 `url`이 비어 있는 원격 서버는 `/mcp`, `claude mcp list`, [`/plugin`](https://code.claude.com/docs/ko/plugins/install) 관리자에서 `not configured`로 표시되며, Claude Code는 연결을 시도하지 않습니다. 플러그인은 나중에 구성할 커넥터를 위해 이와 같은 자리표시자 항목을 포함할 수 있으므로, Claude Code는 이를 오류나 설정 문제로 보고하지 않습니다. `/mcp`의 서버 세부 정보 보기에는 `No URL configured for this server`가 표시되며, 연결하려면 항목의 `url`을 설정하십시오.

295 295 

296#### 구성 경고296#### 구성 경고

297 297 

298Claude Code는 아래의 구성 문제에 대해 경고합니다. 각 항목은 Claude Code가 확인하는 내용과 경고를 지우는 방법을 설명합니다:298Claude Code는 아래의 구성 문제에 대해 경고합니다. 각 항목은 Claude Code가 확인하는 내용과 경고를 해제하는 방법을 설명합니다.

299 299 

300* **숨겨진 공백**: Claude Code는 MCP 구성 값이 숨겨진 선행 또는 후행 공백을 전달할 때 경고합니다. 이는 종종 후행 줄 바꿈이 있는 토큰을 붙여넣기에서 나옵니다. Claude Code는 `command`, `url`, 각 `args` 항목, 그리고 `env` 및 `headers` 아래의 값과 키 이름을 확인합니다. Claude Code는 `claude mcp list` 출력 및 `/mcp`에서 경고를 표시하며, 값을 그대로 보여주지 않고 영향을 받는 필드의 이름만 지정합니다. 예: `Leading or trailing whitespace in: headers.Authorization`. Claude Code는 공백을 자르지 않고 작성된 대로 정확히 값을 사용하므로 구성을 편집하여 제거하세요.300* **숨겨진 공백**: MCP 구성 값에 숨겨진 앞뒤 공백이 있으면 Claude Code가 경고합니다. 이는 주로 끝에 줄바꿈이 있는 토큰을 붙여 넣을 때 발생합니다. Claude Code는 `command`, `url`, 각 `args` 항목, 그리고 `env` 및 `headers` 아래의 값과 키 이름을 확인합니다. Claude Code는 `claude mcp list` 출력과 `/mcp`에 경고를 표시하며, 값을 그대로 보여 주지 않고 영향을 받는 필드의 이름만 표시합니다(예: `Leading or trailing whitespace in: headers.Authorization`). Claude Code는 공백을 자르지 않고 작성된 값 그대로 사용하므로, 구성을 편집하여 공백을 제거하십시오.

301* **둘 이상의 범위에서 동일한 이름**: 다른 엔드포인트를 사용하여 둘 이상의 [범위](#mcp-installation-scopes)에서 동일한 서버 이름을 정의하면 Claude Code는 `claude mcp list` 출력 및 `/mcp`에서 충돌에 대해 경고합니다. Claude Code는 엔드포인트당 OAuth 로그인을 저장하므로 한 프로젝트에서 로드되는 정의를 인증할 때, 다른 정의가 로드되는 프로젝트에서는 여전히 별도로 로그인해야 합니다. 원하는 엔드포인트를 유지하고 `claude mcp remove <name> --scope <scope>`로 다른 엔드포인트를 제거하세요. 경고에서 Claude Code는 각 범위의 엔드포인트를 구성에 작성된 대로 인용합니다. [`${VAR}` 참조](#environment-variable-expansion-in-mcp-json)는 확장되지 않으므로 API 키와 같은 확인된 값을 표시하지 않습니다.301* **여러 범위에 있는 동일한 이름**: 동일한 서버 이름을 서로 다른 엔드포인트로 둘 이상의 [범위](#mcp-installation-scopes)에 정의하면, Claude Code는 `claude mcp list` 출력과 `/mcp`에서 충돌에 대해 경고합니다. Claude Code는 OAuth 로그인을 엔드포인트별로 저장하므로, 한 프로젝트에서 로드되는 정의를 인증하더라도 다른 정의가 로드되는 프로젝트에서는 별도로 로그인해야 합니다. 원하는 엔드포인트를 유지하고 나머지는 `claude mcp remove <name> --scope <scope>`로 제거하십시오. 경고에서 Claude Code는 각 범위의 엔드포인트를 구성에 작성된 그대로, [`${VAR}` 참조](#environment-variable-expansion-in-mcp-json)를 확장하지 않은 상태로 인용하므로 API 키와 같은 확인된 값은 절대 표시되지 않습니다.

302* **예약된 이름**: Claude Code는 `workspace`, `claude-in-chrome`, `computer-use`, `Claude Preview` 및 `Claude Browser`를 포함한 기본 제공 서버의 이름을 예약합니다. 구성에서 예약된 이름의 서버를 정의하면 Claude Code는 로드 시 이를 건너뛰고 이름을 바꾸도록 요청하는 경고를 표시합니다. `claude mcp add`는 예약된 이름을 오류로 거부합니다. `Claude Preview` 및 `Claude Browser`는 모두 [Claude Code 데스크톱 앱의 미리보기 창](https://code.claude.com/docs/ko/desktop.md#preview-your-app)이 사용하는 기본 제공 서버의 이름입니다.302* **예약된 이름**: Claude Code는 `workspace`, `claude-in-chrome`, `computer-use`, `Claude Preview`, `Claude Browser`를 포함한 기본 제공 서버의 이름을 예약합니다. 구성에서 예약된 이름으로 서버를 정의하면 Claude Code는 로드 시 이를 건너뛰고 이름을 변경하라는 경고를 표시합니다. `claude mcp add`는 예약된 이름을 오류와 함께 거부합니다. `Claude Preview`와 `Claude Browser`는 모두 [Claude Code 데스크톱 앱의 미리보기 창](https://code.claude.com/docs/ko/desktop.md#preview-your-app)이 사용하는 기본 제공 서버의 이름입니다.

303* **누락된 환경 변수**: 서버 구성의 [`${VAR}` 참조](#environment-variable-expansion-in-mcp-json)가 설정되지 않은 변수의 이름을 지정하고 `:-default`가 없으면 Claude Code는 `claude mcp list` 출력 및 `/mcp`에서 경고하며, 변수의 이름을 지정하고, 여전히 `${VAR}` 텍스트가 확장되지 않은 상태로 서버를 로드합니다. 변수를 설정하거나 `${VAR:-default}` 폴백을 추가하세요. 원격 서버의 `url` 및 `headers`에서 일부 자격 증명 변수는 [경고 없이 비어 있는 것으로 읽습니다](#credential-variables-that-read-as-empty).303* **누락된 환경 변수**: 서버 구성의 [`${VAR}` 참조](#environment-variable-expansion-in-mcp-json)가 설정되지 않았고 `:-default`도 없는 변수를 가리키면, Claude Code는 `claude mcp list` 출력과 `/mcp`에서 해당 변수 이름과 함께 경고하고, `${VAR}` 텍스트를 확장하지 않은 채로 서버를 로드합니다. 변수를 설정하거나 `${VAR:-default}` 폴백을 추가하십시오. 원격 서버의 `url`과 `headers`에서는 일부 자격 증명 변수가 경고 없이 대신 [빈 값으로 읽힙니다](#credential-variables-that-read-as-empty).

304 304 

305#### 도구 가용성305#### 도구 가용성

306 306 

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

308 308 

309##### 클라우드 세션의 도구 개수309##### 클라우드 세션의 도구 수

310 310 

311[클라우드 세션](https://code.claude.com/docs/ko/claude-code-on-the-web.md)에서 `3 of 13 tools available` 같은 개수는 Claude가 나머지 10개를 사용할 수 없다는 의미입니다. 다음과 같은 원인을 확인하십시오.311[클라우드 세션](https://code.claude.com/docs/ko/claude-code-on-the-web.md)에서 `3 of 13 tools available`과 같은 수는 Claude가 나머지 10개를 사용할 수 없다는 의미입니다. 다음과 같은 원인 등을 확인하십시오.

312 312 

313* **저장소의 `.claude/settings.json`에 있는 거부 규칙이 해당 도구나 서버 전체를 지정함**: [세션이 해당 파일을 읽는 경우](https://code.claude.com/docs/ko/settings.md#settings-in-cloud-sessions) [규칙](https://code.claude.com/docs/ko/permissions.md#mcp)을 제거하십시오313* **저장소의 `.claude/settings.json`에 있는 거부 규칙이 해당 도구나 서버 전체를 지정함**: [세션이 해당 파일을 읽는 경우](https://code.claude.com/docs/ko/settings.md#settings-in-cloud-sessions) [규칙](https://code.claude.com/docs/ko/permissions.md#mcp)을 제거하십시오

314* **도구의 전체 이름이 128자를 초과함**: [이름이 너무 긴 경우의 단계](https://code.claude.com/docs/ko/errors.md#mcp-tool-name-over-128-characters)를 따르십시오314* **도구의 전체 이름이 128자를 초과함**: [너무 긴 이름에 대한 단계](https://code.claude.com/docs/ko/errors.md#mcp-tool-name-over-128-characters)를 따르십시오

315* **서버가 Claude가 아닌 자체 인터페이스용으로 도구를 나열함**: 서버를 관리하는 경우 도구의 `_meta.ui.visibility`에 `model`을 추가하여 Claude에 도구를 제공하십시오. 그렇지 않다면 수정할 것이 없습니다.315* **서버가 Claude가 아닌 자체 인터페이스용으로 도구를 나열함**: 서버를 관리한다면 도구의 `_meta.ui.visibility`에 `model`을 추가하여 Claude에 도구를 제공하십시오. 그렇지 않다면 수정할 것이 없습니다.

316 316 

317##### 아직 연결 중인 서버의 도구317##### 아직 연결 중인 서버의 도구

318 318 

319요청이 백그라운드에서 아직 연결 중인 서버의 도구가 필요한 경우 Claude는 해당 서버가 연결될 때까지 기다립니다. 대기 방식은 구성에 따라 다릅니다:319요청에 백그라운드에서 아직 연결 중인 서버의 도구가 필요하면, Claude는 계속하기 전에 해당 서버를 기다립니다. 대기 방식은 구성에 따라 다릅니다.

320 320 

321* **[도구 검색](#scale-with-mcp-tool-search) 포함 (기본값)**: 대기는 `ToolSearch` 호출 내에서 발생합니다.321* **[도구 검색](#scale-with-mcp-tool-search) 사용 시(기본값)**: 대기는 `ToolSearch` 호출 내부에서 이루어집니다.

322* **도구 검색 없음**: Claude는 대신 `WaitForMcpServers` 도구를 사용합니다. 도구 검색이 없는 구성에는 `ENABLE_TOOL_SEARCH=false` 및 Google Cloud의 Agent Platform에서 Claude Opus 4.5, Claude Sonnet 4.5, Claude Haiku 4.5보다 이전 모델이 포함됩니다. `ANTHROPIC_BASE_URL` 게이트웨이의 경우 [LLM 게이트웨이를 통한 도구 검색](#tool-search-through-a-gateway)을 참조하세요.322* **도구 검색 미사용 시**: Claude는 대신 `WaitForMcpServers` 도구를 사용합니다. 도구 검색을 사용하지 않는 구성에는 `ENABLE_TOOL_SEARCH=false`, 그리고 Google Cloud의 Agent Platform에서 Claude Opus 4.5, Claude Sonnet 4.5, Claude Haiku 4.5보다 이전 모델을 사용하는 경우가 포함됩니다. `ANTHROPIC_BASE_URL` 게이트웨이에 대해서는 [LLM 게이트웨이를 통한 도구 검색](#tool-search-through-a-gateway)을 참조하십시오.

323* **Microsoft Foundry [Azure에서 호스팅되는 배포](https://platform.claude.com/docs/en/build-with-claude/claude-in-microsoft-foundry#hosting-options)**: Claude Code는 배포의 서버 측 거부를 API를 통해서만 발견하므로 Claude는 `WaitForMcpServers`가 아닌 도구 검색 경로에서 시작합니다. Claude Code가 해당 배포를 [사전 로드](#scale-with-mcp-tool-search)로 전환한 후에는 연결을 완료한 서버의 도구가 Claude의 다음 요청에서 사용 가능해집니다.323* **Microsoft Foundry [Azure 호스팅 배포](https://platform.claude.com/docs/en/build-with-claude/claude-in-microsoft-foundry#hosting-options)에서**: Claude Code는 API를 통해서만 배포의 서버 측 거부를 발견하므로, Claude는 `WaitForMcpServers`가 아닌 도구 검색 경로로 시작합니다. Claude Code가 해당 배포를 [사전 로딩](#scale-with-mcp-tool-search)으로 전환한 후에는, 연결을 완료한 서버의 도구를 Claude의 다음 요청에서 사용할 수 있습니다.

324 324 

325도구 검색이 활성화되면 Claude가 작업 중일 때 서버가 연결을 완료하면 Claude Code는 같은 턴의 다음 요청에서 서버의 도구 이름을 Claude에 나열합니다. 그러면 Claude는 사용자의 다음 메시지를 기다리지 않고 해당 도구를 검색하고 호출할 수 있습니다.325도구 검색이 활성화된 상태에서 Claude가 작업하는 동안 서버 연결이 완료되면, Claude Code는 같은 턴의 다음 요청에서 Claude에 서버의 도구 이름을 나열합니다. 그러면 Claude는 다음 메시지를 기다리지 않고 해당 도구를 검색하고 호출할 수 있습니다.

326 326 

327세션을 재개한 후에는 도구의 MCP 서버가 아직 연결 중인 동안에도 Claude가 저장된 대화의 도구를 호출할 수 있습니다. 서버가 첫 번째 연결 시도 중인 동안 Claude Code는 호출을 최대 10초 동안 보류하고 도구를 사용할 수 있게 되면 실행합니다. 서버가 제시간에 연결되지 않거나 이미 [실패한 시도 후 재시도 중](#automatic-reconnection)인 경우, 호출은 `No such tool available` [도구 오류](https://code.claude.com/docs/ko/errors.md#no-such-tool-available)로 실패합니다.327세션을 재개한 후 도구의 MCP 서버가 아직 연결 중일 때 Claude가 저장된 대화의 도구를 호출할 수 있습니다. 서버가 첫 번째 연결을 시도하는 동안 Claude Code는 호출을 최대 10초간 보류하고 도구를 사용할 수 있게 되면 실행합니다. 서버가 제시간에 연결되지 않거나 이미 [실패한 시도 후 재시도 중](#automatic-reconnection)이면, 호출은 `No such tool available` [도구 오류](https://code.claude.com/docs/ko/errors.md#no-such-tool-available)와 함께 실패합니다.

328 328 

329### 서버를 제거하지 않고 비활성화329### 서버를 제거하지 않고 비활성화

330 330 

331`/mcp` 패널에서 서버를 토글하여 Claude Code가 구성을 잃지 않고 연결하지 않도록 중지합니다. Claude Code는 여전히 `/mcp`에서 서버를 나열하며, 비활성화로 표시합니다.331`/mcp` 패널에서 서버를 끄면 구성을 잃지 않고 Claude Code가 해당 서버에 연결하지 않도록 할 수 있습니다. Claude Code는 여전히 `/mcp`에 서버를 비활성화됨으로 표시하여 나열합니다.

332 332 

333서버를 토글하면 Claude Code는 `~/.claude.json`의 프로젝트당 선택을 기록합니다. 이는 분리된 서버 집합을 포함하는 두 목록 중 하나입니다:333서버를 전환하면 Claude Code는 선택 사항을 `~/.claude.json`에 프로젝트별로 기록하며, 서로 겹치지 않는 서버 집합을 다루는 두 목록 중 하나에 기록합니다.

334 334 

335* `disabledMcpServers`: 사용자 구성 서버, 플러그인 서버, 조직이 [관리형 설정을 통해 제공](https://code.claude.com/docs/ko/managed-mcp.md#provide-servers-through-managed-settings)하는 서버, Claude Code가 [자체적으로 가져오는](#how-connectors-reach-claude-code) claude.ai 커넥터 및 기본적으로 켜져 있는 기본 제공 서버에 대한 옵트아웃 목록입니다. Claude Code는 여기에 나열한 서버에 연결하지 않습니다. [claude.ai 커넥터 비활성화](#disable-claude-ai-connectors)에 설명된 프로젝트별 `/mcp` 토글로 claude.ai 커넥터를 비활성화하면 Claude Code는 이를 표시 이름 (예: `claude.ai Slack`)으로 이 목록에 씁니다.335* `disabledMcpServers`: 사용자가 구성한 서버, 플러그인 서버, 조직이 [관리형 설정을 통해 제공하는](https://code.claude.com/docs/ko/managed-mcp.md#provide-servers-through-managed-settings) 서버, Claude Code가 [직접 가져오는](#how-connectors-reach-claude-code) claude.ai 커넥터, 기본적으로 켜져 있는 기본 제공 서버에 대한 옵트아웃 목록입니다. Claude Code는 여기에 나열된 서버에 연결하지 않습니다. [claude.ai 커넥터 비활성화](#disable-claude-ai-connectors)에 설명된 프로젝트별 `/mcp` 토글로 claude.ai 커넥터를 비활성화하면, Claude Code는 이를 표시 이름(예: `claude.ai Slack`)으로 이 목록에 기록합니다.

336* `enabledMcpServers`: `computer-use`와 같이 기본적으로 꺼져 있는 기본 제공 서버에 대한 옵트인 목록입니다. Claude Code는 여기에 나열할 때만 기본 꺼짐 서버에 연결합니다.336* `enabledMcpServers`: `computer-use`와 같이 기본적으로 꺼져 있는 기본 제공 서버에 대한 옵트인 목록입니다. Claude Code는 기본적으로 꺼져 있는 서버가 여기에 나열된 경우에만 연결합니다.

337 337 

338Claude Code는 각 서버에 대해 정확히 두 목록 중 하나를 참조하므로 어느 목록도 다른 목록을 재정의하지 않습니다. 일반 서버를 `enabledMcpServers`에 추가하거나 기본 꺼짐 기본 제공 서버를 `disabledMcpServers`에 추가하면 Claude Code는 항목을 무시합니다.338Claude Code는 각 서버에 대해 두 목록 중 정확히 하나만 참조하므로, 어느 목록도 다른 목록을 재정의하지 않습니다. 일반 서버를 `enabledMcpServers`에 추가하거나 기본적으로 꺼져 있는 기본 제공 서버를 `disabledMcpServers`에 추가하면 Claude Code는 해당 항목을 무시합니다.

339 339 

340`disabledMcpServers` 및 `enabledMcpServers`는 [`enabledMcpjsonServers`](https://code.claude.com/docs/ko/settings-reference#enabledmcpjsonservers) 및 [`disabledMcpjsonServers`](https://code.claude.com/docs/ko/settings-reference#disabledmcpjsonservers)와 무관합니다. 이는 프로젝트의 `.mcp.json` 파일에 정의된 서버의 승인을 제어합니다.340`disabledMcpServers`와 `enabledMcpServers`는 프로젝트의 `.mcp.json` 파일에 정의된 서버의 승인을 제어하는 [`enabledMcpjsonServers`](https://code.claude.com/docs/ko/settings-reference#enabledmcpjsonservers) 및 [`disabledMcpjsonServers`](https://code.claude.com/docs/ko/settings-reference#disabledmcpjsonservers)와 관련이 없습니다.

341 341 

342### MCP 클라이언트 런타임342### MCP 클라이언트 런타임

343 343 

344Claude Code는 두 클라이언트 런타임 중 하나를 통해 MCP 서버에 연결합니다. v1 런타임은 MCP TypeScript SDK 1.x를 기반으로 합니다. v2 런타임은 [MCP TypeScript SDK 2.0](https://ts.sdk.modelcontextprotocol.io/v2/)의 동일한 코드이며, MCP 프로토콜 개정 2026-07-28을 추가합니다. 이 페이지의 나머지는 v2 런타임을 이름으로 지정하는 섹션을 제외하고 두 런타임 모두에 적용됩니다.344Claude Code는 두 가지 클라이언트 런타임 중 하나를 통해 MCP 서버에 연결합니다. v1 런타임은 MCP TypeScript SDK 1.x를 기반으로 합니다. v2 런타임은 동일한 코드를 [MCP TypeScript SDK 2.0](https://ts.sdk.modelcontextprotocol.io/v2/) 위에 구축한 것으로, MCP 프로토콜 리비전 2026-07-28을 추가합니다. 이 페이지의 나머지 내용은 섹션에서 v2 런타임을 명시한 경우를 제외하고 두 런타임 모두에 적용됩니다.

345 345 

346Claude Code는 시작할 때마다 런타임을 선택하고 종료할 때까지 유지합니다. [기능 플래그를 가져오는](https://code.claude.com/docs/ko/env-vars.md#features-that-need-feature-flag-fetching) 세션에서 Claude Code v2.1.232 이상에서 v2 런타임을 사용합니다.346Claude Code는 시작할 때마다 런타임을 선택하고 종료할 때까지 유지합니다. [기능 플래그를 가져오는](https://code.claude.com/docs/ko/env-vars.md#features-that-need-feature-flag-fetching) 세션에서는 Claude Code v2.1.232 이상에서 v2 런타임을 사용합니다.

347 347 

348기능 플래그를 가져오지 않는 세션에서 Claude Code는 Claude Code v2.1.274 이상에서 기본적으로 v2 런타임을 사용합니다:348기능 플래그를 가져오지 않는 세션에서는 Claude Code v2.1.274 이상에서 기본적으로 v2 런타임을 사용합니다.

349 349 

350* Amazon Bedrock, Claude Platform on AWS, Google Cloud의 Agent Platform 또는 Microsoft Foundry의 세션. Claude Code를 내장한 호스트 플랫폼이 [`CLAUDE_CODE_PROVIDER_MANAGED_BY_HOST`](https://code.claude.com/docs/ko/env-vars)를 설정한 경우는 제외350* Amazon Bedrock, Claude Platform on AWS, Google Cloud의 Agent Platform 또는 Microsoft Foundry의 세션(Claude Code를 내장한 호스트 플랫폼이 [`CLAUDE_CODE_PROVIDER_MANAGED_BY_HOST`](https://code.claude.com/docs/ko/env-vars)를 설정한 경우 제외)

351* [Claude 앱 게이트웨이](https://code.claude.com/docs/ko/claude-apps-gateway)를 통해 로그인한 세션351* [Claude apps gateway](https://code.claude.com/docs/ko/claude-apps-gateway)를 통해 로그인한 세션

352* 텔레메트리 또는 기능 플래그 가져오기를 끈 세션. 예를 들어 `DISABLE_TELEMETRY`352* 예를 들어 `DISABLE_TELEMETRY`로 텔레메트리나 기능 플래그 가져오기를 끈 세션

353 353 

354v2에서 Claude Code는 또한:354v2에서 Claude Code는 다음과 같이도 동작합니다.

355 355 

356* HTTP, stdio 및 claude.ai 커넥터 서버에 더 새로운 개정을 지원하는지 묻고, 지원하는 서버와 함께 사용합니다. 여기에는 클라우드 세션 및 [Remote Control](https://code.claude.com/docs/ko/remote-control.md) 세션의 커넥터가 포함됩니다. 다른 모든 서버에는 v1처럼 연결합니다.356* HTTP, stdio, claude.ai 커넥터 서버에 최신 리비전을 지원하는지 묻고, 지원하는 서버와는 이를 사용합니다. 여기에는 클라우드 및 [Remote Control](https://code.claude.com/docs/ko/remote-control.md) 세션의 커넥터가 포함됩니다. 그 외의 모든 서버에는 v1과 동일하게 연결합니다.

357* [열린 스트림](#notification-streams-on-the-v2-runtime)을 통해 더 새로운 개정의 서버에서 `list_changed` 알림을 받습니다.357* 최신 리비전을 사용하는 서버로부터 [열어 두는 스트림](#notification-streams-on-the-v2-runtime)을 통해 `list_changed` 알림을 받습니다.

358* 더 새로운 개정에 연결되는 [채널](#push-messages-with-channels) 서버를 등록하지 않습니다. 해당 개정은 채널 메시지를 전달할 수 없기 때문입니다.358* 최신 리비전으로 연결하는 [채널](#push-messages-with-channels) 서버는 등록하지 않습니다. 해당 리비전은 채널 메시지를 전달할 수 없기 때문입니다.

359* 인증 응답이 예상치 못한 발급자의 이름을 지정하는 [MCP OAuth 로그인](#authenticate-with-remote-mcp-servers)을 실패합니다.359* 인가 응답에 예상치 못한 발급자가 명시된 [MCP OAuth 로그인](#authenticate-with-remote-mcp-servers)을 실패 처리합니다.

360* [MCP OAuth](#authenticate-with-remote-mcp-servers) 자격 증명을 HTTPS를 통해 제공되거나 `localhost`, `127.0.0.1` 또는 `::1`에서 제공되는 토큰 엔드포인트에만 보냅니다. 토큰 엔드포인트가 로컬 네트워크의 장치와 같은 다른 곳에서 일반 `http://`인 서버의 로그인이 실패합니다. [HTTPS가 아닌 토큰 엔드포인트로 자격 증명 전송 거부](https://code.claude.com/docs/ko/errors.md#refusing-to-send-credentials-to-non-https-token-endpoint)를 참조하세요.360* [MCP OAuth](#authenticate-with-remote-mcp-servers) 자격 증명을 HTTPS로 제공되거나 `localhost`, `127.0.0.1`, `::1`에 있는 토큰 엔드포인트에만 보냅니다. 로컬 네트워크의 장치와 같이 그 외의 위치에서 일반 `http://`를 사용하는 토큰 엔드포인트를 가진 서버는 로그인에 실패합니다. [Refusing to send credentials to non-https token endpoint](https://code.claude.com/docs/ko/errors.md#refusing-to-send-credentials-to-non-https-token-endpoint)를 참조하십시오.

361 361 

362Anthropic은 Claude Code가 가져오는 기능 플래그를 통해 특정 서버를 이전 프로토콜에 유지하거나 해당 스트림에서 제외할 수 있습니다. 런타임을 직접 선택하려면 [`MCP_SDK_GENERATION`](https://code.claude.com/docs/ko/env-vars)을 `v1` 또는 `v2`로 설정하십시오.362Anthropic은 Claude Code가 가져오는 기능 플래그로 특정 서버를 이전 프로토콜에 유지하거나 해당 스트림에서 제외할 수 있습니다. 런타임을 직접 선택하려면 [`MCP_SDK_GENERATION`](https://code.claude.com/docs/ko/env-vars)을 `v1` 또는 `v2`로 설정하십시오.

363 363 

364Claude Code가 서버에 최신 리비전에 대해 물을지 결정하려면 [`MCP_PROTOCOL_NEGOTIATION`](https://code.claude.com/docs/ko/env-vars)을 `auto` 또는 `legacy`로 설정하십시오. 이 변수를 설정하지 않으면, 예를 들어 stdio 서버가 질문을 받고 종료된 후에는 Claude Code가 7일 동안 해당 서버에 묻는 것을 건너뛸 수 있습니다. 업그레이드된 서버에 더 빨리 묻게 하려면 `auto`를 설정하십시오.364Claude Code가 서버에 최신 리비전에 대해 묻는지 여부를 결정하려면 [`MCP_PROTOCOL_NEGOTIATION`](https://code.claude.com/docs/ko/env-vars)을 `auto` 또는 `legacy`로 설정하십시오. 이 변수가 설정되지 않은 경우, Claude Code는 예를 들어 서버가 질문을 받고 종료된 후 7일 동안 stdio 서버에 묻는 것을 건너뛸 수 있습니다. 업그레이드된 서버에 더 빨리 묻도록 하려면 `auto`를 설정하십시오.

365 365 

366### 동적 도구 업데이트366### 동적 도구 업데이트

367 367 

368MCP 서버는 연결된 상태에서 제공하는 도구, 프롬프트 또는 리소스를 변경하고 `list_changed` 알림을 보낼 수 있습니다. 알림이 도착하면:368MCP 서버는 연결된 상태에서 제공하는 도구, 프롬프트 또는 리소스를 변경하고 `list_changed` 알림을 보낼 수 있습니다. 알림이 도착하면 다음과 같이 처리됩니다.

369 369 

370* **대화형 터미널 세션에서**는 Claude Code가 해당 서버에서 업데이트된 목록을 가져오므로 서버를 다시 연결할 필요가 없습니다.370* **대화형 터미널 세션에서**는 Claude Code가 해당 서버에서 업데이트된 목록을 가져오므로 다시 연결할 필요가 없습니다.

371* **`-p` 플래그를 사용하는 [비대화형 모드](https://code.claude.com/docs/ko/headless.md) 및 [Agent SDK](https://code.claude.com/docs/ko/agent-sdk/overview.md)에서**는 Claude Code가 이러한 알림에 대해 도구 목록만 새로 고칩니다.371* **`-p` 플래그를 사용한 [비대화형 모드](https://code.claude.com/docs/ko/headless.md)와 [Agent SDK](https://code.claude.com/docs/ko/agent-sdk/overview.md)에서**는 Claude Code가 이러한 알림에 대해 도구 목록만 새로 고칩니다.

372 372 

373새로 고침 요청이 실패하면 Claude Code는 나중에 새로 고침이 성공할 때까지 서버의 이전에 발견된 도구, 프롬프트 및 리소스를 유지합니다.373새로 고침 요청이 실패하면 Claude Code는 이후 새로 고침이 성공할 때까지 이전에 발견한 서버의 도구, 프롬프트, 리소스를 유지합니다.

374 374 

375#### v2 런타임의 알림 스트림375#### v2 런타임의 알림 스트림

376 376 

377[v2 런타임](#mcp-client-runtimes)에서 Claude Code는 더 새로운 프로토콜 개정의 서버에서 열린 스트림을 통해 `list_changed` 알림을 받습니다. 스트림이 닫히면 Claude Code는 두 가지 제한으로 다시 엽니다:377[v2 런타임](#mcp-client-runtimes)에서 Claude Code는 최신 프로토콜 리비전을 사용하는 서버로부터 열어 두는 스트림을 통해 `list_changed` 알림을 받습니다. 스트림이 닫히면 Claude Code는 다음 두 가지 제한 내에서 스트림을 다시 엽니다.

378 378 

379* **스트림이 10초 이내에 다시 닫힘**: Claude Code는 최대 3번 다시 열고, 그 후 해당 연결에 대해 중지합니다.379* **스트림이 10초 이내에 다시 닫히는 경우**: Claude Code는 최대 세 번까지 다시 연 다음 해당 연결에 대해서는 중단합니다.

380* **스트림이 10초 이상 열려 있다가 닫힘** (서버리스 호스트에 대한 스트림이 일반적으로 하는 것처럼): 1시간에 5번 다시 열기 후 Claude Code는 다음 열기 전에 약 6시간을 기다립니다.380* **스트림이 10초보다 오래 열려 있다가 닫히는 경우**(서버리스 호스트로의 스트림에서 흔히 발생): 1시간 내에 다섯 번 다시 연 후에는 Claude Code가 다음 재연결까지 약 6시간을 기다립니다.

381 381 

382스트림이 다시 열릴 때까지 서버의 마지막 가져온 도구, 프롬프트 및 리소스를 유지합니다. 변경 사항을 더 빨리 선택하려면 `/mcp`에서 서버를 다시 연결하세요.382스트림이 다시 열릴 때까지는 서버에서 마지막으로 가져온 도구, 프롬프트, 리소스가 유지됩니다. 변경 사항을 더 빨리 반영하려면 `/mcp`에서 서버를 다시 연결하십시오.

383 383 

384### 자동 재연결384### 자동 재연결

385 385 

386Claude Code는 세션 중에 연결이 끊어진 원격 서버를 다시 연결하고 일시적 오류 후 HTTP 또는 SSE 서버의 첫 연결을 재시도합니다. stdio 서버의 경우 [종료되거나 시작에 실패한 stdio 서버](#stdio-servers-that-exit-or-fail-to-start)를 참조하세요.386Claude Code는 세션 도중 끊어진 원격 서버에 다시 연결하고, 일시적인 오류 후 HTTP 또는 SSE 서버의 첫 번째 연결을 재시도합니다. stdio 서버에 대해서는 [종료되거나 시작에 실패한 stdio 서버](#stdio-servers-that-exit-or-fail-to-start)를 참조하십시오.

387 387 

388#### 원격 서버의 세션 중 연결 끊김388#### 세션 도중 원격 서버 연결 끊김

389 389 

390Claude Code는 먼저 연결이 끊어진 원격 서버에 대해 1초 지연으로 시작하여 매번 두 배씩 늘리는 지수 백오프를 사용해 최대 5번 재연결을 시도합니다:390Claude Code는 먼저 끊어진 원격 서버에 지수 백오프로 최대 다섯 번 재연결을 시도하며, 1초 지연으로 시작하여 매번 두 배로 늘립니다.

391 391 

392* **대화형 세션**: `/mcp`는 Claude Code가 재연결하는 동안 서버를 보류 중으로 표시합니다. 5번의 실패 시도 후 Claude Code는 서버를 실패로 표시하거나 서버가 다시 인증이 필요할 때 인증 필요로 표시합니다. 실패로 표시할 때 `MCP server "<name>" disconnected · open /mcp to reconnect` 알림이 표시됩니다. `/mcp`에서 수동으로 재시도할 수 있습니다.392* **대화형 세션에서**: Claude Code가 재연결하는 동안 `/mcp`는 서버를 대기 중으로 표시합니다. 다섯 번 실패하면 Claude Code는 서버를 실패로 표시하거나, 서버에 다시 인가가 필요한 경우 인증 필요로 표시합니다. 서버를 실패로 표시하면 `MCP server "<name>" disconnected · open /mcp to reconnect` 알림이 표시됩니다. `/mcp`에서 수동으로 재시도할 수 있습니다.

393* **[`claude -p`](https://code.claude.com/docs/ko/headless) 실행 및 [Agent SDK](https://code.claude.com/docs/ko/agent-sdk/overview.md) 세션**: Claude Code는 동일한 5번의 시도를 수행하지만, 시도를 표시할 `/mcp` 패널은 없습니다. 5번 모두 실패하면 서버의 도구 없이 실행이 계속됩니다:393* **[`claude -p`](https://code.claude.com/docs/ko/headless) 실행과 [Agent SDK](https://code.claude.com/docs/ko/agent-sdk/overview.md) 세션에서**: Claude Code는 동일하게 다섯 번 시도하지만, 이를 표시할 `/mcp` 패널은 없습니다. 다섯 번 모두 실패하면 실행은 서버의 도구 없이 계속됩니다.

394 * **5xx 응답이나 시간 초과와 같은 일시적 오류 후**: Claude Code는 HTTP 또는 SSE 서버를 백그라운드에서 계속 재시도합니다. 재시도는 최대 약 30분 동안 지속되며, 재시도로 연결되면 서버의 도구를 다시 사용할 수 있게 됩니다. 그때까지 Agent SDK 세션은 [상태](https://code.claude.com/docs/ko/agent-sdk/mcp.md#error-handling)를 `failed`로 보고하며, 코드에서 [서버를 다시 연결](https://code.claude.com/docs/ko/agent-sdk/mcp.md#error-handling)할 수 있습니다. `claude -p`에서 다시 연결하려면 실행을 다시 시작하세요.394 * **5xx 응답이나 타임아웃과 같은 일시적인 오류 후**: Claude Code는 백그라운드에서 HTTP 또는 SSE 서버를 계속 재시도합니다. 재시도는 최대 약 30분간 지속되며, 연결되면 서버의 도구를 다시 사용할 수 있게 됩니다. 그때까지 Agent SDK 세션은 [상태](https://code.claude.com/docs/ko/agent-sdk/mcp.md#error-handling)를 `failed`로 보고하며, 코드에서 [서버를 다시 연결](https://code.claude.com/docs/ko/agent-sdk/mcp.md#error-handling)할 수 있습니다. `claude -p`에서 다시 연결하려면 실행을 다시 시작하십시오.

395 * **서버가 [다시 로그인하도록 요구할 때](#authenticate-with-remote-mcp-servers)**: Claude Code는 재시도를 중지하고, Agent SDK 세션은 서버의 상태를 `needs-auth`로 보고합니다. 셸에서 [`claude mcp login <name>`](#authenticate-from-the-command-line)으로 로그인하세요. 그런 다음 실행을 다시 시작하거나, Agent SDK 세션에서는 대신 [서버를 다시 연결](https://code.claude.com/docs/ko/agent-sdk/mcp.md#error-handling)하세요.395 * **서버가 [다시 로그인을 요구하는 경우](#authenticate-with-remote-mcp-servers)**: Claude Code는 재시도를 중단하고, Agent SDK 세션은 서버 상태를 `needs-auth`로 보고합니다. 셸에서 [`claude mcp login <name>`](#authenticate-from-the-command-line)으로 로그인하십시오. 그런 다음 실행을 다시 시작하거나, Agent SDK 세션에서는 대신 [서버를 다시 연결](https://code.claude.com/docs/ko/agent-sdk/mcp.md#error-handling)하십시오.

396 396 

397#### 실패한 첫 연결397#### 첫 번째 연결 실패

398 398 

399HTTP 또는 SSE 서버의 첫 연결이 5xx 응답, 연결 거부 또는 시간 초과와 같은 일시적 오류로 실패하면 Claude Code는 최대 3번 재시도합니다. 연결이 여전히 실패하면 Claude Code는 서버를 실패로 표시합니다.399HTTP 또는 SSE 서버의 첫 번째 연결이 5xx 응답, 연결 거부 또는 타임아웃과 같은 일시적인 오류로 실패하면 Claude Code는 최대 세 번 재시도합니다. 그래도 연결에 실패하면 Claude Code는 서버를 실패로 표시합니다.

400 400 

401이러한 재시도는 다음 경우에는 적용되지 않습니다:401다음 경우에는 이러한 재시도가 적용되지 않습니다.

402 402 

403* stdio 서버의 첫 연결. 다시 시도하려면 [종료되거나 시작에 실패한 stdio 서버](#stdio-servers-that-exit-or-fail-to-start)를 참조하세요403* stdio 서버의 첫 번째 연결. 다시 시도하려면 [종료되거나 시작에 실패한 stdio 서버](#stdio-servers-that-exit-or-fail-to-start)를 참조하십시오

404* WebSocket 서버의 첫 연결. 대화형 터미널 세션에서 다시 시도하려면 `/mcp`의 서버 메뉴에서 **Reconnect**를 선택하세요404* WebSocket 서버의 첫 번째 연결. 대화형 터미널 세션에서 다시 시도하려면 `/mcp`의 서버 메뉴에서 **Reconnect**를 선택하십시오

405* 인증 또는 찾을 수 없음 오류. 구성 변경이 필요하기 때문입니다. [`headersHelper`](#use-dynamic-headers-for-custom-authentication)가 서버의 `Authorization` 헤더의 유일한 소스일 때 Claude Code는 인증 오류를 재시도합니다. 각 시도에서 도우미를 다시 실행하고 새 자격 증명을 선택할 수 있기 때문입니다.405* 인증 또는 찾을 수 없음 오류. 해결하려면 구성 변경이 필요하기 때문입니다. 단, [`headersHelper`](#use-dynamic-headers-for-custom-authentication)가 서버의 `Authorization` 헤더의 유일한 출처인 경우, Claude Code는 매 시도마다 헬퍼를 다시 실행하여 새 자격 증명을 가져올 수 있으므로 인증 오류도 재시도합니다

406 406 

407#### 종료되거나 시작에 실패한 stdio 서버407#### 종료되거나 시작에 실패한 stdio 서버

408 408 

409stdio 서버를 다시 시작하려면 서버에 일어난 일과 일치하는 열을 읽으세요. Claude Code를 실행하는 방식(대화형 세션, `claude -p` 실행 또는 Agent SDK 세션)에 따라 해당하는 행을 찾으세요.409stdio 서버를 다시 시작하려면 서버에 발생한 상황에 해당하는 열을 읽으십시오. 행은 Claude Code를 실행하는 방식(대화형 세션, `claude -p` 실행 또는 Agent SDK 세션)으로 찾습니다.

410 410 

411| Claude Code 실행 방식 | 세션 중 서버 프로세스가 종료된 경우 | 서버의 첫 연결이 실패한 경우 |411| Claude Code 실행 방식 | 세션 도중 서버 프로세스가 종료된 경우 | 서버의 첫 번째 연결이 실패한 경우 |

412| - | - | - |412| - | - | - |

413| 대화형 세션 | Claude Code는 서버를 실패로 표시합니다. 다시 시작하려면 `/mcp`의 서버 메뉴에서 **Reconnect**를 선택하세요 | Claude Code는 서버를 실패로 표시합니다. 다시 시작하려면 `/mcp`의 서버 메뉴에서 **Reconnect**를 선택하세요 |413| 대화형 세션 | Claude Code가 서버를 실패로 표시합니다. 다시 시작하려면 `/mcp`의 서버 메뉴에서 **Reconnect**를 선택하십시오 | Claude Code가 서버를 실패로 표시합니다. 다시 시작하려면 `/mcp`의 서버 메뉴에서 **Reconnect**를 선택하십시오 |

414| `claude -p` 실행 | Claude가 다음에 서버의 도구 중 하나를 호출할 때 Claude Code가 서버를 다시 시작하며, 서버가 연결되면 호출이 실행됩니다 | 서버의 도구 없이 실행이 계속됩니다. Claude Code가 연결을 다시 시도하도록 하려면 실행을 다시 시작하세요. 플러그인이 서버를 제공하는 경우 새 실행은 실패 후 15분 동안 연결을 건너뛰므로, 먼저 그만큼 기다리거나 [더 빨리 재시도](https://code.claude.com/docs/ko/errors.md#skipping-connection-recent-failure-cached)하세요 |414| `claude -p` 실행 | 다음에 Claude가 서버의 도구 중 하나를 호출할 때 Claude Code가 서버를 다시 시작하며, 서버가 연결되면 호출이 실행됩니다 | 실행은 서버의 도구 없이 계속됩니다. Claude Code가 연결을 다시 시도하도록 하려면 실행을 다시 시작하십시오. 플러그인이 서버를 제공하는 경우, 실패 후 15분 동안은 새 실행에서 연결을 건너뛰므로 먼저 그만큼 기다리거나 [더 빨리 재시도](https://code.claude.com/docs/ko/errors.md#skipping-connection-recent-failure-cached)하십시오 |

415| Agent SDK 세션 | Claude가 다음에 서버의 도구 중 하나를 호출할 때 Claude Code가 서버를 다시 시작하며, 서버가 연결되면 호출이 실행됩니다 | 서버의 도구 없이 세션이 계속됩니다. 코드에서 [서버를 다시 연결](https://code.claude.com/docs/ko/agent-sdk/mcp.md#error-handling)할 수 있습니다 |415| Agent SDK 세션 | 다음에 Claude가 서버의 도구 중 하나를 호출할 때 Claude Code가 서버를 다시 시작하며, 서버가 연결되면 호출이 실행됩니다 | 세션은 서버의 도구 없이 계속됩니다. 코드에서 [서버를 다시 연결](https://code.claude.com/docs/ko/agent-sdk/mcp.md#error-handling)할 수 있습니다 |

416 416 

417#### 실패한 검색 요청417#### 검색 요청 실패

418 418 

419서버가 연결된 후 Claude Code는 `tools/list`, `prompts/list` 및 `resources/list`와 같은 기능 검색 요청을 보냅니다. Claude Code는 일시적 네트워크 또는 서버 오류 후 짧은 백오프로 최대 3번 재시도합니다. 인증 오류, 4xx 응답 또는 요청 시간 초과는 재시도하지 않습니다.419서버가 연결되면 Claude Code는 `tools/list`, `prompts/list`, `resources/list`와 같은 기능 검색 요청을 보냅니다. Claude Code는 일시적인 네트워크 또는 서버 오류 후 이러한 요청을 짧은 백오프로 최대 세 번 재시도합니다. 인증 오류, 4xx 응답 또는 요청 시간 초과는 재시도하지 않습니다.

420 420 

421#### 실패한 서버 직접 재시도421#### 실패한 서버 직접 재시도

422 422 

423실패했거나 인증이 필요한 모든 서버를 재시도하려면 대화형 터미널 세션의 Claude Code 프롬프트에서 `/mcp reconnect all`을 실행합니다. 이 기능에는 Claude Code v2.1.284 이상이 필요합니다. 이전 버전에서는 `MCP server "all" not found`가 출력됩니다.423실패했거나 인증이 필요한 모든 서버를 재시도하려면, 대화형 터미널 세션의 Claude Code 프롬프트에서 `/mcp reconnect all`을 실행하십시오. 이 기능에는 Claude Code v2.1.284 이상이 필요합니다. 이전 버전에서는 `MCP server "all" not found`가 출력됩니다.

424 424 

425#### Claude가 서버 실패를 배우는 방법425#### Claude가 서버 실패를 알게 되는 방법

426 426 

427구성된 서버가 연결에 실패하면 Claude Code가 Claude에 알리는지 여부는 [도구 검색](#scale-with-mcp-tool-search)에 따라 다릅니다. 기본적으로 켜져 있습니다:427Claude Code가 연결에 실패한 구성된 서버에 대해 Claude에 알리는지 여부는 기본적으로 켜져 있는 [도구 검색](#scale-with-mcp-tool-search)에 따라 달라집니다.

428 428 

429* 도구 검색을 사용하면 Claude Code는 Claude에 어느 서버가 실패했는지와 연결 오류를 알리므로, Claude는 응답에서 연결 실패를 보고합니다. Claude Code는 일치하는 도구를 찾지 못한 `ToolSearch` 결과에 동일한 정보를 포함합니다.429* 도구 검색을 사용하면 Claude Code는 어떤 서버가 실패했는지와 연결 오류를 Claude에 알리므로, Claude는 응답에서 연결 실패를 보고합니다. Claude Code는 일치하는 도구를 찾지 못한 `ToolSearch` 결과에도 동일한 정보를 포함합니다.

430* [도구 검색이 없는 구성](#configure-tool-search)에서 Claude Code는 실패한 서버 연결을 Claude에 보고하지 않습니다.430* [도구 검색을 사용하지 않는 구성](#configure-tool-search)에서는 Claude Code가 실패한 서버 연결을 Claude에 보고하지 않습니다.

431 431 

432### 채널을 사용한 메시지 푸시432### 채널로 메시지 푸시

433 433 

434MCP 서버는 또한 메시지를 세션에 직접 푸시할 수 있으므로 Claude는 CI 결과, 모니터링 경고 또는 채팅 메시지와 같은 외부 이벤트에 반응할 수 있습니다. 이를 활성화하려면 서버가 `claude/channel` 기능을 선언하고 시작 시 `--channels` 플래그로 옵트인합니다. 공식적으로 지원되는 채널을 사용하려면 [채널](https://code.claude.com/docs/ko/channels.md)을 참조하거나, 자신만의 채널을 구축하려면 [채널 참조](https://code.claude.com/docs/ko/channels-reference.md)를 참조하세요.434MCP 서버는 세션에 메시지를 직접 푸시하여 Claude가 CI 결과, 모니터링 알림, 채팅 메시지와 같은 외부 이벤트에 반응하도록 할 수도 있습니다. 이를 활성화하려면 서버가 `claude/channel` 기능을 선언하고, 시작 시 `--channels` 플래그로 옵트인해야 합니다. 공식적으로 지원되는 채널을 사용하려면 [채널](https://code.claude.com/docs/ko/channels.md)을, 직접 만들려면 [채널 참조](https://code.claude.com/docs/ko/channels-reference.md)를 참조하십시오.

435 435 

436[v2 런타임](#mcp-client-runtimes)에서 MCP 프로토콜 개정 2026-07-28을 협상하는 채널 서버는 채널 메시지를 전달할 수 없으므로 Claude Code는 이를 채널로 등록하지 않습니다. 해당 개정을 지원하지 않는 채널 서버는 이전 핸드셰이크로 연결되며 이전과 같이 등록됩니다.436[v2 런타임](#mcp-client-runtimes)에서 MCP 프로토콜 리비전 2026-07-28을 협상한 채널 서버는 채널 메시지를 전달할 수 없으므로 Claude Code는 이를 채널로 등록하지 않습니다. 해당 리비전을 지원하지 않는 채널 서버는 이전 핸드셰이크로 연결하여 이전과 같이 등록됩니다.

437 437 

438Claude Code는 기본적으로 stdio 서버에 해당 개정을 요청합니다. stdio 채널 서버를 이전 핸드셰이크에 유지하려면 [`MCP_PROTOCOL_NEGOTIATION`](https://code.claude.com/docs/ko/env-vars)을 `legacy`로 설정하세요. 이렇게 하면 모든 서버가 이전 핸드셰이크에 유지됩니다.438Claude Code는 기본적으로 stdio 서버에 해당 리비전을 요청합니다. stdio 채널 서버를 이전 핸드셰이크로 유지하려면 [`MCP_PROTOCOL_NEGOTIATION`](https://code.claude.com/docs/ko/env-vars)을 `legacy`로 설정하십시오. 이렇게 하면 모든 서버가 이전 핸드셰이크를 유지합니다.

439 439 

440> [!TIP]440> [!TIP]

441>441>

442> 팁:442> 팁:

443>443>

444> * `-s` 또는 `--scope` 플래그를 사용하여 구성이 저장되는 위치를 지정하세요:444> * `-s` 또는 `--scope` 플래그로 구성이 저장되는 위치를 지정합니다.

445> * `local` (기본값): 현재 프로젝트에서만 사용자에게만 사용 가능445> * `local`(기본값): 현재 프로젝트에서 사용자 본인만 사용 가능

446> * `project`: `.mcp.json` 파일을 통해 프로젝트의 모든 사람과 공유446> * `project`: `.mcp.json` 파일을 통해 프로젝트의 모든 사람과 공유

447> * `user`: 모든 프로젝트에서 사용자에게 사용 가능447> * `user`: 모든 프로젝트에서 사용자 본인이 사용 가능

448> * `-e` 또는 `--env` 플래그로 환경 변수를 설정하세요 (예: `-e KEY=value`)448> * `-e` 또는 `--env` 플래그로 환경 변수를 설정합니다(예: `-e KEY=value`)

449> * `--transport` 및 `--header` 플래그는 `-t` 및 `-H` 단축형도 허용합니다449> * `--transport` 및 `--header` 플래그는 `-t` 및 `-H` 짧은 형식도 허용합니다

450> * `MCP_TIMEOUT` 환경 변수를 사용하여 MCP 서버 시작 시간 초과를 구성하세요 (예: `MCP_TIMEOUT=10000 claude`는 10초 시간 초과를 설정)450> * `MCP_TIMEOUT` 환경 변수로 MCP 서버 시작 타임아웃을 구성합니다(예: `MCP_TIMEOUT=10000 claude`는 10초 타임아웃을 설정)

451> * 서버당 도구 실행 시간 초과를 설정하려면 해당 서버의 `.mcp.json` 항목에 밀리초 단위의 `timeout` 필드를 추가하세요. 예를 들어 10분의 경우 `"timeout": 600000`입니다. 이는 해당 서버에만 `MCP_TOOL_TIMEOUT` 환경 변수를 재정의합니다451> * 해당 서버의 `.mcp.json` 항목에 밀리초 단위의 `timeout` 필드를 추가하여 서버별 도구 실행 타임아웃을 설정합니다(예: 10분의 경우 `"timeout": 600000`). 이는 해당 서버에 대해서만 `MCP_TOOL_TIMEOUT` 환경 변수를 재정의합니다

452> * Claude Code는 MCP 도구 출력이 10,000 토큰을 초과할 때 경고를 표시하고 기본적으로 출력을 25,000 토큰으로 제한합니다. 토큰 제한을 변경하려면 `MAX_MCP_OUTPUT_TOKENS` 환경 변수를 설정하세요 (예: `MAX_MCP_OUTPUT_TOKENS=50000`). 경고 임계값은 고정됩니다. 서버가 도구 자체의 제한을 높이지 않는 한, 50,000자를 초과하는 성공한 텍스트 결과는 이 변수와 관계없이 파일에 저장됩니다. [MCP 출력 제한 및 경고](#mcp-output-limits-and-warnings)를 참조하세요452> * Claude Code는 MCP 도구 출력이 10,000 토큰을 초과하면 경고를 표시하며, 기본적으로 출력을 25,000 토큰으로 제한합니다. 토큰 제한을 변경하려면 `MAX_MCP_OUTPUT_TOKENS` 환경 변수를 설정합니다(예: `MAX_MCP_OUTPUT_TOKENS=50000`). 경고 임계값은 고정되어 있습니다. 서버가 도구 자체의 제한을 높이지 않는 한, 50,000자보다 긴 성공적인 텍스트 결과는 이 변수와 관계없이 파일에 저장됩니다. [MCP 출력 제한 및 경고](#mcp-output-limits-and-warnings)를 참조하십시오

453> * OAuth 2.0 인증이 필요한 원격 서버로 인증하려면 `/mcp`를 사용하세요453> * OAuth 2.0 인증이 필요한 원격 서버에 인증하려면 `/mcp`를 사용합니다

454 454 

455### MCP 도구 호출의 시간 제한455### MCP 도구 호출의 시간 제한

456 456 

457MCP 도구 호출이 실행될 수 있는 시간을 제한하려면 다음을 사용합니다.457MCP 도구 호출이 실행될 수 있는 시간을 제한하려면 다음을 사용합니다.

458 458 

459* **서버별**: 해당 서버의 구성 항목에 밀리초 단위의 `timeout` 필드를 추가합니다459* **서버별**: 해당 서버의 구성 항목에 밀리초 단위의 `timeout` 필드를 추가합니다

460* **모든 서버 공통**: [`MCP_TOOL_TIMEOUT`](https://code.claude.com/docs/ko/env-vars)을 설정합니다460* **전체 서버**: [`MCP_TOOL_TIMEOUT`](https://code.claude.com/docs/ko/env-vars)을 설정합니다

461 461 

462서버당 `timeout`은 도구 호출당 하드 월클록 제한이며, 서버의 진행 알림은 이를 연장하지 않습니다. 1000 미만의 값은 무시되고 `MCP_TOOL_TIMEOUT`으로 넘어가거나, 해당 변수가 설정되지 않은 경우 약 28시간의 기본값으로 넘어갑니다. HTTP, SSE 또는 [claude.ai 커넥터](https://code.claude.com/docs/ko/mcp.md#use-mcp-servers-from-claude-ai) 서버의 경우 서버의 첫 응답 바이트까지 각 요청을 포함하는 요청당 두 번째 타이머도 있습니다. Claude Code는 해당 타이머를 60초, 서버에 적용되는 도구 시간 초과 및 `MCP_TIMEOUT` 중 가장 큰 값으로 설정합니다. 설정되지 않은 `MCP_TOOL_TIMEOUT`의 28시간 기본값은 해당 비교에 들어가지 않으며, 60초 미만의 값은 타이머를 단축하지 않습니다. Stdio 및 WebSocket 서버에는 요청당 타이머가 없습니다.462서버별 `timeout`은 도구 호출당 엄격한 실제 경과 시간 제한이며, 서버의 진행 알림으로 연장되지 않습니다. 1000 미만의 값은 무시되고 `MCP_TOOL_TIMEOUT`으로 폴백하며, 해당 변수가 설정되지 않은 경우 기본값인 약 28시간이 적용됩니다. HTTP, SSE 또는 [claude.ai 커넥터](https://code.claude.com/docs/ko/mcp.md#use-mcp-servers-from-claude-ai) 서버에는 각 요청을 서버의 첫 번째 응답 바이트까지 다루는 두 번째 요청별 타이머도 있습니다. Claude Code는 이 타이머를 60초, 서버에 적용되는 도구 타임아웃, `MCP_TIMEOUT` 세 값 중 가장 큰 값으로 설정합니다. 설정되지 않은 `MCP_TOOL_TIMEOUT`의 28시간 기본값은 이 비교에 포함되지 않으며, 60초 미만의 값은 타이머를 줄이지 않습니다. stdio 및 WebSocket 서버에는 요청별 타이머가 없습니다.

463 463 

464서버당 최소 1000의 `timeout`은 또한 아래에 설명된 유휴 시간 초과의 하한으로 작동합니다: Claude Code는 서버당 `timeout`보다 더 빨리 유휴 상태로 인해 해당 서버의 도구 호출을 중단하지 않습니다.4641000 이상의 서버별 `timeout`은 아래에 설명된 유휴 타임아웃의 하한으로도 작용합니다. Claude Code는 서버별 `timeout`보다 빨리 유휴 상태를 이유로 해당 서버의 도구 호출을 중단하지 않습니다.

465 465 

466MCP 서버에 대한 도구 호출이 유휴 윈도우 동안 응답 및 진행 알림을 보내지 않으면 월클록 제한을 기다리는 대신 오류로 중단됩니다. 유휴 시간 초과는 IDE 서버 및 SDK 인프로세스 서버를 제외한 모든 서버 유형에 적용됩니다. 유휴 윈도우는 HTTP, SSE, WebSocket 및 [claude.ai 커넥터](#use-mcp-servers-from-claude-ai) 서버의 경우 기본값 5분, stdio 서버의 경우 30분입니다.466유휴 시간 동안 응답이나 진행 알림을 보내지 않는 MCP 서버에 대한 도구 호출은 실제 경과 시간 제한을 기다리지 않고 오류와 함께 중단됩니다. 유휴 타임아웃은 IDE 서버와 SDK 인프로세스 서버를 제외한 모든 서버 유형에 적용됩니다. 유휴 시간의 기본값은 HTTP, SSE, WebSocket, [claude.ai 커넥터](#use-mcp-servers-from-claude-ai) 서버의 경우 5분이고, stdio 서버의 경우 30분입니다.

467 467 

468[`CLAUDE_CODE_MCP_TOOL_IDLE_TIMEOUT`](https://code.claude.com/docs/ko/env-vars) 환경 변수를 밀리초 단위로 설정하여 유휴 윈도우를 변경하거나, `0`으로 설정하여 확인을 비활성화하세요.468유휴 시간을 변경하려면 [`CLAUDE_CODE_MCP_TOOL_IDLE_TIMEOUT`](https://code.claude.com/docs/ko/env-vars) 환경 변수를 밀리초 단위로 설정하고, 확인을 비활성화하려면 `0`으로 설정하십시오.

469 469 

470이 시간 초과는 호출이 실행될 수 있는 기간을 제한하며, 항상 세션을 차단하는 기간을 제한하지는 않습니다: 2분을 지나 실행되는 주 대화 호출은 먼저 백그라운드 작업으로 이동합니다. [긴 도구 호출의 자동 백그라운드 처리](#automatic-backgrounding-of-long-tool-calls)를 참조하세요.470이러한 타임아웃은 호출이 실행될 수 있는 시간을 제한하지만, 항상 세션을 차단하는 시간을 제한하는 것은 아닙니다. 2분을 넘게 실행되는 메인 대화의 호출은 먼저 백그라운드 작업으로 이동합니다. [긴 도구 호출의 자동 백그라운드 전환](#automatic-backgrounding-of-long-tool-calls)을 참조하십시오.

471 471 

472### 긴 도구 호출의 자동 백그라운드 처리472### 긴 도구 호출의 자동 백그라운드 전환

473 473 

474[`/tasks`](https://code.claude.com/docs/ko/commands#all-commands)의 백그라운드 호출 세부 정보 보기에 `runs on the server; survives exiting this session`이 표시되면 [서버에서 실행되는 MCP 작업](#mcp-tasks-that-run-on-the-server)을 참조하세요.474[`/tasks`](https://code.claude.com/docs/ko/commands#all-commands)에서 백그라운드 호출의 세부 정보 보기에 `runs on the server; survives exiting this session`이 표시되면 [서버에서 실행되는 MCP 작업](#mcp-tasks-that-run-on-the-server)을 참조하십시오.

475 475 

476주 대화에서 2분 이상 실행 중인 MCP 도구 호출은 세션을 차단하는 대신 백그라운드 작업으로 이동합니다. Claude는 작업 ID를 즉시 받고 계속 작업하며, 호출이 완료되면 결과가 작업 알림으로 도착합니다.476메인 대화에서 2분이 지나도 계속 실행 중인 MCP 도구 호출은 세션을 차단하지 않고 백그라운드 작업으로 이동합니다. Claude는 즉시 작업 ID를 받고 계속 작업하며, 호출이 완료되면 결과가 작업 알림으로 도착합니다.

477 477 

478작업은 [`/tasks`](https://code.claude.com/docs/ko/commands#all-commands)에 나타나며, 여기서 중지할 수도 있습니다. 작업은 세션을 종료하면 유지되지 않습니다. 작업 항목에는 서버가 보고한 최신 진행 상황이 표시됩니다. 작업을 중지하면 Claude Code는 호출을 취소하고 결과가 오지 않는다고 Claude에 알립니다. 중지한다고 해서 서버가 중지된다는 보장은 없습니다: 서버가 이미 작업의 일부를 수행했거나 여전히 작업을 완료할 수 있습니다.478작업은 [`/tasks`](https://code.claude.com/docs/ko/commands#all-commands)에 표시되며 여기서 중지할 수도 있습니다. 작업은 세션을 종료하면 유지되지 않습니다. 작업 항목에는 서버가 보고한 최신 진행 상황이 표시됩니다. 작업을 중지하면 Claude Code는 호출을 취소하고 결과가 오지 않는다고 Claude에 알립니다. 중지해도 서버가 중단된다는 보장은 없습니다. 서버가 이미 작업의 일부를 수행했거나 여전히 완료할 수 있습니다.

479 479 

480호출이 백그라운드에서 실행되는 동안 호출당 제한이 여전히 적용됩니다: 서버당 `timeout` 또는 [`MCP_TOOL_TIMEOUT`](https://code.claude.com/docs/ko/env-vars)으로 설정된 월클록 제한 및 [`CLAUDE_CODE_MCP_TOOL_IDLE_TIMEOUT`](https://code.claude.com/docs/ko/env-vars)으로 설정된 유휴 시간 초과입니다.480호출이 백그라운드에서 실행되는 동안에도 호출별 제한은 계속 적용됩니다. 즉, 서버별 `timeout` 또는 [`MCP_TOOL_TIMEOUT`](https://code.claude.com/docs/ko/env-vars)으로 설정된 실제 경과 시간 제한과 [`CLAUDE_CODE_MCP_TOOL_IDLE_TIMEOUT`](https://code.claude.com/docs/ko/env-vars)으로 설정된 유휴 타임아웃이 적용됩니다.

481 481 

482자동 백그라운드 전환을 변경하거나 끄려면 다음을 수행합니다.482자동 백그라운드 전환을 변경하거나 끄려면 다음을 사용합니다.

483 483 

484* 임계값을 변경하려면 [`CLAUDE_CODE_MCP_AUTO_BACKGROUND_MS`](https://code.claude.com/docs/ko/env-vars) 환경 변수를 밀리초 단위로 설정하고, 자동 백그라운드 전환을 끄려면 `0`으로 설정합니다. `0`으로 설정하면 대화형 세션에서 Claude가 [MCP 작업을 기다립니다](#make-claude-wait-for-the-result-of-an-mcp-task)484* 임계값을 변경하려면 [`CLAUDE_CODE_MCP_AUTO_BACKGROUND_MS`](https://code.claude.com/docs/ko/env-vars) 환경 변수를 밀리초 단위로 설정하고, 자동 백그라운드 전환을 끄려면 `0`으로 설정합니다. `0`이면 대화형 세션에서 Claude가 [MCP 작업도 기다립니다](#make-claude-wait-for-the-result-of-an-mcp-task)

485* [`CLAUDE_CODE_DISABLE_BACKGROUND_TASKS`](https://code.claude.com/docs/ko/env-vars)를 `1`로 설정하여 자동 백그라운드 전환과 [백그라운드 명령](https://code.claude.com/docs/ko/tools-reference.md#background-commands)을 끕니다485* 자동 백그라운드 전환과 [백그라운드 명령](https://code.claude.com/docs/ko/tools-reference.md#background-commands)을 끄려면 [`CLAUDE_CODE_DISABLE_BACKGROUND_TASKS`](https://code.claude.com/docs/ko/env-vars)를 `1`로 설정합니다

486 486 

487일부 호출은 백그라운드로 이동하지 않습니다:487일부 호출은 백그라운드로 이동하지 않습니다.

488 488 

489* [서브에이전트](https://code.claude.com/docs/ko/sub-agents.md)의 호출; Claude Code는 주 대화 호출만 백그라운드 처리합니다489* [서브에이전트](https://code.claude.com/docs/ko/sub-agents.md)의 호출. Claude Code는 메인 대화의 호출만 백그라운드로 전환합니다

490* IDE 서버에 대한 호출490* IDE 서버에 대한 호출

491* [비대화형 모드](https://code.claude.com/docs/ko/headless.md)의 호출. `CLAUDE_AUTO_BACKGROUND_TASKS`가 `1`로 설정되지 않는 한. 일회성 실행은 결과가 도착하기 전에 끝날 수 있기 때문입니다491* [비대화형 모드](https://code.claude.com/docs/ko/headless.md)의 호출. 일회성 실행은 결과가 도착하기 전에 종료될 수 있으므로, `CLAUDE_AUTO_BACKGROUND_TASKS`가 `1`로 설정된 경우에만 예외입니다

492 492 

493열린 [유도 대화 상자](#respond-to-mcp-elicitation-requests)를 기다리는 호출은 대화 상자가 열려 있는 동안 백그라운드 처리되지 않습니다. 서버가 느린 것이 아니라 입력을 기다리고 있으므로 Claude Code는 대화 상자가 닫힐 때까지 이동을 연기합니다.493열려 있는 [elicitation 대화 상자](#respond-to-mcp-elicitation-requests)를 기다리는 호출은 대화 상자가 열려 있는 동안 백그라운드로 전환되지 않습니다. 서버가 느린 것이 아니라 사용자 입력을 기다리며 차단된 상태이므로, Claude Code는 대화 상자가 닫힐 때까지 이동을 미룹니다.

494 494 

495### 서버에서 실행되는 MCP 작업495### 서버에서 실행되는 MCP 작업

496 496 

497MCP 작업은 보고서 내보내기나 빌드처럼 MCP 서버가 [MCP tasks 확장](https://modelcontextprotocol.io/extensions/tasks/overview)을 사용하여 직접 실행하는 긴 작업입니다. Claude의 도구 호출은 서버가 작업을 수락하면 반환되므로, [Claude가 기다리도록](#make-claude-wait-for-the-result-of-an-mcp-task) 하지 않는 한 Claude는 계속 작업합니다. 작업이 끝나면 트랜스크립트에 그 사실이 표시되고 Claude가 결과를 받습니다. 결과는 Claude에게 요청하세요.497MCP 작업은 보고서 내보내기나 빌드와 같이 MCP 서버가 [MCP tasks 확장](https://modelcontextprotocol.io/extensions/tasks/overview)을 사용하여 직접 실행하는 긴 작업입니다. Claude의 도구 호출은 서버가 작업을 수락하면 반환되므로, [Claude가 기다리도록 하지](#make-claude-wait-for-the-result-of-an-mcp-task) 않는 한 Claude는 계속 작업합니다. 작업이 끝나면 트랜스크립트에 그 사실이 표시되고 Claude가 결과를 받습니다. Claude에게 결과를 요청하십시오.

498 498 

499그동안 하단에는 `1 MCP task`와 같은 개수가 표시되며, Claude Code는 서버에 작업 상태를 확인하면서 작업을 추적합니다. 원격 서버의 작업은 종료한 후에도 계속 실행됩니다. 다시 추적하려면 [같은 세션을 재개](#exit-clear-or-resume-while-an-mcp-task-runs)하세요.499그동안 푸터에는 `1 MCP task`와 같은 수가 표시되며, Claude Code는 서버에 상태를 확인하여 작업을 추적합니다. 원격 서버의 작업은 종료한 후에도 계속 실행됩니다. 다시 추적하려면 [같은 세션을 재개](#exit-clear-or-resume-while-an-mcp-task-runs)하십시오.

500 500 

501> [!NOTE]501> [!NOTE]

502>502>

503> MCP 작업은 Claude Code CLI에서 공개 베타이며 Claude Code v2.1.304 이상이 필요합니다. 이를 사용할 수 있는 세션과 서버는 [호출이 MCP 작업이 되기 위한 조건](#requirements-for-mcp-tasks)에 나와 있습니다.503> MCP 작업은 Claude Code CLI에서 공개 베타로 제공되며 Claude Code v2.1.304 이상이 필요합니다. 이 기능을 사용할 수 있는 세션과 서버는 [호출이 MCP 작업이 되기 위한 조건](#requirements-for-mcp-tasks)에 나와 있습니다.

504 504 

505#### MCP 작업 중지 또는 결과 받기505#### MCP 작업 중지 또는 결과 가져오기

506 506 

507실행 중인 작업을 중지하려면 [`/tasks`](https://code.claude.com/docs/ko/commands#all-commands)에서 작업을 선택하고 `x`를 누르거나 Claude에게 요청합니다. Claude Code는 작업 추적을 중단하고 서버에 취소를 요청하지만, 서버가 그래도 작업을 완료할 수 있습니다. 연결이 끊긴 서버는 먼저 `/mcp`에서 다시 연결하세요. 그렇지 않으면 취소 요청이 전송되지 않고, Claude Code가 작업을 잊어 다시 추적할 수 없습니다. `Esc`를 눌러도 백그라운드 작업은 중지되지 않습니다.507실행 중인 작업을 중지하려면 [`/tasks`](https://code.claude.com/docs/ko/commands#all-commands)에서 작업을 선택하고 `x`를 누르거나 Claude에게 요청하십시오. Claude Code는 작업 추적을 중단하고 서버에 취소를 요청하지만, 서버는 여전히 작업을 완료할 수 있습니다. 연결이 끊긴 서버는 먼저 `/mcp`에서 다시 연결하십시오. 그렇지 않으면 취소 요청이 전송되지 않고, Claude Code는 작업을 잊어버려 다시 추적할 수 없습니다. `Esc`를 눌러도 백그라운드 작업은 중지되지 않습니다.

508 508 

509작업이 끝나면 트랜스크립트에 다음과 같은 줄이 표시됩니다.509작업이 끝나면 트랜스크립트에 다음과 같은 줄이 나타납니다.

510 510 

511```text theme={null}511```text theme={null}

512MCP task <server task id> (<server>/<tool>) completed.512MCP task <server task id> (<server>/<tool>) completed.

513```513```

514 514 

515결과는 트랜스크립트가 아니라 Claude에게 전달되므로 Claude에게 결과를 요청하세요. 결과가 도착할 때 Claude가 유휴 상태이면 Claude는 요청 없이 결과 처리를 시작합니다.515결과는 트랜스크립트가 아니라 Claude에 전달되므로 Claude에게 결과를 요청하십시오. 결과가 도착할 때 Claude가 유휴 상태이면 Claude는 요청 없이도 결과를 처리하기 시작합니다.

516 516 

517#### MCP 작업의 질문에 답변517#### MCP 작업의 질문에 답하기

518 518 

519실행 중인 작업은 [elicitation 대화상자](#respond-to-mcp-elicitation-requests)를 열어 입력을 요청할 수 있습니다. `/tasks`가 열려 있는 동안에는 대화상자가 숨겨지므로, 답변하려면 `/tasks`를 닫으세요. 거절하거나 `Esc`를 누르는 것도 서버에 대한 답변이며, 서버는 작업을 계속할지 결정합니다.519실행 중인 작업은 [elicitation 대화 상자](#respond-to-mcp-elicitation-requests)를 열어 입력을 요청할 수 있습니다. `/tasks`가 열려 있는 동안에는 대화 상자가 숨겨지므로, 답하려면 `/tasks`를 닫으십시오. 거절하거나 `Esc`를 누르는 것도 서버에 대한 응답이며, 서버는 이를 바탕으로 작업을 계속할지 결정합니다.

520 520 

521[비대화형](https://code.claude.com/docs/ko/headless.md) 세션에서 Claude Code는 입력을 요청하는 작업에 대해 [`Elicitation` 훅](https://code.claude.com/docs/ko/hooks#elicitation)을 실행하거나 Agent SDK의 `onElicitation` 콜백을 호출하지 않고 서버에 작업 취소를 요청합니다.521[비대화형](https://code.claude.com/docs/ko/headless.md) 세션에서는 Claude Code가 입력을 요청하는 작업에 대해 [`Elicitation` 훅](https://code.claude.com/docs/ko/hooks#elicitation)을 실행하거나 Agent SDK의 `onElicitation` 콜백을 호출하지 않고 서버에 작업 취소를 요청합니다.

522 522 

523#### MCP 작업 실행 중 종료, 지우기 또는 재개523#### MCP 작업 실행 중 종료, 초기화 또는 재개

524 524 

525원격 서버의 작업은 종료한 후에도 계속 실행됩니다. stdio 서버의 프로세스는 Claude Code가 종료되면 중지되지만, 그 작업은 `/tasks`에 `runs on the server; survives exiting this session`으로 표시됩니다. 해당 서버의 문서에 작업이 프로세스보다 오래 유지된다고 명시되어 있지 않다면, 종료하기 전에 작업이 끝나도록 기다리거나 `/tasks`에서 중지하세요.525원격 서버의 작업은 종료한 후에도 계속 실행됩니다. stdio 서버의 프로세스는 Claude Code가 종료될 때 중지되지만, 해당 작업은 `/tasks`에 `runs on the server; survives exiting this session`으로 표시됩니다. 해당 서버의 문서에서 작업이 프로세스보다 오래 지속된다고 명시하지 않는 한, 먼저 해당 작업이 완료되도록 두거나 `/tasks`에서 중지하십시오.

526 526 

527| 상황 | 작업에 일어나는 일 | 할 수 있는 일 |527| 상황 | 작업에 일어나는 일 | 할 수 있는 조치 |

528| - | - | - |528| - | - | - |

529| `/clear` 또는 `/branch`를 실행하거나, `/resume`으로 다른 세션으로 이동 | Claude Code가 열려 있는 동안에는 결과가 현재 대화에 도착합니다 | 종료한 후에는 작업이 시작된 세션을 `claude --resume`으로 재개합니다 |529| `/clear` 또는 `/branch`를 실행하거나, `/resume`으로 다른 세션을 재개한 경우 | Claude Code가 열려 있는 동안 결과는 현재 대화에 도착합니다 | 종료한 후에는 작업이 시작된 세션을 `claude --resume`으로 재개하십시오 |

530| Claude Code 종료 | 종료 대화상자의 `The following will stop when you exit:` 아래에 작업이 나열되더라도, 어떤 종료 옵션도 원격 서버의 작업을 취소하지 않습니다 | 먼저 `/tasks`에서 중지하거나, 나중에 같은 세션을 재개합니다 |530| Claude Code를 종료한 경우 | 종료 대화 상자에서 `The following will stop when you exit:` 아래에 작업이 나열되더라도, 어떤 종료 옵션도 원격 서버의 작업을 취소하지 않습니다 | 먼저 `/tasks`에서 중지하거나, 나중에 같은 세션을 재개하십시오 |

531| 작업의 세션으로 대화형으로 복귀: `claude --resume`, `claude --continue` 또는 `/resume` | 서버가 연결되면 Claude Code가 작업을 다시 추적하며, 그동안 작업이 끝났고 서버가 여전히 작업을 알고 있다면 Claude가 결과를 받습니다 | 서버의 이름과 연결 설정을 변경하지 않고 유지합니다 |531| `claude --resume`, `claude --continue` 또는 `/resume`으로 작업의 세션에 대화형으로 돌아온 경우 | 서버가 연결되면 Claude Code가 작업을 다시 추적하며, 그사이 작업이 완료되었고 서버가 아직 이를 알고 있으면 Claude가 결과를 받습니다 | 서버의 이름과 연결 설정을 변경하지 마십시오 |

532| 일회성 `claude -p "<prompt>"` 실행에서 `--resume` 또는 `--continue`로 작업의 세션을 재개 | 해당 실행은 작업을 추적하지 않습니다 | 대화형으로 재개하거나 `--input-format stream-json`으로 재개합니다 |532| 일회성 `claude -p "<prompt>"` 실행에서 `--resume` 또는 `--continue`로 작업의 세션을 재개한 경우 | 해당 실행은 작업을 추적하지 않습니다 | 대화형으로 재개하거나 `--input-format stream-json`으로 재개하십시오 |

533| 새 세션을 시작하거나 `--fork-session` 사용 | 새 세션은 작업을 추적하지 않습니다 | 작업을 시작한 세션을 재개합니다 |533| 새 세션을 시작하거나 `--fork-session`을 사용한 경우 | 새 세션은 작업을 추적하지 않습니다 | 작업을 시작한 세션을 재개하십시오 |

534 534 

535#### 호출이 MCP 작업이 되기 위한 조건535#### 호출이 MCP 작업이 되기 위한 조건

536 536 

537도구 호출은 다음 조건을 모두 충족할 때만 MCP 작업이 됩니다.537도구 호출은 다음 조건을 모두 충족할 때만 MCP 작업이 됩니다.

538 538 

539* 서버가 작업을 지원합니다539* 서버가 작업을 지원합니다

540* 서버가 [프로토콜 개정판 2026-07-28](#mcp-client-runtimes)로 연결된 HTTP, stdio 또는 claude.ai 커넥터 서버입니다. [`MCP_SDK_GENERATION=v1` 또는 `MCP_PROTOCOL_NEGOTIATION=legacy`](https://code.claude.com/docs/ko/env-vars)를 설정하면 이 조건이 충족되지 않습니다540* 서버가 [프로토콜 리비전 2026-07-28](#mcp-client-runtimes)로 연결된 HTTP, stdio 또는 claude.ai 커넥터 서버입니다. [`MCP_SDK_GENERATION=v1` 또는 `MCP_PROTOCOL_NEGOTIATION=legacy`](https://code.claude.com/docs/ko/env-vars)를 설정하면 이 조건이 충족되지 않습니다

541* 세션이 [기능 플래그를 가져옵니다](https://code.claude.com/docs/ko/env-vars.md#features-that-need-feature-flag-fetching). 따라서 Amazon Bedrock과 같은 서드파티 제공업체가 아니어야 하며, 텔레메트리나 플래그 가져오기가 꺼져 있지 않아야 합니다541* 세션이 [기능 플래그를 가져옵니다](https://code.claude.com/docs/ko/env-vars.md#features-that-need-feature-flag-fetching). 따라서 Amazon Bedrock과 같은 서드파티 제공업체에서는 해당되지 않으며, 텔레메트리나 플래그 가져오기를 끈 경우에도 해당되지 않습니다

542* Anthropic이 해당 종류의 세션에 MCP 작업을 활성화했습니다. v2.1.304 이상에서는 터미널 CLI 세션, [Agent SDK](https://code.claude.com/docs/ko/agent-sdk/overview.md) 세션, [GitHub Actions](https://code.claude.com/docs/ko/github-actions.md) 실행이 포함됩니다. [VS Code 확장](https://code.claude.com/docs/ko/vs-code.md)이나 [데스크톱 앱](https://code.claude.com/docs/ko/desktop.md)과 같은 다른 사용 환경에서는 MCP 작업을 사용할 수 없습니다542* Anthropic이 해당 종류의 세션에 MCP 작업을 켰습니다. v2.1.304 이상에서는 터미널 CLI 세션, [Agent SDK](https://code.claude.com/docs/ko/agent-sdk/overview.md) 세션, [GitHub Actions](https://code.claude.com/docs/ko/github-actions.md) 실행이 포함됩니다. [VS Code 확장](https://code.claude.com/docs/ko/vs-code.md)과 [데스크톱 앱](https://code.claude.com/docs/ko/desktop.md) 같은 다른 사용 환경에서는 MCP 작업을 사용할 수 없습니다

543* 호출이 [서브에이전트](https://code.claude.com/docs/ko/sub-agents.md)가 아니라 메인 대화에서 이루어집니다543* 호출이 [서브에이전트](https://code.claude.com/docs/ko/sub-agents.md)가 아닌 메인 대화에서 발생합니다

544* 세션이 대화형이거나, [Agent SDK](https://code.claude.com/docs/ko/agent-sdk/overview.md) 세션 또는 `--input-format stream-json`을 읽는 `claude -p` 실행이 다음을 충족합니다.544* 세션이 대화형이거나, [Agent SDK](https://code.claude.com/docs/ko/agent-sdk/overview.md) 세션 또는 `--input-format stream-json`을 읽는 `claude -p` 실행이 다음 조건을 충족합니다.

545 * [`CLAUDE_AUTO_BACKGROUND_TASKS`](https://code.claude.com/docs/ko/env-vars)가 `1`545 * [`CLAUDE_AUTO_BACKGROUND_TASKS`](https://code.claude.com/docs/ko/env-vars)가 `1`

546 * `CLAUDE_CODE_DISABLE_MCP_TASK_BACKGROUND`가 `1`이 아님546 * `CLAUDE_CODE_DISABLE_MCP_TASK_BACKGROUND`가 `1`이 아님

547 * `CLAUDE_CODE_MCP_AUTO_BACKGROUND_MS`가 `0`이 아님547 * `CLAUDE_CODE_MCP_AUTO_BACKGROUND_MS`가 `0`이 아님

548 548 

549그 외의 호출은 일반 도구 호출이며, 그중 어떤 호출이 백그라운드로 전환되는지는 [오래 걸리는 도구 호출의 자동 백그라운드 전환](#automatic-backgrounding-of-long-tool-calls)에 설명되어 있습니다.549그 외의 호출은 일반 도구 호출이며, 그중 어떤 호출이 백그라운드로 이동하는지는 [긴 도구 호출의 자동 백그라운드 전환](#automatic-backgrounding-of-long-tool-calls)에 나와 있습니다.

550 550 

551Agent SDK 또는 stream-json 세션의 입력은 열어 두세요. 입력이 닫히면 실행은 [MCP 작업을 기다리지 않습니다](https://code.claude.com/docs/ko/headless.md#mcp-work-when-a-non-interactive-run-ends). 일회성 `claude -p "<prompt>"` 실행에서는 MCP 작업을 사용할 수 없습니다.551Agent SDK 또는 stream-json 세션의 입력은 열어 두십시오. 입력이 닫힌 후에는 실행이 [MCP 작업을 기다리지 않기](https://code.claude.com/docs/ko/headless.md#mcp-work-when-a-non-interactive-run-ends) 때문입니다. 일회성 `claude -p "<prompt>"` 실행에서는 MCP 작업을 사용할 수 없습니다.

552 552 

553#### MCP 작업의 상태 메시지553#### MCP 작업의 상태 메시지

554 554 

555작업의 `/tasks` 항목이나 종료 시 트랜스크립트 줄에 표시되는 다음 메시지는 Claude Code가 서버나 작업에 연결할 수 없다는 뜻입니다. `/tasks`에 이러한 메시지가 표시되는 동안에도 작업은 여전히 실행 중일 수 있습니다. Claude Code는 작업을 그대로 두고 계속 확인합니다. `300s` 메시지와 구성 관련 메시지는 연결이 복구된 후에도 항목에 남아 있습니다.555작업의 `/tasks` 항목이나 마지막 트랜스크립트 줄에 표시되는 다음 메시지는 Claude Code가 서버나 작업에 도달할 수 없다는 의미입니다. `/tasks`에 메시지가 표시되는 동안에도 작업은 여전히 실행 중일 수 있습니다. Claude Code는 작업을 그대로 두고 계속 확인합니다. `300s` 메시지와 구성 관련 메시지는 연결이 복구된 후에도 항목에 남아 있습니다.

556 556 

557| 메시지 | 일어나고 있는 일 | 할 수 있는 일 |557| 메시지 | 발생 상황 | 할 수 있는 조치 |

558| - | - | - |558| - | - | - |

559| `reconnecting…` | 재개 이후 서버가 응답하지 않았거나, 상태 확인에 응답이 없습니다 | 계속 표시되면 `/mcp`에서 다시 연결합니다 |559| `reconnecting…` | 재개 이후 서버가 응답하지 않았거나, 상태 확인에 응답이 없습니다 | 계속 표시되면 `/mcp`에서 다시 연결하십시오 |

560| `needs a sign-in to <server>` | 서버가 상태 확인을 거부했습니다 | `/mcp`에서 로그인합니다 |560| `needs a sign-in to <server>` | 서버가 상태 확인을 거부했습니다 | `/mcp`에서 로그인하십시오 |

561| `status requests come back with errors; retrying…` | 서버 또는 서버 앞의 프록시가 상태 확인에 오류로 응답합니다 | Claude Code가 재시도하는 동안 기다립니다 |561| `status requests come back with errors; retrying…` | 서버 또는 그 앞의 프록시가 상태 확인에 오류로 응답합니다 | Claude Code가 재시도하는 동안 기다리십시오 |

562| `server '<name>' did not reconnect within 300s` | 연결이 끊기거나 서버가 비활성화되는 등의 이유로 5분 동안 응답받은 확인이 없습니다 | `/mcp`에서 다시 연결합니다 |562| `server '<name>' did not reconnect within 300s` | 예를 들어 연결이 끊겼거나 서버가 비활성화되어 5분 동안 응답된 확인이 없습니다 | `/mcp`에서 다시 연결하십시오 |

563| `server '<name>' asked for a sign-in, and none was accepted within 300s` | 5분이 지나도 서버가 여전히 로그인을 요구합니다 | `/mcp`에서 로그인합니다 |563| `server '<name>' asked for a sign-in, and none was accepted within 300s` | 5분이 지나도 서버가 여전히 로그인을 요구합니다 | `/mcp`에서 로그인하십시오 |

564| `status requests to server '<name>' came back with errors, and none succeeded in 300s` | 5분 동안 오류 응답만 받았습니다 | 서버 자체의 상태나 로그를 확인합니다 |564| `status requests to server '<name>' came back with errors, and none succeeded in 300s` | 5분 동안 오류 응답만 받았습니다 | 서버 자체의 상태나 로그를 확인하십시오 |

565| `server '<name>' is not configured in this session; the task may still be running on it` | 세션에 해당 이름의 서버가 없습니다. 예를 들어 서버가 제거되었거나, 이름이 바뀌었거나, `--mcp-config`에서 빠졌거나, claude.ai 커넥터가 아직 로드 중입니다 | 같은 이름으로 서버를 복원한 다음 세션을 다시 재개합니다. 로드 중인 커넥터라면 아무것도 하지 않아도 됩니다. 커넥터가 나타나면 Claude Code가 작업을 추적합니다 |565| `server '<name>' is not configured in this session; the task may still be running on it` | 예를 들어 서버가 제거되었거나, 이름이 변경되었거나, `--mcp-config`에서 빠졌거나, claude.ai 커넥터가 아직 로드 중이어서 세션에 해당 이름의 서버가 없습니다 | 같은 이름으로 서버를 복원한 다음 세션을 다시 재개하십시오. 로드 중인 커넥터라면 조치할 필요가 없습니다. 커넥터가 나타나면 Claude Code가 작업을 추적합니다 |

566| `server '<name>' was reconfigured to a different transport since this task was created`로 시작하는 메시지 | 해당 이름의 서버가 있지만, 작업이 시작된 이후 URL, command, args, env, headers, timeout 등 연결 설정이 변경되었습니다 | 이전 설정을 복원한 다음 세션을 다시 재개합니다 |566| `server '<name>' was reconfigured to a different transport since this task was created`로 시작하는 메시지 | 해당 이름의 서버가 있지만, 작업 시작 이후 URL, 명령, args, env, headers 또는 timeout 같은 연결 설정이 변경되었습니다 | 이전 설정을 복원한 다음 세션을 다시 재개하십시오 |

567| `the server rejected this task's id; asking again…` | 서버가 작업 ID를 모른다고 응답합니다. Claude Code는 최대 5분 동안 계속 묻습니다 | 기다립니다. 서버가 ID를 다시 인식하면 메시지가 사라지고, 그렇지 않으면 `outcome unknown.` 줄이 이어집니다 |567| `the server rejected this task's id; asking again…` | 서버가 작업 ID를 모른다고 응답합니다. Claude Code는 최대 5분 동안 계속 요청합니다 | 기다리십시오. 서버가 ID를 다시 인식하면 메시지가 사라지고, 그렇지 않으면 `outcome unknown.` 줄이 이어집니다 |

568| `outcome unknown.`으로 끝나는 트랜스크립트 줄(한 형태는 `expired on the server: outcome unknown.`) | 서버가 ID를 거부했거나 다른 영구 오류로 거절했으며, Claude Code가 작업 추적을 중단했습니다 | 다시 호출하면 작업이 반복될 수 있습니다. 도구를 다시 호출하기 전에, 예를 들어 Claude에게 서버의 다른 도구를 사용하도록 요청하여 서버에서 무엇이 수행되었는지 확인하세요 |568| `outcome unknown.`으로 끝나는 트랜스크립트 줄(한 가지 형태는 `expired on the server: outcome unknown.`) | 서버가 ID를 거부했거나 다른 영구 오류로 거부하여 Claude Code가 작업 추적을 중단했습니다 | 두 번째 호출이 작업을 반복할 수 있습니다. 도구를 다시 호출하기 전에, 예를 들어 Claude에게 서버의 다른 도구를 사용하도록 요청하여 무엇이 수행되었는지 서버에서 확인하십시오 |

569 569 

570#### MCP 작업의 시간 제한570#### MCP 작업의 시간 제한

571 571 

572기본적으로 백그라운드의 작업에는 Claude Code 시간 제한이 없습니다. 실제 경과 시간 제한과 유휴 타임아웃을 포함한 [도구 호출 시간 제한](#time-limits-on-mcp-tool-calls)은 서버가 작업으로 호출에 응답할 때까지 적용됩니다. [Claude가 기다리도록](#make-claude-wait-for-the-result-of-an-mcp-task) 하면 작업 전체에 적용됩니다. 응답받은 상태 확인은 유휴 타임아웃에서 활동으로 간주됩니다.572기본적으로 백그라운드의 작업에는 Claude Code 시간 제한이 없습니다. 실제 경과 시간 제한과 유휴 타임아웃을 포함한 [도구 호출 시간 제한](#time-limits-on-mcp-tool-calls)은 서버가 작업으로 호출에 응답할 때까지 적용됩니다. [Claude가 기다리도록 하면](#make-claude-wait-for-the-result-of-an-mcp-task) 작업 전체에 적용됩니다. 응답된 상태 확인은 유휴 타임아웃에서 활동으로 간주됩니다.

573 573 

574#### Claude가 MCP 작업의 결과를 기다리도록 설정574#### Claude가 MCP 작업의 결과를 기다리도록 하기

575 575 

576대화형 세션에서 Claude가 작업의 결과를 기다리도록 하려면, 예를 들어 [`settings.json`](https://code.claude.com/docs/ko/settings)의 `env` 블록에서 다음 두 환경 변수 중 하나를 설정합니다.576대화형 세션에서 Claude가 작업의 결과를 기다리도록 하려면 두 환경 변수 중 하나를 설정하십시오. 예를 들어 [`settings.json`](https://code.claude.com/docs/ko/settings)의 `env` 블록에 설정할 수 있습니다.

577 577 

578* **[`CLAUDE_CODE_MCP_AUTO_BACKGROUND_MS`](https://code.claude.com/docs/ko/env-vars)를 `0`으로 설정**: Claude는 모든 MCP 도구 호출이 끝날 때까지 기다립니다578* **[`CLAUDE_CODE_MCP_AUTO_BACKGROUND_MS`](https://code.claude.com/docs/ko/env-vars)를 `0`으로 설정**: Claude는 모든 MCP 도구 호출이 끝날 때까지 기다립니다

579* **[`CLAUDE_CODE_DISABLE_MCP_TASK_BACKGROUND`](https://code.claude.com/docs/ko/env-vars)를 `1`로 설정**: Claude는 작업의 결과를 기다립니다. [자동 백그라운드 전환](#automatic-backgrounding-of-long-tool-calls)이 켜져 있으면 기본적으로 2분 후에 호출을 전환하므로, 짧은 작업은 그 자리에서 끝나고 긴 작업은 사용자를 차단하지 않습니다. 전환된 호출은 MCP 작업이 아니라 일반 백그라운드 호출이며, 세션을 종료하면 유지되지 않습니다579* **[`CLAUDE_CODE_DISABLE_MCP_TASK_BACKGROUND`](https://code.claude.com/docs/ko/env-vars)를 `1`로 설정**: Claude는 작업의 결과를 기다립니다. [자동 백그라운드 전환](#automatic-backgrounding-of-long-tool-calls)이 켜져 있는 동안에는 기본적으로 2분 후 호출을 이동하므로, 짧은 작업은 그 자리에서 완료되고 긴 작업은 사용자를 차단하지 않습니다. 이동된 호출은 MCP 작업이 아닌 일반 백그라운드 호출이며, 세션을 종료하면 유지되지 않습니다

580 580 

581Claude가 기다리는 동안 `Esc`를 누르거나 [실제 경과 시간 제한 또는 유휴 타임아웃](#time-limits-on-mcp-tasks)에 도달하면 호출이 종료되며, Claude Code는 서버에 작업 취소를 요청합니다.581Claude가 기다리는 동안 `Esc`를 누르거나 [실제 경과 시간 제한 또는 유휴 타임아웃](#time-limits-on-mcp-tasks)에 도달하면 호출이 종료되며, Claude Code는 서버에 작업 취소를 요청합니다.

582 582 

590}590}

591```591```

592 592 

593### 서버 개발자를 위한 MCP 작업593### 서버 작성자를 위한 MCP 작업

594 594 

595MCP 서버를 개발한다면, 오래 실행되는 `tools/call`에 작업으로 응답할 수 있습니다. 보내는 메시지는 [MCP tasks 확장](https://modelcontextprotocol.io/extensions/tasks/overview)에 정의되어 있습니다. [프로토콜 개정판 2026-07-28](#mcp-client-runtimes) 연결에서는 각 요청이 `params._meta["io.modelcontextprotocol/clientCapabilities"]`에 Claude Code의 클라이언트 기능을 담고 있으며, `extensions` 아래에 `"io.modelcontextprotocol/tasks": {}`가 포함됩니다. [작업이 될 수 없는](#requirements-for-mcp-tasks) `tools/call` 요청에는 이 확장이 포함되지 않습니다.595MCP 서버를 만든다면 장시간 실행되는 `tools/call`에 작업으로 응답할 수 있습니다. 보내는 메시지는 [MCP tasks 확장](https://modelcontextprotocol.io/extensions/tasks/overview)에 정의되어 있습니다. [프로토콜 리비전 2026-07-28](#mcp-client-runtimes) 연결에서는 각 요청이 `params._meta["io.modelcontextprotocol/clientCapabilities"]`에 Claude Code의 클라이언트 기능을 포함하며, `extensions` 아래에 `"io.modelcontextprotocol/tasks": {}`가 있습니다. [작업이 될 수 없는](#requirements-for-mcp-tasks) `tools/call` 요청에는 해당 확장이 생략됩니다.

596 596 

597#### 작업으로 호출에 응답597#### 작업으로 호출에 응답하기

598 598 

599요청에 확장이 포함된 경우에만 작업으로 응답하십시오. 그렇지 않으면 호출이 `Unsupported result type 'task' for tools/call` 도구 오류와 함께 실패합니다. 응답에 `taskId`가 없거나 유효한 `status`가 없어도 호출은 같은 방식으로 실패합니다. 작업 객체는 `tools/call` 응답의 JSON-RPC `result`이며, `content` 배열이 필요하지 않고, 여기서는 선택 사항인 `statusMessage`와 `pollIntervalMs`를 포함합니다.599요청에 확장이 포함된 경우에만 작업으로 응답하십시오. 그렇지 않으면 호출은 `Unsupported result type 'task' for tools/call` 도구 오류와 함께 실패합니다. 응답에 `taskId`가 없거나 유효한 `status`가 없는 경우에도 호출이 같은 방식으로 실패합니다. 작업 객체는 `tools/call` 응답의 JSON-RPC `result`이며, `content` 배열이 필요하지 않습니다. 여기서는 선택 사항인 `statusMessage`와 `pollIntervalMs`를 포함합니다.

600 600 

601```json theme={null}601```json theme={null}

602{602{

613 613 

614| 필드 | Claude Code의 처리 방식 |614| 필드 | Claude Code의 처리 방식 |

615| - | - |615| - | - |

616| `resultType` | 응답을 작업으로 표시하려면 `"task"`로 설정합니다. 없으면 Claude Code는 응답을 일반 결과로 읽습니다 |616| `resultType` | 응답을 작업으로 표시하려면 `"task"`로 설정합니다. 이 필드가 없으면 Claude Code는 응답을 일반 결과로 읽습니다 |

617| `taskId` | 필수입니다. 공백 없는 출력 가능한 ASCII 문자 최대 128자여야 하며, 그렇지 않으면 Claude는 `MCP server "<name>" returned a malformed task handle for tool "<tool>"`로 시작하는 도구 오류를 받습니다. 재개 후 Claude Code는 새 연결에서 ID를 조회하므로, 연결이 바뀌어도 ID에 응답할 수 있도록 유지하세요 |617| `taskId` | 필수입니다. 공백 없이 출력 가능한 ASCII 문자 최대 128자여야 하며, 그렇지 않으면 Claude는 `MCP server "<name>" returned a malformed task handle for tool "<tool>"`로 시작하는 도구 오류를 받습니다. 재개 후 Claude Code는 새 연결에서 ID에 대해 묻기 때문에, 여러 연결에서 ID에 응답할 수 있도록 유지하십시오 |

618| `status` | 필수입니다. `working`, `input_required`, `completed`, `failed`, `cancelled` 중 하나입니다. 다른 값은 `Unsupported result type` 오류를 발생시킵니다 |618| `status` | 필수입니다. `working`, `input_required`, `completed`, `failed`, `cancelled` 중 하나입니다. 다른 값은 `Unsupported result type` 오류를 발생시킵니다 |

619| `createdAt`, `lastUpdatedAt`, `ttlMs` | tasks extension에서 필수이며, `ttlMs`는 `null`일 수 있습니다. Claude Code는 `ttlMs`가 지났다는 이유로 작업을 폐기하지 않습니다 |619| `createdAt`, `lastUpdatedAt`, `ttlMs` | tasks 확장에서 필수이며, `ttlMs`는 `null`일 수 있습니다. Claude Code는 `ttlMs`가 지났다는 이유로 작업을 삭제하지 않습니다 |

620| `pollIntervalMs` | 선택 사항입니다. `tasks/get` 요청 간 밀리초 간격이며, 250에서 30000 사이로 제한됩니다. 필드가 없거나 `null`이면 Claude Code는 2000을 사용하며, 각 `tasks/get` 응답에서 값을 다시 읽습니다 |620| `pollIntervalMs` | 선택 사항입니다. `tasks/get` 요청 사이의 밀리초이며, 250에서 30000 사이로 제한됩니다. 필드가 없거나 `null`이면 Claude Code는 2000을 사용하며, 각 `tasks/get` 응답에서 값을 다시 읽습니다 |

621| `statusMessage` | 선택 사항입니다. `/tasks`는 이 첫 응답이 아니라 최신 `tasks/get` 응답의 값을 표시하며, 필드를 생략한 응답은 값을 지웁니다. [Claude Code의 상태 메시지](#status-messages-on-an-mcp-task)가 대신 표시될 수 있습니다 |621| `statusMessage` | 선택 사항입니다. `/tasks`는 이 첫 번째 값이 아니라 최신 `tasks/get` 응답의 값을 표시하며, 필드를 생략한 응답은 값을 지웁니다. [Claude Code의 상태 메시지](#status-messages-on-an-mcp-task)가 대신 표시될 수 있습니다 |

622 622 

623Claude Code는 `createdAt`, `lastUpdatedAt` 또는 `ttlMs`를 생략하거나 `pollIntervalMs`를 `null`로 설정한 작업 응답을 받아들입니다. v2.1.317 이전에는 대신 `Unsupported result type` 오류와 함께 호출이 실패했습니다. 해당 버전에서도 작동하게 하려면 tasks extension이 요구하는 세 필드를 보내고, `pollIntervalMs`는 숫자로 보내거나 아예 보내지 마십시오.623Claude Code는 `createdAt`, `lastUpdatedAt` 또는 `ttlMs`를 생략하거나 `pollIntervalMs`를 `null`로 설정한 작업 응답도 허용합니다. v2.1.317 이전에는 대신 호출이 `Unsupported result type` 오류와 함께 실패했습니다. 이러한 버전에서도 작동하도록 하려면 tasks 확장에서 요구하는 세 필드를 보내고, `pollIntervalMs`는 숫자로 보내거나 아예 보내지 마십시오.

624 624 

625HTTP 또는 claude.ai 커넥터 서버에서는 작업 응답이 [요청별 타이머](#time-limits-on-mcp-tool-calls) 안에 시작되어야 하므로, 작업을 수락하고 먼저 응답한 다음 작업을 수행하세요.625HTTP 또는 claude.ai 커넥터 서버에서는 작업 응답이 [요청별 타이머](#time-limits-on-mcp-tool-calls) 내에 시작되어야 하므로, 먼저 작업을 수락하고 응답한 다음 작업을 수행하십시오.

626 626 

627#### 상태, 결과, 질문 보고627#### 상태, 결과, 질문 보고하기

628 628 

629작업 응답 직후 Claude Code는 `{ "taskId": ... }`와 함께 `tasks/get`을 보내고, 이후 폴링 간격마다 반복합니다. tasks 확장은 응답에 `taskId`, `status`, `createdAt`, `lastUpdatedAt`, `ttlMs`와 함께 `"resultType": "complete"`를 포함하도록 요구합니다. `ttlMs`는 `null`일 수 있으며, `statusMessage`와 `pollIntervalMs`는 선택 사항입니다. 다음 예시는 빌드 완료를 보고합니다.629작업 응답 직후 Claude Code는 `{ "taskId": ... }`와 함께 `tasks/get`을 보내고, 이후 폴링 간격마다 한 번씩 반복합니다. tasks 확장은 응답에 `taskId`, `status`, `createdAt`, `lastUpdatedAt`, `ttlMs`와 함께 `"resultType": "complete"`를 포함하도록 요구합니다. `ttlMs`는 `null`일 수 있으며, `statusMessage`와 `pollIntervalMs`는 선택 사항입니다. 다음 예시는 빌드가 완료되었음을 보고합니다.

630 630 

631```json theme={null}631```json theme={null}

632{632{

645| 상태, 메서드 또는 응답 | Claude Code의 처리 방식 |645| 상태, 메서드 또는 응답 | Claude Code의 처리 방식 |

646| - | - |646| - | - |

647| `working` | 계속 폴링합니다 |647| `working` | 계속 폴링합니다 |

648| `completed` | 최상위 `result` 객체에 담긴 일반 `tools/call` 결과를 Claude에게 전달합니다. 그 안의 `isError: true`는 실패로 보고됩니다 |648| `completed` | 최상위 `result` 객체에 있는 일반 `tools/call` 결과를 Claude에 전달합니다. 그 안의 `isError: true`는 실패로 보고됩니다 |

649| `failed` | 실패한 작업에 대해 tasks 확장이 요구하는 최상위 `error` 객체 `{ code, message, data }`의 `message`를 Claude에게 알립니다. 해당 `message`가 없으면 Claude는 대신 `statusMessage`를 받고, 그것도 없으면 `Task failed`를 받습니다 |649| `failed` | 최상위 `error` 객체 `{ code, message, data }`의 `message`를 Claude에 전달합니다. tasks 확장은 실패한 작업에 이 객체를 요구합니다. 해당 `message`가 없으면 Claude는 대신 `statusMessage`를 받고, 그것도 없으면 `Task failed`를 받습니다 |

650| `cancelled` | `statusMessage`를 Claude에게 알리고, 없으면 `Task was cancelled by the server`를 알립니다 |650| `cancelled` | Claude에 `statusMessage`를 전달하고, 없으면 `Task was cancelled by the server`를 전달합니다 |

651| `input_required` | 임의로 정한 키를 `{ method, params }`에 매핑하는 객체인 `inputRequests`를 읽습니다. Claude Code는 각 키에 대해 `{ taskId, inputResponses }`와 함께 `tasks/update`로 한 번 응답하며, `inputResponses`는 같은 키를 해당 요청의 결과에 매핑합니다. 작업당 16개를 초과하는 키는 무시됩니다 |651| `input_required` | 선택한 키를 `{ method, params }`에 매핑하는 객체인 `inputRequests`를 읽습니다. Claude Code는 각 키에 대해 `{ taskId, inputResponses }`와 함께 `tasks/update`로 한 번씩 응답하며, `inputResponses`는 동일한 키를 해당 요청의 결과에 매핑합니다. 작업당 16개를 초과하는 키는 무시됩니다 |

652| `inputRequests`의 메서드 | `elicitation/create`는 대화형 터미널 세션에서만 처리되며, `roots/list`는 모든 곳에서 처리됩니다. Claude Code가 요청을 처리할 수 없으면 서버에 작업 취소를 요청합니다 |652| `inputRequests`의 메서드 | `elicitation/create`는 대화형 터미널 세션에서만 처리되고, `roots/list`는 모든 곳에서 처리됩니다. Claude Code가 요청을 처리할 수 없으면 서버에 작업 취소를 요청합니다 |

653| 그 외의 `status` 값 | Claude Code가 서버에 작업 취소를 요청하고 Claude에게 실패로 보고합니다 |653| 다른 `status` 값 | Claude Code가 서버에 작업 취소를 요청하고 Claude에 실패로 보고합니다 |

654| JSON-RPC 오류 `-32602` | 알 수 없는 작업 ID로 읽습니다. 백그라운드의 작업이면 Claude Code는 최대 5분 동안 계속 묻다가, 결과를 알 수 없다고 Claude에게 보고합니다 |654| JSON-RPC 오류 `-32602` | 알 수 없는 작업 ID로 읽습니다. 백그라운드의 작업에 대해 Claude Code는 최대 5분 동안 계속 요청한 다음, 결과를 알 수 없다고 Claude에 보고합니다 |

655| `tasks/cancel` | 서버가 연결된 상태에서 Claude나 사용자가 작업을 중지할 때 등에 전송됩니다. 종료 시에는 전송되지 않습니다 |655| `tasks/cancel` | 예를 들어 서버가 연결된 상태에서 Claude나 사용자가 작업을 중지할 때 전송됩니다. 종료 시에는 전송되지 않습니다 |

656| `tasks/result`, `tasks/list`, `notifications/tasks` | 사용되지 않으므로, 결과는 `tasks/get` 응답에 담으세요 |656| `tasks/result`, `tasks/list`, `notifications/tasks` | 사용되지 않으므로, 결과는 `tasks/get` 응답에 담으십시오 |

657 657 

658### 플러그인 제공 MCP 서버658### 플러그인 제공 MCP 서버

659 659 

660[플러그인](https://code.claude.com/docs/ko/plugins/overview.md)은 MCP 서버를 번들로 제공할 수 있으며, 플러그인을 활성화하면 도구 및 통합을 제공합니다.660[플러그인](https://code.claude.com/docs/ko/plugins/overview.md)은 플러그인을 활성화할 때 도구와 통합을 제공하는 MCP 서버를 번들로 포함할 수 있습니다.

661 661 

662**플러그인 MCP 서버의 작동 방식**:662**플러그인 MCP 서버의 작동 방식**:

663 663 

664* 플러그인은 플러그인 루트의 `.mcp.json` 또는 `plugin.json`에 인라인으로 MCP 서버를 정의합니다664* 플러그인은 플러그인 루트의 `.mcp.json` 또는 `plugin.json`에 인라인으로 MCP 서버를 정의합니다

665* 플러그인을 활성화하면 Claude Code는 MCP 서버를 자동으로 시작합니다665* 플러그인을 활성화하면 Claude Code가 해당 MCP 서버를 자동으로 시작합니다

666* Claude Code는 플러그인 MCP 도구를 수동으로 구성된 MCP 도구와 함께 제공합니다666* Claude Code는 수동으로 구성한 MCP 도구와 함께 플러그인 MCP 도구를 제공합니다

667* 플러그인 서버를 추가하고 제거하려면 플러그인을 설치하거나 제거하세요. `/mcp` 명령이 아닙니다. 설치된 플러그인 서버를 `/mcp`에서 [토글하여 끌 수 있습니다](#disable-a-server-without-removing-it). 이는 플러그인을 제거하지 않고 Claude Code가 연결하지 않도록 중지합니다.667* 플러그인 서버는 `/mcp` 명령이 아니라 플러그인을 설치하거나 제거하여 추가하고 제거합니다. 그래도 `/mcp`에서 [설치된 플러그인 서버를 끌](#disable-a-server-without-removing-it) 수 있으며, 이렇게 하면 플러그인을 제거하지 않고도 Claude Code가 해당 서버에 연결하지 않습니다

668 668 

669**플러그인 MCP 구성 예**:669**플러그인 MCP 구성 예시**:

670 670 

671플러그인 루트의 `.mcp.json`:671플러그인 루트의 `.mcp.json`:

672 672 

684}684}

685```685```

686 686 

687또는 `plugin.json`에 인라인:687또는 `plugin.json`에 인라인으로:

688 688 

689```json theme={null}689```json theme={null}

690{690{

700 700 

701**플러그인 MCP 기능**:701**플러그인 MCP 기능**:

702 702 

703* **자동 라이프사이클**: 서버는 다음 지점에서 연결 및 연결 해제됩니다:703* **자동 수명 주기**: 서버는 다음 시점에 연결되고 연결 해제됩니다.

704 * 세션 시작 시 Claude Code는 활성화된 플러그인의 서버를 자동으로 연결합니다. `/mcp`에서 이전에 사용한 원격 (HTTP 또는 SSE) 플러그인 서버는 [`cached` 상태](#server-status-detail)를 대신 표시할 수 있습니다. Claude Code는 Claude가 도구 중 하나를 처음 호출할 때 연결합니다. stdio 플러그인 서버의 연결이 15분 이내에 실패한 경우 Claude Code는 [연결을 건너뜁니다](https://code.claude.com/docs/ko/errors.md#skipping-connection-recent-failure-cached).704 * 세션 시작 시 Claude Code는 활성화된 플러그인의 서버를 자동으로 연결합니다. `/mcp`에서 이전에 사용한 적이 있는 원격(HTTP 또는 SSE) 플러그인 서버는 대신 [`cached` 상태](#server-status-detail)로 표시될 수 있으며, Claude Code는 Claude가 해당 서버의 도구 중 하나를 처음 호출할 때 연결합니다. stdio 플러그인 서버의 연결이 15분 이내에 실패한 경우 Claude Code는 [연결을 건너뜁니다](https://code.claude.com/docs/ko/errors.md#skipping-connection-recent-failure-cached)

705 * 세션 중에 플러그인을 활성화하거나 비활성화하면 Claude Code는 변경이 적용될 때 MCP 서버를 연결하거나 연결 해제합니다. [플러그인 변경 사항을 다시 시작하지 않고 적용](https://code.claude.com/docs/ko/plugins/cli-reference.md#reload-plugins)은 그 시기를 설명합니다. 대화형 터미널이 없는 세션에서 `/reload-plugins`는 플러그인 MCP 서버를 연결하거나 연결 해제하지 않습니다. 이 변경 사항은 다음 세션에서 적용됩니다.705 * 세션 중에 플러그인을 활성화하거나 비활성화하면 Claude Code는 변경 사항이 적용될 때 해당 MCP 서버를 연결하거나 연결 해제합니다. 적용 시점은 [재시작 없이 플러그인 변경 사항 적용](https://code.claude.com/docs/ko/plugins/cli-reference.md#reload-plugins)에서 설명합니다. 대화형 터미널이 없는 세션에서는 `/reload-plugins`가 플러그인 MCP 서버를 연결하거나 연결 해제하지 않으며, 이러한 변경 사항은 다음 세션에서 적용됩니다

706 * 다시 로드할 때 Claude Code는 구성이 변경되지 않은 플러그인 서버의 라이브 연결을 유지하고, 이름을 지정하지 않고 [Agent SDK에서 세션의 MCP 서버 목록을 바꿀 때](https://code.claude.com/docs/ko/agent-sdk/typescript.md#mcpsetserversresult) 동일하게 수행합니다.706 * 다시 로드할 때 Claude Code는 구성이 변경되지 않은 플러그인 서버의 활성 연결을 유지하며, Agent SDK에서 해당 서버의 이름을 지정하지 않고 [세션의 MCP 서버 목록을 교체](https://code.claude.com/docs/ko/agent-sdk/typescript.md#mcpsetserversresult)할 때도 마찬가지입니다

707 * v2.1.246 이상에서 [`/cd`로 세션을 이동](https://code.claude.com/docs/ko/permissions#move-the-session-to-another-directory)할 때 Claude Code는 새 디렉터리의 설정이 활성화하는 플러그인의 서버를 연결하고 더 이상 활성화되지 않는 플러그인의 서버를 연결 해제합니다. 이동 후 `/reload-plugins`를 실행할 필요가 없습니다.707 * v2.1.246 이상에서 [`/cd`로 세션을 이동](https://code.claude.com/docs/ko/permissions#move-the-session-to-another-directory)하면 Claude Code는 새 디렉터리의 설정에서 활성화된 플러그인의 서버를 연결하고 더 이상 활성화되지 않은 플러그인의 서버를 연결 해제하므로, 이동 후 `/reload-plugins`를 실행할 필요가 없습니다

708 * [클라우드 세션](https://code.claude.com/docs/ko/claude-code-on-the-web.md)에서 아직 연결되지 않은 플러그인 서버에 대한 MCP 호출 (예: 유휴 세션이 깨어난 직후)은 서버를 요청 시 시작하고 연결을 기다립니다.708 * [클라우드 세션](https://code.claude.com/docs/ko/claude-code-on-the-web.md)에서는 유휴 세션이 깨어난 직후처럼 아직 연결되지 않은 플러그인 서버에 MCP 호출이 발생하면 필요에 따라 서버를 시작하고 연결될 때까지 기다립니다

709* **경로 자리 표시자**: `${CLAUDE_PLUGIN_ROOT}`는 플러그인의 설치 디렉터리로 확인되고, `${CLAUDE_PLUGIN_DATA}`는 [지속적인 상태](https://code.claude.com/docs/ko/plugins/components.md#path-variables-and-persistent-data) 디렉터리로 확인되며, `${CLAUDE_PROJECT_DIR}`은 안정적인 프로젝트 루트로 확인됩니다. 대체는 다음에 적용됩니다:709* **경로 플레이스홀더**: `${CLAUDE_PLUGIN_ROOT}`는 플러그인의 설치 디렉터리로, `${CLAUDE_PLUGIN_DATA}`는 플러그인의 [영구 상태](https://code.claude.com/docs/ko/plugins/components.md#path-variables-and-persistent-data) 디렉터리로, `${CLAUDE_PROJECT_DIR}`는 안정적인 프로젝트 루트로 변환됩니다. 치환은 다음에 적용됩니다.

710 * `stdio` 서버: `command`, `args`, `env`710 * `stdio` 서버: `command`, `args`, `env`

711 * `http`, `sse` 및 `ws` 서버: `url`, `headers` 및 `headersHelper`711 * `http`, `sse`, `ws` 서버: `url`, `headers`, `headersHelper`

712* **사용자 환경 액세스**: 수동으로 구성된 서버와 동일한 환경 변수에 액세스712* **사용자 환경 접근**: 수동으로 구성한 서버와 동일한 환경 변수에 접근할 수 있습니다

713* **여러 전송 유형**: stdio, SSE, HTTP 및 WebSocket 전송 지원. 전송 지원은 서버에 따라 다를 수 있습니다.713* **다양한 전송 유형**: stdio, SSE, HTTP, WebSocket 전송을 지원하지만, 전송 지원 여부는 서버에 따라 다를 수 있습니다

714 714 

715플러그인 서버는 플러그인에서 온 것을 나타내는 표시기와 함께 `/mcp`에 나타납니다.715플러그인 서버는 `/mcp`에서 플러그인에서 제공된 것임을 나타내는 표시와 함께 나타납니다.

716 716 

717`claude mcp get`은 플러그인의 stdio 또는 WebSocket 서버에 구성된 값을 숨깁니다. 이 값에는 자격 증명이 포함될 수 있기 때문입니다:717`claude mcp get`은 플러그인의 stdio 또는 WebSocket 서버에 구성된 값에 자격 증명이 포함될 수 있으므로 이를 숨깁니다.

718 718 

719* **stdio 서버**: `Command: stdio`, 빈 `Args:` 줄, 그리고 각 환경 변수를 `NAME=[REDACTED]`로 인쇄합니다719* **stdio 서버**: `Command: stdio`, 빈 `Args:` 줄, 그리고 각 환경 변수를 `NAME=[REDACTED]` 형식으로 출력합니다

720* **WebSocket 서버**: `URL: ws`와 각 헤더를 `<name>: [REDACTED]`로 인쇄하며, `claude mcp list`는 URL 대신 `ws`를 표시합니다720* **WebSocket 서버**: `URL: ws`와 각 헤더를 `<name>: [REDACTED]` 형식으로 출력하며, `claude mcp list`는 URL 대신 `ws`를 표시합니다

721 721 

722플러그인이 구성한 내용을 확인하려면 [디스크에서 플러그인을 찾아](https://code.claude.com/docs/ko/plugins/loading.md#find-plugins-on-disk) 해당 `.mcp.json` 또는 `plugin.json`을 읽으세요.722플러그인이 구성한 내용을 확인하려면 [디스크에서 플러그인을 찾아](https://code.claude.com/docs/ko/plugins/loading.md#find-plugins-on-disk) 해당 `.mcp.json` 또는 `plugin.json`을 읽으십시오.

723 723 

724**플러그인 MCP 도구 이름**:724**플러그인 MCP 도구 이름**:

725 725 

726플러그인 번들 MCP 서버의 도구는 호출 가능한 이름에 플러그인 이름과 서버 키를 모두 포함합니다. 전체 형식은 `mcp__plugin_<plugin-name>_<server-name>__<tool-name>`이며, `A-Z`, `a-z`, `0-9`, `_`, `-` 외의 모든 문자는 `_`로 바뀝니다. `my-plugin`이라는 플러그인에 번들된 `database-tools` 서버의 경우, `query` 도구는 다음과 같이 호출할 수 있습니다:726플러그인에 번들로 포함된 MCP 서버의 도구는 호출 가능한 이름에 플러그인 이름과 서버 키를 모두 포함합니다. 전체 형식은 `mcp__plugin_<plugin-name>_<server-name>__<tool-name>`이며, `A-Z`, `a-z`, `0-9`, `_`, `-` 이외의 문자는 `_`로 대체됩니다. `my-plugin`이라는 플러그인에 번들로 포함된 `database-tools` 서버의 경우, `query` 도구는 다음과 같이 호출할 수 있습니다.

727 727 

728```728```

729mcp__plugin_my-plugin_database-tools__query729mcp__plugin_my-plugin_database-tools__query

730```730```

731 731 

732[권한 규칙](https://code.claude.com/docs/ko/permissions.md)에서 도구를 참조할 때, 스킬의 `allowed-tools` 목록에서, [서브에이전트의 `tools` 필드](https://code.claude.com/docs/ko/sub-agents#available-tools)에서, 또는 [훅 matcher](https://code.claude.com/docs/ko/hooks.md#match-mcp-tools)에서 이 전체 이름을 사용하세요. `mcp__database-tools__.*`와 같은 베어 서버 키에 대해 작성된 훅 matcher는 플러그인 번들 서버에 대해 절대 실행되지 않습니다.732[권한 규칙](https://code.claude.com/docs/ko/permissions.md), 스킬의 `allowed-tools` 목록, [서브에이전트의 `tools` 필드](https://code.claude.com/docs/ko/sub-agents#available-tools) 또는 [훅 matcher](https://code.claude.com/docs/ko/hooks.md#match-mcp-tools)에서 도구를 참조할 때는 이 전체 이름을 사용하십시오. `mcp__database-tools__.*`처럼 서버 키만으로 작성한 훅 matcher는 플러그인에 번들로 포함된 서버에 대해 절대 실행되지 않습니다.

733 733 

734서버 자체는 `plugin:<plugin-name>:<server-name>` (예: `plugin:my-plugin:database-tools`)과 같은 범위 지정 이름으로 등록됩니다. 구성된 서버 이름이 예상되는 위치 (예: [`mcp_tool` 훅의 `server` 필드](https://code.claude.com/docs/ko/hooks#mcp-tool-hook-fields))에서 해당 이름을 사용하세요.734서버 자체는 `plugin:my-plugin:database-tools`처럼 `plugin:<plugin-name>:<server-name>` 형식의 범위 지정 이름으로 등록됩니다. [`mcp_tool` 훅의 `server` 필드](https://code.claude.com/docs/ko/hooks#mcp-tool-hook-fields)처럼 구성된 서버 이름이 필요한 곳에서는 이 이름을 사용하십시오.

735 735 

736플러그인과 함께 MCP 서버를 번들로 제공하는 방법에 대한 자세한 내용은 [플러그인 구성 요소 참조](https://code.claude.com/docs/ko/plugins/components.md#mcp-servers)를 참조하세요.736플러그인에 MCP 서버를 번들로 포함하는 방법에 대한 자세한 내용은 [플러그인 컴포넌트 레퍼런스](https://code.claude.com/docs/ko/plugins/components.md#mcp-servers)를 참조하십시오.

737 737 

738## MCP 설치 범위738## MCP 설치 범위

739 739 

1800* **Claude Opus 4.5, Sonnet 4.5, Haiku 4.5 및 이후 모델**: 도구 검색은 기본적으로 활성화되며, Anthropic API와 동일합니다.1800* **Claude Opus 4.5, Sonnet 4.5, Haiku 4.5 및 이후 모델**: 도구 검색은 기본적으로 활성화되며, Anthropic API와 동일합니다.

1801* **이전 Agent Platform 모델**: Claude Code는 필요한 베타 헤더를 거부하는 서빙 스택 때문에 모든 MCP 도구를 미리 로드합니다. `ENABLE_TOOL_SEARCH=true`는 이를 재정의하지 않습니다.1801* **이전 Agent Platform 모델**: Claude Code는 필요한 베타 헤더를 거부하는 서빙 스택 때문에 모든 MCP 도구를 미리 로드합니다. `ENABLE_TOOL_SEARCH=true`는 이를 재정의하지 않습니다.

1802 1802 

1803v2.1.221 이전에는 Claude Code가 `ENABLE_TOOL_SEARCH=true`를 설정하지 않는 한 Google Cloud의 Agent Platform의 모든 모델에 대해 도구 검색을 비활성화했습니다.

1804 

1805`ENABLE_TOOL_SEARCH` 환경 변수로 도구 검색 동작을 제어하세요:1803`ENABLE_TOOL_SEARCH` 환경 변수로 도구 검색 동작을 제어하세요:

1806 1804 

1807| 값 | 동작 |1805| 값 | 동작 |

model-config.md +4 −4

Details

71* **Fable 5.2**: `/model fable`을 실행하거나 `claude --model fable`로 시작합니다. [Claude 앱 게이트웨이](https://code.claude.com/docs/ko/claude-apps-gateway) 세션에서는 대신 `/model claude-fable-5-2`를 실행합니다.71* **Fable 5.2**: `/model fable`을 실행하거나 `claude --model fable`로 시작합니다. [Claude 앱 게이트웨이](https://code.claude.com/docs/ko/claude-apps-gateway) 세션에서는 대신 `/model claude-fable-5-2`를 실행합니다.

72* **Fable 5.1 또는 Fable 5**: 모델 ID로 선택합니다. Anthropic API에서 `/model claude-fable-5-1` 또는 `/model claude-fable-5`를 실행하거나 `claude --model claude-fable-5-1`로 시작합니다. 다른 공급자에서는 공급자의 모델 ID를 사용하거나 `ANTHROPIC_DEFAULT_FABLE_MODEL`로 [고정합니다](#pin-models-for-third-party-deployments).72* **Fable 5.1 또는 Fable 5**: 모델 ID로 선택합니다. Anthropic API에서 `/model claude-fable-5-1` 또는 `/model claude-fable-5`를 실행하거나 `claude --model claude-fable-5-1`로 시작합니다. 다른 공급자에서는 공급자의 모델 ID를 사용하거나 `ANTHROPIC_DEFAULT_FABLE_MODEL`로 [고정합니다](#pin-models-for-third-party-deployments).

73 73 

74Pro, Max, Team, Enterprise 플랜에서는 사용자 설정에 저장된 `claude-fable-5-1` 모델이 `fable` 별칭으로 이동합니다:74Pro, Max, Ultra, Team, Enterprise 플랜에서는 사용자 설정에 저장된 `claude-fable-5-1` 모델이 `fable` 별칭으로 이동합니다:

75 75 

76* **Pro 또는 Max 플랜**: 이동은 v2.1.321 이상을 처음 실행할 때 이루어집니다. 터미널에서는 시작 모델 라인에 `(auto-updated)`가 한 번 표시될 수 있습니다.76* **Pro, Max 또는 Ultra 플랜**: 이동은 v2.1.321 이상을 처음 실행할 때 이루어집니다. 터미널에서는 시작 모델 라인에 `(auto-updated)`가 한 번 표시될 수 있습니다.

77* **Team 또는 Enterprise 플랜**: 이동은 조직의 설정을 기다리므로 이후의 시작 시에 이루어지거나 전혀 이루어지지 않을 수 있습니다. 다음 세션부터 적용되며 `(auto-updated)` 라인은 표시되지 않습니다. 모델을 확인하려면 `/model`을 실행합니다.77* **Team 또는 Enterprise 플랜**: 이동은 조직의 설정을 기다리므로 이후의 시작 시에 이루어지거나 전혀 이루어지지 않을 수 있습니다. 다음 세션부터 적용되며 `(auto-updated)` 라인은 표시되지 않습니다. 모델을 확인하려면 `/model`을 실행합니다.

78 78 

79이동 후에는 Fable 5.2에 대해 [수준을 설정](#adjust-effort-level)하지 않은 한 세션이 Fable 5.2의 기본 effort로 시작합니다. Console 계정, 타사 공급자, 그리고 프로젝트, 로컬 또는 관리형 설정은 `claude-fable-5-1`을 유지합니다.79이동 후에는 Fable 5.2에 대해 [수준을 설정](#adjust-effort-level)하지 않은 한 세션이 Fable 5.2의 기본 effort로 시작합니다. Console 계정, 타사 공급자, 그리고 프로젝트, 로컬 또는 관리형 설정은 `claude-fable-5-1`을 유지합니다.

97 97 

98플랜 및 시트 계층에 따라 Fable 사용은 플랜에 포함된 한도를 사용하는 대신 [사용량 크레딧](https://support.claude.com/en/articles/12429409-extra-usage-for-paid-claude-plans)으로 청구될 수 있습니다. 그렇게 되면 `/model` 선택기는 Fable 행에 "사용량 크레딧 필요"를 표시합니다. 사용량 크레딧을 관리하려면 [구독에 사용량 크레딧 추가](https://code.claude.com/docs/ko/costs.md#add-usage-credits-to-your-subscription)를 참조하십시오.98플랜 및 시트 계층에 따라 Fable 사용은 플랜에 포함된 한도를 사용하는 대신 [사용량 크레딧](https://support.claude.com/en/articles/12429409-extra-usage-for-paid-claude-plans)으로 청구될 수 있습니다. 그렇게 되면 `/model` 선택기는 Fable 행에 "사용량 크레딧 필요"를 표시합니다. 사용량 크레딧을 관리하려면 [구독에 사용량 크레딧 추가](https://code.claude.com/docs/ko/costs.md#add-usage-credits-to-your-subscription)를 참조하십시오.

99 99 

100대화형 세션에서 Claude Code는 Fable 사용량 크레딧 동의 프롬프트를 표시할 수 있습니다. 조직 청구가 있는 Enterprise 플랜의 구성원은 프롬프트를 보지 않습니다. 사용량 크레딧을 사용하여 Fable을 계속하거나 기본 모델로 전환할 수 있습니다. 프롬프트를 해제할 수도 있습니다:100대화형 세션에서 Claude Code는 Fable 사용량 크레딧 동의 프롬프트를 표시할 수 있습니다. 사용량 크레딧을 사용하여 Fable을 계속하거나 기본 모델로 전환할 수 있습니다. 프롬프트를 해제할 수도 있습니다:

101 101 

102* `/model`로 Fable 모델을 선택하면 현재 모델을 유지합니다.102* `/model`로 Fable 모델을 선택하면 현재 모델을 유지합니다.

103* 세션 중간에 Claude Code는 기본 모델에서 턴을 계속합니다.103* 세션 중간에 Claude Code는 기본 모델에서 턴을 계속합니다.

245* **메인 세션 모델**: `/model`, `--model` 플래그, `ANTHROPIC_MODEL` 환경 변수, `model` 설정, [`ANTHROPIC_DEFAULT_MODEL`](#set-a-default-model-for-new-sessions), 그리고 [세션을 재개할 때](#setting-your-model) 복원되는 모델245* **메인 세션 모델**: `/model`, `--model` 플래그, `ANTHROPIC_MODEL` 환경 변수, `model` 설정, [`ANTHROPIC_DEFAULT_MODEL`](#set-a-default-model-for-new-sessions), 그리고 [세션을 재개할 때](#setting-your-model) 복원되는 모델

246* **별칭 해석**: `ANTHROPIC_DEFAULT_OPUS_MODEL`, `ANTHROPIC_DEFAULT_SONNET_MODEL`, `ANTHROPIC_DEFAULT_HAIKU_MODEL`, 그리고 `ANTHROPIC_DEFAULT_FABLE_MODEL` 환경 변수는 허용된 별칭을 목록 외부의 모델로 리디렉션할 수 없습니다246* **별칭 해석**: `ANTHROPIC_DEFAULT_OPUS_MODEL`, `ANTHROPIC_DEFAULT_SONNET_MODEL`, `ANTHROPIC_DEFAULT_HAIKU_MODEL`, 그리고 `ANTHROPIC_DEFAULT_FABLE_MODEL` 환경 변수는 허용된 별칭을 목록 외부의 모델로 리디렉션할 수 없습니다

247* **빠른 모드**: `/fast`는 목록 외부의 Opus 모델로 암묵적으로 전환될 때 토글을 거부하며, "is not in your organization's allowed models" 메시지를 표시합니다247* **빠른 모드**: `/fast`는 목록 외부의 Opus 모델로 암묵적으로 전환될 때 토글을 거부하며, "is not in your organization's allowed models" 메시지를 표시합니다

248* **서브에이전트 및 팀원 모델**: [서브에이전트](https://code.claude.com/docs/ko/sub-agents.md#choose-a-model) 프론트매터의 `model` 필드, Agent 도구의 `model` 매개변수, [에이전트 팀](https://code.claude.com/docs/ko/agent-teams.md#specify-teammates-and-models) 팀원 모델, `CLAUDE_CODE_SUBAGENT_MODEL`, 그리고 v2.1.197 이전에는 `/agents` 마법사의 모델 선택기&#x20;248* **서브에이전트 및 팀원 모델**: [서브에이전트](https://code.claude.com/docs/ko/sub-agents.md#choose-a-model) 프론트매터의 `model` 필드, Agent 도구의 `model` 매개변수, [에이전트 팀](https://code.claude.com/docs/ko/agent-teams.md#specify-teammates-and-models) 팀원 모델, `CLAUDE_CODE_SUBAGENT_MODEL`, 그리고 v2.1.197 이하에서는 `/agents` 마법사의 모델 선택기&#x20;

249* **스킬 및 명령 모델**: [스킬 및 명령](https://code.claude.com/docs/ko/skills.md)의 `model` 프론트매터249* **스킬 및 명령 모델**: [스킬 및 명령](https://code.claude.com/docs/ko/skills.md)의 `model` 프론트매터

250* **어드바이저 모델**: 구성된 [`advisorModel`](https://code.claude.com/docs/ko/advisor) 설정 및 `--advisor` 플래그250* **어드바이저 모델**: 구성된 [`advisorModel`](https://code.claude.com/docs/ko/advisor) 설정 및 `--advisor` 플래그

251* **백그라운드 에이전트 모델**: [디스패치 선택기](https://code.claude.com/docs/ko/agent-view.md)에서 선택된 모델251* **백그라운드 에이전트 모델**: [디스패치 선택기](https://code.claude.com/docs/ko/agent-view.md)에서 선택된 모델

Details

146 146 

147### 메트릭 카디널리티 제어147### 메트릭 카디널리티 제어

148 148 

149다음 환경 변수는 카디널리티를 관리하기 위해 메트릭에 포함되는 속성을 제어합니다.149다음 환경 변수는 카디널리티를 관리하기 위해 메트릭과 이벤트에 포함되는 속성을 제어합니다.

150 150 

151| 환경 변수 | 설명 | 기본값 | 비활성화 예시 |151| 환경 변수 | 설명 | 기본값 | 비활성화 예시 |

152| - | - | - | - |152| - | - | - | - |

153| `OTEL_METRICS_INCLUDE_SESSION_ID` | 메트릭에 session.id 속성과, 클라우드 세션의 경우 ccr.session.id 속성을 포함합니다 | `true` | `false` |153| `OTEL_METRICS_INCLUDE_SESSION_ID` | 메트릭과 이벤트에 session.id 속성과, 클라우드 세션의 경우 ccr.session.id 속성을 포함합니다 | `true` | `false` |

154| `OTEL_METRICS_INCLUDE_VERSION` | 메트릭에 app.version 속성을 포함합니다 | `false` | `true` |154| `OTEL_METRICS_INCLUDE_VERSION` | 메트릭과 이벤트에 app.version 속성을 포함합니다 | `false` | `true` |

155| `OTEL_METRICS_INCLUDE_ACCOUNT_UUID` | 메트릭에 user.account\_uuid 및 user.account\_id 속성을 포함합니다 | `true` | `false` |155| `OTEL_METRICS_INCLUDE_ACCOUNT_UUID` | 메트릭과 이벤트에 user.account\_uuid 및 user.account\_id 속성을 포함합니다 | `true` | `false` |

156| `OTEL_METRICS_INCLUDE_ENTRYPOINT` | 메트릭에 app.entrypoint 속성을 포함합니다 | `false` | `true` |156| `OTEL_METRICS_INCLUDE_ENTRYPOINT` | 메트릭과 이벤트에 app.entrypoint 속성을 포함합니다 | `false` | `true` |

157| `OTEL_METRICS_INCLUDE_RESOURCE_ATTRIBUTES` | `OTEL_RESOURCE_ATTRIBUTES`의 키를 메트릭 데이터 포인트의 속성으로 포함합니다 | `true` | `false` |157| `OTEL_METRICS_INCLUDE_RESOURCE_ATTRIBUTES` | `OTEL_RESOURCE_ATTRIBUTES`의 키를 메트릭 데이터 포인트와 이벤트의 속성으로 포함합니다 | `true` | `false` |

158| `OTEL_METRICS_INCLUDE_REPOSITORY` | 메트릭과 이벤트에 `vcs.*` [저장소 식별 속성](#repository-attributes)을 포함합니다. Claude Code v2.1.269 이상이 필요합니다 | `false` | `true` |158| `OTEL_METRICS_INCLUDE_REPOSITORY` | 메트릭과 이벤트에 `vcs.*` [저장소 식별 속성](#repository-attributes)을 포함합니다. Claude Code v2.1.269 이상이 필요합니다 | `false` | `true` |

159 159 

160일반적으로 카디널리티가 낮을수록 성능이 향상되고 스토리지 비용이 줄어들지만, 분석용 데이터의 세분성은 떨어집니다.160일반적으로 카디널리티가 낮을수록 성능이 향상되고 스토리지 비용이 줄어들지만, 분석용 데이터의 세분성은 떨어집니다.

523export OTEL_METRICS_EXPORTER=otlp523export OTEL_METRICS_EXPORTER=otlp

524export OTEL_LOGS_EXPORTER=otlp524export OTEL_LOGS_EXPORTER=otlp

525export OTEL_EXPORTER_OTLP_METRICS_PROTOCOL=http/protobuf525export OTEL_EXPORTER_OTLP_METRICS_PROTOCOL=http/protobuf

526export OTEL_EXPORTER_OTLP_METRICS_ENDPOINT=http://metrics.example.com:4318526export OTEL_EXPORTER_OTLP_METRICS_ENDPOINT=http://metrics.example.com:4318/v1/metrics

527export OTEL_EXPORTER_OTLP_LOGS_PROTOCOL=grpc527export OTEL_EXPORTER_OTLP_LOGS_PROTOCOL=grpc

528export OTEL_EXPORTER_OTLP_LOGS_ENDPOINT=http://logs.example.com:4317528export OTEL_EXPORTER_OTLP_LOGS_ENDPOINT=http://logs.example.com:4317

529```529```

571 571 

572더 자세하게 텔레메트리를 속성 지정하려면 다음 옵션을 사용합니다:572더 자세하게 텔레메트리를 속성 지정하려면 다음 옵션을 사용합니다:

573 573 

574* **Claude Tag 세션 식별**: [메트릭 카디널리티 제어](#metrics-cardinality-control)에서 설명한 대로 `OTEL_METRICS_INCLUDE_ENTRYPOINT=true`를 설정합니다. 그러면 메트릭은 `app.entrypoint`를 전달하며, 그 값은 Claude Tag 세션의 경우 `claude-in-slack`입니다.574* **Claude Tag 세션 식별**: [메트릭 카디널리티 제어](#metrics-cardinality-control)에서 설명한 대로 `OTEL_METRICS_INCLUDE_ENTRYPOINT=true`를 설정합니다. 그러면 메트릭 및 이벤트는 `app.entrypoint`를 전달하며, 그 값은 Claude Tag 세션의 경우 `claude-in-slack`입니다.

575* **사용자 정의 속성 추가**: 해당 세션에 대한 다른 `OTEL_*` 변수를 설정하는 동일한 위치에 [`OTEL_RESOURCE_ATTRIBUTES`](#multi-team-organization-support)를 설정합니다. 환경의 [설정 스크립트](https://code.claude.com/docs/ko/cloud-environments.md#setup-scripts)에서 `export`하면, 값이 Claude Code에 도달하지 않습니다. 설정 스크립트는 Claude Code가 시작되기 전에 실행되는 별도의 Bash 스크립트이며, 이것이 내보내는 변수는 여기서 끝납니다.575* **사용자 정의 속성 추가**: 해당 세션에 대한 다른 `OTEL_*` 변수를 설정하는 동일한 위치에 [`OTEL_RESOURCE_ATTRIBUTES`](#multi-team-organization-support)를 설정합니다. 환경의 [설정 스크립트](https://code.claude.com/docs/ko/cloud-environments.md#setup-scripts)에서 `export`하면, 값이 Claude Code에 도달하지 않습니다. 설정 스크립트는 Claude Code가 시작되기 전에 실행되는 별도의 Bash 스크립트이며, 이것이 내보내는 변수는 여기서 끝납니다.

576 576 

577Claude Tag 채널 세션에서 Claude는 조직의 [공유 ID](https://code.claude.com/docs/ko/cloud-environments.md#set-the-environment-a-claude-tag-channel-uses)로 작동하며 어떤 멤버로도 작동하지 않으므로, `user.*` 속성에 의존하여 Claude를 태그한 사람을 식별하지 마십시오.577Claude Tag 채널 세션에서 Claude는 조직의 [공유 ID](https://code.claude.com/docs/ko/cloud-environments.md#set-the-environment-a-claude-tag-channel-uses)로 작동하며 어떤 멤버로도 작동하지 않으므로, `user.*` 속성에 의존하여 Claude를 태그한 사람을 식별하지 마십시오.

587| `session.id` | Claude Code 자체의 세션 ID로, `/clear`를 실행하면 새 값으로 바뀝니다 | `OTEL_METRICS_INCLUDE_SESSION_ID` (기본값: true) |587| `session.id` | Claude Code 자체의 세션 ID로, `/clear`를 실행하면 새 값으로 바뀝니다 | `OTEL_METRICS_INCLUDE_SESSION_ID` (기본값: true) |

588| `ccr.session.id` | 클라우드 세션 식별자로, [클라우드 환경](https://code.claude.com/docs/ko/cloud-environments.md)에서 실행되는 세션의 `CLAUDE_CODE_REMOTE_SESSION_ID` 값입니다 | `OTEL_METRICS_INCLUDE_SESSION_ID` (기본값: true) |588| `ccr.session.id` | 클라우드 세션 식별자로, [클라우드 환경](https://code.claude.com/docs/ko/cloud-environments.md)에서 실행되는 세션의 `CLAUDE_CODE_REMOTE_SESSION_ID` 값입니다 | `OTEL_METRICS_INCLUDE_SESSION_ID` (기본값: true) |

589| `app.version` | 현재 Claude Code 버전 | `OTEL_METRICS_INCLUDE_VERSION` (기본값: false) |589| `app.version` | 현재 Claude Code 버전 | `OTEL_METRICS_INCLUDE_VERSION` (기본값: false) |

590| `app.entrypoint` | 세션이 시작된 방식으로, `cli`, `sdk-cli`, `sdk-ts`, `sdk-py`, `claude-vscode`, 또는 Claude Tag 세션의 경우 `claude-in-slack` 등이 있습니다 | `OTEL_METRICS_INCLUDE_ENTRYPOINT` (기본값: false) |590| `app.entrypoint` | 세션이 시작된 방식입니다. 예를 들어 `cli`, `sdk-cli`, `sdk-ts`, `sdk-py`, `claude-vscode`, 클라우드 외부의 Claude Desktop Code 탭 세션을 나타내는 `claude-desktop`, [서드파티 배포](https://claude.com/docs/third-party/claude-desktop/overview)에서 같은 세션을 나타내는 `claude-desktop-3p`, Claude Tag 세션을 나타내는 `claude-in-slack` 등이 있습니다. 클라우드 세션 값으로는 `remote`가 있으며, Claude Desktop 또는 모바일 앱에서 시작한 세션에는 `remote_desktop`과 `remote_mobile`이 있습니다 | `OTEL_METRICS_INCLUDE_ENTRYPOINT` (기본값: false) |

591| `organization.id` | 조직 UUID(인증된 경우) | 사용 가능한 경우 항상 포함 |591| `organization.id` | 조직 UUID(인증된 경우) | 사용 가능한 경우 항상 포함 |

592| `user.account_uuid` | 계정 UUID(인증된 경우) | `OTEL_METRICS_INCLUDE_ACCOUNT_UUID` (기본값: true) |592| `user.account_uuid` | 계정 UUID(인증된 경우) | `OTEL_METRICS_INCLUDE_ACCOUNT_UUID` (기본값: true) |

593| `user.account_id` | Anthropic 관리자 API와 일치하는 태그 형식의 계정 ID(인증된 경우)로, 예를 들면 `user_01BWBeN28...`입니다 | `OTEL_METRICS_INCLUDE_ACCOUNT_UUID` (기본값: true) |593| `user.account_id` | Anthropic 관리자 API와 일치하는 태그 형식의 계정 ID(인증된 경우)로, 예를 들면 `user_01BWBeN28...`입니다 | `OTEL_METRICS_INCLUDE_ACCOUNT_UUID` (기본값: true) |

643 643 

644| 메트릭 이름 | 설명 | 단위 |644| 메트릭 이름 | 설명 | 단위 |

645| - | - | - |645| - | - | - |

646| `claude_code.session.count` | 시작된 CLI 세션 수 | 없음 |646| `claude_code.session.count` | 시작된 세션 수 | 없음 |

647| `claude_code.lines_of_code.count` | 수정된 코드 줄 수 | 없음 |647| `claude_code.lines_of_code.count` | 수정된 코드 줄 수 | 없음 |

648| `claude_code.pull_request.count` | 생성된 풀 리퀘스트 수 | 없음 |648| `claude_code.pull_request.count` | 생성된 풀 리퀘스트 수 | 없음 |

649| `claude_code.commit.count` | 생성된 git 커밋 수 | 없음 |649| `claude_code.commit.count` | 생성된 git 커밋 수 | 없음 |

660 660 

661#### 세션 카운터661#### 세션 카운터

662 662 

663각 세션이 시작될 때 증가합니다.663각 세션이 시작될 때 증가합니다. 대신 사람 수를 세려면 [사용량 모니터링](#usage-monitoring)을 참조하세요.

664 664 

665**속성**:665**속성**:

666 666 

1458 1458 

1459이 페이지의 다른 모든 OTel 이벤트와 마찬가지로, 이 이벤트는 사용자가 구성한 텔레메트리 백엔드로만 전송됩니다. Claude Code v2.1.227 이상이 필요합니다.1459이 페이지의 다른 모든 OTel 이벤트와 마찬가지로, 이 이벤트는 사용자가 구성한 텔레메트리 백엔드로만 전송됩니다. Claude Code v2.1.227 이상이 필요합니다.

1460 1460 

1461Claude Code가 보존 기간을 안전하게 결정할 수 없는 경우 정리 작업을 일시 중지하고 `result`를 `"skipped"`로 설정하고 `skip_reason`을 포함한 이벤트를 내보냅니다. [관리형 설정](https://code.claude.com/docs/ko/server-managed-settings.md)이 `cleanupPeriodDays`를 설정하면 관리형 값이 보존 기간을 고정하며, 우선순위가 낮은 범위의 설정 파일이 손상되었거나 유효하지 않더라도 정리 작업이 실행됩니다. `managed-settings.json` 자체를 읽을 수 없는 경우, [관리형 계층](https://code.claude.com/docs/ko/managed-settings.md#how-claude-code-combines-managed-sources)이 서버 관리형 설정이나 손상된 파일 옆의 `managed-settings.d/` 드롭인 등 다른 곳에서 `cleanupPeriodDays`를 제공하지 않는 한 Claude Code는 여전히 정리 작업을 일시 중지합니다. 삭제 카운터 속성은 `result`가 `"complete"`인 경우에만 존재합니다.1461정리 작업이 실행되었는지 확인하려면 `result`를 읽습니다.

1462 

1463* `"complete"`: 정리 작업이 실행되었으며, 이벤트에 해당 카운트가 포함됩니다

1464* `"skipped"`: Claude Code가 보존 기간을 안전하게 결정할 수 없어 정리 작업을 일시 중지했으며, 이벤트에 카운트가 포함되지 않습니다. `skip_reason`이 `"settings_unknowable"` 또는 `"settings_invalid_key_set"`인 경우, 이후 세션에서 정리 작업을 실행할 수 있도록 해당 머신에서 `/status`가 보고하는 설정 오류를 수정합니다

1465 

1466[관리형 설정](https://code.claude.com/docs/ko/server-managed-settings.md)이 `cleanupPeriodDays`를 설정하면 관리형 값이 보존 기간을 고정하며, 더 낮은 우선순위 범위의 설정 파일이 손상되었거나 유효하지 않더라도 정리 작업이 실행됩니다.

1462 1467 

1463**이벤트 이름**: `claude_code.retention_sweep`1468**이벤트 이름**: `claude_code.retention_sweep`

1464 1469 

1469* `event.timestamp`: ISO 8601 타임스탬프1474* `event.timestamp`: ISO 8601 타임스탬프

1470* `event.sequence`: 이벤트 순서를 지정하기 위한 프로세스별 카운터로, [이벤트 상관관계 속성](#event-correlation-attributes)에서 설명합니다1475* `event.sequence`: 이벤트 순서를 지정하기 위한 프로세스별 카운터로, [이벤트 상관관계 속성](#event-correlation-attributes)에서 설명합니다

1471* `result`: 정리 작업이 실행된 경우 `"complete"`, Claude Code가 일시 중지한 경우 `"skipped"`1476* `result`: 정리 작업이 실행된 경우 `"complete"`, Claude Code가 일시 중지한 경우 `"skipped"`

1472* `period_days`: 병합된 설정의 `cleanupPeriodDays` 값(일 단위), 또는 이를 설정하는 소스가 없으면 `30`. 건너뛴 이벤트에서는 Claude Code가 읽을 수 있었던 설정 소스로 계산한, 정리 작업이 사용했을 값입니다1477* `period_days`: 정리 작업이 시작될 때의 보존 기간(일 단위)입니다. 병합된 설정의 `cleanupPeriodDays`에 [`settings.read` 훅](https://code.claude.com/docs/ko/plugins/mods/events#settings-read-hook)에 의한 변경 사항을 적용한 값입니다. 그 결과 키가 설정되지 않은 경우 `30`입니다. skipped 이벤트에서는 Claude Code가 읽을 수 있었던 설정 소스로부터 계산한, 정리 작업이 사용했을 값입니다

1473* `used_default`: 읽을 수 있는 설정 소스 중 `cleanupPeriodDays`를 설정한 소스가 없으면 `"true"`, 그렇지 않으면 `"false"`. 완료 이벤트에서 `"true"`는 30일 기본값이 적용되었음을 의미합니다1478* `used_default`: `period_days`가 `30`으로 폴백된 경우 `"true"`, 그렇지 않으면 `"false"`. complete 이벤트에서 `"true"`는 30일 기본값이 적용되었음을 의미합니다

1474* `skip_reason`: Claude Code가 스윕을 일시 중지한 이유. `result`가 `"skipped"`인 경우에만 존재합니다:1479* `skip_reason`: Claude Code가 스윕을 일시 중지한 이유. `result`가 `"skipped"`인 경우에만 존재합니다:

1475 * `"user_source_disabled"`: [`--setting-sources`](https://code.claude.com/docs/ko/cli-reference#cli-flags) 플래그나 SDK의 [`settingSources`](https://code.claude.com/docs/ko/agent-sdk/typescript#options) 옵션 등으로 사용자 설정이 제외되었고, 활성화된 소스 중 `cleanupPeriodDays`를 제공하는 것이 없습니다1480 * `"user_source_disabled"`: [`--setting-sources`](https://code.claude.com/docs/ko/cli-reference#cli-flags) 플래그나 SDK의 [`settingSources`](https://code.claude.com/docs/ko/agent-sdk/typescript#options) 옵션 등으로 사용자 설정이 제외되었고, 활성화된 소스 중 `cleanupPeriodDays`를 제공하는 것이 없습니다

1476 * `"settings_unknowable"`: 설정 파일을 읽거나 파싱할 수 없어 `cleanupPeriodDays` 또는 `desktopSessionCleanupPeriodDays`가 Claude Code가 볼 수 없는 값으로 설정되어 있을 수 있습니다1481 * `"settings_unknowable"`: 설정 파일을 읽거나 파싱할 수 없어 `cleanupPeriodDays` 또는 `desktopSessionCleanupPeriodDays`가 Claude Code가 볼 수 없는 값으로 설정되어 있을 수 있습니다

1549| 메트릭 | 분석 기회 |1554| 메트릭 | 분석 기회 |

1550| - | - |1555| - | - |

1551| `claude_code.token.usage` | 토큰 [`type`](#token-counter), 사용자, 팀, 모델, `skill.name`, `plugin.name` 또는 `agent.name`별로 분류 |1556| `claude_code.token.usage` | 토큰 [`type`](#token-counter), 사용자, 팀, 모델, `skill.name`, `plugin.name` 또는 `agent.name`별로 분류 |

1552| `claude_code.session.count` | 시간 경과에 따른 채택 및 참여 추적 |

1553| `claude_code.lines_of_code.count` | 코드 추가 및 제거를 추적하여 생산성 측정, 모델별로 분류 |1557| `claude_code.lines_of_code.count` | 코드 추가 및 제거를 추적하여 생산성 측정, 모델별로 분류 |

1554| `claude_code.commit.count` & `claude_code.pull_request.count` | 개발 워크플로우에 미치는 영향 이해 |1558| `claude_code.commit.count` & `claude_code.pull_request.count` | 개발 워크플로우에 미치는 영향 이해 |

1555 1559 

1560사용 환경별 활성 사용자를 비교하려면 `OTEL_METRICS_INCLUDE_ENTRYPOINT=true`를 설정하여 메트릭과 이벤트에 [`app.entrypoint`](#standard-attributes)를 추가합니다. 그런 다음 [`claude_code.user_prompt`](#user-prompt-event) 이벤트에서, 또는 메트릭만 내보내는 경우 `claude_code.token.usage`에서 엔트리포인트별로 고유한 `user.account_uuid` 값의 수를 셉니다. 예를 들어 대화형 CLI 세션에는 `cli`를 사용하고, Claude Desktop의 Code 탭에는 `claude-desktop`, `claude-desktop-3p`, `remote_desktop`을 하나로 묶습니다.

1561 

1562`user.account_uuid`는 Claude Tag 채널 세션에서는 사람을 식별하지 않으며, Claude 계정이 없는 세션에는 존재하지 않습니다. [사용자에게 작업 귀속](#attribute-actions-to-users)을 참조하세요. 한 사람이 여러 세션을 시작하거나 세션이 프롬프트를 받지 않는 경우, [`claude_code.session.count`](#session-counter)는 증가하지만 활성 사용자는 늘어나지 않습니다.

1563 

1556### 비용 모니터링1564### 비용 모니터링

1557 1565 

1558`claude_code.cost.usage` 메트릭은 다음에 도움이 됩니다:1566`claude_code.cost.usage` 메트릭은 다음에 도움이 됩니다:

1783## 보안 및 개인 정보 보호1791## 보안 및 개인 정보 보호

1784 1792 

1785* OpenTelemetry 내보내기는 선택 사항이며 명시적 구성이 필요합니다. Anthropic의 별도 운영 원격 측정 및 이를 비활성화하는 방법에 대해서는 [데이터 사용](https://code.claude.com/docs/ko/data-usage.md#telemetry-services)을 참조하세요1793* OpenTelemetry 내보내기는 선택 사항이며 명시적 구성이 필요합니다. Anthropic의 별도 운영 원격 측정 및 이를 비활성화하는 방법에 대해서는 [데이터 사용](https://code.claude.com/docs/ko/data-usage.md#telemetry-services)을 참조하세요

1786* 원본 파일 콘텐츠 및 코드 스니펫은 메트릭 또는 이벤트에 포함되지 않습니다. 추적 스팬은 별도의 데이터 경로입니다: 아래의 `OTEL_LOG_TOOL_CONTENT` 항목을 참조하세요1794* 기본적으로 원본 파일 콘텐츠 및 코드 스니펫은 메트릭 또는 이벤트에 포함되지 않습니다. `OTEL_LOG_TOOL_DETAILS` 또는 `OTEL_LOG_RAW_API_BODIES`와 같은 변수를 설정하면 이벤트에 이러한 내용이 포함될 수 있습니다. 추적 스팬은 별도의 데이터 경로입니다: 아래의 `OTEL_LOG_TOOL_CONTENT` 항목을 참조하세요

1787* OAuth를 통해 인증된 경우 `user.email`이 원격 측정 속성에 포함되며, 구성한 OTel 엔드포인트로만 전송되고 Anthropic으로는 절대 전송되지 않습니다. 조직에서 이것이 우려 사항인 경우 원격 측정 백엔드와 함께 작업하여 이 필드를 필터링하거나 수정하세요1795* OAuth를 통해 인증된 경우 `user.email`이 원격 측정 속성에 포함되며, 구성한 OTel 엔드포인트로만 전송되고 Anthropic으로는 절대 전송되지 않습니다. 조직에서 이것이 우려 사항인 경우 원격 측정 백엔드와 함께 작업하여 이 필드를 필터링하거나 수정하세요

1788* 사용자 프롬프트 콘텐츠는 기본적으로 수집되지 않습니다. 프롬프트 길이만 기록됩니다. 프롬프트 콘텐츠를 포함하려면 `OTEL_LOG_USER_PROMPTS=1`을 설정하세요. 활성화되면:1796* 사용자 프롬프트 콘텐츠는 기본적으로 수집되지 않습니다. 프롬프트 길이만 기록됩니다. 프롬프트 콘텐츠를 포함하려면 `OTEL_LOG_USER_PROMPTS=1`을 설정하세요. 활성화되면:

1789 * `user_prompt` 이벤트는 `prompt`와 [`prompt_text`](#user-prompt-event)라는 두 속성에 프롬프트 텍스트를 전달합니다. 수집기에서 속성 이름으로 이벤트의 프롬프트 텍스트를 삭제하거나 마스킹하는 경우 규칙에 두 속성을 모두 지정하세요1797 * `user_prompt` 이벤트는 `prompt`와 [`prompt_text`](#user-prompt-event)라는 두 속성에 프롬프트 텍스트를 전달합니다. 수집기에서 속성 이름으로 이벤트의 프롬프트 텍스트를 삭제하거나 마스킹하는 경우 규칙에 두 속성을 모두 지정하세요

Details

686* **수락하는 경우**: Claude Code는 `skipDangerousModePermissionPrompt`를 `~/.claude/settings.json`에서 `true`로 설정하므로 이후 세션은 대화상자를 건너뜁니다. 대화상자를 다시 보려면 해당 파일에서 키를 제거하거나 `false`로 설정하십시오. [`skipDangerousModePermissionPrompt` 참조](https://code.claude.com/docs/ko/settings-reference#skipdangerousmodepermissionprompt)는 사용자 또는 조직이 설정할 수 있는 다른 설정 파일을 나열합니다.686* **수락하는 경우**: Claude Code는 `skipDangerousModePermissionPrompt`를 `~/.claude/settings.json`에서 `true`로 설정하므로 이후 세션은 대화상자를 건너뜁니다. 대화상자를 다시 보려면 해당 파일에서 키를 제거하거나 `false`로 설정하십시오. [`skipDangerousModePermissionPrompt` 참조](https://code.claude.com/docs/ko/settings-reference#skipdangerousmodepermissionprompt)는 사용자 또는 조직이 설정할 수 있는 다른 설정 파일을 나열합니다.

687* **거부하는 경우**: Claude Code가 종료됩니다.687* **거부하는 경우**: Claude Code가 종료됩니다.

688 688 

689`user` 없이 [`--setting-sources`](https://code.claude.com/docs/ko/cli-reference#cli-flags)를 전달하면, 이전에 수락했더라도 대화상자가 다시 나타날 수 있습니다. 이를 건너뛰려면 `--setting-sources user,project`와 같이 `user`를 추가하십시오.

690 

689[비대화형 모드](https://code.claude.com/docs/ko/headless.md)에서는 대화상자가 표시되지 않습니다.691[비대화형 모드](https://code.claude.com/docs/ko/headless.md)에서는 대화상자가 표시되지 않습니다.

690 692 

691[백그라운드 세션](https://code.claude.com/docs/ko/agent-view.md)은 수락 기록이 사용자 설정 또는 관리형 설정에 있을 때 이를 적용합니다:693[백그라운드 세션](https://code.claude.com/docs/ko/agent-view.md)은 수락 기록이 사용자 설정 또는 관리형 설정에 있을 때 이를 적용합니다:

permissions.md +5 −3

Details

578* `mcp__puppeteer__*`는 와일드카드 구문을 사용하며 역시 `puppeteer` 서버의 모든 도구와 매칭됩니다578* `mcp__puppeteer__*`는 와일드카드 구문을 사용하며 역시 `puppeteer` 서버의 모든 도구와 매칭됩니다

579* `mcp__puppeteer__puppeteer_navigate`는 `puppeteer` 서버가 제공하는 `puppeteer_navigate` 도구와 매칭됩니다579* `mcp__puppeteer__puppeteer_navigate`는 `puppeteer` 서버가 제공하는 `puppeteer_navigate` 도구와 매칭됩니다

580 580 

581MCP 도구에 대한 허용 규칙은 [지정자](#use-specifiers-for-fine-grained-control) 없이 작성하십시오. [권한 업데이트](https://code.claude.com/docs/ko/hooks.md#permission-update-entries)에서는 이 지정자를 `ruleContent`라고 부릅니다. 도구 호출 중 일부만 허용하기 위해 지정자를 추가하면 규칙은 어떤 호출과도 매칭되지 않습니다. 대신 일부 호출을 차단하려면 [입력 매개변수로 매칭](#match-by-input-parameter)을 참조하십시오.

582 

581`<server>`에는 해당 서버의 도구 이름에 나타나는 방식 그대로 서버 이름을 작성하십시오. 다음 예시는 특수 문자가 있는 이름, 플러그인의 서버, 그리고 `__`를 포함하거나 `_`로 끝나는 이름에 대해 작성할 규칙을 보여 줍니다.583`<server>`에는 해당 서버의 도구 이름에 나타나는 방식 그대로 서버 이름을 작성하십시오. 다음 예시는 특수 문자가 있는 이름, 플러그인의 서버, 그리고 `__`를 포함하거나 `_`로 끝나는 이름에 대해 작성할 규칙을 보여 줍니다.

582 584 

583* **`.`이나 공백 같은 문자가 있는 이름**: 해당 문자는 `_`가 되므로, `my.server`로 구성한 서버의 경우 `mcp__my_server__*`를 작성합니다585* **`.`이나 공백 같은 문자가 있는 이름**: 해당 문자는 `_`가 되므로, `my.server`로 구성한 서버의 경우 `mcp__my_server__*`를 작성합니다

632 634 

633PreToolUse 훅 결정은 권한 규칙을 우회하지 않습니다. Claude Code는 PreToolUse 훅이 반환하는 값에 관계없이 deny 및 ask 규칙을 평가합니다. 일치하는 deny 규칙은 호출을 차단하고, 일치하는 ask 규칙은 훅이 `"allow"` 또는 `"ask"`를 반환했을 때도 여전히 프롬프트합니다. 이는 [권한 관리](#manage-permissions)에서 설명한 deny 우선 우선순위를 유지하며, 관리형 설정에서 설정한 deny 규칙을 포함합니다.635PreToolUse 훅 결정은 권한 규칙을 우회하지 않습니다. Claude Code는 PreToolUse 훅이 반환하는 값에 관계없이 deny 및 ask 규칙을 평가합니다. 일치하는 deny 규칙은 호출을 차단하고, 일치하는 ask 규칙은 훅이 `"allow"` 또는 `"ask"`를 반환했을 때도 여전히 프롬프트합니다. 이는 [권한 관리](#manage-permissions)에서 설명한 deny 우선 우선순위를 유지하며, 관리형 설정에서 설정한 deny 규칙을 포함합니다.

634 636 

635이 우선순위는 설정 파일의 훅과 플러그인의 `hooks/hooks.json`에 있는 훅을 포함합니다. 설치한 [mod](https://code.claude.com/docs/ko/plugins/mods/overview.md)가 [`tool.check`](https://code.claude.com/docs/ko/plugins/mods/events#approve-or-refuse-a-tool-call-before-the-user-is-asked) 이벤트를 처리하면, `PreToolUse` 훅이 실행된 후에 응답합니다. 머신에 [관리형 설정](https://code.claude.com/docs/ko/settings.md#check-what-your-organization-enforces)이 있거나 Team 또는 Enterprise [`/login`](https://code.claude.com/docs/ko/authentication#authentication-precedence)이 세션의 자격 증명인 경우, mod가 호출을 승인해도 다음 결과는 기본적으로 그대로 유지됩니다:637이 우선순위는 설정 파일의 훅과 플러그인의 `hooks/hooks.json`에 있는 훅을 포함합니다. 설치한 [mod](https://code.claude.com/docs/ko/plugins/mods/overview.md)가 [`tool.check`](https://code.claude.com/docs/ko/plugins/mods/events#approve-or-refuse-a-tool-call-before-the-user-is-asked) 이벤트를 처리하면, `PreToolUse` 훅이 실행된 후에 응답합니다. [관리형 설정](https://code.claude.com/docs/ko/settings.md#check-what-your-organization-enforces)이나 [`managed-mcp.json` 파일](https://code.claude.com/docs/ko/managed-mcp#deploy-managed-mcp-json)이 있거나 Team 또는 Enterprise [`/login`](https://code.claude.com/docs/ko/authentication#authentication-precedence)이 세션의 자격 증명인 경우, mod가 호출을 승인해도 다음 결과는 기본적으로 그대로 유지됩니다:

636 638 

637* deny 규칙이 거부하는 호출은 계속 거부되며, 조직에서 이를 변경할 수 있습니다.639* deny 규칙이 거부하는 호출은 계속 거부됩니다.

638* ask 규칙이 확인을 요청할 호출은 여전히 확인을 요청합니다.640* ask 규칙이 확인을 요청할 호출은 여전히 확인을 요청합니다.

639* `PreToolUse` 훅 또는 [`permissions.blockReadsOutsideWorkingDirectories`](https://code.claude.com/docs/ko/settings-reference#permissions-blockreadsoutsideworkingdirectories)가 확인을 요청할 호출은 여전히 확인을 요청합니다.641* `PreToolUse` 훅 또는 [`permissions.blockReadsOutsideWorkingDirectories`](https://code.claude.com/docs/ko/settings-reference#permissions-blockreadsoutsideworkingdirectories)가 확인을 요청할 호출은 여전히 확인을 요청합니다.

640* `PreToolUse` 훅이 차단한 호출은 훅이 어느 설정 파일에서 왔는지에 관계없이 계속 차단됩니다.642* `PreToolUse` 훅이 차단한 호출은 훅이 어느 설정 파일에서 왔는지에 관계없이 계속 차단됩니다.

641* [`--permission-prompt-tool`](https://code.claude.com/docs/ko/cli-reference#cli-flags) 또는 Agent SDK [`canUseTool` 콜백](https://code.claude.com/docs/ko/agent-sdk/user-input#handle-tool-approval-requests)에 확인을 요청할 호출은 여전히 해당 도구나 콜백에 전달됩니다.643* [`--permission-prompt-tool`](https://code.claude.com/docs/ko/cli-reference#cli-flags) 또는 Agent SDK [`canUseTool` 콜백](https://code.claude.com/docs/ko/agent-sdk/user-input#handle-tool-approval-requests)에 확인을 요청할 호출은 여전히 해당 도구나 콜백에 전달됩니다.

642 644 

643관리형 설정이 없고 Team 또는 Enterprise `/login`도 세션의 자격 증명이 아닌 경우, mod는 deny 규칙이 거부하는 호출이나 `PreToolUse` 훅이 차단한 호출을 승인할 수 있습니다. 대신 API 키나 장기 [`CLAUDE_CODE_OAUTH_TOKEN`](https://code.claude.com/docs/ko/authentication#generate-a-long-lived-token)으로 실행되는 세션은 해당 로그인이 저장되어 있더라도 그 로그인을 사용하지 않습니다.645구성에 따라 관리형 설정과 `managed-mcp.json` 파일이 없고, Team 또는 Enterprise `/login`도 세션의 자격 증명이 아닐 수 있습니다. 이 구성에서는 mod가 deny 규칙이 거부하는 호출이나 `PreToolUse` 훅이 차단한 호출을 승인할 수 있습니다. 대신 API 키나 장기 [`CLAUDE_CODE_OAUTH_TOKEN`](https://code.claude.com/docs/ko/authentication#generate-a-long-lived-token)으로 실행되는 세션은 해당 로그인이 저장되어 있더라도 그 로그인을 사용하지 않습니다.

644 646 

645이 구성에서는 ask 규칙, `PreToolUse` 훅 또는 `permissions.blockReadsOutsideWorkingDirectories`가 확인을 요청할 호출을 mod가 승인하면 확인을 요청하지 않습니다. mod가 승인한 호출에 대해서는 `--permission-prompt-tool` 또는 `canUseTool` 콜백에도 묻지 않습니다. 자동 모드, 플랜 모드, `dontAsk` 모드는 모든 구성에서 각각 고유한 결과를 추가합니다:647이 구성에서는 ask 규칙, `PreToolUse` 훅 또는 `permissions.blockReadsOutsideWorkingDirectories`가 확인을 요청할 호출을 mod가 승인하면 확인을 요청하지 않습니다. mod가 승인한 호출에 대해서는 `--permission-prompt-tool` 또는 `canUseTool` 콜백에도 묻지 않습니다. 자동 모드, 플랜 모드, `dontAsk` 모드는 모든 구성에서 각각 고유한 결과를 추가합니다:

646 648 

Details

20 20 

21## claude plugin 명령21## claude plugin 명령

22 22 

23셸이나 스크립트에서 `claude plugin <subcommand>`을 실행하세요. Claude Code 세션 외부에서 실행합니다. 이 하위 명령들은 [`/plugin`](#plugin-in-a-session) 패널을 열지 않고 플러그인을 설치하고 관리합니다.23Claude Code 세션 밖에서 셸이나 스크립트로 `claude plugin <subcommand>`를 실행합니다. 이 하위 명령을 사용하면 [`/plugin`](#plugin-in-a-session) 패널을 열지 않고도 플러그인을 설치하고 관리할 수 있습니다.

24 24 

25`claude plugins`는 `claude plugin`의 별칭입니다.25`claude plugins`는 `claude plugin`의 별칭입니다.

26 26 

27모든 하위 명령은 다음 종료 코드, 플러그인 인수, 범위 값을 공유합니다:27모든 하위 명령은 다음 종료 코드, 플러그인 인수, 범위 값을 공유합니다.

28 28 

29* **종료 코드**: 성공 시 `0`, 실패 시 `1`. `validate`는 예상치 못한 오류에 대해 종료 코드 `2`를 추가하고, `eval`은 [해당 섹션](#plugin-eval)에 나열된 코드를 추가합니다.29* **종료 코드**: 성공 시 `0`, 실패 시 `1`입니다. `validate`는 예기치 않은 오류에 대해 종료 코드 `2`를 추가하고, `eval`은 [해당 섹션](#plugin-eval)에 나열된 코드를 추가합니다.

30* **플러그인 인수**: `<plugin>` 인수는 플러그인 `name` 또는 `name@marketplace`입니다. 두 마켓플레이스가 같은 이름을 제공할 때는 정규화된 형식을 사용하세요. `configure`는 정규화된 형식만 사용합니다.30* **플러그인 인수**: `<plugin>` 인수는 플러그인 `name` 또는 `name@marketplace`입니다. 두 마켓플레이스가 같은 이름을 제공하는 경우 정규화된 형식을 사용합니다. `configure`는 정규화된 형식만 받습니다.

31* **범위**: `--scope`는 `user`, `project`, 또는 `local`을 사용하며, 명령이 쓰는 설정 파일의 이름을 지정합니다. `update`는 `managed`도 사용합니다.31* **범위**: `--scope`는 `user`, `project`, `local` 중 하나를 받으며, 명령이 기록할 설정 파일을 지정합니다. `update`는 `managed`도 받습니다.

32 32 

33### plugin init33### plugin init

34 34 

35`~/.claude/skills/<name>/`에 새 플러그인을 스캐폴드합니다. 관리자가 [skills-directory 플러그인을 차단](https://code.claude.com/docs/ko/plugins/loading.md#skills-directory-plugins-blocked-by-managed-settings)하지 않은 한, 다음 세션에서 설치 단계 없이 `<name>@skills-dir`로 로드됩니다.35`~/.claude/skills/<name>/`에 새 플러그인의 기본 구조를 생성합니다. 관리자가 [스킬 디렉터리 플러그인을 차단](https://code.claude.com/docs/ko/plugins/loading.md#skills-directory-plugins-blocked-by-managed-settings)하지 않았다면, 별도의 설치 단계 없이 다음 세션에서 `<name>@skills-dir`로 로드됩니다.

36 36 

37`new`는 `init`의 별칭입니다.37`new`는 `init`의 별칭입니다.

38 38 

39이 명령으로 시작하는 생성, 테스트, 편집 워크플로는 [플러그인 생성](https://code.claude.com/docs/ko/plugins/create.md)을 참조하세요.39이 명령으로 시작하는 생성, 테스트, 편집 워크플로는 [플러그인 만들기](https://code.claude.com/docs/ko/plugins/create.md)를 참조하세요.

40 40 

41```bash theme={null}41```bash theme={null}

42claude plugin init <name> [options]42claude plugin init <name> [options]

43```43```

44 44 

45`<name>`은 `~/.claude/skills/` 아래의 디렉토리 이름이 되고 플러그인의 매니페스트에서 `name`이 됩니다.45`<name>`은 `~/.claude/skills/` 아래의 디렉터리 이름이자 매니페스트에 기록되는 플러그인의 `name`이 됩니다.

46 46 

47이 명령은 다른 위치에 대한 플래그가 없습니다. 대신 프로젝트 내에 스캐폴드하려면 [플러그인 생성](https://code.claude.com/docs/ko/plugins/create.md)을 참조하세요.47이 명령에는 다른 위치를 지정하는 플래그가 없습니다. 대신 프로젝트 안에 기본 구조를 생성하려면 [플러그인 만들기](https://code.claude.com/docs/ko/plugins/create.md)를 참조하세요.

48 48 

49| 플래그 | 설명 |49| 플래그 | 설명 |

50| :- | :- |50| :- | :- |

51| `--description <text>` | 매니페스트 설명 |51| `--description <text>` | 매니페스트 설명 |

52| `--author <name>` | 작성자 이름. 기본값은 `git config user.name` |52| `--author <name>` | 작성자 이름. 기본값은 `git config user.name` |

53| `--author-email <email>` | 작성자 이메일. 기본값은 `git config user.email` |53| `--author-email <email>` | 작성자 이메일. 기본값은 `git config user.email` |

54| `--with <components...>` | `skills`, `agents`, `hooks`, `mcp`, `lsp`, `output-style`, 또는 `channel`에 대한 스타터 파일도 스캐폴드합니다 |54| `--with <components...>` | `skills`, `agents`, `hooks`, `mcp`, `lsp`, `output-style`, `channel`에 대한 시작 파일도 함께 생성 |

55| `-f, --force` | 대상의 기존 `.claude-plugin/`을 덮어씁니다 |55| `-f, --force` | 대상 위치에 있는 기존 `.claude-plugin/`을 덮어씀 |

56 56 

57스킬 및 훅 파일 스타터를 포함한 플러그인을 스캐폴드합니다:57시작용 스킬 및 훅 파일을 포함한 플러그인 기본 구조를 생성합니다.

58 58 

59```bash theme={null}59```bash theme={null}

60claude plugin init my-helper --with skills hooks60claude plugin init my-helper --with skills hooks

61```61```

62 62 

63Claude Code는 작성한 내용을 검증하고 `Created plugin "my-helper" at ~/.claude/skills/my-helper`를 출력한 후, 로드되는 ID와 이를 끄는 `claude plugin disable` 명령을 출력합니다.63Claude Code는 작성한 내용을 검증한 뒤 `Created plugin "my-helper" at ~/.claude/skills/my-helper`를 출력하고, 이어서 로드될 ID와 플러그인을 끄는 `claude plugin disable` 명령을 출력합니다.

64 64 

65Claude Code는 안전하게 스캐폴드할 수 없을 때 아무것도 쓰지 않고 `1`로 종료하며 메시지에 이유를 명시합니다. 다음은 일반적인 이유입니다:65안전하게 기본 구조를 생성할 수 없는 경우 Claude Code는 아무것도 기록하지 않고 `1`로 종료하며, 메시지에 그 이유를 표시합니다. 일반적인 이유는 다음과 같습니다.

66 66 

67* 알 수 없는 `--with` 값67* 알 수 없는 `--with` 값

68* `--force` 없이 대상에 기존 스캐폴드가 있음68* `--force` 없이 대상 위치에 기존 기본 구조가 있는 경우

69* `skills-dir` 소스가 없는 관리형 마켓플레이스 허용 목록 또는 이를 지정하는 차단 목록. 메시지는 [`Plugins from ~/.claude/skills/ are blocked by your organization's managed settings`](https://code.claude.com/docs/ko/plugins/troubleshooting#plugins-from-claude-skills-are-blocked-by-your-organizations-managed-s)입니다.69* 관리형 마켓플레이스 허용 목록에 `skills-dir` 소스가 없거나, 차단 목록에 해당 소스가 지정된 경우. 이때 메시지는 [`Plugins from ~/.claude/skills/ are blocked by your organization's managed settings`](https://code.claude.com/docs/ko/plugins/troubleshooting#plugins-from-claude-skills-are-blocked-by-your-organizations-managed-s)입니다.

70 70 

71### plugin install71### plugin install

72 72 

73추가한 마켓플레이스에서 플러그인을 설치합니다. `i`는 `install`의 별칭입니다.73마켓플레이스 중 하나에서 플러그인을 설치합니다. `i`는 `install`의 별칭입니다.

74 74 

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

76claude plugin install <plugin> [options]76claude plugin install <plugin> [options]

77```77```

78 78 

79대부분의 플러그인은 프롬프트 없이 설치됩니다. 마켓플레이스 항목이 [설치를 위해 명령을 실행](https://code.claude.com/docs/ko/plugins/host-marketplace.md)하거나 [다운로드를 위해 `headersHelper`를 설정](https://code.claude.com/docs/ko/plugins/host-marketplace#how-users-accept-a-headershelper-command)하는 플러그인의 경우, Claude Code는 먼저 명령을 출력하고 `Run this command now? [y/N]`을 묻습니다.79대부분의 플러그인은 확인 요청 없이 설치됩니다. 마켓플레이스 항목이 [명령을 실행하여 설치](https://code.claude.com/docs/ko/plugins/host-marketplace.md)하거나 [다운로드에 `headersHelper`를 설정](https://code.claude.com/docs/ko/plugins/host-marketplace#how-users-accept-a-headershelper-command)하는 플러그인의 경우, Claude Code는 먼저 해당 명령을 출력하고 `Run this command now? [y/N]`라고 묻습니다.

80 80 

81| 플래그 | 설명 |81| 플래그 | 설명 |

82| :- | :- |82| :- | :- |

83| `-s, --scope <scope>` | 설치 범위: `user`, `project`, 또는 `local`. 기본값은 `user` |83| `-s, --scope <scope>` | 설치 범위: `user`, `project`, `local`. 기본값은 `user` |

84| `--config <key=value>` | 플러그인의 매니페스트가 선언하는 [`userConfig`](https://code.claude.com/docs/ko/plugins/manifest-reference) 옵션을 설정합니다. 각 옵션에 대해 플래그를 반복합니다. `<server>.<key>` 형식으로 작성된 키는 대신 플러그인 내부에 포함된 번들 파일의 [번들 MCP 서버](https://code.claude.com/docs/ko/plugins/components.md#include-a-packaged-mcpb-server)가 자체 `user_config`에서 선언하는 설정을 설정합니다. `<server>.<key>` 형식은 Claude Code v2.1.285 이상 필요합니다 |84| `--config <key=value>` | 플러그인 매니페스트가 선언한 [`userConfig`](https://code.claude.com/docs/ko/plugins/manifest-reference) 옵션을 설정합니다. 옵션마다 플래그를 반복합니다. `<server>.<key>` 형식으로 작성한 키는 플러그인 안에 포함된 번들 파일의 경우 [번들된 MCP 서버](https://code.claude.com/docs/ko/plugins/components.md#include-a-packaged-mcpb-server)가 자체 `user_config`에 선언한 설정을 대신 지정합니다. `<server>.<key>` 형식을 사용하려면 Claude Code v2.1.285 이상이 필요합니다 |

85| `-y, --yes` | `Run this command now?` 프롬프트 없이 표시된 설치 명령을 수락합니다. Bash 도구나 훅에서와 같이 Claude Code 세션 내부에서 명령이 실행될 때는 무시됩니다. Claude Code v2.1.229 이상 필요 |85| `-y, --yes` | `Run this command now?` 확인 요청 없이 표시된 설치 명령을 수락합니다. Bash 도구나 훅 등 Claude Code 세션 안에서 명령이 실행될 때는 무시됩니다. Claude Code v2.1.229 이상이 필요합니다 |

86| `--accept-command <sha256>` | 이전 [`--json` 실행](#plugin-json-result)이 `shownCommand`에서 보고한 `sha256`인 표시된 설치 명령을 수락합니다. `-y` 대신 사용합니다. `-y`와 결합할 수 없습니다. [표시된 설치 명령 수락](#accept-a-displayed-install-command)을 참조하세요. Claude Code v2.1.271 이상 필요 |86| `--accept-command <sha256>` | `-y` 대신, 이전 [`--json` 실행](#plugin-json-result)이 `shownCommand`에 보고한 `sha256`에 해당하는 표시된 설치 명령을 수락합니다. `-y`와 함께 사용할 수 없습니다. [표시된 설치 명령 수락](#accept-a-displayed-install-command)을 참조하세요. Claude Code v2.1.271 이상이 필요합니다 |

87| `--json` | 스크립트에서 사용하기 위해 사람이 읽을 수 있는 메시지 대신 stdout의 마지막 줄에 하나의 JSON 객체로 결과를 출력합니다. [JSON 결과 형식](#plugin-json-result)을 참조하세요. Claude Code v2.1.268 이상 필요 |87| `--json` | 스크립트에서 사용할 수 있도록 사람이 읽을 수 있는 메시지 대신 stdout의 마지막 줄에 결과를 하나의 JSON 객체로 출력합니다. [JSON 결과 형식](#plugin-json-result)을 참조하세요. Claude Code v2.1.268 이상이 필요합니다 |

88| `--marketplace <source>` | 이름만으로 지정한 `<plugin>`을 `<source>`의 마켓플레이스에서 설치합니다. 해당 마켓플레이스를 아직 추가하지 않았다면 먼저 추가합니다. [한 번의 명령으로 마켓플레이스 추가 및 설치](https://code.claude.com/docs/ko/plugins/install.md#add-a-marketplace-and-install-in-one-command)를 참조하세요. Claude Code v2.1.292 이상 필요 |88| `--marketplace <source>` | 순수 이름으로 지정한 `<plugin>`을 `<source>`에 있는 마켓플레이스에서 설치하며, 해당 마켓플레이스를 아직 추가하지 않았다면 먼저 추가합니다. [한 번의 명령으로 마켓플레이스 추가 및 설치](https://code.claude.com/docs/ko/plugins/install.md#add-a-marketplace-and-install-in-one-command)를 참조하세요. Claude Code v2.1.292 이상이 필요합니다 |

89 89 

90셸에서 `claude plugin install --help`를 실행하여 버전이 지원하는 모든 옵션을 확인하세요.90사용 중인 버전이 지원하는 모든 옵션을 보려면 셸에서 `claude plugin install --help`를 실행하세요.

91 91 

92자신의 터미널에서 `-y`를 전달하여 프롬프트 없이 표시된 명령을 수락합니다. TTY가 없을 때와 Claude가 명령을 실행할 때 어떤 일이 발생하는지 다음과 같습니다:92확인 요청 없이 표시된 명령을 수락하려면 직접 사용하는 터미널에서 `-y`를 전달합니다. TTY가 없을 때와 Claude가 명령을 실행할 때는 다음과 같이 동작합니다.

93 93 

94* **stdin 또는 stdout이 TTY가 아니고 `-y` 또는 `--accept-command`를 전달하지 않음**: 설치가 거부됩니다. 출력에는 명령만 표시되었다고 나오고 종료 코드는 `1`입니다94* **stdin 또는 stdout이 TTY가 아니고 `-y`와 `--accept-command` 중 어느 것도 전달하지 않은 경우**: 설치가 거부됩니다. 출력에 명령이 표시만 되었다고 나타나며 종료 코드는 `1`입니다

95* **Claude가 Bash 도구를 통해 명령을 실행**: `-y`는 무시됩니다. 대신 자신의 터미널에서 명령을 실행하세요95* **Claude가 Bash 도구를 통해 명령을 실행하는 경우**: `-y`가 무시됩니다. 대신 직접 사용하는 터미널에서 명령을 실행하세요

96 96 

97프로젝트를 복제하는 모든 사람을 위해 플러그인을 설치합니다:97프로젝트를 클론하는 모든 사람과 플러그인을 공유하려면 `--scope project`로 `claude plugin install`을 실행하고 `.claude/settings.json`을 커밋하세요. 그런 다음 각 사용자가 자신의 클론에서 [마켓플레이스를 추가](https://code.claude.com/docs/ko/plugins/install.md#add-a-marketplace)하고 [같은 명령을 실행](https://code.claude.com/docs/ko/plugins/loading.md#enabled-in-project-settings-but-not-installed)하도록 합니다.

98 98 

99```bash theme={null}99```bash theme={null}

100claude plugin install formatter@my-marketplace --scope project100claude plugin install formatter@my-marketplace --scope project

101```101```

102 102 

103Claude Code는 `Successfully installed plugin: formatter@my-marketplace (scope: project)`를 출력합니다. 새로운 것이 설치되지 않으면 출력에 이유가 나옵니다:103Claude Code는 `Successfully installed plugin: formatter@my-marketplace (scope: project)`를 출력합니다. 새로 설치된 항목이 없으면 출력에 그 이유가 나타납니다.

104 104 

105* **해당 범위에 이미 설치됨**: 출력은 `Plugin "formatter@my-marketplace" is already installed (scope: project)`이고 종료 코드는 `0`입니다105* **해당 범위에 이미 설치된 경우**: 출력은 `Plugin "formatter@my-marketplace" is already installed (scope: project)`이고 종료 코드는 `0`입니다

106* **명령 소스 프롬프트를 거부함**: 출력은 `Aborted.`이고 종료 코드는 `1`입니다106* **명령 소스 확인 요청을 거부한 경우**: 출력은 `Aborted.`이고 종료 코드는 `1`입니다

107* **`headersHelper` 프롬프트를 거부하거나 TTY 없이 확인할 수 없음**: 출력은 `Aborted — the command was not run.`이고 종료 코드는 `1`입니다107* **`headersHelper` 확인 요청을 거부했거나 TTY가 없어 확인할 수 없는 경우**: 출력은 `Aborted — the command was not run.`이고 종료 코드는 `1`입니다

108 108 

109#### JSON 결과 형식109#### JSON 결과 형식

110 110 

111`plugin install`에 `--json`을 전달하면 stdout의 마지막 줄은 하나의 JSON 객체입니다. Claude Code가 마켓플레이스에서 선언한 명령을 그 앞에 출력하므로 해당 줄만 파싱하세요.111`plugin install`에 `--json`을 전달하면 stdout의 마지막 줄은 하나의 JSON 객체입니다. Claude Code가 마켓플레이스에서 선언한 명령을 그보다 앞에 출력하므로 해당 줄만 파싱하세요.

112 112 

113세 개의 필드는 항상 존재합니다:113다음 세 필드는 항상 존재합니다.

114 114 

115* `command`: 실행된 하위 명령(예: `install`)115* `command`: 실행된 하위 명령(예: `install`)

116* `outcome`: `ok` 또는 `failed`116* `outcome`: `ok` 또는 `failed`

117* `message`: 결과에 대한 사람이 읽을 수 있는 설명117* `message`: 사람이 읽을 수 있는 결과 설명

118 118 

119`pluginId`, `scope`, `failureCode` 같은 다른 필드는 적용될 때만 나타납니다.119`pluginId`, `scope`, `failureCode` 같은 다른 필드는 해당되는 경우에만 나타납니다.

120 120 

121`--json` 옵션은 `plugin uninstall`, `plugin update`, `plugin enable`, `plugin disable`에서도 해당 하위 명령의 자체 필드를 포함한 동일한 객체를 출력합니다.121`plugin uninstall`, `plugin update`, `plugin enable`, `plugin disable`의 `--json` 옵션은 각 하위 명령 고유의 필드를 포함한 동일한 객체를 출력합니다.

122 122 

123사용 오류(예: 잘못된 `--scope`)는 결과 줄을 출력하지 않고 stderr에 이유를 포함하여 `1`로 종료합니다.123잘못된 `--scope` 같은 사용법 오류는 결과 줄을 출력하지 않고, 이유를 stderr에 출력하며 `1`로 종료합니다.

124 124 

125#### 마켓플레이스 명령의 JSON 결과125#### 마켓플레이스 명령의 JSON 결과

126 126 

127`plugin marketplace add`, `plugin marketplace remove`, `plugin marketplace update`에서 `--json`은 stdout의 마지막 줄에 `command`, `outcome`, `message` 필드가 있는 하나의 JSON 객체를 출력합니다. 다음은 `claude plugin marketplace remove your-marketplace --json`의 결과입니다:127`plugin marketplace add`, `plugin marketplace remove`, `plugin marketplace update`에서 `--json`은 stdout의 마지막 줄에 `command`, `outcome`, `message` 필드를 포함한 하나의 JSON 객체를 출력합니다. 다음은 `claude plugin marketplace remove your-marketplace --json`의 결과입니다.

128 128 

129```json theme={null}129```json theme={null}

130{"command":"marketplace-remove","outcome":"ok","marketplace":"your-marketplace","message":"Successfully removed marketplace: your-marketplace"}130{"command":"marketplace-remove","outcome":"ok","marketplace":"your-marketplace","message":"Successfully removed marketplace: your-marketplace"}

131```131```

132 132 

133`command` 값은 `marketplace-add`, `marketplace-remove`, 또는 `marketplace-update`입니다. 아래 필드는 적용될 때만 나타납니다:133`command` 값은 `marketplace-add`, `marketplace-remove`, `marketplace-update` 중 하나입니다. 아래 필드는 해당되는 경우에만 나타납니다.

134 134 

135* `marketplace`: 명령이 작업한 마켓플레이스의 이름135* `marketplace`: 명령이 작업한 마켓플레이스의 이름

136* `failureCode`: 명령이 실패한 이유를 나타내는 코드(예: `invalid_source`)136* `failureCode`: 명령이 실패한 이유를 나타내는 코드(예: `invalid_source`)

137 137 

138인수가 [예약된 이름](https://code.claude.com/docs/ko/plugins/marketplace-reference.md#reserved-names)인 `anthropic-plugin-directory`일 때 `plugin marketplace add`와 `plugin marketplace remove`는 결과 줄을 출력하지 않을 수 있으므로, 해당 이름에 대해서는 종료 코드를 확인하세요.138인수가 [예약된 이름](https://code.claude.com/docs/ko/plugins/marketplace-reference.md#reserved-names)인 `anthropic-plugin-directory`인 경우 `plugin marketplace add`와 `plugin marketplace remove`는 결과 줄을 출력하지 않을 수 있으므로, 이 이름에 대해서는 종료 코드를 확인하세요.

139 139 

140#### 표시된 설치 명령 수락140#### 표시된 설치 명령 수락

141 141 

142`--json` 실행이 마켓플레이스에서 선언한 명령을 표시하고 실행하지 않으면, `failed` 결과는 `shownCommand` 객체도 포함합니다. 해당 필드에는 표시된 명령, 속한 플러그인, 명령의 `sha256`이 포함됩니다.142`--json` 실행이 마켓플레이스에서 선언한 명령을 표시만 하고 실행하지 않으면, `failed` 결과에 `shownCommand` 객체도 포함됩니다. 이 객체의 필드에는 표시된 그대로의 명령, 해당 명령이 속한 플러그인, 그리고 명령의 `sha256`이 포함됩니다.

143 143 

144정확히 그 명령을 수락하려면 자신의 터미널에서 해당 `sha256`을 `--accept-command`로 다시 실행하세요. 플래그는 Claude Code 세션 내부에서 효과가 없기 때문입니다. Claude Code v2.1.271 이상 필요합니다.144정확히 그 명령을 수락하려면 직접 사용하는 터미널에서 해당 `sha256`을 `--accept-command`로 지정해 다시 실행합니다. 이 플래그는 Claude Code 세션 안에서는 효과가 없기 때문입니다. Claude Code v2.1.271 이상이 필요합니다.

145 145 

146`sha256`은 정확히 그 명령, 플러그인, 마켓플레이스 카탈로그에 대한 수락으로 계산됩니다. 명령이 표시된 이후 이들 중 하나라도 변경되면 Claude Code는 `sha256`을 수락하지 않고 명령을 다시 표시합니다. 실행 자체의 마켓플레이스 새로고침이 가져오는 변경도 그러한 변경으로 계산됩니다.146`sha256`은 정확히 그 명령, 플러그인, 마켓플레이스 카탈로그에 대해서만 수락으로 간주됩니다. 명령이 표시된 이후 이 중 하나라도 변경되었다면 Claude Code는 `sha256`을 수락하지 않고 명령을 다시 표시합니다. 실행 과정에서 이루어지는 마켓플레이스 새로 고침으로 가져온 변경도 이러한 변경에 해당합니다.

147 147 

148`shownCommand.acceptCommandMatched`가 `false`이면, 전달한 `sha256`이 현재 표시된 명령과 일치하지 않습니다. 해당 명령을 검토한 후 해당 `sha256`으로 다시 실행하세요.148`shownCommand.acceptCommandMatched`가 `false`이면 전달한 `sha256`이 현재 표시된 명령과 일치하지 않는 것입니다. 해당 명령의 `sha256`으로 다시 실행하기 전에 그 명령을 검토하세요.

149 149 

150### plugin uninstall150### plugin uninstall

151 151 

157 157 

158| 플래그 | 설명 |158| 플래그 | 설명 |

159| :- | :- |159| :- | :- |

160| `-s, --scope <scope>` | 범위에서 제거: `user`, `project`, 또는 `local`. 기본값은 `user` |160| `-s, --scope <scope>` | 제거할 범위: `user`, `project`, `local`. 기본값은 `user` |

161| `--keep-data` | 플러그인의 지속적 데이터 디렉토리 `~/.claude/plugins/data/<id>/`를 보존합니다 |161| `--keep-data` | 플러그인의 영구 데이터 디렉터리 `~/.claude/plugins/data/<id>/`를 보존 |

162| `--prune` | 남은 플러그인이 필요하지 않은 자동 설치된 [의존성](https://code.claude.com/docs/ko/plugins/dependencies.md)도 제거합니다 |162| `--prune` | 남은 플러그인 중 어느 것도 필요로 하지 않는 자동 설치된 [의존성](https://code.claude.com/docs/ko/plugins/dependencies.md)도 제거 |

163| `-y, --yes` | `--prune` 확인 프롬프트를 건너뜁니다. stdin 또는 stdout이 TTY가 아닐 때 `--prune`과 함께 필요합니다 |163| `-y, --yes` | `--prune` 확인 요청을 건너뜁니다. stdin 또는 stdout이 TTY가 아닐 때 `--prune`과 함께 사용해야 합니다 |

164| `--json` | 결과를 stdout의 마지막 줄에 하나의 JSON 객체로 출력합니다. [`plugin install --json`](#plugin-json-result)과 동일한 형식입니다. `--prune`과 결합할 수 없습니다. Claude Code v2.1.268 이상 필요 |164| `--json` | [`plugin install --json`과 같은 형식](#plugin-json-result)으로 stdout의 마지막 줄에 결과를 하나의 JSON 객체로 출력합니다. `--prune`과 함께 사용할 수 없습니다. Claude Code v2.1.268 이상이 필요합니다 |

165 165 

166프로젝트 범위에서 플러그인을 제거합니다:166프로젝트 범위에서 플러그인을 제거합니다.

167 167 

168```bash theme={null}168```bash theme={null}

169claude plugin uninstall formatter@my-marketplace --scope project169claude plugin uninstall formatter@my-marketplace --scope project

170```170```

171 171 

172Claude Code는 `Successfully uninstalled plugin: formatter (scope: project)`를 출력합니다. 플러그인이 해당 범위에 설치되지 않으면 명령은 `Failed to uninstall plugin "formatter@my-marketplace":`로 시작하는 줄을 출력하고 `1`로 종료합니다.172Claude Code는 `Successfully uninstalled plugin: formatter (scope: project)`를 출력합니다. 해당 범위에 플러그인이 설치되어 있지 않으면 `Failed to uninstall plugin "formatter@my-marketplace":`로 시작하는 줄을 출력하고 `1`로 종료합니다.

173 173 

174실패 줄이 `"formatter" was not uninstalled:`로 계속되고 설정 파일의 이름을 지정하면, Claude Code는 범위의 설정이 더 이상 플러그인을 켜지 않는지 확인할 수 없으므로 플러그인은 저장한 모든 것과 함께 설치된 상태로 유지됩니다. `--json`을 사용하면 결과는 `failureCode: "settings_still_on"`을 포함합니다. 이 설정 확인은 Claude Code v2.1.282 이상 필요합니다.174실패 줄이 `"formatter" was not uninstalled:`로 이어지며 설정 파일 이름을 표시하는 경우, Claude Code가 해당 범위의 설정이 더 이상 플러그인을 켜지 않는다는 것을 확인하지 못한 것이므로, 플러그인은 저장된 모든 항목과 함께 설치된 상태로 유지됩니다. `--json`을 사용하면 결과에 `failureCode: "settings_still_on"`이 포함됩니다. 이 설정 확인에는 Claude Code v2.1.282 이상이 필요합니다.

175 175 

176#### 제거가 삭제하고 유지하는 것176#### 제거 시 삭제되는 항목과 유지되는 항목

177 177 

178마지막으로 설치된 범위에서 플러그인을 제거하면, Claude Code는 플러그인의 저장된 [옵션 및 시크릿](https://code.claude.com/docs/ko/plugins/manifest-reference.md#user-configuration)과 데이터 디렉토리 `~/.claude/plugins/data/<id>/`도 삭제합니다. 세 가지 예외가 있습니다:178플러그인이 설치된 마지막 범위에서 플러그인을 제거하면, Claude Code는 플러그인에 저장된 [옵션과 시크릿](https://code.claude.com/docs/ko/plugins/manifest-reference.md#user-configuration), 그리고 데이터 디렉터리 `~/.claude/plugins/data/<id>/`도 삭제합니다. 다음 세 가지 예외가 있습니다.

179 179 

180* `--keep-data`를 사용하면 데이터 디렉토리가 유지됩니다180* `--keep-data`를 사용하면 데이터 디렉터리가 유지됩니다

181* 다른 설치된 플러그인이 같은 폴더를 사용할 때(예: 이 플러그인과 ID가 문자 대소문자에서만 다른 경우) 데이터 디렉토리가 유지됩니다181* 다른 설치된 플러그인이 같은 폴더를 사용하는 경우(예: ID가 이 플러그인과 대소문자만 다른 플러그인) 데이터 디렉터리가 유지됩니다

182* Claude Code가 해당 범위에서 플러그인을 제거한 후 설치된 플러그인 목록을 다시 읽을 수 없으면 옵션, 시크릿, 데이터 디렉토리 모두 유지됩니다. 플러그인이 다른 범위에 여전히 설치되어 있을 수 있기 때문입니다. 제거는 여전히 성공합니다. 메시지는 유지된 것과 삭제 방법을 나열하고, `--json`을 사용하면 결과는 `savedKept: "install_records_unreadable"`을 포함합니다182* 해당 범위에서 플러그인을 제거한 후 Claude Code가 설치된 플러그인 목록을 다시 읽을 수 없는 경우, 플러그인이 다른 범위에 여전히 설치되어 있을 수 있으므로 옵션, 시크릿, 데이터 디렉터리가 모두 유지됩니다. 제거 자체는 성공합니다. 메시지에 유지된 항목과 이를 삭제하는 방법이 나열되며, `--json`을 사용하면 결과에 `savedKept: "install_records_unreadable"`이 포함됩니다

183 183 

184`--json`을 사용하면 `keptData`는 디렉토리가 유지되었는지 보고하고, `/plugin`은 유지되었을 때 `· data preserved`를 표시합니다. `--keep-data` 없이 유지되는 디렉토리의 경우 이 보고는 Claude Code v2.1.281 이상 필요합니다. `savedKept` 필드는 Claude Code v2.1.282 이상 필요합니다.184`--json`을 사용하면 `keptData`가 디렉터리의 유지 여부를 보고하며, 유지된 경우 `/plugin`에 `· data preserved`가 표시됩니다. `--keep-data` 없이 디렉터리가 유지되는 경우 이 보고 기능에는 Claude Code v2.1.281 이상이 필요합니다. `savedKept` 필드에는 Claude Code v2.1.282 이상이 필요합니다.

185 185 

186### plugin enable186### plugin enable

187 187 

188비활성화된 플러그인을 활성화합니다. [claude.ai에서 동기화된 플러그인](https://code.claude.com/docs/ko/plugins/loading.md#synced-plugins)의 경우 `<name>@synced`를 플러그인으로 전달하세요.188비활성화된 플러그인을 활성화합니다. [claude.ai에서 동기화된 플러그인](https://code.claude.com/docs/ko/plugins/loading.md#synced-plugins)의 경우 플러그인으로 `<name>@synced`를 전달합니다.

189 189 

190```bash theme={null}190```bash theme={null}

191claude plugin enable <plugin> [options]191claude plugin enable <plugin> [options]

193 193 

194| 플래그 | 설명 |194| 플래그 | 설명 |

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

196| `-s, --scope <scope>` | 활성화할 범위: `user`, `project`, 또는 `local`. 생략하면 자동 감지됩니다 |196| `-s, --scope <scope>` | 활성화할 범위: `user`, `project`, `local`. 생략하면 자동으로 감지됩니다 |

197| `--json` | 결과를 stdout의 마지막 줄에 하나의 JSON 객체로 출력합니다. [`plugin install --json`](#plugin-json-result)과 동일한 형식입니다. Claude Code v2.1.268 이상 필요 |197| `--json` | [`plugin install --json`과 같은 형식](#plugin-json-result)으로 stdout의 마지막 줄에 결과를 하나의 JSON 객체로 출력합니다. Claude Code v2.1.268 이상이 필요합니다 |

198 198 

199`--scope` 없이 명령은 설정 파일을 local, project, user 순서로 확인하고 플러그인을 언급하는 첫 번째 범위를 사용합니다.199`--scope`가 없으면 명령은 local, project, user 순서로 설정 파일을 확인하고 플러그인을 언급하는 첫 번째 범위를 사용합니다.

200 200 

201플러그인이 선언되지 않은 `--scope`를 전달하면 명령은 재정의를 쓰거나 실패합니다:201플러그인이 선언되지 않은 `--scope`를 전달하면 명령은 재정의를 기록하거나 실패합니다.

202 202 

203* **선언하는 범위보다 [우선순위가 높은 범위](https://code.claude.com/docs/ko/plugins/loading.md)**: Claude Code는 전달한 범위에 재정의를 씁니다. 예를 들어 `claude plugin disable formatter --scope local`은 프로젝트에서 활성화된 플러그인을 혼자만 끕니다203* **선언된 범위보다 [우선하는](https://code.claude.com/docs/ko/plugins/loading.md) 범위**: Claude Code는 전달한 범위에 재정의를 기록합니다. 예를 들어 `claude plugin disable formatter --scope local`은 프로젝트에서 활성화된 플러그인을 본인에 대해서만 끕니다

204* **다른 범위**: 명령은 `Plugin "formatter" is installed at project scope, not user. Use --scope project or omit --scope to auto-detect.`로 실패합니다204* **그 외의 범위**: 명령이 `Plugin "formatter" is installed at project scope, not user. Use --scope project or omit --scope to auto-detect.`와 함께 실패합니다

205 205 

206플러그인이 해결된 범위에서 이미 활성화되어 있으면 명령은 `Plugin "formatter" is already enabled`를 출력하고 `1`로 종료합니다. `--json`을 사용하면 결과는 `"failureCode": "already_in_goal_state"`와 `"alreadyInGoalState": true`를 가지므로 스크립트는 그 경우를 성공으로 처리할 수 있습니다.206결정된 범위에서 플러그인이 이미 활성화되어 있으면 명령은 `Plugin "formatter" is already enabled`를 출력하고 `1`로 종료합니다. `--json`을 사용하면 결과에 `"failureCode": "already_in_goal_state"`와 `"alreadyInGoalState": true`가 포함되므로, 스크립트에서 이 경우를 성공으로 처리할 수 있습니다.

207 207 

208플러그인이 [의존성](https://code.claude.com/docs/ko/plugins/dependencies.md)을 선언하면 Claude Code는 이들도 활성화합니다. 명령은 다음 경우에 실패합니다:208플러그인이 [의존성](https://code.claude.com/docs/ko/plugins/dependencies.md)을 선언하면 Claude Code는 의존성도 함께 활성화합니다. 다음 경우에는 명령이 실패합니다.

209 209 

210* **의존성이 설치되지 않음**: 활성화가 실패하고 누락된 각 의존성에 대해 `claude plugin install` 명령을 출력합니다210* **의존성이 설치되어 있지 않은 경우**: 활성화가 실패하고 누락된 각 의존성에 대한 `claude plugin install` 명령을 출력합니다

211* **의존성이 조직의 플러그인 정책에 의해 차단됨**: 활성화가 실패하고 차단된 의존성의 이름을 지정합니다211* **의존성이 조직의 플러그인 정책에 의해 차단된 경우**: 활성화가 실패하고 차단된 의존성의 이름을 표시합니다

212* **의존성이 대상 범위보다 우선순위가 높은 범위에서 `false`로 설정됨**: 활성화가 실패합니다. 해당 범위에서 의존성을 활성화하거나 `--scope`를 전달하여 거기에 쓰세요212* **대상 범위보다 우선순위가 높은 범위에서 의존성이 `false`로 설정된 경우**: 활성화가 실패합니다. 해당 범위에서 의존성을 활성화하거나, `--scope`를 전달하여 그 범위에 기록하세요

213 213 

214선언된 곳 어디든 플러그인을 다시 활성화합니다:214플러그인이 선언된 위치에서 다시 활성화합니다.

215 215 

216```bash theme={null}216```bash theme={null}

217claude plugin enable formatter217claude plugin enable formatter

218```218```

219 219 

220Claude Code는 `Successfully enabled plugin: formatter (scope: project)`를 출력하고 감지된 범위의 이름을 지정합니다.220Claude Code는 감지한 범위를 포함하여 `Successfully enabled plugin: formatter (scope: project)`를 출력합니다.

221 221 

222### plugin disable222### plugin disable

223 223 

224플러그인을 제거하지 않고 비활성화합니다. [claude.ai에서 동기화된 플러그인](https://code.claude.com/docs/ko/plugins/loading.md#synced-plugins)의 경우 `<name>@synced`를 플러그인으로 전달하세요.224플러그인을 제거하지 않고 비활성화합니다. [claude.ai에서 동기화된 플러그인](https://code.claude.com/docs/ko/plugins/loading.md#synced-plugins)의 경우 플러그인으로 `<name>@synced`를 전달합니다.

225 225 

226```bash theme={null}226```bash theme={null}

227claude plugin disable [plugin] [options]227claude plugin disable [plugin] [options]

229 229 

230| 플래그 | 설명 |230| 플래그 | 설명 |

231| :- | :- |231| :- | :- |

232| `-a, --all` | 활성화된 모든 플러그인을 비활성화합니다. 플러그인 이름이나 `--scope`와 결합할 수 없습니다 |232| `-a, --all` | 활성화된 모든 플러그인을 비활성화합니다. 플러그인 이름이나 `--scope`와 함께 사용할 수 없습니다 |

233| `-s, --scope <scope>` | 비활성화할 범위: `user`, `project`, 또는 `local`. 생략하면 자동 감지됩니다 |233| `-s, --scope <scope>` | 비활성화할 범위: `user`, `project`, `local`. 생략하면 자동으로 감지됩니다 |

234| `--json` | 결과를 stdout의 마지막 줄에 하나의 JSON 객체로 출력합니다. [`plugin install --json`](#plugin-json-result)과 동일한 형식입니다. Claude Code v2.1.268 이상 필요 |234| `--json` | [`plugin install --json`과 같은 형식](#plugin-json-result)으로 stdout의 마지막 줄에 결과를 하나의 JSON 객체로 출력합니다. Claude Code v2.1.268 이상이 필요합니다 |

235 235 

236`--scope` 없이 범위는 [`plugin enable`](#plugin-enable)과 동일한 local, project, user 순서로 자동 감지됩니다.236`--scope`가 없으면 [`plugin enable`](#plugin-enable)과 같은 local, project, user 순서로 범위를 자동 감지합니다.

237 237 

238플러그인 이름이나 `--all`을 모두 전달하지 않으면 Claude Code는 `Please specify a plugin name or use --all to disable all plugins`를 출력하고 `1`로 종료합니다. 이미 비활성화된 플러그인을 비활성화하면 `Plugin "formatter" is already disabled`를 출력하고 `1`로 종료합니다. [`plugin enable`](#plugin-enable)이 이미 활성화된 플러그인에 대해 하는 것과 같습니다.238플러그인 이름과 `--all` 중 어느 것도 전달하지 않으면 Claude Code는 `Please specify a plugin name or use --all to disable all plugins`를 출력하고 `1`로 종료합니다. 이미 비활성화된 플러그인을 비활성화하면, [`plugin enable`](#plugin-enable)이 이미 활성화된 플러그인에 대해 동작하는 것처럼 `Plugin "formatter" is already disabled`를 출력하고 `1`로 종료합니다.

239 239 

240명령은 여전히 필요한 플러그인에 대해 실패합니다:240여전히 필요한 플러그인에 대해서는 명령이 실패합니다.

241 241 

242* **다른 활성화된 플러그인이 [이에 의존](https://code.claude.com/docs/ko/plugins/dependencies.md)함**: 명령이 실패하고 먼저 비활성화할 의존 플러그인의 이름을 지정합니다242* **활성화된 다른 플러그인이 해당 플러그인에 [의존하는](https://code.claude.com/docs/ko/plugins/dependencies.md) 경우**: 명령이 실패하고 먼저 비활성화해야 할 의존 플러그인의 이름을 표시합니다

243* **조직이 동기화된 플러그인으로 이를 요구함**: 명령이 실패하고 아무것도 저장하지 않습니다243* **조직이 해당 플러그인을 동기화된 플러그인으로 요구하는 경우**: 명령이 실패하고 아무것도 저장하지 않습니다

244 244 

245한 플러그인을 비활성화합니다:245플러그인 하나를 비활성화합니다.

246 246 

247```bash theme={null}247```bash theme={null}

248claude plugin disable formatter248claude plugin disable formatter

252 252 

253### plugin update253### plugin update

254 254 

255플러그인을 마켓플레이스가 제공하는 최신 버전으로 업데이트합니다. 새 버전은 다음 세션에 로드되거나 실행 중인 세션에서 `/reload-plugins`를 실행한 후 로드됩니다.255플러그인을 마켓플레이스가 제공하는 최신 버전으로 업데이트합니다. 새 버전은 다음 세션에서, 또는 실행 중인 세션에서 `/reload-plugins`를 실행한 후에 로드됩니다.

256 256 

257```bash theme={null}257```bash theme={null}

258claude plugin update <plugin> [options]258claude plugin update <plugin> [options]

260 260 

261| 플래그 | 설명 |261| 플래그 | 설명 |

262| :- | :- |262| :- | :- |

263| `-s, --scope <scope>` | 업데이트할 범위: `user`, `project`, `local`, 또는 `managed`. 생략하면 자동 감지됩니다 |263| `-s, --scope <scope>` | 업데이트할 범위: `user`, `project`, `local`, `managed`. 생략하면 자동으로 감지됩니다 |

264| `-y, --yes` | [명령 소스](https://code.claude.com/docs/ko/plugins/host-marketplace.md) 플러그인에서 변경된 설치 명령을 프롬프트 없이 수락합니다. `--accept-command`를 전달하지 않는 한 stdin 또는 stdout이 TTY가 아닐 때 필요합니다. Claude Code v2.1.229 이상 필요 |264| `-y, --yes` | [명령 소스](https://code.claude.com/docs/ko/plugins/host-marketplace.md) 플러그인의 변경된 설치 명령을 확인 요청 없이 수락합니다. `--accept-command`를 전달하지 않는 한, stdin 또는 stdout이 TTY가 아닐 때 필요합니다. Claude Code v2.1.229 이상이 필요합니다 |

265| `--accept-command <sha256>` | 이전 [`--json` 실행](#plugin-json-result)이 `shownCommand`에서 보고한 `sha256`인 마켓플레이스에서 선언한 명령을 수락합니다. `-y` 대신 사용합니다. `-y`와 결합할 수 없습니다. Claude Code v2.1.271 이상 필요 |265| `--accept-command <sha256>` | `-y` 대신, 이전 [`--json` 실행](#plugin-json-result)이 `shownCommand`에 보고한 `sha256`에 해당하는 마켓플레이스 선언 명령을 수락합니다. `-y`와 함께 사용할 수 없습니다. Claude Code v2.1.271 이상이 필요합니다 |

266| `--json` | 결과를 stdout의 마지막 줄에 하나의 JSON 객체로 출력합니다. [`plugin install --json`](#plugin-json-result)과 동일한 형식입니다. Claude Code v2.1.268 이상 필요 |266| `--json` | [`plugin install --json`과 같은 형식](#plugin-json-result)으로 stdout의 마지막 줄에 결과를 하나의 JSON 객체로 출력합니다. Claude Code v2.1.268 이상이 필요합니다 |

267 267 

268플러그인을 업데이트합니다:268플러그인을 업데이트합니다.

269 269 

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

271claude plugin update formatter@my-marketplace271claude plugin update formatter@my-marketplace

272```272```

273 273 

274Claude Code는 `Checking for updates for plugin "formatter@my-marketplace"…`를 출력한 후 결과를 출력합니다. 더 새로운 것이 없으면 `formatter is already at the latest version (1.0.0).`를 출력하고 `0`으로 종료합니다. 단, [플러그인의 의존성 설치를 재시도](#retry-an-unfinished-dependency-install)하고 그 설치가 실패하는 경우는 예외입니다.274Claude Code는 `Checking for updates for plugin "formatter@my-marketplace"…`를 출력한 다음 결과를 출력합니다. 더 새로운 버전이 없으면 `formatter is already at the latest version (1.0.0).`를 출력하고 `0`으로 종료합니다. 단, [플러그인의 의존성 설치를 재시도](#retry-an-unfinished-dependency-install)했는데 그 설치가 실패한 경우는 예외입니다.

275 275 

276#### 명령이 업데이트하는 범위276#### 명령이 업데이트하는 범위

277 277 

278`--scope`를 생략하면 명령은 현재 프로젝트에 설치된 가장 구체적인 범위에서 플러그인을 업데이트합니다. local, project, user, managed 순서로 확인합니다.278`--scope`를 생략하면 명령은 현재 프로젝트에 대해 플러그인이 설치된 가장 구체적인 범위에서 플러그인을 업데이트하며, local, project, user, managed 순서로 확인합니다.

279 279 

280v2.1.281 이전에는 `--scope`를 생략할 때 명령이 `user`를 사용했으므로 프로젝트 또는 local 범위에만 설치된 플러그인을 업데이트하면 `Plugin "<name>" is not installed at scope user`로 실패했습니다. 이 버전에서는 `--scope`를 전달하세요.280v2.1.281 이전에는 `--scope`를 생략하면 명령이 `user`를 사용했으므로, 프로젝트 또는 로컬 범위에만 설치된 플러그인을 업데이트하면 `Plugin "<name>" is not installed at scope user`와 함께 실패했습니다. 이러한 버전에서는 `--scope`를 전달하세요.

281 281 

282`managed`는 업데이트할 수 있지만 설치할 수 없는 유일한 범위입니다. 관리자가 설치한 플러그인은 [조직을 위한 플러그인 관리](https://code.claude.com/docs/ko/plugins/org.md)를 참조하세요.282`managed`는 업데이트는 가능하지만 설치는 할 수 없는 유일한 범위입니다. 관리자가 설치한 플러그인에 대해서는 [조직의 플러그인 관리](https://code.claude.com/docs/ko/plugins/org.md)를 참조하세요.

283 283 

284#### 이름만으로 업데이트284#### 순수 이름으로 업데이트

285 285 

286플러그인 이름만 전달할 수 있으며, 명령은 설치된 플러그인과 일치시킵니다. 다른 마켓플레이스의 설치된 플러그인이 이름을 공유하면 명령은 업데이트를 거부하고 대신 실행할 정규화된 `plugin-name@marketplace-name` 명령을 나열합니다. 이름만으로 업데이트하려면 Claude Code v2.1.246 이상 필요합니다.286순수 플러그인 이름을 전달할 수 있으며, 명령은 이를 설치된 플러그인과 대조합니다. 서로 다른 마켓플레이스에서 설치된 플러그인이 같은 이름을 공유하면 명령은 업데이트를 거부하고 대신 실행할 정규화된 `plugin-name@marketplace-name` 명령을 나열합니다. 순수 이름으로 업데이트하려면 Claude Code v2.1.246 이상이 필요합니다.

287 287 

288#### 완료되지 않은 의존성 설치 재시도288#### 완료되지 않은 의존성 설치 재시도

289 289 

290플러그인이 이미 최신 버전이면 명령은 캐시된 사본에서 완료되지 않은 의존성 설치를 재시도할 수도 있습니다. 이 재시도가 실행되거나 건너뛰어지는 경우는 [나열된 패키지가 설치되지 않음](https://code.claude.com/docs/ko/plugins/troubleshooting.md#the-packages-it-lists-are-not-installed)을 참조하세요. 재시도가 실패하면 출력은 이유와 함께 `Failed to update plugin "formatter@my-marketplace"`이고 종료 코드는 `1`입니다. v2.1.287 이전에는 명령이 설치를 재시도하지 않고 플러그인이 최신 버전이라고 보고했습니다.290플러그인이 이미 최신 버전인 경우, 명령은 캐시된 사본에서 완료되지 않은 의존성 설치를 재시도할 수도 있습니다. 이 재시도가 실행되거나 건너뛰어지는 경우는 [나열된 패키지가 설치되지 않음](https://code.claude.com/docs/ko/plugins/troubleshooting.md#the-packages-it-lists-are-not-installed)을 참조하세요. 재시도가 실패하면 출력은 이유와 함께 `Failed to update plugin "formatter@my-marketplace"`이고 종료 코드는 `1`입니다. v2.1.287 이전에는 명령이 설치를 재시도하지 않고 플러그인이 최신 버전이라고 보고했습니다.

291 291 

292### plugin list292### plugin list

293 293 

299 299 

300| 플래그 | 설명 |300| 플래그 | 설명 |

301| :- | :- |301| :- | :- |

302| `--json` | 목록을 JSON으로 출력합니다 |302| `--json` | 목록을 JSON으로 출력 |

303| `--available` | 설치하지 않은 마켓플레이스가 제공하는 플러그인도 나열합니다. `--json` 없이는 효과가 없습니다 |303| `--available` | 마켓플레이스가 제공하지만 설치하지 않은 플러그인도 나열합니다. `--json` 없이는 효과가 없습니다 |

304| `--data-size [plugin]` | 각 설치된 플러그인의 [저장된 데이터 디렉토리](#what-an-uninstall-deletes-and-keeps)를 측정하거나 `name@marketplace`로 지정된 명명된 플러그인만 측정합니다. `--json` 없이는 효과가 없습니다. 이름에 설치 기록이 없으면 명령은 `--data-size names a plugin that is not installed`를 출력하고 목록을 출력하는 대신 `1`로 종료합니다. Claude Code v2.1.285 이상 필요합니다 |304| `--data-size [plugin]` | 설치된 각 플러그인의 [저장된 데이터 디렉터리](#what-an-uninstall-deletes-and-keeps) 크기를 측정하거나, `name@marketplace`로 지정한 플러그인의 크기만 측정합니다. `--json` 없이는 효과가 없습니다. 이름에 해당하는 설치 기록이 없으면 명령은 목록을 출력하는 대신 `--data-size names a plugin that is not installed`를 출력하고 `1`로 종료합니다. Claude Code v2.1.285 이상이 필요합니다 |

305 305 

306Claude Code는 사람이 읽을 수 있는 출력을 각 플러그인이 로드되는 방식으로 그룹화합니다:306Claude Code는 사람이 읽을 수 있는 출력을 각 플러그인이 로드되는 방식에 따라 그룹화합니다.

307 307 

308* **`Installed plugins:`**: 마켓플레이스에서 설치한 플러그인308* **`Installed plugins:`**: 마켓플레이스에서 설치한 플러그인

309* **`Session-only plugins (--plugin-dir / --plugin-url):`**: 같은 명령에서 이 플래그로 로드된 플러그인(예: `claude --plugin-dir ./my-plugin plugin list`)309* **`Session-only plugins (--plugin-dir / --plugin-url):`**: `claude --plugin-dir ./my-plugin plugin list`처럼 같은 명령에서 해당 플래그로 로드된 플러그인

310* **`Skills-directory plugins (.claude/skills/*):`**: Claude Code가 skills 디렉토리에서 찾은 플러그인310* **`Skills-directory plugins (.claude/skills/*):`**: Claude Code가 스킬 디렉터리에서 찾은 플러그인

311* **`Synced from claude.ai`**: [claude.ai 계정에서 동기화된 플러그인](https://code.claude.com/docs/ko/plugins/loading.md#synced-plugins)311* **`Synced from claude.ai`**: [claude.ai 계정에서 동기화된 플러그인](https://code.claude.com/docs/ko/plugins/loading.md#synced-plugins)

312 312 

313어떤 그룹에도 아무것도 없으면 Claude Code는 ``No plugins installed. Use `claude plugin install` to install a plugin.``를 출력합니다.313어느 그룹에도 항목이 없으면 Claude Code는 ``No plugins installed. Use `claude plugin install` to install a plugin.``를 출력합니다.

314 314 

315#### JSON 출력315#### JSON 출력

316 316 

317`--json`을 사용하면 Claude Code는 설치당 하나의 객체를 포함하는 배열을 출력합니다. 각 객체는 아래 필드를 포함합니다. `id`, `version`, `scope`, `enabled`, `installPath`는 항상 존재하고 다른 필드는 적용될 때만 나타납니다.317`--json`을 사용하면 Claude Code는 설치마다 하나의 객체를 포함한 배열을 출력합니다. 각 객체에는 아래 필드가 포함됩니다. `id`, `version`, `scope`, `enabled`, `installPath`는 항상 존재하며, 나머지는 해당되는 경우에만 나타납니다.

318 318 

319| 필드 | 유형 | 설명 |319| 필드 | 타입 | 설명 |

320| :- | :- | :- |320| :- | :- | :- |

321| `id` | string | 설치의 경우 `name@marketplace`, 세션 전용 플러그인의 경우 `name@inline`, skills-directory 플러그인의 경우 `name@skills-dir`, claude.ai에서 동기화된 플러그인의 경우 `name@synced` |321| `id` | string | 설치의 경우 `name@marketplace`, 세션 전용 플러그인의 경우 `name@inline`, 스킬 디렉터리 플러그인의 경우 `name@skills-dir`, claude.ai에서 동기화된 플러그인의 경우 `name@synced` |

322| `version` | string | 마켓플레이스 설치의 경우 [Claude Code가 설치 시 계산한](https://code.claude.com/docs/ko/plugins/loading.md#versions-and-updates) 버전. 세션 전용, skills-directory, 또는 동기화된 플러그인의 경우 매니페스트의 `version`, 또는 선언하지 않으면 `unknown` |322| `version` | string | 마켓플레이스 설치의 경우 설치 시 [Claude Code가 계산한 버전](https://code.claude.com/docs/ko/plugins/loading.md#versions-and-updates). 세션 전용, 스킬 디렉터리 또는 동기화된 플러그인의 경우 매니페스트의 `version`이며, 선언이 없으면 `unknown` |

323| `scope` | string | 설치의 경우 `user`, `project`, `local`, 또는 `managed`. skills-directory 플러그인의 경우 `user` 또는 `project`. 세션 전용 플러그인의 경우 `session`. claude.ai에서 동기화된 플러그인의 경우 `synced` |323| `scope` | string | 설치의 경우 `user`, `project`, `local`, `managed`; 스킬 디렉터리 플러그인의 경우 `user` 또는 `project`; 세션 전용 플러그인의 경우 `session`; claude.ai에서 동기화된 플러그인의 경우 `synced` |

324| `enabled` | boolean | 병합된 설정에서 플러그인이 활성화되어 있는지 여부 |324| `enabled` | boolean | 병합된 설정에서 플러그인이 활성화되어 있는지 여부 |

325| `installPath` | string | 플러그인이 로드되는 디렉토리. 단, 세션이 마켓플레이스 폴더에서 [제자리에서 로드](https://code.claude.com/docs/ko/plugins/loading.md#in-place-and-copied-plugins)하는 플러그인은 제외 |325| `installPath` | string | 플러그인이 로드되는 디렉터리. 단, 세션이 마켓플레이스 폴더에서 [제자리에서 로드](https://code.claude.com/docs/ko/plugins/loading.md#in-place-and-copied-plugins)하는 플러그인은 제외 |

326| `readFromFolder` | string | 세션이 마켓플레이스 폴더에서 [제자리에서 로드](https://code.claude.com/docs/ko/plugins/loading.md#in-place-and-copied-plugins)하는 플러그인의 경우, 해당 폴더 안에 있는 플러그인의 소스 디렉토리. Claude Code v2.1.289 이상 필요 |326| `readFromFolder` | string | 세션이 마켓플레이스 폴더에서 [제자리에서 로드](https://code.claude.com/docs/ko/plugins/loading.md#in-place-and-copied-plugins)하는 플러그인의 경우, 해당 폴더 안에 있는 플러그인의 소스 디렉터리. Claude Code v2.1.289 이상이 필요합니다 |

327| `folderVersion` | string | `readFromFolder`가 있을 때, Claude Code가 해당 폴더에서 로드한 플러그인의 `version`으로, 위의 `version` 필드와 다를 수 있습니다. 플러그인이 로드되지 않았거나 버전을 선언하지 않으면 없습니다. Claude Code v2.1.289 이상 필요 |327| `folderVersion` | string | `readFromFolder`와 함께 나타나며, Claude Code가 해당 폴더에서 로드한 플러그인의 `version`으로, 위의 `version` 필드와 다를 수 있습니다. 플러그인이 로드되지 않았거나 버전을 선언하지 않으면 나타나지 않습니다. Claude Code v2.1.289 이상이 필요합니다 |

328| `installedAt` | string | 설치의 ISO 타임스탬프. 마켓플레이스 설치만 해당 |328| `installedAt` | string | 설치의 ISO 타임스탬프. 마켓플레이스 설치에만 해당 |

329| `lastUpdated` | string | 마지막 업데이트의 ISO 타임스탬프. 마켓플레이스 설치만 해당 |329| `lastUpdated` | string | 마지막 업데이트의 ISO 타임스탬프. 마켓플레이스 설치에만 해당 |

330| `projectPath` | string | 설치가 속한 프로젝트. `project` 및 `local` 범위만 해당 |330| `projectPath` | string | 설치가 속한 프로젝트. `project` 및 `local` 범위에만 해당 |

331| `mcpServers` | object | 플러그인의 MCP 서버 정의(마켓플레이스에서 설치한 플러그인이 있을 때) |331| `mcpServers` | object | 마켓플레이스에서 설치한 플러그인에 MCP 서버 정의가 있는 경우, 해당 정의 |

332| `errors` | array of strings | 플러그인이 로드되지 않았을 때의 로드 오류 |332| `errors` | array of strings | 플러그인 로드에 실패한 경우의 로드 오류 |

333| `notes` | array of strings | 작성 문제나 [설치되지 않은 패키지](https://code.claude.com/docs/ko/plugins/loading.md#when-the-dependency-install-fails-or-is-skipped)처럼 로드 오류가 아닌 경고 |333| `notes` | array of strings | 작성 관련 문제나 [설치되지 않은 패키지](https://code.claude.com/docs/ko/plugins/loading.md#when-the-dependency-install-fails-or-is-skipped) 등 로드 오류가 아닌 경고 |

334| `errorDetails` | array of objects | 각 `errors` 항목에 대한 하나의 객체로, 진단 `type`과 플러그인, 마켓플레이스, 서버, 파일 같은 참조하는 이름을 제공합니다. Claude Code v2.1.268 이상 필요 |334| `errorDetails` | array of objects | 각 `errors` 항목마다 하나의 객체로, 진단 `type`과 플러그인, 마켓플레이스, 서버, 파일 등 참조하는 이름을 제공합니다. Claude Code v2.1.268 이상이 필요합니다 |

335| `noteDetails` | array of objects | 각 `notes` 항목에 대한 동일한 세부 객체. Claude Code v2.1.268 이상 필요 |335| `noteDetails` | array of objects | 각 `notes` 항목에 대한 동일한 세부 정보 객체. Claude Code v2.1.268 이상이 필요합니다 |

336| `hasUserConfig` | boolean | 플러그인이 로드되고 매니페스트가 [`userConfig` 옵션](https://code.claude.com/docs/ko/plugins/manifest-reference#user-configuration)을 선언할 때 존재하고 `true`입니다. 플러그인이 로드되지 않은 경우 매니페스트가 무엇을 선언하든 없습니다. 저장된 값은 절대 포함되지 않습니다. Claude Code v2.1.285 이상 필요합니다 |336| `hasUserConfig` | boolean | 플러그인이 로드되었고 매니페스트가 [`userConfig` 옵션](https://code.claude.com/docs/ko/plugins/manifest-reference#user-configuration)을 선언한 경우 존재하며 `true`입니다. 로드에 실패한 플러그인에 대해서는 매니페스트의 선언과 관계없이 나타나지 않습니다. Claude Code v2.1.285 이상이 필요합니다 |

337| `projectEnabled` | boolean | 프로젝트의 공유 `.claude/settings.json`이 플러그인을 켜는지 여부. 마켓플레이스 설치만 해당. Claude Code v2.1.285 이상 필요합니다 |337| `projectEnabled` | boolean | 프로젝트의 공유 `.claude/settings.json`이 플러그인을 켜는지 여부. 마켓플레이스 설치에만 해당. Claude Code v2.1.285 이상이 필요합니다 |

338| `dataDirSize` | object | `--data-size`를 사용하면 플러그인의 [저장된 데이터 디렉토리](#what-an-uninstall-deletes-and-keeps)의 크기를 `bytes`와 `human`으로 표시합니다. 디렉토리가 없거나 비어 있으면 없습니다. 마켓플레이스 설치만 해당. Claude Code v2.1.285 이상 필요합니다 |338| `dataDirSize` | object | `--data-size`와 함께 나타나며, 플러그인의 [저장된 데이터 디렉터리](#what-an-uninstall-deletes-and-keeps) 크기를 `bytes`와 `human`으로 제공합니다. 디렉터리가 없거나 비어 있으면 나타나지 않습니다. 마켓플레이스 설치에만 해당. Claude Code v2.1.285 이상이 필요합니다 |

339| `dataDirUnreadable` | boolean | `--data-size`를 사용하면 저장된 데이터 디렉토리가 존재하지만 측정할 수 없을 때 `true`입니다. 마켓플레이스 설치만 해당. Claude Code v2.1.285 이상 필요합니다 |339| `dataDirUnreadable` | boolean | `--data-size`와 함께 나타나며, 저장된 데이터 디렉터리가 존재하지만 측정할 수 없는 경우 `true`. 마켓플레이스 설치에만 해당. Claude Code v2.1.285 이상이 필요합니다 |

340 340 

341`--json --available`을 사용하면 Claude Code는 배열 대신 하나의 객체를 출력합니다. 해당 `installed` 필드는 설치된 플러그인 객체의 배열을 보유하고, `available` 필드는 설치하지 않은 각 마켓플레이스 플러그인에 대해 아래 필드를 포함하는 하나의 객체를 보유합니다.341`--json --available`을 사용하면 Claude Code는 배열 대신 하나의 객체를 출력합니다. 이 객체의 `installed` 필드에는 설치된 플러그인 객체의 배열이, `available` 필드에는 설치되지 않은 마켓플레이스 플러그인마다 아래 필드를 가진 객체가 하나씩 담깁니다.

342 342 

343| 필드 | 유형 | 설명 |343| 필드 | 타입 | 설명 |

344| :- | :- | :- |344| :- | :- | :- |

345| `pluginId` | string | `name@marketplace` |345| `pluginId` | string | `name@marketplace` |

346| `name` | string | 마켓플레이스의 플러그인 이름 |346| `name` | string | 마켓플레이스에서의 플러그인 이름 |

347| `marketplaceName` | string | 이를 제공하는 마켓플레이스 |347| `marketplaceName` | string | 플러그인을 제공하는 마켓플레이스 |

348| `source` | string or object | 마켓플레이스 항목의 [source](https://code.claude.com/docs/ko/plugins/marketplace-reference.md): 상대 경로의 경우 string, 그 외의 경우 object |348| `source` | string or object | 마켓플레이스 항목의 [소스](https://code.claude.com/docs/ko/plugins/marketplace-reference.md): 상대 경로이면 문자열, 그 외에는 객체 |

349| `description` | string | 항목의 설명(있을 때) |349| `description` | string | 항목에 설명이 있는 경우 해당 설명 |

350| `version` | string | 항목의 버전(선언할 때) |350| `version` | string | 항목이 버전을 선언한 경우 해당 버전 |

351| `installCount` | number | 설치 수(Claude Code가 플러그인에 대해 가지고 있을 때) |351| `installCount` | number | Claude Code에 해당 플러그인의 설치 수가 있는 경우 설치 수 |

352 352 

353### plugin details353### plugin details

354 354 

355플러그인의 컴포넌트 인벤토리와 예상 토큰 비용을 표시합니다.355플러그인의 구성 요소 목록과 예상 토큰 비용을 표시합니다.

356 356 

357플러그인은 로드되어야 합니다: 설치되거나, skills 디렉토리에서 찾거나, 같은 명령에서 `--plugin-dir` 또는 `--plugin-url`로 전달됩니다. `<name>`은 플러그인 `name` 또는 `name@marketplace`입니다.357플러그인은 로드된 상태여야 합니다. 즉, 설치되어 있거나, 스킬 디렉터리에서 발견되었거나, 같은 명령에서 `--plugin-dir` 또는 `--plugin-url`로 전달되어야 합니다. `<name>`은 플러그인 `name` 또는 `name@marketplace`입니다.

358 358 

359```bash theme={null}359```bash theme={null}

360claude plugin details <name>360claude plugin details <name>

361```361```

362 362 

363명령은 `--help` 외에 플래그를 사용하지 않습니다.363이 명령은 `--help` 외에는 플래그를 받지 않습니다.

364 364 

365설치된 플러그인이 기여하는 것을 표시합니다:365설치된 플러그인이 제공하는 내용을 표시합니다.

366 366 

367```bash theme={null}367```bash theme={null}

368claude plugin details formatter368claude plugin details formatter

369```369```

370 370 

371Claude Code는 플러그인의 이름, 버전, 설명, 소스를 출력한 후 다음 섹션을 출력합니다:371Claude Code는 플러그인의 이름, 버전, 설명, 소스를 출력한 다음 다음 섹션을 출력합니다.

372 372 

373* **`Component inventory`**: 플러그인의 skills, agents, hooks, MCP 서버, LSP 서버373* **`Component inventory`**: 플러그인의 스킬, 에이전트, 훅, MCP 서버, LSP 서버

374* **`Projected token cost`**: 플러그인이 모든 세션에 추가하는 항상 켜진 토큰374* **`Projected token cost`**: 플러그인이 모든 세션에 추가하는 상시 토큰

375* **`Per-component (rounded)`**: 각 skill, agent, 명령에 대한 항상 켜진 토큰과 호출 시 추정치. 플러그인에 이러한 항목이 없을 때 생략됨375* **`Per-component (rounded)`**: 각 스킬, 에이전트, 명령에 대한 상시 및 호출 시 추정치. 플러그인에 해당 항목이 없으면 생략됩니다

376 376 

377두 비용 수치가 의미하는 바는 [플러그인 비용 및 사용량 측정](https://code.claude.com/docs/ko/plugins/measure.md)을 참조하세요.377두 비용 수치의 의미는 [플러그인 비용 및 사용량 측정](https://code.claude.com/docs/ko/plugins/measure.md)을 참조하세요.

378 378 

379로드되지 않은 플러그인의 경우 Claude Code는 다음 메시지를 출력하고 `1`로 종료합니다:379로드되지 않은 플러그인의 경우 Claude Code는 다음 메시지를 출력하고 `1`로 종료합니다.

380 380 

381```text theme={null}381```text theme={null}

382Plugin "formatter" not found. Run `claude plugin list` to see installed plugins, or pass --plugin-dir <path> to load one from disk.382Plugin "formatter" not found. Run `claude plugin list` to see installed plugins, or pass --plugin-dir <path> to load one from disk.

383```383```

384 384 

385`@builtin`으로 끝나는 ID는 [Claude Code에 내장된 플러그인](https://code.claude.com/docs/ko/plugins/mods/overview.md#mods-built-into-claude-code) 중 하나를 가리킵니다. 이러한 ID를 전달했는데 Claude Code가 해당 플러그인을 찾지 못하면 메시지는 대신 다음과 같습니다:385`@builtin`으로 끝나는 ID는 [Claude Code에 내장된 플러그인](https://code.claude.com/docs/ko/plugins/mods/overview.md#mods-built-into-claude-code) 중 하나를 가리킵니다. 이러한 ID를 전달했는데 Claude Code가 해당 플러그인을 찾지 못하면 대신 다음 메시지가 표시됩니다.

386 386 

387```text theme={null}387```text theme={null}

388Plugin "<name>@builtin" not found. Built-in plugins don't appear in `claude plugin list`. To see the ones available in a session, run /plugin in Claude Code and open the Installed tab.388Plugin "<name>@builtin" not found. Built-in plugins don't appear in `claude plugin list`. To see the ones available in a session, run /plugin in Claude Code and open the Installed tab.

390 390 

391### plugin configure391### plugin configure

392 392 

393설치된 플러그인의 [`userConfig`](https://code.claude.com/docs/ko/plugins/manifest-reference#user-configuration) 옵션과 설정된 옵션을 표시하거나 stdin에서 파이프된 값을 저장합니다. Claude Code v2.1.285 이상 필요합니다.393설치된 플러그인의 [`userConfig`](https://code.claude.com/docs/ko/plugins/manifest-reference#user-configuration) 옵션과 설정된 옵션을 표시하거나, stdin으로 전달된 값을 저장합니다. Claude Code v2.1.285 이상이 필요합니다.

394 394 

395```bash theme={null}395```bash theme={null}

396claude plugin configure <plugin>396claude plugin configure <plugin>

398 398 

399| 플래그 | 설명 |399| 플래그 | 설명 |

400| :- | :- |400| :- | :- |

401| `--values-stdin` | stdin에서 옵션 값을 단일 줄 문자열로 이루어진 JSON 객체로 읽고 저장합니다. 생략한 옵션은 저장된 값을 유지합니다 |401| `--values-stdin` | stdin에서 한 줄 문자열로 구성된 JSON 객체로 옵션 값을 읽어 저장합니다. 생략한 옵션은 저장된 값을 유지합니다 |

402| `--json` | 결과를 stdout에 하나의 JSON 객체로 출력합니다. `--values-stdin` 없이 객체는 옵션의 `schema`와 `choices`, 시작 `inputs`, `configured`와 `unconfigured` 옵션 이름을 포함합니다. `--values-stdin`을 사용하면 `saved` 옵션 이름과 다시 읽을 수 있을 때 `unconfigured` 옵션 이름을 포함합니다 |402| `--json` | stdout에 결과를 하나의 JSON 객체로 출력합니다. `--values-stdin` 없이 사용하면 객체에 옵션의 `schema`와 `choices`, 시작 `inputs`, 그리고 `configured` 및 `unconfigured` 옵션 이름이 포함됩니다. `--values-stdin`과 함께 사용하면 `saved` 옵션 이름과, 다시 읽을 수 있는 경우 `unconfigured` 옵션 이름이 포함됩니다 |

403 403 

404플래그 없이 명령은 각 옵션을 최대 세 개의 레이블로 나열합니다: `required` 또는 `optional`, 그 다음 매니페스트가 민감하다고 선언하는 옵션의 경우 `sensitive`, 그 다음 `set` 또는 `not set`. 저장된 값을 출력하지 않습니다. `--json`을 사용하면 출력에는 민감하지 않은 옵션의 저장된 값이 포함되고 민감한 옵션의 텍스트는 절대 포함되지 않습니다.404플래그 없이 실행하면 명령은 각 옵션을 최대 세 개의 레이블과 함께 나열합니다. `required` 또는 `optional`, 매니페스트가 민감한 옵션으로 선언한 경우 `sensitive`, 그리고 `set` 또는 `not set` 순입니다. 저장된 값은 출력하지 않습니다. `--json`을 사용하면 출력에 민감하지 않은 옵션의 저장된 값이 포함되며, 민감한 옵션의 텍스트는 절대 포함되지 않습니다.

405 405 

406값을 저장하려면 옵션 키를 문자열 값으로 매핑하는 JSON 객체로 파일에 작성한 후 파일을 stdin에 전달하세요. `formatter@my-marketplace`를 `claude plugin list`가 표시하는 자신의 플러그인 ID로 바꾸세요. 이 예제는 `{"api_url": "https://example.com"}`을 포함하는 `values.json` 파일에서 `api_url`이라는 하나의 옵션을 설정합니다:406값을 저장하려면 옵션 키를 문자열 값에 매핑하는 JSON 객체로 파일에 작성한 다음, 해당 파일을 stdin으로 전달합니다. `formatter@my-marketplace`를 `claude plugin list`에 표시되는 자신의 플러그인 ID로 바꾸세요. 이 예시는 `{"api_url": "https://example.com"}`가 담긴 `values.json` 파일에서 `api_url`이라는 옵션 하나를 설정합니다.

407 407 

408```bash theme={null}408```bash theme={null}

409claude plugin configure formatter@my-marketplace --values-stdin < values.json409claude plugin configure formatter@my-marketplace --values-stdin < values.json

410```410```

411 411 

412Claude Code는 각 값을 옵션의 선언된 유형에 대해 검증하고 `Configuration saved. Restart Claude Code to apply it.`를 출력합니다. 매니페스트가 선언하지 않은 키를 전달하거나 검증에 실패하는 값을 전달하면 명령은 아무것도 저장하지 않고, `Failed to save configuration:`을 이유와 함께 출력하고, `1`로 종료합니다. `--json`을 사용하면 거부된 값은 stdout에 `refused` 필드가 `message`를 포함하고 한 옵션이 잘못되었을 때 해당 `option` 키를 포함하는 객체도 출력합니다.412Claude Code는 각 값을 옵션에 선언된 타입과 대조하여 검증하고 `Configuration saved. Restart Claude Code to apply it.`를 출력합니다. 매니페스트가 선언하지 않은 키나 검증에 실패한 값을 전달하면 명령은 아무것도 저장하지 않고, 이유와 함께 `Failed to save configuration:`를 출력한 후 `1`로 종료합니다. `--json`을 사용하면 거부된 값이 있을 때 stdout에 객체도 출력되며, 이 객체의 `refused` 필드에는 `message`와, 하나의 옵션에 문제가 있는 경우 해당 `option` 키가 포함됩니다.

413 413 

414`claude plugin list`가 표시하는 대로 플러그인의 전체 `name@marketplace` ID를 전달하세요. `configure`는 `name`만으로는 수락하지 않습니다. 로드된 플러그인이 해당 ID를 가지지 않으면 명령은 `No installed plugin has the id "<plugin>".`를 출력하고 `1`로 종료합니다.414`claude plugin list`에 표시되는 대로 플러그인의 전체 `name@marketplace` ID를 전달하세요. `configure`는 순수 `name`을 받지 않습니다. 해당 ID를 가진 로드된 플러그인이 없으면 명령은 `No installed plugin has the id "<plugin>".`를 출력하고 `1`로 종료합니다.

415 415 

416번들 MCP 서버의 설정은 [`plugin install --config`](#plugin-install) 또는 `/plugin`의 **Configure** 항목을 참조하세요.416번들된 MCP 서버의 설정에 대해서는 [`plugin install --config`](#plugin-install) 또는 `/plugin`의 **Configure** 항목을 참조하세요.

417 417 

418### plugin prune418### plugin prune

419 419 

420설치된 플러그인이 더 이상 필요하지 않은 자동 설치된 [의존성](https://code.claude.com/docs/ko/plugins/dependencies.md)을 제거합니다. 명령은 직접 설치한 플러그인을 절대 제거하지 않습니다. `autoremove`는 `prune`의 별칭입니다.420더 이상 설치된 플러그인 중 어느 것도 필요로 하지 않는 자동 설치된 [의존성](https://code.claude.com/docs/ko/plugins/dependencies.md)을 제거합니다. 이 명령은 사용자가 직접 설치한 플러그인은 절대 제거하지 않습니다. `autoremove`는 `prune`의 별칭입니다.

421 421 

422```bash theme={null}422```bash theme={null}

423claude plugin prune [options]423claude plugin prune [options]

425 425 

426| 플래그 | 설명 |426| 플래그 | 설명 |

427| :- | :- |427| :- | :- |

428| `-s, --scope <scope>` | 범위에서 정리: `user`, `project`, 또는 `local`. 기본값은 `user` |428| `-s, --scope <scope>` | 정리할 범위: `user`, `project`, `local`. 기본값은 `user` |

429| `--dry-run` | 제거하지 않고 제거될 것을 나열합니다 |429| `--dry-run` | 실제로 제거하지 않고 제거될 항목을 나열 |

430| `-y, --yes` | 확인 프롬프트를 건너뜁니다. stdin 또는 stdout이 TTY가 아닐 때 필요합니다 |430| `-y, --yes` | 확인 요청을 건너뜁니다. stdin 또는 stdout이 TTY가 아닐 때 필요합니다 |

431 431 

432정리가 제거할 것을 미리 봅니다:432정리 시 제거될 항목을 미리 확인합니다.

433 433 

434```bash theme={null}434```bash theme={null}

435claude plugin prune --dry-run435claude plugin prune --dry-run

436```436```

437 437 

438Claude Code는 고아 의존성을 나열하고 `(dry run — nothing removed)`로 끝냅니다. 제거할 것이 없으면 `Nothing to prune`으로 시작하는 줄을 출력합니다.438Claude Code는 고아 상태의 의존성을 나열하고 `(dry run — nothing removed)`로 끝납니다. 제거할 항목이 없으면 `Nothing to prune`으로 시작하는 줄을 출력합니다.

439 439 

440`--dry-run` 없이 명령은 프롬프트에서 확인하거나 `-y`를 전달한 후에만 고아 의존성을 제거합니다.440`--dry-run` 없이 실행하면 명령은 확인 요청에서 확인하거나 `-y`를 전달한 경우에만 고아 상태의 의존성을 제거합니다.

441 441 

442프롬프트에서 어떻게 답하든 종료 코드는 `0`입니다.442확인 요청에 어떻게 응답하든 종료 코드는 `0`입니다.

443 443 

444`prune`이 하는 일은 터미널이 연결되어 있는지와 `-y`를 전달하는지에 따라 다릅니다:444`prune`의 동작은 터미널 연결 여부와 `-y` 전달 여부에 따라 달라집니다.

445 445 

446| 터미널 및 플래그 | 어떤 일이 발생하는지 |446| 터미널 및 플래그 | 동작 |

447| :- | :- |447| :- | :- |

448| 대화형 터미널, `-y` 없음 | 고아 의존성을 나열하고 `Remove? [y/N]`을 묻습니다 |448| 대화형 터미널, `-y` 없음 | 고아 상태의 의존성을 나열하고 `Remove? [y/N]`라고 묻습니다 |

449| 모든 터미널, `-y` | 제거하고 `Removed N auto-installed plugins: <names>`를 출력합니다 |449| 모든 터미널, `-y` 있음 | 의존성을 제거하고 `Removed N auto-installed plugins: <names>`를 출력합니다 |

450| TTY가 아닌 stdin 또는 stdout, `-y` 없음 | 목록을 출력하고 ``Not a TTY — run `claude plugin prune -y` to remove.``를 출력하고 아무것도 제거하지 않습니다 |450| TTY가 아닌 stdin 또는 stdout, `-y` 없음 | 목록과 ``Not a TTY — run `claude plugin prune -y` to remove.``를 출력하고 아무것도 제거하지 않습니다 |

451 451 

452### plugin eval452### plugin eval

453 453 

454플러그인의 [eval 케이스](https://code.claude.com/docs/ko/plugin-evals.md)를 실행하고 점수가 매겨진 결과를 보고합니다. Claude Code v2.1.269 이상 필요합니다.454플러그인의 [eval 케이스](https://code.claude.com/docs/ko/plugin-evals.md)를 실행하고 점수가 매겨진 결과를 보고합니다. Claude Code v2.1.269 이상이 필요합니다.

455 455 

456각 케이스는 프롬프트와 채점자입니다. Claude Code는 대상 플러그인만 로드된 격리된 세션에서 여러 번 실행하고 기본적으로 플러그인 없이도 실행하므로 보고서는 차이를 표시합니다.456각 케이스는 프롬프트와 채점기로 구성됩니다. Claude Code는 대상 플러그인만 로드된 격리된 세션에서 케이스를 여러 번 실행하며, 기본적으로 플러그인 없이도 실행하여 보고서에 그 차이가 표시되도록 합니다.

457 457 

458케이스 형식, 채점자, 결과, CI 사용법은 [플러그인을 evals로 테스트](https://code.claude.com/docs/ko/plugin-evals.md)를 참조하세요.458케이스 형식, 채점기, 결과, CI 사용법은 [eval로 플러그인 테스트](https://code.claude.com/docs/ko/plugin-evals.md)를 참조하세요.

459 459 

460```bash theme={null}460```bash theme={null}

461claude plugin eval [target] [options]461claude plugin eval [target] [options]

462```462```

463 463 

464선택적 `target`은 현재 디렉토리로 기본값이며 다음 형식 중 하나를 사용합니다:464선택적 `target`의 기본값은 현재 디렉터리이며, 다음 형식 중 하나를 받습니다.

465 465 

466* 플러그인 디렉토리466* 플러그인 디렉터리

467* 단일 `prompt.md` 또는 `case.yaml` 파일467* 단일 `prompt.md` 또는 `case.yaml` 파일

468* `name` 또는 `name@marketplace`로 설치된 플러그인468* `name` 또는 `name@marketplace` 형식의 설치된 플러그인

469* `name@skills-dir`469* `name@skills-dir`

470 470 

471`--tag`, `--allow-tools`, `--json` 앞에 target을 놓으세요. 이 옵션들 각각은 뒤따르는 단어를 값으로 사용하므로 이 옵션 중 하나 뒤에 작성된 target은 target 대신 태그, 도구 이름, 또는 JSON 출력 경로로 읽힙니다.471대상은 `--tag`, `--allow-tools`, `--json`보다 앞에 두세요. 이러한 옵션은 뒤따르는 단어를 값으로 받으므로, 이 중 하나의 뒤에 작성한 대상은 대상이 아니라 태그, 도구 이름 또는 JSON 출력 경로로 읽힙니다.

472 472 

473이 표는 대부분의 실행이 사용하는 옵션을 나열합니다. `--case`, `--tag`, `--output-dir`, `--report`, `--allow-real-servers`, `--keep-temp`, `--verbose`를 포함한 전체 집합은 `claude plugin eval --help`를 실행하세요.473이 표에는 대부분의 실행에서 사용하는 옵션이 나열되어 있습니다. `--case`, `--tag`, `--output-dir`, `--report`, `--allow-real-servers`, `--keep-temp`, `--verbose`를 포함한 전체 옵션을 보려면 `claude plugin eval --help`를 실행하세요.

474 474 

475| 옵션 | 설명 | 기본값 |475| 옵션 | 설명 | 기본값 |

476| :- | :- | :- |476| :- | :- | :- |

477| `--runs <n>` | 각 [arm](https://code.claude.com/docs/ko/plugin-evals.md#compare-against-a-no-plugin-baseline)의 케이스당 실행 | 각 케이스의 `runs`, 그 외 3 |477| `--runs <n>` | 각 [arm](https://code.claude.com/docs/ko/plugin-evals.md#compare-against-a-no-plugin-baseline)에서 케이스당 실행 횟수 | 각 케이스의 `runs`, 없으면 3 |

478| `-j, --concurrency <n>` | 동시에 실행할 에이전트 세션, 1\~8. 속도 제한을 공유합니다 | `1` |478| `-j, --concurrency <n>` | 동시에 실행할 에이전트 세션 수(1\~8). 세션들은 속도 제한을 공유합니다 | `1` |

479| `--model <model>` | 테스트 중인 에이전트의 모델 | 각 케이스의 `model`, 그 외 `ANTHROPIC_MODEL`이 설정되면 해당 값, 그 외 Claude Code의 기본값 |479| `--model <model>` | 테스트 대상 에이전트의 모델 | 각 케이스의 `model`, 없으면 설정된 경우 `ANTHROPIC_MODEL`, 그것도 없으면 Claude Code의 기본값 |

480| `--judge-model <model>` | `llm` 및 `baseline` 채점자의 모델 | [백그라운드 작업](https://code.claude.com/docs/ko/plugin-evals.md#grade-the-result)용 모델 |480| `--judge-model <model>` | `llm` 및 `baseline` 채점기의 모델 | [백그라운드 작업](https://code.claude.com/docs/ko/plugin-evals.md#grade-the-result)용 모델 |

481| `--ablation <mode>` | `none` 또는 `with-without`. [플러그인 없음 기준선에 대해 점수 매기기](https://code.claude.com/docs/ko/plugin-evals.md#compare-against-a-no-plugin-baseline)를 참조하세요 | 해당 섹션이 설명하는 대로 케이스당 결정됨 |481| `--ablation <mode>` | `none` 또는 `with-without`. [플러그인 없는 기준선과 비교하여 점수 매기기](https://code.claude.com/docs/ko/plugin-evals.md#compare-against-a-no-plugin-baseline)를 참조하세요 | 해당 섹션에서 설명하는 대로 케이스별로 결정 |

482| `--threshold <0..1>` | 케이스가 이 아래로 점수를 받으면 1로 종료 | `1.0` |482| `--threshold <0..1>` | 어떤 케이스라도 이 값보다 낮은 점수를 받으면 1로 종료 | `1.0` |

483| `--max-cost-usd <usd>` | 지출이 이에 도달하면 다음 실행 전에 중지하고 2로 종료하고 부분 결과를 보고합니다 | 제한 없음 |483| `--max-cost-usd <usd>` | 지출이 이 값에 도달하면 다음 실행 전에 중지하고, 2로 종료하며, 부분 결과를 보고 | 제한 없음 |

484| `--allow-tools <tools...>` | 읽기 전용 집합 이상의 도구를 부여합니다(예: `Bash`, `Write`, `Edit`, 또는 `"mcp__plugin_<plugin>_<server>__*"`). [도구 부여](https://code.claude.com/docs/ko/plugin-evals.md#grant-tools)를 참조하세요 | |484| `--allow-tools <tools...>` | 읽기 전용 세트 외의 도구(예: `Bash`, `Write`, `Edit`, `"mcp__plugin_<plugin>_<server>__*"`)를 허용합니다. [도구 허용](https://code.claude.com/docs/ko/plugin-evals.md#grant-tools)을 참조하세요 | |

485| `--scaffold` | 각 케이스의 [`scaffold_script`](https://code.claude.com/docs/ko/plugin-evals#add-setup-or-history-with-case-yaml)를 실행합니다 | 꺼짐 |485| `--scaffold` | 각 케이스의 [`scaffold_script`](https://code.claude.com/docs/ko/plugin-evals#add-setup-or-history-with-case-yaml)를 실행 | 꺼짐 |

486| `--trust-plugin` | 첫 실행 신뢰 프롬프트를 건너뜁니다(CI용). [실행이 접근할 수 있는 것](https://code.claude.com/docs/ko/plugin-evals.md#security)을 참조하세요 | 꺼짐 |486| `--trust-plugin` | CI용으로 첫 실행 시 신뢰 확인 요청을 건너뜁니다. [실행이 접근할 수 있는 항목](https://code.claude.com/docs/ko/plugin-evals.md#security)을 참조하세요 | 꺼짐 |

487| `--mocks <mode>` | `record` 또는 `off`. [MCP 서버 모의](https://code.claude.com/docs/ko/plugin-evals.md#mock-mcp-servers)를 참조하세요 | `record` |487| `--mocks <mode>` | `record` 또는 `off`. [MCP 서버 모의](https://code.claude.com/docs/ko/plugin-evals.md#mock-mcp-servers)를 참조하세요 | `record` |

488| `--eval-dir <dir>` | 케이스를 보유하는 플러그인 아래의 디렉토리 | 매니페스트의 `experimental.evals`, 그 외 `evals` |488| `--eval-dir <dir>` | 케이스가 들어 있는 플러그인 하위 디렉터리 | 매니페스트의 `experimental.evals`, 없으면 `evals` |

489| `--json [path]` | [결과 문서](https://code.claude.com/docs/ko/plugin-evals.md#json-result)를 stdout으로 출력하거나 `.json` 경로에 씁니다 | |489| `--json [path]` | [결과 문서](https://code.claude.com/docs/ko/plugin-evals.md#json-result)를 stdout에 출력하거나 `.json` 경로에 기록 | |

490| `--no-publish` | HTML 보고서를 로컬로 유지합니다 | |490| `--no-publish` | HTML 보고서를 로컬에 유지 | |

491 491 

492종료 코드는 실행이 어떻게 끝났는지 보고합니다. 파이프라인에서 이를 처리하려면 [CI에서 evals 실행](https://code.claude.com/docs/ko/plugin-evals.md#run-evals-in-ci)을 참조하세요.492종료 코드는 실행이 어떻게 끝났는지를 보고합니다. 파이프라인에서 이에 따라 동작하려면 [CI에서 eval 실행](https://code.claude.com/docs/ko/plugin-evals.md#run-evals-in-ci)을 참조하세요.

493 493 

494| 종료 코드 | 의미 |494| 종료 코드 | 의미 |

495| :- | :- |495| :- | :- |

496| `0` | 스위트가 통과했습니다: 모든 케이스가 임계값을 충족하고 다른 어떤 원인으로도 실행이 실패하지 않았습니다 |496| `0` | 스위트 통과: 모든 케이스가 임계값을 충족하고 실행을 실패시킨 다른 요인이 없음 |

497| `1` | 실패한 케이스, 로드 오류, 신뢰할 수 없는 플러그인 디렉토리, [API 오류로 끝난 실행](https://code.claude.com/docs/ko/plugin-evals.md#runs-ended-on-an-api-error), 또는 [CI에서 evals 실행](https://code.claude.com/docs/ko/plugin-evals.md#run-evals-in-ci)에 나열된 기타 원인 |497| `1` | 실패한 케이스, 로드 오류, 신뢰되지 않은 플러그인 디렉터리, [API 오류로 끝난](https://code.claude.com/docs/ko/plugin-evals.md#runs-ended-on-an-api-error) 실행, 또는 [CI에서 eval 실행](https://code.claude.com/docs/ko/plugin-evals.md#run-evals-in-ci)에 나열된 기타 원인 |

498| `2` | 부분 실행 |498| `2` | 부분 실행 |

499| `130` | 중단됨 |499| `130` | 중단됨 |

500| `143` | 종료됨 |500| `143` | 종료됨 |

501 501 

502### plugin eval init502### plugin eval init

503 503 

504현재 디렉토리의 플러그인에 대한 eval 스위트를 생성합니다. Claude Code v2.1.269 이상 필요합니다. [첫 eval 스위트 생성](https://code.claude.com/docs/ko/plugin-evals.md#create-your-first-eval-suite)을 참조하세요.504현재 디렉터리에 있는 플러그인의 eval 스위트를 생성합니다. Claude Code v2.1.269 이상이 필요합니다. [첫 eval 스위트 만들기](https://code.claude.com/docs/ko/plugin-evals.md#create-your-first-eval-suite)를 참조하세요.

505 505 

506```bash theme={null}506```bash theme={null}

507claude plugin eval init [name] [options]507claude plugin eval init [name] [options]

508```508```

509 509 

510플러그인의 루트 폴더(`.claude-plugin/plugin.json` 또는 skill의 `SKILL.md`를 보유한 디렉토리)에서 명령을 실행하세요. 의도적으로 다른 디렉토리에 스위트를 스캐폴드하려면 `--eval-dir`을 전달하세요.510플러그인의 루트 폴더, 즉 `.claude-plugin/plugin.json` 또는 스킬의 `SKILL.md`가 있는 디렉터리에서 명령을 실행하세요. 의도적으로 다른 디렉터리에 스위트를 생성하려면 `--eval-dir`을 전달합니다.

511 511 

512터미널에서 명령은 작성 인터뷰를 위해 대화형 Claude Code 세션을 엽니다. 인터뷰에서 Claude는 다음을 수행합니다:512터미널에서 이 명령은 작성 인터뷰를 위한 대화형 Claude Code 세션을 엽니다. 인터뷰에서 Claude는 다음을 수행합니다.

513 513 

5141. 플러그인을 읽습니다5141. 플러그인을 읽습니다

5152. 플러그인이 잘 해야 할 일을 묻습니다5152. 플러그인이 무엇을 잘해야 하는지 사용자에게 묻습니다

5163. 케이스와 채점자를 제안합니다5163. 케이스와 채점기를 제안합니다

5174. 케이스 파일을 씁니다5174. 케이스 파일을 작성합니다

5185. 케이스를 실행하고, 채점자가 사용자의 판단대로 점수를 매기는지 확인하기 위해 사용자와 함께 등급을 검토합니다5185. 케이스를 실행하고 사용자와 함께 점수를 검토하여 채점기가 사용자가 매길 점수와 같은 방식으로 채점하는지 확인합니다

519 519 

520`--bare`를 사용하거나 터미널 없이 실행하면 명령은 대신 빈 단일 케이스 템플릿을 씁니다. Claude가 Claude Code 세션 내부에서 명령을 실행하면 명령은 템플릿을 쓰는 대신 해당 세션이 따를 인터뷰 지침을 출력합니다.520`--bare`를 사용하거나 터미널이 없으면 명령은 대신 빈 단일 케이스 템플릿을 작성합니다. Claude가 Claude Code 세션 안에서 명령을 실행하면, 명령은 템플릿을 작성하는 대신 해당 세션이 따를 인터뷰 지침을 출력합니다.

521 521 

522선택적 `name`은 케이스 이름입니다. `--bare`를 사용하거나 터미널 없이 실행할 때 필요합니다. 명령이 해당 케이스에 대한 빈 템플릿을 쓰기 때문입니다. 케이스 이름은 문자 또는 숫자로 시작하고 문자, 숫자, `.`, `_`, `-`만 포함합니다. 모든 플랫폼에서 명령은 Windows가 저장할 수 없는 이름(예: `con` 또는 `.`로 끝나는 이름)도 거부합니다.522선택적 `name`은 케이스 이름입니다. `--bare`를 사용하거나 터미널이 없을 때는 명령이 해당 케이스의 빈 템플릿을 작성하므로 필수입니다. 케이스 이름은 문자 또는 숫자로 시작하며 문자, 숫자, `.`, `_`, `-`만 포함할 수 있습니다. 모든 플랫폼에서 명령은 `con`이나 `.`으로 끝나는 이름처럼 Windows에서 저장할 수 없는 이름도 거부합니다.

523 523 

524명령은 다음 옵션을 수락합니다:524이 명령은 다음 옵션을 받습니다.

525 525 

526| 옵션 | 설명 | 기본값 |526| 옵션 | 설명 | 기본값 |

527| :- | :- | :- |527| :- | :- | :- |

528| `--bare` | 인터뷰를 실행하는 대신 `<name>`에 대해 빈 `prompt.md` 및 `graders/criteria.md`를 씁니다 | |528| `--bare` | 인터뷰를 실행하는 대신 `<name>`에 대한 빈 `prompt.md`와 `graders/criteria.md`를 작성 | |

529| `-i, --interactive` | 인터뷰를 요구합니다. 템플릿을 쓰는 대신 터미널 없이 실패합니다 | |529| `-i, --interactive` | 인터뷰를 필수로 요구합니다. 터미널이 없으면 템플릿을 작성하는 대신 실패합니다 | |

530| `--eval-dir <dir>` | 케이스를 쓸 현재 디렉토리 아래의 디렉토리 | 매니페스트의 `experimental.evals`, 그 외 `evals` |530| `--eval-dir <dir>` | 케이스를 작성할 현재 디렉터리 하위 디렉터리 | 매니페스트의 `experimental.evals`, 없으면 `evals` |

531 531 

532### plugin tag532### plugin tag

533 533 

534플러그인 릴리스에 대해 `<name>--v<version>`이라는 주석이 달린 git 태그를 생성합니다. 태그 지정 전에 명령은 플러그인의 `plugin.json`과 이를 나열하는 마켓플레이스 항목이 버전에 동의하는지 확인합니다.534플러그인 릴리스를 위해 `<name>--v<version>`이라는 이름의 주석이 달린 git 태그를 생성합니다. 태그를 생성하기 전에 명령은 플러그인의 `plugin.json`과 해당 플러그인을 나열하는 모든 마켓플레이스 항목의 버전이 일치하는지 확인합니다.

535 535 

536릴리스를 태그할 시점은 [플러그인 게시](https://code.claude.com/docs/ko/plugins/publish.md)를 참조하세요.536릴리스에 태그를 지정할 시점은 [플러그인 게시](https://code.claude.com/docs/ko/plugins/publish.md)를 참조하세요.

537 537 

538```bash theme={null}538```bash theme={null}

539claude plugin tag [path] [options]539claude plugin tag [path] [options]

540```540```

541 541 

542`[path]`는 플러그인 디렉토리이며 현재 디렉토리로 기본값입니다. 명령은 해당 디렉토리에서 위로 올라가며 플러그인을 나열하는 `.claude-plugin/marketplace.json`을 찾아 마켓플레이스 항목을 찾습니다.542`[path]`는 플러그인 디렉터리이며 기본값은 현재 디렉터리입니다. 명령은 해당 디렉터리에서 상위로 올라가며 플러그인을 나열하는 `.claude-plugin/marketplace.json`을 찾아 마켓플레이스 항목을 확인합니다.

543 543 

544| 플래그 | 설명 |544| 플래그 | 설명 |

545| :- | :- |545| :- | :- |

546| `--push` | 생성 후 `--remote`에 태그를 푸시합니다 |546| `--push` | 태그를 생성한 후 `--remote`로 푸시 |

547| `--dry-run` | 태그를 생성하지 않고 태그 지정할 것을 출력합니다 |547| `--dry-run` | 태그를 생성하지 않고 태그가 지정될 내용을 출력 |

548| `-f, --force` | 더티 작업 트리 및 태그 이미 존재 확인을 건너뜁니다 |548| `-f, --force` | 작업 트리 변경 사항 확인과 태그 존재 여부 확인을 건너뜀 |

549| `-m, --message <msg>` | 태그 주석 메시지. `%s`는 버전을 나타냅니다. 기본값은 `<name> <version>` |549| `-m, --message <msg>` | 태그 주석 메시지. `%s`는 버전을 나타냅니다. 기본값은 `<name> <version>` |

550| `--remote <name>` | `--push`로 푸시할 원격. 기본값은 `origin` |550| `--remote <name>` | `--push`로 푸시할 원격. 기본값은 `origin` |

551 551 

552마켓플레이스 체크아웃의 플러그인에 대한 태그를 미리 봅니다:552마켓플레이스 체크아웃에서 플러그인의 태그를 미리 확인합니다.

553 553 

554```bash theme={null}554```bash theme={null}

555claude plugin tag plugins/formatter --dry-run555claude plugin tag plugins/formatter --dry-run

556```556```

557 557 

558Claude Code는 계획을 출력합니다:558Claude Code는 다음 계획을 출력합니다.

559 559 

560* 플러그인 이름560* 플러그인 이름

561* 버전과 어느 파일에서 왔는지561* 버전과 해당 버전을 가져온 파일

562* 일치하는 마켓플레이스 항목(있을 때)562* 일치하는 마켓플레이스 항목(있는 경우)

563* 태그 이름563* 태그 이름

564* 실행할 `git tag` 및 `git push` 명령564* 실행할 `git tag` 및 `git push` 명령

565 565 

566`--dry-run` 없이 Claude Code는 `Created tag formatter--v1.0.0`을 출력하고 `Pushed to origin` 또는 직접 실행할 푸시 명령을 출력합니다. 푸시가 실패하면 태그는 여전히 로컬로 생성되고 명령은 오류로 종료됩니다.566`--dry-run` 없이 실행하면 Claude Code는 `Created tag formatter--v1.0.0`를 출력하고, `Pushed to origin` 또는 직접 실행할 푸시 명령을 출력합니다. 푸시가 실패해도 태그는 로컬에 생성된 상태이며 명령은 오류와 함께 종료됩니다.

567 567 

568안전하게 태그 지정할 수 없을 때 명령은 `1`로 종료하고 이유를 출력합니다. 일반적인 이유는 다음과 같습니다:568안전하게 태그를 지정할 수 없으면 명령은 이유를 출력하고 `1`로 종료합니다. 일반적인 이유는 다음과 같습니다.

569 569 

570* `plugin.json` 또는 마켓플레이스 항목에 `version` 없음570* `plugin.json` 또는 마켓플레이스 항목에 `version`이 없음

571* 태그가 이미 존재함571* 태그가 이미 존재함

572* 작업 트리가 더티함572* 작업 트리에 커밋되지 않은 변경 사항이 있음

573 573 

574### plugin test574### plugin test

575 575 

576코드가 이벤트 핸들러를 등록하는 플러그인인 [mod](https://code.claude.com/docs/ko/plugins/mods/overview.md)의 테스트를 실행합니다. 이 명령에는 세션, 로그인, 네트워크가 필요하지 않습니다. 테스트 작성 방법은 [mod 테스트](https://code.claude.com/docs/ko/plugins/mods/test.md)를 참조하세요.576[mod](https://code.claude.com/docs/ko/plugins/mods/overview.md), 즉 코드에서 이벤트 핸들러를 등록하는 플러그인의 테스트를 실행합니다. 이 명령에는 세션, 로그인, 네트워크가 필요하지 않습니다. 테스트 작성 방법은 [mod 테스트](https://code.claude.com/docs/ko/plugins/mods/test.md)를 참조하세요.

577 577 

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

579claude plugin test [directory]579claude plugin test [directory]

580```580```

581 581 

582`[directory]`는 mod의 디렉토리이며 현재 디렉토리로 기본값입니다. 명령은 그 아래에서 이름이 `.test.ts` 또는 `.test.tsx`로 끝나는 모든 파일을 실행하고, 테스트가 실패하면 상태 1로 종료합니다.582`[directory]`는 mod의 디렉터리이며 기본값은 현재 디렉터리입니다. 명령은 그 하위에서 이름이 `.test.ts` 또는 `.test.tsx`로 끝나는 모든 파일을 실행하며, 테스트가 실패하면 상태 1로 종료합니다.

583 583 

584`./first-mod`에 있는 mod의 테스트를 실행합니다:584`./first-mod`에 있는 mod의 테스트를 실행합니다.

585 585 

586```bash theme={null}586```bash theme={null}

587claude plugin test ./first-mod587claude plugin test ./first-mod

589 589 

590### plugin validate590### plugin validate

591 591 

592플러그인 매니페스트, 마켓플레이스 매니페스트, 또는 디렉토리의 skills, agents, 명령을 검증하고 CI 작업이 처리할 수 있는 코드로 종료합니다. 생성, 테스트, 편집 워크플로는 [플러그인 생성](https://code.claude.com/docs/ko/plugins/create.md)을 참조하세요. 각 매니페스트에서 검증자가 확인하는 것은 [플러그인 매니페스트 참조](https://code.claude.com/docs/ko/plugins/manifest-reference.md) 및 [마켓플레이스 참조](https://code.claude.com/docs/ko/plugins/marketplace-reference.md)를 참조하세요.592플러그인 매니페스트, 마켓플레이스 매니페스트, 또는 디렉터리의 스킬, 에이전트, 명령을 검증하고 CI 작업이 활용할 수 있는 코드로 종료합니다. 생성, 테스트, 편집 워크플로는 [플러그인 만들기](https://code.claude.com/docs/ko/plugins/create.md)를 참조하세요. 검증기가 각 매니페스트에서 확인하는 내용은 [플러그인 매니페스트 참조](https://code.claude.com/docs/ko/plugins/manifest-reference.md)와 [마켓플레이스 참조](https://code.claude.com/docs/ko/plugins/marketplace-reference.md)를 참조하세요.

593 593 

594```bash theme={null}594```bash theme={null}

595claude plugin validate <path> [options]595claude plugin validate <path> [options]

597 597 

598| 플래그 | 설명 |598| 플래그 | 설명 |

599| :- | :- |599| :- | :- |

600| `--strict` | 경고를 오류로 취급하므로, 런타임이 허용하는 인식되지 않은 필드와 누락된 메타데이터로 인해 실행이 실패합니다 |600| `--strict` | 경고를 오류로 처리하여, 런타임이 허용하는 인식되지 않은 필드와 누락된 메타데이터도 실행을 실패시킵니다 |

601| `--json` | 검증 보고서를 동일한 종료 코드로 하나의 JSON 객체로 출력합니다. Claude Code v2.1.259 이상 필요 |601| `--json` | 동일한 종료 코드로 검증 보고서를 하나의 JSON 객체로 출력합니다. Claude Code v2.1.259 이상이 필요합니다 |

602 602 

603커밋하기 전에 플러그인을 검증합니다:603커밋하기 전에 플러그인을 검증합니다.

604 604 

605```bash theme={null}605```bash theme={null}

606claude plugin validate ./my-plugin --strict606claude plugin validate ./my-plugin --strict

607```607```

608 608 

609#### 디렉토리 검증609#### 디렉터리 검증

610 610 

611`<path>`는 [매니페스트 파일](#validate-a-manifest-file) 또는 디렉토리입니다. 디렉토리가 주어지면 Claude Code는 거기서 찾은 것으로 검증할 것을 선택합니다:611`<path>`는 [매니페스트 파일](#validate-a-manifest-file) 또는 디렉터리입니다. 디렉터리가 주어지면 Claude Code는 그 안에서 찾은 항목에 따라 검증할 대상을 선택합니다.

612 612 

613* `.claude-plugin/marketplace.json`(존재할 때)613* `.claude-plugin/marketplace.json`이 존재하는 경우 해당 파일

614* 그 외 `.claude-plugin/plugin.json`614* 그렇지 않으면 `.claude-plugin/plugin.json`

615* 그 외 컴포넌트 파일(디렉토리 이름으로 선택). 매니페스트 없이 컴포넌트 파일을 검증하려면 Claude Code v2.1.233 이상 필요:615* 그렇지 않으면 디렉터리 이름에 따라 선택된 구성 요소 파일. 매니페스트 없이 구성 요소 파일을 검증하려면 Claude Code v2.1.233 이상이 필요합니다.

616 * `skills`, `agents`, 또는 `commands`라는 디렉토리: 그 안의 파일616 * `skills`, `agents`, `commands`라는 이름의 디렉터리: 그 안의 파일

617 * `.claude`라는 디렉토리: 그 안의 `skills`, `agents`, `commands` 디렉토리617 * `.claude`라는 이름의 디렉터리: 그 안의 `skills`, `agents`, `commands` 디렉터리

618 * 다른 디렉토리: 그 `.claude` 아래의 이 세 디렉토리618 * 그 외의 디렉터리: 해당 디렉터리의 `.claude` 아래에 있는 이 세 디렉터리

619 619 

620디렉토리에 `.claude-plugin/marketplace.json`과 `.claude-plugin/plugin.json`이 모두 있으면 Claude Code는 마켓플레이스와 함께 플러그인의 매니페스트 및 컴포넌트 파일도 검증합니다. 이 기능은 Claude Code v2.1.289 이상이 필요합니다.620디렉터리에 `.claude-plugin/marketplace.json`과 `.claude-plugin/plugin.json`이 모두 있으면, Claude Code는 마켓플레이스와 함께 플러그인의 매니페스트 및 구성 요소 파일도 검증합니다. Claude Code v2.1.289 이상이 필요합니다.

621 621 

622Claude Code는 이름을 지정한 디렉토리 내의 심볼릭 링크를 따르지 않습니다. 링크가 어디에 있는지에 따라 어떤 일이 발생하는지 다릅니다:622Claude Code는 지정한 디렉터리 안의 심볼릭 링크를 따라가지 않습니다. 동작은 링크의 위치에 따라 달라집니다.

623 623 

624* **플러그인 또는 `.claude` 루트 아래의 연결된 `skills`, `agents`, 또는 `commands` 디렉토리**: Claude Code는 그 안의 아무것도 읽지 않았다고 경고합니다.624* **플러그인 또는 `.claude` 루트 아래에 링크된 `skills`, `agents`, `commands` 디렉터리**: Claude Code는 그 안의 어떤 것도 읽지 않았다고 경고합니다.

625* **`skills`, `agents`, 또는 `commands` 디렉토리 내의 연결된 항목**: Claude Code는 이를 건너뛰고 경고하며, 디렉토리당 세션이 로드할 건너뛴 항목 수를 나타냅니다.625* **`skills`, `agents`, `commands` 디렉터리 안에 링크된 항목**: Claude Code는 해당 항목을 건너뛰고, 디렉터리별로 세션이라면 로드했을 항목 중 몇 개를 건너뛰었는지 경고합니다.

626* **이름을 지정한 `skills`, `agents`, 또는 `commands` 디렉토리 자체가 심볼릭 링크이거나 그 부모 `.claude` 디렉토리가 심볼릭 링크**: Claude Code는 오류를 보고하고 그 안의 아무것도 확인하지 않습니다. 대신 실제 디렉토리의 이름을 지정하세요.626* **지정한 `skills`, `agents`, `commands` 디렉터리 자체가 심볼릭 링크이거나, 그 상위 `.claude` 디렉터리가 심볼릭 링크인 경우**: Claude Code는 오류를 보고하고 그 안의 어떤 것도 확인하지 않습니다. 대신 실제 디렉터리를 지정하세요.

627 627 

628몇 가지 파일은 검증 실행으로 읽지 않습니다:628일부 파일은 검증 실행에서 읽히지 않습니다.

629 629 

630* **플러그인 루트의 `SKILL.md`**: 플러그인 디렉토리에 대해 `claude plugin validate`를 실행할 때 Claude Code는 플러그인 루트의 `SKILL.md`를 확인하지 않습니다630* **플러그인 루트의 `SKILL.md`**: 플러그인 디렉터리를 대상으로 `claude plugin validate`를 실행하면 Claude Code는 플러그인 루트의 `SKILL.md`를 확인하지 않습니다

631* **플러그인 루트의 `CLAUDE.md`**: 플러그인 실행에서 Claude Code는 플러그인 루트의 `CLAUDE.md`에 대해서도 경고합니다631* **플러그인 루트의 `CLAUDE.md`**: 플러그인 실행에서 Claude Code는 플러그인 루트의 `CLAUDE.md`에 대해서도 경고합니다

632* **마켓플레이스 실행의 플러그인 파일**: 마켓플레이스 디렉토리에서 실행할 때 Claude Code는 마켓플레이스가 다른 디렉토리에 나열한 플러그인의 스킬, 에이전트, 명령, 훅 파일이나 그 플러그인에 번들된 MCP 서버 파일을 열지 않습니다. 이 파일의 오류를 찾으려면 각 플러그인 디렉토리를 검증하세요632* **마켓플레이스 실행에서의 플러그인 파일**: 마켓플레이스 디렉터리에서 실행하면 Claude Code는 마켓플레이스가 다른 디렉터리에서 나열하는 플러그인의 스킬, 에이전트, 명령, 훅 파일이나 이들이 번들하는 MCP 서버 파일을 열지 않습니다. 이러한 파일의 오류를 찾으려면 각 플러그인 디렉터리를 검증하세요

633 633 

634#### 매니페스트 파일 검증634#### 매니페스트 파일 검증

635 635 

636파일 이름이 `plugin.json` 또는 `marketplace.json`이 아니고 `.claude-plugin` 디렉토리에 있지 않으면, Claude Code는 파일의 필드를 보고 파일의 종류를 판단합니다. 다음 경우에는 파일을 마켓플레이스로 검증하고, 그 외에는 플러그인 매니페스트로 검증합니다:636파일 이름이 `plugin.json` 또는 `marketplace.json`이 아니고 `.claude-plugin` 디렉터리에 있지도 않으면, Claude Code는 필드를 보고 파일의 종류를 결정합니다. 다음 경우에는 파일을 마켓플레이스로 검증하고, 그 외에는 플러그인 매니페스트로 검증합니다.

637 637 

638* `plugins`가 배열임638* `plugins`가 배열인 경우

639* `plugins`와 `owner`가 모두 존재함639* `plugins`와 `owner`가 모두 있는 경우

640* 파일에 `owner`처럼 `marketplace.json`만 정의하는 필드가 있고, `author`처럼 `plugin.json`만 정의하는 필드는 없음640* 파일에 `owner`처럼 `marketplace.json`만 정의하는 필드가 있고, `author`처럼 `plugin.json`만 정의하는 필드는 없는 경우

641 641 

642검사를 직접 선택하려면 파일 이름을 `plugin.json` 또는 `marketplace.json`으로 지정하세요. Claude Code는 `.claude-plugin` 디렉토리에 있는 그 외의 파일은 플러그인 매니페스트로 검증합니다.642확인 항목을 직접 선택하려면 파일 이름을 `plugin.json` 또는 `marketplace.json`으로 지정하세요. Claude Code는 `.claude-plugin` 디렉터리에 있는 그 외의 파일을 플러그인 매니페스트로 검증합니다.

643 643 

644#### 출력 및 종료 코드644#### 출력 및 종료 코드

645 645 

646Claude Code는 검증한 파일, 경로가 있는 오류 및 경고, 판정 줄을 출력합니다. 종료 코드는 판정을 따릅니다:646Claude Code는 검증한 파일, 경로가 포함된 오류 및 경고, 그리고 판정 줄을 출력합니다. 종료 코드는 판정을 따릅니다.

647 647 

648| 종료 코드 | 판정 줄 | 의미 |648| 종료 코드 | 판정 줄 | 의미 |

649| :- | :- | :- |649| :- | :- | :- |

650| `0` | `Validation passed` 또는 `Validation passed with warnings` | 매니페스트가 로드됩니다. `--strict`를 사용하면 경고도 없습니다 |650| `0` | `Validation passed` 또는 `Validation passed with warnings` | 매니페스트가 로드됩니다. `--strict`를 사용하면 경고도 없습니다 |

651| `1` | `Validation failed` 또는 `Validation failed (--strict treats warnings as errors)` | 오류 또는 `--strict` 아래의 경고. [조언](#advice-on-the-readme)은 `--strict` 사용 여부와 관계없이 포함되지 않습니다 |651| `1` | `Validation failed` 또는 `Validation failed (--strict treats warnings as errors)` | 오류가 있거나, `--strict`에서 경고가 있습니다. [조언](#advice-on-the-readme)은 `--strict` 여부와 관계없이 포함되지 않습니다 |

652| `2` | `Unexpected error during validation: <reason>` | 검증자 자체가 실패했습니다(예: 읽을 수 없는 경로) |652| `2` | `Unexpected error during validation: <reason>` | 읽을 수 없는 경로 등으로 검증기 자체가 실패했습니다 |

653 653 

654`--json`을 사용하면 Claude Code는 보고서를 stdout에 다음 최상위 필드를 포함하는 하나의 JSON 객체로 씁니다:654`--json`을 사용하면 Claude Code는 다음 최상위 필드를 가진 하나의 JSON 객체로 보고서를 stdout에 기록합니다.

655 655 

656* `success`: 종료 코드가 제공하는 동일한 판정656* `success`: 종료 코드가 나타내는 것과 같은 판정

657* `strict`: 실행이 경고를 오류로 취급했는지 여부657* `strict`: 실행에서 경고를 오류로 처리했는지 여부

658* `target`: Claude Code가 검증한 해결된 경로658* `target`: Claude Code가 검증한 확인된 경로

659* `manifest`: 매니페스트의 자체 결과 또는 매니페스트 없는 실행의 경우 `null`659* `manifest`: 매니페스트 자체의 결과, 또는 매니페스트가 없는 실행의 경우 `null`

660* `contents`: 파일별 결과로, 각각 `file`의 이름을 지정하고 `errors`, `warnings`, `notes` 배열을 포함합니다. 오류, 경고, 메모가 없는 파일은 항목이 없으므로 보고할 것이 없으면 `contents`는 비어 있습니다. [`marketplace.json`과 `plugin.json`이 있는 디렉토리](#validate-a-directory)의 경우 `manifest`는 `marketplace.json` 결과이고 `plugin.json` 결과는 `contents`에 들어갑니다660* `contents`: 파일별 결과로, 각 항목은 `file`을 지정하고 `errors`, `warnings`, `notes` 배열을 포함합니다. 오류, 경고, 참고 사항이 없는 파일은 항목이 생성되지 않으므로, 보고할 내용이 없으면 `contents`는 비어 있습니다. [`marketplace.json`과 `plugin.json`이 있는 디렉터리](#validate-a-directory)의 경우 `manifest`는 `marketplace.json`의 결과이고 `plugin.json`의 결과는 `contents`에 들어갑니다

661 * `gatingHooks`: 작업을 거부할 수 있는 각 [mod](https://code.claude.com/docs/ko/plugins/mods/overview.md) 훅(예: `tool.call` 훅)에 [`.catch` 핸들러](https://code.claude.com/docs/ko/plugins/mods/events#handle-a-hook-that-fails)가 있는지 여부. 각 항목은 `module`, `pattern`, `hook`, `hasCatch`를 제공합니다. Claude Code v2.1.290 이상 필요661 * `gatingHooks`: `tool.call` 훅처럼 작업을 거부할 수 있는 각 [mod](https://code.claude.com/docs/ko/plugins/mods/overview.md) 훅에 [`.catch` 핸들러](https://code.claude.com/docs/ko/plugins/mods/events#handle-a-hook-that-fails)가 있는지 여부. 각 항목은 `module`, `pattern`, `hook`, `hasCatch`를 제공합니다. Claude Code v2.1.290 이상이 필요합니다

662* `advice`: 실행의 [조언](#advice-on-the-readme)으로, 각 항목은 README를 `file`로 지정하고 `message`와 붙여 넣을 `installLine`을 포함합니다. 조언이 없으면 비어 있습니다. Claude Code v2.1.295 이상 필요662* `advice`: 실행의 [조언](#advice-on-the-readme)으로, 각 항목은 README를 `file`로 지정하고 `message`와 붙여 넣을 `installLine`을 포함합니다. 조언이 없으면 비어 있습니다. Claude Code v2.1.295 이상이 필요합니다

663 663 

664종료 `2`에서 명령은 stdout에 아무것도 쓰지 않습니다. 오류 메시지는 stderr로 이동합니다.664종료 코드 `2`에서는 명령이 stdout에 아무것도 기록하지 않습니다. 오류 메시지는 stderr로 출력됩니다.

665 665 

666#### README에 대한 조언666#### README에 대한 조언

667 667 

668`claude plugin validate` 출력의 `Advice` 블록은 플러그인의 README에 마켓플레이스에서 플러그인을 설치하는 줄이 없다는 의미이며, 추가할 줄을 제공합니다. 조언은 오류나 경고가 아닙니다. `--strict` 사용 여부와 관계없이 판정 줄이나 종료 코드를 바꾸지 않습니다. Claude Code v2.1.295 이상이 필요합니다.668`claude plugin validate` 출력의 `Advice` 블록은 플러그인의 README에 마켓플레이스에서 플러그인을 설치하는 줄이 없다는 뜻이며, 추가할 줄을 제시합니다. 조언은 오류나 경고가 아닙니다. `--strict` 여부와 관계없이 판정 줄이나 종료 코드를 변경하지 않습니다. Claude Code v2.1.295 이상이 필요합니다.

669 669 

670예를 들어 `acme-tools` 마켓플레이스의 디렉토리를 검증하면 `deploy-helper` 플러그인에 대해 다음 조언이 출력됩니다:670예를 들어 `acme-tools` 마켓플레이스의 디렉터리를 검증하면 `deploy-helper` 플러그인에 대해 다음 조언이 출력됩니다.

671 671 

672```text theme={null}672```text theme={null}

673Validating marketplace manifest: /path/to/acme-tools/.claude-plugin/marketplace.json673Validating marketplace manifest: /path/to/acme-tools/.claude-plugin/marketplace.json

680✔ Validation passed680✔ Validation passed

681```681```

682 682 

683조언을 해소하려면 제안된 줄을 조언이 지정한 README에 붙여 넣은 다음, 셸에서 `claude plugin validate`를 다시 실행하세요. `Advice` 블록이 사라집니다.683조언을 해결하려면 제안된 줄을 지정된 README에 붙여 넣은 다음 셸에서 `claude plugin validate`를 다시 실행하세요. `Advice` 블록이 사라집니다.

684 684 

685제안된 줄에 자리 표시자 `<owner>/<repo>`가 있으면 그대로 붙여 넣어도 조언이 해소되지 않습니다. 먼저 실제 소스를 확인하세요:685제안된 줄에 자리 표시자 `<owner>/<repo>`가 포함되어 있으면, 그대로 붙여 넣어서는 조언이 해결되지 않습니다. 먼저 실제 소스를 확인하세요.

686 686 

687* **플러그인 자체 디렉토리를 검증한 경우**: 마켓플레이스가 자체 디렉토리 안의 디렉토리에서 플러그인을 나열하면 대신 그 마켓플레이스 디렉토리를 검증하세요. GitHub 저장소처럼 다른 곳에서 플러그인을 나열하면 `<owner>/<repo>`를 직접 채우세요687* **플러그인 자체의 디렉터리를 검증한 경우**: 마켓플레이스가 자신의 디렉터리 안에 있는 디렉터리에서 플러그인을 나열하는 경우에는 대신 해당 디렉터리를 검증합니다. 마켓플레이스가 GitHub 저장소 등 다른 위치에서 플러그인을 나열하는 경우에는 `<owner>/<repo>`를 직접 채워 넣으세요

688* **마켓플레이스 디렉토리를 검증한 경우**: Claude Code는 해당 디렉토리 최상위에 있는 `.git` 디렉토리의 `origin` 원격에서 소스를 채웁니다. 원격이 없는 경우처럼 그 원격을 사용할 수 없으면 `<owner>/<repo>`를 마켓플레이스의 소스로 직접 바꾸세요688* **마켓플레이스의 디렉터리를 검증한 경우**: Claude Code는 해당 디렉터리 최상위에 있는 `.git` 디렉터리의 `origin` 원격에서 소스를 채워 넣습니다. 원격이 없는 경우처럼 해당 원격을 사용할 수 없으면 `<owner>/<repo>`를 마켓플레이스의 소스로 직접 바꾸세요

689 689 

690이미 작성한 설치 줄은 같은 줄에서 `plugin install` 또는 그 짧은 형식인 `plugin i` 뒤에 다음 중 하나가 오면 인정됩니다. `/plugin` 표기와 `claude plugin` 표기 모두 인정됩니다:690이미 작성한 설치 줄은 `plugin install` 또는 그 짧은 형식인 `plugin i` 뒤에 같은 줄에서 다음 중 하나가 이어지면 인정됩니다. `/plugin`과 `claude plugin` 표기 모두 인정됩니다.

691 691 

692* `<plugin>@<marketplace>`(예: `/plugin install deploy-helper@acme-tools`)692* `<plugin>@<marketplace>`(예: `/plugin install deploy-helper@acme-tools`)

693* 플러그인 이름과 `--marketplace <source>`(예: `/plugin install deploy-helper --marketplace acme/tools`)693* 플러그인 이름과 `--marketplace <source>`(예: `/plugin install deploy-helper --marketplace acme/tools`)

Details

169 169 

170### 한 세션 동안 플러그인 로드170### 한 세션 동안 플러그인 로드

171 171 

172세 가지 방법으로 단일 세션 동안 플러그인을 로드할 수 있습니다: `--plugin-dir`으로 디스크의 디렉토리 또는 `.zip` 아카이브에서, `--plugin-url`로 URL에서, 또는 플래그를 추가할 수 없을 때 환경 변수에서. 각 플러그인은 해당 세션에만 로드되며, 설정에 아무것도 기록되지 않습니다. 세션 중에 플러그인의 파일을 편집하면 `/reload-plugins`를 실행하여 변경 사항을 로드합니다.172세 가지 방법으로 단일 세션 동안 플러그인을 로드할 수 있습니다:

173 

174* `--plugin-dir`으로 디스크의 디렉토리 또는 `.zip` 아카이브에서

175* `--plugin-url`로 URL에서

176* 플래그를 추가할 수 없을 때 환경 변수에서

177 

178세션 중에 플러그인의 파일을 편집하면 `/reload-plugins`를 실행하여 변경 사항을 로드합니다.

173 179 

174#### 디렉토리 또는 `.zip`에서 플러그인 로드180#### 디렉토리 또는 `.zip`에서 플러그인 로드

175 181 

Details

123 123 

124이러한 항목 소스는 git 계정이 필요하지 않습니다:124이러한 항목 소스는 git 계정이 필요하지 않습니다:

125 125 

126* **`archive`**: HTTPS를 통해 다운로드된 zip. 사용자는 `git`이나 계정이 필요하지 않으며 URL에 대한 네트워크 액세스만 필요합니다. Claude Code v2.1.224 이상이 필요합니다. 각 아카이브를 `sha256`으로 고정하여 Claude Code가 변경된 다운로드를 거부하도록 합니다. 다운로드와 함께 자격 증명을 보내려면 [아카이브 다운로드 인증](#authenticate-archive-downloads)을 참조하세요.126* **`archive`**: HTTPS를 통해 다운로드된 zip. 사용자는 `git`이나 계정이 필요하지 않으며 URL에 대한 네트워크 액세스만 필요합니다. 각 아카이브를 `sha256`으로 고정하여 Claude Code가 변경된 다운로드를 거부하도록 합니다. 다운로드와 함께 자격 증명을 보내려면 [아카이브 다운로드 인증](#authenticate-archive-downloads)을 참조하세요.

127* **공개 git 저장소**: Claude Code는 항목이 `https://` URL을 제공할 때 자격 증명 없이 HTTPS를 통해 공개 `url` 또는 `git-subdir` 소스를 복제합니다. `github` 소스 또는 `owner/repo`로 작성된 `git-subdir` 소스의 경우 GitHub SSH 키가 없는 사용자는 `CLAUDE_CODE_PLUGIN_PREFER_HTTPS=1`을 설정합니다.127* **공개 git 저장소**: Claude Code는 항목이 `https://` URL을 제공할 때 자격 증명 없이 HTTPS를 통해 공개 `url` 또는 `git-subdir` 소스를 복제합니다. `github` 소스 또는 `owner/repo`로 작성된 `git-subdir` 소스의 경우 GitHub SSH 키가 없는 사용자는 `CLAUDE_CODE_PLUGIN_PREFER_HTTPS=1`을 설정합니다.

128 128 

129SSH 키가 없는 머신의 셸에서 `claude plugin install`이 이 변수 없이 성공하더라도 안내에 `CLAUDE_CODE_PLUGIN_PREFER_HTTPS=1`을 유지하세요. `github` 소스의 경우 해당 명령은 자체적으로 HTTPS로 대체하며 `SSH not configured, cloning via HTTPS`를 출력할 수 있습니다. 세션 내 `/plugin`에서 실행한 설치와 플러그인 업데이트는 HTTPS로 대체하지 않으므로, 이 변수가 없으면 GitHub SSH 키가 없는 사용자에게는 실패합니다.129SSH 키가 없는 머신의 셸에서 `claude plugin install`이 이 변수 없이 성공하더라도 안내에 `CLAUDE_CODE_PLUGIN_PREFER_HTTPS=1`을 유지하세요. `github` 소스의 경우 해당 명령은 자체적으로 HTTPS로 대체하며 `SSH not configured, cloning via HTTPS`를 출력할 수 있습니다. 세션 내 `/plugin`에서 실행한 설치와 플러그인 업데이트는 HTTPS로 대체하지 않으므로, 이 변수가 없으면 GitHub SSH 키가 없는 사용자에게는 실패합니다.

Details

132플러그인의 설치 범위는 누가 플러그인을 얻는지, 어느 설정 파일에 활성화된 것으로 기록되는지를 결정합니다:132플러그인의 설치 범위는 누가 플러그인을 얻는지, 어느 설정 파일에 활성화된 것으로 기록되는지를 결정합니다:

133 133 

134* **User scope**: 플러그인이 이 머신의 모든 프로젝트에서 사용자에게 활성화됩니다. 항목은 `~/.claude/settings.json`의 `enabledPlugins`에 들어갑니다.134* **User scope**: 플러그인이 이 머신의 모든 프로젝트에서 사용자에게 활성화됩니다. 항목은 `~/.claude/settings.json`의 `enabledPlugins`에 들어갑니다.

135* **Project scope**: 플러그인이 이 저장소에서 작업하는 모든 사람에게 활성화됩니다. 항목은 커밋하는 `.claude/settings.json`에 들어갑니다. 해당 항목을 커밋하면 협력자에게 플러그인이 켜지지만 머신에 다운로드되지 않으므로, 각 협력자는 한 번 `claude plugin install <name>@<marketplace> --scope project`를 실행해야 합니다. [프로젝트 설정에서 활성화되었지만 설치되지 않음](https://code.claude.com/docs/ko/plugins/loading.md#enabled-in-project-settings-but-not-installed)을 참조하세요.135* **Project scope**: 플러그인이 이 저장소에서 작업하는 모든 사람에게 활성화됩니다. 항목은 커밋하는 `.claude/settings.json`에 들어갑니다. 해당 항목을 커밋하면 협력자에게 플러그인이 켜지지만 협력자의 머신에 다운로드되지는 않습니다. 각 협력자는 클론마다 한 번씩 `claude plugin install <name>@<marketplace> --scope project`도 실행해야 합니다. [프로젝트 설정에서 활성화되었지만 설치되지 않음](https://code.claude.com/docs/ko/plugins/loading.md#enabled-in-project-settings-but-not-installed)을 참조하세요.

136* **Local scope**: 플러그인이 이 저장소에서만 사용자에게 활성화됩니다. 항목은 `.claude/settings.local.json`에 들어갑니다.136* **Local scope**: 플러그인이 이 저장소에서만 사용자에게 활성화됩니다. 항목은 `.claude/settings.local.json`에 들어갑니다.

137 137 

138일부 플러그인은 [`defaultEnabled`](https://code.claude.com/docs/ko/plugins/manifest-reference#defaultenabled) 필드를 통해 작성자가 꺼진 상태로 시작하도록 설정합니다. 이러한 플러그인은 설치되지만 셸에서 `claude plugin enable <name>`을 사용하거나 세션의 `/plugin`의 **Installed** 탭에서 켤 때까지 꺼진 상태로 유지됩니다.138일부 플러그인은 [`defaultEnabled`](https://code.claude.com/docs/ko/plugins/manifest-reference#defaultenabled) 필드를 통해 작성자가 꺼진 상태로 시작하도록 설정합니다. 이러한 플러그인은 설치되지만 셸에서 `claude plugin enable <name>`을 사용하거나 세션의 `/plugin`의 **Installed** 탭에서 켤 때까지 꺼진 상태로 유지됩니다.

Details

173 173 

174프로젝트 활성화 플러그인을 머신에서 거부하려면 프로젝트 파일보다 우선 순위가 높은 `.claude/settings.local.json`에서 id를 `false`로 설정합니다.174프로젝트 활성화 플러그인을 머신에서 거부하려면 프로젝트 파일보다 우선 순위가 높은 `.claude/settings.local.json`에서 id를 `false`로 설정합니다.

175 175 

176### `--add-dir` 디렉토리에서 활성화되었지만 로드되지 않음

177 

178Claude Code는 추가된 디렉토리의 파일 중 하나에 있는 `true` 값의 `enabledPlugins` 항목을 해당 파일의 설정 소스가 켜져 있을 때만 읽습니다:

179 

180* **`.claude/settings.json`**: `project`

181* **`.claude/settings.local.json`**: `project` 및 `local`

182 

183세션이 로드하는 설정 소스를 확인합니다. 설정 소스는 [`--setting-sources`](https://code.claude.com/docs/ko/cli-reference#cli-flags)로 설정합니다. CLI에서는 `user`, `project`, `local`이 모두 기본적으로 켜져 있습니다.

184 

185예를 들어 셸에서 `claude --setting-sources user --add-dir ./shared`를 실행하면 Claude Code는 `./shared`의 두 파일 중 어느 것도 읽지 않습니다. `true`가 있는 파일에 해당하는 플래그를 전달합니다:

186 

187* **`settings.json`**: `--setting-sources user,project`

188* **`settings.local.json`**: `--setting-sources user,project,local`

189 

176### 프로젝트 설정에서 활성화되었지만 설치되지 않음190### 프로젝트 설정에서 활성화되었지만 설치되지 않음

177 191 

178플러그인의 유일한 `true`가 프로젝트의 `.claude/settings.json`에 있을 때 Claude Code는 [상대 경로 소스](https://code.claude.com/docs/ko/plugins/marketplace-reference.md#plugin-sources)가 있거나 [시드 디렉토리](https://code.claude.com/docs/ko/plugins/org.md#seed-containers-and-ci)가 이미 보유하지 않는 한 설치되지 않은 머신에 플러그인을 가져오지 않습니다. 대신 `/plugin` **Errors** 탭은 `Plugin "<name>" is enabled in project settings but isn't installed here`를 표시합니다.192기본적으로 프로젝트의 `.claude/settings.json`에서만 활성화된 플러그인은 머신에 설치하기 전까지 세션 시작 시 로드되지 않습니다. 머신에 마켓플레이스가 있으면 `/plugin` **Errors** 탭에 [`Plugin "<name>" is enabled in project settings but isn't installed here`](https://code.claude.com/docs/ko/plugins/troubleshooting#plugin-is-enabled-in-project-settings-but-isnt-installed-here) 또는 [`Plugin "<name>" not cached at <path>`](https://code.claude.com/docs/ko/plugins/troubleshooting#plugin-not-cached-at)가 표시됩니다.

193 

194> [!NOTE]

195>

196> 탭에 두 메시지 중 어느 것도 표시되지 않으면 설치하기 전에 [마켓플레이스를 추가](https://code.claude.com/docs/ko/plugins/install.md#add-a-marketplace)합니다. 마켓플레이스의 소스는 `.claude/settings.json`의 `extraKnownMarketplaces` 설정에서 찾거나 관리자에게 문의합니다.

197 

198설치하려면 `enabledPlugins`에 있는 플러그인의 키를 사용하여 프로젝트의 셸에서 다음을 실행합니다:

199 

200```shell theme={null}

201claude plugin install <name>@<marketplace> --scope project

202```

203 

204플러그인을 로드하려면 세션에서 `/reload-plugins`를 실행하거나 새 세션을 시작합니다. 각 복제본에서 설치를 반복하거나, `--scope user`를 사용하여 모든 프로젝트에 적용합니다.

205 

206다음의 경우에는 설치 없이 플러그인을 로드할 수 있습니다:

179 207 

180상대 경로 플러그인은 마켓플레이스 자체에서 로드되기 때문에 설치 기록이 필요하지 않습니다.208* **[시드 디렉토리](https://code.claude.com/docs/ko/plugins/org.md#seed-containers-and-ci)에 있는 경우**: 실행할 것이 없습니다

209* **로컬 경로에서 추가한 마켓플레이스에 [상대 경로](https://code.claude.com/docs/ko/plugins/marketplace-reference.md#plugin-sources)로 나열된 경우**: 플러그인이 세션 시작 시 로드되므로 실행할 것이 없습니다

210* **추가한 git 마켓플레이스의 `marketplace.json`에 `./plugins/formatter`와 같은 상대 경로로 나열된 경우**: `/reload-plugins`를 실행하여 현재 세션에서만 로드합니다. 한 번의 [비대화형 `-p` 실행](https://code.claude.com/docs/ko/headless)에서 로드하려면 [`CLAUDE_CODE_SYNC_PLUGIN_INSTALL=1`](https://code.claude.com/docs/ko/env-vars)을 설정합니다.

181 211 

182Claude Code는 다음 소스 중 하나가 이를 `true`로 설정할 때만 외부 소스가 있는 플러그인을 가져옵니다:212Claude Code는 다음 소스 중 하나가 이를 `true`로 설정할 때만 외부 소스가 있는 플러그인을 가져옵니다:

183 213 

Details

189 189 

190### `metadata`190### `metadata`

191 191 

192카탈로그 또는 자격 필드와 같은 자신의 데이터를 위한 자유 형식 객체. Claude Code는 이를 읽지 않습니다. Claude Code v2.1.222 이상이 필요합니다.192카탈로그 또는 자격 필드와 같은 자신의 데이터를 위한 자유 형식 객체. Claude Code는 이를 읽지 않습니다.

193 193 

194### 디렉토리 목록 필드194### 디렉토리 목록 필드

195 195 

394 394 

395매니페스트의 모든 컴포넌트 경로는 플러그인 루트에 상대적이며 `./`로 시작해야 합니다. `commands/foo.md`와 같은 경로는 유효성 검사에 실패합니다. `skills` 및 `mcpServers`는 각각 해당 규칙 외부의 한 형식을 허용합니다:395매니페스트의 모든 컴포넌트 경로는 플러그인 루트에 상대적이며 `./`로 시작해야 합니다. `commands/foo.md`와 같은 경로는 유효성 검사에 실패합니다. `skills` 및 `mcpServers`는 각각 해당 규칙 외부의 한 형식을 허용합니다:

396 396 

397* **`skills`**: 또한 `"."`를 허용합니다. `"."`와 `"./"`는 모두 플러그인 루트를 나타냅니다. v2.1.221 이전에는 `"."`가 매니페스트 유효성 검사에 실패했으므로 플러그인이 이전 버전에서 로드되어야 할 때 `"./"`를 사용하세요397* **`skills`**: 또한 `"."`를 허용합니다. `"."`와 `"./"`는 모두 플러그인 루트를 나타냅니다

398* **`mcpServers`**: 또한 `https://` 번들 URL을 허용합니다398* **`mcpServers`**: 또한 `https://` 번들 URL을 허용합니다

399 399 

400`experimental.evals`는 컴포넌트 경로가 아니므로 이 섹션의 규칙이 적용되지 않으며, 대신 `claude plugin eval`이 실행될 때 값을 확인합니다. 이 값은 `"quality/evals"`와 같이 플러그인 루트 아래의 디렉토리를 지정하며, `./` 접두사는 있어도 되고 없어도 됩니다. 배열을 사용하면 첫 번째 항목만 사용됩니다. 허용되는 값과 사용할 수 없는 값을 지정했을 때 어떻게 되는지는 [다른 eval 디렉토리 사용](https://code.claude.com/docs/ko/plugin-evals.md#use-a-different-eval-directory)을 참조하세요.400`experimental.evals`는 컴포넌트 경로가 아니므로 이 섹션의 규칙이 적용되지 않으며, 대신 `claude plugin eval`이 실행될 때 값을 확인합니다. 이 값은 `"quality/evals"`와 같이 플러그인 루트 아래의 디렉토리를 지정하며, `./` 접두사는 있어도 되고 없어도 됩니다. 배열을 사용하면 첫 번째 항목만 사용됩니다. 허용되는 값과 사용할 수 없는 값을 지정했을 때 어떻게 되는지는 [다른 eval 디렉토리 사용](https://code.claude.com/docs/ko/plugin-evals.md#use-a-different-eval-directory)을 참조하세요.

403 403 

404모든 컴포넌트 경로는 플러그인 루트 내부로 해결되어야 하며 존재해야 합니다. `claude plugin validate`는 모든 컴포넌트 키 아래의 경로를 확인합니다:404모든 컴포넌트 경로는 플러그인 루트 내부로 해결되어야 하며 존재해야 합니다. `claude plugin validate`는 모든 컴포넌트 키 아래의 경로를 확인합니다:

405 405 

406* **포함**: 플러그인 루트 외부로 해결되는 경로는 로드되지 않으며 `/plugin` **Errors** 탭에 `<component> path escapes plugin directory: <path>`가 표시됩니다. `..`를 포함하는 경로가 일반적인 경우이며 `claude plugin validate`는 오류 `Path contains ".." which could be a path traversal attempt`를 보고합니다406* **포함**: 플러그인 루트 외부로 해결되는 경로는 로드되지 않으며 `/plugin` **Errors** 탭에 `<component> path escapes plugin directory: <path>`가 표시됩니다. `..`를 포함하는 경로가 일반적인 경우이며 `claude plugin validate`는 오류 `Path contains ".." which could be a path traversal attempt`를 보고합니다. `mcpServers` 또는 `lspServers` 파일의 경우 [`path not read`](https://code.claude.com/docs/ko/errors#server-file-path-not-read) 메시지는 경로가 절대 경로이거나 `..`를 포함한다는 의미입니다

407* **존재**: 존재하지 않는 경로는 로드되지 않으며 `/plugin` **Errors** 탭에 `<component> path not found: <path>`가 표시됩니다. `claude plugin validate`는 오류 `Path not found`를 보고합니다407* **존재**: 존재하지 않는 경로는 로드되지 않으며 `/plugin` **Errors** 탭에 `<component> path not found: <path>`가 표시됩니다. `claude plugin validate`는 오류 `Path not found`를 보고합니다

408 408 

409`outputStyles`, `lspServers`, `monitors` 및 `themes` 경로의 경우 `claude plugin validate` 확인에는 Claude Code v2.1.283 이상이 필요합니다.409`outputStyles`, `lspServers`, `monitors` 및 `themes` 경로의 경우 `claude plugin validate` 확인에는 Claude Code v2.1.283 이상이 필요합니다.

Details

94| `dependencies` | array | 이 플러그인이 작동하려면 활성화되어 있어야 하는 플러그인입니다. 각 항목은 `"name"`, `"name@marketplace"` 또는 객체입니다. [플러그인 의존성](https://code.claude.com/docs/ko/plugins/dependencies.md)을 참조하십시오 |94| `dependencies` | array | 이 플러그인이 작동하려면 활성화되어 있어야 하는 플러그인입니다. 각 항목은 `"name"`, `"name@marketplace"` 또는 객체입니다. [플러그인 의존성](https://code.claude.com/docs/ko/plugins/dependencies.md)을 참조하십시오 |

95| `defaultEnabled` | boolean | 기본값은 `true`입니다. 사용자가 [`enabledPlugins`](https://code.claude.com/docs/ko/settings-reference#enabledplugins)에서 설정하지 않았을 때 플러그인이 활성화된 상태로 시작하는지 여부를 나타냅니다. 항목의 값이 `plugin.json`보다 우선합니다 |95| `defaultEnabled` | boolean | 기본값은 `true`입니다. 사용자가 [`enabledPlugins`](https://code.claude.com/docs/ko/settings-reference#enabledplugins)에서 설정하지 않았을 때 플러그인이 활성화된 상태로 시작하는지 여부를 나타냅니다. 항목의 값이 `plugin.json`보다 우선합니다 |

96| `displayName` | string | UI에 표시되는 사람이 읽을 수 있는 이름입니다. 항목과 플러그인의 `plugin.json` 모두 이 값을 설정하지 않으면 사용자에게는 플러그인의 `name`이 표시됩니다 |96| `displayName` | string | UI에 표시되는 사람이 읽을 수 있는 이름입니다. 항목과 플러그인의 `plugin.json` 모두 이 값을 설정하지 않으면 사용자에게는 플러그인의 `name`이 표시됩니다 |

97| `metadata` | object | 사용자 정의 필드를 위한 자유 형식 객체입니다. Claude Code는 이 값을 읽지 않습니다. Claude Code v2.1.222 이상이 필요합니다 |97| `metadata` | object | 사용자 정의 필드를 위한 자유 형식 객체입니다. Claude Code는 이 값을 읽지 않습니다 |

98| `headers` | object | Claude Code가 이 항목의 [아카이브](#archive-plugin-source)를 다운로드할 때 보내는 HTTP 헤더입니다. 여기에서 설정한 헤더는 마켓플레이스 소스의 [`headers`](#fields-by-type)에 있는 같은 이름의 헤더를 대체합니다. Claude Code v2.1.238 이상이 필요합니다 |98| `headers` | object | Claude Code가 이 항목의 [아카이브](#archive-plugin-source)를 다운로드할 때 보내는 HTTP 헤더입니다. 여기에서 설정한 헤더는 마켓플레이스 소스의 [`headers`](#fields-by-type)에 있는 같은 이름의 헤더를 대체합니다. Claude Code v2.1.238 이상이 필요합니다 |

99| `headersHelper` | string | 만료되는 자격 증명을 위해 이 항목의 아카이브 다운로드 헤더를 하나의 JSON 객체로 출력하는 명령입니다. 항목에서 [`"strict": false`](#strict-mode)도 설정해야 합니다. Claude Code v2.1.238 이상이 필요합니다. [아카이브 다운로드 인증](https://code.claude.com/docs/ko/plugins/host-marketplace.md#authenticate-archive-downloads)을 참조하십시오 |99| `headersHelper` | string | 만료되는 자격 증명을 위해 이 항목의 아카이브 다운로드 헤더를 하나의 JSON 객체로 출력하는 명령입니다. 항목에서 [`"strict": false`](#strict-mode)도 설정해야 합니다. Claude Code v2.1.238 이상이 필요합니다. [아카이브 다운로드 인증](https://code.claude.com/docs/ko/plugins/host-marketplace.md#authenticate-archive-downloads)을 참조하십시오 |

100 100 

142| `url` | `url`, `ref`, `sha` | URL로 지정하는 모든 git 저장소 |142| `url` | `url`, `ref`, `sha` | URL로 지정하는 모든 git 저장소 |

143| `git-subdir` | `url`, `path`, `ref`, `sha` | sparse checkout으로 가져오는 git 저장소의 하위 디렉터리 하나 |143| `git-subdir` | `url`, `path`, `ref`, `sha` | sparse checkout으로 가져오는 git 저장소의 하위 디렉터리 하나 |

144| `npm` | `package`, `version`, `registry` | npm 레지스트리 패키지 또는 tarball 링크로, 사용자의 npm 클라이언트로 가져오며 설치 스크립트를 실행하지 않고 압축을 풉니다 |144| `npm` | `package`, `version`, `registry` | npm 레지스트리 패키지 또는 tarball 링크로, 사용자의 npm 클라이언트로 가져오며 설치 스크립트를 실행하지 않고 압축을 풉니다 |

145| `archive` | `url`, `sha256` | HTTPS를 통한 Zip 아카이브입니다. Claude Code v2.1.224 이상이 필요합니다 |145| `archive` | `url`, `sha256` | HTTPS를 통한 Zip 아카이브 |

146| `command` | `command`, `timeout`, `mode` | Claude Code가 사용자 머신에서 실행하는 명령이 출력하는 디렉터리입니다. Claude Code v2.1.229 이상이 필요합니다 |146| `command` | `command`, `timeout`, `mode` | Claude Code가 사용자 머신에서 실행하는 명령이 출력하는 디렉터리입니다. Claude Code v2.1.229 이상이 필요합니다 |

147 147 

148`url`과 `github`라는 이름은 [마켓플레이스 소스](#marketplace-sources) 유형이기도 하며, 이 경우 `url`은 git 저장소가 아니라 `marketplace.json` 파일에 대한 직접 링크를 의미합니다. `git`은 마켓플레이스 소스로만 존재하고, `npm`은 양쪽 모두에 존재합니다. `git-subdir`, `archive`, `command`는 플러그인 소스로만 존재합니다.148`url`과 `github`라는 이름은 [마켓플레이스 소스](#marketplace-sources) 유형이기도 하며, 이 경우 `url`은 git 저장소가 아니라 `marketplace.json` 파일에 대한 직접 링크를 의미합니다. `git`은 마켓플레이스 소스로만 존재하고, `npm`은 양쪽 모두에 존재합니다. `git-subdir`, `archive`, `command`는 플러그인 소스로만 존재합니다.

Details

57* **mod가 켜져 있습니다.** 사용자는 플러그인 설정에서 허용하는 모든 마켓플레이스에서 mod가 포함된 플러그인을 설치하거나, `--plugin-dir`로 디렉터리에서 플러그인을 불러올 수 있습니다.57* **mod가 켜져 있습니다.** 사용자는 플러그인 설정에서 허용하는 모든 마켓플레이스에서 mod가 포함된 플러그인을 설치하거나, `--plugin-dir`로 디렉터리에서 플러그인을 불러올 수 있습니다.

58* **기본 제공 가드가 먼저 실행됩니다.** Claude Code는 사용자가 설치한 모든 mod보다 먼저 `sec-default@builtin`이라는 기본 제공 mod를 불러옵니다. 사용자는 이를 끌 수 없습니다. `/plugin`과 디버그 로그에는 `cc-plugin-sec-default`로 표시됩니다. 가드는 다음 중 하나에 해당하면 로드됩니다.58* **기본 제공 가드가 먼저 실행됩니다.** Claude Code는 사용자가 설치한 모든 mod보다 먼저 `sec-default@builtin`이라는 기본 제공 mod를 불러옵니다. 사용자는 이를 끌 수 없습니다. `/plugin`과 디버그 로그에는 `cc-plugin-sec-default`로 표시됩니다. 가드는 다음 중 하나에 해당하면 로드됩니다.

59 59 

60 * 머신에 관리형 설정이 있는 경우60 * 머신에 관리형 설정 또는 [`managed-mcp.json`](https://code.claude.com/docs/ko/managed-mcp#deploy-managed-mcp-json) 파일이 있는 경우

61 * 세션이 Team 또는 Enterprise 플랜의 [`/login` 자격 증명](https://code.claude.com/docs/ko/authentication#authentication-precedence)으로 실행되는 경우61 * 세션이 Team 또는 Enterprise 플랜의 [`/login` 자격 증명](https://code.claude.com/docs/ko/authentication#authentication-precedence)으로 실행되는 경우

62 62 

63 API 키로 인증하거나 Amazon Bedrock, Google Cloud의 Agent Platform 또는 Microsoft Foundry를 통해 인증하는 사용자는 관리형 설정이 있는 머신에서만 가드가 적용됩니다. 장기 [`CLAUDE_CODE_OAUTH_TOKEN`](https://code.claude.com/docs/ko/authentication#generate-a-long-lived-token)으로 실행되는 세션도 머신에 Team 또는 Enterprise 로그인이 저장되어 있더라도 해당 로그인으로 간주되지 않습니다.63 API 키로 인증하거나 Amazon Bedrock, Google Cloud의 Agent Platform 또는 Microsoft Foundry를 통해 인증하는 사용자는 관리형 설정 또는 `managed-mcp.json`이 있는 머신에서만 가드가 적용됩니다. 장기 [`CLAUDE_CODE_OAUTH_TOKEN`](https://code.claude.com/docs/ko/authentication#generate-a-long-lived-token)으로 실행되는 세션도 머신에 Team 또는 Enterprise 로그인이 저장되어 있더라도 해당 로그인으로 간주되지 않습니다.

64* **가드는 관리 대상을 보호합니다.** 사용자의 mod는 관리형 훅이 받는 내용이나 결정하는 내용, 시스템 프롬프트, 관리형 `CLAUDE.md` 및 기타 관리형 지침, 모든 mod가 설정으로 읽는 내용, 관리형 MCP 서버의 도구와 설명을 변경할 수 없습니다.64* **가드는 관리 대상을 보호합니다.** 사용자의 mod는 관리형 훅이 받는 내용이나 결정하는 내용, 시스템 프롬프트, 관리형 `CLAUDE.md` 및 기타 관리형 지침, 모든 mod가 설정으로 읽는 내용, 관리형 MCP 서버의 도구와 설명을 변경할 수 없습니다.

65* **관리 대상 밖에서는 사용자의 mod가 해당 사용자로서 동작합니다.** mod는 해당 사용자의 권한을 유지합니다. 여전히 파일을 읽고 쓰고, 프로세스를 시작하고, 네트워크 요청을 보낼 수 있습니다. 또한 도구 호출과 프롬프트를 다시 작성하고, 도구 호출을 거부하고, 인터페이스에 그릴 수 있습니다.65* **관리 대상 밖에서는 사용자의 mod가 해당 사용자로서 동작합니다.** mod는 해당 사용자의 권한을 유지합니다. 여전히 파일을 읽고 쓰고, 프로세스를 시작하고, 네트워크 요청을 보낼 수 있습니다. 또한 도구 호출과 프롬프트를 다시 작성하고, 도구 호출을 거부하고, 인터페이스에 그릴 수 있습니다.

66* **권한 규칙과 `PreToolUse` 훅이 사용자의 mod보다 우선합니다.** 가드가 로드된 환경에서는 기본적으로 규칙이 어느 설정 파일에 있든 사용자의 mod가 `deny` 규칙이 거부하는 호출이나 `ask` 규칙이 확인을 요청하는 호출을 승인할 수 없습니다. 또한 mod는 어떤 `PreToolUse` 훅이든 차단한 호출을 승인할 수 없습니다.66* **권한 규칙과 `PreToolUse` 훅이 사용자의 mod보다 우선합니다.** 가드가 로드된 환경에서는 기본적으로 규칙이 어느 설정 파일에 있든 사용자의 mod가 `deny` 규칙이 거부하는 호출이나 `ask` 규칙이 확인을 요청하는 호출을 승인할 수 없습니다. 또한 mod는 어떤 `PreToolUse` 훅이든 차단한 호출을 승인할 수 없습니다.

76 76 

77* **설정 훅은 계속 작동합니다.** 설정 파일과 플러그인의 `hooks/hooks.json`에 있는 command, HTTP, prompt, agent 훅은 mod와 함께 이전과 같이 실행됩니다.77* **설정 훅은 계속 작동합니다.** 설정 파일과 플러그인의 `hooks/hooks.json`에 있는 command, HTTP, prompt, agent 훅은 mod와 함께 이전과 같이 실행됩니다.

78* **가드가 로드된 환경에서는 deny 규칙이 우선합니다.** [`allowModsToOverrideDenyRules`](#set-options-on-the-built-in-guard)를 설정하지 않는 한, 사용자의 mod는 `deny` 규칙이 거부하는 호출을 승인할 수 없습니다.78* **가드가 로드된 환경에서는 deny 규칙이 우선합니다.** [`allowModsToOverrideDenyRules`](#set-options-on-the-built-in-guard)를 설정하지 않는 한, 사용자의 mod는 `deny` 규칙이 거부하는 호출을 승인할 수 없습니다.

79* **관리형 훅이 먼저 실행됩니다.** 관리형 설정의 `PreToolUse` 훅은 어떤 mod의 [`tool.call`](https://code.claude.com/docs/ko/plugins/mods/reference#tools) 훅보다도 먼저 실행되며, 해당 관리형 훅이 도구 호출을 차단하면 그 호출에 대해서는 어떤 mod의 `tool.call` 훅도 실행되지 않습니다. 호출이 진행되고 mod가 호출을 다시 작성하면 관리형 훅이 다시 작성된 호출에 대해 다시 실행되므로, 여전히 호출을 차단할 수 있습니다.79* **관리형 훅이 먼저 실행됩니다.** 관리형 설정의 `PreToolUse` 훅은 모든 mod의 [`tool.call`](https://code.claude.com/docs/ko/plugins/mods/reference#tools) 훅보다 먼저 실행되며, 해당 관리형 훅이 도구 호출을 차단하면 그 호출에 대해서는 어떤 mod의 `tool.call` 훅도 실행되지 않습니다. 호출이 진행되고 mod가 이를 재작성하면 관리형 훅이 재작성된 호출에 대해 다시 실행되므로, 기본적으로 관리형 훅은 여전히 해당 호출을 차단할 수 있습니다.

80 80 

81 다른 설정 파일과 플러그인의 `PreToolUse` 훅은 마지막 mod 이후에 실행됩니다. mod가 도구 호출에 직접 응답하면 도구는 실행되지 않으며 해당 훅도 실행되지 않습니다. [mod 실행 순서](https://code.claude.com/docs/ko/plugins/mods/events.md#the-order-mods-run-in)를 참조하십시오.81 다른 설정 파일과 플러그인의 `PreToolUse` 훅은 마지막 mod 이후에 실행됩니다. mod가 도구 호출에 직접 응답하면 도구는 실행되지 않으며 해당 훅도 실행되지 않습니다. [mod 실행 순서](https://code.claude.com/docs/ko/plugins/mods/events.md#the-order-mods-run-in)를 참조하십시오.

82* **네트워크 정책은 `$.http.fetch`에 적용됩니다.**82* **네트워크 정책은 `$.http.fetch`에 적용됩니다.**

260| 옵션 | 미설정 | `true` |260| 옵션 | 미설정 | `true` |

261| :- | :- | :- |261| :- | :- | :- |

262| `allowManagedModsOnly` | 사용자 자체 mod가 실행됨 | [조직의 mod](#install-your-organizations-mods)와 Claude Code에 기본 제공되는 mod만 훅을 실행합니다. 사용자가 설치했거나 `--plugin-dir`로 지정한 mod를 포함해 그 밖의 모든 mod는 Claude Code가 거부합니다. |262| `allowManagedModsOnly` | 사용자 자체 mod가 실행됨 | [조직의 mod](#install-your-organizations-mods)와 Claude Code에 기본 제공되는 mod만 훅을 실행합니다. 사용자가 설치했거나 `--plugin-dir`로 지정한 mod를 포함해 그 밖의 모든 mod는 Claude Code가 거부합니다. |

263| `allowModsToOverrideDenyRules` | 거부 규칙이 사용자 mod보다 우선함 | 도구 호출을 승인하는 사용자 mod가 `deny` 규칙이 거부한 호출을 승인할 수 있음 |263| `allowModsToOverrideDenyRules` | 거부 규칙이 사용자 mod보다 우선함 | 도구 호출을 승인하는 사용자 mod가 `deny` 규칙을 포함해 [기본적으로 유지되는 결과](https://code.claude.com/docs/ko/permissions.md#precedence-among-rules-hooks-and-mods) 대부분을 넘어서 호출을 승인할 수 있음 |

264 264 

265옵션의 적용 여부는 다음 규칙에 따라 결정됩니다.265옵션의 적용 여부는 다음 규칙에 따라 결정됩니다.

266 266 

350 350 

351* **목록이 기본값을 대체합니다**: 관리형 설정에서 `prependPlugins`를 설정하는 경우, 기본 제공 가드를 유지하려면 목록에 `sec-default@builtin`을 지정하십시오. 이 가드는 기본 제공되므로 `enabledPlugins` 항목이 필요하지 않습니다.351* **목록이 기본값을 대체합니다**: 관리형 설정에서 `prependPlugins`를 설정하는 경우, 기본 제공 가드를 유지하려면 목록에 `sec-default@builtin`을 지정하십시오. 이 가드는 기본 제공되므로 `enabledPlugins` 항목이 필요하지 않습니다.

352* **자체 ID는 조직의 것으로 간주되어야 합니다**: 관리형 설정에서 Claude Code는 플러그인이 조직 mod의 조건을 충족하지 않는 ID를 건너뜁니다352* **자체 ID는 조직의 것으로 간주되어야 합니다**: 관리형 설정에서 Claude Code는 플러그인이 조직 mod의 조건을 충족하지 않는 ID를 건너뜁니다

353* **저장소에서는 설정할 수 없습니다**: Claude Code는 두 설정을 관리형 설정에서 읽으며 저장소의 설정 파일에서는 절대 읽지 않습니다. 사용자는 관리형 설정이 없는 컴퓨터에서, 그리고 세션의 자격 증명이 Team 또는 Enterprise `/login`이 아닌 경우에만 `~/.claude/settings.json`에서 이를 설정하여 자신의 mod 순서를 정할 수 있습니다. 그 외의 경우 Claude Code는 사용자 설정의 두 키를 모두 무시합니다. 그곳의 목록은 기본 제공 가드를 추가하지도 제거하지도 않습니다.353* **저장소에서는 두 목록을 설정할 수 없습니다**: Claude Code는 저장소의 설정 파일에 있는 두 목록을 모두 무시하므로, 관리형 설정에서 설정하십시오.

354* **사용자는 자신의 mod 순서를 정하기 위해 이를 설정할 수 있습니다**: `~/.claude/settings.json`에서, 관리형 설정 또는 `managed-mcp.json` 파일이 없는 컴퓨터에서만, 그리고 세션의 자격 증명이 Team 또는 Enterprise `/login`이 아닌 경우에만 가능합니다. 그 외의 경우 Claude Code는 사용자 설정의 두 키를 모두 무시합니다. 그곳의 목록은 기본 제공 가드를 추가하지도 제거하지도 않습니다.

354 355 

355### 자체 mod로 정책 적용하기356### 자체 mod로 정책 적용하기

356 357 

Details

21 21 

22대화형 Claude Code 세션에서 원하는 mod를 설명하면 Claude가 작성합니다. Claude는 `plugin-authoring`이라는 내장 [스킬](https://code.claude.com/docs/ko/skills.md)을 기반으로 작업하며, 이 스킬은 mod를 작성할 위치, 현재 버전에서 사용할 수 있는 이벤트와 메서드, mod가 로드되는 방식을 Claude에게 알려 줍니다. mod를 요청하면 Claude가 스킬을 로드할 수 있으며, Claude Code 프롬프트에서 `/plugin-authoring`을 실행하여 직접 로드할 수도 있습니다.22대화형 Claude Code 세션에서 원하는 mod를 설명하면 Claude가 작성합니다. Claude는 `plugin-authoring`이라는 내장 [스킬](https://code.claude.com/docs/ko/skills.md)을 기반으로 작업하며, 이 스킬은 mod를 작성할 위치, 현재 버전에서 사용할 수 있는 이벤트와 메서드, mod가 로드되는 방식을 Claude에게 알려 줍니다. mod를 요청하면 Claude가 스킬을 로드할 수 있으며, Claude Code 프롬프트에서 `/plugin-authoring`을 실행하여 직접 로드할 수도 있습니다.

23 23 

24mod는 승인한 후에 실행됩니다. 단, [Claude가 작성한 mod를 로드할 수 없는 세션](#sessions-that-skip-the-approval)은 예외입니다.24`auto` 및 `bypassPermissions` [권한 모드](https://code.claude.com/docs/ko/permission-modes.md)에서는 턴이 끝날 때 mod가 실행될 수 있습니다. 그 외의 경우에는 승인한 후에 실행됩니다. 단, [Claude가 작성한 mod를 로드할 수 없는 세션](#sessions-that-skip-the-approval)은 예외입니다.

25 25 

26**1. mod 설명하기**26**1. mod 설명하기**

27 27 

33 33 

34**2. mod 승인하기**34**2. mod 승인하기**

35 35 

36Claude가 첫 번째 파일을 저장하면 Claude Code가 해당 세션에서 핫 리로딩을 활성화할지 묻습니다. 핫 리로딩은 이 세션에서 Claude가 작성한 mod를 실행하고 이후의 각 변경 사항을 반영합니다.36Claude가 첫 번째 파일을 저장하면 Claude Code가 해당 세션에서 핫 리로딩을 활성화할지 묻습니다. 핫 리로딩은 이 세션에서 Claude가 작성한 mod를 실행하고 이후의 각 변경 사항을 반영합니다. 질문이 표시되지 않으면 이 단계를 건너뛰십시오.

37 37 

38다음 중 하나를 선택합니다.38다음 중 하나를 선택합니다.

39 39 

40* **Enable for this session**: 세션의 mod 폴더에 있는 mod가 턴이 끝날 때 로드되고, mod를 변경하는 각 턴이 끝날 때마다 다시 로드됩니다. 이 선택은 세션을 재개한 후를 포함하여 세션 동안 유지됩니다.40* **Turn them on**: 세션의 mod 폴더에 있는 mod가 턴이 끝날 때 로드되고, mod를 변경하는 각 턴이 끝날 때마다 다시 로드됩니다. 이 선택은 세션을 재개한 후를 포함하여 세션 동안 유지됩니다.

41* **Not now**: 지금은 아무것도 로드되지 않습니다. 파일은 Claude가 작성한 위치에 그대로 남아 있으며, 해당 세션이 다음에 시작될 때 mod가 로드됩니다. mod가 로드되지 않도록 하려면 해당 디렉터리를 삭제하십시오.41* **Not now**: 지금은 아무것도 로드되지 않습니다. 파일은 Claude가 작성한 위치에 그대로 남아 있으며, 해당 세션이 다음에 시작될 때 mod가 로드됩니다. mod가 로드되지 않도록 하려면 해당 디렉터리를 삭제하십시오.

42 42 

43**3. mod가 로드되었는지 확인하기**43**3. mod가 로드되었는지 확인하기**

59 59 

60### Claude가 작성한 mod를 로드할 수 없는 세션60### Claude가 작성한 mod를 로드할 수 없는 세션

61 61 

62Claude가 작성한 mod는 mod 실행이 허용된 신뢰할 수 있는 워크스페이스에서 사용자가 승인한 후에만 로드됩니다. 다음 세션에서는 로드되지 않습니다.62Claude가 작성한 mod는 mod 실행이 허용된 신뢰할 수 있는 워크스페이스에서 로드되며, 확인을 요청하는 모드에서는 사용자가 승인한 후에 로드됩니다. 다음 세션에서는 로드되지 않습니다.

63 63 

64* **승인할 사람이 없는 경우**: `claude -p` 실행이나 [`dontAsk` 모드](https://code.claude.com/docs/ko/permission-modes)처럼 세션에서 프롬프트를 표시할 수 없는 경우64* **승인할 사람이 없는 경우**: `auto` 및 `bypassPermissions` 모드 이외의 모드에서 `claude -p`를 실행하는 경우나 [`dontAsk` 모드](https://code.claude.com/docs/ko/permission-modes)처럼 세션에서 프롬프트를 표시할 수 없는 경우

65* **워크스페이스를 신뢰하지 않는 경우**: 해당 디렉터리에 대한 신뢰 프롬프트를 수락하지 않은 경우65* **워크스페이스를 신뢰하지 않는 경우**: 해당 디렉터리에 대한 신뢰 프롬프트를 수락하지 않은 경우

66* **mod가 비활성화된 경우**: `--safe-mode` 또는 `--bare`로 시작했거나, `disableAllHooks`를 설정했거나, 조직의 [관리형 설정에서 차단한](https://code.claude.com/docs/ko/plugins/mods/admin.md#choose-how-much-to-allow) 경우66* **mod가 비활성화된 경우**: `--safe-mode` 또는 `--bare`로 시작했거나, `disableAllHooks`를 설정했거나, 조직의 [관리형 설정에서 차단한](https://code.claude.com/docs/ko/plugins/mods/admin.md#choose-how-much-to-allow) 경우

67 67 

Details

328 328 

329어떤 mod가 이 이벤트를 받는지와 Claude Code 버전을 확인하세요.329어떤 mod가 이 이벤트를 받는지와 Claude Code 버전을 확인하세요.

330 330 

331* **기본 제공 가드**: 관리형 설정이 있거나 Team 또는 Enterprise [`/login`](https://code.claude.com/docs/ko/authentication#authentication-precedence)이 세션의 자격 증명인 경우, [기본 제공 가드](https://code.claude.com/docs/ko/plugins/mods/admin.md#know-what-happens-by-default)는 설치했거나 `--plugin-dir`로 로드한 mod에서 이 훅을 건너뛸 수 있습니다. 확인하려면 [디버그 로그](https://code.claude.com/docs/ko/plugins/mods/troubleshoot.md#read-the-debug-log)에서 `settings.read bypassed by cc-plugin-sec-default`를 검색하세요. 해당 텍스트가 포함된 줄에 해당 mod의 이름이 있으면 조직의 관리자에게 [해당 mod를 조직의 mod 중 하나로 설치](https://code.claude.com/docs/ko/plugins/mods/admin.md#install-your-organizations-mods)해 달라고 요청하세요.331* **기본 제공 가드**: [기본 제공 가드](https://code.claude.com/docs/ko/plugins/mods/admin.md#know-what-happens-by-default)가 로드되는 환경에서는 설치했거나 `--plugin-dir`로 로드한 mod에서 이 훅을 건너뛸 수 있습니다. 확인하려면 [디버그 로그](https://code.claude.com/docs/ko/plugins/mods/troubleshoot.md#read-the-debug-log)에서 `settings.read bypassed by cc-plugin-sec-default`를 검색하세요. 해당 텍스트가 포함된 줄에 해당 mod의 이름이 있으면 조직의 관리자에게 [해당 mod를 조직의 mod 중 하나로 설치](https://code.claude.com/docs/ko/plugins/mods/admin.md#install-your-organizations-mods)해 달라고 요청하세요.

332* **버전**: Claude Code 자체의 읽기에서 이 이벤트가 발생하는 것과 `e.layers` 필드에는 Claude Code v2.1.304 이상이 필요합니다.332* **버전**: Claude Code 자체의 읽기에서 이 이벤트가 발생하는 것과 `e.layers` 필드에는 Claude Code v2.1.304 이상이 필요합니다.

333 333 

334#### `settings.read` 훅이 받는 값334#### `settings.read` 훅이 받는 값

Details

78 78 

79mod는 샌드박스에서 실행되지 않습니다. [샌드박싱](https://code.claude.com/docs/ko/sandboxing.md)을 켜면 샌드박스는 Claude가 실행하는 Bash 명령을 격리하지만, mod가 시작하는 프로세스는 샌드박스 밖에서 실행됩니다.79mod는 샌드박스에서 실행되지 않습니다. [샌드박싱](https://code.claude.com/docs/ko/sandboxing.md)을 켜면 샌드박스는 Claude가 실행하는 Bash 명령을 격리하지만, mod가 시작하는 프로세스는 샌드박스 밖에서 실행됩니다.

80 80 

81[관리형 설정](https://code.claude.com/docs/ko/settings.md#check-what-your-organization-enforces)이 있거나 Team 또는 Enterprise [`/login`](https://code.claude.com/docs/ko/authentication#authentication-precedence)이 세션의 자격 증명인 경우, 기본적으로 mod의 승인은 사용자의 `ask` 규칙이나 `PreToolUse` 훅을 넘어 호출을 통과시키지 않습니다. 둘 다 없으면 mod는 `ask` 규칙이 확인을 요청할 호출이나 사용자의 `PreToolUse` 훅이 차단한 호출을 승인할 수 있습니다. mod가 `deny` 규칙이 거부하는 호출도 승인할 수 있는 경우를 확인하려면 [훅으로 권한 확장하기](https://code.claude.com/docs/ko/permissions.md#precedence-among-rules-hooks-and-mods)를 참조하십시오.81[기본 제공 가드](https://code.claude.com/docs/ko/plugins/mods/admin.md#know-what-happens-by-default)가 막지 않는 한, mod는 사용자의 `deny` 또는 `ask` 규칙이나 `PreToolUse` 훅이 중단시킬 [많은 도구 호출](https://code.claude.com/docs/ko/permissions.md#precedence-among-rules-hooks-and-mods)을 승인할 수 있습니다. 가드가 로드되어 있으면 기본적으로 사용자의 mod는 이렇게 할 수 없습니다. 로컬 터미널 세션에서 `/plugin`의 **Installed** 탭에 `cc-plugin-sec-default`가 표시되면 가드가 로드된 것입니다.

82 82 

83mod는 Claude Code 인터페이스의 많은 부분을 다시 꾸밀 수 있지만, 권한 프롬프트는 변경할 수 없습니다. 프롬프트에 표시되는 내용은 mod가 바꿀 수 없습니다.83mod는 Claude Code 인터페이스의 많은 부분을 다시 꾸밀 수 있지만, 권한 프롬프트는 변경할 수 없습니다. 프롬프트에 표시되는 내용은 mod가 바꿀 수 없습니다.

84 84 

Details

39| `next.origin` | 이벤트를 발생시킨 주체의 `{ plugin, tier }`입니다. Claude Code 자체는 `{ plugin: 'engine', tier: 'core' }`입니다. mod의 `tier`는 [mod 실행 순서](https://code.claude.com/docs/ko/plugins/mods/events.md#the-order-mods-run-in)에서의 우선순위 그룹으로, `prepend`, `user`, `append`, `builtin` 중 하나입니다. |39| `next.origin` | 이벤트를 발생시킨 주체의 `{ plugin, tier }`입니다. Claude Code 자체는 `{ plugin: 'engine', tier: 'core' }`입니다. mod의 `tier`는 [mod 실행 순서](https://code.claude.com/docs/ko/plugins/mods/events.md#the-order-mods-run-in)에서의 우선순위 그룹으로, `prepend`, `user`, `append`, `builtin` 중 하나입니다. |

40| `next.budget` | 밀리초 단위의 훅 시간 제한입니다. `next.budget.ms`는 전체 제한이고, `next.budget.remainingMs`는 현재 남은 시간입니다 |40| `next.budget` | 밀리초 단위의 훅 시간 제한입니다. `next.budget.ms`는 전체 제한이고, `next.budget.remainingMs`는 현재 남은 시간입니다 |

41| `next.to(e, tier)` | 이후의 tier인 `append`, `builtin`, `core` 중 하나로 건너뜁니다. `next.to(e, 'append')`는 사용자가 설치한 mod를 건너뜁니다. `prependPlugins` 또는 `appendPlugins`에 있는 mod만 이를 호출할 수 있습니다. |41| `next.to(e, tier)` | 이후의 tier인 `append`, `builtin`, `core` 중 하나로 건너뜁니다. `next.to(e, 'append')`는 사용자가 설치한 mod를 건너뜁니다. `prependPlugins` 또는 `appendPlugins`에 있는 mod만 이를 호출할 수 있습니다. |

42| `next.error` | `.catch` 핸들러에서만 사용할 수 있습니다. 훅이 실패한 경우 `kind`는 `throw` 또는 `timeout`이고, `message`는 오류의 텍스트입니다. 이벤트가 해당 훅의 mods API 호출 내부 또는 훅 외부에 있는 mod 코드의 mods API 호출 내부에서 발생하여 훅을 건너뛴 경우 `kind`는 `re-entry`입니다. `re-entry`는 Claude Code v2.1.292 이상이 필요합니다. |42| `next.error` | `.catch` 핸들러에서만 사용할 수 있습니다. `kind`는 `throw` 또는 `timeout`이고, `message`는 오류의 텍스트입니다. |

43| `next.error.cause` | `kind`가 `re-entry`인 경우에만 설정됩니다. `tool.call` 또는 [`PreToolUse`](https://code.claude.com/docs/ko/hooks#pretooluse) 훅이 이벤트가 발생한 mods API 호출을 변경했거나, `agent.spawn` 훅이 해당 호출로 시작된 에이전트를 변경한 경우 `rewritten`입니다. 다른 mod가 mods API에 추가한 메서드가 해당 이벤트를 발생시킨 경우, `rewritten`에도 해당하지 않는 한 `lent`입니다. `lent`는 Claude Code v2.1.292 이상, `rewritten`은 v2.1.300 이상이 필요합니다. |

44| `next.called` | `.catch` 핸들러에서만 사용할 수 있습니다. 훅이 `next`를 호출한 경우 `true`입니다. |43| `next.called` | `.catch` 핸들러에서만 사용할 수 있습니다. 훅이 `next`를 호출한 경우 `true`입니다. |

45 44 

46## 이벤트45## 이벤트

252| [`AbovePrompt`](https://code.claude.com/docs/ko/plugins/mods/interface#pick-where-to-draw) | `hasSurvey`, `isWorking`, `maxRows`, `bodyColumns`, `scroll`, `view` | 단일 인스턴스 | 터미널, Desktop |251| [`AbovePrompt`](https://code.claude.com/docs/ko/plugins/mods/interface#pick-where-to-draw) | `hasSurvey`, `isWorking`, `maxRows`, `bodyColumns`, `scroll`, `view` | 단일 인스턴스 | 터미널, Desktop |

253| [`Placed`](https://code.claude.com/docs/ko/plugins/mods/interface#place-a-row-in-the-transcript) | `id`, `plugin`, `onScreen` | `$.ui.place`가 반환한 `requestId` | 터미널 |252| [`Placed`](https://code.claude.com/docs/ko/plugins/mods/interface#place-a-row-in-the-transcript) | `id`, `plugin`, `onScreen` | `$.ui.place`가 반환한 `requestId` | 터미널 |

254| [`Backdrop`](https://code.claude.com/docs/ko/plugins/mods/interface#put-a-backdrop-behind-the-conversation) | `id`, `plugin`, `glass`, `colorScheme` | `backdrop` | `desktop` 및 `mobile` 사용 환경. Desktop 또는 모바일 앱이 배경 그리기를 요청할 때 훅이 실행됩니다. |253| [`Backdrop`](https://code.claude.com/docs/ko/plugins/mods/interface#put-a-backdrop-behind-the-conversation) | `id`, `plugin`, `glass`, `colorScheme` | `backdrop` | `desktop` 및 `mobile` 사용 환경. Desktop 또는 모바일 앱이 배경 그리기를 요청할 때 훅이 실행됩니다. |

255| `UserMessage` | `text`, `origin`, `isExpanded`, 그리고 origin에 따라 `task` 또는 `from` | 메시지 id | 터미널, Desktop, VS Code |254| `UserMessage` | `text`, `origin`, `isExpanded`, 그리고 origin에 따라 `task` 또는 `from` | 그려진 행의 id | 터미널, Desktop, VS Code |

256| `AssistantMessage` | 응답의 텍스트 | 메시지 id | 터미널, Desktop, VS Code |255| `AssistantMessage` | 응답의 텍스트 | 그려진 행의 id | 터미널, Desktop, VS Code |

257| `ToolUse`, `ToolResult`, `ToolGroup` | 도구의 이름, 입력, 결과 | 도구 호출 id | 터미널, Desktop, VS Code |256| `ToolUse`, `ToolResult`, `ToolGroup` | 도구의 이름, 입력, 결과 | 도구 호출 id | 터미널, Desktop, VS Code |

258| `CommandOutput` | `command`, `text` | 메시지 id | 터미널, Desktop |257| `CommandOutput` | `command`, `text` | 그려진 행의 id | 터미널, Desktop |

259| [`AskUserQuestion`](https://code.claude.com/docs/ko/plugins/mods/interface#change-what-claude-code-already-draws) | 질문과 선택지 | 도구 호출 id | 터미널, Desktop, VS Code |258| [`AskUserQuestion`](https://code.claude.com/docs/ko/plugins/mods/interface#change-what-claude-code-already-draws) | 질문과 선택지 | 도구 호출 id | 터미널, Desktop, VS Code |

260| `ToolProgress` | `kind` | 도구 호출 id | 터미널 |259| `ToolProgress` | `kind` | 도구 호출 id | 터미널 |

261| [`Spinner`](https://code.claude.com/docs/ko/plugins/mods/interface#change-what-claude-code-already-draws) | `word`, `message`, `suffix`, `mode` | 에이전트 id | 터미널, Desktop, VS Code |260| [`Spinner`](https://code.claude.com/docs/ko/plugins/mods/interface#change-what-claude-code-already-draws) | `word`, `message`, `suffix`, `mode` | 에이전트 id | 터미널, Desktop, VS Code |

262| `TurnDuration` | `word`, `durationMs` | 메시지 id | 터미널 |261| `TurnDuration` | `word`, `durationMs` | 그려진 행의 id | 터미널 |

263| `InfoNotice` | `text`, `command` | 메시지 id | 터미널 |262| `InfoNotice` | `text`, `command` | 앞에 `notice:`가 붙은 알림의 `text` | 터미널 |

264| `SessionMode` | `modes` | 단일 인스턴스 | 터미널, Desktop |263| `SessionMode` | `modes` | 단일 인스턴스 | 터미널, Desktop |

265| `PromptHint` | `isDraft`, `isWorking`, `hint` | 단일 인스턴스 | 터미널, Desktop |264| `PromptHint` | `isDraft`, `isWorking`, `hint` | 단일 인스턴스 | 터미널, Desktop |

266 265 

424| :- | :- | :- |423| :- | :- | :- |

425| `CLAUDE_CODE_PLUGIN_DIRS` | 환경, 또는 `~/.claude/settings.json`의 `env` | 플래그를 전달할 수 없는 앱을 위해 `--plugin-dir`와 같은 방식으로 로드할 플러그인 디렉터리입니다. 절대 경로를 `:`로 구분하며, Windows에서는 `;`로 구분합니다. |424| `CLAUDE_CODE_PLUGIN_DIRS` | 환경, 또는 `~/.claude/settings.json`의 `env` | 플래그를 전달할 수 없는 앱을 위해 `--plugin-dir`와 같은 방식으로 로드할 플러그인 디렉터리입니다. 절대 경로를 `:`로 구분하며, Windows에서는 `;`로 구분합니다. |

426| `CLAUDE_CODE_PLUGIN_DIR_WATCH` | 환경 | `1`로 설정하면 장시간 실행되는 비대화형 세션이 저장 시 `--plugin-dir` mod를 다시 로드합니다 |425| `CLAUDE_CODE_PLUGIN_DIR_WATCH` | 환경 | `1`로 설정하면 장시간 실행되는 비대화형 세션이 저장 시 `--plugin-dir` mod를 다시 로드합니다 |

427| `prependPlugins`, `appendPlugins` | 관리형 설정. 관리형 설정이 없는 머신에서, 자격 증명이 Team 또는 Enterprise `/login`이 아닌 세션에서만 사용자 설정. | `acme-guard@acme-tools`와 같은 플러그인 ID 목록입니다. `prependPlugins`의 mod는 사용자가 설치한 모든 mod보다 먼저 실행되고, `appendPlugins`의 mod는 그 후에 나열된 순서대로 실행됩니다. [mod 실행 순서](https://code.claude.com/docs/ko/plugins/mods/events.md#the-order-mods-run-in)를 참조하세요. |426| `prependPlugins`, `appendPlugins` | 관리형 설정. 관리형 설정 또는 [`managed-mcp.json`](https://code.claude.com/docs/ko/managed-mcp#deploy-managed-mcp-json) 파일이 없는 머신에서, 자격 증명이 Team 또는 Enterprise `/login`이 아닌 세션에서만 사용자 설정. | `acme-guard@acme-tools`와 같은 플러그인 ID 목록입니다. `prependPlugins`의 mod는 사용자가 설치한 모든 mod보다 먼저 실행되고, `appendPlugins`의 mod는 그 후에 나열된 순서대로 실행됩니다. [mod 실행 순서](https://code.claude.com/docs/ko/plugins/mods/events.md#the-order-mods-run-in)를 참조하세요. |

428| `allowManagedModsOnly` | 관리형 설정, [기본 제공 가드의 옵션](https://code.claude.com/docs/ko/plugins/mods/admin.md#set-options-on-the-built-in-guard)으로 설정 | [조직의 mod로 간주되는](https://code.claude.com/docs/ko/plugins/mods/admin.md#install-your-organizations-mods) mod와 Claude Code에 기본 제공되는 mod만 훅을 실행합니다. 사용자의 설정 훅은 계속 실행됩니다. |427| `allowManagedModsOnly` | 관리형 설정, [기본 제공 가드의 옵션](https://code.claude.com/docs/ko/plugins/mods/admin.md#set-options-on-the-built-in-guard)으로 설정 | [조직의 mod로 간주되는](https://code.claude.com/docs/ko/plugins/mods/admin.md#install-your-organizations-mods) mod와 Claude Code에 기본 제공되는 mod만 훅을 실행합니다. 사용자의 설정 훅은 계속 실행됩니다. |

429| `allowModsToOverrideDenyRules` | 관리형 설정, [기본 제공 가드의 옵션](https://code.claude.com/docs/ko/plugins/mods/admin.md#set-options-on-the-built-in-guard)으로 설정 | 사용자가 설치한 mod가 `deny` 규칙이 거부하는 도구 호출을 승인할 수 있도록 합니다 |428| `allowModsToOverrideDenyRules` | 관리형 설정, [기본 제공 가드의 옵션](https://code.claude.com/docs/ko/plugins/mods/admin.md#set-options-on-the-built-in-guard)으로 설정 | 사용자가 설치한 mod가 `deny` 규칙을 포함하여 [기본적으로 유지되는 결과](https://code.claude.com/docs/ko/permissions.md#precedence-among-rules-hooks-and-mods) 대부분을 무시하고 도구 호출을 승인할 수 있도록 합니다 |

430| `allowManagedHooksOnly` | 관리형 설정 | 조직의 것이 아닌 훅과 설치된 mod를 차단합니다. [계속 실행되는 항목](https://code.claude.com/docs/ko/settings-reference.md#what-runs-under-allowmanagedhooksonly)을 참조하세요. |429| `allowManagedHooksOnly` | 관리형 설정 | 조직의 것이 아닌 훅과 설치된 mod를 차단합니다. [계속 실행되는 항목](https://code.claude.com/docs/ko/settings-reference.md#what-runs-under-allowmanagedhooksonly)을 참조하세요. |

431| `disableAllHooks` | 모든 설정 파일 | 관리형 설정에서는 설치된 플러그인의 mod나 훅이 하나도 실행되지 않습니다. 사용자 본인의 설정에서는 조직이 관리하는 항목이 계속 실행됩니다. [`disableAllHooks`](https://code.claude.com/docs/ko/settings-reference#disableallhooks)를 참조하세요. |430| `disableAllHooks` | 모든 설정 파일 | 관리형 설정에서는 설치된 플러그인의 mod나 훅이 하나도 실행되지 않습니다. 사용자 본인의 설정에서는 조직이 관리하는 항목이 계속 실행됩니다. [`disableAllHooks`](https://code.claude.com/docs/ko/settings-reference#disableallhooks)를 참조하세요. |

432| `disableSideloadFlags` | 관리형 설정 | 시작 시 `--plugin-dir` 및 `--plugin-url`을 거부합니다 |431| `disableSideloadFlags` | 관리형 설정 | 시작 시 `--plugin-dir` 및 `--plugin-url`을 거부합니다 |

433| `pluginConfigs` | 사용자 또는 관리형 설정 | mod의 `userConfig` 값을 보관하며, `acme-guard@acme-tools`와 같은 플러그인 ID를 키로 사용합니다. `--plugin-dir`로 로드된 mod의 경우 `first-mod@inline`과 같이 이름과 `@inline`을 키로 사용합니다 |432| `pluginConfigs` | 사용자 또는 관리형 설정 | mod의 `userConfig` 값을 보관하며, `acme-guard@acme-tools`와 같은 플러그인 ID를 키로 사용합니다. `--plugin-dir`로 로드된 mod의 경우 `first-mod@inline`과 같이 이름과 `@inline`을 키로 사용합니다 |

434 433 

435`sec-default@builtin`은 Claude Code에 기본 제공되는 가드로, `/plugin` 및 디버그 로그에는 `cc-plugin-sec-default`로 표시됩니다. 관리형 설정이 있는 머신이거나 자격 증명이 Team 또는 Enterprise [`/login`](https://code.claude.com/docs/ko/authentication#authentication-precedence)인 세션에서는, 사용자가 설치하는 모든 mod보다 먼저 로드됩니다. 관리형 `prependPlugins`가 설정된 경우, 이 가드는 해당 목록에 이름이 포함된 경우에만 나열된 위치에서 로드됩니다.434`sec-default@builtin`은 Claude Code에 기본 제공되는 가드로, `/plugin` 및 디버그 로그에는 `cc-plugin-sec-default`로 표시됩니다. [이 가드가 로드되는 경우](https://code.claude.com/docs/ko/plugins/mods/admin.md#know-what-happens-by-default), 사용자가 설치하는 모든 mod보다 먼저 실행됩니다. 관리형 `prependPlugins`가 설정된 경우, 이 가드는 해당 목록에 이름이 포함된 경우에만 나열된 위치에서 로드됩니다.

436 435 

437소스는 [Claude Code 저장소의 `mods/sec-default` 디렉터리](https://github.com/anthropics/claude-code/tree/main/mods/sec-default)에 있습니다.436소스는 [Claude Code 저장소의 `mods/sec-default` 디렉터리](https://github.com/anthropics/claude-code/tree/main/mods/sec-default)에 있습니다.

438 437 

Details

14 14 

15모듈이 로드되지 않거나, 훅을 건너뛰거나, 다른 mod가 사용자의 mod를 거부하면 Claude Code는 해당 mod의 이름이 포함된 한 줄을 기록합니다. 이 줄을 확인하는 위치는 세션에 따라 다릅니다.15모듈이 로드되지 않거나, 훅을 건너뛰거나, 다른 mod가 사용자의 mod를 거부하면 Claude Code는 해당 mod의 이름이 포함된 한 줄을 기록합니다. 이 줄을 확인하는 위치는 세션에 따라 다릅니다.

16 16 

17* **플러그인 디렉터리를 핫 리로드하는 세션**: 트랜스크립트에 흐리게 표시되는 줄입니다. `--plugin-dir`로 시작한 대화형 세션이나, Claude가 작성한 mod에 대해 [핫 리로드를 활성화한](https://code.claude.com/docs/ko/plugins/mods/create.md#ask-claude-for-a-mod) 세션이 이에 해당합니다.17* **플러그인 디렉터리를 핫 리로드하는 세션**: 트랜스크립트에 흐린 줄로 표시됩니다. `--plugin-dir`로 시작한 대화형 세션이거나, Claude가 작성한 mod에 대해 [핫 리로딩이 켜져 있는](https://code.claude.com/docs/ko/plugins/mods/create.md#ask-claude-for-a-mod) 세션이 이에 해당합니다.

18* **그 외의 대화형 세션(예: 마켓플레이스에서 설치한 mod를 실행하는 세션)**: [디버그 로그](#read-the-debug-log)에만 기록됩니다. 디버그 로그를 얻으려면 `claude --debug`로 세션을 시작합니다.18* **그 외의 대화형 세션(예: 마켓플레이스에서 설치한 mod를 실행하는 세션)**: [디버그 로그](#read-the-debug-log)에만 기록됩니다. 디버그 로그를 얻으려면 `claude --debug`로 세션을 시작합니다.

19* **`--plugin-dir`을 사용한 `claude -p` 실행**: 기본 텍스트 출력 형식에서 stderr로 출력됩니다. 다른 mod에 의한 거부는 디버그 로그에만 기록됩니다.19* **`--plugin-dir`을 사용한 `claude -p` 실행**: 기본 텍스트 출력 형식에서 stderr로 출력됩니다. 다른 mod에 의한 거부는 디버그 로그에만 기록됩니다.

20 20 

68 68 

69### 기본 제공 가드의 메시지69### 기본 제공 가드의 메시지

70 70 

71관리형 설정이 있는 컴퓨터에서, 또는 Team이나 Enterprise `/login` 자격 증명을 사용하는 세션에서, [기본 제공 가드](https://code.claude.com/docs/ko/plugins/mods/admin.md#know-what-happens-by-default)가 mod 또는 mod의 응답 중 하나를 거부할 수 있습니다. 각 메시지에는 조직의 관리자가 규칙을 변경하기 위해 설정하는 옵션이 명시되어 있습니다.71[기본 제공 가드](https://code.claude.com/docs/ko/plugins/mods/admin.md#know-what-happens-by-default)가 로드되는 환경에서는 가드가 mod 또는 mod의 응답 중 하나를 거부할 수 있습니다. 각 메시지에는 조직의 관리자가 규칙을 변경하기 위해 설정하는 옵션이 명시되어 있습니다.

72 72 

73| 메시지 포함 내용 | 의미 | 표시 위치 |73| 메시지 포함 내용 | 의미 | 표시 위치 |

74| :- | :- | :- |74| :- | :- | :- |

plugins/org.md +1 −1

Details

89* **대화형 세션**: Claude Code는 기여자가 해당 폴더에 대한 [작업 영역 신뢰 대화](https://code.claude.com/docs/ko/permissions.md#what-runs-before-you-trust-a-folder)를 수락한 후에만 마켓플레이스를 등록합니다.89* **대화형 세션**: Claude Code는 기여자가 해당 폴더에 대한 [작업 영역 신뢰 대화](https://code.claude.com/docs/ko/permissions.md#what-runs-before-you-trust-a-folder)를 수락한 후에만 마켓플레이스를 등록합니다.

90* **[비대화형 `-p` 실행](https://code.claude.com/docs/ko/headless)**: 항목은 사용자가 이미 대화형으로 신뢰를 수락한 폴더 또는 `~/.claude.json`에서 `hasTrustDialogAccepted` 플래그를 설정한 폴더에만 적용됩니다.90* **[비대화형 `-p` 실행](https://code.claude.com/docs/ko/headless)**: 항목은 사용자가 이미 대화형으로 신뢰를 수락한 폴더 또는 `~/.claude.json`에서 `hasTrustDialogAccepted` 플래그를 설정한 폴더에만 적용됩니다.

91 91 

92마켓플레이스가 상대 경로로 나열하는 플러그인은 저장소의 `extraKnownMarketplaces` 항목이 적용되면 마켓플레이스 복사본에서 로드됩니다. 마켓플레이스 항목이 플러그인의 자체 GitHub 저장소와 같은 외부 소스를 대신 가리키는 플러그인은 저장소의 설정만으로는 설치되지 않습니다. 각 기여자는 [플러그인 설치](https://code.claude.com/docs/ko/plugins/install.md)에서 설명하는 대로 `claude plugin install <name>@<marketplace> --scope project`를 실행할 때까지 `Plugin "<name>" is enabled in project settings but isn't installed`를 봅니다.92저장소에서 `enabledPlugins`를 설정해도 플러그인이 설치되지는 않습니다. 마켓플레이스가 등록되면 각 기여자에게 `claude plugin install <name>@<marketplace> --scope project`를 실행하도록 요청합니다. 실행하기 전까지 `/plugin`의 **Errors** 탭에 `Plugin "<name>" is enabled in project settings but isn't installed here` 또는 [`not cached`](https://code.claude.com/docs/ko/plugins/troubleshooting#plugin-not-cached-at)가 표시될 수 있습니다. 로컬 `directory` 또는 `file` 마켓플레이스가 [상대 경로 `source`](https://code.claude.com/docs/ko/plugins/marketplace-reference#plugin-sources)로 플러그인을 나열하는 경우에는 기여자가 설치할 필요가 없습니다.

93 93 

94상대 경로가 있는 로컬 `directory` 또는 `file` 소스를 사용하는 경우 경로는 저장소의 주 체크아웃에 대해 확인됩니다. git worktree에서 Claude Code를 실행할 때 경로는 여전히 주 체크아웃을 가리키므로 모든 worktree는 같은 마켓플레이스 위치를 공유합니다.94상대 경로가 있는 로컬 `directory` 또는 `file` 소스를 사용하는 경우 경로는 저장소의 주 체크아웃에 대해 확인됩니다. git worktree에서 Claude Code를 실행할 때 경로는 여전히 주 체크아웃을 가리키므로 모든 worktree는 같은 마켓플레이스 위치를 공유합니다.

95 95 

Details

322 322 

323### 마켓플레이스 업데이트가 오프라인에서 계속 실패323### 마켓플레이스 업데이트가 오프라인에서 계속 실패

324 324 

325마켓플레이스의 git 호스트에 도달할 수 없는 환경에서 작업하고 있으며, 모든 세션이 백그라운드에서 실패한 새로고침을 반복합니다. 마켓플레이스의 기존 체크아웃은 제자리에 남아 있고 시작이 지연되지 않습니다.325마켓플레이스의 git 호스트에 도달할 수 없는 환경에서 작업하고 있으며, 모든 세션이 백그라운드에서 실패한 새로고침을 반복합니다. 마켓플레이스의 기존 체크아웃은 제자리에 남아 있습니다.

326 326 

327각 세션에서 [자동 업데이트가 켜진](https://code.claude.com/docs/ko/plugins/loading.md#which-marketplaces-and-plugins-auto-update) 마켓플레이스의 경우 Claude Code는 백그라운드에서 마켓플레이스의 git 호스트에서 새 커밋을 확인합니다. 해당 확인이 호스트에 도달할 수 없으면 마켓플레이스를 다시 클론하려고 시도하고 오프라인에서 해당 클론도 실패합니다.327각 세션에서 [자동 업데이트가 켜진](https://code.claude.com/docs/ko/plugins/loading.md#which-marketplaces-and-plugins-auto-update) 마켓플레이스의 경우 Claude Code는 백그라운드에서 마켓플레이스의 git 호스트에서 새 커밋을 확인합니다. 해당 확인이 호스트에 도달할 수 없으면 마켓플레이스를 다시 클론하려고 시도하고 오프라인에서 해당 클론도 실패합니다.

328 328 

617 617 

618## 플러그인이 설치되었지만 작동하지 않음618## 플러그인이 설치되었지만 작동하지 않음

619 619 

620설치가 성공했지만 플러그인의 스킬, 훅 또는 서버가 아무것도 하지 않습니다. [플러그인이 나타나지 않거나 스킬이 표시되지 않음](#plugin-doesnt-appear-or-its-skills-dont-show-up)으로 시작합니다. 이는 Claude Code가 로드한 내용을 보고하는 위치를 알려주고 메시지와 일치합니다.620설치는 성공했지만 플러그인의 스킬, 훅 또는 서버가 아무 동작도 하지 않습니다. 먼저 Claude Code가 로드한 항목을 어디에서 보고하는지 설명하는 [플러그인이 나타나지 않거나 스킬이 표시되지 않음](#plugin-doesnt-appear-or-its-skills-dont-show-up)부터 확인한 다음, 표시된 메시지와 일치하는 항목을 찾습니다.

621 621 

622### 플러그인이 나타나지 않거나 스킬이 표시되지 않음622### 플러그인이 나타나지 않거나 스킬이 표시되지 않음

623 623 

624플러그인을 설치했고 `/`를 입력하여 스킬을 기대했거나 Claude에게 사용하도록 요청했으며 아무것도 일어나지 않았습니다.624플러그인을 설치한 후 해당 스킬을 기대하며 `/`를 입력하거나 Claude에게 플러그인을 사용하도록 요청했지만 아무 일도 일어나지 않았습니다.

625 625 

626변경하기 전에 플러그인의 상태를 확인합니다:626무언가를 변경하기 전에 플러그인의 상태를 확인합니다.

627 627 

628**1. 플러그인이 설치되고 활성화되었는지 확인**628**1. 플러그인이 설치되고 활성화되었는지 확인**

629 629 

630`/plugin`을 실행하고 **Installed**를 엽니다. 플러그인이 나열되고 활성화되었는지 확인합니다. 셸의 `claude plugin list`는 각 플러그인의 버전, 범위 및 `Status: ✔ enabled`와 함께 동일한 목록을 인쇄합니다.630`/plugin`을 실행하고 **Installed**를 엽니다. 플러그인이 목록에 있고 활성화되어 있는지 확인합니다. 셸에서 `claude plugin list`를 실행하면 각 플러그인의 버전, 범위, `Status: ✔ enabled`와 함께 동일한 목록이 출력됩니다.

631 631 

632**2. Errors 탭 읽기**632**2. Errors 탭 읽기**

633 633 

634동일한 패널에서 **Errors** 탭을 엽니다. 각 항목은 메시지를 지침 줄과 쌍으로 만듭니다. 이 섹션의 나머지 부분의 대부분의 메시지는 해당 탭에서 나옵니다.634같은 패널에서 **Errors** 탭을 엽니다. 각 항목은 메시지와 안내 줄로 구성됩니다. 이 섹션의 나머지 부분에 나오는 메시지 대부분은 이 탭에서 표시됩니다.

635 635 

636**3. 이 세션 중에 설치한 경우 다시 로드**636**3. 이번 세션 중에 설치했다면 다시 로드**

637 637 

638플러그인이 설치되고 오류가 없지만 이 세션 중에 설치한 경우 `/reload-plugins`를 실행합니다. 플러그인, 스킬, 에이전트, 훅 및 서버의 개수와 함께 `Reloaded:`를 인쇄합니다. 무언가가 실패하면 `N errors during load. Run /plugin for details.`를 추가합니다.638플러그인이 설치되어 있고 오류가 없지만 이번 세션 중에 설치했다면 `/reload-plugins`를 실행합니다. 이 명령은 플러그인, 스킬, 에이전트, 훅, 서버의 개수와 함께 `Reloaded:`를 출력합니다. 실패한 항목이 있으면 `N errors during load. Run /plugin for details.`가 추가됩니다.

639 639 

640플러그인이 오류 없이 로드되지만 스킬이 여전히 나타나지 않으면 다음 단계는 자신의 플러그인과 다른 사람의 플러그인에 따라 다릅니다:640플러그인이 오류 없이 로드되었는데도 스킬이 여전히 나타나지 않는다면, 다음 단계는 직접 만든 플러그인인지 다른 사람의 플러그인인지에 따라 다릅니다.

641 641 

642* **빌드 중인 플러그인**: [플러그인이 로드되지만 스킬이 누락됨](#plugin-loads-but-its-skills-are-missing)을 참조합니다.642* **직접 빌드 중인 플러그인**: [플러그인은 로드되지만 스킬이 누락됨](#plugin-loads-but-its-skills-are-missing)을 참조합니다

643* **다른 사람이 게시한 플러그인**: `/plugin`에서 **Installed**를 열고 플러그인의 세부 정보 창을 열어 플러그인에 포함된 내용을 나열합니다. 거기에 스킬이 나열되지 않은 플러그인은 `/`를 입력할 때 제공할 스킬이 없습니다.643* **다른 사람이 게시한 플러그인**: `/plugin`에서 **Installed**를 열고 플러그인의 세부 정보 창을 엽니다. 이 창에는 플러그인에 포함된 항목이 나열됩니다. 여기에 스킬이 나열되지 않은 플러그인은 `/`를 입력해도 제공할 스킬이 없습니다

644 644 

645### `Run /reload-plugins to apply.`645### `Run /reload-plugins to apply.`

646 646 

647`/plugin`의 설치 요약이 `Plugin is now active.` 대신 `Run /reload-plugins to apply.`로 끝났습니다. 동시에 프롬프트 위에 `Plugins changed. Run /reload-plugins to activate.` 알림이 나타날 수 있습니다.647`/plugin`의 설치 요약이 `Plugin is now active.` 대신 `Run /reload-plugins to apply.`로 끝났습니다. 동시에 프롬프트 위에 `Plugins changed. Run /reload-plugins to activate.` 알림이 나타날 수 있습니다.

648 648 

649Claude Code가 설치 중에 플러그인을 활성화하지 않았습니다. 활성화하면 [프롬프트 캐시가 무효화](https://code.claude.com/docs/ko/prompt-caching.md#enabling-or-disabling-a-plugin)되거나 활성화 시도가 실패했기 때문입니다.649플러그인을 활성화하면 [프롬프트 캐시가 무효화](https://code.claude.com/docs/ko/prompt-caching.md#enabling-or-disabling-a-plugin)되거나 활성화 시도가 실패했기 때문에 Claude Code가 설치 중에 플러그인을 활성화하지 않았습니다.

650 650 

651명령을 입력할 필요가 없습니다. 패널이 닫히고 Claude Code가 `/reload-plugins`를 실행하거나 스트리밍 중인 응답이 완료될 때까지 대기열에 넣습니다.651명령을 직접 입력할 필요는 없습니다. 패널이 닫히고 Claude Code가 `/reload-plugins`를 대신 실행하거나, 스트리밍 중인 응답이 끝날 때까지 대기열에 넣습니다.

652 652 

653해당 다시 로드가 인쇄하는 내용을 읽습니다:653다시 로드 후 출력되는 내용을 확인합니다.

654 654 

655* **플러그인, 스킬, 에이전트, 훅 및 서버의 개수와 함께 `Reloaded:`**: 플러그인이 이제 활성화되었습니다. 무언가가 로드되지 못하면 줄이 `N errors during load. Run /plugin for details.`를 추가합니다.655* **플러그인, 스킬, 에이전트, 훅, 서버의 개수와 함께 표시되는 `Reloaded:`**: 이제 플러그인이 활성화되었습니다. 로드에 실패한 항목이 있으면 해당 줄에 `N errors during load. Run /plugin for details.`가 추가됩니다.

656* **`This reload changes MCP tools (...) — your next message will re-read the whole conversation instead of using the cache. Run /reload-plugins --force to apply.`**: 다시 로드가 플러그인 MCP 서버를 추가하거나 제거하거나 `LSP` 도구를 추가하거나 제거하며 프롬프트 캐시를 무효화합니다. LSP 경우 줄이 `This reload adds the LSP tool` 또는 `This reload removes the LSP tool`로 시작합니다. `--force`로 실행하여 플러그인을 활성화하거나 새 세션을 시작합니다.656* **`This reload changes MCP tools (...) — your next message will re-read the whole conversation instead of using the cache. Run /reload-plugins --force to apply.`**: 다시 로드하면 플러그인 MCP 서버 또는 `LSP` 도구가 추가되거나 제거되어 프롬프트 캐시가 무효화됩니다. LSP의 경우 해당 줄은 `This reload adds the LSP tool` 또는 `This reload removes the LSP tool`로 시작합니다. 그래도 플러그인을 활성화하려면 `--force`와 함께 실행하거나 새 세션을 시작합니다

657 657 

658v2.1.268 이전에는 설치 중에 활성화되지 않은 설치가 직접 `/reload-plugins`를 실행할 때까지 대기 중이었습니다.658v2.1.268 이전에는 설치 중에 활성화되지 않은 플러그인은 사용자가 직접 `/reload-plugins`를 실행할 때까지 보류 상태로 남아 있었습니다.

659 659 

660v2.1.246 이전에는 해당 요약의 스킬 개수가 플러그인의 `commands/` 항목만 포함했으므로 다시 로드가 플러그인의 `SKILL.md` 스킬을 로드하고 여전히 `0 skills`를 보고할 수 있었습니다.660v2.1.246 이전에는 해당 요약의 스킬 개수에 플러그인의 `commands/` 항목만 포함되었기 때문에, 다시 로드하면 플러그인의 `SKILL.md` 스킬을 로드하고도 `0 skills`로 보고될 수 있었습니다.

661 661 

662### `The packages it lists are not installed` 또는 `were not installed, because ...`662### `The packages it lists are not installed` 또는 `were not installed, because ...`

663 663 

664`/plugin`과 `claude plugin list`는 의존성 설치 후 `node_modules` 디렉토리가 남지 않은 플러그인에 이 메모 중 하나를 표시합니다. 플러그인은 로드되지만 누락된 패키지가 필요한 부분은 작동하지 않을 수 있습니다.664의존성 설치 후 `node_modules` 디렉터리가 남지 않은 플러그인에 대해 `/plugin`과 `claude plugin list`에 이 메모 중 하나가 표시됩니다. 플러그인은 로드되지만, 누락된 패키지가 필요한 부분은 작동하지 않을 수 있습니다.

665 665 

666* **`are not installed`**: 이 플러그인에 대해 설치를 실행할 수 있지만 완료되지 않았습니다(예: 실패하거나 시간 초과된 경우). 설치를 재시도하려면 메모에 나온 `claude plugin update` 명령을 셸에서 실행하거나 `/plugin`에서 플러그인을 업데이트합니다.666* **`are not installed`**: 이 플러그인에 대해 설치를 실행할 수는 있지만, 실패하거나 시간이 초과되는 등의 이유로 완료되지 않았습니다. 설치를 재시도하려면 셸에서 메모에 제시된 `claude plugin update` 명령을 실행하거나 `/plugin`에서 플러그인을 업데이트합니다

667 667 

668 ```shell theme={null}668 ```shell theme={null}

669 claude plugin update formatter@my-marketplace669 claude plugin update formatter@my-marketplace

670 ```670 ```

671 671 

672 재시도가 실패하면 출력에 원인이 표시됩니다. `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC`가 설정되어 있는 동안에는 `claude plugin update`와 `/plugin`이 재시도를 건너뛰고 플러그인이 최신 버전이라고 보고합니다.672 재시도가 실패하면 출력에 원인이 표시됩니다. `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC`이 설정되어 있는 동안에는 `claude plugin update`와 `/plugin`이 재시도를 건너뛰고 플러그인이 최신 버전이라고 보고합니다.

673 673 

674* **`were not installed, because ...`**: 이 플러그인에 대해서는 설치를 실행할 수 없으며, 메모에 Yarn, pnpm 또는 `bun.lockb` 잠금 파일, 또는 이 컴퓨터에 해당 패키지 관리자가 설치되지 않은 잠금 파일과 같은 이유가 명시됩니다. 해당 이유가 해소되지 않는 한 플러그인을 업데이트해도 패키지가 설치되지 않습니다. 이유가 잠금 파일이라면 플러그인 작성자가 이를 교체해야 합니다. 패키지 관리자가 누락된 경우라면 이를 설치한 다음 플러그인을 업데이트합니다.674* **`were not installed, because ...`**: 이 플러그인에 대해 설치를 실행할 수 없으며, 메모에 Yarn, pnpm 또는 `bun.lockb` 잠금 파일이나 이 컴퓨터에 패키지 관리자가 설치되어 있지 않은 잠금 파일 등의 이유가 명시됩니다. 해당 이유가 해결되지 않는 한 플러그인을 업데이트해도 패키지가 설치되지 않습니다. 원인이 잠금 파일이라면 플러그인 작성자가 이를 교체해야 합니다. 패키지 관리자가 누락된 경우라면 패키지 관리자를 설치한 다음 플러그인을 업데이트합니다

675 675 

676### `Plugin "<name>" not cached at <path>`676### `Plugin "<name>" not cached at <path>`

677 677 

678**Errors** 탭은 이 줄을 `Run /plugin to refresh the plugin cache`의 지침과 함께 표시합니다. Claude Code는 플러그인에 대한 설치 기록을 가지고 있지만 기록이 가리키는 디렉토리가 누락되었습니다(예: 캐시를 지운 후).678**Errors** 탭에 `Run /plugin to refresh the plugin cache`라는 안내와 함께 이 줄이 표시됩니다. 이는 Claude Code가 플러그인의 사용 가능한 사본을 찾지 못했다는 의미입니다. 예를 들어 캐시를 지워서 설치 기록이 가리키는 디렉터리가 없거나, 설정에서 플러그인을 활성화하는 저장소를 열었지만 해당 플러그인을 설치하지 않은 경우입니다.

679 679 

680셸에서 플러그인을 다시 설치합니다. `claude plugin install <name>@<marketplace>`는 설치 디렉토리가 누락되었지만 기록이 존재하는 플러그인을 다시 다운로드합니다:680셸에서 플러그인을 설치합니다. `.claude/settings.json`에서 플러그인을 활성화하는 저장소를 열었다면, [프로젝트 설정에서 활성화되었지만 설치되지 않음](https://code.claude.com/docs/ko/plugins/loading.md#enabled-in-project-settings-but-not-installed)에 설명된 대로 `enabledPlugins`의 플러그인 키를 사용하여 프로젝트에서 다음을 실행합니다.

681 

682```shell theme={null}

683claude plugin install <name>@<marketplace> --scope project

684```

685 

686그렇지 않은 경우 다음을 실행합니다. 이 명령은 기록은 있지만 설치 디렉터리가 없는 플러그인을 다시 다운로드합니다.

681 687 

682```shell theme={null}688```shell theme={null}

683claude plugin install <name>@<marketplace>689claude plugin install <name>@<marketplace>

684```690```

685 691 

686그런 다음 세션에서 `/reload-plugins`를 실행합니다. **Errors** 탭 항목이 사라지고 플러그인이 **Installed** 아래로 돌아옵니다.692그런 다음 세션에서 `/reload-plugins`를 실행합니다. **Errors** 탭 항목이 사라지고 플러그인이 **Installed** 아래에 나열됩니다.

687 693 

688### `installed_plugins.json holds a record under "<id>" that this version of Claude Code cannot read`694### `installed_plugins.json holds a record under "<id>" that this version of Claude Code cannot read`

689 695 

690메시지는 다음 형식으로 표시됩니다:696이 메시지는 다음 형태로 나타납니다.

691 697 

692* **`claude plugin list`**: `Note:`로 인쇄합니다.698* **`claude plugin list`**: `Note:`로 출력합니다

693* **`claude plugin install`, `uninstall`, 및 `update`**: `Plugin "<name>" was not installed:`, `Plugin "<name>" was not uninstalled:`, 또는 `Plugin "<name>" was not updated:`로 거부하고 동일한 텍스트가 뒤따릅니다.699* **`claude plugin install`, `uninstall`, `update`**: `Plugin "<name>" was not installed:`, `Plugin "<name>" was not uninstalled:` 또는 `Plugin "<name>" was not updated:` 뒤에 같은 텍스트를 붙여 실행을 거부합니다

694* **이 세 명령 중 하나에서 `--json`**: 결과 줄은 동일한 `message` 및 `failureCode: "install_records_unreadable"`을 전달합니다.700* **이 세 명령 중 하나에 `--json` 사용**: 결과 줄에 동일한 `message`와 `failureCode: "install_records_unreadable"`이 포함됩니다

695* **여러 개의 그러한 기록**: 메시지는 `holds records under`를 읽습니다.701* **이러한 기록이 여러 개인 경우**: 메시지가 `holds records under`로 표시됩니다

696* **전체 파일이 이 버전이 알 수 없는 형식을 선언**: 메시지는 `installed_plugins.json is in a format (version <N>) that this version of Claude Code does not know` 대신 읽습니다.702* **파일 전체가 이 버전에서 알 수 없는 형식을 선언한 경우**: 메시지가 대신 `installed_plugins.json is in a format (version <N>) that this version of Claude Code does not know`로 표시됩니다

697 703 

698`installed_plugins.json`의 명명된 기록은 유효한 플러그인 id 아래의 유효한 JSON이지만 해당 필드는 이 버전에 대해 구문 분석되지 않습니다. 아마도 다른 버전의 Claude Code(아마도 더 최신 버전)가 작성했을 것입니다.704`installed_plugins.json`의 해당 기록은 유효한 플러그인 ID 아래에 있는 유효한 JSON이지만, 그 필드를 이 버전에서 파싱할 수 없습니다. 다른 버전의 Claude Code, 아마도 더 최신 버전이 이 기록을 작성했을 가능성이 높습니다.

699 705 

700기록이 있는 동안 이 버전은 파일을 다시 작성하지 않으므로 기록이 손실되지 않습니다.706기록이 존재하는 동안 이 버전은 파일을 다시 쓰지 않으므로 기록이 손실되지 않습니다.

701 707 

702메시지의 옵션을 순서대로 가져옵니다:708메시지의 선택지를 순서대로 시도합니다.

703 709 

7041. `claude update`로 Claude Code를 업데이트합니다.7101. `claude update`로 Claude Code를 업데이트합니다.

7052. 업데이트할 수 없으면 기록을 작성한 Claude Code 버전으로 명명된 플러그인을 제거합니다.7112. 업데이트할 수 없다면 기록을 작성한 버전의 Claude Code로 해당 플러그인을 제거합니다.

7063. 둘 다 도움이 되지 않으면 `installed_plugins.json`에서 기록을 수동으로 삭제한 다음 Claude Code를 다시 시작하거나 `/reload-plugins`를 실행합니다.7123. 둘 다 도움이 되지 않으면 `installed_plugins.json`에서 해당 기록을 직접 삭제한 다음 Claude Code를 재시작하거나 `/reload-plugins`를 실행합니다.

707 713 

708### `installed_plugins.json could not be read and was rebuilt`714### `installed_plugins.json could not be read and was rebuilt`

709 715 

710`claude plugin list`는 이 메모를 `installed_plugins.json` 옆에 있는 `installed_plugins.unreadable.<date>.<hash>.kept`라는 보관된 파일의 경로와 함께 인쇄합니다.716`installed_plugins.unreadable.<date>.<hash>.kept`라는 보존 파일이 `installed_plugins.json` 옆에 있는 동안 `claude plugin list`는 해당 파일의 경로와 함께 이 메모를 출력합니다.

711 717 

712유효한 JSON이 아니거나 플러그인 목록이 아닌 `installed_plugins.json`은 설치한 내용을 말할 수 없습니다.718유효한 JSON이 아니거나 플러그인 목록이 아닌 `installed_plugins.json`으로는 무엇을 설치했는지 알 수 없습니다.

713 719 

714`.kept` 파일을 열어 이전 파일이 기록한 내용을 확인하고 누락된 플러그인을 다시 설치합니다. Claude Code는 파일을 다시 읽지 않으며 파일은 [`cleanupPeriodDays`](https://code.claude.com/docs/ko/settings-reference#cleanupperioddays) 일정에 따라 만료됩니다.720`.kept` 파일을 열어 이전 파일에 기록된 내용을 확인하고, 누락된 플러그인을 다시 설치합니다. Claude Code는 이 파일을 다시 읽지 않으며, 이 파일은 [`cleanupPeriodDays`](https://code.claude.com/docs/ko/settings-reference#cleanupperioddays) 일정에 따라 만료됩니다.

715 721 

716### `install records under names that no version of Claude Code can use were removed from installed_plugins.json`722### `install records under names that no version of Claude Code can use were removed from installed_plugins.json`

717 723 

718`claude plugin list`는 이 메모를 `installed_plugins.json` 옆에 있는 `installed_plugins.set-aside.<date>.<hash>.json`이라는 복사본의 경로와 함께 인쇄합니다. 메모는 `Nothing needs doing about these copies.`로 끝납니다.724`installed_plugins.set-aside.<date>.<hash>.json`이라는 사본이 `installed_plugins.json` 옆에 있는 동안 `claude plugin list`는 해당 사본의 경로와 함께 이 메모를 출력합니다. 메모는 `Nothing needs doing about these copies.`로 끝납니다.

719 725 

720`installed_plugins.json`의 기록은 유효한 플러그인 id가 아닌 키 아래에 있었으므로 Claude Code의 어떤 버전도 사용할 수 없습니다. 파일의 나머지는 정상적으로 로드됩니다.726`installed_plugins.json`의 기록이 유효한 플러그인 ID가 아닌 키 아래에 있었기 때문에 어떤 버전의 Claude Code도 이를 사용할 수 없습니다. 파일의 나머지 부분은 정상적으로 로드됩니다.

721 727 

722Claude Code는 사용할 수 없는 기록을 `.set-aside` 파일로 복사하고 목록에서 삭제합니다. Claude Code는 복사본을 다시 읽지 않으며 복사본은 [`cleanupPeriodDays`](https://code.claude.com/docs/ko/settings-reference#cleanupperioddays) 일정에 따라 만료됩니다.728Claude Code는 사용할 수 없는 기록을 `.set-aside` 파일로 복사하고 목록에서 제거합니다. Claude Code는 이 사본을 다시 읽지 않으며, 사본은 [`cleanupPeriodDays`](https://code.claude.com/docs/ko/settings-reference#cleanupperioddays) 일정에 따라 만료됩니다.

723 729 

724### `does not load (...), so Claude Code ignores the whole file`730### `does not load (...), so Claude Code ignores the whole file`

725 731 

726명령은 작동했습니다. 경고에 명시된 설정 파일에 오류가 있으므로, 이를 수정할 때까지 Claude Code는 명령이 해당 파일에 기록한 내용을 포함하여 파일 전체를 무시합니다.732명령은 성공했습니다. 경고에 명시된 설정 파일에 오류가 있어서, 오류를 수정할 때까지 Claude Code는 명령이 해당 파일에 쓴 내용을 포함하여 파일 전체를 무시합니다.

727 733 

728경고에 명시된 오류를 수정합니다. Claude Code가 허용하지 않는 값의 경우 [손상된 설정 파일 수정](https://code.claude.com/docs/ko/settings.md#fix-a-broken-settings-file)에서 방법을 설명합니다. 그런 다음 명령의 변경 사항이 더 이상 파일에 없으면 명령을 다시 실행합니다.734경고에 명시된 오류를 수정합니다. Claude Code가 허용하지 않는 값의 경우 [손상된 설정 파일 수정](https://code.claude.com/docs/ko/settings.md#fix-a-broken-settings-file)에서 방법을 확인할 수 있습니다. 그런 다음 명령의 변경 사항이 더 이상 파일에 없다면 명령을 다시 실행합니다.

729 735 

730이 경고는 셸에서 실행한 `claude plugin install`, `enable`, `disable` 또는 `claude plugin marketplace add`의 성공 줄 다음에 표시됩니다:736이 경고는 셸에서 `claude plugin install`, `enable`, `disable` 또는 `claude plugin marketplace add`의 성공 줄 다음에 표시됩니다.

731 737 

732```text theme={null}738```text theme={null}

733⚠ /home/user/.claude/settings.json does not load (its "permissions" is not valid), so Claude Code ignores the whole file, including anything this command wrote there. Fix the file, then run this command again if its change is missing. If a newer Claude Code wrote the file, update Claude Code instead.739⚠ /home/user/.claude/settings.json does not load (its "permissions" is not valid), so Claude Code ignores the whole file, including anything this command wrote there. Fix the file, then run this command again if its change is missing. If a newer Claude Code wrote the file, update Claude Code instead.

734```740```

735 741 

736괄호 안의 텍스트가 오류를 나타냅니다:742괄호 안의 텍스트가 오류를 나타냅니다.

737 743 

738* **`its "<key>" is not valid`**: 따옴표로 묶인 설정에 Claude Code가 허용하지 않는 값이 있습니다. 허용되는 값은 [설정 참조](https://code.claude.com/docs/ko/settings-reference.md)에서 해당 설정을 찾아 확인합니다. 둘 이상의 값이 실패하면 텍스트는 `its "permissions" and 1 other value are not valid`처럼 첫 번째 설정을 명시하고 나머지의 개수를 표시합니다.744* **`its "<key>" is not valid`**: 따옴표로 표시된 설정에 Claude Code가 허용하지 않는 값이 들어 있습니다. [설정 레퍼런스](https://code.claude.com/docs/ko/settings-reference.md)에서 해당 설정이 허용하는 값을 확인합니다. 둘 이상의 값이 실패하면 `its "permissions" and 1 other value are not valid`처럼 첫 번째 설정의 이름과 나머지 개수가 표시됩니다.

739* **`it is not a JSON object`**: 최상위 수준이 배열인 파일처럼 파일의 최상위 수준이 JSON 객체가 아닙니다.745* **`it is not a JSON object`**: 최상위가 배열인 파일처럼 파일의 최상위가 JSON 객체가 아닙니다.

740 746 

741### `Disabled in ~/.claude/settings.json but still loads`747### `Disabled in ~/.claude/settings.json but still loads`

742 748 

743`~/.claude/settings.json`에서 플러그인을 `false`로 설정했고, `claude plugin list` 또는 `/plugin`의 행이 `— project settings enable it, which overrides your user setting`과 같은 소스를 따르는 이 메시지를 표시합니다. 더 높은 우선순위 소스의 `true`가 사용자 설정을 재정의하고 있습니다.749`~/.claude/settings.json`에서 플러그인을 `false`로 설정했는데, `claude plugin list` 또는 `/plugin`의 해당 행에 이 메시지와 함께 `— project settings enable it, which overrides your user setting`처럼 플러그인을 활성화하는 소스가 표시됩니다. 우선순위가 더 높은 해당 소스의 `true`가 사용자 설정을 재정의하고 있습니다.

744 750 

745머신에서 프로젝트 활성화 플러그인을 거부하려면 id를 `.claude/settings.local.json`에서 `false`로 설정합니다. 이는 프로젝트 파일보다 우선순위가 높습니다. 메시지가 이름을 지정할 수 있는 다른 소스의 경우 [사용자 설정에서 비활성화되었지만 여전히 로드됨](https://code.claude.com/docs/ko/plugins/loading.md#disabled-in-user-settings-but-still-loads)을 참조합니다.751프로젝트에서 활성화한 플러그인을 내 컴퓨터에서만 사용하지 않으려면, 프로젝트 파일보다 우선순위가 높은 `.claude/settings.local.json`에서 해당 ID를 `false`로 설정합니다. 메시지에 표시될 수 있는 다른 소스에 대해서는 [사용자 설정에서 비활성화했지만 여전히 로드됨](https://code.claude.com/docs/ko/plugins/loading.md#disabled-in-user-settings-but-still-loads)을 참조합니다.

746 752 

747`claude plugin list`가 대신 플러그인을 `required by your org`로 표시하면 설정 파일이 관련되지 않습니다: 조직이 claude.ai에서 동기화된 플러그인을 필수로 표시하고 이전에 비활성화했더라도 로드됩니다. [claude.ai에서 동기화된 플러그인](https://code.claude.com/docs/ko/plugins/loading.md#synced-plugins)을 참조합니다.753`claude plugin list`에서 플러그인이 대신 `required by your org`로 표시된다면 설정 파일과는 관계가 없습니다. 조직이 claude.ai에서 동기화된 해당 플러그인을 필수로 지정했으며, 이전에 비활성화했더라도 로드됩니다. [claude.ai에서 동기화된 플러그인](https://code.claude.com/docs/ko/plugins/loading.md#synced-plugins)을 참조합니다.

748 754 

749### `Plugin "<name>" is enabled in project settings but isn't installed here`755### `Plugin "<name>" is enabled in project settings but isn't installed here`

750 756 

751**Errors** 탭은 프로젝트의 `.claude/settings.json`이 활성화하는 플러그인에 대해 이 줄을 `Run claude plugin install <name>@<marketplace> --scope project to install it for this project`의 지침과 함께 표시합니다.757프로젝트의 `.claude/settings.json`이 활성화하는 플러그인에 대해 **Errors** 탭에 `Run claude plugin install <name>@<marketplace> --scope project to install it for this project`라는 안내와 함께 이 줄이 표시됩니다.

752 758 

753저장소의 설정은 모든 사람이 플러그인을 활성화할 수 있지만 설치하지는 않습니다. 플러그인이 GitHub 저장소 또는 npm 패키지와 같은 외부 소스에서 나올 때 Claude Code는 직접 설치할 때까지 다운로드하지 않습니다. 지침 줄의 명령을 셸에서 실행한 다음 다시 로드합니다:759저장소의 설정은 해당 저장소를 여는 모든 사람에게 플러그인을 활성화할 수 있지만, 플러그인을 설치하지는 않습니다. 플러그인이 GitHub 저장소나 npm 패키지 같은 외부 소스에서 제공되는 경우, 사용자가 직접 설치할 때까지 Claude Code는 이를 다운로드하지 않습니다. 셸에서 안내 줄의 명령을 실행한 다음 다시 로드합니다.

754 760 

755```shell theme={null}761```shell theme={null}

756claude plugin install <name>@<marketplace> --scope project762claude plugin install <name>@<marketplace> --scope project

757```763```

758 764 

759세션에서 `/reload-plugins`를 실행한 후 **Errors** 탭 항목이 사라지고 플러그인이 **Installed** 아래에 나열됩니다.765세션에서 `/reload-plugins`를 실행하면 **Errors** 탭 항목이 사라지고 플러그인이 **Installed** 아래에 나열됩니다.

760 766 

761조직이 플러그인을 미리 설치하면 대신 관리 설정을 통해 그렇게 합니다. [플러그인 사전 설치 및 필수](https://code.claude.com/docs/ko/plugins/org.md#pre-install-and-require-plugins)를 참조합니다.767조직에서 플러그인을 미리 설치해 주는 경우에는 대신 관리형 설정을 통해 설치합니다. [플러그인 사전 설치 및 필수 지정](https://code.claude.com/docs/ko/plugins/org.md#pre-install-and-require-plugins)을 참조합니다.

762 768 

763### Windows에서 `plugin uninstall` 후에도 플러그인이 설치된 상태로 남음769### Windows에서 `plugin uninstall` 후에도 플러그인이 설치된 상태로 남음

764 770 

765Windows에서 프로젝트 또는 로컬 범위로 `claude plugin uninstall`을 실행하면 성공했다고 보고되지만, `claude plugin list` 또는 `/plugin`에 여전히 플러그인이 나열됩니다.771Windows에서 프로젝트 또는 로컬 범위로 `claude plugin uninstall`을 실행하면 성공했다고 보고되지만, `claude plugin list` 또는 `/plugin`에 여전히 플러그인이 나열됩니다.

766 772 

767`installed_plugins.json`에 프로젝트 폴더에 대한 플러그인 설치 기록이 두 개 있었고, 각 기록은 폴더 경로를 서로 다르게 표기하며, 한 번의 제거로는 그중 하나만 삭제됩니다. 확인하려면 셸에서 `claude plugin list --json`을 실행합니다. 남아 있는 플러그인 행의 `projectPath`는 제거를 실행한 위치와 폴더를 다르게 표기합니다(예: `C:\work\app`에 대해 `c:\work\app`).773`installed_plugins.json`에 프로젝트 폴더에 대한 플러그인 설치 기록이 두 개 있었고, 각각 폴더 경로를 다르게 표기했으며, 한 번의 제거로 그중 하나만 삭제됩니다. 확인하려면 셸에서 `claude plugin list --json`을 실행합니다. 남아 있는 플러그인 행의 `projectPath`가 `C:\work\app` 대신 `c:\work\app`처럼 제거를 실행한 위치와 다르게 폴더를 표기하고 있습니다.

768 774 

769같은 폴더에서 같은 `--scope`로 동일한 제거 명령을 다시 실행합니다. 두 번째 실행은 자체 경로 표기 아래에서 기록을 찾지 못하므로 다른 표기 아래의 기록을 제거합니다. 프로젝트 범위 설치의 경우:775같은 폴더에서 같은 `--scope`로 동일한 제거 명령을 다시 실행합니다. 두 번째 실행에서는 자신의 경로 표기로는 기록을 찾지 못하므로 다른 표기로 된 기록을 제거합니다. 프로젝트 범위 설치의 경우:

770 776 

771```shell theme={null}777```shell theme={null}

772claude plugin uninstall <name>@<marketplace> --scope project778claude plugin uninstall <name>@<marketplace> --scope project

776 782 

777v2.1.295 이전에는 두 번째 실행이 `Plugin "<name>" is not installed in project scope`로 실패합니다. `claude update`를 실행한 다음 제거를 다시 실행합니다.783v2.1.295 이전에는 두 번째 실행이 `Plugin "<name>" is not installed in project scope`로 실패합니다. `claude update`를 실행한 다음 제거를 다시 실행합니다.

778 784 

779### git 저장소에서 설치한 플러그인의 버전이 `unknown`으로 표시됨785### Git 저장소에서 설치한 플러그인의 버전이 `unknown`으로 표시됨

780 786 

781`claude plugin list`의 `Version: unknown`은 Claude Code가 git 소스 플러그인의 버전으로 사용하는 커밋을 읽지 못했음을 의미할 수 있습니다. 플러그인은 자체 저장소를 가지고 있거나 git으로 호스팅되는 마켓플레이스 내부에 있을 수 있습니다.787`claude plugin list`의 `Version: unknown`은 Claude Code가 Git 소스 플러그인의 버전으로 사용하는 커밋을 읽지 못했다는 의미일 수 있습니다. 플러그인은 자체 저장소를 가지고 있거나 Git으로 호스팅되는 마켓플레이스 안에 있을 수 있습니다.

782 788 

783셸에서 다음 명령을 실행합니다. `formatter@my-marketplace`는 `claude plugin list`에 표시된 플러그인의 `name@marketplace` 줄로 바꿉니다:789셸에서 다음 명령을 실행하되, `formatter@my-marketplace`를 `claude plugin list`에 표시된 플러그인의 `name@marketplace` 줄로 바꿉니다.

784 790 

785**1. Claude Code 업데이트**791**1. Claude Code 업데이트**

786 792 

787[Claude Code를 업데이트](https://code.claude.com/docs/ko/setup.md#update-claude-code)하여 v2.1.302 이상으로 만듭니다. 이 버전은 커밋을 읽을 수 있는 형식으로 클론합니다:793커밋을 읽을 수 있는 형식으로 클론하는 v2.1.302 이상으로 [Claude Code를 업데이트](https://code.claude.com/docs/ko/setup.md#update-claude-code)합니다.

788 794 

789```shell theme={null}795```shell theme={null}

790claude update796claude update

792 798 

793**2. 마켓플레이스 업데이트**799**2. 마켓플레이스 업데이트**

794 800 

795마켓플레이스 저장소 내부 플러그인의 커밋을 보관하는 Claude Code의 마켓플레이스 사본을 업데이트합니다:801마켓플레이스 저장소 안에 있는 플러그인의 커밋을 보관하는 Claude Code의 마켓플레이스 사본을 업데이트합니다.

796 802 

797```shell theme={null}803```shell theme={null}

798claude plugin marketplace update my-marketplace804claude plugin marketplace update my-marketplace

800 806 

801**3. 플러그인 업데이트**807**3. 플러그인 업데이트**

802 808 

803플러그인을 업데이트하여 기록된 버전을 다시 작성합니다:809플러그인을 업데이트하여 기록된 버전을 다시 씁니다.

804 810 

805```shell theme={null}811```shell theme={null}

806claude plugin update formatter@my-marketplace812claude plugin update formatter@my-marketplace

808 814 

809**4. 버전 확인**815**4. 버전 확인**

810 816 

811`Version:` 줄에 [12자 커밋 ID](https://code.claude.com/docs/ko/plugins/loading.md#how-claude-code-computes-the-version)와 같은 값이 있는지 확인합니다:817`Version:` 줄에 [12자리 커밋 ID](https://code.claude.com/docs/ko/plugins/loading.md#how-claude-code-computes-the-version)와 같은 값이 있는지 확인합니다.

812 818 

813```shell theme={null}819```shell theme={null}

814claude plugin list820claude plugin list

815```821```

816 822 

817`claude plugin update`는 [실행할 때마다 한 범위의 블록을 변경](https://code.claude.com/docs/ko/plugins/cli-reference.md#which-scope-the-command-updates)합니다. 여전히 `unknown`이 표시되는 블록의 경우 해당 블록의 `Scope:` 값으로 다시 실행합니다:823`claude plugin update`는 [한 번 실행할 때 하나의 범위 블록만 변경](https://code.claude.com/docs/ko/plugins/cli-reference.md#which-scope-the-command-updates)합니다. 여전히 `unknown`으로 표시되는 블록이 있다면 해당 블록의 `Scope:` 값으로 다시 실행합니다.

818 824 

819```shell theme={null}825```shell theme={null}

820claude plugin update formatter@my-marketplace --scope project826claude plugin update formatter@my-marketplace --scope project

821```827```

822 828 

823다시 실행한 후에도 블록에 여전히 `unknown`이 표시되면 [추가 도움 받기](https://code.claude.com/docs/ko/troubleshooting.md#get-more-help)를 참조합니다.829다시 실행한 후에도 블록이 여전히 `unknown`으로 표시되면 [추가 도움 받기](https://code.claude.com/docs/ko/troubleshooting.md#get-more-help)를 참조합니다.

824 830 

825### `Failed to load hooks from <path>` 및 발화하지 않는 훅831### `Failed to load hooks from <path>` 및 실행되지 않는 훅

826 832 

827플러그인의 훅이 실행되지 않거나 하나가 작업을 차단합니다. **Errors** 탭이 로드 실패를 표시하거나, 훅이 로드되고 트랜스크립트에서 `<Event> hook error` 공지를 보거나, 훅이 오류 없이 로드되고 절대 발화하지 않습니다.833플러그인의 훅이 실행되지 않거나 훅이 작업을 차단합니다. **Errors** 탭에 훅의 로드 실패가 표시되거나, 훅이 로드되었지만 트랜스크립트에 `<Event> hook error` 알림이나 차단 오류가 표시되거나, 훅이 오류 없이 로드되었지만 실행되지 않는 경우입니다.

828 834 

829#### 훅이 로드되지 못함835#### 훅 로드 실패

830 836 

831**Errors** 탭은 다음 메시지 중 하나를 표시합니다:837**Errors** 탭에 다음 메시지 중 하나가 표시됩니다.

832 838 

833* **`Failed to load hooks from <path>: <reason>`**: `hooks/hooks.json`이 유효한 JSON이 아니거나 훅 스키마가 실패합니다. 이유는 구문 분석 또는 유효성 검사 오류의 이름을 지정합니다. 파일을 수정합니다. 플러그인을 게시하기 전에 `hooks/hooks.json`의 JSON 구문 문제를 포착하려면 셸에서 `claude plugin validate <plugin-directory>`를 실행합니다.839* **`Failed to load hooks from <path>: <reason>`**: `hooks/hooks.json`이 유효한 JSON이 아니거나 훅 스키마를 통과하지 못합니다. 이유에 파싱 또는 유효성 검사 오류가 명시됩니다. 파일을 수정합니다. 플러그인을 게시하기 전에 `hooks/hooks.json`의 JSON 구문 문제를 발견하려면 셸에서 `claude plugin validate <plugin-directory>`를 실행합니다

834* **`hooks path not found: <path>`**: 매니페스트의 `hooks` 필드가 플러그인 루트에 상대적으로 해당 경로에 존재하지 않는 파일의 이름을 지정합니다. 경로를 수정하거나 파일을 추가합니다.840* **`hooks path not found: <path>`**: 매니페스트의 `hooks` 필드가 플러그인 루트 기준 해당 경로에 존재하지 않는 파일을 가리킵니다. 경로를 수정하거나 파일을 추가합니다

835* **`hooks path escapes plugin directory: <path>`**: [Path escapes plugin directory](https://code.claude.com/docs/ko/errors.md#path-escapes-plugin-directory)를 참조합니다.841* **`hooks path escapes plugin directory: <path>`**: [Path escapes plugin directory](https://code.claude.com/docs/ko/errors.md#path-escapes-plugin-directory)를 참조합니다

836 842 

837#### 트랜스크립트의 `hook error` 공지843#### 트랜스크립트의 `hook error` 알림

838 844 

839`... hook error: Failed with non-blocking status code: <stderr>` 형식의 공지는 훅이 실행되고 명령이 실패했음을 의미합니다. 예를 들어 `Stop hook error: Failed with non-blocking status code: /bin/sh: node: command not found`는 Claude Code가 생성한 셸이 `node`를 찾을 수 없음을 의미합니다. 설치하거나 `claude`를 시작하는 터미널의 `PATH`에 있는지 확인합니다.845`... hook error: Failed with non-blocking status code: <stderr>` 형태의 알림은 훅이 실행되었지만 해당 명령이 실패했다는 의미입니다. 예를 들어 `Stop hook error: Failed with non-blocking status code: /bin/sh: node: command not found`는 Claude Code가 생성한 셸이 `node`를 찾지 못했다는 의미입니다. `node`를 설치하거나, `claude`를 시작하는 터미널의 `PATH`에 있는지 확인합니다.

840 846 

841stderr이 플러그인의 경로를 공백에서 자르면 훅의 셸 형식 명령이 `${CLAUDE_PLUGIN_ROOT}`를 따옴표 외부에서 사용하고 설치 경로에 공백이 포함되어 있습니다. 변수를 큰따옴표로 감싸거나 [exec 형식](https://code.claude.com/docs/ko/hooks.md#exec-form-and-shell-form)을 사용합니다. 따옴표 없는 변수를 찾으려면 플러그인 디렉토리에서 `claude plugin validate`를 실행하고 [따옴표 경고](https://code.claude.com/docs/ko/plugins/manifest-reference.md#quoting-and-path-separators)를 찾습니다.847stderr에 플러그인 경로가 공백에서 잘려 표시된다면, 훅의 셸 형식 명령이 `${CLAUDE_PLUGIN_ROOT}`를 따옴표 없이 사용하고 있고 설치 경로에 공백이 포함되어 있는 것입니다. 변수를 큰따옴표로 감싸거나 [exec 형식](https://code.claude.com/docs/ko/hooks.md#exec-form-and-shell-form)을 사용합니다. 따옴표로 감싸지 않은 변수를 찾으려면 플러그인 디렉터리에서 `claude plugin validate`를 실행하고 [따옴표 경고](https://code.claude.com/docs/ko/plugins/manifest-reference.md#quoting-and-path-separators)를 확인합니다.

842 848 

843공지가 `Failed to run: Plugin directory does not exist: <path>`로 표시되면 [`Plugin directory does not exist`](#plugin-directory-does-not-exist)를 참조합니다.849알림이 `Failed to run: Plugin directory does not exist: <path>`라면 [`Plugin directory does not exist`](#plugin-directory-does-not-exist)를 참조합니다.

844 850 

845다른 오류의 경우 플러그인 디렉토리에서 훅의 명령을 직접 실행하여 전체 출력을 보거나 [디버그 로깅](https://code.claude.com/docs/ko/hooks.md#debug-hooks)으로 전체 stderr을 캡처합니다.851그 밖의 오류는 플러그인 디렉터리에서 훅의 명령을 직접 실행하여 전체 출력을 확인하거나, [디버그 로깅](https://code.claude.com/docs/ko/hooks.md#debug-hooks)으로 전체 stderr를 캡처합니다.

846 852 

847#### 플러그인 훅이 도구 호출 또는 프롬프트를 차단853#### 플러그인 훅이 도구 호출이나 프롬프트를 차단함

848 854 

849종료 코드 2로 종료하는 훅은 [실행한 작업을 차단](https://code.claude.com/docs/ko/hooks.md#exit-code-2)합니다. 플러그인의 훅이 이런 방식으로 차단하고 stderr이 차단 메시지일 때 오류는 `This hook comes from the <plugin> plugin.`으로 끝나므로 비활성화하거나 수정할 플러그인을 알 수 있습니다. v2.1.281 이전에는 오류가 플러그인의 이름을 지정하지 않았습니다.855종료 코드 2로 종료하는 훅은 [해당 훅이 실행된 작업을 차단](https://code.claude.com/docs/ko/hooks.md#exit-code-2)합니다. 플러그인의 훅이 이런 방식으로 차단하고 stderr가 차단 메시지인 경우, 어떤 플러그인을 비활성화하거나 수정해야 하는지 알 수 있도록 오류가 `This hook comes from the <plugin> plugin.`으로 끝납니다. v2.1.281 이전에는 오류에 플러그인 이름이 표시되지 않았습니다.

850 856 

851해당 메시지가 플러그인의 경로를 공백에서 자르면 [따옴표 없는 `${CLAUDE_PLUGIN_ROOT}` 수정](#hook-error-notices-in-the-transcript)을 적용합니다.857해당 메시지에 플러그인 경로가 공백에서 잘려 표시된다면 [따옴표 없는 `${CLAUDE_PLUGIN_ROOT}` 수정 방법](#hook-error-notices-in-the-transcript)을 적용합니다.

852 858 

853#### 훅이 로드되지만 절대 발화하지 않음859#### 훅이 로드되지만 실행되지 않음

854 860 

855훅이 오류 없이 로드되지만 절대 발화하지 않으면 먼저 세션에서 `/plugin`을 실행하고 플러그인의 세부 정보를 엽니다. 그곳에 `Its hooks.json hooks do not run`으로 시작하는 메모가 있으면 같은 이름을 가진 다른 활성화된 플러그인이 대신 훅을 등록했다는 의미이며, [두 개의 활성화된 플러그인이 이름을 공유할 때의 훅](https://code.claude.com/docs/ko/plugins/loading.md#hooks-when-two-enabled-plugins-share-a-name)에서 어느 사본인지와 전환 방법을 설명합니다. 그렇지 않으면 훅의 정의를 확인한 다음 실행되는 모습을 지켜봅니다:861훅이 오류 없이 로드되지만 실행되지 않는다면, 먼저 세션에서 `/plugin`을 실행하고 플러그인의 세부 정보를 엽니다. 그곳에 `Its hooks.json hooks do not run`으로 시작하는 메모가 있다면 같은 이름의 다른 활성화된 플러그인이 대신 훅을 등록했다는 의미이며, [활성화된 두 플러그인의 이름이 같을 때의 훅](https://code.claude.com/docs/ko/plugins/loading.md#hooks-when-two-enabled-plugins-share-a-name)에서 어느 사본인지와 전환 방법을 확인할 수 있습니다. 그렇지 않은 경우 훅의 정의를 확인한 다음 실행되는 모습을 관찰합니다.

856 862 

857**1. 이벤트 이름 확인**863**1. 이벤트 이름 확인**

858 864 

859이벤트 이름은 대소문자를 구분하므로 정확히 일치하는지 확인합니다(예: `PostToolUse`).865이벤트 이름은 대소문자를 구분하므로 `PostToolUse`처럼 정확히 일치하는지 확인합니다.

860 866 

861**2. 매처 확인**867**2. matcher 확인**

862 868 

863훅의 `matcher`가 도구 이름과 일치하는지 확인합니다.869훅의 `matcher`가 도구 이름과 일치하는지 확인합니다.

864 870 

865**3. 의도적으로 이벤트 트리거**871**3. 의도적으로 이벤트 발생시키기**

866 872 

867`PostToolUse` 훅의 경우 Claude에게 파일을 편집하도록 요청합니다.873`PostToolUse` 훅의 경우 Claude에게 파일을 편집하도록 요청합니다.

868 874 

869**4. 디버그 로그 읽기**875**4. 디버그 로그 읽기**

870 876 

871[디버그 로그](https://code.claude.com/docs/ko/hooks.md#debug-hooks)를 열어 어떤 훅이 일치했는지 기록합니다. 실행된 훅은 종료 코드와 함께 거기에 나타납니다.877어떤 훅이 일치했는지 기록하는 [디버그 로그](https://code.claude.com/docs/ko/hooks.md#debug-hooks)를 엽니다. 실행된 훅은 종료 코드와 함께 그곳에 표시됩니다.

872 878 

873### `Plugin directory does not exist: <path>`879### `Plugin directory does not exist: <path>`

874 880 

875메시지에 다시 설치하라고 나와 있더라도 먼저 Claude Code 프롬프트에서 `/reload-plugins`를 실행합니다. 세션이 플러그인의 훅을 로드한 디렉토리가 디스크에서 사라지면 플러그인의 훅이 `Failed to run: Plugin directory does not exist: <path> (<plugin> — run /plugin to reinstall)`로 실패하고 훅이 실행되지 않습니다. [`Plugin directory not found at path: <path>`](#plugin-directory-not-found-at-path)는 마켓플레이스 항목에 관한 다른 메시지입니다.881메시지에서 다시 설치하라고 안내하더라도, 먼저 Claude Code 프롬프트에서 `/reload-plugins`를 실행합니다. 세션이 플러그인의 훅을 로드한 디렉터리가 디스크에서 사라지면, 플러그인의 훅이 `Failed to run: Plugin directory does not exist: <path> (<plugin> — run /plugin to reinstall)`로 실패하고 훅이 실행되지 않습니다. [`Plugin directory not found at path: <path>`](#plugin-directory-not-found-at-path)는 마켓플레이스 항목에 관한 다른 메시지입니다.

876 882 

877다시 로드하면 플러그인의 현재 디렉토리에서 훅을 로드합니다. 실패는 각 훅 이벤트와 명령마다 세션당 한 번만 표시되므로, 훅이 더 이상 오류를 표시하지 않는다고 해서 문제가 해결되었음을 확인할 수는 없습니다. 대신 다시 로드의 출력을 읽습니다:883다시 로드하면 플러그인의 현재 디렉터리에서 훅을 로드합니다. 실패는 세션당 각 훅 이벤트와 명령마다 한 번씩만 표시되므로, 훅이 조용해졌다고 해서 문제가 해결되었다고 확신할 수는 없습니다. 대신 다시 로드의 출력을 확인합니다.

878 884 

879* **오류 줄이 없는 `Reloaded:`**: 플러그인의 훅이 더 이상 누락된 디렉토리를 가리키지 않습니다.885* **오류 줄이 없는 `Reloaded:`**: 플러그인의 훅이 더 이상 누락된 디렉터리를 가리키지 않습니다

880* **`N errors during load. Run /plugin for details.`**: `/plugin`에서 **Errors** 탭을 열고 표시된 메시지에 대한 이 페이지의 항목을 따릅니다.886* **`N errors during load. Run /plugin for details.`**: `/plugin`에서 **Errors** 탭을 열고 표시된 메시지에 해당하는 이 페이지의 항목을 따릅니다

881* **`Run /reload-plugins --force to apply.`로 끝나는 줄**: 아무것도 다시 로드되지 않았으며 훅이 계속 실패합니다. Claude Code 프롬프트에서 `/reload-plugins --force`를 실행합니다.887* **`Run /reload-plugins --force to apply.`로 끝나는 줄**: 아무것도 다시 로드되지 않았으며 훅은 계속 실패합니다. Claude Code 프롬프트에서 `/reload-plugins --force`를 실행합니다

882 888 

883### `Invalid MCP server config for "<server>"` 및 시작하지 않는 MCP 서버889### `Invalid MCP server config for "<server>"` 및 시작되지 않는 MCP 서버

884 890 

885플러그인이 MCP 서버를 번들로 제공하고 **Errors** 탭이 `Invalid MCP server config for "<server>": <error>`를 표시하거나 서버가 나열되지만 `/mcp`가 연결된 것을 절대 표시하지 않습니다.891플러그인에 MCP 서버가 포함되어 있는데, **Errors** 탭에 `Invalid MCP server config for "<server>": <error>`가 표시되거나, 서버가 목록에는 있지만 `/mcp`에서 연결된 것으로 표시되지 않습니다.

886 892 

887#### `Invalid MCP server config for "<server>": <error>`893#### `Invalid MCP server config for "<server>": <error>`

888 894 

889서버의 구성이 스키마 확인을 통과하지만 Claude Code가 이 세션에 대해 해결할 수 없습니다. 콜론 뒤의 텍스트는 원인의 이름을 지정하고 수정을 결정합니다:895서버의 구성이 스키마 검사는 통과했지만, Claude Code가 이번 세션에서 이를 확인(resolve)할 수 없습니다. 콜론 뒤의 텍스트가 원인을 나타내며 수정 방법을 결정합니다.

890 896 

891* **`Missing environment variables: <names>`**: Claude Code를 시작하는 셸에서 해당 변수를 설정한 다음 새 세션을 시작합니다.897* **`Missing environment variables: <names>`**: Claude Code를 시작하는 셸에서 해당 변수를 설정한 다음 새 세션을 시작합니다

892* **`URL is unset or invalid`**: URL이 사용하는 `${user_config.*}` 옵션이 설정되지 않았습니다. `/plugin configure <plugin>`을 실행하여 설정합니다.898* **`URL is unset or invalid`**: URL이 사용하는 `${user_config.*}` 옵션이 설정되지 않았습니다. `/plugin configure <plugin>`을 실행하여 설정합니다

893* **`has an invalid MCP url`** 또는 **`headersHelper for MCP server '<server>' references ${user_config.*}`**: 플러그인 자체의 구성이 잘못되었습니다. 플러그인의 MCP 구성에서 `url` 또는 `headersHelper`를 수정하거나 플러그인이 당신의 것이 아니면 플러그인 작성자에게 보고합니다. `headersHelper` 경우는 [플러그인 명령이 user\_config를 참조](https://code.claude.com/docs/ko/errors.md#plugin-command-references-user-config) 아래에 자체 항목이 있습니다.899* **`has an invalid MCP url`** 또는 **`headersHelper for MCP server '<server>' references ${user_config.*}`**: 플러그인 자체의 구성에 문제가 있습니다. 플러그인의 MCP 구성에서 `url` 또는 `headersHelper`를 수정하거나, 직접 만든 플러그인이 아니라면 플러그인 작성자에게 보고합니다. `headersHelper`의 경우는 [plugin command references user\_config](https://code.claude.com/docs/ko/errors.md#plugin-command-references-user-config) 아래에 별도 항목이 있습니다

894 900 

895#### `Bundled MCP server "<name>" was not started: it needs configuration`901#### `Bundled MCP server "<name>" was not started: it needs configuration`

896 902 

897플러그인은 서버를 [MCPB 번들](https://code.claude.com/docs/ko/plugins/components.md#include-a-packaged-mcpb-server)로 포함하고 `user_config`를 선언하며, 필수 설정에 저장된 값이 없거나 저장된 값이 번들 자체의 유효성 검사에 실패하므로 Claude Code는 서버 시작을 건너뜁니다. 플러그인의 나머지는 작동합니다.903플러그인이 `user_config`를 선언하는 [MCPB 번들](https://code.claude.com/docs/ko/plugins/components.md#include-a-packaged-mcpb-server)로 서버를 포함하고 있는데, 필수 설정에 아직 저장된 값이 없거나 저장된 값이 번들 자체의 유효성 검사를 통과하지 못해 Claude Code가 서버 시작을 건너뜁니다. 플러그인의 나머지 부분은 작동합니다.

898 904 

899`/plugin`의 **Installed** 탭에서 플러그인을 선택하고 **Configure**를 선택하여 값을 제공합니다. 저장한 후 `/plugin`은 `Configuration saved.`를 표시하고 닫으며 Claude Code는 [설치된 플러그인 관리](https://code.claude.com/docs/ko/plugins/install.md#manage-installed-plugins) 아래에 설명된 대로 플러그인을 다시 로드합니다. 해당 다시 로드가 적용되면 서버가 시작됩니다. v2.1.285 이전에는 Claude Code가 이 줄을 표시하지 않고 서버를 건너뛰었습니다.905`/plugin`의 **Installed** 탭에서 플러그인을 선택하고 **Configure**를 선택하여 값을 입력합니다. 저장하면 `/plugin`에 `Configuration saved.`가 표시되고 닫히며, Claude Code가 [설치된 플러그인 관리](https://code.claude.com/docs/ko/plugins/install.md#manage-installed-plugins)에 설명된 대로 플러그인을 다시 로드합니다. 다시 로드가 적용되면 서버가 시작됩니다. v2.1.285 이전에는 Claude Code가 이 줄을 표시하지 않고 서버를 건너뛰었습니다.

900 906 

901#### 서버가 구성되었지만 절대 연결되지 않음907#### 서버가 구성되었지만 연결되지 않음

902 908 

903`/mcp`를 실행하여 서버의 상태를 확인합니다. 서버가 정상이면 `/mcp`는 연결된 것으로 나열합니다.909`/mcp`를 실행하여 서버의 상태를 확인합니다. 서버가 정상이면 `/mcp`에 연결된 것으로 나열됩니다.

904 910 

905서버가 시작되는 동안 인쇄한 오류를 읽으려면 `claude --debug`를 실행하고 `~/.claude/debug/<session-id>.txt`에서 로그를 엽니다. `--debug` 플래그는 터미널에 인쇄하지 않습니다.911서버가 시작 중에 출력한 오류를 읽으려면 `claude --debug`를 실행하고 `~/.claude/debug/<session-id>.txt`에 있는 로그를 엽니다. `--debug` 플래그는 터미널에 출력하지 않습니다.

906 912 

907> [!NOTE]913> [!NOTE]

908>914>

909> `claude --debug`를 실행하기 전 15분 이내에 [플러그인의 stdio 서버](https://code.claude.com/docs/ko/mcp.md#plugin-provided-mcp-servers) 연결이 실패한 경우 Claude Code는 [서버를 시작하지 않습니다](https://code.claude.com/docs/ko/errors.md#skipping-connection-recent-failure-cached). 새 세션에서 `/mcp`의 서버 메뉴에서 **Reconnect**를 선택하여 서버를 시작한 다음 로그를 엽니다.915> `claude --debug`를 실행하기 전 15분 이내에 [플러그인의 stdio 서버](https://code.claude.com/docs/ko/mcp.md#plugin-provided-mcp-servers) 연결이 실패한 경우, Claude Code는 [서버를 시작하지 않습니다](https://code.claude.com/docs/ko/errors.md#skipping-connection-recent-failure-cached). 새 세션에서 `/mcp`의 서버 메뉴에서 **Reconnect**를 선택하여 서버를 시작한 다음 로그를 엽니다.

910 916 

911`.mcp.json`의 서버 항목이 스키마가 실패하면 **Errors** 탭에 나타나지 않습니다. Claude Code는 해당 서버를 삭제하고 `Invalid MCP server config for <server> in <path>`만 해당 디버그 로그에 기록합니다. 플러그인을 로드하지 않고 항목을 찾으려면 플러그인 디렉토리에서 셸에서 `claude plugin validate`를 실행합니다. 이는 오류로 보고합니다.917스키마를 통과하지 못한 `.mcp.json`의 서버 항목은 **Errors** 탭에 나타나지 않습니다. Claude Code는 해당 서버를 제외하고 `Invalid MCP server config for <server> in <path>`를 해당 디버그 로그에만 기록합니다. 플러그인을 로드하지 않고 해당 항목을 찾으려면 셸에서 플러그인 디렉터리에 대해 `claude plugin validate`를 실행합니다. 이 명령은 해당 항목을 오류로 보고합니다.

912 918 

913v2.1.281 이전에는 `claude plugin validate`가 `.mcp.json`을 확인하지 않았습니다.919v2.1.281 이전에는 `claude plugin validate`가 `.mcp.json`을 검사하지 않았습니다.

914 920 

915#### 서버가 `--plugin-dir`로 작동하지만 설치 후 실패921#### `--plugin-dir`로는 서버가 작동하지만 설치 후에는 실패함

916 922 

917플러그인의 작성자이고 서버가 `--plugin-dir`로 소스 디렉토리에서 플러그인을 로드할 때 시작되지만 설치 후 실패합니다.923플러그인 작성자로서 `--plugin-dir`를 사용해 소스 디렉터리에서 플러그인을 로드하면 서버가 시작되지만, 플러그인을 설치하면 실패합니다.

918 924 

919Claude Code는 설치된 플러그인을 캐시로 복사하므로 소스 디렉토리에서만 작동하는 경로가 중단됩니다. `${CLAUDE_PLUGIN_ROOT}`로 플러그인 내부의 경로를 작성합니다.925Claude Code는 설치된 플러그인을 캐시에 복사하므로, 소스 디렉터리에서만 작동하는 경로는 깨집니다. 플러그인 내부의 경로는 `${CLAUDE_PLUGIN_ROOT}`를 사용하여 작성합니다.

920 926 

921플러그인 디렉토리 외부에 도달하는 경로의 경우 [플러그인이 참조하는 파일이 디렉토리 외부에서 찾을 수 없음](#files-the-plugin-references-outside-its-directory-arent-found)을 참조합니다.927플러그인 디렉터리 외부를 가리키는 경로에 대해서는 [플러그인이 디렉터리 외부에서 참조하는 파일을 찾을 수 없음](#files-the-plugin-references-outside-its-directory-arent-found)을 참조합니다.

922 928 

923### 언어 서버가 시작되지 않거나 너무 많은 메모리를 사용하거나 잘못된 진단을 보고929### 언어 서버가 시작되지 않거나, 메모리를 너무 많이 사용하거나, 잘못된 진단을 보고함

924 930 

925[코드 인텔리전스 플러그인](https://code.claude.com/docs/ko/plugins/code-intelligence.md)을 설치했고 Claude가 진단을 보지 못하거나 언어 서버가 너무 많은 메모리를 사용하거나 실제가 아닌 오류를 보고합니다.931[코드 인텔리전스 플러그인](https://code.claude.com/docs/ko/plugins/code-intelligence.md)을 설치했지만 Claude가 진단을 보지 못하거나, 언어 서버가 메모리를 너무 많이 사용하거나 실제가 아닌 오류를 보고합니다.

926 932 

927#### 언어 서버가 시작되지 않음933#### 언어 서버가 시작되지 않음

928 934 

929플러그인은 별도로 설치하는 언어 서버 바이너리에 연결되고 Claude Code는 `PATH`에서 명령 이름으로 생성합니다.935플러그인은 별도로 설치하는 언어 서버 바이너리에 연결하며, Claude Code는 `PATH`에서 명령 이름으로 이를 실행합니다.

930 936 

931`/plugin` **Errors** 탭은 `Executable not found in $PATH: "<binary>"`와 같은 이유와 함께 실패를 표시하고 `claude --debug`는 `LSP server <name> failed to start: <reason>`으로 로그합니다.937`/plugin`의 **Errors** 탭에 `Executable not found in $PATH: "<binary>"`와 같은 이유와 함께 실패가 표시되며, `claude --debug`는 이를 `LSP server <name> failed to start: <reason>`으로 로그에 기록합니다.

932 938 

933바이너리를 설치하고 `claude`를 시작하는 터미널의 `PATH`에 있는지 확인합니다(예: `which typescript-language-server`). 그런 다음 새 세션을 시작합니다.939바이너리를 설치하고, 예를 들어 `which typescript-language-server`로 `claude`를 시작하는 터미널의 `PATH`에 있는지 확인합니다. 그런 다음 새 세션을 시작합니다.

934 940 

935#### 언어 서버가 너무 많은 메모리를 사용941#### 언어 서버가 메모리를 너무 많이 사용함

936 942 

937`rust-analyzer` 및 `pyright`와 같은 언어 서버는 전체 프로젝트를 인덱싱합니다. 세션에서 `/plugin disable <plugin>`으로 플러그인을 비활성화하고 대신 Claude의 기본 제공 검색 도구에 의존합니다.943`rust-analyzer`와 `pyright` 같은 언어 서버는 프로젝트 전체를 인덱싱합니다. 세션에서 `/plugin disable <plugin>`으로 플러그인을 비활성화하고 대신 Claude의 기본 제공 검색 도구를 사용합니다.

938 944 

939#### 모노레포의 거짓 양성 진단945#### 모노레포에서의 잘못된 진단(false positive)

940 946 

941작업 공간에 대해 구성되지 않은 언어 서버는 내부 패키지에 대해 확인되지 않은 가져오기를 보고할 수 있습니다. Claude Code 측에서 수정할 것이 없으며 진단이 Claude가 코드를 편집하는 것을 중단하지 않습니다.947워크스페이스에 맞게 구성되지 않은 언어 서버는 내부 패키지에 대해 해결되지 않은 import를 보고할 수 있습니다. Claude Code 측에서 수정할 사항은 없으며, 이러한 진단이 Claude의 코드 편집을 막지는 않습니다.

942 948 

943## 플러그인 만들기949## 플러그인 만들기

944 950 

Details

103[빠른 모드](https://code.claude.com/docs/ko/fast-mode.md)와 표준 속도는 별도의 캐시를 유지하므로, 빠른 모드를 켜거나 끈 후 다음 요청은 다른 속도에서 캐시한 내용을 사용할 수 없습니다. 대화에서 처음으로 빠른 모드를 켜면 다음 요청은 지금까지의 전체 대화를 캐시 없이 [빠른 모드 요금](https://code.claude.com/docs/ko/fast-mode.md#understand-the-cost-tradeoff)으로 읽습니다. 이 비용을 작게 유지하려면 세션을 시작할 때 빠른 모드를 켭니다.103[빠른 모드](https://code.claude.com/docs/ko/fast-mode.md)와 표준 속도는 별도의 캐시를 유지하므로, 빠른 모드를 켜거나 끈 후 다음 요청은 다른 속도에서 캐시한 내용을 사용할 수 없습니다. 대화에서 처음으로 빠른 모드를 켜면 다음 요청은 지금까지의 전체 대화를 캐시 없이 [빠른 모드 요금](https://code.claude.com/docs/ko/fast-mode.md#understand-the-cost-tradeoff)으로 읽습니다. 이 비용을 작게 유지하려면 세션을 시작할 때 빠른 모드를 켭니다.

104 104 

105* Claude가 작업 중일 때 켜면 해당 턴은 표준 속도로 완료되며, 캐시되지 않은 읽기 비용은 다음 턴의 첫 번째 요청에서 지불합니다.105* Claude가 작업 중일 때 켜면 해당 턴은 표준 속도로 완료되며, 캐시되지 않은 읽기 비용은 다음 턴의 첫 번째 요청에서 지불합니다.

106* 현재 모델이 빠른 모드를 지원하지 않으면 `/fast`를 실행할 때 [Opus로도 전환](https://code.claude.com/docs/ko/fast-mode.md#toggle-fast-mode)됩니다. 이 [모델 전환](#switching-models)은 실행 중인 턴의 다음 요청부터 자체적으로 새로운 캐시를 시작합니다.106* 현재 모델이 빠른 모드를 지원하지 않으면 `/fast`를 실행할 때 [모델도 전환](https://code.claude.com/docs/ko/fast-mode.md#toggle-fast-mode)됩니다. 이 [모델 전환](#switching-models)은 실행 중인 턴의 다음 요청부터 자체적으로 새로운 캐시를 시작합니다.

107 107 

108이후의 각 토글은 전환하는 속도에 캐시되어 있지 않은 내용을 캐시 없이 읽습니다. 속도 제한 후 [표준 속도로 폴백](https://code.claude.com/docs/ko/fast-mode.md#handle-rate-limits)하고 나중에 빠른 모드로 돌아가는 것처럼 Claude Code가 자체적으로 수행하는 속도 변경도 토글로 간주됩니다.108이후의 각 토글은 전환하는 속도에 캐시되어 있지 않은 내용을 캐시 없이 읽습니다. 속도 제한 후 [표준 속도로 폴백](https://code.claude.com/docs/ko/fast-mode.md#handle-rate-limits)하고 나중에 빠른 모드로 돌아가는 것처럼 Claude Code가 자체적으로 수행하는 속도 변경도 토글로 간주됩니다.

109 109 

Details

185* **Effort 수준**: 연결된 기기에서 `/effort` 또는 기기의 effort 컨트롤로 [effort 수준](https://code.claude.com/docs/ko/model-config.md#adjust-effort-level)을 설정하면 Claude Code는 사용자 머신의 세션에 이를 적용합니다. `CLAUDE_CODE_EFFORT_LEVEL`로 수준을 고정한 경우 세션은 해당 수준을 유지하며, Claude Code는 effort 컨트롤에서 다른 값을 선택해도 거부합니다. effort 컨트롤에서 수준을 선택하려면 사용자 머신에 Claude Code v2.1.234 이상이 필요합니다.185* **Effort 수준**: 연결된 기기에서 `/effort` 또는 기기의 effort 컨트롤로 [effort 수준](https://code.claude.com/docs/ko/model-config.md#adjust-effort-level)을 설정하면 Claude Code는 사용자 머신의 세션에 이를 적용합니다. `CLAUDE_CODE_EFFORT_LEVEL`로 수준을 고정한 경우 세션은 해당 수준을 유지하며, Claude Code는 effort 컨트롤에서 다른 값을 선택해도 거부합니다. effort 컨트롤에서 수준을 선택하려면 사용자 머신에 Claude Code v2.1.234 이상이 필요합니다.

186* **연결 실패 후 다시 연결**: `/remote-control`을 실행하여 다시 연결합니다. 그 사이에 압축으로 대화가 다시 작성되었거나 `/resume`으로 대화를 전환한 경우, Claude Code는 사용하던 서버 세션을 세션 목록에 남겨 두는 대신 보관 처리합니다. claude.ai/code의 [보관된 세션](https://code.claude.com/docs/ko/claude-code-on-the-web.md#find-an-archived-session)에서 해당 세션을 여전히 찾을 수 있습니다. 기기가 연결된 상태에서 대화를 전환하면 세션이 보관 처리되지 않습니다.186* **연결 실패 후 다시 연결**: `/remote-control`을 실행하여 다시 연결합니다. 그 사이에 압축으로 대화가 다시 작성되었거나 `/resume`으로 대화를 전환한 경우, Claude Code는 사용하던 서버 세션을 세션 목록에 남겨 두는 대신 보관 처리합니다. claude.ai/code의 [보관된 세션](https://code.claude.com/docs/ko/claude-code-on-the-web.md#find-an-archived-session)에서 해당 세션을 여전히 찾을 수 있습니다. 기기가 연결된 상태에서 대화를 전환하면 세션이 보관 처리되지 않습니다.

187 187 

188### 브라우저에서 세션 분기하기

189 

190세션을 중단하지 않고 다른 방향을 시도하려면 [claude.ai/code](https://claude.ai/code)에서 세션을 열고 세션 메뉴에서 **Fork**를 선택하거나, 트랜스크립트의 이전 메시지에서 분기합니다. 분기된 세션은 세션 목록에 새 세션으로 열리고 해당 지점부터 대화를 이어 가며, 원래 세션은 계속 실행됩니다. 분기하려면 사용자 머신에 Claude Code v2.1.277 이상이 필요합니다.

191 

192`--spawn session`으로 시작한 `claude remote-control` 서버는 세션 하나만 수용할 수 있으므로 분기된 세션을 실행할 수 없습니다.

193 

194Claude Code는 다음과 같은 경우 분기를 거부합니다.

195 

196* 세션이 사용 중인 경우. 세션이 유휴 상태일 때 분기합니다.

197* 세션이 VS Code 확장 프로그램 또는 [Agent SDK](https://code.claude.com/docs/ko/agent-sdk/overview.md)로 빌드된 다른 앱에서 호스팅되는 경우.

198 

188### 모든 세션에서 Remote Control 활성화하기199### 모든 세션에서 Remote Control 활성화하기

189 200 

190자동 연결이 켜져 있지 않으면 Remote Control은 `claude remote-control`, `claude --remote-control` 또는 `/remote-control`을 명시적으로 실행할 때만 활성화됩니다. 모든 대화형 세션에서 자동 연결을 켜려면 Claude Code에서 `/config`를 실행하고 **Enable Remote Control for all sessions**를 설정합니다. 이 토글은 세 가지 값을 가집니다.201자동 연결이 켜져 있지 않으면 Remote Control은 `claude remote-control`, `claude --remote-control` 또는 `/remote-control`을 명시적으로 실행할 때만 활성화됩니다. 모든 대화형 세션에서 자동 연결을 켜려면 Claude Code에서 `/config`를 실행하고 **Enable Remote Control for all sessions**를 설정합니다. 이 토글은 세 가지 값을 가집니다.

198* **VS Code 확장 프로그램**: [명령 메뉴](https://code.claude.com/docs/ko/vs-code.md#use-the-prompt-box)의 Settings 섹션에 있는 **Enable Remote Control for all sessions**.209* **VS Code 확장 프로그램**: [명령 메뉴](https://code.claude.com/docs/ko/vs-code.md#use-the-prompt-box)의 Settings 섹션에 있는 **Enable Remote Control for all sessions**.

199* **Desktop 앱**: **Settings > Code** 또는 **Settings > Claude Code**에 있는 **Connect new sessions to Remote Control**. [다른 기기에 표시되는 세션 제어하기](https://code.claude.com/docs/ko/desktop.md#control-which-sessions-appear-on-your-other-devices)를 참조하세요.210* **Desktop 앱**: **Settings > Code** 또는 **Settings > Claude Code**에 있는 **Connect new sessions to Remote Control**. [다른 기기에 표시되는 세션 제어하기](https://code.claude.com/docs/ko/desktop.md#control-which-sessions-appear-on-your-other-devices)를 참조하세요.

200 211 

201대신 설정 파일에서 자동 연결을 켜려면 사용자 `~/.claude/settings.json` 또는 [관리형 설정](https://code.claude.com/docs/ko/managed-settings.md)에서 [`remoteControlAtStartup`](https://code.claude.com/docs/ko/settings-reference#remotecontrolatstartup)을 `true`로 설정합니다. 프로젝트 또는 로컬 설정(`.claude/settings.json`, `.claude/settings.local.json`)에서는 Claude Code가 `false`를 적용하여 해당 저장소의 자동 연결을 끄지만 `true`는 무시하므로, 체크인된 파일로 저장소를 여는 모든 사람에게 Remote Control을 켤 수는 없습니다.212대신 설정 파일에서 자동 연결을 켜려면 사용자 `~/.claude/settings.json` 또는 [관리형 설정](https://code.claude.com/docs/ko/managed-settings.md)에서 [`remoteControlAtStartup`](https://code.claude.com/docs/ko/settings-reference#remotecontrolatstartup)을 `true`로 설정합니다. 프로젝트 또는 로컬 설정(`.claude/settings.json`, `.claude/settings.local.json`)에서는 Claude Code가 `false`를 적용하여 해당 저장소의 자동 연결을 끕니다. `true`는 무시하므로, 체크인된 파일로 저장소를 여는 모든 사람에게 Remote Control을 켤 수는 없습니다.

202 213 

203자동 연결은 사용자 자신의 claude.ai 계정으로 로그인하므로, 자동 연결로 시작된 세션은 사용자 본인 계정의 Claude 앱에만 표시되며 다른 누구에게도 접근 권한을 부여하지 않습니다.214자동 연결은 사용자 자신의 claude.ai 계정으로 로그인하므로, 자동 연결로 시작된 세션은 사용자 본인 계정의 Claude 앱에만 표시되며 다른 누구에게도 접근 권한을 부여하지 않습니다.

204 215 

routines.md +1 −1

Details

528* [`/loop` 및 세션 내 예약](https://code.claude.com/docs/ko/scheduled-tasks): 열려 있는 CLI 세션 내에서 로컬 작업 예약528* [`/loop` 및 세션 내 예약](https://code.claude.com/docs/ko/scheduled-tasks): 열려 있는 CLI 세션 내에서 로컬 작업 예약

529* [데스크톱 예약 작업](https://code.claude.com/docs/ko/desktop-scheduled-tasks.md): 로컬 파일에 액세스할 수 있는 사용자의 머신에서 실행되는 로컬 예약 작업529* [데스크톱 예약 작업](https://code.claude.com/docs/ko/desktop-scheduled-tasks.md): 로컬 파일에 액세스할 수 있는 사용자의 머신에서 실행되는 로컬 예약 작업

530* [클라우드 환경](https://code.claude.com/docs/ko/cloud-environments.md): 클라우드 세션의 네트워크 액세스, 환경 변수 및 설정 스크립트 구성530* [클라우드 환경](https://code.claude.com/docs/ko/cloud-environments.md): 클라우드 세션의 네트워크 액세스, 환경 변수 및 설정 스크립트 구성

531* [프로젝트](https://code.claude.com/docs/ko/claude-projects.md): Claude가 병렬 클라우드 세션 전반에서 조율하는 진행 중인 작업이며, 프로젝트에서 만든 예약 작업은 해당 프로젝트의 **Scheduled tasks** 탭에 나타납니다531* [프로젝트](https://code.claude.com/docs/ko/claude-projects.md): Claude가 병렬 클라우드 세션 전반에서 조율하는 진행 중인 작업이며, 프로젝트에서 만든 예약 작업은 해당 프로젝트의 **Scheduled tasks** 보기에 나타납니다

532* [MCP 커넥터](https://code.claude.com/docs/ko/mcp.md): Slack, Linear, Google Drive와 같은 외부 서비스 연결532* [MCP 커넥터](https://code.claude.com/docs/ko/mcp.md): Slack, Linear, Google Drive와 같은 외부 서비스 연결

533* [GitHub Actions](https://code.claude.com/docs/ko/github-actions.md): 저장소 이벤트 발생 시 CI 파이프라인에서 Claude 실행533* [GitHub Actions](https://code.claude.com/docs/ko/github-actions.md): 저장소 이벤트 발생 시 CI 파이프라인에서 Claude 실행

sandboxing.md +4 −0

Details

903 903 

904실패 후 Claude는 [명령을 샌드박스 외부에서 다시 실행하도록 제안](#the-unsandboxed-retry-escape-hatch)할 수 있습니다. 해당 재시도를 승인하거나 다른 터미널에서 git 명령을 직접 실행합니다. `allowUnsandboxedCommands`를 `false`로 설정한 경우 Claude는 재시도를 제안할 수 없으므로 명령을 직접 실행합니다.904실패 후 Claude는 [명령을 샌드박스 외부에서 다시 실행하도록 제안](#the-unsandboxed-retry-escape-hatch)할 수 있습니다. 해당 재시도를 승인하거나 다른 터미널에서 git 명령을 직접 실행합니다. `allowUnsandboxedCommands`를 `false`로 설정한 경우 Claude는 재시도를 제안할 수 없으므로 명령을 직접 실행합니다.

905 905 

906### git 명령이 `Unable to create '…/index.lock'`로 실패

907 

908저장소의 하위 디렉터리에서 Claude Code를 시작한 경우, 이 오류는 `.git`이 [샌드박싱된 명령이 쓸 수 있는 범위](#filesystem-isolation) 밖에 있다는 의미일 수 있습니다. 대신 저장소 루트에서 Claude Code를 시작하거나, [연결된 worktree](https://code.claude.com/docs/ko/worktrees.md)에서는 워크트리의 루트에서 시작합니다.

909 

906### `objects` 또는 `refs`라는 폴더가 명령 후 사라짐910### `objects` 또는 `refs`라는 폴더가 명령 후 사라짐

907 911 

908세션 중에 나타난 최상위 `objects` 또는 `refs` 폴더는 [샌드박싱된 명령이 끝난 후 삭제될](#when-the-sandbox-deletes-head-objects-or-refs) 수 있습니다. 명령, Claude, 사용자 중 누가 만들었는지는 관계없습니다. 폴더를 유지하려면 폴더 안에 무언가를 남겨 둡니다. 세션 중에 `HEAD` 파일이나 심볼릭 링크가 최상위에 있었다면 이를 다른 곳으로 옮긴 다음, 해당 작업 디렉터리에서 열려 있는 모든 Claude Code 세션을 다시 시작합니다.912세션 중에 나타난 최상위 `objects` 또는 `refs` 폴더는 [샌드박싱된 명령이 끝난 후 삭제될](#when-the-sandbox-deletes-head-objects-or-refs) 수 있습니다. 명령, Claude, 사용자 중 누가 만들었는지는 관계없습니다. 폴더를 유지하려면 폴더 안에 무언가를 남겨 둡니다. 세션 중에 `HEAD` 파일이나 심볼릭 링크가 최상위에 있었다면 이를 다른 곳으로 옮긴 다음, 해당 작업 디렉터리에서 열려 있는 모든 Claude Code 세션을 다시 시작합니다.

Details

54}54}

55```55```

56 56 

57또한 각 팀원은 클론마다 한 번씩 [`claude plugin install security-guidance@claude-plugins-official --scope project`를 실행합니다](https://code.claude.com/docs/ko/plugins/loading#enabled-in-project-settings-but-not-installed).

58 

57관리자는 [관리 설정](https://code.claude.com/docs/ko/admin-setup.md)에서 [`enabledPlugins`](https://code.claude.com/docs/ko/settings-reference#enabledplugins)를 설정하여 조직 전체에서 플러그인을 활성화할 수 있습니다.59관리자는 [관리 설정](https://code.claude.com/docs/ko/admin-setup.md)에서 [`enabledPlugins`](https://code.claude.com/docs/ko/settings-reference#enabledplugins)를 설정하여 조직 전체에서 플러그인을 활성화할 수 있습니다.

58 60 

59## 플러그인이 확인하는 것61## 플러그인이 확인하는 것

135patterns:137patterns:

136 - rule_name: internal_api_key138 - rule_name: internal_api_key

137 substrings: ["sk_live_", "AKIA"]139 substrings: ["sk_live_", "AKIA"]

138 reminder: "하드코딩된 API 키 접두사. 비밀 관리자에서 자격 증명을 로드합니다."140 reminder: "Hardcoded API key prefix. Load credentials from the secret manager."

139 - rule_name: tenant_unfiltered_query141 - rule_name: tenant_unfiltered_query

140 regex: "\\.objects\\.all\\(\\)"142 regex: "\\.objects\\.all\\(\\)"

141 paths: ["**/src/tenants/**"]143 paths: ["**/src/tenants/**"]

142 reminder: "다중 테넌트 코드는 org_id로 필터링해야 합니다."144 reminder: "Multi-tenant code must filter by org_id."

143```145```

144 146 

145| 필드 | 유형 | 설명 |147| 필드 | 유형 | 설명 |

Details

235set -u235set -u

236export GIT_ALLOW_PROTOCOL=${GIT_ALLOW_PROTOCOL:-https:http:ssh}236export GIT_ALLOW_PROTOCOL=${GIT_ALLOW_PROTOCOL:-https:http:ssh}

237IFS=':'237IFS=':'

238rc=0 # becomes 1 when a step fails; a non-zero exit makes the runner log it

238# -c overrides beat repo-local settings, blocking session-written fsmonitor,239# -c overrides beat repo-local settings, blocking session-written fsmonitor,

239# hook-path, and gpg-program config from executing code with the hook's240# hook-path, and gpg-program config from executing code with the hook's

240# privileges. -c commit.gpgsign=false also leaves these rescue commits241# privileges. -c commit.gpgsign=false also leaves these rescue commits

245g() { git -c core.fsmonitor=false -c core.hooksPath=/dev/null \246g() { git -c core.fsmonitor=false -c core.hooksPath=/dev/null \

246 -c commit.gpgsign=false "$@"; }247 -c commit.gpgsign=false "$@"; }

247for ws in $CLAUDE_RUNNER_WORKSPACE_PATHS; do248for ws in $CLAUDE_RUNNER_WORKSPACE_PATHS; do

248 cd "$ws" 2>/dev/null || continue249 cd "$ws" || { rc=1; continue; }

249 [ -z "$(g status --porcelain 2>/dev/null)" ] && continue250 g add -A || rc=1

250 g add -A251 g diff-index --cached --quiet HEAD && continue # nothing to save

251 g commit -q -m "runner snapshot: $CLAUDE_RUNNER_SESSION_ID ($CLAUDE_RUNNER_EXIT_REASON)" || continue252 g commit -q -m "runner snapshot: $CLAUDE_RUNNER_SESSION_ID ($CLAUDE_RUNNER_EXIT_REASON)" || { rc=1; continue; }

252 g push -q origin "HEAD:refs/heads/rescue/$CLAUDE_RUNNER_SESSION_ID" || true253 g push -q origin "HEAD:refs/heads/rescue/$CLAUDE_RUNNER_SESSION_ID" || rc=1

253done254done

255exit "$rc"

254```256```

255 257 

256스크립트의 `GIT_ALLOW_PROTOCOL` 줄은 git을 HTTPS, HTTP, SSH 원격으로 제한합니다. 러너 환경에 이미 비어 있지 않은 자체 `GIT_ALLOW_PROTOCOL` 목록이 설정되어 있으면 스크립트는 해당 목록을 유지합니다.258스크립트의 `GIT_ALLOW_PROTOCOL` 줄은 git을 HTTPS, HTTP, SSH 원격으로 제한합니다. 러너 환경에 이미 비어 있지 않은 자체 `GIT_ALLOW_PROTOCOL` 목록이 설정되어 있으면 스크립트는 해당 목록을 유지합니다.

Details

23 * **[Anthropic 관리형 git](#use-the-anthropic-git-proxy) 사용 시**: 이러한 자격 증명이 있으면 Claude는 Anthropic 관리형 git을 거치지 않고 GitHub에 직접 접근합니다.23 * **[Anthropic 관리형 git](#use-the-anthropic-git-proxy) 사용 시**: 이러한 자격 증명이 있으면 Claude는 Anthropic 관리형 git을 거치지 않고 GitHub에 직접 접근합니다.

24 * **Anthropic 관리형 git 미사용 시**: [이미지에 git 구성 포함](#ship-git-config-in-your-image)에서 설명하는 만큼 범위를 엄격하게 제한하면 클론 자격 증명을 이미지에 유지할 수 있습니다.24 * **Anthropic 관리형 git 미사용 시**: [이미지에 git 구성 포함](#ship-git-config-in-your-image)에서 설명하는 만큼 범위를 엄격하게 제한하면 클론 자격 증명을 이미지에 유지할 수 있습니다.

25* **세션 실행 호스트에서 환경 시크릿 분리**: 환경 시크릿은 러너를 등록하고 환경에 대기 중인 모든 세션을 선택할 수 있습니다. 고정 플릿에서는 모든 러너 호스트에 있으며, 모든 세션의 코드가 시크릿 파일을 읽을 수 있습니다. [온디맨드 러너](https://code.claude.com/docs/ko/self-hosted-environments-configuration.md#on-demand-runners)를 선호하세요. 여기서 시크릿은 사용자 코드를 실행하지 않는 오케스트레이터 호스트에 유지되며, 각 러너는 정확히 하나의 러너를 등록하는 단일 사용 작업 주문을 받습니다. 고정 플릿에서는 환경 시크릿 파일을 모든 세션이 읽을 수 있는 것으로 취급하고 의심되는 세션 손상 후 시크릿을 회전하세요.25* **세션 실행 호스트에서 환경 시크릿 분리**: 환경 시크릿은 러너를 등록하고 환경에 대기 중인 모든 세션을 선택할 수 있습니다. 고정 플릿에서는 모든 러너 호스트에 있으며, 모든 세션의 코드가 시크릿 파일을 읽을 수 있습니다. [온디맨드 러너](https://code.claude.com/docs/ko/self-hosted-environments-configuration.md#on-demand-runners)를 선호하세요. 여기서 시크릿은 사용자 코드를 실행하지 않는 오케스트레이터 호스트에 유지되며, 각 러너는 정확히 하나의 러너를 등록하는 단일 사용 작업 주문을 받습니다. 고정 플릿에서는 환경 시크릿 파일을 모든 세션이 읽을 수 있는 것으로 취급하고 의심되는 세션 손상 후 시크릿을 회전하세요.

26 * **손상이 의심되는 경우**: [Owner](https://code.claude.com/docs/ko/cloud-environments.md#organization-shared-environments)가 환경의 **구성** 탭에서 새 시크릿을 생성하고 이전 시크릿을 취소하도록 한 다음, 새 시크릿을 배포하세요. Anthropic은 이전 시크릿의 작업 주문으로 실행된 온디맨드 러너를 포함하여 이전 시크릿을 사용하는 모든 오케스트레이터와 러너를 거부합니다. 러너가 종료되며, 해당 세션이 중단됩니다.26 * **손상이 의심되는 경우 먼저 의심되는 세션 취소**: 해당 러너를 중지하거나 시크릿을 취소하기 전에 **활동** 탭의 세션 메뉴에서 **토큰 취소**를 선택하세요. 그러면 어떤 러너도 해당 세션을 재개할 수 없습니다.

27 * **그런 다음 시크릿 교체**: [Owner](https://code.claude.com/docs/ko/cloud-environments.md#organization-shared-environments)가 환경의 **구성** 탭에서 새 시크릿을 생성하고 이전 시크릿을 취소하도록 한 다음, 새 시크릿을 배포하세요. Anthropic은 이전 시크릿의 작업 주문으로 실행된 온디맨드 러너를 포함하여 이전 시크릿을 사용하는 모든 오케스트레이터와 러너를 거부합니다. 러너가 종료되며, 해당 세션이 중단됩니다.

27* **기본 거부 네트워크 이그레스**: 모든 환경에서 네트워크 경계에서 러너 및 세션 컨테이너 아웃바운드 트래픽을 제한하세요. [기본 거부 이그레스](#default-deny-egress)에서 허용할 항목과 이유를 다룹니다.28* **기본 거부 네트워크 이그레스**: 모든 환경에서 네트워크 경계에서 러너 및 세션 컨테이너 아웃바운드 트래픽을 제한하세요. [기본 거부 이그레스](#default-deny-egress)에서 허용할 항목과 이유를 다룹니다.

28* **최소 권한 호스트 IAM**: 러너 호스트에 연결된 컴퓨팅 ID(예: 인스턴스 프로필 또는 노드 서비스 계정)는 러너 자체가 필요한 것만 부여해야 합니다. 세션은 호스트의 ID를 상속하는 대신 래퍼 스크립트를 통해 자신의 자격증명을 얻어야 합니다.29* **최소 권한 호스트 IAM**: 러너 호스트에 연결된 컴퓨팅 ID(예: 인스턴스 프로필 또는 노드 서비스 계정)는 러너 자체가 필요한 것만 부여해야 합니다. 세션은 호스트의 ID를 상속하는 대신 래퍼 스크립트를 통해 자신의 자격증명을 얻어야 합니다.

29* **세션에서 클라우드 메타데이터 엔드포인트 차단**: 세션을 호스트 ID에서 벗어나게 유지하려면 클라우드 메타데이터 엔드포인트에 대한 액세스를 차단해야 하며, 서브넷 수준 이그레스 정책은 링크 로컬 메타데이터 트래픽을 가로채지 않으므로 컨테이너 자체에서 차단하세요:30* **세션에서 클라우드 메타데이터 엔드포인트 차단**: 세션을 호스트 ID에서 벗어나게 유지하려면 클라우드 메타데이터 엔드포인트에 대한 액세스를 차단해야 하며, 서브넷 수준 이그레스 정책은 링크 로컬 메타데이터 트래픽을 가로채지 않으므로 컨테이너 자체에서 차단하세요:

243 244 

244Claude Code v2.1.267 이상의 러너는 각 세션에 대해 Anthropic이 세션의 git을 제공하는 경우 `governed git ACTIVE`를 포함하는 `[runner:session]` 라인을, 제공하지 않는 경우 `the server withheld Anthropic-managed git for this session`을 포함하는 `[runner:warn]` 라인 하나를 로그에 기록합니다. 다음 경우 중에서 보고 있는 라인을 찾으세요:245Claude Code v2.1.267 이상의 러너는 각 세션에 대해 Anthropic이 세션의 git을 제공하는 경우 `governed git ACTIVE`를 포함하는 `[runner:session]` 라인을, 제공하지 않는 경우 `the server withheld Anthropic-managed git for this session`을 포함하는 `[runner:warn]` 라인 하나를 로그에 기록합니다. 다음 경우 중에서 보고 있는 라인을 찾으세요:

245 246 

246* **`governed git ACTIVE`와 `withheld` 라인 모두 없음**: Claude Code v2.1.267 이전의 러너는 두 라인 모두 기록하지 않으며, Anthropic은 해당 세션을 제공하지 않습니다. [버전 고정](#pin-the-version)에 따라 러너를 v2.1.267 이상으로 업데이트하세요.247* **`governed git ACTIVE`와 `withheld` 라인 모두 없음**: 러너가 Claude Code v2.1.267보다 오래된 버전이면 Anthropic은 해당 세션을 제공하지 않습니다. [버전 고정](#pin-the-version)에 따라 러너를 v2.1.267 이상으로 업데이트하세요.

247* **`withheld` 라인**: Anthropic이 세션을 제공하지 않았습니다. 이전에 git 프록시로 작동하던 러너도 사용자 측의 변경 없이 이런 방식으로 실패할 수 있습니다.248* **`withheld` 라인**: Anthropic이 세션을 제공하지 않았습니다. 이전에 git 프록시로 작동하던 러너도 사용자 측의 변경 없이 이런 방식으로 실패할 수 있습니다.

248 * **저장소가 github.com에 없음**: GitHub Enterprise Server와 같은 다른 git 호스트에 저장소가 하나라도 있는 세션은 해당 github.com 저장소를 포함하여 제공되지 않습니다. 해당 환경의 러너에 대해 [Anthropic git 프록시를 끄세요](#turn-the-anthropic-git-proxy-off).249 * **저장소가 github.com에 없음**: GitHub Enterprise Server와 같은 다른 git 호스트에 저장소가 하나라도 있는 세션은 해당 github.com 저장소를 포함하여 제공되지 않습니다. 해당 환경의 러너에 대해 [Anthropic git 프록시를 끄세요](#turn-the-anthropic-git-proxy-off).

249 * **모든 저장소가 github.com에 있음**: `withheld` 라인의 세션 ID와 함께 [Anthropic 계정 팀](#report-an-issue)에 실패를 보고하세요. Anthropic은 자체 측에서 이유를 기록합니다.250 * **모든 저장소가 github.com에 있음**: `withheld` 라인의 세션 ID와 함께 [Anthropic 계정 팀](#report-an-issue)에 실패를 보고하세요. Anthropic은 자체 측에서 이유를 기록합니다.

396노드가 ARM인 경우 `linux-x64`를 `linux-arm64`로 바꾸거나, Alpine과 같은 musl 기반 이미지에서 `linux-x64-musl` 또는 `linux-arm64-musl`로 바꾸세요. musl 이미지가 필요로 하는 추가 패키지는 [Alpine Linux 설정](https://code.claude.com/docs/ko/setup.md#alpine-linux-and-musl-based-distributions)을 참조하세요. URL은 표준 Claude Code 릴리스 위치이므로 [바이너리 무결성 및 코드 서명](https://code.claude.com/docs/ko/setup.md#binary-integrity-and-code-signing)에 설명된 대로 릴리스의 서명된 매니페스트에 대해 다운로드된 바이너리를 확인할 수 있습니다. 러너는 Claude Code 버전 2.1.224 이상이 필요하며, Claude Tag 세션을 제공하려면 2.1.229 이상이 필요합니다. 이미지를 빌드한 다음 레지스트리로 푸시하고 아래 레시피에서 참조하세요:397노드가 ARM인 경우 `linux-x64`를 `linux-arm64`로 바꾸거나, Alpine과 같은 musl 기반 이미지에서 `linux-x64-musl` 또는 `linux-arm64-musl`로 바꾸세요. musl 이미지가 필요로 하는 추가 패키지는 [Alpine Linux 설정](https://code.claude.com/docs/ko/setup.md#alpine-linux-and-musl-based-distributions)을 참조하세요. URL은 표준 Claude Code 릴리스 위치이므로 [바이너리 무결성 및 코드 서명](https://code.claude.com/docs/ko/setup.md#binary-integrity-and-code-signing)에 설명된 대로 릴리스의 서명된 매니페스트에 대해 다운로드된 바이너리를 확인할 수 있습니다. 러너는 Claude Code 버전 2.1.224 이상이 필요하며, Claude Tag 세션을 제공하려면 2.1.229 이상이 필요합니다. 이미지를 빌드한 다음 레지스트리로 푸시하고 아래 레시피에서 참조하세요:

397 398 

398```bash theme={null}399```bash theme={null}

400# If your model needs a newer release, change stable to latest in the URL

399docker build \401docker build \

400 --build-arg CLAUDE_CODE_VERSION="$(curl -fsSL https://downloads.claude.ai/claude-code-releases/stable)" \402 --build-arg CLAUDE_CODE_VERSION="$(curl -fsSL https://downloads.claude.ai/claude-code-releases/stable)" \

401 -t <your-registry>/claude-runner:latest .403 -t <your-registry>/claude-runner:latest .

429러너는 `--capacity`를 사용하여 한 번에 실행하는 세션 수를 제한합니다. CPU 또는 메모리를 세션 간에 나누지 않으므로 러너의 세션은 컨테이너의 CPU 및 메모리를 공유합니다. 한 세션의 메모리 사용으로 다른 세션이 종료되지 않도록 하려면 [자체 메모리 제한](#give-each-session-its-own-memory-limit)을 둔 러너당 한 세션을 실행하세요.431러너는 `--capacity`를 사용하여 한 번에 실행하는 세션 수를 제한합니다. CPU 또는 메모리를 세션 간에 나누지 않으므로 러너의 세션은 컨테이너의 CPU 및 메모리를 공유합니다. 한 세션의 메모리 사용으로 다른 세션이 종료되지 않도록 하려면 [자체 메모리 제한](#give-each-session-its-own-memory-limit)을 둔 러너당 한 세션을 실행하세요.

430 432 

431* **러너당 한 세션**: 각 컨테이너에 한 세션의 값을 제공하세요. `--capacity 1`에서 이 크기 조정을 사용하세요. [강화 섹션](#harden-your-deployment)이 권장하고, [온디맨드 러너](https://code.claude.com/docs/ko/self-hosted-environments-configuration.md#on-demand-runners)의 경우, 값을 [`spawn-runner` 훅](https://code.claude.com/docs/ko/self-hosted-environments-configuration#the-spawn-runner-hook)이 제출하는 워크로드(예: Kubernetes Job의 pod 템플릿)에 설정합니다.433* **러너당 한 세션**: 각 컨테이너에 한 세션의 값을 제공하세요. `--capacity 1`에서 이 크기 조정을 사용하세요. [강화 섹션](#harden-your-deployment)이 권장하고, [온디맨드 러너](https://code.claude.com/docs/ko/self-hosted-environments-configuration.md#on-demand-runners)의 경우, 값을 [`spawn-runner` 훅](https://code.claude.com/docs/ko/self-hosted-environments-configuration#the-spawn-runner-hook)이 제출하는 워크로드(예: Kubernetes Job의 pod 템플릿)에 설정합니다.

432* **러너당 여러 세션**: `--capacity`가 1보다 클 때 한 세션의 값에 용량을 곱하세요. 컨테이너에서 한 번에 최대 그 많은 세션이 실행될 수 있기 때문입니다. [Kubernetes](#kubernetes) 및 [Docker Compose](#docker-compose) 레시피는 CPU 또는 메모리 제한 없이 `--capacity 4`를 실행하므로 실행하는 용량에 맞게 크기가 조정된 제한을 추가하세요.434* **러너당 여러 세션**: `--capacity`가 1보다 클 때 한 세션의 값에 용량을 곱하세요. [유휴 세션을 포함하여](#release-idle-sessions-on-a-fixed-fleet) 컨테이너에서 한 번에 최대 그 많은 세션이 실행될 수 있기 때문입니다. [Kubernetes](#kubernetes) 및 [Docker Compose](#docker-compose) 레시피는 CPU 또는 메모리 제한 없이 `--capacity 4`를 실행하므로 실행하는 용량에 맞게 크기가 조정된 제한을 추가하세요.

433* **한 호스트의 여러 러너 컨테이너**: 각 러너는 `--capacity`에 대해 자신의 세션만 계산하므로 러너 용량의 합계에 맞게 호스트 크기를 조정하세요:435* **한 호스트의 여러 러너 컨테이너**: 각 러너는 `--capacity`에 대해 자신의 세션만 계산하므로 러너 용량의 합계에 맞게 호스트 크기를 조정하세요:

434 436 

435 * **메모리**: 한 세션의 메모리에 합계를 곱한 다음 호스트 자체 프로세스가 사용하는 양을 더합니다437 * **메모리**: 한 세션의 메모리에 합계를 곱한 다음 호스트 자체 프로세스가 사용하는 양을 더합니다

Details

56| `--session-stop-grace-sec <n>` | `SELF_HOSTED_RUNNER_SESSION_STOP_GRACE_MS` | `5` | 세션이 끝난 후 Claude 프로세스를 강제 종료하기 전에 정상적으로 종료되기를 기다리는 시간입니다. 자식 프로세스 자체의 `SessionEnd` 훅에 더 많은 시간이 필요하면 값을 늘리십시오. |56| `--session-stop-grace-sec <n>` | `SELF_HOSTED_RUNNER_SESSION_STOP_GRACE_MS` | `5` | 세션이 끝난 후 Claude 프로세스를 강제 종료하기 전에 정상적으로 종료되기를 기다리는 시간입니다. 자식 프로세스 자체의 `SessionEnd` 훅에 더 많은 시간이 필요하면 값을 늘리십시오. |

57| `--startup-timeout-min <n>` | `SELF_HOSTED_RUNNER_STARTUP_TIMEOUT_MS` | `15` | 초기화되지 않은 자식 프로세스를 세션 슬롯 해제 전까지 기다리는 시간입니다. 카운트가 시작되는 시점과 어떤 세션은 계속 실행되도록 두는지에 대해서는 [세션 시작 타임아웃](#session-startup-timeout)을 참조하십시오. `0`은 타임아웃을 비활성화합니다. |57| `--startup-timeout-min <n>` | `SELF_HOSTED_RUNNER_STARTUP_TIMEOUT_MS` | `15` | 초기화되지 않은 자식 프로세스를 세션 슬롯 해제 전까지 기다리는 시간입니다. 카운트가 시작되는 시점과 어떤 세션은 계속 실행되도록 두는지에 대해서는 [세션 시작 타임아웃](#session-startup-timeout)을 참조하십시오. `0`은 타임아웃을 비활성화합니다. |

58| `--trust-workspace [bool]` | `SELF_HOSTED_RUNNER_TRUST_WORKSPACE` | 켜짐 | 각 세션의 저장소 경로에 대한 영구 신뢰를 미리 설정하여 저장소에 커밋된 `permissions.allow` 및 `additionalDirectories`가 적용되도록 합니다. 저장소에 커밋된 권한 부여를 제외하고 대신 호스트 구성의 `settings.json`에서 허용 규칙을 구성하려면 `false`로 설정하십시오. 저장소에 커밋된 `sandbox.*` 설정은 어느 경우든 여전히 적용되며, 이 때문에 [저장소 설정 가드](https://code.claude.com/docs/ko/self-hosted-environments-deploy.md#harden-your-deployment)는 이 플래그와 관계없이 해당 설정을 검사합니다. |58| `--trust-workspace [bool]` | `SELF_HOSTED_RUNNER_TRUST_WORKSPACE` | 켜짐 | 각 세션의 저장소 경로에 대한 영구 신뢰를 미리 설정하여 저장소에 커밋된 `permissions.allow` 및 `additionalDirectories`가 적용되도록 합니다. 저장소에 커밋된 권한 부여를 제외하고 대신 호스트 구성의 `settings.json`에서 허용 규칙을 구성하려면 `false`로 설정하십시오. 저장소에 커밋된 `sandbox.*` 설정은 어느 경우든 여전히 적용되며, 이 때문에 [저장소 설정 가드](https://code.claude.com/docs/ko/self-hosted-environments-deploy.md#harden-your-deployment)는 이 플래그와 관계없이 해당 설정을 검사합니다. |

59| `--use-anthropic-git-proxy` | `CLAUDE_RUNNER_USE_GIT_PROXY=1` | 꺼짐 | 고객이 관리하는 git 인증 대신 [Anthropic git 프록시](https://code.claude.com/docs/ko/self-hosted-environments-deploy.md#use-the-anthropic-git-proxy)를 통해 github.com의 저장소를 클론합니다. `--capacity 1`과 git 2.32 이상이 필요하며, 그렇지 않으면 러너가 시작을 거부합니다. 다시 쓰기 플래그보다 우선합니다. |59| `--use-anthropic-git-proxy` | `CLAUDE_RUNNER_USE_GIT_PROXY=1` | 꺼짐 | 고객이 관리하는 git 인증 대신 [Anthropic git 프록시](https://code.claude.com/docs/ko/self-hosted-environments-deploy.md#use-the-anthropic-git-proxy)를 통해 github.com의 저장소를 클론합니다. `--capacity 1`과 git 2.32 이상이 필요하며, 그렇지 않으면 러너가 시작을 거부합니다. 또한 Claude Code v2.1.267 이상이 필요합니다. 다시 쓰기 플래그보다 우선합니다. |

60 60 

61대부분의 기간 플래그에는 최댓값이 있으며, 이는 각 타임아웃을 런타임의 32비트 타이머 상한인 약 24.85일 이내로 유지하기 위해 정해졌습니다. `--*-min` 플래그는 10080분(7일), `--drain-grace-sec`는 604800초(역시 7일), `--drain-wait-sec`는 86400초(24시간)가 상한입니다. `--session-stop-grace-sec`와 `--post-session-hook-timeout-sec`에는 상한이 없습니다. 상한을 초과했을 때의 동작은 사용 환경에 따라 다릅니다.61대부분의 기간 플래그에는 최댓값이 있으며, 이는 각 타임아웃을 런타임의 32비트 타이머 상한인 약 24.85일 이내로 유지하기 위해 정해졌습니다. `--*-min` 플래그는 10080분(7일), `--drain-grace-sec`는 604800초(역시 7일), `--drain-wait-sec`는 86400초(24시간)가 상한입니다. `--session-stop-grace-sec`와 `--post-session-hook-timeout-sec`에는 상한이 없습니다. 상한을 초과했을 때의 동작은 사용 환경에 따라 다릅니다.

62 62 

Details

12 12 

13[자체 호스팅 환경](https://code.claude.com/docs/ko/self-hosted-environments)에서 Claude Code [클라우드 세션](https://code.claude.com/docs/ko/claude-code-on-the-web.md)은 사용자가 빌드하고 유지 관리하는 러너 이미지에서 실행됩니다. 새 이미지를 프로덕션 환경에 배포하기 전에 스크립트에서 테스트 환경에 대해 전체 세션을 실행합니다. 세션을 생성하고, Claude의 응답을 읽고, 후속 메시지를 보내고, 그 응답도 읽습니다. 이것이 러너 이미지, git 액세스 및 모든 사용자 정의 도구를 검증한 후 변경 사항을 승격하기 전에 수행하는 CI 스모크 테스트의 형태입니다.13[자체 호스팅 환경](https://code.claude.com/docs/ko/self-hosted-environments)에서 Claude Code [클라우드 세션](https://code.claude.com/docs/ko/claude-code-on-the-web.md)은 사용자가 빌드하고 유지 관리하는 러너 이미지에서 실행됩니다. 새 이미지를 프로덕션 환경에 배포하기 전에 스크립트에서 테스트 환경에 대해 전체 세션을 실행합니다. 세션을 생성하고, Claude의 응답을 읽고, 후속 메시지를 보내고, 그 응답도 읽습니다. 이것이 러너 이미지, git 액세스 및 모든 사용자 정의 도구를 검증한 후 변경 사항을 승격하기 전에 수행하는 CI 스모크 테스트의 형태입니다.

14 14 

15이 레시피는 사용자가 이미 [환경과 러너를 설정](https://code.claude.com/docs/ko/self-hosted-environments-quickstart.md#set-up-an-environment-and-runner)했으며, CI 작업이 테스트 스크립트와 동일한 호스트에서 러너 프로세스를 시작한다고 가정합니다. 이는 새 러너 이미지를 테스트하기 위한 자연스러운 설정입니다. 러너에 설치한 Stop 훅은 각 턴의 최종 응답을 로컬 파일에 기록하고, 스크립트는 그곳에서 읽으므로 Anthropic API에 대한 유일한 호출은 두 디스패치 자체입니다. 테스트 러너가 별도의 인프라에 있는 경우 [원격 테스트 러너](#remote-test-runners)를 참조하세요.15이 레시피는 사용자가 이미 [환경과 러너를 설정](https://code.claude.com/docs/ko/self-hosted-environments-quickstart.md#set-up-an-environment-and-runner)했으며, CI 작업이 테스트 스크립트와 동일한 호스트에서 러너 프로세스를 시작한다고 가정합니다. 러너에 설치한 Stop 훅은 각 턴의 최종 응답을 로컬 파일에 기록하고, 스크립트는 그곳에서 응답을 읽습니다. 테스트 러너가 별도의 인프라에 있는 경우 [원격 테스트 러너](#remote-test-runners)를 참조하세요.

16 16 

17## 테스트 러너에 캡처 훅 설치17## 테스트 러너에 캡처 훅 설치

18 18 

Details

62 62 

63Hook은 `settings.json`과 동일한 형식을 사용합니다.63Hook은 `settings.json`과 동일한 형식을 사용합니다.

64 64 

65이 예제는 조직 전체에서 모든 파일 편집 후 감사 스크립트를 실행합니다:65이 예제는 조직 전체에서 `Edit` 및 `Write` 도구 호출 후 감사 스크립트를 실행합니다:

66 66 

67```json theme={null}67```json theme={null}

68{68{

95 95 

96설정이 적용되고 있는지 확인하려면 사용자에게 Claude Code를 다시 시작하도록 요청합니다. 구성에 [보안 승인 대화](#security-approval-dialogs)를 트리거하는 설정이 포함된 경우, 사용자는 Claude Code가 다음 시작 또는 실행 중인 대화형 세션에서 1시간 이내에 설정을 가져올 때 관리 설정을 설명하는 프롬프트를 봅니다. 사용자가 `/permissions`를 실행하여 유효한 권한 규칙을 확인하도록 하여 관리 권한 규칙이 활성화되어 있는지 확인할 수도 있습니다.96설정이 적용되고 있는지 확인하려면 사용자에게 Claude Code를 다시 시작하도록 요청합니다. 구성에 [보안 승인 대화](#security-approval-dialogs)를 트리거하는 설정이 포함된 경우, 사용자는 Claude Code가 다음 시작 또는 실행 중인 대화형 세션에서 1시간 이내에 설정을 가져올 때 관리 설정을 설명하는 프롬프트를 봅니다. 사용자가 `/permissions`를 실행하여 유효한 권한 규칙을 확인하도록 하여 관리 권한 규칙이 활성화되어 있는지 확인할 수도 있습니다.

97 97 

98세션에서 사용자가 `/status`를 실행하도록 하십시오. 서버 관리 설정이 적용되는 경우 [`Setting sources` 줄](https://code.claude.com/docs/ko/managed-settings#read-the-source-in-/status)에 `Enterprise managed settings`가 괄호 안의 `remote`와 함께 표시됩니다.

99 

98특정 머신에서 가져오기 결과를 확인하려면 사용자가 `claude doctor`를 실행하고 `Managed settings (remote)` 줄을 읽도록 하십시오. Claude Code v2.1.248 이상이 필요합니다. 이 줄은 다음 네 가지 결과 중 하나를 보고합니다:100특정 머신에서 가져오기 결과를 확인하려면 사용자가 `claude doctor`를 실행하고 `Managed settings (remote)` 줄을 읽도록 하십시오. Claude Code v2.1.248 이상이 필요합니다. 이 줄은 다음 네 가지 결과 중 하나를 보고합니다:

99 101 

100* 전달된 설정이 로드됨102* 전달된 설정이 로드됨

247* 게이트웨이가 참석한 대화형 시작에 `401`로 응답하고 이 설정이 꺼져 있으면, 게이트웨이는 해당 로그인을 종료했습니다. Claude Code는 [`Cloud gateway session expired — run /login to reconnect.`](https://code.claude.com/docs/ko/errors#cloud-gateway-session-expired)를 인쇄하고 사용자가 `/login`을 실행할 때까지 게이트웨이에서 로그아웃된 상태로 세션을 엽니다.249* 게이트웨이가 참석한 대화형 시작에 `401`로 응답하고 이 설정이 꺼져 있으면, 게이트웨이는 해당 로그인을 종료했습니다. Claude Code는 [`Cloud gateway session expired — run /login to reconnect.`](https://code.claude.com/docs/ko/errors#cloud-gateway-session-expired)를 인쇄하고 사용자가 `/login`을 실행할 때까지 게이트웨이에서 로그아웃된 상태로 세션을 엽니다.

248* 가져오기가 다른 방식으로 실패하거나, `claude auth` 부명령을 제외한 다른 모든 종류의 시작에서 실패하면, 클라이언트는 오류와 함께 종료됩니다.250* 가져오기가 다른 방식으로 실패하거나, `claude auth` 부명령을 제외한 다른 모든 종류의 시작에서 실패하면, 클라이언트는 오류와 함께 종료됩니다.

249 251 

250이 설정이 서버 관리 설정을 가져오는 세션에서 활성 상태일 때, CLI는 원격 설정이 새로 가져올 때까지 시작 시 차단됩니다. 가져오기가 실패하면, CLI는 정책 없이 진행하지 않고 종료됩니다. 이 설정은 자체 영속화됩니다. 서버에서 전달되면, 첫 번째 성공적인 새 세션 가져오기 전에도 후속 시작이 동일한 동작을 적용하도록 로컬로 캐시됩니다. [서버 관리 설정을 가져오지 않는](#platform-availability) 세션은 대기 없이 시작됩니다.252이 설정이 서버 관리형 설정을 가져오는 세션에서 활성 상태이면, CLI는 원격 설정을 새로 가져올 때까지 시작 시 차단됩니다. 가져오기가 실패하면, CLI는 정책 없이 진행하지 않고 종료됩니다. [서버 관리형 설정을 가져오지 않는](#platform-availability) 세션은 대기 없이 시작됩니다.

251 253 

252이를 활성화하려면 관리 설정 구성에 키를 추가하세요:254이를 활성화하려면 관리 설정 구성에 키를 추가하세요:

253 255 

259 261 

260[엔드포인트 관리](https://code.claude.com/docs/ko/managed-settings.md#delivery-mechanisms) MDM 프로필 또는 시스템 `managed-settings.json` 파일에서 이 키를 설정하여 첫 시작 시 실패 폐쇄 동작을 적용할 수도 있습니다. 이 플래그는 위의 [우선순위 규칙](#settings-precedence)의 예외입니다. Claude Code는 관리자 제어 관리 소스가 이를 설정할 때 이를 준수합니다. 캐시된 서버 관리 페이로드도 있으면 MDM 전달 값을 무시하지 않습니다.262[엔드포인트 관리](https://code.claude.com/docs/ko/managed-settings.md#delivery-mechanisms) MDM 프로필 또는 시스템 `managed-settings.json` 파일에서 이 키를 설정하여 첫 시작 시 실패 폐쇄 동작을 적용할 수도 있습니다. 이 플래그는 위의 [우선순위 규칙](#settings-precedence)의 예외입니다. Claude Code는 관리자 제어 관리 소스가 이를 설정할 때 이를 준수합니다. 캐시된 서버 관리 페이로드도 있으면 MDM 전달 값을 무시하지 않습니다.

261 263 

264이후 시작에서 Claude Code는 캐시된 설정에서 서버가 전달한 값을 읽으므로, 이 설정은 새 세션의 첫 가져오기 전에 이미 활성 상태입니다. 캐시된 복사본에 의존하지 않고 이 설정을 활성 상태로 유지하려면, 엔드포인트 관리형 소스에도 키를 설정하세요.

265 

262[`policyHelper`](https://code.claude.com/docs/ko/settings-reference#policyhelper)가 관리 설정을 제공할 때, 그 출력은 Claude Code가 시작 후 읽는 키에 대해 다른 모든 관리 소스를 대체합니다. Claude Code가 이 키를 읽는 소스에 대해서는 [그 설정 항목](https://code.claude.com/docs/ko/settings-reference.md#forceremotesettingsrefresh)을 참조하세요. `policyHelper` 항목은 Claude Code가 헬퍼를 읽는 소스와 실행 시기를 나타냅니다.266[`policyHelper`](https://code.claude.com/docs/ko/settings-reference#policyhelper)가 관리 설정을 제공할 때, 그 출력은 Claude Code가 시작 후 읽는 키에 대해 다른 모든 관리 소스를 대체합니다. Claude Code가 이 키를 읽는 소스에 대해서는 [그 설정 항목](https://code.claude.com/docs/ko/settings-reference.md#forceremotesettingsrefresh)을 참조하세요. `policyHelper` 항목은 Claude Code가 헬퍼를 읽는 소스와 실행 시기를 나타냅니다.

263 267 

264설정 가져오기는 또한 중간 HTTP 프록시가 오래된 응답을 제공하지 않도록 `Cache-Control: no-cache` 헤더를 보냅니다.268설정 가져오기는 또한 중간 HTTP 프록시가 오래된 응답을 제공하지 않도록 `Cache-Control: no-cache` 헤더를 보냅니다.

settings.md +2 −2

Details

66 66 

67### 팀과 설정 공유하기67### 팀과 설정 공유하기

68 68 

69`.claude/settings.json`을 커밋하면 저장소를 클론하는 모든 사람이 동일한 권한, 훅, 플러그인을 받습니다. 각 팀원은 여전히 자신의 `.claude/settings.local.json`에서 이를 개인적으로 재정의할 수 있으므로 개인 예외 사항은 커밋할 필요가 없습니다. 완전한 팀 파일 예시는 [팀의 공유 설정](https://code.claude.com/docs/ko/settings-example.md#a-teams-shared-settings)을 참조하세요.69`.claude/settings.json`을 커밋하면 저장소를 클론하는 모든 사람이 동일한 권한, 훅, 플러그인 설정을 받습니다. 각 팀원은 여전히 자신의 `.claude/settings.local.json`에서 이를 개인적으로 재정의할 수 있으므로 개인 예외 사항은 커밋할 필요가 없습니다. 완전한 팀 파일 예시는 [팀의 공유 설정](https://code.claude.com/docs/ko/settings-example.md#a-teams-shared-settings)을 참조하세요.

70 70 

71커밋한 내용 중 일부는 각 팀원이 [폴더를 신뢰](https://code.claude.com/docs/ko/permissions.md#project-allow-rules-and-workspace-trust)할 때까지 적용이 보류되며, 몇몇 키는 저장소 파일에서는 전혀 적용되지 않습니다. 두 경우 모두 [적용되지 않는 설정 문제 해결](#common-cases)에서 다룹니다.71커밋한 내용 중 일부는 각 팀원이 [폴더를 신뢰](https://code.claude.com/docs/ko/permissions.md#project-allow-rules-and-workspace-trust)할 때까지 적용이 보류되며, 몇몇 키는 저장소 파일에서는 전혀 적용되지 않습니다. 두 경우 모두 [적용되지 않는 설정 문제 해결](#common-cases)에서 다룹니다.

72 72 

199* **설정 오류**: 사용자, 프로젝트 또는 로컬 파일에 유효하지 않은 JSON 또는 스키마가 거부하는 값이 있습니다. 대화형 세션 시작 시 Claude Code는 Claude의 도움으로 파일을 수정하거나, 종료하거나, 손상된 설정 없이 계속할 수 있는 대화를 표시합니다.199* **설정 오류**: 사용자, 프로젝트 또는 로컬 파일에 유효하지 않은 JSON 또는 스키마가 거부하는 값이 있습니다. 대화형 세션 시작 시 Claude Code는 Claude의 도움으로 파일을 수정하거나, 종료하거나, 손상된 설정 없이 계속할 수 있는 대화를 표시합니다.

200* **설정 경고**: 개별 항목만 실패합니다. 예: 잘못된 형식의 권한 규칙 또는 알 수 없는 hook 이벤트 이름. Claude Code는 해당 값을 건너뛰고 파일의 나머지를 유지합니다.200* **설정 경고**: 개별 항목만 실패합니다. 예: 잘못된 형식의 권한 규칙 또는 알 수 없는 hook 이벤트 이름. Claude Code는 해당 값을 건너뛰고 파일의 나머지를 유지합니다.

201* **관리되는 설정**: Claude Code는 파일의 나머지를 적용합니다. [관리되는 설정의 유효하지 않은 항목](https://code.claude.com/docs/ko/managed-settings.md#invalid-entries-in-managed-settings)은 삭제되는 것과 유효하지 않은 항목을 수정할 때까지 폴백하는 키를 설명합니다. 유효한 JSON이 아닌 관리되는 설정 문서는 [관리되는 설정 문서를 파싱할 수 없음](https://code.claude.com/docs/ko/errors.md#managed-settings-document-could-not-be-parsed)을 참조하세요.201* **관리되는 설정**: Claude Code는 파일의 나머지를 적용합니다. [관리되는 설정의 유효하지 않은 항목](https://code.claude.com/docs/ko/managed-settings.md#invalid-entries-in-managed-settings)은 삭제되는 것과 유효하지 않은 항목을 수정할 때까지 폴백하는 키를 설명합니다. 유효한 JSON이 아닌 관리되는 설정 문서는 [관리되는 설정 문서를 파싱할 수 없음](https://code.claude.com/docs/ko/errors.md#managed-settings-document-could-not-be-parsed)을 참조하세요.

202* **구성 오류**: [`~/.claude.json`](https://code.claude.com/docs/ko/claude-directory#ce-claude-json)을 파싱할 수 없습니다. `claude -p` 실행은 종료되며 파일은 변경되지 않습니다. 이전 사본을 복원하려면 [\~/.claude.json의 구성 오류](https://code.claude.com/docs/ko/errors.md#configuration-error-in-claude-json)를 참조하세요. Claude Code는 손상된 파일을 `~/.claude/backups/.claude.json.corrupted.<timestamp>`에 복사하고, 대화형 세션에서는 종료하고 직접 수정할지 기본 구성으로 재설정할지 묻습니다. 파일이 비어 있고 복원할 백업이 없으면 Claude Code는 기본 설정으로 시작합니다.202* **구성 오류**: [`~/.claude.json`](https://code.claude.com/docs/ko/claude-directory#ce-claude-json)을 파싱할 수 없습니다. `claude -p` 실행은 종료됩니다. 이전 사본을 복원하려면 [\~/.claude.json의 구성 오류](https://code.claude.com/docs/ko/errors.md#configuration-error-in-claude-json)를 참조하세요. Claude Code는 손상된 파일을 `~/.claude/backups/.claude.json.corrupted.<timestamp>`에 복사하고, 대화형 세션에서는 종료하고 수정할지 기본 구성으로 재설정할지 묻습니다. 파일이 비어 있고 복원할 백업이 없으면 Claude Code는 기본 설정으로 시작합니다.

203 203 

204계속한 후 `/status`를 실행하여 영향을 받는 파일을 확인하고 각 오류의 세부 사항을 보려면 `claude doctor`를 실행합니다.204계속한 후 `/status`를 실행하여 영향을 받는 파일을 확인하고 각 오류의 세부 사항을 보려면 `claude doctor`를 실행합니다.

205 205 

skills.md +1 −1

Details

22 22 

23Claude Code에는 `/doctor`, `/code-review`, `/batch`, `/debug`, `/loop`, `/claude-api` 등의 번들 스킬 세트가 포함되어 있습니다. 번들 스킬은 프롬프트 기반입니다. 즉, Claude에 상세한 지침을 제공하고 도구를 사용하여 작업을 조율하도록 합니다. 대부분의 기본 제공 명령은 대신 고정된 로직을 직접 실행합니다.23Claude Code에는 `/doctor`, `/code-review`, `/batch`, `/debug`, `/loop`, `/claude-api` 등의 번들 스킬 세트가 포함되어 있습니다. 번들 스킬은 프롬프트 기반입니다. 즉, Claude에 상세한 지침을 제공하고 도구를 사용하여 작업을 조율하도록 합니다. 대부분의 기본 제공 명령은 대신 고정된 로직을 직접 실행합니다.

24 24 

25번들 스킬은 다른 스킬과 동일한 방식으로 호출합니다. `/` 다음에 스킬 이름을 입력하면 됩니다. Claude는 관련성이 있을 때 일부 번들 스킬을 자동으로 호출합니다. `/verify`를 포함한 다른 스킬은 사용자가 호출할 때만 실행되므로, 이러한 더 오래 실행되는 검사가 시간과 토큰을 소비하는 시점을 제어할 수 있습니다.25번들 스킬은 `/` 다음에 스킬 이름을 입력하여 호출합니다. Claude는 관련성이 있을 때 일부 번들 스킬을 자동으로 호출하며, [`/verify`](#run-and-verify-your-app)를 포함한 다른 스킬은 사용자가 호출할 때만 실행됩니다.

26 26 

27대부분의 번들 스킬은 모든 세션에서 사용 가능합니다. 일부는 특정 기능에 따라 달라집니다. 예를 들어 `/workflow-authoring`은 [동적 워크플로](https://code.claude.com/docs/ko/workflows.md)가 활성화된 경우에만 사용 가능합니다.27대부분의 번들 스킬은 모든 세션에서 사용 가능합니다. 일부는 특정 기능에 따라 달라집니다. 예를 들어 `/workflow-authoring`은 [동적 워크플로](https://code.claude.com/docs/ko/workflows.md)가 활성화된 경우에만 사용 가능합니다.

28 28 

sub-agents.md +1 −1

Details

145> [!NOTE]145> [!NOTE]

146>146>

147> `/agents`를 실행하면 Claude에게 요청하거나 `.claude/agents/` 및 `~/.claude/agents/`를 직접 편집하라는 알림이 출력됩니다.147> `/agents`를 실행하면 Claude에게 요청하거나 `.claude/agents/` 및 `~/.claude/agents/`를 직접 편집하라는 알림이 출력됩니다.

148> Claude Code v2.1.197 이전 버전에서는 `/agents`가 라이브 서브에이전트를 나열하는 **Running** 탭과 생성, 편집 및 삭제를 위한 **Library** 탭이 있는 대화형 마법사를 엽니다.&#x20;148> Claude Code v2.1.197 이하 버전에서는 `/agents`가 라이브 서브에이전트를 나열하는 **Running** 탭과 생성, 편집 및 삭제를 위한 **Library** 탭이 있는 대화형 마법사를 엽니다.&#x20;

149 149 

150## 서브에이전트 구성150## 서브에이전트 구성

151 151 

Details

330 330 

331## 대용량 콘텐츠 붙여넣기331## 대용량 콘텐츠 붙여넣기

332 332 

333프롬프트에 800자 이상 또는 3줄 이상의 텍스트를 붙여넣으면 Claude Code는 입력을 `[Pasted text #1 +120 lines]`과 같은 플레이스홀더로 축약하여 입력 상자를 사용 가능한 상태로 유지하고, 제출할 때 전체 콘텐츠를 여전히 전송합니다. 전체 파일이나 긴 로그와 같은 매우 큰 입력의 경우, 콘텐츠를 파일에 작성하고 붙여넣기 대신 Claude에 파일을 읽도록 요청합니다. 대화 기록을 읽기 쉽게 유지하고 Claude가 나중 차례에서 경로로 파일을 참조할 수 있습니다. VS Code 통합 터미널은 매우 큰 붙여넣기에서 Claude Code에 도달하기 전에 문자를 삭제할 수 있으므로, 거기서는 파일을 사용합니다.333프롬프트에 800자 이상 또는 3줄 이상의 텍스트를 붙여넣으면 Claude Code는 입력을 `[Pasted text #1 +120 lines]`과 같은 플레이스홀더로 축약하여 입력 상자를 사용 가능한 상태로 유지하고, 제출할 때 전체 콘텐츠를 여전히 전송합니다. 전체 파일이나 긴 로그와 같은 매우 큰 입력의 경우, 콘텐츠를 파일에 작성하고 붙여넣기 대신 Claude에 파일을 읽도록 요청합니다. 대화 트랜스크립트를 읽기 쉽게 유지하고 Claude가 이후 턴에서 경로로 파일을 참조할 수 있습니다. VS Code 통합 터미널은 매우 큰 붙여넣기에서 Claude Code에 도달하기 전에 문자를 삭제할 수 있으므로, 거기서는 파일을 사용합니다.

334 334 

335붙여넣기에 [보이지 않는 유니코드 문자](https://code.claude.com/docs/ko/interactive-mode.md#invisible-characters-in-prompts)가 포함되어 있으면 Claude Code는 Enter를 누를 때 이를 제거하고 정리된 프롬프트를 입력 상자에 다시 넣어서 다른 Enter로 전송할 수 있도록 합니다.335붙여넣기에 [보이지 않는 유니코드 문자](https://code.claude.com/docs/ko/interactive-mode.md#invisible-characters-in-prompts)가 포함되어 있으면 Claude Code는 Enter를 누를 때 이를 제거하고 정리된 프롬프트를 입력 상자에 다시 넣어서 다른 Enter로 전송할 수 있도록 합니다.

336 336 

344 344 

345### 붙여넣은 텍스트가 있는 프롬프트 회수345### 붙여넣은 텍스트가 있는 프롬프트 회수

346 346 

347Claude Code는 축약된 각 `[Pasted text #N]` 플레이스홀더 뒤의 콘텐츠를 `~/.claude/paste-cache/` 아래에 유지하므로, [명령 기록](https://code.claude.com/docs/ko/interactive-mode.md#command-history)에서 프롬프트를 회수하고 다시 제출하면 전체 붙여넣은 콘텐츠가 다시 전송되며, 나중 세션에서도 포함됩니다. [`cleanupPeriodDays`](https://code.claude.com/docs/ko/settings-reference#cleanupperioddays)보다 오래된 캐시 파일은 [보존 스윕 규칙](https://code.claude.com/docs/ko/claude-directory.md#cleaned-up-automatically)에 따라 삭제되므로, 회수된 프롬프트는 더 이상 존재하지 않는 붙여넣은 텍스트를 참조할 수 있습니다. 이러한 프롬프트를 제출하면 Claude Code는 절대 리터럴 `[Pasted text #N]` 문자열을 전송하지 않으며, 누락된 붙여넣기의 이름을 지정하는 알림을 표시합니다:347Claude Code는 각 `[Pasted text #N]` 플레이스홀더 뒤의 콘텐츠를 `~/.claude/paste-cache/` 아래에 유지하므로, [명령 기록](https://code.claude.com/docs/ko/interactive-mode.md#command-history)에서 프롬프트를 회수하고 다시 제출하면 전체 붙여넣은 콘텐츠가 다시 전송되며, 나중 세션에서도 포함됩니다.

348 

349[`cleanupPeriodDays`](https://code.claude.com/docs/ko/settings-reference#cleanupperioddays)보다 오래된 캐시 파일은 [보존 스윕 규칙](https://code.claude.com/docs/ko/claude-directory.md#cleaned-up-automatically)에 따라 삭제되므로, 회수된 프롬프트는 더 이상 존재하지 않는 붙여넣은 텍스트를 참조할 수 있습니다. 이러한 프롬프트를 제출하면 Claude Code는 리터럴 `[Pasted text #N]` 문자열을 전송하지 않으며, 누락된 붙여넣기의 이름을 지정하는 알림을 표시합니다:

348 350 

349* 남은 텍스트가 있는 일반 프롬프트에서 Claude Code는 플레이스홀더를 제거하고 남은 텍스트를 전송합니다.351* 남은 텍스트가 있는 일반 프롬프트에서 Claude Code는 플레이스홀더를 제거하고 남은 텍스트를 전송합니다.

350* [셸 모드](https://code.claude.com/docs/ko/interactive-mode.md#shell-mode-with-prefix) 명령 또는 `/` 명령에서, 제거가 실행되는 내용을 변경할 수 있으며, 제거가 비어 있는 모든 프롬프트에서 Claude Code는 제출을 취소하고 원본 텍스트를 입력에 유지하며, 플레이스홀더는 여전히 포함됩니다. 플레이스홀더를 삭제하거나 명령을 편집한 후 다시 제출합니다.352* 제거로 인해 실행되는 내용이 달라지는 [셸 모드](https://code.claude.com/docs/ko/interactive-mode.md#shell-mode-with-prefix) 명령 또는 `/` 명령, 그리고 제거 후 비게 되는 모든 프롬프트에서 Claude Code는 제출을 취소하고 원본 텍스트를 입력에 유지하며, 플레이스홀더는 여전히 포함됩니다. 플레이스홀더를 삭제하거나 명령을 편집한 후 다시 제출합니다.

351 353 

352## Vim 키바인딩으로 프롬프트 편집하기354## Vim 키바인딩으로 프롬프트 편집하기

353 355 

Details

29| 설치 중 `EACCES: permission denied` | [설치 디렉터리의 권한 수정](#permission-errors-during-installation) |29| 설치 중 `EACCES: permission denied` | [설치 디렉터리의 권한 수정](#permission-errors-during-installation) |

30| `TLS connect error` 또는 `SSL/TLS secure channel` | [CA 인증서 업데이트](#tls-or-ssl-connection-errors) |30| `TLS connect error` 또는 `SSL/TLS secure channel` | [CA 인증서 업데이트](#tls-or-ssl-connection-errors) |

31| `CRYPT_E_NO_REVOCATION_CHECK` 또는 `CRYPT_E_REVOCATION_OFFLINE` | [차단된 인증서 해지 확인 우회](#tls-or-ssl-connection-errors) |31| `CRYPT_E_NO_REVOCATION_CHECK` 또는 `CRYPT_E_REVOCATION_OFFLINE` | [차단된 인증서 해지 확인 우회](#tls-or-ssl-connection-errors) |

32| `Failed to fetch version` 또는 다운로드 서버에 도달할 수 없음 | [네트워크 및 프록시 설정 확인](#check-network-connectivity) |32| `Failed to fetch version` 또는 다운로드 서버에 도달할 수 없음 | [네트워크 및 프록시 설정 확인](#check-network-connectivity), 또는 인증서 오류인 경우 [회사 CA 인증서 구성](#tls-or-ssl-connection-errors) |

33| `The connection dropped while downloading the update` 또는 `Download timed out: exceeded the total deadline` | [업데이트 다시 실행 또는 프록시 설정](#the-connection-dropped-while-downloading-the-update) |33| `The connection dropped while downloading the update` 또는 `Download timed out: exceeded the total deadline` | [업데이트 다시 실행 또는 프록시 설정](#the-connection-dropped-while-downloading-the-update) |

34| `Release verification failed for Claude Code` | [`claude update` 또는 `claude install` 다시 실행](#release-verification-failed) |34| `Release verification failed for Claude Code` | [`claude update` 또는 `claude install` 다시 실행](#release-verification-failed) |

35| 세션 하단에 빨간색으로 `Auto-update failed · Run claude doctor` 표시 | [셸에서 `claude update` 실행](#auto-update-failed) |35| 세션 하단에 빨간색으로 `Auto-update failed · Run claude doctor` 표시 | [셸에서 `claude update` 실행](#auto-update-failed) |

94* `403`: 일반적으로 호스트를 차단하는 프록시 또는 네트워크 필터이거나, Claude Code가 [해당 지역에서 사용 불가능](https://www.anthropic.com/supported-countries)합니다.94* `403`: 일반적으로 호스트를 차단하는 프록시 또는 네트워크 필터이거나, Claude Code가 [해당 지역에서 사용 불가능](https://www.anthropic.com/supported-countries)합니다.

95* `5xx`: 일반적으로 임시 서비스 문제입니다. 몇 분 기다렸다가 다시 시도하세요.95* `5xx`: 일반적으로 임시 서비스 문제입니다. 몇 분 기다렸다가 다시 시도하세요.

96 96 

97출력이 없거나 `Could not resolve host` 또는 연결 시간 초과가 표시되면 네트워크가 연결을 차단하고 있습니다. 일반적인 원인:97출력이 없거나 설치 프로그램에 `Could not resolve host` 또는 연결 시간 초과가 표시되면 연결에 실패한 것이므로 다음 원인을 확인하세요:

98 98 

99* `downloads.claude.ai`를 차단하는 회사 방화벽 또는 프록시99* `downloads.claude.ai`를 차단하는 회사 방화벽 또는 프록시

100* 지역 네트워크 제한: VPN 또는 대체 네트워크 시도100* 지역 네트워크 제한: VPN 또는 대체 네트워크 시도

101* TLS/SSL 문제: 시스템의 CA 인증서를 업데이트하거나 `HTTPS_PROXY`가 구성되어 있는지 확인101* TLS/SSL 문제: [TLS 또는 SSL 연결 오류](#tls-or-ssl-connection-errors) 참조

102 102 

103회사 프록시 뒤에 있는 경우 설치하기 전에 `HTTPS_PROXY` 및 `HTTP_PROXY`를 프록시 주소로 설정하세요. 프록시 URL을 모르는 경우 IT 팀에 문의하거나 브라우저의 프록시 설정을 확인하세요.103회사 프록시 뒤에 있는 경우 설치하기 전에 `HTTPS_PROXY` 및 `HTTP_PROXY`를 프록시 주소로 설정하세요. 프록시 URL을 모르는 경우 IT 팀에 문의하거나 브라우저의 프록시 설정을 확인하세요.

104 104 

566 irm https://claude.ai/install.ps1 | iex566 irm https://claude.ai/install.ps1 | iex

567 ```567 ```

568 568 

5693. **프록시 또는 방화벽 간섭 확인**: TLS 검사를 수행하는 회사 프록시는 `unable to get local issuer certificate` 및 `SELF_SIGNED_CERT_IN_CHAIN`을 포함한 이러한 오류를 유발할 수 있습니다. 설치 단계의 경우 설치 다운로드가 회사 프록시의 CA를 신뢰하도록 합니다.5693. **프록시 또는 방화벽 간섭 확인**: TLS 검사를 수행하는 회사 프록시는 `unable to get local issuer certificate`, `unable to verify the first certificate`, `SELF_SIGNED_CERT_IN_CHAIN`을 포함한 이러한 오류를 유발할 수 있습니다. 설치 다운로드가 회사 프록시의 CA를 신뢰하도록 합니다.

570 570 

571 > [tab] macOS/Linux571 > [tab] macOS/Linux

572 >572 >

573 > 설치 스크립트의 `curl` 다운로드에는 `CURL_CA_BUNDLE`을, 스크립트가 이어서 실행하는 `claude install` 명령에는 [`NODE_EXTRA_CA_CERTS`](https://code.claude.com/docs/ko/network-config#custom-ca-certificates)를 설정합니다. 프록시의 루트 CA 인증서가 포함된 PEM 파일이 없으면 IT 팀에 요청합니다. 이 예에서는 두 변수를 모두 프록시의 CA 파일로 설정하고 같은 터미널에서 스크립트를 실행합니다.

574 >

573 > ```bash theme={null}575 > ```bash theme={null}

574 > curl --cacert /path/to/corporate-ca.pem -fsSL https://claude.ai/install.sh | bash576 > export CURL_CA_BUNDLE=/path/to/corporate-ca.pem

577 > export NODE_EXTRA_CA_CERTS=/path/to/corporate-ca.pem

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

575 > ```579 > ```

580 >

581 > 그래도 이러한 인증서 오류 중 하나로 설치가 실패하면 IT 팀에 공개 루트 인증서와 프록시의 전체 CA 체인이 모두 포함된 파일을 요청합니다. 그런 다음 두 변수를 모두 해당 파일로 설정합니다.

576 582 

577 > [tab] Windows PowerShell583 > [tab] Windows PowerShell

578 >584 >

596 > $env:NODE_EXTRA_CA_CERTS = 'C:\path\to\corporate-ca.pem'602 > $env:NODE_EXTRA_CA_CERTS = 'C:\path\to\corporate-ca.pem'

597 > ```603 > ```

598 604 

599 인증서 파일이 없으면 IT 팀에 요청합니다. 프록시가 원인인지 확인하기 위해 직접 연결에서 시도할 수도 있습니다.

600 

6014. **Windows에서 차단된 해지 확인 해결**. 오류 `CRYPT_E_NO_REVOCATION_CHECK (0x80092012)` 및 `CRYPT_E_REVOCATION_OFFLINE (0x80092013)`은 curl이 서버에 도달했지만 네트워크가 인증서 해지 조회를 차단함을 의미합니다. 이는 회사 방화벽 뒤에서 일반적입니다. 실패한 명령이 `install.cmd`를 다운로드하는 `curl`인 경우 `--ssl-revoke-best-effort`를 추가하여 명령 프롬프트에서 다시 실행합니다.6054. **Windows에서 차단된 해지 확인 해결**. 오류 `CRYPT_E_NO_REVOCATION_CHECK (0x80092012)` 및 `CRYPT_E_REVOCATION_OFFLINE (0x80092013)`은 curl이 서버에 도달했지만 네트워크가 인증서 해지 조회를 차단함을 의미합니다. 이는 회사 방화벽 뒤에서 일반적입니다. 실패한 명령이 `install.cmd`를 다운로드하는 `curl`인 경우 `--ssl-revoke-best-effort`를 추가하여 명령 프롬프트에서 다시 실행합니다.

602 ```batch theme={null}606 ```batch theme={null}

603 curl --ssl-revoke-best-effort -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd607 curl --ssl-revoke-best-effort -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd

610 614 

611### `Failed to fetch version from downloads.claude.ai`615### `Failed to fetch version from downloads.claude.ai`

612 616 

613설치 프로그램이 다운로드 서버에 도달할 수 없습니다. 이는 보통 `downloads.claude.ai`가 네트워크에서 차단되었음을 의미합니다. [네트워크 연결 확인](#check-network-connectivity)을 참조하세요.617메시지 끝에 원인이 표시됩니다. `unable to verify the first certificate`와 같은 인증서 오류라면 [TLS 또는 SSL 연결 오류](#tls-or-ssl-connection-errors)를 참조하세요. 그 외의 원인이라면 [네트워크 연결 확인](#check-network-connectivity)을 참조하세요.

614 618 

615### The connection dropped while downloading the update619### The connection dropped while downloading the update

616 620 

workflows.md +10 −4

Details

375 375 

376 v2.1.305 이전에는 `pipeline()` 항목이나 `parallel()` 작업이 각각 둘 이상의 에이전트를 실행한 스크립트를 편집하지 않고 다시 시작할 때도 완료된 에이전트가 다시 실행될 수 있었습니다. 새 실행에서 이러한 재실행을 막으려면 Claude Code를 업데이트하세요.376 v2.1.305 이전에는 `pipeline()` 항목이나 `parallel()` 작업이 각각 둘 이상의 에이전트를 실행한 스크립트를 편집하지 않고 다시 시작할 때도 완료된 에이전트가 다시 실행될 수 있었습니다. 새 실행에서 이러한 재실행을 막으려면 Claude Code를 업데이트하세요.

377* **중지 시점에 실행 중이었음**: 처음부터 다시 시작합니다. 전체 실행을 중지해도 어떤 에이전트도 실패한 것으로 간주되지 않습니다.377* **중지 시점에 실행 중이었음**: 처음부터 다시 시작합니다. 전체 실행을 중지해도 어떤 에이전트도 실패한 것으로 간주되지 않습니다.

378* **v2.1.318 이상에서 [사용 한도로 실패함](#when-a-run-hits-your-usage-limit)**: 다시 실행되며, 완료된 에이전트는 저장된 결과를 반환합니다. 실패 후 스크립트가 다른 에이전트를 호출했고 그 에이전트가 결과를 반환했다면, 스크립트가 실패한 에이전트 뒤에 시작하는 모든 에이전트도 다시 실행됩니다.

378* **실패함**: 다시 실행되며, 스크립트가 그 뒤에 시작하는 모든 에이전트도 완료된 에이전트를 포함하여 다시 실행됩니다. [`/workflows`](#watch-the-run)에서 에이전트 하나를 선택하고 `x`를 눌러 해당 에이전트만 중지하면 실패로 간주됩니다.379* **실패함**: 다시 실행되며, 스크립트가 그 뒤에 시작하는 모든 에이전트도 완료된 에이전트를 포함하여 다시 실행됩니다. [`/workflows`](#watch-the-run)에서 에이전트 하나를 선택하고 `x`를 눌러 해당 에이전트만 중지하면 실패로 간주됩니다.

379 380 

380마지막 경우는 팬아웃 도중에 실패가 발생하면 이미 완료된 작업까지 다시 실행된다는 의미입니다. 스크립트가 A, B, C, D를 순서대로 시작하고 B가 실패하면, 다시 시작할 때 A는 캐시에서 반환되고 B, C, D는 다시 실행됩니다.381마지막 경우는 팬아웃 도중에 **실패함** 상태인 에이전트가 있으면 이미 완료된 작업까지 다시 실행된다는 의미입니다. 스크립트가 A, B, C, D를 순서대로 시작하고 B가 **실패함** 상태이면, 다시 시작할 때 A는 캐시에서 반환되고 B, C, D는 다시 실행됩니다.

381 382 

382A, B, C, D를 시작하던 스크립트를 A, C, B, D 순서로 시작하도록 편집하면, 두 번째로 시작하는 에이전트는 이전 실행에서 B였던 자리에 이제 C가 됩니다. 다시 시작하면 A는 캐시에서 반환되고 C, B, D는 다시 실행됩니다.383A, B, C, D를 시작하던 스크립트를 A, C, B, D 순서로 시작하도록 편집하면, 두 번째로 시작하는 에이전트는 이전 실행에서 B였던 자리에 이제 C가 됩니다. 다시 시작하면 A는 캐시에서 반환되고 C, B, D는 다시 실행됩니다.

383 384 

395 396 

396### 실행이 사용 한도에 도달한 경우397### 실행이 사용 한도에 도달한 경우

397 398 

398에이전트가 claude.ai [사용 한도](https://code.claude.com/docs/ko/interactive-mode.md#wait-for-a-usage-limit-to-reset)에 도달하면 해당 에이전트를 실패 처리하는 대신 실행이 일시 중지됩니다. 한도에 도달한 에이전트는 한도가 재설정될 때까지 대기하며, 새 에이전트는 시작되지 않습니다. 한도가 재설정되고 잠시 후 대기 중이던 에이전트가 다시 실행되고 실행이 자동으로 계속됩니다. Claude Code v2.1.271 이상이 필요하며, 이전 버전에서는 영향을 받은 에이전트가 실패합니다.399에이전트가 claude.ai [사용 한도](https://code.claude.com/docs/ko/interactive-mode.md#wait-for-a-usage-limit-to-reset)에 도달하면 해당 에이전트를 실패 처리하는 대신 실행이 일시 중지됩니다. 한도에 도달한 에이전트는 한도가 재설정될 때까지 대기하며, 새 에이전트는 시작되지 않습니다. 한도가 재설정되고 잠시 후 대기 중이던 에이전트가 다시 실행되고 실행이 자동으로 계속됩니다. Claude Code v2.1.271 이상, 또는 Desktop [Code 탭](https://code.claude.com/docs/ko/desktop.md)에서는 [v2.1.319 이상](https://code.claude.com/docs/ko/desktop.md#claude-code-version-in-the-code-tab)이 필요합니다. 이전 버전에서는 영향을 받은 에이전트가 실패합니다.

399 400 

400실행이 대기하는 동안 작업 패널의 진행 줄과 [`/workflows`](#watch-the-run) 헤더에 한도가 재설정되는 시점이 표시됩니다.401실행이 대기하는 동안 작업 패널의 진행 줄과 [`/workflows`](#watch-the-run) 헤더에 한도가 재설정되는 시점이 표시됩니다. Code 탭에서는 실행에 `Paused at usage limit · continues after 3:45 PM if the app stays open`과 같은 줄이 표시됩니다. 앱을 열어 두세요.

401 402 

402실행은 다음 조건이 모두 충족될 때만 일시 중지되며, 하나라도 충족되지 않으면 영향을 받은 에이전트가 대신 실패합니다.403실행은 다음 조건이 모두 충족될 때만 일시 중지되며, 하나라도 충족되지 않으면 영향을 받은 에이전트가 대신 실패합니다.

403 404 

404* 세션이 대화형이며 claude.ai 구독으로 로그인되어 있습니다. `claude -p`를 사용하는 [비대화형 모드](https://code.claude.com/docs/ko/headless.md)나 [Agent SDK](https://code.claude.com/docs/ko/agent-sdk/overview.md), [백그라운드 세션](https://code.claude.com/docs/ko/agent-view.md), [Remote Control](https://code.claude.com/docs/ko/remote-control.md) 또는 [에이전트 팀](https://code.claude.com/docs/ko/agent-teams.md) 팀원 세션에서는 실행이 일시 중지되지 않습니다.405* 세션이 [사용량 기반 과금](https://code.claude.com/docs/ko/interactive-mode.md#start-a-wait-yourself)이 없는 claude.ai 구독으로 로그인되어 있으며, 다음 세션 유형 중 하나입니다.

406 * 대화형 터미널 세션. `claude -p`를 사용하는 [비대화형 모드](https://code.claude.com/docs/ko/headless.md)나 [Agent SDK](https://code.claude.com/docs/ko/agent-sdk/overview.md), [백그라운드 세션](https://code.claude.com/docs/ko/agent-view.md), [Remote Control](https://code.claude.com/docs/ko/remote-control.md) 또는 [에이전트 팀](https://code.claude.com/docs/ko/agent-teams.md) 팀원 세션에서는 실행이 일시 중지되지 않습니다.

407 * Code 탭에서 시작한 로컬 세션. SSH, WSL, [Dispatch](https://code.claude.com/docs/ko/desktop.md#sessions-from-dispatch) 또는 [예약 작업](https://code.claude.com/docs/ko/desktop-scheduled-tasks.md) 세션, Remote Control에서 또는 [기업용 런처](https://code.claude.com/docs/ko/corporate-launcher.md)를 통해 시작한 세션에서는 실행이 일시 중지되지 않으며, [`CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC`](https://code.claude.com/docs/ko/env-vars#variables)가 설정된 동안에도 일시 중지되지 않습니다.

405* [`autoContinueAtUsageLimit`](https://code.claude.com/docs/ko/settings-reference#autocontinueatusagelimit)가 켜져 있습니다. 이는 세션 자체가 [사용 한도가 재설정될 때까지 대기](https://code.claude.com/docs/ko/interactive-mode.md#wait-for-a-usage-limit-to-reset)하도록 하는 것과 같은 설정입니다. 대기 중에 이 설정을 끄면 대기가 종료되고 대기 중이던 에이전트가 실패합니다.408* [`autoContinueAtUsageLimit`](https://code.claude.com/docs/ko/settings-reference#autocontinueatusagelimit)가 켜져 있습니다. 이는 세션 자체가 [사용 한도가 재설정될 때까지 대기](https://code.claude.com/docs/ko/interactive-mode.md#wait-for-a-usage-limit-to-reset)하도록 하는 것과 같은 설정입니다. 대기 중에 이 설정을 끄면 대기가 종료되고 대기 중이던 에이전트가 실패합니다.

409* Code 탭에서 [세션 한도 카드](https://code.claude.com/docs/ko/errors.md#youve-hit-your-session-limit)의 **Auto-continue when limits reset** 체크박스가 기본값대로 선택되어 있습니다. 선택을 해제하면 관리형 설정에서 `autoContinueAtUsageLimit`를 `true`로 설정하지 않는 한 Code 탭 세션의 실행이 더 이상 일시 중지되지 않습니다.

406* 한도가 24시간 이내에 재설정됩니다. 주간 한도는 그보다 더 늦게 재설정될 수 있습니다.410* 한도가 24시간 이내에 재설정됩니다. 주간 한도는 그보다 더 늦게 재설정될 수 있습니다.

407* 실행이 이미 두 번 대기하지 않았습니다. 세 번째로 한도에 도달하면 에이전트가 실패합니다.411* 실행이 이미 두 번 대기하지 않았습니다. 세 번째로 한도에 도달하면 에이전트가 실패합니다.

408 412 

413에이전트가 한도로 인해 실패한 실행을 마무리하려면 한도가 재설정된 후 Claude에게 [워크플로를 다시 시작](#which-agents-run-again)하도록 요청하세요.

414 

409### 에이전트가 멈추고 다시 시작되는 경우415### 에이전트가 멈추고 다시 시작되는 경우

410 416 

411출력이 충분히 오랫동안 도착하지 않는 에이전트는 같은 프롬프트로 처음부터 다시 시작합니다. [`/workflows`](#watch-the-run)에서 해당 에이전트 이름에 `(retry 1)` 접미사가 붙고, 세부 정보에 `attempt 2 (stalled)`가 표시됩니다. 재시작은 자동으로 이루어지므로 별도로 조치할 필요가 없습니다.417출력이 충분히 오랫동안 도착하지 않는 에이전트는 같은 프롬프트로 처음부터 다시 시작합니다. [`/workflows`](#watch-the-run)에서 해당 에이전트 이름에 `(retry 1)` 접미사가 붙고, 세부 정보에 `attempt 2 (stalled)`가 표시됩니다. 재시작은 자동으로 이루어지므로 별도로 조치할 필요가 없습니다.

worktrees.md +1 −1

Details

253 253 

254Worktree는 자체 파일과 브랜치를 가지지만 메인 체크아웃과 다음을 공유합니다:254Worktree는 자체 파일과 브랜치를 가지지만 메인 체크아웃과 다음을 공유합니다:

255 255 

256* **저장소의 `.git` 디렉토리**: worktree의 git 명령은 메인 저장소의 공유 `.git` 디렉토리에 쓰며, [샌드박싱](https://code.claude.com/docs/ko/sandboxing.md#filesystem-isolation)은 이러한 쓰기를 허용하므로 `git commit`과 같은 명령이 샌드박스가 활성화된 worktree 내부에서 작동합니다.256* **저장소의 `.git` 디렉토리**: worktree의 git 명령은 메인 저장소의 공유 `.git` 디렉토리에 씁니다. [샌드박스](https://code.claude.com/docs/ko/sandboxing.md#filesystem-isolation)가 활성화된 경우 `git commit`과 같은 명령은 worktree의 루트에서 실행되는 세션에서 작동하며, 이곳은 `--worktree`가 세션을 시작하는 위치입니다. 기본적으로 [worktree의 하위 디렉토리에서 `claude`를 실행하면 이러한 명령은 `index.lock` 오류와 함께 실패합니다](https://code.claude.com/docs/ko/sandboxing#git-index-lock).

257* **플러그인**: [프로젝트 범위](https://code.claude.com/docs/ko/plugins/loading.md#find-where-a-plugin-is-enabled)에서 메인 체크아웃에서 설치된 플러그인도 동일한 저장소의 worktree에 로드되므로 worktree마다 다시 설치할 필요가 없습니다.257* **플러그인**: [프로젝트 범위](https://code.claude.com/docs/ko/plugins/loading.md#find-where-a-plugin-is-enabled)에서 메인 체크아웃에서 설치된 플러그인도 동일한 저장소의 worktree에 로드되므로 worktree마다 다시 설치할 필요가 없습니다.

258* **권한 승인**: worktree 세션에서 Bash 명령에 대해 "예, 다시 묻지 않기"를 선택하면 규칙이 메인 체크아웃의 `.claude/settings.local.json`에 저장됩니다. 이 규칙은 메인 체크아웃과 저장소의 다른 모든 worktree에 적용되며, worktree 제거 후에도 유지됩니다.258* **권한 승인**: worktree 세션에서 Bash 명령에 대해 "예, 다시 묻지 않기"를 선택하면 규칙이 메인 체크아웃의 `.claude/settings.local.json`에 저장됩니다. 이 규칙은 메인 체크아웃과 저장소의 다른 모든 worktree에 적용되며, worktree 제거 후에도 유지됩니다.

259 259 

Details

41 41 

42### ZDR이 포함하지 않는 것42### ZDR이 포함하지 않는 것

43 43 

44ZDR은 ZDR이 활성화된 조직의 경우에도 다음을 포함하지 않습니다. 이러한 기능은 [표준 데이터 보존 정책](https://code.claude.com/docs/ko/data-usage.md#data-retention)을 따릅니다:44ZDR은 ZDR이 활성화된 조직의 경우에도 다음을 포함하지 않습니다. 행에 별도로 명시된 경우를 제외하고, 이러한 기능은 [표준 데이터 보존 정책](https://code.claude.com/docs/ko/data-usage.md#data-retention)을 따릅니다:

45 45 

46| 기능 | 세부 정보 |46| 기능 | 세부 정보 |

47| - | - |47| - | - |

48| claude.ai의 채팅 | Claude for Enterprise 웹 인터페이스를 통한 채팅 대화는 ZDR에 포함되지 않습니다. |48| claude.ai의 채팅 | Claude for Enterprise 웹 인터페이스를 통한 채팅 대화는 ZDR에 포함되지 않습니다. |

49| Cowork | Cowork 세션은 ZDR에 포함되지 않습니다. |49| Cowork | Cowork 세션은 ZDR에 포함되지 않습니다. |

50| 아티팩트 | 채팅 대화 및 Cowork 세션의 아티팩트는 ZDR에 포함되지 않으며, 조직에서 아티팩트에 대한 보존 기간을 설정하지 않는 한 삭제될 때까지 보관됩니다. ZDR이 적용된 Claude Code에서는 아티팩트를 사용할 수 없습니다. |

50| Claude Code 분석 | 프롬프트 또는 모델 응답을 저장하지 않지만 계정 이메일 및 사용 통계와 같은 생산성 메타데이터를 수집합니다. 기여도 메트릭은 ZDR 조직에서 사용할 수 없습니다. [분석 대시보드](https://code.claude.com/docs/ko/analytics.md)는 사용 메트릭만 표시합니다. |51| Claude Code 분석 | 프롬프트 또는 모델 응답을 저장하지 않지만 계정 이메일 및 사용 통계와 같은 생산성 메타데이터를 수집합니다. 기여도 메트릭은 ZDR 조직에서 사용할 수 없습니다. [분석 대시보드](https://code.claude.com/docs/ko/analytics.md)는 사용 메트릭만 표시합니다. |

51| 사용자 및 시트 관리 | 계정 이메일 및 시트 할당과 같은 관리 데이터는 표준 정책에 따라 보존됩니다. |52| 사용자 및 시트 관리 | 계정 이메일 및 시트 할당과 같은 관리 데이터는 표준 정책에 따라 보존됩니다. |

52| 타사 통합 | 타사 도구, MCP servers 또는 기타 외부 통합에서 처리한 데이터는 ZDR에 포함되지 않습니다. 해당 서비스의 데이터 처리 관행을 독립적으로 검토하세요. |53| 타사 통합 | 타사 도구, MCP servers 또는 기타 외부 통합에서 처리한 데이터는 ZDR에 포함되지 않습니다. 해당 서비스의 데이터 처리 관행을 독립적으로 검토하세요. |

60| [웹의 Claude Code](https://code.claude.com/docs/ko/claude-code-on-the-web.md)(Desktop 앱에서 시작된 [클라우드 세션](https://code.claude.com/docs/ko/desktop.md#cloud-sessions) 포함) | 프롬프트 및 완성을 포함한 대화 기록이 있는 세션 데이터의 서버 측 저장이 필요합니다. |61| [웹의 Claude Code](https://code.claude.com/docs/ko/claude-code-on-the-web.md)(Desktop 앱에서 시작된 [클라우드 세션](https://code.claude.com/docs/ko/desktop.md#cloud-sessions) 포함) | 프롬프트 및 완성을 포함한 대화 기록이 있는 세션 데이터의 서버 측 저장이 필요합니다. |

61| [Chat 및 Cowork 통합](https://support.claude.com/en/articles/17444462-set-up-and-manage-the-new-unified-claude-experience-for-your-enterprise-organization) | 클라우드 세션이 필요합니다. |62| [Chat 및 Cowork 통합](https://support.claude.com/en/articles/17444462-set-up-and-manage-the-new-unified-claude-experience-for-your-enterprise-organization) | 클라우드 세션이 필요합니다. |

62| [Claude Tag](https://claude.com/docs/claude-tag) | 채널 메모리 및 세션 기록을 유지합니다. |63| [Claude Tag](https://claude.com/docs/claude-tag) | 채널 메모리 및 세션 기록을 유지합니다. |

63| [Artifacts](https://code.claude.com/docs/ko/artifacts.md) | Anthropic 운영 인프라에 게시된 페이지 콘텐츠를 저장해야 합니다. |64| Claude Code의 [아티팩트](https://code.claude.com/docs/ko/artifacts.md) | Anthropic 운영 인프라에 게시된 페이지 콘텐츠를 저장해야 합니다. |

65| [Claude Docs](https://support.claude.com/en/articles/16923645-get-started-with-claude-docs) | Anthropic 운영 인프라에 문서 콘텐츠를 저장해야 합니다. |

64| 피드백 제출(`/feedback`, `/bug`, `/share`) | 피드백을 제출하면 대화 데이터가 Anthropic으로 전송됩니다. |66| 피드백 제출(`/feedback`, `/bug`, `/share`) | 피드백을 제출하면 대화 데이터가 Anthropic으로 전송됩니다. |

65| [원격 제어](https://code.claude.com/docs/ko/remote-control.md) | Anthropic 서버에 세션 기록을 저장하여 기기 간 대화를 동기화합니다. |67| [원격 제어](https://code.claude.com/docs/ko/remote-control.md) | Anthropic 서버에 세션 기록을 저장하여 기기 간 대화를 동기화합니다. |

66 68