Codex 문제 해결 및 점검 가이드
Codex 문제 해결의 핵심은 OpenAI 호환 인터페이스입니다. 일반적으로 Base URL, Key, 모델 이름, 현재 Provider 적용 여부 순서로 점검합니다.
먼저 무엇을 확인해야 하나요?
| 점검 항목 | 확인 방법 | 이유 |
|---|---|---|
| 공급자(Provider)의 OpenAI 호환 인터페이스 지원 여부 | 대시보드에서 API 주소, Base URL, OpenAI 호환성 등의 안내 확인 가능 | Codex가 호환 인터페이스로 요청할 수 있어야 합니다 |
| Base URL | 공급업체(Provider)가 제공하는 API 링크 복사 | /v1 필요 여부는 대시보드 예시를 따르고 임의로 추측하지 마세요 |
| Key 상태 | Key가 비활성화/만료되지 않았으며 계정 잔액이 정상인지 확인 | 401 오류는 대부분 Key 점검부터 시작합니다 |
| 모델 이름 | 대시보드의 모델 목록에서 정확히 복사 | 모델 이름의 대소문자, 하이픈(-), 버전 번호 등이 틀리면 오류가 발생합니다 |
자주 발생하는 오류
| 현상 | 우선 점검 항목 | 해결 방법 |
|---|---|---|
| 401 / Unauthorized | API Key | Key를 다시 생성하거나 복사하고, 비활성화/만료되지 않았는지 및 계정 잔액이 정상인지 확인하세요. |
| 404 / model not found | 모델 이름 | 기억에 의존해 모델 이름을 입력하지 마세요. 공급업체 대시보드의 모델 목록에서 복사하세요. 모델 목록 조회를 지원하는 경우 먼저 목록을 가져오고, 실패하면 수동으로 추가하세요. |
| Base URL 관련 오류 | API 링크가 완전한지 여부 | Base URL은 공급업체에서 제공하는 API 링크입니다. /v1 포함 여부는 대시보드 예시를 따르고 임의로 추측하지 마세요. |
| 요청이 전달되지 않으나 Key는 정상인 경우 | 프로토콜 일치 여부 | 현재 공급업체가 Claude, Gemini 또는 웹 채팅 전용 인터페이스가 아닌 OpenAI 호환 인터페이스를 제공하는지 확인하세요. |
| CC-Switch 사용 후 적용되지 않음 | 대상 도구 선택 | Provider가 Claude Code가 아닌 Codex에 적용되었는지 확인하고, 터미널이나 클라이언트를 재시작한 후 다시 테스트하세요. |
최소 테스트
실제 프로젝트 작업을 진행하기 전에 가장 짧은 질문으로 테스트하여 요청이 정상 작동하는지 확인하세요.
Codex 최소 테스트
codex "Please reply only: Codex configuration test successful"문의 템플릿
공급업체(Provider)에 문의할 때 작성 예시
Tool: Codex 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