Claude Code를 사용하는 개발자라면 누구나 한 번쯤 이런 화면을 마주한 적이 있을 겁니다. 터미널에 「Symbioting… (3m 12s · ↓ 5.7k tokens)」라는 문구가 뜨고, 진행 표시줄이 마치 얼어붙은 것처럼 몇 분 동안 아무런 반응이 없죠. 답답한 마음에 "아직 있나요?"라고 메시지를 보내면, 갑자기 Claude가 기다렸다는 듯이 작업을 이어가는 기이한 경험을 해보셨을 겁니다.
이런 '멈춤 + 메시지 입력으로 부활'하는 현상은 마법처럼 보이지만, 사실 Anthropic의 스트리밍 프로토콜, 타임아웃 메커니즘, 그리고 컨텍스트 관리 과정에서 발생하는 몇 가지 구체적인 오류 패턴이 겹쳐서 나타나는 결과입니다. 이 글에서는 Claude Code 공식 문제 해결 문서와 GitHub Issues #25979, #24688, #39718, #25286, #25539, #51659 등 영문 자료를 바탕으로 Claude Code가 멈추는 진짜 이유를 파헤치고, 즉시 적용 가능한 7가지 복구 방법과 5가지 예방 전략을 정리해 드립니다.
핵심 가치: 이 글을 읽고 나면 각 스피너(spinner) 문구의 상태 의미, 왜 메시지를 보내면 부활하는지, 언제 Ctrl+C로 재시작해야 하는지, 그리고 멈춤 현상을 거의 제로에 가깝게 줄이는 방법을 알게 될 것입니다.
Claude Code 상태 표시기 완벽 해설
'멈춤' 문제를 해결하려면 먼저 Claude Code가 터미널에 표시하는 상태 줄을 이해해야 합니다. 스크린샷의 Symbioting… (3m 12s · ↓ 5.7k tokens)는 신비로워 보이지만, 사실 각 부분이 명확한 의미를 가진 구조화된 정보입니다.
| 필드 | 예시 값 | 의미 |
|---|---|---|
| 스피너 동사 | Symbioting… |
현재 단계의 의인화된 설명, 2.1.23 버전부터 커스텀 가능 |
| 경과 시간 | 3m 12s |
현재 단계 시작부터 현재까지의 누적 시간 |
| 흐름 화살표 | ↓ 또는 ↑ |
↓는 API로부터 데이터 수신 중, ↑는 전송 중 |
| 토큰 카운트 | 5.7k tokens |
현재까지 다운로드/업로드된 토큰 수 |
Claude Code에는 187개의 기본 스피너 동사가 내장되어 있으며, Befuddling, Ruminating, Accomplishing, Symbioting 등이 그 예입니다. 이는 단순히 기다리는 경험을 생동감 있게 만들기 위한 장치일 뿐, 기술적인 차이는 없습니다. 2.1.23 버전부터는 spinnerVerbs 설정 항목이 도입되어, 커뮤니티에서 제공하는 1900개 이상의 커스텀 동사 팩으로 교체할 수도 있습니다.
Claude Code가 실제로 멈췄는지 판단하는 핵심은 동사가 아니라 시간이 계속 흐르는지, 토큰 카운트가 변하는지입니다. 만약 3분 12초에서 30초가 지났는데 시간은 3분 42초가 되었지만 토큰 카운트는 5.7k에 머물러 있다면, 스트리밍 응답이 중단되었다고 판단할 수 있습니다.
국내에서 APIYI(apiyi.com)와 같은 API 중계 서비스를 통해 Claude API를 호출하는 경우에도 상태 줄의 의미는 공식과 동일하므로, 같은 방법으로 문제를 진단할 수 있습니다.
Claude Code 멈춤 현상의 6가지 근본 원인
상태 표시기의 의미를 이해했다면, 실제 발생하는 증상과 대조하여 근본 원인을 파악할 수 있습니다. 아래 6가지 원인은 GitHub 이슈 트래커에서 보고된 실제 사례의 90% 이상을 차지하며, 발생 빈도순으로 정리했습니다.
근본 원인 1: API 스트리밍 응답의 조용한 중단
가장 흔하면서도 파악하기 어려운 원인으로, GitHub 이슈 #25979와 관련이 있습니다. Claude Code의 HTTP 클라이언트에는 read timeout 메커니즘이 없습니다. 상위 API가 전송 도중 패킷 발송을 멈추면 프로세스는 커널의 epoll_wait 상태에서 무한 대기하게 됩니다. UI의 스피너는 계속 돌아가지만 토큰 카운트는 전혀 오르지 않습니다. 주로 네트워크 불안정, tmux 멀티플렉싱, SSH 연결 끊김 등이 원인입니다.
근본 원인 2: 도구 호출 페이로드 과다로 인한 연결 리셋
이슈 #39718과 관련이 있습니다. 모델이 수십만 줄의 파일을 Write하는 등 대규모 출력을 생성하는 도구를 실행할 때, OS가 5분 동안 유효한 데이터 전송이 없으면 HTTP 연결을 강제로 리셋합니다. Claude Code가 이 오류를 제대로 처리하지 못해 UI상에서는 스피너가 계속 유지됩니다. 보통 정확히 5분 정도 대기 후 멈추는 현상이 나타납니다.
근본 원인 3: 자동 압축(Auto-compact)의 병목 현상
컨텍스트 윈도우가 꽉 차면 자동 압축이 트리거됩니다. 대용량 파일이나 도구 출력이 압축 후 다시 컨텍스트로 읽히는 과정이 반복되면 시스템이 Autocompact is thrashing 메시지를 띄우며 멈춥니다. 메시지가 뜨기 전까지 UI는 멈춘 것처럼 보입니다.
근본 원인 4: 컨텍스트 사용률 80% 초과
공식 문서에 따르면 컨텍스트 사용률이 80%를 넘으면 응답 속도가 급격히 저하되며, 일부 상황에서는 장시간 응답 없음 상태가 됩니다. 이 "가짜 멈춤"의 특징은 토큰 카운트가 매우 느리게나마 증가한다는 점입니다.
근본 원인 5: 설정 오류로 인한 초기 구동 실패
이슈 #31049, #29652 등과 관련이 있습니다. enableAllProjectMcpServers: true 설정으로 너무 많은 로컬 MCP 서버를 불러오거나, additionalDirectories에 //C:/와 같은 잘못된 경로를 입력하면 Claude Code가 초기 구동 시 멈출 수 있습니다.
근본 원인 6: 상태 표시줄 잔상 (응답 완료 후 UI 미갱신)
이슈 #25539와 관련이 있습니다. Claude는 이미 결과를 반환했지만 터미널 UI의 스피너가 사라지지 않는 경우입니다. 이때 엔터를 치거나 메시지를 보내면 Claude는 즉시 다음 작업을 수행합니다. 사실 멈춘 것이 아니라 UI만 멈춘 척하고 있는 것입니다.
문제 해결 시 먼저 토큰 카운트가 증가하는지 확인하세요. APIYI(apiyi.com) 플랫폼을 통해 Claude API를 중계하고 있다면, 플랫폼 로그에서 요청이 200 OK를 반환했는지 확인하여 Claude Code UI 상태와 교차 검증하는 것이 좋습니다.
메시지를 보내면 Claude Code가 다시 살아나는 이유
많은 분이 Claude Code가 3분간 멈췄을 때 "아직 있니?"라고 묻거나 엔터키를 누르면 다시 작동하는 "기적"을 경험합니다. 이는 프로토콜 수준에서 설명할 수 있습니다.
첫째, **상태 표시줄 잔상(원인 6)**의 경우입니다. 이미 작업은 끝났는데 UI만 멈춘 상태라, 새로운 메시지가 들어오면 다음 프롬프트로 처리되어 마치 "부활"한 것처럼 보입니다.
둘째, **스트리밍 응답 지연(원인 1)**의 경우입니다. 새로운 입력이 들어오면 Claude Code가 기존의 hang 상태를 강제 종료하고 새로운 HTTP 요청을 시작합니다. 이전 대화 기록을 포함해 다시 요청을 보내므로 모델이 중단 지점부터 답변을 이어갈 수 있습니다.
셋째, MCP 서버나 도구 호출이 응답을 대기 중인 경우입니다. 새 메시지가 새로운 도구 호출 결정으로 라우팅되면서 기존의 멈춘 호출을 우회하게 됩니다.
다만, 메시지 보내기가 만능은 아닙니다. 프로세스가 복구 불가능한 대기 상태(원인 2 후기 등)라면 메시지는 입력 큐에 쌓일 뿐 처리되지 않으므로, 이때는 Ctrl+C로 종료해야 합니다. APIYI(apiyi.com) 플랫폼을 이용 중이라면, 플랫폼이 공식 엔드포인트보다 타임아웃 연결을 더 빨리 해제해주기 때문에 메시지를 통한 복구 성공률이 더 높을 수 있습니다.
Claude Code 멈춤 현상 해결을 위한 7가지 방법
문제의 근본 원인에 따라 적절한 해결책이 달라집니다. 아래 표는 가장 효과적인 7가지 방법을 '침습성(작업에 미치는 영향)'이 낮은 순서대로 정리했으니 상황에 맞춰 선택해 보세요.
| 방법 | 명령어 | 적용 원인 | 컨텍스트 손실 여부 |
|---|---|---|---|
| 메시지 전송 | 텍스트 직접 입력 | 원인 1 / 6 | 아니오 |
| 현재 작업 중단 | Ctrl+C |
원인 1 / 2 / 3 | 아니오 |
| 자가 진단 | /doctor |
모두(우선 실행) | 아니오 |
| 컨텍스트 압축 | /compact |
원인 3 / 4 | 일부 기록이 요약됨 |
| 세션 초기화 | /clear |
원인 4(심각) | 예 |
| 터미널 재시작 후 복구 | claude --resume |
원인 1 / 2(심각) | 아니오 |
| 프로세스 강제 종료 | kill -9 <pid> |
원인 1 / 2(복구 불가) | 현재 턴 손실 |
실제 조치 순서는 '가벼운 것부터 무거운 것 순서'로 진행하는 것을 권장합니다. 먼저 엔터를 누르거나 간단한 메시지를 보내보고, 안 되면 Ctrl+C로 현재 턴을 취소하세요. 터미널이 완전히 응답하지 않는다면 터미널을 종료한 뒤 claude --resume 명령어로 세션을 다시 불러오면 됩니다.
/doctor는 Anthropic에서 공식 추천하는 필수 진단 명령어입니다. 설치 상태, 설정 파일, MCP 서버 목록, 컨텍스트 사용량 등 핵심 지표를 한 번에 검사하며, 실행 후 보통 구체적인 해결책을 제시해 줍니다. 만약 출력 결과에 Context: 87%와 같이 표시된다면 원인 4일 가능성이 높으니, /compact를 사용해 즉시 해결할 수 있습니다.
긴 작업이 필요한 경우, 워크플로우에 주기적으로 /compact를 넣어 컨텍스트 사용량을 60% 이하로 유지하는 것이 좋습니다. 또한 APIYI(apiyi.com) 플랫폼을 통해 Claude를 호출할 때, Claude Code 메인 프로세스와 MCP 서버에 각각 별도의 할당량을 신청하면 문제 발생 시 원인을 더 쉽게 파악할 수 있습니다.
Claude Code 멈춤 현상 방지를 위한 5가지 베스트 프랙티스
문제 해결은 사후 약방문일 뿐, 진정으로 안정적인 워크플로우는 예방에서 시작됩니다. GitHub 이슈에서 도출된 근본 원인을 바탕으로, 멈춤 현상을 거의 제로에 가깝게 줄일 수 있는 5가지 실천 방안을 정리했습니다.
첫 번째는 대용량 파일 분할 읽기입니다. 1MB 이상의 파일을 한 번에 읽으면 거의 확실하게 컨텍스트 윈도우 압박을 받습니다. ls -la로 크기를 먼저 확인한 뒤, Read 명령어의 offset/limit 파라미터를 사용해 나누어 읽는 2단계 방식을 적용하세요.
두 번째는 복잡한 작업은 서브 에이전트(subagent)에게 위임하기입니다. Claude Code의 서브 에이전트는 독립적인 컨텍스트 윈도우를 가집니다. 대량의 파일 생성이나 일괄 코드 수정 같은 작업은 서브 에이전트에게 맡겨 메인 컨텍스트가 과부하되는 것을 근본적으로 방지하세요.
세 번째는 불필요한 MCP 서버 끄기입니다. MCP 서버를 추가할 때마다 시작 시 멈춤 현상(hang) 위험이 커집니다. 설정에서 매일 사용하는 필수 MCP만 남기고 나머지는 모두 비활성화하세요.
네 번째는 메인 모델 타임아웃 및 읽기 타임아웃 설정입니다. 커뮤니티에서 검증된 방법은 STREAM_READ_TIMEOUT_MS를 120초로 설정하고, 외부 와치독(watchdog) 프로세스를 통해 JSONL 데이터가 갱신되지 않으면 자동으로 프로세스를 종료 후 재시작하게 만드는 것입니다.
다섯 번째는 안정적인 API 경로 사용입니다. 해외망 호출, 가정용 인터넷, tmux 연결 등은 스트리밍 중단 확률을 높입니다. APIYI(apiyi.com)와 같은 API 중계 서비스를 통해 Claude 모델을 호출하면, 안정적인 중계 노드를 통해 TCP 연결을 유지할 수 있어 멈춤 현상을 획기적으로 줄일 수 있습니다.
이 5가지를 실천하는 팀들은 멈춤 현상이 주당 510회에서 1회 미만으로 줄었고, 복구 시간 또한 510분에서 수십 초 내로 단축되었다고 합니다.
자주 묻는 질문 (FAQ)
Q1: 스피너 문구가 바뀌는 것은 Claude가 다른 작업을 하고 있다는 뜻인가요?
아닙니다. 187개의 기본 문구는 단순히 무작위로 선택되는 의인화된 문구일 뿐, Claude의 실제 상태와는 아무런 관련이 없습니다. 현재 상태를 판단하려면 토큰 카운트와 대기 시간을 확인하세요.
Q2: Ctrl+C를 누르면 컨텍스트가 사라지나요?
아니요, 사라지지 않습니다. Ctrl+C는 현재 진행 중인 작업만 취소하며, 전체 대화 세션은 그대로 유지됩니다. 만약 Ctrl+C가 반응하지 않는다면 한 번 더 누르거나 터미널을 종료한 뒤, claude --resume 명령어로 세션을 복구할 수 있습니다.
Q3: 국내에서 Claude Code를 사용하면 더 자주 멈추나요?
해외망 연결은 스트리밍 중단의 주요 원인 중 하나입니다. APIYI(apiyi.com)와 같은 API 중계 서비스를 사용하면 안정적인 노드가 Anthropic과의 연결을 유지해주므로, 국내 개발 환경에서의 멈춤 확률이 눈에 띄게 낮아집니다.
Q4: `Autocompact is thrashing` 메시지가 뜨면 어떻게 해야 하나요?
즉시 현재 작업을 멈추고, /compact keep only the plan and the diff와 같이 특정 범위를 지정하는 압축 명령어를 사용하여 컨텍스트에서 불필요한 원본 출력을 제거하세요. 그래도 해결되지 않으면 새 세션을 열거나 대용량 파일 읽기 작업을 서브 에이전트 모드로 전환하세요.
Q5: 스피너 문구를 직접 수정할 수 있나요?
네, 가능합니다. ~/.claude/settings.json 파일에 spinnerVerbs 필드를 추가하면 됩니다. default, append, replace 모드를 지원하며 문자열 배열을 통해 커스텀할 수 있습니다. 이미 커뮤니티에는 88개 테마, 1900개 이상의 문구 팩이 공유되어 있으니 이를 활용해 보세요.
요약
Claude Code가 멈추는 현상의 본질은 스트리밍 프로토콜, 컨텍스트 관리, MCP 통합이라는 세 가지 하위 시스템이 엣지 케이스에서 충돌하며 발생하는 문제입니다. 상태 표시기의 4가지 필드를 이해하고, 6가지 근본 원인과 7가지 복구 방법을 숙지하면 '알 수 없는 현상'을 '해결 가능한 장애'로 바꿀 수 있습니다.
실무적인 제안은 복구 방법을 근육 기억처럼 익히는 것입니다. 먼저 메시지를 보내보고, 안 되면 Ctrl+C를 누르고, /doctor를 실행한 뒤, 마지막으로 터미널을 껐다가 claude --resume을 시도하세요. 안정적인 API 중계 서비스와 5가지 예방 수칙을 병행하여 컨텍스트를 80% 이하로 유지하고, 대용량 파일은 서브 에이전트에게 맡기며, APIYI(apiyi.com)를 통해 안정적인 경로를 확보한다면 대부분의 멈춤 현상은 수십 초 내에 스스로 해결할 수 있습니다.
작성자: APIYI 기술팀
문의: APIYI(apiyi.com)를 통해 Claude 전 시리즈 모델 및 Claude Code 안정적인 중계 서비스 지원 확인
업데이트 시간: 2026-05-13
