> ## 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 for VS Code 使用教程

> Codex 集成指南 - Ace Data Cloud

Codex 是 OpenAI 推出的編程 Agent。除了終端 CLI，它也提供了 VS Code 擴展，可以在編輯器側邊欄裡聊天、閱讀文件、引用上下文、生成修改並預覽變更。

本文介紹如何透過 Ace Data Cloud 的 OpenAI Responses 相容代理，在 VS Code 中配置和使用 Codex 擴展。Codex VS Code 擴展和 Codex CLI 使用同一個本地配置體系，因此只要把 `~/.codex/config.toml` 指向 Ace Data Cloud，即可讓 VS Code 中的 Codex 走 `https://api.acedata.cloud/v1`。

## 申請流程

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

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

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

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

## 安裝 Codex 擴展

在 VS Code 的擴展市場中搜尋 `Codex`，安裝 OpenAI 發布的 **Codex - OpenAI's coding agent** 擴展。它的 Marketplace ID 是：

```text theme={null}
openai.chatgpt
```

也可以在命令列中安裝：

```bash theme={null}
code --install-extension openai.chatgpt
```

安裝完成後，重啟或重新載入 VS Code。如果沒有看到 Codex 入口，可以打開命令面板（macOS：`Cmd+Shift+P`，Windows/Linux：`Ctrl+Shift+P`），搜尋並執行：

```text theme={null}
Codex: Open Codex Sidebar
```

Codex 預設會出現在 VS Code 右側側邊欄。你也可以把它拖回左側 Activity Bar。

## 安裝 Codex CLI（用於驗證）

官方文件說明 Codex VS Code 擴展和 Codex CLI 使用同一套配置層。為了在配置 VS Code 前先驗證 API Token 和模型是否可用，建議同時安裝 Codex CLI。

官方推薦方式之一是透過 npm 安裝，要求 Node.js 18 或更高版本：

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

macOS 用戶也可以透過 Homebrew 安裝：

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

安裝完成後，在終端檢查命令是否可用：

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

如果你只想使用 VS Code 擴展，也可以跳過 CLI 驗證步驟；後續仍然使用同一份 `~/.codex/config.toml` 配置。

## 配置 Ace Data Cloud API

Codex VS Code 擴展和 Codex CLI 共享配置文件。預設情況下，Codex 會提示登入 OpenAI 官方帳號或配置官方 API Key。要改用 Ace Data Cloud，需要配置 API Token 和 `~/.codex/config.toml`。

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

推薦把 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
```

如果 VS Code 已經開啟，請重啟或重新載入 VS Code，讓擴展讀取到新的環境變數。

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

Codex 的使用者級配置文件位於 `~/.codex/config.toml`。如果該文件不存在，可以新建：

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

寫入以下配置：

```toml theme={null}
model_provider = "acedatacloud"
model = "gpt-5"
model_reasoning_effort = "high"
approval_policy = "on-request"
sandbox_mode = "workspace-write"

[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.acedatacloud]` |
| `model`                  | 預設使用的模型 ID                                       |
| `model_reasoning_effort` | 推理強度，常用值為 `low`、`medium`、`high`                  |
| `approval_policy`        | 命令執行前的確認策略，日常使用推薦 `on-request`                   |
| `sandbox_mode`           | Codex 執行命令時的沙箱權限，日常開發推薦 `workspace-write`        |
| `base_url`               | Ace Data Cloud 的 OpenAI 相容 API 地址                |
| `env_key`                | Codex 讀取 API Token 的環境變數名稱                       |
| `wire_api`               | 協議類型，使用 OpenAI Responses API 必須為 `responses`     |

也可以在 Codex 擴展右上角點擊齒輪圖示，選擇 **Codex Settings > Open config.toml**，直接從 VS Code 打開這份配置文件。

### 專案級配置

如果你只想讓某個專案使用不同配置，可以在專案根目錄建立 `.codex/config.toml`。Codex 會優先讀取專案級配置，但專案需要被標記為 trusted 才會載入 `.codex/` 下的配置。

範例：

```toml theme={null}
model = "gpt-5-mini"
model_reasoning_effort = "medium"
```

建議把包含個人 Token 的配置放在環境變數裡，不要寫進專案倉庫。專案級 `.codex/config.toml` 也建議依團隊情況決定是否提交。

## 清理已快取的 OpenAI 登入

如果你之前已經在 Codex 擴展中登入過 OpenAI 官方帳號，本地可能仍然保留官方登入狀態。切換到 Ace Data Cloud 代理前，可以先在終端執行：

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

如果命令不可用，也可以刪除本地快取文件：

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

然後重啟或重新載入 VS Code。

## 基本使用

配置完成後，打開 VS Code 左側或右側的 Codex 面板，直接輸入需求即可。例如：

```text theme={null}
解釋當前專案的目錄結構，並指出主要入口文件。
```

Codex 擴展可以結合編輯器中的文件和選中程式碼作為上下文。你也可以在輸入框中用 `@` 引用文件，例如：

```text theme={null}
參考 @src/App.vue，幫我把這個頁面拆成更清晰的元件。
```

如果選中一段程式碼，可以透過命令面板執行：

```text theme={null}
Codex: Add to Codex Thread
```

也可以執行：

```text theme={null}
Codex: Add File to Codex Thread
```

把整個當前文件加入上下文。

## 切換模型和推理強度

Codex VS Code 擴展支援在輸入框下方的模型切換器中切換模型，也可以調整 reasoning effort。使用 Ace Data Cloud 自訂供應商時，最穩妥的方式是先在 `~/.codex/config.toml` 中寫好預設 `model`，再按需在介面裡切換。推薦預設使用：

| 場景          | 推薦模型                      | 推理強度     |
| ----------- | ------------------------- | -------- |
| 日常程式碼閱讀和小修改 | `gpt-5-mini`              | `medium` |
| 常規開發任務      | `gpt-5`                   | `high`   |
| 複雜重構和深度推理   | `gpt-5.5` 或 `gpt-5.5-pro` | `high`   |
| 推理增強任務      | `o3`                      | `high`   |

如果介面裡沒有顯示你想要的模型，可以直接修改 `~/.codex/config.toml` 中的 `model` 欄位，然後重啟或重新載入 VS Code。完整模型列表可參考 [Ace Data Cloud OpenAI 服務文件](https://platform.acedata.cloud/documents/openai)。

## 選擇工作模式

Codex 擴展支援不同工作模式。常見模式如下：

| 模式                    | 適用場景                             |
| --------------------- | -------------------------------- |
| `Chat`                | 只想討論、解釋程式碼、先做計畫，不希望 Codex 直接改文件  |
| `Agent`               | 讓 Codex 閱讀文件、修改程式碼、執行必要命令，日常開發推薦 |
| `Agent (Full Access)` | 允許更高權限和網路存取，適合你明確知道風險的場景         |

日常建議使用 `Agent`，並保留 `approval_policy = "on-request"`。這樣 Codex 在需要執行敏感命令、存取工作區外路徑或網路時，會先詢問確認。

## 驗證配置

可以先在終端用同一套配置驗證 Codex 是否能透過 Ace Data Cloud 工作：

```bash theme={null}
codex exec --model gpt-5-mini "Reply with exactly: ADC_Codex_OK"
```

如果配置正確，應能看到類似回覆：

```text theme={null}
ADC_Codex_OK
```

然後回到 VS Code，打開 Codex 面板，輸入一個簡單問題：

```text theme={null}
用一句話說明當前工作區的用途。
```

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

## 工作原理

Codex VS Code 擴展並不是獨立的一套模型配置。它使用本機 Codex CLI，並共享 Codex 的配置層：

1. VS Code 擴展啟動 Codex，並讀取使用者級 `~/.codex/config.toml`。
2. 如果當前專案被信任，並且專案裡存在 `.codex/config.toml`，Codex 會再載入專案級配置。
3. 當 `model_provider` 指向 `acedatacloud` 時，Codex 從 `ACEDATACLOUD_API_KEY` 讀取 API Token。
4. 請求透過 OpenAI Responses 協議發送到 `https://api.acedata.cloud/v1/responses`。
5. Ace Data Cloud 驗證身份、檢查額度、轉發請求，並記錄用量。

因此，終端 CLI 和 VS Code 擴展通常只需要配置一次。你在終端驗證通過後，VS Code 擴展也會使用同一份配置。

## 了解更多

* [Codex IDE extension 官方文件](https://developers.openai.com/codex/ide)
* [Codex IDE extension 設定參考](https://developers.openai.com/codex/ide/settings)
* [Codex CLI 配置基礎](https://developers.openai.com/codex/config-basic)
* [Ace Data Cloud OpenAI 服務文件](https://platform.acedata.cloud/documents/openai)