Codex CLI에서 BeatAPI 사용하기

Codex CLI는 파일을 읽고 쓰고, 명령을 실행하며 작업을 처음부터 끝까지 처리하는 터미널 코딩 에이전트입니다. 제공자와 OpenAI Responses 형식으로 통신하며, BeatAPI가 이 형식을 POST /v1/responses에서 제공하므로 프록시 없이 제공자로 추가하면 됩니다.

사전 준비

Node.js 설치 — LTS 릴리스, v20 이상.
BeatAPI API 키 — 대시보드 → API Keys에서 만드세요.

1단계: Codex CLI 설치

npm

Homebrew (macOS)

npm install -g @openai/codex

macOS나 Linux에서 권한 오류가 나면 앞에 sudo를 붙이세요.

설치를 확인합니다.

codex --version

2단계: BeatAPI를 제공자로 추가

Codex CLI는 제공자 설정을 ~/.codex/(Windows에서는 C:\Users\<you>\.codex\)에 보관합니다. 디렉터리가 없으면 codex를 한 번 실행하고 Ctrl + C를 누르세요. 디렉터리가 자동으로 만들어집니다.

2.1 키

~/.codex/auth.json을 만들거나 편집합니다.

{
  "OPENAI_API_KEY": "<BEATAPI_API_KEY>"
}

2.2 제공자

~/.codex/config.toml을 만들거나 편집합니다.

# Default model
model = "gpt-5.6-sol"
# Default provider — must match the id in [model_providers.<id>] below
model_provider = "beatapi"
[model_providers.beatapi]
name = "BeatAPI"
base_url = "https://api.beatapi.io/v1"
wire_api = "responses"
requires_openai_auth = true

필드	값
`model`	아래 표의 아무 모델 ID
`model_provider`	`[model_providers.<id>]`에서 쓴 id와 일치해야 합니다
`name`	표시 이름. 자유롭게 정하세요
`base_url`	`https://api.beatapi.io/v1` — `/v1` 접미사를 붙이고 끝에 슬래시 없음
`wire_api`	`responses`. 현재 Codex 릴리스에서는 `chat` 프로토콜이 제거되었습니다
`requires_openai_auth`	`true`를 지정하면 Codex가 `auth.json`의 키로 인증합니다

제공자 설정은 사용자 수준의 ~/.codex/config.toml에서만 적용됩니다. Codex는 프로젝트 로컬 .codex/config.toml의 model_provider와 model_providers를 무시하고 시작할 때 경고를 표시합니다. openai, ollama, lmstudio id는 예약되어 있으므로, 위 블록은 이를 덮어쓰지 않고 새 id를 정의합니다.

두 파일을 저장한 뒤 Codex CLI를 다시 시작하세요.

대안: auth.json 대신 환경 변수 사용

[model_providers.beatapi]
name = "BeatAPI"
base_url = "https://api.beatapi.io/v1"
wire_api = "responses"
env_key = "BEATAPI_API_KEY"

그런 다음 셸 프로필에서 BEATAPI_API_KEY를 export하세요. auth.json은 더 이상 필요하지 않습니다. 실수로 커밋하기 쉬운 파일에 키를 두지 않아도 됩니다.

3단계: 확인하고 작업 시작

codex "Introduce yourself in one sentence"

답변이 오면 연결된 것입니다. 로그인 화면, 401 또는 403이 나타나면 연결되지 않은 것이니 FAQ를 참고하세요.

대화형 UI를 쓰려면 codex만 실행한 뒤 일상적인 말로 작업을 설명하세요.

Create an Express.js server with a JSON health check endpoint

Codex가 프로젝트를 분석하고 코드를 작성하며 명령을 실행합니다. 민감한 작업 전에는 먼저 묻습니다.

승인 모드

모드	동작
Read Only	파일을 읽기만 하며, 쓰기나 명령 실행에는 확인이 필요합니다
Auto	작업 디렉터리 안에서 읽기, 쓰기, 명령 실행을 합니다
Full Access	확인을 전혀 묻지 않습니다

Auto로 시작하세요. /approvals로 언제든 바꿀 수 있습니다.

모델

대화형 UI에서 /model로 전환하거나, config.toml의 model을 바꾸고 다시 시작하세요.

모델 ID	추천 용도
`gpt-5.6-sol`	가장 강력한 코딩 등급. Codex의 기본값
`gpt-6-astra`	최신 세대. 입력 토큰이 272K를 넘으면 상위 요금 적용
`gpt-5.6-terra`	일상 작업을 위한 성능과 비용의 균형
`gpt-5.6-luna`	대량 처리 단계를 위한 빠르고 저렴한 등급

계정의 모든 텍스트 모델이 /v1/responses에서 응답하므로 위 목록에 국한되지 않습니다. 텍스트 API를 참고하세요. 요금은 가격 페이지에 있습니다.

gpt-6-astra와 GPT-5.6 계열은 입력 토큰이 272K를 넘으면, grok-4.5, grok-4.6, grok-4.7은 200K를 넘으면 더 높은 요금이 적용됩니다. 긴 에이전트 세션은 터미널에 아무 표시 없이 이 기준을 넘을 수 있으니, 예산을 잡을 때는 최신 가격 페이지와 사용 기록을 확인하세요.

자주 쓰는 명령

명령	설명
`codex`	대화형 UI 시작
`codex "task"`	초기 지시와 함께 시작
`codex exec "task"`	비대화형 — 실행 후 종료
`codex --model gpt-5.6-terra`	특정 모델로 시작
`/model`	UI에서 모델 전환
`/approvals`	승인 모드 변경
`Ctrl + C`	종료

자주 묻는 질문

실행 시 로그인 화면이 나타남

설정을 읽지 못하고 있습니다.

두 파일 모두 프로젝트 디렉터리가 아니라 ~/.codex/에 있어야 합니다.
model_provider는 [model_providers.<id>]의 id와 정확히 일치해야 합니다.
auth.json은 올바른 JSON, config.toml은 올바른 TOML이어야 합니다. 대개 둥근 따옴표가 원인이니 곧은 따옴표를 쓰세요.

401 또는 403

상태	의미	조치
`401`	`missing_api_key` 또는 `invalid_api_key`: 키가 없거나 잘못되었거나 만료, 비활성화, 소진되었습니다	`auth.json`의 키를 대시보드 → API Keys와 비교하세요
`403`	`forbidden`: 키나 계정이 이 모델을 사용할 수 없습니다(예: 무료 크레딧)	계정 상태와 요청한 모델을 확인하세요

base_url이 모델 제조사의 주소가 아니라 https://api.beatapi.io/v1인지도 확인하세요.

`wire_api = "chat"`이 거부됨

현재 Codex 릴리스에서는 Chat Completions 프로토콜이 제거되었습니다. wire_api = "responses"를 설정하고 다시 시작하세요. BeatAPI는 Responses 형식을 제공하므로 다른 설정은 바꿀 필요가 없습니다.

모든 요청에서 404 발생

대부분 기본 URL 문제입니다. /v1으로 끝나야 하며, 끝에 슬래시나 추가 경로가 없어야 합니다.

402 insufficient_credits

잔액 부족: 잔액이 0이거나 요청 가격보다 적습니다. 대시보드에서 충전하세요.

429 rate_limit_exceeded

키의 요청 속도 한도를 넘었습니다. Retry-After 헤더를 따르세요. 분당 한도는 누적 충전액에 따라 올라가며 대시보드에 표시됩니다.

도구 호출 실패

wire_api = "responses"를 확인하세요. 특정 모델이 Codex의 도구 프로토콜에서 계속 오작동하면, 가장 많이 검증된 조합인 gpt-5.6-sol을 사용해 보세요.

지원

대시보드에서 지원 티켓을 열고 실패한 응답의 request_id를 함께 보내 주세요.