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/typescript.md +6 −4

Details

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 이상이 필요합니다 |

716| `reloadOutputStyles()` | [출력 스타일](/docs/ko/output-styles)을 디스크에서 다시 읽어 중간 세션에서 추가하거나 편집한 스타일 파일을 실행 중인 세션에서 사용할 수 있도록 합니다. 다시 로드 후 사용 가능한 스타일 이름을 나열하는 [`SDKControlReloadOutputStylesResponse`](#sdkcontrolreloadoutputstylesresponse)로 해결됩니다. 에이전트 SDK v0.3.261 이상이 필요합니다 |716| `reloadOutputStyles()` | [출력 스타일](/docs/ko/output-styles)을 디스크에서 다시 읽어 중간 세션에서 추가하거나 편집한 스타일 파일을 실행 중인 세션에서 사용할 수 있도록 합니다. 다시 로드 후 사용 가능한 스타일 이름을 나열하는 [`SDKControlReloadOutputStylesResponse`](#sdkcontrolreloadoutputstylesresponse)로 해결됩니다. 에이전트 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 서버를 활성화 또는 비활성화합니다. 비활성화하면 서버를 연결 해제하고 도구를 제거합니다. 중간 세션에서 `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 에이전트 SDK v0.3.280 이상이 필요합니다 |

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

1848type SDKStartupFailureReason =1848type SDKStartupFailureReason =

1849 | "org_pin_api_key_conflict"1849 | "org_pin_api_key_conflict"

1850 | "provider_not_allowed"

1850 | "org_verify_failed"1851 | "org_verify_failed"

1851 | "org_pin_mismatch"1852 | "org_pin_mismatch"

1852 | "managed_settings_invalid"1853 | "managed_settings_invalid"

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

1870| :- | :- |1871| :- | :- |

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

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

3222};3224};

3223```3225```

3224 3226

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

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

3228 Monitor3230 Monitor

4126 4128

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

4128 4130

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

4130 4132

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

4132 4134

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-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 +1 −1

Details

439 439

440* **Claude가 실행하는 명령**: 클라우드 환경은 자신의 명령 타임아웃을 설정하지 않으므로 Bash 도구의 기본값이 적용됩니다. Claude는 기본적으로 명령을 2분 동안 기다리며 최대 10분까지 요청할 수 있습니다.440* **Claude가 실행하는 명령**: 클라우드 환경은 자신의 명령 타임아웃을 설정하지 않으므로 Bash 도구의 기본값이 적용됩니다. Claude는 기본적으로 명령을 2분 동안 기다리며 최대 10분까지 요청할 수 있습니다.

441 441

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` 밀리초 이상으로 설정하면 해당 제한과 포그라운드 기본값이 모두 길어집니다.442 명령이 [타임아웃](/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)로 실행하는 훅에 타임아웃을 적용하지 않습니다.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* **설정 스크립트**: 대략 5분 이상 걸리는 스크립트는 캐시되지 않습니다. [스크립트 요구 사항](#script-requirements)은 그 이하로 유지하는 방법을 다룹니다.444* **설정 스크립트**: 대략 5분 이상 걸리는 스크립트는 캐시되지 않습니다. [스크립트 요구 사항](#script-requirements)은 그 이하로 유지하는 방법을 다룹니다.

445* **유휴 세션**: 몇 분 동안 활동이 없으면 세션의 VM이 파일이 저장된 상태로 일시 중지되고, 일시 중지된 VM은 나중에 회수될 수 있습니다. [환경 변수 설정](#set-environment-variables)은 각 경우에 세션이 선택하는 항목을 설명하고, [Environment expired](/docs/ko/claude-code-on-the-web#environment-expired)는 VM이 회수된 세션을 다시 여는 방법을 다룹니다.445* **유휴 세션**: 몇 분 동안 활동이 없으면 세션의 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 +1 −1

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

desktop.md +8 −0

Details

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>

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/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 −2

Details

791 791

792`hooks/hooks.json`과 `hooks` manifest 키의 Hooks는 모두 로드됩니다. 모든 이벤트와 그 페이로드의 경우, [Hook 이벤트](/docs/ko/hooks#hook-events)를 참조합니다.792`hooks/hooks.json`과 `hooks` manifest 키의 Hooks는 모두 로드됩니다. 모든 이벤트와 그 페이로드의 경우, [Hook 이벤트](/docs/ko/hooks#hook-events)를 참조합니다.

793 793

794JavaScript 함수로 hooks를 작성하여 Claude Code 내부에서 실행되고 인터페이스에 그릴 수 있도록 하려면, 동일한 `hooks/hooks.json`의 `modules` 키 아래에 모듈 파일을 나열합니다. 하나를 가진 플러그인은 mod입니다. [mod 만들기](/docs/ko/plugins/mods/create)를 참조합니다.

795

794<h4 id="when-plugin-hooks-fire">796<h4 id="when-plugin-hooks-fire">

795 플러그인 hooks가 발생할 때797 플러그인 hooks가 발생할 때

796</h4>798</h4>

868 870

869서버는 번들의 manifest에서 `name`을 가져옵니다.871서버는 번들의 manifest에서 `name`을 가져옵니다.

870 872

873번들의 자신의 manifest는 서버가 필요로 하는 설정을 `user_config` 블록에서 선언할 수 있습니다. 저장된 값이 없는 필수 설정을 가진 번들된 서버는 시작되지 않습니다. `/plugin` **Errors** 탭은 `Bundled MCP server "<name>" was not started: it needs configuration`을 표시합니다.

874

875사용자는 두 가지 방법 중 하나로 값을 제공합니다:

876

877* **`/plugin`에서**: 플러그인을 **Installed** 탭에서 선택하고 **Configure**를 선택합니다

878* **설치 시, 셸에서**: [`--config <server>.<key>=<value>`](/docs/ko/plugins/cli-reference#plugin-install)를 `claude plugin install`에 전달합니다. Claude Code v2.1.285 이상이 필요하고, 플러그인 내부에 패키지된 번들에만 작동합니다.

879

871전송 및 인증의 경우, [MCP](/docs/ko/mcp#plugin-provided-mcp-servers)를 참조합니다.880전송 및 인증의 경우, [MCP](/docs/ko/mcp#plugin-provided-mcp-servers)를 참조합니다.

872 881

873<h3 id="lsp-servers">882<h3 id="lsp-servers">

1071 구성 대화 상자가 나타날 때1080 구성 대화 상자가 나타날 때

1072</h3>1081</h3>

1073 1082

1074대화 상자는 대화형 `/plugin` 인터페이스에서만 나타납니다. 사용자가 다음 중 하나를 수행할 때 아직 설정되지 않은 옵션에 대해 열립니다:1083대화 상자는 대화형 `/plugin` 인터페이스의 일부입니다. 사용자가 다음 중 하나를 수행할 때 아직 설정되지 않은 옵션에 대해 열립니다:

1075 1084

1076* `/plugin`에서 플러그인을 설치합니다1085* `/plugin`에서 플러그인을 설치합니다

1077* 세션 내에서 `/plugin install <plugin>@<marketplace>`를 실행합니다1086* 세션 내에서 `/plugin install <plugin>@<marketplace>`를 실행합니다

1079 1088

1080언제든지 동일한 대화 상자를 열려면, 사용자는 `/plugin configure <plugin>@<marketplace>`를 실행합니다.1089언제든지 동일한 대화 상자를 열려면, 사용자는 `/plugin configure <plugin>@<marketplace>`를 실행합니다.

1081 1090

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)는 라인을 인용합니다.1091VS Code 확장의 [플러그인 관리 대화 상자](/docs/ko/vs-code#install-plugins)는 설치 후 양식으로 설정되지 않은 옵션을 요청하며, 플러그인의 행에 있는 기어 아이콘은 모든 옵션과 함께 양식을 다시 엽니다.

1092

1093`claude plugin install` 셸 명령은 `userConfig` 값을 프롬프트하지 않습니다. 셸에서 값을 설정하려면, 설치할 때 각각을 `--config KEY=VALUE`로 전달하거나, 그 후 JSON 객체를 [`claude plugin configure --values-stdin`](/docs/ko/plugins/cli-reference#plugin-configure)으로 파이프합니다.

1094

1095옵션이 설정되지 않으면, `claude plugin install`은 `userConfig options not yet set` 라인을 인쇄합니다. 라인의 정확한 텍스트는 [The `userConfig` dialog never appears](/docs/ko/plugins/troubleshooting#the-userconfig-dialog-never-appears)를 참조합니다.

1083 1096

1084옵션 필드, 각 값이 저장되는 위치, 컴포넌트가 저장된 값을 참조하는 방법, `${user_config.*}`를 거부하는 필드의 경우, [사용자 구성](/docs/ko/plugins/manifest-reference#user-configuration)을 참조합니다.1097옵션 필드, 각 값이 저장되는 위치, 컴포넌트가 저장된 값을 참조하는 방법, `${user_config.*}`를 거부하는 필드의 경우, [사용자 구성](/docs/ko/plugins/manifest-reference#user-configuration)을 참조합니다.

1085 1098

plugins/install.md +8 −2

Details

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/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 +2 −1

Details

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

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 +219 −126

Details

603| [`allowManagedMcpServersOnly`](#allowmanagedmcpserversonly) | 관리되는 [MCP](/docs/ko/mcp) 허용 목록을 유일하게 적용되는 것으로 만들기 | MCP | 관리됨 |604| [`allowManagedMcpServersOnly`](#allowmanagedmcpserversonly) | 관리되는 [MCP](/docs/ko/mcp) 허용 목록을 유일하게 적용되는 것으로 만들기 | MCP | 관리됨 |

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 +20 −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

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 20:02 UTC