Claude Code 문제 해결 가이드
Claude Code 문제 해결의 핵심은 Claude / Anthropic 전용 설정이 올바르게 적용되었는지 확인하는 것입니다. OpenAI 호환 주소나 Codex 모델명, Gemini Key 등을 Claude Code에 혼용하지 마세요.
가장 먼저 확인해야 할 사항
| 확인 항목 | 확인 방법 | 이유 |
|---|---|---|
| 대상 도구 | Codex나 Gemini CLI가 아닌 Claude Code를 점검하고 있는지 확인하세요 | 도구마다 설정 파일, 프로토콜 및 모델명이 서로 다릅니다. |
| 프로바이더 지원 프로토콜 | 대시보드나 가이드에 Claude, Anthropic, Claude Code가 명시되어 있는지 확인 | OpenAI 호환 인터페이스만 제공하는 프로바이더는 Claude Code를 지원하지 않을 수 있습니다 |
| Key 유형 | Claude / Anthropic 전용 Key 사용 | Key 유형이 잘못되면 401 오류나 인증 실패가 바로 발생합니다 |
| 터미널 상태 | 설정을 전환한 후 터미널을 다시 열고 테스트 | 기존 터미널 창에는 전환 전의 환경 변수나 설정이 여전히 남아 있을 수 있습니다 |
자주 발생하는 오류
| 현상 | 우선 확인 사항 | 해결 방법 |
|---|---|---|
| 명령어는 실행되지만 요청이 실패하는 경우 | Claude Code에 새 설정이 적용되었는지 확인 | 현재 터미널 창을 닫고 다시 연 후 가장 짧은 테스트 질문을 보내보세요. CC-Switch를 통해 전환한 후에는 동일한 설정을 수동으로 동시에 수정하지 마세요. |
| 401 / Unauthorized | Key 유형 및 무결성 | Claude / Anthropic 전용 Key를 사용 중인지 확인하고 Claude Code에 OpenAI 호환 Key를 입력하지 마세요. 다시 복사할 때 앞뒤 공백이 들어가지 않았는지 확인하세요. |
| 404 / model not found | Claude 모델명 | 프로바이더 대시보드에 기재된 Claude 모델명을 대소문자, 하이픈, 버전 번호 변경 없이 그대로 입력하세요. |
| 연결 시간 초과 또는 응답 없음 | Claude Base URL | 대시보드에서 Claude / Anthropic API 주소를 확인하세요. OpenAI 호환 주소만 제공하는 프로바이더는 Claude Code를 지원하지 않을 수 있습니다. |
| 전환 후에도 이전 프로바이더가 계속 사용되는 경우 | 터미널 세션 및 설정 소스 | 터미널을 다시 열고 재테스트하세요. 여전히 적용되지 않는다면 CC-Switch의 현재 프로바이더가 Claude Code에 올바르게 적용되었는지 확인하세요. |
최소 단위 테스트
테스트할 때는 먼저 정해진 짧은 질문을 보내 응답이 오는지 확인한 다음 실제 프로젝트를 진행하세요.
Claude Code 최소 테스트
claude "Please reply only: Claude Code configuration test successful"문의 템플릿
프로바이더에 문의할 때 작성 형식
Tool: Claude Code System version: Provider dashboard Base URL: Model ID / model name: Exact error: I have checked: no spaces in the Key / balance is sufficient / model name copied exactly / Base URL copied from the dashboard / terminal reopened