Claude Code 설치·로그인 오류 해결: command not found 등

Windows 11 테스트 환경에서 Claude Code를 npm으로, 선택적 의존성과 설치 스크립트를 끈 채 설치하고 claude.exe를 실행해 봤습니다. 돌아온 건 is not compatible with the version of Windows you're running으로 끝나는 한 줄이었어요. 한국어 Windows라면 claude.exe의 버전이 실행 중인 Windows 버전과 호환되지 않습니다로 나오는 그 오류입니다.

메시지만 보면 운영체제나 CPU를 의심하게 되는데, 둘 다 원인이 아니었습니다. 실행 파일 자리에 500바이트짜리 자리표시자가 놓여 있었거든요.

설치 오류는 이렇게 문구가 엉뚱한 곳을 가리킬 때가 많습니다. 그래서 저는 오류 문구를 검색하기 전에 네 단계(내려받기·설치 실행·첫 실행·로그인) 중 어디서 멈췄는지부터 가르길 권합니다.

설치 명령을 실행한 뒤 claude --version부터 쳐 보세요. 버전이 찍히면 남은 문제는 로그인 쪽이고, 명령을 못 찾으면 PATH, 다른 오류가 나면 설치 단계에서 멈춘 겁니다.

2026년 9월 23일 Ubuntu 24.04 테스트 환경(Claude Code 2.1.280)과 10월 1일 Windows 11 · PowerShell 5.1 테스트 환경(2.1.286)에서 직접 확인했고, 오류별 원인과 해결은 공식 문서 기준입니다. 여기서는 설치와 로그인이 끝나기 전의 실패만 다룹니다.

설치 뒤 설정이 안 먹는 문제는 설정이 적용되지 않을 때 무엇이 읽혔는지부터 보는 순서에, 한도·과부하 오류는 한도 오류 메시지를 갈래로 가르는 법에 있습니다.

어디서 멈췄는지부터

설치 한 줄은 네 가지 일을 잇달아 합니다. 스크립트를 내려받고, 실행 파일을 받아 제자리에 놓고, 셸이 그 파일을 찾아 실행하고, 프로그램이 계정에 로그인하죠. 화면의 오류 문구는 어디서 멈췄는지 잘 알려 주지 않아서, 뒤 단계의 문구로 앞 단계의 문제를 찾으면 원인이 안 나옵니다.

단계	넘었다는 신호	확인 방법
1. 내려받기	스크립트 도착	curl -sI 첫 줄이 200
2. 설치 실행	실패 줄 없음	설치 출력 전체 읽기
3. 첫 실행	버전 번호 출력	claude --version
4. 로그인	세션 시작	세션 안에서 /status

claude doctor는 3단계를 넘은 뒤에야 쓸 수 있습니다. claude를 못 찾는 상태에서는 돌릴 수조차 없거든요.

요구사항도 짧게 적어 둡니다. macOS 13.0 이상, Windows 10 1809 이상(Windows Server 2019 이상), Ubuntu 20.04 이상, Debian 10 이상, Alpine Linux 3.19 이상에서 RAM 4GB 이상의 x64 또는 ARM64가 필요하고, 인터넷 연결과 지원 국가 조건이 따로 있습니다. 설치하는 순간에는 여유 메모리 512MB쯤이면 되지만 실행에는 더 필요해요.

내려받기·설치 단계에서 멈췄을 때

이 단계의 오류는 대개 웹페이지, 인증서, 메모리, 잠금 중 하나입니다. 먼저 설치 서버에 닿는지 봅니다.

curl -sI https://downloads.claude.ai/claude-code-releases/latest

HTTP/1.1 403 Forbidden
Content-Type: text/plain; charset=utf-8

위는 막혔을 때의 출력 예입니다. 첫 줄로 판단하면 돼요.

• 200 → 서버에 닿았습니다. 다음 단계 문제입니다.
• 403 → 대개 회사 프록시나 네트워크 필터, 아니면 지원되지 않는 지역입니다. 이 상태에서는 설치 명령을 몇 번 다시 쳐도 같습니다.
• 5xx → 대개 일시적입니다. 몇 분 뒤 다시 합니다.
• 아무것도 안 나옴 → 서버 이름을 풀지 못했거나 연결 자체가 막혔습니다. 바로 아래 절입니다.

회사 네트워크라면 HTTP_PROXY·HTTPS_PROXY를 프록시 주소로 설정한 뒤 설치합니다.

curl: (6) Could not resolve host: claude.ai

설치 명령을 쳤는데 이 한 줄만 남기고 프롬프트로 돌아오는 경우입니다. claude.ai라는 이름을 IP 주소로 바꾸지 못한 거예요. 흔한 원인은 회사 방화벽·프록시가 바깥 연결을 막은 경우와 지역 네트워크 제한입니다.

10월 9일 Ubuntu 24.04(curl 8.5.0)에서 서버 이름을 풀지 못하는 상황으로 설치 명령을 쳐 보니 눈여겨볼 게 두 가지 있더라고요.

하나는 설치가 안 됐는데도 명령 전체는 성공으로 끝난다는 점입니다. curl은 종료 코드 6으로 끝나고, 파이프 뒤의 Bash에는 아무것도 넘어가지 않았어요. 빈 입력을 받은 Bash는 아무것도 하지 않고 0으로 끝나니, 파이프 전체의 종료 코드도 0이 됩니다.

이 명령을 설치 스크립트나 CI에 넣어 두었다면 실패가 그냥 지나가니, 그런 곳에서는 set -o pipefail을 켜 두세요. curl의 실패가 그대로 명령 전체의 실패가 됩니다.

다른 하나는 위의 연결 확인 명령 curl -sI가 이 상황에서 아무것도 출력하지 않는다는 점이에요. -s가 오류 문구까지 숨기기 때문입니다. 출력이 비었다면 막힌 것으로 보면 되고, 문구를 직접 보고 싶으면 -S를 더합니다.

curl -sSI https://downloads.claude.ai/claude-code-releases/latest

curl: (6) Could not resolve host: downloads.claude.ai

회사·학교 네트워크라면 IT 담당자에게 프록시 주소를 받아 HTTPS_PROXY·HTTP_PROXY에 넣고 다시 설치합니다. 프록시를 지정하면 curl은 서버 이름을 직접 풀지 않고 프록시에 맡기므로, 바깥 이름을 풀 수 없는 네트워크에서도 설치가 진행될 수 있어요. 지역 네트워크 제한이라면 다른 네트워크나 VPN에서 시도합니다.

syntax error near unexpected token

설치 명령을 쳤더니 Bash가 문법 오류를 내는 경우입니다. PowerShell에서는 HTML 태그나 CSS를 가리키는 파싱 오류로 나오고, 문구는 PowerShell 버전과 시스템 언어마다 다릅니다.

설치 주소가 스크립트 대신 HTML을 돌려줬고, 셸이 그걸 명령으로 읽은 거예요. 받은 페이지에 App unavailable in region이 있으면 지원되지 않는 국가이고, 본문 없이 403만 왔다면 프록시나 방화벽일 수 있습니다.

curl -sI로 연결부터 확인하고, 지원 국가인데 403이면 프록시 설정을 보세요. 그래도 안 되면 macOS는 brew install --cask claude-code, Windows는 winget install Anthropic.ClaudeCode로 설치합니다. 일시적인 경우도 많아 몇 분 뒤 다시 하면 되기도 합니다.

오류 끝의 토큰은 받은 HTML의 줄바꿈에 따라 `newline'이 되기도 `<'가 되기도 합니다. HTML을 Bash에 직접 넘겨 보니 둘 다 나왔고 원인은 같았어요. 검색할 때는 끝의 토큰을 빼세요.

unable to get local issuer certificate

설치 도중 인증서 오류로 끝나는 경우입니다. curl: (35) TLS connect error, schannel: next InitializeSecurityContext failed, PowerShell의 Could not establish trust relationship for the SSL/TLS secure channel도 같은 갈래예요. 시스템 인증서가 오래됐거나, 중간에서 TLS를 검사하는 회사 프록시가 있는 겁니다.

• Ubuntu·Debian은 sudo apt-get update && sudo apt-get install ca-certificates, macOS는 시스템 업데이트로 인증서를 갱신합니다.
• 회사 프록시라면 그 인증서(CA)를 믿게 해야 합니다. macOS·Linux는 curl --cacert /path/to/corporate-ca.pem -fsSL https://claude.ai/install.sh | bash처럼 지정하고, Windows PowerShell 설치 프로그램은 Windows 인증서 저장소로 검증하므로 IT 담당자에게 등록을 요청합니다.
• 설치 뒤 Claude Code의 API 요청까지 같은 인증서를 믿게 하려면 NODE_EXTRA_CA_CERTS를 그 파일 경로로 설정합니다.

403과 헷갈리기 쉬운데 해법이 다릅니다. 403은 프록시 주소를 알려 주는 문제, 인증서 오류는 프록시의 인증서를 믿게 하는 문제입니다.

curl: (35) error:0A00010B:SSL routines::wrong version number

같은 35번이라 위의 TLS connect error와 한 갈래로 묶기 쉬운데, 이건 인증서 문제가 아닙니다. curl은 TLS로 말을 걸었는데 상대가 평문 HTTP로 답한 거예요. 인증서를 주고받기도 전에 대화가 어긋났으니 인증서를 갱신해도 그대로입니다.

10월 9일 Ubuntu 24.04(curl 8.5.0)에서 평문 HTTP로만 답하는 프록시를 https://로 시작하는 주소로 지정해 설치 스크립트를 받아 보니 바로 이 문구가 나왔습니다. 평문 HTTP 포트에 https://로 직접 붙어도 같았고요. 테스트 환경의 curl은 오류 앞에 OpenSSL/3.0.13:을 붙였는데, 이 부분 없이 검색되는 문구도 있으니 검색할 때는 wrong version number만 넣으세요.

curl: (35) OpenSSL/3.0.13: error:0A00010B:SSL routines::wrong version number

그래서 이 문구가 보이면 프록시 주소의 맨 앞부터 보세요. 변수 이름이 HTTPS_PROXY라서 값도 https://로 적기 쉬운데, 프록시가 평문으로 받는 곳이라면 그게 바로 이 오류가 돼요. 설치 문서의 예시도 HTTPS_PROXY=http://proxy.example.com:8080처럼 http://로 적혀 있습니다.

echo "$HTTPS_PROXY $https_proxy"

curl은 소문자 https_proxy도 읽으니 둘 다 확인하고, IT 담당자에게 받은 주소의 스킴을 그대로 넣은 뒤 다시 설치합니다. 다시 설치했는데도 같은 문구가 나오면 프록시 설정을 비운 채 다른 네트워크에서 위의 연결 확인을 해 보세요. 네트워크 쪽 문제인지가 갈립니다.

Installation was killed before it could finish (exit code 137)

Linux에서 설치 도중 Killed가 찍히고 끝나는 경우로, 작은 VPS나 클라우드 인스턴스에서 흔합니다. 대개 메모리가 모자라 OOM 킬러가 설치 단계(claude install)를 끝낸 거예요. 설치 스크립트도 종료 코드 137을 알리는 줄에 대개 메모리가 바닥났다는 뜻이라고 덧붙이고, 마지막 줄에서 여유 메모리 약 512MB를 확보해 다시 실행하라고 안내합니다.

메모리를 비우고 다시 실행하세요. 여유가 없으면 스왑을 만들어 설치를 마칩니다.

sudo fallocate -l 2G /swapfile
sudo chmod 600 /swapfile
sudo mkswap /swapfile
sudo swapon /swapfile

설치는 이렇게 넘겨도 실행에는 RAM 4GB 이상이 필요하니 가능하면 더 큰 인스턴스를 씁니다. 137이 설치가 아니라 사용 중에 나면 실행 중 exit code 137을 다룬 글을 보세요.

Raw mode is not supported

조직이 배포한 관리 설정에 보안 승인이 필요한 변경이 있으면, 2.1.246 이전 버전은 설치 도중 승인 창을 띄우려 합니다. 승인 창은 터미널 입력이 필요한데 curl … | bash는 입력이 파이프라 실패하는 거죠.

설치 명령을 그대로 다시 실행하면 됩니다. 스크립트는 예전 버전을 지정해도 최신 릴리스의 설치 명령을 쓰고, v2.1.246 이상은 승인 창을 다음 대화형 세션으로 미룹니다. 단, 조직 설정이 시작 때 설정 가져오기를 기다리게 돼 있으면(forceRemoteSettingsRefresh 등) 승인 창이 여전히 뜨고 파이프 설치도 여전히 실패합니다.

Failed to download binary: The process cannot access the file ... because it is being used by another process

Windows에서 설치 프로그램이 %USERPROFILE%\.claude\downloads에 쓰지 못한 경우입니다. 대개 이전 설치 시도가 아직 돌고 있거나 백신이 받다 만 파일을 검사 중이에요. 다른 PowerShell 창을 닫고 검사가 끝나기를 기다린 뒤, 그 폴더를 지우고 다시 설치하세요.

Error: Cask 'claude-code' is not installed.

brew uninstall --cask claude-code나 brew upgrade claude-code를 쳤더니 Homebrew가 이렇게 답하는 경우입니다. Homebrew 소스에서 이 문구가 나오는 자리를 찾아봤어요. Homebrew가 설치 기록을 갖고 있지 않은 cask를 지우거나, 이름을 지정해 올리려 할 때 납니다(--force를 붙이지 않은 경우).

Claude Code에서 이렇게 되는 경우는 두 가지로 보입니다.

• claude-code@latest로 설치해 놓고 claude-code로 명령을 친 경우. Homebrew에는 stable 채널의 claude-code와 latest 채널의 claude-code@latest가 따로 있고, 올리든 지우든 설치한 이름 그대로 써야 합니다.
• 공식 설치 스크립트나 npm으로 설치해 놓고 brew로 관리하려는 경우. Homebrew는 자기가 깔지 않은 Claude Code를 모릅니다.

먼저 Homebrew에 무엇이 깔려 있는지 봅니다.

brew list --cask | grep claude-code

claude-code@latest가 나오면 그 이름으로 다시 치면 됩니다. 아무것도 안 나오면 Homebrew로 설치한 게 아니니, claude doctor의 Running: 줄로 실제로 도는 설치 방식을 확인하세요. Ubuntu 테스트 환경의 네이티브 설치본은 Running: native (2.1.295)로 나왔습니다.

네이티브 설치는 백그라운드에서 스스로 업데이트하고 직접 올릴 때는 claude update를 씁니다. 방식별 명령은 설치 방식별 업데이트 명령과 안 될 때 보는 순서에 정리해 두었습니다.

이름이 비슷한 Cask 'claude-code' is unavailable: No Cask with this name exists는 다른 문제입니다. 로컬 Homebrew의 cask 목록이 그 cask가 나오기 전 것이라, brew update 뒤 다시 설치하면 됩니다.

첫 실행에서 멈췄을 때

claude --version이 버전을 찍지 않으면 이 단계입니다. 저는 PATH, 자리표시자, CPU 순서로 의심합니다. 비슷해 보이는 세 경우를 먼저 갈라 두면 이렇습니다.

보이는 것	뜻
명령을 찾을 수 없음	파일이 PATH에 없음
claude native binary not installed, Windows 호환 오류	파일은 있는데 자리표시자
Illegal instruction, Exec format error	실행 파일이 이 CPU·환경에서 못 돎

command not found: claude

플랫폼마다 문구가 다릅니다. macOS zsh: command not found: claude, Linux bash: claude: command not found, Windows CMD 'claude' is not recognized as an internal or external command, PowerShell claude : The term 'claude' is not recognized as the name of a cmdlet입니다.

설치 위치가 PATH에 없는 겁니다. macOS·Linux는 ~/.local/bin/claude, Windows는 %USERPROFILE%\.local\bin\claude.exe에 놓이니, 그 폴더를 셸 설정의 PATH에 넣고 터미널을 새로 여세요.

함정이 하나 있습니다. VS Code 확장만 깔았다면 ~/.local/bin/claude는 없어요. 확장은 자기 패널용 사본을 확장 폴더에 두므로, 터미널에서 쓰려면 따로 설치해야 합니다.

반대로 터미널의 claude는 되는데 VS Code가 Could not locate the Claude CLI on PATH를 띄운다면 원인이 다릅니다. 그 경우는 VS Code가 CLI를 못 찾을 때 확인하는 순서에 따로 정리했습니다.

Windows의 확인 명령과 PATH 등록은 Windows에서 Claude Code를 설치하고 확인하는 순서에 있습니다.

Error: claude native binary not installed.

claude는 찾는데 버전 대신 안내문이 나오는 경우입니다. 선택적 의존성과 스크립트를 모두 끈 채 설치했더니 이렇게 나왔습니다(직접 실행한 출력).

$ ./node_modules/.bin/claude --version
Error: claude native binary not installed.

Either postinstall did not run (--ignore-scripts, some pnpm configs)
or the platform-native optional dependency was not downloaded
(--omit=optional).
…

npm 패키지 @anthropic-ai/claude-code는 실제 실행 파일을 플랫폼별 선택적 의존성으로 따로 받고, 설치 후 스크립트(postinstall)가 그 파일을 claude 자리에 복사합니다. 둘 중 하나라도 건너뛰면 자리표시자가 남아요.

.npmrc의 optional=false, --omit=optional(pnpm --no-optional, yarn --ignore-optional), --ignore-scripts가 흔한 원인입니다.

안내문은 postinstall을 다시 돌리라고 하지만, 실행 파일을 받지 않은 상태에서는 소용없습니다. 돌려 보면 플랫폼 패키지가 없다는 말과 Fallback: node …/cli-wrapper.cjs 줄만 나와요. 이 래퍼도 이미 받은 플랫폼 패키지를 찾아 실행하는 것이라, 패키지가 없으면 Could not find native binary package만 냅니다.

고치는 순서는 이렇습니다.

1. --omit=optional 없이(.npmrc의 optional=false도 지우고) 다시 설치합니다.
2. 스크립트를 막은 환경이면 postinstall을 직접 돌립니다. 성공하면 아무것도 출력하지 않습니다.

npm install @anthropic-ai/claude-code --ignore-scripts
node node_modules/@anthropic-ai/claude-code/install.cjs
./node_modules/.bin/claude --version

확인할 곳은 npm이 말하는 패키지 수입니다. Ubuntu 테스트 환경에서는 이렇게 달라졌어요.

설치	npm 출력	claude --version
선택적 의존성 끔	added 1 package	안내문
다시 설치 + postinstall	added 2 packages	2.1.280 (Claude Code)

늘어난 하나가 플랫폼별 실행 파일입니다. 이게 안 내려오면 postinstall을 몇 번 돌려도 그대로예요. 다시 설치하다 npm error code ENOTEMPTY가 나면 다른 문제로, npm error path가 가리키는 폴더와 그 옆 .claude-code-* 임시 폴더를 지우고 다시 설치합니다.

Windows: claude.exe의 버전이 실행 중인 Windows 버전과 호환되지 않습니다

맨 앞에 적은 그 오류입니다. Windows에서는 같은 자리표시자가 안내문 대신 운영체제 오류로 나타나요. Windows 11 테스트 환경에서 Claude Code 2.1.286을 같은 방식으로 설치해 재현했고, CMD에서는 이렇게 나왔습니다(종료 코드 216).

This version of <프로젝트 경로>\node_modules\@anthropic-ai\claude-code\bin\claude.exe is not compatible with the version of Windows you're running. Check your computer's system information and then contact the software publisher.

한국어 Windows에서는 claude.exe의 버전이 실행 중인 Windows 버전과 호환되지 않습니다. 컴퓨터의 시스템 정보를 확인하고 소프트웨어 게시자에게 문의하십시오.로, PowerShell에서는 Program 'claude.exe' failed to run: The specified executable is not a valid application for this OS platform.으로 나옵니다.

이 상태의 bin\claude.exe는 500바이트짜리 셸 스크립트입니다. Linux는 이걸 실행해 안내문을 보여 주지만, Windows는 실행 파일로 읽지 못해 안내문이 한 줄도 안 나와요.

메시지가 “Windows 버전”을 탓해서 운영체제나 CPU를 의심하게 되는데, 이 경우엔 둘 다 원인이 아니었습니다. postinstall을 돌리면 “실행하면 안내문이 나온다”고 알려 주는데 실제로는 이 오류가 나와서 더 헷갈렸고요.

가르는 방법은 파일 크기입니다. 전역 설치라면 파일은 %APPDATA%\npm\node_modules\@anthropic-ai\claude-code\bin\claude.exe에 있습니다.

(Get-Item .\node_modules\@anthropic-ai\claude-code\bin\claude.exe).Length

상태	claude.exe 크기
자리표시자	500바이트
정상(2.1.286)	245,092,000바이트(약 234MB)

고치는 순서는 Linux와 같습니다. 선택적 의존성을 받도록 다시 설치해 @anthropic-ai/claude-code-win32-x64를 내려받고, postinstall을 돌립니다. 그 뒤 claude.exe가 500바이트에서 245,092,000바이트로 바뀌었고 2.1.286 (Claude Code)가 찍혔습니다.

오류 코드 216은 실행 파일 형식이 Windows와 맞지 않을 때 쓰이므로, 파일 크기가 정상인데도 이 메시지가 나오면 아래 CPU 종류 문제부터 보세요.

Illegal instruction과 Exec format error

두 문구는 원인이 다릅니다.

• Illegal instruction: CPU 종류가 어긋났거나(예: ARM 서버에 x86 실행 파일), AVX 명령어가 없는 CPU입니다. 대략 2013년 이전 Intel·AMD CPU와 AVX를 넘기지 않는 가상 머신이 해당합니다.
• cannot execute binary file: Exec format error(WSL): WSL1의 알려진 문제입니다. 실행 파일 헤더 형태가 바뀌어 WSL1이 읽지 못합니다.

CPU 종류는 uname -m(PowerShell은 $env:PROCESSOR_ARCHITECTURE), AVX는 grep -m1 -ow avx /proc/cpuinfo로 봅니다. avx가 찍히면 있는 것이고 아무것도 안 나오면 없는 것입니다.

CPU 종류가 다르거나 AVX가 없으면 설치 방법을 바꿔도 소용없습니다. 다른 방법도 같은 실행 파일을 받기 때문이에요. AVX가 없는 CPU에는 실행 파일 차원의 우회법이 없어 공식 이슈를 지켜봐야 합니다. WSL1이면 wsl --set-version <DistroName> 2로 WSL2로 바꾸거나, WSL1에 남아야 한다면 ~/.bashrc에 동적 링커를 거쳐 실행하는 claude() 함수를 둡니다.

설치 뒤 Error loading shared library libstdc++.so.6가 나면, 설치 프로그램이 시스템과 다른 실행 파일 변형을 받았을 수 있습니다(musl 크로스 컴파일 패키지가 깔린 glibc 시스템을 musl로 오인하는 경우 등).

ldd --version 2>&1 | head -1에 GLIBC가 보이면 glibc(테스트 환경 출력: ldd (Ubuntu GLIBC 2.39-0ubuntu8.7) 2.39), musl이 보이면 musl입니다. glibc인데 musl용을 받았다면 지우고 다시 설치하고, 실제로 musl(Alpine 등)이면 apk add libgcc libstdc++ ripgrep을 실행합니다.

버전은 패키지 목록이 아니라 실행 파일에 묻기

Ubuntu 테스트 환경에서 두 명령이 다른 숫자를 말했습니다.

명령	결과
npm -g ls @anthropic-ai/claude-code	2.1.42
claude --version	2.1.280 (Claude Code)

지금 실제로 도는 버전은 claude --version이 알려 줍니다. 설치본이 여럿이면 버전이 어긋나거나 예상과 다르게 동작할 수 있으니 which -a claude로 모두 세어 보세요. 업데이트했는데 이 값이 그대로라면 설치 방식별 업데이트 명령과 안 될 때 보는 순서를 보면 됩니다.

로그인에서 막혔을 때

원인이 뚜렷하지 않으면 깨끗하게 다시 로그인하는 게 먼저입니다. 세션 안에서 /logout → Claude Code 종료 → claude로 다시 시작하면 대부분 풀려요. 그래도 안 풀리는 대표적인 경우가 아래입니다.

OAuth error: Invalid code. Please make sure the full code was copied

로그인 코드가 만료됐거나 복사하다 잘린 경우입니다. Enter로 다시 시작하고 브라우저가 열리면 빠르게 마치세요. 브라우저가 안 열리면 c로 전체 URL을 복사하고, SSH 같은 원격 세션이면 그 URL을 사용자 쪽 브라우저에서 엽니다.

WSL2·SSH·컨테이너에서는 브라우저가 다른 호스트에서 열려 Claude Code로 돌아오지 못하는 일이 많습니다. 그러면 브라우저가 코드를 보여 주니 터미널의 Paste code here if prompted 자리에 붙여 넣습니다. 붙여 넣기가 안 먹으면 터미널의 다른 붙여 넣기 단축키를 쓰거나, 표준 입력으로 코드를 받는 claude auth login을 씁니다.

API Error: 403 — 로그인은 됐는데 요청이 거부될 때

API Error: 403 {"error":{"type":"forbidden","message":"Request not allowed"}}는 계정 권한, 구독 상태, 또는 중간 프록시 문제입니다.

• Pro·Max 사용자는 계정 설정에서 구독이 활성인지 봅니다.
• Console 계정은 “Claude Code”나 “Developer” 역할이 있는지 봅니다. 관리자가 Console의 Settings → Members에서 정합니다.
• 프록시 뒤라면 프록시가 API 요청에 끼어들었을 수 있습니다.

This organization has been disabled — 구독이 살아 있는데 조직이 비활성이라고 할 때

환경 변수 ANTHROPIC_API_KEY가 구독 로그인을 덮은 경우입니다. 이 키를 한 번 승인하면 Claude Code는 구독 대신 키를 쓰고, 키가 비활성·만료된 조직의 것이면 API Error: 400 ... "This organization has been disabled"가 납니다.

예전 직장이나 지난 프로젝트의 키가 셸 프로필에 남은 경우가 흔하고, 비대화형 모드(-p)에서는 승인 없이 키가 있으면 늘 씁니다.

macOS·Linux는 unset ANTHROPIC_API_KEY, Windows PowerShell은 Remove-Item Env:ANTHROPIC_API_KEY로 지우고 다시 실행하세요. 다시 생기지 않게 ~/.zshrc·~/.bashrc·~/.profile의 export ANTHROPIC_API_KEY=... 줄을, Windows는 $PROFILE과 사용자 환경 변수를 정리합니다.

지금 어느 방식으로 붙었는지는 /status로 봅니다.

세션이 끝날 때마다 다시 로그인하라고 하면 토큰 만료 쪽입니다. /login으로 다시 인증하고, 반복되면 시스템 시계를 확인하세요. 토큰 검증이 정확한 시각에 기대기 때문입니다.

macOS는 자격 증명을 로그인 키체인에 저장하는데, 키체인이 쓰기를 거부하면 평문 파일에 저장하고 claude doctor가 경고로 알려 줍니다.

다른 사람들이 겪은 문제

공개된 GitHub 이슈에서 확인한 내용입니다. 네 건 모두 설치 명령이 끝난 뒤 실행하거나 출력을 끝까지 읽어야 문제가 드러났다는 점에서 같은 이야기를 합니다. 마지막 줄의 “완료”를 믿지 말라는 거죠.

• 갱신 성공 메시지 뒤에 자리표시자: dimension-zero(2026-09-23, #96265)는 claude update가 Successfully updated from 2.1.276 to version 2.1.280을 출력했는데 claude.exe가 The specified executable is not a valid application for this OS platform으로 실행되지 않았다고 보고했습니다. 남은 파일은 자리표시자였고, 실행 중인 프로세스가 붙든 .exe를 npm이 못 바꾼 것으로 추정했으며, 패키지 폴더에서 node install.cjs를 돌리면 다시 동작한다고 적었습니다. 작성 시점에 열려 있습니다.
• 실패 줄 뒤에 완료 줄: mmoreno43(2026-02-03, #22756)은 회사 워크스테이션에서 PowerShell 설치가 unable to get local issuer certificate로 실패했는데, ✘ Installation failed 몇 줄 뒤 마지막 줄에 ✅ Installation complete!가 찍혔다고 보고했습니다. NODE_EXTRA_CA_CERTS로도 안 풀렸고 원인·해결은 이슈에 없습니다. 중복으로 닫혔습니다.
• AVX 없는 CPU: mauroencinas(2026-04-18, #50384)는 AVX·AVX2가 없는 CPU에서 npm install -g @anthropic-ai/claude-code@2.1.113 뒤 claude --version이 Illegal instruction으로 죽는다고 보고했습니다. 네이티브 실행 파일로 바뀐 변경과 관련 있다고 추정했고 not planned로 닫혔습니다.
• WSL1: mbasilepa(2026-03-25, #38788)는 2.1.81까지는 됐지만 2.1.83부터 cannot execute binary file: Exec format error가 난다고 보고했습니다. 원인·우회법은 이슈에 없고, 위의 WSL2 전환과 동적 링커 우회는 공식 문서의 방법입니다.

마치며

설치 오류를 재현해 보니, 문구 자체보다 그 문구가 어느 단계에서 나왔는지가 훨씬 많은 걸 알려 줬습니다. “Windows 버전과 호환되지 않는다”는 말이 실은 500바이트짜리 파일 이야기였던 것처럼요.

그래서 막히면 curl -sI → 설치 출력 → claude --version → /status 순서로 어디까지 넘었는지부터 보시길 권합니다. claude를 찾는데 안 돈다면 자리표시자를, 구독이 거부되면 셸에 남은 ANTHROPIC_API_KEY를 먼저 의심하시고요.

무엇보다 설치 명령의 마지막 줄을 믿지 말고 claude --version을 한 번 쳐 보세요. 서버 이름조차 못 풀어 아무것도 설치되지 않았을 때도 curl … | bash는 종료 코드 0으로 끝나거든요. 설치를 넘겼다면 다음으로 막히는 곳은 대개 설정이니, 설정 파일 네 개와 우선순위를 이어서 보면 됩니다.