> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mixroute.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# codex

## 1. 介紹

本文件旨在指導使用者將 **Codex CLI** 成功接入 **Mixroute**。Codex CLI 是一款執行在終端機中的命令列 AI 輔助程式設計工具。透過修改其官方的設定目錄 `~/.codex` 下的設定檔，您可以建立穩定且易於管理的多模型接入環境。

## 2. 接入前的準備

在進行設定之前，請確保您已經完成了以下準備工作：

1. **安裝 Codex CLI**：確保您的開發環境中已經全域安裝了該工具套件。
2. **取得 Mixroute 憑證 (API Key)**：
   * 造訪 Mixroute 官方控制台並註冊/登入您的帳號。
   * 找到 API 金鑰管理頁面，產生並複製您的專屬 **API Key**（通常以 `sk-` 開頭）。
3. **確認網路連線**：確保您的開發裝置目前的網路環境可以正常連線至 Mixroute 的服務位址：`https://api.mixroute.ai`。

## 3. 設定階段

Codex CLI 的核心設定位於使用者目錄下的 `.codex` 資料夾中。設定主要涉及兩個檔案：`config.toml` (負責介面與模型參數) 和 `auth.json` (負責安全儲存金鑰)。

### 3.1 找到或建立設定目錄

**Windows 使用者：** 鍵盤按下 `Win+R` 鍵，輸入 `%userprofile%\.codex` 後 Enter。

**MacOS / Linux 使用者：** 在終端機輸入或透過檔案管理員存取 `~/.codex`。

*重要提示：如果您是首次安裝 Codex CLI，該目錄或其中的檔案可能不存在，請手動建立該目錄及以下提到的兩個檔案。*

### 3.2 設定 Config.toml

建立或編輯 `.codex/config.toml` 檔案，將以下 Mixroute 的設定內容複製並儲存：

```toml theme={null}
# 設定全域預設的提供商為 mixroute
model_provider = "mixroute"
# 設定預設使用的模型（根據 Mixroute 平台支援的模型填寫，例如 gpt-5.5, claude-sonnet-5 等）
model = "openai/gpt-5.5"
model_reasoning_effort = "high"
disable_response_storage = true
model_verbosity = "high"

[model_providers.mixroute]
name = "mixroute API Gateway"
base_url = "https://api.mixroute.ai/v1"
# 使用相容的 chat 介面
wire_api = "chat"
# 第三方網關建議關閉強制 sk- 驗證
requires_openai_auth = false
```

> **注意：**
>
> 1. `base_url` 必須以 `/v1` 結尾，且不要帶尾隨斜線。
> 2. `wire_api` 建議保持為 `"chat"`，因為大多數第三方中繼網關實作的是 `/chat/completions`。如果遇到 404 錯誤，可嘗試修改為 `"responses"` 視平台具體相容情況而定。

### 3.3 設定 auth.json

建立或編輯 `.codex/auth.json` 檔案。為了安全，不要將 API Key 直接寫在 TOML 檔案中，而是存放在此 JSON 檔案裡：

```json theme={null}
{
  "OPENAI_API_KEY": "sk-您的Mixroute金鑰xxxxxxxxxxxx"
}
```

請將 `"sk-您的Mixroute金鑰xxxxxxxxxxxx"` 替換為您在準備階段取得的真實 Mixroute API Key。

## 4. 驗證與測試

設定完成後，請在終端機中喚起 Codex CLI，進行對話測試：

```bash theme={null}
codex
```

當終端機出現互動介面時，嘗試輸入一段簡單的測試提示詞（例如：「你好，請寫一個 Python 的 hello world 指令碼」）。

* 如果 Codex 能夠正常回應，則說明接入 Mixroute 已成功。
* 如果遇到報錯（如未授權或連線失敗），請仔細檢查 `auth.json` 中的金鑰格式是否正確（包含雙引號），以及 `config.toml` 中的 `base_url` 是否準確填寫了 `https://api.mixroute.ai/v1`。