Codex

Codex 사용자 지정 제공자 설정 및 오류 해결

Codex의 model_provider, Base URL, wire_api, API Key, Model ID를 설정하세요. 제공자 설정, 401, 404 오류를 해결합니다.

짧은 답변

model_provider는 Codex CLI가 사용할 provider를 지정합니다. value는 [model_providers.<id>] 아래에 정의된 provider id와 일치해야 합니다.

base_url은 model requests를 보내는 API endpoint입니다. OpenAI-compatible provider에서는 보통 /v1 style endpoint를 가리킵니다.

wire_api는 요청 프로토콜을 선택합니다. 현재 Codex는 responses만 지원하며 이 설정을 생략해도 같은 값을 사용합니다.

이 내용이 필요한 경우

custom OpenAI-compatible provider를 구성 중임
Codex가 provider를 찾을 수 없다고 하거나 model requests가 실패함
model_provider와 model의 차이를 확신하지 못함
BetterToken, OpenAI 또는 다른 provider를 하나의 config.toml에 넣고 있음
Base URL, API Key 및 Model ID를 분리해야 함

Field 관계

Field	목적
`model_provider`	active provider id 선택
`[model_providers.<id>]`	하나의 provider detailed configuration 정의
`name`	provider의 display name
`base_url`	root API endpoint
`wire_api`	provider 요청 프로토콜; 현재 `responses`만 지원합니다.
`model`	default main model ID
`review_model`	`/review` 등의 code review flows에 사용하는 model

파일 위치 확인 및 백업

사용자 지정 CODEX_HOME이 설정되어 있으면 해당 디렉터리의 config.toml과 auth.json을 편집하세요. 그렇지 않으면 macOS / Linux에서는 ~/.codex, Windows에서는 %USERPROFILE%\.codex를 사용합니다. CLI와 App은 같은 디렉터리를 사용해야 합니다. WSL은 별도의 사용자 디렉터리를 사용합니다.

편집하기 전에 Codex를 완전히 종료하고 두 파일을 비공개 위치에 백업하세요. 없는 파일은 생성합니다. 기존 설정을 교체하고 키나 테이블을 중복으로 추가하지 마세요. 관련 없는 설정은 유지하세요.

권장 pattern

config.toml 편집

이 문서는 사용자 수준 config.toml을 사용합니다. 최상위 키는 모든 TOML 테이블 앞에 두고 [projects."<path>"] 안에 넣지 마세요. 이 테이블은 프로젝트의 trust_level을 저장합니다. 선택한 provider ID와 테이블 이름을 일치시키세요. 파일 인증에서는 선택한 provider에서 env_key와 experimental_bearer_token을 제거합니다.

model_provider = "bettertoken"
model = "gpt-6-astra"
cli_auth_credentials_store = "file"

[model_providers.bettertoken]
name = "BetterToken"
base_url = "https://bettertoken.ai/v1"
wire_api = "responses"
requires_openai_auth = true
supports_websockets = false

예제는 GPT-6 Astra(gpt-6-astra)를 사용합니다. 다른 모델은 모델 광장에서 전체 ID를 복사해 model을 바꾸세요. GPT, Kimi, GLM은 같은 파일 인증 구조를 사용하며 자동 설정은 GPT에서 사용할 수 있습니다.

auth.json 편집

auth.json은 config.toml과 같은 디렉터리에 있습니다. auth.json이 없으면 해당 디렉터리에 새로 만드세요. 파일 내용을 다음 JSON으로 설정하고, YOUR_API_KEY를 자신의 BetterToken API Key로 바꾼 다음 저장하세요.

{
  "auth_mode": "apikey",
  "OPENAI_API_KEY": "YOUR_API_KEY"
}

설정 매개변수

매개변수	역할과 위치	기본값과 예시
`model_provider`	사용자 설정 최상위; 아래에 정의한 ID를 선택합니다.	기본값 `openai`; 여기서는 `bettertoken`.
`model`	최상위; 모델 광장의 전체 Model ID.	예시 `gpt-6-astra`; 필요에 따라 변경합니다.
`cli_auth_credentials_store`	최상위; 로그인 인증 정보 저장소.	여기서는 `file`: 같은 디렉터리의 `auth.json`을 읽습니다.
`name`	provider 테이블; 표시 이름만 지정합니다.	`BetterToken`은 Model ID가 아닙니다.
`base_url`	provider 테이블; 모델 API의 Base URL.	`https://bettertoken.ai/v1`을 사용하면 Codex가 `/responses`를 붙입니다.
`wire_api`	provider 테이블; 요청 프로토콜.	현재 `responses`만 지원하며 생략 시 기본값도 같습니다.
`requires_openai_auth`	provider 테이블; OpenAI 인증과 인증 정보 저장소를 사용합니다.	기본값 `false`; 여기서는 `true`. 로그인 파일 유지 스위치가 아닙니다.
`supports_websockets`	provider 테이블; Responses WebSocket 지원.	기본값 `false`; 여기서는 HTTP/SSE를 유지합니다.
`auth_mode`	`auth.json` 내부; 인증 모드.	여기서는 `apikey`: 공식 ChatGPT 인증을 대체합니다.
`OPENAI_API_KEY`	`auth.json` 내부; API 인증 Key.	`YOUR_API_KEY`를 BetterToken API Key로 바꿉니다.

여기서 파일 인증을 사용하면 API Key 모드로 전환됩니다. 공식 계정을 유지하려면 공식 로그인 유지 설정을 사용하고 두 모드를 섞지 마세요. 차이는 인증 목적이며 CLI, App, Extension의 차이가 아닙니다.

선택적 조정

이 세 설정은 선택적 조정이며 연결의 필수 조건이 아닙니다. 필요하면 기존 [model_providers.bettertoken] 테이블에 추가하고 같은 이름의 테이블을 또 만들지 마세요.

request_max_retries = 4
stream_max_retries = 8
stream_idle_timeout_ms = 300000

매개변수	역할과 위치	기본값과 예시
`request_max_retries`	provider 테이블; HTTP 요청의 최대 재시도 횟수.	기본값 `4`; 연결 상태에 맞게 조정합니다.
`stream_max_retries`	provider 테이블; 스트림 중단 후 재연결 횟수.	기본값 `5`; `8`은 선택적 사용자 지정 값입니다.
`stream_idle_timeout_ms`	provider 테이블; 스트림 비활성 시간 제한, 밀리초 단위.	기본값 `300000`; 작업 전체의 시간 제한이 아닙니다.

설정 계층과 이전 키

모델과 추론 설정을 [projects."<path>"]에 넣지 마세요. 프로젝트별 모델은 신뢰한 프로젝트의 .codex/config.toml 최상위에 둘 수 있지만 provider와 인증은 사용자 설정에 둡니다. 현재 profile은 CODEX_HOME의 NAME.config.toml을 codex --profile NAME으로 선택합니다. 이전 [profiles.NAME] 테이블이나 최상위 profile 선택자는 사용하지 않습니다.

재시작 및 확인

두 파일을 저장한 뒤 터미널에서 새 Codex CLI 세션을 바로 시작하세요.

codex

백그라운드 프로세스를 포함해 Codex App을 완전히 종료한 다음 다시 열고 새 로컬 작업을 만드세요. 사용하는 각 클라이언트에서 짧은 프롬프트를 보내 정상 응답을 확인하세요.

문제 해결

401, 403 또는 로그인 요청이 표시되면 활성 디렉터리, auth.json의 Key, auth_mode = apikey, cli_auth_credentials_store = file, requires_openai_auth = true를 확인하세요. 제공업체나 모델 오류가 발생하면 제공업체 ID 일치 여부, https://bettertoken.ai/v1, wire_api = responses, 모델 사용 가능 여부를 확인하세요. 변경 사항이 적용되지 않으면 설정 재정의 항목을 확인하고 CLI와 App이 같은 CODEX_HOME을 사용하는지 확인하세요.