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

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 

3222};3222};

3223```3223```

3224 3224 

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

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

3228 Monitor3228 Monitor

4126 4126 

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

4128 4128 

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

4130 4130 

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

4132 4132 

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="터미널의 에이전트 뷰: 헤더는 Claude Code v2.1.140, 모델, 작업 디렉토리 및 요약 개수를 표시합니다. 세션은 입력 필요, 작업 중, 완료됨으로 그룹화되며, 하단에 디스패치 입력과 키보드 힌트의 바닥글이 있습니다." 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="터미널의 에이전트 뷰: 헤더는 Claude Code v2.1.140, 모델, 작업 디렉토리 및 요약 개수를 표시합니다. 세션은 입력 필요, 작업 중, 완료됨으로 그룹화되며, 하단에 디스패치 입력과 키보드 힌트의 바닥글이 있습니다." width="1872" height="680" data-path="images/agent-view-dark.png" />

14 14 

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

16 16 

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

3657 Claude Desktop을 열 수 없음3657 Claude Desktop을 열 수 없음

3658</h3>3658</h3>

3659 3659 

3660[`/desktop`](/docs/ko/desktop#coming-from-the-cli) 또는 그 별칭 `/app`을 실행했고 Claude Code가 Claude Desktop을 열기 위해 사용하는 시스템 명령어가 실패했습니다. 세션은 터미널에 남아 있습니다.3660[`/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로 종료됩니다.

3661 

3662괄호의 텍스트는 실패한 명령어를 이름 지정합니다. 종료 상태와 첫 번째 오류 출력 줄이 있으면 함께 표시됩니다. macOS에서 해당 명령어는 `open`입니다. 이 예와 같이 Windows에서는 `rundll32`입니다:

3661 3663 

3662```text theme={null}3664```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.3665Error: 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```3666```

3665 3667 

3666**해야 할 일:**3668**해야 할 일:**

3667 3669 

3668* Claude Desktop을 직접 열고 `/desktop`을 다시 실행합니다.3670* Claude Desktop을 직접 열고 `/desktop` 또는 `claude --desktop`을 다시 실행합니다.

3669* 해당 명령어의 전체 오류 출력을 읽으려면 `/debug`로 디버그 로깅을 켜고 `/desktop`을 다시 실행한 후 디버그 로그를 확인합니다.3671* 실패한 명령어의 전체 오류 출력을 읽으려면 `/debug`로 디버그 로깅을 켜고 `/desktop`을 다시 실행하거나 `claude --desktop --debug-file <path>`를 실행한 후 디버그 로그를 확인합니다.

3670 3672 

3671v2.1.275 이전에는 메시지가 `Failed to open Claude Desktop. Please try opening it manually.`였고 무엇이 실패했는지 말하지 않았습니다.3673v2.1.285 이전에는 메시지가 `Open Claude Desktop and run /desktop again.`으로 끝났습니다. v2.1.275 이전에는 `Failed to open Claude Desktop. Please try opening it manually.`였고 무엇이 실패했는지 말하지 않았습니다.

3672 3674 

3673<h3 id="terminal-setup-left-your-zed-keymap-unchanged">3675<h3 id="terminal-setup-left-your-zed-keymap-unchanged">

3674 /terminal-setup이 Zed 키맵을 변경하지 않음3676 /terminal-setup이 Zed 키맵을 변경하지 않음

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`으로 시작하는 명령어는 제외됩니다. 명령어가 실행되는 시간을 변경하려면 [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` 환경 변수를 `1`로 설정합니다. 자세한 내용은 [환경 변수](/docs/ko/env-vars)를 참조하세요.

367 365 

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>

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

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 

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에서도 사용 가능하며, 그 반대도 마찬가지입니다.