도움말
Claude Code 오류
오류 메시지별로 원인을 찾아보세요. 각 항목은 무엇을 뜻하는지, 그다음 무엇을 해야 하는지를 설명합니다. 먼저 요청이 어디로 가는지 확인하세요. Claude Code에서 /status를 실행하면 Base URL이 https://corecode.live여야 합니다. 아니라면 Claude Code 문서에 따라 먼저 설정을 고치세요.
Unable to connect to Anthropic services
첫 실행 시 온보딩이 Anthropic 서비스에 접속하는데 중국 본토에서는 접속이 안 되는 경우가 많아, Claude Code가 Unable to connect to Anthropic services 또는 Failed to connect to api.anthropic.com을 표시합니다. 릴레이와는 무관하며, 온보딩을 건너뛰면 됩니다.
- 편집기로
~/.claude.json(Windows는%USERPROFILE%\.claude.json)을 엽니다. - 최상위에
"hasCompletedOnboarding": true를 추가하고 저장합니다. claude를 다시 실행합니다.
나머지 공식 요청(자동 업데이트, 텔레메트리, 오류 보고)이 계속 실패하면 ~/.claude/settings.json의 env에 "CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC": "1"을 추가해 끄세요. 권장 설정을 참고하세요.
Invalid API key · Please run /login
Claude Code가 릴레이 키를 찾지 못하고 공식 로그인으로 돌아갔습니다. 흔한 원인은 다음과 같습니다.
- 변수를 다른 터미널에서만 설정했습니다.
~/.claude/settings.json의env에 넣는 것이 확실한 방법이며, 모든 터미널과 VS Code 확장이 이 파일을 읽습니다. - 변수 이름의 오타입니다. 릴레이 키는
ANTHROPIC_AUTH_TOKEN에, 주소는ANTHROPIC_BASE_URL에 넣습니다. - Claude Code를 재시작하지 않았습니다. 설정은 시작할 때만 읽습니다.
안내 메시지대로 claude.ai 계정으로 /login을 실행하지 마세요. Claude Code가 공식 계정으로 전환됩니다.
Auth conflict: Both a token and an API key are set
ANTHROPIC_AUTH_TOKEN과 ANTHROPIC_API_KEY가 둘 다 설정되어 Claude Code가 어느 쪽을 쓸지 판단하지 못합니다. ANTHROPIC_API_KEY를 제거하고 ANTHROPIC_AUTH_TOKEN만 남기세요. 현재 터미널에서도 비어 있는지 echo $ANTHROPIC_API_KEY(PowerShell에서는 $env:ANTHROPIC_API_KEY)로 확인하세요. 전에 claude.ai에 로그인했다면 /logout도 실행하세요.
401 authentication_error
릴레이가 요청은 받았지만 키를 받아들이지 않습니다. 복사 중 글자가 빠졌거나, 키가 삭제되었거나, 다른 공급자의 키입니다. API 키 페이지에서 다시 복사하고 sk-로 시작하는지, 앞뒤에 공백이 없는지 확인하세요.
403
| 메시지 | 원인 | 해결 방법 |
|---|---|---|
| Insufficient quota | 잔액이 모두 소진되었습니다. | 지갑에서 충전하세요. 설정 변경 없이 바로 다시 작동합니다. |
| Only requests from Claude Code are accepted | 仅限CC(Claude Code 전용) 그룹의 키는 Claude Code CLI만 허용하며, SDK, curl, 그 밖의 클라이언트는 거부됩니다. | Claude Code에서 사용하세요. 다른 클라이언트에는 可外接(외부 클라이언트용) 그룹의 키를 쓰세요. |
| Request not allowed | 요청이 릴레이를 거치지 않고 Anthropic에 직접 전달되어 Anthropic의 지역 제한으로 거부되었습니다. | /status로 Base URL을 확인하세요. 위를 참고하세요. |
| This conversation contains a message the upstream model refused under its usage policy | Anthropic의 안전 분류기가 이 대화의 메시지 하나를 거부했습니다. 같은 대화를 다시 보내면 또 거부되므로 CoreCode는 전달하지 않고 중단합니다. 분류기는 가끔 평범한 요청도 거부하며, Claude Code의 auto 모드가 보내는 별도의 검사도 포함됩니다. | 새 대화를 시작하거나, 거부된 메시지를 수정해 다시 보내세요. 계속 발생하면 CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS가 설정되어 있는지 확인하세요. auto 모드의 비용을 참고하세요. |
429 rate_limit_error
키가 요청 속도 또는 동시 실행 한도를 넘었습니다. Claude Code가 알아서 대기 후 재시도하므로 가끔 나오는 경우에는 조치가 필요 없습니다. 계속 발생하면 동시에 실행하는 Claude Code 세션과 서브에이전트를 줄이세요. 더 높은 동시 실행이 필요하면 문의해 주세요.
529 overloaded_error
Anthropic이 일시적으로 과부하 상태입니다. 설정 때문이 아니며 Claude Code가 알아서 재시도합니다. 몇 분 넘게 계속되면 서비스 상태를 확인하거나 /model로 잠시 다른 모델로 전환하세요.
500, 502, 503, 504
Service deployment in progress; retry shortly.와 함께 오는503: CoreCode가 릴리스 중입니다. 응답에Retry-After: 5가 포함되어 있으니 몇 초 후에 다시 시도하세요. 이미 진행 중인 요청은 영향을 받지 않습니다.- 그 밖의
5xx: 업스트림 또는 게이트웨이의 장애입니다. 먼저 서비스 상태를 확인하세요. 정상으로 보이는데 오류가 반복되면 사용 로그에서 실패한 요청의 시각을 보내 주세요.
400 invalid_request_error
| 메시지 | 해결 방법 |
|---|---|
prompt is too long | 컨텍스트가 모델의 한도를 넘었습니다. /compact로 기록을 압축하거나 /clear로 새 세션을 시작하세요. |
| 모델이 존재하지 않음 | 요금 페이지에 나열된 모델 이름을 공급사 접두사 없이 사용하세요. |
오랫동안 출력이 없거나 타임아웃이 발생할 때
확장 사고 중에는 모델이 몇 분 동안 텍스트를 내지 않을 수 있으며 정상입니다. CoreCode 게이트웨이의 읽기 타임아웃은 10분입니다. Claude Code 자체의 타임아웃은 밀리초 단위의 API_TIMEOUT_MS이며, 10분보다 짧게 설정하면 클라이언트가 긴 사고를 중간에 끊습니다.
프록시나 VPN을 켠 경우
corecode.live는 중국 본토에서 직접 접속할 수 있습니다. 전역 프록시는 요청을 먼 길로 돌려 보내 느려지고 가끔 스트림이 끊깁니다. 프록시 클라이언트에서 corecode.live에 DIRECT 규칙을 추가하세요. 결제 페이지가 열리지 않을 때도 프록시를 끄고 다시 시도해 보세요.
그래도 해결되지 않을 때
먼저 서비스 상태를 확인하세요. 정상으로 보이면 claude --version의 출력, 정확한 오류 메시지, 사용 로그에서 확인한 실패한 요청의 시각, 세 가지를 보내 주세요. WeChat 그룹에서 물어볼 수도 있습니다. 그 밖의 질문은 FAQ에 있습니다.