클로드 코드 오류 해결: command not found부터 권한 문제까지 정리

클로드 코드 오류 해결 핵심 흐름 이미지 — 처음에는 모든 오류를 한 번에 해결하려 하기보다, 자주 막히는 지점을 순서대로 확인하는 편이 빠릅니다.

클로드 코드(Claude Code)를 처음 설치하고 나서 가장 많이 검색하게 되는 건 멋진 기능보다도 왜 안 되는지입니다. claude 명령어가 안 잡히거나, 로그인 이후 실행이 꼬이거나, 권한 승인 팝업이 너무 자주 떠서 흐름이 끊기는 경우가 특히 많습니다.

이 글은 그런 상황을 대비한 클로드 코드 오류 해결 정리입니다. 오류 메시지를 무작정 쫓기보다, 초반에 자주 막히는 원인을 기준으로 차근차근 확인하는 흐름으로 구성했습니다.

Table of Contents

가장 먼저 확인할 것 4가지

클로드 코드 오류 해결 체크리스트 이미지 — 오류가 나도 이 순서로 보면 대부분 빨리 정리됩니다.

Node.js와 npm이 정상인지 확인
claude와 claude doctor가 실행되는지 확인
/login, /permissions 상태 점검
현재 프로젝트 폴더와 추가 디렉터리 범위 확인

이 네 가지만 먼저 봐도, 어디서 문제가 생겼는지 범위를 꽤 빨리 좁힐 수 있습니다.

1. claude 명령어가 안 될 때

설치는 했는데 claude 명령어가 안 잡히는 경우가 있습니다. 이때는 보통 설치 자체보다 Node.js / npm 환경이나 현재 셸 반영 문제가 더 많습니다.

node --version
npm --version
claude

먼저 Node.js와 npm 버전이 정상적으로 나오는지 확인하고, 설치 직후라면 터미널을 완전히 다시 열어보는 편이 좋습니다. 전역 설치가 끝났더라도 현재 세션에 경로 반영이 늦는 경우가 있기 때문입니다.

이미 설치를 마쳤다면 claude doctor로 현재 상태를 같이 점검해보는 편이 빠릅니다.

claude doctor

2. 로그인 이후 실행이 이상할 때

처음 로그인 이후에 세션이 꼬이거나, 인증 상태가 애매하게 남아서 실행이 매끄럽지 않은 경우도 있습니다. 이럴 때는 무작정 다시 설치하기보다 로그인 흐름부터 다시 확인하는 편이 낫습니다.

/login

대화형 세션 안에서 다시 로그인 상태를 정리해보고, 문제가 계속되면 터미널을 다시 시작한 뒤 재시도하는 쪽이 일반적으로 더 빠릅니다.

3. 권한 승인 팝업이 너무 자주 뜰 때

오류처럼 느껴지지만, 실제로는 권한 설정이 아직 맞지 않은 경우가 많습니다. 파일 읽기와 간단한 분석 정도는 되는데, 편집이나 실행 단계에서 계속 멈춘다면 /permissions를 먼저 확인하는 편이 좋습니다.

/permissions

이때 중요한 건 권한을 전부 넓게 푸는 것이 아니라, 반복되는 승인만 줄이는 방향으로 정리하는 것입니다. 자주 하는 작업은 조금 덜 끊기게 하고, 영향이 큰 변경은 계속 확인을 남겨두는 편이 안전합니다.

이 부분은 아래 글에서 더 자세히 정리해두었습니다.

클로드 코드 권한 설정 방법

4. 프로젝트 바깥 폴더를 못 읽을 때

이 경우도 권한 문제로 느껴지기 쉽지만, 실제로는 작업 범위 설정 문제일 때가 많습니다. 다른 폴더를 함께 읽혀야 한다면 /add-dir로 범위를 추가하는 것이 더 정확합니다.

/add-dir ../shared-lib

예를 들어 메인 프로젝트와 공용 라이브러리를 같이 봐야 하거나, 문서 폴더와 코드 폴더를 함께 확인해야 할 때 유용합니다. 권한을 무작정 넓히기보다, 필요한 디렉터리만 추가하는 편이 관리가 쉽습니다.

5. 설정을 바꿨는데 적용이 안 되는 것 같을 때

클로드 코드는 전역 설정, 프로젝트 설정, 로컬 설정이 겹칠 수 있습니다. 그래서 값을 바꿨는데도 반응이 없다고 느껴질 때가 있습니다.

~/.claude/settings.json
.claude/settings.json
.claude/settings.local.json

처음에는 이 셋을 동시에 많이 건드리지 말고, 어떤 파일이 현재 작업에 적용되고 있는지부터 정리하는 편이 좋습니다.

6. 처음에는 어떤 순서로 점검하면 좋을까

오류가 보이면 아래 순서로 보는 편이 가장 덜 복잡합니다.

환경 확인: node, npm, claude
상태 점검: claude doctor
로그인 확인: /login
권한 확인: /permissions
범위 확인: /add-dir

이 순서를 잡아두면 원인을 훨씬 빨리 좁힐 수 있습니다. 처음부터 세팅 파일 전체를 뒤지는 방식은 오히려 더 헷갈릴 때가 많습니다.

자주 헷갈리는 부분

다시 설치하면 해결되나요?
항상 그렇지는 않습니다. 초반 문제의 상당수는 설치보다 세션, 로그인, 권한, 작업 범위 쪽에 있습니다.

doctor는 언제 쓰면 좋나요?
명령어는 있는데 동작이 이상하거나, 어디서 꼬였는지 감이 안 올 때 가장 먼저 써볼 만합니다.

권한을 넓히면 오류가 다 없어지나요?
아닙니다. 반복 팝업은 줄일 수 있지만, 작업 범위 문제나 로그인 문제는 별도로 봐야 합니다.

정리

클로드 코드 오류 해결은 메시지를 하나씩 외우는 방식보다, 환경 확인 -> doctor -> 로그인 -> 권한 -> 작업 범위 순서로 보는 편이 훨씬 현실적입니다.

처음에는 claude doctor와 /permissions, /add-dir 이 세 가지를 먼저 익혀두면 대부분의 초반 문제를 훨씬 덜 헤매고 정리할 수 있습니다.