Codex에 OpenAI-compatible API 연결하기

사전 준비

• 공식 Codex CLI 설치에 필요한 Node.js와 npm
• 본인의 BetterToken 계정, 본인 전용 API Key, Setup 또는 model plaza의 최신 전체 Model ID
• 짧은 요청 한 번을 실행할 수 있는 잔액 또는 사용 가능한 테스트 한도
• macOS/Linux 터미널 또는 Windows PowerShell. 아래에 두 환경의 명령을 모두 제공합니다.
• 다른 provider를 사용하는 경우 Responses API, SSE streaming, 필요한 tool calls 지원 여부에 대한 확인

설정 전에 호환성 확인하기

Provider가 Chat Completions 예제만 보여 주고 Responses API는 설명하지 않는다면 먼저 지원 여부를 확인하거나 작은 요청으로 테스트하세요. 일반 채팅 클라이언트의 설정을 검증 없이 Codex로 옮기지 마세요.

단계 1. Codex CLI 설치 또는 업데이트하기

npm install -g @openai/codex
codex --version

현재 설정 필드는 공식 Codex Config Reference에서 확인하세요. 2026년 8월 14일 기준으로 model_provider는 model_providers의 항목을 선택하고, env_key는 키를 담은 환경 변수를 지정하며, wire_api에서 지원하는 유일한 값은 responses입니다.

단계 2. 독립된 profile 파일 만들기

현재 OpenAI Config Reference에서는 이름이 있는 profile을 $CODEX_HOME/bt.config.toml에 저장합니다. 기본적으로 CODEX_HOME은 macOS/Linux에서 보통 ~/.codex, Windows에서 %USERPROFILE%\.codex에 해당하지만, 사용자가 값을 지정했다면 그 값이 우선하며 실제 경로도 달라집니다.

macOS/Linux에서 변수를 변경하지 않고 디렉터리를 확인하세요.

printf '%s\n' "${CODEX_HOME:-$HOME/.codex}"

PowerShell에서는 다음을 실행합니다.

if ($env:CODEX_HOME) { $env:CODEX_HOME } else { Join-Path $env:USERPROFILE ".codex" }

표시된 디렉터리에 bt.config.toml을 정확히 만드세요.

model = "YOUR_MODEL_ID"
model_provider = "bettertoken"

[model_providers.bettertoken]
name = "BetterToken"
base_url = "https://www.bettertoken.ai/v1?utm_source=blog&utm_medium=organic_content&utm_campaign=SEO-016&utm_content=openai-sovmestimyy-api-codex-podklyuchenie"
env_key = "BETTERTOKEN_API_KEY"
wire_api = "responses"
requires_openai_auth = false
request_max_retries = 4
stream_max_retries = 8
stream_idle_timeout_ms = 300000
supports_websockets = false

$CODEX_HOME/bt.config.toml 파일은 --profile bt 명령과 대응합니다. 이 profile은 기본 $CODEX_HOME/config.toml을 대체하지 않으므로 공식 provider도 계속 사용할 수 있습니다.

YOUR_MODEL_ID를 Setup, model plaza 또는 현재 가이드에 표시되고 본인 키에서 사용할 수 있는 최신 전체 API ID로 바꾸세요. 모델 제목의 표시 이름이 API ID와 다르면 표시 이름을 사용하지 마세요.

Codex가 provider 주소 뒤에 /responses를 자동으로 붙이므로 Base URL은 /v1/responses가 아니라 /v1으로 끝나야 합니다. 전체 경로를 넣으면 경로가 중복될 수 있습니다.

단계 3. 환경 변수로 API Key 전달하기

macOS/Linux:

export BETTERTOKEN_API_KEY="YOUR_API_KEY"

영구 설정에는 보호된 secret manager 또는 적절한 권한을 적용한 shell 초기화 파일을 사용하세요. 키를 저장소, .env.example, README 또는 공용 컴퓨터의 shell history에 남는 명령에 넣지 마세요.

값을 출력하지 않고 변수가 설정됐는지 확인합니다.

test -n "$BETTERTOKEN_API_KEY" && echo "BETTERTOKEN_API_KEY is set"

Windows PowerShell에서는 현재 창에 값을 지정하고 다음 세션에서도 사용할 수 있도록 저장합니다.

$env:BETTERTOKEN_API_KEY = "YOUR_API_KEY"
[Environment]::SetEnvironmentVariable("BETTERTOKEN_API_KEY", "YOUR_API_KEY", "User")
if ($env:BETTERTOKEN_API_KEY) { "BETTERTOKEN_API_KEY is set" }

단계 4. Codex CLI에서 profile 실행 후 요청 검증하기

Codex CLI를 다시 시작하고 다음을 실행하세요.

codex --profile bt

첫 테스트는 짧아야 하며 파일을 변경하면 안 됩니다.

한 줄로 답하세요: CODEX_PROVIDER_OK. 파일을 변경하거나 명령을 실행하지 마세요.

오류 없이 응답이 도착하고 모델이 선택한 Model ID와 일치하며, 테스트 후 새 요청의 모델, 상태, 사용량이 BetterToken Workspace에 표시되면 연결을 확인할 수 있습니다. 정상 응답만으로는 실제 처리 경로를 증명할 수 없으므로 사용량 기록도 확인하세요. 그다음 테스트 파일 하나만 읽어 보고, 이 읽기 전용 점검이 성공한 뒤에만 작업 저장소를 여세요.

Codex Desktop은 동일한 custom provider 필드를 사용하지만, 구성 선택 및 실행 방법은 현재 BetterToken 가이드에서 확인해야 합니다. CLI의 --profile 명령이 그대로 적용된다고 가정하지 마세요. VS Code Extension은 별도 가이드를 따르고, 확인 없이 CLI profile이나 인증 방식을 옮기지 마세요.

오류 유형별 진단

Profile을 찾지 못하거나 구성이 적용되지 않음

세 항목이 정확히 일치하는지 확인하세요. 파일 이름은 bt.config.toml이어야 하고, 명령에는 --profile bt가 있어야 하며, model_provider = "bettertoken"은 [model_providers.bettertoken] 테이블과 일치해야 합니다. 그런 다음 Codex CLI를 완전히 종료하고 새 터미널을 열어 짧은 테스트를 반복하세요.

기존 OpenAI 환경 변수가 예상 경로를 덮어쓸 수 있습니다. macOS/Linux에서는 값을 출력하지 말고 설정 여부만 확인하세요.

test -n "$OPENAI_API_KEY" && echo "OPENAI_API_KEY is set"
test -n "$OPENAI_BASE_URL" && echo "OPENAI_BASE_URL is set"
unset OPENAI_API_KEY OPENAI_BASE_URL

PowerShell에서는 현재 세션과 이후 사용자 세션에서 해당 변수를 제거합니다.

Remove-Item Env:OPENAI_API_KEY -ErrorAction SilentlyContinue
Remove-Item Env:OPENAI_BASE_URL -ErrorAction SilentlyContinue
[Environment]::SetEnvironmentVariable("OPENAI_API_KEY", $null, "User")
[Environment]::SetEnvironmentVariable("OPENAI_BASE_URL", $null, "User")

정리한 뒤 새 터미널을 열고 BETTERTOKEN_API_KEY만 다시 설정한 다음 codex --profile bt를 실행하세요.

404 또는 JSON 대신 HTML이 반환됨

대부분 endpoint 경로가 잘못 조합된 경우입니다. base_url에 /responses, /chat/completions 또는 불필요한 proxy 경로가 없는지 확인하세요. BetterToken에서는 정확히 `https://www.bettertoken.ai/v1%60%EC%9D%B4%EC%96%B4%EC%95%BC?utm_source=blog&utm_medium=organic_content&utm_campaign=SEO-016&utm_content=openai-sovmestimyy-api-codex-podklyuchenie 합니다.

401 또는 403

env_key 이름, 같은 프로세스에서 환경 변수를 사용할 수 있는지, 선택한 모델에 본인 키로 접근할 수 있는지 확인하세요. 키가 log에 노출됐을 가능성이 있다면 해당 키를 revoke하고 새로 만드세요.

model not found

Setup, model plaza 또는 현재 가이드에서 최신 전체 Model ID를 다시 복사하고 본인 키에서 사용할 수 있는지 확인하세요. Version suffix를 추측하거나 오래된 group 이름을 영구적인 이름으로 간주하지 마세요.

Chat Completions 또는 지원하지 않는 필드 오류

wire_api = "responses"인지, provider가 필요한 Codex 기능을 포함한 Responses API를 실제로 구현하는지 확인하세요. 값을 chat으로 바꿔도 해결되지 않습니다. 현재 Codex reference는 responses만 지원합니다.

Stream이 시작된 뒤 중간에 끊김

먼저 작은 요청 하나를 다시 실행하세요. 그다음 proxy, timeout, SSE 지원 여부를 확인합니다. 제한 없이 retry 횟수를 늘리면 중복 요청과 추가 사용량이 발생할 수 있습니다.

공식 설정을 잃지 않고 되돌리기

Provider를 독립된 $CODEX_HOME/bt.config.toml로 분리했으므로 현재 Codex CLI 세션을 종료하고 --profile bt 없이 다시 실행하세요. 그러면 기본 $CODEX_HOME/config.toml이 다시 적용됩니다. auth.json을 삭제하거나 공식 token을 타사 API Key로 바꾸지 마세요. Codex Desktop은 현재 BetterToken 가이드에서 되돌리는 방법을 확인하고, VS Code Extension은 별도 가이드의 절차를 따르세요.

최종 확인

Codex 연결에는 “OpenAI-compatible” URL만으로는 부족합니다. Responses API, 올바른 Base URL, 사용할 수 있는 Model ID, 환경 변수의 키라는 네 요소가 모두 맞아야 합니다. 독립된 profile에 설정하고 읽기 전용 테스트를 실행한 뒤 Workspace의 새 요청을 확인한 다음 작업 저장소를 여세요.

오래된 필드나 mapping을 복사하지 않으려면 BetterToken의 최신 Codex 설정 가이드를 확인하고 본인 API Key를 만든 뒤 Codex CLI의 bt profile로 첫 읽기 전용 요청을 보내세요.