터미널에서 코드를 짜고 검토받고 싶어서 클로드 CLI를 설치하려는 분들이 많아요. 설치 자체는 명령어 한 줄이면 끝나지만, 운영체제별로 권한 문제나 경로 문제로 막히는 경우가 종종 있어서 처음부터 순서대로 정리해볼게요.
설치 전에 확인해야 할 것
클로드 CLI는 Node.js 환경을 기반으로 동작하는 도구라서, 설치하기 전에 Node.js와 npm이 컴퓨터에 있는지부터 확인하는 게 순서예요. 터미널에 node -v와 npm -v를 입력해서 버전이 출력되면 준비가 된 상태예요.
Node.js가 없다면 공식 홈페이지에서 LTS 버전을 먼저 설치해야 해요. 너무 오래된 버전을 쓰고 있으면 CLI 설치 과정에서 호환성 오류가 날 수 있어서, 가능하면 최신 LTS로 맞춰두는 게 이후 문제를 줄이는 방법이에요.
macOS라면 터미널 앱을, 윈도우라면 PowerShell이나 명령 프롬프트를 사용하면 되고, 윈도우 사용자는 WSL(Windows Subsystem for Linux) 환경에서 설치하는 것이 더 안정적이라는 평가가 많아요.
npm으로 설치하는 기본 명령어
가장 기본적인 설치 방법은 npm 전역 설치 명령어를 사용하는 거예요. 터미널을 열고 아래 명령어를 입력하면 시스템 전역에 CLI가 설치돼요.
- 전역 설치:
npm install -g @anthropic-ai/claude-code명령어로 어디서든 실행할 수 있는 전역 도구로 설치해요. - 설치 확인: 설치가 끝나면
claude --version으로 버전이 정상적으로 뜨는지 확인해요. - 업데이트: 새 버전이 나오면 같은 설치 명령어를 다시 실행하거나 CLI 내부 업데이트 명령으로 최신화할 수 있어요.
전역 설치 시 권한 오류(EACCES 등)가 뜨는 경우가 있는데, 이는 npm이 시스템 폴더에 쓰기 권한이 없어서 발생하는 문제예요. 이때 sudo를 붙여서 강제로 설치하는 방법도 있지만, 권장되는 방식은 npm의 전역 설치 경로를 사용자 홈 디렉터리 쪽으로 바꿔주는 거예요.
macOS와 윈도우, 설치 방식의 차이
macOS 사용자는 Homebrew를 이용한 Node.js 설치를 선호하는 경우가 많고, Homebrew로 설치한 Node 환경에서는 npm 전역 설치 권한 문제가 상대적으로 적게 발생해요. 터미널 기본 셸이 zsh인 경우 설치 후 PATH 설정이 제대로 잡혀 있는지 .zshrc 파일을 확인하는 것도 도움이 돼요.
윈도우 사용자는 명령 프롬프트에서 바로 설치해도 되지만, 실행 정책이나 경로 인식 문제로 명령어가 인식되지 않는 경우가 있어요. 이런 경우 WSL을 설치해서 그 안에서 Node.js와 CLI를 설치하면 리눅스와 동일한 환경에서 안정적으로 사용할 수 있어요.
두 환경 모두 설치가 끝난 뒤에는 새 터미널 창을 열어서 명령어가 정상 인식되는지 다시 확인하는 습관이 필요해요. 기존에 열려 있던 터미널은 PATH 변경 내용을 반영하지 못하는 경우가 많기 때문이에요.
설치 후 로그인과 초기 설정
설치가 끝나면 터미널에서 claude 명령어를 실행해 대화형 모드로 진입할 수 있어요. 처음 실행하면 계정 인증 절차가 안내되는데, 브라우저 창이 열리면서 로그인 화면으로 연결돼요.
계정 로그인을 마치면 터미널로 돌아와 인증이 완료됐다는 안내를 확인하면 돼요. 이후부터는 별도 로그인 없이 해당 터미널 환경에서 계속 CLI를 사용할 수 있어요.
작업 폴더로 이동한 뒤 그 안에서 claude를 실행하면 현재 디렉터리를 프로젝트 컨텍스트로 인식해서 코드 관련 질문이나 수정 요청에 바로 활용할 수 있어요.
설치 후 자주 겪는 문제와 해결
가장 흔한 문제는 명령어를 찾을 수 없다는 오류인데, 대부분 PATH에 npm 전역 설치 경로가 등록되지 않아서 생겨요. npm config get prefix로 설치 경로를 확인하고, 그 경로의 bin 폴더가 PATH에 포함돼 있는지 셸 설정 파일에서 점검하면 해결돼요.
버전이 오래돼서 특정 기능이 동작하지 않는 경우도 있는데, 이럴 때는 기존 설치를 npm uninstall -g @anthropic-ai/claude-code로 제거한 뒤 다시 설치하면 깨끗하게 정리돼요.
- 명령어 인식 안 됨: PATH에 npm 전역 bin 경로가 등록돼 있는지 확인해요.
- 권한 오류(EACCES): sudo 강제 설치보다는 npm 전역 경로를 사용자 디렉터리로 옮기는 방식을 권장해요.
- 버전 충돌: 기존 설치를 완전히 제거하고 재설치하면 대부분 해결돼요.
설치 과정 자체는 명령어 한 줄로 끝나는 간단한 작업이지만, 환경마다 PATH나 권한 설정이 달라서 처음 한 번은 위 순서를 차근차근 따라가는 게 안전해요. 일단 한 번 정상적으로 설치되면 이후에는 업데이트도 같은 명령어로 손쉽게 처리할 수 있어요.