Claude Code가 프로세스의 code 1 종료를 표시하면 바로 재설치하거나 전체 캐시를 지우지 마세요. 이 문구는 Claude Code가 실행한 프로세스가 일반 실패 코드로 종료됐다는 뜻일 뿐입니다. 실제 소유자는 일반 터미널, VS Code/Cursor, Claude Desktop/Cowork, GitHub Action, wrapper, API key/auth, PATH, 이전 세션, 버전 업데이트, 서비스 상태 중 하나일 수 있습니다.
먼저 실행 경로로 분기하기
한국어 공개 사례는 API key 누락, 잘못된 자격 증명, Node 환경, VSCode 설치 오류, GitHub Action 설정, hooks 문서까지 함께 보여 줍니다. 그래서 이 문제는 하나의 해결책으로 밀어붙이면 안 됩니다. 먼저 어디서 실패했는지 고정해야 합니다.
| 보이는 조건 | 첫 분기 | 가장 안전한 첫 조치 | 같은 경로 검증 | 에스컬레이션 시점 |
|---|---|---|---|---|
| 일반 터미널에서 바로 실패 | 터미널 또는 설치 | 새 shell에서 같은 폴더로 들어가 claude doctor | 같은 명령 재실행 | 새 shell에서도 같은 실패 |
| VS Code, Cursor, IDE 안에서만 실패 | IDE 하위 프로세스 | 시스템 터미널에서 같은 명령 실행 | IDE와 raw terminal 비교 | 터미널은 정상, IDE는 실패 |
| 로그인, 계정 전환, API key 변경 뒤 실패 | 인증 또는 세션 | /status 확인 후 해당 경로만 재인증 | 같은 login path 재실행 | 상태 정상인데 경로는 실패 |
| Windows/PATH/Git/shell 문제가 보임 | PATH와 설치 | where claude, Git, PATH 확인 | 새 터미널에서 binary 확인 | 전제 조건은 통과, 실행은 실패 |
| npm script, hook, CI, alias로 실패 | wrapper 또는 script | wrapper를 우회하고 직접 claude 실행 | 한 층씩 다시 추가 | direct path 정상, wrapper에서 재발 |
| 특정 이전 세션이나 프로젝트만 실패 | 세션 상태 | 새 최소 세션 또는 임시 폴더 생성 | 작은 동일 작업 실행 | 새 세션도 같은 실패 |
| 업데이트 직후 또는 장애 중에 동시 발생 | 버전 또는 상태 | version과 status 확인 시각 기록 | 상태/버전 변화 뒤 같은 경로 재검증 | 증거 패킷이 준비됨 |
핵심은 한 번에 하나만 바꾸는 것입니다. 재설치, 설정 삭제, token 교체, PATH 수정, 확장 비활성화를 동시에 하면 운 좋게 해결돼도 원인을 잃습니다. 해결 완료 기준은 다른 경로가 되는 것이 아니라, 원래 실패하던 같은 경로가 최소 변경 후 성공하는 것입니다.
이 오류가 실제로 의미하는 것
이 code 1 표시는 프로세스가 일반 실패 코드로 종료됐다는 뜻입니다. API 요청 전에 끝났을 수도 있고, IDE가 띄운 subprocess, hook, 설정 읽기, auth refresh, wrapper timeout, live incident, 오래된 세션 내부에서 실패했을 수도 있습니다.
따라서 "API key를 설정하면 된다"나 "재설치하면 된다"는 답은 한 분기에는 맞을 수 있지만 전체 답은 아닙니다. 한국어 사례에서 API key와 VSCode 오류가 강하게 보이는 이유는 실제 사례가 있기 때문이지만, 그 문구만 보고 모든 사용자를 auth branch로 보내면 IDE나 wrapper 문제를 놓칩니다.
실무 규칙은 단순합니다. 실행 경로를 유지합니다. 한 변수만 변경합니다. 변경 뒤 같은 경로로 확인합니다. 같은 경로가 계속 실패하면 다음 분기로 이동하기 전에 증거를 남깁니다. 이 방식은 시간이 조금 더 걸려도 팀 전체가 재현 가능한 복구 절차를 얻습니다.
상태, 인증, API key, 로그인
API key 누락, 잘못된 자격 증명, OAuth, 계정 전환, subscription/API route 전환, SSO, 서비스 상태 문제가 의심될 때 이 분기를 봅니다. 다만 status와 auth는 다릅니다. 서비스 장애라면 로컬 상태를 계속 바꾸는 것이 아니라 같은 경로를 보존해야 하고, auth 문제라면 활성 경로를 확인해야 합니다.
먼저 Anthropic status를 보고 확인 시각을 기록합니다. Claude Code가 slash command를 받을 수 있으면 /status로 현재 route와 account를 확인합니다. API key나 OAuth가 의심되면 해당 경로만 갱신합니다. 모든 token을 바꾸거나 전체 ~/.claude를 지우는 것은 마지막 단계에 가깝습니다.
로그가 HTTP 500, request id, server error로 좁혀지면 Claude Code API Error 500 가이드로 이동하세요. subscription과 API key billing route가 헷갈린다면 Claude Code API key vs subscription 가이드를 보세요. usage window나 explicit limit가 보이면 rate limit 문제입니다.
Windows, PATH, 설치
설치 분기는 command not found, 잘못된 binary, missing Git, shell 불일치, permission error, first-run setup failure가 보일 때만 첫 후보입니다. code 1 문구만으로 설치가 깨졌다고 판단하면, 정상인 binary를 불필요하게 바꿀 수 있습니다.
macOS/Linux에서는 claude --version, which claude, claude doctor를 확인합니다. Windows에서는 where claude, git --version, PowerShell/WSL, PATH 순서를 확인합니다. 새 터미널에서 version조차 나오지 않으면 설치 분기입니다. version이 나오지만 IDE나 특정 프로젝트에서만 실패하면 IDE, 환경, 세션, wrapper 분기로 넘어가야 합니다.
아직 설치 전제 조건을 확인하지 않았다면 Claude Code 설치 가이드가 더 가까운 문서입니다. 여기서는 설치된 Claude Code가 특정 실행 경로에서 code 1로 종료되는 상황을 다룹니다.
IDE, 환경 변수, 세션
VS Code와 Cursor는 단순한 터미널 창이 아닙니다. 확장 로그, 통합 터미널 shell, working directory, workspace settings, task/launch config, debugger auto-attach, injected environment variables가 시스템 터미널과 다를 수 있습니다. 공개 issue에서도 IDE가 subprocess 환경에 영향을 준 사례가 있었습니다.
먼저 시스템 터미널에서 같은 프로젝트 폴더로 들어가 pwd, claude --version, 최소 claude 실행을 확인합니다. 그 다음 IDE 안에서 같은 directory와 같은 command를 실행합니다. 시스템 터미널은 정상인데 IDE만 실패하면, extension output, integrated shell, workspace settings, debugger auto-attach, task config, PATH/proxy/token 차이를 확인합니다.
두 경로가 모두 실패하면 환경과 세션을 봅니다. PATH, proxy, token/auth variables, shell startup, Node shim, corporate network처럼 실행에 영향을 주는 항목만 확인합니다. secrets를 로그에 출력하거나 삭제하지 마세요. 세션은 별도입니다. 새 임시 폴더 또는 최소 세션으로 작은 작업을 실행합니다. 새 세션이 성공하면 이전 workspace나 conversation state가 원인 일부입니다.
Hooks, wrapper, GitHub Action
npm script, alias, shell function, pre-commit hook, CI step, GitHub Action, 내부 task runner는 외부 계층입니다. 이 계층이 code 1을 반환해도 최종 메시지는 Claude Code process exit처럼 보일 수 있습니다.
직접 claude를 실행해 보세요. 직접 실행이 정상이라면 alias, npm script, hook, CI, timeout wrapper를 한 층씩 다시 붙입니다. 오류를 처음 되살리는 층이 첫 수정 대상입니다. 그 층의 exit code, permission, working directory, environment, timeout, stderr 처리, secret 주입 여부를 확인합니다.
direct path가 정상인데 Claude Code를 재설치하는 것은 이미 동작하는 층을 바꾸는 일입니다. GitHub Action에서는 secret 이름, job 권한, checkout 위치, non-interactive shell, timeout이 특히 자주 문제를 만듭니다. wrapper의 실패를 Claude Code 본체 실패로 오해하지 않는 것이 중요합니다.
업데이트 회귀 또는 실시간 장애
업데이트 직후 시작됐거나 같은 시간대에 GitHub, Reddit, 커뮤니티에서 같은 문구가 늘었다면 버전/상태 분기를 유지합니다. 하지만 오래된 게시글은 현재 증거가 아닙니다.
claude --version, 설치 경로, OS, shell, IDE extension version, 시스템 터미널 재현 여부, Anthropic status 확인 시각, 직전 변경 사항을 기록합니다. 상태 페이지가 회복된 뒤 같은 경로가 회복되면 service branch입니다. 특정 버전에서만 재현되고 수정 버전에서 사라지면 version branch입니다. 둘 다 아니면 최신 업데이트만 계속 탓하면 안 됩니다.
이 분기는 로컬 상태를 보호하기 위해 필요합니다. 장애 중에 cache, token, PATH, extension을 동시에 바꾸면 장애가 끝난 뒤에도 원인을 확인할 수 없습니다. 버전 회귀를 보고하려면 version과 failing surface가 있어야 합니다.
같은 경로 검증과 증거 패킷
수정 완료는 원래 실패하던 경로로 판단합니다. VS Code에서 실패했다면 시스템 터미널 성공은 분류 증거일 뿐입니다. npm script에서 실패했다면 직접 명령 성공은 wrapper 의심 증거일 뿐입니다. 원래 경로가 아직 실패하면 작업은 끝나지 않았습니다.
에스컬레이션 전에 수집할 것은 명확합니다. 실행 경로 또는 전체 명령, 전체 오류 텍스트, Claude Code version, OS, shell, IDE, status 확인 시각, 활성 인증 경로, 최근 변경, 시스템 터미널과 IDE/wrapper 비교, 최소 재현 단계, logs, session id, request id 또는 correlation id입니다. request id가 없다면 그것도 정보입니다. API 요청 전에 로컬 실행에서 실패했을 가능성을 보여 줍니다.
좋은 report는 길지 않아도 됩니다. "Windows, VS Code, version X, 시스템 터미널 정상, IDE 안에서만 실패, auto-attach 관련 환경 제거 뒤 같은 IDE path 복구"처럼 분기가 보여야 합니다. "code 1이 뜹니다"만 있으면 상대는 처음부터 분기표를 다시 타야 합니다.
분기별 빠른 조치
| 분기 | 먼저 할 일 | 먼저 피할 일 | 성공 증거 |
|---|---|---|---|
| 터미널 | 새 shell, 같은 directory, claude doctor | 전체 config 삭제 | 같은 command가 시작됨 |
| 인증/세션 | /status, 해당 login path 갱신 | 모든 token 교체 | 같은 login path 성공 |
| Windows/PATH | where claude, Git, PATH | 증거 없는 재설치 | 새 터미널에서 binary 확인 |
| IDE | 시스템 터미널 비교 | Claude Code 전체 탓하기 | IDE path가 복구됨 |
| 환경 변수 | PATH/proxy/token/shell startup | secrets 출력/삭제 | 하나의 차이가 설명됨 |
| wrapper | direct path 확인 후 층 추가 | 먼저 Claude Code 변경 | wrapper 층이 고립됨 |
| 상태/버전 | status 시각과 version 기록 | 오래된 글을 현재 증거로 사용 | 상태/버전 변화 뒤 같은 경로 복구 |
| 미확정 | 증거 패킷 준비 | 랜덤 수정 반복 | issue에 분기 메모가 있음 |
자주 묻는 질문
이 오류는 Claude Code가 다운됐다는 뜻인가요?
그 자체로는 아닙니다. status 확인은 필요하지만, 터미널, IDE, wrapper, auth, 세션, PATH도 같은 문구를 만들 수 있습니다.
먼저 재설치해야 하나요?
대부분은 아닙니다. binary가 없거나 PATH/Git/shell/permission 문제가 확인될 때만 첫 조치가 됩니다. 한 경로는 정상이고 다른 경로만 실패한다면 재설치는 첫 진단이 아닙니다.
가장 빠른 안전 확인은 무엇인가요?
실행 경로를 고정하고 시스템 터미널과 실패 경로를 비교하는 것입니다. 그 다음 한 가지만 바꾸고 같은 경로로 다시 확인합니다.
VS Code나 Cursor에서만 실패하면 어떻게 하나요?
같은 폴더에서 시스템 터미널로 같은 명령을 실행합니다. 정상이라면 extension logs, integrated shell, workspace settings, auto-attach, environment variables, working directory를 봅니다.
API 500이나 rate limit와 같은 문제인가요?
아닙니다. process exit는 API 요청 전에 발생할 수 있습니다. HTTP 500이나 request id가 보이면 API Error 500 가이드를 사용하세요. 사용량 제한이면 Claude Code rate limit 가이드가 맞습니다.
작업 규칙
Claude Code 종료 코드 1은 단일 fix가 아니라 분기 라우팅 문제로 다루세요. 실행 경로를 찾고, 가장 덜 파괴적인 분기를 먼저 확인하고, 하나만 바꾼 뒤 같은 경로로 재검증합니다. 그래도 실패할 때만 증거와 함께 에스컬레이션하세요.