Codex 安裝並不難，真正容易卡住的是接入：API Key 放在哪裡、config.toml 怎麼寫、Windows 和 macOS 有什麼區別、VS Code 為什麼讀不到終端裡的變數、模型要不要固定……

如果你只想盡快把 Codex 跑起來，可以把配置收斂為三個值：

Provider: acedatacloud
Base URL: https://api.acedata.cloud/v1
API Key env: ACEDATACLOUD_API_KEY

完成後，Codex CLI、Desktop 和 VS Code 擴展可以共享 ~/.codex/config.toml，模型則在啟動後直接選擇，不需要為了換模型不斷改接入配置。

下面從零開始完成一次配置。

準備工作

開始前請確認：

  • 已註冊並登入 Ace Data Cloud
  • 已建立或擁有一個可用應用
  • 本機已安裝 Node.js 與 npm
  • 能夠使用終端或 PowerShell
  • 準備使用 Codex CLI、Codex Desktop 或 VS Code 擴展中的至少一種

第一步：取得 Ace Data Cloud API Key

打開 Ace Data Cloud 應用列表，進入可用應用並複製 API Key。

請注意：

  • API Key 屬於敏感憑證，不要寫進公開倉庫
  • 不要把真實 Key 放入教程截圖
  • 建議按環境或用途分別建立和管理憑證
  • 懷疑洩露時，應及時輪換或撤銷

本文統一使用環境變數 ACEDATACLOUD_API_KEY，避免將明文憑證直接寫入 Codex 配置檔。

第二步：安裝 Codex CLI

使用 npm 全域安裝 Codex：

npm install -g @openai/codex

安裝後驗證：

codex --version

如果提示找不到命令，先確認 npm 全域可執行目錄已加入 PATH，再重新打開終端。

如果你主要使用 VS Code，也可以安裝 OpenAI 發布的 Codex 擴展：

code --install-extension openai.chatgpt

CLI 與 VS Code 擴展共享配置檔，因此建議先把 Provider 和環境變數配置好，再啟動編輯器驗證。

第三步：設定 API Key 環境變數

macOS / Linux：當前終端會話

export ACEDATACLOUD_API_KEY="你的 API Key"

此命令只對當前 Shell 及其子進程生效。關閉終端後變數會消失。

macOS / Linux：長期生效

如果使用 Zsh：

echo 'export ACEDATACLOUD_API_KEY="你的 API Key"' >> ~/.zshrc
source ~/.zshrc

如果使用 Bash：

echo 'export ACEDATACLOUD_API_KEY="你的 API Key"' >> ~/.bashrc
source ~/.bashrc

不要在共用電腦上盲目複製包含真實 Key 的 Shell 配置；團隊環境應結合憑證管理工具和最小權限策略。

Windows PowerShell

setx ACEDATACLOUD_API_KEY "你的 API Key"

執行後關閉並重新打開 PowerShell。setx 不會自動更新目前已開啟的進程，因此原有終端和 VS Code 可能仍讀不到新值。

如需只在當前 PowerShell 會話臨時設定：

$env:ACEDATACLOUD_API_KEY="你的 API Key"

第四步：建立或編輯 config.toml

Codex CLI、Desktop 和 VS Code 擴展共享以下配置檔：

  • macOS / Linux：~/.codex/config.toml
  • Windows：%USERPROFILE%\.codex\config.toml

如果目錄不存在，先建立。

macOS / Linux：

mkdir -p ~/.codex

然後寫入：

model_provider = "acedatacloud"

[model_providers.acedatacloud]
name = "acedatacloud"
base_url = "https://api.acedata.cloud/v1"

[model_providers.acedatacloud.auth]
command = "sh"
args = ["-c", "echo $ACEDATACLOUD_API_KEY"]

Windows 使用相同的 Provider 和 Base URL，但認證命令改為 PowerShell：

model_provider = "acedatacloud"

[model_providers.acedatacloud]
name = "acedatacloud"
base_url = "https://api.acedata.cloud/v1"

[model_providers.acedatacloud.auth]
command = "powershell"
args = ["-NoProfile", "-Command", "Write-Output $env:ACEDATACLOUD_API_KEY"]

配置中的三個名稱要嚴格保持一致：

  • model_provider = "acedatacloud"
  • [model_providers.acedatacloud]
  • [model_providers.acedatacloud.auth]

Base URL 也要完整包含 /v1。

第五步：啟動 Codex 並選擇模型

儲存配置後，重新打開終端並執行：

codex

進入 Codex 後執行：

/model

確認目前 Provider 為 acedatacloud，然後從可用列表選擇模型。

接入配置裡不必固定 model。把 Provider 與模型選擇分開，可以減少切換模型時反覆編輯 TOML 的成本。實際型號與可用範圍會更新，應以 /model 和平台即時目錄為準。

第六步：用最小請求驗證

不要一開始就要求 Codex 重構整個倉庫。先發送一個簡單、可快速判斷結果的請求，例如：

請概括目前專案的目錄結構，不要修改任何檔案。

隨後打開 Ace Data Cloud Usage History，確認請求已到達，並查看狀態與消耗。

如果最小請求成功，再逐步嘗試讀取檔案、生成修改方案、編輯程式碼和執行測試。

VS Code 配置要點

VS Code 擴展會讀取同一份 ~/.codex/config.toml，但它能否看到 API Key 取決於擴展運行進程的環境。

配置後請完全退出並重新打開 VS Code。macOS / Linux 上，如果從圖形界面啟動後仍讀不到變數，可以從已設定 Key 的終端運行：

code .

使用以下環境時，應在擴展實際運行的一側配置變數：

  • Remote SSH：遠端主機
  • WSL：WSL Linux 環境
  • Dev Container：容器環境
  • Codespaces 或類似遠端環境：對應遠端會話

只在本機 Shell 設定變數，不能保證遠端擴展自動獲得它。

Codex Desktop 配置要點

Desktop 與 CLI 共享配置檔，但圖形應用不一定繼承終端裡臨時執行的 export。

如果 Desktop 讀不到 Key：

  1. 將環境變數設定為長期或系統級
  2. 完全退出 Desktop
  3. 重新啟動應用
  4. 再檢查 Provider 和模型

常見錯誤排查

1. 401、Unauthorized 或 Incorrect API Key

檢查順序：

  1. API Key 是否複製完整
  2. 環境變數名是否為 ACEDATACLOUD_API_KEY
  3. 當前進程是否在設定變數之後啟動
  4. auth.command 是否符合當前作業系統
  5. 憑證是否仍有效 不要將完整的 Key 輸出到日誌或聊天中。可以用僅判斷“是否存在”的方式檢查變數。

macOS / Linux：

if [ -n "$ACEDATACLOUD_API_KEY" ]; then echo "Key is set"; else echo "Key is missing"; fi

PowerShell：

if ($env:ACEDATACLOUD_API_KEY) { "Key is set" } else { "Key is missing" }

2. Provider 沒有變成 acedatacloud

確認配置文件路徑和 TOML 層級。常見錯誤包括：

  • 檔案名寫成 config.toml.txt
  • 編輯了另一個使用者目錄
  • 表名拼寫不一致
  • 引號或陣列格式錯誤
  • 儲存後沒有重啟客戶端

3. Base URL 請求失敗

確認地址是：

https://api.acedata.cloud/v1

不要漏掉 https:// 或末尾 /v1，也不要誤用控制台頁面地址。

4. CLI 能用，VS Code 不能用

這通常不是 Provider 配置問題，而是 VS Code 進程沒有讀取到環境變數。從已設定變數的終端啟動 code .，或配置系統級變數後完全重啟 VS Code。

5. WSL、SSH 或容器裡讀不到 Key

環境變數需要設定在 Codex 或擴展真正運行的環境。Windows 主機上的 setx 不會自動寫入 WSL；本機變數也不會自動傳給遠端 SSH 主機或容器。

6. 找不到想用的模型

不要手動猜測舊模型 ID。運行 /model 查看即時可選項，並檢查應用權限、餘額和當前 Provider。

7. 請求到達但無法完成複雜任務

先縮小任務範圍：讓 Codex 只讀分析、列計畫，再逐步允許修改和測試。模型接入成功不代表所有倉庫任務都應一次完成；複雜變更仍需明確的驗收標準、測試和人工審查。

推薦的配置檢查清單

在提交第一個正式任務前，逐項確認：

  • 已從應用列表取得有效 API Key
  • Key 保存在 ACEDATACLOUD_API_KEY
  • 沒有將 Key 寫入 Git 倉庫
  • model_provider 為 acedatacloud
  • Base URL 為 https://api.acedata.cloud/v1
  • auth.command 與作業系統一致
  • 已完全重啟 Codex 或 VS Code
  • /model 能看到 Provider 和模型
  • 最小測試請求成功
  • Usage History 中能看到對應調用記錄

一個 Provider，減少重複配置

這套接入方式的重點並不是多寫一段 TOML，而是建立穩定邊界：

  • API Key 由環境變數管理
  • Provider 連接由 config.toml 管理
  • 模型在 Codex 內按任務選擇
  • 調用記錄和消耗在 Ace Data Cloud 控制台統一查看
  • CLI、Desktop 與 VS Code 共用一份配置

當認證、Provider 與模型選擇被拆分清楚，許多“Codex 為何又不能用”的問題就能快速定位，而不必反覆登入、重裝或複製多份配置。

打開 Codex 配置中心 查看不同客戶端的官方指南，或前往 應用列表 取得 API Key。

參考資料