본문으로 건너뛰기

Codex CLI

Responses 지원 모델로 코딩 작업 시작하기

사용자 config.toml에 게이트웨이 provider를 등록하고, 환경 변수로 키를 전달해 모델을 선택하고 응답을 받는 방법을 안내합니다.

페이지 목차
프로젝트의 .codex/config.toml에 쓴 provider 설정은 적용되지 않습니다

이 설정은 Codex CLI용입니다. provider 설정은 사용자 설정 파일인 ~/.codex/config.toml에 작성합니다. Codex는 프로젝트의 .codex/config.toml에 있는 model_provider, model_providers, profile, profiles를 무시합니다.

시작 전 준비

설정을 마치면 Codex CLI가 사용자 설정에 등록한 게이트웨이 provider를 거쳐 Responses를 지원하는 모델을 호출합니다. API 키는 환경 변수로 전달하고, 연결 여부는 모델 응답이 출력되는지로 확인합니다.

  • AI 게이트웨이 API 키

    현재 사용할 수 있는 AI 게이트웨이 API 키를 준비합니다.

  • 모델 코드

    에셋에서 Responses를 지원하는 모델의 정확한 코드를 확인합니다. 에셋에 표시된 모델 코드를 줄이거나 바꾸지 않고 사용합니다.

  • Codex CLI

    로컬 환경에 Codex CLI를 설치합니다. 아래 설정은 로컬에 설치된 Codex CLI의 config.toml 기준입니다.

Codex CLI에 넣을 값은 아래 단계에 모두 있습니다. API 형식별 기본 URL과 인증 헤더 전체는 인증과 기본 URL에 정리돼 있습니다.

연결 설정

provider는 모델에 연결할 주소와 API 형식, 인증 방법을 묶은 설정입니다. ~/.codex/config.toml에 게이트웨이를 provider로 등록하고, model에 기본으로 사용할 모델 코드를 지정합니다.

  1. provider 등록하기

    ~/.codex/config.toml에 다음 내용을 작성합니다.

    model = "<MODEL_CODE>" # 에셋의 정확한 모델 코드 model_provider = "letsur" [model_providers.letsur] name = "Letsur Gateway" base_url = "https://gw.letsur.ai/v1" # 요청 경로는 base_url + /responses env_key = "LETSUR_API_KEY" # 키를 읽을 환경 변수 이름 wire_api = "responses" # Responses API 사용

    wire_api에 지정할 수 있는 값은 responses뿐입니다. chat을 지정하면 Codex CLI가 설정을 읽지 못하고 오류를 표시합니다. model_provider에는 Codex가 예약한 ID(openai, ollama, lmstudio 등)가 아닌 이름을 사용합니다.

  2. API 키 환경 변수 설정하기

    실제 키를 명령어나 config.toml에 직접 입력하지 마세요

    env_key에는 Codex가 키를 읽을 환경 변수 이름만 지정합니다.

    실행 환경에서 LETSUR_API_KEY 환경 변수에 AI 게이트웨이 API 키를 설정합니다. codex 명령을 실행하는 프로세스가 이 변수를 읽을 수 있어야 합니다.

모델 선택

필요한 적용 범위에 따라 다음 방법 중 하나를 선택합니다.

기본 모델 바꾸기

config.toml의 model 값을 에셋의 다른 모델 코드로 바꿉니다. 실행 옵션, 프로필이나 신뢰한 프로젝트의 .codex/config.toml에서 다른 모델을 지정하지 않으면 Codex CLI가 이 기본값을 사용합니다. 같은 키가 여러 곳에 있으면 실행 옵션, 프로젝트 설정, 프로필, 사용자 설정 순으로 앞의 값이 적용됩니다.

한 번만 바꾸기

실행할 때 -m(--model) 옵션으로 지정한 모델은 그 실행에만 적용됩니다. --skip-git-repo-check는 Git 저장소가 아닌 디렉터리에서 codex exec를 실행할 수 있게 하는 옵션입니다.

codex exec -m "<MODEL_CODE>" --skip-git-repo-check "..."

프로필로 전환하기

Codex CLI 0.134.0 이상에서는 자주 사용하는 조합을 별도 프로필 파일에 정의하고 -p(--profile)로 선택합니다. 이 버전부터 --profile은 config.toml의 [profiles.<이름>] 표를 읽지 않으므로, 프로필 파일에서는 키를 표로 묶지 않고 최상위에 작성합니다. Codex CLI는 ~/.codex/config.toml을 먼저 읽고 그 위에 프로필 파일의 값을 덮어씁니다. 예를 들어 ~/.codex/letsur-secondary.config.toml 파일을 다음과 같이 만듭니다.

model = "<SECONDARY_MODEL_CODE>" model_provider = "letsur"
codex exec -p letsur-secondary --skip-git-repo-check "..."

연결 확인

LETSUR_API_KEY가 설정된 실행 환경에서 다음 명령을 실행합니다.

codex exec --skip-git-repo-check "ping"

모델 응답이 출력되면 Codex CLI가 게이트웨이를 거쳐 모델을 호출한 것입니다. 실제 작업에 사용할 도구와 기능의 동작은 선택한 모델로 별도로 확인합니다.

지원 범위와 제약

Codex custom provider는 Responses API만 지원합니다. Codex CLI는 base_url 뒤에 /responses를 추가해 요청을 보냅니다. 요청 필드와 응답 형식은 Responses 명세에서 확인합니다.

문제 해결

증상다음 행동
Missing environment variable: `LETSUR_API_KEY`. 오류가 표시됩니다env_key에 지정한 이름과 실제 환경 변수 이름이 일치하는지, 값이 비어 있지 않은지 확인합니다
Codex CLI가 모델을 찾지 못합니다model 또는 -m의 값이 에셋 화면의 정확한 모델 코드와 일치하는지 확인합니다
unexpected status 401 오류가 표시됩니다키 값과 키 상태(비활성 또는 만료)를 확인합니다
`wire_api = "chat"` is no longer supported 오류가 표시됩니다wire_api를 responses로 바꿉니다
provider 요청이 실패합니다base_url에 /v1이 포함되어 있는지, provider 설정을 프로젝트 설정이 아닌 ~/.codex/config.toml에 작성했는지 확인합니다

그 밖의 오류는 오류 type별 대응에서 확인합니다.

설정 기준: 기본 설정 , 고급 설정 , 설정 레퍼런스 , 개발자 명령 레퍼런스 , Codex 공식 저장소 의 provider 설정 위치와 키, wire_api 허용 값, 프로필 파일, 설정 우선순위, -m, -p, codex exec 옵션과 오류 메시지를 2026년 11월 13일에 확인했습니다. 이 확인에는 렛서 게이트웨이와의 실제 연동 시험이 포함되지 않습니다.