claude doctor는 클로드 코드(Claude Code)를 쓰다가 뭔가 이상할 때 가장 먼저 떠올리면 좋은 명령입니다. command not found처럼 명령 자체가 안 되거나, 로그인 이후 동작이 어색하거나, 지금 환경이 왜 꼬였는지 감이 안 올 때 특히 유용합니다.
이 글은 그래서 claude doctor 사용법을 중심으로, 무엇을 점검하는 명령인지, 언제 먼저 써야 하는지, 결과를 보고 다음에 무엇을 보면 되는지까지 한 흐름으로 정리했습니다.
Table of Contents
claude doctor는 언제 쓰면 좋을까
보통 아래 같은 상황에서 먼저 써볼 만합니다.
- 설치는 했는데 뭔가 실행이 매끄럽지 않을 때
- 환경이 꼬인 것 같은데 원인이 안 보일 때
- 권한이나 로그인 문제를 바로 단정하기 어렵을 때
- 재설치 전에 현재 상태를 먼저 확인하고 싶을 때
즉 문제를 바로 고치는 명령이라기보다, 어디서부터 봐야 할지 알려주는 진단 명령에 가깝습니다.
가장 기본적인 실행 방법
claude doctor처음에는 이 한 줄만 기억하면 됩니다. 설치 뒤 command가 안 될 때는 claude 자체 실행 여부를 먼저 보고, command는 되는데 상태가 이상하면 doctor를 바로 보는 식으로 생각하면 쉽습니다.
doctor로 주로 확인하는 것
- 현재 실행 환경이 정상인지
- Node.js와 npm 쪽 문제를 의심해야 하는지
- 세션이나 권한 쪽에서 추가로 볼 것이 있는지
- 다음에 설정 파일이나 범위를 확인해야 하는지
즉 “뭐가 안 된다”를 바로 고치는 것보다, 문제가 환경인지, 설정인지, 권한인지를 나누는 데 강합니다.
이 순서로 보면 가장 덜 헷갈립니다
claude명령 자체가 되는지 확인claude doctor실행- 필요하면
/login과/permissions확인 - 프로젝트 범위가 문제면
/add-dir점검
처음부터 설정 파일을 전부 뒤지기보다, 이 순서로 보면 문제 범위를 훨씬 빨리 좁힐 수 있습니다.
command not found와는 어떻게 다를까
command not found는 보통 명령 자체를 찾지 못하는 쪽에 가깝고, doctor는 명령이 돌아가는 상태에서 현재 환경을 진단하는 쪽에 가깝습니다. 그래서 두 문제를 같은 것으로 보면 오히려 헷갈릴 수 있습니다.
정리하면 이렇게 생각하면 됩니다.
claude가 아예 안 되면: 설치와 PATH, Node.js 쪽부터claude는 되는데 이상하면:claude doctor부터
doctor 다음에 자주 이어지는 점검
doctor를 보고 나면 보통 아래 중 하나로 이어집니다.
/login재확인/permissions에서 권한 흐름 점검/add-dir로 작업 범위 추가.claude/settings.json계열 우선순위 확인
즉 doctor 하나로 끝난다기보다, 다음 진단 경로를 정리해주는 역할이 큽니다.
재설치 전에 왜 먼저 보는 게 좋을까
초반에는 이상하면 다시 설치하고 싶어지기 쉽습니다. 하지만 실제로는 세션 문제, 설정 충돌, 권한 흐름, 작업 범위 문제인 경우가 더 많습니다. 이런 상황에서 재설치를 먼저 하면 시간만 더 들고 원인은 그대로 남을 수 있습니다.
그래서 doctor는 단순해 보여도 꽤 실전적입니다. 특히 여러 문제를 한꺼번에 의심하기 시작했을 때, 어디부터 봐야 하는지 순서를 잡아주기 때문입니다.
함께 보면 좋은 글
정리
claude doctor 사용법은 복잡하지 않습니다. 하지만 언제 먼저 써야 하는지와, 결과를 본 뒤 어디를 이어서 점검해야 하는지를 알고 있으면 문제 해결 속도가 훨씬 빨라집니다.
클로드 코드가 이상할 때는 재설치보다 먼저 claude doctor부터 확인하는 습관을 들이는 편이 훨씬 현실적입니다.
참고한 공식 문서
- Claude Code common workflows
- Claude Code settings
- Claude Code permissions
