클로드 코드(Claude Code) 로그인 오류, 원인과 해결 순서

맥(darwin arm64)에서 Claude Code 2.1.309로 한 번 실행했을 때, 빈 설정 폴더를 CLAUDE_CONFIG_DIR로 지정한 요청은 0.5초 뒤 Not logged in · Please run /login을 반환했습니다. 같은 맥에서 원래 설정 폴더로 보낸 요청은 5.5초 뒤 정상 답을 받았습니다. 이 측정을 보면 Claude Code 로그인 오류는 계정이 로그아웃됐을 때만 뜨는 것이 아니라, 지금 실행이 로그인 정보가 없는 설정 폴더를 보고 있을 때도 같은 메시지가 나올 수 있습니다. 다만 이 결과는 claude.ai 계정으로 로그인한 환경에서 한 번 실행한 것이고, 환경 변수로 지정한 API 키나 클라우드 제공자 설정처럼 다른 인증 경로를 쓰는 환경까지 검증한 것은 아닙니다. 직접 재현해 볼 때도 같은 조건(맥, claude.ai 로그인, 빈 설정 폴더)에서 비교하는 편이 좋습니다.

클로드 코드 로그인 안 됨 메시지는 언제 뜰까요?

재현 방법은 단순합니다. 작업 폴더 안에 빈 설정 폴더를 만들고, CLAUDE_CONFIG_DIR 환경 변수로 그 폴더를 가리킨 채 요청을 보내면 됩니다. 직접 실행해 보면 결과는 이렇습니다.

$ mkdir -p empty-config && CLAUDE_CONFIG_DIR="$PWD/empty-config" claude -p "OK라고만 답하세요" --model claude-haiku-5-5 --output-format json | jq '{"오류": .is_error, "답": .result}'
{
  "오류": true,
  "답": "Not logged in · Please run /login"
}

답 대신 로그인하라는 안내가 돌아왔고, 오류 표시(is_error)도 true였습니다. 그렇다면 이 폴더 기준으로 로그인 상태는 어떻게 보일까요? 같은 폴더를 가리킨 채 상태를 물으면 로그인 여부는 false, 방식은 none으로 나옵니다.

$ CLAUDE_CONFIG_DIR="$PWD/empty-config" claude auth status --json | jq '{"로그인": .loggedIn, "방식": .authMethod}'
{
  "로그인": false,
  "방식": "none"
}

반면 설정 폴더를 바꾸지 않은 기본 실행에서는 로그인 true, 방식 claude.ai였고 같은 질문에 OK라는 답이 돌아왔습니다. 오류가 난 실행도 기록된 종료 코드는 0이었습니다. 다만 측정은 출력을 jq 파이프로 넘긴 결과라, 이 0은 파이프라인 전체의 값입니다. claude 자체의 종료 코드는 따로 확인하지 않았으므로, 이 측정만으로는 claude가 로그인 실패에 어떤 종료 코드를 돌려주는지 가를 수 없습니다. 에이전트나 스크립트에서 claude -p를 돌리고 있다면 set -o pipefail을 쓰거나 JSON 출력의 is_error를 함께 확인하는 편이 좋습니다.

도식출처: 근거를 바탕으로 코드가 그린 도식

함께 읽을 글

• 클로드 코드(Claude Code) 설정파일, 위치와 우선순위 확인법
• 코덱스(Codex) 로그인 에러, 인증이 안 될 때 원인과 해결 방법
• 클로드 코드(Claude Code) 플러그인 사용법, 만들기부터 첫 실행까지

다시 로그인하는 순서

메시지를 봤다면 아래 순서로 확인해 보세요. 상태 확인을 먼저 하는 이유는 정말 로그아웃된 것인지, 다른 설정 폴더를 보고 있는 것인지부터 갈라야 하기 때문이에요.

1. 로그인 상태 확인: 셸에서 로그인 여부와 방식을 봅니다. 로그인이 false이고 방식이 none이면 지금 실행은 로그인 정보를 찾지 못한 상태입니다.

$ claude auth status --json | jq '{"로그인": .loggedIn, "방식": .authMethod, "제공자": .apiProvider, "구독": .subscriptionType}'

2. 설정 폴더 확인: 셸 설정이나 alias에 CLAUDE_CONFIG_DIR이 걸려 있다면 그 폴더를 가리킨 채 상태를 따로 봅니다(앞 절의 두 번째 명령). 기본 실행은 로그인돼 있는데 이쪽만 false라면 다음 절에서 다루는 경우입니다.
3. 다시 로그인: 셸에서는 claude auth login, 대화 화면에서는 /login을 실행합니다. claude auth --help를 보면 하위 명령은 login, logout, status 세 가지예요. 로그아웃한 뒤 다시 인증하고 싶다면 대화 화면에서 /logout을 입력하면 됩니다. 이때 처음 실행 설정 상태도 초기화되어, 다음 claude 실행에서 로그인과 설정을 다시 거칩니다.
4. 브라우저에서 인증: 브라우저가 저절로 열리지 않으면 c를 눌러 로그인 주소를 복사한 뒤 브라우저에 붙여 넣습니다. 로그인 후 브라우저가 돌아오지 않고 코드를 보여 주면 터미널의 Paste code here if prompted 자리에 붙여 넣으세요. 브라우저가 로컬 콜백 서버에 닿지 못하는 WSL2, SSH 세션, 컨테이너에서 흔한 일입니다. 끝나면 Login successful이 뜨고 Enter를 눌러 이어 갑니다.
5. 요청으로 확인: 짧은 요청을 보내 is_error가 false이고 답이 오는지 봅니다.

$ claude -p "OK라고만 답하세요" --model claude-haiku-5-5 --setting-sources project --strict-mcp-config --output-format json | jq '{"오류": .is_error, "답": .result}'
{
  "오류": false,
  "답": "OK"
}

도식출처: 근거를 바탕으로 코드가 그린 도식

설정 폴더를 바꾸면 왜 로그인이 풀릴까요?

인증 문서에 따르면 로그인 정보는 맥에서는 암호화된 macOS 키체인에, 리눅스에서는 ~/.claude/.credentials.json(파일 권한 0600)에 저장됩니다. 그런데 CLAUDE_CONFIG_DIR을 설정하면 .credentials.json이 그 폴더 아래로 가고, 맥의 키체인 항목도 그 폴더 기준으로 따로 잡힙니다. 그래서 다른 폴더로 띄운 세션은 다른 항목을 읽죠. 앞의 재현에서 빈 폴더가 로그아웃 상태로 보인 것도 이 설명과 맞아떨어집니다.

이 동작을 일부러 쓰기도 합니다. 예를 들어 회사 계정과 개인 계정에 동시에 로그인해 두려면 계정마다 설정 폴더를 따로 주면 돼요. 폴더마다 설정, 세션 기록, claude.ai 로그인이나 API 키를 따로 가집니다. Bash나 Zsh라면 ~/.bashrc나 ~/.zshrc에 이런 alias를 넣습니다.

alias claude-work='CLAUDE_CONFIG_DIR=~/.claude-work claude'

새 터미널에서 claude-work를 처음 실행하면 그 폴더용 로그인과 설정을 새로 거칩니다. 클라이언트 작업용 계정을 따로 쓰는 1인 개발자라면, 로그인 오류가 났을 때 지금 띄운 것이 claude인지 alias인지부터 보는 편이 빠릅니다. 단, API 키 없이 로그인한 Claude Console 계정 두 개는 설정 폴더 바깥에 저장되므로 폴더를 나눠도 구분되지 않습니다.

클로드 코드 인증 오류, 메시지별로 볼 곳

그런데 로그인 정보가 분명히 있는데도 막힌다면요? 이럴 때는 메시지를 기준으로 갈라 보세요. 설치·로그인 문제 해결 문서와 인증 문서가 짚는 경우는 다음과 같습니다.

세션이 만료되면 어떻게 될까요? API 키 없이 Console 계정으로 로그인한 경우(v2.1.242 이상) 클로드 코드가 로그인을 자동으로 갱신합니다. 갱신에 실패하면 다시 로그인할 때까지 요청이 만료 오류로 실패해요.

네트워크 점검은 문서에서 설치 프로그램이 내려받는 downloads.claude.ai에 닿는지 보는 방식으로 안내합니다. 첫 줄에 200이 보이면 닿은 것이고, 403은 보통 프록시·네트워크 필터나 지역 제한, 5xx는 보통 일시적인 서비스 문제입니다. 회사 프록시 뒤라면 HTTPS_PROXY와 HTTP_PROXY를 설정하라고 합니다.

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

자주 하는 실수

• 종료 코드만 보고 성공으로 판단: 재현에서는 로그인 오류가 난 실행도 종료 코드가 0이었습니다.
• alias나 셸 설정의 설정 폴더 지정을 잊음: CLAUDE_CONFIG_DIR이 다른 폴더를 가리키면 그 폴더의 로그인만 봅니다.
• 맥 SSH 세션에서 키체인이 잠긴 상태: 키체인이 쓰기를 거부하면 기본 설정에서는 로그인이 ~/.claude/.credentials.json에 저장되고, CLAUDE_CONFIG_DIR을 지정했다면 그 폴더 아래 .credentials.json에 저장됩니다. API 키를 만드는 Console 로그인은 키체인에 쓸 수 있을 때까지 실패하고, 키체인으로 되돌리는 방법은 문제 해결 문서의 복구 절차에 있습니다.
• API 키 환경 변수를 남겨 둔 채 키 없는 로그인 시도: Console 계정으로 키 없이 로그인하려면 먼저 ANTHROPIC_API_KEY를 해제해야 합니다.

다시 막혔을 때 더 확인할 점

• alias로 띄운 세션의 확인 요청: alias로 CLAUDE_CONFIG_DIR을 지정해 띄웠다면, 확인용 요청과 claude auth status도 같은 CLAUDE_CONFIG_DIR로 보내야 같은 폴더의 로그인을 봅니다.

• 로그인 상태가 true이고 방식이 none이 아닌가

• 지금 실행에 CLAUDE_CONFIG_DIR이 걸려 있다면, 그 폴더 기준 상태도 true인가

• 다시 로그인한 뒤 Login successful을 봤는가

• 짧은 요청의 is_error가 false인가

• 메시지가 OAuth·403·권한·지역 오류라면 위 표의 조치를 따랐는가

• 버전이 v2.1.290 이전은 아닌가

직접 실행한 조건과 한계

맥 한 대(darwin arm64, Node.js v22.23.1)에서 Claude Code 2.1.309로 새 임시 폴더를 만들고, 여섯 단계를 차례로 한 번씩 실행했습니다. 로그인된 상태의 요청은 사용자 설정과 MCP 서버를 끈 옵션을 붙여 claude-haiku-5-5 모델로 보냈어요. 걸린 시간은 버전 확인 0.0초, 상태 보기 0.1초, 로그인된 요청 5.5초, 빈 폴더 요청 0.5초, 빈 폴더 상태 0.1초, 도움말 0.0초였고 종료 코드는 모두 0이었습니다.

도식출처: 명령 실행 실측

빈 폴더 요청이 더 빨리 끝난 것은 한 번 잰 값이라, 이 측정만으로는 이유를 가를 수 없습니다. 실제 로그인을 건드리지 않고 빈 설정 폴더로만 오류를 재현했으므로, 진짜 만료된 세션이나 OAuth 오류, 조직 제한은 재현하지 않았어요. 리눅스와 윈도우도 실행하지 않았으니 저장 위치처럼 운영체제마다 다른 부분은 공식 문서를 기준으로 확인하세요.