> ## Documentation Index > Fetch the complete documentation index at: https://docs.aihubmix.com/llms.txt > Use this file to discover all available pages before exploring further. # Codex CLI AIHubMix 연동 튜토리얼 > Codex CLI에서 AIHubMix 연동: 단일 API 키로 /model 목록에서 GLM, Claude, Gemini, DeepSeek 등 모델을 자유롭게 전환. config.toml 설정, model_catalog_json 모델 카탈로그 생성 스크립트, 문제 해결 FAQ 포함. [Codex CLI](https://openai.com/codex/)는 OpenAI 공식 터미널 코딩 도구입니다. AIHubMix를 연동하면 단일 API 키만으로 터미널에서 GLM, Claude, Gemini, DeepSeek 등 여러 벤더의 모델을 호출하고 자유롭게 전환할 수 있어 특정 벤더에 묶이지 않습니다. 이 문서는 두 가지 방식을 다룹니다: **기본 방식**(profile + 고정된 단일 모델, 가장 빠른 시작)과 **사용자 지정 모델 방식**(`model_catalog_json` 카탈로그 파일로 `/model` 목록에서 언제든 전환). # OpenAI Codex CLI 통합 AiHubMix는 OpenAI [Codex CLI](https://github.com/openai/codex)와의 원활한 통합을 제공하여 명령줄 환경에서 직접 고급 AI 프로그래밍 지원을 활용할 수 있도록 합니다. 간단한 구성 단계를 통해 자연어를 사용하여 터미널에서 다양한 프로그래밍 및 시스템 작업을 수행할 수 있습니다.\ 사용하기 전에 다음 명령을 실행하여 설치하거나 업데이트하십시오: ```bash theme={null} npm install -g @openai/codex ``` ## 구성 단계 ### 1. 환경 변수 설정 셸 구성 파일(예: `.zshrc` 또는 `.bashrc`)을 열고 다음 환경 변수를 추가합니다: ```bash theme={null} export OPENAI_BASE_URL="https://aihubmix.com/v1" export OPENAI_API_KEY="sk-***" ``` `OPENAI_API_KEY`는 [AiHubMix 키](https://aihubmix.com/token)여야 합니다. 변수 이름은 OpenAI 네이티브 클라이언트와의 호환성을 위해 `OPENAI_API_KEY`로 유지됩니다. ### 2. 구성 변경 사항 적용 터미널에서 다음 명령을 실행하여 환경 변수를 적용합니다: ```bash theme={null} source ~/.zshrc # zsh를 사용하는 경우 # 또는 source ~/.bashrc # bash를 사용하는 경우 ``` ### 3. Codex CLI 실행 프로젝트 디렉토리로 이동하여 `codex` 명령을 실행합니다: ```bash theme={null} cd /your_project_path codex ``` 프로젝트 디렉토리에서 codex 명령을 실행한 터미널 화면 ### 4. 자연어를 사용하여 작업 실행 이제 다음과 같이 자연어를 사용하여 Codex CLI에 지침을 입력할 수 있습니다: ```bash theme={null} # 샘플 입력 TTSComponent를 분해하고 핵심 로직을 Mermaid 순서도로 추출하세요. ``` Codex CLI에 자연어 작업을 입력해 응답을 받는 화면 ## 고급 구성 * 기본 모델은 `codex-mini-latest`이며, 이는 Codex CLI에서 사용하기 위해 특별히 미세 조정된 `o4-mini` 버전으로 `~/.codex/config.json`에서 수정할 수 있습니다. * 현재 OpenAI 모델만 지원되며, 모델 목록은 [응답 API 문서](https://platform.openai.com/docs/api-reference/responses)에서 찾을 수 있습니다. * `~/.codex/instructions.md` 파일을 편집하여 시스템 프롬프트를 사용자 지정하여 AI 어시스턴트의 동작을 조정할 수 있습니다. ## 유용한 명령 참조 ### 도움말 명령 ```bash theme={null} codex -h ``` ### 전체 명령 옵션 ```bash theme={null} 사용법 $ codex [옵션] <프롬프트> 옵션 -h, --help 사용법을 표시하고 종료합니다 -m, --model <모델> 완료에 사용할 모델 (기본값: codex-mini-latest) -i, --image <경로> 입력으로 포함할 이미지 파일 경로 -v, --view <롤아웃> 세션을 시작하는 대신 이전에 저장된 롤아웃을 검사합니다 -q, --quiet 어시스턴트의 최종 출력만 인쇄하는 비대화형 모드 -a, --approval-mode <모드> 승인 정책을 재정의합니다: 'suggest', 'auto-edit' 또는 'full-auto' --auto-edit 파일 편집을 자동으로 승인합니다. 여전히 명령에 대한 프롬프트가 표시됩니다 --full-auto 샌드박스에서 실행될 때 편집 및 명령을 자동으로 승인합니다 --no-project-doc 리포지토리의 'codex.md'를 자동으로 포함하지 않습니다 --project-doc <파일> <파일>에 있는 추가 마크다운 파일을 컨텍스트로 포함합니다 --full-stdout 명령 출력에서 stdout/stderr를 자르지 않습니다 위험한 옵션 --dangerously-auto-approve-everything 모든 확인 프롬프트를 건너뛰고 샌드박스 없이 명령을 실행합니다. 일시적인 로컬 테스트용으로만 사용됩니다. 실험적 옵션 -f, --full-context 전체 리포지토리를 컨텍스트에 로드하고 한 번에 편집 배치를 적용하는 "전체 컨텍스트" 모드로 시작합니다. --model을 제외한 모든 다른 플래그와 호환되지 않습니다. 예제 $ codex "ASCII 아트를 인쇄하는 파이썬 프로그램을 작성하고 실행하세요" $ codex -q "빌드 문제 수정" ```

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](https://developers.openai.com/codex/config-advanced) ### 두 가지 연동 방식 이 페이지 앞부분의 「환경 변수 설정」에서 다룬 것은 **기본 방식**이고, 이 절에서 다루는 것은 **사용자 지정 모델 방식**입니다. 차이는 다음과 같으니 필요에 따라 선택하세요: | | 기본 방식(profile + 단일 모델) | 사용자 지정 모델 방식(이 절) | | ------ | --------------------------------------- | ------------------------------------- | | 설정 내용 | `config.toml`에 `model = "xxx"`를 고정으로 작성 | 추가로 `model_catalog_json` 목록 파일을 유지 관리 | | 모델 전환 | 설정 파일을 수정한 뒤 재시작 | `/model` 목록에서 바로 선택, 언제든 전환 가능 | | 적합한 상황 | 장기간 특정 모델 하나를 고정으로 사용 | 여러 모델을 자주 비교 / 전환하고 싶을 때 | | 복잡도 | 낮음 | 중간 | 전체 과정은 4단계뿐입니다: **목록 파일 생성 → `config.toml` 수정 → 환경 변수 설정 → 재시작 후 모델 선택**. ### 1단계: 모델 목록 파일 생성 목록 파일은 `{ "models": [ ... ] }` 구조이며, 배열의 각 요소는 `/model`에서 선택할 수 있는 하나의 모델을 설명합니다. 아래에서는 먼저 **하나의 고정 모델**로 필드를 설명한 뒤, **상위 30개를 일괄 생성**하는 스크립트를 제공합니다. #### 1.1 먼저 형식 이해하기: 모델 하나 고정 다음은 **Codex가 파싱할 수 있음이 검증된** 최소 완전 목록(`glm-5.2` 한 모델만 포함)입니다. 그대로 `~/.codex/model-catalogs/custom-models.json`으로 저장하면 바로 사용할 수 있습니다. 더 많은 모델을 원한다면 `models` 배열에 동일한 구조의 항목을 계속 추가하세요. ```json theme={null} { "models": [ { "slug": "glm-5.2", "display_name": "GLM 5.2", "description": "GLM 5.2 (via AIHubMix)", "context_window": 1000000, "max_context_window": 1000000, "supported_reasoning_levels": [ { "effort": "low", "description": "Fast responses" }, { "effort": "medium", "description": "Balanced" }, { "effort": "high", "description": "Deeper reasoning" } ], "shell_type": "shell_command", "visibility": "list", "supported_in_api": true, "priority": 0, "availability_nux": null, "upgrade": null, "base_instructions": "You are Codex, a coding agent.", "supports_reasoning_summaries": true, "support_verbosity": false, "default_verbosity": null, "apply_patch_tool_type": null, "truncation_policy": { "mode": "tokens", "limit": 10000 }, "supports_parallel_tool_calls": true, "experimental_supported_tools": [] } ] } ``` 필드 설명(일반적으로 수정하게 되는 몇 가지): | 필드 | 역할 | 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`, `availability_nux`, `upgrade`, `supports_reasoning_summaries`, `support_verbosity`, `default_verbosity`, `apply_patch_tool_type`, `truncation_policy`, `supports_parallel_tool_calls`, `experimental_supported_tools`. 최신 버전 Codex(`codex-cli 0.130.0`에서 검증됨)는 엄격하게 파싱하므로, **하나라도 빠지면 목록 전체가 폐기되고** 내장 목록으로 폴백되며, `missing field base_instructions` 같은 오류가 발생합니다. 증상은 「`/model`에 사용자 지정 모델이 하나도 보이지 않음」으로 나타납니다. 따라서 위 예시에서 필드를 더 삭제해서는 안 됩니다. `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](https://aihubmix.com/api/v1/models?type=llm)의 상위 30개 LLM을 한 번에 목록에 작성하려면 아래 스크립트를 사용하세요. 이 스크립트는 **하나의 내장 모델을 템플릿으로 복제**하므로 필수 필드(올바른 `base_instructions` 포함)가 처음부터 완비되어 있어 Codex 버전이 달라도 누락되지 않습니다. `curl`, `python3` 및 설치된 `codex` CLI가 필요합니다: ```bash theme={null} mkdir -p ~/.codex/model-catalogs # 1) 내장 모델 하나를 템플릿으로 사용: base_instructions 등 모든 필수 필드를 자체적으로 갖추고 있음 codex debug models --bundled > /tmp/_tpl.json # 2) AIHubMix 모델 목록 가져오기 curl -s "https://aihubmix.com/api/v1/models?type=llm" > /tmp/_aihubmix.json # 3) 템플릿을 복제해 항목을 하나씩 생성하고, 각 모델 고유의 필드만 덮어쓰기 python3 - <<'PY' > ~/.codex/model-catalogs/custom-models.json import json, sys tpl = json.load(open("/tmp/_tpl.json"))["models"][0] # 임의의 내장 모델을 템플릿으로 api = json.load(open("/tmp/_aihubmix.json"))["data"] # 이미지 생성 모델 건너뛰기(types에 image_generation 포함), 그 후 상위 30개 취하기 api = [m for m in api if "image_generation" not in (m.get("types") or "")][:30] out = [] for i, m in enumerate(api): e = dict(tpl) # 템플릿의 모든 필드 복제 ctx = m.get("context_length") or 200000 e["slug"] = m["model_id"] # 반드시 API의 model_id와 일치해야 함 e["display_name"] = m.get("model_name") or m["model_id"] e["description"] = (m.get("model_name") or m["model_id"]) + " (via AIHubMix)" e["context_window"] = ctx e["max_context_window"] = ctx e["visibility"] = "list" e["supported_in_api"] = True e["priority"] = i e["availability_nux"] = None e["upgrade"] = None out.append(e) json.dump({"models": out}, sys.stdout, ensure_ascii=False, indent=2) PY ``` 스크립트는 각 모델 고유의 필드(`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를 정의합니다: ```toml theme={null} # ⚠️ model_catalog_json은 반드시 루트 레벨에 작성해야 하며, [model_providers.*] 섹션 안에 넣으면 안 됩니다 model_provider = "aihubmix" model_catalog_json = "~/.codex/model-catalogs/custom-models.json" [model_providers.aihubmix] name = "Aihubmix" base_url = "https://aihubmix.com/v1" wire_api = "responses" env_key = "AIHUBMIX_API_KEY" ``` `wire_api = "responses"`가 핵심이며, **누락하거나 `chat`으로 작성하면 연결되지 않습니다**. 최신 버전 Codex는 OpenAI의 Responses API(`/v1/responses`)만 사용하며, AIHubMix는 이미 Responses API를 네이티브로 호환하므로 `https://aihubmix.com/v1`을 직접 가리키기만 하면 되고 별도의 변환 프록시를 구축할 필요가 없습니다. 겸사겸사 **기본 모델**과 **기본 추론 단계**를 지정하고 싶다면(시작 시 바로 사용, 매번 직접 선택할 필요 없음) 다음의 더 완전한 설정을 사용할 수 있습니다: ```toml theme={null} model = "glm-5.2" # 시작 시 기본 모델, 목록 파일에 존재해야 함 model_provider = "aihubmix" model_catalog_json = "~/.codex/model-catalogs/custom-models.json" model_reasoning_effort = "high" # 기본 추론 단계: minimal / low / medium / high [model_providers.aihubmix] name = "Aihubmix" base_url = "https://aihubmix.com/v1" wire_api = "responses" env_key = "AIHUBMIX_API_KEY" ``` 설정을 마치면 `config.toml`은 대략 다음과 같습니다(빨간 박스는 이 단계의 핵심 항목: 루트 레벨의 `model` / `model_provider` / `model_catalog_json` 및 `[model_providers.aihubmix]` 섹션): config.toml의 model_catalog_json 및 aihubmix 공급자 설정 ### 3단계: 환경 변수 설정 위 `env_key`에서 지정한 환경 변수를 설정하세요(`=` 양쪽에 공백이 없도록 주의): ```bash theme={null} export AIHUBMIX_API_KEY=sk-xxx ``` `~/.zshrc` / `~/.bashrc`에 작성하여 영구화하는 것을 권장합니다. [AIHubMix 콘솔](https://aihubmix.com/token)에서 Key를 발급받으세요. ### 4단계: 재시작 후 모델 선택 Codex App / TUI를 재시작하여 목록 파일을 적용한 다음: ```bash theme={null} codex # TUI에서 /model을 입력하면 위에서 선언한 30개 모델을 보고 전환할 수 있습니다 ``` `/model`을 입력하면 목록에 선언된 모든 모델이 나열됩니다. 방향키로 선택하고 Enter로 확정하세요: Codex /model 선택기에 표시된 AIHubMix 사용자 지정 모델 목록 모델을 선택한 후 `/model`에서 추론 단계(effort)도 선택할 수 있습니다. 필요에 따라 `low` / `medium` / `high`를 선택하면 됩니다. ### 5단계: 적용 여부 검증 1. Codex에 진입한 후 `/model`을 입력하여 목록에 선언된 모델이 보이는지 확인하고, 그중 하나(예: `glm-5.2`)로 전환합니다. 2. 아무 질문이나 던져 연결이 통하는지 검증합니다. 주의: **「너는 어떤 모델이니」로 판단하지 마세요**——`base_instructions`에 「You are Codex... based on GPT-5」라고 쓰여 있어 모든 모델이 이대로 GPT-5라고 자칭하므로, 물어봐도 실제 모델을 구분할 수 없습니다. 실제로 호출된 모델을 확인하려면 [AIHubMix 콘솔](https://aihubmix.com/token)의 「로그」 페이지에서 해당 요청 기록의 `model_id`를 확인하세요. 이것이 진실입니다. 전환에 성공하면 상단에 `Model changed to ...`가 표시되고, 하단 상태 표시줄에도 현재 모델과 컨텍스트 윈도우가 표시됩니다(아래 그림은 `glm-5.2`로 전환했으며, 윈도우 258K): glm-5.2로 전환한 후의 Codex 세션과 하단 상태 표시줄 ## 사용자 지정 모델 자주 묻는 질문 * **`/model`에 사용자 지정 모델이 보이지 않나요?** 다음 순서대로 점검하세요: 1. **먼저 `codex debug models`를 실행하세요**. `missing field ...`(가장 흔함, 필수 필드 누락)나 `unknown variant ...`(필드명/값이 잘못됨)가 발생하면 목록 전체가 파싱에 실패해 폐기된 것입니다——1단계의 「내장 템플릿 복제」 스크립트로 다시 생성하면 됩니다. 2. `model_catalog_json`이 `config.toml`의 **루트 레벨**에 작성되었는지, `[model_providers.*]` 섹션 안에 있지 않은지 확인하세요; 3. JSON이 snake\_case 공식 필드를 사용하는지, `visibility`가 `list`인지 확인하세요; 4. `codex debug models`에서는 이미 모든 모델이 보이지만 \*\*데스크톱 앱(Desktop App)\*\*에서는 한두 개만 남고 현재 모델이 「사용자 지정」으로 표시된다면——이는 데스크톱 앱의 알려진 버그입니다: 로컬 목록 위에 공식 slug 화이트리스트 필터를 한 겹 더 씌워서 비공식 모델을 선택기에서 제거합니다(GitHub Issue [#19694](https://github.com/openai/codex/issues/19694), [#15138](https://github.com/openai/codex/issues/15138) 참조). 이때 모델은 사실 여전히 `config.toml`의 `model = "..."`에 따라 정상적으로 호출되며(AIHubMix 로그로 확인 가능), 단지 이름이 표시되지 않을 뿐입니다. **올바르게 표시하려면 터미널 `codex` CLI / 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](https://developers.openai.com/codex/config-advanced) ｜ [Configuration Reference](https://developers.openai.com/codex/config-reference) * 공식 내장 목록 형식 참고: [codex-rs/models-manager/models.json](https://github.com/openai/codex/blob/main/codex-rs/models-manager/models.json) * 커뮤니티 가이드: [Codex config.toml: 6줄로 임의의 사용자 지정 provider 연동하기](https://www.morphllm.com/codex-provider-configuration) *** 마지막 업데이트: 2026-06-25