메인 콘텐츠로 건너뛰기
Codex CLI는 OpenAI 공식 터미널 코딩 도구입니다. AIHubMix를 연동하면 단일 API 키만으로 터미널에서 GLM, Claude, Gemini, DeepSeek 등 여러 벤더의 모델을 호출하고 자유롭게 전환할 수 있어 특정 벤더에 묶이지 않습니다. 이 문서는 두 가지 방식을 다룹니다: 기본 방식(profile + 고정된 단일 모델, 가장 빠른 시작)과 사용자 지정 모델 방식(model_catalog_json 카탈로그 파일로 /model 목록에서 언제든 전환).

OpenAI Codex CLI 통합

AiHubMix는 OpenAI Codex CLI와의 원활한 통합을 제공하여 명령줄 환경에서 직접 고급 AI 프로그래밍 지원을 활용할 수 있도록 합니다. 간단한 구성 단계를 통해 자연어를 사용하여 터미널에서 다양한 프로그래밍 및 시스템 작업을 수행할 수 있습니다.
사용하기 전에 다음 명령을 실행하여 설치하거나 업데이트하십시오:
npm install -g @openai/codex

구성 단계

1. 환경 변수 설정

셸 구성 파일(예: .zshrc 또는 .bashrc)을 열고 다음 환경 변수를 추가합니다:
export OPENAI_BASE_URL="https://aihubmix.com/v1"
export OPENAI_API_KEY="sk-***"
OPENAI_API_KEYAiHubMix 키여야 합니다. 변수 이름은 OpenAI 네이티브 클라이언트와의 호환성을 위해 OPENAI_API_KEY로 유지됩니다.

2. 구성 변경 사항 적용

터미널에서 다음 명령을 실행하여 환경 변수를 적용합니다:
source ~/.zshrc  # zsh를 사용하는 경우
# 또는
source ~/.bashrc  # bash를 사용하는 경우

3. Codex CLI 실행

프로젝트 디렉토리로 이동하여 codex 명령을 실행합니다:
cd /your_project_path
codex
프로젝트 디렉토리에서 codex 명령을 실행한 터미널 화면

4. 자연어를 사용하여 작업 실행

이제 다음과 같이 자연어를 사용하여 Codex CLI에 지침을 입력할 수 있습니다:
# 샘플 입력
TTSComponent를 분해하고 핵심 로직을 Mermaid 순서도로 추출하세요.
Codex CLI에 자연어 작업을 입력해 응답을 받는 화면

고급 구성

  • 기본 모델은 codex-mini-latest이며, 이는 Codex CLI에서 사용하기 위해 특별히 미세 조정된 o4-mini 버전으로 ~/.codex/config.json에서 수정할 수 있습니다.
  • 현재 OpenAI 모델만 지원되며, 모델 목록은 응답 API 문서에서 찾을 수 있습니다.
  • ~/.codex/instructions.md 파일을 편집하여 시스템 프롬프트를 사용자 지정하여 AI 어시스턴트의 동작을 조정할 수 있습니다.

유용한 명령 참조

도움말 명령

codex -h

전체 명령 옵션

  사용법
    $ 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

두 가지 연동 방식

이 페이지 앞부분의 「환경 변수 설정」에서 다룬 것은 기본 방식이고, 이 절에서 다루는 것은 사용자 지정 모델 방식입니다. 차이는 다음과 같으니 필요에 따라 선택하세요:
기본 방식(profile + 단일 모델)사용자 지정 모델 방식(이 절)
설정 내용config.tomlmodel = "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 배열에 동일한 구조의 항목을 계속 추가하세요.
{
  "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를 선택할 수 있음
visibilitylist로 설정해야 선택기에 나타남
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의 상위 30개 LLM을 한 번에 목록에 작성하려면 아래 스크립트를 사용하세요. 이 스크립트는 하나의 내장 모델을 템플릿으로 복제하므로 필수 필드(올바른 base_instructions 포함)가 처음부터 완비되어 있어 Codex 버전이 달라도 누락되지 않습니다. curl, python3 및 설치된 codex CLI가 필요합니다:
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를 정의합니다:
# ⚠️ 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을 직접 가리키기만 하면 되고 별도의 변환 프록시를 구축할 필요가 없습니다.
겸사겸사 기본 모델기본 추론 단계를 지정하고 싶다면(시작 시 바로 사용, 매번 직접 선택할 필요 없음) 다음의 더 완전한 설정을 사용할 수 있습니다:
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에서 지정한 환경 변수를 설정하세요(= 양쪽에 공백이 없도록 주의):
export AIHUBMIX_API_KEY=sk-xxx
~/.zshrc / ~/.bashrc에 작성하여 영구화하는 것을 권장합니다. AIHubMix 콘솔에서 Key를 발급받으세요.

4단계: 재시작 후 모델 선택

Codex App / TUI를 재시작하여 목록 파일을 적용한 다음:
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 콘솔의 「로그」 페이지에서 해당 요청 기록의 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_jsonconfig.toml루트 레벨에 작성되었는지, [model_providers.*] 섹션 안에 있지 않은지 확인하세요;
    3. JSON이 snake_case 공식 필드를 사용하는지, visibilitylist인지 확인하세요;
    4. codex debug models에서는 이미 모든 모델이 보이지만 **데스크톱 앱(Desktop App)**에서는 한두 개만 남고 현재 모델이 「사용자 지정」으로 표시된다면——이는 데스크톱 앱의 알려진 버그입니다: 로컬 목록 위에 공식 slug 화이트리스트 필터를 한 겹 더 씌워서 비공식 모델을 선택기에서 제거합니다(GitHub Issue #19694, #15138 참조). 이때 모델은 사실 여전히 config.tomlmodel = "..."에 따라 정상적으로 호출되며(AIHubMix 로그로 확인 가능), 단지 이름이 표시되지 않을 뿐입니다. 올바르게 표시하려면 터미널 codex CLI / TUI를 사용하세요. 데스크톱 앱은 config.tomlmodel = "원하는 모델"을 고정으로 작성하는 수밖에 없으며, 공식 수정을 기다려야 합니다.
  • 목록은 「병합」이 아니라 「교체」입니다. 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 필드 세트로 바꾸면 됩니다.

참고 문서


마지막 업데이트: 2026-06-25