Claude Code 원격 연결 끊김 문제 해결: 여섯 가지 끊김 유형의 증상, 판별 기준 및 해결 방법

Claude Code를 원격으로 실행할 때 가장 괴로운 것은 연결이 안 되는 것이 아니라, 연결은 됐다가 또 끊기고, 끊길 때마다 원인이 다르다는 것입니다.

「연결 끊김」이라는 단어는 사실 여섯 가지 완전히 다른 장애를 포괄합니다. 각각의 증상은 특징이 있고, 해결 방법도 서로 무관합니다—네트워크 전환으로 인한 지속 연결 실패를 기기 절전으로 처리하면 절전을 꺼도 소용없고, 반쯤 죽은 연결을 네트워크 문제로 여기고 기다려도 해가 뜰 때까지 스스로 회복되지 않습니다.

이 글은 실제로 보이는 현상을 기준으로 원인을 역추적합니다. 각 끊김 유형에 대해 증상, 확인 방법, 그리고 해당 해결 방법을 제시합니다. 바로 실행하고 싶다면 마지막 절의 점검 목록으로 건너뛰세요.

이 글은 연결 끊김 점검만 다룹니다. 원격 접속 구성 방법은 《Claude Code 원격 접속: 본체를 꺼도 어디서나 세션 제어》를, 모바일 사용법은 《휴대폰으로 Claude Code 연결: iOS에서 언제든 세션 및 승인 도구 확인》을 참조하세요.

먼저 증상을 확인하세요: 어떤 유형인가요?

원격 연결은 두 구간으로 나뉩니다. Claude Code를 실행하는 개발 머신 ←→ 손에 든 조회 기기. 어느 한쪽에 문제가 생기면 모두 '끊김'으로 나타나지만, 현상은 다릅니다:

보이는 현상	대부분 원인	이동
세션이 갑자기 멈추고, 다시 연결해 보니 진행도 그 시점에 멈춰 있음	개발 머신 절전 / 잠금 화면	§1
엘리베이터에 타거나, 4로 전환하거나, WiFi를 바꾸는 순간 끊김	지속 연결이 강제 종료됨	§2
로컬 터미널을 닫거나 로컬이 절전되면 원격도 즉시 끊김	화면 미러링 방식의 하드 제약	§3
온라인 표시이지만 메시지를 보내도 소식이 없고 오류도 없음	반쯤 죽은 연결	§4
재연결은 되지만 빈 세션이 되거나, 끊긴 동안의 메시지가 사라짐	재연결 시 원래 세션에 복귀하지 못함	§5
몇 시간 후 다시 연결하면 세션이 사라짐	프로세스가 회수되고 콜드 리커버리 없음	§6

가장 오해하기 쉬운 것은 네 번째입니다. 오류가 없습니다. 연결 상태는 초록색이고 메시지도 전송되지만, 응답만 영원히 없습니다—직접 끊기는 것보다 찾기 어렵습니다. 모든 표시등이 '정상'이라고 말해주기 때문입니다.

1. 개발 머신 절전 / 잠금 화면 / 덮개 닫기

증상: 세션이 특정 시점에 완전히 멈춥니다. 다시 연결해도 진행 상황은 끊긴 그 순간에 멈춰 있고 한 발짝도 나아가지 않습니다.

이유: 많은 사람이 '개발 머신이 계속 켜져 있다'고 생각하지만, 시스템 절전, 덮개 닫기 절전, 예약 잠금 화면은 모두 Claude Code 프로세스를 일시 중지하거나 바로 종료시킵니다. 조회 쪽에서는 '갑자기 멈췄다'로 보입니다.

확인 방법: 개발 머신에 돌아가 해당 프로세스가 아직 있는지, 시스템 로그에 절전 기록이 있는지 확인하세요. 프로세스는 있지만 타임스탬프가 끊긴 시점에 멈춰 있다면 거의 이것입니다.

해결 방법: 개발 머신의 전원 설정을 '절전 안 함 / 덮개 닫아도 절전 안 함'으로 설정하세요. 이것이 유일하게 근본적으로 해결하는 방법입니다—어떤 원격 방식도 이미 절전된 기기는 살릴 수 없습니다.

2. 네트워크 전환으로 인한 지속 연결 강제 종료

증상: 세션이 아주 명확한 순간에 끊깁니다—엘리베이터에 들어가거나, WiFi에서 4G로 전환하거나, 집 인터넷이 새벽에 재접속될 때입니다.

이유: 원격 실시간 동기화는 하나의 지속 연결(WebSocket/SSH)에 의존합니다. IP가 바뀌면 이 연결은 그 자리에서 무효가 되며, 어떤 협상 여지도 없습니다.

확인 방법: 끊긴 시점과 네트워크 전환 시점이 일치한다면 이것입니다.

해결 방법: 이 유형은 피할 수 없으므로 자동 재연결 + 백오프로 대비해야 합니다(1초→2초→5초…, 끊기자마자 난사하지 않도록). 순수 SSH에는 이 기능이 없어서 끊기면 끊긴 것이고, 수동으로 다시 입력해야 합니다. 방식을 선택할 때 이는 필수 기준입니다.

3. 화면 미러링 방식: 로컬이 포그라운드로 켜져 있어야 함

증상: 로컬 터미널을 닫거나 로컬이 절전되면 휴대폰 쪽도 즉시 끊깁니다. 서서히 타임아웃되는 것이 아니라 동기화가 무너지는 것입니다.

이유: Anthropic 공식 Remote Control은 로컬에서 실행 중인 세션을 휴대폰/브라우저로 투사하는 방식입니다. 전제 조건은 로컬의 Claude Code가 항상 포그라운드로 켜져 있고 로컬이 항상 온라인 상태여야 한다는 것입니다. 로컬이 죽으면 원격 쪽은 의존할 독립적인 수명 주기가 없습니다.

확인 방법: 로컬 터미널 창을 닫고 원격이 같은 순간 끊기는지 확인하세요. 그렇다면 화면 미러링 방식을 사용하는 것입니다.

해결 방법: 개발 머신 측 상주 데몬 서비스 아키텍처로 바꾸세요—세션을 실행하는 쪽을 부팅 시 자동 시작되는 백그라운드 서비스로 만들어 조회 기기와 독립적으로 살아 있게 합니다. 조회 쪽이 닫히거나, 바뀌거나, 끊겨도 개발 머신에서 계속 실행됩니다. 이것이 '화면 미러링'과 '상주 서비스'의 본질적인 차이이며, 매개변수로 조정할 수 있는 것이 아닙니다.

4. 반쯤 죽은 연결(half-open): 가장 발견하기 어려운 유형

증상: 온라인으로 표시되고, 메시지를 보내도 반응이 없으며, 오류도 없습니다. 몇 분 동안 멈춰 있을 수도 있고, 수동으로 재연결할 때까지 계속 멈춰 있을 수도 있습니다.

이유: 네트워크가 조용히 중단될 때(NAT 테이블 항목 타임아웃, 중간 장비 상태 손실, 신호가 약해져 패킷만 유실되고 연결은 유지되는 경우), TCP 양쪽 끝은 둘 다 아직 연결되어 있다고 생각할 수 있습니다. 실제 데이터는 더 이상 전달되지 않습니다. 하트비트가 없으면 양쪽은 이 착각을 계속 유지합니다.

확인 방법: 연결 상태가 정상으로 표시되지만 보낸 메시지에 전달 확인도 오류도 없고, 수동으로 끊고 재연결하면 즉시 회복된다면 그것입니다.

해결 방법: 연결에 **하트비트(keepalive ping)**를 실행해야 합니다. 약정 시간 안에 상대방의 어떤 응답도 받지 못하면 이를 반쯤 죽은 연결로 판단하고, 가만히 기다리지 말고 능동적으로 끊고 재연결합니다. 판단 기준은 '응답을 받지 못함'이어야 하지, '오류가 없음'이어서는 안 됩니다—반쯤 죽은 연결은 절대 오류를 보고하지 않습니다.

5. 재연결해도 원래 세션으로 복귀하지 못함 / 메시지 유실

증상: 끊겨도 재연결은 되지만, 다시 연결하면 빈 세션이거나 끊긴 동안 상대방이 보낸 메시지가 모두 사라져 있습니다.

이유: 재연결은 단지 새 연결을 만드는 것일 뿐, 그 연결을 원래 세션에 다시 구독시키지 않습니다. 끊긴 동안의 메시지도 캐시되지 않습니다.

확인 방법: 재연결 후 세션 ID가 바뀌었거나, 기록이 재연결 시점부터만 시작됩니다.

해결 방법: 재연결 후 자동으로 원래 세션에 다시 구독하고, 끊긴 동안의 기록을 재생해 주는 방식을 선택하세요. 재연결만 되고 복귀하지 못하면 연결한 것이나 마찬가지입니다.

6. 세션 프로세스가 회수되고 콜드 리커버리가 없음

증상: 짧은 시간 끊김과 재연결은 정상이지만, 몇 시간 후 다시 돌아오면 세션이 사라져 있습니다.

이유: 오랫동안 유휴 상태였던 세션 프로세스가 회수될 수 있고, 데몬 프로세스 자체도 재시작되었을 수 있습니다(업그레이드, 크래시 후 재기동). 메모리의 세션 상태도 함께 사라집니다.

확인 방법: 오래 끊겨야 재현되고, 짧은 끊김에서는 재현되지 않습니다.

해결 방법: 콜드 리커버리 능력이 필요합니다—세션 상태를 디스크에 저장하여 프로세스가 사라져도 디스크에서 컨텍스트를 복구할 수 있어야 합니다. 이상적으로는 메시지를 하나 보내면 자동으로 복구되어 계속되며, 사용자는 느끼지 못합니다.

점검 목록(어떤 방식이든 그대로 따를 수 있음)

순서대로 확인하세요. 각 단계는 독립적으로 검증할 수 있습니다.

1. 세션을 실행하는 기기가 절전 / 잠금 화면 상태인가요? → 자동 절전을 끄고, 덮개를 닫아도 절전되지 않게 하세요.（§1）
2. 끊긴 시점과 네트워크 전환 시점이 일치하나요? → 자동 재연결 + 백오프가 있는 방식을 선택하고, 순수 SSH에 의존하지 마세요.（§2）
3. 로컬 터미널을 닫으면 원격이 즉시 끊기나요? → 화면 미러링 방식의 하드 제약이므로, 상주 데몬 아키텍처로 바꿔야 합니다.（§3）
4. '온라인 표시지만 메시지에 반응 없음'에 갇혀 있나요? → 반쯤 죽은 연결이며, 하트비트 감지만이 자동으로 복구할 수 있습니다.（§4）
5. 재연결 후 세션이 비었거나 메시지가 줄었나요? → '원래 세션 복귀 + 기록 재생'이 필요합니다.（§5）
6. 오래 끊겨야만 세션이 사라지나요? → 디스크 저장 + 콜드 리커버리가 필요합니다.（§6）

구체적인 방안에 적용하기

위 여섯 가지 중 1번만 여러분 기기의 설정 문제이고, 나머지 다섯 가지는 모두 아키텍처에 의해 결정됩니다—방식을 선택할 때 이미 정해져서, 문제가 생긴 후 매개변수를 조정해도 되살릴 수 없습니다.

연결이 끊기지 않는 원격 방식은 다음을 동시에 갖춰야 합니다: 개발 머신 측 상주 데몬 프로세스(§1의 잔여 위험과 §3에 대응), 자동 재연결 + 백오프(§2), 하트비트 감지(§4), 재연결 시 원래 세션 복귀 + 기록 재생(§5), 디스크 저장 콜드 리커버리(§6).

PandaNpc + pandapaw 조합은 이 여섯 가지를 하나씩 맞춰 구현했습니다. pandapaw는 개발 머신에서 부팅 시 자동 시작되는 상주 데몬 프로세스로 등록됩니다(수동으로 켜야 하는 터미널 창이 아니라, 크래시되면 자동으로 다시 실행됩니다); 조회 쪽은 끊기면 자동 재연결되고 백오프가 적용됩니다; 연결에 하트비트를 실행하여 응답이 없으면 반쯤 죽은 연결로 판단하고 능동적으로 재연결합니다; 재연결 후 자동으로 원래 세션에 다시 구독하고 끊긴 동안의 기록을 재생합니다; 세션 프로세스가 회수되더라도 메시지 하나로 디스크에서 콜드 리커버리하여 계속됩니다.

구체적인 설치 및 연결 방법은 《Claude Code 원격 접속》을, 휴대폰에서의 세션 조회와 도구 승인은 《휴대폰으로 Claude Code 연결》을 참조하세요.

덤으로 알아둘 함정: 원격 실행 시 과금을 밟지 마세요

연결 끊김을 점검할 때 claude -p(headless 모드)로 바꿔 실행하기 쉽지만, 2026년 6월 15일부터 Anthropic이 과금을 조정했습니다—headless는 더 이상 구독 할당량에 포함되지 않고, 소액의 월간 SDK 크레딧을 사용하며, 다 쓰면 API 기준으로 과금되므로, 과도하게 사용하면 초과하기 쉽습니다. 대화형 모드(claude REPL)는 여전히 구독 할당량에 포함됩니다. 방식을 바꾸며 연결 끊김을 점검할 때 과금 모드까지 함께 바꾸지 않도록 주의하세요.