본문으로 건너뛰기

Codex CLI

AI 게이트웨이의 Responses API 지원 모델을 Codex CLI에서 사용하세요.

이 설정은 Codex CLI용입니다. provider 설정은 프로젝트의 .codex/config.toml이 아니라 사용자 설정인 ~/.codex/config.toml에 둡니다. Codex는 프로젝트 설정에 있는 model_provider와 model_providers를 무시합니다.

시작 전 준비

  • AI 게이트웨이 API 키

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

  • 정확한 모델 코드

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

  • Codex CLI

    이 가이드는 로컬에 설치된 Codex CLI의 config.toml을 기준으로 합니다.

공통 기본 URL과 키 형식은 외부 도구 연결에서 비교합니다.

게이트웨이 provider 연결하기

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

model = "<MODEL_CODE>"     # 에셋의 정확한 모델 코드
model_provider = "letsur"
 
[model_providers.letsur]
name = "Letsur Gateway"
base_url = "https://gw.letsur.ai/v1"  # 뒤에 /responses 가 붙습니다
env_key = "LETSUR_API_KEY"            # 키를 읽을 환경 변수 이름
wire_api = "responses"                # 현재 Codex는 responses 만 지원

config.toml에는 실제 키를 적지 마세요. env_key에는 키 값이 아니라 Codex가 키를 읽을 환경 변수 이름만 둡니다.

아래 명령은 키 입력을 화면과 셸 히스토리에 남기지 않고 현재 셸 세션의 LETSUR_API_KEY에 저장합니다. 새 터미널을 열면 다시 설정해야 합니다.

printf 'Letsur API 키: '
IFS= read -rs LETSUR_API_KEY
printf '\n'
export LETSUR_API_KEY

모델 선택

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

기본 모델 바꾸기

config.toml의 model 값을 에셋의 다른 모델 코드로 바꿉니다. 실행 옵션이나 프로필에서 다른 모델을 선택하지 않으면 이 기본값을 사용합니다.

한 번만 바꾸기

실행 시 -m(--model)로 그 실행에만 다른 모델을 씁니다.

LETSUR_MODEL_CODE="<MODEL_CODE>"
codex exec -m "${LETSUR_MODEL_CODE}" --skip-git-repo-check "..."

프로필로 전환하기

Codex CLI 0.134.0 이상에서는 자주 쓰는 조합을 별도 프로필 파일에 정의하고 -p(--profile)로 선택합니다. 예를 들어 ~/.codex/letsur-secondary.config.toml을 만듭니다.

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

연결 확인

(
  test -n "${LETSUR_API_KEY:-}" || { echo "LETSUR_API_KEY가 필요합니다." >&2; exit 1; }
  codex exec --skip-git-repo-check "ping"
)

모델 응답이 출력되면 설정한 provider와 키로 모델을 호출한 것입니다. 실제 코딩 작업에 사용할 도구와 기능도 선택한 모델에서 동작하는지 확인합니다.

지원 범위와 제약

Codex custom provider는 Responses wire API만 지원합니다. 선택한 모델과 Letsur 게이트웨이가 /v1/responses 요청을 지원하는지 에셋과 API 레퍼런스에서 확인합니다.

문제 해결

증상먼저 확인할 것
키를 찾지 못합니다env_key에 적은 이름과 실제 환경 변수 이름이 같은지 확인합니다
모델을 찾지 못합니다model 또는 -m에 에셋의 정확한 모델 코드를 사용했는지 확인합니다
provider 요청이 실패합니다base_url에 /v1이 포함되고 wire_api가 responses인지 확인합니다

설정 기준: 공식 고급 설정 과 설정 레퍼런스 에서 provider의 설정 위치, 프로필 파일과 Responses 설정을 2026년 9월 14일에 대조했습니다. 명령 옵션은 Codex CLI 레퍼런스 에서 확인합니다.