Claude Code /doctor로 설정 문제 한 번에 진단하기

Claude Code 입문

Claude Code를 설치했는데 뭔가 안 돼요. 에러 메시지를 검색해봐도 답이 안 나와요. 이럴 때 /doctor 명령어 하나면 30초 안에 원인을 찾을 수 있어요.

📌 3줄 요약

• /doctor는 Claude Code 환경 전체(Node.js·API 키·네트워크)를 자동으로 진단해주는 내장 명령어예요.
• 초록색 ✓ / 빨간색 ✗ 표시로 문제 항목을 직관적으로 파악하고, 해결 방향까지 안내받을 수 있어요.
• /doctor로 해결이 안 되면 캐시 초기화 → 재설치 → GitHub Issues 순서로 대응하면 돼요.

🗂️ 목차

• 1. /doctor 명령어가 하는 일
• 2. /doctor 실행 방법과 출력 결과 읽기
• 3. 자주 나오는 진단 항목별 해결법
• 4. /doctor로 해결되지 않을 때 다음 단계

/doctor 명령어가 하는 일

Claude Code를 설치하고 나서 실행이 안 되거나, 갑자기 동작이 이상해질 때가 있어요. 이런 상황에서 문제 원인을 하나씩 찾아다니면 시간이 오래 걸려요. 에러 메시지를 복사해서 검색하고, 스택오버플로우 답변을 따라해보고, 그래도 안 되면 다시 검색하는 과정을 반복하게 돼요. 초보자일수록 에러 메시지 자체가 낯설기 때문에, 어디서부터 손을 대야 할지 막막한 경우가 많아요.

/doctor 명령어는 Claude Code 환경 전체를 자동으로 점검해주는 진단 도구예요. Node.js 버전, API 키 설정, 네트워크 연결, 권한 문제 등을 한꺼번에 확인해 줘요. 사람이 하나씩 체크해야 할 항목을 명령어 하나로 전부 돌려주는 것이라서, 진단 시간을 크게 줄여줘요.

🔍 병원에서 건강검진을 받는 것과 비슷하다고 생각하면 돼요. 어디가 아픈지 모를 때, 전체 검사를 먼저 돌려보는 것과 같은 원리예요. 검사 결과를 보고 어떤 항목에 문제가 있는지 파악한 다음, 그 부분만 집중적으로 치료하는 거예요.

이 명령어는 Claude Code CLI에 내장되어 있어서, 별도 설치 없이 바로 사용할 수 있어요. 터미널(terminal)에서 Claude Code를 실행할 수 있는 환경이라면 Windows, Mac, Linux 어디서든 동일하게 작동해요. 특별한 관리자 권한도 필요 없기 때문에, 누구나 부담 없이 실행해볼 수 있어요.

💬 제가 직접 써보니, 에러 메시지를 구글에 검색하는 것보다 /doctor를 먼저 돌리는 게 훨씬 빨랐어요. 특히 설치 직후 "뭔가 안 되는데 뭐가 문제인지 모르겠다"는 상황에서 가장 유용했어요. 문제 원인을 30초 안에 특정할 수 있다는 점이, 이 명령어의 가장 큰 가치라고 생각해요.

/doctor 실행 방법과 출력 결과 읽기

사용법은 아주 간단해요. Claude Code 대화창에서 /doctor를 입력하고 엔터를 누르면 돼요. 별도의 옵션이나 추가 인자(argument) 없이, 명령어 하나만 입력하면 자동으로 전체 진단이 시작돼요. 실행하는 데 보통 5~10초 정도 걸리니, 잠깐만 기다리면 결과가 쭉 출력돼요.

 

실행하면 각 항목을 순서대로 점검하면서 결과를 보여줘요. 정상이면 초록색 체크(✓) 표시가, 문제가 있으면 빨간색 엑스(✗) 표시가 나타나요. 이 색상 구분 덕분에 텍스트를 꼼꼼히 읽지 않아도, 어디에 문제가 있는지 직관적으로 알 수 있어요. 프로그래밍에 익숙하지 않은 분도 초록색과 빨간색만 구분하면 현재 상태를 바로 파악할 수 있어요.

출력 결과는 크게 세 영역으로 나뉘어요.

영역	점검 내용
시스템 환경	Node.js 버전, OS 정보
인증 상태	API 키 유효성
네트워크 연결	API 서버 접속 가능 여부

이 세 가지가 Claude Code가 정상 작동하기 위한 핵심 조건이라서, /doctor도 이 순서대로 검사해요.

각 항목 옆에는 간단한 설명도 함께 출력돼요. 예를 들어 Node.js 버전이 낮으면 "Node.js >= 18 required"처럼 필요한 조건을 구체적으로 알려줘요. 단순히 "실패"라고만 표시하는 게 아니라, 어떤 조건이 충족되지 않았는지까지 보여주기 때문에 해결 방향을 바로 잡을 수 있어요.

 

💬 제가 처음 /doctor를 실행했을 때, Node.js 버전 문제가 바로 잡혔어요. 에러 로그를 한 줄씩 읽는 것보다 시각적으로 한눈에 파악되는 점이 가장 큰 장점이라고 느꼈어요. 처음 접하는 분이라도 결과 화면만 보면 "아, 여기가 문제구나" 하고 바로 이해할 수 있을 거예요.

자주 나오는 진단 항목별 해결법

가장 흔한 문제는 Node.js 버전이 낮은 경우예요. Claude Code는 Node.js 18 이상이 필요하므로, node -v로 현재 버전을 확인하고 업데이트해야 해요. 만약 14나 16 버전이 출력된다면, 최신 LTS 버전으로 교체해야 /doctor 진단을 통과할 수 있어요.

 

Node.js 업데이트 방법

1

공식 사이트(nodejs.org)에서 LTS 버전을 다운로드해요.

2

Windows라면 설치 파일을 실행하고, 기존 버전 위에 덮어씌우면 자동으로 교체돼요. Mac이라면 brew install node@20 같은 명령어로도 간편하게 설치할 수 있어요.

3

설치 후 터미널을 껐다가 다시 열어야 새 버전이 인식돼요.

💡 설치 후 터미널을 반드시 재시작해야 새 버전이 인식돼요. 이 점을 놓쳐서 "업데이트했는데 왜 그대로지?" 하는 경우가 많아요.

두 번째로 많은 문제는 API 키 인증 실패예요. 환경변수(environment variable)에 ANTHROPIC_API_KEY가 제대로 설정되어 있는지 확인해 보세요. API 키는 Anthropic 콘솔(console.anthropic.com)에서 발급받을 수 있고, sk-ant-로 시작하는 긴 문자열이에요. 이 키가 환경변수에 등록되어 있지 않으면 Claude Code는 API 서버와 통신할 수 없어요.

⚠️ 키 값이 올바르게 들어가 있어도 실패할 수 있어요. 앞뒤에 공백이 포함되어 있거나, 따옴표가 잘못 들어간 경우가 의외로 많아요. 특히 키를 복사·붙여넣기할 때, 줄바꿈 문자(\n)가 함께 복사되는 실수가 자주 발생해요. 눈에 보이지 않는 문자이기 때문에 찾기가 어려운데, 텍스트 에디터에 붙여넣어서 확인하면 발견할 수 있어요.

세 번째는 네트워크 관련 문제예요. 회사나 학교 네트워크에서 프록시(proxy) 설정 때문에 API 서버에 접속하지 못하는 경우가 있어요. 방화벽(firewall)이 외부 API 호출을 차단하고 있다면, 아무리 설정을 바꿔도 연결이 되지 않아요.

이때는 HTTPS_PROXY 환경변수를 설정하거나, 네트워크 관리자에게 api.anthropic.com 도메인 허용을 요청해야 해요. VPN을 사용 중이라면, VPN을 끄고 다시 시도해보는 것도 방법이에요. 개인 핫스팟으로 연결해서 테스트해보면, 네트워크 문제인지 다른 문제인지 빠르게 구분할 수 있어요.

 

💬 제가 직접 겪었던 사례인데, API 키를 복사할 때 마지막에 줄바꿈 문자가 포함되어 인증에 실패했어요. 눈에 보이지 않는 문자 때문에 한참 헤맸으니, 키 설정 후에는 /doctor로 바로 확인하는 습관을 들이는 게 좋아요.

/doctor로 해결되지 않을 때 다음 단계

/doctor가 모든 항목에 초록색 체크를 보여주는데도 문제가 계속될 수 있어요. 이런 경우는 /doctor가 점검하지 않는 영역에서 문제가 발생하고 있을 가능성이 높아요. 예를 들어 프로젝트별 설정 파일 충돌이나, 특정 파일 권한 문제처럼 환경 진단으로 잡히지 않는 원인이 있을 수 있어요. 이 경우에는 Claude Code의 캐시를 초기화하는 것을 먼저 시도해 보세요.

 

🔍 캐시(cache)란 Claude Code가 빠른 응답을 위해 임시로 저장해두는 데이터를 말해요. 이 데이터가 꼬이거나 오래된 정보가 남아 있으면 예상치 못한 오류가 발생할 수 있어요. 캐시 초기화 후에는 첫 실행이 약간 느려질 수 있지만, 기존 설정이나 대화 내용이 삭제되는 것은 아니니 안심하세요.

claude --clear-cache 명령어로 캐시를 비울 수 있어요.

그래도 안 된다면 Claude Code를 완전히 삭제하고 다시 설치하는 것이 가장 확실해요.

재설치 절차

1

npm uninstall -g @anthropic-ai/claude-code로 기존 버전을 제거해요.

2

npm install -g @anthropic-ai/claude-code로 깨끗한 상태에서 재설치해요.

3

API 키만 다시 설정하면 바로 사용할 수 있어요. 이전에 만들었던 프로젝트 파일이나 코드에는 영향을 주지 않아요.

재설치 후에도 동일한 문제가 반복된다면, GitHub Issues 페이지에 증상을 보고하는 것을 추천해요. /doctor 실행 결과를 함께 첨부하면, 개발팀이 문제를 훨씬 빠르게 파악할 수 있어요. 이슈를 작성할 때는 운영체제, Node.js 버전, /doctor 결과 스크린샷을 함께 올리면 답변을 받을 확률이 높아져요. 다른 사용자가 이미 같은 문제를 보고했을 수도 있으니, 이슈 검색을 먼저 해보는 것도 좋은 방법이에요.

💬 제가 직접 써보니, /doctor를 먼저 돌리고 그 결과를 기반으로 다음 행동을 결정하는 패턴이 가장 효율적이었어요. 문제 해결의 시작점을 /doctor로 잡으면, 불필요한 삽질을 크게 줄일 수 있어요. "일단 /doctor부터"라는 습관 하나만 들여도, Claude Code 트러블슈팅 시간이 절반 이하로 줄어들 거예요.

✍️ 마치며

Claude Code가 갑자기 동작하지 않을 때, 가장 먼저 할 일은 /doctor를 실행하는 거예요. 30초 안에 Node.js 버전, API 키, 네트워크 문제를 한눈에 파악할 수 있고, 해결 방향까지 안내받을 수 있어요. /doctor로 해결되지 않을 때는 캐시 초기화 → 재설치 → GitHub Issues 순서로 대응하면 대부분의 문제를 해결할 수 있어요. "일단 /doctor부터" — 이 습관 하나면 충분해요.