# Codex CLI 設定ガイド

> ~/.codex/config.toml でカスタムモデルプロバイダーを設定し、Codex CLI を LLMoxy ゲートウェイに接続して、Grok 4.7 などのモデルでターミナルプログラミングを行います。

> **📌 Codex CLI について**
> Codex CLI は OpenAI 公式のターミナルコーディングエージェントで、Rust で記述されており、ローカルでコードを読み取り、変更し、実行できます（[オープンソース](https://github.com/openai/codex)）。デフォルトで OpenAI に接続しますが、`model_provider` のカスタマイズをサポートしているため、LLMoxy ゲートウェイにシームレスに接続し、Grok 4.7 などのモデルを使用できます。

## インストール手順

### 1. Node.js のインストール

[Node.js 公式サイト](https://nodejs.org/) にアクセスし、左側の LTS バージョンをダウンロードすることを推奨します。これは長期サポート版で、より安定しています。

### 2. Codex CLI のインストール

コマンドラインを開き、npm でグローバルインストール：

```bash
npm install -g @openai/codex
```

macOS ユーザーは Homebrew も使用可能：

```bash
brew install codex
```

インストールを検証：

```bash
codex --version
```

Codex CLI は macOS、Linux、Windows をサポートします。Windows ユーザーは PowerShell でネイティブ実行するか、WSL2 で Linux ネイティブ環境を利用することを推奨します。

## 設定手順

Codex CLI の設定ファイルは `~/.codex/config.toml` にあります（Windows: `%USERPROFILE%\.codex\config.toml`）。LLMoxy への接続は 2 ステップのみ：**カスタムプロバイダーを登録** + **API Key を提供**。

### 1. API Key を取得

[LLMoxy コンソール](https://llmoxy.com/) → API Key 管理 → 秘密鍵をコピー。

> 注意：**auto** グループのトークンを使用してください。

### 2. config.toml を書き込み

`~/.codex/config.toml` に以下を追加（ファイルが存在しない場合は新規作成）：

```toml
# デフォルトで LLMoxy プロバイダーとモデルを使用
model = "grok-4.7"
model_provider = "llmoxy"

[model_providers.llmoxy]
name = "LLMoxy"
base_url = "https://llmoxy.com/v1"
wire_api = "responses"
env_key = "LLMOXY_API_KEY"
```

**設定項目の説明：**

- `model` — デフォルトのモデル名。LLMoxy がサポートするモデルを入力（例：`grok-4.7`）
- `model_provider` — 下記で定義したプロバイダー ID を指す
- `base_url` — LLMoxy ゲートウェイアドレス。**末尾に `/v1` あり**
- `wire_api` — `/v1/responses` を使うため `responses` を指定。Codex が対応しているのはこの値だけで、`chat` はエラーになります
- `env_key` — API Key を保存する環境変数名。次のステップで設定

> **ヒント**
> Claude Code とは異なり、Codex CLI の `base_url` は **末尾に `/v1` が必要** です。

### 3. API Key 環境変数を設定

`env_key` で指定した環境変数には、システムで実際の Key を設定する必要があります。

**Windows（PowerShell、永続的）：**

```powershell
[Environment]::SetEnvironmentVariable("LLMOXY_API_KEY","あなたの LLMoxy API Key","User")
```

設定後、**PowerShell を閉じて新しいウィンドウを開く** と読み込まれます。

**macOS / Linux：**

```bash
{
echo ''
echo '# LLMoxy'
echo 'export LLMOXY_API_KEY="あなたの LLMoxy API Key"'
} >> ~/.zshrc   # Bash ユーザーの場合は ~/.bashrc に変更
source ~/.zshrc
```

検証：

```bash
echo "$LLMOXY_API_KEY"
```

`あなたの LLMoxy API Key` を [LLMoxy コンソール](https://llmoxy.com/) からコピーした実際の Key に **必ず** 置き換えてください。

### 4. 起動

プロジェクトディレクトリに入り、インタラクティブセッションを開始：

```bash
codex
```

正常に会話してタスクを実行できれば、LLMoxy への接続に成功しています。

## よく使う操作

### モデルと推論強度の切り替え

セッション中に `/model` を入力してモデルを切り替えたり、推論強度（reasoning effort）を調整したりできます。起動時に `-m` で指定することも可能：

```bash
codex -m grok-4.7
```

### 承認モード（Approval modes）

Codex はファイル編集やコマンド実行前に確認を求めます。セッション中に `/approvals` で切り替えたり、起動時に指定したりできます：

```bash
codex --ask-for-approval      # 毎ステップ確認（デフォルト、最も安全）
codex --full-auto             # 自動実行。ワークディレクトリ内、ネットワーク制限付きサンドボックスでのみ実行
```

> **💡 ヒント**
> 初めてプロジェクトディレクトリで実行する際、Codex はそのディレクトリを信頼するかどうかを尋ねます。

### スクリプト化実行（非インタラクティブ）

`exec` サブコマンドでワンオフのタスクを Codex に任せます。スクリプトや CI から呼び出すのに適しています：

```bash
codex exec "main.go の ParseConfig に単体テストを追加"
```

### 画像入力

スクリーンショットやデザイン原稿を添付して、Codex に画像と組み合わせて要件を理解させることができます：

```bash
codex -i screenshot.png "このデザイン原稿に従ってログインページを実装"
```

### Web 検索

Web 検索を有効にして最新情報を取得：

```bash
codex --search
```

### MCP ツールへの接続

`config.toml` で `[mcp_servers.*]` を介して MCP サービスを登録し、Codex にサードパーティツールとコンテキストを提供します。この設定は LLMoxy プロバイダー設定と共存可能です：

```toml
[mcp_servers.chrome-devtools]
command = "npx"
args = ["chrome-devtools-mcp@latest"]
```

## よくある問題

### `npm install -g` 権限エラー

`sudo npm install -g` は使用しないでください。nvm で Node.js を管理することを推奨します。または npm グローバルディレクトリを変更：

```bash
npm config set prefix ~/.npm-global
```

その後 `~/.npm-global/bin` を PATH に追加。macOS ユーザーは Homebrew 経由で Node.js をインストールすることも可能（sudo 不要）。

### 起動後も OpenAI アカウントへのログインを要求される

`config.toml` で `model_provider = "llmoxy"` が有効になっており、`LLMOXY_API_KEY` 環境変数が設定されていることを確認。カスタムプロバイダーを設定後、Codex は API Key 認証を使用し、ChatGPT ログインは不要です。

### エラー 404 / モデルが存在しない

- `base_url` に `/v1` が含まれていることを確認：`https://llmoxy.com/v1`
- `model` に LLMoxy がサポートするモデル名が入力されていることを確認
- `wire_api = "responses"` になっているか確認してください。Codex は `chat` に対応しておらず、古い手順の `wire_api = "chat"` はエラーになります

### 環境変数が有効にならない

- Windows：`SetEnvironmentVariable(...,"User")` は **ターミナルを再度開く** と読み込まれる
- macOS / Linux：`source ~/.zshrc`（または `~/.bashrc`）を実行するか、ターミナルを再度開き、`echo "$LLMOXY_API_KEY"` で検証

### API 呼び出し失敗 / 残高問題

- API Key に余分なスペースがないことを確認
- [LLMoxy コンソール](https://llmoxy.com/) でアカウント残高とトークングループを確認（**auto** グループの使用を推奨）

### リモートサーバー接続タイムアウト（Linux）

- ネットワークを確認：`curl -I https://llmoxy.com`
- プロキシが必要な場合は、`HTTPS_PROXY` 環境変数を設定

これは https://jp.llmoxy.com/docs/code-tutorials/codex-cli の markdown 版です。
