~/.codex/config.toml을 사용합니다. AIHubMix를 연동하면 단일 API 키만으로 GLM, Claude, Gemini, DeepSeek 등 여러 벤더의 모델을 호출할 수 있어 특정 벤더에 묶이지 않습니다. 이 문서는 두 가지 방식을 다룹니다: 기본 방식(고정된 단일 모델, 가장 빠른 시작)과 사용자 지정 모델 방식(model_catalog_json 카탈로그 파일로 /model 목록에서 언제든 전환).
설치
공식 웹사이트에서 다운로드(macOS 버전)
https://openai.com/en/codex/명령줄로 설치
기본 설정
설정 파일로 설정하기
~/.codex/config.toml설정 파일에 다음 설정을 추가합니다:
env_key에 지정한 환경 변수에 AIHubMix API 키를 설정합니다(=양쪽에 공백이 없도록 주의):
~/.zshrc / ~/.bashrc에 작성하여 영구화하는 것을 권장합니다. AIHubMix 콘솔에서 Key를 발급받으세요.
사용자 지정 provider는 기본적으로
~/.codex/auth.json의 OPENAI_API_KEY를 읽지 않습니다. 키는 반드시 env_key에 지정한 환경 변수로 전달해야 하며, 그렇지 않으면 요청에 키가 포함되지 않아 401이 반환됩니다.model은 AIHubMix의 다른 모델 ID로 바꿀 수 있습니다. 다만 GLM, Claude 같은 OpenAI 외 모델로 바꾸면 Codex가 Model metadata for ... not found를 표시하고 기본값으로 폴백하므로, 이런 경우에는 아래의 사용자 지정 모델 방식을 사용하세요.
cc-switch로 설정하기
- CC-Switch를 실행하고 공급자를 추가합니다.

- 프리셋 목록에서 「AiHubMix」를 선택합니다.

- 「API Key」 칸에 키를 입력하고 「추가」를 클릭하여 설정을 저장합니다.

- 홈 화면으로 돌아가 공급자 목록에서 「AiHubMix」를 선택하고 「활성화」를 클릭하면 바로 사용할 수 있습니다.

Codex 사용하기
터미널에서 사용하기
- 터미널을 열고 프로젝트 디렉토리로 이동한 다음
codex명령을 실행합니다.
-
필요에 따라 권한을 설정합니다. 이후 언제든
/permissions로 변경할 수 있습니다. -
필요에 따라 사용할 모델을 선택합니다. 하단 상태 표시줄에 현재 모델이 표시되며,
/model로 전환할 수 있습니다.

- 자연어로 요청을 입력해 정상적으로 응답하면 설정이 완료된 것입니다.

Codex 데스크톱 앱에서 사용하기
- Codex 데스크톱 앱을 열고 작업 디렉토리를 선택합니다.
- 입력창에 작업을 입력해 정상적으로 응답하면 설정이 완료된 것입니다.

유용한 명령 참조
전체 목록은codex --help를 참고하세요. 자주 쓰는 명령과 옵션은 다음과 같습니다:
Codex에서 사용자 지정 모델 사용하기
Codex는 기본적으로/model 목록에 OpenAI 공식 모델만 표시합니다. 목록에서 AIHubMix의 임의의 모델(GLM, Claude, Gemini, DeepSeek, Kimi, Qwen……)을 직접 선택하고 싶다면, 공식적으로 지원되는 「사용자 지정 모델」 메커니즘을 사용할 수 있습니다: 로컬 JSON 파일(model_catalog_json)을 통해 선택 가능한 모델을 선언하고, [model_providers.aihubmix]로 요청을 AIHubMix로 향하게 하는 방식입니다.
공식 설명: Advanced Configuration · Custom model providers
두 가지 연동 방식
이 페이지 앞부분의 「기본 설정」에서 다룬 것은 기본 방식이고, 이 절에서 다루는 것은 사용자 지정 모델 방식입니다. 차이는 다음과 같으니 필요에 따라 선택하세요:
전체 과정은 4단계뿐입니다: 목록 파일 생성 →
config.toml 수정 → 환경 변수 설정 → 재시작 후 모델 선택.
1단계: 모델 목록 파일 생성
목록 파일은{ "models": [ ... ] } 구조이며, 배열의 각 요소는 /model에서 선택할 수 있는 하나의 모델을 설명합니다. 아래에서는 먼저 하나의 고정 모델로 필드를 설명한 뒤, 상위 30개를 일괄 생성하는 스크립트를 제공합니다.
1.1 먼저 형식 이해하기: 모델 하나 고정
다음은 Codex가 파싱할 수 있음이 검증된 최소 완전 목록(glm-5.2 한 모델만 포함)입니다. 그대로 ~/.codex/model-catalogs/custom-models.json으로 저장하면 바로 사용할 수 있습니다. 더 많은 모델을 원한다면 models 배열에 동일한 구조의 항목을 계속 추가하세요.
base_instructions에 대하여: 이것은 해당 모델의 시스템 프롬프트입니다. 예시에서는 한 문장으로 자리만 채웠으며, 모델은 정상적으로 동작합니다. 네이티브 Codex에 가장 가까운 코딩 성능을 원한다면, codex debug models --bundled에 있는 임의의 내장 모델의 완전한 base_instructions로 교체하세요(다음 절의 일괄 스크립트가 바로 이렇게 합니다).
공식 목록은 snake_case 필드(
display_name, supported_in_api, visibility)를 사용합니다. 두 가지 오류 모두 목록 전체를 폐기시켜 /model에 모델이 보이지 않게 합니다: 필수 필드가 빠지면 missing field ...가 발생하고, displayName, hidden 같은 camelCase 구형식이나 인식되지 않는 값을 사용하면 unknown variant ...가 발생합니다. 본문의 이 필드 세트를 기준으로 하면 피할 수 있습니다.1.2 상위 30개 일괄 생성
여러 항목을 직접 손으로 작성하면 필드를 누락하기 쉽습니다. AIHubMix 모델 목록 API의 상위 30개 LLM을 한 번에 목록에 작성하려면 아래 스크립트를 사용하세요. 이 스크립트는 하나의 내장 모델을 템플릿으로 복제하므로 필수 필드(올바른base_instructions 포함)가 처음부터 완비되어 있어 Codex 버전이 달라도 누락되지 않습니다. curl, python3 및 설치된 codex CLI가 필요합니다:
slug, display_name, description, context_window 등)만 덮어쓰고 추론 단계를 low / medium / high로 제한하며, 나머지 필수 필드는 모두 내장 템플릿에서 복제합니다. 이것이 바로 1.1의 그 필드 세트이며, 다만 base_instructions는 완전한 공식 프롬프트를 사용합니다.
생성된 파일은 비교적 큽니다(각 항목이 완전한base_instructions를 포함하여 약 1~2 MB). 이는 정상적인 현상입니다. 실행 후codex debug models로 올바르게 파싱되는지 검증하세요(5단계 참조).
스크립트의image_generation필터 줄은 의도적으로 남겨둔 것입니다:type=llm응답 중 극소수 모델이image_generation태그를 동시에 갖고 있어(예:gemini-3.1-flash-image) 대화에 적합하지 않으므로, 스크립트가 자동으로 건너뛴 후 상위 30개를 취합니다.
2단계: config.toml 수정
~/.codex/config.toml을 편집하여 루트 레벨에 model_catalog_json을 추가하고 aihubmix provider를 정의합니다:
wire_api는 이제 responses만 지원하며(생략해도 기본값이 responses), chat은 더 이상 지원되지 않습니다. Codex는 OpenAI의 Responses API(/v1/responses)만 사용하며, AIHubMix는 이미 Responses API를 네이티브로 호환하므로 https://aihubmix.com/v1을 직접 가리키기만 하면 되고 별도의 변환 프록시를 구축할 필요가 없습니다.model에는 목록에 있는 모델을 지정해야 합니다. 1.1의 수동 목록이라면 glm-5.2를 쓰면 됩니다. 1.2의 스크립트를 사용했다면 목록에는 API의 현재 상위 30개 모델이 들어가며, 이 목록은 바뀝니다. 먼저 codex debug models | grep -o '"slug":"[^"]*"'로 확인한 뒤 그중에서 고르세요(이 글에서는 claude-opus-5-5 사용).
설정을 마치면 config.toml은 대략 다음과 같습니다(빨간 박스는 이 단계의 핵심 항목: 루트 레벨의 model / model_provider / model_catalog_json 및 [model_providers.aihubmix] 섹션):

3단계: 환경 변수 설정
위env_key에서 지정한 환경 변수를 설정하세요(= 양쪽에 공백이 없도록 주의):
~/.zshrc / ~/.bashrc에 작성하여 영구화하는 것을 권장합니다. AIHubMix 콘솔에서 Key를 발급받으세요.
4단계: 재시작 후 모델 선택
Codex App / TUI를 재시작하여 목록 파일을 적용한 다음:/model을 입력하면 목록에 선언된 모든 모델이 나열됩니다. 방향키로 선택하고 Enter로 확정하세요:

/model에서 추론 단계(effort)도 선택할 수 있습니다. 필요에 따라 low / medium / high를 선택하면 됩니다.

5단계: 적용 여부 검증
- Codex에 진입한 후
/model을 입력하여 목록에 선언된 모델이 보이는지 확인하고, 그중 하나(예:claude-opus-5-5)로 전환합니다. - 아무 질문이나 던져 연결이 통하는지 검증합니다. 주의: 「너는 어떤 모델이니」로 판단하지 마세요.
base_instructions에 「You are Codex… based on GPT-5」라고 쓰여 있어 모든 모델이 이대로 GPT-5라고 자칭하므로, 물어봐도 실제 모델을 구분할 수 없습니다. 실제로 호출된 모델을 확인하려면 AIHubMix 콘솔의 「로그」 페이지에서 해당 요청 기록의model_id를 확인하세요. 이것이 진실입니다.
Model changed to ...가 표시되고, 하단 상태 표시줄에도 현재 모델과 컨텍스트 윈도우가 표시됩니다(아래 그림은 claude-opus-5-5로 전환했으며, 윈도우 950K):

사용자 지정 모델 자주 묻는 질문
-
시작 시
legacy profile = "..." config is no longer supported오류가 발생합니다. Codex 0.134.0부터profile =과[profiles.xxx]는 더 이상 지원되지 않습니다. 두 부분을 모두 삭제하고 위의 「기본 설정」대로 설정을 다시 작성하세요. - 이전 스크립트로 목록을 생성한 경우. 이전 스크립트는 내장 템플릿의 code mode를 끄지 않았습니다. Codex가 업데이트되면서 첫 번째 내장 모델이 gpt-6 시리즈로 바뀌었기 때문에, 생성된 목록은 정상적으로 파싱되지만 요청에 표준 tools 목록이 포함되지 않습니다. 1단계의 새 스크립트로 목록을 다시 생성하세요.
-
/model에 사용자 지정 모델이 보이지 않나요? 다음 순서대로 점검하세요:- 먼저
codex debug models를 실행하세요.missing field ...(가장 흔함, 필수 필드 누락)나unknown variant ...(필드명/값이 잘못됨)가 발생하면 목록 전체가 파싱에 실패해 폐기된 것입니다. 1단계의 「내장 템플릿 복제」 스크립트로 다시 생성하면 됩니다. model_catalog_json이config.toml의 루트 레벨에 작성되었는지,[model_providers.*]섹션 안에 있지 않은지 확인하세요;- JSON이 snake_case 공식 필드를 사용하는지,
visibility가list인지 확인하세요; codex debug models에서는 이미 모든 모델이 보이지만 **데스크톱 앱(Desktop App)**에서는 한두 개만 남고 현재 모델이 「사용자 지정」으로 표시된다면, 이는 데스크톱 앱의 알려진 버그입니다: 로컬 목록 위에 공식 slug 화이트리스트 필터를 한 겹 더 씌워서 비공식 모델을 선택기에서 제거합니다(GitHub Issue #19694, #15138 참조). 이때 모델은 사실 여전히config.toml의model = "..."에 따라 정상적으로 호출되며(AIHubMix 로그로 확인 가능), 단지 이름이 표시되지 않을 뿐입니다. 올바르게 표시하려면 터미널codexCLI / TUI를 사용하세요. 데스크톱 앱은config.toml에model = "원하는 모델"을 고정으로 작성하는 수밖에 없으며, 공식 수정을 기다려야 합니다.
- 먼저
-
목록은 「병합」이 아니라 「교체」입니다.
model_catalog_json은 모델 목록 전체를 교체하며 추가하지 않습니다(실측: 목록에 모델 2개만 넣으면codex debug models에 그 2개만 남고 내장gpt-5.x가 전부 사라짐). 두 종류 모두 원한다면 함께 사용자 지정 목록에 작성하세요. -
요청에서 프로토콜 오류 발생 / 연결 불가. 대부분 provider의
base_url또는wire_api가 잘못 짝지어진 경우입니다. AIHubMix는 반드시wire_api = "responses"+base_url = "https://aihubmix.com/v1"이어야 합니다. Chat Completions만 지원하는 서드파티에 연결하는 경우 로컬 변환 프록시가 필요하지만, AIHubMix 사용자는 이 단계가 필요 없습니다. -
“Reconnecting”이 계속되다가 오류로 끝납니다. 먼저 마지막 오류 줄을 확인하세요.
401 Unauthorized는 요청에 키가 포함되지 않았다는 뜻입니다. provider 섹션에env_key가 설정되어 있는지, 그리고 Codex를 시작하는 터미널에서 해당 환경 변수가 적용되어 있는지 확인하세요(새 터미널을 열거나source ~/.zshrc실행).auth.json에만 있는 키는 사용자 지정 provider에서 사용되지 않습니다. -
파싱에서
missing field ...(예:missing field base_instructions) 발생. 항목에 필수 필드가 빠진 것입니다. 최신 버전 Codex는 엄격하게 파싱하므로base_instructions,availability_nux,upgrade,supports_reasoning_summaries,support_verbosity,default_verbosity,apply_patch_tool_type,truncation_policy,supports_parallel_tool_calls,experimental_supported_tools등이 모두 존재해야 합니다. 1단계의 「내장 템플릿 복제」 스크립트로 한 번에 채울 수 있습니다. -
파싱에서
unknown variant발생. 목록 JSON에 Codex가 인식하지 못하는 필드명이나 값이 있습니다(흔히displayName/hidden등 camelCase 구형식). 본문의 snake_case 필드 세트로 바꾸면 됩니다.
참고 문서
- 공식 문서: Advanced Configuration | Configuration Reference
- 공식 내장 목록 형식 참고: codex-rs/models-manager/models.json
- 커뮤니티 가이드: Codex config.toml: 6줄로 임의의 사용자 지정 provider 연동하기
마지막 업데이트: 2026-10-15