> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.beatapi.io/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.beatapi.io/_mcp/server. # Codex CLI에서 BeatAPI 사용하기 > Codex CLI에 BeatAPI를 사용자 지정 모델 제공자로 추가해, 터미널 코딩 에이전트가 계정의 모든 모델로 동작하게 합니다. # Codex CLI에서 BeatAPI 사용하기 Codex CLI는 파일을 읽고 쓰고, 명령을 실행하며 작업을 처음부터 끝까지 처리하는 터미널 코딩 에이전트입니다. 제공자와 OpenAI Responses 형식으로 통신하며, BeatAPI가 이 형식을 `POST /v1/responses`에서 제공하므로 프록시 없이 제공자로 추가하면 됩니다. ## 사전 준비 1. **Node.js 설치** — LTS 릴리스, v20 이상. 2. **BeatAPI API 키** — [대시보드 → API Keys](https://beatapi.io/dashboard/apikeys)에서 만드세요. ## 1단계: Codex CLI 설치 #### npm ```bash npm install -g @openai/codex ``` macOS나 Linux에서 권한 오류가 나면 앞에 `sudo`를 붙이세요. #### Homebrew (macOS) ```bash brew install codex ``` 설치를 확인합니다. ```bash codex --version ``` ## 2단계: BeatAPI를 제공자로 추가 Codex CLI는 제공자 설정을 `~/.codex/`(Windows에서는 `C:\Users\\.codex\`)에 보관합니다. 디렉터리가 없으면 `codex`를 한 번 실행하고 `Ctrl + C`를 누르세요. 디렉터리가 자동으로 만들어집니다. ### 2.1 키 `~/.codex/auth.json`을 만들거나 편집합니다. ```json { "OPENAI_API_KEY": "" } ``` ### 2.2 제공자 `~/.codex/config.toml`을 만들거나 편집합니다. ```toml # Default model model = "gpt-5.6-sol" # Default provider — must match the id in [model_providers.] 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와 일치해야 합니다 | | `name` | 표시 이름. 자유롭게 정하세요 | | `base_url` | `https://api.beatapi.io/v1` — `/v1` 접미사를 붙이고 끝에 슬래시 없음 | | `wire_api` | `responses`. 현재 Codex 릴리스에서는 `chat` 프로토콜이 제거되었습니다 | | `requires_openai_auth` | `true`를 지정하면 Codex가 `auth.json`의 키로 인증합니다 | > **Note** > > 제공자 설정은 **사용자 수준**의 `~/.codex/config.toml`에서만 적용됩니다. Codex는 프로젝트 로컬 `.codex/config.toml`의 `model_provider`와 `model_providers`를 무시하고 시작할 때 경고를 표시합니다. `openai`, `ollama`, `lmstudio` id는 예약되어 있으므로, 위 블록은 이를 덮어쓰지 않고 새 id를 정의합니다. 두 파일을 저장한 뒤 Codex CLI를 다시 시작하세요. ### 대안: auth.json 대신 환경 변수 사용 ```toml [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단계: 확인하고 작업 시작 ```bash 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](/text-api)를 참고하세요. 요금은 [가격 페이지](https://beatapi.io/pricing)에 있습니다. > **Note** > > `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` | 종료 | ## 자주 묻는 질문 ### 실행 시 로그인 화면이 나타남 설정을 읽지 못하고 있습니다. 1. 두 파일 모두 프로젝트 디렉터리가 아니라 `~/.codex/`에 있어야 합니다. 2. `model_provider`는 `[model_providers.]`의 id와 정확히 일치해야 합니다. 3. `auth.json`은 올바른 JSON, `config.toml`은 올바른 TOML이어야 합니다. 대개 둥근 따옴표가 원인이니 곧은 따옴표를 쓰세요. ### 401 또는 403 | 상태 | 의미 | 조치 | | ----- | ----------------------------------------------------------------------- | ------------------------------------------------------------------------------ | | `401` | `missing_api_key` 또는 `invalid_api_key`: 키가 없거나 잘못되었거나 만료, 비활성화, 소진되었습니다 | `auth.json`의 키를 [대시보드 → API Keys](https://beatapi.io/dashboard/apikeys)와 비교하세요 | | `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`을 사용해 보세요. ## 지원 [대시보드](https://beatapi.io/dashboard)에서 지원 티켓을 열고 실패한 응답의 `request_id`를 함께 보내 주세요.