클로드 코드(Claude Code) CLI 설치하기: 맥과 윈도우 두 갈래로

2026년 8월 25일읽는 데 약 6분#가이드 #개발환경 #클로드코드

한줄 요약: 클로드 코드(Claude Code)를 터미널에서 직접 쓰려면 CLI를 설치해야 합니다. 권장 경로는 공식 설치 스크립트 한 줄이고 Node.js가 필요 없습니다. 맥과 윈도우는 여는 창과 명령이 다르기 때문에, 이 글은 두 갈래로 안내합니다.

왜 이 글이 따로 있나

클로드 코드는 데스크톱 앱이 아니라 터미널에서 직접 씁니다. 그런데 검색해서 나오는 안내 중에는 아직도 “Node.js부터 설치하라”는 예전 방식이 많고, CLI 자체는 하나인데 설치할 때 여는 창과 실행하는 명령이 맥과 윈도우에서 다릅니다. 그래서 이 글은 지금 기준 권장 경로 하나를, 운영체제별로 나란히 정리했습니다.

내 컴퓨터가 맥인지 윈도우인지만 알면 됩니다. 나머지는 그대로 따라가면 됩니다.

터미널이 처음이라면

터미널을 한 번도 열어본 적이 없어도 됩니다. 공식 문서가 안내하는 여는 법은 이렇습니다.

맥: Cmd + Space를 눌러 스포트라이트 검색을 열고 “터미널”(또는 Terminal)이라고 입력한 뒤 엔터를 칩니다.

윈도우: Win + X를 눌러 나오는 메뉴에서 “Windows PowerShell”(또는 “터미널”)을 고릅니다. 시작 메뉴에서 “PowerShell”이라고 검색해도 같은 창이 열립니다.

어느 쪽이든 깜빡이는 커서만 있는 창이 뜹니다. 이 창이 터미널입니다. 마우스로 클릭할 것은 없고, 아래 코드블록을 붙여넣고 엔터를 치는 것이 할 일의 전부입니다.

1단계. 설치 스크립트 한 줄 실행하기

클로드 코드를 설치하는 방법은 여러 가지지만, 공식 문서가 **권장 경로(Recommended)**로 표시한 것은 아래 설치 스크립트입니다. 이 경로는 Node.js를 전혀 쓰지 않습니다.

맥 (리눅스, WSL도 동일)

여는 창 터미널 Cmd + Space로 스포트라이트를 열고 "터미널" 입력
설치 명령 아래 코드블록을 붙여넣기 터미널에 붙여넣고 엔터
확인 명령 claude --version 버전 문자열이 찍히면 성공

Node.js 없이 이 한 줄로 끝납니다

윈도우 (PowerShell)

여는 창 PowerShell 시작 메뉴에서 "PowerShell" 입력
설치 명령 아래 코드블록을 붙여넣기 PowerShell에 붙여넣고 엔터
확인 명령 claude --version 버전 문자열이 찍히면 성공

Node.js 없이 이 한 줄로 끝납니다

맥과 윈도우 모두 창을 열고, 설치 스크립트 한 줄을 붙여넣고, 확인 명령으로 마칩니다. 실제로 붙여넣을 명령은 아래 코드블록에 있습니다

맥, 리눅스, WSL은 터미널에 아래 명령을 붙여넣습니다.

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

윈도우는 PowerShell에 아래 명령을 붙여넣습니다.

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

흔한 함정

윈도우에는 PowerShell과 명령 프롬프트(CMD) 두 창이 있어 헷갈리기 쉽습니다. 프롬프트에 PS C:\처럼 앞에 PS가 붙어 있으면 PowerShell이고, C:\만 있고 PS가 없으면 명령 프롬프트입니다. 명령 프롬프트를 쓰고 있다면 위 명령 대신 아래 명령을 씁니다.

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

다른 설치 방법도 있습니다

같은 문서에 다른 경로도 나와 있습니다. 이미 아래 도구를 쓰고 있다면 그걸 그대로 써도 됩니다.

방법	명령	비고
맥 Homebrew	`brew install --cask claude-code`	Homebrew가 이미 있는 경우
윈도우 winget	`winget install Anthropic.ClaudeCode`	winget이 이미 있는 경우
npm	`npm install -g @anthropic-ai/claude-code`	Node.js가 있어야 합니다. 아래 절 참고

npm 경로는 없어도 됩니다

1단계 설치 스크립트를 썼다면 이 절은 필요 없습니다. 클로드 코드는 npm으로도 설치할 수 있지만, 이건 npm을 이미 쓰고 있는 사람을 위한 선택지이지 권장 경로가 아닙니다.

다른 프로젝트에서 npm 경로로 클로드 코드를 설치하고 싶을 때만 아래를 참고하세요. 공식 문서는 npm 경로에 Node.js 22 이상이 필요하다고 안내하고, sudo npm install -g는 쓰지 말라고 명시합니다. 캡처 속 페이지 기본 선택(맥 nvm, 윈도우 Chocolatey)은 버전 관리 도구부터 설치하는 개발자용 경로라, 코드 블록 대신 아래 “Or get a prebuilt Node.js®“의 설치 파일(맥 .pkg, 윈도우 .msi)을 받는 편이 간단합니다.

Node.js 다운로드 페이지에서 macOS, nvm, npm을 선택한 화면. Bash 코드 블록에 nvm 설치 명령과 nvm install 24, node -v로 v24.19.0을 확인하는 명령이 보이고, 그 아래 macOS용 prebuilt Node.js 안내와 macOS Installer (.pkg), Standalone Binary (.gz) 초록 버튼이 있다 — 맥에서 Node.js를 받는 화면입니다. npm 경로를 쓸 사람만 필요합니다

같은 Node.js 다운로드 페이지에서 위쪽 선택기를 Windows, Chocolatey, npm으로 바꾼 화면. PowerShell 코드 블록에 Chocolatey 설치 명령과 choco install nodejs 명령이 보이고, 그 아래 Windows용 prebuilt Node.js 안내와 Windows Installer (.msi), Standalone Binary (.zip) 초록 버튼, ARM64로 설정된 아키텍처 선택 칸이 있다 — 윈도우에서 Node.js를 받는 화면입니다. 아키텍처 칸이 ARM64로 기본 잡혀 있어, 받기 전에 내 컴퓨터와 맞는지 확인이 필요합니다. 윈도우 설정의 '시스템 정보'에서 시스템 종류를 확인할 수 있습니다. 캡처의 버전은 v24.19.0 LTS라, 클로드 코드의 npm 설치 패키지가 요구하는 22 이상 조건은 자동으로 충족됩니다

2단계. `claude` 실행하고 로그인하기

claude --version으로 버전이 찍혔다면 설치는 끝난 것입니다. 이제 claude라고 치고 엔터를 칩니다.

처음 실행하면 로그인이 필요합니다. 브라우저 창이 자동으로 열려 로그인 화면으로 안내합니다. 무료 플랜 계정이면 이 단계에서 막힙니다(맨 위 흔한 함정 참고). 로그인을 마치고 터미널로 돌아오면 환영 화면이 보입니다. 이 화면이 보이면 준비가 끝난 것입니다.

로그인 뒤 화면 안에서 알아두면 편한 것들입니다.

터미널 안에서는 마우스로 클릭할 수 없습니다. 화살표 키로 움직입니다.
클로드가 뭔가 실행 중일 때 멈추려면 Esc를 누릅니다.
나가려면 exit을 치거나, 빈 프롬프트에서 Ctrl + D를 두 번 누릅니다.
/help를 치면 쓸 수 있는 명령 목록이 나옵니다.

확인이 안 되면

설치 명령 자체가 안 되는 경우와, 설치는 됐는데 로그인이 안 되는 경우는 원인이 다릅니다. 공식 트러블슈팅 문서가 증상별로 정리해 둔 대응입니다.

설치 명령이 실패할 때

증상	원인	할 일
`syntax error near unexpected token '<'` 또는 화면에 HTML 코드가 보임	설치 주소가 스크립트 대신 웹페이지를 돌려준 것	잠시 후 같은 명령을 다시 실행. 반복되면 맥은 `brew install --cask claude-code`, 윈도우는 `winget install Anthropic.ClaudeCode`로 설치
`curl: (22) ... 403`	방화벽이나 프록시가 막았거나 지원하지 않는 지역	위와 같은 대체 설치 명령 사용
PowerShell에서 `irm`을 못 알아봄(`is not recognized`)	지금 연 창이 PowerShell이 아니라 CMD	PowerShell을 새로 열어 다시 시도하거나, CMD 전용 명령(`curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd`) 사용
`command not found: claude` / `'claude' is not recognized`	설치는 됐지만 설치 폴더가 아직 PATH(명령을 찾는 경로 목록)에 없음	창을 닫고 새로 열어 다시 시도. 그래도 안 되면 아래 PATH 추가 명령 실행

command not found가 반복되면, 설치 폴더를 PATH에 직접 추가합니다.

맥(Zsh): 아래 두 줄을 붙여넣고 실행한 뒤, 새 터미널을 엽니다.

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

윈도우(PowerShell): 아래 명령을 붙여넣고 실행한 뒤, 새 창을 엽니다.

$currentPath = [Environment]::GetEnvironmentVariable('PATH', 'User')
[Environment]::SetEnvironmentVariable('PATH', "$currentPath;$env:USERPROFILE\.local\bin", 'User')

설치 폴더에 쓰기 권한이 없다는 오류가 나면, 맥이나 리눅스에서 아래 명령으로 소유자를 내 계정으로 되돌립니다. 윈도우는 설치 위치가 내 계정 폴더(%USERPROFILE%) 안이라 이 오류가 거의 나지 않습니다.

sudo mkdir -p ~/.local/bin
sudo chown -R $(whoami) ~/.local

설치는 됐는데 로그인이 안 될 때

증상	원인	할 일
브라우저가 자동으로 안 열림	환경에 따라 자동 실행이 안 될 수 있음	클로드 코드가 로그인 대기 중인 화면에서 `c`를 눌러 로그인 주소를 복사한 뒤 브라우저에 직접 붙여넣기
`OAuth error: Invalid code`	로그인 코드가 만료됐거나 복사 중 일부가 잘림	엔터를 눌러 재시도. 브라우저가 열리면 빠르게 로그인 마치기
로그인 뒤 `403 Forbidden`	계정이 무료 플랜이거나 구독이 비활성 상태	claude.ai/settings에서 구독 상태 확인
원인을 모르겠을 때	-	`/logout`으로 로그아웃 → 터미널 종료 → `claude`로 재시작해 다시 로그인

위 표에도 없는 증상이면 claude doctor를 쳐서 진단 결과를 봅니다. 무엇이 빠졌는지 알려 줍니다.

이 글의 설치 명령과 계정 조건은 2026년 8월 24일 code.claude.com/docs/en/setup에서 확인했습니다. 터미널을 여는 법과 첫 실행 안내는 같은 날 code.claude.com/docs/en/terminal-guide에서, “확인이 안 되면” 절의 증상별 대응은 같은 날 code.claude.com/docs/en/troubleshoot-install에서 확인했습니다. Node.js 화면과 버전 번호(v24.19.0, npm 11.17.0)는 같은 날 nodejs.org/en/download에서 확인했습니다. 설치 방법과 계정 조건은 바뀔 수 있으니 실제 화면이 다르면 공식 문서를 기준으로 판단하세요.