muaco Tech Note

Claude Codecode.claude.com

Claude Code가 안 될 때설치·로그인·권한 오류 확인 순서

Claude Code가 설치, 로그인, 권한 가운데 어디서 막혔는지 가리고, 갈래별 순서대로 확인해 직접 푸는 법을 정리했습니다.

안녕하세요, muaco입니다.

이 글로 풀 수 있는 문제

Claude Code가 안 될 때는 설치, 로그인, 권한 가운데 어디서 막혔는지부터 가리면 대부분 혼자 풀 수 있습니다. 이 글은 세 갈래를 공식 문제 해결 문서의 순서대로 정리했습니다.

택배가 안 왔을 때를 떠올려 보세요. 물건이 아직 출발하지 않았는지, 출입증이 없어 경비실에서 막혔는지, 열쇠가 없어 문 앞에 놓였는지에 따라 할 일이 다릅니다. 설치, 로그인, 권한이 각각 이 셋에 해당합니다.

2026년 10월에 확인한 공식 문서가 기준입니다. 글에 나오는 버전 번호는 예시라서 여러분 화면과 다를 수 있습니다.

시작 전에 갖춰 둘 준비물

  • 요금제: Pro, Max, Team, Enterprise, Console 계정 가운데 하나가 있어야 합니다. 무료 claude.ai 요금제에는 Claude Code가 들어 있지 않습니다.
  • 운영체제: macOS 13.0 이상, Windows 10 1809 이상, Ubuntu 20.04 이상, Debian 10 이상을 지원합니다. 메모리는 4GB 이상이 필요합니다.
  • 지역: Anthropic이 지원하는 국가에서만 쓸 수 있습니다.
  • 터미널: 터미널(글자로 명령을 쳐서 컴퓨터를 부리는 창)을 열 줄 알면 됩니다. Windows에서는 줄 앞에 PS C:\가 보이면 PowerShell, PS 없이 C:\만 보이면 CMD입니다.

따라 하기: 막힌 곳을 세 갈래로 나누기

먼저, 어디서 멈췄는지 가리기

따라 하기
  1. 새 터미널 창을 열고 claude --version을 입력하세요. 2.1.211 (Claude Code)처럼 버전 번호가 나오면 설치는 끝난 상태입니다.
  2. 번호 대신 command not found나 not recognized가 나오면 아래 설치 갈래 두 묶음을 차례로 보세요.
  3. 버전이 나왔다면 claude doctor로 설치 상태와 설정 파일 오류를 점검하세요. 읽기만 하는 점검이라 아무것도 바뀌지 않습니다.
  4. 로그인하다 OAuth 오류가 나거나 로그인 뒤 API Error: 403이 보이면 로그인 갈래로, permission denied나 EACCES가 보이면 권한 갈래로 가세요. 설치 중 curl: (22)와 함께 뜬 403은 설치 갈래 3단계에서 다룹니다.

설치 명령이 실패할 때

따라 하기
  1. 창에 맞는 설치 명령을 썼는지 보세요. macOS, Linux, WSL은 curl -fsSL https://claude.ai/install.sh | bash, Windows PowerShell은 irm https://claude.ai/install.ps1 | iex입니다.
  2. Windows CMD라면 curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd를 씁니다. 'irm' is not recognized는 CMD에 PowerShell 명령을, The token '&&' is not a valid statement separator는 PowerShell에 CMD 명령을 넣었다는 뜻입니다.
  3. 설치가 syntax error near unexpected token '<'나 curl: (22) ... error: 403으로 끝나면 몇 분 뒤 다시 실행하세요. 설치 주소가 스크립트 대신 웹페이지를 돌려준 경우입니다. 출력에 App unavailable in region이 있으면 지원하지 않는 국가에서 접속한 상태입니다.
  4. 회사망이라면 curl -sI https://downloads.claude.ai/claude-code-releases/latest로 다운로드 서버에 닿는지 확인합니다. 첫 줄에 200이 보이면 닿은 상태입니다. PowerShell에서는 curl 대신 curl.exe를 씁니다.
  5. 응답이 없거나 시간이 초과되면 회사 방화벽이나 프록시(회사망에서 바깥으로 나가는 길목의 중계소)가 막은 경우가 흔합니다. IT 담당자에게 프록시 주소를 받아 그 주소를 담는 환경 변수(프로그램이 켜질 때 읽어 가는 메모지)인 HTTP_PROXY와 HTTPS_PROXY에 넣습니다. macOS·Linux는 아래 두 줄의 proxy.example.com:8080 자리를 받은 주소로 바꿔 실행하세요. 
    export HTTP_PROXY=http://proxy.example.com:8080
export HTTPS_PROXY=http://proxy.example.com:8080
    PowerShell은 아래 두 줄을 쓰고 CMD라면 PowerShell 창을 열어 씁니다. 두 줄을 실행한 그 창에서 설치 명령을 다시 실행하면 됩니다. 
    $env:HTTP_PROXY = 'http://proxy.example.com:8080'
$env:HTTPS_PROXY = 'http://proxy.example.com:8080'

설치 뒤 claude를 못 찾을 때

컴퓨터는 명령을 받으면 미리 적어 둔 서랍 목록만 뒤집니다. 이 목록을 PATH라고 부릅니다. 프로그램이 목록에 없는 서랍에 들어 있으면 깔려 있어도 못 찾습니다.

따라 하기
  1. macOS·Linux는 ls -la ~/.local/bin/claude, PowerShell은 Test-Path "$env:USERPROFILE\.local\bin\claude.exe", CMD는 dir "%USERPROFILE%\.local\bin\claude.exe"로 프로그램이 제자리에 있는지 확인하세요. 파일 정보나 True가 나오면 프로그램은 있습니다. 없다고 나오면 설치 명령부터 다시 실행합니다.
  2. 그 폴더가 PATH에 이미 있는지 봅니다. macOS·Linux는 echo $PATH | tr ':' '\n' | grep -Fx "$HOME/.local/bin", PowerShell은 $env:PATH -split ';' | Select-String '\.local\\bin', CMD는 echo %PATH% | findstr /i "local\bin"입니다. 아무것도 안 나오면 다음 단계로, 폴더 경로가 나오면 아래 막히기 쉬운 곳의 첫 항목으로 가세요.
  3. macOS 기본 셸인 Zsh라면 아래 두 줄로 그 폴더를 PATH에 넣습니다. Bash라면 두 줄의 ~/.zshrc를 Linux는 ~/.bashrc로, macOS는 ~/.bash_profile로 모두 바꿔 입력하세요. 
    echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc
  4. Windows PowerShell이라면 아래 두 줄로 사용자 PATH에 폴더를 더합니다. 
    $currentPath = [Environment]::GetEnvironmentVariable('PATH', 'User')
[Environment]::SetEnvironmentVariable('PATH', "$currentPath;$env:USERPROFILE\.local\bin", 'User')
  5. Windows CMD라면 시스템 설정의 환경 변수 화면에서 사용자 PATH에 %USERPROFILE%\.local\bin을 추가하세요. 그 화면을 찾기 어렵다면 PowerShell 창을 열어 위 두 줄을 실행해도 됩니다.
  6. 열려 있는 터미널 창을 모두 닫고 새 창에서 claude --version을 다시 입력하세요. 버전 번호가 나오면 이 갈래는 끝입니다.

로그인에서 막혔을 때

건물에 들어가려면 경비실에서 신분을 확인받고 출입증을 받습니다. Claude Code의 로그인도 같아서 브라우저에서 계정을 확인받고 출입증을 들고 돌아옵니다.

따라 하기
  1. 로그인 뒤 API Error: 403 Request not allowed가 나오면 claude.ai/settings에서 구독이 살아 있는지 확인하세요. Console 계정이라면 관리자가 Members 화면에서 "Claude Code"나 "Developer" 역할을 줬는지 봅니다.
  2. 브라우저가 저절로 열리지 않으면 로그인 화면에서 c를 누르세요. 로그인 주소가 클립보드에 복사되니 브라우저 주소창에 붙여 넣으면 됩니다.
  3. OAuth error: Invalid code가 나오면 Enter를 눌러 다시 시도하고 브라우저가 열리면 곧바로 끝까지 진행하세요. 로그인 코드가 만료됐거나 복사하다 잘렸을 때 나는 오류입니다.
  4. WSL2나 원격 접속(SSH) 환경이라면 로그인 뒤 브라우저에 코드가 뜹니다. 그 코드를 터미널의 Paste code here if prompted 자리에 붙여 넣으세요.
  5. 붙여 넣어도 반응이 없다면 claude auth login으로 로그인합니다.
  6. MCP 서버나 플러그인 로그인을 써 왔다면, 로그아웃 뒤 다시 연결해야 합니다. 원인이 안 보이면 Claude Code 안에서 /logout을 입력하고 창을 닫은 뒤, claude로 다시 시작해 로그인하세요.

권한 오류가 날 때

방마다 열쇠가 있듯 폴더에도 들어가 쓸 수 있는 사람이 정해져 있고 이 허락을 권한이라고 부릅니다. 설치 프로그램이 홈 폴더에 파일을 넣다가 열쇠가 없으면 permission denied나 EACCES를 내고 멈춥니다. Windows는 설치 위치가 사용자 폴더 안이라 이 문제가 드뭅니다.

따라 하기
  1. 설치 중 EACCES: permission denied가 나오면 아래 두 줄로 쓰기 권한을 확인하세요. 둘 다 writable이 나오면 이 폴더들은 원인이 아닙니다. 
    test -w ~/.local/bin && echo "writable" || echo "not writable"
test -w ~/.claude && echo "writable" || echo "not writable"
  2. 관리자 권한이 필요하고 폴더 주인을 바꾸는 단계입니다. not writable이 나왔다면 아래 두 줄로 폴더를 만들고 주인을 내 계정으로 바꾼 뒤, 설치 명령을 다시 실행하세요. 
    sudo mkdir -p ~/.local/bin
sudo chown -R $(whoami) ~/.local
  3. PATH를 넣다가 zsh: permission denied: /Users/you/.zshrc가 나오면 ls -l ~/.zshrc(Bash라면 ~/.bashrc)로 파일 주인을 보세요. 출력의 세 번째 칸이 주인입니다. 이때 PATH 설정은 저장되지 않은 상태입니다.
  4. 주인이 root 같은 다른 계정이면 관리자 권한이 필요합니다. 그때는 sudo chown $(whoami) ~/.zshrc, 주인이 나라면 chmod u+w ~/.zshrc를 실행한 뒤 PATH 두 줄을 다시 입력하세요.
  5. npm으로 설치하다 권한 오류가 났다면 sudo npm install -g로 밀어붙이지 마세요. 문서는 이 방식이 권한 문제와 보안 위험을 부른다고 경고하며 기본 설치 명령으로 바꾸라고 안내합니다.
  6. Windows에서 npm 설치 뒤 running scripts is disabled on this system이 나오면 PowerShell 설치 명령으로 다시 설치하세요. PowerShell 실행 정책이 npm이 만든 .ps1 실행 스크립트를 막은 경우입니다. irm https://claude.ai/install.ps1 | iex는 이 정책에 걸리지 않습니다.

막히기 쉬운 곳

PATH를 고쳤는데 그대로 못 찾는다고 나옵니다

보이는 화면: PATH 두 줄을 넣었거나 폴더가 이미 PATH에 있는데도 command not found: claude가 다시 뜹니다.

왜 그런지: 이미 열려 있던 창은 고치기 전 PATH를 그대로 씁니다. VS Code 같은 편집기 안의 터미널은 편집기한테서 PATH를 물려받습니다.

어떻게 하는지: 새 창을 열거나 편집기를 완전히 껐다 켭니다. 그래도 안 되면 grep -n '.local/bin' ~/.zshrc로 줄이 저장됐는지 보고 echo $0으로 지금 셸이 Zsh인지 Bash인지도 확인하세요.

폴더가 원래 PATH에 있었다면 설치가 겹쳤을 수 있습니다. which -a claude(PowerShell은 where.exe claude)로 둘 이상 잡히면 기본 설치 하나만 남기고 npm으로 설치한 쪽은 npm uninstall -g @anthropic-ai/claude-code로 지우세요.

구독 중인데 organization has been disabled가 뜹니다

보이는 화면: 구독이 살아 있는데 API Error: 400과 함께 This organization has been disabled가 나옵니다.

왜 그런지: ANTHROPIC_API_KEY는 구독과 따로 발급받는 API 키를 담는 환경 변수입니다. 정기권 옆에 회사 카드를 꽂아 둔 지갑처럼, 승인해 둔 키가 있으면 Claude Code는 구독 대신 그 키를 씁니다. 예전 회사나 프로젝트의 키가 셸 설정에 남아 있을 때 흔히 생깁니다.

어떻게 하는지: macOS·Linux는 unset ANTHROPIC_API_KEY, Windows PowerShell은 Remove-Item Env:ANTHROPIC_API_KEY를 입력한 뒤 claude를 다시 실행합니다. 어떤 로그인 방식이 쓰이는지는 Claude Code 안에서 /status로 확인됩니다.

다음에도 같은 일이 없으려면 ~/.zshrc, ~/.bashrc, ~/.profile에서 export ANTHROPIC_API_KEY=로 시작하는 줄을 지우세요. Windows는 PowerShell 프로필($PROFILE)과 사용자 환경 변수에서 ANTHROPIC_API_KEY를 찾아 지웁니다.

여기서 더 나아가려면

계정이나 결제 문제라면 claude.ai에 로그인해 왼쪽 아래 이니셜을 누르고 Get help로 지원팀을 찾으세요. 설치 문제가 끝내 안 풀리면 운영체제, 실행한 설치 명령, 오류 전문을 모아 공식 GitHub 저장소에 알리면 됩니다.

이상으로 글 마치겠습니다.

출처

#Claude Code#문제 해결#오류#디버깅#설치#로그인#PATH#권한

같은 분류의 글