Documentation 2026-09-30 23:00 UTC to 2026-10-01 05:00 UTC

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` |

109| [에이전트 보기 비활성화](/docs/ko/agent-view#how-background-sessions-are-hosted) | `claude agents`, `--bg`, `/background` 및 온디맨드 감독자를 끕니다 | `disableAgentView` |110| [에이전트 보기 비활성화](/docs/ko/agent-view#how-background-sessions-are-hosted) | `claude agents`, `--bg`, `/background` 및 온디맨드 감독자를 끕니다 | `disableAgentView` |

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` |

2885 2885 

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

2887 2887 

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

2889 2889 

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

2891 2891 

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

717| `accountInfo()` | 계정 정보를 반환합니다 |717| `accountInfo()` | 계정 정보를 반환합니다 |

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

722| `streamInput(stream)` | 다중 턴 대화를 위해 쿼리에 입력 메시지를 스트리밍합니다 |722| `streamInput(stream)` | 다중 턴 대화를 위해 쿼리에 입력 메시지를 스트리밍합니다 |

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

1872| `org_verify_failed` | 로그인의 조직을 핀에 대해 확인할 수 없음(예: 네트워크 실패 또는 취소된 토큰) |1874| `org_verify_failed` | 로그인의 조직을 핀에 대해 확인할 수 없음(예: 네트워크 실패 또는 취소된 토큰) |

1873| `org_pin_mismatch` | 로그인이 핀이 허용하지 않는 조직에 속함 |1875| `org_pin_mismatch` | 로그인이 핀이 허용하지 않는 조직에 속함 |

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 

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 

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>

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>

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` |

66| `--agent` | 현재 세션에 대한 에이전트를 지정합니다(`agent` 설정 재정의) | `claude --agent my-custom-agent` |66| `--agent` | 현재 세션에 대한 에이전트를 지정합니다(`agent` 설정 재정의) | `claude --agent my-custom-agent` |

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'` |

86| `--debug-file <path>` | 특정 파일 경로에 디버그 로그를 작성합니다. 암묵적으로 디버그 모드를 활성화합니다. `CLAUDE_CODE_DEBUG_LOGS_DIR`보다 우선합니다 | `claude --debug-file /tmp/claude-debug.log` |86| `--debug-file <path>` | 특정 파일 경로에 디버그 로그를 작성합니다. 암묵적으로 디버그 모드를 활성화합니다. `CLAUDE_CODE_DEBUG_LOGS_DIR`보다 우선합니다 | `claude --debug-file /tmp/claude-debug.log` |

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` |

87| `--disable-slash-commands` | 이 세션에 대해 모든 스킬 및 명령을 비활성화합니다 | `claude --disable-slash-commands` |88| `--disable-slash-commands` | 이 세션에 대해 모든 스킬 및 명령을 비활성화합니다 | `claude --disable-slash-commands` |

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` |

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

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"` |

121| `--ref <branch>` | `--environment`를 사용하면 새 세션의 체크아웃을 로컬 `HEAD` 대신 명명된 ref를 기반으로 합니다 | `claude -p "Run the smoke test" --environment ccpool_abc123 --ref main` |122| `--ref <branch>` | `--environment`를 사용하면 새 세션의 체크아웃을 로컬 `HEAD` 대신 명명된 ref를 기반으로 합니다 | `claude -p "Run the smoke test" --environment ccpool_abc123 --ref main` |

122| `--remote` | `--cloud`의 더 이상 사용되지 않는 별칭. 기존 세션 형식 포함 | `claude --remote "Fix the login bug"` |123| `--remote` | `--cloud`의 더 이상 사용되지 않는 별칭. 기존 세션 형식 포함 | `claude --remote "Fix the login bug"` |

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` |

129| `--session-id` | 대화에 특정 세션 ID를 사용합니다(유효한 UUID여야 함) | `claude --session-id "550e8400-e29b-41d4-a716-446655440000"` |130| `--session-id` | 대화에 특정 세션 ID를 사용합니다(유효한 UUID여야 함) | `claude --session-id "550e8400-e29b-41d4-a716-446655440000"` |

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` |

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이 회수된 세션을 다시 여는 방법을 다룹니다.

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)을 참조하십시오. |

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에서 터미널 세션을 계속하려면:

331| `Remote managed settings failed to load (<cause>)` | [구성 경고](#remote-managed-settings-failed-to-load) |331| `Remote managed settings failed to load (<cause>)` | [구성 경고](#remote-managed-settings-failed-to-load) |

332| `Managed settings were not approved; exiting without applying them.` | [구성 경고](#managed-settings-were-not-approved) |332| `Managed settings were not approved; exiting without applying them.` | [구성 경고](#managed-settings-were-not-approved) |

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) |

336| `Managed settings drop-in directory could not be read` | [구성 경고](#managed-settings-document-could-not-be-parsed) |338| `Managed settings drop-in directory could not be read` | [구성 경고](#managed-settings-document-could-not-be-parsed) |

339| `Unable to read managed policy settings` | [구성 경고](#unable-to-read-managed-policy-settings) |

337| `otelHeadersHelper failed; telemetry is not being exported. See /status: ...` | [구성 경고](#otelheadershelper-failed) |340| `otelHeadersHelper failed; telemetry is not being exported. See /status: ...` | [구성 경고](#otelheadershelper-failed) |

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) |

339| `headersHelper not run — this workspace has no persisted trust` | [구성 경고](#headershelper-not-run) |342| `headersHelper not run — this workspace has no persisted trust` | [구성 경고](#headershelper-not-run) |

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)에서 각 폴백이 적용되는 시기를 설명합니다.

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>

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 도구는 허용 규칙이 일치해도 거부됩니다

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 

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

49 

48<h2 id="subscriptions-and-gateways">50<h2 id="subscriptions-and-gateways">

49 구독 및 gateway51 구독 및 gateway

50</h2>52</h2>

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| :- | :- |

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">

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` 도구는 다음과 같이 호출할 수 있습니다:

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 

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 

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` 또는 `permission_mode` 없는 [Python Agent SDK](/docs/ko/agent-sdk/python#claudeagentoptions) | [기능 플래그를 가져오는](/docs/ko/env-vars#features-that-need-feature-flag-fetching) 세션에서 `default`. 기능 플래그를 가져오지 않는 세션(예: 타사 공급자 또는 원격 분석 비활성화)에서는 Claude Code v2.1.285 이상에서 `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`입니다. |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| :- | :- |

111| 시작하려는 한 세션 | 권한 모드를 플래그로 전달합니다. 예: `claude --permission-mode default` |111| 시작하려는 한 세션 | 권한 모드를 플래그로 전달합니다. 예: `claude --permission-mode default` |

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 권한 모드 전환

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 

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| :- | :- |

300| `--json` | 목록을 JSON으로 출력합니다 |300| `--json` | 목록을 JSON으로 출력합니다 |

301| `--available` | 설치하지 않은 마켓플레이스가 제공하는 플러그인도 나열합니다. `--json` 없이는 효과가 없습니다 |301| `--available` | 설치하지 않은 마켓플레이스가 제공하는 플러그인도 나열합니다. `--json` 없이는 효과가 없습니다 |

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 

330| `notes` | array of strings | 로드되고 작동하는 플러그인에 대한 작성 경고 |331| `notes` | array of strings | 로드되고 작동하는 플러그인에 대한 작성 경고 |

331| `errorDetails` | array of objects | 각 `errors` 항목에 대한 하나의 객체로, 진단 `type`과 플러그인, 마켓플레이스, 서버, 파일 같은 참조하는 이름을 제공합니다. Claude Code v2.1.268 이상 필요 |332| `errorDetails` | array of objects | 각 `errors` 항목에 대한 하나의 객체로, 진단 `type`과 플러그인, 마켓플레이스, 서버, 파일 같은 참조하는 이름을 제공합니다. Claude Code v2.1.268 이상 필요 |

332| `noteDetails` | array of objects | 각 `notes` 항목에 대한 동일한 세부 객체. Claude Code v2.1.268 이상 필요 |333| `noteDetails` | array of objects | 각 `notes` 항목에 대한 동일한 세부 객체. Claude Code v2.1.268 이상 필요 |

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>

868 868 

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

870 870 

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

872 

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

874 

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

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

877 

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

872 879 

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

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

1072</h3>1079</h3>

1073 1080 

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

1075 1082 

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

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

1079 1086 

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

1081 1088 

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

1090 

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

1092 

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

1083 1094 

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

1085 1096 

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 

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>

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">

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" />

33 

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>`로 중지하도록 지시했습니다.

35 

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`는 해당 실행을 비대화형으로 유지하지 않습니다.

37 

38 Claude Code는 명령줄에 다음 중 하나가 있으면 세션을 열지 않습니다:

39 

40 * 파이프되거나 리디렉션된 입력 또는 출력

41 * `--permission-mode`, `--model` 또는 `--settings`와 같이 세션을 구성하는 플래그

42 * `--output-format json` 또는 `--json-schema`와 같이 출력을 읽는 플래그

43 * `--max-turns` 또는 `--max-budget-usd`와 같이 실행을 제한하거나 되감기하는 플래그

44 

45 이 중 하나가 있거나 [에이전트 보기가 꺼져 있으면](/docs/ko/agent-view#turn-off-agent-view) Claude Code는 아무것도 보내지 않고 상태 1로 종료하며 세션이 백그라운드에서 실행 중임을 출력하고 ID를 결정할 수 없을 때 `claude agents`에서 찾도록 지시하거나 `claude attach <id>` 명령을 출력합니다. 대신 대화의 복사본을 재개하려면 `--fork-session`을 추가합니다. 자신의 플래그가 적용된 자신의 세션에서 대화 자체를 계속하려면 `claude stop <id>`를 실행한 다음 명령을 반복합니다.

46 

47 `/` 또는 `!`로 시작하는 프롬프트는 전송되지 않으며 세션이 질문에 대한 답변을 기다리는 동안 어떤 프롬프트도 전송되지 않습니다. 두 경우 모두 Claude Code는 세션을 열지 않으며 메시지에는 `Your prompt was not sent to it`과 이유가 포함됩니다.

48* **세션 내에서**: `/resume`은 현재 대화를 백그라운드로 이동하고 이 터미널을 실행 중인 세션에 연결하며 `Opening "<title>", running in the background (<id>)`를 출력합니다. 빈 프롬프트에서 `←`를 눌러 에이전트 보기로 돌아가면 남긴 대화도 나열됩니다. 현재 대화가 백그라운드로 이동할 수 없으면(예: 이미 백그라운드 세션에 연결되어 있거나 세션 지속성이 꺼져 있음) `/resume`은 대신 실행할 `claude attach` 명령을 출력합니다.

49 

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)에서 계획 모드로 재개됩니다.

599| [`allowedChannelPlugins`](#allowedchannelplugins) | 메시지를 푸시할 수 있는 [채널 플러그인](/docs/ko/channels#restrict-which-channel-plugins-can-run)의 기본 허용 목록 교체 | 플러그인 및 기술 | 관리됨 |599| [`allowedChannelPlugins`](#allowedchannelplugins) | 메시지를 푸시할 수 있는 [채널 플러그인](/docs/ko/channels#restrict-which-channel-plugins-can-run)의 기본 허용 목록 교체 | 플러그인 및 기술 | 관리됨 |

600| [`allowedHttpHookUrls`](#allowedhttphookurls) | [HTTP hooks](/docs/ko/hooks)가 대상으로 할 수 있는 URL 제한 | 훅 및 자동화 | 모든 파일 |600| [`allowedHttpHookUrls`](#allowedhttphookurls) | [HTTP hooks](/docs/ko/hooks)가 대상으로 할 수 있는 URL 제한 | 훅 및 자동화 | 모든 파일 |

601| [`allowedMcpServers`](#allowedmcpservers) | 사용자가 추가할 수 있는 [MCP 서버](/docs/ko/mcp) 허용 목록 | MCP | 모든 파일 |601| [`allowedMcpServers`](#allowedmcpservers) | 사용자가 추가할 수 있는 [MCP 서버](/docs/ko/mcp) 허용 목록 | MCP | 모든 파일 |

602| [`allowedProviders`](#allowedproviders) | 기계가 사용할 수 있는 [API 공급자](/docs/ko/third-party-integrations) 제한 | 인증 및 공급자 | 관리됨 |

602| [`allowManagedHooksOnly`](#allowmanagedhooksonly) | 조직이 배포하는 [훅](/docs/ko/hooks)만 실행 | 훅 및 자동화 | 관리됨 |603| [`allowManagedHooksOnly`](#allowmanagedhooksonly) | 조직이 배포하는 [훅](/docs/ko/hooks)만 실행 | 훅 및 자동화 | 관리됨 |

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

604| [`allowManagedPermissionRulesOnly`](#allowmanagedpermissionrulesonly) | [관리되는 설정](/docs/ko/managed-settings)을 [권한 규칙](/docs/ko/permissions#managed-settings)의 유일한 설정 소스로 만들기 | 권한 설정 | 관리됨 |605| [`allowManagedPermissionRulesOnly`](#allowmanagedpermissionrulesonly) | [관리되는 설정](/docs/ko/managed-settings)을 [권한 규칙](/docs/ko/permissions#managed-settings)의 유일한 설정 소스로 만들기 | 권한 설정 | 관리됨 |

5879 5880 

5880도우미 스크립트를 통해 자격 증명을 제공하고, 조직의 경우 로그인 방법이나 조직을 강제합니다. [인증](/docs/ko/authentication)을 참조하세요.5881도우미 스크립트를 통해 자격 증명을 제공하고, 조직의 경우 로그인 방법이나 조직을 강제합니다. [인증](/docs/ko/authentication)을 참조하세요.

5881 5882 

5883<h3 id="allowedproviders">

5884 `allowedProviders`

5885</h3>

5886 

5887머신이 Claude에 도달할 수 있는 서비스를 나열합니다. 예를 들어 Anthropic API, Amazon Bedrock, 또는 LLM 게이트웨이입니다. 나열되지 않은 공급자의 세션은 시작 시, 로그인 시, API에 다음으로 연락할 때 거부되므로 세션 중간에 나열되지 않은 공급자로 전환하는 것도 거부됩니다. [거부 메시지](/docs/ko/errors#managed-settings-dont-allow-this-api-provider)는 공급자를 선택한 것과 계속하는 단계를 이름 지정합니다. Claude Code v2.1.285 이상이 필요합니다.

5888 

5889* **범위**: [`관리됨`](#scopes). 머신 자신의 관리자가 소싱한 목록, MDM 정책 및 관리 설정 파일은 서버 관리 설정도 하나를 전달할 때 계속 적용됩니다: 세션은 두 목록 모두의 공급자만 사용할 수 있으므로 서버 관리 목록은 머신이 허용하는 것을 좁힐 수 있지만 절대 확장할 수 없습니다. 어느 머신 소스의 `allowedProviders`가 계산되는지는 [Claude Code가 관리 소스를 결합하는 방법](/docs/ko/managed-settings#how-claude-code-combines-managed-sources)을 따릅니다. 서버 관리 설정만을 통해 전달된 목록은 [서버 관리 설정을 가져오는](/docs/ko/server-managed-settings#platform-availability) 세션에만 도달합니다.

5890* **유형**: 문자열 배열, 각각 다음 중 하나:

5891 * `"anthropic"`: Anthropic의 자체 호스트의 Anthropic API, claude.ai 또는 Console 로그인 또는 API 키를 통해. [`forceLoginMethod`](#forceloginmethod) 또는 [`forceLoginOrgUUID`](#forceloginorguuid)와 쌍을 이루어 로그인도 제한합니다.

5892 * `"bedrock"`: [Amazon Bedrock](/docs/ko/amazon-bedrock)

5893 * `"vertex"`: [Google Cloud의 Agent Platform](/docs/ko/google-vertex-ai), 이전의 Vertex AI

5894 * `"foundry"`: [Microsoft Foundry](/docs/ko/microsoft-foundry)

5895 * `"anthropicAws"`: [AWS의 Claude Platform](/docs/ko/claude-platform-on-aws)

5896 * `"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"`을 함께 나열합니다.

5897 * `"customEndpoint"`: Anthropic API 또는 클라우드 공급자의 API를 다른 호스트로 보냅니다. 예를 들어 `ANTHROPIC_BASE_URL`로 이름 지정된 [LLM 게이트웨이](/docs/ko/llm-gateway), 공급자의 `ANTHROPIC_*_BASE_URL` 변수, 또는 단순 리소스 이름이 아닌 `ANTHROPIC_FOUNDRY_RESOURCE` 값입니다. Claude Code는 관리 [`env`](#env) 블록이 고정한 정확한 값에 대해서만 이를 허용합니다.

5898 * `"gateway"`: [클라우드 게이트웨이](/docs/ko/claude-apps-gateway) 로그인

5899* **기본값**: 설정되지 않음, 따라서 모든 공급자를 사용할 수 있습니다.

5900 

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

5902{

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

5904}

5905```

5906 

5907각 클라우드 공급자의 항목은 해당 공급자의 자체 서비스를 의미합니다. 지역, FIPS, 및 개인 엔드포인트를 포함합니다.

5908 

5909Claude Code가 공급자 이름으로 인식하지 않는 항목은 삭제되고 보고되며, 목록의 나머지는 강제됩니다. 빈 목록이거나 모든 항목이 인식되지 않는 목록의 경우, Claude Code는 모든 공급자를 거부하고 머신에서 시작하지 않습니다.

5910 

5911<h4 id="endpoints-that-need-a-pin-in-managed-env">

5912 관리 `env`에서 핀이 필요한 엔드포인트

5913</h4>

5914 

5915핀은 관리 [`env`](#env) 블록에 설정된 엔드포인트 변수의 값입니다. 세션이 공급자의 트래픽을 해당 공급자의 자체 서비스 이외의 곳으로 보낼 때, Claude Code는 세션의 값이 핀과 동일한 경우에만 이를 허용합니다. 이러한 엔드포인트에는 하나가 필요합니다:

5916 

5917* **`"customEndpoint"` 세션**: 호스트를 이름 지정하는 변수, 예를 들어 `ANTHROPIC_BASE_URL`

5918* **Amazon Bedrock**: AWS SDK의 `AWS_ENDPOINT_URL`, `AWS_ENDPOINT_URL_BEDROCK`, 및 `AWS_ENDPOINT_URL_BEDROCK_RUNTIME` 변수는 Bedrock의 자체 서비스 외부를 가리킬 때입니다. 세션은 `"customEndpoint"` 대신 `"bedrock"` 아래에 머물러 있습니다.

5919* **게이트웨이 로그인의 URL**: 세션은 `"gateway"` 아래에 머물러 있으며, [`forceLoginGatewayUrl`](#forcelogingatewayurl)도 핀으로 계산됩니다.

5920 

5921어느 `env` 블록이 핀으로 계산되는지는 목록이 설정된 위치에 따라 다릅니다:

5922 

5923* **머신의 관리자 소스가 목록을 설정합니다**: 머신의 자체 관리자 소스의 `env` 블록만 계산됩니다.

5924* **서버 관리 설정만 목록을 설정합니다**: 해당 서버 관리 설정의 `env` 값도 계산됩니다.

5925 

5926목록은 클라우드 공급자의 자격 증명 및 테넌시 변수 또는 `HTTPS_PROXY` 및 인증서 설정과 같은 네트워크 경로를 판단하지 않습니다. 관리 `env` 블록에서 플릿에 대해 이를 설정합니다.

5927 

5882<h3 id="apikeyhelper">5928<h3 id="apikeyhelper">

5883 `apiKeyHelper`5929 `apiKeyHelper`

5884</h3>5930</h3>

6401| :- | :- | :- |6447| :- | :- | :- |

6402| 목록 | 모든 소스의 항목을 결합합니다. | [`permissions.allow`](#permissions-allow), [`sandbox.network.allowedDomains`](#sandbox-network-alloweddomains) 및 기타 목록 키 |6448| 목록 | 모든 소스의 항목을 결합합니다. | [`permissions.allow`](#permissions-allow), [`sandbox.network.allowedDomains`](#sandbox-network-alloweddomains) 및 기타 목록 키 |

6403| 잠금 | 모든 소스가 설정하는 가장 엄격한 값을 적용합니다. 어떤 소스도 엄격한 값을 설정하지 않으면 최우선 소스에서만 더 느슨한 값을 적용합니다. | [`allowManagedPermissionRulesOnly`](#allowmanagedpermissionrulesonly), [`permissions.disableBypassPermissionsMode`](#permissions-disablebypasspermissionsmode) 및 기타 boolean 또는 enum 잠금 |6449| 잠금 | 모든 소스가 설정하는 가장 엄격한 값을 적용합니다. 어떤 소스도 엄격한 값을 설정하지 않으면 최우선 소스에서만 더 느슨한 값을 적용합니다. | [`allowManagedPermissionRulesOnly`](#allowmanagedpermissionrulesonly), [`permissions.disableBypassPermissionsMode`](#permissions-disablebypasspermissionsmode) 및 기타 boolean 또는 enum 잠금 |

6404| 제한 허용 목록 | 하위 소스의 항목을 추가하지 않고 설정하는 최우선 소스에서 목록 전체를 가져옵니다. 최우선 소스가 설정하지 않으면 다음 소스에서 전체를 가져옵니다. | [`availableModels`](#availablemodels), [`allowedMcpServers`](#allowedmcpservers), [`strictKnownMarketplaces`](#strictknownmarketplaces), [`allowedChannelPlugins`](#allowedchannelplugins) 및 [`fallbackModel`](#fallbackmodel) 체인 |6450| 제한 허용 목록 | 하위 소스의 항목을 추가하지 않고 설정하는 최우선 소스에서 목록 전체를 가져옵니다. 최우선 소스가 설정하지 않으면 다음 소스에서 전체를 가져옵니다. | [`availableModels`](#availablemodels), [`allowedMcpServers`](#allowedmcpservers), [`allowedProviders`](#allowedproviders), [`strictKnownMarketplaces`](#strictknownmarketplaces), [`allowedChannelPlugins`](#allowedchannelplugins) 및 [`fallbackModel`](#fallbackmodel) 체인 |

6405| 값 전체 | 하위 소스의 항목이나 필드를 결합하지 않고 설정하는 최우선 소스에서 값 전체를 가져옵니다. 최우선 소스가 설정하지 않으면 다음 소스에서 전체를 가져옵니다. | [`sandbox.credentials.awsPairs`](#sandbox-credentials-awspairs), [`sandbox.ripgrep`](#sandbox-ripgrep) |6451| 값 전체 | 하위 소스의 항목이나 필드를 결합하지 않고 설정하는 최우선 소스에서 값 전체를 가져옵니다. 최우선 소스가 설정하지 않으면 다음 소스에서 전체를 가져옵니다. | [`sandbox.credentials.awsPairs`](#sandbox-credentials-awspairs), [`sandbox.ripgrep`](#sandbox-ripgrep) |

6406| 제공된 MCP 서버 | 모든 소스의 서버 이름을 결합합니다. 두 소스가 동일한 이름을 설정하면 상위 소스의 전체 항목을 적용합니다. | [`managedMcpServers`](#managedmcpservers) |6452| 제공된 MCP 서버 | 모든 소스의 서버 이름을 결합합니다. 두 소스가 동일한 이름을 설정하면 상위 소스의 전체 항목을 적용합니다. | [`managedMcpServers`](#managedmcpservers) |

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) |6453| 최우선 소스에서만 읽기 | 정책 키를 전달하는 최우선 소스에서만 키를 읽으므로, 최우선 소스가 설정하지 않을 때에도 하위 소스의 값은 무시됩니다. | [`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 정책 또는 관리형 설정 파일일 때만 인정하므로, 서버 관리형 설정에서는 적용되지 않습니다.6461* **[`policyHelper`](#policyhelper)**: Claude Code는 정책 키를 전달하는 최우선 소스가 MDM 정책 또는 관리형 설정 파일일 때만 인정하므로, 서버 관리형 설정에서는 적용되지 않습니다.

6416* **[`modelOverrides`](#modeloverrides)**: `availableModels`와 쌍을 이룹니다. Claude Code는 설정하는 최우선 소스에서 `modelOverrides`를 가져옵니다. 단, 상위 소스가 `modelOverrides` 없이 `availableModels`를 설정하는 경우는 제외됩니다. 이 경우 모든 소스에서 `modelOverrides`를 무시합니다.6462* **[`modelOverrides`](#modeloverrides)**: `availableModels`와 쌍을 이룹니다. Claude Code는 설정하는 최우선 소스에서 `modelOverrides`를 가져옵니다. 단, 상위 소스가 `modelOverrides` 없이 `availableModels`를 설정하는 경우는 제외됩니다. 이 경우 모든 소스에서 `modelOverrides`를 무시합니다.

6417* **[`forceLoginGatewayUrl`](#forcelogingatewayurl), [`gatewayInternalNetworks`](#gatewayinternalnetworks) 및 [`forceLoginMethod`](#forceloginmethod)의 `"gateway"` 값**: Claude Code는 서버 관리형 설정에서 이들 중 어느 것도 읽지 않으므로, 거기의 값은 MDM 정책 또는 관리형 설정 파일에 설정된 값을 적용하거나 숨기지 않습니다. 머신의 관리자 소스 중에서 정책 키를 전달하는 최우선 순위 소스만 서버 관리형 설정도 있는지 여부와 관계없이 이들을 제공합니다.6463* **[`forceLoginGatewayUrl`](#forcelogingatewayurl), [`gatewayInternalNetworks`](#gatewayinternalnetworks) 및 [`forceLoginMethod`](#forceloginmethod)의 `"gateway"` 값**: Claude Code는 서버 관리형 설정에서 이들 중 어느 것도 읽지 않으므로, 거기의 값은 MDM 정책 또는 관리형 설정 파일에 설정된 값을 적용하거나 숨기지 않습니다. 머신의 관리자 소스 중에서 정책 키를 전달하는 최우선 순위 소스만 서버 관리형 설정도 있는지 여부와 관계없이 이들을 제공합니다.

6464* **[`allowedProviders`](#allowedproviders)**: 표의 규칙 이후에도 머신 자체의 목록이 결과를 제한하며, 해당 항목의 범위 참고 사항에 명시되어 있습니다.

6418 6465 

6419머신에서 결합된 소스를 확인하려면 `/status`를 실행하고 [`Setting sources` 행을 읽으세요](/docs/ko/managed-settings#read-the-source-in-/status).6466머신에서 결합된 소스를 확인하려면 `/status`를 실행하고 [`Setting sources` 행을 읽으세요](/docs/ko/managed-settings#read-the-source-in-/status).

6420 6467 

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>

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 

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가 작동하지 않음