설치 명령 자체는 한 줄입니다. 문제는 그 줄을 친 다음에 생깁니다. 로그인까지는 매끄럽게 넘어갔는데, 막상 첫 요청을 보내면 커서만 깜빡이고 응답이 오지 않는 상황. 많은 사람이 이걸 설치 실패로 읽고 지우고 다시 깔기를 반복합니다.
그런데 다시 까는 행동은 대개 헛수고입니다. 설치가 제대로 됐는지와, 첫 실행이 끝까지 도는지는 사실 별개의 문제이기 때문입니다. 전자는 내 컴퓨터와 명령어가 맞느냐의 문제고, 후자는 내 컴퓨터에서 API까지 가는 길이 얼마나 멀고 깨끗하냐의 문제입니다. 이 둘을 섞어 보기 시작하면 진단이 끝없이 꼬입니다. 그래서 이 글은 둘을 분리한 채로 진행합니다.
까는 것과 도는 것은 다른 문제다
예를 들어 회선이 느린 동료의 노트북을 떠올려 보면 이해가 빠릅니다. 명령어도 같고 버전도 같은데, 서버에서 멀다는 이유 하나로 첫 요청이 자꾸 끊깁니다. 여기서 재설치를 만 번 해도 회선은 빨라지지 않습니다. 고쳐야 할 대상이 아예 다른 층에 있는 거죠.
이 글이 상정하는 독자는 둘입니다. 하나는 CLI를 한 번도 안 써 본 신규 사용자. 동작하는 세션까지 가장 짧게 가고 싶은 사람입니다. 다른 하나는 설치를 표준화하려는 팀입니다. 같은 절차가 모든 엔지니어의 장비에서 똑같이 돌아야 하고, 그중엔 네트워크가 멀어 첫 요청이 가장 잘 막히는 동료도 섞여 있습니다. 원하는 결과는 결국 하나로 모입니다. 제대로 깔리고, 첫 실행이 타임아웃 없이 끝나는 것.
버전부터 맞춘다
가장 먼저 할 일은 환경 확인입니다. Claude Code는 macOS, Linux, Windows에서 돌아갑니다. npm 패키지를 쓸 거라면 Node.js 18 이상이 필요한데, 굳이 아슬아슬하게 18에 맞추지 말고 22 LTS를 깔아 두는 편이 마음이 편합니다.
점검은 node --version 한 줄이면 됩니다. 이 단계를 건너뛰고 생기는 설치 실패의 거의 전부가 버전 불일치입니다. 무슨 희귀한 버그가 아니라요. 그리고 계정. CLI는 자격이 되는 유료 요금제 안에 들어 있고, 무료 웹 플랜에는 포함되지 않습니다. 로그인 단계에서 막혀 당황하지 않으려면 설치 전에 계정 상태부터 확인해 두는 게 낫습니다.
설치 방법은 둘 중 하나
경로는 크게 둘입니다.
네이티브 설치 프로그램은 별도 의존성이 없고 갱신도 백그라운드에서 알아서 됩니다. 워크스테이션 한 대에 빠르게 올리려면 이쪽이 가장 손이 덜 갑니다.
이미 Node 도구 체인을 쓰고 있다면 npm 경로가 자연스럽습니다.
npm install -g @anthropic-ai/claude-code
둘 다 정식 지원이라 어느 쪽을 골라도 됩니다. 단, npm 경로에는 한 가지 함정이 있습니다. 명령어 앞에 sudo를 붙이지 마세요. 권한 오류가 났을 때 root로 우회 설치하는 건 임시방편이고, 나중에 더 골치 아픈 문제를 부릅니다. 그럴 땐 Node 버전 관리자(nvm 같은)로 전역 패키지를 사용자 공간에 두는 게 정석입니다.
버전을 여러 개 굴려야 하는 환경이라면 처음부터 버전 관리자로 설치하는 선택지도 있습니다. 격리가 깔끔하고 권한 충돌이 가장 적게 납니다.
로그인하고, 진짜로 도는지 확인한다
claude로 CLI를 띄우고 안내되는 로그인 흐름을 마칩니다. 여기서 끝내지 말고 설치가 끝에서 끝까지 멀쩡한지 증명하는 게 핵심입니다.
claude --version으로 실행 파일이 제대로 잡히는지 본다.- 세션 안에서
/doctor를 돌려 설정 문제를 미리 잡는다. - "여기 파일 목록 보여줘" 정도의 사소한 프롬프트를 한 번 보내 응답을 받아 본다.
이 마지막 왕복이 깔끔하게 돌아오면 설치는 견고하다고 봐도 됩니다. 반대로 로그인은 됐는데 이 사소한 요청이 멈춘다면, 설치를 의심할 게 아닙니다. 설치는 멀쩡합니다.
대부분의 가이드가 끝내는 곳, 여기서부터가 본론
설치 안내 글은 보통 로그인까지 보여 주고 마칩니다. 정작 사람들이 막히는 지점은 그 너머인데도요.
CLI가 완벽하게 깔리고 로그인까지 됐어도, 내 장비에서 API까지 가는 경로가 느리거나 패킷 손실이 많으면 전체가 고장 난 것처럼 보입니다. 첫 agent 실행 한 번이 내부적으로 여러 차례 왕복을 주고받기 때문입니다. 그 왕복 중 한 홉이 막히면, 화면상으로는 그냥 "멈춘" 것처럼 보입니다.
그래서 한 번은 API 호스트로 ping을 보내 기준선을 잡아 두길 권합니다. 지연이 눈에 띄게 높다면 병목은 코드도 명령어도 아닌 경로입니다. 서버에서 멀리 떨어진 위치에서 작업하는 개발자일수록 이 차이가 크게 벌어집니다.
NasaCode가 손보는 부분이 바로 여기입니다. 개발자 트래픽을 저지연 노드로 태워, 서버 바로 옆에서 깐 설치든 대륙 건너에서 깐 설치든 첫 실행이 비슷하게 끝까지 돌도록 맞춰 둔 거죠. 자세한 건 nasacode.com에서 볼 수 있습니다.
설치 방법 한눈에 비교
| 방법 | 의존성 | 갱신 방식 | 적합한 상황 |
|---|---|---|---|
| 네이티브 설치 프로그램 | 없음 | 백그라운드 자동 | 워크스테이션 한 대, 가장 빠른 시작 |
| npm 전역 설치 | Node.js 18+ | latest 수동 재설치 | 이미 Node 도구 체인을 쓰는 경우 |
| 버전 관리자 설치 | nvm 등 | 수동, 버전별 격리 | Node 여러 버전을 동시에 관리 |
표에서 빠진 변수가 하나 있는데, 바로 네트워크입니다. 어느 방법으로 깔든 멀거나 불안정한 회선이라면 마지막 연결 단계를 따로 챙겨야 첫 실행이 멈추지 않습니다.
자주 부딪히는 상황
무료 계정으로도 쓸 수 있나요?
아니요. 자격이 되는 유료 요금제나 콘솔 접근이 필요하고, 무료 웹 계층에는 들어 있지 않습니다. 설치 전에 계정 상태를 한 번 확인해 두세요.
npm 설치가 권한 오류로 죽어요
대개 상승 권한으로 돌렸거나, 시스템이 소유한 Node에 설치하려다 난 오류입니다. 버전 관리자로 다시 깔아 전역 패키지가 사용자 공간에 놓이게 하면 사라집니다.
로그인은 됐는데 첫 명령에서 그냥 멈춰 있어요
설치는 정상이고 연결이 문제일 가능성이 높습니다. API 호스트까지의 지연을 재 보세요. 높게 나오면 경로가 병목입니다. 이때는 트래픽을 최적화된 경로로 태우는 것 외에 달리 손쓸 데가 없습니다.
처음 시작하는데 뭘로 깔까요?
특별한 이유가 없다면 마찰이 가장 적은 네이티브 설치 프로그램으로 시작하면 됩니다. Node를 여러 버전 굴려야 한다든가 분명한 이유가 생겼을 때 npm이나 버전 관리자로 옮겨도 늦지 않습니다.
정리하면 깔끔한 설치는 네 박자입니다. 버전 확인, 장비에 맞는 방법으로 설치, 사소한 프롬프트로 로그인 검증, 그리고 진짜로 의존하기 전에 API까지의 경로를 안정시키기. 마지막 한 박자를 빼먹으면, 완벽하게 깔린 설치도 첫 실제 작업 앞에서 고장 난 것처럼 보일 수 있습니다.
