Claude Code 설치 가이드: Native와 npm 비교, PATH 설정 및 첫 실행

Claude Code를 네이티브 설치(Native Install)할 경우 Node.js 런타임 환경은 전혀 필요하지 않습니다. 현재 npm 설치 프로그램은 Node.js 22 이상을 요구하지만, 설치된 바이너리 자체는 Node 런타임과 완전히 독립적으로 실행됩니다. Anthropic 공식 문서에서는 네이티브 설치 방식을 사용할 것을 명시적으로 권장하고 있습니다(자세한 내용은 설치 가이드 참조). 터미널에서 코딩 에이전트를 활용하려면 적절한 설치 방식을 선택하고, 지원되는 셸 환경에서 명령어를 실행한 뒤, 운영체제에서 실행 파일을 정상적으로 인식하는지 확인해야 합니다. 명령어 실행 오류가 발생할 경우 문제의 근본 원인을 파악하려면 독립형 네이티브 배포판과 패키지 관리자를 통한 설치 방식 간의 구조적 차이를 명확히 구분해야 합니다.

Native 또는 npm: 아키텍처 경계와 Node.js의 역할

Anthropic 공식 문서에서는 Native Install 방식(설치 가이드)을 권장합니다. 이 방식에서는 Node.js 런타임이 전혀 필요하지 않습니다. 설치 스크립트가 미리 컴파일된 독립 실행형 바이너리를 직접 다운로드하며, 실행 과정에서도 Node와 일체 상호작용하지 않습니다.

글로벌 npm 패키지를 통한 설치도 대안으로 계속 지원됩니다. 현재 npm 설치 프로그램은 Node.js 22 이상의 버전을 요구합니다. 이전 버전의 Node.js 환경에서 설치를 실행하면 npm에서 EBADENGINE 경고를 출력하지만, 설치 프로세스 자체는 대체로 정상 완료됩니다. 패키지가 플랫폼에 맞는 사전 컴파일 바이너리를 내려받아 심볼릭 링크를 생성하기 때문입니다. 실행 시점(runtime)에도 설치된 Claude Code 바이너리는 Node.js 내부에서 구동되지 않습니다.

따라서 Claude Code를 실행하기 위해 항상 Node.js가 필수라는 주장은 기술적으로 사실이 아닙니다. Node.js 버전을 확인해야 하는 상황은 의도적으로 npm을 통해 설치할 때뿐입니다.

지원 운영체제별 설치 명령어

사용 중인 운영체제와 셸 환경에 맞는 공식 스크립트를 실행하여 정상적인 설치를 진행합니다.

macOS, Linux 및 WSL (Bash / Zsh)

curl -fsSL https://claude.ai/install.sh | bash

Windows PowerShell

irm https://claude.ai/install.ps1 | iex

Windows 명령 프롬프트 (CMD)

curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd

npm을 통한 대체 설치 방식

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

중요: 이 명령어를 sudo npm install -g로 실행하지 마십시오. 슈퍼유저(관리자) 권한으로 패키지를 설치하면 홈 디렉터리 내 파일 권한 충돌이 발생하며 보안 위험을 초래할 수 있습니다.

네이티브 Windows 환경에서 Git for Windows 설치는 이제 선택 사항입니다. Git for Windows가 설치되어 있다면 에이전트는 Git Bash를 통해 Bash 명령어를 실행할 수 있으며, 설치되어 있지 않은 경우 Claude Code는 기본 내장된 PowerShell 도구로 대체하여 동작합니다.

설치 상태 및 동작 확인

설치 스크립트 실행이 완료되면 시스템 환경에서 바이너리를 호출할 수 있는지 확인합니다:

claude --version

버전 정보가 정상적으로 출력되면 바이너리가 성공적으로 다운로드 및 압축 해제되어 환경에 등록되었음을 나타냅니다. 다만 버전이 정상 출력되었다고 해서 클라이언트 인증이 완료되었거나 모델 요청을 처리할 수 있는 상태임을 의미하는 것은 아니며, 이는 실행 파일 자체의 무결성만을 검증한 것입니다.

시스템 환경에 대한 전반적인 진단을 위해 진단 유틸리티 명령어를 실행합니다:

claude doctor

claude doctor 명령어는 로컬 환경을 종합적으로 검사합니다. 대화형 코딩 세션을 시작하지 않고도 설정 파일 상태, 파일 시스템 권한, 시스템 종속성을 점검하여 잠재적인 구성 문제를 사전에 식별해 줍니다.

문제 해결: command not found 오류 진단 및 대처법

터미널에서 claude 명령어를 찾을 수 없다는 오류(또는 Windows에서 내부 또는 외부 명령으로 인식되지 않는다는 메시지)가 나타나면 다음 진단 워크플로를 순서대로 진행하십시오:

[Ошибка вызова: claude не найден]
         │
         ▼
[Шаг 1: Открыть новый сеанс терминала]
         │
    Помогло? ──Да──> Завершено
         │ Нет
         ▼
[Шаг 2: Проверить физическое наличие бинарного файла на диске]
         │
    Файл найден? ──Нет──> Ошибка загрузки/прав; повторить установку
         │ Да
         ▼
[Шаг 3: Проверить тип установки и PATH]
         │
 ┌───────┴────────────────────────┐
 ▼                                ▼
[Native Install]                [npm Install]
Проверить PATH:                 Проверить PATH через npm prefix -g:
- Unix: ~/.local/bin            - Unix: <prefix>/bin
- Win: %USERPROFILE%\.local\bin - Win: <prefix>
(Не переустанавливать только из-за PATH)

위의 다이어그램은 문제 진단 순서를 나타냅니다:

• 오류 시작점: [Ошибка вызова: claude не найден]은 “호출 오류: claude 명령어를 찾을 수 없음”을 의미합니다.
• 1단계: [Шаг 1: Открыть новый сеанс терминала]는 새 터미널 세션을 열라는 지침입니다. 문제가 해결되었는지 확인하여(Помогло? ──Да──> Завершено / “해결되었는가? ──예──> 완료”) 정상이면 종료하고, 여전히 해결되지 않았다면(Нет / “아니요”) 2단계로 진행합니다.
• 2단계: [Шаг 2: Проверить физическое наличие бинарного файла на диске]는 디스크에 바이너리 파일이 물리적으로 존재하는지 확인하는 단계입니다. 파일이 존재하지 않는다면(Файл найден? ──Нет──> Ошибка загрузки/прав; повторить установку / “파일이 없는가? ──아니요──> 다운로드 또는 권한 오류; 재설치 진행”) 설치를 다시 실행해야 합니다. 파일이 존재한다면(Да / “예”) 3단계로 이동합니다.
• 3단계: [Шаг 3: Проверить тип установки и PATH]는 설치 방식과 PATH 환경 변수를 점검합니다:
  • Native Install: PATH 확인(Проверить PATH:): Unix 환경은 ~/.local/bin, Windows 환경은 %USERPROFILE%\.local\bin.
  • npm Install: npm prefix -g를 통해 PATH 확인(Проверить PATH через npm prefix -g:): Unix 환경은 <prefix>/bin, Windows 환경은 <prefix>.
  • 하단 참고 문구 (Не переустанавливать только из-за PATH)는 *(단순한 PATH 설정 오류 때문에 맹목적으로 프로그램을 재설치하지 마십시오)*라는 주의 사항입니다.

1. 새 터미널 세션 열기

설치 스크립트는 셸 프로필 설정 파일(.bashrc, .zshrc)이나 Windows 사용자 환경 변수를 수정합니다. 이미 열려 있는 기존 터미널 세션은 이러한 변경 사항을 즉시 반영하지 못합니다. 현재 터미널 창을 완전히 닫고 새 세션을 시작하십시오.

2. 바이너리 실행 파일의 실제 경로 확인

Native Install의 경우 사용자가 별도로 환경 변수를 재정의하지 않았다면 실행 파일은 기본 디렉터리에 위치합니다:

• macOS, Linux, WSL: ~/.local/bin/claude (버전별 파일은 ~/.local/share/claude에 저장됨)
• Windows: %USERPROFILE%\.local\bin\claude.exe

이 경로들은 기본 표준 경로이며, 사용자가 직접 설정을 재정의한 경우 달라질 수 있습니다. 해당 디렉터리에 파일이 존재하지 않는다면 네트워크 차단이나 쓰기 권한 부족으로 인해 설치가 비정상 종료되었을 가능성이 있습니다.

3. 셸 진단 명령어 실행

현재 셸이 실행 파일을 정상적으로 감지하고 해석하는지 확인하기 위해 기본 진단 명령어를 활용합니다:

• Zsh / Bash: command -v claude 또는 type -a claude 실행
• PowerShell: Get-Command claude 및 where.exe claude 실행
• CMD: where claude 실행

4. Native와 npm에 따른 PATH 분리 확인

자주 발생하는 오류 중 하나는 Native Install 문제 해결 시 Node.js 경로를 잘못 수정하려는 경우입니다.

• Native Install로 설치한 경우 Node.js 디렉터리나 npm prefix -g는 문제와 전혀 관련이 없습니다. Unix 계열 시스템에서는 ~/.local/bin, Windows에서는 %USERPROFILE%\.local\bin 디렉터리가 PATH 환경 변수에 등록되어 있는지 확인하고 추가해야 합니다.
• **npm install -g**로 설치한 경우 글로벌 실행 파일 디렉터리는 npm prefix -g 명령어로 확인합니다:
  • Unix 계열 시스템(macOS, Linux, WSL)에서는 실행 파일이 <prefix>/bin에 위치합니다.
  • Windows 환경에서는 실행 파일이 <prefix> 루트 디렉터리에 직접 배치됩니다. npm bin -g 및 npm root -g 명령어는 올바른 실행 파일 경로를 가리키지 않습니다.

디스크에 바이너리 파일이 존재하는데도 명령어를 찾을 수 없다는 오류가 발생한다면, 먼저 PATH 변수와 셸의 실행 파일 해석 방식을 확인하십시오. 전체 절대 경로로 실행해도 오류가 발생한다면 정확한 에러 메시지를 확인하고 공식 설치 문제 해결 문서를 참조해야 합니다. 파일 권한, 플랫폼 바이너리 호환성, 다운로드 미완료 등의 문제를 점검해야 하며, 단순히 command not found 오류가 발생했다고 해서 무작정 재설치를 반복해서는 안 됩니다.

첫 실행 및 안전한 실습 가이드

명령어 인식이 확인되면 소규모 테스트 프로젝트 디렉터리로 이동하여 세션을 시작합니다:

cd /path/to/test-project
claude

처음 실행하면 브라우저를 통한 표준 인증 절차가 진행됩니다. 세션이 시작된 후 /status 명령어를 입력하면 현재 작업 디렉터리, 계정 식별자, 사용 중인 모델을 확인할 수 있습니다.

초기 동작을 확인하기 위해 비파괴적인 실습 프롬프트를 입력해 봅니다:

Объясни назначение основных файлов в проекте. Не изменяй файлы, не устанавливай зависимости и не выполняй команды в терминале.

(러시아어 테스트 프롬프트 번역: “프로젝트의 주요 파일들이 어떤 역할을 하는지 설명해 줘. 파일을 수정하거나, 의존성을 설치하거나, 터미널에서 명령어를 실행하지 마.”)

기대되는 정상 응답은 에이전트가 코드 변경(diff)을 생성하거나 파일을 수정하지 않고 주요 파일 목록과 역할을 명확히 설명하는 것입니다. 작업이 끝나면 별도의 터미널 창에서 git diff를 실행하여 코드베이스에 아무런 변경 사항이 발생하지 않았음을 확인하십시오.

여기서 주의해야 할 점은 프롬프트에 작성한 지시문은 모델에 제공하는 자연어 가이드일 뿐, 강제적인 실행 모드(enforced mode)나 운영체제 수준의 샌드박스가 아니라는 사실입니다. 만약 레포지토리 내 파일 자동 수정을 엄격히 방지해야 한다면 계획 모드(plan mode)를 활성화하여 실행하십시오:

claude --permission-mode plan

plan 모드에서 에이전트는 기본적으로 파일을 읽고 읽기 전용 셸 명령만 사용하며 소스 코드를 편집하지 않습니다. 그러나 이 모드 역시 운영체제 수준의 격리된 샌드박스는 아니며, 자동 실행이 허용된 환경에서는 분류기(classifier)의 승인을 받은 명령어가 실행될 수 있습니다(엄격한 시스템 수준의 물리적 격리로 간주해서는 안 되며, 2026-09-15 기준 공식 문서에 명시된 내용입니다).

권한 확인 정책에 관한 자세한 내용은 권한 가이드를 참조하십시오. 대화형 세션을 종료하려면 Ctrl+D 단축키를 누릅니다.

독립 API 제공업체 연동

CLI 클라이언트 유틸리티를 설치하는 것과 모델 제공업체를 설정하는 것은 서로 독립적인 작업 단계입니다. 기본 계정 로그인 대신 Anthropic 호환 서드파티 게이트웨이를 사용하고자 한다면, CLI의 로컬 설치와 동작 확인을 마친 후 별도로 연동 설정을 진행합니다.

예를 들어 독립 API 제공업체인 BetterToken은 개발자에게 전용 API Key를 발급하며, 대시보드(Dashboard)를 통해 모델 요청 통계, 토큰 소비량, 결제 내역을 투명하게 관리할 수 있도록 지원합니다. 필수 환경 변수 내보내기(export) 및 API 기본 주소(Base URL) 설정 방법에 대한 구체적인 내용은 BetterToken의 Claude Code 공식 문서에서 확인할 수 있습니다. 로컬 바이너리의 다운로드, 업데이트 및 실행 자체는 이 가이드에서 설명한 표준 CLI 메커니즘을 그대로 따릅니다.