Claude Code 문제 해결

Claude Code 문제 해결 (성능·안정성·검색)

Claude Code가 실행 중일 때 겪는 성능·안정성·검색 문제를 다루는 페이지입니다. 어떤 문제인지에 따라 시작할 페이지가 다릅니다: command not found처럼 설치·PATH·권한·TLS 쪽이면 설치와 로그인 문제 해결, 설정이 안 먹거나 훅이 발동하지 않으면 설정 디버깅을 먼저 보세요. 어느 쪽인지 확실하지 않다면 세션 안에서 /doctor를 실행해 설치·설정·확장·컨텍스트 사용을 자동 점검하고, claude가 아예 시작하지 않으면 셸에서 claude doctor를, MCP 서버 상태는 /mcp를 확인합니다.

출처: 공식문서

본문

성능과 안정성

CPU·메모리 사용량이 높을 때

Claude Code는 큰 코드베이스를 처리할 때 리소스를 많이 쓸 수 있습니다.

/compact로 컨텍스트 크기를 줄이세요. Not enough messages to compact.가 나오면 요약할 대화가 너무 적다는 뜻입니다(단일 대용량 붙여넣기로 컨텍스트가 가득 찬 경우에도 발생 가능).
큰 작업 사이에는 Claude Code를 닫고 다시 시작하세요.
큰 빌드 디렉터리를 .gitignore에 추가하세요.
claude --safe-mode로 재시작해 플러그인·MCP 서버·훅이 원인인지 확인하세요. 모든 커스터마이즈를 끈 상태로 실행되며, 사용량이 줄어들면 설정 디버깅에서 범인을 찾으세요.

이후에도 메모리가 높게 유지되면 /heapdump를 실행해 ~/Desktop에 <session-id>.heapsnapshot(JS 힙 스냅샷)과 <session-id>-diagnostics.json(메모리 분석) 두 파일을 씁니다. Desktop 폴더가 없는 Linux에서는 홈 디렉터리에 씁니다.

⚠️ .heapsnapshot 파일에는 전체 대화와 자격 증명을 포함한 프로세스 내 모든 문자열이 들어갑니다. 공개 이슈에 첨부하거나 공유하지 마세요.

출력은 상주 집합 크기, JS 힙, 배열 버퍼, 미집계 네이티브 메모리와 누수 지표를 요약해 보여줍니다. 결과물로 둘 중 하나를 하세요:

보고: GitHub 이슈를 열고 통계만 담고 대화·자격증명이 없는 -diagnostics.json만 첨부.
직접 조사: 대부분 JS 힙이면 Chrome DevTools의 Memory → Load에서 .heapsnapshot을 열어 retained size로 정렬.

터미널에서 큰 표가 잘려 보일 때

200행이 넘는 Markdown 테이블은 첫 200행만 렌더하고 … N more rows not shown 줄을 붙입니다. 표시만 잘리는 것일 뿐 전체 표는 대화에 남고 /copy는 모든 행을 복사합니다. 터미널에서 읽기 어려우면 Claude에게 파일로 쓰도록 하세요. v2.1.208 이전에는 모든 행을 렌더링해서 재개 시 멈출 수 있었습니다.

자동 압축이 thrashing 오류로 멈출 때

Autocompact is thrashing: the context refilled to the limit...는 자동 압축은 성공했지만 파일·도구 출력이 곧바로 컨텍스트를 여러 번 다시 가득 채웠다는 뜻입니다. Claude Code는 진전 없는 루프에 API 호출을 낭비하지 않도록 재시도를 멈춥니다. 복구하려면:

과대 파일을 특정 라인 구간·함수처럼 작은 덩어리로 읽게 하세요.
큰 출력을 버리는 포커스로 /compact keep only the plan and the diff처럼 /compact를 실행하세요.
큰 파일 작업을 별도 컨텍스트에서 도는 서브에이전트로 옮기세요.
이전 대화가 더 필요 없으면 /clear를 실행하세요.

명령이 멈추거나 프리즈될 때

Ctrl+C로 현재 작업 취소를 시도하세요.
반응이 없으면 터미널을 닫고 재시작하세요.

재시작해도 대화는 유지됩니다. 같은 디렉터리에서 claude --resume으로 세션을 이어가세요.

에디터 통합 터미널에서 텍스트가 깨질 때

VS Code·Cursor·Devin Desktop 통합 터미널에 글자가 깨지거나 틀린 글리프로 보이면 GPU 렌더러가 원인일 가능성이 높습니다. 세션 안에서 /terminal-setup을 실행해 terminal.integrated.gpuAcceleration을 "off"로 설정하거나, 에디터 설정에서 직접 바꾸고 창을 새로 고치세요.

풀스크린 렌더링에서 마우스 휠이 한 줄씩 스크롤될 때

풀스크린 렌더링에서는 터미널 대신 Claude Code가 직접 스크롤합니다. 휠 한 칸당 이동 줄 수를 늘리려면 /scroll-speed로 저장하거나 CLAUDE_CODE_SCROLL_SPEED 환경변수를 설정하세요(JetBrains IDE 터미널은 예외 — 자체 스크롤 처리라 둘 다 무시). PgUp/PgDn은 반 화면씩 이동하고, 터미널 기본 스크롤백으로 되돌리려면 /tui default로 클래식 렌더러로 전환하세요.

샌드박스 안에서 `pbcopy` 같은 클립보드 명령이 실패할 때

샌드박싱이 켜져 있으면 pbcopy, xclip, wl-copy가 샌드박스 안에서 시스템 클립보드에 닿지 못할 수 있습니다. Claude의 출력을 클립보드에 넣으려면 내용을 응답으로 출력하게 한 뒤 /copy를 실행하세요. /copy는 샌드박스 명령이 아니라 Claude Code 프로세스 자체에서 클립보드에 씁니다. 파이프된 명령이 직접 클립보드에 닿게 하려면 pbcopy *, wl-copy *, xclip *를 excludedCommands에 추가해 샌드박스 밖에서 실행하게 하세요.

SSH에서 복사한 텍스트가 로컬 클립보드에 안 갈 때

SSH 원격 머신에서 Claude Code는 로컬 클립보드 도구를 실행할 수 없습니다. tmux 밖에서 풀스크린 렌더링 선택 또는 /copy 시 OSC 52 이스케이프 시퀀스로 텍스트를 터미널에 보냅니다. /copy는 도착 여부와 무관하게 Copied to clipboard를 보고하고, tmux 밖에서는 sent N chars via OSC 52로 표시됩니다. iTerm2는 Settings > General > Selection > Applications in terminal may access clipboard를 켜기 전까지, macOS Terminal.app은 OSC 52를 지원하지 않습니다. OSC 52 없이 얻으려면 터미널 네이티브 선택 키를 누른 채 드래그해서 일반 단축키로 복사하거나, 원격에 CLAUDE_CODE_DISABLE_MOUSE=1을 설정하세요.

검색·발견 문제

Search 도구·@file 언급·커스텀 에이전트·커스텀 스킬이 파일을 못 찾으면 번들된 ripgrep 바이너리가 실행되지 않을 수 있습니다. 플랫폼의 ripgrep 패키지를 설치한 뒤 USE_BUILTIN_RIPGREP를 0으로 설정하세요.

# macOS
brew install ripgrep
# Ubuntu/Debian
sudo apt install ripgrep
# Alpine
apk add ripgrep
# Arch
pacman -S ripgrep
# Windows
winget install BurntSushi.ripgrep.MSVC

{
  "env": {
    "USE_BUILTIN_RIPGREP": "0"
  }
}

적용 확인은 claude doctor에서 Search 줄이 OK (bundled) 대신 시스템 ripgrep 경로를 보이는지 확인하세요.

WSL에서 검색 결과가 느리거나 불완전할 때

WSL의 파일시스템 간 작업 디스크 읽기 성능 저하로 매치 수가 적을 수 있습니다. 해결책: ① 디렉터리·파일 타입을 지정해 더 구체적으로 검색("auth-service 패키지에서 JWT 검증 로직 검색"), ② 프로젝트를 Windows 파일시스템(/mnt/c/) 대신 Linux 파일시스템(/home/)으로 이동, ③ 가능하면 WSL 대신 Windows 네이티브로 실행.

더 알아보기

문제가 여기 없는 경우: /doctor로 셋업 점검, /mcp로 MCP 상태 확인, /feedback으로 Anthropic에 직접 보고, GitHub 저장소 확인, Claude에게 직접 물어보세요. 계정·결제·구독 문제는 claude.ai(Console 사용자는 platform.claude.com)에서 Get help를 통해 Anthropic 지원에 문의하세요.

Claude Code 문제 해결