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

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

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

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

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

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

클로드 코드 문제 해결은 증상을 설치, 로그인, 설정, 성능 네 가지로 나누고 claude doctor와 /doctor로 원인을 좁힌 뒤 공식 문서의 해당 항목을 따라가는 과정입니다.

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

🩺 먼저 쓰는 진단 명령

claude가 아예 열리지 않으면 셸에서 claude doctor부터 돌립니다. 세션은 열리는데 무언가 이상하면 /doctor를 씁니다. 어떤 설정이 원인인지 모르겠다면 claude --safe-mode로 시작해 문제가 사라지는지 봅니다. 사라진다면 내가 추가한 설정 가운데 하나가 원인입니다.

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

command not found는 운영체제마다 문구가 다르지만 원인은 대부분 같습니다. 클로드 코드는 맥과 리눅스에서 ~/.local/bin/claude, 윈도우에서 %USERPROFILE%\.local\bin\claude.exe에 설치되는데, 이 폴더가 PATH(명령을 찾아볼 폴더 목록)에 없으면 셸이 claude를 찾지 못합니다.

해결 순서는 새 터미널 창을 여는 것부터입니다. 그래도 안 되면 설치 폴더를 PATH에 더합니다. 맥의 zsh라면 echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc를 실행하고 새 터미널을 엽니다. 윈도우에서 PATH를 더하는 PowerShell 명령은 준이아빠블로그의 클로드 코드 설치 오류 해결에 있습니다.

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

• VS Code 확장만 설치함: 확장은 자기 안에 클로드 코드 사본을 두고 PATH에 넣지 않습니다. 터미널에서 쓰려면 따로 설치합니다
• 설치가 두 벌 있음: which -a claude로 여러 경로가 나오면 네이티브 설치와 npm 설치가 함께 있는 것입니다. 한쪽을 지웁니다
• npm 설치의 Node.js 버전: v2.1.198부터 Node.js 22 이상이 필요합니다. 낮은 버전은 경고만 띄우고 설치가 끝나기도 합니다
• npm 권한 오류: sudo npm install -g는 쓰지 않습니다. 오류가 반복되면 공식 권장인 네이티브 설치로 바꿉니다
• 저사양 리눅스에서 Killed: 메모리 부족입니다. 설치에 약 512MB의 여유 메모리가 필요합니다

윈도우에서는 명령을 넣는 창이 맞는지 먼저 봅니다. irm이 인식되지 않으면 CMD에 PowerShell 명령을 넣은 것이고, &&가 문법 오류로 나오면 PowerShell에 CMD 명령을 넣은 것입니다. 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에, MCP 서버는 ~/.claude.json이나 프로젝트 루트의 .mcp.json에 둡니다. settings.json에 MCP 서버를 적거나 .mcp.json을 .claude/ 폴더 안에 두면 읽지 않습니다. MCP 서버별 확인 순서는 MCP 서버 연결하기에 정리했습니다.

설정끼리 어떻게 겹치는지 모르겠다면 /status로 적용된 값과 출처를 보고, 완전히 빈 설정과 비교하려면 cd /tmp && CLAUDE_CONFIG_DIR=/tmp/claude-clean claude로 새 설정 폴더에서 시작해 봅니다.

🐢 느려지거나 멈출 때

화면이 멈춘 것처럼 보여도 아래의 경과 시간 표시가 바뀌고 있다면 작업 중입니다. 컨텍스트가 커질수록 느려지는 원인은 비용과 한도 관리의 /clear, /compact 기준과 같이 봅니다.

🔄 업데이트가 안 될 때

네이티브 설치는 백그라운드에서 자동으로 업데이트되지만, Homebrew와 WinGet 설치는 기본으로 자동 업데이트하지 않습니다. 직접 올리려면 claude update, brew upgrade claude-code, winget upgrade Anthropic.ClaudeCode를 씁니다. npm 설치는 npm install -g @anthropic-ai/claude-code@latest로 올리고 npm update -g는 피하라고 공식 문서가 적습니다. 업데이트 채널은 latest(기본)와 대체로 일주일 전 버전인 stable 가운데 고릅니다.

🐞 문제를 신고하는 방법

위 방법으로 풀리지 않으면 세션 안에서 /bug(별칭 /share)로 신고합니다. 보낼 대화 범위를 고르고 동의 화면을 거칩니다. 제품 의견은 /feedback으로 보냅니다. 계정, 결제, 구독 문제는 클로드 코드가 아니라 claude.ai 왼쪽 아래의 Get help로 지원팀에 문의합니다.

❓ 자주 묻는 질문

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

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

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

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

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

대개 컨텍스트 문제입니다. 컨텍스트 경고와 자동 압축은 사용량 한도와 별개이고, /context로 무엇이 컨텍스트를 많이 차지하는지 본 뒤 /compact나 /clear로 줄입니다.

📋 3줄 요약

1. 클로드 코드 공식 문제 해결 문서는 설치와 로그인, 설정 미적용, 성능과 검색, API 오류 네 페이지로 나뉘어 있고 진단은 셸의 claude doctor와 세션 안의 /doctor로 시작합니다.

2. command not found는 대부분 설치 폴더 ~/.local/bin이 PATH에 없어서 생기고, npm 설치는 v2.1.198부터 Node.js 22 이상을 요구합니다.

3. 세션이 멈추면 Ctrl+C 뒤 같은 폴더에서 claude --resume으로 대화를 이어 가고, 원인을 가릴 때는 사용자 설정을 모두 끈 claude --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