적용 버전: CC Switch 3.16.0 이상. 이 글은 저장소 문서와 코드를 기반으로 작성되었으며, DeepSeek를 OpenAI Chat Completions 호환 인터페이스의 예시로 사용합니다. 스크린샷은 현재 프론트엔드 인터페이스에서 가져온 것으로, 실제 API Key나 계정 잔액 노출을 방지하기 위해 비식별화된 예시 데이터를 사용했습니다.
로컬 라우팅이 필요한 이유
새 버전의 Codex CLI는 OpenAI Responses API를 기반으로 하지만, DeepSeek, Kimi, MiniMax, SiliconFlow와 같은 많은 제공업체는 실제로 OpenAI Chat Completions 형식, 즉 /chat/completions를 노출합니다. 이 두 프로토콜의 요청 본문, 스트리밍 이벤트 및 반환 구조는 다릅니다. Chat 인터페이스를 Codex 설정에 직접 입력하면 모델 목록이 잘못 표시되거나 404/400 오류가 발생하거나 Codex가 스트리밍 응답을 제대로 파싱하지 못하는 경우가 많습니다.
CC Switch는 Codex가 항상 로컬 경로에 연결하도록 하고 여전히 Responses API를 통해 요청을 보내는 방식을 사용합니다. 경로는 내부적으로 현재 제공업체가 Chat 형식인지 식별하고, 요청을 Chat Completions로 다시 작성하여 업스트림으로 보낸 후, Chat 응답을 다시 Responses 형식으로 변환하여 Codex에 반환합니다.
이 체인은 크게 네 단계로 나뉩니다:
- Codex가 인계할 때 로컬 구성이
http://127.0.0.1:15721/v1로 작성되고wire_api = "responses"가 강제로 설정됩니다. - Provider의
meta.apiFormat = "openai_chat"는 경로에 실제 업스트림이 Chat Completions임을 알려줍니다. - 경로가
/responses또는/v1/responses를/chat/completions로 다시 작성하고 Responses 요청 본문을 Chat 요청 본문으로 변환합니다. - 업스트림이 반환된 후, 경로는 Chat JSON 또는 SSE를 Codex가 이해할 수 있는 Responses JSON/SSE로 변환합니다.
준비 사항
먼저 세 가지를 준비해야 합니다:
- CC Switch가 설치되어 있고 시작 준비가 완료되어야 합니다.
- Codex CLI가 설치되어 있고 최소 한 번 실행되어
~/.codex/config.toml디렉토리 구조가 존재해야 합니다. - DeepSeek 또는 유사한 Chat Completions 제공업체의 API Key가 필요합니다.
DeepSeek의 공식 문서에 따르면 OpenAI 호환 기본 URL은 https://api.deepseek.com입니다(다른 제공업체는 종종 /v1 접미사가 있는 기본 URL을 사용합니다). Chat API 경로는 /chat/completions입니다. CC Switch의 DeepSeek 사전 설정에는 이미 이 정보가 구성되어 있으므로 인터페이스 경로를 수동으로 조합하는 대신 사전 설정을 우선 사용하시기 바랍니다.
1단계: Codex Provider 추가
CC Switch를 열고 상단의 Codex 탭으로 전환한 후 오른쪽 상단의 더하기 기호를 클릭하여 Provider를 추가합니다.
내장 사전 설정에서 DeepSeek를 선택합니다. 다음 두 가지만 수행하면 됩니다:
- DeepSeek API Key를 입력합니다.
- Provider를 저장합니다.
사전 설정에는 이미 DeepSeek의 요청 주소, 기본 모델, 모델 메뉴 및 사고/추론 매개변수가 포함되어 있으며 "로컬 라우팅 매핑 필요"가 자동으로 켜집니다. 필요에 따라 기본 모델이나 모델 표시 이름을 조정할 수 있습니다. 프로토콜 변환은 라우팅 계층에서 처리합니다.
2단계: 로컬 라우팅 활성화 및 Codex 인계
설정에서 라우팅 페이지로 이동하여 로컬 라우팅을 확장하고 두 가지 토글을 완료합니다:
- 기본 라우팅 스위치를 켜서 로컬 서비스를 시작합니다. 기본 주소는
127.0.0.1:15721입니다. - 라우팅 활성화에서 Codex를 켭니다. Codex만 경로를 통과하도록 하려면 Claude와 Gemini를 끈 상태로 유지할 수 있습니다.
인계 후 CC Switch는 Codex의 실시간 구성을 로컬 경로로 지정하고 인증을 플레이스홀더로 관리합니다. 실제 DeepSeek Key는 여전히 CC Switch Provider 구성에 저장되며 포워딩 중에 로컬 경로에 의해 주입되므로 Codex 실시간 구성에 Key를 노출할 필요가 없습니다.
3단계: Provider 전환 및 Codex 재시작
Codex Provider 목록으로 돌아가서 DeepSeek Provider에 대해 활성화를 클릭합니다. "경로 필요" 태그가 보이면 이 Provider를 사용하려면 경로가 실행 중이어야 함을 의미합니다. 경로가 시작되지 않은 경우 CC Switch는 "정상 사용을 위해 라우팅 서비스가 필요합니다"라는 팝업을 표시합니다.
전환 후에는 현재 Codex 터미널 세션을 재시작하는 것이 좋습니다. 그 이유는 다음과 같습니다:
- Codex 프로세스가 이미 이전
config.toml을 읽었을 수 있습니다. modelcatalogjson이 생성된 후/model메뉴는 일반적으로 새 프로세스에서 새로 고쳐야 합니다.
Codex에 들어간 후 /model을 사용하여 현재 모델이 DeepSeek 사전 설정의 모델(예: DeepSeek V4 Flash)인지 확인할 수 있습니다. 현재 Codex 앱은 사용자 정의 다중 모델 선택을 지원하지 않으며 구성의 첫 번째 모델을 기본값으로 사용합니다.
다른 Chat Provider 처리 방법
DeepSeek, Kimi, MiniMax, SiliconFlow와 같은 일반적인 Chat 형식 Provider는 CC Switch에 이미 사전 설정이 있으므로 우선 사용하시기 바랍니다. 사전 설정에 없는 Provider에 대해서만 사용자 정의 구성을 선택해야 합니다. 이 경우 해당 문서에 따라 API Key, 기본 URL 및 모델을 입력하고 API 형식을 OpenAI Chat Completions(라우팅 필요)로 설정합니다.
업스트림이 OpenAI Responses API를 직접 지원하는 경우 "로컬 라우팅 매핑 필요"를 켤 필요가 없습니다. 이 경우 CC Switch는 Chat 변환 없이 Responses를 통해 직접 연결할 수 있습니다.
FAQ
Codex가 404를 반환하거나 /responses를 찾을 수 없음
일반적으로 Codex 인계가 활성화되지 않았거나 업스트림 Chat 기본 URL을 Codex에 직접 수동으로 입력했기 때문입니다. ~/.codex/config.toml이 http://127.0.0.1:15721/v1을 가리키는지 확인하세요.
DeepSeek 업스트림이 404를 반환함
내장 DeepSeek 사전 설정을 사용하는 경우 먼저 현재 Provider가 실제로 사전 설정에서 온 것이고 Codex 라우팅이 활성화되어 있는지 확인하세요. 사용자 정의 Provider를 사용하는 경우에만 기본 URL을 다시 확인해야 합니다. 기본 URL은 서비스 루트 주소여야 하며 /chat/completions가 포함된 전체 인터페이스 경로가 아닙니다.
/model에 DeepSeek 모델이 표시되지 않음
Provider를 저장한 후 Codex를 재시작하세요. CC Switch는 cc-switch-model-catalog.json을 생성하고 경로를 modelcatalogjson에 기록하지만, 실행 중인 Codex 프로세스는 모델 디렉토리를 핫로드하지 못할 수 있습니다.
현재 Codex 앱은 다중 모델 선택을 지원하지 않으며 첫 번째 모델을 기본값으로 사용합니다.
경로는 켜져 있지만 요청이 여전히 잘못된 Provider로 전송됨
세 가지 상태가 일관되는지 확인하세요: Codex 탭의 현재 Provider가 DeepSeek이고, 로컬 라우팅 서비스가 실행 중이며, 라우팅 활성화의 Codex 스위치가 켜져 있어야 합니다.
로컬 라우팅을 통해 공식 OpenAI Codex 계정을 사용할 수 있나요?
권장되지 않습니다. CC Switch는 로컬 라우팅 인계 모드에서 공식 Provider로 전환하는 것을 방지합니다. 프록시를 통해 공식 API에 액세스하면 계정 위험이 발생할 수 있기 때문입니다. 라우팅은 주로 타사, 집계 또는 프로토콜 변환 시나리오를 위한 것입니다.
