Codex - Alibaba Cloud Model Studio

Codex 是 OpenAI 推出的終端 AI 編程助手。可通過 Token Plan 個人版、Token Plan 團隊版、Coding Plan 或隨用隨付接入阿里雲百鍊。

安裝 Codex

安裝或更新 Node.js（v18.0 或更高版本）。
在終端中執行以下命令安裝 Codex。

npm install -g @openai/codex

執行以下命令驗證安裝。

codex --version

配置接入憑證

接入需要編輯設定檔~/.codex/config.toml並配置環境變數OPENAI_API_KEY。請根據您的接入方式選擇對應配置。

配置模型中繼資料

使用自訂模型（如 qwen3.8-max）時，需要配置模型中繼資料檔案，使 Codex 正確識別模型的上下文視窗、推理深度等參數。

建立檔案 ~/.codex/model-catalog.local.json，寫入以下內容：

{
  "models": [
    {
      "slug": "qwen3.8-max",
      "display_name": "qwen3.8-max",
      "description": "DashScope model: qwen3.8-max",
      "default_reasoning_level": "xhigh",
      "supported_reasoning_levels": [
        {
          "effort": "low",
          "description": "Fast responses with lighter reasoning"
        },
        {
          "effort": "medium",
          "description": "Greater reasoning depth for complex problems"
        },
        {
          "effort": "xhigh",
          "description": "Extra high reasoning depth for complex problems"
        }
      ],
      "context_window": 983616,
      "effective_context_window_percent": 95,
      "supports_parallel_tool_calls": false,
      "supports_image_detail_original": true,
      "input_modalities": ["text", "image"],
      "shell_type": "default",
      "visibility": "list",
      "supported_in_api": true,
      "priority": 1,
      "base_instructions": "",
      "support_verbosity": false,
      "supports_reasoning_summaries": false,
      "experimental_supported_tools": [],
      "truncation_policy": {
        "mode": "bytes",
        "limit": 10000
      }
    }
  ]
}

在 ~/.codex/config.toml 中添加以下配置，指向中繼資料檔案：

model_catalog_json = "~/.codex/model-catalog.local.json"

Token Plan 個人版

model請選擇支援的模型。將OPENAI_API_KEY環境變數設定為 Token Plan 個人版專屬 API Key。

Responses API

若所選模型支援 OpenAI Responses API，可使用最新版 Codex。

model_provider = "Model_Studio_Token_Plan_Personal"
model = "qwen3.8-max"
[model_providers.Model_Studio_Token_Plan_Personal]
name = "Model_Studio_Token_Plan_Personal"
base_url = "https://token-plan.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1"
env_key = "OPENAI_API_KEY"
wire_api = "responses"

Chat/Completions API（其他模型）

其他模型需通過 Chat/Completions API 接入，需安裝舊版本 Codex，如 0.80.0（新版本 Codex 已不再支援 wire_api = "chat" 配置，升級後如遇報錯請參見下文 FAQ）：

npm install -g @openai/codex@0.80.0

model_provider = "Model_Studio_Token_Plan_Personal"
model = "glm-5"
[model_providers.Model_Studio_Token_Plan_Personal]
name = "Model_Studio_Token_Plan_Personal"
base_url = "https://token-plan.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1"
env_key = "OPENAI_API_KEY"
wire_api = "chat"

配置環境變數

將OPENAI_API_KEY環境變數設定為 Token Plan 個人版專屬 API Key。

macOS

在終端中執行以下命令，查看預設 Shell 類型。

echo $SHELL

根據 Shell 類型設定環境變數：

Zsh

# 將 YOUR_API_KEY 替換為 Token Plan 個人版 API Key
echo 'export OPENAI_API_KEY="YOUR_API_KEY"' >> ~/.zshrc

Bash

# 將 YOUR_API_KEY 替換為 Token Plan 個人版 API Key
echo 'export OPENAI_API_KEY="YOUR_API_KEY"' >> ~/.bash_profile

執行以下命令使環境變數生效。
Zsh
```
source ~/.zshrc
```
Bash
```
source ~/.bash_profile
```

Windows

CMD

在 CMD 中運行以下命令，設定環境變數。

REM 將 YOUR_API_KEY 替換為 Token Plan 個人版 API Key
setx OPENAI_API_KEY "YOUR_API_KEY"

開啟一個新的 CMD 視窗，運行以下命令檢查環境變數是否生效。

echo %OPENAI_API_KEY%

PowerShell

在 PowerShell 中運行以下命令，設定環境變數。

# 將 YOUR_API_KEY 替換為 Token Plan 個人版 API Key
[Environment]::SetEnvironmentVariable("OPENAI_API_KEY", "YOUR_API_KEY", [EnvironmentVariableTarget]::User)

開啟一個新的 PowerShell 視窗，運行以下命令檢查環境變數是否生效。

echo $env:OPENAI_API_KEY

Token Plan 團隊版

model請選擇支援的模型。將OPENAI_API_KEY環境變數設定為 Token Plan 團隊版專屬 API Key。

Responses API

若所選模型支援 OpenAI Responses API，可使用最新版 Codex。

model_provider = "Model_Studio_Token_Plan"
model = "qwen3.8-max"
[model_providers.Model_Studio_Token_Plan]
name = "Model_Studio_Token_Plan"
base_url = "https://token-plan.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1"
env_key = "OPENAI_API_KEY"
wire_api = "responses"

Chat/Completions API（其他模型）

其他模型需通過 Chat/Completions API 接入，需安裝舊版本 Codex，如 0.80.0（新版本 Codex 已不再支援 wire_api = "chat" 配置，升級後如遇報錯請參見下文 FAQ）：

npm install -g @openai/codex@0.80.0

model_provider = "Model_Studio_Token_Plan"
model = "glm-5"
[model_providers.Model_Studio_Token_Plan]
name = "Model_Studio_Token_Plan"
base_url = "https://token-plan.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1"
env_key = "OPENAI_API_KEY"
wire_api = "chat"

配置環境變數

將OPENAI_API_KEY環境變數設定為 Token Plan 團隊版專屬 API Key。

macOS

在終端中執行以下命令，查看預設 Shell 類型。

echo $SHELL

根據 Shell 類型設定環境變數：

Zsh

# 將 YOUR_API_KEY 替換為 Token Plan 團隊版 API Key
echo 'export OPENAI_API_KEY="YOUR_API_KEY"' >> ~/.zshrc

Bash

# 將 YOUR_API_KEY 替換為 Token Plan 團隊版 API Key
echo 'export OPENAI_API_KEY="YOUR_API_KEY"' >> ~/.bash_profile

執行以下命令使環境變數生效。
Zsh
```
source ~/.zshrc
```
Bash
```
source ~/.bash_profile
```

Windows

CMD

在 CMD 中運行以下命令，設定環境變數。

REM 將 YOUR_API_KEY 替換為 Token Plan 團隊版 API Key
setx OPENAI_API_KEY "YOUR_API_KEY"

開啟一個新的 CMD 視窗，運行以下命令檢查環境變數是否生效。

echo %OPENAI_API_KEY%

PowerShell

在 PowerShell 中運行以下命令，設定環境變數。

# 將 YOUR_API_KEY 替換為 Token Plan 團隊版 API Key
[Environment]::SetEnvironmentVariable("OPENAI_API_KEY", "YOUR_API_KEY", [EnvironmentVariableTarget]::User)

開啟一個新的 PowerShell 視窗，運行以下命令檢查環境變數是否生效。

echo $env:OPENAI_API_KEY

Coding Plan

model請選擇支援的模型。將OPENAI_API_KEY環境變數設定為 Coding Plan 專屬 API Key。

Chat/Completions API

Coding Plan 僅支援 Chat/Completions API，需安裝舊版本 Codex，如 0.80.0（新版本 Codex 已不再支援 wire_api = "chat" 配置，升級後如遇報錯請參見下文 FAQ）：

npm install -g @openai/codex@0.80.0

model_provider = "Model_Studio_Coding_Plan"
model = "qwen3.7-plus"
[model_providers.Model_Studio_Coding_Plan]
name = "Model_Studio_Coding_Plan"
base_url = "https://coding-intl.dashscope.aliyuncs.com/v1"
env_key = "OPENAI_API_KEY"
wire_api = "chat"

配置環境變數

將OPENAI_API_KEY環境變數設定為 Coding Plan 專屬 API Key。

macOS

在終端中執行以下命令，查看預設 Shell 類型。

echo $SHELL

根據 Shell 類型設定環境變數：

Zsh

# 將 YOUR_API_KEY 替換為 Coding Plan API Key
echo 'export OPENAI_API_KEY="YOUR_API_KEY"' >> ~/.zshrc

Bash

# 將 YOUR_API_KEY 替換為 Coding Plan API Key
echo 'export OPENAI_API_KEY="YOUR_API_KEY"' >> ~/.bash_profile

執行以下命令使環境變數生效。
Zsh
```
source ~/.zshrc
```
Bash
```
source ~/.bash_profile
```

Windows

CMD

在 CMD 中運行以下命令，設定環境變數。

REM 將 YOUR_API_KEY 替換為 Coding Plan API Key
setx OPENAI_API_KEY "YOUR_API_KEY"

開啟一個新的 CMD 視窗，運行以下命令檢查環境變數是否生效。

echo %OPENAI_API_KEY%

PowerShell

在 PowerShell 中運行以下命令，設定環境變數。

# 將 YOUR_API_KEY 替換為 Coding Plan API Key
[Environment]::SetEnvironmentVariable("OPENAI_API_KEY", "YOUR_API_KEY", [EnvironmentVariableTarget]::User)

開啟一個新的 PowerShell 視窗，運行以下命令檢查環境變數是否生效。

echo $env:OPENAI_API_KEY

隨用隨付

將OPENAI_API_KEY環境變數設定為百鍊 API Key。可用模型參見支援的模型。

根據地區設定base_url，API Key 須與所選地區對應，請將 URL 中的 {WorkspaceId} 替換為真實的擷取Workspace ID：

華北2（北京）：https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/compatible-mode/v1
新加坡：https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1

隨用隨付支援 Responses API 和 Chat/Completions API 兩種接入方式，請根據使用的模型選擇：

Responses API

適用於支援 OpenAI Responses API 的模型（如 qwen3.7-max），可使用最新版 Codex。

model_provider = "Model_Studio"
model = "qwen3.7-max"
[model_providers.Model_Studio]
name = "Model_Studio"
base_url = "https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1"
env_key = "OPENAI_API_KEY"
wire_api = "responses"

Chat/Completions API

適用於僅支援 Chat/Completions API 的模型，需安裝 Codex 0.80.0（新版本 Codex 已不再支援 wire_api = "chat" 配置，升級後如遇報錯請參見下文 FAQ）：

npm install -g @openai/codex@0.80.0

model_provider = "Model_Studio"
model = "qwen3.6-plus"
[model_providers.Model_Studio]
name = "Model_Studio"
base_url = "https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1"
env_key = "OPENAI_API_KEY"
wire_api = "chat"

配置環境變數

將OPENAI_API_KEY環境變數設定為百鍊 API Key。

macOS

在終端中執行以下命令，查看預設 Shell 類型。

echo $SHELL

根據 Shell 類型設定環境變數：

Zsh

# 將 YOUR_API_KEY 替換為百鍊 API Key
echo 'export OPENAI_API_KEY="YOUR_API_KEY"' >> ~/.zshrc

Bash

# 將 YOUR_API_KEY 替換為百鍊 API Key
echo 'export OPENAI_API_KEY="YOUR_API_KEY"' >> ~/.bash_profile

執行以下命令使環境變數生效。
Zsh
```
source ~/.zshrc
```
Bash
```
source ~/.bash_profile
```

Windows

CMD

在 CMD 中運行以下命令，設定環境變數。

REM 將 YOUR_API_KEY 替換為百鍊 API Key
setx OPENAI_API_KEY "YOUR_API_KEY"

開啟一個新的 CMD 視窗，運行以下命令檢查環境變數是否生效。

echo %OPENAI_API_KEY%

PowerShell

在 PowerShell 中運行以下命令，設定環境變數。

# 將 YOUR_API_KEY 替換為百鍊 API Key
[Environment]::SetEnvironmentVariable("OPENAI_API_KEY", "YOUR_API_KEY", [EnvironmentVariableTarget]::User)

開啟一個新的 PowerShell 視窗，運行以下命令檢查環境變數是否生效。

echo $env:OPENAI_API_KEY

驗證配置

配置完成後，建立終端視窗，執行以下命令啟動 Codex：

codex

如果正常進入對話介面，說明配置成功。

使用 CC Switch

CC Switch 是社區開源的案頭 GUI，支援在多個 API Key 或計費套餐之間一鍵切換，無需手動修改 ~/.codex/config.toml。

安裝

macOS：執行 brew tap farion1231/ccswitch && brew install --cask cc-switch，或從 Releases 下載 .dmg。
Windows：從 Releases 下載 .msi 安裝包或便攜版 .zip。
Linux：Arch 發行版執行 paru -S cc-switch-bin；其他發行版從 Releases 下載 .deb / .rpm / .AppImage。

添加供應商

在 CC Switch 主介面頂部表徵圖欄選中 Codex 表徵圖，點擊右上方 + 進入添加新供應商，按下表填入配置後點擊添加。

計費方案	配置資訊
Token Plan 個人版	供應商名稱：百鍊-Token Plan 個人版 API Key：控制台擷取請求地址：`https://token-plan.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1`
Token Plan 團隊版	供應商名稱：百鍊-Token Plan 團隊版 API Key：控制台擷取請求地址：`https://token-plan.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1`
Coding Plan	供應商名稱：百鍊-Coding Plan API Key：控制台擷取請求地址：`https://coding-intl.dashscope.aliyuncs.com/v1`
隨用隨付	供應商名稱：百鍊-隨用隨付 API Key：百鍊 API Key 請求地址：`https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1`

展開進階選項填寫模型名稱，從對應套餐支援的模型中選擇，例如 qwen3.7-max（Coding Plan 不支援）。
回到主介面，點擊該供應商右側啟用按鈕，然後重新開啟終端視窗執行 codex 使配置生效。

常見問題

第三方工具提示“不支援國內模型”或“檢查被拒 / Bad request (400)”怎麼辦？

原因：部分第三方管理工具（如 CC-Switch）在切換供應商時會發起“健全狀態檢查/串連測試”探測請求，該探測請求的格式與 Codex 實際調用的請求格式不同，百鍊網關可能因此返回 400 Bad request 並提示“檢查被拒”，工具據此顯示“不支援國內模型”。此提示僅代表健全狀態檢查探測未通過，並不代表百鍊不支援中國內地模型，也不影響 Codex 的實際使用。

說明：百鍊支援通過 Codex 使用中國內地模型，配置方式詳見上文配置接入憑證。

解決方案：建議參照上文配置接入憑證，直接在~/.codex/config.toml中完成配置，無需依賴第三方工具的健全狀態檢查結果；配置完成後參照驗證配置啟動 Codex，若能正常進入對話介面即表示可正常使用中國內地模型。

報錯 wire_api 配置問題怎麼辦？

原因：Codex 新版本不再支援 wire_api = "chat" 配置。根據版本不同，可能出現以下報錯：

wire_api = "chat" is no longer supported
unknown configuration field wire_api

解決方案：

報錯 wire_api = "chat" is no longer supported：將設定檔中的 wire_api 改為 responses，並確認 base_url 配置正確。詳見上文配置接入憑證中對應方案的配置樣本。
報錯 unknown configuration field wire_api：從設定檔 ~/.codex/config.toml 的對應 provider 節中刪除 wire_api 欄位。

報錯 unexpected status 401 Unauthorized 怎麼辦？

原因：

誤用了其他方案的 API Key（Token Plan 個人版、Token Plan 團隊版、Coding Plan 和隨用隨付的 API Key 互不相通）
訂閱到期
API Key 複製不完整、有空格或拼字錯誤

解決方案：

確認使用的是所選方案對應的專屬 API Key。
前往對應方案的管理頁面確認訂閱是否到期。
重新複製 API Key，確保完整且無空格。
如以上均正常仍報錯，可在對應管理頁面重設 API Key，重設後請使用新 API Key 進行配置。

報錯 unexpected status 404 Not Found 怎麼辦？

原因：設定檔中的base_url或wire_api填寫錯誤。

解決方案：確認base_url和wire_api與所選方案的配置一致。參見上文配置接入憑證中對應方案的配置樣本。

報錯 stream disconnected before completion: stream closed before response.completed 怎麼辦？

原因：Codex 與服務端的流式串連在響應完成前斷開。常見於以下情境：

對話線程過長，Codex 觸發上下文壓縮時請求失敗
網路不穩定，SSE 或 WebSocket 串連中途斷開
服務端過載或觸發限流，提前終止串連

解決方案：

開啟新的對話線程，避免單個線程積累過多上下文。
檢查網路連接是否穩定，關閉 VPN 或代理後重試。
等待一段時間後重試，Codex 內建了自動重試機制，多數情況下重試可恢複。

報錯 429 請求超頻或額度用盡怎麼辦？

原因：429 錯誤有以下兩種情形：

請求超頻（429 Requests rate limit exceeded）：短時間內請求過於密集。
限額用盡（429 Allocated quota exceeded 或 Your token-plan quota has been exhausted）：Token Plan 個人版的套餐月額度用盡。

解決方案：

請求超頻：等待一分鐘後重試，降低請求頻率。
限額用盡：等待下一個訂閱月額度自動重設；或購買用量包（套餐月額度用盡後自動抵扣用量包額度）；或升級套餐。注意：報錯資訊中的重設時間（如 The quota will reset at HH:MM:SS UTC）以國際標準時間（UTC）為準，換算為北京時間（CST）需加 8 小時。