Codex CLI で BeatAPI を使う

Codex CLI は、ファイルの読み書き、コマンド実行、一連の作業を行うターミナルのコーディングエージェントです。BeatAPI が POST /v1/responses で提供する OpenAI Responses 形式で通信するため、プロキシを用意せず、接続先として追加できます。

前提条件

Node.js がインストールされていること。 v20 以降の LTS 版を使います。
BeatAPI API キー。 ダッシュボード → API キーで作成します。

ステップ 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 を作成、または編集します。

# 標準モデル
model = "gpt-5.6-sol"
# 標準の接続先。下の [model_providers.<id>] の ID と一致させます
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`	`/v1` を含み、末尾スラッシュのない `https://api.beatapi.io/v1`
`wire_api`	`responses`。現在の Codex では `chat` プロトコルは削除されている
`requires_openai_auth`	`true` で `auth.json` のキーを使って認証する

接続先の設定はユーザーレベルの ~/.codex/config.toml でのみ有効です。プロジェクト内の .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 を確認してください。

codex だけを実行すると対話画面が開きます。自然言語で作業内容を入力します。

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

Codex はプロジェクトを分析し、コードを作成してコマンドを実行します。慎重な扱いが必要な操作の前には確認します。

承認モード

モード	動作
Read Only	ファイルを読む。書き込みやコマンド実行には確認が必要
Auto	作業ディレクトリ内で読み書きとコマンド実行を行う
Full Access	確認なしで操作する

まず Auto から始めてください。/approvals でいつでも変更できます。

モデル

対話画面の /model、または config.toml の model を変更して再起動すると切り替わります。

モデル ID	用途
`gpt-5.6-sol`	最も高性能なコーディングモデル。Codex の標準選択
`gpt-6-astra`	最新世代。入力トークンが 272K を超えると単価が上がる
`gpt-5.6-terra`	日常作業での性能とコストのバランス
`gpt-5.6-luna`	大量処理向けの高速、低価格モデル

アカウントのすべてのテキストモデルが /v1/responses に対応しており、上記に限定されません。Text API を参照してください。料金は料金ページに掲載しています。

gpt-6-astra と GPT-5.6 シリーズは入力トークンが 272K、grok-4.5、grok-4.6、grok-4.7 は 200K を超えると単価が上がります。長いエージェントセッションでは、ターミナルに通知されないまま境界を超える場合があります。予算を見積もる際は、最新の料金ページと利用記録を確認してください。

よく使うコマンド

コマンド	内容
`codex`	対話画面を開く
`codex "task"`	初期の指示を指定して開始
`codex exec "task"`	非対話で実行し終了
`codex --model gpt-5.6-terra`	モデルを指定して開始
`/model`	画面内でモデルを切り替え
`/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 キーと照合
`403`	`forbidden`。無料クレジットだけの場合など、キーまたはアカウントがモデルを利用できない	アカウントの状態と指定モデルを確認

base_url がモデル提供元の 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 を添えてください。