클로드 코드 오류: 안 될 때 원인과 해결

검은 창에 영어로 된 빨간 글씨가 뜨고, 그다음부터 아무것도 진행되지 않습니다. 클로드 코드(Claude Code) 오류는 대부분 네 곳 중 한 곳에서 생깁니다. 설치 명령을 붙여 넣은 직후, 설치는 끝났는데 claude 를 입력했을 때, 로그인할 때, 그리고 잘 쓰다가 갑자기 멈출 때입니다.

어디서 막혔는지에 따라 원인도 조치도 전혀 다릅니다. 그래서 이 글은 해결책을 늘어놓지 않고, 내 오류가 어느 쪽인지 먼저 가른 뒤 그 자리에 맞는 조치만 안내합니다. 내용은 2026년 9월 18일에 공식 문서를 열어 확인한 기준이고, 예시는 Windows 중심입니다.

내 오류가 어느 단계인지 먼저 가르기

화면에 뜬 메시지를 그대로 두고 아래 네 가지 중 어느 쪽인지 보세요.

1. 설치 명령을 붙여 넣자마자 오류가 났다 → 명령을 실행한 창의 종류가 맞지 않거나, 내려받기가 막힌 경우입니다.
2. 설치는 끝났다고 나왔는데 claude 를 입력하면 “인식되지 않는다”고 한다 → 프로그램은 설치됐지만 컴퓨터가 그 위치를 모르는 상태입니다.
3. claude 는 켜지는데 로그인에서 넘어가지 않는다 → 계정, 요금제, 인증 문제입니다.
4. 쓰던 중에 API Error 나 한도 메시지가 뜬다 → 내 컴퓨터보다는 서버, 사용량, 대화 길이 쪽입니다.

설치 명령을 넣자마자 오류가 날 때

Windows에는 명령을 입력하는 창이 두 가지 있습니다. PowerShell과 명령 프롬프트(CMD)입니다. 클로드 코드 설치 명령은 창마다 다른데, 다른 창의 명령을 붙여 넣으면 이런 메시지가 나옵니다.

'irm' is not recognized as an internal or external command

CMD 창에 PowerShell용 명령을 넣었다는 뜻입니다.

The token '&&' is not a valid statement separator

반대로 PowerShell 창에 CMD용 명령을 넣었을 때 나옵니다.

A parameter cannot be found that matches parameter name 'fsSL' 또는 'bash' is not recognized as the name of a cmdlet

맥·리눅스용 명령을 Windows에 붙여 넣은 경우입니다.

내가 어느 창에 있는지는 입력 줄 맨 앞을 보면 압니다. 공식 문서 기준으로 PS C:\ 처럼 PS가 붙어 있으면 PowerShell, C:\ 만 있으면 CMD입니다. 시작 메뉴에서 PowerShell을 검색해 연 다음 아래 명령을 넣는 쪽이 가장 단순합니다. 이 명령은 클로드 코드를 내 사용자 폴더 아래에 설치하며, 공식 문서에 따르면 관리자 권한으로 실행할 필요가 없습니다.

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

같은 자리에서 나오는 다른 메시지도 몇 가지 있습니다.

Claude Code does not support 32-bit Windows — 컴퓨터가 64비트인데도 이 메시지가 나오면 시작 메뉴에서 Windows PowerShell (x86) 항목을 연 경우입니다. 그 창을 닫고 (x86)이 붙지 않은 Windows PowerShell 로 다시 여세요. 확실히 하려면 오류가 난 창에 [Environment]::Is64BitOperatingSystem 을 입력합니다. True 가 나오면 운영체제는 문제없습니다.

The process cannot access the file ... because it is being used by another process — 설치 프로그램이 내려받기 폴더에 파일을 쓰지 못한 상태입니다. 공식 문서는 이전 설치 시도가 아직 돌고 있거나 백신이 받는 중인 파일을 검사할 때 생긴다고 설명합니다. 설치를 돌리던 다른 창을 모두 닫고, 아래 두 줄을 차례로 실행하세요. 첫 줄은 설치 프로그램의 내려받기 폴더를 지웁니다. 지운 것은 되돌릴 수 없지만 둘째 줄의 설치 명령이 필요한 파일을 다시 받습니다.

Remove-Item -Recurse -Force "$env:USERPROFILE\.claude\downloads"
irm https://claude.ai/install.ps1 | iex

App unavailable in region — 클로드 코드가 지원되지 않는 국가로 인식됐다는 뜻입니다. 설치 방법을 바꿔도 해결되지 않습니다.

curl: (22) The requested URL returned error: 403 이나 HTML 코드가 섞인 긴 오류 — 설치 스크립트 대신 웹 페이지가 내려온 경우입니다. 회사 방화벽이나 프록시가 막는 경우도 있고, 일시적인 문제일 때도 있습니다. 몇 분 뒤 다시 해 보고, 그래도 같다면 winget install Anthropic.ClaudeCode 로 설치하는 방법이 공식 문서에 대안으로 나와 있습니다. 회사 PC라면 네트워크 담당자에게 downloads.claude.ai 접속이 허용돼 있는지 물어보는 편이 빠릅니다.

설치를 처음부터 차근차근 다시 하고 싶다면 클로드 코드 설치, 윈도우에서 처음 하는 사람이 막히는 것들에 전체 순서가 있습니다. 여기서는 막힌 지점만 다룹니다.

설치는 끝났는데 claude 가 인식되지 않을 때

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

둘 다 같은 뜻입니다. 프로그램은 설치됐는데, 컴퓨터가 claude 라는 이름을 들었을 때 어느 폴더를 찾아봐야 하는지 모르는 상태입니다. 컴퓨터가 명령을 찾아보는 폴더 목록을 PATH라고 부르는데, 클로드 코드가 설치된 폴더가 그 목록에 빠져 있는 것입니다.

가장 먼저 할 일은 창을 닫고 새로 여는 것입니다. 설치를 실행했던 창은 설치 전의 폴더 목록을 그대로 들고 있어서, 새 창에서는 바로 되는 경우가 있습니다.

새 창에서도 같다면 PowerShell에서 아래 명령으로 확인합니다. 읽기만 하는 명령입니다.

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

아무것도 출력되지 않으면 목록에 빠져 있는 것이 맞습니다. 아래 두 줄이 공식 문서가 안내하는 추가 방법입니다. 내 Windows 사용자 계정의 PATH 목록 맨 뒤에 설치 폴더(%USERPROFILE%\.local\bin)를 한 줄 덧붙일 뿐, 기존 항목은 건드리지 않습니다. 되돌리고 싶으면 Windows의 환경 변수 설정 화면에서 사용자 PATH에 추가된 그 항목을 지우면 됩니다.

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

실행한 뒤에는 창을 닫고 새로 열어야 적용됩니다.

확인 명령에서 결과가 나왔는데도 안 된다면 두 가지를 더 봅니다. 하나는 VS Code 확장 프로그램만 설치한 경우입니다. 공식 문서에 따르면 확장은 자기 안에서만 쓰는 사본을 갖고 있을 뿐 터미널용 claude 를 설치하지 않습니다. 이때는 위의 설치 명령으로 따로 설치해야 합니다. 다른 하나는 claude 를 입력했더니 오류 대신 Claude 데스크톱 앱이 열리는 경우입니다. 오래된 버전의 데스크톱 앱이 같은 이름을 먼저 차지해서 생기는 일로, 공식 문서의 해결책은 데스크톱 앱을 최신 버전으로 업데이트하는 것입니다.

로그인에서 막힐 때

로그인 문제는 컴퓨터 설정보다 계정 쪽 원인이 많습니다. 그래서 요금제부터 확인합니다.

요금제가 맞는데도 안 된다면, 원인이 분명하지 않은 로그인 실패 대부분에 공식 문서가 권하는 방법은 로그인을 새로 하는 것입니다. 클로드 코드 안에서 /logout 을 입력해 완전히 로그아웃하고, 클로드 코드를 닫은 다음, claude 로 다시 켜서 로그인 과정을 처음부터 진행합니다. 저장된 로그인 정보만 지워지고, 다시 로그인하면 원래대로 돌아옵니다.

브라우저가 자동으로 열리지 않으면 로그인 안내가 떠 있는 상태에서 키보드 c 를 누르세요. 로그인 주소가 복사됩니다. 브라우저 주소창에 붙여 넣으면 됩니다.

메시지별로는 이렇습니다.

OAuth error: Invalid code. Please make sure the full code was copied — 로그인 코드가 시간이 지나 만료됐거나, 복사할 때 일부가 잘린 경우입니다. Enter를 눌러 다시 시도하고, 브라우저가 열리면 지체하지 말고 마치세요.

API Error: 403 {"error":{"type":"forbidden","message":"Request not allowed"}} — 로그인은 됐는데 사용 권한이 없다는 뜻입니다. Pro·Max 사용자라면 claude.ai/settings 에서 구독이 살아 있는지 확인합니다. 회사 네트워크라면 프록시가 요청을 막는 경우도 있습니다.

This organization has been disabled — 구독이 멀쩡한데 이 메시지가 나오면 원인이 꽤 구체적입니다. 컴퓨터에 ANTHROPIC_API_KEY 라는 값이 예전에 저장돼 있어서, 클로드 코드가 내 구독 대신 그 오래된 키로 접속하려는 상황입니다. 이전 직장이나 예전 프로젝트에서 넣어 둔 키가 남아 있을 때 흔하다고 공식 문서는 설명합니다. PowerShell에서 Remove-Item Env:ANTHROPIC_API_KEY 를 실행한 뒤 claude 를 다시 켜 보세요. 이 명령은 지금 열린 창에서만 그 값을 지웁니다. 효과가 있으면 Windows의 사용자 환경 변수에서도 같은 이름의 항목을 찾아 지워야 다음에도 유지됩니다. 어떤 방식으로 인증돼 있는지는 클로드 코드 안에서 /status 로 확인합니다.

며칠 잘 쓰다가 다시 로그인하라고 나오는 것은 인증이 만료된 것이고, /login 으로 해결됩니다. 자주 반복된다면 컴퓨터 시계가 맞는지 확인하라고 공식 문서는 안내합니다. 인증 확인이 시각에 의존하기 때문입니다.

잘 쓰다가 오류 메시지가 뜰 때

이 구간의 오류는 재설치로 고쳐지지 않는 것이 많습니다. 메시지가 어느 쪽 문제를 말하는지부터 봅니다.

API Error: 500 Internal server error, API Error: Repeated 529 Overloaded errors — 공식 오류 안내(Error reference)에서 서버 오류로 분류된 메시지입니다. 내 설치 상태와는 관계가 없다는 뜻이므로 프로그램을 지우고 다시 까는 것부터 하지는 마세요. 서비스 장애 여부는 status.claude.com 에서 확인됩니다. 이 메시지들의 세부 조치는 공식 오류 안내의 해당 항목에 있는데, 이 글을 쓰는 시점에 그 항목 본문까지는 직접 확인하지 못했습니다.

You've hit your session limit, You've hit your weekly limit — 공식 오류 안내에서 사용량 한도로 분류된 메시지입니다. 요금제에 포함된 사용량을 다 썼다는 뜻입니다. Claude 도움말 센터는 한도 도달 메시지에 표시된 재설정 시각까지 기다리라고 안내하고, 클로드 코드에서는 /model 로 더 가벼운 모델로 바꿔 계속 쓰는 방법도 소개합니다. 한도의 구체적인 크기는 요금제마다 다르고 바뀔 수 있어 여기에 숫자로 적지 않습니다.

Context limit reached · /compact or /clear to continue — 대화가 너무 길어져 한 번에 기억할 수 있는 양을 넘겼다는 뜻입니다. 해결 방법이 메시지에 이미 들어 있습니다. /compact 는 지금까지의 대화를 요약해 줄이고, /clear 는 대화를 비우고 새로 시작합니다. /clear 뒤에는 앞의 대화 맥락이 사라지니, 이어서 할 작업이면 /compact 를 먼저 쓰세요.

Not logged in · Please run /login — 말 그대로입니다. /login 을 입력합니다.

메시지 없이 화면이 멈춘 경우에는 Ctrl+C로 현재 작업을 취소해 봅니다. 반응이 없으면 터미널 창을 닫고 다시 여는 수밖에 없는데, 공식 문서에 따르면 그래도 대화는 사라지지 않습니다. 같은 폴더에서 claude --resume 을 실행하면 하던 세션을 이어 갑니다.

클로드 코워크 설치 오류는 원인이 다릅니다

지식iN에 올라온 「클로드 코워크 설치 오류?」 같은 질문은 클로드 코드와 다른 제품 이야기입니다. 코워크(Cowork)는 공식 도움말 표현으로 “클로드 코드와 같은 구조를 쓰되 터미널이 필요 없는” 기능이고, Claude 데스크톱 앱 안에서 돌아갑니다. 유료 플랜(Pro, Max, Team, Enterprise)에서 제공됩니다. 그래서 위에서 다룬 PATH나 설치 명령 문제는 코워크와 관계가 없습니다.

코워크가 Windows에서 설치되지 않거나 켜지지 않을 때, 공식 자료로 확인되는 원인은 세 가지입니다.

첫째, 컴퓨터 여유 공간입니다. 코워크는 내 컴퓨터 안에 격리된 가상 컴퓨터(가상 머신)를 만들어 그 안에서 작업합니다. 설치 안내 문서는 여유 디스크 약 25GB와 메모리 8GB를 요구 사항으로 적고 있습니다.

둘째, 관리자 권한입니다. 공식 배포 안내에 따르면 코워크까지 포함한 전체 기능을 설치하려면 관리자 권한이 필요하고, 권한 없이 설치하면 앱은 깔리지만 데스크톱의 코워크는 쓸 수 없습니다. 회사에서 받은 PC에서 자주 걸리는 지점입니다.

셋째, Windows의 가상화 기능입니다. 코워크를 켤 때 아래 메시지가 나오는 경우입니다.

Missing HCS services: HNS, vmcompute, vfpext

가상 머신을 돌리는 Windows 구성 요소(Virtual Machine Platform)가 이 컴퓨터에 등록돼 있지 않다는 뜻입니다.

세 가지 어디에도 해당하지 않는 코워크 오류는 이 글의 범위 밖입니다. 오류 문구를 그대로 복사해 Claude 고객 지원에 문의하는 편이 빠릅니다. 문의 경로는 글 끝에 있습니다.

클로드가 틀린 답을 하는 것은 오류일까요

「클로드 AI의 오류, 왜곡, 문제점, 한계점들은?」 이라는 질문은 프로그램이 멈추는 오류가 아니라, 클로드가 내놓은 답이 틀린 경우를 묻습니다. 둘은 성격이 다릅니다. 앞의 것은 고치면 없어지고, 뒤의 것은 지금의 AI가 가진 한계라서 사용하는 쪽에서 관리해야 합니다.

Anthropic 공식 도움말은 이 점을 숨기지 않습니다. 클로드가 때때로 틀리거나 오해를 부르는 답을 내놓으며, 이는 현재 생성형 AI의 한계에서 나오는 부산물이라고 적고 있습니다. 학습 시점 이후의 일을 모르거나, 그럴듯해 보이지만 실제로는 없는 인용문을 만들어 내는 경우를 예로 듭니다.

그래서 사용자가 할 일도 도움말에 나와 있습니다. 클로드를 유일한 정보 출처로 삼지 말 것, 결과가 중요한 조언은 꼼꼼히 따져 볼 것, 웹 검색을 쓴 답이라면 클로드가 인용한 원문을 직접 열어 볼 것입니다. 엉뚱한 답에는 엄지 아래 버튼을 눌러 알릴 수 있습니다.

클로드 코드에서도 같은 원칙이 통합니다. 클로드 코드가 “이 오류는 이렇게 고치면 됩니다”라며 제안하는 명령이나 파일 수정도 틀릴 수 있습니다. 무엇을 바꾸는 작업인지 읽어 보고 승인하고, 이해되지 않으면 “이 명령이 무엇을 바꾸는지, 되돌릴 수 있는지 설명해 주세요”라고 먼저 물어보세요.

오류를 줄이려면 무엇을 고르면 좋을까요

같은 클로드 코드라도 설치 방법과 실행 환경에 따라 만나는 오류가 달라집니다. 공식 문서에 나온 차이를 기준으로 정리하면 이렇습니다.

설치 방법은 공식 설치 명령(네이티브 설치)을 권합니다. 공식 문서가 권장 방식으로 표시해 두었고, 백그라운드에서 자동으로 업데이트된다는 점이 근거입니다. WinGet 설치는 간단하지만 자동 업데이트가 되지 않아 winget upgrade Anthropic.ClaudeCode 를 직접 실행해야 합니다. npm 설치는 Node.js 22 이상이 필요하고(v2.1.198부터), Windows에서는 running scripts is disabled on this system 같은 실행 정책 오류를 추가로 만날 수 있습니다. 이미 npm을 쓰는 개발자가 아니라면 고를 이유가 적습니다.

검은 창 자체가 부담스럽다면 Claude 데스크톱 앱을 고려해 보세요. 공식 문서는 터미널 없이 클로드 코드를 쓰는 방법으로 데스크톱 앱을 안내합니다. PATH나 명령 창 구분 같은 문제를 아예 만나지 않게 됩니다. 다만 앞에서 본 것처럼 코워크 기능은 컴퓨터 사양과 권한 조건이 따로 있습니다.

Windows에서 그냥 쓸지, WSL(Windows 안에서 리눅스를 돌리는 기능)에서 쓸지 고민이라면 처음에는 그냥 Windows에서 쓰는 쪽이 단순합니다. 공식 문서 기준으로 추가로 필요한 것이 없고, Git for Windows도 선택 사항입니다. WSL은 리눅스 개발 도구를 쓰거나, 명령을 격리해 실행하는 샌드박스 기능이 필요한 경우에 고르는 선택지입니다. WSL에서는 로그인할 때 브라우저가 자동으로 돌아오지 않아 코드를 직접 붙여 넣어야 하는 등 챙길 것이 조금 더 있습니다.

고쳐졌는지 확인하고 첫 요청까지 가 보기

조치를 했다면 새 PowerShell 창을 열고 다음 순서로 확인합니다.

1. claude --version 을 입력합니다. 정상이면 2.1.211 (Claude Code) 같은 형태로 버전 번호가 한 줄 나옵니다. 숫자는 시점마다 다릅니다. 이 한 줄이 나오면 설치와 PATH 문제는 끝난 것입니다.
2. claude doctor 를 입력합니다. 경고 항목이 있으면 권장 조치와 함께 표시됩니다.
3. 작업할 폴더로 이동합니다. 예를 들어 바탕 화면에 만든 연습용 폴더라면 cd Desktop\연습폴더 처럼 입력합니다.
4. claude 를 입력합니다. 처음이면 브라우저가 열리고 로그인 안내가 나옵니다. 안내대로 마치면 터미널 안에서 대화형 화면이 열립니다.
5. 가벼운 요청을 하나 입력해 봅니다. 예를 들면 “이 폴더에 어떤 파일이 있는지 알려 주세요” 정도면 충분합니다. 답이 돌아오면 설치, 로그인, 서버 연결이 모두 정상입니다.

5번에서 오류가 난다면 그때 뜬 메시지를 위의 「잘 쓰다가 오류 메시지가 뜰 때」 항목과 맞춰 보세요.

그래도 안 될 때

오류를 넘기고 첫 요청까지 성공했다면, 다음은 실제 일을 맡겨 볼 차례입니다. 클로드 코드 자동화, 초보자도 할 수 있을까?에서 처음 맡겨 보기 좋은 작업과 준비물을 이어서 볼 수 있습니다.