본문으로 건너뛰기

Codex CLI 연동

Codex CLI의 OpenAI 호환 provider로 Letsur 게이트웨이를 사용하세요.

사용자 설정, 환경 변수 키 전달, 모델 선택, 연결 확인과 오류 복구를 다룹니다.

이 가이드는 Codex CLI를 기준으로 검증했습니다. provider 설정은 프로젝트의 .codex/config.toml이 아니라 사용자 설정인 ~/.codex/config.toml에 둡니다. Codex는 프로젝트 설정에 있는 model_provider와 model_providers를 무시합니다.

시작 전 준비

  • AI 게이트웨이 API 키

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

  • 정확한 모델 코드

    에셋의 풀네임을 사용합니다. alias나 suffix 없는 짧은 코드는 사용하지 않습니다.

  • Codex CLI

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

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

게이트웨이 provider 연결하기

~/.codex/config.toml에 provider와 기본 모델을 설정합니다.

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 "..."

프로필로 전환하기

자주 쓰는 조합은 별도 프로필 파일로 정의하고 -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인지 확인합니다

설정 기준: Codex configuration reference , Codex developer commands 에서 provider, profile, codex exec 옵션을 2026년 8월 7일에 확인했습니다.

마지막 업데이트