Documentation — Spybara

admin-setup.md +1 −0

Details

106| [claude.ai 동기화 비활성화](/docs/ko/settings-reference#syncclaudeaiskills) | Claude Code가 개발자가 claude.ai에서 활성화하는 [skills](/docs/ko/skills#how-synced-skills-behave) 및 [플러그인](/docs/ko/plugins/loading#synced-plugins)을 로드하지 않도록 합니다. 조직의 claude.ai에서 Skills를 끄면 Claude Code는 둘 다 동기화를 중지하고, v2.1.273 이상에서는 이미 동기화한 것도 제거합니다. Skills를 끄지 않고 둘 중 하나를 중지하려면 관리되는 설정에서 해당 키를 `false`로 설정합니다 | `syncClaudeAiSkills`, `syncClaudeAiPlugins` |106| [claude.ai 동기화 비활성화](/docs/ko/settings-reference#syncclaudeaiskills) | Claude Code가 개발자가 claude.ai에서 활성화하는 [skills](/docs/ko/skills#how-synced-skills-behave) 및 [플러그인](/docs/ko/plugins/loading#synced-plugins)을 로드하지 않도록 합니다. 조직의 claude.ai에서 Skills를 끄면 Claude Code는 둘 다 동기화를 중지하고, v2.1.273 이상에서는 이미 동기화한 것도 제거합니다. Skills를 끄지 않고 둘 중 하나를 중지하려면 관리되는 설정에서 해당 키를 `false`로 설정합니다 | `syncClaudeAiSkills`, `syncClaudeAiPlugins` |

107| [Hook 제한](/docs/ko/settings-reference#allowmanagedhooksonly) | 실행되는 hooks를 제한하고 HTTP hook URL을 제한합니다. 전체 효과 목록은 [`allowManagedHooksOnly` 아래에서 실행되는 것](/docs/ko/settings-reference#what-runs-under-allowmanagedhooksonly)을 참조하세요 | `allowManagedHooksOnly`, `allowedHttpHookUrls` |107| [Hook 제한](/docs/ko/settings-reference#allowmanagedhooksonly) | 실행되는 hooks를 제한하고 HTTP hook URL을 제한합니다. 전체 효과 목록은 [`allowManagedHooksOnly` 아래에서 실행되는 것](/docs/ko/settings-reference#what-runs-under-allowmanagedhooksonly)을 참조하세요 | `allowManagedHooksOnly`, `allowedHttpHookUrls` |

108| [로그인 적용](/docs/ko/settings-reference#forceloginmethod) | 로그인을 특정 방법 또는 Anthropic 조직으로 제한합니다. 메서드 제한은 VS Code 확장, Agent SDK, `claude setup-token` 및 `/install-github-app` 전체에 적용되며, 터미널의 대화형 로그인 화면은 `/login` 또는 처음 실행 온보딩으로 도달하며, 메서드를 적용하지 않고 미리 선택합니다. Claude Code는 터미널, VS Code 확장 및 Agent SDK에서 claude.ai 계정 로그인에 대한 조직을 확인하며, Claude Console 로그인 또는 [gateway](/docs/ko/claude-apps-gateway) 로그인에 대해서는 확인하지 않습니다. v2.1.212 이전에는 터미널 로그인만 두 키를 모두 적용했습니다. 설정되면 `ANTHROPIC_API_KEY`, `ANTHROPIC_AUTH_TOKEN` 또는 `apiKeyHelper`로 인증된 세션은 시작 시 차단됩니다. 클라우드 공급자 세션은 이러한 자격 증명 중 하나 또는 이전 Claude Console 로그인으로 저장된 API 키도 있는 경우가 아니면 영향을 받지 않습니다 | `forceLoginMethod`, `forceLoginOrgUUID` |108| [로그인 적용](/docs/ko/settings-reference#forceloginmethod) | 로그인을 특정 방법 또는 Anthropic 조직으로 제한합니다. 메서드 제한은 VS Code 확장, Agent SDK, `claude setup-token` 및 `/install-github-app` 전체에 적용되며, 터미널의 대화형 로그인 화면은 `/login` 또는 처음 실행 온보딩으로 도달하며, 메서드를 적용하지 않고 미리 선택합니다. Claude Code는 터미널, VS Code 확장 및 Agent SDK에서 claude.ai 계정 로그인에 대한 조직을 확인하며, Claude Console 로그인 또는 [gateway](/docs/ko/claude-apps-gateway) 로그인에 대해서는 확인하지 않습니다. v2.1.212 이전에는 터미널 로그인만 두 키를 모두 적용했습니다. 설정되면 `ANTHROPIC_API_KEY`, `ANTHROPIC_AUTH_TOKEN` 또는 `apiKeyHelper`로 인증된 세션은 시작 시 차단됩니다. 클라우드 공급자 세션은 이러한 자격 증명 중 하나 또는 이전 Claude Console 로그인으로 저장된 API 키도 있는 경우가 아니면 영향을 받지 않습니다 | `forceLoginMethod`, `forceLoginOrgUUID` |

109| [공급자 제한](/docs/ko/settings-reference#allowedproviders) | 머신이 사용할 수 있는 API 공급자를 제한합니다. 나열되지 않은 공급자의 세션은 시작 시, 로그인 시, API에 다음으로 연락할 때 거부됩니다. Claude Code v2.1.285 이상이 필요합니다 | `allowedProviders` |

110| [기업 런처 구성](/docs/ko/corporate-launcher) | [백그라운드 에이전트 감독자](/docs/ko/agent-view#how-background-sessions-are-hosted), 해당 워커 및 [다른 적용 대상 백그라운드 프로세스](/docs/ko/corporate-launcher#what-the-launcher-covers)에 에이전트 보기를 끄는 대신 필수 기업 런처를 접두사로 붙입니다 | `processWrapper` |111| [기업 런처 구성](/docs/ko/corporate-launcher) | [백그라운드 에이전트 감독자](/docs/ko/agent-view#how-background-sessions-are-hosted), 해당 워커 및 [다른 적용 대상 백그라운드 프로세스](/docs/ko/corporate-launcher#what-the-launcher-covers)에 에이전트 보기를 끄는 대신 필수 기업 런처를 접두사로 붙입니다 | `processWrapper` |

111| [모델 제한](/docs/ko/model-config#restrict-model-selection) | `availableModels`는 선택기에 나타나는 모델을 필터링합니다. `enforceAvailableModels`를 추가하면 자동 선택된 기본 모델도 제한합니다. 이 설정이 CLI, 웹 및 IDE에 도달하는 방법은 [표면 적용 범위](/docs/ko/model-config#surface-coverage)를 참조하세요 | `availableModels`, `enforceAvailableModels` |112| [모델 제한](/docs/ko/model-config#restrict-model-selection) | `availableModels`는 선택기에 나타나는 모델을 필터링합니다. `enforceAvailableModels`를 추가하면 자동 선택된 기본 모델도 제한합니다. 이 설정이 CLI, 웹 및 IDE에 도달하는 방법은 [표면 적용 범위](/docs/ko/model-config#surface-coverage)를 참조하세요 | `availableModels`, `enforceAvailableModels` |

agent-sdk/hooks.md +6 −2

Details

418 ```418 ```

419</CodeGroup>419</CodeGroup>

420 420

421차단을 확인하려면 `PreToolUse`에서 콜백을 `Write|Edit` 매처로 등록하고 에이전트에 `/etc` 아래에 파일을 생성하도록 요청합니다. 메시지 스트림의 Write 도구 결과에는 `Writing to /etc is not allowed`가 포함되며 파일이 생성되지 않습니다.

422

421<h3 id="auto-approve-specific-tools">423<h3 id="auto-approve-specific-tools">

422 특정 도구 자동 승인424 특정 도구 자동 승인

423</h3>425</h3>

468 470

469이벤트가 발생하면 일치하는 모든 훅이 병렬로 실행됩니다. 권한 결정의 경우 가장 제한적인 결과가 우선합니다. 단일 `deny`는 다른 훅이 반환하는 것에 관계없이 도구 호출을 차단합니다. 완료 순서가 비결정적이므로 다른 훅이 먼저 실행되었다고 가정하지 않고 각 훅이 독립적으로 작동하도록 작성합니다.471이벤트가 발생하면 일치하는 모든 훅이 병렬로 실행됩니다. 권한 결정의 경우 가장 제한적인 결과가 우선합니다. 단일 `deny`는 다른 훅이 반환하는 것에 관계없이 도구 호출을 차단합니다. 완료 순서가 비결정적이므로 다른 훅이 먼저 실행되었다고 가정하지 않고 각 훅이 독립적으로 작동하도록 작성합니다.

470 472

471아래 예제는 모든 도구 호출에 대해 세 가지 독립적인 확인을 등록합니다:473아래 예제는 모든 도구 호출에 대해 세 가지 독립적인 확인을 등록합니다. 예제의 훅 이름(예: Python의 `audit_logger` 또는 TypeScript의 `auditLogger`)은 사용자가 정의하는 콜백을 나타냅니다:

472 474

473<CodeGroup>475<CodeGroup>

474 ```python Python theme={null}476 ```python Python theme={null}

500 다중 도구 매처로 필터링502 다중 도구 매처로 필터링

501</h3>503</h3>

502 504

503다중 도구 매처를 사용하여 관련 도구 간에 하나의 콜백을 공유합니다. 이 예제는 서로 다른 범위의 세 가지 매처를 등록합니다:505다중 도구 매처를 사용하여 관련 도구 간에 하나의 콜백을 공유합니다. 이 예제는 서로 다른 범위의 세 가지 매처를 등록하며, 예제의 각 훅 이름은 사용자가 정의하는 콜백을 나타냅니다:

504 506

505* 파이프로 구분된 정확한 목록(`Write|Edit|NotebookEdit`)은 파일 수정 도구에만 `file_security_hook`을 트리거합니다.507* 파이프로 구분된 정확한 목록(`Write|Edit|NotebookEdit`)은 파일 수정 도구에만 `file_security_hook`을 트리거합니다.

506* 정규식(`^mcp__`)은 이름이 `mcp__`로 시작하는 모든 MCP 도구에 대해 `mcp_audit_hook`을 트리거합니다.508* 정규식(`^mcp__`)은 이름이 `mcp__`로 시작하는 모든 MCP 도구에 대해 `mcp_audit_hook`을 트리거합니다.

585 ```587 ```

586</CodeGroup>588</CodeGroup>

587 589

590훅이 발생하는지 확인하려면 콜백을 등록하고 에이전트에 현재 디렉토리의 파일을 나열하는 등 작은 작업을 서브에이전트에 위임하도록 요청합니다. 서브에이전트가 완료되면 콜백은 서브에이전트의 ID와 트랜스크립트 경로와 함께 `[SUBAGENT] Completed:` 줄을 출력합니다.

591

588<h3 id="make-http-requests-from-hooks">592<h3 id="make-http-requests-from-hooks">

589 훅에서 HTTP 요청 만들기593 훅에서 HTTP 요청 만들기

590</h3>594</h3>

agent-sdk/permissions.md +9 −0

Details

121 121

122권한 모드는 Claude가 도구를 사용하는 방식을 전역적으로 제어합니다. `query()`를 호출할 때 권한 모드를 설정하거나 스트리밍 세션 중에 동적으로 변경할 수 있습니다.122권한 모드는 Claude가 도구를 사용하는 방식을 전역적으로 제어합니다. `query()`를 호출할 때 권한 모드를 설정하거나 스트리밍 세션 중에 동적으로 변경할 수 있습니다.

123 123

124권한 모드를 설정하지 않으면 Claude Code는 [세션이 시작되는 모드](/docs/ko/permission-modes#which-mode-a-session-starts-in)의 규칙에 따라 시작 권한 모드를 선택합니다.

125

126* 적용되는 세션의 [설정 파일](/docs/ko/settings#where-settings-live)의 `permissions.defaultMode`

127* 그렇지 않으면 [자동 모드](/docs/ko/permission-modes#eliminate-prompts-with-auto-mode)일 수 있는 기본 제공 기본값

128

129자동 모드에서 시작하는 세션은 `Bash` 항목과 같은 광범위한 허용 규칙을 삭제합니다. [자동 모드가 작업을 평가하는 방식](/docs/ko/permission-modes#how-auto-mode-evaluates-actions)에서 설명합니다. 애플리케이션이 `default` 모드 또는 이러한 규칙에 의존하는 경우 `default`를 명시적으로 전달하세요.

130

131TypeScript Agent SDK v0.3.286 이전에는 `permissionMode`를 생략하는 것이 `default`를 전달하는 것과 동일했습니다.

132

124<h3 id="available-modes">133<h3 id="available-modes">

125 사용 가능한 모드134 사용 가능한 모드

126</h3>135</h3>

agent-sdk/python.md +249 −75

Details

517 async def set_model(self, model: str | None = None) -> None517 async def set_model(self, model: str | None = None) -> None

518 async def rewind_files(self, user_message_id: str) -> None518 async def rewind_files(self, user_message_id: str) -> None

519 async def get_mcp_status(self) -> McpStatusResponse519 async def get_mcp_status(self) -> McpStatusResponse

520 async def get_context_usage(self) -> ContextUsageResponse

520 async def reconnect_mcp_server(self, server_name: str) -> None521 async def reconnect_mcp_server(self, server_name: str) -> None

521 async def toggle_mcp_server(self, server_name: str, enabled: bool) -> None522 async def toggle_mcp_server(self, server_name: str, enabled: bool) -> None

522 async def stop_task(self, task_id: str) -> None523 async def stop_task(self, task_id: str) -> None

541| `rewind_files(user_message_id)` | 지정된 사용자 메시지의 상태로 파일 복원. `enable_file_checkpointing=True` 필요. [파일 체크포인팅](/docs/ko/agent-sdk/file-checkpointing) 참조 |542| `rewind_files(user_message_id)` | 지정된 사용자 메시지의 상태로 파일 복원. `enable_file_checkpointing=True` 필요. [파일 체크포인팅](/docs/ko/agent-sdk/file-checkpointing) 참조 |

544| `get_context_usage()` | 카테고리, 스킬 및 도구별 컨텍스트 윈도우 사용량의 분석 가져오기. 대화형 세션에서 `/context`가 표시하는 것과 동일한 데이터입니다. [`ContextUsageResponse`](#contextusageresponse)를 반환합니다. 분석을 계산하기 위해 Claude Code는 메시지 스트림에 나타나지 않는 여러 토큰 계산 API 요청을 수행합니다. [이러한 요청이 어떻게 처리되는지](#contextusageresponse) 참조 |

545| `stop_task(task_id)` | 실행 중인 백그라운드 작업 중지. 상태 `"stopped"`인 [`TaskNotificationMessage`](#tasknotificationmessage)가 메시지 스트림에서 따릅니다 |547| `stop_task(task_id)` | 실행 중인 백그라운드 작업 중지. 상태 `"stopped"`인 [`TaskNotificationMessage`](#tasknotificationmessage)가 메시지 스트림에서 따릅니다 |

616 예제 - ClaudeSDKClient를 사용한 스트리밍 입력618 예제 - ClaudeSDKClient를 사용한 스트리밍 입력

617</h4>619</h4>

618 620

621`query()`는 사용자 메시지 딕셔너리의 비동기 반복 가능 객체도 허용하므로, 전송 시간에 프롬프트를 조립하거나 이미지와 같은 콘텐츠 블록을 포함할 수 있습니다. Claude Code는 반복 가능 객체가 완료될 때까지 기다리지 않고 첫 번째 생성된 메시지가 도착하는 즉시 응답을 시작하며, `receive_response()`는 해당 응답을 종료하는 `ResultMessage`에서 중지됩니다. Claude가 답변하기 전에 읽어야 할 모든 것을 이 생성기처럼 하나의 메시지에 넣고, 각 `query()` 호출을 자신의 `receive_response()` 루프와 쌍을 이루십시오.

622

619```python theme={null}623```python theme={null}

620import asyncio624import asyncio

621from claude_agent_sdk import ClaudeSDKClient625from claude_agent_sdk import ClaudeSDKClient

622 626

623 627

624async def message_stream():628async def message_stream():

625 """Generate messages dynamically."""629 """Assemble the prompt at send time and yield it as one user message."""

626 yield {630 readings = {"Temperature": "25°C", "Humidity": "60%"}

627 "type": "user",631 data = ", ".join(f"{name}: {value}" for name, value in readings.items())

628 "message": {"role": "user", "content": "Analyze the following data:"},

629 }

630 await asyncio.sleep(0.5)

631 yield {

632 "type": "user",

633 "message": {"role": "user", "content": "Temperature: 25°C, Humidity: 60%"},

634 }

635 await asyncio.sleep(0.5)

636 yield {632 yield {

637 "type": "user",633 "type": "user",

638 "message": {"role": "user", "content": "What patterns do you see?"},634 "message": {

635 "role": "user",

636 "content": f"Analyze the following sensor data and describe any patterns you see: {data}",

637 },

639 }638 }

640 639

641 640

1012| `type` | 예 | 프리셋 시스템 프롬프트를 사용하려면 `"preset"`이어야 합니다 |1011| `type` | 예 | 프리셋 시스템 프롬프트를 사용하려면 `"preset"`이어야 합니다 |

1013| `preset` | 예 | Claude Code의 시스템 프롬프트를 사용하려면 `"claude_code"`이어야 합니다 |1012| `preset` | 예 | Claude Code의 시스템 프롬프트를 사용하려면 `"claude_code"`이어야 합니다 |

1014| `append` | 아니오 | 프리셋 시스템 프롬프트에 추가할 추가 지침 |1013| `append` | 아니오 | 프리셋 시스템 프롬프트에 추가할 추가 지침 |

1015| `exclude_dynamic_sections` | 아니오 | 작업 디렉토리, git 상태 및 메모리 경로와 같은 세션별 컨텍스트를 시스템 프롬프트에서 첫 사용자 메시지로 이동합니다. 사용자 및 머신 간 프롬프트 캐시 재사용을 개선합니다. [시스템 프롬프트 수정](/docs/ko/agent-sdk/modifying-system-prompts#improve-prompt-caching-across-users-and-machines) 참조 |1014| `exclude_dynamic_sections` | 아니오 | 사용자별 컨텍스트 (예: 자동 메모리 위치)를 시스템 프롬프트에서 첫 사용자 메시지로 이동합니다. 사용자 및 머신 간 프롬프트 캐시 재사용을 개선합니다. [시스템 프롬프트 수정](/docs/ko/agent-sdk/modifying-system-prompts#improve-prompt-caching-across-users-and-machines) 참조 |

1016| `snapshot` | 아니오 | `False`로 설정하여 [세션이 첫 요청에서 기록한 프롬프트를 재사용](/docs/ko/agent-sdk/modifying-system-prompts#change-the-prompt-of-an-existing-session) 대신 모든 요청에서 시스템 프롬프트를 다시 빌드합니다. Python Agent SDK 0.2.153 이상 필요 |1015| `snapshot` | 아니오 | `False`로 설정하여 [세션이 첫 요청에서 기록한 프롬프트를 재사용](/docs/ko/agent-sdk/modifying-system-prompts#change-the-prompt-of-an-existing-session) 대신 모든 요청에서 시스템 프롬프트를 다시 빌드합니다. Python Agent SDK 0.2.153 이상 필요 |

1017 1016

1018<h3 id="systempromptcustom">1017<h3 id="systempromptcustom">

1609 1608

1609<h3 id="contextusageresponse">

1610 `ContextUsageResponse`

1611</h3>

1612

1613[`ClaudeSDKClient.get_context_usage()`](#methods)의 응답입니다. 이것은 Claude Code가 대화형 세션에서 `/context` 명령을 위해 렌더링하는 것과 동일한 페이로드이므로, 토큰 수 외에도 Claude Code가 `/context` 사용량 그리드를 그리는 데 사용하는 `color` 및 `gridRows`와 같은 표시 필드를 포함합니다.

1614

1615Claude Code는 [토큰 계산](https://platform.claude.com/docs/en/build-with-claude/token-counting) API에 여러 요청을 보내 이 페이로드를 빌드합니다. 이 요청은 메시지 스트림에 나타나지 않으므로, 스트림을 읽는 비용 추적은 이를 보지 못합니다. Anthropic API에서 토큰 계산은 청구되지 않습니다.

1616

1617```python theme={null}

1618class ContextUsageResponse(TypedDict):

1619 categories: list[ContextUsageCategory]

1620 totalTokens: int

1621 maxTokens: int

1622 rawMaxTokens: int

1623 percentage: float

1624 model: str

1625 isAutoCompactEnabled: bool

1626 memoryFiles: list[dict[str, Any]]

1627 mcpTools: list[dict[str, Any]]

1628 agents: list[dict[str, Any]]

1629 gridRows: list[list[dict[str, Any]]]

1630 autoCompactThreshold: NotRequired[int]

1631 deferredBuiltinTools: NotRequired[list[dict[str, Any]]]

1632 systemTools: NotRequired[list[dict[str, Any]]]

1633 systemPromptSections: NotRequired[list[dict[str, Any]]]

1634 slashCommands: NotRequired[dict[str, Any]]

1635 skills: NotRequired[dict[str, Any]] # skill usage with frontmatter breakdown

1636 messageBreakdown: NotRequired[dict[str, Any]] # message tokens by type

1637 apiUsage: NotRequired[dict[str, Any] | None]

1638```

1639

1640각 `ContextUsageCategory` 항목은 `name`, `tokens`, `color` 및 선택적 `isDeferred` 플래그를 포함합니다. `totalTokens`는 세션의 현재 컨텍스트 사용량이고, `maxTokens`는 사용량이 측정되는 윈도우입니다. 해당 윈도우는 모델의 컨텍스트 윈도우이거나, 적용되는 자동 압축 윈도우이며, `rawMaxTokens`는 `maxTokens`와 동일한 값을 포함합니다. `apiUsage`는 세션의 실행 총계가 아닌 최신 API 응답의 사용량을 보유합니다. Claude Code는 선택적 `deferredBuiltinTools`, `systemTools` 및 `systemPromptSections` 키를 설정하지 않으므로, 타입이 이를 선언하더라도 이들이 없을 것으로 예상합니다.

1641

1610<h3 id="sdkpluginconfig">1642<h3 id="sdkpluginconfig">

1611 `SdkPluginConfig`1643 `SdkPluginConfig`

1612</h3>1644</h3>

2712 2744

2713모든 기본 Claude Code 도구의 입력/출력 스키마 문서입니다. Python SDK는 이들을 타입으로 내보내지 않지만, 메시지의 도구 입력 및 출력 구조를 나타냅니다.2745모든 기본 Claude Code 도구의 입력/출력 스키마 문서입니다. Python SDK는 이들을 타입으로 내보내지 않지만, 메시지의 도구 입력 및 출력 구조를 나타냅니다.

2714 2746

2747각 출력은 해당 도구에 대해 [`UserMessage.tool_use_result`](#usermessage)에서 읽는 값입니다. 키 이름은 Claude Code가 내보내는 그대로 나타납니다. `| None`으로 주석이 달린 키와 "present when" 또는 "optional" 주석이 있는 키는 적용되지 않을 때 생략됩니다.

2748

2715<h3 id="agent">2749<h3 id="agent">

2716 Agent2750 Agent

2717</h3>2751</h3>

2805```python theme={null}2839```python theme={null}

2806{2840{

2807 "status": "remote_launched",2841 "status": "remote_launched",

2808 "taskId": str, # 원격 작업의 ID2842 "taskId": str, # 전달된 작업의 ID

2809 "sessionUrl": str, # 원격 클라우드 세션으로의 링크2843 "sessionUrl": str, # 클라우드 세션으로의 링크

2810 "description": str, # 작업 설명2844 "description": str, # 작업 설명

2811 "prompt": str, # 에이전트가 실행하는 프롬프트2845 "prompt": str, # 에이전트가 실행하는 프롬프트

2812 "outputFile": str, # 에이전트의 출력이 기록되는 파일 경로2846 "outputFile": str, # 에이전트의 출력이 기록되는 파일 경로

2813}2847}

2814```2848```

2815 2849

2816서브에이전트의 결과를 반환합니다. 출력은 `status` 필드에서 구분됩니다: 완료된 작업의 경우 `"completed"`, 백그라운드 작업의 경우 `"async_launched"`, Claude Code가 원격 클라우드 세션으로 전달한 작업의 경우 `"remote_launched"`. `sessionUrl`은 해당 세션으로 연결되고 `taskId`는 이를 식별합니다. Claude Code가 [서브에이전트의 격리된 worktree를 유지](/docs/ko/worktrees#isolate-subagents-with-worktrees)한 경우, `completed` 변형의 `worktreePath`는 이를 찾을 수 있는 위치이고, `worktreeBranch`는 Claude Code가 git으로 worktree를 생성했을 때의 브랜치입니다.2850서브에이전트의 결과를 반환합니다. 출력은 `status` 필드에서 구분됩니다: 완료된 작업의 경우 `"completed"`, 백그라운드 작업의 경우 `"async_launched"`, Claude Code가 클라우드 세션으로 전달한 작업의 경우 `"remote_launched"`. `sessionUrl`은 해당 세션으로 연결되고 `taskId`는 이를 식별합니다. Claude Code가 [서브에이전트의 격리된 worktree를 유지](/docs/ko/worktrees#isolate-subagents-with-worktrees)한 경우, `completed` 변형의 `worktreePath`는 이를 찾을 수 있는 위치이고, `worktreeBranch`는 Claude Code가 git으로 worktree를 생성했을 때의 브랜치입니다.

2817 2851

2818`completed` 변형에서 `resolvedModel`은 서브에이전트가 시작한 모델을 이름 지으며, 이는 [`availableModels`](/docs/ko/model-config#restrict-model-selection) 또는 다른 오버라이드가 적용될 때 요청된 `model` 입력과 다를 수 있습니다. 이 필드는 Claude Code v2.1.174 이상이 필요합니다. `async_launched` 변형에서 `resolvedModel`은 에이전트가 백그라운드로 이동했을 때 사용 중인 모델을 이름 지으므로, 백그라운드 전환 전에 발생한 스왑이 반영됩니다. `modelsUsed` 필드는 두 변형 모두에서 순서대로 사용된 모델을 나열하며, 연속 반복은 축소됩니다. 실행 중에 모델이 교체되었을 때만 설정됩니다. `modelsUsed`와 백그라운드 시간 `resolvedModel` 동작은 Claude Code v2.1.212 이상이 필요합니다.2852`completed` 변형에서 `resolvedModel`은 서브에이전트가 시작한 모델을 이름 지으며, 이는 [`availableModels`](/docs/ko/model-config#restrict-model-selection) 또는 다른 오버라이드가 적용될 때 요청된 `model` 입력과 다를 수 있습니다. 이 필드는 Claude Code v2.1.174 이상이 필요합니다. `async_launched` 변형에서 `resolvedModel`은 에이전트가 백그라운드로 이동했을 때 사용 중인 모델을 이름 지으므로, 백그라운드 전환 전에 발생한 스왑이 반영됩니다. `modelsUsed` 필드는 두 변형 모두에서 순서대로 사용된 모델을 나열하며, 연속 반복은 축소됩니다. 실행 중에 모델이 교체되었을 때만 설정됩니다. `modelsUsed`와 백그라운드 시간 `resolvedModel` 동작은 Claude Code v2.1.212 이상이 필요합니다.

2819 2853

2820Claude Code는 전체 실행이 아닌 서브에이전트의 최종 API 요청에서 `usage`와 `totalTokens`를 채웁니다. `usage`의 `output_tokens_details` 아래 `thinking_tokens`이 있을 때, 이는 해당 요청의 출력 토큰 중 생각 토큰의 수입니다. `output_tokens_details` 키는 Claude Code v2.1.228을 번들로 하는 Python SDK v0.2.136 이상이 필요합니다.2854Claude Code는 전체 실행이 아닌 서브에이전트의 최종 API 요청에서 `usage`와 `totalTokens`를 채웁니다. 존재할 때, `usage`의 `output_tokens_details` 아래 `thinking_tokens`은 해당 요청의 출력 토큰 중 생각 토큰의 수입니다. `output_tokens_details` 키는 Claude Code v2.1.228을 번들로 하는 Python SDK v0.2.136 이상이 필요합니다.

2821 2855

2822<h3 id="askuserquestion">2856<h3 id="askuserquestion">

2823 AskUserQuestion2857 AskUserQuestion

2885 2919

2886**도구 이름:** `Bash`2920**도구 이름:** `Bash`

2887 2921

2888전경 상한선을 설정하는 것에 대해서는 [시간 초과 및 출력 제한](/docs/ko/tools-reference#timeout-and-output-limits)을 참조하십시오. 백그라운드 시간 제한에 대해서는 [백그라운드 명령](/docs/ko/tools-reference#background-commands)을 참조하십시오.2922전경 상한선을 설정하는 것에 대해서는 [시간 초과 및 출력 제한](/docs/ko/tools-reference#timeout-and-output-limits)을 참조하십시오. 백그라운드 시간 제한에 대해서는 [백그라운드 명령의 시간 제한](/docs/ko/tools-reference#time-limit-for-background-commands)을 참조하십시오.

2889 2923

2890**입력:**2924**입력:**

2891 2925

2962 2996

2963```python theme={null}2997```python theme={null}

2964{2998{

2965 "message": str, # 확인 메시지2999 "filePath": str, # 편집된 파일

2966 "replacements": int, # 수행된 바꾸기 수3000 "oldString": str, # 바뀐 텍스트

2967 "file_path": str, # 편집된 파일 경로3001 "newString": str, # 이를 대체한 텍스트

3002 "originalFile": str | None, # 편집 전 파일 내용

3003 "structuredPatch": [ # 변경에 대한 Diff 청크

3004 {

3005 "oldStart": int,

3006 "oldLines": int,

3007 "newStart": int,

3008 "newLines": int,

3009 "lines": list[str],

3010 }

3011 ],

3012 "userModified": bool, # 사용자가 제안된 편집을 수락하기 전에 변경했는지 여부

3013 "replaceAll": bool, # 모든 항목이 바뀌었는지 여부

3014 "gitDiff": { # 파일에 대한 선택적 git diff 요약

3015 "filename": str,

3016 "status": "modified" | "added",

3017 "additions": int,

3018 "deletions": int,

3019 "changes": int,

3020 "patch": str,

3021 "repository": str | None, # 사용 가능할 때 GitHub owner/repo

3022 } | None,

2968}3023}

2969```3024```

2970 3025

2984}3039}

2985```3040```

2986 3041

2987**출력 (텍스트 파일):**3042Claude가 읽은 내용에 따라 출력은 다음 형태 중 하나를 취합니다. `type` 키를 확인하여 구분하십시오.

3043

3044**출력 (type: `"text"`):**

3045

3046```python theme={null}

3047{

3048 "type": "text",

3049 "file": {

3050 "filePath": str, # 읽은 파일

3051 "content": str, # 반환된 콘텐츠

3052 "numLines": int, # 반환된 콘텐츠의 줄 수

3053 "startLine": int, # 콘텐츠가 시작되는 줄 번호

3054 "totalLines": int, # 파일의 총 줄 수

3055 "truncatedByTokenCap": bool | None, # 전체 파일 읽기가 토큰 상한을 초과했을 때 표시되고 True이며 콘텐츠는 첫 페이지입니다

3056 },

3057}

3058```

3059

3060**출력 (type: `"image"`):**

3061

3062```python theme={null}

3063{

3064 "type": "image",

3065 "file": {

3066 "base64": str, # Base64로 인코딩된 이미지 데이터

3067 "type": "image/jpeg" | "image/png" | "image/gif" | "image/webp", # 이미지 MIME 타입

3068 "originalSize": int, # 원본 파일 크기(바이트)

3069 "dimensions": { # 좌표 매핑을 위한 선택적 크기 정보

3070 "originalWidth": int | None, # 선택적; 원본 너비(픽셀)

3071 "originalHeight": int | None, # 선택적; 원본 높이(픽셀)

3072 "displayWidth": int | None, # 선택적; 크기 조정 후 너비

3073 "displayHeight": int | None, # 선택적; 크기 조정 후 높이

3074 } | None,

3075 },

3076}

3077```

3078

3079**출력 (type: `"notebook"`):**

3080

3081```python theme={null}

3082{

3083 "type": "notebook",

3084 "file": {

3085 "filePath": str, # 읽은 노트북

3086 "cells": list, # 노트북 셀

3087 },

3088}

3089```

3090

3091**출력 (type: `"pdf"`):**

3092

3093```python theme={null}

3094{

3095 "type": "pdf",

3096 "file": {

3097 "filePath": str, # 읽은 PDF

3098 "base64": str, # Base64로 인코딩된 PDF 데이터

3099 "originalSize": int, # 파일 크기(바이트)

3100 },

3101}

3102```

3103

3104**출력 (type: `"parts"`):**

2988 3105

2989```python theme={null}3106```python theme={null}

2990{3107{

2991 "content": str, # 줄 번호가 있는 파일 내용3108 "type": "parts",

2992 "total_lines": int, # 파일의 총 줄 수3109 "file": {

2993 "lines_returned": int, # 실제로 반환된 줄3110 "filePath": str, # 읽은 PDF

3111 "originalSize": int, # 파일 크기(바이트)

3112 "count": int, # 이미지로 추출된 페이지 수

3113 "outputDir": str, # 추출된 페이지 이미지를 포함하는 디렉토리

3114 },

3115 "firstPage": int | None, # 선택적 추출된 첫 페이지의 문서 페이지 번호

2994}3116}

2995```3117```

2996 3118

2997**출력 (이미지):**3119**출력 (type: `"file_unchanged"`):**

2998 3120

2999```python theme={null}3121```python theme={null}

3000{3122{

3001 "image": str, # Base64로 인코딩된 이미지 데이터3123 "type": "file_unchanged", # 파일은 Claude가 이 세션에서 마지막으로 읽은 이후 변경되지 않았으므로 콘텐츠가 반복되지 않습니다

3002 "mime_type": str, # 이미지 MIME 타입3124 "file": {

3003 "file_size": int, # 파일 크기(바이트)3125 "filePath": str,

3126 },

3127 "source": "seeded" | None, # 이전 복사본이 시작 시 로드된 CLAUDE.md 또는 메모리 파일에서 나온 경우 표시됨

3004}3128}

3005```3129```

3006 3130

3015```python theme={null}3139```python theme={null}

3016{3140{

3017 "file_path": str, # 쓸 파일의 절대 경로3141 "file_path": str, # 쓸 파일의 절대 경로

3018 "content": str, # 파일에 쓸 내용3142 "content": str, # 파일에 쓸 콘텐츠

3019}3143}

3020```3144```

3021 3145

3023 3147

3024```python theme={null}3148```python theme={null}

3025{3149{

3026 "message": str, # 성공 메시지3150 "type": "create" | "update", # 쓰기가 새 파일을 생성했는지 또는 기존 파일을 덮어썼는지 여부

3027 "bytes_written": int, # 쓴 바이트 수3151 "filePath": str, # 쓴 파일

3028 "file_path": str, # 쓴 파일 경로3152 "content": str, # 쓴 콘텐츠

3153 "structuredPatch": [ # Diff 청크; 새 파일, 아무것도 변경되지 않음, 또는 Claude Code가 diff를 건너뛴 경우 비어 있음

3154 {

3155 "oldStart": int,

3156 "oldLines": int,

3157 "newStart": int,

3158 "newLines": int,

3159 "lines": list[str],

3160 }

3161 ],

3162 "originalFile": str | None, # 이전 콘텐츠; 새 파일이거나 이전 콘텐츠가 너무 클 때 None

3163 "gitDiff": { # 파일에 대한 선택적 git diff 요약

3164 "filename": str,

3165 "status": "modified" | "added",

3166 "additions": int,

3167 "deletions": int,

3168 "changes": int,

3169 "patch": str,

3170 "repository": str | None, # 사용 가능할 때 GitHub owner/repo

3171 } | None,

3172 "userModified": bool | None, # 선택적; 사용자가 수락하기 전에 제안된 콘텐츠를 편집했는지 여부

3029}3173}

3030```3174```

3031 3175

3048 3192

3049```python theme={null}3193```python theme={null}

3050{3194{

3051 "matches": list[str], # 일치하는 파일 경로 배열3195 "durationMs": int, # 검색을 실행하는 데 걸린 시간(밀리초)

3052 "count": int, # 찾은 일치 수3196 "numFiles": int, # 반환된 경로 수, 모든 잘림 후

3053 "search_path": str, # 사용된 검색 디렉토리3197 "filenames": list[str], # 일치하는 파일 경로

3198 "truncated": bool, # 결과가 100파일 제한에서 잘렸는지 여부

3199 "totalMatches": int | None, # 선택적 잘림 전 일치하는 파일의 총 수; countIsComplete가 False일 때 하한

3200 "countIsComplete": bool | None, # 선택적; totalMatches가 정확한지 여부

3054}3201}

3055```3202```

3056 3203

3204`totalMatches`와 `countIsComplete`는 Claude Code v2.1.191 이상이 필요합니다.

3205

3057<h3 id="grep">3206<h3 id="grep">

3058 Grep3207 Grep

3059</h3>3208</h3>

3074 "-B": int | None, # 각 일치 전에 표시할 줄3223 "-B": int | None, # 각 일치 전에 표시할 줄

3075 "-A": int | None, # 각 일치 후에 표시할 줄3224 "-A": int | None, # 각 일치 후에 표시할 줄

3076 "-C": int | None, # 전후에 표시할 줄3225 "-C": int | None, # 전후에 표시할 줄

3226 "context": int | None, # 전후에 표시할 줄; -C는 별칭

3227 "-o": bool | None, # 각 줄의 일치한 부분만 인쇄

3077 "head_limit": int | None, # 출력을 처음 N개 줄/항목으로 제한3228 "head_limit": int | None, # 출력을 처음 N개 줄/항목으로 제한

3229 "offset": int | None, # head_limit을 적용하기 전에 처음 N개 줄/항목 건너뛰기

3078 "multiline": bool | None, # 다중 줄 모드 활성화3230 "multiline": bool | None, # 다중 줄 모드 활성화

3079}3231}

3080```3232```

3081 3233

3082**출력 (content 모드):**3234**출력:**

3083 3235

3084```python theme={null}3236```python theme={null}

3085{3237{

3086 "matches": [3238 "mode": "content" | "files_with_matches" | "count" | None, # 사용된 출력 모드

3087 {3239 "numFiles": int, # 결과의 파일 수; 콘텐츠 모드에서는 항상 0

3088 "file": str,3240 "filenames": list[str], # files_with_matches 모드의 일치하는 파일; 다른 모드에서는 비어 있음

3089 "line_number": int | None,3241 "content": str | None, # 콘텐츠 모드의 일치하는 줄, 또는 count 모드의 파일별 수

3090 "line": str,3242 "numLines": int | None, # 콘텐츠의 줄 수, 콘텐츠 모드에 표시됨

3091 "before_context": list[str] | None,3243 "numMatches": int | None, # 총 일치 수, count 모드에 표시됨

3092 "after_context": list[str] | None,3244 "totalFiles": int | None, # 선택적 head_limit과 offset 전 총 수, files_with_matches 모드

3093 }3245 "totalLines": int | None, # 선택적 head_limit과 offset 전 총 수, 콘텐츠 모드

3094 ],3246 "appliedLimit": int | None, # head_limit이 결과를 잘랐을 때 표시됨

3095 "total_matches": int,3247 "appliedOffset": int | None, # offset이 적용되었을 때 표시됨

3096}3248}

3097```3249```

3098 3250

3099**출력 (files\_with\_matches 모드):**3251Grep은 각 출력 모드에서 이 dict 형태를 반환합니다. 어떤 선택적 키가 표시되는지는 `output_mode`에 따라 다릅니다.

3100 3252

3101```python theme={null}3253`totalFiles`는 Claude Code v2.1.208 이상이 필요합니다. `totalLines`는 Claude Code v2.1.210 이상이 필요합니다.

3102{

3103 "files": list[str], # 일치를 포함하는 파일

3104 "count": int, # 일치를 포함하는 파일 수

3105}

3106```

3107 3254

3108<h3 id="notebookedit">3255<h3 id="notebookedit">

3109 NotebookEdit3256 NotebookEdit

3127 3274

3128```python theme={null}3275```python theme={null}

3129{3276{

3130 "message": str, # 성공 메시지3277 "new_source": str, # 셀에 쓴 소스

3131 "edit_type": "replaced" | "inserted" | "deleted", # 수행된 편집 타입3278 "old_source": str | None, # 이전 셀 소스, replace와 delete에 표시됨

3132 "cell_id": str | None, # 영향을 받은 셀 ID3279 "cell_id": str | None, # 편집된 셀의 ID, 사용 가능할 때

3133 "total_cells": int, # 편집 후 노트북의 총 셀 수3280 "cell_type": "code" | "markdown", # 셀 타입

3281 "language": str, # 노트북의 프로그래밍 언어

3282 "edit_mode": str, # 사용된 편집 모드

3283 "error": str | None, # 작업이 실패했을 때 오류 메시지

3284 "notebook_path": str, # 노트북 파일

3285 "original_file": str, # 편집 전 노트북 콘텐츠

3286 "updated_file": str, # 편집 후 노트북 콘텐츠

3134}3287}

3135```3288```

3136 3289

3228 3381

3229```python theme={null}3382```python theme={null}

3230{3383{

3231 "message": str, # 성공 메시지3384 "oldTodos": [ # 업데이트 전 할 일 목록

3232 "stats": {"total": int, "pending": int, "in_progress": int, "completed": int},3385 {

3386 "content": str,

3387 "status": "pending" | "in_progress" | "completed",

3388 "activeForm": str,

3389 }

3390 ],

3391 "newTodos": [ # 업데이트 후 할 일 목록

3392 {

3393 "content": str,

3394 "status": "pending" | "in_progress" | "completed",

3395 "activeForm": str,

3396 }

3397 ],

3233}3398}

3234```3399```

3235 3400

3401 3566

3402```python theme={null}3567```python theme={null}

3403{3568{

3404 "message": str, # 확인 메시지3569 "plan": str | None, # 사용자에게 제시된 계획

3405 "approved": bool | None, # 사용자가 계획을 승인했는지 여부3570 "isAgent": bool, # 서브에이전트가 도구를 호출했을 때 True

3571 "filePath": str | None, # 계획이 파일에 저장되었을 때 표시됨

3572 "hasTaskTool": bool | None, # 선택적; 현재 컨텍스트에서 Agent 도구를 사용할 수 있는지 여부

3573 "planWasEdited": bool | None, # 사용자가 승인하기 전에 계획을 편집했을 때 표시되고 True

3574 "awaitingLeaderApproval": bool | None, # 팀원이 팀 리더에게 승인을 위해 계획을 보냈을 때 표시되고 True

3575 "requestId": str | None, # 선택적 해당 승인 요청의 ID

3406}3576}

3407```3577```

3408 3578

3420}3590}

3421```3591```

3422 3592

3593결과는 dict가 아닌 list이므로, `tool_use_result`는 이 도구에 대해 `list`를 보유합니다.

3594

3423**출력:**3595**출력:**

3424 3596

3425```python theme={null}3597```python theme={null}

3426{3598[ # 리소스당 하나의 항목

3427 "resources": [

3428 {3599 {

3429 "uri": str,3600 "uri": str, # 리소스 URI

3430 "name": str,3601 "name": str, # 리소스 이름

3431 "description": str | None,3602 "mimeType": str | None, # 선택적 MIME 타입

3432 "mimeType": str | None,3603 "description": str | None, # 선택적 설명

3433 "server": str,3604 "server": str, # 이 리소스를 제공하는 서버

3434 }3605 }

3435 ],3606]

3436 "total": int,

3437}

3438```3607```

3439 3608

3440<h3 id="readmcpresource">3609<h3 id="readmcpresource">

3457```python theme={null}3626```python theme={null}

3458{3627{

3459 "contents": [3628 "contents": [

3460 {"uri": str, "mimeType": str | None, "text": str | None, "blob": str | None}3629 {

3630 "uri": str, # 리소스 URI

3631 "mimeType": str | None, # 선택적 MIME 타입

3632 "text": str | None, # 텍스트 콘텐츠, 또는 바이너리 콘텐츠에 대한 노트

3633 "blobSavedTo": str | None, # Claude Code가 바이너리 콘텐츠를 디스크에 저장했을 때 표시됨; 저장된 파일의 경로

3634 }

3461 ],3635 ],

3462 "server": str,3636 "error": str | None, # 서버가 리소스를 읽을 수 없을 때 표시됨

3463}3637}

3464```3638```

3465 3639

agent-sdk/skills.md +1 −1

Details

271</CodeGroup>271</CodeGroup>

272 272

273<Note>273<Note>

274 `compact_boundary` 메시지는 압축이 실행되었을 때만 도착합니다. 요약할 것이 없으면 `/compact`는 대신 이유를 보고합니다. 실행은 여전히 `success` 결과로 끝나고 `compact_boundary` 메시지가 없으며, 결과 텍스트는 이유를 전달합니다. 예를 들어 짧은 교환 후 `Not enough messages to compact.`입니다. 새로운 원샷 `query()` 호출은 빈 컨텍스트로 시작하므로 이 패턴을 이전 턴이 있는 세션에서 사용하십시오. 예를 들어 [스트리밍 입력 모드](/docs/ko/agent-sdk/streaming-vs-single-mode)에서 또는 세션을 재개할 때입니다.274 `compact_boundary` 메시지는 압축이 실행되었을 때만 도착합니다. 계속된 세션에 메시지가 있지만 `/compact`가 요약할 수 있는 것이 없으면 실행은 여전히 오류 대신 `success` 결과로 끝나고 `compact_boundary` 메시지가 도착하지 않습니다. 그러면 결과 텍스트가 이유를 전달합니다. 예를 들어 세션이 프롬프트를 보유하지만 Claude의 응답이 아직 없을 때 `Not enough messages to compact.`입니다. 새로운 원샷 `query()` 호출은 빈 컨텍스트로 시작하므로 이 패턴을 이전 턴이 있는 세션에서 사용하십시오. 예를 들어 [스트리밍 입력 모드](/docs/ko/agent-sdk/streaming-vs-single-mode)에서 또는 세션을 재개할 때입니다.

275</Note>275</Note>

276 276

277<h3 id="reset-context-with-/clear">277<h3 id="reset-context-with-/clear">

agent-sdk/typescript.md +307 −343

Details

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

607 607

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

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

610</h4>610</h4>

611 611

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

613 613

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

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

627});627});

628```628```

629 629

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

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

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

633 633

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

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

636 636

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

638 638

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

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

641</h3>641</h3>

642 642

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

644 644

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

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

696 696

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

719| `toggleMcpServer(serverName, enabled)` | `reconnectMcpServer()`와 동일한 이름 해결을 사용하여 이름으로 MCP 서버를 활성화 또는 비활성화합니다. 비활성화하면 서버를 연결 해제합니다 |719| `toggleMcpServer(serverName, enabled)` | `reconnectMcpServer()`와 동일한 이름 해결을 사용하여 MCP 서버를 이름으로 활성화 또는 비활성화합니다. stdio, SSE 또는 HTTP 서버를 비활성화하면 연결을 끊고 도구를 제거합니다. 중간 세션에서 `setMcpServers()`로 추가한 서버의 경우 도구 제거에 Claude Code v2.1.285 이상이 필요합니다 |

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

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

725 725

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

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

728</h4>728</h4>

729 729

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

731 731

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

733 733

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

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

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

737 737

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

739 739

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

741 741

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

743 743

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

745 745

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

747 747

748* `effortLevel: null`은 설정 파일의 `effortLevel`이 아닌 모델의 기본 노력 수준으로 세션을 반환합니다. `query()`의 `effort` 옵션도 복원하지 않습니다.748* `effortLevel: null`은 `query()`의 `effort` 옵션이나 설정 파일의 `effortLevel`이 아닌 모델의 기본 노력 수준으로 세션을 반환합니다.

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

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

751 751

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

753 753

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

755 755

758 758

759const q = query({ prompt: messageStream });759const q = query({ prompt: messageStream });

760 760

761// 세션의 나머지 부분에 대해 모델을 재정의합니다761// Override the model for the rest of the session

762await q.applyFlagSettings({ model: "claude-opus-4-6" });762await q.applyFlagSettings({ model: "claude-opus-4-6" });

763 763

764// 나중에: 재정의를 지웁니다. 모델이 Claude Code의 기본값으로 재설정됩니다764// Later: clear the override; the model resets to Claude Code's default

765await q.applyFlagSettings({ model: null });765await q.applyFlagSettings({ model: null });

766```766```

767 767

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

774</h4>774</h4>

775 775

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

777 777

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

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

780 780

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

782 782

783<h3 id="warmquery">783<h3 id="warmquery">

784 `WarmQuery`784 `WarmQuery`

785</h3>785</h3>

786 786

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

788 788

789```typescript theme={null}789```typescript theme={null}

790interface WarmQuery extends AsyncDisposable {790interface WarmQuery extends AsyncDisposable {

800| 메서드 | 설명 |800| 메서드 | 설명 |

801| :- | :- |801| :- | :- |

804 804

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

806 806

808 `SpareProcess`808 `SpareProcess`

809</h3>809</h3>

810 810

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

812 812

813```typescript theme={null}813```typescript theme={null}

814interface SpareProcess extends AsyncDisposable {814interface SpareProcess extends AsyncDisposable {

828 828

829| 멤버 | 설명 |829| 멤버 | 설명 |

830| :- | :- |830| :- | :- |

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

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

835 835

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

837 837

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

839 839

840<h3 id="sdkcontrolinitializeresponse">840<h3 id="sdkcontrolinitializeresponse">

841 `SDKControlInitializeResponse`841 `SDKControlInitializeResponse`

857};857};

858```858```

859 859

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

861 861

862요청이 훅을 전달하지 않으면 Claude Code는 필드를 생략합니다. 요청이 훅을 전달하면 값은 요청이 세션의 첫 번째 초기화인지 여부와 반복된 요청의 경우 세션에 도달한 방식에 따라 달라집니다:862요청이 훅을 전달하지 않으면 Claude Code는 필드를 생략합니다. 요청이 훅을 전달할 때, 값은 요청이 세션의 첫 번째 초기화인지, 반복된 요청의 경우 세션에 도달한 방식에 따라 달라집니다:

863 863

864* `true`: Claude Code가 훅을 등록했습니다. 세션의 첫 번째 초기화는 이 값을 반환합니다. CLI의 stdin을 통해 전송된 반복 초기화도 `true`를 반환합니다. 이 경우 새 요청의 훅이 이전에 등록된 훅을 대체합니다.864* `true`: Claude Code가 훅을 등록했습니다. 세션의 첫 번째 초기화는 이 값을 반환합니다. CLI의 stdin을 통해 전송된 반복 초기화도 `true`를 반환합니다. 이 경우 새 요청의 훅이 이전에 등록된 훅을 대체합니다.

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

866 866

867에이전트 SDK v0.3.238 이전에는 응답이 필드를 전달하지 않았고 Claude Code는 모든 반복 초기화에서 `hooks`를 무시했습니다.867Agent SDK v0.3.238 이전에는 응답이 필드를 전달하지 않았고, Claude Code는 모든 반복 초기화에서 `hooks`를 무시했습니다.

868 868

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

870 870

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

872 872

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

874 874

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

876 876

877<h3 id="sdkcontrolinterruptresponse">877<h3 id="sdkcontrolinterruptresponse">

878 `SDKControlInterruptResponse`878 `SDKControlInterruptResponse`

879</h3>879</h3>

880 880

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

882 882

883```typescript theme={null}883```typescript theme={null}

884type SDKControlInterruptResponse = {884type SDKControlInterruptResponse = {

887};887};

888```888```

889 889

890`still_queued`는 중단이 도착했을 때 대기 중이던 사용자 메시지의 UUID를 나열합니다. 대기열에 여전히 있는 메시지와 Claude Code가 이미 다음 턴을 위해 대기열에서 꺼낸 메시지입니다. 세션의 첫 턴이 시작된 후 Claude Code는 중단하지 않으면 나열된 메시지를 처리하고 여러 메시지를 한 턴으로 병합할 수 있습니다. 첫 턴이 시작되기 전에 중단하면 Claude Code는 시작되는 즉시 해당 턴을 중단하고 해당 턴의 나열된 메시지는 응답을 받지 않습니다.890`still_queued`는 중단이 도착했을 때 대기 중이던 사용자 메시지의 UUID를 나열합니다. 대기열에 여전히 있는 메시지와 Claude Code가 이미 다음 턴을 위해 대기열에서 꺼낸 메시지입니다. 세션의 첫 턴이 시작된 후 Claude Code는 중단하지 않는 한 나열된 메시지를 처리하고 여러 메시지를 하나의 턴으로 병합할 수 있습니다. 첫 턴이 시작되기 전에 중단하면 Claude Code는 시작되는 즉시 해당 턴을 중단하고 해당 턴의 나열된 메시지는 응답을 받지 않습니다.

891 891

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

893 893

894이 주의 사항으로 목록을 해석하세요:894이러한 주의사항으로 목록을 해석합니다:

895 895

896* UUID가 있는 메시지만 나타납니다. 빈 배열은 다른 것도 실행되지 않는다는 의미가 아닙니다.896* UUID로 대기열에 들어간 메시지만 나타납니다. 빈 배열은 다른 것이 실행되지 않음을 의미하지 않습니다.

897* 메인 스레드 메시지만 나열됩니다. 서브에이전트로 주소 지정된 메시지는 범위를 벗어납니다.897* 메인 스레드 메시지만 나열됩니다. 서브에이전트로 주소 지정된 메시지는 범위를 벗어납니다.

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

899 899

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

901 901

902`cancelled` 목록은 `still_queued`와 동일한 주의 사항을 전달합니다. `interrupt()` 메서드는 절대 `cancel_queued`를 보내지 않으므로 해결되는 수신은 `cancelled`를 전달하지 않습니다.902`cancelled` 목록은 `still_queued`와 동일한 주의사항을 전달합니다. `interrupt()` 메서드는 `cancel_queued`를 보내지 않으므로 해결하는 수신은 `cancelled`를 전달하지 않습니다.

903 903

904수신은 중단이 처리되는 순간의 스냅샷이며 깨끗한 중단에서 중단된 턴의 [`SDKResultMessage`](#sdkresultmessage) 전에 도착합니다. 해당 결과 후 수신을 읽으세요. 루프는 즉시 다음 대기 중인 턴을 시작하므로 결과 후 검사하는 대기열이 이미 변경되었습니다.904수신은 중단이 처리되는 순간의 스냅샷이며, 깨끗한 중단에서 중단된 턴의 [`SDKResultMessage`](#sdkresultmessage) 전에 도착합니다. 해당 결과 후 수신을 읽습니다. 루프는 즉시 다음 대기 중인 턴을 시작하므로 결과 후 검사하는 대기열이 이미 변경되었습니다.

905 905

906<h3 id="sdkcontrolgetcontextusageresponse">906<h3 id="sdkcontrolgetcontextusageresponse">

907 `SDKControlGetContextUsageResponse`907 `SDKControlGetContextUsageResponse`

908</h3>908</h3>

909 909

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

911 911

912메서드의 선택적 `detail` 인수는 Claude Code가 각 카테고리를 계산하는 방식을 선택합니다. 기본값 `'full'`을 사용하면 Claude Code는 토큰 계산 API 요청으로 각 카테고리를 계산합니다. 대신 `{ detail: 'summary' }`를 전달하여 마지막 응답의 사용량 및 로컬 추정에서 답변을 가져옵니다. 토큰 계산 요청이 나가지 않으며 카테고리별 숫자는 대략적입니다. `detail` 인수는 에이전트 SDK v0.3.257 이상이 필요합니다.912메서드의 선택적 `detail` 인수는 Claude Code가 각 카테고리를 계산하는 방식을 선택합니다. `detail` 인수는 Agent SDK v0.3.257 이상이 필요합니다.

913 913

914프롬프트 대신 `/context`를 메서드로 보내면 Claude Code는 결과를 전달하는 어시스턴트 메시지의 `context_usage` 필드에 [`SDKContextUsage`](#sdkcontextusage) 페이로드를 첨부합니다. 해당 필드는 에이전트 SDK v0.3.232 이상이 필요합니다.914* **`'full'`**: 기본값입니다. Claude Code는 [토큰 계산](https://platform.claude.com/docs/en/build-with-claude/token-counting) API 요청으로 각 카테고리를 계산합니다. 이러한 요청은 메시지 스트림에 나타나지 않으므로 스트림을 읽는 비용 추적이 이를 보지 못합니다. Anthropic API에서 토큰 계산은 청구되지 않습니다.

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

916

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

915 918

916```typescript theme={null}919```typescript theme={null}

917type SDKControlGetContextUsageResponse = {920type SDKControlGetContextUsageResponse = {

1008};1011};

1009```1012```

1010 1013

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

1012 1015

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

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

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

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

1017 1020

1018`totalTokens`는 세션의 현재 컨텍스트 사용량이고 `maxTokens`는 사용량이 측정되는 창입니다. 해당 창은 모델의 컨텍스트 창이거나 적용되는 낮은 자동 압축 창입니다. `rawMaxTokens`는 `maxTokens`와 동일한 값을 전달하고 `percentage`는 해당 창의 반올림된 백분율로 `totalTokens`입니다.1021`totalTokens`는 세션의 현재 컨텍스트 사용량이고 `maxTokens`는 사용량이 측정되는 창입니다. 해당 창은 모델의 컨텍스트 창이거나 적용되는 경우 더 낮은 자동 압축 창입니다. `rawMaxTokens`는 `maxTokens`와 동일한 값을 전달하고 `percentage`는 해당 창의 반올림된 백분율로 `totalTokens`입니다. `apiUsage`는 세션의 실행 합계가 아닌 최신 API 응답의 사용량을 보유합니다.

1019 1022

1020Claude Code는 선택적 `deferredBuiltinTools`, `systemTools` 및 `systemPromptSections` 진단을 설정하지 않으므로 유형이 선언하더라도 없을 것으로 예상하세요.1023Claude Code는 선택적 `deferredBuiltinTools`, `systemTools` 및 `systemPromptSections` 진단을 설정하지 않으므로 유형이 선언하더라도 없을 것으로 예상합니다.

1021 1024

1022<h3 id="sdkcontrolreadfileresponse">1025<h3 id="sdkcontrolreadfileresponse">

1023 `SDKControlReadFileResponse`1026 `SDKControlReadFileResponse`

1034};1037};

1035```1038```

1036 1039

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

1038 1041

1039<h4 id="what-readfile-can-read">1042<h4 id="what-readfile-can-read">

1040 readFile()이 읽을 수 있는 것1043 readFile()이 읽을 수 있는 것

1043`readFile()`은 Read 도구보다 더 좁은 파일 집합을 제공합니다:1046`readFile()`은 Read 도구보다 더 좁은 파일 집합을 제공합니다:

1044 1047

1045* `cwd` 및 `additionalDirectories` 같은 세션의 작업 디렉토리 중 하나 내의 일반 파일1048* `cwd` 및 `additionalDirectories` 같은 세션의 작업 디렉토리 중 하나 내의 일반 파일

1046* 세션의 도구 결과 같은 Claude Code 자체 파일 중 일부1049* 세션의 도구 결과 같은 Claude Code 자체의 몇 가지 파일

1047 1050

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

1049 1052

1050<h3 id="sdkcontrolreloadpluginsresponse">1053<h3 id="sdkcontrolreloadpluginsresponse">

1051 `SDKControlReloadPluginsResponse`1054 `SDKControlReloadPluginsResponse`

1074};1077};

1075```1078```

1076 1079

1077컬렉션 필드는 호출 후 세션을 설명합니다:1080수집 필드는 호출 후 세션을 설명합니다:

1078 1081

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

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

1081* `error_count`: 플러그인 로드의 오류 수1084* `error_count`: 플러그인 로드의 오류 수

1082 1085

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

1084 1087

1085옵션을 전달하면 `held`를 읽어 발생한 일을 알아보세요:1088옵션을 전달하면 `held`를 읽어 무슨 일이 일어났는지 알아봅니다:

1086 1089

1087* `true`: 다시 로드가 적용되지 않았으며 컬렉션 필드는 여전히 세션을 설명합니다. `cache_impact`는 적용이 변경할 것을 말합니다. 어쨌든 적용하려면 옵션 없이 `reloadPlugins()`를 다시 호출하세요.1090* `true`: 다시 로드가 적용되지 않았고 수집 필드는 여전히 세션을 설명합니다. `cache_impact`는 적용이 변경할 것을 말합니다. 어쨌든 적용하려면 옵션 없이 `reloadPlugins()`를 다시 호출합니다.

1088* `false`: 검사에서 캐시 영향을 찾지 못했으며 다시 로드가 적용되었습니다.1091* `false`: 검사가 캐시 영향을 찾지 못했고 다시 로드가 적용되었습니다.

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

1090 1093

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

1092 1095

1093<h3 id="sdkcontrolreloadskillsresponse">1096<h3 id="sdkcontrolreloadskillsresponse">

1094 `SDKControlReloadSkillsResponse`1097 `SDKControlReloadSkillsResponse`

1102};1105};

1103```1106```

1104 1107

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

1106 1109

1107<h3 id="sdkcontrolreloadoutputstylesresponse">1110<h3 id="sdkcontrolreloadoutputstylesresponse">

1108 `SDKControlReloadOutputStylesResponse`1111 `SDKControlReloadOutputStylesResponse`

1122 `SDKControlMcpReadResourceResponse`1125 `SDKControlMcpReadResourceResponse`

1123</h3>1126</h3>

1124 1127

1125[`readMcpResource()`](#query-object)의 반환 유형으로, MCP 서버의 `resources/read` 결과를 전달합니다. TypeScript 에이전트 SDK v0.3.280 이상이 필요합니다.1128[`readMcpResource()`](#query-object)의 반환 유형으로, MCP 서버의 `resources/read` 결과를 전달합니다. TypeScript Agent SDK v0.3.280 이상이 필요합니다.

1126 1129

1127```typescript theme={null}1130```typescript theme={null}

1128type SDKControlMcpReadResourceResponse = {1131type SDKControlMcpReadResourceResponse = {

1136};1139};

1137```1140```

1138 1141

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

1143

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

1140 1145

1141각 `contents` 항목은 서버가 보낸 하나의 콘텐츠 항목입니다. `com.anthropic/` 접두사 아래의 `_meta` 키는 Claude Code용으로 예약되어 있으므로 제외됩니다. `blob`은 바이너리 항목의 base64 데이터를 보유하고, `_meta`는 항목 자체의 `_meta`이며, MCP Apps 서버는 리소스의 `ui.csp` 및 `ui.permissions`를 여기에 넣습니다. 콘텐츠는 신뢰할 수 없는 제3자 HTML이므로 샌드박스에서 렌더링하세요.1146콘텐츠는 신뢰할 수 없는 제3자 HTML이므로 샌드박스에서 렌더링합니다.

1142 1147

1143<h3 id="agentdefinition">1148<h3 id="agentdefinition">

1144 `AgentDefinition`1149 `AgentDefinition`

1168 1173

1169| 필드 | 필수 | 설명 |1174| 필드 | 필수 | 설명 |

1170| :- | :- | :- |1175| :- | :- | :- |

1171| `description` | 예 | 이 에이전트를 사용할 때를 설명하는 자연어 설명 |1176| `description` | 예 | 이 에이전트를 사용할 때를 설명하는 자연어 |

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

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

1174| `prompt` | 예 | 에이전트의 시스템 프롬프트 |1179| `prompt` | 예 | 에이전트의 시스템 프롬프트 |

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

1176| `mcpServers` | 아니오 | 이 에이전트의 MCP 서버 사양입니다 |1181| `mcpServers` | 아니오 | 이 에이전트의 MCP 서버 사양 |

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

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

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

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

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

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

1183| `effort` | 아니오 | 이 에이전트의 추론 노력 수준입니다. 명명된 수준 또는 정수를 허용합니다 |1188| `effort` | 아니오 | 이 에이전트의 추론 노력 수준입니다. 명명된 수준 또는 정수를 허용합니다 |

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

1185| `criticalSystemReminder_EXPERIMENTAL` | 아니오 | 실험적: 시스템 프롬프트에 추가된 중요 알림 |1190| `criticalSystemReminder_EXPERIMENTAL` | 아니오 | 실험적: 시스템 프롬프트에 추가된 중요 알림 |

1186 1191

1187<h3 id="agentmcpserverspec">1192<h3 id="agentmcpserverspec">

1188 `AgentMcpServerSpec`1193 `AgentMcpServerSpec`

1189</h3>1194</h3>

1190 1195

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

1192 1197

1193```typescript theme={null}1198```typescript theme={null}

1194type AgentMcpServerSpec = string | Record<string, McpServerConfigForProcessTransport>;1199type AgentMcpServerSpec = string | Record<string, McpServerConfigForProcessTransport>;

1200 `SettingSource`1205 `SettingSource`

1201</h3>1206</h3>

1202 1207

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

1204 1209

1205```typescript theme={null}1210```typescript theme={null}

1206type SettingSource = "user" | "project" | "local";1211type SettingSource = "user" | "project" | "local";

1216 기본 동작1221 기본 동작

1217</h4>1222</h4>

1218 1223

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

1220 1225

1221<h4 id="why-use-settingsources">1226<h4 id="why-use-settingsources">

1222 settingSources를 사용하는 이유1227 settingSources를 사용하는 이유

1227```typescript theme={null}1232```typescript theme={null}

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

1229 1234

1230// 디스크에서 사용자, 프로젝트 또는 로컬 설정을 로드하지 마세요1235// Do not load user, project, or local settings from disk

1231const result = query({1236const result = query({

1232 prompt: "Analyze this code",1237 prompt: "Analyze this code",

1233 options: { settingSources: [] }1238 options: { settingSources: [] }

1239```typescript theme={null}1244```typescript theme={null}

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

1241 1246

1242// 프로젝트 설정만 로드, 사용자 및 로컬 무시1247// Load only project settings, ignore user and local

1243const result = query({1248const result = query({

1244 prompt: "Run CI checks",1249 prompt: "Run CI checks",

1245 options: {1250 options: {

1246 settingSources: ["project"] // .claude/settings.json만1251 settingSources: ["project"] // Only .claude/settings.json

1247 }1252 }

1248});1253});

1249```1254```

1250 1255

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

1252 1257

1253<h4 id="settings-precedence">1258<h4 id="settings-precedence">

1254 설정 우선 순위1259 설정 우선순위

1255</h4>1260</h4>

1256 1261

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

1258 1263

12591. 로컬 설정 (`.claude/settings.local.json`)12641. 로컬 설정(`.claude/settings.local.json`)

12602. 프로젝트 설정 (`.claude/settings.json`)12652. 프로젝트 설정(`.claude/settings.json`)

12613. 사용자 설정 (`~/.claude/settings.json`)12663. 사용자 설정(`~/.claude/settings.json`)

1262 1267

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

1264 1269

1272 | "acceptEdits" // 파일 편집 자동 수락1277 | "acceptEdits" // 파일 편집 자동 수락

1273 | "bypassPermissions" // 권한 검사 우회; 명시적 요청 규칙은 여전히 프롬프트1278 | "bypassPermissions" // 권한 검사 우회; 명시적 요청 규칙은 여전히 프롬프트

1274 | "plan" // 계획 모드 - 편집 없이 탐색1279 | "plan" // 계획 모드 - 편집 없이 탐색

1275 | "dontAsk" // 권한에 대해 프롬프트하지 마세요, 사전 승인되지 않으면 거부1280 | "dontAsk" // 권한에 대해 프롬프트하지 않음, 사전 승인되지 않으면 거부

1276 | "auto"; // 모델 분류기가 권한 프롬프트를 승인 또는 거부1281 | "auto"; // 모델 분류자가 셸 명령어 및 네트워크 요청 같은 작업을 검토

1277```1282```

1278 1283

1279<h3 id="canusetool">1284<h3 id="canusetool">

1282 1287

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

1284 1289

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

1286 1291

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

1288 1293

1289```typescript theme={null}1294```typescript theme={null}

1290type CanUseTool = (1295type CanUseTool = (

1308| 옵션 | 유형 | 설명 |1313| 옵션 | 유형 | 설명 |

1309| :- | :- | :- |1314| :- | :- | :- |

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

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

1319| `requestId` | `string` | `control_request` 봉투의 `request_id`입니다. 애플리케이션이 SDK 외부의 자체 채널(예: 서명된 HTTP POST)을 통해 보내는 `control_response`는 이 값을 에코해야 Claude Code 프로세스가 응답을 요청과 일치시킬 수 있습니다 |1324| `requestId` | `string` | `control_request` 봉투의 `request_id`입니다. 애플리케이션이 자신의 채널(예: 서명된 HTTP POST)을 통해 보내는 `control_response`는 이 값을 에코해야 하므로 Claude Code 프로세스가 회신을 요청과 일치시킬 수 있습니다 |

1320 1325

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

1322 1327

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

1324 1329

1360 1365

1361| 필드 | 유형 | 설명 |1366| 필드 | 유형 | 설명 |

1362| :- | :- | :- |1367| :- | :- | :- |

1364 1369

1365<h3 id="mcpserverconfig">1370<h3 id="mcpserverconfig">

1366 `McpServerConfig`1371 `McpServerConfig`

1456| :- | :- | :- |1461| :- | :- | :- |

1460 1465

1461**예제:**1466**예제:**

1462 1467

1549* `'model_not_found'`: 선택한 모델이 존재하지 않거나 계정이나 배포에서 사용할 수 없음1554* `'model_not_found'`: 선택한 모델이 존재하지 않거나 계정이나 배포에서 사용할 수 없음

1550* `'overloaded'`: API가 서버가 용량에 도달했기 때문에 529를 반환했으며, 할당량에 대한 429인 `'rate_limit'`과는 다름1555* `'overloaded'`: API가 서버가 용량에 도달했기 때문에 529를 반환했으며, 할당량에 대한 429인 `'rate_limit'`과는 다름

1551* `'account_on_hold'`: [계정이 보류 중](/docs/ko/errors#your-account-is-on-hold)1556* `'account_on_hold'`: [계정이 보류 중](/docs/ko/errors#your-account-is-on-hold)

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

1553 1558

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

1555 1560

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

1557 1562

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

1559 1564

1560`context_usage`는 `/context` 보고서의 구조화된 복사본이며, [`SDKContextUsage`](#sdkcontextusage)로 입력되고 Agent SDK v0.3.232 이상이 필요합니다. 프롬프트로 `/context`를 보낼 때, Claude Code는 보고서를 어시스턴트 메시지로 전달하며, 그 `message.content`는 마크다운 테이블을 보유하고, 동일한 메시지에 `context_usage`를 첨부합니다. Claude Code는 다른 어시스턴트 메시지에는 필드를 설정하지 않으며, 이전 버전은 `/context` 테이블을 없이 전달하므로, 필드가 있을 때 분석을 읽고 없을 때 마크다운 텍스트로 돌아가세요.1565`context_usage`는 `/context` 보고서의 구조화된 복사본이며, [`SDKContextUsage`](#sdkcontextusage)로 입력되고 Agent SDK v0.3.232 이상이 필요합니다. 프롬프트로 `/context`를 보낼 때, Claude Code는 보고서를 어시스턴트 메시지로 전달하며, 그 `message.content`는 마크다운 테이블을 보유하고, `context_usage`를 동일한 메시지에 첨부합니다. Claude Code는 다른 어시스턴트 메시지에는 필드를 설정하지 않으며, 이전 버전은 `/context` 테이블을 없이 전달하므로, 필드가 있을 때는 분석을 읽고 없을 때는 마크다운 텍스트로 돌아가세요.

1561 1566

1562<h3 id="sdkusermessage">1567<h3 id="sdkusermessage">

1563 `SDKUserMessage`1568 `SDKUserMessage`

1582};1587};

1583```1588```

1584 1589

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

1586 1591

1587`shouldQuery` 또는 `client_composed`를 설정하여 Claude Code가 메시지를 처리하는 방식을 변경합니다:1592Claude Code가 보낸 메시지를 처리하는 방식을 변경하려면 `shouldQuery` 또는 `client_composed`를 설정하세요:

1588 1593

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

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

1591 1596

1592`tool_result` 블록을 전달하는 메시지에서 `tool_use_result`는 모델로 전송된 텍스트가 아니라 도구의 구조화된 출력 객체입니다. 해당 형태는 일치하는 `tool_use` 블록으로 명명된 도구에 따라 다르므로 필드는 `unknown`으로 입력됩니다. 기본 제공 형태는 [도구 출력 타입](#tool-output-types) 아래에 나열되어 있습니다.1597`tool_result` 블록을 전달하는 메시지에서 `tool_use_result`는 모델로 전송된 텍스트가 아니라 도구의 구조화된 출력 객체입니다. 해당 형태는 일치하는 `tool_use` 블록으로 명명된 도구에 따라 다르므로 필드는 `unknown`으로 입력됩니다. 기본 제공 형태는 [도구 출력 타입](#tool-output-types)에 나열되어 있습니다.

1593 1598

1594`Agent` 도구의 경우 `tool_use_result`는 [`AgentOutput`](#agent-2)입니다. `completed` 결과에서 `content`는 Claude Code가 `tool_result` 텍스트에 추가하는 에이전트 ID 및 사용량 트레일러 없이 서브에이전트의 보고서를 보유하므로 해당 텍스트를 구문 분석하는 대신 `tool_use_result`에서 렌더링합니다.1599`Agent` 도구의 경우 `tool_use_result`는 [`AgentOutput`](#agent-2)입니다. `completed` 결과에서 `content`는 Claude Code가 `tool_result` 텍스트에 추가하는 에이전트 ID 및 사용량 트레일러 없이 서브에이전트의 보고서를 보유하므로, 해당 텍스트를 구문 분석하는 대신 `tool_use_result`에서 렌더링하세요.

1595 1600

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

1597 1602

1598사용자가 입력한 것이 아니라 붙여넣은 `message.content`의 부분을 알려주도록 `inline_pastes`를 설정하고, 붙여넣기당 하나의 문자열을 설정합니다. 프롬프트 텍스트는 사용자가 배치한 위치에 유지됩니다. Claude Code는 각 나열된 붙여넣기를 `<pasted_content>` 태그로 감쌀 수 있으므로 Claude는 붙여넣은 자료를 사용자 자신의 단어와 구별할 수 있습니다. 프롬프트의 마지막 텍스트 블록의 붙여넣기만 래핑됩니다. TypeScript Agent SDK v0.3.280 이상이 필요합니다.1603Claude Code에 `message.content`의 어느 부분을 사용자가 붙여넣었는지 알려주려면 `inline_pastes`를 설정하세요. 입력한 것이 아니라 붙여넣은 것이며, 붙여넣기당 하나의 문자열입니다. 프롬프트 텍스트는 사용자가 배치한 위치에 유지됩니다. Claude Code는 각 나열된 붙여넣기를 `<pasted_content>` 태그로 감쌀 수 있으므로 Claude는 붙여넣은 자료를 사용자 자신의 단어와 구별할 수 있습니다. 프롬프트의 마지막 텍스트 블록의 붙여넣기만 감싸집니다. TypeScript Agent SDK v0.3.280 이상이 필요합니다.

1599 1604

1600<h3 id="sdkusermessagereplay">1605<h3 id="sdkusermessagereplay">

1601 `SDKUserMessageReplay`1606 `SDKUserMessageReplay`

1618};1623};

1619```1624```

1620 1625

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

1622 1627

1623<h3 id="sdkresultmessage">1628<h3 id="sdkresultmessage">

1624 `SDKResultMessage`1629 `SDKResultMessage`

1698 1703

1699결과의 여러 필드는 `subtype` 이상의 진단 세부 정보를 전달합니다:1704결과의 여러 필드는 `subtype` 이상의 진단 세부 정보를 전달합니다:

1700 1705

1701* `api_error_status`: 대화를 종료한 API 오류의 HTTP 상태 코드입니다. 턴이 API 오류 없이 끝났을 때 없거나 `null`입니다.1706* `api_error_status`: 대화를 종료한 API 오류의 HTTP 상태 코드입니다. 턴이 API 오류 없이 끝났을 때는 없거나 `null`입니다.

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

1703* `ttft_stream_ms`: 응답 스트림이 열릴 때 첫 번째 `message_start` 스트림 이벤트까지의 밀리초 단위 시간입니다. `ttft_ms`보다 낮습니다. 두 사이의 간격은 첫 번째 메시지를 스트리밍하는 데 소요된 시간입니다. 성공 분기에만 있습니다.1708* `ttft_stream_ms`: 응답 스트림이 열릴 때 첫 번째 `message_start` 스트림 이벤트까지의 밀리초 단위 시간입니다. `ttft_ms`보다 낮습니다. 두 사이의 간격은 첫 번째 메시지를 스트리밍하는 데 소요된 시간입니다. 성공 팔에만 있습니다.

1704* `user_message_uuid`: 이 턴이 답변한 메시지의 `uuid`입니다. 어떤 결과가 이를 전달하는지는 [`user_message_uuid`](#user_message_uuid)를 참조하세요.1709* `user_message_uuid`: 이 턴이 답변한 메시지의 `uuid`입니다. 어느 결과가 이를 전달하는지는 [`user_message_uuid`](#user_message_uuid)를 참조하세요.

1705* `user_message_uuids`: Claude Code가 이 턴에서 답변한 모든 메시지의 `uuid`입니다. [`user_message_uuids`](#user_message_uuids)를 참조하세요.1710* `user_message_uuids`: Claude Code가 이 턴에서 답변한 모든 메시지의 `uuid`입니다. [`user_message_uuids`](#user_message_uuids)를 참조하세요.

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

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

~~1708~~ 1713* `request_sent_wall_ms`: Claude Code가 API 요청을 디스패치한 에포크 밀리초이며, 서버 측 타임스탬프에 대한 조인입니다. [`user_message_uuid`](#user_message_uuid)와 함께만 있으며, `is_error` false인 성공 결과에서 API 요청을 보낸 턴에만 있습니다.

1709`local_command`: 턴이 발송한 명령의 이름으로, `/compact`와 같이 에이전트 루프에 들어가지 않고 명령이 완료된 턴의 성공 결과에서만 있습니다. 이름은 소문자 문자와 밑줄로 접혀 있으므로 `/reload-plugins`는 `reload_plugins`를 보고합니다. MCP 서버가 제공하는 명령과 기본 제공 `/mcp`는 `mcp`를 보고합니다. 자신이 정의한 명령은 `custom`을 보고합니다. 인수는 절대 포함되지 않습니다. 에이전트 루프에 들어간 모든 턴과 명령을 실행하지 않은 전송에서 없습니다. Agent SDK v0.3.268 이상이 필요합니다.1714* `first_content_frame_ms`: 첫 번째 `content_block_start` 또는 `content_block_delta` 스트림 이벤트까지의 밀리초 단위 시간이며, 생각 블록을 콘텐츠로 계산합니다. 성공 팔에만 있으며, `is_error`가 false일 때만 있습니다. Agent SDK v0.3.260 이상이 필요합니다.

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

1711* `request_sent_wall_ms`: Claude Code가 API 요청을 발송한 에포크 밀리초로, 서버 측 타임스탬프와 조인하기 위한 것입니다. [`user_message_uuid`](#user_message_uuid)와 함께만 있으며, `is_error` false인 성공 결과에서 턴이 API 요청을 보냈을 때만 있습니다.1716* `usage`: 메인 에이전트 루프만 해당합니다. 서브에이전트 및 보조 모델 호출을 제외하며, 스트리밍 입력 세션에서는 턴당입니다. 토큰/비용 회계에는 `modelUsage`를 선호하세요.

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

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

1714`first_content_frame_ms`: 첫 번째 `content_block_start` 또는 `content_block_delta` 스트림 이벤트까지의 밀리초 단위 시간으로, 생각 블록을 콘텐츠로 계산합니다. 성공 분기에만 있으며, `is_error`가 false일 때만 있습니다. Agent SDK v0.3.260 이상이 필요합니다.1719* `queued_turn_count`: Claude Code가 결과를 생성했을 때 `origin: { kind: "human" }`으로 보낸 메시지 중 여전히 대기 중인 메시지의 수입니다. `0`과 없는 필드가 무엇을 의미하는지는 [`queued_turn_count`](#queued_turn_count)를 참조하세요.

~~1715~~ 1720* `result_index`: 이 결과가 프로세스가 작성하는 모든 결과에서 0부터 계산하여 실행의 전달 순서에서 어디에 떨어지는지입니다. 두 팔에 모두 있습니다. 쓰기가 실패한 결과도 여전히 번호를 소비하므로 시퀀스의 간격은 결과가 손실되었음을 의미합니다. Agent SDK v0.3.268 이상이 필요합니다.

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

~~1717~~

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

~~1719~~

1720* `usage`: 메인 에이전트 루프만 해당합니다. 서브에이전트 및 보조 모델 호출을 제외하며, 스트리밍 입력 세션에서는 턴당입니다. 토큰/비용 회계를 위해 `modelUsage`를 선호합니다.

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

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

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

1724*

~~1725~~

1726`result_index`: 이 결과가 실행의 전달 순서에서 어디에 떨어지는지로, 프로세스가 작성하는 모든 결과에서 0부터 계산합니다. 양쪽 분기에 있습니다. 쓰기가 실패한 결과도 번호를 소비하므로 시퀀스의 간격은 결과가 손실되었음을 의미합니다. Agent SDK v0.3.268 이상이 필요합니다.

~~1727~~

1728*

~~1729~~

1730`startup_failure_reason`: Claude Code가 시작을 거부한 이유로, 알려진 시작 실패 전에 작성하는 `error_during_execution` 결과에서 확인할 수 있습니다. 값과 어떤 실패가 이를 전달하는지는 [`startup_failure_reason`](#startup_failure_reason)을 참조하세요. Agent SDK v0.3.274 이상이 필요합니다.

~~1731~~

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

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

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

1735 1725

1736이유 코드를 사용하여 자신의 UI에서 빠른 모드가 꺼진 이유를 설명하는 대신 가용성을 다시 도출합니다. 각 코드는 빠른 모드를 차단한 검사의 이름을 지정합니다:1726이유 코드를 사용하여 자신의 UI에서 빠른 모드가 꺼진 이유를 설명하는 대신 가용성을 다시 도출하세요. 각 코드는 빠른 모드를 차단한 검사의 이름을 지정합니다:

1737 1727

1738| 이유 코드 | 의미 |1728| 이유 코드 | 의미 |

1739| - | - |1729| - | - |

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

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

1750 1740

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

1752 1742

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

1754 1744

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

1756 1746

1757필드는 시작 오류와 같이 사용자 턴 전에 내보낸 결과에는 없습니다.1747필드는 시작 오류 같은 사용자 턴 전에 내보낸 결과에는 없습니다.

1758 1748

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

1760 1750

1761<h4 id="user_message_uuid">1751<h4 id="user_message_uuid">

1762 `user_message_uuid`1752 `user_message_uuid`

1763</h4>1753</h4>

1764 1754

1765턴이 답변하는 [`SDKUserMessage`](#sdkusermessage)의 `uuid`로, Claude Code의 회신을 보낸 메시지와 일치시킬 수 있도록 에코됩니다. Claude Code는 메시지에 하나를 설정한 경우에만 `uuid`를 에코합니다. 필드는 `SDKUserMessage`에서 선택 사항이며, `query()`에 전달된 문자열 프롬프트는 없습니다.1755턴이 답변하는 [`SDKUserMessage`](#sdkusermessage)의 `uuid`이며, Claude Code의 회신을 보낸 메시지와 일치시킬 수 있도록 에코됩니다. Claude Code는 메시지에 설정한 경우에만 `uuid`를 에코합니다. 필드는 `SDKUserMessage`에서 선택 사항이며, `query()`에 전달된 문자열 프롬프트는 없습니다.

1766 1756

1767턴이 답변하는 메시지는 턴이 시작된 방식에 따라 다릅니다:1757턴이 답변하는 메시지는 턴이 시작된 방식에 따라 다릅니다:

1768 1758

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

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

~~1771~~ 1761* **Claude Code가 [`CLAUDE_CODE_RESUME_INTERRUPTED_TURN`](/docs/ko/env-vars) 아래에서 중단된 턴을 다시 실행하기 위해 생성하는 프롬프트**: 중단된 턴의 마지막 프롬프트가 보낸 일반 메시지일 때, 턴을 열었는지 또는 Claude Code가 턴 중에 선택했는지 여부에 관계없이, 다시 실행은 처음에 해당 메시지에 답변합니다. [`resume_reason`](#resume_reason)은 중단된 시도의 다시 실행 프레임을 알려줍니다. 마지막 프롬프트가 보낸 일반 메시지가 아닐 때, 다시 실행은 처음에 보낸 메시지에 답변하지 않습니다. Claude Code가 도구 호출 사이에 일반 메시지를 선택하면, 턴은 그 이후로 선택된 메시지에 답변합니다. 중단된 턴의 프롬프트를 에코하려면 Agent SDK v0.3.268 이상이 필요합니다.

1772**`isSynthetic: true`로 보낸 메시지**: 턴은 처음에 해당 메시지에 답변합니다. Claude Code가 도구 호출 사이에 일반 메시지를 선택하면 턴은 그 이후로 선택된 메시지에 답변합니다. 합성 메시지의 `uuid` 에코는 Agent SDK v0.3.265 이상이 필요합니다. 이전 버전은 합성 턴에서 아무것도 에코하지 않습니다.1762* **Claude Code가 자체적으로 생성한 다른 프롬프트**: 턴은 처음에 보낸 메시지에 답변하지 않으며 프레임은 에코를 전달하지 않습니다. Claude Code가 도구 호출 사이에 일반 메시지를 선택하면, 턴은 그 이후로 해당 메시지에 답변합니다. 선택 에코는 Agent SDK v0.3.265 이상이 필요합니다. 이전 버전은 이러한 턴에서 아무것도 에코하지 않습니다.

~~1773~~

1774*

~~1775~~

1776**Claude Code가 [`CLAUDE_CODE_RESUME_INTERRUPTED_TURN`](/docs/ko/env-vars) 아래에서 다시 실행하기 위해 생성하는 프롬프트**: 중단된 턴의 마지막 프롬프트가 보낸 일반 메시지일 때, 턴을 열었는지 또는 Claude Code가 턴 중에 선택했는지 여부에 관계없이 다시 실행은 처음에 해당 메시지에 답변합니다. [`resume_reason`](#resume_reason)은 중단된 시도의 다시 실행 프레임을 말합니다. 마지막 프롬프트가 보낸 일반 메시지가 아닐 때, 다시 실행은 처음에 보낸 메시지에 답변하지 않습니다. Claude Code가 도구 호출 사이에 보낸 일반 메시지를 선택하면 턴은 그 이후로 선택된 메시지에 답변합니다. 중단된 턴의 프롬프트 에코는 Agent SDK v0.3.268 이상이 필요합니다.

~~1777~~

1778*

~~1779~~

1780**Claude Code가 자체 생성한 다른 프롬프트**: 턴은 처음에 보낸 메시지에 답변하지 않으며 프레임은 에코를 전달하지 않습니다. Claude Code가 도구 호출 사이에 보낸 일반 메시지를 선택하면 턴은 그 이후로 해당 메시지에 답변합니다. 픽업 에코는 Agent SDK v0.3.265 이상이 필요합니다. 이전 버전은 이러한 턴에서 아무것도 에코하지 않습니다.

1781 1763

1782Claude Code는 세 가지 종류의 프레임에서 답변된 메시지의 `uuid`를 에코합니다:1764Claude Code는 세 가지 종류의 프레임에서 답변된 메시지의 `uuid`를 에코합니다:

1783 1765

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

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

~~1786~~ 1768* **턴의 모든 [`thinking_tokens`](#sdkthinkingtokensmessage) 프레임**: 턴의 첫 번째 회신을 기다리지 않고 보낸 메시지에 생각 진행을 귀속시킬 수 있습니다. Agent SDK v0.3.260 이상이 필요합니다.

1787**턴의 첫 번째 회신**: 첫 번째 [어시스턴트 메시지](#sdkassistantmessage) 또는 `includePartialMessages`를 사용하면 `event.type`이 `ping`이 아닌 첫 번째 [스트림 이벤트](#sdkpartialassistantmessage)로, 결과가 도착하기 전에 회신을 바인드할 수 있습니다. 턴이 아무것도 스트리밍하지 않으면 Claude Code는 대신 첫 번째 어시스턴트 메시지에 설정합니다. 첫 번째 회신 에코는 Agent SDK v0.3.246 이상이 필요합니다. 턴이 답변하는 메시지가 중간에 변경되면 변경 후 첫 번째 회신이 필드를 전달하며, Agent SDK v0.3.265 이상에서 필요합니다. 이전 버전은 턴당 하나의 회신 프레임에 설정합니다.

~~1788~~

1789*

~~1790~~

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

1792 1769

1793Claude Code는 다음 경우에 필드를 생략합니다:1770Claude Code는 다음 경우에 필드를 생략합니다:

1794 1771

1795* 첫 번째 회신 이외의 회신 프레임1772* 첫 번째 회신 이외의 회신 프레임

1796* 서브에이전트 프레임1773* 서브에이전트 프레임

1797* `uuid`가 있는 메시지에 답변하지 않는 턴: 턴이 하나 없이 보낸 메시지에 답변했거나 Claude Code가 턴을 시작했고 하나가 있는 일반 메시지를 선택하지 않았습니다1774* 보낸 메시지에 답변하지 않거나 `uuid` 없이 보낸 메시지에 답변하는 턴

1798* 보낸 메시지에 답변하지 않는 결과로, 충돌한 워커 프로세스 후 0으로 설정된 결과와 같습니다1775* 충돌한 워커 프로세스 후 0으로 설정된 결과 같은 보낸 메시지에 답변하지 않는 결과

1799 1776

1800<h4 id="user_message_uuids">1777<h4 id="user_message_uuids">

1801 `user_message_uuids`1778 `user_message_uuids`

1802</h4>1779</h4>

1803 1780

1804Claude Code가 이 턴에서 답변한 모든 메시지의 `uuid`입니다. 여러 메시지를 가깝게 보내면 Claude Code는 이를 하나의 턴으로 병합할 수 있으며, `user_message_uuid`는 마지막 메시지만 명명합니다. 병합된 메시지 중 하나에 회신을 일치시키려면 이 목록의 어디든지 해당 메시지의 `uuid`를 찾으세요. Agent SDK v0.3.259 이상이 필요합니다.1781Claude Code가 이 턴에서 답변한 모든 메시지의 `uuid`입니다. 여러 메시지를 가깝게 보낼 때, Claude Code는 이를 하나의 턴으로 병합할 수 있으며, `user_message_uuid`는 마지막 메시지만 명명합니다. 병합된 메시지 중 하나와 회신을 일치시키려면, 이 목록의 어디든 해당 메시지의 `uuid`를 찾으세요. Agent SDK v0.3.259 이상이 필요합니다.

1805 1782

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

1807 1784

1808Claude Code가 턴이 실행되는 동안 보낸 일반 메시지를 선택하면 해당 메시지의 `uuid`를 결과의 목록에 추가합니다.1785Claude Code가 턴이 실행되는 동안 보낸 일반 메시지를 선택할 때, 해당 메시지의 `uuid`를 결과의 목록에 추가합니다.

1809 1786

1810첫 번째 회신 또는 결과가 목록 없이 `user_message_uuid`를 전달하면 이전 Claude Code 버전에서 나온 것이므로 단일 필드로 돌아가세요.1787첫 번째 회신이나 결과가 목록 없이 `user_message_uuid`를 전달할 때, 이전 Claude Code 버전에서 나온 것이므로 단일 필드로 돌아가세요.

1811 1788

1812<h4 id="resume_reason">1789<h4 id="resume_reason">

1813 `resume_reason`1790 `resume_reason`

1814</h4>1791</h4>

1815 1792

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

1817 1794

1818Claude Code는 두 가지 종류의 프레임에 필드를 설정합니다:1795Claude Code는 두 가지 종류의 프레임에 필드를 설정합니다:

1819 1796

1820* **다시 실행의 결과**: 성공 및 오류 분기 모두에서, 결과가 `user_message_uuid`를 전달하는지 여부에 관계없이.1797* **다시 실행의 결과**: 성공 및 오류 팔 모두에서, 결과가 `user_message_uuid`를 전달하는지 여부에 관계없이.

1821* **다시 실행의 회신 프레임**: [`user_message_uuid`](#user_message_uuid)를 전달하는 것들.1798* **다시 실행의 회신 프레임**: [`user_message_uuid`](#user_message_uuid)를 전달하는 것들.

1822 1799

1823값은 `interrupted_turn`과 같이 턴이 다시 실행된 이유를 명명하는 짧은 소문자 토큰입니다. 필드는 다른 모든 턴에는 없습니다.1800값은 `interrupted_turn` 같은 턴이 다시 실행된 이유를 명명하는 짧은 소문자 토큰입니다. 필드는 다른 모든 턴에는 없습니다.

1824 1801

1825<h4 id="queued_turn_count">1802<h4 id="queued_turn_count">

1826 `queued_turn_count`1803 `queued_turn_count`

1827</h4>1804</h4>

1828 1805

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

1830 1807

1831`0`과 없는 필드가 무엇을 의미하는지:1808`0`과 없는 필드가 무엇을 의미하는지:

1832 1809

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

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

1835 1812

1836<h4 id="startup_failure_reason">1813<h4 id="startup_failure_reason">

1837 `startup_failure_reason`1814 `startup_failure_reason`

1838</h4>1815</h4>

1839 1816

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

1841 1818

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

1843 1820

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

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

1846 1823

1847```typescript theme={null}1824```typescript theme={null}

1848type SDKStartupFailureReason =1825type SDKStartupFailureReason =

1849 | "org_pin_api_key_conflict"1826 | "org_pin_api_key_conflict"

1827 | "provider_not_allowed"

1850 | "org_verify_failed"1828 | "org_verify_failed"

1851 | "org_pin_mismatch"1829 | "org_pin_mismatch"

1852 | "managed_settings_invalid"1830 | "managed_settings_invalid"

1868 1846

1869| 값 | 세션을 중지한 것 |1847| 값 | 세션을 중지한 것 |

1870| :- | :- |1848| :- | :- |

1871| `org_pin_api_key_conflict` | 관리 설정이 [첫 번째 당사자 또는 Cloud 게이트웨이 로그인](/docs/ko/authentication#restrict-login-to-your-organization)을 요구하며, Anthropic API 키, 인증 토큰 또는 `apiKeyHelper`가 대신 구성됨 |1849| `org_pin_api_key_conflict` | 관리 설정이 [첫 번째 당사자 또는 Cloud 게이트웨이 로그인](/docs/ko/authentication#restrict-login-to-your-organization)을 요구하며, Anthropic API 키, 인증 토큰, 또는 `apiKeyHelper`가 대신 구성됨 |

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

1874| `managed_settings_invalid` | 관리 정책 설정을 읽을 수 없거나 핀이 조직을 명명하지 않음 또는 [관리 모델 제한](/docs/ko/errors#managed-settings-block-the-default-model)이 기본 옵션에 대해 허용된 모델을 남기지 않음 |1853| `managed_settings_invalid` | 관리 정책 설정을 읽을 수 없음, 핀이 조직을 명명하지 않음, 또는 [관리 모델 제한](/docs/ko/errors#managed-settings-block-the-default-model)이 기본 옵션에 대해 허용된 모델을 남기지 않음 |

1877| `gateway_access_denied` | Cloud 게이트웨이에 대한 관리 설정 요청이 403으로 돌아왔으며, 게이트웨이의 [문제 해결 테이블](/docs/ko/claude-apps-gateway-deploy#troubleshooting)이 이를 다룹니다 |1856| `gateway_access_denied` | Cloud 게이트웨이에 대한 관리 설정 요청이 403으로 돌아옴(게이트웨이의 [문제 해결 테이블](/docs/ko/claude-apps-gateway-deploy#troubleshooting)이 다룸) |

1887 1866

1928};1907};

1929```1908```

1930 1909

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

~~1932~~

1933`terminal_slash_commands`는 `exit`와 같은 로컬 터미널에 바인드된 인터페이스를 가진 `slash_commands`의 항목을 명명합니다. 다른 `slash_commands` 항목처럼 보낼 수 있습니다. 필드는 원격 또는 모바일 클라이언트가 명령 메뉴에서 이를 숨길 수 있도록 존재합니다. 필드는 비어 있지 않을 때만 있으며 Agent SDK v0.3.229 이상이 필요합니다.

1934 1911

1935* 각 `mcp_servers` 항목의 `source`: 서버 정의가 어디에서 나왔는지로, [`McpServerStatus`](#mcpserverstatus)의 `source`와 동일한 값입니다. Agent SDK v0.3.274 이상이 필요합니다.1912`terminal_slash_commands`는 `slash_commands`의 항목 중 인터페이스가 로컬 터미널에 바인딩된 것들의 이름을 지정합니다(예: `exit`). 다른 `slash_commands` 항목처럼 보낼 수 있습니다. 필드는 원격 또는 모바일 클라이언트가 명령 메뉴에서 이를 숨길 수 있도록 존재합니다. 필드는 비어 있지 않을 때만 있으며, Agent SDK v0.3.229 이상이 필요합니다.

1936*

1937 1913

1938`effort`: [노력 수준](/docs/ko/model-config#adjust-effort-level) Claude Code가 세션의 다음 요청에서 보내거나 보내지 않을 때 `null`입니다. Claude Code는 [Remote Control](/docs/ko/remote-control) 클라이언트로 보내는 초기화 메시지에만 필드를 설정하고 애플리케이션이 읽는 초기화 메시지에서 생략합니다. Agent SDK v0.3.234 이상이 필요합니다.1914* 각 `mcp_servers` 항목의 `source`: 서버의 정의가 어디에서 나왔는지이며, [`McpServerStatus`](#mcpserverstatus)의 `source`와 동일한 값입니다. Agent SDK v0.3.274 이상이 필요합니다.

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

1939 1916

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

1941 1918

1942| 기능 | 의미 |1919| 기능 | 의미 |

1943| - | - |1920| - | - |

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

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

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

1947 1923

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

1949 1925

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

1951 1927

1952아래 테이블은 각 `plugin_errors` 항목의 필드를 나열합니다.1928아래 테이블은 각 `plugin_errors` 항목의 필드를 나열합니다.

1953 1929

1954| 필드 | 타입 | 설명 |1930| 필드 | 타입 | 설명 |

1955| - | - | - |1931| - | - | - |

1960 1936

1961<h3 id="sdkpartialassistantmessage">1937<h3 id="sdkpartialassistantmessage">

1962 `SDKPartialAssistantMessage`1938 `SDKPartialAssistantMessage`

1963</h3>1939</h3>

1964 1940

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

1966 1942

1967```typescript theme={null}1943```typescript theme={null}

1968type SDKPartialAssistantMessage = {1944type SDKPartialAssistantMessage = {

1978};1954};

1979```1955```

1980 1956

1981Claude Code는 턴의 첫 번째 비핑 스트림 이벤트에 `user_message_uuid`와 `user_message_uuids`를 설정하고, 턴이 답변하는 메시지가 변경될 때 [`user_message_uuid`](#user_message_uuid)의 조건에 따라 다시 설정합니다. Claude Code가 재시작으로 인해 중단된 턴을 다시 실행할 때, 다시 실행의 스트림 이벤트가 이러한 필드를 전달하면 [`resume_reason`](#resume_reason)도 전달합니다.1957Claude Code는 [`user_message_uuid`](#user_message_uuid)의 조건에 따라 턴의 첫 번째 비핑 스트림 이벤트에 `user_message_uuid`와 `user_message_uuids`를 설정하며, 턴이 답변하는 메시지가 변경될 때 다시 설정합니다. Claude Code가 재시작으로 중단된 턴을 다시 실행할 때, 이러한 필드를 전달하는 다시 실행된 스트림 이벤트도 [`resume_reason`](#resume_reason)을 전달합니다.

1982 1958

1983<h3 id="sdkcompactboundarymessage">1959<h3 id="sdkcompactboundarymessage">

1984 `SDKCompactBoundaryMessage`1960 `SDKCompactBoundaryMessage`

2003 `SDKInformationalMessage`1979 `SDKInformationalMessage`

2004</h3>1980</h3>

2005 1981

2006루프에서 내보낸 일반 텍스트 배너입니다. 비오류 상태 줄, `UserPromptSubmit` 훅의 블록 이유와 같은 훅 피드백, 명령 출력을 전달합니다. Claude Code v2.1.227 이상에서 훅의 [`systemMessage`](/docs/ko/hooks#json-output)는 이 메시지로 도착할 수 있으며, 각 줄은 `PostToolUse:Bash says:`와 같은 훅의 이름으로 접두사가 붙습니다. 각 [이벤트의 섹션](/docs/ko/hooks#hook-events)은 훅 페이지에서 출력이 어떻게 표시되는지 말합니다. `content`를 주어진 `level`에서 일반 텍스트로 렌더링합니다.1982루프에서 내보낸 일반 텍스트 배너입니다. Claude Code가 발생시키는 경고, 공지, 기타 비오류 상태 줄과 `UserPromptSubmit` 훅의 블록 이유 같은 훅 피드백을 전달합니다.

1983

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

1985

1986`content`를 주어진 `level`에서 평문으로 렌더링하세요.

2007 1987

2008```typescript theme={null}1988```typescript theme={null}

2009type SDKInformationalMessage = {1989type SDKInformationalMessage = {

2022 `SDKWorkerShuttingDownMessage`2002 `SDKWorkerShuttingDownMessage`

2023</h3>2003</h3>

2024 2004

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

2026 2006

2027```typescript theme={null}2007```typescript theme={null}

2028type SDKWorkerShuttingDownMessage = {2008type SDKWorkerShuttingDownMessage = {

2038 `SDKPluginInstallMessage`2018 `SDKPluginInstallMessage`

2039</h3>2019</h3>

2040 2020

2041플러그인 설치 진행 이벤트입니다. [`CLAUDE_CODE_SYNC_PLUGIN_INSTALL`](/docs/ko/env-vars)이 설정되었을 때 내보내져서 Agent SDK 애플리케이션이 첫 번째 턴 전에 마켓플레이스 플러그인 설치를 추적할 수 있습니다. `started`와 `completed` 상태는 전체 설치를 괄호로 묶습니다. `installed`와 `failed` 상태는 개별 마켓플레이스를 보고하고 `name`을 포함합니다.2021플러그인 설치 진행 이벤트입니다. [`CLAUDE_CODE_SYNC_PLUGIN_INSTALL`](/docs/ko/env-vars)이 설정되었을 때 내보내지므로 Agent SDK 애플리케이션이 첫 번째 턴 전에 마켓플레이스 플러그인 설치를 추적할 수 있습니다. `started`와 `completed` 상태는 전체 설치를 괄호로 묶습니다. `installed`와 `failed` 상태는 개별 마켓플레이스를 보고하며 `name`을 포함합니다.

2042 2022

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

2044type SDKPluginInstallMessage = {2024type SDKPluginInstallMessage = {

2056 `SDKPermissionDeniedMessage`2036 `SDKPermissionDeniedMessage`

2057</h3>2037</h3>

2058 2038

2059권한 시스템이 대화형 프롬프트 없이 도구 호출을 거부할 때 내보낸 스트림 이벤트입니다. 뒤따르는 `is_error` 도구 결과만 관찰하는 대신 거부를 실시간으로 UI에 렌더링하는 데 사용합니다. 어떤 거부를 보고하는지는 실행이 권한 프롬프트를 처리하는 방식에 따라 다릅니다:2039권한 시스템이 대화형 프롬프트 없이 도구 호출을 거부할 때 내보낸 스트림 이벤트입니다. 이를 사용하여 거부를 UI에서 렌더링하세요. 이는 뒤따르는 `is_error` 도구 결과만 관찰하는 것이 아니라 발생할 때입니다. 어느 거부를 보고하는지는 실행이 권한 프롬프트를 처리하는 방식에 따라 다릅니다:

2060 2040

2061* **[`canUseTool`](#canusetool) 콜백과 기본 [`permissionPrompts: 'host'`](#options)**: 권한 프롬프트는 콜백으로 이동하고, 이 이벤트는 Claude Code가 이를 호출하지 않고 자체적으로 결정한 거부를 보고합니다.2041* **[`canUseTool`](#canusetool) 콜백과 기본 [`permissionPrompts: 'host'`](#options)**: 권한 프롬프트는 콜백으로 가며, 이 이벤트는 Claude Code가 호출 없이 자체적으로 결정한 거부를 보고합니다.

2062* **둘 다 없음**: 베어 `-p` 실행 또는 `canUseTool`도 `permissionPromptToolName`도 설정하지 않는 `query()`는 프롬프트했을 모든 도구 호출을 거부하고, 이 이벤트는 그러한 거부와 Claude Code가 자체적으로 결정한 거부를 보고합니다. v2.1.223 이전에는 Claude Code가 콜백 없는 실행에서 이 이벤트를 내보내지 않았습니다.2042* **둘 다 없음**: 베어 `-p` 실행 또는 `canUseTool`도 `permissionPromptToolName`도 설정하지 않는 `query()`, 프롬프트했을 도구 호출을 거부하며, 이 이벤트는 이러한 거부와 Claude Code가 자체적으로 결정한 거부를 보고합니다. v2.1.223 이전에는 Claude Code가 콜백 없는 실행에서 이 이벤트를 내보내지 않았습니다.

2063* **MCP 프롬프트 도구**, `permissionPromptToolName` 또는 [`--permission-prompt-tool`](/docs/ko/cli-reference#cli-flags) 플래그로 설정하고 기본 `permissionPrompts: 'host'`: Claude Code는 이 이벤트를 전혀 내보내지 않으며, 규칙 거부를 포함하여 자체적으로 결정한 거부도 포함하지 않습니다.2043* **MCP 프롬프트 도구**(기본 `permissionPrompts: 'host'`와 함께 `permissionPromptToolName` 또는 [`--permission-prompt-tool`](/docs/ko/cli-reference#cli-flags) 플래그로 설정): Claude Code는 이 이벤트를 전혀 내보내지 않으며, 규칙 거부도 자체적으로 결정한 것도 아닙니다.

2064* **[`permissionPrompts: 'none'`](#options)**: Claude Code는 프롬프트했을 호출을 거부하며, `canUseTool` 또는 MCP 프롬프트 도구도 설정되어 있을 때도 거부하고, 이 이벤트는 그러한 거부와 Claude Code가 자체적으로 결정한 거부를 보고합니다. Claude Code v2.1.259 이상이 필요합니다.2044* **[`permissionPrompts: 'none'`](#options)**: Claude Code는 프롬프트했을 호출을 거부하며, `canUseTool` 또는 MCP 프롬프트 도구도 설정되었을 때도 마찬가지이며, 이 이벤트는 이러한 거부와 Claude Code가 자체적으로 결정한 거부를 보고합니다. Claude Code v2.1.259 이상이 필요합니다.

2065 2045

2066모든 구성에서 이 이벤트는 `PreToolUse` 훅 경로에서 결정된 거부를 건너뜁니다. 훅이 호출을 거부했는지 또는 거부 규칙이 훅의 허용 또는 요청 결정을 재정의했는지 여부입니다. 이벤트는 또한 최선의 노력입니다: 때때로 Claude Code는 이 이벤트를 내보내지 않고 거부를 기록하므로 [결과 메시지](#sdkresultmessage)의 `permission_denials`이 권위 있는 기록입니다.2046모든 구성에서 이 이벤트는 `PreToolUse` 훅 경로에서 결정된 거부를 건너뜁니다. 훅이 호출을 거부했는지 또는 거부 규칙이 훅의 허용 또는 요청 결정을 재정의했는지 여부에 관계없이. 이벤트는 또한 최선의 노력입니다: 가끔 Claude Code는 이 이벤트를 내보내지 않고 거부를 기록하므로 [결과 메시지](#sdkresultmessage)의 `permission_denials`이 권위 있는 기록입니다.

2067 2047

2068```typescript theme={null}2048```typescript theme={null}

2069type SDKPermissionDeniedMessage = {2049type SDKPermissionDeniedMessage = {

2084| - | - | - |2064| - | - | - |

2091 2071

2092<h3 id="sdkpermissiondenial">2072<h3 id="sdkpermissiondenial">

2107 `SDKContextUsage`2087 `SDKContextUsage`

2108</h3>2088</h3>

2109 2089

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

2111 2091

2112```typescript theme={null}2092```typescript theme={null}

2113type SDKContextUsage = {2093type SDKContextUsage = {

2144};2124};

2145```2125```

2146 2126

2147테이블은 Claude Code가 각 필드에 넣는 것을 나열합니다. `model`에서 `over_limit`까지의 필드는 세션 전체를 설명하고, 수집 필드는 개별 항목에 토큰을 귀속시킵니다.2127테이블은 Claude Code가 각 필드에 넣는 것을 나열합니다. `model`에서 `over_limit`까지의 필드는 세션 전체를 설명하며, 수집 필드는 개별 항목에 토큰을 귀속시킵니다.

2148 2128

2149| 필드 | 타입 | 설명 |2129| 필드 | 타입 | 설명 |

2150| - | - | - |2130| - | - | - |

2153| `raw_max_tokens` | `number` | 모델의 컨텍스트 윈도우 또는 적용되는 낮은 [자동 압축 윈도우](/docs/ko/model-config#context-window-and-auto-compaction)로, 설정한 것 또는 1M 토큰 윈도우를 가진 일부 모델에 Claude Code가 적용하는 200K 경계와 같습니다. Claude Code는 이 윈도우에 대해 `total_tokens`를 측정합니다 |2133| `raw_max_tokens` | `number` | 모델의 컨텍스트 윈도우 또는 적용되는 낮은 [자동 압축 윈도우](/docs/ko/model-config#context-window-and-auto-compaction)(예: 설정한 것 또는 1M 토큰 윈도우가 있는 일부 모델에 Claude Code가 적용하는 200K 경계). Claude Code는 `total_tokens`를 이 윈도우에 대해 측정 |

2161 2141

2162`over_limit.kind`는 Claude Code가 윈도우를 해결한 방식을 기록하며, 다음 요청을 API가 수락하는지 여부가 아닙니다:2142`over_limit.kind`는 Claude Code가 윈도우를 해결한 방식을 기록하며, 다음 요청을 API가 수락하는지 여부가 아닙니다:

2163 2143

2164* `hard_limit`: 윈도우는 Claude Code가 API가 요청을 거부하는 모델 자체의 제한이라고 믿는 것입니다2144* `hard_limit`: 윈도우는 Claude Code가 모델 자신의 제한이라고 믿는 것이며, 그 이상으로 API가 요청을 거부함

2165* `compaction_window`: 윈도우는 압축 정책 윈도우로, 모델의 제한과 일치할 수도 있고 아닐 수도 있습니다2145* `compaction_window`: 윈도우는 압축 정책 윈도우이며, 모델의 제한과 일치할 수도 있고 아닐 수도 있음

2166 2146

2167Claude Code는 타입을 추가적으로 진화시켜 기존 타입을 재구성하는 대신 새로운 데이터를 선택적 필드로 추가합니다. 알고 있는 필드를 읽고 인식하지 못하는 필드는 무시합니다.2147Claude Code는 기존 것을 재구성하는 대신 선택적 필드로 새 데이터를 추가하여 타입을 점진적으로 발전시킵니다. 알고 있는 필드를 읽고 인식하지 못하는 것은 무시하세요.

2168 2148

2169<h3 id="sdkcontextusagecategory">2149<h3 id="sdkcontextusagecategory">

2170 `SDKContextUsageCategory`2150 `SDKContextUsageCategory`

2171</h3>2151</h3>

2172 2152

2173`/context` 사용량별 카테고리 분석의 한 행입니다.2153`/context` 사용량별 범주 분석의 한 행입니다.

2174 2154

2175```typescript theme={null}2155```typescript theme={null}

2176type SDKContextUsageCategory = {2156type SDKContextUsageCategory = {

2180};2160};

2181```2161```

2182 2162

2183테이블은 Claude Code가 행의 각 필드에 넣는 것을 나열합니다.2163테이블은 행의 각 필드에 Claude Code가 넣는 것을 나열합니다.

2184 2164

2185| 필드 | 타입 | 설명 |2165| 필드 | 타입 | 설명 |

2186| - | - | - |2166| - | - | - |

2190 2170

2191각 `kind` 값은 행의 토큰이 무엇인지 말합니다:2171각 `kind` 값은 행의 토큰이 무엇인지 말합니다:

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

2194* `free`: 남은 윈도우2174* `free`: 남은 윈도우

2195* `buffer`: 압축 예약2175* `buffer`: 압축 예약

2196* `deferred`: Claude Code가 윈도우 밖에 보유하고 사용량 계산에서 제외하지만 인식을 위해 나열하는 도구 스키마2176* `deferred`: Claude Code가 윈도우 밖에 보유하고 사용량 계산에서 제외하는 도구 스키마이며, 인식을 위해 나열됨

2197 2177

2198<h3 id="sdkmessageorigin">2178<h3 id="sdkmessageorigin">

2199 `SDKMessageOrigin`2179 `SDKMessageOrigin`

2200</h3>2180</h3>

2201 2181

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

2203 2183

2204```typescript theme={null}2184```typescript theme={null}

2205type SDKMessageOrigin =2185type SDKMessageOrigin =

2227 2207

2228| `kind` | 의미 |2208| `kind` | 의미 |

2229| - | - |2209| - | - |

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

2232| `peer` | 다른 에이전트의 메시지: 프로세스 내 [팀원](/docs/ko/agent-teams) 또는 [교차 세션 피어](/docs/ko/cross-session-messaging), 다른 Claude Code 세션입니다. [피어 원점 필드](#peer-origin-fields)에서 필드별 의미와 신뢰 모델을 참조하세요. |2212| `peer` | 다른 에이전트의 메시지: 프로세스 내 [팀원](/docs/ko/agent-teams) 또는 [교차 세션 피어](/docs/ko/cross-session-messaging), 다른 Claude Code 세션. [피어 원점 필드](#peer-origin-fields)에서 필드별 의미와 신뢰 모델을 참조하세요. |

2233| `task-notification` | 완료된 백그라운드 작업과 같이 신선한 사용자 프롬프트 없이 도착하는 전달을 위해 주입된 합성 턴입니다. [`SDKTaskNotificationMessage`](#sdktasknotificationmessage)를 참조하세요. 애플리케이션이 [예약된 실행으로 선언](#declare-a-scheduled-run)하는 프롬프트도 이 종류를 전달합니다. 선택적 `subkind`는 알림을 발생시킨 것을 표시합니다. [작업 알림 서브종류](#task-notification-subkinds)를 참조하세요. |2213| `task-notification` | 신선한 사용자 프롬프트 없이 도착하는 전달(예: 완료된 배경 작업)을 위해 주입된 합성 턴. [`SDKTaskNotificationMessage`](#sdktasknotificationmessage)에서 해당 팔을 참조하세요. 애플리케이션이 [예약된 실행으로 선언](#declare-a-scheduled-run)하는 프롬프트도 이 종류를 전달합니다. 선택적 `subkind`는 알림을 발생시킨 것을 표시합니다. [작업 알림 서브종류](#task-notification-subkinds)를 참조하세요. |

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

2237 2217

2238<h3 id="task-notification-subkinds">2218<h3 id="task-notification-subkinds">

2239 작업 알림 서브종류2219 작업 알림 서브종류

2240</h3>2220</h3>

2241 2221

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

2243 2223

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

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

2246 2226

2247`peer-send-message`: 알림은 [교차 세션 `SendMessage` 도구](/docs/ko/cross-session-messaging)가 아니라 [클라우드 세션](/docs/ko/claude-code-on-the-web)이 서로 메시지를 보내는 데 사용하는 서버 측 `send_message` 도구로 다른 세션이 보낸 메시지이며, Anthropic 서버가 두 세션이 동일한 비공개 세션 그룹에 속한다고 확인했습니다. Claude Code v2.1.224 이상이 필요합니다. 서버가 그런 식으로 확인하지 않은 `send_message` 전달은 `subkind`를 얻지 못합니다.2227다른 모든 작업 알림에는 `subkind`가 없습니다. 여기에는 [PR 활동](/docs/ko/claude-code-on-the-web#how-claude-responds-to-pr-activity)이 세션에 전달되고 완료된 작업 같은 배경 이벤트가 포함됩니다. [교차 세션 `SendMessage` 도구](/docs/ko/cross-session-messaging)의 메시지는 작업 알림이 아닙니다: 동일한 머신의 세션에서 오든 다른 머신의 Anthropic 서버를 통해 오든, Claude Code는 이들에게 `kind: "peer"`를 제공하고 [피어 원점 필드](#peer-origin-fields)를 제공합니다.

2248 2228

2249다른 모든 작업 알림에는 `subkind`가 없습니다. 여기에는 [PR 활동](/docs/ko/claude-code-on-the-web#how-claude-responds-to-pr-activity)이 세션에 전달되고 완료된 작업과 같은 백그라운드 이벤트가 포함됩니다. [교차 세션 `SendMessage` 도구](/docs/ko/cross-session-messaging)의 메시지는 작업 알림이 아닙니다: 동일한 머신의 세션에서 오든 다른 머신의 Anthropic 서버를 통해 오든 Claude Code는 `kind: "peer"`를 제공하고 [피어 원점 필드](#peer-origin-fields)를 제공합니다.2229`fireReason`은 `scheduled-trigger` 알림이 발생한 이유를 `scheduled`, `manual`, `retry`, `catch_up`, 또는 `api` 같은 짧은 소문자 토큰으로 말합니다. Anthropic 서버는 [루틴](/docs/ko/routines)의 전달에 설정하며, 애플리케이션은 예약된 실행을 선언할 때 설정합니다. 어느 것도 보내지 않았을 때는 없습니다. TypeScript Agent SDK v0.3.280 이상이 필요합니다.

~~2250~~

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

2252 2230

2253<h4 id="declare-a-scheduled-run">2231<h4 id="declare-a-scheduled-run">

2254 예약된 실행 선언2232 예약된 실행 선언

2255</h4>2233</h4>

2256 2234

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

2258 2236

2259<h3 id="peer-origin-fields">2237<h3 id="peer-origin-fields">

2260 피어 원점 필드2238 피어 원점 필드

2261</h3>2239</h3>

2262 2240

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

~~2264~~

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

2266*

~~2267~~

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

~~2269~~

2270* `senderTaskId`: 팀원의 작업 ID입니다. 교차 세션 피어의 경우 없습니다.

2271*

~~2272~~

2273`name`: 발신자의 표시 이름으로, Claude Code에서 정규화됩니다: Unicode 제어, 형식, 대리, 줄 또는 단락 구분 기호 코드 포인트를 제거한 다음 결과를 자르고 64개 코드 포인트로 제한하고 줄임표를 추가합니다. Claude Code v2.1.205 이상이 필요합니다.

~~2274~~

2275*

~~2276~~

2277`body`: 피어 봉투가 제거된 디코딩된 메시지 본문로, 모델이 보는 것과 바이트 정확합니다. 팀원 메시지의 경우 항상 있습니다. 교차 세션 피어의 경우 턴이 정확히 Claude Code에서 형성한 하나의 피어 봉투일 때만 있습니다. 메시지 텍스트를 다시 구문 분석하는 대신 `name`과 `body`를 렌더링합니다. Claude Code v2.1.205 이상이 필요합니다.

~~2278~~

2279*

~~2280~~

2281`fromSession`: 발신자의 호스트 열기 가능 세션 ID로, 발신자의 호스트에서 설정하여 UI가 발신 세션으로 다시 링크할 수 있습니다. `from`과 마찬가지로 발신자가 주장한 것입니다: 네비게이션 대상으로만 사용하고 발신자의 신원 증명으로 취급하지 마세요. Claude Code v2.1.216 이상이 필요합니다.

~~2282~~

2283*

2284 2242

2285`verifiedPeerPid`: 이 세션의 교차 세션 메시징 소켓에 연결된 프로세스의 프로세스 ID로, 커널에서 확인하고 페이로드가 아닌 연결 자체에서 읽습니다. 발신자를 식별하려면 `from`이 아니라 이를 사용합니다: `from`은 동일한 사용자 프로세스에서 위조 가능합니다. 필드는 Claude Code가 확인할 수 없을 때 없으며, 예를 들어 Windows 또는 비소켓 수신에서 없으므로 없는 값은 발신자가 확인되지 않음을 의미합니다. 중계된 트래픽의 경우 메시지의 작성자가 아니라 중계를 식별하고 프로세스 ID는 재활용 가능하므로 인증 토큰이 아니라 출처로 취급합니다. Claude Code v2.1.216 이상이 필요합니다.2243* `from`: 팀원의 이름 또는 교차 세션 피어의 발신자 주소. [일방향 교차 머신 메시지](/docs/ko/cross-session-messaging#message-sessions-on-other-machines)의 경우, 발신자는 회신 주소가 없으며 `from`은 `"unknown"`입니다. 값은 발신자가 작성한 것입니다. `verifiedPeerPid`는 확인된 신원입니다.

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

2245* `senderTaskId`: 팀원의 작업 ID. 교차 세션 피어에는 없습니다.

2246* `name`: 발신자의 표시 이름이며, Claude Code에서 정규화됩니다: Unicode 제어, 형식, 대리, 줄 또는 단락 구분자 코드 포인트를 제거한 다음 결과를 자르고 64개 코드 포인트로 제한하며 줄임표를 추가합니다. Claude Code v2.1.205 이상이 필요합니다.

2247* `body`: 피어 봉투가 제거된 디코딩된 메시지 본문이며, 모델이 보는 것과 바이트 정확합니다. 팀원 메시지에는 항상 있습니다. 교차 세션 피어의 경우, 턴이 정확히 Claude Code에서 형성한 하나의 피어 봉투일 때만 있습니다. 메시지 텍스트를 다시 구문 분석하는 대신 `name`과 `body`를 렌더링하세요. Claude Code v2.1.205 이상이 필요합니다.

2248* `fromSession`: 발신자의 호스트 열기 가능 세션 ID이며, 발신자의 호스트에서 설정되므로 UI가 발신 세션으로 다시 링크할 수 있습니다. `from`처럼, 발신자가 주장한 것입니다: 발신자의 신원 증명으로 취급하지 말고 네비게이션 대상으로만 사용하세요. Claude Code v2.1.216 이상이 필요합니다.

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

2286 2250

2287<h2 id="hook-types">2251<h2 id="hook-types">

2288 훅 타입2252 훅 타입

3222};3186};

3223```3187```

3224 3188

3225선택적 타임아웃 및 백그라운드 실행을 포함한 Bash 명령을 실행합니다. 작업 디렉터리는 다중 턴 세션의 이후 턴에서 실행되는 명령을 포함하여 명령 간에 유지됩니다. 내보낸 환경 변수와 같은 셸 상태는 유지되지 않습니다. 어느 디렉터리 변경이 유지되는지에 대한 제한 사항은 [명령 간에 유지되는 것](/docs/ko/tools-reference#what-persists-between-commands)을 참조하세요. 포그라운드 상한을 설정하는 것에 대해서는 [타임아웃 및 출력 제한](/docs/ko/tools-reference#timeout-and-output-limits)을 참조하세요. 백그라운드 시간 제한에 대해서는 [백그라운드 명령](/docs/ko/tools-reference#background-commands)을 참조하세요.3189선택적 타임아웃 및 백그라운드 실행을 포함한 Bash 명령을 실행합니다. 작업 디렉터리는 다중 턴 세션의 이후 턴에서 실행되는 명령을 포함하여 명령 간에 유지됩니다. 내보낸 환경 변수와 같은 셸 상태는 유지되지 않습니다. 어느 디렉터리 변경이 유지되는지에 대한 제한 사항은 [명령 간에 유지되는 것](/docs/ko/tools-reference#what-persists-between-commands)을 참조하세요. 포그라운드 상한을 설정하는 것에 대해서는 [타임아웃 및 출력 제한](/docs/ko/tools-reference#timeout-and-output-limits)을 참조하세요. 백그라운드 시간 제한에 대해서는 [백그라운드 명령의 시간 제한](/docs/ko/tools-reference#time-limit-for-background-commands)을 참조하세요.

3226 3190

3227<h3 id="monitor">3191<h3 id="monitor">

3228 Monitor3192 Monitor

4126 4090

4127`timedOutAfterMs`는 밀리초 단위의 타임아웃이며, 명령이 타임아웃에 도달하고 명시적으로 시작하지 않고 백그라운드로 이동했을 때 설정됩니다. `backgroundCwdHint`는 백그라운드 명령에 `cd`, `pushd`, `popd` 또는 `chdir`과 같은 디렉토리 변경 내장이 포함되어 있을 때 설정되며, 세션 작업 디렉토리가 변경되지 않았음을 나타냅니다. 두 필드 모두 Claude Code v2.1.210 이상이 필요합니다.4091`timedOutAfterMs`는 밀리초 단위의 타임아웃이며, 명령이 타임아웃에 도달하고 명시적으로 시작하지 않고 백그라운드로 이동했을 때 설정됩니다. `backgroundCwdHint`는 백그라운드 명령에 `cd`, `pushd`, `popd` 또는 `chdir`과 같은 디렉토리 변경 내장이 포함되어 있을 때 설정되며, 세션 작업 디렉토리가 변경되지 않았음을 나타냅니다. 두 필드 모두 Claude Code v2.1.210 이상이 필요합니다.

4128 4092

4129포그라운드에서 실행 중인 서브에이전트가 백그라운드 명령을 소유할 때, 명령은 [해당 서브에이전트의 실행이 끝날 때 종료됩니다](/docs/ko/tools-reference#background-commands). Claude Code는 이러한 명령에 `backgroundEndsWithFinalResponse`를 `true`로 설정하고, 명령이 턴을 유지할 때 필드를 생략합니다. 주 대화 또는 백그라운드 서브에이전트에서 시작한 명령처럼 필드는 Claude Code v2.1.227 이상이 필요합니다.4093포그라운드에서 실행 중인 서브에이전트가 백그라운드 명령을 소유할 때, 명령은 [해당 서브에이전트의 실행이 끝날 때 종료됩니다](/docs/ko/tools-reference#when-a-background-command-stops). Claude Code는 이러한 명령에 `backgroundEndsWithFinalResponse`를 `true`로 설정하고, 명령이 턴을 유지할 때 필드를 생략합니다. 주 대화 또는 백그라운드 서브에이전트에서 시작한 명령처럼 필드는 Claude Code v2.1.227 이상이 필요합니다.

4130 4094

4131Claude Code는 `gitOperation.commit.branch`를 git의 커밋 요약 줄에 명명된 분기로 설정하고, 분리된 HEAD에서 만든 커밋의 경우 생략합니다. 이 필드는 Agent SDK v0.3.227 이상이 필요합니다. Claude Code는 `gh pr reopen` 명령을 `reopened` PR 작업으로 보고하며, 이는 Agent SDK v0.3.234 이상이 필요합니다.4095Claude Code는 `gitOperation.commit.branch`를 git의 커밋 요약 줄에 명명된 분기로 설정하고, 분리된 HEAD에서 만든 커밋의 경우 생략합니다. 이 필드는 Agent SDK v0.3.227 이상이 필요합니다. Claude Code는 `gh pr reopen` 명령을 `reopened` PR 작업으로 보고하며, 이는 Agent SDK v0.3.234 이상이 필요합니다.

4132 4096

agent-view.md +2 −20

Details

8 8

9`claude agents`로 열 수 있는 에이전트 뷰는 모든 백그라운드 세션을 위한 하나의 화면입니다: 무엇이 실행 중인지, 무엇이 입력을 필요로 하는지, 무엇이 완료되었는지를 보여줍니다. 새로운 세션을 디스패치하고, 트랜스크립트를 스크롤하는 대신 한눈에 상태를 확인하고, 필요할 때만 개입합니다. 각 백그라운드 세션은 터미널이 연결되지 않은 상태에서도 계속 실행되는 완전한 Claude Code 대화이므로, 언제든지 열고, 답변하고, 떠날 수 있습니다.9`claude agents`로 열 수 있는 에이전트 뷰는 모든 백그라운드 세션을 위한 하나의 화면입니다: 무엇이 실행 중인지, 무엇이 입력을 필요로 하는지, 무엇이 완료되었는지를 보여줍니다. 새로운 세션을 디스패치하고, 트랜스크립트를 스크롤하는 대신 한눈에 상태를 확인하고, 필요할 때만 개입합니다. 각 백그라운드 세션은 터미널이 연결되지 않은 상태에서도 계속 실행되는 완전한 Claude Code 대화이므로, 언제든지 열고, 답변하고, 떠날 수 있습니다.

10 10

11<img src="https://mintcdn.com/claude-code/1B48Qz2Z9hac4SLG/images/agent-view-light.png?fit=max&auto=format&n=1B48Qz2Z9hac4SLG&q=85&s=7a186c96ed47d6700d084d77e786be65" className="dark:hidden" alt="터미널의 에이전트 뷰: 헤더는 Claude Code v2.1.140, 모델, 작업 디렉토리 및 요약 개수를 표시합니다. 세션은 입력 필요, 작업 중, 완료됨으로 그룹화되며, 하단에 디스패치 입력과 키보드 힌트의 바닥글이 있습니다." width="1772" height="780" data-path="images/agent-view-light.png" />11<img src="https://mintcdn.com/claude-code/HDAmBwgbrZVk0pOt/images/agent-view-light.png?fit=max&auto=format&n=HDAmBwgbrZVk0pOt&q=85&s=d6905012bee31f3e6b3920b09c05dd02" className="dark:hidden" alt="터미널의 에이전트 뷰. 상단의 한 줄은 입력을 기다리는 세션, 작업 중인 세션, 완료된 세션의 개수를 표시합니다. 네 개의 세션이 입력 필요, 작업 중, 완료됨 아래에 그룹화되어 있습니다. 각 행은 세션의 이름, 최신 상태 또는 질문, 시간을 표시합니다. 하단에는 새 작업을 설명하기 위한 입력 필드와 키보드 힌트 행이 있습니다." width="1872" height="680" data-path="images/agent-view-light.png" />

12 12

13<img src="https://mintcdn.com/claude-code/1B48Qz2Z9hac4SLG/images/agent-view-dark.png?fit=max&auto=format&n=1B48Qz2Z9hac4SLG&q=85&s=a5bed7434bae368faea3a8f023b52aa2" className="hidden dark:block" alt="터미널의 에이전트 뷰: 헤더는 Claude Code v2.1.140, 모델, 작업 디렉토리 및 요약 개수를 표시합니다. 세션은 입력 필요, 작업 중, 완료됨으로 그룹화되며, 하단에 디스패치 입력과 키보드 힌트의 바닥글이 있습니다." width="1772" height="780" data-path="images/agent-view-dark.png" />13<img src="https://mintcdn.com/claude-code/HDAmBwgbrZVk0pOt/images/agent-view-dark.png?fit=max&auto=format&n=HDAmBwgbrZVk0pOt&q=85&s=fc3c195bfc57e313ced1f1beb36cee93" className="hidden dark:block" alt="터미널의 에이전트 뷰. 상단의 한 줄은 입력을 기다리는 세션, 작업 중인 세션, 완료된 세션의 개수를 표시합니다. 네 개의 세션이 입력 필요, 작업 중, 완료됨 아래에 그룹화되어 있습니다. 각 행은 세션의 이름, 최신 상태 또는 질문, 시간을 표시합니다. 하단에는 새 작업을 설명하기 위한 입력 필드와 키보드 힌트 행이 있습니다." width="1872" height="680" data-path="images/agent-view-dark.png" />

14 14

15Claude가 사용자의 감시 없이 작업할 수 있는 여러 독립적인 작업이 있을 때 에이전트 뷰를 사용합니다. 버그 수정, 풀 리퀘스트 검토, 불안정한 테스트 조사를 세 개의 행으로 디스패치하고, 다른 창에서 계속 작업하며, 행에 입력이 필요하거나 결과가 있음을 표시할 때 다시 확인합니다.15Claude가 사용자의 감시 없이 작업할 수 있는 여러 독립적인 작업이 있을 때 에이전트 뷰를 사용합니다. 버그 수정, 풀 리퀘스트 검토, 불안정한 테스트 조사를 세 개의 행으로 디스패치하고, 다른 창에서 계속 작업하며, 행에 입력이 필요하거나 결과가 있음을 표시할 때 다시 확인합니다.

16 16

966 966

967Claude Code는 `Enter`에서 또는 `claude attach`에서 [셸 명령](#run-a-shell-command)을 실행하는 행을 다시 시작하지 않습니다. 왜냐하면 명령을 다시 실행하기 때문입니다; 행의 메시지와 `claude attach` 모두 명령이 다시 실행되지 않음을 나타냅니다.967Claude Code는 `Enter`에서 또는 `claude attach`에서 [셸 명령](#run-a-shell-command)을 실행하는 행을 다시 시작하지 않습니다. 왜냐하면 명령을 다시 실행하기 때문입니다; 행의 메시지와 `claude attach` 모두 명령이 다시 실행되지 않음을 나타냅니다.

968 968

969<h4 id="terminal-host-died">

970 터미널 호스트 죽음

971</h4>

~~972~~

973Linux 및 WSL에서 감독자는 세션을 열든 열지 않든 몇 초마다 각 호스트 프로세스를 확인하고, 프로세스가 종료되었지만 감독자에 대한 연결이 닫히지 않은 경우 세션을 실패로 표시합니다.

~~974~~

975* 에이전트 뷰에서 행은 `terminal host process died — press Enter to restart`를 표시합니다. 행에서 `Enter`를 누르면 Claude Code는 새로운 호스트 프로세스에서 세션을 다시 시작합니다.

976* 셸에서 `claude attach <id>`는 이미 실패로 표시된 세션을 다시 시작합니다. 그렇지 않으면 원인을 보고하고 종료하며, `claude attach <id>`를 다시 실행하라고 알려줍니다.

~~977~~

978<h4 id="session-isn’t-responding">

979 세션이 응답하지 않음

980</h4>

~~981~~

982감독자가 열린 상태를 수락하지만 약 10초 동안 출력이 도착하지 않으면, Claude Code는 시도를 종료하고 다시 시작을 제공합니다. 단순히 중단된 세션, 예를 들어 머신 절전 상태에서는 이 제안에 도달하지 않습니다: 감독자는 [열 때 자체적으로 다시 시작](#read-session-state)합니다.

~~983~~

984* 에이전트 뷰에서 바닥글은 `Press enter again to restart this session — it isn't responding (its conversation is saved and resumes).`를 표시합니다. 같은 행에서 `Enter`를 다시 누르면 Claude Code는 응답하지 않는 프로세스를 중지하고 세션을 다시 시작합니다; 두 번째 누름 없이는 아무것도 중지하지 않습니다.

985* 셸에서 `claude attach <id>`는 원인을 보고하고 종료하며, `claude stop <id>`를 실행한 후 `claude attach <id>`를 실행하라고 알려줍니다.

~~986~~

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

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

989</h3>971</h3>

amazon-bedrock.md +12 −0

Details

384 384

385`opus`와 같은 모델 별칭은 핀으로 작동하지 않으며, Claude Code가 인식하지 못하는 모델 ID(예: 애플리케이션 추론 프로필 ARN)도 마찬가지입니다.385`opus`와 같은 모델 별칭은 핀으로 작동하지 않으며, Claude Code가 인식하지 못하는 모델 ID(예: 애플리케이션 추론 프로필 ARN)도 마찬가지입니다.

386 386

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

388

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

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

391</h3>

392

393계정이 세션이 실행 중인 모델에 대한 액세스를 잃으면(예: 관리자가 Amazon Bedrock 계정에서 비활성화), Claude Code는 각 요청이 실패하는 대신 세션을 다른 모델로 전환하고 `Switched to <fallback> because <model> is not available`을 표시합니다. 시작 폴백과 동일한 모델을 시도합니다: 먼저 동일한 계층의 이전 버전을 시도하고, 사용 가능한 Opus 버전이 없는 Opus 세션의 경우 기본 Sonnet 모델을 시도합니다.

394

395전환은 고정하지 않은 계층에만 적용되며, 이는 시작 폴백과 동일한 조건입니다. 선택한 특정 버전에서의 세션 또는 [애플리케이션 추론 프로필 ARN](#map-each-model-version-to-an-inference-profile)에서의 세션은 모델을 유지하고, 폴백 모델 체인이 없으면 요청이 실패합니다. [자동 모드](/docs/ko/permission-modes#enable-auto-mode-on-bedrock-agent-platform-or-foundry)에서 Claude Code는 Amazon Bedrock에서 자동 모드가 지원하는 모델로만 전환합니다. 해당 모델도 사용할 수 없으면 요청이 [AWS 인증 실패](/docs/ko/errors#aws-authentication-failed)로 실패하고 모델을 활성화하라는 힌트가 표시됩니다.

396

397구성한 [폴백 모델 체인](/docs/ko/model-config#fallback-model-chains)은 계층 전환을 대체합니다: 이러한 거부에서 Claude Code는 구성한 폴백으로 전환합니다. 거부된 요청이 전환하지 않고 실패하도록 하려면 [`CLAUDE_CODE_DISABLE_MODEL_ACCESS_FALLBACK=1`](/docs/ko/env-vars)을 설정합니다. 구성한 폴백 체인은 여전히 이러한 거부에서 전환합니다; 모든 거부된 요청이 실패하도록 하려면 체인도 제거합니다.

398

387<h2 id="cross-region-inference-profile-prefixes">399<h2 id="cross-region-inference-profile-prefixes">

388 교차 지역 추론 프로필 접두사400 교차 지역 추론 프로필 접두사

389</h2>401</h2>

artifacts.md +1 −1

Details

400 400

401[`--settings`](/docs/ko/cli-reference#cli-flags) 파일에서 아티팩트를 끄거나 `CLAUDE_CODE_DISABLE_ARTIFACT`를 사용하거나, 관리자가 [관리되는 설정](/docs/ko/server-managed-settings)에서 아티팩트를 끄면, 어떤 설정 파일도 아티팩트를 다시 켤 수 없습니다. v2.1.242 이전에는 [우선순위 스택](/docs/ko/settings#settings-precedence)에서 더 높은 파일이 낮은 우선순위 파일에서 `"enableArtifact": false`를 설정했을 때도 아티팩트를 다시 켤 수 있었습니다.401[`--settings`](/docs/ko/cli-reference#cli-flags) 파일에서 아티팩트를 끄거나 `CLAUDE_CODE_DISABLE_ARTIFACT`를 사용하거나, 관리자가 [관리되는 설정](/docs/ko/server-managed-settings)에서 아티팩트를 끄면, 어떤 설정 파일도 아티팩트를 다시 켤 수 없습니다.

402 402

403프로젝트의 `.claude/settings.json` 또는 `.claude/settings.local.json`에서 `"enableArtifact": false`를 설정하여 해당 프로젝트의 세션에 대해 아티팩트를 끌 수도 있습니다. 두 파일 중 하나에서 `"enableArtifact": true`를 설정해도 아티팩트를 다시 켜지 않습니다. 프로젝트 및 로컬 설정에서 키를 인식하려면 Claude Code v2.1.242 이상이 필요합니다.403프로젝트의 `.claude/settings.json` 또는 `.claude/settings.local.json`에서 `"enableArtifact": false`를 설정하여 해당 프로젝트의 세션에 대해 아티팩트를 끌 수도 있습니다. 두 파일 중 하나에서 `"enableArtifact": true`를 설정해도 아티팩트를 다시 켜지 않습니다. 프로젝트 및 로컬 설정에서 키를 인식하려면 Claude Code v2.1.242 이상이 필요합니다.

404 404

authentication.md +20 −0

Details

192* **Amazon Bedrock, Google Cloud's Agent Platform 또는 Microsoft Foundry와 같은 클라우드 공급자 세션**: `ANTHROPIC_API_KEY`, `ANTHROPIC_AUTH_TOKEN` 또는 `apiKeyHelper` 자격 증명, 또는 이전 Claude Console 로그인으로 저장된 API 키가 여전히 머신에 있는 동안에만 차단됩니다. 제거하면 세션이 시작됩니다. 이러한 세션은 클라우드 공급자에 대해 인증하며, 클라우드 공급자의 액세스 정책이 이를 제어합니다.192* **Amazon Bedrock, Google Cloud's Agent Platform 또는 Microsoft Foundry와 같은 클라우드 공급자 세션**: `ANTHROPIC_API_KEY`, `ANTHROPIC_AUTH_TOKEN` 또는 `apiKeyHelper` 자격 증명, 또는 이전 Claude Console 로그인으로 저장된 API 키가 여전히 머신에 있는 동안에만 차단됩니다. 제거하면 세션이 시작됩니다. 이러한 세션은 클라우드 공급자에 대해 인증하며, 클라우드 공급자의 액세스 정책이 이를 제어합니다.

193* **[Anthropic 프로필 또는 페더레이션 자격 증명](#anthropic-profiles-and-federation-credentials)**: `ANTHROPIC_API_KEY`, `ANTHROPIC_AUTH_TOKEN` 또는 `apiKeyHelper` 자격 증명, 또는 이전 Claude Console 로그인으로 저장된 API 키가 머신에도 있지 않는 한 차단되지 않습니다. 키는 프로필이 속한 조직을 확인하지 않습니다.193* **[Anthropic 프로필 또는 페더레이션 자격 증명](#anthropic-profiles-and-federation-credentials)**: `ANTHROPIC_API_KEY`, `ANTHROPIC_AUTH_TOKEN` 또는 `apiKeyHelper` 자격 증명, 또는 이전 Claude Console 로그인으로 저장된 API 키가 머신에도 있지 않는 한 차단되지 않습니다. 키는 프로필이 속한 조직을 확인하지 않습니다.

194 194

195<h3 id="restrict-which-api-providers-a-machine-may-use">

196 머신이 사용할 수 있는 API 공급자 제한

197</h3>

198

199[관리형 설정](/docs/ko/managed-settings)의 [`allowedProviders`](/docs/ko/settings-reference#allowedproviders)는 관리형 머신이 Anthropic API, Amazon Bedrock 또는 LLM 게이트웨이와 같은 Claude에 도달할 수 있는 서비스를 나열합니다. 이는 세션이 Anthropic과 통신할 때 사용하는 계정을 제어하는 `forceLoginMethod` 및 `forceLoginOrgUUID`를 보완합니다. Claude Code v2.1.285 이상이 필요합니다.

200

201```json managed-settings.json theme={null}

202{

203 "forceLoginMethod": "claudeai",

204 "forceLoginOrgUUID": ["xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"],

205 "allowedProviders": ["anthropic", "bedrock"]

206}

207```

208

209이 파일을 사용하면 claude.ai 조직에 로그인하거나 Amazon Bedrock으로 구성된 개발자가 정상적으로 시작됩니다. 다른 공급자로 설정된 세션은 시작 시 거부되며, 실행 중인 세션이 다른 공급자로 전환되면 다음 요청에서 거부됩니다. [관리형 설정이 이 API 공급자를 허용하지 않음](/docs/ko/errors#managed-settings-dont-allow-this-api-provider)은 각 메시지를 표시합니다.

210

211* **LLM 게이트웨이 또는 프록시 허용**: `"customEndpoint"`를 나열하고 동일한 소스의 관리형 `env` 블록에서 게이트웨이의 URL을 설정하세요. [설정 참조](/docs/ko/settings-reference#allowedproviders)는 모든 값을 나열하고 어떤 엔드포인트 변수에 관리형 `env` 핀이 필요한지 설명합니다.

212* **관리형 머신에 배포**: 정책의 나머지를 전달하는 관리형 소스에 목록을 넣으세요. 항목의 [범위 참고](/docs/ko/settings-reference#allowedproviders)는 서버 관리 목록이 이와 어떻게 결합되는지 설명합니다.

213* **서버 관리 설정만**: [서버 관리 설정](/docs/ko/server-managed-settings)에만 설정하는 목록은 조직의 설정을 가져오는 세션에만 도달하므로 장치 관리로 도달할 수 없는 머신의 편의로 취급하세요. 강제 사항이 아닙니다. [플랫폼 가용성](/docs/ko/server-managed-settings#platform-availability)은 어떤 세션이 이를 가져오는지 나열합니다.

214

195<h2 id="credential-management">215<h2 id="credential-management">

196 자격증명 관리216 자격증명 관리

197</h2>217</h2>

auto-mode-config.md +2 −6

Details

285 `/permissions`에서 규칙 편집285 `/permissions`에서 규칙 편집

286</h2>286</h2>

287 287

288설정 파일을 열지 않고 분류기 규칙을 보고 편집하려면 [`/permissions`](/docs/ko/permissions#manage-permissions)를 실행하고 **Auto mode** 탭을 선택합니다. 이 탭은 Claude Code v2.1.246 이상이 필요하며, [자동 모드를 사용할 수 있을 때](/docs/ko/permission-modes#eliminate-prompts-with-auto-mode)만 세션에 나타납니다.288설정 파일을 열지 않고 분류기 규칙과 `environment` 항목을 보고 편집하려면 [`/permissions`](/docs/ko/permissions#manage-permissions)를 실행하고 **Auto mode** 탭을 선택합니다. 이 탭은 Claude Code v2.1.246 이상이 필요하며, [자동 모드를 사용할 수 있을 때](/docs/ko/permission-modes#eliminate-prompts-with-auto-mode)만 세션에 나타납니다.

289 289

290이 탭은 [분류기가 구성을 읽는 각 범위](#where-the-classifier-reads-configuration)의 `allow`, `soft_deny`, `hard_deny`, `environment` 항목을 나열하고, 각 섹션에 대해 기본 제공 규칙이 적용되는지 여부를 표시합니다. Claude Code는 [관리되는 설정](/docs/ko/server-managed-settings) 또는 `--settings` 플래그의 항목을 읽기 전용으로 표시하고, 탭에서 수행한 모든 변경 사항을 `~/.claude/settings.json`에 저장합니다. 탭에서 다음을 수행할 수 있습니다:290Claude Code는 [관리되는 설정](/docs/ko/server-managed-settings) 또는 `--settings` 플래그의 항목을 읽기 전용으로 표시하고, 탭에서 수행한 모든 변경 사항을 `~/.claude/settings.json`에 저장합니다.

~~291~~

292* `allow`, `soft_deny`, `hard_deny` 섹션의 규칙을 추가, 편집 또는 삭제합니다. 섹션에 첫 번째 규칙을 추가하면 Claude Code도 `"$defaults"`를 삽입하여 [기본 제공 규칙](#override-the-block-and-allow-rules)이 계속 적용되도록 합니다.

293* `allow`, `soft_deny` 또는 `hard_deny`의 기본 제공 규칙을 끄거나 다시 켭니다. Claude Code는 해당 섹션의 목록에서 `"$defaults"`를 추가하거나 제거하여 선택을 기록하므로, 기본 제공 규칙을 끄려면 섹션에 자신의 규칙이 최소 하나 필요합니다.

294* `environment` 항목을 편집기에서 하나의 문서로 편집합니다. 아직 `environment` 항목을 구성하지 않았다면 Claude Code는 먼저 기본 제공 환경을 바꿀지 여부를 묻고, 전체 기본 제공 텍스트에서 편집기를 엽니다. 저장하면 Claude Code는 `autoMode.environment` 배열을 문서로 바꿉니다. [기본 제공 항목을 유지](#define-trusted-infrastructure)하려면 `"$defaults"` 줄을 포함합니다.

295 291

296<h2 id="route-all-shell-commands-through-the-classifier">292<h2 id="route-all-shell-commands-through-the-classifier">

297 모든 셸 명령을 분류기를 통해 라우팅합니다293 모든 셸 명령을 분류기를 통해 라우팅합니다

claude-apps-gateway-config.md +405 −317

Details

58 `listen`58 `listen`

59</h3>59</h3>

60 60

~~61`listen` 블록은 게이트웨이가 서비스하는 위치를 제어합니다: 바인드 주소와 포트, 외부에서 보이는 원본(origin), 그리고 선택적 TLS 종료입니다.~~61`listen` 블록은 게이트웨이가 서비스하는 위치를 제어합니다: 바인드 주소와 포트, 외부에서 보이는 원본, 그리고 선택적 TLS 종료입니다.

62 62

63| 필드 | 필수 | 설명 |63| 필드 | 필수 | 설명 |

64| - | - | - |64| - | - | - |

65| `host` | 아니오 | 바인드 주소입니다. 기본값 `0.0.0.0`. |65| `host` | 아니오 | 바인드 주소입니다. 기본값 `0.0.0.0`. |

66| `port` | 아니오 | 바인드 포트입니다. 기본값 `8080`. |66| `port` | 아니오 | 바인드 포트입니다. 기본값 `8080`. |

67| `public_url` | `host`가 루프백이 아닌 경우 | 외부에서 보이는 `https://` 원본으로, IdP `redirect_uri`와 검색 메타데이터를 구축하는 데 사용됩니다. `host`가 루프백 주소가 아닐 때마다 필수이며, TLS가 ALB, Ingress, Cloud Run 같은 프록시에서 종료되든 게이트웨이 자체에서 `tls`를 통해 종료되든 상관없습니다. 게이트웨이는 `X-Forwarded-*` 헤더에서 자신의 원본을 파생시키지 않기 때문입니다. 이들은 클라이언트가 스푸핑할 수 있습니다. 이것 없이는 부팅이 실패합니다. 아래의 `trusted_proxies`는 클라이언트 IP 해석만 제어합니다. 또한 [텔레메트리](#telemetry)를 활성화하려면 필수입니다. 게이트웨이가 클라이언트에 푸시하는 OTLP 엔드포인트를 이 URL에서 구축하기 때문입니다. |67| `public_url` | `host`가 루프백이 아닌 경우 필수 | 외부에서 보이는 `https://` 원본으로, IdP `redirect_uri`와 검색 메타데이터를 구축하는 데 사용됩니다. TLS가 ALB, Ingress, Cloud Run 같은 프록시에서 종료되든 `tls`를 통해 게이트웨이 자체에서 종료되든 `host`가 루프백 주소가 아닐 때마다 필수입니다. 게이트웨이는 `X-Forwarded-*` 헤더에서 자신의 원본을 파생시키지 않기 때문입니다. 이들은 클라이언트가 스푸핑할 수 있습니다. 이것 없이는 부팅이 실패합니다. 아래의 `trusted_proxies`는 클라이언트 IP 해석만 제어합니다. 또한 [텔레메트리](#telemetry)를 활성화하는 데 필수입니다. 게이트웨이가 클라이언트에 푸시하는 OTLP 엔드포인트를 이 URL에서 구축하기 때문입니다. |

68| `tls.cert` / `tls.key` | 아니오 | 게이트웨이가 TLS를 자체적으로 종료하는 경우 PEM 경로 |68| `tls.cert` / `tls.key` | 아니오 | 게이트웨이가 TLS를 자체적으로 종료하는 경우 PEM 경로 |

69| `trusted_proxies` | 아니오 | 게이트웨이 앞의 로드 밸런서의 CIDR 또는 IP입니다. 설정되면 게이트웨이는 이 피어들로부터만 `X-Forwarded-For`를 신뢰하고 IP별 속도 제한 및 감사를 위해 실제 클라이언트 IP를 기록합니다. nginx `set_real_ip_from`과 동등합니다. `X-Forwarded-For` 항목이 `ipv4:port` 또는 `[ipv6]:port`로 작성되면(일부 로드 밸런서가 하는 것처럼) 포트가 제거된 상태로 읽혀집니다. 포트가 추가되고 괄호가 없는 IPv6 주소는 다른 주소로 읽히거나 전혀 읽히지 않을 수 있으므로, 해당 형식을 작성하는 프록시의 포트 옵션을 끕니다. |69| `trusted_proxies` | 아니오 | 게이트웨이 앞의 로드 밸런서의 CIDR 또는 IP입니다. 설정되면 게이트웨이는 이 피어들로부터만 `X-Forwarded-For`를 신뢰하고 실제 클라이언트 IP를 기록하여 IP당 속도 제한 및 감사를 수행합니다. nginx `set_real_ip_from`과 동등합니다. `X-Forwarded-For` 항목이 일부 로드 밸런서처럼 `ipv4:port` 또는 `[ipv6]:port`로 작성되면 포트가 제거된 상태로 읽혀집니다. 포트가 추가되고 괄호가 없는 IPv6 주소는 다른 주소로 읽히거나 전혀 읽히지 않을 수 있으므로 해당 형식을 작성하는 모든 프록시에서 포트 옵션을 끕니다. |

70 70

71<h3 id="oidc">71<h3 id="oidc">

72 `oidc`72 `oidc`

74 74

75`oidc` 블록은 게이트웨이를 ID 공급자에 연결하고 누가 로그인할 수 있는지 결정합니다. 발급자와 OAuth 클라이언트의 이름을 지정하고, 이메일과 그룹을 전달하는 클레임을 매핑하며, 이메일 도메인 또는 그룹별로 로그인을 제한합니다.75`oidc` 블록은 게이트웨이를 ID 공급자에 연결하고 누가 로그인할 수 있는지 결정합니다. 발급자와 OAuth 클라이언트의 이름을 지정하고, 이메일과 그룹을 전달하는 클레임을 매핑하며, 이메일 도메인 또는 그룹별로 로그인을 제한합니다.

76 76

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

78 78

79| 필드 | 필수 | 설명 |79| 필드 | 필수 | 설명 |

80| - | - | - |80| - | - | - |

81| `issuer` | 예 | OIDC 검색 기본입니다. `/.well-known/openid-configuration`에서 검색을 제공해야 합니다. 프로덕션에서는 HTTPS를 사용하세요. 게이트웨이는 `http://` 발급자를 수락합니다. `http://localhost:8081` 같은 루프백 발급자는 [SSRF 가드](/docs/ko/claude-apps-gateway-deploy#threat-model-summary)에 의해 거부됩니다. `CLAUDE_GATEWAY_ALLOW_LOOPBACK=1`이 게이트웨이의 환경에 설정되어 있지 않은 경우입니다. |81| `issuer` | 예 | OIDC 검색 기본입니다. `/.well-known/openid-configuration`에서 검색을 제공해야 합니다. 프로덕션에서는 HTTPS를 사용하세요. 게이트웨이는 `http://` 발급자를 수락합니다. `http://localhost:8081` 같은 루프백 발급자는 `CLAUDE_GATEWAY_ALLOW_LOOPBACK=1`이 게이트웨이의 환경에 설정되지 않으면 [SSRF 가드](/docs/ko/claude-apps-gateway-deploy#threat-model-summary)에 의해 거부됩니다. |

82| `client_id` / `client_secret` | 예 | OAuth 클라이언트 등록에서 가져옵니다. |82| `client_id` / `client_secret` | 예 | OAuth 클라이언트 등록에서 가져옵니다. |

83| `allowed_email_domains` | 아니오 | `email` 클레임이 이 도메인 중 하나에 없는 id\_token을 거부합니다(대소문자 구분 안 함). 다중 테넌트 IdP 오구성에 대한 심층 방어입니다. 이 설정과 무관하게, `email_verified` 클레임이 명시적으로 `false`인 id\_token은 항상 거부됩니다. |83| `allowed_email_domains` | 아니오 | `email` 클레임이 이 도메인 중 하나에 없는 id\_token을 거부합니다(대소문자 구분 안 함). 다중 테넌트 IdP 잘못된 구성에 대한 심층 방어입니다. 이 설정과 무관하게 `email_verified` 클레임이 명시적으로 `false`인 id\_token은 항상 거부됩니다. |

84| `allowed_groups` | 아니오 | 로그인을 이 IdP 그룹의 멤버로 제한하며, `groups_claim`에 대해 일치합니다. 허용된 이메일 도메인에 있지만 이 그룹 중 어느 것에도 없는 사용자는 거부됩니다. IdP가 그룹 클레임을 내보내야 합니다. 일치는 해당 클레임의 값에 대한 정확한 대소문자 구분 문자열 비교이며, 게이트웨이는 중첩된 그룹을 확장하지 않습니다. 하위 그룹의 멤버를 허용하려면 여기에 하위 그룹을 나열하거나 IdP를 구성하여 평탄화된 멤버십을 내보냅니다. |84| `allowed_groups` | 아니오 | 로그인을 이 IdP 그룹의 멤버로 제한하고 `groups_claim`에 대해 일치시킵니다. 허용된 이메일 도메인에 있지만 이 그룹 중 어느 것도 아닌 사용자는 거부됩니다. IdP가 그룹 클레임을 내보내야 합니다. 일치는 해당 클레임의 값에 대한 정확한 대소문자 구분 문자열 비교이며 게이트웨이는 중첩된 그룹을 확장하지 않습니다. 하위 그룹의 멤버를 허용하려면 여기에 하위 그룹을 나열하거나 IdP를 구성하여 평탄화된 멤버십을 내보냅니다. |

85| `groups_claim` | 아니오 | 어느 id\_token 클레임이 그룹 멤버십을 전달하는지입니다. 기본값 `groups`. Microsoft Entra는 `roles` 아래에 앱 역할을 내보냅니다. 평탄한 키 또는 `/resource_access/gateway/roles` 같은 RFC 6901 JSON 포인터를 중첩된 클레임에 대해 수락합니다. |85| `groups_claim` | 아니오 | 어느 id\_token 클레임이 그룹 멤버십을 전달하는지입니다. 기본값 `groups`. Microsoft Entra는 `roles` 아래에 앱 역할을 내보냅니다. 평면 키 또는 중첩된 클레임에 대해 `/resource_access/gateway/roles` 같은 RFC 6901 JSON 포인터를 수락합니다. |

86| `google_groups` | 아니오 | Google Workspace Admin SDK Directory API를 통해 로그인한 사용자의 그룹을 조회합니다. Google의 id\_token은 그룹 클레임을 전달하지 않기 때문입니다. `service_account_json_path`를 `https://www.googleapis.com/auth/admin.directory.group.readonly` 범위에 대한 도메인 전체 위임이 있는 서비스 계정 키 파일로 설정하고, `admin_email`을 서비스 계정이 가장하는 Workspace 관리자로 설정합니다. Directory API는 실제 관리자 주체가 필요합니다. 각 사용자의 그룹 이메일 주소는 그룹 클레임이 되므로, `allowed_groups`와 `managed.policies.match.groups`는 그룹 이메일에 대해 일치합니다. |86| `google_groups` | 아니오 | Google Workspace Admin SDK Directory API를 통해 로그인한 사용자의 그룹을 조회합니다. Google의 id\_token은 그룹 클레임을 전달하지 않기 때문입니다. `service_account_json_path`를 `https://www.googleapis.com/auth/admin.directory.group.readonly` 범위에 대한 도메인 전체 위임이 있는 서비스 계정 키 파일로 설정하고, `admin_email`을 서비스 계정이 가장하는 Workspace 관리자로 설정합니다. Directory API는 실제 관리자 주체가 필요합니다. 각 사용자의 그룹 이메일 주소는 그룹 클레임이 되므로 `allowed_groups`와 `managed.policies.match.groups`는 그룹 이메일에 대해 일치합니다. |

87| `email_claim` | 아니오 | 어느 id\_token 클레임이 사용자의 이메일을 전달하는지입니다. 기본값 `email`. ADFS 및 Entra B2C 같은 일부 IdP는 대신 `upn` 또는 `preferred_username`을 내보냅니다. 평탄한 키, JSON 포인터, 또는 첫 번째 존재하는 키가 사용되는 폴백 키 목록을 수락합니다. |87| `email_claim` | 아니오 | 어느 id\_token 클레임이 사용자의 이메일을 전달하는지입니다. 기본값 `email`. ADFS 및 Entra B2C 같은 일부 IdP는 대신 `upn` 또는 `preferred_username`을 내보냅니다. 평면 키, JSON 포인터 또는 첫 번째 존재하는 키가 사용되는 폴백 키 목록을 수락합니다. |

88| `scopes` | 아니오 | 게이트웨이가 요청하는 OIDC 범위의 전체 재정의입니다. 기본값 `[openid, profile, email, offline_access]`. IdP가 인식하지 못하는 범위를 거부하거나 그룹 또는 이메일을 내보내기 위해 사용자 정의 범위가 필요한 경우 설정합니다. `openid`을 포함해야 합니다. `offline_access`를 제거하면 새로 고침 토큰이 비활성화되므로 개발자는 `session.ttl_hours`마다 브라우저 로그인을 다시 실행합니다. IdP별 범위 레시피(예: Google의 새로 고침 토큰 흐름)는 [ID 공급자 설정](/docs/ko/claude-apps-gateway-deploy#identity-provider-setup)을 참조하세요. |88| `scopes` | 아니오 | 게이트웨이가 요청하는 OIDC 범위의 전체 재정의입니다. 기본값 `[openid, profile, email, offline_access]`. IdP가 인식하지 못하는 범위를 거부하거나 그룹 또는 이메일을 내보내기 위해 사용자 정의 범위가 필요한 경우 설정합니다. `openid`을 포함해야 합니다. `offline_access`를 제거하면 새로 고침 토큰이 비활성화되므로 개발자는 `session.ttl_hours`마다 브라우저 로그인을 다시 실행합니다. Google의 새로 고침 토큰 흐름 같은 IdP별 범위 레시피는 [ID 공급자 설정](/docs/ko/claude-apps-gateway-deploy#identity-provider-setup)을 참조하세요. |

89| `scope_on_refresh` | 아니오 | 게이트웨이가 새로 고침 토큰을 교환할 때 로그인 요청과 동일한 목록으로 `scope`도 보냅니다. 기본값 `false`: 새로 고침 요청은 `scope`를 생략합니다. 대부분의 IdP는 모든 새로 고침에서 id\_token을 반환하고 이것이 필요하지 않습니다. IdP가 `openid`을 다시 요청할 때만 새로 고침 시 id\_token을 반환하는 경우 `true`로 설정합니다. Okta는 새로 고침 부여에 대해 이를 문서화합니다. id\_token이 없으면 모든 새로 고침은 IdP의 userinfo 엔드포인트가 새로 고쳐진 액세스 토큰을 수락하는 데 달려 있습니다. 로그인을 게이트하거나 그룹의 정책을 일치시키고 IdP의 새로 고침 시간 id\_token이 이들을 생략하는 경우, `userinfo_fallback: true`도 설정하여 게이트웨이가 userinfo 엔드포인트에서 이들을 채웁니다. 요청된 것보다 적은 범위를 부여한 IdP는 기존 세션에 대해서도 `invalid_scope`로 새로 고침을 거부할 수 있습니다. 이것을 설정한 후 새로 고침이 `token_endpoint`에서 실패하기 시작하면 키를 설정 해제합니다. 게이트웨이 서버에서 Claude Code v2.1.260 이상이 필요합니다. |89| `scope_on_refresh` | 아니오 | 게이트웨이가 새로 고침 토큰을 교환할 때 로그인 요청과 동일한 목록으로 `scope`도 보냅니다. 기본값 `false`: 새로 고침 요청은 `scope`를 생략합니다. 대부분의 IdP는 모든 새로 고침에서 id\_token을 반환하고 이것이 필요하지 않습니다. IdP가 다시 `openid`을 요청할 때만 새로 고침 시 id\_token을 반환하는 경우 `true`로 설정합니다. Okta는 새로 고침 부여에 대해 이를 문서화합니다. id\_token이 없으면 모든 새로 고침은 IdP의 userinfo 엔드포인트가 새로 고침된 액세스 토큰을 수락하는 데 달려 있습니다. 로그인을 게이트하거나 그룹의 정책을 일치시키고 IdP의 새로 고침 시간 id\_token이 이를 생략하는 경우 `userinfo_fallback: true`도 설정하여 게이트웨이가 userinfo 엔드포인트에서 이를 채우도록 합니다. 요청된 것보다 적은 범위를 부여한 IdP는 `invalid_scope`로 새로 고침을 거부할 수 있습니다. 이것이 켜져 있는 동안 `scopes`에 항목을 추가하면 기존 세션도 포함됩니다. 이것을 설정한 후 새로 고침이 `token_endpoint`에서 실패하기 시작하면 키를 설정 해제합니다. 게이트웨이 서버에서 Claude Code v2.1.260 이상이 필요합니다. |

90| `extra_auth_params` | 아니오 | IdP 인증 요청에 그대로 추가되는 추가 쿼리 매개변수입니다. 이것은 Google 새로 고침 토큰의 `access_type: offline`, 일부 Entra 테넌트의 `domain_hint`, 또는 단계별 흐름의 `acr_values` 같은 IdP별 동작에 대한 재정의 메커니즘입니다. 게이트웨이 관리 프로토콜 매개변수는 재정의할 수 없습니다: `state`, `nonce`, `redirect_uri`, PKCE, `scope`, `response_type`, `response_mode`, 및 `client_id`. |90| `extra_auth_params` | 아니오 | IdP 인증 요청에 그대로 추가되는 추가 쿼리 매개변수입니다. 이것은 Google 새로 고침 토큰의 `access_type: offline`, 일부 Entra 테넌트의 `domain_hint` 또는 단계별 흐름의 `acr_values` 같은 IdP별 동작에 대한 재정의 메커니즘입니다. 게이트웨이 관리 프로토콜 매개변수는 재정의할 수 없습니다: `state`, `nonce`, `redirect_uri`, PKCE, `scope`, `response_type`, `response_mode`, `client_id`. |

91| `userinfo_fallback` | 아니오 | id\_token이 이메일 또는 그룹을 생략할 때 `/userinfo`에서 가져옵니다. Keycloak 경량 액세스 토큰, Okta org 서버, 및 ADFS 최소 토큰에 필요합니다. id\_token은 권한이 있으며, userinfo는 간격만 채웁니다. 기본값 `false`. |91| `userinfo_fallback` | 아니오 | id\_token이 이메일 또는 그룹을 생략할 때 `/userinfo`에서 가져옵니다. Keycloak 경량 액세스 토큰, Okta org 서버 및 ADFS 최소 토큰에 필요합니다. id\_token은 권위 있는 상태로 유지됩니다. userinfo는 간격만 채웁니다. 기본값 `false`. |

92| `use_pkce` | 아니오 | 인증 요청에 PKCE(S256) 챌린지를 보냅니다. 기본값 `true`. IdP가 이 기밀 클라이언트에 대해 PKCE를 거부하는 경우에만 `false`로 설정합니다. |92| `use_pkce` | 아니오 | 인증 요청에 PKCE(S256) 챌린지를 보냅니다. 기본값 `true`. IdP가 이 기밀 클라이언트에 대해 PKCE를 거부하는 경우에만 `false`로 설정합니다. |

93| `clock_skew_seconds` | 아니오 | id\_token 시간 클레임을 검증할 때 클록 드리프트를 허용합니다. 기본값 `0`으로 엄격합니다. 로그인 직후 호스트/IdP 클록 스큐로 인해 "token expired / not yet valid" 오류가 표시되면 올립니다. |93| `clock_skew_seconds` | 아니오 | id\_token 시간 클레임을 검증할 때 클록 드리프트를 허용합니다. 기본값 `0`으로 엄격합니다. 로그인 직후 호스트/IdP 클록 스큐로 인해 "token expired / not yet valid" 오류가 표시되면 이를 높입니다. |

94| `token_endpoint_auth_method` | 아니오 | 토큰 엔드포인트 인증 방법을 재정의합니다. `client_secret_basic` 또는 `client_secret_post`를 수락합니다. 기본적으로 자동 협상됩니다. |94| `token_endpoint_auth_method` | 아니오 | 토큰 엔드포인트 인증 방법을 재정의합니다. `client_secret_basic` 또는 `client_secret_post`를 수락합니다. 기본적으로 자동 협상됩니다. |

~~95| `id_token_signed_response_alg` | 아니오 | 예상되는 id\_token 서명 알고리즘입니다. 기본값 `RS256`. ES256, PS256, 또는 EdDSA로 서명하는 IdP에 대해 설정합니다. |~~95| `id_token_signed_response_alg` | 아니오 | 예상되는 id\_token 서명 알고리즘입니다. 기본값 `RS256`. ES256, PS256 또는 EdDSA로 서명하는 IdP에 대해 설정합니다. |

~~96| `additional_authorized_parties` | 아니오 | `client_id` 이외에 수락할 추가 `azp` 값입니다. Keycloak 브로커 및 토큰 교환 흐름의 경우입니다. |~~96| `additional_authorized_parties` | 아니오 | `client_id` 외에 수락할 추가 `azp` 값입니다. Keycloak 브로커 및 토큰 교환 흐름의 경우입니다. |

97| `discovery_url` | 아니오 | `issuer`에서 파생시키는 대신 이 URL에서 검색 문서를 가져옵니다. 발급자 호스트를 다시 작성하는 프록시 뒤의 IdP의 경우입니다. 경로는 `/.well-known/`을 포함해야 합니다. |97| `discovery_url` | 아니오 | 이 URL에서 검색 문서를 가져옵니다. `issuer`에서 파생시키는 대신 발급자 호스트를 다시 작성하는 프록시 뒤의 IdP의 경우입니다. 경로는 `/.well-known/`을 포함해야 합니다. |

98| `use_proxy` | 아니오 | 게이트웨이의 자체 IdP 요청을 `HTTPS_PROXY` 또는 `HTTP_PROXY`의 정방향 프록시를 통해 보내고, `NO_PROXY`를 준수합니다. `false`로 설정하면 이 요청들은 직접 이동합니다. v2.1.227 이상이 필요합니다. 아래의 [정방향 프록시를 통한 IdP 요청](#idp-requests-through-a-forward-proxy)을 참조하세요. |98| `use_proxy` | 아니오 | 게이트웨이의 자체 IdP 요청을 `HTTPS_PROXY` 또는 `HTTP_PROXY`의 전방 프록시를 통해 보내고 `NO_PROXY`를 준수합니다. `false`는 이 요청을 직접 유지합니다. v2.1.227 이상이 필요합니다. 아래의 [전방 프록시를 통한 IdP 요청](#idp-requests-through-a-forward-proxy)을 참조하세요. |

99| `form_action_origins` | 아니오 | `/device` 페이지의 `Content-Security-Policy: form-action` 지시문에 대한 추가 원본입니다. 게이트웨이는 이미 `'self'`와 검색된 `authorization_endpoint` 원본을 허용하지만, Chrome은 전체 리디렉션 체인에 대해 `form-action`을 적용합니다. IdP가 Azure AD가 ADFS로 페더레이션되거나, 허브-스포크 Okta, 또는 회사 SSO 인터셉터 같은 두 번째 호스트를 통해 리디렉션하는 경우, 인증 요청이 리디렉션될 수 있는 모든 원본을 나열합니다. |99| `form_action_origins` | 아니오 | `/device` 페이지의 `Content-Security-Policy: form-action` 지시문에 대한 추가 원본입니다. 게이트웨이는 이미 `'self'`와 검색된 `authorization_endpoint` 원본을 허용하지만 Chrome은 전체 리디렉션 체인에 대해 `form-action`을 적용합니다. IdP가 Azure AD가 ADFS로 페더레이션되거나 허브-스포크 Okta 또는 회사 SSO 인터셉터 같은 두 번째 호스트를 통해 리디렉션하는 경우 인증 요청이 리디렉션될 수 있는 모든 원본을 나열합니다. |

100| `ca_cert_pem` | 아니오 | PEM 인코딩된 CA 인증서 자체이며, 파일 경로가 아닙니다. IdP 요청에만 시스템 신뢰 저장소를 대체합니다. 마운트된 파일을 로드하려면 `${file:/etc/gateway/idp-ca.pem}`을 작성합니다. 회사 PKI 뒤의 Keycloak 또는 Dex에 사용합니다. |100| `ca_cert_pem` | 아니오 | PEM 인코딩된 CA 인증서 자체이며 파일 경로가 아닙니다. IdP 요청에만 시스템 신뢰 저장소를 대체합니다. 마운트된 파일을 로드하려면 `${file:/etc/gateway/idp-ca.pem}`을 작성합니다. 회사 PKI 뒤의 Keycloak 또는 Dex에 사용합니다. |

101 101

102<h4 id="idp-requests-through-a-forward-proxy">102<h4 id="idp-requests-through-a-forward-proxy">

103 정방향 프록시를 통한 IdP 요청103 전방 프록시를 통한 IdP 요청

104</h4>104</h4>

105 105

106추론 업스트림은 모든 버전에서 `HTTPS_PROXY` 및 `HTTP_PROXY`를 준수합니다. 게이트웨이의 자체 IdP, 검색, JWKS, 토큰, 및 userinfo 요청은 `oidc.use_proxy: true`를 설정하지 않는 한 직접 이동합니다. v2.1.227 이상이 필요합니다. 프록시 변수가 설정되고, `use_proxy`가 설정 해제되고, 발급자가 `NO_PROXY`로 적용되지 않으면, 게이트웨이는 이 요청들을 직접 유지하고 부팅 시 선택하도록 요청하는 공지를 기록합니다. `use_proxy: false`는 이들을 직접 유지하고 공지를 침묵시킵니다.106추론 업스트림은 모든 버전에서 `HTTPS_PROXY` 및 `HTTP_PROXY`를 준수합니다. 게이트웨이 자체의 IdP, 검색, JWKS, 토큰 및 userinfo에 대한 요청은 `oidc.use_proxy: true`를 설정하지 않으면 직접 이동합니다. v2.1.227 이상이 필요합니다. 프록시 변수가 설정되고 `use_proxy`가 설정되지 않으며 발급자가 `NO_PROXY`로 적용되지 않으면 게이트웨이는 이 요청을 직접 유지하고 부팅 시 선택하도록 요청하는 공지를 기록합니다. `use_proxy: false`는 이를 직접 유지하고 공지를 무음처리합니다.

107 107

108`use_proxy: true`를 사용하면, 포드는 각 IdP 엔드포인트의 호스트명을 자체적으로 해석하고 프록시에 해석된 IP 주소로 `CONNECT`하도록 요청합니다. 따라서 프록시는 발급자뿐만 아니라 검색 문서가 이름을 지정하는 모든 호스트의 IP 주소로 `CONNECT`를 수락해야 합니다. `http://` 프록시 URL을 사용합니다. `ca_cert_pem`과 [SSRF 가드](/docs/ko/claude-apps-gateway-deploy#threat-model-summary)는 프록시된 경로에도 적용됩니다.108`use_proxy: true`를 사용하면 포드는 각 IdP 엔드포인트의 호스트 이름을 자체적으로 해석하고 프록시에 해석된 IP 주소로 `CONNECT`하도록 요청합니다. 따라서 프록시는 발급자뿐만 아니라 검색 문서가 이름을 지정하는 모든 호스트의 IP 주소로 `CONNECT`를 수락해야 합니다. `http://` 프록시 URL을 사용합니다. `ca_cert_pem`과 [SSRF 가드](/docs/ko/claude-apps-gateway-deploy#threat-model-summary)는 프록시된 경로에도 적용됩니다.

109 109

110[프록시 전용 이그레스](#proxy-only-egress)는 이 둘을 변경합니다: 활성화되는 동안, IdP 요청은 `use_proxy: false`를 설정하지 않는 한 프록시를 따르며, 게이트웨이는 먼저 해석하지 않고 프록시에 각 IdP 호스트명을 전달합니다.110[프록시 전용 이그레스](#proxy-only-egress)는 이 둘을 모두 변경합니다. 활성화되는 동안 IdP 요청은 `use_proxy: false`를 설정하지 않으면 프록시를 따르고 게이트웨이는 프록시에 각 IdP 호스트 이름을 먼저 해석하지 않고 전달합니다.

111 111

112<h4 id="proxy-only-egress">112<h4 id="proxy-only-egress">

113 프록시 전용 이그레스113 프록시 전용 이그레스

114</h4>114</h4>

115 115

116게이트웨이의 환경에서 `HTTPS_PROXY` 옆에 `CLAUDE_GATEWAY_PROXY_IS_EGRESS_BOUNDARY=1`을 설정합니다. 포드가 해당 정방향 프록시를 통해서만 다른 호스트에 도달하고 공개 DNS 이름을 자체적으로 해석할 수 없거나, 프록시가 IP 주소로 `CONNECT`를 거부할 때입니다. v2.1.277 이상이 필요합니다. 이것은 `gateway.yaml` 키가 아닌 환경 변수이므로 구성 파일의 아무것도 게이트웨이의 주소 확인을 완화할 수 없습니다.116게이트웨이의 환경에서 `HTTPS_PROXY` 옆에 `CLAUDE_GATEWAY_PROXY_IS_EGRESS_BOUNDARY=1`을 설정합니다. 포드가 해당 전방 프록시를 통해서만 다른 호스트에 도달하고 공개 DNS 이름을 자체적으로 해석할 수 없거나 프록시가 IP 주소로 `CONNECT`를 거부할 때입니다. v2.1.277 이상이 필요합니다. 구성 파일의 아무것도 게이트웨이의 주소 확인을 완화할 수 없도록 `gateway.yaml` 키가 아닌 환경 변수입니다.

117 117

118```bash theme={null}118```bash theme={null}

119export HTTPS_PROXY=http://proxy.corp.example.com:3128119export HTTPS_PROXY=http://proxy.corp.example.com:3128

124 124

125게이트웨이는 프록시 전용 이그레스가 활성화되는 동안 부팅 시 하나의 `network:` 줄을 기록합니다.125게이트웨이는 프록시 전용 이그레스가 활성화되는 동안 부팅 시 하나의 `network:` 줄을 기록합니다.

126 126

127아래의 각 행은 `HTTPS_PROXY`가 설정된 게이트웨이의 아웃바운드 요청 클래스 하나이며, 기본적으로 그리고 프록시 전용 이그레스가 활성화되는 동안입니다.127아래의 각 행은 `HTTPS_PROXY`가 설정된 게이트웨이에서 기본적으로 그리고 프록시 전용 이그레스가 활성화되는 동안 아웃바운드 요청의 한 클래스입니다.

128 128

129| 아웃바운드 요청 | 기본값 | 프록시 전용 이그레스 활성화 |129| 아웃바운드 요청 | 기본값 | 프록시 전용 이그레스 활성화 |

130| - | - | - |130| - | - | - |

131| `provider: anthropic` 업스트림, Workload Identity Federation 토큰 교환, `telemetry.forward_to` 내보내기 | 로컬에서 해석되고 확인된 후 확인된 IP 주소로 프록시를 통해 `CONNECT`. `NO_PROXY`에 나열된 텔레메트리 수집기는 대신 직접 도달합니다. | 프록시에 전달된 호스트명 |131| `provider: anthropic` 업스트림, Workload Identity Federation 토큰 교환, `telemetry.forward_to` 내보내기 | 로컬에서 해석되고 확인된 후 프록시를 통해 확인된 IP 주소로 `CONNECT`. `NO_PROXY`에 나열된 텔레메트리 수집기는 대신 직접 도달합니다. | 프록시에 전달된 호스트 이름 |

132| IdP 검색, JWKS, 토큰, 및 userinfo | [`oidc.use_proxy: true`](#idp-requests-through-a-forward-proxy)가 아닌 한 직접, 그러면 확인된 IP 주소로 `CONNECT` | 호스트명이 프록시에 전달됩니다. `oidc.use_proxy: false`가 내부 IdP를 직접 유지하지 않는 한 |132| IdP 검색, JWKS, 토큰 및 userinfo | [`oidc.use_proxy: true`](#idp-requests-through-a-forward-proxy)가 아니면 직접이고, 그러면 확인된 IP 주소로 `CONNECT`. | 호스트 이름이 프록시에 전달되고, `oidc.use_proxy: false`는 내부 IdP를 직접 유지합니다. |

134 134

135프록시 전용 이그레스는 게이트웨이의 환경이 이 세 가지 조건을 모두 충족하지 않는 한 꺼져 있습니다:135프록시 전용 이그레스는 게이트웨이의 환경이 이 세 가지 조건을 모두 충족하지 않으면 꺼진 상태로 유지됩니다:

136 136

137* `HTTPS_PROXY` 또는 `HTTP_PROXY`가 설정됩니다.137* `HTTPS_PROXY` 또는 `HTTP_PROXY`가 설정됩니다.

138* `NO_PROXY` 및 `no_proxy`는 비어 있습니다. 플랫폼이 둘 중 하나를 포드에 주입하면, 게이트웨이 컨테이너에서 둘 다 빈 값으로 설정합니다. `NO_PROXY`에 텔레메트리 수집기를 나열하면 프록시 전용 이그레스가 꺼져 있습니다.138* `NO_PROXY` 및 `no_proxy`가 비어 있습니다. 플랫폼이 포드에 둘 중 하나를 주입하면 게이트웨이 컨테이너에서 둘 다 빈 값으로 설정합니다. `NO_PROXY`에 텔레메트리 수집기를 나열하면 프록시 전용 이그레스가 꺼진 상태로 유지됩니다.

139* `CLAUDE_GATEWAY_ALLOW_LOOPBACK`이 켜져 있지 않습니다. 포드의 자체 루프백의 수집기 또는 IdP는 프록시 전용 이그레스와 결합될 수 없습니다. 루프백 주소가 프록시에 전달되면 프록시 호스트 자신의 것이 되기 때문입니다. 대신 이 서비스들에 프록시가 도달할 수 있는 주소를 제공합니다. 같은 이유로 게이트웨이는 프록시 전용 이그레스가 활성화되는 동안 `localhost` 스타일 이름을 완전히 거부합니다.139* `CLAUDE_GATEWAY_ALLOW_LOOPBACK`이 켜져 있지 않습니다. 포드 자체의 루프백에 있는 수집기 또는 IdP는 프록시 전용 이그레스와 결합할 수 없습니다. 루프백 주소가 프록시에 전달되면 프록시 호스트 자체이기 때문입니다. 대신 이 서비스에 프록시가 도달할 수 있는 주소를 제공합니다. 같은 이유로 게이트웨이는 프록시 전용 이그레스가 활성화되는 동안 `localhost` 스타일 이름을 완전히 거부합니다.

140 140

141이 조건 중 하나가 충족되지 않으면, 게이트웨이는 부팅 시 경고를 기록하고 이를 중지한 변수의 이름을 지정하며 기본 동작을 유지합니다.141이 조건 중 하나가 충족되지 않으면 게이트웨이는 부팅 시 경고를 기록하고 이를 중지한 변수의 이름을 지정하며 기본 동작을 유지합니다.

142 142

143프록시 전용 이그레스가 활성화되면, 내부 수집기 및 IP 주소로 구성된 모든 호스트를 포함하여 프록시의 모든 대상을 허용합니다. [`oidc.use_proxy: false`](#idp-requests-through-a-forward-proxy)로 내부 IdP를 직접 유지할 수 있습니다.143프록시 전용 이그레스가 활성화되면 내부 수집기 및 IP 주소로 구성된 모든 호스트를 포함하여 프록시의 모든 대상을 허용합니다. [`oidc.use_proxy: false`](#idp-requests-through-a-forward-proxy)를 사용하여 내부 IdP를 직접 유지할 수 있습니다.

144 144

145<Warning>145<Warning>

146 프록시의 허용 목록이 게이트웨이의 자체 확인만큼 엄격할 때만 이것을 켭니다. 프록시는 `169.254.169.254` 및 `metadata.google.internal` 같은 클라우드 메타데이터 엔드포인트, 링크 로컬 주소, 및 프록시 호스트의 자체 루프백을 거부해야 하며, 이름뿐만 아니라 이름이 해석되는 주소로 이들을 거부해야 합니다. 게이트웨이는 더 이상 호스트명이 이들 중 하나로 해석되는 것을 잡지 않기 때문입니다. 요청한 곳 어디든 연결하는 프록시는 이 요청들에 대해 게이트웨이의 [SSRF 가드](/docs/ko/claude-apps-gateway-deploy#threat-model-summary)를 제거합니다.146 프록시의 허용 목록이 게이트웨이 자체의 확인만큼 엄격할 때만 이를 켭니다. 프록시는 `169.254.169.254` 및 `metadata.google.internal` 같은 클라우드 메타데이터 엔드포인트, 링크 로컬 주소 및 프록시 호스트 자체의 루프백을 거부해야 하며, 이름으로만이 아니라 이름이 해석되는 주소로 거부해야 합니다. 게이트웨이가 더 이상 이 중 하나로 해석되는 호스트 이름을 포착하지 않기 때문입니다. 요청된 곳 어디든 연결하는 프록시는 이 요청에 대한 게이트웨이의 [SSRF 가드](/docs/ko/claude-apps-gateway-deploy#threat-model-summary)를 제거합니다.

147</Warning>147</Warning>

148 148

149<h3 id="session">149<h3 id="session">

150 `session`150 `session`

151</h3>151</h3>

152 152

153`session` 블록은 게이트웨이가 로그인 후 발행하는 베어러 토큰을 형성합니다: 이들에 서명하는 비밀과 얼마나 오래 살아있는지입니다.153`session` 블록은 게이트웨이가 로그인 후 발행하는 베어러 토큰을 형성합니다: 이를 서명하는 비밀과 얼마나 오래 살아있는지입니다.

154 154

155| 필드 | 필수 | 설명 |155| 필드 | 필수 | 설명 |

156| - | - | - |156| - | - | - |

157| `jwt_secret` | 예 | 최소 32바이트의 엔트로피입니다. 예를 들어 `openssl rand -base64 32`에서 가져옵니다. 게이트웨이의 HS256 베어러 토큰에 서명합니다. 단일 문자열 또는 회전을 위한 배열을 수락합니다: 인덱스 0이 서명하고 모든 항목이 검증합니다. 회전하려면 새 비밀을 앞에 추가하고, `ttl_hours`를 기다린 후, 이전 항목을 제거합니다. |157| `jwt_secret` | 예 | 최소 32바이트의 엔트로피입니다. 예를 들어 `openssl rand -base64 32`에서 가져옵니다. 게이트웨이의 HS256 베어러 토큰에 서명합니다. 단일 문자열 또는 회전을 위한 배열을 수락합니다: 인덱스 0이 서명하고 모든 항목이 검증합니다. 회전하려면 새 비밀을 앞에 추가하고 `ttl_hours`를 기다린 후 이전 비밀을 제거합니다. |

158| `ttl_hours` | 아니오 | 게이트웨이 베어러 토큰 수명입니다. 기본값 `1`. CLI는 IdP가 새로 고침 토큰을 발행할 때 만료 전에 자동으로 새로 고칩니다. 더 짧은 수명은 더 빠르게 프로비저닝을 해제합니다. 더 긴 수명은 더 적은 IdP 왕복을 만듭니다. IdP가 `offline_access`를 사용할 수 없기 때문에 새로 고침 토큰을 발행할 수 없으면, 자동 새로 고침이 없으므로 개발자가 매시간 브라우저 로그인으로 돌아가는 것을 피하기 위해 이것을 `8` 또는 `12`로 올립니다. |158| `ttl_hours` | 아니오 | 게이트웨이 베어러 토큰 수명입니다. 기본값 `1`. CLI는 IdP가 새로 고침 토큰을 발행할 때 만료 전에 자동으로 새로 고칩니다. 더 짧은 수명은 더 빠르게 프로비저닝을 해제합니다. 더 긴 수명은 더 적은 IdP 왕복을 만듭니다. IdP가 `offline_access`를 사용할 수 없기 때문에 새로 고침 토큰을 발행할 수 없으면 자동 새로 고침이 없으므로 이를 `8` 또는 `12`로 높여 개발자가 매시간 브라우저 로그인으로 돌아가는 것을 피합니다. |

159 159

160<h3 id="store">160<h3 id="store">

161 `store`161 `store`

165 165

166| 필드 | 필수 | 설명 |166| 필드 | 필수 | 설명 |

167| - | - | - |167| - | - | - |

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

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

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

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

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

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

174 174

175로컬 개발의 경우, `postgres_url`을 일회용 Postgres 컨테이너로 지정합니다. 예를 들어 `docker run --rm -p 5432:5432 -e POSTGRES_HOST_AUTH_METHOD=trust postgres`.175로컬 개발의 경우 `postgres_url`을 일회용 Postgres 컨테이너로 지정합니다. 예를 들어 `docker run --rm -p 5432:5432 -e POSTGRES_HOST_AUTH_METHOD=trust postgres`.

176 176

177<h3 id="upstreams">177<h3 id="upstreams">

178 `upstreams`178 `upstreams`

180 180

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

182 182

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

184 184

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

186 186

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

188 188

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

190 190

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

192 192

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

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

197게이트웨이는 업스트림이 응답한 방식에 따라 한 업스트림의 오류 응답 또는 자체 `502`를 반환합니다:197게이트웨이는 업스트림이 응답한 방식에 따라 한 업스트림의 오류 응답 또는 자체 `502`를 반환합니다:

198 198

199* **업스트림이 게이트웨이가 [장애 조치](#multiple-upstreams)하지 않는 상태를 반환했습니다**: 해당 업스트림의 응답입니다. 게이트웨이는 추가 업스트림을 시도하지 않습니다.199* **업스트림이 게이트웨이가 [장애 조치](#multiple-upstreams)하지 않는 상태를 반환했습니다**: 해당 업스트림의 응답입니다. 게이트웨이는 추가 업스트림을 시도하지 않습니다.

200* **게이트웨이가 시도한 모든 업스트림이 [장애 조치](#multiple-upstreams)하는 방식으로 실패했습니다**: 마지막 `429`. 아무도 `429`를 반환하지 않으면, 게이트웨이는 순서대로 마지막 `401` 또는 `403`, 마지막 `404`, 및 마지막 `501`을 선호합니다. 아무도 이들 중 어느 것도 반환하지 않으면, 게이트웨이의 자체 `502`, `all upstreams failed (N attempted)`. N은 게이트웨이가 요청된 모델을 제공하지 않기 때문에 건너뛴 항목을 포함하여 [`upstreams`](#upstreams)의 모든 항목을 계산합니다.200* **게이트웨이가 시도한 모든 업스트림이 [장애 조치](#multiple-upstreams)하는 방식으로 실패했습니다**: 마지막 `429`. 아무도 `429`를 반환하지 않으면 게이트웨이는 순서대로 마지막 `401` 또는 `403`, 마지막 `404`, 마지막 `501`을 선호합니다. 아무도 이 중 하나를 반환하지 않으면 게이트웨이 자체의 `502`, `all upstreams failed (N attempted)`입니다. N은 게이트웨이가 요청된 모델을 제공하지 않기 때문에 건너뛴 항목을 포함하여 [`upstreams`](#upstreams)의 모든 항목을 계산합니다.

201 201

202게이트웨이가 업스트림의 응답을 반환할 때, 업스트림의 상태 코드를 유지합니다. 업스트림의 메시지를 유지하는지 여부는 공급자에 따라 다릅니다. Anthropic API 업스트림의 오류 본문은 개발자에게 변경되지 않은 상태로 도달합니다.202게이트웨이가 업스트림의 응답을 반환할 때 업스트림의 상태 코드를 유지합니다. 업스트림의 메시지를 유지하는지 여부는 공급자에 따라 다릅니다. Anthropic API 업스트림의 오류 본문은 개발자에게 변경되지 않은 상태로 도달합니다.

203 203

204Amazon Bedrock, Claude Platform on AWS, Google Cloud의 Agent Platform, 및 Microsoft Foundry 업스트림은 오류 텍스트에서 계정 ID, 역할 ARN, 및 프로젝트 ID의 이름을 지정할 수 있습니다. 게이트웨이는 해당 전체 텍스트를 [운영 로그](/docs/ko/claude-apps-gateway-deploy#logs)에 기록합니다. 개발자가 이 업스트림들에서 보는 것은 거부에 따라 다릅니다:204Amazon Bedrock, Claude Platform on AWS, Google Cloud의 Agent Platform 및 Microsoft Foundry 업스트림은 오류 텍스트에서 계정 ID, 역할 ARN 및 프로젝트 ID의 이름을 지정할 수 있습니다. 게이트웨이는 해당 전체 텍스트를 [운영 로그](/docs/ko/claude-apps-gateway-deploy#logs)에 기록합니다. 개발자가 이 업스트림에서 보는 것은 거부에 따라 다릅니다:

205 205

206* Anthropic의 표준 오류 봉투의 `400` 또는 `413`: `prompt is too long` 같은 업스트림의 자체 메시지입니다. Claude Platform on AWS, Agent Platform, 및 Microsoft Foundry는 모델 API 거부에 대해 이 봉투를 반환합니다.206* Anthropic의 표준 오류 봉투의 `400` 또는 `413`: `prompt is too long` 같은 업스트림 자체의 메시지입니다. Claude Platform on AWS, Agent Platform 및 Microsoft Foundry는 모델 API 거부에 대해 이 봉투를 반환합니다.

207* 공급자의 자체 형태의 `400` 또는 `413`: `capability_rejected:` 토큰입니다. 게이트웨이가 거부를 분류할 수 없으면, `400`에서 `upstream rejected the request` 또는 `413`에서 `request too large for this upstream`.207* 공급자 자체의 형태의 `400` 또는 `413`: `capability_rejected:` 토큰입니다. 게이트웨이가 거부를 분류할 수 없으면 `400`에서 `upstream rejected the request` 또는 `413`에서 `request too large for this upstream`.

208* 다른 상태: `429`에서 `upstream rate limit exceeded` 같은 상태별 일반 복사입니다.208* 다른 상태: `429`에서 `upstream rate limit exceeded` 같은 상태별 일반 복사입니다.

209 209

210예를 들어, 게이트웨이는 Amazon Bedrock의 `Input is too long for requested model.`을 `capability_rejected: prompt_too_long`으로 대체합니다. Claude Code는 `prompt is too long`에서처럼 해당 토큰에서 [자동으로 압축합니다](/docs/ko/errors#prompt-is-too-long).210예를 들어 게이트웨이는 Amazon Bedrock의 `Input is too long for requested model.`을 `capability_rejected: prompt_too_long`으로 대체합니다. Claude Code는 `prompt is too long`처럼 해당 토큰에서 [자동으로 압축합니다](/docs/ko/errors#prompt-is-too-long).

211 211

212클라우드 업스트림의 `400` 또는 `413` 메시지를 유지하거나 `capability_rejected:` 토큰으로 대체하려면 게이트웨이 v2.1.233 이상이 필요합니다.212클라우드 업스트림의 `400` 또는 `413` 메시지를 유지하거나 `capability_rejected:` 토큰으로 대체하려면 게이트웨이 v2.1.233 이상이 필요합니다.

213 213

215 Anthropic API215 Anthropic API

216</h4>216</h4>

217 217

218최소 Anthropic 업스트림은 [Claude Console](https://platform.claude.com)의 API 키입니다:218최소 Anthropic 업스트림은 [Claude 콘솔](https://platform.claude.com)의 API 키입니다:

219 219

220```yaml theme={null}220```yaml theme={null}

221upstreams:221upstreams:

229 229

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

231 231

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

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

234 234

235정적 키 또는 베어러 대신, Workload Identity Federation을 사용할 수 있습니다. [Workload Identity Federation 가이드](https://platform.claude.com/docs/en/manage-claude/workload-identity-federation)를 따라 페더레이션 규칙을 생성한 후, 워크로드의 OIDC JWT를 파일로 마운트합니다. 예를 들어 Kubernetes 프로젝션된 서비스 계정 토큰 또는 CI 플랫폼의 id-token입니다. 게이트웨이는 JWT를 단기 베어러로 교환하고 자동으로 새로 고칩니다. 토큰 파일은 모든 교환에서 다시 읽혀지므로, 회전된 프로젝션된 토큰은 재시작 없이 선택됩니다.235정적 키 또는 베어러 대신 Workload Identity Federation을 사용할 수 있습니다. [Workload Identity Federation 가이드](https://platform.claude.com/docs/en/manage-claude/workload-identity-federation)를 따라 페더레이션 규칙을 만든 후 워크로드의 OIDC JWT를 Kubernetes 프로젝션된 서비스 계정 토큰 또는 CI 플랫폼의 id-token 같은 파일로 마운트합니다. 게이트웨이는 JWT를 단기 베어러로 교환하고 자동으로 새로 고칩니다. 토큰 파일은 모든 교환에서 다시 읽혀지므로 회전된 프로젝션된 토큰은 재시작 없이 선택됩니다.

236 236

237```yaml theme={null}237```yaml theme={null}

238upstreams:238upstreams:

248<a id="per-user-identity-headers-for-a-proxy-you-run" />248<a id="per-user-identity-headers-for-a-proxy-you-run" />

249 249

250<h5 id="per-user-identity-headers-for-a-proxy-you-run">250<h5 id="per-user-identity-headers-for-a-proxy-you-run">

251 사용자가 실행하는 프록시에 대한 사용자별 ID 헤더251 프록시를 실행하는 경우 사용자별 ID 헤더

252</h5>252</h5>

253 253

254`provider: anthropic` 업스트림의 `base_url`을 Anthropic API 대신 실행하는 프록시로 지정할 수 있습니다. 해당 프록시에 각 요청을 보낸 개발자를 알리려면, 해당 업스트림에서 `forward_user_identity: true`를 설정합니다. 그러면 프록시는 개발자별로 지출을 속성화할 수 있습니다. 게이트웨이 서버에서 Claude Code v2.1.233 이상이 필요합니다.254`provider: anthropic` 업스트림의 `base_url`을 Anthropic API 대신 실행하는 프록시로 지정할 수 있습니다. 해당 프록시에 각 요청을 보낸 개발자를 알리려면 해당 업스트림에 `forward_user_identity: true`를 설정합니다. 그러면 프록시는 개발자별로 지출을 기인할 수 있습니다. 게이트웨이 v2.1.233 이상을 실행해야 합니다.

255 255

256예를 들어, `upstream-gateway.internal.example.com`의 프록시의 경우:256예를 들어 `upstream-gateway.internal.example.com`의 프록시의 경우:

257 257

258```yaml theme={null}258```yaml theme={null}

259upstreams:259upstreams:

264 forward_user_identity: true # default false264 forward_user_identity: true # default false

265```265```

266 266

267게이트웨이는 해당 업스트림으로 전달하는 모든 요청에 이 헤더들을 추가합니다.267게이트웨이는 해당 업스트림으로 전달하는 모든 요청에 이 헤더를 추가합니다.

268 268

269| 헤더 | 값 |269| 헤더 | 값 |

270| - | - |270| - | - |

274 274

275IdP 토큰이 이메일을 전달하지 않으면, 게이트웨이는 `x-claude-gateway-user-id`만 보내고 두 이메일 헤더를 생략합니다. IdP가 이메일을 다른 클레임에 넣으면, [`oidc.email_claim`](#oidc)을 해당 클레임으로 설정합니다.275IdP 토큰이 이메일을 전달하지 않으면 게이트웨이는 `x-claude-gateway-user-id`만 보내고 두 이메일 헤더를 생략합니다. IdP가 이메일을 다른 클레임에 넣으면 [`oidc.email_claim`](#oidc)을 해당 클레임으로 설정합니다.

276 276

277프록시가 개발자의 이메일을 전달한 요청에 `429`로 응답하면, 게이트웨이는 해당 응답을 개발자에게 그대로 반환하고 다음 업스트림으로 장애 조치하지 않으므로, 프록시의 사용자별 예산 또는 속도 제한이 유지됩니다. 프록시의 다른 응답은 일반적인 [장애 조치 규칙](#upstreams)을 따릅니다. 개발자의 IdP 토큰이 이메일을 전달하지 않으면, 게이트웨이는 이메일 헤더 없이 요청을 전달하므로, 이 요청 중 하나에 대한 `429`는 업스트림 용량으로 계산되고 장애 조치합니다. 게이트웨이 서버에서 v2.1.267 이전에는 모든 `429`가 장애 조치했습니다.277프록시가 개발자의 이메일을 전달한 요청에 `429`로 응답하면 게이트웨이는 해당 응답을 개발자에게 그대로 반환하고 다음 업스트림으로 장애 조치하지 않으므로 프록시의 사용자별 예산 또는 속도 제한이 유지됩니다. 프록시의 다른 응답은 일반적인 [장애 조치 규칙](#upstreams)을 따릅니다. 개발자의 IdP 토큰이 이메일을 전달하지 않으면 게이트웨이는 이메일 헤더 없이 요청을 전달하므로 이 중 하나에 대한 `429`는 업스트림 용량으로 계산되고 장애 조치합니다. 게이트웨이 서버의 v2.1.267 이전에는 모든 `429`가 장애 조치했습니다.

278 278

279`forward_user_identity`를 운영하는 프록시인 업스트림의 `base_url`에만 설정합니다. 게이트웨이는 개발자 이메일을 해당 `base_url`이 이름을 지정하는 모든 서버로 보냅니다. `base_url`이 기본값인 Anthropic API인 경우, 게이트웨이는 시작을 거부합니다.279`forward_user_identity`를 `base_url`이 운영하는 프록시인 업스트림에만 설정합니다. 게이트웨이는 개발자 이메일을 해당 `base_url`이 이름을 지정하는 모든 서버에 보냅니다. `base_url`이 기본값인 Anthropic API인 경우 게이트웨이는 시작을 거부합니다.

280 280

281<h4 id="amazon-bedrock">281<h4 id="amazon-bedrock">

282 Amazon Bedrock282 Amazon Bedrock

283</h4>283</h4>

284 284

285클라이언트 측 Amazon Bedrock 배포(게이트웨이가 대체하거나 앞에 있는)의 경우, [Amazon Bedrock의 Claude Code](/docs/ko/amazon-bedrock)를 참조하세요. 게이트웨이 측 업스트림:285클라이언트 측 Amazon Bedrock 배포의 경우 게이트웨이가 대체하거나 앞에 있는 경우 [Amazon Bedrock의 Claude Code](/docs/ko/amazon-bedrock)를 참조하세요. 게이트웨이 측 업스트림:

286 286

287```yaml theme={null}287```yaml theme={null}

288upstreams:288upstreams:

301 # base_url: https://bedrock-runtime-fips.us-east-1.amazonaws.com301 # base_url: https://bedrock-runtime-fips.us-east-1.amazonaws.com

302```302```

303 303

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

305 305

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

307 307

308| 설정 | 방법 |308| 설정 | 방법 |

309| - | - |309| - | - |

310| IAM 권한 | 게이트웨이의 주체에 추론 프로필 ARN과 기본 기초 모델 ARN 모두에 `bedrock:InvokeModel` 및 `bedrock:InvokeModelWithResponseStream`을 부여합니다. US 지역의 기본 제공 카탈로그의 경우: `arn:aws:bedrock:<region>:<account>:inference-profile/us.anthropic.*` 및 `arn:aws:bedrock:*::foundation-model/anthropic.*`. 또한 기초 모델 ARN에 `bedrock:CountTokens`를 부여합니다. 게이트웨이는 이를 사용하여 클라이언트가 포기한 요청의 입력 토큰을 계산하므로, [지출 제한](#admin)이 정확하게 유지됩니다. 이것 없이 게이트웨이는 해당 계산을 위해 일회용 Bedrock 요청으로 폴백합니다. |310| IAM 권한 | 게이트웨이의 주체에 추론 프로필 ARN과 기본 기초 모델 ARN 모두에 `bedrock:InvokeModel` 및 `bedrock:InvokeModelWithResponseStream`을 부여합니다. US 지역의 기본 제공 카탈로그의 경우: `arn:aws:bedrock:<region>:<account>:inference-profile/us.anthropic.*` 및 `arn:aws:bedrock:*::foundation-model/anthropic.*`. 또한 기초 모델 ARN에 `bedrock:CountTokens`를 부여합니다. 게이트웨이는 이를 사용하여 클라이언트가 포기한 요청의 입력 토큰을 계산합니다. 비용이 없으므로 [지출 제한](#admin)이 정확하게 유지됩니다. 이것 없으면 게이트웨이는 해당 계산을 위해 일회용 Bedrock 요청으로 폴백합니다. |

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

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

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

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

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

316 316

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

318 Amazon Bedrock 가드레일 적용318 Amazon Bedrock 가드레일 적용

319</h5>319</h5>

320 320

321게이트웨이가 Bedrock 업스트림을 통해 보내는 모든 추론 요청에 Amazon Bedrock 가드레일을 적용하려면, 해당 업스트림에 `guardrail` 블록을 추가합니다. 게이트웨이 서버에서 Claude Code v2.1.281 이상이 필요합니다.321게이트웨이가 Bedrock 업스트림을 통해 보내는 모든 추론 요청에 Amazon Bedrock 가드레일을 적용하려면 해당 업스트림에 `guardrail` 블록을 추가합니다. 게이트웨이 서버에서 Claude Code v2.1.281 이상이 필요합니다.

322 322

323```yaml theme={null}323```yaml theme={null}

324upstreams:324upstreams:

332```332```

333 333

334<Warning>334<Warning>

335 게이트웨이는 가드레일 입력 태그를 지원하지 않습니다. 프롬프트에 가드 콘텐츠 태그를 추가하지 않으므로, 입력 태그에만 적용되는 가드레일 필터는 게이트웨이를 통한 트래픽에서 실행되지 않습니다. 입력 태그에 따라 달라지는 필터는 [입력 태그](https://docs.aws.amazon.com/bedrock/latest/userguide/guardrails-tagging.html)를 Amazon Bedrock 설명서에서 참조하세요.335 게이트웨이는 가드레일 입력 태그를 지원하지 않습니다. 프롬프트에 가드 콘텐츠 태그를 추가하지 않으므로 Amazon Bedrock이 태그된 입력에만 적용하는 가드레일 필터는 게이트웨이를 통한 트래픽에서 실행되지 않습니다. 입력 태그에 따라 다른 필터는 Amazon Bedrock 설명서의 [입력 태그](https://docs.aws.amazon.com/bedrock/latest/userguide/guardrails-tagging.html)를 참조하세요.

336</Warning>336</Warning>

337 337

338또한 게이트웨이의 AWS 주체에 가드레일에 `bedrock:ApplyGuardrail`을 부여합니다.338또한 이 업스트림의 요청에 서명하는 주체에 가드레일에 `bedrock:ApplyGuardrail`을 부여합니다: 게이트웨이의 AWS 주체 또는 [`assume_role`](#bedrock-in-another-aws-account)을 사용하여 `role_arn`에 이름이 지정된 역할입니다.

339 339

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

341 341

342가드레일은 Bedrock 업스트림만 다룹니다. `upstreams`에 다른 공급자를 나열하면, 게이트웨이는 가드레일 없이 해당 공급자로 요청을 보냅니다.342가드레일은 Bedrock 업스트림만 적용합니다. `upstreams`에 다른 공급자를 나열하면 게이트웨이는 가드레일 없이 해당 공급자에 요청을 보냅니다.

343 343

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

345

346<a id="bedrock-in-another-aws-account" />

347

348<h5 id="bedrock-in-another-aws-account">

349 다른 AWS 계정의 Bedrock

350</h5>

351

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

353

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

355

356```yaml theme={null}

357upstreams:

358 - name: bedrock-isolated

359 provider: bedrock

360 region: us-east-1

361 auth: {} # the gateway's own role: it only calls STS

362 assume_role:

363 role_arn: arn:aws:iam::222222222222:role/claude-gateway-bedrock

364 # external_id: ${BEDROCK_ROLE_EXTERNAL_ID} # when the role's trust policy requires one

365```

366

367`assume_role` 블록은 세 가지 키를 사용합니다:

368

369| 키 | 의미 |

370| - | - |

371| `role_arn` | 게이트웨이가 가정하는 IAM 역할입니다. `arn:aws:iam::` 또는 `arn:aws-us-gov:iam::` ARN입니다. 이 업스트림이 필요한 [Bedrock 권한](#amazon-bedrock), `bedrock:CountTokens` 포함, 그리고 업스트림이 `guardrail`을 설정할 때 `bedrock:ApplyGuardrail`을 제공합니다. |

372| `external_id` | 선택 사항입니다. 모든 `sts:AssumeRole` 호출에서 외부 ID로 전송됩니다. 역할의 신뢰 정책이 하나를 요구할 때 설정하고 모두 숫자인 경우 따옴표로 묶습니다. |

373| `session_name` | 선택 사항입니다. `email` 또는 `sub`는 각 개발자에게 자신의 세션을 제공합니다: [개발자별 AWS 비용 기인](#per-developer-aws-cost-attribution)을 참조하세요. 설정 해제되면 모든 요청이 `claude-apps-gateway`라는 하나의 세션을 사용합니다. |

374

375역할의 신뢰 정책은 게이트웨이의 자체 주체(예: IRSA 또는 ECS 작업 역할)의 이름을 지정합니다. 해당 주체는 역할에 `sts:AssumeRole`이 필요하고 자체 Bedrock 권한이 없습니다. `external_id`를 설정하지 않으면 `Condition`을 제거합니다.

376

377```json theme={null}

378{

379 "Version": "2012-10-17",

380 "Statement": [{

381 "Effect": "Allow",

382 "Principal": { "AWS": "arn:aws:iam::111111111111:role/claude-gateway" },

383 "Action": "sts:AssumeRole",

384 "Condition": { "StringEquals": { "sts:ExternalId": "your-external-id" } }

385 }]

386}

387```

388

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

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

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

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

393

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

395

396```yaml theme={null}

397models:

398 - id: claude-opus-restricted # a custom id, not a built-in model name

399 upstream_model:

400 bedrock-isolated: us.anthropic.claude-opus-4-8 # the only upstream that serves it

401```

402

403<a id="per-developer-aws-cost-attribution" />

404

405<h5 id="per-developer-aws-cost-attribution">

406 개발자별 AWS 비용 기인

407</h5>

408

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

410

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

412

413```yaml theme={null}

414upstreams:

415 - provider: bedrock

416 region: us-east-1

417 auth: {} # the gateway's own role: it only calls STS

418 assume_role:

419 role_arn: arn:aws:iam::123456789012:role/claude-gateway-bedrock-user

420 session_name: email # or sub

421```

422

423`session_name`은 어느 검증된 클레임이 AWS `RoleSessionName`이 되는지를 선택합니다: `email` 또는 `sub`. 게이트웨이는 ASCII 문자, 숫자 및 `_+,.@-` 이외의 모든 문자를 UTF-8 바이트당 `=XX` 16진수로 작성하고 64자보다 긴 결과를 접두사와 해시로 단축하므로 각 개발자의 세션 이름은 유효하고 고유하게 유지됩니다. 토큰이 클레임을 포함하지 않는 개발자의 요청은 이 업스트림을 통해 전송되지 않으며 운영자 로그는 `sub`로 전환하거나 [`oidc.email_claim`](#oidc)을 설정하도록 말합니다.

424

425활성 개발자는 시간당 게이트웨이 복제본당 하나의 STS 호출이 소요되며 동시 첫 요청은 하나의 호출을 공유합니다.

426

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

428

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

345 430

346<h4 id="claude-platform-on-aws">431<h4 id="claude-platform-on-aws">

347 Claude Platform on AWS432 Claude Platform on AWS

348</h4>433</h4>

349 434

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

351 436

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

353 438

354```yaml theme={null}439```yaml theme={null}

355upstreams:440upstreams:

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

369```454```

370 455

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

372 457

373| 필드 | 필수 | 설명 |458| 필드 | 필수 | 설명 |

374| - | - | - |459| - | - | - |

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

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

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

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

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

380 465

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

382 467

383<h4 id="google-cloud-agent-platform">468<h4 id="google-cloud-agent-platform">

384 Google Cloud Agent Platform469 Google Cloud Agent Platform

385</h4>470</h4>

386 471

387동등한 클라이언트 측 설정의 경우, [Google Cloud의 Claude Code](/docs/ko/google-vertex-ai)를 참조하세요. 게이트웨이 측 업스트림:472동등한 클라이언트 측 설정의 경우 [Google Cloud의 Claude Code](/docs/ko/google-vertex-ai)를 참조하세요. 게이트웨이 측 업스트림:

388 473

389```yaml theme={null}474```yaml theme={null}

390upstreams:475upstreams:

398 # base_url: https://us-east5-aiplatform.p.googleapis.com483 # base_url: https://us-east5-aiplatform.p.googleapis.com

399```484```

400 485

401빈 `auth` 블록은 Application Default Credentials를 사용합니다: `GOOGLE_APPLICATION_CREDENTIALS`, GCE 메타데이터, 또는 GKE Workload Identity입니다. 서비스 계정 JSON 키 파일은 지원되지만 권장되지 않습니다. Workload Identity를 사용하거나 GCE 또는 Cloud Run 인스턴스에 서비스 계정을 연결합니다.486빈 `auth` 블록은 Application Default Credentials를 사용합니다: `GOOGLE_APPLICATION_CREDENTIALS`, GCE 메타데이터 또는 GKE Workload Identity. 서비스 계정 JSON 키 파일은 지원되지만 권장되지 않습니다. Workload Identity를 사용하거나 GCE 또는 Cloud Run 인스턴스에 서비스 계정을 연결합니다.

402 487

403Google Cloud의 Agent Platform에 대해 [글로벌 엔드포인트](https://cloud.google.com/vertex-ai/generative-ai/docs/learn/locations)를 사용하려면 `region: global`을 설정합니다. Google은 각 요청을 사용 가능한 지역으로 라우팅하므로, 지역별 모델 가용성을 추적할 필요가 없습니다. 특정 지역을 설정하면 모든 요청을 이에 고정합니다.488Google Cloud의 Agent Platform에 대해 [전역 엔드포인트](https://cloud.google.com/vertex-ai/generative-ai/docs/learn/locations)를 사용하려면 `region: global`을 설정합니다. Google은 각 요청을 사용 가능한 지역으로 라우팅하므로 지역별 모델 가용성을 추적하지 않습니다. 특정 지역을 설정하면 모든 요청이 이에 고정됩니다.

404 489

405| 설정 | 방법 |490| 설정 | 방법 |

406| - | - |491| - | - |

407| IAM 권한 | 게이트웨이의 서비스 계정에 프로젝트에 `roles/aiplatform.user`를 부여하거나, `aiplatform.endpoints.predict`가 있는 사용자 정의 역할을 부여합니다. Google Cloud의 Agent Platform API(`aiplatform.googleapis.com`)를 활성화합니다. |492| IAM 권한 | 게이트웨이의 서비스 계정에 프로젝트에 `roles/aiplatform.user`를 부여하거나 `aiplatform.endpoints.predict`를 사용하는 사용자 정의 역할을 부여합니다. Google Cloud의 Agent Platform API(`aiplatform.googleapis.com`)를 활성화합니다. |

408| 모델 액세스 | Model Garden에서 프로젝트에 대해 Claude 모델을 활성화합니다. 이들은 특정 지역에 게시됩니다. 지원되는 지역은 모델 카드를 확인합니다. |493| 모델 액세스 | Model Garden에서 프로젝트에 대해 Claude 모델을 활성화합니다. 이들은 특정 지역에 게시됩니다. 지원되는 지역은 모델 카드를 확인합니다. |

409| GKE(Workload Identity) | GCP 서비스 계정을 게이트웨이의 Kubernetes 서비스 계정에 바인드하고 KSA에 `iam.gke.io/gcp-service-account: claude-gateway@<proj>.iam.gserviceaccount.com`으로 주석을 답니다. `auth: {}`가 이를 선택합니다. |494| GKE(Workload Identity) | GCP 서비스 계정을 게이트웨이의 Kubernetes 서비스 계정에 바인드하고 KSA에 `iam.gke.io/gcp-service-account: claude-gateway@<proj>.iam.gserviceaccount.com`으로 주석을 답니다. `auth: {}`가 이를 선택합니다. |

410| Cloud Run / GCE | 서비스의 서비스 계정을 `roles/aiplatform.user`가 있는 것으로 설정합니다. `auth: {}`가 이를 선택합니다. |495| Cloud Run / GCE | 서비스의 서비스 계정을 `roles/aiplatform.user`를 가진 것으로 설정합니다. `auth: {}`가 이를 선택합니다. |

411| 다른 곳 | `auth: { service_account_json: /secrets/sa.json }`. JSON 키 파일로 마운트된 비밀의 경로입니다. 필드는 파일 경로를 취하고, 키 내용이 아니므로, `${file:…}` 확장이 관련되지 않습니다. |496| 다른 곳 | `auth: { service_account_json: /secrets/sa.json }`, JSON 키 파일로 마운트된 비밀의 경로입니다. 필드는 키 콘텐츠가 아닌 파일 경로를 사용하므로 `${file:…}` 확장이 관련되지 않습니다. |

412 497

413<h4 id="microsoft-foundry">498<h4 id="microsoft-foundry">

414 Microsoft Foundry499 Microsoft Foundry

415</h4>500</h4>

416 501

417클라이언트 측 Microsoft Foundry 배포의 경우, [Microsoft Foundry의 Claude Code](/docs/ko/microsoft-foundry)를 참조하세요. 게이트웨이 측 업스트림:502클라이언트 측 Microsoft Foundry 배포의 경우 [Microsoft Foundry의 Claude Code](/docs/ko/microsoft-foundry)를 참조하세요. 게이트웨이 측 업스트림:

418 503

419```yaml theme={null}504```yaml theme={null}

420upstreams:505upstreams:

426 # api_key: ${FOUNDRY_API_KEY}511 # api_key: ${FOUNDRY_API_KEY}

427```512```

428 513

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

430 515

431| 설정 | 방법 |516| 설정 | 방법 |

432| - | - |517| - | - |

434| 배포 | Microsoft Foundry는 정규 모델 ID가 아닌 관리자 선택 배포 이름을 사용합니다. 각 정규 ID를 배포 이름으로 매핑하는 [`models:`](#models) 블록을 추가합니다. |519| 배포 | Microsoft Foundry는 정규 모델 ID가 아닌 관리자가 선택한 배포 이름을 사용합니다. 각 정규 ID를 배포 이름으로 매핑하는 [`models:`](#models) 블록을 추가합니다. |

435| AKS(워크로드 ID) | 클러스터의 OIDC 발급자와 사용자 할당 Managed Identity를 페더레이션하고 게이트웨이의 서비스 계정에 바인드합니다. `use_azure_ad: true`는 `WorkloadIdentityCredential`을 통해 이를 선택합니다. |520| AKS(워크로드 신원) | 사용자 할당 Managed Identity를 클러스터의 OIDC 발급자와 페더레이션하고 게이트웨이의 서비스 계정에 바인드합니다. `use_azure_ad: true`는 `WorkloadIdentityCredential`을 통해 이를 선택합니다. |

437| 다른 곳 | `auth: { api_key: "${FOUNDRY_API_KEY}" }`. `{ }` 내에서 `${…}`를 인용합니다. |522| 다른 곳 | `auth: { api_key: "${FOUNDRY_API_KEY}" }`. `{ }` 내에서 `${…}`를 따옴표로 묶습니다. |

438 523

439<h4 id="static-headers-on-upstream-requests">524<h4 id="static-headers-on-upstream-requests">

440 업스트림의 정적 헤더525 업스트림 요청의 정적 헤더

441</h4>526</h4>

442 527

443게이트웨이가 한 업스트림으로 보내는 요청에 고정 헤더를 추가하려면, 해당 업스트림에서 `headers:`를 설정합니다. 실행하는 프록시가 헤더로 트래픽을 라우팅하거나 속성화할 때 사용합니다.528게이트웨이가 한 업스트림으로 보내는 요청에 고정 헤더를 추가하려면 해당 업스트림에 `headers:`를 설정합니다. 실행하는 프록시가 헤더별로 트래픽을 라우팅하거나 기인할 때 사용합니다.

444 529

445`headers:`는 게이트웨이 서버에서 Claude Code v2.1.277 이상이 필요합니다. 이전 게이트웨이는 키를 찾으면 시작을 거부합니다. 키를 추가하기 전에 모든 복제본을 업그레이드하고, 이전 버전으로 롤백하기 전에 키를 제거합니다.530`headers:`는 게이트웨이 서버에서 Claude Code v2.1.277 이상이 필요합니다. 이전 게이트웨이는 키를 찾으면 시작을 거부합니다. 키를 추가하기 전에 모든 복제본을 업그레이드하고 이전 버전으로 롤백하기 전에 키를 제거합니다.

446 531

447헤더는 `base_url`이 이름을 지정하는 서버로 이동하거나, `base_url`이 설정 해제되어 있을 때 공급자의 자체 엔드포인트로 이동합니다. 공급자는 프록시가 제거하지 않는 한 이들도 받습니다.532헤더는 `base_url`이 이름을 지정하는 서버 또는 `base_url`이 설정되지 않으면 공급자의 자체 엔드포인트로 이동합니다. 공급자는 프록시가 제거하지 않으면 이를 받습니다.

448 533

449이 예제는 `upstream-proxy.internal.example.com`의 프록시를 통해 `provider: vertex` 업스트림에 도달합니다. 프록시가 읽는 `x-source` 헤더를 설정하고, `PROXY_TOKEN` 환경 변수의 토큰을 `x-proxy-token`으로 보냅니다:534이 예제는 `upstream-proxy.internal.example.com`의 프록시를 통해 `provider: vertex` 업스트림에 도달합니다. 프록시가 읽는 `x-source` 헤더를 설정하고 `PROXY_TOKEN` 환경 변수의 토큰을 `x-proxy-token`으로 보냅니다:

450 535

451```yaml theme={null}536```yaml theme={null}

452upstreams:537upstreams:

460 x-proxy-token: ${PROXY_TOKEN}545 x-proxy-token: ${PROXY_TOKEN}

461```546```

462 547

463값은 양쪽 끝에 공백이 없는 인쇄 가능한 ASCII 텍스트입니다. 숫자, `true`, 또는 `false`를 인용하여 YAML이 이를 텍스트로 읽도록 합니다.548값은 양쪽 끝에 공백이 없는 인쇄 가능한 ASCII 텍스트입니다. 숫자, `true` 또는 `false`를 따옴표로 묶어 YAML이 이를 텍스트로 읽도록 합니다.

464 549

465비밀을 구성 파일에서 벗어나도록 유지하려면, [비밀 확장](#secret-expansion)을 사용하여 `${VAR}`로 환경 변수에서 또는 `${file:/path}`로 파일에서 값을 로드합니다. 빈 값으로 해석되는 `${VAR}`은 게이트웨이가 시작되는 것을 중지합니다.550비밀을 구성 파일에서 벗어나게 하려면 [비밀 확장](#secret-expansion)을 사용하여 `${VAR}`을 사용하는 환경 변수 또는 `${file:/path}`를 사용하는 파일에서 값을 로드합니다. 빈 값으로 해석되는 `${VAR}`은 게이트웨이가 시작되지 않도록 중지합니다.

466 551

467`headers:`는 모든 공급자에서 작동하며, 각 업스트림은 자신의 것만 보냅니다.552`headers:`는 모든 공급자에서 작동하고 각 업스트림은 자신의 것만 보냅니다.

468 553

469게이트웨이가 업스트림으로 보내는 모든 요청이 이들을 전달하지는 않습니다:554게이트웨이가 업스트림으로 보내는 모든 요청이 이를 전달하는 것은 아닙니다:

470 555

472| - | - |557| - | - |

473| `/v1/messages`, 스트리밍 또는 아님, 및 `/v1/messages/count_tokens` | 예 |558| `/v1/messages`, 스트리밍 또는 아니오, 및 `/v1/messages/count_tokens` | 예 |

475| 클라이언트가 포기한 요청에 대한 Amazon Bedrock의 `CountTokens` 호출 | 아니오 |560| 클라이언트가 포기한 요청에 대한 Amazon Bedrock의 `CountTokens` 호출 | 아니오 |

476| Workload Identity Federation 토큰 교환 | 아니오 |561| Workload Identity Federation 토큰 교환 | 아니오 |

477 562

478AWS SigV4로 요청에 서명하는 Amazon Bedrock 또는 Claude Platform on AWS 업스트림에서, 이 헤더들은 서명의 일부이므로, 프록시는 이들을 변경되지 않은 상태로 통과시켜야 합니다.563Amazon Bedrock 또는 Claude Platform on AWS 업스트림에서 AWS SigV4로 요청에 서명할 때 이 헤더는 서명의 일부이므로 프록시는 이를 변경되지 않은 상태로 전달해야 합니다.

479 564

480게이트웨이가 예약한 이름을 사용하면, 시작을 거부하고 시작 오류가 헤더의 이름을 지정합니다. 예약된 이름은 다음을 포함합니다:565게이트웨이가 예약한 이름을 사용하면 시작을 거부하고 시작 오류가 헤더의 이름을 지정합니다. 예약된 이름은 다음을 포함합니다:

481 566

482* `authorization` 및 `x-api-key`567* `authorization` 및 `x-api-key`

483* `host`, `content-type`, 및 `user-agent`568* `host`, `content-type` 및 `user-agent`

484* `anthropic-`, `x-goog-`, `x-amz-`, 또는 `x-amzn-`으로 시작하는 모든 이름569* `anthropic-`, `x-goog-`, `x-amz-` 또는 `x-amzn-`으로 시작하는 모든 이름

485 570

486<h4 id="multiple-upstreams">571<h4 id="multiple-upstreams">

487 여러 업스트림572 여러 업스트림

488</h4>573</h4>

489 574

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

491 576

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

493 578

494`429`는 업스트림별 용량이므로, 프로비저닝된 처리량(PT) 소진은 온디맨드로 장애 조치합니다. 업스트림에서 [`forward_user_identity: true`](#per-user-identity-headers-for-a-proxy-you-run)를 설정하면, 개발자의 이메일을 전달한 요청에 대한 `429`는 사용자별 거부이고 장애 조치하지 않습니다.579`429`는 업스트림별 용량이므로 프로비저닝된 처리량(PT) 소진은 온디맨드로 장애 조치합니다. 업스트림에 [`forward_user_identity: true`](#per-user-identity-headers-for-a-proxy-you-run)를 설정하면 개발자의 이메일을 전달한 요청에 대한 `429`는 사용자별 거부이고 장애 조치하지 않습니다.

495 580

496모든 요청은 첫 번째 업스트림에서 시작합니다. 요청은 앞의 모든 업스트림이 실패했거나 요청된 모델을 제공하지 않을 때만 나중 업스트림에 도달합니다.581모든 요청은 첫 번째 업스트림에서 시작합니다. 요청은 앞의 모든 업스트림이 실패했거나 요청된 모델을 제공하지 않을 때만 나중 업스트림에 도달합니다.

497 582

498게이트웨이는 실패한 업스트림의 기록을 유지하지 않으므로, 업스트림이 다운되는 동안, 이에 도달하는 모든 요청은 여전히 이를 시도하고 실패할 때까지 기다립니다.583게이트웨이는 실패한 업스트림의 기록을 유지하지 않으므로 업스트림이 다운되는 동안 이에 도달하는 모든 요청은 여전히 이를 시도하고 실패할 때까지 기다린 후 계속합니다.

499 584

500Anthropic API 업스트림의 경우, [`timeouts.upstream_ttfb_ms`](#http-tuning)는 다운된 업스트림에서의 대기를 제한합니다. 이 설정은 다른 공급자에게 적용되지 않으며, 게이트웨이는 업스트림이 응답하기 시작할 때까지 최대 1시간을 기다립니다.585Anthropic API 업스트림의 경우 [`timeouts.upstream_ttfb_ms`](#http-tuning)는 다운된 업스트림에서의 대기를 제한합니다. 이 설정은 다른 공급자에게 적용되지 않습니다. 게이트웨이는 업스트림이 응답을 시작할 때까지 최대 1시간을 기다립니다.

501 586

502`404`는 업스트림별 모델 가용성이므로, 모델을 활성화하지 않은 업스트림은 이를 제공하는 나중 업스트림을 차단하지 않습니다. 요청된 모델을 해석할 수 없는 업스트림은 네트워크 왕복 없이 건너뜁니다.587`404`는 업스트림별 모델 가용성이므로 모델을 활성화하지 않은 업스트림은 이를 제공하는 나중 업스트림을 차단하지 않습니다. 요청된 모델을 해석할 수 없는 업스트림은 네트워크 왕복 없이 건너뜁니다.

503 588

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

505 590

506```yaml theme={null}591```yaml theme={null}

507upstreams:592upstreams:

515 provider: bedrock600 provider: bedrock

516 region: us-west-2601 region: us-west-2

517 auth: {}602 auth: {}

518 # Different account: a separate Bedrock allotment via assumed-role creds.603 # Different account: a separate Bedrock allotment via static keys.

519 - name: bedrock-acct2604 - name: bedrock-acct2

520 provider: bedrock605 provider: bedrock

521 region: us-east-1606 region: us-east-1

541 626

542| 레버 | 방법 |627| 레버 | 방법 |

543| - | - |628| - | - |

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

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

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

549 634

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

551 636

552CLI는 주어진 요청을 제공하는 업스트림과 무관하게 게이트웨이에 동일한 기능 게이팅을 적용하므로, 장애 조치는 업스트림이 거부할 본문 필드를 보내지 않습니다.637CLI는 요청을 제공하는 업스트림과 무관하게 게이트웨이에 동일한 기능 게이팅을 적용하므로 장애 조치는 업스트림이 거부할 본문 필드를 보내지 않습니다.

553 638

554<h2 id="optional-sections">639<h2 id="optional-sections">

555 선택적 섹션640 선택적 섹션

563 648

564```yaml theme={null}649```yaml theme={null}

565admin:650admin:

566 # Named static API keys for the admin endpoints, sent as x-api-key.651 # 관리자 엔드포인트용 명명된 정적 API 키, x-api-key로 전송됩니다.

567 # The id appears in the audit log as admin-key:<id> so each key is652 # id는 감사 로그에 admin-key:<id>로 나타나므로 각 키는

568 # attributable. Array for rotation: add the new key, roll clients,653 # 추적 가능합니다. 회전을 위한 배열: 새 키를 추가하고,

569 # remove the old.654 # 클라이언트를 롤링한 후 이전 키를 제거합니다.

570 write_keys:655 write_keys:

571 - { id: terraform, key: "${GATEWAY_ADMIN_WRITE_KEY_TF}" }656 - { id: terraform, key: "${GATEWAY_ADMIN_WRITE_KEY_TF}" }

572 - { id: ci, key: "${GATEWAY_ADMIN_WRITE_KEY_CI}" }657 - { id: ci, key: "${GATEWAY_ADMIN_WRITE_KEY_CI}" }

573 read_keys:658 read_keys:

574 - { id: reporting, key: "${GATEWAY_ADMIN_READ_KEY}" }659 - { id: reporting, key: "${GATEWAY_ADMIN_READ_KEY}" }

575 # IdP groups granted full admin via the normal gateway JWT (no API key).660 # 일반 게이트웨이 JWT를 통해 전체 관리자 권한이 부여된 IdP 그룹(API 키 없음).

576 admin_groups: [platform-finops]661 admin_groups: [platform-finops]

577 blocked_message: request an increase at https://go.example.com/claude-limits662 blocked_message: request an increase at https://go.example.com/claude-limits

578```663```

580| 필드 | 필수 | 설명 |665| 필드 | 필수 | 설명 |

581| - | - | - |666| - | - | - |

582| `write_keys` | 아니요 | `{id, key}` 배열입니다. 이 중 하나와 일치하는 `x-api-key`는 지출 한도를 나열, 설정 및 삭제할 수 있습니다. 키 값은 최소 32자 이상이어야 하며, `id`는 `read_keys`와 `write_keys` 전체에서 고유해야 합니다. |667| `write_keys` | 아니요 | `{id, key}` 배열입니다. 이 중 하나와 일치하는 `x-api-key`는 지출 한도를 나열, 설정 및 삭제할 수 있습니다. 키 값은 최소 32자 이상이어야 하며, `id`는 `read_keys`와 `write_keys` 전체에서 고유해야 합니다. |

583| `read_keys` | 아니요 | `{id, key}` 배열입니다. 읽기 전용: 상한 나열, ID로 하나 가져오기, [`/effective`](/docs/ko/claude-apps-gateway-spend-limits#%2Feffective) 및 [`/audit`](/docs/ko/claude-apps-gateway-spend-limits#%2Faudit) 읽기를 포함한 모든 `GET` 엔드포인트입니다. |668| `read_keys` | 아니요 | `{id, key}` 배열입니다. 읽기 전용: 상한 나열, ID별 하나 가져오기, [`/effective`](/docs/ko/claude-apps-gateway-spend-limits#%2Feffective) 및 [`/audit`](/docs/ko/claude-apps-gateway-spend-limits#%2Faudit) 읽기를 포함한 모든 `GET` 엔드포인트입니다. |

584| `admin_groups` | 아니요 | IdP 그룹 이름입니다. `groups` 클레임이 이 중 하나를 포함하는 gateway JWT는 전체 관리자 액세스(읽기 및 쓰기)를 가지며 `oidc:<sub>`로 감사됩니다. 인간 관리자에게는 이를 사용하고, 머신에는 API 키를 사용하세요. 이 목록의 빈 항목은 부팅 시 gateway를 중지합니다. [gateway 부팅 시 중지되는 Matcher 값](#matcher-values-that-stop-the-gateway-at-boot)을 참조하세요. |669| `admin_groups` | 아니요 | IdP 그룹 이름입니다. `groups` 클레임에 이 중 하나가 포함된 게이트웨이 JWT는 전체 관리자 액세스(읽기 및 쓰기)를 가지며 `oidc:<sub>`로 감사됩니다. 인간 관리자에게는 이를 사용하고, 머신에는 API 키를 사용하세요. 이 목록의 빈 항목은 부팅 시 게이트웨이를 중지합니다. [게이트웨이 부팅 시 중지되는 매처 값](#matcher-values-that-stop-the-gateway-at-boot)을 참조하세요. |

585| `blocked_message` | 아니요 | 차단된 개발자가 보는 `429 billing_error`에 그대로 추가됩니다. URL이나 Slack 채널과 같은 전체 지시사항을 작성하세요. 설정하지 않으면 gateway는 기본 메시지만 보냅니다. [강제 작동 방식](/docs/ko/claude-apps-gateway-spend-limits#how-enforcement-works)을 참조하세요. |670| `blocked_message` | 아니요 | 차단된 개발자가 보는 `429 billing_error`에 그대로 추가됩니다. URL이나 Slack 채널과 같은 전체 지시사항을 작성하세요. 설정하지 않으면 게이트웨이는 기본 메시지만 전송합니다. [강제 작동 방식](/docs/ko/claude-apps-gateway-spend-limits#how-enforcement-works)을 참조하세요. |

586| `audit_retention_days` | 아니요 | 기본값 `365`입니다. 더 오래된 `admin_audit` 행은 정리됩니다. |671| `audit_retention_days` | 아니요 | 기본값 `365`입니다. 더 오래된 `admin_audit` 행은 정리됩니다. |

587| `spend_retention_months` | 아니요 | 기본값 `13`입니다. 이보다 오래된 `spend` 카운터 행은 정리됩니다. 기본값은 연간 비교 보고를 위해 전체 연도와 현재 부분 월을 유지합니다. |672| `spend_retention_months` | 아니요 | 기본값 `13`입니다. 이보다 오래된 `spend` 카운터 행은 정리됩니다. 기본값은 연간 비교 보고를 위해 전체 연도와 현재 부분 월을 유지합니다. |

588| `identity_retention_days` | 아니요 | 기본값 `90`입니다. 각 개발자의 이메일, 표시 이름 및 그룹(PII)을 보유하는 `principal_emails` 행의 마지막 확인 TTL입니다. 의도적으로 지출 보존보다 짧아서 프로비저닝 해제된 ID가 익명 지출 카운터가 남아있는 동안 만료됩니다. |673| `identity_retention_days` | 아니요 | 기본값 `90`입니다. `principal_emails` 행의 마지막 확인 TTL로, 각 개발자의 이메일, 표시 이름 및 그룹(PII)을 보유합니다. 의도적으로 지출 보존보다 짧아서 프로비저닝 해제된 ID가 만료되는 동안 익명 지출 카운터는 유지됩니다. |

589| `group_limit_mode` | 아니요 | `min`(기본값) 또는 `max`입니다. 개발자가 상한이 있는 여러 그룹에 속할 때, `min`은 가장 제한적인 것을 강제하고 `max`는 가장 제한적이지 않은 것을 강제합니다. 강제 및 `/effective` 모두에서 사용됩니다. |674| `group_limit_mode` | 아니요 | `min`(기본값) 또는 `max`입니다. 개발자가 상한이 있는 여러 그룹에 속할 때, `min`은 가장 제한적인 것을 강제하고 `max`는 가장 제한적이지 않은 것을 강제합니다. 강제 및 `/effective` 모두에서 사용됩니다. |

590 675

591<h3 id="enforcement">676<h3 id="enforcement">

596 681

597| 필드 | 필수 | 설명 |682| 필드 | 필수 | 설명 |

598| - | - | - |683| - | - | - |

599| `fail_closed_on_error` | 아니요 | 기본값 `false`입니다. Postgres 중단 시 지출 강제는 열린 상태로 실패하므로 추론이 계속 작동합니다. `true`로 설정하여 닫힌 상태로 실패: 초과 용량 개발자는 차단되지만, 저장소에 도달할 수 없으면 모든 사람이 차단됩니다. [`admin:`](#admin) 블록이 필요합니다. 지출 강제는 `admin`이 구성될 때만 실행되며, 이를 `true`로 설정하면 gateway는 시작을 거부합니다. |684| `fail_closed_on_error` | 아니요 | 기본값 `false`입니다. 지출 강제는 Postgres 중단 시 열린 상태로 실패하므로 추론이 계속 작동합니다. `true`로 설정하여 닫힌 상태로 실패: 초과 용량 개발자는 차단되지만, 저장소에 도달할 수 없으면 모두가 차단됩니다. [`admin:`](#admin) 블록이 필요합니다. 지출 강제는 `admin`이 구성될 때만 실행되며, 이를 `true`로 설정하지 않으면 게이트웨이는 시작을 거부합니다. |

600 685

601<h3 id="pricing">686<h3 id="pricing">

602 `pricing`687 `pricing`

603</h3>688</h3>

604 689

605`pricing` 블록은 지출 미터에 USD 정가 대신 청구할 금액을 알려주므로 상한과 [`/effective`](/docs/ko/claude-apps-gateway-spend-limits#%2Feffective)는 계약 요금을 반영합니다. 금액은 USD로 유지되며 청구서가 아닌 추정치입니다. 두 가지 전제 조건:690`pricing` 블록은 지출 미터에 USD 정가 대신 청구할 금액을 알려주므로 상한과 [`/effective`](/docs/ko/claude-apps-gateway-spend-limits#%2Feffective)는 계약 요금을 반영합니다. 금액은 USD로 유지되며 청구서가 아닌 추정치입니다. 두 가지 전제 조건이 있습니다:

606 691

607* gateway 서버의 Claude Code v2.1.227 이상입니다. 이전 버전은 부팅 시 알 수 없는 키를 거부합니다.692* 게이트웨이 서버의 Claude Code v2.1.227 이상. 이전 버전은 부팅 시 알 수 없는 키를 거부합니다.

608* [`admin:`](#admin) 블록 또는 v2.1.268 이상에서 최소 하나의 정책이 있는 [`managed:`](#managed) 블록입니다. gateway는 `pricing`이 설정되었지만 두 블록 모두 없으면 시작을 거부합니다.693* [`admin:`](#admin) 블록 또는 v2.1.268 이상에서 최소 하나의 정책이 있는 [`managed:`](#managed) 블록입니다. 게이트웨이는 `pricing`이 설정되었지만 두 블록 모두 없으면 시작을 거부합니다. 아무것도 읽지 않기 때문입니다.

609 694

610```yaml theme={null}695```yaml theme={null}

611pricing:696pricing:

621 706

622| 필드 | 필수 | 설명 |707| 필드 | 필수 | 설명 |

623| - | - | - |708| - | - | - |

624| `multiplier` | 아니요 | 기본값 `1`입니다. 미터는 정가 또는 재정의 여부에 관계없이 모든 미터링된 금액에 이를 곱하므로 `0.85`는 가격의 85%를 청구합니다. 0보다 크고 최대 10이어야 하며, 1 이상의 값은 [가격 인상](#mark-prices-up)입니다. |709| `multiplier` | 아니요 | 기본값 `1`입니다. 미터는 정가 또는 재정의 여부에 관계없이 모든 계량 금액에 이를 곱하므로 `0.85`는 가격의 85%를 청구합니다. 0보다 크고 최대 10이어야 하며, 1 이상의 값은 [마크업](#mark-prices-up)입니다. |

625| `overrides` | 아니요 | 백만 토큰당 USD의 `{upstream, model, input, output, cache_read, cache_write}` 행입니다. 네 가지 요금 모두 필수입니다. 각각 0보다 크고 최대 10000이어야 합니다. |710| `overrides` | 아니요 | 백만 토큰당 USD의 `{upstream, model, input, output, cache_read, cache_write}` 행입니다. 네 가지 요금 모두 필수입니다. 각각 0보다 크고 최대 10000이어야 합니다. |

626 711

627미터가 재정의 행과 일치하는 방식:712미터가 재정의 행과 일치하는 방식:

628 713

629* 행은 `upstream`(즉, [`upstreams[].name`](#upstreams))이 `model`에 대해 제공하는 요청의 정가를 대체합니다. 여기에는 더 높은 [빠른 모드](/docs/ko/fast-mode#understand-the-cost-tradeoff) 요금이 포함되므로 빠른 요청과 표준 요청은 동일한 네 가지 요금으로 미터링됩니다.714* 행은 `upstream`(즉, [`upstreams[].name`](#upstreams))이 `model`에 대해 제공하는 요청의 정가를 대체합니다. 여기에는 더 높은 [빠른 모드](/docs/ko/fast-mode#understand-the-cost-tradeoff) 요금이 포함되므로 빠른 요청과 표준 요청은 동일한 네 가지 요금으로 계량됩니다.

630* `claude-sonnet-4-6`과 같은 기본 제공 ID는 [`models[].id`](#models)처럼 일치하며, 미터가 해당 모델로 가격을 책정하는 모든 날짜 형식, 지역 Amazon Bedrock 형식 또는 Google Cloud의 Agent Platform 형식을 포함합니다. 다른 문자열(예: 별칭 또는 추론 프로필 ARN)은 클라이언트가 보낸 ID 또는 upstream으로 보낸 문자열과 대소문자를 구분하지 않고 일치합니다.715* `claude-sonnet-4-6`과 같은 기본 제공 ID는 [`models[].id`](#models)처럼 일치하며, 미터가 해당 모델로 가격을 책정하는 모든 날짜 형식, 지역 Amazon Bedrock 형식 또는 Google Cloud의 Agent Platform 형식을 포함합니다. 별칭이나 추론 프로필 ARN과 같은 다른 문자열은 클라이언트가 보낸 ID 또는 업스트림으로 보낸 문자열과 대소문자를 구분하지 않고 일치합니다.

631* 행이 겹칠 경우, 미터는 첫 번째 행이 아닌 가장 구체적인 행을 선택합니다. upstream으로 보낸 정확한 모델 문자열인 행, 그 다음 클라이언트가 보낸 정확한 ID와 일치하는 행, 그 다음 기본 제공 모델을 명명하는 행입니다.716* 행이 겹칠 경우, 미터는 첫 번째 행이 아닌 가장 구체적인 행을 선택합니다: 업스트림으로 보낸 정확한 모델 문자열인 행, 그 다음 클라이언트가 보낸 정확한 ID와 일치하는 행, 그 다음 기본 제공 모델을 명명하는 행입니다.

632* 알 수 없는 upstream 이름은 부팅을 실패하게 하며, 하나의 upstream에 대해 동일한 모델을 명명하는 두 행도 마찬가지입니다(기본 제공 모델의 두 가지 철자 포함). gateway는 부팅 시 요청 가능한 모델이 사용할 수 없는 행에 대해 경고합니다.717* 알 수 없는 업스트림 이름은 부팅을 실패하게 하며, 하나의 업스트림에 대해 동일한 모델을 명명하는 두 행도 마찬가지입니다(기본 제공 모델의 두 가지 철자 포함). 게이트웨이는 부팅 시 요청 가능한 모델이 사용할 수 없는 행에 대해 경고합니다.

633* 웹 검색 요청은 \$0.01 정가로 유지됩니다. 승수는 여전히 이에 적용됩니다.718* 웹 검색 요청은 \$0.01 정가로 유지됩니다. 승수는 여전히 이에 적용됩니다.

634 719

635지역별 요금의 경우, 각 지역에 자체 명명된 upstream을 제공하고 upstream당 하나의 행을 제공하세요.720지역별 요금의 경우, 각 지역에 자체 명명된 업스트림을 제공하고 업스트림당 하나의 행을 제공합니다.

636 721

637<h4 id="mark-prices-up">722<h4 id="mark-prices-up">

638 가격 인상723 가격 인상

639</h4>724</h4>

640 725

641gateway 서버의 v2.1.271 이상에서는 `multiplier`를 1 이상 10까지 설정하여 공급자가 청구하는 것보다 더 많이 미터링할 수 있습니다(예: 내부 청구 요금). 이 예제는 모든 요청을 가격의 120%로 미터링합니다:726게이트웨이 서버의 v2.1.271 이상에서는 `multiplier`를 1 이상 10까지 설정하여 공급자가 청구하는 것보다 더 많이 계량할 수 있습니다(예: 내부 청구 요금). 이 예제는 모든 요청을 가격의 120%로 계량합니다:

642 727

643```yaml theme={null}728```yaml theme={null}

644pricing:729pricing:

645 multiplier: 1.2730 multiplier: 1.2

646```731```

647 732

648[`admin:`](#admin) 블록이 있으면 인상은 지출 한도에도 적용됩니다. 미터는 가격의 120%를 계산하므로 개발자는 상한에 더 빨리 도달합니다. gateway는 부팅 시 그렇다고 말하는 경고를 기록합니다.733[`admin:`](#admin) 블록이 있으면 마크업이 지출 한도에도 적용됩니다. 미터는 가격의 120%를 계산하므로 개발자는 상한에 더 빨리 도달합니다. 게이트웨이는 부팅 시 그렇다고 말하는 경고를 기록합니다.

649 734

650승수는 upstream 공급자가 요청에 대해 청구하는 금액을 변경하지 않습니다.735승수는 업스트림 공급자가 요청에 청구하는 금액을 변경하지 않습니다.

651 736

652gateway가 [서명된 클라이언트에 요금을 보내는](#send-the-rates-to-signed-in-clients) 경우, 개발자는 인상을 보기 위해 Claude Code v2.1.271 이상이 필요합니다. 이전 클라이언트는 1 이상의 `multiplier`를 무시하고 이 없이 비용을 표시합니다.737게이트웨이가 [서명된 클라이언트에 요금을 보내는](#send-the-rates-to-signed-in-clients) 경우, 개발자는 마크업을 보기 위해 Claude Code v2.1.271 이상이 필요합니다. 이전 클라이언트는 1 이상의 `multiplier`를 무시하고 비용을 표시하지 않습니다.

653 738

654v2.1.271보다 이전인 gateway 서버는 1 이상의 `multiplier`를 설정하면 시작을 거부합니다.739v2.1.271보다 이전인 게이트웨이 서버는 `multiplier`를 1 이상으로 설정하면 시작을 거부합니다.

655 740

656<h4 id="send-the-rates-to-signed-in-clients">741<h4 id="send-the-rates-to-signed-in-clients">

657 서명된 클라이언트에 요금 보내기742 서명된 클라이언트에 요금 전송

658</h4>743</h4>

659 744

660gateway 서버의 v2.1.268 이상에서는 gateway가 `pricing`의 요금을 제공하는 [`managed`](#managed) 정책에 [`modelPricing`](/docs/ko/settings-reference#modelpricing) 관리 설정으로 넣습니다. 정책과 일치하는 개발자는 `/usage`, 상태 줄 및 OpenTelemetry에서 각 모델 ID를 제공하는 첫 번째 upstream의 `pricing` 요금을 봅니다. 정책과 일치하지 않는 개발자는 관리 설정을 받지 않으므로 해당 수치는 정가로 유지됩니다. 클라이언트는 Claude Code v2.1.242 이상에서 설정을 적용합니다.745게이트웨이 서버의 v2.1.268 이상에서는 게이트웨이가 `pricing`의 요금을 제공하는 [`managed`](#managed) 정책에 [`modelPricing`](/docs/ko/settings-reference#modelpricing) 관리 설정으로 추가합니다. 정책과 일치하는 개발자는 `/usage`, 상태 줄 및 OpenTelemetry에서 각 모델 ID를 제공하는 첫 번째 업스트림의 `pricing` 요금을 봅니다. 정책과 일치하지 않는 개발자는 관리 설정을 받지 않으므로 수치는 정가로 유지됩니다. 클라이언트는 Claude Code v2.1.242 이상에서 설정을 적용합니다.

661 746

662* gateway가 추가하는 것: 정책의 `cli` 블록이 이미 `modelPricing`을 설정하지 않으면, gateway는 `multiplier`와 클라이언트가 요청할 수 있는 모든 모델 ID에 대해 해당 ID를 제공하는 첫 번째 upstream의 재정의 행을 추가합니다. 장애 조치 upstream만 청구하는 요금은 gateway에 유지됩니다.747* 게이트웨이가 추가하는 것: 정책의 `cli` 블록이 이미 `modelPricing`을 설정하지 않으면, 게이트웨이는 `multiplier`와 클라이언트가 요청할 수 있는 모든 모델 ID에 대해 해당 ID를 제공하는 첫 번째 업스트림의 재정의 행을 추가합니다. 장애 조치 업스트림만 청구하는 요금은 게이트웨이에 유지됩니다.

663* 하나의 정책 제외: 정책의 `cli` 블록에서 `modelPricing`을 `{}`로 설정하면, 해당 개발자는 정가로 유지됩니다.748* 하나의 정책을 제외: 정책의 `cli` 블록에서 `modelPricing`을 `{}`로 설정하면, 해당 개발자는 정가로 유지됩니다.

664* 정책의 자체 요금 유지: `cli` 블록이 자체 `multiplier` 또는 `overrides`로 `modelPricing`을 설정하는 정책은 해당 `modelPricing`을 유지하며, gateway는 자체 요금을 추가하지 않습니다.749* 정책의 자체 요금 유지: `cli` 블록이 자체 `multiplier` 또는 `overrides`로 `modelPricing`을 설정하는 정책은 해당 `modelPricing`을 전체적으로 유지하며, 게이트웨이는 자체 요금을 추가하지 않습니다.

665 750

666<h3 id="models">751<h3 id="models">

667 `models`752 `models`

668</h3>753</h3>

669 754

670`models` 블록은 선택적 관리자 큐레이션 모델 목록이며, `/v1/models`에서 제공되고 upstream당 모델 ID를 변환하는 데 사용됩니다. 미국 이외의 Amazon Bedrock 지역, Amazon Bedrock 프로비저닝된 처리량 ARN 및 Microsoft Foundry 배포 이름에 필수입니다.755`models` 블록은 선택적 관리자 큐레이션 모델 목록으로, `/v1/models`에서 제공되며 업스트림별 모델 ID를 변환하는 데 사용됩니다. 미국 이외의 Amazon Bedrock 지역, Amazon Bedrock 프로비저닝된 처리량 ARN 및 Microsoft Foundry 배포 이름에 필수입니다.

671 756

672```yaml theme={null}757```yaml theme={null}

673auto_include_builtin_models: true # false: expose only the list below758auto_include_builtin_models: true # false: 아래 목록만 노출

674models:759models:

675 - id: claude-opus-4-8760 - id: claude-opus-4-8

676 label: Claude Opus 4.8761 label: Claude Opus 4.8

677 # description: optional text shown in clients that surface it762 # description: 선택적 텍스트, 이를 표시하는 클라이언트에 표시됨

678 upstream_model:763 upstream_model:

679 anthropic: claude-opus-4-8764 anthropic: claude-opus-4-8

680 bedrock: us.anthropic.claude-opus-4-8 # or an inference-profile ARN765 bedrock: us.anthropic.claude-opus-4-8 # 또는 추론 프로필 ARN

681 foundry: your-opus-deployment-name766 foundry: your-opus-deployment-name

682```767```

683 768

684`upstream_model` 아래의 각 키는 구성된 upstream의 `name`과 일치해야 하며, 기본값은 공급자 이름입니다. upstream과 일치하지 않는 키는 부팅을 실패하게 하므로 사용하지 않는 공급자의 줄은 생략하세요.769`upstream_model` 아래의 각 키는 구성된 업스트림의 `name`과 일치해야 하며, 기본값은 공급자 이름입니다. 업스트림과 일치하지 않는 키는 부팅을 실패하게 하므로 사용하지 않는 공급자의 줄은 생략합니다.

685 770

686<h3 id="managed">771<h3 id="managed">

687 `managed`772 `managed`

688</h3>773</h3>

689 774

690`managed` 블록은 IdP 그룹 또는 이메일 도메인을 기반으로 한 역할 기반 액세스 정책을 정의합니다. 정책은 순서대로 평가되며, 첫 번째 일치가 선택된 후 `match: {}` catch-all 기본값에 병합됩니다. 이들은 ETag/304 캐싱과 함께 `GET /managed/settings`에서 사용자별로 제공됩니다.775`managed` 블록은 IdP 그룹 또는 이메일 도메인을 기반으로 하는 역할 기반 액세스 정책을 정의합니다. 정책은 순서대로 평가되며, 첫 번째 일치가 선택된 후 `match: {}` 캐치올 기본값에 병합됩니다. 이들은 ETag/304 캐싱과 함께 `GET /managed/settings`에서 사용자별로 제공됩니다.

691 776

692```yaml theme={null}777```yaml theme={null}

693managed:778managed:

694 policies:779 policies:

695 # Specific groups first.780 # 특정 그룹을 먼저 배치합니다.

696 - match: { groups: [eng-contractors] }781 - match: { groups: [eng-contractors] }

697 cli:782 cli:

698 availableModels: [claude-sonnet-4-6]783 availableModels: [claude-sonnet-4-6]

699 permissions: { deny: ["WebFetch", "WebSearch"] }784 permissions: { deny: ["WebFetch", "WebSearch"] }

700 # Default catch-all last: matches everyone who authenticated.785 # 기본 캐치올을 마지막에 배치: 인증된 모든 사용자와 일치합니다.

701 - match: {}786 - match: {}

702 cli:787 cli:

703 availableModels: [claude-opus-4-8, claude-sonnet-4-6, claude-haiku-4-5]788 availableModels: [claude-opus-4-8, claude-sonnet-4-6, claude-haiku-4-5]

704```789```

705 790

706`match: {}` catch-all은 관례상 마지막에 나열되며 기본 계층으로 취급됩니다. 다른 모든 정책은 설정하지 않은 모든 키를 catch-all에서 상속하므로 역할별 항목은 조직 기본값과 다른 것만 나열하면 됩니다. 병합 규칙은 키 유형에 따라 다릅니다:791`match: {}` 캐치올은 관례적으로 마지막에 나열되며 기본 계층으로 처리됩니다. 다른 모든 정책은 설정하지 않은 모든 키를 캐치올에서 상속하므로 역할별 항목은 조직 기본값과 다른 것만 나열하면 됩니다. 병합 규칙은 키 유형에 따라 다릅니다:

707 792

708* **허용 목록**: `availableModels` 및 `permissions.allow`입니다. 특정 정책의 목록은 기본값의 목록을 완전히 대체합니다.793* **허용 목록**: `availableModels` 및 `permissions.allow`입니다. 특정 정책의 목록은 기본값의 목록을 완전히 대체합니다.

709* **거부 목록 및 후크 배열**: `permissions.deny`, `permissions.ask`, `disabledMcpjsonServers`, `deniedMcpServers`, `blockedMarketplaces` 및 모든 `hooks` 이벤트 유형 배열입니다. 이들은 기본값과 정책의 합집합을 취하므로 조직 전체 거부 또는 감사 후크는 역할별 재정의로 실수로 삭제될 수 없습니다.794* **거부 목록 및 후크 배열**: `permissions.deny`, `permissions.ask`, `disabledMcpjsonServers`, `deniedMcpServers`, `blockedMarketplaces` 및 모든 `hooks` 이벤트 유형 배열입니다. 이들은 기본값과 정책의 합집합을 취하므로 조직 전체 거부 또는 감사 후크가 역할별 재정의에 의해 실수로 삭제될 수 없습니다.

710* **레코드 유형 키**: `env`, `modelOverrides` 및 `skillOverrides`입니다. 이들은 얕게 병합되므로 역할별 `env` 블록은 설정하는 키를 재정의하고 나머지는 기본값에서 상속합니다.795* **레코드 유형 키**: `env`, `modelOverrides` 및 `skillOverrides`입니다. 이들은 얕게 병합되므로 역할별 `env` 블록은 설정하는 키를 재정의하고 나머지는 기본값에서 상속합니다.

711 796

712`availableModels`는 `/v1/messages`에서 서버 측으로도 강제되므로 거부된 모델은 클라이언트가 보내는 것에 관계없이 `400`을 반환합니다.797`availableModels`는 `/v1/messages`에서 서버 측으로도 강제되므로 거부된 모델은 클라이언트가 보내는 것에 관계없이 `400`을 반환합니다.

713 798

714gateway는 요청을 릴레이하기 전에 `model` 값 자체를 검증하므로 잘못된 형식의 값은 upstream에 도달하지 않습니다. 두 가지 경우에 `400`으로 요청을 거부합니다:799게이트웨이는 요청을 업스트림으로 중계하기 전에 `model` 값 자체를 검증하므로 잘못된 형식의 값은 업스트림에 도달하지 않습니다. 두 가지 경우에 `400`으로 요청을 거부합니다:

715 800

716* 값이 누락되었거나 비어있을 때, gateway는 `model is required` 메시지로 요청을 거부합니다. 이 확인에는 Claude Code v2.1.228 이상을 실행하는 gateway가 필요합니다.801* 값이 누락되었거나 비어 있으면, 게이트웨이는 `model is required` 메시지로 요청을 거부합니다. 이 확인에는 Claude Code v2.1.228 이상을 실행하는 게이트웨이가 필요합니다.

717* 값이 있지만 문자열이 아닐 때, gateway는 `model must be a string` 메시지로 요청을 거부합니다. Claude Code v2.1.221 이상을 실행하는 gateway가 필요합니다.802* 값이 있지만 문자열이 아니면, 게이트웨이는 `model must be a string` 메시지로 요청을 거부합니다. Claude Code v2.1.221 이상을 실행하는 게이트웨이가 필요합니다.

718 803

719| Matcher | 동작 |804| 매처 | 동작 |

720| - | - |805| - | - |

721| `match: {}` | 모든 인증된 사용자와 일치합니다. 이 중 하나로 시작하고 나중에 위에 그룹 범위 정책을 추가하세요. |806| `match: {}` | 모든 인증된 사용자와 일치합니다. 이 중 하나로 시작하고 나중에 위에 그룹 범위 정책을 추가합니다. |

722| `match: { groups: [a, b] }` | JWT의 `groups` 클레임이 나열된 그룹 중 하나를 포함하면 일치합니다. 대소문자 구분: 그룹은 IdP의 정확한 대소문자와 일치해야 합니다. |807| `match: { groups: [a, b] }` | JWT의 `groups` 클레임에 나열된 그룹 중 하나가 포함되면 일치합니다. 대소문자 구분: 그룹은 IdP의 정확한 대소문자와 일치해야 합니다. |

723| `match: { email_domain: example.com }` | JWT의 `email` 클레임에서 마지막 `@` 뒤의 부분과 일치하며, 대소문자를 구분하지 않습니다. 정책당 하나의 도메인을 허용합니다. |808| `match: { email_domain: example.com }` | JWT의 `email` 클레임에서 마지막 `@` 뒤의 부분과 일치하며, 대소문자를 구분하지 않습니다. 정책당 하나의 도메인을 허용합니다. |

724| `match: { groups: [a], email_domain: example.com }` | 두 조건 모두 일치해야 합니다 |809| `match: { groups: [a], email_domain: example.com }` | 두 조건 모두 일치해야 합니다 |

725 810

726인증된 사용자가 정책과 일치하지 않으면 gateway의 기본값을 받으며, 이는 카탈로그의 모든 모델과 관리 설정이 없음을 의미합니다. 보장된 기본 정책을 원하면 마지막에 `match: {}` catch-all을 추가하세요.811정책과 일치하지 않는 인증된 사용자는 게이트웨이의 기본값을 받습니다. 즉, 카탈로그의 모든 모델과 관리 설정이 없습니다. 보장된 기본 정책을 원하면 마지막에 `match: {}` 캐치올을 추가합니다.

727 812

728<Note>813<Note>

729 gateway는 자체 사용자 디렉토리를 유지하지 않습니다. 사용자의 IdP 토큰에서 각 요청을 인증하여 토큰의 `groups` 클레임에서 그룹 멤버십을 읽고 이에 대해 정책을 평가합니다. 열거할 명단이 없고 사전 생성할 계정이 없으므로 SCIM 엔드포인트가 없습니다. SCIM이 동기화할 것이 없기 때문입니다.814 게이트웨이는 자체 사용자 디렉토리를 유지하지 않습니다. 사용자의 IdP 토큰에서 각 요청을 인증하여 토큰의 `groups` 클레임에서 그룹 멤버십을 읽고 이에 대해 정책을 평가합니다. 동기화할 것이 없으므로 열거할 명단이 없고, 사전 생성할 계정이 없으며, SCIM 엔드포인트도 없습니다.

730 815

731 사용자 및 그룹 수명 주기 관리를 진실의 원천인 IdP의 기본 SCIM 프로비저닝 또는 전용 ID 거버넌스 플랫폼에서 실행하세요. 거기서 관리되는 멤버십 및 프로비저닝 해제는 토큰을 통해 gateway로 자동으로 흐릅니다. Claude 계정 자체의 SCIM 프로비저닝을 원하면 이는 [Claude for Enterprise](/docs/ko/admin-setup) 기능입니다.816 사용자 및 그룹 수명 주기 관리를 진실의 원천인 IdP의 기본 SCIM 프로비저닝 또는 전용 ID 거버넌스 플랫폼에서 실행합니다. 거기서 관리되는 멤버십 및 프로비저닝 해제는 토큰을 통해 게이트웨이로 자동으로 흐릅니다. Claude 계정 자체의 SCIM 프로비저닝을 원하면 이는 [Claude for Enterprise](/docs/ko/admin-setup) 기능입니다.

732 817

733 두 가지 전파 시계가 적용됩니다:818 두 가지 전파 시계가 적용됩니다:

734 819

735 * **정책 내용**: 정책을 편집하고 재배포하면 연결된 클라이언트의 다음 관리 설정 폴에서 1시간 이내에 도달합니다([다음 시작에만 적용되는 변경](/docs/ko/server-managed-settings#fetch-and-caching-behavior) 제외).820 * **정책 내용**: 정책을 편집하고 재배포하면 연결된 클라이언트가 다음 관리 설정 폴링 시 1시간 이내에 도달합니다([다음 시작 시에만 적용되는 변경](/docs/ko/server-managed-settings#fetch-and-caching-behavior) 제외).

736 * **그룹 멤버십**: 사용자의 그룹 멤버십을 변경하면 어떤 정책이 일치하는지 변경됩니다. 이는 다음 세션 재발급, 즉 다음 자동 새로고침에서 적용되며, `session.ttl_hours`로 제한됩니다.821 * **그룹 멤버십**: 사용자의 그룹 멤버십을 변경하면 어떤 정책이 일치하는지 변경됩니다. 이는 다음 세션 재발급 시, 즉 다음 자동 새로고침 시 적용되며, `session.ttl_hours`로 제한됩니다.

737</Note>822</Note>

738 823

739<h4 id="matcher-values-that-stop-the-gateway-at-boot">824<h4 id="matcher-values-that-stop-the-gateway-at-boot">

740 gateway 부팅 시 중지되는 Matcher 값825 게이트웨이 부팅 시 중지되는 매처 값

741</h4>826</h4>

742 827

743부팅 시 gateway는 모든 정책의 `match` 블록과 [`admin_groups`](#admin) 목록을 확인합니다. 이 값 중 하나라도 필드를 명명하는 오류로 gateway를 중지합니다:828부팅 시 게이트웨이는 모든 정책의 `match` 블록과 [`admin_groups`](#admin) 목록을 확인합니다. 이 값 중 하나라도 필드를 명명하는 오류로 게이트웨이를 중지합니다:

744 829

745* 빈 `groups` 목록830* 빈 `groups` 목록

746* `groups` 또는 `admin_groups`의 빈 항목831* `groups` 또는 `admin_groups`의 빈 항목

747* 빈 `email_domain`832* 빈 `email_domain`

748* `@`, 공백 또는 쉼표를 포함하는 `email_domain`입니다. gateway는 값을 자르고 이 확인 전에 선행 `@` 하나를 제거합니다. `example.com`과 같은 하나의 베어 도메인을 작성하세요.833* `@`, 공백 또는 쉼표를 포함하는 `email_domain`입니다. 게이트웨이는 값을 자르고 이 확인 전에 선행 `@` 하나를 제거합니다. `example.com`과 같은 하나의 베어 도메인을 작성합니다.

749 834

750v2.1.232 이전에는 gateway가 이 값으로 시작했습니다. 각 값은 다음과 같은 효과를 가졌습니다:835v2.1.232 이전에는 게이트웨이가 이 값으로 시작했습니다. 각 값은 다음과 같은 효과를 가졌습니다:

751 836

752* 빈 `email_domain`: gateway는 도메인 확인을 건너뛰었으므로 빈 `email_domain`과 `groups` 목록이 없는 정책은 모든 인증된 사용자와 일치했습니다.837* 빈 `email_domain`: 게이트웨이는 도메인 확인을 건너뛰었으므로 빈 `email_domain`과 `groups` 목록이 없는 정책은 모든 인증된 사용자와 일치했습니다.

753* 빈 `groups` 목록: 정책은 아무도 일치하지 않았습니다.838* 빈 `groups` 목록: 정책은 아무도 일치하지 않았습니다.

754* `@`, 공백 또는 쉼표를 포함하는 `email_domain`: 정책은 아무도 일치하지 않았습니다.839* `@`, 공백 또는 쉼표를 포함하는 `email_domain`: 정책은 아무도 일치하지 않았습니다.

755* `groups` 또는 `admin_groups`의 빈 항목: 항목은 해당 사용자의 IdP `groups` 클레임도 빈 항목을 포함할 때만 사용자와 일치했습니다. `admin_groups`에서 해당 일치는 관리자 액세스를 부여했습니다. `admin_groups` 목록이 빈 항목을 포함하지 않으면 아무도 이 방식으로 관리자 액세스를 얻지 못했습니다.840* `groups` 또는 `admin_groups`의 빈 항목: 항목은 해당 사용자의 IdP `groups` 클레임도 빈 항목을 포함할 때만 사용자와 일치했습니다. `admin_groups`에서 해당 일치는 관리자 액세스를 부여했습니다. `admin_groups` 목록에 빈 항목이 포함되지 않으면 아무도 이 방식으로 관리자 액세스를 얻지 못했습니다.

756 841

757<h4 id="what-goes-in-cli">842<h4 id="what-goes-in-cli">

758 `cli`에 들어가는 것843 `cli`에 들어가는 것

759</h4>844</h4>

760 845

761각 `cli` 값은 완전한 Claude Code `managed-settings.json` 문서이며, MDM을 통해 배포하거나 `/etc/claude-code/managed-settings.json`에 배포할 동일한 스키마이며, 여기서는 YAML로 표현됩니다. CLI는 전달된 문서를 관리 계층에서 적용하며, 사용자 및 프로젝트 설정 위에 있고, 서버 관리 설정 대신입니다. 따라서 `policyHelper` 및 `wslInheritsWindowsSettings`와 같이 [OS 수준 정책 소스로 제한된 설정](/docs/ko/server-managed-settings#current-limitations)을 무시합니다.846각 `cli` 값은 완전한 Claude Code `managed-settings.json` 문서로, MDM을 통해 배포하거나 `/etc/claude-code/managed-settings.json`에 배포할 동일한 스키마이며, 여기서는 YAML로 표현됩니다. CLI는 전달된 문서를 관리 계층에서 적용하여 사용자 및 프로젝트 설정 위에 있으며, 서버 관리 설정 대신 사용합니다. 따라서 [`policyHelper`](/docs/ko/settings-reference#policyhelper) 및 `wslInheritsWindowsSettings`와 같이 [OS 수준 정책 소스로 제한된](/docs/ko/server-managed-settings#current-limitations) 설정을 무시합니다.

762 847

763gateway는 부팅 시 각 문서를 CLI의 설정 스키마에 대해 검증하므로 인식되지 않는 최상위 키는 모든 위반 키를 명명하는 오류로 부팅을 실패합니다. 스키마의 의도적으로 열린 부분은 여전히 임의의 값을 허용합니다. 더 새로운 클라이언트가 gateway의 스키마가 인식하지 못하는 항목을 인식할 수 있기 때문입니다. 이 열린 키에는 `env`, `pluginConfigs` 및 `permissions` 아래에 중첩된 키가 포함됩니다.848게이트웨이는 부팅 시 CLI의 설정 스키마에 대해 각 문서를 검증하므로 인식할 수 없는 최상위 키는 모든 위반 키를 명명하는 오류로 부팅을 실패하게 합니다. 의도적으로 열린 스키마 부분은 여전히 임의의 값을 허용합니다. 게이트웨이의 스키마가 인식하지 못하는 항목을 더 새로운 클라이언트가 인식할 수 있기 때문입니다. 이 열린 키에는 `env`, `pluginConfigs` 및 `permissions` 아래에 중첩된 키가 포함됩니다.

764 849

765검증은 gateway의 설치된 버전과 함께 번들된 스키마를 사용하므로, 더 새로운 Claude Code 릴리스에서 도입한 최상위 설정 키를 관리 구성에 넣으려면 먼저 gateway를 업그레이드해야 합니다. 전체 조직에 배포하기 전에 하나의 클라이언트에서 새 정책을 스모크 테스트하세요.850검증이 게이트웨이의 설치된 버전과 함께 번들된 스키마를 사용하므로, 더 새로운 Claude Code 릴리스에서 도입한 최상위 설정 키를 관리 구성에 넣으려면 먼저 게이트웨이를 업그레이드해야 합니다. 하나의 클라이언트에서 새 정책을 스모크 테스트한 후 롤아웃합니다.

766 851

767전체 키 참조는 [Claude Code 설정](/docs/ko/settings-reference#all-settings)에 있습니다. 운영자가 가장 먼저 찾는 키:852전체 키 참조는 [Claude Code 설정](/docs/ko/settings-reference#all-settings)에 있습니다. 운영자가 가장 먼저 찾는 키:

768 853

771 policies:856 policies:

772 - match: {}857 - match: {}

773 cli:858 cli:

774 # Model access (also enforced server-side at /v1/messages)859 # 모델 액세스(/v1/messages에서도 서버 측으로 강제됨)

775 availableModels: [claude-opus-4-8, claude-sonnet-4-6, claude-haiku-4-5]860 availableModels: [claude-opus-4-8, claude-sonnet-4-6, claude-haiku-4-5]

776 861

777 # Permission policy862 # 권한 정책

778 permissions:863 permissions:

779 deny:864 deny:

780 - "WebFetch"865 - "WebFetch"

781 - "Read(./.env)"866 - "Read(./.env)"

782 - "Read(./secrets/**)"867 - "Read(./secrets/**)"

783 disableBypassPermissionsMode: disable # blocks --dangerously-skip-permissions868 disableBypassPermissionsMode: disable # --dangerously-skip-permissions 차단

784 allowManagedPermissionRulesOnly: true # ignore user/project permission rules869 allowManagedPermissionRulesOnly: true # 사용자/프로젝트 권한 규칙 무시

785 870

786 # Environment pushed into the CLI process. DISABLE_UPDATES blocks871 # CLI 프로세스로 푸시된 환경입니다. DISABLE_UPDATES는 배경 및 수동 업데이트를 차단합니다.

787 # background and manual updates; DISABLE_AUTOUPDATER stops only872 # DISABLE_AUTOUPDATER는 배경 업데이트만 중지합니다.

788 # background updates.

789 env:873 env:

790 DISABLE_UPDATES: "1" # pin versions via your own distribution874 DISABLE_UPDATES: "1" # 자체 배포를 통해 버전 고정

791 875

792 # Org-wide hooks. Hook commands run on developer machines, not the876 # 조직 전체 후크입니다. 후크 명령은 게이트웨이가 아닌 개발자 머신에서 실행되므로

793 # gateway, so the path must exist on every client OS in the policy.877 # 경로는 정책의 모든 클라이언트 OS에 존재해야 합니다.

794 hooks:878 hooks:

795 PostToolUse:879 PostToolUse:

796 - matcher: "Edit|Write"880 - matcher: "Edit|Write"

800 884

801| 키 | 강제 대상 | 효과 |885| 키 | 강제 대상 | 효과 |

802| - | - | - |886| - | - | - |

804| `permissions.allow` / `.deny` | CLI | 도구 및 명령 규칙입니다. [권한](/docs/ko/permissions)을 참조하세요. |888| `permissions.allow` / `.deny` | CLI | 도구 및 명령 규칙입니다. [권한](/docs/ko/permissions)을 참조하세요. |

805| `permissions.disableBypassPermissionsMode` | CLI | [`bypassPermissions`](/docs/ko/permission-modes#skip-all-checks-with-bypasspermissions-mode) 모드(권한 프롬프트를 건너뛰는 모드)와 `--dangerously-skip-permissions` 플래그를 차단하려면 `disable`로 설정하세요. |889| `permissions.disableBypassPermissionsMode` | CLI | 권한 프롬프트를 건너뛰는 모드인 [`bypassPermissions`](/docs/ko/permission-modes#skip-all-checks-with-bypasspermissions-mode)와 `--dangerously-skip-permissions` 플래그를 차단하려면 `disable`으로 설정합니다. |

806| `allowManagedPermissionRulesOnly` | CLI | `true`일 때, 관리 설정은 권한 규칙의 유일한 설정 소스가 됩니다. [`allowManagedPermissionRulesOnly`](/docs/ko/settings-reference#allowmanagedpermissionrulesonly) 항목은 Claude Code가 무시하는 모든 소스를 나열합니다. |890| `allowManagedPermissionRulesOnly` | CLI | `true`일 때, 관리 설정은 권한 규칙의 유일한 설정 소스가 됩니다. [`allowManagedPermissionRulesOnly`](/docs/ko/settings-reference#allowmanagedpermissionrulesonly) 항목은 Claude Code가 무시하는 모든 소스를 나열합니다. |

807| `env` | CLI | CLI 프로세스에 병합된 환경 변수입니다. 원격 측정, 자동 업데이트 및 모델 이름 재정의에 사용하세요. |891| `env` | CLI | CLI 프로세스로 병합된 환경 변수입니다. 원격 측정, 자동 업데이트 및 모델 이름 재정의에 사용합니다. |

808| `hooks` | CLI | 조직 전체 [후크](/docs/ko/hooks) |892| `hooks` | CLI | 조직 전체 [후크](/docs/ko/hooks) |

809| `managedMcpServers` | CLI | 정책과 일치하는 모든 개발자에게 [제공되는](/docs/ko/managed-mcp#provide-servers-through-managed-settings) 원격 MCP 서버(`http` 및 `sse`만). [정책의 MCP 서버](#mcp-servers-in-a-policy)를 참조하세요. gateway 서버 및 클라이언트에서 Claude Code v2.1.259 이상이 필요합니다. 이전 클라이언트는 키를 무시합니다. |893| `managedMcpServers` | CLI | [모든 일치하는 개발자에게 제공되는](/docs/ko/managed-mcp#provide-servers-through-managed-settings) 원격 MCP 서버로, 자신이 추가한 서버 `http` 및 `sse`와 함께입니다. [정책의 MCP 서버](#mcp-servers-in-a-policy)를 참조하세요. 게이트웨이 서버 및 클라이언트에서 Claude Code v2.1.259 이상이 필요합니다. 이전 클라이언트는 키를 무시합니다. |

810 894

811이 설정은 네트워크를 통해 도착하므로 CLI는 아래 나열된 설정을 적용하기 전에 각 개발자에게 보안 승인 대화 상자를 표시합니다:895이 설정은 네트워크를 통해 도착하므로 CLI는 아래 나열된 설정을 적용하기 전에 각 개발자에게 보안 승인 대화 상자를 표시합니다:

812 896

814* 프록시 및 기본 URL 변수와 같이 개발자의 승인이 필요한 `env` 변수898* 프록시 및 기본 URL 변수와 같이 개발자의 승인이 필요한 `env` 변수

815* `apiKeyHelper` 및 `statusLine`과 같은 셸 실행 설정899* `apiKeyHelper` 및 `statusLine`과 같은 셸 실행 설정

816* 샌드박스 바이너리 설정 `sandbox.bwrapPath`, `sandbox.socatPath` 및 `sandbox.ripgrep`900* 샌드박스 바이너리 설정 `sandbox.bwrapPath`, `sandbox.socatPath` 및 `sandbox.ripgrep`

817* `sandbox.network.tlsTerminate` 및 프록시 포트 설정과 같이 트래픽을 가로채고, 자격 증명을 주입하거나, 격리를 약화시키는 샌드박스 설정입니다. [보안 승인 대화 상자](/docs/ko/server-managed-settings#security-approval-dialogs)는 모두 나열합니다.901* `sandbox.network.tlsTerminate` 및 프록시 포트 설정과 같이 트래픽을 가로채거나 자격 증명을 주입하거나 격리를 약화시키는 샌드박스 설정입니다. [보안 승인 대화 상자](/docs/ko/server-managed-settings#security-approval-dialogs)는 모두 나열합니다.

818 902

819[승인 메모리](/docs/ko/server-managed-settings#approval-memory)는 승인이 얼마나 오래 지속되는지와 대화 상자가 다시 나타나는 시기를 다룹니다.903[승인 메모리](/docs/ko/server-managed-settings#approval-memory)는 승인이 얼마나 오래 지속되는지와 대화 상자가 다시 나타나는 시기를 다룹니다.

820 904

821Claude Code는 모델 선택 설정 및 숫자 제한과 같이 개발자에게 승인 대화 상자를 표시하지 않고 전달된 일부 `env` 변수를 적용합니다. 다른 전달된 변수는 적용 전에 개발자의 승인이 필요할 수 있습니다. 비어있지 않은 프록시, 기본 URL 또는 `OTEL_EXPORTER_OTLP_ENDPOINT` 값은 항상 그렇습니다. 전달된 변수가 승인이 필요하면 대화 상자가 이를 명명합니다.905Claude Code는 모델 선택 설정 및 숫자 제한과 같이 개발자 승인 대화 상자를 표시하지 않고 전달된 일부 `env` 변수를 적용합니다. 다른 전달된 변수는 적용되기 전에 개발자의 승인이 필요할 수 있습니다. 비어 있지 않은 프록시, 기본 URL 또는 `OTEL_EXPORTER_OTLP_ENDPOINT` 값은 항상 그렇습니다. 전달된 변수가 승인이 필요하면 대화 상자가 이를 명명합니다.

822 906

823[환경 변수 및 승인 대화 상자](/docs/ko/server-managed-settings#environment-variables-and-the-approval-dialog)는 세부 사항과 전달된 값이 승인이 필요한지 여부를 결정하는 네 가지 개인 정보 보호 토글을 포함합니다. v2.1.218 이전에는 Claude Code가 더 적은 변수를 개발자에게 묻지 않고 적용했으므로 더 많은 전달된 변수가 대화 상자를 트리거했습니다.907[환경 변수 및 승인 대화 상자](/docs/ko/server-managed-settings#environment-variables-and-the-approval-dialog)는 세부 정보와 전달된 값이 승인이 필요한지 여부를 결정하는 네 가지 개인 정보 보호 토글을 포함합니다. v2.1.218 이전에는 Claude Code가 더 적은 변수를 개발자에게 묻지 않고 적용했으므로 더 많은 전달된 변수가 대화 상자를 트리거했습니다.

824 908

825gateway의 [원격 측정](#telemetry) 구성은 `OTEL_EXPORTER_OTLP_ENDPOINT`를 푸시하므로 `telemetry.forward_to`를 설정하면 각 대화형 클라이언트에서 대화 상자를 트리거합니다. 대화 상자는 손상되었거나 적대적인 gateway로부터 개발자의 머신을 보호하며, 개발자로부터 조직을 보호하지 않습니다.909게이트웨이의 [원격 측정](#telemetry) 구성은 `OTEL_EXPORTER_OTLP_ENDPOINT`를 푸시하므로 `telemetry.forward_to`를 설정하면 각 대화형 클라이언트에서 대화 상자를 트리거합니다. 대화 상자는 손상되었거나 적대적인 게이트웨이로부터 개발자의 머신을 보호하며, 개발자로부터 조직을 보호하지 않습니다.

826 910

827`-p` 플래그가 있는 비대화형 실행은 대화 상자를 표시할 수 없습니다. 해당 실행에 대해서만 푸시된 설정을 적용하고 이를 승인된 것으로 기록하지 않으므로 개발자의 다음 대화형 세션은 여전히 대화 상자를 표시합니다. v2.1.207 이전에는 비대화형 실행이 설정을 승인된 것으로 저장했고 나중의 대화형 세션은 이에 대한 대화 상자를 표시하지 않았습니다.911[비대화형 실행](/docs/ko/server-managed-settings#security-approval-dialogs)(예: `claude -p` 또는 Agent SDK 세션)은 대화 상자를 표시할 수 없습니다. 해당 실행에만 푸시된 설정을 적용하고 승인된 것으로 기록하지 않으므로 개발자의 다음 대화형 세션은 여전히 대화 상자를 표시합니다. v2.1.207 이전에는 비대화형 실행이 설정을 승인된 것으로 저장했고 이후 대화형 세션은 대화 상자를 표시하지 않았습니다.

828 912

829개발자가 거부하면 Claude Code는 정책을 적용하지 않고 해당 세션을 종료합니다. 새 후크 또는 대화 상자를 트리거하는 env 변수를 광범위한 정책에 푸시하면 Claude Code는 일치하는 모든 개발자에게 대화 상자를 표시합니다. 실행 중인 세션에서 다음 시간별 폴에 대화 상자를 표시하고, 그렇지 않으면 개발자의 다음 시작 시 표시합니다.913개발자가 거부하면 Claude Code는 정책을 적용하지 않고 해당 세션을 종료합니다. 새 후크 또는 대화 상자를 트리거하는 env 변수를 광범위한 정책으로 푸시하면 모든 일치하는 개발자는 대화형 세션에서 대화 상자를 봅니다. 실행 중인 대화형 세션은 다음 시간별 폴링에서 이를 표시하고, 그렇지 않으면 개발자의 다음 대화형 시작 시 나타납니다.

830 914

831`cli` 키는 이전 릴리스에서 `settings`로 명명되었습니다. 해당 철자는 여전히 별칭으로 허용되지만 새 배포는 `cli`를 사용해야 합니다.915`cli` 키는 이전 릴리스에서 `settings`로 명명되었습니다. 해당 철자는 여전히 별칭으로 허용되지만 새 배포는 `cli`를 사용해야 합니다.

832 916

834 정책의 MCP 서버918 정책의 MCP 서버

835</h4>919</h4>

836 920

837정책이 일치하는 Claude Code 클라이언트에 MCP 서버를 제공하려면 해당 정책의 `cli` 블록에서 [`managedMcpServers`](/docs/ko/managed-mcp#provide-servers-through-managed-settings)를 설정하세요. gateway 서버 및 클라이언트에서 Claude Code v2.1.259 이상이 필요합니다.921정책이 일치하는 Claude Code 클라이언트에 MCP 서버를 제공하려면 해당 정책의 `cli` 블록에서 [`managedMcpServers`](/docs/ko/managed-mcp#provide-servers-through-managed-settings)를 설정합니다. 게이트웨이 서버 및 클라이언트에서 Claude Code v2.1.259 이상이 필요합니다.

838 922

839gateway는 [Claude Code가 클라이언트에서 적용하는 동일한 규칙](/docs/ko/managed-mcp#what-an-entry-can-contain)으로 부팅 시 각 항목을 확인하며, 항목이 확인을 실패하면 gateway는 시작을 거부하고 항목을 명명합니다.923게이트웨이는 부팅 시 [Claude Code가 클라이언트에 적용하는 동일한 규칙](/docs/ko/managed-mcp#what-an-entry-can-contain)으로 각 항목을 확인하며, 항목이 확인을 실패하면 게이트웨이는 시작을 거부하고 항목을 명명합니다.

840 924

841`gateway.yaml`에 `${VAR}` 참조를 작성하면 gateway는 [비밀 확장](#secret-expansion)을 통해 부팅 시 환경에서 이를 해결하므로 일치하는 모든 클라이언트는 리터럴 값을 받고 읽을 수 있습니다. [제공된 서버에 대한 헤더 지침](/docs/ko/managed-mcp#provide-servers-through-managed-settings)은 확장된 값에 적용됩니다.925`gateway.yaml`에 `${VAR}` 참조를 작성하면 게이트웨이는 부팅 시 [비밀 확장](#secret-expansion)을 통해 환경에서 이를 해결하고 항목 확인을 실행하므로 모든 일치하는 클라이언트는 리터럴 값을 받고 읽을 수 있습니다. [제공된 서버에 대한 헤더 지침](/docs/ko/managed-mcp#provide-servers-through-managed-settings)은 확장된 값에 적용됩니다.

842 926

843gateway는 `cli` 블록에서 `.mcp.json` 철자 `mcpServers`를 거부하며, 부팅 오류는 `managedMcpServers`를 사용할 키로 명명합니다. v2.1.259 이전에는 gateway가 `cli` 블록의 모든 MCP 서버 정의를 거부했습니다.927게이트웨이는 `cli` 블록에서 `.mcp.json` 철자 `mcpServers`를 거부하며, 부팅 오류는 사용할 키로 `managedMcpServers`를 명명합니다. v2.1.259 이전에는 게이트웨이가 `cli` 블록의 모든 MCP 서버 정의를 거부했습니다.

844 928

845<h4 id="claude-desktop-overlay">929<h4 id="claude-desktop-overlay">

846 Claude Desktop 오버레이930 Claude Desktop 오버레이

847</h4>931</h4>

848 932

849조직이 [Claude Desktop](/docs/ko/desktop)도 배포하면 동일한 gateway가 두 클라이언트를 제공합니다. Claude Desktop의 [관리 구성](https://claude.com/docs/third-party/claude-desktop/configuration)에서 `bootstrapUrl`을 `<listen.public_url>/user/bootstrap`으로 지정하세요. Claude Desktop은 해당 URL에서 OAuth 발급자를 파생하고, 이 gateway에 대해 동일한 장치 코드 로그인을 실행하고, 응답에서 구성을 가져옵니다.933조직이 [Claude Desktop](/docs/ko/desktop)도 배포하면 동일한 게이트웨이가 두 클라이언트를 제공합니다. Claude Desktop의 [관리 구성](https://claude.com/docs/third-party/claude-desktop/configuration)에서 `bootstrapUrl`을 `<listen.public_url>/user/bootstrap`으로 지정합니다. Claude Desktop은 해당 URL에서 OAuth 발급자를 파생하고 이 게이트웨이에 대해 동일한 디바이스 코드 로그인을 실행하며 응답에서 구성을 가져옵니다.

850 934

851<Note>935<Note>

852 gateway 서버의 Claude Code v2.1.203 이상이 필요하며, 명시적 옵트인이 필요합니다. 정책이 사용자와 일치하는 `desktop` 키를 전달하지 않으면 `/user/bootstrap`은 404를 반환합니다. 빈 `desktop: {}`은 정책을 옵트인하며, `match: {}` 기본 계층의 `desktop` 키는 이를 상속하는 모든 정책을 옵트인합니다. 감사 로그는 각 요청을 `desktop_bootstrap.serve` 또는 `desktop_bootstrap.denied`로 기록합니다.936 게이트웨이 서버의 Claude Code v2.1.203 이상이 필요하며, 명시적 옵트인이 필요합니다: 정책이 `desktop` 키를 전달하지 않으면 `/user/bootstrap`은 404를 반환합니다. 빈 `desktop: {}`은 정책을 옵트인하고, `match: {}` 기본 계층의 `desktop` 키는 이를 상속하는 모든 정책을 옵트인합니다. 감사 로그는 각 요청을 `desktop_bootstrap.serve` 또는 `desktop_bootstrap.denied`로 기록합니다.

853</Note>937</Note>

854 938

855gateway는 일치하는 정책의 `cli` 블록과 최상위 gateway 구성에서 응답의 대부분을 파생합니다:939게이트웨이는 응답의 대부분을 일치하는 정책의 `cli` 블록과 최상위 게이트웨이 구성에서 파생합니다:

856 940

857* `availableModels`의 모델 목록941* 모델 목록은 `availableModels`에서

858* 베어 도구 이름 `permissions.deny` 항목의 비활성화된 도구입니다. 정책의 `desktop` 블록에서 `disabledBuiltinTools`를 설정하면 gateway는 파생된 목록과 값의 합집합을 제공하므로 이 방식으로 더 많은 도구를 비활성화할 수 있지만 `permissions.deny`를 통해 비활성화한 도구를 다시 활성화할 수 없습니다.942* 비활성화된 도구는 베어 도구 이름 `permissions.deny` 항목에서입니다. 정책의 `desktop` 블록에서 `disabledBuiltinTools`를 설정하면 게이트웨이는 값과 파생된 목록의 합집합을 제공하므로 이 방식으로 더 많은 도구를 비활성화할 수 있지만 `permissions.deny`를 통해 비활성화한 도구를 다시 활성화할 수 없습니다.

859* `sandbox.network.allowedDomains`의 송신 허용 목록입니다. 정책의 `desktop` 블록에서 `coworkEgressAllowedHosts`를 설정하면 gateway는 파생된 목록 대신 해당 값을 사용합니다.943* 송신 허용 목록은 `sandbox.network.allowedDomains`에서입니다. 정책의 `desktop` 블록에서 `coworkEgressAllowedHosts`를 설정하면 게이트웨이는 파생된 목록 대신 해당 값을 사용합니다.

860* gateway 자체를 가리키는 OTLP 엔드포인트 및 서명된 사용자의 ID 속성입니다. gateway는 해당 엔드포인트에서 받는 내보내기를 `forward_to` 대상으로 릴레이합니다. [`telemetry.forward_to`](#telemetry) 및 `listen.public_url`을 모두 설정할 때 엔드포인트 및 속성을 포함합니다.944* 게이트웨이 자체를 가리키는 OTLP 엔드포인트와 서명된 사용자의 ID 속성입니다. 게이트웨이는 해당 엔드포인트에서 받는 내보내기를 `forward_to` 대상으로 중계합니다. [`telemetry.forward_to`](#telemetry)와 `listen.public_url`을 모두 설정할 때 엔드포인트와 속성을 포함합니다.

861 945

862 Claude Desktop은 모든 신호를 하나의 인코딩으로 내보냅니다: `http/protobuf` 또는 `OTEL_EXPORTER_OTLP_PROTOCOL` 또는 해당 신호별 변형 중 하나를 `http/json`으로 설정할 때 `http/json`입니다. gateway 서버의 Claude Code v2.1.261 이전에는 응답이 관계없이 `http/json`을 설정했으므로 protobuf만 허용하는 수집기는 Claude Desktop의 내보내기를 거부했습니다.946 Claude Desktop은 하나의 인코딩으로 모든 신호를 내보냅니다: `http/protobuf` 또는 `OTEL_EXPORTER_OTLP_PROTOCOL` 또는 정책의 `env`에서 신호별 변형 중 하나를 `http/json`으로 설정할 때 `http/json`입니다. 게이트웨이 서버의 Claude Code v2.1.261 이전에는 응답이 protobuf만 허용하는 수집기가 Claude Desktop의 내보내기를 거부했으므로 관계없이 `http/json`을 설정했습니다.

863 947

864정책의 `desktop` 블록에서 `disabledBuiltinTools`, `coworkEgressAllowedHosts` 또는 Claude Desktop의 자체 `managedMcpServers` 설정을 설정하려면 gateway 서버의 Claude Code v2.1.232 이상이 필요합니다. Claude Desktop의 `managedMcpServers`는 객체가 아닌 배열 값을 취합니다.948정책의 `desktop` 블록에서 `disabledBuiltinTools`, `coworkEgressAllowedHosts` 또는 Claude Desktop의 자체 `managedMcpServers` 설정을 설정하려면 게이트웨이 서버의 Claude Code v2.1.232 이상이 필요합니다. Claude Desktop의 `managedMcpServers`는 객체가 아닌 배열 값을 취합니다.

865 949

866gateway는 Claude Desktop 동등물이 없는 키(예: `hooks` 및 `Bash(npm *)` 같은 범위 지정 권한 규칙)를 부트스트랩 응답에서 생략합니다.950게이트웨이는 `hooks` 및 `Bash(npm *)` 같은 범위 권한 규칙과 같이 Claude Desktop 동등물이 없는 키를 생략합니다.

867 951

868`cli` 옆에 선택적 `desktop` 블록을 추가하여 Claude Desktop 설정을 직접 설정하세요. Claude Desktop의 [관리 구성 참조](https://claude.com/docs/third-party/claude-desktop/configuration)의 설정을 평면 키 이름으로 작성하세요. `bootstrapUrl`과 같이 Claude Desktop이 MDM 또는 로컬 파일에서만 읽는 키는 생략하세요. gateway는 부팅 시 이를 거부합니다. v2.1.232 이전에는 gateway가 `chatTabEnabled` 및 `disableAutoUpdates`와 같은 고정된 11개의 기능 게이트 키 목록을 허용했고 부팅 시 다른 모든 키를 거부했습니다. v2.1.227 이전에는 gateway가 부팅 시 `chatTabEnabled` 및 `chatAdvancedFileAnalysisEnabled`도 거부했습니다.952`cli` 옆에 선택적 `desktop` 블록을 추가하여 Claude Desktop 설정을 직접 설정합니다. Claude Desktop의 [관리 구성 참조](https://claude.com/docs/third-party/claude-desktop/configuration)의 설정을 평면 키 이름으로 작성합니다. `bootstrapUrl`과 같이 Claude Desktop이 MDM 또는 로컬 파일에서만 읽는 키는 생략합니다. 게이트웨이는 부팅 시 이를 거부합니다. v2.1.232 이전에는 게이트웨이가 `chatTabEnabled` 및 `disableAutoUpdates`와 같은 11개의 고정 기능 게이트 키를 허용했고 부팅 시 다른 모든 키를 거부했습니다. v2.1.227 이전에는 게이트웨이가 부팅 시 `chatTabEnabled` 및 `chatAdvancedFileAnalysisEnabled`도 거부했습니다.

869 953

870```yaml theme={null}954```yaml theme={null}

871managed:955managed:

879 banner: { text: "Contractor build: internal use only" }963 banner: { text: "Contractor build: internal use only" }

880```964```

881 965

882모든 키는 선택적입니다. Claude Desktop은 생략한 모든 키에 대해 자체 기본값을 적용합니다. gateway는 부팅 시 각 `desktop` 블록을 Claude Desktop 자체가 사용하는 구성 스키마에 대해 검증하므로 실수는 전체 연결된 데스크톱에 도달하지 않고 키를 명명하는 오류로 gateway 시작에 표시됩니다. gateway는 블록이 다음을 포함할 때 부팅을 실패합니다:966모든 키는 선택적입니다. Claude Desktop은 생략한 모든 키에 대해 자체 기본값을 적용합니다. 게이트웨이는 부팅 시 각 `desktop` 블록을 Claude Desktop 자체가 사용하는 구성 스키마에 대해 검증하므로 실수는 모든 연결된 데스크톱에 도달하는 대신 게이트웨이 시작에서 키를 명명하는 오류로 표시됩니다. 게이트웨이는 블록에 다음이 포함될 때 부팅을 실패합니다:

883 967

884* 알 수 없는 키968* 알 수 없는 키

885* Claude Desktop이 거부하거나 자동으로 삭제할 값을 가진 인식된 키(예: 빈 값 또는 중첩된 항목 내의 오타 부분 키). v2.1.260 이전에는 gateway가 `managedMcpServers` 또는 `orgPluginSettings` 항목의 중첩된 객체 내에서 오타 필드를 자동으로 삭제했습니다.969* Claude Desktop이 거부하거나 자동으로 삭제할 값을 가진 인식된 키(예: 빈 값 또는 중첩된 항목 내 오타 필드). v2.1.260 이전에는 게이트웨이가 부팅을 실패하는 대신 `managedMcpServers` 또는 `orgPluginSettings` 항목의 중첩된 객체 내 오타 필드를 자동으로 삭제했습니다.

886* gateway가 자체 계산하는 키: 추론 연결, 모델 목록 및 OTLP 릴레이입니다. [`upstreams`](#upstreams), [`models`](#models) 및 [`telemetry`](#telemetry) 섹션의 `forward_to`를 통해 이를 구성하세요.970* 게이트웨이가 자체 계산하는 키: 추론 연결, 모델 목록 및 OTLP 중계입니다. 이들을 [`upstreams`](#upstreams), [`models`](#models) 및 [`telemetry`](#telemetry) 섹션의 `forward_to`를 통해 구성합니다.

887* 현재 키의 레거시 별칭입니다. 부팅 오류에서 gateway는 작성할 정규 키를 명명합니다.971* 현재 키의 레거시 별칭입니다. 부팅 오류에서 게이트웨이는 작성할 정규 키를 명명합니다.

888 972

889더 이상 사용되지 않는 값 또는 항목 형태(예: `transport` 없는 `managedMcpServers` 항목)를 사용하면 gateway는 시작하고 대체를 명명하는 경고를 기록합니다.973더 이상 사용되지 않는 값이나 항목 형태(예: `transport` 없는 `managedMcpServers` 항목)를 사용하면 게이트웨이는 시작하고 대체를 명명하는 경고를 기록합니다.

890 974

891gateway는 `cli` 블록과 마찬가지로 설치된 버전과 함께 번들된 스키마에 대해 `desktop` 블록을 검증합니다. 더 새로운 Claude Desktop 릴리스에서 도입한 설정을 전달하려면 먼저 gateway를 업그레이드하세요. 예를 들어 `userPluginMarketplacesEnabled` 및 `userPluginUploadsEnabled`는 gateway 서버의 Claude Code v2.1.260 이상과 멤버 머신의 Claude Desktop 1.37937.0 이상이 필요합니다.975게이트웨이는 `cli` 블록과 마찬가지로 설치된 버전과 함께 번들된 스키마에 대해 `desktop` 블록을 검증합니다. 더 새로운 Claude Desktop 릴리스에서 도입한 설정을 전달하려면 먼저 게이트웨이를 업그레이드합니다. 예를 들어 `userPluginMarketplacesEnabled` 및 `userPluginUploadsEnabled`는 게이트웨이 서버의 Claude Code v2.1.260 이상과 멤버 머신의 Claude Desktop 1.37937.0 이상이 필요합니다.

892 976

893`blockReadsOutsideWorkingDirectories`, `disableBypassPermissionsMode`, `configRecheckIntervalMinutes` 및 `sshClientPath`는 gateway 서버의 Claude Code v2.1.281 이상이 필요합니다. Microsoft 365 `managedMcpServers` 항목의 `microsoftAuthBroker`의 `required` 값과 `continuousAccessEvaluation` 필드도 마찬가지입니다. Claude Desktop 릴리스가 `required` 값보다 앞서면 이를 `disabled`로 읽으므로 모든 멤버의 Claude Desktop이 이를 지원한 후에만 `required`를 설정하세요. Claude Desktop의 [관리 구성 참조](https://claude.com/docs/third-party/claude-desktop/configuration)는 각 키를 처음 읽는 릴리스를 나열합니다.977`blockReadsOutsideWorkingDirectories`, `disableBypassPermissionsMode`, `configRecheckIntervalMinutes` 및 `sshClientPath`는 게이트웨이 서버의 Claude Code v2.1.281 이상이 필요합니다. Microsoft 365 `managedMcpServers` 항목의 `microsoftAuthBroker`의 `required` 값과 `continuousAccessEvaluation` 필드도 마찬가지입니다. `required` 값보다 이전인 Claude Desktop 릴리스는 이를 `disabled`로 읽으므로 모든 멤버의 Claude Desktop이 이를 지원한 후에만 `required`를 설정합니다. Claude Desktop의 [관리 구성 참조](https://claude.com/docs/third-party/claude-desktop/configuration)는 각 키를 먼저 읽는 릴리스를 나열합니다.

894 978

895정책의 `desktop` 블록에서 `orgPluginSettings`를 설정하면 gateway는 Claude Desktop 1.15200.0 이상이 읽는 배열 형식으로 제공합니다. 더 오래된 데스크톱은 배열을 무시하고 플러그인 도구 정책을 강제하지 않으므로 이에 의존하기 전에 멤버를 1.15200.0 이상으로 업데이트하세요.979정책의 `desktop` 블록에서 `orgPluginSettings`를 설정하면 게이트웨이는 Claude Desktop 1.15200.0 이상이 읽는 배열 형태로 제공합니다. 더 오래된 데스크톱은 배열을 무시하고 플러그인 도구 정책을 강제하지 않으므로 이에 의존하기 전에 멤버를 1.15200.0 이상으로 업데이트합니다.

896 980

897gateway는 정책의 `desktop` 블록이 설정하지 않은 키를 `match: {}` catch-all의 `desktop` 블록에서 채웁니다. 기본값의 `cli` 블록을 채우는 방식과 동일합니다. 기본값과 역할 정책 모두에서 `disabledBuiltinTools` 또는 `builtinToolPolicy`를 설정하면 gateway는 기본값의 제한을 유지합니다:981게이트웨이는 정책의 `desktop` 블록이 설정하지 않은 키를 `match: {}` 캐치올의 `desktop` 블록에서 채웁니다. 정책의 `cli` 블록을 기본값에서 채우는 것과 동일한 방식입니다. 기본값과 역할 정책 모두에서 `disabledBuiltinTools` 또는 `builtinToolPolicy`를 설정하면 게이트웨이는 기본값의 제한을 유지합니다:

898 982

899* `disabledBuiltinTools`: gateway는 기본값의 목록과 정책의 목록의 합집합을 사용합니다.983* `disabledBuiltinTools`: 게이트웨이는 기본값의 목록과 정책의 목록의 합집합을 사용합니다.

900* `builtinToolPolicy`: 기본값에서 도구를 `allow` 이외의 값으로 설정하면 역할 정책에서 동일한 도구에 대해 `allow`를 설정해도 gateway는 해당 값을 유지합니다.984* `builtinToolPolicy`: 기본값에서 도구를 `allow` 이외의 값으로 설정하면 역할 정책에서 동일한 도구에 대해 `allow`를 설정해도 게이트웨이는 해당 값을 유지합니다.

901 985

902다른 모든 키의 경우 역할 정책에서 설정하면 gateway는 역할 정책의 값을 사용합니다. gateway는 배열 또는 `banner`와 같은 중첩된 객체를 전체적으로 대체하므로 역할 정책에서 `banner.text`를 설정하면 gateway는 기본값의 `banner.backgroundColor`를 삭제합니다.986다른 모든 키의 경우 역할 정책에서 설정하면 게이트웨이는 역할 정책의 값을 사용합니다. 게이트웨이는 배열 또는 `banner`와 같은 중첩된 객체를 전체적으로 대체하므로 역할 정책에서 `banner.text`를 설정하면 게이트웨이는 기본값의 `banner.backgroundColor`를 삭제합니다.

903 987

904Claude Desktop을 배포하지 않으면 정책에서 `desktop`을 완전히 생략하세요. gateway는 모든 사용자에 대해 `/user/bootstrap`에서 404를 반환합니다.988Claude Desktop을 배포하지 않으면 정책에서 `desktop`을 완전히 생략합니다. 게이트웨이는 모든 사용자에 대해 `/user/bootstrap`에서 404를 반환합니다.

905 989

906<h4 id="precedence-with-other-managed-sources">990<h4 id="precedence-with-other-managed-sources">

907 다른 관리 소스와의 우선 순위991 다른 관리 소스와의 우선순위

908</h4>992</h4>

909 993

910장치에 MDM 전달 정책 또는 로컬 `managed-settings.json`도 있으면 gateway 전달 설정이 우선합니다. 관리 설정 페이지의 [관리 계층 내 우선 순위](/docs/ko/managed-settings#precedence-within-the-managed-tier)는 로컬 소스가 적용되는 시기를 말하며, 샌드박스 잠금 키, `forceRemoteSettingsRefresh` 및 변수별 `env` 병합과 같이 어떤 소스를 선택했는지 관계없이 Claude Code가 모든 관리 소스에서 읽는 [키](/docs/ko/managed-settings#keys-read-from-every-admin-source)를 포함합니다. MDM 프로필 또는 관리 설정 파일에서 구성된 [`policyHelper`](/docs/ko/settings-reference#policyhelper)는 gateway가 설정을 전달하지 않을 때만 실행됩니다. 항목은 해당 출력이 대체하는 것을 말합니다.994디바이스에 MDM 전달 정책 또는 로컬 `managed-settings.json`도 있으면 게이트웨이 전달 설정이 우선합니다. [관리 계층 내 우선순위](/docs/ko/managed-settings#precedence-within-the-managed-tier)는 로컬 소스가 적용되는 시기를 설명하며, 샌드박스 잠금 키, `forceRemoteSettingsRefresh` 및 변수별 `env` 병합과 같이 어떤 소스를 선택했는지 관계없이 Claude Code가 모든 관리 소스에서 읽는 [키](/docs/ko/managed-settings#keys-read-from-every-admin-source)를 포함합니다. 관리 설정 파일에서 구성된 [`policyHelper`](/docs/ko/settings-reference#policyhelper)는 게이트웨이가 설정을 전달하지 않을 때만 실행됩니다. 항목은 출력이 대체하는 것을 설명합니다.

911 995

912[Claude Desktop](/docs/ko/desktop)과 같은 임베딩 호스트는 SDK `managedSettings` 옵션을 통해 정책을 제공할 수 있습니다. [임베딩 호스트의 부모 설정](/docs/ko/managed-settings#parent-settings-from-embedding-hosts)은 Claude Code가 이를 적용하는 시기를 말하며, [부모 설정 제한](/docs/ko/claude-apps-gateway#restrict-parent-settings)은 `allowManaged*Only` 잠금 없이도 여전히 적용되는 허용 방향 설정을 나열합니다.996[Claude Desktop](/docs/ko/desktop)과 같은 임베딩 호스트는 SDK `managedSettings` 옵션을 통해 정책을 제공할 수 있습니다. [임베딩 호스트의 부모 설정](/docs/ko/managed-settings#parent-settings-from-embedding-hosts)은 Claude Code가 이를 적용하는 시기를 설명하며, [부모 설정 제한](/docs/ko/claude-apps-gateway#restrict-parent-settings)은 `allowManaged*Only` 잠금 없이도 여전히 적용되는 허용 방향 설정을 나열합니다.

913 997

914gateway 정책은 비대화형 `claude -p` 실행 및 Agent SDK에서 생성된 세션을 포함하여 머신의 모든 Claude Code 호출에 적용됩니다. gateway가 시작 시 도달할 수 없으면 서명된 세션은 정책 없이 실행하지 않고 오류로 종료됩니다.998게이트웨이 정책은 비대화형 `claude -p` 실행 및 Agent SDK에서 생성한 세션을 포함하여 머신의 모든 Claude Code 호출에 적용됩니다. 게이트웨이가 시작 시 도달할 수 없으면 서명된 세션은 정책 없이 실행하는 대신 오류로 종료됩니다.

915 999

916<h3 id="telemetry">1000<h3 id="telemetry">

917 `telemetry`1001 `telemetry`

918</h3>1002</h3>

919 1003

920CLI는 메트릭, 로그 및 활성화되면 추적을 gateway로 보내며, gateway는 이를 각 구성된 대상으로 그대로 릴레이합니다. 내보내기는 OpenTelemetry Protocol(OTLP)을 HTTP를 통해 사용합니다. 릴레이를 건너뛰고 세션이 수집기로 직접 내보내도록 하려면 [정책에서 수집기를 명명하세요](#export-directly-to-your-collector). [사용 모니터링](/docs/ko/monitoring-usage)에서 CLI가 내보내는 메트릭 및 이벤트를 참조하세요.1004CLI는 메트릭, 로그 및 활성화되면 추적을 게이트웨이로 전송하며, 게이트웨이는 이를 각 구성된 대상으로 그대로 중계합니다. 내보내기는 OpenTelemetry Protocol(OTLP)을 HTTP를 통해 사용합니다. 중계를 건너뛰고 세션이 수집기로 직접 내보내도록 하려면 [정책에서 수집기를 명명](#export-directly-to-your-collector)합니다. [사용량 모니터링](/docs/ko/monitoring-usage)에서 CLI가 내보내는 메트릭 및 이벤트를 참조하세요.

921 1005

922CLI는 gateway 발급 JWT에서 읽은 인증된 사용자의 ID로 각 내보내기에 스탬프를 찍습니다: `user.id`, `user.email` 및 `user.groups` 속성입니다. 개발자별 비용 및 사용 귀속은 따라서 개발자 측 구성 없이 작동합니다.1006`/login`을 통해 서명된 세션에서 CLI는 게이트웨이 발급 JWT에서 읽은 인증된 사용자의 ID로 각 내보내기에 스탬프를 찍습니다: `user.id`, `user.email` 및 `user.groups` 속성입니다. 개발자별 비용 및 사용량 귀속은 따라서 개발자 측 구성 없이 작동합니다.

923 1007

924[Claude Desktop](#claude-desktop-overlay) 및 gateway를 통해 서명된 Cowork 세션은 `user.email` 및 `user.groups`와 함께 `enduser.id`로 원격 측정에 스탬프를 찍으므로 `user.email` 또는 `user.groups`에 대한 하나의 쿼리로 터미널, Desktop 및 Cowork 사용을 포함할 수 있습니다. `user.groups`는 쉼표로 구분된 IdP 그룹 목록입니다.1008[Claude Desktop](#claude-desktop-overlay) 및 게이트웨이를 통해 서명된 Cowork 세션은 `enduser.id`와 함께 `user.email` 및 `user.groups`로 원격 측정에 스탐프를 찍으므로 `user.email` 또는 `user.groups`에 대한 하나의 쿼리로 터미널, Desktop 및 Cowork 사용량을 포함할 수 있습니다. `user.groups`는 쉼표로 구분된 IdP 그룹 목록입니다.

925 1009

926Desktop 및 Cowork 원격 측정은 또한 `enduser.sub`를 전달하며, 이는 사용자의 이메일이 변경될 때 동일하게 유지되는 ID 공급자가 사용자에게 발급하는 `sub` 클레임입니다. 터미널 세션은 동일한 값을 `user.id` 아래에 스탬프를 찍으므로 `enduser.sub`를 터미널 `user.id`와 일치시키는 쿼리는 한 사용자의 터미널, Desktop 및 Cowork 사용을 함께 포함합니다. Desktop 및 Cowork 내보내기에서 `user.id`는 주제가 아닌 익명 식별자입니다.1010Desktop 및 Cowork 원격 측정은 또한 사용자의 이메일이 변경될 때 동일하게 유지되는 `sub` 클레임인 `enduser.sub`를 전달하므로 `enduser.sub`를 터미널 `user.id`와 일치시키는 쿼리는 한 사용자의 터미널, Desktop 및 Cowork 사용량을 함께 포함합니다. Desktop 및 Cowork 내보내기에서 `user.id`는 주제가 아닌 익명 식별자입니다.

927 1011

928Claude Code의 모든 OpenTelemetry 데이터와 마찬가지로 이 속성은 조직이 구성하는 대상으로만 이동하며 Anthropic으로는 이동하지 않습니다.1012Claude Code의 모든 OpenTelemetry 데이터와 마찬가지로 이 속성은 조직이 구성하는 대상으로만 이동하며 Anthropic으로는 이동하지 않습니다.

929 1013

930사용자의 그룹 목록이 퍼센트 인코딩 후 255자보다 길거나 그룹 이름에 쉼표 또는 등호 기호가 포함되면 gateway는 이를 자르지 않고 해당 사용자의 Desktop 및 Cowork 원격 측정에서 `user.groups`를 생략합니다. 해당 사용자의 터미널 세션은 여전히 전체 목록을 전달합니다.1014사용자의 그룹 목록이 퍼센트 인코딩 후 255자보다 길거나 그룹 이름에 쉼표 또는 등호 기호가 포함되면 게이트웨이는 자르는 대신 해당 사용자의 Desktop 및 Cowork 원격 측정에서 `user.groups`를 생략합니다. 해당 사용자의 터미널 세션은 여전히 전체 목록을 전달합니다.

931 1015

932주제가 퍼센트 인코딩 후 255자보다 길거나 공백, 인쇄 가능한 ASCII 외의 문자 또는 `,` `;` `=` `\` `"` `%` 중 하나를 포함하면 gateway는 `enduser.sub`를 생략합니다. 해당 사용자의 Desktop 및 Cowork 원격 측정은 다른 속성을 유지합니다.1016주제가 퍼센트 인코딩 후 255자보다 길거나 공백, 인쇄 가능한 ASCII 외 문자 또는 `,` `;` `=` `\` `"` `%` 중 하나를 포함하면 게이트웨이는 `enduser.sub`를 생략합니다. 해당 사용자의 Desktop 및 Cowork 원격 측정은 다른 속성을 유지합니다.

933 1017

934Desktop 및 Cowork 원격 측정에서 `user.email` 및 `user.groups`를 위해 gateway 서버의 Claude Code v2.1.265 이상이 필요하며, 각 개발자의 머신에서 `user.groups`를 위해 Claude Desktop 1.24012 이상이 필요합니다.1018Desktop 및 Cowork 원격 측정에서 `user.email` 및 `user.groups`를 위해 게이트웨이 서버의 Claude Code v2.1.265 이상이 필요하며, 각 개발자 머신의 Claude Desktop 1.24012 이상이 `user.groups`를 위해 필요합니다.

935 1019

936`enduser.sub`를 위해 gateway 서버의 Claude Code v2.1.274 이상이 필요합니다.1020`enduser.sub`를 위해 게이트웨이 서버의 Claude Code v2.1.274 이상이 필요합니다.

937 1021

938```yaml theme={null}1022```yaml theme={null}

939telemetry:1023telemetry:

941 - url: https://otel-collector.internal.example.com1025 - url: https://otel-collector.internal.example.com

942 headers:1026 headers:

943 Authorization: ${OTLP_TOKEN}1027 Authorization: ${OTLP_TOKEN}

944 # Per-signal opt-in. Default: metrics only.1028 # 신호별 옵트인입니다. 기본값: 메트릭만.

945 metrics: true1029 metrics: true

946 logs: false1030 logs: false

947 traces: false1031 traces: false

951```1035```

952 1036

953<Warning>1037<Warning>

954 각 대상은 `metrics`, `logs` 및 `traces`에 독립적으로 옵트인하며, 기본값은 메트릭만입니다. 신호는 민감도가 다릅니다:1038 각 대상은 `metrics`, `logs` 및 `traces`를 독립적으로 옵트인하며, 기본값은 메트릭만입니다. 신호는 민감도가 다릅니다:

955 1039

956 * **메트릭**: 토큰 수, 요청 수 및 지연 시간과 같은 집계 카운터1040 * **메트릭**: 토큰 수, 요청 수 및 지연 시간과 같은 집계 카운터

957 * **로그 및 추적**: 전체 Bash 명령, 도구 입력 및 파일 경로를 전달할 수 있으며, Claude Code가 개발자의 머신에서 수행하는 모든 것을 포함합니다.1041 * **로그 및 추적**: 전체 Bash 명령, 도구 입력 및 파일 경로를 전달할 수 있으며, Claude Code가 개발자 머신에서 수행하는 모든 것을 포함합니다.

958 1042

959 로그 및 추적을 해당 데이터가 보증하는 액세스 제어 및 보존 정책이 있는 대상에서만 활성화하세요.1043 로그 및 추적은 해당 데이터가 보증하는 액세스 제어 및 보존 정책이 있는 대상에서만 활성화합니다.

960</Warning>1044</Warning>

961 1045

962각 `forward_to` URL은 gateway의 자체 루프백 인터페이스의 수집기에 대한 하나의 예외를 제외하고 `https://`를 사용해야 합니다:1046각 `forward_to` URL은 `https://`를 사용해야 하며, 게이트웨이의 자체 루프백 인터페이스의 수집기에 대한 한 가지 예외가 있습니다:

963 1047

964* `http://localhost:<port>`는 구성 검증을 통과하지만 [SSRF 가드](/docs/ko/claude-apps-gateway-deploy#threat-model-summary)는 `ECONNREFUSED_SSRF`로 모든 내보내기를 차단합니다. gateway의 환경에서 `CLAUDE_GATEWAY_ALLOW_LOOPBACK=1`을 설정하지 않으면 차단됩니다.1048* `http://localhost:<port>`는 구성 검증을 통과하지만 [SSRF 가드](/docs/ko/claude-apps-gateway-deploy#threat-model-summary)는 `ECONNREFUSED_SSRF`로 모든 내보내기를 차단합니다. 게이트웨이 환경에서 `CLAUDE_GATEWAY_ALLOW_LOOPBACK=1`을 설정하지 않으면 차단됩니다.

965* `http://127.0.0.1:<port>` 또는 `http://[::1]:<port>`는 해당 변수가 설정되지 않으면 부팅을 실패합니다.1049* `http://127.0.0.1:<port>` 또는 `http://[::1]:<port>`는 해당 변수가 설정되지 않으면 부팅을 실패합니다.

966 1050

967클러스터 내 수집기의 경우 자체 내부 주소에서 HTTPS를 통해 노출하거나 변수가 설정된 사이드카로 실행하세요.1051클러스터 내 수집기의 경우 자체 내부 주소에서 HTTPS를 통해 노출하거나 변수가 설정된 사이드카로 실행합니다.

968 1052

969`HTTPS_PROXY`가 설정되면 gateway는 해당 프록시를 통해 내보내기를 보냅니다.1053`HTTPS_PROXY`가 설정되면 게이트웨이는 해당 프록시를 통해 내보내기를 전송합니다.

970 1054

971내부 수집기에 직접 도달하려면 호스트 이름으로 또는 `.internal.example.com`과 같은 선행 점이 있는 도메인으로 `NO_PROXY`에 추가하세요. gateway 서버의 Claude Code v2.1.277 이상이 필요합니다. gateway가 프록시 없이 수집기에 도달할 수 있는지 확인하세요. 선행 점이 없는 항목은 정확한 이름만 일치하며 그 아래의 이름은 일치하지 않습니다. CIDR 범위는 일치하지 않습니다.1055내부 수집기에 직접 도달하려면 호스트 이름 또는 `.internal.example.com`과 같은 선행 점이 있는 도메인으로 `NO_PROXY`에 추가합니다. 게이트웨이 서버의 Claude Code v2.1.277 이상이 필요합니다. 게이트웨이가 프록시 없이 수집기에 도달할 수 있는지 확인합니다. 선행 점이 없는 항목은 정확한 이름만 일치하며 그 아래 이름은 일치하지 않습니다. CIDR 범위는 일치하지 않습니다.

972 1056

973[프록시 전용 송신](#proxy-only-egress)이 켜져 있으면 프록시 전용 송신이 꺼지므로 프록시에서 수집기를 허용하세요.1057[프록시 전용 송신](#proxy-only-egress)이 켜져 있으면 프록시에서 수집기를 허용합니다. 프록시 전용 송신을 끄기 때문입니다.

974 1058

975원격 측정은 CLI에서 기본적으로 꺼져 있습니다. `telemetry.forward_to` 및 `listen.public_url`을 모두 설정하면 gateway는 `/managed/settings`를 통해 6개의 환경 변수를 푸시하여 연결된 클라이언트에 대해 켭니다:1059원격 측정은 CLI에서 기본적으로 꺼져 있습니다. `telemetry.forward_to`와 `listen.public_url`을 모두 설정하면 게이트웨이는 `/managed/settings`를 통해 6개의 환경 변수를 푸시하여 연결된 클라이언트에 대해 켭니다:

976 1060

977* `CLAUDE_CODE_ENABLE_TELEMETRY=1`1061* `CLAUDE_CODE_ENABLE_TELEMETRY=1`

978* `OTEL_METRICS_EXPORTER`, `OTEL_LOGS_EXPORTER` 및 `OTEL_TRACES_EXPORTER`는 각각 최소 하나의 `forward_to` 대상이 해당 신호를 활성화하면 `otlp`로 설정되고, 그렇지 않으면 `none`으로 설정됩니다.1062* `OTEL_METRICS_EXPORTER`, `OTEL_LOGS_EXPORTER` 및 `OTEL_TRACES_EXPORTER`는 각각 최소 하나의 `forward_to` 대상이 해당 신호를 활성화하면 `otlp`로 설정되고, 그렇지 않으면 `none`으로 설정됩니다.

979* `OTEL_EXPORTER_OTLP_ENDPOINT=<public_url>`1063* `OTEL_EXPORTER_OTLP_ENDPOINT=<public_url>`

980* `OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf`1064* `OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf`

981 1065

982[자신의 레이블 추가](#add-your-own-labels)할 때 gateway는 또한 `OTEL_RESOURCE_ATTRIBUTES`를 푸시합니다.1066[자체 레이블을 추가](#add-your-own-labels)할 때 게이트웨이는 또한 `OTEL_RESOURCE_ATTRIBUTES`를 푸시합니다.

983 1067

984gateway 서버의 Claude Code v2.1.265 이전에는 gateway가 신호가 옵트인하지 않은 신호를 포함하여 세 개의 내보내기 선택기를 모두 `otlp`로 푸시했습니다.1068게이트웨이 서버의 Claude Code v2.1.265 이전에는 게이트웨이가 신호가 옵트인한 신호를 포함하여 세 개의 내보내기 선택기를 모두 `otlp`로 푸시했습니다.

985 1069

986푸시된 엔드포인트는 공개 URL에서 빌드되므로 메트릭 및 로그는 개발자 또는 정책의 OTEL 구성이 필요하지 않습니다.1070푸시된 엔드포인트는 공개 URL에서 빌드되므로 메트릭 및 로그는 개발자 또는 정책의 OTEL 구성이 필요하지 않습니다.

987 1071

988`/login`을 통해 서명된 개발자는 자체 OTEL 구성으로 내보내기를 리디렉션할 수 없습니다:1072`/login`을 통해 서명된 개발자는 자체 OTEL 구성으로 내보내기를 리디렉션할 수 없습니다:

989 1073

990* **로컬로 설정된 변수**: Claude Code는 푸시된 변수를 관리 계층에서 적용하므로 각 변수는 개발자가 로컬로 설정한 값을 재정의합니다.1074* **로컬로 설정된 변수**: Claude Code는 푸시된 변수를 관리 계층에서 적용하므로 각 변수는 개발자가 로컬로 설정한 값을 재정의합니다.

991* **로컬로 구성된 엔드포인트**: OTLP/HTTP 내보내기가 활성화되면 CLI는 gateway가 원격 측정 변수를 푸시했는지 여부에 관계없이 로컬로 구성된 엔드포인트를 무시합니다. 정책이 [수집기를 엔드포인트로 명명](#export-directly-to-your-collector)하지 않으면 내보내기는 gateway로 이동합니다.1075* **로컬로 구성된 엔드포인트**: OTLP/HTTP 내보내기가 활성화되면 CLI는 로컬로 구성된 엔드포인트를 무시합니다. 게이트웨이가 원격 측정 변수를 푸시했는지 여부에 관계없이 내보내기는 정책이 [수집기를 엔드포인트로 명명](#export-directly-to-your-collector)하지 않으면 게이트웨이로 이동합니다.

992 1076

993신호에 대한 `forward_to` 대상이 없으면 gateway는 이를 수락하고 삭제합니다. 개발자가 이미 Claude Code 원격 측정을 수집기 중 하나로 내보내면 `forward_to` 대상으로 추가하고 로그 또는 추적을 내보내면 활성화하여 서명 후 데이터를 계속 받도록 하세요. 릴레이를 건너뛰려면 [정책에서 수집기를 명명하세요](#export-directly-to-your-collector).1077`forward_to` 대상이 신호에 없으면 게이트웨이는 이를 수락하고 삭제합니다. 개발자가 이미 Claude Code 원격 측정을 수집기 중 하나로 내보내면 `forward_to` 대상으로 추가하고 로그 또는 추적을 내보내면 활성화하여 서명 후 데이터를 계속 받습니다. 중계를 건너뛰려면 [정책에서 수집기를 엔드포인트로 명명](#export-directly-to-your-collector)합니다.

994 1078

995[추적](/docs/ko/monitoring-usage#traces-beta)은 또한 각 클라이언트에서 `CLAUDE_CODE_ENHANCED_TELEMETRY_BETA=1`이 필요합니다. gateway가 푸시하지 않으므로 관리 정책의 `env` 블록에서 설정하세요. 개발자는 푸시된 엔드포인트가 이미 트리거하는 동일한 [보안 승인 대화 상자](#managed)에서 이를 승인합니다.1079[추적](/docs/ko/monitoring-usage#traces-beta)은 또한 각 클라이언트에서 `CLAUDE_CODE_ENHANCED_TELEMETRY_BETA=1`이 필요합니다. 게이트웨이가 푸시하지 않으므로 관리 정책의 `env` 블록에서 설정합니다. 개발자는 푸시된 엔드포인트가 이미 트리거하는 동일한 [보안 승인 대화 상자](#managed)에서 이를 승인합니다.

996 1080

997추적하려는 그룹의 정책에서만 `1`로 설정하세요. 정책이 설정하지 않으면 `match: {}` catch-all 정책이 설정한 경우 해당 값을 상속합니다([병합 규칙](#managed) 참조). 개발자가 로컬로 변수를 설정해도 그룹의 클라이언트가 추적을 보내지 않도록 하려면 해당 그룹의 정책에서 `0`으로 설정하세요.1081추적을 원하는 그룹의 클라이언트에서만 `1`로 설정합니다. 설정하지 않은 정책은 [병합 규칙](#managed)에 따라 `match: {}` 캐치올 정책에서 값을 상속합니다. 개발자가 로컬로 변수를 설정해도 그룹의 클라이언트가 추적을 보내지 않도록 하려면 해당 그룹의 정책에서 `0`으로 설정합니다.

998 1082

999protobuf 및 JSON OTLP 인코딩 모두 릴레이되며 모든 OpenTelemetry 호환 백엔드가 대상으로 작동합니다.1083Protobuf 및 JSON OTLP 인코딩 모두 중계되며 모든 OpenTelemetry 호환 백엔드가 대상으로 작동합니다.

1000 1084

1001<h4 id="add-your-own-labels">1085<h4 id="add-your-own-labels">

1002 자신의 레이블 추가1086 자체 레이블 추가

1003</h4>1087</h4>

1004 1088

1005고정된 레이블(예: `service.namespace` 또는 `deployment.environment.name`)을 gateway를 통해 서명된 세션의 원격 측정에 넣으려면 `telemetry.resource_attributes`를 설정하세요. 각 레이블은 OpenTelemetry 리소스 속성이며 모든 대상이 동일한 레이블을 받습니다.1089`service.namespace` 또는 `deployment.environment.name`과 같은 고정 레이블을 게이트웨이를 통해 서명된 세션의 원격 측정에 넣으려면 `telemetry.resource_attributes`를 설정합니다. 각 레이블은 OpenTelemetry 리소스 속성이며 모든 대상이 동일한 레이블을 받습니다.

1006 1090

1007세션은 `telemetry.forward_to` 및 `listen.public_url`도 설정할 때만 레이블을 받습니다. 이 예제는 두 개의 레이블을 추가합니다:1091세션은 `telemetry.forward_to`와 `listen.public_url`도 설정할 때만 레이블을 받습니다. 이 예제는 두 개의 레이블을 추가합니다:

1008 1092

1009```yaml theme={null}1093```yaml theme={null}

1010telemetry:1094telemetry:

1015 deployment.environment.name: prod1099 deployment.environment.name: prod

1016```1100```

1017 1101

1018gateway는 레이블이 다음 규칙 중 하나를 위반할 때 시작을 거부하며 시작 오류가 레이블을 명명합니다:1102게이트웨이는 레이블이 이 규칙 중 하나를 위반할 때 시작을 거부하며 시작 오류는 레이블을 명명합니다:

1019 1103

1020* 이름은 문자, 숫자, `.`, `_` 및 `-`만 사용합니다.1104* 이름은 문자, 숫자, `.`, `_` 및 `-`만 사용합니다.

1021* 이름은 예약되지 않습니다. 모든 문자 케이스에서 비교하면 예약된 이름은 `user.`, `enduser.` 또는 `identity.`로 시작하는 모든 것과 `service.name`, `service.version`, `claude.deployment_mode`, `host.arch`, `os.type`, `os.version` 및 `wsl.version`입니다.1105* 이름은 예약되지 않습니다. 모든 문자 경우에서 비교하면 예약된 이름은 `user.`, `enduser.` 또는 `identity.`로 시작하는 모든 것과 `service.name`, `service.version`, `claude.deployment_mode`, `host.arch`, `os.type`, `os.version` 및 `wsl.version`입니다.

1022* 값은 공백이 없는 비어있지 않은 인쇄 가능한 ASCII이며 `, ; = \ " %` 중 하나가 아닙니다.1106* 값은 공백이 없고 `, ; = \ " %` 중 하나가 없는 비어 있지 않은 인쇄 가능한 ASCII입니다.

1023* 값은 최대 255자입니다. gateway가 퍼센트 인코딩 후 계산하므로 `/`, `:` 및 `@`는 각각 3자로 계산됩니다.1107* 값은 게이트웨이가 퍼센트 인코딩 후 계산한 후 최대 255자이므로 `/`, `:` 및 `@`는 각각 3으로 계산됩니다.

1024* 값은 텍스트이므로 숫자, `true` 또는 `false`를 인용하세요.1108* 값은 텍스트이므로 숫자, `true` 또는 `false`를 인용합니다.

1025 1109

1026gateway 서버의 Claude Code v2.1.281 이상이 필요합니다. 이전 gateway는 키를 찾으면 시작을 거부하므로 모든 복제본을 업그레이드한 후 키를 추가하고 이전 버전으로 롤백하기 전에 제거하세요.1110게이트웨이 서버의 Claude Code v2.1.281 이상이 필요하여 `telemetry.resource_attributes`를 설정합니다. 이전 게이트웨이는 키를 찾으면 시작을 거부합니다. 모든 복제본을 업그레이드한 후 키를 추가하고 이전 버전으로 롤백하기 전에 키를 제거합니다.

1027 1111

1028`/login`을 통해 서명된 터미널 세션은 다른 [원격 측정 변수](#telemetry)와 함께 레이블을 `OTEL_RESOURCE_ATTRIBUTES`로 받습니다. 정책의 `env` 블록에서 `OTEL_RESOURCE_ATTRIBUTES`를 설정하면 해당 정책과 일치하는 터미널 세션은 레이블 대신 해당 값을 받습니다. Claude Desktop은 `user.email` 및 다른 ID 속성과 함께 gateway에서 레이블을 받습니다.1112`/login`을 통해 서명된 터미널 세션은 다른 [원격 측정 변수](#telemetry)와 함께 푸시된 `OTEL_RESOURCE_ATTRIBUTES`로 레이블을 받습니다. 정책의 `env` 블록에서 `OTEL_RESOURCE_ATTRIBUTES`를 설정하면 해당 정책이 일치하는 터미널 세션은 레이블 대신 해당 값을 받습니다. Claude Desktop은 게이트웨이에서 `user.email` 및 다른 ID 속성과 함께 레이블을 받습니다.

1029 1113

1030Claude Code는 또한 각 레이블을 모든 메트릭 데이터 포인트에 복사하므로 리소스 속성을 인덱싱하지 않는 백엔드에서 메트릭을 필터링할 수 있습니다. 해당 복사를 끄려면 [메트릭 카디널리티 제어](/docs/ko/monitoring-usage#metrics-cardinality-control)를 참조하세요.1114Claude Code는 또한 각 레이블을 모든 메트릭 데이터 포인트에 복사하므로 리소스 속성을 인덱싱하지 않는 백엔드에서 이를 필터링할 수 있습니다. 해당 복사를 끄려면 [메트릭 카디널리티 제어](/docs/ko/monitoring-usage#metrics-cardinality-control)를 참조하세요.

1031 1115

1032<h4 id="export-directly-to-your-collector">1116<h4 id="export-directly-to-your-collector">

1033 수집기로 직접 내보내기1117 수집기로 직접 내보내기

1034</h4>1118</h4>

1035 1119

1036`/login`을 통해 서명된 세션이 릴레이를 통해 수집기로 직접 원격 측정을 보내도록 하려면 [관리 정책](#managed)의 `env` 블록에서 `OTEL_EXPORTER_OTLP_ENDPOINT`를 수집기의 `https://` 기본 URL로 설정하세요. Claude Code는 `/v1/metrics`, `/v1/logs` 또는 `/v1/traces`를 설정한 URL에 추가합니다(예: `https://otel-collector.example.com:4318`). 각 신호는 OTLP/HTTP를 통해 거기로 내보냅니다. 각 개발자의 머신에서 Claude Code v2.1.265 이상이 필요합니다. 이전 클라이언트는 릴레이를 통해 내보냅니다.1120`/login`을 통해 서명된 세션이 중계를 통해 대신 수집기로 직접 원격 측정을 보내도록 하려면 [관리 정책](#managed)의 `env` 블록에서 `OTEL_EXPORTER_OTLP_ENDPOINT`를 수집기의 `https://` 기본 URL로 설정합니다. Claude Code는 URL에 `/v1/metrics`, `/v1/logs` 또는 `/v1/traces`를 추가합니다(예: `https://otel-collector.example.com:4318`). 각 신호를 OTLP/HTTP를 통해 거기로 내보냅니다. 각 개발자 머신의 Claude Code v2.1.265 이상이 필요합니다. 이전 클라이언트는 중계를 통해 내보냅니다.

~~1037~~

1038수집기에 인증하려면 동일한 `env` 블록에서 `OTEL_EXPORTER_OTLP_HEADERS`를 설정하세요. 세션은 이 방식으로 명명된 수집기에 개발자의 gateway 세션 토큰을 보내지 않습니다.

1039 1121

1040정책에서 이 엔드포인트를 추가하거나 변경하면 Claude Code는 각 개발자에게 [보안 승인 대화 상자](#managed)에서 이를 승인하도록 요청한 후 대화형 세션에서 이를 적용합니다.1122수집기에 인증하려면 동일한 `env` 블록에서 `OTEL_EXPORTER_OTLP_HEADERS`를 설정합니다. 세션은 이 방식으로 명명된 수집기에 개발자의 게이트웨이 세션 토큰을 보내지 않습니다.

1041 1123

1042Claude Code는 신호를 직접 내보내기 전에 엔드포인트를 확인하고 확인이 실패하면 해당 신호를 릴레이에 유지합니다. 확인에는 다음이 포함됩니다:1124Claude Code는 신호를 직접 내보내기 전에 엔드포인트를 확인하고 확인이 실패하면 해당 신호를 중계에 유지합니다. 확인에는 다음이 포함됩니다:

1043 1125

1044* 엔드포인트는 gateway 자체에서 옵니다. MDM 프로필 또는 로컬 `managed-settings.json`에서 동일한 변수를 설정하면 내보내기는 릴레이에 유지됩니다.1126* 엔드포인트는 게이트웨이 자체에서 옵니다. MDM 프로필 또는 로컬 `managed-settings.json`에서 동일한 변수를 설정하면 내보내기는 중계에 유지됩니다.

1045* URL은 `https://`를 사용하거나 루프백 주소에 `http://`를 사용합니다.1127* URL은 `https://`를 사용하거나 루프백 주소에 `http://`를 사용합니다.

1046* URL은 쿼리 또는 조각이 없는 `/v1/<signal>`로 끝나는 경로로 확인됩니다. Claude Code는 일반 변수에서 해당 경로를 자체 빌드합니다. `OTEL_EXPORTER_OTLP_METRICS_ENDPOINT`와 같은 신호별 변수를 작성된 대로 사용하므로 전체 경로를 거기에 포함하세요.1128* URL은 쿼리 또는 조각이 없는 `/v1/<signal>`로 끝나는 경로로 확인됩니다. Claude Code는 자신이 해당 경로를 빌드합니다. `OTEL_EXPORTER_OTLP_METRICS_ENDPOINT`와 같은 신호별 변수를 작성된 대로 사용하므로 전체 경로를 거기에 포함합니다.

1047* URL은 gateway의 자체 호스트가 아닙니다. gateway로 주소 지정된 엔드포인트는 릴레이 경로와 세션 토큰을 유지합니다.1129* URL은 게이트웨이의 자체 호스트가 아닙니다. 게이트웨이로 주소 지정된 엔드포인트는 중계 경로와 세션 토큰을 유지합니다.

1048* 어떤 설정 소스에서도 [`otelHeadersHelper`](/docs/ko/settings-reference#otelheadershelper)를 구성하지 않았습니다. 도우미가 구성되면 모든 신호는 릴레이에 유지됩니다.1130* 당신도 개발자도 [`otelHeadersHelper`](/docs/ko/settings-reference#otelheadershelper)를 어떤 설정 소스에서도 구성하지 않았습니다. 도우미가 구성되면 모든 신호는 중계에 유지됩니다.

1049 1131

1050명명한 엔드포인트는 내보내기가 가는 위치만 변경합니다. 여전히 `OTEL_*_EXPORTER` 선택기로 어떤 신호를 내보낼지 선택합니다.1132명명한 엔드포인트는 내보내기가 가는 위치만 변경합니다. 여전히 `OTEL_*_EXPORTER` 선택기로 어떤 신호를 내보낼지 선택합니다.

1051 1133

1052엔드포인트 자체는 내보내기를 켜지 않으므로 gateway가 이미 푸시하지 않으면 변수도 설정하세요:1134엔드포인트 자체는 내보내기를 켜지 않으므로 게이트웨이가 이미 푸시하지 않으면 활성화하는 변수도 설정합니다:

1053 1135

1054* gateway가 이미 [원격 측정 변수를 푸시](#telemetry)하면 활성화, 선택기 및 프로토콜을 포함하고 푸시된 `<public_url>` 값을 재정의합니다. `forward_to` 대상이 활성화하지 않는 신호에 대해서만 `OTEL_*_EXPORTER` 선택기를 `otlp`로 직접 설정하세요.1136* 게이트웨이가 이미 [원격 측정 변수를 푸시](#telemetry)하면 활성화, 선택기 및 프로토콜을 포함하고 푸시된 `<public_url>` 값을 명시적 엔드포인트가 재정의합니다. `forward_to` 대상이 활성화하지 않는 신호에 대해서만 `OTEL_*_EXPORTER` 선택기를 `otlp`로 직접 설정합니다.

1055* 그렇지 않으면 `CLAUDE_CODE_ENABLE_TELEMETRY=1`, `OTEL_*_EXPORTER` 선택기 및 `OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf`도 설정하세요.1137* 그렇지 않으면 `CLAUDE_CODE_ENABLE_TELEMETRY=1`, `OTEL_*_EXPORTER` 선택기 및 `OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf`도 설정합니다.

1056 1138

1057개발자가 로그아웃하거나 다른 gateway에 로그인하면 수집기로의 내보내기가 중지되고 Claude Code는 각 남은 배치를 늦게 전달하지 않고 삭제합니다.1139개발자가 로그아웃하거나 다른 게이트웨이에 로그인하면 수집기로의 내보내기가 중지되고 Claude Code는 각 남은 배치를 보내는 대신 삭제합니다.

1058 1140

1059<h4 id="when-a-destination-fails">1141<h4 id="when-a-destination-fails">

1060 대상이 실패할 때1142 대상이 실패할 때

1061</h4>1143</h4>

1062 1144

1063gateway는 버퍼링, 재시도 또는 원격 측정 저장을 하지 않으므로 대상에 도달하지 않는 내보내기는 늦게 전달되지 않고 삭제됩니다. 각 대상은 독립적으로 성공하거나 실패하며 내보내는 클라이언트는 어느 쪽이든 성공 응답을 받으므로 실패한 전달은 gateway의 로그에만 나타납니다.1145게이트웨이는 버퍼링, 재시도 또는 원격 측정을 저장하지 않으므로 대상에 도달하지 않는 내보내기는 늦게 전달되는 대신 삭제됩니다. 각 대상은 독립적으로 성공하거나 실패하며 내보내는 클라이언트는 어느 쪽이든 성공 응답을 받으므로 실패한 전달은 게이트웨이의 로그에만 나타납니다.

1064 1146

1065대상에 대해 5번 연속 실패한 후 gateway는 30초 단위로 전달을 일시 중지하고 각 일시 중지를 기록하며 전달이 성공할 때까지 계속합니다. 모든 오류 응답, 시간 초과 또는 연결 오류는 실패한 전달로 계산됩니다. `400`, `413`, `415`, `422` 및 `431`은 제외되며, 이들은 수집기가 해당 내보내기의 페이로드를 잘못되었거나 너무 크다고 거부했음을 의미합니다.1147대상에 대한 5번의 연속 실패 전달 후 게이트웨이는 30초 스트레치에서 전달을 일시 중지하고 각 일시 중지를 기록하며 전달이 성공할 때까지 계속합니다. 모든 오류 응답, 시간 초과 또는 연결 오류는 실패한 전달로 계산됩니다. 단, `400`, `413`, `415`, `422` 및 `431`은 수집기가 해당 내보내기의 페이로드를 잘못된 형식 또는 너무 큼으로 거부했음을 의미합니다.

1066 1148

1067거부된 페이로드는 실패 카운트를 진행하거나 재설정하지 않습니다. gateway는 대상으로 전달을 계속하고 첫 거부 및 그 후 100번마다 경고를 기록하며 대상을 명명합니다.1149거부된 페이로드는 실패 카운트를 진행하거나 재설정하지 않습니다: 게이트웨이는 대상으로 전달을 계속하고 대상의 첫 거부 및 그 후 100번마다 상태를 명명하는 경고를 기록합니다.

1068 1150

1069<h3 id="http-tuning">1151<h3 id="http-tuning">

1070 HTTP 튜닝1152 HTTP 조정

1071</h3>1153</h3>

1072 1154

10734개의 선택적 최상위 블록 `access_control`, `limits`, `timeouts` 및 `rate_limits`는 HTTP 표면을 조정합니다. 기본값은 대부분의 배포에 적합합니다.11554개의 선택적 최상위 블록 `access_control`, `limits`, `timeouts` 및 `rate_limits`는 HTTP 표면을 조정합니다. 기본값은 대부분의 배포에 적합합니다.

1074 1156

1075| 블록 | 키 | 기본값 | 설명 |1157| 블록 | 키 | 기본값 | 설명 |

1076| - | - | - | - |1158| - | - | - | - |

1077| `access_control` | `allow_cidrs` / `deny_cidrs` | 비어있음 | `trusted_proxies` 해결 후 클라이언트 주소별 인바운드 IP 허용/거부입니다. `deny_cidrs`가 먼저 확인됩니다. 일치하는 클라이언트는 `allow_cidrs`도 일치해도 거부됩니다. `allow_cidrs`가 비어있지 않으면 gateway는 기본 거부입니다. `/healthz` 및 `/readyz`는 `allow_cidrs`에서 제외됩니다. 신뢰할 수 있는 프록시가 IP 주소가 아닌 `X-Forwarded-For` 항목을 보내면 실제 클라이언트는 알 수 없으며 gateway는 확인할 내용을 명명하는 경고를 한 번 기록합니다. 목록이 요청에 적용되는 경우 `403`으로 거부하고 감사 이유 `xff_unparseable`입니다. 어느 것도 적용되지 않으면 요청을 제공하고 프록시의 자체 주소를 IP별 요금 제한 및 감사의 클라이언트 IP로 사용합니다. |1159| `access_control` | `allow_cidrs` / `deny_cidrs` | 비어 있음 | `trusted_proxies` 해결 후 클라이언트 주소별 인바운드 IP 허용/거부입니다. `deny_cidrs`를 먼저 확인합니다. 클라이언트가 일치하면 `allow_cidrs`도 일치해도 거부됩니다. `allow_cidrs`가 비어 있지 않으면 게이트웨이는 기본 거부입니다. `/healthz` 및 `/readyz`는 `allow_cidrs`에서 제외됩니다. 신뢰할 수 있는 프록시가 IP 주소가 아닌 `X-Forwarded-For` 항목을 보내면 실제 클라이언트는 알 수 없으며 게이트웨이는 확인할 내용을 명명하는 경고를 한 번 기록합니다. 목록이 요청에 적용되는 경우 `403`과 감사 이유 `xff_unparseable`로 거부합니다. 어느 것도 적용되지 않으면 요청을 제공하고 프록시의 자체 주소를 IP별 요금 제한 및 감사의 클라이언트 IP로 사용합니다. |

1082| `rate_limits` | `device_authorization.max` / `.window_seconds` | 30 / 600 | 인증되지 않은 장치 인증 엔드포인트의 IP별 요금 제한입니다. 공유 송신 IP 또는 NAT 뒤의 큰 조직에 대해 올립니다. [대규모 배포](/docs/ko/claude-apps-gateway-deploy#large-rollouts)는 크기를 조정하는 방법을 보여줍니다. 이 제한은 장치 부여 로그인 흐름에만 적용되며 `/v1/messages` 추론에는 적용되지 않습니다. [사용자 코드 무차별 대입 공격 저항](/docs/ko/claude-apps-gateway-deploy#user-code-brute-force-resistance)을 참조하세요. |1164| `rate_limits` | `device_authorization.max` / `.window_seconds` | 30 / 600 | 인증되지 않은 디바이스 인증 엔드포인트의 IP별 요금 제한입니다. 공유 송신 IP 또는 NAT 뒤의 큰 조직에 대해 올립니다. [대규모 롤아웃](/docs/ko/claude-apps-gateway-deploy#large-rollouts)은 크기를 조정하는 방법을 보여줍니다. 이 제한은 디바이스 부여 로그인 흐름에만 적용되며 `/v1/messages` 추론에는 적용되지 않습니다. [사용자 코드 무차별 대입 공격 저항](/docs/ko/claude-apps-gateway-deploy#user-code-brute-force-resistance)을 참조하세요. |

1083| `rate_limits` | `device_verify.max` / `.window_seconds` | 10 / 600 | `/device`의 `user_code` 제출에 대한 IP별 요금 제한입니다. 이것이 누군가가 다른 개발자의 코드를 추측하는 것을 중지합니다. [대규모 배포](/docs/ko/claude-apps-gateway-deploy#large-rollouts)는 얼마나 올릴지 보여줍니다. |1165| `rate_limits` | `device_verify.max` / `.window_seconds` | 10 / 600 | `/device`의 `user_code` 제출에 대한 IP별 요금 제한입니다. 누군가 다른 개발자의 코드를 추측하는 것을 중지하는 것입니다. [대규모 롤아웃](/docs/ko/claude-apps-gateway-deploy#large-rollouts)은 얼마나 올릴지 보여줍니다. |

1084 1166

1085두 `access_control` 목록을 비어있게 두면(기본값) gateway는 모든 클라이언트 주소를 제공하므로 네트워크만 도달할 수 있는 사람을 제한합니다. gateway는 개발자 머신에서 명령을 실행하는 [관리 설정](#managed)을 푸시할 수 있기 때문에 중요합니다.1167두 `access_control` 목록을 비워 두면(기본값) 게이트웨이는 모든 클라이언트 주소를 제공하므로 네트워크만 도달할 수 있는 사람을 제한합니다. 게이트웨이는 [관리 설정](#managed)을 푸시할 수 있으므로 중요합니다. 개발자 머신에서 명령을 실행합니다.

1086 1168

1087`allow_cidrs`가 비어있는 동안 gateway는 요청에 응답하는 방식을 변경하지 않고 두 위치에서 경고합니다:1169`allow_cidrs`가 비어 있는 동안 게이트웨이는 두 곳에서 경고합니다. 요청에 답하는 방식을 변경하지 않습니다:

1088 1170

1089* **부팅 시**: 운영 로그의 경고는 개인 범위 `10.0.0.0/8`, `172.16.0.0/12`, `192.168.0.0/16`, `100.64.0.0/10`, `127.0.0.0/8`, `::1/128` 및 `fc00::/7`만 허용하고 개발자가 연결하는 다른 내부 범위를 권장합니다. gateway를 루프백 주소에 바인드하고 `trusted_proxies` 또는 `public_url`을 설정하지 않으면(로컬 개발처럼) 경고가 나타나지 않습니다.1171* **부팅 시**: 운영 로그의 경고는 개발자가 연결하는 개인 범위 `10.0.0.0/8`, `172.16.0.0/12`, `192.168.0.0/16`, `100.64.0.0/10`, `127.0.0.0/8`, `::1/128` 및 `fc00::/7`과 다른 내부 범위만 허용할 것을 권장합니다. 게이트웨이를 루프백 주소에 바인드하고 `trusted_proxies` 또는 `public_url`을 설정하지 않으면(로컬 개발처럼) 경고가 나타나지 않습니다.

1090* **런타임**: 요청이 처음 해당 개인 범위 외의 주소에서 도착하면 gateway는 경고를 기록하고 클라이언트 IP를 전달하는 [`access.public_client` 감사 이벤트](/docs/ko/claude-apps-gateway-deploy#logs)를 내보냅니다. 둘 다 프로세스당 한 번 실행됩니다. 링크 로컬 주소 `169.254.0.0/16` 및 `fe80::/10`은 공개로 계산되지 않습니다. gateway는 이 확인이 실행되기 전에 `/healthz` 및 `/readyz`에 응답하므로 공개 범위의 상태 프로브는 이를 트리거하지 않습니다.1172* **런타임**: 요청이 처음 해당 개인 범위 외부의 주소에서 도착하면 게이트웨이는 경고를 기록하고 클라이언트 IP를 전달하는 [`access.public_client` 감사 이벤트](/docs/ko/claude-apps-gateway-deploy#logs)를 내보냅니다. 둘 다 프로세스당 한 번 실행됩니다. 링크 로컬 주소 `169.254.0.0/16` 및 `fe80::/10`은 공개로 계산되지 않습니다. 게이트웨이는 이 확인이 실행되기 전에 `/healthz` 및 `/readyz`에 응답하므로 공개 범위의 상태 프로브는 이를 트리거하지 않습니다.

1091 1173

1092두 신호 모두 gateway가 해결하는 클라이언트 주소를 사용합니다. 로드 밸런서, 포트 포워드 또는 터널이 트래픽을 릴레이하고 `listen.trusted_proxies`에 나열되지 않으면 gateway는 릴레이의 주소를 보며, 이는 보통 개인이므로 런타임 경고나 개인 허용 목록이 이를 포착하지 않습니다.1174두 신호 모두 게이트웨이가 해결하는 클라이언트 주소를 사용합니다. 로드 밸런서, 포트 포워드 또는 터널이 트래픽을 중계하고 `listen.trusted_proxies`에 나열되지 않으면 게이트웨이는 중계의 주소를 보며, 이는 일반적으로 개인이므로 런타임 경고나 개인 허용 목록이 이를 포착하지 않습니다.

1093 1175

1094그러한 프론트 엔드 뒤에서 먼저 [`listen.trusted_proxies`](#listen)를 설정하여 gateway가 실제 클라이언트 주소를 보도록 하고 gateway와 그 앞의 모든 것을 공개 인터넷에서 도달할 수 없도록 유지하세요.1176그러한 프론트 엔드 뒤에서 먼저 [`listen.trusted_proxies`](#listen)를 설정하여 게이트웨이가 실제 클라이언트 주소를 보도록 하고 게이트웨이와 그 앞의 모든 것을 공개 인터넷에서 도달할 수 없도록 유지합니다.

1095 1177

1096<h3 id="load_test_mode">1178<h3 id="load_test_mode">

1097 `load_test_mode`1179 `load_test_mode`

1098</h3>1180</h3>

1099 1181

1100`load_test_mode` 블록을 사용하면 모델 공급자를 호출하지 않고 gateway를 부하 테스트할 수 있습니다. 켜져 있는 동안 gateway는 각 공급자 요청을 평소대로 빌드하고 서명하며, 보내지 않고 버리고, 정상적인 응답 경로를 통해 통조림 회신을 다시 스트리밍합니다. 회신은 통조림임을 말하는 문장으로 시작하는 채우기 텍스트입니다.1182`load_test_mode` 블록을 사용하면 모델 공급자를 호출하지 않고 게이트웨이를 부하 테스트할 수 있습니다. 켜져 있는 동안 게이트웨이는 각 공급자 요청을 일반적으로 빌드하고 서명하며 대신 삭제하고 정상 응답 경로를 통해 통조림 회신을 스트리밍합니다. 회신은 통조림임을 말하는 문장으로 시작하는 필러 텍스트입니다.

1101 1183

1102gateway 서버의 Claude Code v2.1.282 이상이 필요합니다. 이전 버전은 키가 설정되면 시작을 거부하므로 모든 복제본을 업그레이드한 후 블록을 추가하고 롤백하기 전에 제거하세요.1184게이트웨이 서버의 Claude Code v2.1.282 이상이 필요합니다. 이전 게이트웨이는 키를 찾으면 시작을 거부합니다. 모든 복제본을 업그레이드한 후 블록을 추가하고 이전 버전으로 롤백하기 전에 블록을 제거합니다.

1103 1185

1104아래 예제는 기본값으로 모드를 켜며, 약 10초에 걸쳐 스트리밍되는 750개 출력 토큰의 회신입니다:1186아래 예제는 기본값으로 모드를 켜며, 약 750개 토큰의 텍스트로 약 10초에 걸쳐 스트리밍되는 회신입니다:

1105 1187

1106```yaml theme={null}1188```yaml theme={null}

1107load_test_mode:1189load_test_mode:

1108 enabled: true1190 enabled: true

1109 reply_tokens: 750 # roughly how many tokens of text each canned reply carries1191 reply_tokens: 750 # 대략 각 통조림 회신이 전달하는 텍스트의 토큰 수

1110 reply_seconds: 9.5 # how long a streamed reply takes1192 reply_seconds: 9.5 # 스트리밍된 회신이 걸리는 시간

1111```1193```

1112 1194

1113| 필드 | 필수 | 설명 |1195| 필드 | 필수 | 설명 |

1114| - | - | - |1196| - | - | - |

1115| `enabled` | 예 | `true`는 모드를 켭니다. `false`는 모드를 끈 상태로 파일에 숫자를 유지합니다. 블록이 없으면 gateway는 시작을 거부합니다. |1197| `enabled` | 예 | `true`는 모드를 켭니다. `false`는 모드를 끈 상태로 파일에 숫자를 유지합니다. 블록이 있지만 없으면 게이트웨이는 시작을 거부합니다. |

1116| `reply_tokens` | 아니요 | 기본값 `750`입니다. 각 통조림 회신이 전달하는 텍스트의 토큰 수(대략), 1에서 100000 사이의 정수입니다. |1198| `reply_tokens` | 아니요 | 기본값 `750`입니다. 대략 각 통조림 회신이 전달하는 텍스트의 토큰 수로, 1에서 100000 사이의 정수입니다. |

1117| `reply_seconds` | 아니요 | 기본값 `9.5`입니다. 스트리밍된 회신이 걸리는 시간(0에서 600 사이). `0`은 전체 회신을 한 번에 보냅니다. 비스트리밍 요청에 대한 회신은 항상 한 번에 옵니다. |1199| `reply_seconds` | 아니요 | 기본값 `9.5`입니다. 스트리밍된 회신이 걸리는 시간으로, 0에서 600 사이입니다. `0`은 전체 회신을 한 번에 보냅니다. 비스트리밍 요청에 대한 회신은 항상 한 번에 옵니다. |

1200

1201이 모드의 부하 테스트는 게이트웨이, Postgres 및 게이트웨이 앞의 모든 것을 포함합니다. 공급자의 제한, 속도 또는 네트워크 경로는 포함하지 않습니다.

1118 1202

1119이 모드의 부하 테스트는 gateway, Postgres 및 gateway 앞의 모든 것을 포함합니다. 공급자의 한도, 속도 또는 네트워크 경로는 포함하지 않습니다.1203모델 요청이 공급자로 전송되지 않으므로 복제본의 요청당 CPU는 추정치이며 프로덕션보다 낮게 읽습니다. 프로덕션도 공급자로의 트래픽을 암호화합니다. 실제 공급자에 대한 작은 파일럿으로 복제본 수를 확인합니다. v2.1.283 이전에는 추정치가 훨씬 더 낮게 읽혔습니다.

1120 1204

1121모드가 켜져 있는 동안 요청은 최대 7자리의 정수를 보유하는 `x-load-test-user` 헤더를 전달할 수 있으며, gateway는 각 숫자를 요청과 함께 온 개발자의 이메일 및 그룹을 가진 별도의 개발자로 계산합니다. 부하 테스트 배포에 자체 빈 데이터베이스를 제공하세요. gateway는 모드가 켜져 있고 개발자가 이미 무언가를 지출한 데이터베이스에 대해 시작을 거부합니다.1205모드가 켜져 있는 동안 요청은 최대 7자리의 정수를 보유하는 `x-load-test-user` 헤더를 전달할 수 있습니다. 게이트웨이는 각 숫자를 요청과 함께 온 개발자의 이메일 및 그룹을 가진 별도의 개발자로 계산합니다.

1206

1207부하 테스트 배포에 자체 빈 데이터베이스를 제공합니다. 게이트웨이는 모드가 켜져 있고 이미 무언가를 지출한 개발자가 있는 데이터베이스에 대해 시작을 거부합니다.

1122 1208

1123<Warning>1209<Warning>

1124 개발자가 사용하는 gateway에 대해 이를 켜지 마세요. 모든 요청은 통조림 회신을 받고 모델은 호출되지 않습니다. gateway는 부팅 시 `load_test_mode is on` 경고를 기록하고 모드가 켜져 있는 동안 각 `inference` [감사 이벤트](/docs/ko/claude-apps-gateway-deploy#logs)를 `load_test: true`로 표시합니다.1210 개발자가 사용하는 게이트웨이에 대해 이를 켜지 마세요. 모든 요청은 통조림 회신을 받고 모델은 호출되지 않습니다. 게이트웨이는 부팅 시 `load_test_mode is on` 경고를 기록하고 모드가 켜져 있는 동안 각 `inference` [감사 이벤트](/docs/ko/claude-apps-gateway-deploy#logs)를 `load_test: true`로 표시합니다.

1125</Warning>1211</Warning>

1126 1212

1127<h2 id="complete-example">1213<h2 id="complete-example">

1298 1384

1299`parentSettingsBehavior: "merge"`는 Claude Desktop의 이그레스 허용 목록 전달이 임베드된 Claude Code 세션에서 작동하도록 유지합니다. [Claude Desktop 세션에 정책 전달](/docs/ko/claude-apps-gateway#deliver-policy-to-claude-desktop-sessions)에서 메커니즘과 옵트인이 위치해야 하는 곳을 설명합니다.1385`parentSettingsBehavior: "merge"`는 Claude Desktop의 이그레스 허용 목록 전달이 임베드된 Claude Code 세션에서 작동하도록 유지합니다. [Claude Desktop 세션에 정책 전달](/docs/ko/claude-apps-gateway#deliver-policy-to-claude-desktop-sessions)에서 메커니즘과 옵트인이 위치해야 하는 곳을 설명합니다.

1300 1386

1301`managed-settings.json` 파일을 각 장치에 배포합니다. 일반적으로 MDM 플랫폼을 통해 배포합니다. 각 메커니즘이 정책을 저장하는 위치는 [정책을 저장하는 각 메커니즘의 위치](/docs/ko/managed-settings#where-each-mechanism-stores-the-policy)를 참조하십시오.1387개발자가 클라우드 공급자 변수 또는 자신의 `ANTHROPIC_BASE_URL`로 게이트웨이를 우회하는 것을 방지하려면 같은 파일에 `"allowedProviders": ["gateway"]`를 추가합니다. Claude Code는 Cloud 게이트웨이로 설정되지 않은 머신의 모든 세션을 거부하고, `forceLoginGatewayUrl`이 지정하는 게이트웨이 또는 파일의 `env` 블록이 `ANTHROPIC_BASE_URL`으로 설정한 URL을 가진 게이트웨이만 허용합니다. `claude gateway`는 이 목록을 설정하는 머신에서 실행되기를 거부하므로 게이트웨이 호스트에서 이 키를 제외합니다. 설정 참조의 [`allowedProviders`](/docs/ko/settings-reference#allowedproviders) 항목을 참조하십시오. Claude Code v2.1.285 이상이 필요합니다.

1388

1389`managed-settings.json` 파일을 각 장치에 배포합니다. 일반적으로 MDM 플랫폼을 통해 배포합니다. 파일 경로는 플랫폼마다 다릅니다. [각 메커니즘이 정책을 저장하는 위치](/docs/ko/managed-settings#where-each-mechanism-stores-the-policy)를 참조하십시오.

1302 1390

1303기본적으로 Windows의 레지스트리 정책 또는 macOS의 관리형 기본 설정 plist는 [위의 예외 키 및 교차 소스 확인](#precedence-with-other-managed-sources)을 제외하고 `managed-settings.json` 파일을 병합하지 않고 대체합니다. 이 스니펫의 모든 세 키는 최고 우선순위 소스 규칙을 따르므로 그룹 정책 또는 구성 프로필을 통해 정책을 전달하는 플릿은 대신 해당 메커니즘에 모두 세 개를 모두 배치해야 합니다.1391기본적으로 Windows의 레지스트리 정책 또는 macOS의 관리형 기본 설정 plist는 [위의 예외 키 및 교차 소스 확인](#precedence-with-other-managed-sources)을 제외하고 `managed-settings.json` 파일을 병합하지 않고 대체합니다. 이 스니펫의 모든 세 키는 최고 우선순위 소스 규칙을 따르므로 그룹 정책 또는 구성 프로필을 통해 정책을 전달하는 플릿은 대신 해당 메커니즘에 모두 세 개를 배치해야 합니다.

1304 1392

1305Claude Desktop의 경우 Claude Desktop의 자체 [관리형 구성](https://claude.com/docs/third-party/claude-desktop/configuration)에서 `bootstrapUrl` 키를 `<listen.public_url>/user/bootstrap`으로 설정합니다. 로그인 흐름 및 그룹별 정책은 정책이 `desktop` 키로 서버 측에서 옵트인되면 CLI의 정책과 일치합니다. 옵트인이 없으면 `/user/bootstrap`은 404를 반환합니다. 서버 측 절반은 [Claude Desktop 오버레이](#claude-desktop-overlay)를 참조하십시오.1393Claude Desktop의 경우 Claude Desktop의 자체 [관리형 구성](https://claude.com/docs/third-party/claude-desktop/configuration)에서 `bootstrapUrl` 키를 `<listen.public_url>/user/bootstrap`으로 설정합니다. 로그인 흐름 및 그룹별 정책은 정책이 `desktop` 키로 서버 측에서 옵트인되면 CLI의 정책과 일치합니다. 옵트인이 없으면 `/user/bootstrap`은 404를 반환합니다. 서버 측 절반은 [Claude Desktop 오버레이](#claude-desktop-overlay)를 참조하십시오.

1306 1394

1307Claude Code는 [`forceLoginGatewayUrl`](/docs/ko/settings-reference#forcelogingatewayurl), [`gatewayInternalNetworks`](/docs/ko/settings-reference#gatewayinternalnetworks), 및 [`forceLoginMethod`](/docs/ko/settings-reference#forceloginmethod)의 `"gateway"` 값을 머신의 관리형 소스에서만 인정합니다: `managed-settings.json`, macOS plist 또는 Windows HKLM 레지스트리, 또는 정책 헬퍼. 개발자가 자신의 `~/.claude/settings.json`에서 이들을 설정하는 것은 효과가 없으며, 게이트웨이 페이로드에서 설정하는 것도 마찬가지입니다.1395Claude Code는 [`forceLoginGatewayUrl`](/docs/ko/settings-reference#forcelogingatewayurl), [`gatewayInternalNetworks`](/docs/ko/settings-reference#gatewayinternalnetworks), 및 [`forceLoginMethod`](/docs/ko/settings-reference#forceloginmethod)의 `"gateway"` 값을 머신의 관리형 소스에서만 인정합니다: `managed-settings.json`, macOS plist 또는 Windows HKLM 레지스트리, 또는 정책 헬퍼. 개발자가 자신의 `~/.claude/settings.json`에서 이들을 설정하는 것은 게이트웨이 로그인을 구성하지 않으며, 게이트웨이 페이로드에서 설정하는 것도 마찬가지입니다.

1308 1396

1309`forceLoginMethod` 및 `forceLoginOrgUUID`를 페이로드에서 제외합니다. Claude Code는 여전히 시작 자격 증명 확인을 위해 페이로드에서 두 키를 모두 읽으므로, 머신에 Anthropic 발급 자격 증명을 유지하는 개발자는 로그인 후에도 [관리자 정책이 Cloud 게이트웨이 로그인을 요구합니다](/docs/ko/errors#administrator-policy-requires-a-cloud-gateway-sign-in)에서 설명한 시작 종료를 받게 됩니다.1397페이로드에서 `forceLoginMethod` 및 `forceLoginOrgUUID`를 제외합니다. Claude Code는 여전히 시작 자격 증명 확인을 위해 페이로드에서 두 키를 모두 읽으므로, 머신에 Anthropic 발급 자격 증명을 유지하는 개발자는 로그인 후에도 [관리자 정책이 Cloud 게이트웨이 로그인을 요구합니다](/docs/ko/errors#administrator-policy-requires-a-cloud-gateway-sign-in)에서 설명한 시작 종료를 받게 됩니다.

1310 1398

1311<h2 id="related">1399<h2 id="related">

1312 관련1400 관련

claude-directory.md +1 −0

Details

1562| `image-cache/<session>/` | Claude Code v2.1.274 이전 버전에서 저장한 첨부 이미지입니다. 이후 버전은 붙여넣은 이미지와 첨부 이미지를 `~/.claude` 외부에 저장하며, [`CLAUDE_CODE_TMPDIR`](/docs/ko/env-vars)이 제어하는 임시 디렉토리 아래 각 세션에 대한 `images/` 디렉토리에 저장합니다. 스윕은 나이에 관계없이 여기에 있는 다른 세션의 남은 디렉토리를 제거합니다. |1562| `image-cache/<session>/` | Claude Code v2.1.274 이전 버전에서 저장한 첨부 이미지입니다. 이후 버전은 붙여넣은 이미지와 첨부 이미지를 `~/.claude` 외부에 저장하며, [`CLAUDE_CODE_TMPDIR`](/docs/ko/env-vars)이 제어하는 임시 디렉토리 아래 각 세션에 대한 `images/` 디렉토리에 저장합니다. 스윕은 나이에 관계없이 여기에 있는 다른 세션의 남은 디렉토리를 제거합니다. |

1563| `uploads/<session>/` | 웹 또는 모바일 앱에서 첨부한 파일 및 모바일 앱에서 첨부한 사진. [Remote Control](/docs/ko/remote-control) 세션에 메시지를 보낼 때입니다. [cloud session](/docs/ko/claude-code-on-the-web)에 대한 첨부는 대신 해당 세션의 자체 클라우드 환경에 저장되며, 사용자의 머신에는 저장되지 않습니다. |1563| `uploads/<session>/` | 웹 또는 모바일 앱에서 첨부한 파일 및 모바일 앱에서 첨부한 사진. [Remote Control](/docs/ko/remote-control) 세션에 메시지를 보낼 때입니다. [cloud session](/docs/ko/claude-code-on-the-web)에 대한 첨부는 대신 해당 세션의 자체 클라우드 환경에 저장되며, 사용자의 머신에는 저장되지 않습니다. |

1564| `dev-mods/<session>/` | [Claude가 작성한 Mods](/docs/ko/plugins/mods/create#ask-claude-for-a-mod) (세션 중) |

1566| `shell-snapshots/` | 시작 시 캡처된 별칭, 함수 및 셸 옵션. [Bash tool](/docs/ko/tools-reference#bash-tool-behavior)에 의해 각 명령에 적용됩니다. 정상 종료 시 제거됩니다. 스윕은 충돌 후 남은 것을 정리합니다. |1567| `shell-snapshots/` | 시작 시 캡처된 별칭, 함수 및 셸 옵션. [Bash tool](/docs/ko/tools-reference#bash-tool-behavior)에 의해 각 명령에 적용됩니다. 정상 종료 시 제거됩니다. 스윕은 충돌 후 남은 것을 정리합니다. |

cli-reference.md +4 −3

Details

64| `--add-dir` | Claude가 파일을 읽고 편집할 수 있도록 추가 작업 디렉터리를 추가합니다. 파일 액세스 권한을 부여합니다. Claude Code는 이러한 디렉터리에서 대부분의 `.claude/` 구성을 [검색하지 않습니다](/docs/ko/permissions#additional-directories-grant-file-access-not-configuration). 각 경로가 디렉터리로 존재하는지 검증합니다. `\\server\share`와 같은 대부분의 [네트워크 경로](/docs/ko/errors#working-directory-is-a-network-path)를 추가할 수 없습니다. 이러한 디렉터리를 세션 간에 유지하려면 설정에서 [`permissions.additionalDirectories`](/docs/ko/settings-reference#permissions-additionaldirectories)를 설정합니다 | `claude --add-dir ../apps ../lib` |64| `--add-dir` | Claude가 파일을 읽고 편집할 수 있도록 추가 작업 디렉터리를 추가합니다. 파일 액세스 권한을 부여합니다. Claude Code는 이러한 디렉터리에서 대부분의 `.claude/` 구성을 [검색하지 않습니다](/docs/ko/permissions#additional-directories-grant-file-access-not-configuration). 각 경로가 디렉터리로 존재하는지 검증합니다. `\\server\share`와 같은 대부분의 [네트워크 경로](/docs/ko/errors#working-directory-is-a-network-path)를 추가할 수 없습니다. 이러한 디렉터리를 세션 간에 유지하려면 설정에서 [`permissions.additionalDirectories`](/docs/ko/settings-reference#permissions-additionaldirectories)를 설정합니다 | `claude --add-dir ../apps ../lib` |

65| `--advisor <model>` | 이 세션에 대해 모델 별칭 `fable`, `opus` 또는 `sonnet`, 또는 전체 모델 ID를 사용하여 서버 측 [advisor 도구](/docs/ko/advisor)를 활성화합니다. 세션에 대해 `advisorModel` 설정보다 우선합니다. `fable`은 [Fable 액세스](/docs/ko/advisor#choose-an-advisor-model)가 필요합니다 | `claude --advisor opus` |65| `--advisor <model>` | 이 세션에 대해 모델 별칭 `fable`, `opus` 또는 `sonnet`, 또는 전체 모델 ID를 사용하여 서버 측 [advisor 도구](/docs/ko/advisor)를 활성화합니다. 세션에 대해 `advisorModel` 설정보다 우선합니다. `fable`은 [Fable 액세스](/docs/ko/advisor#choose-an-advisor-model)가 필요합니다 | `claude --advisor opus` |

67| `--agents` | JSON을 통해 사용자 정의 서브에이전트를 동적으로 정의합니다. [CLI 정의 서브에이전트에 대해 나열된 필드](/docs/ko/sub-agents#choose-the-subagent-scope)를 허용합니다. With `--print`, the value can instead be the path to a JSON file holding the object; the file form requires Claude Code v2.1.281 or later. Claude Code는 시작 시 값을 검증하고 잘못된 값에서 종료합니다. 메시지 및 검증을 건너뛰는 플래그와 환경 변수는 [`Invalid --agents configuration`](/docs/ko/errors#invalid-agents-configuration)을 참조하세요. 검증에는 Claude Code v2.1.242 이상이 필요합니다 | `claude --agents '{"reviewer":{"description":"Reviews code","prompt":"You are a code reviewer"}}'` |67| `--agents` | JSON을 통해 사용자 정의 서브에이전트를 동적으로 정의합니다. [CLI 정의 서브에이전트에 대해 나열된 필드](/docs/ko/sub-agents#choose-the-subagent-scope)를 허용합니다. `--print`를 사용하면 값이 대신 JSON 객체를 보유하는 JSON 파일의 경로일 수 있습니다. 파일 형식에는 Claude Code v2.1.281 이상이 필요합니다. Claude Code는 시작 시 값을 검증하고 잘못된 값에서 종료합니다. 메시지 및 검증을 건너뛰는 플래그와 환경 변수는 [`Invalid --agents configuration`](/docs/ko/errors#invalid-agents-configuration)을 참조하세요. 검증에는 Claude Code v2.1.242 이상이 필요합니다 | `claude --agents '{"reviewer":{"description":"Reviews code","prompt":"You are a code reviewer"}}'` |

68| `--allow-dangerously-skip-permissions` | `Shift+Tab` 모드 사이클에 `bypassPermissions`를 추가하되 시작하지 않습니다. `plan`과 같은 다른 모드에서 시작하고 나중에 `bypassPermissions`로 전환할 수 있습니다. [권한 모드](/docs/ko/permission-modes#skip-all-checks-with-bypasspermissions-mode)를 참조하세요 | `claude --permission-mode plan --allow-dangerously-skip-permissions` |68| `--allow-dangerously-skip-permissions` | `Shift+Tab` 모드 사이클에 `bypassPermissions`를 추가하되 시작하지 않습니다. `plan`과 같은 다른 모드에서 시작하고 나중에 `bypassPermissions`로 전환할 수 있습니다. [권한 모드](/docs/ko/permission-modes#skip-all-checks-with-bypasspermissions-mode)를 참조하세요 | `claude --permission-mode plan --allow-dangerously-skip-permissions` |

69| `--allowedTools`, `--allowed-tools` | 권한을 묻지 않고 실행되는 도구입니다. 패턴 매칭에 대해 [권한 규칙 구문](/docs/ko/settings-reference#permission-rule-syntax)을 참조하세요. 사용 가능한 도구를 제한하려면 대신 `--tools`를 사용하세요. [작업 추적 도구](/docs/ko/tools-reference#task-tool-availability) 중 하나를 여기에 이름 지으면 Claude Code도 세션을 옵트인합니다 | `"Bash(git log *)" "Bash(git diff *)" "Read"` |69| `--allowedTools`, `--allowed-tools` | 권한을 묻지 않고 실행되는 도구입니다. 패턴 매칭에 대해 [권한 규칙 구문](/docs/ko/settings-reference#permission-rule-syntax)을 참조하세요. 사용 가능한 도구를 제한하려면 대신 `--tools`를 사용하세요. [작업 추적 도구](/docs/ko/tools-reference#task-tool-availability) 중 하나를 여기에 이름 지으면 Claude Code도 세션을 옵트인합니다 | `"Bash(git log *)" "Bash(git diff *)" "Read"` |

70| `--append-subagent-system-prompt` | [포크된 서브에이전트](/docs/ko/sub-agents#fork-the-current-conversation)를 제외한 모든 [서브에이전트](/docs/ko/sub-agents)의 시스템 프롬프트 끝에 사용자 정의 텍스트를 추가합니다. 포크된 서브에이전트는 대화 자체의 프롬프트를 재사용합니다. 중첩된 서브에이전트를 포함합니다. `-p`를 사용한 비대화형 모드에서만 적용됩니다. Claude Code v2.1.205 이상이 필요합니다 | `claude -p --append-subagent-system-prompt "Cite file paths in every answer" "query"` |70| `--append-subagent-system-prompt` | [포크된 서브에이전트](/docs/ko/sub-agents#fork-the-current-conversation)를 제외한 모든 [서브에이전트](/docs/ko/sub-agents)의 시스템 프롬프트 끝에 사용자 정의 텍스트를 추가합니다. 포크된 서브에이전트는 대화 자체의 프롬프트를 재사용합니다. 중첩된 서브에이전트를 포함합니다. `-p`를 사용한 비대화형 모드에서만 적용됩니다. Claude Code v2.1.205 이상이 필요합니다 | `claude -p --append-subagent-system-prompt "Cite file paths in every answer" "query"` |

84| `--dangerously-skip-permissions` | 권한 프롬프트를 건너뜁니다. `--permission-mode bypassPermissions`과 동등합니다. 이것이 건너뛰는 것과 건너뛰지 않는 것에 대해 [권한 모드](/docs/ko/permission-modes#skip-all-checks-with-bypasspermissions-mode)를 참조하세요. `--bg`로 시작된 세션의 경우, 모드는 [감독자가 세션을 다시 시작할 때 유지됩니다](/docs/ko/agent-view#permission-mode-model-and-effort) | `claude --dangerously-skip-permissions` |84| `--dangerously-skip-permissions` | 권한 프롬프트를 건너뜁니다. `--permission-mode bypassPermissions`과 동등합니다. 이것이 건너뛰는 것과 건너뛰지 않는 것에 대해 [권한 모드](/docs/ko/permission-modes#skip-all-checks-with-bypasspermissions-mode)를 참조하세요. `--bg`로 시작된 세션의 경우, 모드는 [감독자가 세션을 다시 시작할 때 유지됩니다](/docs/ko/agent-view#permission-mode-model-and-effort) | `claude --dangerously-skip-permissions` |

85| `--debug` | `--debug='mcp,startup'` 또는 `--debug='!1p'`와 같은 선택적 카테고리 필터링으로 디버그 모드를 활성화합니다. 필터는 `=` 형식에서만 바인딩됩니다. 공백으로 구분된 필터는 필터링 없이 디버그 모드를 활성화합니다 | `claude --debug='mcp,startup'` |85| `--debug` | `--debug='mcp,startup'` 또는 `--debug='!1p'`와 같은 선택적 카테고리 필터링으로 디버그 모드를 활성화합니다. 필터는 `=` 형식에서만 바인딩됩니다. 공백으로 구분된 필터는 필터링 없이 디버그 모드를 활성화합니다 | `claude --debug='mcp,startup'` |

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

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

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

116| `--permission-prompts` | 인쇄 모드에서 권한 프롬프트에 응답하는 사람을 설정합니다. 기본 `host`를 사용하면 Claude Code는 Agent SDK 호스트 또는 `--permission-prompt-tool` 도구로 보냅니다. 아무도 응답할 수 없을 때 `none`을 전달하면 Claude Code는 대신 거부합니다. [무인 실행에서 권한 프롬프트 끄기](/docs/ko/headless#turn-off-permission-prompts-in-unattended-runs)를 참조하세요. Claude Code v2.1.259 이상이 필요합니다 | `claude -p --permission-prompts none "query"` |117| `--permission-prompts` | 인쇄 모드에서 권한 프롬프트에 응답하는 사람을 설정합니다. 기본 `host`를 사용하면 Claude Code는 Agent SDK 호스트 또는 `--permission-prompt-tool` 도구로 보냅니다. 아무도 응답할 수 없을 때 `none`을 전달하면 Claude Code는 대신 거부합니다. [무인 실행에서 권한 프롬프트 끄기](/docs/ko/headless#turn-off-permission-prompts-in-unattended-runs)를 참조하세요. Claude Code v2.1.259 이상이 필요합니다 | `claude -p --permission-prompts none "query"` |

117| `--plugin-dir` | 이 세션에만 디렉터리 또는 `.zip` 아카이브에서 플러그인을 로드하거나 [플러그인 폴더](/docs/ko/plugins/create#load-a-directory-or-archive-for-one-session)에서 여러 개를 로드합니다. 각 플래그는 하나의 경로를 사용합니다. 더 많은 경로에 대해 플래그를 반복합니다: `--plugin-dir A --plugin-dir B.zip`. 플러그인 폴더를 전달하려면 Claude Code v2.1.265 이상이 필요합니다 | `claude --plugin-dir ./my-plugin` |118| `--plugin-dir` | 이 세션에만 디렉터리 또는 `.zip` 아카이브에서 플러그인을 로드하거나 [플러그인 폴더](/docs/ko/plugins/create#load-a-directory-or-archive-for-one-session)에서 여러 개를 로드합니다. 각 플래그는 하나의 경로를 사용합니다. 더 많은 경로에 대해 플래그를 반복합니다: `--plugin-dir A --plugin-dir B.zip`. 플러그인 폴더를 전달하려면 Claude Code v2.1.265 이상이 필요합니다 | `claude --plugin-dir ./my-plugin` |

119| `--print`, `-p` | 대화형 모드 없이 응답을 인쇄합니다([프로그래밍 방식 사용에 대한 Agent SDK 문서](/docs/ko/agent-sdk/overview) 참조) | `claude -p "query"` |120| `--print`, `-p` | 대화형 모드 없이 응답을 인쇄합니다([프로그래밍 방식 사용에 대한 Agent SDK 문서](/docs/ko/agent-sdk/overview) 참조). `--resume`을 백그라운드 세션에서 여전히 실행 중인 경우 [세션 재개](/docs/ko/sessions#resume-a-running-background-session)를 참조하세요 | `claude -p "query"` |

120| `--prompt-suggestions` | 각 턴 후에 예측된 다음 사용자 프롬프트를 사용하여 `prompt_suggestion` 메시지를 내보냅니다. 매우 짧은 대화는 없을 수 있습니다. `--print`, `--output-format stream-json` 및 `--verbose`가 필요합니다. [프롬프트 제안](/docs/ko/interactive-mode#prompt-suggestions)을 참조하세요 | `claude -p --prompt-suggestions --output-format stream-json --verbose "query"` |121| `--prompt-suggestions` | 각 턴 후에 예측된 다음 사용자 프롬프트를 사용하여 `prompt_suggestion` 메시지를 내보냅니다. 매우 짧은 대화는 없을 수 있습니다. `--print`, `--output-format stream-json` 및 `--verbose`가 필요합니다. [프롬프트 제안](/docs/ko/interactive-mode#prompt-suggestions)을 참조하세요 | `claude -p --prompt-suggestions --output-format stream-json --verbose "query"` |

124| `--remote-control-session-name-prefix <prefix>` | 명시적 이름이 설정되지 않은 경우 자동 생성된 [Remote Control](/docs/ko/remote-control) 세션 이름의 접두사입니다. 기본값은 머신의 호스트 이름이며 `myhost-graceful-unicorn`과 같은 이름을 생성합니다. 동일한 효과를 위해 `CLAUDE_REMOTE_CONTROL_SESSION_NAME_PREFIX`를 설정합니다 | `claude remote-control --remote-control-session-name-prefix dev-box` |125| `--remote-control-session-name-prefix <prefix>` | 명시적 이름이 설정되지 않은 경우 자동 생성된 [Remote Control](/docs/ko/remote-control) 세션 이름의 접두사입니다. 기본값은 머신의 호스트 이름이며 `myhost-graceful-unicorn`과 같은 이름을 생성합니다. 동일한 효과를 위해 `CLAUDE_REMOTE_CONTROL_SESSION_NAME_PREFIX`를 설정합니다 | `claude remote-control --remote-control-session-name-prefix dev-box` |

125| `--replay-user-messages` | stdin에서 사용자 메시지를 다시 내보내 stdout으로 승인합니다. `--input-format stream-json` 및 `--output-format stream-json`이 필요합니다 | `claude -p --input-format stream-json --output-format stream-json --verbose --replay-user-messages` |126| `--replay-user-messages` | stdin에서 사용자 메시지를 다시 내보내 stdout으로 승인합니다. `--input-format stream-json` 및 `--output-format stream-json`이 필요합니다 | `claude -p --input-format stream-json --output-format stream-json --verbose --replay-user-messages` |

126| `--restricted` | 제한된 모드에서 시작합니다. 평가 하네스가 공유 머신에서 `claude`를 구동하고 Claude Code가 해당 머신의 명령을 실행하거나 사용자 및 프로젝트 설정을 읽지 않아야 할 때 사용합니다. Claude Code는 명령을 실행하거나 코드를 실행하는 기본 제공 도구와 WebFetch를 제거합니다. `--tools`에서 개별적으로 이름을 지정하지 않는 한 `default` 사전 설정을 통해서는 제거합니다. 또한 기본 제공 파일 도구를 [작업 디렉터리](/docs/ko/permissions#working-directories)로 제한하고, [관리되는 설정](/docs/ko/managed-settings) 및 `--settings`만 로드하며, [`bypassPermissions`](/docs/ko/permission-modes#skip-all-checks-with-bypasspermissions-mode)를 거부하고, [제한된 세션에서 클라우드 세션을 만드는 것을 거부합니다](/docs/ko/errors#cloud-sessions-cannot-be-created-from-a-restricted-session). Claude Code v2.1.248 이상이 필요합니다 | `claude --restricted -p "query"` |127| `--restricted` | 제한된 모드에서 시작합니다. 평가 하네스가 공유 머신에서 `claude`를 구동하고 Claude Code가 해당 머신의 명령을 실행하거나 사용자 및 프로젝트 설정을 읽지 않아야 할 때 사용합니다. Claude Code는 명령을 실행하거나 코드를 실행하는 기본 제공 도구와 WebFetch를 제거합니다. `--tools`에서 개별적으로 이름을 지정하지 않는 한 `default` 사전 설정을 통해서는 제거합니다. 또한 기본 제공 파일 도구를 [작업 디렉터리](/docs/ko/permissions#working-directories)로 제한하고, [관리되는 설정](/docs/ko/managed-settings) 및 `--settings`만 로드하며, [`bypassPermissions`](/docs/ko/permission-modes#skip-all-checks-with-bypasspermissions-mode)를 거부하고, [제한된 세션에서 클라우드 세션을 만드는 것을 거부합니다](/docs/ko/errors#cloud-sessions-cannot-be-created-from-a-restricted-session). Claude Code v2.1.248 이상이 필요합니다 | `claude --restricted -p "query"` |

127| `--resume`, `-r` | ID 또는 이름으로 특정 세션을 재개하거나 세션을 선택할 대화형 선택기를 표시합니다. ID 대신 세션의 `.jsonl` [트랜스크립트 파일](/docs/ko/sessions#where-transcripts-are-stored)의 절대 경로를 전달할 수 있습니다. 선택기 및 이름 검색에는 이 디렉터리를 `/add-dir`로 추가한 세션이 포함됩니다. 세션 ID를 전달하면 Claude Code는 현재 프로젝트 디렉터리 및 해당 git 워크트리를 검색한 다음 이 머신의 다른 모든 프로젝트를 검색합니다. v2.1.223 이전에는 ID 검색이 현재 프로젝트 디렉터리 및 해당 git 워크트리만 다루었습니다. [백그라운드 세션](/docs/ko/agent-view)은 `bg`로 표시된 선택기에 나타납니다 | `claude --resume auth-refactor` |128| `--resume`, `-r` | ID 또는 이름으로 특정 세션을 재개하거나 세션을 선택할 대화형 선택기를 표시합니다. ID 대신 세션의 `.jsonl` [트랜스크립트 파일](/docs/ko/sessions#where-transcripts-are-stored)의 절대 경로를 전달할 수 있습니다. 선택기 및 이름 검색에는 이 디렉터리를 `/add-dir`로 추가한 세션이 포함됩니다. 세션 ID를 전달하면 Claude Code는 현재 프로젝트 디렉터리 및 해당 git 워크트리를 검색한 다음 이 머신의 다른 모든 프로젝트를 검색합니다. v2.1.223 이전에는 ID 검색이 현재 프로젝트 디렉터리 및 해당 git 워크트리만 다루었습니다. [백그라운드 세션](/docs/ko/agent-view)은 `bg`로 표시된 선택기에 나타납니다. 여전히 실행 중인 세션을 재개하면 [해당 세션](/docs/ko/sessions#resume-a-running-background-session)을 `claude attach`를 통해 이 터미널에서 열고, 명령줄에 전달한 프롬프트는 다음 턴으로 이동합니다. v2.1.285 이전에는 Claude Code가 거부하고 대신 실행할 `claude attach` 명령을 인쇄했습니다 | `claude --resume auth-refactor` |

128| `--safe-mode` | 손상된 구성을 문제 해결하기 위해 모든 사용자 정의를 비활성화하여 시작합니다: CLAUDE.md, 스킬, 플러그인, 훅, MCP 서버, 사용자 정의 명령 및 에이전트, 출력 스타일, 워크플로우, 사용자 정의 테마, 사용자 정의 키 바인딩, 상태 줄 및 파일 제안 명령, LSP 서버 및 자동 메모리는 로드되지 않습니다. 인증, 모델 선택, 기본 제공 도구 및 권한은 정상적으로 작동하며, 이는 [`--bare`](/docs/ko/headless#start-faster-with-bare-mode)와 다릅니다. 관리되는 설정 정책은 여전히 적용되며, 정책 구성 훅, 상태 줄 및 파일 제안 명령을 포함합니다. 관리되는 플러그인, 관리되는 스킬, 관리되는 CLAUDE.md 및 정책 구성 MCP 서버는 포함되지 않습니다. [자동 모델 폴백](/docs/ko/model-config#automatic-model-fallback)을 트리거하는 사용자 정의를 확인하는 데 유용합니다. [`CLAUDE_CODE_SAFE_MODE`](/docs/ko/env-vars)를 설정합니다 | `claude --safe-mode` |129| `--safe-mode` | 손상된 구성을 문제 해결하기 위해 모든 사용자 정의를 비활성화하여 시작합니다: CLAUDE.md, 스킬, 플러그인, 훅, MCP 서버, 사용자 정의 명령 및 에이전트, 출력 스타일, 워크플로우, 사용자 정의 테마, 사용자 정의 키 바인딩, 상태 줄 및 파일 제안 명령, LSP 서버 및 자동 메모리는 로드되지 않습니다. 인증, 모델 선택, 기본 제공 도구 및 권한은 정상적으로 작동하며, 이는 [`--bare`](/docs/ko/headless#start-faster-with-bare-mode)와 다릅니다. 관리되는 설정 정책은 여전히 적용되며, 정책 구성 훅, 상태 줄 및 파일 제안 명령을 포함합니다. 관리되는 플러그인, 관리되는 스킬, 관리되는 CLAUDE.md 및 정책 구성 MCP 서버는 포함되지 않습니다. [자동 모델 폴백](/docs/ko/model-config#automatic-model-fallback)을 트리거하는 사용자 정의를 확인하는 데 유용합니다. [`CLAUDE_CODE_SAFE_MODE`](/docs/ko/env-vars)를 설정합니다 | `claude --safe-mode` |

130| `--setting-sources` | 로드할 설정 소스의 쉼표로 구분된 목록(`user`, `project`, `local`). [에이전트 뷰](/docs/ko/agent-view#what-carries-over-when-you-background) 및 [에이전트 팀](/docs/ko/agent-teams#context-and-communication)을 참조하여 이 세션에서 시작하는 세션이 목록을 상속하는 경우를 확인하세요 | `claude --setting-sources user,project` |131| `--setting-sources` | 로드할 설정 소스의 쉼표로 구분된 목록(`user`, `project`, `local`). [에이전트 뷰](/docs/ko/agent-view#what-carries-over-when-you-background) 및 [에이전트 팀](/docs/ko/agent-teams#context-and-communication)을 참조하여 이 세션에서 시작하는 세션이 목록을 상속하는 경우를 확인하세요 | `claude --setting-sources user,project` |

cloud-environments.md +5 −4

Details

56 </Step>56 </Step>

57 57

58 <Step title="환경 추가 또는 편집">58 <Step title="환경 추가 또는 편집">

59 **Add cloud environment**를 선택하거나, 기존 환경 위에 마우스를 올리고 오른쪽에 나타나는 설정 아이콘을 선택합니다. 대화 상자에는 이름, 네트워크 액세스 수준, 환경 변수 및 설정 스크립트가 포함됩니다. Pro 또는 Max 플랜에서 기존 클라우드 환경을 편집할 때 대화 상자에는 [API 자격 증명](#add-api-credentials)도 포함됩니다.59 **Cloud**를 선택하여 환경을 나열합니다. 그런 다음 **Add cloud environment**를 선택하거나, 기존 환경 위에 마우스를 올리고 오른쪽에 나타나는 설정 아이콘을 선택합니다.

61 대화 상자에는 이름, 네트워크 액세스 수준, 환경 변수 및 설정 스크립트가 포함됩니다. Pro 또는 Max 플랜에서 기존 클라우드 환경을 편집할 때 대화 상자에는 [API 자격 증명](#add-api-credentials)도 포함됩니다.

60 62

61 <Frame>63 <Frame>

62 <img src="https://mintcdn.com/claude-code/ZFId6l95856c5LSw/images/cloud-environment-dialog.png?fit=max&auto=format&n=ZFId6l95856c5LSw&q=85&s=30d4478b31d1f879f7ee287ddab32505" alt="New cloud environment 대화 상자입니다. 기본값 자리 표시자가 있는 Name 필드, Trusted로 설정된 Network access 선택기(네트워크 정책 및 액세스 수준에 대한 링크 포함), .env 형식 자리 표시자 텍스트가 있는 Environment variables 상자(환경을 사용하는 모든 사람이 값을 볼 수 있다는 참고 사항 포함), Claude Code가 시작되기 전에 새 세션이 시작될 때 실행되는 Bash 스크립트로 설명된 Setup script 상자, 그리고 Cancel 및 Create environment 버튼이 있습니다." width="874" height="1372" data-path="images/cloud-environment-dialog.png" />64 <img src="https://mintcdn.com/claude-code/ZFId6l95856c5LSw/images/cloud-environment-dialog.png?fit=max&auto=format&n=ZFId6l95856c5LSw&q=85&s=30d4478b31d1f879f7ee287ddab32505" alt="New cloud environment 대화 상자입니다. 기본값 자리 표시자가 있는 Name 필드, Trusted로 설정된 Network access 선택기(네트워크 정책 및 액세스 수준에 대한 링크 포함), .env 형식 자리 표시자 텍스트가 있는 Environment variables 상자(환경을 사용하는 모든 사람이 값을 볼 수 있다는 참고 사항 포함), Claude Code가 시작되기 전에 새 세션이 시작될 때 실행되는 Bash 스크립트로 설명된 Setup script 상자, 그리고 Cancel 및 Create environment 버튼이 있습니다." width="874" height="1372" data-path="images/cloud-environment-dialog.png" />

108* **Role**: claude.ai 조직의 조직 관리자 역할110* **Role**: claude.ai 조직의 조직 관리자 역할

109 * Team 및 Enterprise에서는 Owner가 보유하고 Admin은 보유하지 않습니다.111 * Team 및 Enterprise에서는 Owner가 보유하고 Admin은 보유하지 않습니다.

110 * Pro 및 Max에서는 자신의 조직에서 보유합니다.112 * Pro 및 Max에서는 자신의 조직에서 보유합니다.

111 * 이 역할이 없으면 자신의 환경에서도 자격 증명 목록 대신 참고 사항이 표시됩니다. Owner에게 공유 환경에 자격 증명을 추가하고 해당 환경에서 세션을 실행하도록 요청하십시오.

112* **Environment type**: 이미 존재하는 Anthropic 호스팅 클라우드 환경입니다. [자체 호스팅 환경](/docs/ko/self-hosted-environments)에는 API 자격 증명이 없습니다.113* **Environment type**: 이미 존재하는 Anthropic 호스팅 클라우드 환경입니다. [자체 호스팅 환경](/docs/ko/self-hosted-environments)에는 API 자격 증명이 없습니다.

113* **API reachability**: API가 인터넷에서의 연결을 수락합니다. 요청이 Anthropic의 네트워크에서 나가기 때문입니다.114* **API reachability**: API가 인터넷에서의 연결을 수락합니다. 요청이 Anthropic의 네트워크에서 나가기 때문입니다.

114* **Encryption keys**: 조직이 고객 관리 암호화 키를 사용하는 경우 자격 증명을 저장할 수 없습니다.115* **Encryption keys**: 조직이 고객 관리 암호화 키를 사용하는 경우 자격 증명을 저장할 수 없습니다.

121 122

122<Steps>123<Steps>

123 <Step title="환경의 API 자격 증명 열기">124 <Step title="환경의 API 자격 증명 열기">

124 [claude.ai/code](https://claude.ai/code)의 환경 선택기에서 [편집할 환경을 열기](#configure-your-environment)합니다. **Update cloud environment** 대화 상자에서 **Environment variables** 아래에 **API credentials**를 찾습니다. 환경에 이미 있는 자격 증명과 적용되는 호스트를 볼 수 있습니다.125 [claude.ai/code](https://claude.ai/code)의 환경 선택기에서 [편집할 환경을 열기](#configure-your-environment)합니다. **Edit cloud environment** 대화 상자에서 **Environment variables** 아래에 **API credentials**를 찾습니다. 환경에 이미 있는 자격 증명과 적용되는 호스트를 볼 수 있습니다.

125 </Step>126 </Step>

126 127

127 <Step title="자격 증명 추가">128 <Step title="자격 증명 추가">

439 440

440* **Claude가 실행하는 명령**: 클라우드 환경은 자신의 명령 타임아웃을 설정하지 않으므로 Bash 도구의 기본값이 적용됩니다. Claude는 기본적으로 명령을 2분 동안 기다리며 최대 10분까지 요청할 수 있습니다.441* **Claude가 실행하는 명령**: 클라우드 환경은 자신의 명령 타임아웃을 설정하지 않으므로 Bash 도구의 기본값이 적용됩니다. Claude는 기본적으로 명령을 2분 동안 기다리며 최대 10분까지 요청할 수 있습니다.

441 442

442 명령이 [타임아웃](/docs/ko/tools-reference#timeout-and-output-limits)에 도달하면 Claude Code는 명령이 `sleep`으로 시작하지 않는 한 명령을 중지하는 대신 [백그라운드로 이동](/docs/ko/tools-reference#background-commands)합니다. 이런 방식으로 이동된 명령은 Claude Code가 [백그라운드 시간 제한](/docs/ko/tools-reference#background-commands)에서 중지하기 전에 최대 30분 더 실행될 수 있습니다. `BASH_DEFAULT_TIMEOUT_MS`를 `1800000` 밀리초 이상으로 설정하면 해당 제한과 포그라운드 기본값이 모두 길어집니다.443 명령이 [타임아웃](/docs/ko/tools-reference#timeout-and-output-limits)에 도달하면 Claude Code는 명령이 `sleep`으로 시작하지 않는 한 명령을 중지하는 대신 [백그라운드로 이동](/docs/ko/tools-reference#foreground-commands-that-move-to-the-background)합니다. 이런 방식으로 이동된 명령은 Claude Code가 [백그라운드 시간 제한](/docs/ko/tools-reference#time-limit-for-background-commands)에서 중지하기 전에 최대 30분 더 실행될 수 있습니다. `BASH_DEFAULT_TIMEOUT_MS`를 `1800000` 밀리초 이상으로 설정하면 해당 제한과 포그라운드 기본값이 모두 길어집니다.

443* **SessionStart 훅**: Claude Code는 [`timeout`](/docs/ko/hooks#common-fields)을 초 단위로 설정하지 않으면 600초 후 `command` 훅을 취소합니다. Claude Code는 [`async: true`](/docs/ko/hooks#run-hooks-in-the-background)로 실행하는 훅에 타임아웃을 적용하지 않습니다.444* **SessionStart 훅**: Claude Code는 [`timeout`](/docs/ko/hooks#common-fields)을 초 단위로 설정하지 않으면 600초 후 `command` 훅을 취소합니다. Claude Code는 [`async: true`](/docs/ko/hooks#run-hooks-in-the-background)로 실행하는 훅에 타임아웃을 적용하지 않습니다.

444* **설정 스크립트**: 대략 5분 이상 걸리는 스크립트는 캐시되지 않습니다. [스크립트 요구 사항](#script-requirements)은 그 이하로 유지하는 방법을 다룹니다.445* **설정 스크립트**: 대략 5분 이상 걸리는 스크립트는 캐시되지 않습니다. [스크립트 요구 사항](#script-requirements)은 그 이하로 유지하는 방법을 다룹니다.

445* **유휴 세션**: 몇 분 동안 활동이 없으면 세션의 VM이 파일이 저장된 상태로 일시 중지되고, 일시 중지된 VM은 나중에 회수될 수 있습니다. [환경 변수 설정](#set-environment-variables)은 각 경우에 세션이 선택하는 항목을 설명하고, [Environment expired](/docs/ko/claude-code-on-the-web#environment-expired)는 VM이 회수된 세션을 다시 여는 방법을 다룹니다.446* **유휴 세션**: 몇 분 동안 활동이 없으면 세션의 VM이 파일이 저장된 상태로 일시 중지되고, 일시 중지된 VM은 나중에 회수될 수 있습니다. [환경 변수 설정](#set-environment-variables)은 각 경우에 세션이 선택하는 항목을 설명하고, [Environment expired](/docs/ko/claude-code-on-the-web#environment-expired)는 VM이 회수된 세션을 다시 여는 방법을 다룹니다.

commands.md +1 −1

Details

132| `/remote-control` | 이 세션을 claude.ai에서 [원격 제어](/docs/ko/remote-control)에 사용 가능하게 합니다. 로그아웃 상태에서 실행하면 원격 제어에 claude.ai 구독이 필요하고 로그인 방법을 알려줍니다. v2.1.206 이전에는 `Unknown command: /remote-control`을 보고했습니다. 별칭: `/rc` |132| `/remote-control` | 이 세션을 claude.ai에서 [원격 제어](/docs/ko/remote-control)에 사용 가능하게 합니다. 로그아웃 상태에서 실행하면 원격 제어에 claude.ai 구독이 필요하고 로그인 방법을 알려줍니다. v2.1.206 이전에는 `Unknown command: /remote-control`을 보고했습니다. 별칭: `/rc` |

133| `/remote-env` | 클라우드 세션에 대한 기본 [클라우드 환경](/docs/ko/cloud-environments#select-an-environment-from-the-cli)을 선택합니다. CLI에서 시작합니다. |133| `/remote-env` | 클라우드 세션에 대한 기본 [클라우드 환경](/docs/ko/cloud-environments#select-an-environment-from-the-cli)을 선택합니다. CLI에서 시작합니다. |

134| `/rename [name]` | 현재 세션의 이름을 바꾸고 프롬프트 바에 이름을 표시합니다. 이름 없이 대화 기록에서 자동 생성합니다. 비대화형 모드(`-p`)에서도 사용 가능합니다. Claude Code v2.1.205 이상이 필요합니다. claude.ai 및 데스크톱 앱을 포함한 모든 이름 바꾸기 표면에서 Claude Code는 새 이름의 제어 및 보이지 않는 문자를 공백으로 바꾸고 이름을 200자로 제한합니다. 보이지 않는 문자가 제거되면 이름이 비어 있으면 Claude Code가 거부하고 `That name is empty once invisible characters are removed. Usage: /rename <name>`을 표시합니다. 문자 교체 및 길이 제한은 Claude Code v2.1.221 이상이 필요합니다. 이 컴퓨터의 다른 라이브 세션이 전달한 이름을 이미 사용하면 Claude Code가 [변형을 적용](/docs/ko/sessions#name-your-sessions)합니다. |134| `/rename [name]` | 현재 세션의 이름을 바꾸고 프롬프트 바에 이름을 표시합니다. 이름 없이 대화 기록에서 자동 생성합니다. 비대화형 모드(`-p`)에서도 사용 가능합니다. Claude Code v2.1.205 이상이 필요합니다. claude.ai 및 데스크톱 앱을 포함한 모든 이름 바꾸기 표면에서 Claude Code는 새 이름의 제어 및 보이지 않는 문자를 공백으로 바꾸고 이름을 200자로 제한합니다. 보이지 않는 문자가 제거되면 이름이 비어 있으면 Claude Code가 거부하고 `That name is empty once invisible characters are removed. Usage: /rename <name>`을 표시합니다. 문자 교체 및 길이 제한은 Claude Code v2.1.221 이상이 필요합니다. 이 컴퓨터의 다른 라이브 세션이 전달한 이름을 이미 사용하면 Claude Code가 [변형을 적용](/docs/ko/sessions#name-your-sessions)합니다. |

135| `/resume [session]` | ID 또는 이름으로 대화를 재개하거나 세션 선택기를 엽니다. [백그라운드 세션](/docs/ko/agent-view)은 선택기에 `bg`로 표시됩니다. 아직 실행 중인 세션은 여기서 재개할 수 없으므로 `claude agents`에서 첨부하거나 먼저 중지합니다. 별칭: `/continue` |135| `/resume [session]` | ID 또는 이름으로 대화를 재개하거나 세션 선택기를 엽니다. [백그라운드 세션](/docs/ko/agent-view)은 선택기에 `bg`로 표시됩니다. 선택기 또는 ID 또는 이름으로 아직 실행 중인 세션을 재개하면 [해당 세션을 엽니다](/docs/ko/sessions#resume-a-running-background-session). 현재 대화가 백그라운드로 이동하고 이 터미널이 실행 중인 세션에 첨부됩니다. 빈 프롬프트에서 `←`를 눌러 에이전트 보기로 돌아갑니다. 이는 또한 남겨둔 대화를 나열합니다. v2.1.285 이전에는 Claude Code가 거부하고 `claude attach`를 사용하거나 먼저 중지하도록 지시했습니다. 별칭: `/continue` |

136| `/review [low\|medium\|high\|xhigh\|max\|ultra] [--fix] [--comment] [pr#\|branch\|path]` | [`/code-review`](/docs/ko/code-review#review-a-diff-locally)의 별칭입니다. 현재 diff 또는 전달한 PR 번호, 분기 또는 경로(예: `/review 1234`)를 검토하고 동일한 노력 수준 및 플래그를 사용합니다. 수준이 지정되지 않으면 검토가 마지막으로 입력한 `low`~~`max` 수준을 재사용합니다. 정확한 규칙은 [로컬에서 diff 검토](/docs/ko/code-review#review-a-diff-locally)를 참조하십시오. 깊은 클라우드 검토의 경우 [`/code-review ultra`](/docs/ko/ultrareview)를 사용합니다. v2.1.223 이전에는 `/review`가 GitHub 풀 요청을 번호로 검토하는 별도의 명령어였으며, 인수 없이 실행할 때 열린 PR을 나열하여 선택합니다. v2.1.186~~v2.1.201에서는 `/code-review medium`과 동일한 다중 에이전트 엔진을 실행했습니다. |136| `/review [low\|medium\|high\|xhigh\|max\|ultra] [--fix] [--comment] [pr#\|branch\|path]` | [`/code-review`](/docs/ko/code-review#review-a-diff-locally)의 별칭입니다. 현재 diff 또는 전달한 PR 번호, 분기 또는 경로(예: `/review 1234`)를 검토하고 동일한 노력 수준 및 플래그를 사용합니다. 수준이 지정되지 않으면 검토가 마지막으로 입력한 `low`~~`max` 수준을 재사용합니다. 정확한 규칙은 [로컬에서 diff 검토](/docs/ko/code-review#review-a-diff-locally)를 참조하십시오. 깊은 클라우드 검토의 경우 [`/code-review ultra`](/docs/ko/ultrareview)를 사용합니다. v2.1.223 이전에는 `/review`가 GitHub 풀 요청을 번호로 검토하는 별도의 명령어였으며, 인수 없이 실행할 때 열린 PR을 나열하여 선택합니다. v2.1.186~~v2.1.201에서는 `/code-review medium`과 동일한 다중 에이전트 엔진을 실행했습니다. |

137| `/rewind` | 대화 및/또는 코드를 이전 지점으로 되감기하거나 선택한 메시지에서 요약합니다. [체크포인팅](/docs/ko/checkpointing)을 참조하십시오. 별칭: `/checkpoint`, `/undo` |137| `/rewind` | 대화 및/또는 코드를 이전 지점으로 되감기하거나 선택한 메시지에서 요약합니다. [체크포인팅](/docs/ko/checkpointing)을 참조하십시오. 별칭: `/checkpoint`, `/undo` |

138| `/run` | **[스킬](/docs/ko/skills#bundled-skills).** 프로젝트의 앱을 시작하고 구동하여 테스트를 통과하는 것뿐만 아니라 변경 사항이 작동하는 것을 확인합니다. [앱 실행 및 확인](/docs/ko/skills#run-and-verify-your-app)을 참조하십시오. |138| `/run` | **[스킬](/docs/ko/skills#bundled-skills).** 프로젝트의 앱을 시작하고 구동하여 테스트를 통과하는 것뿐만 아니라 변경 사항이 작동하는 것을 확인합니다. [앱 실행 및 확인](/docs/ko/skills#run-and-verify-your-app)을 참조하십시오. |

context-window.md +1 −1

Details

1634 1634

1635더 작은 대화보다 더 큰 윈도우가 필요한 경우 Fable 모델, Sonnet 5 이상, Opus 4.6 이상, Sonnet 4.6은 100만 토큰 컨텍스트 윈도우를 지원합니다. 플랜별 가용성 및 `[1m]` 모델 변형을 선택하는 방법은 [확장 컨텍스트](/docs/ko/model-config#extended-context)를 참조하세요. 압축은 더 큰 제한에서도 동일한 방식으로 작동합니다.1635더 작은 대화보다 더 큰 윈도우가 필요한 경우 Fable 모델, Sonnet 5 이상, Opus 4.6 이상, Sonnet 4.6은 100만 토큰 컨텍스트 윈도우를 지원합니다. 플랜별 가용성 및 `[1m]` 모델 변형을 선택하는 방법은 [확장 컨텍스트](/docs/ko/model-config#extended-context)를 참조하세요. 압축은 더 큰 제한에서도 동일한 방식으로 작동합니다.

1636 1636

1637Sonnet 5.5 및 Sonnet 5는 1M 컨텍스트 윈도우로 실행되며 선택할 `[1m]` 변형이 없습니다. [Sonnet 5.5 및 Sonnet 5 컨텍스트 윈도우](/docs/ko/model-config#sonnet-5-5-and-sonnet-5-context-window)에서 자동 압축 임계값과 LLM 게이트웨이 예외를 참조하세요.1637Sonnet 5.5 및 Sonnet 5는 1M 컨텍스트 윈도우로 실행되며 선택할 `[1m]` 변형이 없습니다. [Sonnet 5.5 및 Sonnet 5 컨텍스트 윈도우](/docs/ko/model-config#sonnet-5-5-and-sonnet-5-context-window)에서 자동 압축 임계값을 참조하고, [게이트웨이 뒤의 컨텍스트 윈도우](/docs/ko/model-config#context-window-behind-a-gateway)에서 `ANTHROPIC_BASE_URL`을 [LLM 게이트웨이](/docs/ko/llm-gateway)로 설정할 때 Claude Code가 윈도우 크기를 조정하는 방법을 참조하세요.

1638 1638

1639자동 압축이 실행되는 지점은 모델과 구성에 따라 다릅니다. [기본 자동 압축 임계값](/docs/ko/model-config#default-auto-compact-thresholds)에서 모델별 경계를 참조하고, Claude Code가 모델 ID(예: [LLM 게이트웨이](/docs/ko/llm-gateway) 별칭)에 대해 잘못된 윈도우를 가정하는 경우 [게이트웨이 또는 사용자 정의 모델 ID에 대한 윈도우 수정](/docs/ko/model-config#correct-the-window-for-a-gateway-or-custom-model-id)을 참조하세요.1639자동 압축이 실행되는 지점은 모델과 구성에 따라 다릅니다. [기본 자동 압축 임계값](/docs/ko/model-config#default-auto-compact-thresholds)에서 모델별 경계를 참조하고, Claude Code가 모델 ID(예: [LLM 게이트웨이](/docs/ko/llm-gateway) 별칭)에 대해 잘못된 윈도우를 가정하는 경우 [게이트웨이 또는 사용자 정의 모델 ID에 대한 윈도우 수정](/docs/ko/model-config#correct-the-window-for-a-gateway-or-custom-model-id)을 참조하세요.

1640 1640

costs.md +2 −2

Details

51 51

52줄의 미스, 예상 재구축 및 따뜻함 또는 차가움 부분은 다음을 의미합니다:52줄의 미스, 예상 재구축 및 따뜻함 또는 차가움 부분은 다음을 의미합니다:

53 53

54* **Misses**: 캐시가 이미 보유한 콘텐츠를 다시 처리한 요청이며, 마지막 미스의 시간과 해당 요청이 캐시에 다시 작성한 토큰 수입니다. Claude Code는 요청이 캐시에서 읽을 수 있었던 것의 5% 이상 및 최소 2,000개 토큰을 다시 처리할 때 요청을 미스로 계산합니다. [캐시를 무효화하는 작업](/docs/ko/prompt-caching#actions-that-invalidate-the-cache)은 일반적인 원인을 나열합니다. Claude Code가 마지막 미스의 가능한 원인을 식별할 수 있을 때, 줄은 이를 이름으로 지정합니다. 예를 들어 `likely cause: tool definitions changed`입니다. 가능한 원인 텍스트는 Claude Code v2.1.260 이상이 필요합니다.54* **Misses**: 캐시가 이미 보유한 콘텐츠를 다시 처리한 요청이며, 마지막 미스의 시간과 해당 요청이 캐시에 다시 작성한 토큰 수입니다. [캐시를 무효화하는 작업](/docs/ko/prompt-caching#actions-that-invalidate-the-cache)은 일반적인 원인을 나열합니다. Claude Code가 마지막 미스의 가능한 원인을 식별할 수 있을 때, 줄은 이를 이름으로 지정합니다. 예를 들어 `likely cause: tool definitions changed`입니다. 가능한 원인 텍스트는 Claude Code v2.1.260 이상이 필요합니다.

55* **Expected rebuilds**: Claude Code가 [압축](/docs/ko/prompt-caching#compacting-the-conversation)을 통해 또는 컨텍스트에서 이전 도구 결과를 지워서 대화를 다시 작성했을 때, 동일한 종류의 미스를 예상 재구축으로 계산합니다. 이 부분은 최소 하나의 예상 재구축이 발생한 후에만 나타납니다.55* **Expected rebuilds**: Claude Code가 [압축](/docs/ko/prompt-caching#compacting-the-conversation)을 통해 또는 컨텍스트에서 이전 도구 결과를 지워서 대화를 다시 작성했을 때, 동일한 종류의 미스를 예상 재구축으로 계산합니다. 이 부분은 최소 하나의 예상 재구축이 발생한 후에만 나타납니다.

56* **Warm or cold**: 캐시된 접두사가 여전히 [캐시 수명](/docs/ko/prompt-caching#cache-lifetime) 내에 있는지 여부이며, 적용 중인 TTL입니다. 캐시가 차가울 때, 줄은 세션이 유휴 상태인 기간을 표시합니다. 응답이 캐시 토큰을 보고하지 않았을 때, 줄은 대신 `no prompt caching reported by the API`로 끝납니다.56* **Warm or cold**: 캐시된 접두사가 여전히 [캐시 수명](/docs/ko/prompt-caching#cache-lifetime) 내에 있는지 여부이며, 적용 중인 TTL입니다. 캐시가 차가울 때, 줄은 세션이 유휴 상태인 기간을 표시합니다. 응답이 캐시 토큰을 보고하지 않았을 때, 줄은 대신 `no prompt caching reported by the API`로 끝납니다.

57 57

263`/usage`를 사용하여 현재 토큰 사용량을 확인하거나, [상태 줄을 구성](/docs/ko/statusline#context-window-usage)하여 지속적으로 표시하십시오.263`/usage`를 사용하여 현재 토큰 사용량을 확인하거나, [상태 줄을 구성](/docs/ko/statusline#context-window-usage)하여 지속적으로 표시하십시오.

264 264

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

266* **사용자 정의 compaction 지침 추가**: `/compact Focus on code samples and API usage`는 Claude에게 요약 중에 보존할 내용을 알려줍니다. 새로운 세션에서는 아직 대화 기록이 없기 때문에 `/compact`를 실행하면 `Not enough messages to compact.`를 출력합니다.266* **사용자 정의 compaction 지침 추가**: `/compact Focus on code samples and API usage`는 Claude에게 요약 중에 보존할 내용을 알려줍니다.

267 267

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

269 269

desktop.md +9 −1

Details

751 751

752클라우드 세션은 앱을 닫아도 백그라운드에서 계속됩니다. 사용량은 별도의 컴퓨팅 요금 없이 [구독 계획 한도](/docs/ko/costs)에 포함됩니다.752클라우드 세션은 앱을 닫아도 백그라운드에서 계속됩니다. 사용량은 별도의 컴퓨팅 요금 없이 [구독 계획 한도](/docs/ko/costs)에 포함됩니다.

753 753

754다양한 네트워크 액세스 수준 및 환경 변수를 가진 사용자 정의 클라우드 환경을 만들 수 있습니다. 클라우드 세션을 시작할 때 프롬프트 상자의 환경 드롭다운을 열어 이를 관리합니다:754다양한 네트워크 액세스 수준 및 환경 변수를 가진 사용자 정의 클라우드 환경을 만들 수 있습니다. 이를 관리하려면 프롬프트 상자의 환경 드롭다운을 열고 **Cloud**를 선택합니다:

755 755

756* **환경 추가**: **클라우드 환경 추가**를 선택합니다756* **환경 추가**: **클라우드 환경 추가**를 선택합니다

757* **자신의 환경 중 하나를 편집하거나 보관**: 위에 마우스를 올린 다음 기어 아이콘을 클릭합니다757* **자신의 환경 중 하나를 편집하거나 보관**: 위에 마우스를 올린 다음 기어 아이콘을 클릭합니다

967 967

968CLI 세션을 Desktop으로 이동하려면 터미널에서 `/desktop`을 실행하세요. Claude가 세션을 저장하고 데스크톱 앱에서 열은 후 CLI를 종료합니다. 이 명령은 Claude 구독으로 로그인했을 때 macOS 및 x64 Windows에서 사용 가능합니다. API 키 인증이나 Amazon Bedrock, Google Cloud의 Agent Platform, Microsoft Foundry에서는 사용할 수 없습니다.968CLI 세션을 Desktop으로 이동하려면 터미널에서 `/desktop`을 실행하세요. Claude가 세션을 저장하고 데스크톱 앱에서 열은 후 CLI를 종료합니다. 이 명령은 Claude 구독으로 로그인했을 때 macOS 및 x64 Windows에서 사용 가능합니다. API 키 인증이나 Amazon Bedrock, Google Cloud의 Agent Platform, Microsoft Foundry에서는 사용할 수 없습니다.

969 969

970셸에서 [`claude --desktop`](/docs/ko/cli-reference#cli-flags)은 터미널 세션을 시작하지 않고 Desktop을 직접 엽니다. Claude Code v2.1.285 이상이 필요하며 `/desktop`과 동일한 플랫폼 및 로그인 요구 사항이 있습니다. 다른 인수가 없으면 현재 디렉토리에서 Desktop을 엽니다. Desktop에서 기존 CLI 세션을 열려면 이 디렉토리의 가장 최근 대화를 위해 `--continue`를 추가하거나, `/status`가 표시하는 세션 ID로 `--resume`을 추가합니다:

971

972```bash theme={null}

973claude --desktop --resume <session-id>

974```

975

976Claude Code는 `Opening session <session-id> in Claude Desktop`을 출력하고, 세션이 앱에서 열리며, 명령이 종료됩니다. 세션 이름은 ID 대신 작동하지 않습니다. Claude Code는 다른 터미널에서 열려 있거나 백그라운드에서 여전히 실행 중인 세션을 이동하지 않습니다. Claude Desktop이 설치되지 않은 경우, 명령은 다운로드 링크를 출력하고 종료됩니다.

977

970Desktop 내에서 `/resume`을 사용하여 CLI 세션을 계속할 수도 있습니다. 이 명령은 로컬 세션에서 사용 가능하며, SSH, WSL 또는 클라우드 세션에서는 사용할 수 없습니다.978Desktop 내에서 `/resume`을 사용하여 CLI 세션을 계속할 수도 있습니다. 이 명령은 로컬 세션에서 사용 가능하며, SSH, WSL 또는 클라우드 세션에서는 사용할 수 없습니다.

971 979

972Desktop에서 터미널 세션을 계속하려면:980Desktop에서 터미널 세션을 계속하려면:

desktop-linux.md +12 −0

Details

163 163

164`claude-desktop`이 이 메시지와 함께 종료되면 root로 실행했습니다. 일반 사용자로 로그인하고 거기서 실행하십시오.164`claude-desktop`이 이 메시지와 함께 종료되면 root로 실행했습니다. 일반 사용자로 로그인하고 거기서 실행하십시오.

165 165

166<h3 id="your-sign-in-won’t-be-saved-on-this-device">

167 이 기기에서 로그인이 저장되지 않습니다

168</h3>

169

170Claude Desktop은 GNOME Keyring 또는 KDE Wallet과 같은 데스크톱의 키링에 로그인을 저장합니다. 잠금 해제된 키링에 도달할 수 없으면 로그인이 저장되지 않으며 앱을 실행할 때마다 다시 로그인합니다. 시스템과 일치하는 경우를 선택하십시오:

171

172* **키링이 설치되지 않음, KDE Plasma 이외의 데스크톱**: `--no-install-recommends`로 설치했거나 권장 패키지를 건너뛰는 최소 이미지에서 apt가 키링을 설치하지 않았습니다. `sudo apt install gnome-keyring`으로 GNOME Keyring을 설치하십시오.

173* **GNOME Keyring도 설치된 KDE Plasma**: KDE Wallet은 Plasma 데스크톱과 함께 제공됩니다. 두 키링이 충돌하며 KDE Wallet이 작동하더라도 Claude Desktop이 이 알림을 표시할 수 있습니다. `sudo apt remove gnome-keyring`으로 추가 항목을 제거한 후 컴퓨터를 다시 시작하십시오.

174* **키링이 설치되었지만 잠금됨**: 잠금을 해제하십시오.

175

176수정 후 앱을 다시 시작하고 로그인하십시오. 그런 다음 앱을 종료했다가 다시 실행하여 앱이 여전히 로그인된 상태로 열리는지 확인하십시오.

177

166<h3 id="cowork-isn’t-available">178<h3 id="cowork-isn’t-available">

167 Cowork를 사용할 수 없음179 Cowork를 사용할 수 없음

168</h3>180</h3>

desktop-quickstart.md +1 −1

Details

135 135

136**Claude를 일정에 따라 실행.** [예약된 작업](/docs/ko/desktop-scheduled-tasks)을 설정하여 Claude를 정기적으로 자동으로 실행합니다: 매일 아침 일일 코드 검토, 주간 종속성 감사 또는 연결된 도구에서 정보를 가져오는 브리핑입니다.136**Claude를 일정에 따라 실행.** [예약된 작업](/docs/ko/desktop-scheduled-tasks)을 설정하여 Claude를 정기적으로 자동으로 실행합니다: 매일 아침 일일 코드 검토, 주간 종속성 감사 또는 연결된 도구에서 정보를 가져오는 브리핑입니다.

137 137

138**준비가 되면 확장.** 사이드바에서 [병렬 세션](/docs/ko/desktop#work-in-parallel-with-sessions)을 열어 여러 작업을 동시에 수행하고, 각각 자체 Git worktree에서 실행하고, [작업 창](/docs/ko/desktop#watch-background-tasks)을 열어 세션이 실행 중인 서브에이전트 및 백그라운드 명령어를 봅니다. [사이드 채팅](/docs/ko/desktop#ask-a-side-question-without-derailing-the-session)을 열어 메인 스레드를 방해하지 않고 질문을 할 수 있습니다. [장기 실행 작업을 클라우드로 전송](/docs/ko/desktop#run-long-running-tasks-in-the-cloud)하여 앱을 닫아도 계속 실행되도록 하거나, 작업이 예상보다 오래 걸리면 [웹 또는 IDE에서 세션을 계속](/docs/ko/desktop#continue-in-another-surface)할 수 있습니다. [GitHub, Slack 및 Linear와 같은 외부 도구를 연결](/docs/ko/desktop#extend-claude-code)하여 워크플로우를 통합합니다.138**준비가 되면 확장.** 사이드바에서 [병렬 세션](/docs/ko/desktop#work-in-parallel-with-sessions)을 열어 여러 작업을 동시에 수행하고, 필요에 따라 각각 자체 Git worktree에서 실행하고, [작업 창](/docs/ko/desktop#watch-background-tasks)을 열어 세션이 실행 중인 서브에이전트 및 백그라운드 명령어를 봅니다. [사이드 채팅](/docs/ko/desktop#ask-a-side-question-without-derailing-the-session)을 열어 메인 스레드를 방해하지 않고 질문을 할 수 있습니다. [장기 실행 작업을 클라우드로 전송](/docs/ko/desktop#run-long-running-tasks-in-the-cloud)하여 앱을 닫아도 계속 실행되도록 하거나, 작업이 예상보다 오래 걸리면 [웹 또는 IDE에서 세션을 계속](/docs/ko/desktop#continue-in-another-surface)할 수 있습니다. [GitHub, Slack 및 Linear와 같은 외부 도구를 연결](/docs/ko/desktop#extend-claude-code)하여 워크플로우를 통합합니다.

139 139

140<h2 id="what’s-next">140<h2 id="what’s-next">

141 다음 단계141 다음 단계

errors.md +60 −7

Details

333| `Claude Code can't start: your organization's managed settings block the default model` / `Claude Code can't start: your organization allows only the models listed in "availableModels"` | [구성 경고](#managed-settings-block-the-default-model) |333| `Claude Code can't start: your organization's managed settings block the default model` / `Claude Code can't start: your organization allows only the models listed in "availableModels"` | [구성 경고](#managed-settings-block-the-default-model) |

334| `Your organization's managed settings allow Claude Code to use: <providers>` | [구성 경고](#managed-settings-dont-allow-this-api-provider) |

335| `Your organization's managed settings allow Claude Code to use no API provider at all` | [구성 경고](#managed-settings-dont-allow-this-api-provider) |

334| `MCP server <name> is blocked by enterprise managed policy` | [구성 경고](#mcp-server-is-blocked-by-enterprise-managed-policy) |336| `MCP server <name> is blocked by enterprise managed policy` | [구성 경고](#mcp-server-is-blocked-by-enterprise-managed-policy) |

335| `Managed settings document could not be parsed as a JSON object; none of its settings are in effect. Fix or remove it.` | [구성 경고](#managed-settings-document-could-not-be-parsed) |337| `Managed settings document could not be parsed as a JSON object; none of its settings are in effect. Fix or remove it.` | [구성 경고](#managed-settings-document-could-not-be-parsed) |

339| `Unable to read managed policy settings` | [구성 경고](#unable-to-read-managed-policy-settings) |

338| `"crossSessionInbound" must be one of "accept", "hold", "refuse"` | [구성 경고](#crosssessioninbound-must-be-one-of-accept-hold-refuse) |341| `"crossSessionInbound" must be one of "accept", "hold", "refuse"` | [구성 경고](#crosssessioninbound-must-be-one-of-accept-hold-refuse) |

3657 Claude Desktop을 열 수 없음3660 Claude Desktop을 열 수 없음

3658</h3>3661</h3>

3659 3662

3660[`/desktop`](/docs/ko/desktop#coming-from-the-cli) 또는 그 별칭 `/app`을 실행했고 Claude Code가 Claude Desktop을 열기 위해 사용하는 시스템 명령어가 실패했습니다. 세션은 터미널에 남아 있습니다.3663[`/desktop`](/docs/ko/desktop#coming-from-the-cli) 또는 그 별칭 `/app`을 실행했거나 [`claude --desktop`](/docs/ko/cli-reference#cli-flags)을 셸에서 실행했고 Claude Code가 Claude Desktop을 열기 위해 사용하는 시스템 명령어가 실패했습니다. `/desktop` 후 세션은 터미널에 남아 있습니다. `claude --desktop`은 메시지를 `Error:` 접두사 없이 출력하고 상태 1로 종료됩니다.

3664

3665괄호의 텍스트는 실패한 명령어를 이름 지정합니다. 종료 상태와 첫 번째 오류 출력 줄이 있으면 함께 표시됩니다. macOS에서 해당 명령어는 `open`입니다. 이 예와 같이 Windows에서는 `rundll32`입니다:

3661 3666

3662```text theme={null}3667```text theme={null}

3663Error: Couldn't open Claude Desktop (`open` exited 1: LSOpenURLsWithRole() failed for the URL claude://resume?session=<session-id> with error -10814). Open Claude Desktop and run /desktop again.3668Error: Couldn't open Claude Desktop (`open` exited 1: LSOpenURLsWithRole() failed for the URL claude://resume?session=<session-id> with error -10814). Open Claude Desktop and try again.

3664```3669```

3665 3670

3666**해야 할 일:**3671**해야 할 일:**

3667 3672

3668* Claude Desktop을 직접 열고 `/desktop`을 다시 실행합니다.3673* Claude Desktop을 직접 열고 `/desktop` 또는 `claude --desktop`을 다시 실행합니다.

3669* 해당 명령어의 전체 오류 출력을 읽으려면 `/debug`로 디버그 로깅을 켜고 `/desktop`을 다시 실행한 후 디버그 로그를 확인합니다.3674* 실패한 명령어의 전체 오류 출력을 읽으려면 `/debug`로 디버그 로깅을 켜고 `/desktop`을 다시 실행하거나 `claude --desktop --debug-file <path>`를 실행한 후 디버그 로그를 확인합니다.

3670 3675

3671v2.1.275 이전에는 메시지가 `Failed to open Claude Desktop. Please try opening it manually.`였고 무엇이 실패했는지 말하지 않았습니다.3676v2.1.285 이전에는 메시지가 `Open Claude Desktop and run /desktop again.`으로 끝났습니다. v2.1.275 이전에는 `Failed to open Claude Desktop. Please try opening it manually.`였고 무엇이 실패했는지 말하지 않았습니다.

3672 3677

3673<h3 id="terminal-setup-left-your-zed-keymap-unchanged">3678<h3 id="terminal-setup-left-your-zed-keymap-unchanged">

3674 /terminal-setup이 Zed 키맵을 변경하지 않음3679 /terminal-setup이 Zed 키맵을 변경하지 않음

5193* 설정을 관리하는 경우 사용자가 실행할 수 있는 모델을 `availableModels`에 추가하거나 모든 폴백을 차단하는 `deniedModels` 항목을 좁히세요. [특정 모델 또는 버전 차단](/docs/ko/model-config#block-specific-models-or-versions)은 기본 옵션이 어떻게 단계적으로 낮춰지는지 설명합니다.5198* 설정을 관리하는 경우 사용자가 실행할 수 있는 모델을 `availableModels`에 추가하거나 모든 폴백을 차단하는 `deniedModels` 항목을 좁히세요. [특정 모델 또는 버전 차단](/docs/ko/model-config#block-specific-models-or-versions)은 기본 옵션이 어떻게 단계적으로 낮춰지는지 설명합니다.

5194* 설정을 관리하지 않으면 메시지를 관리자에게 보내세요. 자신의 설정 파일은 관리 `availableModels` 또는 `deniedModels` 목록을 확대할 수 없습니다.5199* 설정을 관리하지 않으면 메시지를 관리자에게 보내세요. 자신의 설정 파일은 관리 `availableModels` 또는 `deniedModels` 목록을 확대할 수 없습니다.

5195 5200

5201<h3 id="managed-settings-dont-allow-this-api-provider">

5202 관리 설정이 이 API 공급자를 허용하지 않음

5203</h3>

5204

5205조직의 [관리 설정](/docs/ko/managed-settings)이 [`allowedProviders`](/docs/ko/settings-reference#allowedproviders) 목록을 설정하고, 세션의 API 공급자가 목록에 없거나 세션이 해당 항목이 요구하는 방식으로 고정되지 않은 엔드포인트를 사용합니다. Claude Code는 시작 전, 로그인 전, 또는 세션이 다음으로 API에 연결할 때 거부합니다. 메시지는 허용된 공급자로 시작합니다:

5206

5207```text theme={null}

5208조직의 관리 설정이 Claude Code를 사용하도록 허용합니다: Anthropic API, Amazon Bedrock.

5209```

5210

5211목록이 비어 있으면 메시지는 대신 다음과 같이 읽습니다:

5212

5213```text theme={null}

5214조직의 관리 설정이 Claude Code를 사용하도록 허용하는 API 공급자가 없습니다(allowedProviders가 빈 목록임). 따라서 이 머신에서 시작할 수 없습니다.

5215```

5216

5217모든 항목이 인식되지 않으면 괄호 안의 텍스트는 대신 `(allowedProviders lists only unrecognized entries)`입니다.

5218

5219**할 일:**

5220

5221* 메시지의 `To continue:` 단계를 따르세요.

5222* 설정을 관리하는 경우 메시지의 `Admins:`로 시작하는 줄이 추가할 항목 또는 고정할 값을 이름으로 지정하며, [`allowedProviders`](/docs/ko/settings-reference#allowedproviders) 항목은 어느 소스의 `env` 블록이 이를 고정할 수 있는지 말합니다.

5223

5196<h3 id="mcp-server-is-blocked-by-enterprise-managed-policy">5224<h3 id="mcp-server-is-blocked-by-enterprise-managed-policy">

5197 MCP 서버가 엔터프라이즈 관리 정책에 의해 차단됨5225 MCP 서버가 엔터프라이즈 관리 정책에 의해 차단됨

5198</h3>5226</h3>

5246* 머신을 관리하면 명명된 문서가 JSON 객체로 구문 분석되도록 수정하거나 파일, 프로필 또는 레지스트리 값을 제거하세요. 빈 `managed-settings.json`은 `{}`로 계산되며 실행을 차단하지 않습니다.5274* 머신을 관리하면 명명된 문서가 JSON 객체로 구문 분석되도록 수정하거나 파일, 프로필 또는 레지스트리 값을 제거하세요. 빈 `managed-settings.json`은 `{}`로 계산되며 실행을 차단하지 않습니다.

5247* 관리하지 않으면 관리자에게 배포된 문서를 수정하도록 요청하세요. 자신의 설정 파일의 아무것도 이 오류를 야기하거나 지우지 않습니다.5275* 관리하지 않으면 관리자에게 배포된 문서를 수정하도록 요청하세요. 자신의 설정 파일의 아무것도 이 오류를 야기하거나 지우지 않습니다.

5248 5276

5277<h3 id="unable-to-read-managed-policy-settings">

5278 관리 정책 설정을 읽을 수 없음

5279</h3>

5280

5281조직이 [관리 설정](/docs/ko/managed-settings)을 배포하고, 배포된 소스 중 하나가 있지만 운영 체제가 읽기를 거부하는 것이 아닌 I/O 오류 같은 이유로 읽을 수 없습니다. 다른 관리 소스가 정책을 제공하지 않으면 Claude Code는 소스가 수행할 수 있는 정책 없이 실행하는 대신 시작 시 종료됩니다:

5282

5283```text theme={null}

5284관리 정책 설정을 읽을 수 없습니다.

5285이 머신에는 조직 로그인 적용이 필요할 수 있지만 정책 파일을 로드하지 못했습니다.

5286관리자에게 문의하세요.

5287

5288세부 정보: <source>: <reason>

5289```

5290

5291동일한 상태에서 로그인 흐름, 이미 실행 중인 세션의 API 요청, 및 [`claude gateway`](/docs/ko/claude-apps-gateway) 서버는 [`allowedProviders`](/docs/ko/settings-reference#allowedproviders)를 이름으로 지정하는 첫 번째 줄의 변형으로 거부됩니다.

5292

5293운영 체제가 거부한 읽기(예: 루트 전용 파일)는 이 종료를 생성하지 않습니다: [세션은 해당 소스의 정책 없이 시작됩니다](/docs/ko/managed-settings#find-entries-claude-code-dropped). 구문 분석할 수 없는 소스의 경우 Claude Code는 [소스를 이름으로 지정하는 다른 메시지](#managed-settings-document-could-not-be-parsed)로 종료됩니다.

5294

5295**할 일:**

5296

5297* 머신을 관리하면 `Detail:` 줄이 이름으로 지정한 문제를 수정하여 배포된 소스를 읽을 수 있도록 하거나 소스를 제거하세요.

5298* 관리하지 않으면 메시지를 관리자에게 보내세요. 자신의 설정 파일의 아무것도 이 오류를 야기하거나 지우지 않습니다.

5299

5300v2.1.285 이전에는 claude.ai 또는 Claude Console 자격 증명으로 로그인한 세션만 이 메시지로 종료되었으며, 운영 체제가 거부한 읽기도 이를 생성했습니다.

5301

5249<h3 id="otelheadershelper-failed">5302<h3 id="otelheadershelper-failed">

5250 otelHeadersHelper 실패5303 otelHeadersHelper 실패

5251</h3>5304</h3>

5458 응답 품질이 평소보다 낮아 보입니다5511 응답 품질이 평소보다 낮아 보입니다

5459</h2>5512</h2>

5460 5513

5461Claude의 답변이 예상보다 덜 능력 있어 보이지만 오류가 표시되지 않는 경우, 원인은 일반적으로 모델 자체가 아니라 대화 상태입니다. Claude Code는 모델 버전을 자동으로 변경하지 않습니다. 세 가지 특정 경우에만 폴백 모델로 전환할 수 있습니다:5514Claude의 답변이 예상보다 덜 능력 있어 보이지만 오류가 표시되지 않는 경우, 원인은 일반적으로 모델 자체가 아니라 대화 상태입니다. Claude Code는 모델 버전을 자동으로 변경하지 않습니다. 다음의 경우에 폴백 모델로 전환할 수 있습니다:

5462 5515

5463* 구성된 [`--fallback-model`](/docs/ko/cli-reference#cli-flags)은 가용성 오류 후 해당 턴에만 제어를 인수받으며, 트랜스크립트에 공지가 표시됩니다5516* 구성된 [`--fallback-model`](/docs/ko/cli-reference#cli-flags)은 가용성 오류 후 해당 턴에만 제어를 인수받으며, 트랜스크립트에 공지가 표시됩니다

5464* Amazon Bedrock 또는 Google Cloud의 Agent Platform 시작 확인에서 기본 모델을 사용할 수 없음을 발견합니다5517* Amazon Bedrock 또는 Google Cloud의 Agent Platform 시작 확인에서 기본 모델을 사용할 수 없음을 발견하거나, 계정이 [세션 중간에 모델에 대한 액세스를 잃음](/docs/ko/amazon-bedrock#when-a-model-is-disabled-mid-session)

5465* [자동 모델 폴백](/docs/ko/model-config#automatic-model-fallback)은 Fable 5.1, Fable 5, Opus 5.5, Sonnet 5.5, Opus 5에서 세션을 플래그된 카테고리의 폴백 모델로 이동하며, 해당 카테고리에 폴백 모델이 있을 때 트랜스크립트에 공지를 표시합니다5518* [자동 모델 폴백](/docs/ko/model-config#automatic-model-fallback)은 Fable 5.1, Fable 5, Opus 5.5, Sonnet 5.5, Opus 5에서 세션을 플래그된 카테고리의 폴백 모델로 이동하며, 해당 카테고리에 폴백 모델이 있을 때 트랜스크립트에 공지를 표시합니다

5466 5519

5467아래의 모델 선택 확인은 두 번째와 세 번째 경우를 포착합니다. 첫 번째는 `/model` 변경이 아니라 트랜스크립트 공지로 나타납니다. [모델 구성](/docs/ko/model-config)에서 각 폴백이 적용되는 시기를 설명합니다.5520아래의 모델 선택 확인은 두 번째와 세 번째 경우를 포착합니다. 첫 번째는 `/model` 변경이 아니라 트랜스크립트 공지로 나타납니다. [모델 구성](/docs/ko/model-config)에서 각 폴백이 적용되는 시기를 설명합니다.

google-vertex-ai.md +12 −0

Details

293 293

294`opus`와 같은 모델 별칭은 고정으로 작동하지 않으며, Claude Code가 인식하지 못하는 모델 ID도 마찬가지입니다.294`opus`와 같은 모델 별칭은 고정으로 작동하지 않으며, Claude Code가 인식하지 못하는 모델 ID도 마찬가지입니다.

295 295

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

297

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

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

300</h3>

301

302프로젝트가 세션이 실행 중인 모델에 대한 액세스를 잃으면(예: 관리자가 [Model Garden](https://console.cloud.google.com/vertex-ai/model-garden)에서 비활성화하는 경우), Claude Code는 각 요청이 실패하는 대신 세션을 다른 모델로 전환하고 `Switched to <fallback> because <model> is not available`을 표시합니다. 시작 폴백과 동일한 모델을 시도합니다: 먼저 동일한 계층의 이전 버전이고, Opus 세션에서 사용 가능한 Opus 버전이 없으면 기본 Sonnet 모델입니다.

303

304전환은 고정하지 않은 계층에만 적용되며, 이는 시작 폴백과 동일한 조건입니다. 선택한 특정 버전의 세션은 모델을 유지하고, 폴백 모델 체인이 없으면 요청이 실패합니다. [자동 모드](/docs/ko/permission-modes#enable-auto-mode-on-bedrock-agent-platform-or-foundry)에서 Claude Code는 Agent Platform에서 자동 모드가 지원하는 모델로만 전환합니다. 해당 모델도 사용 가능하지 않으면 요청이 실패합니다.

305

306구성한 [폴백 모델 체인](/docs/ko/model-config#fallback-model-chains)은 계층 전환을 대체합니다: 이러한 거부에서 Claude Code는 구성한 폴백으로 전환합니다. 거부된 요청이 전환되지 않고 실패하도록 하려면 [`CLAUDE_CODE_DISABLE_MODEL_ACCESS_FALLBACK=1`](/docs/ko/env-vars)을 설정합니다. 구성한 폴백 체인은 여전히 이러한 거부에서 전환합니다. 모든 거부된 요청이 실패하도록 하려면 체인도 제거합니다.

307

296<h2 id="iam-configuration">308<h2 id="iam-configuration">

297 IAM 구성309 IAM 구성

298</h2>310</h2>

headless.md +2 −2

Details

297 도구 자동 승인297 도구 자동 승인

298</h3>298</h3>

299 299

300`--allowedTools`를 사용하여 Claude가 특정 도구를 프롬프트 없이 사용하도록 허용합니다. 이 예제는 테스트 스위트를 실행하고 실패를 수정하며 Claude가 권한을 요청하지 않고 Bash 명령을 실행하고 파일을 읽고 편집하도록 허용합니다:300`--allowedTools`를 사용하여 Claude가 특정 도구를 프롬프트 없이 사용하도록 허용합니다. `Read` 및 `Edit`를 나열하면 Claude가 권한을 요청하지 않고 파일을 읽고 편집하도록 허용합니다. `Bash`를 나열하면 셸 명령에 대해서도 동일하게 작동합니다. 단, [자동 모드](/docs/ko/permission-modes#how-auto-mode-evaluates-actions)에서 시작하는 실행은 예외입니다. 이 경우 Claude Code는 광범위한 허용 규칙으로 bare `Bash` 항목을 삭제하고 자동 모드가 각 명령을 대신 평가합니다. 이 예제는 테스트 스위트를 실행하고 이 세 도구를 나열하여 실패를 수정합니다:

301 301

302```bash theme={null}302```bash theme={null}

303claude -p "Run the test suite and fix any failures" \303claude -p "Run the test suite and fix any failures" \

304 --allowedTools "Bash,Read,Edit"304 --allowedTools "Bash,Read,Edit"

305```305```

306 306

307전체 세션에 대한 기준선을 설정하려면 개별 도구를 나열하는 대신 [권한 모드](/docs/ko/permission-modes)를 전달합니다. `-p`의 경우 [기본 시작 권한 모드](/docs/ko/permission-modes#which-mode-a-session-starts-in)는 모든 플랜에서 Manual이므로 원하는 권한 모드를 전달합니다:307전체 세션에 대한 기준선을 설정하려면 개별 도구를 나열하는 대신 [권한 모드](/docs/ko/permission-modes)를 전달합니다. 권한 모드를 설정하지 않는 실행은 [기본 제공 시작 권한 모드](/docs/ko/permission-modes#which-mode-a-session-starts-in)를 사용하며, 이는 `auto`일 수 있으므로 원하는 권한 모드를 전달합니다:

308 308

309* **`auto`**: `--permission-mode auto`를 전달하여 분류기가 대부분의 작업을 검토하도록 합니다309* **`auto`**: `--permission-mode auto`를 전달하여 분류기가 대부분의 작업을 검토하도록 합니다

310* **`dontAsk`**: Claude Code는 그렇지 않으면 프롬프트할 모든 호출을 거부하며, 이는 잠긴 CI 실행에 유용합니다. Manual 모드에서 승인이 필요하지 않은 작업(예: 작업 디렉토리의 파일 읽기 및 [읽기 전용 명령 집합](/docs/ko/permissions#read-only-commands))과 `--allowedTools` 항목 또는 `permissions.allow` 규칙이 적용되는 작업은 여전히 실행됩니다. `AskUserQuestion`, 조직이 [`ask`](/docs/ko/mcp#organization-controls-on-connector-tools)로 설정한 커넥터 도구 및 [`requiresUserInteraction`](/docs/ko/mcp#require-approval-for-a-specific-tool)으로 표시된 MCP 도구는 허용 규칙이 일치해도 거부됩니다310* **`dontAsk`**: Claude Code는 그렇지 않으면 프롬프트할 모든 호출을 거부하며, 이는 잠긴 CI 실행에 유용합니다. Manual 모드에서 승인이 필요하지 않은 작업(예: 작업 디렉토리의 파일 읽기 및 [읽기 전용 명령 집합](/docs/ko/permissions#read-only-commands))과 `--allowedTools` 항목 또는 `permissions.allow` 규칙이 적용되는 작업은 여전히 실행됩니다. `AskUserQuestion`, 조직이 [`ask`](/docs/ko/mcp#organization-controls-on-connector-tools)로 설정한 커넥터 도구 및 [`requiresUserInteraction`](/docs/ko/mcp#require-approval-for-a-specific-tool)으로 표시된 MCP 도구는 허용 규칙이 일치해도 거부됩니다

hooks-guide.md +2 −0

Details

1016 1016

1017반대는 사실이 아닙니다: `"allow"`를 반환하는 hook은 설정의 거부 규칙을 우회하지 않으며, [`requiresUserInteraction`](/docs/ko/mcp#require-approval-for-a-specific-tool)으로 표시된 MCP 도구의 프롬프트를 억제할 수 없거나 조직이 [커넥터 도구](/docs/ko/mcp#organization-controls-on-connector-tools)를 `ask`로 설정한 세션에서 해당 설정이 Claude Code에 도달하는 경우입니다. Hooks는 제한을 강화할 수 있지만 권한 규칙이 허용하는 것을 초과하여 완화할 수 없습니다.1017반대는 사실이 아닙니다: `"allow"`를 반환하는 hook은 설정의 거부 규칙을 우회하지 않으며, [`requiresUserInteraction`](/docs/ko/mcp#require-approval-for-a-specific-tool)으로 표시된 MCP 도구의 프롬프트를 억제할 수 없거나 조직이 [커넥터 도구](/docs/ko/mcp#organization-controls-on-connector-tools)를 `ask`로 설정한 세션에서 해당 설정이 Claude Code에 도달하는 경우입니다. Hooks는 제한을 강화할 수 있지만 권한 규칙이 허용하는 것을 초과하여 완화할 수 없습니다.

1018 1018

1019[mod](/docs/ko/plugins/mods/overview)를 설치하여 `tool.check`를 hook하면 `PreToolUse` hook이 차단한 호출을 승인할 수 있습니다. 단, hook이 관리되는 설정에 있는 경우는 제외됩니다. [Hooks로 권한 확장](/docs/ko/permissions#extend-permissions-with-hooks)에서 어떤 규칙이 mod보다 우선하는지 나열합니다.

1020

1019<h3 id="hook-not-firing">1021<h3 id="hook-not-firing">

1020 Hook이 발생하지 않음1022 Hook이 발생하지 않음

1021</h3>1023</h3>

interactive-mode.md +4 −6

Details

346* Claude Code에 명령어를 백그라운드에서 실행하도록 프롬프트합니다.346* Claude Code에 명령어를 백그라운드에서 실행하도록 프롬프트합니다.

347* `Ctrl+B`를 눌러 일반 Bash 도구 호출을 백그라운드로 이동합니다. Tmux 사용자는 tmux의 접두사 키 때문에 `Ctrl+B`를 두 번 눌러야 합니다.347* `Ctrl+B`를 눌러 일반 Bash 도구 호출을 백그라운드로 이동합니다. Tmux 사용자는 tmux의 접두사 키 때문에 `Ctrl+B`를 두 번 눌러야 합니다.

348 348

349명령어가 완료되기 전에 시간 초과에 도달하면, Claude Code는 자동으로 [명령어를 백그라운드로 이동](/docs/ko/tools-reference#background-commands)합니다. 단, `sleep`으로 시작하는 명령어는 제외됩니다. 명령어가 실행되는 시간을 변경하려면 [Bash 시간 초과 환경 변수](/docs/ko/tools-reference#timeout-and-output-limits)를 설정합니다.349명령어가 완료되기 전에 시간 초과에 도달하면, Claude Code는 자동으로 [명령어를 백그라운드로 이동](/docs/ko/tools-reference#foreground-commands-that-move-to-the-background)합니다. 단, `sleep`으로 시작하는 명령어는 제외됩니다. [`CLAUDE_CODE_DISABLE_BACKGROUND_TASKS`](/docs/ko/env-vars#variables)를 사용하여 백그라운드 작업을 비활성화했거나 [베어 모드](/docs/ko/headless#start-faster-with-bare-mode)로 시작한 경우, 명령어는 시간 초과 시 중지됩니다. 시간 초과를 변경하려면 [Bash 시간 초과 환경 변수](/docs/ko/tools-reference#timeout-and-output-limits)를 설정합니다.

350 350

351**주요 기능:**351**주요 기능:**

352 352

358* macOS 및 Linux에서 Claude Code는 운영 체제가 메모리 압박 신호를 보낼 때 실행 중인 백그라운드 작업을 종료합니다. 단, 세션이 최소 30분 동안 유휴 상태이고 턴 또는 서브에이전트가 실행 중이지 않아야 합니다. Claude Code v2.1.193 이상이 필요합니다.358* macOS 및 Linux에서 Claude Code는 운영 체제가 메모리 압박 신호를 보낼 때 실행 중인 백그라운드 작업을 종료합니다. 단, 세션이 최소 30분 동안 유휴 상태이고 턴 또는 서브에이전트가 실행 중이지 않아야 합니다. Claude Code v2.1.193 이상이 필요합니다.

359 * [디버그 로그](/docs/ko/debug-your-config)에 작업이 중지된 이유 또는 압박 이벤트가 작업을 실행 중인 상태로 둔 이유가 표시됩니다.359 * [디버그 로그](/docs/ko/debug-your-config)에 작업이 중지된 이유 또는 압박 이벤트가 작업을 실행 중인 상태로 둔 이유가 표시됩니다.

360 * [`CLAUDE_CODE_DISABLE_BG_SHELL_PRESSURE_REAP`](/docs/ko/env-vars)을 `1`로 설정하여 메모리 압박 중지를 비활성화합니다.360 * [`CLAUDE_CODE_DISABLE_BG_SHELL_PRESSURE_REAP`](/docs/ko/env-vars)을 `1`로 설정하여 메모리 압박 중지를 비활성화합니다.

361* 백그라운드 Bash 및 PowerShell 명령어는 시간 제한이 있으며, 명령어가 백그라운드에 진입한 순간부터 계산됩니다. 30분 또는 명령어를 백그라운드에서 시작할 때 Claude가 요청한 `timeout`(최대 2시간)입니다. 예를 들어 `Ctrl+B`로 백그라운드로 이동된 명령어는 이동 시점부터 30분을 얻습니다. 명령어가 시간 제한에 도달하면, Claude Code는 명령어를 중지하고 Claude에게 이유를 알립니다. Claude는 작업이 여전히 필요한 경우 더 긴 `timeout`으로 명령어를 다시 시작할 수 있습니다. 두 개의 환경 변수가 제한을 높이며(밀리초 단위), 둘 다 제한을 단축할 수 없습니다.361* 백그라운드 Bash 및 PowerShell 명령어는 시간 제한이 있으며, 명령어가 백그라운드에 진입한 순간부터 계산됩니다. 30분 또는 명령어를 백그라운드에서 시작할 때 Claude가 요청한 `timeout`(최대 2시간)입니다. 예를 들어 `Ctrl+B`로 백그라운드로 이동된 명령어는 이동 시점부터 30분을 얻습니다. 명령어가 시간 제한에 도달하면, Claude Code는 명령어를 중지하고 Claude에게 이유를 알립니다. Claude는 작업이 여전히 필요한 경우 더 긴 `timeout`으로 명령어를 다시 시작할 수 있습니다. 제한을 높이려면 도구 참조의 [백그라운드 명령어의 시간 제한 높이기](/docs/ko/tools-reference#raise-the-time-limit-for-background-commands)를 참조하세요.

362 * [`BASH_DEFAULT_TIMEOUT_MS`](/docs/ko/env-vars)를 `1800000` 이상으로 설정하여 30분 기본값을 해당 값으로 바꿉니다. 이동된 명령어에도 적용됩니다.362* 포그라운드 [서브에이전트](/docs/ko/sub-agents#run-subagents-in-foreground-or-background)가 시작한 백그라운드 명령어는 해당 서브에이전트의 실행이 끝날 때 종료됩니다. 완료, 실패 또는 중단 여부와 관계없이 종료됩니다. 도구 참조의 [백그라운드 명령어가 중지될 때](/docs/ko/tools-reference#when-a-background-command-stops)를 참조하세요.

363 * [`BASH_MAX_TIMEOUT_MS`](/docs/ko/env-vars)를 `7200000` 이상으로 설정하여 2시간 최대값을 높입니다. `BASH_DEFAULT_TIMEOUT_MS`를 `7200000` 이상으로 설정하면 동일한 방식으로 높아집니다.

364* 포그라운드 [서브에이전트](/docs/ko/sub-agents#run-subagents-in-foreground-or-background)가 시작한 백그라운드 명령어는 해당 서브에이전트의 실행이 끝날 때 종료됩니다. 완료, 실패 또는 중단 여부와 관계없이 종료됩니다. 도구 참조의 [백그라운드 명령어](/docs/ko/tools-reference#background-commands)를 참조하세요.

365 363

366모든 백그라운드 작업 기능을 비활성화하려면 `CLAUDE_CODE_DISABLE_BACKGROUND_TASKS` 환경 변수를 `1`로 설정합니다. 자세한 내용은 [환경 변수](/docs/ko/env-vars)를 참조하세요.364모든 백그라운드 작업 기능을 비활성화하려면 [`CLAUDE_CODE_DISABLE_BACKGROUND_TASKS`](/docs/ko/env-vars#variables) 환경 변수를 `1`로 설정합니다. [베어 모드](/docs/ko/headless#start-faster-with-bare-mode)로 시작하면 이 기능도 비활성화됩니다.

367 365

368**일반적인 백그라운드 명령어:**366**일반적인 백그라운드 명령어:**

369 367

llm-gateway.md +2 −0

Details

45 45

46[조직을 위해 LLM gateway 배포](/docs/ko/llm-gateway-rollout)는 각 단계를 안내하고 각 단계에서 배포할 구성 파일을 보여줍니다. gateway는 조직 설정의 한 부분입니다. 정책 적용, 사용량 가시성 및 데이터 처리 결정의 경우 [조직을 위해 Claude Code 설정](/docs/ko/admin-setup)을 참조하세요.46[조직을 위해 LLM gateway 배포](/docs/ko/llm-gateway-rollout)는 각 단계를 안내하고 각 단계에서 배포할 구성 파일을 보여줍니다. gateway는 조직 설정의 한 부분입니다. 정책 적용, 사용량 가시성 및 데이터 처리 결정의 경우 [조직을 위해 Claude Code 설정](/docs/ko/admin-setup)을 참조하세요.

47 47

48`ANTHROPIC_BASE_URL`을 통해 도달한 gateway를 관리되는 머신이 사용할 수 있는 유일한 대상으로 만들려면, 동일한 관리되는 설정 파일에서 [`allowedProviders`](/docs/ko/settings-reference#allowedproviders)를 `["customEndpoint"]`로 설정하고 gateway의 `ANTHROPIC_BASE_URL`을 해당 파일의 `env` 블록에 넣습니다. Claude Code는 Anthropic에 직접 또는 개발자의 자체 프록시를 포함하여 다른 곳을 가리키는 세션을 거부하고, `ANTHROPIC_BASE_URL`을 해당 파일에 설정한 값으로만 수락합니다. `ANTHROPIC_BEDROCK_BASE_URL`과 같은 공급자별 엔드포인트 변수를 통해 도달한 gateway의 경우, `allowedProviders` 항목은 어느 변수를 고정할지 나타냅니다. Claude Code v2.1.285 이상이 필요합니다.

48<h2 id="subscriptions-and-gateways">50<h2 id="subscriptions-and-gateways">

49 구독 및 gateway51 구독 및 gateway

50</h2>52</h2>

llm-gateway-protocol.md +1 −1

Details

310 310

311Claude Code는 아래의 두 자격 증명 헤더로 검색 요청을 전송하고 값이 해결되지 않는 헤더는 생략합니다. 두 헤더를 모두 전송하려면 Claude Code v2.1.248 이상이 필요합니다. 이전 버전은 `ANTHROPIC_AUTH_TOKEN`이 설정되었을 때만 `Authorization`을 전송하고, 그렇지 않으면 `x-api-key`만 전송합니다.311Claude Code는 아래의 두 자격 증명 헤더로 검색 요청을 전송하고 값이 해결되지 않는 헤더는 생략합니다. 두 헤더를 모두 전송하려면 Claude Code v2.1.248 이상이 필요합니다. 이전 버전은 `ANTHROPIC_AUTH_TOKEN`이 설정되었을 때만 `Authorization`을 전송하고, 그렇지 않으면 `x-api-key`만 전송합니다.

312 312

313* `Authorization`: `ANTHROPIC_AUTH_TOKEN`을 베어러 토큰으로, 그렇지 않으면 [`apiKeyHelper`](/docs/ko/llm-gateway-connect#rotate-credentials-with-apikeyhelper) 값을 베어러 토큰으로. 이 경우 Claude Code는 요청을 전송하기 전에 도우미가 반환될 때까지 기다립니다.313* `Authorization`: `ANTHROPIC_AUTH_TOKEN`을 베어러 토큰으로, 그렇지 않으면 [`apiKeyHelper`](/docs/ko/llm-gateway-connect#rotate-credentials-with-apikeyhelper) 값을 베어러 토큰으로.

314* `x-api-key`: Claude Code가 해결한 API 키 (예: `ANTHROPIC_API_KEY`). 도우미 값이 유일한 자격 증명일 때, 이 헤더도 이를 전달하므로 값이 두 헤더 모두에 도착합니다.314* `x-api-key`: Claude Code가 해결한 API 키 (예: `ANTHROPIC_API_KEY`). 도우미 값이 유일한 자격 증명일 때, 이 헤더도 이를 전달하므로 값이 두 헤더 모두에 도착합니다.

315 315

316Claude Code는 또한 `ANTHROPIC_CUSTOM_HEADERS`의 모든 헤더를 전송합니다. 사용자 정의 헤더에 비어 있지 않은 값이 있으면, Claude Code는 같은 이름의 기본 제공 헤더 대신 이를 전송하며, 이름은 대소문자를 구분하지 않게 일치합니다.316Claude Code는 또한 `ANTHROPIC_CUSTOM_HEADERS`의 모든 헤더를 전송합니다. 사용자 정의 헤더에 비어 있지 않은 값이 있으면, Claude Code는 같은 이름의 기본 제공 헤더 대신 이를 전송하며, 이름은 대소문자를 구분하지 않게 일치합니다.

managed-settings.md +8 −2

Details

199 199

200[게이트웨이 로그인 키](#choose-a-delivery-mechanism)는 별도의 규칙을 따릅니다. Claude Code는 서버 관리 설정에서 이들을 절대 읽지 않으므로, 서버 관리 설정이 선택된 소스인 동안 정책 키를 가진 머신의 가장 높은 순위의 관리 소스가 여전히 이들을 제공합니다. 그 아래에 순위가 지정된 관리 소스의 값이나 HKCU 레지스트리의 값은 무시됩니다.200[게이트웨이 로그인 키](#choose-a-delivery-mechanism)는 별도의 규칙을 따릅니다. Claude Code는 서버 관리 설정에서 이들을 절대 읽지 않으므로, 서버 관리 설정이 선택된 소스인 동안 정책 키를 가진 머신의 가장 높은 순위의 관리 소스가 여전히 이들을 제공합니다. 그 아래에 순위가 지정된 관리 소스의 값이나 HKCU 레지스트리의 값은 무시됩니다.

201 201

202[`allowedProviders`](/docs/ko/settings-reference#allowedproviders)는 자신의 규칙을 가집니다: 해당 항목의 Scope 노트는 머신에 설정된 목록이 서버 관리 목록과 어떻게 결합되는지 설명합니다. Claude Code v2.1.285 이상이 필요합니다.

203

202관리 소스가 `allowManagedMcpServersOnly`를 설정하거나 `allowedMcpServers` 목록을 설정하고 그 값이 적용 중인 값이 아닐 때, `/status` 및 `claude doctor`가 해당 소스와 키의 이름을 지정합니다.204관리 소스가 `allowManagedMcpServersOnly`를 설정하거나 `allowedMcpServers` 목록을 설정하고 그 값이 적용 중인 값이 아닐 때, `/status` 및 `claude doctor`가 해당 소스와 키의 이름을 지정합니다.

203 205

204<h3 id="compose-every-managed-source">206<h3 id="compose-every-managed-source">

353* 빈 관리형 설정 파일은 `{}`로 계산됩니다.355* 빈 관리형 설정 파일은 `{}`로 계산됩니다.

354* 사용자 쓰기 가능 HKCU 레지스트리 키의 손상된 값은 시작을 차단하지 않습니다. Claude Code는 이를 `/status` 및 `claude doctor`의 알림으로 보고합니다.356* 사용자 쓰기 가능 HKCU 레지스트리 키의 손상된 값은 시작을 차단하지 않습니다. Claude Code는 이를 `/status` 및 `claude doctor`의 알림으로 보고합니다.

355 357

356관리형 설정 파일, 드롭인 파일 또는 `managed-settings.d/` 디렉토리를 읽을 수 없고 관리자 소스가 정책을 제공하지 않으면, claude.ai 또는 Claude Console 자격 증명으로 로그인한 세션은 관리자에게 문의하라는 메시지와 함께 시작 시 종료됩니다.358관리형 설정 파일, 드롭인 파일, `managed-settings.d/` 디렉토리, MDM 프로필 또는 HKLM 레지스트리 값이 있지만 읽을 수 없고, 관리자 소스가 정책을 제공하지 않으면, 읽기 실패 이유에 따라 어떤 일이 발생하는지 달라집니다:

359

360* 운영 체제가 읽기를 거부한 경우(예: 루트 전용 파일), 모든 세션은 해당 소스의 정책 없이 시작됩니다. `/status` 및 `claude doctor`는 실패를 기록하고, `-p`를 사용한 실행은 stderr에도 인쇄합니다.

361* I/O 오류와 같은 다른 읽기 실패의 경우, 모든 세션은 [관리자에게 문의하라는 메시지](/docs/ko/errors#unable-to-read-managed-policy-settings)와 함께 시작 시 종료됩니다.

357 362

358삭제된 항목을 찾으려면 다음 세 위치 중 하나를 확인합니다:363삭제된 항목을 찾으려면 다음 세 위치 중 하나를 확인합니다:

359 364

387| 필드 | 존재하지만 유효하지 않을 때의 동작 |392| 필드 | 존재하지만 유효하지 않을 때의 동작 |

388| :- | :- |393| :- | :- |

389| `allowedMcpServers` | 값이 수정될 때까지 빈 허용 목록으로 적용되므로, 사용자가 추가하는 MCP 서버는 허용되지 않습니다. 조직이 [`managedMcpServers`](/docs/ko/settings-reference#managedmcpservers)를 통해 전달하는 서버는 여전히 로드되고, `managed-mcp.json` 서버는 [서버 평가 방법](/docs/ko/managed-mcp#how-a-server-is-evaluated)에 따라 로드됩니다. 개별 유효하지 않은 항목은 제거되고 유효한 부분 집합이 적용됩니다. |394| `allowedMcpServers` | 값이 수정될 때까지 빈 허용 목록으로 적용되므로, 사용자가 추가하는 MCP 서버는 허용되지 않습니다. 조직이 [`managedMcpServers`](/docs/ko/settings-reference#managedmcpservers)를 통해 전달하는 서버는 여전히 로드되고, `managed-mcp.json` 서버는 [서버 평가 방법](/docs/ko/managed-mcp#how-a-server-is-evaluated)에 따라 로드됩니다. 개별 유효하지 않은 항목은 제거되고 유효한 부분 집합이 적용됩니다. |

395| [`allowedProviders`](/docs/ko/settings-reference#allowedproviders) | 값이 수정될 때까지 빈 허용 목록으로 적용되므로, 모든 API 제공자가 거부되고 Claude Code는 머신에서 시작되지 않습니다. 개별 항목만 알려진 제공자 이름이 아니면, Claude Code는 해당 항목을 삭제하고 보고하며 나머지를 적용합니다. |

390| `allowedHttpHookUrls` | Claude Code는 값을 수정할 때까지 빈 관리형 [허용 목록](/docs/ko/settings-reference#allowedhttphookurls)을 적용하므로, HTTP 훅은 다른 설정 파일이 해당 URL을 나열하는 경우에만 실행됩니다. 개별 항목만 유효하지 않으면, Claude Code는 해당 항목을 제거하고 나머지를 적용합니다. |396| `allowedHttpHookUrls` | Claude Code는 값을 수정할 때까지 빈 관리형 [허용 목록](/docs/ko/settings-reference#allowedhttphookurls)을 적용하므로, HTTP 훅은 다른 설정 파일이 해당 URL을 나열하는 경우에만 실행됩니다. 개별 항목만 유효하지 않으면, Claude Code는 해당 항목을 제거하고 나머지를 적용합니다. |

391| `httpHookAllowedEnvVars` | Claude Code는 값을 수정할 때까지 빈 관리형 [허용 목록](/docs/ko/settings-reference#httphookallowedenvvars)을 적용하므로, 헤더 변수는 다른 설정 파일이 이름을 지정하는 경우에만 보간됩니다. 개별 항목만 유효하지 않으면, Claude Code는 해당 항목을 제거하고 나머지를 적용합니다. |397| `httpHookAllowedEnvVars` | Claude Code는 값을 수정할 때까지 빈 관리형 [허용 목록](/docs/ko/settings-reference#httphookallowedenvvars)을 적용하므로, 헤더 변수는 다른 설정 파일이 이름을 지정하는 경우에만 보간됩니다. 개별 항목만 유효하지 않으면, Claude Code는 해당 항목을 제거하고 나머지를 적용합니다. |

392| `allowedChannelPlugins` | 값을 수정할 때까지 빈 허용 목록을 적용하므로, `--channels`에 전달된 채널 플러그인은 허용되지 않습니다. 개별 항목만 유효하지 않으면, 해당 항목을 제거하고 나머지를 적용합니다. |398| `allowedChannelPlugins` | 값을 수정할 때까지 빈 허용 목록을 적용하므로, `--channels`에 전달된 채널 플러그인은 허용되지 않습니다. 개별 항목만 유효하지 않으면, 해당 항목을 제거하고 나머지를 적용합니다. |

437 443

438대부분은 잠금입니다. 잠금이 관리하는 값(예: 권한 규칙 또는 `sandbox.network.allowedDomains`)은 모든 수준에서 설정할 수 있는 일반 키이며, 잠금은 Claude Code에 관리형 값만 준수하도록 지시합니다.444대부분은 잠금입니다. 잠금이 관리하는 값(예: 권한 규칙 또는 `sandbox.network.allowedDomains`)은 모든 수준에서 설정할 수 있는 일반 키이며, 잠금은 Claude Code에 관리형 값만 준수하도록 지시합니다.

439 445

440이 표는 권한, 플러그인 및 전달 제어를 다룹니다. 여기에 나열되지 않은 키의 경우, [설정 참조](/docs/ko/settings-reference#all-settings) 인덱스의 범위 열에 관리형 전용 여부가 표시됩니다. 그곳의 나머지 관리형 전용 키에는 게이트웨이 로그인 URL, 버전, 브라우저, 모바일 시뮬레이터, SSH 호스트, Desktop 로컬 세션, 샌드박스 바이너리 경로, 모델 가격 책정, 모델 제한 및 CLAUDE.md 제어가 포함됩니다.446이 표는 권한, 플러그인 및 전달 제어를 다룹니다. 여기에 나열되지 않은 키의 경우, [설정 참조](/docs/ko/settings-reference#all-settings) 인덱스의 범위 열에 관리형 전용 여부가 표시됩니다.

441 447

442| 설정 | 설명 |448| 설정 | 설명 |

443| :- | :- |449| :- | :- |

mcp.md +5 −5

Details

273 273

274* ``⏸ Pending approval (run `claude` to approve)``: 아직 승인하지 않은 `.mcp.json`의 프로젝트 범위 서버입니다. Claude Code는 `claude mcp list` 및 `claude mcp get <name>` 모두에 표시합니다. 대화형으로 `claude`를 실행하여 검토하고 승인하세요.274* ``⏸ Pending approval (run `claude` to approve)``: 아직 승인하지 않은 `.mcp.json`의 프로젝트 범위 서버입니다. Claude Code는 `claude mcp list` 및 `claude mcp get <name>` 모두에 표시합니다. 대화형으로 `claude`를 실행하여 검토하고 승인하세요.

275* `✘ Rejected (see disabledMcpjsonServers in settings)`: [`disabledMcpjsonServers`](/docs/ko/settings-reference#disabledmcpjsonservers) 항목이 거부하는 `.mcp.json` 서버입니다. Claude Code는 `claude mcp get <name>`에만 표시합니다.275* `✘ Rejected (see disabledMcpjsonServers in settings)`: [`disabledMcpjsonServers`](/docs/ko/settings-reference#disabledmcpjsonservers) 항목이 거부하는 `.mcp.json` 서버입니다. Claude Code는 `claude mcp get <name>`에만 표시합니다.

276* `⊘ Disabled for this project (re-enable via /mcp)`: 프로젝트의 [`disabledMcpServers`](#disable-a-server-without-removing-it) 목록이 이름을 지정하는 서버입니다. Claude Code는 `claude mcp list` 및 `claude mcp get <name>` 모두에 표시합니다. `/mcp` 패널에서 서버를 다시 켜세요. v2.1.238 이전에는 두 명령 모두 비활성화된 서버에 연결하여 상태 확인을 수행하고 연결 결과를 보고했습니다.276* `⊘ Disabled for this project (re-enable via /mcp)`: 프로젝트의 [`disabledMcpServers`](#disable-a-server-without-removing-it) 목록이 이름을 지정하는 서버입니다. Claude Code는 `claude mcp list` 및 `claude mcp get <name>` 모두에 표시합니다. `/mcp` 패널에서 서버를 다시 켜세요.

277 277

278WebSocket 서버는 `claude mcp list` 출력에 나타나지 않습니다. `claude mcp get <name>` 또는 `/mcp` 패널을 사용하여 확인하세요.278WebSocket 서버는 `claude mcp list` 출력에 나타나지 않습니다. `claude mcp get <name>` 또는 `/mcp` 패널을 사용하여 확인하세요.

279 279

321 321

322* **숨겨진 공백**: Claude Code는 MCP 구성 값이 숨겨진 선행 또는 후행 공백을 전달할 때 경고합니다. 이는 종종 후행 줄 바꿈이 있는 토큰을 붙여넣기에서 나옵니다. Claude Code는 `command`, `url`, 각 `args` 항목, 그리고 `env` 및 `headers` 아래의 값과 키 이름을 확인합니다. Claude Code는 `claude mcp list` 출력 및 `/mcp`에서 경고를 표시하며, 영향을 받는 필드의 이름을 지정합니다. 예: `Leading or trailing whitespace in: headers.Authorization`. Claude Code는 공백을 자르지 않고 작성된 대로 정확히 값을 사용하므로 구성을 편집하여 제거하세요.322* **숨겨진 공백**: Claude Code는 MCP 구성 값이 숨겨진 선행 또는 후행 공백을 전달할 때 경고합니다. 이는 종종 후행 줄 바꿈이 있는 토큰을 붙여넣기에서 나옵니다. Claude Code는 `command`, `url`, 각 `args` 항목, 그리고 `env` 및 `headers` 아래의 값과 키 이름을 확인합니다. Claude Code는 `claude mcp list` 출력 및 `/mcp`에서 경고를 표시하며, 영향을 받는 필드의 이름을 지정합니다. 예: `Leading or trailing whitespace in: headers.Authorization`. Claude Code는 공백을 자르지 않고 작성된 대로 정확히 값을 사용하므로 구성을 편집하여 제거하세요.

323* **둘 이상의 범위에서 동일한 이름**: 다른 엔드포인트를 사용하여 둘 이상의 [범위](#mcp-installation-scopes)에서 동일한 서버 이름을 정의하면 Claude Code는 `claude mcp list` 출력 및 `/mcp`에서 충돌에 대해 경고합니다. Claude Code는 엔드포인트당 OAuth 로그인을 저장하므로 한 프로젝트에서 로드되는 정의를 인증할 때, 다른 정의가 로드되는 프로젝트에서는 여전히 별도로 로그인해야 합니다. 원하는 엔드포인트를 유지하고 `claude mcp remove <name> --scope <scope>`로 다른 엔드포인트를 제거하세요. 경고에서 Claude Code는 각 범위의 엔드포인트를 구성에 작성된 대로 인용합니다. [`${VAR}` 참조](#environment-variable-expansion-in-mcp-json)는 확장되지 않으므로 API 키와 같은 확인된 값을 표시하지 않습니다.323* **둘 이상의 범위에서 동일한 이름**: 다른 엔드포인트를 사용하여 둘 이상의 [범위](#mcp-installation-scopes)에서 동일한 서버 이름을 정의하면 Claude Code는 `claude mcp list` 출력 및 `/mcp`에서 충돌에 대해 경고합니다. Claude Code는 엔드포인트당 OAuth 로그인을 저장하므로 한 프로젝트에서 로드되는 정의를 인증할 때, 다른 정의가 로드되는 프로젝트에서는 여전히 별도로 로그인해야 합니다. 원하는 엔드포인트를 유지하고 `claude mcp remove <name> --scope <scope>`로 다른 엔드포인트를 제거하세요. 경고에서 Claude Code는 각 범위의 엔드포인트를 구성에 작성된 대로 인용합니다. [`${VAR}` 참조](#environment-variable-expansion-in-mcp-json)는 확장되지 않으므로 API 키와 같은 확인된 값을 표시하지 않습니다.

324* **예약된 이름**: Claude Code는 `workspace`, `claude-in-chrome`, `computer-use`, `Claude Preview` 및 `Claude Browser`를 포함한 기본 제공 서버의 이름을 예약합니다. 구성에서 예약된 이름의 서버를 정의하면 Claude Code는 로드 시 이를 건너뛰고 이름을 바꾸도록 요청하는 경고를 표시합니다. `claude mcp add`는 예약된 이름을 오류로 거부합니다. `Claude Preview` 및 `Claude Browser`는 모두 [Claude Code 데스크톱 앱의 미리보기 창](/docs/ko/desktop#preview-your-app)이 사용하는 기본 제공 서버의 이름입니다. v2.1.205 이전에는 `Claude Browser`가 예약되지 않았으므로 사용자 구성 서버가 해당 이름으로 등록될 수 있었습니다.324* **예약된 이름**: Claude Code는 `workspace`, `claude-in-chrome`, `computer-use`, `Claude Preview` 및 `Claude Browser`를 포함한 기본 제공 서버의 이름을 예약합니다. 구성에서 예약된 이름의 서버를 정의하면 Claude Code는 로드 시 이를 건너뛰고 이름을 바꾸도록 요청하는 경고를 표시합니다. `claude mcp add`는 예약된 이름을 오류로 거부합니다. `Claude Preview` 및 `Claude Browser`는 모두 [Claude Code 데스크톱 앱의 미리보기 창](/docs/ko/desktop#preview-your-app)이 사용하는 기본 제공 서버의 이름입니다.

325* **누락된 환경 변수**: [`${VAR}` 참조](#environment-variable-expansion-in-mcp-json)가 설정되지 않은 변수의 이름을 지정하고 `:-default`가 없으면 Claude Code는 `claude mcp list` 출력 및 `/mcp`에서 경고하며, 변수의 이름을 지정하고, 여전히 `${VAR}` 텍스트가 확장되지 않은 상태로 서버를 로드합니다. 변수를 설정하거나 `${VAR:-default}` 폴백을 추가하세요. 원격 서버의 `url` 및 `headers`에서 일부 자격 증명 변수는 [경고 없이 비어 있는 것으로 읽습니다](#credential-variables-that-read-as-empty).325* **누락된 환경 변수**: [`${VAR}` 참조](#environment-variable-expansion-in-mcp-json)가 설정되지 않은 변수의 이름을 지정하고 `:-default`가 없으면 Claude Code는 `claude mcp list` 출력 및 `/mcp`에서 경고하며, 변수의 이름을 지정하고, 여전히 `${VAR}` 텍스트가 확장되지 않은 상태로 서버를 로드합니다. 변수를 설정하거나 `${VAR:-default}` 폴백을 추가하세요. 원격 서버의 `url` 및 `headers`에서 일부 자격 증명 변수는 [경고 없이 비어 있는 것으로 읽습니다](#credential-variables-that-read-as-empty).

326 326

327<h4 id="tool-availability">327<h4 id="tool-availability">

417 실패한 첫 연결417 실패한 첫 연결

418</h4>418</h4>

419 419

420HTTP 또는 SSE 서버의 첫 연결이 5xx 응답, 연결 거부 또는 시간 초과와 같은 일시적 오류로 실패하면 Claude Code는 최대 3번 재시도합니다. 연결이 여전히 실패하면 Claude Code는 서버를 실패로 표시합니다. Claude Code는 시작 시 및 서버가 세션 중에 추가될 때 이 방식으로 재시도합니다. 여기에는 Claude Code가 [클라우드 세션](/docs/ko/claude-code-on-the-web)에 구성에서 추가하는 서버 및 Agent SDK의 [`setMcpServers()`](/docs/ko/agent-sdk/typescript)로 추가하는 서버가 포함됩니다.420HTTP 또는 SSE 서버의 첫 연결이 5xx 응답, 연결 거부 또는 시간 초과와 같은 일시적 오류로 실패하면 Claude Code는 최대 3번 재시도합니다. 연결이 여전히 실패하면 Claude Code는 서버를 실패로 표시합니다.

421 421

422Claude Code는 이 경우에 재시도하지 않습니다:422Claude Code는 이 경우에 재시도하지 않습니다:

423 423

551 551

552플러그인 서버는 플러그인에서 온 것을 나타내는 표시기와 함께 `/mcp`에 나타납니다.552플러그인 서버는 플러그인에서 온 것을 나타내는 표시기와 함께 `/mcp`에 나타납니다.

553 553

554플러그인의 stdio 서버의 경우, `claude mcp get`은 `Command: stdio`, 빈 `Args:` 줄, 그리고 각 환경 변수를 `NAME=[REDACTED]`로 인쇄합니다. 값은 자격 증명을 전달할 수 있기 때문에 숨겨집니다.

555

554**플러그인 MCP 도구 이름**:556**플러그인 MCP 도구 이름**:

555 557

556플러그인 번들 MCP 서버의 도구는 호출 가능한 이름에 플러그인 이름과 서버 키를 모두 포함합니다. 전체 형식은 `mcp__plugin_<plugin-name>_<server-name>__<tool-name>`이며, `A-Z`, `a-z`, `0-9`, `_`, `-` 외의 모든 문자는 `_`로 바뀝니다. `my-plugin`이라는 플러그인에 번들된 `database-tools` 서버의 경우, `query` 도구는 다음과 같이 호출할 수 있습니다:558플러그인 번들 MCP 서버의 도구는 호출 가능한 이름에 플러그인 이름과 서버 키를 모두 포함합니다. 전체 형식은 `mcp__plugin_<plugin-name>_<server-name>__<tool-name>`이며, `A-Z`, `a-z`, `0-9`, `_`, `-` 외의 모든 문자는 `_`로 바뀝니다. `my-plugin`이라는 플러그인에 번들된 `database-tools` 서버의 경우, `query` 도구는 다음과 같이 호출할 수 있습니다:

1456* 최상위 속성 이름은 1\~64자 길이여야 하며 ASCII 문자와 숫자, `_`, `.`, `-`만 사용해야 합니다1458* 최상위 속성 이름은 1\~64자 길이여야 하며 ASCII 문자와 숫자, `_`, `.`, `-`만 사용해야 합니다

1457* 스키마는 JSON Schema draft 2020-12 메타스키마에 대해 유효해야 합니다. Claude Code는 `$schema`를 선언하지 않는 스키마와 draft 2020-12를 선언하는 스키마에 이 확인을 적용합니다. 다른 방언을 선언하는 스키마는 이 확인을 건너뛰지만, 위의 속성 이름 확인은 여전히 적용됩니다1459* 스키마는 JSON Schema draft 2020-12 메타스키마에 대해 유효해야 합니다. Claude Code는 `$schema`를 선언하지 않는 스키마와 draft 2020-12를 선언하는 스키마에 이 확인을 적용합니다. 다른 방언을 선언하는 스키마는 이 확인을 건너뛰지만, 위의 속성 이름 확인은 여전히 적용됩니다

1458 1460

1459Claude Code는 [루트 수준 결합자 재작성](#tool-input-schemas-with-a-root-level-combinator) 후에 확인을 실행하며, 실제로 전송할 스키마에 대해 실행합니다.

~~1460~~

1461Claude Code가 도구를 제외할 때, 서버의 로그에 이유를 기록하고 제외된 도구와 그 이유를 Claude에 알리므로, Claude에 도구가 누락된 이유를 물어볼 수 있습니다. 서버에서 스키마를 수정하면, Claude Code가 다음에 서버의 도구를 로드할 때 도구가 다시 나타납니다.1461Claude Code가 도구를 제외할 때, 서버의 로그에 이유를 기록하고 제외된 도구와 그 이유를 Claude에 알리므로, Claude에 도구가 누락된 이유를 물어볼 수 있습니다. 서버에서 스키마를 수정하면, Claude Code가 다음에 서버의 도구를 로드할 때 도구가 다시 나타납니다.

1462 1462

1463Claude Code는 Anthropic에서 가져오는 기능 플래그를 통해 제외를 켭니다. [플래그 가져오기가 꺼진 배포](/docs/ko/env-vars#features-that-need-feature-flag-fetching)에서 또는 에어갭 머신과 같이 플래그가 도착한 적이 없는 머신에서, Claude Code는 여전히 확인을 실행하고 서버의 로그에 어떤 도구가 거부될 것인지 기록하지만, 도구의 스키마를 API로 어쨌든 전송합니다. API는 [도구를 위치로 이름 지은 400 오류](/docs/ko/errors#tool-input-schema-is-invalid)로 해당 스키마를 포함하는 요청을 거부합니다. v2.1.216 이전에는 배포가 이러한 확인을 실행하지 않았습니다.1463Claude Code는 Anthropic에서 가져오는 기능 플래그를 통해 제외를 켭니다. [플래그 가져오기가 꺼진 배포](/docs/ko/env-vars#features-that-need-feature-flag-fetching)에서 또는 에어갭 머신과 같이 플래그가 도착한 적이 없는 머신에서, Claude Code는 여전히 확인을 실행하고 서버의 로그에 어떤 도구가 거부될 것인지 기록하지만, 도구의 스키마를 API로 어쨌든 전송합니다. API는 [도구를 위치로 이름 지은 400 오류](/docs/ko/errors#tool-input-schema-is-invalid)로 해당 스키마를 포함하는 요청을 거부합니다. v2.1.216 이전에는 배포가 이러한 확인을 실행하지 않았습니다.

mcp-quickstart.md +3 −1

Details

360 360

361 다음에 일어나는 일은 문제가 어디에 있는지 알려줍니다:361 다음에 일어나는 일은 문제가 어디에 있는지 알려줍니다:

362 362

363 * 명령이 시작되고 입력을 기다립니다: 서버 자체가 작동합니다. `claude mcp get <name>`을 실행하고 거기에 표시된 명령이 방금 실행한 것과 일치하는지 확인합니다. 표시된 명령이 입력한 것과 다르면 서버 명령 전에 `--` 구분 기호를 생략했을 가능성이 높습니다. 서버를 제거하고 `--`를 제자리에 두고 다시 추가합니다. `.mcp.json`을 손으로 작성한 경우 구문과 위치를 확인합니다.363 * 명령이 시작되고 입력을 기다립니다: 서버 자체가 작동합니다.

364

365 `claude mcp get <name>`을 실행하고 거기에 표시된 명령이 방금 실행한 것과 일치하는지 확인합니다. 표시된 명령이 입력한 것과 다르면 서버 명령 전에 `--` 구분 기호를 생략했을 가능성이 높습니다. 서버를 제거하고 `--`를 제자리에 두고 다시 추가합니다. `.mcp.json`을 손으로 작성한 경우 구문과 위치를 확인합니다. v2.1.285 이전에는 `claude mcp get`이 `type` 필드 없이 저장된 stdio 항목(예: 손으로 작성한 `.mcp.json` 항목)에 대해 `Command` 줄을 인쇄하지 않았습니다. 이러한 버전에서는 대신 `claude mcp list`를 실행하면 어느 쪽이든 명령줄을 인쇄합니다.

364 * 명령 오류: 메시지는 Node.js 또는 브라우저와 같이 누락된 것을 이름으로 지정합니다.366 * 명령 오류: 메시지는 Node.js 또는 브라우저와 같이 누락된 것을 이름으로 지정합니다.

365 </Accordion>367 </Accordion>

366 368

model-config.md +10 −5

Details

39| **`sonnet`** | 일상적인 코딩 작업을 위해 최신 Sonnet 모델을 사용합니다 |39| **`sonnet`** | 일상적인 코딩 작업을 위해 최신 Sonnet 모델을 사용합니다 |

40| **`opus`** | 복잡한 추론 작업을 위해 최신 Opus 모델을 사용합니다 |40| **`opus`** | 복잡한 추론 작업을 위해 최신 Opus 모델을 사용합니다 |

41| **`haiku`** | 간단한 작업을 위해 빠르고 효율적인 Haiku 모델을 사용합니다 |41| **`haiku`** | 간단한 작업을 위해 빠르고 효율적인 Haiku 모델을 사용합니다 |

42| **`sonnet[1m]`** | 긴 세션을 위해 [100만 토큰 컨텍스트 윈도우](https://platform.claude.com/docs/en/build-with-claude/context-windows#context-window-sizes-by-model)를 가진 Sonnet을 사용합니다. `sonnet`이 이미 기본 100만 윈도우를 가진 Sonnet 5.5 또는 Sonnet 5로 확인되는 경우 효과가 없습니다. [LLM 게이트웨이](/docs/ko/llm-gateway) 뒤에서는 해당 모델의 100만 윈도우를 선택합니다 |42| **`sonnet[1m]`** | 긴 세션을 위해 [100만 토큰 컨텍스트 윈도우](https://platform.claude.com/docs/en/build-with-claude/context-windows#context-window-sizes-by-model)를 가진 Sonnet을 사용합니다. `sonnet`이 이미 기본 100만 윈도우를 가진 Sonnet 5.5 또는 Sonnet 5로 확인되는 경우 효과가 없습니다 |

43| **`opus[1m]`** | 긴 세션을 위해 [100만 토큰 컨텍스트 윈도우](https://platform.claude.com/docs/en/build-with-claude/context-windows#context-window-sizes-by-model)를 가진 Opus를 사용합니다 |43| **`opus[1m]`** | 긴 세션을 위해 [100만 토큰 컨텍스트 윈도우](https://platform.claude.com/docs/en/build-with-claude/context-windows#context-window-sizes-by-model)를 가진 Opus를 사용합니다 |

44| **`opusplan`** | 계획 모드 중에 `opus`를 사용한 다음 실행을 위해 `sonnet`으로 전환하는 특수 모드입니다 |44| **`opusplan`** | 계획 모드 중에 `opus`를 사용한 다음 실행을 위해 `sonnet`으로 전환하는 특수 모드입니다 |

45 45

521 폴백 모델 체인521 폴백 모델 체인

522</h3>522</h3>

523 523

524기본 모델이 과부하 상태이거나 사용할 수 없거나 다른 재시도 불가능한 서버 오류를 반환할 때, Claude Code는 요청이 실패하는 대신 폴백 모델로 전환할 수 있습니다. 인증, 청구, 속도 제한, 요청 크기 및 전송 오류, 그리고 [조직의 정책 확인에 의한 거부](/docs/ko/errors#automatic-retries)는 전환을 트리거하지 않습니다. 이들은 정상적인 재시도 및 오류 처리를 따릅니다.524기본 모델이 과부하 상태이거나 사용할 수 없거나 다른 재시도 불가능한 서버 오류를 반환할 때, Claude Code는 요청이 실패하는 대신 폴백 모델로 전환할 수 있습니다. 인증, 청구, 속도 제한, 요청 크기 및 전송 오류, 그리고 [조직의 정책 확인에 의한 거부](/docs/ko/errors#automatic-retries)는 전환을 트리거하지 않습니다. 이들은 정상적인 재시도 및 오류 처리를 따릅니다. [Amazon Bedrock](/docs/ko/amazon-bedrock#when-a-model-is-disabled-mid-session) 또는 [Google Cloud의 Agent Platform](/docs/ko/google-vertex-ai#when-a-model-is-disabled-mid-session)이 계정이 호출할 수 없는 모델을 거부할 때 전환되며, Claude Code는 이를 인증 오류가 아닌 모델을 사용할 수 없는 것으로 취급합니다.

525 525

526하나 이상의 폴백 모델을 구성하고 Claude Code는 순서대로 시도하며, 전환할 때 알림을 표시합니다. 전환은 현재 턴에만 지속되므로, 다음 메시지는 기본 모델을 다시 먼저 시도합니다. Claude Code는 체인을 중복 제거 후 3개 모델로 제한하고 추가 항목을 무시합니다.526하나 이상의 폴백 모델을 구성하고 Claude Code는 순서대로 시도하며, 전환할 때 알림을 표시합니다. 전환은 현재 턴에만 지속되므로, 다음 메시지는 기본 모델을 다시 먼저 시도합니다. Claude Code는 체인을 중복 제거 후 3개 모델로 제한하고 추가 항목을 무시합니다.

527 527

775 775

776Claude Code는 Anthropic API에 직접 연결할 때만 이러한 플랜 요구 사항을 확인합니다. 저장된 claude.ai 로그인이 활성 자격증으로 유지되는 동안 `ANTHROPIC_BASE_URL`을 [LLM 게이트웨이](/docs/ko/llm-gateway#subscriptions-and-gateways)로 지정하면, Claude Code는 계정의 사용 크레딧을 확인하지 않습니다. `[1m]` 옵션은 `/model`에서 사용 가능하게 유지되고, 게이트웨이는 요청이 성공하는지 결정합니다. v2.1.229 이전에는 Claude Code가 해당 구성에서 사용 크레딧을 확인할 수 없을 때 `/model sonnet[1m]`을 거부했습니다.776Claude Code는 Anthropic API에 직접 연결할 때만 이러한 플랜 요구 사항을 확인합니다. 저장된 claude.ai 로그인이 활성 자격증으로 유지되는 동안 `ANTHROPIC_BASE_URL`을 [LLM 게이트웨이](/docs/ko/llm-gateway#subscriptions-and-gateways)로 지정하면, Claude Code는 계정의 사용 크레딧을 확인하지 않습니다. `[1m]` 옵션은 `/model`에서 사용 가능하게 유지되고, 게이트웨이는 요청이 성공하는지 결정합니다. v2.1.229 이전에는 Claude Code가 해당 구성에서 사용 크레딧을 확인할 수 없을 때 `/model sonnet[1m]`을 거부했습니다.

777 777

778<span id="context-window-behind-a-gateway" />

779

780`ANTHROPIC_BASE_URL`을 [LLM 게이트웨이](/docs/ko/llm-gateway) 또는 다른 프록시로 설정하면, Claude Code는 인식하는 각 모델에 Anthropic API의 모델이 가진 것과 동일한 컨텍스트 윈도우를 제공합니다. Fable 5.1, Fable 5, Sonnet 5 이상 및 Opus 4.7 이상은 선택할 `[1m]` 변형이 없는 1M 윈도우를 얻고, Opus 4.6과 같이 `[1m]` 변형을 통해서만 1M에 도달하는 모델은 이 없이 200K에서 실행됩니다. Claude Code는 게이트웨이 또는 그 뒤의 서버가 적용하는 더 낮은 제한을 감지할 수 없습니다. 게이트웨이가 200K 토큰 이상의 요청을 거부하면, [`/autocompact 200k`](#set-the-auto-compact-window)를 실행하여 세션이 해당 경계에서 압축되도록 합니다.

781

7781M 컨텍스트를 끄려면, `CLAUDE_CODE_DISABLE_1M_CONTEXT=1`을 설정하세요. Claude Code는 모델 선택기에서 1M 모델 변형을 제거합니다. Sonnet 5 및 Fable 모델과 같이 기본 1M 윈도우가 있는 모델에서, 모델을 200K 컨텍스트 윈도우로 취급합니다:7821M 컨텍스트를 끄려면, `CLAUDE_CODE_DISABLE_1M_CONTEXT=1`을 설정하세요. Claude Code는 모델 선택기에서 1M 모델 변형을 제거합니다. Sonnet 5 및 Fable 모델과 같이 기본 1M 윈도우가 있는 모델에서, 모델을 200K 컨텍스트 윈도우로 취급합니다:

779 783

780* 자동 압축이 켜져 있으면, 세션은 [자동 압축](#set-the-auto-compact-window)을 통해 200K 경계에서 압축됩니다. 자동 압축 윈도우를 200K 위로 설정해도 보류를 해제하지 않습니다. Claude Code는 해당 윈도우를 모델의 컨텍스트 윈도우로 제한하기 때문입니다.784* 자동 압축이 켜져 있으면, 세션은 [자동 압축](#set-the-auto-compact-window)을 통해 200K 경계에서 압축됩니다. 자동 압축 윈도우를 200K 위로 설정해도 보류를 해제하지 않습니다. Claude Code는 해당 윈도우를 모델의 컨텍스트 윈도우로 제한하기 때문입니다.

803 807

804Anthropic API에서, Sonnet 5.5 및 Sonnet 5는 항상 1M 컨텍스트 윈도우로 실행됩니다. 200K 변형이 없고, 선택할 `[1m]` 접미사가 없으며, 어떤 플랜에서도 사용 크레딧이 필요하지 않습니다. 세션은 윈도우가 채워지기 전에 자동 압축되며, 기본적으로 약 967K 토큰에서 압축됩니다. [`CLAUDE_CODE_AUTO_COMPACT_WINDOW`](/docs/ko/env-vars)를 설정하여 다른 임계값을 선택합니다.808Anthropic API에서, Sonnet 5.5 및 Sonnet 5는 항상 1M 컨텍스트 윈도우로 실행됩니다. 200K 변형이 없고, 선택할 `[1m]` 접미사가 없으며, 어떤 플랜에서도 사용 크레딧이 필요하지 않습니다. 세션은 윈도우가 채워지기 전에 자동 압축되며, 기본적으로 약 967K 토큰에서 압축됩니다. [`CLAUDE_CODE_AUTO_COMPACT_WINDOW`](/docs/ko/env-vars)를 설정하여 다른 임계값을 선택합니다.

805 809

806두 가지 구성이 윈도우를 200K로 예산합니다:810Claude Code는 [LLM 게이트웨이](/docs/ko/llm-gateway) 또는 다른 사용자 정의 `ANTHROPIC_BASE_URL` 뒤에서 Sonnet 5.5 및 Sonnet 5에 동일한 1M 윈도우를 제공합니다. 게이트웨이가 더 낮은 제한을 적용하면, [게이트웨이 뒤의 컨텍스트 윈도우](#context-window-behind-a-gateway)를 참조하세요.

811

812이 설정은 윈도우를 200K로 예산합니다:

807 813

808* **LLM 게이트웨이**: `ANTHROPIC_BASE_URL`이 [게이트웨이](/docs/ko/llm-gateway)를 가리킬 때, Claude Code는 1M 지원을 확인할 수 없습니다. 전체 윈도우를 사용하려면, 모델 선택기에서 Sonnet 5.5(1M context)를 선택하세요. 이는 `sonnet[1m]`으로 매핑되거나, Sonnet 5의 경우 `/model claude-sonnet-5[1m]`을 실행합니다.

809* **`CLAUDE_CODE_DISABLE_1M_CONTEXT=1`**: 기본 1M 윈도우가 있는 모든 모델의 세션을 200K 윈도우로 유지합니다. [확장 컨텍스트](#extended-context)에서 보류가 적용되는 방식을 참조하세요. 컨텍스트를 제한해야 하는 배포에 유용합니다.814* **`CLAUDE_CODE_DISABLE_1M_CONTEXT=1`**: 기본 1M 윈도우가 있는 모든 모델의 세션을 200K 윈도우로 유지합니다. [확장 컨텍스트](#extended-context)에서 보류가 적용되는 방식을 참조하세요. 컨텍스트를 제한해야 하는 배포에 유용합니다.

810 815

811<h2 id="context-window-and-auto-compaction">816<h2 id="context-window-and-auto-compaction">

841* [클라우드 세션](/docs/ko/claude-code-on-the-web)은 대화가 모델 제한에 접근할 때 압축합니다.846* [클라우드 세션](/docs/ko/claude-code-on-the-web)은 대화가 모델 제한에 접근할 때 압축합니다.

842* Sonnet 4.6 및 Opus 4.6([확장 컨텍스트](#extended-context) 없음)은 200K 경계에서 압축하며, Opus 4.8 및 이후 버전도 Amazon Bedrock, Google Cloud의 Agent Platform, Microsoft Foundry와 같은 200K 컨텍스트 윈도우로 실행할 때 압축합니다.847* Sonnet 4.6 및 Opus 4.6([확장 컨텍스트](#extended-context) 없음)은 200K 경계에서 압축하며, Opus 4.8 및 이후 버전도 Amazon Bedrock, Google Cloud의 Agent Platform, Microsoft Foundry와 같은 200K 컨텍스트 윈도우로 실행할 때 압축합니다.

843* [`CLAUDE_CODE_DISABLE_1M_CONTEXT=1`](/docs/ko/env-vars)을 설정하면 Sonnet 5 및 Fable 모델과 같이 기본 1M 윈도우가 있는 모델은 200K 경계에서 압축합니다.848* [`CLAUDE_CODE_DISABLE_1M_CONTEXT=1`](/docs/ko/env-vars)을 설정하면 Sonnet 5 및 Fable 모델과 같이 기본 1M 윈도우가 있는 모델은 200K 경계에서 압축합니다.

844* Sonnet 5, Fable 모델, Anthropic API의 Opus 4.7 이상과 같이 기본 1M 윈도우로 실행되는 모델은 윈도우가 채워지기 전에 압축되며, 기본적으로 약 967K 토큰에서 압축됩니다. Amazon Bedrock, Google Cloud의 Agent Platform, Microsoft Foundry에서는 [타사 배포를 위한 모델 고정](#pin-models-for-third-party-deployments)에서 해당 윈도우로 실행되는 모델을 나타냅니다. Sonnet 5.5 및 Sonnet 5를 200K로 예산하는 구성의 경우 [Sonnet 5.5 및 Sonnet 5 컨텍스트 윈도우](#sonnet-5-5-and-sonnet-5-context-window)를 참조하십시오.849* 기본 1M 윈도우로 실행되는 모델은 윈도우가 채워지기 전에 압축되며, 기본적으로 약 967K 토큰에서 압축됩니다. Anthropic API에서는 Sonnet 5, Fable 모델, Opus 4.7 이상이 포함됩니다. Amazon Bedrock, Google Cloud의 Agent Platform, Microsoft Foundry에서는 [타사 배포를 위한 모델 고정](#pin-models-for-third-party-deployments)에서 해당 윈도우로 실행되는 모델을 참조하십시오. 사용자 정의 `ANTHROPIC_BASE_URL` 뒤에서는 [게이트웨이 뒤의 컨텍스트 윈도우](#context-window-behind-a-gateway)를 참조하십시오.

845* Claude Code가 인식하지 못하는 모델 ID(예: [LLM 게이트웨이](/docs/ko/llm-gateway) 별칭)의 세션은 Claude Code가 ID에 대해 가정하는 컨텍스트 윈도우에서 압축합니다. [게이트웨이 또는 사용자 정의 모델 ID의 윈도우 수정](#correct-the-window-for-a-gateway-or-custom-model-id)을 참조하십시오.850* Claude Code가 인식하지 못하는 모델 ID(예: [LLM 게이트웨이](/docs/ko/llm-gateway) 별칭)의 세션은 Claude Code가 ID에 대해 가정하는 컨텍스트 윈도우에서 압축합니다. [게이트웨이 또는 사용자 정의 모델 ID의 윈도우 수정](#correct-the-window-for-a-gateway-or-custom-model-id)을 참조하십시오.

846 851

847<h3 id="correct-the-window-for-a-gateway-or-custom-model-id">852<h3 id="correct-the-window-for-a-gateway-or-custom-model-id">

network-config.md +1 −1

Details

247| `registry.npmjs.org` | 플러그인 설치(npm 소스 플러그인 패키지 가져오기 및 플러그인의 Node.js 패키지 종속성 설치), `npx` 실행 MCP 서버 및 Claude Code 자체의 npm 및 bun 설치를 위한 패키지 레지스트리 |247| `registry.npmjs.org` | 플러그인 설치(npm 소스 플러그인 패키지 가져오기 및 플러그인의 Node.js 패키지 종속성 설치), `npx` 실행 MCP 서버 및 Claude Code 자체의 npm 및 bun 설치를 위한 패키지 레지스트리 |

249| `*.frame.claudeusercontent.com` | [Artifact](/docs/ko/artifacts) 콘텐츠 읽기. CLI는 Claude가 Artifact를 열 때 이 호스트에서 Artifact의 파일을 가져오며, Artifact 도구가 계정에 [사용 가능](/docs/ko/artifacts#availability)할 때만 가져옵니다. 도구를 끄고 이 요구사항을 제거하려면 [`"enableArtifact": false`](/docs/ko/settings-reference#enableartifact) 또는 [`CLAUDE_CODE_DISABLE_ARTIFACT=1`](/docs/ko/env-vars)을 설정하십시오. Claude Code는 더 이상 사용되지 않는 [`disableArtifact`](/docs/ko/settings-reference#disableartifact) 설정도 준수합니다. 이러한 설정이 상호 작용하는 방식은 [Artifact 비활성화](/docs/ko/artifacts#disable-artifacts)를 참조하십시오 |249| `*.frame.claudeusercontent.com` | [Artifact](/docs/ko/artifacts) 콘텐츠 읽기. CLI는 Claude가 Artifact를 열 때 이 호스트에서 Artifact의 파일을 가져오며, Artifact 도구가 계정에 [사용 가능](/docs/ko/artifacts#availability)할 때만 가져옵니다. 도구를 끄고 이 요구사항을 제거하려면 [`"enableArtifact": false`](/docs/ko/settings-reference#enableartifact) 또는 [`CLAUDE_CODE_DISABLE_ARTIFACT=1`](/docs/ko/env-vars)을 설정하십시오 |

250| `github.com` | GitHub 호스팅 [플러그인 마켓플레이스](/docs/ko/plugins/overview) 및 플러그인 복제, 공식 Anthropic 마켓플레이스 포함, HTTPS 또는 SSH를 통해. GitHub `owner/repo` 소스를 HTTPS를 통해서만 복제하려면 [`CLAUDE_CODE_PLUGIN_PREFER_HTTPS=1`](/docs/ko/env-vars)을 설정하십시오 |250| `github.com` | GitHub 호스팅 [플러그인 마켓플레이스](/docs/ko/plugins/overview) 및 플러그인 복제, 공식 Anthropic 마켓플레이스 포함, HTTPS 또는 SSH를 통해. GitHub `owner/repo` 소스를 HTTPS를 통해서만 복제하려면 [`CLAUDE_CODE_PLUGIN_PREFER_HTTPS=1`](/docs/ko/env-vars)을 설정하십시오 |

251| `raw.githubusercontent.com` | [`/release-notes`](/docs/ko/commands)에 대한 변경 로그 피드. 대화형 세션에서 Claude Code는 캐시된 변경 로그가 실행 중인 버전을 아직 다루지 않을 때(예: 업데이트 후 첫 시작) 시작 시 백그라운드에서도 가져옵니다. 비대화형 및 클라우드 세션은 절대 가져오지 않습니다 |251| `raw.githubusercontent.com` | [`/release-notes`](/docs/ko/commands)에 대한 변경 로그 피드. 대화형 세션에서 Claude Code는 캐시된 변경 로그가 실행 중인 버전을 아직 다루지 않을 때(예: 업데이트 후 첫 시작) 시작 시 백그라운드에서도 가져옵니다. 비대화형 및 클라우드 세션은 절대 가져오지 않습니다 |

252| `*-review.googlesource.com` | `googlesource.com` 체크아웃에서 Gerrit 변경 조회. Claude Desktop Code 탭 세션이 `origin`이 `googlesource.com` 호스트인 [신뢰할 수 있는](/docs/ko/permissions#project-allow-rules-and-workspace-trust) 체크아웃에서 시작되거나 재개될 때, Claude Code는 HEAD의 `Change-Id`와 일치하는 열린 변경에 대해 해당 호스트의 `-review` 서버에 익명으로 한 번 요청합니다. 다른 세션 유형은 조회를 건너뛰며, 다른 Gerrit 호스트는 연결되지 않습니다. 선택 사항: [`CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC`](/docs/ko/env-vars)으로 비활성화 |252| `*-review.googlesource.com` | `googlesource.com` 체크아웃에서 Gerrit 변경 조회. Claude Desktop Code 탭 세션이 `origin`이 `googlesource.com` 호스트인 [신뢰할 수 있는](/docs/ko/permissions#project-allow-rules-and-workspace-trust) 체크아웃에서 시작되거나 재개될 때, Claude Code는 HEAD의 `Change-Id`와 일치하는 열린 변경에 대해 해당 호스트의 `-review` 서버에 익명으로 한 번 요청합니다. 다른 세션 유형은 조회를 건너뛰며, 다른 Gerrit 호스트는 연결되지 않습니다. 선택 사항: [`CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC`](/docs/ko/env-vars)으로 비활성화 |

permission-modes.md +102 −98

Details

67 세션이 시작되는 모드67 세션이 시작되는 모드

68</h2>68</h2>

69 69

~~70터미널에서 새 세션을 시작할 때 Claude Code는 다음 중 첫 번째로 적용되는 것에서 권한 모드를 가져옵니다:~~70터미널에서 새 세션을 시작할 때 Claude Code는 다음 중 적용되는 첫 번째 항목에서 권한 모드를 가져옵니다.

71 71

721. `--permission-mode` 플래그 또는 `--dangerously-skip-permissions`721. `--permission-mode` 플래그 또는 `--dangerously-skip-permissions`

73 73

742. [설정 파일](/docs/ko/settings#where-settings-live)의 `permissions.defaultMode`742. [설정 파일](/docs/ko/settings#where-settings-live)의 `permissions.defaultMode`

75 75

76 `.claude/settings.json` 또는 `.claude/settings.local.json`에서 `"auto"`를 설정하면 값이 적용되지 않고 Claude Code는 `~/.claude/settings.json`의 `defaultMode` 대신 기본 제공 기본값을 사용합니다. 이 두 파일에서 `"bypassPermissions"`를 설정하면 적용되지 않으며 세션은 Manual 모드에서 시작됩니다. 다른 값은 모든 설정 파일에서 적용됩니다.76 `.claude/settings.json` 또는 `.claude/settings.local.json`에서 `"auto"`를 설정하면 해당 값이 적용되지 않으며, Claude Code는 `~/.claude/settings.json`의 `defaultMode` 대신 기본 제공 기본값을 사용합니다. 이 두 파일에서 `"bypassPermissions"`를 설정하면 역시 적용되지 않으며, 세션은 수동 모드에서 시작됩니다. 다른 값들은 모든 설정 파일에서 적용됩니다.

77 77

783. 기본 제공 기본값783. 기본 제공 기본값

79 79

80VS Code 확장이 시작하는 대화는 [권한 모드 전환](#switch-permission-modes)의 확장 자체 목록을 따릅니다. Claude Code가 재개된 세션을 시작하는 권한 모드는 [resume 시 권한 모드](/docs/ko/sessions#permission-mode-on-resume)를 참조하세요.80VS Code 확장 프로그램이 시작하는 대화는 [권한 모드 전환](#switch-permission-modes)의 확장 프로그램 자체 목록을 따릅니다. Claude Code가 재개된 세션을 시작하는 권한 모드에 대해서는 [재개 시 권한 모드](/docs/ko/sessions#permission-mode-on-resume)를 참조하세요.

81 81

82기본 제공 `auto` 기본값은 macOS, Linux, WSL에서 Claude Code v2.1.228 이상이 필요하고, 네이티브 Windows에서는 v2.1.233 이상이 필요합니다. 이전 버전에서는 기본 제공 기본값은 Manual입니다.82기본 제공 `auto` 기본값은 macOS, Linux 및 WSL에서 Claude Code v2.1.228 이상이 필요하며, 기본 Windows에서는 v2.1.233 이상이 필요합니다. 이전 버전에서는 기본 제공 기본값이 수동입니다.

83 83

84기본 제공 기본값은 Claude Code를 실행하는 방법에 따라 달라집니다. 세션과 일치하는 첫 번째 행이 적용됩니다. 표는 터미널 또는 VS Code 확장을 통해 시작하는 세션을 다룹니다. 데스크톱 앱 및 claude.ai는 [권한 모드 전환](#switch-permission-modes)의 Desktop 및 Web 탭을 참조하세요.84기본 제공 기본값은 Claude Code를 실행하는 방식에 따라 달라집니다. 세션과 일치하는 첫 번째 행이 적용됩니다. 이 표는 터미널이나 VS Code 확장 프로그램을 통해 시작하는 세션을 다룹니다. 데스크톱 앱 및 claude.ai의 경우 [권한 모드 전환](#switch-permission-modes)의 데스크톱 및 웹 탭을 참조하세요.

85 85

~~86| Claude Code를 실행하는 방법 | 기본 제공 시작 권한 모드 |~~86| Claude Code를 실행하는 방식 | 기본 제공 시작 권한 모드 |

87| :- | :- |87| :- | :- |

88| 모든 설정 파일이 `disableAutoMode`를 `"disable"`로 설정 | `default` |88| 모든 설정 파일이 `disableAutoMode`를 `"disable"`로 설정 | `default` |

~~89| `claude -p` 또는 [Agent SDK](/docs/ko/agent-sdk/permissions) | `default` |~~89| `claude -p` 또는 [Agent SDK](/docs/ko/agent-sdk/permissions#permission-modes) | [기능 플래그를 가져오는](/docs/ko/env-vars#features-that-need-feature-flag-fetching) 세션에서 `default`. 기능 플래그를 가져오지 않는 세션(예: 타사 공급자 또는 원격 분석 비활성화)에서는 Claude Code v2.1.285 이상에서 `auto`, 이전 버전에서는 `default`. 자동 기본값을 보류하는 정책이 있는 조직의 세션은 대신 `default`에서 시작됩니다. |

90| 터미널 또는 [VS Code 확장](/docs/ko/vs-code)에서 | Claude Code v2.1.283 이상에서는 `auto`이고, 이전 버전에서는 [기능 플래그를 가져오는](/docs/ko/env-vars#features-that-need-feature-flag-fetching) 세션에서 Pro, Max, Team 플랜의 `auto`이고, 그 외에는 `default`입니다. |90| 터미널 또는 [VS Code 확장 프로그램](/docs/ko/vs-code)을 통해 | Claude Code v2.1.283 이상에서 `auto`; 이전 버전에서는 [기능 플래그를 가져오는](/docs/ko/env-vars#features-that-need-feature-flag-fetching) 세션에서 Pro, Max 또는 Team 플랜의 `auto`, 그 외에는 `default` |

91 91

92[설치 또는 업그레이드 후 첫 번째 세션](/docs/ko/env-vars#first-session-after-an-install-or-upgrade)에서 Claude Code는 기능 플래그가 도착하기 전에 시작 권한 모드를 선택할 수 있습니다. 해당 세션은 표에서 제공하는 것과 다른 권한 모드에서 시작할 수 있으며, 다음 세션은 표와 일치합니다.92[설치 또는 업그레이드 후 첫 번째 세션](/docs/ko/env-vars#first-session-after-an-install-or-upgrade)에서 Claude Code는 기능 플래그가 도착하기 전에 시작 권한 모드를 선택할 수 있습니다. 해당 세션은 표에서 제공하는 것과 다른 권한 모드에서 시작할 수 있으며, 다음 세션은 표와 일치합니다.

93 93

94플래그, 설정 파일, 또는 기본 제공 기본값이 `auto`를 선택하지만 auto mode를 세션에서 사용할 수 없으면 Claude Code는 대신 Manual에서 세션을 시작합니다. Auto mode는 세션이 [가용성 요구사항](#eliminate-prompts-with-auto-mode)을 충족하지 않을 때 사용할 수 없습니다. 예를 들어 설정 파일이 이를 끄거나 지원하지 않는 모델이거나, Anthropic이 서버 측에서 임시로 이를 끈 경우입니다.94플래그, 설정 파일 또는 기본 제공 기본값이 `auto`를 선택하지만 자동 모드를 세션에서 사용할 수 없는 경우, Claude Code는 대신 수동 모드에서 세션을 시작합니다. 자동 모드는 세션이 [가용성 요구 사항](#eliminate-prompts-with-auto-mode)을 충족하지 않을 때(예: 설정 파일이 자동 모드를 비활성화하거나 지원하지 않는 모델) 또는 Anthropic이 서버 측에서 임시로 자동 모드를 비활성화했을 때 사용할 수 없습니다.

95 95

~~96기본 제공 기본값이 처음으로 세션 중 하나를 auto mode에서 시작할 때 Claude Code는 이 페이지로 연결되는 알림을 표시합니다:~~96기본 제공 기본값이 처음으로 세션 중 하나를 자동 모드에서 시작할 때, Claude Code는 이 페이지로 연결되는 알림을 표시합니다.

97 97

~~98* 터미널에서 세션 상단에 한 번~~98* 터미널에서 세션 맨 위에 한 번

~~99* VS Code 확장에서 새 대화 화면의 카드로 해제할 때까지 유지됨~~99* VS Code 확장 프로그램에서 새 대화 화면의 카드로 표시되며, 이를 닫을 때까지 유지됩니다.

100 100

101Pro, Max, Team 플랜에서 `~/.claude/settings.json`이 `auto` 이외의 `defaultMode`를 설정하고 다른 설정 파일이 설정하지 않으면 세션은 해당 모드에서 계속 시작됩니다. Claude Code는 터미널 또는 VS Code 확장에서 한 번 설정을 auto mode로 변경할지 묻습니다. 거부하면 설정은 그대로 유지됩니다.101`~/.claude/settings.json`이 `auto` 이외의 `defaultMode`를 설정하고 다른 설정 파일이 설정하지 않으면, 세션은 계속해서 해당 모드에서 시작됩니다. Pro, Max 및 Team 플랜에서, 그리고 [기능 플래그를 가져오지 않는](/docs/ko/env-vars#features-that-need-feature-flag-fetching) 세션에서 Claude Code는 터미널 또는 VS Code 확장 프로그램에서 한 번 설정을 자동 모드로 변경할지 여부를 묻습니다. 거절하면 설정은 그대로 유지됩니다.

102 102

103<h3 id="start-in-a-different-mode">103<h3 id="start-in-a-different-mode">

104 다른 권한 모드에서 시작104 다른 권한 모드에서 시작

105</h3>105</h3>

106 106

107한 세션, 또는 머신, 프로젝트, 또는 조직의 모든 세션에 대한 기본값으로 시작 권한 모드를 설정할 수 있습니다. 둘 이상의 설정 파일이 `permissions.defaultMode`를 설정하면 [설정 우선순위](/docs/ko/settings#settings-precedence)가 결정하므로 프로젝트 또는 관리형 값이 `~/.claude/settings.json`을 능가합니다. 이미 실행 중인 세션의 권한 모드를 변경하려면 [권한 모드 전환](#switch-permission-modes)을 참조하세요.107한 세션에 대해 또는 머신, 프로젝트 또는 조직의 모든 세션에 대한 기본값으로 시작 권한 모드를 설정할 수 있습니다. 둘 이상의 설정 파일이 `permissions.defaultMode`를 설정할 때 [설정 우선순위](/docs/ko/settings#settings-precedence)가 결정하므로, 프로젝트 또는 관리되는 값이 `~/.claude/settings.json`을 능가합니다. 이미 실행 중인 세션의 권한 모드를 변경하려면 [권한 모드 전환](#switch-permission-modes)을 참조하세요.

108 108

109| 시작 권한 모드를 설정하려면 | 이렇게 하세요 |109| 시작 권한 모드를 설정하는 대상 | 수행할 작업 |

110| :- | :- |110| :- | :- |

112| 이 머신에서 시작하는 모든 터미널 세션 | `~/.claude/settings.json`에서 `permissions.defaultMode`를 설정합니다. VS Code 확장이 읽는 것은 [권한 모드 전환](#switch-permission-modes)을 참조하세요. |112| 이 머신에서 시작하는 모든 터미널 세션 | `~/.claude/settings.json`에서 `permissions.defaultMode`를 설정합니다. VS Code 확장 프로그램이 읽는 내용은 [권한 모드 전환](#switch-permission-modes)을 참조하세요. |

113| 한 프로젝트에서 시작하는 모든 터미널 세션 | 프로젝트의 `.claude/settings.json`에서 `permissions.defaultMode`를 설정합니다. 터미널에서 시작하는 세션은 `auto` 및 `bypassPermissions`를 제외한 모든 값을 준수합니다. VS Code 확장이 시작하는 세션은 시작 권한 모드에 대해 프로젝트 설정을 읽지 않습니다. |113| 한 프로젝트에서 시작하는 모든 터미널 세션 | 프로젝트의 `.claude/settings.json`에서 `permissions.defaultMode`를 설정합니다. 터미널에서 시작하는 세션은 `auto` 및 `bypassPermissions`을 제외한 모든 값을 준수합니다. VS Code 확장 프로그램이 시작하는 세션은 시작 권한 모드에 대한 프로젝트 설정을 읽지 않습니다. |

114| 조직의 모든 터미널 세션 | [관리형 설정](/docs/ko/managed-settings)에서 `permissions.defaultMode`를 설정합니다. 터미널 세션은 해당 모드에서 시작하고 사람들은 여전히 auto mode로 전환할 수 있습니다. VS Code 확장이 읽는 것은 [권한 모드 전환](#switch-permission-modes)을 참조하세요. auto mode를 제거하여 아무도 선택할 수 없도록 하려면 `permissions.disableAutoMode`를 `"disable"`로 설정합니다. |114| 조직의 모든 터미널 세션 | [관리되는 설정](/docs/ko/managed-settings)에서 `permissions.defaultMode`를 설정합니다. 터미널 세션은 해당 모드에서 시작되며 사용자는 여전히 자동 모드로 전환할 수 있습니다. VS Code 확장 프로그램이 읽는 내용은 [권한 모드 전환](#switch-permission-modes)을 참조하세요. 자동 모드를 제거하여 아무도 선택할 수 없도록 하려면 `permissions.disableAutoMode`를 `"disable"`로 설정합니다. |

115 115

116이 예제는 머신의 모든 터미널 세션을 Manual 모드(설정 값 `default`)에서 시작하도록 합니다. `~/.claude/settings.json`에 저장합니다:116이 예제는 머신의 모든 터미널 세션이 수동 모드(구성 값은 `default`)에서 시작되도록 합니다. `~/.claude/settings.json`에 저장합니다.

117 117

118```json theme={null}118```json theme={null}

119{119{

123}123}

124```124```

125 125

126다음 세션은 상태 표시줄에 `⏸ manual mode on`을 표시합니다.126다음 세션을 시작하면 상태 표시줄에 `⏸ manual mode on`이 표시됩니다.

127 127

128<h2 id="switch-permission-modes">128<h2 id="switch-permission-modes">

129 권한 모드 전환129 권한 모드 전환

291 자동 모드로 권한 프롬프트 제거291 자동 모드로 권한 프롬프트 제거

292</h2>292</h2>

293 293

294자동 모드를 사용하면 Claude가 일상적인 권한 프롬프트 없이 실행될 수 있습니다. 별도의 분류기 모델이 실행 전에 작업을 검토하여 요청을 초과하거나, 인식되지 않은 인프라를 대상으로 하거나, Claude가 읽은 악의적인 콘텐츠로 인해 발생한 것으로 보이는 모든 것을 차단합니다. 명시적 [요청 규칙](/docs/ko/permissions#manage-permissions)은 여전히 프롬프트를 강제합니다.294자동 모드를 사용하면 Claude가 일상적인 권한 프롬프트 없이 실행될 수 있습니다. 별도의 분류기 모델이 실행 전에 작업을 검토하여 요청을 초과하는 모든 것, 인식되지 않은 인프라를 대상으로 하는 것, 또는 Claude가 읽은 악의적인 콘텐츠로 인해 발생한 것으로 보이는 것을 차단합니다. 명시적 [요청 규칙](/docs/ko/permissions#manage-permissions)은 여전히 프롬프트를 강제합니다.

295 295

296Claude Code v2.1.283 이상에서는 자동 모드가 모든 플랜 및 제공자의 대화형 터미널 및 VS Code 세션에 대한 [기본 제공 시작 권한 모드](#which-mode-a-session-starts-in)입니다. 이전 버전에서는 Pro, Max 및 Team 플랜에서만 기본 제공 시작 권한 모드입니다.296Claude Code v2.1.283 이상에서는 자동 모드가 모든 플랜 및 제공자의 대화형 터미널 및 VS Code 세션에 대한 [기본 제공 시작 권한 모드](#which-mode-a-session-starts-in)입니다. 이전 버전에서는 Pro, Max 및 Team 플랜에서만 기본 제공 시작 권한 모드입니다.

297 297

298분류기는 또한 자동 모드와 [플랜 모드에서 분류기가 명령을 검토하는 동안](#analyze-before-you-edit-with-plan-mode) 모두에서 Claude Code가 전달하기 전에 [`SendMessage`](/docs/ko/tools-reference)를 사용하여 다른 에이전트에 보내는 각 메시지(일반 텍스트 또는 구조화된 [에이전트 팀](/docs/ko/agent-teams) 메시지)를 검토합니다. 전송 검토에는 Claude Code v2.1.222 이상이 필요합니다.298분류기는 또한 자동 모드와 [분류기가 명령을 검토하는 동안 계획 모드](#analyze-before-you-edit-with-plan-mode)에서 Claude Code가 전달하기 전에 [`SendMessage`](/docs/ko/tools-reference)를 사용하여 다른 에이전트에 보내는 각 메시지(일반 텍스트 또는 구조화된 [에이전트 팀](/docs/ko/agent-teams) 메시지)를 검토합니다. 전송 검토에는 Claude Code v2.1.222 이상이 필요합니다.

299 299

300기본적으로 분류기는 `rm -rf /` 또는 `rm -rf ~`와 같은 중요 경로를 대상으로 하는 `rm` 및 `rmdir` 제거를 검토하지 않습니다. [중요 경로](#critical-paths)는 각 권한 모드에서 이들에게 어떤 일이 발생하는지 다룹니다.300기본적으로 분류기는 `rm -rf /` 또는 `rm -rf ~`와 같은 중요 경로를 대상으로 하는 `rm` 및 `rmdir` 제거를 검토하지 않습니다. [중요 경로](#critical-paths)는 각 권한 모드에서 이들에게 어떤 일이 발생하는지 다룹니다.

301 301

302자동 모드는 또한 Claude가 명확히 하는 질문을 위해 멈추지 않고 계속 작업하도록 Claude를 유도하지만, Claude는 여전히 프롬프트나 스킬이 명시적으로 이를 요구할 때 질문합니다. 여전히 프롬프트를 표시하는 모드에서 더 강력한 자율 동작을 원하면 [사전 예방적 출력 스타일](/docs/ko/output-styles)을 설정하세요.302자동 모드는 또한 Claude가 명확히 하는 질문을 위해 멈추지 않고 계속 작업하도록 Claude를 유도하지만, Claude는 여전히 프롬프트나 스킬이 명시적으로 이를 요구할 때 질문합니다. 여전히 프롬프트를 표시하는 모드에서 더 강력한 자율 동작을 원하면 [적극적 출력 스타일](/docs/ko/output-styles)을 대신 설정하세요.

303 303

304<Warning>304<Warning>

305 자동 모드는 권한 프롬프트를 줄이지만 안전을 보장하지 않습니다. 일반적인 방향을 신뢰하는 작업에 사용하고, 민감한 작업에 대한 검토 대체로 사용하지 마세요.305 자동 모드는 권한 프롬프트를 줄이지만 안전을 보장하지 않습니다. 일반적인 방향을 신뢰하는 작업에 사용하고, 민감한 작업에 대한 검토 대체로 사용하지 마세요.

306</Warning>306</Warning>

307 307

308자동 모드는 계정이 다음 모든 요구 사항을 충족할 때만 사용 가능합니다:308자동 모드는 계정이 다음 요구 사항을 모두 충족할 때만 사용 가능합니다:

309 309

310* **플랜**: 모든 플랜.310* **플랜**: 모든 플랜.

311* **조직**: Team 및 Enterprise에서는 자동 모드를 기본적으로 사용할 수 있습니다. 관리자는 [관리 설정](/docs/ko/managed-settings)에서 `permissions.disableAutoMode`를 `"disable"`로 설정하여 조직에 대해 이를 끌 수 있습니다.311* **조직**: Team 및 Enterprise에서는 자동 모드를 기본적으로 사용할 수 있습니다. 관리자는 [관리 설정](/docs/ko/managed-settings)에서 `permissions.disableAutoMode`를 `"disable"`로 설정하여 조직에 대해 이를 끌 수 있습니다.

312* **모델**: Anthropic API 및 [AWS의 Claude Platform](/docs/ko/claude-platform-on-aws)에서는 Claude Opus 4.6 이상, Sonnet 4.6 이상 또는 [Fable 모델](/docs/ko/model-config#work-with-fable). Amazon Bedrock, Google Cloud의 Agent Platform, Microsoft Foundry 및 로그인한 [Claude 앱 게이트웨이](/docs/ko/claude-apps-gateway) 세션에서는 Claude Sonnet 5 이상, Opus 4.7 이상 및 Fable 모델만 해당합니다. Sonnet 4.5, Opus 4.5, Haiku 및 claude-3 모델을 포함한 이전 모델은 어떤 제공자에서도 지원되지 않습니다.312* **모델**: Anthropic API 및 [AWS의 Claude Platform](/docs/ko/claude-platform-on-aws)에서는 Claude Opus 4.6 이상, Sonnet 4.6 이상 또는 [Fable 모델](/docs/ko/model-config#work-with-fable). Amazon Bedrock, Google Cloud의 Agent Platform, Microsoft Foundry 및 로그인한 [Claude 앱 게이트웨이](/docs/ko/claude-apps-gateway) 세션에서는 Claude Sonnet 5 이상, Opus 4.7 이상 및 Fable 모델만 해당합니다. Sonnet 4.5, Opus 4.5, Haiku 및 claude-3 모델을 포함한 이전 모델은 어떤 제공자에서도 지원되지 않습니다.

313* **제공자**: Anthropic API, AWS의 Claude Platform, Amazon Bedrock, Google Cloud의 Agent Platform, Microsoft Foundry 및 로그인한 Claude 앱 게이트웨이 세션에서 기본적으로 사용 가능합니다.313* **제공자**: Anthropic API, AWS의 Claude Platform, Amazon Bedrock, Google Cloud의 Agent Platform, Microsoft Foundry 및 로그인한 Claude 앱 게이트웨이 세션에서 기본적으로 사용 가능합니다.

314 314

315Claude Code가 자동 모드를 사용할 수 없다고 보고하면 먼저 이러한 요구 사항과 설정 파일이 [`disableAutoMode`](/docs/ko/settings-reference#disableautomode)를 설정하는지 확인하세요. Anthropic이 서버 측에서 자동 모드를 끄거나 서버가 계정에 대해 자동 모드를 거부했을 수도 있습니다. 두 답변 중 하나를 받은 세션은 세션이 끝날 때까지 자동 모드를 끈 상태로 유지하므로 나중에 새 세션을 시작하세요.315Claude Code가 자동 모드를 사용할 수 없다고 보고하면 먼저 이러한 요구 사항과 설정 파일이 [`disableAutoMode`](/docs/ko/settings-reference#disableautomode)를 설정하는지 확인하세요. Anthropic은 또한 서버 측에서 자동 모드를 끄거나 서버가 계정에 대해 자동 모드를 거부했을 수 있습니다. 어느 한 답변을 받은 세션은 세션이 끝날 때까지 자동 모드를 끈 상태로 유지하므로 나중에 새 세션을 시작하세요.

316 316

317모델의 이름을 지정하고 자동 모드가 작업의 안전성을 "결정할 수 없다"고 말하는 별도의 메시지는 분류기 요청이 실패했음을 의미합니다. 이 실패는 일반적으로 일시적이지만 Amazon Bedrock에서는 계정이 명명된 모델을 호출할 수 있을 때까지 반복될 수 있습니다. 원인 및 수행할 작업은 [오류 참조](/docs/ko/errors#auto-mode-cannot-determine-the-safety-of-an-action)를 참조하세요.317모델을 이름 지정하고 자동 모드가 작업의 안전성을 "결정할 수 없다"고 말하는 별도의 메시지는 분류기 요청이 실패했음을 의미합니다. 이 실패는 일반적으로 일시적이지만 Amazon Bedrock에서는 계정이 명명된 모델을 호출할 수 있을 때까지 반복될 수 있습니다. 원인 및 수행할 작업은 [오류 참조](/docs/ko/errors#auto-mode-cannot-determine-the-safety-of-an-action)를 참조하세요.

318 318

319[설정](/docs/ko/settings-reference#all-settings)에서 `defaultMode: "auto"`를 설정했는데 터미널 세션이 오류 없이 Manual 모드에서 시작되면 설정이 `.claude/settings.json` 또는 `.claude/settings.local.json`에 있을 가능성이 높습니다. `auto`는 이러한 파일에서 적용되지 않습니다. `~/.claude/settings.json`으로 이동하세요. VS Code 확장이 시작한 대화의 경우 [권한 모드 전환](#switch-permission-modes) 대신 확장의 자체 목록을 확인하세요.319[설정](/docs/ko/settings-reference#all-settings)에서 `defaultMode: "auto"`를 설정했는데 터미널 세션이 오류 없이 Manual 모드로 시작되면 설정이 `.claude/settings.json` 또는 `.claude/settings.local.json`에 있을 가능성이 높습니다. `auto`는 이러한 파일에서 적용되지 않습니다. `~/.claude/settings.json`으로 이동하세요. VS Code 확장이 시작한 대화의 경우 [권한 모드 전환](#switch-permission-modes) 대신 확장의 자체 목록을 확인하세요.

320 320

321<h3 id="enable-auto-mode-on-bedrock-agent-platform-or-foundry">321<h3 id="enable-auto-mode-on-bedrock-agent-platform-or-foundry">

322 Bedrock, Agent Platform 또는 Foundry의 자동 모드322 Bedrock, Agent Platform 또는 Foundry의 자동 모드

323</h3>323</h3>

324 324

325[Amazon Bedrock](/docs/ko/amazon-bedrock), [Google Cloud의 Agent Platform](/docs/ko/google-vertex-ai), [Microsoft Foundry](/docs/ko/microsoft-foundry) 및 로그인한 [Claude 앱 게이트웨이](/docs/ko/claude-apps-gateway) 세션에서는 자동 모드를 기본적으로 사용할 수 있습니다. Claude Code v2.1.283 이상에서는 대화형 터미널 및 [VS Code](/docs/ko/vs-code) 세션에 대한 [기본 제공 시작 권한 모드](#which-mode-a-session-starts-in)이기도 합니다. 시작 권한 모드를 직접 선택하려면 [다른 권한 모드에서 시작](#start-in-a-different-mode)에서 설명하는 대로 `permissions.defaultMode`를 설정하거나 VS Code 확장의 모드 표시기에서 권한 모드를 선택하세요.325[Amazon Bedrock](/docs/ko/amazon-bedrock), [Google Cloud의 Agent Platform](/docs/ko/google-vertex-ai), [Microsoft Foundry](/docs/ko/microsoft-foundry) 및 로그인한 [Claude 앱 게이트웨이](/docs/ko/claude-apps-gateway) 세션에서는 자동 모드를 기본적으로 사용할 수 있습니다. 다른 것이 권한 모드를 설정하지 않으면 해당 섹션의 테이블이 나열하는 버전에서도 [기본 제공 시작 권한 모드](#which-mode-a-session-starts-in)입니다. 시작 권한 모드를 직접 선택하려면 [다른 권한 모드에서 시작](#start-in-a-different-mode)이 설명하는 대로 `permissions.defaultMode`를 설정하거나 VS Code 확장의 모드 표시기에서 권한 모드를 선택하세요.

326 326

327이러한 제공자에서는 Claude Sonnet 5 이상, Opus 4.7 이상 및 Fable 모델만 지원됩니다. 다른 모델에서는 세션이 Manual로 시작됩니다.327이러한 제공자에서는 Claude Sonnet 5 이상, Opus 4.7 이상 및 Fable 모델만 지원됩니다. 다른 모델에서는 세션이 Manual로 시작됩니다.

328 328

329개발자가 자동 모드를 사용하지 못하도록 하려면 [관리 설정](/docs/ko/managed-settings)에서 `disableAutoMode`를 `"disable"`로 설정하세요. 이렇게 하면 `Shift+Tab` 사이클에서 `auto`가 제거되고, `--permission-mode auto`로 시작한 세션은 Manual로 시작됩니다. 이미 자동 모드에서 실행 중인 세션은 설정이 [관리자 배포 소스](/docs/ko/managed-settings#which-managed-source-claude-code-uses)에서 해당 세션에 도달할 때 이를 떠나고 `auto mode disabled by settings`를 표시합니다. v2.1.251 이전에는 실행 중인 세션이 끝날 때까지 자동 모드를 유지했습니다.329개발자가 자동 모드를 사용하지 못하도록 하려면 [관리 설정](/docs/ko/managed-settings)에서 `disableAutoMode`를 `"disable"`로 설정하세요. 이렇게 하면 `Shift+Tab` 사이클에서 `auto`가 제거되고, `--permission-mode auto`로 시작된 세션은 Manual로 시작됩니다. 이미 자동 모드로 실행 중인 세션은 설정이 [관리자 배포 소스](/docs/ko/managed-settings#which-managed-source-claude-code-uses)에서 해당 세션에 도달할 때 이를 떠나고 `auto mode disabled by settings`를 표시합니다. v2.1.251 이전에는 실행 중인 세션이 끝날 때까지 자동 모드를 유지했습니다.

330 330

331v2.1.158부터 v2.1.206까지는 `CLAUDE_CODE_ENABLE_AUTO_MODE=1`을 설정할 때까지 이러한 제공자에서 자동 모드가 꺼져 있었고, Claude Code는 변수도 설정되지 않은 한 이러한 제공자에서 `defaultMode: "auto"`를 무시했습니다. 변수는 호환성을 위해 여전히 허용되며 v2.1.207 이후로는 효과가 없습니다.331v2.1.158부터 v2.1.206까지는 `CLAUDE_CODE_ENABLE_AUTO_MODE=1`을 설정할 때까지 이러한 제공자에서 자동 모드가 꺼져 있었고, Claude Code는 변수도 설정되지 않으면 이러한 제공자에서 `defaultMode: "auto"`를 무시했습니다. 변수는 호환성을 위해 여전히 허용되며 v2.1.207 이후로는 효과가 없습니다.

332 332

333<h3 id="server-side-classifier-review">333<h3 id="server-side-classifier-review">

334 서버 측 분류기 검토334 서버 측 분류기 검토

336 336

337자동 모드에서 Claude Code는 서버에 [결정 순서](#how-the-classifier-evaluates-actions)가 검토를 위해 보내는 작업을 확인하도록 요청할 수 있으며, 이는 자체 분류기 요청을 보내는 대신 세션의 모델 요청의 일부로 수행됩니다. 이러한 세션은 다음을 요청합니다:337자동 모드에서 Claude Code는 서버에 [결정 순서](#how-the-classifier-evaluates-actions)가 검토를 위해 보내는 작업을 확인하도록 요청할 수 있으며, 이는 자체 분류기 요청을 보내는 대신 세션의 모델 요청의 일부로 수행됩니다. 이러한 세션은 다음을 요청합니다:

338 338

339* **Anthropic API에 대한 직접 연결**: 대화형 터미널 세션에서 모든 claude.ai 플랜 및 Claude API를 사용하는 계정에서 Anthropic이 롤아웃할 때. Pro, Max 및 Team 플랜에서는 Claude Code v2.1.271 이상이 필요하고, Enterprise 플랜 및 Claude API 계정에서는 v2.1.278 이상이 필요합니다. v2.1.282부터는 [기능 플래그를 가져오지 않는](/docs/ko/env-vars#features-that-need-feature-flag-fetching) 세션(예: 원격 측정을 끈 경우)은 모든 종류의 세션에서 기본적으로 서버에 요청합니다.339* **Anthropic API에 대한 직접 연결**: 대화형 터미널 세션에서 모든 claude.ai 플랜 및 Claude API를 사용하는 계정에서 Anthropic이 롤아웃할 때. Pro, Max 및 Team 플랜에서는 Claude Code v2.1.271 이상이 필요하고, Enterprise 플랜 및 Claude API 계정에서는 v2.1.278 이상이 필요합니다. v2.1.282부터는 [기능 플래그를 가져오지 않는](/docs/ko/env-vars#features-that-need-feature-flag-fetching) 세션(예: 원격 분석을 끈 경우)은 모든 종류의 세션에서 기본적으로 서버에 요청합니다.

340* **클라우드 제공자, LLM 게이트웨이 또는 프록시**: [AWS의 Claude Platform](/docs/ko/claude-platform-on-aws), Amazon Bedrock, Google Cloud의 Agent Platform 및 Microsoft Foundry에서, 그리고 `ANTHROPIC_BASE_URL`을 [LLM 게이트웨이 또는 프록시](/docs/ko/llm-gateway)로 가리킬 때마다 플랜에 관계없이. 기본적으로 요청하려면 Claude Code v2.1.278 이상이 필요합니다.340* **클라우드 제공자, LLM 게이트웨이 또는 프록시**: [AWS의 Claude Platform](/docs/ko/claude-platform-on-aws), Amazon Bedrock, Google Cloud의 Agent Platform 및 Microsoft Foundry에서, 그리고 `ANTHROPIC_BASE_URL`을 [LLM 게이트웨이 또는 프록시](/docs/ko/llm-gateway)로 가리킬 때마다 플랜에 관계없이. 기본적으로 요청하려면 Claude Code v2.1.278 이상이 필요합니다.

341* **로그인한 [Claude 앱 게이트웨이](/docs/ko/claude-apps-gateway) 세션**: Claude Code v2.1.280 이상이 필요합니다341* **로그인한 [Claude 앱 게이트웨이](/docs/ko/claude-apps-gateway) 세션**: Claude Code v2.1.280 이상이 필요합니다

342 342

343서버가 작업을 검토하는 경우 해당 판정이 이를 결정합니다. 다른 두 가지 결과가 가능합니다:343서버가 작업을 검토하는 경우 해당 판정이 이를 결정합니다. 다른 두 가지 결과가 가능합니다:

344 344

345* **서버가 세션을 검토하지 않음**: 응답이 검토 결과 없이 완료되거나 서버가 이 세션을 검토하지 않는다고 답합니다. 가장 일반적인 원인은 검토 요청이나 결과를 삭제하는 LLM 게이트웨이 또는 프록시이며, 아직 서버 측 검사가 없는 플랫폼, 지역 또는 자격 증명입니다. Claude Code는 자체 분류기 요청으로 폴백합니다. 이 폴백이 세션의 나머지 부분에 대해 유지되면 [분류기 요청 요금에 대한 공지](/docs/ko/auto-mode-classifier-billing)를 표시합니다.345* **서버가 세션을 검토하지 않음**: 응답이 검토 결과 없이 완료되거나 서버가 이 세션을 검토하지 않는다고 답합니다. 가장 일반적인 원인은 검토 요청이나 결과를 삭제하는 LLM 게이트웨이 또는 프록시이며, 아직 서버 측 검사가 없는 플랫폼, 지역 또는 자격 증명입니다. Claude Code는 자체 분류기 요청으로 폴백합니다. 이 폴백이 세션의 나머지 부분에 대해 유지되면 [분류기 요청 요금에 대한 공지](/docs/ko/auto-mode-classifier-billing)를 이러한 요청이 청구되는 계정에 표시합니다.

346* **서버가 작업에 대한 판정을 제공하지 않음**: Claude Code는 검토되지 않은 상태로 실행하는 대신 작업을 거부합니다. 모든 연결에서 이는 응답이 검토 결과가 도착하기 전에 끝나거나 결과가 Claude Code가 읽을 수 없는 형식으로 도착할 때 발생합니다. 응답을 단축하거나 결과를 다시 작성하는 LLM 게이트웨이 또는 프록시가 둘 다 발생할 수 있습니다. Anthropic API에 대한 직접 연결에서는 서버의 검사가 작업에 대해 실패할 때도 발생합니다(예: 시간 초과). [서버가 안전 판정을 반환하지 않음](/docs/ko/errors#the-server-returned-no-safety-verdict)은 거부 메시지, 거부가 반복될 때 발생하는 일 및 수행할 작업을 다룹니다.346* **서버가 작업에 대한 판정을 제공하지 않음**: Claude Code는 검토되지 않은 상태로 실행하는 대신 작업을 거부합니다. 모든 연결에서 이는 응답이 검토 결과가 도착하기 전에 끝나거나 결과가 Claude Code가 읽을 수 없는 형식으로 도착할 때 발생합니다. 응답을 단축하거나 결과를 다시 작성하는 LLM 게이트웨이 또는 프록시가 둘 다 발생할 수 있습니다. Anthropic API에 대한 직접 연결에서는 서버의 검사가 작업에 대해 실패할 때도 발생합니다(예: 시간 초과). [서버가 안전 판정을 반환하지 않음](/docs/ko/errors#the-server-returned-no-safety-verdict)은 거부 메시지, 거부가 반복될 때 발생하는 일 및 수행할 작업을 다룹니다.

347 347

348서버에 요청하는 것을 건너뛰고 항상 Claude Code의 자체 분류기 요청을 사용하려면 [`CLAUDE_CODE_AUTO_MODE_SERVER=0`](/docs/ko/env-vars)을 설정하세요. Anthropic API에 대한 직접 연결에서 변수에는 Claude Code v2.1.281 이상이 필요합니다. 거기서 `1`로 설정하면 `-p` 또는 Agent SDK 세션과 같이 아직 서버 검토가 없는 세션에서 서버 검토를 켭니다. `CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1`도 설정하지 않은 경우입니다. `CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1`을 설정하고 `CLAUDE_CODE_AUTO_MODE_SERVER`를 설정하지 않은 상태로 두면 Claude Code도 서버에 요청하는 것을 중지합니다. [사전 릴리스 기능 비활성화](/docs/ko/llm-gateway-protocol#disable-pre-release-capabilities)에서 설명하는 경우는 제외합니다.348서버에 요청하는 것을 건너뛰고 항상 Claude Code의 자체 분류기 요청을 사용하려면 [`CLAUDE_CODE_AUTO_MODE_SERVER=0`](/docs/ko/env-vars)을 설정하세요. Anthropic API에 대한 직접 연결에서 변수에는 Claude Code v2.1.281 이상이 필요합니다. 거기서 `1`로 설정하면 아직 서버 검토가 없는 세션(예: `-p` 또는 Agent SDK 세션)에서 서버 검토를 켭니다. `CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1`도 설정하지 않은 경우입니다. `CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1`을 설정하고 `CLAUDE_CODE_AUTO_MODE_SERVER`를 설정하지 않으면 Claude Code도 서버에 요청하는 것을 중지합니다. [사전 릴리스 기능 비활성화](/docs/ko/llm-gateway-protocol#disable-pre-release-capabilities)가 설명하는 경우는 제외합니다.

349 349

350<h3 id="what-the-classifier-blocks-by-default">350<h3 id="what-the-classifier-blocks-by-default">

351 분류기가 기본적으로 차단하는 것351 분류기가 기본적으로 차단하는 것

363* 공유 인프라 수정363* 공유 인프라 수정

364* 세션 전에 존재했던 파일을 돌이킬 수 없게 파괴364* 세션 전에 존재했던 파일을 돌이킬 수 없게 파괴

365* 강제 푸시365* 강제 푸시

366* 리포지토리 외부로 비밀 또는 민감한 데이터를 보내거나 배포가 노출하는 것을 확대할 변경 사항을 커밋하거나 푸시합니다. 이는 비밀을 아직 받지 않는 대상으로 전달하는 CI 워크플로우 또는 배포 구성, 비밀 저장소를 읽고 데이터를 보내는 스크립트 또는 설정 단계, 그리고 배포가 게시하는 것을 확대하는 구성 변경(예: 레지스트리, 가시성, 아티팩트 또는 소스맵 설정)을 다룹니다. 검사는 모든 분기에 적용되고, 리포지토리가 공개인 경우에도 적용되며, 파이프라인을 트리거하는지 여부에 관계없이 커밋이나 푸시가 발생할 때 실행됩니다. 이를 지우려면 커밋이나 푸시만이 아니라 실행 효과의 이름을 지정해야 합니다. v2.1.211 이전에는 이 검사가 기본 분기로 범위가 지정되었습니다: 거기로의 푸시는 민감한 콘텐츠, 요청한 것과 비교하여 숨겨지거나 잘못 설명된 변경 사항, 리포지토리 외부에서 이식된 콘텐츠 또는 요청한 검토를 우회하는 콘텐츠를 전달할 때 차단되었습니다.366* 실행될 때 비밀이나 민감한 데이터를 리포지토리 외부로 보내거나 배포가 노출하는 것을 확대할 변경 사항을 커밋하거나 푸시합니다. 이는 비밀을 아직 받지 않는 대상으로 전달하는 CI 워크플로우 또는 배포 구성, 비밀 저장소를 읽고 데이터를 보내는 스크립트 또는 설정 단계, 그리고 배포가 게시하는 것을 확대하는 구성 변경(예: 레지스트리, 가시성, 아티팩트 또는 소스맵 설정)을 다룹니다. 검사는 모든 분기에 적용되고, 리포지토리가 공개인 경우에도 적용되며, 해당 커밋이나 푸시가 파이프라인을 트리거하는지 여부에 관계없이 커밋되거나 푸시될 때 발생합니다. 이를 지우려면 커밋이나 푸시만이 아니라 실행 효과를 이름 지정해야 합니다. v2.1.211 이전에는 이 검사가 기본 분기로 범위가 지정되었습니다: 거기로의 푸시는 민감한 콘텐츠, 요청한 것과 비교하여 숨겨지거나 잘못 설명된 변경 사항, 리포지토리 외부에서 이식된 콘텐츠 또는 요청한 검토 주변으로 라우팅된 콘텐츠를 전달할 때 차단되었습니다.

367* `git reset --hard`, `git checkout -- .`, `git restore .`, `git clean -fd`, `git stash drop` 또는 `git stash clear`는 분류기가 커밋되지 않은 변경 사항을 삭제할 것으로 가정합니다.367* `git reset --hard`, `git checkout -- .`, `git restore .`, `git clean -fd`, `git stash drop` 또는 `git stash clear`는 분류기가 커밋되지 않은 변경 사항을 삭제할 것으로 가정합니다.

368* v2.1.198부터 HEAD의 커밋이 이미 푸시된 경우 `git commit --amend`. 메시지 전용 단어 변경은 차단되지 않습니다: 이 세션 중에 Claude가 생성한 커밋에서 새로 스테이징된 것이 없는 `--amend -m`.368* 커밋이 이 세션에서 생성되지 않았을 때 `git commit --amend`

369* v2.1.198부터 커밋이 이미 푸시되었을 때 `git commit --amend`. 메시지 전용 단어 변경은 차단되지 않습니다: 새로 스테이징된 것이 없는 `--amend -m`은 Claude가 이 세션 중에 생성한 커밋에서입니다.

369* `terraform destroy`, `pulumi destroy`, `cdk destroy` 또는 `terragrunt destroy`, 그리고 리소스를 파괴하는 계획 적용370* `terraform destroy`, `pulumi destroy`, `cdk destroy` 또는 `terragrunt destroy`, 그리고 리소스를 파괴하는 계획 적용

370* 비밀 관리자에 쓰기, 또는 DNS 레코드 또는 TLS 인증서 변경371* 비밀 관리자에 쓰기, 또는 DNS 레코드 또는 TLS 인증서 변경

371* 인간이 승인하지 않은 풀 요청 병합, Claude의 자체 풀 요청 승인 또는 CI 검사 비활성화372* 인간이 승인하지 않은 풀 요청 병합, Claude의 자체 풀 요청 승인 또는 CI 검사 비활성화

372* `atlantis apply` 또는 봇의 `/deploy` 또는 `/merge`와 같은 자동화에 대한 명령 자체인 댓글 게시373* `atlantis apply` 또는 봇의 `/deploy` 또는 `/merge`와 같은 자동화에 대한 명령 자체인 댓글 게시

373* 프로덕션 기능 플래그 토글, 램프 또는 삭제374* 프로덕션 기능 플래그 토글, 램핑 또는 삭제

374* 보호된 IaC 범위에 인프라 변경 사항 적용, 또는 클러스터 노드 드레인 및 제거375* 보호된 IaC 범위에 인프라 변경 사항 적용, 또는 클러스터 노드 드레이닝 및 제거

375* 레이블 선택기 또는 `--all`과 같이 다른 사용자의 작업을 포착하는 공유 컴퓨팅 클러스터에 대한 쓰기376* 레이블 선택기 또는 `--all`과 같이 다른 사용자의 작업을 포착하는 명명된 리소스를 초과하는 공유 컴퓨팅 클러스터에 쓰기

376* 모든 노드에서 실행되거나 클러스터 트래픽을 가로채는 Kubernetes 리소스 생성(예: DaemonSets 및 승인 웹훅)377* 모든 노드에서 실행되거나 클러스터 트래픽을 가로채는 Kubernetes 리소스 생성(예: DaemonSets 및 승인 웹훅)

377* 민감한 원격 대상으로의 대화형 셸 또는 포트 포워드378* 민감한 원격 대상으로의 대화형 셸 또는 포트 포워드

378* 로컬 서비스를 공개 인터넷에서 도달 가능하게 하는 터널 또는 역셸 열기379* 로컬 서비스를 공개 인터넷에서 도달 가능하게 하는 터널 또는 역셸 열기

379* 라이브 자격 증명 또는 토큰을 기록 또는 파일에 인쇄380* 라이브 자격 증명 또는 토큰을 기록 또는 파일에 인쇄

380* [환경](/docs/ko/auto-mode-config#define-trusted-infrastructure)에서 민감한 데이터 위치로 나열된 위치에 액세스하거나 해당 위치에서 데이터 복사. v2.1.198부터 이는 또한 한 위치에서 항목이 제외하는 대상으로 데이터를 보내는 것을 차단합니다.381* [환경](/docs/ko/auto-mode-config#define-trusted-infrastructure)에서 민감한 데이터 위치로 나열된 위치에 액세스하거나 해당 위치에서 데이터 복사. v2.1.198부터 이는 또한 항목이 제외하는 대상으로 한 위치에서 데이터를 보내는 것을 차단합니다.

381* 내부 패키지 레지스트리를 공개 레지스트리로 우회하는 패키지 설치. v2.1.198부터 이는 또한 환경에 나열된 경우뿐만 아니라 대화에서 Claude에게 내부 레지스트리 또는 미러가 존재한다고 말한 경우에도 적용됩니다.382* 내부 패키지 레지스트리를 공개 레지스트리로 우회하는 패키지 설치 라우팅. v2.1.198부터 이는 또한 대화에서 Claude에 내부 레지스트리 또는 미러가 존재한다고 말했을 때 적용되며, 환경에 나열된 경우만이 아닙니다.

382* `--insecure`와 같은 안전 가드를 해제하는 플래그로 명령 실행383* `--insecure`와 같은 안전 가드를 해제하는 플래그로 명령 실행

383* `--dangerously-skip-permissions` 또는 `--no-sandbox`로 시작한 것과 같이 인간 승인이나 샌드박스 없이 실행되는 자율 에이전트 루프 시작. v2.1.198부터 이는 또한 `--yes-always`로 시작한 러너와 같이 격리 및 작업별 승인이 비활성화된 상태로 제3자 에이전트 또는 평가 하네스를 실행하는 것을 다룹니다.384* `--dangerously-skip-permissions` 또는 `--no-sandbox`로 시작된 것과 같이 인간 승인이나 샌드박스 없이 실행되는 자율 에이전트 루프 시작. v2.1.198부터 이는 또한 `--yes-always`로 시작된 러너와 같이 격리 및 작업별 승인이 비활성화된 상태로 제3자 에이전트 또는 평가 하네스를 실행하는 것을 다룹니다.

384* [Chrome의 Claude](/docs/ko/chrome) 브라우저 작업으로 페이지 콘텐츠, 쿠키 또는 자격 증명을 출처 외부로 보낼 수 있음385* [Chrome의 Claude](/docs/ko/chrome) 브라우저 작업으로 페이지 콘텐츠, 쿠키 또는 자격 증명을 원본 외부로 보낼 수 있음

385 386

386이러한 범주 중 일부는 민감한 원격 대상 및 보호된 IaC 범위와 같이 구체적인 이름으로 좁힐 수 있는 [환경](/docs/ko/auto-mode-config#define-trusted-infrastructure) 항목에 따라 달라집니다.387이러한 범주 중 여러 개는 민감한 원격 대상 및 보호된 IaC 범위와 같이 구체적인 이름으로 좁힐 수 있는 [환경](/docs/ko/auto-mode-config#define-trusted-infrastructure) 항목에 따라 달라집니다.

387 388

388Claude Code v2.1.198 이상도 기본적으로 다음을 차단합니다:389Claude Code v2.1.198 이상도 기본적으로 다음을 차단합니다:

389 390

390* 특정 명명된 경로가 아닌 와일드카드, 글로브 또는 나이 필터로 `/tmp`, `$TMPDIR` 또는 다른 공유 스크래치 또는 캐시 디렉토리의 파일 삭제391* 특정 명명된 경로가 아닌 와일드카드, 글로브 또는 나이 필터로 `/tmp`, `$TMPDIR` 또는 다른 공유 스크래치 또는 캐시 디렉토리의 파일 삭제

391* 자신의 메시지가 해당 수신자에게 이러한 세부 정보를 승인하지 않은 경우 전송, 업로드, 게시 또는 다른 사람이나 공유 시스템에 작성된 콘텐츠에 민감한 세부 정보 포함. PR 및 이슈 본문, 커밋 메시지 및 댓글은 리포지토리가 신뢰 경계 외부이거나 공개인 경우 이러한 종류의 아웃바운드 콘텐츠로 계산됩니다. 조직의 자체 공개 리포지토리 포함; 내부 파일 경로, 코드명, 이메일 또는 계정 식별자와 같은 라이브 API 응답 데이터 및 인프라 식별자는 민감한 세부 정보로 계산됩니다. PR, 이슈 및 커밋 메시지 범위 지정에는 Claude Code v2.1.200 이상이 필요합니다. PR 또는 이슈 본문의 API 응답의 라이브 개인 데이터(예: 이메일 주소, 계정 또는 조직 식별자 또는 사용 메트릭)에는 리포지토리의 가시성이나 신뢰 경계에 관계없이 해당 세부 정보와 수신자의 이름을 지정해야 합니다. 이 검사에는 Claude Code v2.1.203 이상이 필요합니다.392* 자신의 메시지가 해당 수신자에게 이러한 세부 정보를 승인하지 않았을 때 전송, 업로드, 게시 또는 다른 사람이나 공유 시스템에 작성된 콘텐츠에 민감한 세부 정보 포함. PR 및 이슈 본문, 커밋 메시지 및 댓글은 리포지토리가 신뢰 경계 외부이거나 공개일 때 이러한 종류의 아웃바운드 콘텐츠로 계산됩니다. 조직의 자체 공개 리포지토리 포함; 내부 파일 경로, 코드명, 이메일 또는 계정 식별자와 같은 라이브 API 응답 데이터 및 인프라 식별자는 민감한 세부 정보로 계산됩니다. PR, 이슈 및 커밋 메시지 범위 지정에는 Claude Code v2.1.200 이상이 필요합니다. PR 또는 이슈 본문의 API 응답의 라이브 개인 데이터(예: 이메일 주소, 계정 또는 조직 식별자 또는 사용 메트릭)에는 리포지토리의 가시성이나 신뢰 경계에 관계없이 이러한 세부 정보와 수신자를 이름 지정해야 합니다. 이 검사에는 Claude Code v2.1.203 이상이 필요합니다.

392* Claude Code의 자체 tmux 창으로 키스트로크를 보내 자체 인터페이스를 구동하는 것으로, 분류기는 Claude가 자체 권한이나 감시를 변경하는 것으로 취급합니다.393* Claude Code의 자체 tmux 창으로 키스트로크를 보내 자체 인터페이스를 구동하는 것으로, 분류기는 Claude가 자체 권한이나 감시를 변경하는 것으로 취급합니다.

393 394

394Claude Code v2.1.200 이상도 기본적으로 다음을 차단합니다:395Claude Code v2.1.200 이상도 기본적으로 다음을 차단합니다:

395 396

396* 인증, 액세스 제어, 입력 검증 또는 샌드박싱과 같은 보안 동작을 보호하는 테스트 또는 어설션 주석 처리, 삭제 또는 강제 통과397* 인증, 액세스 제어, 입력 검증 또는 샌드박싱과 같은 보안 동작을 보호하는 테스트 또는 어설션을 주석 처리, 삭제 또는 강제 통과

397* Claude가 세션에서 생성하지 않은 상태 저장 리소스 삭제 또는 해체(더 구체적인 삭제 규칙이 적용되지 않고 해당 리소스의 이름을 지정하지 않은 경우)398* Claude가 세션에서 생성하지 않은 상태 저장 리소스 삭제 또는 해체(더 구체적인 삭제 규칙이 적용되지 않고 해당 리소스를 이름 지정하지 않은 경우)

398* API 기본 URL, 프록시 엔드포인트, 웹훅 수신자 또는 레지스트리 미러를 작업에 맞지 않는 제3자 호스트로 다시 가리키기(`.env.example`과 같은 예제 파일 포함)399* API 기본 URL, 프록시 엔드포인트, 웹훅 수신자 또는 레지스트리 미러를 작업에 맞지 않는 제3자 호스트로 다시 가리키기(`.env.example`과 같은 예제 파일 포함)

399* `git remote set-url` 또는 `git remote add`로 푸시가 가는 위치 변경(새 원격의 이름을 지정하지 않은 경우)400* `git remote set-url` 또는 `git remote add`로 푸시가 가는 위치 변경(새 원격을 이름 지정하지 않은 경우)

400* 공개로 알려진 리포지토리로 비밀 또는 개인 또는 신뢰할 수 있는 데이터 푸시, 또는 해당 리포지토리의 자체 작업의 일부가 아닌 기밀 자료를 거기로 푸시. dotfiles 리포지토리의 자체 주제는 개인 또는 신뢰할 수 있는 데이터의 유일한 예외이며, 개인 리포지토리에서 도달하는 콘텐츠는 모든 공개 표면에 동일한 방식으로 차단됩니다. 두 개선 사항 모두 Claude Code v2.1.203 이상이 필요합니다. v2.1.203 이전에는 개인 데이터가 기밀 자료와 함께 그룹화되었고 해당 리포지토리의 자체 작업의 일부가 아닌 경우에만 차단되었습니다. 리포지토리의 가시성이 확립되지 않은 경우 분류기는 그것만으로 차단하지 않습니다. 대신 다른 규칙에 대해 콘텐츠를 판단합니다.401* 공개로 알려진 리포지토리로 비밀이나 개인 또는 신뢰할 수 있는 데이터 푸시, 또는 해당 리포지토리의 자체 작업의 일부가 아닌 기밀 자료를 거기로 푸시. dotfiles 리포지토리의 자체 주제는 개인 또는 신뢰할 수 있는 데이터의 유일한 예외이며, 개인 리포지토리에서 도달하는 콘텐츠는 모든 공개 표면에 동일한 방식으로 차단됩니다. 두 개선 사항 모두 Claude Code v2.1.203 이상이 필요합니다. v2.1.203 이전에는 개인 데이터가 기밀 자료와 함께 그룹화되었고 해당 리포지토리의 자체 작업의 일부가 아닐 때만 차단되었습니다. 리포지토리의 가시성이 확립되지 않으면 분류기는 그것만으로 차단하지 않습니다. 대신 다른 규칙에 대해 콘텐츠를 판단합니다.

401* 다른 리포지토리 또는 조직에 대한 풀 요청 열기, `gh repo fork`로 포킹 또는 제3자 리포지토리로 푸시(해당 외부 대상의 이름을 지정하지 않은 경우)402* 다른 리포지토리 또는 조직에 대한 풀 요청 열기, `gh repo fork`로 포킹 또는 제3자 리포지토리로 푸시(해당 외부 대상을 이름 지정하지 않은 경우)

402 403

403Claude Code v2.1.203 이상도 기본적으로 다음을 차단합니다:404Claude Code v2.1.203 이상도 기본적으로 다음을 차단합니다:

404 405

405* 민감한 로컬 저장소의 콘텐츠 또는 이름, 경로 또는 유형이 민감한 것으로 표시된 파일의 콘텐츠가 커밋, 푸시, PR 또는 이슈 텍스트, gist 또는 붙여넣기 또는 패키지 게시에 들어가는 경우(소스와 대상의 이름을 지정하지 않은 경우). 세션 기록 및 대화 로그, SSH 키, 클라우드 자격 증명, 브라우저 프로필 및 셸 기록과 같은 자격 증명 및 구성 점 폴더, 그리고 사용자 데이터 내보내기는 모두 계산되며, 리포지토리가 개인이라는 것이 이를 지우지 않습니다.406* 민감한 로컬 저장소의 콘텐츠 또는 이름, 경로 또는 유형이 민감한 것으로 표시하는 파일의 콘텐츠가 커밋, 푸시, PR 또는 이슈 텍스트, gist 또는 붙여넣기 또는 패키지 게시에 들어가는 것(소스와 대상을 모두 이름 지정하지 않은 경우). 세션 기록 및 대화 로그, SSH 키, 클라우드 자격 증명, 브라우저 프로필 및 셸 기록과 같은 자격 증명 및 구성 점 폴더, 그리고 사용자 데이터 내보내기는 모두 계산되며, 리포지토리가 개인이라는 것이 이를 지우지 않습니다.

406 407

407Claude Code v2.1.205 이상도 기본적으로 다음을 차단합니다:408Claude Code v2.1.205 이상도 기본적으로 다음을 차단합니다:

408 409

409* Claude Code 세션 기록, `~/.claude/projects/` 또는 구성된 구성 디렉토리 아래의 `.jsonl` 기록 파일에 직접 또는 셸 명령을 통해 쓰기. 규칙은 또한 Claude Code가 자체 검사를 위해 각 기록 항목에 추가하는 메타데이터 줄을 다룹니다. 기록 읽기는 차단되지 않습니다.410* Claude Code 세션 기록, `~/.claude/projects/` 또는 구성된 구성 디렉토리 아래의 `.jsonl` 기록 파일에 쓰기(직접 또는 셸 명령을 통해). 규칙은 또한 Claude Code가 자체 검사를 위해 각 기록 항목에 추가하는 메타데이터 줄을 다룹니다. 기록 읽기는 차단되지 않습니다.

410* `rm -rf "$VAR"` 또는 `Remove-Item -Recurse -Force $dir`과 같은 재귀적 강제 삭제로, 대상이 분류기가 보는 대화의 어디에도 할당되지 않은 셸 변수이거나 그러한 변수에 루트된 글로브입니다. 값은 분류기가 절대 받지 않는 이전 명령 출력에서만 나왔으므로 분류기는 삭제 대상을 다른 삭제 규칙에 대해 확인할 수 없습니다. 블록은 삭제되는 정확한 경로의 이름을 지정하거나 Claude가 명령에 작성된 해결된 리터럴 경로로 삭제를 다시 실행할 때 지워집니다. 분류기가 대상을 해결할 수 있는 삭제는 영향을 받지 않습니다.411* 대상이 대화에서 분류기가 보는 어디에도 할당되지 않은 셸 변수인 `rm -rf "$VAR"` 또는 `Remove-Item -Recurse -Force $dir`과 같은 재귀적 강제 삭제. 값은 분류기가 절대 받지 않는 이전 명령 출력에서만 나왔으므로 분류기는 삭제 대상을 다른 삭제 규칙에 대해 확인할 수 없습니다. 정확한 경로를 이름 지정하거나 Claude가 해결된 리터럴 경로가 명령에 작성된 상태로 삭제를 다시 실행할 때 블록이 지워집니다. 분류기가 대상을 해결할 수 있는 삭제는 영향을 받지 않습니다.

411 412

412 변수 바로 아래의 글로브(예: `rm -rf "$VAR"/*`)는 [중요 경로](#critical-paths) 대신입니다. `Remove-Item` 대상이 베어 `*` 또는 `/*` 또는 `\*`로 끝나는 경우 분류기에 도달하지 않습니다: Claude Code [이를 직접 거부합니다](#remove-item-in-powershell).413 변수 바로 아래의 글로브(예: `rm -rf "$VAR"/*`)는 [중요 경로](#critical-paths) 대신입니다. `Remove-Item` 대상이 맨 `*` 또는 `/*` 또는 `\*`로 끝나는 것은 분류기에 도달하지 않습니다: Claude Code는 [PowerShell에서 Remove-Item](#remove-item-in-powershell)을 거부합니다.

413 414

414Claude Code v2.1.257 이상도 기본적으로 다음을 차단합니다:415Claude Code v2.1.257 이상도 기본적으로 다음을 차단합니다:

415 416

416* `169.254.169.254`와 같은 클라우드 인스턴스 메타데이터 엔드포인트에서 자격 증명 요청 또는 머신의 자체 서비스 계정 또는 노드 ID로 클라우드, 클러스터 또는 레지스트리 호출을 명시적으로 인증417* `169.254.169.254`와 같은 클라우드 인스턴스 메타데이터 엔드포인트에서 자격 증명 요청 또는 머신의 자체 서비스 계정 또는 노드 ID로 클라우드, 클러스터 또는 레지스트리 호출을 명시적으로 인증

417* 직접 요청이 아닌 다른 경로(예: 터널, 역셸 또는 공개 외부를 가리키도록 다시 작성된 리졸버 또는 프록시 구성)로 공개 호스트에 도달418* 직접 요청이 아닌 다른 경로로 공개 호스트에 도달(예: 터널, 역셸 또는 외부를 가리키도록 다시 작성된 리졸버 또는 프록시 구성)

418* 노드 인증서 또는 노드의 컨테이너 레지스트리 인증과 같이 작업이 아닌 호스트에 속하는 자격 증명 읽기419* 호스트가 아닌 작업에 속하는 자격 증명 읽기(예: 노드 인증서 또는 노드의 컨테이너 레지스트리 인증)

419* Claude가 시작하지 않은 형제 컨테이너, 포드 또는 VM 또는 그 아래의 노드에 연결 또는 스캔420* Claude가 시작하지 않은 형제 컨테이너, 포드 또는 VM 또는 그 아래의 노드에 연결 또는 스캔

420 421

421Claude Code가 이 중 하나를 허용하도록 의도된 곳에서 실행되는 경우 `autoMode.environment`의 [호스트 포함 항목](/docs/ko/auto-mode-config#define-trusted-infrastructure)에서 해당 설정을 설명하세요.422Claude Code가 이 중 하나를 허용하도록 의도된 곳에서 실행되면 `autoMode.environment`의 [호스트 포함 항목](/docs/ko/auto-mode-config#define-trusted-infrastructure)에서 해당 설정을 설명하세요.

422 423

423Claude Code v2.1.261 이상도 기본적으로 다음을 차단합니다:424Claude Code v2.1.261 이상도 기본적으로 다음을 차단합니다:

424 425

425* 메시지, PR 또는 이슈 텍스트, 문서 또는 링크가 열리거나 가져올 다른 곳에 공개 붙여넣기, 다이어그램 또는 데이터 공유 서비스에 대한 링크 게시 또는 작성(URL 자체가 공유되는 콘텐츠를 전달하는 경우)(해당 서비스의 이름을 지정하지 않은 경우)426* 메시지, PR 또는 이슈 텍스트, 문서 또는 링크가 열리거나 가져올 다른 곳에서 공개 붙여넣기, 다이어그램 또는 데이터 공유 서비스에 대한 링크 게시 또는 작성(URL 자체가 공유되는 콘텐츠를 전달할 때, 해당 서비스를 이름 지정하지 않은 경우)

426 427

427**기본적으로 허용됨**:428**기본적으로 허용됨**:

428 429

430* 잠금 파일 또는 매니페스트에 선언된 종속성 설치431* 잠금 파일 또는 매니페스트에 선언된 종속성 설치

431* `.env` 읽기 및 자격 증명을 일치하는 API로 전송432* `.env` 읽기 및 자격 증명을 일치하는 API로 전송

432* 읽기 전용 HTTP 요청433* 읽기 전용 HTTP 요청

433* 기본 분기를 포함하여 작업 중인 리포지토리의 모든 분기로 푸시. 배포 또는 게시 대상으로 표시하는 이름(예: `production` 또는 `gh-pages`)의 비기본 분기는 포함되지 않습니다: 분류기는 거기로의 푸시를 자체 조건에 따라 판단합니다. 푸시의 콘텐츠는 여전히 다른 규칙에 대해 검사되고, [`permissions.deny` 규칙](/docs/ko/permissions#manage-permissions)은 여전히 모든 모드에서 [작성된 대로](/docs/ko/permissions#bash-rule-limits) 푸시 명령을 차단할 수 있으며, 원격의 자체 분기 보호가 여전히 적용됩니다. v2.1.211 이전에는 시작한 분기, Claude가 생성한 분기 및 기본 분기로의 일상적인 푸시만 기본적으로 허용되었으며, v2.1.203 이전에는 기본 분기로의 직접 푸시가 차단되었습니다.434* 기본 분기를 포함하여 작업 중인 리포지토리의 모든 분기로 푸시. 배포 또는 게시 대상으로 이름을 표시하는 비기본 분기(예: `production` 또는 `gh-pages`)는 포함되지 않습니다: 분류기는 거기로의 푸시를 자체 조건에 따라 판단합니다. 푸시의 콘텐츠는 여전히 다른 규칙에 대해 검사되고, [`permissions.deny` 규칙](/docs/ko/permissions#manage-permissions)은 여전히 모든 모드에서 [작성된 대로](/docs/ko/permissions#bash-rule-limits) 푸시 명령을 차단할 수 있으며, 원격의 자체 분기 보호는 여전히 적용됩니다. v2.1.211 이전에는 시작한 분기, Claude가 생성한 분기 및 기본 분기로의 일상적인 푸시만 기본적으로 허용되었으며, v2.1.203 이전에는 기본 분기로의 직접 푸시가 차단되었습니다.

434* 같은 세션에서 Claude가 이전에 생성한 정확한 작업 삭제435* 같은 세션에서 Claude가 생성한 정확한 작업 삭제

435* 작업의 일부로 보안 관련 코드, 구성 및 위협 모델 읽기, 검토 또는 작성436* 작업의 일부로 보안 관련 코드, 구성 및 위협 모델 읽기, 검토 또는 작성

436* 같은 다중 에이전트 세션에서 함께 작업하는 에이전트 간의 메시지437* 같은 다중 에이전트 세션에서 함께 작업하는 에이전트 간의 메시지

437* [`environment`](/docs/ko/auto-mode-config#define-trusted-infrastructure)에 나열한 신뢰할 수 있는 도메인, 버킷 및 서비스로 데이터 전송. 이는 동일한 인프라에 대한 파괴적 또는 자격 증명 작업이 아닌 데이터 흐름만 다룹니다.438* [`environment`](/docs/ko/auto-mode-config#define-trusted-infrastructure)에 나열한 신뢰할 수 있는 도메인, 버킷 및 서비스로 데이터 전송. 이는 동일한 인프라에 대한 파괴적이거나 자격 증명 작업이 아닌 데이터 흐름만 다룹니다.

438* [Chrome의 Claude](/docs/ko/chrome) 신뢰할 수 있는 내부 도메인, localhost 또는 이름을 지정한 URL로의 탐색439* [Chrome의 Claude](/docs/ko/chrome) 신뢰할 수 있는 내부 도메인, localhost 또는 이름 지정한 URL로의 탐색

439 440

440샌드박스된 명령은 기본적으로 네트워크 액세스를 받지 않습니다. Claude는 명령이 필요한 호스트를 명령 자체에 이름을 지정하고, 분류기는 명령과 함께 이를 검토하며, 승인된 목록은 해당 명령만을 위해 이러한 호스트를 엽니다. [명령별 허용 도메인](/docs/ko/sandboxing#per-command-allowed-domains-in-auto-mode)은 목록이 열 수 있는 것과 열 수 없는 것, 그리고 명령이 나열되지 않은 호스트에 도달할 때 발생하는 일을 다룹니다.441샌드박스된 명령은 기본적으로 네트워크 액세스를 받지 않습니다. Claude는 명령이 필요한 호스트를 명령 자체에 이름 지정하고, 분류기는 명령과 함께 이를 검토하며, 승인된 목록은 해당 명령만을 위해 이러한 호스트를 엽니다. [명령별 허용 도메인](/docs/ko/sandboxing#per-command-allowed-domains-in-auto-mode)은 목록이 열 수 있는 것과 열 수 없는 것, 그리고 명령이 나열되지 않은 호스트에 도달할 때 발생하는 일을 다룹니다.

441 442

442`claude auto-mode defaults`를 실행하여 전체 규칙 목록을 JSON으로 인쇄하세요. 일상적인 작업이 차단되면 관리자는 `autoMode.environment` 설정을 통해 신뢰할 수 있는 리포지토리, 버킷 및 서비스를 추가할 수 있습니다: [자동 모드 구성](/docs/ko/auto-mode-config)을 참조하세요.443`claude auto-mode defaults`를 실행하여 전체 규칙 목록을 JSON으로 인쇄하세요. 일상적인 작업이 차단되면 관리자는 `autoMode.environment` 설정을 통해 신뢰할 수 있는 리포지토리, 버킷 및 서비스를 추가할 수 있습니다: [자동 모드 구성](/docs/ko/auto-mode-config)을 참조하세요.

443 444

444작업 중인 리포지토리의 모든 분기로 푸시하고 요청과 일치하는 풀 요청을 생성하는 것은 프롬프트 없이 실행됩니다. 푸시 또는 풀 요청이 [차단 목록](#what-the-classifier-blocks-by-default)에 해당하지 않는 한(예: 리포지토리를 떠나는 비밀 또는 민감한 데이터 또는 다른 리포지토리 또는 조직을 대상으로 하는 풀 요청). 자동 모드에 머물면서 이러한 명령 전에 인간 체크포인트를 요구하려면 `permissions.ask` 규칙을 추가하세요. 이는 명령 [작성된 대로](/docs/ko/permissions#bash-rule-limits)와 일치합니다: [일반적인 경계](/docs/ko/auto-mode-config#common-boundaries)를 참조하세요.445작업 중인 리포지토리의 모든 분기로 푸시하고 요청과 일치하는 풀 요청을 생성하는 것은 프롬프트 없이 실행됩니다. 푸시 또는 풀 요청이 [차단 목록](#what-the-classifier-blocks-by-default)에 해당하지 않는 한(예: 비밀이나 민감한 데이터가 리포지토리를 떠나거나 다른 리포지토리 또는 조직을 대상으로 하는 풀 요청). 자동 모드에 머물면서 이러한 명령 전에 인간 체크포인트를 요구하려면 `permissions.ask` 규칙을 추가하세요. 이는 명령 [작성된 대로](/docs/ko/permissions#bash-rule-limits)와 일치합니다: [일반적인 경계](/docs/ko/auto-mode-config#common-boundaries)를 참조하세요.

445 446

446<h3 id="first-read-outside-the-working-directories">447<h3 id="first-read-outside-the-working-directories">

447 작업 디렉토리 외부의 첫 번째 읽기448 작업 디렉토리 외부의 첫 번째 읽기

449 450

450[`permissions.blockReadsOutsideWorkingDirectories`](/docs/ko/settings-reference#permissions-blockreadsoutsideworkingdirectories)가 꺼져 있는 동안 파일 읽기는 자동 모드에서 프롬프트 없이 실행되며, [작업 디렉토리](/docs/ko/permissions#working-directories) 외부의 읽기를 포함합니다. Claude가 처음으로 Read, Grep 또는 Glob 도구를 이들 외부의 경로에 사용할 때 Claude Code는 해당 읽기를 허용할지 묻습니다.451[`permissions.blockReadsOutsideWorkingDirectories`](/docs/ko/settings-reference#permissions-blockreadsoutsideworkingdirectories)가 꺼져 있는 동안 파일 읽기는 자동 모드에서 프롬프트 없이 실행되며, [작업 디렉토리](/docs/ko/permissions#working-directories) 외부의 읽기를 포함합니다. Claude가 처음으로 Read, Grep 또는 Glob 도구를 이들 외부의 경로에 사용할 때 Claude Code는 해당 읽기를 허용할지 묻습니다.

451 452

452프롬프트는 비대화형 `-p` 실행이나 백그라운드 세션에 나타나지 않습니다. 읽기는 이전과 같이 실행됩니다.453프롬프트는 비대화형 `-p` 실행이나 백그라운드 세션에 나타나지 않습니다. 거기서의 읽기는 이전과 같이 실행됩니다.

453 454

454답변이 무엇이든 Claude는 계속 작업합니다:455답변이 무엇이든 Claude는 계속 작업합니다:

455 456

456* **예, 작업 디렉토리 외부의 모든 읽기를 계속 허용**: 읽기가 실행되고, 나중에 작업 디렉토리 외부의 읽기는 이전과 같이 실행되며, Claude Code는 프롬프트가 다시 나타나지 않도록 답변을 기록합니다.457* **예, 작업 디렉토리 외부의 모든 읽기를 계속 허용**: 읽기가 실행되고, 나중의 작업 디렉토리 외부의 읽기는 이전과 같이 실행되며, Claude Code는 프롬프트가 다시 나타나지 않도록 답변을 기록합니다.

457* **아니요, 지금부터 작업 디렉토리 외부의 읽기 차단**: 읽기가 거부되고 Claude Code는 [`permissions.blockReadsOutsideWorkingDirectories`](/docs/ko/settings-reference#permissions-blockreadsoutsideworkingdirectories)를 사용자 설정에서 `true`로 설정하여 파일 도구가 모든 나중 세션 및 모든 권한 모드에서 이러한 읽기를 거부하도록 합니다. 나중에 Claude가 이러한 경로를 읽도록 하려면 `/add-dir`로 디렉토리를 추가하거나 설정을 제거하세요.458* **아니요, 지금부터 작업 디렉토리 외부의 읽기 차단**: 읽기가 거부되고, Claude Code는 [`permissions.blockReadsOutsideWorkingDirectories`](/docs/ko/settings-reference#permissions-blockreadsoutsideworkingdirectories)를 사용자 설정에서 `true`로 설정하여 파일 도구가 모든 나중의 세션과 모든 권한 모드에서 이러한 읽기를 거부하도록 합니다. 나중에 Claude가 이러한 경로를 읽도록 하려면 `/add-dir`로 디렉토리를 추가하거나 설정을 제거하세요.

458* **아니요, 다음에 다시 묻기**: 읽기가 거부되고 작업 디렉토리 외부의 다음 읽기는 다시 프롬프트합니다.459* **아니요, 다음에 다시 묻기**: 읽기가 거부되고, 작업 디렉토리 외부의 다음 읽기는 다시 프롬프트합니다.

459* **예, 하지만 다음에 다시 묻기**: 읽기가 실행되고, 아무것도 저장되지 않으며, 작업 디렉토리 외부의 다음 읽기는 다시 프롬프트합니다.460* **예, 하지만 다음에 다시 묻기**: 읽기가 실행되고, 아무것도 저장되지 않으며, 작업 디렉토리 외부의 다음 읽기는 다시 프롬프트합니다.

460 461

461<h3 id="boundaries-you-state-in-conversation">462<h3 id="boundaries-you-state-in-conversation">

462 대화에서 명시한 경계463 대화에서 명시한 경계

463</h3>464</h3>

464 465

465분류기는 대화에서 명시한 경계를 차단 신호로 취급합니다. "푸시하지 마" 또는 "배포하기 전에 검토할 때까지 기다려"라고 Claude에게 말하면 분류기는 기본 규칙이 허용하더라도 일치하는 작업을 차단합니다. 경계는 나중 메시지에서 이를 해제할 때까지 유효합니다. Claude의 자체 판단이 조건이 충족되었다는 것은 이를 해제하지 않습니다.466분류기는 대화에서 명시한 경계를 차단 신호로 취급합니다. "푸시하지 마" 또는 "배포하기 전에 검토할 때까지 기다려"라고 Claude에 말하면 분류기는 기본 규칙이 허용하더라도 일치하는 작업을 차단합니다. 경계는 나중의 메시지에서 이를 해제할 때까지 유효합니다. Claude의 자체 판단이 조건이 충족되었다는 것이 이를 해제하지 않습니다.

466 467

467경계는 규칙으로 저장되지 않습니다. 분류기는 각 검사에서 기록에서 이를 다시 읽으므로 [컨텍스트 압축](/docs/ko/costs#reduce-token-usage)이 경계를 명시한 메시지를 제거하면 경계가 손실될 수 있습니다. 하드 보장을 위해 [거부 규칙](/docs/ko/permissions#permission-rule-syntax)을 대신 추가하세요.468경계는 규칙으로 저장되지 않습니다. 분류기는 각 검사에서 기록에서 이를 다시 읽으므로 [컨텍스트 압축](/docs/ko/costs#reduce-token-usage)이 경계를 명시한 메시지를 제거하면 경계가 손실될 수 있습니다. 하드 보장을 위해 [거부 규칙](/docs/ko/permissions#permission-rule-syntax)을 대신 추가하세요.

468 469

470 대화에서 명시한 승인471 대화에서 명시한 승인

471</h3>472</h3>

472 473

473차단된 작업이 허용된다고 Claude에게 말하면 분류기는 이를 승인으로 읽고 블록을 지울 수 있습니다. 이를 표현한 방식이 작업이 실행되는지 여부와 승인이 얼마나 멀리 도달하는지를 결정합니다:474차단된 작업이 허용된다고 Claude에 말하면 분류기는 이를 승인으로 읽고 블록을 지울 수 있습니다. 이를 표현한 방식이 작업이 실행되는지, 그리고 승인이 얼마나 멀리 도달하는지를 결정합니다:

474 475

475* **작업과 그 세부 정보의 이름 지정**: 메시지는 작업과 강제 푸시의 분기와 같이 이를 위험하게 만드는 특정 사항의 이름을 지정해야 합니다. 동사만 이름을 지정하면 아무것도 지워지지 않으므로 "강제 푸시할 수 있습니다"는 블록을 제자리에 둡니다.476* **작업과 그 세부 정보를 이름 지정**: 메시지는 작업과 이를 위험하게 만드는 구체적인 것(예: 강제 푸시의 분기)을 이름 지정해야 합니다. 동사만 이름 지정하는 것은 아무것도 지우지 않으므로 "강제 푸시할 수 있습니다"는 블록을 제자리에 두고 있습니다.

476* **한 작업을 다루도록 예상**: 승인은 이름을 지정한 파괴적 작업을 다루므로 나중 작업은 승인을 상시로 부여하지 않는 한 다시 차단됩니다. 일상적인 패턴을 한 번에 하나씩 승인하는 것을 중지하려면 [`autoMode.allow`](/docs/ko/auto-mode-config#override-the-block-and-allow-rules)에 추가하세요.477* **한 작업을 다루도록 예상**: 승인은 이름 지정한 파괴적 작업을 다루므로 나중의 작업은 다시 차단됩니다. 일상적인 패턴을 한 번에 하나씩 승인하는 것을 중지하려면 [`autoMode.allow`](/docs/ko/auto-mode-config#override-the-block-and-allow-rules)에 추가하세요.

477* **일부 블록은 제자리에 유지됨**: [분류기의 우선 순위 순서](/docs/ko/auto-mode-config#override-the-block-and-allow-rules)는 승인이 도달할 수 있는 블록을 설정합니다. 이를 지우지 않을 단계를 실행하려면 [자동 모드를 떠나](#switch-permission-modes) 권한 프롬프트에 답하세요.478* **일부 블록은 제자리에 남음**: [분류기의 우선 순위 순서](/docs/ko/auto-mode-config#override-the-block-and-allow-rules)는 승인이 도달할 수 있는 블록을 설정합니다. 이를 지우지 않을 단계를 실행하려면 [자동 모드를 떠나](#switch-permission-modes) 권한 프롬프트에 답하세요.

478 479

479<h3 id="when-auto-mode-falls-back">480<h3 id="when-auto-mode-falls-back">

480 자동 모드가 폴백할 때481 자동 모드가 폴백할 때

483자동 모드가 세션의 작업을 승인할 수 없을 때 발생하는 일은 경우에 따라 다릅니다:484자동 모드가 세션의 작업을 승인할 수 없을 때 발생하는 일은 경우에 따라 다릅니다:

484 485

485* **차단된 작업**: Claude Code는 알림을 표시하고 `/permissions` 아래의 **최근 거부됨** 탭에 작업을 나열하며, 여기서 `r`을 눌러 수동 승인으로 다시 시도할 수 있습니다.486* **차단된 작업**: Claude Code는 알림을 표시하고 `/permissions` 아래의 **최근 거부됨** 탭에 작업을 나열하며, 여기서 `r`을 눌러 수동 승인으로 다시 시도할 수 있습니다.

486* **반복된 블록**: 분류기가 작업을 연속 3회 또는 총 20회 차단하면 자동 모드가 일시 중지되고 Claude Code는 프롬프트를 다시 시작합니다. 프롬프트된 작업을 승인하면 자동 모드가 재개됩니다. 블록이 계산되는 방식은 [반복 블록 임계값](#repeated-block-thresholds)을 참조하세요.487* **반복된 블록**: 분류기가 작업을 연속 3회 또는 총 20회 차단하면 자동 모드가 일시 중지되고 Claude Code는 프롬프트를 다시 시작합니다. 프롬프트된 작업을 승인하면 자동 모드가 재개됩니다. [반복된 블록 임계값](#repeated-block-thresholds)을 참조하여 블록이 어떻게 계산되는지 확인하세요.

487* **분류기의 판정 없음**: 자동 모드와 별개의 안전 검사가 분류기의 자체 요청을 거부하거나 분류기의 응답이 구문 분석되지 않을 때 Claude Code는 알림이나 **최근 거부됨** 항목 없이 작업을 거부합니다. 각 경우가 표시하는 메시지 및 수행할 작업은 [자동 모드가 작업의 안전성을 결정할 수 없음](/docs/ko/errors#auto-mode-cannot-determine-the-safety-of-an-action)을 참조하세요.488* **분류기의 판정 없음**: 자동 모드와 별개인 안전 검사가 분류기의 자체 요청을 거부하거나 분류기의 응답이 구문 분석되지 않을 때 Claude Code는 알림이나 **최근 거부됨** 항목 없이 작업을 거부합니다. [자동 모드가 작업의 안전성을 결정할 수 없음](/docs/ko/errors#auto-mode-cannot-determine-the-safety-of-an-action)을 참조하여 각 경우가 표시하는 메시지와 수행할 작업을 확인하세요.

488* **서버의 판정 없음**: [서버 측 분류기 검토](#server-side-classifier-review)에서 Claude Code는 서버가 판정을 제공하지 않는 작업을 거부하고 연속 10개 응답 후 판정이 없으면 턴을 중지합니다. [서버가 안전 판정을 반환하지 않음](/docs/ko/errors#the-server-returned-no-safety-verdict)을 참조하세요.489* **서버의 판정 없음**: [서버 측 분류기 검토](#server-side-classifier-review)에서 Claude Code는 서버가 판정을 제공하지 않는 작업을 거부하고, 연속 10개 응답 후 판정이 없으면 턴을 중지합니다. [서버가 안전 판정을 반환하지 않음](/docs/ko/errors#the-server-returned-no-safety-verdict)을 참조하세요.

489* **검사 중 모드 전환**: 분류기 검사가 보류 중일 때 권한 모드를 전환하면 Claude Code는 새 모드가 요청하지 않을 판정을 삭제합니다. 대신 승인을 위해 프롬프트되거나 [`dontAsk` 모드](#allow-only-pre-approved-tools-with-dontask-mode)에서 작업이 자동 거부됩니다.490* **검사 중 모드 전환**: 분류기 검사가 보류 중일 때 권한 모드를 전환하면 Claude Code는 새 모드가 요청하지 않을 판정을 삭제합니다. 대신 승인을 위해 프롬프트되거나 [`dontAsk` 모드](#allow-only-pre-approved-tools-with-dontask-mode)에서 작업이 자동 거부됩니다.

490 491

491<h4 id="repeated-block-thresholds">492<h4 id="repeated-block-thresholds">

492 반복 블록 임계값493 반복된 블록 임계값

493</h4>494</h4>

494 495

4953개 연속 블록 및 20개 총 블록의 임계값은 구성할 수 없습니다. 총 카운터는 세션에 대해 유지되고 자체 제한이 폴백을 트리거할 때만 재설정됩니다. Claude Code는 자동 모드와 별개의 안전 검사가 분류기의 자체 요청을 거부할 때 거부를 어느 임계값에도 계산하지 않습니다.496연속 3개 블록 및 총 20개 블록의 임계값은 구성할 수 없습니다. 총 카운터는 세션에 대해 유지되고 자체 한계가 폴백을 트리거할 때만 재설정됩니다. Claude Code는 자동 모드와 별개인 안전 검사가 분류기의 자체 요청을 거부할 때 거부를 어느 임계값에도 계산하지 않습니다.

496 497

497[비대화형](/docs/ko/headless) `-p` 실행에 [`--permission-prompt-tool`](/docs/ko/cli-reference#cli-flags)이 없으면 폴백할 프롬프트가 없습니다. 반복된 블록이 임계값에 도달하면 작업이 실행되지 않고 Claude는 계속 작업합니다. Claude Code는 실행을 중지하지 않습니다.498[비대화형](/docs/ko/headless) `-p` 실행이 [`--permission-prompt-tool`](/docs/ko/cli-reference#cli-flags)이 없으면 폴백할 프롬프트가 없습니다. 반복된 블록이 임계값에 도달하면 작업이 실행되지 않고 Claude는 계속 작업합니다. Claude Code는 실행을 중지하지 않습니다.

498 499

499반복된 블록은 일반적으로 분류기가 인프라에 대한 컨텍스트를 놓치고 있음을 의미합니다. `/feedback`을 사용하여 거짓 양성을 보고하거나 관리자가 [신뢰할 수 있는 인프라를 구성](/docs/ko/auto-mode-config)하도록 하세요.500반복된 블록은 일반적으로 분류기가 인프라에 대한 컨텍스트를 놓치고 있음을 의미합니다. `/feedback`을 사용하여 거짓 양성을 보고하거나 관리자가 [신뢰할 수 있는 인프라를 구성](/docs/ko/auto-mode-config)하도록 하세요.

500 501

501<h3 id="how-auto-mode-evaluates-actions">502<h3 id="how-auto-mode-evaluates-actions">

502 자동 모드가 작업을 평가하는 방식503 자동 모드가 작업을 평가하는 방법

503</h3>504</h3>

504 505

505다음 섹션은 Claude Code가 작업을 평가하는 순서, 분류기가 하위 에이전트 작업을 검토하는 방식, 그리고 분류기 호출이 비용 및 지연 시간에 추가하는 것을 다룹니다.506다음 섹션은 Claude Code가 작업을 평가하는 순서, 분류기가 하위 에이전트 작업을 검토하는 방법, 그리고 분류기 호출이 비용 및 지연 시간에 추가하는 것을 다룹니다.

506 507

507<span id="how-the-classifier-evaluates-actions" />508<span id="how-the-classifier-evaluates-actions" />

508 509

509<AccordionGroup>510<AccordionGroup>

510 <Accordion title="분류기가 작업을 평가하는 방식">511 <Accordion title="분류기가 작업을 평가하는 방법">

511 각 작업은 고정된 결정 순서를 거칩니다. 첫 번째 일치하는 단계가 승리합니다:512 각 작업은 고정된 결정 순서를 거칩니다. 첫 번째 일치하는 단계가 승리합니다:

512 513

513 1. [허용, 요청 또는 거부 규칙](/docs/ko/permissions#manage-permissions)과 일치하는 작업은 다음 예외를 제외하고 즉시 해결됩니다:514 1. [허용, 요청 또는 거부 규칙](/docs/ko/permissions#manage-permissions)과 일치하는 작업은 다음 예외를 제외하고 즉시 해결됩니다:

514 * [보호된 경로](#protected-paths)에 대한 쓰기는 허용 규칙이 일치할 때도 분류기로 라우팅됩니다.515 * [보호된 경로](#protected-paths)에 쓰기는 허용 규칙이 일치할 때도 분류기로 라우팅됩니다.

515 * 허용 규칙은 `rm` 및 `rmdir` 제거를 [중요 경로](#critical-paths)로 대상으로 하는 것을 승인하지 않습니다.516 * 허용 규칙은 `rm` 및 `rmdir` 제거를 [중요 경로](#critical-paths)로 대상으로 하는 것을 승인하지 않습니다.

516 * [`requiresUserInteraction`](/docs/ko/mcp#require-approval-for-a-specific-tool)으로 표시된 MCP 도구는 허용 규칙이 일치할 때도 직접 프롬프트하고, 조직이 [요청으로 설정](/docs/ko/mcp#organization-controls-on-connector-tools)한 커넥터 도구도 해당 설정이 Claude Code에 도달하는 세션에서 프롬프트합니다.517 * [`requiresUserInteraction`](/docs/ko/mcp#require-approval-for-a-specific-tool)으로 표시된 MCP 도구는 허용 규칙이 일치할 때도 직접 프롬프트하고, 조직이 [이를 `ask`로 설정](/docs/ko/mcp#organization-controls-on-connector-tools)한 커넥터 도구도 해당 설정이 Claude Code에 도달하는 세션에서 프롬프트합니다.

517 * [명령별 허용 도메인](/docs/ko/sandboxing#per-command-allowed-domains-in-auto-mode)을 전달하는 셸 명령도 규칙이 명령을 승인하지만 호스트를 승인하지 않기 때문에 분류기로 라우팅됩니다.518 * [명령별 허용 도메인](/docs/ko/sandboxing#per-command-allowed-domains-in-auto-mode)을 전달하는 셸 명령도 규칙이 명령을 승인하지만 호스트를 승인하지 않기 때문에 분류기로 라우팅됩니다.

518 * `Bash(git push *)`와 같은 명령의 콘텐츠에 일치하는 규칙을 요청하면 권한 프롬프트로 폴백합니다.519 * `Bash(git push *)`와 같은 명령의 콘텐츠에서 일치하는 규칙을 요청하면 권한 프롬프트로 폴백합니다.

519 * [심볼릭 링크 검사](/docs/ko/permissions#symlinks)가 해결하는 쓰기가 보호된 경로로 Claude가 요청한 경로 자체가 보호되지 않을 때 프롬프트합니다.520 * [symlink 검사](/docs/ko/permissions#symlinks)가 해결하는 쓰기가 보호된 경로로 Claude가 요청한 경로 자체가 보호되지 않으면 프롬프트합니다.

520 2. 읽기 전용 작업 및 작업 디렉토리의 파일 편집은 자동 승인되며, [보호된 경로](#protected-paths) 및 [작업 디렉토리 외부의 첫 번째 읽기](#first-read-outside-the-working-directories)에 대한 쓰기는 제외되며, 이는 프롬프트합니다.521 2. 읽기 전용 작업 및 작업 디렉토리의 파일 편집은 자동 승인되며, [보호된 경로](#protected-paths) 및 [작업 디렉토리 외부의 첫 번째 읽기](#first-read-outside-the-working-directories)에 쓰기는 제외되며, 이는 프롬프트합니다.

521 * [서버 측 분류기 검토](#server-side-classifier-review)가 있는 세션에서 읽기 전용 및 [샌드박스된](/docs/ko/sandboxing#sandbox-modes) 셸 명령은 해당 검토를 기다리고 이를 플래그하면 차단됩니다.522 * [서버 측 분류기 검토](#server-side-classifier-review)가 있는 세션에서 읽기 전용 및 [샌드박스된](/docs/ko/sandboxing#sandbox-modes) 셸 명령은 해당 검토를 기다리고 이를 플래그하면 차단됩니다.

522 * [심볼릭 링크 검사](/docs/ko/permissions#symlinks)가 해결하는 작업 디렉토리 내의 쓰기가 외부 위치로 프롬프트합니다.523 * 작업 디렉토리 내의 쓰기가 [symlink 검사](/docs/ko/permissions#symlinks)가 외부 위치로 해결하면 프롬프트합니다.

523 3. 다른 모든 것은 [중요 경로 제거](#critical-paths)의 기본 처리를 제외하고 분류기로 이동합니다. 1단계에서 직접 프롬프트하는 커넥터 도구 및 `requiresUserInteraction` MCP 도구는 분류기에 도달하지 않으므로 조직 필수 승인이나 동의 단계도 자동 승인되지 않습니다.524 3. 다른 모든 것은 [중요 경로 제거](#critical-paths)의 기본 처리를 제외하고 분류기로 이동합니다. 1단계에서 직접 프롬프트하는 커넥터 도구 및 `requiresUserInteraction` MCP 도구는 분류기에 도달하지 않으므로 조직 필수 승인이나 동의 단계도 자동 승인되지 않습니다.

524 4. 분류기가 차단하면 Claude는 이유를 받습니다. 대부분의 세션에서 이유는 `[Data Exfiltration]`과 같이 분류기가 일치한 규칙의 이름을 지정하기보다는 서면 설명을 제공합니다. [거부 검토](/docs/ko/auto-mode-config#review-denials)를 참조하세요.525 4. 분류기가 차단하면 Claude는 이유를 받습니다. 대부분의 세션에서 이유는 분류기가 일치한 규칙(예: `[Data Exfiltration]`)을 이름 지정하기보다는 서면 설명을 제공합니다. [거부 검토](/docs/ko/auto-mode-config#review-denials)를 참조하세요.

525 526

526 자동 모드에 들어갈 때 임의의 코드 실행을 부여하는 광범위한 허용 규칙이 삭제됩니다:527 설치한 [mod](/docs/ko/plugins/mods/overview)가 `tool.check`를 후킹할 수 있으며 3단계 전에 작업을 승인하고, 분류기는 mod가 승인한 작업을 검사하지 않습니다. [후크로 권한 확장](/docs/ko/permissions#extend-permissions-with-hooks)을 참조하세요.

528

529 자동 모드에 들어가면 임의의 코드 실행을 부여하는 광범위한 허용 규칙이 삭제됩니다:

527 530

528 * 무조건 `Bash(*)` 또는 `PowerShell(*)`531 * 무조건 `Bash(*)` 또는 `PowerShell(*)`

529 * `Bash(python*)`과 같은 와일드카드 인터프리터532 * `Bash(python*)`과 같은 와일드카드 인터프리터

530 * 패키지 관리자 실행 명령533 * 패키지 관리자 실행 명령

531 * `Agent` 허용 규칙534 * `Agent` 허용 규칙

532 * [`Monitor`](/docs/ko/tools-reference#monitor-tool) 허용 규칙(Claude Code가 Monitor 명령을 셸을 통해 실행하기 때문)535 * [`Monitor`](/docs/ko/tools-reference#monitor-tool) 허용 규칙(Claude Code는 Monitor 명령을 셸을 통해 실행하기 때문)

533 536

534 `Bash(npm test)`와 같은 좁은 규칙은 유효합니다. Claude Code는 자동 모드를 떠날 때 삭제된 규칙을 복원합니다. v2.1.236 이전에는 Claude Code가 자동 모드에서 `Monitor` 허용 규칙을 유효하게 두었으므로 전체 도구와 일치하는 규칙이 분류기 검토 없이 Monitor 명령을 승인했습니다.537 `Bash(npm test)`와 같은 좁은 규칙은 유효합니다. Claude Code는 자동 모드를 떠날 때 삭제된 규칙을 복원합니다. v2.1.236 이전에는 Claude Code가 자동 모드에서 `Monitor` 허용 규칙을 유효하게 두었으므로 전체 도구와 일치하는 규칙이 분류기 검토 없이 Monitor 명령을 승인했습니다.

535 538

537 540

538 Claude Code 자체가 보낸 분류기 요청에서 분류기는 사용자 메시지, 파일 읽기 및 검색과 같은 읽기 전용 조회 이외의 도구 호출, 그리고 CLAUDE.md 콘텐츠를 봅니다. 도구 결과는 이러한 요청에서 제거되므로 파일이나 웹 페이지의 악의적인 콘텐츠는 분류기를 직접 조작할 수 없습니다.541 Claude Code 자체가 보낸 분류기 요청에서 분류기는 사용자 메시지, 파일 읽기 및 검색과 같은 읽기 전용 조회 이외의 도구 호출, 그리고 CLAUDE.md 콘텐츠를 봅니다. 도구 결과는 이러한 요청에서 제거되므로 파일이나 웹 페이지의 악의적인 콘텐츠는 분류기를 직접 조작할 수 없습니다.

539 542

540 호출의 결과에 [PostToolUse 훅의 `classifierContext` 필드](/docs/ko/hooks#annotate-a-result-for-the-auto-mode-classifier)로 주석을 달 수 있으며, 분류기는 이를 애플리케이션 제공 컨텍스트로 읽습니다. 필드에는 Claude Code v2.1.236 이상이 필요합니다.543 [PostToolUse 후크의 `classifierContext` 필드](/docs/ko/hooks#annotate-a-result-for-the-auto-mode-classifier)로 호출의 결과에 주석을 달 수 있으며, 분류기는 이를 애플리케이션 제공 컨텍스트로 읽습니다. 필드에는 Claude Code v2.1.236 이상이 필요합니다.

541 544

542 별도의 서버 측 프로브는 들어오는 도구 결과를 스캔하고 Claude가 읽기 전에 의심스러운 콘텐츠에 플래그를 지정합니다. 이러한 계층이 함께 작동하는 방식에 대한 자세한 내용은 [자동 모드 공지](https://claude.com/blog/auto-mode) 및 [엔지니어링 심층 분석](https://www.anthropic.com/engineering/claude-code-auto-mode)을 참조하세요.545 별도의 서버 측 프로브는 들어오는 도구 결과를 스캔하고 Claude가 읽기 전에 의심스러운 콘텐츠에 플래그를 지정합니다. 이러한 계층이 함께 작동하는 방식에 대한 자세한 내용은 [자동 모드 공지](https://claude.com/blog/auto-mode) 및 [엔지니어링 심층 분석](https://www.anthropic.com/engineering/claude-code-auto-mode)을 참조하세요.

543 </Accordion>546 </Accordion>

544 547

545 <Accordion title="자동 모드가 하위 에이전트를 처리하는 방식">548 <Accordion title="자동 모드가 하위 에이전트를 처리하는 방법">

546 분류기는 [하위 에이전트](/docs/ko/sub-agents) 작업을 세 지점에서 검사합니다:549 분류기는 [하위 에이전트](/docs/ko/sub-agents) 작업을 세 지점에서 검사합니다:

547 550

548 1. 하위 에이전트가 시작하기 전에 위임된 작업 설명이 평가되므로 위험해 보이는 작업은 생성 시간에 차단됩니다.551 1. 하위 에이전트가 시작하기 전에 위임된 작업 설명이 평가되므로 위험해 보이는 작업은 생성 시간에 차단됩니다.

549 2. 하위 에이전트가 실행되는 동안 각 작업은 부모 세션과 동일한 [결정 순서](#how-the-classifier-evaluates-actions)를 거치며 동일한 블록 및 허용 규칙을 사용합니다. 하위 에이전트의 프론트매터의 모든 `permissionMode`는 무시됩니다.552 2. 하위 에이전트가 실행되는 동안 각 작업은 부모 세션과 동일한 [결정 순서](#how-the-classifier-evaluates-actions)를 거치며 동일한 블록 및 허용 규칙을 사용합니다. 하위 에이전트의 frontmatter의 모든 `permissionMode`는 무시됩니다.

550 3. 하위 에이전트가 완료되면 분류기는 부모가 보고서를 읽기 전에 작업과 최종 보고서를 검토합니다. 분류기가 하위 에이전트의 작업이나 보고서에 플래그를 지정하거나 별도의 API 안전 검사가 검토를 거부하면 보고서는 여전히 전달되며 보안 경고가 앞에 붙습니다. 분류기를 사용할 수 없으면 보고서는 하위 에이전트의 작업을 확인한 후 작업하도록 하는 메모와 함께 도착합니다.553 3. 하위 에이전트가 완료되면 분류기는 부모가 보고서를 읽기 전에 작업과 최종 보고서를 검토합니다. 분류기가 하위 에이전트의 작업이나 보고서에 플래그를 지정하거나 별도의 API 안전 검사가 검토를 거부하면 보고서는 여전히 전달되며 보안 경고가 앞에 붙습니다. 분류기를 사용할 수 없으면 보고서는 하위 에이전트의 작업을 확인한 후 작업하도록 주의하는 메모와 함께 도착합니다.

551 </Accordion>554 </Accordion>

552 555

553 <Accordion title="비용 및 지연 시간">556 <Accordion title="비용 및 지연 시간">

554 분류기는 기본적으로 `/model` 선택이 아닌 Claude Sonnet 5에서 실행됩니다. Anthropic이 서버 측에서 구성하는 분류기 모델이 해당 기본값보다 우선합니다. 세션의 모델이 Claude Sonnet 4.6이거나 [`availableModels`](/docs/ko/model-config#restrict-model-selection)이 Sonnet 5를 제외할 때 분류기는 세션의 모델 대신 실행되거나 세션이 [Fable 모델](/docs/ko/model-config#work-with-fable)에서 실행될 때 Opus 모델에서 실행됩니다. Anthropic API 이외의 제공자에서 해당 Opus 폴백은 제공자의 기본 Opus 모델입니다.557 분류기는 `/model` 선택이 아닌 기본적으로 Claude Sonnet 5에서 실행됩니다. Anthropic이 서버 측에서 구성하는 분류기 모델이 해당 기본값보다 우선합니다. 세션의 모델이 Claude Sonnet 4.6이거나 [`availableModels`](/docs/ko/model-config#restrict-model-selection)이 Sonnet 5를 제외할 때 분류기는 세션의 모델 대신 실행되거나 세션이 [Fable 모델](/docs/ko/model-config#work-with-fable)에서 실행될 때 Opus 모델에서 실행됩니다. Anthropic API 이외의 제공자에서 해당 Opus 폴백은 제공자의 기본 Opus 모델입니다.

555 558

556 세션의 첫 번째 자동 모드 요청은 Sonnet 5 기본값을 검증합니다: 요청이 성공하면 Sonnet 5는 세션의 분류기 모델로 유지되고, 모델을 사용할 수 없기 때문에 실패하면 세션은 폴백을 대신 사용합니다. 해당 검증이 정착한 후 분류기의 모델은 세션에 대해 변경되지 않습니다.559 세션의 첫 번째 자동 모드 요청은 Sonnet 5 기본값을 검증합니다: 요청이 성공하면 Sonnet 5는 세션의 분류기 모델로 유지되고, 모델을 사용할 수 없기 때문에 실패하면 세션은 폴백을 대신 사용합니다.

557 560

558 Enterprise 플랜 및 Claude API를 사용하는 계정, [AWS의 Claude Platform](/docs/ko/claude-platform-on-aws), Amazon Bedrock, Google Cloud의 Agent Platform 또는 Microsoft Foundry에서 분류기 호출은 토큰 사용량에 계산됩니다. 각 검사는 기록의 일부와 보류 중인 작업을 보내 실행 전에 왕복을 추가합니다. 읽기 및 보호된 경로 외부의 작업 디렉토리 편집은 분류기를 건너뛰므로 오버헤드는 주로 셸 명령 및 네트워크 작업에서 나옵니다. 서버가 세션의 모델 요청의 일부로 작업을 검토하는 경우 계산할 별도의 분류기 호출이 없습니다. [서버 측 분류기 검토](#server-side-classifier-review)를 참조하세요.561 Enterprise 플랜 및 Claude API를 사용하는 계정, [AWS의 Claude Platform](/docs/ko/claude-platform-on-aws), Amazon Bedrock, Google Cloud의 Agent Platform 또는 Microsoft Foundry에서 분류기 호출은 토큰 사용량에 계산됩니다. 각 검사는 기록의 일부와 보류 중인 작업을 보내며 실행 전에 왕복을 추가합니다. 읽기 및 보호된 경로 외부의 작업 디렉토리 편집은 분류기를 건너뛰므로 오버헤드는 주로 셸 명령 및 네트워크 작업에서 나옵니다. 서버가 세션의 모델 요청의 일부로 작업을 검토하는 경우 계산할 별도의 분류기 호출이 없습니다. [서버 측 분류기 검토](#server-side-classifier-review)를 참조하세요.

559 562

560 샌드박스된 네트워크 액세스는 명령별 분류기 요청을 추가하지 않습니다. 분류기는 [명령이 이름을 지정하는 호스트](/docs/ko/sandboxing#per-command-allowed-domains-in-auto-mode)를 명령과 함께 한 번의 검토로 판단하고 Claude Code는 분류기를 다시 호출하지 않고 승인된 목록에 대해 각 연결을 검사합니다.563 샌드박스된 네트워크 액세스는 명령별 분류기 요청을 추가하지 않습니다. 분류기는 [명령이 이름 지정하는 호스트](/docs/ko/sandboxing#per-command-allowed-domains-in-auto-mode)를 명령과 함께 판단하고, Claude Code는 분류기를 다시 호출하지 않고 승인된 목록에 대해 각 연결을 검사합니다.

561 </Accordion>564 </Accordion>

562</AccordionGroup>565</AccordionGroup>

563 566

666* `.yarn`669* `.yarn`

667* `.mvn`670* `.mvn`

668* `.claude`, `.claude/worktrees` 제외 (Claude가 자신의 git worktrees를 저장하는 위치)671* `.claude`, `.claude/worktrees` 제외 (Claude가 자신의 git worktrees를 저장하는 위치)

672* [`--plugin-dir`](/docs/ko/plugins/mods/create#change-a-mod-with-claude)로 로드한 디렉토리. Claude Code는 파일이 변경될 때 이 디렉토리에서 mod의 코드를 다시 로드하고 실행하기 때문입니다.

669 673

670보호된 파일:674보호된 파일:

671 675

permissions.md +14 −3

Details

598 598

599[Claude Code 훅](/docs/ko/hooks-guide)을 사용하면 런타임에 권한을 평가하는 사용자 정의 셸 명령을 등록할 수 있습니다. Claude Code가 도구 호출을 수행할 때, PreToolUse 훅은 [`EndConversation`](/docs/ko/tools-reference#endconversation-tool-behavior)을 제외한 모든 도구에 대해 권한 프롬프트 전에 실행됩니다. 훅 출력은 도구 호출을 거부하거나, 프롬프트를 강제하거나, 프롬프트를 건너뛰어 호출을 진행하도록 할 수 있습니다.599[Claude Code 훅](/docs/ko/hooks-guide)을 사용하면 런타임에 권한을 평가하는 사용자 정의 셸 명령을 등록할 수 있습니다. Claude Code가 도구 호출을 수행할 때, PreToolUse 훅은 [`EndConversation`](/docs/ko/tools-reference#endconversation-tool-behavior)을 제외한 모든 도구에 대해 권한 프롬프트 전에 실행됩니다. 훅 출력은 도구 호출을 거부하거나, 프롬프트를 강제하거나, 프롬프트를 건너뛰어 호출을 진행하도록 할 수 있습니다.

600 600

601훅 결정은 권한 규칙을 우회하지 않습니다. Claude Code는 PreToolUse 훅이 반환하는 값에 관계없이 deny 및 ask 규칙을 평가합니다. 일치하는 deny 규칙은 호출을 차단하고, 일치하는 ask 규칙은 훅이 `"allow"` 또는 `"ask"`를 반환했을 때도 여전히 프롬프트합니다. 이는 [권한 관리](#manage-permissions)에서 설명한 deny 우선 우선순위를 유지하며, 관리형 설정에서 설정한 deny 규칙을 포함합니다.601PreToolUse 훅 결정은 권한 규칙을 우회하지 않습니다. Claude Code는 PreToolUse 훅이 반환하는 값에 관계없이 deny 및 ask 규칙을 평가합니다. 일치하는 deny 규칙은 호출을 차단하고, 일치하는 ask 규칙은 훅이 `"allow"` 또는 `"ask"`를 반환했을 때도 여전히 프롬프트합니다. 이는 [권한 관리](#manage-permissions)에서 설명한 deny 우선 우선순위를 유지하며, 관리형 설정에서 설정한 deny 규칙을 포함합니다.

602

603이 우선순위는 설정 파일의 훅과 플러그인의 `hooks/hooks.json`에 있는 훅을 포함합니다. 설치한 [mod](/docs/ko/plugins/mods/overview)가 `tool.check`를 훅하면 규칙과 `PreToolUse` 훅이 결정한 후에 응답하며, 그 응답은 이들을 대체할 수 있습니다:

604

605* **Ask 규칙**: mod는 ask 규칙이 프롬프트할 호출을 승인할 수 있습니다

606* **`PreToolUse` 훅의 차단**: mod는 훅이 관리형 설정에 있지 않은 경우 호출을 승인할 수 있습니다

607* **자동 모드 분류기**: [자동 모드](/docs/ko/permission-modes#eliminate-prompts-with-auto-mode)에서 mod가 승인한 호출은 분류기 확인 없이 실행됩니다

608* **Deny 규칙**: 관리형 설정이 있는 머신에서 또는 Team 또는 Enterprise 플랜으로 로그인한 경우, deny 규칙은 기본적으로 mod보다 우선하며, 조직에서 이를 변경할 수 있습니다. 다른 곳에서는 mod가 deny 규칙이 거부하는 호출을 승인할 수 있습니다.

609

610[mod를 신뢰할지 결정](/docs/ko/plugins/mods/overview#decide-whether-to-trust-a-mod)을 참조하거나, 관리형 설정을 배포하는 경우 [조직을 위한 mod 관리](/docs/ko/plugins/mods/admin#know-what-happens-by-default)를 참조하세요.

602 611

603[`requiresUserInteraction`](/docs/ko/mcp#require-approval-for-a-specific-tool)으로 표시된 MCP 도구와 조직에서 [세션에서 해당 설정이 Claude Code에 도달하는 경우 `ask`로 설정](/docs/ko/mcp#organization-controls-on-connector-tools)한 커넥터 도구도 훅이 `"allow"`를 반환할 때 여전히 프롬프트합니다.612[`requiresUserInteraction`](/docs/ko/mcp#require-approval-for-a-specific-tool)으로 표시된 MCP 도구와 조직에서 [세션에서 해당 설정이 Claude Code에 도달하는 경우 `ask`로 설정](/docs/ko/mcp#organization-controls-on-connector-tools)한 커넥터 도구도 훅이 `"allow"`를 반환할 때 여전히 프롬프트합니다.

604 613

716 725

717설정 범위 전체에서도 동일하게 적용됩니다: 사용자 설정에서 권한을 허용하고 프로젝트 설정에서 거부하면, deny 규칙이 이를 차단합니다. 그 반대도 마찬가지입니다: 사용자 수준의 deny는 프로젝트 수준의 allow를 차단합니다. 왜냐하면 모든 범위의 deny 규칙이 allow 규칙보다 먼저 평가되기 때문입니다.726설정 범위 전체에서도 동일하게 적용됩니다: 사용자 설정에서 권한을 허용하고 프로젝트 설정에서 거부하면, deny 규칙이 이를 차단합니다. 그 반대도 마찬가지입니다: 사용자 수준의 deny는 프로젝트 수준의 allow를 차단합니다. 왜냐하면 모든 범위의 deny 규칙이 allow 규칙보다 먼저 평가되기 때문입니다.

718 727

728이 우선순위는 설정 파일과 명령줄 인수 간의 관계입니다. deny 규칙이 설치한 [mod](/docs/ko/plugins/mods/overview)에 대해 유지되는지 여부는 [훅으로 권한 확장](#extend-permissions-with-hooks)을 참조하십시오.

729

719Embedding hosts는 SDK `managedSettings` 옵션을 통해 추가 관리형 정책을 제공할 수 있습니다. 여기에는 관리자가 `allowManaged*Only` 잠금을 설정하지 않은 경우 권한 허용 규칙이 포함됩니다. [Claude Desktop 세션에 정책 전달](/docs/ko/claude-apps-gateway#deliver-policy-to-claude-desktop-sessions)에서 embedder 정책이 언제 적용되는지 다룹니다.730Embedding hosts는 SDK `managedSettings` 옵션을 통해 추가 관리형 정책을 제공할 수 있습니다. 여기에는 관리자가 `allowManaged*Only` 잠금을 설정하지 않은 경우 권한 허용 규칙이 포함됩니다. [Claude Desktop 세션에 정책 전달](/docs/ko/claude-apps-gateway#deliver-policy-to-claude-desktop-sessions)에서 embedder 정책이 언제 적용되는지 다룹니다.

720 731

721<h2 id="project-allow-rules-and-workspace-trust">732<h2 id="project-allow-rules-and-workspace-trust">

762| 설정 파일의 [Hooks](/docs/ko/hooks), [`env`](/docs/ko/settings-reference#env) 블록 및 [`apiKeyHelper`](/docs/ko/settings-reference#apikeyhelper)와 같은 도우미 명령, 그리고 프로젝트 스킬의 [hooks](/docs/ko/hooks#hooks-in-skills-and-agents) 및 [`allowed-tools`](/docs/ko/skills#pre-approve-tools-for-a-skill) | 사용됨 | 사용됨. 워크스페이스 신뢰는 어떤 세션에서도 스킬의 `allowed-tools`를 제한하지 않습니다 |773| 설정 파일의 [Hooks](/docs/ko/hooks), [`env`](/docs/ko/settings-reference#env) 블록 및 [`apiKeyHelper`](/docs/ko/settings-reference#apikeyhelper)와 같은 도우미 명령, 그리고 프로젝트 스킬의 [hooks](/docs/ko/hooks#hooks-in-skills-and-agents) 및 [`allowed-tools`](/docs/ko/skills#pre-approve-tools-for-a-skill) | 사용됨 | 사용됨. 워크스페이스 신뢰는 어떤 세션에서도 스킬의 `allowed-tools`를 제한하지 않습니다 |

763| `.claude/settings.json`의 `permissions.allow` 규칙 및 `additionalDirectories` | 신뢰 대화상자를 수락할 때까지 사용되지 않으며, 대화상자는 다시 나타나 이를 나열합니다 | 사용되지 않습니다. Claude Code는 [`this workspace has not been trusted`](/docs/ko/errors#workspace-has-not-been-trusted) 경고를 stderr에 출력합니다 |774| `.claude/settings.json`의 `permissions.allow` 규칙 및 `additionalDirectories` | 신뢰 대화상자를 수락할 때까지 사용되지 않으며, 대화상자는 다시 나타나 이를 나열합니다 | 사용되지 않습니다. Claude Code는 [`this workspace has not been trusted`](/docs/ko/errors#workspace-has-not-been-trusted) 경고를 stderr에 출력합니다 |

764| 프로젝트 [subagent](/docs/ko/sub-agents#hooks-in-subagent-frontmatter)의 Frontmatter hooks, 프로젝트 [`@skills-dir` plugin](/docs/ko/plugins/loading#plugins-shared-through-a-repository), 그리고 저장소 또는 `--add-dir` 디렉터리의 [`extraKnownMarketplaces`](/docs/ko/settings-reference#extraknownmarketplaces) 항목 | 사용되지 않으며, 대화상자가 제공되지 않습니다 | 사용되지 않습니다 |775| 프로젝트 [subagent](/docs/ko/sub-agents#hooks-in-subagent-frontmatter)의 Frontmatter hooks, 프로젝트 [`@skills-dir` plugin](/docs/ko/plugins/loading#plugins-shared-through-a-repository), 그리고 저장소 또는 `--add-dir` 디렉터리의 [`extraKnownMarketplaces`](/docs/ko/settings-reference#extraknownmarketplaces) 항목 | 사용되지 않으며, 대화상자가 제공되지 않습니다 | 사용되지 않습니다 |

765| 저장소 또는 `--add-dir` 디렉터리의 subagent frontmatter에 있는 인라인 [`mcpServers`](/docs/ko/sub-agents#scope-mcp-servers-to-a-subagent). v2.1.238 이전에는 Claude Code가 두 상황 모두에서 이러한 서버를 로드했습니다 | 사용되지 않으며, 대화상자가 제공되지 않습니다 | 사용되지 않습니다 |776| 저장소 또는 `--add-dir` 디렉터리의 subagent frontmatter에 있는 인라인 [`mcpServers`](/docs/ko/sub-agents#scope-mcp-servers-to-a-subagent) | 사용되지 않으며, 대화상자가 제공되지 않습니다 | 사용되지 않습니다 |

766| `.mcp.json`의 서버, 저장소가 [자체 설정에서 승인](/docs/ko/mcp#project-server-approvals-and-workspace-trust)하는 서버 포함 | Claude Code는 연결하기 전에 묻습니다. 저장소의 자체 승인은 계산되지 않습니다 | 승인 여부와 관계없이 묻지 않고 연결됩니다. SDK는 `settingSources`에 프로젝트 설정이 포함될 때만 로드합니다. 같은 폴더의 `claude mcp list`는 여전히 그러한 서버를 보류 중으로 보고합니다 |777| `.mcp.json`의 서버, 저장소가 [자체 설정에서 승인](/docs/ko/mcp#project-server-approvals-and-workspace-trust)하는 서버 포함 | Claude Code는 연결하기 전에 묻습니다. 저장소의 자체 승인은 계산되지 않습니다 | 승인 여부와 관계없이 묻지 않고 연결됩니다. SDK는 `settingSources`에 프로젝트 설정이 포함될 때만 로드합니다. 같은 폴더의 `claude mcp list`는 여전히 그러한 서버를 보류 중으로 보고합니다 |

767| `.mcp.json`의 서버에 있는 [`headersHelper`](/docs/ko/mcp#trust-a-folder-before-its-headershelper-runs). v2.1.238 이전에는 Claude Code가 두 상황 모두에서 도우미를 실행했습니다 | 신뢰 대화상자를 수락할 때까지 실행되지 않으며, 대화상자는 도우미가 선언된 위치를 다시 이름으로 지정합니다. Claude Code는 그때까지 정적 `headers`만으로 서버를 연결합니다 | 실행되지 않습니다. Claude Code는 정적 `headers`만으로 서버를 연결하고 서버당 [`headersHelper not run`](/docs/ko/errors#headershelper-not-run) 줄을 stderr에 출력합니다 |778| `.mcp.json`의 서버에 있는 [`headersHelper`](/docs/ko/mcp#trust-a-folder-before-its-headershelper-runs) | 신뢰 대화상자를 수락할 때까지 실행되지 않으며, 대화상자는 도우미가 선언된 위치를 다시 이름으로 지정합니다. Claude Code는 그때까지 정적 `headers`만으로 서버를 연결합니다 | 실행되지 않습니다. Claude Code는 정적 `headers`만으로 서버를 연결하고 서버당 [`headersHelper not run`](/docs/ko/errors#headershelper-not-run) 줄을 stderr에 출력합니다 |

768 779

769이 정확한 폴더를 신뢰해야 하는 행의 경우, 수동으로 신뢰하세요: `~/.claude.json`에서 `projects["<path>"].hasTrustDialogAccepted`를 `true`로 설정하세요. 여기서 `<path>`는 저장소 루트이거나 저장소 외부의 폴더입니다. Claude Code는 건너뛴 subagent hook 또는 인라인 MCP 서버의 디버그 로그 줄에, 건너뛴 허용 규칙의 stderr 경고에, 그리고 건너뛴 도우미의 `headersHelper not run` 줄에 정확한 키를 출력합니다.780이 정확한 폴더를 신뢰해야 하는 행의 경우, 수동으로 신뢰하세요: `~/.claude.json`에서 `projects["<path>"].hasTrustDialogAccepted`를 `true`로 설정하세요. 여기서 `<path>`는 저장소 루트이거나 저장소 외부의 폴더입니다. Claude Code는 건너뛴 subagent hook 또는 인라인 MCP 서버의 디버그 로그 줄에, 건너뛴 허용 규칙의 stderr 경고에, 그리고 건너뛴 도우미의 `headersHelper not run` 줄에 정확한 키를 출력합니다.

770 781

plugins/anthropic-marketplaces.md +5 −5

Details

43 `anthropics/claude-code`의 데모 마켓플레이스43 `anthropics/claude-code`의 데모 마켓플레이스

44</h3>44</h3>

45 45

46튜토리얼이나 이전 지침 세트에서 `/plugin marketplace add anthropics/claude-code`를 실행하도록 말하면, 이는 `claude-code-plugins`라는 데모 마켓플레이스를 추가합니다. 이는 Claude Code가 이미 추가한 공식 마켓플레이스가 아닙니다.46튜토리얼이나 이전 지침 세트에서 `/plugin marketplace add anthropics/claude-code`를 실행하도록 말하면, 이는 `claude-code-plugins`라는 데모 마켓플레이스를 추가합니다. 이는 공식 마켓플레이스가 아닙니다.

47 47

48데모 마켓플레이스의 플러그인 대부분은 같은 이름으로 공식 마켓플레이스에도 있습니다. 예를 들어, `code-review`, `feature-dev`, `commit-commands`, `security-guidance`는 둘 다에 있습니다. 두 개의 복사본이 설치되지 않도록 `claude-plugins-official`에서 이들을 설치합니다.48데모 마켓플레이스의 플러그인 대부분은 같은 이름으로 공식 마켓플레이스에도 있습니다. 예를 들어, `code-review`, `feature-dev`, `commit-commands`, `security-guidance`는 둘 다에 있습니다. 두 개의 복사본이 설치되지 않도록 `claude-plugins-official`에서 이들을 설치합니다.

49 49

51 공식 마켓플레이스에서 플러그인 찾기51 공식 마켓플레이스에서 플러그인 찾기

52</h2>52</h2>

53 53

54공식 마켓플레이스인 `claude-plugins-official`은 Claude Code가 추가하는 것입니다. 나열된 대부분의 내용은 Anthropic이 아닌 파트너 및 기타 작성자에게서 제공됩니다: 도구 공급업체는 Claude Code를 자신의 서비스에 연결하는 플러그인을 발행하고, Anthropic은 `commit-commands`, `code-review`, `feature-dev` 및 [언어 서버 플러그인](/docs/ko/plugins/code-intelligence)과 같은 더 작은 자신의 세트를 유지 관리합니다. 카탈로그는 자주 변경되므로 이 페이지에는 나열되지 않습니다.54기본적으로 Claude Code는 공식 마켓플레이스인 `claude-plugins-official`을 추가합니다. 나열된 대부분의 내용은 Anthropic이 아닌 파트너 및 기타 작성자에게서 제공됩니다: 도구 공급업체는 Claude Code를 자신의 서비스에 연결하는 플러그인을 발행하고, Anthropic은 `commit-commands`, `code-review`, `feature-dev` 및 [언어 서버 플러그인](/docs/ko/plugins/code-intelligence)과 같은 더 작은 자신의 세트를 유지 관리합니다. 카탈로그는 자주 변경되므로 이 페이지에는 나열되지 않습니다.

55 55

56포함된 내용을 보려면 Claude Code 세션에서 `/plugin`의 **발견** 탭을 사용하십시오. 이를 검색하거나 웹에서 [Claude 마켓플레이스](https://claude.com/marketplace/plugins)를 찾아볼 수 있습니다.56포함된 내용을 보려면 Claude Code 세션에서 `/plugin`의 **발견** 탭을 사용하십시오. 이를 검색하거나 웹에서 [Claude 마켓플레이스](https://claude.com/marketplace/plugins)를 찾아볼 수 있습니다.

57 57

61 61

62Claude Code, 웹 또는 GitHub에서 Anthropic의 마켓플레이스에서 플러그인을 검색할 수 있습니다:62Claude Code, 웹 또는 GitHub에서 Anthropic의 마켓플레이스에서 플러그인을 검색할 수 있습니다:

63 63

~~64* **Claude Code에서 찾아보기**: 대화형 세션에서 `/plugin`을 실행합니다. **발견** 탭에는 추가한 마켓플레이스의 플러그인이 나열됩니다.~~64* **Claude Code에서 찾아보기**: 대화형 세션에서 `/plugin`을 실행합니다. **Discover** 탭에는 마켓플레이스의 플러그인이 나열됩니다.

65* **Claude Code에서 이름으로**: 세션에서 `/plugin install <name>`을 실행하면, 추가한 마켓플레이스에서 이름을 조회합니다. 플러그인이 그 중 하나에 있으면 세부 정보가 `/plugin` 패널에서 열리고, [설치 범위](/docs/ko/plugins/install#install-a-plugin)를 선택하고 확인할 때까지 아무것도 설치되지 않습니다. 없으면 `Plugin "<name>" not found in any marketplace`가 표시됩니다.65* **Claude Code에서 이름으로**: 세션에서 `/plugin install <name>`을 실행하면, 마켓플레이스에서 이름을 조회합니다. 플러그인이 그 중 하나에 있으면 세부 정보가 `/plugin` 패널에서 열리고, [설치 범위](/docs/ko/plugins/install#install-a-plugin)를 선택하고 확인할 때까지 아무것도 설치되지 않습니다. 없으면 `Plugin "<name>" not found in any marketplace`가 표시됩니다.

66* **웹에서**: [Claude 마켓플레이스](https://claude.com/marketplace/plugins)에서 전체 카탈로그를 검색하면, 설치 수를 표시하고 일부 플러그인을 **Anthropic 검증됨**으로 표시합니다.66* **웹에서**: [Claude 마켓플레이스](https://claude.com/marketplace/plugins)에서 전체 카탈로그를 검색하면, 설치 수를 표시하고 일부 플러그인을 **Anthropic 검증됨**으로 표시합니다.

67* **GitHub에서**: [`anthropics/claude-plugins-official`](https://github.com/anthropics/claude-plugins-official)과 같은 마켓플레이스의 저장소에서 `.claude-plugin/marketplace.json`을 엽니다. 해당 파일이 카탈로그 자체입니다.67* **GitHub에서**: [`anthropics/claude-plugins-official`](https://github.com/anthropics/claude-plugins-official)과 같은 마켓플레이스의 저장소에서 `.claude-plugin/marketplace.json`을 엽니다. 해당 파일이 카탈로그 자체입니다.

68 68

69Anthropic의 디렉토리는 이러한 마켓플레이스와 별개입니다. 디렉토리는 claude.ai의 카탈로그이며, `/plugin`은 이를 나열하지 않습니다. claude.ai의 디렉토리에서 추가한 플러그인은 [계정 동기화](/docs/ko/plugins/loading#synced-plugins)를 통해 Claude Code에 도달합니다. 플러그인을 Anthropic의 디렉토리에 나열하려면 [Anthropic의 디렉토리에 제출](/docs/ko/plugins/publish#submit-to-anthropics-directory)을 참조합니다.69Anthropic의 디렉토리는 이러한 마켓플레이스와 별개입니다. 디렉토리는 claude.ai의 카탈로그입니다. claude.ai의 디렉토리에서 추가한 플러그인은 [계정 동기화](/docs/ko/plugins/loading#synced-plugins)를 통해 Claude Code에 도달합니다. 플러그인을 Anthropic의 디렉토리에 나열하려면 [Anthropic의 디렉토리에 제출](/docs/ko/plugins/publish#submit-to-anthropics-directory)을 참조합니다.

70 70

71데스크톱 앱에서 또는 스크립트에서 설치하거나 클라우드 세션이 로드하는 것을 보려면 [플러그인 설치](/docs/ko/plugins/install)를 참조합니다.71데스크톱 앱에서 또는 스크립트에서 설치하거나 클라우드 세션이 로드하는 것을 보려면 [플러그인 설치](/docs/ko/plugins/install)를 참조합니다.

72 72

plugins/cli-reference.md +36 −2

Details

29모든 하위 명령어는 다음 종료 코드, 플러그인 인수, 범위 값을 공유합니다:29모든 하위 명령어는 다음 종료 코드, 플러그인 인수, 범위 값을 공유합니다:

30 30

31* **종료 코드**: 성공 시 `0`, 실패 시 `1`. `validate`는 예상치 못한 오류에 대해 종료 코드 `2`를 추가하고, `eval`은 [해당 섹션](#plugin-eval)에 나열된 코드를 추가합니다.31* **종료 코드**: 성공 시 `0`, 실패 시 `1`. `validate`는 예상치 못한 오류에 대해 종료 코드 `2`를 추가하고, `eval`은 [해당 섹션](#plugin-eval)에 나열된 코드를 추가합니다.

32* **플러그인 인수**: `<plugin>` 인수는 플러그인 `name` 또는 `name@marketplace`입니다. 두 마켓플레이스가 같은 이름을 제공할 때는 정규화된 형식을 사용하세요.32* **플러그인 인수**: `<plugin>` 인수는 플러그인 `name` 또는 `name@marketplace`입니다. 두 마켓플레이스가 같은 이름을 제공할 때는 정규화된 형식을 사용하세요. `configure`는 정규화된 형식만 사용합니다.

33* **범위**: `--scope`는 `user`, `project`, 또는 `local`을 사용하며, 명령어가 쓰는 설정 파일의 이름을 지정합니다. `update`는 `managed`도 사용합니다.33* **범위**: `--scope`는 `user`, `project`, 또는 `local`을 사용하며, 명령어가 쓰는 설정 파일의 이름을 지정합니다. `update`는 `managed`도 사용합니다.

34 34

35<h3 id="plugin-init">35<h3 id="plugin-init">

87| 플래그 | 설명 |87| 플래그 | 설명 |

88| :- | :- |88| :- | :- |

89| `-s, --scope <scope>` | 설치 범위: `user`, `project`, 또는 `local`. 기본값은 `user` |89| `-s, --scope <scope>` | 설치 범위: `user`, `project`, 또는 `local`. 기본값은 `user` |

90| `--config <key=value>` | 플러그인의 매니페스트가 선언하는 [`userConfig`](/docs/ko/plugins/manifest-reference) 옵션을 설정합니다. 각 옵션에 대해 플래그를 반복합니다. Claude Code v2.1.147 이상 필요 |90| `--config <key=value>` | 플러그인의 매니페스트가 선언하는 [`userConfig`](/docs/ko/plugins/manifest-reference) 옵션을 설정합니다. 각 옵션에 대해 플래그를 반복합니다. Claude Code v2.1.147 이상 필요합니다. `<server>.<key>` 형식으로 작성된 키는 플러그인 내부에 배송된 [번들 MCP 서버](/docs/ko/plugins/components#include-a-packaged-mcpb-server)가 자체 `user_config`에서 선언하는 설정을 설정합니다. `<server>.<key>` 형식은 Claude Code v2.1.285 이상 필요합니다 |

91| `-y, --yes` | `Run this command now?` 프롬프트 없이 표시된 설치 명령어를 수락합니다. Bash 도구나 훅에서와 같이 Claude Code 세션 내부에서 명령어가 실행될 때는 무시됩니다. Claude Code v2.1.229 이상 필요 |91| `-y, --yes` | `Run this command now?` 프롬프트 없이 표시된 설치 명령어를 수락합니다. Bash 도구나 훅에서와 같이 Claude Code 세션 내부에서 명령어가 실행될 때는 무시됩니다. Claude Code v2.1.229 이상 필요 |

92| `--accept-command <sha256>` | 이전 [`--json` 실행](#plugin-json-result)이 `shownCommand`에서 보고한 `sha256`인 표시된 설치 명령어를 수락합니다. `-y` 대신 사용합니다. `-y`와 결합할 수 없습니다. [표시된 설치 명령어 수락](#accept-a-displayed-install-command)을 참조하세요. Claude Code v2.1.271 이상 필요 |92| `--accept-command <sha256>` | 이전 [`--json` 실행](#plugin-json-result)이 `shownCommand`에서 보고한 `sha256`인 표시된 설치 명령어를 수락합니다. `-y` 대신 사용합니다. `-y`와 결합할 수 없습니다. [표시된 설치 명령어 수락](#accept-a-displayed-install-command)을 참조하세요. Claude Code v2.1.271 이상 필요 |

93| `--json` | 스크립트에서 사용하기 위해 stdout의 마지막 줄에 하나의 JSON 객체로 결과를 출력합니다. [JSON 결과 형식](#plugin-json-result)을 참조하세요. Claude Code v2.1.268 이상 필요 |93| `--json` | 스크립트에서 사용하기 위해 stdout의 마지막 줄에 하나의 JSON 객체로 결과를 출력합니다. [JSON 결과 형식](#plugin-json-result)을 참조하세요. Claude Code v2.1.268 이상 필요 |

299| :- | :- |299| :- | :- |

302| `--data-size [plugin]` | 각 설치된 플러그인의 [저장된 데이터 디렉토리](#what-an-uninstall-deletes-and-keeps)를 측정하거나 `name@marketplace`로 지정된 명명된 플러그인만 측정합니다. `--json` 없이는 효과가 없습니다. 이름에 설치 기록이 없으면 명령어는 `--data-size names a plugin that is not installed`를 출력하고 목록을 출력하는 대신 `1`로 종료합니다. Claude Code v2.1.285 이상 필요합니다 |

302 303

303Claude Code는 사람이 읽을 수 있는 출력을 각 플러그인이 로드되는 방식으로 그룹화합니다:304Claude Code는 사람이 읽을 수 있는 출력을 각 플러그인이 로드되는 방식으로 그룹화합니다:

304 305

334| `hasUserConfig` | boolean | 플러그인이 로드되고 매니페스트가 [`userConfig` 옵션](/docs/ko/plugins/manifest-reference#user-configuration)을 선언할 때 존재하고 `true`입니다. 플러그인이 로드되지 않은 경우 매니페스트가 무엇을 선언하든 없습니다. 저장된 값은 절대 포함되지 않습니다. Claude Code v2.1.285 이상 필요합니다 |

335| `projectEnabled` | boolean | 프로젝트의 공유 `.claude/settings.json`이 플러그인을 켜는지 여부. 마켓플레이스 설치만 해당. Claude Code v2.1.285 이상 필요합니다 |

336| `dataDirSize` | object | `--data-size`를 사용하면 플러그인의 [저장된 데이터 디렉토리](#what-an-uninstall-deletes-and-keeps)의 크기를 `bytes`와 `human`으로 표시합니다. 디렉토리가 없거나 비어 있으면 없습니다. 마켓플레이스 설치만 해당. Claude Code v2.1.285 이상 필요합니다 |

337| `dataDirUnreadable` | boolean | `--data-size`를 사용하면 저장된 데이터 디렉토리가 존재하지만 측정할 수 없을 때 `true`입니다. 마켓플레이스 설치만 해당. Claude Code v2.1.285 이상 필요합니다 |

333 338

334`--json --available`을 사용하면 Claude Code는 배열 대신 하나의 객체를 출력합니다. 해당 `installed` 필드는 설치된 플러그인 객체의 배열을 보유하고, `available` 필드는 설치하지 않은 각 마켓플레이스 플러그인에 대해 아래 필드를 포함하는 하나의 객체를 보유합니다.339`--json --available`을 사용하면 Claude Code는 배열 대신 하나의 객체를 출력합니다. 해당 `installed` 필드는 설치된 플러그인 객체의 배열을 보유하고, `available` 필드는 설치하지 않은 각 마켓플레이스 플러그인에 대해 아래 필드를 포함하는 하나의 객체를 보유합니다.

335 340

373 378

374로드되지 않은 플러그인의 경우 Claude Code는 ``Plugin "formatter" not found. Run `claude plugin list` to see installed plugins, or pass --plugin-dir <path> to load one from disk.``를 출력하고 `1`로 종료합니다.379로드되지 않은 플러그인의 경우 Claude Code는 ``Plugin "formatter" not found. Run `claude plugin list` to see installed plugins, or pass --plugin-dir <path> to load one from disk.``를 출력하고 `1`로 종료합니다.

375 380

381<h3 id="plugin-configure">

382 plugin configure

383</h3>

384

385설치된 플러그인의 [`userConfig`](/docs/ko/plugins/manifest-reference#user-configuration) 옵션과 설정된 옵션을 표시하거나 stdin에서 파이프된 값을 저장합니다. Claude Code v2.1.285 이상 필요합니다.

386

387```bash theme={null}

388claude plugin configure <plugin>

389```

390

391| 플래그 | 설명 |

392| :- | :- |

393| `--values-stdin` | stdin에서 옵션 값을 JSON 객체의 단일 줄 문자열로 읽고 저장합니다. 생략한 옵션은 저장된 값을 유지합니다 |

394| `--json` | 결과를 stdout에 하나의 JSON 객체로 출력합니다. `--values-stdin` 없이 객체는 옵션의 `schema`와 `choices`, 시작 `inputs`, `configured`와 `unconfigured` 옵션 이름을 포함합니다. `--values-stdin`을 사용하면 `saved` 옵션 이름과 읽을 수 있을 때 `unconfigured` 옵션 이름을 포함합니다 |

395

396플래그 없이 명령어는 각 옵션을 최대 세 개의 레이블로 나열합니다: `required` 또는 `optional`, 그 다음 매니페스트가 민감하다고 선언하는 옵션의 경우 `sensitive`, 그 다음 `set` 또는 `not set`. 저장된 값을 출력하지 않습니다. `--json`을 사용하면 출력에는 민감하지 않은 옵션의 저장된 값이 포함되고 민감한 옵션의 텍스트는 절대 포함되지 않습니다.

397

398값을 저장하려면 JSON 객체로 파일에 작성하여 옵션 키를 문자열 값으로 매핑한 후 파일을 stdin에 전달하세요. `formatter@my-marketplace`를 자신의 플러그인 ID로 바꾸세요. `claude plugin list`가 표시하는 대로입니다. 이 예제는 `{"api_url": "https://example.com"}`을 포함하는 `values.json` 파일에서 `api_url`이라는 하나의 옵션을 설정합니다:

399

400```bash theme={null}

401claude plugin configure formatter@my-marketplace --values-stdin < values.json

402```

403

404Claude Code는 각 값을 옵션의 선언된 유형에 대해 검증하고 `Configuration saved. Restart Claude Code to apply it.`를 출력합니다. 매니페스트가 선언하지 않은 키를 전달하거나 검증에 실패하는 값을 전달하면 명령어는 아무것도 저장하지 않고, `Failed to save configuration:`을 이유와 함께 출력하고, `1`로 종료합니다. `--json`을 사용하면 거부된 값은 stdout에 `refused` 필드가 `message`를 포함하고 한 옵션이 잘못되었을 때 해당 `option` 키를 포함하는 객체도 출력합니다.

405

406플러그인의 전체 `name@marketplace` ID를 전달하세요. `claude plugin list`가 표시하는 대로입니다. `configure`는 베어 `name`을 수락하지 않습니다. 로드된 플러그인이 해당 ID를 가지지 않으면 명령어는 `No installed plugin has the id "<plugin>".`를 출력하고 `1`로 종료합니다.

407

408번들 MCP 서버의 설정은 [`plugin install --config`](#plugin-install) 또는 `/plugin`의 **Configure** 항목을 참조하세요.

409

376<h3 id="plugin-prune">410<h3 id="plugin-prune">

377 plugin prune411 plugin prune

378</h3>412</h3>

plugins/components.md +15 −3

Details

13 id: 'manifest',13 id: 'manifest',

14 name: 'Manifest',14 name: 'Manifest',

15 path: '.claude-plugin/plugin.json',15 path: '.claude-plugin/plugin.json',

~~16 required: "Required by Anthropic's directory",~~

17 lines: [{16 lines: [{

18 depth: 0,17 depth: 0,

19 kind: 'folder',18 kind: 'folder',

791 790

792`hooks/hooks.json`과 `hooks` manifest 키의 Hooks는 모두 로드됩니다. 모든 이벤트와 그 페이로드의 경우, [Hook 이벤트](/docs/ko/hooks#hook-events)를 참조합니다.791`hooks/hooks.json`과 `hooks` manifest 키의 Hooks는 모두 로드됩니다. 모든 이벤트와 그 페이로드의 경우, [Hook 이벤트](/docs/ko/hooks#hook-events)를 참조합니다.

793 792

793JavaScript 함수로 hooks를 작성하여 Claude Code 내부에서 실행되고 인터페이스에 그릴 수 있도록 하려면, 동일한 `hooks/hooks.json`의 `modules` 키 아래에 모듈 파일을 나열합니다. 하나를 가진 플러그인은 mod입니다. [mod 만들기](/docs/ko/plugins/mods/create)를 참조합니다.

794

794<h4 id="when-plugin-hooks-fire">795<h4 id="when-plugin-hooks-fire">

795 플러그인 hooks가 발생할 때796 플러그인 hooks가 발생할 때

796</h4>797</h4>

868 869

869서버는 번들의 manifest에서 `name`을 가져옵니다.870서버는 번들의 manifest에서 `name`을 가져옵니다.

870 871

872번들의 자신의 manifest는 서버가 필요로 하는 설정을 `user_config` 블록에서 선언할 수 있습니다. 저장된 값이 없는 필수 설정을 가진 번들된 서버는 시작되지 않습니다. `/plugin` **Errors** 탭은 `Bundled MCP server "<name>" was not started: it needs configuration`을 표시합니다.

873

874사용자는 두 가지 방법 중 하나로 값을 제공합니다:

875

876* **`/plugin`에서**: 플러그인을 **Installed** 탭에서 선택하고 **Configure**를 선택합니다

877* **설치 시, 셸에서**: [`--config <server>.<key>=<value>`](/docs/ko/plugins/cli-reference#plugin-install)를 `claude plugin install`에 전달합니다. Claude Code v2.1.285 이상이 필요하고, 플러그인 내부에 패키지된 번들에만 작동합니다.

878

871전송 및 인증의 경우, [MCP](/docs/ko/mcp#plugin-provided-mcp-servers)를 참조합니다.879전송 및 인증의 경우, [MCP](/docs/ko/mcp#plugin-provided-mcp-servers)를 참조합니다.

872 880

873<h3 id="lsp-servers">881<h3 id="lsp-servers">

1071 구성 대화 상자가 나타날 때1079 구성 대화 상자가 나타날 때

1072</h3>1080</h3>

1073 1081

1074대화 상자는 대화형 `/plugin` 인터페이스에서만 나타납니다. 사용자가 다음 중 하나를 수행할 때 아직 설정되지 않은 옵션에 대해 열립니다:1082대화 상자는 대화형 `/plugin` 인터페이스의 일부입니다. 사용자가 다음 중 하나를 수행할 때 아직 설정되지 않은 옵션에 대해 열립니다:

1075 1083

1076* `/plugin`에서 플러그인을 설치합니다1084* `/plugin`에서 플러그인을 설치합니다

1077* 세션 내에서 `/plugin install <plugin>@<marketplace>`를 실행합니다1085* 세션 내에서 `/plugin install <plugin>@<marketplace>`를 실행합니다

1079 1087

1080언제든지 동일한 대화 상자를 열려면, 사용자는 `/plugin configure <plugin>@<marketplace>`를 실행합니다.1088언제든지 동일한 대화 상자를 열려면, 사용자는 `/plugin configure <plugin>@<marketplace>`를 실행합니다.

1081 1089

1082`claude plugin install` 셸 명령은 `userConfig` 값을 프롬프트하지 않습니다. 셸에서 값을 설정하려면, 각각을 `--config KEY=VALUE`로 전달합니다. 옵션이 설정되지 않으면, 명령은 `userConfig options not yet set` 라인을 인쇄하여 둘 다 설정하는 방법을 이름 지정합니다. [The `userConfig` dialog never appears](/docs/ko/plugins/troubleshooting#the-userconfig-dialog-never-appears)는 라인을 인용합니다.1090VS Code 확장의 [플러그인 관리 대화 상자](/docs/ko/vs-code#install-plugins)는 설치 후 양식으로 설정되지 않은 옵션을 요청하며, 플러그인의 행에 있는 기어 아이콘은 모든 옵션과 함께 양식을 다시 엽니다.

1091

1092`claude plugin install` 셸 명령은 `userConfig` 값을 프롬프트하지 않습니다. 셸에서 값을 설정하려면, 설치할 때 각각을 `--config KEY=VALUE`로 전달하거나, 그 후 JSON 객체를 [`claude plugin configure --values-stdin`](/docs/ko/plugins/cli-reference#plugin-configure)으로 파이프합니다.

1093

1094옵션이 설정되지 않으면, `claude plugin install`은 `userConfig options not yet set` 라인을 인쇄합니다. 라인의 정확한 텍스트는 [The `userConfig` dialog never appears](/docs/ko/plugins/troubleshooting#the-userconfig-dialog-never-appears)를 참조합니다.

1083 1095

1084옵션 필드, 각 값이 저장되는 위치, 컴포넌트가 저장된 값을 참조하는 방법, `${user_config.*}`를 거부하는 필드의 경우, [사용자 구성](/docs/ko/plugins/manifest-reference#user-configuration)을 참조합니다.1096옵션 필드, 각 값이 저장되는 위치, 컴포넌트가 저장된 값을 참조하는 방법, `${user_config.*}`를 거부하는 필드의 경우, [사용자 구성](/docs/ko/plugins/manifest-reference#user-configuration)을 참조합니다.

1085 1097

plugins/install.md +9 −3

Details

41 /plugin install commit-commands@claude-plugins-official41 /plugin install commit-commands@claude-plugins-official

42 ```42 ```

43 43

44 대신 검색하려면 플러그인 이름 없이 `/plugin`을 실행합니다. 패널이 **Discover** 탭에서 열리며, 추가한 모든 마켓플레이스의 플러그인을 나열하고, 입력하여 검색한 후 플러그인에서 **Enter**를 눌러 세부 정보를 열 수 있습니다.44 대신 검색하려면 플러그인 이름 없이 `/plugin`을 실행합니다. 패널이 **Discover** 탭에서 열리며, 마켓플레이스의 플러그인을 나열하고, 입력하여 검색한 후 플러그인에서 **Enter**를 눌러 세부 정보를 열 수 있습니다.

45 </Step>45 </Step>

46 46

47 <Step title="플러그인이 추가하는 항목 검토">47 <Step title="플러그인이 추가하는 항목 검토">

72 요약의 마지막 문장은 플러그인이 이 세션에서 사용 가능한지 여부를 알려줍니다:72 요약의 마지막 문장은 플러그인이 이 세션에서 사용 가능한지 여부를 알려줍니다:

73 73

74 * **Active now**: `Plugin is now active.` 다시 로드할 필요가 없습니다.74 * **Active now**: `Plugin is now active.` 다시 로드할 필요가 없습니다.

75 * **Active, but a server needs setup**: `Plugin is now active.`는 `Its bundled MCP server needs configuration before it can start`로 이어집니다. 플러그인의 [번들된 MCP server](/docs/ko/plugins/components#include-a-packaged-mcpb-server)는 옵션을 설정할 때까지 시작할 수 없습니다. `/plugin`의 **Installed** 탭에서 플러그인을 선택하고 **Configure**를 선택하여 서버의 옵션을 설정합니다.

75 * **Reload needed**: `Run /reload-plugins to activate.` 패널이 닫히고 Claude Code가 해당 다시 로드를 실행합니다. 다시 로드가 [프롬프트 캐시를 무효화](/docs/ko/prompt-caching#enabling-or-disabling-a-plugin)하면 경고하고 대신 플러그인을 보류 상태로 둡니다. `/reload-plugins --force`를 실행하여 어쨌든 활성화하면 캐시되지 않은 요청 하나가 소요됩니다.76 * **Reload needed**: `Run /reload-plugins to activate.` 패널이 닫히고 Claude Code가 해당 다시 로드를 실행합니다. 다시 로드가 [프롬프트 캐시를 무효화](/docs/ko/prompt-caching#enabling-or-disabling-a-plugin)하면 경고하고 대신 플러그인을 보류 상태로 둡니다. `/reload-plugins --force`를 실행하여 어쨌든 활성화하면 캐시되지 않은 요청 하나가 소요됩니다.

76 * **Load failed**: `The plugin couldn't be loaded`. `/plugin`의 **Errors** 탭을 열어 이유를 확인한 후 [설치 후: 플러그인이 작동하지 않음](/docs/ko/plugins/troubleshooting#plugin-installed-but-not-working)을 참조하세요.77 * **Load failed**: `The plugin couldn't be loaded`. `/plugin`의 **Errors** 탭을 열어 이유를 확인한 후 [설치 후: 플러그인이 작동하지 않음](/docs/ko/plugins/troubleshooting#plugin-installed-but-not-working)을 참조하세요.

77 </Step>78 </Step>

248비공개 마켓플레이스는 GitHub 또는 다른 git 호스트의 저장소에 있으며, 복제하려면 자격 증명이 필요합니다. 공개 마켓플레이스와 동일한 `/plugin marketplace add` 또는 `claude plugin marketplace add` 명령으로 추가합니다. Claude Code는 머신에 이미 있는 git 자격 증명으로 복제하고 절대 프롬프트하지 않으므로, 각 연결 방식에는 요구 사항이 있습니다:249비공개 마켓플레이스는 GitHub 또는 다른 git 호스트의 저장소에 있으며, 복제하려면 자격 증명이 필요합니다. 공개 마켓플레이스와 동일한 `/plugin marketplace add` 또는 `claude plugin marketplace add` 명령으로 추가합니다. Claude Code는 머신에 이미 있는 git 자격 증명으로 복제하고 절대 프롬프트하지 않으므로, 각 연결 방식에는 요구 사항이 있습니다:

249 250

250* **HTTPS**: git 자격 증명 도우미가 적용되므로 `gh auth login`, macOS Keychain 또는 `git-credential-store`로 설정한 액세스가 작동합니다. 대화형 프롬프트가 억제되므로 인증한 적이 없는 호스트는 암호를 요청하는 대신 실패합니다.251* **HTTPS**: git 자격 증명 도우미가 적용되므로 `gh auth login`, macOS Keychain 또는 `git-credential-store`로 설정한 액세스가 작동합니다. 대화형 프롬프트가 억제되므로 인증한 적이 없는 호스트는 암호를 요청하는 대신 실패합니다.

251* **SSH**: 호스트가 이미 `known_hosts` 파일에 있어야 하고 키가 암호 프롬프트 없이 작동해야 합니다. 호스트 지문 및 암호 프롬프트도 억제되기 때문입니다.252* **SSH**: 호스트가 이미 `known_hosts` 파일에 있어야 하고 키가 암호 프롬프트 없이 작동해야 합니다. git 설정이 `GIT_SSH_COMMAND`, `GIT_SSH` 또는 git config의 `core.sshCommand`에서 SSH 프로그램을 이름 지정하면 Claude Code는 해당 프로그램을 실행합니다.

252* **GitHub `owner/repo` 약자**: Claude Code는 SSH 키가 `github.com`에 인증되는지 확인한 후, 인증되면 SSH를 통해 복제하고 인증되지 않으면 HTTPS를 통해 복제합니다. [`CLAUDE_CODE_PLUGIN_PREFER_HTTPS=1`](/docs/ko/env-vars#variables)을 설정하여 해당 확인을 건너뛰고 항상 HTTPS를 통해 복제합니다.253* **GitHub `owner/repo` 약자**: Claude Code는 SSH 키가 `github.com`에 인증되는지 확인한 후, 인증되면 SSH를 통해 복제하고 인증되지 않으면 HTTPS를 통해 복제합니다. [`CLAUDE_CODE_PLUGIN_PREFER_HTTPS=1`](/docs/ko/env-vars#variables)을 설정하여 해당 확인을 건너뛰고 항상 HTTPS를 통해 복제합니다.

253 254

254동일한 자격 증명이 `/plugin install`, `/plugin marketplace update` 및 `claude plugin update`를 실행할 때 적용됩니다.255동일한 자격 증명이 `/plugin install`, `/plugin marketplace update` 및 `claude plugin update`를 실행할 때 적용됩니다.

288 289

289* 입력하여 이름 또는 설명으로 필터링합니다.290* 입력하여 이름 또는 설명으로 필터링합니다.

290* **Space**를 눌러 선택한 플러그인을 활성화 또는 비활성화하고, **f**를 눌러 즐겨찾기에 추가합니다.291* **Space**를 눌러 선택한 플러그인을 활성화 또는 비활성화하고, **f**를 눌러 즐겨찾기에 추가합니다.

291* **Enter**를 눌러 플러그인의 세부 정보를 엽니다. 여기의 메뉴는 **Disable plugin** 또는 **Enable plugin**, **Update now**, **Uninstall**을 제공합니다. 설정을 사용하는 플러그인은 **Configure options**도 제공합니다.292* **Enter**를 눌러 플러그인의 세부 정보를 엽니다.

293

294플러그인의 세부 정보 메뉴는 **Disable plugin** 또는 **Enable plugin**, **Update now**, **Uninstall**을 제공합니다. 설정을 사용하는 플러그인에는 두 가지 항목이 더 나타나며, 플러그인은 둘 다 표시할 수 있습니다:

295

296* **Configure options**: 플러그인의 매니페스트가 [`userConfig` 옵션](/docs/ko/plugins/manifest-reference#user-configuration)을 선언할 때 표시됩니다. 해당 옵션의 대화 상자를 엽니다.

297* **Configure**: 플러그인이 [번들로 제공되는 MCP 서버](/docs/ko/plugins/components#include-a-packaged-mcpb-server)를 포함할 때 표시됩니다. 해당 서버의 자체 `user_config` 설정을 지정합니다.

292 298

293탭은 **Managed** 범위의 플러그인도 표시할 수 있습니다. 조직이 [관리 설정](/docs/ko/settings#settings-files)을 통해 설치한 플러그인이며, 여기서 활성화, 비활성화 또는 제거할 수 없습니다.299탭은 **Managed** 범위의 플러그인도 표시할 수 있습니다. 조직이 [관리 설정](/docs/ko/settings#settings-files)을 통해 설치한 플러그인이며, 여기서 활성화, 비활성화 또는 제거할 수 없습니다.

294 300

plugins/manifest-reference.md +12 −0

Details

149| `types` | Path | [mod](/docs/ko/plugins/mods/reference#files)의 `$.state` 값 및 `$` 명사를 선언하는 `.d.ts` 파일 |

170 171

171Claude Code는 모든 컴포넌트를 이 아래에 네임스페이스하므로 플러그인 `deploy-tools`의 에이전트 `reviewer`는 `deploy-tools:reviewer`로 나타납니다.172Claude Code는 모든 컴포넌트를 이 아래에 네임스페이스하므로 플러그인 `deploy-tools`의 에이전트 `reviewer`는 `deploy-tools:reviewer`로 나타납니다.

172 173

174`claude plugin validate`는 또한 이름이 Anthropic의 자체 플러그인 중 하나로 통과하지 않는지 확인합니다. 검사는 대소문자를 무시하고 구분자의 모든 실행을 하나로 취급합니다:

175

176| 이름 | 결과 |

177| :- | :- |

178| `claude-`, `anthropic-`, `anthropics-` 또는 `cc-plugin-`으로 시작 | 오류 |

179| `claude`, `anthropic`, `anthropics`, `claude-code` 또는 `claude-mods`임 | 오류 |

180| `official`을 `claude` 또는 `anthropic` 옆에 배치, 예: `official-claude-tools` | 오류 |

181| `mcp-for-claude`와 같이 다른 곳에서 `claude`, `anthropic` 또는 `anthropics`를 전체 단어로 포함 | 경고 |

182

183오류는 `Plugin name "<name>" is reserved: it passes as one of Anthropic's own`으로 읽히고 경고는 `Plugin name "<name>" reads as one of Anthropic's own`으로 읽힙니다. `claude plugin init` 및 `claude plugin tag`는 오류를 그리는 이름을 거부합니다. 이 명령들만 이름을 확인합니다. Claude Code는 여전히 이름을 거부하는 플러그인을 설치하고 로드합니다.

184

173<h3 id="displayname">185<h3 id="displayname">

174 `displayName`186 `displayName`

175</h3>187</h3>

plugins/marketplace-reference.md +2 −0

Details

484| `Author name cannot be empty` | 오류 | `owner.name` |484| `Author name cannot be empty` | 오류 | `owner.name` |

485| `Plugin name cannot contain spaces. Use kebab-case (e.g., "my-plugin")` | 오류 | `plugins[i].name` |485| `Plugin name cannot contain spaces. Use kebab-case (e.g., "my-plugin")` | 오류 | `plugins[i].name` |

486| `Plugin name cannot contain control or bidirectional-formatting characters` | 오류 | `plugins[i].name` |486| `Plugin name cannot contain control or bidirectional-formatting characters` | 오류 | `plugins[i].name` |

487| `Plugin name "x" is reserved: it passes as one of Anthropic's own` | 오류 | `plugins[i].name`. 매니페스트의 [`name`](/docs/ko/plugins/manifest-reference#name)에서 예약된 이름 참조 |

488| `Plugin name "x" reads as one of Anthropic's own` | 경고 | `plugins[i].name` |

487| `Claude Code cannot install plugins from marketplace "x". Each part of a plugin id (plugin@marketplace) may use only the letters a-z and A-Z, digits, ".", "_" and "-", and must start with a letter or digit. Change the marketplace's "name".` | 오류 | `name` |489| `Claude Code cannot install plugins from marketplace "x". Each part of a plugin id (plugin@marketplace) may use only the letters a-z and A-Z, digits, ".", "_" and "-", and must start with a letter or digit. Change the marketplace's "name".` | 오류 | `name` |

488| `Claude Code cannot install plugin "x". Each part of a plugin id (plugin@marketplace) may use only the letters a-z and A-Z, digits, ".", "_" and "-", and must start with a letter or digit. Change this entry's "name".` | 오류 | `plugins[i].name` |490| `Claude Code cannot install plugin "x". Each part of a plugin id (plugin@marketplace) may use only the letters a-z and A-Z, digits, ".", "_" and "-", and must start with a letter or digit. Change this entry's "name".` | 오류 | `plugins[i].name` |

489| `Duplicate plugin name "x" found in marketplace` | 오류 | 두 항목이 `name` 공유 |491| `Duplicate plugin name "x" found in marketplace` | 오류 | 두 항목이 `name` 공유 |

plugins/mods/admin.md +375 −0 created

Details

1> ## Documentation Index

2> 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.

5# 조직의 mod 관리

7> 관리되는 설정으로 Claude Code mod를 제어합니다: 사용자가 설치한 mod 중지, 자신의 mod만 허용, mod가 수행할 수 있는 작업 검토, 자신의 mod로 정책 적용.

9[mod](/docs/ko/plugins/mods/overview)는 Claude Code 내에서 실행되는 플러그인으로, 이를 설치한 사용자의 권한으로 코드를 실행합니다. Mod는 샌드박스 처리되지 않습니다. [관리되는 설정](/docs/ko/managed-settings)을 통해 사용자의 머신에서 mod가 실행되는지 여부, 어떤 mod가 실행되는지, 그리고 어떤 순서로 실행되는지를 결정할 수 있습니다. 또한 다른 mod가 수행하는 작업을 감시하거나 거부하는 자신의 mod를 설치할 수 있습니다.

11이 페이지는 파일, MDM 또는 claude.ai 관리자 콘솔을 통해 Claude Code의 관리되는 설정을 배포하는 담당자를 위한 것입니다. Mod는 Claude Code v2.1.287 이상에서 기본적으로 활성화되어 있습니다. 수행하려는 작업과 일치하는 섹션부터 시작하세요:

13* **사용자의 자체 mod를 제외하고, 자신의 mod 포함 여부와 관계없이**: [사용자가 설치한 mod가 로드되지 않도록 중지](#stop-user-installed-mods-from-loading)

14* **아무것도 변경하지 않을 때 사용자가 얻는 것 확인**: [기본적으로 어떤 일이 발생하는지 알기](#know-what-happens-by-default)

15* **다른 제한 사항이 있는 mod 유지**: [허용할 범위 선택](#choose-how-much-to-allow)

17<Note>

18 다음 경우는 다른 페이지에서 다룹니다:

20 * **이전에 관리되는 설정을 배포한 적이 없는 경우**: [관리되는 설정 배포](/docs/ko/managed-settings)부터 시작하세요

21 * **사용자가 설치할 수 있는 플러그인을 제어하려는 경우**: [조직의 플러그인 관리](/docs/ko/plugins/org)를 참조하세요

22</Note>

24<h2 id="stop-user-installed-mods-from-loading">

25 사용자가 설치한 mod가 로드되지 않도록 중지

26</h2>

28사용자가 가져오는 모든 mod가 로드되지 않도록 하려면 [기본 제공 가드](#know-what-happens-by-default)인 정책 mod에서 `allowManagedModsOnly` 옵션을 설정하세요. Claude Code는 사용자가 설치한 모든 mod 앞에 이 mod를 로드합니다. 옵션은 `pluginConfigs` 아래의 관리되는 설정에 `cc-plugin-sec-default@builtin`으로 키가 지정되어 있습니다:

30```json managed-settings.json theme={null}

31{

32 "pluginConfigs": {

33 "cc-plugin-sec-default@builtin": {

34 "options": {

35 "allowManagedModsOnly": true

36 }

37 }

38 }

39}

40```

42관리되는 설정에서 옵션을 설정하면:

44* **사용자가 가져오는 mod는 로드되지 않습니다**: 사용자가 설치한 플러그인의 mod, `--plugin-dir`로 로드된 mod, [세션 중에 Claude가 작성한 mod](/docs/ko/plugins/mods/create#ask-claude-for-a-mod)를 포함합니다

45* **조직의 mod는 계속 로드됩니다**: [조직의 것으로 간주되는](#install-your-organizations-mods) mod는 확인되지 않습니다. 다른 모든 mod는 사용자의 것으로 간주되며 로드되지 않습니다. 여기에는 GitHub 또는 다른 원격 마켓플레이스에서 활성화하는 플러그인의 mod와 조직이 claude.ai의 구성원을 위해 활성화하는 mod가 포함됩니다. 조직의 것으로 간주되는 mod가 없으면 설치된 mod는 로드되지 않습니다.

46* **사용자는 이를 실행 취소할 수 없습니다**: 가드는 관리되는 설정에서만 옵션을 읽으므로 사용자, 프로젝트 또는 로컬 설정 파일의 동일한 항목이나 `--settings`로 전달된 파일의 항목은 아무것도 변경하지 않습니다

47* **파일 또는 MDM 정책은 모든 공급자를 포함합니다**: 옵션을 파일로 또는 MDM을 통해 전달하면 Amazon Bedrock, Google Cloud의 Agent Platform, Microsoft Foundry에서 동일한 방식으로 작동합니다. claude.ai 관리자 콘솔에서 전달하는 경우 [플랫폼 가용성](/docs/ko/server-managed-settings#platform-availability)을 참조하세요

48* **사용자의 다른 사용자 정의는 계속 작동합니다**: [설정 파일의 hook](/docs/ko/hooks), 상태 줄, `/goal`은 영향을 받지 않습니다

49* **기본 제공 mod는 계속 실행됩니다**: `AGENTS.md` 지원과 같이 Claude Code에 기본 제공되는 mod는 각각 [자신의 스위치](/docs/ko/plugins/mods/overview#mods-built-into-claude-code)를 가집니다

51사용자의 머신에서 옵션을 확인하려면 `--plugin-dir`과 mod를 보유한 디렉터리의 경로(예: `claude --plugin-dir ./first-mod`)를 사용하여 Claude Code를 시작하세요. mod의 hook은 실행되지 않으며 트랜스크립트와 디버그 로그에는 [가드의 메시지](/docs/ko/plugins/mods/troubleshoot#messages-from-the-built-in-guard)가 있으며, 이는 mod의 이름과 `allowManagedModsOnly`를 나타냅니다. mod가 로드되면 [정책이 적용 중인지 확인](/docs/ko/managed-settings#check-that-a-policy-is-in-force) 및 [옵션이 적용되는지 결정하는 규칙](#set-options-on-the-built-in-guard)을 참조하세요.

53초기 액세스 중에 `CLAUDE_CODE_ENABLE_FUNCTION_HOOKS`를 `0`으로 설정한 경우 이 옵션으로 바꾸세요. Claude Code v2.1.287 이상은 모든 값에서 변수를 무시하므로 `0`이 있으면 mod가 활성화된 상태로 유지됩니다.

55<h2 id="know-what-happens-by-default">

56 기본적으로 어떤 일이 발생하는지 알기

57</h2>

59자신의 mod 설정이 없으면 사용자가 얻는 것은 다음과 같습니다:

61* **Mod가 활성화되어 있습니다.** 사용자는 플러그인 설정이 허용하는 모든 마켓플레이스에서 mod를 포함하는 플러그인을 설치하거나 `--plugin-dir`을 사용하여 디렉터리에서 로드할 수 있습니다.

62* **기본 제공 가드가 먼저 실행됩니다.** Claude Code는 `sec-default@builtin`이라는 기본 제공 mod를 사용자가 설치한 모든 mod 앞에 로드합니다. 사용자는 이를 끌 수 없습니다. `/plugin`과 디버그 로그는 이를 `cc-plugin-sec-default`로 나열합니다. 가드는 다음 중 하나가 참일 때 로드됩니다:

64 * 머신에 관리되는 설정이 있습니다

65 * 사용자가 Team 또는 Enterprise 플랜으로 Claude Code에 로그인했습니다

67 API 키로 인증하거나 Amazon Bedrock, Google Cloud의 Agent Platform, Microsoft Foundry를 통해 인증하는 사용자는 관리되는 설정이 있는 머신에서만 가드를 받습니다.

68* **가드는 관리하는 것을 보호합니다.** 사용자의 mod는 관리되는 hook이 받거나 결정하는 것, 시스템 프롬프트, 관리되는 `CLAUDE.md` 및 기타 관리되는 지침, 모든 mod가 설정으로 읽는 것, 관리되는 MCP 서버의 도구 및 설명을 변경할 수 없습니다.

69* **다른 모든 것은 허용됩니다.** 가드는 다른 제한을 추가하지 않습니다. 사용자의 mod는 여전히 파일을 읽고 쓰고, 프로세스를 시작하고, 네트워크 요청을 하고, 도구 호출 및 프롬프트를 다시 쓰고, 도구 호출을 거부하고, 그렇지 않으면 프롬프트할 도구 호출을 승인하고, 모두 해당 사용자의 권한으로 인터페이스에 그릴 수 있습니다.

70* **거부 규칙 및 관리되는 hook이 우선합니다.** 가드가 로드되는 곳에서 사용자의 mod는 `deny` 규칙이 거부하는 호출을 승인할 수 없으며, 어느 설정 파일이 규칙을 보유하든 상관없습니다. 관리되는 설정의 `PreToolUse` hook의 블록도 최종입니다. 둘 다 Claude의 도구 호출에 적용됩니다. 둘 다 mod의 자체 [`$.fs` 및 `$.process` 호출](/docs/ko/plugins/mods/api#reach-files-processes-and-the-network)에는 적용되지 않습니다: `Read(.env)`가 거부되면 mod는 여전히 `$.fs.read`로 해당 파일을 읽거나 그렇게 하는 프로그램을 시작할 수 있습니다. 이러한 호출을 제한하려면 mod가 로드되지 않도록 하거나 [정책 mod](#enforce-a-policy-with-a-mod-of-your-own)에서 호출을 hook하세요.

71* **다른 권한 확인을 재정의할 수 있습니다.** 도구 호출을 승인하는 사용자의 mod는 `ask` 규칙이 프롬프트할 호출이나 관리되는 설정 외부의 `PreToolUse` hook이 차단한 호출을 승인할 수 있습니다. 자동 모드에서 mod가 승인하는 호출은 분류기 확인 없이 실행됩니다.

73가드의 소스는 [Claude Code 저장소의 `mods/sec-default` 디렉터리](https://github.com/anthropics/claude-code/tree/main/mods/sec-default)에서 공개적으로 사용 가능합니다.

75<h3 id="know-which-controls-still-apply">

76 여전히 적용되는 제어 알기

77</h3>

79Mod는 이미 있는 제어를 대체하지 않습니다:

81* **설정 hook은 계속 작동합니다.** 설정 파일 및 플러그인의 `hooks/hooks.json`의 Command, HTTP, prompt, agent hook은 mod와 함께 이전과 같이 실행됩니다. 이에 대해 더 이상 사용되지 않는 것은 없습니다.

82* **거부 규칙은 가드가 로드되는 곳에서 우선합니다.** 사용자의 mod는 `deny` 규칙이 거부하는 호출을 승인할 수 없습니다. [`allowModsToOverrideDenyRules`](#set-options-on-the-built-in-guard)를 설정하지 않는 한 말입니다.

83* **관리되는 hook이 먼저 실행됩니다.** 관리되는 설정의 `PreToolUse` hook은 모든 mod가 도구 호출을 보기 전에 실행되며 해당 블록은 최종입니다. mod가 호출을 다시 쓰면 관리되는 hook이 다시 쓴 호출에서 다시 실행되므로 블록이 여전히 적용됩니다. 다른 설정 파일 및 플러그인의 `PreToolUse` hook은 마지막 mod 후에 실행되므로 자신의 결과를 도구 실행 대신 반환하는 mod는 이들이 실행되지 않도록 합니다. [Mod가 실행되는 순서](/docs/ko/plugins/mods/events#the-order-mods-run-in)를 참조하세요.

84* **네트워크 정책은 `$.http.fetch`를 포함합니다.** 조직이 웹 가져오기를 끄거나 세션에 대해 필수가 아닌 네트워크 트래픽이 꺼져 있으면 Claude Code는 mod가 `$.http.fetch`로 만드는 네트워크 요청을 거부합니다. 정책은 mod가 `$.process.run`으로 시작하는 프로그램을 포함하지 않습니다. 해당 프로그램은 사용자 자신의 액세스로 네트워크에 도달합니다.

85* **플러그인 제어는 mod를 포함합니다.** Mod는 플러그인이므로 [사용자가 설치할 수 있는 것을 제한하는 설정](/docs/ko/plugins/org#restrict-what-users-can-install)(예: `strictKnownMarketplaces`)은 설치 가능 여부를 결정합니다.

86* **Mod는 권한 프롬프트를 변경할 수 없습니다.** Mod는 Claude Code 인터페이스의 대부분을 다시 스타일링할 수 있지만 권한 프롬프트는 할 수 없으므로 프롬프트가 표시하는 것을 변경할 수 없습니다. Mod는 여전히 프롬프트가 나타나기 전에 도구 호출을 승인하거나 거부할 수 있습니다. [기본적으로 어떤 일이 발생하는지 알기](#know-what-happens-by-default)에서 설명합니다.

87* **신뢰 프롬프트가 먼저 나타납니다.** 사용자가 아직 신뢰하지 않은 디렉터리의 대화형 세션에서 신뢰 프롬프트에 답할 때까지 mod는 로드되지 않습니다.

88* **`--safe-mode`는 설치된 mod를 끕니다. 자신의 mod도 포함합니다.** `claude --safe-mode`로 세션을 시작하여 mod가 문제를 일으켰는지 확인하세요.

90이러한 제어 중 어느 것도 mod를 샌드박스 처리하지 않습니다. 허용하는 mod는 사용자로 실행되며 파일, 프로세스, 네트워크에 대한 사용자의 액세스 권한이 있습니다.

92<h2 id="decide-whether-to-leave-mods-on">

93 Mod를 활성화된 상태로 유지할지 결정

94</h2>

96Mod는 플러그인의 다른 부분보다 더 많은 작업을 할 수 있습니다. Claude Code 내부에서 실행되기 때문입니다. 모든 프롬프트와 도구 호출을 보고, 변경할 수 있으며, 권한 프롬프트가 나타나기 전에 도구 호출을 승인하거나 거부할 수 있습니다.

98사용자가 mod로 로드할 수 있는 것은 이미 있는 플러그인 제어에 따라 달라집니다:

100| 현재 플러그인 제어 | 사용자가 mod로 로드할 수 있는 것 |

101| :- | :- |

102| 없음 | 모든 마켓플레이스의 mod, `--plugin-dir`이 있는 모든 디렉터리, 또는 Claude가 세션 중에 작성하는 mod |

103| 마켓플레이스 허용 목록 | 허용하는 마켓플레이스의 mod 또는 `--plugin-dir`이 있는 모든 디렉터리. Claude가 작성하는 mod는 허용 목록이 [`skills-dir`을 포함](/docs/ko/plugins/org#keep-skills-directory-plugins-loading)할 때만 로드됩니다. |

104| 마켓플레이스 허용 목록 및 `disableSideloadFlags` | 허용하는 마켓플레이스의 mod |

105

106[조직의 플러그인 관리](/docs/ko/plugins/org)는 플러그인이 로드되는 모든 방법과 각각을 제어하는 설정을 나열합니다.

107

108사용자가 설치하기 전에 마켓플레이스의 mod를 확인하려면 [mod가 할 수 있는 작업 검토](#review-what-a-mod-can-do)를 참조하세요. 사용자의 mod를 그렇게 할 때까지 제외하려면 [사용자가 설치한 mod가 로드되지 않도록 중지](#stop-user-installed-mods-from-loading)를 참조하세요.

109

110<h3 id="review-what-a-mod-can-do">

111 mod가 할 수 있는 작업 검토

112</h3>

113

114실행하지 않고도 mod가 할 수 있는 작업을 볼 수 있습니다. 셸에서 플러그인의 디렉터리에 대해 `claude plugin validate`를 실행하세요:

115

116```bash theme={null}

117claude plugin validate ./some-mod

118```

119

120출력의 두 줄은 mod의 코드를 설명합니다:

121

122```text theme={null}

123 ❯ ./register.js hooks: session.start, tool.call, ui.render{component=Pane}

124 ❯ ./register.js calls: $.fs.read, $.http.fetch, $.store.set, $.ui.open

125```

126

127`hooks:` 줄은 mod가 받는 이벤트를 나열합니다. `calls:` 줄은 코드가 호출하는 mod API 메서드를 나열합니다. [mod API](/docs/ko/plugins/mods/api)(mod의 코드에서 `$`로 작성됨)는 mod가 파일, 프로세스, 네트워크에 도달하는 방법입니다. Claude Code는 이 명령이 읽을 수 없는 방식으로 mod API를 사용하는 mod를 로드하기를 거부합니다.

128

129`calls:` 줄에서 다음을 찾으세요:

130

131| 호출 | 의미 |

132| :- | :- |

133| `$.fs.read`, `$.fs.write` | 사용자가 할 수 있는 곳 어디든 파일을 읽거나 씁니다 |

134| `$.process.run`, `$.process.spawn` | 사용자로 프로그램을 시작합니다 |

135| `$.http.fetch` | 네트워크 요청을 합니다 |

136| `$.env.get`, `$.settings.read` | 환경 변수 및 설정을 읽습니다. API 키를 보유할 수 있습니다. `env reads:` 줄은 각 변수의 이름을 지정합니다. |

137| `$.env.set` | Claude Code 및 시작하는 모든 명령 및 MCP 서버에 대한 환경 변수를 설정합니다. 이는 해당 프로그램이 실행하는 것을 변경할 수 있습니다. `env writes:` 줄은 각 변수의 이름을 지정합니다. |

138| `$.mcp.call` | 연결된 MCP 서버의 도구를 호출합니다. 세션의 권한 규칙에 따릅니다 |

139| `$.model.complete` | 모델 호출에 사용자의 플랜 또는 API 키를 사용합니다 |

140| `$.prompt.submit` | 프롬프트를 제출하고 사용자 자신의 말로 보낼 수 있습니다 |

141| `$.session.send` | 다른 세션 또는 subagent의 Claude가 읽는 메시지를 보냅니다 |

142

143`hooks:` 줄에서 [`tool.call`](/docs/ko/plugins/mods/reference#tools) 및 [`prompt.submit`](/docs/ko/plugins/mods/reference#prompts-and-what-claude-reads)은 mod가 모든 도구 호출 및 모든 프롬프트를 보고 변경할 수 있음을 의미합니다. [`session.append`](/docs/ko/plugins/mods/reference#session)는 mod가 저장되기 전에 대화의 각 행을 다시 쓸 수 있음을 의미합니다. [`ui.render{component=AskUserQuestion}`](/docs/ko/plugins/mods/interface#change-what-claude-code-already-draws)는 mod가 Claude가 사용자에게 질문하는 데 사용하는 대화를 다시 그릴 수 있음을 의미합니다. `tool.check`는 mod가 권한 프롬프트가 나타나기 전에 도구 호출을 승인하거나 거부할 수 있음을 의미합니다. [기본적으로 어떤 일이 발생하는지 알기](#know-what-happens-by-default)는 해당 답변보다 우선하는 규칙 및 hook을 나열합니다.

144

145<h2 id="choose-how-much-to-allow">

146 허용할 범위 선택

147</h2>

148

149Mod 정책은 설치된 mod가 없는 것부터 사용자가 선택하는 모든 mod까지 다양하며, 자신의 mod가 다른 mod를 확인하고 각각은 몇 가지 관리되는 설정입니다. 원하는 정책을 첫 번째 열에서 찾고 두 번째 열이 이름을 지정하는 것을 설정하세요. [관리되는 설정 배포](/docs/ko/managed-settings)는 관리되는 설정이 있는 위치를 다룹니다.

150

151| 원하는 것 | 설정 |

152| :- | :- |

153| 설치된 mod 없음, hook은 건드리지 않음 | [`allowManagedModsOnly`](#set-options-on-the-built-in-guard)를 설정하고 자신의 mod를 배포하지 않음 |

154| 설치된 mod 없음, hook도 없음. 관리되는 hook 포함 | `disableAllHooks`를 `true`로 설정 |

155| 조직의 mod만 | 가드의 [`allowManagedModsOnly` 옵션](#stop-user-installed-mods-from-loading)을 설정하고 [mod를 설치](#install-your-organizations-mods)하여 조직의 것으로 간주되도록 함 |

156| 승인하는 마켓플레이스의 모든 mod | [마켓플레이스 제한](/docs/ko/plugins/org#restrict-what-users-can-install)을 유지하고 `disableSideloadFlags`를 `true`로 설정 |

157| 모든 mod, 자신의 mod가 다른 mod를 확인 | [mod를 설치](#install-your-organizations-mods)하고 `prependPlugins`에서 `sec-default@builtin`과 함께 나열 |

158

159각 설정이 하는 작업:

160

161* **`allowManagedModsOnly`**: 기본 제공 가드의 옵션입니다. 사용자의 자체 mod는 로드되지 않으며 설정 hook, 상태 줄, `/goal`은 계속 작동합니다. [사용자가 설치한 mod가 로드되지 않도록 중지](#stop-user-installed-mods-from-loading)는 포함하는 것을 나열합니다.

162* **`allowManagedHooksOnly`**: 더 넓은 설정입니다. [조직의 mod](#install-your-organizations-mods) 및 Claude Code에 기본 제공되는 mod만 로드됩니다. 사용자가 자신이 설치한 mod는 로드되지 않습니다. 설정은 또한 사용자의 자체 설정 파일의 hook을 차단합니다. 설정하기 전에 [`allowManagedHooksOnly` 아래에서 실행되는 것](/docs/ko/settings-reference#what-runs-under-allowmanagedhooksonly)을 읽으세요.

163* **`disableAllHooks`**: 가장 넓은 설정입니다. 관리되는 설정에서 설치된 모든 플러그인의 mod(자신의 포함)를 중지하고 설정 파일의 모든 hook을 끕니다. 따라서 관리되는 설정의 `PreToolUse` hook은 더 이상 아무것도 차단하지 않습니다. 사용자 정의 상태 줄 및 `/goal`도 작동을 중지합니다. 설정하기 전에 [`disableAllHooks`](/docs/ko/settings-reference#disableallhooks)를 읽으세요.

164* **`disableSideloadFlags`**: 시작 시 `--plugin-dir` 및 `--plugin-url`을 거부하므로 아무도 디렉터리에서 mod를 로드하지 않으며 Claude가 세션 중에 작성하는 mod가 로드되지 않도록 합니다. 설정은 또한 `--agents` 및 `--mcp-config`를 거부합니다. 설정하기 전에 [`disableSideloadFlags`](/docs/ko/settings-reference#disablesideloadflags)를 읽으세요.

165

166Claude Code에 기본 제공되는 mod(예: `AGENTS.md` 지원)는 이러한 설정의 영향을 받지 않습니다. 각각은 [자신의 스위치](/docs/ko/plugins/mods/overview#mods-built-into-claude-code)를 가집니다.

167

168mod가 로드되지 않은 사용자는 디버그 로그에서 이유를 찾습니다. [거부 메시지](/docs/ko/plugins/mods/troubleshoot#refusal-messages)는 `allowManagedHooksOnly` 및 `disableAllHooks`의 줄을 나열하고 [기본 제공 가드의 메시지](/docs/ko/plugins/mods/troubleshoot#messages-from-the-built-in-guard)는 `allowManagedModsOnly`의 줄을 가집니다.

169

170<h3 id="set-options-on-the-built-in-guard">

171 기본 제공 가드에서 옵션 설정

172</h3>

173

174기본 제공 가드는 두 가지 옵션을 사용합니다. [사용자가 설치한 mod가 로드되지 않도록 중지](#stop-user-installed-mods-from-loading)의 예제처럼 `pluginConfigs` 아래의 관리되는 설정에서 `cc-plugin-sec-default@builtin`으로 키가 지정되어 있습니다.

175

176표는 각 옵션이 설정되지 않았을 때와 `true`로 설정되었을 때 사용자가 얻는 것을 제공합니다:

177

178| 옵션 | 설정되지 않음 | `true` |

179| :- | :- | :- |

180| `allowManagedModsOnly` | 사용자의 자체 mod가 로드됨 | [조직의 mod](#install-your-organizations-mods) 및 Claude Code에 기본 제공되는 mod만 로드됩니다. Claude Code는 사용자가 설치했거나 `--plugin-dir`로 이름을 지정한 mod를 포함한 다른 모든 mod를 거부합니다. |

181| `allowModsToOverrideDenyRules` | 거부 규칙이 사용자의 mod보다 우선합니다 | 도구 호출을 승인하는 사용자의 mod는 `deny` 규칙이 거부하는 호출을 승인할 수 있습니다 |

182

183이러한 규칙은 옵션이 적용되는지 결정합니다:

184

185* **ID는 여기서 한 가지 철자입니다**: Claude Code는 `cc-plugin-sec-default@builtin` 아래에서만 옵션을 읽습니다. `prependPlugins`는 `sec-default@builtin`도 허용하고 `pluginConfigs`는 허용하지 않습니다.

186* **관리되는 설정만 계산됩니다**: 사용자, 프로젝트 또는 로컬 설정 파일의 동일한 항목이나 `--settings`로 전달된 파일의 항목은 옵션을 설정하거나 느슨하게 하지 않습니다

187* **가드가 로드되어야 합니다**: `prependPlugins`를 설정하면 [목록에서 가드의 이름을 지정](#install-your-organizations-mods)하세요. 가드가 로드되지 않는 곳에서 옵션도 적용되지 않습니다.

188* **가드는 닫힌 상태로 실패합니다**: 가드가 관리되는 설정을 읽을 수 없으면 로드 시 모든 사용자의 mod를 거부합니다. 사용자의 mod가 승인한 호출에 대해 거부 규칙을 확인할 수 없으면 호출을 거부합니다.

189

190[기본 제공 가드의 메시지](/docs/ko/plugins/mods/troubleshoot#messages-from-the-built-in-guard)는 옵션이 적용될 때 사용자가 보는 것입니다.

191

192<h2 id="run-your-organization’s-own-mods">

193 조직의 자체 mod 실행

194</h2>

195

196모든 사용자에게 자신의 mod를 배포하고, 사용자의 mod에 상대적으로 실행되는 위치를 선택하고, 정책을 적용하는 데 사용할 수 있습니다.

197

198<h3 id="install-your-organizations-mods">

199 조직의 mod를 설치하고 순서를 설정합니다

200</h3>

201

202조직의 mod는 사용자의 mod가 로드되지 않는 곳에 로드되고 그 앞에서 실행될 수 있으므로 Claude Code는 mod가 조직에서 왔다는 것을 알 수 있어야 합니다. 다음이 모두 참일 때만 mod를 조직의 것으로 취급합니다:

203

204* 관리되는 `enabledPlugins`는 mod의 플러그인을 `true`로 설정합니다

205* 관리되는 설정은 플러그인의 [마켓플레이스](/docs/ko/plugins/create-marketplace)를 사용자의 머신의 디렉터리로 절대 경로로 이름을 지정합니다. `extraKnownMarketplaces` 항목이 그렇게 하고 사용자를 위해 마켓플레이스를 등록합니다.

206* 마켓플레이스는 플러그인을 상대 경로로 나열하므로 Claude Code는 [해당 디렉터리에서 로드](/docs/ko/plugins/loading#in-place-and-copied-plugins)합니다

207

208이를 충족하려면 장치 관리가 마켓플레이스 디렉터리를 모든 머신의 동일한 경로에 복사하도록 합니다. 관리되는 설정 파일처럼 디렉터리 및 그 위의 모든 디렉터리를 관리자만 쓸 수 있도록 만드세요. 거기에 쓸 수 있는 사람은 누구든 mod를 다시 쓸 수 있습니다. claude.ai 관리자 콘솔에서 전달하는 관리되는 설정은 키를 전달할 수 있지만 머신에 디렉터리를 넣을 수 없습니다.

209

210디렉터리는 마켓플레이스의 매니페스트 및 플러그인을 보유합니다:

211

212```text theme={null}

213/opt/acme/claude-plugins/

214├── .claude-plugin/

215│ └── marketplace.json

216└── plugins/

217 └── acme-guard/

218 ├── .claude-plugin/

219 │ └── plugin.json

220 └── hooks/

221 ├── hooks.json

222 └── register.js

223```

224

225매니페스트는 플러그인을 해당 디렉터리에 상대적인 경로로 나열합니다:

226

227```json /opt/acme/claude-plugins/.claude-plugin/marketplace.json theme={null}

228{

229 "name": "acme-tools",

230 "owner": { "name": "Acme" },

231 "plugins": [

232 { "name": "acme-guard", "source": "./plugins/acme-guard", "description": "Acme policy mod" }

233 ]

234}

235```

236

237Claude Code가 캐시에 복사하는 플러그인은 관리되는 `enabledPlugins`가 활성화하더라도 사용자의 것으로 간주됩니다. 이는 GitHub, git, URL 또는 npm 소스의 모든 플러그인을 포함합니다. 해당 mod는 사용자의 mod 중에서 실행되고 `prependPlugins` 및 `appendPlugins`는 이를 건너뛰고 `allowManagedModsOnly` 또는 `allowManagedHooksOnly` 아래에서 로드되지 않습니다. 사용자의 디버그 로그에는 플러그인의 ID로 시작하고 `is enabled by managed settings, but`인 줄이 있습니다.

238

239Claude Code는 도구를 실행하는 것과 같이 행동하려고 할 때마다 이벤트를 발생시키고 각 mod에 차례로 전달합니다. 조직의 것으로 간주되는 mod는 어디에도 나열하지 않아도 [사용자의 mod 전에 실행](/docs/ko/plugins/mods/events#the-order-mods-run-in)됩니다. 위치를 설정하려면 ID를 두 가지 설정 중 하나에 나열하세요. ID는 플러그인의 이름, `@`, 마켓플레이스의 이름입니다. 예: `acme-guard@acme-tools`.

240

241* **`prependPlugins`**: mod는 모든 사용자의 mod 전에 모든 이벤트를 보고 모든 결과 후에 봅니다. 이벤트를 변경하거나 거부하거나 사용자의 mod를 건너뛸 수 있습니다.

242* **`appendPlugins`**: mod는 모든 사용자의 mod 후에 실행되므로 해당 mod가 전달하는 이벤트만 해당 형식으로 봅니다

243

244이 예제는 `/opt/acme/claude-plugins`에서 `acme-tools` 마켓플레이스를 선언하고 `acme-guard`를 활성화하고 해당 mod를 먼저 실행하고 기본 제공 가드를 그 다음에 실행합니다:

245

246```json managed-settings.json theme={null}

247{

248 "extraKnownMarketplaces": {

249 "acme-tools": {

250 "source": { "source": "directory", "path": "/opt/acme/claude-plugins" }

251 }

252 },

253 "enabledPlugins": { "acme-guard@acme-tools": true },

254 "prependPlugins": ["acme-guard@acme-tools", "sec-default@builtin"]

255}

256```

257

258각 키는 한 가지 작업을 합니다:

259

260* **`extraKnownMarketplaces`**: `acme-tools` 마켓플레이스를 보유하는 디렉터리의 이름을 지정합니다. `path`는 `.claude-plugin/marketplace.json`을 포함하는 디렉터리의 절대 경로입니다.

261* **`enabledPlugins`**: 이러한 관리되는 설정을 받는 모든 사용자에 대해 `acme-guard`를 켭니다

262* **`prependPlugins`**: `acme-guard`를 먼저, 기본 제공 가드를 두 번째로 배치하고 사용자가 설치한 모든 mod 앞에 배치합니다. Claude Code는 나열하는 순서를 따릅니다.

263

264사용자의 머신이 설정을 받았는지 확인하려면 [정책이 적용 중인지 확인](/docs/ko/managed-settings#check-that-a-policy-is-in-force)을 참조하세요.

265

266mod가 실행되는 위치를 확인하려면 해당 머신에서 `claude --debug`로 세션을 시작하고 [디버그 로그](/docs/ko/plugins/mods/troubleshoot#read-the-debug-log)에서 mod의 ID를 검색하세요:

267

268* **`hooks module acme-guard@acme-tools loaded`, `tier prepend` 포함**: mod는 조직의 것으로 간주되고 먼저 실행됩니다

269* **`tier user`가 있는 동일한 줄**: Claude Code는 이를 사용자의 mod로 취급합니다. 두 번째 줄 `prependPlugins names acme-guard@acme-tools, which is not an enabled managed plugin with a hooks module; skipped`는 목록이 이를 건너뛰었다고 말합니다.

270

271이러한 규칙은 두 목록의 어떤 ID가 적용되는지 결정합니다:

272

273* **목록은 기본값을 대체합니다**: 관리되는 설정에서 `prependPlugins`를 설정할 때 기본 제공 가드를 유지하려면 `sec-default@builtin`을 이름을 지정하세요. 가드는 기본 제공되며 `enabledPlugins` 항목이 필요하지 않습니다.

274* **자신의 ID는 조직의 것으로 간주되어야 합니다**: 관리되는 설정에서 Claude Code는 플러그인이 조직의 mod에 대한 세 가지 조건을 충족하지 않는 ID를 건너뜁니다

275* **저장소는 이들을 설정할 수 없습니다**: Claude Code는 두 설정을 관리되는 설정에서만 읽고 저장소의 설정 파일에서는 읽지 않습니다. 사용자는 `~/.claude/settings.json`에서 설정하여 관리되는 설정이 없는 머신에서만 자신의 mod를 정렬할 수 있으며 Team 또는 Enterprise 플랜으로 로그인하지 않은 경우에만 가능합니다. 다른 곳에서 Claude Code는 사용자 설정의 두 키를 무시합니다. 거기의 목록은 기본 제공 가드를 추가하거나 제거하지 않습니다.

276

277<h3 id="enforce-a-policy-with-a-mod-of-your-own">

278 자신의 mod로 정책 적용

279</h3>

280

281모든 사용자의 mod를 제외하려면 자신의 mod가 필요하지 않습니다. [`allowManagedModsOnly`](#stop-user-installed-mods-from-loading)를 설정하세요. 일부 사용자의 mod를 허용하고 다른 mod를 거부하거나 mod가 하는 작업을 기록하려는 경우 정책 mod를 작성하세요.

282

283다른 mod가 로드되려고 할 때마다 mod는 `claude plugin validate`가 인쇄하는 목록을 [`plugin.register`](/docs/ko/plugins/mods/reference#other-mods)라는 이벤트에서 받습니다. `prependPlugins`의 mod는 해당 목록을 읽고 mod를 거부할 수 있습니다. 또한 [이름으로 모든 mod API 호출을 hook](/docs/ko/plugins/mods/api#reach-files-processes-and-the-network)하여 다른 모든 mod에 대해 해당 호출을 기록하거나 거부할 수 있습니다. 이름은 `$.` 없는 메서드이므로 `fs.write`의 hook은 모든 `$.fs.write` 호출을 봅니다.

284

285이 정책 mod는 자신의 코드가 `$.process.run` 또는 `$.process.spawn`을 호출하는 모든 사용자의 mod를 거부합니다. 또한 감사 로그를 유지하여 각 도구 호출 및 mod가 쓰는 각 파일을 디버그 로그에 씁니다. 먼저 실행되므로 로그는 사용자의 mod가 변경하기 전에 요청된 것을 기록합니다. `acme-guard/hooks/register.js`로 저장하세요:

286

287```javascript acme-guard/hooks/register.js theme={null}

288// 사용자의 mod가 호출할 수 없는 메서드, 각각 namespace.method로 철자

289const BLOCKED_CALLS = ['process.run', 'process.spawn']

290

291export function register(on) {

292 // 다른 mod가 로드되려고 할 때마다 실행됨

293 on('plugin.register', async ($, e, next) => {

294 // 해당 mod의 코드에서 차단 목록에 있는 호출을 유지

295 const blocked = e.uses.calls.filter((call) => BLOCKED_CALLS.includes(call))

296 if (e.tier === 'user' && blocked.length > 0) {

297 // 거부를 반환하면 mod가 로드되지 않으며 텍스트가 이유입니다

298 return { refuse: 'Acme policy: mods may not call ' + blocked.join(', ') }

299 }

300 // 다른 모든 mod를 로드하도록 허용

301 return next(e)

302 })

303

304 // 각 도구 호출을 기록한 다음 변경되지 않은 상태로 진행

305 on('tool.call', async ($, e, next) => {

306 $.ui.log('audit tool.call ' + e.tool, { to: 'debug' })

307 return next(e)

308 })

309

310 // 파일을 쓴 mod를 기록한 다음 경로를 기록합니다. mod가 선택했으므로 인용됨

311 on('fs.write', async ($, e, next) => {

312 $.ui.log('audit fs.write by ' + next.origin.plugin + ' ' + JSON.stringify(e.path), { to: 'debug' })

313 return next(e)

314 })

315}

316```

317

318파일은 세 가지 hook을 등록합니다:

319

320* **`plugin.register`**: 다른 mod가 로드되는지 결정합니다. 차단된 메서드를 호출하는 사용자의 mod를 거부하고 다른 모든 mod를 전달합니다.

321* **`tool.call`**: 각 도구 호출에 대해 `audit tool.call Bash`와 같은 줄을 디버그 로그에 쓰고 아무것도 변경하지 않습니다

322* **`fs.write`**: 다른 mod가 만드는 각 `$.fs.write` 호출에 대해 `audit fs.write by reader "/tmp/notes.md"`와 같은 줄을 씁니다. mod의 이름이 먼저 나오고 경로가 인용되므로 mod가 선택하는 경로는 줄의 다른 필드로 전달될 수 없습니다.

323

324`plugin.register` hook은 이벤트의 두 필드를 읽습니다:

325

326* **`e.tier`**: mod가 실행될 위치, `prepend`, `user`, `append`, `builtin` 중 하나입니다. 사람이 설치하는 모든 mod는 `user`입니다.

327* **`e.uses.calls`**: mod가 호출하는 mod API 메서드, 각각 `process.run`과 같이 `namespace.method`로 철자, `claude plugin validate`가 인쇄하는 `$.` 없음

328

329사용자가 `$.process.run`을 호출하는 mod를 설치하면 mod가 로드되지 않으며 디버그 로그에는 `refused by acme-guard:`로 끝나고 이유가 있는 줄이 있습니다. 거부는 또한 [플러그인 디렉터리를 핫 리로드하는 세션](/docs/ko/plugins/mods/troubleshoot#find-out-why-a-mod-does-nothing)의 트랜스크립트에 도달합니다. 전체 mod를 거부하지 않고 호출을 차단하려면 해당 호출의 이름에 대한 hook에서 `{ deny: 'your reason' }`을 반환하세요.

330

331감사 줄을 디버그 로그 이외의 다른 곳으로 보내려면 동일한 hook에서 `$.http.fetch`를 호출하세요.

332

333세션은 mod 없이 실행될 수 있습니다. 설치된 mod를 실행하는 워커 스레드가 [3번 충돌](/docs/ko/plugins/mods/troubleshoot#mods-that-run-in-the-hooks-worker-are-off-for-this-session)하면 Claude Code는 기본 제공되지 않은 모든 mod(자신의 포함)를 언로드합니다. 사용자가 `/reload-plugins`를 실행하거나 새 세션을 시작할 때까지입니다. 그리고 `--safe-mode`로 Claude Code를 시작하는 사용자는 설치된 mod 없이 실행되며 자신의 mod도 포함됩니다.

334

335[mod 만들기](/docs/ko/plugins/mods/create)는 mod가 필요한 파일을 다룹니다. [다른 mod를 판단하는 mod 테스트](/docs/ko/plugins/mods/test#test-a-mod-that-judges-other-mods)는 이 정책 mod에 대한 테스트 파일을 가집니다.

336

337<h4 id="refuse-mods-when-your-check-fails">

338 확인이 실패할 때 mod 거부

339</h4>

340

341`plugin.register` hook이 throw하거나 시간 제한을 초과하면 Claude Code는 hook을 건너뛰므로 확인이 열린 상태로 실패하고 확인 중인 mod가 로드됩니다. 닫힌 상태로 실패하고 사용자의 mod를 거부하려면 확인을 명명된 함수로 이동하고 거부를 반환하는 `.catch` 핸들러를 추가하세요. 이 파일 버전은 `plugin.register` hook만 표시하므로 첫 번째 버전의 두 감사 hook을 `register`에 유지하세요:

342

343```javascript acme-guard/hooks/register.js theme={null}

344const BLOCKED_CALLS = ['process.run', 'process.spawn']

345

346// 이전과 동일한 확인, 자신의 함수로 이동됨

347async function checkMod($, e, next) {

348 const blocked = e.uses.calls.filter((call) => BLOCKED_CALLS.includes(call))

349 if (e.tier === 'user' && blocked.length > 0) {

350 return { refuse: 'Acme policy: mods may not call ' + blocked.join(', ') }

351 }

352 return next(e)

353}

354

355export function register(on) {

356 // 핸들러는 checkMod가 throw하거나 시간 제한을 초과할 때만 실행됨

357 on('plugin.register', checkMod).catch(async ($, e, next) => {

358 // 조직의 mod 및 기본 제공 mod를 로드하도록 허용

359 if (e.tier !== 'user') return next(e)

360 // 확인할 수 없었던 사용자의 mod를 거부

361 return { refuse: 'Acme policy check failed, so this mod was not loaded' }

362 })

363}

364```

365

366핸들러가 있으면 확인이 throw하거나 시간 초과될 때 확인 중인 mod가 로드되지 않으며 거부 줄은 두 번째 이유를 전달합니다. 예: `refused by acme-guard: Acme policy check failed, so this mod was not loaded`. 핸들러는 `user` 계층 외부의 모든 mod를 `next(e)`로 전달하므로 실패한 확인이 조직이 나열하는 mod를 중지하지 않습니다. [실패하는 hook 처리](/docs/ko/plugins/mods/events#handle-a-hook-that-fails)는 다른 이벤트에 대해 `.catch`를 다룹니다.

367

368<h2 id="next-steps">

369 다음 단계

370</h2>

371

372* [플러그인 보안](/docs/ko/plugins/security): 모든 플러그인이 사용자의 머신에서 할 수 있는 것과 설치 전에 검토하는 방법

373* [Mod 개요](/docs/ko/plugins/mods/overview): mod가 무엇이고 hook, skill, MCP 서버와 어떻게 비교되는지

374* [Mod가 실행되는 순서](/docs/ko/plugins/mods/events#the-order-mods-run-in): `prependPlugins` 및 `appendPlugins`가 사용자의 mod와 어떻게 맞는지

375* [설정 및 환경 변수](/docs/ko/plugins/mods/reference#settings-and-environment-variables): 이 페이지에서 이름이 지정된 모든 설정을 한 표에서

plugins/mods/api.md +218 −0 created

Details

1> ## Documentation Index

2> 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.

5# mods API 사용하기

7> Claude Code mod에서 mods API를 호출하여 명령어와 도구를 추가하고, 모델을 호출하고, 타이머에서 작업을 실행하고, 다른 세션에 메시지를 보내고, 파일 및 네트워크에 접근합니다.

9mods API는 mod가 작동하기 위해 호출하는 메서드의 집합입니다. 명령어와 도구를 추가하고, 모델을 호출하고, 이벤트 사이에 작업을 실행하고, 파일 시스템, 프로세스 및 네트워크에 접근합니다. 모든 hook은 첫 번째 인수인 `$`로 이를 받으며, 메서드는 `$.ui` 및 `$.fs`와 같은 네임스페이스로 그룹화됩니다. [이벤트](/docs/ko/plugins/mods/events)는 hook이 실행되는 시점을 결정하며, mods API는 hook이 실행되면 호출하는 것입니다.

11여기서 시작하기 전에 [첫 번째 mod를 빌드](/docs/ko/plugins/mods/create)하세요. 모든 메서드에 대해 [mods API 메서드](/docs/ko/plugins/mods/reference#mods-api-methods)를 참조하거나 [빌드용 타입](/docs/ko/plugins/mods/create#get-the-types-for-your-build)을 읽으세요.

13<h2 id="add-a-command-or-a-tool">

14 명령어 또는 도구 추가하기

15</h2>

17mod는 사용자가 실행할 명령어와 Claude가 호출할 도구를 추가할 수 있습니다. 둘 다 [`session.start`](/docs/ko/plugins/mods/reference#session) hook에 등록하세요. Claude Code는 첫 번째 프롬프트 전에 해당 hook을 기다리므로, 등록한 것은 첫 번째 턴부터 사용 가능합니다.

19<h3 id="add-a-command">

20 명령어 추가하기

21</h3>

23명령어는 사용자용입니다. 등록한 후 해당 이름에 대해 [`command.run`](/docs/ko/plugins/mods/reference#commands-and-configuration)을 처리하세요. 이 예제는 선택적 일 수를 받는 `/standup` 명령어를 추가합니다:

25```javascript theme={null}

26on('session.start', async ($, e, next) => {

27 // /standup을 명령어 목록에 추가하고, 사용자가 볼 수 있는 설명을 포함합니다

28 await $.command.register({ name: 'standup', description: 'Summarize what changed today', argumentHint: '[days]' })

29 return next(e)

30})

32// matcher는 hook을 /standup으로 제한하므로 다른 명령어는 도달하지 않습니다

33on('command.run', { command: 'standup' }, async ($, e) => {

34 // e.args는 명령어 이름 뒤에 입력된 텍스트이거나 빈 문자열입니다

35 return { text: 'Summary for the last ' + (e.args || '1') + ' day(s): ...' }

36})

37```

39세션이 시작된 후, `/standup`은 설명과 함께 `/`를 입력할 때 보이는 목록에 나타납니다. `argumentHint`는 명령어를 입력한 후 공백을 입력할 때 프롬프트 뒤에 표시되며, `/standup [days]`와 같이 표시됩니다. `/standup 3`을 실행하면, 두 번째 hook은 `Summary for the last 3 day(s): ...`을 반환하고, 트랜스크립트는 플러그인 이름 뒤에 해당 텍스트를 표시합니다. hook은 `next`를 호출하지 않습니다. 명령어는 당신의 동작 외에 다른 동작이 없기 때문입니다.

41반환하는 `text`는 트랜스크립트에 인쇄되고 Claude가 읽습니다. 아무것도 인쇄하지 않으려면, [pane](/docs/ko/plugins/mods/interface#pick-where-to-draw)만 여는 명령어의 경우 `{}`를 반환하세요. Claude가 작업 중일 때 명령어를 실행하도록 하려면 등록에 `immediate: true`를 추가하세요.

43내장 명령어가 사용하지 않는 이름을 선택하세요. 세션에서 `/`를 입력하여 확인하세요. `$.command.register`는 사용 중인 이름에 대해 `"/focus" refused: it is the built-in /focus`와 같은 메시지와 함께 throw합니다. throw하는 hook은 건너뛰어지므로 해당 `session.start` hook의 나머지 부분도 실행되지 않습니다. 해당 hook에서 마지막에 명령어를 등록하거나 호출을 `try`와 `catch`로 래핑하세요.

45<h3 id="add-a-tool">

46 도구 추가하기

47</h3>

49도구는 Claude용입니다. 이름, Claude가 읽는 설명, 입력을 위한 JSON Schema로 등록하세요. Claude는 `mcp__`, 플러그인 이름, 두 개의 언더스코어, 등록한 이름으로 구성된 더 긴 이름 아래에서 이를 봅니다. [`tool.call`](/docs/ko/plugins/mods/events#guard-or-change-a-tool-call) hook에서 해당 전체 이름으로 필터링된 호출을 처리합니다. 이 예제는 `my-mod`라는 플러그인에서 `ticket`을 등록하므로 전체 이름은 `mcp__my-mod__ticket`입니다. Claude에게 이슈 추적기에서 티켓을 조회하는 도구를 제공합니다:

51```javascript theme={null}

52on('session.start', async ($, e, next) => {

53 await $.tool.register({

54 name: 'ticket',

55 // Claude는 이 설명에서 도구를 호출할 시점을 결정합니다

56 description: 'Look up a ticket by its id and return its title and status',

57 // Claude가 보내야 하는 인수: id라는 필수 문자열 하나

58 inputSchema: { type: 'object', properties: { id: { type: 'string' } }, required: ['id'] },

59 })

60 return next(e)

61})

63// 전체 도구 이름은 mcp__, 플러그인 이름, 등록한 이름입니다

64on('tool.call', { tool: 'mcp__my-mod__ticket' }, async ($, e) => {

65 // 도구의 인수는 e의 필드이므로 id는 e.id입니다

66 const response = await $.http.fetch('https://tickets.example.com/api/' + encodeURIComponent(e.id))

67 // 어느 쪽이든 결과를 반환하므로 Claude는 조회가 실패했을 때를 알 수 있습니다

68 return { result: response.ok ? response.text : 'Lookup failed with status ' + response.status }

69})

70```

72티켓에 대해 물으면, Claude는 `mcp__my-mod__ticket`을 해당 id로 호출할 수 있습니다. 두 번째 hook은 티켓을 가져오고 응답 본문을 반환하며, Claude는 이를 도구의 결과로 읽습니다. 서버가 오류 상태로 응답하면, Claude는 `Lookup failed with status`와 숫자를 읽습니다.

74<h2 id="call-a-model">

75 모델 호출하기

76</h2>

78mod는 텍스트 정렬 또는 요약과 같은 작은 작업을 위해 대화 외부에서 모델에 질문할 수 있습니다. `$.model.complete`는 세션의 자격 증명으로 모델에 하나의 프롬프트를 보내고 회신으로 해결됩니다. 대화 기록이 없습니다.

80이 hook은 [`command.run`](#add-a-command)으로 등록된 `/triage` 명령어에 답하여 작은 모델에 그 뒤에 입력된 텍스트에 레이블을 지정하도록 요청합니다:

82```javascript theme={null}

83on('command.run', { command: 'triage' }, async ($, e) => {

84 const r = await $.model.complete({

85 model: 'haiku',

86 // 시스템 프롬프트는 작업을 설정하고, 프롬프트는 레이블을 지정할 텍스트를 전달합니다

87 system: 'Reply with one word: bug, feature, or question.',

88 prompt: e.args,

89 // 한 단어는 적은 토큰이 필요하며, 호출은 15초 후 포기합니다

90 maxTokens: 20,

91 timeoutMs: 15000,

92 })

93 // r.text는 모델이 답변했을 때만 존재하므로 먼저 r.isAnswered를 확인하세요

94 const label = r.isAnswered ? r.text.trim() : 'unknown'

95 return { text: 'Label: ' + label }

96})

97```

99`/triage the export button does nothing`을 실행하면, mod는 해당 텍스트를 모델로 보내고 `Label: bug`와 같은 답변을 인쇄합니다. Claude의 대화는 요청의 일부가 아닙니다. 모델이 답변하지 않으면 레이블은 `unknown`입니다.

100

101Claude API 실패는 호출을 거부하지 않으므로 `r.isAnswered`를 확인하고, `false`일 때 `r.reason`을 읽으세요. 호출은 Claude Code가 보내지 않을 요청(예: 조직이 차단한 모델)에 대해서만 거부합니다. [빌드용 타입](/docs/ko/plugins/mods/create#get-the-types-for-your-build)은 `effort`와 같은 다른 옵션을 나열하고, [제한](/docs/ko/plugins/mods/reference#limits)은 `maxTokens` 기본값을 제공합니다.

102

103`$.model.fork({ prompt })`는 대신 현재 대화에 대해 한 가지 질문을 하며, 동일한 모델과 시스템 프롬프트를 사용하므로 Claude API는 대부분을 프롬프트 캐시에서 제공합니다.

104

105이러한 호출은 사용자의 플랜 또는 API 키를 사용합니다.

106

107<h2 id="run-work-in-the-background">

108 백그라운드에서 작업 실행하기

109</h2>

110

111한 이벤트를 초과하는 작업(예: 1분마다 무언가를 확인)은 `session.start`에서 시작하는 타이머에서 실행됩니다. hook 자체는 하나의 이벤트에 대해 실행되며 자체 실행 시간 제한은 10초입니다. `next` 또는 mods API 호출에 소비된 시간은 계산되지 않습니다. `$.clock.sleep` 제외. `$.clock.every` 및 `$.clock.after`는 `setInterval` 및 `setTimeout`을 대신하며, 지연은 밀리초 단위입니다: `$.clock.after(5000, fn)`은 지금부터 5초 후에 `fn`을 한 번 호출합니다. 각각은 `cancel()` 메서드가 있는 타이머를 반환하고, `await $.clock.now()`는 밀리초 단위의 시간을 제공합니다.

112

113이 hook은 1분마다 pull request의 확인을 조회하고 프롬프트 아래에 결과를 표시합니다. `summarize`는 명령어의 JSON 출력을 몇 단어로 변환하는 자신의 함수입니다:

114

115```javascript theme={null}

116on('session.start', async ($, e, next) => {

117 // 60,000밀리초마다 함수를 호출하며, 지금부터 1분 후에 시작합니다

118 $.clock.every(60_000, async () => {

119 const status = await $.process.run(['gh', 'pr', 'checks', '--json', 'state'])

120 // 프롬프트 아래의 줄을 최신 요약으로 바꿉니다

121 $.ui.status('checks: ' + summarize(status.stdout))

122 })

123 // 타이머를 기다리지 않고 반환하므로 세션이 바로 시작됩니다

124 return next(e)

125})

126```

127

128세션은 평소대로 시작됩니다. 1분 후, 프롬프트 아래에 `⚠`, mod의 이름, 그리고 `checks:`와 요약이 있는 줄이 나타납니다. 그 후 1분마다 교체됩니다. 타이머의 콜백은 모든 이벤트 외부에서 실행되므로 턴 사이에 계속 실행되고 턴을 시작하지 않습니다. 콜백이 throw하면, 오류는 [디버그 로그](/docs/ko/plugins/mods/troubleshoot#read-the-debug-log)로 이동하고 타이머는 다음 간격에 다시 실행됩니다.

129

130<h3 id="show-something-without-starting-a-turn">

131 턴을 시작하지 않고 무언가 표시하기

132</h3>

133

134백그라운드 작업은 턴을 시작하지 않고 사용자에게 무언가를 표시할 수 있습니다. 이러한 각 호출은 다른 위치에 텍스트를 배치합니다:

135

136| 호출 | 사용자가 보는 것 |

137| :- | :- |

138| `$.ui.status(text)` | 변경할 때까지 프롬프트 아래에 남아있는 한 줄입니다. `⚠`와 mod의 이름으로 시작하며, `⚠ my-mod: checks: 3 passing`과 같습니다. |

139| `$.ui.toast(text)` | 오른쪽 상단의 작은 상자이며, mod의 이름이 텍스트 위에 있고 몇 초 후 사라집니다 |

140| `$.ui.log(text)` | Claude가 읽지 않는 트랜스크립트의 흐릿한 줄입니다. `●`과 mod의 이름으로 시작하며, `● my-mod: build finished`와 같습니다. |

141

142<h3 id="start-a-turn-from-a-background-job">

143 백그라운드 작업에서 턴 시작하기

144</h3>

145

146백그라운드 작업이 Claude의 주의가 필요한 것을 발견하면, `$.prompt.submit({ text })`로 프롬프트를 제출하여 턴을 시작할 수 있습니다. Claude는 발신자로 mod의 이름을 지정하는 문장 뒤의 텍스트를 읽습니다. 해당 문장 없이 사용자 자신의 말로 보내려면 `asUser: true`를 추가하세요. 호출은 세션이 유휴 상태가 될 때까지 기다린 후 새 턴을 시작합니다. 해당 턴이 시작될 때 해결되므로 Claude가 작업 중일 때 실행되는 핸들러에서 `await`하지 마세요.

147

148<h3 id="stop-background-work">

149 백그라운드 작업 중지하기

150</h3>

151

152백그라운드 작업은 두 가지 방법으로 중지됩니다. 모듈이 다시 로드되면 타이머가 중지됩니다. hook 내의 장기 실행 작업의 경우, [`next.signal`](/docs/ko/plugins/mods/reference#the-hook-function)은 hook이 처리하는 이벤트가 중단될 때(예: 사용자가 중단할 때) 중단되는 `AbortSignal`이므로 장기 실행 항목에 전달하세요.

153

154<h2 id="send-and-receive-messages-between-sessions">

155 세션 간 메시지 보내고 받기

156</h2>

157

158mod는 다른 세션 또는 이 세션의 subagent 중 하나에 일반 텍스트 메시지를 보낼 수 있으며, 도착하고 떠나는 메시지를 관찰할 수 있습니다. `$.session.send({ to, text })`는 하나를 보내며, SendMessage 도구가 만드는 것과 동일한 전달입니다. `to`는 세션의 경우 `{ sessionId }`, `$.agent.list()`의 subagent의 경우 `{ agentId }`, 또는 수신한 메시지가 온 문자열 주소입니다. 호출은 메시지가 큐에 들어가면 `{ isDelivered: true }`로 해결됩니다. 아무것도 전달되지 않으면 `{ isDelivered: false, reason }`으로 해결되며, `reason`은 이유를 설명합니다.

159

160이 hook은 [`command.run`](#add-a-command)으로 등록된 `/ping` 명령어에 답하여 그 뒤에 입력한 id의 세션에 상태를 요청합니다:

161

162```javascript theme={null}

163on('command.run', { command: 'ping' }, async ($, e) => {

164 // e.args는 /ping 뒤에 입력된 세션 id입니다

165 const sent = await $.session.send({ to: { sessionId: e.args }, text: 'Status? One line.' })

166 // 호출은 어느 쪽이든 해결되므로 isDelivered를 확인하여 무슨 일이 일어났는지 알아봅니다

167 if (!sent.isDelivered) $.ui.toast('Not delivered: ' + sent.reason)

168 // 빈 결과는 이 세션의 트랜스크립트에 아무것도 인쇄하지 않습니다

169 return {}

170})

171```

172

173메시지가 큐에 들어가면 세션에 아무것도 나타나지 않으며, 다른 세션의 Claude는 `Status? One line.`을 읽습니다. 아무것도 전달되지 않으면, 오른쪽 상단의 작은 상자가 이유를 제공하고 몇 초 후 사라집니다.

174

175두 이벤트를 통해 mod는 메시지를 관찰할 수 있습니다. 두 이벤트 모두에서 `next(e)`를 반환하여 각 메시지를 변경되지 않은 상태로 전달합니다:

176

177| 이벤트 | 발생 시점 | 유용한 필드 |

178| :- | :- | :- |

179| `session.receive` | 메시지가 이 세션에 도착하며, Claude가 읽기 전입니다 | `e.text`, 및 `e.origin.kind`(예: 다른 세션 또는 agent의 경우 `peer` 또는 `peer-send-message`, `task-notification`, 또는 `scheduled-trigger`). Claude에서 메시지를 유지하려면 `{ consumed: reason }`을 반환합니다. |

180| `session.send` | 메시지가 SendMessage 도구 또는 mod에서 떠나려고 합니다 | `e.to`, `e.text`, 및 `e.origin.kind`(이는 `model` 또는 `plugin`입니다) |

181

182[인바운드 메시지를 거부](/docs/ko/cross-session-messaging#control-inbound-messages)하도록 설정된 세션은 `session.receive`가 발생하기 전에 메시지를 거부하므로 hook은 이를 보지 않습니다. 승인을 위해 보류 중인 메시지는 먼저 hook에 도달하므로 mod는 아직 승인하지 않은 메시지를 읽을 수 있습니다. hook의 `next(e)`는 메시지가 전달되지 않으면 거부합니다.

183

184수신한 메시지의 발신자 이름은 발신자가 작성한 것이므로 이를 기반으로 결정하지 마세요.

185

186<h2 id="reach-files-processes-and-the-network">

187 파일, 프로세스 및 네트워크에 접근하기

188</h2>

189

190mod는 Claude Code를 실행하는 사용자와 동일한 권한으로 파일 시스템, 프로세스 및 네트워크에 접근합니다. hooks 모듈 자체는 Node.js API, `setTimeout`과 같은 타이머 전역, 자체 네트워크 또는 파일 접근이 없습니다. `URL`, `TextEncoder`, `AbortController`, `crypto.subtle`과 같은 표준 JavaScript 및 웹 API를 사용할 수 있습니다. 아래의 각 네임스페이스는 한 종류의 접근을 다룹니다:

191

192| 네임스페이스 | 수행하는 작업 |

193| :- | :- |

194| `$.fs` | `read(path)`, `write(path, text)`, `exists(path)`, `stat(path)`, 및 `list(path)`는 파일 및 디렉토리에서 작동합니다 |

195| `$.process` | `run(['git', 'status'])`는 명령어를 시작하고 종료될 때 해결됩니다. `spawn`은 장기 실행 명령어의 출력을 스트리밍합니다. |

196| `$.http` | `http` 또는 `https`를 통한 `fetch(url, init)`. 본문이 읽혀지면 `{ status, ok, headers, text }`로 해결됩니다. |

197| `$.store` | 플러그인 자신의 JSON 키-값 저장소이며, 세션 간에 유지됩니다 |

198| `$.env` | 환경 변수를 `get` 및 `set`합니다. 이름을 리터럴 문자열로 작성하세요. |

199| `$.settings` | 설정 파일 및 관리 정책이 보유한 것을 `read`합니다 |

200| `$.session` | `messages()`는 트랜스크립트를 `{ role, text, toolUses }` 목록으로 반환합니다. 또한 작업 디렉토리, 모델 등입니다. [`usage()`](/docs/ko/plugins/mods/reference#mods-api-methods)는 컨텍스트 윈도우 사용 및 플랜 제한을 반환합니다. |

201| `$.mcp` | 연결된 MCP 서버에서 도구를 `call`합니다 |

202

203파일 및 프로세스에는 자체 규칙이 몇 가지 있습니다:

204

205* **경로**: 상대 경로는 세션의 작업 디렉토리 아래에 있습니다

206* **`$.fs.list`**: 한 디렉토리의 항목을 `{ name, kind, size, isLink }`로 반환하며 하위 디렉토리로 내려가지 않습니다

207* **`$.process.run`**: 인수 목록을 받으며 shell을 사용하지 않습니다. 종료 코드에 관계없이 `{ exitCode, stdout, stderr }`로 해결됩니다. 프로그램을 시작할 수 없거나 기본값인 30초의 타임아웃에서 여전히 실행 중이면 거부하므로 `try`와 `catch`로 래핑하세요.

208

209이러한 호출 각각은 그 자체로 이벤트이며, `$.fs.read`의 경우 `fs.read`와 같이 `$.` 없이 네임스페이스 및 메서드로 이름이 지정됩니다. [체인의 앞에 있는](/docs/ko/plugins/mods/events#the-order-mods-run-in) mod는 호출을 관찰, 다시 작성 또는 거부할 수 있으며, 이것이 조직이 mod가 도달하는 것을 제한하는 방법입니다.

210

211<h2 id="next-steps">

212 다음 단계

213</h2>

214

215* [이벤트에 반응하기](/docs/ko/plugins/mods/events): hook 도구 호출, 프롬프트 및 턴

216* [인터페이스에 그리기](/docs/ko/plugins/mods/interface): mod가 수집한 것을 pane 또는 프롬프트 위에 표시합니다

217* [mod 테스트하기](/docs/ko/plugins/mods/test): 테스트에서 이러한 호출 중 하나를 stub합니다

218* [Mods 참조](/docs/ko/plugins/mods/reference): 모든 이벤트, 모든 mods API 메서드 및 제한

plugins/mods/create.md +395 −0 created

Details

1> ## Documentation Index

2> 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.

5# 모드 만들기

7> Claude가 설명으로부터 Claude Code 모드를 작성하도록 하거나, 도구 호출을 세고 명령을 추가하는 모드를 직접 작성하세요. 다시 로드 및 검증 루프를 배웁니다.

9모드는 Claude Code [플러그인](/docs/ko/plugins/overview)으로, 이벤트가 발생할 때 Claude Code가 호출하는 함수를 포함한 hooks 모듈이라는 항목 파일을 가집니다. 이는 JavaScript 또는 TypeScript 파일입니다. 모드를 만드는 방법은 두 가지입니다:

11* **Claude에게 작성하도록 요청**: Claude Code 세션에서 [원하는 것을 설명](#ask-claude-for-a-mod)하세요

12* **직접 작성**: [튜토리얼을 따르세요](#write-a-mod-yourself) 모드의 코드가 어떻게 작동하는지 배우세요. Node.js, 번들러 또는 빌드 단계가 필요하지 않습니다. Claude Code는 `.js` 및 `.ts` 파일을 직접 로드하기 때문입니다.

14모드가 올바른 도구인지 아직 결정하지 못했다면, 먼저 [개요의 비교](/docs/ko/plugins/mods/overview#compare-mods-settings-hooks-skills-and-mcp-servers)를 읽으세요.

16<Note>

17 모드는 Claude Code v2.1.287 이상이 필요합니다. 셸에서 `claude --version`을 실행하여 확인하세요. 모드가 로드될 수 있는지 확인하려면 [모드가 로드될 수 있는지 확인](/docs/ko/plugins/mods/troubleshoot#check-whether-mods-can-load)을 참조하세요.

18</Note>

20<h2 id="ask-claude-for-a-mod">

21 Claude에게 모드 작성 요청

22</h2>

24대화형 Claude Code 세션에서 원하는 모드를 설명하면 Claude가 작성합니다. Claude는 `plugin-authoring`이라는 내장 [스킬](/docs/ko/skills)에서 작동하며, 이는 모드를 작성할 위치, 버전이 가진 이벤트 및 메서드, 모드가 로드되는 방식을 알려줍니다. Claude는 모드를 요청할 때 스킬을 로드할 수 있거나, Claude Code 프롬프트에서 `/plugin-authoring`을 실행하여 직접 로드할 수 있습니다.

26모드는 승인하면 실행됩니다. 단, [Claude가 작성한 모드가 로드될 수 없는 세션](#sessions-that-skip-the-approval)은 제외됩니다.

28<Steps>

29 <Step title="모드 설명">

30 자신의 말로 모드를 요청하세요. 예를 들어 `현재 git 브랜치를 프롬프트 위에 표시하는 모드를 만들어`라고 할 수 있습니다. Claude는 세션의 모드 폴더에 있는 자신의 디렉토리에 모드를 작성합니다. 이는 `~/.claude/dev-mods/` 다음에 세션의 ID가 옵니다. 모드의 전체 경로는 `~/.claude/dev-mods/3f2a9c1e-5b7d-4e8a-9c21-6d0f4b8a7e13/git-branch/`와 같습니다.

32 <Note>

33 `default` 및 `acceptEdits` [권한 모드](/docs/ko/permission-modes#protected-paths)에서 Claude Code는 Claude가 모드의 각 파일을 생성하기 전에 요청합니다. `~/.claude`는 보호된 경로이기 때문입니다. 각 파일이 나타나면 승인하세요.

34 </Note>

35 </Step>

37 <Step title="모드 승인">

38 Claude가 첫 번째 파일을 저장하면 Claude Code는 세션에 대해 핫 리로딩을 활성화할지 묻습니다. 핫 리로딩은 이 세션에서 Claude가 작성한 모드를 실행하고 나중에 변경 사항을 선택합니다.

40 다음 중 하나를 선택하세요:

42 * **이 세션에 대해 활성화**: 세션의 모드 폴더에 있는 모드는 턴이 끝날 때 로드되고, 변경 사항이 있는 각 턴의 끝에 다시 로드됩니다. 답변은 세션 동안 지속되며, 재개한 후에도 지속됩니다.

43 * **지금은 아님**: 지금은 아무것도 로드되지 않습니다. 파일은 Claude가 작성한 위치에 남아 있으며, 모드는 해당 세션이 다음에 시작될 때 로드됩니다. 모드가 로드되지 않도록 하려면 해당 디렉토리를 삭제하세요.

44 </Step>

46 <Step title="모드가 로드되었는지 확인">

47 Claude Code 프롬프트에서 `/plugin`을 실행하고 **Installed** 탭이 선택될 때까지 Tab을 누르세요. 모드가 나열되며, 여기서 끌 수 있습니다.

48 </Step>

50 <Step title="모드 시도">

51 요청한 것을 사용하세요. 예제 프롬프트의 경우 현재 브랜치 이름이 프롬프트 상자 위에 나타납니다. 모드가 원하는 작업을 수행하지 않으면 Claude에게 변경할 사항을 알려주세요. 모드는 파일을 변경하는 각 턴의 끝에 다시 로드되므로 Claude가 완료되는 즉시 변경 사항을 시도할 수 있습니다.

52 </Step>

53</Steps>

55<h3 id="use-the-mod-in-other-sessions">

56 다른 세션에서 모드 사용

57</h3>

59Claude가 작성한 모드는 모드를 만든 세션에서만 로드되며, Claude Code는 [`cleanupPeriodDays`](/docs/ko/settings-reference#cleanupperioddays)보다 오래되면 해당 세션의 모드 폴더를 삭제합니다. 모드를 유지하려면 모드 폴더에서 디렉토리를 `~/mods/git-branch`와 같은 자신의 위치로 복사하세요. 그런 다음 로드 방법을 선택하세요:

61* **시작하는 세션에서**: 셸에서 `claude --plugin-dir ~/mods/git-branch`를 실행하세요

62* **다른 사람들을 위해**: [마켓플레이스에 추가](#share-your-mod)하여 설치할 수 있도록 하세요

64<h3 id="sessions-that-skip-the-approval">

65 Claude가 작성한 모드가 로드될 수 없는 세션

66</h3>

68Claude가 작성한 모드는 승인 후에만 로드되며, 모드가 실행될 수 있는 신뢰할 수 있는 작업 공간에서만 로드됩니다. 이 세션에서는 로드되지 않습니다:

70* **승인할 사람이 없음**: `claude -p` 실행 또는 [`dontAsk` 모드](/docs/ko/permission-modes)와 같이 세션이 프롬프트를 표시할 수 없습니다

71* **작업 공간을 신뢰하지 않음**: 디렉토리에 대한 신뢰 프롬프트를 수락하지 않았습니다

72* **모드가 중지됨**: `--safe-mode` 또는 `--bare`로 시작했거나, `disableAllHooks`를 설정했거나, 조직의 [관리 설정이 차단](/docs/ko/plugins/mods/admin#choose-how-much-to-allow)했습니다

74<h2 id="write-a-mod-yourself">

75 모드 직접 작성

76</h2>

78이 튜토리얼에서는 Claude가 수행하는 도구 호출을 세고, Claude가 작동하는 동안 스피너 옆에 개수를 표시하고, 개수를 인쇄하는 `/tally` 명령을 추가하는 `first-mod`라는 모드를 빌드합니다. 그런 다음 Claude Code가 모드 옆에 작성한 타입 선언을 읽고 `claude plugin validate`를 실행합니다. 함께 버전이 제공하는 이벤트 및 메서드와 Claude Code가 코드에서 읽는 것을 보여줍니다.

80이 녹화는 완성된 모드를 보여줍니다. 스피너는 도구 호출을 세고, `/tally`는 개수를 인쇄하며, 코드 편집은 세션이 실행되는 동안 적용됩니다:

82<Frame>

83 <video autoPlay muted loop playsInline controls className="w-full dark:hidden" src="https://mintcdn.com/claude-code/dgiVO_Od1X1faduV/images/mods-first-mod-light.mp4?fit=max&auto=format&n=dgiVO_Od1X1faduV&q=85&s=eb561134afa90375777408453ba51c77" aria-label="Claude Code 세션에서 '여기 파일을 나열하고 README를 읽어'라는 프롬프트가 입력되고 전송됩니다. 스피너는 '생각 중 · 도구 호출: 1'을 읽고 Claude가 작동하면서 개수가 증가합니다. /tally 명령은 'first-mod: Claude가 이 모드가 로드된 이후 3개의 도구 호출을 했습니다'를 인쇄합니다. 한 줄은 first-mod가 다시 로드되었고 네 개의 hooks를 나열합니다. 다음 프롬프트에서 스피너는 '생각 중 · 사용된 도구: 1'을 읽습니다." data-path="images/mods-first-mod-light.mp4" />

85 <video autoPlay muted loop playsInline controls className="w-full hidden dark:block" src="https://mintcdn.com/claude-code/dgiVO_Od1X1faduV/images/mods-first-mod-dark.mp4?fit=max&auto=format&n=dgiVO_Od1X1faduV&q=85&s=09779dadc7ef66c2b1e2da0c2e31ac72" aria-label="Claude Code 세션에서 '여기 파일을 나열하고 README를 읽어'라는 프롬프트가 입력되고 전송됩니다. 스피너는 '생각 중 · 도구 호출: 1'을 읽고 Claude가 작동하면서 개수가 증가합니다. /tally 명령은 'first-mod: Claude가 이 모드가 로드된 이후 3개의 도구 호출을 했습니다'를 인쇄합니다. 한 줄은 first-mod가 다시 로드되었고 네 개의 hooks를 나열합니다. 다음 프롬프트에서 스피너는 '생각 중 · 사용된 도구: 1'을 읽습니다." data-path="images/mods-first-mod-dark.mp4" />

86</Frame>

88세 개의 파일을 작성합니다:

90```text theme={null}

91first-mod/

92├── .claude-plugin/

93│ └── plugin.json

94└── hooks/

95 ├── hooks.json

96 └── register.js

97```

99* **`plugin.json`**: 플러그인의 [매니페스트](/docs/ko/plugins/manifest-reference)

100* **`hooks.json`**: [코드 파일을 가리킵니다](/docs/ko/plugins/mods/reference#files)

101* **`register.js`**: 코드, hooks 모듈이라고 불립니다

102

103<Steps>

104 <Step title="플러그인 디렉토리 생성">

105 파일을 보관할 두 디렉토리를 생성하세요:

106

107 <Tabs>

108 <Tab title="Bash or Zsh">

109 ```bash theme={null}

110 mkdir -p first-mod/.claude-plugin first-mod/hooks

111 ```

112 </Tab>

113

114 <Tab title="PowerShell">

115 ```powershell theme={null}

116 New-Item -ItemType Directory -Force first-mod\.claude-plugin, first-mod\hooks

117 ```

118 </Tab>

119 </Tabs>

120 </Step>

121

122 <Step title="매니페스트 작성">

123 모드는 플러그인이며, 모드는 [매니페스트](/docs/ko/plugins/manifest-reference)가 필요합니다. 이 모드의 매니페스트에는 특별한 필드가 없습니다. 이를 `first-mod/.claude-plugin/plugin.json`으로 저장하세요:

124

125 ```json first-mod/.claude-plugin/plugin.json theme={null}

126 {

127 "name": "first-mod",

128 "version": "0.1.0",

129 "description": "Counts Claude's tool calls, shows the count beside the spinner, and adds a /tally command",

130 "author": { "name": "Your Name" }

131 }

132 ```

133 </Step>

134

135 <Step title="Claude Code에 코드 위치 알리기">

136 Claude Code가 플러그인을 로드할 때, 플러그인의 `hooks/hooks.json`을 읽습니다. 해당 파일의 `modules` 키는 코드의 경로를 제공하며, 이를 가지는 것이 플러그인을 모드로 만드는 것입니다. 한 경로를 나열하세요. `hooks.json`에 상대적입니다. 여기서는 다음 단계에서 작성할 `register.js`를 가리킵니다.

137

138 이를 `first-mod/hooks/hooks.json`으로 저장하세요:

139

140 ```json first-mod/hooks/hooks.json theme={null}

141 {

142 "description": "The first-mod hooks module",

143 "modules": ["./register.js"]

144 }

145 ```

146 </Step>

147

148 <Step title="코드 작성">

149 이 파일은 모드의 코드이며, hooks 모듈이라고 불립니다. 모드가 로드될 때, Claude Code는 파일이 내보내는 `register` 함수를 호출하고 [`on`](/docs/ko/plugins/mods/reference#the-hook-function)이라는 함수를 전달합니다. `on`에 대한 각 호출은 이벤트 핸들러(hook이라고 불림)를 이름이 지정한 이벤트에 등록합니다.

150

151 이를 `first-mod/hooks/register.js`로 저장하세요:

152

153 ```javascript first-mod/hooks/register.js theme={null}

154 // The count, shared by the hooks below

155 let calls = 0

156

157 // Claude Code calls this once when the mod loads

158 export function register(on) {

159 // Runs when the session starts, before your first prompt

160 on('session.start', async ($, e, next) => {

161 // Add the /tally command

162 await $.command.register({

163 name: 'tally',

164 description: 'Show how many tool calls Claude has made',

165 })

166 // Let the session start as usual

167 return next(e)

168 })

169

170 // Runs each time Claude is about to use a tool

171 on('tool.call', async ($, e, next) => {

172 calls += 1

173 // Ask Claude Code to draw the interface again, so the new count shows

174 $.ui.invalidate('ui.render')

175 // Let the tool run as usual

176 return next(e)

177 })

178

179 // Runs when you type /tally, and only then, because of the matcher

180 on('command.run', { command: 'tally' }, async () => {

181 // The text to print in the transcript

182 return { text: 'Claude has made ' + calls + ' tool calls since this mod loaded' }

183 })

184

185 // Runs each time Claude Code draws the spinner

186 on('ui.render', { component: 'Spinner' }, async ($, e, next) => {

187 // Keep Claude Code's spinner, with the count added after its word

188 return next({ ...e, props: { ...e.props, suffix: ' · tool calls: ' + calls + '…' } })

189 })

190 }

191 ```

192

193 파일은 `calls`에 개수를 유지하고 네 개의 hooks를 등록합니다:

194

195 * \*\*[`session.start`](/docs/ko/plugins/mods/reference#session)\*\*는 세션이 시작될 때, 첫 번째 프롬프트 전에 실행되며, 모드가 다시 로드될 때마다 실행됩니다. Claude Code에 `/tally` 명령을 추가합니다.

196 * \*\*[`tool.call`](/docs/ko/plugins/mods/reference#tools)\*\*는 Claude가 도구를 사용하려고 할 때마다 실행됩니다. `calls`에 1을 더하고 Claude Code에 인터페이스를 다시 그리도록 요청합니다.

197 * \*\*[`command.run`](/docs/ko/plugins/mods/reference#commands-and-configuration)\*\*은 `/tally`를 입력할 때 실행됩니다. 인쇄할 텍스트를 반환합니다.

198 * \*\*[`ui.render`](/docs/ko/plugins/mods/reference#interface)\*\*는 Claude Code가 스피너를 그릴 때마다 실행됩니다. 스피너의 단어 뒤에 개수를 추가합니다.

199

200 [예제 모드가 어떻게 작동하는지](#how-the-example-mod-works)는 각 hook이 취하는 세 개의 인수와 각각이 반환하는 것을 설명합니다.

201 </Step>

202

203 <Step title="모드 로드">

204 `--plugin-dir` 플래그로 Claude Code를 시작하세요. 이는 설치하지 않고 한 세션에 대해 플러그인 디렉토리를 로드합니다:

205

206 ```bash theme={null}

207 claude --plugin-dir ./first-mod

208 ```

209 </Step>

210

211 <Step title="모드 시도">

212 Claude에게 몇 가지 도구 호출을 수행하는 작업을 요청하세요. 예를 들어 `여기 파일을 나열하고 README를 읽어`. Claude가 작동하는 동안 스피너의 단어 뒤에 증가하는 개수가 나타납니다. 예를 들어 `생각 중 · 도구 호출: 2…`. Claude가 완료되면 `/tally`를 입력하고 Enter를 누르세요. 트랜스크립트는 `first-mod: Claude가 이 모드가 로드된 이후 2개의 도구 호출을 했습니다`를 표시하며, 자신의 개수가 있습니다. Claude Code는 플러그인의 이름을 명령의 텍스트 앞에 놓습니다.

213

214 대화형 세션 없이 명령을 확인하려면 비대화형 모드에서 실행하세요:

215

216 ```bash theme={null}

217 claude -p "/tally" --plugin-dir ./first-mod

218 ```

219

220 ```text theme={null}

221 first-mod: Claude has made 0 tool calls since this mod loaded

222 ```

223

224 `/tally`가 명령 목록에 없으면 모듈이 로드되지 않았습니다. [모드가 아무것도 하지 않는 이유 찾기](/docs/ko/plugins/mods/troubleshoot#find-out-why-a-mod-does-nothing)를 참조하세요.

225 </Step>

226

227 <Step title="세션이 실행되는 동안 코드 변경">

228 세션을 열어 두세요. `register.js`에서 `ui.render` hook의 `' · tool calls: '`를 `' · tools used: '`로 변경하고 저장하세요. 강조된 줄이 변경되는 줄입니다:

229

230 ```javascript first-mod/hooks/register.js {4} theme={null}

231 // Runs each time Claude Code draws the spinner

232 on('ui.render', { component: 'Spinner' }, async ($, e, next) => {

233 // Keep Claude Code's spinner, with the count added after its word

234 return next({ ...e, props: { ...e.props, suffix: ' · tools used: ' + calls + '…' } })

235 })

236 ```

237

238 트랜스크립트의 한 줄은 `first-mod`가 다시 로드되었고 hooks를 나열하며, 다음 스피너는 새 텍스트를 사용합니다. 예를 들어 `생각 중 · 사용된 도구: 1…`.

239 </Step>

240</Steps>

241

242<h3 id="how-the-example-mod-works">

243 예제 모드가 어떻게 작동하는지

244</h3>

245

246`on`에 전달하는 각 함수는 hook이며, 이는 이벤트 핸들러입니다. Claude Code는 모든 hook에 동일한 세 개의 인수를 전달합니다:

247

248* **mods API**, `$`라고 이름 지어짐: 모드가 자신 외부에 도달하기 위해 호출할 수 있는 모든 메서드. `$.ui` 및 `$.command`와 같은 [네임스페이스](/docs/ko/plugins/mods/reference#mods-api-methods)에 있습니다

249* **이벤트**, `e`라고 이름 지어짐: [이벤트의 입력](/docs/ko/plugins/mods/reference#events). 도구 호출의 이름 및 인수와 같은 일반 데이터

250* **다음 핸들러**, [`next`](/docs/ko/plugins/mods/events#how-a-hook-handles-an-event)라고 이름 지어짐: 이벤트를 다른 모드로 전달한 다음 Claude Code의 자체 동작으로 전달하고 결과를 반환하는 함수

251

252`first-mod`의 hooks는 hook이 할 수 있는 세 가지 방식으로 이벤트를 처리합니다:

253

254* **관찰**: `session.start` hook은 명령을 등록하고, `tool.call` hook은 호출을 세고 다시 그리도록 요청합니다. 둘 다 `next(e)`를 반환하므로 세션이 시작되고 도구가 평소대로 실행됩니다.

255* **답변**: `command.run` hook은 자신의 결과를 반환하고 `next`를 호출하지 않습니다. `on`의 두 번째 인수인 `{ command: 'tally' }`는 [matcher](/docs/ko/plugins/mods/events#filter-which-events-a-hook-handles)라고 불리는 필터이므로 hook은 `/tally`에 대해서만 실행됩니다.

256* **다시 쓰기**: `ui.render` hook은 `e`의 복사본과 함께 `next`를 호출하며, 그 `suffix`는 개수를 보유하므로 Claude Code는 단어 뒤에 텍스트가 있는 일반적인 스피너를 그립니다

257

258Claude Code는 `--plugin-dir`으로 로드된 디렉토리를 감시하고 파일이 변경될 때 hooks 모듈을 핫 리로드합니다. 각 리로드는 `register`를 다시 실행하므로 `calls`는 `0`으로 돌아가고 `/tally`는 다시 세기 시작합니다. 리로드 전체에서 값을 유지하려면 [상태 유지](/docs/ko/plugins/mods/interface#keep-state)를 참조하세요.

259

260<h2 id="keep-working-on-a-mod">

261 모드에서 계속 작업하기

262</h2>

263

264모드가 로드되면 Claude가 변경하도록 할 수 있으며, 버전의 타입 정의에 대해 코드를 확인하고, Claude Code가 찾은 이벤트 및 호출을 나열하고, 테스트할 수 있습니다.

265

266<h3 id="change-a-mod-with-claude">

267 Claude로 모드 변경하기

268</h3>

269

270이미 가지고 있는 모드를 변경하려면 `--plugin-dir`이 모드의 디렉토리를 가리키도록 하여 세션을 시작하세요. 그러면 Claude가 작성한 것이 동일한 세션에서 로드됩니다:

271

272```bash theme={null}

273claude --plugin-dir ./first-mod

274```

275

276그런 다음 변경을 요청하세요. 예를 들어 `이 모드에 /tally-reset 명령을 추가하여 tally를 0으로 설정하세요`. Claude는 hooks 모듈을 편집하고, `claude plugin validate`를 실행하고, 보고하는 것을 수정합니다. `--plugin-dir`으로 로드하는 디렉토리는 [보호된 경로](/docs/ko/permission-modes#protected-paths)이므로 `default` 및 `acceptEdits` 모드에서 모드에 대한 Claude의 각 편집을 승인하도록 요청받습니다. 보호된 경로 테이블은 다른 권한 모드의 결과를 제공합니다.

277

278Claude가 턴 중에 저장한 파일은 턴이 끝날 때 다시 로드되므로 Claude가 완료되는 즉시 `/tally-reset`을 시도할 수 있습니다.

279

280<h3 id="get-the-types-for-your-build">

281 버전의 타입 정의 가져오기

282</h3>

283

284Claude Code가 `--plugin-dir`에 전달한 디렉토리에서 모드를 로드하거나 다시 로드할 때마다, 또는 [Claude가 작성한 모드](#ask-claude-for-a-mod)일 때마다, `.d.ts`로 끝나는 TypeScript 선언 파일을 모드의 디렉토리 내 `.claude-plugin/types/`에 작성합니다. 이들은 실행 중인 Claude Code 버전의 정확한 이벤트, mods API 메서드 및 요소를 설명하므로 편집기는 hooks를 자동 완성하고 타입 확인할 수 있습니다. 선언을 온라인으로 탐색하려면 Claude Code 저장소의 [`mods/types/claude-code.d.ts`](https://github.com/anthropics/claude-code/blob/main/mods/types/claude-code.d.ts)를 읽으세요. 첫 번째 줄은 이를 작성한 버전의 이름을 지정합니다. 디렉토리는 다음 파일을 보유합니다:

285

286| 경로 | 선언하는 것 |

287| :- | :- |

288| `claude-code/index.d.ts` | 모든 이벤트 및 입력과 결과, 모든 mods API 네임스페이스 및 메서드, 각 표면이 그릴 수 있는 요소 |

289| `claude-code-tools/index.d.ts` | 내장 도구의 입력 및 결과. `e.tool === 'Bash'` 확인이 `e`를 좁히도록 |

290| `claude-code-mcp/index.d.ts` | 모드에서 파일을 마지막으로 저장했을 때 연결된 MCP 도구의 입력 |

291| 플러그인 이름의 디렉토리에 있는 `index.d.ts` | 해당 플러그인이 mods API에 추가하는 것. `plugin.json`이 `dependencies` 아래에 나열하는 각 플러그인에 대해 하나의 디렉토리가 있습니다. |

292| `tsconfig.json` | hooks 모듈에 맞는 컴파일러 옵션 |

293

294모드에 자신의 `tsconfig.json`이 없으면 Claude Code는 생성된 것을 확장하는 모드의 루트에 하나를 추가하므로 편집기와 `tsc -p ./first-mod`는 추가 설정 없이 모드를 타입 확인합니다.

295

296이벤트 및 메서드는 릴리스 간에 변경될 수 있으므로 불일치할 때 이 페이지를 포함한 모든 페이지보다 이 파일을 신뢰하세요.

297

298`claude-code/index.d.ts`는 모든 mods API 메서드에 대한 주석 및 예제가 있는 빌드의 가장 완전한 참조입니다. 무언가를 찾으려면 파일에서 이름(예: `'tool.call'`)을 검색하세요.

299

300<h3 id="check-what-claude-code-reads-from-your-mod">

301 Claude Code가 모드에서 읽는 것 확인하기

302</h3>

303

304모드를 Claude Code가 보는 방식으로 보려면, 코드를 실행하거나 세션을 시작하지 않고 `claude plugin validate`를 사용하세요. 매니페스트를 확인하고 Claude Code가 모드를 로드할 때 실행하는 hooks 모듈의 소스에 대해 동일한 정적 분석을 실행합니다. 셸에서 모드의 디렉토리에서 실행하세요:

305

306```bash theme={null}

307claude plugin validate ./first-mod

308```

309

310`first-mod`의 경우 출력에는 다음 줄이 포함됩니다.

311

312```text theme={null}

313 ❯ ./register.js hooks: session.start, tool.call, command.run{command=tally}, ui.render{component=Spinner}

314 ❯ ./register.js calls: $.command.register, $.ui.invalidate

315

316✔ Validation passed

317```

318

319`hooks:` 줄은 모듈이 hook하는 이벤트를 나열하며, 각각은 중괄호에 필터가 있습니다. `calls:` 줄은 호출하는 모든 mods API 메서드를 나열합니다. 환경 변수를 읽거나 설정하는 모듈도 `env reads:` 및 `env writes:` 줄을 가지며, [`$.state`](/docs/ko/plugins/mods/interface#keep-state)를 사용하는 모듈은 `state reads:` 및 `state writes:` 줄을 가집니다.

320

321hook하려고 한 이벤트가 첫 번째 줄에서 누락되면 Claude Code도 해당 hook을 호출하지 않습니다. 일반적인 원인은 철자가 잘못된 이벤트 이름이며, 명령은 `"tool.calls" is not an event`와 같은 오류로 보고합니다.

322

323정적 분석이 모든 hook과 호출을 찾을 수 있도록 다음 규칙을 따르세요:

324

325* 각 mods API 호출을 완전히 철자하세요: `$`, 네임스페이스, 메서드. 예를 들어 `$.store.get('notes')`. `$`를 동일한 파일의 최상위 수준에서 선언된 함수로 전달할 수 있으며, `loadNotes`라는 함수의 경우 `calls:` 줄은 `$.store.get (via loadNotes)`를 읽습니다. `$`를 메서드, 함수 내부에서 정의된 함수, 또는 파일의 다른 부분에서 가져온 함수로 전달하면 검증이 실패합니다. [`$.state`](/docs/ko/plugins/mods/interface#keep-state)가 사용하는 `read` 및 `update` 함수는 이를 취할 수 있는 가져오기입니다. `$` 또는 네임스페이스 중 하나를 변수에 할당하거나, 구조 분해하거나, 계산된 이름으로 인덱싱하지 마세요. `const ui = $.ui`는 `$.ui is used as a value`로 실패합니다.

326* 각 `on` 호출에서 이벤트 이름을 문자열 리터럴로 작성하세요. 예를 들어 `'tool.call'`. 변수 또는 이름 목록에 대한 루프는 `the event name passed to on() is not a string literal`로 실패합니다.

327* `register` 내부에서 `on`이라는 두 번째 변수 또는 매개변수를 선언하지 마세요. 검증은 `"on" is declared again (shadowed)`로 실패합니다.

328* 상대 경로로 플러그인 디렉토리 내 파일에서만 가져오세요. 허용되는 유일한 베어 가져오기는 타입 및 몇 가지 도우미를 위한 `claude-code`입니다.

329* 파일의 맨 위에 `import` 선언을 사용하세요. 예를 들어 `import { name } from './file.js'`. 동적 `import()`는 `a dynamic import(); a hooks module imports its own files with an import declaration`로 실패합니다.

330* 모든 파일을 ES 모듈로 작성하세요. `import`를 사용하고 `require`는 사용하지 마세요. [참조](/docs/ko/plugins/mods/reference#files)는 Claude Code가 로드하는 파일 확장자를 나열합니다.

331

332<h3 id="test-the-mod">

333 모드 테스트하기

334</h3>

335

336모드에 대한 자동화된 테스트를 작성하고 세션, 로그인 또는 네트워크 없이 셸에서 `claude plugin test`로 실행할 수 있습니다. 테스트는 hooks가 처리하는 이벤트를 발생시키고 hooks가 수행한 작업을 확인합니다.

337

338이 테스트는 두 개의 도구 호출을 발생시키고, `/tally`를 실행하고, 회신이 둘 다 세는지 확인합니다. 이를 `first-mod/tests/first-mod.test.ts`로 저장하세요:

339

340```typescript first-mod/tests/first-mod.test.ts theme={null}

341import { expect, test } from 'claude-code/testing'

342

343test('/tally reports the tool calls the mod has seen', async ($, on) => {

344 // Answer each tool call in Claude Code's place, so no tool runs

345 on('tool.call', () => ({ result: 'ok' }))

346

347 // Raise two tool calls, which the mod's tool.call hook counts

348 await $.tool.call({ tool: 'Bash', command: 'ls' })

349 await $.tool.call({ tool: 'Read', file_path: 'README.md' })

350

351 // Run /tally and check the text its hook returns

352 const answer = await $.command.run({ command: 'tally', args: '' })

353 expect(answer.text).toBe('Claude has made 2 tool calls since this mod loaded')

354})

355```

356

357셸에서 `first-mod` 디렉토리에서 테스트를 실행하세요:

358

359```bash theme={null}

360claude plugin test

361```

362

363출력은 각 테스트와 통과 여부를 이름으로 지정하며, 실행 간에 다양한 타이밍이 있습니다:

364

365```text theme={null}

366tests/first-mod.test.ts:

367(pass) /tally reports the tool calls the mod has seen [22.87ms]

368

369 1 pass

370 0 fail

371Ran 1 test across 1 file. [0.19s]

372```

373

374[모드 테스트](/docs/ko/plugins/mods/test)는 모델 호출 또는 저장소를 스텁하고, 타이머 및 그리기를 테스트하는 것을 다룹니다.

375

376<h2 id="share-your-mod">

377 모드 공유

378</h2>

379

380모드는 플러그인이므로 매니페스트에서 버전을 지정하고 사람들은 `/plugin` 명령으로 설치하고 업데이트합니다. 다른 사람들에게 제공하려면 [마켓플레이스에 추가](/docs/ko/plugins/publish)하세요.

381

382그 전에 플러그인의 `name`을 확인하세요: `claude plugin validate`는 [Anthropic의 자체 것처럼 보이는](/docs/ko/plugins/manifest-reference#name) 이름(예: `claude-`로 시작하는 이름)을 실패합니다. 이벤트 및 메서드는 릴리스 간에 변경될 수 있으므로 README는 테스트한 Claude Code 버전을 말하는 곳입니다.

383

384설치된 복사본이 아닌 `--plugin-dir`이 있는 디렉토리에 대해 계속 개발하세요. Claude Code는 설치된 플러그인을 버전별로 캐시하므로 버전을 올리고 다시 설치할 때까지 편집 사항이 설치된 복사본에 도달하지 않습니다.

385

386<h2 id="next-steps">

387 다음 단계

388</h2>

389

390* [인터페이스에 그리기](/docs/ko/plugins/mods/interface): 창을 열고, 프롬프트 위에 그리고, 버튼 및 텍스트 필드 추가

391* [이벤트에 반응](/docs/ko/plugins/mods/events): 도구 호출, 프롬프트 및 턴 hook

392* [mods API 사용](/docs/ko/plugins/mods/api): 명령 및 도구 추가, 모델 호출, 타이머에서 작업 실행

393* [모드 테스트](/docs/ko/plugins/mods/test): Claude Code가 답변할 것을 스텁하고, 타이머 및 그리기 테스트

394* [모드 문제 해결](/docs/ko/plugins/mods/troubleshoot): 모드가 아무것도 하지 않는 이유 및 디버그 로그

395* [내장 모드의 소스 읽기](/docs/ko/plugins/mods/overview#read-the-source-of-built-in-mods): 완전한 플러그인. 각각 hooks 모듈 및 테스트 포함

plugins/mods/events.md +336 −0 created

Details

1> ## Documentation Index

2> 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.

5# 이벤트에 모드로 반응하기

7> 모드에서 Claude Code 이벤트 처리: 도구 호출, 프롬프트, 턴 관찰, 재작성 또는 응답, 훅이 처리하는 이벤트 필터링, 다른 모드 계획

9훅은 이벤트 핸들러입니다. Claude Code가 명명된 이벤트가 발생할 때 실행하는 함수입니다. Claude Code는 도구를 실행하거나, 프롬프트를 제출하거나, 모델에 요청을 보내거나, 세션을 시작하거나 종료할 때와 같이 행동하려고 할 때마다 이벤트를 발생시킵니다. 훅은 Claude Code가 행동하기 전에 실행되므로 이벤트를 관찰하거나, 재작성하거나, Claude Code를 대신하여 응답할 수 있습니다. [`on(eventName, handler)`](/docs/ko/plugins/mods/reference#the-hook-function)로 훅을 등록합니다.

11여기서 시작하기 전에 [첫 번째 모드를 빌드](/docs/ko/plugins/mods/create)하세요. 모든 이벤트와 정확한 필드는 [참조](/docs/ko/plugins/mods/reference#events)를 보거나 [빌드의 타입을 읽으세요](/docs/ko/plugins/mods/create#get-the-types-for-your-build).

13<h2 id="how-a-hook-handles-an-event">

14 훅이 이벤트를 처리하는 방법

15</h2>

17훅은 이벤트와 Claude Code가 그것에 대해 할 일 사이에 있으므로 이벤트를 관찰하거나, 재작성하거나, 직접 응답할 수 있습니다. 세 가지 인수를 받습니다: [mods API](/docs/ko/plugins/mods/api)를 `$`로, 이벤트를 `e`로, 다음 핸들러를 `next`로 받습니다. 이벤트의 핸들러들은 미들웨어 체인을 형성합니다. `next(e)`는 다음 핸들러를 호출하는데, 이는 다른 모드의 훅이거나 체인의 끝에서 Claude Code 자신의 동작이며, 결과로 해결됩니다. 훅이 `next`로 무엇을 하는지가 세 가지 중 어느 것을 하는지 결정합니다.

19<h3 id="observe-an-event">

20 이벤트 관찰하기

21</h3>

23이벤트를 변경하지 않고 관찰하려면 작업을 수행하고 `next(e)`를 반환합니다. 이 훅은 Claude가 사용하려고 하는 각 도구를 기록합니다:

25```javascript theme={null}

26on('tool.call', async ($, e, next) => {

27 // 도구가 실행되기 전에 실행됨

28 $.ui.log('Claude is about to use ' + e.tool)

29 // 이벤트를 변경하지 않고 전달

30 return next(e)

31})

32```

34각 도구가 실행되기 전에 `● my-mod: Claude is about to use Bash`와 같은 흐릿한 줄이 트랜스크립트에 나타나며, 여기서 `my-mod`는 플러그인의 이름입니다. 도구는 모드 없이 실행되는 것처럼 실행됩니다.

36이벤트 후에 행동하려면 `await next(e)`를 하고, 작업을 수행한 후 결과를 반환합니다. 이 훅은 각 도구가 실행된 후에 기록합니다:

38```javascript theme={null}

39on('tool.call', async ($, e, next) => {

40 // 도구를 실행하고 결과를 기다림

41 const result = await next(e)

42 // 도구가 실행된 후에 실행됨

43 $.ui.log(e.tool + ' finished')

44 // 결과를 변경하지 않고 반환

45 return result

46})

47```

49이제 줄은 각 도구가 완료된 후에 나타납니다. Claude는 훅이 `next(e)`가 해결된 것을 반환하기 때문에 어느 쪽이든 같은 결과를 읽습니다.

51<h3 id="rewrite-an-event">

52 이벤트 재작성하기

53</h3>

55Claude Code가 행동하는 것을 변경하려면, 예를 들어 프롬프트의 텍스트를 변경하려면 수정된 이벤트 복사본으로 `next`를 호출합니다. 이벤트 자체는 불변입니다: 모든 깊이에서 동결되어 있으며, 필드에 할당하면 오류가 발생합니다. 이 훅은 각 프롬프트를 전송하기 전에 트림합니다:

57```javascript theme={null}

58on('prompt.submit', async ($, e, next) => {

59 // 텍스트가 변경된 이벤트의 복사본을 전달

60 return next({ ...e, text: e.text.trim() })

61})

62```

64나중의 핸들러와 Claude Code는 트림된 프롬프트를 받고 원본을 절대 보지 않습니다. 결과를 변경할 수도 있습니다: `await next(e)`를 한 후 필드가 바뀐 결과의 복사본을 반환합니다.

66<h3 id="answer-an-event">

67 이벤트에 응답하기

68</h3>

70이벤트를 직접 처리하려면 `next`를 호출하지 않고 결과를 반환합니다. 이는 체인을 단락시키므로 나중의 모드와 Claude Code의 자신의 동작이 실행되지 않습니다. 이 훅은 모든 Bash 명령을 거부합니다:

72```javascript theme={null}

73on('tool.call', { tool: 'Bash' }, async () => {

74 // next를 호출하지 않으므로 명령이 실행되지 않음

75 return { deny: 'Bash is turned off in this project. Use the file tools.' }

76})

77```

79Claude가 Bash 명령을 시도할 때 명령이 실행되지 않으며, Claude는 `deny` 텍스트를 도구의 결과로 읽습니다. 각 이벤트는 자신의 결과 형태를 가지고 있으며, [이벤트 참조](/docs/ko/plugins/mods/reference#events)에 나열되어 있습니다.

81<h3 id="filter-which-events-a-hook-handles">

82 훅이 처리하는 이벤트 필터링하기

83</h3>

85훅을 일부 이벤트에만 실행하려면 `on`의 두 번째 인수로 필터를 전달합니다. Claude Code는 필터를 매처라고 부릅니다. 이는 필드가 이벤트의 필드와 비교되는 객체이며, 모든 필드가 일치할 때만 훅이 실행됩니다. 필드는 값, 허용된 값의 배열, 또는 정규 표현식일 수 있습니다.

87이 예제의 각 줄은 같은 함수 `hook`을 더 좁은 도구 호출 집합에 등록합니다:

89```javascript theme={null}

90// 문자열은 하나의 값과 일치: Bash 호출만

91on('tool.call', { tool: 'Bash' }, hook)

92// 배열은 그 안의 모든 값과 일치: Edit 호출과 Write 호출

93on('tool.call', { tool: ['Edit', 'Write'] }, hook)

94// 정규 표현식은 패턴으로 일치: 하나의 MCP 서버의 모든 도구

95on('tool.call', { tool: /^mcp__github__/ }, hook)

96```

98`hook`은 Bash, Edit, 또는 Write 호출에 대해 한 번씩 실행되며, 이름이 `mcp__github__`로 시작하는 도구에 대한 호출에 대해 한 번씩 실행됩니다. Read와 같은 다른 도구에 대한 호출은 세 가지 중 어느 것도 일치하지 않으므로 `hook`은 그것에 대해 실행되지 않습니다.

100이벤트 이름은 와일드카드일 수 있습니다. `'classic.*'`는 모든 [설정 훅 이벤트](#hook-the-settings-hook-events)와 일치합니다. `'*'`는 [텔레메트리 이벤트](/docs/ko/plugins/mods/reference#telemetry)를 제외한 모든 이벤트와 일치하며, 이는 이름으로 또는 `'telemetry.*'`로 훅합니다.

101

102각 이벤트를 매처당 한 번씩 등록합니다. 매처 없이 `session.start`에 대해 `on`을 두 번 호출하면 모듈이 `on("session.start") is registered twice without a matcher`로 로드되지 않습니다. 모드가 세션 시작 시 수행하는 모든 것을 하나의 훅에 넣으세요.

103

104<h2 id="hook-what-claude-is-doing">

105 Claude가 하는 일을 훅하기

106</h2>

107

108이 이벤트들을 훅하여 도구 호출, 프롬프트, 또는 턴이 발생할 때 보거나 변경합니다. 모든 이벤트와 훅이 반환할 수 있는 것은 [이벤트 참조](/docs/ko/plugins/mods/reference#events)를 보세요.

109

110<h3 id="guard-or-change-a-tool-call">

111 도구 호출 보호 또는 변경하기

112</h3>

113

114`tool.call` 훅은 Claude가 사용하려고 하는 각 도구를 보므로 호출을 거부하거나, 인수를 변경하거나, 통과시킬 수 있습니다. `tool.call`은 Claude Code가 도구를 실행하려고 할 때 발생하며, 서브에이전트가 만드는 호출과 MCP 도구에 대한 호출을 포함합니다. `e.tool`은 도구의 이름이고 도구의 인수는 `e`의 필드입니다. 예를 들어 Bash의 경우 `e.command`입니다. `next(e)`를 호출하면 Claude Code는 권한 확인을 실행한 후 도구를 실행합니다.

115

116이 훅은 강제 푸시하는 Bash 명령을 거부하고 Claude에게 이유를 알립니다:

117

118```javascript theme={null}

119// 매처는 훅을 Bash 호출로 제한하므로 e.command는 셸 명령

120on('tool.call', { tool: 'Bash' }, async ($, e, next) => {

121 if (/git push .*--force/.test(e.command)) {

122 // next를 호출하지 않고 반환하면 이벤트에 응답하므로 명령이 실행되지 않음

123 return { deny: 'Force pushes are not allowed in this repository. Push to a new branch instead.' }

124 }

125 // 다른 모든 명령은 권한 확인을 거쳐 Bash로 진행

126 return next(e)

127})

128```

129

130Claude가 `git push --force`를 시도할 때 명령이 실행되지 않으며 훅이 `next`를 호출하지 않기 때문에 권한 프롬프트가 나타나지 않습니다. Claude는 `deny` 텍스트를 도구의 결과로 읽으므로 Claude가 행동할 수 있는 지시로 작성하세요. 다른 모든 Bash 명령은 모드 없이 실행되는 것처럼 실행됩니다.

131

132도구가 실행된 후에 행동하려면 `await next(e)`를 하고, 작업을 수행한 후 `next`가 준 것을 반환합니다. 이 훅은 Claude가 변경하는 각 `.mdx` 파일을 [`$.ui.log`](/docs/ko/plugins/mods/api#show-something-without-starting-a-turn)로 기록하며, 이는 Claude가 읽지 않는 흐릿한 줄을 트랜스크립트에 추가합니다:

133

134```javascript theme={null}

135on('tool.call', { tool: ['Edit', 'Write'] }, async ($, e, next) => {

136 // 권한 확인과 도구를 기다리고 그들이 생산한 것을 유지

137 const result = await next(e)

138 // 거부된 호출은 { deny }로 돌아오고, 실패한 것은 isError가 설정됨

139 const changed = !result.deny && !result.isError

140 if (changed && e.file_path.endsWith('.mdx')) $.ui.log('Claude changed ' + e.file_path)

141 // 결과를 받은 대로 반환하므로 Claude는 도구가 반환한 것을 읽음

142 return result

143})

144```

145

146Claude가 `.mdx` 파일을 편집하거나 쓴 후 트랜스크립트의 흐릿한 줄이 파일의 이름을 지정합니다. 다른 종류의 파일이나 거부되거나 실패한 호출에 대해서는 아무것도 기록되지 않습니다. 훅이 받은 결과를 반환하기 때문에 호출에 대한 Claude의 보기는 변경되지 않습니다.

147

148호출을 변경하려면 변경된 인수를 `next`에 전달합니다. 호출을 다시 시도하려면 `next(e)`를 다시 호출합니다: 첫 번째 결과에서 `isError`를 보는 훅은 도구를 두 번째로 실행하고 그 결과를 반환할 수 있습니다. 호출에 직접 응답하려면 `next`를 호출하지 않고 `result` 필드가 있는 객체를 반환합니다. 예를 들어 `{ result: 'Skipped by my-mod' }`입니다. 그렇게 하면 권한 프롬프트가 나타나지 않으며 도구가 실행되지 않으므로 반환하는 결과가 Claude가 무슨 일이 일어났는지에 대해 배우는 모든 것입니다.

149

150조직의 [관리 설정](/docs/ko/server-managed-settings)의 훅은 모든 모드의 `tool.call` 훅 전에 실행되며, 그 중 하나의 블록은 최종입니다.

151

152<h4 id="hold-a-tool-call-until-the-user-decides">

153 사용자가 결정할 때까지 도구 호출 보류하기

154</h4>

155

156훅은 도구 호출을 일시 중지하고 진행하기 전에 사용자에게 무엇을 할지 물어볼 수 있습니다. `tool.call` 훅은 `next`를 호출하거나 반환하기 전에 `await`할 수 있으며, 도구 호출은 그때까지 보류됩니다. 사용자에게 질문을 하려면 `$.ui.ask`를 호출합니다. 이는 Claude가 당신에게 무언가를 물어보는 데 사용하는 대화 상자에서 번호가 매겨진 옵션 목록 위에 질문을 표시하고 사용자가 선택한 레이블로 해결됩니다. 옵션 후에 대화 상자는 다른 답변을 입력하기 위한 행과 **Chat about this** 행을 추가합니다.

157

158이 예제의 `RISKY` 패턴은 `rm -r`, `rm -rf`, `git reset --hard`, 그리고 `--force`가 있는 `git push`와 일치하며, `git push -f`와 같은 다른 철자는 놓칩니다. 이 모듈은 패턴과 일치하는 Bash 명령을 실행하기 전에 물어봅니다:

159

160```javascript theme={null}

161const RISKY = /\brm\s+-rf?\b|\bgit\s+reset\s+--hard\b|\bgit\s+push\b.*--force/

162

163export function register(on) {

164 on('tool.call', { tool: 'Bash' }, async ($, e, next) => {

165 // 질문 없이 다른 모든 명령을 통과시킴

166 if (!RISKY.test(e.command)) return next(e)

167 // 안전한 답변에서 시작하므로 아무도 답변하지 않는 질문은 명령을 거부

168 let answer = 'Refuse'

169 try {

170 // 도구 호출은 사용자가 두 레이블 중 하나를 선택할 때까지 여기서 기다림

171 answer = await $.ui.ask('Run this command? ' + e.command, ['Run it', 'Refuse'])

172 } catch {

173 // 사용자가 질문을 해제했거나 이것이 아무도 물어볼 사람이 없는 claude -p 실행

174 }

175 if (answer !== 'Run it') {

176 // next를 호출하지 않고 응답하므로 명령이 실행되지 않음

177 return { deny: 'The user declined this command. Ask before trying a different approach.' }

178 }

179 return next(e)

180 })

181}

182```

183

184Claude가 `rm -rf build`와 같은 명령을 시도할 때 질문이 명령과 함께 나타나고 명령은 답변을 기다립니다:

185

186* **사용자가 Run it을 선택**: 훅이 `next(e)`를 호출하고 일반적인 권한 확인이 여전히 그 후에 실행됩니다

187* **사용자가 Refuse를 선택**: 명령이 실행되지 않으며 Claude는 `deny` 텍스트를 읽습니다

188* **사용자가 답변을 입력**: `$.ui.ask`는 입력된 텍스트로 해결됩니다. 훅은 `Run it`과 비교하므로 다른 텍스트는 명령을 거부합니다.

189* **아무도 답변하지 않음**: `$.ui.ask`는 사용자가 질문을 해제하거나 **Chat about this**를 선택할 때 또는 `claude -p` 실행에서 거부하므로 `catch` 블록은 답변을 `Refuse`로 유지합니다

190

191`$.ui.ask`와 같은 mods API 호출 내에서 대기를 유지하세요. 이 시간은 훅의 [10초 시간 제한](/docs/ko/plugins/mods/reference#limits)에 포함되지 않기 때문입니다. 자신의 약속을 기다리는 데 소비된 시간은 포함됩니다. Claude Code는 시간 초과된 훅을 건너뛰므로 보류된 명령이 실행됩니다.

192

193<h3 id="rewrite-or-add-to-a-prompt">

194 프롬프트 재작성 또는 추가하기

195</h3>

196

197`prompt.submit` 훅은 턴이 시작되기 전에 각 프롬프트를 보므로 텍스트를 재작성하거나 추가할 수 있습니다. `e.text`는 입력된 것입니다.

198

199| 이것을 하려면 | 이것을 반환하세요 |

200| :- | :- |

201| 프롬프트를 재작성합니다. 트랜스크립트의 메시지는 새 텍스트를 표시합니다. | `next({ ...e, text: newText })` |

202| Claude만 읽는 텍스트를 프롬프트 후에 추가합니다 | `next({ ...e, context: [...(e.context ?? []), extraText] })` |

203| 프롬프트가 전송되지 않도록 중지합니다 | `{ drop: 'the reason' }` |

204

205이 훅은 프롬프트가 풀 요청을 언급할 때마다 현재 브랜치 이름을 Claude에게 추가합니다:

206

207```javascript theme={null}

208on('prompt.submit', async ($, e, next) => {

209 // 풀 요청을 언급하지 않는 프롬프트를 그대로 전달

210 if (!/\bPR\b|pull request/i.test(e.text)) return next(e)

211 const git = await $.process.run(['git', 'branch', '--show-current'])

212 // git 저장소 외부에서 명령이 실패하므로 추가할 브랜치가 없음

213 if (git.exitCode !== 0) return next(e)

214 // 이전 훅이 추가한 모든 컨텍스트를 유지하고 Claude를 위해 하나 더 추가

215 return next({ ...e, context: [...(e.context ?? []), 'Current branch: ' + git.stdout.trim()] })

216})

217```

218

219`open a PR for this change`와 같은 프롬프트를 보낼 때 메시지는 트랜스크립트에서 동일하게 보이며, Claude는 `Current branch: feature/auth`와 같은 줄도 그 후에 읽습니다. 풀 요청을 언급하지 않는 프롬프트는 변경되지 않고 통과하며 `git`은 실행되지 않습니다.

220

221[다른 이벤트](/docs/ko/plugins/mods/reference#prompts-and-what-claude-reads)는 Claude가 읽는 나머지를 다룹니다: 시스템 프롬프트의 각 섹션에 대한 `prompt.section`, 첫 번째 메시지와 함께 전송되는 컨텍스트에 대한 `prompt.context`, 그리고 스킬의 텍스트에 대한 `skill.prompt`. 이 훅의 텍스트가 요청 간에 변경되면 [프롬프트 캐시를 무효화합니다](/docs/ko/prompt-caching).

222

223<h3 id="follow-a-turn">

224 턴 따라가기

225</h3>

226

227턴은 Claude가 하나의 프롬프트에 응답하여 수행하는 모든 것입니다. `turn.start`, `turn.step`, 그리고 `turn.complete`를 훅하여 하나를 따라가세요:

228

229| 이벤트 | 언제 발생하는가 | 훅이 할 수 있는 것 |

230| :- | :- | :- |

231| `turn.start` | 턴이 시작됩니다 | 관찰합니다. `e.turnId`는 다른 두 이벤트에서 턴을 식별합니다. |

232| `turn.step` | Claude Code가 모델에 하나의 요청을 보내려고 합니다. 도구 호출이 있는 턴은 여러 개를 가집니다. `e.agentId`는 서브에이전트의 요청에 대해 설정됩니다. | 각 요청의 토큰 사용량을 읽고, `next({ ...e, model })`로 다른 모델에 보내거나, 모델을 호출하지 않고 응답합니다 |

233| `turn.complete` | 턴이 끝났으며, 사용자가 중단한 턴을 포함하며, 여기서 `e.isAborted`는 `true`입니다. `e.answer`는 Claude의 최종 텍스트이고, `e.durationMs`는 소요된 시간이며, `e.usage`는 턴의 토큰 합계입니다. 서브에이전트의 턴은 `e.agentId`가 설정된 상태로 발생합니다. | 관찰하거나, `{ text: 'Done in 12 seconds' }`와 같은 `text` 필드가 있는 객체를 반환하여 답변 아래에 줄을 표시합니다 |

234

235`turn.step` 훅을 비동기 생성기로 작성하세요. 이벤트가 스트림되기 때문입니다. `yield* next(e)`는 응답을 스트림할 때 전달하고 완료된 결과로 평가됩니다. 이 훅은 각 요청에서 Claude API가 [프롬프트 캐시](/docs/ko/prompt-caching)에서 제공한 양을 기록합니다:

236

237```javascript theme={null}

238// function*는 훅을 생성기로 만들어 응답을 조각별로 전달할 수 있음

239on('turn.step', async function* ($, e, next) {

240 // 요청을 보내고, 각 조각이 도착할 때 전달하고, 완료된 결과를 유지

241 const result = yield* next(e)

242 // 토큰 개수를 보고하지 않는 결과를 건너뜀

243 if (result.usage) {

244 $.ui.log('cache read ' + result.usage.cache_read_input_tokens + ' · wrote ' + result.usage.cache_creation_input_tokens)

245 }

246 // 결과를 변경하지 않고 반환하므로 턴이 평소대로 계속됨

247 return result

248})

249```

250

251Claude의 응답은 모드 없이 하는 것처럼 화면으로 스트림됩니다. 각 요청이 완료된 후 트랜스크립트의 흐릿한 줄이 캐시에서 읽은 토큰 수와 쓴 토큰 수를 제공합니다. 도구 호출이 있는 턴은 여러 요청을 가지므로 여러 줄을 추가합니다.

252

253`result.usage`는 Claude API가 요청에 대해 보고하는 네 가지 토큰 개수와 응답한 `model`을 보유합니다: `input_tokens`, `output_tokens`, `cache_read_input_tokens`, 그리고 `cache_creation_input_tokens`. 훅은 서브에이전트의 요청에 대해서도 실행되므로 주 대화만 원할 때 `e.agentId`를 확인하세요.

254

255<h3 id="hook-the-settings-hook-events">

256 설정 훅 이벤트 훅하기

257</h3>

258

259설정 훅은 설정 파일에서 구성하는 명령, HTTP, 프롬프트, 그리고 에이전트 훅입니다. 각 [설정 훅 이벤트](/docs/ko/hooks#hook-events), 예를 들어 `Stop`, `SessionEnd`, 또는 `PostToolUse`는 또한 `classic.` 다음에 설정 훅 이벤트의 이름이 오는 이벤트입니다. 예를 들어 `classic.Stop`. `e`는 설정 훅이 stdin에서 받는 JSON이며, `transcript_path`를 포함합니다.

260

261이 훅은 Claude가 응답을 마칠 때 발생하는 `Stop`을 사용하여 세션의 트랜스크립트가 저장되는 위치를 기록합니다:

262

263```javascript theme={null}

264on('classic.Stop', async ($, e, next) => {

265 // e는 설정 파일의 Stop 훅이 stdin에서 읽는 것과 같은 필드를 가짐

266 $.ui.log('Transcript saved at ' + e.transcript_path)

267 // 이벤트를 전달하므로 설정 파일의 Stop 훅이 여전히 실행됨

268 return next(e)

269})

270```

271

272Claude가 응답을 마칠 때마다 트랜스크립트의 흐릿한 줄이 트랜스크립트 파일의 경로를 제공합니다. 훅은 `next(e)`를 반환하므로 이벤트를 관찰하고 턴이 끝나는 방식에 대해 아무것도 변경하지 않습니다.

273

274<h2 id="run-alongside-other-mods">

275 다른 모드와 함께 실행

276</h2>

277

278여러 모드가 동일한 이벤트를 후킹할 수 있으며, 그 중 하나가 실패할 수 있습니다. 모드가 도구 호출을 차단하는 경우, 체인에서의 위치와 후크가 실패할 때 발생하는 상황을 확인하십시오.

279

280<h3 id="the-order-mods-run-in">

281 모드가 실행되는 순서

282</h3>

283

284동일한 이벤트의 후킹은 하나의 미들웨어 체인을 형성합니다. 각 모드의 `next`는 다음 모드의 후크를 호출하고, 마지막 `next`는 Claude Code의 자체 동작에 도달합니다. 첫 번째 모드는 가장 바깥쪽입니다. 즉, 다른 모드보다 먼저 이벤트를 보고 그 후에 결과를 보며, 다른 모드가 실행될지 여부를 결정합니다. 나중의 모드는 이전 모드가 이벤트를 보는 것을 막을 수 없습니다.

285

286Claude Code는 각 모드의 출처에 따라 체인을 정렬합니다.

287

2881. 내장 가드 `sec-default@builtin`은 Claude Code에 내장된 모드로, `/plugin`에서 `cc-plugin-sec-default`로 나열되며, [여기서 로드](/docs/ko/plugins/mods/admin#know-what-happens-by-default)되고, 조직이 [`prependPlugins`](/docs/ko/plugins/mods/admin#install-your-organizations-mods)에 나열한 모드, 그리고 조직의 것으로 간주되며 `appendPlugins`에 없는 다른 모드

2892. 설치한 모드

2903. 조직이 `appendPlugins`에 나열한 모드

2914. Claude Code에 내장된 다른 모드

292

293설치한 모드 중에서, 모드는 매니페스트의 `dependencies` 아래에 나열한 모드보다 먼저 실행됩니다. 하나의 모듈 내에서, 후킹은 `register`가 `on`을 호출한 순서대로 실행됩니다.

294

295<h4 id="where-settings-hooks-run-in-the-order">

296 설정 후킹이 순서대로 실행되는 위치

297</h4>

298

299설정 파일에서 구성된 `PreToolUse` 후킹도 도구 호출 중에 실행되며, 모드 체인의 고정된 지점에서 실행됩니다.

300

301* **관리되는 설정의 `PreToolUse` 후킹**: 첫 번째 모드의 `tool.call` 후킹 전에 실행되며, 그 중 하나의 차단은 최종적이므로 모드가 호출을 보지 못합니다.

302* **다른 모든 설정 파일 및 플러그인의 `hooks/hooks.json`의 `PreToolUse` 후킹**: 마지막 모드가 `next`를 호출한 후, Claude Code의 자체 동작의 일부로 실행됩니다. `next`를 호출하지 않고 `tool.call`에 응답하는 모드는 이들이 실행되는 것을 방지하고, `next`를 호출하는 모드는 반환하는 결과에서 이들의 결정을 봅니다.

303

304[`tool.check`](/docs/ko/plugins/mods/reference#tools)는 Claude Code가 도구 호출 실행 여부를 결정하는 이벤트입니다. 이는 해당 후킹과 권한 규칙이 결정한 후에 발생하며, `next(e)`는 해당 결정으로 해석됩니다. `tool.check`의 후킹은 `{ decision: 'allow' }`와 같은 다른 결정을 반환할 수 있으므로, 두 번째 그룹의 후킹이 차단한 호출을 승인할 수 있습니다. [후킹으로 권한 확장](/docs/ko/permissions#extend-permissions-with-hooks)은 어떤 결정이 모드보다 우선하는지 나열합니다.

305

306<h3 id="handle-a-hook-that-fails">

307 실패한 후킹 처리

308</h3>

309

310실패한 후킹은 세션을 중단하지 않으며, 대신 발생하는 상황을 결정할 수 있습니다. `.catch` 핸들러가 없는 후킹이 throw되거나, 시간 초과되거나, 잘못된 형태의 결과를 반환할 때, 다음에 발생하는 상황은 `next`를 호출했는지 여부에 따라 달라집니다.

311

312* **`next`를 호출하기 전에 실패함**: Claude Code는 이를 건너뛰고, 다음 핸들러가 그 자리에서 실행됩니다.

313* **`next`가 해석된 후에 실패함**: 해당 결과가 유지되고, 아무것도 두 번 실행되지 않습니다.

314

315한 줄은 모드, 이벤트, 그리고 이유를 이름 지으며, 예를 들어 `my-mod: tool.call hook skipped: threw Error: boom`입니다. 이를 읽는 위치는 세션에 따라 달라지며, [모드가 아무것도 하지 않는 이유 알아내기](/docs/ko/plugins/mods/troubleshoot#find-out-why-a-mod-does-nothing)에 나열되어 있습니다. 그리기가 유효성 검사를 통과하지 못하는 `ui.render` 후킹은 [요소에서 트리 구축](/docs/ko/plugins/mods/interface#build-a-tree-from-elements)에서 설명하는 대로 다르게 보고됩니다.

316

317호출을 차단하는 후킹이 실패하도록 닫히게 하려면, 그 자리에 응답하는 `.catch` 오류 핸들러를 추가하십시오. 여기서 `guard`는 후킹 함수입니다.

318

319```javascript theme={null}

320// on은 등록을 반환하고, .catch는 해당 하나의 후킹에 핸들러를 첨부합니다.

321on('tool.call', { tool: 'Bash' }, guard).catch(async ($, e, next) => {

322 // next.error.kind는 'throw' 또는 'timeout'이며, guard가 어떻게 실패했는지를 나타냅니다.

323 return { deny: 'The command guard failed, so this command was not run: ' + next.error.kind }

324})

325```

326

327`guard`가 작동하는 동안, 핸들러는 실행되지 않습니다. `guard`가 Bash 호출에서 throw되거나 시간 초과될 때, Claude Code는 동일한 이벤트로 핸들러를 호출합니다. 핸들러는 `{ deny }`를 반환하므로, 명령이 실행되지 않으며, Claude는 끝에 `throw` 또는 `timeout`이 있는 텍스트를 읽습니다. 핸들러가 없으면, Claude Code는 `guard`를 건너뛰고 명령을 실행합니다. 핸들러는 [1초](/docs/ko/plugins/mods/reference#limits) 내에 응답해야 합니다.

328

329<h2 id="next-steps">

330 다음 단계

331</h2>

332

333* [mods API 사용](/docs/ko/plugins/mods/api): 명령과 도구를 추가하고, 모델을 호출하고, 타이머에서 작업을 실행합니다

334* [인터페이스에 그리기](/docs/ko/plugins/mods/interface): 훅이 수집한 것을 창이나 프롬프트 위에 표시합니다

335* [모드 테스트](/docs/ko/plugins/mods/test): 테스트에서 이 이벤트 중 하나를 발생시킵니다

336* [Mods 참조](/docs/ko/plugins/mods/reference): 모든 이벤트, 모든 mods API 메서드, 그리고 제한

plugins/mods/interface.md +874 −0 created

Details

1> ## Documentation Index

2> 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.

5# 모드로 인터페이스에 그리기

7> Claude Code 모드에서 창, 프롬프트 위의 밴드, 버튼, 텍스트 필드를 그리고, 누름과 입력을 처리하며, 다시 그릴 때와 세션 간에 상태를 유지합니다.

9모드는 Claude Code에서 자신의 인터페이스를 그릴 수 있고 Claude Code가 이미 그리는 인터페이스의 일부를 변경할 수 있습니다. 모드가 그릴 수 있는 각 위치를 [렌더 사이트](/docs/ko/plugins/mods/reference#render-sites)라고 하며, 창, 프롬프트 위의 밴드, 또는 스피너 같은 것들이 있습니다. Claude Code는 렌더 사이트를 그리려고 할 때마다 [`ui.render`](/docs/ko/plugins/mods/reference#interface) 이벤트를 발생시키고, 해당 이벤트에 대한 훅이 그곳에 그릴 내용을 반환합니다.

11이 지도는 터미널 세션에서 모드가 그릴 수 있는 위치를 보여줍니다:

13<img src="https://mintcdn.com/claude-code/dgiVO_Od1X1faduV/images/mods-screen-map.svg?fit=max&auto=format&n=dgiVO_Od1X1faduV&q=85&s=5fda26b6609c62b68c6f9e528c1590ea" className="dark:hidden" alt="Claude Code 터미널 세션의 지도. 모드는 오른쪽에 사이드바로 창을 추가하고, 대화 기록의 오른쪽 위에 토스트를 추가하고, 대화 기록에 로그 줄을 추가하고, 프롬프트 위에 밴드를 추가하고, 프롬프트 아래에 상태 줄을 추가할 수 있습니다. 모드는 메시지, 도구 호출 행, 스피너를 다시 그릴 수 있습니다. 프롬프트는 Claude Code 자신의 것입니다." width="600" height="336" data-path="images/mods-screen-map.svg" />

15<img src="https://mintcdn.com/claude-code/dgiVO_Od1X1faduV/images/mods-screen-map-dark.svg?fit=max&auto=format&n=dgiVO_Od1X1faduV&q=85&s=5b4161581a1bd2c0450b0c8b57bc1225" className="hidden dark:block" alt="Claude Code 터미널 세션의 지도. 모드는 오른쪽에 사이드바로 창을 추가하고, 대화 기록의 오른쪽 위에 토스트를 추가하고, 대화 기록에 로그 줄을 추가하고, 프롬프트 위에 밴드를 추가하고, 프롬프트 아래에 상태 줄을 추가할 수 있습니다. 모드는 메시지, 도구 호출 행, 스피너를 다시 그릴 수 있습니다. 프롬프트는 Claude Code 자신의 것입니다." width="600" height="336" data-path="images/mods-screen-map-dark.svg" />

17더 좁은 터미널에서는 창이 대화 기록 옆이 아니라 프롬프트 위에 있습니다.

19여기서 시작하기 전에 [첫 번째 모드](/docs/ko/plugins/mods/create)를 만드세요. 두 개의 탭과 카운터가 있는 창을 만드는 작업 예제로 시작한 다음, 변경하려는 각 부분에 대한 섹션을 읽으세요.

21<Note>

22 한 가지 속성이나 제한을 찾으려면 [참조](/docs/ko/plugins/mods/reference#render-sites)를 보세요.

23</Note>

25<h2 id="build-a-pane-with-tabs">

26 탭이 있는 창 만들기

27</h2>

29이 섹션에서는 `/hello-tabs` 명령을 추가하는 모드를 만들고, 이 명령은 창을 엽니다. 창은 넓은 전체 화면 터미널에서는 대화 기록 옆의 사이드바이거나, 그렇지 않으면 프롬프트 위의 프레임된 영역입니다. 이 창은 두 개의 탭을 표시하고, 두 번째 탭에는 카운터에 1을 더하는 버튼이 있습니다. Claude Code를 다시 시작한 후에도 카운트는 여전히 있습니다.

31완성된 모드는 다음과 같습니다. 녹화는 창을 열고, 두 번째 탭으로 전환하고, 버튼을 몇 번 누르고, 첫 번째 탭으로 돌아갑니다:

33<Frame>

34 <video autoPlay muted loop playsInline controls className="w-full dark:hidden" src="https://mintcdn.com/claude-code/dgiVO_Od1X1faduV/images/mods-hello-tabs-light.mp4?fit=max&auto=format&n=dgiVO_Od1X1faduV&q=85&s=49d520094d87b5b44bfe50fa49677f06" aria-label="/hello-tabs 명령이 Claude Code 프롬프트에 입력되고 프레임된 창이 위에 열리며, 맨 위에 '1: One'과 '2: Two'가 있고 '이것은 첫 번째 탭입니다.'라는 텍스트가 있습니다. 두 번째 탭은 'Count: 1' 옆에 'Add one' 버튼을 표시하고, 카운트는 3으로 올라갑니다. 창은 그 다음 첫 번째 탭으로 돌아갑니다." data-path="images/mods-hello-tabs-light.mp4" />

36 <video autoPlay muted loop playsInline controls className="w-full hidden dark:block" src="https://mintcdn.com/claude-code/dgiVO_Od1X1faduV/images/mods-hello-tabs-dark.mp4?fit=max&auto=format&n=dgiVO_Od1X1faduV&q=85&s=ff7a14d713d6e5d3b0000efa8522ea4b" aria-label="/hello-tabs 명령이 Claude Code 프롬프트에 입력되고 프레임된 창이 위에 열리며, 맨 위에 '1: One'과 '2: Two'가 있고 '이것은 첫 번째 탭입니다.'라는 텍스트가 있습니다. 두 번째 탭은 'Count: 1' 옆에 'Add one' 버튼을 표시하고, 카운트는 3으로 올라갑니다. 창은 그 다음 첫 번째 탭으로 돌아갑니다." data-path="images/mods-hello-tabs-dark.mp4" />

37</Frame>

39Claude Code에는 기본 제공 탭 요소가 없으므로 탭은 행의 두 버튼입니다. 모드는 어느 것이 활성인지 추적하고 그 탭의 내용을 행 아래에 그립니다.

41<Steps>

42 <Step title="플러그인 만들기">

43 모드는 매니페스트, 코드를 가리키는 `hooks.json`, 그리고 코드 파일이 있는 플러그인입니다. [모드 만들기](/docs/ko/plugins/mods/create#write-a-mod-yourself)는 각각을 설명합니다. `hello-tabs`라는 디렉토리를 만들고 그 안에 `.claude-plugin`과 `hooks` 디렉토리를 만든 다음 처음 두 파일을 저장하세요.

45 매니페스트를 `hello-tabs/.claude-plugin/plugin.json`으로 저장하세요:

47 ```json hello-tabs/.claude-plugin/plugin.json theme={null}

48 {

49 "name": "hello-tabs",

50 "version": "0.1.0",

51 "description": "Opens a pane with two tabs and a counter",

52 "author": { "name": "Your Name" }

53 }

54 ```

56 `hello-tabs/hooks/hooks.json`에서 진입점의 이름을 지정하세요:

58 ```json hello-tabs/hooks/hooks.json theme={null}

59 {

60 "modules": ["./register.js"]

61 }

62 ```

63 </Step>

65 <Step title="코드 작성">

66 코드는 각 훅에서 하나씩 세 가지 작업을 수행합니다:

68 * `/hello-tabs` 명령 추가

69 * 해당 명령을 실행할 때 창 열기

70 * 창의 내용 그리기: 탭 행과 열린 탭의 본문

72 두 개의 모듈 수준 변수인 `tab`과 `count`는 창의 상태를 유지합니다.

74 이를 `hello-tabs/hooks/register.js`로 저장하세요:

76 ```javascript hello-tabs/hooks/register.js theme={null}

77 // 창의 id, 창을 열고 그릴 때 인식하는 데 사용됨

78 const PANE = 'hello-tabs'

80 // 창이 표시하는 것: 어느 탭이 열려 있는지, 그리고 카운터의 값

81 let tab = 'one'

82 let count = 0

84 export function register(on) {

85 // 첫 프롬프트 전에 실행되고, 다시 로드 후에도 실행됨

86 on('session.start', async ($, e, next) => {

87 await $.command.register({ name: 'hello-tabs', description: 'Open the hello-tabs pane' })

88 // 이전 세션이 저장한 카운트를 로드합니다 (있는 경우)

89 const saved = await $.store.get('count')

90 if (typeof saved === 'number') count = saved

91 return next(e)

92 })

94 // /hello-tabs를 입력할 때 실행됨

95 on('command.run', { command: 'hello-tabs' }, async ($) => {

96 // 창을 열고, 키보드를 주고, Esc로 닫을 수 있게 함

97 await $.ui.open({ id: PANE, title: 'Hello tabs', focus: true, closeOnEscape: true })

98 // 대화 기록에 아무것도 인쇄하지 않음

99 return {}

100 })

101

102 // Claude Code가 창을 그릴 때마다 실행됨

103 on('ui.render', { component: 'Pane' }, async ($, e, next) => {

104 // 다른 모드의 창은 그대로 두기

105 if (e.requestId !== PANE) return next(e)

106 // 이 앱이 그릴 수 있는 요소 가져오기

107 const { Box, Text, Button } = $.ui.resolve(e)

108 // Claude Code가 이 훅을 다시 실행하도록 요청

109 const redraw = () => $.ui.invalidate('ui.render')

110

111 // 한 탭: 누르면 해당 탭으로 전환하는 버튼

112 const tabButton = (name, label, hotkey) =>

113 Button({

114 key: 'tab-' + name,

115 label,

116 hotkey,

117 plain: true,

118 // 열려 있지 않은 탭을 어둡게 함

119 dimColor: tab !== name,

120 onPress: () => {

121 tab = name

122 redraw()

123 },

124 })

125

126 // 어느 탭이 열려 있는지에 따라 탭 아래에 가는 것

127 const body =

128 tab === 'one'

129 ? [Text({ children: ['This is the first tab.'] })]

130 : [

131 Box({

132 flexDirection: 'row',

133 columnGap: 2,

134 children: [

135 Button({

136 key: 'more',

137 label: 'Add one',

138 hotkey: 'a',

139 onPress: async () => {

140 count += 1

141 redraw()

142 // 카운트를 저장하여 다시 시작 후에도 있도록 함

143 await $.store.set('count', count)

144 },

145 }),

146 Text({ children: ['Count: ' + count] }),

147 ],

148 }),

149 ]

150

151 // 전체 창: 탭 행, 빈 줄, 그 다음 본문

152 return Box({

153 flexDirection: 'column',

154 children: [

155 Box({

156 flexDirection: 'row',

157 columnGap: 3,

158 children: [tabButton('one', 'One', '1'), tabButton('two', 'Two', '2')],

159 }),

160 Text({ children: [' '] }),

161 ...body,

162 ],

163 })

164 })

165 }

166 ```

167

168 각 훅은 코드가 명확하게 하지 않는 것도 수행합니다:

169

170 * \*\*[`session.start`](/docs/ko/plugins/mods/reference#session)\*\*는 또한 [`$.store`](#keep-state)에서 저장된 카운트를 읽습니다. 이는 세션 간에 지속되는 키-값 저장소입니다.

171 * \*\*[`command.run`](/docs/ko/plugins/mods/api#add-a-command)\*\*은 Claude Code에 창이 존재한다고만 알립니다. 창을 열어도 아무것도 그려지지 않습니다: Claude Code는 그 다음 `ui.render`를 발생시켜 그곳에 무엇을 넣을지 묻습니다.

172 * \*\*`ui.render`\*\*는 요소 트리를 반환합니다. 이는 다른 상자, 텍스트, 버튼을 보유하는 `Box`이며, 실행될 때마다 `tab`과 `count`에서 다시 빌드합니다.

173

174 버튼을 누르면 `onPress` 콜백이 실행되고, 이는 변수를 변경하고 `redraw`를 호출합니다. Claude Code는 그 다음 `ui.render` 훅을 다시 실행하고, 훅은 새로운 값에서 새로운 트리를 빌드합니다. 모든 대화형 그리기는 그 렌더 사이클을 사용합니다: 콜백이 상태를 변경하고, 훅이 새로운 상태에서 다시 렌더링합니다.

175 </Step>

176

177 <Step title="창 열기">

178 셸에서 `claude --plugin-dir ./hello-tabs`로 Claude Code를 시작하세요. Claude Code 프롬프트에서 `/hello-tabs`를 실행하세요. 맨 위에 `1: One`과 `2: Two`가 있는 창이 열립니다. `2`를 누르고, 그 다음 **Add one**의 핫키인 `a`를 몇 번 누르세요. 카운트가 올라갑니다.

179 </Step>

180

181 <Step title="카운트가 저장되었는지 확인">

182 Esc를 눌러 창을 닫고 세션을 종료하세요. 셸에서 같은 `claude --plugin-dir ./hello-tabs` 명령으로 Claude Code를 다시 시작하고, Claude Code 프롬프트에서 `/hello-tabs`를 실행하세요. 카운트는 남겨둔 곳에 있습니다.

183

184 카운트를 지우려면 모드가 `$.store.delete('count')`를 호출하도록 하세요. [상태 유지](#keep-state)는 각 종류의 값이 얼마나 오래 지속되는지를 다룹니다.

185 </Step>

186</Steps>

187

188<h2 id="pick-where-to-draw">

189 그리기 위치 선택

190</h2>

191

192`ui.render` 훅은 원하는 위치로 좁히지 않는 한 모든 렌더 사이트에서 실행됩니다. 렌더 사이트를 선택하려면 [매처](/docs/ko/plugins/mods/events#filter-which-events-a-hook-handles)라고 불리는 필터를 `on`의 두 번째 인수로 전달합니다. `{ component: 'Pane' }`은 훅을 창에서만 실행합니다. 훅에서 `e.component`는 사이트의 이름을 지정하고, `e.surface`는 어떤 앱이 그리고 있는지 나타내며, `e.props`는 사이트 자체의 데이터를 보유합니다. 창의 경우 `e.requestId`는 열 때 사용한 `id`입니다.

193

194두 사이트는 모드가 채울 때까지 비어 있으며, 창과 밴드입니다. 탭을 선택하여 각각이 무엇인지, 그리고 어떻게 그리는지 확인합니다:

195

196<Tabs>

197 <Tab title="Pane">

198 창은 넓은 전체 화면 터미널에서 대화 옆의 사이드바이거나, 그렇지 않으면 프롬프트 위의 프레임 영역입니다. 여러 창이 열려 있으면 각각 제목을 표시하는 탭을 가집니다.

199

200 창은 모드가 `$.ui.open`을 `id`와 함께 호출할 때 나타나며, 예를 들어 `$.ui.open({ id: 'hello-tabs' })`입니다. [올바른 시간에 창 열기](#open-a-pane-at-the-right-time)는 다른 필드와 창이 더 넓은 터미널을 기다릴 때를 다룹니다.

201

202 창에 그리려면 `{ component: 'Pane' }`으로 필터링하고 `e.requestId`가 `id`인지 확인합니다.

203 </Tab>

204

205 <Tab title="Band above the prompt">

206 밴드는 프롬프트 입력 바로 위의 스트립입니다. 항상 있으며 모든 모드가 공유합니다.

207

208 훅은 밴드에 무언가를 표시하는 트리를 반환하거나, 아무것도 표시하지 않으려면 `next(e)`를 반환합니다. 트리는 모드 [이후의 것들](/docs/ko/plugins/mods/events#the-order-mods-run-in)이 그곳에 그리는 것을 대체합니다. 그들의 것을 유지하려면 `await next(e)`의 결과를 트리의 [`Box`](#build-a-tree-from-elements)의 자식 중에 넣습니다.

209

210 밴드에 그리려면 `{ component: 'AbovePrompt' }`으로 필터링합니다.

211 </Tab>

212</Tabs>

213

214<h3 id="change-what-claude-code-already-draws">

215 Claude Code가 이미 그리는 것 변경

216</h3>

217

218Claude Code는 대부분의 인터페이스를 자체적으로 그립니다: 메시지, 도구 호출 행, 스피너 등. 이러한 각 부분도 렌더 사이트이므로 모드는 이를 다시 스타일링하거나 대체할 수 있습니다. 하나를 변경하려면 이 표의 이름으로 `ui.render` 훅을 필터링합니다:

219

220| Site | What it is |

221| :- | :- |

222| `UserMessage`, `AssistantMessage` | 대화의 메시지 |

223| `ToolUse`, `ToolResult`, `ToolGroup` | 도구 호출의 행, 그 결과, 그리고 접힌 호출 실행 |

224| `CommandOutput` | 명령이 인쇄한 행 |

225| `AskUserQuestion` | Claude가 질문을 하기 위해 열 수 있는 대화 |

226| `Spinner`, `ToolProgress`, `TurnDuration` | 턴의 상태 줄: Claude가 작업하는 동안 애니메이션되는 줄, 실행 중인 도구의 실시간 진행 줄, 턴을 닫는 줄 |

227| `InfoNotice`, `SessionMode`, `PromptHint` | 로고 아래의 상태 줄, 바닥글의 모드 레이블, 프롬프트 아래의 힌트 줄 |

228

229Claude Code가 이미 그리는 사이트에서 훅에는 세 가지 선택이 있습니다: 세부 사항 변경, 그리기 대체, 또는 그대로 두기. 탭을 선택하여 각각을 스피너에 적용한 것을 확인합니다. 예제는 [튜토리얼 모드](/docs/ko/plugins/mods/create#write-a-mod-yourself)처럼 다른 훅이 계산하는 `calls` 변수를 읽습니다.

230

231<Tabs>

232 <Tab title="Change a detail">

233 Claude Code의 그리기를 유지하고 그 일부를 변경하려면 변경된 `props`로 이벤트의 복사본을 `next`에 전달합니다. 이 훅은 스피너의 단어 뒤의 텍스트를 변경합니다:

234

235 ```javascript theme={null}

236 on('ui.render', { component: 'Spinner' }, async ($, e, next) => {

237 // Keep Claude Code's spinner, and change the text after its word

238 return next({ ...e, props: { ...e.props, suffix: ' · tool calls: ' + calls + '…' } })

239 })

240 ```

241

242 스피너는 애니메이션과 단어를 유지하고 텍스트가 단어를 따릅니다:

243

244 ```text theme={null}

245 Thinking · tool calls: 2…

246 ```

247 </Tab>

248

249 <Tab title="Replace the drawing">

250 사이트 위치에 자신의 것을 그리려면 트리를 반환하고 `next`를 호출하지 마십시오. 이 훅은 스피너가 있을 위치에 한 줄의 텍스트를 그립니다:

251

252 ```javascript theme={null}

253 on('ui.render', { component: 'Spinner' }, async ($, e) => {

254 const { Text } = $.ui.resolve(e)

255 // No call to next, so this line is drawn in the spinner's place

256 return Text({ children: ['Claude has made ' + calls + ' tool calls'] })

257 })

258 ```

259

260 Claude가 작업하는 동안 줄이 표시되고 Claude Code의 스피너는 표시되지 않습니다:

261

262 ```text theme={null}

263 Claude has made 2 tool calls

264 ```

265 </Tab>

266

267 <Tab title="Leave it alone">

268 사이트를 Claude Code가 그리는 대로 두려면 `next(e)`를 반환합니다. 훅은 종종 일부 이벤트에 대해서는 그렇게 하고 다른 이벤트에 대해서는 그렇지 않습니다. 이 훅은 계산할 호출이 있을 때까지 스피너를 그대로 둡니다:

269

270 ```javascript theme={null}

271 on('ui.render', { component: 'Spinner' }, async ($, e, next) => {

272 // Nothing to show yet, so pass the event on unchanged

273 if (calls === 0) return next(e)

274 return next({ ...e, props: { ...e.props, suffix: ' · tool calls: ' + calls + '…' } })

275 })

276 ```

277

278 첫 번째 도구 호출 전에 스피너는 모드 없이 하는 방식으로 보입니다:

279

280 ```text theme={null}

281 Thinking…

282 ```

283 </Tab>

284</Tabs>

285

286권한 프롬프트는 렌더 사이트가 아니므로 모드는 표시되는 것을 변경할 수 없습니다. 질문 대화 `AskUserQuestion`은 하나이므로 모드는 그것을 변경할 수 있습니다.

287

288터미널과 Desktop 앱은 모두 동일한 사이트를 발생시키지 않습니다. `Pane`, `AbovePrompt`, `Spinner`, 그리고 대화 사이트는 둘 다에서 작동합니다. 몇 가지 다른 상태 줄은 터미널에서만 발생합니다. [렌더 사이트 표](/docs/ko/plugins/mods/reference#render-sites)는 각각이 발생하는 위치를 나열합니다.

289

290<h3 id="open-a-pane-at-the-right-time">

291 올바른 시간에 창 열기

292</h3>

293

294창은 모드가 열 때만 나타납니다. 어떻게 그리고 언제 열 것인지는 키보드 포커스를 받는지, 얼마나 많은 공간을 요청하는지, 그리고 좁은 터미널에서 전혀 표시되는지 여부를 결정합니다.

295

296창을 열려면 선택한 `id`로 [`$.ui.open`](/docs/ko/plugins/mods/reference#mods-api-methods)을 호출합니다. `id`는 창의 이름입니다: `ui.render` 훅이 확인하고, 창을 닫을 때 다시 전달합니다.

297

298```javascript theme={null}

299await $.ui.open({ id: 'hello-tabs', title: 'Hello tabs', focus: true })

300```

301

302창을 닫으려면 열 때 사용한 `id`로 `$.ui.close`를 호출합니다:

303

304```javascript theme={null}

305await $.ui.close({ id: 'hello-tabs' })

306```

307

308`id` 외에도 `$.ui.open`은 다음 선택적 필드를 사용합니다:

309

310| Field | What it does |

311| :- | :- |

312| `title` | 둘 이상의 창이 열려 있을 때 창의 탭 레이블 |

313| `focus` | [키보드 포커스](#know-which-keys-your-mod-can-receive) 요청 |

314| `closeOnEscape` | Esc가 창을 닫게 합니다 |

315| `holdToasts` | 창이 닫힐 때까지 [`$.ui.toast`](/docs/ko/plugins/mods/api#show-something-without-starting-a-turn)의 작은 알림인 토스트를 유지합니다 |

316| `rows` | 창이 프롬프트 위에 있을 때 요청할 높이입니다. 기본값은 공간의 1/3입니다. |

317| `columns` | 창이 대화 옆에 있을 때 요청할 너비입니다 |

318

319`focus`, `closeOnEscape`, 그리고 `holdToasts`는 선택적이며 `true`만 허용합니다. 하나를 생략하려면 이를 빼십시오. `false`를 전달하면 `ui.open: focus is true or left out`과 같은 오류가 발생합니다. 조건부로 하나를 설정하려면 조건이 유지될 때만 필드를 추가합니다. 이 호출은 `items`가 비어 있지 않을 때만 키보드 포커스를 요청합니다:

320

321```javascript theme={null}

322const pane = { id: 'hello-tabs', title: 'Hello tabs' }

323await $.ui.open(items.length > 0 ? { ...pane, focus: true } : pane)

324```

325

326Claude가 작업하는 동안 명령이 창을 열 수 있도록 하려면 [명령을 등록](/docs/ko/plugins/mods/api#add-a-command)할 때 `immediate: true`를 추가합니다. 없으면 턴 중에 입력된 명령은 턴이 끝날 때까지 기다립니다.

327

328<h4 id="when-a-pane-waits-for-a-wider-terminal">

329 창이 더 넓은 터미널을 기다릴 때

330</h4>

331

332모드가 요청받지 않고 열 수 있는 창은 좁은 터미널에 나타나지 않으므로 작은 화면을 차지할 수 없습니다. 나타나는지 여부는 열 수 있는 것에 따라 다릅니다:

333

334* **사용자가 한 것**, 예를 들어 실행한 명령이나 누른 버튼과 같이 사용자가 한 것으로 열린 경우, 창은 모든 너비에서 나타납니다

335* **모드가 자체적으로 작동하여 열린 경우**, 예를 들어 타이머 또는 [`turn.start`](/docs/ko/plugins/mods/events#follow-a-turn) 훅에서, 창은 최소 144개 열의 터미널에서만 나타납니다. 사용자가 그 창을 직접 한 번 열었으면 110개 열이면 충분합니다.

336

337창이 나타나면 `$.ui.open`은 `{ isPlaced: true }`로 해결됩니다. 창이 대기 중이면 `isPlaced`는 `false`이고 `reason`은 이유를 설명하는 문자열입니다. 대기 중인 창은 사용자가 열거나 터미널을 넓힐 때 나타납니다. 창을 열지 않고 무언가를 사용할 수 있다고 말하려면 `$.ui.toast('Your message')`를 호출합니다. 이는 몇 초 후에 사라지는 작은 알림을 표시합니다.

338

339<h2 id="build-a-tree-from-elements">

340 요소에서 트리 만들기

341</h2>

342

343`ui.render` 훅이 반환하는 것은 요소 트리입니다: 상자, 텍스트, 그리고 서로 중첩된 컨트롤로 만든 그릴 것의 설명. 그리기를 설명하고, Claude Code는 터미널이나 데스크톱 앱에서 렌더링합니다.

344

345요소를 얻으려면 훅에서 `$.ui.resolve(e)`를 호출하세요. 예를 들어 `const { Box, Text, Button } = $.ui.resolve(e)`. 각 요소는 함수입니다. 속성을 전달하고, 그 안에 가는 요소와 문자열을 `children`에 넣습니다.

346

347대부분의 그리기는 네 가지 요소를 사용합니다. 탭을 선택하여 각각과 터미널이 어떻게 그리는지 보세요:

348

349<Tabs>

350 <Tab title="텍스트">

351 `Text`는 `bold`와 `color` 같은 선택적 스타일링으로 문자열을 그립니다:

352

353 ```javascript theme={null}

354 Text({ children: ['This is the first tab.'] })

355 ```

356

357 ```text theme={null}

358 This is the first tab.

359 ```

360 </Tab>

361

362 <Tab title="상자">

363 `Box`는 그 안에 있는 것을 행이나 열로 배열합니다. 이것은 버튼과 텍스트 줄을 나란히 놓고, 두 열 떨어져 있습니다:

364

365 ```javascript theme={null}

366 Box({

367 flexDirection: 'row',

368 columnGap: 2,

369 children: [

370 Button({ key: 'more', label: 'Add one', onPress: addOne }),

371 Text({ children: ['Count: 0'] }),

372 ],

373 })

374 ```

375

376 ```text theme={null}

377 [ Add one ] Count: 0

378 ```

379 </Tab>

380

381 <Tab title="버튼">

382 `Button`은 사용자가 누를 수 있는 컨트롤입니다. `onPress` 콜백을 실행합니다. `plain: true`로 괄호가 없고 핫키를 표시합니다:

383

384 ```javascript theme={null}

385 Button({ key: 'more', label: 'Add one', onPress: addOne })

386 Button({ key: 'tab-one', label: 'One', hotkey: '1', plain: true, onPress: showTabOne })

387 ```

388

389 ```text theme={null}

390 [ Add one ]

391 1: One

392 ```

393 </Tab>

394

395 <Tab title="입력">

396 `Input`은 텍스트 필드입니다. 사용자가 Enter를 누르면 텍스트로 `onSubmit` 콜백을 실행합니다:

397

398 ```javascript theme={null}

399 Input({

400 key: 'new-note',

401 label: 'Note',

402 placeholder: 'Type a note and press Enter',

403 value: '',

404 submitLabel: 'add',

405 onSubmit: addNote,

406 })

407 ```

408

409 ```text theme={null}

410 Note: Type a note and press Enter ⏎ add

411 ```

412 </Tab>

413</Tabs>

414

415이 표는 모든 요소를 나열합니다:

416

417| 요소 | 무엇을 그리는가 | 어디서 |

418| :- | :- | :- |

419| `Box` | 플렉스 컨테이너. `flexDirection`, `columnGap`, `padding`, `borderStyle`, `width` 같은 레이아웃 속성을 사용합니다. | 모든 곳 |

420| `Text` | 스타일이 지정된 텍스트. `color`, `bold`, `dimColor`, `italic`, `wrap`을 사용합니다. `color`는 테마 키 또는 `'red'` 같은 색입니다. `wrap`은 `'wrap'`, `'truncate'`, `'truncate-start'`, `'truncate-middle'`, 또는 `'truncate-end'`입니다. | 모든 곳 |

421| `Button` | `onPress`를 호출하는 컨트롤 | 모든 곳 |

422| `Link`, `Code`, `Markdown` | `href`와 선택적 `label`이 있는 링크, 코드 블록, Claude의 답변 방식으로 포맷된 텍스트. `Markdown`은 `children`이 아닌 `text` 속성에서 내용을 가져오고, `onLinkPress`를 전달할 때 `key`가 필요합니다. | 모든 곳 |

423| `Input`, `Select` | 텍스트 필드와 선택기 | 터미널, 데스크톱 |

424| `Svg` | SVG 문서 | 데스크톱 |

425| `Client` | 두 번째 파일로 그려진 영역, 애니메이션과 포인터 입력용. 그 파일은 모드 API를 받지 않습니다. 데이터를 게시하여 훅에만 도달하며, 이는 `ui.message` 이벤트로 도착합니다. | 터미널, 데스크톱 |

426| `Raster`, `Image` | [색상 셀의 그리드](#draw-a-grid-of-colored-cells), 그리고 그림 | 터미널 |

427

428모듈이 `.tsx` 또는 `.jsx` 파일이면 트리를 JSX로 쓸 수 있습니다. `$.ui.resolve(e)`에서 요소를 분해하세요. 훅 모듈에는 요소 전역이 없기 때문입니다.

429

430트리가 앱이 없는 요소, 요소가 사용하지 않는 속성, 또는 아무것도 가지 않는 곳에 자식을 사용하면 Claude Code는 자신의 버전의 사이트를 그립니다.

431

432`--plugin-dir`로 시작한 세션에서 대화 기록 줄은 그렇게 말합니다. 예를 들어 `ui.render (Pane) refused: Text prop "bogusProp" is not allowed; the engine drew its own`. [디버그 로그](/docs/ko/plugins/mods/troubleshoot#read-the-debug-log)는 `ui.render (Pane): a hook returned a tree that does not validate`로 같은 이유로 기록합니다. 세션에 다른 것도 나타나지 않으므로 그리기가 표시되지 않으면 그 줄이나 로그를 확인하세요.

433

434<h3 id="draw-a-grid-of-colored-cells">

435 색상 셀의 그리드 그리기

436</h3>

437

438열 지도, 스파크라인, 또는 터미널의 게임 보드의 경우 각 셀에 대해 하나의 `Box`가 아닌 하나의 `Raster`를 그리세요. `Raster`는 `key`, `columns`과 `rows`의 크기, 그리고 모든 셀을 하나의 문자열로 압축하는 `cells`를 사용합니다. 각 셀은 세 개의 숫자입니다: 문자의 코드 포인트, 색, 배경색. 색은 빨강, 녹색, 파랑 각각 두 자리의 16진수 숫자입니다. 예를 들어 빨강의 경우 `0xc62828`, 터미널의 기본값의 경우 `0x01000000`.

439

440데스크톱 앱에는 `Raster`가 없으므로 `e.surface`를 확인하고 거기에 텍스트를 그리세요. 이 창 본문은 3x2 열 지도를 그립니다:

441

442```javascript theme={null}

443// "터미널의 기본 색을 사용"을 의미하는 값

444const DEFAULT_COLOR = 0x01000000

445

446// [문자, 색] 쌍의 행을 Raster가 사용하는 하나의 문자열로 압축

447// 한 셀은 세 개의 숫자: 문자의 코드 포인트, 색, 배경색

448function cellsOf(rows) {

449 const numbers = rows.flat().flatMap(([char, color]) => [char.codePointAt(0), color, DEFAULT_COLOR])

450 return new Uint8Array(Uint32Array.from(numbers).buffer).toBase64()

451}

452

453on('ui.render', { component: 'Pane' }, async ($, e, next) => {

454 // id가 'heat'인 창에서만 그리기

455 if (e.requestId !== 'heat') return next(e)

456 const { Box, Text, Raster } = $.ui.resolve(e)

457 // 3개의 셀 각각이 블록 문자와 색인 2행

458 const rows = [

459 [['█', 0x2e7d32], ['█', 0xf9a825], ['█', 0xc62828]],

460 [['█', 0x2e7d32], ['█', 0x2e7d32], ['█', 0xf9a825]],

461 ]

462 if (e.surface !== 'terminal') {

463 return Text({ children: ['The heat map needs the terminal.'] })

464 }

465 return Box({

466 flexDirection: 'column',

467 children: [Raster({ key: 'grid', columns: 3, rows: 2, cells: cellsOf(rows) })],

468 })

469})

470```

471

472터미널에서 창은 그리드를 표시합니다:

473

474<img src="https://mintcdn.com/claude-code/dgiVO_Od1X1faduV/images/mods-heat-map.svg?fit=max&auto=format&n=dgiVO_Od1X1faduV&q=85&s=b91bcce3bad74bc851149133d4acc5d5" alt="색상 블록의 작은 그리드를 보유하는 터미널의 창, 2행 3개. 맨 위 행은 녹색, 호박색, 빨강입니다. 아래 행은 녹색, 녹색, 호박색입니다." width="360" height="132" data-path="images/mods-heat-map.svg" />

475

476`rows` 배열은 변경할 부분이고, `cellsOf`는 그것을 압축된 문자열로 변환합니다. 훅은 `id`가 `heat`인 창에서만 그리므로 [`hello-tabs` 예제](#build-a-pane-with-tabs)가 창을 열 때처럼 명령에서 `$.ui.open({ id: 'heat' })`로 하나를 열어야 합니다.

477

478각 문자는 한 셀 너비여야 합니다. 이미 화면에 있는 `Raster`를 애니메이션하려면 창의 `id`를 `requestId`로, `Raster`의 `key`를 `key`로, 같은 크기, 그리고 새로운 셀로 `$.ui.blit`을 호출하세요. 이 예제의 경우 `$.ui.blit({ requestId: 'heat', key: 'grid', columns: 3, rows: 2, cells: cellsOf(newRows) })`입니다. 그것은 `ui.render` 훅을 다시 실행하지 않고 그 하나의 요소를 다시 칠합니다.

479

480<h2 id="respond-to-presses-and-typing">

481 누름과 입력에 응답

482</h2>

483

484사용자가 버튼을 누르거나, 필드에 입력하거나, 모드가 그린 목록에서 선택하면 Claude Code는 해당 컨트롤에 준 함수를 호출하고, 모듈에서 실행됩니다. 각 컨트롤은 자신의 콜백을 사용합니다:

485

486* **`Button`**: `onPress(e)`를 사용합니다. 여기서 `e.surface`는 누름이 온 앱입니다

487* **`Input`**: `onSubmit(value)`와 `onInput(value)`를 사용합니다

488* **`Select`**: `onSelect(value)`를 사용합니다. 선택지는 `options`에 있으며, 고유한 값을 가진 최소 하나의 선택지 목록입니다. 예를 들어 `[{ value: 'sm', label: 'Small' }, { value: 'lg', label: 'Large' }]`

489

490테스트는 `key`로 컨트롤을 누르거나 입력하므로 각각에 하나를 주세요. 컨트롤의 각 사용은 또한 [`ui.press`, `ui.input`, 또는 `ui.select`](/docs/ko/plugins/mods/reference#interface)를 `e.element`의 `key`로 발생시키고, 다른 모드는 이러한 이벤트를 훅할 수 있습니다. 그 훅은 콜백 전에 실행되므로 사용자가 `Input`에 입력하는 것을 보고 변경하거나 콜백 대신 답할 수 있습니다. 모드 API에는 다른 모드의 버튼을 누르는 메서드가 없습니다.

491

492<h3 id="know-which-keys-your-mod-can-receive">

493 키보드 포커스와 핫키

494</h3>

495

496모드는 절대 키보드를 직접 읽지 않습니다. 사용자가 키를 누르고, Claude Code는 어느 컨트롤이 그것인지 결정하고, 그 컨트롤의 콜백이 실행됩니다. [밴드의 숫자 핫키](/docs/ko/plugins/mods/reference#elements)를 제외하고, 이는 창이나 밴드가 키보드 포커스를 가질 때만 발생합니다. 나머지 시간에는 키가 프롬프트로 갑니다.

497

498<h4 id="how-a-pane-gets-keyboard-focus">

499 창이 키보드 포커스를 얻는 방법

500</h4>

501

502창은 세 가지 방법 중 하나로 키보드 포커스를 얻습니다:

503

504* 모드가 명령이나 누름에서 `focus: true`로 열기

505* 사용자가 Ctrl+X를 누른 다음 Tab

506* 사용자가 클릭

507

508Claude Code는 프롬프트가 비어 있고 다른 것이 키보드 포커스를 가지지 않을 때만 `focus: true`를 부여합니다. 사용자가 입력하는 동안 열리는 창은 그들의 키 입력을 가져가지 않습니다.

509

510<h4 id="what-each-key-does">

511 각 키가 하는 것

512</h4>

513

514이 표는 창이나 밴드가 키보드 포커스를 가질 때 키가 하는 것을 나열합니다:

515

516| 키 | 무엇을 하는가 |

517| :- | :- |

518| Tab | 다음 컨트롤로 이동 |

519| 위 및 아래 | 그리기가 맞을 때 컨트롤 간 이동. 창이나 밴드가 표시할 수 있는 것보다 더 많은 행을 가지면 스크롤합니다. |

520| Enter | 포커스된 `Button`을 누르거나, 포커스된 `Input`을 제출하거나, `Select`에서 선택 |

521| 버튼의 핫키 | 그 버튼을 누릅니다. `Input`이 포커스를 가질 때 모든 인쇄 가능한 키는 필드로 갑니다. |

522| Esc | 키보드 포커스를 프롬프트로 반환합니다. `closeOnEscape: true`로 창도 닫습니다. |

523

524모드는 Tab이나 화살표 키를 다른 것에 바인드할 수 없으므로 게임은 `w`, `a`, `s`, `d`로 조종합니다.

525

526<h4 id="set-a-hotkey-and-the-first-focus">

527 핫키와 첫 포커스 설정

528</h4>

529

530컨트롤의 두 속성이 키보드가 어떻게 도달하는지 결정합니다:

531

532* **`hotkey`**: 사용자가 `Button`을 한 키로 누르도록 하려면 `hotkey: 'a'`처럼 한 자리 또는 한 소문자의 `hotkey`를 주세요

533* **`autoFocus`**: 창이 열릴 때 어느 컨트롤이 포커스를 가지는지 선택하려면 `autoFocus: true`를 추가하세요. 다른 것에서는 속성을 생략하세요. Claude Code는 `autoFocus: false`를 거부합니다.

534

535핫키가 표시되는 방식은 버튼과 앱에 따라 다릅니다:

536

537| 버튼 | 터미널에서 | 데스크톱 앱에서 |

538| :- | :- | :- |

539| 괄호 포함, 기본값 | `[ Add one ]`, 핫키 표시 없음 | 옆에 작은 키가 있는 레이블 |

540| `plain: true` 포함 | `1: One` | 옆에 작은 키가 있는 레이블 |

541

542터미널에서 괄호가 있는 버튼의 레이블에 키의 이름을 지정하거나 `plain: true`를 사용하여 사용자가 누를 것을 볼 수 있도록 하세요. [요소 참조](/docs/ko/plugins/mods/reference#elements)는 다른 `Button` 규칙을 가집니다: `action`, 밴드의 숫자 핫키, 그리고 한 핫키의 두 버튼.

543

544<h3 id="take-typed-input-and-draw-a-row-for-each-item">

545 입력된 텍스트를 가져오고 각 항목에 대해 행을 그리기

546</h3>

547

548많은 창은 텍스트 필드와 그 아래 목록입니다. 이 섹션의 예제는 노트 창입니다: 노트를 입력하고 Enter를 눌러 추가하고, 각 노트에는 삭제하는 `x` 버튼이 있습니다. 두 개의 노트가 추가되면 터미널은 창을 이렇게 그립니다:

549

550```text theme={null}

551╭──────────────────────────────────────────────────────────╮

552│ Note: Type a note and press Enter ⏎ add ✕ │

553│ x buy milk │

554│ x call bob │

555╰──────────────────────────────────────────────────────────╯

556```

557

558예제는 두 가지 기술을 사용합니다:

559

560* **입력된 텍스트 가져오기**: `Input`은 사용자가 Enter를 누르면 필드의 텍스트로 `onSubmit(value)`를 호출하고, 모든 변경에 `onInput(value)`를 호출합니다

561* **목록 그리기**: 데이터를 각각 하나의 행으로 매핑하고, 모든 행의 버튼에 자신의 `key`를 주세요

562

563이 훅은 창의 내용을 그립니다:

564

565```javascript theme={null}

566// 창이 그리는 목록

567let notes = []

568

569on('ui.render', { component: 'Pane' }, async ($, e, next) => {

570 // id가 'notes'인 창에서만 그리기

571 if (e.requestId !== 'notes') return next(e)

572 const { Box, Text, Button, Input } = $.ui.resolve(e)

573 const redraw = () => $.ui.invalidate('ui.render')

574

575 return Box({

576 flexDirection: 'column',

577 children: [

578 Input({

579 key: 'new-note',

580 label: 'Note',

581 placeholder: 'Type a note and press Enter',

582 // 매번 필드를 비워서 그리기, 제출 후 지우기

583 value: '',

584 submitLabel: 'add',

585 autoFocus: true,

586 // 필드에서 Enter를 누를 때 실행

587 onSubmit: async (value) => {

588 // 빈 줄 무시

589 if (!value.trim()) return

590 notes = [...notes, value.trim()]

591 redraw()

592 await $.store.set('notes', notes)

593 },

594 }),

595 // 각 노트에 대해 한 행: 삭제 버튼, 그 다음 노트의 텍스트

596 ...notes.map((note, i) =>

597 Box({

598 flexDirection: 'row',

599 columnGap: 1,

600 children: [

601 Button({

602 // 자신의 키, 각 행의 버튼을 구별할 수 있도록

603 key: 'delete-' + i,

604 label: 'x',

605 plain: true,

606 onPress: async () => {

607 notes = notes.filter((_, j) => j !== i)

608 redraw()

609 await $.store.set('notes', notes)

610 },

611 }),

612 Text({ children: [note] }),

613 ],

614 }),

615 ),

616 ],

617 })

618})

619```

620

621창을 시도하려면:

622

623* **노트 추가**: 줄을 입력하고 Enter를 누르세요. 줄이 새 행으로 나타나고 필드가 비워집니다.

624* **노트 삭제**: Tab을 누르다가 노트의 `x` 버튼이 포커스를 가질 때까지, 그 다음 Enter를 누르세요. `x`는 버튼의 레이블이고 핫키가 아니므로 문자를 입력해도 누르지 않습니다.

625

626각 변경은 `hello-tabs`와 같은 렌더 사이클을 따릅니다: 콜백이 `notes`를 변경하고, `redraw`를 호출하고, 목록을 `$.store`에 저장합니다.

627

628필드는 `value` 속성 때문에 각 제출 후 비워집니다. `value`는 필드가 그려질 때 보유하는 텍스트이고, 사용자의 입력은 훅이 필드를 다시 그릴 때까지 그것을 대체합니다. 예제는 항상 필드를 `''`로 그립니다.

629

630예제는 노트를 저장하고 로드하지 않습니다. 다음 세션에서 그들을 다시 가져오려면 `hello-tabs`가 `count`를 읽는 방식처럼 `session.start` 훅에서 읽으세요.

631

632세 가지 속성이 필드의 줄을 구성합니다. `Note: Type a note and press Enter ⏎ add`:

633

634| 속성 | 예제에서 | 무엇인가 |

635| :- | :- | :- |

636| `label` | `Note` | 필드 앞의 텍스트. 터미널은 그 뒤에 `: `를 그립니다. |

637| `placeholder` | `Type a note and press Enter` | 필드가 비어 있는 동안 표시되는 흐린 텍스트 |

638| `submitLabel` | `add` | `⏎` 뒤의 단어로 Enter가 하는 것을 말합니다 |

639

640`Input`을 제출해도 [`$.prompt.submit`](/docs/ko/plugins/mods/api#start-a-turn-from-a-background-job)을 호출하지 않으면 턴을 시작하지 않습니다.

641

642<h2 id="redraw-when-something-changes">

643 사이트 다시 그리기

644</h2>

645

646그리기는 스냅샷입니다: 훅이 마지막으로 실행되었을 때 `ui.render` 훅이 반환한 것을 보여줍니다. 새로운 것을 표시하려면 훅이 다시 실행되어야 합니다. Claude Code는 일부 변경에 대해 다시 실행하고, 모드는 나머지를 요청합니다.

647

648<h3 id="when-claude-code-redraws-without-being-asked">

649 Claude Code가 요청받지 않고 다시 그릴 때

650</h3>

651

652Claude Code는 사이트의 속성이 변경되거나 터미널의 너비가 변경될 때 `ui.render` 훅을 다시 실행합니다. 타이머에서 훅을 실행하지 않고, 모듈의 변수가 변경되는 것을 알 수 없습니다.

653

654<h3 id="redraw-when-your-data-changes">

655 데이터가 변경될 때 다시 그리기

656</h3>

657

658데이터가 변경된 후 사이트를 다시 그리려면 `$.ui.invalidate('ui.render')`를 호출하세요. 이 창은 누름을 세습니다. 버튼의 콜백은 `count`를 변경한 다음 다시 그리기를 요청합니다:

659

660```javascript theme={null}

661let count = 0

662

663on('ui.render', { component: 'Pane' }, async ($, e, next) => {

664 if (e.requestId !== 'counter') return next(e)

665 const { Box, Text, Button } = $.ui.resolve(e)

666 return Box({

667 flexDirection: 'row',

668 columnGap: 2,

669 children: [

670 Button({

671 key: 'more',

672 label: 'Add one',

673 onPress: () => {

674 count += 1

675 // 데이터가 변경되었으므로 Claude Code에 창을 다시 그리도록 요청

676 $.ui.invalidate('ui.render')

677 },

678 }),

679 Text({ children: ['Count: ' + count] }),

680 ],

681 })

682})

683```

684

685각 누름은 창의 숫자를 올립니다. [`hello-tabs` 예제](#build-a-pane-with-tabs)는 같은 호출을 `redraw` 함수로 래핑합니다.

686

687[`$.state`](#keep-a-value-in-\$-state)에 보관하는 값은 호출이 필요하지 않습니다. 값을 쓰면 그것을 읽는 사이트가 다시 그려지기 때문입니다.

688

689<h3 id="redraw-on-a-timer">

690 타이머에서 다시 그리기

691</h3>

692

693시계, 카운트다운, 또는 세션 외부의 값을 최신 상태로 유지하려면 일정에 따라 다시 그리세요. 모듈의 `session.start` 훅에서 타이머를 시작하세요. 모듈이 이미 하나를 가지고 있으면, `hello-tabs`처럼, [`$.clock.every`](/docs/ko/plugins/mods/api#run-work-in-the-background) 줄을 추가하세요:

694

695```javascript theme={null}

696on('session.start', async ($, e, next) => {

697 // 1000밀리초마다 Claude Code에 사이트를 다시 그리도록 요청

698 $.clock.every(1000, () => $.ui.invalidate('ui.render'))

699 return next(e)

700})

701```

702

703Claude Code는 이제 `ui.render` 훅을 초당 한 번 실행합니다. 모듈이 다시 로드되면 타이머가 중지되고, 새 복사본이 자신의 것을 시작합니다.

704

705<h3 id="how-often-a-site-can-redraw">

706 사이트가 얼마나 자주 다시 그릴 수 있는가

707</h3>

708

709Claude Code는 사이트가 얼마나 자주 다시 그려지는지 제한하므로 모드는 데이터가 변경될 때마다 `$.ui.invalidate`를 호출할 수 있습니다. 보이는 창과 밴드는 다른 사이트보다 높은 제한을 가지고, [제한 표](/docs/ko/plugins/mods/reference#limits)는 숫자를 가집니다.

710

711제한보다 빠르게 오는 호출은 하나의 다시 그리기로 결합됩니다. 그 다시 그리기는 훅을 한 번 실행하고, 훅은 그 순간의 데이터를 읽으므로 최신 값이 표시되고 그 사이의 값은 표시되지 않습니다. 애니메이션은 제한보다 빠르게 실행될 수 없습니다.

712

713<h2 id="keep-state">

714 상태 유지

715</h2>

716

717모드는 값을 유지하는 세 곳이 있고, 값이 얼마나 오래 지속되는지에 따라 다릅니다: 모듈이 다시 로드될 때까지, 세션이 끝날 때까지, 또는 한 세션에서 다음 세션까지. 값이 얼마나 오래 지속되어야 하는지에 따라 선택하세요:

718

719| 여기에 유지 | 지속되는 기간 | 사용 대상 |

720| :- | :- | :- |

721| 모듈 수준 변수 | 모듈이 다시 로드될 때까지. 개발 중에 파일을 저장할 때마다 발생 | `hello-tabs`의 `tab`처럼 잃을 수 있는 값 |

722| `$.state` | 세션이 끝나거나 사용자가 `/clear`, `/resume`, 또는 `/branch`를 실행할 때까지 | 그리기가 의존하는 값으로 다시 로드를 생존해야 함 |

723| `$.store` | 모드가 삭제하거나, 세션이 [`cleanupPeriodDays`](/docs/ko/settings-reference#cleanupperioddays) 동안 저장소를 읽거나 쓰지 않을 때까지. 저장소는 `~/.claude/plugins/store/` 아래 플러그인 자신의 JSON 파일로 저장되는 키-값 저장소입니다. | 설정, 기록, 사용자가 다음에 찾을 것으로 예상하는 모든 것 |

724

725`$.store.get(key)`는 값 또는 `undefined`로 해결되고, `$.store.set(key, value)`는 모든 JSON 값을 사용합니다.

726

727<h3 id="keep-a-value-in-state">

728 `$.state`에 값 유지

729</h3>

730

731`$.state`는 세션 길이의 값을 유지하고 당신을 위해 다시 그립니다. 이는 반응형 상태입니다: 값을 읽는 `ui.render` 훅이 그것을 구독하므로 Claude Code는 값을 쓸 때마다 그 사이트를 다시 그리고, `$.ui.invalidate`를 호출할 필요가 없습니다. `$.state`의 값은 또한 변수가 하지 않는 모듈의 다시 로드를 생존합니다.

732

733설정하려면 값을 선언하고, 매니페스트를 선언으로 가리키고, 각 값을 정의하고 사용하세요. 예제는 `hello-tabs`에서 `count`를 `$.state`로 이동합니다.

734

735<h4 id="declare-the-values">

736 값 선언

737</h4>

738

739타입 파일에서 값을 선언하세요. 외부 키는 플러그인의 이름이고, 그 아래의 각 항목은 값과 그 타입입니다. 이를 `hello-tabs/types/index.d.ts`로 저장하세요:

740

741```typescript hello-tabs/types/index.d.ts theme={null}

742declare module 'claude-code' {

743 interface PluginState {

744 'hello-tabs': {

745 tab: 'one' | 'two'

746 count: number

747 }

748 }

749}

750```

751

752<h4 id="point-the-manifest-at-the-declaration">

753 매니페스트를 선언으로 가리키기

754</h4>

755

756`claude plugin validate`가 코드를 해당 파일에 대해 확인하도록 하려면 선언의 경로로 매니페스트에 `types` 필드를 추가하세요:

757

758```json hello-tabs/.claude-plugin/plugin.json theme={null}

759{

760 "name": "hello-tabs",

761 "version": "0.1.0",

762 "description": "Opens a pane with two tabs and a counter",

763 "author": { "name": "Your Name" },

764 "types": "./types/index.d.ts"

765}

766```

767

768<h4 id="define-read-and-write-a-value">

769 값 정의, 읽기, 쓰기

770</h4>

771

772모듈에서 각 값을 기본값으로 정의하고, 그리는 동안 읽고, 콜백에서 쓰세요. `atom`은 값과 기본값의 이름을 지정하고, `read`는 반환하고, `update`는 씁니다. 세 가지 도우미는 `$.state.get`과 `$.state.set`을 호출합니다:

773

774```javascript theme={null}

775import { atom, read, update } from 'claude-code'

776

777// 모듈의 맨 위: 값의 이름을 지정하고 기본값을 주기

778const count = atom({ plugin: 'hello-tabs', key: 'count' }, 0)

779

780// ui.render 훅에서: 값을 읽어 그리기

781const n = await read($, count)

782

783// 버튼에서: 이전 값에서 새 값을 쓰기

784onPress: () => update($, count, (value) => value + 1)

785```

786

787`ui.render` 훅이 `count`를 읽었기 때문에 Claude Code는 버튼이 그것을 쓸 때마다 훅을 다시 실행합니다.

788

789코드에 세 가지 규칙이 적용됩니다:

790

791* **`plugin`과 `key`를 리터럴 문자열로 쓰기**: `claude plugin validate`는 소스에서 읽습니다

792* **타입 파일에서 모든 값을 선언하기**: 그렇지 않으면 검증이 `hello-tabs.count is not declared`로 실패합니다

793* **콜백이나 다른 이벤트의 훅에서 쓰기**: `ui.render` 훅은 상태를 읽을 수 있고 쓸 수 없으므로 `onPress`, `onSubmit`, 또는 다른 이벤트의 훅에서 쓰세요

794

795<h4 id="change-hello-tabs-to-use-state">

796 `hello-tabs`를 `$.state` 사용으로 변경

797</h4>

798

799`hello-tabs`에서 `count`를 `$.state`로 이동하려면 그것을 사용하는 모든 줄을 변경하세요:

800

801* **모듈의 맨 위**: `import` 줄을 추가하고, `let count = 0`을 `atom` 줄로 대체

802* **`ui.render` 훅에서**: `tabButton` 전에 `read` 줄을 추가하고, `Text`에서 `'Count: ' + n`을 그리기

803* **Add one 버튼에서**: `onPress`를 [한 세션 이상에서 저장](#save-from-more-than-one-session)의 것으로 대체합니다. 이는 카운트를 저장하고 쓰기도 합니다

804* **`session.start` 훅에서**: `saved`를 읽는 두 줄을 [/clear 후 저장된 값 다시 로드](#load-a-saved-value-again-after-clear)의 `loadCount` 호출로 대체

805

806`tab`이 여전히 변수이므로 `redraw`를 유지하세요.

807

808<h3 id="load-a-saved-value-again-after-clear">

809 `/clear` 후 저장된 값 다시 로드

810</h3>

811

812모드가 `$.store`에서 저장된 값을 `session.start`에서 `$.state`로 복사하면, `/clear`, `/resume`, 또는 `/branch` 후에 다시 복사해야 합니다. 이 명령은 모든 `$.state` 값을 기본값으로 되돌리고, `session.start`는 다시 발생하지 않습니다. [`classic.SessionStart`](/docs/ko/plugins/mods/events#hook-the-settings-hook-events)는 각각 후에 발생하고, `e.source`는 `clear`, `resume`, 또는 `fork`로 설정되므로 값을 다시 복사하세요. 그렇지 않으면 그리기는 기본값을 표시하고, `$.state` 값을 저장하는 콜백은 저장한 것 위에 기본값을 씁니다.

813

814이 코드는 두 훅에서 `count`를 로드합니다. `$.state` 버전의 `hello-tabs`를 기반으로 하며, `count`는 원자이고 `update`는 가져옵니다. `loadCount`를 `register` 위에 놓고, 이미 가지고 있는 `session.start` 훅에 `loadCount` 호출을 추가하세요. `classic.SessionStart`는 또한 시작 시 그리고 압축 후에 발생하며, 이는 `$.state`를 재설정하지 않으므로 `source`의 필터는 훅을 세 가지 재설정으로 유지합니다:

815

816```javascript theme={null}

817// $.store에서 저장된 카운트를 $.state로 복사하거나, 아무것도 저장되지 않으면 0

818async function loadCount($) {

819 const saved = Number((await $.store.get('count')) ?? 0)

820 await update($, count, () => saved)

821}

822

823// 첫 프롬프트 전에 실행되고, 다시 로드 후에도 실행됨

824on('session.start', async ($, e, next) => {

825 await loadCount($)

826 return next(e)

827})

828

829// /clear, /resume, /branch 후에 다시 실행되며, fork를 보고합니다

830on('classic.SessionStart', { source: ['clear', 'resume', 'fork'] }, async ($, e, next) => {

831 await loadCount($)

832 return next(e)

833})

834```

835

836두 훅이 제자리에 있으면 창은 `/clear` 후 저장된 카운트를 표시하고 `0`이 아니며, **Add one**의 다음 누름은 저장된 카운트에 추가합니다.

837

838`loadCount`는 `$.state`의 값 위에 저장된 값을 쓰고, `session.start`는 모듈이 다시 로드될 때마다 다시 발생합니다. 저장소가 뒤처지지 않도록 하려면 모든 변경에 저장하세요. **Add one** 버튼이 하는 것처럼.

839

840다시 로드를 세션 없이 확인하려면 [`/clear` 후 그리기를 테스트](/docs/ko/plugins/mods/test#test-a-drawing-after-clear)하세요.

841

842<h3 id="save-from-more-than-one-session">

843 한 세션 이상에서 저장

844</h3>

845

846머신의 모든 세션이 모드를 실행하면 하나의 `$.store`를 공유합니다. `get` 다음에 `set`은 원자적이지 않습니다. 두 세션이 각각 값을 읽고, 변경하고, 다시 쓸 때 경쟁하고, 두 번째 쓰기가 첫 번째를 대체합니다.

847

848두 가지 선택이 그것을 덜 가능하게 합니다:

849

850* **각 항목에 자신의 키를 주기**: `set`은 자신의 키만 변경하므로 다른 키를 쓰는 세션은 서로를 덮어쓰지 않습니다

851* **쓰기 바로 전에 다시 읽기**: 여러 세션이 변경하는 값의 경우, 콜백에서 키를 `get`하고 `session.start`에서 로드한 복사본이 아닌 그것에서 새 값을 빌드하세요. 다른 세션의 쓰기는 여전히 `get`과 `set` 사이에 착지하면 손실됩니다.

852

853이 버튼은 저장소가 지금 보유하는 것에 1을 더한 다음 그리기를 업데이트합니다:

854

855```javascript theme={null}

856onPress: async () => {

857 // 저장소가 지금 보유하는 것을 읽기, 다른 세션이 변경했을 수 있음

858 const saved = Number((await $.store.get('count')) ?? 0)

859 // 새 카운트를 저장한 다음 표시

860 await $.store.set('count', saved + 1)

861 await update($, count, () => saved + 1)

862}

863```

864

865두 번째 세션이 이 세션이 시작된 이후로 자신의 버튼을 세 번 눌렀다면, 이 누름은 그 세 개를 포함하는 카운트를 표시하고 저장합니다.

866

867<h2 id="next-steps">

868 다음 단계

869</h2>

870

871* [이벤트에 반응](/docs/ko/plugins/mods/events): 도구 호출과 턴에서 그리기 공급

872* [모드 API 사용](/docs/ko/plugins/mods/api): 타이머와 모델 호출에서 그리기 공급

873* [그리기 테스트](/docs/ko/plugins/mods/test#test-a-drawing): 테스트에서 버튼을 누르기, 한 개 이상의 표면에서

874* [렌더 사이트](/docs/ko/plugins/mods/reference#render-sites)와 [요소](/docs/ko/plugins/mods/reference#elements): 각 사이트의 속성과 각 요소의 속성

plugins/mods/overview.md +269 −0 created

Details

1> ## Documentation Index

2> 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.

5# Mods 개요

7> mod를 사용하여 Claude Code에 창, 명령, 도구 호출 규칙을 추가합니다. mod가 할 수 있는 것, mod를 만들거나 설치하는 방법, mod가 실행되는 위치를 확인합니다.

9mod는 Claude Code의 모양과 동작을 변경하는 [플러그인](/docs/ko/plugins/overview)입니다. JavaScript 또는 TypeScript 이벤트 핸들러로 구성됩니다. Claude Code는 도구 호출, 제출된 프롬프트, 인터페이스의 일부가 그려지는 것과 같은 이벤트가 발생할 때 하나를 호출하며, 핸들러는 이벤트를 감시하거나, 변경하거나, 인수할 수 있습니다. mod를 사용하여 각 요청 후 컨텍스트가 얼마나 찼는지 차트로 표시하는 창과 같이 Claude Code에 자신만의 기능을 추가합니다. mod의 파일과 완전한 예제는 [mod의 작동 방식](#how-a-mod-works)을 참조합니다.

11<Note>

12 Claude Code의 기존 [hooks](/docs/ko/hooks)도 이벤트에서 실행되며, 설정 파일에서 구성하는 셸 명령, HTTP 요청 또는 프롬프트입니다. mod의 핸들러는 Claude Code 내부에서 실행되는 함수입니다. Claude Code는 두 종류의 hooks를 모두 호출합니다. 이 페이지에서 "hook"은 mod의 핸들러를 의미하고, 설정 파일 종류는 "설정 hook"입니다.

13</Note>

15<h2 id="what-a-mod-can-do">

16 mod가 할 수 있는 것

17</h2>

19설정 hooks, skills, 상태 줄, MCP 서버는 Claude Code 외부에서 작동합니다. 각각 스크립트를 실행하거나 Claude에 텍스트 또는 도구를 제공합니다. mod는 Claude Code 내부에서 실행되므로 다음을 수행할 수 있습니다:

21* **사용할 수 있는 인터페이스 그리기**: 대화 옆의 창 또는 프롬프트 위의 밴드, 탭, 버튼, 텍스트 필드 포함. [인터페이스에 그리기](/docs/ko/plugins/mods/interface)를 참조합니다.

22* **Claude Code 자체 인터페이스 다시 그리기**: Claude Code가 자체적으로 그리는 부분(예: 도구 호출의 행, 스피너 또는 Claude가 질문하는 대화)을 교체하거나 다시 스타일링합니다. [Claude Code가 이미 그린 것 변경](/docs/ko/plugins/mods/interface#change-what-claude-code-already-draws)을 참조합니다.

23* **도구 호출 또는 요청에 개입**: 예를 들어, 도구 호출을 유지하면서 사용자에게 질문하고, 도구를 실행하지 않고 답변하거나, 한 요청을 다른 모델로 보냅니다. [도구 호출 보호 또는 변경](/docs/ko/plugins/mods/events#guard-or-change-a-tool-call) 및 [턴 따르기](/docs/ko/plugins/mods/events#follow-a-turn)를 참조합니다.

24* **명령에서 자신의 코드 실행**: Claude 턴 없이 즉시 실행되는 `/command`, Claude가 작업 중일 때도 실행됩니다. [명령 또는 도구 추가](/docs/ko/plugins/mods/api#add-a-command-or-a-tool)를 참조합니다.

25* **hooks 간 데이터 공유**: mod의 hooks는 파일의 변수를 공유하므로 한 hook이 기록하는 것을 다른 hook이 표시할 수 있습니다. 예를 들어, 한 hook은 도구 호출을 세면서 다른 hook은 스피너 옆에 개수를 표시하거나, 한 hook은 각 요청의 토큰 사용량을 읽으면서 다른 hook은 창에서 차트로 표시할 수 있습니다. [이벤트에 반응](/docs/ko/plugins/mods/events)을 참조합니다.

27Mods는 Claude Code CLI 및 Claude Desktop 앱의 Code 탭에서 작동합니다. VS Code 확장, `claude -p`, 클라우드 세션과 같은 다른 위치에서의 동작을 이해하려면 [mods가 실행되는 위치](#where-mods-run)를 참조합니다. 설정 hook, skill 또는 MCP 서버가 이미 필요한 것을 수행하면, mod를 작성하기 전에 [비교](#compare-mods-settings-hooks-skills-and-mcp-servers)합니다. 조직의 mods를 관리하려면 [조직의 mods 관리](/docs/ko/plugins/mods/admin)를 참조합니다.

29<h2 id="get-a-mod">

30 mod 가져오기

31</h2>

33다음 세 가지 방법 중 하나로 mod를 시작할 수 있습니다:

35* **이미 가지고 있는 것 사용**: Claude Code의 일부 기능은 `/diff`와 같은 mods입니다. [Claude Code에 내장된 Mods](#mods-built-into-claude-code)를 참조합니다.

36* **하나 만들기**: Claude Code 세션에서 원하는 것을 설명하면 Claude가 mod를 작성합니다. [Claude에 mod 요청](/docs/ko/plugins/mods/create#ask-claude-for-a-mod)을 참조합니다. mod의 코드가 어떻게 작동하는지 배우려면 [직접 작성](/docs/ko/plugins/mods/create#write-a-mod-yourself)합니다.

37* **하나 설치**: [mod 설치 또는 업데이트](#install-or-update-a-mod)를 참조합니다.

39<h3 id="install-or-update-a-mod">

40 mod 설치 또는 업데이트

41</h3>

43<Warning>

44 mod는 사용자의 권한으로 실행되는 코드입니다. 파일을 읽고 쓰고, 프로세스를 시작하고, 네트워크 요청을 할 수 있습니다. 신뢰하는 작성자 및 마켓플레이스에서만 mods를 설치합니다. [mod를 신뢰할지 결정](#decide-whether-to-trust-a-mod)을 참조합니다.

45</Warning>

47mod는 마켓플레이스에서 플러그인으로 설치됩니다. 플러그인의 이름, `@`, 마켓플레이스의 이름을 제공합니다. 이 예제는 `your-org`라는 마켓플레이스에서 `token-chart`라는 플러그인을 설치합니다:

49* Claude Code 세션에서 `/plugin install token-chart@your-org`를 실행합니다.

50* 셸에서 `claude plugin install token-chart@your-org`를 실행합니다.

52[플러그인 설치](/docs/ko/plugins/install)는 마켓플레이스, 범위, VS Code 확장 및 Desktop 앱, [플러그인 업데이트 유지](/docs/ko/plugins/install#keep-plugins-updated)를 다룹니다. 이는 mod를 포함하는 플러그인에 변경 없이 적용됩니다.

54세션이 열려 있는 동안 셸에서 mod를 설치하거나 업데이트하면, 해당 세션에서 `/reload-plugins`를 실행하여 로드합니다. 그렇지 않으면 Claude Code를 다음에 시작할 때 로드됩니다.

56<h2 id="decide-whether-to-trust-a-mod">

57 모드를 신뢰할지 결정하기

58</h2>

60모드는 Claude Code 내에서 사용자의 권한으로 실행되는 코드입니다. 신뢰하는 작성자 및 [마켓플레이스에서만 모드를 설치하십시오](/docs/ko/plugins/security).

62<h3 id="what-a-mod-can-reach">

63 모드가 접근할 수 있는 것

64</h3>

66모드는 사용자의 권한으로 실행되므로, 설치하기 전에 어떤 것에 접근할 수 있는지 알아야 합니다. 모드가 로드되면 다음을 수행할 수 있습니다:

68* **사용자로서 머신에서 작동**: 사용자 계정이 접근할 수 있는 모든 곳에서 파일을 읽고 쓰기, 프로그램 시작, 네트워크 요청 수행

69* **비밀 정보 읽기**: 환경 변수 및 설정 파일(API 키 포함)

70* **세션 확인**: 사용자가 보내는 모든 프롬프트 및 Claude가 수행하는 모든 도구 호출 확인

71* **세션 변경**: 프롬프트 또는 도구 호출 재작성, 사용자가 입력한 것처럼 프롬프트 제출, 다른 세션으로 메시지 전송

72* **사용자에게 묻지 않고 작동**: 사용자에게 묻기 전에 도구 호출 승인

73* **사용량 소비**: 플랜 또는 API 키의 모델 호출

75도구 호출을 승인하는 모드는 `ask` 규칙이 프롬프트하는 호출이나 사용자의 `PreToolUse` 훅이 차단한 호출을 승인할 수 있습니다. [훅으로 권한 확장하기](/docs/ko/permissions#extend-permissions-with-hooks)에서는 이러한 모드가 승인할 수 있는 것(예: `deny` 규칙이 거부하는 호출을 승인할 수 있는 경우 포함)을 나열합니다.

77모드는 Claude Code 인터페이스의 대부분을 다시 스타일링할 수 있지만, 권한 프롬프트는 변경할 수 없습니다. 프롬프트가 표시하는 내용을 변경할 수 없습니다.

79<h3 id="list-what-a-mod-does-before-you-install-one">

80 설치하기 전에 모드가 수행하는 작업 나열하기

81</h3>

83모드를 설치하기 전에, 모드가 훅하는 이벤트와 파일 읽기 또는 네트워크 요청 수행과 같이 Claude Code에 요청하는 작업을 실행하지 않고 나열할 수 있습니다. 먼저 플러그인의 파일을 가져옵니다(예: 저장소 복제). 그런 다음 셸에서 플러그인 디렉터리에 대해 `claude plugin validate`를 실행합니다:

85```bash theme={null}

86claude plugin validate ./some-mod

87```

89출력의 `hooks:` 및 `calls:` 줄은 모드가 처리하는 이벤트와 Claude Code에 요청하는 작업을 나열합니다. [모드가 수행할 수 있는 작업 검토하기](/docs/ko/plugins/mods/admin#review-what-a-mod-can-do)에서는 출력과 확인할 호출을 보여줍니다.

91<h2 id="turn-mods-on-or-off">

92 mods 켜기 또는 끄기

93</h2>

95Mods는 Claude Code v2.1.287 이상이 필요하며 기본적으로 켜져 있습니다. 셸에서 `claude --version`을 실행하여 확인하고, 더 오래된 경우 Claude Code를 업데이트합니다.

97mods를 끄려면 중지할 개수와 기간을 선택합니다. 다시 켜려면 동일한 변경을 취소합니다:

99* **하나의 mod**: [`/plugin`의 **설치됨** 탭](/docs/ko/plugins/install#manage-installed-plugins)에서 플러그인을 비활성화하거나 제거합니다.

100* **모든 설치된 mod, 한 세션 동안**: [`--safe-mode`](/docs/ko/cli-reference#cli-flags)로 Claude Code를 시작합니다. 이는 다른 사용자 정의도 제외합니다.

101* **설치한 모든 mod, 모든 세션에서**: `~/.claude/settings.json`에서 [`"disableAllHooks": true`](/docs/ko/settings-reference#disableallhooks)를 설정합니다. 설정 hooks 및 사용자 정의 상태 줄도 중지됩니다. 조직이 관리하는 것은 계속 실행됩니다.

102

103조직을 통해 Claude Code를 사용하면 관리자가 로드되는 mods를 제한할 수도 있습니다. 관리자는 [사용자 설치 mods가 로드되지 않도록 중지](/docs/ko/plugins/mods/admin#stop-user-installed-mods-from-loading)에서 시작합니다.

104

105mods가 로드될 수 있는지 확인하려면 [mods가 로드될 수 있는지 확인](/docs/ko/plugins/mods/troubleshoot#check-whether-mods-can-load)을 참조합니다.

106

107<Note>

108 초기 액세스 중에 `CLAUDE_CODE_ENABLE_FUNCTION_HOOKS`를 설정한 경우 제거합니다. Claude Code v2.1.287 이상은 이를 무시하므로 `0`으로 설정해도 mods가 꺼지지 않습니다.

109</Note>

110

111<h3 id="see-which-mods-a-session-loaded">

112 세션이 로드한 mods 보기

113</h3>

114

115터미널 세션이 로드한 mods를 보려면 Claude Code 프롬프트에서 `/plugin`을 실행합니다. 탭 아래의 흐린 줄은 개수와 이름(예: `1 mod active · first-mod`)을 제공합니다. 설치한 mod가 거기에 이름이 없으면 [mod가 아무것도 하지 않는 이유 찾기](/docs/ko/plugins/mods/troubleshoot#find-out-why-a-mod-does-nothing)를 참조합니다.

116

117<h2 id="how-a-mod-works">

118 mod의 작동 방식

119</h2>

120

121mod는 hooks라고 불리는 이벤트 핸들러를 등록하는 [플러그인](/docs/ko/plugins/overview)입니다. Claude Code는 Claude가 도구를 호출하거나 스피너가 그려질 때와 같은 이벤트가 발생할 때 hook을 실행합니다. 작은 mod는 세 개의 파일을 가집니다:

122

123```text theme={null}

124first-mod/

125├── .claude-plugin/

126│ └── plugin.json

127└── hooks/

128 ├── hooks.json

129 └── register.js

130```

131

132* **`plugin.json`**: 플러그인의 [매니페스트](/docs/ko/plugins/manifest-reference)

133* **`hooks.json`**: [코드 파일을 가리킵니다](/docs/ko/plugins/mods/reference#files)

134* **`register.js`**: [코드](/docs/ko/plugins/mods/create#write-a-mod-yourself), hooks 모듈이라고 불립니다. Claude Code에 어떤 이벤트에서 함수를 실행할지 알려줍니다.

135

136이것은 완전한 `register.js`입니다. Claude가 수행하는 도구 호출을 세고 Claude가 작업하는 동안 스피너 옆에 개수를 표시합니다(예: `Thinking · tool calls: 3…`).

137

138```javascript hooks/register.js theme={null}

139// 아래의 두 hooks로 공유되는 개수

140let calls = 0

141

142// Claude Code는 mod가 로드될 때 이것을 한 번 호출합니다

143export function register(on) {

144 // Claude가 도구를 사용하려고 할 때마다 실행됩니다

145 on('tool.call', async ($, e, next) => {

146 calls += 1

147 // Claude Code에 인터페이스를 다시 그리도록 요청하여 새 개수가 표시되도록 합니다

148 $.ui.invalidate('ui.render')

149 // 도구가 평소대로 실행되도록 합니다

150 return next(e)

151 })

152

153 // Claude Code가 스피너를 그릴 때마다 실행됩니다

154 on('ui.render', { component: 'Spinner' }, async ($, e, next) => {

155 // Claude Code의 스피너를 유지하고 단어 뒤에 개수를 추가합니다

156 return next({ ...e, props: { ...e.props, suffix: ' · tool calls: ' + calls + '…' } })

157 })

158}

159```

160

161파일은 두 개의 hooks를 등록하고 둘 다 맨 위의 `calls` 변수를 사용합니다:

162

163* **[`tool.call`](/docs/ko/plugins/mods/reference#tools) hook**은 Claude가 도구를 사용하려고 할 때마다 실행됩니다. `calls`에 1을 더하고, Claude Code에 인터페이스를 다시 그리도록 요청하고, 도구가 평소대로 실행되도록 합니다.

164* **[`ui.render`](/docs/ko/plugins/mods/reference#interface) hook**은 Claude Code가 스피너를 그릴 때마다 실행됩니다. Claude Code의 스피너를 유지하고 단어 뒤에 개수를 추가합니다.

165

166이 기록은 mod가 작동하는 것을 보여줍니다. 프롬프트 상자 위의 스피너 줄을 보세요. Claude가 디렉토리를 나열하고 두 파일을 읽는 동안 `Thinking · tool calls: 1…`, 그 다음 `2…`, 그 다음 `3…`을 읽습니다.

167

168<Frame>

169 <video autoPlay muted loop playsInline controls className="w-full dark:hidden" src="https://mintcdn.com/claude-code/dgiVO_Od1X1faduV/images/mods-overview-light.mp4?fit=max&auto=format&n=dgiVO_Od1X1faduV&q=85&s=00a18aa0743b59a700f0275ce226e6d1" aria-label="Claude Code 세션에서 '여기 파일을 나열하고 README를 읽기' 프롬프트가 입력되고 전송됩니다. Claude가 작업하는 동안 스피너는 '생각 중 · tool calls: 1', 그 다음 2, 그 다음 3을 읽습니다. Claude가 파일을 나열하고 두 개를 읽습니다." data-path="images/mods-overview-light.mp4" />

170

171 <video autoPlay muted loop playsInline controls className="w-full hidden dark:block" src="https://mintcdn.com/claude-code/dgiVO_Od1X1faduV/images/mods-overview-dark.mp4?fit=max&auto=format&n=dgiVO_Od1X1faduV&q=85&s=d5223da2fef16ceaaa214a36d72c0536" aria-label="Claude Code 세션에서 '여기 파일을 나열하고 README를 읽기' 프롬프트가 입력되고 전송됩니다. Claude가 작업하는 동안 스피너는 '생각 중 · tool calls: 1', 그 다음 2, 그 다음 3을 읽습니다. Claude가 파일을 나열하고 두 개를 읽습니다." data-path="images/mods-overview-dark.mp4" />

172</Frame>

173

174<h3 id="what-a-hook-can-do-with-an-event">

175 hook이 이벤트로 할 수 있는 것

176</h3>

177

178Claude Code는 이벤트에 작용하기 전에 hook을 실행하므로 hook이 다음에 일어날 일을 결정합니다. 세 가지 선택이 있습니다:

179

180* **관찰**: 일어나는 일을 기록하고 예제의 `tool.call` hook처럼 변경되지 않은 상태로 계속합니다.

181* **다시 작성**: 이벤트를 변경한 후 계속합니다. `ui.render` hook이 스피너에 개수를 추가할 때처럼 합니다.

182* **답변**: 이벤트를 자체적으로 처리하여 일반적인 동작이 실행되지 않습니다(예: 명령 거부).

183

184자신의 코드 외부에서 무언가를 수행하려면(예: 그리기, 명령 추가, 모델 호출, 파일 읽기, 프로세스 시작 또는 네트워크 요청), hook은 mods API를 호출합니다. hook은 이러한 작업을 수행할 다른 방법이 없으므로 Claude Code가 [mod를 설치하기 전에 mod가 수행하는 작업을 나열](#list-what-a-mod-does-before-you-install-one)할 수 있습니다.

185

186각 선택 뒤의 코드는 [이벤트에 반응](/docs/ko/plugins/mods/events#how-a-hook-handles-an-event)을 참조합니다. hook이 호출할 수 있는 것은 [mods API 사용](/docs/ko/plugins/mods/api)을 참조합니다.

187

188<h3 id="where-mods-run">

189 mods가 실행되는 위치

190</h3>

191

192mod의 hooks는 플러그인을 로드하는 모든 종류의 세션에서 실행됩니다. 그리기는 더 좁습니다. 터미널과 Desktop 앱만 mod의 창, 밴드, 교체된 행을 표시합니다. 이 표는 Claude Code를 실행할 수 있는 각 위치를 나열합니다:

193

194| Claude Code를 실행하는 위치 | Hooks 실행 | mod가 그리는 것이 나타나는 위치 |

195| :- | :- | :- |

196| 터미널의 `claude`, 편집기의 통합 터미널 및 JetBrains 플러그인 포함 | 예 | 예 |

197| Desktop 앱의 Code 탭, WSL 세션 제외 | 예 | 예, [elements 표](/docs/ko/plugins/mods/reference#elements)가 터미널 전용으로 표시하는 요소 제외 |

198| Desktop 앱의 [WSL 세션](/docs/ko/desktop-wsl) | 아니요, WSL 세션에서는 플러그인을 사용할 수 없기 때문입니다 | 아니요 |

199| VS Code 확장의 채팅 패널 | 예 | 아니요 |

200| `claude -p` 및 [Agent SDK](/docs/ko/agent-sdk/overview) | 예 | 아니요 |

201| claude.ai 또는 모바일 앱에서 [Remote Control](/docs/ko/remote-control) | 예, 머신의 세션에서 | 머신의 터미널에서 |

202| [클라우드 세션](/docs/ko/claude-code-on-the-web) | 예, [클라우드 세션에 도달하는](/docs/ko/cloud-environments#what-carries-over-from-your-setup) 플러그인의 경우 | 아니요 |

203

204그리는 mod는 실행 중인 앱을 확인하고 아무것도 그리지 않는 대화 또는 명령의 텍스트 응답으로 폴백할 수 있습니다.

205

206<h2 id="control-mods-for-your-organization">

207 조직의 mods 제어

208</h2>

209

210관리자는 [관리 설정](/docs/ko/managed-settings)을 통해 mods가 실행되는지 여부와 어떤 것이 실행되는지 결정합니다. [조직의 mods 관리](/docs/ko/plugins/mods/admin)는 기본적으로 일어나는 일, mod를 검토하는 방법, mod로 정책을 적용하는 방법을 다룹니다.

211

212<h2 id="compare-mods-settings-hooks-skills-and-mcp-servers">

213 mods, 설정 hooks, skills, MCP 서버 비교

214</h2>

215

216Mods, 설정 hooks, skills, MCP 서버는 겹칩니다. 이 표는 각각이 무엇이고 언제 선택할지 보여줍니다.

217

218| | Mod | 설정 hook | Skill | MCP 서버 |

219| :- | :- | :- | :- | :- |

222| 인터페이스에 그릴 수 있는가 | 예 | 아니요 | 아니요 | 아니요 |

225

226각각의 다른 것은 자신의 페이지를 가집니다: [Hooks](/docs/ko/hooks), [Skills](/docs/ko/skills), [MCP](/docs/ko/mcp). 플러그인은 네 가지를 모두 보유할 수 있으므로 mod는 skill 및 MCP 서버와 동일한 플러그인에 포함될 수 있습니다.

227

228<h2 id="mods-built-into-claude-code">

229 Claude Code에 내장된 Mods

230</h2>

231

232Claude Code의 일부 기능은 mods입니다. 세션이 가진 것을 보려면 Claude Code 프롬프트에서 `/plugin`을 실행하고 **설치됨** 탭으로 이동하여 **내장**에 나열된 것을 확인합니다. 내장 mod를 업데이트하거나 제거할 수 없으며, 표의 마지막 열은 각각을 끄는 방법을 설명합니다. [`mods active` 줄](#see-which-mods-a-session-loaded)은 내장 mods를 제외합니다.

233

234이 표는 `/plugin`이 표시하는 이름으로 각 항목을 나열합니다:

235

237| :- | :- | :- | :- |

238| `cc-plugin-agents-md` | `AGENTS.md`를 프로젝트 지침으로 로드합니다 | 모든 세션, [AGENTS.md를 읽을 수 없는 것](/docs/ko/memory#when-agents-md-support-is-unavailable) 제외 | `/plugin`에서 비활성화하거나 [로드되는 지침 파일 선택](/docs/ko/memory#choose-which-instruction-files-load) |

240| `cc-plugin-plugin-authoring` | Claude에 mods를 작성하기 위한 [`plugin-authoring` skill](/docs/ko/plugins/mods/create#ask-claude-for-a-mod)을 제공합니다. skill을 보유하고 mod 코드는 없습니다. | Anthropic이 설치된 mods를 원격으로 끄지 않은 경우 | `/plugin`에서 비활성화합니다 |

241| `cc-plugin-sec-default` | 사용자가 설치한 mods로부터 조직이 관리하는 것을 보호합니다 | [가드가 로드되는 위치](/docs/ko/plugins/mods/admin#know-what-happens-by-default) | 할 수 없습니다. 관리자가 [순서를 설정](/docs/ko/plugins/mods/admin#install-your-organizations-mods)합니다 |

243| `cc-plugin-you-should-know` | Claude가 더 긴 작업을 수행하는 동안 당신을 지켜보는 측면 에이전트를 실행합니다. 놓칠 수 있는 가치 있는 정보를 찾으면 프롬프트 위에 메모를 표시합니다. | 기본적으로 비활성화됩니다. 조직에서 사용 가능한 경우 `/plugin` -> **설치됨** -> **비활성화된 항목 표시**에 나열됩니다. [`/plugin enable cc-plugin-you-should-know@builtin`](/docs/ko/plugins/cli-reference#plugin-in-a-session)으로 활성화합니다. | `/plugin`에서 비활성화합니다 |

244

245설치된 mods를 중지하는 설정 및 플래그(예: `disableAllHooks`, `--bare`, `--safe-mode`)는 내장 mods를 중지하지 않습니다.

246

247<h3 id="read-the-source-of-built-in-mods">

248 내장 mods의 소스 읽기

249</h3>

250

251이러한 mods의 소스는 [Claude Code 저장소의 `mods` 디렉토리](https://github.com/anthropics/claude-code/tree/main/mods)에서 공개적으로 사용 가능합니다. 각각은 hooks 모듈 및 테스트가 있는 완전한 플러그인입니다:

252

253* [`diff`](https://github.com/anthropics/claude-code/tree/main/mods/diff): `/diff` 창, 키보드 작업에 바인딩된 버튼 및 mod가 처리하는 스크롤링

254* [`agents-md`](https://github.com/anthropics/claude-code/tree/main/mods/agents-md): `AGENTS.md`를 프로젝트 지침으로 로드, [`userConfig`](/docs/ko/plugins/components#user-configuration) 옵션 포함

255* [`sec-default`](https://github.com/anthropics/claude-code/tree/main/mods/sec-default): [기본적으로 일어나는 일 알기](/docs/ko/plugins/mods/admin#know-what-happens-by-default)에 설명된 가드, mod가 정책을 적용하는 모델

256* [`telemetry`](https://github.com/anthropics/claude-code/tree/main/mods/telemetry): 다른 mods가 호출할 수 있는 메서드를 추가하고 유형을 제공합니다

257

258<h2 id="next-steps">

259 다음 단계

260</h2>

261

262* [mod 만들기](/docs/ko/plugins/mods/create): 도구 호출을 세고, 스피너 옆에 개수를 표시하고, 명령을 추가하는 것을 만들고, 편집 및 다시 로드 루프를 배웁니다.

263* [인터페이스에 그리기](/docs/ko/plugins/mods/interface): 창, 프롬프트 위의 밴드, 버튼, 텍스트 필드, 상태

264* [이벤트에 반응](/docs/ko/plugins/mods/events): 도구 호출, 프롬프트, 턴, mods가 실행되는 순서

265* [mods API 사용](/docs/ko/plugins/mods/api): 명령, 도구, 모델 호출, 타이머, 파일

266* [mod 테스트](/docs/ko/plugins/mods/test): 세션 없이 실행되는 자동화된 테스트

267* [mod 문제 해결](/docs/ko/plugins/mods/troubleshoot): mod가 아무것도 하지 않는 이유, 디버그 로그

268* [조직의 mods 관리](/docs/ko/plugins/mods/admin): 기본값, 관리 설정, mod 검토, 정책 mods

269* [Mods 참조](/docs/ko/plugins/mods/reference): 모든 이벤트, 메서드, 요소, 제한

plugins/mods/test.md +422 −0 created

Details

1> ## Documentation Index

2> 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.

5# 모드 테스트

7> 이벤트를 발생시키고, Claude Code의 답변을 스텁하고, 버튼을 누르는 Claude Code 모드에 대한 자동화된 테스트를 작성합니다. 세션, 로그인, 네트워크가 필요하지 않습니다.

9모드에 대한 자동화된 테스트를 작성하고 [`claude plugin test`](/docs/ko/plugins/mods/reference#commands)를 사용하여 셸에서 실행할 수 있습니다. 테스트는 훅이 처리하는 이벤트를 발생시키고 훅이 수행한 작업을 확인하므로 세션에 도달하기 전에 문제를 발견할 수 있습니다. 첫 번째 예제는 [모드 만들기](/docs/ko/plugins/mods/create)의 모드를 테스트합니다.

11<h2 id="write-a-test">

12 테스트 작성

13</h2>

15테스트는 모드를 로드하고, Claude Code가 하는 방식으로 훅을 통해 이벤트를 보내고, 세션, 로그인, 네트워크 없이 훅이 수행한 작업을 확인합니다. 셸에서 `claude plugin test`를 사용하여 테스트를 실행하며, 각 테스트 파일은 `claude-code/testing` 모듈의 테스트 라이브러리인 테스트 키트를 가져옵니다.

17각 테스트 파일에 `first-mod.test.ts`와 같이 `.test.ts`로 끝나는 이름을 지정하고 플러그인 디렉토리의 어디든지 저장합니다. 모든 테스트 파일에는 최소한 하나의 `test()`가 필요하며, 그렇지 않으면 `declares no test(): nothing ran`으로 실행이 실패합니다. 테스트 파일은 모드의 자체 파일과 형제 `.ts` 헬퍼를 가져올 수 있으므로 게임의 규칙과 같은 일반 함수를 키트 없이 단위 테스트할 수 있습니다.

19이 테스트는 두 개의 도구 호출을 발생시키고, [모드 만들기](/docs/ko/plugins/mods/create)의 `/tally` 명령을 실행하고, 회신이 둘 다 계산하는지 확인합니다. 첫 번째 줄은 [스텁](#stub-what-claude-code-would-answer)이며, Claude Code 대신 도구 호출에 답변합니다. `first-mod/tests/first-mod.test.ts`로 저장합니다:

21```typescript first-mod/tests/first-mod.test.ts theme={null}

22import { expect, test } from 'claude-code/testing'

24test('/tally reports the tool calls the mod has seen', async ($, on) => {

25 // Answer each tool call in Claude Code's place, so no tool runs

26 on('tool.call', () => ({ result: 'ok' }))

28 // Raise two tool calls, which the mod's tool.call hook counts

29 await $.tool.call({ tool: 'Bash', command: 'ls' })

30 await $.tool.call({ tool: 'Read', file_path: 'README.md' })

32 // Run /tally and check the text its hook returns

33 const answer = await $.command.run({ command: 'tally', args: '' })

34 expect(answer.text).toBe('Claude has made 2 tool calls since this mod loaded')

35})

36```

38셸에서 `first-mod` 디렉토리에서 테스트를 실행합니다:

40```bash theme={null}

41claude plugin test

42```

44출력은 각 테스트와 통과 여부를 이름으로 지정하며, 실행마다 다양한 타이밍을 표시합니다:

46```text theme={null}

47tests/first-mod.test.ts:

48(pass) /tally reports the tool calls the mod has seen [22.87ms]

50 1 pass

51 0 fail

52Ran 1 test across 1 file. [0.19s]

53```

55각 `$.tool.call`은 모드의 [`tool.call`](/docs/ko/plugins/mods/reference#tools) 훅을 통과했으며, 이는 개수에 1을 더하고 호출을 스텁으로 전달했습니다. `ls`는 실행되지 않았고 파일도 읽지 않았습니다. `$.command.run`은 모드의 [`command.run`](/docs/ko/plugins/mods/reference#commands-and-configuration) 훅으로 이동했으며, `answer`는 해당 훅이 반환한 객체입니다.

57테스트가 실패하면 명령이 상태 1로 종료되므로 CI에서 작동합니다. 자신의 모드를 실행하는 셸에서 로드할 수 없으면 `claude plugin test: hooks modules are turned off`로 시작하는 줄을 이유와 함께 출력하고 상태 1로 종료합니다.

59<h3 id="stub-what-claude-code-would-answer">

60 Claude Code가 답변할 내용 스텁하기

61</h3>

63테스트에서는 모델, 저장소, 도구가 실행되지 않으므로 모드가 Claude Code의 답변을 기대하는 곳마다 테스트는 스텁으로 답변을 제공합니다. 테스트 함수는 다음 두 가지 인수를 받습니다:

65* **`$`**: 테스트의 자체 `$`이며, Claude Code가 있는 곳에 서 있습니다. 훅이 받는 [mods API](/docs/ko/plugins/mods/reference#mods-api-methods)가 아닙니다. 각 메서드는 같은 이름의 이벤트를 발생시키고, 모드의 훅을 통해 보내고, 결과로 해결됩니다: `$.tool.call({ tool: 'Bash', command: 'ls' })`는 `tool.call`을 발생시킵니다. `$.command.run`, `$.prompt.submit`, `$.session.start`, `$.turn.complete`는 같은 방식으로 작동하며, `$.classic.Stop` 및 기타 `$.classic` 메서드는 [설정 훅 이벤트](/docs/ko/plugins/mods/events#hook-the-settings-hook-events)를 발생시킵니다. 테스트는 `ui.close`와 같은 mods API 호출을 직접 발생시킬 수 없습니다. 예를 들어 창을 닫는 버튼을 눌러 모드를 통해 트리거합니다.

66* **`on`**: 스텁을 등록하기 위해 호출합니다. 스텁은 Claude Code 대신 답변하는 훅입니다. `$.` 없이 mods API 호출의 이름을 지정하므로 `store.get`으로 등록된 스텁은 모드의 `$.store.get`에 답변합니다. 모드가 [`$.model.complete`](/docs/ko/plugins/mods/api#call-a-model) 또는 [`$.store.get`](/docs/ko/plugins/mods/interface#keep-state)을 호출할 때 스텁이 답변을 제공합니다.

68이 예제는 모델 호출을 스텁합니다. 훅은 `grader`라는 모드에 속하며 문장을 모델로 보내고 회신이 `PASS`로 시작하는지 보고하는 `/grade` 명령을 처리합니다. 파일은 테스트 중인 훅만 포함하므로 모드에는 [모드 만들기](/docs/ko/plugins/mods/create#write-a-mod-yourself)와 같이 `plugin.json` 및 `hooks.json`도 필요합니다. 세션에서 `/grade`를 입력하려면 모드도 [명령을 등록](/docs/ko/plugins/mods/api#add-a-command)해야 합니다:

70```javascript grader/hooks/register.js theme={null}

71export function register(on) {

72 on('command.run', { command: 'grade' }, async ($, e) => {

73 // e.args is the text typed after /grade

74 const reply = await $.model.complete({

75 model: 'haiku',

76 system: 'Grade the sentence. Start your reply with PASS or FAIL.',

77 prompt: e.args,

78 })

79 const passed = reply.isAnswered && reply.text.startsWith('PASS')

80 return { text: passed ? 'Passed' : 'Try again' }

81 })

82}

83```

85이 테스트는 모델 호출을 스텁하여 훅이 통과 회신으로 수행하는 작업을 확인합니다:

87```typescript grader/tests/grader.test.ts theme={null}

88import { expect, test } from 'claude-code/testing'

90test('a passing grade is reported', async ($, on) => {

91 // Answer the mod's $.model.complete call with a fixed reply, so no model runs

92 on('model.complete', () => ({

93 value: {

94 isAnswered: true,

95 text: 'PASS\nNice sentence.',

96 usage: { input_tokens: 10, output_tokens: 5, cache_read_input_tokens: 0, cache_creation_input_tokens: 0 },

97 },

98 }))

100 // Run /grade, which makes the mod call the model

101 const answer = await $.command.run({ command: 'grade', args: 'The cat sat on the mat.' })

102 expect(answer.text).toBe('Passed')

103})

104```

105

106테스트는 훅의 `reply`가 `value` 아래의 객체이고 `text`가 `PASS`로 시작하기 때문에 통과합니다. 다른 분기를 확인하려면 스텁이 `FAIL`로 시작하는 `text`를 반환하는 두 번째 테스트를 추가하고 `Try again`을 기대합니다.

107

108mods API 호출에 대한 스텁은 `value` 필드가 있는 객체를 반환하며, 이는 모드에서 호출이 해결되는 것을 보유합니다: `{ value: 7 }`은 `$.store.get`이 `7`로 해결되도록 합니다. [`turn.step`](/docs/ko/plugins/mods/reference#turns) 또는 `tool.call`과 같은 Claude Code의 이벤트에 대한 스텁은 해당 이벤트의 자체 결과(예: `{ result: 'ok' }`)를 반환합니다. `$.session.send` 및 `$.prompt.fill`도 테이블이 표시하는 대로 이벤트의 결과를 사용합니다. [스텁이 반환하는 것 조회](#look-up-what-a-stub-returns)는 각 일반 이름이 취하는 형식을 보여줍니다. 두 가지 오류는 스텁이 잘못되었거나 누락되었음을 의미합니다. 실패한 테스트의 출력에는 `the engine reported:`로 시작하는 블록이 포함되며, 각 오류가 표시됩니다:

109

110* `returned neither { value } nor { deny }`: mods API 호출에 대한 스텁이 일반 값을 반환했습니다

111* `no implementation for` 다음에 이름: 모드가 해당 호출을 수행했고 스텁이 답변하지 않습니다

112

113키트는 또한 전체 네임스페이스에 답변하는 메모리 내 모의 객체를 내보냅니다. `mock.clock(on)`은 [`$.clock`](/docs/ko/plugins/mods/api#run-work-in-the-background)에 답변하고, `mock.store(on, { count: 7 })`은 해당 항목으로 시작하는 저장소에서 `$.store`에 답변하고, `mock.env(on, { CI: 'true' })`는 해당 변수에서 `$.env.get`에 답변합니다. `mock.clock`은 테스트가 진행하는 모의 시계를 반환하므로 타이머 테스트는 대기하지 않습니다. `mock.store`은 아무것도 반환하지 않으므로 모드가 저장한 것을 확인하려면 [그리기 테스트](#test-a-drawing)처럼 두 개의 `store` 스텁을 직접 작성합니다.

114

115<h3 id="follow-the-test-kit’s-rules">

116 테스트 키트의 규칙 따르기

117</h3>

118

119테스트 키트에는 자체 규칙이 몇 가지 있으며, 하나를 위반하면 새로운 테스트 작성자가 처음 만나는 오류가 발생합니다:

120

121* **`$`의 첫 번째 호출 전에 모든 스텁을 등록합니다.** 그 후에 `on`을 호출하면 `on("ui.render") after the test first called $`와 같은 오류가 발생합니다.

122

123* **[`session.start`](/docs/ko/plugins/mods/reference#session)는 자체적으로 실행되지 않습니다.** 각 테스트는 모듈이 새로 로드되고 훅이 호출되지 않은 상태로 시작되므로 모듈 수준 변수는 초기 값을 유지합니다. 훅이 `session.start`가 설정하는 것에 의존하면 먼저 발생시킵니다:

124

125 ```typescript theme={null}

126 // Answer the event after your hook passes it on with next(e)

127 on('session.start', () => ({ cwd: '/work' }))

128 // Answer the $.command.register call your hook makes

129 on('command.register', () => ({ value: undefined }))

130 // Raise the event, which runs your session.start hook

131 await $.session.start({ surface: 'terminal', isInteractive: true, cwd: '/work' })

132 ```

133

134 두 번째 스텁은 [튜토리얼](/docs/ko/plugins/mods/create#write-a-mod-yourself)과 같은 `session.start` 훅이 수행하는 `$.command.register` 호출에 답변합니다. 없으면 해당 호출이 `no implementation for command.register`로 거부되고 키트가 훅을 건너뛰므로 훅의 호출 후 아무것도 실행되지 않습니다. 테스트는 그 시점에서 실패하지 않습니다. 건너뛴 훅은 나중에 확인이 실패할 경우에만 `the engine reported:` 아래에 나열됩니다.

135

136* **`next(e)`를 반환하는 훅에는 답변할 스텁이 필요합니다.** 예를 들어 [`ui.render`](/docs/ko/plugins/mods/reference#interface) 훅이 `next(e)`를 반환할 때, Claude가 유휴 상태일 때 아무것도 그리지 않으려면 [마운트](#test-a-drawing)가 `no implementation for ui.render`로 실패합니다. 요소를 일반 데이터로 반환하는 스텁을 등록합니다:

137

138 ```typescript theme={null}

139 // Stands for what Claude Code would draw at the site

140 on('ui.render', () => ({ type: 'Text', props: {}, children: ['drawn by Claude Code'] }))

141 ```

142

143 스텁이 등록되면 마운트가 성공하고, `ui.find({ type: 'Text' })`는 훅이 `next(e)`를 반환할 때마다 해당 요소를 반환합니다.

144

145* **`turn.step`에 대한 스텁은 비동기 생성기이며**, 테스트는 결과를 얻기 위해 스트림을 끝까지 읽습니다:

146

147 ```typescript theme={null}

148 on('turn.step', async function* ($, e) {

149 // Each yield is one piece of the model's streamed reply

150 yield { kind: 'text', index: 0, text: 'ok' }

151 // The return value is the result of the whole request

152 return { turnId: e.turnId, index: e.index, answer: 'ok', toolUses: [], stopReason: 'end_turn', usage: null }

153 })

154

155 // Raise one request to the model, which runs your turn.step hook

156 const stream = $.turn.step({ turnId: 't', index: 0, model: 'claude-test', messageCount: 1 })

157 // Read every piece until the stream says it's done

158 let step = await stream.next()

159 while (step.done !== true) step = await stream.next()

160 const result = step.value

161 ```

162

163 루프가 끝나면 `result`는 `turn.step` 훅이 변경할 기회를 가진 후 스텁이 반환한 객체입니다. 여기서 `result.answer`는 `'ok'`입니다.

164

165* **도구 호출을 도구의 이름과 인수를 필드로 발생시킵니다**, 예: `await $.tool.call({ tool: 'Bash', command: 'ls' })`, 그리고 `{ result }`를 반환하는 `tool.call` 스텁을 등록합니다.

166

167<h3 id="look-up-what-a-stub-returns">

168 스텁이 반환하는 것 조회

169</h3>

170

171모드가 테스트에서 수행하는 모든 mods API 호출에는 Claude Code 대신 답변할 스텁이 필요합니다. 단, 키트가 자체적으로 답변하는 몇 가지는 제외됩니다: [`$.ui.invalidate`](/docs/ko/plugins/mods/interface#redraw-when-something-changes) 및 [`$.state`](/docs/ko/plugins/mods/interface#keep-state) 호출. `$.clock` 호출의 경우 `mock.clock(on)`을 사용하거나 모드의 `$.clock.now()`가 `no implementation for clock.now`로 실패합니다.

172

173이 표는 모드가 가장 많이 사용하는 것들을 나열합니다. 첫 번째 열은 모드가 수행하거나 `next(e)`로 전달하는 호출 또는 이벤트입니다. 두 번째는 해당 이름 아래 `on`에 전달할 함수이므로 `$.store.get` 행은 `on('store.get', ($, e) => ({ value: saved.get(e.key) }))`가 됩니다. 스텁의 `'...'`는 채울 텍스트를 표시합니다:

174

175| 모드가 호출하거나 전달하는 것 | 스텁 |

176| :- | :- |

177| `$.command.register`, `$.tool.register`, `$.ui.toast`, `$.ui.log`, `$.ui.status`, `$.ui.close`, `$.store.set` | `() => ({ value: undefined })`. `ui.toast` 및 `ui.log`의 경우 텍스트는 `e.text`입니다. |

178| `$.store.get` | `($, e) => ({ value: saved.get(e.key) })` |

179| `$.fs.read` | `($, e) => ({ value: e.path.endsWith('notes.md') ? '# Notes' : '' })`. `e.path`는 절대 경로로 도착하므로 `endsWith`와 비교합니다. |

180| `$.ui.open` | `() => ({ value: { isPlaced: true } })` |

181| `$.ui.ask` | `tool.call` 스텁입니다. 질문이 `AskUserQuestion` 도구에 대한 호출로 도착하기 때문입니다: `($, e) => ({ result: { answers: { [e.questions[0].question]: 'Run it' } } })`. 모드가 다른 도구 호출을 전달하면 먼저 `e.tool`을 확인합니다. |

182| `$.model.complete` | `() => ({ value: { isAnswered: true, text: '...', usage } })` |

183| `$.process.run` | `($, e) => ({ value: { exitCode: 0, stdout: '...', stderr: '' } })`. `e.argv`는 인수 목록이고 `e.init`은 `cwd` 및 `timeoutMs`를 보유합니다. |

184| 실패해야 하는 모든 mods API 호출 | `() => ({ deny: 'the reason' })`. 이는 모드에서 호출이 거부되도록 합니다. 예외를 발생시키는 스텁은 대신 건너뜁니다. |

185| `session.start` | `() => ({ cwd: '/work' })` |

186| `turn.start` | `($, e) => ({ turnId: e.turnId })` |

187| `tool.call` | `() => ({ result: '...' })` |

188| `turn.complete` | `() => ({ text: '' })`. `$.turn.complete({ turnId, answer, durationMs, isAborted: false, usage: null })`로 발생시킵니다. |

189| `prompt.submit` | `($, e) => ({ text: e.text })` |

190| `prompt.fill` | `() => ({ isFilled: true })` |

191| `$.prompt.read` | `() => ({ value: { text: '...', cursor: 0 } })` |

192| `$.ui.copy` | `() => ({ value: { isCopied: true } })` |

193| `$.session.messages` | `() => ({ value: [{ role: 'assistant', text: '...', toolUses: [] }] })` |

194| `$.session.id`, `$.agent.list` | `() => ({ value: 'abc123' })`, `() => ({ value: [] })` |

195| `session.send` | `() => ({ isDelivered: true })`. `e.to`는 모드가 `{ sessionId }`를 전달했을 때도 문자열로 도착합니다. |

196| `session.receive` | `($, e) => ({ text: e.text })`. `$.session.receive({ origin: { kind: 'peer-send-message' }, text })`로 발생시킵니다. |

197| `ui.render` | `() => ({ type: 'Text', props: {}, children: ['...'] })` |

198

199`expect`는 `toBe`, `toEqual`, `toMatch`, `toMatchObject`, `toContain`, `toBeDefined`, `toBeUndefined`, `toThrow` 어설션을 가지며, 이들 중 어느 것 앞에도 `.not`을 사용할 수 있습니다.

200

201<h2 id="test-a-timer">

202 타이머 테스트

203</h2>

204

205타이머에서 작업을 실행하는 모드는 테스트가 대기하는 대신 시간을 앞으로 이동할 수 있도록 테스트가 제어하는 시계가 필요합니다. `const clock = mock.clock(on)`은 `0`에서 시작하고 테스트가 이동할 때만 이동하는 모의 시계를 반환합니다. 다른 시간에 시작하려면 `mock.clock(on, { now: 5000 })`과 같이 밀리초 단위로 전달합니다. 시계에는 다음 메서드가 있습니다:

206

207| 메서드 | 수행하는 작업 |

208| :- | :- |

209| `await clock.advance(1000)` | 시간을 해당 밀리초만큼 앞으로 이동하고 기한이 된 각 타이머를 실행합니다 |

210| `await clock.set(5000)` | 시간을 해당 값으로 앞으로 이동합니다. `advance`처럼 |

211| `clock.now()` | 시간을 반환합니다. 모드의 `$.clock.now()`가 해결되는 것입니다 |

212| `await clock.settle()` | 이미 기한이 된 타이머(예: 0 지연 `$.clock.after` 호출 체인)를 실행합니다. 시간을 이동하지 않습니다 |

213| `await clock.sleep(2000)` | 스텁 내부에서 테스트가 그 거리만큼 진행할 때까지만 해당 스텁이 답변하도록 합니다. 느린 모델이나 프로세스를 시뮬레이션하는 방법입니다 |

214

215이 훅은 `countdown`이라는 모드에 속하며 초 단위로 숫자를 사용하는 `/countdown` 명령을 처리하고, 1초 `$.clock.every` 타이머를 시작하고, 0에서 토스트를 표시합니다. `grader`와 마찬가지로 파일은 테스트 중인 훅만 포함하고 명령을 등록하지 않습니다:

216

217```javascript countdown/hooks/register.js theme={null}

218export function register(on) {

219 on('command.run', { command: 'countdown' }, async ($, e) => {

220 // e.args is the text typed after /countdown

221 let left = Number(e.args)

222 const timer = $.clock.every(1000, () => {

223 left -= 1

224 if (left === 0) {

225 timer.cancel()

226 $.ui.toast('Time is up')

227 }

228 })

229 // Print nothing in the transcript

230 return {}

231 })

232}

233```

234

235이 테스트는 `/countdown 3`을 실행하고 모의 시계를 이동하므로 3초를 기다리지 않고 3초의 동작을 확인합니다:

236

237```typescript countdown/tests/countdown.test.ts theme={null}

238import { expect, mock, test } from 'claude-code/testing'

239

240test('the countdown ends with a toast', async ($, on) => {

241 // Answer every $.clock call from a clock the test controls

242 const clock = mock.clock(on)

243 // Collect the text of each toast the mod shows

244 const toasts: string[] = []

245 on('ui.toast', ($, e) => {

246 toasts.push(e.text)

247 return { value: undefined }

248 })

249

250 await $.command.run({ command: 'countdown', args: '3' })

251 // After two seconds the timer has fired twice, and no toast is due

252 await clock.advance(2000)

253 expect(toasts).toEqual([])

254 // The third second brings the count to zero

255 await clock.advance(1000)

256 expect(toasts).toEqual(['Time is up'])

257})

258```

259

260첫 번째 `expect`는 토스트가 일찍 오지 않음을 보여주고, 두 번째는 한 번 옴을 보여줍니다. 각 `advance`는 기한이 된 타이머가 실행된 후 해결되므로 다음 줄의 확인은 그 효과를 봅니다.

261

262<h2 id="test-a-drawing">

263 그리기 테스트

264</h2>

265

266테스트는 모드의 [렌더 사이트](/docs/ko/plugins/mods/reference#render-sites) 중 하나를 그리고, 그린 요소를 누르고, 입력하고, 찾을 수 있습니다. `$.ui.mount`는 모드의 `ui.render` 훅을 통해 사이트를 그리고 각각에 대한 메서드가 있는 핸들을 반환합니다. 한 테스트에서 여러 앱을 다루려면 `surface`를 그릴 앱으로 설정합니다. 이 테스트는 [탭으로 창 만들기](/docs/ko/plugins/mods/interface#build-a-pane-with-tabs)의 창을 열고, 탭을 전환하고, 버튼을 누르고, 터미널과 Desktop 앱의 개수를 확인합니다:

267

268```typescript hello-tabs/tests/hello-tabs.test.ts theme={null}

269import { expect, test } from 'claude-code/testing'

270

271// What Claude Code passes to a ui.render hook for this pane, apart from the app

272const PANE = {

273 plugin: 'hello-tabs',

274 component: 'Pane',

275 requestId: 'hello-tabs',

276 viewport: { columns: 100, rows: 30 },

277 props: {

278 title: 'Hello tabs',

279 isFocused: true,

280 bodyColumns: 60,

281 placement: 'inline',

282 scroll: { offset: 0, bodyRows: 10 },

283 view: {},

284 },

285} as const

286

287test('the second tab counts presses and saves the count', async ($, on) => {

288 // Stub $.store with a Map, so the test can read what the mod saved

289 const saved = new Map<string, unknown>()

290 on('store.get', ($, e) => ({ value: saved.get(e.key) }))

291 on('store.set', ($, e) => {

292 saved.set(e.key, e.value)

293 return { value: undefined }

294 })

295

296 // Draw the pane once for each app

297 for (const surface of ['terminal', 'desktop'] as const) {

298 const ui = await $.ui.mount({ ...PANE, surface })

299 // Press the buttons by the key the mod gave them

300 await ui.press({ key: 'tab-two' })

301 await ui.press({ key: 'more' })

302 // The second tab's count line is in the drawing

303 expect(await ui.find({ type: 'Text', text: /^Count: \d+$/ })).toBeDefined()

304 await ui.unmount()

305 }

306

307 // One press in each app makes two

308 expect(saved.get('count')).toBe(2)

309})

310```

311

312셸에서 `hello-tabs` 디렉토리에서 `claude plugin test`를 실행합니다. 테스트는 두 앱이 모두 개수 줄을 그리고 모드가 `2`를 저장했을 때 통과합니다. 두 마운트가 모두 같은 로드된 모듈을 사용하기 때문에 개수는 첫 번째 앱에서 두 번째 앱으로 이월됩니다.

313

314`$.ui.mount`가 반환하는 핸들에는 제공한 `key`로 요소를 주소 지정하는 다음 메서드가 있습니다:

315

316| 메서드 | 수행하는 작업 |

317| :- | :- |

318| `press({ key: 'more' })` | 해당 키가 있는 `Button`을 누릅니다 |

319| `input({ key: 'new-note', text: 'buy milk' })` | 텍스트를 해당 키가 있는 `Input`에 입력하고 Enter를 누릅니다. `kind: 'change'`를 추가하여 제출하지 않고 입력합니다. |

320| `select({ key: 'size', value: 'large' })` | 해당 키가 있는 `Select`에서 해당 값이 있는 옵션을 선택합니다 |

321| `find({ key: 'more' })` 또는 `find({ type: 'Text', text: 'Count: 2' })` | 첫 번째 일치하는 요소를 `{ type, props, children }`으로 반환하거나 `undefined`를 반환합니다. `text`는 문자열 또는 정규식일 수 있습니다. |

322| `unmount()` | 그리기를 제거합니다 |

323

324각 메서드는 핸들러가 완료된 후 해결되므로 다음 줄에서 결과를 확인할 수 있습니다. `props`를 Claude Code가 해당 사이트에 전달할 것으로 설정합니다. [렌더 사이트 표](/docs/ko/plugins/mods/reference#render-sites)는 각 사이트의 props를 나열하고, [빌드의 타입](/docs/ko/plugins/mods/create#get-the-types-for-your-build)은 해당 타입을 가집니다.

325

326그리기 테스트는 훅이 반환하는 트리와 해당 앱에 유효한지 확인합니다. 앱이 이를 그리는 방식을 확인하지 않으므로 실제 세션에서 새 레이아웃을 살펴봅니다.

327

328<h3 id="test-a-drawing-after-clear">

329 `/clear` 후 그리기 테스트

330</h3>

331

332각 테스트는 모든 `$.state` 값이 기본값으로 시작하며, 이는 `/clear`가 남기는 방식입니다. 모드가 다음에 수행하는 작업을 테스트하려면 `session.start`를 건너뛰고, `source: 'clear'`로 `classic.SessionStart`를 발생시키고, 모드가 그리는 것을 확인합니다.

333

334이 테스트는 ['/clear' 후 저장된 값 다시 로드](/docs/ko/plugins/mods/interface#load-a-saved-value-again-after-clear)의 모듈을 확인합니다. [그리기 테스트](#test-a-drawing)의 파일에 추가합니다. 여기서 `PANE`이 정의됩니다. 해당 파일의 첫 번째 테스트는 [하나 이상의 세션에서 저장](/docs/ko/plugins/mods/interface#save-from-more-than-one-session)의 버튼처럼 버튼이 개수를 저장할 것으로 기대합니다:

335

336```typescript hello-tabs/tests/hello-tabs.test.ts theme={null}

337test('the saved count comes back after /clear', async ($, on) => {

338 // The store already holds a count of 7

339 on('store.get', () => ({ value: 7 }))

340 // Answer the event after your hook passes it on with next(e)

341 on('classic.SessionStart', () => ({}))

342

343 // Raise the event that fires after /clear, which runs your hook

344 await $.classic.SessionStart({ source: 'clear' })

345

346 const ui = await $.ui.mount({ ...PANE, surface: 'terminal' })

347 await ui.press({ key: 'tab-two' })

348 // The pane shows the stored count, not the default of 0

349 expect(await ui.find({ type: 'Text', text: 'Count: 7' })).toBeDefined()

350})

351```

352

353테스트는 `classic.SessionStart` 훅이 저장된 `7`을 창이 그리기 전에 `$.state`에 복사했을 때 통과합니다. 모듈에 해당 훅이 없으면 창이 `Count: 0`을 그리고, `find`가 `undefined`를 반환하고, 테스트가 `toBeDefined`에서 실패합니다.

354

355<h2 id="test-a-mod-that-judges-other-mods">

356 다른 모드를 판단하는 모드 테스트

357</h2>

358

359조직이 [`prependPlugins`](/docs/ko/plugins/mods/admin)에 나열하는 모드는 다른 모드가 로드되기 전에 거부할 수 있습니다. 하나를 테스트하려면 모드의 계층을 설정하고 테스트에 모드가 허용하거나 거부할 두 번째 모드를 제공합니다:

360

361* **`tier`**: 테스트 파일의 맨 위에서 한 번 호출합니다. 예: `tier('prepend')`로 모드를 `prepend`, `append`, `builtin`으로 로드합니다. 이는 [모드가 실행되는 순서](/docs/ko/plugins/mods/events#the-order-mods-run-in)에서의 위치입니다. 없으면 모드가 `user`로 로드됩니다.

362* **`plugins`**: 테스트 본문 앞에 `test`에 옵션 객체를 전달합니다. 해당 `plugins` 배열은 인라인으로 작성한 모드를 보유하며, 각각 `name` 및 `register` 함수를 가집니다. `user` 이외의 곳에 하나를 로드하려면 `tier`를 추가합니다.

363

364이 테스트 파일은 [관리 페이지의 정책 모드](/docs/ko/plugins/mods/admin#enforce-a-policy-with-a-mod-of-your-own)를 먼저 로드합니다. 정책 모드가 프로세스를 시작하는 모드를 거부하고 그렇지 않은 모드를 허용하는지 확인합니다:

365

366```typescript acme-guard/tests/guard.test.ts theme={null}

367import { expect, test, tier } from 'claude-code/testing'

368

369// Load the mod under test ahead of every other mod

370tier('prepend')

371

372// A second mod whose code calls $.process.run, which the policy blocks

373const runner = {

374 name: 'runner',

375 register(on) {

376 on('tool.call', async ($, e, next) => {

377 await $.process.run(['ls'])

378 return { result: 'runner answered' }

379 })

380 },

381}

382

383// A second mod that calls nothing the policy blocks

384const reader = {

385 name: 'reader',

386 register(on) {

387 on('tool.call', async ($, e, next) => {

388 return { result: 'reader answered' }

389 })

390 },

391}

392

393test('refuses a mod that starts a process', { plugins: [runner] }, async ($, on) => {

394 on('tool.call', () => ({ result: 'claude code answered' }))

395 let message = ''

396 try {

397 // The first call on $ loads the mods, so the refusal is thrown here

398 await $.tool.call({ tool: 'Bash', command: 'ls' })

399 } catch (error) {

400 message = error.message

401 }

402 expect(message).toBe('runner: refused by acme-guard: Acme policy: mods may not call process.run')

403})

404

405test('admits a mod that starts no process', { plugins: [reader] }, async ($, on) => {

406 on('tool.call', () => ({ result: 'claude code answered' }))

407 const out = await $.tool.call({ tool: 'Bash', command: 'ls' })

408 // The answer comes from reader, which shows that it loaded

409 expect(out).toEqual({ result: 'reader answered' })

410})

411```

412

413셸에서 `acme-guard` 디렉토리에서 `claude plugin test`를 실행합니다. 두 테스트 모두 정책 모드가 관리 페이지에 표시된 대로 통과합니다.

414

415키트는 테스트의 첫 번째 `$` 호출에서 모든 모드를 로드합니다. 모드가 하나를 거부하면 해당 호출이 예외를 발생시키고, 메시지는 거부된 모드, 거부한 모드, 이유를 이름으로 지정합니다. 두 번째 테스트에서는 아무것도 거부되지 않으므로 `reader`가 스텁에 도달하기 전에 도구 호출에 답변합니다.

416

417<h2 id="next-steps">

418 다음 단계

419</h2>

420

421* [모드 문제 해결](/docs/ko/plugins/mods/troubleshoot): 모드가 세션에서 아무것도 하지 않는 이유 알아보기

422* [모드 참조](/docs/ko/plugins/mods/reference): 스텁 작성을 위한 모든 이벤트의 입력 및 결과

plugins/mods/troubleshoot.md +295 −0 created

Details

1> ## Documentation Index

2> 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.

5# mod 문제 해결

7> Claude Code mod이 작동하지 않는 이유를 파악합니다: 증상이나 메시지를 원인과 일치시키고, 거부 메시지를 조회하며, 디버그 로그를 읽습니다.

9mod의 모듈이나 해당 hook 중 하나가 실패하면 Claude Code는 이를 건너뛰고 세션이 계속되므로, 손상된 mod은 아무것도 하지 않는 것처럼 보일 수 있습니다. Claude Code가 mod에서 읽은 내용과 문제를 보고하는 위치를 확인하여 시작한 다음, 발생한 증상이나 메시지를 찾습니다.

11<h2 id="find-out-why-a-mod-does-nothing">

12 mod이 아무것도 하지 않는 이유 파악

13</h2>

15mod이 아무것도 하지 않을 때, 두 가지 확인으로 이유를 찾을 수 있습니다: Claude Code가 mod의 파일에서 읽은 내용과 무언가를 건너뛸 때 작성하는 줄입니다. 첫 번째의 경우, 셸에서 [`claude plugin validate`](/docs/ko/plugins/mods/create#check-what-claude-code-reads-from-your-mod)를 mod의 디렉터리와 함께 실행합니다(예: `claude plugin validate ./first-mod`). 이는 세션을 시작하지 않고도 잘못된 이벤트, 잘못된 manifest, Claude Code가 읽을 수 없는 모듈을 포착합니다.

17모듈이 로드되지 않거나, hook이 건너뛰어지거나, 다른 mod이 귀사의 mod을 거부할 때, Claude Code는 귀사의 mod의 이름을 지정하는 한 줄을 작성합니다. 해당 줄을 읽는 위치는 세션에 따라 다릅니다:

19* **플러그인 디렉터리를 핫 리로드하는 세션**: 트랜스크립트의 흐린 줄입니다. 이는 `--plugin-dir`로 시작한 대화형 세션이거나, Claude가 작성한 mod에 대해 [핫 리로딩을 활성화](/docs/ko/plugins/mods/create#ask-claude-for-a-mod)한 세션입니다.

20* **마켓플레이스에서 설치한 mod을 실행하는 것과 같은 다른 모든 대화형 세션**: [디버그 로그](#read-the-debug-log)만 해당합니다. 하나를 얻으려면 `claude --debug`로 세션을 시작합니다.

21* **`--plugin-dir`을 사용한 `claude -p` 실행**: stderr, 기본 텍스트 출력 형식입니다. 다른 mod의 거부는 디버그 로그로만 이동합니다.

23<h2 id="check-whether-mods-can-load">

24 mod이 로드될 수 있는지 확인

25</h2>

27설정이 mod을 로드할 수 있는지 확인하려면 mod을 설치하지 않고도 셸에서 `claude plugin test`를 실행합니다(mod을 보유하지 않은 디렉터리에서). 세션이 필요하지 않습니다. 인쇄되는 메시지는 상태를 알려줍니다:

29| 메시지 포함 | 의미 |

30| :- | :- |

31| `no hooks module to load` | mod을 로드할 수 있습니다. 명령이 이 디렉터리에서 테스트할 mod을 찾지 못했습니다. |

32| `hooks modules are turned off here` | 설정이 mod을 차단하고 있습니다: 자신의 설정에서 `disableAllHooks` 또는 조직의 정책 |

33| `hooks modules are turned off in this process` | Anthropic이 설치된 mod을 원격으로 비활성화했습니다. 컴퓨터의 어떤 설정도 이를 다시 켤 수 없습니다. |

35조직은 또한 `allowManagedModsOnly`를 설정하여 자신의 mod만 허용할 수 있으며, 이 명령은 이를 보고하지 않습니다. 이 경우 설치한 mod이 로드되지 않으며, [메시지가 이유를 설명합니다](/docs/ko/plugins/mods/troubleshoot#messages-from-the-built-in-guard).

37<h2 id="the-mod-doesn’t-load">

38 mod이 로드되지 않음

39</h2>

41mod이 추가하는 것이 아무것도 나타나지 않습니다: 명령, 그리기, 동작 변화가 없습니다.

43<h3 id="your-version-is-older-than-2-1-287">

44 버전이 2.1.287보다 오래됨

45</h3>

47`claude --version`은 2.1.287보다 오래된 버전을 인쇄합니다. 버전이 mod이 기본적으로 켜지기 전의 것입니다.

49[Claude Code 업데이트](/docs/ko/setup#update-claude-code).

51<h3 id="the-mods-active-line-doesn’t-name-the-mod">

52 `mods active` 줄이 mod의 이름을 지정하지 않음

53</h3>

55mod이 추가하는 것이 아무것도 나타나지 않으며, `/plugin`의 [`mods active` 줄](/docs/ko/plugins/mods/overview#see-which-mods-a-session-loaded)이 이를 이름 지정하지 않습니다. hooks 모듈이 로드되지 않았습니다. Claude Code가 이를 거부했을 때, 디버그 로그에는 `hooks module`, mod의 이름, `not loaded:`로 시작하는 줄이 있습니다(예: `--plugin-dir`로 로드된 mod의 경우 `hooks module first-mod@inline not loaded: disableAllHooks in managed settings`).

57콜론 뒤의 이유를 읽습니다. [거부 메시지](#refusal-messages) 섹션에는 각각이 나열되어 있습니다. 로그에 그러한 줄이 없으면 이 그룹의 다른 항목을 통해 작업합니다.

59<h3 id="a-claude-p-run-prints-hooks-module-not-loaded">

60 `claude -p` 실행이 `hooks module not loaded` 인쇄

61</h3>

63줄은 mod의 이름으로 시작하여 stderr로 이동합니다. hooks 모듈이 거부되었습니다. 비대화형 실행에는 트랜스크립트가 없으므로 메시지는 stderr로 이동합니다.

65콜론 뒤의 이유를 읽습니다. [거부 메시지](#refusal-messages) 섹션에는 각각이 나열되어 있습니다.

67<h3 id="refusal-messages">

68 거부 메시지

69</h3>

71각각은 디버그 로그에서 `hooks module`, mod의 이름, `not loaded:` 뒤에 옵니다.

73| 메시지 시작 | 의미 |

74| :- | :- |

75| `hooks modules are turned off for installed plugins in this process` | Anthropic이 설치된 mod을 원격으로 비활성화했습니다. 컴퓨터의 어떤 설정도 이를 다시 켤 수 없습니다. |

76| `disableAllHooks in managed settings` | 조직이 설치된 플러그인의 hook을 비활성화했습니다 |

77| `only managed plugins and built-in plugins run` | `allowManagedHooksOnly`가 설정되었거나 관리되는 설정이 아닌 설정 파일에서 `disableAllHooks`가 설정되었습니다 |

78| `installed plugins that are not managed load no hooks module in this mode (--bare)` | `--bare`로 Claude Code를 시작했습니다 |

79| `another plugin of that name loads first` | 두 플러그인이 이름을 공유합니다. 관리되는 것 또는 먼저 로드된 것이 사용됩니다. |

81<h3 id="messages-from-the-built-in-guard">

82 기본 제공 가드의 메시지

83</h3>

85관리되는 설정이 있는 컴퓨터 또는 Team 또는 Enterprise 플랜으로 로그인한 사용자의 경우, [기본 제공 가드](/docs/ko/plugins/mods/admin#know-what-happens-by-default)는 mod 또는 해당 답변 중 하나를 거부할 수 있습니다. 각 메시지는 조직의 관리자가 규칙을 변경하도록 설정하는 옵션의 이름을 지정합니다.

87| 메시지 포함 | 의미 | 나타나는 위치 |

88| :- | :- | :- |

89| `mods are limited to your organization's by policy (allowManagedModsOnly)` | 조직이 [자신의 mod만](/docs/ko/plugins/mods/admin#install-your-organizations-mods) 허용하므로 귀사의 mod이 로드되지 않았습니다 | 디버그 로그 및 [플러그인 디렉터리를 핫 리로드하는 세션](#find-out-why-a-mod-does-nothing)의 트랜스크립트 |

90| `tried to lift a deny rule in your settings` | mod의 [`tool.check`](/docs/ko/plugins/mods/reference#tools) hook이 `deny` 규칙이 거부하는 호출을 승인했습니다. 호출은 거부된 상태로 유지됩니다. | 트랜스크립트 및 디버그 로그, 세션의 각 mod마다 한 번씩. `claude -p` 실행에서는 디버그 로그만 해당합니다. |

91| `the deny rules in your settings could not be checked for this call, so it is refused` | 가드가 mod이 승인한 호출을 확인하는 동안 실패했으므로 호출을 거부했습니다 | 거부된 호출에 대해 Claude가 읽는 이유 |

93<h3 id="validate-passes-and-lists-no-hooks-line">

94 `validate`가 통과하고 `hooks` 줄을 나열하지 않음

95</h3>

97`hooks/hooks.json`에 `modules` 키가 없거나 키가 잘못 입력되었습니다.

99`"modules": ["./register.js"]`를 추가합니다.

100

101<h3 id="hooks-module-did-not-load">

102 `hooks module did not load`

103</h3>

104

105줄은 mod의 이름으로 시작한 다음 `hooks module did not load:` 및 이유가 뒤따르며, 문제가 코드에 있을 때 파일과 줄을 제공합니다. Claude Code가 모듈을 로드할 수 없었습니다(예: 최상위 코드가 throw되었기 때문).

106

107이유가 이름 지정하는 오류를 수정합니다.

108

109<h3 id="options-do-not-fit-plugin-json-userconfig">

110 `options do not fit plugin.json userConfig`

111</h3>

112

113줄은 mod의 이름으로 시작한 다음 `hooks module did not load: options do not fit plugin.json userConfig:` 및 이유가 뒤따릅니다. 옵션이 [`userConfig`](/docs/ko/plugins/components#user-configuration) 필드에 맞지 않습니다(예: 필드의 `max` 위의 숫자 또는 필수 필드에 값이 없음).

114

115값을 설정하거나 변경합니다. 줄의 끝은 `settings.json`의 `pluginConfigs` 항목의 이름을 지정합니다.

116

117<h3 id="no-mod-loads-in-a-directory-you-opened-for-the-first-time">

118 처음 열린 디렉터리에서 mod이 로드되지 않음

119</h3>

120

121디렉터리에 대한 신뢰 프롬프트에 답변하지 않았습니다.

122

123`claude`를 사용하여 해당 디렉터리에서 대화형 세션을 시작하고 열리는 신뢰 프롬프트를 수락합니다.

124

125<h3 id="no-installed-plugin-loads-at-all">

126 설치된 플러그인이 로드되지 않음

127</h3>

128

129`--safe-mode`로 Claude Code를 시작했습니다.

130

131플래그 없이 시작합니다.

132

133<h2 id="a-hook-is-skipped-or-a-mod-is-unloaded">

134 hook이 건너뛰어지거나 mod이 언로드됨

135</h2>

136

137mod이 로드되었고, Claude Code가 해당 hook 중 하나를 건너뛰거나 언로드했습니다.

138

139<h3 id="hook-skipped">

140 `hook skipped`

141</h3>

142

143줄은 mod과 이벤트의 이름을 지정한 다음 `hook skipped:` 및 이유를 말합니다(예: `first-mod: tool.call hook skipped: threw Error: boom`). hook이 throw되었거나, [10초 시간 제한](/docs/ko/plugins/mods/reference#limits)을 초과하여 실행되었거나, 잘못된 모양의 결과를 반환했습니다. 줄은 mod이 다시 로드될 때까지 각 이벤트 및 실패 종류마다 한 번씩 나타납니다.

144

145오류를 수정합니다. 디버그 로그에는 모든 발생에 대한 줄이 있습니다.

146

147<h3 id="no-command-run-hook-answered-it">

148 `no command.run hook answered it`

149</h3>

150

151사용자가 mod이 추가한 명령을 실행하면, 회신은 mod과 명령의 이름을 지정합니다(예: `first-mod registered /tally but no command.run hook answered it`). 그런 다음 hook을 추가하도록 지시합니다. Claude Code는 명령이 답변 없이 체인의 끝에 도달할 때 해당 회신을 출력합니다. 이는 두 가지 경우에 발생합니다:

152

153* **hook이 명령에 답변하지 않음**: 모듈에 `command.run` hook이 없거나, hook의 [필터](/docs/ko/plugins/mods/events#filter-which-events-a-hook-handles)가 다른 명령의 이름을 지정하거나, hook이 `next(e)`를 반환했습니다.

154* **Claude Code가 hook을 건너뜀**: [`hook skipped`](#hook-skipped)에 이유가 나열됩니다. [`$.ui.open`](/docs/ko/plugins/mods/interface#open-a-pane-at-the-right-time)에 `focus: false`를 전달하는 것이 이 상황에 도달하는 한 가지 방법입니다.

155

156모듈에 이미 회신이 설명하는 hook이 있으면, `command.run`의 이름을 지정하는 `hook skipped` 줄을 찾으십시오. 이는 이유를 제공합니다. 명령을 실행하는 [테스트](/docs/ko/plugins/mods/test)는 동일한 이유로 실패합니다.

157

158<h3 id="it-crashed-the-hooks-worker">

159 `it crashed the hooks worker`

160</h3>

161

162줄은 mod의 이름으로 시작합니다(예: `first-mod was unloaded: it crashed the hooks worker`). 설치된 mod은 하나의 워커 스레드를 공유합니다. 워커가 응답을 중지하거나 충돌했으며, Claude Code가 이를 이 mod으로 추적하고 언로드했습니다. 스레드를 차단하는 hook(예: 절대 await하지 않는 루프)이 한 가지 원인입니다.

163

164hook을 수정합니다.

165

166<h3 id="mods-that-run-in-the-hooks-worker-are-off-for-this-session">

167 `mods that run in the hooks worker are off for this session`

168</h3>

169

170줄은 `hooks: mods that run in the hooks worker are off for this session: it crashed 3 times`를 읽습니다. 워커가 3번 중지되었고 Claude Code가 중지를 하나의 mod으로 추적할 수 없어서 기본 제공되지 않은 모든 mod(조직이 설치하는 mod 포함)을 언로드했습니다. 이 줄은 모든 대화형 세션의 트랜스크립트에 도달합니다.

171

172`/reload-plugins`를 실행하여 다시 로드합니다.

173

174<h2 id="a-tool-call-is-denied">

175 도구 호출이 거부됨

176</h2>

177

178mod이 로드되었고 해당 hook이 실행되며, 이를 건드린 도구 호출이 거부됩니다.

179

180<h3 id="a-hook-changed-this-call’s-input-after-the-model-wrote-it">

181 `a hook changed this call's input after the model wrote it`

182</h3>

183

184자동 모드에서 거부된 도구 호출은 이 이유를 제공합니다. hook이 [서버 측 분류자](/docs/ko/permission-modes#server-side-classifier-review)가 검토한 후 도구 호출의 입력을 변경했으므로 해당 검토는 실행될 내용을 포함하지 않습니다. hook은 mod의 [`tool.call`](/docs/ko/plugins/mods/reference#tools) 또는 [`turn.step`](/docs/ko/plugins/mods/reference#turns) hook이거나 [`PreToolUse`](/docs/ko/hooks#pretooluse) 설정 hook일 수 있습니다. 메시지는 어느 것인지 말하지 않습니다.

185

186메시지는 Claude에게 기록된 대로 호출을 다시 한 번 발급하도록 지시합니다. 그것도 거부되면 hook은 매번 입력을 변경하므로 mod 또는 hook을 끄거나 자동 모드를 떠나 호출을 직접 승인합니다.

187

188<h3 id="a-message-about-the-deny-rules-in-your-settings">

189 설정의 거부 규칙에 대한 메시지

190</h3>

191

192`tried to lift a deny rule in your settings` 및 `the deny rules in your settings could not be checked for this call, so it is refused`는 모두 기본 제공 가드에서 옵니다.

193

194[기본 제공 가드의 메시지](#messages-from-the-built-in-guard)에서 조회합니다.

195

196<h2 id="a-drawing-doesn’t-appear-or-respond">

197 그리기가 나타나지 않거나 응답하지 않음

198</h2>

199

200mod이 로드되었고 해당 pane, band 또는 컨트롤이 예상대로 작동하지 않습니다.

201

202<h3 id="a-pane-or-band-is-empty-or-shows-claude-code’s-usual-content">

203 pane 또는 band가 비어 있거나 Claude Code의 일반적인 콘텐츠를 표시함

204</h3>

205

206hook이 반환한 [tree](/docs/ko/plugins/mods/interface#build-a-tree-from-elements)가 유효성 검사를 통과하지 못했습니다. `--plugin-dir`을 사용하면 트랜스크립트는 `ui.render (Pane) refused:`를 이유와 함께 말합니다(예: `first-mod: ui.render (Pane) refused: Box prop "flexDirection" must be one of row, column, row-reverse, column-reverse; the engine drew its own`). 디버그 로그에는 `a hook returned a tree that does not validate`가 동일한 이유와 함께 있습니다.

207

208해당 줄의 이유를 읽습니다. 일반적인 원인은 요소가 취하지 않는 prop과 앱이 없는 요소입니다.

209

210<h3 id="ui-open-runs-and-no-pane-appears">

211 `$.ui.open`이 실행되고 pane이 나타나지 않음

212</h3>

213

214호출이 사용자가 한 것에서 오지 않았으며 터미널이 144열보다 좁습니다.

215

216명령 또는 버튼에서 pane을 열거나 호출의 `isPlaced` 결과를 확인합니다. [올바른 시간에 pane 열기](/docs/ko/plugins/mods/interface#open-a-pane-at-the-right-time)를 참조합니다.

217

218<h3 id="hotkeys-do-nothing">

219 핫키가 아무것도 하지 않음

220</h3>

221

222pane에 키보드 포커스가 없습니다.

223

224Ctrl+X를 누른 다음 Tab을 누르거나 pane을 클릭합니다. `focus: true`로 명령에서 열기합니다.

225

226<h3 id="a-drawing-works-in-the-terminal-and-not-in-the-desktop-app">

227 그리기가 터미널에서 작동하고 Desktop 앱에서는 작동하지 않음

228</h3>

229

230사이트 또는 요소를 사용할 수 없습니다.

231

232[렌더 사이트](/docs/ko/plugins/mods/reference#render-sites) 및 [요소](/docs/ko/plugins/mods/reference#elements) 테이블을 확인합니다.

233

234<h2 id="an-edit-or-a-value-is-lost">

235 편집 또는 값이 손실됨

236</h2>

237

238mod이 실행되고 변경하거나 유지한 값이 없습니다.

239

240<h3 id="your-edits-don’t-take-effect">

241 편집이 적용되지 않음

242</h3>

243

244설치한 플러그인을 편집하고 있습니다. Claude Code는 설치된 버전의 캐시된 복사본을 실행합니다.

245

246`claude --plugin-dir ./first-mod`와 같이 작업 복사본을 가리키는 `--plugin-dir`로 개발합니다. 이는 저장할 때 다시 로드됩니다.

247

248<h3 id="a-value-resets-when-the-module-reloads">

249 모듈이 다시 로드될 때 값이 재설정됨

250</h3>

251

252모듈 수준 변수는 각 다시 로드 시 다시 초기화됩니다.

253

254[값을 `$.state` 또는 `$.store`에 유지합니다](/docs/ko/plugins/mods/interface#keep-state).

255

256<h3 id="a-value-resets-after-/clear-/resume-or-/branch">

257 `/clear`, `/resume` 또는 `/branch` 후 값이 재설정됨

258</h3>

259

260값이 재설정되거나 저장된 값이 기본값으로 대체됩니다. 이러한 각 명령은 `$.state`를 기본값으로 재설정하며, `session.start`는 다시 실행되지 않습니다.

261

262[`classic.SessionStart` hook에서 저장된 값을 다시 로드합니다](/docs/ko/plugins/mods/interface#load-a-saved-value-again-after-clear).

263

264<h2 id="read-the-debug-log">

265 디버그 로그 읽기

266</h2>

267

268디버그 로그에는 Claude Code가 로드하거나 거부하는 모든 모듈, 실패하는 모든 hook, 거부하는 모든 결과에 대한 줄이 있으므로 트랜스크립트가 아무것도 표시하지 않을 때 볼 위치입니다. 하나를 작성하려면 셸에서 `--debug`로 Claude Code를 시작하거나 `--debug-file <path>`로 위치를 선택합니다:

269

270```bash theme={null}

271claude --debug-file ./mod-debug.log --plugin-dir ./first-mod

272```

273

274다른 터미널에서 파일을 따르고 mod의 이름으로 필터링합니다:

275

276```bash theme={null}

277tail -f ./mod-debug.log | grep first-mod

278```

279

280로드된 mod에는 이름을 지정하고 hook하는 이벤트를 나열하는 줄이 있습니다. `--plugin-dir`로 로드된 mod은 이름 뒤에 `@inline`으로 나타납니다:

281

282```text theme={null}

283hooks module first-mod@inline loaded (worker, environment 2, tier user); events: session.start,tool.call,command.run,ui.render

284```

285

286유효성 검사를 통과하지 못한 그리기는 거부된 결과로 계산되며 줄도 가져옵니다. 로그에 자신의 줄을 작성하려면 [`$.ui.log`](/docs/ko/plugins/mods/api#show-something-without-starting-a-turn)를 두 번째 인수와 함께 호출합니다(예: `$.ui.log('message', { to: 'debug' })`). 두 번째 인수 없이 `$.ui.log`는 트랜스크립트에 흐린 줄을 추가합니다.

287

288`--plugin-dir`로 로드된 mod을 편집하는 동안 트랜스크립트는 mod의 이름을 지정하고 해당 hook을 나열하는 각 다시 로드에 대한 줄을 표시합니다. 저장이 모듈을 손상시키면 줄은 `reload failed, the previous version stays loaded:`를 이유와 함께 말하며, 마지막 작동 버전이 계속 실행됩니다.

289

290<h2 id="next-steps">

291 다음 단계

292</h2>

293

294* [mod 테스트](/docs/ko/plugins/mods/test): 문제가 세션에 도달하기 전에 포착합니다

295* [플러그인 문제 해결](/docs/ko/plugins/troubleshooting): mod에 특정하지 않은 플러그인 설치 및 로드 문제

plugins/org.md +4 −1

Details

213| `allowedChannelPlugins` | 채널 메시지를 푸시할 수 있는 플러그인의 기본 목록을 대체합니다. `channelsEnabled: true` 필요 | [채널 플러그인이 실행할 수 있는 것 제한](/docs/ko/channels#restrict-which-channel-plugins-can-run)을 참조하세요 |213| `allowedChannelPlugins` | 채널 메시지를 푸시할 수 있는 플러그인의 기본 목록을 대체합니다. `channelsEnabled: true` 필요 | [채널 플러그인이 실행할 수 있는 것 제한](/docs/ko/channels#restrict-which-channel-plugins-can-run)을 참조하세요 |

214| [`CLAUDE_CODE_DISABLE_OFFICIAL_MARKETPLACE_AUTOINSTALL=1`](/docs/ko/env-vars) | 대화형 터미널 세션이 공식 마켓플레이스를 자동 등록하는 것을 중지합니다 | 이미 등록된 마켓플레이스를 제거하지 않습니다. 허용 목록 및 차단 목록은 이 없이도 같은 자동 등록을 제어합니다. 이를 설정하여 시작한 머신은 설정을 해제한 후 자동 등록을 재개하지 않습니다 |214| [`CLAUDE_CODE_DISABLE_OFFICIAL_MARKETPLACE_AUTOINSTALL=1`](/docs/ko/env-vars) | 대화형 터미널 세션이 공식 마켓플레이스를 자동 등록하는 것을 중지합니다 | 이미 등록된 마켓플레이스를 제거하지 않습니다. 허용 목록 및 차단 목록은 이 없이도 같은 자동 등록을 제어합니다. 이를 설정하여 시작한 머신은 설정을 해제한 후 자동 등록을 재개하지 않습니다 |

215| [`allowManagedModsOnly`](/docs/ko/plugins/mods/admin#stop-user-installed-mods-from-loading) | 조직의 것으로 [계산되지 않는](/docs/ko/plugins/mods/admin#install-your-organizations-mods) 설치된 모든 [mod](/docs/ko/plugins/mods/overview)가 로드되는 것을 중지합니다 | mod를 포함하는 플러그인이 설치되는 것을 중지하지 않습니다. 그렇게 하려면 이 표의 마켓플레이스 키를 사용하세요 |

215 216

216표의 모든 키는 `enabledPlugins`, `syncClaudeAiPlugins` 및 `CLAUDE_CODE_DISABLE_OFFICIAL_MARKETPLACE_AUTOINSTALL` 제외하고 관리되는 설정입니다:217표의 모든 키는 `enabledPlugins`, `syncClaudeAiPlugins`, `CLAUDE_CODE_DISABLE_OFFICIAL_MARKETPLACE_AUTOINSTALL` 및 `allowManagedModsOnly` 제외하고 관리되는 설정입니다:

217 218

218* **`enabledPlugins`**: 모든 범위에서 설정할 수 있으며 관리되는 설정이 이를 잠급니다.219* **`enabledPlugins`**: 모든 범위에서 설정할 수 있으며 관리되는 설정이 이를 잠급니다.

219* **`syncClaudeAiPlugins`**: 각 사용자는 자신의 사용자 또는 로컬 설정에서도 설정할 수 있습니다. [설정 참조에서 해당 범위](/docs/ko/settings-reference#syncclaudeaiplugins)를 참조하세요.220* **`syncClaudeAiPlugins`**: 각 사용자는 자신의 사용자 또는 로컬 설정에서도 설정할 수 있습니다. [설정 참조에서 해당 범위](/docs/ko/settings-reference#syncclaudeaiplugins)를 참조하세요.

220* **`CLAUDE_CODE_DISABLE_OFFICIAL_MARKETPLACE_AUTOINSTALL`**: 이는 [전체 플릿에 대해 업데이트 끄기](#turn-updates-off-for-the-whole-fleet) 아래에 표시된 관리되는 `env` 블록을 통해 제공하는 환경 변수입니다.221* **`CLAUDE_CODE_DISABLE_OFFICIAL_MARKETPLACE_AUTOINSTALL`**: 이는 [전체 플릿에 대해 업데이트 끄기](#turn-updates-off-for-the-whole-fleet) 아래에 표시된 관리되는 `env` 블록을 통해 제공하는 환경 변수입니다.

222* **`allowManagedModsOnly`**: 이는 관리되는 설정의 `pluginConfigs` 아래에서 설정하는 기본 제공 플러그인의 옵션입니다. [사용자 설치 mod가 로드되는 것 중지](/docs/ko/plugins/mods/admin#stop-user-installed-mods-from-loading)를 참조하세요.

221 223

222여기의 각 설정 키는 [설정 참조](/docs/ko/settings-reference)에 항목이 있습니다.224여기의 각 설정 키는 [설정 참조](/docs/ko/settings-reference)에 항목이 있습니다.

223 225

457* [마켓플레이스 참조](/docs/ko/plugins/marketplace-reference#marketplace-sources): `extraKnownMarketplaces`, `strictKnownMarketplaces` 및 `blockedMarketplaces`가 수락하는 `source` 값459* [마켓플레이스 참조](/docs/ko/plugins/marketplace-reference#marketplace-sources): `extraKnownMarketplaces`, `strictKnownMarketplaces` 및 `blockedMarketplaces`가 수락하는 `source` 값

458* [마켓플레이스 호스팅 및 유지](/docs/ko/plugins/host-marketplace): 정책이 가리키는 마켓플레이스 실행460* [마켓플레이스 호스팅 및 유지](/docs/ko/plugins/host-marketplace): 정책이 가리키는 마켓플레이스 실행

459* [플러그인 보안 및 신뢰](/docs/ko/plugins/security): 플러그인이 머신에서 할 수 있는 것 및 설치 전에 하나를 검토하는 방법461* [플러그인 보안 및 신뢰](/docs/ko/plugins/security): 플러그인이 머신에서 할 수 있는 것 및 설치 전에 하나를 검토하는 방법

462* [조직을 위한 모드 관리](/docs/ko/plugins/mods/admin): 모드(Claude Code 내에서 실행되는 플러그인)를 끄거나 제한합니다

460* [서버 관리 설정](/docs/ko/server-managed-settings): claude.ai 관리자 콘솔에서 이 키를 제공463* [서버 관리 설정](/docs/ko/server-managed-settings): claude.ai 관리자 콘솔에서 이 키를 제공

461* [플러그인 문제 해결](/docs/ko/plugins/troubleshooting#blocked-by-your-organization): 정책이 사용자를 차단할 때 사용자가 보는 메시지464* [플러그인 문제 해결](/docs/ko/plugins/troubleshooting#blocked-by-your-organization): 정책이 사용자를 차단할 때 사용자가 보는 메시지

plugins/overview.md +4 −3

Details

15 * **MCP 서버를 구축했고 Anthropic의 디렉토리에 포함시키려는 경우**: [디렉토리에 게시](https://claude.com/docs/directory/publish)를 참조하세요15 * **MCP 서버를 구축했고 Anthropic의 디렉토리에 포함시키려는 경우**: [디렉토리에 게시](https://claude.com/docs/directory/publish)를 참조하세요

16</Note>16</Note>

17 17

18지금 플러그인을 시도하려면 Claude Code 터미널 세션에서 `/plugin`을 실행하고 **Discover** 탭에서 플러그인을 설치합니다. **Discover** 탭에는 Anthropic의 공식 마켓플레이스와 추가한 마켓플레이스의 플러그인이 나열됩니다. 여기서:18지금 플러그인을 시도하려면 Claude Code 터미널 세션에서 `/plugin`을 실행하고 **Discover** 탭에서 플러그인을 설치합니다. **Discover** 탭에는 마켓플레이스의 플러그인이 나열됩니다. 여기서:

19 19

20* [플러그인 설치 및 관리](/docs/ko/plugins/install): 전체 설치 단계, 범위 및 기타 표면20* [플러그인 설치 및 관리](/docs/ko/plugins/install): 전체 설치 단계, 범위 및 기타 표면

21* [플러그인 만들기](/docs/ko/plugins/create): 자신만의 플러그인 만들기21* [플러그인 만들기](/docs/ko/plugins/create): 자신만의 플러그인 만들기

30* [**스킬**](/docs/ko/plugins/components#skills): Claude가 관련성이 있을 때 로드하는 `SKILL.md` 지침이며, 명령으로도 실행할 수 있습니다.30* [**스킬**](/docs/ko/plugins/components#skills): Claude가 관련성이 있을 때 로드하는 `SKILL.md` 지침이며, 명령으로도 실행할 수 있습니다.

31* [**에이전트**](/docs/ko/plugins/components#agents): Claude가 위임할 수 있는 서브에이전트 정의31* [**에이전트**](/docs/ko/plugins/components#agents): Claude가 위임할 수 있는 서브에이전트 정의

32* [**훅**](/docs/ko/plugins/components#hooks): Claude Code가 편집 후와 같은 수명 주기의 특정 지점에서 실행하는 명령32* [**훅**](/docs/ko/plugins/components#hooks): Claude Code가 편집 후와 같은 수명 주기의 특정 지점에서 실행하는 명령

33* [**훅 모듈**](/docs/ko/plugins/mods/overview): JavaScript 함수로 작성된 훅으로, 창을 그리고 명령을 추가할 수도 있습니다. 이를 가진 플러그인을 mod라고 합니다.

33* [**MCP 서버**](/docs/ko/plugins/components#mcp-servers): 플러그인이 활성화되어 있는 동안 Claude Code가 연결하는 도구 서버34* [**MCP 서버**](/docs/ko/plugins/components#mcp-servers): 플러그인이 활성화되어 있는 동안 Claude Code가 연결하는 도구 서버

34 35

~~35이 다이어그램은 각 구성 요소 유형 중 하나씩 보유한 `my-plugin`이라는 플러그인과 플러그인이 로드되면 각 파일에서 얻는 것을 보여줍니다.~~36이 다이어그램은 스킬, 에이전트, 훅 및 MCP 서버를 보유한 `my-plugin`이라는 플러그인과 플러그인이 로드되면 각 파일에서 얻는 것을 보여줍니다.

36 37

37<img src="https://mintcdn.com/claude-code/2Q_GtOEovg5qaBem/images/plugin-directory.svg?fit=max&auto=format&n=2Q_GtOEovg5qaBem&q=85&s=f623b64e82713b830e48174f0a922888" className="dark:hidden" alt="Diagram in two columns joined by five straight arrows. Left, the directory of a plugin named my-plugin, holding a manifest at .claude-plugin/plugin.json, skills/review/SKILL.md, agents/reviewer.md, hooks/hooks.json, .mcp.json, and other components. Right, what each file gives you in your session: the manifest sets the plugin name, my-plugin; the skill runs as /my-plugin:review; the agent file is a subagent Claude can delegate to; the hooks file holds hooks that run on lifecycle events; and .mcp.json adds an MCP server that gives Claude tools." width="760" height="336" data-path="images/plugin-directory.svg" />38<img src="https://mintcdn.com/claude-code/2Q_GtOEovg5qaBem/images/plugin-directory.svg?fit=max&auto=format&n=2Q_GtOEovg5qaBem&q=85&s=f623b64e82713b830e48174f0a922888" className="dark:hidden" alt="Diagram in two columns joined by five straight arrows. Left, the directory of a plugin named my-plugin, holding a manifest at .claude-plugin/plugin.json, skills/review/SKILL.md, agents/reviewer.md, hooks/hooks.json, .mcp.json, and other components. Right, what each file gives you in your session: the manifest sets the plugin name, my-plugin; the skill runs as /my-plugin:review; the agent file is a subagent Claude can delegate to; the hooks file holds hooks that run on lifecycle events; and .mcp.json adds an MCP server that gives Claude tools." width="760" height="336" data-path="images/plugin-directory.svg" />

38 39

74 플러그인 마켓플레이스는 [Claude Marketplace](https://claude.com/marketplace)가 아닙니다. Claude Marketplace는 claude.com/marketplace의 웹사이트로, 플러그인, 커넥터, 파트너 제품 및 서비스 파트너를 검색할 수 있습니다. `/plugin marketplace add`로 추가하는 마켓플레이스가 아닙니다.75 플러그인 마켓플레이스는 [Claude Marketplace](https://claude.com/marketplace)가 아닙니다. Claude Marketplace는 claude.com/marketplace의 웹사이트로, 플러그인, 커넥터, 파트너 제품 및 서비스 파트너를 검색할 수 있습니다. `/plugin marketplace add`로 추가하는 마켓플레이스가 아닙니다.

75</Note>76</Note>

76 77

77Claude Code는 [관리 정책](/docs/ko/plugins/org#allow-the-official-marketplace-and-your-own)이 차단하지 않는 한 대화형 터미널 세션을 처음 시작할 때 Anthropic의 공식 마켓플레이스를 추가합니다. Claude Code는 Anthropic의 커뮤니티 및 데모 마켓플레이스를 포함하여 자체적으로 다른 마켓플레이스를 추가하지 않습니다. 세 가지 Anthropic 마켓플레이스를 구분하려면 [Anthropic의 마켓플레이스](/docs/ko/plugins/anthropic-marketplaces)를 읽으세요. 공식 마켓플레이스가 나열하는 것을 보려면 세션에서 `/plugin`의 **Discover** 탭을 열거나 [Claude Marketplace](https://claude.com/marketplace/plugins)를 검색하세요.78Claude Code는 [관리 정책](/docs/ko/plugins/org#allow-the-official-marketplace-and-your-own)이 차단하지 않는 한 대화형 터미널 세션을 처음 시작할 때 Anthropic의 공식 마켓플레이스를 추가합니다. Claude Code는 Anthropic의 커뮤니티 및 데모 마켓플레이스를 자체적으로 추가하지 않습니다. 세 가지 Anthropic 마켓플레이스를 구분하려면 [Anthropic의 마켓플레이스](/docs/ko/plugins/anthropic-marketplaces)를 읽으세요. 공식 마켓플레이스가 나열하는 것을 보려면 세션에서 `/plugin`의 **Discover** 탭을 열거나 [Claude Marketplace](https://claude.com/marketplace/plugins)를 검색하세요.

78 79

79이 다이어그램은 마켓플레이스에서 세션까지의 경로를 보여줍니다. 마켓플레이스는 플러그인을 나열하고, 플러그인을 설치하면 Claude Code가 구성 요소를 로드합니다.80이 다이어그램은 마켓플레이스에서 세션까지의 경로를 보여줍니다. 마켓플레이스는 플러그인을 나열하고, 플러그인을 설치하면 Claude Code가 구성 요소를 로드합니다.

80 81

plugins/security.md +2 −1

Details

29플러그인은 사용자 권한으로 머신에서 실행되는 코드와 Claude의 컨텍스트에 지침으로 입력되는 콘텐츠를 포함할 수 있으므로 [플러그인을 설치하기 전에 검토하십시오](#review-a-plugin-before-you-install). 설치된 플러그인이 할 수 있는 것은 다음과 같습니다:29플러그인은 사용자 권한으로 머신에서 실행되는 코드와 Claude의 컨텍스트에 지침으로 입력되는 콘텐츠를 포함할 수 있으므로 [플러그인을 설치하기 전에 검토하십시오](#review-a-plugin-before-you-install). 설치된 플러그인이 할 수 있는 것은 다음과 같습니다:

30 30

31* **Hooks**: 플러그인의 [hooks](/docs/ko/hooks)는 도구 호출 전후와 같이 Claude Code의 수명 주기의 특정 지점에서 셸 명령으로 실행됩니다.31* **Hooks**: 플러그인의 [hooks](/docs/ko/hooks)는 도구 호출 전후와 같이 Claude Code의 수명 주기의 특정 지점에서 셸 명령으로 실행됩니다.

32* **Mods**: 플러그인의 [mod](/docs/ko/plugins/mods/overview)는 Claude Code 내에서 사용자의 권한으로 JavaScript를 실행합니다. 설치하기 전에 mod가 수행하는 작업을 나열하려면 [mod를 신뢰할지 결정하기](/docs/ko/plugins/mods/overview#decide-whether-to-trust-a-mod)를 참조하십시오.

32* **MCP 및 LSP 서버**: Claude Code는 활성화된 플러그인이 선언하는 [MCP 서버](/docs/ko/mcp)에 연결되고 Claude에 해당 도구를 제공합니다. stdio MCP 서버는 Claude Code가 머신에서 시작하는 프로세스로 실행됩니다. Claude Code는 플러그인이 선언하는 언어 서버도 시작합니다.33* **MCP 및 LSP 서버**: Claude Code는 활성화된 플러그인이 선언하는 [MCP 서버](/docs/ko/mcp)에 연결되고 Claude에 해당 도구를 제공합니다. stdio MCP 서버는 Claude Code가 머신에서 시작하는 프로세스로 실행됩니다. Claude Code는 플러그인이 선언하는 언어 서버도 시작합니다.

33* **`bin/` 디렉토리**: Claude Code는 활성화된 각 플러그인의 `bin/` 디렉토리를 Bash 도구의 셸의 `PATH`에 추가하므로 Claude의 Bash 명령은 여기의 모든 실행 파일을 실행할 수 있습니다.34* **`bin/` 디렉토리**: Claude Code는 활성화된 각 플러그인의 `bin/` 디렉토리를 Bash 도구의 셸의 `PATH`에 추가하므로 Claude의 Bash 명령은 여기의 모든 실행 파일을 실행할 수 있습니다.

34* **Skills, commands, and agents**: 이들은 Claude의 컨텍스트에 지침으로 입력되므로 Claude가 이미 가지고 있는 도구로 수행하는 작업에 영향을 미칩니다.35* **Skills, commands, and agents**: 이들은 Claude의 컨텍스트에 지침으로 입력되므로 Claude가 이미 가지고 있는 도구로 수행하는 작업에 영향을 미칩니다.

37Claude Code의 [권한 규칙](/docs/ko/permissions) 및 [sandbox](/docs/ko/sandboxing)는 Claude가 수행하는 도구 호출을 다루며, 플러그인이 자체적으로 실행하는 코드는 다루지 않습니다:38Claude Code의 [권한 규칙](/docs/ko/permissions) 및 [sandbox](/docs/ko/sandboxing)는 Claude가 수행하는 도구 호출을 다루며, 플러그인이 자체적으로 실행하는 코드는 다루지 않습니다:

38 39

39* **Hooks 및 서버 프로세스**: 명령 hooks는 전체 사용자 권한으로 셸 명령을 실행합니다. Claude Code는 hooks 및 MCP 서버를 sandbox 외부에서 실행합니다.40* **Hooks 및 서버 프로세스**: 명령 hooks는 전체 사용자 권한으로 셸 명령을 실행합니다. Claude Code는 hooks 및 MCP 서버를 sandbox 외부에서 실행합니다.

40* **Claude의 도구 호출**: 플러그인의 MCP 도구 중 하나에 대한 호출 및 플러그인의 `bin/`에서 실행 파일을 실행하는 Bash 명령은 도구 호출이므로 권한 규칙이 적용됩니다.41* **Claude의 도구 호출**: 플러그인의 MCP 도구 중 하나에 대한 호출 및 플러그인의 `bin/`에서 실행 파일을 실행하는 Bash 명령은 도구 호출이므로 권한 규칙이 적용됩니다. mod가 도구 호출에 수행할 수 있는 작업에 대해서는 [mod를 신뢰할지 결정하기](/docs/ko/plugins/mods/overview#decide-whether-to-trust-a-mod)를 참조하십시오.

41 42

42플러그인을 설치하면 해당 매니페스트 또는 마켓플레이스 항목이 [`defaultEnabled: false`](/docs/ko/plugins/install#choose-an-install-scope)를 설정하고 사용자가 직접 활성화하지 않은 경우를 제외하고는 플러그인이 활성화됩니다.43플러그인을 설치하면 해당 매니페스트 또는 마켓플레이스 항목이 [`defaultEnabled: false`](/docs/ko/plugins/install#choose-an-install-scope)를 설정하고 사용자가 직접 활성화하지 않은 경우를 제외하고는 플러그인이 활성화됩니다.

43 44

plugins/troubleshooting.md +41 −2

Details

201 201

202성공적인 추가는 `Successfully added marketplace: <name>`을 인쇄합니다.202성공적인 추가는 `Successfully added marketplace: <name>`을 인쇄합니다.

203 203

204<h3 id="invalid-git-url">

205 `Invalid git URL`

206</h3>

207

208마켓플레이스를 추가하거나, 플러그인을 설치하거나, git 주소에서 업데이트를 실행했고, 명령이 메시지에 `Invalid git URL`로 실패했습니다.

209

210Claude Code는 git을 실행하기 전에 모든 git 주소를 확인합니다. 지원하지 않는 프로토콜이 있는 주소를 거부합니다. 또한 git이 주소가 표시하는 것과 다른 서버 또는 폴더의 이름을 지정하는 것으로 읽을 수 있는 주소를 거부합니다.

211

212주소 뒤의 텍스트는 변경할 내용의 이름을 지정합니다. 메시지가 말하는 대로 주소를 다시 작성하고 명령을 다시 실행합니다.

213

214대신 `is blocked by enterprise policy`라고 말하는 거부는 조직의 설정에서 나옵니다. [마켓플레이스 소스가 엔터프라이즈 정책에 의해 차단됨](#marketplace-source-is-blocked-by-enterprise-policy)을 참조합니다.

215

204<h3 id="path-does-not-exist">216<h3 id="path-does-not-exist">

205 `Path does not exist: <path>`217 `Path does not exist: <path>`

206</h3>218</h3>

410 422

411셸의 `claude plugin install`은 다른 메시지를 인쇄합니다. 대상 범위에 이미 설치된 플러그인의 경우 `Plugin "<name>@<marketplace>" is already installed (scope: user)`를 인쇄하고 종료 코드 0으로 종료합니다. 캐시 디렉토리가 누락된 경우 동일한 명령이 다시 다운로드합니다.423셸의 `claude plugin install`은 다른 메시지를 인쇄합니다. 대상 범위에 이미 설치된 플러그인의 경우 `Plugin "<name>@<marketplace>" is already installed (scope: user)`를 인쇄하고 종료 코드 0으로 종료합니다. 캐시 디렉토리가 누락된 경우 동일한 명령이 다시 다운로드합니다.

412 424

425<h3 id="plugin-would-share-its-folder">

426 `"<plugin>" was not installed: it would share its folder with "<other>"`

427</h3>

428

429`claude plugin install`, `/plugin` 또는 세션의 설치 제안을 통해 플러그인을 설치했고, Claude Code가 이 줄로 거부했거나 `would share its saved data with`로 거부했습니다.

430

431거부된 플러그인의 id와 설치된 플러그인의 id는 디스크의 동일한 폴더에 매핑됩니다: `.`과 `@`이 `-`로 작성되면 동일합니다. macOS 및 Windows에서 대문자만 다른 id도 동일한 폴더에 매핑됩니다. 둘 다 설치하면 한 플러그인의 파일이 다른 플러그인의 폴더에 들어가므로 Claude Code는 거부하고 설치된 플러그인이 파일을 유지합니다.

432

433메시지는 해결 방법을 지정합니다:

434

435* **다른 플러그인이 설치됨**: 메시지는 `Only one of the two can be installed.`라고 말하고 다른 플러그인을 제거하는 `claude plugin uninstall` 명령 또는 `/plugin`의 제거 단계를 지정합니다. 실행한 다음 다시 설치합니다. 제거가 제거하는 것에 대해서는 [제거가 삭제하고 유지하는 것](/docs/ko/plugins/cli-reference#what-an-uninstall-deletes-and-keeps)을 참조합니다.

436* **두 id가 한 번의 설치에 도착함**: 플러그인과 필요한 종속성 같은 경우: 설치 순서는 도움이 되지 않습니다. 두 플러그인을 나열하는 마켓플레이스의 유지 관리자만 이름을 바꿔서 수정할 수 있습니다. 두 플러그인이 다른 마켓플레이스에서 올 때 둘 중 하나의 유지 관리자가 수정할 수 있습니다.

437

413<h3 id="this-plugin-uses-a-source-type-your-claude-code-version-does-not-suppo">438<h3 id="this-plugin-uses-a-source-type-your-claude-code-version-does-not-suppo">

414 `This plugin uses a source type your Claude Code version does not support`439 `This plugin uses a source type your Claude Code version does not support`

415</h3>440</h3>

790* **`URL is unset or invalid`**: URL이 사용하는 `${user_config.*}` 옵션이 설정되지 않았습니다. `/plugin configure <plugin>`을 실행하여 설정합니다.815* **`URL is unset or invalid`**: URL이 사용하는 `${user_config.*}` 옵션이 설정되지 않았습니다. `/plugin configure <plugin>`을 실행하여 설정합니다.

791* **`has an invalid MCP url`** 또는 **`headersHelper for MCP server '<server>' references ${user_config.*}`**: 플러그인 자체의 구성이 잘못되었습니다. 플러그인의 MCP 구성에서 `url` 또는 `headersHelper`를 수정하거나 플러그인이 당신의 것이 아니면 플러그인 작성자에게 보고합니다. `headersHelper` 경우는 [플러그인 명령이 user\_config를 참조](/docs/ko/errors#plugin-command-references-user-config) 아래에 자체 항목이 있습니다.816* **`has an invalid MCP url`** 또는 **`headersHelper for MCP server '<server>' references ${user_config.*}`**: 플러그인 자체의 구성이 잘못되었습니다. 플러그인의 MCP 구성에서 `url` 또는 `headersHelper`를 수정하거나 플러그인이 당신의 것이 아니면 플러그인 작성자에게 보고합니다. `headersHelper` 경우는 [플러그인 명령이 user\_config를 참조](/docs/ko/errors#plugin-command-references-user-config) 아래에 자체 항목이 있습니다.

792 817

818<h4 id="bundled-mcp-server-name-was-not-started-it-needs-configuration">

819 `Bundled MCP server "<name>" was not started: it needs configuration`

820</h4>

821

822플러그인은 서버를 [MCPB 번들](/docs/ko/plugins/components#include-a-packaged-mcpb-server)로 포함하고 `user_config`를 선언하며, 필수 설정에 저장된 값이 없거나 저장된 값이 번들 자체의 유효성 검사에 실패하므로 Claude Code는 서버 시작을 건너뜁니다. 플러그인의 나머지는 작동합니다.

823

824`/plugin`의 **Installed** 탭에서 플러그인을 선택하고 **Configure**를 선택하여 값을 제공합니다. 저장한 후 `/plugin`은 `Configuration saved.`를 표시하고 닫으며 Claude Code는 [설치된 플러그인 관리](/docs/ko/plugins/install#manage-installed-plugins) 아래에 설명된 대로 플러그인을 다시 로드합니다. 해당 다시 로드가 적용되면 서버가 시작됩니다. v2.1.285 이전에는 Claude Code가 이 줄을 표시하지 않고 서버를 건너뛰었습니다.

825

793<h4 id="server-is-configured-but-never-connects">826<h4 id="server-is-configured-but-never-connects">

794 서버가 구성되었지만 절대 연결되지 않음827 서버가 구성되었지만 절대 연결되지 않음

795</h4>828</h4>

934 967

935플러그인이 `userConfig` 옵션을 선언하지만 설치할 때 구성 대화상자가 나타나지 않습니다.968플러그인이 `userConfig` 옵션을 선언하지만 설치할 때 구성 대화상자가 나타나지 않습니다.

936 969

937대화형 설치는 대화상자를 표시하고 셸 명령은 대신 값을 플래그로 사용합니다:970설치가 값을 요청하는지 여부는 실행 위치에 따라 다릅니다:

938 971

939* **세션의 `/plugin install` 또는 `/plugin`의 Discover 탭**: 대화상자는 이 대화형 설치의 일부입니다.972* **세션의 `/plugin install` 또는 `/plugin`의 Discover 탭**: 대화상자는 이 대화형 설치의 일부입니다.

973* **VS Code 확장의 플러그인 관리 대화상자**: 설정되지 않은 옵션을 설치 후 양식으로 요청합니다. v2.1.285 이전에는 거기서 설치할 때 옵션 양식을 표시하지 않았으므로 `/plugin configure <plugin>@<marketplace>`를 사용하여 터미널 세션에서 값을 설정합니다.

940* **셸의 `claude plugin install`**: 절대 `userConfig` 값을 묻지 않습니다. 전달하는 `--config KEY=VALUE` 값을 저장하고 옵션이 설정되지 않으면 `N userConfig options not yet set — run /plugin configure <plugin>@<marketplace> in Claude Code, or pass --config KEY=VALUE.`를 인쇄합니다. 설정되지 않은 옵션이 필수이면 `(M required)`가 `not yet set`을 따릅니다.974* **셸의 `claude plugin install`**: 절대 `userConfig` 값을 묻지 않습니다. 전달하는 `--config KEY=VALUE` 값을 저장하고 옵션이 설정되지 않으면 `N userConfig options not yet set — run /plugin configure <plugin>@<marketplace> in Claude Code, or pass --config KEY=VALUE.`를 인쇄합니다. 설정되지 않은 옵션이 필수이면 `(M required)`가 `not yet set`을 따릅니다.

941 975

942셸에서 설치한 경우 `--config`로 값을 전달합니다. 옵션당 하나의 플래그:976셸에서 설치한 경우 `--config`로 값을 전달합니다. 옵션당 하나의 플래그:

945claude plugin install my-plugin@my-marketplace --config api_url=https://example.com979claude plugin install my-plugin@my-marketplace --config api_url=https://example.com

946```980```

947 981

948모든 옵션이 설정되면 설치 출력에 `not yet set` 줄이 없습니다. 대신 나중에 대화상자를 열려면 세션에서 `/plugin configure my-plugin@my-marketplace`를 실행합니다.982모든 옵션이 설정되면 설치 출력에 `not yet set` 줄이 없습니다.

983

984대신 나중에 대화상자를 열려면 세션에서 `/plugin configure my-plugin@my-marketplace`를 실행합니다. 셸에서 [`claude plugin configure`](/docs/ko/plugins/cli-reference#plugin-configure)는 어떤 옵션이 아직 설정되지 않았는지 표시하고 stdin에서 파이프된 값을 저장합니다. Claude Code v2.1.285 이상이 필요합니다.

949 985

950매니페스트가 선언하지 않는 `--config` 키를 전달하면 플러그인이 여전히 설치되고 명령이 `⚠ Installed, but --config not applied: --config key "<key>" isn't declared in this plugin's userConfig.`를 인쇄합니다. 플러그인이 선언하는 키를 따릅니다.986매니페스트가 선언하지 않는 `--config` 키를 전달하면 플러그인이 여전히 설치되고 명령이 `⚠ Installed, but --config not applied: --config key "<key>" isn't declared in this plugin's userConfig.`를 인쇄합니다. 플러그인이 선언하는 키를 따릅니다.

951 987

988자체 `user_config`를 선언하는 [MCPB 번들 파일](/docs/ko/plugins/components#include-a-packaged-mcpb-server)을 제공하는 플러그인의 경우 메시지는 `isn't declared in this plugin's userConfig or by its bundled MCP servers.`로 읽고 알려진 키는 해당 서버의 키를 포함하며 `<server>.<key>`로 작성됩니다. 매니페스트가 URL로 참조하는 번들은 설치 시간에 읽지 않으므로 해당 키는 나열되지 않으며 메시지는 `/plugin`에서 구성하도록 말합니다. `<server>.<key>` 키 설정에는 Claude Code v2.1.285 이상이 필요합니다.

989

952<h3 id="claude-plugin-validate-reports-errors">990<h3 id="claude-plugin-validate-reports-errors">

953 `claude plugin validate`가 오류를 보고991 `claude plugin validate`가 오류를 보고

954</h3>992</h3>

969| `Path is a file; skills entries must be directories containing SKILL.md` | `skills` 항목이 디렉토리 대신 `SKILL.md`를 가리킵니다. | 부모 디렉토리를 가리키거나 루트 수준 `SKILL.md`의 경우 `.`를 가리킵니다. |1007| `Path is a file; skills entries must be directories containing SKILL.md` | `skills` 항목이 디렉토리 대신 `SKILL.md`를 가리킵니다. | 부모 디렉토리를 가리키거나 루트 수준 `SKILL.md`의 경우 `.`를 가리킵니다. |

970| `No frontmatter block found` 또는 `YAML frontmatter failed to parse: <error>` | 스킬, 에이전트 또는 명령 파일에 누락되거나 유효하지 않은 YAML frontmatter가 있습니다. | `---` 구분 기호 사이에 frontmatter를 추가하거나 수정합니다. 플러그인 디렉토리를 검증할 때 보고됩니다. |1008| `No frontmatter block found` 또는 `YAML frontmatter failed to parse: <error>` | 스킬, 에이전트 또는 명령 파일에 누락되거나 유효하지 않은 YAML frontmatter가 있습니다. | `---` 구분 기호 사이에 frontmatter를 추가하거나 수정합니다. 플러그인 디렉토리를 검증할 때 보고됩니다. |

1009| `Plugin name "<name>" is reserved: it passes as one of Anthropic's own` | 플러그인의 `name`은 [예약된 이름](/docs/ko/plugins/manifest-reference#name) 중 하나입니다. | 플러그인이 수행하는 작업에 대해 플러그인의 이름을 바꿉니다. |

972 1011

973각 수정 후 오류가 없을 때까지 명령을 다시 실행합니다.1012각 수정 후 오류가 없을 때까지 명령을 다시 실행합니다.

scheduled-tasks.md +1 −1

Details

84<span id="loop-provider-differences" />84<span id="loop-provider-differences" />

85 85

86<Note>86<Note>

87 동적으로 선택된 간격과 [내장 유지보수 프롬프트](#run-the-built-in-maintenance-prompt)는 모든 제공자에서 작동하며, [기능 플래그 가져오기](/docs/ko/env-vars#features-that-need-feature-flag-fetching)가 꺼져 있어도 작동합니다. Amazon Bedrock, Claude Platform on AWS, Google Cloud의 Agent Platform, Microsoft Foundry에서 또는 가져오기가 꺼져 있을 때, 둘 다 Claude Code v2.1.248 이상이 필요합니다. 이러한 경우 이전 버전에서는 간격이 없는 프롬프트가 고정 10분 스케줄에서 실행되고, 프롬프트가 없는 `/loop`는 사용 메시지를 출력합니다.87 동적으로 선택된 간격과 [내장 유지보수 프롬프트](#run-the-built-in-maintenance-prompt)는 모든 제공자에서 작동하며, [기능 플래그 가져오기](/docs/ko/env-vars#features-that-need-feature-flag-fetching)가 꺼져 있어도 작동합니다. Amazon Bedrock, Claude Platform on AWS, Google Cloud의 Agent Platform, Microsoft Foundry에서 또는 가져오기가 꺼져 있을 때, 둘 다 Claude Code v2.1.248 이상이 필요합니다.

88</Note>88</Note>

89 89

90<h3 id="run-the-built-in-maintenance-prompt">90<h3 id="run-the-built-in-maintenance-prompt">

self-hosted-environments.md +1 −1

Details

87러너는 한 번에 하나의 소유자를 제공합니다. 러너가 선택하는 첫 번째 세션이 러너를 해당 세션의 소유자에게 잠그고, 러너는 그 후 구성된 용량까지 해당 소유자의 세션만 실행합니다. 소유자가 누구인지는 세션이 어떻게 시작되었는지에 따라 다릅니다:87러너는 한 번에 하나의 소유자를 제공합니다. 러너가 선택하는 첫 번째 세션이 러너를 해당 세션의 소유자에게 잠그고, 러너는 그 후 구성된 용량까지 해당 소유자의 세션만 실행합니다. 소유자가 누구인지는 세션이 어떻게 시작되었는지에 따라 다릅니다:

88 88

89* **사용자가 시작한 세션**: 소유자는 해당 사용자의 계정입니다.89* **사용자가 시작한 세션**: 소유자는 해당 사용자의 계정입니다.

90* **Claude Tag 채널 세션**: Claude는 사용자 계정이 없는 상태로 실행하므로, 소유자는 세션을 시작한 [Claude Tag 에이전트](https://claude.com/docs/claude-tag/concepts/glossary#agent-identity)입니다. 해당 에이전트가 시작하는 모든 채널 세션은 Slack 메시지를 보낸 사람이 누구든 동일한 소유자를 가지므로, `--capacity` 이상 또는 양수 `--drain-grace-sec`로 실행할 때 러너가 잠긴 경우 다양한 사람들이 시작한 세션을 제공합니다. 사용자에게 잠긴 러너는 이를 선택하지 않으며, Claude Tag 에이전트에게 잠긴 러너는 사용자의 세션을 선택하지 않습니다.90* **Claude Tag 채널 세션**: Claude는 사용자 계정이 없는 상태로 실행하므로, 소유자는 세션을 시작한 [Claude Tag 에이전트](https://claude.com/docs/claude-tag/concepts/glossary#agent-identity)입니다. 해당 에이전트가 시작하는 모든 채널 세션은 Slack 메시지를 보낸 사람이 누구든 동일한 소유자를 가지므로, `--capacity` 이상 또는 양수 `--drain-grace-sec`로 실행할 때 러너가 잠긴 경우 다양한 사람들이 시작한 세션을 제공합니다.

91 91

92따라서 최소 플릿 크기는 한 번에 활성화될 것으로 예상되는 소유자의 수이며, 사용자와 Claude Tag 에이전트를 계산합니다.92따라서 최소 플릿 크기는 한 번에 활성화될 것으로 예상되는 소유자의 수이며, 사용자와 Claude Tag 에이전트를 계산합니다.

93 93

server-managed-settings.md +2 −1

Details

163 관리 소스 전체의 키별 예외163 관리 소스 전체의 키별 예외

164</h3>164</h3>

165 165

166세 가지 종류의 키가 병합 금지 규칙의 예외입니다:166이러한 키는 병합 금지 규칙의 예외입니다:

167 167

168* **교차 소스 잠금 키**: 샌드박스 허용 목록 잠금과 같은 작은 키 집합으로, [관리 설정 페이지에 나열되어 있습니다](/docs/ko/managed-settings#precedence-within-the-managed-tier). Claude Code는 관리자 제어 관리 소스가 이들을 설정할 때 이들을 준수합니다. 사용자 쓰기 가능 HKCU 레지스트리 계층은 제외됩니다.168* **교차 소스 잠금 키**: 샌드박스 허용 목록 잠금과 같은 작은 키 집합으로, [관리 설정 페이지에 나열되어 있습니다](/docs/ko/managed-settings#precedence-within-the-managed-tier). Claude Code는 관리자 제어 관리 소스가 이들을 설정할 때 이들을 준수합니다. 사용자 쓰기 가능 HKCU 레지스트리 계층은 제외됩니다.

169 169

171* **`env` 블록**: 자격증명 키와 쌍을 이루는 원격 분석 단위 및 라우팅 변수를 제외하고(아래에서 다룸), 관리자 제어 소스 전체에서 키별로 병합됩니다. 각 환경 변수에 대해 이를 정의하는 가장 높은 우선순위 소스가 우승하며, 낮은 관리 소스는 높은 소스가 설정하지 않은 변수를 채웁니다. 따라서 엔드포인트 관리 `env` 항목은 서버 관리 구성이 해당 변수를 설정하지 않을 때마다 적용되거나, 캐시된 서버 값이 [서버 확인 대기 중](#fetch-and-caching-behavior)일 때 적용됩니다. Claude Code v2.1.223 이상이 필요합니다. v2.1.223 이전에는 Claude Code가 선택된 소스의 전체 `env` 블록만 적용합니다.171* **`env` 블록**: 자격증명 키와 쌍을 이루는 원격 분석 단위 및 라우팅 변수를 제외하고(아래에서 다룸), 관리자 제어 소스 전체에서 키별로 병합됩니다. 각 환경 변수에 대해 이를 정의하는 가장 높은 우선순위 소스가 우승하며, 낮은 관리 소스는 높은 소스가 설정하지 않은 변수를 채웁니다. 따라서 엔드포인트 관리 `env` 항목은 서버 관리 구성이 해당 변수를 설정하지 않을 때마다 적용되거나, 캐시된 서버 값이 [서버 확인 대기 중](#fetch-and-caching-behavior)일 때 적용됩니다. Claude Code v2.1.223 이상이 필요합니다. v2.1.223 이전에는 Claude Code가 선택된 소스의 전체 `env` 블록만 적용합니다.

172 * **원격 분석 단위**: `OTEL_EXPORTER_OTLP_*` 내보내기 키, `OTEL_LOG_*` 콘텐츠 캡처 토글, `OTEL_LOGS_EXPORTER`, 그리고 베타 추적 변수 `ENABLE_BETA_TRACING_DETAILED` 및 `BETA_TRACING_ENDPOINT`는 이들 중 하나를 설정하는 가장 높은 소스를 단위로 따릅니다. `otelHeadersHelper` 자격증명 키를 전달하는 소스는 단위를 주장하지만, 선택된 소스일 때만 이러한 변수를 제공합니다. 선택되지 않은 소스가 키를 전달하면 이들 중 어느 것도 제공하지 않으며 여전히 낮은 소스가 이들을 채우는 것을 차단합니다. 어느 쪽이든, 한 소스의 내보내기 엔드포인트는 다른 소스의 자격증명과 쌍을 이룰 수 없습니다.172 * **원격 분석 단위**: `OTEL_EXPORTER_OTLP_*` 내보내기 키, `OTEL_LOG_*` 콘텐츠 캡처 토글, `OTEL_LOGS_EXPORTER`, 그리고 베타 추적 변수 `ENABLE_BETA_TRACING_DETAILED` 및 `BETA_TRACING_ENDPOINT`는 이들 중 하나를 설정하는 가장 높은 소스를 단위로 따릅니다. `otelHeadersHelper` 자격증명 키를 전달하는 소스는 단위를 주장하지만, 선택된 소스일 때만 이러한 변수를 제공합니다. 선택되지 않은 소스가 키를 전달하면 이들 중 어느 것도 제공하지 않으며 여전히 낮은 소스가 이들을 채우는 것을 차단합니다. 어느 쪽이든, 한 소스의 내보내기 엔드포인트는 다른 소스의 자격증명과 쌍을 이룰 수 없습니다.

173 * **자격증명 쌍 라우팅**: `apiKeyHelper` 또는 `otelHeadersHelper`와 같은 선택된 소스 전용 자격증명 키와 라우팅 변수를 쌍으로 하는 소스는 해당 슬롯을 획득할 때만 이러한 라우팅 변수를 제공합니다.173 * **자격증명 쌍 라우팅**: `apiKeyHelper` 또는 `otelHeadersHelper`와 같은 선택된 소스 전용 자격증명 키와 라우팅 변수를 쌍으로 하는 소스는 해당 슬롯을 획득할 때만 이러한 라우팅 변수를 제공합니다.

174* **`allowedProviders`**: 머신에 설정된 목록과 서버 관리 목록은 [그 항목의 범위 참고](/docs/ko/settings-reference#allowedproviders)에 명시된 대로 결합됩니다. Claude Code v2.1.285 이상이 필요합니다.

174* **게이트웨이 로그인 키**: Claude Code는 서버 관리 설정에서 [`forceLoginGatewayUrl`](/docs/ko/settings-reference#forcelogingatewayurl), [`gatewayInternalNetworks`](/docs/ko/settings-reference#gatewayinternalnetworks), 또는 [`forceLoginMethod`](/docs/ko/settings-reference#forceloginmethod)의 `"gateway"` 값을 읽지 않으므로, 거기의 값은 MDM 정책 또는 관리 설정 파일에 설정된 값을 적용하지도 숨기지도 않습니다. [`managedSourcesBehavior` 항목](/docs/ko/settings-reference#managedsourcesbehavior)은 머신의 어느 관리 소스가 이들을 제공하는지 나타냅니다.175* **게이트웨이 로그인 키**: Claude Code는 서버 관리 설정에서 [`forceLoginGatewayUrl`](/docs/ko/settings-reference#forcelogingatewayurl), [`gatewayInternalNetworks`](/docs/ko/settings-reference#gatewayinternalnetworks), 또는 [`forceLoginMethod`](/docs/ko/settings-reference#forceloginmethod)의 `"gateway"` 값을 읽지 않으므로, 거기의 값은 MDM 정책 또는 관리 설정 파일에 설정된 값을 적용하지도 숨기지도 않습니다. [`managedSourcesBehavior` 항목](/docs/ko/settings-reference#managedsourcesbehavior)은 머신의 어느 관리 소스가 이들을 제공하는지 나타냅니다.

175 176

176<h3 id="fetch-and-caching-behavior">177<h3 id="fetch-and-caching-behavior">

sessions.md +20 −2

Details

29 29

30`claude --continue`는 완료된 [백그라운드 세션](/docs/ko/agent-view)을 열지만 여전히 실행 중인 세션은 열지 않습니다. 완료된 백그라운드 세션을 열려면 Claude Code v2.1.257 이상이 필요합니다. 가장 최근 대화가 [백그라운드로 이동](/docs/ko/agent-view#send-the-session-to-the-background)한 세션이고 여전히 그곳에서 실행 중인 경우 Claude Code는 `Your most recent conversation is running in the background`와 해당 세션의 ID로 종료됩니다. [`claude agents`](/docs/ko/agent-view#attach-to-a-session)에서 세션에 연결하거나 `claude --resume`을 실행하여 다른 세션을 선택합니다.30`claude --continue`는 완료된 [백그라운드 세션](/docs/ko/agent-view)을 열지만 여전히 실행 중인 세션은 열지 않습니다. 완료된 백그라운드 세션을 열려면 Claude Code v2.1.257 이상이 필요합니다. 가장 최근 대화가 [백그라운드로 이동](/docs/ko/agent-view#send-the-session-to-the-background)한 세션이고 여전히 그곳에서 실행 중인 경우 Claude Code는 `Your most recent conversation is running in the background`와 해당 세션의 ID로 종료됩니다. [`claude agents`](/docs/ko/agent-view#attach-to-a-session)에서 세션에 연결하거나 `claude --resume`을 실행하여 다른 세션을 선택합니다.

31 31

32<span id="resume-a-running-background-session" />

34세션을 `claude --resume` 또는 `/resume`으로 재개할 때 해당 세션이 여전히 실행 중인 [백그라운드 세션](/docs/ko/agent-view)에 속하면 Claude Code는 실행 중인 세션 자체를 엽니다. 명령줄에서 `--bg`를 사용하면 재개는 [백그라운드 디스패치](/docs/ko/agent-view#from-your-shell) 대신입니다. v2.1.285 이전에는 Claude Code가 거부하고 `claude attach <id>`로 세션을 열거나 먼저 `claude stop <id>`로 중지하도록 지시했습니다.

36* **셸에서**: `claude --resume <session>`은 대화 기록 자체를 로드하는 대신 같은 터미널에서 해당 세션에 대해 [`claude attach`](/docs/ko/agent-view#attach-to-a-session)를 실행합니다. `claude --resume <session> "check the tests too"`와 같이 명령줄에서 전달하는 프롬프트는 먼저 세션의 다음 턴으로 이동하고 Claude Code는 `Sent your prompt to the background session (<id>); opening it…`를 출력한 후 연결합니다. 터미널에서 입력한 `claude -p --resume <session> "prompt"`도 동일하게 작동하므로 `-p`는 해당 실행을 비대화형으로 유지하지 않습니다.

38 Claude Code는 명령줄에 다음 중 하나가 있으면 세션을 열지 않습니다:

40 * 파이프되거나 리디렉션된 입력 또는 출력

41 * `--permission-mode`, `--model` 또는 `--settings`와 같이 세션을 구성하는 플래그

42 * `--output-format json` 또는 `--json-schema`와 같이 출력을 읽는 플래그

43 * `--max-turns` 또는 `--max-budget-usd`와 같이 실행을 제한하거나 되감기하는 플래그

45 이 중 하나가 있거나 [에이전트 보기가 꺼져 있으면](/docs/ko/agent-view#turn-off-agent-view) Claude Code는 아무것도 보내지 않고 상태 1로 종료하며 세션이 백그라운드에서 실행 중임을 출력하고 ID를 결정할 수 없을 때 `claude agents`에서 찾도록 지시하거나 `claude attach <id>` 명령을 출력합니다. 대신 대화의 복사본을 재개하려면 `--fork-session`을 추가합니다. 자신의 플래그가 적용된 자신의 세션에서 대화 자체를 계속하려면 `claude stop <id>`를 실행한 다음 명령을 반복합니다.

47 `/` 또는 `!`로 시작하는 프롬프트는 전송되지 않으며 세션이 질문에 대한 답변을 기다리는 동안 어떤 프롬프트도 전송되지 않습니다. 두 경우 모두 Claude Code는 세션을 열지 않으며 메시지에는 `Your prompt was not sent to it`과 이유가 포함됩니다.

48* **세션 내에서**: `/resume`은 현재 대화를 백그라운드로 이동하고 이 터미널을 실행 중인 세션에 연결하며 `Opening "<title>", running in the background (<id>)`를 출력합니다. 빈 프롬프트에서 `←`를 눌러 에이전트 보기로 돌아가면 남긴 대화도 나열됩니다. 현재 대화가 백그라운드로 이동할 수 없으면(예: 이미 백그라운드 세션에 연결되어 있거나 세션 지속성이 꺼져 있음) `/resume`은 대신 실행할 `claude attach` 명령을 출력합니다.

32모든 디렉토리에서 `claude --resume <session-id>`를 실행할 수 있습니다. Claude Code는 현재 프로젝트 디렉토리 및 해당 git worktree에서 ID를 먼저 찾은 다음 이 머신의 다른 모든 프로젝트에서 찾으므로 다른 곳에서 시작되었거나 [`/cd`](/docs/ko/commands)로 이동한 세션을 찾습니다. 교차 프로젝트 검색은 정확히 하나의 다른 프로젝트가 해당 ID에 대한 메시지가 있는 대화 기록을 보유할 때만 ID를 확인하므로 손으로 복사한 중복은 Claude Code가 임의의 복사본을 재개하지 않고 찾을 수 없음을 보고하게 합니다. 저장된 세션이 ID와 일치하지 않으면 Claude Code는 `No conversation found with session ID: <session-id>`를 보고합니다. v2.1.223 이전에는 조회가 현재 프로젝트 디렉토리 및 해당 git worktree에서 중지되었으므로 세션이 마지막으로 작업한 디렉토리에서 재개해야 했습니다.50모든 디렉토리에서 `claude --resume <session-id>`를 실행할 수 있습니다. Claude Code는 현재 프로젝트 디렉토리 및 해당 git worktree에서 ID를 먼저 찾은 다음 이 머신의 다른 모든 프로젝트에서 찾으므로 다른 곳에서 시작되었거나 [`/cd`](/docs/ko/commands)로 이동한 세션을 찾습니다. 교차 프로젝트 검색은 정확히 하나의 다른 프로젝트가 해당 ID에 대한 메시지가 있는 대화 기록을 보유할 때만 ID를 확인하므로 손으로 복사한 중복은 Claude Code가 임의의 복사본을 재개하지 않고 찾을 수 없음을 보고하게 합니다. 저장된 세션이 ID와 일치하지 않으면 Claude Code는 `No conversation found with session ID: <session-id>`를 보고합니다. v2.1.223 이전에는 조회가 현재 프로젝트 디렉토리 및 해당 git worktree에서 중지되었으므로 세션이 마지막으로 작업한 디렉토리에서 재개해야 했습니다.

33 51

34<h3 id="what-a-resumed-session-restores">52<h3 id="what-a-resumed-session-restores">

35 재개된 세션이 복원하는 것53 재개된 세션이 복원하는 것

36</h3>54</h3>

37 55

~~38재개된 세션은 대화와 함께 저장된 상태를 복원합니다:~~56Claude Code가 대화 기록에서 대화를 로드할 때 재개된 세션은 대화와 함께 저장된 상태를 복원합니다:

39 57

40* 대화 기록: 도구 호출 및 결과를 포함한 전체 기록입니다. 이전 프로세스가 종료될 때(예: 충돌) 여전히 실행 중이던 도구는 재개할 때 완료되거나 다시 실행되지 않습니다. Claude는 호출이 결과가 기록되기 전에 중단된 것으로 표시되고 다시 실행하기 전에 효과가 있었는지 확인하도록 지시받으며, [`CLAUDE_CODE_RESUME_INTERRUPTED_TURN`](/docs/ko/env-vars#variables)이 설정되지 않은 경우입니다. v2.1.281 이전에는 Claude Code가 중단된 호출을 대화에서 삭제하거나 사용자가 중단한 것으로 Claude에게 표시했습니다.58* 대화 기록: 도구 호출 및 결과를 포함한 전체 기록입니다. 이전 프로세스가 종료될 때(예: 충돌) 여전히 실행 중이던 도구는 재개할 때 완료되거나 다시 실행되지 않습니다. Claude는 호출이 결과가 기록되기 전에 중단된 것으로 표시되고 다시 실행하기 전에 효과가 있었는지 확인하도록 지시받으며, [`CLAUDE_CODE_RESUME_INTERRUPTED_TURN`](/docs/ko/env-vars#variables)이 설정되지 않은 경우입니다. v2.1.281 이전에는 Claude Code가 중단된 호출을 대화에서 삭제하거나 사용자가 중단한 것으로 Claude에게 표시했습니다.

41* 모델: 세션은 사용 중이던 모델에서 계속됩니다. 모델이 폐기되었거나 `availableModels`에서 허용되지 않을 때, 시작 시 `--model` 플래그 또는 `ANTHROPIC_MODEL` 계열 환경 변수가 모델을 선택할 때, 또는 [Amazon Bedrock, Google Cloud의 Agent Platform 및 Microsoft Foundry](/docs/ko/third-party-integrations)와 같이 공급자별 배포 ID를 사용하는 공급자에서는 모델이 복원되지 않습니다. [모델 구성](/docs/ko/model-config#setting-your-model)에서 해결 순서를 참조하세요.59* 모델: 세션은 사용 중이던 모델에서 계속됩니다. 모델이 폐기되었거나 `availableModels`에서 허용되지 않을 때, 시작 시 `--model` 플래그 또는 `ANTHROPIC_MODEL` 계열 환경 변수가 모델을 선택할 때, 또는 [Amazon Bedrock, Google Cloud의 Agent Platform 및 Microsoft Foundry](/docs/ko/third-party-integrations)와 같이 공급자별 배포 ID를 사용하는 공급자에서는 모델이 복원되지 않습니다. [모델 구성](/docs/ko/model-config#setting-your-model)에서 해결 순서를 참조하세요.

51 재개 시 권한 모드69 재개 시 권한 모드

52</h4>70</h4>

53 71

~~54Claude Code가 재개된 세션을 시작하는 권한 모드는 재개 방식에 따라 달라집니다:~~72Claude Code가 재개된 세션을 시작하는 권한 모드는 재개 방식에 따라 달라집니다. 아래 경우는 Claude Code가 대화 기록에서 대화를 로드할 때 적용됩니다. [여전히 실행 중인 백그라운드 세션을 열 때](#resume-a-running-background-session)는 해당 세션이 있는 권한 모드를 유지합니다.

55 73

56* 터미널: `claude --continue`, `claude --resume <session-id>` 또는 이름이 한 세션과 일치할 때 `-p` 없이 `claude --resume <name>`. Claude Code는 세션이 있던 권한 모드를 복원합니다. 단, 표의 경우는 제외됩니다. `--permission-mode` 또는 `--dangerously-skip-permissions`를 전달하여 복원된 모드를 재정의합니다.74* 터미널: `claude --continue`, `claude --resume <session-id>` 또는 이름이 한 세션과 일치할 때 `-p` 없이 `claude --resume <name>`. Claude Code는 세션이 있던 권한 모드를 복원합니다. 단, 표의 경우는 제외됩니다. `--permission-mode` 또는 `--dangerously-skip-permissions`를 전달하여 복원된 모드를 재정의합니다.

57* 비대화형: `claude -p --resume` 또는 `claude -p --continue`. Claude Code는 새로운 `claude -p` 실행이 시작될 권한 모드로 실행을 시작합니다. 단, 계획 모드에서 종료된 세션은 [아래 조건](#resume-in-plan-mode-with-p)에서 계획 모드로 재개됩니다.75* 비대화형: `claude -p --resume` 또는 `claude -p --continue`. Claude Code는 새로운 `claude -p` 실행이 시작될 권한 모드로 실행을 시작합니다. 단, 계획 모드에서 종료된 세션은 [아래 조건](#resume-in-plan-mode-with-p)에서 계획 모드로 재개됩니다.

settings-reference.md +220 −127

Details

603| [`allowManagedMcpServersOnly`](#allowmanagedmcpserversonly) | 관리되는 [MCP](/docs/ko/mcp) 허용 목록을 유일하게 적용되는 것으로 만들기 | MCP | 관리됨 |604| [`allowManagedMcpServersOnly`](#allowmanagedmcpserversonly) | 관리되는 [MCP](/docs/ko/mcp) 허용 목록을 유일하게 적용되는 것으로 만들기 | MCP | 관리됨 |

1274 1277

1275저장한 수준을 변경하거나 제거하려면 키를 직접 편집합니다.1278저장한 수준을 변경하거나 제거하려면 키를 직접 편집합니다.

1276 1279

1277모델의 `effortLevel`은 동일한 설정 파일의 최상위 [`effortLevel`](#effortlevel)보다 우선합니다. 파일 간에 Claude Code는 각 모델을 별도로 확인합니다: 해당 모델에 대해 `effortLevel`을 설정하거나 [해당 모델에 적용되는](/docs/ko/model-config#adjust-effort-level) 최상위 `effortLevel`을 설정하는 가장 높은 우선순위 [설정 파일](/docs/ko/settings#settings-precedence)이 결정하므로 관리되는 설정의 `effortLevel`은 사용자 설정에서 저장한 수준을 능가합니다. [노력 수준 조정](/docs/ko/model-config#adjust-effort-level)은 저장된 수준을 재정의할 수 있는 다른 것(예: 시작 시 `--effort`)을 나열합니다.1280여기서 지정한 모델의 `effortLevel`은 동일한 설정 파일의 최상위 [`effortLevel`](#effortlevel)보다 우선합니다. 파일 간에 Claude Code는 각 모델을 별도로 확인합니다: 해당 모델에 대해 `effortLevel`을 설정하거나 [해당 모델에 적용되는](#effortlevel) 최상위 `effortLevel`을 설정하는 가장 높은 우선순위 [설정 파일](/docs/ko/settings#settings-precedence)이 결정하므로 관리되는 설정의 `effortLevel`은 사용자 설정에서 저장한 수준보다 우선합니다. [노력 수준 조정](/docs/ko/model-config#adjust-effort-level)은 저장된 수준을 재정의할 수 있는 다른 것(예: 시작 시 `--effort`)을 나열합니다.

1278 1281

1279한 모델의 노력을 설정하는 대신 제한하려면 해당 모델의 항목에 [`maxEffortLevel`](#maxeffortlevel) 필드를 추가합니다. 필드는 Claude Code v2.1.267 이상이 필요합니다.1282한 모델의 노력을 설정하는 대신 제한하려면 해당 모델의 항목에 [`maxEffortLevel`](#maxeffortlevel) 필드를 추가합니다. 필드는 Claude Code v2.1.267 이상이 필요합니다.

1280 1283

3675 `spinnerTipsOverride`3678 `spinnerTipsOverride`

3676</h3>3679</h3>

3677 3680

3678Claude Code가 Claude가 작업하는 동안 표시하는 [스피너 팁](#spinnertipsenabled)에 자신의 팁을 추가하거나 내장 팁을 당신의 것으로 바꿉니다. Claude Code는 당신의 팁을 내장 팁과 동일한 회전에 넣습니다: 가장 오래 표시되지 않은 팁을 선택하고, 여전히 쿨다운 중인 팁을 건너뛰고, 우선순위로 동점을 깹니다.3681Claude Code가 Claude가 작업하는 동안 표시하는 [스피너 팁](#spinnertipsenabled)에 자신의 팁을 추가하거나 내장 팁을 당신의 것으로 바꿉니다. Claude Code는 당신의 팁을 내장 팁과 동일한 회전에 넣습니다.

3679 3682

3680[`spinnerTipsEnabled`](#spinnertipsenabled)을 `false`로 설정하면 Claude Code는 모든 팁(당신의 것 포함)을 숨깁니다.3683[`spinnerTipsEnabled`](#spinnertipsenabled)을 `false`로 설정하면 Claude Code는 모든 팁(당신의 것 포함)을 숨깁니다.

3681 3684

3683* **유형**: `tips`, `tipsFile`, `label` 및 `excludeDefault` 필드를 포함하는 객체, 각각 선택 사항3686* **유형**: `tips`, `tipsFile`, `label` 및 `excludeDefault` 필드를 포함하는 객체, 각각 선택 사항

3684* **기본값**: 설정되지 않음, 따라서 Claude Code는 내장 팁만 표시합니다3687* **기본값**: 설정되지 않음, 따라서 Claude Code는 내장 팁만 표시합니다

3685 3688

3686팁 객체, `tipsFile`, `label` 및 범위 줄의 규칙(프로젝트 및 로컬 설정이 평문 문자열만 기여)에는 Claude Code v2.1.247 이상이 필요합니다. 이전 버전에서는 프로젝트 또는 로컬 파일의 `excludeDefault`도 적용됩니다.3689팁 객체, `tipsFile`, `label` 및 범위 줄의 규칙(프로젝트 및 로컬 설정이 평문 문자열만 기여)에는 Claude Code v2.1.247 이상이 필요합니다.

3687 3690

3688각 `tips` 항목은 평문 문자열 또는 다음 필드를 포함하는 객체입니다:3691각 `tips` 항목은 평문 문자열 또는 다음 필드를 포함하는 객체입니다:

3689 3692

4305이를 `true`로 설정하면 Claude Code는 로드되는 훅 및 훅과 유사한 명령을 변경합니다:4308이를 `true`로 설정하면 Claude Code는 로드되는 훅 및 훅과 유사한 명령을 변경합니다:

4306 4309

4307* **관리되는 훅 및 SDK 훅 실행**: 관리되는 설정의 훅 및 [Agent SDK](/docs/ko/agent-sdk/overview)가 프로세스에 등록하는 훅4310* **관리되는 훅 및 SDK 훅 실행**: 관리되는 설정의 훅 및 [Agent SDK](/docs/ko/agent-sdk/overview)가 프로세스에 등록하는 훅

4308* **강제 활성화된 플러그인 훅 실행**: 관리되는 설정이 [`enabledPlugins`](#enabledplugins)를 통해 강제로 활성화하는 플러그인의 훅. Claude Code는 전체 `plugin@marketplace` ID와 일치하므로 다른 마켓플레이스의 동일한 이름의 플러그인은 차단된 상태로 유지됩니다. 이를 통해 조직 마켓플레이스를 통해 검증된 훅을 배포하면서 다른 모든 것을 차단할 수 있습니다.4311* **강제 활성화된 플러그인 훅 실행**: 관리되는 설정이 [`enabledPlugins`](#enabledplugins)를 통해 강제로 활성화하는 플러그인의 훅. Claude Code는 전체 `plugin@marketplace` ID와 일치하므로 다른 마켓플레이스의 동일한 이름의 플러그인은 차단된 상태로 유지됩니다. 이를 통해 조직 마켓플레이스를 통해 검증된 훅을 배포하면서 다른 모든 것을 차단할 수 있습니다. 이러한 플러그인의 [mod](/docs/ko/plugins/mods/overview)는 [조직의 것으로 계산될 때](/docs/ko/plugins/mods/admin#install-your-organizations-mods)만 로드됩니다.

4309* **다른 모든 것은 차단됨**: 사용자, 프로젝트 및 로컬 훅, 다른 플러그인의 훅, 에이전트 프론트매터에 선언된 훅4312* **다른 모든 것은 차단됨**: 사용자, 프로젝트 및 로컬 훅, 다른 설치된 플러그인의 훅 및 mod, 에이전트 프론트매터에 선언된 훅. [Claude Code에 내장된 mod](/docs/ko/plugins/mods/overview#mods-built-into-claude-code)는 계속 실행됩니다. 사용자의 mod만 차단하려면 [`allowManagedModsOnly`](/docs/ko/plugins/mods/admin#set-options-on-the-built-in-guard)를 대신 설정합니다.

4310* **명령 소스 플러그인 비활성화**: Claude Code는 또한 [`disableCommandPluginSources`](#disablecommandpluginsources)를 명시적으로 `false`로 설정하지 않는 한 [`command` 소스](/docs/ko/plugins/marketplace-reference#command-plugin-source)가 있는 플러그인(관리되는 `enabledPlugins`에서 강제로 활성화된 플러그인 포함)을 비활성화합니다.4313* **명령 소스 플러그인 비활성화**: Claude Code는 또한 [`disableCommandPluginSources`](#disablecommandpluginsources)를 명시적으로 `false`로 설정하지 않는 한 [`command` 소스](/docs/ko/plugins/marketplace-reference#command-plugin-source)가 있는 플러그인(관리되는 `enabledPlugins`에서 강제로 활성화된 플러그인 포함)을 비활성화합니다.

4311* **마켓플레이스 `headersHelper` 명령 차단**: Claude Code는 또한 [`disableCommandPluginSources`](#disablecommandpluginsources)가 명시적으로 `false`로 설정되지 않는 한 마켓플레이스 [`headersHelper` 명령](/docs/ko/plugins/host-marketplace#authenticate-archive-downloads)을 차단합니다. 단, 관리되는 설정 자체가 선언하는 마켓플레이스는 제외됩니다. Claude Code v2.1.238 이상이 필요합니다.4314* **마켓플레이스 `headersHelper` 명령 차단**: Claude Code는 또한 [`disableCommandPluginSources`](#disablecommandpluginsources)가 명시적으로 `false`로 설정되지 않는 한 마켓플레이스 [`headersHelper` 명령](/docs/ko/plugins/host-marketplace#authenticate-archive-downloads)을 차단합니다. 단, 관리되는 설정 자체가 선언하는 마켓플레이스는 제외됩니다. Claude Code v2.1.238 이상이 필요합니다.

4312* **상태 줄 및 파일 제안이 관리되는 설정으로 좁혀짐**: Claude Code는 [상태 줄 및 파일 제안 게이트](#status-line-and-file-suggestion-gates)를 따르면서 관리되는 설정에서만 [`statusLine`](/docs/ko/statusline), [`fileSuggestion`](#filesuggestion), [`subagentStatusLine`](/docs/ko/statusline#subagent-status-lines)을 읽습니다.4315* **상태 줄 및 파일 제안이 관리되는 설정으로 좁혀짐**: Claude Code는 [상태 줄 및 파일 제안 게이트](#status-line-and-file-suggestion-gates)를 따르면서 관리되는 설정에서만 [`statusLine`](/docs/ko/statusline), [`fileSuggestion`](#filesuggestion), [`subagentStatusLine`](/docs/ko/statusline#subagent-status-lines)을 읽습니다.

4492 플러그인 및 스킬4495 플러그인 및 스킬

4493</h2>4496</h2>

4494 4497

4495플러그인을 활성화하고, 마켓플레이스를 등록하고, 조직이 허용하는 플러그인 소스를 제한하고, 로드되는 스킬을 제어합니다. 플러그인 설치 및 빌드에 대해서는 [플러그인](/docs/ko/plugins/overview)을 참조하십시오.4498플러그인을 활성화하고, 마켓플레이스를 등록하고, 조직이 허용하는 플러그인 소스를 제한하고, 로드되는 스킬을 제어합니다. 플러그인 설치 및 빌드에 대해서는 [플러그인](/docs/ko/plugins/overview)을 참조하세요.

4496 4499

4497<h3 id="disablebundledskills">4500<h3 id="disablebundledskills">

4498 `disableBundledSkills`4501 `disableBundledSkills`

4499</h3>4502</h3>

4500 4503

4501Claude Code에 포함된 [스킬](/docs/ko/skills) 및 워크플로우를 끕니다. Claude Code는 번들 스킬 및 워크플로우를 완전히 제거하는 한편, `/init`과 같은 기본 제공 명령어는 입력 가능하지만 모델에서 숨겨집니다.4504Claude Code에 포함된 [스킬](/docs/ko/skills) 및 워크플로우를 끕니다. Claude Code는 번들 스킬 및 워크플로우를 완전히 제거하고, `/init`과 같은 기본 제공 명령어는 입력 가능하지만 모델에서 숨겨집니다.

4502 4505

4503* **범위**: [`모든 파일`](#scopes)4506* **범위**: [`모든 파일`](#scopes)

4504* **유형**: 부울4507* **유형**: 부울

4513}4516}

4514```4517```

4515 4518

4516플러그인, `.claude/skills/`, `.claude/commands/`의 스킬은 영향을 받지 않습니다. `/doctor`는 기본 제공 명령어처럼 입력 가능하며, 이를 숨기려면 대신 [`DISABLE_DOCTOR_COMMAND`](/docs/ko/env-vars)를 설정하십시오.4519플러그인, `.claude/skills/`, `.claude/commands/`의 스킬은 영향을 받지 않습니다. `/doctor`는 기본 제공 명령어처럼 입력 가능합니다. 이를 숨기려면 대신 [`DISABLE_DOCTOR_COMMAND`](/docs/ko/env-vars)를 설정하세요.

4517 4520

4518<h3 id="disableskillshellexecution">4521<h3 id="disableskillshellexecution">

4519 `disableSkillShellExecution`4522 `disableSkillShellExecution`

4521 4524

4522[스킬](/docs/ko/skills) 및 사용자, 프로젝트, 플러그인 또는 추가 디렉터리 소스의 사용자 정의 명령어에서 `` !`...` `` 및 ` ```! ` 블록에 대한 인라인 셸 실행을 끕니다. Claude Code는 각 명령어를 실행하는 대신 `[shell command execution disabled by policy]`로 바꿉니다.4525[스킬](/docs/ko/skills) 및 사용자, 프로젝트, 플러그인 또는 추가 디렉터리 소스의 사용자 정의 명령어에서 `` !`...` `` 및 ` ```! ` 블록에 대한 인라인 셸 실행을 끕니다. Claude Code는 각 명령어를 실행하는 대신 `[shell command execution disabled by policy]`로 바꿉니다.

4523 4526

4524* **범위**: [`모든 파일`](#scopes). 관리 설정의 `true`는 다른 곳의 `false`로 재정의될 수 없습니다.4527* **범위**: [`모든 파일`](#scopes). 관리되는 설정의 `true`는 다른 곳의 `false`로 재정의될 수 없습니다.

4525* **유형**: 부울4528* **유형**: 부울

4526 * `true`: Claude Code는 각 인라인 셸 명령어를 실행하는 대신 `[shell command execution disabled by policy]`로 바꿉니다4529 * `true`: Claude Code는 각 인라인 셸 명령어를 실행하는 대신 `[shell command execution disabled by policy]`로 바꿉니다

4527 * `false`: 인라인 셸이 실행됩니다4530 * `false`: 인라인 셸이 실행됩니다

4533}4536}

4534```4537```

4535 4538

4536번들 스킬 및 관리 설정을 통해 배포된 스킬은 영향을 받지 않습니다.4539번들 스킬 및 관리되는 설정을 통해 배포된 스킬은 영향을 받지 않습니다.

4537 4540

4538<h3 id="skilloverrides">4541<h3 id="skilloverrides">

4539 `skillOverrides`4542 `skillOverrides`

4540</h3>4543</h3>

4541 4544

4542[스킬](/docs/ko/skills#override-skill-visibility-from-settings)의 `SKILL.md`를 편집하지 않고 스킬을 숨기거나 축소합니다. Claude Code는 각 스킬 이름 아래의 값을 Claude가 보는 스킬 목록 및 `/` 자동 완성에 적용합니다.4545[스킬](/docs/ko/skills#override-skill-visibility-from-settings)의 `SKILL.md`를 편집하지 않고 숨기거나 축소합니다. Claude Code는 각 스킬 이름 아래의 값을 Claude가 보는 스킬 목록 및 `/` 자동 완성에 적용합니다.

4543 4546

4544* **범위**: [`모든 파일`](#scopes). `/skills` 메뉴는 `.claude/settings.local.json`에 씁니다.4547* **범위**: [`모든 파일`](#scopes). `/skills` 메뉴는 `.claude/settings.local.json`에 씁니다.

4545* **유형**: 스킬 이름을 다음 중 하나에 매핑하는 객체:4548* **유형**: 스킬 이름을 다음 중 하나에 매핑하는 객체:

4560}4563}

4561```4564```

4562 4565

4563재정의는 플러그인 스킬에 적용되지 않으며, `/plugin`을 통해 관리합니다.4566재정의는 플러그인 스킬에 적용되지 않으며, 이는 `/plugin`을 통해 관리합니다.

4564 4567

4565관리 설정 및 `--settings`로 전달된 파일에서 `/doctor`의 `checkup`과 같은 번들 스킬의 별칭에 대한 키도 스킬에 적용됩니다. [별칭 키가 스킬 자체 이름의 키와 어떻게 결합되는지](/docs/ko/skills#override-skill-visibility-from-settings)를 참조하십시오.4568관리되는 설정 및 `--settings`로 전달된 파일에서, `/doctor`의 `checkup`과 같은 번들 스킬의 별칭에 대한 키도 스킬에 적용됩니다. [별칭 키가 스킬 자체 이름의 키와 어떻게 결합되는지](/docs/ko/skills#override-skill-visibility-from-settings)를 참조하세요.

4566 4569

4567<h3 id="syncclaudeaiskills">4570<h3 id="syncclaudeaiskills">

4568 `syncClaudeAiSkills`4571 `syncClaudeAiSkills`

4569</h3>4572</h3>

4570 4573

4571[claude.ai 계정에 대해 활성화된 스킬](/docs/ko/skills#how-synced-skills-behave)의 다운로드를 끕니다. Claude Code는 [claude.ai 계정으로 로그인하는 터미널 세션](/docs/ko/skills#where-synced-skills-load)에서 `~/.claude/skills/synced/`로 다운로드하며, 대화형 또는 비대화형이고 Cowork 및 클라우드 세션에서도 다운로드합니다. `false`로 설정하여 해당 다운로드를 중지하고 이미 동기화된 스킬 로드를 중지합니다. Claude Code는 `false`만 인정합니다. `true`는 설정되지 않은 것과 같으며 다른 곳에서 꺼진 동기화를 켜지 않습니다.4574[claude.ai 계정에 대해 활성화된 스킬](/docs/ko/skills#how-synced-skills-behave)의 다운로드를 끕니다. Claude Code는 [claude.ai 계정으로 로그인하는 터미널 세션](/docs/ko/skills#where-synced-skills-load)에서 `~/.claude/skills/synced/`로 다운로드하며, 대화형 또는 비대화형이고 Cowork 및 클라우드 세션입니다. `false`로 설정하여 해당 다운로드를 중지하고 이미 동기화된 스킬 로드를 중지합니다. Claude Code는 `false`만 인정합니다. `true`는 설정되지 않은 것과 같으며 다른 곳에서 꺼진 동기화를 켜지 않습니다.

4572 4575

4573* **범위**: [`사용자, 로컬 또는 관리`](#scopes), 및 `--settings`로 전달된 파일. 저장소는 이를 끌 수 없습니다.4576* **범위**: [`사용자, 로컬 또는 관리됨`](#scopes), 및 `--settings`로 전달된 파일. 저장소는 이를 끌 수 없습니다.

4574* **유형**: 부울4577* **유형**: 부울

4575 * `false`: Claude Code는 동기화된 스킬 다운로드를 중지하고 `~/.claude/skills/synced/`에 있는 스킬 로드를 중지합니다. 사용자 또는 관리 설정에서 `~/.claude/skills/.trash/`로도 이동합니다4578 * `false`: Claude Code는 동기화된 스킬 다운로드를 중지하고 `~/.claude/skills/synced/`에 있는 스킬 로드를 중지합니다. 사용자 또는 관리되는 설정에서 이를 `~/.claude/skills/.trash/`로 이동합니다

4576 * `true`: 설정되지 않은 것과 같습니다4579 * `true`: 설정되지 않은 것과 같습니다

4577* **기본값**: 설정되지 않음, 따라서 claude.ai 계정으로 로그인한 세션은 스킬을 동기화합니다4580* **기본값**: 설정되지 않음, 따라서 claude.ai 계정으로 로그인한 세션은 스킬을 동기화합니다

4578 4581

4588 `syncClaudeAiPlugins`4591 `syncClaudeAiPlugins`

4589</h3>4592</h3>

4590 4593

4591[claude.ai 계정에 대해 활성화된 플러그인](/docs/ko/plugins/loading#synced-plugins)의 다운로드를 끕니다. Claude Code는 claude.ai 계정으로 로그인하는 터미널 세션의 시작 부분에서 `~/.claude/plugins/synced/`로 다운로드하고 Cowork 세션에서도 다운로드하며, 각각을 `<name>@synced`로 로드합니다. `false`로 설정하여 해당 다운로드를 중지하고 이미 동기화된 플러그인 로드를 중지합니다. Claude Code는 `false`만 인정합니다. `true`는 설정되지 않은 것과 같으며 다른 곳에서 꺼진 동기화를 켜지 않습니다. Claude Code v2.1.273 이상이 필요합니다.4594[claude.ai 계정에 대해 활성화된 플러그인](/docs/ko/plugins/loading#synced-plugins)의 다운로드를 끕니다. Claude Code는 claude.ai 계정으로 로그인하는 터미널 세션의 시작 및 Cowork 세션에서 `~/.claude/plugins/synced/`로 다운로드하고 각각을 `<name>@synced`로 로드합니다. `false`로 설정하여 해당 다운로드를 중지하고 이미 동기화된 플러그인 로드를 중지합니다. Claude Code는 `false`만 인정합니다. `true`는 설정되지 않은 것과 같으며 다른 곳에서 꺼진 동기화를 켜지 않습니다. Claude Code v2.1.273 이상이 필요합니다.

4592 4595

4593* **범위**: [`사용자, 로컬 또는 관리`](#scopes), 및 `--settings`로 전달된 파일. 저장소는 이를 끌 수 없습니다.4596* **범위**: [`사용자, 로컬 또는 관리됨`](#scopes), 및 `--settings`로 전달된 파일. 저장소는 이를 끌 수 없습니다.

4594* **유형**: 부울4597* **유형**: 부울

4595 * `false`: Claude Code는 동기화된 플러그인 다운로드를 중지하고 `~/.claude/plugins/synced/`에 있는 플러그인 로드를 중지합니다. 사용자 또는 관리 설정에서 `~/.claude/plugins/.trash/`로도 이동합니다4598 * `false`: Claude Code는 동기화된 플러그인 다운로드를 중지하고 `~/.claude/plugins/synced/`에 있는 플러그인 로드를 중지합니다. 사용자 또는 관리되는 설정에서 이를 `~/.claude/plugins/.trash/`로 이동합니다

4596 * `true`: 설정되지 않은 것과 같습니다4599 * `true`: 설정되지 않은 것과 같습니다

4597* **기본값**: 설정되지 않음, 따라서 claude.ai 계정으로 로그인한 세션은 플러그인을 동기화합니다4600* **기본값**: 설정되지 않음, 따라서 claude.ai 계정으로 로그인한 세션은 플러그인을 동기화합니다

4598 4601

4599모든 동기화된 플러그인이 아닌 하나의 동기화된 플러그인을 끄려면 [`enabledPlugins`](#enabledplugins)에서 `"<name>@synced": false`를 설정합니다.4602모든 동기화된 플러그인이 아닌 하나의 동기화된 플러그인을 끄려면 [`enabledPlugins`](#enabledplugins)에서 `"<name>@synced": false`를 설정하세요.

4600 4603

4601이 예제는 머신이 모든 세션에서 계정의 플러그인을 다운로드하지 않도록 유지합니다:4604이 예제는 머신이 모든 세션에서 계정의 플러그인을 다운로드하지 않도록 유지합니다:

4602 4605

4610 `allowedChannelPlugins`4613 `allowedChannelPlugins`

4611</h3>4614</h3>

4612 4615

4613[채널](/docs/ko/channels) 플러그인이 조직의 세션에 메시지를 푸시할 수 있는 채널을 선택합니다. 이를 설정하면 Claude Code는 기본 Anthropic 허용 목록 대신 목록을 사용합니다. 각 항목은 플러그인과 플러그인이 나오는 마켓플레이스의 이름을 지정합니다.4616[채널](/docs/ko/channels) 플러그인이 조직의 세션에 메시지를 푸시할 수 있는 채널을 선택합니다. 설정하면 Claude Code는 기본 Anthropic 허용 목록 대신 목록을 사용합니다. 각 항목은 플러그인과 이를 제공하는 마켓플레이스의 이름을 지정합니다.

4614 4617

4615* **범위**: [`관리`](#scopes)4618* **범위**: [`관리됨`](#scopes)

4616* **유형**: 각각 `marketplace` 및 `plugin` 문자열을 포함하는 객체의 배열. 항목은 대신 `"telegram@claude-plugins-official"`과 같은 `"plugin@marketplace"` 문자열일 수 있으며, Claude Code는 이를 동등한 객체로 취급합니다. 문자열 형식은 Claude Code v2.1.267 이상이 필요합니다. 이전 버전은 하나를 포함할 때 전체 `allowedChannelPlugins` 값을 거부합니다4619* **유형**: 각각 `marketplace` 및 `plugin` 문자열을 포함하는 객체 배열. 항목은 대신 `"telegram@claude-plugins-official"`과 같은 `"plugin@marketplace"` 문자열일 수 있으며, Claude Code는 이를 동등한 객체로 취급합니다. 문자열 형식은 Claude Code v2.1.267 이상이 필요합니다. 이전 버전은 하나를 포함할 때 전체 `allowedChannelPlugins` 값을 거부합니다

4617* **기본값**: 설정되지 않음, 따라서 Claude Code는 기본 Anthropic 허용 목록을 사용합니다4620* **기본값**: 설정되지 않음, 따라서 Claude Code는 기본 Anthropic 허용 목록을 사용합니다

4618 4621

4619이 예제는 채널을 켜고 공식 Anthropic 마켓플레이스의 Telegram 플러그인만 허용합니다:4622이 예제는 채널을 켜고 공식 Anthropic 마켓플레이스의 Telegram 플러그인만 허용합니다:

4629 4632

4630빈 배열은 모든 채널 플러그인을 차단합니다.4633빈 배열은 모든 채널 플러그인을 차단합니다.

4631 4634

4632이 키는 채널이 계정에 대해 [`channelsEnabled`](#channelsenabled) 게이트를 통과한 후에 적용됩니다. Team 및 Enterprise 플랜에서, 그리고 관리 설정이 있는 Console 계정에서는 `channelsEnabled: true`를 의미합니다. [채널 플러그인 실행 제한](/docs/ko/channels#restrict-which-channel-plugins-can-run)을 참조하십시오.4635이 키는 채널이 계정에 대해 [`channelsEnabled`](#channelsenabled) 게이트를 통과한 후에 적용됩니다. Team 및 Enterprise 플랜에서, 그리고 관리되는 설정이 있는 Console 계정에서는 `channelsEnabled: true`를 의미합니다. [채널 플러그인 실행 제한](/docs/ko/channels#restrict-which-channel-plugins-can-run)을 참조하세요.

4633 4636

4634<h3 id="blockedmarketplaces">4637<h3 id="blockedmarketplaces">

4635 `blockedMarketplaces`4638 `blockedMarketplaces`

4636</h3>4639</h3>

4637 4640

4638조직의 플러그인 마켓플레이스 소스를 차단합니다. Claude Code는 마켓플레이스 추가 및 플러그인 설치, 업데이트, 새로 고침 및 자동 업데이트 시 차단 목록을 확인하므로, 정책을 설정하기 전에 누군가 추가한 마켓플레이스는 플러그인을 가져오는 데 사용될 수 없습니다. 차단된 소스는 다운로드 전에 확인되므로 파일 시스템에 닿지 않습니다.4641조직의 플러그인 마켓플레이스 소스를 차단합니다. Claude Code는 마켓플레이스 추가 및 플러그인 설치, 업데이트, 새로 고침 및 자동 업데이트 시 차단 목록을 확인하므로, 정책을 설정하기 전에 누군가 추가한 마켓플레이스는 플러그인을 가져오는 데 사용할 수 없습니다. 차단된 소스는 다운로드 전에 확인되므로 파일 시스템에 닿지 않습니다.

4639 4642

4640[claude.ai 관리 콘솔](/docs/ko/server-managed-settings)에서 이 키를 설정하면 claude.ai는 조직의 누구든 claude.ai에서 git 저장소의 마켓플레이스를 추가할 때도 적용합니다. [제한 작동 방식](/docs/ko/plugins/org#restrict-what-users-can-install)에서 설명합니다.4643[claude.ai 관리 콘솔](/docs/ko/server-managed-settings)에서 이 키를 설정하면, claude.ai는 조직의 누구든 claude.ai에서 git 저장소의 마켓플레이스를 추가할 때도 적용합니다. [제한 작동 방식](/docs/ko/plugins/org#restrict-what-users-can-install)에서 설명합니다.

4641 4644

4642* **범위**: [`관리`](#scopes)4645* **범위**: [`관리됨`](#scopes)

4643* **유형**: [`strictKnownMarketplaces`](#allowed-source-types)와 동일한 형식의 마켓플레이스 소스 객체 배열4646* **유형**: [`strictKnownMarketplaces`](#allowed-source-types)와 동일한 형식의 마켓플레이스 소스 객체 배열

4644* **기본값**: 설정되지 않음, 따라서 마켓플레이스가 차단되지 않습니다4647* **기본값**: 설정되지 않음, 따라서 마켓플레이스가 차단되지 않습니다

4645 4648

4653}4656}

4654```4657```

4655 4658

4656GitHub 항목은 [소유자 와일드카드 형식](#owner-wildcards) `"owner/*"`을 사용하여 해당 GitHub 소유자 아래의 모든 저장소를 차단할 수 있으며, Claude Code v2.1.223 이상이 필요합니다. `{ "source": "skills-dir" }`을 추가하여 Claude Code가 마켓플레이스를 제한하지 않고 `~/.claude/skills/`에서 [`@skills-dir` 플러그인](/docs/ko/plugins/loading#plugins-shared-through-a-repository)을 로드하지 않도록 합니다. [관리 마켓플레이스 제한](/docs/ko/plugins/org#restrict-what-users-can-install)을 참조하십시오.4659GitHub 항목은 [소유자 와일드카드 형식](#owner-wildcards) `"owner/*"`을 사용하여 해당 GitHub 소유자 아래의 모든 저장소를 차단할 수 있으며, Claude Code v2.1.223 이상이 필요합니다. `{ "source": "skills-dir" }`을 추가하여 Claude Code가 `~/.claude/skills/`에서 [`@skills-dir` 플러그인](/docs/ko/plugins/loading#plugins-shared-through-a-repository)을 로드하지 않도록 하되 마켓플레이스를 제한하지 않습니다. [관리되는 마켓플레이스 제한](/docs/ko/plugins/org#restrict-what-users-can-install)을 참조하세요.

4657 4660

4658<h3 id="channelsenabled">4661<h3 id="channelsenabled">

4659 `channelsEnabled`4662 `channelsEnabled`

4660</h3>4663</h3>

4661 4664

4662조직의 [채널](/docs/ko/channels)을 허용합니다. claude.ai Team 및 Enterprise 플랜에서 Claude Code는 이를 `true`로 설정할 때까지 채널을 차단합니다. API 키로 인증하는 [Anthropic Console](/docs/ko/authentication#claude-console-authentication) 계정의 경우 채널이 기본적으로 허용됩니다. 조직이 관리 설정을 배포하면 Claude Code는 이 키를 `true`로 설정할 때까지 해당 계정의 채널도 차단합니다.4665조직의 [채널](/docs/ko/channels)을 허용합니다. claude.ai Team 및 Enterprise 플랜에서 Claude Code는 이를 `true`로 설정할 때까지 채널을 차단합니다. API 키로 인증하는 [Anthropic Console](/docs/ko/authentication#claude-console-authentication) 계정의 경우 채널이 기본적으로 허용됩니다. 조직이 관리되는 설정을 배포하면 Claude Code는 이 키를 `true`로 설정할 때까지 해당 계정의 채널도 차단합니다.

4663 4666

4664* **범위**: [`관리`](#scopes)4667* **범위**: [`관리됨`](#scopes)

4665* **유형**: 부울4668* **유형**: 부울

4666 * `true`: Claude Code는 조직의 채널을 허용합니다4669 * `true`: Claude Code는 조직의 채널을 허용합니다

4667 * `false`: 설정되지 않은 것과 같습니다. 채널이 차단되는지 여부는 기본값에서 설명하는 대로 플랜에 따라 다릅니다4670 * `false`: 설정되지 않은 것과 같습니다. 채널이 차단되는지 여부는 기본값에서 설명하는 대로 플랜에 따라 다릅니다

4668* **기본값**: 설정되지 않음. 채널은 Team 및 Enterprise 플랜에서 차단되고 관리 설정이 있는 Console 계정에서 차단되며, Pro 및 Max 플랜에서 허용되고 관리 설정이 없는 Console 계정에서 허용됩니다4671* **기본값**: 설정되지 않음. 채널은 Team 및 Enterprise 플랜 및 관리되는 설정이 있는 Console 계정에서 차단되고, Pro 및 Max 플랜 및 관리되는 설정이 없는 Console 계정에서 허용됩니다

4669 4672

4670```json managed-settings.json theme={null}4673```json managed-settings.json theme={null}

4671{4674{

4673}4676}

4674```4677```

4675 4678

4676활성화된 후 플러그인이 채널로 등록할 수 있는 것을 제한하려면 [`allowedChannelPlugins`](#allowedchannelplugins)을 설정합니다. [엔터프라이즈 제어](/docs/ko/channels#enterprise-controls)를 참조하십시오.4679활성화된 후 플러그인이 채널로 등록할 수 있는 것을 제한하려면 [`allowedChannelPlugins`](#allowedchannelplugins)을 설정하세요. [엔터프라이즈 제어](/docs/ko/channels#enterprise-controls)를 참조하세요.

4677 4680

4678<h3 id="disablecommandpluginsources">4681<h3 id="disablecommandpluginsources">

4679 `disableCommandPluginSources`4682 `disableCommandPluginSources`

4680</h3>4683</h3>

4681 4684

4682[`command` 플러그인 소스](/docs/ko/plugins/marketplace-reference#command-plugin-source)를 차단합니다. 이는 사용자의 머신에서 마켓플레이스 선언 명령어를 실행하여 플러그인을 설치합니다. 이를 `true`로 설정하면 Claude Code는 명령어를 실행하지 않으며, 명령어 소스 플러그인을 설치 또는 업데이트하지 않고, 이미 설치된 플러그인 로드를 중지합니다. `false`로 설정하여 명시적으로 허용합니다. 명령어 소스를 차단할 때마다, `true`로 설정하든 [`allowManagedHooksOnly`](#allowmanagedhooksonly) 아래에서 설정되지 않은 상태로 두든, 마켓플레이스 [`headersHelper` 명령어](/docs/ko/plugins/host-marketplace#authenticate-archive-downloads)도 차단합니다. 단, 관리 설정 자체가 선언하는 마켓플레이스는 제외합니다. Claude Code v2.1.229 이상이 필요하며, `headersHelper` 차단은 v2.1.238 이상이 필요합니다.4685[`command` 플러그인 소스](/docs/ko/plugins/marketplace-reference#command-plugin-source)를 차단합니다. 이는 마켓플레이스에서 선언한 명령어를 사용자의 머신에서 실행하여 플러그인을 설치합니다. `true`로 설정하면 Claude Code는 명령어를 실행하지 않고, 명령어 소스 플러그인을 설치 또는 업데이트하지 않으며, 이미 설치된 플러그인 로드를 중지합니다. `false`로 설정하여 명시적으로 허용합니다. 명령어 소스를 차단할 때마다, `true`로 설정하든 [`allowManagedHooksOnly`](#allowmanagedhooksonly) 아래에서 설정되지 않은 상태로 두든, 마켓플레이스 [`headersHelper` 명령어](/docs/ko/plugins/host-marketplace#authenticate-archive-downloads)도 차단합니다. 단, 관리되는 설정 자체가 선언하는 마켓플레이스는 제외합니다. Claude Code v2.1.229 이상이 필요하며, `headersHelper` 차단은 v2.1.238 이상이 필요합니다.

4683 4686

4684* **범위**: [`관리`](#scopes)4687* **범위**: [`관리됨`](#scopes)

4685* **유형**: 부울4688* **유형**: 부울

4686 * `true`: Claude Code는 마켓플레이스 선언 명령어를 실행하지 않으며, 명령어 소스 플러그인을 설치 또는 업데이트하지 않고, 이미 설치된 플러그인 로드를 중지합니다4689 * `true`: Claude Code는 마켓플레이스에서 선언한 명령어를 실행하지 않고, 명령어 소스 플러그인을 설치 또는 업데이트하지 않으며, 이미 설치된 플러그인 로드를 중지합니다

4687 * `false`: Claude Code는 명령어 소스 플러그인을 명시적으로 허용합니다4690 * `false`: Claude Code는 명령어 소스 플러그인을 명시적으로 허용합니다

4688* **기본값**: 설정되지 않음, 따라서 Claude Code는 [`allowManagedHooksOnly`](#allowmanagedhooksonly)를 따릅니다. 훅 실행을 관리 설정으로 제한하는 조직은 명령어 소스도 비활성화됩니다4691* **기본값**: 설정되지 않음, 따라서 Claude Code는 [`allowManagedHooksOnly`](#allowmanagedhooksonly)를 따릅니다. 훅 실행을 관리되는 설정으로 제한하는 조직은 명령어 소스도 비활성화됩니다

4689 4692

4690```json managed-settings.json theme={null}4693```json managed-settings.json theme={null}

4691{4694{

4699 `pluginSuggestionMarketplaces`4702 `pluginSuggestionMarketplaces`

4700</h3>4703</h3>

4701 4704

4702스피너 팁 및 `/plugin` **Discover** 탭 상단에 고정된 상황별 설치 제안으로 나타날 수 있는 플러그인의 마켓플레이스 이름을 지정합니다. 기본 제공 자사 프론트엔드 설계 팁은 영향을 받지 않습니다. 제안은 각 플러그인의 마켓플레이스 항목의 `relevance` 선언에서 나옵니다.4705스피너 팁 및 `/plugin` **검색** 탭 상단에 고정된 상황별 설치 제안으로 나타날 수 있는 플러그인의 마켓플레이스 이름을 지정합니다. 기본 제공 자사 프론트엔드 설계 팁은 영향을 받지 않습니다. 제안은 마켓플레이스 항목의 각 플러그인의 `relevance` 선언에서 나옵니다.

4703 4706

4704* **범위**: [`관리`](#scopes)4707* **범위**: [`관리됨`](#scopes)

4705* **유형**: 마켓플레이스 이름의 배열4708* **유형**: 마켓플레이스 이름 배열

4706* **기본값**: 설정되지 않음, 따라서 마켓플레이스 선언 제안이 표시되지 않습니다4709* **기본값**: 설정되지 않음, 따라서 마켓플레이스에서 선언한 제안이 표시되지 않습니다

4707 4710

4708```json managed-settings.json theme={null}4711```json managed-settings.json theme={null}

4709{4712{

4711}4714}

4712```4715```

4713 4716

4714이름은 마켓플레이스가 머신에 등록되고 등록된 소스가 동일한 관리 설정에서도 선언될 때만 적용됩니다. 해당 이름의 [`extraKnownMarketplaces`](#extraknownmarketplaces) 항목 또는 [`strictKnownMarketplaces`](#strictknownmarketplaces)의 항목으로 선언됩니다. Claude Code는 허용 목록 이름 아래에서 다른 소스에서 등록된 마켓플레이스를 무시합니다. 공식 마켓플레이스는 소스 요구 사항에서 제외됩니다. 공식 Anthropic 소스에서만 등록할 수 있으므로 이름만 허용 목록에 추가하면 충분합니다. [컨텍스트별 플러그인 제안](/docs/ko/plugins/relevance)을 참조하십시오.4717이름은 마켓플레이스가 머신에 등록되고 등록된 소스가 동일한 관리되는 설정에서도 선언될 때만 적용됩니다. 해당 이름의 [`extraKnownMarketplaces`](#extraknownmarketplaces) 항목 또는 [`strictKnownMarketplaces`](#strictknownmarketplaces)의 항목으로 선언됩니다. Claude Code는 허용 목록에 있는 이름 아래에서 다른 소스에서 등록된 마켓플레이스를 무시합니다. 공식 마켓플레이스는 소스 요구 사항에서 제외됩니다. 공식 Anthropic 소스에서만 등록할 수 있으므로 이름만 허용 목록에 추가하면 충분합니다. [컨텍스트별 플러그인 제안](/docs/ko/plugins/relevance)을 참조하세요.

4715 4718

4716<h3 id="plugintrustmessage">4719<h3 id="plugintrustmessage">

4717 `pluginTrustMessage`4720 `pluginTrustMessage`

4719 4722

4720설치 전에 Claude Code가 표시하는 플러그인 신뢰 경고에 조직의 자체 텍스트를 추가합니다. 예를 들어 내부 마켓플레이스의 플러그인이 검증되었음을 확인합니다.4723설치 전에 Claude Code가 표시하는 플러그인 신뢰 경고에 조직의 자체 텍스트를 추가합니다. 예를 들어 내부 마켓플레이스의 플러그인이 검증되었음을 확인합니다.

4721 4724

4722* **범위**: [`관리`](#scopes)4725* **범위**: [`관리됨`](#scopes)

4723* **유형**: 문자열4726* **유형**: 문자열

4724* **기본값**: 설정되지 않음, 따라서 Claude Code는 표준 경고만 표시합니다4727* **기본값**: 설정되지 않음, 따라서 Claude Code는 표준 경고만 표시합니다

4725 4728

4733 `strictKnownMarketplaces`4736 `strictKnownMarketplaces`

4734</h3>4737</h3>

4735 4738

4736조직의 사람들이 추가하고 플러그인을 설치할 수 있는 플러그인 마켓플레이스 소스를 제한합니다. Claude Code는 마켓플레이스 추가 및 플러그인 설치, 업데이트, 새로 고침 및 자동 업데이트 시 허용 목록을 적용하며, 모든 네트워크 또는 파일 시스템 작업 전에 적용하므로, 정책을 설정하기 전에 누군가 추가한 마켓플레이스는 소스가 더 이상 일치하지 않으면 플러그인을 가져오는 데 사용될 수 없습니다. 차단된 사용자는 관리 정책의 이름을 지정하는 오류를 봅니다.4739조직의 사람들이 추가하고 플러그인을 설치할 수 있는 플러그인 마켓플레이스 소스를 제한합니다. Claude Code는 마켓플레이스 추가 및 플러그인 설치, 업데이트, 새로 고침 및 자동 업데이트 시 허용 목록을 적용하며, 모든 네트워크 또는 파일 시스템 작업 전에 수행하므로, 정책을 설정하기 전에 누군가 추가한 마켓플레이스는 소스가 더 이상 일치하지 않으면 플러그인을 가져오는 데 사용할 수 없습니다. 차단된 사용자는 관리되는 정책의 이름을 지정하는 오류를 봅니다.

4737 4740

4738[claude.ai 관리 콘솔](/docs/ko/server-managed-settings)에서 이 키를 설정하면 claude.ai는 조직의 누구든 claude.ai에서 git 저장소의 마켓플레이스를 추가할 때도 적용합니다. [제한 작동 방식](/docs/ko/plugins/org#restrict-what-users-can-install)에서 설명합니다.4741[claude.ai 관리 콘솔](/docs/ko/server-managed-settings)에서 이 키를 설정하면, claude.ai는 조직의 누구든 claude.ai에서 git 저장소의 마켓플레이스를 추가할 때도 적용합니다. [제한 작동 방식](/docs/ko/plugins/org#restrict-what-users-can-install)에서 설명합니다.

4739 4742

4740* **범위**: [`관리`](#scopes)4743* **범위**: [`관리됨`](#scopes)

4741* **유형**: 마켓플레이스 소스 객체의 배열. [허용된 소스 유형](#allowed-source-types)을 참조하십시오4744* **유형**: 마켓플레이스 소스 객체 배열. [허용된 소스 유형](#allowed-source-types)을 참조하세요

4742* **기본값**: 설정되지 않음, 따라서 사용자는 모든 마켓플레이스를 추가할 수 있습니다. 빈 배열은 공식 Anthropic 마켓플레이스를 포함한 모든 마켓플레이스 소스를 차단하는 완전한 잠금입니다4745* **기본값**: 설정되지 않음, 따라서 사용자는 모든 마켓플레이스를 추가할 수 있습니다. 빈 배열은 공식 Anthropic 마켓플레이스를 포함한 모든 마켓플레이스 소스를 차단하는 완전한 잠금입니다

4743 4746

4744이 예제는 두 개의 GitHub 저장소를 허용합니다. 하나는 `v2.0` ref에 고정되고 하나는 호스팅된 `marketplace.json` URL입니다:4747이 예제는 두 개의 GitHub 저장소를 허용합니다. 하나는 `v2.0` ref에 고정되고 하나는 호스팅된 `marketplace.json` URL입니다:

4753}4756}

4754```4757```

4755 4758

4756이 키를 `allowedMarketplaces`로도 쓸 수 있습니다. [마켓플레이스 키 별칭](#marketplace-key-aliases)에서 Claude Code가 별칭을 어떻게 취급하는지 및 어느 버전이 이를 수용하는지 설명합니다. 이 키는 정책 게이트입니다. 사용자가 추가할 수 있는 것을 제어하지만 아무것도 등록하지 않습니다. 제한 및 사전 등록을 한 파일에서 수행하려면 [`extraKnownMarketplaces`와 결합](#combine-with-extraknownmarketplaces)을 참조하십시오. 사용자 대면 보기는 [관리 마켓플레이스 제한](/docs/ko/plugins/org#restrict-what-users-can-install)을 참조하십시오.4759이 키를 `allowedMarketplaces`로도 쓸 수 있습니다. [마켓플레이스 키 별칭](#marketplace-key-aliases)은 Claude Code가 별칭을 어떻게 취급하는지 및 어느 버전이 이를 수용하는지 설명합니다. 이 키는 정책 게이트입니다. 사용자가 추가할 수 있는 것을 제어하지만 아무것도 등록하지 않습니다. 제한 및 사전 등록을 한 파일에서 수행하려면 [`extraKnownMarketplaces`와 결합](#combine-with-extraknownmarketplaces)을 참조하세요. 사용자 대면 보기는 [관리되는 마켓플레이스 제한](/docs/ko/plugins/org#restrict-what-users-can-install)을 참조하세요.

4757 4760

4758<h4 id="allowed-source-types">4761<h4 id="allowed-source-types">

4759 허용된 소스 유형4762 허용된 소스 유형

4768| `url` | `{ "source": "url", "url": "https://plugins.example.com/marketplace.json", "headers": { "Authorization": "Bearer ${TOKEN}" } }` | `url` 필수; `headers`는 인증된 액세스를 위해 HTTP 헤더를 추가합니다 |4771| `url` | `{ "source": "url", "url": "https://plugins.example.com/marketplace.json", "headers": { "Authorization": "Bearer ${TOKEN}" } }` | `url` 필수; `headers`는 인증된 액세스를 위해 HTTP 헤더를 추가합니다 |

4769| `file` | `{ "source": "file", "path": "/opt/acme-corp/plugins/marketplace.json" }` | `path` 필수, `marketplace.json` 파일의 절대 경로 |4772| `file` | `{ "source": "file", "path": "/opt/acme-corp/plugins/marketplace.json" }` | `path` 필수, `marketplace.json` 파일의 절대 경로 |

4770| `directory` | `{ "source": "directory", "path": "/opt/acme-corp/approved-marketplaces" }` | `path` 필수, `.claude-plugin/marketplace.json`을 포함하는 디렉터리의 절대 경로 |4773| `directory` | `{ "source": "directory", "path": "/opt/acme-corp/approved-marketplaces" }` | `path` 필수, `.claude-plugin/marketplace.json`을 포함하는 디렉터리의 절대 경로 |

4771| `hostPattern` | `{ "source": "hostPattern", "hostPattern": "^github\\.example\\.com$" }` | `hostPattern` 필수, 마켓플레이스 호스트의 어디든 일치하는 정규식. `^` 및 `$`로 고정하여 전체 호스트를 일치시킵니다 |4774| `hostPattern` | `{ "source": "hostPattern", "hostPattern": "^github\\.example\\.com$" }` | `hostPattern` 필수, 마켓플레이스 호스트의 어디든 일치하는 정규식. `^` 및 `$`로 앵커하여 전체 호스트를 일치시킵니다 |

4772| `pathPattern` | `{ "source": "pathPattern", "pathPattern": "^/opt/approved/" }` | `pathPattern` 필수, `file` 및 `directory` 소스의 `path`의 어디든 일치하는 정규식. 접두사를 고정하려면 `^`로 시작합니다 |4775| `pathPattern` | `{ "source": "pathPattern", "pathPattern": "^/opt/approved/" }` | `pathPattern` 필수, `file` 및 `directory` 소스의 `path`의 어디든 일치하는 정규식. `^`로 시작하여 접두사를 고정합니다 |

4773| `skills-dir` | `{ "source": "skills-dir" }` | 필드 없음. `~/.claude/skills/` 플러그인 스캔을 다시 옵트인합니다 |4776| `skills-dir` | `{ "source": "skills-dir" }` | 필드 없음. `~/.claude/skills/` 플러그인 스캔을 다시 옵트인합니다 |

4774 4777

4775세 가지 소스 유형은 표 이상의 규칙을 포함합니다:4778세 가지 소스 유형은 표 이상의 규칙을 수행합니다:

4776 4779

4777* **`url`**: URL 마켓플레이스는 `marketplace.json` 파일만 다운로드하고, Claude Code는 해당 서버에서 상대 경로로 플러그인 파일을 가져오지 않으므로, 플러그인은 상대 경로 이외의 [플러그인 소스](/docs/ko/plugins/marketplace-reference#plugin-sources)(예: 아카이브 URL, 동일한 호스트에 있을 수 있음)를 사용해야 합니다. 상대 경로가 있는 플러그인의 경우 Git 기반 마켓플레이스를 대신 사용합니다. [URL 기반 마켓플레이스에서 상대 경로가 있는 플러그인이 실패합니다](/docs/ko/plugins/troubleshooting#plugins-with-relative-paths-fail-in-url-based-marketplaces)를 참조하십시오.4780* **`url`**: URL 마켓플레이스는 `marketplace.json` 파일만 다운로드하고, Claude Code는 해당 서버에서 상대 경로로 플러그인 파일을 가져오지 않으므로, 플러그인은 상대 경로 이외의 [플러그인 소스](/docs/ko/plugins/marketplace-reference#plugin-sources)(예: 아카이브 URL, 동일한 호스트에 있을 수 있음)를 사용해야 합니다. 상대 경로가 있는 플러그인의 경우 Git 기반 마켓플레이스를 대신 사용하세요. [URL 기반 마켓플레이스에서 상대 경로가 있는 플러그인이 실패합니다](/docs/ko/plugins/troubleshooting#plugins-with-relative-paths-fail-in-url-based-marketplaces)를 참조하세요.

4778* **`hostPattern`**: 각 저장소를 나열하지 않고 내부 GitHub Enterprise 또는 GitLab 서버의 모든 마켓플레이스를 허용하는 데 사용합니다. Claude Code는 `github` 소스를 `github.com`과 비교하고, `url` 소스에서 호스트 이름을 가져오며, [git URL](https://git-scm.com/docs/git-clone#_git_urls)의 형식에 따라 `git` 소스에서 가져옵니다:4781* **`hostPattern`**: 각 저장소를 나열하지 않고 내부 GitHub Enterprise 또는 GitLab 서버의 모든 마켓플레이스를 허용하는 데 사용합니다. Claude Code는 `github` 소스를 `github.com`과 비교하고, `url` 소스에서 호스트 이름을 가져오고, [git URL](https://git-scm.com/docs/git-clone#_git_urls)의 형식에 따라 `git` 소스에서 가져옵니다:

4779 4782

4780 * `https://` 또는 `ssh://`와 같은 스키마가 있는 URL: URL의 호스트 이름.4783 * `https://` 또는 `ssh://`와 같은 스키마가 있는 URL: URL의 호스트 이름.

4781 * 스키마 없는 SSH 주소, git의 `user@host:path` 형식(예: `git@git.example.com:tools/plugins.git`): `@`와 `:` 사이의 호스트, 이는 git이 연결하는 호스트입니다.4784 * 스키마 없는 SSH 주소, git의 `user@host:path` 형식(예: `git@git.example.com:tools/plugins.git`): `@`와 `:` 사이의 호스트, 이는 git이 연결하는 호스트입니다.

4790 소유자 와일드카드4793 소유자 와일드카드

4791</h4>4794</h4>

4792 4795

4793GitHub 소유자 아래의 모든 저장소와 일치하는 `repo` 값이 `"<owner>/*"`인 `github` 항목입니다. 소유자 와일드카드는 Claude Code v2.1.223 이상이 필요하며 `strictKnownMarketplaces` 및 `blockedMarketplaces`에서만 작동합니다. `github` 소스가 나타나는 다른 곳(예: `extraKnownMarketplaces` 또는 `/plugin marketplace add`)에서는 `repo` 값이 단일 저장소의 이름을 지정해야 합니다. v2.1.223 이전에는 Claude Code가 항목을 문자 그대로 비교했으므로 허용 목록 항목이 저장소와 일치하지 않았고 차단 목록 항목이 아무것도 차단하지 않았습니다. 단일 저장소 항목은 모든 버전에서 적용됩니다.4796GitHub 항목의 `repo` 값이 `"<owner>/*"`인 경우 해당 GitHub 소유자 아래의 모든 저장소와 일치합니다. 소유자 와일드카드는 Claude Code v2.1.223 이상이 필요하며 `strictKnownMarketplaces` 및 `blockedMarketplaces`에서만 작동합니다. `github` 소스가 나타나는 다른 곳(예: `extraKnownMarketplaces` 또는 `/plugin marketplace add`)에서는 `repo` 값이 단일 저장소의 이름을 지정해야 합니다. v2.1.223 이전에는 Claude Code가 항목을 문자 그대로 비교했으므로 허용 목록 항목이 저장소와 일치하지 않았고 차단 목록 항목이 아무것도 차단하지 않았습니다. 단일 저장소 항목은 모든 버전에서 적용됩니다.

4794 4797

4795이 항목은 `acme-corp` 조직의 모든 마켓플레이스 저장소를 허용합니다:4798이 항목은 `acme-corp` 조직의 모든 마켓플레이스 저장소를 허용합니다:

4796 4799

4802}4805}

4803```4806```

4804 4807

4805전체 저장소 이름 위치만 와일드카드일 수 있습니다. Claude Code는 `*`, `*/plugins` 또는 `acme-corp/tools-*`와 같은 항목을 유효하지 않은 것으로 무시하므로 저장소와 일치하지 않습니다.4808저장소 이름 위치만 와일드카드일 수 있습니다. Claude Code는 `*`, `*/plugins`, 또는 `acme-corp/tools-*`와 같은 항목을 유효하지 않은 것으로 무시하므로 저장소와 일치하지 않습니다.

4806 4809

4807일치 규칙은 두 설정 간에 다릅니다:4810일치 규칙은 두 설정 간에 다릅니다:

4808 4811

4813| `ref` | 정확한 항목 규칙을 따릅니다. `ref`가 있는 항목은 정확한 ref가 있는 소스와만 일치하고, 없는 항목은 ref를 지정하지 않는 소스와만 일치합니다 | `ref`가 없는 항목은 일치하는 저장소의 모든 ref를 차단합니다 |4816| `ref` | 정확한 항목 규칙을 따릅니다. `ref`가 있는 항목은 정확한 ref가 있는 소스와만 일치하고, 없는 항목은 ref를 지정하지 않는 소스와만 일치합니다 | `ref`가 없는 항목은 일치하는 저장소의 모든 ref를 차단합니다 |

4815 4818

4816<h4 id="exact-matching">4819<h4 id="exact-matching">

4817 정확한 일치4820 정확한 일치

4832 공식 마켓플레이스만 허용4835 공식 마켓플레이스만 허용

4833</h4>4836</h4>

4834 4837

4835공식 Anthropic 마켓플레이스만 허용하고 다른 것은 허용하지 않으려면 해당 저장소를 나열합니다:4838공식 Anthropic 마켓플레이스만 허용하고 다른 것은 허용하지 않으려면 해당 저장소를 나열하세요:

4836 4839

4837```json managed-settings.json theme={null}4840```json managed-settings.json theme={null}

4838{4841{

4842}4845}

4843```4846```

4844 4847

4845이 항목을 사용하면 Claude Code는 이미 등록된 공식 마켓플레이스를 사용 가능하게 유지하고, 새 머신에서 대화형 터미널 세션을 처음 시작할 때 마켓플레이스를 자동으로 등록합니다. 자동 등록은 가장 일반적으로 다음을 놓칩니다:4848이 항목을 사용하면 Claude Code는 이미 등록된 공식 마켓플레이스를 사용 가능하게 유지하고, 새 머신에서는 대화형 터미널 세션을 처음 시작할 때 마켓플레이스를 자동으로 등록합니다. 자동 등록은 일반적으로 다음을 놓칩니다:

4846 4849

4847* 머신의 첫 번째 대화형 터미널 세션 전에 실행되는 비대화형 환경.4850* 머신의 첫 번째 대화형 터미널 세션 전에 실행되는 비대화형 환경.

4848* Claude Code가 VS Code 확장을 통해서만 실행된 머신.4851* Claude Code가 VS Code 확장을 통해서만 실행된 머신.

4849* Claude Code가 이미 마켓플레이스를 차단한 정책(예: 빈 배열 잠금) 아래에서 대화형 터미널 세션을 실행한 머신. Claude Code는 차단된 시도를 기록하고 정책이 변경된 후 다시 시도하지 않습니다.4852* Claude Code가 이미 빈 배열 잠금과 같이 마켓플레이스를 차단한 정책 아래에서 대화형 터미널 세션을 실행한 머신. Claude Code는 차단된 시도를 기록하고 정책이 변경된 후 다시 시도하지 않습니다.

4850 4853

4851이러한 머신에서는 동일한 `managed-settings.json`의 [`extraKnownMarketplaces`](#extraknownmarketplaces)에 마켓플레이스를 추가하여 Claude Code가 자동으로 등록하도록 하거나 `claude plugin marketplace add anthropics/claude-plugins-official`을 실행합니다.4854이러한 머신에서는 동일한 `managed-settings.json`의 [`extraKnownMarketplaces`](#extraknownmarketplaces)에 마켓플레이스를 추가하여 Claude Code가 자동으로 등록하도록 하거나 `claude plugin marketplace add anthropics/claude-plugins-official`을 실행하세요.

4852 4855

4853<h4 id="combine-with-extraknownmarketplaces">4856<h4 id="combine-with-extraknownmarketplaces">

4854 `extraKnownMarketplaces`와 결합4857 `extraKnownMarketplaces`와 결합

4859| 측면 | `strictKnownMarketplaces` | `extraKnownMarketplaces` |4862| 측면 | `strictKnownMarketplaces` | `extraKnownMarketplaces` |

4860| - | - | - |4863| - | - | - |

4861| 목적 | 조직 정책 적용 | 팀 편의 |4864| 목적 | 조직 정책 적용 | 팀 편의 |

4863| 동작 | 허용 목록에 없는 추가 차단 | 누락된 마켓플레이스 등록 |4866| 동작 | 허용 목록에 없는 추가 차단 | 누락된 마켓플레이스 등록 |

4867 4870

4868마켓플레이스를 제한하고 모든 사용자에 대해 사전 등록하려면 `managed-settings.json`에서 둘 다 설정합니다:4871모든 사용자에 대해 마켓플레이스를 제한하고 사전 등록하려면 `managed-settings.json`에서 둘 다 설정하세요:

4869 4872

4870```json managed-settings.json theme={null}4873```json managed-settings.json theme={null}

4871{4874{

4880}4883}

4881```4884```

4882 4885

4883`strictKnownMarketplaces`만 설정하면 사용자는 여전히 `/plugin marketplace add`로 허용된 마켓플레이스를 직접 추가할 수 있습니다. 공식 Anthropic 마켓플레이스는 Claude Code가 자동으로 등록하는 유일한 마켓플레이스이며, 허용 목록이 이를 허용할 때만 등록합니다. [공식 마켓플레이스만 허용](#allow-only-the-official-marketplace)은 놓치는 머신을 나열합니다.4886`strictKnownMarketplaces`만 설정하면 사용자는 여전히 `/plugin marketplace add`로 허용된 마켓플레이스를 추가할 수 있습니다. 공식 Anthropic 마켓플레이스는 Claude Code가 자동으로 등록하는 유일한 마켓플레이스이며, 허용 목록이 이를 허용할 때만 등록합니다. [공식 마켓플레이스만 허용](#allow-only-the-official-marketplace)은 놓치는 머신을 나열합니다.

4884 4887

4885<h3 id="strictpluginonlycustomization">4888<h3 id="strictpluginonlycustomization">

4886 `strictPluginOnlyCustomization`4889 `strictPluginOnlyCustomization`

4887</h3>4890</h3>

4888 4891

4889사용자 및 프로젝트 소스의 스킬, 에이전트, 훅 및 MCP 서버를 차단하여 플러그인 또는 관리 설정에서만 올 수 있도록 합니다. [`strictKnownMarketplaces`](#strictknownmarketplaces)와 결합하여 전체 사용자 정의 공급 체인을 제어합니다. 마켓플레이스 허용 목록은 사용자가 설치할 수 있는 플러그인을 제어합니다.4892사용자 및 프로젝트 소스의 스킬, 에이전트, 훅 및 MCP 서버를 차단하여 플러그인 또는 관리되는 설정에서만 올 수 있도록 합니다. [`strictKnownMarketplaces`](#strictknownmarketplaces)와 결합하여 전체 사용자 정의 공급 체인을 제어합니다. 마켓플레이스 허용 목록은 사용자가 설치할 수 있는 플러그인을 제어합니다.

4890 4893

4891* **범위**: [`관리`](#scopes)4894* **범위**: [`관리됨`](#scopes)

4892* **유형**: 모든 네 가지 사용자 정의를 잠그려면 `true`, 또는 `"skills"`, `"agents"`, `"hooks"`, `"mcp"`에서 잠글 종류의 이름을 지정하는 배열4895* **유형**: 모든 네 가지 사용자 정의를 잠그려면 `true`, 또는 `"skills"`, `"agents"`, `"hooks"`, `"mcp"`에서 잠글 종류의 이름을 지정하는 배열

4893* **기본값**: 설정되지 않음, 따라서 아무것도 잠기지 않습니다4896* **기본값**: 설정되지 않음, 따라서 아무것도 잠기지 않습니다

4894 4897

4906 `strictPluginOnlyCustomization.skills`4909 `strictPluginOnlyCustomization.skills`

4907</h3>4910</h3>

4908 4911

4909`skills` 표면을 잠급니다. Claude Code는 `~/.claude/skills/` 및 `.claude/skills/`의 스킬, `~/.claude/commands/` 및 `.claude/commands/`의 사용자 정의 명령어, `--add-dir` 디렉터리의 스킬, claude.ai 계정에서 동기화된 스킬 로드를 중지하고, 플러그인 스킬, 번들 스킬, 관리 정책 디렉터리의 스킬 로드를 계속합니다.4912`skills` 표면을 잠급니다. Claude Code는 `~/.claude/skills/` 및 `.claude/skills/`의 스킬, `~/.claude/commands/` 및 `.claude/commands/`의 사용자 정의 명령어, `--add-dir` 디렉터리 아래의 스킬 및 명령어, claude.ai 계정에서 동기화된 스킬 로드를 중지합니다. 플러그인 스킬, 번들 스킬, 관리되는 정책 디렉터리의 스킬은 계속 로드합니다.

4910 4913

4911* **범위**: [`관리`](#scopes)4914* **범위**: [`관리됨`](#scopes)

4912* **유형**: [`strictPluginOnlyCustomization`](#strictpluginonlycustomization) 배열의 문자열 `"skills"`4915* **유형**: [`strictPluginOnlyCustomization`](#strictpluginonlycustomization) 배열의 문자열 `"skills"`

4913* **기본값**: 잠기지 않음4916* **기본값**: 잠기지 않음

4914 4917

4922 `strictPluginOnlyCustomization.agents`4925 `strictPluginOnlyCustomization.agents`

4923</h3>4926</h3>

4924 4927

4925`agents` 표면을 잠급니다. Claude Code는 `~/.claude/agents/` 및 `.claude/agents/`의 에이전트 로드를 중지하고, 플러그인 에이전트, 기본 제공 에이전트, 관리 정책 디렉터리의 에이전트 로드를 계속합니다.4928`agents` 표면을 잠급니다. Claude Code는 `~/.claude/agents/`, `.claude/agents/`, `--add-dir` 디렉터리의 에이전트 로드를 중지합니다. 플러그인 에이전트, 기본 제공 에이전트, 관리되는 정책 디렉터리의 에이전트는 계속 로드합니다.

4926 4929

4927* **범위**: [`관리`](#scopes)4930* **범위**: [`관리됨`](#scopes)

4928* **유형**: [`strictPluginOnlyCustomization`](#strictpluginonlycustomization) 배열의 문자열 `"agents"`4931* **유형**: [`strictPluginOnlyCustomization`](#strictpluginonlycustomization) 배열의 문자열 `"agents"`

4929* **기본값**: 잠기지 않음4932* **기본값**: 잠기지 않음

4930 4933

4938 `strictPluginOnlyCustomization.hooks`4941 `strictPluginOnlyCustomization.hooks`

4939</h3>4942</h3>

4940 4943

4941`hooks` 표면을 잠급니다. Claude Code는 사용자, 프로젝트 및 로컬 `settings.json`의 훅 실행을 중지하고, 플러그인 훅 및 관리 설정의 훅 실행을 계속합니다.4944`hooks` 표면을 잠급니다. Claude Code는 사용자, 프로젝트, 로컬 `settings.json`의 훅 실행을 중지하고 플러그인 훅 및 관리되는 설정의 훅은 계속 실행합니다.

4942 4945

4943* **범위**: [`관리`](#scopes)4946* **범위**: [`관리됨`](#scopes)

4944* **유형**: [`strictPluginOnlyCustomization`](#strictpluginonlycustomization) 배열의 문자열 `"hooks"`4947* **유형**: [`strictPluginOnlyCustomization`](#strictpluginonlycustomization) 배열의 문자열 `"hooks"`

4945* **기본값**: 잠기지 않음4948* **기본값**: 잠기지 않음

4946 4949

4954 `strictPluginOnlyCustomization.mcp`4957 `strictPluginOnlyCustomization.mcp`

4955</h3>4958</h3>

4956 4959

4957`mcp` 표면을 잠급니다. Claude Code는 `~/.claude.json` 및 `.mcp.json`의 MCP 서버 로드를 중지하고, 플러그인 MCP 서버, [`managed-mcp.json`](/docs/ko/managed-mcp) 서버, [`managedMcpServers`](#managedmcpservers)의 서버 로드를 계속합니다.4960`mcp` 표면을 잠급니다. Claude Code는 `~/.claude.json` 및 `.mcp.json`의 MCP 서버 로드를 중지하고 플러그인 MCP 서버, [`managed-mcp.json`](/docs/ko/managed-mcp) 서버, [`managedMcpServers`](#managedmcpservers)의 서버는 계속 로드합니다.

4958 4961

4959* **범위**: [`관리`](#scopes)4962* **범위**: [`관리됨`](#scopes)

4960* **유형**: [`strictPluginOnlyCustomization`](#strictpluginonlycustomization) 배열의 문자열 `"mcp"`4963* **유형**: [`strictPluginOnlyCustomization`](#strictpluginonlycustomization) 배열의 문자열 `"mcp"`

4961* **기본값**: 잠기지 않음4964* **기본값**: 잠기지 않음

4962 4965

4970 `enabledPlugins`4973 `enabledPlugins`

4971</h3>4974</h3>

4972 4975

4973`plugin-name@marketplace-name`으로 키가 지정된 개별 [플러그인](/docs/ko/plugins/overview)을 켜거나 끕니다. 모든 범위에서 항목이 없는 플러그인은 [`defaultEnabled`](/docs/ko/plugins/manifest-reference#fields) 값으로 폴백합니다. `/plugin` 또는 `claude plugin enable`로 플러그인을 활성화 또는 비활성화하면 Claude Code가 이 키를 작성합니다.4976`plugin-name@marketplace-name`으로 키가 지정된 개별 [플러그인](/docs/ko/plugins/overview)을 켜거나 끕니다. 모든 범위에서 항목이 없는 플러그인은 [`defaultEnabled`](/docs/ko/plugins/manifest-reference#fields) 값으로 폴백합니다. `/plugin` 또는 `claude plugin enable`으로 플러그인을 활성화 또는 비활성화하면 Claude Code가 이 키를 작성합니다.

4974 4977

4975* **범위**: [`모든 파일`](#scopes)4978* **범위**: [`모든 파일`](#scopes)

4976* **유형**: `plugin-name@marketplace-name`을 부울에 매핑하는 객체4979* **유형**: `plugin-name@marketplace-name`을 부울에 매핑하는 객체

4993* **사용자 설정**: 개인 플러그인 기본 설정4996* **사용자 설정**: 개인 플러그인 기본 설정

4994* **프로젝트 설정**: 저장소의 모든 사람과 공유되는 플러그인4997* **프로젝트 설정**: 저장소의 모든 사람과 공유되는 플러그인

4995* **로컬 설정**: 머신별 재정의, Claude Code가 설정을 저장할 때 gitignored4998* **로컬 설정**: 머신별 재정의, Claude Code가 설정을 저장할 때 gitignored

4996* **관리 설정**: 조직 전체 정책. `false`로 설정된 플러그인은 모든 범위에서 설치가 차단되고 마켓플레이스에서 숨겨집니다4999* **관리되는 설정**: 조직 전체 정책. `false`로 설정된 플러그인은 모든 범위에서 설치가 차단되고 마켓플레이스에서 숨겨집니다

4997 5000

4998프로젝트 설정은 사용자 설정보다 우선하므로 `~/.claude/settings.json`에서 플러그인을 `false`로 설정해도 프로젝트의 `.claude/settings.json`이 활성화하는 플러그인은 비활성화되지 않습니다. 머신에서 프로젝트 활성화 플러그인을 거부하려면 대신 `.claude/settings.local.json`에서 `false`로 설정합니다. 관리 설정으로 강제 활성화된 플러그인은 관리 설정이 로컬 설정을 재정의하므로 이 방식으로 비활성화될 수 없습니다.5001프로젝트 설정은 사용자 설정보다 우선하므로 `~/.claude/settings.json`에서 플러그인을 `false`로 설정해도 프로젝트의 `.claude/settings.json`이 활성화하는 플러그인은 비활성화되지 않습니다. 프로젝트 활성화 플러그인을 머신에서 옵트아웃하려면 대신 `.claude/settings.local.json`에서 `false`로 설정하세요. 관리되는 설정으로 강제 활성화된 플러그인은 관리되는 설정이 로컬 설정을 재정의하므로 이 방식으로 비활성화될 수 없습니다.

4999 5002

5000프로젝트의 `.claude/settings.json`에서 GitHub 저장소 또는 npm 패키지와 같은 외부 소스의 플러그인을 활성화해도 다른 사람을 위해 설치되지 않습니다. 플러그인을 로드하는 모든 경로에서 Claude Code는 각 사용자가 [직접 설치할 때까지](/docs/ko/plugins/org#require-plugins-per-repository) 플러그인이 설치되지 않은 것으로 보고합니다.5003프로젝트의 `.claude/settings.json`에서 GitHub 저장소 또는 npm 패키지와 같은 외부 소스의 플러그인을 활성화해도 다른 사람을 위해 설치되지 않습니다. 플러그인을 로드하는 모든 경로에서 Claude Code는 각 사용자가 [직접 설치할 때까지](/docs/ko/plugins/org#require-plugins-per-repository) 플러그인이 설치되지 않은 것으로 보고합니다.

5001 5004

5003 `extraKnownMarketplaces`5006 `extraKnownMarketplaces`

5004</h3>5007</h3>

5005 5008

5006저장소를 열거나 관리 설정이 도달하는 모든 사람이 마켓플레이스를 직접 추가하지 않고도 얻을 수 있도록 이름으로 추가 플러그인 마켓플레이스를 등록합니다. Claude Code는 아직 알지 못하는 각 마켓플레이스를 등록합니다. [`enabledPlugins`](#enabledplugins)가 이름을 지정한 플러그인이 설치되는지 여부는 플러그인의 소스 및 어느 파일이 이를 활성화하는지에 따라 다릅니다. 해당 항목에는 규칙이 있습니다.5009추가 플러그인 마켓플레이스를 이름으로 등록하여 저장소를 열거나 관리되는 설정이 도달하는 모든 사람이 직접 추가하지 않고도 마켓플레이스를 얻습니다. Claude Code는 아직 알지 못하는 각 마켓플레이스를 등록합니다. [`enabledPlugins`](#enabledplugins)가 이를 명명하는 플러그인이 설치되는지 여부는 플러그인의 소스 및 어느 파일이 이를 활성화하는지에 따라 다릅니다. 해당 항목에는 규칙이 있습니다.

5007 5010

5008* **범위**: [`모든 파일`](#scopes). Claude Code는 해당 폴더에 대한 작업 공간 신뢰 대화를 수락한 후에만 저장소의 `.claude/settings.json` 또는 `.claude/settings.local.json`의 항목을 인정합니다. 신뢰하지 않은 폴더(예: `-p` 실행 포함)에서는 메시지 없이 무시합니다.5011* **범위**: [`모든 파일`](#scopes). Claude Code는 해당 폴더에 대한 작업 공간 신뢰 대화를 수락한 후에만 저장소의 `.claude/settings.json` 또는 `.claude/settings.local.json`의 항목을 인정합니다. 신뢰하지 않은 폴더(예: `-p` 실행)에서는 메시지 없이 무시합니다.

5009* **유형**: 마켓플레이스 이름을 `source` 객체 및 선택적 `autoUpdate` 부울이 있는 객체에 매핑하는 객체5012* **유형**: 마켓플레이스 이름을 `source` 객체 및 선택적 `autoUpdate` 부울이 있는 객체에 매핑하는 객체

5010* **기본값**: 설정되지 않음5013* **기본값**: 설정되지 않음

5011 5014

5030}5033}

5031```5034```

5032 5035

5033[폴더를 신뢰하기 전에 실행되는 것](/docs/ko/permissions#what-runs-before-you-trust-a-folder)은 신뢰 게이트를 저장소가 제공할 수 있는 다른 콘텐츠와 비교합니다. 이 키를 `additionalMarketplaces`로도 쓸 수 있습니다. [마켓플레이스 키 별칭](#marketplace-key-aliases)을 참조하십시오.5036[폴더를 신뢰하기 전에 실행되는 것](/docs/ko/permissions#what-runs-before-you-trust-a-folder)은 신뢰 게이트를 저장소가 제공할 수 있는 다른 콘텐츠와 비교합니다. 이 키를 `additionalMarketplaces`로도 쓸 수 있습니다. [마켓플레이스 키 별칭](#marketplace-key-aliases)을 참조하세요.

5034 5037

5035시작 후 백그라운드에서 해당 마켓플레이스를 새로 고치고 설치된 플러그인을 업데이트하도록 Claude Code를 만들려면 `source` 옆에 `"autoUpdate": true`를 설정합니다. 생략하면 `claude-plugins-official` 및 대부분의 다른 공식 Anthropic 마켓플레이스는 기본값이 `true`이고 타사 마켓플레이스는 기본값이 `false`입니다. [자동 업데이트 구성](/docs/ko/plugins/install#keep-plugins-updated)을 참조하십시오.5038`source` 옆에 `"autoUpdate": true`를 설정하여 Claude Code가 해당 마켓플레이스를 새로 고치고 시작 후 백그라운드에서 설치된 플러그인을 업데이트하도록 합니다. 생략하면 `claude-plugins-official` 및 대부분의 다른 공식 Anthropic 마켓플레이스는 `true`로 기본값이 지정되고 타사 마켓플레이스는 `false`로 기본값이 지정됩니다. [자동 업데이트 구성](/docs/ko/plugins/install#keep-plugins-updated)을 참조하세요.

5036 5039

5037둘 이상의 설정 파일이 동일한 이름 아래에 마켓플레이스 항목을 정의할 때 Claude Code는 [최고 우선순위 파일](/docs/ko/settings#settings-precedence)의 항목을 전체적으로 사용합니다. 해당 항목은 낮은 우선순위 항목을 바꾸고 필드를 상속하지 않으므로 재정의는 한 파일의 `source.headers` 자격 증명을 다른 파일이 제어하는 URL과 결합할 수 없습니다. v2.1.228 이전에는 Claude Code가 같은 이름 항목을 필드별로 병합했으므로 더 높은 우선순위 파일의 항목은 설정하지 않은 필드(다른 파일의 `headers` 포함)를 상속할 수 있었습니다.5040둘 이상의 설정 파일이 동일한 이름 아래에 마켓플레이스 항목을 정의할 때 Claude Code는 [최고 우선순위 파일](/docs/ko/settings#settings-precedence)의 항목을 사용합니다. 해당 항목은 낮은 우선순위 항목을 대체하고 필드를 상속하지 않으므로 재정의는 한 파일의 `source.headers` 자격 증명을 다른 파일이 제어하는 URL과 결합할 수 없습니다. v2.1.228 이전에는 Claude Code가 같은 이름 항목을 필드별로 병합했으므로 더 높은 우선순위 파일의 항목은 설정하지 않은 필드(다른 파일의 `headers` 포함)를 상속할 수 있었습니다.

5038 5041

5039<h4 id="marketplace-source-types">5042<h4 id="marketplace-source-types">

5040 마켓플레이스 소스 유형5043 마켓플레이스 소스 유형

5044 5047

5045* **`github`**: GitHub 저장소, `repo` 포함5048* **`github`**: GitHub 저장소, `repo` 포함

5046* **`git`**: 모든 git URL, `url` 포함5049* **`git`**: 모든 git URL, `url` 포함

5047* **`url`**: `marketplace.json` 파일에 대한 직접 URL, `url` 및 선택적 `headers` 및 인증된 액세스를 위한 `headersHelper` 포함. `headersHelper`는 `headers`에 나열하기에는 너무 단기간인 값을 가진 헤더를 인쇄하는 명령어의 이름을 지정하며 Claude Code v2.1.238 이상이 필요합니다5050* **`url`**: `marketplace.json` 파일에 대한 직접 URL, `url` 및 선택적 `headers` 및 `headersHelper`(인증된 액세스용). `headersHelper`는 `headers`에 나열하기에는 너무 단기간인 값을 가진 헤더를 인쇄하는 명령어의 이름을 지정하며 Claude Code v2.1.238 이상이 필요합니다

5048* **`file`**: `marketplace.json` 파일에 대한 로컬 경로, `path` 포함5051* **`file`**: `marketplace.json` 파일에 대한 로컬 경로, `path` 포함

5049* **`directory`**: 개발 전용 로컬 파일 시스템 경로, `path` 포함5052* **`directory`**: 로컬 파일 시스템 경로, `path` 포함. 개발용으로 사용하거나 조직이 [각 머신에 배포하는](/docs/ko/plugins/mods/admin#install-your-organizations-mods) 마켓플레이스용으로 사용합니다.

5050* **`settings`**: 호스팅된 저장소 없이 설정 파일에 직접 선언된 인라인 마켓플레이스, `name` 및 `plugins` 포함5053* **`settings`**: 호스팅된 저장소 없이 설정 파일에 직접 선언된 인라인 마켓플레이스, `name` 및 `plugins` 포함

5051 5054

5052`git` 소스 유형은 자체 호스팅 GitLab 및 Bitbucket을 포함한 모든 git 호스팅 서비스와 함께 작동합니다. Claude Code는 해당 머신에서 `git clone`이 사용할 것과 동일한 인증으로 저장소를 복제합니다. 구성된 자격 증명 도우미 또는 SSH 키. `GITHUB_TOKEN`과 같은 공급자 토큰은 이를 읽는 자격 증명 도우미를 통해 적용됩니다. 설정 세부 정보는 [비공개 저장소](/docs/ko/plugins/host-marketplace#grant-access-to-a-private-marketplace)를 참조하십시오.5055`git` 소스 유형은 자체 호스팅 GitLab 및 Bitbucket을 포함한 모든 git 호스팅 서비스와 함께 작동합니다. Claude Code는 해당 머신에서 `git clone`이 사용할 것과 동일한 인증으로 저장소를 복제합니다. 구성된 자격 증명 도우미 또는 SSH 키. `GITHUB_TOKEN`과 같은 공급자 토큰은 이를 읽는 자격 증명 도우미를 통해 적용됩니다. [비공개 저장소](/docs/ko/plugins/host-marketplace#grant-access-to-a-private-marketplace)를 참조하세요.

5053 5056

5054`github` 및 `git` 소스의 경우 Claude Code는 마켓플레이스 저장소를 추가하거나 업데이트하기 위해 복제할 때 [Git LFS](https://git-lfs.com) 콘텐츠를 다운로드하지 않습니다. LFS 추적 파일은 포인터 파일로 체크아웃되고 추가 또는 업데이트 출력은 몇 개인지 보고합니다.5057`github` 및 `git` 소스의 경우 Claude Code는 마켓플레이스 저장소를 복제하여 추가하거나 업데이트할 때 [Git LFS](https://git-lfs.com) 콘텐츠를 다운로드하지 않습니다. LFS 추적 파일은 포인터 파일로 체크아웃되고 추가 또는 업데이트 출력은 몇 개인지 보고합니다.

5055 5058

5056`source` 객체 내의 `skipLfs` 필드는 수용되며 효과가 없습니다. v2.1.274 이전에는 Claude Code가 `"skipLfs": true`를 설정하지 않으면 LFS 콘텐츠를 다운로드했습니다.5059`source` 객체 내의 `skipLfs` 필드는 수용되며 효과가 없습니다. v2.1.274 이전에는 `"skipLfs": true`를 설정하지 않으면 Claude Code가 LFS 콘텐츠를 다운로드했습니다.

5057 5060

5058URL 소스의 경우 `headers`의 자격 증명이 만료되고 명령어가 새 자격 증명을 생성해야 할 때 `source` 객체 내에 `headersHelper`를 설정합니다. Claude Code v2.1.238 이상이 필요합니다. 명령어가 인쇄해야 하는 것 및 Claude Code가 실행하는 위치는 [headersHelper 명령어 작성](/docs/ko/plugins/host-marketplace#write-the-headershelper-command)을 참조하고, Claude Code가 headersHelper 명령어를 건너뛰는 경우는 [Claude Code가 headersHelper 명령어를 건너뛰거나 출력을 삭제할 때](/docs/ko/plugins/host-marketplace#when-claude-code-skips-a-headershelper-command-or-drops-its-output)를 참조하십시오. `https://` 마켓플레이스 URL에 `headersHelper`를 설정하면 Claude Code는 명령어를 두 지점에서 실행하여 한 실행의 출력을 최대 60초 동안 재사용합니다:5061URL 소스의 경우 자격 증명이 `headers`에서 만료되고 명령어가 새 자격 증명을 생성해야 할 때 `source` 객체 내에 `headersHelper`를 설정합니다. Claude Code v2.1.238 이상이 필요합니다. 명령어가 인쇄해야 하는 것 및 Claude Code가 실행하는 위치는 [headersHelper 명령어 작성](/docs/ko/plugins/host-marketplace#write-the-headershelper-command)을 참조하고, Claude Code가 건너뛰는 경우는 [Claude Code가 headersHelper 명령어를 건너뛰거나 출력을 삭제할 때](/docs/ko/plugins/host-marketplace#when-claude-code-skips-a-headershelper-command-or-drops-its-output)를 참조하세요. `https://` 마켓플레이스 URL에서 `headersHelper`를 설정하면 Claude Code는 명령어를 두 지점에서 실행하여 한 실행의 출력을 최대 60초 동안 재사용합니다:

5059 5062

5060* 해당 마켓플레이스의 `marketplace.json` 각 가져오기 전(나중의 새로 고침 포함). Claude Code는 인쇄된 헤더를 해당 가져오기와 함께 보냅니다.5063* 해당 마켓플레이스의 `marketplace.json` 각 가져오기 전(나중의 새로 고침 포함). Claude Code는 인쇄된 헤더를 해당 가져오기와 함께 보냅니다.

5061* 마켓플레이스 URL의 원점(동일한 스키마, 호스트 및 포트를 의미)의 각 플러그인 아카이브 다운로드 전. Claude Code는 출력을 해당 다운로드와 함께 보내고 다른 다운로드는 헤더를 받지 않습니다.5064* 마켓플레이스 URL의 원점(동일한 스키마, 호스트, 포트를 의미)의 각 플러그인 아카이브 다운로드 전. Claude Code는 출력을 해당 다운로드와 함께 보내고 다른 다운로드는 헤더를 받지 않습니다.

5062 5065

5063Claude Code는 [`--add-dir`](/docs/ko/permissions#what-runs-before-you-trust-a-folder)로 추가한 디렉터리의 `.claude/settings.json` 또는 `.claude/settings.local.json`에서 설정된 모든 `headersHelper`를 무시하며, `url` 소스 및 인라인 플러그인 항목 모두에서 해당 파일에 설정된 고정 `headers`만 보냅니다. [사용자가 headersHelper 명령어를 수락하는 방법](/docs/ko/plugins/host-marketplace#how-users-accept-a-headershelper-command)은 다른 설정 파일을 다룹니다.5066Claude Code는 [`--add-dir`](/docs/ko/permissions#what-runs-before-you-trust-a-folder)로 추가하는 디렉터리의 `.claude/settings.json` 또는 `.claude/settings.local.json`에서 설정된 `headersHelper`를 무시하고 `url` 소스 및 인라인 플러그인 항목 모두에서 해당 파일에 설정된 고정 `headers`만 보냅니다. [사용자가 headersHelper 명령어를 수락하는 방법](/docs/ko/plugins/host-marketplace#how-users-accept-a-headershelper-command)은 다른 설정 파일을 다룹니다.

5064 5067

5065`settings` 소스에 나열된 플러그인은 GitHub 또는 npm과 같은 외부 소스를 참조해야 하며 `name`은 마켓플레이스 키와 일치해야 합니다. 여전히 `enabledPlugins`에서 각 플러그인을 별도로 활성화합니다. 이 예제는 하나의 플러그인을 인라인으로 선언합니다:5068`settings` 소스에 나열된 플러그인은 GitHub 또는 npm과 같은 외부 소스를 참조해야 하며 `name`은 마켓플레이스 키와 일치해야 합니다. 여전히 `enabledPlugins`에서 각 플러그인을 별도로 활성화합니다. 이 예제는 하나의 플러그인을 인라인으로 선언합니다:

5066 5069

5088 5091

5089자체 `source`가 [`archive`](/docs/ko/plugins/marketplace-reference#archive-plugin-source)인 `source: 'settings'` 아래의 플러그인 항목은 아카이브 다운로드를 위해 `headers`를 설정할 수 있습니다. `headers`에 넣을 값이 단기간인 경우(예: 레지스트리가 요청 시 발행하는 토큰) 대신 `headersHelper` 명령어를 설정합니다. 항목은 둘 다 설정할 수 있습니다. 두 필드 모두 Claude Code v2.1.238 이상이 필요합니다.5092자체 `source`가 [`archive`](/docs/ko/plugins/marketplace-reference#archive-plugin-source)인 `source: 'settings'` 아래의 플러그인 항목은 아카이브 다운로드를 위해 `headers`를 설정할 수 있습니다. `headers`에 넣을 값이 단기간인 경우(예: 레지스트리가 요청 시 발행하는 토큰) 대신 `headersHelper` 명령어를 설정합니다. 항목은 둘 다 설정할 수 있습니다. 두 필드 모두 Claude Code v2.1.238 이상이 필요합니다.

5090 5093

5091Claude Code는 항목의 `headers` 및 명령어가 인쇄한 것을 해당 플러그인의 아카이브 다운로드와 함께 보내고 다른 다운로드와는 함께 보내지 않습니다. Claude Code는 사용자가 [해당 플러그인 하나를 직접 설치 또는 업데이트할 때](/docs/ko/plugins/host-marketplace#how-users-accept-a-headershelper-command)만 명령어를 실행합니다. 세 가지 추가 규칙은 항목을 보유한 파일에 따라 다릅니다:5094Claude Code는 항목의 `headers` 및 명령어가 인쇄하는 것을 해당 플러그인의 아카이브 다운로드와 함께 보내고 다른 다운로드와는 함께 보내지 않습니다. Claude Code는 사용자가 [해당 플러그인 하나를 직접 설치 또는 업데이트할 때만](/docs/ko/plugins/host-marketplace#how-users-accept-a-headershelper-command) 명령어를 실행합니다. 세 가지 추가 규칙은 항목을 보유하는 파일에 따라 다릅니다:

5092 5095

5093* **`strict`**: 마켓플레이스의 `marketplace.json`의 항목과 달리 설정 파일의 항목은 인라인 매니페스트 필드가 없으므로 `"strict": false`가 필요하지 않습니다. [엄격 모드](/docs/ko/plugins/marketplace-reference#strict-mode)를 참조하십시오.5096* **`strict`**: 마켓플레이스의 `marketplace.json`의 항목과 달리 설정 파일의 항목은 `"strict": false`가 필요하지 않습니다. 설정 파일은 인라인할 매니페스트 필드를 수행하지 않기 때문입니다. [엄격 모드](/docs/ko/plugins/marketplace-reference#strict-mode)를 참조하세요.

5094* **폴더 신뢰**: 프로젝트의 `.claude/settings.json` 또는 `.claude/settings.local.json`의 항목의 경우 Claude Code는 사용자가 [해당 폴더도 신뢰한](/docs/ko/permissions#what-runs-before-you-trust-a-folder) 후에만 명령어를 실행합니다.5097* **폴더 신뢰**: 프로젝트의 `.claude/settings.json` 또는 `.claude/settings.local.json`의 항목의 경우 Claude Code는 사용자가 [해당 폴더도 신뢰한](/docs/ko/permissions#what-runs-before-you-trust-a-folder) 후에만 명령어를 실행합니다.

5095* **헤더 필터**: Claude Code는 저장소가 해당 파일을 제공할 수 있으므로 프로젝트의 `.claude/settings.json` 또는 `.claude/settings.local.json`의 항목에서 [요청 라우팅 및 클라이언트 ID 헤더 이름](/docs/ko/plugins/host-marketplace#when-claude-code-skips-a-headershelper-command-or-drops-its-output)을 삭제합니다. Claude Code는 카탈로그 항목 및 `--add-dir` 디렉터리의 설정 항목에 동일한 필터를 적용하고 사용자 설정, `--settings` 파일 또는 관리 설정의 항목에는 필터를 적용하지 않습니다.5098* **헤더 필터**: Claude Code는 저장소가 해당 파일을 제공할 수 있으므로 프로젝트의 `.claude/settings.json` 또는 `.claude/settings.local.json`의 항목에서 [요청 라우팅 및 클라이언트 ID 헤더 이름](/docs/ko/plugins/host-marketplace#when-claude-code-skips-a-headershelper-command-or-drops-its-output)을 삭제합니다. Claude Code는 카탈로그 항목 및 `--add-dir` 디렉터리의 설정의 항목에 동일한 필터를 적용하고 사용자 설정, `--settings` 파일 또는 관리되는 설정의 항목에는 필터를 적용하지 않습니다.

5096 5099

5097<h4 id="marketplace-key-aliases">5100<h4 id="marketplace-key-aliases">

5098 마켓플레이스 키 별칭5101 마켓플레이스 키 별칭

5100 5103

5101Claude Code v2.1.232 이상에서는 `extraKnownMarketplaces`를 `additionalMarketplaces`로, `strictKnownMarketplaces`를 `allowedMarketplaces`로 쓸 수 있습니다. Claude Code는 각 별칭을 다음과 같이 취급합니다:5104Claude Code v2.1.232 이상에서는 `extraKnownMarketplaces`를 `additionalMarketplaces`로, `strictKnownMarketplaces`를 `allowedMarketplaces`로 쓸 수 있습니다. Claude Code는 각 별칭을 다음과 같이 취급합니다:

5102 5105

5103* 이전 버전은 별칭을 무시하므로 혼합 Claude Code 버전의 플릿을 위한 관리 설정 파일과 같이 이전 버전도 읽는 파일에서 정규 철자를 유지합니다.5106* 이전 버전은 별칭을 무시하므로 관리되는 설정 파일과 같이 이전 버전도 읽는 파일에서 정규 철자를 유지합니다.

5104* 정규 키를 수용하는 모든 설정 파일에서 Claude Code는 별칭을 정규 키와 정확히 동일하게 읽습니다.5107* 정규 키를 수용하는 모든 설정 파일에서 Claude Code는 별칭을 정규 키와 정확히 동일하게 읽습니다.

5105* Claude Code는 파일을 업데이트할 때 `additionalMarketplaces`를 `extraKnownMarketplaces`로 다시 쓸 수 있습니다.5108* Claude Code는 파일을 업데이트할 때 `additionalMarketplaces`를 `extraKnownMarketplaces`로 다시 쓸 수 있습니다.

5106* 한 파일에서 두 철자를 모두 설정하면 Claude Code는 정규 값을 사용하고 별칭을 무시합니다.5109* 한 파일에서 두 철자를 모두 설정하면 Claude Code는 정규 값을 사용하고 별칭을 무시합니다.

5111 5114

5112플러그인의 [`userConfig`](/docs/ko/plugins/manifest-reference#user-configuration) 구성 대화에서 제공하는 민감하지 않은 답변을 플러그인 ID로 키가 지정된 상태로 저장합니다. Claude Code는 대화를 작성할 때 이 키를 사용자 설정에 작성하므로 직접 편집할 필요가 없습니다. Claude Code는 민감한 옵션을 macOS Keychain에 저장하고, Keychain이 쓰기를 거부할 때 `~/.claude/.credentials.json`으로 폴백합니다. 지원되는 키체인이 없는 플랫폼에서는 `~/.claude/.credentials.json`에 저장합니다.5115플러그인의 [`userConfig`](/docs/ko/plugins/manifest-reference#user-configuration) 구성 대화에서 제공하는 민감하지 않은 답변을 플러그인 ID로 키가 지정된 상태로 저장합니다. Claude Code는 대화를 작성할 때 이 키를 사용자 설정에 작성하므로 직접 편집할 필요가 없습니다. Claude Code는 민감한 옵션을 macOS Keychain에 저장하고, Keychain이 쓰기를 거부할 때 `~/.claude/.credentials.json`으로 폴백합니다. 지원되는 키체인이 없는 플랫폼에서는 `~/.claude/.credentials.json`에 저장합니다.

5113 5116

5114* **범위**: [`사용자 또는 관리`](#scopes)5117* **범위**: [`사용자 또는 관리됨`](#scopes)

5115* **유형**: 플러그인 ID를 `options` 필드가 있는 객체에 매핑하는 객체, 각 옵션 이름을 문자열, 숫자, 부울 또는 문자열 배열에 매핑하고, 동일한 형태의 서버별 사용자 구성 값을 보유하는 선택적 `mcpServers` 필드5118* **유형**: 플러그인 ID를 `options` 필드가 있는 객체에 매핑하는 객체. 각 옵션 이름을 문자열, 숫자, 부울 또는 문자열 배열에 매핑하고, 동일한 형태의 서버별 사용자 구성 값을 보유하는 선택적 `mcpServers` 필드

5116* **기본값**: 설정되지 않음5119* **기본값**: 설정되지 않음

5117 5120

5118이 예제는 `acme-tools`의 `deployer` 플러그인에 대한 `api_endpoint` 옵션을 저장합니다:5121이 예제는 `acme-tools`의 `deployer` 플러그인에 대한 `api_endpoint` 옵션을 저장합니다:

5133 5136

5134Claude Code는 이 값을 플러그인 훅, MCP 및 LSP 구성에 대체하므로 프로젝트 및 로컬 항목을 무시합니다. 복제된 저장소는 이를 제공할 수 없습니다. v2.1.207 이전에는 프로젝트 및 로컬 설정도 읽혔습니다.5137Claude Code는 이 값을 플러그인 훅, MCP 및 LSP 구성에 대체하므로 프로젝트 및 로컬 항목을 무시합니다. 복제된 저장소는 이를 제공할 수 없습니다. v2.1.207 이전에는 프로젝트 및 로컬 설정도 읽혔습니다.

5135 5138

5139<h3 id="prependplugins">

5140 `prependPlugins`

5141</h3>

5142

5143모든 사용자가 설치하는 모드 전에 [모드](/docs/ko/plugins/mods/overview)가 실행되는 관리되는 플러그인을 나열된 순서로 나열합니다. 관리되는 설정에서 이 키를 설정할 때 목록에 `sec-default@builtin`을 명명하여 기본 제공 가드를 유지합니다. 관리되는 설정에서 Claude Code는 플러그인이 조직의 것으로 계산되지 않는 ID를 건너뜁니다. [조직의 모드 설치 및 순서 설정](/docs/ko/plugins/mods/admin#install-your-organizations-mods)에서 해당 조건 및 두 순서 키가 함께 작동하는 방식을 참조하세요.

5144

5145* **범위**: [`사용자 또는 관리됨`](#scopes). Claude Code는 관리되는 설정에서 키를 읽습니다. 관리되는 설정이 없는 머신에서 Team 또는 Enterprise 플랜으로 로그인하지 않은 사용자의 경우에만 사용자 설정에서 키를 읽습니다. 프로젝트 및 로컬 설정 및 `--settings` 파일의 키는 무시합니다.

5146* **유형**: `plugin-name@marketplace-name` 문자열 배열

5147* **기본값**: 설정되지 않음

5148

5149```json managed-settings.json theme={null}

5150{

5151 "extraKnownMarketplaces": {

5152 "acme-tools": {

5153 "source": { "source": "directory", "path": "/opt/acme/claude-plugins" }

5154 }

5155 },

5156 "enabledPlugins": { "acme-guard@acme-tools": true },

5157 "prependPlugins": ["acme-guard@acme-tools", "sec-default@builtin"]

5158}

5159```

5160

5161<h3 id="appendplugins">

5162 `appendPlugins`

5163</h3>

5164

5165모든 사용자가 설치하는 모드 후에 [모드](/docs/ko/plugins/mods/overview)가 실행되는 관리되는 플러그인을 나열된 순서로 나열합니다. `prependPlugins` 및 `appendPlugins` 모두에 나열된 ID는 앞에 붙습니다. 관리되는 설정에서 Claude Code는 플러그인이 [조직의 것으로 계산되지 않는](/docs/ko/plugins/mods/admin#install-your-organizations-mods) ID를 건너뜁니다.

5166

5167* **범위**: [`사용자 또는 관리됨`](#scopes). Claude Code는 관리되는 설정에서 키를 읽습니다. 관리되는 설정이 없는 머신에서 Team 또는 Enterprise 플랜으로 로그인하지 않은 사용자의 경우에만 사용자 설정에서 키를 읽습니다. 프로젝트 및 로컬 설정 및 `--settings` 파일의 키는 무시합니다.

5168* **유형**: `plugin-name@marketplace-name` 문자열 배열

5169* **기본값**: 설정되지 않음

5170

5171```json managed-settings.json theme={null}

5172{

5173 "extraKnownMarketplaces": {

5174 "acme-tools": {

5175 "source": { "source": "directory", "path": "/opt/acme/claude-plugins" }

5176 }

5177 },

5178 "enabledPlugins": { "acme-audit@acme-tools": true },

5179 "appendPlugins": ["acme-audit@acme-tools"]

5180}

5181```

5182

5136<h2 id="mcp">5183<h2 id="mcp">

5137 MCP5184 MCP

5138</h2>5185</h2>

5598 원격, 데스크톱 및 알림5645 원격, 데스크톱 및 알림

5599</h2>5646</h2>

5600 5647

5601Remote Control, 클라우드 환경, 데스크톱 앱 및 Claude Code가 필요할 때 보내는 알림을 구성합니다. [Remote Control](/docs/ko/remote-control)을 참조하세요.5648Remote Control, 클라우드 환경, 데스크톱 앱 및 Claude Code가 필요할 때 전송하는 알림을 구성합니다. [Remote Control](/docs/ko/remote-control)을 참조하세요.

5602 5649

5603<h3 id="agentpushnotifenabled">5650<h3 id="agentpushnotifenabled">

5604 `agentPushNotifEnabled`5651 `agentPushNotifEnabled`

5605</h3>5652</h3>

5606 5653

5607Claude가 가치 있다고 판단할 때 휴대폰으로 푸시 알림을 보낼 수 있도록 허용합니다. 예를 들어 긴 작업이 완료될 때입니다. Claude Code는 이 선택을 계정에 동기화하며, [Remote Control](/docs/ko/remote-control)이 연결되어 있을 때 푸시가 도착합니다. `/config`에서 **Claude가 결정할 때 푸시**로 표시됩니다.5654Claude가 가치 있다고 판단할 때(예: 긴 작업이 완료될 때) 휴대폰으로 푸시 알림을 보낼 수 있도록 허용합니다. Claude Code는 이 선택을 계정에 동기화하며, [Remote Control](/docs/ko/remote-control)이 연결되어 있을 때 푸시가 도착합니다. `/config`에서 **Claude가 결정할 때 푸시**로 표시됩니다.

5608 5655

5609* **범위**: [`Any file`](#scopes). Claude Code는 이전 버전에서 `~/.claude.json`에 남겨진 값도 읽습니다.5656* **범위**: [`Any file`](#scopes). Claude Code는 이전 버전에서 `~/.claude.json`에 남겨진 값도 읽습니다.

5610* **유형**: Boolean5657* **유형**: Boolean

5624 `awaySummaryEnabled`5671 `awaySummaryEnabled`

5625</h3>5672</h3>

5626 5673

5627몇 분 동안 터미널에서 떠난 후 돌아올 때 한 줄의 세션 요약을 표시합니다. `false`로 설정하거나 `/config`에서 **세션 요약**을 끄면 요약이 중지됩니다.5674몇 분 동안 터미널에서 떠난 후 돌아올 때 한 줄짜리 세션 요약을 표시합니다. `false`로 설정하거나 `/config`에서 **세션 요약**을 끄면 요약이 중지됩니다.

5628 5675

5629* **범위**: [`Any file`](#scopes)5676* **범위**: [`Any file`](#scopes)

5630* **유형**: Boolean5677* **유형**: Boolean

5631 * `true`: 몇 분 동안 떠난 후 돌아올 때 한 줄의 세션 요약을 볼 수 있습니다5678 * `true`: 몇 분 동안 떠난 후 돌아올 때 한 줄짜리 세션 요약이 표시됩니다

5632 * `false`: Claude Code는 요약을 표시하지 않습니다5679 * `false`: Claude Code는 요약을 표시하지 않습니다

5633* **기본값**: 설정되지 않음, 따라서 요약은 켜져 있습니다5680* **기본값**: 설정되지 않음, 따라서 요약이 켜져 있습니다

5634* **세션별 재정의**: [`CLAUDE_CODE_ENABLE_AWAY_SUMMARY`](/docs/ko/env-vars)는 이 키보다 한 세션에 대해 어느 방향이든 우선합니다5681* **세션별 재정의**: [`CLAUDE_CODE_ENABLE_AWAY_SUMMARY`](/docs/ko/env-vars)는 이 키보다 한 세션에 대해 어느 방향이든 우선합니다

5635 5682

5636```json settings.json theme={null}5683```json settings.json theme={null}

5646</h3>5693</h3>

5647 5694

5648<Warning>5695<Warning>

5649 더 이상 사용되지 않으며 [`enableArtifact`](#enableartifact)로 대체되었습니다. Claude Code는 여전히 `disableArtifact: true`를 `enableArtifact: false`와 동등하게 인정하며, `disableArtifact: false`는 무시합니다.5696 더 이상 사용되지 않으며 [`enableArtifact`](#enableartifact)로 대체되었습니다. Claude Code는 여전히 `disableArtifact: true`를 `enableArtifact: false`와 동등하게 처리하며, `disableArtifact: false`는 무시합니다.

5650</Warning>5697</Warning>

5651 5698

5652대신 [`enableArtifact`](#enableartifact)를 사용하여 claude.ai에서 세션 출력을 비공개 웹 페이지로 게시하는 [Artifact](/docs/ko/artifacts) 도구를 끕니다. `/config`에서 **Artifacts** 행을 끄면 Claude Code는 `enableArtifact`를 사용자 설정에 작성하고 이 키를 지웁니다.5699대신 [`enableArtifact`](#enableartifact)를 사용하여 [Artifact](/docs/ko/artifacts) 도구를 끕니다. 이 도구는 세션 출력을 claude.ai의 비공개 웹 페이지로 게시합니다. `/config`에서 **Artifacts** 행을 끄면 Claude Code는 `enableArtifact`를 사용자 설정에 기록하고 이 키를 지웁니다.

5653 5700

5654* **범위**: [`Any file`](#scopes)5701* **범위**: [`Any file`](#scopes)

5655* **유형**: Boolean5702* **유형**: Boolean

5656 * `true`: Claude Code는 파일이 적용되는 모든 세션에 대해 Artifact 도구를 끄고, 다른 파일은 이를 다시 켜지 않습니다. v2.1.242 이전에는 더 높은 우선순위 파일이 낮은 파일의 `true`를 재정의할 수 있었으며, 키가 잠금으로 작동하지 않았습니다5703 * `true`: Claude Code는 파일이 적용되는 모든 세션에 대해 Artifact 도구를 끄며, 다른 파일은 이를 다시 켤 수 없습니다

5657 * `false`: 무시됨; 도구를 켜진 상태로 두려면 키를 제거합니다5704 * `false`: 무시됨; 도구를 켜진 상태로 두려면 키를 제거하세요

5658* **기본값**: 설정되지 않음, 따라서 도구는 계정의 [가용성](/docs/ko/artifacts#availability)을 따릅니다5705* **기본값**: 설정되지 않음, 따라서 도구는 계정의 [가용성](/docs/ko/artifacts#availability)을 따릅니다

5659* **세션별 재정의**: [`CLAUDE_CODE_DISABLE_ARTIFACT`](/docs/ko/env-vars)를 `1`로 설정하면 한 세션에 대해 도구가 꺼집니다5706* **세션별 재정의**: [`CLAUDE_CODE_DISABLE_ARTIFACT`](/docs/ko/env-vars)를 `1`로 설정하면 한 세션에 대해 도구가 꺼집니다

5660 5707

5670 `disableDeepLinkRegistration`5717 `disableDeepLinkRegistration`

5671</h3>5718</h3>

5672 5719

5673Claude Code가 `claude-cli://` 프로토콜 핸들러를 운영 체제에 등록하지 않도록 중지합니다. 이는 대화형 세션의 첫 번째 프롬프트를 보낸 후에 등록됩니다. [Deep links](/docs/ko/deep-links)를 사용하면 외부 도구가 미리 채워진 프롬프트로 Claude Code 세션을 열 수 있습니다. 프로토콜 핸들러 등록이 제한되거나 별도로 관리되는 환경에서 이를 설정합니다.5720Claude Code가 `claude-cli://` 프로토콜 핸들러를 운영 체제에 등록하지 않도록 중지합니다. 이 키가 설정되지 않으면 Claude Code는 대화형 세션의 첫 번째 프롬프트를 보낸 후에 등록합니다. [Deep links](/docs/ko/deep-links)를 사용하면 외부 도구가 미리 채워진 프롬프트로 Claude Code 세션을 열 수 있습니다. 프로토콜 핸들러 등록이 제한되거나 별도로 관리되는 환경에서 이를 설정합니다.

5674 5721

5675* **범위**: [`Any file`](#scopes)5722* **범위**: [`Any file`](#scopes)

5676* **유형**: 문자열 `"disable"`5723* **유형**: 문자열 `"disable"`

5686 `disableDesktopLocalSessions`5733 `disableDesktopLocalSessions`

5687</h3>5734</h3>

5688 5735

5689개발자가 SSH를 통해 원격 머신에서 작업해야 하는 배포의 경우 [데스크톱 앱](/docs/ko/desktop#local-sessions-on-managed-devices)에서 디바이스에서 실행되는 Code 세션을 끕니다. Code 탭에서 **Local** 환경은 환경 드롭다운에 남아 있지만 회색으로 표시되고 선택할 수 없으며, 조직이 이를 끄도록 했다는 도구 설명이 표시됩니다. Windows에서는 WSL 항목도 같은 방식으로 회색으로 표시되지만, WSL 세션이 관리되는 디바이스에서 실행되는지 여부는 [별도로 관리됩니다](/docs/ko/admin-setup#wsl-sessions-in-claude-code-desktop). 새 세션은 구성된 [SSH 연결](/docs/ko/desktop#ssh-sessions)이 있으면 첫 번째로 기본값이 설정되며, 앱은 같은 머신으로의 SSH 연결을 포함하여 디바이스에서 세션을 시작하거나 재개하기를 거부합니다. 다른 호스트로의 SSH 세션 및 클라우드 세션은 영향을 받지 않습니다. 데스크톱 앱은 이 키를 읽습니다. 터미널 CLI는 무시합니다. Claude Desktop v1.37937.0 이상이 필요합니다.5736개발자가 SSH를 통해 원격 머신에서 작업해야 하는 배포의 경우 [데스크톱 앱](/docs/ko/desktop#local-sessions-on-managed-devices)에서 실행되는 Code 세션을 끕니다. Code 탭에서 **Local** 환경은 환경 드롭다운에 남아 있지만 회색으로 표시되고 선택할 수 없으며, 조직이 이를 끄도록 했다는 도구 설명이 표시됩니다. Windows에서는 WSL 항목도 같은 방식으로 회색으로 표시되지만, WSL 세션이 관리되는 디바이스에서 실행되는지 여부는 [별도로 관리됩니다](/docs/ko/admin-setup#wsl-sessions-in-claude-code-desktop). 새 세션은 구성된 첫 번째 [SSH 연결](/docs/ko/desktop#ssh-sessions)로 기본 설정되며, 앱은 디바이스에서 세션을 시작하거나 재개하기를 거부합니다(같은 머신으로의 SSH 연결 포함). 다른 호스트로의 SSH 세션 및 클라우드 세션은 영향을 받지 않습니다. 데스크톱 앱은 이 키를 읽습니다. 터미널 CLI는 무시합니다. Claude Desktop v1.37937.0 이상이 필요합니다.

5690 5737

5691* **범위**: [`Managed`](#scopes)5738* **범위**: [`Managed`](#scopes)

5692* **유형**: Boolean; JSON Boolean `true`만 적용됩니다5739* **유형**: Boolean; JSON Boolean `true`만 적용됩니다

5700}5747}

5701```5748```

5702 5749

5703데스크톱 앱은 다른 값을 무시하며, Boolean이 아닌 값(예: 문자열 `"true"` 또는 `1`)도 경고를 기록합니다. [`sshConfigs`](#sshconfigs)와 함께 사용하여 사용자가 작동하는 연결에 도달하도록 하고, [`sshHostAllowlist`](#sshhostallowlist)와 함께 사용하여 도달할 수 있는 호스트를 제한합니다. [관리되는 디바이스의 로컬 세션](/docs/ko/desktop#local-sessions-on-managed-devices)을 참조하세요.5750데스크톱 앱은 다른 값을 무시하며, Boolean이 아닌 값(예: 문자열 `"true"` 또는 `1`)도 경고를 기록합니다. [`sshConfigs`](#sshconfigs)와 함께 사용하여 사용자가 작동하는 연결에 도달하도록 하고, [`sshHostAllowlist`](#sshhostallowlist)와 함께 사용하여 사용자가 도달할 수 있는 호스트를 제한합니다. [관리되는 디바이스의 로컬 세션](/docs/ko/desktop#local-sessions-on-managed-devices)을 참조하세요.

5704 5751

5705Claude Desktop은 데스크톱 구성에서 파생된 정책(예: 송신 허용 목록, 파일 시스템 샌드박스 및 타사 배포의 MCP 제한)으로 Code 세션을 제공합니다. Claude Code는 [관리 소스](/docs/ko/managed-settings#how-claude-code-combines-managed-sources)(서버 관리 설정, MDM 또는 OS 수준 정책 또는 관리되는 설정 파일)가 있을 때마다 해당 부모 설정을 무시합니다. 타사 배포와 같이 이전에 없던 디바이스에 이 키를 배포하면 데스크톱 파생 정책이 적용되지 않습니다. [임베딩 호스트가 정책을 추가하도록 허용](/docs/ko/managed-settings#let-an-embedding-host-add-policy)은 부모 설정이 여전히 병합될 수 있는 경우를 다룹니다. 이는 이 방식으로 배포하는 모든 키에 적용되며, 이 키에만 해당하지 않습니다.5752Claude Desktop은 데스크톱 구성에서 파생된 정책(예: 송신 허용 목록, 파일 시스템 샌드박스 및 타사 배포의 MCP 제한)으로 Code 세션을 제공합니다. Claude Code는 [관리 소스](/docs/ko/managed-settings#how-claude-code-combines-managed-sources)(서버 관리 설정, MDM 또는 OS 수준 정책 또는 관리 설정 파일)가 있을 때마다 해당 부모 설정을 무시합니다. 타사 배포와 같이 이전에 없던 디바이스에 이 키를 배포하면 데스크톱 파생 정책이 적용되지 않습니다. [임베딩 호스트가 정책을 추가하도록 허용](/docs/ko/managed-settings#let-an-embedding-host-add-policy)은 부모 설정이 여전히 병합될 수 있는 경우를 다룹니다. 이는 이 키뿐만 아니라 이런 방식으로 배포하는 모든 키에 적용됩니다.

5706 5753

5707<h3 id="disableremotecontrol">5754<h3 id="disableremotecontrol">

5708 `disableRemoteControl`5755 `disableRemoteControl`

5709</h3>5756</h3>

5710 5757

5711[Remote Control](/docs/ko/remote-control)을 끕니다: Claude Code는 `claude remote-control`, `--remote-control` 플래그, 자동 시작 및 세션 내 토글을 거부하며, 조직의 정책이 이를 비활성화했다고 보고합니다. [관리되는 설정](/docs/ko/managed-settings)에 배치하여 디바이스별 MDM 적용을 수행합니다.5758[Remote Control](/docs/ko/remote-control)을 끕니다: Claude Code는 `claude remote-control`, `--remote-control` 플래그, 자동 시작 및 세션 내 토글을 거부하며, 조직의 정책이 이를 비활성화했다고 보고합니다. [관리 설정](/docs/ko/managed-settings)에 배치하여 디바이스별 MDM 적용을 수행합니다.

5712 5759

5713* **범위**: [`Any file`](#scopes)5760* **범위**: [`Any file`](#scopes)

5714* **유형**: Boolean5761* **유형**: Boolean

5726 `enableArtifact`5773 `enableArtifact`

5727</h3>5774</h3>

5728 5775

5729claude.ai에서 세션 출력을 비공개 웹 페이지로 게시하는 [Artifact](/docs/ko/artifacts) 도구를 끕니다. `/config`에서 **Artifacts** 행을 끄면 Claude Code는 이 키를 사용자 설정에 작성하므로 일반적으로 수동으로 편집하지 않습니다. Claude Code v2.1.196 이상이 필요합니다.5776[Artifact](/docs/ko/artifacts) 도구를 끕니다. 이 도구는 세션 출력을 claude.ai의 비공개 웹 페이지로 게시합니다. `/config`에서 **Artifacts** 행을 끄면 Claude Code는 이 키를 사용자 설정에 기록하므로 일반적으로 수동으로 편집할 필요가 없습니다. Claude Code v2.1.196 이상이 필요합니다.

5730 5777

5731* **범위**: [`Any file`](#scopes). 모든 파일이 도구를 끌 수 있으며, 아무도 이를 다시 켤 수 없습니다.5778* **범위**: [`Any file`](#scopes). 모든 파일이 도구를 끌 수 있으며, 어떤 파일도 이를 다시 켤 수 없습니다.

5732* **유형**: Boolean5779* **유형**: Boolean

5733 * `false`: Claude Code는 파일이 적용되는 모든 세션에 대해 Artifact 도구를 끕니다5780 * `false`: Claude Code는 파일이 적용되는 모든 세션에 대해 Artifact 도구를 끕니다

5734 * `true`: 키를 설정하지 않은 것과 동일합니다. 다른 파일의 `false`, [`CLAUDE_CODE_DISABLE_ARTIFACT`](/docs/ko/env-vars) 또는 조직의 [관리 설정](/docs/ko/artifacts#manage-artifacts-for-your-organization)을 재정의하지 않기 때문입니다5781 * `true`: 다른 파일의 `false`, [`CLAUDE_CODE_DISABLE_ARTIFACT`](/docs/ko/env-vars) 또는 조직의 [관리 설정](/docs/ko/artifacts#manage-artifacts-for-your-organization)을 재정의하지 않으므로 키를 설정하지 않은 것과 같습니다

5735* **기본값**: 설정되지 않음, 따라서 도구는 계정의 [가용성](/docs/ko/artifacts#availability)을 따릅니다5782* **기본값**: 설정되지 않음, 따라서 도구는 계정의 [가용성](/docs/ko/artifacts#availability)을 따릅니다

5736 5783

5737```json settings.json theme={null}5784```json settings.json theme={null}

5740}5787}

5741```5788```

5742 5789

5743사용자 설정 이외의 소스가 도구를 끄고 있는 동안 Claude Code는 `/config`에서 **Artifacts** 행을 숨깁니다. 거기서 이를 켜도 아무것도 변경되지 않기 때문입니다. [아티팩트 비활성화](/docs/ko/artifacts#disable-artifacts)는 도구를 끄는 모든 방법을 나열합니다. v2.1.242 이전에는 Claude Code가 프로젝트 및 로컬 설정에서 이 키를 무시했으며, [우선순위 스택](/docs/ko/settings#settings-precedence)에서 더 높은 파일이 낮은 파일의 끔을 다시 켤 수 있었습니다.5790사용자 설정 이외의 소스가 도구를 끄고 있는 동안 Claude Code는 `/config`에서 **Artifacts** 행을 숨깁니다. 이는 거기서 이를 켜도 아무것도 변경되지 않기 때문입니다. [아티팩트 비활성화](/docs/ko/artifacts#disable-artifacts)는 도구를 끄는 모든 방법을 나열합니다.

5744 5791

5745<h3 id="inputneedednotifenabled">5792<h3 id="inputneedednotifenabled">

5746 `inputNeededNotifEnabled`5793 `inputNeededNotifEnabled`

5747</h3>5794</h3>

5748 5795

5749권한 프롬프트 또는 질문이 입력을 기다리고 있을 때 휴대폰에서 푸시 알림을 받습니다. Claude Code는 [Remote Control](/docs/ko/remote-control)이 연결되어 있을 때만 이를 보냅니다. `/config`에서 **작업 필요 시 푸시**로 표시됩니다.5796권한 프롬프트 또는 질문이 입력을 기다리고 있을 때 휴대폰에서 푸시 알림을 받습니다. Claude Code는 [Remote Control](/docs/ko/remote-control)이 연결되어 있을 때만 이러한 알림을 보냅니다. `/config`에서 **작업 필요 시 푸시**로 표시됩니다.

5750 5797

5751* **범위**: [`Any file`](#scopes). Claude Code는 이전 버전에서 `~/.claude.json`에 남겨진 값도 읽습니다.5798* **범위**: [`Any file`](#scopes). Claude Code는 이전 버전에서 `~/.claude.json`에 남겨진 값도 읽습니다.

5752* **유형**: Boolean5799* **유형**: Boolean

5766 `preferredNotifChannel`5813 `preferredNotifChannel`

5767</h3>5814</h3>

5768 5815

5769작업이 완료되거나 권한 프롬프트가 대기 중일 때 Claude Code가 알림을 보내는 방식을 선택합니다. `/config`에서 **로컬 알림**으로 표시됩니다.5816작업이 완료되거나 권한 프롬프트가 대기 중일 때 Claude Code가 사용자에게 알리는 방식을 선택합니다. `/config`에서 **로컬 알림**으로 표시됩니다.

5770 5817

5771* **범위**: [`Any file`](#scopes). Claude Code는 이전 버전에서 `~/.claude.json`에 남겨진 값도 읽습니다.5818* **범위**: [`Any file`](#scopes). Claude Code는 이전 버전에서 `~/.claude.json`에 남겨진 값도 읽습니다.

5772* **유형**: 문자열, 다음 중 하나:5819* **유형**: 문자열, 다음 중 하나:

5785}5832}

5786```5833```

5787 5834

5788`"auto"`를 사용하면 Claude Code는 iTerm2, Ghostty 및 Kitty에서 데스크톱 알림을 보냅니다. Terminal.app에서는 Terminal의 감지 가능한 벨을 끄면 벨 문자를 울리고, 다른 터미널에서는 아무것도 하지 않습니다. 모든 터미널에서 벨 문자를 울리려면 `"terminal_bell"`을 설정합니다. [터미널 벨 또는 알림 받기](/docs/ko/terminal-config#get-a-terminal-bell-or-notification)를 참조하세요.5835`"auto"`를 사용하면 Claude Code는 iTerm2, Ghostty 및 Kitty에서 데스크톱 알림을 보냅니다. Terminal.app에서는 Terminal의 감지 가능한 벨을 끈 경우에만 벨 문자를 울리고, 다른 터미널에서는 아무것도 하지 않습니다. 모든 터미널에서 벨 문자를 울리려면 `"terminal_bell"`을 설정합니다. [터미널 벨 또는 알림 받기](/docs/ko/terminal-config#get-a-terminal-bell-or-notification)를 참조하세요.

5789 5836

5790<h3 id="remote-defaultenvironmentid">5837<h3 id="remote-defaultenvironmentid">

5791 `remote.defaultEnvironmentId`5838 `remote.defaultEnvironmentId`

5792</h3>5839</h3>

5793 5840

5794`claude --cloud`와 같이 CLI에서 만드는 클라우드 세션에 대한 기본 [클라우드 환경](/docs/ko/cloud-environments)을 선택합니다. Claude Code는 [`/remote-env`](/docs/ko/cloud-environments#select-an-environment-from-the-cli)로 환경을 선택할 때 이 키를 사용자 설정에 작성합니다.5841CLI에서 만드는 클라우드 세션(예: `claude --cloud`)에 대한 기본 [클라우드 환경](/docs/ko/cloud-environments)을 선택합니다. Claude Code는 [`/remote-env`](/docs/ko/cloud-environments#select-an-environment-from-the-cli)로 환경을 선택할 때 이 키를 사용자 설정에 기록합니다.

5795 5842

5796* **범위**: [`Any file`](#scopes). 자체 호스팅 환경 ID의 경우 사용자 또는 관리되는 설정 또는 `--settings` 플래그만 해당합니다.5843* **범위**: [`Any file`](#scopes). 자체 호스팅 환경 ID의 경우 사용자 또는 관리 설정 또는 `--settings` 플래그만 해당합니다.

5797* **유형**: 문자열, `env_...` 또는 `ccpool_...`과 같은 환경 ID5844* **유형**: 문자열, `env_...` 또는 `ccpool_...`과 같은 환경 ID

5798* **기본값**: 설정되지 않음, 따라서 Claude Code는 목록에 Anthropic 호스팅 환경이 있으면 이를 사용하고, 그렇지 않으면 [Remote Control 브리지 환경](/docs/ko/cloud-environments#the-default-environment)이 아닌 목록의 첫 번째 환경을 사용하거나, 모든 환경이 브리지 환경일 때 첫 번째 환경을 사용합니다5845* **기본값**: 설정되지 않음, 따라서 Claude Code는 목록에 Anthropic 호스팅 환경이 있으면 이를 사용하고, 그렇지 않으면 [Remote Control 브리지 환경](/docs/ko/cloud-environments#the-default-environment)이 아닌 목록의 첫 번째 환경을 사용하거나, 모든 환경이 브리지 환경인 경우 첫 번째 환경을 사용합니다

5799* **세션별 재정의**: `--environment`는 생성하는 하나의 클라우드 세션에 대해 이 키보다 우선합니다5846* **세션별 재정의**: `--environment`는 생성하는 하나의 클라우드 세션에 대해 이 키보다 우선합니다

5800 5847

5801```json settings.json theme={null}5848```json settings.json theme={null}

5806}5853}

5807```5854```

5808 5855

5809`env_`로 시작하는 Anthropic 호스팅 환경 ID는 표준 설정 우선순위를 따르므로 저장소의 프로젝트 설정의 값이 사용자 수준 선택을 재정의합니다. `ccpool_`로 시작하는 [자체 호스팅 환경](/docs/ko/self-hosted-environments) ID는 사용자 설정, 관리되는 설정 및 `--settings` 플래그에서만 인정됩니다. Claude Code는 저장소의 프로젝트 또는 로컬 설정에서 이를 무시하며, `/remote-env`는 무시한 값을 표시하므로 체크인된 파일이 선택하지 않은 자체 호스팅 환경으로 세션을 조종할 수 없습니다.5856`env_`로 시작하는 Anthropic 호스팅 환경 ID는 표준 설정 우선순위를 따르므로 리포지토리의 프로젝트 설정의 값이 사용자 수준 선택을 재정의합니다. `ccpool_`로 시작하는 [자체 호스팅 환경](/docs/ko/self-hosted-environments) ID는 사용자 설정, 관리 설정 및 `--settings` 플래그에서만 인정됩니다. Claude Code는 리포지토리의 프로젝트 또는 로컬 설정에서 이를 무시하며, `/remote-env`는 무시한 값을 표시하므로 체크인된 파일이 선택하지 않은 자체 호스팅 환경으로 세션을 유도할 수 없습니다.

5810 5857

5811<h3 id="remotecontrolatstartup">5858<h3 id="remotecontrolatstartup">

5812 `remoteControlAtStartup`5859 `remoteControlAtStartup`

5813</h3>5860</h3>

5814 5861

5815각 대화형 세션이 시작될 때 [Remote Control](/docs/ko/remote-control)을 자동으로 연결합니다. `/remote-control`을 기다리는 대신입니다. `true`로 설정하여 자동 연결을 켜거나 `false`로 설정하여 끕니다. `/config`에서 **모든 세션에 대해 Remote Control 활성화**로 표시됩니다.5862각 대화형 세션이 시작될 때 [Remote Control](/docs/ko/remote-control)을 자동으로 연결합니다. `/remote-control`을 기다리는 대신 `true`로 설정하여 자동 연결을 켜거나 `false`로 설정하여 끕니다. `/config`에서 **모든 세션에 대해 Remote Control 활성화**로 표시됩니다.

5816 5863

5817* **범위**: [`Any file`](#scopes). Claude Code는 이전 버전에서 `~/.claude.json`에 남겨진 값도 읽습니다.5864* **범위**: [`Any file`](#scopes). Claude Code는 이전 버전에서 `~/.claude.json`에 남겨진 값도 읽습니다.

5818* **유형**: Boolean5865* **유형**: Boolean

5819 * `true`: Claude Code는 각 대화형 세션이 시작될 때 Remote Control을 자동으로 연결합니다5866 * `true`: Claude Code는 각 대화형 세션이 시작될 때 Remote Control을 자동으로 연결합니다

5820 * `false`: Claude Code는 `/remote-control`을 기다립니다5867 * `false`: Claude Code는 `/remote-control`을 기다립니다

5821* **기본값**: 설정되지 않음, 따라서 [자동 연결 기본값](/docs/ko/remote-control#enable-remote-control-for-all-sessions)이 적용됩니다5868* **기본값**: 설정되지 않음, 따라서 [자동 연결 기본값](/docs/ko/remote-control#enable-remote-control-for-all-sessions)이 적용됩니다

5822* **세션별 재정의**: `--remote-control`은 이 키가 `false`일 때도 한 세션에 대해 Remote Control을 켜고, 플래그는 한 세션에 대해 이를 끌 수 없습니다5869* **세션별 재정의**: `--remote-control`은 이 키가 `false`일 때도 한 세션에 대해 Remote Control을 켜고, 어떤 플래그도 한 세션에 대해 이를 끌 수 없습니다

5823 5870

5824```json settings.json theme={null}5871```json settings.json theme={null}

5825{5872{

5827}5874}

5828```5875```

5829 5876

5830Claude Code는 프로젝트 또는 로컬 설정의 `true`를 무시하므로 저장소는 체크아웃에 대해 자동 연결을 끌 수 있지만 켤 수 없습니다. 전체 범위별 동작은 [모든 세션에 대해 Remote Control 활성화](/docs/ko/remote-control#enable-remote-control-for-all-sessions) 및 [더 엄격한 값이 적용되는 보안 키](/docs/ko/settings#security-keys-where-the-stricter-value-applies)를 참조하세요.5877Claude Code는 프로젝트 또는 로컬 설정의 `true`를 무시하므로 리포지토리는 체크아웃에 대해 자동 연결을 끌 수 있지만 켤 수는 없습니다. 전체 범위별 동작은 [모든 세션에 대해 Remote Control 활성화](/docs/ko/remote-control#enable-remote-control-for-all-sessions) 및 [더 엄격한 값이 적용되는 보안 키](/docs/ko/settings#security-keys-where-the-stricter-value-applies)를 참조하세요.

5831 5878

5832<h3 id="sshconfigs">5879<h3 id="sshconfigs">

5833 `sshConfigs`5880 `sshConfigs`

5834</h3>5881</h3>

5835 5882

5836[Desktop](/docs/ko/desktop#pre-configure-ssh-connections-for-your-team) 환경 드롭다운에 SSH 연결을 추가합니다. 관리자는 이를 사용하여 팀에 공유 연결을 배포합니다. 관리되는 설정에서 정의한 연결은 관리됨으로 표시되므로 사용자는 이를 선택할 수 있지만 앱에서 편집하거나 삭제할 수 없습니다.5883[Desktop](/docs/ko/desktop#pre-configure-ssh-connections-for-your-team) 환경 드롭다운에 SSH 연결을 추가합니다. 관리자는 이를 사용하여 팀에 공유 연결을 배포합니다. 관리 설정에서 정의한 연결은 관리됨으로 표시되므로 사용자는 이를 선택할 수 있지만 앱에서 편집하거나 삭제할 수 없습니다.

5837 5884

5838* **범위**: [`User or managed`](#scopes). 데스크톱 앱은 이 키를 읽습니다.5885* **범위**: [`User or managed`](#scopes). 데스크톱 앱은 이 키를 읽습니다.

5839* **유형**: 필수 `id`, `name` 및 `sshHost`와 선택적 `sshPort` 및 `sshIdentityFile`을 포함하는 객체 배열5886* **유형**: 필수 `id`, `name` 및 `sshHost`와 선택적 `sshPort` 및 `sshIdentityFile`을 포함하는 객체 배열

5857 `sshHostAllowlist`5904 `sshHostAllowlist`

5858</h3>5905</h3>

5859 5906

5860[Desktop SSH 세션](/docs/ko/desktop#restrict-which-ssh-hosts-users-can-connect-to)이 연결할 수 있는 호스트를 제한합니다. Desktop 앱만 이 키를 읽습니다. CLI는 읽지 않습니다. 패턴은 대소문자를 구분하지 않습니다: `*`는 모든 호스트와 일치하고, `*.example.com`은 `example.com` 및 모든 하위 도메인과 일치하며, 다른 모든 것은 `~/.ssh/config` 해석 후 호스트 이름과 정확히 일치합니다. 빈 배열은 SSH 세션을 끕니다.5907[Desktop SSH 세션](/docs/ko/desktop#restrict-which-ssh-hosts-users-can-connect-to)이 연결할 수 있는 호스트를 제한합니다. Desktop 앱만 이 키를 읽습니다. CLI는 읽지 않습니다. 패턴은 대소문자를 구분하지 않습니다: `*`는 모든 호스트와 일치하고, `*.example.com`은 `example.com` 및 모든 하위 도메인과 일치하며, 다른 것은 `~/.ssh/config` 해석 후 호스트 이름과 정확히 일치합니다. 빈 배열은 SSH 세션을 끕니다.

5861 5908

5862* **범위**: [`Managed`](#scopes)5909* **범위**: [`Managed`](#scopes)

5863* **유형**: 호스트 이름 패턴 배열5910* **유형**: 호스트 이름 패턴 배열

5864* **기본값**: 설정되지 않음, 따라서 모든 호스트가 허용됩니다5911* **기본값**: 설정되지 않음, 따라서 모든 호스트가 허용됩니다

5865 5912

5866이 예제는 `devboxes.example.com` 및 해당 하위 도메인과 정확한 호스트 `bastion.example.com`을 허용합니다:5913이 예제는 `devboxes.example.com` 및 해당 하위 도메인, 그리고 정확한 호스트 `bastion.example.com`을 허용합니다:

5867 5914

5868```json managed-settings.json theme={null}5915```json managed-settings.json theme={null}

5869{5916{

5879 5926

5880도우미 스크립트를 통해 자격 증명을 제공하고, 조직의 경우 로그인 방법이나 조직을 강제합니다. [인증](/docs/ko/authentication)을 참조하세요.5927도우미 스크립트를 통해 자격 증명을 제공하고, 조직의 경우 로그인 방법이나 조직을 강제합니다. [인증](/docs/ko/authentication)을 참조하세요.

5881 5928

5929<h3 id="allowedproviders">

5930 `allowedProviders`

5931</h3>

5932

5933머신이 Claude에 도달할 수 있는 서비스를 나열합니다. 예를 들어 Anthropic API, Amazon Bedrock, 또는 LLM 게이트웨이입니다. 나열되지 않은 공급자의 세션은 시작 시, 로그인 시, API에 다음으로 연락할 때 거부되므로 세션 중간에 나열되지 않은 공급자로 전환하는 것도 거부됩니다. [거부 메시지](/docs/ko/errors#managed-settings-dont-allow-this-api-provider)는 공급자를 선택한 것과 계속하는 단계를 이름 지정합니다. Claude Code v2.1.285 이상이 필요합니다.

5934

5935* **범위**: [`관리됨`](#scopes). 머신 자신의 관리자가 소싱한 목록, MDM 정책 및 관리 설정 파일은 서버 관리 설정도 하나를 전달할 때 계속 적용됩니다: 세션은 두 목록 모두의 공급자만 사용할 수 있으므로 서버 관리 목록은 머신이 허용하는 것을 좁힐 수 있지만 절대 확장할 수 없습니다. 어느 머신 소스의 `allowedProviders`가 계산되는지는 [Claude Code가 관리 소스를 결합하는 방법](/docs/ko/managed-settings#how-claude-code-combines-managed-sources)을 따릅니다. 서버 관리 설정만을 통해 전달된 목록은 [서버 관리 설정을 가져오는](/docs/ko/server-managed-settings#platform-availability) 세션에만 도달합니다.

5936* **유형**: 문자열 배열, 각각 다음 중 하나:

5937 * `"anthropic"`: Anthropic의 자체 호스트의 Anthropic API, claude.ai 또는 Console 로그인 또는 API 키를 통해. [`forceLoginMethod`](#forceloginmethod) 또는 [`forceLoginOrgUUID`](#forceloginorguuid)와 쌍을 이루어 로그인도 제한합니다.

5938 * `"bedrock"`: [Amazon Bedrock](/docs/ko/amazon-bedrock)

5939 * `"vertex"`: [Google Cloud의 Agent Platform](/docs/ko/google-vertex-ai), 이전의 Vertex AI

5940 * `"foundry"`: [Microsoft Foundry](/docs/ko/microsoft-foundry)

5941 * `"anthropicAws"`: [AWS의 Claude Platform](/docs/ko/claude-platform-on-aws)

5942 * `"mantle"`: Amazon Bedrock [Mantle 엔드포인트](/docs/ko/amazon-bedrock#use-the-mantle-endpoint). [Mantle을 Invoke API와 함께 실행](/docs/ko/amazon-bedrock#run-mantle-alongside-the-invoke-api)하는 세션은 두 공급자를 모두 사용하므로 `"bedrock"`과 `"mantle"`을 함께 나열합니다.

5943 * `"customEndpoint"`: Anthropic API 또는 클라우드 공급자의 API를 다른 호스트로 보냅니다. 예를 들어 `ANTHROPIC_BASE_URL`로 이름 지정된 [LLM 게이트웨이](/docs/ko/llm-gateway), 공급자의 `ANTHROPIC_*_BASE_URL` 변수, 또는 단순 리소스 이름이 아닌 `ANTHROPIC_FOUNDRY_RESOURCE` 값입니다. Claude Code는 관리 [`env`](#env) 블록이 고정한 정확한 값에 대해서만 이를 허용합니다.

5944 * `"gateway"`: [클라우드 게이트웨이](/docs/ko/claude-apps-gateway) 로그인

5945* **기본값**: 설정되지 않음, 따라서 모든 공급자를 사용할 수 있습니다.

5946

5947```json managed-settings.json theme={null}

5948{

5949 "allowedProviders": ["anthropic", "bedrock"]

5950}

5951```

5952

5953각 클라우드 공급자의 항목은 해당 공급자의 자체 서비스를 의미합니다. 지역, FIPS, 및 개인 엔드포인트를 포함합니다.

5954

5955Claude Code가 공급자 이름으로 인식하지 않는 항목은 삭제되고 보고되며, 목록의 나머지는 강제됩니다. 빈 목록이거나 모든 항목이 인식되지 않는 목록의 경우, Claude Code는 모든 공급자를 거부하고 머신에서 시작하지 않습니다.

5956

5957<h4 id="endpoints-that-need-a-pin-in-managed-env">

5958 관리 `env`에서 핀이 필요한 엔드포인트

5959</h4>

5960

5961핀은 관리 [`env`](#env) 블록에 설정된 엔드포인트 변수의 값입니다. 세션이 공급자의 트래픽을 해당 공급자의 자체 서비스 이외의 곳으로 보낼 때, Claude Code는 세션의 값이 핀과 동일한 경우에만 이를 허용합니다. 이러한 엔드포인트에는 하나가 필요합니다:

5962

5963* **`"customEndpoint"` 세션**: 호스트를 이름 지정하는 변수, 예를 들어 `ANTHROPIC_BASE_URL`

5964* **Amazon Bedrock**: AWS SDK의 `AWS_ENDPOINT_URL`, `AWS_ENDPOINT_URL_BEDROCK`, 및 `AWS_ENDPOINT_URL_BEDROCK_RUNTIME` 변수는 Bedrock의 자체 서비스 외부를 가리킬 때입니다. 세션은 `"customEndpoint"` 대신 `"bedrock"` 아래에 머물러 있습니다.

5965* **게이트웨이 로그인의 URL**: 세션은 `"gateway"` 아래에 머물러 있으며, [`forceLoginGatewayUrl`](#forcelogingatewayurl)도 핀으로 계산됩니다.

5966

5967어느 `env` 블록이 핀으로 계산되는지는 목록이 설정된 위치에 따라 다릅니다:

5968

5969* **머신의 관리자 소스가 목록을 설정합니다**: 머신의 자체 관리자 소스의 `env` 블록만 계산됩니다.

5970* **서버 관리 설정만 목록을 설정합니다**: 해당 서버 관리 설정의 `env` 값도 계산됩니다.

5971

5972목록은 클라우드 공급자의 자격 증명 및 테넌시 변수 또는 `HTTPS_PROXY` 및 인증서 설정과 같은 네트워크 경로를 판단하지 않습니다. 관리 `env` 블록에서 플릿에 대해 이를 설정합니다.

5973

5882<h3 id="apikeyhelper">5974<h3 id="apikeyhelper">

5883 `apiKeyHelper`5975 `apiKeyHelper`

5884</h3>5976</h3>

6401| :- | :- | :- |6493| :- | :- | :- |

6402| 목록 | 모든 소스의 항목을 결합합니다. | [`permissions.allow`](#permissions-allow), [`sandbox.network.allowedDomains`](#sandbox-network-alloweddomains) 및 기타 목록 키 |6494| 목록 | 모든 소스의 항목을 결합합니다. | [`permissions.allow`](#permissions-allow), [`sandbox.network.allowedDomains`](#sandbox-network-alloweddomains) 및 기타 목록 키 |

6403| 잠금 | 모든 소스가 설정하는 가장 엄격한 값을 적용합니다. 어떤 소스도 엄격한 값을 설정하지 않으면 최우선 소스에서만 더 느슨한 값을 적용합니다. | [`allowManagedPermissionRulesOnly`](#allowmanagedpermissionrulesonly), [`permissions.disableBypassPermissionsMode`](#permissions-disablebypasspermissionsmode) 및 기타 boolean 또는 enum 잠금 |6495| 잠금 | 모든 소스가 설정하는 가장 엄격한 값을 적용합니다. 어떤 소스도 엄격한 값을 설정하지 않으면 최우선 소스에서만 더 느슨한 값을 적용합니다. | [`allowManagedPermissionRulesOnly`](#allowmanagedpermissionrulesonly), [`permissions.disableBypassPermissionsMode`](#permissions-disablebypasspermissionsmode) 및 기타 boolean 또는 enum 잠금 |

6404| 제한 허용 목록 | 하위 소스의 항목을 추가하지 않고 설정하는 최우선 소스에서 목록 전체를 가져옵니다. 최우선 소스가 설정하지 않으면 다음 소스에서 전체를 가져옵니다. | [`availableModels`](#availablemodels), [`allowedMcpServers`](#allowedmcpservers), [`strictKnownMarketplaces`](#strictknownmarketplaces), [`allowedChannelPlugins`](#allowedchannelplugins) 및 [`fallbackModel`](#fallbackmodel) 체인 |6496| 제한 허용 목록 | 하위 소스의 항목을 추가하지 않고 설정하는 최우선 소스에서 목록 전체를 가져옵니다. 최우선 소스가 설정하지 않으면 다음 소스에서 전체를 가져옵니다. | [`availableModels`](#availablemodels), [`allowedMcpServers`](#allowedmcpservers), [`allowedProviders`](#allowedproviders), [`strictKnownMarketplaces`](#strictknownmarketplaces), [`allowedChannelPlugins`](#allowedchannelplugins) 및 [`fallbackModel`](#fallbackmodel) 체인 |

6405| 값 전체 | 하위 소스의 항목이나 필드를 결합하지 않고 설정하는 최우선 소스에서 값 전체를 가져옵니다. 최우선 소스가 설정하지 않으면 다음 소스에서 전체를 가져옵니다. | [`sandbox.credentials.awsPairs`](#sandbox-credentials-awspairs), [`sandbox.ripgrep`](#sandbox-ripgrep) |6497| 값 전체 | 하위 소스의 항목이나 필드를 결합하지 않고 설정하는 최우선 소스에서 값 전체를 가져옵니다. 최우선 소스가 설정하지 않으면 다음 소스에서 전체를 가져옵니다. | [`sandbox.credentials.awsPairs`](#sandbox-credentials-awspairs), [`sandbox.ripgrep`](#sandbox-ripgrep) |

6407| 최우선 소스에서만 읽기 | 정책 키를 전달하는 최우선 소스에서만 키를 읽으므로, 최우선 소스가 설정하지 않을 때에도 하위 소스의 값은 무시됩니다. | [`apiKeyHelper`](#apikeyhelper), [`awsAuthRefresh`](#awsauthrefresh), [`awsCredentialExport`](#awscredentialexport), [`gcpAuthRefresh`](#gcpauthrefresh), [`otelHeadersHelper`](#otelheadershelper), `proxyAuthHelper`, [`forceLoginOrgUUID`](#forceloginorguuid), [`forceLoginMethod`](#forceloginmethod)의 `"claudeai"` 및 `"console"` 값, [`parentSettingsBehavior`](#parentsettingsbehavior), [`modelPicker`](#modelpicker), [`policyHelper`](#policyhelper), [`permissions.defaultMode`](#permissions-defaultmode) |6499| 최우선 소스에서만 읽기 | 정책 키를 전달하는 최우선 소스에서만 키를 읽으므로, 최우선 소스가 설정하지 않을 때에도 하위 소스의 값은 무시됩니다. | [`apiKeyHelper`](#apikeyhelper), [`awsAuthRefresh`](#awsauthrefresh), [`awsCredentialExport`](#awscredentialexport), [`gcpAuthRefresh`](#gcpauthrefresh), [`otelHeadersHelper`](#otelheadershelper), `proxyAuthHelper`, [`forceLoginOrgUUID`](#forceloginorguuid), [`forceLoginMethod`](#forceloginmethod)의 `"claudeai"` 및 `"console"` 값, [`parentSettingsBehavior`](#parentsettingsbehavior), [`modelPicker`](#modelpicker), [`policyHelper`](#policyhelper), [`permissions.defaultMode`](#permissions-defaultmode) |

6415* **[`policyHelper`](#policyhelper)**: Claude Code는 정책 키를 전달하는 최우선 소스가 MDM 정책 또는 관리형 설정 파일일 때만 인정하므로, 서버 관리형 설정에서는 적용되지 않습니다.6507* **[`policyHelper`](#policyhelper)**: Claude Code는 정책 키를 전달하는 최우선 소스가 MDM 정책 또는 관리형 설정 파일일 때만 인정하므로, 서버 관리형 설정에서는 적용되지 않습니다.

6416* **[`modelOverrides`](#modeloverrides)**: `availableModels`와 쌍을 이룹니다. Claude Code는 설정하는 최우선 소스에서 `modelOverrides`를 가져옵니다. 단, 상위 소스가 `modelOverrides` 없이 `availableModels`를 설정하는 경우는 제외됩니다. 이 경우 모든 소스에서 `modelOverrides`를 무시합니다.6508* **[`modelOverrides`](#modeloverrides)**: `availableModels`와 쌍을 이룹니다. Claude Code는 설정하는 최우선 소스에서 `modelOverrides`를 가져옵니다. 단, 상위 소스가 `modelOverrides` 없이 `availableModels`를 설정하는 경우는 제외됩니다. 이 경우 모든 소스에서 `modelOverrides`를 무시합니다.

6417* **[`forceLoginGatewayUrl`](#forcelogingatewayurl), [`gatewayInternalNetworks`](#gatewayinternalnetworks) 및 [`forceLoginMethod`](#forceloginmethod)의 `"gateway"` 값**: Claude Code는 서버 관리형 설정에서 이들 중 어느 것도 읽지 않으므로, 거기의 값은 MDM 정책 또는 관리형 설정 파일에 설정된 값을 적용하거나 숨기지 않습니다. 머신의 관리자 소스 중에서 정책 키를 전달하는 최우선 순위 소스만 서버 관리형 설정도 있는지 여부와 관계없이 이들을 제공합니다.6509* **[`forceLoginGatewayUrl`](#forcelogingatewayurl), [`gatewayInternalNetworks`](#gatewayinternalnetworks) 및 [`forceLoginMethod`](#forceloginmethod)의 `"gateway"` 값**: Claude Code는 서버 관리형 설정에서 이들 중 어느 것도 읽지 않으므로, 거기의 값은 MDM 정책 또는 관리형 설정 파일에 설정된 값을 적용하거나 숨기지 않습니다. 머신의 관리자 소스 중에서 정책 키를 전달하는 최우선 순위 소스만 서버 관리형 설정도 있는지 여부와 관계없이 이들을 제공합니다.

6510* **[`allowedProviders`](#allowedproviders)**: 표의 규칙 이후에도 머신 자체의 목록이 결과를 제한하며, 해당 항목의 범위 참고 사항에 명시되어 있습니다.

6418 6511

6419머신에서 결합된 소스를 확인하려면 `/status`를 실행하고 [`Setting sources` 행을 읽으세요](/docs/ko/managed-settings#read-the-source-in-/status).6512머신에서 결합된 소스를 확인하려면 `/status`를 실행하고 [`Setting sources` 행을 읽으세요](/docs/ko/managed-settings#read-the-source-in-/status).

6420 6513

third-party-integrations.md +2 −0

Details

253 253

254보안 팀은 Claude Code가 수행할 수 있고 수행할 수 없는 작업에 대한 관리형 권한을 구성할 수 있으며, 이는 로컬 구성으로 덮어쓸 수 없습니다. [자세히 알아봅니다](/docs/ko/security).254보안 팀은 Claude Code가 수행할 수 있고 수행할 수 없는 작업에 대한 관리형 권한을 구성할 수 있으며, 이는 로컬 구성으로 덮어쓸 수 없습니다. [자세히 알아봅니다](/docs/ko/security).

255 255

256배포 옵션 중 관리형 머신이 사용할 수 있는 옵션을 제한하려면 관리형 설정에서 [`allowedProviders`](/docs/ko/settings-reference#allowedproviders)를 설정합니다. 예를 들어 `["bedrock"]`은 Amazon Bedrock만 허용하고 다른 것은 허용하지 않습니다. Mantle 엔드포인트도 활성화하는 Bedrock 플릿은 `"mantle"`도 나열합니다. 항목은 어떤 엔드포인트 변수도 관리형 `env` 핀이 필요한지를 나타냅니다. Claude Code v2.1.285 이상이 필요합니다.

257

256<h3 id="leverage-mcp-for-integrations">258<h3 id="leverage-mcp-for-integrations">

257 MCP를 통합에 활용259 MCP를 통합에 활용

258</h3>260</h3>

tools-reference.md +30 −5

Details

172* `BASH_DEFAULT_TIMEOUT_MS` — Claude가 타임아웃을 전달하지 않을 때의 기본값입니다. 기본값은 2분입니다.172* `BASH_DEFAULT_TIMEOUT_MS` — Claude가 타임아웃을 전달하지 않을 때의 기본값입니다. 기본값은 2분입니다.

173* `BASH_MAX_TIMEOUT_MS` — 기본값으로, Claude가 요청하는 것을 제한하는 상한을 설정합니다. 유효한 상한은 둘 중 더 큰 값이며, 기본값은 10분입니다.173* `BASH_MAX_TIMEOUT_MS` — 기본값으로, Claude가 요청하는 것을 제한하는 상한을 설정합니다. 유효한 상한은 둘 중 더 큰 값이며, 기본값은 10분입니다.

174 174

175Claude가 백그라운드에서 시작하는 명령의 경우, `timeout`은 대신 명령이 거기서 실행될 수 있는 기간을 설정하며, [백그라운드 명령](#background-commands) 아래에 설명된 별도의 기본값과 최대값이 있습니다. [PowerShell 도구](#powershell-tool)는 동일한 타임아웃 규칙을 따르고 동일한 두 변수를 읽습니다.175Claude가 백그라운드에서 시작하는 명령의 경우, `timeout`은 대신 명령이 거기서 실행될 수 있는 기간을 설정하며, [백그라운드 명령의 시간 제한](#time-limit-for-background-commands) 아래에 설명된 별도의 기본값과 최대값이 있습니다. [PowerShell 도구](#powershell-tool)는 동일한 타임아웃 규칙을 따르고 동일한 두 변수를 읽습니다.

176 176

177<h4 id="output-limits">177<h4 id="output-limits">

178 출력 제한178 출력 제한

197 197

198개발 서버 또는 감시 빌드와 같은 장기 실행 프로세스의 경우, Claude는 `run_in_background: true`를 설정하여 명령을 백그라운드 작업으로 시작하고 실행 중인 동안 계속 작업할 수 있습니다. `/tasks`로 백그라운드 작업을 나열하고 중지합니다. 거기서 또는 데스크톱 앱과 같은 연결된 클라이언트에서 중지한 후, Claude는 대기하지 않고 계속 진행합니다. 서브에이전트가 명령을 시작한 경우, 해당 서브에이전트가 계속 진행합니다.198개발 서버 또는 감시 빌드와 같은 장기 실행 프로세스의 경우, Claude는 `run_in_background: true`를 설정하여 명령을 백그라운드 작업으로 시작하고 실행 중인 동안 계속 작업할 수 있습니다. `/tasks`로 백그라운드 작업을 나열하고 중지합니다. 거기서 또는 데스크톱 앱과 같은 연결된 클라이언트에서 중지한 후, Claude는 대기하지 않고 계속 진행합니다. 서브에이전트가 명령을 시작한 경우, 해당 서브에이전트가 계속 진행합니다.

199 199

200[포그라운드 서브에이전트](/docs/ko/sub-agents#run-subagents-in-foreground-or-background)가 시작한 명령은 해당 서브에이전트의 실행이 끝날 때 중지됩니다. 완료되었든, 실패했든, 또는 중단되었든 상관없습니다. 주 대화 또는 백그라운드 서브에이전트가 시작한 명령은 최종 응답 후에도 계속 실행되며, 종료되거나, 중지되거나, 시간 제한에 도달할 때까지 계속됩니다. `-p` 플래그가 있는 비대화형 모드에서, [백그라운드 명령은 실행의 최종 결과 직후에 종료됩니다](/docs/ko/headless#background-tasks-at-exit).200<h4 id="when-a-background-command-stops">

201 백그라운드 명령이 중지될 때

202</h4>

203

204[포그라운드 서브에이전트](/docs/ko/sub-agents#run-subagents-in-foreground-or-background)가 시작한 명령은 해당 서브에이전트의 실행이 끝날 때 중지됩니다. 완료되었든, 실패했든, 또는 중단되었든 상관없습니다. 주 대화 또는 백그라운드 서브에이전트가 시작한 명령은 최종 응답 후에도 계속 실행되며, 종료되거나, 중지되거나, [시간 제한](#time-limit-for-background-commands)에 도달할 때까지 계속됩니다. `-p` 플래그가 있는 비대화형 모드에서, [백그라운드 명령은 실행의 최종 결과 직후에 종료됩니다](/docs/ko/headless#background-tasks-at-exit).

205

206<h4 id="time-limit-for-background-commands">

207 백그라운드 명령의 시간 제한

208</h4>

201 209

202Bash 및 PowerShell 백그라운드 명령에는 시간 제한이 있으며, 명령이 백그라운드에 진입하는 순간부터 계산됩니다:210Bash 및 PowerShell 백그라운드 명령에는 시간 제한이 있으며, 명령이 백그라운드에 진입하는 순간부터 계산됩니다:

203 211

204* Claude가 백그라운드에서 시작하는 명령은 30분 또는 `run_in_background`로 전달하는 `timeout`을 받으며, 최대 2시간입니다.212* Claude가 백그라운드에서 시작하는 명령은 30분 또는 `run_in_background`로 전달하는 `timeout`을 받으며, 최대 2시간입니다.

205* 포그라운드에서 시작한 후 백그라운드로 이동하는 명령(예: `Ctrl+B` 또는 타임아웃 시)은 이동 시점부터 30분을 받습니다.213* 포그라운드에서 시작한 후 백그라운드로 이동하는 명령(예: `Ctrl+B` 또는 타임아웃 시)은 이동 시점부터 30분을 받습니다.

206 214

215백그라운드 명령이 시간 제한에 도달하면, Claude Code는 이를 중지하고 Claude에 이유를 알립니다. Claude는 작업이 여전히 필요하면 더 긴 `timeout`으로 명령을 다시 시작할 수 있습니다. 중지 알림은 `Background command "<description>" was stopped after reaching its background time limit`를 읽습니다.

216

217<h4 id="raise-the-time-limit-for-background-commands">

218 백그라운드 명령의 시간 제한 높이기

219</h4>

220

207두 개의 [환경 변수](/docs/ko/env-vars)는 Bash 및 PowerShell 명령 모두에 대해 이러한 제한을 높입니다. 둘 다 밀리초를 사용하며, 어느 것도 제한을 단축할 수 없습니다. 더 낮은 값은 30분 기본값과 2시간 최대값을 그대로 둡니다.221두 개의 [환경 변수](/docs/ko/env-vars)는 Bash 및 PowerShell 명령 모두에 대해 이러한 제한을 높입니다. 둘 다 밀리초를 사용하며, 어느 것도 제한을 단축할 수 없습니다. 더 낮은 값은 30분 기본값과 2시간 최대값을 그대로 둡니다.

208 222

209* `BASH_DEFAULT_TIMEOUT_MS`를 `1800000` 이상으로 설정하여 30분 기본값을 해당 값으로 바꿉니다. Claude가 `timeout` 없이 시작하는 명령과 이동된 명령 모두에 적용됩니다.223* `BASH_DEFAULT_TIMEOUT_MS`를 `1800000` 이상으로 설정하여 30분 기본값을 해당 값으로 바꿉니다. Claude가 `timeout` 없이 시작하는 명령과 이동된 명령 모두에 적용됩니다.

210* `BASH_MAX_TIMEOUT_MS`를 `7200000` 이상으로 설정하여 2시간 최대값을 해당 값으로 높입니다. `BASH_DEFAULT_TIMEOUT_MS`를 `7200000` 이상으로 설정하면 최대값을 동일한 방식으로 높입니다.224* `BASH_MAX_TIMEOUT_MS`를 `7200000` 이상으로 설정하여 2시간 최대값을 해당 값으로 높입니다. `BASH_DEFAULT_TIMEOUT_MS`를 `7200000` 이상으로 설정하면 최대값을 동일한 방식으로 높입니다.

211 225

212백그라운드 명령이 시간 제한에 도달하면, Claude Code는 이를 중지하고 Claude에 이유를 알립니다. Claude는 작업이 여전히 필요하면 더 긴 `timeout`으로 명령을 다시 시작할 수 있습니다. 중지 알림은 `Background command "<description>" was stopped after reaching its background time limit`를 읽습니다.226<h4 id="foreground-commands-that-move-to-the-background">

227 포그라운드 명령이 백그라운드로 이동

228</h4>

213 229

214포그라운드 명령이 완료되지 않고 타임아웃에 도달하면, Claude Code는 이를 중지하지 않고 백그라운드로 이동합니다. 단, 명령이 `sleep`으로 시작하는 경우는 제외됩니다. 이동된 명령의 시간 제한은 이동 시점부터 계산되며, 포그라운드 서브에이전트의 이동된 명령은 여전히 해당 서브에이전트의 실행이 끝날 때 중지됩니다.230포그라운드 명령이 완료되지 않고 타임아웃에 도달하면, Claude Code는 이를 중지하지 않고 백그라운드로 이동합니다. 단, 명령이 `sleep`으로 시작하는 경우는 제외됩니다. 이동된 명령의 [시간 제한](#time-limit-for-background-commands)은 이동 시점부터 계산되며, 포그라운드 서브에이전트의 이동된 명령은 여전히 해당 서브에이전트의 실행이 끝날 때 중지됩니다.

215 231

216[`CLAUDE_CODE_DISABLE_BACKGROUND_TASKS=1`](/docs/ko/env-vars#variables)을 설정하면 자동 백그라운드 처리 및 나머지 백그라운드 작업 기능을 비활성화합니다.232[`CLAUDE_CODE_DISABLE_BACKGROUND_TASKS=1`](/docs/ko/env-vars#variables)을 설정하면 자동 백그라운드 처리 및 나머지 백그라운드 작업 기능을 비활성화합니다.

217 233

244나열하는 것이 무엇이든, 이러한 규칙이 적용됩니다:260나열하는 것이 무엇이든, 이러한 규칙이 적용됩니다:

245 261

246* **알 수 없는 이름**: Claude Code는 인식하지 못하는 이름을 무시합니다.262* **알 수 없는 이름**: Claude Code는 인식하지 못하는 이름을 무시합니다.

247* **Bash, PowerShell 및 Monitor**: Claude Code는 나열하는 것이 무엇이든 Bash, PowerShell 및 Monitor 도구 명령을 상한 아래에 유지합니다.

248* **변수 설정 해제**: Claude Code는 Anthropic이 서버에서 제공하는 구성에서 다른 제한된 종류의 집합을 가져오며, 해당 집합은 시간이 지남에 따라 변할 수 있으므로, 변경되지 않는 집합이 필요할 때 변수를 설정합니다.263* **변수 설정 해제**: Claude Code는 Anthropic이 서버에서 제공하는 구성에서 다른 제한된 종류의 집합을 가져오며, 해당 집합은 시간이 지남에 따라 변할 수 있으므로, 변경되지 않는 집합이 필요할 때 변수를 설정합니다.

249* **권한 게이팅 훅**: 모든 종류가 제한되더라도, Claude Code는 작업을 차단하거나 결과를 변경할 수 있는 훅과 해당 훅이 호출하는 모든 MCP 서버를 상한에서 제외하므로, 커널이 권한 게이팅 훅을 중단하는 것이 차단하는 작업을 허용할 수 없습니다.264* **권한 게이팅 훅**: 모든 종류가 제한되더라도, Claude Code는 작업을 차단하거나 결과를 변경할 수 있는 훅과 해당 훅이 호출하는 모든 MCP 서버를 상한에서 제외하므로, 커널이 권한 게이팅 훅을 중단하는 것이 차단하는 작업을 허용할 수 없습니다.

250 265

648 663

649샌드박스된 명령은 WebFetch의 사전 승인된 문서 도메인의 기본 제공 집합을 상속하지 않습니다. 샌드박스된 명령이 프롬프트 없이 도메인에 도달하도록 하려면, 도메인을 [`allowedDomains`](/docs/ko/settings-reference#sandbox-network-alloweddomains)에 추가하거나 `WebFetch(domain:...)` 규칙으로 허용하십시오. [샌드박스도 이를 준수합니다](/docs/ko/sandboxing#network-isolation). WebFetch는 반대로 샌드박스 허용 목록을 읽지 않으므로, 샌드박스 또는 조직 네트워크 허용 목록에 도메인을 추가해도 WebFetch가 이에 대해 프롬프트를 표시하는 것을 중단하지 않습니다.664샌드박스된 명령은 WebFetch의 사전 승인된 문서 도메인의 기본 제공 집합을 상속하지 않습니다. 샌드박스된 명령이 프롬프트 없이 도메인에 도달하도록 하려면, 도메인을 [`allowedDomains`](/docs/ko/settings-reference#sandbox-network-alloweddomains)에 추가하거나 `WebFetch(domain:...)` 규칙으로 허용하십시오. [샌드박스도 이를 준수합니다](/docs/ko/sandboxing#network-isolation). WebFetch는 반대로 샌드박스 허용 목록을 읽지 않으므로, 샌드박스 또는 조직 네트워크 허용 목록에 도메인을 추가해도 WebFetch가 이에 대해 프롬프트를 표시하는 것을 중단하지 않습니다.

650 665

666<h3 id="webfetch-availability">

667 WebFetch 가용성

668</h3>

669

670Claude Code v2.1.285 이상에서는 [`CLAUDE_CODE_DISABLE_WEB_FETCH`](/docs/ko/env-vars#variables)를 `1`로 설정하여 WebFetch를 끌 수 있습니다.

671

672Team 또는 Enterprise claude.ai 계정으로 로그인하고 [LLM 게이트웨이](/docs/ko/llm-gateway)를 통해 연결하지 않으면, WebFetch는 또한 조직의 정책에 따라 달라집니다. Claude Code는 세션이 시작될 때 `api.anthropic.com`에서 이 정책을 요청합니다. 다른 앱이 제공한 claude.ai 토큰 아래에서 실행되는 것과 같이 Claude Code가 계획을 결정할 수 없는 세션도 마찬가지입니다.

673

674WebFetch가 세션에서 누락된 경우, 세션에서 `/status`를 실행하십시오. `Organization policy` 줄이 정책이 로드되지 않았으며 웹 가져오기를 기다리는 기능 중 하나로 이름을 지정하면, Claude Code는 조직이 이를 허용하는지 확인할 때까지 WebFetch를 보류합니다. 세션 외부에서 `claude doctor`는 자체 요청을 하고 동일한 줄을 인쇄합니다. WebFetch를 허용하는 정책이 로드되면, 도구는 재시작 없이 반환됩니다.

675

651<h2 id="websearch-tool-behavior">676<h2 id="websearch-tool-behavior">

652 WebSearch 도구 동작677 WebSearch 도구 동작

653</h2>678</h2>

vs-code.md +25 −5

Details

58 58

59 * **활동 표시줄**: 왼쪽 사이드바의 Spark 아이콘을 클릭하여 세션 목록을 엽니다. 세션을 클릭하여 [선호하는 위치](#extension-settings)에서 열거나 새 세션을 시작합니다. 이 아이콘은 항상 활동 표시줄에 표시됩니다.59 * **활동 표시줄**: 왼쪽 사이드바의 Spark 아이콘을 클릭하여 세션 목록을 엽니다. 세션을 클릭하여 [선호하는 위치](#extension-settings)에서 열거나 새 세션을 시작합니다. 이 아이콘은 항상 활동 표시줄에 표시됩니다.

60 * **명령 팔레트**: `Cmd+Shift+P`(Mac) 또는 `Ctrl+Shift+P`(Windows/Linux)를 누르고 "Claude Code"를 입력한 후 "새 탭에서 열기"와 같은 옵션을 선택합니다.60 * **명령 팔레트**: `Cmd+Shift+P`(Mac) 또는 `Ctrl+Shift+P`(Windows/Linux)를 누르고 "Claude Code"를 입력한 후 "새 탭에서 열기"와 같은 옵션을 선택합니다.

61 * **상태 표시줄**: [`preferredLocation`](#extension-settings)을 `sidebar`로 설정했거나 **Claude Code: 사이드 바에서 열기**로 Claude를 열었다면 창의 오른쪽 아래 모서리에서 **✻ Claude Code**를 클릭합니다. 파일을 열지 않았을 때도 작동합니다.61 * **상태 표시줄**: 창의 오른쪽 아래 모서리에서 **✻ Claude Code**를 클릭합니다. 파일을 열지 않았을 때도 작동합니다.

62 62

63 Claude 패널을 드래그하여 VS Code의 어느 곳으로든 재배치할 수 있습니다. 자세한 내용은 [워크플로우 사용자 정의](#customize-your-workflow)를 참조하십시오.63 Claude 패널을 드래그하여 VS Code의 어느 곳으로든 재배치할 수 있습니다. 자세한 내용은 [워크플로우 사용자 정의](#customize-your-workflow)를 참조하십시오.

64 </Step>64 </Step>

362 362

363플러그인 탭에서:363플러그인 탭에서:

364 364

365* **설치된 플러그인**은 상단에 표시되며 토글 스위치로 활성화 또는 비활성화할 수 있습니다365* **설치된 플러그인**은 상단에 표시되며 토글 스위치로 활성화 또는 비활성화할 수 있습니다.

366 * 프로젝트의 공유 `.claude/settings.json`이 켜는 플러그인을 끄면 확장 프로그램이 먼저 묻습니다. **내 것만 비활성화**는 사용자만을 위해 끄고, **모두를 위해 비활성화**는 공유 파일을 변경합니다.

366* **사용 가능한 플러그인**은 구성된 마켓플레이스에서 아래에 표시됩니다367* **사용 가능한 플러그인**은 구성된 마켓플레이스에서 아래에 표시됩니다

367* 이름 또는 설명으로 플러그인을 필터링하려면 검색을 사용합니다368* 이름 또는 설명으로 플러그인을 필터링하려면 검색을 사용합니다

368* 사용 가능한 플러그인에서 **설치**를 클릭합니다369* 사용 가능한 플러그인에서 **설치**를 클릭합니다

373* **이 프로젝트용으로 설치**: 프로젝트 협력자와 공유(프로젝트 범위)374* **이 프로젝트용으로 설치**: 프로젝트 협력자와 공유(프로젝트 범위)

374* **로컬로 설치**: 이 저장소에서만 사용자용(로컬 범위)375* **로컬로 설치**: 이 저장소에서만 사용자용(로컬 범위)

375 376

377설치가 완료되면 아직 설정되지 않은 플러그인의 [구성 옵션](/docs/ko/plugins/components#user-configuration)을 요청하는 양식이 나타납니다. 나중에 옵션을 검토하거나 변경하려면 플러그인 행의 기어 아이콘을 클릭합니다.

378

379민감한 텍스트 필드는 마스킹되며, 이전에 저장한 비밀은 \*\*(변경되지 않음)\*\*으로 표시됩니다. 저장된 값을 유지하려면 필드를 비워 둡니다.

380

381변경 사항을 저장한 후 열려 있는 세션은 플러그인을 다시 로드하고 대화 상자에 **플러그인 변경 사항을 적용하려면 Claude를 다시 시작하세요**가 표시됩니다.

382

383<h3 id="uninstall-plugins">

384 플러그인 제거

385</h3>

386

387각 설치된 행은 설치된 [범위](/docs/ko/plugins/install#choose-an-install-scope)를 나타냅니다. 해당 설치를 제거하려면 행의 휴지통 아이콘을 클릭합니다. 흐린 휴지통 아이콘은 이 작업 공간에서 제거할 수 없는 행(예: 조직에서 관리하는 플러그인 또는 다른 프로젝트용으로 설치된 플러그인)을 표시합니다.

388

389확장 프로그램은 두 가지 경우에 먼저 묻습니다:

390

391* **프로젝트의 공유 `.claude/settings.json`이 켜는 플러그인**: **내 것만 비활성화**를 선택하면 협력자를 위해 플러그인이 설치된 상태로 유지되거나, **모두를 위해 제거**를 선택하면 [`--keep-data`](/docs/ko/plugins/cli-reference#what-an-uninstall-deletes-and-keeps)를 사용하여 프로젝트의 설치를 제거하므로 플러그인의 저장된 데이터 디렉토리가 유지됩니다. 이미 자신을 위해 플러그인을 끈 경우 휴지통 아이콘은 질문 없이 자신의 설치를 제거합니다.

392* **그 외의 경우, 저장된 데이터가 있는 플러그인의 마지막 설치**: 데이터를 유지할지 삭제할지 선택합니다. **유지**가 기본값입니다.

393

376<h3 id="share-a-plugin-install-link">394<h3 id="share-a-plugin-install-link">

377 플러그인 설치 링크 공유395 플러그인 설치 링크 공유

378</h3>396</h3>

407 425

408* GitHub 저장소, URL 또는 로컬 경로를 입력하여 새 마켓플레이스를 추가합니다426* GitHub 저장소, URL 또는 로컬 경로를 입력하여 새 마켓플레이스를 추가합니다

409* 새로고침 아이콘을 클릭하여 마켓플레이스의 플러그인 목록을 업데이트합니다427* 새로고침 아이콘을 클릭하여 마켓플레이스의 플러그인 목록을 업데이트합니다

410* 휴지통 아이콘을 클릭하여 마켓플레이스를 제거합니다428* 휴지통 아이콘을 클릭하여 마켓플레이스를 제거합니다. 이를 제거하면 [이 마켓플레이스에서 설치한 모든 플러그인이 제거되므로](/docs/ko/plugins/install#manage-marketplaces) 확인 메시지에 해당 플러그인이 먼저 나열됩니다.

429

430대화 상자에서 변경한 플러그인 변경 사항은 해당 VS Code 창에서 열려 있는 Claude Code 세션에 즉시 적용됩니다.

411 431

412대화 상자에서 변경한 플러그인 변경 사항은 해당 VS Code 창에서 열려 있는 Claude Code 세션에 즉시 적용됩니다. 대화 상자를 연 세션이 플러그인을 다시 로드할 수 없는 경우 대화 상자에서 다시 시도하거나 해당 세션에서 Claude를 다시 시작하도록 제안합니다.432대화 상자를 연 세션이 플러그인을 다시 로드할 수 없는 경우 대화 상자에서 다시 시도하거나 해당 세션에서 Claude를 다시 시작하도록 제안합니다.

413 433

414<Note>434<Note>

415 VS Code의 플러그인 관리는 내부적으로 동일한 CLI 명령을 사용합니다. 확장 프로그램에서 구성한 플러그인 및 마켓플레이스는 CLI에서도 사용 가능하며, 그 반대도 마찬가지입니다.435 VS Code의 플러그인 관리는 내부적으로 동일한 CLI 명령을 사용합니다. 확장 프로그램에서 구성한 플러그인 및 마켓플레이스는 CLI에서도 사용 가능하며, 그 반대도 마찬가지입니다.

7884. **충돌하는 확장 프로그램 비활성화**: 다른 AI 확장 프로그램(Cline, Continue 등) 임시 비활성화8084. **충돌하는 확장 프로그램 비활성화**: 다른 AI 확장 프로그램(Cline, Continue 등) 임시 비활성화

7895. **작업 영역 신뢰 확인**: 확장 프로그램은 제한된 모드에서 작동하지 않습니다8095. **작업 영역 신뢰 확인**: 확장 프로그램은 제한된 모드에서 작동하지 않습니다

790 810

791또는 [`preferredLocation`](#extension-settings)을 `sidebar`로 설정했거나 **Claude Code: Open in Side Bar**로 Claude를 열었다면, **상태 표시줄**(우측 하단 모서리)의 "✻ Claude Code"를 클릭하세요. 이는 파일이 열려 있지 않아도 작동합니다. **명령 팔레트**(`Cmd+Shift+P` / `Ctrl+Shift+P`)를 사용하고 "Claude Code"를 입력할 수도 있습니다.811또는 **상태 표시줄**(우측 하단 모서리)의 **✻ Claude Code**를 클릭하세요. 이는 파일이 열려 있지 않아도 작동합니다. **명령 팔레트**(`Cmd+Shift+P` / `Ctrl+Shift+P`)를 사용하고 "Claude Code"를 입력할 수도 있습니다.

792 812

793<h3 id="cmd-esc-does-nothing-on-macos">813<h3 id="cmd-esc-does-nothing-on-macos">

794 macOS에서 Cmd+Esc가 작동하지 않음814 macOS에서 Cmd+Esc가 작동하지 않음

worktrees.md +1 −1

Details

145* Worktree가 백그라운드하지 않은 `--worktree` 세션에 속합니다. 나이와 관계없이.145* Worktree가 백그라운드하지 않은 `--worktree` 세션에 속합니다. 나이와 관계없이.

146* `git worktree add`로 직접 worktree를 생성했습니다. 나중에 `--worktree <name>` 세션을 실행하고 해당 세션을 백그라운드했더라도.146* `git worktree add`로 직접 worktree를 생성했습니다. 나중에 `--worktree <name>` 세션을 실행하고 해당 세션을 백그라운드했더라도.

147 147

148Claude Code는 생성하는 모든 git worktree에 git 메타데이터에 마커를 작성하며, 스윕은 마커가 없는 worktree를 유지합니다. [`WorktreeCreate` 훅](#non-git-version-control)이 생성한 worktree를 포함합니다. v2.1.246 이전에는 스윕이 마커를 확인하지 않았으며, 오래된 백그라운드 세션 레코드가 가리킬 때 직접 생성한 worktree를 제거할 수 있었습니다.148Claude Code는 생성하는 모든 git worktree에 git 메타데이터에 마커를 작성하며, 스윕은 마커가 없는 worktree를 유지합니다. [`WorktreeCreate` 훅](#non-git-version-control)이 생성한 worktree를 포함합니다.

149 149

150에이전트가 실행 중인 동안 Claude Code는 해당 worktree에서 `git worktree lock`을 유지하여 동시 정리가 이를 제거할 수 없도록 하며, 에이전트가 완료되면 잠금을 해제합니다. Claude Code는 백그라운드된 세션을 위해 생성한 worktree에서 세션이 실행되는 동안 동일한 잠금을 유지하므로 스윕은 worktree를 제자리에 두고 `git worktree remove`는 이를 제거하기를 거부합니다.150에이전트가 실행 중인 동안 Claude Code는 해당 worktree에서 `git worktree lock`을 유지하여 동시 정리가 이를 제거할 수 없도록 하며, 에이전트가 완료되면 잠금을 해제합니다. Claude Code는 백그라운드된 세션을 위해 생성한 worktree에서 세션이 실행되는 동안 동일한 잠금을 유지하므로 스윕은 worktree를 제자리에 두고 `git worktree remove`는 이를 제거하기를 거부합니다.

151 151

Documentation 2026-09-30 23:00 UTC to 2026-10-01 23:59 UTC