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

## 前提条件

1. **Node.js がインストールされていること。** v20 以降の LTS 版を使います。
2. **BeatAPI API キー。** [ダッシュボード → API キー](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\<you>\.codex\`）にあります。存在しなければ、`codex` を一度実行し `Ctrl + C` で終了すると作成されます。

### 2.1 キー

`~/.codex/auth.json` を作成、または編集します。

```json
{
  "OPENAI_API_KEY": "<BEATAPI_API_KEY>"
}
```

### 2.2 接続先

`~/.codex/config.toml` を作成、または編集します。

```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` のキーを使って認証する                 |

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

`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](/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`                       | 対話画面を開く      |
| `codex "task"`                | 初期の指示を指定して開始 |
| `codex exec "task"`           | 非対話で実行し終了    |
| `codex --model gpt-5.6-terra` | モデルを指定して開始   |
| `/model`                      | 画面内でモデルを切り替え |
| `/approvals`                  | 承認モードを変更     |
| `Ctrl + C`                    | 終了           |

## よくある質問

### 起動するとログイン画面が表示されます

設定が読み込まれていません。

1. 両方のファイルはプロジェクト内ではなく `~/.codex/` に配置します。
2. `model_provider` と `[model_providers.<id>]` の ID を完全に一致させます。
3. `auth.json` は有効な JSON、`config.toml` は有効な TOML にします。装飾付き引用符がよくある原因です。通常の引用符を使ってください。

### 401 または 403

| ステータス | 意味                                                                | 対処                                                                          |
| ----- | ----------------------------------------------------------------- | --------------------------------------------------------------------------- |
| `401` | `missing_api_key` または `invalid_api_key`。キーが未指定、不正、期限切れ、無効、または上限到達 | `auth.json` のキーを[ダッシュボード → API キー](https://beatapi.io/dashboard/apikeys)と照合 |
| `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` を試してください。

## サポート

[ダッシュボード](https://beatapi.io/dashboard)からチケットを作成し、失敗したレスポンスの `request_id` を添えてください。