개발 도구 연결

ChatGPT 및 Codex에 타사 API 연결하기: config.toml 완벽 설정 가이드

~/.codex/config.toml 파일을 수정하여 Codex 및 ChatGPT CLI에 맞춤형 공급자를 연동합니다. wire_api responses 필수 규격, auth.json 설정, CC Switch 연동 및 오류 해결을 다룹니다.

config.toml 수정 전 준비 사항

OpenAI Codex CLI와 데스크톱 앱은 코드 생성 및 저장소 자동 리팩터링을 위한 강력한 에이전트 환경을 제공합니다. config.toml에 맞춤형 모델 공급자를 설정하면 Codex의 모든 트래픽을 독립적인 API Route 게이트웨이로 전송하여 요금 페이지에 있는 GPT-5 시리즈, Claude Sonnet, DeepSeek 등 모델을 사용하고 호출을 감사할 수 있습니다. 날짜가 있는 Claude 요금 비교는 블로그에 있으며, 이 글은 절감 비율을 말하지 않습니다.

설정을 시작하기 전에 API 연결에서 유효한 API Route 키를 복사하고, 요금 페이지에서 대상 모델의 활성화 상태와 가격 그룹을 확인하세요. 공식 인터페이스 규격은 표준 OpenAI Chat Completions 규격과 함께 대조해 볼 수 있습니다.

프로토콜 핵심: wire_api를 반드시 responses로 지정해야 하는 이유

최신 버전의 Codex에서 가장 중요한 변경 사항은 레거시 Chat Completions 프로토콜이 완전히 지원 중단되었다는 점입니다. config.toml의 공급자 설정 블록에서는 반드시 wire_api = "responses"를 지정해야 합니다. 이전 방식인 wire_api = "chat"을 입력하면 Codex 실행 시 지원되지 않는 프로토콜 예외가 발생하며 즉시 중단됩니다.

Codex는 도구 호출, 에이전트 단계 동기화, 로컬 작업 공간의 실시간 반영을 위해 OpenAI의 상태 기반 Responses API 규격을 필수적으로 요구합니다. API Route는 Responses API 프로토콜 변환을 자체적으로 지원하므로 별도의 변환 프록시 없이도 원활하게 동작합니다.

Codex 공급자 설정 주요 항목 정리
설정 키지정값 / 권장값기술 설명 및 주의점
model_provider"api_route"Codex 실행 시 기본으로 활성화할 공급자 식별자를 지정합니다.
base_url"https://global.api-route.com/v1"게이트웨이 호출 주소입니다. 반드시 끝에 /v1을 포함하고 후행 슬래시는 제거하세요.
wire_api"responses"필수 프로토콜 형식입니다. 최신 Codex CLI에서는 "chat" 형식이 완전히 제거되었습니다.
requires_openai_authtrueOpenAI 표준 규격에 맞춘 Bearer 인증 헤더를 전송하도록 지시합니다.
disable_response_storagetrue외부 서버에 세션 기록이 남지 않도록 방지하는 보안 옵션입니다.

주의할 점은 보안 격리 정책으로 인해 프로젝트 로컬 경로의 .codex/config.toml에 작성된 공급자 블록은 Codex가 완전히 무시한다는 것입니다. 모든 맞춤형 공급자는 사용자 홈 디렉터리의 전역 설정 파일에 작성해야 합니다.

단계별 실습: config.toml 및 auth.json 수정하기

Codex의 환경 설정 파일은 운영체제별로 다음 위치에 저장됩니다:

  • macOS / Linux: ~/.codex/config.toml 및 ~/.codex/auth.json
  • Windows: %USERPROFILE%\.codex\config.toml 및 %USERPROFILE%\.codex\auth.json

먼저 디렉터리를 생성하고, 편집기를 열기 전에 기존 설정을 백업합니다:

mkdir -p ~/.codex
test -f ~/.codex/config.toml && cp ~/.codex/config.toml ~/.codex/config.toml.bak
nano ~/.codex/config.toml

~/.codex/config.toml의 전체 내용을 아래의 공급자 설정으로 완전히 교체합니다:

# ~/.codex/config.toml
model_provider = "api_route"
model = "gpt-5.6-sol"
disable_response_storage = true

[model_providers.api_route]
name = "API Route"
base_url = "https://global.api-route.com/v1"
wire_api = "responses"
requires_openai_auth = true
supports_websockets = false

이어서 발급받은 API Route 키를 ~/.codex/auth.json에 저장합니다. Codex는 이 파일의 OPENAI_API_KEY를 인증 토큰으로 읽어옵니다:

{
  "OPENAI_API_KEY": "sk-your-api-route-key"
}

Linux나 macOS 환경에서는 보안을 위해 파일 접근 권한을 현재 사용자로 제한하는 것이 안전합니다:

chmod 600 ~/.codex/config.toml
chmod 600 ~/.codex/auth.json

Linux 환경의 추가적인 설정 팁은 Codex 사용자 지정 공급자 가이드에서도 확인할 수 있습니다.

GUI 방식: CC Switch 데스크톱 앱으로 간편하게 연동하기

TOML 파일을 직접 편집하는 대신 시각적인 UI를 선호한다면 오픈소스 도구인 CC Switch를 사용하는 것이 편리합니다. Codex, Claude Code 등 여러 CLI 도구의 공급자 프로필을 클릭 한 번으로 전환할 수 있습니다.

  1. API Route에 로그인한 뒤 API 연결에서 키, 모델, 연결 노드를 선택합니다.
  2. 대상 애플리케이션으로 Codex를 선택하고 연결 방식을 CC Switch로 유지합니다.
  3. 로컬에서 CC Switch 앱이 실행 중인지 확인한 후 “CC Switch로 가져오기”를 클릭합니다.
  4. CC Switch 앱의 Codex 공급자 목록에서 방금 가져온 api-route를 “사용 중”으로 활성화합니다.
  5. Codex 앱을 재시작하면 좌측 하단에 api-route 공급자 태그가 표시됩니다.

CC Switch는 내부적으로 상기 규격의 config.toml 및 auth.json을 자동으로 정확하게 작성하므로 오타나 들여쓰기 오류를 방지할 수 있습니다.

연결 확인 및 오류 해결 진단 매트릭스

설정을 마친 후 터미널에서 Codex 내장 진단 명령어를 실행하여 정상 작동 여부를 확인합니다:

codex doctor
codex "Reply in one sentence: What model are you?"

실행 중 오류가 발생할 경우 아래 매트릭스를 참고하여 조치하세요:

Codex CLI 맞춤형 공급자 오류 진단 표
오류 증상원인 분석확인 및 조치 방법
Unsupported wire_api errorconfig.toml에 wire_api = "chat"으로 잘못 기재wire_api = "responses"로 수정하세요. 최신 버전은 chat 규격을 거부합니다.
401 Unauthorizedauth.json의 키 누락 또는 오타~/.codex/auth.json의 키 이름이 OPENAI_API_KEY인지 확인하고 유효한 API 키를 입력하세요.
404 Not Foundbase_url 주소에 /v1이 빠졌거나 경로 오류base_url이 https://global.api-route.com/v1 형식인지 확인하고 끝에 슬래시를 넣지 마세요.
설정이 무시되고 공식 서버로 연결됨프로젝트 로컬 폴더의 .codex에 파일 작성사용자 홈 경로 ~/.codex/config.toml로 파일을 이동하세요. 로컬 공급자 설정은 차단됩니다.
403 Forbidden / 모델 접근 불가선택한 model이 키의 가격 그룹에 포함되지 않음/v1/models로 접근 가능한 모델 목록을 조회하거나 API 연결에서 그룹 권한을 점검하세요.

테스트 요청을 보낸 후에는 호출 로그에서 실제 토큰 차감 내역과 응답 시간을 확인하세요.

운영 배포 전 점검 체크리스트

  1. 기존 설정 백업: 유사시 공식 OpenAI 서버로 즉시 롤백할 수 있도록 config.toml.bak을 보관합니다.
  2. 무료 크레딧 활용: 회원가입 시 지급되는 $0.20 테스트 크레딧으로 빠른 시작 가이드에 따라 소액 검증을 먼저 진행합니다.
  3. 명시적 모델 고정: model = "..." 항목에 gpt-5.6-sol과 같이 검증된 모델명을 명확히 지정합니다.
  4. 보안 파일 보호: ~/.codex/auth.json 파일이 깃허브 공개 저장소에 커밋되지 않도록 주의합니다.
  5. 로그 주기적 대조: 대규모 코드 생성 작업 후에는 호출 로그를 열어 실제 청구 금액을 확인합니다.

이 가이드에 따라 설정을 완료하면 최신 Responses API의 에이전트 성능을 그대로 유지하면서 API Route의 합리적인 종량제 요금 혜택을 누릴 수 있습니다.