# 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 只需兩步：**註冊一個自定義供應商** + **提供 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` — 接口協議，填 `responses`，走 `/v1/responses`。Codex 只支援這一種，填 `chat` 會直接報錯
- `env_key` — 存放 API Key 的環境變量名，下一步會設置

> **TIP**
> 與 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 搜索獲取最新信息：

```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://tw.llmoxy.com/docs/code-tutorials/codex-cli 的 markdown 版本。
