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

설치

공식 웹사이트에서 다운로드(macOS 버전)

https://openai.com/en/codex/

명령줄로 설치

기본 설정

설정 파일로 설정하기

  1. ~/.codex/config.toml 설정 파일에 다음 설정을 추가합니다:
  1. env_key에 지정한 환경 변수에 AIHubMix API 키를 설정합니다(= 양쪽에 공백이 없도록 주의):
~/.zshrc / ~/.bashrc에 작성하여 영구화하는 것을 권장합니다. AIHubMix 콘솔에서 Key를 발급받으세요.
사용자 지정 provider는 기본적으로 ~/.codex/auth.json의 OPENAI_API_KEY를 읽지 않습니다. 키는 반드시 env_key에 지정한 환경 변수로 전달해야 하며, 그렇지 않으면 요청에 키가 포함되지 않아 401이 반환됩니다.
Codex 0.134.0부터 profile = "..."와 [profiles.xxx]는 더 이상 지원되지 않습니다. 이전 설정을 그대로 두면 시작할 때 legacy profile = "..." config is no longer supported 오류가 발생합니다. 이 가이드의 이전 버전대로 설정했다면 두 부분을 모두 삭제하고 위 설정으로 바꾸세요. 여러 설정을 나눠 써야 한다면 달라지는 항목만 ~/.codex/<이름>.config.toml에 작성하고([profiles.xxx] 아래가 아니라 최상위 키로), codex --profile <이름>으로 Codex를 시작하세요.
model은 AIHubMix의 다른 모델 ID로 바꿀 수 있습니다. 다만 GLM, Claude 같은 OpenAI 외 모델로 바꾸면 Codex가 Model metadata for ... not found를 표시하고 기본값으로 폴백하므로, 이런 경우에는 아래의 사용자 지정 모델 방식을 사용하세요.

cc-switch로 설정하기

  1. CC-Switch를 실행하고 공급자를 추가합니다.
CC-Switch 공급자 추가 화면
  1. 프리셋 목록에서 「AiHubMix」를 선택합니다.
CC-Switch 프리셋 목록에서 AiHubMix 선택
  1. 「API Key」 칸에 키를 입력하고 「추가」를 클릭하여 설정을 저장합니다.
CC-Switch에 API Key를 입력하고 저장
  1. 홈 화면으로 돌아가 공급자 목록에서 「AiHubMix」를 선택하고 「활성화」를 클릭하면 바로 사용할 수 있습니다.
CC-Switch에서 AiHubMix 공급자 활성화

Codex 사용하기

터미널에서 사용하기

  1. 터미널을 열고 프로젝트 디렉토리로 이동한 다음 codex 명령을 실행합니다.
  1. 필요에 따라 권한을 설정합니다. 이후 언제든 /permissions로 변경할 수 있습니다.
  2. 필요에 따라 사용할 모델을 선택합니다. 하단 상태 표시줄에 현재 모델이 표시되며, /model로 전환할 수 있습니다.
Codex 시작 후 하단 상태 표시줄에 현재 모델이 표시된 화면
  1. 자연어로 요청을 입력해 정상적으로 응답하면 설정이 완료된 것입니다.
Codex CLI에 자연어 작업을 입력해 응답을 받는 화면

Codex 데스크톱 앱에서 사용하기

  1. Codex 데스크톱 앱을 열고 작업 디렉토리를 선택합니다.
  2. 입력창에 작업을 입력해 정상적으로 응답하면 설정이 완료된 것입니다.
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, 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 이상, 0.162.1에서 재확인)는 엄격하게 파싱하므로, 하나라도 빠지면 목록 전체가 폐기되고 내장 목록으로 폴백되며, 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가 필요합니다:
스크립트는 각 모델 고유의 필드(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] 섹션): config.toml의 model_catalog_json 및 aihubmix 공급자 설정

3단계: 환경 변수 설정

위 env_key에서 지정한 환경 변수를 설정하세요(= 양쪽에 공백이 없도록 주의):
~/.zshrc / ~/.bashrc에 작성하여 영구화하는 것을 권장합니다. AIHubMix 콘솔에서 Key를 발급받으세요.

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

Codex App / TUI를 재시작하여 목록 파일을 적용한 다음:
/model을 입력하면 목록에 선언된 모든 모델이 나열됩니다. 방향키로 선택하고 Enter로 확정하세요: Codex /model 선택기에 표시된 AIHubMix 사용자 지정 모델 목록 모델을 선택한 후 /model에서 추론 단계(effort)도 선택할 수 있습니다. 필요에 따라 low / medium / high를 선택하면 됩니다. claude-opus-5-5의 추론 단계 선택 화면

5단계: 적용 여부 검증

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

사용자 지정 모델 자주 묻는 질문

  • 시작 시 legacy profile = "..." config is no longer supported 오류가 발생합니다. Codex 0.134.0부터 profile =과 [profiles.xxx]는 더 이상 지원되지 않습니다. 두 부분을 모두 삭제하고 위의 「기본 설정」대로 설정을 다시 작성하세요.
  • 이전 스크립트로 목록을 생성한 경우. 이전 스크립트는 내장 템플릿의 code mode를 끄지 않았습니다. Codex가 업데이트되면서 첫 번째 내장 모델이 gpt-6 시리즈로 바뀌었기 때문에, 생성된 목록은 정상적으로 파싱되지만 요청에 표준 tools 목록이 포함되지 않습니다. 1단계의 새 스크립트로 목록을 다시 생성하세요.
  • /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, #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”이 계속되다가 오류로 끝납니다. 먼저 마지막 오류 줄을 확인하세요. 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 필드 세트로 바꾸면 됩니다.

참고 문서


마지막 업데이트: 2026-10-15