Coding Agent 설정

Codex CLI/App 사용자 지정 API 설정

config.toml, auth.json, BetterToken API Key, Responses Base URL로 Codex CLI와 Codex App을 설정합니다.

Codex CLI와 Codex App은 로컬 작업에 config.toml과 auth.json을 함께 사용합니다. 이 설정은 OpenAI Responses를 통해 BetterToken API Key를 사용합니다.

주요 설정

필드	값
API Key	`auth.json` → `OPENAI_API_KEY`
Base URL	`https://bettertoken.ai/v1`
Model	`gpt-6-astra`

준비 사항

npm 또는 BetterToken 자동 설정 스크립트를 사용한다면 Node.js 설치
BetterToken API Key 생성
모델 광장 또는 Key 설정 대화 상자에서 Model ID 복사

가입하고 BetterToken API Key 받기

이미 계정이 있나요? 로그인하고 잔액을 충전한 다음 콘솔에서 키를 만드세요.

설치하기

Node.js 없이 macOS/Linux 또는 Windows용 공식 독립 설치 프로그램을 사용할 수 있습니다. npm을 사용하려면 Node.js를 먼저 설치한 다음 실행하세요.

npm install -g @openai/codex

파일 위치 확인 및 백업

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

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

명령줄 설정

BetterToken 자동 설정 스크립트는 Codex 제공자 설정을 작성합니다. Node.js가 필요하며 API Key 또는 Model ID를 인수로 전달하지 않으면 직접 입력하라는 메시지가 표시됩니다.

macOS / Linux

curl -fsSL "https://bettertoken.ai/install-codex-provider.sh" | bash

Windows

iwr "https://bettertoken.ai/install-codex-provider.ps1" -OutFile "$env:TEMP\install-codex-provider.ps1"; powershell -ExecutionPolicy Bypass -File "$env:TEMP\install-codex-provider.ps1"

설치 후 두 파일을 아래 수동 설정과 비교하고 차이가 있으면 수정한 뒤 Codex를 시작하세요.

수동 설정

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을 완전히 종료한 다음 다시 열고 새 로컬 작업을 만드세요. 사용하는 각 클라이언트에서 짧은 프롬프트를 보내 정상 응답을 확인하세요.

Codex CLI 0.164.0은 파일 읽기 도구 호출을 포함한 환경 변수 인증 테스트도 통과했습니다. requires_openai_auth = false를 설정했을 때와 이 필드를 생략했을 때 모두 env_key가 작동했습니다。

모델 전환

model을 변경하고 필요하면 review_model도 변경하세요. 파일을 저장하고 현재 Codex 프로세스를 종료한 뒤 다시 시작하세요. 설정 대화 상자 또는 모델 광장의 Model ID를 사용하세요.

흔한 오류

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을 사용하는지 확인하세요.