46 46
47첫 번째 메시지를 보내기 전에 프롬프트 영역에서 네 가지를 구성하세요:47첫 번째 메시지를 보내기 전에 프롬프트 영역에서 네 가지를 구성하세요:
48 48
49* **환경**: Claude가 실행되는 위치를 선택합니다. 자신의 머신의 경우 **Local**, [클라우드 세션](#cloud-sessions)의 경우 **Cloud**, 관리하는 원격 머신의 경우 [**SSH 연결**](#ssh-sessions), 또는 Windows의 경우 [**WSL 배포판**](/docs/ko/desktop-wsl)을 선택합니다. [환경 구성](#environment-configuration)을 참조하세요.49* **환경**: Claude가 실행되는 위치를 선택합니다. 자신의 머신의 경우 **Local**, 앱을 닫은 후에도 계속되는 [클라우드 세션](#cloud-sessions)의 경우 **Cloud**, 관리하는 원격 머신의 경우 [**SSH 연결**](#ssh-sessions), 또는 Windows의 경우 [**WSL 배포판**](/docs/ko/desktop-wsl)을 선택합니다. SSH 세션의 작업은 [Desktop 연결이 끊긴 동안에도 계속 실행](#keep-a-task-running-while-desktop-is-disconnected)될 수 있지만, Claude 계정을 사용하는 경우 로그인이 만료되면 중지될 수 있습니다. [환경 구성](#environment-configuration)을 참조하세요.
50* **프로젝트 폴더**: Claude가 작업할 폴더 또는 저장소를 선택합니다. 클라우드 세션의 경우 [여러 저장소](#run-long-running-tasks-in-the-cloud)를 추가할 수 있습니다.50* **프로젝트 폴더**: Claude가 작업할 폴더 또는 저장소를 선택합니다. 클라우드 세션의 경우 [여러 저장소](#run-long-running-tasks-in-the-cloud)를 추가할 수 있습니다.
51* **모델**: 전송 버튼 옆의 드롭다운에서 [모델](/docs/ko/model-config#available-models)을 선택합니다. 세션 중에 이를 변경할 수 있습니다.51* **모델**: 전송 버튼 옆의 드롭다운에서 [모델](/docs/ko/model-config#available-models)을 선택합니다. 세션 중에 이를 변경할 수 있습니다.
52* **권한 모드**: [모드 선택기](#choose-a-permission-mode)에서 Claude가 가질 자율성을 선택합니다. 세션 중에 이를 변경할 수 있습니다.52* **권한 모드**: [모드 선택기](#choose-a-permission-mode)에서 Claude가 가질 자율성을 선택합니다. 세션 중에 이를 변경할 수 있습니다.
236 터미널에서 명령 실행하기236 터미널에서 명령 실행하기
237</h3>237</h3>
238 238
239통합 터미널을 사용하면 다른 앱으로 전환하지 않고 세션과 함께 명령을 실행할 수 있습니다. 세션 제목 표시줄에서 **Terminal**을 클릭하거나 macOS 또는 Windows에서 \*\*Ctrl+\`\*\*를 누릅니다. 터미널은 세션의 작업 디렉터리에서 열리고 Claude와 동일한 환경을 공유하므로 `npm test` 또는 `git status`와 같은 명령은 Claude가 편집하는 것과 동일한 파일을 봅니다. 두 번째 터미널 탭을 열려면 터미널 패널 헤더의 \*\*+\*\*를 클릭하거나 채팅의 폴더를 마우스 오른쪽 버튼으로 클릭하여 **Open in terminal**을 선택합니다. 터미널은 로컬 및 [SSH](#ssh-sessions) 세션에서 사용 가능합니다.239통합 터미널을 사용하면 다른 앱으로 전환하지 않고 세션과 함께 명령을 실행할 수 있습니다. 세션 제목 표시줄에서 **Terminal**을 클릭하거나 macOS 또는 Windows에서 \*\*Ctrl+\`\*\*를 누릅니다. 터미널은 세션의 작업 디렉터리에서 열리고 Claude와 동일한 환경을 공유하므로 `npm test` 또는 `git status`와 같은 명령은 Claude가 편집하는 것과 동일한 파일을 봅니다. 두 번째 터미널 탭을 열려면 터미널 패널 헤더의 \*\*+\*\*를 클릭하거나 채팅의 폴더를 마우스 오른쪽 버튼으로 클릭하여 **Open in terminal**을 선택합니다.
240
241터미널은 로컬 및 [SSH](#ssh-sessions) 세션에서 사용 가능하며, [Windows 원격 머신](#windows-remote-machines)에서는 제한이 있습니다.
240 242
241<h3 id="open-and-edit-files">243<h3 id="open-and-edit-files">
242 파일 열기 및 편집하기244 파일 열기 및 편집하기
468 470
469클라우드 세션이 작동하는 방식에 대한 자세한 내용은 [클라우드에서 Claude Code 사용하기](/docs/ko/claude-code-on-the-web)를 참조하세요. 한 가지 작업이 많은 클라우드 세션이 필요할 때 사이드바에서 **Projects**를 선택하여 [프로젝트](/docs/ko/claude-projects)를 만들고, Claude가 한 대화에서 세션을 시작하고 추적하도록 합니다.471클라우드 세션이 작동하는 방식에 대한 자세한 내용은 [클라우드에서 Claude Code 사용하기](/docs/ko/claude-code-on-the-web)를 참조하세요. 한 가지 작업이 많은 클라우드 세션이 필요할 때 사이드바에서 **Projects**를 선택하여 [프로젝트](/docs/ko/claude-projects)를 만들고, Claude가 한 대화에서 세션을 시작하고 추적하도록 합니다.
470 472
473<Note>
474 [SSH 세션](#ssh-sessions)의 작업도 [Desktop 연결이 끊긴 동안 계속 실행](#keep-a-task-running-while-desktop-is-disconnected)될 수 있지만, Claude 계정을 사용하는 경우 로그인이 만료되면 중지될 수 있습니다.
475</Note>
476
471<h3 id="continue-in-another-surface">477<h3 id="continue-in-another-surface">
472 다른 사용 환경에서 계속하기478 다른 사용 환경에서 계속하기
473</h3>479</h3>
772 778
773* **Local**: 머신에서 실행되며 파일에 직접 액세스합니다779* **Local**: 머신에서 실행되며 파일에 직접 액세스합니다
774* **Cloud**: Anthropic이 관리하는 인프라에서 기본적으로 실행됩니다. 앱을 닫아도 세션이 계속됩니다.780* **Cloud**: Anthropic이 관리하는 인프라에서 기본적으로 실행됩니다. 앱을 닫아도 세션이 계속됩니다.
775* **SSH**: SSH를 통해 연결하는 원격 머신(예: 자신의 서버, 클라우드 VM 또는 개발 컨테이너)에서 실행됩니다781* **SSH**: SSH를 통해 연결하는 원격 머신(예: 자신의 서버, 클라우드 VM 또는 개발 컨테이너)에서 실행됩니다. 실행 중인 작업은 [Desktop 연결이 끊긴 동안에도 계속 진행](#keep-a-task-running-while-desktop-is-disconnected)될 수 있지만, Claude 계정을 사용하는 경우 로그인이 만료되면 중지될 수 있습니다.
776* **WSL** (Windows): 머신의 [WSL 2 배포판](/docs/ko/desktop-wsl)에서 실행되며, Linux 도구 모음 및 기본 경로를 사용합니다782* **WSL** (Windows): 머신의 [WSL 2 배포판](/docs/ko/desktop-wsl)에서 실행되며, Linux 도구 모음 및 기본 경로를 사용합니다
777 783
778<h3 id="local-sessions">784<h3 id="local-sessions">
812 818
813SSH 세션을 사용하면 데스크톱 앱을 인터페이스로 사용하면서 원격 머신에서 Claude Code를 실행할 수 있습니다. 이는 클라우드 VM, 개발 컨테이너 또는 특정 하드웨어 또는 종속성이 있는 서버에 있는 코드베이스로 작업할 때 유용합니다.819SSH 세션을 사용하면 데스크톱 앱을 인터페이스로 사용하면서 원격 머신에서 Claude Code를 실행할 수 있습니다. 이는 클라우드 VM, 개발 컨테이너 또는 특정 하드웨어 또는 종속성이 있는 서버에 있는 코드베이스로 작업할 때 유용합니다.
814 820
821<Note>
822 Desktop을 [타사 제공업체](/docs/ko/third-party-integrations)와 함께 사용하는 경우 SSH 세션에는 별도의 설정이 필요합니다. [SSH remote sessions in Claude Desktop on 3P](https://claude.com/docs/third-party/claude-desktop/ssh-remote-sessions)를 참조하세요.
823</Note>
824
815SSH 연결을 추가하려면 세션을 시작하기 전에 프롬프트 상자의 환경 드롭다운을 열고 \*\*SSH > SSH 연결 추가…\*\*를 선택한 다음 연결 세부 정보를 입력합니다:825SSH 연결을 추가하려면 세션을 시작하기 전에 프롬프트 상자의 환경 드롭다운을 열고 \*\*SSH > SSH 연결 추가…\*\*를 선택한 다음 연결 세부 정보를 입력합니다:
816 826
817* **Name**: 이 연결의 친화적인 레이블827* **Name**: 이 연결의 친화적인 레이블
822 832
823추가되면 연결이 환경 드롭다운의 **SSH** 아래에 나타납니다. 이를 선택하여 해당 머신에서 세션을 시작합니다. Claude는 원격 머신에서 파일 및 도구에 액세스하여 실행됩니다.833추가되면 연결이 환경 드롭다운의 **SSH** 아래에 나타납니다. 이를 선택하여 해당 머신에서 세션을 시작합니다. Claude는 원격 머신에서 파일 및 도구에 액세스하여 실행됩니다.
824 834
825원격 머신은 Linux 또는 macOS를 실행해야 합니다. 데스크톱은 처음 연결할 때 원격 머신에 Claude Code를 자동으로 설치합니다. 연결되면 SSH 세션은 권한 모드, 커넥터, 플러그인 및 MCP 서버를 지원합니다.835원격 머신은 Linux, macOS 또는 [Windows](#windows-remote-machines)를 실행할 수 있습니다. 데스크톱은 처음 연결할 때 원격 머신에 Claude Code를 자동으로 설치합니다. 연결되면 SSH 세션은 권한 모드, 커넥터, 플러그인 및 MCP 서버를 지원합니다.
836
837<h4 id="remote-machine-requirements-for-ssh-sessions">
838 SSH 세션의 원격 머신 요구 사항
839</h4>
840
841Linux 또는 macOS 원격 머신에는 지원되는 프로세서, SFTP를 지원하는 SSH 서버, `noexec`로 마운트되지 않은 설치 폴더, 작동하는 셸, 네트워크 액세스가 필요합니다. 연결하기 전에, 또는 로그인한 후 연결이 실패할 때 각 요구 사항을 확인하세요:
842
843* **시스템**: x86\_64 또는 arm64 프로세서. 머신은 Claude Code의 [시스템 요구 사항](/docs/ko/setup#system-requirements)도 충족해야 합니다.
844* **SFTP**: SSH 서버가 SFTP 하위 시스템을 제공해야 하며, 이는 `sshd_config`의 `Subsystem sftp` 줄로 켜집니다. 확인하려면 컴퓨터의 터미널에서 `sftp`로 동일한 호스트와 포트에 연결합니다. 정상적으로 작동하는 서버는 `sftp>` 프롬프트를 표시합니다.
845* **연결당 세션 수**: macOS 및 Linux의 Desktop은 하나의 SSH 연결에서 여러 세션을 엽니다. 서버의 `sshd_config`가 `MaxSessions 1`로 설정되어 있다면 OpenSSH의 기본값인 10 등으로 값을 늘립니다.
846* **설치 폴더**: Desktop은 홈 디렉터리의 `~/.claude/remote/` 아래에 도우미 프로그램과 Claude Code를 설치합니다. 해당 위치에서 이를 실행하므로 이 폴더는 `noexec`로 마운트된 파일 시스템에 있으면 안 됩니다. 연결하는 각 사용자의 홈 디렉터리에 약 1 GB의 디스크 공간을 확보하세요.
847* **셸**: 원격 머신에서 계정에 설정된 셸은 Bash, Zsh, `sh`처럼 SSH를 통해 전송된 명령을 실행할 수 있어야 합니다
848* **네트워크**: Claude Code는 원격 머신에서 실행되며 네트워크 요청도 그곳에서 보내므로, 머신에는 [Claude Code에 필요한 네트워크 액세스](/docs/ko/network-config#network-access-requirements)가 있어야 합니다. 머신이 Claude Code를 다운로드할 수 없는 경우 Desktop이 컴퓨터에서 다운로드하여 업로드합니다. Claude Code의 다른 요청은 여전히 원격 머신에서 전송됩니다.
849
850<h4 id="use-your-ssh-configuration-on-macos-and-linux">
851 macOS 및 Linux에서 SSH 구성 사용
852</h4>
853
854macOS 및 Linux에서 Desktop은 컴퓨터의 OpenSSH 클라이언트를 실행하여 연결하므로 `~/.ssh/config`를 사용합니다. OpenSSH 클라이언트를 통한 연결에는 Claude Desktop v1.37937.0 이상이 필요합니다. 해당 파일의 `Host` 이름을 **SSH host** 필드에 입력하면 `HostName`, `User`, `IdentityFile`, `CertificateFile`, `ProxyJump`, `ProxyCommand`와 같은 해당 항목의 설정이 사용됩니다.
855
856연결을 추가하기 전에 컴퓨터의 터미널에서 클라이언트와 항목을 확인하세요:
857
858* **클라이언트 버전**: `ssh -V`를 실행합니다. 클라이언트는 OpenSSH 7.6 이상이어야 합니다.
859* **항목**: `ssh devbox`와 같이 `Host` 이름으로 `ssh`를 실행합니다. 실패하면 먼저 항목을 수정합니다.
860
861**SSH port** 및 **SSH key (optional)** 필드는 비워 둘 수 있습니다. 값을 입력하면 Desktop은 이를 항목과 함께 사용합니다:
862
863* **SSH port**: 여기에 입력한 값은 항목의 `Port`를 재정의합니다
864* **SSH key (optional)**: Desktop은 항목의 `IdentityFile` 및 SSH 에이전트의 키에 더해 선택한 키 파일을 제공합니다
865
866<h5 id="reach-a-machine-behind-a-jump-host">
867 점프 호스트 뒤의 머신에 연결
868</h5>
869
870bastion이라고도 하는 점프 호스트 뒤의 머신에 연결하려면 항목에 `ProxyJump` 또는 `ProxyCommand`를 설정합니다. 다음 항목은 `bastion.example.com`을 통해 `devbox.internal.example.com`에 연결합니다:
871
872```text ~/.ssh/config theme={null}
873Host devbox
874 HostName devbox.internal.example.com
875 User alice
876 ProxyJump bastion.example.com
877```
878
879**SSH host** 필드에 `devbox`를 입력합니다.
880
881<h5 id="raise-the-ssh-connection-timeout">
882 SSH 연결 타임아웃 늘리기
883</h5>
884
885SSH 구성에서 호스트에 `ConnectTimeout`을 설정하지 않은 경우 Desktop은 `ssh`에 연결 시간으로 30초를 줍니다. 점프 호스트나 `ProxyCommand`를 거치는 경우 이 시간에는 경로가 연결되는 데 걸리는 시간이 포함됩니다. 경로에 더 긴 시간이 필요하다면 항목에 더 높은 값을 추가합니다:
886
887```text ~/.ssh/config theme={null}
888Host devbox
889 HostName devbox.internal.example.com
890 User alice
891 ProxyJump bastion.example.com
892 ConnectTimeout 120
893```
894
895`ssh`는 호스트에 대해 처음 찾은 값을 사용하므로, 이 항목을 `ConnectTimeout`을 설정하는 `Host *` 항목보다 위에 두세요. 확인하려면 컴퓨터의 터미널에서 `ssh -G devbox`를 실행합니다. 출력에 `connecttimeout 120`이 포함됩니다. 값을 변경한 후에는 Desktop을 종료했다가 다시 엽니다.
896
897<h4 id="windows-remote-machines">
898 Windows 원격 머신
899</h4>
900
901Windows 원격 머신을 사용하려면 Claude Desktop v2.31226.0 이상이 필요합니다.
902
903Microsoft의 OpenSSH Server를 사용하세요. 머신은 x64 또는 ARM64일 수 있습니다. SSH 서버가 시작하는 셸은 `cmd.exe`, Windows PowerShell 5.1 또는 Git Bash일 수 있습니다.
904
905Windows 원격 머신은 Linux 원격 머신보다 테스트가 덜 이루어졌습니다. 이에 의존하기 전에 직접 작업을 시도해 보세요.
906
907Windows 원격 머신에서는 특히 다음과 같은 제한이 있습니다:
908
909* **터미널**: 폴더가 `C:/projects/app`과 같은 Windows 경로인 세션에서는 [터미널](#run-commands-in-the-terminal)이 열리지 않습니다
910* **샌드박스**: Claude Code는 그곳에서 네이티브 Windows로 실행되며, 네이티브 Windows에서는 명령을 샌드박스 없이 실행합니다. [샌드박스가 실행되는 위치](/docs/ko/sandboxing)를 참조하세요.
911* **플러그인**: Desktop은 `:`가 포함된 이름처럼 Windows가 저장할 수 없는 파일 또는 폴더 이름을 가진 플러그인을 복사하지 않습니다. 세션에는 Desktop이 제외한 플러그인이 나열됩니다.
912* **MCP 서버**: 일부 Windows 원격 머신에서는 `claude_desktop_config.json`의 MCP 서버에 대한 Claude의 호출이 Desktop을 거치므로, [Desktop 연결이 끊긴 동안](#limits-while-desktop-is-disconnected) Claude가 해당 도구를 호출할 수 없습니다. Claude Desktop v2.37337.0 이전에는 모든 Windows 원격 머신에서 이 제한이 적용됩니다.
913* **워크트리**: 워크트리는 `<project-root>/.claude/worktrees/`에 생성됩니다. [다른 폴더를 선택](#choose-where-ssh-session-worktrees-go)해도 Desktop은 이를 무시합니다.
914* **이전 메시지**: SSH 서버의 셸이 `cmd.exe` 또는 Windows PowerShell인 경우 세션의 이전 메시지를 보려면 먼저 연결해야 할 수 있습니다
915* **포크**: SSH 서버의 셸이 `cmd.exe` 또는 Windows PowerShell인 경우 세션은 첫 번째 메시지에서만 포크할 수 있습니다
916* **연결이 끊긴 동안 실행**: 작업은 SSH 서버가 프로그램을 시작한 연결보다 프로그램이 오래 실행되도록 허용하는 경우에만 [Desktop 연결이 끊긴 동안 계속 실행](#keep-a-task-running-while-desktop-is-disconnected)됩니다. 확인하려면 [원격 머신을 테스트](#prepare-a-long-task)하세요.
917* **남은 프로세스**: 세션이 끝난 후 Claude Code가 시작한 프로그램이 계속 실행될 수 있으므로 머신을 확인하세요. Desktop이 설치하는 [백그라운드 도우미](#keep-a-task-running-while-desktop-is-disconnected)는 그곳에서 자체적으로 중지되지 않습니다.
918
919<h4 id="keep-a-task-running-while-desktop-is-disconnected">
920 Desktop 연결이 끊긴 동안 작업 계속 실행
921</h4>
922
923컴퓨터가 절전 모드로 전환되거나, 네트워크가 끊기거나, Desktop을 종료해도 작업은 완료되거나, 사용자의 입력이 필요하거나, [제한](#limits-while-desktop-is-disconnected) 중 하나에 도달할 때까지 계속 진행됩니다. 덮개를 닫는 것은 절전으로 간주됩니다. 업데이트를 위한 재시작을 포함하여 Desktop 또는 컴퓨터를 재시작하는 것은 종료로 간주됩니다.
924
925Claude Code는 Desktop이 원격 머신에 설치하는 백그라운드 도우미 아래에서 프로세스로 실행되므로, 계속 실행되는 데 SSH 연결이 필요하지 않습니다. 이 섹션의 동작을 사용하려면 Claude Desktop v2.31226.0 이상이 필요합니다.
926
927<Warning>
928 Claude 계정으로 Desktop에 로그인하는 경우 작업이 밤새 실행될 것으로 기대하지 마세요. Desktop은 Desktop이 실행 중이고 연결되어 있는 동안에만 작업의 로그인을 갱신하므로, 연결이 끊긴 후 작업의 로그인이 만료될 수 있으며 그러면 작업이 중지됩니다. 연결이 끊길 때 남아 있는 시간은 상황에 따라 다릅니다.
929
930 지금까지 수행한 작업은 원격 머신에 남아 있으며, 돌아와서 메시지를 보내 계속할 수 있습니다.
931
932 작업을 밤새 실행해야 하는 경우:
933
934 * 덮개를 열고 Desktop을 실행한 상태로 [컴퓨터를 깨어 있는 상태](/docs/ko/desktop-scheduled-tasks#how-scheduled-tasks-run)와 온라인 상태로 유지하세요
935 * 원격 머신과 경로상의 모든 점프 호스트에 대해 SSH 에이전트가 보유한 키처럼 프롬프트 없이 작동하는 로그인을 사용하세요. 그러면 연결이 끊겼을 때 Desktop이 자동으로 다시 연결할 수 있습니다.
936
937 컴퓨터가 절전 상태이거나 꺼져 있는 동안 실행되어야 하는 작업이라면 대신 [클라우드 세션](#run-long-running-tasks-in-the-cloud)을 시작하세요.
938</Warning>
939
940* **절전 또는 네트워크 끊김 후**: 프로세스가 [여전히 실행 중](#limits-while-desktop-is-disconnected)이고 Desktop이 프롬프트 없이 로그인할 수 있으면 실행 중인 작업을 되찾을 수 있습니다. 그렇지 않으면 [메시지를 보내세요](#reconnect-after-sleep-or-a-network-loss).
941* **종료 후, macOS 또는 Linux의 Desktop과 Claude 계정을 사용하는 경우**: Desktop이 [프로세스에 다시 합류](#reopen-a-session-after-you-quit-desktop)할 수 있으면 실행 중인 작업을 되찾을 수 있습니다. 그렇지 않으면 작업이 중지됩니다. 계속 중지된 상태라면 메시지를 보내세요.
942* **종료 후, Windows의 Desktop 또는 [타사 제공업체](/docs/ko/third-party-integrations)를 사용하는 경우**: 세션이 열릴 때 Desktop이 프로세스를 종료하므로 실행 중인 작업을 잃게 됩니다. 계속하려면 메시지를 보내세요.
943
944돌아왔을 때 작업이 완료되지 않았다면 Desktop이 다시 연결할 수 없다는 안내, 인증 오류 또는 대기 중인 요청이 있는지 확인하세요:
945
946* **Desktop이 다시 연결할 수 없음**: 세션에 이유가 표시되며, 알림에도 표시될 수 있습니다. Desktop에서 [로그인이 필요](#reconnect-after-sleep-or-a-network-loss)할 수 있습니다.
947* **인증 오류**: [로그인 토큰 또는 자격 증명](#limits-while-desktop-is-disconnected)이 만료되었을 수 있습니다. Claude 계정을 사용하는 경우 메시지를 보내 계속하세요. 타사 제공업체를 사용하는 경우 [SSH remote sessions in Claude Desktop on 3P](https://claude.com/docs/third-party/claude-desktop/ssh-remote-sessions)를 참조하세요.
948* **대기 중인 요청**: [요청에 응답합니다](#handle-requests-that-arrive-while-you-are-away)
949* **해당 사항 없음**: 메시지를 보내 계속합니다
950
951<a id="prepare-a-long-task" />
952
953<h5 id="prepare-a-long-task">
954 긴 작업 준비
955</h5>
956
957* **먼저 업데이트**: 긴 작업을 시작하기 전에 Desktop을 업데이트하세요. macOS와 Windows에서 Desktop은 다운로드한 업데이트를 설치하기 위해 자동으로 재시작할 수 있습니다. 이 재시작은 Claude가 SSH 작업을 수행하는 동안 대기합니다. Claude 계정을 사용하는 macOS에서는 기본적으로 업데이트가 72시간 동안 대기한 후에는 재시작이 그대로 진행될 수 있습니다.
958* **Desktop을 종료하지 않기**: Desktop이 Windows에서 실행되거나 타사 제공업체를 사용하는 경우 긴 작업이 실행되는 동안 열어 두세요. 종료한 후에는 세션이 열릴 때 Desktop이 [실행 중인 작업을 종료](#reopen-a-session-after-you-quit-desktop)합니다. 열어 두더라도 [사용자를 기다리는](#handle-requests-that-arrive-while-you-are-away) 요청은 보호되지 않습니다.
959* **요청 줄이기**: [작업이 사용자를 기다리는 빈도를 줄이는](#handle-requests-that-arrive-while-you-are-away) 권한 모드, 규칙 또는 훅을 선택하세요
960* **점프 호스트 확인**: 점프 호스트가 휴대폰 푸시와 같은 로그인을 요구하는 경우 프롬프트 없이 작동하는 로그인으로 전환하세요. 그렇지 않으면 Desktop이 다시 연결을 시도할 때마다 푸시를 다시 보낼 수 있습니다.
961* **원격 머신 테스트**: 짧은 작업을 시작하고, 작업이 아직 실행 중일 때 Desktop을 종료한 다음, 작업이 완료되었어야 할 시점이 충분히 지난 후 세션을 다시 엽니다. 작업이 완료되지 않았고 세션에 인증 오류가 표시되지 않으면 원격 머신에서 [작업을 종료시킬 수 있는 요인](#limits-while-desktop-is-disconnected)을 확인하세요.
962* **Desktop 터미널에서 명령 실행하지 않기**: 원격 머신이 [유휴 터미널을 로그아웃](#limits-while-desktop-is-disconnected)시키는 경우 Desktop 외부의 SSH 로그인에서 직접 명령을 실행하세요
963
964<a id="limits-while-desktop-is-disconnected" />
965
966<h5 id="limits-while-desktop-is-disconnected">
967 Desktop 연결이 끊긴 동안의 제한
968</h5>
969
970실행 중인 상태로 둔 작업은 로그인이 만료되거나, 원격 머신이 작업을 종료하거나, 도우미가 중지되거나 교체될 때 종료될 수 있습니다:
971
972* **로그인 토큰 또는 자격 증명**: Claude 계정을 사용하는 경우 토큰이 만료되면 작업이 인증 오류와 함께 중지됩니다. 타사 제공업체를 사용하는 경우 싱글 사인온이나 자격 증명 도우미에서 받은 자격 증명처럼 만료되는 자격 증명에도 동일하게 적용됩니다. [SSH remote sessions in Claude Desktop on 3P](https://claude.com/docs/third-party/claude-desktop/ssh-remote-sessions)를 참조하세요. Claude 계정을 사용하는 경우 Desktop이 로그인을 갱신할 수 있도록 [Desktop을 실행하고 연결된 상태로 유지](#keep-a-task-running-while-desktop-is-disconnected)하세요.
973* **원격 머신**: 원격 머신이 재시작되거나, SSH 연결이 닫힐 때 프로세스를 종료하면 실행 중인 작업이 종료됩니다. Desktop 연결이 끊긴 동안에는 아무것도 이를 다시 시작하지 않습니다. systemd-logind의 `KillUserProcesses`가 `yes`이고 사용자에게 적용되는 Linux 머신은 이런 방식으로 프로세스를 종료합니다. 그곳에서 작업을 계속 실행하려면 관리자에게 `KillExcludeUsers` 등으로 사용자를 예외 처리해 달라고 요청하세요.
974* **유휴 터미널**: 일부 Linux 원격 머신은 일정 시간 동안 아무도 입력하지 않은 터미널을 로그아웃시킵니다(systemd-logind의 `StopIdleSessionSec`). macOS 또는 Linux의 Desktop에서는 세션의 [터미널](#run-commands-in-the-terminal)과 `!` 명령이 기본적으로 Desktop의 SSH 연결을 공유합니다. 그러면 이 로그아웃이 Desktop이 연결되어 있는 동안 연결을 종료하며, 실행 중인 작업도 함께 종료될 수 있습니다. 터미널 창을 닫아도 이를 막을 수 없으므로 [해당 터미널에서 명령을 실행하지 마세요](#prepare-a-long-task).
975* **Desktop 업데이트**: 업데이트에 새 도우미가 포함된 경우 Desktop은 이후 연결 시 원격 머신의 도우미를 교체하며, 이로 인해 아직 실행 중인 작업이 종료될 수 있습니다
976* **장기간 부재**: Linux 또는 macOS 원격 머신에서 Desktop이 30일 동안 연결하지 않으면 도우미가 중지되고 그 아래에서 실행되는 모든 Claude Code 프로세스가 종료됩니다. 그 전에 연결하세요.
977
978Desktop 연결이 끊긴 동안에는 파일 편집 및 일부 도구가 실패할 수 있습니다. 작업에 이들이 필요하다면 Desktop을 연결된 상태로 유지하세요:
979
980* **워크트리**: [워크트리](#work-in-parallel-with-sessions)를 사용하는 세션에서는 Claude가 파일을 편집하기 전에 Desktop이 각 편집을 확인합니다. Desktop 연결이 끊긴 동안에는 각 편집이 약 30초간 대기한 후 실패합니다. 셸 명령은 계속 실행됩니다. Linux 또는 macOS 원격 머신에서는 [편집이 계속 작동할 수 있습니다](#worktree-edits-while-disconnected). 확실하지 않다면 워크트리 없이 세션을 시작하세요.
981* **폴더 제한**: 조직에서 세션이 사용할 수 있는 폴더를 제한하는 경우 Desktop은 워크트리 여부와 관계없이 각 파일 읽기, 검색, 편집을 확인합니다. Desktop 연결이 끊긴 동안에는 각 작업이 최대 10분간 대기한 후 실패합니다.
982* **커넥터**: [커넥터](#connect-external-tools) 및 Desktop이 제공하는 기타 도구는 Desktop을 통해 실행되므로, 연결이 끊긴 동안에는 각 호출이 약 30초 후에 실패합니다
983* **워크플로**: Desktop은 각 새 [워크플로](/docs/ko/workflows)가 시작되기 전에 이를 확인하므로, Desktop 연결이 끊긴 동안에는 새 워크플로가 최대 10분간 대기한 후 실패합니다
984* **MCP 서버**: Claude Code가 원격 머신에서 시작하는 MCP 서버는 Desktop을 거치지 않으므로 Claude가 해당 도구를 계속 호출할 수 있습니다. `claude_desktop_config.json`의 서버는 Desktop이 [기본 제공 SSH 클라이언트](#worktree-edits-while-disconnected)를 사용하지 않는 경우에만 여기에 포함됩니다. 그렇지 않은 경우와 [일부 Windows 원격 머신](#windows-remote-machines)에서는 Desktop 연결이 끊긴 동안 Claude가 해당 도구를 호출할 수 없습니다.
985
986<span id="worktree-edits-while-disconnected" />
987
988<Accordion title="워크트리의 편집이 계속 작동하는 경우">
989 Linux 또는 macOS 원격 머신에서는 확인이 Desktop을 거치지 않으므로, Desktop 연결이 끊긴 동안에도 워크트리 내부의 편집이 계속 작동합니다. Claude Desktop v2.37337.0 이전에는 Linux 원격 머신에서만 해당됩니다.
990
991 다음을 포함한 일부 경우에는 여전히 편집이 실패합니다:
992
993 * **기본 제공 SSH 클라이언트**: Desktop이 이를 사용하는 경우. 예를 들어 Microsoft Store 설치, Microsoft의 OpenSSH 9.4 이상이 없는 Windows 컴퓨터, 또는 타사 제공업체를 사용하는 Windows의 기본 동작
994 * **저장소 위치**: 저장소가 홈 디렉터리, 그 상위 폴더 또는 `~/.claude`인 경우
995 * **macOS 경로**: macOS 원격 머신에서 저장소가 `/Volumes` 아래에 있거나, 저장소 또는 워크트리 경로의 폴더 이름에 `~` 또는 비ASCII 문자가 포함된 경우
996 * **폴더 제한**: 조직에서 세션이 사용할 수 있는 폴더를 제한하는 경우
997 * **회사 런처**: Claude Desktop v2.37337.0 이전에서 Claude 계정으로 로그인하고, 조직이 [회사 런처](/docs/ko/corporate-launcher)를 통해 원격 머신에서 Claude Code를 시작하는 경우
998
999 워크트리가 없는 세션에는 조직에서 세션이 사용할 수 있는 폴더를 제한하지 않는 한 이러한 확인이 없습니다.
1000</Accordion>
1001
1002<a id="handle-requests-that-arrive-while-you-are-away" />
1003
1004<h5 id="handle-requests-that-arrive-while-you-are-away">
1005 부재 중에 도착하는 요청 처리
1006</h5>
1007
1008Desktop 연결이 끊긴 동안 Claude가 승인을 필요로 하거나 질문을 하면 Claude는 원격 머신에서 대기합니다. 대기 자체에는 시간 제한이 없습니다. Desktop이 프로세스에 다시 합류하면 요청을 표시합니다. 대신 Desktop이 새 프로세스를 시작하면 요청을 잃게 됩니다.
1009
1010작업이 사용자를 기다리는 동안 Desktop은 업데이트 설치 등을 위해 자동으로 재시작할 수 있습니다. Desktop이 Windows에서 실행되거나 타사 제공업체를 사용하는 경우 재시작 후 요청을 잃게 됩니다.
1011
1012요청을 잃은 경우 메시지를 보내 계속하세요.
1013
1014작업이 사용자를 기다리기 위해 멈추는 빈도를 줄이고 부재 중에도 작업 소식을 받으려면, 자리를 비우기 전에 다음 중 하나를 설정하세요:
1015
1016* **자동 모드**: [사용할 수 있는 경우](#auto-mode-availability) [자동 모드](#choose-a-permission-mode)를 선택합니다. 반복적으로 차단되면 [다시 확인을 요청받습니다](/docs/ko/permission-modes#when-auto-mode-falls-back).
1017* **허용 규칙**: 원격 머신의 사용자 설정 파일인 `~/.claude/settings.json`에 작업에 필요한 명령에 대한 [허용 규칙](/docs/ko/permissions#manage-permissions)을 추가합니다. 조직이 [관리형 설정의 권한 규칙만 허용](/docs/ko/settings-reference#allowmanagedpermissionrulesonly)하는 경우 관리자에게 원격 머신에 적용되는 [관리형 설정](#managed-settings)에 이를 추가해 달라고 요청하세요. 프로젝트의 `.claude/settings.json`에 있는 허용 규칙은 [프로젝트 허용 규칙 및 워크스페이스 신뢰](/docs/ko/permissions#project-allow-rules-and-workspace-trust)를 참조하세요.
1018* **응답하는 훅**: 원격 머신의 `~/.claude/settings.json`에 [`PermissionRequest` 훅](/docs/ko/hooks#permissionrequest)을 구성하여 사용자 대신 요청을 허용하거나 거부합니다
1019* **알림을 보내는 훅**: 같은 파일에 `permission_prompt` matcher와 함께 [`Notification` 훅](/docs/ko/hooks#notification)을 구성하여 요청이 대기 중일 때 자신에게 메시지를 보냅니다
1020* **Claude가 완료되면 알려 주는 훅**: 같은 파일에 [`Stop` 훅](/docs/ko/hooks#stop)을 구성하여 Claude가 응답을 마쳤을 때 자신에게 메시지를 보냅니다. API 오류로 턴이 끝나면 실행되지 않습니다. 이 경우에는 [`StopFailure` 훅](/docs/ko/hooks#stopfailure)을 구성하세요.
1021
1022조직이 [관리형 훅만 실행](/docs/ko/settings-reference#allowmanagedhooksonly)하는 경우 관리자에게 원격 머신에 적용되는 [관리형 설정](#managed-settings)에 훅을 추가해 달라고 요청하세요.
1023
1024Claude Code는 Bypass permissions를 포함한 어떤 권한 모드에서도 [일부 작업](/docs/ko/permission-modes#actions-no-mode-auto-approves)을 자동 승인하지 않습니다. 권한 모드에 따라 Claude Code는 이러한 작업을 거부하거나 사용자에게 묻고, 그러면 작업은 사용자의 응답을 기다립니다.
1025
1026<a id="reconnect-after-sleep-or-a-network-loss" />
1027
1028<h5 id="reconnect-after-sleep-or-a-network-loss">
1029 절전 또는 네트워크 끊김 후 다시 연결
1030</h5>
1031
1032돌아왔을 때 Desktop이 다시 연결되지 않았다면 세션에서 메시지를 보내세요. Desktop은 SSH 에이전트가 보유한 키처럼 프롬프트 없이 로그인할 수 있는 경우에만 자동으로 다시 연결합니다.
1033
1034* **저장된 비밀번호**: Desktop이 기억하도록 허용한 비밀번호도 프롬프트 없이 작동하지만, 장기간 자리를 비우는 경우에는 SSH 에이전트가 보유한 키를 사용하는 것이 좋습니다. 해당 비밀번호로 로그인이 중단되거나 멈추면 Desktop은 다시 연결을 중단하고 사용자를 기다릴 수 있습니다.
1035* **기타 프롬프트**: 원격 머신이 일회용 코드와 같은 다른 항목을 요청하면 컴퓨터에서 알림을 받을 수 있습니다. 알림을 클릭하거나 세션에서 메시지를 보내면 Desktop이 프롬프트를 표시합니다.
1036
1037<Accordion title="점프 호스트가 로그인을 요청하거나, 중단이 길거나, 출력이 누락되었거나, 프로세스가 사라진 경우">
1038 - **점프 호스트, 부재 중 푸시 중지**: macOS 또는 Linux의 Desktop에서 휴대폰 푸시와 같은 점프 호스트의 로그인 요청에 아무도 응답하지 않을 때 발생할 수 있습니다. 그러면 Desktop은 컴퓨터 앞에 아무도 없는 동안 다시 연결을 중단합니다. 컴퓨터 잠금을 해제하거나 컴퓨터를 사용하면 Desktop이 다시 시도할 수 있으므로 푸시를 다시 받을 수 있습니다. 응답 없는 시도가 세 번 이어지면 사용자가 재시도하거나 메시지를 보낼 때까지 기다립니다.
1039 - **점프 호스트, 푸시가 계속 옴**: Windows의 Desktop처럼 아무도 응답하지 않는다는 것을 Desktop이 알 수 없는 경우, 다시 합류할 프로세스가 있는 동안에는 해당 프로세스가 여전히 실행 중인지와 관계없이 계속 시도합니다. 시도할 때마다 푸시를 다시 받을 수 있습니다. 시도를 끝내려면 Desktop을 종료하세요. 단, 이로 인해 [실행 중인 작업을 잃을 수 있습니다](#reopen-a-session-after-you-quit-desktop).
1040 - **긴 중단**: Desktop은 약 5분마다 한 번 시도하도록 속도를 늦춥니다. 더 빨리 다시 연결하려면 세션에서 재시도하거나 메시지를 보내세요. 메시지는 Desktop이 연결되면 전달됩니다.
1041 - **누락된 출력**: Desktop 연결이 끊긴 동안 도우미는 각 세션의 가장 최근 Claude Code 출력을 16 MiB 버퍼에 보관하고 오래된 출력은 삭제합니다. Desktop이 다시 연결된 후 세션에 `Loading recent output from <host>…`가 표시될 수 있습니다. Desktop이 모든 출력을 불러올 수 없으면 `Some output produced while you were disconnected may be missing here.` 행이 표시됩니다. 이 행은 작업이 중지되었다는 의미가 아닙니다.
1042 - **사라진 프로세스**: Desktop이 다시 연결될 때 프로세스가 사라졌다면, Desktop은 대화의 저장된 기록에서 새 프로세스를 시작하고 Claude에게 작업을 계속하도록 지시할 수 있습니다. 프로세스가 계속 종료되거나 Desktop이 타사 제공업체를 사용하는 경우 Desktop은 작업을 자동으로 계속하지 않습니다. 메시지를 보내 계속하세요.
1043</Accordion>
1044
1045<a id="reopen-a-session-after-you-quit-desktop" />
1046
1047<h5 id="reopen-a-session-after-you-quit-desktop">
1048 Desktop 종료 후 세션 다시 열기
1049</h5>
1050
1051Desktop을 종료한 후에도 작업은 완료되거나, 사용자의 입력이 필요하거나, [제한](#limits-while-desktop-is-disconnected) 중 하나에 도달할 때까지 원격 머신에서 계속 실행됩니다.
1052
1053* **macOS 또는 Linux의 Desktop, Claude 계정 사용**: Desktop을 시작하고 세션을 엽니다. Desktop이 프로세스에 다시 합류할 수 있으면 실행 중인 작업을 되찾을 수 있습니다. 예를 들어 일부 Desktop 업데이트 후나 조직이 관리형 설정을 변경한 후에는 항상 다시 합류할 수 있는 것은 아닙니다.
1054* **macOS 또는 Linux에서 Desktop이 다시 합류할 수 없는 경우**: Desktop은 프로세스를 종료하고 대화의 저장된 기록에서 새 프로세스를 시작합니다. 실행 중인 작업은 중지되고, 대기 중이던 승인이나 질문도 잃게 됩니다. 업데이트 후에는 Desktop이 Claude에게 계속하도록 지시할 수 있습니다. 작업이 계속 중지된 상태라면 메시지를 보내세요.
1055* **Windows의 Desktop, 또는 모든 플랫폼에서 타사 제공업체 사용**: 작업이 완료되었을 것으로 예상될 때만 Desktop을 다시 시작하세요. Desktop은 종료 후 절대 다시 합류하지 않으므로 실행 중인 작업을 되찾을 수 없습니다. 세션이 열릴 때 프로세스를 종료하며, 이는 Desktop이 시작될 때 발생할 수 있습니다. 메시지를 보내 계속하세요.
1056
1057타사 배포의 경우 [SSH remote sessions in Claude Desktop on 3P](https://claude.com/docs/third-party/claude-desktop/ssh-remote-sessions)를 참조하세요.
1058
1059<Warning>
1060 대화의 Claude Code 프로세스가 아직 실행 중인 동안에는 원격 머신에서 해당 대화에 대해 [`claude --resume`](/docs/ko/cli-reference#cli-flags)을 실행하지 마세요. Claude Code는 이를 막지 않으며, 그러면 두 프로세스가 같은 대화에 기록합니다. 확실하지 않다면 대화의 사본에서 계속하는 `--fork-session`을 추가하세요. 단, 두 프로세스는 여전히 같은 파일에서 작업합니다.
1061</Warning>
826 1062
827<h4 id="choose-where-ssh-session-worktrees-go">1063<h4 id="choose-where-ssh-session-worktrees-go">
828 SSH 세션 워크트리 위치 선택1064 SSH 세션 워크트리 위치 선택
8342. 원격 머신의 `~/.claude/settings.json`에 있는 [`worktree.location`](/docs/ko/settings-reference#worktree-location)10702. 원격 머신의 `~/.claude/settings.json`에 있는 [`worktree.location`](/docs/ko/settings-reference#worktree-location)
8353. 기본값인 `<project-root>/.claude/worktrees/`10713. 기본값인 `<project-root>/.claude/worktrees/`
836 1072
837각 프로젝트는 설정한 폴더 안에 자체 하위 폴더를 가지므로, `~/worktrees`를 사용하면 워크트리 경로는 `~/worktrees/<project>-<id>/<worktree-name>`이 됩니다. 설정한 폴더가 프로젝트 내부에 있으면 Desktop은 해당 프로젝트에 대해 이를 무시하고 기본값을 사용합니다.1073각 프로젝트는 설정한 폴더 안에 자체 하위 폴더를 가지므로, `~/worktrees`를 사용하면 워크트리 경로는 `~/worktrees/<project>-<id>/<worktree-name>`이 됩니다. 설정한 폴더가 프로젝트 내부에 있으면 Desktop은 해당 프로젝트에 대해 이를 무시하고 기본값을 사용합니다. [Windows 원격 머신](#windows-remote-machines)에서는 Desktop이 항상 기본값을 사용합니다.
838 1074
839이전에 추가한 연결이나 조직에서 관리하는 연결에 **Worktree folder**를 설정하려면 환경 드롭다운에서 해당 연결 위에 마우스를 올린 다음 기어 아이콘을 클릭합니다.1075이전에 추가한 연결이나 조직에서 관리하는 연결에 **Worktree folder**를 설정하려면 환경 드롭다운에서 해당 연결 위에 마우스를 올린 다음 기어 아이콘을 클릭합니다.
840 1076
