Documentation — Spybara

admin-setup.md +2 −0

Details

91| [Required version range](/ko/settings) | 실행 중인 버전이 조직 승인 범위를 벗어날 때 시작을 거부합니다. 다운그레이드만 차단하는 `minimumVersion`보다 더 강력합니다 | `requiredMinimumVersion`, `requiredMaximumVersion` |91| [Required version range](/ko/settings) | 실행 중인 버전이 조직 승인 범위를 벗어날 때 시작을 거부합니다. 다운그레이드만 차단하는 `minimumVersion`보다 더 강력합니다 | `requiredMinimumVersion`, `requiredMaximumVersion` |

92 92

93claude.ai 또는 Anthropic API를 통해 인증하는 구성원이 있는 조직은 설정을 배포하지 않고도 모델을 관리할 수 있습니다. [organization model restrictions](/ko/model-config#organization-model-restrictions)는 개별 모델을 비활성화하고, [organization default model](/ko/model-config#organization-default-model)은 새 세션이 시작되는 모델을 설정하며, [organization effort limits](/ko/model-config#organization-effort-limits)는 역할별 노력 수준을 제한합니다. 세 가지 제어 모두 Claude Enterprise 플랜이 필요합니다. 모델 제한 및 노력 제한은 서버 측에서 시행되며, 기본 모델은 사용자가 변경할 수 있는 시작점입니다(조직이 이를 시행하지 않는 한). 시행은 제한된 조직 집합에서 사용 가능합니다. 가용성에 대해 Anthropic 계정 팀에 문의하세요. 이러한 제어 중 어느 것도 Amazon Bedrock, Google Cloud의 Agent Platform, Microsoft Foundry 또는 [Claude Platform on AWS](/ko/claude-platform-on-aws)의 세션에 도달하지 않습니다. 이러한 공급자에서는 제한을 위해 위의 `availableModels`를 사용하고 기본값을 위해 관리 설정의 `model` 키를 사용하세요.

93권한 규칙 및 샌드박싱은 다양한 계층을 다룹니다. WebFetch를 거부하면 Claude의 fetch 도구가 차단되지만 Bash가 허용되면 `curl` 및 `wget`은 여전히 모든 URL에 도달할 수 있습니다. 샌드박싱은 OS 수준에서 시행되는 네트워크 도메인 허용 목록으로 그 격차를 닫습니다.95권한 규칙 및 샌드박싱은 다양한 계층을 다룹니다. WebFetch를 거부하면 Claude의 fetch 도구가 차단되지만 Bash가 허용되면 `curl` 및 `wget`은 여전히 모든 URL에 도달할 수 있습니다. 샌드박싱은 OS 수준에서 시행되는 네트워크 도메인 허용 목록으로 그 격차를 닫습니다.

94 96

95이러한 제어가 방어하는 위협 모델은 [Security](/ko/security)를 참조하세요.97이러한 제어가 방어하는 위협 모델은 [Security](/ko/security)를 참조하세요.

advisor.md +4 −3

Details

85조언자는 주 모델 이상의 기능을 가져야 합니다. 각 주 모델에 대해 허용되는 조언자는 다음과 같습니다:85조언자는 주 모델 이상의 기능을 가져야 합니다. 각 주 모델에 대해 허용되는 조언자는 다음과 같습니다:

86 86

87| 주 모델 | 허용되는 조언자 | 참고 |87| 주 모델 | 허용되는 조언자 | 참고 |

~~88| ----------------------------------------------- | ------------------------ | ---------------------------------------------------------------------- |~~88| ----------------------------------------------- | ------------------------- | ----------------------------------------------------------------------------------------------------------- |

90| Sonnet 4.6 | Fable, Opus, Sonnet | |90| Sonnet 4.6 | Fable, Opus, Sonnet | |

93| Opus 4.7 이상 | Fable, Opus 4.7, Opus 4.8 | Opus 4.7과 Opus 4.8은 동등한 기능으로 평가되므로 둘 다 다른 하나를 조언자로 허용합니다. Opus 4.6 또는 Sonnet 5 조언자를 가진 Opus 4.7 주 모델은 거부됩니다 |

93| Fable 5 ({/* min-version: 2.1.170 */}v2.1.170+) | Fable | Opus 또는 Sonnet 조언자는 거부됩니다 |94| Fable 5 ({/* min-version: 2.1.170 */}v2.1.170+) | Fable | Opus 또는 Sonnet 조언자는 거부됩니다 |

94 95

95Fable 5는 주 모델로 작동하든 조언자로 작동하든 Claude Code v2.1.170 이상과 Fable 5 액세스가 필요합니다.96Fable 5는 주 모델로 작동하든 조언자로 작동하든 Claude Code v2.1.170 이상과 Fable 5 액세스가 필요합니다.

174/advisor off175/advisor off

175```176```

176 177

177`/advisor` 명령 및 `--advisor` 플래그를 포함하여 조언자 도구를 완전히 비활성화하려면 `CLAUDE_CODE_DISABLE_ADVISOR_TOOL=1`을 설정하세요. [환경 변수](/ko/env-vars)를 참고하세요.178조언자 도구를 완전히 비활성화하려면 `CLAUDE_CODE_DISABLE_ADVISOR_TOOL=1`을 설정하세요. `/advisor` 명령을 사용할 수 없게 되며 구성된 `advisorModel`은 무시됩니다. `--advisor` 플래그는 허용되지만 효과가 없습니다. 이를 전달하는 기존 스크립트는 오류 없이 계속 작동합니다. [환경 변수](/ko/env-vars)를 참고하세요.

178 179

179<h2 id="compare-with-related-features">180<h2 id="compare-with-related-features">

180 관련 기능과 비교181 관련 기능과 비교

agent-sdk/agent-loop.md +41 −0

Details

86<Accordion title="예제: 메시지 타입 확인 및 결과 처리">86<Accordion title="예제: 메시지 타입 확인 및 결과 처리">

87 <CodeGroup>87 <CodeGroup>

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

89 import asyncio

89 from claude_agent_sdk import query, AssistantMessage, ResultMessage90 from claude_agent_sdk import query, AssistantMessage, ResultMessage

90 91

93 async def main():

94 try:

91 async for message in query(prompt="Summarize this project"):95 async for message in query(prompt="Summarize this project"):

92 if isinstance(message, AssistantMessage):96 if isinstance(message, AssistantMessage):

93 print(f"Turn completed: {len(message.content)} content blocks")97 print(f"Turn completed: {len(message.content)} content blocks")

96 print(message.result)100 print(message.result)

97 else:101 else:

98 print(f"Stopped: {message.subtype}")102 print(f"Stopped: {message.subtype}")

103 except Exception as error:

104 # A single-shot query() raises after yielding an error result. If the

105 # failure was an error result, the error subtype branches above have

106 # already run; connection or process failures yield no result message.

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

108

109

110 asyncio.run(main())

99 ```111 ```

100 112

101 ```typescript TypeScript theme={null}113 ```typescript TypeScript theme={null}

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

103 115

116 try {

104 for await (const message of query({ prompt: "Summarize this project" })) {117 for await (const message of query({ prompt: "Summarize this project" })) {

105 if (message.type === "assistant") {118 if (message.type === "assistant") {

106 console.log(`Turn completed: ${message.message.content.length} content blocks`);119 console.log(`Turn completed: ${message.message.content.length} content blocks`);

113 }126 }

114 }127 }

115 }128 }

129 } catch (error) {

130 // A single-shot query() throws after yielding an error result. If the

131 // failure was an error result, the error subtype branches above have

132 // already run; connection or process failures yield no result message.

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

134 }

116 ```135 ```

117 </CodeGroup>136 </CodeGroup>

118</Accordion>137</Accordion>

321 340

322`result` 필드(최종 텍스트 출력)는 `success` 변형에만 존재하므로 항상 읽기 전에 서브타입을 확인합니다. 모든 결과 서브타입은 `total_cost_usd`, `usage`, `num_turns`, `session_id`를 전달하므로 비용을 추적하고 오류 후에도 재개할 수 있습니다. Python에서 `total_cost_usd`와 `usage`는 선택적으로 입력되며 일부 오류 경로에서 `None`일 수 있으므로 형식을 지정하기 전에 보호합니다. `usage` 필드 해석에 대한 세부 정보는 [비용 및 사용량 추적](/ko/agent-sdk/cost-tracking)을 참조하세요.341`result` 필드(최종 텍스트 출력)는 `success` 변형에만 존재하므로 항상 읽기 전에 서브타입을 확인합니다. 모든 결과 서브타입은 `total_cost_usd`, `usage`, `num_turns`, `session_id`를 전달하므로 비용을 추적하고 오류 후에도 재개할 수 있습니다. Python에서 `total_cost_usd`와 `usage`는 선택적으로 입력되며 일부 오류 경로에서 `None`일 수 있으므로 형식을 지정하기 전에 보호합니다. `usage` 필드 해석에 대한 세부 정보는 [비용 및 사용량 추적](/ko/agent-sdk/cost-tracking)을 참조하세요.

323 342

343<Note>

344 쿼리가 오류 결과로 끝날 때:

345

346 * 단일 `query()` 호출은 최종 결과 메시지를 생성한 다음 `Reached maximum number of turns`와 같은 실패 텍스트를 포함하는 오류를 발생시킵니다. 발생은 의도적입니다 — 코드가 이를 지나서 계속 진행해야 하는 경우 루프를 try 블록으로 래핑합니다. 기본 Claude Code 프로세스도 0이 아닌 코드로 종료됩니다.

347 * 스트리밍 입력 세션은 활성 상태로 유지되며 계속 메시지를 보낼 수 있습니다.

348</Note>

349

324결과는 또한 모델이 최종 턴에서 생성을 중지한 이유를 나타내는 `stop_reason` 필드(`TypeScript에서 string | null`, Python에서 `str | None`)를 포함합니다. 일반적인 값은 `end_turn`(모델이 정상적으로 완료됨), `max_tokens`(출력 토큰 제한에 도달함), `refusal`(모델이 요청을 거부함)입니다. 오류 결과 서브타입에서 `stop_reason`은 루프가 끝나기 전의 마지막 어시스턴트 응답의 값을 전달합니다. 거부를 감지하려면 `stop_reason === "refusal"`(TypeScript) 또는 `stop_reason == "refusal"`(Python)을 확인합니다. 전체 타입은 [`SDKResultMessage`](/ko/agent-sdk/typescript#sdkresultmessage)(TypeScript) 또는 [`ResultMessage`](/ko/agent-sdk/python#resultmessage)(Python)을 참조하세요.350결과는 또한 모델이 최종 턴에서 생성을 중지한 이유를 나타내는 `stop_reason` 필드(`TypeScript에서 string | null`, Python에서 `str | None`)를 포함합니다. 일반적인 값은 `end_turn`(모델이 정상적으로 완료됨), `max_tokens`(출력 토큰 제한에 도달함), `refusal`(모델이 요청을 거부함)입니다. 오류 결과 서브타입에서 `stop_reason`은 루프가 끝나기 전의 마지막 어시스턴트 응답의 값을 전달합니다. 거부를 감지하려면 `stop_reason === "refusal"`(TypeScript) 또는 `stop_reason == "refusal"`(Python)을 확인합니다. 전체 타입은 [`SDKResultMessage`](/ko/agent-sdk/typescript#sdkresultmessage)(TypeScript) 또는 [`ResultMessage`](/ko/agent-sdk/python#resultmessage)(Python)을 참조하세요.

325 351

326<h2 id="hooks">352<h2 id="hooks">

348 374

349이 예제는 이 페이지의 주요 개념을 실패한 테스트를 수정하는 단일 에이전트로 결합합니다. 허용된 도구(자동 승인되므로 에이전트가 자율적으로 실행됨), 프로젝트 설정, 턴 및 추론 노력에 대한 안전 제한으로 에이전트를 구성합니다. 루프가 실행되면 잠재적 재개를 위해 세션 ID를 캡처하고, 최종 결과를 처리하고, 총 비용을 인쇄합니다.375이 예제는 이 페이지의 주요 개념을 실패한 테스트를 수정하는 단일 에이전트로 결합합니다. 허용된 도구(자동 승인되므로 에이전트가 자율적으로 실행됨), 프로젝트 설정, 턴 및 추론 노력에 대한 안전 제한으로 에이전트를 구성합니다. 루프가 실행되면 잠재적 재개를 위해 세션 ID를 캡처하고, 최종 결과를 처리하고, 총 비용을 인쇄합니다.

350 376

377단일 `query()` 호출이 오류 결과를 생성한 후 발생하기 때문에, 루프는 try 블록으로 래핑되어 제한에 도달하면 스크립트가 깔끔하게 종료됩니다.

378

351<CodeGroup>379<CodeGroup>

352 ```python Python theme={null}380 ```python Python theme={null}

353 import asyncio381 import asyncio

357 async def run_agent():385 async def run_agent():

358 session_id = None386 session_id = None

359 387

388 try:

360 async for message in query(389 async for message in query(

361 prompt="Find and fix the bug causing test failures in the auth module",390 prompt="Find and fix the bug causing test failures in the auth module",

362 options=ClaudeAgentOptions(391 options=ClaudeAgentOptions(

389 print(f"Stopped: {message.subtype}")418 print(f"Stopped: {message.subtype}")

390 if message.total_cost_usd is not None:419 if message.total_cost_usd is not None:

391 print(f"Cost: ${message.total_cost_usd:.4f}")420 print(f"Cost: ${message.total_cost_usd:.4f}")

421 except Exception as error:

422 # A single-shot query() raises after yielding an error result. If the

423 # failure was an error result, the error subtype branches above have

424 # already run; connection or process failures yield no result message.

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

392 426

393 427

394 asyncio.run(run_agent())428 asyncio.run(run_agent())

399 433

400 let sessionId: string | undefined;434 let sessionId: string | undefined;

401 435

436 try {

402 for await (const message of query({437 for await (const message of query({

403 prompt: "Find and fix the bug causing test failures in the auth module",438 prompt: "Find and fix the bug causing test failures in the auth module",

404 options: {439 options: {

428 console.log(`Cost: $${message.total_cost_usd.toFixed(4)}`);463 console.log(`Cost: $${message.total_cost_usd.toFixed(4)}`);

429 }464 }

430 }465 }

466 } catch (error) {

467 // A single-shot query() throws after yielding an error result. If the

468 // failure was an error result, the error subtype branches above have

469 // already run; connection or process failures yield no result message.

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

471 }

431 ```472 ```

432</CodeGroup>473</CodeGroup>

433 474

agent-sdk/cost-tracking.md +45 −2

Details

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

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

65 65

66 try {

66 for await (const message of query({ prompt: "Summarize this project" })) {67 for await (const message of query({ prompt: "Summarize this project" })) {

67 if (message.type === "result") {68 if (message.type === "result") {

68 console.log(`Total cost: $${message.total_cost_usd}`);69 console.log(`Total cost: $${message.total_cost_usd}`);

69 }70 }

70 }71 }

72 } catch (error) {

73 // A single-shot query() throws after yielding an error result. If the

74 // failure was an error result, it still carried total_cost_usd and the

75 // branch above has already run; connection or process failures yield

76 // no result message.

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

78 }

71 ```79 ```

72 80

73 ```python Python theme={null}81 ```python Python theme={null}

76 84

77 85

78 async def main():86 async def main():

87 try:

79 async for message in query(prompt="Summarize this project"):88 async for message in query(prompt="Summarize this project"):

80 if isinstance(message, ResultMessage):89 if isinstance(message, ResultMessage):

81 print(f"Total cost: ${message.total_cost_usd or 0}")90 print(f"Total cost: ${message.total_cost_usd or 0}")

91 except Exception as error:

92 # A single-shot query() raises after yielding an error result. If the

93 # failure was an error result, it still carried total_cost_usd and the

94 # branch above has already run; connection or process failures yield

95 # no result message.

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

82 97

83 98

84 asyncio.run(main())99 asyncio.run(main())

110let totalInputTokens = 0;125let totalInputTokens = 0;

111let totalOutputTokens = 0;126let totalOutputTokens = 0;

112 127

113for await (const message of query({ prompt: "Summarize this project" })) {128try {

129 for await (const message of query({ prompt: "Summarize this project" })) {

114 if (message.type === "assistant") {130 if (message.type === "assistant") {

115 const msgId = message.message.id;131 const msgId = message.message.id;

116 132

121 totalOutputTokens += message.message.usage.output_tokens;137 totalOutputTokens += message.message.usage.output_tokens;

122 }138 }

123 }139 }

140 }

141} catch (error) {

142 // A single-shot query() throws after yielding an error result, so the

143 // totals below still reflect the steps that ran before the failure.

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

124}145}

125 146

126console.log(`Steps: ${seenIds.size}`);147console.log(`Steps: ${seenIds.size}`);

139```typescript theme={null}160```typescript theme={null}

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

141 162

142for await (const message of query({ prompt: "Summarize this project" })) {163try {

164 for await (const message of query({ prompt: "Summarize this project" })) {

143 if (message.type !== "result") continue;165 if (message.type !== "result") continue;

144 166

145 for (const [modelName, usage] of Object.entries(message.modelUsage)) {167 for (const [modelName, usage] of Object.entries(message.modelUsage)) {

149 console.log(` Cache read: ${usage.cacheReadInputTokens}`);171 console.log(` Cache read: ${usage.cacheReadInputTokens}`);

150 console.log(` Cache creation: ${usage.cacheCreationInputTokens}`);172 console.log(` Cache creation: ${usage.cacheCreationInputTokens}`);

151 }173 }

174 }

175} catch (error) {

176 // A single-shot query() throws after yielding an error result. If the

177 // failure was an error result, the per-model breakdown above has already

178 // printed; connection or process failures yield no result message.

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

152}180}

153```181```

154 182

173 ];201 ];

174 202

175 for (const prompt of prompts) {203 for (const prompt of prompts) {

204 try {

176 for await (const message of query({ prompt })) {205 for await (const message of query({ prompt })) {

177 if (message.type === "result") {206 if (message.type === "result") {

178 totalSpend += message.total_cost_usd;207 totalSpend += message.total_cost_usd;

179 console.log(`This call: $${message.total_cost_usd}`);208 console.log(`This call: $${message.total_cost_usd}`);

180 }209 }

181 }210 }

211 } catch (error) {

212 // A single-shot query() throws after yielding an error result. If the

213 // failure was an error result, this call's cost was already counted;

214 // connection or process failures yield no result message. Continue

215 // with the next prompt.

216 console.error(`Call failed: ${error}`);

217 }

182 }218 }

183 219

184 console.log(`Total spend: $${totalSpend.toFixed(4)}`);220 console.log(`Total spend: $${totalSpend.toFixed(4)}`);

199 ]235 ]

200 236

201 for prompt in prompts:237 for prompt in prompts:

238 try:

202 async for message in query(prompt=prompt):239 async for message in query(prompt=prompt):

203 if isinstance(message, ResultMessage):240 if isinstance(message, ResultMessage):

204 cost = message.total_cost_usd or 0241 cost = message.total_cost_usd or 0

205 total_spend += cost242 total_spend += cost

206 print(f"This call: ${cost}")243 print(f"This call: ${cost}")

244 except Exception as error:

245 # A single-shot query() raises after yielding an error result. If

246 # the failure was an error result, this call's cost was already

247 # counted; connection or process failures yield no result message.

248 # Continue with the next prompt.

249 print(f"Call failed: {error}")

207 250

208 print(f"Total spend: ${total_spend:.4f}")251 print(f"Total spend: ${total_spend:.4f}")

209 252

agent-sdk/file-checkpointing.md +25 −7

Details

50 50

51파일 체크포인팅을 사용하려면 옵션에서 활성화하고, 응답 스트림에서 체크포인트 UUID를 캡처한 다음, 복원이 필요할 때 `rewindFiles()`(TypeScript) 또는 `rewind_files()`(Python)를 호출합니다.51파일 체크포인팅을 사용하려면 옵션에서 활성화하고, 응답 스트림에서 체크포인트 UUID를 캡처한 다음, 복원이 필요할 때 `rewindFiles()`(TypeScript) 또는 `rewind_files()`(Python)를 호출합니다.

52 52

53다음 예제는 전체 흐름을 보여줍니다: 체크포인팅을 활성화하고, 응답 스트림에서 체크포인트 UUID와 세션 ID를 캡처한 다음, 나중에 세션을 재개하여 파일을 되돌립니다. 각 단계는 아래에서 자세히 설명됩니다.53다음 예제는 전체 흐름을 보여줍니다: 체크포인팅을 활성화하고, 응답 스트림에서 체크포인트 UUID와 세션 ID를 캡처한 다음, 나중에 세션을 재개하여 파일을 되돌립니다. 각 단계는 아래에서 자세히 설명됩니다. 이 섹션의 예제는 "인증 모듈 리팩토링"이라는 프롬프트를 사용합니다. 인증 모듈을 포함하는 프로젝트에서 실행하거나, 프롬프트를 변경하여 프로젝트에 존재하는 파일을 지정하면 파일 변경을 확인하고 되돌리기가 파일을 복원하는 것을 볼 수 있습니다.

54 54

55<CodeGroup>55<CodeGroup>

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

197 session_id = None197 session_id = None

198 198

199 async for message in client.receive_response():199 async for message in client.receive_response():

200 # Update checkpoint on each user message (keeps the latest)200 # Capture the first user message UUID as the checkpoint

201 if isinstance(message, UserMessage) and message.uuid:201 if isinstance(message, UserMessage) and message.uuid and checkpoint_id is None:

202 checkpoint_id = message.uuid202 checkpoint_id = message.uuid

203 # Capture session ID from the result message203 # Capture session ID from the result message

204 if isinstance(message, ResultMessage):204 if isinstance(message, ResultMessage):

210 let sessionId: string | undefined;210 let sessionId: string | undefined;

211 211

212 for await (const message of response) {212 for await (const message of response) {

213 // Update checkpoint on each user message (keeps the latest)213 // Capture the first user message UUID as the checkpoint

214 if (message.type === "user" && message.uuid) {214 if (message.type === "user" && message.uuid && !checkpointId) {

215 checkpointId = message.uuid;215 checkpointId = message.uuid;

216 }216 }

217 // Capture session ID from any message that has it217 // Capture session ID from any message that has it

250 ```250 ```

251 </CodeGroup>251 </CodeGroup>

252 252

253 세션 ID와 체크포인트 ID를 캡처한 경우 CLI에서도 되돌릴 수 있습니다:253 세션 ID와 체크포인트 ID를 캡처한 경우 CLI에서도 되돌릴 수 있습니다. 이 명령은 [Claude Code 설치](/ko/setup)에서 제공되는 `claude` 실행 파일이 필요하며 SDK 패키지에는 설치되지 않습니다. SDK는 체크포인팅을 활성화하지만, `claude -p`를 직접 실행할 때는 `CLAUDE_CODE_ENABLE_SDK_FILE_CHECKPOINTING` 환경 변수를 설정해야 합니다:

254 254

255 ```bash theme={null}255 ```bash theme={null}

256 claude -p --resume <session-id> --rewind-files <checkpoint-uuid>256 CLAUDE_CODE_ENABLE_SDK_FILE_CHECKPOINTING=true claude -p --resume <session-id> --rewind-files <checkpoint-uuid>

257 ```257 ```

258

259 `--rewind-files` 플래그는 `claude --help` 출력에 나타나지 않지만 CLI는 표시된 대로 이를 허용합니다.

258 </Step>260 </Step>

259</Steps>261</Steps>

260 262

270 272

271이 패턴은 가장 최근의 체크포인트 UUID만 유지하며, 각 에이전트 턴 전에 업데이트합니다. 처리 중에 문제가 발생하면 마지막 안전한 상태로 즉시 되돌리고 루프를 벗어날 수 있습니다.273이 패턴은 가장 최근의 체크포인트 UUID만 유지하며, 각 에이전트 턴 전에 업데이트합니다. 처리 중에 문제가 발생하면 마지막 안전한 상태로 즉시 되돌리고 루프를 벗어날 수 있습니다.

272 274

275이 예제를 실행하기 전에 `your_revert_condition`(Python) 또는 `yourRevertCondition`(TypeScript)을 오류 감지 또는 유효성 검사 실패와 같은 자신의 확인으로 바꾸십시오. 플레이스홀더는 예제에서 정의되지 않습니다.

276

273<CodeGroup>277<CodeGroup>

274 ```python Python theme={null}278 ```python Python theme={null}

275 import asyncio279 import asyncio

752 756

753**해결책**: 원본 세션에서 `enable_file_checkpointing=True`(Python) 또는 `enableFileCheckpointing: true`(TypeScript)가 설정되었는지 확인한 다음, 예제에 표시된 패턴을 사용합니다: 첫 번째 사용자 메시지 UUID를 캡처하고, 세션을 완전히 완료한 다음, 빈 프롬프트로 재개하고 `rewindFiles()`를 한 번 호출합니다.757**해결책**: 원본 세션에서 `enable_file_checkpointing=True`(Python) 또는 `enableFileCheckpointing: true`(TypeScript)가 설정되었는지 확인한 다음, 예제에 표시된 패턴을 사용합니다: 첫 번째 사용자 메시지 UUID를 캡처하고, 세션을 완전히 완료한 다음, 빈 프롬프트로 재개하고 `rewindFiles()`를 한 번 호출합니다.

754 758

759<h3 id="file-rewinding-is-not-enabled-error">

760 "File rewinding is not enabled" 오류

761</h3>

762

763이 오류는 체크포인팅이 활성화되지 않은 상태에서 비대화형 되돌리기를 시도할 때 발생합니다: `--rewind-files`를 사용하여 bare `claude -p`를 실행하거나, 체크포인팅을 활성화하지 않는 옵션이 있는 재개된 세션을 포함한 SDK 세션을 실행하는 경우입니다. SDK는 `enable_file_checkpointing`(Python) 또는 `enableFileCheckpointing`(TypeScript)이 되돌리기를 수행하는 세션에서 활성화될 때만 내부적으로 `CLAUDE_CODE_ENABLE_SDK_FILE_CHECKPOINTING` 환경 변수를 설정합니다. bare CLI는 절대 설정하지 않습니다.

764

765**해결책**: bare CLI의 경우 명령을 실행할 때 환경 변수를 설정합니다:

766

767```bash theme={null}

768CLAUDE_CODE_ENABLE_SDK_FILE_CHECKPOINTING=true claude -p --resume <session-id> --rewind-files <checkpoint-uuid>

769```

770

771SDK의 경우, 이 페이지의 예제에서 수행하는 것처럼 재개된 세션에서 `enable_file_checkpointing=True`(Python) 또는 `enableFileCheckpointing: true`(TypeScript)를 설정합니다.

772

755<h3 id="processtransport-is-not-ready-for-writing-error">773<h3 id="processtransport-is-not-ready-for-writing-error">

756 "ProcessTransport is not ready for writing" 오류774 "ProcessTransport is not ready for writing" 오류

757</h3>775</h3>

agent-sdk/permissions.md +13 −2

Details

28 </Step>28 </Step>

29 29

30 <Step title="요청 규칙">30 <Step title="요청 규칙">

31 [settings.json](/ko/settings#permission-settings)에서 `ask` 규칙을 확인합니다. 요청 규칙이 일치하면 `bypassPermissions` 모드에서도 호출이 확인을 위해 [`canUseTool` 콜백](/ko/agent-sdk/user-input)으로 전달됩니다. `dontAsk` 모드에서는 일치하는 요청 규칙이 거부됩니다. 이 모드는 절대 프롬프트를 표시하지 않기 때문입니다.31 [settings.json](/ko/settings#permission-settings)에서 `ask` 규칙을 확인합니다. 요청 규칙이 일치하면 `bypassPermissions` 모드에서도 호출이 확인을 위해 [`canUseTool` 콜백](/ko/agent-sdk/user-input)으로 전달됩니다.

33 사용자 상호작용이 필요한 도구는 동일한 방식으로 작동합니다: `AskUserQuestion` 및 서버가 [`_meta["anthropic/requiresUserInteraction"]`](/ko/mcp#require-approval-for-a-specific-tool)을 설정하는 MCP 도구는 허용 규칙이 일치하는 경우에도 항상 콜백으로 전달됩니다. `dontAsk` 모드에서는 두 경우 모두 거부됩니다. 이 모드는 절대 프롬프트를 표시하지 않기 때문입니다. {/* min-version: 2.1.199 */}MCP 주석에는 Claude Code v2.1.199 이상이 필요합니다.

32 </Step>34 </Step>

33 35

34 <Step title="권한 모드">36 <Step title="권한 모드">

46 48

47<img src="https://mintcdn.com/claude-code/jYgs7qigNjO1Badj/images/agent-sdk/permissions-flow.svg?fit=max&auto=format&n=jYgs7qigNjO1Badj&q=85&s=c771ad9085b1277d3708027a49c744bc" alt="6단계 권한 평가 흐름의 다이어그램으로, 위의 단계와 일치합니다: 도구 요청이 훅, 거부 규칙, 요청 규칙, 권한 모드, 허용 규칙 및 canUseTool을 통과합니다. 훅, 거부 규칙 및 canUseTool은 차단으로 라우팅할 수 있습니다. 권한 모드 우회, 허용 규칙 및 canUseTool은 실행으로 라우팅할 수 있습니다." width="1180" height="260" data-path="images/agent-sdk/permissions-flow.svg" />49<img src="https://mintcdn.com/claude-code/jYgs7qigNjO1Badj/images/agent-sdk/permissions-flow.svg?fit=max&auto=format&n=jYgs7qigNjO1Badj&q=85&s=c771ad9085b1277d3708027a49c744bc" alt="6단계 권한 평가 흐름의 다이어그램으로, 위의 단계와 일치합니다: 도구 요청이 훅, 거부 규칙, 요청 규칙, 권한 모드, 허용 규칙 및 canUseTool을 통과합니다. 훅, 거부 규칙 및 canUseTool은 차단으로 라우팅할 수 있습니다. 권한 모드 우회, 허용 규칙 및 canUseTool은 실행으로 라우팅할 수 있습니다." width="1180" height="260" data-path="images/agent-sdk/permissions-flow.svg" />

48 50

51v2.1.198부터 이 평가 순서에 도달할 수 없는 `canUseTool` 콜백을 전달하면 TypeScript SDK는 쿼리가 구성될 때 Node.js 프로세스 경고를 한 번 발생시킵니다. 경고의 코드는 `CLAUDE_SDK_CAN_USE_TOOL_SHADOWED`입니다. 두 가지 구성이 이를 트리거합니다:

53* `permissionMode: 'bypassPermissions'` - 권한 모드 단계에 도달한 모든 호출을 자동 승인합니다

54* `"Read"`와 같은 각 단순 `allowedTools` 항목 - 콜백이 상담되기 전에 전체 도구를 자동 승인합니다

56`Bash(ls *)`와 같은 지정자가 있는 항목과 `acceptEdits` 모드는 이를 트리거하지 않으며, 설정 파일에서 오는 허용 규칙은 확인에 표시되지 않습니다.

58`process.on('warning', ...)`으로 수신하고 코드를 일치시켜 로깅하거나 억제합니다. 모드 및 규칙과 관계없이 모든 도구 호출을 제어하려면 대신 [`PreToolUse` 훅](/ko/agent-sdk/hooks)을 사용합니다.

49이 페이지는 **허용 및 거부 규칙**과 **권한 모드**에 중점을 둡니다. 다른 단계의 경우:60이 페이지는 **허용 및 거부 규칙**과 **권한 모드**에 중점을 둡니다. 다른 단계의 경우:

50 61

51* **훅:** 도구 요청을 허용, 거부 또는 수정하는 사용자 정의 코드를 실행합니다. [훅으로 실행 제어](/ko/agent-sdk/hooks)를 참조하세요.62* **훅:** 도구 요청을 허용, 거부 또는 수정하는 사용자 정의 코드를 실행합니다. [훅으로 실행 제어](/ko/agent-sdk/hooks)를 참조하세요.

67허용 규칙은 리터럴 `mcp__<server>__` 접두사 이후에만 도구 이름 글롭을 허용합니다. 서버 세그먼트는 글롭이 없어야 하므로 규칙이 구성한 특정 서버의 이름을 지정합니다. `mcp__puppeteer__*`는 `puppeteer` 서버의 모든 도구와 일치하고 `mcp__github__get_*`는 해당 `get_` 도구와 일치합니다. `allowed_tools=["*"]` 또는 `allowed_tools=["mcp__*"]`와 같은 앵커되지 않은 항목은 시작 경고와 함께 무시되며 아무것도 자동 승인하지 않습니다.78허용 규칙은 리터럴 `mcp__<server>__` 접두사 이후에만 도구 이름 글롭을 허용합니다. 서버 세그먼트는 글롭이 없어야 하므로 규칙이 구성한 특정 서버의 이름을 지정합니다. `mcp__puppeteer__*`는 `puppeteer` 서버의 모든 도구와 일치하고 `mcp__github__get_*`는 해당 `get_` 도구와 일치합니다. `allowed_tools=["*"]` 또는 `allowed_tools=["mcp__*"]`와 같은 앵커되지 않은 항목은 시작 경고와 함께 무시되며 아무것도 자동 승인하지 않습니다.

68 79

69<Warning>80<Warning>

70 **자동 승인된 도구는 절대 `canUseTool`에 도달하지 않습니다.** `acceptEdits` 또는 `bypassPermissions`에 의해, 또는 허용 규칙에 의해 이전 단계에서 승인된 도구 호출은 `canUseTool` 콜백을 건너뛰므로 거기에 배치한 권한 검사는 해당 도구에 대해 자동으로 무시됩니다. 적용 범위는 항목의 형식에 따라 달라집니다. `Read` 또는 `mcp__github__get_issue`와 같은 단순 이름은 해당 도구에 대한 모든 호출을 자동 승인하는 반면, `Bash(ls *)`와 같은 범위 규칙은 일치하는 호출만 자동 승인하고 다른 `Bash` 호출은 여전히 콜백으로 통과합니다. 모든 도구 호출에서 실행되어야 하는 검사의 경우 [`PreToolUse` 훅](/ko/agent-sdk/hooks)을 사용합니다. 훅은 다른 모든 단계 이전에 실행되며, 훅 거부는 `bypassPermissions` 모드에서도 적용됩니다.81 **자동 승인된 도구는 절대 `canUseTool`에 도달하지 않습니다.** `acceptEdits` 또는 `bypassPermissions`에 의해, 또는 허용 규칙에 의해 이전 단계에서 승인된 도구 호출은 `canUseTool` 콜백을 건너뛰므로 거기에 배치한 권한 검사는 해당 도구에 대해 자동으로 무시됩니다. 예외는 사용자 상호작용이 필요한 도구인 `AskUserQuestion` 및 [`_meta["anthropic/requiresUserInteraction"]`](/ko/mcp#require-approval-for-a-specific-tool)로 표시된 MCP 도구이며, 이들은 허용 규칙이 일치할 때에도 콜백에 도달합니다. 적용 범위는 항목의 형식에 따라 달라집니다. `Read` 또는 `mcp__github__get_issue`와 같은 단순 이름은 해당 도구에 대한 모든 호출을 자동 승인하는 반면, `Bash(ls *)`와 같은 범위 규칙은 일치하는 호출만 자동 승인하고 다른 `Bash` 호출은 여전히 콜백으로 통과합니다. 모든 도구 호출에서 실행되어야 하는 검사의 경우 [`PreToolUse` 훅](/ko/agent-sdk/hooks)을 사용합니다. 훅은 다른 모든 단계 이전에 실행되며, 훅 거부는 `bypassPermissions` 모드에서도 적용됩니다.

71</Warning>82</Warning>

72 83

73잠금된 에이전트의 경우 `allowedTools`를 `permissionMode: "dontAsk"`와 쌍으로 사용합니다. 나열된 도구는 승인되고 다른 모든 항목은 프롬프트 대신 완전히 거부됩니다:84잠금된 에이전트의 경우 `allowedTools`를 `permissionMode: "dontAsk"`와 쌍으로 사용합니다. 나열된 도구는 승인되고 다른 모든 항목은 프롬프트 대신 완전히 거부됩니다:

agent-sdk/python.md +1 −1

Details

958```958```

959 959

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

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

962* `CLAUDE_ASYNC_AGENT_STALL_TIMEOUT_MS`: `run_in_background`으로 시작된 서브에이전트의 정지 감시견. 기본값 `600000`. 각 스트림 이벤트에서 재설정됩니다. 정지 시 서브에이전트를 중단하고, 작업을 실패로 표시하고, 부분 결과와 함께 오류를 부모에게 표시합니다. 동기 서브에이전트에는 적용되지 않습니다.962* `CLAUDE_ASYNC_AGENT_STALL_TIMEOUT_MS`: `run_in_background`으로 시작된 서브에이전트의 정지 감시견. 기본값 `600000`. 각 스트림 이벤트에서 재설정됩니다. 정지 시 서브에이전트를 중단하고, 작업을 실패로 표시하고, 부분 결과와 함께 오류를 부모에게 표시합니다. 동기 서브에이전트에는 적용되지 않습니다.

963* `CLAUDE_ENABLE_STREAM_WATCHDOG` with `CLAUDE_STREAM_IDLE_TIMEOUT_MS`: 헤더가 도착했지만 응답 본문이 스트리밍을 중지할 때 요청을 중단합니다. 감시견은 모든 공급자에 대해 기본적으로 켜져 있습니다. `CLAUDE_ENABLE_STREAM_WATCHDOG=0`으로 설정하여 비활성화합니다. `CLAUDE_STREAM_IDLE_TIMEOUT_MS`는 기본값 `300000`이고 해당 최소값으로 제한됩니다. 중단된 요청은 정상 재시도 경로를 거칩니다.963* `CLAUDE_ENABLE_STREAM_WATCHDOG` with `CLAUDE_STREAM_IDLE_TIMEOUT_MS`: 헤더가 도착했지만 응답 본문이 스트리밍을 중지할 때 요청을 중단합니다. 감시견은 모든 공급자에 대해 기본적으로 켜져 있습니다. `CLAUDE_ENABLE_STREAM_WATCHDOG=0`으로 설정하여 비활성화합니다. `CLAUDE_STREAM_IDLE_TIMEOUT_MS`는 기본값 `300000`이고 해당 최소값으로 제한됩니다. 중단된 요청은 정상 재시도 경로를 거칩니다.

964 964

agent-sdk/subagents.md +36 −20

Details

7> 서브에이전트를 정의하고 호출하여 컨텍스트를 격리하고, 작업을 병렬로 실행하며, Claude Agent SDK 애플리케이션에서 특화된 지침을 적용합니다.7> 서브에이전트를 정의하고 호출하여 컨텍스트를 격리하고, 작업을 병렬로 실행하며, Claude Agent SDK 애플리케이션에서 특화된 지침을 적용합니다.

8 8

9서브에이전트는 메인 에이전트가 집중된 부작업을 처리하기 위해 생성할 수 있는 별도의 에이전트 인스턴스입니다.9서브에이전트는 메인 에이전트가 집중된 부작업을 처리하기 위해 생성할 수 있는 별도의 에이전트 인스턴스입니다.

10서브에이전트를 사용하여 집중된 부작업의 컨텍스트를 격리하고, 여러 분석을 병렬로 실행하며, 메인 에이전트의 프롬프트를 비대하게 만들지 않으면서 특화된 지침을 적용합니다.10서브에이전트를 사용하여 컨텍스트를 격리하고, 여러 분석을 병렬로 실행하며, 메인 에이전트의 프롬프트를 비대하게 만들지 않으면서 특화된 지침을 적용합니다.

11 11

12이 가이드에서는 `agents` 매개변수를 사용하여 SDK에서 서브에이전트를 정의하고 사용하는 방법을 설명합니다.12이 가이드에서는 `agents` 매개변수를 사용하여 SDK에서 서브에이전트를 정의하고 사용하는 방법을 설명합니다.

13 13

17 17

18서브에이전트를 세 가지 방법으로 생성할 수 있습니다.18서브에이전트를 세 가지 방법으로 생성할 수 있습니다.

19 19

~~20* **프로그래밍 방식**: `query()` 옵션에서 `agents` 매개변수 사용 ([TypeScript](/ko/agent-sdk/typescript#agentdefinition), [Python](/ko/agent-sdk/python#agentdefinition))~~20* **프로그래밍 방식**: `query()` 옵션에서 `agents` 매개변수 사용. [TypeScript](/ko/agent-sdk/typescript#agentdefinition) 및 [Python](/ko/agent-sdk/python#agentdefinition) 참조 확인

~~21* **파일 시스템 기반**: `.claude/agents/` 디렉토리에 마크다운 파일로 에이전트 정의 ([서브에이전트를 파일로 정의](/ko/sub-agents) 참조)~~21* **파일 시스템 기반**: `.claude/agents/` 디렉토리에 마크다운 파일로 에이전트 정의. [서브에이전트를 파일로 정의](/ko/sub-agents) 참조

22* **기본 제공 범용**: Claude는 언제든지 Agent 도구를 통해 기본 제공 `general-purpose` 서브에이전트를 호출할 수 있습니다.22* **기본 제공 범용**: Claude는 언제든지 Agent 도구를 통해 기본 제공 `general-purpose` 서브에이전트를 호출할 수 있습니다.

23 23

24이 가이드는 SDK 애플리케이션에 권장되는 프로그래밍 방식에 중점을 둡니다.24이 가이드는 SDK 애플리케이션에 권장되는 프로그래밍 방식에 중점을 둡니다.

61 61

62**예시:** `doc-reviewer` 서브에이전트는 Read 및 Grep 도구에만 액세스할 수 있으므로, 문서 파일을 분석할 수 있지만 실수로 수정할 수 없습니다.62**예시:** `doc-reviewer` 서브에이전트는 Read 및 Grep 도구에만 액세스할 수 있으므로, 문서 파일을 분석할 수 있지만 실수로 수정할 수 없습니다.

63 63

~~64<h2 id="creating-subagents">~~64<h2 id="create-subagents">

65 서브에이전트 생성65 서브에이전트 생성

66</h2>66</h2>

67 67

69 프로그래밍 방식 정의 (권장)69 프로그래밍 방식 정의 (권장)

70</h3>70</h3>

71 71

72`agents` 매개변수를 사용하여 코드에서 직접 서브에이전트를 정의합니다. 이 예시는 읽기 전용 액세스가 있는 코드 리뷰어와 명령을 실행할 수 있는 테스트 러너라는 두 개의 서브에이전트를 생성합니다. Claude가 `Agent` 도구를 통해 서브에이전트를 호출하므로 `allowedTools`에 `Agent`를 포함하여 권한 프롬프트 없이 서브에이전트 호출을 자동으로 승인합니다.72`agents` 매개변수를 사용하여 코드에서 직접 서브에이전트를 정의합니다. Claude는 `Agent` 도구를 통해 서브에이전트를 호출하므로 `allowedTools`에 `Agent`를 포함하여 권한 프롬프트 없이 서브에이전트 호출을 자동으로 승인합니다.

73 73

74이 페이지의 대부분의 예시는 최종 결과만 출력합니다. Claude가 서브에이전트에 위임했는지 직접 답변했는지 확인하려면 [서브에이전트 호출 감지](#detecting-subagent-invocation)를 참조하세요.74이 페이지의 대부분의 예시는 최종 결과만 출력합니다. Claude가 서브에이전트에 위임했는지 직접 답변했는지 확인하려면 [서브에이전트 호출 감지](#detect-subagent-invocation)를 참조하세요.

76이 예시는 읽기 전용 액세스가 있는 코드 리뷰어와 명령을 실행할 수 있는 테스트 러너라는 두 개의 서브에이전트를 생성합니다.

75 77

76<CodeGroup>78<CodeGroup>

77 ```python Python theme={null}79 ```python Python theme={null}

197 199

198Python SDK에서 `disallowedTools` 및 `mcpServers`와 같은 여러 단어로 된 필드 이름은 Python의 snake\_case 규칙을 따르지 않고 와이어 형식과 일치하도록 camelCase를 유지합니다. 자세한 내용은 [`AgentDefinition` 참조](/ko/agent-sdk/python#agentdefinition)를 참조하세요.200Python SDK에서 `disallowedTools` 및 `mcpServers`와 같은 여러 단어로 된 필드 이름은 Python의 snake\_case 규칙을 따르지 않고 와이어 형식과 일치하도록 camelCase를 유지합니다. 자세한 내용은 [`AgentDefinition` 참조](/ko/agent-sdk/python#agentdefinition)를 참조하세요.

199 201

202Claude Code v2.1.198에서 두 가지 서브에이전트 동작이 변경되었습니다:

203

204* 서브에이전트는 기본적으로 백그라운드에서 실행됩니다. [`run_in_background`](/ko/agent-sdk/typescript) 입력을 생략하는 Agent 도구 호출은 백그라운드 서브에이전트를 시작하고, Claude는 계속하기 전에 결과가 필요할 때 `run_in_background: false`를 설정합니다. v2.1.198 이전에는 `run_in_background`를 생략하면 서브에이전트가 동기적으로 실행되었습니다. 특정 에이전트에 대해 Claude가 요청하는 것과 관계없이 백그라운드 실행을 강제하려면 `background` 필드를 `true`로 설정합니다.

205* 서브에이전트는 메인 세션의 확장 사고 구성을 상속합니다. 이전 버전에서는 메인 세션의 설정과 관계없이 서브에이전트 내에서 확장 사고가 비활성화됩니다.

206

200<Note>207<Note>

201 {/* min-version: 2.1.172 */}Claude Code v2.1.172부터 서브에이전트는 자신의 서브에이전트를 생성할 수 있습니다. 메인 에이전트 아래 5단계 깊이의 서브에이전트는 추가 서브에이전트를 생성할 수 없습니다. 포그라운드 또는 백그라운드에서 실행되는지 여부와 관계없이 이 제한이 적용됩니다. 서브에이전트가 다른 서브에이전트를 생성하지 못하도록 하려면 `tools` 배열에서 `Agent`를 생략하거나 `disallowedTools`에 추가합니다. 전체 깊이 규칙은 [중첩된 서브에이전트](/ko/sub-agents#spawn-nested-subagents)를 참조하세요.208 {/* min-version: 2.1.172 */}Claude Code v2.1.172부터 서브에이전트는 자신의 서브에이전트를 생성할 수 있습니다. 메인 에이전트 아래 5단계 깊이의 서브에이전트는 포그라운드 또는 백그라운드에서 실행되는지 여부와 관계없이 추가 서브에이전트를 생성할 수 없습니다. 서브에이전트가 다른 서브에이전트를 생성하지 못하도록 하려면 `tools` 배열에서 `Agent`를 생략하거나 `disallowedTools`에 추가합니다. 전체 깊이 규칙은 [중첩된 서브에이전트](/ko/sub-agents#spawn-nested-subagents)를 참조하세요.

202</Note>209</Note>

203 210

204<h3 id="filesystem-based-definition-alternative">211<h3 id="filesystem-based-definition-alternative">

225 232

226<Note>233<Note>

227 부모는 서브에이전트의 최종 메시지를 Agent 도구 결과로 그대로 받지만, 자신의 응답에서 요약할 수 있습니다. 서브에이전트 출력을 사용자 대면 응답에서 그대로 유지하려면, **메인** `query()` 호출에 전달하는 프롬프트 또는 `systemPrompt` 옵션에 그렇게 하도록 지시하는 지침을 포함하세요.234 부모는 서브에이전트의 최종 메시지를 Agent 도구 결과로 그대로 받지만, 자신의 응답에서 요약할 수 있습니다. 서브에이전트 출력을 사용자 대면 응답에서 그대로 유지하려면, 메인 `query()` 호출에 전달하는 프롬프트 또는 `systemPrompt` 옵션에 그렇게 하도록 지시하는 지침을 포함하세요.

228</Note>235</Note>

229 236

230<h2 id="invoking-subagents">237Claude Code v2.1.199 기준으로, 속도 제한과 같이 서브에이전트를 조기에 종료하는 API 오류는 절대 결과로 전달되지 않습니다. 서브에이전트가 이미 출력을 생성한 경우, Agent 도구는 서브에이전트가 완료되지 않았다는 메모와 함께 해당 부분 출력을 반환합니다. 그렇지 않으면 도구 결과는 오류 메시지인 `Agent terminated early due to an API error`이며, 그 뒤에 오류 세부 정보가 따릅니다. 자세한 내용은 [서브에이전트의 API 오류](/ko/sub-agents#api-errors-in-subagents)를 참조하세요.

238

239<h2 id="invoke-subagents">

231 서브에이전트 호출240 서브에이전트 호출

232</h2>241</h2>

233 242

329 ```338 ```

330</CodeGroup>339</CodeGroup>

331 340

332<h2 id="detecting-subagent-invocation">341<h2 id="detect-subagent-invocation">

333 서브에이전트 호출 감지342 서브에이전트 호출 감지

334</h2>343</h2>

335 344

336서브에이전트는 Agent 도구를 통해 호출됩니다. 서브에이전트가 호출될 때를 감지하려면, `name`이 `"Agent"`인 `tool_use` 블록을 확인하세요. 서브에이전트의 컨텍스트 내에서의 메시지에는 `parent_tool_use_id` 필드가 포함됩니다.345Claude는 Agent 도구를 통해 서브에이전트를 호출합니다. 서브에이전트가 호출될 때를 감지하려면, `name`이 `"Agent"`인 `tool_use` 블록을 확인하세요. 서브에이전트의 컨텍스트 내에서의 메시지에는 `parent_tool_use_id` 필드가 포함됩니다.

337 346

338<Note>347<Note>

339 도구 이름은 Claude Code v2.1.63에서 `"Task"`에서 `"Agent"`로 변경되었습니다. 현재 SDK 릴리스는 `tool_use` 블록에서 `"Agent"`를 내보내지만 여전히 `system:init` 도구 목록과 `result.permission_denials[].tool_name`에서 `"Task"`를 사용합니다. `block.name`에서 두 값을 모두 확인하면 SDK 버전 간 호환성이 보장됩니다.348 도구 이름은 Claude Code v2.1.63에서 `"Task"`에서 `"Agent"`로 변경되었습니다. 현재 SDK 릴리스는 `tool_use` 블록에서 `"Agent"`를 내보내지만 여전히 `system:init` 도구 목록과 `result.permission_denials[].tool_name`에서 `"Task"`를 사용합니다. `block.name`에서 두 값을 모두 확인하면 SDK 버전 간 호환성이 보장됩니다.

422 ```431 ```

423</CodeGroup>432</CodeGroup>

424 433

425<h2 id="resuming-subagents">434<h2 id="resume-subagents">

426 서브에이전트 재개435 서브에이전트 재개

427</h2>436</h2>

428 437

429서브에이전트를 재개하여 중단한 지점에서 계속할 수 있습니다. 재개된 서브에이전트는 이전의 모든 도구 호출, 결과 및 추론을 포함한 전체 대화 기록을 유지합니다. 서브에이전트는 새로 시작하는 대신 정확히 중단한 지점에서 계속됩니다.438서브에이전트를 재개하여 중단한 지점에서 계속할 수 있습니다. 재개된 서브에이전트는 이전의 모든 도구 호출, 결과 및 추론을 포함한 전체 대화 기록을 유지합니다.

430 439

431서브에이전트가 완료되면, Agent 도구 결과에는 `agentId: <id>`를 포함하는 텍스트 블록이 포함됩니다. 기본 제공 [`Explore` 및 `Plan` 에이전트](/ko/sub-agents#built-in-subagents)는 일회성이며 `agentId`를 반환하지 않으므로, 재개가 필요한 경우 사용자 정의 에이전트 또는 `general-purpose`를 사용하세요. 서브에이전트를 프로그래밍 방식으로 재개하려면:440서브에이전트가 완료되면, Agent 도구 결과에는 `agentId: <id>`를 포함하는 텍스트 블록이 포함됩니다. 기본 제공 [`Explore` 및 `Plan` 에이전트](/ko/sub-agents#built-in-subagents)는 일회성이며 `agentId`를 반환하지 않으므로, 재개가 필요한 경우 사용자 정의 에이전트 또는 `general-purpose`를 사용하세요. 서브에이전트를 프로그래밍 방식으로 재개하려면:

432 441

662 671

663Claude가 서브에이전트에 위임하는 대신 작업을 직접 완료하는 경우:672Claude가 서브에이전트에 위임하는 대신 작업을 직접 완료하는 경우:

664 673

6651. **Agent 호출이 승인되었는지 확인**: `allowedTools`에 `Agent`를 포함하여 서브에이전트 호출을 자동 승인합니다. 이를 포함하지 않으면 Agent 호출이 `canUseTool` 콜백으로 전달되거나 `dontAsk` 모드에서는 거부됩니다.674* **Agent 호출이 승인되었는지 확인**: `allowedTools`에 `Agent`를 포함하여 서브에이전트 호출을 자동 승인합니다. 이를 포함하지 않으면 Agent 호출이 `canUseTool` 콜백으로 전달되거나 `dontAsk` 모드에서는 거부됩니다.

6662. **명시적 프롬프팅 사용**: 프롬프트에서 서브에이전트를 이름으로 언급하세요(예: "code-reviewer 에이전트를 사용하여...").675* **명시적 프롬프팅 사용**: 프롬프트에서 서브에이전트를 이름으로 언급하세요(예: "code-reviewer 에이전트를 사용하여...").

6673. **명확한 설명 작성**: Claude가 작업을 적절히 일치시킬 수 있도록 서브에이전트를 사용해야 할 때를 정확히 설명하세요.676* **명확한 설명 작성**: Claude가 작업을 적절히 일치시킬 수 있도록 서브에이전트를 사용해야 할 때를 정확히 설명하세요.

668 677

669<h3 id="filesystem-based-agents-not-loading">678<h3 id="filesystem-based-agents-not-loading">

670 파일 시스템 기반 에이전트가 로드되지 않음679 파일 시스템 기반 에이전트가 로드되지 않음

671</h3>680</h3>

672 681

673`.claude/agents/`에 정의된 에이전트는 시작 시에만 로드됩니다. Claude Code가 실행 중인 동안 새 에이전트 파일을 생성하면, 세션을 다시 시작하여 로드하세요.682Claude Code는 `~/.claude/agents/` 및 `.claude/agents/`를 감시하며 새로운 또는 편집된 에이전트 파일을 몇 초 내에 선택하며, 재시작이 필요하지 않습니다. 정의가 나타나지 않으면 다음 원인들을 확인하세요:

683

684* **새로운 `agents` 디렉토리**: 감시자는 세션이 시작될 때 존재했던 디렉토리만 포함하므로, 새 디렉토리의 첫 번째 파일은 세션 재시작이 필요합니다. 이것이 가장 일반적인 원인입니다.

685* **잘못된 frontmatter 또는 중복된 `name`**: 파일의 YAML을 확인하고, 기존 에이전트가 이미 해당 `name`을 사용하고 있는지 확인하세요.

686* **`--disable-slash-commands`**: 이 플래그로 시작된 세션은 이러한 디렉토리를 감시하지 않으며 새 파일을 로드하려면 항상 재시작이 필요합니다.

687* **동일한 이름의 프로그래밍 방식 에이전트**: `query()`에 전달된 `agents`는 동일한 이름의 파일 시스템 에이전트를 재정의합니다.

688

689파일 형식에 대해서는 [서브에이전트 파일 작성 방법](/ko/sub-agents#write-subagent-files)을 참조하세요.

674 690

675<h3 id="windows-long-prompt-failures">691<h3 id="long-prompt-failures-on-windows">

676 Windows: 긴 프롬프트 실패692 Windows에서 긴 프롬프트 실패

677</h3>693</h3>

678 694

679Windows에서는 매우 긴 프롬프트가 있는 서브에이전트가 명령줄 길이 제한(8191자)으로 인해 실패할 수 있습니다. 프롬프트를 간결하게 유지하거나 복잡한 지침에는 파일 시스템 기반 에이전트를 사용하세요.695Windows에서는 매우 긴 프롬프트가 있는 서브에이전트가 명령줄 길이 제한인 8191자로 인해 실패할 수 있습니다. 프롬프트를 간결하게 유지하거나 복잡한 지침에는 파일 시스템 기반 에이전트를 사용하세요.

680 696

681<h2 id="related-documentation">697<h2 id="related-documentation">

682 관련 문서698 관련 문서

agent-sdk/todo-tracking.md +68 −6

Details

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

10 10

11<Note>11<Note>

12 TypeScript Agent SDK 0.3.142 및 Claude Code v2.1.142부터 세션은 `TodoWrite` 대신 구조화된 Task 도구인 `TaskCreate`, `TaskUpdate`, `TaskGet`, `TaskList`를 사용합니다. 모니터링 코드 변경 방법은 [Task 도구로 마이그레이션](#migrate-to-task-tools)을 참조하십시오. 이 페이지의 예제는 아직 마이그레이션하지 않은 세션에 대해 `TodoWrite`를 계속 표시하기 위해 `CLAUDE_CODE_ENABLE_TASKS=0`을 설정합니다.12 TypeScript Agent SDK 0.3.142 및 Claude Code v2.1.142부터 세션은 `TodoWrite` 대신 구조화된 Task 도구인 `TaskCreate`, `TaskUpdate`, `TaskGet`, `TaskList`를 사용합니다. Python SDK는 Python 패키지 버전이 아닌 실행하는 Claude Code CLI에서 이 변경 사항을 가져옵니다. pip 패키지 내에 번들된 CLI 또는 `cli_path`로 지정한 CLI가 v2.1.142 이상이면 전환이 적용됩니다. 모니터링 코드 변경 방법은 [Task 도구로 마이그레이션](#migrate-to-task-tools)을 참조하십시오. 이 페이지의 예제는 아직 마이그레이션하지 않은 세션에 대해 `TodoWrite`를 계속 표시하기 위해 `CLAUDE_CODE_ENABLE_TASKS=0`을 설정합니다.

13</Note>13</Note>

14 14

15<h3 id="todo-lifecycle">15<h3 id="todo-lifecycle">

27 할일이 사용되는 경우27 할일이 사용되는 경우

28</h3>28</h3>

29 29

~~30SDK는 다음의 경우에 자동으로 할일을 생성합니다:~~30SDK는 대부분의 다단계 작업에 대해 할일을 생성합니다. 예를 들면:

31 31

32* **복잡한 다단계 작업** - 3개 이상의 서로 다른 작업이 필요한 경우32* **복잡한 다단계 작업** - 3개 이상의 서로 다른 작업이 필요한 경우

33* **사용자 제공 작업 목록** - 여러 항목이 언급될 때33* **사용자 제공 작업 목록** - 여러 항목이 언급될 때

34* **중요한 작업** - 진행 상황 추적이 도움이 되는 경우34* **중요한 작업** - 진행 상황 추적이 도움이 되는 경우

35* **명시적 요청** - 사용자가 할일 구성을 요청할 때35* **명시적 요청** - 사용자가 할일 구성을 요청할 때

36 36

37매우 짧거나 단일 단계의 요청에 대해서는 할일을 건너뛸 수 있습니다.

37<h2 id="examples">39<h2 id="examples">

38 예제40 예제

39</h2>41</h2>

40 42

43이 예제들을 실행하기 전에 [빠른 시작](/ko/agent-sdk/quickstart)을 따라 Claude Agent SDK를 설치하십시오.

45각 예제는 에이전트가 완료될 때까지 실행되고 최종 결과 메시지를 생성합니다. 세션이 먼저 턴 제한에 도달하면 해당 결과 메시지는 `error_max_turns` 서브타입을 가집니다. 해당 종료를 감지하려면 `subtype`을 확인하십시오.

47이 예제들은 단일 `query()` 호출을 사용합니다. `error_max_turns` 결과를 생성한 후 `query()`는 `Reached maximum number of turns`를 포함하는 오류를 발생시킵니다. 각 예제는 이것이 발생할 때 깔끔하게 종료하기 위해 루프를 try 블록으로 래핑합니다.

49결과 서브타입에 대해서는 [결과 처리](/ko/agent-sdk/agent-loop#handle-the-result)를 참조하십시오.

41<h3 id="monitoring-todo-changes">51<h3 id="monitoring-todo-changes">

42 할일 변경 모니터링52 할일 변경 모니터링

43</h3>53</h3>

46 ```typescript TypeScript theme={null}56 ```typescript TypeScript theme={null}

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

48 58

59 try {

49 for await (const message of query({60 for await (const message of query({

50 prompt: "Optimize my React app performance and track progress with todos",61 prompt: "Optimize my React app performance and track progress with todos",

51 // Re-enable TodoWrite, which this example monitors. Without it, the SDK uses62 // Re-enable TodoWrite, which this example monitors. Without it, the SDK uses

68 }79 }

69 }80 }

70 }81 }

82 } catch (error) {

83 // A single-shot query() throws after yielding an error result,

84 // such as when the maxTurns limit is hit.

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

86 }

71 ```87 ```

72 88

73 ```python Python theme={null}89 ```python Python theme={null}

90 import asyncio

74 from claude_agent_sdk import query, ClaudeAgentOptions, AssistantMessage, ToolUseBlock92 from claude_agent_sdk import query, ClaudeAgentOptions, AssistantMessage, ToolUseBlock

75 93

95 async def main():

96 try:

76 async for message in query(97 async for message in query(

77 prompt="Optimize my React app performance and track progress with todos",98 prompt="Optimize my React app performance and track progress with todos",

78 # Re-enable TodoWrite, which this example monitors. Without it, the SDK uses99 # Re-enable TodoWrite, which this example monitors. Without it, the SDK uses

95 else "❌"116 else "❌"

96 )117 )

97 print(f"{i + 1}. {status} {todo['content']}")118 print(f"{i + 1}. {status} {todo['content']}")

119 except Exception as error:

120 # A single-shot query() raises after yielding an error result,

121 # such as when the max_turns limit is hit.

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

123

124

125 asyncio.run(main())

98 ```126 ```

99</CodeGroup>127</CodeGroup>

100 128

128 }156 }

129 157

130 async trackQuery(prompt: string) {158 async trackQuery(prompt: string) {

159 try {

131 for await (const message of query({160 for await (const message of query({

132 prompt,161 prompt,

133 // Re-enable TodoWrite, which this tracker watches for.162 // Re-enable TodoWrite, which this tracker watches for.

142 }171 }

143 }172 }

144 }173 }

174 } catch (error) {

175 // A single-shot query() throws after yielding an error result,

176 // such as when the maxTurns limit is hit.

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

178 }

145 }179 }

146 }180 }

147 181

151 ```185 ```

152 186

153 ```python Python theme={null}187 ```python Python theme={null}

188 import asyncio

189

154 from claude_agent_sdk import query, ClaudeAgentOptions, AssistantMessage, ToolUseBlock190 from claude_agent_sdk import query, ClaudeAgentOptions, AssistantMessage, ToolUseBlock

155 from typing import List, Dict191 from typing import List, Dict

156 192

186 print(f"{i + 1}. {icon} {text}")222 print(f"{i + 1}. {icon} {text}")

187 223

188 async def track_query(self, prompt: str):224 async def track_query(self, prompt: str):

225 try:

189 async for message in query(226 async for message in query(

190 prompt=prompt,227 prompt=prompt,

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

196 if isinstance(block, ToolUseBlock) and block.name == "TodoWrite":233 if isinstance(block, ToolUseBlock) and block.name == "TodoWrite":

197 self.todos = block.input["todos"]234 self.todos = block.input["todos"]

198 self.display_progress()235 self.display_progress()

236 except Exception as error:

237 # A single-shot query() raises after yielding an error result,

238 # such as when the max_turns limit is hit.

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

199 240

200 241

201 # Usage242 # Usage

243 async def main():

202 tracker = TodoTracker()244 tracker = TodoTracker()

203 await tracker.track_query("Build a complete authentication system with todos")245 await tracker.track_query("Build a complete authentication system with todos")

246

247

248 asyncio.run(main())

204 ```249 ```

205</CodeGroup>250</CodeGroup>

206 251

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

219 264

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

221 266

222스트리밍된 `tool_use` 입력은 모델이 내보낸 원본 형태입니다. Claude Code는 실행 전에 일부 거의 올바른 키 이름을 수정하여 `id` 또는 `task_id`를 `taskId`로, `active_form`을 `activeForm`으로 매핑하지만, 이 수정은 스트림에 반영되지 않습니다. 아래 샘플처럼 `TaskUpdate` 입력 필드를 방어적으로 읽으십시오. 정규 이름이 항상 존재한다고 가정하지 마십시오.267스트리밍된 `tool_use` 입력은 모델이 내보낸 원본 형태입니다. Claude Code는 실행 전에 일부 거의 올바른 키 이름을 수정하여 `id` 또는 `task_id`를 `taskId`로, `active_form`을 `activeForm`으로 매핑하지만, 이 수정은 스트림에 반영되지 않습니다. 아래 샘플처럼 `TaskUpdate` 입력 필드를 방어적으로 읽으십시오. 정규 이름이 항상 존재한다고 가정하지 마십시오.

223 268

225 ```typescript TypeScript theme={null}270 ```typescript TypeScript theme={null}

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

227 272

273 try {

228 for await (const message of query({274 for await (const message of query({

229 prompt: "Optimize my React app performance",275 prompt: "Optimize my React app performance and track progress with todos",

276 options: { maxTurns: 15 },

230 })) {277 })) {

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

232 for (const block of message.message.content) {279 for (const block of message.message.content) {

246 }293 }

247 }294 }

248 }295 }

296 } catch (error) {

297 // A single-shot query() throws after yielding an error result.

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

299 }

249 ```300 ```

250 301

251 ```python Python theme={null}302 ```python Python theme={null}

252 from claude_agent_sdk import query, AssistantMessage, ToolUseBlock303 import asyncio

253 304

305 from claude_agent_sdk import query, ClaudeAgentOptions, AssistantMessage, ToolUseBlock

306

307 async def main():

308 try:

254 async for message in query(309 async for message in query(

255 prompt="Optimize my React app performance",310 prompt="Optimize my React app performance and track progress with todos",

311 options=ClaudeAgentOptions(max_turns=15),

256 ):312 ):

257 if not isinstance(message, AssistantMessage):313 if not isinstance(message, AssistantMessage):

258 continue314 continue

269 )325 )

270 if task_id:326 if task_id:

271 print(f" {task_id} -> {block.input['status']}")327 print(f" {task_id} -> {block.input['status']}")

328 except Exception as error:

329 # A single-shot query() raises after yielding an error result.

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

331

332

333 asyncio.run(main())

272 ```334 ```

273</CodeGroup>335</CodeGroup>

274 336

agent-sdk/typescript.md +19 −7

Details

551```551```

552 552

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

554* `CLAUDE_CODE_MAX_RETRIES`: 최대 API 재시도 횟수. 기본값 `10`, 최대 `15`로 제한됩니다. 각 재시도는 자체 `API_TIMEOUT_MS` 윈도우를 가지므로 최악의 경우 벽시간은 대략 `API_TIMEOUT_MS × (CLAUDE_CODE_MAX_RETRIES + 1)` 더하기 백오프입니다. 더 긴 중단을 기다려야 하는 무인 실행의 경우 `CLAUDE_CODE_RETRY_WATCHDOG=1`을 설정하여 용량 오류를 무한정 재시도합니다.554* `CLAUDE_CODE_MAX_RETRIES`: 최대 API 재시도 횟수. 기본값 `10`, 최대 `15`로 제한됩니다. 각 재시도는 자체 `API_TIMEOUT_MS` 윈도우를 가지므로 최악의 경우 벽시간은 대략 `API_TIMEOUT_MS × (CLAUDE_CODE_MAX_RETRIES + 1)` 더하기 백오프입니다. 더 긴 중단을 기다려야 하는 무인 실행의 경우 `CLAUDE_CODE_RETRY_WATCHDOG=1`을 설정하여 용량 오류를 무한정 재시도합니다. 그리고 {/* min-version: 2.1.199 */}Claude Code v2.1.199부터 다른 일시적 오류의 기본값을 `300`으로 올리고 이 변수의 상한을 제거합니다.

555* `CLAUDE_ASYNC_AGENT_STALL_TIMEOUT_MS`: `run_in_background`으로 시작된 서브에이전트에 대한 정지 감시견입니다. 기본값 `600000`. 각 스트림 이벤트에서 재설정되며, 정지 시 서브에이전트를 중단하고 작업을 실패로 표시하며 부분 결과와 함께 오류를 부모에게 표시합니다. 동기 서브에이전트에는 적용되지 않습니다.555* `CLAUDE_ASYNC_AGENT_STALL_TIMEOUT_MS`: `run_in_background`으로 시작된 서브에이전트에 대한 정지 감시견입니다. 기본값 `600000`. 각 스트림 이벤트에서 재설정되며, 정지 시 서브에이전트를 중단하고 작업을 실패로 표시하며 부분 결과와 함께 오류를 부모에게 표시합니다. 동기 서브에이전트에는 적용되지 않습니다.

556* `CLAUDE_ENABLE_STREAM_WATCHDOG` 및 `CLAUDE_STREAM_IDLE_TIMEOUT_MS`: 헤더가 도착했지만 응답 본문이 스트리밍을 중지할 때 요청을 중단합니다. 감시견은 모든 공급자에 대해 기본적으로 켜져 있습니다. `CLAUDE_ENABLE_STREAM_WATCHDOG=0`으로 설정하여 비활성화합니다. `CLAUDE_STREAM_IDLE_TIMEOUT_MS`는 기본값 `300000`이고 해당 최소값으로 고정됩니다. 중단된 요청은 일반 재시도 경로를 거칩니다.556* `CLAUDE_ENABLE_STREAM_WATCHDOG` 및 `CLAUDE_STREAM_IDLE_TIMEOUT_MS`: 헤더가 도착했지만 응답 본문이 스트리밍을 중지할 때 요청을 중단합니다. 감시견은 모든 공급자에 대해 기본적으로 켜져 있습니다. `CLAUDE_ENABLE_STREAM_WATCHDOG=0`으로 설정하여 비활성화합니다. `CLAUDE_STREAM_IDLE_TIMEOUT_MS`는 기본값 `300000`이고 해당 최소값으로 고정됩니다. 중단된 요청은 일반 재시도 경로를 거칩니다.

557 557

901 decisionReason?: string;901 decisionReason?: string;

902 toolUseID: string;902 toolUseID: string;

903 agentID?: string;903 agentID?: string;

904 requestId: string;

904 }905 }

905) => Promise<PermissionResult>;906) => Promise<PermissionResult | null>;

906```907```

907 908

908| 옵션 | 타입 | 설명 |909| 옵션 | 타입 | 설명 |

917| `requestId` | `string` | `control_request` 봉투의 `request_id`입니다. 애플리케이션이 SDK 외부에서 보내는 `control_response` (예: 서명된 HTTP POST)는 이 값을 반복해야 Claude Code 프로세스가 회신을 요청과 일치시킬 수 있습니다 |

918

919콜백은 일반적으로 [`PermissionResult`](#permissionresult)를 반환하여 요청을 해결하며, SDK는 이를 전송을 통해 `control_response`로 다시 작성합니다. 애플리케이션이 이미 이 요청에 대해 `control_response`를 자체 채널을 통해 보낸 경우에만 `null`을 반환하고 `requestId`를 반복합니다. SDK는 그러면 전송에 응답을 작성하는 것을 건너뜁니다. 다른 경우에 `null`을 반환하면 도구 호출이 무한정 차단된 상태로 유지됩니다. `control_response`가 전송되지 않고 권한 프롬프트가 시간 초과되지 않기 때문입니다.

920

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

916 922

917<h3 id="permissionresult">923<h3 id="permissionresult">

918 `PermissionResult`924 `PermissionResult`

2179};2185};

2180```2186```

2181 2187

2182ID로 실행 중인 백그라운드 작업 또는 셸을 중지합니다.2188ID로 실행 중인 백그라운드 작업 또는 셸을 중지합니다. {/* min-version: 2.1.198 */}v2.1.198부터 `task_id`는 에이전트 팀 팀원 또는 에이전트 ID 또는 이름으로 명명된 백그라운드 에이전트도 수락합니다.

2183 2189

2184<h3 id="notebookedit">2190<h3 id="notebookedit">

2185 NotebookEdit2191 NotebookEdit

3788| `ripgrep` | `{ command: string; args?: string[] }` | `undefined` | 샌드박스 환경을 위한 사용자 정의 ripgrep 바이너리 구성 |3794| `ripgrep` | `{ command: string; args?: string[] }` | `undefined` | 샌드박스 환경을 위한 사용자 정의 ripgrep 바이너리 구성 |

3789 3795

3790<Note>3796<Note>

3791 샌드박스는 플랫폼 지원에 따라 다르며, Linux에서는 `bubblewrap` 및 `socat`과 같은 도구가 필요합니다. `enabled`가 `true`이고 샌드박스를 시작할 수 없는 경우 `query()`는 `subtype: "error_during_execution"`이 있는 `result` 메시지를 보고하고 `errors`에 이유를 표시한 후 중지합니다. `query()`가 메시지를 생성하기 전에 예외를 발생시킬 것으로 예상하는 대신 해당 subtype을 감시합니다.3797 샌드박스는 플랫폼 지원에 따라 다르며, Linux에서는 `bubblewrap` 및 `socat`과 같은 도구가 필요합니다. `enabled`가 `true`이고 샌드박스를 시작할 수 없는 경우 `query()`는 `subtype: "error_during_execution"`이 있는 `result` 메시지를 보고하고 `errors`에 이유를 표시합니다. 단일 메시지 `query()` 호출의 경우 SDK는 해당 오류 결과를 생성한 후 예외를 발생시키므로 루프를 try 블록으로 래핑하여 이를 지나 계속 진행합니다. 오류 계약에 대해서는 [결과 처리](/ko/agent-sdk/agent-loop#handle-the-result)를 참조합니다.

3792 3798

3793 대신 샌드박스되지 않은 상태로 실행하려면 `failIfUnavailable: false`를 설정합니다.3799 대신 샌드박스되지 않은 상태로 실행하려면 `failIfUnavailable: false`를 설정합니다.

3794</Note>3800</Note>

3800```typescript theme={null}3806```typescript theme={null}

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

3802 3808

3803for await (const message of query({3809try {

3810 for await (const message of query({

3804 prompt: "Build and test my project",3811 prompt: "Build and test my project",

3805 options: {3812 options: {

3806 sandbox: {3813 sandbox: {

3811 }3818 }

3812 }3819 }

3813 }3820 }

3814})) {3821 })) {

3815 if ("result" in message) console.log(message.result);3822 if ("result" in message) console.log(message.result);

3823 }

3824} catch (error) {

3825 // 단일 쿼리 query()는 오류 결과를 생성한 후 예외를 발생시킵니다.

3826 // 예를 들어 샌드박스를 시작할 수 없는 경우 (failIfUnavailable은 기본값이 true입니다).

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

3816}3828}

3817```3829```

3818 3830

3929<Warning>3941<Warning>

3930 `dangerouslyDisableSandbox: true`로 실행되는 명령은 전체 시스템 액세스 권한이 있습니다. `canUseTool` 핸들러가 이러한 요청을 신중하게 검증하는지 확인합니다.3942 `dangerouslyDisableSandbox: true`로 실행되는 명령은 전체 시스템 액세스 권한이 있습니다. `canUseTool` 핸들러가 이러한 요청을 신중하게 검증하는지 확인합니다.

3931 3943

3932 `permissionMode`가 `bypassPermissions`로 설정되고 `allowUnsandboxedCommands`가 활성화되면 모델은 승인 프롬프트 없이 샌드박스 외부에서 명령을 자율적으로 실행할 수 있습니다. 이 조합은 모델이 샌드박스 격리를 조용히 탈출하도록 효과적으로 허용합니다.3944 `permissionMode`가 `bypassPermissions`로 설정되고 `allowUnsandboxedCommands`가 활성화되면 모델은 승인 프롬프트 없이 샌드박스 외부에서 명령을 자율적으로 실행할 수 있습니다 (명시적 [`ask` 규칙](/ko/agent-sdk/permissions#how-permissions-are-evaluated)은 여전히 하나를 강제합니다). 이 조합은 모델이 샌드박스 격리를 조용히 탈출하도록 효과적으로 허용합니다.

3933</Warning>3945</Warning>

3934 3946

3935<h2 id="see-also">3947<h2 id="see-also">

agent-teams.md +12 −3

Details

89* **Enter**: 선택한 팀원의 대화 기록을 열고 직접 메시지 전송89* **Enter**: 선택한 팀원의 대화 기록을 열고 직접 메시지 전송

90* **Escape**: 선택한 팀원의 현재 턴 중단90* **Escape**: 선택한 팀원의 현재 턴 중단

91 91

92{/* min-version: 2.1.181 */}v2.1.181부터, 유휴 팀원의 행은 30초 후 숨겨지고 다음 턴에 다시 나타납니다. 팀원은 숨겨진 상태에서도 계속 실행되고 주소 지정 가능합니다.92{/* min-version: 2.1.199 */}v2.1.199부터, 유휴 팀원의 행은 다른 팀원이나 서브에이전트가 여전히 작업 중인 동안 패널에 남아 있으므로, 이를 선택하여 대화 기록을 검토하거나 추가 작업을 보낼 수 있습니다. 패널의 모든 에이전트가 유휴 상태가 되면, 유휴 행은 30초 후 숨겨지고 팀원의 다음 턴에 다시 나타납니다. 팀원은 숨겨진 상태에서도 계속 실행되고 주소 지정 가능합니다. v2.1.181부터 v2.1.198까지는, 유휴 행이 다른 팀원들이 여전히 작업 중이더라도 자신의 턴이 끝난 후 30초 후에 숨겨졌습니다. v2.1.181 이전 버전에서는 유휴 행이 숨겨지지 않습니다.

94세 명 이상의 팀원이 동시에 유휴 상태일 때, 처음 세 명을 넘는 행들은 `5명이 유휴 상태일 때 2명의 유휴 에이전트`와 같이 축소된 팀원의 수를 세는 단일 행으로 축소됩니다. 이를 선택하고 Enter를 누르면 축소된 행들이 확장되거나, Esc를 누르면 다시 축소됩니다. 작업 중인 팀원, 실패한 팀원, 그리고 현재 보고 있는 팀원은 항상 자신의 행을 유지합니다.

93 95

94각 팀원이 자신의 분할 창에 있기를 원하면 [표시 모드 선택](#choose-a-display-mode)을 참조합니다.96각 팀원이 자신의 분할 창에 있기를 원하면 [표시 모드 선택](#choose-a-display-mode)을 참조합니다.

95 97

174* **In-process 모드**: 에이전트 패널에서 위아래 화살표 키를 사용하여 팀원을 선택한 후 Enter를 눌러 세션을 보고 입력하여 메시지를 보냅니다. 선택된 팀원에서 `x`를 눌러 중지합니다. Ctrl+T를 눌러 작업 목록을 전환합니다.176* **In-process 모드**: 에이전트 패널에서 위아래 화살표 키를 사용하여 팀원을 선택한 후 Enter를 눌러 세션을 보고 입력하여 메시지를 보냅니다. 선택된 팀원에서 `x`를 눌러 중지합니다. Ctrl+T를 눌러 작업 목록을 전환합니다.

175* **분할 창 모드**: 팀원의 창을 클릭하여 세션과 직접 상호작용합니다. 각 팀원은 자신의 터미널의 전체 보기를 가집니다.177* **분할 창 모드**: 팀원의 창을 클릭하여 세션과 직접 상호작용합니다. 각 팀원은 자신의 터미널의 전체 보기를 가집니다.

176 178

179팀원을 보고 있는 동안, 일반 텍스트와 [skills](/ko/skills)는 해당 팀원에게 전달되지만, 기본 제공 명령은 여전히 리더의 세션에서 실행됩니다.

180

181팀원의 모델과 빠른 모드는 생성될 때 고정되므로, `/model`과 `/fast`는 리더의 설정만 변경합니다. {/* min-version: 2.1.199 */}v2.1.199부터는 팀원을 보고 있는 동안 두 명령 중 하나를 입력하면 변경이 리더에게 적용된다는 알림이 표시됩니다. 이전 버전은 표시 없이 리더에게 적용했습니다. `/effort`는 여전히 보고 있는 팀원의 이후 턴에 적용됩니다. 팀원들은 리더의 [노력 수준](/ko/model-config#adjust-effort-level)을 따르기 때문입니다.

182

177<h3 id="assign-and-claim-tasks">183<h3 id="assign-and-claim-tasks">

178 작업 할당 및 요청184 작업 할당 및 요청

179</h3>185</h3>

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

296 302

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

298* **유휴 알림**: 팀원이 완료되고 중지되면, 자동으로 리더에게 알립니다.304* **유휴 알림**: 팀원이 완료되고 중지되면, 자동으로 리더에게 알립니다. {/* min-version: 2.1.198 */}v2.1.198부터, 턴이 API 오류로 끝난 팀원은 정상적으로 완료된 것처럼 보이는 대신 실패했음을 리더에게 알리고 오류 텍스트를 포함합니다.

299* **공유 작업 목록**: 모든 에이전트는 작업 상태를 보고 사용 가능한 작업을 요청할 수 있습니다.305* **공유 작업 목록**: 모든 에이전트는 작업 상태를 보고 사용 가능한 작업을 요청할 수 있습니다.

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

301 307

430Claude에게 팀원을 생성하도록 요청한 후 팀원이 나타나지 않으면:436Claude에게 팀원을 생성하도록 요청한 후 팀원이 나타나지 않으면:

431 437

432* In-process 모드에서, 팀원들이 프롬프트 입력 아래의 에이전트 패널에 나타납니다. 위아래 화살표 키를 사용하여 팀원을 선택한 후 Enter를 눌러 확인합니다.438* In-process 모드에서, 팀원들이 프롬프트 입력 아래의 에이전트 패널에 나타납니다. 위아래 화살표 키를 사용하여 팀원을 선택한 후 Enter를 눌러 확인합니다.

433* 유휴 상태로 앉아 있다가 사라진 팀원 행은 중지된 것이 아니라 숨겨진 것입니다. 유휴 행은 30초 후에 숨겨지며 팀원의 다음 차례에 다시 나타납니다. 팀원의 이름으로 메시지를 보내 다시 표시합니다.439* 유휴 상태로 앉아 있다가 사라진 팀원 행은 중지된 것이 아니라 숨겨진 것입니다. 유휴 행은 전체 패널이 유휴 상태가 된 후 30초 후에 숨겨지며 팀원의 다음 차례에 다시 나타납니다. 3명 이상의 팀원이 유휴 상태일 때, 초과 행들은 Enter로 확장할 수 있는 단일 `N idle agents` 행으로 축소됩니다. 팀원의 이름으로 메시지를 보내 숨겨진 행을 다시 표시합니다.

434* Claude에게 준 작업이 팀을 보증할 만큼 복잡한지 확인합니다. Claude는 작업에 따라 팀원을 생성할지 결정합니다.440* Claude에게 준 작업이 팀을 보증할 만큼 복잡한지 확인합니다. Claude는 작업에 따라 팀원을 생성할지 결정합니다.

435* 분할 창을 명시적으로 요청했으면, tmux가 설치되어 있고 PATH에서 사용 가능한지 확인합니다:441* 분할 창을 명시적으로 요청했으면, tmux가 설치되어 있고 PATH에서 사용 가능한지 확인합니다:

436 ```bash theme={null}442 ```bash theme={null}

453* 직접 추가 지시를 제공합니다459* 직접 추가 지시를 제공합니다

454* 작업을 계속하기 위해 대체 팀원을 생성합니다460* 작업을 계속하기 위해 대체 팀원을 생성합니다

455 461

462v2.1.198 기준으로, 리더 또는 다른 팀원의 메시지는 실패한 API 요청을 재시도하기 위해 대기 중인 in-process 팀원을 깨우므로, 전체 재시도 지연을 기다리지 않고 즉시 재시도합니다.

463

456<h3 id="lead-shuts-down-before-work-is-done">464<h3 id="lead-shuts-down-before-work-is-done">

457 리더가 작업 완료 전에 종료됨465 리더가 작업 완료 전에 종료됨

458</h3>466</h3>

481* **종료가 느릴 수 있음**: 팀원들은 현재 요청이나 도구 호출을 마친 후 종료되어 시간이 걸릴 수 있습니다.489* **종료가 느릴 수 있음**: 팀원들은 현재 요청이나 도구 호출을 마친 후 종료되어 시간이 걸릴 수 있습니다.

482* **세션당 한 팀**: 세션은 정확히 하나의 팀을 가지며, 해당 세션으로 범위가 지정됩니다. 추가 명명된 팀을 만들거나 세션 간에 팀을 공유할 수 없습니다.490* **세션당 한 팀**: 세션은 정확히 하나의 팀을 가지며, 해당 세션으로 범위가 지정됩니다. 추가 명명된 팀을 만들거나 세션 간에 팀을 공유할 수 없습니다.

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

492* **In-process 팀원의 백그라운드 서브에이전트 없음**: in-process 팀원의 자체 서브에이전트는 포그라운드에서 실행됩니다. `run_in_background`를 사용하거나 `background: true`를 설정하는 서브에이전트 정의로 백그라운드 서브에이전트를 요청하면 오류가 반환됩니다. 팀원의 백그라운드 작업은 리더의 프로세스보다 오래 지속될 수 없기 때문입니다. 주 대화에서 시작된 서브에이전트는 [백그라운드 기본값](/ko/sub-agents#run-subagents-in-foreground-or-background)을 따릅니다.

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

485* **생성 시 권한 설정**: 모든 팀원은 리더의 권한 모드로 시작합니다. 생성 후 개별 팀원 모드를 변경할 수 있지만, 생성 시 팀원별 모드를 설정할 수 없습니다.494* **생성 시 권한 설정**: 모든 팀원은 리더의 권한 모드로 시작합니다. 생성 후 개별 팀원 모드를 변경할 수 있지만, 생성 시 팀원별 모드를 설정할 수 없습니다.

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

agent-view.md +68 −13

Details

27* [빠른 시작](#quick-start): Claude에게 백그라운드에서 작업할 작업을 제공하고, 확인하고, 필요할 때 개입합니다27* [빠른 시작](#quick-start): Claude에게 백그라운드에서 작업할 작업을 제공하고, 확인하고, 필요할 때 개입합니다

28* [에이전트 뷰로 세션 모니터링](#monitor-sessions-with-agent-view), 상태 아이콘, 엿보기 및 답변, 연결, 구성 및 키보드 단축키 포함28* [에이전트 뷰로 세션 모니터링](#monitor-sessions-with-agent-view), 상태 아이콘, 엿보기 및 답변, 연결, 구성 및 키보드 단축키 포함

29* [에이전트 뷰에서 새로운 에이전트 디스패치](#dispatch-new-agents), 세션 내에서, 또는 셸에서29* [에이전트 뷰에서 새로운 에이전트 디스패치](#dispatch-new-agents), 세션 내에서, 또는 셸에서

~~30* [셸에서 세션 관리](#manage-sessions-from-the-shell)~~30* [셸에서 세션 관리](#manage-sessions-from-the-shell) `claude agents`, `claude attach` 및 관련 명령어 사용

31* [백그라운드 세션이 호스팅되는 방식](#how-background-sessions-are-hosted), 감독자 프로세스에 의해31* [백그라운드 세션이 호스팅되는 방식](#how-background-sessions-are-hosted), 감독자 프로세스에 의해

32 32

33<h2 id="quick-start">33<h2 id="quick-start">

64 </Step>64 </Step>

65 65

66 <Step title="기존 세션 가져오기">66 <Step title="기존 세션 가져오기">

67 이미 열려 있는 세션을 에이전트 뷰로 이동하려면 세션 내에서 `/bg`를 실행하거나, 빈 프롬프트에서 `←`를 눌러 세션을 백그라운드로 보내고 한 단계에서 에이전트 뷰를 엽니다. 세션은 계속 실행되며 디스패치한 세션과 함께 행으로 나타납니다.67 이 단계에는 실행 중인 세션이 필요합니다. 이전 단계를 따랐다면 이 터미널에서 열려 있는 세션이 없으므로, 다른 터미널에서 일반 `claude` 세션을 열고 먼저 메시지를 보냅니다. 이미 열려 있는 세션을 에이전트 뷰로 이동하려면 세션 내에서 `/bg`를 실행하거나, 빈 프롬프트에서 `←`를 눌러 세션을 백그라운드로 보내고 한 단계에서 에이전트 뷰를 엽니다. 세션은 계속 실행되며 디스패치한 세션과 함께 행으로 나타납니다.

68 </Step>68 </Step>

69</Steps>69</Steps>

70 70

76 76

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

78 78

79이름은 해당 세션에서 [`/color`](/ko/commands)로 설정된 색상으로 표시됩니다. {/* min-version: 2.1.199 */}v2.1.199부터 색상은 `←` 또는 `/background`로 [세션을 백그라운드로 보낼](#from-inside-a-session) 때 유지됩니다.

79기본적으로 목록은 모든 프로젝트에 걸쳐 시작한 모든 백그라운드 세션을 표시합니다. 한 저장소에서 작업하는 세션과 다른 worktree에서 작업하는 세션은 모두 여기에 나타나며, 에이전트 뷰를 연 디렉토리와 관계없이 표시됩니다. 목록을 한 프로젝트로 범위를 지정하려면 `--cwd`를 전달합니다:81기본적으로 목록은 모든 프로젝트에 걸쳐 시작한 모든 백그라운드 세션을 표시합니다. 한 저장소에서 작업하는 세션과 다른 worktree에서 작업하는 세션은 모두 여기에 나타나며, 에이전트 뷰를 연 디렉토리와 관계없이 표시됩니다. 목록을 한 프로젝트로 범위를 지정하려면 `--cwd`를 전달합니다:

80 82

81```bash theme={null}83```bash theme={null}

91 ✽ clawd walk cycle Write assets/sprites/clawd-walk.png 3m93 ✽ clawd walk cycle Write assets/sprites/clawd-walk.png 3m

92 94

93검토 준비 완료95검토 준비 완료

~~94 ∙ jump physics Opened PR with collision fix PR #2048 2h~~96 ∙ jump physics Opened PR with collision fix #2048 2h

95 97

96입력 필요98입력 필요

97 ✻ power-up design needs input: double jump or wall climb? 1m99 ✻ power-up design needs input: double jump or wall climb? 1m

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

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

131 133

132행의 오른쪽 가장자리에 나타날 수 있는 `PR #N` 레이블은 [세션이 열은 풀 리퀘스트](#pull-request-status)이며, 상태 아이콘의 일부가 아닙니다. 세션이 둘 이상의 풀 리퀘스트를 열었을 때 레이블은 `3 PRs`와 같은 개수를 표시합니다.134행의 오른쪽 가장자리에 나타날 수 있는 `#N` 레이블은 [세션이 열은 풀 리퀘스트](#pull-request-status)이며, 상태 아이콘의 일부가 아닙니다.

133 135

134터미널 탭 제목은 에이전트 뷰가 열려 있는 동안 입력 대기 중인 개수를 표시합니다: 세션이 입력이 필요할 때 `2 awaiting input · claude agents`, 필요하지 않을 때 `claude agents`.136터미널 탭 제목은 에이전트 뷰가 열려 있는 동안 입력 대기 중인 개수를 표시합니다: 세션이 입력이 필요할 때 `2 awaiting input · claude agents`, 필요하지 않을 때 `claude agents`.

135 137

138v2.1.198부터 에이전트 뷰가 열려 있는 동안 Claude Code는 로컬 백그라운드 세션이 입력이 필요하거나, 완료되거나, 실패할 때 구성된 [터미널 알림 채널](/ko/terminal-config#get-a-terminal-bell-or-notification)을 통해 알림을 보냅니다. [`/loop`](/ko/scheduled-tasks) 세션과 같이 일정에 따라 실행되는 세션은 입력이 필요할 때만 알립니다. 알림은 Claude Code의 나머지 부분과 동일한 [`preferredNotifChannel` 설정](/ko/settings#available-settings)을 사용하며 `agent_needs_input` 또는 `agent_completed` 유형으로 [`Notification` 훅](/ko/hooks#notification)을 실행합니다.

139

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

137 141

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

151 풀 리퀘스트 상태155 풀 리퀘스트 상태

152</h3>156</h3>

153 157

154세션이 풀 리퀘스트를 열면 `PR #1234` 레이블이 행의 오른쪽 가장자리에 나타나며, 하이퍼링크를 지원하는 터미널에서 풀 리퀘스트에 연결됩니다. 세션에 후속 조치를 보낼 때 레이블이 유지되므로 행이 라이브 진행 상황으로 되돌아가는 동안 풀 리퀘스트가 표시된 상태로 유지됩니다.158세션이 풀 리퀘스트를 열면 `#1234` 레이블이 행의 오른쪽 가장자리에 나타나며, 하이퍼링크를 지원하는 터미널에서 풀 리퀘스트에 연결됩니다. 세션에 후속 조치를 보낼 때 레이블이 유지되므로 행이 라이브 진행 상황으로 되돌아가는 동안 풀 리퀘스트가 표시된 상태로 유지됩니다. 백그라운드 세션이 worktree에서 변경 사항을 격리하면 이러한 풀 리퀘스트를 직접 열며, [파일 편집이 격리되는 방식](#how-file-edits-are-isolated)은 이것이 발생하는 시기와 세션이 요청 없이 절대 수행하지 않는 작업을 다룹니다.

155 159

156세션이 둘 이상의 풀 리퀘스트를 열었을 때 레이블은 `3 PRs`와 같은 개수를 표시하며, 가장 주의가 필요한 열린 풀 리퀘스트로 색상이 지정됩니다. [엿보기 패널](#peek-and-reply)을 열어 모두 확인합니다.160세션이 둘 이상의 풀 리퀘스트를 열었을 때 레이블은 `3 PRs`와 같은 개수를 표시하며, 가장 주의가 필요한 열린 풀 리퀘스트로 색상이 지정됩니다. [엿보기 패널](#peek-and-reply)을 열어 모두 확인합니다.

157 161

190 194

191연결된 세션은 `tui` 설정과 관계없이 항상 [전체 화면 모드](/ko/fullscreen)로 렌더링됩니다. 백그라운드 세션에는 추가할 터미널 스크롤백이 없기 때문입니다. `PgUp`, `PgDn` 또는 마우스 휠로 스크롤하고, `Ctrl+O`를 눌러 트랜스크립트 모드로 전환합니다. 터미널의 기본 스크롤 및 tmux 복사 모드는 현재 뷰포트만 표시하며, 이는 전체 화면 애플리케이션을 실행할 때와 동일합니다.195연결된 세션은 `tui` 설정과 관계없이 항상 [전체 화면 모드](/ko/fullscreen)로 렌더링됩니다. 백그라운드 세션에는 추가할 터미널 스크롤백이 없기 때문입니다. `PgUp`, `PgDn` 또는 마우스 휠로 스크롤하고, `Ctrl+O`를 눌러 트랜스크립트 모드로 전환합니다. 터미널의 기본 스크롤 및 tmux 복사 모드는 현재 뷰포트만 표시하며, 이는 전체 화면 애플리케이션을 실행할 때와 동일합니다.

192 196

193빈 프롬프트에서 `←`를 눌러 분리하고 에이전트 뷰로 돌아갑니다. 대화 상자가 포커스를 가지고 있고 `←`에 응답하지 않으면 `Ctrl+Z`를 눌러 즉시 분리합니다.197빈 프롬프트에서 `←`를 누르거나 `/exit`를 실행하여 분리하고 에이전트 뷰로 돌아갑니다. v2.1.198부터 이는 에이전트 뷰에서 세션을 열었는지 또는 셸에서 `claude attach <id>`로 실행했는지 여부와 관계없이 동일하게 작동합니다.

198

199`Ctrl+Z`도 분리하지만 시작한 위치로 돌아갑니다: 에이전트 뷰에서 연결한 경우 에이전트 뷰, 또는 `claude attach`를 실행한 경우 셸입니다. 대화 상자가 포커스를 가지고 있고 `←`에 응답하지 않을 때 `Ctrl+Z`를 사용합니다.

194 200

195`Ctrl+C`는 연결된 동안 표준 인터럽트 동작을 유지합니다: 분리하는 대신 실행 중인 응답 또는 `!` 셸 명령을 취소합니다. 빈 프롬프트에서 `Ctrl+C`를 두 번 누르면 분리되며, 다른 세션에서와 동일합니다.201`Ctrl+C`는 연결된 동안 표준 인터럽트 동작을 유지합니다: 분리하는 대신 실행 중인 응답 또는 `!` 셸 명령을 취소합니다. 빈 프롬프트에서 `Ctrl+C`를 두 번 누르면 분리되며, 다른 세션에서와 동일합니다.

196 202

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

198 204

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

206

207도구가 실행 중일 때 `←`를 누르면 Claude Code는 완료될 때까지 약 10초를 기다린 후 백그라운드로 보내며, 응답은 백그라운드 세션에서 계속됩니다. 대신 즉시 백그라운드로 보내려면 `←`를 다시 누릅니다. 진행 중인 작업을 백그라운드 세션으로 이월할 수 없으면 `Background this session?` 대화가 먼저 나타나며, [`/background`](#from-inside-a-session)와 동일합니다.

208

209행은 대화 기록이 없는 새로운 세션에서도 생성되므로 `→`는 이를 반환합니다. 해당 행이 유일한 경우 에이전트 뷰는 아래에 온보딩 힌트를 표시합니다.

210

211`/config`에서 `leftArrowOpensAgents` 설정으로 이 단축키를 끌 수 있습니다.

200 212

201<h3 id="organize-the-list">213<h3 id="organize-the-list">

202 목록 구성214 목록 구성

217 229

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

219 231

220오래된 완료된 세션은 목록을 짧게 유지하기 위해 `… N more` 행으로 접힙니다. 실패 및 열린 풀 리퀘스트가 있는 세션은 항상 표시됩니다. `완료됨` 그룹은 라이브 그룹 이후 남은 수직 공간을 채우며, 짧은 터미널에서 헤더는 단일 요약 라인으로 압축되므로 작업 중이거나 입력이 필요한 세션이 표시된 상태로 유지됩니다.232화면에 맞지 않는 완료된 세션은 `… N more` 행으로 접힙니다. 실패 및 열린 풀 리퀘스트가 있는 세션은 항상 표시됩니다. `완료됨` 그룹은 라이브 그룹 이후 남은 수직 공간을 채우며, 짧은 터미널에서 헤더는 단일 요약 라인으로 압축되므로 작업 중이거나 입력이 필요한 세션이 표시된 상태로 유지됩니다.

221 233

222<h3 id="filter-sessions">234<h3 id="filter-sessions">

223 세션 필터링235 세션 필터링

285 297

286에이전트 뷰 자체에서만 실행되는 작은 명령 집합이 있습니다: `/exit` 및 `/quit`는 에이전트 뷰를 닫고, `/logout`은 로그아웃하며, `/model`은 [디스패치 모델](#set-the-model)을 설정합니다. 스킬, 사용자 정의 명령 및 `/init`과 같은 프롬프트 확장 기본 제공 명령은 새로운 백그라운드 세션으로 첫 번째 프롬프트로 전송됩니다. 다른 기본 제공 명령은 대신 `세션에 연결하여 실행` 힌트를 표시합니다.298에이전트 뷰 자체에서만 실행되는 작은 명령 집합이 있습니다:

299

300* `/exit` 및 `/quit`는 에이전트 뷰를 닫습니다

301* `/logout`은 로그아웃합니다

302* `/model`은 [디스패치 모델](#set-the-model)을 설정합니다

303* {/* min-version: 2.1.198 */}v2.1.198부터 `/login`은 세션에 연결하지 않고 다시 로그인할 수 있도록 로그인 대화 상자를 엽니다

304

305스킬, 사용자 정의 명령 및 `/init`과 같은 프롬프트 확장 기본 제공 명령은 새로운 백그라운드 세션으로 첫 번째 프롬프트로 전송됩니다. 다른 기본 제공 명령은 대신 `세션에 연결하여 실행` 힌트를 표시합니다.

287 306

288반복되는 작업을 [스킬](/ko/skills)로 패키징하면 프롬프트를 다시 입력하지 않고 에이전트 뷰에서 동일한 워크플로우를 여러 번 시작할 수 있습니다.307반복되는 작업을 [스킬](/ko/skills)로 패키징하면 프롬프트를 다시 입력하지 않고 에이전트 뷰에서 동일한 워크플로우를 여러 번 시작할 수 있습니다.

289 308

307 326

308`/background` 또는 별칭 `/bg`를 실행하여 현재 대화를 백그라운드 세션으로 이동합니다. `/bg run the test suite and fix any failures`와 같은 프롬프트를 전달하여 먼저 하나의 추가 명령을 보냅니다. Claude가 응답 중일 때 `/bg`를 실행하면 응답이 백그라운드 세션에서 계속됩니다.327`/background` 또는 별칭 `/bg`를 실행하여 현재 대화를 백그라운드 세션으로 이동합니다. `/bg run the test suite and fix any failures`와 같은 프롬프트를 전달하여 먼저 하나의 추가 명령을 보냅니다. Claude가 응답 중일 때 `/bg`를 실행하면 응답이 백그라운드 세션에서 계속됩니다.

309 328

329백그라운드 작업이 실행 중인 대화형 세션(예: 서브에이전트, 백그라운드 셸 명령, 워크플로우 또는 [모니터](/ko/tools-reference#monitor-tool))을 종료하면 즉시 종료되지 않고 `Background work is running` 대화 상자가 표시됩니다. {/* min-version: 2.1.198 */}v2.1.198부터 대화 상자는 `Exit anyway` 및 `Stay`와 함께 `Move to background and exit`를 제공합니다. 이를 선택하면 `/background`와 동일한 방식으로 세션을 백그라운드로 이동한 다음 셸로 돌아가므로 계속할 수 있는 작업이 계속 실행되고 세션이 에이전트 뷰에 나타납니다. 에이전트 뷰가 [꺼져](#turn-off-agent-view) 있을 때는 이 옵션이 표시되지 않습니다.

330

310대화형 세션에서 백그라운드로 이동하면 저장된 대화에서 재개되는 새로운 프로세스가 시작되며, 진행 중인 작업이 이동됩니다: 실행 중인 백그라운드 셸 명령, 백그라운드 서브에이전트, 동적 워크플로우 및 [`/loop`](/ko/scheduled-tasks)로 생성한 예약된 작업이 백그라운드 세션으로 이동하고 계속 실행됩니다. 서브에이전트는 시작한 모든 것과 함께 이동하므로 Windows를 포함한 모든 작업이 이동할 수 있을 때만 이동합니다. 진행 중인 작업을 이동하는 대신 중지하려면 [`CLAUDE_DISABLE_ADOPT=1`](/ko/env-vars#variables) 환경 변수를 설정합니다. Claude Code는 백그라운드로 이동하기 전에 확인을 요청합니다.331대화형 세션에서 백그라운드로 이동하면 저장된 대화에서 재개되는 새로운 프로세스가 시작되며, 진행 중인 작업이 이동됩니다: 실행 중인 백그라운드 셸 명령, 백그라운드 서브에이전트, 동적 워크플로우 및 [`/loop`](/ko/scheduled-tasks)로 생성한 예약된 작업이 백그라운드 세션으로 이동하고 계속 실행됩니다. 서브에이전트는 시작한 모든 것과 함께 이동하므로 Windows를 포함한 모든 작업이 이동할 수 있을 때만 이동합니다. 진행 중인 작업을 이동하는 대신 중지하려면 [`CLAUDE_DISABLE_ADOPT=1`](/ko/env-vars#variables) 환경 변수를 설정합니다. Claude Code는 백그라운드로 이동하기 전에 확인을 요청합니다.

311 332

312이동할 수 없는 작업(예: 실행 중인 [모니터](/ko/tools-reference#monitor-tool))은 중지됩니다. 모니터를 소유한 백그라운드 서브에이전트는 함께 중지됩니다. 이러한 작업이 실행 중일 때 Claude Code는 `Background this session?` 대화 상자를 표시하므로 중지되기 전에 확인할 수 있습니다.333이동할 수 없는 작업(예: 실행 중인 [모니터](/ko/tools-reference#monitor-tool))은 중지됩니다. 모니터를 소유한 백그라운드 서브에이전트는 함께 중지됩니다. 이러한 작업이 실행 중일 때 Claude Code는 `Background this session?` 대화 상자를 표시하므로 중지되기 전에 확인할 수 있습니다.

336claude --bg "investigate the flaky SettingsChangeDetector test"357claude --bg "investigate the flaky SettingsChangeDetector test"

337```358```

338 359

360프롬프트는 위치 인수이며 `-p` 값이 아닙니다. {/* min-version: 2.1.198 */}v2.1.198부터 `--bg`를 `-p` 또는 `--print`와 결합하면 세션이 생성되기 전에 오류로 거부됩니다. `--print`는 `claude agents`가 연결하는 대화형 세션을 시작하지 않기 때문입니다.

361

339특정 서브에이전트를 세션의 주 에이전트로 실행하려면 `--bg`를 `--agent`와 결합합니다:362특정 서브에이전트를 세션의 주 에이전트로 실행하려면 `--bg`를 `--agent`와 결합합니다:

340 363

341```bash theme={null}364```bash theme={null}

348claude --bg --name "flaky-test-fix" "investigate the flaky SettingsChangeDetector test"371claude --bg --name "flaky-test-fix" "investigate the flaky SettingsChangeDetector test"

349```372```

350 373

351백그라운드로 보낸 후 Claude는 세션의 짧은 ID와 관리 명령을 인쇄합니다. `--name`을 전달하면 짧은 ID 뒤에 이름이 나타납니다:374백그라운드로 보낸 후 Claude는 세션의 짧은 ID와 관리 명령을 인쇄합니다. 백그라운드 세션을 호스팅하는 서비스가 아직 실행 중이 아닐 때 `--bg`는 이 출력 위에 `Starting background service…`를 먼저 인쇄할 수 있습니다. `--name`을 전달하면 짧은 ID 뒤에 이름이 나타납니다:

352 375

353```text theme={null}376```text theme={null}

354backgrounded · 7c5dcf5d · flaky-test-fix377backgrounded · 7c5dcf5d · flaky-test-fix

408 431

409백그라운드 세션이 생성하는 [서브에이전트](/ko/sub-agents)는 세션의 작업 디렉토리를 상속하므로 파일 편집은 세션의 worktree가 아닌 작업 복사본에 저장됩니다. 서브에이전트에 자신의 별도 worktree를 제공하려면 프론트매터에서 [`isolation: worktree`](/ko/sub-agents#supported-frontmatter-fields)를 설정하거나 생성할 때 `isolation: "worktree"`를 전달합니다.432백그라운드 세션이 생성하는 [서브에이전트](/ko/sub-agents)는 세션의 작업 디렉토리를 상속하므로 파일 편집은 세션의 worktree가 아닌 작업 복사본에 저장됩니다. 서브에이전트에 자신의 별도 worktree를 제공하려면 프론트매터에서 [`isolation: worktree`](/ko/sub-agents#supported-frontmatter-fields)를 설정하거나 생성할 때 `isolation: "worktree"`를 전달합니다.

410 433

434v2.1.198부터 worktree에서 코드 변경을 격리한 백그라운드 세션은 또한 커밋하고, 자신의 브랜치를 푸시하고, 멈추지 않고 초안 풀 리퀘스트를 엽니다. [`#N` 레이블](#pull-request-status)은 풀 리퀘스트가 열릴 때 행에 나타납니다. `main` 또는 `master`로 푸시하지 않으며, 강제 푸시하거나 병합하지 않으며, 풀 리퀘스트를 열지 말도록 지시했거나 저장소에 원격이 없을 때 풀 리퀘스트를 건너뜁니다.

435

436격리하지 않은 체크아웃을 편집하는 세션은 여전히 커밋하거나 브랜치를 전환하기 전에 묻습니다. 이는 격리가 `"none"`으로 설정되었을 때, worktree 이동이 실패했을 때 또는 세션이 이미 존재하는 worktree 내부에서 시작되었을 때 적용됩니다.

437

411<h3 id="set-the-model">438<h3 id="set-the-model">

412 모델 설정439 모델 설정

413</h3>440</h3>

523 550

524세션이 완료되고 약 1시간 동안 연결되지 않은 상태로 있으면 감독자는 리소스를 확보하기 위해 프로세스를 중지합니다. `Ctrl+T`로 [고정](#organize-the-list)한 세션은 예외이며 유휴 상태에서도 프로세스를 실행 상태로 유지합니다. 트랜스크립트와 상태는 어느 쪽이든 디스크에 유지되며, 다음에 연결하거나, 엿보거나, 중지된 세션에 답변할 때 감독자는 중단된 위치에서 새로운 프로세스를 시작합니다. 모든 세션이 완료되고 터미널이 연결되지 않으면 감독자 자체가 종료되고 다음에 필요할 때 다시 시작됩니다.551세션이 완료되고 약 1시간 동안 연결되지 않은 상태로 있으면 감독자는 리소스를 확보하기 위해 프로세스를 중지합니다. `Ctrl+T`로 [고정](#organize-the-list)한 세션은 예외이며 유휴 상태에서도 프로세스를 실행 상태로 유지합니다. 트랜스크립트와 상태는 어느 쪽이든 디스크에 유지되며, 다음에 연결하거나, 엿보거나, 중지된 세션에 답변할 때 감독자는 중단된 위치에서 새로운 프로세스를 시작합니다. 모든 세션이 완료되고 터미널이 연결되지 않으면 감독자 자체가 종료되고 다음에 필요할 때 다시 시작됩니다.

525 552

526백그라운드 셸 명령 및 동적 워크플로우는 세션의 프로세스가 중지되거나, 다시 시작되거나, Windows를 포함한 업데이트될 때 계속 실행됩니다. 해당 세션을 위해 시작된 다음 프로세스는 이들을 다시 선택하고, 그 사이에 완료된 셸 명령은 출력과 함께 완료된 것으로 보고되며, 워크플로우는 중단된 위치에서 재개됩니다. 서브에이전트가 시작한 셸 명령 및 실행 중인 [모니터](/ko/tools-reference#monitor-tool)는 여전히 프로세스와 함께 중지되며, 세션을 삭제하면 모든 것이 중지됩니다. 백그라운드 셸 명령 및 워크플로우를 프로세스와 함께 중지하려면 [`CLAUDE_CODE_DISABLE_BG_EXIT_HANDOFF`](/ko/env-vars#variables) 환경 변수를 `1`로 설정합니다.553세션이 최상위 수준에서 시작한 백그라운드 작업은 프로세스가 중지되거나, 다시 시작되거나, Windows를 포함한 업데이트될 때 인계됩니다. 해당 세션을 위해 시작된 다음 프로세스는 작업을 다시 선택합니다:

554

555* 그 사이에 완료된 백그라운드 셸 명령은 출력과 함께 완료된 것으로 보고됩니다

556* 동적 워크플로우는 중단된 위치에서 재개됩니다

557* [백그라운드 서브에이전트](/ko/sub-agents#run-subagents-in-foreground-or-background)는 자체 트랜스크립트에서 재개됩니다

558

559{/* min-version: 2.1.198 */}v2.1.198부터 인계는 세 가지 모두를 포함합니다. v2.1.198 이전에는 셸 명령과 워크플로우만 포함했으므로 백그라운드 서브에이전트는 프로세스와 함께 중지되었고 다음 깨어날 때 실패한 것으로 보고되었습니다.

560

561상태가 프로세스 자체 내에만 있는 작업은 인계되지 않고 프로세스와 함께 중지됩니다. 이는 서브에이전트가 시작한 셸 명령(재개된 서브에이전트가 다시 시작할 수 있음)과 실행 중인 [모니터](/ko/tools-reference#monitor-tool)(이벤트 스트림을 다른 프로세스로 이동할 수 없음)입니다.

562

563세션을 삭제하면 인계된 모든 것이 중지됩니다. 세션의 모든 백그라운드 작업을 인계 대신 프로세스와 함께 중지하려면 [`CLAUDE_CODE_DISABLE_BG_EXIT_HANDOFF`](/ko/env-vars#variables) 환경 변수를 `1`로 설정합니다.

527 564

528다시 시작된 세션이 트랜스크립트를 비어 있는 것으로 잘못 읽었기 때문에 원본 프롬프트만 표시되면서 돌아오면, 대화 트랜스크립트는 삭제되는 대신 `.orphaned-` 접두사로 이름이 바뀌므로 머신에 남아 있습니다.565다시 시작된 세션이 트랜스크립트를 비어 있는 것으로 잘못 읽었기 때문에 원본 프롬프트만 표시되면서 돌아오면, 대화 트랜스크립트는 삭제되는 대신 `.orphaned-` 접두사로 이름이 바뀌므로 머신에 남아 있습니다.

529 566

600 637

601절전 상태만으로는 이 문제가 발생하지 않습니다. 세션은 절전 상태에서 보존되며 감독자는 깨어날 때 이들에 다시 연결됩니다.638절전 상태만으로는 이 문제가 발생하지 않습니다. 세션은 절전 상태에서 보존되며 감독자는 깨어날 때 이들에 다시 연결됩니다.

602 639

640<h3 id="a-session-fails-before-starting-with-a-possibly-low-memory-note">

641 세션이 시작되기 전에 `possibly low memory` 메모와 함께 실패함

642</h3>

643

644v2.1.199부터 백그라운드 세션의 프로세스가 시작을 완료하기 전에 종료되고 호스트의 메모리가 부족하면, 행의 상태는 종료를 이름 지정하고 `possibly low memory — free some up and retry`를 추가합니다. 이전 버전은 이 실패에 대해 기본 종료 이유만 표시했습니다.

645

646메모는 가설이지 확인된 원인이 아닙니다. Claude Code는 프로세스가 오류를 작성하지 않고 신호로 중지되지 않고 자동으로 종료되었으며 호스트가 그 순간 메모리 부족을 보고한 경우에만 추가합니다. 프로세스가 종료되기 전에 오류를 작성한 경우, 행은 대신 해당 오류를 표시합니다.

647

648머신의 메모리를 확보한 후 행에 연결하거나, 엿보거나, 답변하면 감독자가 세션을 위한 새로운 프로세스를 시작합니다. 메모리가 계속 부족하면 감독자는 [유휴 세션을 중지](#the-supervisor-process)하여 자체적으로 리소스를 확보합니다.

649

603<h3 id="agent-view-says-the-background-service-did-not-respond">650<h3 id="agent-view-says-the-background-service-did-not-respond">

604 에이전트 뷰에서 백그라운드 서비스가 응답하지 않음651 에이전트 뷰에서 백그라운드 서비스가 응답하지 않음

605</h3>652</h3>

630 677

631원인 및 해결 방법의 전체 목록은 [오류 참조](/ko/errors#could-not-resolve-authentication-method)를 참조합니다.678원인 및 해결 방법의 전체 목록은 [오류 참조](/ko/errors#could-not-resolve-authentication-method)를 참조합니다.

632 679

633<h3 id="background-sessions-cannot-read-desktop-documents-or-downloads-on-macos">680<h3 id="background-sessions-can’t-read-desktop-documents-or-downloads-on-macos">

634 macOS에서 백그라운드 세션이 Desktop, Documents 또는 Downloads를 읽을 수 없음681 macOS에서 백그라운드 세션이 Desktop, Documents 또는 Downloads를 읽을 수 없음

635</h3>682</h3>

636 683

638 685

639기본 설치 프로그램을 사용하면 항목이 Claude Code로 표시되고 권한이 업데이트 전체에서 유지됩니다. Homebrew 또는 npm과 같은 다른 설치 방법을 사용하면 항목이 바이너리 경로를 표시하며 업데이트 후 다시 권한을 부여해야 할 수 있습니다.686기본 설치 프로그램을 사용하면 항목이 Claude Code로 표시되고 권한이 업데이트 전체에서 유지됩니다. Homebrew 또는 npm과 같은 다른 설치 방법을 사용하면 항목이 바이너리 경로를 표시하며 업데이트 후 다시 권한을 부여해야 할 수 있습니다.

640 687

688<h3 id="background-sessions-can’t-reach-local-network-hosts-on-macos">

689 macOS에서 백그라운드 세션이 로컬 네트워크 호스트에 도달할 수 없음

690</h3>

691

692macOS 15 이상에서 시스템은 로컬 네트워크 권한을 부여할 때까지 프로세스가 로컬 네트워크의 장치에 도달하는 것을 차단합니다. v2.1.198 이전에는 백그라운드 세션 호스트가 해당 권한을 요청하지 않았으므로, LAN 주소를 대상으로 하는 명령은 포그라운드 터미널에서 동일한 명령이 작동했음에도 불구하고 `connect: no route to host`로 실패했습니다. {/* min-version: 2.1.198 */}v2.1.198부터 백그라운드 세션의 첫 번째 명령이 로컬 네트워크 주소에 연결되면 Claude Code에 대한 macOS 로컬 네트워크 권한 프롬프트를 트리거합니다. 한 번 부여하면 이러한 명령은 포그라운드 터미널에서와 동일한 방식으로 LAN 호스트에 도달합니다.

693

641<h3 id="a-session-is-slow-to-respond-after-attaching">694<h3 id="a-session-is-slow-to-respond-after-attaching">

642 연결 후 세션이 응답이 느림695 연결 후 세션이 응답이 느림

643</h3>696</h3>

677에이전트 뷰는 연구 미리보기 중에 빠르게 발전했습니다. 이전 Claude Code 버전을 사용 중인 경우 이 페이지의 일부 동작이 다를 수 있습니다. 특히 `claude agents`는 아직 지원하지 않는 플래그를 `unknown option` 오류로 거부합니다. 아래 표는 각 플래그와 동작이 추가된 시기를 나열합니다.730에이전트 뷰는 연구 미리보기 중에 빠르게 발전했습니다. 이전 Claude Code 버전을 사용 중인 경우 이 페이지의 일부 동작이 다를 수 있습니다. 특히 `claude agents`는 아직 지원하지 않는 플래그를 `unknown option` 오류로 거부합니다. 아래 표는 각 플래그와 동작이 추가된 시기를 나열합니다.

678 731

679| 버전 | 변경 사항 |732| 버전 | 변경 사항 |

680| -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |733| -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

734| v2.1.199 | {/* min-version: 2.1.199 */}메모리 부족 호스트에서 시작을 완료하기 전에 프로세스가 종료되는 백그라운드 세션은 단순히 종료 이유만 표시하는 대신 행 상태에 `possibly low memory — free some up and retry`를 표시합니다. `←` 또는 `/background`로 세션을 백그라운드로 이동하면 `/color`를 새 행으로 이동합니다. |

735| v2.1.198 | {/* min-version: 2.1.198 */}에이전트 뷰는 백그라운드 세션이 입력이 필요하거나, 완료되거나, 실패할 때 `preferredNotifChannel`을 통해 알림을 보내고 `agent_needs_input` 또는 `agent_completed` 유형으로 `Notification` 훅을 실행합니다. `claude attach <id>` 내의 `←` 및 `/exit`는 셸로 종료하는 대신 에이전트 뷰로 돌아갑니다. `Ctrl+Z`는 셸로 돌아갑니다. 백그라운드 세션이 작업을 워크트리에 격리하면 자신의 격리된 분기를 커밋하고 푸시하며, `main` 또는 `master`를 사용하지 않고, 완료될 때 먼저 묻는 대신 초안 풀 요청을 엽니다. `/login`은 에이전트 뷰에서 실행되고 로그인 대화를 엽니다. `Background work is running` 종료 대화는 `Move to background and exit`를 제공합니다. 종료 핸드오프는 백그라운드 서브에이전트도 포함하며, 이들은 실패로 보고되는 대신 다음 깨어날 때 트랜스크립트에서 재개됩니다. `claude --bg`는 `-p` 또는 `--print`와 결합되면 오류로 거부됩니다. |

681| v2.1.196 | {/* min-version: 2.1.196 */}단일 `←` 누름이 포그라운드 세션을 백그라운드로 이동합니다. 이전 버전은 바닥글 힌트와 확인이 있는 두 번의 누름이 필요했습니다. `claude agents`에 전달된 `--dangerously-skip-permissions`는 자동으로 삭제되는 대신 면책 조항을 표시합니다. 이름을 지정하지 않은 대화형 세션은 세션 목록 및 `claude agents --json`에서 `my-app-3f`와 같은 기본 이름을 가집니다. 백그라운드 셸 명령 및 동적 워크플로우는 세션의 프로세스가 중지되거나, 다시 시작되거나, Windows를 포함한 업데이트될 때 생존합니다. `CLAUDE_CODE_DISABLE_BG_EXIT_HANDOFF=1`을 설정하여 핸드오프를 끕니다. 다시 시작 시 비어 있는 것으로 잘못 읽은 트랜스크립트는 삭제되는 대신 `.orphaned-` 접두사로 이름이 바뀝니다. |736| v2.1.196 | {/* min-version: 2.1.196 */}단일 `←` 누름이 포그라운드 세션을 백그라운드로 이동합니다. 이전 버전은 바닥글 힌트와 확인이 있는 두 번의 누름이 필요했습니다. `claude agents`에 전달된 `--dangerously-skip-permissions`는 자동으로 삭제되는 대신 면책 조항을 표시합니다. 이름을 지정하지 않은 대화형 세션은 세션 목록 및 `claude agents --json`에서 `my-app-3f`와 같은 기본 이름을 가집니다. 백그라운드 셸 명령 및 동적 워크플로우는 세션의 프로세스가 중지되거나, 다시 시작되거나, Windows를 포함한 업데이트될 때 생존합니다. `CLAUDE_CODE_DISABLE_BG_EXIT_HANDOFF=1`을 설정하여 핸드오프를 끕니다. 다시 시작 시 비어 있는 것으로 잘못 읽은 트랜스크립트는 삭제되는 대신 `.orphaned-` 접두사로 이름이 바뀝니다. |

682| v2.1.195 | {/* min-version: 2.1.195 */}Windows에서도 백그라운드 세션으로 이동할 때 진행 중인 작업이 이동합니다. `CLAUDE_DISABLE_ADOPT=1`을 설정하여 대신 중지합니다. `완료됨` 그룹은 남은 수직 공간을 채우고 짧은 터미널에서 헤더가 압축됩니다. 이전 Claude Code 버전은 더 이상 최신 세션의 `state.json` 필드를 삭제하거나 해당 세션을 `claude agents`에서 숨기지 않습니다. 중지된 세션에 연결하면 최대 5초 동안 빈 화면을 표시하는 대신 즉시 전환됩니다. 연결을 수락할 수 없는 감독자는 자체적으로 종료되고 잠금을 해제합니다. |737| v2.1.195 | {/* min-version: 2.1.195 */}Windows에서도 백그라운드 세션으로 이동할 때 진행 중인 작업이 이동합니다. `CLAUDE_DISABLE_ADOPT=1`을 설정하여 대신 중지합니다. `완료됨` 그룹은 남은 수직 공간을 채우고 짧은 터미널에서 헤더가 압축됩니다. 이전 Claude Code 버전은 더 이상 최신 세션의 `state.json` 필드를 삭제하거나 해당 세션을 `claude agents`에서 숨기지 않습니다. 중지된 세션에 연결하면 최대 5초 동안 빈 화면을 표시하는 대신 즉시 전환됩니다. 연결을 수락할 수 없는 감독자는 자체적으로 종료되고 잠금을 해제합니다. |

683| v2.1.174 | {/* min-version: 2.1.174 */}백그라운드 세션은 더 이상 감독자의 시작 셸에서 `ANTHROPIC_BASE_URL`과 같은 게이트웨이 엔드포인트 변수를 상속하지 않습니다. 감독자는 사전 준비된 워커에 새로운 자격 증명 스냅샷을 제공하여 허위 `Could not resolve authentication method` 오류를 수정합니다. |738| v2.1.174 | {/* min-version: 2.1.174 */}백그라운드 세션은 더 이상 감독자의 시작 셸에서 `ANTHROPIC_BASE_URL`과 같은 게이트웨이 엔드포인트 변수를 상속하지 않습니다. 감독자는 사전 준비된 워커에 새로운 자격 증명 스냅샷을 제공하여 허위 `Could not resolve authentication method` 오류를 수정합니다. |

agents.md +1 −1

Details

53실행 중인 작업을 확인하는 명령은 사용한 접근 방식에 따라 다릅니다:53실행 중인 작업을 확인하는 명령은 사용한 접근 방식에 따라 다릅니다:

54 54

55* 백그라운드 세션의 경우, `claude agents`는 [에이전트 뷰](/ko/agent-view)를 열어줍니다: 모든 세션, 상태, 입력이 필요한 세션을 보여주는 하나의 화면입니다.55* 백그라운드 세션의 경우, `claude agents`는 [에이전트 뷰](/ko/agent-view)를 열어줍니다: 모든 세션, 상태, 입력이 필요한 세션을 보여주는 하나의 화면입니다.

56* 현재 세션의 서브에이전트의 경우, `/agents`는 라이브 서브에이전트를 나열하는 **Running** 탭과 [사용자 정의 서브에이전트를 생성하고 편집](/ko/sub-agents#use-the-%2Fagents-command)할 수 있는 **Library** 탭이 있는 패널을 엽니다. 유사한 이름에도 불구하고 이는 `claude agents`와 별개입니다.56* 현재 세션의 서브에이전트의 경우, 명명된 백그라운드 서브에이전트는 상태와 함께 @-멘션 타입어헤드에 나타납니다. {/* min-version: 2.1.198 */}v2.1.198부터 `/agents`는 더 이상 패널을 열지 않으며, 서브에이전트 파일 위치를 가리키는 공지를 출력합니다. [사용자 정의 서브에이전트를 생성하고 편집](/ko/sub-agents#configure-subagents)하려면 Claude에 요청하거나 파일을 직접 편집하세요. 유사한 이름에도 불구하고 `/agents`는 `claude agents`와 별개입니다.

57* 현재 세션의 백그라운드에서 실행 중인 모든 것의 경우, `/tasks`는 각 항목을 나열하고 확인, 연결 또는 중지할 수 있게 해줍니다.57* 현재 세션의 백그라운드에서 실행 중인 모든 것의 경우, `/tasks`는 각 항목을 나열하고 확인, 연결 또는 중지할 수 있게 해줍니다.

58* 동적 워크플로우의 경우, `/workflows`는 실행 중이고 완료된 실행, 각각이 있는 단계, 완료된 에이전트의 수를 나열합니다.58* 동적 워크플로우의 경우, `/workflows`는 실행 중이고 완료된 실행, 각각이 있는 단계, 완료된 에이전트의 수를 나열합니다.

59 59

amazon-bedrock.md +1 −1

Details

184 184

185이 두 설정은 서로 다른 트리거 조건을 가집니다:185이 두 설정은 서로 다른 트리거 조건을 가집니다:

186 186

187* **`awsAuthRefresh`**: Claude Code가 AWS 자격 증명이 만료되었음을 감지할 때만 실행됩니다. 타임스탬프를 기반으로 로컬에서 또는 Bedrock이 자격 증명 오류를 반환할 때 감지되며, 새로 고쳐진 자격 증명으로 요청을 다시 시도합니다.187* **`awsAuthRefresh`**: Claude Code가 AWS 자격 증명이 만료되었음을 감지할 때만 실행됩니다. 타임스탬프를 기반으로 로컬에서 또는 API가 자격 증명 오류를 반환할 때 감지되며, 새로 고쳐진 자격 증명으로 요청을 다시 시도합니다.

188* **`awsCredentialExport`**: 세션 시작 시 및 각 자격 증명 다시 로드 시 실행되며, AWS 기본 자격 증명 공급자 체인의 자격 증명이 여전히 유효한 경우에도 실행됩니다. Bedrock 계정이 기본 공급자 체인이 확인할 자격 증명과 다른 교차 계정 자격 증명을 필요로 할 때 사용하십시오.188* **`awsCredentialExport`**: 세션 시작 시 및 각 자격 증명 다시 로드 시 실행되며, AWS 기본 자격 증명 공급자 체인의 자격 증명이 여전히 유효한 경우에도 실행됩니다. Bedrock 계정이 기본 공급자 체인이 확인할 자격 증명과 다른 교차 계정 자격 증명을 필요로 할 때 사용하십시오.

189 189

190<h5 id="example-configuration">190<h5 id="example-configuration">

auto-mode-config.md +18 −7

Details

54 54

55대부분의 조직에서 `autoMode.environment`는 설정해야 하는 유일한 필드입니다. 분류기에 신뢰할 수 있는 저장소, 버킷 및 도메인을 알려줍니다. 분류기는 이를 사용하여 "외부"가 무엇을 의미하는지 결정하므로, 나열되지 않은 모든 대상은 잠재적 정보 유출 대상입니다.55대부분의 조직에서 `autoMode.environment`는 설정해야 하는 유일한 필드입니다. 분류기에 신뢰할 수 있는 저장소, 버킷 및 도메인을 알려줍니다. 분류기는 이를 사용하여 "외부"가 무엇을 의미하는지 결정하므로, 나열되지 않은 모든 대상은 잠재적 정보 유출 대상입니다.

56 56

~~57Claude Code v2.1.195부터 `claude auto-mode defaults`는 두 가지 종류의 환경 항목을 인쇄합니다.~~57Claude Code v2.1.198부터 `claude auto-mode defaults`는 세 가지 종류의 환경 항목을 인쇄합니다. v2.1.195 이전 버전은 처음 다섯 개의 신뢰 슬롯만 인쇄합니다.

58 58

59* **컨텍스트 슬롯**: 조직, 스택 및 보안 태세를 설명하여 분류기가 컨텍스트의 다른 규칙을 읽을 수 있도록 합니다. 다른 두 가지 종류와 달리 컨텍스트 슬롯은 이를 대상으로 하는 자체 규칙이 없습니다. 각각은 `None configured`로 기본 설정되거나 옆에 명명된 보수적 가정으로 기본 설정됩니다:

60 * **조직**

61 * **Claude Code의 주요 용도**: 소프트웨어 개발으로 기본 설정됨

62 * **클라우드 제공자**

63 * **저장소 가시성**: 원격 호스트 및 이름이 다르게 표시하지 않는 한 저장소는 비공개로 가정됩니다

64 * **내부 공유 / 스니펫 호스팅**: 공개 붙여넣기 및 gist 서비스는 명명할 때까지 신뢰 경계 외부로 취급됩니다

65 * **조직별 CLI**

66 * **비밀 관리**

67 * **기본 / 보호된 분기**: `main` 및 `master`는 다른 것을 명명할 때까지 보호된 것으로 취급됩니다

68 * **CI/CD 배포 대상**

69 * **네트워크 태세**

70 * **보호된 배포 네임스페이스 / 환경**: 명명할 때까지 민감한 원격 대상 휴리스틱으로 폴백됩니다

71 * **데이터 보존 / 기밀 해제**

59* **신뢰 슬롯**: 분류기가 경계 내부로 취급하는 것을 명명합니다. 슬롯은 신뢰할 수 있는 저장소, 소스 제어, 신뢰할 수 있는 내부 도메인, 신뢰할 수 있는 클라우드 버킷, 주요 내부 서비스 및 내부 패키지 레지스트리입니다. 저장소 및 소스 제어 항목은 기본적으로 작업 저장소와 그 구성된 원격 저장소로 설정됩니다. 다른 모든 신뢰 슬롯은 기본적으로 `None configured`로 설정되므로, 추가할 때까지 다른 것은 신뢰되지 않습니다.72* **신뢰 슬롯**: 분류기가 경계 내부로 취급하는 것을 명명합니다. 슬롯은 신뢰할 수 있는 저장소, 소스 제어, 신뢰할 수 있는 내부 도메인, 신뢰할 수 있는 클라우드 버킷, 주요 내부 서비스 및 내부 패키지 레지스트리입니다. 저장소 및 소스 제어 항목은 기본적으로 작업 저장소와 그 구성된 원격 저장소로 설정됩니다. 다른 모든 신뢰 슬롯은 기본적으로 `None configured`로 설정되므로, 추가할 때까지 다른 것은 신뢰되지 않습니다.

60* **민감도 슬롯**: 보호 규칙이 고위험으로 취급하는 것을 명명합니다. 슬롯은 PII / 규제 데이터 위치, 민감한 원격 대상 및 보호된 IaC 범위입니다. 각각은 기본적으로 광범위한 휴리스틱으로 설정되며, 예를 들어 이름에 `prod` 또는 `production`을 포함하는 모든 호스트 또는 네임스페이스를 민감한 원격 대상으로 취급하므로, 보호 규칙은 아무것도 구성하기 전에 활성화됩니다. 민감도 슬롯에서 구체적인 대상을 명명하면 휴리스틱 대신 명명된 대상에 해당 규칙이 적용됩니다.73* **민감도 슬롯**: 보호 규칙이 고위험으로 취급하는 것을 명명합니다. 슬롯은 민감한 데이터 위치 및 대상, 민감한 원격 대상 및 보호된 IaC 범위입니다. 각각은 기본적으로 광범위한 휴리스틱으로 설정되며, 예를 들어 이름에 `prod` 또는 `production`을 포함하는 모든 호스트 또는 네임스페이스를 민감한 원격 대상으로 취급하므로, 보호 규칙은 아무것도 구성하기 전에 활성화됩니다. 민감도 슬롯에서 구체적인 대상을 명명하면 휴리스틱 대신 명명된 대상에 해당 규칙이 적용됩니다.

~~62v2.1.195 이전 버전은 처음 다섯 개의 신뢰 슬롯만 인쇄합니다.~~

63 74

64기본값과 함께 자신의 항목을 추가하려면 배열에 리터럴 문자열 `"$defaults"`를 포함하세요. 기본 항목은 해당 위치에 삽입되므로, 사용자 정의 항목은 기본값 앞이나 뒤에 올 수 있습니다.75기본값과 함께 자신의 항목을 추가하려면 배열에 리터럴 문자열 `"$defaults"`를 포함하세요. 기본 항목은 해당 위치에 삽입되므로, 사용자 정의 항목은 기본값 앞이나 뒤에 올 수 있습니다.

65 76

87* **신뢰할 수 있는 내부 도메인**: 네트워크 내부의 API, 대시보드 및 서비스에 대한 호스트명(예: `*.internal.example.com`)98* **신뢰할 수 있는 내부 도메인**: 네트워크 내부의 API, 대시보드 및 서비스에 대한 호스트명(예: `*.internal.example.com`)

88* **주요 내부 서비스**: CI, 아티팩트 레지스트리, 내부 패키지 인덱스, 인시던트 도구99* **주요 내부 서비스**: CI, 아티팩트 레지스트리, 내부 패키지 인덱스, 인시던트 도구

89* **내부 패키지 레지스트리**: 설치가 라우팅되어야 하는 개인 npm, PyPI 또는 기타 레지스트리이므로, 공개 레지스트리를 위해 이를 우회하는 설치는 차단됩니다.100* **내부 패키지 레지스트리**: 설치가 라우팅되어야 하는 개인 npm, PyPI 또는 기타 레지스트리이므로, 공개 레지스트리를 위해 이를 우회하는 설치는 차단됩니다.

90* **PII / 규제 데이터 위치**: 개인 또는 규제 데이터를 보유하는 버킷, 데이터베이스 또는 경로이므로, 분류기가 콘텐츠에서 추측하는 대신 해당 위치를 보호합니다.101* **민감한 데이터 위치 및 대상**: 개인 데이터, 기밀 비즈니스 데이터, 자격 증명, 규제 데이터 또는 유사하게 민감한 자료를 보유하는 버킷, 데이터베이스 또는 경로, 그리고 각 위치의 데이터가 공유될 수 있는 대상이므로, 분류기가 콘텐츠에서 추측하는 대신 해당 위치를 보호합니다. {/* min-version: 2.1.195 */}{/* max-version: 2.1.197 */}Claude Code v2.1.195부터 v2.1.197까지는 이 항목을 PII / 규제 데이터 위치로 명명하고 대상 차원 없이 개인 또는 규제 데이터를 보유하는 위치만 포함합니다

91* **민감한 원격 대상**: 프로덕션으로 계산되는 네임스페이스, 호스트 또는 컨테이너이므로, 원격 셸 및 포트 포워드는 명시적 승인이 필요합니다.102* **민감한 원격 대상**: 프로덕션으로 계산되는 네임스페이스, 호스트 또는 컨테이너이므로, 원격 셸 및 포트 포워드는 명시적 승인이 필요합니다.

92* **보호된 IaC 범위**: 적용 또는 삭제가 항상 변경을 명명하도록 요구해야 하는 인프라 리소스입니다.103* **보호된 IaC 범위**: 적용 또는 삭제가 항상 변경을 명명하도록 요구해야 하는 인프라 리소스입니다.

93* **추가 컨텍스트**: 규제 산업 제약, 다중 테넌트 인프라 또는 분류기가 위험으로 취급해야 할 사항에 영향을 미치는 규정 준수 요구사항104* **추가 컨텍스트**: 규제 산업 제약, 다중 테넌트 인프라 또는 분류기가 위험으로 취급해야 할 사항에 영향을 미치는 규정 준수 요구사항

94 105

95내부 패키지 레지스트리, PII / 규제 데이터 위치, 민감한 원격 대상 및 보호된 IaC 범위 항목은 Claude Code v2.1.195 이상이 필요합니다. 이전 버전은 여전히 이를 일반 컨텍스트로 읽지만 이를 대상으로 하는 기본 제공 규칙이 없습니다.106내부 패키지 레지스트리, 민감한 데이터 위치 및 대상, 민감한 원격 대상 및 보호된 IaC 범위 항목은 Claude Code v2.1.195 이상이 필요합니다. 이전 버전은 여전히 이를 일반 컨텍스트로 읽지만 이를 대상으로 하는 기본 제공 규칙이 없습니다.

96 107

97유용한 시작 템플릿: 괄호로 묶인 필드를 채우고 적용되지 않는 줄을 제거하세요.108유용한 시작 템플릿: 괄호로 묶인 필드를 채우고 적용되지 않는 줄을 제거하세요.

98 109

chrome.md +15 −2

Details

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

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

4 4

~~5# Chrome에서 Claude Code 사용하기 (베타)~~5# Chrome에서 Claude Code 사용하기

6 6

7> Claude Code를 Chrome 브라우저에 연결하여 웹 앱을 테스트하고, 콘솔 로그로 디버깅하며, 양식 작성을 자동화하고, 웹 페이지에서 데이터를 추출합니다.7> Claude Code를 Chrome 브라우저에 연결하여 웹 앱을 테스트하고, 콘솔 로그로 디버깅하며, 양식 작성을 자동화하고, 웹 페이지에서 데이터를 추출합니다.

8 8

11Claude는 브라우저 작업을 위해 새 탭을 열고 브라우저의 로그인 상태를 공유하므로 이미 로그인한 모든 사이트에 액세스할 수 있습니다. 브라우저 작업은 실시간으로 표시되는 Chrome 창에서 실행됩니다. Claude가 로그인 페이지나 CAPTCHA를 만나면 일시 중지하고 수동으로 처리하도록 요청합니다.11Claude는 브라우저 작업을 위해 새 탭을 열고 브라우저의 로그인 상태를 공유하므로 이미 로그인한 모든 사이트에 액세스할 수 있습니다. 브라우저 작업은 실시간으로 표시되는 Chrome 창에서 실행됩니다. Claude가 로그인 페이지나 CAPTCHA를 만나면 일시 중지하고 수동으로 처리하도록 요청합니다.

12 12

13<Note>13<Note>

14 Chrome 통합은 베타 버전이며 현재 Google Chrome 및 Microsoft Edge에서 작동합니다. Brave, Arc 또는 기타 Chromium 기반 브라우저에서는 아직 지원되지 않습니다. WSL(Windows Subsystem for Linux)도 지원되지 않습니다.14 Chrome 통합은 Google Chrome 및 Microsoft Edge에서 작동합니다. Brave, Arc 또는 기타 Chromium 기반 브라우저에서는 아직 지원되지 않습니다. Windows Subsystem for Linux(WSL)도 지원되지 않습니다.

15</Note>15</Note>

16 16

17<h2 id="capabilities">17<h2 id="capabilities">

90 90

91사이트 수준 권한은 Chrome 확장 프로그램에서 상속됩니다. Chrome 확장 프로그램 설정에서 권한을 관리하여 Claude가 탐색하고, 클릭하고, 입력할 수 있는 사이트를 제어합니다.91사이트 수준 권한은 Chrome 확장 프로그램에서 상속됩니다. Chrome 확장 프로그램 설정에서 권한을 관리하여 Claude가 탐색하고, 클릭하고, 입력할 수 있는 사이트를 제어합니다.

92 92

93<h3 id="browser-tools-in-plan-mode">

94 계획 모드에서의 브라우저 도구

95</h3>

97[계획 모드](/ko/permission-modes#analyze-before-you-edit-with-plan-mode)에서는 페이지나 브라우저 상태만 읽는 브라우저 도구 호출이 권한 프롬프트 없이 실행되고, 상태를 변경하는 호출은 승인을 요청합니다.

99* **읽기 전용 호출**: `read_page`, `get_page_text`, `find`, 콘솔 메시지 또는 네트워크 요청 읽기, 스크린샷 촬영

100* **상태 변경 호출**: 클릭, 입력, 탐색, 탭 및 창 관리, GIF 녹화

101

102v2.1.199부터 `tabs_context_mcp`의 `createIfEmpty`, 콘솔 및 네트워크 리더의 `clear`, 스크린샷의 `save_to_disk`와 같이 상태 변경 입력 플래그를 설정하는 읽기 전용 호출도 승인을 요청합니다. `browser_batch` 호출은 내부의 모든 작업이 읽기 전용일 때만 프롬프트 없이 실행됩니다.

103

93<h2 id="example-workflows">104<h2 id="example-workflows">

94 예제 워크플로우105 예제 워크플로우

95</h2>106</h2>

208 219

209Chrome 통합을 처음 활성화할 때 Claude Code는 네이티브 메시징 호스트 구성 파일을 설치합니다. Chrome은 시작 시 이 파일을 읽으므로 첫 번째 시도에서 확장 프로그램이 감지되지 않으면 Chrome을 다시 시작하여 새 구성을 선택합니다.220Chrome 통합을 처음 활성화할 때 Claude Code는 네이티브 메시징 호스트 구성 파일을 설치합니다. Chrome은 시작 시 이 파일을 읽으므로 첫 번째 시도에서 확장 프로그램이 감지되지 않으면 Chrome을 다시 시작하여 새 구성을 선택합니다.

210 221

222v2.1.199부터 Claude Code는 첫 번째 설치 시에만 확장 프로그램을 연결하도록 요청하는 브라우저 탭을 엽니다. Claude Code 빌드 또는 구성 디렉터리 전환 후와 같이 구성 파일을 다시 작성하는 이후 세션에서는 다시 열지 않습니다.

223

211연결이 계속 실패하면 다음 위치에 호스트 구성 파일이 있는지 확인합니다.224연결이 계속 실패하면 다음 위치에 호스트 구성 파일이 있는지 확인합니다.

212 225

213Chrome의 경우:226Chrome의 경우:

claude-apps-gateway-config.md +61 −8

Details

4 4

5# Claude 앱 게이트웨이 구성5# Claude 앱 게이트웨이 구성

6 6

7> 모든 gateway.yaml 옵션에 대한 참조: 리스너 및 TLS, OIDC, 세션, Postgres 저장소, Bedrock/Agent Platform/Foundry 업스트림, 모델 라우팅, 관리형 정책 및 텔레메트리.7> 모든 gateway.yaml 옵션에 대한 참조: 리스너 및 TLS, OIDC, 세션, Postgres 저장소, Bedrock/Claude Platform on AWS/Agent Platform/Foundry 업스트림, 모델 라우팅, 관리형 정책 및 텔레메트리.

8 8

9Claude 앱 게이트웨이 배포는 하나의 YAML 파일(관례상 `gateway.yaml`)로 구성됩니다. 이 파일은 게이트웨이가 수행하는 모든 작업을 정의합니다: 어디서 수신 대기하는지, 개발자가 어떻게 로그인하는지, 추론이 어디로 가는지, 어떤 정책과 텔레메트리가 적용되는지입니다. 이 페이지는 해당 파일의 모든 옵션에 대한 참조입니다. 첫 번째 파일을 작성하려면 [빠른 시작](/ko/claude-apps-gateway#quickstart)에서 시작하세요. 이 페이지는 최소한의 작동 구성을 구축하고 실행합니다. 만족스러운 구성이 있으면 [배포 가이드](/ko/claude-apps-gateway-deploy)에서 Kubernetes, Cloud Run 또는 자신의 플랫폼에서 컨테이너화 및 호스팅하는 방법을 다룹니다.9Claude 앱 게이트웨이 배포는 하나의 YAML 파일(관례상 `gateway.yaml`)로 구성됩니다. 이 파일은 게이트웨이가 수행하는 모든 작업을 정의합니다: 어디서 수신 대기하는지, 개발자가 어떻게 로그인하는지, 추론이 어디로 가는지, 어떤 정책과 텔레메트리가 적용되는지입니다. 이 페이지는 해당 파일의 모든 옵션에 대한 참조입니다.

11첫 번째 파일을 작성하려면 [빠른 시작](/ko/claude-apps-gateway#quickstart)에서 시작하세요. 이 페이지는 최소한의 작동 구성을 구축하고 실행합니다. 만족스러운 구성이 있으면 [배포 가이드](/ko/claude-apps-gateway-deploy)에서 Kubernetes, Cloud Run 또는 자신의 플랫폼에서 컨테이너화 및 호스팅하는 방법을 다룹니다.

10 12

11게이트웨이는 `claude gateway --config /path/to/gateway.yaml`을 사용하여 시작 시 파일을 한 번 읽습니다. 모든 옵션은 부팅 시 스키마에 대해 검증되므로 잘못된 구성은 첫 사용 시가 아니라 필드 수준 오류로 시작 시 실패합니다.13게이트웨이는 `claude gateway --config /path/to/gateway.yaml`을 사용하여 시작 시 파일을 한 번 읽습니다. 모든 옵션은 부팅 시 스키마에 대해 검증되므로 잘못된 구성은 첫 사용 시가 아니라 필드 수준 오류로 시작 시 실패합니다.

12 14

24* [`oidc`](#oidc): ID 공급자(IdP), 발급자, 클라이언트, 클레임 매핑 및 로그인 가능 사용자 포함26* [`oidc`](#oidc): ID 공급자(IdP), 발급자, 클라이언트, 클레임 매핑 및 로그인 가능 사용자 포함

25* [`session`](#session): 게이트웨이가 발급하는 베어러 토큰, 비밀 및 수명 포함27* [`session`](#session): 게이트웨이가 발급하는 베어러 토큰, 비밀 및 수명 포함

26* [`store`](#store): 장치 권한 부여 및 속도 제한 카운터용 PostgreSQL28* [`store`](#store): 장치 권한 부여 및 속도 제한 카운터용 PostgreSQL

~~27* [`upstreams`](#upstreams): 추론이 가는 위치, Anthropic, Bedrock, Agent Platform 또는 Foundry 여부~~29* [`upstreams`](#upstreams): 추론이 가는 위치, Anthropic, Bedrock, Claude Platform on AWS, Agent Platform 또는 Foundry 여부

28 30

29**선택 사항 섹션:**31**선택 사항 섹션:**

30 32

68 `oidc`70 `oidc`

69</h3>71</h3>

70 72

71OpenID Connect(OIDC)는 게이트웨이가 ID 공급자와 함께 사용하는 SSO 프로토콜입니다. IdP 측에서 등록할 내용은 [ID 공급자 설정](/ko/claude-apps-gateway-deploy#identity-provider-setup)을 참조하세요. `oidc` 블록은 게이트웨이를 ID 공급자에 연결하고 로그인할 수 있는 사용자를 결정합니다. 발급자 및 OAuth 클라이언트의 이름을 지정하고, 이메일 및 그룹을 전달하는 클레임을 매핑하며, 이메일 도메인 또는 그룹별로 로그인을 제한합니다.73`oidc` 블록은 게이트웨이를 ID 공급자에 연결하고 로그인할 수 있는 사용자를 결정합니다. 발급자 및 OAuth 클라이언트의 이름을 지정하고, 이메일 및 그룹을 전달하는 클레임을 매핑하며, 이메일 도메인 또는 그룹별로 로그인을 제한합니다.

75OpenID Connect(OIDC)는 게이트웨이가 ID 공급자와 함께 사용하는 SSO 프로토콜입니다. IdP 측에서 등록할 내용은 [ID 공급자 설정](/ko/claude-apps-gateway-deploy#identity-provider-setup)을 참조하세요.

72 76

73| 필드 | 필수 | 설명 |77| 필드 | 필수 | 설명 |

74| ------------------------------- | --- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |78| ------------------------------- | --- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

121 `upstreams`125 `upstreams`

122</h3>126</h3>

123 127

124`upstreams`는 정렬된 목록입니다. 게이트웨이는 요청된 모델을 확인하는 첫 번째 업스트림으로 추론을 전달합니다. `5xx`, `429` 또는 시간 초과 시 다음으로 장애 조치합니다. 다른 `4xx`는 그렇지 않습니다. 이러한 오류는 업스트림이 아닌 요청에 기인하기 때문입니다. 동일한 공급자의 여러 업스트림은 고유한 `name:`을 설정해야 합니다.128`upstreams`는 정렬된 목록입니다. 게이트웨이는 요청된 모델을 확인하는 첫 번째 업스트림으로 추론을 전달합니다. `5xx`, `429`, `401`, `403`, `404` 또는 시간 초과 시 다음으로 장애 조치합니다. 다른 `4xx`는 그렇지 않습니다. 이러한 오류는 업스트림이 아닌 요청에 기인하기 때문입니다. `401` 또는 `403`은 게이트웨이 자신의 자격증명이 해당 업스트림에 대해 실패했음을 의미하고, `404`는 해당 업스트림이 요청된 모델을 제공하지 않음을 의미하므로 목록의 나중 업스트림이 여전히 제공할 수 있습니다.

129

130`404`에서의 장애 조치는 게이트웨이 v2.1.198 이상이 필요합니다. 이전 릴리스는 목록의 나중 업스트림이 모델을 제공했을 때도 첫 번째 `404`를 클라이언트에 반환했습니다.

125 131

126Bedrock, Agent Platform 및 Foundry 클라이언트는 시작 시 한 번 구축되며 SDK는 자격증명을 내부적으로 새로 고치므로 클라우드 자격증명을 회전해도 재시작이 필요하지 않습니다. 정적 Anthropic API 키 및 베어러는 시작 시 읽혀집니다. [Anthropic API](#anthropic-api)를 참조하세요.132동일한 공급자의 여러 업스트림은 고유한 `name:`을 설정해야 합니다.

133

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

127 135

128<h4 id="anthropic-api">136<h4 id="anthropic-api">

129 Anthropic API137 Anthropic API

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

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

195 203

204<h4 id="claude-platform-on-aws">

205 Claude Platform on AWS

206</h4>

207

208Claude Platform on AWS는 `aws-external-anthropic.<region>.api.aws`에서 AWS 인프라의 퍼스트파티 Anthropic API를 제공합니다. 퍼스트파티 모델 ID를 사용하고, 전송된 대로 `anthropic-beta` 헤더를 준수하며, `count_tokens`를 제공하므로 Bedrock 특정 변환이 적용되지 않습니다. `anthropicAws` 공급자는 Claude Code v2.1.198 이상이 필요합니다. 이전 게이트웨이 릴리스는 부팅 시 이를 거부합니다.

209

210동일한 플랫폼의 클라이언트 측 배포의 경우 [Claude Platform on AWS의 Claude Code](/ko/claude-platform-on-aws)를 참조하세요. 게이트웨이 측 업스트림:

211

212```yaml theme={null}

213upstreams:

214 - provider: anthropicAws

215 region: us-east-1

216 workspace_id: wrkspc_...

217 auth:

218 api_key: ${ANTHROPIC_AWS_API_KEY} # x-api-key로 전송됨

219 # 또는 AWS 기본 자격증명 체인을 통한 SigV4:

220 # auth: {}

221 # 또는 명시적 SigV4 자격증명:

222 # auth:

223 # aws_access_key_id: ${AWS_ACCESS_KEY_ID}

224 # aws_secret_access_key: ${AWS_SECRET_ACCESS_KEY}

225 # 파생된 엔드포인트를 재정의합니다:

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

227```

228

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

230

231| 필드 | 필수 | 설명 |

232| ------------------------------------------------------- | --- | ---------------------------------------------------------------------------------------------- |

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

234| `workspace_id` | 예 | 모든 요청에서 헤더로 전송됨; 플랫폼이 필요로 함 |

235| `auth.api_key` | 아니요 | 플랫폼의 API 키, `x-api-key`로 전송됨. 베어러 토큰이 아님: 두 인증 모드는 API 키 또는 SigV4입니다. |

236| `auth.aws_access_key_id` / `auth.aws_secret_access_key` | 아니요 | 명시적 SigV4 자격증명. 하나를 다른 하나 없이 설정하면 부팅 시 실패합니다. `auth.aws_session_token`은 이들과 함께 허용됩니다. |

237| `base_url` | 아니요 | 파생된 엔드포인트를 재정의합니다 |

238

239플랫폼이 퍼스트파티 모델 ID를 확인하므로 기본 제공 카탈로그는 [`models:`](#models) 블록 없이 이로 라우팅합니다. `models:` 목록을 큐레이션할 때 항목을 `anthropicAws:`로 퍼스트파티 ID로 키합니다.

240

196<h4 id="google-cloud-agent-platform">241<h4 id="google-cloud-agent-platform">

197 Google Cloud Agent Platform242 Google Cloud Agent Platform

198</h4>243</h4>

255 300

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

257 302

258게이트웨이는 순서대로 업스트림을 시도합니다. `5xx`, `429`, 시간 초과 및 누락된 엔드포인트(`501`)는 장애 조치합니다. 다른 `4xx`는 그렇지 않습니다. `429`는 업스트림별 용량이므로 프로비저닝된 처리량(PT) 소진은 온디맨드로 장애 조치합니다. 요청된 모델을 확인할 수 없는 업스트림은 네트워크 왕복 없이 건너뜁니다.303게이트웨이는 순서대로 업스트림을 시도합니다. `5xx`, `429`, `401`, `403`, `404`, 시간 초과 및 누락된 엔드포인트(`501`)는 장애 조치합니다. 다른 `4xx`는 그렇지 않습니다. `429`는 업스트림별 용량이므로 프로비저닝된 처리량(PT) 소진은 온디맨드로 장애 조치합니다. `404`는 업스트림별 모델 가용성이므로 모델을 활성화하지 않은 업스트림은 해당 모델을 제공하는 나중 업스트림을 차단하지 않습니다. 요청된 모델을 확인할 수 없는 업스트림은 네트워크 왕복 없이 건너뜁니다.

259 304

260이 예제는 프로비저닝된 처리량 Bedrock 할당을 먼저 라우팅하고, 온디맨드 및 두 번째 계정으로 오버플로우하며, 마지막으로 Anthropic API로 장애 조치합니다:305이 예제는 프로비저닝된 처리량 Bedrock 할당을 먼저 라우팅하고, 온디맨드 및 두 번째 계정으로 오버플로우하며, 마지막으로 Anthropic API로 장애 조치합니다:

261 306

512* `sandbox.network.allowManagedDomainsOnly` 및 `sandbox.filesystem.allowManagedReadPathsOnly`: 잠금 시 해당 허용 목록은 소스 전체에서 합집합됩니다.557* `sandbox.network.allowManagedDomainsOnly` 및 `sandbox.filesystem.allowManagedReadPathsOnly`: 잠금 시 해당 허용 목록은 소스 전체에서 합집합됩니다.

513* [`allowAllClaudeAiMcps`](/ko/settings#available-settings): claude.ai MCP 서버 허용 목록에 대한 허용 전용 재정의558* [`allowAllClaudeAiMcps`](/ko/settings#available-settings): claude.ai MCP 서버 허용 목록에 대한 허용 전용 재정의

514* `sandbox.bwrapPath` 및 `sandbox.socatPath`: [샌드박스](/ko/sandboxing) 도우미 바이너리의 파일 시스템 경로559* `sandbox.bwrapPath` 및 `sandbox.socatPath`: [샌드박스](/ko/sandboxing) 도우미 바이너리의 파일 시스템 경로

560* [`forceRemoteSettingsRefresh`](/ko/server-managed-settings): 원격 관리형 설정이 새로 가져올 때까지 시작을 차단하므로 키가 없는 캐시된 원격 페이로드가 가장 높은 우선순위 소스인 경우에도 MDM 또는 파일 정책이 적용됩니다.

515 561

516`allowManagedPermissionRulesOnly` 및 `disableBypassPermissionsMode`는 교차 소스가 아니므로 승리한 소스의 값만 적용됩니다. 설정 페이지의 동일한 규칙은 [설정 우선순위](/ko/settings#settings-precedence)를 참조하세요.562`allowManagedPermissionRulesOnly` 및 `disableBypassPermissionsMode`는 교차 소스가 아니므로 승리한 소스의 값만 적용됩니다. 설정 페이지의 동일한 규칙은 [설정 우선순위](/ko/settings#settings-precedence)를 참조하세요.

517 563

583| `rate_limits` | `device_authorization.max` / `.window_seconds` | 30 / 600 | 인증되지 않은 장치 인증 엔드포인트에 대한 IP당 속도 제한. 공유 송신 IP 또는 NAT 뒤의 큰 조직에 대해 올립니다. 이러한 한도는 장치 권한 부여 로그인 흐름에만 적용되며 `/v1/messages` 추론에는 적용되지 않습니다. [사용자 코드 무차별 대입 공격 저항](/ko/claude-apps-gateway-deploy#user-code-brute-force-resistance)을 참조하세요. |629| `rate_limits` | `device_authorization.max` / `.window_seconds` | 30 / 600 | 인증되지 않은 장치 인증 엔드포인트에 대한 IP당 속도 제한. 공유 송신 IP 또는 NAT 뒤의 큰 조직에 대해 올립니다. 이러한 한도는 장치 권한 부여 로그인 흐름에만 적용되며 `/v1/messages` 추론에는 적용되지 않습니다. [사용자 코드 무차별 대입 공격 저항](/ko/claude-apps-gateway-deploy#user-code-brute-force-resistance)을 참조하세요. |

585 631

661 # region: us-east-1707 # region: us-east-1

662 # auth: {}708 # auth: {}

663 709

710 # - provider: anthropicAws

711 # region: us-east-1

712 # workspace_id: wrkspc_...

713 # auth:

714 # api_key: ${ANTHROPIC_AWS_API_KEY}

715

664 # - provider: vertex716 # - provider: vertex

665 # region: us-east5717 # region: us-east5

666 # project_id: example-prod718 # project_id: example-prod

677 upstream_model:729 upstream_model:

678 anthropic: claude-opus-4-8730 anthropic: claude-opus-4-8

679 # bedrock: us.anthropic.claude-opus-4-8731 # bedrock: us.anthropic.claude-opus-4-8

732 # anthropicAws: claude-opus-4-8

680 # vertex: claude-opus-4-8733 # vertex: claude-opus-4-8

681 # foundry: <your-opus-deployment-name>734 # foundry: <your-opus-deployment-name>

682 - id: claude-sonnet-4-6735 - id: claude-sonnet-4-6

claude-code-on-the-web.md +2 −2

Details

721텔레포트는 세션을 재개하기 전에 이러한 요구 사항을 확인합니다. 요구 사항이 충족되지 않으면 오류가 표시되거나 문제를 해결하라는 메시지가 표시됩니다.721텔레포트는 세션을 재개하기 전에 이러한 요구 사항을 확인합니다. 요구 사항이 충족되지 않으면 오류가 표시되거나 문제를 해결하라는 메시지가 표시됩니다.

722 722

723| 요구 사항 | 세부 정보 |723| 요구 사항 | 세부 정보 |

724| --------------- | ------------------------------------------------------------------------- |724| --------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

725| Clean git state | 작업 디렉토리에 커밋되지 않은 변경 사항이 없어야 합니다. 텔레포트가 필요한 경우 변경 사항을 stash하라는 메시지를 표시합니다. |725| Clean git state | 작업 디렉토리에 커밋되지 않은 변경 사항이 없어야 합니다. 텔레포트가 필요한 경우 변경 사항을 stash하라는 메시지를 표시합니다. |

726| 올바른 저장소 | fork가 아닌 동일한 저장소의 체크아웃에서 `--teleport`를 실행해야 합니다. |726| 올바른 저장소 | fork가 아닌 동일한 저장소의 체크아웃에서 `--teleport`를 실행해야 합니다. {/* min-version: 2.1.199 */}v2.1.199부터 Claude Code는 `git@work:owner/repo.git`과 같은 SSH 호스트 별칭이나 `insteadOf`로 다시 쓴 짧은 형식과 같이 원격을 호스트 이름으로 구문 분석할 수 없는 경우에도 체크아웃을 수락합니다. 먼저 확인 프롬프트를 표시하고, 원격의 소유자 및 저장소 이름이 세션의 저장소와 일치할 때만 표시됩니다. |

727| 분기 사용 가능 | 클라우드 세션의 분기가 원격으로 푸시되어야 합니다. 텔레포트가 자동으로 가져와 체크아웃합니다. |727| 분기 사용 가능 | 클라우드 세션의 분기가 원격으로 푸시되어야 합니다. 텔레포트가 자동으로 가져와 체크아웃합니다. |

728| 동일한 계정 | 클라우드 세션에서 사용한 동일한 claude.ai 계정으로 인증되어야 합니다. |728| 동일한 계정 | 클라우드 세션에서 사용한 동일한 claude.ai 계정으로 인증되어야 합니다. |

729 729

claude-platform-on-aws.md +1 −1

Details

230 230

231CI 및 자동화의 경우 Anthropic 서비스를 호출할 수 있는 권한이 있는 IAM 역할을 실행기에 제공하고 `AWS_REGION`을 설정하십시오. 자격 증명 체인이 역할을 자동으로 선택합니다.231CI 및 자동화의 경우 Anthropic 서비스를 호출할 수 있는 권한이 있는 IAM 역할을 실행기에 제공하고 `AWS_REGION`을 설정하십시오. 자격 증명 체인이 역할을 자동으로 선택합니다.

232 232

233SSO 자격 증명이 세션 중에 만료되면 [`awsAuthRefresh`](/ko/amazon-bedrock#advanced-credential-configuration)를 구성하여 Claude Code가 로그인 명령을 다시 실행하고 실패하는 대신 재시도하도록 합니다. `settings.json`에 명령을 추가하십시오.233SSO 자격 증명이 세션 중에 만료되면 [`awsAuthRefresh`](/ko/amazon-bedrock#advanced-credential-configuration)를 구성하여 Claude Code가 로그인 명령을 다시 실행하고 실패하는 대신 재시도하도록 합니다. Claude Platform on AWS에서 자동 새로 고침을 하려면 Claude Code v2.1.198 이상이 필요합니다. 이전 버전은 `/login`을 실행하라는 프롬프트로 중지되며, AWS 자격 증명을 새로 고칠 수 없습니다. `settings.json`에 명령을 추가하십시오.

234 234

235```json theme={null}235```json theme={null}

236{236{

cli-reference.md +4 −2

Details

47 47

48하위 명령어를 잘못 입력하면 Claude Code는 가장 가까운 일치를 제안하고 세션을 시작하지 않고 종료합니다. 예를 들어, `claude udpate`는 `Did you mean claude update?`를 인쇄합니다.48하위 명령어를 잘못 입력하면 Claude Code는 가장 가까운 일치를 제안하고 세션을 시작하지 않고 종료합니다. 예를 들어, `claude udpate`는 `Did you mean claude update?`를 인쇄합니다.

49 49

50{/* min-version: 2.1.199 */}v2.1.199부터 `claude --dangerously-skip-permissions daemon <subcommand>`는 `daemon` 하위 명령어를 실행합니다. 이전 버전에서는 `daemon <subcommand>`를 새 대화형 세션의 프롬프트로 처리했으므로 플래그가 먼저 올 때 하위 명령어가 실행되지 않았습니다. 이는 `claude`가 플래그를 포함하도록 별칭이 지정된 경우 일반적인 설정입니다. 선행 `--dangerously-skip-permissions` 또는 `--allow-dangerously-skip-permissions`만 이 방식으로 `daemon`으로 라우팅됩니다. 다른 선행 플래그는 여전히 대화형 세션을 시작합니다.

50<h2 id="cli-flags">52<h2 id="cli-flags">

51 CLI 플래그53 CLI 플래그

52</h2>54</h2>

66| `--ax-screen-reader` | {/* min-version: 2.1.181 */}스크린 리더 친화적 출력을 렌더링합니다: 장식용 테두리나 애니메이션 없는 평문입니다. 클래식 렌더러를 강제하므로 이 세션에 대해 [`tui`](/ko/settings#available-settings) 설정은 효과가 없습니다. [`CLAUDE_AX_SCREEN_READER`](/ko/env-vars) 및 [`axScreenReader`](/ko/settings#available-settings) 설정보다 우선합니다. Claude Code v2.1.181 이상이 필요합니다 | `claude --ax-screen-reader` |68| `--ax-screen-reader` | {/* min-version: 2.1.181 */}스크린 리더 친화적 출력을 렌더링합니다: 장식용 테두리나 애니메이션 없는 평문입니다. 클래식 렌더러를 강제하므로 이 세션에 대해 [`tui`](/ko/settings#available-settings) 설정은 효과가 없습니다. [`CLAUDE_AX_SCREEN_READER`](/ko/env-vars) 및 [`axScreenReader`](/ko/settings#available-settings) 설정보다 우선합니다. Claude Code v2.1.181 이상이 필요합니다 | `claude --ax-screen-reader` |

67| `--bare` | 최소 모드: hooks, skills, plugins, MCP 서버, 자동 메모리 및 CLAUDE.md의 자동 검색을 건너뜁니다. 스크립트된 호출이 더 빠르게 시작됩니다. Claude는 Bash, 파일 읽기 및 파일 편집 도구에 액세스할 수 있습니다. [`CLAUDE_CODE_SIMPLE`](/ko/env-vars)을 설정합니다. [bare 모드](/ko/headless#start-faster-with-bare-mode) 참조 | `claude --bare -p "query"` |69| `--bare` | 최소 모드: hooks, skills, plugins, MCP 서버, 자동 메모리 및 CLAUDE.md의 자동 검색을 건너뜁니다. 스크립트된 호출이 더 빠르게 시작됩니다. Claude는 Bash, 파일 읽기 및 파일 편집 도구에 액세스할 수 있습니다. [`CLAUDE_CODE_SIMPLE`](/ko/env-vars)을 설정합니다. [bare 모드](/ko/headless#start-faster-with-bare-mode) 참조 | `claude --bare -p "query"` |

69| `--bg`, `--background` | 세션을 [백그라운드 에이전트](/ko/agent-view)로 시작하고 즉시 반환합니다. 세션 ID와 관리 명령어를 인쇄합니다. `--exec`과 결합하여 Claude 세션 대신 셸 명령어를 백그라운드 작업으로 실행하거나, `--agent`와 결합하여 특정 subagent를 실행합니다 | `claude --bg "investigate the flaky test"` |71| `--bg`, `--background` | 세션을 [백그라운드 에이전트](/ko/agent-view)로 시작하고 즉시 반환합니다. 세션 ID와 관리 명령어를 인쇄합니다. `--exec`과 결합하여 Claude 세션 대신 셸 명령어를 백그라운드 작업으로 실행하거나, `--agent`와 결합하여 특정 subagent를 실행합니다. {/* min-version: 2.1.198 */}`-p`/`--print`와 결합할 수 없습니다. [오류 참조](/ko/errors#command-line-errors) 참조 | `claude --bg "investigate the flaky test"` |

70| `--channels` | (연구 미리보기) Claude가 이 세션에서 수신해야 할 [채널](/ko/channels) 알림이 있는 MCP 서버입니다. `plugin:<name>@<marketplace>` 항목의 공백으로 구분된 목록입니다. Claude.ai 인증이 필요합니다 | `claude --channels plugin:my-notifier@my-marketplace` |72| `--channels` | (연구 미리보기) Claude가 이 세션에서 수신해야 할 [채널](/ko/channels) 알림이 있는 MCP 서버입니다. `plugin:<name>@<marketplace>` 항목의 공백으로 구분된 목록입니다. Claude.ai 인증이 필요합니다 | `claude --channels plugin:my-notifier@my-marketplace` |

100| `--no-session-persistence` | 세션 지속성을 비활성화하여 세션이 디스크에 저장되지 않고 재개할 수 없습니다(인쇄 모드만 해당). [`CLAUDE_CODE_SKIP_PROMPT_HISTORY`](/ko/env-vars) 환경 변수는 모든 모드에서 동일한 작업을 수행합니다 | `claude -p --no-session-persistence "query"` |102| `--no-session-persistence` | 세션 지속성을 비활성화하여 세션이 디스크에 저장되지 않고 재개할 수 없습니다(인쇄 모드만 해당). [`CLAUDE_CODE_SKIP_PROMPT_HISTORY`](/ko/env-vars) 환경 변수는 모든 모드에서 동일한 작업을 수행합니다 | `claude -p --no-session-persistence "query"` |

102| `--permission-mode` | 지정된 [권한 모드](/ko/permission-modes)에서 시작합니다. `default`, `acceptEdits`, `plan`, `auto`, `dontAsk` 또는 `bypassPermissions`를 허용합니다. 설정 파일의 `defaultMode`를 재정의합니다 | `claude --permission-mode plan` |104| `--permission-mode` | 지정된 [권한 모드](/ko/permission-modes)에서 시작합니다. `default`, `acceptEdits`, `plan`, `auto`, `dontAsk` 또는 `bypassPermissions`를 허용합니다. 설정 파일의 `defaultMode`를 재정의합니다 | `claude --permission-mode plan` |

103| `--permission-prompt-tool` | 비대화형 모드에서 권한 프롬프트를 처리할 MCP 도구를 지정합니다 | `claude -p --permission-prompt-tool mcp_auth_tool "query"` |105| `--permission-prompt-tool` | 비대화형 모드에서 권한 프롬프트를 처리할 MCP 도구를 지정합니다. {/* min-version: 2.1.199 */}v2.1.199부터 프롬프트 도구는 [사용자 상호작용이 필요한](/ko/mcp#require-approval-for-a-specific-tool) 것으로 표시된 MCP 도구를 승인할 수 없습니다: 하나에 대한 `allow` 결과는 거부로 변환됩니다 | `claude -p --permission-prompt-tool mcp_auth_tool "query"` |

104| `--plugin-dir` | 이 세션에만 디렉토리 또는 `.zip` 아카이브에서 plugin을 로드합니다. 각 플래그는 하나의 경로를 사용합니다. 여러 plugins의 경우 플래그를 반복합니다: `--plugin-dir A --plugin-dir B.zip` | `claude --plugin-dir ./my-plugin` |106| `--plugin-dir` | 이 세션에만 디렉토리 또는 `.zip` 아카이브에서 plugin을 로드합니다. 각 플래그는 하나의 경로를 사용합니다. 여러 plugins의 경우 플래그를 반복합니다: `--plugin-dir A --plugin-dir B.zip` | `claude --plugin-dir ./my-plugin` |

105| `--plugin-url` | 이 세션에만 URL에서 plugin `.zip` 아카이브를 가져옵니다. 여러 plugins의 경우 플래그를 반복하거나 단일 따옴표 값에 공백으로 구분된 URL을 전달합니다 | `claude --plugin-url https://example.com/plugin.zip` |107| `--plugin-url` | 이 세션에만 URL에서 plugin `.zip` 아카이브를 가져옵니다. 여러 plugins의 경우 플래그를 반복하거나 단일 따옴표 값에 공백으로 구분된 URL을 전달합니다 | `claude --plugin-url https://example.com/plugin.zip` |

commands.md +9 −8

Details

10 10

11`/`를 입력하면 사용 가능한 모든 명령어를 볼 수 있으며, `/` 다음에 문자를 입력하여 필터링할 수 있습니다.11`/`를 입력하면 사용 가능한 모든 명령어를 볼 수 있으며, `/` 다음에 문자를 입력하여 필터링할 수 있습니다.

12 12

~~13명령어는 메시지의 시작 부분에서만 인식됩니다. 명령어 이름 다음에 오는 텍스트는 인수로 전달됩니다.~~13명령어는 메시지의 시작 부분에서만 인식됩니다. 명령어 이름 다음에 오는 텍스트는 인수로 전달됩니다. {/* min-version: 2.1.199 */}v2.1.199부터 [skills](/ko/skills#pass-arguments-to-skills)는 예외입니다. skill 호출 뒤에 더 많은 skills가 따르는 경우(예: `/skill-a /skill-b do XYZ`), 시작 부분에 명명된 모든 skill을 로드하고 후행 텍스트를 각각에 인수로 전달합니다. 최대 6개의 skills를 연결할 수 있습니다.

14 14

15<h2 id="commands-across-a-typical-workflow">15<h2 id="commands-across-a-typical-workflow">

16 일반적인 워크플로우 전반의 명령어16 일반적인 워크플로우 전반의 명령어

18 18

19대부분의 명령어는 프로젝트 설정부터 변경 사항 배포까지 세션의 특정 지점에서 유용합니다.19대부분의 명령어는 프로젝트 설정부터 변경 사항 배포까지 세션의 특정 지점에서 유용합니다.

20 20

21**리포지토리의 첫 번째 세션.** `/init`을 실행하여 시작 `CLAUDE.md`를 생성한 다음, `/memory`를 실행하여 이를 개선합니다. `/mcp` 및 `/agents`를 사용하여 프로젝트에 필요한 모든 서버 또는 subagent를 설정하고, `/permissions`을 사용하여 원하는 승인 규칙을 설정합니다.21**리포지토리의 첫 번째 세션.** `/init`을 실행하여 시작 `CLAUDE.md`를 생성한 다음, `/memory`를 실행하여 이를 개선합니다. `/mcp`를 사용하여 프로젝트에 필요한 모든 서버를 설정하고, Claude에게 원하는 [subagent](/ko/sub-agents)를 생성하도록 요청하며, `/permissions`을 실행하여 승인 규칙을 설정합니다.

22 22

23**작업 중.** `/plan`은 큰 변경 전에 plan mode로 전환합니다. `/model` 및 `/effort`는 소비하는 추론의 양을 조정합니다. 대화가 길어지면 `/context`는 윈도우가 어디로 가는지 보여주고 `/compact`는 이를 요약합니다. `/btw`를 사용하여 기록을 부풀리지 않아야 하는 빠른 여담을 남깁니다.23**작업 중.** `/plan`은 큰 변경 전에 plan mode로 전환합니다. `/model` 및 `/effort`는 사용 중인 모델과 적용하는 추론의 양을 조정합니다. 대화가 길어지면 `/context`는 윈도우를 채우는 것을 보여주고 `/compact`는 이를 요약하여 공간을 확보합니다. `/btw`를 사용하여 대화 기록에 추가되지 않아야 하는 빠른 여담을 남깁니다.

24 24

25**병렬로 작업 실행.** `/agents`는 Claude가 부작업을 위임할 수 있는 [subagent](/ko/sub-agents)의 관리자를 열고, `/tasks`는 현재 세션의 백그라운드에서 실행 중인 작업을 나열합니다. `/background`는 전체 세션을 분리하여 [background agent](/ko/agent-view)로 계속 실행되도록 하고 터미널을 해제합니다. 코드베이스에 걸친 큰 변경의 경우, `/batch`는 이를 독립적인 단위로 분해하고 각각을 자신의 [worktree](/ko/worktrees)에서 실행합니다. [병렬로 agent 실행](/ko/agents)을 참조하여 이러한 접근 방식이 어떻게 관련되는지 확인하십시오.25**병렬로 작업 실행.** Claude는 부작업을 [subagent](/ko/sub-agents)에게 위임하고, `/tasks`는 현재 세션의 백그라운드에서 실행 중인 작업을 나열합니다. `/background`는 전체 세션을 분리하여 [background agent](/ko/agent-view)로 계속 실행되도록 하고 터미널을 해제합니다. 코드베이스에 걸친 큰 변경의 경우, `/batch`는 이를 독립적인 단위로 분해하고 각각을 자신의 [worktree](/ko/worktrees)에서 실행합니다. [병렬로 agent 실행](/ko/agents)을 참조하여 이러한 접근 방식이 어떻게 관련되는지 확인하십시오.

26 26

27**배포 전.** `/diff`는 변경된 내용을 표시하고, `/code-review`는 diff를 정확성 버그 및 정리에 대해 확인하며 `--fix`로 결과를 적용할 수 있고, `/review`는 GitHub pull request에서 동일한 읽기 전용 검토를 실행하며, `/security-review`는 더 깊은 읽기 전용 검토를 제공합니다. `/code-review ultra`는 클라우드에서 다중 agent 검토를 실행합니다.27**배포 전.** `/diff`는 변경된 내용을 표시하고, `/code-review`는 diff를 정확성 버그 및 정리에 대해 확인하며 `--fix`로 결과를 적용할 수 있고, `/review`는 GitHub pull request에서 동일한 읽기 전용 검토를 실행하며, `/security-review`는 더 깊은 읽기 전용 검토를 제공합니다. `/code-review ultra`는 클라우드에서 다중 agent 검토를 실행합니다.

28 28

51| :--------------------------------------------------------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |51| :--------------------------------------------------------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

52| `/add-dir <path>` | 현재 세션 중에 파일 액세스를 위한 작업 디렉토리를 추가합니다. 대부분의 `.claude/` 구성은 추가된 디렉토리에서 [발견되지 않습니다](/ko/permissions#additional-directories-grant-file-access-not-configuration). 나중에 `--continue` 또는 `--resume`을 사용하여 추가된 디렉토리에서 세션을 재개할 수 있습니다 |52| `/add-dir <path>` | 현재 세션 중에 파일 액세스를 위한 작업 디렉토리를 추가합니다. 대부분의 `.claude/` 구성은 추가된 디렉토리에서 [발견되지 않습니다](/ko/permissions#additional-directories-grant-file-access-not-configuration). 나중에 `--continue` 또는 `--resume`을 사용하여 추가된 디렉토리에서 세션을 재개할 수 있습니다 |

53| `/advisor [model\|off]` | {/* min-version: 2.1.98 */}[advisor tool](/ko/advisor)을 활성화 또는 비활성화합니다. 이 도구는 작업 중 주요 순간에 두 번째 모델에 지침을 요청합니다. `opus`, `sonnet`, `fable` ({/* min-version: 2.1.170 */}v2.1.170+) 또는 전체 모델 ID를 허용합니다. 인수 없이 선택기를 엽니다. Claude Code v2.1.98 이상이 필요합니다 |53| `/advisor [model\|off]` | {/* min-version: 2.1.98 */}[advisor tool](/ko/advisor)을 활성화 또는 비활성화합니다. 이 도구는 작업 중 주요 순간에 두 번째 모델에 지침을 요청합니다. `opus`, `sonnet`, `fable` ({/* min-version: 2.1.170 */}v2.1.170+) 또는 전체 모델 ID를 허용합니다. 인수 없이 선택기를 엽니다. Claude Code v2.1.98 이상이 필요합니다 |

54| `/agents` | [agent](/ko/sub-agents) 구성을 관리합니다 |54| `/agents` | {/* min-version: 2.1.198 */}v2.1.198부터 `/agents`를 실행하면 Claude에 [subagents](/ko/sub-agents)를 만들거나 관리하도록 요청하거나, `.claude/agents/` 또는 `~/.claude/agents/`를 직접 편집하도록 상기시키는 메시지를 인쇄합니다. {/* max-version: 2.1.197 */}v2.1.197 이전에는 subagent 구성을 만들고 관리하기 위한 대화형 인터페이스를 엽니다 |

55| `/autofix-pr [prompt]` | 현재 브랜치의 PR을 감시하고 CI가 실패하거나 검토자가 댓글을 남길 때 수정 사항을 푸시하는 [Claude Code on the web](/ko/claude-code-on-the-web#auto-fix-pull-requests) 세션을 생성합니다. `gh pr view`를 사용하여 체크아웃된 브랜치에서 열린 PR을 감지합니다. 다른 PR을 감시하려면 먼저 해당 브랜치를 체크아웃하세요. 기본적으로 클라우드 세션은 모든 CI 실패 및 검토 댓글을 수정하도록 지시받습니다. 프롬프트를 전달하여 다른 지침을 제공합니다. 예를 들어 `/autofix-pr only fix lint and type errors`. `gh` CLI 및 [Claude Code on the web](/ko/claude-code-on-the-web)에 대한 액세스가 필요합니다 |55| `/autofix-pr [prompt]` | 현재 브랜치의 PR을 감시하고 CI가 실패하거나 검토자가 댓글을 남길 때 수정 사항을 푸시하는 [Claude Code on the web](/ko/claude-code-on-the-web#auto-fix-pull-requests) 세션을 생성합니다. `gh pr view`를 사용하여 체크아웃된 브랜치에서 열린 PR을 감지합니다. 다른 PR을 감시하려면 먼저 해당 브랜치를 체크아웃하세요. 기본적으로 클라우드 세션은 모든 CI 실패 및 검토 댓글을 수정하도록 지시받습니다. 프롬프트를 전달하여 다른 지침을 제공합니다. 예를 들어 `/autofix-pr only fix lint and type errors`. `gh` CLI 및 [Claude Code on the web](/ko/claude-code-on-the-web)에 대한 액세스가 필요합니다 |

56| `/background [prompt]` | 현재 세션을 [background agent](/ko/agent-view)로 분리하여 실행하고 이 터미널을 해제합니다. 분리하기 전에 한 가지 더 지침을 보내려면 프롬프트를 전달합니다. `claude agents`로 세션을 모니터링합니다. 별칭: `/bg` |56| `/background [prompt]` | 현재 세션을 [background agent](/ko/agent-view)로 분리하여 실행하고 이 터미널을 해제합니다. 분리하기 전에 한 가지 더 지침을 보내려면 프롬프트를 전달합니다. `claude agents`로 세션을 모니터링합니다. 별칭: `/bg` |

57| `/batch <instruction>` | **[Skill](/ko/skills#bundled-skills).** 코드베이스 전체에서 대규모 변경 사항을 병렬로 조율합니다. 코드베이스를 연구하고, 작업을 5\~30개의 독립적인 단위로 분해하고, 계획을 제시합니다. 승인되면 격리된 [git worktree](/ko/worktrees)에서 단위당 하나의 [background subagent](/ko/sub-agents#run-subagents-in-foreground-or-background)를 생성합니다. 각 subagent는 해당 단위를 구현하고, 테스트를 실행하고, pull request를 엽니다. git 리포지토리가 필요합니다. 예: `/batch migrate src/ from Solid to React` |57| `/batch <instruction>` | **[Skill](/ko/skills#bundled-skills).** 코드베이스 전체에서 대규모 변경 사항을 병렬로 조율합니다. 코드베이스를 연구하고, 작업을 5\~30개의 독립적인 단위로 분해하고, 계획을 제시합니다. 승인되면 격리된 [git worktree](/ko/worktrees)에서 단위당 하나의 [background subagent](/ko/sub-agents#run-subagents-in-foreground-or-background)를 생성합니다. 각 subagent는 해당 단위를 구현하고, 테스트를 실행하고, pull request를 엽니다. git 리포지토리가 필요합니다. 예: `/batch migrate src/ from Solid to React` |

68| `/context [all]` | 현재 컨텍스트 사용량을 색상 그리드로 시각화합니다. 컨텍스트 집약적 도구, 메모리 부풀림 및 용량 경고에 대한 최적화 제안을 표시합니다. [fullscreen mode](/ko/fullscreen)에서는 항목별 분석이 그리드를 표시하기 위해 축소됩니다. `all`을 전달하여 확장합니다 |68| `/context [all]` | 현재 컨텍스트 사용량을 색상 그리드로 시각화합니다. 컨텍스트 집약적 도구, 메모리 부풀림 및 용량 경고에 대한 최적화 제안을 표시합니다. [fullscreen mode](/ko/fullscreen)에서는 항목별 분석이 그리드를 표시하기 위해 축소됩니다. `all`을 전달하여 확장합니다 |

69| `/copy [N]` | 마지막 어시스턴트 응답을 클립보드에 복사합니다. 숫자 `N`을 전달하여 N번째 최신 응답을 복사합니다: `/copy 2`는 두 번째 마지막 응답을 복사합니다. 코드 블록이 있을 때는 개별 블록 또는 전체 응답을 선택할 수 있는 대화형 선택기를 표시합니다. 선택기에서 `w`를 누르면 클립보드 대신 파일에 선택 항목을 작성하며, 이는 SSH를 통해 유용합니다 |69| `/copy [N]` | 마지막 어시스턴트 응답을 클립보드에 복사합니다. 숫자 `N`을 전달하여 N번째 최신 응답을 복사합니다: `/copy 2`는 두 번째 마지막 응답을 복사합니다. 코드 블록이 있을 때는 개별 블록 또는 전체 응답을 선택할 수 있는 대화형 선택기를 표시합니다. 선택기에서 `w`를 누르면 클립보드 대신 파일에 선택 항목을 작성하며, 이는 SSH를 통해 유용합니다 |

71| `/dataviz [request]` | **[Skill](/ko/skills#bundled-skills).** 차트, 그래프 및 대시보드에 대한 디자인 지침입니다. Claude는 데이터에 대한 차트 형식을 선택하고, 역할별로 색상을 할당하고, 번들 스크립트를 사용하여 색맹 안전성 및 대비에 대한 팔레트를 검증하고, 마크, 상호 작용 및 접근성 규칙을 적용합니다. 자신의 팔레트로 바꿀 수 있는 브랜드 중립 자리 표시자 팔레트를 사용합니다. {/* min-version: 2.1.198 */}Claude Code v2.1.198 이상이 필요합니다 |

71| `/debug [description]` | **[Skill](/ko/skills#bundled-skills).** 현재 세션에 대해 디버그 로깅을 활성화하고 세션 디버그 로그를 읽어 문제를 해결합니다. 디버그 로깅은 `claude --debug`로 시작하지 않는 한 기본적으로 꺼져 있으므로, 세션 중간에 `/debug`를 실행하면 그 시점부터 로그 캡처를 시작합니다. 선택적으로 분석에 초점을 맞추기 위해 문제를 설명합니다 |72| `/debug [description]` | **[Skill](/ko/skills#bundled-skills).** 현재 세션에 대해 디버그 로깅을 활성화하고 세션 디버그 로그를 읽어 문제를 해결합니다. 디버그 로깅은 `claude --debug`로 시작하지 않는 한 기본적으로 꺼져 있으므로, 세션 중간에 `/debug`를 실행하면 그 시점부터 로그 캡처를 시작합니다. 선택적으로 분석에 초점을 맞추기 위해 문제를 설명합니다 |

72| `/deep-research <question>` | **[Workflow](/ko/workflows#bundled-workflows).** 질문에 대한 웹 검색을 펼치고, 소스를 가져와 교차 검증하고, 인용된 보고서를 종합합니다 |73| `/deep-research <question>` | **[Workflow](/ko/workflows#bundled-workflows).** 질문에 대한 웹 검색을 펼치고, 소스를 가져와 교차 검증하고, 인용된 보고서를 종합합니다 |

74| `/design-sync [hint]` | **[Skill](/ko/skills#bundled-skills).** 리포지토리의 React design system을 변환하고 [Claude Design](https://claude.ai/design)에 업로드하여 생성하는 디자인이 실제 구성 요소를 사용하도록 합니다. 선택적으로 design system의 이름을 지정합니다. 예를 들어 `/design-sync Acme DS`. 첫 번째 동기화는 모든 구성 요소를 확인하며 큰 리포지토리에서는 몇 시간이 걸릴 수 있습니다. Anthropic API에서 사용 가능합니다. Amazon Bedrock, Google Cloud의 Agent Platform 및 Microsoft Foundry에서는 기본 도구가 claude.ai에 도달할 수 없으므로 명령어를 사용할 수 없습니다 |75| `/design-sync [hint]` | **[Skill](/ko/skills#bundled-skills).** 리포지토리의 React design system을 변환하고 [Claude Design](https://claude.ai/design)에 업로드하여 생성하는 디자인이 실제 구성 요소를 사용하도록 합니다. 선택적으로 design system의 이름을 지정합니다. 예를 들어 `/design-sync Acme DS`. 첫 번째 동기화는 모든 구성 요소를 확인하며 큰 리포지토리에서는 몇 시간이 걸릴 수 있습니다. Anthropic API에서 사용 가능합니다. Amazon Bedrock, Google Cloud의 Agent Platform 및 Microsoft Foundry에서는 기본 도구가 claude.ai에 도달할 수 없으므로 명령어를 사용할 수 없습니다 |

76| `/diff` | 커밋되지 않은 변경 사항과 턴별 diff를 표시하는 대화형 diff 뷰어를 엽니다. 왼쪽/오른쪽 화살표를 사용하여 현재 git diff와 개별 Claude 턴 사이를 전환하고, 위/아래를 사용하여 파일을 탐색합니다 |77| `/diff` | 커밋되지 않은 변경 사항과 턴별 diff를 표시하는 대화형 diff 뷰어를 엽니다. 왼쪽/오른쪽 화살표를 사용하여 현재 git diff와 개별 Claude 턴 사이를 전환하고, 위/아래를 사용하여 파일을 탐색합니다. {/* min-version: 2.1.198 */}v2.1.198부터 열린 뷰어는 또한 리포지토리의 git 상태가 다른 터미널의 브랜치 전환 또는 커밋과 같이 세션 외부에서 변경될 때 자동으로 새로 고쳐집니다 |

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

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

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

84| `/focus` | 포커스 뷰를 전환합니다. 마지막 프롬프트, 편집 diffstats가 있는 한 줄 도구 호출 요약 및 최종 응답만 표시합니다. 선택 항목은 세션 전체에서 유지됩니다. 설정에서 [`viewMode`](/ko/settings#available-settings)를 설정하여 재정의할 수 있습니다. [fullscreen rendering](/ko/fullscreen)에서만 사용 가능합니다 |85| `/focus` | 포커스 뷰를 전환합니다. 마지막 프롬프트, 편집 diffstats가 있는 한 줄 도구 호출 요약 및 최종 응답만 표시합니다. {/* min-version: 2.1.198 */}v2.1.198부터 도구 호출 요약은 또한 턴에서 시작된 subagents의 개수를 세고 완료된 백그라운드 작업 알림을 단일 개수로 축소합니다. 선택 항목은 세션 전체에서 유지됩니다. 설정에서 [`viewMode`](/ko/settings#available-settings)를 설정하여 재정의할 수 있습니다. [fullscreen rendering](/ko/fullscreen)에서만 사용 가능합니다 |

85| `/fork <directive>` | {/* min-version: 2.1.161 */}[forked subagent](/ko/sub-agents#fork-the-current-conversation)를 생성합니다. 이는 전체 대화를 상속하고 지시문에서 작업하는 백그라운드 subagent이며, 당신은 계속 진행합니다. 그 결과는 완료되면 당신의 대화로 돌아옵니다. 대화의 복사본으로 자신이 전환하려면 `/branch`를 사용하세요. v2.1.161 이전에는 `/fork`가 `/branch`의 별칭입니다 |86| `/fork <directive>` | {/* min-version: 2.1.161 */}[forked subagent](/ko/sub-agents#fork-the-current-conversation)를 생성합니다. 이는 전체 대화를 상속하고 지시문에서 작업하는 백그라운드 subagent이며, 당신은 계속 진행합니다. 그 결과는 완료되면 당신의 대화로 돌아옵니다. 대화의 복사본으로 자신이 전환하려면 `/branch`를 사용하세요. v2.1.161 이전에는 `/fork`가 `/branch`의 별칭입니다 |

86| `/goal [condition\|clear]` | [goal](/ko/goal)을 설정합니다. Claude는 조건이 충족될 때까지 여러 턴에 걸쳐 계속 작업합니다. 인수 없이 현재 또는 가장 최근에 달성한 goal을 표시합니다. `clear`, `stop`, `off`, `reset`, `none` 또는 `cancel`은 활성 goal을 조기에 제거합니다 |87| `/goal [condition\|clear]` | [goal](/ko/goal)을 설정합니다. Claude는 조건이 충족될 때까지 여러 턴에 걸쳐 계속 작업합니다. 인수 없이 현재 또는 가장 최근에 달성한 goal을 표시합니다. `clear`, `stop`, `off`, `reset`, `none` 또는 `cancel`은 활성 goal을 조기에 제거합니다 |

87| `/heapdump` | JavaScript 힙 스냅샷 및 메모리 분석을 `~/Desktop`에 작성하거나, Desktop 폴더가 없는 Linux의 경우 홈 디렉토리에 작성하여 높은 메모리 사용량을 진단합니다. [troubleshooting](/ko/troubleshooting#high-cpu-or-memory-usage)을 참조하세요 |88| `/heapdump` | JavaScript 힙 스냅샷 및 메모리 분석을 `~/Desktop`에 작성하거나, Desktop 폴더가 없는 Linux의 경우 홈 디렉토리에 작성하여 높은 메모리 사용량을 진단합니다. [troubleshooting](/ko/troubleshooting#high-cpu-or-memory-usage)을 참조하세요 |

127| `/setup-bedrock` | [Amazon Bedrock](/ko/amazon-bedrock) 인증, 지역 및 모델 핀을 대화형 마법사를 통해 구성합니다. `CLAUDE_CODE_USE_BEDROCK=1`이 설정되어 있을 때만 표시됩니다. 처음 Bedrock을 사용하는 사용자는 로그인 화면에서도 이 마법사에 액세스할 수 있습니다 |128| `/setup-bedrock` | [Amazon Bedrock](/ko/amazon-bedrock) 인증, 지역 및 모델 핀을 대화형 마법사를 통해 구성합니다. `CLAUDE_CODE_USE_BEDROCK=1`이 설정되어 있을 때만 표시됩니다. 처음 Bedrock을 사용하는 사용자는 로그인 화면에서도 이 마법사에 액세스할 수 있습니다 |

128| `/setup-vertex` | [Google Vertex AI](/ko/google-vertex-ai) 인증, 프로젝트, 지역 및 모델 핀을 대화형 마법사를 통해 구성합니다. `CLAUDE_CODE_USE_VERTEX=1`이 설정되어 있을 때만 표시됩니다. 처음 Vertex AI를 사용하는 사용자는 로그인 화면에서도 이 마법사에 액세스할 수 있습니다 |129| `/setup-vertex` | [Google Vertex AI](/ko/google-vertex-ai) 인증, 프로젝트, 지역 및 모델 핀을 대화형 마법사를 통해 구성합니다. `CLAUDE_CODE_USE_VERTEX=1`이 설정되어 있을 때만 표시됩니다. 처음 Vertex AI를 사용하는 사용자는 로그인 화면에서도 이 마법사에 액세스할 수 있습니다 |

129| `/simplify [target]` | {/* min-version: 2.1.154 */}}**[Skill](/ko/skills#bundled-skills).** 변경된 코드를 정리 기회에 대해 검토하고 수정 사항을 적용합니다. 4개의 검토 [agents](/ko/sub-agents)가 병렬로 실행되어 기존 헬퍼의 재사용, 단순화, 효율성 및 변경이 추상화의 올바른 수준에 있는지 여부를 다룹니다. v2.1.154부터 검토는 정확성 버그를 찾지 않습니다. 버그를 찾으려면 `/code-review`를 사용하세요. 이전 버전에서 `/simplify`는 `/code-review --fix`와 동일합니다. 특정 대상을 검토하려면 경로 또는 PR 참조를 전달합니다 |130| `/simplify [target]` | {/* min-version: 2.1.154 */}}**[Skill](/ko/skills#bundled-skills).** 변경된 코드를 정리 기회에 대해 검토하고 수정 사항을 적용합니다. 4개의 검토 [agents](/ko/sub-agents)가 병렬로 실행되어 기존 헬퍼의 재사용, 단순화, 효율성 및 변경이 추상화의 올바른 수준에 있는지 여부를 다룹니다. v2.1.154부터 검토는 정확성 버그를 찾지 않습니다. 버그를 찾으려면 `/code-review`를 사용하세요. 이전 버전에서 `/simplify`는 `/code-review --fix`와 동일합니다. 특정 대상을 검토하려면 경로 또는 PR 참조를 전달합니다 |

130| `/skills` | 사용 가능한 [skills](/ko/skills)를 나열합니다. `t`를 눌러 토큰 수로 정렬합니다. `Space`를 눌러 [Claude 또는 `/` 메뉴에서 skill을 숨기고](/ko/skills#override-skill-visibility-from-settings), `Enter`를 눌러 저장합니다 |131| `/skills` | 사용 가능한 [skills](/ko/skills)를 나열합니다. {/* min-version: 2.1.121 */}}v2.1.121부터 입력하여 이름으로 목록을 필터링합니다. `t`를 눌러 토큰 수로 정렬합니다. `Space`를 눌러 [Claude 또는 `/` 메뉴에서 skill의 가시성을 순환](/ko/skills#override-skill-visibility-from-settings)한 다음 `Enter`를 눌러 저장합니다 |

context-window.md +1 −1

Details

1587 압축 후 유지되는 것1587 압축 후 유지되는 것

1588</h2>1588</h2>

1589 1589

1590긴 세션이 압축될 때, Claude Code는 대화 기록을 요약하여 컨텍스트 윈도우에 맞춥니다. 사용자의 지시사항에 어떤 일이 발생하는지는 로드된 방식에 따라 달라집니다:1590긴 세션이 압축될 때, Claude Code는 대화 기록을 요약하여 컨텍스트 윈도우에 맞춥니다. {/* min-version: 2.1.198 */}v2.1.198부터는 요약 요청이 세션의 [확장 사고](/ko/model-config#extended-thinking) 구성을 상속하므로, 세션에서 사고가 활성화되어 있을 때는 사고를 활성화하여 추론하고 그렇지 않으면 비활성화된 상태로 유지됩니다. 사고는 요약이 생성되는 방식에만 영향을 미치며, 이후 세션 설정은 변경되지 않습니다. 사용자의 지시사항에 어떤 일이 발생하는지는 로드된 방식에 따라 달라집니다:

1591 1591

1592| 메커니즘 | 압축 후 |1592| 메커니즘 | 압축 후 |

1593| :---------------------------- | :------------------------------------------------------- |1593| :---------------------------- | :------------------------------------------------------- |

costs.md +3 −3

Details

107* **작업 간 지우기**: 관련 없는 작업으로 전환할 때 `/clear`를 사용하여 새로 시작하십시오. 오래된 컨텍스트는 이후의 모든 메시지에서 토큰을 낭비합니다. 지우기 전에 `/rename`을 사용하여 나중에 세션을 쉽게 찾을 수 있도록 한 다음, `/resume`을 사용하여 돌아가십시오.107* **작업 간 지우기**: 관련 없는 작업으로 전환할 때 `/clear`를 사용하여 새로 시작하십시오. 오래된 컨텍스트는 이후의 모든 메시지에서 토큰을 낭비합니다. 지우기 전에 `/rename`을 사용하여 나중에 세션을 쉽게 찾을 수 있도록 한 다음, `/resume`을 사용하여 돌아가십시오.

108* **사용자 정의 compaction 지침 추가**: `/compact Focus on code samples and API usage`는 Claude에게 요약 중에 보존할 내용을 알려줍니다.108* **사용자 정의 compaction 지침 추가**: `/compact Focus on code samples and API usage`는 Claude에게 요약 중에 보존할 내용을 알려줍니다.

109 109

110CLAUDE.md에서 compaction 동작을 사용자 정의할 수도 있습니다:110프로젝트의 루트에 있는 CLAUDE.md 파일에서 compaction 동작을 사용자 정의할 수도 있습니다:

111 111

112```markdown theme={null}112```markdown theme={null}

113# Compact instructions113# Compact instructions

170 </Tab>170 </Tab>

171 171

172 <Tab title="filter-test-output.sh">172 <Tab title="filter-test-output.sh">

173 hook은 이 스크립트를 호출하며, 이는 명령이 테스트 러너인지 확인하고 실패만 표시하도록 수정합니다:173 hook은 이 스크립트를 호출합니다. `mkdir -p ~/.claude/hooks`로 폴더를 만들고, 아래 스크립트를 `~/.claude/hooks/filter-test-output.sh`로 저장한 다음, `chmod +x ~/.claude/hooks/filter-test-output.sh`로 실행 가능하게 만드십시오. 명령이 테스트 러너인지 확인하고 실패만 표시하도록 수정합니다:

174 174

175 ```bash theme={null}175 ```bash theme={null}

176 #!/bin/bash176 #!/bin/bash

198 확장 사고 조정198 확장 사고 조정

199</h3>199</h3>

200 200

201확장 사고는 기본적으로 활성화되어 있습니다. 복잡한 계획 및 추론 작업의 성능을 크게 향상시키기 때문입니다. 사고 토큰은 출력 토큰으로 청구되며, 기본 예산은 모델에 따라 수만 개의 토큰이 될 수 있습니다. 깊은 추론이 필요하지 않은 더 간단한 작업의 경우, `/effort`를 사용하거나 `/model`에서 [노력 수준](/ko/model-config#adjust-effort-level)을 낮추거나, `/config`에서 사고를 비활성화하거나, [고정 사고 예산](/ko/model-config#adaptive-reasoning-and-fixed-thinking-budgets)이 있는 모델에서 `MAX_THINKING_TOKENS=8000`으로 예산을 낮춤으로써 비용을 줄일 수 있습니다. 적응형 추론 모델은 0이 아닌 예산을 무시하므로 대신 노력 수준을 사용하십시오. Fable 5에서는 사고 비활성화를 사용할 수 없으며, 항상 확장 사고를 사용합니다.201확장 사고는 기본적으로 활성화되어 있습니다. 복잡한 계획 및 추론 작업의 성능을 크게 향상시키기 때문입니다. 사고 토큰은 출력 토큰으로 청구되며, 기본 예산은 모델에 따라 수만 개의 토큰이 될 수 있습니다. 깊은 추론이 필요하지 않은 더 간단한 작업의 경우, `/effort`를 사용하거나 `/model`에서 [노력 수준](/ko/model-config#adjust-effort-level)을 낮추거나, `/config`에서 사고를 비활성화하거나, [고정 사고 예산](/ko/model-config#adaptive-reasoning-and-fixed-thinking-budgets)이 있는 모델에서 `MAX_THINKING_TOKENS` [환경 변수](/ko/env-vars)를 설정하여 예산을 낮춤으로써(예: `MAX_THINKING_TOKENS=8000`) 비용을 줄일 수 있습니다. 적응형 추론 모델은 0이 아닌 예산을 무시하므로 대신 노력 수준을 사용하십시오. Fable 5에서는 사고 비활성화를 사용할 수 없으며, 항상 확장 사고를 사용합니다.

202 202

203<h3 id="delegate-verbose-operations-to-subagents">203<h3 id="delegate-verbose-operations-to-subagents">

204 자세한 작업을 subagents에 위임204 자세한 작업을 subagents에 위임

debug-your-config.md +1 −2

Details

14 컨텍스트에 로드된 항목 확인14 컨텍스트에 로드된 항목 확인

15</h2>15</h2>

16 16

17`/context` 명령은 현재 세션의 컨텍스트 윈도우를 차지하는 모든 항목을 시스템 프롬프트, 메모리 파일, 스킬, MCP 도구 및 대화 메시지로 분류하여 표시합니다. 먼저 이를 실행하여 `CLAUDE.md`, 규칙 또는 스킬 설명이 실제로 존재하는지 확인합니다.17`/context` 명령은 현재 세션의 컨텍스트 윈도우를 차지하는 모든 항목을 시스템 프롬프트, 메모리 파일, 스킬, 사용자 정의 서브에이전트(로드된 소스 포함), MCP 도구 및 대화 메시지로 분류하여 표시합니다. 먼저 이를 실행하여 `CLAUDE.md`, 규칙 또는 스킬 설명이 실제로 존재하는지 확인합니다.

18 18

19특정 카테고리에 대한 세부 정보는 전용 명령으로 팔로우업합니다:19특정 카테고리에 대한 세부 정보는 전용 명령으로 팔로우업합니다:

20 20

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

23| `/memory` | 로드된 `CLAUDE.md` 및 규칙 파일, 자동 메모리 항목 |23| `/memory` | 로드된 `CLAUDE.md` 및 규칙 파일, 자동 메모리 항목 |

~~25| `/agents` | 구성된 서브에이전트 및 해당 설정 |~~

26| `/hooks` | 활성 훅 구성 |25| `/hooks` | 활성 훅 구성 |

27| `/mcp` | 연결된 MCP 서버 및 해당 상태 |26| `/mcp` | 연결된 MCP 서버 및 해당 상태 |

28| `/permissions` | 현재 적용 중인 허용 및 거부 규칙 |27| `/permissions` | 현재 적용 중인 허용 및 거부 규칙 |

desktop.md +1 −1

Details

829* **Linux (베타)**: 컴퓨터 사용은 아직 Linux 데스크톱 앱에서 사용할 수 없습니다. [Linux에서 Claude Desktop](/ko/desktop-linux)을 참조하세요.829* **Linux (베타)**: 컴퓨터 사용은 아직 Linux 데스크톱 앱에서 사용할 수 없습니다. [Linux에서 Claude Desktop](/ko/desktop-linux)을 참조하세요.

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

831* **Agent teams**: 서로 메시지를 주고받는 병렬 Claude Code 세션은 [CLI](/ko/agent-teams)에서 사용 가능하며 Desktop에서는 사용할 수 없습니다. 한 세션 내에서 다중 에이전트 작업의 경우 [동적 워크플로우](/ko/workflows)를 사용합니다. 이는 Desktop에서 실행됩니다.831* **Agent teams**: 서로 메시지를 주고받는 병렬 Claude Code 세션은 [CLI](/ko/agent-teams)에서 사용 가능하며 Desktop에서는 사용할 수 없습니다. 한 세션 내에서 다중 에이전트 작업의 경우 [동적 워크플로우](/ko/workflows)를 사용합니다. 이는 Desktop에서 실행됩니다.

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

833 833

834<h2 id="troubleshooting">834<h2 id="troubleshooting">

835 문제 해결835 문제 해결

env-vars.md +9 −5

Details

146| `CCR_FORCE_BUNDLE` | GitHub 액세스가 가능한 경우에도 [`claude --remote`](/ko/claude-code-on-the-web#send-local-repositories-without-github)가 로컬 리포지토리를 번들로 제공하고 업로드하도록 강제하려면 `1`로 설정합니다. |146| `CCR_FORCE_BUNDLE` | GitHub 액세스가 가능한 경우에도 [`claude --remote`](/ko/claude-code-on-the-web#send-local-repositories-without-github)가 로컬 리포지토리를 번들로 제공하고 업로드하도록 강제하려면 `1`로 설정합니다. |

147| `CLAUDECODE` | Claude Code가 생성하는 subprocess(Bash 및 PowerShell 도구, tmux 세션, [훅](/ko/hooks) 명령, [상태 줄](/ko/statusline) 명령, stdio [MCP 서버](/ko/mcp) subprocess)에서 `1`로 설정됩니다. IDE 확장도 통합 터미널에서 이를 설정합니다. Claude Code가 생성한 subprocess 내에서 스크립트가 실행 중인지 감지하는 데 사용합니다. 현재 프로세스가 도구 호출 또는 훅에 의해 직접 생성되었는지, 아니면 Claude Code가 시작한 stdio [MCP 서버](/ko/mcp) 내부인지 확인하려면 `CLAUDE_CODE_CHILD_SESSION`을 대신 사용합니다. |147| `CLAUDECODE` | Claude Code가 생성하는 subprocess(Bash 및 PowerShell 도구, tmux 세션, [훅](/ko/hooks) 명령, [상태 줄](/ko/statusline) 명령, stdio [MCP 서버](/ko/mcp) subprocess)에서 `1`로 설정됩니다. IDE 확장도 통합 터미널에서 이를 설정합니다. Claude Code가 생성한 subprocess 내에서 스크립트가 실행 중인지 감지하는 데 사용합니다. 현재 프로세스가 도구 호출 또는 훅에 의해 직접 생성되었는지, 아니면 Claude Code가 시작한 stdio [MCP 서버](/ko/mcp) 내부인지 확인하려면 `CLAUDE_CODE_CHILD_SESSION`을 대신 사용합니다. |

148| `CLAUDE_AFK_COUNTDOWN_MS` | {/* min-version: 2.1.198 */}자동 계속 전에 응답하지 않은 `AskUserQuestion` 대화 상자에 화면상 카운트다운이 나타나기 전의 밀리초입니다. 기본값 `20000`(20초). `CLAUDE_AFK_TIMEOUT_MS` 참조. Claude Code v2.1.198 이상이 필요합니다. |

149| `CLAUDE_AFK_TIMEOUT_MS` | {/* min-version: 2.1.198 */}응답하지 않은 [`AskUserQuestion`](/ko/tools-reference) 대화 상자가 자동으로 계속되기 전의 유휴 시간(밀리초)입니다. 기본값 `60000`(60초). 자리를 비웠을 때 질문을 열어 두려면 `86400000`(24시간)과 같은 큰 값을 설정합니다. `0`으로 설정해도 타임아웃이 꺼지지 않습니다. 대화 상자가 즉시 닫힙니다. Claude Code v2.1.198 이상이 필요합니다. |

148| `CLAUDE_AGENT_SDK_DISABLE_BUILTIN_AGENTS` | 모든 기본 제공 [subagent](/ko/sub-agents) 유형(예: Explore 및 Plan)을 비활성화하려면 `1`로 설정합니다. 비대화형 모드(`-p` 플래그)에만 적용됩니다. SDK 사용자가 백지 상태를 원할 때 유용합니다. |150| `CLAUDE_AGENT_SDK_DISABLE_BUILTIN_AGENTS` | 모든 기본 제공 [subagent](/ko/sub-agents) 유형(예: Explore 및 Plan)을 비활성화하려면 `1`로 설정합니다. 비대화형 모드(`-p` 플래그)에만 적용됩니다. SDK 사용자가 백지 상태를 원할 때 유용합니다. |

149| `CLAUDE_AGENT_SDK_MCP_NO_PREFIX` | SDK에서 생성한 MCP 서버의 도구 이름에서 `mcp__<server>__` 접두사를 건너뛰려면 `1`로 설정합니다. 도구는 원래 이름을 사용합니다. SDK 사용만 해당 |151| `CLAUDE_AGENT_SDK_MCP_NO_PREFIX` | SDK에서 생성한 MCP 서버의 도구 이름에서 `mcp__<server>__` 접두사를 건너뛰려면 `1`로 설정합니다. 도구는 원래 이름을 사용합니다. SDK 사용만 해당 |

150| `CLAUDE_ASYNC_AGENT_STALL_TIMEOUT_MS` | 백그라운드 subagent의 정체 타임아웃(밀리초). 기본값 `600000`(10분). 타이머는 각 스트리밍 진행 이벤트에서 재설정됩니다. 윈도우 내에 진행이 도착하지 않으면 subagent가 중단되고 작업이 실패로 표시되며 부분 결과가 부모에게 표시됩니다. |152| `CLAUDE_ASYNC_AGENT_STALL_TIMEOUT_MS` | 백그라운드 subagent의 정체 타임아웃(밀리초). 기본값 `600000`(10분). 타이머는 각 스트리밍 진행 이벤트에서 재설정됩니다. 윈도우 내에 진행이 도착하지 않으면 subagent가 중단되고 작업이 실패로 표시되며 부분 결과가 부모에게 표시됩니다. |

162| `CLAUDE_CODE_ATTRIBUTION_HEADER` | 시스템 프롬프트의 시작 부분에서 속성 블록(클라이언트 버전 및 프롬프트 지문)을 생략하려면 `0`으로 설정합니다. 비활성화하면 [LLM 게이트웨이](/ko/llm-gateway)를 통해 라우팅할 때 프롬프트 캐시 히트율이 향상됩니다. Anthropic API 캐싱은 영향을 받지 않습니다. |164| `CLAUDE_CODE_ATTRIBUTION_HEADER` | 시스템 프롬프트의 시작 부분에서 속성 블록(클라이언트 버전 및 프롬프트 지문)을 생략하려면 `0`으로 설정합니다. 비활성화하면 [LLM 게이트웨이](/ko/llm-gateway)를 통해 라우팅할 때 프롬프트 캐시 히트율이 향상됩니다. Anthropic API 캐싱은 영향을 받지 않습니다. |

163| `CLAUDE_CODE_AUTO_COMPACT_WINDOW` | 자동 압축 계산에 사용되는 컨텍스트 용량을 토큰 단위로 설정합니다. 기본값은 모델의 컨텍스트 윈도우입니다: 표준 모델의 경우 200K 또는 [확장 컨텍스트](/ko/model-config#extended-context) 모델의 경우 1M입니다. Sonnet 5는 자체 [기본 임계값](/ko/model-config#sonnet-5-context-window)을 가집니다. 1M 모델에서 `500000`과 같은 낮은 값을 사용하여 압축 목적상 윈도우를 500K로 취급합니다. 값은 모델의 실제 컨텍스트 윈도우로 제한됩니다. `CLAUDE_AUTOCOMPACT_PCT_OVERRIDE`는 이 값의 백분율로 적용됩니다. 이 변수를 설정하면 압축 임계값이 상태 줄의 `used_percentage`에서 분리되며, 이는 항상 모델의 전체 컨텍스트 윈도우를 사용합니다. |165| `CLAUDE_CODE_AUTO_COMPACT_WINDOW` | 자동 압축 계산에 사용되는 컨텍스트 용량을 토큰 단위로 설정합니다. 기본값은 모델의 컨텍스트 윈도우입니다: 표준 모델의 경우 200K 또는 [확장 컨텍스트](/ko/model-config#extended-context) 모델의 경우 1M입니다. Sonnet 5는 자체 [기본 임계값](/ko/model-config#sonnet-5-context-window)을 가집니다. 1M 모델에서 `500000`과 같은 낮은 값을 사용하여 압축 목적상 윈도우를 500K로 취급합니다. 값은 모델의 실제 컨텍스트 윈도우로 제한됩니다. `CLAUDE_AUTOCOMPACT_PCT_OVERRIDE`는 이 값의 백분율로 적용됩니다. 이 변수를 설정하면 압축 임계값이 상태 줄의 `used_percentage`에서 분리되며, 이는 항상 모델의 전체 컨텍스트 윈도우를 사용합니다. |

164| `CLAUDE_CODE_AUTO_CONNECT_IDE` | 자동 [IDE 연결](/ko/vs-code)을 재정의합니다. 기본적으로 Claude Code는 지원되는 IDE의 통합 터미널 내에서 실행될 때 자동으로 연결됩니다. 이를 방지하려면 `false`로 설정합니다. tmux가 부모 터미널을 가리는 경우와 같이 자동 감지가 실패할 때 연결을 강제하려면 `true`로 설정합니다. [`autoConnectIde`](/ko/settings#global-config-settings) 전역 구성 설정보다 우선합니다. |166| `CLAUDE_CODE_AUTO_CONNECT_IDE` | 자동 [IDE 연결](/ko/vs-code)을 재정의합니다. 기본적으로 Claude Code는 지원되는 IDE의 통합 터미널 내에서 실행될 때 자동으로 연결됩니다. 이를 방지하려면 `false`로 설정합니다. tmux가 부모 터미널을 가리는 경우와 같이 자동 감지가 실패할 때 연결을 강제하려면 `true`로 설정합니다. [`autoConnectIde`](/ko/settings#global-config-settings) 전역 구성 설정보다 우선합니다. |

167| `CLAUDE_CODE_BRIDGE_SESSION_ID` | {/* min-version: 2.1.199 */}세션에 활성 [Remote Control](/ko/remote-control) 연결이 있는 동안 Bash 도구 및 [훅 명령](/ko/hooks) subprocess에서 자동으로 설정되며, 연결이 끝나면 제거됩니다. 값은 `session_` 형식의 세션 ID이며, 세션의 `claude.ai/code` URL에 나타나는 동일한 식별자이므로 스크립트가 이를 실행한 세션으로 다시 연결할 수 있습니다. Claude Code v2.1.199 이상이 필요합니다. [클라우드 세션](/ko/claude-code-on-the-web)에서는 `CLAUDE_CODE_REMOTE_SESSION_ID`를 대신 읽습니다. |

165| `CLAUDE_CODE_CERT_STORE` | TLS 연결을 위한 CA 인증서 소스의 쉼표로 구분된 목록입니다. `bundled`는 Claude Code와 함께 제공되는 Mozilla CA 세트입니다. `system`은 운영 체제 신뢰 저장소입니다. 기본값은 `bundled,system`입니다. |168| `CLAUDE_CODE_CERT_STORE` | TLS 연결을 위한 CA 인증서 소스의 쉼표로 구분된 목록입니다. `bundled`는 Claude Code와 함께 제공되는 Mozilla CA 세트입니다. `system`은 운영 체제 신뢰 저장소입니다. 기본값은 `bundled,system`입니다. |

166| `CLAUDE_CODE_CHILD_SESSION` | {/* min-version: 2.1.172 */}Bash, PowerShell, Monitor 도구, [훅](/ko/hooks) 명령, [상태 줄](/ko/statusline) 명령을 통해 Claude Code가 생성하는 subprocess에서 `1`로 설정됩니다. stdio [MCP 서버](/ko/mcp) subprocess에는 설정되지 않으며, 이는 장기 실행되고 이를 생성한 세션보다 오래 지속됩니다. `CLAUDECODE`와 달리 이는 Claude Code의 자체 생성 경로에서만 설정되고 IDE 확장에서는 설정되지 않으므로 중첩 세션을 IDE 통합 터미널에서 시작된 최상위 `claude`와 안정적으로 구분합니다. 이 방식으로 시작된 중첩 대화형 `claude` TUI는 `--resume`, `--continue`, 위쪽 화살표 기록, `claude agents` 목록에서 자동으로 제외됩니다. 비대화형 `claude -p` 세션은 여전히 지속됩니다. `CLAUDE_CODE_FORCE_SESSION_PERSISTENCE=1`을 설정하여 이 제외를 재정의합니다. Claude Code v2.1.172 이상이 필요합니다. |169| `CLAUDE_CODE_CHILD_SESSION` | {/* min-version: 2.1.172 */}Bash, PowerShell, Monitor 도구, [훅](/ko/hooks) 명령, [상태 줄](/ko/statusline) 명령을 통해 Claude Code가 생성하는 subprocess에서 `1`로 설정됩니다. stdio [MCP 서버](/ko/mcp) subprocess에는 설정되지 않으며, 이는 장기 실행되고 이를 생성한 세션보다 오래 지속됩니다. `CLAUDECODE`와 달리 이는 Claude Code의 자체 생성 경로에서만 설정되고 IDE 확장에서는 설정되지 않으므로 중첩 세션을 IDE 통합 터미널에서 시작된 최상위 `claude`와 안정적으로 구분합니다. 이 방식으로 시작된 중첩 대화형 `claude` TUI는 `--resume`, `--continue`, 위쪽 화살표 기록, `claude agents` 목록에서 자동으로 제외됩니다. 비대화형 `claude -p` 세션은 여전히 지속됩니다. `CLAUDE_CODE_FORCE_SESSION_PERSISTENCE=1`을 설정하여 이 제외를 재정의합니다. Claude Code v2.1.172 이상이 필요합니다. |

180| `CLAUDE_CODE_DISABLE_AUTO_MEMORY` | [자동 메모리](/ko/memory#auto-memory)를 비활성화하려면 `1`로 설정합니다. `0`으로 설정하여 `--bare` 모드 또는 [`autoMemoryEnabled: false`](/ko/settings#available-settings)가 그렇지 않으면 비활성화할 때에도 자동 메모리를 강제로 켭니다. 비활성화되면 Claude는 자동 메모리 파일을 생성하거나 로드하지 않습니다. |183| `CLAUDE_CODE_DISABLE_AUTO_MEMORY` | [자동 메모리](/ko/memory#auto-memory)를 비활성화하려면 `1`로 설정합니다. `0`으로 설정하여 `--bare` 모드 또는 [`autoMemoryEnabled: false`](/ko/settings#available-settings)가 그렇지 않으면 비활성화할 때에도 자동 메모리를 강제로 켭니다. 비활성화되면 Claude는 자동 메모리 파일을 생성하거나 로드하지 않습니다. |

181| `CLAUDE_CODE_DISABLE_BACKGROUND_TASKS` | Bash 및 subagent 도구의 `run_in_background` 매개변수, 자동 백그라운드 처리, Ctrl+B 단축키를 포함한 모든 백그라운드 작업 기능을 비활성화하려면 `1`로 설정합니다. |184| `CLAUDE_CODE_DISABLE_BACKGROUND_TASKS` | Bash 및 subagent 도구의 `run_in_background` 매개변수, 자동 백그라운드 처리, Ctrl+B 단축키를 포함한 모든 백그라운드 작업 기능을 비활성화하려면 `1`로 설정합니다. |

182| `CLAUDE_CODE_DISABLE_BG_EXIT_HANDOFF` | {/* min-version: 2.1.196 */}[백그라운드 세션](/ko/agent-view)의 실행 중인 백그라운드 셸 명령 및 동적 워크플로우를 [감독자](/ko/agent-view#the-supervisor-process)가 중지, 재시작 또는 해당 세션의 프로세스를 업데이트할 때 중지하려면 `1`로 설정합니다. 대신 다음 프로세스로 전달하는 대신입니다. 이 핸드오프에만 영향을 줍니다: `←` 또는 [`/background`](/ko/agent-view#from-inside-a-session)로 세션을 백그라운드 처리하면 여전히 진행 중인 작업을 수행하고, `CLAUDE_DISABLE_ADOPT`는 둘 다 끕니다. Claude Code v2.1.196 이상이 필요합니다. |185| `CLAUDE_CODE_DISABLE_BG_EXIT_HANDOFF` | {/* min-version: 2.1.196 */}[백그라운드 세션](/ko/agent-view)의 실행 중인 백그라운드 셸 명령, 동적 워크플로우, {/* min-version: 2.1.198 */}v2.1.198부터 백그라운드 subagent를 [감독자](/ko/agent-view#the-supervisor-process)가 중지, 재시작 또는 해당 세션의 프로세스를 업데이트할 때 중지하려면 `1`로 설정합니다. 대신 다음 프로세스로 전달하는 대신입니다. 이 핸드오프에만 영향을 줍니다: `←` 또는 [`/background`](/ko/agent-view#from-inside-a-session)로 세션을 백그라운드 처리하면 여전히 진행 중인 작업을 수행하고, `CLAUDE_DISABLE_ADOPT`는 둘 다 끕니다. Claude Code v2.1.196 이상이 필요합니다. |

183| `CLAUDE_CODE_DISABLE_BG_SHELL_PRESSURE_REAP` | {/* min-version: 2.1.193 */}운영 체제가 메모리 압력을 보고할 때 Claude Code가 [백그라운드 셸 명령](/ko/interactive-mode#background-bash-commands)을 종료하지 않도록 하려면 `1`로 설정합니다. 기본적으로 macOS 및 Linux에서 Claude Code는 세션이 30분 동안 유휴 상태이고 턴 또는 subagent가 실행 중이 아닐 때 메모리 압력 신호에서 주 세션에서 시작된 백그라운드 셸을 종료합니다. Windows에는 메모리 압력 신호가 없으므로 이 변수는 효과가 없습니다. Claude Code v2.1.193 이상이 필요합니다. |186| `CLAUDE_CODE_DISABLE_BG_SHELL_PRESSURE_REAP` | {/* min-version: 2.1.193 */}운영 체제가 메모리 압력을 보고할 때 Claude Code가 [백그라운드 셸 명령](/ko/interactive-mode#background-bash-commands)을 종료하지 않도록 하려면 `1`로 설정합니다. 기본적으로 macOS 및 Linux에서 Claude Code는 세션이 30분 동안 유휴 상태이고 턴 또는 subagent가 실행 중이 아닐 때 메모리 압력 신호에서 주 세션에서 시작된 백그라운드 셸을 종료합니다. Windows에는 메모리 압력 신호가 없으므로 이 변수는 효과가 없습니다. Claude Code v2.1.193 이상이 필요합니다. |

184| `CLAUDE_CODE_DISABLE_BUNDLED_SKILLS` | Claude Code와 함께 제공되는 [skill](/ko/skills) 및 워크플로우를 비활성화하려면 `1`로 설정합니다: 번들 skill 및 워크플로우는 완전히 제거되고, `/init`과 같은 기본 제공 슬래시 명령은 입력 가능하지만 모델에서 숨겨집니다. 플러그인, `.claude/skills/`, `.claude/commands/`의 skill은 영향을 받지 않습니다. [`disableBundledSkills`](/ko/settings#available-settings) 설정과 동일합니다. `0`은 이를 재정의하지 않습니다. |187| `CLAUDE_CODE_DISABLE_BUNDLED_SKILLS` | Claude Code와 함께 제공되는 [skill](/ko/skills) 및 워크플로우를 비활성화하려면 `1`로 설정합니다: 번들 skill 및 워크플로우는 완전히 제거되고, `/init`과 같은 기본 제공 슬래시 명령은 입력 가능하지만 모델에서 숨겨집니다. 플러그인, `.claude/skills/`, `.claude/commands/`의 skill은 영향을 받지 않습니다. [`disableBundledSkills`](/ko/settings#available-settings) 설정과 동일합니다. `0`은 이를 재정의하지 않습니다. |

186| `CLAUDE_CODE_DISABLE_CRON` | [예약된 작업](/ko/scheduled-tasks)을 비활성화하려면 `1`로 설정합니다. `/loop` skill과 cron 도구를 사용할 수 없게 되고 이미 예약된 모든 작업이 중지되며, 세션 중에 이미 실행 중인 작업을 포함한 모든 작업이 실행되지 않습니다. |189| `CLAUDE_CODE_DISABLE_CRON` | [예약된 작업](/ko/scheduled-tasks)을 비활성화하려면 `1`로 설정합니다. `/loop` skill과 cron 도구를 사용할 수 없게 되고 이미 예약된 모든 작업이 중지되며, 세션 중에 이미 실행 중인 작업을 포함한 모든 작업이 실행되지 않습니다. |

187| `CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS` | Anthropic 특정 `anthropic-beta` 요청 헤더 및 베타 도구 스키마 필드(`defer_loading` 및 `eager_input_streaming` 등)를 API 요청에서 제거하려면 `1`로 설정합니다. 프록시 게이트웨이가 "Unexpected value(s) for the `anthropic-beta` header" 또는 "Extra inputs are not permitted"와 같은 오류로 요청을 거부할 때 사용합니다. 표준 필드(`name`, `description`, `input_schema`, `cache_control`)는 유지됩니다. |190| `CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS` | Anthropic 특정 `anthropic-beta` 요청 헤더 및 베타 도구 스키마 필드(`defer_loading` 및 `eager_input_streaming` 등)를 API 요청에서 제거하려면 `1`로 설정합니다. 프록시 게이트웨이가 "Unexpected value(s) for the `anthropic-beta` header" 또는 "Extra inputs are not permitted"와 같은 오류로 요청을 거부할 때 사용합니다. 표준 필드(`name`, `description`, `input_schema`, `cache_control`)는 유지됩니다. |

191| `CLAUDE_CODE_DISABLE_EXPLORE_PLAN_AGENTS` | {/* min-version: 2.1.198 */}기본 제공 [Explore 및 Plan subagent](/ko/sub-agents#built-in-subagents)를 비활성화하려면 `1`로 설정합니다. Claude는 검색 도구 또는 범용 subagent로 탐색하고, [계획 모드](/ko/permission-modes#analyze-before-you-edit-with-plan-mode)는 Explore 및 Plan 에이전트를 시작하는 대신 파일을 직접 읽습니다. Explore 또는 Plan이라는 사용자 정의 subagent는 영향을 받지 않습니다. Agent SDK 또는 비대화형 모드에서 모든 기본 제공 subagent 유형을 제거하려면 `CLAUDE_AGENT_SDK_DISABLE_BUILTIN_AGENTS`를 대신 사용합니다. Claude Code v2.1.198 이상이 필요합니다. |

189| `CLAUDE_CODE_DISABLE_FEEDBACK_SURVEY` | "Claude가 어떻게 하고 있나요?" 세션 품질 설문조사를 비활성화하려면 `1`로 설정합니다. `DISABLE_TELEMETRY`, `DO_NOT_TRACK`, 또는 `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC`이 설정되면 설문조사도 비활성화됩니다. `CLAUDE_CODE_ENABLE_FEEDBACK_SURVEY_FOR_OTEL`이 다시 옵트인하지 않으면 설문조사 샘플 레이트를 설정하려면 [`feedbackSurveyRate`](/ko/settings#available-settings) 설정을 사용합니다. [세션 품질 설문조사](/ko/data-usage#session-quality-surveys) 참조 |193| `CLAUDE_CODE_DISABLE_FEEDBACK_SURVEY` | "Claude가 어떻게 하고 있나요?" 세션 품질 설문조사를 비활성화하려면 `1`로 설정합니다. `DISABLE_TELEMETRY`, `DO_NOT_TRACK`, 또는 `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC`이 설정되면 설문조사도 비활성화됩니다. `CLAUDE_CODE_ENABLE_FEEDBACK_SURVEY_FOR_OTEL`이 다시 옵트인하지 않으면 설문조사 샘플 레이트를 설정하려면 [`feedbackSurveyRate`](/ko/settings#available-settings) 설정을 사용합니다. [세션 품질 설문조사](/ko/data-usage#session-quality-surveys) 참조 |

190| `CLAUDE_CODE_DISABLE_FILE_CHECKPOINTING` | 파일 [체크포인팅](/ko/checkpointing)을 비활성화하려면 `1`로 설정합니다. `/rewind` 명령이 코드 변경 사항을 복원할 수 없습니다. |194| `CLAUDE_CODE_DISABLE_FILE_CHECKPOINTING` | 파일 [체크포인팅](/ko/checkpointing)을 비활성화하려면 `1`로 설정합니다. `/rewind` 명령이 코드 변경 사항을 복원할 수 없습니다. |

231| `CLAUDE_CODE_MAX_CONTEXT_TOKENS` | Claude Code가 활성 모델에 대해 가정하는 컨텍스트 윈도우 크기를 재정의합니다. {/* min-version: 2.1.193 */}v2.1.193부터 Claude Code가 Claude 모델로 인식하는 모델 이름에 대해 직접 적용됩니다. 인식된 Claude 모델의 경우 `DISABLE_COMPACT`도 설정되어 있을 때만 적용됩니다. `ANTHROPIC_BASE_URL`을 통해 이름의 기본 제공 크기와 일치하지 않는 컨텍스트 윈도우를 가진 모델로 라우팅할 때 사용합니다. |235| `CLAUDE_CODE_MAX_CONTEXT_TOKENS` | Claude Code가 활성 모델에 대해 가정하는 컨텍스트 윈도우 크기를 재정의합니다. {/* min-version: 2.1.193 */}v2.1.193부터 Claude Code가 Claude 모델로 인식하는 모델 이름에 대해 직접 적용됩니다. 인식된 Claude 모델의 경우 `DISABLE_COMPACT`도 설정되어 있을 때만 적용됩니다. `ANTHROPIC_BASE_URL`을 통해 이름의 기본 제공 크기와 일치하지 않는 컨텍스트 윈도우를 가진 모델로 라우팅할 때 사용합니다. |

232| `CLAUDE_CODE_MAX_OUTPUT_TOKENS` | 대부분의 요청에 대한 최대 출력 토큰 수를 설정합니다. 기본값 및 상한은 모델에 따라 다릅니다. [최대 출력 토큰](https://platform.claude.com/docs/en/about-claude/models/overview#latest-models-comparison) 참조. 이 값을 증가시키면 [자동 압축](/ko/costs#reduce-token-usage)이 트리거되기 전에 사용 가능한 효과적인 컨텍스트 윈도우가 감소합니다. |236| `CLAUDE_CODE_MAX_OUTPUT_TOKENS` | 대부분의 요청에 대한 최대 출력 토큰 수를 설정합니다. 기본값 및 상한은 모델에 따라 다릅니다. [최대 출력 토큰](https://platform.claude.com/docs/en/about-claude/models/overview#latest-models-comparison) 참조. 이 값을 증가시키면 [자동 압축](/ko/costs#reduce-token-usage)이 트리거되기 전에 사용 가능한 효과적인 컨텍스트 윈도우가 감소합니다. |

233| `CLAUDE_CODE_MAX_RETRIES` | 실패한 API 요청을 재시도할 횟수를 재정의합니다(기본값: 10). {/* min-version: 2.1.186 */}v2.1.186부터 최대 15로 제한됩니다. 더 긴 중단을 기다려야 하는 무인 세션의 경우 `CLAUDE_CODE_RETRY_WATCHDOG`을 대신 설정합니다. |237| `CLAUDE_CODE_MAX_RETRIES` | 실패한 API 요청을 재시도할 횟수를 재정의합니다(기본값: 10). {/* min-version: 2.1.186 */}v2.1.186부터 최대 15로 제한됩니다. {/* min-version: 2.1.199 */}v2.1.199부터 `CLAUDE_CODE_RETRY_WATCHDOG`이 기본값을 올리고 제한을 제거합니다. 더 긴 중단을 기다려야 하는 무인 세션의 경우 `CLAUDE_CODE_RETRY_WATCHDOG`을 대신 설정합니다. |

234| `CLAUDE_CODE_MAX_TOOL_USE_CONCURRENCY` | 병렬로 실행할 수 있는 읽기 전용 도구 및 subagent의 최대 수(기본값: 10). 더 높은 값은 병렬 처리를 증가시키지만 더 많은 리소스를 소비합니다. |238| `CLAUDE_CODE_MAX_TOOL_USE_CONCURRENCY` | 병렬로 실행할 수 있는 읽기 전용 도구 및 subagent의 최대 수(기본값: 10). 더 높은 값은 병렬 처리를 증가시키지만 더 많은 리소스를 소비합니다. |

235| `CLAUDE_CODE_MAX_TURNS` | 명시적 제한이 전달되지 않을 때 에이전트 턴 수를 제한합니다. [`--max-turns`](/ko/cli-reference#cli-flags) 전달과 동일하며, 둘 다 설정되면 우선합니다. 양의 정수가 아닌 값은 제한이 없는 것으로 취급되지 않고 오류와 함께 시작 시 거부됩니다. |239| `CLAUDE_CODE_MAX_TURNS` | 명시적 제한이 전달되지 않을 때 에이전트 턴 수를 제한합니다. [`--max-turns`](/ko/cli-reference#cli-flags) 전달과 동일하며, 둘 다 설정되면 우선합니다. 양의 정수가 아닌 값은 제한이 없는 것으로 취급되지 않고 오류와 함께 시작 시 거부됩니다. |

262| `CLAUDE_CODE_REMOTE_SESSION_ID` | [클라우드 세션](/ko/claude-code-on-the-web)에서 현재 세션의 ID로 자동으로 설정됩니다. 세션 트랜스크립트로 다시 연결하는 링크를 구성하려면 이를 읽습니다. [세션으로 출력 다시 연결](/ko/claude-code-on-the-web#link-output-back-to-the-session) 참조 |266| `CLAUDE_CODE_REMOTE_SESSION_ID` | [클라우드 세션](/ko/claude-code-on-the-web)에서 현재 세션의 ID로 자동으로 설정됩니다. 세션 트랜스크립트로 다시 연결하는 링크를 구성하려면 이를 읽습니다. [세션으로 출력 다시 연결](/ko/claude-code-on-the-web#link-output-back-to-the-session) 참조 |

263| `CLAUDE_CODE_RESUME_INTERRUPTED_TURN` | 이전 세션이 중간에 끝난 경우 자동으로 재개하려면 `1`로 설정합니다. SDK 모드에서 사용되므로 모델이 SDK가 프롬프트를 다시 전송할 필요 없이 계속됩니다. |267| `CLAUDE_CODE_RESUME_INTERRUPTED_TURN` | 이전 세션이 중간에 끝난 경우 자동으로 재개하려면 `1`로 설정합니다. SDK 모드에서 사용되므로 모델이 SDK가 프롬프트를 다시 전송할 필요 없이 계속됩니다. |

264| `CLAUDE_CODE_RESUME_PROMPT` | 세션이 중간에 끝난 후 재개할 때 주입되는 계속 메시지를 재정의합니다. 기본값은 `Continue from where you left off.`입니다. 장시간 실행되는 에이전트의 스폰 스크립트는 이를 더 지시적인 부팅 메시지로 설정할 수 있습니다. 빈 문자열은 기본값을 사용합니다. |268| `CLAUDE_CODE_RESUME_PROMPT` | 세션이 중간에 끝난 후 재개할 때 주입되는 계속 메시지를 재정의합니다. 기본값은 `Continue from where you left off.`입니다. 장시간 실행되는 에이전트의 스폰 스크립트는 이를 더 지시적인 부팅 메시지로 설정할 수 있습니다. 빈 문자열은 기본값을 사용합니다. |

265| `CLAUDE_CODE_RETRY_WATCHDOG` | {/* min-version: 2.1.186 */}평가 하네스, CI 작업 또는 원격 작업자와 같은 무인 세션의 경우 `1`로 설정합니다. `429` 및 `529` 용량 오류를 `CLAUDE_CODE_MAX_RETRIES` 시도 후 실패하는 대신 무한정 재시도합니다. 감시견은 시도 사이에 최대 5분까지 백오프하거나 응답이 속도 제한 재설정 시간을 전달할 때 제한이 재설정될 때까지 대기합니다. 사용량 제한에 도달한 세션은 남은 윈도우를 기다립니다. Claude Code v2.1.186 이상이 필요합니다. |269| `CLAUDE_CODE_RETRY_WATCHDOG` | {{/* min-version: 2.1.186 */}}평가 하네스, CI 작업 또는 원격 작업자와 같은 무인 세션의 경우 `1`로 설정합니다. `429` 및 `529` 용량 오류를 `CLAUDE_CODE_MAX_RETRIES` 시도 후 실패하는 대신 무한정 재시도합니다. 감시견은 시도 사이에 최대 5분까지 백오프하거나 응답이 속도 제한 재설정 시간을 전달할 때 제한이 재설정될 때까지 대기합니다. 사용량 제한에 도달한 세션은 남은 윈도우를 기다립니다. {{/* min-version: 2.1.199 */}}v2.1.199부터 서버 오류, 타임아웃, 끊어진 연결과 같은 다른 일시적 오류에 대한 기본 재시도 횟수를 약 3시간의 백오프인 300으로 올리고 `CLAUDE_CODE_MAX_RETRIES`를 명시적으로 설정하면 15의 제한을 제거합니다. Claude Code v2.1.186 이상이 필요합니다. |

266| `CLAUDE_CODE_SAFE_MODE` | 안전 모드에서 시작하려면 `1`로 설정합니다: CLAUDE.md, skill, 플러그인, 훅, MCP 서버, 사용자 정의 명령 및 에이전트, 출력 스타일, 워크플로우, 사용자 정의 테마, 사용자 정의 키 바인딩, 상태 줄 및 파일 제안 명령, LSP 서버, 자동 메모리는 로드되지 않습니다. 손상된 구성을 문제 해결하기 위해. 관리 설정 정책은 여전히 적용되며, 정책 구성 훅, 상태 줄, 파일 제안 명령을 포함합니다. 관리 플러그인, 관리 skill, 관리 CLAUDE.md, 정책 구성 MCP 서버는 로드되지 않습니다. [`--safe-mode`](/ko/cli-reference#cli-flags) 전달과 동일합니다. 직접 생성된 자식 프로세스는 변수를 상속합니다. |270| `CLAUDE_CODE_SAFE_MODE` | 안전 모드에서 시작하려면 `1`로 설정합니다: CLAUDE.md, skill, 플러그인, 훅, MCP 서버, 사용자 정의 명령 및 에이전트, 출력 스타일, 워크플로우, 사용자 정의 테마, 사용자 정의 키 바인딩, 상태 줄 및 파일 제안 명령, LSP 서버, 자동 메모리는 로드되지 않습니다. 손상된 구성을 문제 해결하기 위해. 관리 설정 정책은 여전히 적용되며, 정책 구성 훅, 상태 줄, 파일 제안 명령을 포함합니다. 관리 플러그인, 관리 skill, 관리 CLAUDE.md, 정책 구성 MCP 서버는 로드되지 않습니다. [`--safe-mode`](/ko/cli-reference#cli-flags) 전달과 동일합니다. 직접 생성된 자식 프로세스는 변수를 상속합니다. |

267| `CLAUDE_CODE_SCRIPT_CAPS` | `CLAUDE_CODE_SUBPROCESS_ENV_SCRUB`이 설정되었을 때 세션당 특정 스크립트를 호출할 수 있는 횟수를 제한하는 JSON 객체입니다. 키는 명령 텍스트에 대해 일치하는 부분 문자열입니다. 값은 정수 호출 제한입니다. 예를 들어 `{"deploy.sh": 2}`는 `deploy.sh`를 최대 2번 호출할 수 있습니다. 일치는 부분 문자열 기반이므로 `./scripts/deploy.sh $(evil)`과 같은 셸 확장 트릭도 여전히 제한에 포함됩니다. `xargs` 또는 `find -exec`을 통한 런타임 팬아웃은 감지되지 않습니다. 이는 심층 방어 제어입니다. |271| `CLAUDE_CODE_SCRIPT_CAPS` | `CLAUDE_CODE_SUBPROCESS_ENV_SCRUB`이 설정되었을 때 세션당 특정 스크립트를 호출할 수 있는 횟수를 제한하는 JSON 객체입니다. 키는 명령 텍스트에 대해 일치하는 부분 문자열입니다. 값은 정수 호출 제한입니다. 예를 들어 `{"deploy.sh": 2}`는 `deploy.sh`를 최대 2번 호출할 수 있습니다. 일치는 부분 문자열 기반이므로 `./scripts/deploy.sh $(evil)`과 같은 셸 확장 트릭도 여전히 제한에 포함됩니다. `xargs` 또는 `find -exec`을 통한 런타임 팬아웃은 감지되지 않습니다. 이는 심층 방어 제어입니다. |

268| `CLAUDE_CODE_SCROLL_SPEED` | [전체 화면 렌더링](/ko/fullscreen#mouse-wheel-scrolling)에서 마우스 휠 스크롤 배수를 설정합니다. 1부터 20까지의 값을 허용합니다. 그리고 `0.5`와 같은 1 미만의 분수 값을 허용하여 터미널의 기본 스크롤 경로에서 가속 트랙패드 및 휠 스크롤을 느리게 합니다. 터미널이 증폭 없이 노치당 하나의 휠 이벤트를 보내는 경우 `vim`과 일치하도록 `3`으로 설정합니다. JetBrains IDE 터미널에서는 무시되며, Claude Code는 자체 스크롤 처리를 사용합니다. |272| `CLAUDE_CODE_SCROLL_SPEED` | [전체 화면 렌더링](/ko/fullscreen#mouse-wheel-scrolling)에서 마우스 휠 스크롤 배수를 설정합니다. 1부터 20까지의 값을 허용합니다. 그리고 `0.5`와 같은 1 미만의 분수 값을 허용하여 터미널의 기본 스크롤 경로에서 가속 트랙패드 및 휠 스크롤을 느리게 합니다. 터미널이 증폭 없이 노치당 하나의 휠 이벤트를 보내는 경우 `vim`과 일치하도록 `3`으로 설정합니다. JetBrains IDE 터미널에서는 무시되며, Claude Code는 자체 스크롤 처리를 사용합니다. |

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

304| `CLAUDE_ENABLE_BYTE_WATCHDOG` | 바이트 수준 스트리밍 유휴 감시견을 강제로 활성화하려면 `1`로 설정하거나, 강제로 비활성화하려면 `0`으로 설정합니다. 설정하지 않으면 감시견은 직접 Anthropic API 및 [Claude Platform on AWS](/ko/claude-platform-on-aws) 연결에 대해 기본적으로 활성화됩니다. 바이트 감시견은 `CLAUDE_STREAM_IDLE_TIMEOUT_MS`로 설정된 기간 동안 와이어에 바이트가 도착하지 않으면 연결을 중단합니다. 최소 5분이며 이벤트 수준 감시견과 독립적입니다. |308| `CLAUDE_ENABLE_BYTE_WATCHDOG` | 바이트 수준 스트리밍 유휴 감시견을 강제로 활성화하려면 `1`로 설정하거나, 강제로 비활성화하려면 `0`으로 설정합니다. 설정하지 않으면 감시견은 직접 Anthropic API 및 [Claude Platform on AWS](/ko/claude-platform-on-aws) 연결에 대해 기본적으로 활성화됩니다. 바이트 감시견은 `CLAUDE_STREAM_IDLE_TIMEOUT_MS`로 설정된 기간 동안 와이어에 바이트가 도착하지 않으면 연결을 중단합니다. 최소 5분이며 이벤트 수준 감시견과 독립적입니다. |

305| `CLAUDE_ENABLE_BYTE_WATCHDOG_BEDROCK` | Amazon Bedrock `vnd.amazon.eventstream` 응답에서 바이트 수준 스트리밍 유휴 감시견을 활성화하려면 `1`로 설정합니다. 기본적으로 꺼져 있습니다. `CLAUDE_STREAM_IDLE_TIMEOUT_MS`로 타임아웃을 구성합니다. |309| `CLAUDE_ENABLE_BYTE_WATCHDOG_BEDROCK` | Amazon Bedrock `vnd.amazon.eventstream` 응답에서 바이트 수준 스트리밍 유휴 감시견을 활성화하려면 `1`로 설정합니다. 기본적으로 꺼져 있습니다. `CLAUDE_STREAM_IDLE_TIMEOUT_MS`로 타임아웃을 구성합니다. |

306| `CLAUDE_ENABLE_STREAM_WATCHDOG` | 이벤트 수준 스트리밍 유휴 감시견을 강제로 활성화하려면 `1`로 설정하거나, 강제로 비활성화하려면 `0`으로 설정합니다. {/* min-version: 2.1.196 */}}설정하지 않으면 감시견은 모든 공급자에 대해 기본적으로 켜져 있습니다. v2.1.196 이전에는 설정하지 않은 기본값이 직접 Anthropic API에서 서버 제어이고 다른 공급자에서는 꺼져 있었습니다. {/* min-version: 2.1.169 */}}v2.1.169부터 직접 Anthropic API 및 Claude Platform on AWS 이외의 공급자도 `API_FORCE_IDLE_TIMEOUT`에 설명된 독립적인 5분 본문 유휴 타임아웃을 가집니다. Bedrock에서는 `CLAUDE_ENABLE_BYTE_WATCHDOG_BEDROCK=1`로 독립적인 바이트 수준 감시견을 활성화할 수도 있습니다. 둘 다 설정하면 함께 실행됩니다. `CLAUDE_STREAM_IDLE_TIMEOUT_MS`로 타임아웃을 구성합니다. |310| `CLAUDE_ENABLE_STREAM_WATCHDOG` | 이벤트 수준 스트리밍 유휴 감시견을 강제로 활성화하려면 `1`로 설정하거나, 강제로 비활성화하려면 `0`으로 설정합니다.{/* min-version: 2.1.196 */}}설정하지 않으면 감시견은 모든 공급자에 대해 기본적으로 켜져 있습니다. v2.1.196 이전에는 설정하지 않은 기본값이 직접 Anthropic API에서 서버 제어이고 다른 공급자에서는 꺼져 있었습니다. {/* min-version: 2.1.169 */}}v2.1.169부터 직접 Anthropic API 및 Claude Platform on AWS 이외의 공급자도 `API_FORCE_IDLE_TIMEOUT`에 설명된 독립적인 5분 본문 유휴 타임아웃을 가집니다. Bedrock에서는 `CLAUDE_ENABLE_BYTE_WATCHDOG_BEDROCK=1`로 독립적인 바이트 수준 감시견을 활성화할 수도 있습니다. 둘 다 설정하면 함께 실행됩니다. `CLAUDE_STREAM_IDLE_TIMEOUT_MS`로 타임아웃을 구성합니다. |

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

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

309| `CLAUDE_STREAM_IDLE_TIMEOUT_MS` | 스트리밍 유휴 감시견이 정체된 연결을 닫기 전의 타임아웃(밀리초). 설정하지 않으면 이벤트 수준 감시견은 기본값 300초이고 바이트 수준 감시견은 직접 Anthropic API 연결에서 기본값 180초입니다(Claude Platform on AWS 및 다른 공급자에서 300초). 설정하지 않은 180초 바이트 감시견 기본값은 별개의 값이며 5분 제한을 받지 않습니다. 설정하지 않으면 이벤트 수준 감시견은 기본값 300초이고 바이트 수준 감시견은 직접 Anthropic API 연결에서 기본값 180초입니다(Claude Platform on AWS 및 다른 공급자에서 300초). 설정하지 않은 180초 바이트 감시견 기본값은 별개의 값이며 5분 제한을 받지 않습니다. `API_FORCE_IDLE_TIMEOUT`에 설명된 본문 유휴 타임아웃은 독립적으로 적용됩니다. Bedrock에서는 `CLAUDE_ENABLE_BYTE_WATCHDOG_BEDROCK=1`일 때도 적용됩니다. |313| `CLAUDE_STREAM_IDLE_TIMEOUT_MS` | 스트리밍 유휴 감시견이 정체된 연결을 닫기 전의 타임아웃(밀리초). 설정하지 않으면 이벤트 수준 감시견은 기본값 300초이고 바이트 수준 감시견은 직접 Anthropic API 연결에서 기본값 180초입니다(Claude Platform on AWS 및 다른 공급자에서 300초). 설정하지 않은 180초 바이트 감시견 기본값은 별개의 값이며 5분 제한을 받지 않습니다. `API_FORCE_IDLE_TIMEOUT`에 설명된 본문 유휴 타임아웃은 독립적으로 적용됩니다. Bedrock에서는 `CLAUDE_ENABLE_BYTE_WATCHDOG_BEDROCK=1`일 때도 적용됩니다. |

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

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

errors.md +174 −26

Details

6 6

7> Claude Code 런타임 오류 메시지를 조회하고 각 오류의 의미와 해결 방법을 확인합니다.7> Claude Code 런타임 오류 메시지를 조회하고 각 오류의 의미와 해결 방법을 확인합니다.

8 8

9이 페이지에는 Claude Code가 표시하는 런타임 오류와 각 오류에서 복구하는 방법, 그리고 오류 없이 응답이 이상해 보일 때 확인할 사항이 나열되어 있습니다. `command not found` 또는 설정 중 TLS 오류와 같은 설치 오류는 [문제 해결](/ko/troubleshoot-install)을 참조하십시오.9이 페이지에는 Claude Code가 표시하는 런타임 오류와 각 오류에서 복구하는 방법, 그리고 오류 없이 응답이 이상해 보일 때 확인할 사항이 나열되어 있습니다. `command not found` 또는 설정 중 TLS 오류와 같은 설치 오류는 [설치 및 로그인 문제 해결](/ko/troubleshoot-install)을 참조하십시오.

10 10

11이러한 오류 및 복구 명령은 CLI, [데스크톱 앱](/ko/desktop), [웹의 Claude Code](/ko/claude-code-on-the-web)에 모두 적용됩니다. 세 가지 모두 동일한 Claude Code CLI를 래핑하기 때문입니다. 표면별 문제는 해당 표면의 페이지에 있는 문제 해결 섹션을 참조하십시오.11이러한 오류 및 복구 명령은 CLI, [데스크톱 앱](/ko/desktop), [웹의 Claude Code](/ko/claude-code-on-the-web)에 모두 적용됩니다. 세 가지 모두 동일한 Claude Code CLI를 래핑하기 때문입니다. 표면별 문제는 해당 표면의 페이지에 있는 문제 해결 섹션을 참조하십시오.

12 12

25| `API Error: 500 Internal server error` | [서버 오류](#api-error-500-internal-server-error) |25| `API Error: 500 Internal server error` | [서버 오류](#api-error-500-internal-server-error) |

26| `API Error: Repeated 529 Overloaded errors` | [서버 오류](#api-error-repeated-529-overloaded-errors) |26| `API Error: Repeated 529 Overloaded errors` | [서버 오류](#api-error-repeated-529-overloaded-errors) |

28| `Server error mid-response. The response above may be incomplete.` | [서버 오류](#the-response-above-may-be-incomplete) |

29| `Connection closed mid-response` / `Response stalled mid-stream` | [서버 오류](#the-response-above-may-be-incomplete) |

28| `<model> is temporarily unavailable, so auto mode cannot determine the safety of...` | [서버 오류](#auto-mode-cannot-determine-the-safety-of-an-action) |30| `<model> is temporarily unavailable, so auto mode cannot determine the safety of...` | [서버 오류](#auto-mode-cannot-determine-the-safety-of-an-action) |

29| `Auto mode could not evaluate this action and is blocking it for safety` | [서버 오류](#auto-mode-cannot-determine-the-safety-of-an-action) |31| `Auto mode could not evaluate this action and is blocking it for safety` | [서버 오류](#auto-mode-cannot-determine-the-safety-of-an-action) |

30| `Auto mode classifier transcript exceeded context window` | [서버 오류](#auto-mode-cannot-determine-the-safety-of-an-action) |32| `Auto mode classifier transcript exceeded context window` | [서버 오류](#auto-mode-cannot-determine-the-safety-of-an-action) |

33| `Agent terminated early due to an API error` | [서버 오류](#agent-terminated-early-due-to-an-api-error) |

31| `You've hit your session limit` / `You've hit your weekly limit` | [사용 제한](#you%E2%80%99ve-hit-your-session-limit) |34| `You've hit your session limit` / `You've hit your weekly limit` | [사용 제한](#you%E2%80%99ve-hit-your-session-limit) |

32| `Usage credits required for 1M context` | [사용 제한](#usage-credits-required-for-1m-context) |35| `Usage credits required for 1M context` | [사용 제한](#usage-credits-required-for-1m-context) |

33| `Server is temporarily limiting requests` | [사용 제한](#server-is-temporarily-limiting-requests) |36| `Server is temporarily limiting requests` | [사용 제한](#server-is-temporarily-limiting-requests) |

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

44| `OAuth token revoked` / `OAuth token has expired` | [인증](#oauth-token-revoked-or-expired) |47| `OAuth token revoked` / `OAuth token has expired` | [인증](#oauth-token-revoked-or-expired) |

45| `does not meet scope requirement user:profile` | [인증](#oauth-scope-requirement) |48| `does not meet scope requirement user:profile` | [인증](#oauth-scope-requirement) |

49| `AWS credentials expired or invalid` | [인증](#aws-credentials-expired-or-invalid) |

50| `AWS authentication failed` | [인증](#aws-authentication-failed) |

46| `Unable to connect to API` | [네트워크](#unable-to-connect-to-api) |51| `Unable to connect to API` | [네트워크](#unable-to-connect-to-api) |

48| `SSL certificate verification failed` | [네트워크](#ssl-certificate-errors) |53| `SSL certificate verification failed` | [네트워크](#ssl-certificate-errors) |

54| `SSL certificate error (...)` during login or startup | [네트워크](#ssl-certificate-errors) |

49| `403` with `x-deny-reason: host_not_allowed` in a cloud or routine session | [네트워크](#host-not-allowed-in-a-cloud-session) |55| `403` with `x-deny-reason: host_not_allowed` in a cloud or routine session | [네트워크](#host-not-allowed-in-a-cloud-session) |

50| `Prompt is too long` | [요청 오류](#prompt-is-too-long) |56| `Prompt is too long` | [요청 오류](#prompt-is-too-long) |

51| `Error during compaction: Conversation too long` | [요청 오류](#error-during-compaction-conversation-too-long) |57| `Error during compaction: Conversation too long` | [요청 오류](#error-during-compaction-conversation-too-long) |

61| `max_tokens must be greater than thinking.budget_tokens` | [요청 오류](#thinking-budget-exceeds-output-limit) |67| `max_tokens must be greater than thinking.budget_tokens` | [요청 오류](#thinking-budget-exceeds-output-limit) |

62| `API Error: 400 due to tool use concurrency issues` | [요청 오류](#tool-use-or-thinking-block-mismatch) |68| `API Error: 400 due to tool use concurrency issues` | [요청 오류](#tool-use-or-thinking-block-mismatch) |

63| `Claude Code is unable to respond to this request, which appears to violate our Usage Policy` | [요청 오류](#usage-policy-refusal) |69| `Claude Code is unable to respond to this request, which appears to violate our Usage Policy` | [요청 오류](#usage-policy-refusal) |

71| Responses seem lower quality than usual | [응답 품질](#responses-seem-lower-quality-than-usual) |

65 72

66<h2 id="automatic-retries">73<h2 id="automatic-retries">

67 자동 재시도74 자동 재시도

68</h2>75</h2>

69 76

70Claude Code는 오류를 표시하기 전에 일시적 오류를 재시도합니다. 서버 오류, 과부하 응답, 요청 시간 초과, 임시 429 스로틀, 끊어진 연결은 모두 지수 백오프를 사용하여 최대 10회 재시도됩니다. 재시도하는 동안 스피너는 `Retrying in Ns · attempt x/y` 카운트다운을 표시합니다.77Claude Code는 오류를 표시하기 전에 일시적 오류를 재시도합니다. 서버 오류, 과부하 응답, 요청 시간 초과, 임시 429 스로틀, 끊어진 연결은 모두 지수 백오프를 사용하여 최대 10회 재시도됩니다. {/* min-version: 2.1.198 */}v2.1.198부터 이는 표시되는 출력이 없기 전에 응답 중간에 끊어지는 연결을 포함합니다. Claude Code는 동일한 백오프로 요청을 다시 발급하고 연결 오류로 중지하는 대신 턴이 계속됩니다. {/* min-version: 2.1.199 */}v2.1.199부터 계획의 할당량 헤더를 전달하지 않는 임시 429 스로틀도 claude.ai 구독으로 로그인할 때 재시도됩니다. 이전 버전은 API 키 및 엔터프라이즈 로그인에만 재시도했습니다.

71 78

72{/* min-version: 2.1.185 */}요청이 여전히 대기 중인 상태에서 응답 스트림에 20초 동안 데이터가 도착하지 않으면, 스피너는 재시도가 시작되기 전에 `Waiting for API response · will retry in … · check your network`를 표시합니다. 요청이 아직 실패하지 않았습니다. 카운트다운은 Claude Code가 정지된 연결을 중단하고 재시도하는 지점까지 실행되므로, 데이터가 재개되거나 재시도가 성공하면 배너가 자동으로 사라집니다. v2.1.185부터 임계값은 20초입니다. 이전 버전은 다른 표현으로 10초 후에 배너를 표시합니다. 모든 시도마다 다시 나타나면 [네트워크 문제](#unable-to-connect-to-api)로 취급하십시오.79두 가지 오류 클래스는 재시도할 수 없기 때문에 재시도되지 않습니다.

73 80

~~74이 페이지의 오류 중 하나를 보면 해당 재시도가 이미 소진되었습니다. 다음 환경 변수로 동작을 조정할 수 있습니다.~~81* {/* min-version: 2.1.199 */}v2.1.199부터 TLS 인증서 검증 실패(예: TLS 검사 프록시, 누락된 `NODE_EXTRA_CA_CERTS` 번들 또는 만료된 인증서)는 첫 번째 시도에서 실패하므로 전체 재시도 예산 후가 아닌 즉시 수정이 나타납니다. [SSL 인증서 오류](#ssl-certificate-errors)를 참조하십시오. 핸드셰이크 시간 초과와 같은 일시적 TLS 조건은 여전히 재시도됩니다.

82* {/* min-version: 2.1.199 */}v2.1.199부터 Claude가 이미 표시되는 출력을 스트리밍한 후 도착하는 서버 오류는 부분 응답을 유지하고 [불완전한 응답 공지](#the-response-above-may-be-incomplete)를 추가합니다. 동일한 도구 호출을 두 번 실행할 수 있으므로 재시도하지 않습니다. 이전 버전은 부분 출력을 버리고 턴을 오류로 보고했습니다.

84재시도하는 동안 스피너는 오류 레이블 뒤에 `Retrying in Ns · attempt x/y` 카운트다운을 표시합니다. 레이블은 즉시 조치할 수 있는 오류의 첫 번째 시도에서 구체적인 이유를 나타냅니다. 네트워크가 다운되었거나 TLS 핸드셰이크가 실패했거나 속도 제한에 도달했습니다. 다른 오류의 경우 처음에는 `API error`로 읽습니다. {/* min-version: 2.1.198 */}v2.1.198부터 세 번째 시도의 구체적인 이유로 전환되거나 `CLAUDE_CODE_MAX_RETRIES`가 3개 미만을 허용할 때 최종 시도에서 전환됩니다. 이전 버전은 최종 시도에서만 전환됩니다.

86{/* min-version: 2.1.198 */}v2.1.198부터 일반적인 스피너 팁은 재시도 중에 억제됩니다. 오류 이유가 드러나면 실패가 529 과부하인 경우 카운트다운 아래 줄도 서비스 상태를 확인할 위치를 나타냅니다. Anthropic API의 `status.claude.com` 또는 다른 구성의 메시지에 명시된 제공자 또는 게이트웨이 호스트입니다.

88{/* min-version: 2.1.185 */}요청이 여전히 대기 중인 상태에서 응답 스트림에 20초 동안 데이터가 도착하지 않으면 스피너는 재시도가 시작되기 전에 `Waiting for API response · will retry in … · check your network`를 표시합니다. 요청이 아직 실패하지 않았습니다. 카운트다운은 Claude Code가 정지된 연결을 중단하고 재시도하는 지점까지 실행되므로 데이터가 재개되거나 재시도가 성공하면 배너가 자동으로 사라집니다. v2.1.185부터 임계값은 20초입니다. 이전 버전은 다른 표현으로 10초 후에 배너를 표시합니다. 모든 시도마다 다시 나타나면 [네트워크 문제](#unable-to-connect-to-api)로 취급하십시오.

90이 페이지의 오류 중 하나를 보면 해당 재시도가 이미 소진되었습니다. 인증서 검증 실패와 같이 재시도되지 않는 클래스에 속하지 않는 한 말입니다. 다음 환경 변수로 동작을 조정할 수 있습니다.

75 91

76| 변수 | 기본값 | 효과 |92| 변수 | 기본값 | 효과 |

~~77| :------------------------------------------- | :------ | :-------------------------------------------------------------------------------------------------- |~~93| :------------------------------------------- | :------ | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

78| [`CLAUDE_CODE_MAX_RETRIES`](/ko/env-vars) | 10 | 재시도 횟수입니다. {/* min-version: 2.1.186 */}v2.1.186부터 15로 제한됩니다. 스크립트에서 오류를 더 빨리 표시하려면 낮추십시오. |94| [`CLAUDE_CODE_MAX_RETRIES`](/ko/env-vars) | 10 | 재시도 횟수입니다. {/* min-version: 2.1.186 */}v2.1.186부터 15로 제한됩니다. {/* min-version: 2.1.199 */}v2.1.199부터 `CLAUDE_CODE_RETRY_WATCHDOG`이 기본값을 높이고 상한을 제거합니다. 스크립트에서 오류를 더 빨리 표시하려면 낮추십시오. |

79| [`CLAUDE_CODE_RETRY_WATCHDOG`](/ko/env-vars) | 설정되지 않음 | CI 작업과 같은 무인 세션에서 `1`로 설정하여 `CLAUDE_CODE_MAX_RETRIES` 시도 후 실패하는 대신 `429` 및 `529` 용량 오류를 무한정 재시도합니다. |95| [`CLAUDE_CODE_RETRY_WATCHDOG`](/ko/env-vars) | 설정되지 않음 | CI 작업과 같은 무인 세션에서 `1`로 설정하여 `CLAUDE_CODE_MAX_RETRIES` 시도 후 실패하는 대신 `429` 및 `529` 용량 오류를 무한정 재시도합니다. {/* min-version: 2.1.199 */}v2.1.199부터 서버 오류, 시간 초과, 끊어진 연결과 같은 다른 일시적 오류의 기본 재시도 횟수를 300으로 높입니다. 대략 3시간의 백오프이며 명시적으로 해당 변수를 설정하면 `CLAUDE_CODE_MAX_RETRIES`의 상한 15를 제거합니다. |

80| [`API_TIMEOUT_MS`](/ko/env-vars) | 600000 | 요청당 시간 초과(밀리초)입니다. 느린 네트워크 또는 프록시의 경우 높입니다. |96| [`API_TIMEOUT_MS`](/ko/env-vars) | 600000 | 요청당 시간 초과(밀리초)입니다. 느린 네트워크 또는 프록시의 경우 높입니다. |

81 97

82<h2 id="server-errors">98<h2 id="server-errors">

115API Error: Repeated 529 Overloaded errors. The API is at capacity — this is usually temporary. Try again in a moment. If it persists, check https://status.claude.com.131API Error: Repeated 529 Overloaded errors. The API is at capacity — this is usually temporary. Try again in a moment. If it persists, check https://status.claude.com.

116```132```

117 133

118뒤따르는 문장은 500 오류와 동일한 방식으로 제공자에 따라 다릅니다. 529는 사용 제한이 아니며 할당량에 대해 계산되지 않습니다.134뒤따르는 문장은 500 오류와 동일한 방식으로 제공자에 따라 다릅니다.

135

136529는 사용 제한이 아니며 할당량에 대해 계산되지 않습니다.

119 137

120**할 일:**138**할 일:**

121 139

142* 느린 네트워크 또는 프록시가 원인인 경우 [자동 재시도](#automatic-retries)에 설명된 대로 `API_TIMEOUT_MS`를 높입니다.160* 느린 네트워크 또는 프록시가 원인인 경우 [자동 재시도](#automatic-retries)에 설명된 대로 `API_TIMEOUT_MS`를 높입니다.

143* 시간 초과가 자주 발생하고 네트워크가 정상인 경우 아래 [네트워크 및 연결 오류](#network-and-connection-errors)를 참조하십시오.161* 시간 초과가 자주 발생하고 네트워크가 정상인 경우 아래 [네트워크 및 연결 오류](#network-and-connection-errors)를 참조하십시오.

144 162

163<h3 id="the-response-above-may-be-incomplete">

164 The response above may be incomplete

165</h3>

166

167스트리밍 응답이 Claude가 이미 표시되는 출력을 생성한 후 실패했습니다. 요청을 다시 보내면 동일한 도구 호출을 두 번 실행할 수 있으므로 Claude Code는 이미 스트리밍된 것을 유지하고 턴을 버리는 대신 이 공지를 추가합니다. 표시되는 변형은 원인을 나타냅니다.

168

169```text theme={null}

170API Error: Server error mid-response. The response above may be incomplete.

171API Error: Connection closed mid-response. The response above may be incomplete.

172API Error: Response stalled mid-stream. The response above may be incomplete.

173```

174

175* {/* min-version: 2.1.199 */}}`Server error mid-response`: 스트림 중간 과부하 또는 5xx 서버 오류입니다. 이 변형은 Claude Code v2.1.199 이상이 필요합니다. 그 전에는 부분 출력을 버리고 전체 턴을 오류로 보고했습니다.

176* `Connection closed mid-response`: 연결이 끊어졌습니다.

177* `Response stalled mid-stream`: 스트림이 데이터 전송을 중지했습니다.

178

179**할 일:**

180

181* 스트리밍된 응답을 읽습니다. 아무것도 손실되지 않았지만 마지막 문장이나 도구 호출이 누락될 수 있습니다.

182* `continue`로 회신하여 Claude가 중단된 위치에서 계속하도록 합니다.

183* 표시되는 출력 전에 동일한 오류가 나타나면 Claude Code는 이를 완료하는 대신 요청을 재시도합니다. [자동 재시도](#automatic-retries)를 참조하십시오.

184

145<h3 id="auto-mode-cannot-determine-the-safety-of-an-action">185<h3 id="auto-mode-cannot-determine-the-safety-of-an-action">

146 Auto mode cannot determine the safety of an action186 Auto mode cannot determine the safety of an action

147</h3>187</h3>

173* 작업을 재시도합니다. 일반적으로 다음 시도에서 성공합니다.213* 작업을 재시도합니다. 일반적으로 다음 시도에서 성공합니다.

174* `claude --debug`를 실행하고 작업을 반복하여 디버그 로그에서 기본 분류기 응답을 확인합니다.214* `claude --debug`를 실행하고 작업을 반복하여 디버그 로그에서 기본 분류기 응답을 확인합니다.

175 215

216이전 대화 콘텐츠 때문에 별도의 API 안전 확인이 분류기 요청을 차단했을 때:

217

218```text theme={null}

219Auto mode could not evaluate this action and is blocking it for safety — a safety check separate from auto mode blocked this request because of earlier conversation content — it isn't about the action itself — run with --debug for details

220```

221

222**할 일:**

223

224* 이것은 작업에 대한 결정이 아닙니다. 대화에 이미 있는 콘텐츠가 자동 모드가 분류기에 대화를 보낼 때 API의 안전 필터를 트리거했습니다.

225* 재시도는 도움이 되지 않습니다. 동일한 대화 콘텐츠가 필터를 다시 트리거합니다.

226* 다른 [권한 모드](/ko/permission-modes)로 전환하여 메시지가 표시될 때 작업을 승인하거나 트리거 콘텐츠 없이 새 대화를 시작합니다.

227

176대화가 분류기의 컨텍스트 윈도우보다 커졌을 때:228대화가 분류기의 컨텍스트 윈도우보다 커졌을 때:

177 229

178```text theme={null}230```text theme={null}

186* 나타나는 프롬프트에서 작업을 승인하거나 거부합니다.238* 나타나는 프롬프트에서 작업을 승인하거나 거부합니다.

187* `/compact`를 실행하여 대화 크기를 줄여서 후속 작업이 분류기 윈도우에 맞도록 합니다.239* `/compact`를 실행하여 대화 크기를 줄여서 후속 작업이 분류기 윈도우에 맞도록 합니다.

188 240

241<h3 id="agent-terminated-early-due-to-an-api-error">

242 Agent terminated early due to an API error

243</h3>

244

245{/* min-version: 2.1.199 */}}[서브에이전트](/ko/sub-agents)의 API 요청이 터미널로 실패했습니다. 예를 들어 사용 제한에 도달했거나 서버 오류에 대한 재시도가 소진되었으므로 서브에이전트가 작업을 완료하기 전에 중지했습니다. 이 메시지는 Claude Code v2.1.199 이상이 필요합니다. 그 전에는 API 오류 텍스트가 서브에이전트의 결과인 것처럼 Claude에 반환되었습니다.

246

247```text theme={null}

248Agent terminated early due to an API error: <error detail>

249```

250

251**할 일:**

252

253* 콜론 뒤의 오류 세부 정보를 이 페이지의 자체 섹션(예: [사용 제한](#usage-limits) 또는 [서버 오류](#server-errors))과 일치시키고 해당 섹션의 단계를 따릅니다.

254* 기본 오류가 해결되면 Claude에게 작업을 재시도하거나 [서브에이전트를 재개](/ko/sub-agents#resume-subagents)하도록 요청합니다.

255

256속도 제한, 과부하 또는 서버 오류가 이미 출력을 생성한 포그라운드 서브에이전트를 중단할 때 Claude는 이 오류 대신 불완전한 것으로 표시된 부분 출력을 받습니다. [서브에이전트의 API 오류](/ko/sub-agents#api-errors-in-subagents)를 참조하십시오.

257

189<h2 id="usage-limits">258<h2 id="usage-limits">

190 사용 제한259 사용 제한

191</h2>260</h2>

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

194 263

195<h3 id="you’ve-hit-your-session-limit">264<h3 id="you’ve-hit-your-session-limit">

196 세션 제한에 도달했습니다265 You've hit your session limit

197</h3>266</h3>

198 267

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

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

217 286

218<h3 id="usage-credits-required-for-1m-context">287<h3 id="usage-credits-required-for-1m-context">

219 1M 컨텍스트에 필요한 사용 크레딧288 Usage credits required for 1M context

220</h3>289</h3>

221 290

222선택한 모델은 1M 토큰 확장 컨텍스트 윈도우를 사용하며, 플랜에는 사용 크레딧을 통해서만 포함됩니다.291선택한 모델은 1M 토큰 확장 컨텍스트 윈도우를 사용하며, 플랜에는 사용 크레딧을 통해서만 포함됩니다.

227 296

228이는 할당량 소진이 아니라 자격 확인입니다. 세션 및 주간 허용량에 용량이 남아 있어도 발생합니다. [확장 컨텍스트](/ko/model-config#extended-context)에서 어떤 플랜에 1M 컨텍스트가 직접 포함되고 어떤 플랜에 사용 크레딧이 필요한지 확인하십시오.297이는 할당량 소진이 아니라 자격 확인입니다. 세션 및 주간 허용량에 용량이 남아 있어도 발생합니다. [확장 컨텍스트](/ko/model-config#extended-context)에서 어떤 플랜에 1M 컨텍스트가 직접 포함되고 어떤 플랜에 사용 크레딧이 필요한지 확인하십시오.

229 298

230컨텍스트가 200K 토큰을 초과하여 대화 중에 이 오류가 나타나면 Claude Code는 자동으로 대화를 표준 컨텍스트 제한 이하로 압축하고 이후 세션을 해당 제한으로 유지하므로 조치가 필요하지 않습니다. v2.1.172 이전 버전에서는 `/compact`를 포함한 모든 후속 요청에서 오류가 반복되었습니다. 해당 버전에서는 `/clear`를 실행하여 복구합니다. 아래 단계는 명시적으로 `[1m]` 모델을 선택한 경우에 적용됩니다.299{/* min-version: 2.1.172 */}}컨텍스트가 200K 토큰을 초과하여 대화 중에 이 오류가 나타나면 Claude Code는 자동으로 대화를 표준 컨텍스트 제한 이하로 압축하고 이후 세션을 해당 제한으로 유지하므로 조치가 필요하지 않습니다. v2.1.172 이전 버전에서는 `/compact`를 포함한 모든 후속 요청에서 오류가 반복되었습니다. 해당 버전에서는 `/clear`를 실행하여 복구합니다. 아래 단계는 명시적으로 `[1m]` 모델을 선택한 경우에 적용됩니다.

231 300

232**할 일:**301**할 일:**

233 302

237* 모델 선택기에서 1M 변형을 완전히 제거하려면 [`CLAUDE_CODE_DISABLE_1M_CONTEXT=1`](/ko/env-vars)을 설정합니다.306* 모델 선택기에서 1M 변형을 완전히 제거하려면 [`CLAUDE_CODE_DISABLE_1M_CONTEXT=1`](/ko/env-vars)을 설정합니다.

238 307

239<h3 id="server-is-temporarily-limiting-requests">308<h3 id="server-is-temporarily-limiting-requests">

240 서버가 일시적으로 요청을 제한 중입니다309 Server is temporarily limiting requests

241</h3>310</h3>

242 311

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

246API Error: Server is temporarily limiting requests (not your usage limit)315API Error: Server is temporarily limiting requests (not your usage limit)

247```316```

248 317

249이는 표시되기 전에 [자동으로 재시도](#automatic-retries)됩니다.318Claude Code는 이를 플랜 제한과 구별합니다. 실제 제한 응답이 전달하는 통합 할당량 헤더가 없기 때문입니다. {/* min-version: 2.1.199 */}}v2.1.199부터 이는 인증 방식에 관계없이 [자동으로 재시도](#automatic-retries)됩니다. 이전 버전에서는 claude.ai 구독으로 로그인한 세션이 첫 번째 발생에서 턴을 실패했습니다. API 키 및 엔터프라이즈 로그인만 재시도했습니다.

250 319

251**할 일:**320**할 일:**

252 321

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

255 324

256<h3 id="request-rejected-429">325<h3 id="request-rejected-429">

257 요청 거부됨 (429)326 Request rejected (429)

258</h3>327</h3>

259 328

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

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

274 343

275<h3 id="credit-balance-is-too-low">344<h3 id="credit-balance-is-too-low">

276 크레딧 잔액이 너무 낮습니다345 Credit balance is too low

277</h3>346</h3>

278 347

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

323Could not resolve authentication method. Expected one of apiKey, authToken, credentials, config, or profile to be set. Or for one of the "X-Api-Key" or "Authorization" headers to be explicitly omitted392Could not resolve authentication method. Expected one of apiKey, authToken, credentials, config, or profile to be set. Or for one of the "X-Api-Key" or "Authorization" headers to be explicitly omitted

324```393```

325 394

326{/* min-version: 2.1.174 */}v2.1.174 이전에는 유효한 자격 증명이 구성되어 있어도 유휴 사전 초기화된 워커에 할당된 백그라운드 또는 클라우드 세션이 이런 방식으로 실패할 수 있었습니다. 복구하려면 업그레이드하십시오. 현재 버전에서 오류는 워커 프로세스에 사용 가능한 자격 증명이 없음을 의미합니다.395{/* min-version: 2.1.174 */}}v2.1.174 이전에는 유효한 자격 증명이 구성되어 있어도 유휴 사전 초기화된 워커에 할당된 백그라운드 또는 클라우드 세션이 이런 방식으로 실패할 수 있었습니다. 복구하려면 업그레이드하십시오. 현재 버전에서 오류는 워커 프로세스에 사용 가능한 자격 증명이 없음을 의미합니다.

327 396

328**할 일:**397**할 일:**

329 398

373 Your organization has disabled API key authentication442 Your organization has disabled API key authentication

374</h3>443</h3>

375 444

445{/* min-version: 2.1.169 */}}

376Console 조직의 관리자가 API 키 인증을 비활성화했으므로 API가 Claude Code가 전송하는 키를 거부합니다. `·` 뒤의 복구 힌트는 키가 어디에서 왔는지에 따라 다릅니다.446Console 조직의 관리자가 API 키 인증을 비활성화했으므로 API가 Claude Code가 전송하는 키를 거부합니다. `·` 뒤의 복구 힌트는 키가 어디에서 왔는지에 따라 다릅니다.

377 447

378```text theme={null}448```text theme={null}

437Remote Control is only available when using Claude via api.anthropic.com.507Remote Control is only available when using Claude via api.anthropic.com.

438```508```

439 509

440이는 Amazon Bedrock, Google Vertex AI 및 Microsoft Foundry에 나타납니다. {/* min-version: 2.1.196 */}v2.1.196부터는 [`ANTHROPIC_BASE_URL`](/ko/env-vars)이 `api.anthropic.com` 이외의 호스트(예: [LLM 게이트웨이](/ko/llm-gateway) 또는 프록시)를 가리킬 때도 나타나며, claude.ai로 로그인한 경우에도 마찬가지입니다.510이는 Amazon Bedrock, Google Vertex AI 및 Microsoft Foundry에 나타납니다. {/* min-version: 2.1.196 */}}v2.1.196부터는 [`ANTHROPIC_BASE_URL`](/ko/env-vars)이 `api.anthropic.com` 이외의 호스트(예: [LLM 게이트웨이](/ko/llm-gateway) 또는 프록시)를 가리킬 때도 나타나며, claude.ai로 로그인한 경우에도 마찬가지입니다.

441 511

442**할 일:**512**할 일:**

443 513

477 547

478* `/login`을 실행하여 현재 범위로 새 토큰을 발급합니다. 먼저 로그아웃할 필요가 없습니다.548* `/login`을 실행하여 현재 범위로 새 토큰을 발급합니다. 먼저 로그아웃할 필요가 없습니다.

479 549

550<h3 id="aws-credentials-expired-or-invalid">

551 AWS credentials expired or invalid

552</h3>

553

554{/* min-version: 2.1.198 */}}이 메시지는 Claude Code v2.1.198 이상이 필요하며 [`awsAuthRefresh`](/ko/amazon-bedrock#advanced-credential-configuration)가 설정 파일에 설정되어 있을 때만 나타납니다. AWS 세션 토큰이 만료되었거나 거부되었으며 Claude Code가 이미 실행한 자동 새로 고침이 API가 허용하는 자격 증명을 생성하지 못했습니다. [AWS의 Claude Platform](/ko/claude-platform-on-aws) 또는 [Mantle 엔드포인트](/ko/amazon-bedrock#use-the-mantle-endpoint)의 401에 나타나며, 이는 해당 제공자가 만료된 보안 토큰을 보고하는 방식입니다.

555

556중간의 작업 힌트는 설정의 `awsAuthRefresh` 명령을 나타내므로 다릅니다. 선행 부분은 `AWS credentials expired or invalid`입니다.

557

558```text theme={null}

559AWS credentials expired or invalid · run /login and select "Claude Platform on AWS · refresh credentials", or run `aws sso login --profile myprofile` in another terminal · API Error: 401 ...

560```

561

562`awsAuthRefresh`가 구성되지 않으면 동일한 401은 대신 일반 `Please run /login` 메시지를 표시하며, AWS 자격 증명을 새로 고칠 수 없습니다.

563

564**할 일:**

565

566* 메시지에 명시된 `awsAuthRefresh` 명령(예: `aws sso login --profile myprofile`)을 다른 터미널에서 실행하고 브라우저 로그인을 완료한 후 재시도합니다.

567* 대화형 세션에서 `/login`을 실행하고 **3rd-party platform**을 선택한 후 **Using 3rd-party platforms** 아래에서 **Claude Platform on AWS · refresh credentials**를 선택하여 Claude Code를 다시 시작하지 않고 동일한 명령을 실행합니다. [AWS 자격 증명 구성](/ko/claude-platform-on-aws#1-configure-aws-credentials)을 참조하십시오.

568* 새로 고침 명령이 성공한 후에도 오류가 반복되면 동일한 셸 및 프로필에서 `aws sts get-caller-identity`로 Claude Code 외부에서 신원이 유효한지 확인합니다.

569

570<h3 id="aws-authentication-failed">

571 AWS authentication failed

572</h3>

573

574{/* min-version: 2.1.198 */}}이 메시지는 Claude Code v2.1.198 이상이 필요하며 [`awsAuthRefresh`](/ko/amazon-bedrock#advanced-credential-configuration)가 설정 파일에 설정되어 있을 때만 나타납니다. AWS 제공자가 403을 반환했거나 [Amazon Bedrock](/ko/amazon-bedrock)이 401을 반환했습니다.

575

576Claude Code는 어느 원인을 맞았는지 알 수 없습니다. Amazon Bedrock은 만료된 보안 토큰을 403으로 보고하지만 403은 또한 `AccessDeniedException`에서 누락된 IAM 권한 또는 계정에 대해 활성화되지 않은 모델과 같은 인증 거부를 보고하는 방식입니다.

577

578Amazon Bedrock의 401도 [AWS 자격 증명 만료 또는 유효하지 않음](#aws-credentials-expired-or-invalid) 아래가 아닌 여기에 도달합니다. Bedrock이 만료된 토큰을 401로 보고하지 않기 때문입니다. 해당 엔드포인트의 401은 일반적으로 회사 프록시와 같은 요청 경로의 다른 것에서 나옵니다.

579

580자격 증명 새로 고침은 만료된 토큰을 수정하고 다른 원인을 수정할 수 없으므로 메시지는 둘 다 제공합니다.

581

582```text theme={null}

583AWS authentication failed · run /login and select "Claude Platform on AWS · refresh credentials", or run `aws sso login --profile myprofile` in another terminal · if credentials are current, check AWS permissions and model access · API Error: 403 ...

584```

585

586중간의 작업 힌트는 설정의 `awsAuthRefresh` 명령을 나타내므로 다릅니다. 선행 부분은 `AWS authentication failed`입니다.

587

588**할 일:**

589

590* 메시지에 명시된 `awsAuthRefresh` 명령 또는 `aws sso login`을 실행합니다. 만료된 자격 증명이 원인일 수 있습니다.

591* 자격 증명이 현재이면 [IAM 구성](/ko/amazon-bedrock#iam-configuration)의 IAM 권한이 사용 중인 신원에 연결되어 있고 선택한 모델이 계정 및 지역에 대해 활성화되어 있는지 확인합니다.

592* `aws sts get-caller-identity`를 실행하여 요청이 사용하는 신원을 확인합니다. 오래된 `AWS_PROFILE` 또는 기본 프로필은 권한 불일치의 일반적인 원인입니다.

593

480<h2 id="network-and-connection-errors">594<h2 id="network-and-connection-errors">

481 네트워크 및 연결 오류595 네트워크 및 연결 오류

482</h2>596</h2>

484이러한 오류는 Claude Code의 네트워크 요청이 목적지에 도달하지 못했음을 의미합니다. 일반적으로 로컬 네트워크, 프록시 또는 방화벽, 또는 클라우드 환경의 네트워크 정책에서 발생합니다.598이러한 오류는 Claude Code의 네트워크 요청이 목적지에 도달하지 못했음을 의미합니다. 일반적으로 로컬 네트워크, 프록시 또는 방화벽, 또는 클라우드 환경의 네트워크 정책에서 발생합니다.

485 599

486<h3 id="unable-to-connect-to-api">600<h3 id="unable-to-connect-to-api">

487 API에 연결할 수 없음601 Unable to connect to API

488</h3>602</h3>

489 603

490API에 대한 TCP 연결이 실패했거나 완료되지 않았습니다.604API에 대한 TCP 연결이 실패했거나 완료되지 않았습니다.

515* Docker Desktop 및 유사한 컨테이너 런타임은 아웃바운드 트래픽을 가로챌 수 있습니다. 이를 종료하고 재시도하여 이를 배제합니다.629* Docker Desktop 및 유사한 컨테이너 런타임은 아웃바운드 트래픽을 가로챌 수 있습니다. 이를 종료하고 재시도하여 이를 배제합니다.

516 630

517<h3 id="ssl-certificate-errors">631<h3 id="ssl-certificate-errors">

518 SSL 인증서 오류632 SSL certificate errors

519</h3>633</h3>

520 634

521네트워크의 프록시 또는 보안 어플라이언스가 자체 인증서로 TLS 트래픽을 가로채고 있으며 Claude Code가 이를 신뢰하지 않습니다.635네트워크의 프록시 또는 보안 어플라이언스가 자체 인증서로 TLS 트래픽을 가로채고 있으며 Claude Code가 이를 신뢰하지 않습니다.

525Unable to connect to API: Self-signed certificate detected639Unable to connect to API: Self-signed certificate detected

526```640```

527 641

642{/* min-version: 2.1.199 */}}v2.1.199부터 인증서 검증 실패는 재시도되지 않으므로 이 오류는 전체 [재시도 예산](#automatic-retries) 후가 아닌 첫 번째 시도에 나타납니다. 이전 버전은 표시하기 전에 몇 분 동안 재시도했습니다. 핸드셰이크 시간 초과와 같은 일시적 TLS 조건은 여전히 재시도됩니다.

643

644`/login` 및 시작 연결 확인 중에 동일한 실패는 OpenSSL 코드 및 인라인 수정으로 보고됩니다.

645

646```text theme={null}

647SSL certificate error (UNABLE_TO_GET_ISSUER_CERT_LOCALLY). If you are behind a corporate proxy or TLS-intercepting firewall, set NODE_EXTRA_CA_CERTS to your CA bundle path, or ask IT to allowlist *.anthropic.com. Run /doctor for details.

648```

649

528**할 일:**650**할 일:**

529 651

530* 조직의 CA 번들을 내보내고 `NODE_EXTRA_CA_CERTS=/path/to/ca-bundle.pem`으로 Claude Code를 가리킵니다.652* 조직의 CA 번들을 내보내고 `NODE_EXTRA_CA_CERTS=/path/to/ca-bundle.pem`으로 Claude Code를 가리킵니다.

532* 인증서 검증을 완전히 비활성화하는 `NODE_TLS_REJECT_UNAUTHORIZED=0`을 설정하지 마십시오.654* 인증서 검증을 완전히 비활성화하는 `NODE_TLS_REJECT_UNAUTHORIZED=0`을 설정하지 마십시오.

533 655

534<h3 id="host-not-allowed-in-a-cloud-session">656<h3 id="host-not-allowed-in-a-cloud-session">

535 클라우드 세션에서 호스트가 허용되지 않음657 Host not allowed in a cloud session

536</h3>658</h3>

537 659

538클라우드 세션 또는 루틴의 아웃바운드 HTTP 요청이 환경의 네트워크 정책에 의해 차단되었습니다.660클라우드 세션 또는 루틴의 아웃바운드 HTTP 요청이 환경의 네트워크 정책에 의해 차단되었습니다.

627API Error: 400 ... image dimensions exceed max allowed size749API Error: 400 ... image dimensions exceed max allowed size

628```750```

629 751

630{/* min-version: 2.1.142 */}Claude Code는 처리할 수 없는 이미지를 텍스트 자리 표시자로 바꾸고 다시 시도하므로 후속 메시지가 성공합니다. 2.1.142 이전 버전에서는 붙여넣은 이미지가 대화에 남아 있을 수 있으며 후속 메시지마다 동일한 오류를 반복합니다. 이러한 버전에서 복구하려면 Esc를 두 번 눌러 이미지가 추가된 턴을 지나갑니다.752{/* min-version: 2.1.142 */}}Claude Code는 처리할 수 없는 이미지를 텍스트 자리 표시자로 바꾸고 다시 시도하므로 후속 메시지가 성공합니다. 2.1.142 이전 버전에서는 붙여넣은 이미지가 대화에 남아 있을 수 있으며 후속 메시지마다 동일한 오류를 반복합니다. 이러한 버전에서 복구하려면 Esc를 두 번 눌러 이미지가 추가된 턴을 지나갑니다.

631 753

632**할 일:**754**할 일:**

633 755

694 There's an issue with the selected model816 There's an issue with the selected model

695</h3>817</h3>

696 818

819{/* min-version: 2.1.160 */}}

697구성된 모델 이름이 인식되지 않았거나 계정이 이에 액세스할 수 없습니다. v2.1.160부터 뒤따르는 힌트는 여기에 대화형 형식으로 표시되며 표면에 따라 다릅니다.820구성된 모델 이름이 인식되지 않았거나 계정이 이에 액세스할 수 없습니다. v2.1.160부터 뒤따르는 힌트는 여기에 대화형 형식으로 표시되며 표면에 따라 다릅니다.

698 821

699```text theme={null}822```text theme={null}

729 Model is restricted by your organization's settings852 Model is restricted by your organization's settings

730</h3>853</h3>

731 854

855{/* min-version: 2.1.187 */}}

732조직 관리자가 claude.ai 관리 콘솔에서 이 모델을 비활성화했거나 관리되는 설정의 [`availableModels`](/ko/model-config#restrict-model-selection) 허용 목록으로 제외되었습니다. 제한된 모델이 `--model`, `ANTHROPIC_MODEL` 또는 `model` 설정으로 설정되었을 때 Claude Code는 허용된 모델로 대체하고 계속합니다. 제한된 모델에 대해 `/model <name>`을 입력하면 `Run /model to choose a different model.`로 거부되고 세션은 현재 모델을 유지합니다.856조직 관리자가 claude.ai 관리 콘솔에서 이 모델을 비활성화했거나 관리되는 설정의 [`availableModels`](/ko/model-config#restrict-model-selection) 허용 목록으로 제외되었습니다. 제한된 모델이 `--model`, `ANTHROPIC_MODEL` 또는 `model` 설정으로 설정되었을 때 Claude Code는 허용된 모델로 대체하고 계속합니다. 제한된 모델에 대해 `/model <name>`을 입력하면 `Run /model to choose a different model.`로 거부되고 세션은 현재 모델을 유지합니다.

733 857

734```text theme={null}858```text theme={null}

753 877

754**할 일:**878**할 일:**

755 879

880{/* min-version: 2.1.197 */}}

881

756* `claude update`를 실행하고 Claude Code를 다시 시작합니다. Opus 4.7은 v2.1.111 이상이 필요합니다. Opus 4.8은 v2.1.154 이상이 필요합니다. Sonnet 5는 v2.1.197 이상이 필요합니다.882* `claude update`를 실행하고 Claude Code를 다시 시작합니다. Opus 4.7은 v2.1.111 이상이 필요합니다. Opus 4.8은 v2.1.154 이상이 필요합니다. Sonnet 5는 v2.1.197 이상이 필요합니다.

757* 업그레이드할 수 없으면 `/model`을 실행하고 Opus 4.6 또는 Sonnet 4.6을 선택합니다.883* 업그레이드할 수 없으면 `/model`을 실행하고 Opus 4.6 또는 Sonnet 4.6을 선택합니다.

758* {/* min-version: agent-sdk@0.3.197 */}[Agent SDK](/ko/agent-sdk/overview)에서 이를 맞으면 SDK 패키지를 대신 업그레이드합니다. Opus 4.8은 TypeScript SDK v0.3.154 이상과 Python SDK v0.2.88 이상이 필요합니다. Sonnet 5는 TypeScript SDK v0.3.197 이상이 필요합니다.884* {/* min-version: agent-sdk@0.3.197 */}}[Agent SDK](/ko/agent-sdk/overview)에서 이를 맞으면 SDK 패키지를 대신 업그레이드합니다. Opus 4.8은 TypeScript SDK v0.3.154 이상과 Python SDK v0.2.88 이상이 필요합니다. Sonnet 5는 TypeScript SDK v0.3.197 이상이 필요합니다.

759 885

760<h3 id="thinking-budget-exceeds-output-limit">886<h3 id="thinking-budget-exceeds-output-limit">

761 Thinking budget exceeds output limit887 Thinking budget exceeds output limit

790 916

791**할 일:**917**할 일:**

792 918

793* {/* max-version: 2.1.155 */}Opus 4.7 또는 Opus 4.8을 사용하는 경우 먼저 `claude update`를 실행합니다. v2.1.156 이전 버전은 정상적인 도구 사용 중에 이 오류를 트리거할 수 있으며 `/rewind`는 이를 지우지 않습니다.919* {/* max-version: 2.1.155 */}}Opus 4.7 또는 Opus 4.8을 사용하는 경우 먼저 `claude update`를 실행합니다. v2.1.156 이전 버전은 정상적인 도구 사용 중에 이 오류를 트리거할 수 있으며 `/rewind`는 이를 지우지 않습니다.

794* `/rewind`를 실행하거나 Esc를 두 번 눌러 손상된 턴 전의 체크포인트로 뒤로 이동하고 거기서 계속합니다. [체크포인팅](/ko/checkpointing)을 참조하여 체크포인트가 생성되고 복원되는 방식을 확인합니다.920* `/rewind`를 실행하거나 Esc를 두 번 눌러 손상된 턴 전의 체크포인트로 뒤로 이동하고 거기서 계속합니다. [체크포인팅](/ko/checkpointing)을 참조하여 체크포인트가 생성되고 복원되는 방식을 확인합니다.

795 921

796<h3 id="usage-policy-refusal">922<h3 id="usage-policy-refusal">

811* 어느 턴이 원인인지 식별할 수 없으면 `/clear`를 실행하여 동일한 프로젝트에서 새 대화를 시작합니다. 이전 대화는 디스크에 보존되며 `/resume`에서 사용 가능합니다.937* 어느 턴이 원인인지 식별할 수 없으면 `/clear`를 실행하여 동일한 프로젝트에서 새 대화를 시작합니다. 이전 대화는 디스크에 보존되며 `/resume`에서 사용 가능합니다.

812* [비대화형 모드](/ko/headless)(`-p`)에서는 되감기를 사용할 수 없으므로 다시 표현된 프롬프트로 다시 시도하거나 `--continue` 없이 새 세션을 시작합니다. 정책 확인은 모델에 따라 다르므로 `--model`로 다른 모델로 전환하면 일부 경우에 거부를 해결할 수도 있습니다.938* [비대화형 모드](/ko/headless)(`-p`)에서는 되감기를 사용할 수 없으므로 다시 표현된 프롬프트로 다시 시도하거나 `--continue` 없이 새 세션을 시작합니다. 정책 확인은 모델에 따라 다르므로 `--model`로 다른 모델로 전환하면 일부 경우에 거부를 해결할 수도 있습니다.

813 939

940<h2 id="command-line-errors">

941 명령줄 오류

942</h2>

943

944이러한 오류는 Claude Code의 `claude` 명령줄 자체 검증에서 나옵니다. Claude Code는 세션을 생성하거나 API 요청을 보내기 전에 즉시 인쇄합니다.

945

946<h3 id="conflict-between-bg-and-print">

947 Conflict between --bg and --print

948</h3>

949

950{/* min-version: 2.1.198 */}}

951이 메시지는 Claude Code v2.1.198 이상이 필요합니다. 동일한 `claude` 호출에서 `--bg`를 `-p` 또는 `--print`와 결합했습니다. `--bg`는 나중에 `claude agents`로 첨부하는 [백그라운드 세션](/ko/agent-view#from-your-shell)을 시작하는 반면 `--print`는 [비대화형](/ko/headless)으로 실행되며 `claude agents`가 첨부하는 대화형 세션을 시작하지 않습니다. v2.1.198 이전에는 이 조합이 자동으로 첨부할 수 없는 백그라운드 작업을 자동으로 생성했습니다.

952

953```text theme={null}

954--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>'`.

955```

956

957**할 일:**

958

959* `-p` 또는 `--print`를 제거합니다. `--bg`는 프롬프트를 위치 인수로 사용하므로 `claude --bg "<task>"`가 완전한 명령입니다. [셸에서 새 에이전트 디스패치](/ko/agent-view#from-your-shell)를 참조하십시오.

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

961

814<h2 id="responses-seem-lower-quality-than-usual">962<h2 id="responses-seem-lower-quality-than-usual">

815 응답 품질이 평소보다 낮아 보임963 응답 품질이 평소보다 낮아 보임

816</h2>964</h2>

832 980

833응답이 잘못되면 수정으로 회신하는 것보다 일반적으로 되감기가 더 잘 작동합니다. Esc를 두 번 누르거나 `/rewind`를 실행하여 나쁜 턴 전으로 뒤로 이동한 후 더 구체적으로 프롬프트를 다시 표현합니다. 스레드 내에서 수정하면 잘못된 시도가 컨텍스트에 남아 있어 나중의 답변을 이에 고정할 수 있습니다. [체크포인팅](/ko/checkpointing)을 참조하십시오.981응답이 잘못되면 수정으로 회신하는 것보다 일반적으로 되감기가 더 잘 작동합니다. Esc를 두 번 누르거나 `/rewind`를 실행하여 나쁜 턴 전으로 뒤로 이동한 후 더 구체적으로 프롬프트를 다시 표현합니다. 스레드 내에서 수정하면 잘못된 시도가 컨텍스트에 남아 있어 나중의 답변을 이에 고정할 수 있습니다. [체크포인팅](/ko/checkpointing)을 참조하십시오.

834 982

835위의 확인 후에도 품질이 여전히 이상해 보이면 `/feedback`을 실행하고 예상한 것과 얻은 것을 설명합니다. 이 방식으로 제출된 피드백에는 대화 기록이 포함되어 있으므로 Anthropic이 실제 회귀를 진단하는 가장 빠른 방법입니다. 제공자에서 `/feedback`을 사용할 수 없는 경우 [오류 보고](#report-an-error)를 참조하십시오.983위의 확인 후에도 품질이 여전히 이상해 보이면 `/feedback`을 실행하고 예상한 것과 얻은 것을 설명합니다. 이 방식으로 제출된 피드백에는 대화 기록이 포함되어 있으므로 Anthropic이 실제 회귀를 진단하는 가장 빠른 방법입니다. 환경에서 `/feedback`을 사용할 수 없는 경우 [오류 보고](#report-an-error)를 참조하십시오.

836 984

837<h2 id="report-an-error">985<h2 id="report-an-error">

838 오류 보고986 오류 보고

839</h2>987</h2>

840 988

841이 페이지는 Claude API의 오류를 다룹니다. Claude Code의 다른 구성 요소의 오류는 관련 가이드를 참조하십시오.989이 페이지는 Claude Code 런타임 오류를 다룹니다. 다른 구성 요소의 오류는 관련 가이드를 참조하십시오.

842 990

843* MCP 서버가 연결 또는 인증에 실패함: [MCP](/ko/mcp)991* MCP 서버가 연결 또는 인증에 실패함: [MCP](/ko/mcp)

844* 훅 스크립트가 실패했거나 도구를 차단함: [훅 디버그](/ko/hooks#debug-hooks)992* 훅 스크립트가 실패했거나 도구를 차단함: [훅 디버그](/ko/hooks#debug-hooks)

fullscreen.md +5 −3

Details

58* **`/` 명령 또는 `@` 파일 목록의 제안을 클릭**하여 수락합니다. 마우스 커서 위의 행을 강조 표시합니다.58* **`/` 명령 또는 `@` 파일 목록의 제안을 클릭**하여 수락합니다. 마우스 커서 위의 행을 강조 표시합니다.

59* **선택 메뉴의 옵션을 클릭**하여 선택합니다. 이는 권한 프롬프트, `/model`, `/config` 및 옵션 목록을 표시하는 기타 대화 상자를 포함합니다. 마우스 커서 위의 행에 포인터가 표시됩니다. {/* min-version: 2.1.187 */}Claude Code v2.1.187 이상이 필요합니다.59* **선택 메뉴의 옵션을 클릭**하여 선택합니다. 이는 권한 프롬프트, `/model`, `/config` 및 옵션 목록을 표시하는 기타 대화 상자를 포함합니다. 마우스 커서 위의 행에 포인터가 표시됩니다. {/* min-version: 2.1.187 */}Claude Code v2.1.187 이상이 필요합니다.

60* **축소된 도구 결과를 클릭**하여 확장하고 전체 출력을 봅니다. 다시 클릭하면 축소됩니다. 도구 호출과 그 결과가 함께 확장됩니다. 표시할 내용이 더 있는 메시지만 클릭 가능합니다.60* **축소된 도구 결과를 클릭**하여 확장하고 전체 출력을 봅니다. 다시 클릭하면 축소됩니다. 도구 호출과 그 결과가 함께 확장됩니다. 표시할 내용이 더 있는 메시지만 클릭 가능합니다.

61* **macOS에서 `Cmd`를 누르거나 Linux 및 Windows에서 `Ctrl`을 누르고 URL 또는 파일 경로를 클릭**하여 엽니다. Edit 또는 Write 후 인쇄된 것과 같은 도구 출력의 파일 경로는 기본 애플리케이션에서 열립니다. 일반 `http://` 및 `https://` URL은 브라우저에서 열립니다. {/* min-version: 2.1.181 */}v2.1.181부터 `Cmd` 또는 `Ctrl`을 누르지 않은 일반 클릭은 더 이상 링크를 열지 않으며, 기본 터미널 동작과 일치합니다. VS Code 통합 터미널 및 유사한 xterm.js 기반 터미널에서는 Claude Code가 터미널의 자체 링크 핸들러로 연기하며, 이는 동일한 제스처를 사용합니다.61* **macOS에서 `Cmd`를 누르거나 Linux 및 Windows에서 `Ctrl`을 누르고 URL 또는 파일 경로를 클릭**하여 엽니다. Edit 또는 Write 후 인쇄된 것과 같은 도구 출력의 파일 경로는 기본 애플리케이션에서 열립니다. 일반 `http://` 및 `https://` URL은 브라우저에서 열립니다. {/* min-version: 2.1.181 */}v2.1.181부터 `Cmd` 또는 `Ctrl`을 누르지 않은 일반 클릭은 더 이상 링크를 열지 않으며, 기본 터미널 동작과 일치합니다. 일부 macOS 터미널은 `Cmd`+클릭을 실행 중인 앱으로 전달하며 터미널 마우스 프로토콜은 `Cmd` 키를 인코딩할 방법이 없으므로 Claude Code는 이를 일반 클릭으로 수신합니다. Ghostty에서, 그리고 {/* min-version: 2.1.198 */}v2.1.198부터 macOS의 Warp에서 Claude Code는 이를 감지하고 링크에 대한 일반 클릭이 이를 열 수 있도록 하며, `Cmd`를 누르고 있으면 여전히 작동합니다. VS Code 통합 터미널 및 유사한 xterm.js 기반 터미널에서는 Claude Code가 터미널의 자체 링크 핸들러로 연기하며, 이는 동일한 제스처를 사용합니다.

62* **클릭 및 드래그**하여 대화의 어디든지 텍스트를 선택합니다. 더블 클릭하면 단어를 선택하며, iTerm2의 단어 경계와 일치하므로 파일 경로가 하나의 단위로 선택됩니다. 트리플 클릭하면 줄을 선택합니다.62* **클릭 및 드래그**하여 대화의 어디든지 텍스트를 선택합니다. 더블 클릭하면 단어를 선택하며, iTerm2의 단어 경계와 일치하므로 파일 경로가 하나의 단위로 선택됩니다. {/* min-version: 2.1.198 */}v2.1.198부터 URL을 더블 클릭하면 스킴을 포함한 전체 URL이 선택됩니다. 트리플 클릭하면 줄을 선택합니다.

63* **마우스 휠로 스크롤**하여 대화를 이동합니다.63* **마우스 휠로 스크롤**하여 대화를 이동합니다.

64 64

65선택된 텍스트는 마우스 릴리스 시 자동으로 클립보드에 복사됩니다. 이를 끄려면 `/config`에서 선택 시 복사를 토글합니다. 끄면 `Ctrl+Shift+c`를 눌러 수동으로 복사합니다. kitty, WezTerm, Ghostty, iTerm2와 같은 kitty 키보드 프로토콜을 지원하는 터미널에서는 `Cmd+c`도 작동합니다. 활성 선택이 있으면 `Ctrl+c`는 취소하는 대신 복사합니다.65선택된 텍스트는 마우스 릴리스 시 자동으로 클립보드에 복사됩니다. 이를 끄려면 `/config`에서 선택 시 복사를 토글합니다.

67선택 시 복사가 꺼져 있으면 `Ctrl+Shift+c`를 눌러 수동으로 복사합니다. kitty, WezTerm, Ghostty, iTerm2와 같은 kitty 키보드 프로토콜을 지원하는 터미널에서는 `Cmd+c`도 작동합니다. 활성 선택이 있으면 `Ctrl+c`는 취소하는 대신 복사합니다.

66 68

67활성 선택이 있으면 `Shift`를 누르고 화살표 키를 눌러 키보드에서 확장합니다. `Shift+↑` 및 `Shift+↓`는 선택이 위쪽 또는 아래쪽 가장자리에 도달할 때 뷰포트를 스크롤합니다. `Shift+Home` 및 `Shift+End`는 현재 줄의 시작 또는 끝으로 확장합니다.69활성 선택이 있으면 `Shift`를 누르고 화살표 키를 눌러 키보드에서 확장합니다. `Shift+↑` 및 `Shift+↓`는 선택이 위쪽 또는 아래쪽 가장자리에 도달할 때 뷰포트를 스크롤합니다. `Shift+Home` 및 `Shift+End`는 현재 줄의 시작 또는 끝으로 확장합니다.

68 70

gateways.md +1 −1

Details

44 Claude 앱 게이트웨이44 Claude 앱 게이트웨이

45</h3>45</h3>

46 46

47Claude 앱 게이트웨이는 `claude` 바이너리에 포함된 Anthropic의 자체 호스팅 게이트웨이입니다. Amazon Bedrock, Google Cloud, Microsoft Foundry 또는 Anthropic API를 업스트림으로 라우팅합니다. 개발자는 `/login`을 통해 회사 ID 제공자로 로그인하고, 게이트웨이는 IdP 그룹별로 모델 액세스 및 [관리 설정](/ko/permissions#managed-settings)을 적용하며, [OpenTelemetry Protocol (OTLP)](/ko/monitoring-usage) 사용량 메트릭을 자신의 관찰성 스택으로 내보냅니다.47Claude 앱 게이트웨이는 `claude` 바이너리에 포함된 Anthropic의 자체 호스팅 게이트웨이입니다. Amazon Bedrock, Claude Platform on AWS, Google Cloud, Microsoft Foundry 또는 Anthropic API를 업스트림으로 라우팅합니다. 개발자는 `/login`을 통해 회사 ID 제공자로 로그인하고, 게이트웨이는 IdP 그룹별로 모델 액세스 및 [관리 설정](/ko/permissions#managed-settings)을 적용하며, [OpenTelemetry Protocol (OTLP)](/ko/monitoring-usage) 사용량 메트릭을 자신의 관찰성 스택으로 내보냅니다.

48 48

49각 Claude Code 릴리스와 함께 빌드되고 테스트되므로, Claude Code가 전송하는 헤더 및 요청 필드를 전달합니다. 별도로 유지 관리되는 게이트웨이는 각 릴리스에서 해당 헤더 및 필드가 변경될 때 [전달 규칙을 업데이트](/ko/llm-gateway-protocol#forward-as-open-lists)해야 합니다. Claude 앱 게이트웨이는 CLI와 함께 릴리스되므로 최신 상태를 유지할 목록이 없습니다. [가용성 및 제한 사항](/ko/claude-apps-gateway#availability-and-limitations)에서 게이트웨이 세션에서 다르게 작동하는 작은 기능 집합을 참조하세요.49각 Claude Code 릴리스와 함께 빌드되고 테스트되므로, Claude Code가 전송하는 헤더 및 요청 필드를 전달합니다. 별도로 유지 관리되는 게이트웨이는 각 릴리스에서 해당 헤더 및 필드가 변경될 때 [전달 규칙을 업데이트](/ko/llm-gateway-protocol#forward-as-open-lists)해야 합니다. Claude 앱 게이트웨이는 CLI와 함께 릴리스되므로 최신 상태를 유지할 목록이 없습니다. [가용성 및 제한 사항](/ko/claude-apps-gateway#availability-and-limitations)에서 게이트웨이 세션에서 다르게 작동하는 작은 기능 집합을 참조하세요.

50 50

hooks.md +64 −28

Details

16 Hook 수명 주기16 Hook 수명 주기

17</h2>17</h2>

18 18

19Hook은 Claude Code 세션 중 특정 지점에서 실행됩니다. 이벤트가 발생하고 matcher가 일치하면 Claude Code는 이벤트에 대한 JSON 컨텍스트를 hook 핸들러에 전달합니다. 명령 hook의 경우 입력은 stdin에 도착합니다. HTTP hook의 경우 POST 요청 본문으로 도착합니다. 그러면 핸들러는 입력을 검사하고 조치를 취한 후 선택적으로 결정을 반환할 수 있습니다. 이벤트는 세 가지 주기로 발생합니다: 세션당 한 번 (`SessionStart`, `SessionEnd`), 턴당 한 번 (`UserPromptSubmit`, `Stop`, `StopFailure`), 에이전트 루프 내의 모든 도구 호출에서 (`PreToolUse`, `PostToolUse`):19Hook은 Claude Code 세션 중 특정 지점에서 실행됩니다. 이벤트가 발생하고 matcher가 일치하면 Claude Code는 이벤트에 대한 JSON 컨텍스트를 hook 핸들러에 전달합니다. 명령 hook의 경우 입력은 stdin에 도착합니다. HTTP hook의 경우 POST 요청 본문으로 도착합니다. 그러면 핸들러는 입력을 검사하고 조치를 취한 후 선택적으로 결정을 반환할 수 있습니다.

21이벤트는 세 가지 주기로 발생합니다:

23* 세션당 한 번: `SessionStart` 및 `SessionEnd`

24* 턴당 한 번: `UserPromptSubmit`, `Stop` 및 `StopFailure`

25* 에이전트 루프 내의 모든 도구 호출에서: `PreToolUse` 및 `PostToolUse`

20 26

21<div style={{maxWidth: "500px", margin: "0 auto"}}>27<div style={{maxWidth: "500px", margin: "0 auto"}}>

22 <Frame>28 <Frame>

184 190

185설정 파일 해결에 대한 자세한 내용은 [설정](/ko/settings)을 참조하세요. 엔터프라이즈 관리자는 `allowManagedHooksOnly`를 사용하여 사용자, 프로젝트 및 plugin hook을 차단할 수 있습니다. 관리형 설정 `enabledPlugins`에서 강제 활성화된 plugin의 hook은 면제되므로 관리자는 조직 마켓플레이스를 통해 검증된 hook을 배포할 수 있습니다. [Hook 구성](/ko/settings#hook-configuration)을 참조하세요.191설정 파일 해결에 대한 자세한 내용은 [설정](/ko/settings)을 참조하세요.

192

193엔터프라이즈 관리자는 `allowManagedHooksOnly`를 사용하여 사용자, 프로젝트 및 plugin hook을 차단할 수 있습니다. 관리형 설정 `enabledPlugins`에서 강제 활성화된 plugin의 hook은 면제되므로 관리자는 조직 마켓플레이스를 통해 검증된 hook을 배포할 수 있습니다. [Hook 구성](/ko/settings#hook-configuration)을 참조하세요.

186 194

187<h3 id="matcher-patterns">195<h3 id="matcher-patterns">

188 Matcher 패턴196 Matcher 패턴

217| `Notification` | 알림 유형 | `permission_prompt`, `idle_prompt`, `auth_success`, `elicitation_dialog`, `elicitation_complete`, `elicitation_response` |225| `Notification` | 알림 유형 | `permission_prompt`, `idle_prompt`, `auth_success`, `elicitation_dialog`, `elicitation_complete`, `elicitation_response`, `agent_needs_input`, `agent_completed` |

317 325

318일치하는 모든 hook은 병렬로 실행되며 동일한 핸들러는 자동으로 중복 제거됩니다. 명령 hook은 명령 문자열과 `args`로 중복 제거되고 HTTP hook은 URL로 중복 제거됩니다.326일치하는 모든 hook은 병렬로 실행되며 동일한 핸들러는 자동으로 중복 제거됩니다. 명령 hook은 명령 문자열과 `args`로 중복 제거되고 HTTP hook은 URL로 중복 제거됩니다.

319 327

320핸들러는 현재 디렉토리에서 Claude Code의 환경으로 실행됩니다. `$CLAUDE_CODE_REMOTE` 환경 변수는 원격 웹 환경에서 `"true"`로 설정되고 로컬 CLI에서는 설정되지 않습니다.328핸들러는 현재 디렉토리에서 Claude Code의 환경으로 실행됩니다. `$CLAUDE_CODE_REMOTE` 환경 변수는 원격 웹 환경에서 `"true"`로 설정되고 로컬 CLI에서는 설정되지 않습니다. {/* min-version: 2.1.199 */}v2.1.199부터 [`$CLAUDE_CODE_BRIDGE_SESSION_ID`](/ko/env-vars)는 로컬 세션이 활성 Remote Control 연결을 가지고 있는 동안 [Remote Control](/ko/remote-control) 세션 ID로 설정됩니다.

321 329

322<h4 id="common-fields">330<h4 id="common-fields">

323 공통 필드331 공통 필드

736| `InstructionsLoaded` | 아니오 | 종료 코드는 무시됩니다 |744| `InstructionsLoaded` | 아니오 | 종료 코드는 무시됩니다 |

737| `MessageDisplay` | 아니오 | 원본 텍스트가 표시됩니다 |745| `MessageDisplay` | 아니오 | 원본 텍스트가 표시됩니다 |

738 746

747`SessionStart`, `Setup`, 및 `SubagentStart`의 경우 종료 코드 2 stderr은 트랜스크립트에 `<hook name> hook error` 알림으로 렌더링되며, [차단하지 않는 오류](#exit-code-output)와 동일한 방식입니다. Claude는 이를 보지 못하며 세션 또는 subagent는 진행됩니다. `SubagentStart`의 경우 알림은 부모 대화가 아닌 subagent의 자신의 트랜스크립트에 나타납니다.

748

749Claude Code v2.1.199부터 `SessionStart`, `Setup`, 및 `SubagentStart`는 트랜스크립트에 종료 코드 2 stderr을 표시합니다. 이전 버전은 디버그 로그에만 기록했습니다.

750

739<h3 id="http-response-handling">751<h3 id="http-response-handling">

740 HTTP 응답 처리752 HTTP 응답 처리

741</h3>753</h3>

963 SessionStart 입력975 SessionStart 입력

964</h4>976</h4>

965 977

966[공통 입력 필드](#common-input-fields) 외에도 SessionStart hook은 `source`, `model`, 선택적으로 `agent_type` 및 `session_title`을 받습니다. `source` 필드는 세션이 시작된 방식을 나타냅니다: 새 세션의 경우 `"startup"`, 재개된 세션의 경우 `"resume"`, `/clear` 후 `"clear"`, 압축 후 `"compact"`. `model` 필드는 모델 식별자를 포함합니다. 예를 들어 `/clear` 후 또는 대화 복구를 통해 세션이 복원될 때 생략될 수 있으므로 필드를 읽기 전에 확인하세요. `claude --agent <name>`으로 Claude Code를 시작하면 `agent_type` 필드에 에이전트 이름이 포함됩니다. `session_title` 필드는 이미 설정된 경우 현재 세션 제목을 전달합니다. 예를 들어 `--name` 또는 `/rename`을 통해 설정된 경우입니다. `sessionTitle`을 내보내는 hook은 사용자가 명시적으로 설정한 제목을 덮어쓰지 않도록 먼저 `session_title`을 확인할 수 있습니다.978[공통 입력 필드](#common-input-fields) 외에도 SessionStart hook은 `source` 및 선택적으로 `model`, `agent_type`, `session_title`을 받습니다:

979

980| 필드 | 설명 |

981| :-------------- | :--------------------------------------------------------------------------------------------------------------------------------------- |

982| `source` | 세션이 시작된 방식: 새 세션의 경우 `"startup"`, 재개된 세션의 경우 `"resume"`, `/clear` 후 `"clear"`, 압축 후 `"compact"` |

983| `model` | 활성 모델 식별자. 예를 들어 `/clear` 후 또는 대화 복구를 통해 세션이 복원될 때 생략될 수 있으므로 필드를 읽기 전에 확인하세요 |

984| `agent_type` | `claude --agent <name>`으로 Claude Code를 시작할 때 존재하는 에이전트 이름 |

985| `session_title` | 이미 설정된 경우 현재 세션 제목 (예: `--name` 또는 `/rename`을 통해). `sessionTitle`을 내보내는 hook은 사용자가 명시적으로 설정한 제목을 덮어쓰지 않도록 먼저 `session_title`을 확인할 수 있습니다 |

967 986

968```json theme={null}987```json theme={null}

969{988{

985| 필드 | 설명 |1004| 필드 | 설명 |

986| :------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |1005| :------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

987| `additionalContext` | Claude의 컨텍스트 시작 부분에 추가되는 문자열. 첫 번째 프롬프트 전에 추가됩니다. [Claude를 위한 컨텍스트 추가](#add-context-for-claude)를 참조하여 텍스트가 전달되는 방식과 포함할 내용을 확인하세요 |1006| `additionalContext` | Claude의 컨텍스트 시작 부분에 추가되는 문자열. 첫 번째 프롬프트 전에 추가됩니다. [Claude를 위한 컨텍스트 추가](#add-context-for-claude)를 참조하여 텍스트가 전달되는 방식과 포함할 내용을 확인하세요 |

988| `initialUserMessage` | 세션의 첫 번째 사용자 메시지로 사용되는 문자열. [비대화형 모드](/ko/headless) (`-p`)에 적용되며, 프롬프트가 제공되지 않으면 첫 번째 턴이 됩니다. 프롬프트가 제공되면 다음 턴으로 따릅니다. `additionalContext`와 달리 기존 턴에 첨부되는 이것은 턴을 생성합니다 |1007| `initialUserMessage` | 세션의 첫 번째 사용자 메시지로 사용되는 문자열. [비대화형 모드](/ko/headless)에서 `-p` 플래그와 함께 적용되며, 프롬프트가 제공되지 않으면 첫 번째 턴이 됩니다. 프롬프트가 제공되면 다음 턴으로 따릅니다. `additionalContext`와 달리 기존 턴에 첨부되는 이것은 턴을 생성합니다 |

989| `sessionTitle` | 세션 제목을 설정합니다. `/rename`과 동일한 효과입니다. 시작 폴더, git 분기 또는 worktree 이름에서 세션을 자동으로 이름 지정하는 데 사용합니다. `source`가 `"startup"` 또는 `"resume"`일 때만 적용됩니다; `"clear"` 및 `"compact"`에서는 무시됩니다 |1008| `sessionTitle` | 세션 제목을 설정합니다. `/rename`과 동일한 효과입니다. 시작 폴더, git 분기 또는 worktree 이름에서 세션을 자동으로 이름 지정하는 데 사용합니다. `source`가 `"startup"` 또는 `"resume"`일 때만 적용됩니다; `"clear"` 및 `"compact"`에서는 무시됩니다 |

991| `reloadSkills` | 부울. `true`일 때 Claude Code는 SessionStart hook이 완료된 후 [skill](/ko/skills) 및 명령 디렉토리를 다시 스캔하므로 hook이 설치한 skill은 첫 번째 프롬프트부터 같은 세션에서 사용 가능합니다 |1010| `reloadSkills` | 부울. `true`일 때 Claude Code는 SessionStart hook이 완료된 후 [skill](/ko/skills) 및 명령 디렉토리를 다시 스캔하므로 hook이 설치한 skill은 첫 번째 프롬프트부터 같은 세션에서 사용 가능합니다 |

1062 Setup1081 Setup

1063</h3>1082</h3>

1064 1083

1065`--init-only`로 Claude Code를 시작하거나 print 모드 (`-p`)에서 `--init` 또는 `--maintenance`로 시작할 때만 발생합니다. 일반 시작 시에는 발생하지 않습니다. 일회성 종속성 설치 또는 CI 또는 스크립트에서 명시적으로 트리거하는 예약된 정리에 사용합니다. 일반 세션 시작과 별도입니다. 세션별 초기화의 경우 [SessionStart](#sessionstart)를 대신 사용합니다.1084`--init-only`로 Claude Code를 시작하거나 비대화형 모드(/ko/headless)에서 `-p` 플래그와 함께 `--init` 또는 `--maintenance`로 시작할 때만 발생합니다. 일반 시작 시에는 발생하지 않습니다. 일회성 종속성 설치 또는 CI 또는 스크립트에서 명시적으로 트리거하는 예약된 정리에 사용합니다. 일반 세션 시작과 별도입니다. 세션별 초기화의 경우 [SessionStart](#sessionstart)를 대신 사용합니다.

1066 1085

1067matcher 값은 hook을 트리거한 CLI 플래그에 해당합니다:1086matcher 값은 hook을 트리거한 CLI 플래그에 해당합니다:

1068 1087

1073 1092

1074`--init-only`는 Setup hook과 `startup` matcher가 있는 SessionStart hook을 실행한 다음 대화를 시작하지 않고 종료합니다. `--init` 및 `--maintenance`는 `-p` (print 모드)와 결합할 때만 Setup hook을 발생시킵니다; 대화형 세션에서 이 두 플래그는 현재 Setup hook을 발생시키지 않습니다.1093`--init-only`는 Setup hook과 `startup` matcher가 있는 SessionStart hook을 실행한 다음 대화를 시작하지 않고 종료합니다. `--init` 및 `--maintenance`는 `-p`와 결합할 때만 Setup hook을 발생시킵니다; 대화형 세션에서 이 두 플래그는 현재 Setup hook을 발생시키지 않습니다.

1075 1094

1076Setup은 모든 시작 시 발생하지 않으므로 종속성이 설치된 plugin은 Setup만으로는 의존할 수 없습니다. 실제 패턴은 첫 사용 시 종속성을 확인하고 누락되면 설치하는 것입니다. 예를 들어 `${CLAUDE_PLUGIN_DATA}/node_modules`를 테스트하고 없으면 `npm install`을 실행하는 hook 또는 skill입니다. 설치된 종속성을 저장할 위치는 [지속적 데이터 디렉토리](/ko/plugins-reference#persistent-data-directory)를 참조하세요.1095Setup은 모든 시작 시 발생하지 않으므로 종속성이 설치된 plugin은 Setup만으로는 의존할 수 없습니다. 실제 패턴은 첫 사용 시 종속성을 확인하고 누락되면 설치하는 것입니다. 예를 들어 `${CLAUDE_PLUGIN_DATA}/node_modules`를 테스트하고 없으면 `npm install`을 실행하는 hook 또는 skill입니다. 설치된 종속성을 저장할 위치는 [지속적 데이터 디렉토리](/ko/plugins-reference#persistent-data-directory)를 참조하세요.

1077 1096

1095 Setup 결정 제어1114 Setup 결정 제어

1096</h4>1115</h4>

1097 1116

1098Setup hook은 차단할 수 없습니다. 종료 코드 2에서 stderr이 사용자에게 표시됩니다; 다른 0이 아닌 종료 코드에서 stderr은 `--verbose`로 시작할 때만 나타납니다. 두 경우 모두 실행이 계속됩니다. Claude의 컨텍스트에 정보를 전달하려면 JSON 출력에서 `additionalContext`를 반환합니다; 일반 stdout은 디버그 로그에만 작성됩니다. 모든 hook에 사용 가능한 [JSON 출력 필드](#json-output) 외에도 이러한 이벤트 특정 필드를 반환할 수 있습니다:1117Setup hook은 차단할 수 없습니다. 0이 아닌 종료 코드 (2 포함)는 stderr을 사용자에게 `<hook name> hook error` 알림으로 표시하고 실행이 계속됩니다. [비대화형 모드](/ko/headless)에서 hook 출력은 `--verbose`로 시작할 때만 나타납니다.

1118

1119Claude의 컨텍스트에 정보를 전달하려면 JSON 출력에서 `additionalContext`를 반환합니다; 일반 stdout은 디버그 로그에만 작성됩니다. 모든 hook에 사용 가능한 [JSON 출력 필드](#json-output) 외에도 이러한 이벤트 특정 필드를 반환할 수 있습니다:

1099 1120

1100| 필드 | 설명 |1121| 필드 | 설명 |

1101| :------------------ | :-------------------------------------- |1122| :------------------ | :-------------------------------------- |

1189종료 코드 0에서 대화에 컨텍스트를 추가하는 두 가지 방법이 있습니다:1210종료 코드 0에서 대화에 컨텍스트를 추가하는 두 가지 방법이 있습니다:

1190 1211

1191* **일반 텍스트 stdout**: stdout에 작성된 JSON이 아닌 텍스트는 컨텍스트로 추가됩니다1212* **일반 텍스트 stdout**: stdout에 작성된 JSON이 아닌 텍스트는 컨텍스트로 추가됩니다

1192* **`additionalContext`가 있는 JSON**: 더 많은 제어를 위해 아래 JSON 형식을 사용합니다. `additionalContext` 필드는 컨텍스트로 추가됩니다1213* **`additionalContext`가 있는 JSON**: 더 많은 제어를 위해 아래 JSON 형식을 사용합니다. `additionalContext` 필드는 Claude가 읽는 시스템 알림으로 컨텍스트에 주입됩니다

1193 1214

1194일반 stdout은 트랜스크립트에 hook 출력으로 표시됩니다. `additionalContext` 필드는 더 신중하게 추가됩니다.1215일반 stdout은 트랜스크립트에 hook 출력으로 표시됩니다. `additionalContext` 값은 시스템 알림으로 주입되어 Claude가 표시되는 트랜스크립트 항목 없이 읽습니다.

1195 1216

1196프롬프트를 차단하려면 `decision`을 `"block"`으로 설정한 JSON 객체를 반환합니다:1217프롬프트를 차단하려면 `decision`을 `"block"`으로 설정한 JSON 객체를 반환합니다:

1197 1218

1215}1236}

1216```1237```

1217 1238

1218<Note>

1219 JSON 형식은 간단한 사용 사례에는 필요하지 않습니다. 컨텍스트를 추가하려면 종료 코드 0으로 stdout에 일반 텍스트를 인쇄할 수 있습니다. 프롬프트를 차단하거나 더 구조화된 제어가 필요할 때 JSON을 사용합니다.

1220</Note>

~~1221~~

1222<h3 id="userpromptexpansion">1239<h3 id="userpromptexpansion">

1223 UserPromptExpansion1240 UserPromptExpansion

1224</h3>1241</h3>

1545`PostToolUse`에서 완료된 Agent 호출의 `tool_response`는 subagent의 최종 텍스트와 사용 원격 측정을 전달합니다. hook에서 subagent별 비용을 기록하려면 이러한 필드를 읽으세요:1562`PostToolUse`에서 완료된 Agent 호출의 `tool_response`는 subagent의 최종 텍스트와 사용 원격 측정을 전달합니다. hook에서 subagent별 비용을 기록하려면 이러한 필드를 읽으세요:

1546 1563

1547| 필드 | 유형 | 예제 | 설명 |1564| 필드 | 유형 | 예제 | 설명 |

1548| :------------------ | :-- | :---------------------------------------------------- | :--------------------------------------------------------------------------------------------------- |1565| :------------------ | :-- | :---------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |

1549| `status` | 문자열 | `"completed"` | 동기 호출의 경우 `"completed"`, `run_in_background: true`의 경우 `"async_launched"` |1566| `status` | 문자열 | `"completed"` | `"completed"` (동기 호출의 경우), `"async_launched"` (백그라운드 subagent의 경우). {/* min-version: 2.1.198 */}v2.1.198부터 subagent는 기본적으로 백그라운드에서 실행되므로 생략된 `run_in_background`도 `"async_launched"`를 생성합니다 |

1551| `content` | 배열 | `[{"type": "text", "text": "Found 12 endpoints..."}]` | subagent의 최종 텍스트 블록 |1568| `content` | 배열 | `[{"type": "text", "text": "Found 12 endpoints..."}]` | subagent의 최종 텍스트 블록 |

1552| `resolvedModel` | 문자열 | `"claude-sonnet-4-5"` | subagent가 실행된 모델. 요청된 모델과 다를 수 있습니다. {/* min-version: 2.1.174 */}Claude Code v2.1.174 이상 필요 |1569| `resolvedModel` | 문자열 | `"claude-sonnet-4-5"` | subagent가 실행된 모델. 요청된 모델과 다를 수 있습니다. {/* min-version: 2.1.174 */}Claude Code v2.1.174 이상 필요 |

1555| `totalToolUseCount` | 숫자 | `7` | subagent가 수행한 도구 호출 수 |1572| `totalToolUseCount` | 숫자 | `7` | subagent가 수행한 도구 호출 수 |

1556| `usage` | 객체 | `{"input_tokens": 8320, ...}` | 유형별 토큰 분석: `input_tokens`, `output_tokens`, `cache_creation_input_tokens`, `cache_read_input_tokens` |1573| `usage` | 객체 | `{"input_tokens": 8320, ...}` | 유형별 토큰 분석: `input_tokens`, `output_tokens`, `cache_creation_input_tokens`, `cache_read_input_tokens` |

1557 1574

1558`run_in_background: true` 호출의 경우 도구는 subagent를 시작한 후 즉시 반환되므로 `tool_response`는 사용 필드를 전달하지 않습니다. `status: "async_launched"`, `agentId`, `description`, `prompt`, `outputFile`, `resolvedModel`이 있습니다.1575백그라운드 subagent의 경우 도구는 subagent를 시작한 후 즉시 반환되므로 `tool_response`는 사용 필드를 전달하지 않습니다. `status: "async_launched"`, `agentId`, `description`, `prompt`, `outputFile`, `resolvedModel`이 있습니다.

1559 1576

1560`resolvedModel` 필드는 subagent가 실제로 실행되는 모델의 이름을 지정하며, 이는 `tool_input`의 `model` 값과 다를 수 있습니다. Claude Code v2.1.174 이상이 필요합니다.1577`resolvedModel` 필드는 subagent가 실제로 실행되는 모델의 이름을 지정하며, 이는 `tool_input`의 `model` 값과 다를 수 있습니다. Claude Code v2.1.174 이상이 필요합니다.

1561 1578

1619 1636

1620`AskUserQuestion` 및 `ExitPlanMode`는 사용자 상호 작용이 필요하며 일반적으로 [비대화형 모드](/ko/headless)에서 `-p` 플래그로 차단합니다. `permissionDecision: "allow"`를 `updatedInput`과 함께 반환하면 해당 요구 사항을 충족합니다: hook은 stdin에서 도구의 입력을 읽고 자신의 UI를 통해 답변을 수집하고 `updatedInput`에서 반환하여 도구가 프롬프트 없이 실행되도록 합니다. `"allow"`만 반환하는 것은 이러한 도구에 충분하지 않습니다. `AskUserQuestion`의 경우 원본 `questions` 배열을 에코백하고 각 질문의 텍스트를 선택한 답변으로 매핑하는 [`answers`](#askuserquestion) 객체를 추가합니다.1637`AskUserQuestion` 및 `ExitPlanMode`는 사용자 상호 작용이 필요하며 일반적으로 [비대화형 모드](/ko/headless)에서 `-p` 플래그로 차단합니다. `permissionDecision: "allow"`를 `updatedInput`과 함께 반환하면 해당 요구 사항을 충족합니다: hook은 stdin에서 도구의 입력을 읽고 자신의 UI를 통해 답변을 수집하고 `updatedInput`에서 반환하여 도구가 프롬프트 없이 실행되도록 합니다. `"allow"`만 반환하는 것은 이러한 도구에 충분하지 않습니다. `AskUserQuestion`의 경우 원본 `questions` 배열을 에코백하고 각 질문의 텍스트를 선택한 답변으로 매핑하는 [`answers`](#askuserquestion) 객체를 추가합니다.

1621 1638

1639v2.1.199부터 [`_meta["anthropic/requiresUserInteraction"]`](/ko/mcp#require-approval-for-a-specific-tool)로 표시된 MCP 도구는 더 엄격합니다: hook은 `updatedInput`이 있거나 없이 `"allow"`로 승인 프롬프트를 건너뛸 수 없습니다. Claude Code는 hook이 도구가 필요한 상호 작용을 수집했는지 확인할 수 없기 때문입니다.

1640

1622<Note>1641<Note>

1623 PreToolUse는 이전에 최상위 `decision` 및 `reason` 필드를 사용했지만 이 이벤트에는 더 이상 사용되지 않습니다. 대신 `hookSpecificOutput.permissionDecision` 및 `hookSpecificOutput.permissionDecisionReason`을 사용합니다. 더 이상 사용되지 않는 값 `"approve"` 및 `"block"`은 각각 `"allow"` 및 `"deny"`로 매핑됩니다. PostToolUse 및 Stop과 같은 다른 이벤트는 계속 최상위 `decision` 및 `reason`을 현재 형식으로 사용합니다.1642 PreToolUse는 이전에 최상위 `decision` 및 `reason` 필드를 사용했지만 이 이벤트에는 더 이상 사용되지 않습니다. 대신 `hookSpecificOutput.permissionDecision` 및 `hookSpecificOutput.permissionDecisionReason`을 사용합니다. 더 이상 사용되지 않는 값 `"approve"` 및 `"block"`은 각각 `"allow"` 및 `"deny"`로 매핑됩니다. PostToolUse 및 Stop과 같은 다른 이벤트는 계속 최상위 `decision` 및 `reason`을 현재 형식으로 사용합니다.

1624</Note>1643</Note>

2016 Notification2035 Notification

2017</h3>2036</h3>

2018 2037

2019Claude Code가 알림을 보낼 때 실행됩니다. 알림 유형에서 일치합니다: `permission_prompt`, `idle_prompt`, `auth_success`, `elicitation_dialog`, `elicitation_complete`, `elicitation_response`. matcher를 생략하여 모든 알림 유형에 대해 hook을 실행합니다.2038Claude Code가 알림을 보낼 때 실행됩니다. 알림 유형에서 일치합니다. 생략하여 모든 알림 유형에 대해 hook을 실행합니다.

2039

2040| Matcher | 언제 발생하는지 |

2041| :--------------------- | :---------------------------------------------------------------------- |

2042| `permission_prompt` | Claude가 도구 사용 승인이 필요함 |

2043| `idle_prompt` | Claude가 완료되고 다음 프롬프트를 기다림 |

2044| `auth_success` | 인증 완료 |

2045| `elicitation_dialog` | MCP 서버가 elicitation 양식을 열음 |

2046| `elicitation_complete` | MCP elicitation 양식이 제출되거나 닫힘 |

2047| `elicitation_response` | MCP elicitation 응답이 서버로 다시 전송됨 |

2048| `agent_needs_input` | 백그라운드 세션이 입력을 기다리기 시작함. [agent view](/ko/agent-view)가 터미널에서 열려 있을 때만 발생 |

2049| `agent_completed` | 백그라운드 세션이 완료되거나 실패함. [agent view](/ko/agent-view)가 터미널에서 열려 있을 때만 발생 |

2050

2051`agent_needs_input` 및 `agent_completed` 유형은 Claude Code v2.1.198 이상이 필요합니다.

2020 2052

2021별도의 matcher를 사용하여 알림 유형에 따라 다른 핸들러를 실행합니다. 이 구성은 Claude가 권한 승인이 필요할 때 권한 특정 경고 스크립트를 트리거하고 Claude가 유휴 상태일 때 다른 알림을 트리거합니다:2053별도의 matcher를 사용하여 알림 유형에 따라 다른 핸들러를 실행합니다. 이 구성은 Claude가 권한 승인이 필요할 때 권한 특정 경고 스크립트를 트리거하고 Claude가 유휴 상태일 때 다른 알림을 트리거합니다:

2022 2054

2079 SubagentStart 입력2111 SubagentStart 입력

2080</h4>2112</h4>

2081 2113

2082[공통 입력 필드](#common-input-fields) 외에도 SubagentStart hook은 subagent의 고유 식별자가 있는 `agent_id`와 에이전트 이름이 있는 `agent_type` (`general-purpose`, `Explore`, `Plan`과 같은 기본 제공 에이전트 또는 사용자 정의 에이전트 이름)을 받습니다.2114[공통 입력 필드](#common-input-fields) 외에도 SubagentStart hook은 subagent의 고유 식별자가 있는 `agent_id`와 에이전트 이름이 있는 `agent_type`을 받습니다.

2083 2115

2084```json theme={null}2116```json theme={null}

2085{2117{

3062 3094

3063이벤트에 대해 더 세밀한 제어가 필요한 경우 [결정 제어](#decision-control)에 설명된 이벤트별 필드가 있는 [명령 hook](#command-hook-fields)을 사용합니다.3095이벤트에 대해 더 세밀한 제어가 필요한 경우 [결정 제어](#decision-control)에 설명된 이벤트별 필드가 있는 [명령 hook](#command-hook-fields)을 사용합니다.

3064 3096

3065<h3 id="example-multi-criteria-stop-hook">3097<h3 id="check-multiple-conditions-before-stopping">

3066 예제: 다중 기준 Stop hook3098 중지하기 전에 여러 조건 확인

3067</h3>3099</h3>

3068 3100

3069이 `Stop` hook은 Claude가 중지하기 전에 세 가지 조건을 확인하는 자세한 프롬프트를 사용합니다. `"ok"`가 `false`이면 Claude는 제공된 이유를 다음 명령으로 받으며 계속 작업합니다. `SubagentStop` hook은 [subagent](/ko/sub-agents)가 중지해야 하는지 평가하는 동일한 형식을 사용합니다:3101이 `Stop` hook은 Claude가 중지하기 전에 세 가지 조건을 확인하는 자세한 프롬프트를 사용합니다. `SubagentStop` hook은 [subagent](/ko/sub-agents)가 중지해야 하는지 평가하는 동일한 형식을 사용합니다. `"ok"`가 `false`이면 Claude는 제공된 이유를 다음 명령으로 받으며 계속 작업합니다:

3070 3102

3071```json theme={null}3103```json theme={null}

3072{3104{

3190 3222

3191비동기 hook 완료 알림은 기본적으로 억제됩니다. 보려면 `Ctrl+O`로 자세한 모드를 활성화하거나 `--verbose`로 Claude Code를 시작합니다.3223비동기 hook 완료 알림은 기본적으로 억제됩니다. 보려면 `Ctrl+O`로 자세한 모드를 활성화하거나 `--verbose`로 Claude Code를 시작합니다.

3192 3224

3193<h3 id="example-run-tests-after-file-changes">3225<h3 id="run-tests-after-file-changes">

3194 예제: 파일 변경 후 테스트 실행3226 파일 변경 후 테스트 실행

3195</h3>3227</h3>

3196 3228

3197이 hook은 Claude가 파일을 쓸 때마다 백그라운드에서 테스트 스위트를 시작한 후 테스트가 완료되면 결과를 Claude에 보고합니다. 이 스크립트를 프로젝트의 `.claude/hooks/run-tests-async.sh`에 저장하고 `chmod +x`로 실행 가능하게 만듭니다:3229이 hook은 Claude가 파일을 쓸 때마다 백그라운드에서 테스트 스위트를 시작한 후 테스트가 완료되면 결과를 Claude에 보고합니다. 이 스크립트를 프로젝트의 `.claude/hooks/run-tests-async.sh`에 저장하고 `chmod +x`로 실행 가능하게 만듭니다:

3285 Windows PowerShell 도구3317 Windows PowerShell 도구

3286</h2>3318</h2>

3287 3319

3288Windows에서 개별 hook을 PowerShell에서 실행할 수 있습니다. 명령 hook에서 `"shell": "powershell"`을 설정합니다. Hook은 PowerShell을 직접 생성하므로 `CLAUDE_CODE_USE_POWERSHELL_TOOL`이 설정되어 있는지 여부와 관계없이 작동합니다. Claude Code는 `pwsh.exe` (PowerShell 7+)를 자동 감지하고 `powershell.exe` (5.1)로 폴백합니다.3320Windows에서 명령 hook에 `"shell": "powershell"`을 설정하여 PowerShell에서 개별 hook을 실행할 수 있습니다. Hook은 PowerShell을 직접 생성하므로 `CLAUDE_CODE_USE_POWERSHELL_TOOL`이 설정되어 있는지 여부와 관계없이 작동합니다. Claude Code는 PowerShell 7 이상의 실행 파일인 `pwsh.exe`를 자동 감지하고 Windows PowerShell 5.1의 `powershell.exe`로 폴백합니다.

3289 3321

3290```json theme={null}3322```json theme={null}

3291{3323{

3306}3338}

3307```3339```

3308 3340

3309PowerShell 셸 형식 명령에서 프로젝트 루트를 참조하려면 `$env:CLAUDE_PROJECT_DIR`을 사용하여 환경 변수로 읽습니다. PowerShell은 `${CLAUDE_PROJECT_DIR}` 형식을 로컬 변수로 취급하며 환경 조회가 아니고, Claude Code는 [플러그인 hook](#reference-scripts-by-path)에 대해서만 셸 형식에서 해당 자리 표시자를 대체합니다. `settings.json`에 정의된 hook의 경우 `$env:` 형식을 사용하거나 [exec 형식](#exec-form-and-shell-form)으로 전환합니다. 여기서 `${CLAUDE_PROJECT_DIR}`은 hook이 정의된 위치와 관계없이 각 `args` 요소에서 대체됩니다.3341PowerShell 셸 형식 명령에서 프로젝트 루트를 참조하려면 `${CLAUDE_PROJECT_DIR}` 또는 `$env:CLAUDE_PROJECT_DIR`을 작성합니다. v2.1.198부터 Claude Code는 hook이 `settings.json`, 플러그인 또는 스킬에 정의되어 있는지 여부와 관계없이 PowerShell 셸 형식 명령에서 `${CLAUDE_PROJECT_DIR}`, `${CLAUDE_PLUGIN_ROOT}` 및 `${CLAUDE_PLUGIN_DATA}` 자리 표시자를 PowerShell의 `${env:NAME}` 형식으로 다시 작성합니다. PowerShell은 구문 분석 후 내보낸 환경에서 값을 확인하므로 자리 표시자는 큰따옴표로 묶인 문자열 내에서는 작동하지만 PowerShell이 변수를 확장하지 않는 작은따옴표로 묶인 문자열 내에서는 작동하지 않습니다.

3342

3343v2.1.198 이전에는 이 다시 쓰기가 플러그인 hook에만 적용되었습니다. 이전 버전에서는 `settings.json` hook이 `$env:` 형식이나 [exec 형식](#exec-form-and-shell-form)이 필요하며, 여기서 `${CLAUDE_PROJECT_DIR}`은 hook이 정의된 위치와 관계없이 각 `args` 요소에서 대체됩니다.

3344

3345PowerShell hook에서 `$CLAUDE_PROJECT_DIR`의 단순한 형식을 작성하지 마십시오. PowerShell은 이를 정의되지 않은 로컬 변수로 구문 분석하고 `$null`로 확인하므로 스크립트 경로가 프로젝트 루트 접두사 없이 남습니다. Claude Code는 해당 형식을 다시 작성하지 않으며 대신 [디버그 로그](#debug-hooks)에 경고를 기록합니다.

3310 3346

3311아래 예제는 `$env:` 형식으로 프로젝트 스크립트를 실행하는 `settings.json` hook을 보여줍니다:3347아래 예제는 모든 버전에서 작동하는 `$env:` 형식으로 프로젝트 스크립트를 실행하는 `settings.json` hook을 보여줍니다:

3312 3348

3313```json theme={null}3349```json theme={null}

3314{3350{

hooks-guide.md +27 −23

Details

87 87

88Hooks를 사용하면 Claude Code의 라이프사이클의 주요 지점에서 코드를 실행할 수 있습니다: 편집 후 파일 형식 지정, 실행 전 명령 차단, Claude가 입력이 필요할 때 알림 전송, 세션 시작 시 컨텍스트 주입 등. 전체 hook 이벤트 목록은 [Hooks 참조](/ko/hooks#hook-lifecycle)를 참조하세요.88Hooks를 사용하면 Claude Code의 라이프사이클의 주요 지점에서 코드를 실행할 수 있습니다: 편집 후 파일 형식 지정, 실행 전 명령 차단, Claude가 입력이 필요할 때 알림 전송, 세션 시작 시 컨텍스트 주입 등. 전체 hook 이벤트 목록은 [Hooks 참조](/ko/hooks#hook-lifecycle)를 참조하세요.

89 89

~~90각 예제에는 [설정 파일](#configure-hook-location)에 추가하는 즉시 사용 가능한 구성 블록이 포함되어 있습니다. 가장 일반적인 패턴:~~90각 예제에는 [설정 파일](#configure-hook-location)에 추가하는 즉시 사용 가능한 구성 블록이 포함되어 있습니다.

~~92* [Claude가 입력이 필요할 때 알림 받기](#get-notified-when-claude-needs-input)~~

~~93* [편집 후 코드 자동 형식 지정](#auto-format-code-after-edits)~~

~~94* [보호된 파일에 대한 편집 차단](#block-edits-to-protected-files)~~

~~95* [압축 후 컨텍스트 다시 주입](#re-inject-context-after-compaction)~~

~~96* [구성 변경 감사](#audit-configuration-changes)~~

~~97* [디렉토리 또는 파일이 변경될 때 환경 다시 로드](#reload-environment-when-directory-or-files-change)~~

~~98* [특정 권한 프롬프트 자동 승인](#auto-approve-specific-permission-prompts)~~

99 91

100별도의 모델 검토를 실행하고 결과를 세션에 다시 피드백하는 hooks의 프로덕션 예제는 [`security-guidance` 플러그인이 Claude Code와 통합되는 방식](/ko/security-guidance#how-the-plugin-integrates-with-claude-code)을 참조하세요.92별도의 모델 검토를 실행하고 결과를 세션에 다시 피드백하는 hooks의 프로덕션 예제는 [`security-guidance` 플러그인이 Claude Code와 통합되는 방식](/ko/security-guidance#how-the-plugin-integrates-with-claude-code)을 참조하세요.

101 93

182빈 `matcher`는 모든 알림 유형에서 발생합니다. 특정 이벤트에서만 발생하도록 하려면 다음 값 중 하나로 설정합니다:174빈 `matcher`는 모든 알림 유형에서 발생합니다. 특정 이벤트에서만 발생하도록 하려면 다음 값 중 하나로 설정합니다:

183 175

184| Matcher | 발생 시점 |176| Matcher | 발생 시점 |

185| :--------------------- | :-------------------------- |177| :--------------------- | :--------------------------------------------------------------------- |

184| `agent_needs_input` | 백그라운드 세션이 입력을 기다리기 시작합니다. [agent view](/ko/agent-view)가 열려 있을 때만 발생합니다 |

185| `agent_completed` | 백그라운드 세션이 완료되거나 실패합니다. [agent view](/ko/agent-view)가 열려 있을 때만 발생합니다 |

186

187`agent_needs_input` 및 `agent_completed` matcher는 Claude Code v2.1.198 이상이 필요합니다.

192 188

193`/hooks`를 입력하고 `Notification`을 선택하여 hook이 등록되었는지 확인합니다. 전체 이벤트 스키마는 [Notification 참조](/ko/hooks#notification)를 참조하세요.189`/hooks`를 입력하고 `Notification`을 선택하여 hook이 등록되었는지 확인합니다. 전체 이벤트 스키마는 [Notification 참조](/ko/hooks#notification)를 참조하세요.

194 190

198 194

199Claude가 편집하는 모든 파일에서 [Prettier](https://prettier.io/)를 자동으로 실행하여 수동 개입 없이 형식이 일관되게 유지되도록 합니다.195Claude가 편집하는 모든 파일에서 [Prettier](https://prettier.io/)를 자동으로 실행하여 수동 개입 없이 형식이 일관되게 유지되도록 합니다.

200 196

201이 hook은 `PostToolUse` 이벤트를 `Edit|Write` matcher와 함께 사용하므로 파일 편집 도구 후에만 실행됩니다. {/* min-version: 2.1.191 */}Claude Code v2.1.191 이상에서는 matcher를 `Edit,Write`로도 작성할 수 있습니다. 이러한 버전에서는 `|`와 `,`이 도구 이름 matcher의 상호 교환 가능한 목록 구분자이기 때문입니다. 명령은 [`jq`](https://jqlang.github.io/jq/)를 사용하여 편집된 파일 경로를 추출하고 Prettier에 전달합니다. 프로젝트 루트의 `.claude/settings.json`에 추가합니다:197이 hook은 `PostToolUse` 이벤트를 `Edit|Write` matcher와 함께 사용하므로 파일 편집 도구 후에만 실행됩니다. 명령은 [`jq`](https://jqlang.github.io/jq/)를 사용하여 편집된 파일 경로를 추출하고 Prettier에 전달합니다. 프로젝트 루트의 `.claude/settings.json`에 추가합니다:

202 198

203```json theme={null}199```json theme={null}

204{200{

218}214}

219```215```

220 216

217Claude Code v2.1.191 이상에서는 matcher를 `Edit,Write`로도 작성할 수 있습니다. 이러한 버전에서는 `|`와 `,`이 도구 이름 matcher의 상호 교환 가능한 목록 구분자이기 때문입니다.

218

221<Note>219<Note>

222 이 페이지의 Bash 예제는 JSON 구문 분석을 위해 `jq`를 사용합니다. `brew install jq` (macOS), `apt-get install jq` (Debian/Ubuntu)로 설치하거나 [`jq` 다운로드](https://jqlang.github.io/jq/download/)를 참조하세요.220 이 페이지의 Bash 예제는 JSON 구문 분석을 위해 `jq`를 사용합니다. macOS에서 `brew install jq`로, Debian 및 Ubuntu에서 `apt-get install jq`로 설치하거나 [`jq` 다운로드](https://jqlang.github.io/jq/download/)를 참조하세요.

223</Note>221</Note>

224 222

225<h3 id="block-edits-to-protected-files">223<h3 id="block-edits-to-protected-files">

254 ```252 ```

255 </Step>253 </Step>

256 254

257 <Step title="스크립트를 실행 가능하게 만들기 (macOS/Linux)">255 <Step title="macOS 및 Linux에서 스크립트를 실행 가능하게 만들기">

258 Hook 스크립트는 Claude Code가 실행하려면 실행 가능해야 합니다:256 Hook 스크립트는 Claude Code가 실행하려면 실행 가능해야 합니다:

259 257

260 ```bash theme={null}258 ```bash theme={null}

619 617

620다른 이벤트는 다른 결정 패턴을 사용합니다. 예를 들어 `PostToolUse` 및 `Stop` hooks는 최상위 `decision: "block"` 필드를 사용하고 `PermissionRequest`는 `hookSpecificOutput.decision.behavior`를 사용합니다. 이벤트별 전체 분석은 참조의 [요약 표](/ko/hooks#decision-control)를 참조하세요.618다른 이벤트는 다른 결정 패턴을 사용합니다. 예를 들어 `PostToolUse` 및 `Stop` hooks는 최상위 `decision: "block"` 필드를 사용하고 `PermissionRequest`는 `hookSpecificOutput.decision.behavior`를 사용합니다. 이벤트별 전체 분석은 참조의 [요약 표](/ko/hooks#decision-control)를 참조하세요.

621 619

622`UserPromptSubmit` hooks의 경우 `additionalContext`를 대신 사용하여 Claude의 컨텍스트에 텍스트를 주입합니다. 프롬프트 기반 hooks (`type: "prompt"`)는 출력을 다르게 처리합니다: [프롬프트 기반 hooks](#prompt-based-hooks)를 참조하세요.620`UserPromptSubmit` hooks의 경우 `additionalContext`를 대신 사용하여 Claude의 컨텍스트에 텍스트를 주입합니다.

621

622`type: "prompt"`를 사용하는 Hooks는 출력을 다르게 처리합니다: [프롬프트 기반 hooks](#prompt-based-hooks)를 참조하세요.

623 623

624<h3 id="filter-hooks-with-matchers">624<h3 id="filter-hooks-with-matchers">

625 Matchers로 hooks 필터링625 Matchers로 hooks 필터링

659| `Notification` | 알림 유형 | `permission_prompt`, `idle_prompt`, `auth_success`, `elicitation_dialog`, `elicitation_complete`, `elicitation_response` |659| `Notification` | 알림 유형 | `permission_prompt`, `idle_prompt`, `auth_success`, `elicitation_dialog`, `elicitation_complete`, `elicitation_response`, `agent_needs_input`, `agent_completed` |

807 807

808Claude Code에서 [`/hooks`](/ko/hooks#the-%2Fhooks-menu)를 실행하여 이벤트별로 그룹화된 모든 구성된 hooks를 찾아봅니다. 모든 hooks를 한 번에 비활성화하려면 설정 파일에서 `"disableAllHooks": true`를 설정합니다. 관리형 설정에서 구성된 Hooks는 `disableAllHooks`도 설정되지 않는 한 실행됩니다.808Claude Code에서 [`/hooks`](/ko/hooks#the-%2Fhooks-menu)를 실행하여 이벤트별로 그룹화된 모든 구성된 hooks를 찾아봅니다.

809

810모든 hooks를 비활성화하려면 설정 파일에서 `"disableAllHooks": true`를 설정합니다. 관리형 설정에서 구성된 Hooks는 `disableAllHooks`도 설정되지 않는 한 실행됩니다.

809 811

810Claude Code가 실행 중인 동안 설정 파일을 직접 편집하면 파일 감시자가 일반적으로 hook 변경을 자동으로 선택합니다.812Claude Code가 실행 중인 동안 설정 파일을 직접 편집하면 파일 감시자가 일반적으로 hook 변경을 자동으로 선택합니다.

811 813

925 제한 사항927 제한 사항

926</h3>928</h3>

927 929

930Hooks를 설계할 때 다음 제약 사항을 염두에 두십시오:

931

928* 명령 hooks는 stdout, stderr 및 종료 코드를 통해서만 통신합니다. `/` 명령이나 도구 호출을 직접 트리거할 수 없습니다. `additionalContext`를 통해 반환된 텍스트는 Claude가 일반 텍스트로 읽는 시스템 알림으로 주입됩니다. HTTP hooks는 응답 본문을 통해 통신합니다.932* 명령 hooks는 stdout, stderr 및 종료 코드를 통해서만 통신합니다. `/` 명령이나 도구 호출을 직접 트리거할 수 없습니다. `additionalContext`를 통해 반환된 텍스트는 Claude가 일반 텍스트로 읽는 시스템 알림으로 주입됩니다. HTTP hooks는 응답 본문을 통해 통신합니다.

929* Hook 타임아웃은 유형에 따라 다릅니다. `timeout` 필드(초 단위)로 hook당 재정의할 수 있습니다.933* Hook 타임아웃은 유형에 따라 다릅니다. `timeout` 필드(초 단위)로 hook당 재정의할 수 있습니다.

930 * `command`, `http`, `mcp_tool`: 10분. `UserPromptSubmit`은 이를 30초로 낮추고, `MessageDisplay`는 이를 10초로 낮춥니다.934 * `command`, `http`, `mcp_tool`: 10분. `UserPromptSubmit`은 이를 30초로 낮추고, `MessageDisplay`는 이를 10초로 낮춥니다.

931 * `prompt`: 30초.935 * `prompt`: 30초.

932 * `agent`: 60초.936 * `agent`: 60초.

933* `PostToolUse` hooks는 도구가 이미 실행되었으므로 작업을 취소할 수 없습니다.937* `PostToolUse` hooks는 도구가 이미 실행되었으므로 작업을 취소할 수 없습니다.

934* `PermissionRequest` hooks는 [비대화형 모드](/ko/headless)(`-p`)에서 발생하지 않습니다. 자동화된 권한 결정을 위해 `PreToolUse` hooks를 사용합니다.938* `PermissionRequest` hooks는 [비대화형 모드](/ko/headless)에서 `-p` 플래그와 함께 발생하지 않습니다. 자동화된 권한 결정을 위해 `PreToolUse` hooks를 사용합니다.

935* `Stop` hooks는 작업 완료 시에만이 아니라 Claude가 응답을 완료할 때마다 발생합니다. 사용자 중단 시에는 발생하지 않습니다. API 오류는 대신 [StopFailure](/ko/hooks#stopfailure)를 발생시킵니다.939* `Stop` hooks는 작업 완료 시에만이 아니라 Claude가 응답을 완료할 때마다 발생합니다. 사용자 중단 시에는 발생하지 않습니다. API 오류는 대신 [StopFailure](/ko/hooks#stopfailure)를 발생시킵니다.

936* 여러 PreToolUse hooks가 [`updatedInput`](/ko/hooks#pretooluse)을 반환하여 도구의 인수를 다시 쓸 때 마지막으로 완료된 것이 우승합니다. Hooks는 병렬로 실행되므로 순서는 비결정적입니다. 동일한 도구의 입력을 수정하는 hook이 두 개 이상 있는 것을 피합니다.940* 여러 `PreToolUse` hooks가 [`updatedInput`](/ko/hooks#pretooluse)을 반환하여 도구의 인수를 다시 쓸 때 마지막으로 완료된 것이 우선합니다. Hooks는 병렬로 실행되므로 순서는 비결정적입니다. 동일한 도구의 입력을 수정하는 hook이 두 개 이상 있는 것을 피합니다.

937 941

938<h3 id="hooks-and-permission-modes">942<h3 id="hooks-and-permission-modes">

939 Hooks 및 권한 모드943 Hooks 및 권한 모드

940</h3>944</h3>

941 945

942PreToolUse hooks는 모든 권한 모드 확인 전에 발생합니다. `permissionDecision: "deny"`를 반환하는 hook은 `bypassPermissions` 모드 또는 `--dangerously-skip-permissions`에서도 도구를 차단합니다. 이를 통해 사용자가 권한 모드를 변경하여 우회할 수 없는 정책을 적용할 수 있습니다.946`PreToolUse` hooks는 모든 권한 모드 확인 전에 발생합니다. `permissionDecision: "deny"`를 반환하는 hook은 `bypassPermissions` 모드 또는 `--dangerously-skip-permissions`에서도 도구를 차단합니다. 이를 통해 사용자가 권한 모드를 변경하여 우회할 수 없는 정책을 적용할 수 있습니다.

943 947

944반대는 사실이 아닙니다: `"allow"`를 반환하는 hook은 설정의 거부 규칙을 우회하지 않습니다. Hooks는 제한을 강화할 수 있지만 권한 규칙이 허용하는 것을 초과하여 완화할 수 없습니다.948반대는 사실이 아닙니다: `"allow"`를 반환하는 hook은 설정의 거부 규칙을 우회하지 않습니다. Hooks는 제한을 강화할 수 있지만 권한 규칙이 허용하는 것을 초과하여 완화할 수 없습니다.

945 949

950Hook이 구성되었지만 실행되지 않습니다.954Hook이 구성되었지만 실행되지 않습니다.

951 955

952* `/hooks`를 실행하고 hook이 올바른 이벤트 아래에 나타나는지 확인합니다956* `/hooks`를 실행하고 hook이 올바른 이벤트 아래에 나타나는지 확인합니다

953* Matcher 패턴이 도구 이름과 정확히 일치하는지 확인합니다(matchers는 대소문자 구분)957* Matcher 패턴이 도구 이름과 정확히 일치하는지 확인합니다. Matchers는 대소문자 구분입니다

954* 올바른 이벤트 유형을 트리거하는지 확인합니다(예: `PreToolUse`는 도구 실행 전에 발생하고 `PostToolUse`는 후에 발생)958* 올바른 이벤트 유형을 트리거하는지 확인합니다: `PreToolUse`는 도구 실행 전에 발생하고 `PostToolUse`는 후에 발생합니다

955* 비대화형 모드(`-p`)에서 `PermissionRequest` hooks를 사용하는 경우 대신 `PreToolUse`로 전환합니다959* 비대화형 모드에서 `-p` 플래그와 함께 `PermissionRequest` hooks를 사용하는 경우 대신 `PreToolUse`로 전환합니다

956 960

957<h3 id="hook-error-in-output">961<h3 id="hook-error-in-output">

958 출력에 Hook 오류962 출력에 Hook 오류

976설정 파일을 편집했지만 hooks가 메뉴에 나타나지 않습니다.980설정 파일을 편집했지만 hooks가 메뉴에 나타나지 않습니다.

977 981

978* 파일 편집은 일반적으로 자동으로 선택됩니다. 몇 초 후에 나타나지 않으면 파일 감시자가 변경을 놓쳤을 수 있습니다: 세션을 다시 시작하여 강제로 다시 로드합니다.982* 파일 편집은 일반적으로 자동으로 선택됩니다. 몇 초 후에 나타나지 않으면 파일 감시자가 변경을 놓쳤을 수 있습니다: 세션을 다시 시작하여 강제로 다시 로드합니다.

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

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

981 985

982<h3 id="stop-hook-hits-the-block-cap">986<h3 id="stop-hook-hits-the-block-cap">

how-claude-code-works.md +0 −1

Details

210내장 명령도 설정을 안내합니다:210내장 명령도 설정을 안내합니다:

211 211

212* `/init`은 프로젝트를 위한 CLAUDE.md 생성을 안내합니다212* `/init`은 프로젝트를 위한 CLAUDE.md 생성을 안내합니다

213* `/agents`는 사용자 정의 subagents 구성을 도와줍니다

214* `/doctor`는 설치의 일반적인 문제를 진단합니다213* `/doctor`는 설치의 일반적인 문제를 진단합니다

215 214

216<h3 id="it’s-a-conversation">215<h3 id="it’s-a-conversation">

llm-gateway-protocol.md +9 −1

Details

106 시스템 프롬프트 속성 블록106 시스템 프롬프트 속성 블록

107</h2>107</h2>

108 108

109Claude Code는 클라이언트 버전과 대화에서 파생된 지문을 포함하는 짧은 속성 블록을 시스템 프롬프트 앞에 추가합니다. `api.anthropic.com` 엔드포인트는 처리 전에 블록을 제거하므로 자사 프롬프트 캐싱에 영향을 주지 않습니다. 다른 업스트림은 프롬프트의 일부로 수신합니다. Anthropic 및 클라우드 제공자의 Claude 엔드포인트는 속성을 위해 이를 읽으므로, 게이트웨이에서 제거하기보다는 [`CLAUDE_CODE_ATTRIBUTION_HEADER=0`](/ko/env-vars)을 설정하여 생략합니다.109Claude Code는 클라이언트 버전과 대화에서 파생된 지문을 포함하는 짧은 속성 블록을 시스템 프롬프트 앞에 추가합니다. `api.anthropic.com` 엔드포인트는 변경되지 않은 상태로 첫 번째 시스템 블록으로 도착할 때 처리 전에 블록을 제거하므로 자사 프롬프트 캐싱에 영향을 주지 않습니다. 다른 업스트림은 프롬프트의 일부로 수신합니다.

110

111제거는 위치 기반이므로 게이트웨이가 `system` 배열을 변경되지 않은 상태로 전달할 때만 작동합니다. 다른 시스템 콘텐츠를 잃지 않으면서 블록을 프롬프트에서 제외하려면:

112

113* 받은 `system` 배열을 정확히 전달하고 블록을 먼저 유지합니다: 다른 시스템 블록을 앞에 추가하거나, 배열을 재정렬하거나, 단일 문자열로 변환하면 제거가 실패하고 블록이 모델과 프롬프트 캐시 키에 도달합니다.

114* 블록을 자체 배열 항목에 유지합니다: 엔드포인트는 속성 헤더로 시작하는 병합된 블록을 속성 전체로 취급하고 병합된 나머지 시스템 프롬프트를 포함한 모든 것을 삭제합니다.

115* 게이트웨이가 시스템 콘텐츠를 재구성해야 하는 경우, [`CLAUDE_CODE_ATTRIBUTION_HEADER=0`](/ko/env-vars)을 설정하여 Claude Code가 블록을 생략하도록 합니다. Anthropic 및 클라우드 제공자의 Claude 엔드포인트는 속성을 위해 블록을 읽으므로, 게이트웨이에서 제거하거나 이동하기보다는 클라이언트에서 생략합니다.

116

117변경되지 않은 상태로 엔드포인트에 도달하는 요청은 영향을 받지 않습니다.

110 118

111{/* min-version: 2.1.181 */}Claude Code v2.1.181부터, 요청이 사용자 정의 기본 URL을 통해 라우팅될 때 블록은 대화의 수명 동안 안정적이므로, 전체 요청 본문을 기반으로 하는 게이트웨이 측 프롬프트 캐시는 이를 비활성화하지 않고도 작동합니다. v2.1.181 이전에는 블록이 요청별 토큰을 포함했습니다. 해당 버전에서 게이트웨이가 이러한 캐시를 구현하면 `CLAUDE_CODE_ATTRIBUTION_HEADER=0`을 설정합니다.119{/* min-version: 2.1.181 */}Claude Code v2.1.181부터, 요청이 사용자 정의 기본 URL을 통해 라우팅될 때 블록은 대화의 수명 동안 안정적이므로, 전체 요청 본문을 기반으로 하는 게이트웨이 측 프롬프트 캐시는 이를 비활성화하지 않고도 작동합니다. v2.1.181 이전에는 블록이 요청별 토큰을 포함했습니다. 해당 버전에서 게이트웨이가 이러한 캐시를 구현하면 `CLAUDE_CODE_ATTRIBUTION_HEADER=0`을 설정합니다.

112 120

mcp.md +44 −1

Details

1039 특정 MCP 서버에서 자주 출력 경고가 발생하면 `MAX_MCP_OUTPUT_TOKENS` 제한을 늘리는 것을 고려하세요. 또한 서버 작성자에게 `anthropic/maxResultSizeChars` 주석을 추가하거나 응답을 페이지 매김하도록 요청할 수 있습니다. 주석은 이미지 콘텐츠를 반환하는 도구에는 영향을 주지 않습니다. 이러한 경우 `MAX_MCP_OUTPUT_TOKENS`을 올리는 것이 유일한 옵션입니다.1039 특정 MCP 서버에서 자주 출력 경고가 발생하면 `MAX_MCP_OUTPUT_TOKENS` 제한을 늘리는 것을 고려하세요. 또한 서버 작성자에게 `anthropic/maxResultSizeChars` 주석을 추가하거나 응답을 페이지 매김하도록 요청할 수 있습니다. 주석은 이미지 콘텐츠를 반환하는 도구에는 영향을 주지 않습니다. 이러한 경우 `MAX_MCP_OUTPUT_TOKENS`을 올리는 것이 유일한 옵션입니다.

1040</Warning>1040</Warning>

1041 1041

1042<h2 id="tool-input-schemas-with-a-root-level-combinator">

1043 루트 수준 결합자가 있는 도구 입력 스키마

1044</h2>

1045

1046일부 MCP 서버는 도구의 입력 스키마를 JSON Schema 합집합으로 선언하며, `anyOf`, `oneOf` 또는 `allOf`가 스키마의 최상위 수준에 있습니다. Claude API는 스키마 루트에서 이러한 키워드를 허용하지 않습니다. 이는 `properties` 내에 중첩된 결합자를 허용하며, Claude Code는 변경 없이 전송합니다.

1047

1048Claude Code v2.1.195부터 루트 수준 결합자가 있는 도구는 사용 가능한 상태로 유지됩니다. API에 도구를 보내기 전에 Claude Code는 스키마를 단일 객체로 평탄화하고 Claude에게 어떤 매개변수 그룹이 함께 속하는지 알려주는 문장을 도구의 설명 앞에 추가합니다:

1049

1050* `allOf`: 모든 분기의 속성이 병합되고, 각 분기의 `required` 목록이 여전히 적용됩니다

1051* `anyOf` 및 `oneOf`: 모든 분기의 속성이 병합되고, 각 분기의 `required` 목록은 스키마에 의해 강제되지 않고 도구 설명에 설명됩니다

1052

1053서버는 Claude가 선택한 인수를 수신하므로 서버 측에서 조합을 계속 검증하세요.

1054

1055Claude Code가 API가 허용하는 스키마를 생성할 수 없거나 오프라인 머신과 같이 재작성을 활성화하는 원격 구성을 받지 않는 배포에서는 해당 도구 하나를 건너뛰고, 서버의 로그에 이유를 기록하고, 서버의 다른 도구는 사용 가능하게 유지합니다. v2.1.195보다 이전 버전은 입력 스키마에 루트 수준의 `anyOf`, `oneOf` 또는 `allOf`가 있는 모든 도구를 건너뜁니다.

1056

1057<h2 id="require-approval-for-a-specific-tool">

1058 특정 도구에 대한 승인 필요

1059</h2>

1060

1061MCP 서버를 구축하는 경우 도구의 `tools/list` 응답 항목에서 `_meta["anthropic/requiresUserInteraction"]`을 `true`로 설정하여 도구를 모든 호출에서 명시적 승인이 필요한 것으로 표시할 수 있습니다. 값은 JSON 부울 `true`여야 하며, 다른 값은 무시됩니다.

1062

1063Claude Code는 `acceptEdits`, `auto`, `bypassPermissions` [권한 모드](/ko/permissions#permission-modes)에서도 해당 도구의 권한 프롬프트를 모든 호출에서 표시하고 "다시 묻지 않기" 옵션을 제공하지 않습니다. 도구와 일치하는 [허용 규칙](/ko/permissions#permission-rule-syntax)도 프롬프트를 건너뛰지 않습니다. `dontAsk` 모드에서는 프롬프트를 표시하지 않으므로 Claude Code는 호출을 거부합니다.

1064

1065프롬프트는 사람에게 도달해야 합니다. [`--permission-prompt-tool`](/ko/cli-reference#cli-flags)을 사용하는 비대화형 모드에서 플래그된 도구에 대한 프롬프트 도구의 `allow` 결과는 `MCP tool requires user interaction; not supported via --permission-prompt-tool` 메시지와 함께 거부로 변환됩니다. Agent SDK의 [`canUseTool` 콜백](/ko/agent-sdk/permissions)은 이러한 호출을 수신하고 승인할 수 있습니다. SDK 호스트는 사용자에게 이를 표시할 것으로 예상되기 때문입니다.

1066

1067이를 사용하여 권한 프롬프트 자체가 요점인 도구(예: 동의 또는 액세스 부여 단계)에 사용하세요. 자동 승인은 인간이 동의하지 않았다는 의미이기 때문입니다. 동일한 서버의 다른 도구는 정상적인 권한 동작을 유지합니다.

1068

1069다음 `tools/list` 항목은 한 도구를 항상 승인이 필요한 것으로 표시합니다.

1070

1071```json theme={null}

1072{

1073 "name": "grant_access",

1074 "description": "Requests access to a protected resource",

1075 "_meta": {

1076 "anthropic/requiresUserInteraction": true

1077 }

1078}

1079```

1080

1081`anthropic/requiresUserInteraction` 주석은 Claude Code v2.1.199 이상이 필요합니다. 이전 버전은 이를 무시하고 표준 권한 흐름을 적용합니다.

1082

1083세션이 [Remote Control](/ko/remote-control)에 연결되거나 SDK 호스트에 연결되면 Claude Code는 권한 요청을 사용자 상호작용이 필요한 것으로 표시하므로 클라이언트는 한 번의 탭 승인 작업 대신 도구의 권한 프롬프트를 표시합니다.

1084

1042<h2 id="respond-to-mcp-elicitation-requests">1085<h2 id="respond-to-mcp-elicitation-requests">

1043 MCP 리소스 요청에 응답1086 MCP elicitation 요청에 응답

1044</h2>1087</h2>

1045 1088

1046MCP 서버는 작업 중에 구조화된 입력을 요청할 수 있습니다(elicitation). 서버가 자체적으로 얻을 수 없는 정보가 필요할 때 Claude Code는 대화형 대화 상자를 표시하고 응답을 서버에 다시 전달합니다. 사용자 측에서 구성이 필요하지 않습니다: 서버가 요청할 때 elicitation 대화 상자가 자동으로 나타납니다.1089MCP 서버는 작업 중에 구조화된 입력을 요청할 수 있습니다(elicitation). 서버가 자체적으로 얻을 수 없는 정보가 필요할 때 Claude Code는 대화형 대화 상자를 표시하고 응답을 서버에 다시 전달합니다. 사용자 측에서 구성이 필요하지 않습니다: 서버가 요청할 때 elicitation 대화 상자가 자동으로 나타납니다.

memory.md +1 −1

Details

235- OpenAPI 문서 주석을 포함합니다235- OpenAPI 문서 주석을 포함합니다

236```236```

237 237

238`paths` 필드가 없는 규칙은 무조건 로드되며 모든 파일에 적용됩니다. 경로 범위 규칙은 모든 도구 사용 시가 아니라 Claude가 패턴과 일치하는 파일을 읽을 때 트리거됩니다.238`paths` 필드가 없는 규칙은 무조건 로드되며 모든 파일에 적용됩니다. 경로 범위 규칙은 모든 도구 사용 시가 아니라 Claude가 패턴과 일치하는 파일을 읽을 때 트리거됩니다. v2.1.198 이상에서는 예를 들어 프로젝트 디렉토리에 대한 심볼릭 링크된 경로를 통해 Claude가 파일에 도달할 때도 일치가 작동합니다.

239 239

240`paths` 필드에서 glob 패턴을 사용하여 확장명, 디렉토리 또는 조합으로 파일을 일치시킵니다:240`paths` 필드에서 glob 패턴을 사용하여 확장명, 디렉토리 또는 조합으로 파일을 일치시킵니다:

241 241

model-config.md +54 −8

Details

31 31

32| 모델 별칭 | 동작 |32| 모델 별칭 | 동작 |

33| ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |33| ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

84* `Enter`: 모델을 전환하고 기본값으로 저장합니다84* `Enter`: 모델을 전환하고 기본값으로 저장합니다

85* `s`: 이 세션에만 모델을 전환합니다85* `s`: 이 세션에만 모델을 전환합니다

86 86

~~87`/model <name>`을 직접 입력하면 `Enter`처럼 동작합니다. 프로젝트 및 관리되는 설정은 여전히 우선순위를 가지며 다음 실행 시 다시 적용됩니다.~~87`/model <name>`을 직접 입력하면 `Enter`처럼 동작합니다. 프로젝트 및 관리되는 설정은 여전히 우선순위를 가지며 다음 실행 시 다시 적용됩니다. {/* min-version: 2.1.196 */}관리자가 구성한 [조직 기본 모델](#organization-default-model)도 다음 실행 시 다시 적용됩니다.

88 88

89v2.1.144부터 v2.1.152까지는 `/model`이 현재 세션에만 적용되었으며 선택기에서 `d`가 기본값을 저장했습니다.89v2.1.144부터 v2.1.152까지는 `/model`이 현재 세션에만 적용되었으며 선택기에서 `d`가 기본값을 저장했습니다.

90 90

130* **메인 세션 모델**: `/model`, `--model` 플래그, `ANTHROPIC_MODEL` 환경 변수, `model` 설정 및 [세션을 재개할 때](#setting-your-model) 복원된 모델130* **메인 세션 모델**: `/model`, `--model` 플래그, `ANTHROPIC_MODEL` 환경 변수, `model` 설정 및 [세션을 재개할 때](#setting-your-model) 복원된 모델

131* **별칭 해석**: {/* min-version: 2.1.176 */}`ANTHROPIC_DEFAULT_OPUS_MODEL`, `ANTHROPIC_DEFAULT_SONNET_MODEL`, `ANTHROPIC_DEFAULT_HAIKU_MODEL` 및 `ANTHROPIC_DEFAULT_FABLE_MODEL` 환경 변수는 허용된 별칭을 목록 외부의 모델로 리디렉션할 수 없습니다131* **별칭 해석**: {/* min-version: 2.1.176 */}`ANTHROPIC_DEFAULT_OPUS_MODEL`, `ANTHROPIC_DEFAULT_SONNET_MODEL`, `ANTHROPIC_DEFAULT_HAIKU_MODEL` 및 `ANTHROPIC_DEFAULT_FABLE_MODEL` 환경 변수는 허용된 별칭을 목록 외부의 모델로 리디렉션할 수 없습니다

132* **빠른 모드**: {/* min-version: 2.1.176 */}`/fast`는 목록 외부의 Opus 모델로 암시적으로 전환될 때 토글을 거부하며, "is not in your organization's allowed models" 메시지를 표시합니다132* **빠른 모드**: {/* min-version: 2.1.176 */}`/fast`는 목록 외부의 Opus 모델로 암시적으로 전환될 때 토글을 거부하며, "is not in your organization's allowed models" 메시지를 표시합니다

133* **서브에이전트 모델**: [서브에이전트](/ko/sub-agents#choose-a-model) frontmatter의 `model` 필드, Agent 도구의 `model` 매개변수, `/agents`의 모델 선택기 및 `CLAUDE_CODE_SUBAGENT_MODEL`133* **서브에이전트 모델**: [서브에이전트](/ko/sub-agents#choose-a-model) frontmatter의 `model` 필드, Agent 도구의 `model` 매개변수, `CLAUDE_CODE_SUBAGENT_MODEL`, 그리고 v2.1.197 이하에서는 `/agents` 마법사의 모델 선택기 {/* max-version: 2.1.197 */}

134* **스킬 및 명령 모델**: [스킬 및 명령](/ko/skills)의 `model` frontmatter134* **스킬 및 명령 모델**: [스킬 및 명령](/ko/skills)의 `model` frontmatter

135* **어드바이저 모델**: 구성된 [`advisorModel`](/ko/advisor) 설정 및 `--advisor` 플래그135* **어드바이저 모델**: 구성된 [`advisorModel`](/ko/advisor) 설정 및 `--advisor` 플래그

136* **백그라운드 에이전트 모델**: [디스패치 선택기](/ko/agent-view)에서 선택된 모델136* **백그라운드 에이전트 모델**: [디스패치 선택기](/ko/agent-view)에서 선택된 모델

137 137

138`/model`로 차단된 모델로 전환하면 오류로 거부되고, 차단된 `--model` 플래그, `ANTHROPIC_MODEL` 또는 `model` 설정 값은 시작 시 요청된 모델과 대체된 모델을 모두 이름 지은 경고와 함께 대체되며 세션은 기본 모델에서 시작됩니다. 차단된 서브에이전트, 스킬 또는 명령 재정의는 요청을 실패하지 않고 상속되거나 기본 모델로 폴백됩니다. 차단된 `advisorModel` 설정은 세션에 대해 어드바이저를 비활성화하고, 차단된 `--advisor` 플래그 값은 시작 시 오류로 종료됩니다. 제외된 모델은 `/model` 선택기에서 숨겨집니다.138`/model`로 차단된 모델로 전환하면 오류로 거부되고, 차단된 `--model` 플래그, `ANTHROPIC_MODEL` 또는 `model` 설정 값은 시작 시 요청된 모델과 대체된 모델을 모두 이름 지은 경고와 함께 대체되며 세션은 기본 모델에서 시작됩니다. 차단된 서브에이전트, 스킬 또는 명령 재정의는 요청을 실패하지 않고 상속되거나 기본 모델로 폴백됩니다. 차단된 `advisorModel` 설정은 세션에 대해 어드바이저를 비활성화하고, 차단된 `--advisor` 플래그 값은 시작 시 오류로 종료됩니다. 제외된 모델은 `/model` 선택기에서 숨겨집니다. {/* min-version: 2.1.199 */}v2.1.199부터 목록의 전체 모델 ID(예: 목록이 고정하는 이전 버전)에 기본 제공 선택기 행이 없으면 `/model` 선택기에 자신의 레이블이 지정된 행으로 나타납니다. 이전 버전에서는 그러한 ID는 `/model <id>`를 입력하여만 선택 가능합니다.

139 139

140자동 모델 변경은 동일한 방식으로 확인됩니다: [폴백 모델 체인](#fallback-model-chains)의 허용 목록 외부 요소는 삭제되고, [`opusplan`](#opusplan-model-setting)과 같은 계획 모드 업그레이드는 제외된 모델로 건너뛰어 계획이 세션의 모델에서 계속되며, 대상이 제외된 [자동 모델 폴백](#automatic-model-fallback)은 실행되지 않으므로 플래그된 요청은 거부로 끝납니다. [빠른 모드](/ko/fast-mode)를 활성화하면 세션이 실행될 모델이 허용 목록 외부에 있을 때 거부됩니다.140자동 모델 변경은 동일한 방식으로 확인됩니다: [폴백 모델 체인](#fallback-model-chains)의 허용 목록 외부 요소는 삭제되고, [`opusplan`](#opusplan-model-setting)과 같은 계획 모드 업그레이드는 제외된 모델로 건너뛰어 계획이 세션의 모델에서 계속되며, 대상이 제외된 [자동 모델 폴백](#automatic-model-fallback)은 실행되지 않으므로 플래그된 요청은 거부로 끝납니다. [빠른 모드](/ko/fast-mode)를 활성화하면 세션이 실행될 모델이 허용 목록 외부에 있을 때 거부됩니다.

141 141

246 246

247두 제한은 함께 적용됩니다: 모델은 `availableModels`에 의해 허용되고 조직에 의해 제한되지 않을 때만 선택 가능합니다. 조직 제한은 Anthropic API 및 [LLM 게이트웨이](/ko/llm-gateway) 배포의 세션에 전달됩니다. Bedrock, Vertex AI, Foundry 및 Claude Platform on AWS의 세션은 이를 수신하지 않으므로 대신 해당 제공자에서 `availableModels`을 사용합니다.247두 제한은 함께 적용됩니다: 모델은 `availableModels`에 의해 허용되고 조직에 의해 제한되지 않을 때만 선택 가능합니다. 조직 제한은 Anthropic API 및 [LLM 게이트웨이](/ko/llm-gateway) 배포의 세션에 전달됩니다. Bedrock, Vertex AI, Foundry 및 Claude Platform on AWS의 세션은 이를 수신하지 않으므로 대신 해당 제공자에서 `availableModels`을 사용합니다.

248 248

249<h2 id="organization-default-model">

250 조직 기본 모델

251</h2>

252

253{/* plan-availability: feature=org-default-model plans=enterprise */}

254

255Claude Enterprise 플랜의 조직 관리자는 claude.ai 관리 콘솔에서 Claude Code 구성원에 대한 기본 모델을 설정할 수 있으며, 전체 조직 또는 사용자 정의 역할별로 설정할 수 있습니다. 하나가 설정되면 Default 옵션은 [계정 유형 기본값](#default-model-setting) 대신 해당 모델로 확인됩니다. Claude Code v2.1.196 이상이 필요합니다.

256

257`/model` 선택기의 Default 행은 조직 기본값의 이름을 "Org default" 레이블과 함께 표시합니다. 레이블은 관리자가 전체 조직 또는 역할에 대해 기본값을 설정했는지 여부에 관계없이 "Org default"를 읽습니다. 역할 기본값은 해당 사용자 정의 역할의 구성원을 다루며 조직 전체 기본값보다 우선합니다. 여러 역할이 다른 기본값을 설정하면 가장 강력한 모델이 적용됩니다.

258

259조직 기본값은 시작점이지 제한이 아니며, 다른 모델 선택은 이를 우선합니다:

260

261* `--model` 플래그 및 `ANTHROPIC_MODEL` 환경 변수

262* [관리 설정](/ko/settings#settings-files)의 `model` 값 또는 `--settings`를 통해 제공됨

263* 사용자, 프로젝트 또는 로컬 설정의 `model` 값(예: `/model`로 저장한 모델 포함)

264

265관리자는 또한 조직 기본값을 사용자 선택을 재정의하도록 구성할 수 있습니다. 재정의가 켜져 있으면 사용자, 프로젝트 및 로컬 설정의 `model` 값보다 우선하므로 `/model`로 저장한 모델은 현재 세션에 적용되고 조직 기본값은 다음 실행 시 반환됩니다. 선택이 다르면 `/model`은 `Your organization's default (<model>) applies on restart`를 표시합니다. `--model` 플래그, `ANTHROPIC_MODEL`, 관리 설정 및 `--settings`는 재정의가 켜져 있어도 여전히 우선합니다. 재정의는 제한된 조직 집합에서 사용 가능합니다. Anthropic 계정 팀에 가용성을 문의하세요.

266

267구성원이 선택할 수 있는 모델을 제한하려면 [조직 모델 제한](#organization-model-restrictions) 또는 [`availableModels`](#restrict-model-selection)을 대신 사용합니다.

268

269Claude Code는 시작 시 조직 기본값을 한 번 읽으므로 관리자가 중간 세션에서 변경한 기본값은 다음 실행 시 적용됩니다.

270

271조직 기본값이 사용자 선택을 재정의하지 않으면 관리자가 변경한 후 첫 번째 대화형 실행은 사용자 설정에서 `model` 키를 한 번 제거하므로 새 기본값이 적용됩니다. 파일의 다른 것은 변경하지 않으며, 그 이후 실행에서 `/model`로 저장한 모델은 유지됩니다.

272

273조직 기본값은 채택되기 전에 다른 Default 모델과 동일한 제한 확인을 통과합니다:

274

275* [`availableModels`](#restrict-model-selection)은 자체적으로 Default 옵션을 제한하지 않으므로 허용 목록 외부의 조직 기본값은 여전히 적용됩니다. [`enforceAvailableModels`](#enforce-the-allowlist-for-the-default-model)도 설정되면 허용 목록 외부의 조직 기본값은 다른 Default처럼 첫 번째 허용 목록 항목으로 재매핑됩니다

276* [조직 모델 제한](#organization-model-restrictions)이 계정에 대해 거부하는 조직 기본값은 해당 패밀리의 최신 허용 모델로 대체되거나 모든 버전이 제한될 때 더 낮은 비용 패밀리로 대체됩니다

277* [제로 데이터 보존](/ko/zero-data-retention) 하의 Fable 5와 같이 계정에서 전혀 사용할 수 없는 조직 기본값은 건너뛰어지고 Default 옵션은 계정 유형 기본값으로 확인됩니다

278

279v2.1.199부터 조직 기본값이 계정 유형의 일반적인 기본값과 다른 모델 패밀리인 경우 `/model` 선택기는 해당 일반적인 패밀리에 대한 별도의 행을 유지하므로 세션에 대해 여전히 전환할 수 있습니다. v2.1.196부터 v2.1.198까지 해당 행은 선택기에서 누락됩니다.

280

281조직 기본값은 Anthropic API로 인증된 세션에 전달됩니다. [LLM 게이트웨이](/ko/llm-gateway) 배포, Amazon Bedrock, Google Cloud의 Agent Platform, Microsoft Foundry 및 Claude Platform on AWS의 세션은 이를 수신하지 않습니다. 해당 배포에서 기본값을 설정하려면 [관리 설정](/ko/settings#settings-files)에서 `model` 키를 대신 사용합니다.

282

283<h2 id="organization-effort-limits">

284 조직 노력 제한

285</h2>

286

287{/* plan-availability: feature=org-effort-limits plans=enterprise */}

288

289Claude Enterprise 플랜의 조직 관리자는 [조직 모델 제한](#organization-model-restrictions)과 함께 각 사용자 정의 역할에 대해 모델별 최대 [노력 수준](#adjust-effort-level)을 설정할 수 있습니다. 상한 이상의 수준은 `/effort` 선택기에서 제공되지 않으며, `--effort` 또는 `/effort`로 더 높은 수준을 이름 지으면 상한에서 실행됩니다. 대화형 세션 및 일반 텍스트 `--print` 실행에서 경고는 요청된 수준과 적용된 수준을 이름 지으며, `json` 또는 `stream-json` 출력 또는 백그라운드 에이전트에서 클램프는 자동으로 적용됩니다. 상한은 모델별이므로 모델을 전환하면 사용 가능한 수준이 변경될 수 있습니다. 여러 역할이 동일한 모델을 부여하면 가장 제한이 적은 상한이 적용됩니다. Claude Code v2.1.195 이상이 필요합니다.

290

291노력 제한은 [조직 모델 제한](#organization-model-restrictions)과 함께 전달되며 동일한 제공자 가용성을 따릅니다: Amazon Bedrock, Google Cloud의 Agent Platform, Microsoft Foundry 및 Claude Platform on AWS의 세션은 이를 수신하지 않습니다.

292

249<h2 id="special-model-behavior">293<h2 id="special-model-behavior">

250 특수 모델 동작294 특수 모델 동작

251</h2>295</h2>

263 307

264Enterprise 종량제는 구독 시트가 아닌 사용량으로 청구되는 Enterprise 조직을 의미합니다.308Enterprise 종량제는 구독 시트가 아닌 사용량으로 청구되는 Enterprise 조직을 의미합니다.

265 309

266관리 설정이 [Default 모델에 대한 허용 목록을 적용](#enforce-the-allowlist-for-the-default-model)하고 계정 유형 기본값이 `availableModels`에 없을 때 `default`는 위의 계정 유형 기본값 대신 적용된 Default로 확인됩니다.310관리자가 [조직 기본 모델](#organization-default-model)을 설정한 경우 `default`는 위의 계정 유형 기본값 대신 해당 모델로 확인됩니다. Claude Code v2.1.196 이상이 필요합니다.

311

312관리 설정이 [Default 모델에 대한 허용 목록을 적용](#enforce-the-allowlist-for-the-default-model)하고 계정 유형 기본값이 `availableModels`에 없을 때 `default`는 위의 계정 유형 기본값 대신 적용된 Default로 확인됩니다. 둘 다 적용되면 조직 기본값이 계정 유형 기본값을 먼저 대체하고 강제가 이에 적용됩니다: 허용 목록에 있는 조직 기본값은 유지되고, 목록 외부의 것은 적용된 Default로 확인됩니다.

267 313

268Fable 5는 어떤 계정 유형에서도 기본 모델이 아닙니다. 세션은 `/model fable`, `model` 설정 또는 Fable 5를 사용할 수 있는 `best` 별칭으로 선택한 후에만 Fable 5를 사용합니다. `/model`로 선택하면 사용자 설정에서 선택된 모델로 저장되므로 모델을 변경할 때까지 이후 세션이 Fable 5에서 시작됩니다.314Fable 5는 어떤 계정 유형에서도 기본 모델이 아닙니다. 세션은 `/model fable`, `model` 설정 또는 Fable 5를 사용할 수 있는 `best` 별칭으로 선택한 후에만 Fable 5를 사용합니다. `/model`로 선택하면 사용자 설정에서 선택된 모델로 저장되므로 모델을 변경할 때까지 이후 세션이 Fable 5에서 시작됩니다.

269 315

273 319

274`opusplan` 모델 별칭은 자동화된 하이브리드 접근 방식을 제공합니다:320`opusplan` 모델 별칭은 자동화된 하이브리드 접근 방식을 제공합니다:

275 321

276* **Plan Mode에서** - 복잡한 추론 및 아키텍처 결정을 위해 `opus` 사용322* **Plan Mode에서**: 복잡한 추론 및 아키텍처 결정을 위해 `opus` 사용

277* **실행 모드에서** - 코드 생성 및 구현을 위해 자동으로 `sonnet`으로 전환323* **실행 모드에서**: 코드 생성 및 구현을 위해 자동으로 `sonnet`으로 전환

278 324

279이는 계획을 위한 Opus의 우수한 추론과 실행을 위한 Sonnet의 효율성이라는 두 가지 장점을 모두 제공합니다.325이는 계획을 위한 Opus의 우수한 추론과 실행을 위한 Sonnet의 효율성이라는 두 가지 장점을 모두 제공합니다.

280 326

381 427

382활성 모델이 지원하지 않는 수준을 설정하면 Claude Code는 설정한 수준 이하의 가장 높은 지원 수준으로 폴백합니다. 예를 들어 `xhigh`는 Opus 4.6에서 `high`로 실행됩니다.428활성 모델이 지원하지 않는 수준을 설정하면 Claude Code는 설정한 수준 이하의 가장 높은 지원 수준으로 폴백합니다. 예를 들어 `xhigh`는 Opus 4.6에서 `high`로 실행됩니다. 조직은 또한 모델에 대해 사용 가능한 수준을 제한할 수 있습니다. [조직 노력 제한](#organization-effort-limits)을 참조하세요.

383 429

384기본 노력은 Fable 5, Sonnet 5, Opus 4.8, Opus 4.6 및 Sonnet 4.6에서 `high`이고 Opus 4.7에서 `xhigh`입니다.430기본 노력은 Fable 5, Sonnet 5, Opus 4.8, Opus 4.6 및 Sonnet 4.6에서 `high`이고 Opus 4.7에서 `xhigh`입니다.

385 431

monitoring-usage.md +1 −1

Details

1184 1184

1185Claude Code는 실패한 API 요청을 내부적으로 재시도하고 포기한 후에만 단일 `claude_code.api_error` 이벤트를 내보내므로 이벤트 자체가 해당 요청의 최종 신호입니다. 중간 재시도 시도는 별도의 이벤트로 기록되지 않습니다.1185Claude Code는 실패한 API 요청을 내부적으로 재시도하고 포기한 후에만 단일 `claude_code.api_error` 이벤트를 내보내므로 이벤트 자체가 해당 요청의 최종 신호입니다. 중간 재시도 시도는 별도의 이벤트로 기록되지 않습니다.

1186 1186

1187이벤트의 `attempt` 속성은 총 시도 횟수를 기록합니다. `CLAUDE_CODE_MAX_RETRIES`는 기본값이 10이고 최대 15입니다. 요청이 일시적 오류에 대한 모든 재시도를 소진하면 `attempt`는 해당 유효 제한보다 하나 많습니다: 기본값으로는 11이고 16을 초과하지 않습니다. 더 낮은 값은 `400` 응답과 같은 재시도 불가능한 오류를 나타냅니다.1187이벤트의 `attempt` 속성은 총 시도 횟수를 기록합니다. `CLAUDE_CODE_MAX_RETRIES`는 기본값이 10이고 최대 15입니다. v2.1.199부터 `CLAUDE_CODE_RETRY_WATCHDOG`은 기본값을 높이고 상한을 제거합니다. 요청이 일시적 오류에 대한 모든 재시도를 소진하면 `attempt`는 해당 유효 제한보다 하나 많습니다: 기본값으로는 11이고 감시 기능이 설정되지 않은 경우 16을 초과하지 않습니다. 더 낮은 값은 `400` 응답과 같은 재시도 불가능한 오류를 나타냅니다.

1188 1188

1189복구된 세션과 정체된 세션을 구분하려면 `session.id`로 이벤트를 그룹화하고 오류 후 나중에 `api_request` 이벤트가 존재하는지 확인합니다.1189복구된 세션과 정체된 세션을 구분하려면 `session.id`로 이벤트를 그룹화하고 오류 후 나중에 `api_request` 이벤트가 존재하는지 확인합니다.

1190 1190

permission-modes.md +22 −7

Details

237* 강제 푸시 또는 `main`에 직접 푸시237* 강제 푸시 또는 `main`에 직접 푸시

238* {/* min-version: 2.1.182 */}`git reset --hard`, `git checkout -- .`, `git restore .`, `git clean -fd`, `git stash drop`, 또는 `git stash clear`. 분류기는 이들이 커밋되지 않은 변경 사항을 삭제할 것으로 추정합니다238* {/* min-version: 2.1.182 */}`git reset --hard`, `git checkout -- .`, `git restore .`, `git clean -fd`, `git stash drop`, 또는 `git stash clear`. 분류기는 이들이 커밋되지 않은 변경 사항을 삭제할 것으로 추정합니다

239* `git commit --amend` (HEAD의 커밋이 이 세션에서 생성되지 않은 경우)239* `git commit --amend` (HEAD의 커밋이 이 세션에서 생성되지 않은 경우)

240* {/* min-version: 2.1.198 */}}v2.1.198부터, `git commit --amend` (HEAD의 커밋이 이미 푸시된 경우). 메시지 전용 리워드는 차단되지 않습니다: `--amend -m` (새로 스테이징된 것이 없음, Claude가 이 세션 중에 생성한 커밋)

240* `terraform destroy`, `pulumi destroy`, `cdk destroy`, 또는 `terragrunt destroy`, 그리고 리소스를 삭제하는 계획 적용241* `terraform destroy`, `pulumi destroy`, `cdk destroy`, 또는 `terragrunt destroy`, 그리고 리소스를 삭제하는 계획 적용

241 242

242Claude Code v2.1.195 이상은 기본적으로 더 많은 카테고리를 차단합니다. 여러 개는 민감한 원격 대상 및 보호된 IaC 범위와 같은 [환경](/ko/auto-mode-config#define-trusted-infrastructure) 항목에 따라 달라지며, 이를 구체적인 이름으로 좁힐 수 있습니다.243Claude Code v2.1.195 이상은 기본적으로 더 많은 카테고리를 차단합니다. 여러 개는 민감한 원격 대상 및 보호된 IaC 범위와 같은 [환경](/ko/auto-mode-config#define-trusted-infrastructure) 항목에 따라 달라지며, 이를 구체적인 이름으로 좁힐 수 있습니다.

251* 민감한 원격 대상으로의 대화형 셸 또는 포트 포워드252* 민감한 원격 대상으로의 대화형 셸 또는 포트 포워드

252* 로컬 서비스를 공개 인터넷에서 도달 가능하게 하는 터널 또는 역 셸 열기253* 로컬 서비스를 공개 인터넷에서 도달 가능하게 하는 터널 또는 역 셸 열기

253* 기록 또는 파일에 라이브 자격 증명 또는 토큰 인쇄254* 기록 또는 파일에 라이브 자격 증명 또는 토큰 인쇄

254* PII 또는 규제 데이터 위치 액세스, 또는 데이터를 외부로 복사255* [환경](/ko/auto-mode-config#define-trusted-infrastructure)에 민감한 데이터 위치로 나열된 위치 액세스, 또는 데이터를 외부로 복사. {/* min-version: 2.1.198 */}v2.1.198부터 이는 또한 한 위치에서 항목이 제외하는 대상으로 데이터를 전송하는 것을 차단합니다

255* 패키지 설치를 내부 패키지 레지스트리 주위로 라우팅하여 공개 레지스트리로 이동256* 패키지 설치를 내부 패키지 레지스트리 주위로 라우팅하여 공개 레지스트리로 이동. {/* min-version: 2.1.198 */}v2.1.198부터 이는 또한 환경에 나열되지 않은 경우에도 대화에서 내부 레지스트리 또는 미러가 존재한다고 Claude에게 말한 경우에 적용됩니다

256* `--insecure`와 같이 안전 가드를 해제하는 플래그로 명령 실행257* `--insecure`와 같이 안전 가드를 해제하는 플래그로 명령 실행

258* `--dangerously-skip-permissions` 또는 `--no-sandbox`로 시작된 것과 같이 인간 승인 또는 샌드박스 없이 실행되는 자율 에이전트 루프 시작. {/* min-version: 2.1.198 */}v2.1.198부터 이는 또한 `--yes-always`로 시작된 러너와 같이 격리 및 작업별 승인이 비활성화된 제3자 에이전트 또는 평가 하네스 실행을 포함합니다

257* [Chrome의 Claude](/ko/chrome) 브라우저 작업으로 페이지 콘텐츠, 쿠키, 또는 자격 증명을 원본 외부로 전송할 수 있음259* [Chrome의 Claude](/ko/chrome) 브라우저 작업으로 페이지 콘텐츠, 쿠키, 또는 자격 증명을 원본 외부로 전송할 수 있음

258 260

261Claude Code v2.1.198 이상은 또한 기본적으로 다음을 차단합니다:

262

263* 와일드카드, glob, 또는 나이 필터가 아닌 특정 명명된 경로로 `/tmp`, `$TMPDIR`, 또는 다른 공유 스크래치 또는 캐시 디렉토리의 파일 삭제

264* 자신의 메시지가 해당 수신자에게 해당 세부 정보를 승인하지 않은 경우, 전송, 업로드, 게시, 또는 다른 사람이나 공유 시스템에 작성된 콘텐츠에 민감한 세부 정보 포함

265* Claude Code의 자체 tmux 창으로 키스트로크 전송하여 자체 인터페이스를 구동하는 것. 분류기는 이를 Claude가 자체 권한 또는 감시를 변경하는 것으로 취급합니다

266

259**기본적으로 허용됨**:267**기본적으로 허용됨**:

260 268

261* 작업 디렉토리의 로컬 파일 작업269* 작업 디렉토리의 로컬 파일 작업

272* [`environment`](/ko/auto-mode-config#define-trusted-infrastructure)에 나열한 신뢰할 수 있는 도메인, 버킷, 서비스로 데이터 전송. 이는 같은 인프라에 대한 파괴적이거나 자격 증명 작업이 아닌 데이터 흐름만 포함합니다280* [`environment`](/ko/auto-mode-config#define-trusted-infrastructure)에 나열한 신뢰할 수 있는 도메인, 버킷, 서비스로 데이터 전송. 이는 같은 인프라에 대한 파괴적이거나 자격 증명 작업이 아닌 데이터 흐름만 포함합니다

273* [Chrome의 Claude](/ko/chrome)를 신뢰할 수 있는 내부 도메인, localhost, 또는 이름을 지정한 URL로 탐색281* [Chrome의 Claude](/ko/chrome)를 신뢰할 수 있는 내부 도메인, localhost, 또는 이름을 지정한 URL로 탐색

274 282

275샌드박스 네트워크 액세스 요청은 기본적으로 허용되는 대신 분류기를 통해 라우팅됩니다. `claude auto-mode defaults`를 실행하여 전체 규칙 목록을 확인합니다. 일상적인 작업이 차단되면, 관리자는 `autoMode.environment` 설정을 통해 신뢰할 수 있는 리포지토리, 버킷, 서비스를 추가할 수 있습니다: [자동 모드 구성](/ko/auto-mode-config)을 참조합니다.283샌드박스 네트워크 액세스 요청은 기본적으로 허용되는 대신 분류기를 통해 라우팅됩니다. {/* min-version: 2.1.198 */}v2.1.198부터 분류기는 모든 연결에서 다시 실행하는 대신 네트워크 호스트 및 포트에 대한 판정을 재사용합니다:

284

285* 허용은 새 콘텐츠가 대화에 들어올 때까지 재사용되며, 그 시점에서 해당 호스트가 다시 확인됩니다

286* 대화형 CLI에서, 거부는 턴이 끝날 때 삭제됩니다

287* [비대화형 모드](/ko/headless) 및 Agent SDK 세션에서는 턴 경계가 없으므로, 거부는 실행의 나머지 동안 재사용됩니다

288* 권한 모드 또는 규칙을 변경하면 모든 캐시된 판정이 삭제됩니다

289

290`claude auto-mode defaults`를 실행하여 전체 규칙 목록을 확인합니다. 일상적인 작업이 차단되면, 관리자는 `autoMode.environment` 설정을 통해 신뢰할 수 있는 리포지토리, 버킷, 서비스를 추가할 수 있습니다: [자동 모드 구성](/ko/auto-mode-config)을 참조합니다.

276 291

277<h3 id="boundaries-you-state-in-conversation">292<h3 id="boundaries-you-state-in-conversation">

278 대화에서 명시한 경계293 대화에서 명시한 경계

300 315

301 1. [허용 또는 거부 규칙](/ko/permissions#manage-permissions)과 일치하는 작업은 즉시 해결됩니다. [보호된 경로](#protected-paths)에 대한 쓰기는 제외되며, 허용 규칙이 일치하더라도 분류기로 라우팅됩니다316 1. [허용 또는 거부 규칙](/ko/permissions#manage-permissions)과 일치하는 작업은 즉시 해결됩니다. [보호된 경로](#protected-paths)에 대한 쓰기는 제외되며, 허용 규칙이 일치하더라도 분류기로 라우팅됩니다

302 2. 읽기 전용 작업 및 작업 디렉토리의 파일 편집은 자동 승인됩니다. [보호된 경로](#protected-paths)에 대한 쓰기는 제외됩니다317 2. 읽기 전용 작업 및 작업 디렉토리의 파일 편집은 자동 승인됩니다. [보호된 경로](#protected-paths)에 대한 쓰기는 제외됩니다

303 3. 다른 모든 것은 분류기로 이동합니다318 3. 다른 모든 것은 분류기로 이동합니다. {/* min-version: 2.1.199 */}v2.1.199부터, [`_meta["anthropic/requiresUserInteraction"]`](/ko/mcp#require-approval-for-a-specific-tool)로 표시된 MCP 도구는 분류기를 건너뛰고 직접 프롬프트하므로, 동의 단계는 도구 작성자를 대신하여 자동 승인되지 않습니다

304 4. 분류기가 차단하면, Claude는 이유를 받고 대체 방법을 시도합니다319 4. 분류기가 차단하면, Claude는 이유를 받고 대체 방법을 시도합니다

305 320

306 자동 모드에 들어가면, 임의의 코드 실행을 부여하는 광범위한 허용 규칙이 삭제됩니다:321 자동 모드에 들어가면, 임의의 코드 실행을 부여하는 광범위한 허용 규칙이 삭제됩니다:

326 </Accordion>341 </Accordion>

327 342

328 <Accordion title="비용 및 지연">343 <Accordion title="비용 및 지연">

329 분류기는 `/model` 선택과 독립적인 서버 구성 모델에서 실행되므로, 모델을 전환해도 분류기 가용성이 변경되지 않습니다. 분류기 호출은 토큰 사용량으로 계산됩니다. 각 검사는 기록의 일부와 보류 중인 작업을 전송하여 실행 전에 왕복을 추가합니다. 읽기 및 보호된 경로 외의 작업 디렉토리 편집은 분류기를 건너뛰므로, 오버헤드는 주로 셸 명령 및 네트워크 작업에서 발생합니다.344 분류기는 `/model` 선택과 독립적인 서버 구성 모델에서 실행되므로, 모델을 전환해도 분류기 가용성이 변경되지 않습니다. 분류기 호출은 토큰 사용량으로 계산됩니다. 각 검사는 기록의 일부와 보류 중인 작업을 전송하여 실행 전에 왕복을 추가합니다. 읽기 및 보호된 경로 외의 작업 디렉토리 편집은 분류기를 건너뛰므로, 오버헤드는 주로 셸 명령 및 네트워크 작업에서 발생합니다. {/* min-version: 2.1.198 */}v2.1.198부터 호스트 및 포트에 대한 샌드박스 네트워크 판정은 모든 연결에서 다시 분류되는 대신 재사용되므로, 같은 호스트에 대한 반복된 연결은 각각 검사를 추가하지 않습니다. [분류기가 기본적으로 차단하는 항목](#what-the-classifier-blocks-by-default)은 허용 및 거부가 지속되는 기간을 설명합니다.

330 </Accordion>345 </Accordion>

331</AccordionGroup>346</AccordionGroup>

332 347

334 dontAsk 모드로 사전 승인된 도구만 허용349 dontAsk 모드로 사전 승인된 도구만 허용

335</h2>350</h2>

336 351

337`dontAsk` 모드는 그렇지 않으면 프롬프트할 모든 도구 호출을 자동 거부합니다. `permissions.allow` 규칙과 일치하는 작업 및 [읽기 전용 Bash 명령](/ko/permissions#read-only-commands)만 실행할 수 있습니다. 명시적 [`ask` 규칙](/ko/permissions#manage-permissions)은 프롬프트하는 대신 거부됩니다. 이는 모드를 완전히 비대화형으로 만들어 CI 파이프라인 또는 Claude가 정확히 수행할 수 있는 작업을 사전 정의하는 제한된 환경에 적합합니다. [Claude Code on the web](/ko/claude-code-on-the-web)의 클라우드 세션은 `defaultMode: "dontAsk"`를 무시합니다. 자세한 내용은 [bypassPermissions](#skip-all-checks-with-bypasspermissions-mode)를 참조하십시오.352`dontAsk` 모드는 그렇지 않으면 프롬프트할 모든 도구 호출을 자동 거부합니다. 상태 표시줄에는 이 모드가 활성화되어 있는 동안 `⏵⏵ don't ask on`이 표시됩니다. `permissions.allow` 규칙과 [읽기 전용 Bash 명령](/ko/permissions#read-only-commands)과 일치하는 작업만 실행할 수 있습니다. 명시적 [`ask` 규칙](/ko/permissions#manage-permissions)은 프롬프트하는 대신 거부됩니다. {/* min-version: 2.1.199 */}v2.1.199부터 [`_meta["anthropic/requiresUserInteraction"]`](/ko/mcp#require-approval-for-a-specific-tool)로 표시된 MCP 도구는 allow 규칙이 일치하더라도 이 모드에서 거부됩니다. 왜냐하면 승인 카드가 이 모드에서 수집하지 않는 답변이 필요하기 때문입니다. 이는 모드를 완전히 비대화형으로 만들어 CI 파이프라인 또는 Claude가 정확히 수행할 수 있는 작업을 사전 정의하는 제한된 환경에 적합합니다. [Claude Code on the web](/ko/claude-code-on-the-web)의 클라우드 세션은 `defaultMode: "dontAsk"`를 무시합니다. 자세한 내용은 [bypassPermissions](#skip-all-checks-with-bypasspermissions-mode)를 참조하십시오.

338 353

339시작 시 플래그로 설정합니다:354시작 시 플래그로 설정합니다:

340 355

346 bypassPermissions 모드로 모든 검사 건너뛰기361 bypassPermissions 모드로 모든 검사 건너뛰기

347</h2>362</h2>

348 363

349`bypassPermissions` 모드는 권한 프롬프트 및 안전 검사를 비활성화하여 도구 호출이 즉시 실행되도록 합니다. v2.1.126부터 이는 [보호된 경로](#protected-paths)에 대한 쓰기를 포함하며, 이전 버전은 여전히 프롬프트를 표시합니다. 명시적 [요청 규칙](/ko/permissions#manage-permissions)은 여전히 이 모드에서 프롬프트를 강제하며, 파일 시스템 루트 또는 홈 디렉터리를 대상으로 하는 제거(예: `rm -rf /` 및 `rm -rf ~`)는 모델 오류에 대한 차단기로서 여전히 프롬프트를 표시합니다. 인터넷 액세스가 없는 컨테이너, VM 또는 개발 컨테이너와 같은 격리된 환경에서만 이 모드를 사용하십시오. 여기서 Claude Code는 호스트 시스템에 손상을 줄 수 없습니다.364`bypassPermissions` 모드는 권한 프롬프트 및 안전 검사를 비활성화하여 도구 호출이 즉시 실행되도록 합니다. v2.1.126부터 이는 [보호된 경로](#protected-paths)에 대한 쓰기를 포함하며, 이전 버전은 여전히 프롬프트를 표시합니다. 명시적 [요청 규칙](/ko/permissions#manage-permissions)은 여전히 이 모드에서 프롬프트를 강제하며, 파일 시스템 루트 또는 홈 디렉터리를 대상으로 하는 제거(예: `rm -rf /` 및 `rm -rf ~`)는 모델 오류에 대한 차단기로서 여전히 프롬프트를 표시합니다. {/* min-version: 2.1.199 */}v2.1.199부터 [`_meta["anthropic/requiresUserInteraction"]`](/ko/mcp#require-approval-for-a-specific-tool)로 표시된 MCP 도구도 여전히 프롬프트를 표시합니다. 인터넷 액세스가 없는 컨테이너, VM 또는 개발 컨테이너와 같은 격리된 환경에서만 이 모드를 사용하십시오. 여기서 Claude Code는 호스트 시스템에 손상을 줄 수 없습니다.

350 365

351활성화 플래그 중 하나로 시작한 세션에서 `bypassPermissions`에 들어갈 수 없습니다. 활성화하려면 다시 시작하십시오:366활성화 플래그 중 하나로 시작한 세션에서 `bypassPermissions`에 들어갈 수 없습니다. 활성화하려면 다시 시작하십시오:

352 367

permissions.md +14 −3

Details

272Read 및 Edit 규칙은 모두 [gitignore](https://git-scm.com/docs/gitignore) 사양을 따르며 4가지 고유한 패턴 유형이 있습니다:272Read 및 Edit 규칙은 모두 [gitignore](https://git-scm.com/docs/gitignore) 사양을 따르며 4가지 고유한 패턴 유형이 있습니다:

273 273

274| 패턴 | 의미 | 예시 | 일치 |274| 패턴 | 의미 | 예시 | 일치 |

275| ------------------ | ---------------- | -------------------------------- | ------------------------------ |275| ------------------ | ---------------- | -------------------------------- | -------------------------------------- |

276| `//path` | 파일 시스템 루트의 절대 경로 | `Read(//Users/alice/secrets/**)` | `/Users/alice/secrets/**` |276| `//path` | 파일 시스템 루트의 절대 경로 | `Read(//Users/alice/secrets/**)` | `/Users/alice/secrets/**` |

277| `~/path` | 홈 디렉토리의 경로 | `Read(~/Documents/*.pdf)` | `/Users/alice/Documents/*.pdf` |277| `~/path` | 홈 디렉토리의 경로 | `Read(~/Documents/*.pdf)` | `/Users/alice/Documents/*.pdf` |

278| `/path` | 프로젝트 루트에 상대적인 경로 | `Edit(/src/**/*.ts)` | `<project root>/src/**/*.ts` |278| `/path` | 설정 소스에 상대적인 경로 | `Edit(/src/**/*.ts)` | `<project root>/src/**/*.ts` (프로젝트 설정) |

279| `path` 또는 `./path` | 현재 디렉토리에 상대적인 경로 | `Read(*.env)` | `<cwd>/*.env` |279| `path` 또는 `./path` | 현재 디렉토리에 상대적인 경로 | `Read(*.env)` | `<cwd>/*.env` |

280 280

281<Warning>281<Warning>

282 `/Users/alice/file`과 같은 패턴은 절대 경로가 아닙니다. 프로젝트 루트에 상대적입니다. 절대 경로의 경우 `//Users/alice/file`을 사용합니다.282 `/Users/alice/file`과 같은 패턴은 절대 경로가 아닙니다. 단일 슬래시는 설정 소스에 앵커됩니다. 절대 경로의 경우 `//Users/alice/file`을 사용합니다.

283</Warning>283</Warning>

284 284

285`/path` 패턴은 설정 파일이 정의된 디렉토리에 앵커되므로 동일한 규칙은 배치 위치에 따라 다른 위치와 일치합니다:

286

287| 규칙 정의 위치 | `/path` 해석 |

288| :---------------------------------------- | :------------------------- |

289| `.claude/settings.json`과 같은 프로젝트 또는 로컬 설정 | `<project root>/path` |

290| `~/.claude/settings.json`의 사용자 설정 | `~/.claude/path` |

291| `--settings <file>`로 전달된 파일 | `<directory of file>/path` |

292| CLI 플래그, `/permissions` 또는 세션 규칙 | `<original cwd>/path` |

293

294deny 규칙(예: 사용자 설정의 `Read(/secrets//**)`)은 프로젝트의 `secrets` 디렉토리가 아니라 `~/.claude/secrets/**`를 차단합니다. 모든 프로젝트 내에서 적용되는 사용자 설정의 규칙을 작성하려면 `//` 절대 경로 또는 `~/` 홈 상대 경로를 대신 사용합니다.

295

285Windows에서 경로는 일치하기 전에 POSIX 형식으로 정규화됩니다. `C:\Users\alice`는 `/c/Users/alice`가 되므로 `//c/**/.env`를 사용하여 해당 드라이브의 어디든 `.env` 파일과 일치시킵니다. 모든 드라이브에서 일치시키려면 `//**/.env`를 사용합니다.296Windows에서 경로는 일치하기 전에 POSIX 형식으로 정규화됩니다. `C:\Users\alice`는 `/c/Users/alice`가 되므로 `//c/**/.env`를 사용하여 해당 드라이브의 어디든 `.env` 파일과 일치시킵니다. 모든 드라이브에서 일치시키려면 `//**/.env`를 사용합니다.

286 297

287예시:298예시:

plugins.md +2 −2

Details

352플러그인을 변경할 때 `/reload-plugins`를 실행하여 다시 시작하지 않고 업데이트를 적용합니다. 이는 플러그인, skills, agents, hooks, 플러그인 MCP servers, 플러그인 LSP servers를 다시 로드합니다. 플러그인 구성 요소를 테스트합니다:352플러그인을 변경할 때 `/reload-plugins`를 실행하여 다시 시작하지 않고 업데이트를 적용합니다. 이는 플러그인, skills, agents, hooks, 플러그인 MCP servers, 플러그인 LSP servers를 다시 로드합니다. 플러그인 구성 요소를 테스트합니다:

353 353

354* `/plugin-name:skill-name`으로 skills를 시도해보세요354* `/plugin-name:skill-name`으로 skills를 시도해보세요

355* agents가 `/agents`에 나타나는지 확인하세요355* agents가 `/context`의 Custom Agents 아래에 나타나는지 확인하거나 범위가 지정된 이름으로 @-mention하세요

356* hooks가 예상대로 작동하는지 확인하세요356* hooks가 예상대로 작동하는지 확인하세요

357 357

358<Tip>358<Tip>

502 claude --plugin-dir ./my-plugin502 claude --plugin-dir ./my-plugin

503 ```503 ```

504 504

505 각 구성 요소를 테스트합니다: 명령을 실행하고, agents가 `/agents`에 나타나는지 확인하고, hooks가 올바르게 트리거되는지 확인합니다.505 각 구성 요소를 테스트합니다: 명령을 실행하고, agents가 `/context`에 나타나는지 확인하고, hooks가 올바르게 트리거되는지 확인합니다.

506 </Step>506 </Step>

507</Steps>507</Steps>

508 508

plugins-reference.md +1 −1

Details

79 79

80**통합 지점**:80**통합 지점**:

81 81

~~82* Agents는 `/agents` 인터페이스에 나타납니다.~~82* Agents는 [@-mention 타입어헤드](/ko/sub-agents#invoke-subagents-explicitly)에 `my-plugin:code-reviewer`와 같은 범위가 지정된 이름으로 나타나며, 플러그인이 활성화되면 표시됩니다.

83* Claude는 작업 컨텍스트에 따라 agents를 자동으로 호출할 수 있습니다.83* Claude는 작업 컨텍스트에 따라 agents를 자동으로 호출할 수 있습니다.

84* Agents는 사용자가 수동으로 호출할 수 있습니다.84* Agents는 사용자가 수동으로 호출할 수 있습니다.

85* 플러그인 agents는 기본 제공 Claude agents와 함께 작동합니다.85* 플러그인 agents는 기본 제공 Claude agents와 함께 작동합니다.

sandboxing.md +42 −4

Details

199 자격증명 보호199 자격증명 보호

200</h3>200</h3>

201 201

202`sandbox.credentials` 설정은 샌드박싱된 명령이 액세스하면 안 되는 자격증명 파일 및 환경 변수를 선언합니다. 나열된 파일 경로는 샌드박스 내에서 읽기가 거부되며, `filesystem.denyRead`가 적용하는 것과 동일한 제한이고, 나열된 환경 변수는 각 샌드박싱된 명령 실행 전에 설정 해제됩니다. 전용 `credentials` 블록은 자격증명 규칙을 환경 변수 설정 해제와 함께 그룹화하고 일반 파일시스템 규칙과 분리합니다. Claude Code v2.1.187 이상이 필요합니다.202`sandbox.credentials` 설정은 샌드박싱된 명령이 액세스하면 안 되는 자격증명 파일 및 환경 변수를 선언합니다. 각 항목은 파일 경로 또는 환경 변수와 `mode`를 지정합니다. 전용 `credentials` 블록은 자격증명 규칙을 함께 그룹화하고 일반 파일시스템 규칙과 분리합니다. Claude Code v2.1.187 이상이 필요합니다.

203

204`"mode": "deny"`를 사용하는 항목의 경우 파일 경로는 샌드박스 내에서 읽기가 거부되며, 이는 `filesystem.denyRead`가 적용하는 것과 동일한 제한이고, 환경 변수는 각 샌드박싱된 명령 실행 전에 설정 해제됩니다.

203 205

204아래 예제는 AWS 자격증명 파일 및 SSH 디렉토리의 읽기를 차단하고 샌드박싱된 명령의 환경에서 `GITHUB_TOKEN` 및 `NPM_TOKEN`을 제거합니다:206아래 예제는 AWS 자격증명 파일 및 SSH 디렉토리의 읽기를 차단하고 샌드박싱된 명령의 환경에서 `GITHUB_TOKEN` 및 `NPM_TOKEN`을 제거합니다:

205 207

221}223}

222```224```

223 225

224각 항목은 `"mode": "deny"`를 포함하며, 이는 유일하게 지원되는 값입니다. 명시적 `mode` 필드는 스키마를 향후 모드와의 호환성을 유지합니다. 파일 경로는 `sandbox.filesystem.*` 설정과 동일한 [접두사 규칙](/ko/settings#sandbox-path-prefixes)을 따르며, 모든 [설정 범위](/ko/settings#settings-precedence)의 항목이 병합됩니다. 유일한 모드가 `deny`이므로 모든 범위는 제한을 추가할 수 있지만 제거할 수는 없습니다.226파일 항목은 `"mode": "deny"`만 지원합니다. 환경 변수 항목은 아래에서 설명하는 `"mode": "mask"`도 허용합니다.

227

228파일 경로는 `sandbox.filesystem.*` 설정과 동일한 [접두사 규칙](/ko/settings#sandbox-path-prefixes)을 따르며, 모든 [설정 범위](/ko/settings#settings-precedence)의 `deny` 항목이 병합됩니다. `deny` 항목은 액세스를 좁히기만 하므로 모든 범위는 항목을 추가할 수 있지만 다른 범위가 추가한 항목을 제거할 수는 없습니다.

225 229

226기본 제공 자격증명 거부 목록이 없으므로 나열한 파일 및 변수만 제한됩니다. 이 설정은 샌드박싱된 Bash 명령에만 영향을 미칩니다. 샌드박싱 여부와 관계없이 모든 하위 프로세스에서 Anthropic 및 클라우드 공급자 자격증명을 제거하려면 [`CLAUDE_CODE_SUBPROCESS_ENV_SCRUB`](/ko/env-vars)를 설정합니다.230기본 제공 자격증명 거부 목록이 없으므로 나열한 파일 및 변수만 제한됩니다. 이 설정은 샌드박싱된 Bash 명령에만 영향을 미칩니다. 샌드박싱 여부와 관계없이 모든 하위 프로세스에서 Anthropic 및 클라우드 공급자 자격증명을 제거하려면 [`CLAUDE_CODE_SUBPROCESS_ENV_SCRUB`](/ko/env-vars)를 설정합니다.

227 231

232<h4 id="mask-environment-variables">

233 환경 변수 마스킹

234</h4>

235

236`"mode": "mask"`는 자격증명을 보호하면서 이를 사용하여 인증하는 도구가 계속 작동하도록 합니다. `deny`는 변수를 완전히 제거하므로 `gh` 또는 `npm`과 같이 이를 필요로 하는 도구도 중단됩니다. Claude Code v2.1.199 이상이 필요합니다.

237

238`mask`를 사용하면 샌드박싱된 명령은 실제 값 대신 세션별 센티널 값을 봅니다. 요청이 자격증명의 `injectHosts` 중 하나에 대해 샌드박스를 떠날 때 [샌드박스 프록시](#network-isolation)는 센티널을 실제 값으로 바꿉니다. 명령과 이것이 기록하는 모든 것은 실제 자격증명을 보유하지 않지만 요청은 여전히 인증됩니다.

239

240프록시는 요청 내용 내에서 자격증명을 대체하므로 이를 봐야 합니다. [`network.tlsTerminate`](/ko/settings#sandbox-settings)를 설정하여 프록시가 HTTPS 자체를 종료하도록 합니다. 이 없이는 마스킹이 폐쇄 상태로 실패합니다: 명령은 여전히 센티널만 보지만 센티널이 변경되지 않은 상태로 서버에 도달하고 인증이 실패합니다. Claude Code는 시작 시 및 `/doctor`에서 이 잘못된 구성을 보고합니다.

241

242아래 예제는 두 개의 토큰을 마스킹합니다. `GH_TOKEN`은 `api.github.com`에 대한 요청에서만 대체되고, `NPM_TOKEN`은 `injectHosts`가 없으며 `network.allowedDomains`의 모든 호스트에 대한 요청에서 대체됩니다. 각 `injectHosts` 항목은 자체적으로 `network.allowedDomains`로 커버되어야 합니다.

243

244```json theme={null}

245{

246 "sandbox": {

247 "enabled": true,

248 "network": {

249 "tlsTerminate": {},

250 "allowedDomains": ["*.github.com", "registry.npmjs.org"]

251 },

252 "credentials": {

253 "envVars": [

254 { "name": "GH_TOKEN", "mode": "mask", "injectHosts": ["api.github.com"] },

255 { "name": "NPM_TOKEN", "mode": "mask" }

256 ]

257 }

258 }

259}

260```

261

262`deny`와 달리 마스킹은 프록시가 나열된 호스트에 실제 자격증명을 보내도록 승인하므로 사용자 또는 관리자가 제어하는 설정에서만 적용됩니다: 사용자 설정, 관리 설정 및 `--settings` CLI 플래그. 리포지토리의 `.claude/settings.json` 또는 `.claude/settings.local.json`의 `mask` 항목, `network.tlsTerminate` 및 [`credentials.allowPlaintextInject`](/ko/settings#sandbox-settings)는 무시됩니다.

263

264동일한 변수가 모든 범위에서 `deny`로 나열되면 `deny`가 우선합니다.

265

228<h2 id="how-sandboxing-works">266<h2 id="how-sandboxing-works">

229 샌드박싱 작동 방식267 샌드박싱 작동 방식

230</h2>268</h2>

255* **포괄적 범위**: 제한은 명령으로 생성된 모든 스크립트, 프로그램 및 하위 프로세스에 적용됩니다293* **포괄적 범위**: 제한은 명령으로 생성된 모든 스크립트, 프로그램 및 하위 프로세스에 적용됩니다

256 294

257<Note>295<Note>

258 기본 제공 프록시는 요청된 호스트 이름을 기반으로 허용 목록을 적용하며 TLS 트래픽을 종료하거나 검사하지 않습니다. 이 설계의 의미는 [보안 제한 사항](#security-limitations)을 참조하고, 위협 모델이 TLS 검사를 요구하면 [사용자 정의 프록시 구성](#custom-proxy-configuration)을 참조하세요.296 기본 제공 프록시는 요청된 호스트 이름을 기반으로 허용 목록을 적용하며, 기본적으로 TLS 트래픽을 종료하거나 검사하지 않습니다. {/* min-version: 2.1.199 */}Claude Code v2.1.199 이상에서 사용 가능한 실험적 [`network.tlsTerminate`](/ko/settings#sandbox-settings) 설정은 기본 제공 프록시가 TLS 자체를 종료하도록 하며, 이는 [`mask` 자격 증명 항목](#protect-credentials)이 필요로 합니다. 기본값의 의미는 [보안 제한 사항](#security-limitations)을 참조하고, 위협 모델이 TLS 검사를 요구하면 [사용자 정의 프록시 구성](#custom-proxy-configuration)을 참조하세요.

259</Note>297</Note>

260 298

261<h3 id="os-level-enforcement">299<h3 id="os-level-enforcement">

412 보안 제한 사항450 보안 제한 사항

413</h3>451</h3>

414 452

415* **네트워크 필터링**: 네트워크 필터링 시스템은 프로세스가 연결할 수 있는 도메인을 제한하여 작동합니다. 기본 제공 프록시는 아웃바운드 트래픽을 종료하거나 TLS 검사를 수행하지 않으므로 암호화된 연결의 내용은 검사되지 않습니다. 정책에서 신뢰할 수 있는 도메인만 허용하도록 보장하는 것은 사용자의 책임입니다.453* **네트워크 필터링**: 샌드박스는 프로세스가 연결할 수 있는 도메인을 제한합니다. 기본 제공 프록시는 아웃바운드 트래픽을 종료하거나 TLS를 검사하지 않으므로 암호화된 연결의 내용은 검사되지 않습니다. 실험적인 [`network.tlsTerminate`](/ko/settings#sandbox-settings) 설정은 [`mask` 자격 증명 대체](#protect-credentials)를 위해 프록시에서 TLS를 종료하지만 콘텐츠 필터링을 추가하지 않습니다. 정책에서 신뢰할 수 있는 도메인만 허용하도록 보장하는 것은 사용자의 책임입니다.

416 454

417<Warning>455<Warning>

418 `github.com`과 같은 광범위한 도메인을 허용하면 데이터 유출 경로가 생성될 수 있습니다. 프록시가 TLS를 검사하지 않고 클라이언트 제공 호스트 이름에서 허용 결정을 내리기 때문에 샌드박스 내에서 실행되는 코드는 잠재적으로 [도메인 프론팅](https://en.wikipedia.org/wiki/Domain_fronting) 또는 유사한 기술을 사용하여 허용 목록 외부의 호스트에 도달할 수 있습니다. 위협 모델이 더 강력한 보장을 요구하면 TLS를 종료하고 트래픽을 검사하는 [사용자 정의 프록시](#custom-proxy-configuration)를 구성하고 그 CA 인증서를 샌드박스 내에 설치합니다. 더 강력한 TLS 인식 네트워크 격리는 활발한 개발 영역입니다.456 `github.com`과 같은 광범위한 도메인을 허용하면 데이터 유출 경로가 생성될 수 있습니다. 프록시가 TLS를 검사하지 않고 클라이언트 제공 호스트 이름에서 허용 결정을 내리기 때문에 샌드박스 내에서 실행되는 코드는 잠재적으로 [도메인 프론팅](https://en.wikipedia.org/wiki/Domain_fronting) 또는 유사한 기술을 사용하여 허용 목록 외부의 호스트에 도달할 수 있습니다. 위협 모델이 더 강력한 보장을 요구하면 TLS를 종료하고 트래픽을 검사하는 [사용자 정의 프록시](#custom-proxy-configuration)를 구성하고 그 CA 인증서를 샌드박스 내에 설치합니다. 더 강력한 TLS 인식 네트워크 격리는 활발한 개발 영역입니다.

server-managed-settings.md +18 −6

Details

171 171

172**캐시된 설정으로 이후 시작:**172**캐시된 설정으로 이후 시작:**

173 173

174* 캐시된 설정은 시작 시 즉시 적용됩니다.174* 캐시된 설정은 시작 시 즉시 적용됩니다. 아래에 설명된 전송, 라우팅 및 인증 환경 변수는 제외됩니다.

175* Claude Code는 백그라운드에서 새로운 설정을 가져옵니다.175* Claude Code는 백그라운드에서 새로운 설정을 가져옵니다.

176* 캐시된 설정은 네트워크 장애를 통해 유지됩니다.176* 캐시된 설정은 네트워크 장애를 통해 유지됩니다. 보류된 환경 변수는 가져오기가 성공할 때까지 보류된 상태로 유지됩니다.

177

178v2.1.198 이상에서 Claude Code는 서버가 세션의 페이로드를 확인할 때까지 캐시된 `env` 블록의 세 가지 환경 변수 범주를 보류합니다. 이는 캐시된 프록시, 인증서 기관, 엔드포인트 또는 자격 증명 값이 설정 가져오기를 리디렉션, 가로채기 또는 다시 인증하는 것을 방지합니다. 강화는 서버에서 가져온 설정 캐시에만 적용됩니다. [엔드포인트 관리 설정](/ko/settings#settings-files)은 MDM 또는 `managed-settings.json`을 통해 배포되며 영향을 받지 않습니다. 보류된 범주는 다음과 같습니다.

179

180* `HTTPS_PROXY`, `NODE_EXTRA_CA_CERTS` 및 mTLS 클라이언트 인증서 변수 `CLAUDE_CODE_CLIENT_CERT`와 `CLAUDE_CODE_CLIENT_KEY`와 같은 프록시 및 TLS 구성

181* `ANTHROPIC_BASE_URL`, `CLAUDE_CODE_USE_BEDROCK` 및 `CLAUDE_CODE_USE_VERTEX`와 같은 공급자 선택 변수, 그리고 `ANTHROPIC_BEDROCK_BASE_URL`과 같은 공급자 엔드포인트 URL을 포함한 API 라우팅 및 공급자 선택

182* `ANTHROPIC_API_KEY`, `ANTHROPIC_AUTH_TOKEN` 및 `CLAUDE_CODE_OAUTH_TOKEN`과 같은 인증 자격 증명

183

184캐시된 `env` 블록의 다른 모든 키(예: 원격 분석 및 OpenTelemetry 구성)는 이전과 같이 시작 시 적용됩니다. 가져오기가 성공하면 보류된 변수는 세션의 나머지 기간 동안 적용됩니다.

185

186조직에서 `api.anthropic.com`에 도달하기 위해 프록시가 필요한 경우, 관리 `env` 블록에만 설정하지 말고 셸 환경 또는 [사용자 설정](/ko/settings#settings-files)에서 설정합니다. 첫 번째 시작에는 캐시가 없으므로 이러한 소스는 이미 초기 가져오기에 필요했습니다.

177 187

178Claude Code는 OpenTelemetry 구성과 같은 고급 설정을 제외하고 재시작 없이 설정 업데이트를 자동으로 적용하며, 이는 적용되려면 전체 재시작이 필요합니다.188Claude Code는 OpenTelemetry 구성과 같은 고급 설정을 제외하고 재시작 없이 설정 업데이트를 자동으로 적용하며, 이는 적용되려면 전체 재시작이 필요합니다.

179 189

234 플랫폼 가용성244 플랫폼 가용성

235</h2>245</h2>

236 246

237서버 관리 설정은 `api.anthropic.com`에 대한 직접 연결이 필요하며, 전달을 위해서는 세션이 조직 OAuth 로그인 또는 직접 구성된 API 키로 인증되어야 합니다. [`apiKeyHelper`](/ko/settings#available-settings) 스크립트에서 반환된 키는 설정 가져오기를 트리거하지 않습니다. 서버 관리 설정은 타사 모델 공급자를 사용할 때는 사용할 수 없습니다:247서버 관리 설정은 `api.anthropic.com`에 대한 직접 연결이 필요하며, 전달을 위해서는 세션이 조직 OAuth 로그인 또는 직접 구성된 API 키로 인증되어야 합니다. [`apiKeyHelper`](/ko/settings#available-settings) 스크립트에서 반환된 키는 설정 가져오기를 트리거하지 않습니다.

248

249서버 관리 설정은 타사 모델 공급자를 사용할 때는 사용할 수 없습니다:

238 250

239* Amazon Bedrock251* Amazon Bedrock

240* Google Vertex AI252* Google Vertex AI

259서버 관리 설정은 중앙 집중식 정책 적용을 제공하지만 클라이언트 측 제어로 작동하며 보안 경계가 아닙니다. 관리되지 않는 기기에서 사용자는 이를 우회하기 위해 관리자 또는 sudo 액세스 권한이 필요하지 않습니다.271서버 관리 설정은 중앙 집중식 정책 적용을 제공하지만 클라이언트 측 제어로 작동하며 보안 경계가 아닙니다. 관리되지 않는 기기에서 사용자는 이를 우회하기 위해 관리자 또는 sudo 액세스 권한이 필요하지 않습니다.

260 272

261| 시나리오 | 동작 |273| 시나리오 | 동작 |

262| :-------------------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |274| :-------------------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

263| 사용자가 캐시된 설정 파일을 편집함 | 변조된 파일이 시작 시 적용되지만 다음 서버 가져오기에서 올바른 설정이 복원됩니다. |275| 사용자가 캐시된 설정 파일을 편집함 | 변조된 파일이 시작 시 적용되지만 다음 서버 가져오기에서 올바른 설정이 복원됩니다. {/* min-version: 2.1.198 */}v2.1.198부터 `env` 블록의 전송, API 라우팅 및 인증 환경 변수는 [서버가 페이로드를 확인할 때까지 보류됩니다](#fetch-and-caching-behavior) |

264| 사용자가 캐시된 설정 파일을 삭제함 | 첫 시작 동작이 발생합니다. 설정이 비동기적으로 가져오지며 짧은 적용되지 않은 시간이 있습니다. |276| 사용자가 캐시된 설정 파일을 삭제함 | 첫 시작 동작이 발생합니다. 설정이 비동기적으로 가져오지며 짧은 적용되지 않은 시간이 있습니다. |

265| 사용자가 수정된 Claude Code 바이너리를 실행함 | 수정된 클라이언트를 실행할 수 있는 사용자는 모든 클라이언트 측 제어를 우회할 수 있습니다. |277| 사용자가 수정된 Claude Code 바이너리를 실행함 | 수정된 클라이언트를 실행할 수 있는 사용자는 모든 클라이언트 측 제어를 우회할 수 있습니다. |

266| 사용자가 이전 Claude Code 버전을 실행함 | 서버 관리 설정 이전의 버전은 이를 가져오거나 적용하지 않습니다. |278| 사용자가 이전 Claude Code 버전을 실행함 | 서버 관리 설정 이전의 버전은 이를 가져오거나 적용하지 않습니다. |

267| API를 사용할 수 없음 | 캐시된 설정이 있으면 적용되고, 그렇지 않으면 다음 성공적인 가져오기까지 관리 설정이 적용되지 않습니다. `forceRemoteSettingsRefresh: true`를 사용하면 CLI는 계속하는 대신 종료됩니다. [`claude auth` 부분 명령](#enforce-fail-closed-startup) 제외 |279| API를 사용할 수 없음 | 캐시된 설정이 있으면 적용되고, 그렇지 않으면 다음 성공적인 가져오기까지 관리 설정이 적용되지 않습니다. {/* min-version: 2.1.198 */}v2.1.198부터 캐시된 `env` 블록의 전송, API 라우팅 및 인증 환경 변수는 [가져오기 실패 시 보류됩니다](#fetch-and-caching-behavior). 캐시의 나머지 부분은 여전히 적용됩니다. `forceRemoteSettingsRefresh: true`를 사용하면 CLI는 계속하는 대신 종료됩니다. [`claude auth` 부분 명령](#enforce-fail-closed-startup) 제외 |

268| 사용자가 다른 조직으로 인증함 | 관리 조직 외부의 계정에 대해 설정이 전달되지 않습니다. |280| 사용자가 다른 조직으로 인증함 | 관리 조직 외부의 계정에 대해 설정이 전달되지 않습니다. |

269| 사용자가 [타사 모델 공급자](#platform-availability)를 구성함 | 서버 관리 설정이 우회됩니다. 여기에는 `CLAUDE_CODE_USE_BEDROCK`, `CLAUDE_CODE_USE_MANTLE`, `CLAUDE_CODE_USE_VERTEX`, `CLAUDE_CODE_USE_FOUNDRY`, `CLAUDE_CODE_USE_ANTHROPIC_AWS` 설정 또는 기본이 아닌 `ANTHROPIC_BASE_URL` 설정이 포함됩니다. |281| 사용자가 [타사 모델 공급자](#platform-availability)를 구성함 | 서버 관리 설정이 우회됩니다. 여기에는 `CLAUDE_CODE_USE_BEDROCK`, `CLAUDE_CODE_USE_MANTLE`, `CLAUDE_CODE_USE_VERTEX`, `CLAUDE_CODE_USE_FOUNDRY`, `CLAUDE_CODE_USE_ANTHROPIC_AWS` 설정 또는 기본이 아닌 `ANTHROPIC_BASE_URL` 설정이 포함됩니다. |

270| 네트워크 트래픽이 가로채지거나 리디렉션됨 | 비활성화된 TLS 검증 또는 가로챈 트래픽은 클라이언트가 수신하는 설정을 변경할 수 있습니다. |282| 네트워크 트래픽이 가로채지거나 리디렉션됨 | 비활성화된 TLS 검증 또는 가로챈 트래픽은 클라이언트가 수신하는 설정을 변경할 수 있습니다. |

sessions.md +2 −0

Details

97/branch try-streaming-approach97/branch try-streaming-approach

98```98```

99 99

100이름을 생략하면 Claude Code는 대화의 첫 번째 프롬프트 이후로 새 분기의 이름을 지정합니다. v2.1.198부터 이는 [압축](/ko/how-claude-code-works#when-context-fills-up) 이후에도 적용됩니다. 이전 버전은 압축 요약을 지나 원본 첫 번째 프롬프트를 찾는 대신 리터럴 이름 `Branched conversation`으로 폴백했습니다.

101

100명령줄에서 `--continue` 또는 `--resume`을 `--fork-session`과 결합합니다:102명령줄에서 `--continue` 또는 `--resume`을 `--fork-session`과 결합합니다:

101 103

102```bash theme={null}104```bash theme={null}

settings.md +6 −3

Details

398고급 샌드박싱 동작을 구성합니다. 샌드박싱은 bash 명령을 파일 시스템 및 네트워크에서 격리합니다. 자세한 내용은 [Sandboxing](/ko/sandboxing)을 참조하세요.398고급 샌드박싱 동작을 구성합니다. 샌드박싱은 bash 명령을 파일 시스템 및 네트워크에서 격리합니다. 자세한 내용은 [Sandboxing](/ko/sandboxing)을 참조하세요.

399 399

400| 키 | 설명 | 예제 |400| 키 | 설명 | 예제 |

401| :------------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :--------------------------------------------------- |401| :------------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :--------------------------------------------------- |

403| `failIfUnavailable` | `sandbox.enabled`가 true이지만 샌드박스를 시작할 수 없는 경우 (종속성 누락, 지원되지 않는 플랫폼) 시작 시 오류로 종료합니다. false (기본값)일 때 경고가 표시되고 명령이 샌드박싱되지 않은 상태로 실행됩니다. Managed 설정 배포에서 샌드박싱을 하드 게이트로 요구하는 경우를 위한 것입니다 | `true` |403| `failIfUnavailable` | `sandbox.enabled`가 true이지만 샌드박스를 시작할 수 없는 경우 (종속성 누락, 지원되지 않는 플랫폼) 시작 시 오류로 종료합니다. false (기본값)일 때 경고가 표시되고 명령이 샌드박싱되지 않은 상태로 실행됩니다. Managed 설정 배포에서 샌드박싱을 하드 게이트로 요구하는 경우를 위한 것입니다 | `true` |

410| `filesystem.allowRead` | `denyRead` 영역 내에서 읽기를 다시 허용할 경로입니다. `denyRead`보다 우선합니다. 배열은 모든 설정 범위에서 병합됩니다. 이를 사용하여 작업 공간 전용 읽기 액세스 패턴을 만듭니다. | `["."]` |410| `filesystem.allowRead` | `denyRead` 영역 내에서 읽기를 다시 허용할 경로입니다. `denyRead`보다 우선합니다. 배열은 모든 설정 범위에서 병합됩니다. 이를 사용하여 작업 공간 전용 읽기 액세스 패턴을 만듭니다. | `["."]` |

412| `credentials.files` | 샌드박싱된 명령이 읽을 수 없는 자격 증명 파일 또는 디렉토리입니다. `filesystem.denyRead`와 동일한 읽기 블록을 적용합니다. 별도의 키는 자격 증명 경로를 `credentials.envVars`와 함께 그룹화하고 일반 파일 시스템 규칙과 분리합니다. 각 항목은 `{ "path": "...", "mode": "deny" }`입니다. 경로는 `filesystem.*` 설정과 동일한 [접두사](#sandbox-path-prefixes)를 사용합니다. 배열은 모든 설정 범위에서 병합됩니다. `deny`만 지원됩니다. Claude Code v2.1.187 이상이 필요합니다. | `[{ "path": "~/.aws/credentials", "mode": "deny" }]` |412| `credentials.files` | {/* min-version: 2.1.187 */}샌드박싱된 명령이 읽을 수 없는 자격 증명 파일 또는 디렉토리입니다. `filesystem.denyRead`와 동일한 읽기 블록을 적용합니다. 별도의 키는 자격 증명 경로를 `credentials.envVars`와 함께 그룹화하고 일반 파일 시스템 규칙과 분리합니다. 각 항목은 `{ "path": "...", "mode": "deny" }`입니다. 경로는 `filesystem.*` 설정과 동일한 [접두사](#sandbox-path-prefixes)를 사용합니다. 배열은 모든 설정 범위에서 병합됩니다. `deny`만 지원됩니다. Claude Code v2.1.187 이상이 필요합니다. | `[{ "path": "~/.aws/credentials", "mode": "deny" }]` |

413| `credentials.envVars` | 샌드박싱된 명령을 실행하기 전에 설정 해제할 환경 변수입니다. 각 항목은 `{ "name": "...", "mode": "deny" }`입니다. 배열은 모든 설정 범위에서 병합됩니다. `deny`만 지원됩니다. Claude Code v2.1.187 이상이 필요합니다. | `[{ "name": "GITHUB_TOKEN", "mode": "deny" }]` |413| `credentials.envVars` | {/* min-version: 2.1.187 */}샌드박싱된 명령을 실행하기 전에 설정 해제할 환경 변수입니다. 각 항목은 `{ "name": "...", "mode": "deny" }`입니다. 배열은 모든 설정 범위에서 병합됩니다. `deny`만 지원됩니다. Claude Code v2.1.187 이상이 필요합니다. | `[{ "name": "GITHUB_TOKEN", "mode": "deny" }]` |

414| `credentials.envVars[].injectHosts` | {/* min-version: 2.1.199 */}샌드박스 프록시가 실제 값을 대체할 호스트입니다. 각 호스트는 `network.allowedDomains`에서도 정확히 또는 와일드카드로 포함되어야 합니다. 설정되지 않으면 프록시가 `network.allowedDomains`의 모든 호스트에 대해 값을 대체합니다. `mode`가 `deny`일 때 허용되지만 무시됩니다. Claude Code v2.1.199 이상이 필요합니다. | `["api.github.com"]` |

415| `credentials.allowPlaintextInject` | {/* min-version: 2.1.199 */}}일반 HTTP 요청뿐만 아니라 TLS 종료 HTTPS에서 `mask` 대체를 허용합니다. 일반 HTTP에서 업스트림 ID는 확인되지 않고 자격 증명은 평문으로 이동하므로 신뢰할 수 있는 테스트 네트워크 외부에서는 이를 끕니다. 사용자, managed 또는 CLI `--settings` 설정에서만 적용되며 `.claude/settings.json` 또는 `.claude/settings.local.json`에서는 적용되지 않습니다. 기본값: false. Claude Code v2.1.199 이상이 필요합니다. | `true` |

414| `network.allowUnixSockets` | (macOS만) Unix 소켓 경로 샌드박스에서 액세스 가능. Linux 및 WSL2에서는 무시되며, seccomp 필터가 소켓 경로를 검사할 수 없습니다. 대신 `allowAllUnixSockets`를 사용합니다. | `["~/.ssh/agent-socket"]` |416| `network.allowUnixSockets` | (macOS만) Unix 소켓 경로 샌드박스에서 액세스 가능. Linux 및 WSL2에서는 무시되며, seccomp 필터가 소켓 경로를 검사할 수 없습니다. 대신 `allowAllUnixSockets`를 사용합니다. | `["~/.ssh/agent-socket"]` |

415| `network.allowAllUnixSockets` | 샌드박스에서 모든 Unix 소켓 연결을 허용합니다. Linux 및 WSL2에서 이는 `socket(AF_UNIX, ...)` 호출을 차단하는 seccomp 필터를 건너뛰므로 Unix 소켓을 허용하는 유일한 방법입니다. 기본값: false | `true` |417| `network.allowAllUnixSockets` | 샌드박스에서 모든 Unix 소켓 연결을 허용합니다. Linux 및 WSL2에서 이는 `socket(AF_UNIX, ...)` 호출을 차단하는 seccomp 필터를 건너뛰므로 Unix 소켓을 허용하는 유일한 방법입니다. 기본값: false | `true` |

420| `network.allowManagedDomainsOnly` | (Managed 설정만) Managed 설정의 `allowedDomains` 및 `WebFetch(domain:...)` 허용 규칙만 존중됩니다. 사용자, 프로젝트 및 local 설정의 도메인은 무시됩니다. 허용되지 않은 도메인은 사용자에게 메시지를 표시하지 않고 자동으로 차단됩니다. 거부된 도메인은 여전히 모든 소스에서 존중됩니다. 기본값: false | `true` |422| `network.allowManagedDomainsOnly` | (Managed 설정만) Managed 설정의 `allowedDomains` 및 `WebFetch(domain:...)` 허용 규칙만 존중됩니다. 사용자, 프로젝트 및 local 설정의 도메인은 무시됩니다. 허용되지 않은 도메인은 사용자에게 메시지를 표시하지 않고 자동으로 차단됩니다. 거부된 도메인은 여전히 모든 소스에서 존중됩니다. 기본값: false | `true` |

421| `network.httpProxyPort` | 자신의 프록시를 가져오려는 경우 사용되는 HTTP 프록시 포트입니다. 지정되지 않으면 Claude가 자신의 프록시를 실행합니다. | `8080` |423| `network.httpProxyPort` | 자신의 프록시를 가져오려는 경우 사용되는 HTTP 프록시 포트입니다. 지정되지 않으면 Claude가 자신의 프록시를 실행합니다. | `8080` |

422| `network.socksProxyPort` | 자신의 프록시를 가져오려는 경우 사용되는 SOCKS5 프록시 포트입니다. 지정되지 않으면 Claude가 자신의 프록시를 실행합니다. | `8081` |424| `network.socksProxyPort` | 자신의 프록시를 가져오려는 경우 사용되는 SOCKS5 프록시 포트입니다. 지정되지 않으면 Claude가 자신의 프록시를 실행합니다. | `8081` |

425| `network.tlsTerminate` | {/* min-version: 2.1.199 */}}실험적입니다. 샌드박스 프록시 내에서 TLS를 종료하여 HTTPS 요청의 내용을 읽을 수 있습니다. `mask` [자격 증명 대체](/ko/sandboxing#protect-credentials)에 필요합니다. 세션에 대한 임시 인증 기관을 생성하려면 `{}`로 설정하거나 자신의 것을 사용하려면 `caCertPath` 및 `caKeyPath`로 설정합니다. 사용자, managed 또는 CLI `--settings` 설정에서만 적용되며 `.claude/settings.json` 또는 `.claude/settings.local.json`에서는 적용되지 않습니다. Claude Code v2.1.199 이상이 필요합니다. | `{}` |

424| `enableWeakerNetworkIsolation` | (macOS만) 샌드박스에서 시스템 TLS 신뢰 서비스 (`com.apple.trustd.agent`)에 대한 액세스를 허용합니다. MITM 프록시 및 사용자 정의 CA를 사용하는 `httpProxyPort`를 사용할 때 `gh`, `gcloud` 및 `terraform`과 같은 Go 기반 도구가 TLS 인증서를 확인하는 데 필요합니다. **보안을 감소시킵니다** 잠재적 데이터 유출 경로를 열어서. 기본값: false | `true` |427| `enableWeakerNetworkIsolation` | (macOS만) 샌드박스에서 시스템 TLS 신뢰 서비스 (`com.apple.trustd.agent`)에 대한 액세스를 허용합니다. MITM 프록시 및 사용자 정의 CA를 사용하는 `httpProxyPort`를 사용할 때 `gh`, `gcloud` 및 `terraform`과 같은 Go 기반 도구가 TLS 인증서를 확인하는 데 필요합니다. **보안을 감소시킵니다** 잠재적 데이터 유출 경로를 열어서. 기본값: false | `true` |

425| `allowAppleEvents` | (macOS만) 샌드박싱된 명령이 Apple Events를 보낼 수 있도록 허용합니다. `open`, `osascript` 및 URL을 브라우저에서 열 수 있는 도구에 필요하며, 그렇지 않으면 오류 `-600`으로 실패합니다. **코드 실행 격리를 제거합니다.** 샌드박싱된 명령은 사용자 프롬프트 없이 다른 애플리케이션을 샌드박싱되지 않은 상태로 시작할 수 있습니다. 또한 Terminal과 같은 실행 중인 애플리케이션에 AppleScript 명령을 보낼 수 있으며, 이는 앱별 macOS 자동화 동의 프롬프트 (TCC)의 대상입니다. 사용자, managed 또는 CLI 설정에서만 적용되며 프로젝트 설정에서는 적용되지 않습니다. 기본값: false | `true` |428| `allowAppleEvents` | (macOS만) 샌드박싱된 명령이 Apple Events를 보낼 수 있도록 허용합니다. `open`, `osascript` 및 URL을 브라우저에서 열 수 있는 도구에 필요하며, 그렇지 않으면 오류 `-600`으로 실패합니다. **코드 실행 격리를 제거합니다.** 샌드박싱된 명령은 사용자 프롬프트 없이 다른 애플리케이션을 샌드박싱되지 않은 상태로 시작할 수 있습니다. 또한 Terminal과 같은 실행 중인 애플리케이션에 AppleScript 명령을 보낼 수 있으며, 이는 앱별 macOS 자동화 동의 프롬프트 (TCC)의 대상입니다. 사용자, managed 또는 CLI 설정에서만 적용되며 프로젝트 설정에서는 적용되지 않습니다. 기본값: false | `true` |

setup.md +1 −1

Details

453 npm으로 설치453 npm으로 설치

454</h3>454</h3>

455 455

456Claude Code를 전역 npm 패키지로 설치할 수도 있습니다. 패키지에는 [Node.js 18 이상](https://nodejs.org/en/download)이 필요합니다.456Claude Code를 전역 npm 패키지로 설치할 수도 있습니다. v2.1.198부터 npm 패키지에는 [Node.js 22 이상](https://nodejs.org/en/download)이 필요합니다. 이전 Node.js 버전에서는 npm이 설치 중에 실패하는 대신 `EBADENGINE` 경고를 인쇄합니다. 설치가 완료되고 `claude`는 여전히 실행됩니다. 패키지가 런타임에 Node.js를 사용하지 않는 네이티브 바이너리를 다운로드하기 때문입니다.

457 457

458```bash theme={null}458```bash theme={null}

459npm install -g @anthropic-ai/claude-code459npm install -g @anthropic-ai/claude-code

skills.md +4 −0

Details

443 443

444인수를 사용하여 skill을 호출하지만 skill에 `$ARGUMENTS`가 포함되지 않으면, Claude Code는 `ARGUMENTS: <your input>`을 skill 콘텐츠의 끝에 추가하므로 Claude는 여전히 입력한 내용을 봅니다.444인수를 사용하여 skill을 호출하지만 skill에 `$ARGUMENTS`가 포함되지 않으면, Claude Code는 `ARGUMENTS: <your input>`을 skill 콘텐츠의 끝에 추가하므로 Claude는 여전히 입력한 내용을 봅니다.

445 445

446한 메시지의 시작 부분에 여러 skills를 스택할 수도 있습니다. v2.1.199부터는 `/code-review /fix-issue 123`을 입력하면 두 skill이 모두 로드되고 뒤따르는 텍스트 `123`이 각각에 `$ARGUMENTS`로 전달됩니다. 이전 버전에서는 첫 번째 skill만 로드되고 `/fix-issue 123`을 리터럴 인수 텍스트로 받았습니다.

447

448Claude Code는 첫 번째 skill과 그 뒤에 스택된 최대 5개의 skill을 확장합니다. 확장은 인라인 사용자 호출 가능 skill이 아닌 첫 번째 토큰에서 중지되므로, [forked subagent](#run-skills-in-a-subagent)로 실행되는 skill이나 인수 자체가 `/loop`와 같은 slash 명령어로 시작할 수 있는 skill도 거기서 끝나고, 그 토큰과 그 뒤의 모든 것이 모든 확장된 skill에 대한 인수 텍스트가 됩니다.

449

446위치별로 개별 인수에 액세스하려면 `$ARGUMENTS[N]` 또는 더 짧은 `$N`을 사용합니다:450위치별로 개별 인수에 액세스하려면 `$ARGUMENTS[N]` 또는 더 짧은 `$N`을 사용합니다:

447 451

448```yaml theme={null}452```yaml theme={null}

sub-agents.md +93 −67

Details

24 24

25Claude는 각 subagent의 설명을 사용하여 작업을 위임할 시기를 결정합니다. Subagent를 만들 때 Claude가 언제 사용할지 알 수 있도록 명확한 설명을 작성하세요.25Claude는 각 subagent의 설명을 사용하여 작업을 위임할 시기를 결정합니다. Subagent를 만들 때 Claude가 언제 사용할지 알 수 있도록 명확한 설명을 작성하세요.

26 26

27Claude Code에는 **Explore**, **Plan**, **general-purpose**와 같은 여러 내장 subagent가 포함되어 있습니다. 특정 작업을 처리하기 위해 사용자 정의 subagent를 만들 수도 있습니다.27Claude Code에는 Explore, Plan, general-purpose와 같은 여러 내장 subagent가 포함되어 있습니다. 특정 작업을 처리하기 위해 사용자 정의 subagent를 만들 수도 있습니다.

28 28

29<h2 id="built-in-subagents">29<h2 id="built-in-subagents">

30 내장 subagent30 내장 subagent

38 <Tab title="Explore">38 <Tab title="Explore">

39 코드베이스 검색 및 분석에 최적화된 빠른 읽기 전용 에이전트입니다.39 코드베이스 검색 및 분석에 최적화된 빠른 읽기 전용 에이전트입니다.

40 40

~~41 * **모델**: Haiku (빠름, 낮은 지연시간)~~41 * **모델**: 주 대화에서 상속되며, Claude API에서 Opus로 제한되므로 Explore는 세션에 대해 이미 선택한 모델보다 더 비싼 모델에서 실행되지 않습니다.

~~42 * **도구**: 읽기 전용 도구 (Write 및 Edit 도구에 대한 액세스 거부)~~42 * **도구**: 읽기 전용 도구; Write 및 Edit은 거부됩니다.

43 * **목적**: 파일 검색, 코드 검색, 코드베이스 탐색43 * **목적**: 파일 검색, 코드 검색, 코드베이스 탐색

44 44

45 {/* min-version: 2.1.198 */}v2.1.198부터 Explore는 항상 Haiku에서 실행되는 대신 주 대화의 모델을 상속합니다. Claude API에서 상속된 모델은 Opus로 제한됩니다: 더 높은 계층의 주 대화는 Explore를 Opus에서 실행하고, Sonnet 또는 Haiku의 주 대화는 Explore를 동일한 모델에서 실행합니다. [Amazon Bedrock, Google Cloud의 Agent Platform, Microsoft Foundry 또는 AWS의 Claude Platform](/ko/third-party-integrations)과 같은 다른 공급자에서는 Explore가 주 대화의 모델을 직접 상속합니다.

47 `Explore`라는 [사용자 또는 프로젝트 subagent](#choose-the-subagent-scope)는 내장 subagent를 재정의하고 자신의 `model` 필드를 유지하므로, 탐색을 더 낮은 비용의 모델에서 유지하려면 `model: haiku`를 사용하여 정의하십시오.

45 Claude는 변경 없이 코드베이스를 검색하거나 이해해야 할 때 Explore에 위임합니다. 이렇게 하면 탐색 결과가 주 대화 컨텍스트에서 벗어납니다.49 Claude는 변경 없이 코드베이스를 검색하거나 이해해야 할 때 Explore에 위임합니다. 이렇게 하면 탐색 결과가 주 대화 컨텍스트에서 벗어납니다.

46 50

47 Explore를 호출할 때 Claude는 철저함 수준을 지정합니다: 대상 조회의 경우 **quick**, 균형 잡힌 탐색의 경우 **medium**, 포괄적인 분석의 경우 **very thorough**.51 Explore를 호출할 때 Claude는 철저함 수준을 지정합니다: 대상 조회의 경우 **quick**, 균형 잡힌 탐색의 경우 **medium**, 포괄적인 분석의 경우 **very thorough**.

77 </Tab>81 </Tab>

78</Tabs>82</Tabs>

79 83

~~80내장 subagent는 항상 대화형 세션에 등록됩니다. 특정 내장 유형을 차단하려면:~~84내장 subagent는 기본적으로 대화형 세션에 등록됩니다. 이를 제한하려면:

81 85

82* 특정 내장 유형을 차단하려면 [특정 subagent 비활성화](#disable-specific-subagents)에 표시된 대로 `permissions.deny`에 추가하십시오.86* 특정 내장 유형을 차단하려면 [특정 subagent 비활성화](#disable-specific-subagents)에 표시된 대로 `permissions.deny`에 추가하십시오.

83* Claude가 어떤 subagent에도 위임하는 것을 방지하려면 [`permissions.deny`](/ko/permissions#tool-specific-permission-rules)를 사용하여 `Agent` 도구 자체를 거부하십시오.87* Claude가 어떤 subagent에도 위임하는 것을 방지하려면 [`permissions.deny`](/ko/permissions#tool-specific-permission-rules)를 사용하여 `Agent` 도구 자체를 거부하십시오.

88* {/* min-version: 2.1.198 */}내장 `Explore` 및 `Plan` subagent만 제거하려면 [`CLAUDE_CODE_DISABLE_EXPLORE_PLAN_AGENTS=1`](/ko/env-vars)을 설정하십시오. Claude는 이들에게 위임하는 대신 파일을 직접 읽고 탐색합니다. Claude Code v2.1.198 이상이 필요합니다.

84* [비대화형 모드](/ko/headless) 및 [Agent SDK](/ko/agent-sdk/overview)에서는 [`CLAUDE_AGENT_SDK_DISABLE_BUILTIN_AGENTS=1`](/ko/env-vars)을 설정하여 모든 내장 유형을 제거하고 자신의 것만 제공하십시오.89* [비대화형 모드](/ko/headless) 및 [Agent SDK](/ko/agent-sdk/overview)에서는 [`CLAUDE_AGENT_SDK_DISABLE_BUILTIN_AGENTS=1`](/ko/env-vars)을 설정하여 모든 내장 유형을 제거하고 자신의 것만 제공하십시오.

85 90

86이러한 내장 subagent 외에도 사용자 정의 프롬프트, 도구 제한, 권한 모드, hooks 및 skills를 사용하여 자신의 subagent를 만들 수 있습니다. 다음 섹션에서는 시작하는 방법과 subagent를 사용자 정의하는 방법을 보여줍니다.91이러한 내장 subagent 외에도 사용자 정의 프롬프트, 도구 제한, 권한 모드, hooks 및 skills를 사용하여 자신의 subagent를 만들 수 있습니다. 다음 섹션에서는 시작하는 방법과 subagent를 사용자 정의하는 방법을 보여줍니다.

89 빠른 시작: 첫 번째 subagent 만들기94 빠른 시작: 첫 번째 subagent 만들기

90</h2>95</h2>

91 96

~~92Subagent는 YAML frontmatter가 있는 Markdown 파일로 정의됩니다. [수동으로 만들거나](#write-subagent-files) `/agents` 명령을 사용할 수 있습니다.~~97Subagent는 YAML frontmatter가 있는 Markdown 파일입니다. Claude에게 작성을 요청하거나 [수동으로 파일을 작성](#write-subagent-files)할 수 있습니다.

93 98

94이 연습에서는 `/agents` 명령을 사용하여 사용자 수준 subagent를 만드는 과정을 안내합니다. Subagent는 코드를 검토하고 코드베이스에 대한 개선 사항을 제안합니다.99{/* min-version: 2.1.198 */}v2.1.198부터 `/agents` 명령은 더 이상 대화형 생성 마법사를 열지 않습니다. 이를 실행하면 Claude에게 요청하거나 `.claude/agents/`를 직접 편집하라는 알림이 출력됩니다. Subagent 파일, frontmatter 필드 및 `.claude/agents/`와 `~/.claude/agents/` 위치는 변경되지 않았습니다. 터미널 마법사만 제거되었습니다.

100

101이 연습에서는 코드를 검토하고 개선 사항을 제안하는 사용자 수준 subagent를 만듭니다.

95 102

96<Steps>103<Steps>

~~97 <Step title="subagent 인터페이스 열기">~~104 <Step title="Claude에게 subagent 생성 요청">

~~98 Claude Code에서 다음을 실행합니다:~~105 Claude Code에서 원하는 subagent와 저장 위치를 설명합니다:

99 106

100 ```text wrap theme={null}107 ```text wrap theme={null}

101 /agents108 Create a personal code-improver subagent in ~/.claude/agents/ that scans

109 files and suggests improvements for readability, performance, and best

110 practices. It should explain each issue, show the current code, and

111 provide an improved version. Make it read-only and have it use Sonnet.

102 ```112 ```

103 </Step>

104 113

105 <Step title="위치 선택">114 Claude는 `name`, `description`, `tools` 목록, `model` 및 시스템 프롬프트가 포함된 파일을 작성합니다.

106 **Library** 탭으로 전환하고 **Create new agent**를 선택한 다음 **Personal**을 선택합니다. 이렇게 하면 subagent가 `~/.claude/agents/`에 저장되어 모든 프로젝트에서 사용할 수 있습니다.

107 </Step>115 </Step>

108 116

109 <Step title="Claude로 생성">117 <Step title="파일 검토">

110 **Generate with Claude**를 선택합니다. 메시지가 표시되면 subagent를 설명합니다:118 `~/.claude/agents/code-improver.md`를 열고 frontmatter가 요청한 내용과 일치하는지 확인합니다. 결과는 다음과 같습니다:

111 119

112 ```text wrap theme={null}120 ```markdown theme={null}

113 A code improvement agent that scans files and suggests improvements121 ---

114 for readability, performance, and best practices. It should explain122 name: code-improver

115 each issue, show the current code, and provide an improved version.123 description: Scans files and suggests improvements for readability, performance, and best practices. Use after writing or modifying code.

124 tools: Read, Grep, Glob

125 model: sonnet

126 ---

127

128 You are a code improvement specialist. For each issue you find, explain

129 the problem, show the current code, and provide an improved version.

116 ```130 ```

117 131

118 Claude가 식별자, 설명 및 시스템 프롬프트를 생성합니다.132 파일이 `~/.claude/agents/`에 있으므로 subagent는 머신의 모든 프로젝트에서 사용할 수 있습니다. 대신 하나의 프로젝트로 범위를 지정하려면 해당 프로젝트의 `.claude/agents/` 디렉토리로 이동합니다. [subagent 범위 선택](#choose-the-subagent-scope)에서 두 가지를 비교합니다.

119 </Step>

~~120~~

121 <Step title="도구 선택">

122 읽기 전용 검토자의 경우 **Read-only tools**를 제외한 모든 항목을 선택 해제합니다. 모든 도구를 선택한 상태로 유지하면 subagent는 주 대화에서 사용 가능한 모든 도구를 상속합니다.

123 </Step>

~~124~~

125 <Step title="모델 선택">

126 Subagent가 사용할 모델을 선택합니다. 이 예제 에이전트의 경우 코드 패턴 분석을 위해 기능과 속도의 균형을 맞추는 **Sonnet**을 선택합니다.

127 </Step>

~~128~~

129 <Step title="색상 선택">

130 Subagent의 배경색을 선택합니다. 이렇게 하면 UI에서 어느 subagent가 실행 중인지 식별하는 데 도움이 됩니다.

131 </Step>

~~132~~

133 <Step title="메모리 구성">

134 **User scope**를 선택하여 subagent에 `~/.claude/agent-memory/`에서 [지속적 메모리 디렉토리](#enable-persistent-memory)를 제공합니다. Subagent는 이를 사용하여 코드베이스 패턴 및 반복되는 문제와 같은 대화 간 통찰력을 축적합니다. Subagent가 학습을 유지하지 않으려면 **None**을 선택합니다.

135 </Step>133 </Step>

136 134

137 <Step title="저장 및 시도">135 <Step title="시도해 보기">

138 구성 요약을 검토합니다. `s` 또는 `Enter`를 눌러 저장하거나 `e`를 눌러 편집기에서 저장 및 편집합니다. Subagent는 즉시 사용 가능합니다. 시도해 봅니다:136 Claude에게 새 subagent에 위임하도록 요청합니다:

139 137

140 ```text wrap theme={null}138 ```text wrap theme={null}

141 Use the code-improver agent to suggest improvements in this project139 Use the code-improver agent to suggest improvements in this project

142 ```140 ```

143 141

144 Claude가 새 subagent에 위임하고, subagent가 코드베이스를 스캔하여 개선 제안을 반환합니다.142 Claude가 새 subagent에 위임하고, subagent가 코드베이스를 스캔하여 개선 제안을 반환합니다.

143

144 Claude가 새 subagent를 찾을 수 없으면 Claude Code를 다시 시작하고 다시 시도합니다. 이는 세션이 시작되기 전에 `~/.claude/agents/`가 없었을 때만 발생합니다. 실행 중인 세션은 새로 생성된 `agents` 디렉토리를 감지하지 않기 때문입니다.

145 </Step>145 </Step>

146</Steps>146</Steps>

147 147

148이제 머신의 모든 프로젝트에서 코드베이스를 분석하고 개선 사항을 제안하는 데 사용할 수 있는 subagent가 있습니다.148이제 머신의 모든 프로젝트에서 코드베이스를 분석하고 개선 사항을 제안하는 데 사용할 수 있는 subagent가 있습니다.

149 149

150Markdown 파일로 subagent를 수동으로 만들거나, CLI 플래그를 통해 정의하거나, 플러그인을 통해 배포할 수도 있습니다. 다음 섹션에서는 모든 구성 옵션을 다룹니다.150subagent 파일을 수동으로 작성하거나, CLI 플래그를 통해 정의하거나, 플러그인을 통해 배포할 수도 있습니다. 다음 섹션에서는 모든 구성 옵션을 다룹니다.

151

152<Note>

153 Claude Code v2.1.197 이전 버전에서는 `/agents`가 라이브 subagent를 나열하는 **Running** 탭과 생성, 편집 및 삭제를 위한 **Library** 탭이 있는 대화형 마법사를 엽니다. {/* max-version: 2.1.197 */}

154</Note>

151 155

152<h2 id="configure-subagents">156<h2 id="configure-subagents">

153 Subagent 구성157 Subagent 구성

154</h2>158</h2>

155 159

156<h3 id="use-the-/agents-command">160Subagent의 파일 위치는 누가 사용할 수 있는지를 결정하고, 해당 frontmatter는 무엇을 할 수 있는지를 결정합니다. 이 섹션에서는 subagent 파일이 어디에 있는지와 지원하는 모든 필드를 다룹니다.

157 /agents 명령 사용

158</h3>

~~159~~

160`/agents` 명령은 subagent를 관리하기 위한 탭 인터페이스를 엽니다. **Running** 탭은 라이브 및 최근에 완료된 subagent를 나열하고 열거나 중지할 수 있습니다. **Library** 탭을 사용하면 다음을 수행할 수 있습니다:

~~161~~

162* 사용 가능한 모든 subagent 보기 (내장, 사용자, 프로젝트, 플러그인)

163* 안내된 설정 또는 Claude 생성으로 새 subagent 만들기

164* 기존 subagent 구성 및 도구 액세스 편집

165* 사용자 정의 subagent 삭제

166* 중복이 있을 때 활성 subagent 확인

~~167~~

168이것이 subagent를 만들고 관리하는 권장 방법입니다. 수동 생성 또는 자동화의 경우 subagent 파일을 직접 추가할 수도 있습니다.

169 161

170<h3 id="choose-the-subagent-scope">162<h3 id="choose-the-subagent-scope">

171 Subagent 범위 선택163 Subagent 범위 선택

172</h3>164</h3>

173 165

174Subagent는 YAML frontmatter가 있는 Markdown 파일입니다. 범위에 따라 다른 위치에 저장합니다. 여러 subagent가 같은 이름을 공유할 때 더 높은 우선순위 위치가 우선합니다.166범위에 따라 다른 위치에 subagent 파일을 저장합니다. 여러 subagent가 같은 이름을 공유할 때 Claude Code는 더 높은 우선순위 위치의 subagent를 사용합니다.

175 167

176| 위치 | 범위 | 우선순위 | 만드는 방법 |168| 위치 | 범위 | 우선순위 | 만드는 방법 |

177| :------------------- | :------------ | :----- | :----------------------------- |169| :------------------- | :------------ | :----- | :----------------------------- |

178| 관리되는 설정 | 조직 전체 | 1 (최고) | [관리되는 설정](/ko/settings)을 통해 배포 |170| 관리되는 설정 | 조직 전체 | 1 (최고) | [관리되는 설정](/ko/settings)을 통해 배포 |

183 175

184**프로젝트 subagent** (`.claude/agents/`)는 코드베이스에 특정한 subagent에 이상적입니다. 버전 제어에 체크인하여 팀이 협력하여 사용하고 개선할 수 있습니다.176**프로젝트 subagent** (`.claude/agents/`)는 코드베이스에 특정한 subagent에 이상적입니다. 버전 제어에 체크인하여 팀이 협력하여 사용하고 개선할 수 있습니다.

189 181

190**사용자 subagent** (`~/.claude/agents/`)는 모든 프로젝트에서 사용 가능한 개인 subagent입니다.182**사용자 subagent** (`~/.claude/agents/`)는 모든 프로젝트에서 사용 가능한 개인 subagent입니다.

191 183

192Claude Code는 `.claude/agents/` 및 `~/.claude/agents/`를 재귀적으로 스캔하므로 `agents/review/` 또는 `agents/research/`와 같은 하위 폴더로 정의를 구성할 수 있습니다. 하위 디렉토리 경로는 subagent가 식별되거나 호출되는 방식에 영향을 주지 않습니다. 왜냐하면 ID는 `name` frontmatter 필드에서만 나오기 때문입니다. 전체 트리에서 `name` 값을 고유하게 유지합니다: 한 범위 내의 두 파일이 같은 이름을 선언하면 Claude Code는 하나만 로드합니다. {/* min-version: 2.1.196 */}v2.1.196부터 `/doctor`를 실행하면 동일한 범위의 중복 에이전트 이름을 보고하고 활성 정의를 표시합니다.184Claude Code는 `.claude/agents/` 및 `~/.claude/agents/`를 재귀적으로 스캔하므로 `agents/review/` 또는 `agents/research/`와 같은 하위 폴더로 정의를 구성할 수 있습니다. 하위 디렉토리 경로는 subagent가 식별되거나 호출되는 방식에 영향을 주지 않습니다. 왜냐하면 ID는 `name` frontmatter 필드에서만 나오기 때문입니다.

185

186전체 트리에서 `name` 값을 고유하게 유지합니다: 한 범위 내의 두 파일이 같은 이름을 선언하면 Claude Code는 하나만 로드합니다. {/* min-version: 2.1.196 */}v2.1.196부터 `/doctor`를 실행하면 동일한 범위의 중복 에이전트 이름을 보고하고 활성 정의를 표시합니다.

193 187

194플러그인 `agents/` 디렉토리도 재귀적으로 스캔됩니다. 프로젝트 및 사용자 범위와 달리 플러그인의 `agents/` 디렉토리 내의 하위 폴더는 [범위가 지정된 식별자](#invoke-subagents-explicitly)의 일부가 됩니다: 플러그인 `my-plugin`의 `agents/review/security.md`에 있는 파일은 `my-plugin:review:security`로 등록됩니다.188플러그인 `agents/` 디렉토리도 재귀적으로 스캔됩니다. 프로젝트 및 사용자 범위와 달리 플러그인의 `agents/` 디렉토리 내의 하위 폴더는 [범위가 지정된 식별자](#invoke-subagents-explicitly)의 일부가 됩니다: 플러그인 `my-plugin`의 `agents/review/security.md`에 있는 파일은 `my-plugin:review:security`로 등록됩니다.

195 189

237 231

238**관리되는 subagent**는 조직 관리자가 배포합니다. [관리되는 설정 디렉토리](/ko/settings#settings-files) 내의 `.claude/agents/`에 markdown 파일을 배치하고, 프로젝트 및 사용자 subagent와 동일한 frontmatter 형식을 사용합니다. 관리되는 정의는 같은 이름의 프로젝트 및 사용자 subagent보다 우선합니다.232**관리되는 subagent**는 조직 관리자가 배포합니다. [관리되는 설정 디렉토리](/ko/settings#settings-files) 내의 `.claude/agents/`에 markdown 파일을 배치하고, 프로젝트 및 사용자 subagent와 동일한 frontmatter 형식을 사용합니다. 관리되는 정의는 같은 이름의 프로젝트 및 사용자 subagent보다 우선합니다.

239 233

240**플러그인 subagent**는 설치한 [플러그인](/ko/plugins)에서 제공됩니다. `/agents`에서 사용자 정의 subagent와 함께 나타납니다. 플러그인 subagent 만드는 방법에 대한 자세한 내용은 [플러그인 컴포넌트 참조](/ko/plugins-reference#agents)를 참조하세요.234**플러그인 subagent**는 설치한 [플러그인](/ko/plugins)에서 제공됩니다. 이들은 사용자 정의 subagent와 함께 로드되고 범위가 지정된 이름 아래의 @-mention 자동완성에 나타납니다. 플러그인 subagent 만드는 방법에 대한 자세한 내용은 [플러그인 컴포넌트 참조](/ko/plugins-reference#agents)를 참조하세요.

241 235

242<Note>236<Note>

243 보안상의 이유로 플러그인 subagent는 `hooks`, `mcpServers`, `permissionMode` frontmatter 필드를 지원하지 않습니다. 이러한 필드는 플러그인에서 에이전트를 로드할 때 무시됩니다. 필요한 경우 에이전트 파일을 `.claude/agents/` 또는 `~/.claude/agents/`로 복사합니다. `settings.json` 또는 `settings.local.json`의 [`permissions.allow`](/ko/settings#permission-settings)에 규칙을 추가할 수도 있지만, 이러한 규칙은 전체 세션에 적용되며 플러그인 subagent에만 적용되지 않습니다.237 보안상의 이유로 플러그인 subagent는 `hooks`, `mcpServers`, `permissionMode` frontmatter 필드를 지원하지 않습니다. 이러한 필드는 플러그인에서 에이전트를 로드할 때 무시됩니다. 필요한 경우 에이전트 파일을 `.claude/agents/` 또는 `~/.claude/agents/`로 복사합니다. `settings.json` 또는 `settings.local.json`의 [`permissions.allow`](/ko/settings#permission-settings)에 규칙을 추가할 수도 있지만, 이러한 규칙은 전체 세션에 적용되며 플러그인 subagent에만 적용되지 않습니다.

252Subagent 파일은 구성을 위한 YAML frontmatter를 사용하고 그 뒤에 Markdown의 시스템 프롬프트가 옵니다:246Subagent 파일은 구성을 위한 YAML frontmatter를 사용하고 그 뒤에 Markdown의 시스템 프롬프트가 옵니다:

253 247

254<Note>248<Note>

255 Subagent는 세션 시작 시 로드됩니다. 디스크에서 subagent 파일을 직접 추가하거나 편집하면 세션을 다시 시작하여 로드합니다. `/agents` 인터페이스를 통해 생성된 subagent는 다시 시작하지 않고도 즉시 적용됩니다.249 Claude Code는 `~/.claude/agents/` 및 `.claude/agents/`를 감시합니다. 디스크에서 subagent 파일을 추가하거나 편집하거나 Claude가 하나를 작성하도록 요청하면 Claude Code는 몇 초 내에 변경을 감지하고 다음 위임은 다시 시작할 필요 없이 업데이트된 정의를 사용합니다.

250

251 여전히 다시 시작이 필요한 두 가지 경우가 있습니다:

252

253 * 감시자는 세션이 시작될 때 존재했던 디렉토리만 포함하므로 새 `agents` 디렉토리에서 범위의 첫 번째 에이전트 파일을 생성한 후 다시 시작하여 로드합니다.

254 * `--disable-slash-commands`로 시작된 세션은 이러한 디렉토리를 전혀 감시하지 않습니다.

256</Note>255</Note>

257 256

258```markdown theme={null}257```markdown theme={null}

290| `mcpServers` | 아니오 | 이 subagent에서 사용 가능한 [MCP servers](/ko/mcp). 각 항목은 이미 구성된 서버를 참조하는 서버 이름 (예: `"slack"`) 또는 서버 이름을 키로 하고 전체 [MCP server config](/ko/mcp#installing-mcp-servers)를 값으로 하는 인라인 정의입니다. [플러그인 subagent](#choose-the-subagent-scope)에서는 무시됨 |289| `mcpServers` | 아니오 | 이 subagent에서 사용 가능한 [MCP servers](/ko/mcp). 각 항목은 이미 구성된 서버를 참조하는 서버 이름 (예: `"slack"`) 또는 서버 이름을 키로 하고 전체 [MCP server config](/ko/mcp#installing-mcp-servers)를 값으로 하는 인라인 정의입니다. [플러그인 subagent](#choose-the-subagent-scope)에서는 무시됨 |

291| `hooks` | 아니오 | 이 subagent로 범위가 지정된 [라이프사이클 hooks](#define-hooks-for-subagents). [플러그인 subagent](#choose-the-subagent-scope)에서는 무시됨 |290| `hooks` | 아니오 | 이 subagent로 범위가 지정된 [라이프사이클 hooks](#define-hooks-for-subagents). [플러그인 subagent](#choose-the-subagent-scope)에서는 무시됨 |

292| `memory` | 아니오 | [지속적 메모리 범위](#enable-persistent-memory): `user`, `project`, 또는 `local`. 교차 세션 학습 활성화 |291| `memory` | 아니오 | [지속적 메모리 범위](#enable-persistent-memory): `user`, `project`, 또는 `local`. 교차 세션 학습 활성화 |

293| `background` | 아니오 | 이 subagent를 항상 [background task](#run-subagents-in-foreground-or-background)로 실행하려면 `true`로 설정합니다. 기본값: `false` |292| `background` | 아니오 | 이 subagent를 항상 [background task](#run-subagents-in-foreground-or-background)로 실행하려면 `true`로 설정합니다. 설정하지 않으면 Claude가 선택하고, {/* min-version: 2.1.198 */}v2.1.198부터 기본적으로 subagent를 백그라운드에서 실행합니다 |

294| `effort` | 아니오 | 이 subagent가 활성화될 때의 노력 수준. 세션 노력 수준을 재정의합니다. 기본값: 세션에서 상속. 옵션: `low`, `medium`, `high`, `xhigh`, `max` (사용 가능한 수준은 모델에 따라 다름) |293| `effort` | 아니오 | 이 subagent가 활성화될 때의 노력 수준. 세션 노력 수준을 재정의합니다. 기본값: 세션에서 상속. 옵션: `low`, `medium`, `high`, `xhigh`, `max` (사용 가능한 수준은 모델에 따라 다름) |

295| `isolation` | 아니오 | Subagent를 임시 [git worktree](/ko/worktrees)에서 실행하려면 `worktree`로 설정하여 저장소의 격리된 복사본을 제공합니다. 기본적으로 [기본 분기](/ko/worktrees#choose-the-base-branch)에서 분기되며, 부모 세션의 `HEAD`가 아닙니다. Subagent가 변경 사항을 만들지 않으면 worktree가 자동으로 정리됩니다 |294| `isolation` | 아니오 | Subagent를 임시 [git worktree](/ko/worktrees)에서 실행하려면 `worktree`로 설정하여 저장소의 격리된 복사본을 제공합니다. 기본적으로 [기본 분기](/ko/worktrees#choose-the-base-branch)에서 분기되며, 부모 세션의 `HEAD`가 아닙니다. Subagent가 변경 사항을 만들지 않으면 worktree가 자동으로 정리됩니다 |

296| `color` | 아니오 | 작업 목록 및 트랜스크립트에서 subagent의 표시 색상입니다. `red`, `blue`, `green`, `yellow`, `purple`, `orange`, `pink`, 또는 `cyan`을 허용합니다 |295| `color` | 아니오 | 작업 목록 및 트랜스크립트에서 subagent의 표시 색상입니다. `red`, `blue`, `green`, `yellow`, `purple`, `orange`, `pink`, 또는 `cyan`을 허용합니다 |

316 315

317{/* min-version: 2.1.196 */}v2.1.196부터 `CLAUDE_CODE_SUBAGENT_MODEL`을 `inherit`로 설정하는 것은 설정하지 않은 것과 동일합니다: 해결은 호출별 `model` 매개변수로 계속되고 frontmatter로 계속됩니다. 이전 버전에서는 `inherit`이 subagent를 주 대화의 모델로 강제하고 이 두 소스를 모두 무시했습니다.316{/* min-version: 2.1.196 */}v2.1.196부터 `CLAUDE_CODE_SUBAGENT_MODEL`을 `inherit`로 설정하는 것은 설정하지 않은 것과 동일합니다: 해결은 호출별 `model` 매개변수로 계속되고 frontmatter로 계속됩니다. 이전 버전에서는 `inherit`이 subagent를 주 대화의 모델로 강제하고 이 두 소스를 모두 무시했습니다.

318 317

319환경 변수, 호출별 매개변수, frontmatter 값은 조직의 [`availableModels`](/ko/model-config#restrict-model-selection) 허용 목록에 대해 확인됩니다. 제외된 모델로 해결되는 값은 사용되지 않으며 subagent는 상속된 모델에서 대신 실행됩니다.318Claude Code는 환경 변수, 호출별 매개변수, frontmatter 값을 조직의 [`availableModels`](/ko/model-config#restrict-model-selection) 허용 목록에 대해 확인합니다. 제외된 모델로 해결되는 값은 사용되지 않으며 subagent는 상속된 모델에서 대신 실행됩니다.

319

320{/* min-version: 2.1.198 */}v2.1.198부터 subagent는 주 대화의 [extended thinking](/ko/model-config#extended-thinking) 구성도 상속합니다: 세션에서 thinking이 켜져 있으면 subagent에서도 켜져 있고, 꺼져 있으면 꺼진 상태로 유지됩니다. subagent별 thinking 설정은 없습니다. v2.1.198 이전에는 주 대화의 설정에 관계없이 subagent가 extended thinking을 비활성화한 상태로 실행되었습니다.

320 321

321<h3 id="control-subagent-capabilities">322<h3 id="control-subagent-capabilities">

322 Subagent 기능 제어323 Subagent 기능 제어

430Use the Playwright tools to navigate, screenshot, and interact with pages.431Use the Playwright tools to navigate, screenshot, and interact with pages.

431```432```

432 433

433인라인 정의는 `.mcp.json` 서버 항목 (`stdio`, `http`, `sse`, `ws`)과 동일한 스키마를 사용하며 서버 이름으로 키가 지정됩니다.434인라인 정의는 `.mcp.json` 서버 항목과 동일한 스키마를 사용하며 서버 이름으로 키가 지정되고 `stdio`, `http`, `sse`, `ws` 유형을 지원합니다.

434 435

435MCP 서버를 주 대화에서 완전히 분리하고 도구 설명이 컨텍스트를 소비하지 않도록 하려면 `.mcp.json`이 아닌 여기에 인라인으로 정의합니다. Subagent는 도구를 얻고 부모 대화는 그렇지 않습니다.436MCP 서버를 주 대화에서 완전히 분리하고 도구 설명이 컨텍스트를 소비하지 않도록 하려면 `.mcp.json`이 아닌 여기에 인라인으로 정의합니다. Subagent는 도구를 얻고 부모 대화는 그렇지 않습니다.

436 437

526 지속적 메모리 팁527 지속적 메모리 팁

527</h5>528</h5>

528 529

529* `project`는 권장되는 기본 범위입니다. 메모리를 버전 제어를 통해 공유 가능하게 만듭니다. Subagent의 지식이 모든 프로젝트에 광범위하게 적용될 때 `user`를 사용하거나, 지식이 버전 제어에 체크인되지 않아야 할 때 `local`을 사용합니다.530* `project`는 권장되는 기본 범위입니다. 메모리를 버전 제어를 통해 공유 가능하게 만듭니다.

530* Subagent에 작업을 시작하기 전에 메모리를 확인하도록 요청합니다: "Review this PR, and check your memory for patterns you've seen before."531* Subagent에 작업을 시작하기 전에 메모리를 확인하도록 요청합니다: "Review this PR, and check your memory for patterns you've seen before."

531* Subagent에 작업을 완료한 후 메모리를 업데이트하도록 요청합니다: "Now that you're done, save what you learned to your memory." 시간이 지남에 따라 이렇게 하면 subagent를 더 효과적으로 만드는 지식 기반이 구축됩니다.532* Subagent에 작업을 완료한 후 메모리를 업데이트하도록 요청합니다: "Now that you're done, save what you learned to your memory." 시간이 지남에 따라 이렇게 하면 subagent를 더 효과적으로 만드는 지식 기반이 구축됩니다.

532* Subagent가 자신의 지식 기반을 적극적으로 유지하도록 메모리 지침을 subagent의 markdown 파일에 직접 포함합니다:533* Subagent가 자신의 지식 기반을 적극적으로 유지하도록 메모리 지침을 subagent의 markdown 파일에 직접 포함합니다:

727 728

728전체 메시지는 여전히 Claude로 이동하며, Claude는 요청한 내용을 기반으로 subagent의 작업 프롬프트를 작성합니다. @-mention은 Claude가 호출하는 subagent를 제어하며, 받는 프롬프트는 제어하지 않습니다.729전체 메시지는 여전히 Claude로 이동하며, Claude는 요청한 내용을 기반으로 subagent의 작업 프롬프트를 작성합니다. @-mention은 Claude가 호출하는 subagent를 제어하며, 받는 프롬프트는 제어하지 않습니다.

729 730

730활성화된 [플러그인](/ko/plugins)에서 제공하는 Subagent는 typeahead에 `my-plugin:code-reviewer` 또는 플러그인이 [agents를 하위 폴더로 구성](#choose-the-subagent-scope)할 때 `my-plugin:review:security`와 같은 범위가 지정된 이름으로 나타납니다. 세션에서 현재 실행 중인 명명된 background subagent도 typeahead에 나타나며 이름 옆에 상태를 표시합니다. 선택기를 사용하지 않고 수동으로 mention을 입력할 수도 있습니다: 로컬 subagent의 경우 `@agent-<name>`, 플러그인 subagent의 경우 범위가 지정된 이름 뒤에 `@agent-`를 입력합니다. 예를 들어 `@agent-my-plugin:code-reviewer`입니다.731활성화된 [플러그인](/ko/plugins)에서 제공하는 Subagent는 typeahead에 `my-plugin:code-reviewer` 또는 플러그인이 [agents를 하위 폴더로 구성](#choose-the-subagent-scope)할 때 `my-plugin:review:security`와 같은 범위가 지정된 이름으로 나타납니다. 세션에서 현재 실행 중인 명명된 background subagent도 typeahead에 나타나며 이름 옆에 상태를 표시합니다.

732

733선택기를 사용하지 않고 수동으로 mention을 입력할 수도 있습니다: 로컬 subagent의 경우 `@agent-<name>`, 플러그인 subagent의 경우 범위가 지정된 이름 뒤에 `@agent-`를 입력합니다. 예를 들어 `@agent-my-plugin:code-reviewer`입니다.

731 734

732**전체 세션을 subagent로 실행합니다.** [`--agent <name>`](/ko/cli-reference)을 전달하여 주 스레드 자체가 해당 subagent의 시스템 프롬프트, 도구 제한 및 모델을 취하는 세션을 시작합니다:735**전체 세션을 subagent로 실행합니다.** [`--agent <name>`](/ko/cli-reference)을 전달하여 주 스레드 자체가 해당 subagent의 시스템 프롬프트, 도구 제한 및 모델을 취하는 세션을 시작합니다:

733 736

772* **Foreground subagent**는 완료될 때까지 주 대화를 차단합니다. 권한 프롬프트는 발생하는 대로 사용자에게 전달됩니다.775* **Foreground subagent**는 완료될 때까지 주 대화를 차단합니다. 권한 프롬프트는 발생하는 대로 사용자에게 전달됩니다.

773* **Background subagent**는 계속 작업하는 동안 동시에 실행됩니다. {/* min-version: 2.1.186 */}v2.1.186부터 background subagent가 권한이 필요한 도구 호출에 도달하면 프롬프트가 주 세션에 표시되고 요청하는 subagent의 이름을 지정합니다. 승인하여 subagent를 계속하거나 Esc를 눌러 subagent를 중지하지 않고 해당 도구 호출을 거부합니다. v2.1.186 이전에는 background subagent가 프롬프트를 표시했을 모든 도구 호출을 자동으로 거부했습니다.776* **Background subagent**는 계속 작업하는 동안 동시에 실행됩니다. {/* min-version: 2.1.186 */}v2.1.186부터 background subagent가 권한이 필요한 도구 호출에 도달하면 프롬프트가 주 세션에 표시되고 요청하는 subagent의 이름을 지정합니다. 승인하여 subagent를 계속하거나 Esc를 눌러 subagent를 중지하지 않고 해당 도구 호출을 거부합니다. v2.1.186 이전에는 background subagent가 프롬프트를 표시했을 모든 도구 호출을 자동으로 거부했습니다.

774 777

775Claude는 작업을 기반으로 subagent를 foreground 또는 background에서 실행할지 결정합니다. 다음을 수행할 수도 있습니다:778{/* min-version: 2.1.198 */}v2.1.198부터 subagent는 기본적으로 background에서 실행됩니다. Claude는 결과가 필요한 경우 subagent를 foreground에서 실행합니다. 기본값은 subagent가 실행되는 위치를 변경하며, 수행할 수 있는 작업은 변경하지 않습니다: background subagent는 여전히 주 세션에서 모든 권한 프롬프트를 표시합니다. v2.1.198 이전에는 Claude가 작업을 기반으로 foreground와 background 중에서 선택했습니다.

776 779

777* Claude에 "run this in the background"를 요청780다음을 수행할 수도 있습니다:

781

782* Claude에 작업을 background 또는 foreground에서 실행하도록 요청

778* **Ctrl+B**를 눌러 실행 중인 작업을 background로 이동783* **Ctrl+B**를 눌러 실행 중인 작업을 background로 이동

779 784

780모든 background 작업 기능을 비활성화하려면 `CLAUDE_CODE_DISABLE_BACKGROUND_TASKS` 환경 변수를 `1`로 설정합니다. [환경 변수](/ko/env-vars)를 참조하세요.785모든 background 작업 기능을 비활성화하려면 `CLAUDE_CODE_DISABLE_BACKGROUND_TASKS` 환경 변수를 `1`로 설정합니다. [환경 변수](/ko/env-vars)를 참조하세요.

781 786

782[`CLAUDE_CODE_FORK_SUBAGENT`](#fork-the-current-conversation)가 `1`로 설정되면 `background` 필드와 관계없이 모든 subagent 생성이 background에서 실행됩니다. 이러한 background subagent의 권한 프롬프트는 위에서 설명한 대로 주 세션에 표시됩니다.787[`CLAUDE_CODE_FORK_SUBAGENT`](#fork-the-current-conversation)가 `1`로 설정되면 모든 subagent 생성이 background에서 실행되고 frontmatter `background` 필드는 효과가 없습니다. fork 모드는 `Agent` 도구에서 `run_in_background` 매개변수를 제거하기 때문입니다. `CLAUDE_CODE_DISABLE_BACKGROUND_TASKS`는 fork 모드보다 우선하며 subagent 생성을 foreground에 유지합니다.

788

789<h3 id="api-errors-in-subagents">

790 Subagent의 API 오류

791</h3>

792

793{/* min-version: 2.1.199 */}v2.1.199부터 API 오류 (예: 사용 제한 또는 반복된 서버 오류)로 인해 실행이 종료된 subagent는 오류 텍스트를 subagent의 결과인 것처럼 반환하는 대신 해당 실패를 Claude에 보고합니다. Claude가 받는 내용은 subagent가 실행된 위치에 따라 다릅니다:

794

795* **Foreground**: 속도 제한, 과부하 또는 서버 오류가 이미 출력을 생성한 subagent를 중단하면 Agent 도구는 해당 부분 출력을 subagent가 중단되었으며 작업을 완료하지 못했다는 메모와 함께 반환합니다. 그렇지 않으면 도구 호출이 [`Agent terminated early due to an API error`](/ko/errors#agent-terminated-early-due-to-an-api-error)로 실패하고 오류 세부 정보가 뒤따릅니다.

796* **Background**: subagent는 실패로 표시되며 Claude가 종료될 때 받는 메시지는 API 오류의 이름을 지정하고 subagent의 마지막 출력을 포함하므로 부분 작업이 손실되지 않습니다.

797

798기본 API 오류가 해결되면 Claude에 작업을 다시 시도하거나 [subagent를 재개](#resume-subagents)하도록 요청합니다.

783 799

784<h3 id="common-patterns">800<h3 id="common-patterns">

785 일반적인 패턴801 일반적인 패턴

850 866

851{/* min-version: 2.1.172 */}Claude Code v2.1.172부터 subagent는 자신의 subagent를 생성할 수 있습니다. 위임된 작업이 자체적으로 병렬 하위 작업으로 분할될 때 이를 사용합니다. 예를 들어 각 발견에 대해 검증자를 발송하는 검토자 subagent를 사용하면 중간 출력이 주 대화에 도달하지 않습니다. 최상위 subagent의 요약만 사용자에게 반환됩니다.867{/* min-version: 2.1.172 */}Claude Code v2.1.172부터 subagent는 자신의 subagent를 생성할 수 있습니다. 위임된 작업이 자체적으로 병렬 하위 작업으로 분할될 때 이를 사용합니다. 예를 들어 각 발견에 대해 검증자를 발송하는 검토자 subagent를 사용하면 중간 출력이 주 대화에 도달하지 않습니다. 최상위 subagent의 요약만 사용자에게 반환됩니다.

852 868

853중첩된 subagent는 최상위 subagent와 동일한 방식으로 구성되며 동일한 [범위](#choose-the-subagent-scope)에서 해결됩니다. 프롬프트 입력 아래의 subagent 패널은 전체 트리를 표시합니다: 각 행은 하위 항목의 `(+N)` 개수를 표시하고, {/* min-version: 2.1.193 */}v2.1.193부터 행을 열면 해당 subagent의 형제 및 직접 자식이 `main`으로 돌아가는 경로와 함께 표시됩니다. [`/agents`](#use-the-%2Fagents-command)의 Running 탭은 실행 중인 subagent를 평면 목록으로 나열합니다.869중첩된 subagent는 최상위 subagent와 동일한 방식으로 구성되며 동일한 [범위](#choose-the-subagent-scope)에서 해결됩니다.

870

871프롬프트 입력 아래의 subagent 패널은 전체 트리를 표시합니다: 각 행은 하위 항목의 `(+N)` 개수를 표시하고, {/* min-version: 2.1.193 */}v2.1.193부터 행을 열면 해당 subagent의 형제 및 직접 자식이 `main`으로 돌아가는 경로와 함께 표시됩니다.

854 872

855깊이는 각 수준이 [foreground 또는 background](#run-subagents-in-foreground-or-background)에서 실행되는지 여부와 관계없이 주 대화 아래의 subagent 수준 수로 계산됩니다. 깊이 5의 subagent는 Agent 도구를 받지 않으며 추가로 생성할 수 없습니다. 제한은 고정되어 있으며 구성할 수 없습니다.873깊이는 각 수준이 [foreground 또는 background](#run-subagents-in-foreground-or-background)에서 실행되는지 여부와 관계없이 주 대화 아래의 subagent 수준 수로 계산됩니다. 깊이 5의 subagent는 Agent 도구를 받지 않으며 추가로 생성할 수 없습니다. 제한은 고정되어 있으며 구성할 수 없습니다.

856 874

890 908

891재개된 subagent는 모든 이전 도구 호출, 결과 및 추론을 포함한 전체 대화 기록을 유지합니다. Subagent는 새로 시작하는 대신 정확히 중단한 위치에서 계속됩니다.909재개된 subagent는 모든 이전 도구 호출, 결과 및 추론을 포함한 전체 대화 기록을 유지합니다. Subagent는 새로 시작하는 대신 정확히 중단한 위치에서 계속됩니다.

892 910

893Subagent가 완료되면 Claude는 에이전트 ID를 받습니다. 내장 Explore 및 Plan 에이전트는 일회성이며 에이전트 ID를 반환하지 않으므로 재개할 수 없습니다. 작업을 계속해야 할 때는 `general-purpose` 또는 사용자 정의 subagent를 사용합니다. Claude는 에이전트의 ID를 `to` 필드로 사용하여 `SendMessage` 도구를 사용하여 재개합니다. `SendMessage` 도구는 항상 에이전트 ID 또는 이름으로 subagent를 재개하는 데 사용할 수 있습니다. `shutdown_request` 및 `plan_approval_response`와 같은 구조화된 팀 프로토콜 메시지는 [agent teams](/ko/agent-teams)가 활성화되어야 합니다.911Subagent가 완료되면 Claude는 에이전트 ID를 받습니다. 내장 Explore 및 Plan 에이전트는 일회성이며 에이전트 ID를 반환하지 않으므로 재개할 수 없습니다. 작업을 계속해야 할 때는 `general-purpose` 또는 사용자 정의 subagent를 사용합니다.

912

913Claude는 `SendMessage` 도구를 에이전트의 ID 또는 이름을 `to` 필드로 사용하여 재개합니다. `SendMessage`는 [agent teams](/ko/agent-teams)가 활성화되어야 하는 `shutdown_request` 및 `plan_approval_response`와 같은 구조화된 팀 프로토콜 메시지를 필요로 하지 않습니다. 에이전트 ID 또는 이름으로 subagent를 재개하는 데만 사용할 수 있습니다.

894 914

895Subagent를 재개하려면 Claude에 이전 작업을 계속하도록 요청합니다:915Subagent를 재개하려면 Claude에 이전 작업을 계속하도록 요청합니다:

896 916

904 924

905중단된 subagent가 `SendMessage`를 받으면 새로운 `Agent` 호출 없이 background에서 자동으로 재개됩니다.925중단된 subagent가 `SendMessage`를 받으면 새로운 `Agent` 호출 없이 background에서 자동으로 재개됩니다.

906 926

927{/* min-version: 2.1.199 */}v2.1.199부터 `SendMessage`는 이름이 여전히 대화에서 이전에 도달한 동일한 에이전트를 참조하는지 확인합니다. 더 새로운 에이전트가 이름을 가져간 경우 (예: 이름을 재사용한 다시 생성된 background 에이전트), Claude Code는 잘못된 에이전트에 전달하는 대신 전송을 거부하며 오류는 이름이 현재 도달하는 에이전트를 보고하므로 Claude가 재대상화할 수 있습니다. 여전히 실행 중인 이전 에이전트에 도달하려면 Claude는 생성 결과의 에이전트 ID로 주소를 지정합니다. 확인은 현재 대화로 범위가 지정되며 `/clear`에서 재설정됩니다.

928

929{/* min-version: 2.1.198 */}v2.1.198부터 subagent는 이를 시작한 에이전트의 메시지를 일반적인 작업 지시로 취급하며, 중간 작업 과정 수정을 포함하고 자신의 권한 설정 내에서 작동합니다. 메시지를 보낸 사람과 관계없이 두 가지 제한이 여전히 유지됩니다: 어떤 에이전트의 메시지도 보류 중인 권한 프롬프트에 대한 승인으로 계산되지 않으며, 어떤 에이전트 메시지도 subagent의 권한 설정, `CLAUDE.md` 또는 구성을 변경할 수 없습니다. 권한 시스템 또는 자신의 메시지만 승인을 부여할 수 있습니다.

930

907에이전트 ID를 명시적으로 참조하려면 Claude에 ID를 요청할 수도 있으며, `~/.claude/projects/{project}/{sessionId}/subagents/`의 트랜스크립트 파일에서 ID를 찾을 수 있습니다. 각 트랜스크립트는 `agent-{agentId}.jsonl`로 저장됩니다.931에이전트 ID를 명시적으로 참조하려면 Claude에 ID를 요청할 수도 있으며, `~/.claude/projects/{project}/{sessionId}/subagents/`의 트랜스크립트 파일에서 ID를 찾을 수 있습니다. 각 트랜스크립트는 `agent-{agentId}.jsonl`로 저장됩니다.

908 932

909Subagent 트랜스크립트는 주 대화와 독립적으로 유지됩니다:933Subagent 트랜스크립트는 주 대화와 독립적으로 유지됩니다:

971| `x` | 완료된 포크를 닫거나 실행 중인 포크 중지 |995| `x` | 완료된 포크를 닫거나 실행 중인 포크 중지 |

972| `Esc` | 프롬프트 입력으로 포커스 반환 |996| `Esc` | 프롬프트 입력으로 포커스 반환 |

973 997

998포크 또는 subagent의 트랜스크립트가 열려 있으면 후속 메시지 및 [skills](/ko/skills)는 해당 에이전트로 이동하지만 기본 제공 명령은 여전히 주 대화에서 실행됩니다. {/* min-version: 2.1.199 */}v2.1.199부터 해당 보기에서 `/model` 또는 `/fast`를 입력하면 보기된 에이전트의 모델이나 빠른 모드가 아닌 주 대화의 모델이나 빠른 모드를 변경한다는 알림이 표시되며, 자동으로 실행되지 않습니다.

999

974<h3 id="how-forks-differ-from-named-subagents">1000<h3 id="how-forks-differ-from-named-subagents">

975 포크와 명명된 subagent의 차이점1001 포크와 명명된 subagent의 차이점

976</h3>1002</h3>

tools-reference.md +19 −11

Details

11사용자 정의 도구를 추가하려면 [MCP 서버](/ko/mcp)를 연결합니다. Claude를 재사용 가능한 프롬프트 기반 워크플로우로 확장하려면 [skill](/ko/skills)을 작성합니다. 이는 새로운 도구 항목을 추가하는 대신 기존 `Skill` 도구를 통해 실행됩니다.11사용자 정의 도구를 추가하려면 [MCP 서버](/ko/mcp)를 연결합니다. Claude를 재사용 가능한 프롬프트 기반 워크플로우로 확장하려면 [skill](/ko/skills)을 작성합니다. 이는 새로운 도구 항목을 추가하는 대신 기존 `Skill` 도구를 통해 실행됩니다.

12 12

13| 도구 | 설명 | 필요한 권한 |13| 도구 | 설명 | 필요한 권한 |

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

15| `Agent` | 작업을 처리하기 위해 자체 context window를 가진 [subagent](/ko/sub-agents)를 생성합니다. [Agent 도구 동작](#agent-tool-behavior) 참조 | 아니오 |15| `Agent` | 작업을 처리하기 위해 자체 context window를 가진 [subagent](/ko/sub-agents)를 생성합니다. [Agent 도구 동작](#agent-tool-behavior) 참조 | 아니오 |

16| `Artifact` | HTML 또는 Markdown 파일을 [artifact](/ko/artifacts)로 게시합니다: claude.ai의 비공개 대화형 페이지입니다. Team 및 Enterprise 플랜에서는 조직 내에서 공유할 수 있습니다. {/* plan-availability: feature=artifacts plans=pro,max,team,enterprise providers=anthropic */}Pro, Max, Team 또는 Enterprise 플랜이 필요하며 `/login` 인증이 필요합니다. [가용성](/ko/artifacts#availability) 참조 | 예 |16| `Artifact` | HTML 또는 Markdown 파일을 [artifact](/ko/artifacts)로 게시합니다: claude.ai의 비공개 대화형 페이지입니다. Team 및 Enterprise 플랜에서는 조직 내에서 공유할 수 있습니다. {/* plan-availability: feature=artifacts plans=pro,max,team,enterprise providers=anthropic */}Pro, Max, Team 또는 Enterprise 플랜이 필요하며 `/login` 인증이 필요합니다. [가용성](/ko/artifacts#availability) 참조 | 예 |

17| `AskUserQuestion` | 요구사항을 수집하거나 모호함을 명확히 하기 위해 객관식 질문을 합니다 | 아니오 |17| `AskUserQuestion` | 요구사항을 수집하거나 모호함을 명확히 하기 위해 객관식 질문을 합니다. {/* min-version: 2.1.198 */}v2.1.198부터 60초 이내에 응답하지 않으면 대화 상자가 자동으로 닫힙니다: 이미 선택한 옵션을 제출하고 Claude에게 키보드에서 멀어질 수 있음을 알리므로 Claude는 자체 판단으로 진행하고 나중에 다시 질문할 수 있습니다. 마지막 20초 동안 카운트다운이 나타납니다. 모든 키 입력은 대화 상자를 열린 상태로 유지하며, 포커스를 보고하는 터미널의 포커스된 창도 마찬가지입니다. [`CLAUDE_AFK_TIMEOUT_MS`](/ko/env-vars#variables) 환경 변수를 설정하여 Claude Code가 대기하는 시간을 변경하거나 24시간인 `86400000`과 같은 큰 값으로 설정하여 자리를 비웠을 때 질문을 열린 상태로 유지할 수 있습니다. 이 타임아웃은 `AskUserQuestion`의 객관식 질문에만 적용되며, 플랜 승인을 포함한 권한 프롬프트는 유휴 상태에서 자동으로 해결되지 않습니다 | 아니오 |

18| `Bash` | 환경에서 shell 명령을 실행합니다. [Bash 도구 동작](#bash-tool-behavior) 참조 | 예 |18| `Bash` | 환경에서 shell 명령을 실행합니다. [Bash 도구 동작](#bash-tool-behavior) 참조 | 예 |

19| `CronCreate` | 현재 세션 내에서 반복 또는 일회성 프롬프트를 예약합니다. 작업은 세션 범위이며 `--resume` 또는 `--continue`에서 만료되지 않으면 복원됩니다. [예약된 작업](/ko/scheduled-tasks) 참조 | 아니오 |19| `CronCreate` | 현재 세션 내에서 반복 또는 일회성 프롬프트를 예약합니다. 작업은 세션 범위이며 `--resume` 또는 `--continue`에서 만료되지 않으면 복원됩니다. [예약된 작업](/ko/scheduled-tasks) 참조 | 아니오 |

20| `CronDelete` | ID로 예약된 작업을 취소합니다 | 아니오 |20| `CronDelete` | ID로 예약된 작업을 취소합니다 | 아니오 |

35| `Read` | 파일의 내용을 읽습니다. [Read 도구 동작](#read-tool-behavior) 참조 | 아니오 |35| `Read` | 파일의 내용을 읽습니다. [Read 도구 동작](#read-tool-behavior) 참조 | 아니오 |

36| `ReadMcpResourceTool` | URI로 특정 MCP 리소스를 읽습니다 | 아니오 |36| `ReadMcpResourceTool` | URI로 특정 MCP 리소스를 읽습니다 | 아니오 |

37| `RemoteTrigger` | claude.ai에서 [Routines](/ko/routines)를 생성, 업데이트, 실행 및 나열합니다. `/schedule` 명령을 지원합니다. {/* plan-availability: feature=routines plans=pro,max,team,enterprise providers=anthropic */}Routines는 claude.ai에 있으며 Pro, Max, Team 또는 Enterprise 플랜이 필요하므로, 이 도구는 Amazon Bedrock, Google Vertex AI 또는 Microsoft Foundry에서 접근할 수 없습니다 | 아니오 |37| `RemoteTrigger` | claude.ai에서 [Routines](/ko/routines)를 생성, 업데이트, 실행 및 나열합니다. `/schedule` 명령을 지원합니다. {/* plan-availability: feature=routines plans=pro,max,team,enterprise providers=anthropic */}Routines는 claude.ai에 있으며 Pro, Max, Team 또는 Enterprise 플랜이 필요하므로, 이 도구는 Amazon Bedrock, Google Vertex AI 또는 Microsoft Foundry에서 접근할 수 없습니다 | 아니오 |

38| `ReportFindings` | 코드 리뷰 결과를 구조화된 목록으로 보고하며, 각 결과마다 파일, 요약 및 실패 시나리오를 포함하므로 Claude Code가 텍스트로 인쇄하는 대신 렌더링할 수 있습니다. Claude는 활성 코드 리뷰 지침이 이를 수행하도록 지시할 때 호출합니다. {/* min-version: 2.1.196 */}Claude Code v2.1.196 이상이 필요합니다 | 아니오 |38| `ReportFindings` | 코드 리뷰 결과를 구조화된 목록으로 보고하며, 각 결과마다 파일, 요약 및 실패 시나리오를 포함하므로 Claude Code가 텍스트로 인쇄하는 대신 렌더링할 수 있습니다. Claude는 활성 코드 리뷰 지침이 이를 수행하도록 지시할 때 호출합니다. {/* min-version: 2.1.196 */}Claude Code v2.1.196 이상이 필요합니다. {/* min-version: 2.1.199 */}v2.1.199부터 결과는 `correctness` 또는 `test-coverage`와 같은 선택적 `category` 슬러그를 포함할 수 있으며, 렌더링된 목록에서 파일 위치 옆에 표시됩니다 | 아니오 |

39| `ScheduleWakeup` | [자체 속도 `/loop`](/ko/scheduled-tasks#let-claude-choose-the-interval)의 다음 반복을 다시 예약합니다. Claude는 각 반복이 끝날 때 이를 호출하여 다음 반복이 실행될 시간을 선택합니다(1분에서 1시간 사이). 사용자가 직접 호출하지는 않습니다. 대기 중인 wakeup은 [Stop hook input](/ko/hooks#stop-input)의 `session_crons`에 나타납니다. {/* plan-availability: feature=loop-dynamic providers=anthropic */}Amazon Bedrock, Google Vertex AI 또는 Microsoft Foundry에서는 사용할 수 없으며, 여기서 간격이 없는 `/loop` 프롬프트는 고정 일정으로 실행됩니다 | 아니오 |39| `ScheduleWakeup` | [자체 속도 `/loop`](/ko/scheduled-tasks#let-claude-choose-the-interval)의 다음 반복을 다시 예약합니다. Claude는 각 반복이 끝날 때 이를 호출하여 다음 반복이 실행될 시간을 선택합니다(1분에서 1시간 사이). 사용자가 직접 호출하지는 않습니다. 대기 중인 wakeup은 [Stop hook input](/ko/hooks#stop-input)의 `session_crons`에 나타납니다. {/* plan-availability: feature=loop-dynamic providers=anthropic */}Amazon Bedrock, Google Vertex AI 또는 Microsoft Foundry에서는 사용할 수 없으며, 여기서 간격이 없는 `/loop` 프롬프트는 고정 일정으로 실행됩니다 | 아니오 |

40| `SendMessage` | [agent team](/ko/agent-teams) 팀원에게 메시지를 보내거나, agent ID로 [subagent를 재개합니다](/ko/sub-agents#resume-subagents). 중지된 subagent는 백그라운드에서 자동으로 재개됩니다. 구조화된 팀 프로토콜 메시지는 agent team이 필요합니다 | 아니오 |40| `SendMessage` | [agent team](/ko/agent-teams) 팀원에게 메시지를 보내거나, agent ID 또는 이름으로 [subagent를 재개합니다](/ko/sub-agents#resume-subagents). 중지된 subagent는 백그라운드에서 자동으로 재개됩니다. 구조화된 팀 프로토콜 메시지는 agent team이 필요합니다. {/* min-version: 2.1.198 */}v2.1.198부터 subagent는 이를 시작한 agent로부터의 메시지를 피어 요청이 아닌 일반 작업 지시로 취급합니다. {/* min-version: 2.1.199 */}v2.1.199부터 대화 초반에 해결된 이름과 다른 agent로 현재 해결되는 이름으로의 전송은 전달되는 대신 거부됩니다. [subagent 재개](/ko/sub-agents#resume-subagents) 참조 | 아니오 |

41| `SendUserFile` | 선택적 캡션과 함께 세션에서 파일을 사용자에게 보내므로, 생성된 보고서, 다이어그램, 스크린샷 또는 빌드된 아티팩트가 트랜스크립트에서만 언급되는 대신 사용자의 기기에 도달합니다. {/* min-version: 2.1.196 */}v2.1.196부터 선택적 `display` 입력은 프레젠테이션을 제어합니다: `render`는 클라이언트에서 파일을 인라인으로 열고, `attach`는 다운로드 카드만 표시하며, 설정되지 않으면 클라이언트가 파일 타입에 따라 결정합니다. [Remote Control](/ko/remote-control) 클라이언트가 연결되었거나 세션이 [Claude Code on the web](/ko/claude-code-on-the-web)과 같은 관리형 클라우드 환경에서 실행될 때 사용 가능합니다. 전달은 Anthropic 호스팅 인프라를 통해 실행되므로, 이 도구는 Amazon Bedrock, Google Vertex AI 또는 Microsoft Foundry에서 사용할 수 없습니다 | 아니오 |41| `SendUserFile` | 선택적 캡션과 함께 세션에서 파일을 사용자에게 보내므로, 생성된 보고서, 다이어그램, 스크린샷 또는 빌드된 아티팩트가 트랜스크립트에서만 언급되는 대신 사용자의 기기에 도달합니다. {/* min-version: 2.1.196 */}v2.1.196부터 선택적 `display` 입력은 프레젠테이션을 제어합니다: `render`는 클라이언트에서 파일을 인라인으로 열고, `attach`는 다운로드 카드만 표시하며, 설정되지 않으면 클라이언트가 파일 타입에 따라 결정합니다. [Remote Control](/ko/remote-control) 클라이언트가 연결되었거나 세션이 [Claude Code on the web](/ko/claude-code-on-the-web)과 같은 관리형 클라우드 환경에서 실행될 때 사용 가능합니다. 전달은 Anthropic 호스팅 인프라를 통해 실행되므로, 이 도구는 Amazon Bedrock, Google Vertex AI 또는 Microsoft Foundry에서 사용할 수 없습니다 | 아니오 |

42| `ShareOnboardingGuide` | {/* plan-availability: feature=onboarding-guide-share plans=pro,max,team,enterprise providers=anthropic */}}`ONBOARDING.md`를 업로드하고 팀원이 Claude Code에서 열 수 있는 공유 링크를 반환합니다. 가이드가 작성된 후 `/team-onboarding`에서 호출됩니다. Pro, Max, Team 및 Enterprise 플랜의 claude.ai 구독자가 사용 가능합니다 | 예 |42| `ShareOnboardingGuide` | {/* plan-availability: feature=onboarding-guide-share plans=pro,max,team,enterprise providers=anthropic */}}`ONBOARDING.md`를 업로드하고 팀원이 Claude Code에서 열 수 있는 공유 링크를 반환합니다. 가이드가 작성된 후 `/team-onboarding`에서 호출됩니다. Pro, Max, Team 및 Enterprise 플랜의 claude.ai 구독자가 사용 가능합니다 | 예 |

43| `Skill` | 주 대화 내에서 [skill](/ko/skills#control-who-invokes-a-skill)을 실행합니다 | 예 |43| `Skill` | 주 대화 내에서 [skill](/ko/skills#control-who-invokes-a-skill)을 실행합니다 | 예 |

45| `TaskGet` | 특정 작업의 전체 세부 정보를 검색합니다 | 아니오 |45| `TaskGet` | 특정 작업의 전체 세부 정보를 검색합니다 | 아니오 |

46| `TaskList` | 현재 상태와 함께 모든 작업을 나열합니다 | 아니오 |46| `TaskList` | 현재 상태와 함께 모든 작업을 나열합니다 | 아니오 |

47| `TaskOutput` | (더 이상 사용되지 않음) 백그라운드 작업에서 출력을 검색합니다. 작업의 출력 파일 경로에서 `Read`를 사용하는 것을 권장합니다 | 아니오 |47| `TaskOutput` | (더 이상 사용되지 않음) 백그라운드 작업에서 출력을 검색합니다. 작업의 출력 파일 경로에서 `Read`를 사용하는 것을 권장합니다 | 아니오 |

48| `TaskStop` | ID로 실행 중인 백그라운드 작업을 종료합니다 | 아니오 |48| `TaskStop` | ID로 실행 중인 백그라운드 작업을 종료합니다. {/* min-version: 2.1.198 */}v2.1.198부터 [agent team 팀원](/ko/agent-teams) 또는 agent ID 또는 이름으로 명명된 백그라운드 agent도 허용합니다 | 아니오 |

49| `TaskUpdate` | 작업 상태, 종속성, 세부 정보를 업데이트하거나 작업을 삭제합니다 | 아니오 |49| `TaskUpdate` | 작업 상태, 종속성, 세부 정보를 업데이트하거나 작업을 삭제합니다 | 아니오 |

50| `TodoWrite` | {/* min-version: 2.1.142 */}세션 작업 체크리스트를 관리합니다. v2.1.142부터 기본적으로 비활성화되어 있으며 `TaskCreate`, `TaskGet`, `TaskList`, `TaskUpdate`를 선호합니다. `CLAUDE_CODE_ENABLE_TASKS=0`을 설정하여 다시 활성화합니다 | 아니오 |50| `TodoWrite` | {/* min-version: 2.1.142 */}세션 작업 체크리스트를 관리합니다. v2.1.142부터 기본적으로 비활성화되어 있으며 `TaskCreate`, `TaskGet`, `TaskList`, `TaskUpdate`를 선호합니다. `CLAUDE_CODE_ENABLE_TASKS=0`을 설정하여 다시 활성화합니다 | 아니오 |

51| `ToolSearch` | [tool search](/ko/mcp#scale-with-mcp-tool-search)가 활성화되었을 때 지연된 도구를 검색하고 로드합니다 | 아니오 |51| `ToolSearch` | [tool search](/ko/mcp#scale-with-mcp-tool-search)가 활성화되었을 때 지연된 도구를 검색하고 로드합니다 | 아니오 |

52| `WaitForMcpServers` | {/* min-version: 2.1.142 */}백그라운드에서 여전히 연결 중인 하나 이상의 [MCP 서버](/ko/mcp)를 기다리므로, 요청이 세션을 다시 시작하지 않고도 해당 도구를 사용할 수 있습니다. Claude는 필요한 서버가 아직 연결되지 않았을 때 이를 호출합니다. [tool search](/ko/mcp#scale-with-mcp-tool-search)가 비활성화되었을 때만 나타나며, `ToolSearch`가 활성화되었을 때는 대기를 처리합니다 | 아니오 |52| `WaitForMcpServers` | 백그라운드에서 여전히 연결 중인 하나 이상의 [MCP 서버](/ko/mcp)를 기다리므로, 요청이 세션을 다시 시작하지 않고도 해당 도구를 사용할 수 있습니다. Claude는 필요한 서버가 아직 연결되지 않았을 때 이를 호출합니다. [tool search](/ko/mcp#scale-with-mcp-tool-search)가 비활성화되었을 때만 나타나며, `ToolSearch`가 활성화되었을 때는 대기를 처리합니다 | 아니오 |

53| `WebFetch` | 지정된 URL에서 콘텐츠를 가져옵니다. [WebFetch 도구 동작](#webfetch-tool-behavior) 참조 | 예 |53| `WebFetch` | 지정된 URL에서 콘텐츠를 가져옵니다. [WebFetch 도구 동작](#webfetch-tool-behavior) 참조 | 예 |

54| `WebSearch` | 웹 검색을 수행합니다. [WebSearch 도구 동작](#websearch-tool-behavior) 참조 | 예 |54| `WebSearch` | 웹 검색을 수행합니다. [WebSearch 도구 동작](#websearch-tool-behavior) 참조 | 예 |

55| `Workflow` | [동적 워크플로우](/ko/workflows)를 실행합니다: 백그라운드에서 많은 subagent를 조율하고 하나의 통합된 결과를 반환하는 스크립트입니다 | 예 |55| `Workflow` | [동적 워크플로우](/ko/workflows)를 실행합니다: 백그라운드에서 많은 subagent를 조율하고 하나의 통합된 결과를 반환하는 스크립트입니다 | 예 |

91 Agent 도구 동작91 Agent 도구 동작

92</h2>92</h2>

93 93

94Agent 도구는 별도의 context window에서 subagent를 생성합니다. Subagent는 자신의 작업을 자율적으로 처리한 다음 단일 텍스트 결과를 부모 대화에 반환합니다. 부모는 subagent의 중간 도구 호출이나 출력을 보지 못하고, 최종 결과만 봅니다. Subagent가 실행하는 턴의 수를 제한하려면 [subagent 정의](/ko/sub-agents#supported-frontmatter-fields)에서 `maxTurns`를 설정합니다.94Agent 도구는 별도의 context window에서 subagent를 생성합니다. Subagent는 자신의 작업을 자율적으로 처리한 다음 단일 텍스트 결과를 부모 대화에 반환합니다. 부모는 subagent의 중간 도구 호출이나 출력을 보지 못하고, 최종 결과만 봅니다.

96Subagent가 실행하는 턴의 수를 제한하려면 [subagent 정의](/ko/sub-agents#supported-frontmatter-fields)에서 `maxTurns`를 설정합니다.

95 97

96동일한 Agent 도구는 fork 모드가 활성화되었을 때 [forked subagent](/ko/sub-agents#fork-the-current-conversation)도 시작합니다. Fork는 새로 시작하는 대신 전체 부모 대화를 상속하고, 항상 백그라운드에서 실행되며, 여전히 터미널에서 권한 프롬프트를 표시합니다. 이 섹션의 나머지 부분은 명명된 subagent를 설명합니다.98동일한 Agent 도구는 fork 모드가 활성화되었을 때 [forked subagent](/ko/sub-agents#fork-the-current-conversation)도 시작합니다. Fork는 새로 시작하는 대신 전체 부모 대화를 상속하고, 항상 백그라운드에서 실행되며, 여전히 터미널에서 권한 프롬프트를 표시합니다. 이 섹션의 나머지 부분은 명명된 subagent를 설명합니다.

97 99

102* **`disallowedTools`만**: subagent는 나열된 도구를 제외한 모든 부모 도구를 가져옵니다.104* **`disallowedTools`만**: subagent는 나열된 도구를 제외한 모든 부모 도구를 가져옵니다.

103* **둘 다 설정됨**: `disallowedTools`가 우선합니다. 둘 다에 나열된 도구는 제거됩니다.105* **둘 다 설정됨**: `disallowedTools`가 우선합니다. 둘 다에 나열된 도구는 제거됩니다.

104 106

105Subagent를 시작하는 것 자체는 권한을 요청하지 않습니다. Subagent의 자체 도구 호출은 실행될 때 권한 규칙에 대해 확인됩니다:107Subagent를 시작하는 것 자체는 권한을 요청하지 않습니다. Claude Code는 subagent의 자체 도구 호출을 실행될 때 권한 규칙에 대해 확인합니다.

108

109{/* min-version: 2.1.198 */}v2.1.198부터 subagent는 기본적으로 백그라운드에서 실행됩니다. Claude는 계속하기 전에 결과가 필요할 때 포그라운드에서 하나를 실행합니다.

106 110

107* **포그라운드 subagent**는 각 도구 호출이 발생하는 순간 주 대화에서 보게 될 동일한 권한 프롬프트를 표시합니다.111* **포그라운드 subagent**는 각 도구 호출이 발생하는 순간 주 대화에서 보게 될 동일한 권한 프롬프트를 표시합니다.

108* **백그라운드 subagent** {/* min-version: 2.1.186 */}는 v2.1.186부터 주 세션에서 권한 프롬프트를 표시합니다. 프롬프트는 어느 subagent가 요청하는지 표시하며, Esc를 누르면 subagent를 중지하지 않고 해당 도구 호출만 거부합니다. v2.1.186 이전에는 백그라운드 subagent가 그렇지 않으면 프롬프트를 표시할 모든 도구 호출을 자동으로 거부하고 해당 도구 없이 계속 진행했습니다.112* **백그라운드 subagent** {/* min-version: 2.1.186 */}는 v2.1.186부터 주 세션에서 권한 프롬프트를 표시합니다. 프롬프트는 어느 subagent가 요청하는지 표시하며, Esc를 누르면 subagent를 중지하지 않고 해당 도구 호출만 거부합니다. v2.1.186 이전에는 백그라운드 subagent가 그렇지 않으면 프롬프트를 표시할 모든 도구 호출을 자동으로 거부하고 해당 도구 없이 계속 진행했습니다.

266 PowerShell 도구270 PowerShell 도구

267</h2>271</h2>

268 272

269PowerShell 도구를 사용하면 Claude는 PowerShell 명령을 기본적으로 실행할 수 있습니다. Windows에서는 이것이 Git Bash를 통해 라우팅하는 대신 PowerShell에서 명령을 실행한다는 의미입니다. Git Bash가 없는 Windows에서는 도구가 자동으로 활성화됩니다. Git Bash가 설치된 Windows에서는 도구가 점진적으로 출시되고 있습니다. Linux, macOS 및 WSL에서는 도구가 옵트인입니다.273PowerShell 도구를 사용하면 Claude는 PowerShell 명령을 기본적으로 실행할 수 있습니다. Windows에서는 이것이 Git Bash를 통해 라우팅하는 대신 PowerShell에서 명령을 실행한다는 의미입니다. 도구가 사용 가능해지는 방식은 플랫폼에 따라 다릅니다:

274

275* **Git Bash가 없는 Windows**: 도구가 자동으로 활성화됩니다.

276* **Git Bash가 설치된 Windows**: 도구가 점진적으로 출시되고 있습니다.

277* **Linux, macOS 및 WSL**: 도구가 옵트인입니다.

270 278

271<h3 id="enable-the-powershell-tool">279<h3 id="enable-the-powershell-tool">

272 PowerShell 도구 활성화280 PowerShell 도구 활성화

286 294

287Windows에서 Claude Code는 PowerShell 7+의 경우 `pwsh.exe`를 자동 감지하며 PowerShell 5.1의 경우 `powershell.exe`로 폴백합니다. 도구가 활성화되면 Claude는 PowerShell을 기본 셸로 취급합니다. Bash 도구는 Git Bash가 설치되어 있을 때 POSIX 스크립트에 사용할 수 있습니다.295Windows에서 Claude Code는 PowerShell 7+의 경우 `pwsh.exe`를 자동 감지하며 PowerShell 5.1의 경우 `powershell.exe`로 폴백합니다. 도구가 활성화되면 Claude는 PowerShell을 기본 셸로 취급합니다. Bash 도구는 Git Bash가 설치되어 있을 때 POSIX 스크립트에 사용할 수 있습니다.

288 296

289Claude Code는 프로세스 범위에서만 `-ExecutionPolicy Bypass`를 사용하여 PowerShell을 생성하므로 `.ps1` 스크립트 및 모듈 가져오기는 머신의 정책을 변경하지 않고도 기본 Windows 설치에서 작동합니다. 프로세스 범위 바이패스는 그룹 정책 `MachinePolicy` 또는 `UserPolicy`를 재정의하지 않으므로 엔터프라이즈 잠금이 여전히 적용됩니다. 머신의 유효한 실행 정책을 대신 존중하려면 `CLAUDE_CODE_POWERSHELL_RESPECT_EXECUTION_POLICY=1`을 설정합니다.297Claude Code는 프로세스 범위에서만 `-ExecutionPolicy Bypass`를 사용하여 PowerShell을 생성하므로 `.ps1` 스크립트 및 모듈 가져오기는 머신의 정책을 변경하지 않고도 기본 Windows 설치에서 작동합니다. 프로세스 범위 바이패스는 그룹 정책 `MachinePolicy` 또는 `UserPolicy`를 재정의하지 않으므로 엔터프라이즈 정책이 여전히 적용됩니다. 머신의 유효한 실행 정책을 대신 존중하려면 `CLAUDE_CODE_POWERSHELL_RESPECT_EXECUTION_POLICY=1`을 설정합니다.

290 298

291<h3 id="shell-selection-in-settings-hooks-and-skills">299<h3 id="shell-selection-in-settings-hooks-and-skills">

292 설정, hooks 및 skills의 shell 선택300 설정, hooks 및 skills의 shell 선택

361WebSearch 권한 규칙은 specifier를 사용하지 않습니다. `allow` 또는 `deny`의 단순 `WebSearch` 항목이 유일한 형식입니다.369WebSearch 권한 규칙은 specifier를 사용하지 않습니다. `allow` 또는 `deny`의 단순 `WebSearch` 항목이 유일한 형식입니다.

362 370

363<Note>371<Note>

364 WebSearch는 Claude API 및 Microsoft Foundry에서 사용 가능합니다. Google Cloud Vertex AI에서는 Opus, Sonnet 및 Haiku를 포함한 Claude 4 모델과 함께 작동합니다. Amazon Bedrock은 서버 측 web search 도구를 노출하지 않습니다.372 WebSearch는 Claude API, [AWS의 Claude Platform](/ko/claude-platform-on-aws) 및 Microsoft Foundry에서 사용 가능합니다. Google Cloud Vertex AI에서는 Opus, Sonnet 및 Haiku를 포함한 Claude 4 이상 모델과 함께 작동합니다. Amazon Bedrock은 서버 측 web search 도구를 노출하지 않습니다.

365</Note>373</Note>

366 374

367<h2 id="write-tool-behavior">375<h2 id="write-tool-behavior">

worktrees.md +2 −0

Details

36 36

37세션 중에 Claude에게 "worktree에서 작업하기"를 요청할 수도 있으며, [`EnterWorktree`](/ko/tools-reference) 도구로 하나를 생성합니다. worktree에 들어가면 Claude는 `.claude/worktrees/` 아래의 다른 worktree로 `EnterWorktree`를 호출하여 직접 전환할 수 있습니다. 이전 worktree는 디스크에 그대로 남아 있습니다.37세션 중에 Claude에게 "worktree에서 작업하기"를 요청할 수도 있으며, [`EnterWorktree`](/ko/tools-reference) 도구로 하나를 생성합니다. worktree에 들어가면 Claude는 `.claude/worktrees/` 아래의 다른 worktree로 `EnterWorktree`를 호출하여 직접 전환할 수 있습니다. 이전 worktree는 디스크에 그대로 남아 있습니다.

38 38

39{/* min-version: 2.1.198 */}v2.1.198부터 worktree에 들어가거나 나갈 때 세션 트랜스크립트도 해당 디렉터리의 프로젝트 저장소로 재배치되며, [`/cd`](/ko/commands)와 동일한 방식으로 작동하므로 `/desktop`과 `--resume`이 이후에 해당 위치에서 세션을 찾습니다. [`WorktreeCreate` 훅](#non-git-version-control)으로 생성된 Worktree는 제외되며 트랜스크립트를 시작 디렉터리에 유지합니다.

39처음으로 디렉터리에서 `--worktree`를 사용하기 전에 해당 디렉터리에서 `claude`를 한 번 실행하여 작업 공간 신뢰 대화를 수락합니다. 신뢰가 아직 수락되지 않았으면 `--worktree`는 오류와 함께 종료되고 먼저 디렉터리에서 `claude`를 실행하도록 요청합니다. `-p`를 사용한 비대화형 실행은 [신뢰 확인](/ko/security)을 건너뛰므로 `claude -p --worktree`는 이를 수행하지 않고 진행됩니다.41처음으로 디렉터리에서 `--worktree`를 사용하기 전에 해당 디렉터리에서 `claude`를 한 번 실행하여 작업 공간 신뢰 대화를 수락합니다. 신뢰가 아직 수락되지 않았으면 `--worktree`는 오류와 함께 종료되고 먼저 디렉터리에서 `claude`를 실행하도록 요청합니다. `-p`를 사용한 비대화형 실행은 [신뢰 확인](/ko/security)을 건너뛰므로 `claude -p --worktree`는 이를 수행하지 않고 진행됩니다.

40 42

41<Tip>43<Tip>

Documentation 2026-07-02 23:59 UTC to 2026-07-03 23:00 UTC