단계 1: 실제 오류 확인
claude --version # is the CLI there at all?
claude # start it directly: the real error prints here
claude doctor # install health check터미널에서는 정상적으로 작동하고 확장 프로그램이나 앱에서만 실패한다면, 문제는 Claude Code 자체가 아니라 래퍼를 실행하는 환경(PATH, Node 버전, 프록시 변수)에 있습니다. 터미널에서도 실패한다면 출력되는 메시지로 검색하세요.
알려진 원인(이슈 트래커 기준)
- VS Code에서 백그라운드 세션 재개. 다음으로 시작한 세션을 열면
claude --bg바로 이 오류가 발생합니다. macOS, Windows, Linux에서 보고되었습니다(#77162). 먼저 백그라운드 에이전트를 중지하거나 새 세션을 여세요. - Windows: 비정상 종료 후 남은 고아 프로세스. 이전 프로세스가 여전히 잠금을 잡고 있어 앱을 다시 실행할 수 없습니다(#42776, #53247). 남아 있는 다음 프로세스를 종료하세요:
claude작업 관리자에서 해당 프로세스를 종료하세요. 해당 보고서에서 확인된 확실한 해결 방법은 Windows를 완전히 재시작하는 것입니다. - Apple Silicon의 데스크톱 앱 CLI는 정상적으로 작동하지만 세션을 시작할 때마다 실패하는 경우(#59866, 알려진 이슈와 중복된 보고)에는 앱을 업데이트하세요. 그동안은 터미널에서 CLI를 사용하세요.
- 18 미만의 Node.js 또는 손상된 PATH npm으로 설치한 후 이런 상태라면 래퍼가 CLI를 시작할 수 없습니다.
node -v; 네이티브 설치 프로그램으로 전환하여 Node 의존성을 없애세요. - 잘못된 `~/.claude/settings.json`. hooks 또는 permissions 블록에 불필요한 쉼표가 있으면 CLI가 즉시 종료됩니다. JSON의 유효성을 검사하세요.
- Windows 셸 불일치 — 특정 모델에서 Git Bash를 통해 실행한 PowerShell 도구가 실패하는 경우(#87980)에는 다른 셸을 사용해 보세요.
위 항목 중 해당하는 것이 없다면
- 모두 업데이트하세요:
claude update, 그리고 VS Code 확장 프로그램이나 데스크톱 앱을 업데이트하세요. - 네이티브 설치 프로그램으로 재설치하세요(
curl -fsSL https://claude.ai/install.sh | bash, 또는 다음 문서에 있는 PowerShell / CMD 한 줄 명령: 설치 가이드). - 터미널에서 VS Code를 시작하여 정상 작동하는 CLI와 동일한 환경을 상속하도록 하세요.
- 다음의 출력을 첨부하여 새 이슈를 등록하세요:
claude doctor— 트래커에서는 비정상 종료 문제를 신속하게 분류합니다.
관련 항목
Claude Code가 시작된 후 API 오류로 실패한다면 별개의 문제입니다. 참고: API 오류 500, 과부하 / 529, API 오류 400 또는 OAuth 오류. 확장 프로그램에 관한 내용은 다음을 참고하세요: VS Code에서 Claude Code 사용.
이 문제와 씨름하는 데 지치셨나요?
대신 AI Prime Tech 게이트웨이를 통해 Claude Code를 실행하세요. 게이트웨이 자체 업스트림 계정에서 동일한 Claude 모델을 사용하며, 환경 변수 두 개로 전환할 수 있고, 신규 계정에는 다음이 제공됩니다: $5의 무료 API 크레딧이 제공됩니다 사용할 코드: FIXIT — 카드 불필요.
export ANTHROPIC_BASE_URL=https://aiprimetech.io
export ANTHROPIC_API_KEY=your_key자주 묻는 질문
'Claude Code 프로세스가 코드 1로 종료됨'은 무엇을 의미하나요?
VS Code 확장 프로그램이나 데스크톱 앱이 Claude Code CLI를 실행했지만 오류로 종료되었다는 뜻입니다. 터미널에서 claude를 실행하여 실제 오류 메시지를 확인하세요.
Windows에서 Claude Code가 코드 1로 종료되는 문제는 어떻게 해결하나요?
남아 있는 claude 프로세스를 종료하고(앱이 다시 실행되지 않으면 Windows를 재시작), node -v와 PATH를 확인하고, ~/.claude/settings.json의 유효성을 검사하세요. 필요하면 네이티브 설치 프로그램으로 재설치하세요.
Claude Code가 터미널에서는 작동하지만 VS Code에서는 작동하지 않는 이유는 무엇인가요?
VS Code가 다른 환경(PATH, Node, 프록시 변수)에서 시작되었기 때문입니다. claude가 정상적으로 작동하는 터미널에서 VS Code를 시작하거나 셸 프로필의 변수를 수정하세요.
게이트웨이에서 Claude Code 실행하기
동일한 모델, 환경 변수 두 개, 액면가의 7.69231배에 해당하는 크레딧 또는 정액 무제한 요금제를 이용하세요. 신규 계정: 코드 FIXIT로 $5의 무료 API 크레딧을 받으세요.
API 키 발급받기 무제한 요금제 보기AI Prime Tech는 독립 API 게이트웨이이며 Anthropic과 제휴 관계가 없고, Anthropic의 보증이나 후원을 받지 않습니다. “Claude”와 “Claude Code”는 Anthropic의 상표입니다. 여기에 설명된 Claude Code 기능은 작성 당시 Anthropic의 공개 문서를 기준으로 하며 자주 변경됩니다. 이 페이지의 가격과 모델 목록은 이 게이트웨이의 실시간 설정에서 가져옵니다.