외부 모델을 Codex에 연결하기

이 가이드에서는 호스팅되는 서드 파티 모델을 통합하는 두 가지 경로를 설명합니다.

먼저 이해해야 할 중요한 제한 사항이 하나 있습니다.

이 가이드는 동일한 config.toml을 읽는 Codex CLI, Codex IDE 확장 프로그램, 데스크톱 클라이언트를 포함하여 로컬에서 실행되는 Codex 클라이언트에 적용됩니다. 현재 Codex 클라우드 채팅에서는 이 구성을 통해 사용자 지정 모델로 전환할 수 없습니다.

시작하기 전에

Codex CLI 설치 또는 업데이트

npm install -g @openai/codex@latest
codex --version

처음 설치한 후 Codex를 한 번 이상 실행하세요.

codex

그러면 사용자 구성 디렉터리가 초기화됩니다.

Codex 구성 파일 위치

macOS 및 Linux:

~/.codex/config.toml

Windows:

%USERPROFILE%\.codex\config.toml

변경하기 전에 파일을 백업하세요.

macOS / Linux:

mkdir -p ~/.codex/backup
cp ~/.codex/config.toml \
  ~/.codex/backup/config.toml.$(date +%Y%m%d-%H%M%S) \
  2>/dev/null || true

PowerShell:

$codexDir = Join-Path $HOME ".codex"
$backupDir = Join-Path $codexDir "backup"
New-Item -ItemType Directory -Force -Path $backupDir | Out-Null

$configFile = Join-Path $codexDir "config.toml"
if (Test-Path $configFile) {
  $timestamp = Get-Date -Format "yyyyMMdd-HHmmss"
  Copy-Item $configFile (Join-Path $backupDir "config.toml.$timestamp")
}

공급자, MCP, 모델 게이트웨이는 서로 다릅니다

이 개념들은 서로 다른 문제를 해결합니다.

• model_provider는 Codex가 모델 요청을 보낼 위치를 결정합니다.
• MCP는 GitHub, 브라우저, 데이터베이스 같은 도구와 컨텍스트를 추가합니다.
• 모델 게이트웨이는 Codex와 업스트림 모델 사이에서 프로토콜 변환, 인증, 라우팅, 로깅 또는 속도 제한을 처리합니다.

기반 모델을 변경하려면 MCP가 아니라 공급자를 구성하세요.

API key 보호

실제 API key를 Git 저장소에 커밋하거나 전체 키를 스크린샷, 로그 또는 지원 티켓에 노출하지 마세요.

수동으로 구성한 공급자에는 환경 변수를 사용하는 것이 좋습니다.

[model_providers.example]
env_key = "EXAMPLE_API_KEY"

CC Switch는 공급자 구성을 로컬에 저장하며, 공급자를 전환할 때 로컬 Codex 구성을 수정합니다. CC Switch는 서드 파티 오픈 소스 도구이며 OpenAI 제품이 아닙니다. 공식 CC Switch 웹사이트 또는 GitHub 저장소에서만 설치하고 로컬 데이터베이스, 구성 및 백업을 보호하세요.

1. CC Switch로 서드 파티 모델 연결하기

CC Switch는 대부분의 서드 파티 모델에 더 간편한 옵션입니다. 공급자, API key, 모델 목록 및 로컬 라우팅을 관리하며 호환되지 않는 업스트림 프로토콜을 변환할 수 있습니다.

1.1 CC Switch가 해결하는 문제

최신 Codex 클라이언트는 Responses API 요청을 보내지만, 많은 서드 파티 서비스는 다음 중 하나를 제공합니다.

• OpenAI Chat Completions
• Anthropic Messages
• Codex가 기본적으로 나열하지 않는 모델 ID
• 공급자별 추론 매개변수 또는 스트리밍 이벤트 형식

CC Switch는 다음과 같이 요청 경로를 변환할 수 있습니다.

Codex
  │  Responses API
  ▼
CC Switch local route
  │  Converts the protocol and model name when required
  ▼
Third-party model API
  │
  ▼
CC Switch converts JSON, SSE, reasoning data, and tool calls back to Responses
  │
  ▼
Codex

Responses를 기본적으로 지원하는 공급자는 Chat 프로토콜 변환이 필요하지 않습니다. Chat Completions 또는 Anthropic Messages 공급자에는 로컬 라우팅이 필요합니다.

1.2 CC Switch 설치하기

공식 배포 채널만 사용하세요.

• CC Switch 공식 웹사이트
• CC Switch GitHub 저장소
• CC Switch 릴리스

macOS에서는 Homebrew 사용을 권장합니다.

brew install --cask cc-switch

업데이트하려면 다음을 실행하세요.

brew upgrade --cask cc-switch

Windows에서는 Releases에서 .msi 설치 프로그램 또는 포터블 압축 파일을 다운로드하세요.

Linux에서는 Releases에서 .deb, .rpm 또는 AppImage 패키지를 다운로드하세요. 버전에 따라 레이블이 조금씩 달라질 수 있으므로 최신 안정 릴리스를 사용하고 애플리케이션에 표시되는 옵션을 기준으로 판단하세요.

1.3 사전 요구 사항

다음을 준비하세요.

1. Codex가 설치되어 있고 한 번 이상 실행되었습니다.
2. CC Switch가 설치되어 있으며 정상적으로 시작됩니다.
3. 대상 모델 서비스의 API key가 있습니다.
4. 공급자 문서에서 Base URL, 모델 ID 및 업스트림 프로토콜을 확인했습니다.
5. 공식 Codex 계정 기능이 필요하다면 먼저 공식 로그인을 한 번 완료했습니다.

현재 Codex 로그인 상태를 확인하세요.

codex login status

필요하면 로그인하세요.

codex login

기기 코드 로그인도 사용할 수 있습니다.

codex login --device-auth

1.4 선택 사항: 서드 파티 공급자를 사용하면서 공식 로그인 유지하기

이 옵션은 모델 요청을 서드 파티 공급자에게 보내면서 데스크톱 기능, 공식 플러그인 또는 원격 제어 기능을 유지하려는 경우에 주로 유용합니다. 공식 계정 기능에 의존하지 않는 CLI 전용 사용자는 건너뛰어도 됩니다.

권장 순서:

1. CC Switch Codex 패널에서 OpenAI Official을 선택합니다.
2. Codex를 실행하고 공식 계정으로 로그인합니다.
3. CC Switch에서 Settings → General → Codex App Enhancements를 엽니다.
4. Keep official login when switching third-party providers를 활성화합니다.
5. 서드 파티 공급자를 추가하거나 해당 공급자로 전환합니다.

이 옵션을 활성화하면 CC Switch는 다음을 유지하려고 시도합니다.

• 공식 로그인 상태를 위한 ~/.codex/auth.json
• 활성 서드 파티 공급자, 모델, 엔드포인트 및 인증 구성을 위한 ~/.codex/config.toml

auth.json에는 민감한 로그인 데이터가 들어 있습니다. 공유하거나 버전 관리에 커밋하지 마세요.

1.5 서드 파티 공급자 추가하기

CC Switch를 열고 최상위 Codex 패널로 전환한 다음 오른쪽 위 모서리의 추가 버튼을 클릭합니다.

기본 제공 프리셋 우선 사용하기

프리셋이 있으면 이를 사용하고 API key 및 필수 계정별 값만 입력하세요. 프리셋은 일반적으로 다음을 구성합니다.

• Base URL
• 기본 모델
• 업스트림 프로토콜
• 로컬 라우팅 필요 여부
• 모델 매핑
• 선택된 추론 매개변수

CC Switch가 발전함에 따라 프리셋 목록도 변경됩니다. 장기간 유지되는 문서에는 공급자의 현재 모델 ID를 하드 코딩하지 말고 애플리케이션의 목록과 공급자의 공식 문서를 사용하세요.

사용자 지정 공급자 만들기

프리셋이 없으면 사용자 지정 구성을 선택하고 다음 정보를 입력하세요.

가장 중요한 설정은 Upstream Format입니다.

공급자가 “OpenAI 호환성”을 홍보한다는 이유만으로 Responses를 선택하지 마세요. OpenAI 호환 API 중 상당수는 Chat Completions만 구현합니다.

1.6 Base URL을 올바르게 입력하기

기본적으로 CC Switch는 Base URL에 적절한 API 경로를 추가합니다. 대부분의 경우 /chat/completions 또는 /responses을 직접 반복해서 입력하지 말고 공급자 문서에 나온 API 루트를 입력하세요.

예를 들어 공급자 문서에 다음과 같이 나와 있다면:

POST https://api.example.com/v1/chat/completions

다음을 입력해야 할 수 있습니다.

https://api.example.com

또는 프리셋과 공급자 문서에 따라 다음을 입력할 수도 있습니다.

https://api.example.com/v1

Base URL에 /v1이 포함되는지는 공급자와 CC Switch 프리셋에 따라 다릅니다. 기본 제공 연결 확인 기능 또는 라우팅 로그를 사용하여 최종 요청 URL을 확인하세요.

공급자가 표준이 아닌 전체 엔드포인트 경로를 요구할 때만 Full URL Mode를 사용하세요.

1.7 Needs Local Routing 및 모델 매핑 구성하기

공급자가 Chat Completions, Anthropic Messages 또는 Codex가 기본적으로 인식하지 못하는 모델 이름을 사용하는 경우 Needs Local Routing을 활성화하세요.

Chat 중심 프리셋에서는 일반적으로 자동으로 활성화됩니다. 사용자 지정 공급자에서는 이 옵션을 확인하세요.

활성화하면 모델 매핑 표를 사용할 수 있습니다. 일반적인 필드는 다음과 같습니다.

중요 사항:

• 공급자 문서에 나온 정확한 모델 ID를 사용하세요.
• 컨텍스트 창을 추측하지 마세요.
• 모델 목록을 변경한 후 Codex를 다시 시작하세요.
• CC Switch는 이 매핑을 기반으로 Codex 모델 카탈로그를 생성합니다.
• 릴레이가 도메인이나 모델 이름을 변경하면 추론 기능 자동 감지가 잘못될 수 있으므로 고급 설정에서 검토해야 합니다.

1.8 로컬 라우팅 및 Codex 인계 활성화하기

CC Switch에서 다음을 여세요.

Settings → Routing → Local Routing

그런 다음:

1. 기본 로컬 라우팅 스위치를 활성화합니다.
2. Routing Enabled에서 Codex를 활성화합니다.
3. 공급자의 Needs Local Routing 설정을 확인합니다.
4. 공급자를 사용하는 동안 CC Switch를 계속 실행합니다.

일반적인 기본 로컬 경로는 다음과 같습니다.

http://127.0.0.1:15721

인계가 완료되면 실제 Codex 구성은 CC Switch 로컬 경로를 가리킵니다. 이후 CC Switch가 요청을 현재 선택된 업스트림 공급자에게 전달합니다.

Chat Completions 업스트림의 일반적인 흐름은 다음과 같습니다.

Codex POST /responses
  → CC Switch converts it to POST /chat/completions
  → the provider returns JSON or SSE
  → CC Switch rebuilds Responses JSON or SSE
  → Codex continues the tool-call loop

1.9 공급자 전환 후 Codex 다시 시작하기

CC Switch Codex 공급자 목록으로 돌아가 구성한 공급자를 선택하고 활성화합니다.

다음 이유로 전환 후 Codex를 완전히 다시 시작하세요.

• Codex는 시작할 때 config.toml을 읽습니다.
• /model 메뉴는 일반적으로 시작할 때 카탈로그를 불러옵니다.
• IDE 확장 프로그램 또는 데스크톱 클라이언트가 이전 공급자를 캐시할 수 있습니다.
• 기존 세션에 이전 모델 메타데이터가 남아 있을 수 있습니다.

CLI 사용자는 새 프로세스를 시작하기만 하면 됩니다.

codex

1.10 통합 확인하기

Codex 내에서 다음을 실행하세요.

/status

활성 모델, 공급자, 권한 및 컨텍스트 정보를 검토하세요.

모델 선택기를 여세요.

/model

구성 계층을 검사하세요.

/debug-config

다음 항목도 확인하세요.

• CC Switch의 활성 Codex 공급자
• CC Switch 로컬 라우팅 로그 또는 통계
• 공급자 대시보드의 요청 기록 및 잔액 변화
• ~/.codex/config.toml이 현재 로컬 경로를 가리키는지 여부

간단한 인사만으로 설정을 검증하지 마세요. 에이전트 기능 테스트를 하나 이상 실행하세요.

1. Codex에 현재 프로젝트의 파일 목록을 요청합니다.
2. 파일 하나를 읽고 요약하도록 요청합니다.
3. 작은 파일 하나를 수정하도록 요청합니다.
4. 테스트를 실행하도록 요청합니다.
5. 간단한 실패를 그대로 둔 뒤 테스트 결과를 사용하여 프로젝트 수정을 계속할 수 있는지 확인합니다.

텍스트 생성에 성공했다고 해서 도구 호출과 여러 턴에 걸친 에이전트 워크플로가 호환되는 것은 아닙니다.

1.11 공식 OpenAI 공급자로 되돌리기

CC Switch에서 OpenAI Official을 선택하고 Codex를 다시 시작하세요.

로그인 상태를 확인하세요.

codex login status

필요하면 다시 로그인하세요.

codex login

공식 로그인 상태와 서드 파티 모델 요청이 모두 필요하다면 Keep official login when switching third-party providers가 계속 활성화되어 있는지 확인하세요.

1.12 제한 사항 및 운영 고려 사항

CC Switch는 구성을 간소화하지만 업스트림의 제한을 없애지는 않습니다.

• Chat 또는 Messages 변환을 사용하려면 CC Switch를 계속 실행해야 합니다.
• 프로토콜 변환으로 모든 공급자별 기능을 재현할 수는 없습니다.
• 일부 모델은 채팅은 가능하지만 안정적인 도구 호출을 수행하지 못합니다.
• Web Search, 이미지 입력, WebSockets 또는 응답 저장을 사용하지 못할 수 있습니다.
• 업스트림 공급자의 속도 제한, 요금 및 데이터 보존 정책이 계속 적용됩니다.
• API 릴레이가 요청과 응답을 다시 수정할 수 있습니다.
• CC Switch, Codex 또는 공급자를 업그레이드한 후에는 구성을 다시 테스트해야 합니다.

CC Switch는 로컬 데스크톱 개발에 가장 적합합니다. 서버, CI 또는 장시간 실행되는 헤드리스 자동화에는 기본 Responses 공급자나 자체 호스팅 게이트웨이를 사용하는 것이 좋습니다.

2. 사용자 지정 모델 공급자로 호스팅 API 연결하기

서비스가 Codex에 필요한 Responses API를 기본적으로 지원하는 경우에만 공급자를 직접 구성하세요.

서비스가 /chat/completions 또는 Anthropic Messages만 제공한다면 섹션 1의 CC Switch 워크플로를 사용하세요. wire_api = "chat"으로 불일치를 해결하려고 하지 마세요.

2.1 필수 API 기능

Codex 직접 통합에 적합한 공급자는 최소한 다음을 지원해야 합니다.

• POST /responses
• Responses JSON 객체
• Responses SSE 스트리밍 이벤트
• 함수 또는 도구 호출
• JSON Schema 도구 매개변수
• 도구 결과 반환 후 계속 실행
• 여러 턴 요청 또는 previous_response_id에 상응하는 기능
• 충분한 컨텍스트 창과 안정적인 장시간 요청
• 문서화된 인증, 속도 제한 및 오류 응답

일반적인 텍스트 생성만으로는 안정적인 Codex 에이전트에 충분하지 않습니다.

2.2 일반 구성

사용자 수준 구성을 편집하세요.

~/.codex/config.toml

다음을 추가하세요.

model_provider = "third_party"
model = "provider-model-id"

# Set this only when the model explicitly supports it.
model_reasoning_effort = "high"

# Optional: use the real value published by the provider when no catalog exists.
# model_context_window = 131072

[model_providers.third_party]
name = "My Responses-compatible Provider"
base_url = "https://provider.example.com/v1"
env_key = "THIRD_PARTY_API_KEY"
wire_api = "responses"
request_max_retries = 4
stream_max_retries = 5
stream_idle_timeout_ms = 300000

다음과 같은 예약된 공급자 ID는 사용하지 마세요.

openai
ollama
lmstudio

대신 third_party 또는 company_gateway 같은 사용자 지정 ID를 사용하세요.

2.3 구성 필드

base_url에 /v1이 포함되는지는 공급자 문서에 따라 다릅니다. 일반적인 최종 엔드포인트는 다음과 같습니다.

https://provider.example.com/v1/responses

2.4 API key 설정하기

현재 bash / zsh 세션:

export THIRD_PARTY_API_KEY="your API key"

fish:

set -gx THIRD_PARTY_API_KEY "your API key"

현재 PowerShell 세션:

$env:THIRD_PARTY_API_KEY = "your API key"

현재 Windows 사용자에 대해 영구적으로 설정하기:

[Environment]::SetEnvironmentVariable(
  "THIRD_PARTY_API_KEY",
  "your API key",
  [EnvironmentVariableTarget]::User
)

영구 환경 변수를 설정한 후 터미널, IDE 또는 데스크톱 클라이언트를 다시 시작하세요.

2.5 먼저 Responses 엔드포인트 테스트하기

Codex를 실행하기 전에 공급자를 직접 호출하세요.

export PROVIDER_BASE_URL="https://provider.example.com/v1"

curl "$PROVIDER_BASE_URL/responses" \
  -H "Authorization: Bearer $THIRD_PARTY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "provider-model-id",
    "input": "Reply with exactly: PROVIDER_OK",
    "stream": false
  }'

다음을 확인하세요.

• 엔드포인트가 404를 반환하지 않습니다.
• 응답이 Chat Completions choices 배열만 있는 구조가 아니라 Responses 형식의 구조를 가집니다.
• 모델 ID가 허용됩니다.
• 인증이 올바릅니다.
• 오류에 유용한 진단 정보가 포함됩니다.

그런 다음 다음 항목을 개별적으로 테스트하세요.

• stream: true
• 도구 호출
• 도구 결과 후 계속 실행
• 여러 턴
• 긴 컨텍스트
• 동시 실행 및 속도 제한

2.6 Codex 구성 검증하기

엄격 모드로 시작하세요.

codex --strict-config

--strict-config은 알 수 없는 구성 키를 오류로 처리하므로 오래된 가이드에서 복사한 필드를 식별하는 데 도움이 됩니다.

Codex 내에서 다음을 실행하세요.

/status

구성 소스를 검사하려면 다음을 실행하세요.

/debug-config

기본 구성을 변경하지 않고 한 번의 실행에서만 공급자와 모델을 재정의하려면 다음을 실행하세요.

codex \
  -c 'model_provider="third_party"' \
  -m 'provider-model-id'

2.7 모델 카탈로그와 Unknown model

Codex 모델 카탈로그에서는 다음을 설명할 수 있습니다.

• 컨텍스트 창 크기
• 지원되는 추론 수준
• 입력 모달리티
• 도구 호출 기능
• 잘라내기 동작
• 최소 클라이언트 버전

공급자가 Codex 호환 모델 카탈로그를 제공하면 로컬에 저장하고 다음을 구성하세요.

model_catalog_json = "~/.codex/provider-models.json"

카탈로그가 없으면 실제 값을 확인한 후에만 컨텍스트 창을 설정하세요.

model_context_window = 131072

경고를 없애기 위해 관련 없는 모델의 메타데이터를 복사하지 마세요. 잘못된 기능 또는 컨텍스트 메타데이터는 조기 잘라내기, 업스트림 한도 오류 또는 도구 호출 실패를 일으킬 수 있습니다.

2.8 전체 호환성 체크리스트

프로덕션에서 사용하기 전에 다음을 테스트하세요.

• 비스트리밍 /responses 텍스트
• Responses SSE 스트리밍
• 도구 호출 한 번
• 여러 개의 순차 또는 병렬 도구 호출
• JSON Schema 매개변수
• 도구 결과 후 계속 실행
• 긴 컨텍스트 및 자동 압축
• 추론 매개변수
• 이미지 또는 기타 입력 모달리티
• 속도 제한 및 재시도 동작
• 프록시의 SSE 버퍼링 여부
• 공급자의 도구 필드 삭제 또는 재작성 여부
• 데이터 보존, 로깅 및 개인정보 보호 정책

2.9 공급자 구성을 배치할 위치

model_provider, model_providers 및 공급자 인증을 사용자 수준 파일에 배치하세요.

~/.codex/config.toml

저장소 수준 파일에는 배치하지 마세요.

<project>/.codex/config.toml

Codex는 모델 요청을 리디렉션하거나 공급자 인증을 변경할 수 있는 프로젝트 로컬 필드를 무시합니다. 이를 통해 신뢰할 수 없는 복제 저장소가 요청을 다른 서버로 몰래 전달하는 것을 방지합니다.

3. 프로필로 여러 서드 파티 공급자 관리하기

CC Switch 사용자는 일반적으로 애플리케이션에서 공급자를 전환할 수 있으므로 Codex 프로필이 필요하지 않습니다.

여러 기본 Responses 공급자를 수동으로 구성하는 경우 프로필이 유용합니다. 기본 구성에 공급자 정의를 유지하고 별도의 프로필 파일을 사용하여 공급자와 모델을 선택하세요.

기본 ~/.codex/config.toml:

[model_providers.provider_a]
name = "Provider A"
base_url = "https://api.provider-a.example/v1"
env_key = "PROVIDER_A_API_KEY"
wire_api = "responses"

[model_providers.provider_b]
name = "Provider B"
base_url = "https://api.provider-b.example/v1"
env_key = "PROVIDER_B_API_KEY"
wire_api = "responses"

다음을 만드세요.

~/.codex/fast.config.toml

model_provider = "provider_a"
model = "provider-a-fast-model"
model_reasoning_effort = "medium"

다른 프로필을 만드세요.

~/.codex/quality.config.toml

model_provider = "provider_b"
model = "provider-b-quality-model"
model_reasoning_effort = "high"

Codex를 실행할 때 프로필을 선택하세요.

codex --profile fast
codex --profile quality

비대화형 모드:

codex exec --profile quality "Review the current changes"

프로필 파일의 위치:

$CODEX_HOME/<profile-name>.config.toml

기본 CODEX_HOME은 ~/.codex입니다.

최신 Codex 버전은 별도의 프로필 파일을 사용하며 더 이상 기존 [profiles.<name>] 표를 읽지 않습니다. 각 기존 프로필을 자체 <name>.config.toml 파일로 마이그레이션하세요.

4. 사용자 지정 헤더 및 고급 인증

4.1 표준 bearer 토큰

대부분의 서드 파티 서비스는 다음 구성으로 작동합니다.

[model_providers.third_party]
env_key = "THIRD_PARTY_API_KEY"

Codex는 환경에서 키를 읽고 공급자의 bearer 인증을 적용합니다.

4.2 사용자 지정 API-key 헤더

일부 서비스는 다음을 요구합니다.

x-api-key: <key>

env_http_headers을 사용하세요.

model_provider = "custom_header_provider"
model = "provider-model-id"

[model_providers.custom_header_provider]
name = "Custom Header Provider"
base_url = "https://provider.example.com/v1"
wire_api = "responses"
env_http_headers = { "x-api-key" = "VENDOR_API_KEY" }

VENDOR_API_KEY 값은 비밀 값 자체가 아니라 환경 변수 이름입니다.

export VENDOR_API_KEY="your API key"

4.3 정적 헤더 및 쿼리 매개변수

민감하지 않은 정적 헤더를 추가하세요.

http_headers = { "X-Client-Name" = "codex", "X-Environment" = "development" }

쿼리 매개변수를 추가하세요.

query_params = { "api-version" = "2026-08-01" }

실제 비밀 값을 http_headers에 넣지 마세요.

4.4 명령 기반 인증

엔터프라이즈 환경에서는 키체인, 클라우드 자격 증명 도우미 또는 내부 명령에서 단기 토큰을 가져올 수 있습니다.

[model_providers.corporate]
name = "Corporate Gateway"
base_url = "https://gateway.example.com/v1"
wire_api = "responses"

[model_providers.corporate.auth]
command = "/usr/local/bin/fetch-codex-token"
args = ["--audience", "codex"]
timeout_ms = 5000
refresh_interval_ms = 300000

명령은 표준 출력에 토큰만 출력해야 합니다.

다음 인증 방법을 함께 사용하지 마세요.

• [model_providers.<id>.auth]
• env_key
• experimental_bearer_token
• requires_openai_auth

4.5 프록시를 통해 OpenAI 인증 재사용하기

프록시가 계속 OpenAI 모델에 액세스하며 Codex가 공식 OpenAI 인증을 사용해야 하는 경우에만 다음을 설정하세요.

requires_openai_auth = true

이 설정은 일반적인 서드 파티 모델 API key에 적합하지 않습니다. 활성화하면 Codex는 공급자의 env_key을 무시합니다.

5. 문제 해결

5.1 CC Switch에서 공급자를 변경했지만 Codex가 여전히 이전 모델을 사용하는 경우

각 항목을 확인하세요.

1. 의도한 Codex 공급자가 CC Switch에서 활성화되어 있습니다.
2. 로컬 라우팅 마스터 스위치가 켜져 있습니다.
3. Routing Enabled에서 Codex가 활성화되어 있습니다.
4. Chat 또는 Messages 공급자에서 Needs Local Routing이 활성화되어 있습니다.
5. CC Switch가 계속 실행 중입니다.
6. Codex, IDE 또는 데스크톱 클라이언트를 완전히 다시 시작했습니다.
7. /debug-config에 예상한 구성 소스가 표시됩니다.

모델 매핑을 변경한 후 /model 메뉴가 카탈로그를 다시 불러올 수 있도록 Codex를 다시 시작하세요.

5.2 404, 400 또는 누락된 /responses 엔드포인트

일반적인 원인은 다음과 같습니다.

• Chat Completions 공급자를 기본 Responses 공급자로 취급함
• /v1을 잘못 추가하거나 제거함
• /chat/completions을 두 번 추가함
• 표준이 아닌 엔드포인트에 Full URL Mode를 활성화하지 않음
• 로컬 라우팅이 Codex를 인계하지 못함
• 서드 파티 게이트웨이의 불완전한 Responses 구현

CC Switch 사용자는 Upstream Format과 라우팅 로그를 검사해야 합니다. 직접 공급자 사용자는 <base_url>/responses을 curl으로 호출해야 합니다.

5.3 401 Unauthorized 또는 403 Forbidden

다음을 확인하세요.

• API key가 유효한지
• 올바른 리전, 프로젝트 또는 요금제에 속하는지
• 계정에 충분한 잔액과 권한이 있는지
• 서비스가 bearer 토큰 또는 x-api-key을 요구하는지
• 환경 변수 이름이 env_key과 정확히 일치하는지
• CC Switch에 올바른 키가 저장되었는지
• 프록시가 인증 헤더를 제거했는지

전체 키를 공유 로그에 출력하지 마세요.

bash / zsh:

printenv THIRD_PARTY_API_KEY

PowerShell:

$env:THIRD_PARTY_API_KEY

5.4 /model에 모델이 없는 경우

다음을 확인하세요.

• CC Switch Model Mapping에 정확한 업스트림 모델 ID가 포함되어 있는지
• 공급자가 저장되고 활성화되어 있는지
• Codex를 다시 시작했는지
• 수동 공급자에 유효한 model_catalog_json이 있는지
• 카탈로그 JSON이 유효한지
• 공급자가 모델 이름을 변경했거나 모델을 중단했는지

5.5 텍스트는 작동하지만 Codex가 파일 읽기, 코드 편집 또는 명령 실행을 할 수 없는 경우

가능한 원인:

• 모델의 도구 호출 능력이 부족함
• 업스트림이 함수 호출을 구현하지 않음
• 릴레이가 도구 호출 ID를 삭제함
• 스트리밍 도구 호출 조각이 올바르게 재조립되지 않음
• JSON Schema가 재작성됨
• 다음 턴에 도구 결과가 반환되지 않음
• 모델 컨텍스트가 너무 짧음
• 모델 카탈로그가 기능을 잘못 명시함

간단한 채팅 프롬프트 대신 실제 “읽기 → 편집 → 테스트 실행 → 실패 검사 → 수정” 루프를 테스트하세요.

5.6 스트리밍 연결이 자주 끊기는 경우

CC Switch 사용자는 먼저 로컬 라우팅 로그와 업스트림 응답을 검사해야 합니다. 일반적인 원인은 다음과 같습니다.

• 업스트림 대기열 또는 긴 추론 시간
• SSE를 신속하게 내보내지 않는 게이트웨이
• CDN, 리버스 프록시 또는 회사 네트워크의 버퍼링
• 표준이 아닌 업스트림 이벤트
• 특정 CC Switch 또는 공급자 버전의 호환성 문제

직접 공급자에서는 다음 값을 늘릴 수 있습니다.

request_max_retries = 4
stream_max_retries = 5
stream_idle_timeout_ms = 600000

제한 시간을 늘리면 네트워크 또는 느린 추론 문제를 완화할 수 있지만 잘못된 프로토콜 구현을 고칠 수는 없습니다.

5.7 wire_api = "chat" 때문에 Codex가 시작되지 않는 경우

이 값은 오래된 가이드에 등장합니다. 현재 Codex 구성은 다음만 지원합니다.

wire_api = "responses"

업스트림이 Chat Completions만 제공한다면 CC Switch를 사용하세요.

다음 명령으로 다른 오래된 필드를 확인하세요.

codex --strict-config

5.8 프로젝트 구성을 편집해도 공급자가 변경되지 않는 경우

공급자 설정은 다음 위치에 있어야 합니다.

~/.codex/config.toml

프로젝트 수준 .codex/config.toml은 model_provider 및 model_providers을 포함하여 요청을 리디렉션하거나 공급자 인증을 변경하는 필드를 재정의할 수 없습니다.

5.9 터미널에서는 작동하지만 IDE 확장 프로그램이 API key를 찾지 못하는 경우

GUI 애플리케이션은 기존 터미널에서 일시적으로 내보낸 변수를 상속하지 않는 경우가 많습니다.

가능한 방법:

• 변수가 설정된 터미널에서 IDE를 실행합니다.
• 운영 체제 사용자 환경에 변수를 영구적으로 설정합니다.
• IDE를 완전히 종료한 후 다시 엽니다.
• CC Switch를 사용하여 로컬 공급자 구성을 관리합니다.

5.10 전환 후 공식 로그인 또는 공식 기능이 작동하지 않는 경우

다음을 확인하세요.

• OpenAI Official을 다시 선택했는지
• Keep official login when switching third-party providers가 활성화되어 있는지
• 이전 워크플로가 ~/.codex/auth.json을 덮어썼는지
• codex login status이 성공하는지

필요하면 다시 로그인하세요.

codex login

액세스 토큰이 포함된 auth.json 파일을 공유하거나 수동으로 편집하지 마세요.

5.11 Web Search, 이미지 또는 기타 고급 기능이 작동하지 않는 경우

텍스트와 도구 호출을 지원하는 공급자가 모든 Codex 기능을 반드시 구현하는 것은 아닙니다.

사용자 지정 공급자는 기본적으로 독립형 Web Search 지원을 알리지 않습니다. 공급자, 모델 및 엔드포인트가 실제로 지원하는 경우에만 다음을 설정하세요.

supports_standalone_web_search = true

잘못 활성화하면 Codex가 업스트림에서 처리할 수 없는 요청을 보낼 뿐입니다. 이미지 입력, WebSockets, 응답 저장 및 기타 고급 기능을 별도로 검증하세요.

6. 통합 경로 선택하기

모든 통합을 다음 세 수준에서 검증하세요.

1. 연결성: 텍스트를 안정적으로 반환합니다.
2. 도구 사용: 파일을 읽고 명령을 실행하며 도구 결과에서 계속 진행할 수 있습니다.
3. 작업 완료: 편집, 테스트 및 수정 루프를 완료할 수 있습니다.

다음 사항도 검토하세요.

• 서드 파티 요금
• 속도 제한
• 소스 코드와 프롬프트가 기록되는지 여부
• 데이터 저장 리전
• 팀 또는 엔터프라이즈 규정 준수 요구 사항
• 모델 업그레이드에 회귀 테스트가 필요한지 여부

서드 파티 API key를 사용하면 해당 공급자 또는 릴레이에서 사용량에 대한 요금을 청구합니다. ChatGPT Plus, Pro 또는 Codex 구독에 포함된 할당량을 자동으로 소비하거나 공유하지 않습니다.

참고 자료

• Codex 구성 기본 사항
• Codex 고급 구성
• Codex 구성 참조
• Codex 인증
• Codex 개발자 명령
• Codex 모델
• CC Switch GitHub
• CC Switch 사용자 설명서
• CC Switch: 공급자 추가
• CC Switch: Codex 공식 로그인 유지