Claude Code API 키 인증 실패 오류 해결법

API 키 인증 오류가 발생하는 주요 원인

Claude Code를 처음 설치하고 실행했는데 "Invalid API Key"나 "Authentication failed" 같은 메시지가 뜨면 당황스러워요. 이 오류는 대부분 API 키가 올바르게 설정되지 않았을 때 발생해요. 구체적으로는 몇 가지 원인이 있어요.

첫 번째는 API 키를 아예 설정하지 않은 경우예요. Claude Code는 Anthropic에서 발급받은 API 키가 있어야 동작하는데, 설치만 하고 키 설정을 건너뛰면 인증 오류가 바로 나타나요. 두 번째는 키를 복사할 때 앞뒤에 공백이 포함된 경우예요. 눈에 보이지 않는 공백 문자 하나 때문에 전체 인증이 실패할 수 있어요. 세 번째는 이미 만료되었거나 비활성화된 키를 사용하는 경우예요. Anthropic 콘솔에서 키를 삭제하거나 재생성했다면, 이전 키는 더 이상 작동하지 않아요. 네 번째는 환경 변수(environment variable)가 제대로 적용되지 않은 경우예요. 터미널을 새로 열지 않으면 변경한 환경 변수가 반영되지 않는 경우가 많아요.

 

 

 

API 키를 올바르게 설정하는 방법

API 키 인증 오류를 해결하려면 먼저 유효한 키가 있는지 확인해야 해요. Anthropic 콘솔(console.anthropic.com)에 로그인한 뒤 API Keys 메뉴에서 키를 확인하거나 새로 생성할 수 있어요. 키는 sk-ant-로 시작하는 긴 문자열이에요.

키를 확보했으면 Claude Code에 등록해야 해요. 가장 간단한 방법은 환경 변수로 설정하는 거예요. Windows 터미널에서는 아래 명령어를 사용해요.

set ANTHROPIC_API_KEY=sk-ant-여기에-본인-키-입력

Mac이나 Linux 사용자라면 export 명령어를 사용해요.

export ANTHROPIC_API_KEY=sk-ant-여기에-본인-키-입력

이때 키 앞뒤에 따옴표나 공백이 들어가지 않도록 주의해야 해요. 복사한 뒤 붙여넣기 전에 텍스트 편집기에서 한번 확인하는 습관을 들이면 좋아요. 환경 변수를 설정한 뒤에는 반드시 같은 터미널 창에서 Claude Code를 실행해야 해요. 다른 터미널 창에는 이 설정이 적용되지 않아요.

 

설정 후에도 오류가 계속될 때 점검 목록

환경 변수를 설정했는데도 여전히 인증 오류가 발생한다면, 아래 항목을 하나씩 점검해 보세요.

먼저 환경 변수가 실제로 적용되었는지 확인해요. 터미널에서 echo $ANTHROPIC_API_KEY (Windows CMD에서는 echo %ANTHROPIC_API_KEY%)를 입력했을 때 본인의 키 값이 출력되어야 해요. 빈 값이 나오면 환경 변수 설정이 현재 세션에 반영되지 않은 거예요.

다음으로 키 상태를 확인해요. Anthropic 콘솔에서 해당 키가 활성(Active) 상태인지 살펴보세요. 키를 여러 개 만들었다면 현재 사용 중인 키가 어떤 것인지 헷갈릴 수 있어요. 비활성화된 키나 삭제된 키는 당연히 인증에 실패해요.

네트워크 문제도 원인이 될 수 있어요. 회사나 학교 네트워크에서 특정 외부 API 접속을 차단하는 경우가 있어요. 이럴 때는 모바일 핫스팟 같은 다른 네트워크로 바꿔서 테스트해 보면 네트워크 문제인지 키 문제인지 구분할 수 있어요.

마지막으로 Claude Code 버전이 너무 오래되지 않았는지 확인해요. claude --version 명령어로 현재 버전을 확인하고, 오래된 버전이라면 npm update -g @anthropic-ai/claude-code 명령어로 업데이트해 보세요. 간혹 구버전에서 인증 방식 변경으로 오류가 발생하기도 해요.

 

API 키를 안전하게 관리하는 실전 팁

API 키 인증 오류를 해결한 뒤에는 키를 안전하고 편리하게 관리하는 방법도 알아두면 좋아요.

매번 터미널을 열 때마다 환경 변수를 설정하기 번거롭다면, 시스템 환경 변수로 등록하는 방법이 있어요. Windows에서는 시스템 속성 → 환경 변수에서 ANTHROPIC_API_KEY를 추가하면 돼요. Mac이나 Linux에서는 ~/.bashrc 또는 ~/.zshrc 파일에 export ANTHROPIC_API_KEY=키값을 추가하면 터미널을 새로 열 때마다 자동으로 적용돼요.

한 가지 꼭 기억할 점은 API 키를 코드 파일이나 Git 저장소에 직접 넣으면 안 된다는 거예요. 키가 외부에 노출되면 다른 사람이 여러분의 API 사용량을 소모할 수 있어요. 만약 실수로 키를 커밋했다면, Anthropic 콘솔에서 즉시 해당 키를 비활성화하고 새 키를 발급받으세요.

또한 프로젝트별로 다른 키를 사용하고 싶다면, 프로젝트 루트에 .env 파일을 만들어 관리하는 방법도 있어요. 이때 .gitignore에 .env를 반드시 추가해서 저장소에 포함되지 않도록 해야 해요. 이렇게 관리하면 Claude Code API 키 인증 문제를 예방하면서도 여러 프로젝트를 깔끔하게 운영할 수 있어요.