model_catalog_json 카탈로그 파일로 /model 목록에서 언제든 전환).
OpenAI Codex CLI 통합
AiHubMix는 OpenAI Codex CLI와의 원활한 통합을 제공하여 명령줄 환경에서 직접 고급 AI 프로그래밍 지원을 활용할 수 있도록 합니다. 간단한 구성 단계를 통해 자연어를 사용하여 터미널에서 다양한 프로그래밍 및 시스템 작업을 수행할 수 있습니다.사용하기 전에 다음 명령을 실행하여 설치하거나 업데이트하십시오:
구성 단계
1. 환경 변수 설정
셸 구성 파일(예:.zshrc 또는 .bashrc)을 열고 다음 환경 변수를 추가합니다:
2. 구성 변경 사항 적용
터미널에서 다음 명령을 실행하여 환경 변수를 적용합니다:3. Codex CLI 실행
프로젝트 디렉토리로 이동하여codex 명령을 실행합니다:

4. 자연어를 사용하여 작업 실행
이제 다음과 같이 자연어를 사용하여 Codex CLI에 지침을 입력할 수 있습니다:
고급 구성
유용한 명령 참조
도움말 명령
전체 명령 옵션
Codex에서 사용자 지정 모델 사용하기
Codex는 기본적으로/model 목록에 OpenAI 공식 모델만 표시합니다. 목록에서 AIHubMix의 임의의 모델(GLM, Claude, Gemini, DeepSeek, Kimi, Qwen……)을 직접 선택하고 싶다면, 공식적으로 지원되는 「사용자 지정 모델」 메커니즘을 사용할 수 있습니다: 로컬 JSON 파일(model_catalog_json)을 통해 선택 가능한 모델을 선언하고, [model_providers.aihubmix]로 요청을 AIHubMix로 향하게 하는 방식입니다.
공식 설명: Advanced Configuration · OSS mode / local providers
두 가지 연동 방식
이 페이지 앞부분의 「환경 변수 설정」에서 다룬 것은 기본 방식이고, 이 절에서 다루는 것은 사용자 지정 모델 방식입니다. 차이는 다음과 같으니 필요에 따라 선택하세요:| 기본 방식(profile + 단일 모델) | 사용자 지정 모델 방식(이 절) | |
|---|---|---|
| 설정 내용 | config.toml에 model = "xxx"를 고정으로 작성 | 추가로 model_catalog_json 목록 파일을 유지 관리 |
| 모델 전환 | 설정 파일을 수정한 뒤 재시작 | /model 목록에서 바로 선택, 언제든 전환 가능 |
| 적합한 상황 | 장기간 특정 모델 하나를 고정으로 사용 | 여러 모델을 자주 비교 / 전환하고 싶을 때 |
| 복잡도 | 낮음 | 중간 |
config.toml 수정 → 환경 변수 설정 → 재시작 후 모델 선택.
1단계: 모델 목록 파일 생성
목록 파일은{ "models": [ ... ] } 구조이며, 배열의 각 요소는 /model에서 선택할 수 있는 하나의 모델을 설명합니다. 아래에서는 먼저 하나의 고정 모델로 필드를 설명한 뒤, 상위 30개를 일괄 생성하는 스크립트를 제공합니다.
1.1 먼저 형식 이해하기: 모델 하나 고정
다음은 Codex가 파싱할 수 있음이 검증된 최소 완전 목록(glm-5.2 한 모델만 포함)입니다. 그대로 ~/.codex/model-catalogs/custom-models.json으로 저장하면 바로 사용할 수 있습니다. 더 많은 모델을 원한다면 models 배열에 동일한 구조의 항목을 계속 추가하세요.
| 필드 | 역할 | API 출처 |
|---|---|---|
slug | 모델 ID. Codex가 이것으로 요청을 보내며, 반드시 API가 반환하는 model_id와 일치해야 함 | model_id |
display_name | /model 목록에 표시되는 이름 | model_name |
context_window / max_context_window | 컨텍스트 윈도우. 작성하지 않으면 매우 작은 보수적 기본값으로 폴백됨. API의 실제 값에 맞춰 작성하는 것을 권장 | context_length |
supported_reasoning_levels | 추론 단계. 모델 전환 후에도 /model로 effort를 선택할 수 있음 | — |
visibility | list로 설정해야 선택기에 나타남 | — |
priority | 목록 정렬. 숫자가 작을수록 앞에 위치 | — |
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 등)만 덮어쓰고, 나머지 필수 필드는 모두 내장 템플릿에서 복제합니다. 이것이 바로 1.1의 그 필드 세트이며, 다만 base_instructions는 완전한 공식 프롬프트를 사용합니다.
생성된 파일은 비교적 큽니다(각 항목이 완전한base_instructions를 포함하여 약 1~2 MB). 이는 정상적인 현상입니다. 실행 후codex debug models로 올바르게 파싱되는지 검증하세요(5단계 참조).
스크립트의image_generation필터 줄은 의도적으로 남겨둔 것입니다:type=llm응답 중 극소수 모델이image_generation태그를 동시에 갖고 있어(예:gpt-image-2) 대화에 적합하지 않으므로, 스크립트가 자동으로 건너뛴 후 상위 30개를 취합니다.
2단계: config.toml 수정
~/.codex/config.toml을 편집하여 루트 레벨에 model_catalog_json을 추가하고 aihubmix provider를 정의합니다:
wire_api = "responses"가 핵심이며, 누락하거나 chat으로 작성하면 연결되지 않습니다. 최신 버전 Codex는 OpenAI의 Responses API(/v1/responses)만 사용하며, AIHubMix는 이미 Responses API를 네이티브로 호환하므로 https://aihubmix.com/v1을 직접 가리키기만 하면 되고 별도의 변환 프록시를 구축할 필요가 없습니다.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을 입력하여 목록에 선언된 모델이 보이는지 확인하고, 그중 하나(예:glm-5.2)로 전환합니다. - 아무 질문이나 던져 연결이 통하는지 검증합니다. 주의: 「너는 어떤 모델이니」로 판단하지 마세요——
base_instructions에 「You are Codex… based on GPT-5」라고 쓰여 있어 모든 모델이 이대로 GPT-5라고 자칭하므로, 물어봐도 실제 모델을 구분할 수 없습니다. 실제로 호출된 모델을 확인하려면 AIHubMix 콘솔의 「로그」 페이지에서 해당 요청 기록의model_id를 확인하세요. 이것이 진실입니다.
Model changed to ...가 표시되고, 하단 상태 표시줄에도 현재 모델과 컨텍스트 윈도우가 표시됩니다(아래 그림은 glm-5.2로 전환했으며, 윈도우 258K):

사용자 지정 모델 자주 묻는 질문
-
/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” 재연결. 일부 네트워크/프록시 환경에서는 WebSocket(WSS)이 통하지 않으므로, provider 섹션에
supports_websockets = false를 추가하여 강제로 HTTP를 사용하게 할 수 있습니다. -
파싱에서
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-06-25