클로드 코드 설치 방법: 명령 한 줄이면 1분, 맥·윈도우 첫 실행까지

클로드 코드는 지금 명령 한 줄로 설치되고, Node.js도 필요 없습니다. 쓰려면 Pro 이상 구독이나 API 결제 계정이 있어야 합니다. 이 글은 2026년 10월 13일 macOS 26.1에서 실제로 설치하고 처음 실행한 기록입니다. 윈도우 부분은 공식 문서를 기준으로 정리했습니다.

직접 실행 확인한 날짜 2026-10-13

무엇을 해 주나: 터미널에서 클로드에게 파일 읽기·수정, 명령 실행을 맡기는 코딩 에이전트
쓸 수 있는 곳: macOS 26.1 직접 확인 · Windows 10(1809) 이상 문서상 지원 · Ubuntu 20.04 이상 문서상 지원. RAM 4GB 이상
설치 난이도: 쉬움 · 1분이면 끝
비용: 설치는 무료. 쓰려면 Pro·Max·Team·Enterprise 구독 또는 Console(API 종량제) 계정 필요. 무료 요금제는 안 됨
라이선스: Anthropic 이용약관 적용(오픈소스 라이선스 없음)
실행 환경: macOS 26.1 · Claude Code 2.1.296(기본 설치) · 2026-10-13. 설치부터 첫 실행 화면까지는 새로 만든 빈 계정에서, 5단계 첫 질문은 로그인돼 있던 기존 설치(2.1.292)에서 실행
원본: 공식 설치 문서 (한국어)

설치 방법 고르기

대부분은 첫 줄의 기본 설치를 쓰면 됩니다. 방법마다 다른 것은 업데이트 방식입니다.

Claude Code 공식 설치 문서의 기본 설치 탭과 macOS·Linux·WSL용 설치 명령, 복사 버튼 — ① 기본 설치(권장) 탭 ② 맥·리눅스·WSL용 설치 명령 ③ 복사 버튼 · code.claude.com 한국어 설치 문서, 2026-10-13 촬영

방법	명령	업데이트	이럴 때 고르세요
기본 설치(권장)	`curl … install.sh \| bash` (맥·리눅스·WSL) `irm … install.ps1 \| iex` (윈도우 PowerShell)	자동	처음 설치하는 대부분의 경우
Homebrew(홈브루)	`brew install --cask claude-code`	직접 (`brew upgrade claude-code`)	맥에서 다른 프로그램도 홈브루로 관리할 때
WinGet(윈겟)	`winget install Anthropic.ClaudeCode`	직접 (`winget upgrade Anthropic.ClaudeCode`)	윈도우에서 프로그램을 윈겟으로 관리할 때
npm	`npm install -g @anthropic-ai/claude-code`	자동(폴더 권한이 없으면 안 됨)	Node.js 22 이상 개발 환경을 이미 쓰는 경우

홈브루는 맥용, 윈겟은 윈도우용 프로그램 설치 관리 도구입니다. 공식 문서에 따르면 홈브루의 claude-code는 안정판 채널이라 보통 약 1주 늦은 버전이 깔립니다. 최신판은 claude-code@latest입니다.

여러 방법으로 깔면 어떤 claude가 실행되는지 헷갈립니다. 맥·리눅스는 which -a claude, 윈도우는 where.exe claude로 몇 개가 깔려 있는지 확인합니다.

1단계. 설치 명령 실행하기 (약 1분)

이 단계에서는 공식 설치 명령을 터미널에 붙여 넣습니다. 맥은 Spotlight(⌘+스페이스)에서 “터미널”을 검색해 엽니다. 맥, 리눅스, WSL에서는 터미널에서 아래 명령을 실행합니다.

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

윈도우는 어떤 창에서 실행하는지에 따라 명령이 다릅니다. 줄 앞에 PS C:\가 보이면 PowerShell, C:\만 보이면 CMD입니다. 관리자 권한으로 열 필요는 없습니다.

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

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

첫 줄이 PowerShell용, 둘째 줄이 CMD용입니다.

터미널에서 공식 설치 명령을 실행한 결과. 설치 완료, 설치 위치, PATH 안내가 보인다 — ① 설치 완료 ② 설치 위치 `~/.local/bin/claude` ③ PATH에 등록되지 않았다는 안내 · macOS 26.1 새 계정, 2026-10-13 실제 실행

이렇게 나오면 성공 Claude Code successfully installed!와 버전, 설치 위치가 출력됩니다. 1분이 채 안 걸렸습니다. 설치 중에는 진행률 표시가 없으니 멈춘 것처럼 보여도 기다리면 됩니다. 윈도우는 공식 문서에 따르면 설치가 끝난 뒤 새 창에서 claude --version을 실행하면 버전 번호가 나옵니다.

예전에 npm으로 설치했다면 주의할 점이 있습니다. 이 컴퓨터의 기존 계정에는 npm 설치가 있었는데, 기본 설치 명령이 그것을 지웠습니다. 설치 출력에는 아무 안내가 없었습니다. npm 실행 기록을 보고서야 npm uninstall --global @anthropic-ai/claude-code가 실행된 것을 알았습니다. 이 경우 2단계까지 끝내야 claude 명령이 다시 잡힙니다.

The token '&&' is not a valid statement separator가 나오면: CMD용 명령을 PowerShell에 넣은 것입니다. PowerShell용 첫 줄을 씁니다.
'irm' is not recognized가 나오면: CMD에 PowerShell용 명령을 넣은 것입니다. CMD용 둘째 줄을 씁니다.
Claude Code does not support 32-bit Windows가 나오면: 시작 메뉴에서 이름에 (x86)이 붙지 않은 “Windows PowerShell”을 열고 다시 실행합니다.
syntax error near unexpected token '<'나 403이 나오면: 설치 파일 대신 웹페이지를 받은 것입니다. 지원 지역이나 회사 프록시 문제일 수 있습니다. 잠시 뒤 다시 하거나 홈브루·윈겟으로 설치합니다.

2단계. claude 명령이 잡히는지 확인하기 (약 1분)

이 단계에서는 터미널이 claude를 찾을 수 있게 설치 폴더를 PATH에 등록합니다. PATH는 터미널이 명령을 찾아보는 폴더 목록입니다. 새로 만든 맥 계정에서는 1단계 화면의 ③처럼 ~/.local/bin이 PATH에 없다는 안내가 나왔고, 실제로 claude를 찾지 못했습니다.

PATH 등록 전에는 command not found가 나오고 등록 후에는 버전 2.1.296이 나오는 터미널 화면 — ① 등록 전: command not found ② 등록 후: 버전이 출력됨 · macOS 26.1 zsh 새 계정, 2026-10-13 실제 실행

맥 기본 터미널(zsh)에서는 설치 프로그램이 알려 준 명령을 그대로 실행합니다.

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

bash를 쓰는 리눅스라면 ~/.zshrc 자리에 ~/.bashrc를 넣습니다. 그다음 터미널에서 버전을 확인합니다.

claude --version

이렇게 나오면 성공 2.1.296 (Claude Code)처럼 버전 번호가 나옵니다. 숫자는 설치한 날짜에 따라 다릅니다.

윈도우에서 'claude' is not recognized가 나오면: 터미널 창을 모두 닫고 새로 엽니다. 그래도 안 되면 공식 문서의 PATH 문제 해결에 따라 %USERPROFILE%\.local\bin을 사용자 PATH에 추가합니다.

3단계. 설치 상태 진단하기 (약 1분)

이 단계에서는 진단 명령으로 설치 상태를 한 번 더 봅니다. 읽기만 하는 명령이라 아무것도 바꾸지 않습니다. 터미널에서 실행합니다.

claude doctor

claude doctor 진단 결과 앞부분. 기본 설치 방식, 경로, 자동 업데이트 켜짐이 보인다 — ① 기본 설치(native)로 실행 중 ② 설치 방식 ③ 자동 업데이트 켜짐 · 출력 앞부분, macOS 26.1 새 계정, 2026-10-13 실제 실행

이렇게 나오면 성공 맨 위에 Running: native와 버전이 나오고, 기본 설치라면 Auto-updates: enabled로 자동 업데이트가 켜져 있습니다.

실제 실행 기록 · macOS 26.1 새 계정 · Claude Code 2.1.296 · 2026-10-13 (출력 중 일부)

$ curl -fsSL https://claude.ai/install.sh | bash
  ● Native installation exists but ~/.local/bin is not in your PATH.
✔ Claude Code successfully installed!
  Version: 2.1.296
$ claude --version
zsh:1: command not found: claude
$ echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc && source ~/.zshrc
$ claude --version
2.1.296 (Claude Code)
$ claude doctor
Running: native (2.1.296)
Auto-updates: enabled

claude doctor도 command not found가 나오면: 2단계로 돌아가 PATH 등록을 다시 확인합니다.

4단계. 처음 실행하고 로그인하기 (약 3분)

이 단계에서는 작업할 폴더에서 claude를 처음 실행하고 계정을 연결합니다. 연습용 폴더를 하나 만들어 그 안에서 시작하는 것이 안전합니다. 터미널에서 실행합니다.

mkdir my-first-project && cd my-first-project && claude

처음에는 글자 색 테마를 고르는 화면이 나옵니다. 나중에 /theme로 바꿀 수 있으니 그대로 Enter를 눌러도 됩니다. 다음 화면에서 로그인 방식을 고릅니다.

claude 첫 실행 화면의 로그인 방식 선택. 구독 계정, Console 계정, 외부 클라우드 세 가지 — ① 구독 계정(Pro, Max, Team, Enterprise) ② Console 계정(API 사용량 결제) ③ 외부 클라우드(Bedrock, Foundry, Vertex AI) · macOS 26.1 새 계정, 2026-10-13 실제 첫 실행 화면

Console은 API를 쓴 만큼 결제하는 Anthropic의 개발자 계정입니다.

선택	이런 사람	비용
① 구독 계정	claude.ai를 Pro 이상으로 쓰고 있는 사람	구독료 안에서 사용량 한도까지
② Console 계정	개발자, API 크레딧으로 쓰려는 사람	쓴 토큰만큼 결제
③ 외부 클라우드	회사에서 AWS·Azure·Google Cloud로 쓰는 경우	각 클라우드 요금

①이나 ②를 고르면 브라우저가 열리고 로그인 화면이 나옵니다. 로그인해서 승인하면 터미널로 돌아와 대화창이 열립니다. 이번 기록은 로그인 방식 선택 화면까지 찍었고, 브라우저 로그인 과정은 공식 인증 문서 기준입니다.

브라우저가 자동으로 안 열리면: 공식 문서에 따르면 c를 눌러 주소를 복사한 뒤 브라우저에 붙여 넣으면 됩니다.
ANTHROPIC_API_KEY 환경 변수를 설정해 둔 경우: 클로드 코드가 그 키를 쓸지 묻습니다. 승인하면 로그인 화면 없이 API 결제로 시작합니다. API 키는 대화창이나 채팅에 붙여 넣지 않습니다.

5단계. 내 프로젝트 파일로 첫 질문하기 (약 2분)

이 단계에서는 실제로 쓰는 폴더의 파일을 읽게 해 봅니다. 이 사이트의 작업 폴더에는 다음에 쓸 글 목록(content-plan.md)이 있어서, 그 폴더에서 아래처럼 물었습니다.

content-plan.md를 보고, 1차 목록에서 아직 안 쓴 글 중 다음에 쓸 글 3개를 이유와 함께 한 줄씩 골라 줘

좋은 답이라면 파일 안의 실제 항목과 숫자를 짚어서 고릅니다. 대화창을 열지 않고 한 번만 묻고 끝내려면 claude -p "질문"처럼 -p를 붙입니다.

aiskillwiki 프로젝트 폴더에서 content-plan.md를 읽고 다음에 쓸 글 3개를 고른 claude 첫 질문 결과 — 이미 발행된 글을 빼고 검색량과 직접 해 볼 수 있는지를 근거로 3개를 고른 답 · 로그인된 기존 설치(Claude Code 2.1.292), 2026-10-13 실제 실행

답은 금방 나왔고, 목록에 적힌 검색량과 발행 여부를 정확히 읽어서 골랐습니다. 이 사이트는 실제로 그 순서를 참고해 다음 글을 정했습니다.

처음에는 파일 읽기만 허락하는 것이 안전합니다. 클로드 코드가 파일을 고치거나 명령을 실행하려 할 때는 먼저 허락을 구합니다. 삭제나 외부로 보내는 명령은 자동으로 승인하지 않습니다.

업데이트와 지우기

기본 설치는 백그라운드에서 자동으로 업데이트됩니다. 바로 올리고 싶으면 claude update를 실행합니다. 홈브루·윈겟으로 설치했다면 자동 업데이트가 꺼져 있어 직접 올려야 합니다. 같은 날 확인해 보니 npm으로 깔려 있던 쪽은 2.1.292, 기본 설치로 새로 깐 쪽은 2.1.296이었습니다.

기본 설치를 지우는 명령은 두 줄입니다(맥·리눅스·WSL).

rm -f ~/.local/bin/claude
rm -rf ~/.local/share/claude

기본 설치를 지우는 두 명령을 실행한 뒤 claude 명령을 찾을 수 없다고 나오는 터미널 화면 — ① 두 명령을 실행한 뒤 claude를 찾을 수 없다고 나옴 · macOS 26.1 새 계정, 2026-10-13 실제 실행

설치 방법	지우는 명령
Homebrew	`brew uninstall --cask claude-code`
WinGet	`winget uninstall Anthropic.ClaudeCode`
npm	`npm uninstall -g @anthropic-ai/claude-code`

설정과 대화 기록까지 지우려면 ~/.claude 폴더와 ~/.claude.json 파일을 지웁니다. 허용해 둔 도구, MCP 연결, 세션 기록이 모두 사라지니 필요한 것은 먼저 옮겨 둡니다. 데스크톱 앱과 VS Code 확장도 같은 폴더를 씁니다. 그것들이 깔려 있으면 폴더가 다시 생깁니다.

한계와 주의할 점

윈도우 설치는 이번에 직접 실행하지 않았습니다. 명령과 오류 대처는 공식 문서 기준입니다.
Anthropic이 서비스하지 않는 지역에서는 설치나 로그인이 막힐 수 있습니다.
구독 요금제에는 사용량 한도가 있습니다. 큰 작업을 오래 시키면 한도에 걸려 한동안 기다려야 할 수 있습니다.
설치 명령은 인터넷에서 받은 스크립트를 바로 실행합니다. 회사 컴퓨터라면 보안 정책을 먼저 확인하고, 막혀 있으면 홈브루·윈겟 같은 관리 도구를 씁니다.

대안

이름	다른 점	이럴 때 고르세요
Claude 데스크톱 앱	터미널 없이 창에서 같은 클로드 코드를 씀	터미널이 낯설 때
VS Code 확장	편집기 안에서 씀. 터미널의 `claude` 명령은 따로 설치해야 함	코드를 편집기에서 보며 쓰고 싶을 때
OpenAI 코덱스(Codex)	ChatGPT 계정으로 쓰는 코딩 에이전트	이미 ChatGPT 유료 요금제를 쓰고 있을 때
제미나이 CLI	구글 계정으로 쓰는 터미널 에이전트	구글 생태계에서 쓰거나 다른 모델을 써 보고 싶을 때

자주 묻는 질문

클로드 코드는 무료로 쓸 수 있나요?

설치는 무료지만 쓰려면 Pro 이상 구독이나 Console(API) 결제 계정이 필요합니다. 무료 claude.ai 요금제로는 로그인해도 쓸 수 없습니다.

클로드 코드 설치에 Node.js가 꼭 필요한가요?

아닙니다. 기본 설치 명령은 Node.js 없이 동작합니다. npm으로 설치할 때만 Node.js 22 이상이 필요합니다.

윈도우에서 WSL을 꼭 깔아야 하나요?

아닙니다. PowerShell이나 CMD에서 바로 설치됩니다. 리눅스 도구를 쓰거나 명령을 격리된 환경(샌드박스)에서 돌리고 싶을 때만 WSL 2를 고르면 됩니다.

설치했는데 command not found: claude가 나와요

설치 폴더가 PATH에 없어서입니다. 2단계의 PATH 등록 명령을 실행하거나, 터미널을 닫았다가 새로 엽니다. 예전에 npm으로 설치했던 사람은 기본 설치가 npm 쪽을 지우기 때문에 이 증상이 특히 잘 생깁니다.

클로드 코드 버전 확인과 업데이트는 어떻게 하나요?

claude --version으로 버전을 보고, claude update로 바로 올립니다. 홈브루는 brew upgrade claude-code, 윈겟은 winget upgrade Anthropic.ClaudeCode를 씁니다.

클로드 코드를 완전히 지우려면요?

설치 방법에 맞는 제거 명령을 실행한 뒤, 설정까지 지우려면 ~/.claude와 ~/.claude.json을 삭제합니다. 위 “업데이트와 지우기”에 방법별 명령이 있습니다.

출처

Claude Code 설치 문서, 설치 및 로그인 문제 해결, 인증 문서 (모두 2026-10-13 확인)