클로드 코드 자주 나는 문제와 해결 (설치, 로그인, 멈춤)

이 글은 앤트로픽이 운영하는 code.claude.com/docs의 Troubleshooting, Troubleshoot installation, Debug your configuration, Setup 문서를 한국어 사용자가 실무에 바로 옮길 수 있도록 정리한 글입니다. 명령과 오류 문구는 2026년 10월 3일 공식 문서 기준이고, 원문 링크는 글 끝 참고 자료에 모았습니다.

🤔 설치했는데 명령을 못 찾거나 작업 도중 멈출 때

클로드 코드를 설치하고 claude를 입력했더니 명령을 찾을 수 없다고 나오거나, 잘 쓰다가 갑자기 화면이 멈추거나, MCP 서버를 추가했는데 도구가 보이지 않는 일은 누구나 한 번씩 겪습니다. 검색하면 해결법이 여러 가지 나오지만 원인이 다르면 같은 방법이 통하지 않습니다.

설치 자체는 입문 코스의 클로드 코드 설치 첫걸음에서 다뤘습니다. 지금부터는 문제가 생겼을 때 원인을 좁히는 진단 명령, 증상별 해결 순서, 문제를 신고하는 방법을 정리합니다.

🔑 클로드 코드 문제 해결의 정의

오류 문구와 실행 환경을 기록하고, 해당 증상을 진단한 뒤 한 가지씩 수정하여 같은 동작을 다시 확인하는 과정입니다.

2026년 10월 3일 기준 공식 문서는 증상에 따라 나뉘어 있습니다. 설치와 로그인은 Troubleshoot installation, 설정이 적용되지 않거나 MCP 서버가 안 뜨는 문제는 Debug your configuration, 느림과 멈춤과 검색은 Troubleshooting, API 오류 문구는 Errors 페이지가 맡습니다. 예전 글이 연결하는 Troubleshooting 페이지에는 이제 설치 내용이 없으므로 증상에 맞는 페이지를 찾아갑니다.

🩺 먼저 쓰는 진단 명령

먼저 터미널에서 claude --version을 입력합니다. 버전이 나오지만 세션이 열리지 않으면 claude doctor를 실행합니다. command not found라면 아래 설치와 PATH 항목부터 봅니다. 세션이 열리면 /doctor로 점검하고 제안된 수정 내용을 읽은 뒤 적용합니다.

설정 원인을 비교할 때는 claude --safe-mode를 쓸 수 있습니다. 인증, 모델 선택, 기본 도구와 권한은 유지되며 조직의 관리 훅과 설정 정책도 적용됩니다. 문제가 사라졌다면 꺼진 지침이나 확장 가운데 원인이 있는지 하나씩 확인합니다. 모든 보호 설정을 없애는 모드가 아닙니다.

세션 밖과 안의 진단 명령을 구분한 그림입니다. 왼쪽은 claude --version이 실행되는 경우이며 명령 자체를 찾지 못하면 설치 위치와 PATH부터 확인합니다.

📦 명령을 찾을 수 없을 때: 설치와 PATH

command not found는 셸이 해당 명령을 찾지 못했다는 뜻입니다. 설치 여부와 실행 파일 위치, PATH를 확인해야 원인을 좁힐 수 있습니다. 네이티브 설치를 쓴 클로드 코드는 맥과 리눅스에서 ~/.local/bin/claude, 윈도우에서 %USERPROFILE%\.local\bin\claude.exe에 설치되는데, 이 폴더가 PATH(명령을 찾아볼 폴더 목록)에 없으면 셸이 claude를 찾지 못합니다.

해결 순서는 새 터미널 창을 여는 것부터입니다. 그래도 안 되면 네이티브 설치 파일이 해당 위치에 있는지 먼저 확인합니다. 파일이 없으면 설치 여부를 확인하고, 파일은 있는데 명령을 못 찾을 때 PATH를 점검합니다. 해당 경로가 PATH에 없다는 것을 확인한 경우에만, 맥의 zsh에서 echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc를 실행하고 새 터미널을 엽니다. 윈도우에서 PATH를 더하는 PowerShell 명령은 준이아빠블로그의 클로드 코드 설치 오류 해결에 있습니다.

그 밖에 자주 걸리는 원인은 다음과 같습니다.

• VS Code 확장만 설치함: 확장은 자기 안에 클로드 코드 사본을 두고 PATH에 넣지 않습니다. 터미널에서 쓰려면 따로 설치합니다
• 설치가 두 벌 있음: 맥과 리눅스의 which -a claude, Windows의 where.exe claude로 경로를 확인합니다. 여러 경로가 나와도 설치 방식과 실제 대상을 확인한 뒤 유지할 설치를 정합니다
• npm 설치의 Node.js 버전: v2.1.198부터 Node.js 22 이상이 필요합니다. 낮은 버전은 경고만 띄우고 설치가 끝나기도 합니다
• npm 권한 오류: sudo npm install -g는 쓰지 않습니다. 오류가 반복되면 공식 권장인 네이티브 설치로 바꿉니다
• 저사양 리눅스에서 Killed: 메모리 부족 가능성을 확인합니다. 오류 문구와 시스템 메모리 상태를 대조한 뒤 공식 안내를 따릅니다

윈도우에서는 명령을 넣는 창이 맞는지 먼저 봅니다. irm이 인식되지 않으면 CMD에 PowerShell 명령을 넣은 것이고, &&가 문법 오류로 나오면 사용 중인 PowerShell 버전과 명령 형식부터 확인합니다. Git for Windows는 필수가 아니라 선택이고, 없으면 PowerShell로 명령을 실행합니다. WSL에서는 WSL 터미널 안에서 리눅스용 설치 명령을 쓰고, /mnt/c/의 파일을 검색할 때 느리거나 결과가 불완전하면 검색 범위를 좁혀 봅니다. 필요할 때 리눅스 홈 파일시스템 사용을 검토하되 기존 프로젝트를 바로 옮기지는 않습니다.

🔑 로그인이 안 될 때

• 원인을 모르겠는 로그인 실패: /logout 후 종료하고 claude로 다시 시작해 로그인합니다. 브라우저가 열리지 않으면 c를 눌러 주소를 복사합니다
• OAuth error: Invalid code: 코드 만료나 불완전한 복사 여부를 확인합니다. 다시 받아 끝까지 붙여 넣습니다
• WSL, SSH, 컨테이너: 브라우저에서 로그인한 뒤 화면에 나온 코드를 터미널의 입력란에 붙여 넣습니다. 붙여넣기가 안 되면 claude auth login을 씁니다
• 자주 로그아웃됨: 컴퓨터 시계가 맞는지 확인합니다

/logout을 하면 MCP 서버 로그인도 함께 지워지므로 다시 로그인한 뒤 MCP 인증도 새로 합니다.

⚙️ 설정이 적용되지 않을 때

설정 문제의 상당수는 파일을 잘못된 곳에 둔 경우입니다. 개인 공통 권한, 훅, 환경 변수는 ~/.claude/settings.json에, 프로젝트별 설정은 .claude/settings.json 등에, MCP 서버는 ~/.claude.json이나 프로젝트 루트의 .mcp.json에 둡니다. settings.json에 MCP 서버를 적거나 .mcp.json을 .claude/ 폴더 안에 두면 읽지 않습니다. MCP 서버별 확인 순서는 MCP 서버 연결하기에 정리했습니다.

설정이 겹치면 /status로 활성 설정 출처를 보고 /permissions, /hooks, /mcp, /context에서 해당 항목이 실제로 불러와졌는지 확인합니다.

빈 설정 폴더를 지정하는 CLAUDE_CONFIG_DIR 방식은 별도의 로그인과 환경 확인이 필요한 추가 진단입니다. 조직의 관리 정책과 환경 변수까지 없어지지 않으며 예전에 사용한 폴더는 비어 있지 않을 수 있습니다. 처음에는 원본 설정을 보존하고 safe-mode 비교와 항목별 확인부터 합니다.

🐢 느려지거나 멈출 때

/clear는 현재 대화를 비우므로 필요한 조건과 작업 경로를 먼저 기록합니다. /terminal-setup은 터미널 관련 설정을 바꾸는 명령이며 설치 진단만 하는 명령은 아닙니다.

경과 시간 표시가 바뀌어도 실제 작업이 진전된다고 단정할 수는 없습니다. 최근 도구 출력, 승인 대기와 오류 문구를 확인합니다. 중단하고 재개한 뒤에는 마지막 답변뿐 아니라 실제 파일 변경도 확인합니다. 컨텍스트가 커질수록 느려지는 원인은 비용과 한도 관리의 /clear, /compact 기준과 같이 봅니다.

🔄 업데이트가 안 될 때

네이티브 설치는 백그라운드에서 자동으로 업데이트되지만, Homebrew와 WinGet 설치는 기본으로 자동 업데이트하지 않습니다. 직접 올릴 때는 설치 방식에 맞는 명령 하나를 고릅니다. 네이티브는 claude update, Homebrew는 brew upgrade claude-code, WinGet은 winget upgrade Anthropic.ClaudeCode입니다. Homebrew의 claude-code@latest를 설치했다면 같은 이름으로 upgrade합니다. npm 설치는 npm install -g @anthropic-ai/claude-code@latest로 올리고 npm update -g는 피하라고 공식 문서가 적습니다. 업데이트 채널은 latest와 대체로 일주일 정도 늦은 stable이 있으며 설치 방식과 설정에 따라 적용됩니다. Homebrew의 claude-code는 stable을 따릅니다.

🐞 문제를 신고하는 방법

위 방법으로 풀리지 않으면 세션 안에서 /bug(별칭 /share)로 신고합니다. 보낼 대화 범위와 포함된 내용, 제출 동의 화면을 확인합니다. 오류 해결 연습에서는 신고를 제출할 필요가 없습니다. 제품 의견은 /feedback으로 보냅니다. 계정, 결제, 구독 문제는 클로드 코드가 아니라 claude.ai 왼쪽 아래의 Get help로 지원팀에 문의합니다.

❓ 자주 묻는 질문

네이티브 설치와 npm 설치 가운데 무엇이 좋나요?

공식 문서는 네이티브 설치를 권장으로 표시합니다. 자동 업데이트가 되고 Node.js 버전에 영향을 받지 않습니다. npm 설치도 같은 실행 파일을 받아 쓰지만 Node.js 22 이상과 전역 폴더 쓰기 권한이 필요합니다.

윈도우에서 Git for Windows를 꼭 설치해야 하나요?

2026년 10월 3일 공식 설치 문서 기준으로 선택 사항입니다. 없으면 PowerShell로 명령을 실행하고, 있으면 Git Bash로 실행합니다. 윈도우 네이티브 환경에서는 샌드박스 기능을 쓸 수 없고 WSL 2에서는 됩니다.

대화가 길어진 뒤 갑자기 느려졌는데 한도 문제인가요?

그것만으로는 알 수 없습니다. 사용량 한도 메시지, 서비스 오류, 컨텍스트 표시와 컴퓨터 자원 상태를 구분해 확인합니다. 컨텍스트 경고와 자동 압축은 사용량 한도와 별개이고, /context로 무엇이 컨텍스트를 많이 차지하는지 본 뒤 /compact나 /clear로 줄입니다.

오류를 만들지 않고 진단 순서 연습하기

실제 설정을 망가뜨릴 필요 없이 메모장에 다음 가상 사례를 적습니다.

다음 행동을 “claude doctor 실행”이라고 썼다면 고칩니다. 같은 명령을 찾지 못하므로 새 터미널에서 다시 확인하고 설치 여부와 경로를 검사하는 순서가 맞습니다. 파일이 없는데 PATH만 반복 추가해서는 해결되지 않습니다.

두 번째 가정은 “설치 파일과 PATH를 확인한 뒤 claude --version은 버전을 출력하지만 세션을 열면 멈춘다”입니다. 이번에는 claude doctor의 결과를 확인할 수 있습니다. 실제 오류가 있는 분은 진단 결과 가운데 해당 항목 하나를 골라 공식 안내에 따라 수정하고 처음 실패한 동작을 다시 해 봅니다. 다른 설정은 함께 바꾸지 않습니다.

마지막으로 “버전은 출력되지만 로그인 오류가 나온다”로 조건을 바꿔 봅니다. 설치를 반복하기보다 로그인 오류의 정확한 문구를 확인하는 것이 다음 단계입니다. 기록에는 시도한 조치, 다시 실행한 동작, 달라진 결과와 남은 문제를 남깁니다. 해결되지 않았다면 해결 완료라고 적지 않습니다.

📋 3줄 요약

1. 명령을 찾지 못하면 설치 위치와 PATH를 먼저 확인하고 버전 출력이 되면 doctor 진단으로 넘어갑니다.

2. 오류 문구와 실행 환경을 기록한 뒤 원본 설정을 보존하고 한 가지씩 바꿔 같은 동작을 다시 확인합니다.

3. safe-mode에서도 권한과 조직의 관리 정책이 유지되므로 문제가 사라졌는지와 원인이 밝혀졌는지를 구분합니다.

📚 참고 자료

• 설치 문제 해결 문서: https://code.claude.com/docs/en/troubleshoot-install
• 설정 문제 해결 문서: https://code.claude.com/docs/en/debug-your-config
• 성능과 검색 문제 해결 문서: https://code.claude.com/docs/en/troubleshooting
• 설치 문서: https://code.claude.com/docs/en/setup
• CLI 참고 문서: https://code.claude.com/docs/en/cli-reference