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

# Codex CLI 終端使用教程

> Codex 集成指南 - Ace Data Cloud

Codex CLI 是 OpenAI 推出的開源本地編程 Agent，運行在你的終端裡。它可以閱讀代碼、修改文件、執行命令、解釋錯誤，並協助完成日常開發任務。

Codex CLI 支援自訂模型供應商，你可以透過 Ace Data Cloud 提供的 OpenAI Responses 相容代理來使用它，無需單獨訂閱 OpenAI 官方帳號。配置完成後，Codex CLI 會把請求發送到 `https://api.acedata.cloud/v1`。

## 申請流程

要使用 Codex CLI，首先可以到 [Ace Data Cloud 控制台](https://platform.acedata.cloud/console/applications)，獲取您的 API Token，留作備用。

![](https://cdn.acedata.cloud/5hmkdg.jpg)

如果你尚未登入或註冊，會自動跳轉到登入頁面邀請您來註冊和登入，登入註冊之後會自動返回當前頁面。

在首次申請時會有免費額度贈送，可以免費體驗 Codex CLI 服務。

## 安裝 Codex CLI

Codex CLI 支援 macOS、Linux、Windows 和 WSL。你可以透過 npm 安裝，也可以使用 Homebrew（僅 macOS）。

### npm 安裝（推薦）

如果你已經安裝了 Node.js，可以直接透過 npm 安裝。該方式要求 Node.js 18 或更高版本。

```bash theme={null}
npm install -g @openai/codex
```

### Homebrew 安裝（macOS）

macOS 用戶也可以使用 Homebrew 安裝：

```bash theme={null}
brew install --cask codex
```

### 檢查安裝

安裝完成後，重新打開終端，然後檢查命令是否可用：

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

如果提示 `command not found`，通常是當前終端還沒有載入新的 PATH。請關閉並重新打開終端，或檢查安裝腳本輸出中提示的 PATH 配置。

## 配置 Codex CLI

安裝完成後，Codex CLI 預設會嘗試連接 OpenAI 官方服務。要改用 Ace Data Cloud，需要在 Codex 的配置文件中聲明一個自訂的 `model_provider`，並把 API Token 放到對應的環境變數裡。

### 第一步：設定環境變數

推薦把 API Token 寫入 Shell 配置文件，例如 `~/.zshrc`、`~/.bashrc` 或 `~/.bash_profile`：

```bash theme={null}
export ACEDATACLOUD_API_KEY="{token}"
```

其中 `{token}` 替換為您在 Ace Data Cloud 控制台複製的 API Token。

配置後重新打開終端，或執行對應的 `source` 命令讓配置立即生效：

```bash theme={null}
source ~/.zshrc
```

### 第二步：編輯 Codex 配置文件

Codex CLI 使用 `~/.codex/config.toml` 作為全局配置文件。如果該文件不存在，可以新建它：

```bash theme={null}
mkdir -p ~/.codex
touch ~/.codex/config.toml
```

把以下內容寫入 `~/.codex/config.toml`：

```toml theme={null}
model_provider = "acedatacloud"
model = "gpt-5"
model_reasoning_effort = "high"

[model_providers.acedatacloud]
name = "Ace Data Cloud"
base_url = "https://api.acedata.cloud/v1"
env_key = "ACEDATACLOUD_API_KEY"
wire_api = "responses"
```

各欄位說明如下：

| 欄位                                        | 說明                                               |
| ----------------------------------------- | ------------------------------------------------ |
| `model_provider`                          | 預設使用的供應商名稱，對應下方 `[model_providers.<name>]` 的 key |
| `model`                                   | 預設使用的模型 ID                                       |
| `model_reasoning_effort`                  | 推理強度，常用值為 `low`、`medium`、`high`                  |
| `[model_providers.acedatacloud].base_url` | Ace Data Cloud 的 OpenAI Responses 代理地址           |
| `[model_providers.acedatacloud].env_key`  | Codex CLI 讀取 API Token 的環境變數名稱                   |
| `[model_providers.acedatacloud].wire_api` | 協議類型，使用 OpenAI Responses API 必須為 `responses`     |

### 清理已快取的 OpenAI 登入

如果你之前已經用 OpenAI 官方帳號登入過 Codex CLI，本地可能快取了官方登入狀態（通常保存在 `~/.codex/auth.json`）。切換到 Ace Data Cloud 代理前，建議先清理一次舊登入：

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

如果 `codex logout` 指令不可用，也可以手動刪除快取文件：

```bash theme={null}
rm -f ~/.codex/auth.json
```

如果你從未登入過 OpenAI 官方帳號，可以跳過這一步。

### 啟動會話

進入你的專案目錄，然後啟動 Codex CLI：

```bash theme={null}
cd /path/to/your/project
codex
```

看到 Codex 的互動介面後，就可以直接輸入需求，例如：

```text theme={null}
解釋這個專案的目錄結構
```

### 驗證配置

進入 Codex CLI 後，可以在互動介面查看當前模型和供應商：

```text theme={null}
/model
```

你應該能看到當前模型來自 `acedatacloud` 這個供應商，例如：

```text theme={null}
Model: gpt-5
Provider: acedatacloud
```

如果顯示的供應商不是 `acedatacloud`，說明配置沒有生效。請重新檢查 `~/.codex/config.toml` 是否保存成功，以及 `ACEDATACLOUD_API_KEY` 是否在當前終端可讀：

```bash theme={null}
echo $ACEDATACLOUD_API_KEY
```

你也可以透過 [Ace Data Cloud 控制台 - 使用歷史](https://platform.acedata.cloud/console/usages) 查看請求記錄和扣費詳情，透過 [Ace Data Cloud 控制台 - 應用列表](https://platform.acedata.cloud/console/applications) 查看剩餘額度。

## 工作原理

Codex CLI 原生使用 OpenAI Responses API 協議。Ace Data Cloud 在 `https://api.acedata.cloud/v1/responses` 提供相容 OpenAI Responses API 的代理服務，因此 Codex CLI 不需要本地代理程式，也不需要額外外掛。

工作流程如下：

1. Codex CLI 從 `~/.codex/config.toml` 讀取 `model_provider`，並載入對應的 `[model_providers.acedatacloud]` 配置區塊。
2. Codex CLI 從 `env_key` 指定的環境變數（`ACEDATACLOUD_API_KEY`）讀取 API Token。
3. 請求透過 `wire_api = "responses"` 協議，發送到 `base_url + /responses`，即 `https://api.acedata.cloud/v1/responses`。
4. Ace Data Cloud 使用您的 API Token 驗證身份、檢查額度，並把請求轉發到可用的上游模型通道。
5. 請求完成後，平台根據實際使用量記錄用量並扣減額度。

這意味著你仍然使用原版 `codex` 指令和 Codex CLI 的原生互動體驗，只是把底層模型服務切換為 Ace Data Cloud。

## 配置模型

`~/.codex/config.toml` 中的 `model` 欄位決定 Codex 預設使用的模型。Ace Data Cloud 的 OpenAI Responses 服務支援多種模型，常用包括：

| 模型                 | 說明                 |
| ------------------ | ------------------ |
| `gpt-5`            | 推薦預設模型，適合大多數編碼任務   |
| `gpt-5-mini`       | 更輕量、響應更快，適合簡單任務    |
| `gpt-5.5`          | 更新版本，能力更強          |
| `gpt-5.5-pro`      | 增強版本，適合複雜推理任務      |
| `gpt-4.1`          | 上一代主力模型            |
| `o3`               | 推理增強模型，適合需要深度推理的任務 |
| `o4-mini-high-all` | 輕量推理模型             |

如果想臨時切換模型，可以在啟動 Codex 時透過命令列參數指定：

```bash theme={null}
codex --model gpt-5-mini
```

也可以直接修改 `~/.codex/config.toml` 中的 `model` 欄位後重新啟動。完整的模型列表可以參考 [Ace Data Cloud OpenAI 服務文件](https://platform.acedata.cloud/documents/openai)。

## 專案信任等級

Codex CLI 支援為不同專案設定不同的信任等級，控制 Agent 可以執行哪些操作。可以在 `~/.codex/config.toml` 末尾追加：

```toml theme={null}
[projects."/path/to/trusted/project"]
trust_level = "trusted"

[projects."/path/to/untrusted/project"]
trust_level = "untrusted"
```

其中：

* `trusted`：Agent 擁有完整權限，可以執行命令、修改文件。
* `untrusted`：Agent 僅有受限權限，更適合不熟悉的專案。

## 了解更多

* [Codex CLI 官方倉庫](https://github.com/openai/codex)
* [Ace Data Cloud OpenAI 服務文件](https://platform.acedata.cloud/documents/openai)
* [Ace Data Cloud 控制台](https://platform.acedata.cloud/console/applications)