커스텀 프로바이더 (provider)를 연결했고, 터미널에서 codex가 잘 실행되는데도 Desktop 모델 피커 (model picker)가 마치 모델이 존재하지 않는 것처럼 동작하나요? 그 간극은 거의 대부분 API 키나 설정 구문 (config syntax)의 문제는 아닙니다. 이는 Desktop 클라이언트가 백엔드 (backend)에서 이미 로드한 모델들을 조용히 필터링하고 있기 때문입니다.

30초 진단

무언가를 다시 작성하기 전에, 증상을 표와 대조해 보세요. 대부분의 사람들은 해결책까지 단 한 줄만을 남겨두고 있습니다.

보이는 현상	실제 문제 원인	첫 번째 조치
피커에 모델 이름 없이 "Custom"만 표시됨	모델이 인라인 (inline)으로 설정됨, 카탈로그 메타데이터 (catalog metadata) 없음	해결책 1: 인라인 model을 유지하세요, 작동합니다
...

가장 빠른 확인 방법: 동일한 폴더에서 터미널을 열고 codex (CLI)를 실행한 다음, /model을 입력하세요. 만약 CLI에는 모델이 나열되는데 Desktop에는 나타나지 않는다면, 클라이언트 측 필터 버그 (client-side filter bug)를 겪고 있는 것이며, Desktop 측에서 설정을 아무리 수정해도 모델을 나타나게 할 수 없습니다. 해결책 1로 건너뛰세요.

flowchart TD
  A[Desktop에서 커스텀 모델 누락] --> B{CLI /model에서 보입니까?}
  B -- Yes --> C[Desktop 필터 버그 #19694]
...

이 해결책들을 적용해야 할 때 (그리고 대신 모델을 교체해야 할 때)

모델은 실행되지만 피커 (picker)에 표시되지 않을 때는 설정을 수정하세요. 그것은 디스플레이 문제이며, 다른 모든 것이 이미 작동하고 있기 때문에 10분의 시간을 투자할 가치가 있습니다. 구체적으로, CLI나 직접적인 curl 요청은 성공하지만 Desktop 드롭다운 (dropdown)에 모델이 나타나지 않는 경우가 이에 해당합니다. 이 경우 #19694 필터 또는 카탈로그 공백 (catalog gap) 문제를 겪고 있는 것이며, 해결책 1부터 4까지가 적용됩니다.

라우트 (route) 자체가 깨져 있는 경우에는 설정을 수정하는 대신 모델을 교체하세요. 만약 curl https://your-gateway/v1/responses 결과가 401, 404 또는 model-not-found로 돌아온다면, 피커는 문제가 아닙니다. 프로바이더 (provider) 또는 모델 문자열 (model string)이 잘못된 것이며, 해결되지 않는 라우트를 카탈로그 수정만으로는 살릴 수 없습니다.

그다음은 종료 조건입니다. 만약 당신의 유일한 목표가 커스텀 모델 (custom model)로 요청을 보내는 것이라면, 해결 방법 1(Fix 1)만으로 충분합니다. model을 인라인 (inline)으로 설정하고, 재시작하면 끝입니다. 이 가이드의 나머지 내용은 피커 (picker)가 깔끔하고 전환 가능한 목록을 표시하도록 만드는 것에 관한 것이며, 이는 팀 단위로 작업하거나 모델을 자주 교체하는 사용자에게 중요합니다. 만약 드롭다운 (dropdown)을 전혀 열지 않는다면, 해결 방법 1 이후에는 더 이상 진행하지 마세요.

Codex Desktop이 커스텀 모델을 숨기는 이유

네 가지의 뚜렷한 근본 원인이 있으며, 각각 다른 해결 방법이 필요합니다. 잘못된 원인을 파악하는 바람에 사람들이 이미 잘 작동하는 설정을 오후 내내 다시 입력하며 시간을 허비하곤 합니다.

근본 원인	피커가 모델을 숨기는 이유	해당되는 설정	해결 방법
데스크톱 클라이언트 측 필터 (Desktop client-side filter)	앱 서버 (app-server)가 model/list를 통해 모델을 반환하지만, 데스크톱 렌더러 (renderer)가 이를 누락함	카탈로그 (catalog)가 있는 모든 커스텀 프로바이더 (custom provider)	해결 방법 1 + 해결 방법 4
...

첫 번째 원인은 사람들을 놀라게 하는 부분입니다. 공개된 codex issue #19694에 따르면, 앱 서버 (app-server)는 카탈로그를 올바르게 로드하고 model/list 엔드포인트 (endpoint)를 통해 모델을 반환하지만, 데스크톱 UI (UI)가 추가 필터를 적용하여 피커를 렌더링하기 전에 로컬로 구성된 모델을 제거해 버립니다. 백엔드 (backend)는 당신의 모델을 알고 있습니다. 프론트엔드 (frontend)가 표시를 거부하는 것입니다. 이것은 설정 오류가 아니라 클라이언트 버그 (client bug)이며, 2026-04-26에 접수되어 이 글을 쓰는 시점에도 여전히 열려 있는 상태입니다.

두 번째 원인은 가장 흔하며 가장 덜 심각한 문제입니다. 만약 카탈로그 없이 model = "some-id"라고만 작성했다면, Codex는 해당 문자열은 가지고 있지만 표시 이름 (display name), 컨텍스트 윈도우 (context window), 기능 플래그 (capability flags)는 가지고 있지 않습니다. 피커는

세 번째 원인은 v3.16.5 이전의 cc-switch 사용자들이 겪었던 문제입니다. 커뮤니티는 이를 cc-switch issue #3668에서 추적했습니다. 생성된 카탈로그 (catalog)와 프로바이더 블록 (provider block)이 Codex의 피커 (picker)가 열거하는 내용과 일치하지 않았고, 이로 인해 라우팅 (routing)은 작동함에도 불구하고 서드파티 프로바이더 (third-party providers)에 대한 /model 결과가 빈 값으로 반환되었습니다. 수정 사항에 대한 자세한 내용은 해결 방법 4에서 다룹니다.

네 번째 원인은 명확한 징후가 있습니다. 만약 프로바이더 (provider)를 리포지토리 (repo)의 .codex/config.toml에 넣었다면, Codex는 시작 시 경고를 출력하고 해당 블록을 완전히 무시합니다. 프로바이더 정의 (provider definitions)는 사용자 범위 (user-scoped)로만 제한됩니다.

Codex가 모델을 로드하는 방식 (및 데스크톱 버전의 차이점)

Codex는 계층 구조로 모델 목록을 구축하며, 이 순서를 아는 것이 어떤 해결 방법이 실제로 적용될지를 알려줍니다. 세 가지 소스가 있습니다: 바이너리 (binary)에 포함된 카탈로그, OpenAI에서 가져오는 원격 카탈로그, 그리고 사용자의 로컬 model_catalog_json입니다. 로컬 파일이 우선권을 갖습니다. 로컬 파일은 시작 시 포함된 카탈로그와 원격 카탈로그를 모두 덮어쓰며, 이것이 올바른 model_catalog_json이 서드파티 모델을 위한 단순한 선택 사항이 아닌 실제 핵심 제어 수단인 이유입니다.

모두를 혼란스럽게 만드는 부분은 바로 여기입니다. Codex가 시작될 때, 앱 서버 (app-server)는 세 계층을 모두 읽고 이를 해결 (resolve)한 뒤, 그 결과를 내부 model/list 엔드포인트 (endpoint)를 통해 노출합니다. CLI는 해당 목록을 직접 렌더링(render)하므로 커스텀 모델이 나타납니다. 반면 데스크톱 앱은 동일한 목록을 추가적인 클라이언트 단계를 거쳐 렌더링하는데, 이슈 #19694에 따르면 이 단계에서 자체적인 허용 목록 (allowlist)을 적용하고 로컬로 설정된 항목들을 드롭다운에 도달하기 전에 삭제해 버립니다. 백엔드 (backend)는 동일하고 카탈로그도 동일하지만, 두 개의 서로 다른 피커 (picker)가 존재하는 것입니다. 이 단 하나의 차이점 때문에 CLI는 신뢰할 수 있는 탈출구 (escape hatch)가 되는 반면, 데스크톱은 그렇지 못한 것입니다.

주의해야 할 캐시(cache)도 있습니다. Codex는 ~/.codex/models_cache.json을 유지하며, 제공자(provider)를 전환하거나 카탈로그를 편집한 후에는 항상 동기화(resync)되지 않을 수 있습니다. 설정(config)이 올바른 상태임에도 불구하고, 오래된(stale) 캐시로 인해 이전 목록이 계속 표시되거나 빈 목록이 나타날 수 있습니다. 해당 파일을 삭제하면 다음 실행 시 깨끗하게 재구축(clean rebuild)되므로, 카탈로그 자체에 문제가 있다고 판단하기 전에 시도해 볼 가치가 있습니다.

해결 방법 (모든 설정에 대한 솔루션)

위에서부터 아래 순서대로 진행하세요. 해결 방법 1은 항상 작동하는 방법입니다. 뒤에 나오는 해결 방법들은 선택기(picker)를 보기 좋게 만들고 목록을 전환 가능하게 해줍니다.

해결 방법 1: 모델을 인라인(Inline)으로 설정하기 (신뢰할 수 있는 우회 방법)

이것은 #19694 스레드에서 합의된 우회 방법이며, 가장 먼저 시도해야 할 방법입니다. config.toml에 모델 문자열을 직접 입력하면 선택기(picker)에는 "Custom"이라고 표시됩니다.

# ~/.codex/config.toml   (프로젝트 폴더가 아닌 사용자 레벨)
model = "moonshotai/kimi-k2.7-code"
model_provider = "ofox"
...

키를 내보내기(export)하고 (shell profile에서 export OFOX_API_KEY=sk-...), Codex Desktop을 완전히 종료한 후 다시 여세요. 선택기에는 "Custom"이라고 표시되지만, 모든 요청은 moonshotai/kimi-k2.7-code로 전송됩니다. 만약 다른 모델을 지정하고 싶다면 문자열을 교체하세요. 동일한 게이트웨이(gateway)에 있는 다른 코딩 ID로는 deepseek/deepseek-v4-pro 또는 openai/gpt-5.3-codex가 있습니다. 세 모델 모두 하나의 키로 접근 가능합니다. 제공자(provider) 블록 자체에 대한 단계별 안내는 Codex CLI multi-provider setup via config.toml 가이드를 참조하세요.

wire_api에 관한 참고 사항: Codex는 2026년 2월 초에 기존의 chat/completions 경로를 제거했습니다 (discussion #7782 참조). 이제 responses가 유일하게 지원되는 값이며, 키가 생략될 경우의 기본값입니다. 여전히 wire_api = "chat"으로 설정된 프로바이더(Provider)는 시작 시 오류가 발생합니다. 실질적인 요구 사항은 게이트웨이가 {base_url}/responses에서 OpenAI 호환 Responses 엔드포인트를 노출해야 한다는 것입니다. ofox는 https://api.ofox.ai/v1/responses에서 이를 제공하므로, 여기서 wire_api = "responses"가 올바른 설정입니다. Codex가 /chat/completions만 지원하는 게이트웨이를 가리키게 되면 모든 요청이 404 오류를 발생시키는데, 이는 모델 문제처럼 보이지만 실제로는 프로토콜 불일치(protocol mismatch) 문제입니다. 전체 필드 목록은 Codex configuration reference에서 확인할 수 있습니다.

해결 방법 2: 선택기(Picker)에 표시되도록 모델 카탈로그 추가하기

드롭다운 메뉴에서 "Custom" 대신 실제 이름을 표시하고 싶다면 model_catalog_json이 필요합니다. 이는 시작 시 한 번 로드되는 JSON 파일로, 최상위에 models 배열을 포함합니다. 각 항목은 하나의 모델을 설명합니다.

# ~/.codex/config.toml 상단
model_catalog_json = "/Users/you/.codex/ofox-models.json"
model = "moonshotai/kimi-k2.7-code"
...

공식 codex models.json의 필드를 사용한 최소한의 카탈로그 항목은 다음과 같습니다:

{
  "models": [
    {
...

slug는 프로바이더로 전송하는 문자열과 일치해야 합니다. 공식 카탈로그는 모델당 훨씬 더 많은 필드(추론 수준, 도구 유형, 모달리티 플래그 등)를 포함하고 있으며, 전체 구조를 직접 작성하는 것은 까다롭습니다. 바로 이 점 때문에 다음 해결 방법이 존재합니다. 카탈로그를 변경한 후에는 Desktop을 재시작하십시오. 이 레이어는 번들(bundled) 카탈로그와 원격(remote) 카탈로그를 모두 덮어쓰며, 시작 시에만 다시 읽으므로 스레드별(per-thread) 설정 변경으로는 다시 적용되지 않습니다.

해결 방법 3: 프로바이더를 사용자 수준 설정(User-Level Config)으로 이동

만약 Codex가 무시된 프로바이더 설정에 대해 시작 경고(startup warning)를 출력한다면, 프로바이더 블록이 잘못된 파일에 위치한 것입니다. model_provider와 model_providers는 오직 ~/.codex/config.toml에서만 작동합니다. 리포지토리(repo)의 .codex/config.toml은 프로바이더를 정의할 수 없습니다. 프로젝트 로컬의 model_catalog_json은 별개의 사례입니다. 설계상으로는 여전히 읽혀야 하지만, 새로운 Desktop 스레드에서는 현재 읽히지 않고 있으며, 이는 의도된 동작이 아닌 알려진 버그(#26308)입니다.

# 프로바이더가 실제로 어디에 있는지 확인
grep -rn "model_providers" ~/.codex/config.toml ./.codex/config.toml 2>/dev/null
# 만약 ./.codex/config.toml에 있다면, [model_providers.*] 블록을 이동시키세요
...

지침(instructions) 파일과 같이 리포지토리별로 특화된 항목들은 프로젝트 설정에 유지하세요. 프로바이더와 모델 카탈로그(model catalog)는 사용자 수준(user-level)으로 유지해야 합니다.

해결 방법 4: cc-switch v3.16.5를 사용하여 카탈로그 생성하기

cc-switch를 통해 Codex를 관리하는 경우, v3.16.5 또는 그 이상의 버전으로 업데이트하세요. 해당 릴리스는 네이티브 프로바이더(native providers)에 대해 선택기(picker)가 비어 있는 문제를 해결한 버전입니다. 이 버전은 네이티브 Responses 엔드포인트(apiFormat: "openai_responses")를 사용하는 공급업체를 위해 ~/.codex/cc-switch-model-catalog.json을 생성하며, 이를 통해 Codex Desktop이 실제로 모델을 인식하고 내장 도구(built-in tools)를 사용할 수 있게 됩니다.

업데이트 후 다음 두 가지 작업을 수행하지 않으면 아무것도 변경되지 않습니다:

1. 각 네이티브 프로바이더를 한 번씩 다시 저장하세요. 카탈로그는 저장할 때만 다시 생성됩니다. 기존 프로바이더는 열어서 다시 저장하기 전까지 이전의 (손상된) 상태를 유지합니다. 자동 마이그레이션은 제공되지 않습니다.
2. 디커플링(decoupling, 분리)을 이해하세요. v3.16.5에서는 모델 카탈로그가 더 이상 "로컬 라우팅(local routing)" 토글에 종속되지 않습니다. 네이티브 Responses 공급업체는 로컬 라우팅 활성화 여부와 관계없이 카탈로그를 생성하는 반면, Chat-format 공급업체는 이전과 같이 프록시 변환(proxy conversion) 과정을 거칩니다.

다시 저장한 후 카탈로그가 존재하며 모델 목록이 표시되는지 확인

cat ~/.codex/cc-switch-model-catalog.json | grep -o '"slug":[^,]*'

만약 결과가 비어 있다면, cc-switch에서 공급업체(provider)를 다시 저장하고 다시 확인하십시오.

cc-switch 자체에서 비활성화하는 주의 사항이 하나 있습니다. 몇몇 퍼스트 파티(first-party) 중국 모델(MiMo, LongCat, MiniMax, Qwen3-Coder)은 게이트웨이(gateway)에서 OpenAI의 내장 web_search를 지원하지 않습니다. 따라서 v3.16.5 버전은 Codex가 하드 400(hard 400) 에러를 발생시키는 것을 방지하기 위해 해당 모델들에 대해 이 도구를 기본적으로 꺼둡니다. 만약 이러한 모델들을 게이트웨이를 통해 라우팅(route)한다면, 웹 검색 기능이 꺼져 있을 것임을 예상해야 합니다.

선택기(Picker) 버그와 유사하게 나타나는 일반적인 설정 오류

"커스텀 모델이 표시되지 않는다"는 보고의 절반은 사실 디스플레이의 탈을 쓴 고장 난 경로(route) 문제입니다. 카탈로그를 건드리기 전에 다음 사항들을 먼저 배제하십시오. 각 오류는 마치 선택기가 모델을 숨기고 있는 것처럼 보이는 증상을 유발하지만, 실제로는 요청이 전달될 기회조차 없었던 상황입니다.

증상	실제 원인	해결 방법
시작 오류, 또는 모든 요청이 404 에러 발생	wire_api = "chat" (2026년 2월 삭제됨) 또는 /responses 엔드포인트가 없는 게이트웨이	wire_api = "responses"로 설정하고 Responses 기능이 가능한 게이트웨이를 지정하십시오
...

이러한 오류들을 실제 #19694 필터 문제와 구분하는 결정적인 방법은 단 하나의 명령어로 확인 가능합니다: CLI에서 동일한 요청을 실행해 보십시오. 만약 CLI에서도 실패한다면, 그것은 Desktop 선택기 문제가 아니라 위의 오류 중 하나이며, 카탈로그를 수정해도 해결되지 않습니다. 만약 CLI에서는 성공하는데 Desktop에서만 보이지 않는다면, 그것은 필터 문제이므로 다시 해결 방법 1과 해결 방법 4를 시도해야 합니다.

알려진 Codex Desktop 커스텀 모델 문제 (2026년 타임라인)

이것은 단 하나의 버그가 아닙니다. Codex 앱과 설정을 작성하는 도구들 사이에서 발생하는 연관된 문제들의 집합체입니다. 자신이 어떤 문제를 겪고 있는지 파악하면 잘못된 해결 방법을 적용하는 것을 방지할 수 있습니다.