윈도우나 맥에서 다양한 에러를 만날 수 있습니다. 이런 상황을 익숙하게 받아들이셨으면 좋겠습니다. 개발을 하다 보면 매우 자주 마주치는 일이고, 대부분 금방 해결됩니다.

1. Windows 보안 설정 문제

클로드 코드를 실행했을 때 아래와 같은 빨간 글씨 메시지가 나올 수 있습니다.

• npm is not recognized as an internal or external command...
• npm: 이 시스템에서 스크립트를 실행할 수 없으므로...

해결 방법은 다음과 같습니다.

1. PowerShell을 관리자 권한으로 열기

   • 시작 버튼 → PowerShell 검색 → Windows PowerShell 우클릭 → 관리자 권한으로 실행

2. 아래 명령어를 입력합니다.

   Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass
   

3. 아래와 같은 선택지가 나오면 대문자 A 를 입력하고 엔터를 누릅니다.

   [Y] 예  [A] 모두 예  [N] 아니요  [L] 모두 아니요  [S] 일시 중단  [?] 도움말
   

4. 그 창에서 그대로 설치를 다시 시도합니다.

   npm install -g @anthropic-ai/claude-code
   

2. Mac 관리자 권한 문제

npm ERR! Error: EACCES: permission denied, mkdir '파일경로' 같은 에러는 관리자 권한이 필요한 경우입니다. 설치 명령어 앞에 sudo 를 붙이세요.

sudo npm install -g @anthropic-ai/claude-code

비밀번호를 입력할 때 화면에 글자가 보이지 않는 것은 보안상의 이유이니 당황하지 말고 오탈자 없이 입력 후 엔터를 누릅니다.

3. Git을 설치하라는 에러

Windows에서 Git을 설치하지 않았다면 클로드 코드 실행 시 Git을 설치하라는 에러가 나옵니다. https://git-scm.com/ 에서 Git을 받아 기본 설정 그대로 설치하면 해결됩니다.

4. 터미널에서 텍스트가 입력되지 않는 문제

특정 업데이트 이후 일부 환경에서 터미널에 텍스트가 입력되지 않는 문제가 보고된 적이 있습니다. 우회 방법은 다음과 같습니다.

1. VSCode 확장(extension) 사용 — VSCode용 클로드 코드 확장을 쓰면 입력 문제를 피할 수 있습니다(11장 참고). 권장.
2. 명령 프롬프트(cmd) 사용 — PowerShell 대신 명령 프롬프트로 실행하면 입력이 되는 경우가 있습니다.
3. WSL을 설치해 연결합니다.

5. 사용자 계정 이름에 특수 문자가 있는 경우

Windows 사용자 계정 이름에 한글이나 특수 문자가 포함되면 클로드 코드 실행 시 에러가 발생할 수 있습니다. 이 경우 사용자 계정 이름을 영문으로 변경해야 합니다.

6. 모델이 최신이 아닌 경우 / 기타 에러

새 모델이 나왔는데 클로드 코드에서 보이지 않거나, 동작이 이상하다면 재설치가 가장 확실한 해결책입니다.

npm install -g @anthropic-ai/claude-code