클로드 코드 자주 나는 문제와 해결 (설치, 로그인, 멈춤)
클로드 코드 문제 해결은 화면에 나온 증상과 오류 문구로 막힌 곳이 설치, 로그인, 세션 가운데 어디인지 먼저 정하고, 그곳을 확인하는 명령(claude --version, claude doctor, claude auth status, /doctor)부터 실행해 원인을 좁히는 일입니다.
같은 말:클로드 오류클로드 로그인 안됨클로드 안됨claude 오류클로드 코드 오류클로드 코드 로그인클로드 인증 실패클로드 코드 로그인 풀림클로드 코드 먹통클로드 코드 멈춤claude doctorclaude command not found
이 글은 2026년 10월 25일 기준 Claude Code 공식 문서(Troubleshooting, Troubleshoot installation and login, Error reference, Debug your configuration)와, 같은 날 macOS 터미널에서 Claude Code v2.1.310으로 연습 폴더 오류-연습을 다뤄 본 화면을 근거로 씁니다. 연습 폴더에는 주간보고.txt 한 파일만 두었습니다.
클로드 코드 자주 나는 문제와 해결
TV가 안 나오면 증상부터 보듯
Claude Code 문제도 증상으로 먼저 볼 곳을 정합니다
Claude Code를 쓰다 보면 명령을 찾을 수 없다는 문구, 로그인하라는 문구, 답이 나오다 멈춘 화면을 만납니다. 세 증상은 고치는 곳이 서로 달라서, 증상과 맞지 않는 방법(다시 설치하기, 설정 지우기)을 따라 하면 시간만 쓰고 설정을 잃을 수 있습니다.
거실 TV가 안 나올 때 증상을 보고 먼저 볼 곳을 정하는 일과 같습니다. 증상 버튼을 누르면 TV 그림과, 같은 증상일 때의 Claude Code 실제 화면이 함께 바뀝니다.
거실 TV
증상 고르기
증상 버튼을 누르면 결과 카드에 먼저 볼 곳이 나옵니다.
Claude Code에서는
증상 버튼을 누르면 같은 증상일 때 Claude Code에 나오는 실제 화면이 이 판에 나옵니다.
Claude Code도 증상마다 먼저 볼 곳이 다릅니다. 명령을 찾지 못한다는 문구가 나오면 설치와 PATH를 봅니다. 로그인하라는 문구가 나오면 claude.ai 계정 로그인을 봅니다. 답이 멈추면 세션을 멈추고 다시 여는 방법을 씁니다.
| 거실 TV | Claude Code |
|---|---|
| TV를 보는 사람 | Claude Code에 요청을 보내는 사용자입니다 |
| TV | 내 컴퓨터에 설치한 Claude Code 프로그램입니다 |
| 빠진 전원 플러그 | 터미널이 claude 명령을 찾지 못하는 상태입니다 |
| 영상 앱의 로그인 화면 | Claude Code가 claude.ai 계정 로그인을 다시 요청하는 상태입니다 |
| 재생 중 멈춘 영상 | 응답 도중 멈춘 세션(Claude Code를 시작해 마칠 때까지 이어지는 대화)입니다 |
| 정지 버튼으로 멈춰 보기 | 입력창에서 Esc를 눌러 응답을 멈추는 일입니다 |
| 앱을 닫았다가 다시 열어 이어 보기 | /exit로 마친 뒤 셸에서 claude --continue로 지난 대화를 다시 여는 일입니다 |
Claude Code 문제 해결은 화면에 나온 증상과 오류 문구로 막힌 곳(설치, 로그인, 세션)을 먼저 정하고, 그곳을 확인하는 명령부터 실행하는 일입니다.
TV 그림은 세 증상을 설명하려고 그린 비유입니다. Claude Code 판의 화면은 2026년 10월 25일 macOS 터미널에서 Claude Code v2.1.310으로 실행한 결과이고, Windows PowerShell 문구는 공식 문서 Troubleshoot installation and login에서 옮겼습니다. 로그인 상태 화면은 Claude Code 설정 폴더를 빈 폴더로 지정해 로그인하지 않은 상태로 실행했습니다.
어디서 막혔는지 모르면 진단 명령 세 개를 순서대로 실행합니다
진단 명령은 설치, 설정, 세션 가운데 어디에 문제가 있는지 알려 주는 명령입니다. 앞의 두 명령은 Claude Code를 시작하지 않은 셸(터미널이나 PowerShell에서 명령을 받는 프로그램)에서 실행하고, 마지막 명령은 Claude Code 입력창에서 실행합니다. 버튼을 차례로 누르면 실제 화면과 그 화면으로 알 수 있는 것이 나옵니다.
순서대로 눌러 보기
버튼을 누르면 결과 카드에 화면의 뜻이 나옵니다.
버튼을 누르면 터미널에 실제 화면이 나옵니다.
확인한 것
claude 명령을 찾는지?
설치와 설정 파일?
확장 기능, CLAUDE.md, 권한?
1번과 2번은 2026년 10월 25일 macOS 터미널에서 Claude Code v2.1.310으로 실행한 화면이고, claude doctor 결과는 다섯 줄만 옮겼습니다. /doctor는 Claude가 설정을 바꾸자고 제안하는 명령이라 공식 문서 원문으로 대신했습니다.
로그인 문제는 화면에 나온 문구로 할 일을 고릅니다
Claude Code는 claude.ai 계정(Pro, Max, Team, Enterprise 구독)이나 Anthropic Console 계정으로 로그인해서 씁니다. 로그인 문제는 화면에 나온 문구마다 원인과 할 일이 다릅니다. 버튼을 누르면 그 문구가 나온 화면과 다음에 할 일이 나옵니다.
문구 고르기
버튼을 누르면 결과 카드에 원인과 할 일이 나옵니다.
버튼을 누르면 그 문구가 나온 화면이 나옵니다.
1번은 2026년 10월 25일 Claude Code v2.1.310에서 설정 폴더를 빈 폴더로 지정해 로그인하지 않은 상태로 실행한 화면입니다. 2번과 3번 문구는 공식 문서 Error reference와 Troubleshoot installation and login의 원문입니다.
답이 멈추면 멈추고, 마치고, 같은 폴더에서 다시 엽니다
연습 폴더 오류-연습에서 Claude Code를 시작하고 "주간보고.txt를 읽고 다음 주 할 일을 다섯 줄로 제안해 줘. 파일은 고치지 마"를 보낸 뒤, 답이 나오는 동안 아래 버튼을 차례로 누릅니다. 세 번째 버튼까지 누르면 멈췄던 대화가 그대로 다시 열립니다.
순서대로 눌러 보기
버튼을 누르면 결과 카드에 화면의 뜻이 나옵니다.
버튼을 누르면 터미널에 실제 화면이 나옵니다.
지금 상태
Claude Code 세션답하는 중
대화 기록남아 있음
2026년 10월 25일 macOS 터미널에서 Claude Code v2.1.310으로 실행한 화면입니다. 세션 ID는 줄였고, 이 계정의 상태 표시줄 줄은 기본 화면과 달라 옮기지 않았습니다.
오류 문구로 어느 쪽에서 생긴 문제인지 나눕니다
응답 대신 영어 오류 문구가 나오면, 문구로 문제가 생긴 곳을 나눌 수 있습니다. Anthropic 서비스, 내 플랜의 사용 한도, 내 컴퓨터의 인터넷 연결 가운데 어디인지에 따라 할 일이 다릅니다. 버튼을 누르면 문제가 생긴 곳에 불이 들어옵니다.
문구 고르기
버튼을 누르면 결과 카드에 원인과 할 일이 나옵니다.
버튼을 누르면 오류 문구가 나옵니다.
Anthropic 서비스
내 플랜의 사용 한도
내 컴퓨터와 인터넷 연결
세 문구는 2026년 10월 25일 공식 문서 Error reference의 원문이고, 3:45pm은 문서에 적힌 예시 시각입니다.
클로드 코드 자주 나는 문제와 해결을 정리하면 이렇습니다
- 1
Claude Code가 안 될 때는 화면의 문구로 막힌 곳(설치, 로그인, 세션)을 먼저 정하고, 어디인지 모르면 셸에서
claude --version과claude doctor를, 입력창에서/doctor를 차례로 실행합니다. - 2
command not found가 나오면 새 터미널 창에서 다시 확인하고, 같은 문구가 나오면 설치 폴더가 PATH에 있는지 봅니다. - 3
로그인하라는 문구가 나오면
claude auth status --text로 상태를 보고/login으로 다시 로그인하며, 로그인이 자주 풀리면 컴퓨터 시각을 봅니다. - 4
답이 멈추면
Esc나Ctrl+C로 멈춥니다. 터미널 창을 닫았더라도 새 터미널 창에서 작업하던 폴더로 이동한 뒤claude --continue를 실행하면 대화가 다시 열립니다.
클로드 코드 오류가 나면 무엇부터 확인하나요?
화면에 나온 문구를 그대로 읽고, 그 문구가 가리키는 곳 하나를 먼저 확인합니다. command not found처럼 명령을 찾지 못한다는 문구는 설치와 PATH를 가리킵니다. Please run /login이 붙은 문구는 로그인을 가리킵니다. API Error로 시작하는 문구는 Anthropic 서비스나 내 플랜의 사용 한도를 가리킵니다. 문구가 없거나 어디인지 모르겠으면 새 터미널에서 claude --version을 입력하고, 버전 번호가 나오면 claude doctor를 실행합니다.
공식 문서도 증상에 따라 문서를 나눠 둡니다. 설치와 로그인은 Troubleshoot installation and login, 설정이 적용되지 않는 문제는 Debug your configuration, API Error로 시작하는 문구는 Error reference, 느려지거나 멈추는 문제는 Troubleshooting 문서가 다룹니다. 이 글은 네 문서에서 자주 만나는 증상을 골라 순서대로 정리합니다. Claude Code를 처음 설치하는 단계라면 입문 코스의 클로드 코드 설치 방법을 먼저 봅니다.
먼저 쓰는 진단 명령
진단 명령은 어디에 문제가 있는지 알려 주는 명령입니다. 셸(터미널이나 PowerShell에서 명령을 받는 프로그램)에서 실행하는 명령과 Claude Code 입력창에서 입력하는 명령이 나뉩니다.
| 명령 | 입력하는 곳 | 하는 일 |
|---|---|---|
claude --version | 셸 | 버전 번호(예: 2.1.310 (Claude Code))가 나오면 셸이 Claude Code를 찾은 상태입니다 |
claude doctor | 셸 | Claude Code를 시작하지 않고 설치 상태와 설정 파일 오류를 읽기만 해서 보여 줍니다 |
claude auth status --text | 셸 | 로그인 방식이나 Not logged in 같은 로그인 상태를 보여 줍니다 |
/doctor | Claude Code 입력창 | 설치, 설정, 확장 기능, CLAUDE.md, 권한을 점검하고, 사용자가 승인하면 고칩니다 |
/status | Claude Code 입력창 | 버전, 모델, 계정, 연결 상태와 지금 쓰이는 설정의 출처를 보여 줍니다 |
claude --safe-mode | 셸 | CLAUDE.md, 스킬, 플러그인, 훅, MCP 서버를 끈 채 시작합니다. 로그인, 모델, 기본 도구, 권한은 그대로입니다 |
순서는 셸에서 claude --version, claude doctor를 먼저 실행하고, Claude Code가 시작되면 입력창에서 /doctor를 입력하는 것입니다. 2026년 10월 25일 Claude Code v2.1.310에서 claude doctor를 실행하면 Running: native (2.1.310), Search: OK (bundled), Last update attempt: success 같은 줄 뒤에 No installation issues found.가 나왔습니다. /doctor는 찾은 문제를 먼저 보고하고 무엇이든 바꾸기 전에 확인을 받습니다.
claude --safe-mode는 직접 붙인 설정 가운데 무엇이 문제인지 가려낼 때 씁니다. 이 모드에서 문제가 사라지면 꺼 둔 CLAUDE.md, 스킬, 훅, MCP 서버 가운데 원인이 있으므로 하나씩 다시 켜 보며 찾습니다. 조직이 정한 관리 설정 정책은 이 모드에서도 그대로 적용됩니다.
설치했는데 claude 명령을 못 찾을 때
claude를 입력했을 때 아래 문구가 나오면 셸이 Claude Code 프로그램을 찾지 못한 것입니다.
| 운영체제와 프로그램 | 화면에 나오는 문구 |
|---|---|
| macOS 터미널 | zsh: command not found: claude |
| Linux 터미널 | bash: claude: command not found |
| Windows CMD | 'claude' is not recognized as an internal or external command |
| Windows PowerShell | claude : The term 'claude' is not recognized as the name of a cmdlet |
먼저 터미널이나 PowerShell 창을 새로 열고 claude --version을 다시 입력합니다. 설치 명령을 실행한 창은 설치 전의 PATH(셸이 명령을 찾아보는 폴더 목록)를 그대로 쓰기 때문입니다.
새 창에서도 같은 문구가 나오면 설치 파일이 있는지와 그 폴더가 PATH에 있는지 봅니다. 공식 설치 명령은 macOS에서 ~/.local/bin/claude에 파일을 둡니다. Windows에서는 %USERPROFILE%\.local\bin\claude.exe에 파일을 둡니다. macOS의 zsh에서 이 폴더가 PATH에 없으면 echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc를 실행한 뒤 터미널 창을 새로 엽니다. Windows에서 PATH에 폴더를 더하는 방법은 클로드 코드 설치 방법의 설치 오류 절과 준이아빠블로그의 클로드 코드 설치 오류 해결에 있습니다.
VS Code 확장만 설치했다면 터미널에서 claude를 찾지 못하는 것이 정상입니다. 확장은 Claude Code 사본을 확장 폴더 안에 두고 PATH에 넣지 않으므로, 터미널에서 쓰려면 공식 설치 명령으로 따로 설치합니다.
클로드 코드 로그인이 안 될 때
Claude Code는 claude.ai 계정(Pro, Max, Team, Enterprise 구독)이나 Anthropic Console 계정으로 로그인합니다. 원인을 알 수 없는 로그인 실패는 Claude Code 입력창에서 /logout을 입력하고 Claude Code를 닫은 뒤, 셸에서 claude로 다시 시작해 로그인하면 대부분 풀린다고 공식 문서가 안내합니다. /logout은 저장된 MCP 서버 로그인도 함께 지우므로, 다시 로그인한 뒤 MCP 서버 인증도 새로 합니다.
| 화면에 나온 문구 | 원인 | 할 일 |
|---|---|---|
Not logged in, Please run /login | 쓸 수 있는 로그인 정보가 없습니다 | 입력창에 /login을 입력하거나 셸에서 claude auth login을 실행합니다 |
Login expired, Please run /login | 저장된 로그인을 갱신하지 못해 Claude Code가 지웠습니다 | /login으로 다시 로그인합니다. 로그인하지 않고 다시 보내면 같은 문구가 계속 나옵니다 |
OAuth error: Invalid code. Please make sure the full code was copied | 로그인 코드가 만료되었거나 복사하다 잘렸습니다 | Enter 키로 다시 시작해 빨리 마칩니다. 브라우저가 열리지 않으면 c 키로 주소를 복사해 브라우저에 붙여 넣습니다 |
API Error: 403 Request not allowed | 로그인은 됐지만 요청이 허락되지 않았습니다 | Pro, Max는 claude.ai/settings에서 구독이 살아 있는지 봅니다. Console 계정은 관리자에게 Claude Code 또는 Developer 역할을 받았는지 묻습니다 |
This organization has been disabled | 구독이 있는데도 예전에 넣어 둔 ANTHROPIC_API_KEY 환경 변수가 구독 로그인보다 먼저 쓰이고 있습니다 | macOS에서는 셸에서 unset ANTHROPIC_API_KEY를 실행합니다. Windows PowerShell에서는 Remove-Item Env:ANTHROPIC_API_KEY를 실행합니다. 그다음 claude로 다시 시작하고 /status로 쓰이는 로그인 방식을 봅니다 |
WSL2, SSH로 접속한 컴퓨터, 컨테이너에서는 브라우저가 다른 컴퓨터에서 열려서 로그인 뒤 화면에 로그인 코드가 나옵니다. 이 코드를 터미널의 Paste code here if prompted 줄에 붙여 넣습니다. 붙여넣기가 되지 않으면 셸에서 claude auth login을 실행해 코드를 붙여 넣습니다.
클로드 코드 로그인이 자꾸 풀리면 무엇을 보나요?
컴퓨터의 날짜와 시각이 맞는지부터 봅니다. 공식 문서는 로그인이 자주 풀리면 시스템 시계가 정확한지 확인하라고 안내합니다. 로그인 정보의 유효 기간 확인이 컴퓨터 시각에 기대기 때문입니다.
macOS에서는 로그인 정보를 키체인(macOS의 암호 보관함)에 저장합니다. 키체인에 쓰지 못하는 상태면 claude doctor 결과에 macOS Keychain is not writable로 시작하는 경고가 나오고, 그 경고 아래에 고치는 방법이 함께 나옵니다. 경고가 없으면 키체인은 원인이 아닙니다.
클로드 코드가 멈추거나 느려질 때
답이 나오다 멈추면 Esc를 누릅니다. Esc는 진행 중인 응답이나 도구 호출을 멈추고, 그때까지 한 작업은 남긴 채 입력창으로 돌아옵니다. 반응이 없으면 Ctrl+C를 누르고, 그래도 멈춰 있으면 터미널 창을 닫습니다. 창을 닫아도 대화 기록은 이 컴퓨터에 남습니다. 새 터미널 창을 열고 cd 오류-연습처럼 작업하던 폴더로 이동한 뒤 claude --continue(가장 최근 대화)나 claude --resume(목록에서 고르기)을 실행하면 대화가 다시 열립니다.
| 증상 | 할 일 |
|---|---|
| 답이 멈추고 입력을 받지 않음 | Esc, 안 되면 Ctrl+C, 그래도 안 되면 창을 닫고, 새 터미널 창에서 작업하던 폴더로 이동한 뒤 claude --continue |
| 메모리 사용이 높다는 경고가 나옴 | Claude Code가 쓰는 메모리가 2.5GB를 넘으면 경고가 나옵니다. Claude Code를 다시 시작하고 claude --continue로 대화를 이어 갑니다 |
| 대화가 길어진 뒤 느려짐 | /compact로 지난 대화를 요약해 줄이고, 큰 작업 사이에는 Claude Code를 다시 시작합니다 |
Autocompact is thrashing 문구 | 자동 압축(지난 대화를 요약해 줄이는 기능)으로 비운 컨텍스트(Claude가 한 번에 기억하는 대화 분량)를 큰 파일이나 도구 출력이 곧바로 다시 채운 상태입니다. 큰 파일을 줄 범위를 정해 나눠 읽게 하고, 지난 대화가 필요 없으면 /clear로 새로 시작합니다 |
| VS Code, Cursor 안의 터미널에서 글자가 깨짐 | Claude Code 입력창에 /terminal-setup을 입력해 편집기 터미널의 GPU 가속을 끕니다 |
/clear는 지금 대화를 비우고 새 대화를 시작하므로, 이어서 필요한 조건과 파일 이름은 먼저 적어 둡니다. 대화 길이와 사용량의 관계는 클로드 코드 비용과 한도 관리에 있습니다.
API Error 오류 문구별 원인과 할 일
API Error로 시작하거나 응답 대신 영어 문구가 나오면, 문구로 문제가 생긴 곳을 나눕니다. Claude Code는 일시적인 실패를 최대 10번까지 자동으로 다시 시도한 뒤에 오류를 보여 줍니다.
| 문구 | 문제가 생긴 곳 | 할 일 |
|---|---|---|
API Error: 500 Internal server error | Anthropic 서비스 | 내 요청이나 설정, 계정 때문이 아닙니다. status.claude.com에서 장애 공지를 보고 1분쯤 뒤 다시 보냅니다 |
API Error: Repeated 529 Overloaded errors | Anthropic 서비스 | 모든 사용자에게 API가 잠시 붐빈다는 뜻이고 사용 한도에 계산되지 않습니다. 몇 분 뒤 다시 보내거나 /model로 다른 모델을 고릅니다 |
You've hit your session limit | 내 플랜의 사용 한도 | 문구 끝의 초기화 시각까지 기다립니다. 세션 한도와 주간 한도는 모든 모델에 함께 적용되므로 모델을 바꿔도 풀리지 않습니다. /usage로 남은 한도를 봅니다 |
Unable to connect to API. Check your internet connection | 내 컴퓨터와 인터넷 연결 | 인터넷, VPN, 회사 프록시를 봅니다. macOS 터미널에서는 curl -I https://api.anthropic.com, Windows PowerShell에서는 curl.exe -I https://api.anthropic.com으로 연결을 확인합니다 |
500과 529는 Anthropic 쪽 문제라서 Claude Code를 다시 설치하거나 설정을 지워도 풀리지 않습니다. 사용 한도 문구와 플랜별 한도는 클로드 코드 비용과 한도 관리에서 자세히 다룹니다.
설정이 적용되지 않을 때
설정이 적용되지 않는 문제는 파일을 엉뚱한 곳에 둔 경우가 많습니다. 공식 문서 Debug your configuration의 흔한 원인 표에서 자주 만나는 것만 옮기면 다음과 같습니다.
| 증상 | 원인 | 할 일 |
|---|---|---|
| 개인 권한 규칙이나 훅이 적용되지 않음 | ~/.claude.json에 적었습니다. 이 파일은 앱 상태와 화면 설정을 담는 파일입니다 | permissions, hooks, env는 ~/.claude/settings.json에 적습니다 |
settings.json의 값이 무시됨 | 같은 설정이 settings.local.json에도 있습니다 | settings.local.json이 settings.json보다 우선하므로 두 파일을 함께 봅니다 |
.mcp.json의 MCP 서버가 뜨지 않음 | 파일을 .claude/ 폴더 안에 두었거나 처음 한 번 승인 창을 닫았습니다 | .mcp.json은 프로젝트 맨 위 폴더에 두고, /mcp에서 상태를 보고 승인합니다 |
설정이 겹쳐 무엇이 쓰이는지 모르겠으면 입력창에서 /status로 지금 쓰이는 설정의 출처를 보고, /permissions, /hooks, /mcp에서 그 항목이 실제로 불러와졌는지 봅니다. MCP 서버별 확인 순서는 클로드 코드 MCP 서버 연결에, 권한 규칙은 클로드 코드 권한 모드와 권한 규칙에 있습니다.
업데이트가 안 될 때
공식 설치 명령으로 설치한 Claude Code(네이티브 설치)는 백그라운드에서 자동으로 업데이트됩니다. Homebrew와 WinGet으로 설치했다면 기본으로 자동 업데이트되지 않으므로 직접 올립니다.
| 설치 방식 | 업데이트 명령 |
|---|---|
| 공식 설치 명령(네이티브) | claude update |
| Homebrew(macOS) | brew upgrade claude-code, claude-code@latest를 설치했다면 brew upgrade claude-code@latest |
| WinGet(Windows) | winget upgrade Anthropic.ClaudeCode |
Claude Code 화면 아래에 빨간 Auto-update failed 줄이 보이면 자동 업데이트가 설치되지 않은 것입니다. 하던 일은 그대로 계속할 수 있고, 업데이트를 마치려면 셸에서 claude update를 실행해 그 결과에 나오는 오류 문구를 봅니다. Homebrew의 claude-code는 대개 일주일쯤 늦은 안정판(stable)을 따르고, claude-code@latest는 새 버전이 나오는 대로 받습니다.
문제를 알리는 방법
여기까지 해도 풀리지 않으면 Claude Code 입력창에서 /bug(줄인 이름 /share)를 입력해 Anthropic에 알립니다. 보낼 대화 범위를 고르고 동의 화면에서 확인해야 전송되므로, 회사 자료가 든 대화는 범위를 줄여서 보냅니다. 제품 의견은 같은 창을 여는 /feedback으로 보냅니다. Claude Code가 아예 시작되지 않으면 GitHub 이슈 목록에서 같은 문제를 찾아보고, 새로 올릴 때는 운영체제, 실행한 설치 명령, 오류 문구 전체를 적습니다.
로그인이 반복해서 풀리거나 구독이 인식되지 않는 것처럼 계정이나 결제 문제라면 Claude Code가 아니라 Anthropic 지원팀에 문의합니다. claude.ai에 로그인한 뒤 왼쪽 아래 이니셜을 누르고 Get help를 고릅니다.
직접 해 보기: 진단 명령과 멈춘 대화 다시 열기
Claude Code가 설치되어 있고 로그인되어 있다면 다음 순서로 연습합니다. 5번에서 요청을 보내므로 계정의 사용량이 조금 듭니다.
- 홈 폴더에 빈 폴더
오류-연습을 만들고, 텍스트 편집기(Windows는 메모장, macOS는 텍스트 편집기)로주간보고.txt에주간보고,날짜: 10월 27일,매출: 120만 원세 줄을 저장합니다. - 터미널(Windows는 PowerShell) 창을 새로 열고
claude --version을 입력합니다.2.1.310 (Claude Code)처럼 버전 번호가 나오면 3번으로 갑니다. 터미널을 여는 법은 터미널과 CLI에 있습니다. - 같은 창에서
claude doctor를 입력하고, 마지막 부분에No installation issues found.가 나오는지 봅니다. 경고가 있으면 그 줄을 메모해 둡니다. claude auth status --text를 입력해Login method:줄에 로그인 방식이 나오는지 봅니다.cd 오류-연습을 입력해 폴더로 이동한 뒤claude를 실행하고, 폴더 신뢰 창에서 Yes, I trust this folder를 고릅니다. "주간보고.txt를 읽고 다음 주 할 일을 다섯 줄로 제안해 줘. 파일은 고치지 마"를 보냅니다. 화면에Listed 1 directory줄이 나타나면 바로Esc를 눌러Interrupted줄이 나오는지 봅니다.- 입력창에
/exit를 입력해 Claude Code를 마칩니다. 셸에Resume this session with:줄이 나오면 같은 창에서claude --continue를 실행해, 5번의 요청과Interrupted줄이 그대로 다시 열리는지 봅니다. - 확인했으면
/exit로 마칩니다.
2번에서 command not found가 나오면 이 글의 "설치했는데 claude 명령을 못 찾을 때" 절로, 4번에서 Not logged in이 나오면 "클로드 코드 로그인이 안 될 때" 절로 갑니다.
자주 묻는 질문
claude doctor와 /doctor는 무엇이 다른가요?
claude doctor는 셸에서 실행하고, Claude Code를 시작하지 않은 채 설치 상태와 설정 파일 오류를 읽기만 해서 보여 줍니다. /doctor는 Claude Code 입력창에서 입력하고, 설치와 설정에 더해 확장 기능, CLAUDE.md, 권한까지 점검한 뒤 고칠 안을 제안해 사용자가 승인한 것만 고칩니다. Claude Code가 아예 시작되지 않으면 claude doctor를 씁니다.
529 Overloaded 오류도 사용 한도에 계산되나요?
계산되지 않습니다. 공식 문서 Error reference는 529 오류를 모든 사용자에게 API가 잠시 붐비는 상태로 설명하고, 사용 한도가 아니며 할당량에서 빠지지 않는다고 적습니다. 몇 분 뒤 다시 보내거나 /model로 다른 모델을 고르면 계속 쓸 수 있습니다.
다시 설치하면 로그인 문제도 풀리나요?
로그인 문제는 다시 설치할 필요가 없습니다. claude --version이 버전 번호를 보여 주면 설치는 정상이므로, claude auth status --text로 로그인 상태를 보고 /login이나 claude auth login으로 다시 로그인합니다. 원인을 모르겠으면 /logout 뒤 Claude Code를 닫고 claude로 다시 시작해 로그인합니다.
참고 자료
- Claude Code 공식 문서: Troubleshooting(멈춤, 메모리, 검색, 증상별 문서 안내)
- Claude Code 공식 문서: Troubleshoot installation and login(명령을 못 찾음, PATH, 로그인 오류)
- Claude Code 공식 문서: Error reference(API 오류, 사용 한도, 로그인 만료)
- Claude Code 공식 문서: Debug your configuration(설정 파일 위치와 흔한 원인)
- Claude Code 공식 문서: CLI reference(claude doctor, claude auth status, --continue, --safe-mode)
- Claude Code 공식 문서: Commands(/doctor, /status, /bug, /feedback)
- Claude Code 공식 문서: Set up Claude Code(업데이트)
제대로 이해했는지 한 문제로 확인해 볼까요?
답을 고르면 바로 풀이가 나와요.
새로 연 터미널에서 claude --version을 입력하면 버전 번호가 나오는데, Claude Code를 시작해 요청을 보내면 Login expired 문구가 나옵니다. 먼저 할 일은 무엇일까요?
예제나 확인 질문을 직접 시도한 뒤 완료 표시해요. 더 연습할 내용이 남으면 표시하지 않고 다음 글을 읽어도 됩니다. 완료 버튼은 이해도를 채점하지 않으며 잘못 표시하면 취소할 수 있어요.
