Claude Code 설치 · 로그인 · 멈춤 문제 해결 — 오류 문구로 원인 찾는 순서

KAITABASE가 공식 문서와 원문을 직접 읽고 새로 쓴 가이드입니다.

이 가이드로 할 수 있는 것

Claude Code 공식 문서는 문제를 두 갈래로 나눕니다. 설치 · 로그인 단계에서 막히는 문제는 Troubleshoot installation and login 문서가, 설치된 뒤 느려지거나 멈추는 문제는 Troubleshooting 문서가 다룹니다. 두 문서 모두 "보이는 오류 문구 → 해결 절" 표로 시작합니다.

이 가이드는 그 표를 우리 말로 옮기고, 가장 자주 만나는 경우를 순서대로 묶었습니다. 끝까지 따라 하면 다음을 할 수 있습니다.

1. 내 PC에 Claude Code가 어디에, 몇 개 설치돼 있는지 확인합니다.
2. command not found · 설치 스크립트 오류 · 프록시 · 인증서 문제를 오류 문구로 구분해 고칩니다.
3. 로그인 실패 · 403 · "organization disabled" 를 원인별로 처리합니다.
4. 세션이 멈추거나 메모리를 많이 쓸 때 대화를 잃지 않고 다시 시작합니다.

빠른 시작

어떤 문제든 먼저 아래 세 줄로 현재 상태를 봅니다. Windows PowerShell 기준입니다.

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

2026-10-22에 직접 실행한 결과입니다.

12342.1.307 (Claude Code)
C:\Users\PCuser\AppData\Roaming\npm\claude
C:\Users\PCuser\AppData\Roaming\npm\claude.cmd
HTTP/1.1 200 OK

버전이 나오면 설치는 된 것이고, where.exe 는 어떤 경로의 claude 가 불리는지 보여 줍니다. 마지막 줄이 200 이면 다운로드 서버에 닿습니다. 세션이 열리는데 무엇이 문제인지 모르겠다면 세션 안에서 /doctor 를, claude 가 아예 안 열리면 셸에서 claude doctor 를 실행하라고 공식 문서는 안내합니다(공식 문서 기준, 직접 실행 안 함).

STEP 1. 어디에 설치돼 있는지 확인하기

목표: 설치 방식과 설치 개수를 알아 둡니다. · 예상 시간: 3분

공식 문서가 권하는 설치 방식은 네이티브 설치이며, 위치는 다음과 같습니다.

PowerShell에서 네이티브 설치가 있는지 봅니다.

Test-Path "$env:USERPROFILE\.local\bin\claude.exe"
where.exe claude

macOS · Linux에서는 which -a claude 로 PATH에 있는 claude 를 모두 봅니다.

확인 직접 실행한 PC에서는 Test-Path 가 False, where.exe 가 AppData\Roaming\npm\claude 를 가리켰습니다. 네이티브 설치가 아니라 npm 전역 설치였다는 뜻입니다. 이런 경우 문서의 네이티브 경로 안내가 그대로 맞지 않으므로, 먼저 내 설치 방식을 확인하는 것이 중요합니다.

막히면 공식 문서는 설치가 여러 개면 버전이 엇갈리거나 예상과 다르게 동작할 수 있으니 하나만 남기라고 합니다. 권장은 네이티브 설치이고, 나머지는 npm uninstall -g @anthropic-ai/claude-code(npm), brew uninstall --cask claude-code(Homebrew), winget uninstall Anthropic.ClaudeCode(WinGet)로 지웁니다.

STEP 2. "command not found" 고치기

목표: 설치는 됐는데 claude 를 못 찾는 문제를 PATH로 해결합니다. · 예상 시간: 5분

플랫폼별 오류 문구는 다음과 같습니다.

설치 프로그램은 이 경우를 알아채고 Setup notes: 아래에 Native installation exists but ... is not in your PATH. 를 출력합니다. 다만 PATH를 직접 바꾸지는 않습니다.

PowerShell에서 PATH에 설치 폴더가 있는지 봅니다.

$env:PATH -split ';' | Select-String '\.local\\bin'

출력이 없으면 공식 문서의 명령으로 사용자 PATH에 추가합니다(공식 문서 기준, 직접 실행 안 함 — 사용자 환경 변수를 영구히 바꾸기 때문입니다).

$currentPath = [Environment]::GetEnvironmentVariable('PATH', 'User')
[Environment]::SetEnvironmentVariable('PATH', "$currentPath;$env:USERPROFILE\.local\bin", 'User')

macOS의 zsh라면 다음 두 줄입니다.

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

확인 새 터미널을 열고 claude --version 을 실행해 2.1.307 (Claude Code) 처럼 버전이 나오면 끝입니다.

막히면 이미 열려 있던 창은 예전 PATH를 그대로 씁니다. VS Code 같은 편집기 안의 터미널은 편집기의 PATH를 물려받으므로 편집기를 완전히 껐다 켭니다. Windows에서 업데이트 직후 갑자기 못 찾는다면 %USERPROFILE%\.local\bin 에 claude.exe.old.<숫자> 백업만 남은 경우일 수 있습니다. 공식 문서는 가장 최근 백업의 이름을 claude.exe 로 되돌리거나 다시 설치하라고 안내합니다.

되돌리기 PATH에 넣은 줄이 잘못됐다면 ~/.zshrc 에서 그 줄을 지우거나, Windows는 시스템 설정의 환경 변수 화면에서 사용자 PATH의 해당 항목을 지웁니다.

STEP 3. 설치 명령 자체가 실패할 때

목표: 셸에 맞지 않는 명령, HTML이 돌아오는 경우를 구분합니다. · 예상 시간: 4분

가장 흔한 원인은 다른 셸용 설치 명령을 붙여 넣은 경우입니다.

CMD에 머물고 싶다면 공식 문서의 CMD용 명령을 씁니다.

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

syntax error near unexpected token '<', < was unexpected at this time, System.Xml.XmlDocument 같은 오류는 설치 주소가 스크립트 대신 웹 페이지를 돌려줬다는 뜻입니다. 오류에 App unavailable in region 이 보이면 지원 국가가 아닌 경우이고, 그 밖에는 몇 분 뒤 다시 하거나 Homebrew(brew install --cask claude-code) · WinGet(winget install Anthropic.ClaudeCode) 설치를 써 봅니다.

확인 어떤 설치 방식이든 새 터미널에서 claude --version 이 버전 번호를 출력하면 성공입니다.

주의 Homebrew · WinGet 설치는 기본적으로 스스로 업데이트하지 않습니다. 공식 문서는 Homebrew의 claude-code 캐스크가 stable 채널을 따라 보통 최신 릴리스보다 일주일쯤 늦다고 설명합니다.

STEP 4. 회사 네트워크 · 프록시 · 인증서

목표: 사내망에서 다운로드가 막히는 원인을 찾습니다. · 예상 시간: 5분

설치 프로그램은 downloads.claude.ai 에서 내려받습니다. 빠른 시작의 curl.exe -sI 결과로 원인을 나눕니다.

PowerShell에서는 curl 이 Invoke-WebRequest 의 별칭이라 -sI 를 받지 않으므로 꼭 curl.exe 로 부릅니다. 회사 프록시 뒤라면 설치 전에 프록시 주소를 넣습니다(주소는 IT팀에 확인).

$env:HTTP_PROXY = 'http://proxy.example.com:8080'
$env:HTTPS_PROXY = 'http://proxy.example.com:8080'
irm https://claude.ai/install.ps1 | iex

TLS 검사를 하는 사내 프록시 때문에 unable to get local issuer certificate, SELF_SIGNED_CERT_IN_CHAIN 이 나오면, 설치된 Claude Code가 회사 인증서를 믿도록 NODE_EXTRA_CA_CERTS 에 인증서 파일 경로를 넣습니다. Windows PowerShell 5.1에서 TLS 채널 오류가 나면 같은 창에서 TLS 1.2를 켜고 설치를 다시 실행합니다.

[Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12

막히면 CRYPT_E_NO_REVOCATION_CHECK · CRYPT_E_REVOCATION_OFFLINE 은 인증서 폐기 확인이 막힌 경우입니다. CMD 설치 명령의 curl 에 --ssl-revoke-best-effort 를 붙이거나, .NET으로 내려받는 PowerShell 설치 프로그램 또는 winget 을 씁니다. 업데이트 중 The connection dropped while downloading the update 가 나오면 claude update 를 다시 실행하고, 계속되면 네트워크팀에 downloads.claude.ai 전체 다운로드 허용을 요청합니다.

STEP 5. 로그인 · 403 · organization disabled

목표: 로그인 문제를 원인별로 나눠 처리합니다. · 예상 시간: 4분

원인이 분명하지 않으면 공식 문서는 다음 세 단계로 로그인을 초기화하라고 합니다(공식 문서 기준, 직접 실행 안 함).

1. 세션에서 /logout
2. Claude Code 종료
3. claude 로 다시 시작해 인증

브라우저가 자동으로 안 열리면 c 를 눌러 로그인 주소를 복사해 직접 엽니다. WSL2 · SSH · 컨테이너에서는 브라우저가 다른 컴퓨터에서 열리므로, 로그인 뒤 브라우저에 뜨는 코드를 터미널의 Paste code here if prompted 에 붙여 넣습니다. 붙여 넣기가 안 되면 claude auth login 을 씁니다.

ANTHROPIC_API_KEY 가 남아 있으면 PowerShell에서 지우고 다시 시작합니다. 영구히 지우려면 $PROFILE 과 사용자 환경 변수에서도 지웁니다.

Remove-Item Env:ANTHROPIC_API_KEY
claude

확인 세션 안에서 /status 를 실행하면 지금 어떤 인증 방식이 쓰이는지 볼 수 있습니다.

막히면 로그인을 자주 다시 하라고 하면 시스템 시계가 맞는지 봅니다. 공식 문서는 토큰 검증이 정확한 시각에 의존한다고 설명합니다.

STEP 6. 세션이 멈추거나 느릴 때

목표: 대화를 잃지 않고 멈춤 · 메모리 문제에서 빠져나옵니다. · 예상 시간: 4분

응답이 없으면 먼저 Ctrl+C 로 현재 작업을 취소하고, 그래도 안 되면 터미널을 닫고 다시 엽니다. 공식 문서는 다시 시작해도 대화가 사라지지 않는다고 밝힙니다. 같은 폴더에서 다음을 실행하면 이어집니다.

claude --resume

CPU · 메모리를 많이 쓸 때 공식 문서의 순서는 다음과 같습니다.

1. /compact 로 맥락을 줄입니다.
2. 큰 작업 사이에 Claude Code를 껐다 켭니다.
3. 큰 빌드 폴더를 .gitignore 에 넣습니다.
4. claude --safe-mode 로 다시 시작해 플러그인 · MCP 서버 · 훅이 원인인지 봅니다. 모든 사용자 설정을 끈 상태로 시작합니다.

세션 힙 메모리가 2.5GB를 넘으면 경고가 뜹니다. 이때는 재시작 후 claude --continue 로 새 프로세스에서 대화를 이어 갑니다.

확인 --safe-mode 에서 사용량이 줄면, 원인은 내가 켠 플러그인 · MCP 서버 · 훅 중 하나입니다. 하나씩 켜 보며 찾습니다.

주의 메모리 진단용 /heapdump 가 만드는 .heapsnapshot 파일에는 대화 전체와 자격 증명까지 들어갑니다. 공식 문서는 이 파일을 공개 이슈에 올리지 말고, 신고할 때는 -diagnostics.json 파일만 붙이라고 경고합니다.

막히면 Autocompact is thrashing 오류는 압축 직후 큰 파일이나 도구 출력이 맥락을 다시 채운 경우입니다. 큰 파일은 줄 범위를 나눠 읽게 하고, /compact keep only the plan and the diff 처럼 초점을 줘서 압축하거나, 서브에이전트에 맡깁니다. 검색 · @파일 이 파일을 못 찾으면 내장 ripgrep 문제일 수 있으니 시스템 ripgrep을 설치하고 USE_BUILTIN_RIPGREP 을 0 으로 둡니다.

잘못 쓰는 예 · 바르게 쓰는 예

바로 쓰는 프롬프트 · 템플릿

사내 지원 요청이나 GitHub 이슈에 붙일 정보 모음입니다. 공식 문서는 운영체제, 실행한 설치 명령, 오류 출력 전체를 함께 적으라고 합니다.

12345678[Claude Code 설치 문제 보고]
- 운영체제 · 셸: Windows 11 · PowerShell 5.1
- claude --version 결과:
- where.exe claude(또는 which -a claude) 결과:
- curl.exe -sI https://downloads.claude.ai/claude-code-releases/latest 첫 줄:
- 실행한 설치 명령:
- 오류 출력 전체(잘라 내지 않고):
- 프록시 · 사내 인증서 사용 여부:

세션은 열리는데 원인을 모를 때 Claude Code에 이렇게 묻습니다.

/doctor 결과를 보고, 지금 설치 · 설정에서 문제가 되는 항목을 중요한 순서로 3개만 짚어 주세요.
고칠 수 있는 것이 있으면 무엇을 바꾸는지 먼저 보여 주고, 제가 확인한 뒤에 적용해 주세요.

주의할 점

• 권한: PATH 변경, Set-ExecutionPolicy, sudo chown 같은 명령은 내 계정 설정을 영구히 바꿉니다. 회사 PC라면 IT 정책을 먼저 확인합니다. 이 가이드에서도 이 명령들은 실행하지 않았습니다.
• 보안: /heapdump 의 .heapsnapshot, macOS에서 키체인 대신 쓰일 수 있는 ~/.claude/.credentials.json 에는 자격 증명이 들어갑니다. 공유하지 않습니다.
• 요금: 설치 자체는 비용이 없습니다. 쓰려면 Claude 구독이나 API 키가 필요하며, 요금은 claude.com/pricing에서 확인합니다.
• 지원 범위: 계정 · 결제 · 구독 문제는 설치 문서가 아니라 Anthropic 지원(claude.ai에서 이니셜 → Get help)으로 문의하라고 공식 문서는 안내합니다.
• 라이선스: 이 가이드는 Anthropic 공식 문서를 우리 말로 다시 정리한 것입니다.

공식 자료

• Troubleshoot installation and login — https://code.claude.com/docs/en/troubleshoot-install
• Troubleshooting(성능 · 멈춤 · 검색) — https://code.claude.com/docs/en/troubleshooting
• Set up Claude Code(설치 방법 · 시스템 요구 사항) — https://code.claude.com/docs/en/setup
• Error reference — https://code.claude.com/docs/en/errors
• Network configuration(프록시 · 인증서) — https://code.claude.com/docs/en/network-config
• How to get support — https://support.claude.com/en/articles/9015913-how-to-get-support

더 보기

이 가이드는 KAITABASE가 공식 문서와 원문을 직접 읽고 실행해 본 뒤 새로 쓴 자료입니다. 같은 주제의 다른 글은 KAITABASE에서 이어서 볼 수 있습니다.

• AI 코딩 자료 모음 — https://kaitabase.vercel.app/?area=coding
• KAITABASE 전체 자료 — https://kaitabase.vercel.app