가이드 · 2026년 10월 29일

Claude Code 설치와 첫 실행 — 명령 한 줄 설치부터 첫 질문까지

Claude Code를 맥·윈도우·리눅스에 설치하는 공식 명령, 설치 확인(claude --version·claude doctor), 어떤 요금제로 로그인하는지, 첫 세션에서 무엇부터 물어보면 좋은지, 자동 업데이트와 지우는 법까지 공식 문서와 대조해 정리했다.

Claude Code 한국어 실전 가이드 · 1/10편

결론부터. Claude Code 설치는 명령 한 줄이고, 막히는 곳은 대개 설치가 아니라 '요금제'와 'PATH'다. 이 글은 AI(Claude)가 썼고, 내용은 Claude Code 공식 문서 — Quickstart·Advanced setup과 대조했다. 하이아이오는 맥에서 공식 설치 명령(네이티브 설치)으로 깐 Claude Code로 앱·사이트·홍보를 돌리고 있다.

먼저 확인할 것

가장 흔한 착각: 무료 claude.ai 요금제로는 Claude Code를 쓸 수 없다. 공식 문서에 그렇게 적혀 있다. 구독 대신 Console 계정(선불 크레딧)으로 로그인할 수도 있는데, 이때는 쓴 만큼 돈이 나간다.

설치: 내 컴퓨터에 맞는 한 줄

공식 권장은 네이티브 설치다. 터미널을 열고 하나만 붙여 넣는다.

맥·리눅스·WSL:

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

윈도우 PowerShell(줄 앞에 PS C:\가 보이는 창):

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

윈도우 CMD(PS 없이 C:\만 보이는 창):

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

설치 중에는 진행 표시가 안 나온다. 멈춘 것처럼 보여도 기다리면 된다. 관리자 권한도 필요 없다.

다른 설치 방법

Homebrew의 claude-code는 약 1주 늦은 안정판(stable), claude-code@latest는 최신판이다. npm으로 깔 때 sudo를 붙이지 말라고 공식 문서가 경고한다.

윈도우라면

윈도우에서 바로 쓸 수도 있고 WSL 안에서 쓸 수도 있다. Git for Windows를 깔아 두면 Claude Code가 Git Bash로 명령을 실행하고, 없으면 PowerShell로 실행한다. 명령 실행을 격리하는 샌드박스 기능은 WSL 2에서만 된다.

설치 확인

새 터미널 창을 열고:

claude --version

2.1.xxx (Claude Code)처럼 버전이 나오면 끝이다. command not found가 나오면 설치 폴더가 PATH에 아직 없는 것이다. 공식 설치 문제 해결 문서의 'Fix your PATH'를 따른다.

더 자세히 보려면:

claude doctor

세션을 열지 않고 설치 상태·설정 파일 오류·자동 업데이트 상태를 읽기 전용으로 보여 준다. 뭔가 이상할 때 제일 먼저 돌려 볼 명령이다.

첫 실행과 로그인

작업할 프로젝트 폴더로 가서 실행한다.

cd 내-프로젝트-폴더
claude

처음에는 로그인을 묻는다. 안내대로 브라우저에서 로그인하면 되고, 한 번 하면 다시 묻지 않는다. 계정을 바꾸려면 세션 안에서 /login을 친다.

첫 세션에서 해 볼 것

공식 빠른 시작이 권하는 순서대로, 고치기 전에 먼저 묻는다.

1. 이 프로젝트는 뭘 하는 거야? — 파일을 알아서 읽고 요약한다. 파일을 따로 붙여 넣을 필요가 없다.
2. 폴더 구조 설명해 줘, 시작 지점이 어디야?
3. 작은 수정 하나: 메인 파일에 hello world 함수 추가해 줘 — 바꾸기 전에 허락을 물으면 Yes를 고른다.
4. /init — 코드를 살펴보고 빌드·테스트 명령과 규칙을 담은 CLAUDE.md를 만든다. 이미 있으면 덮어쓰지 않고 고칠 점을 제안한다(공식 문서 — Memory).

CLAUDE.md는 세션마다 처음에 읽히는 메모다. 프로젝트용은 ./CLAUDE.md, 내 모든 프로젝트용은 ~/.claude/CLAUDE.md. 우리는 "커밋 메시지 끝에 무엇을 붙인다" 같은 매번 하는 말을 여기에 적어 두고 다시 말하지 않는다.

처음 외워 둘 것

업데이트와 지우기

네이티브 설치는 시작할 때와 쓰는 중에 새 버전을 확인해 백그라운드로 깔고, 다음 실행부터 적용한다. 바로 올리고 싶으면 claude update. 약 1주 늦은 안정판만 받고 싶으면 /config에서 Auto-update channel을 stable로 바꾼다.

지울 때(맥·리눅스, 네이티브 설치):

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

설정·대화 기록까지 지우려면 ~/.claude와 ~/.claude.json도 지운다. 이건 되돌릴 수 없으니 정말 다 지울 때만.

자주 묻는 질문

무료 계정으로 Claude Code를 쓸 수 있나요?

없다. 공식 문서 기준으로 Pro·Max·Team·Enterprise 구독이나 Console(API) 계정이 필요하다. 무료 claude.ai 요금제에는 Claude Code가 포함되지 않는다.

npm 설치와 네이티브 설치, 뭐가 다른가요?

공식 문서에 따르면 npm 패키지도 같은 네이티브 프로그램을 내려받아 연결한다. 차이는 설치 경로와 업데이트 방식이다. 처음이라면 Node.js가 필요 없는 네이티브 설치가 간단하다.

설치는 됐는데 claude 명령을 못 찾는다고 나와요.

설치 폴더가 PATH에 없어서다. 먼저 터미널을 새로 열어 본다. 그래도 안 되면 공식 설치 문제 해결 문서의 PATH 항목을 따른다. claude doctor가 실행되면 다른 문제도 같이 보여 준다.

터미널이 처음이라 겁나요. 다른 방법은요?

데스크톱 앱, VS Code·JetBrains 확장, 웹(claude.ai/code)으로도 쓸 수 있다. 공식 문서에는 터미널을 처음 여는 사람을 위한 터미널 가이드도 있다.

참고한 링크

• Claude Code 공식 문서 — Quickstart
• Claude Code 공식 문서 — Advanced setup
• Claude Code 공식 문서 — Memory(CLAUDE.md)
• Claude Code 공식 문서 — 설치 문제 해결
• Claude Code 권한 모드 6가지
• Claude Code 서브에이전트 만들기

#클로드 코드#Claude Code#설치#설치 방법#claude doctor#CLAUDE.md#시작하기