클로드코드 설치 방법, 윈도우·맥 명령어와 오류 해결 (2026)

클로드코드(Claude Code)는 Anthropic이 만든 AI 코딩 도구입니다. 터미널(명령어를 입력하는 글자 창)에서 실행되며, 컴퓨터의 파일을 읽고 고치고 명령을 실행합니다. 공식 입문 안내는 코드를 몰라도 원하는 것을 말로 설명하면 Claude가 코드를 써 준다고 설명합니다.

무료(Free) 요금제로는 쓸 수 없습니다. 공식 설치 문서는 Pro, Max, Team, Enterprise 구독이나 Claude Console(선불 크레딧으로 쓰는 API) 계정이 필요하다고 적고 있습니다. 요금표에서도 Free 열의 Claude Code 항목은 No로 표시됩니다.

개인 요금제 가격은 Pro가 월 결제 시 월 20달러, 연간 결제 시 월 17달러(200달러 선불)입니다. Max는 월 100달러부터이며 Pro의 5배 또는 20배 사용량 중에서 고릅니다. 표시 가격에는 세금이 포함되지 않았고, 요금표는 가격과 요금제가 바뀔 수 있다고 밝힙니다.

터미널이 부담스러우면 데스크톱 앱이라는 길도 있습니다. 공식 문서는 macOS·Windows용 데스크톱 앱으로 터미널 없이 Claude Code를 쓸 수 있다고 안내합니다. 이 글은 터미널 설치를 기준으로 설명합니다.

직접 확인하기: Claude 요금제 안내(Anthropic)

공식 시스템 요구사항은 macOS 13.0 이상, Windows 10 1809 이상(또는 Windows Server 2019 이상), Ubuntu 20.04 이상, Debian 10 이상입니다. 메모리는 4GB 이상, 프로세서는 x64 또는 ARM64가 필요합니다. 인터넷 연결이 있어야 하고 Anthropic 지원 국가에서만 쓸 수 있으며, 한국(South Korea)은 지원 국가 목록에 들어 있습니다.

맥에서는 Cmd + Space로 Spotlight를 열고 Terminal을 입력해 터미널을 엽니다. 윈도우에서는 Win + X를 누르고 Windows PowerShell(또는 터미널)을 고릅니다. 맥 버전은 애플 메뉴의 「이 Mac에 관하여」에서 확인합니다.

윈도우에는 PowerShell과 CMD(명령 프롬프트) 두 가지 창이 있고 설치 명령이 서로 다릅니다. 줄 앞에 PS C:\Users\이름> 처럼 PS가 붙으면 PowerShell, PS 없이 C:\로 시작하면 CMD입니다. 창을 헷갈려 다른 쪽 명령을 넣으면 설치 대신 오류가 납니다.

윈도우에서 Git for Windows 설치는 선택 사항입니다. 설치하면 Claude Code가 Git Bash를 쓰고, 없으면 PowerShell을 대신 씁니다. 공식 입문 안내는 Git 설치 화면에서 기본값 그대로 Next를 누르면 된다고 설명합니다.

직접 확인하기: Claude Code 시스템 요구사항(Advanced setup)

PowerShell을 열고 irm https://claude.ai/install.ps1 | iex 를 붙여 넣은 뒤 Enter를 누릅니다. irm은 설치 파일을 내려받고 iex는 그 파일을 실행합니다. 공식 문서는 관리자 권한으로 실행할 필요가 없다고 밝힙니다.

CMD에서 설치할 때는 curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd 를 한 줄 그대로 넣습니다. 앞부분만 넣으면 설치되지 않고 스크립트 글자만 화면에 나옵니다. winget install Anthropic.ClaudeCode 로도 설치할 수 있지만 이 방식은 자동 업데이트가 되지 않습니다.

설치가 끝나면 「Claude Code successfully installed!」 문구가 나옵니다. 이때 지금 창을 닫고 새 PowerShell 창을 열어 claude --version 을 입력합니다. 버전 번호 뒤에 (Claude Code)가 붙어 나오면 정상입니다.

새 창을 여는 이유는 설치를 실행한 창이 예전 PATH(프로그램을 찾는 폴더 목록)를 그대로 갖고 있기 때문입니다. 설치 파일은 %USERPROFILE%\.local\bin\claude.exe 위치에 놓입니다. 시작 메뉴에서 Windows PowerShell (x86)을 열면 32비트 창이라 설치가 거부되므로 (x86)이 없는 항목을 씁니다.

직접 확인하기: Claude Code 터미널 입문 안내(Windows)

터미널에 curl -fsSL https://claude.ai/install.sh | bash 를 붙여 넣고 Enter를 누릅니다. 같은 명령이 리눅스와 WSL(윈도우 안의 리눅스 환경)에서도 쓰입니다. 설치 파일은 ~/.local/bin/claude 위치에 놓입니다.

설치가 끝나면 새 터미널 창을 열고 claude --version 을 입력합니다. command not found가 나오면 설치 마지막에 Setup notes로 출력된 명령을 그대로 실행합니다. 이 공식 설치 방식(네이티브 설치)은 백그라운드에서 자동으로 업데이트됩니다.

Homebrew를 쓰고 있다면 brew install --cask claude-code 로도 설치할 수 있습니다. 이 방식은 자동 업데이트가 되지 않아 brew upgrade claude-code 를 직접 실행해야 합니다. 「No Cask with this name exists」가 나오면 brew update 를 먼저 실행하고 다시 설치합니다.

npm 설치도 공식 문서에 남아 있습니다. Node.js 22 이상에서 npm install -g @anthropic-ai/claude-code 를 실행하며, 문서는 sudo를 붙이면 권한 문제와 보안 위험이 생긴다고 경고합니다. 공식 문서가 권장(Recommended)으로 표시한 방식은 네이티브 설치입니다.

직접 확인하기: Claude Code Quickstart(설치 명령)

작업할 폴더에서 터미널을 열고 claude 를 입력하면 대화 화면이 열립니다. 처음 실행하면 로그인 안내가 나오고 브라우저 창이 열립니다. 구독한 Claude 계정으로 로그인하면 인증 정보가 저장돼 다음부터는 다시 로그인하지 않습니다.

폴더 이동은 cd 다음에 폴더 경로를 넣는 방식이며, 이는 Claude Code 기능이 아니라 일반적인 터미널 사용법입니다. 공식 입문 안내는 프로젝트가 없어도 Claude에게 새로 시작하도록 요청할 수 있다고 설명합니다.

메시지를 입력하고 Enter를 누르면 Claude가 답합니다. 터미널에서는 마우스로 누를 수 없어 화살표 키로 고르고, 실행 중인 작업은 Esc로 멈춥니다. 끝낼 때는 /exit 를 입력하거나 빈 줄에서 Ctrl + D를 두 번 누릅니다.

파일을 만들거나 바꾸기 전에 허락을 묻는 화면이 나오면 Yes를 고릅니다. v2.1.283 이후 버전은 자동 모드로 시작해 대부분의 작업을 묻지 않고 진행하며, Shift+Tab으로 권한 모드를 바꿀 수 있습니다. 회사 설정이나 조직 정책에 따라 시작 모드가 다를 수 있습니다.

/help 는 쓸 수 있는 명령 목록을 보여 줍니다. /clear 는 새 대화를 시작하고, /compact 는 지금까지의 대화를 요약해 공간을 비웁니다. /context 는 대화가 차지한 용량을 색깔 칸으로 보여 주고, /usage 는 요금제 사용 한도와 초기화 시각을 보여 줍니다.

직접 확인하기: Claude Code 명령어 목록(Commands)

한국어 윈도우 CMD에서 「'claude'은(는) 내부 또는 외부 명령, 실행할 수 있는 프로그램, 또는 배치 파일이 아닙니다.」가 나오면 설치 폴더가 PATH에 없는 상태입니다. 공식 문서의 영문 오류 「'claude' is not recognized as an internal or external command」와 같은 오류입니다. 맥에서는 「zsh: command not found: claude」로 나옵니다.

먼저 창을 모두 닫고 새 창에서 claude --version 을 다시 입력합니다. 그래도 안 되면 PowerShell에서 공식 문서의 두 줄 명령을 실행해 %USERPROFILE%\.local\bin 폴더를 사용자 PATH에 더하고 창을 다시 엽니다. CMD만 쓴다면 시스템 설정의 환경 변수 화면에서 같은 경로를 사용자 PATH에 더합니다.

맥에서는 echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc 를 실행하고 이어서 source ~/.zshrc 를 실행합니다. 그 뒤 새 터미널을 열고 다시 시도합니다. ~/.local/bin/claude 파일 자체가 없으면 설치가 끝나지 않은 것이므로 설치 명령을 다시 실행합니다.

「'irm' is not recognized」가 나오면 CMD에 PowerShell 명령을 넣은 것입니다. 반대로 「The token '&&' is not a valid statement separator」는 PowerShell에 CMD 명령을 넣은 경우입니다. 맥용 curl 명령을 PowerShell에 넣으면 'fsSL' 매개변수를 찾을 수 없다는 오류가 납니다.

맥·리눅스에서 권한 오류가 나면 설치 폴더(~/.local/bin, ~/.claude)에 쓸 권한이 없는 경우입니다. 공식 문서는 sudo mkdir -p ~/.local/bin 과 sudo chown -R $(whoami) ~/.local 로 폴더 주인을 내 계정으로 바꾸는 방법을 안내합니다. 윈도우 npm 설치에서 「running scripts is disabled on this system」이 나오면 Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser 를 실행하거나 네이티브 설치로 바꿉니다.

직접 확인하기: Claude Code 설치·로그인 문제 해결

브라우저가 자동으로 열리지 않으면 로그인 화면에서 c를 눌러 주소를 복사하고 브라우저에 직접 붙여 넣습니다. 「OAuth error: Invalid code」는 로그인 코드가 만료됐거나 일부만 복사된 경우라 Enter로 다시 시도해 빨리 끝냅니다. 원인을 모르겠으면 /logout 후 Claude Code를 닫고 claude 로 다시 로그인합니다.

로그인 뒤 「API Error: 403 Request not allowed」가 나오면 Pro·Max 이용자는 claude.ai 설정에서 구독이 활성 상태인지 확인합니다. 회사 프록시가 요청을 막아도 같은 오류가 날 수 있습니다. /status 를 입력하면 지금 어떤 계정과 인증 방식으로 접속했는지 볼 수 있습니다.

「You've hit your session limit · resets 3:45pm」 같은 문구는 요금제 사용량을 다 쓴 상태라는 뜻입니다. 세션 한도와 주간 한도는 모든 모델에 공통이라 모델을 바꿔도 풀리지 않고, 메시지에 적힌 초기화 시각까지 기다려야 합니다. /usage 로 남은 한도를 보고, Pro·Max는 /usage-credits 로 추가 사용량을 살 수 있습니다.

회사망에서 설치가 멈추면 방화벽이나 프록시가 downloads.claude.ai 접속을 막고 있을 수 있습니다. 공식 문서는 IT 담당자에게 프록시 주소를 받아 HTTPS_PROXY 값을 정한 뒤 설치하는 방법을 안내합니다. 과학기술정보통신부와 KISA의 「인공지능(AI) 보안 안내서」도 이용자 수칙으로 중요 정보 입력 금지를 제시하므로, 회사 자료를 맡기기 전에 사내 규정을 확인합니다.

직접 확인하기: Claude Code 오류 안내(사용 한도)

• Claude Code는 Pro, Max, Team, Enterprise 또는 Console 계정이 필요하며 무료 claude.ai 요금제에는 포함되지 않습니다. Anthropic Claude Code 공식 문서
• 공식 시스템 요구사항은 macOS 13.0 이상, Windows 10 1809 이상, 메모리 4GB 이상입니다. Anthropic Claude Code 공식 문서
• Windows에서는 관리자 권한 없이 PowerShell이나 CMD에서 설치 명령을 실행합니다. Anthropic Claude Code 공식 문서
• 설치 후 claude가 인식되지 않으면 설치 폴더가 PATH에 없는 것이며 새 창을 열거나 PATH에 폴더를 더해 해결합니다. Anthropic Claude Code 공식 문서
• Pro 요금제는 월 결제 시 월 20달러, 연간 결제 시 월 17달러(200달러 선불)이며 표시 가격에 세금은 포함되지 않습니다. Anthropic