02. 설치와 인증

큰 그림: 설치는 "전달 방식"의 선택

Claude Code 설치에는 여러 경로가 있지만, 결국 같은 네이티브 바이너리를 당신의 PATH에 놓는 일입니다. 차이는 "어떻게 전달받고, 어떻게 업데이트하느냐"입니다.

flowchart TB
    Start([설치 시작]):::user --> Q{어떤 방식?}:::agent
    Q -->|권장| Native[네이티브 설치 프로그램<br/>의존성 없음·자동 업데이트]:::result
    Q -->|npm 워크플로우| Npm[npm 글로벌<br/>Node 18+·수동 업데이트]:::tool
    Q -->|패키지 매니저| PM[Homebrew / WinGet<br/>apt·dnf·apk·수동 업데이트]:::tool
    Native --> Verify[claude --version<br/>claude doctor]:::danger
    Npm --> Verify
    PM --> Verify
    Verify --> Done([설치 완료]):::result

    classDef user fill:#FFE082,stroke:#F9A825,color:#000
    classDef agent fill:#80DEEA,stroke:#00ACC1,color:#000
    classDef tool fill:#90CAF9,stroke:#1E88E5,color:#000
    classDef result fill:#A5D6A7,stroke:#43A047,color:#000
    classDef danger fill:#EF9A9A,stroke:#E53935,color:#000

OS별 설치

macOS / Linux (네이티브)

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

설치 프로그램이 바이너리를 내려받아 ~/.local/bin에 놓고 PATH와 자동 업데이트를 설정합니다. Node.js·패키지 매니저가 필요 없습니다.

Windows (네이티브)

PowerShell에서:

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

⚠️ 흔한 실수: irm ... is not recognized 오류가 나면 PowerShell이 아니라 CMD에 있는 것입니다. 프롬프트가 PS C:\로 시작하면 PowerShell, C:\로만 시작하면 CMD입니다. CMD라면 install.cmd 방식을 쓰거나 PowerShell을 여세요.

npm으로 설치 (대안)

이미 npm으로 도구를 관리하거나 버전을 팀과 맞춰 고정하고 싶을 때:

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

Node.js 18 이상이 필요합니다. npm 패키지는 같은 바이너리를 전달할 뿐이며, 설치된 claude는 Node를 런타임으로 쓰지 않습니다.

Homebrew / WinGet / 리눅스 패키지 매니저

Homebrew의 기본 캐스크 claude-code는 안정(stable) 채널로 최신보다 약 1주 늦으며 큰 회귀가 있는 릴리스를 건너뜁니다. claude-code@latest는 나오는 즉시 받습니다. 패키지 매니저 설치는 자동 업데이트되지 않으니 주기적으로 직접 업데이트하세요.

요금제: 무엇이 필요한가

Claude Code 바이너리 설치 자체는 무료지만, 사용하려면 Claude Code 접근이 포함된 계정이 필요합니다.

엔터프라이즈 환경에서는 Amazon Bedrock(CLAUDE_CODE_USE_BEDROCK=1), Google Vertex AI(CLAUDE_CODE_USE_VERTEX=1), Microsoft Foundry, 또는 LLM 게이트웨이를 통해서도 쓸 수 있습니다.

인증: 두 갈래 길

설치 후 프로젝트 폴더에서 claude를 처음 실행하면 인증 흐름이 시작됩니다.

flowchart TB
    Run[claude 첫 실행]:::user --> Q{인증 방식}:::agent
    Q -->|개인·대화형| Sub[구독 인증<br/>브라우저로 Claude.ai 로그인]:::result
    Q -->|자동화·CI| Key[API 키<br/>ANTHROPIC_API_KEY 환경변수]:::tool
    Sub --> Use[사용 시작]:::result
    Key --> Use

    classDef user fill:#FFE082,stroke:#F9A825,color:#000
    classDef agent fill:#80DEEA,stroke:#00ACC1,color:#000
    classDef tool fill:#90CAF9,stroke:#1E88E5,color:#000
    classDef result fill:#A5D6A7,stroke:#43A047,color:#000

• 구독 인증: claude 실행 → 브라우저가 열리며 Claude.ai 계정으로 로그인·인가. 사용량은 구독 플랜의 한도에서 차감됩니다. 한 번만 하면 이후엔 저장된 인증을 씁니다.
• API 키 인증: 헤드리스·CI 환경에서는 브라우저 인증 대신 ANTHROPIC_API_KEY 환경변수를 설정합니다. 키는 platform.claude.com의 API Keys에서 발급합니다(보통 sk-로 시작).

⚠️ 흔한 실수: 브라우저가 열렸는데 인증이 안 된다면, 그 브라우저가 올바른 Claude 계정으로 로그인되어 있는지 확인하세요. 무료 플랜 계정으로는 거부됩니다. 꼬였다면 claude logout 후 다시 claude.

설치 점검: claude doctor

뭔가 이상하면 가장 먼저 실행할 명령입니다. 설치 방식·인증 상태·설정·MCP 서버 등을 자동 진단합니다.

claude --version   # 버전 번호가 나오면 설치 성공
claude doctor      # 설치 유형·인증·설정 상세 점검
claude update      # 대기 중인 업데이트 즉시 적용 (네이티브)

이 장에서 배운 것

• 권장 설치는 네이티브 설치 프로그램(의존성 없음·자동 업데이트). npm·Homebrew·WinGet은 대안이며 보통 수동 업데이트다.
• npm 설치 시 절대 sudo를 쓰지 말 것. 권한 오류와 보안 위험의 주범이다.
• 무료 플랜으로는 못 쓰고 Pro 이상이 필요하다. 요금·플랜은 자주 바뀌니 공식 가격 페이지로 확인.
• 인증은 개인·대화형이면 구독 인증, 자동화·CI면 API 키.
• 문제가 생기면 claude doctor로 먼저 진단한다.

✍️ 확인 문제

1. 네이티브 설치와 npm 설치의 가장 큰 차이(업데이트 관점)는 무엇인가요?
2. EACCES 권한 오류가 났을 때 하면 안 되는 일과, 올바른 해결 방향은 무엇인가요?
3. CI 파이프라인에서 Claude Code를 인증하려면 어떤 방식을 써야 하나요?

다음 장: 03. 첫 세션과 기본 작업 흐름 — 드디어 claude를 실행하고 첫 작업을 시켜봅니다.