문제 해결 (Troubleshooting)
기준일: 2026-07-13 난이도: 초급 공식 기준: Troubleshooting, CLI reference, Commands, Manage sessions
Claude Code 문제 해결은 먼저 공식 진단 표면으로 좁힙니다. 세션 안에서는 /doctor, /debug, /mcp, /context를 쓰고, CLI가 시작되지 않을 때는 터미널에서 claude doctor와 claude --safe-mode를 사용합니다.
핵심 개념
| 증상 | 먼저 확인할 공식 표면 |
|---|---|
| 설치, PATH, 로그인 문제 | claude doctor, 설치·로그인 문제 해결 문서 |
| 설정이 적용되지 않음 | /doctor, /memory, /mcp, debug configuration 문서 |
| hooks, skills, plugins, MCP가 의심됨 | claude --safe-mode |
| API 5xx, 529, 429, validation error | Error reference |
| 응답이 느리거나 멈춤 | /compact, /clear, /heapdump, claude --resume |
| 파일 검색이 누락됨 | ripgrep 설치, USE_BUILTIN_RIPGREP=0 |
| 디버그 로그 필요 | claude --debug, claude --debug-file, /debug |
| 세션을 잃은 것처럼 보임 | claude --resume, /resume |
선택 기준
| 상황 | 권장 순서 |
|---|---|
| Claude Code가 실행됨 | /doctor → /mcp → /memory → /context |
| CLI 자체가 시작되지 않음 | claude doctor → PATH·설치 방식 확인 |
| 설정 파일·hook·plugin 영향 의심 | claude --safe-mode로 같은 작업 재현 |
| 특정 런타임 오류 조사 | claude --debug "api,mcp" 또는 /debug |
| 컨텍스트 초과·thrashing | 큰 출력 줄이기 → /compact ... → /clear |
| 세션 중단 후 복구 | 같은 디렉터리에서 claude --resume |
실습
1. 설치와 버전
which claude
claude --version
claude doctor
command not found가 나오면 Native Install 기본 경로가 PATH에 있는지 확인합니다.
ls ~/.local/bin/claude
export PATH="$HOME/.local/bin:$PATH"
설치가 꼬였을 때는 공식 설치 스크립트나 claude install stable로 복구합니다.
curl -fsSL https://claude.ai/install.sh | bash
claude install stable
2. 로그인과 계정
세션 안에서는 /login, /logout을 사용하고, 터미널에서는 공식 auth 명령만 사용합니다.
claude auth login
claude auth logout
claude auth status --text
Remote Control은 API key가 아니라 claude.ai 로그인과 구독 계정이 필요합니다. Team 또는 Enterprise에서는 Owner가 admin settings에서 Remote Control을 켜야 할 수 있습니다.
3. 설정이 적용되지 않을 때
/doctor
/memory
/mcp
/context
확인할 것:
/memory에 기대한CLAUDE.md,CLAUDE.local.md,.claude/rules/가 실제로 보이는가- rules의
paths패턴이 현재 파일과 맞는가 - hooks나 MCP가 실패하거나 느린가
- 같은 작업을
claude --safe-mode에서 재현하면 문제가 사라지는가
--safe-mode는 CLAUDE.md, skills, plugins, hooks, MCP servers, custom commands, agents, output styles, themes, keybindings, LSP servers, auto memory 등을 로드하지 않고 시작합니다. 인증, 모델 선택, 기본 도구, permissions는 유지됩니다.
claude --safe-mode
4. 멈춤과 긴 컨텍스트
명령이 멈춘 것처럼 보이면 먼저 현재 작업을 중단합니다.
Ctrl+C
터미널을 닫아도 대화는 저장됩니다. 같은 디렉터리에서 picker를 열어 복구합니다.
claude --resume
컨텍스트가 커졌다면 세션 안에서 정리합니다.
/context
/compact keep only the accepted plan and current diff
/clear
Autocompact is thrashing... 류 오류는 큰 파일이나 큰 tool output이 요약 직후 컨텍스트를 다시 채우는 상황입니다. 파일을 범위로 나눠 읽고, 필요한 요약 지시를 붙여 /compact를 실행하거나, 별도 subagent로 큰 읽기 작업을 분리합니다.
5. 성능과 메모리
높은 CPU나 메모리 사용량이 계속되면 다음 순서로 좁힙니다.
/compact
/clear
/heapdump
/heapdump는 JavaScript heap snapshot과 메모리 breakdown 파일을 데스크톱 또는 홈 디렉터리에 씁니다. 이 파일은 민감한 경로와 세션 정보를 포함할 수 있으므로 공유 전 내용을 확인합니다.
6. 검색과 파일 발견
Search tool, @file, custom agent, skill이 파일을 못 찾으면 bundled ripgrep 대신 시스템 ripgrep을 사용하게 만듭니다.
macOS:
brew install ripgrep
USE_BUILTIN_RIPGREP=0 claude
Ubuntu/Debian:
sudo apt install ripgrep
USE_BUILTIN_RIPGREP=0 claude
WSL에서 Windows 파일 시스템(/mnt/c/...) 위 프로젝트를 쓰면 검색이 느리거나 누락될 수 있습니다. 가능하면 Linux 파일 시스템 아래로 옮기고 검색 범위를 더 구체적으로 지정합니다.
7. 디버그 로그
특정 하위 시스템을 좁혀 로그를 남깁니다.
claude --debug "api,mcp"
claude --debug-file /tmp/claude-debug.log
세션 중에는 /debug를 실행해 이후 로그를 켜고, 문제 설명을 함께 줄 수 있습니다.
/debug MCP 서버가 연결된 뒤 응답이 느려지는 문제를 확인해줘
도구에 입력할 프롬프트
Claude Code 문제를 공식 진단 순서로 좁혀줘.
먼저 /doctor, /mcp, /memory, /context 결과를 확인하고,
필요하면 claude --safe-mode와 --debug 재현 절차를 제안해줘.
공식 문서에 없는 config, memory, session 하위 명령군은 사용하지 마.
체크리스트
-
claude --version과claude doctor를 확인했다. - 세션 안에서는
/doctor,/mcp,/memory,/context를 먼저 실행했다. - 설정 의심 시
claude --safe-mode로 같은 증상을 비교했다. - 디버그가 필요할 때
--debug또는/debug를 사용했다. - 멈춘 세션은
claude --resume또는/resume으로 복구했다. - 큰 출력은 범위를 줄이고
/compact로 정리했다. - 검색 문제는 ripgrep 설치와 WSL 파일 위치를 확인했다.