Claude Code 설치하기: 운영체제별 공식 명령과 첫 실행

Claude Code란 무엇이며, 왜 터미널에서 사용하나요?#

소프트웨어 개발 경험 없이 바이브 코딩을 시작하는 사람은 거의 누구나 터미널을 두려워합니다. 해커 영화에 나오는 검은 창처럼 보이지만, 실제로는 명령을 입력하는 한 줄일 뿐입니다. Claude Code는 사용자가 말로 작업을 설명하는 동안 스스로 파일을 열고, 수정하고, 검사를 실행하기 위해 바로 이 터미널이 필요합니다.

Anthropic은 제품을 다음과 같이 설명합니다.

익숙한 채팅과의 차이는 간단합니다. 브라우저에서는 창과 편집기 사이를 오가며 코드를 직접 복사해야 합니다. Claude Code는 프로젝트 폴더로 직접 들어가 필요한 파일을 읽고, 변경 사항을 적용한 뒤 무엇을 바꿨는지 보여줍니다. 결정하고 승인하는 사람은 여전히 사용자이며, Claude Code는 기계적인 작업을 대신 처리합니다.

정말 터미널을 사용하고 싶지 않다면 Anthropic의 일반 창 기반 데스크톱 앱이나 브라우저에서 바로 실행되는 claude.ai/code 웹 버전을 사용할 수 있습니다. 하지만 가장 강력하고 유연한 옵션은 터미널 버전이며, 이 글에서는 터미널 버전을 다룹니다.

공식 Claude Code 웹사이트는 어디이며, 무엇을 다운로드해야 하나요?#

초보자가 가장 먼저 혼란스러워하는 점은 공식 Claude Code 웹사이트가 어디에 있고 다운로드하려면 무엇을 클릭해야 하는지입니다. 추측하지 않아도 되도록 Anthropic의 공식 주소를 표로 정리했습니다.

일반 프로그램처럼 웹사이트에서 설치 파일을 다운로드하지 않습니다. 기대와 다른 방식이죠. 터미널 명령으로 설치하면 시스템에 맞는 버전이 다운로드됩니다. 이 글에는 Mac, Windows, Linux용 정확한 명령이 나와 있습니다.

자주 빠지는 함정은 이름입니다. clode code, clade code, слод код, clode design으로 잘못 쓰는 경우가 많습니다. 제품 이름은 Claude Code이며 au가 들어갑니다. 공식 웹사이트를 찾을 때 이 점을 기억하세요. 비슷한 철자의 도메인은 다른 곳의 소유입니다.

정확한 npm 패키지 이름도 알아두면 좋습니다. 표준 패키지는 @anthropic-ai/ 접두사가 붙은 @anthropic-ai/claude-code입니다. Anthropic은 접두사가 없는 짧은 이름 claude-code를 보유하고 있으며, 이는 같은 패키지를 가리키는 공식 참조입니다. 간단한 원칙은 게시자가 Anthropic이어야 하고, 설치에 사용할 이름에는 접두사가 있어야 한다는 것입니다.

Claude Code 설치 우분투: 지원 버전과 컴퓨터 요구 사항#

Claude Code의 요구 사항은 높지 않습니다. Anthropic 서버가 대부분의 작업을 처리하고, 사용자의 컴퓨터는 요청을 보내고 응답을 받기만 합니다.

오해가 가장 많은 Node.js에 대해 따로 설명하겠습니다. Anthropic이 직접 권장하는 네이티브 설치 프로그램은 Node.js가 전혀 필요 없습니다. 독립 실행형 파일 하나로 설치됩니다. npm으로 Claude Code를 설치할 때만 Node.js가 필요하며, 이 경우 버전 22 이상이어야 합니다. 오래된 글에는 'Node 18 이상'이라고 되어 있지만, 이는 오래된 정보이므로 22 이상을 기준으로 삼으세요.

기본 버전을 사용하려면 터미널이 필요합니다. 터미널을 쓰고 싶지 않다면 일반 창이 있는 데스크톱 앱을 설치하거나 claude.ai/code 웹 버전을 사용하세요. 터미널 버전은 여전히 더 많은 기능을 제공하므로, 이 글의 나머지 부분에서는 해당 버전의 설치 방법을 설명합니다.

Claude Code를 설치하는 것은 도구를 손에 넣는 것과 같습니다. 하지만 단독으로 사용하면 환각을 일으키는 경우가 많습니다. 프로젝트를 잊고, 없는 내용을 만들어 내며, 작업 중간에 맥락을 놓칩니다. AI 클론, 세컨드 브레인, 컨텍스트 엔지니어링이라는 세 가지를 결합하면 신뢰성을 높일 수 있습니다. 이 세 가지 기둥이 AI의 환각을 막아 줍니다.

Claude Code 설치 Mac: 네이티브 명령과 Homebrew#

Terminal을 엽니다(Mac에 기본으로 포함되어 있습니다. Spotlight에서 Cmd+Space를 누르고 'Terminal'을 입력하세요). 그런 다음 아래 한 줄을 붙여 넣습니다.

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

이 명령은 Anthropic의 공식 주소에서 설치 프로그램을 다운로드해 Claude Code를 설치합니다. Node.js는 필요하지 않습니다. 네이티브 방식은 업데이트도 편리합니다.

이미 Homebrew를 사용 중이라면 두 번째 방법도 있습니다.

brew install --cask claude-code

차이는 업데이트 방식입니다. 네이티브 설치 프로그램은 자동으로 업데이트되지만 Homebrew는 그렇지 않습니다. brew upgrade claude-code 명령으로 직접 업데이트해야 합니다. 프로그램 자체는 같으므로 익숙한 방법을 선택하세요. 잘 모르겠다면 첫 번째 방법을 사용하세요.

Claude Code 설치 윈도우: PowerShell·CMD·WinGet#

먼저 현재 어떤 셸을 사용 중인지 확인하세요. Windows에는 셸이 두 가지 있으며, 각각 명령이 다릅니다. 창을 열고 프롬프트의 시작 부분을 확인하세요. PS C:\>는 PowerShell을 뜻하며, PS 없이 C:\>만 있으면 명령 프롬프트(CMD)입니다.

PowerShell용(시작 버튼을 마우스 오른쪽 버튼으로 클릭하고 'Terminal'을 선택하면 쉽게 열 수 있습니다):

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

명령 프롬프트(CMD)용:

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

세 번째 방법은 기본 제공 패키지 관리자인 WinGet을 사용하는 것입니다.

winget install Anthropic.ClaudeCode

이미 WSL(Windows 내부의 Linux) 환경을 사용하고 있다면 Linux와 같은 명령으로 WSL 안에 Claude Code를 바로 설치하세요. WSL에서 Node를 사용할 때 발생하는 별도의 문제가 있으며, 아래의 일반적인 오류 섹션에서 설명합니다.

Claude Code 설치 리눅스: 네이티브 명령과 패키지 저장소#

널리 쓰이는 배포판에서 기본으로 사용할 방법은 동일합니다. 독립 실행형 설치 프로그램을 사용하세요.

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

Node.js는 필요하지 않습니다. 프로그램은 단일 파일로 제공되며 이후부터 자동 업데이트됩니다.

시스템 패키지 관리자를 통해서만 프로그램을 설치하는 데 익숙하다면 Anthropic의 공식 저장소를 추가할 수 있습니다. Debian과 Ubuntu에는 apt, Fedora와 RHEL에는 dnf, Alpine에는 apk를 사용합니다. 저장소는 키로 서명되어 있으며 stable 및 latest 채널을 제공합니다. 초보자에게는 다소 과한 방법이므로 자세한 내용은 출처 섹션의 문서에 맡기고, 기본적으로 위 명령을 권장합니다.

저렴한 서버에서는 한 가지 문제가 생길 수 있습니다. 컴퓨터의 여유 메모리가 매우 적으면 Killed(코드 137)라는 메시지와 함께 설치가 중단될 수 있습니다. 메모리가 부족해 시스템이 프로세스를 종료한 것입니다. 해결하려면 스왑 파일을 추가하세요. Claude Code를 설치하려면 여유 메모리가 약 512 MB 필요합니다.

Claude Code를 처음 실행하는 방법#

처음 실행하는 데는 몇 분 정도 걸립니다. 과정은 다음과 같습니다.

1. 프로젝트 폴더로 이동

   터미널에서 cd path-to-project 명령으로 작업할 폴더로 이동한 다음 claude를 입력합니다.

2. 계정에 로그인

   로그인 창이 브라우저에서 열립니다. 자동으로 열리지 않으면 c를 눌러 링크를 복사한 뒤 브라우저에 직접 붙여 넣으세요. 브라우저에 코드가 표시되는 경우(WSL이나 원격 서버에서 발생할 수 있음), 그 코드를 터미널에 다시 붙여 넣습니다.

3. 확인 메시지 대기

   로그인하면 터미널에 Login successful이 표시되고 Enter를 누르라는 메시지가 나옵니다.

4. 첫 질문 하기

   '이 프로젝트는 무슨 일을 하나요?'와 같이 프로젝트에 관한 간단한 질문을 해 보세요. Claude가 파일을 읽고 답변합니다.

5. 첫 변경 사항 승인

   변경을 요청하면 Claude가 제안된 변경 사항을 보여주고 확인을 요청합니다. Shift+Tab으로 접근 모드를 전환할 수 있습니다.

세션에서 바로 기본 명령 몇 가지를 익혀 두면 좋습니다. /help는 명령 목록을 표시하고, /clear는 대화 기록을 지우며, /exit는 종료합니다(두 번 Ctrl+D를 눌러도 종료됩니다). /help를 입력하면 Claude가 이 명령들을 직접 보여줍니다.

구독과 API 키 중 어떤 방식으로 로그인해야 하나요?#

로그인할 때 가장 먼저 떠오르는 질문입니다.

로그인 방법은 두 가지이며, 요금을 내는 방식이 다릅니다.

구독으로 로그인하려면 Claude.ai 계정을 사용하면 됩니다. API 키로 로그인하려면 Claude Console(platform.claude.com)에서 키를 발급받으세요. 사용 중에는 선불 잔액에서 요금이 차감됩니다. 키를 ANTHROPIC_API_KEY 환경 변수에 설정하면 Claude Code가 매번 브라우저를 열지 않습니다.

세션 중 /login으로 계정을 전환하고 /logout으로 로그아웃할 수 있습니다.

하지만 유료 이용 권한이 없으면 Claude Code를 실행할 수 없습니다. 아직 계정이 없다면 먼저 가입에 사용할 이메일 주소를 확인하세요. 나중에 변경할 수 없습니다.

설치가 제대로 되었는지 확인하는 방법#

처음부터 알아둘 만한 명령은 세 가지입니다.

첫 번째는 버전을 확인합니다.

claude --version

정상적으로 설치되었다면 X.Y.Z (Claude Code) 형식의 숫자가 표시됩니다. 구체적인 숫자는 버전에 따라 달라집니다. 중요한 점은 명령을 실행했을 때 버전 번호가 반환되는지입니다. 'command not found'가 표시된다면 다른 문제이며, 다음 섹션에서 다룹니다.

두 번째는 문제가 생겼을 때 사용하는 진단 명령입니다.

세 번째는 세션 안에서 실행하는 /status입니다. 로그인 방식, 연결된 이메일 또는 조직, 이용 권한 만료 여부를 보여줍니다. claude update를 실행하면 백그라운드 업데이트를 기다리지 않고 최신 업데이트를 바로 적용할 수 있습니다.

Claude Code 설치 위치와 PATH: claude 명령을 찾을 수 없다면#

초보자가 가장 자주 겪는 문제지만 생각보다 무서운 문제는 아닙니다. 터미널은 컴퓨터 전체에서 명령을 찾지 않고 PATH에 있는 폴더만 확인합니다. Claude Code는 ~/.local/bin/claude(Mac 및 Linux) 또는 %USERPROFILE%\\.local\\bin\\claude.exe(Windows)에 설치됩니다. 해당 폴더가 PATH에 없으면 터미널에서 프로그램을 찾지 못합니다.

Mac과 Linux에서는 폴더를 목록에 추가하세요. 셸 설정 파일(Zsh는 ~/.zshrc, Bash는 ~/.bashrc)을 열고 맨 끝에 다음 줄을 추가합니다.

export PATH="$HOME/.local/bin:$PATH"

그런 다음 터미널을 닫았다가 다시 엽니다(또는 source ~/.zshrc를 실행합니다). 그러면 claude를 찾을 수 있습니다.

설치 및 첫 실행 중 자주 발생하는 오류#

Anthropic의 공식 문제 해결 가이드에 나오는 다섯 가지 문제를 차례로 살펴보겠습니다.

1. npm으로 설치할 때 오래된 Node 버전 사용. @anthropic-ai/claude-code 패키지에는 Node.js 22 이상이 필요합니다. Windows에서는 스크립트 실행이 비활성화되었다는 메시지와 함께 npm이 실패할 수 있습니다. PowerShell 정책이 스크립트 실행을 막고 있는 것입니다. WSL에서 흔히 발생하는 오류는 exec: node: not found입니다. WSL이 Linux용 Node 대신 Windows용 Node를 사용하고 있다는 뜻입니다. npm에 문제가 생기면 네이티브 설치 프로그램으로 바꾸세요. Node가 필요하지 않습니다.
2. 셸에 맞지 않는 설치 프로그램 사용. 'irm' is not recognized는 PowerShell 명령을 명령 프롬프트에 붙여 넣었다는 뜻입니다. The token '&&' is not a valid statement separator는 반대로 CMD 명령을 PowerShell에서 실행했다는 뜻입니다. A parameter cannot be found that matches parameter name 'fsSL'는 Mac/Linux용 명령을 PowerShell에서 실행했다는 뜻입니다. 프롬프트의 시작 부분을 확인하세요. PS C:\는 PowerShell이고 C:\는 CMD입니다.
3. 오래된 API 키가 구독보다 우선함. 구독이 활성 상태인데 환경에 오래된 키가 설정되어 있으면 API Error: 400 ... This organization has been disabled가 표시됩니다. 키가 구독 로그인보다 우선합니다. unset ANTHROPIC_API_KEY로 키를 제거하고(PowerShell에서는 Remove-Item Env:ANTHROPIC_API_KEY 사용), ~/.zshrc와 ~/.bashrc를 확인한 다음 /status를 입력하세요.
4. 성능이 낮은 서버의 메모리 부족. 설치가 Killed라는 단어와 코드 137을 표시하며 중단되면 RAM이 부족하다는 뜻입니다. 여유 메모리가 약 512 MB 필요합니다. 스왑을 추가하면 해결됩니다.
5. 설치 프로그램이 예상하지 못한 내용을 반환함. syntax error near unexpected token '<' 오류나 <!DOCTYPE html> 참조가 나타나면 설치 URL이 설치 스크립트 대신 웹페이지를 반환한 것입니다. 대개 지역 제한, 회사 방화벽 또는 일시적인 장애가 원인입니다. 다른 방법(Homebrew, WinGet)을 시도하거나 몇 분 후 다시 시도하세요.

이러한 오류가 발생하면 먼저 claude doctor를 실행하세요. 무엇이 잘못되었는지 표시하고 어디를 확인할지 제안합니다.

진단 시 유의할 점이 하나 있습니다. 설치 중에 단순히 403이 표시되는 경우 회사 방화벽이나 프록시가 원인일 수도 있습니다. 사무실 네트워크를 사용 중이라면 먼저 접속이 차단되고 있는지 확인하세요.

설치 후 할 일: 첫 단계#

설치는 시작일 뿐입니다. 진짜 작업은 그다음부터 시작되며, 사람들이 처음 맞닥뜨리는 문제는 기억입니다. 언어 모델은 대화 사이에 사용자를 기억하지 않습니다. 새 채팅에서는 컨텍스트에 넣어 준 내용만 알고 있습니다.

따라서 설치 후 첫 번째 실질적인 단계는 프로젝트 루트에 CLAUDE.md 파일을 만드는 것입니다. 프로젝트의 규칙과 컨텍스트를 담은 텍스트 파일이며, Claude Code는 실행할 때마다 이 파일을 읽습니다. 무엇을 하는지, 프로젝트가 어떻게 구성되어 있는지, 무엇이 중요한지를 한 번 설명해 두면 매 대화마다 반복하지 않아도 됩니다.

별도의 가이드에서 이 파일을 작성하고 Claude를 사용자 지정하는 방법을 설명합니다. Claude 사용자 지정 방법을 참고하세요. 2026년 바이브 코딩 도구 전반을 정리한 지도도 만들었습니다.

사람들이 또 자주 묻는 질문#

바이브 코딩의 전체 프레임워크: AI 클론 + 세컨드 브레인 + 컨텍스트 엔지니어링.