繁體中文

外部模型接入 Codex

Codex 本機客戶端不只能夠使用 OpenAI 官方模型。通過 CC Switch 或 Codex 的自定義 model provider,你可以把 Codex 接入第三方模型廠商、API 聚合平台或企業內部模型閘道器。

本文只介紹第三方線上模型,提供兩種接入路線:

接入方式 適合場景 / 是否需要協議轉換
CC Switch 第三方介面只支援 Chat Completions、Anthropic Messages,或者你希望通過圖形介面快速切換多個 provider

是否需要協議轉換: 由 CC Switch 根據上游協議自動處理
自定義 model provider 第三方服務原生、完整地相容 OpenAI Responses API

是否需要協議轉換: 不需要

開始前必須理解一個關鍵限制:

本文適用於執行在本機的 Codex CLI、Codex IDE 擴充套件以及讀取同一套 config.toml 的桌面客戶端。Codex 雲端會話目前不能通過本文方式切換為自定義模型。

開始之前

安裝或更新 Codex CLI

npm install -g @openai/codex@latest
codex --version

首次安裝後,至少執行一次:

codex

這樣可以初始化 Codex 的使用者設定目錄。

Codex 設定檔位置

macOS 和 Linux:

~/.codex/config.toml

Windows:

%USERPROFILE%\.codex\config.toml

修改設定前建議備份。

macOS / Linux:

mkdir -p ~/.codex/backup
cp ~/.codex/config.toml \
  ~/.codex/backup/config.toml.$(date +%Y%m%d-%H%M%S) \
  2>/dev/null || true

PowerShell:

$codexDir = Join-Path $HOME ".codex"
$backupDir = Join-Path $codexDir "backup"
New-Item -ItemType Directory -Force -Path $backupDir | Out-Null

$configFile = Join-Path $codexDir "config.toml"
if (Test-Path $configFile) {
  $timestamp = Get-Date -Format "yyyyMMdd-HHmmss"
  Copy-Item $configFile (Join-Path $backupDir "config.toml.$timestamp")
}

區分 provider、MCP 和模型閘道器

這三個概念解決的問題不同:

  • model_provider:決定 Codex 把模型請求傳送到哪裡;
  • MCP:給 Codex 增加瀏覽器、GitHub、資料庫等工具與上下文;
  • 模型閘道器:在 Codex 和模型服務之間完成協議轉換、鑑權、路由、日誌或限流。

因此,更換 Codex 的底層模型需要設定 provider,不是設定 MCP。

API Key 安全

不要把真實 API Key 提交到 Git 儲存庫,也不要把完整金鑰放進公開截圖、日誌或工單。

手動設定 provider 時,優先使用環境變數:

[model_providers.example]
env_key = "EXAMPLE_API_KEY"

CC Switch 會在本機儲存 provider 設定,並在切換時修改 Codex 的本機設定。它是第三方開源工具,不是 OpenAI 官方產品。應只從 CC Switch 官方網站或官方 GitHub 儲存庫安裝,並保護好本機設定、資料庫和備份檔案。


1. 使用 CC Switch 接入第三方模型

對於大多數第三方模型,CC Switch 是更容易使用的接入方式。它可以管理 provider、API Key、模型列表和本機路由,並在上游協議不相容時完成轉換。

1.1 CC Switch 解決了什麼問題

新版 Codex 按 Responses API 傳送請求,但不少第三方服務提供的是:

  • OpenAI Chat Completions;
  • Anthropic Messages;
  • 非 Codex 預設識別的模型 ID;
  • 廠商自定義的推理參數和流式事件格式。

CC Switch 的本機路由可以把呼叫鏈轉換為:

Codex
  │  Responses API

CC Switch 本地路由
  │  根据 provider 配置转换协议和模型名称

第三方模型 API


CC Switch 将响应、SSE、推理内容和工具调用转换回 Responses 格式


Codex

對於原生支援 Responses API 的 provider,CC Switch 可以不做 Chat 協議轉換;對於 Chat Completions 或 Anthropic Messages provider,則必須啟用本機路由。

1.2 安裝 CC Switch

只從以下官方來源獲取安裝包:

macOS 推薦使用 Homebrew:

brew install --cask cc-switch

更新:

brew upgrade --cask cc-switch

Windows 可以從 Releases 下載 .msi 安裝包或便攜版壓縮包。

Linux 可以從 Releases 下載 .deb.rpm 或 AppImage。不同版本的介面文字可能略有變化,建議始終使用最新穩定版本,並以應用內實際選項為準。

1.3 準備工作

接入前準備以下內容:

  1. 已安裝並執行過一次 Codex;
  2. 已安裝並能夠正常啟動 CC Switch;
  3. 已獲得目標模型服務的 API Key;
  4. 已從供應商文件確認 Base URL、模型 ID 和上游 API 協議;
  5. 如果需要保留 Codex 官方賬號能力,先完成一次官方登入。

檢查 Codex 登入狀態:

codex login status

需要登入時可以執行:

codex login

也可以使用裝置碼登入:

codex login --device-auth

1.4 可選:切換第三方 provider 時保留官方登入

這一項主要適用於同時使用 Codex 桌面功能、官方外掛或遠端控制能力的使用者。只使用 CLI 且不依賴官方登入能力時,可以跳過。

推薦順序:

  1. 在 CC Switch 的 Codex 頁面切換到 OpenAI Official
  2. 啟動 Codex,並完成官方賬號登入;
  3. 在 CC Switch 開啟 Settings → General → Codex App Enhancements
  4. 開啟 Keep official login when switching third-party providers
  5. 再新增或切換第三方 provider。

開啟後,CC Switch 會盡量保持:

  • ~/.codex/auth.json:繼續儲存官方登入狀態;
  • ~/.codex/config.toml:儲存當前第三方 provider、模型、地址和認證設定。

auth.json 中包含敏感登入資訊,不要複製給他人,也不要提交到版本控制系統。

1.5 新增第三方 provider

開啟 CC Switch,切換到頂部的 Codex 頁面,然後點選右上角的新增按鈕。

優先使用預設

如果應用內已經有對應 provider 預設,優先選擇預設,只填寫 API Key 和必要參數。預設通常會自動設定:

  • Base URL;
  • 預設模型;
  • 上游協議;
  • 是否需要本機路由;
  • 模型對映;
  • 部分推理參數。

CC Switch 的預設列表會隨著版本更新。文件中不應長期固定某個廠商的模型 ID,應以應用內列表和供應商官方文件為準。

使用自定義 provider

預設中沒有目標服務時,選擇自定義設定,並填寫:

欄位 說明
Provider Name 自定義名稱,僅用於識別
API Key 第三方服務的金鑰
Base URL 供應商公佈的 API 根地址
Model ID 上游真實模型 ID,必須完全一致
Upstream Format 上游實際使用的協議
Model Mapping Codex 中顯示和呼叫的模型列表

最關鍵的是正確選擇 Upstream Format

上游格式 何時使用 是否需要本機路由
Responses (native) 上游原生實現 Responses API 通常不需要協議轉換
Chat Completions (routing required) 上游提供 /chat/completions 需要
Anthropic Messages (routing required) 上游使用 Anthropic Messages 協議 需要

不要因為供應商宣傳“相容 OpenAI API”就預設選擇 Responses。很多所謂 OpenAI 相容介面只相容 Chat Completions。

1.6 正確填寫 Base URL

預設情況下,CC Switch 會在 Base URL 後拼接對應的 API 路徑。因此,通常只填寫供應商文件給出的 API 根地址,不要自行重複新增 /chat/completions/responses

例如,供應商要求:

POST https://api.example.com/v1/chat/completions

通常填寫:

https://api.example.com

或者按照預設要求填寫:

https://api.example.com/v1

具體是否包含 /v1,取決於 CC Switch 預設和供應商文件。儲存前應使用 CC Switch 的連線檢測或請求日誌確認最終請求地址。

只有當供應商要求非標準完整路徑時,才使用 CC Switch 的 Full URL Mode,並填寫完整 endpoint。

1.7 設定 Needs Local Routing 和模型對映

當 provider 使用 Chat Completions、Anthropic Messages,或者模型名稱不是 Codex 預設模型時,應啟用 Needs Local Routing

選擇 Chat 類型預設時,CC Switch 通常會自動開啟該選項;自定義 provider 需要自行確認。

啟用後會出現模型對映設定。常見欄位包括:

欄位 說明
Model ID 第三方 API 接收的真實模型名稱
Display Name Codex /model 選單中顯示的名稱
Context Window 可選,模型真實上下文視窗

注意:

  • Model ID 必須與供應商文件完全一致;
  • 不要憑感覺填寫上下文視窗;
  • 模型列表變化後需要重啟 Codex;
  • CC Switch 會根據對映生成 Codex 使用的模型目錄;
  • 如果中轉平台修改了模型名稱或域名,自動推理能力識別可能不準確,應在進階設定中檢查。

1.8 開啟本機路由並接管 Codex

在 CC Switch 中開啟:

Settings → Routing → Local Routing

完成以下操作:

  1. 開啟本機路由總開關;
  2. Routing Enabled 中開啟 Codex
  3. 確認目標 provider 的 Needs Local Routing 狀態正確;
  4. 使用期間保持 CC Switch 正在執行。

本機路由預設地址通常是:

http://127.0.0.1:15721

接管生效後,Codex 的即時設定會指向 CC Switch 本機路由。CC Switch 再根據當前選中的 provider,把請求轉發到真正的第三方 API。

如果上游是 Chat Completions,實際過程通常類似:

Codex POST /responses
  → CC Switch 转换为 POST /chat/completions
  → 第三方模型返回 JSON 或 SSE
  → CC Switch 转换回 Responses JSON 或 SSE
  → Codex 继续执行工具调用

1.9 切換 provider 並重啟 Codex

返回 CC Switch 的 Codex provider 列表,選中剛剛設定的 provider,然後點選啟用。

切換後建議完全退出並重新啟動 Codex,原因包括:

  • Codex 在啟動時讀取 config.toml
  • /model 選單通常在啟動時載入模型目錄;
  • IDE 擴充套件或桌面客戶端可能快取舊 provider;
  • 已存在的會話可能仍儲存舊模型資訊。

CLI 使用者可以重新執行:

codex

1.10 驗證是否接入成功

進入 Codex 後執行:

/status

檢查當前模型、provider、權限和上下文資訊。

檢視模型列表:

/model

檢查設定層級:

/debug-config

同時檢查:

  • CC Switch 當前選中的 Codex provider;
  • CC Switch 本機路由日誌或統計;
  • 第三方平台的請求記錄和餘額變化;
  • ~/.codex/config.toml 是否暫時指向本機路由。

不要只傳送“你好”來驗證。至少完成一次智能體能力測試:

  1. 讓 Codex 列出當前專案檔案;
  2. 讓 Codex 讀取一個檔案並總結內容;
  3. 讓 Codex 修改一個小檔案;
  4. 讓 Codex 執行測試;
  5. 故意保留一個簡單錯誤,觀察它能否根據測試結果繼續修復。

只有文本對話成功,不代表工具呼叫和多輪智能體工作流程已經相容。

1.11 切回 OpenAI 官方 provider

在 CC Switch 中選擇 OpenAI Official,然後重啟 Codex。

檢查登入狀態:

codex login status

如果官方登入狀態異常,重新執行:

codex login

如果你需要同時保留官方登入和第三方模型請求,檢查 Keep official login when switching third-party providers 是否仍然開啟。

1.12 CC Switch 的限制與注意事項

CC Switch 簡化了設定,但仍有以下限制:

  • 使用 Chat 或 Messages 協議時,CC Switch 必須持續執行;
  • 協議轉換不能保證還原所有供應商特有能力;
  • 某些模型雖然能聊天,但工具呼叫質量不足;
  • Web Search、圖片輸入、WebSocket、響應儲存等高階功能可能不相容;
  • 供應商的限流、計費和資料保留政策仍然生效;
  • 中轉平台可能再次修改請求或響應;
  • CC Switch、Codex 或供應商升級後,舊設定可能需要重新驗證。

CC Switch 更適合本機桌面開發。伺服器、CI 或無圖形介面的長期自動化任務,優先使用原生 Responses API 或自建協議閘道器。


2. 手動接入第三方線上模型 API

只有當第三方服務原生支援 Codex 所需的 Responses API 時,才建議直接設定自定義 provider。

如果供應商只提供 /chat/completions 或 Anthropic Messages,請使用第一部分的 CC Switch 流程,不要嘗試設定 wire_api = "chat"

2.1 介面需要滿足的條件

一個可以直接接入 Codex 的 provider,至少應支援:

  • POST /responses
  • Responses JSON 結構;
  • Responses SSE 流式事件;
  • function/tool calling;
  • JSON Schema 工具參數;
  • 工具結果回傳後的繼續推理;
  • 多輪請求或 previous_response_id 等連續對話機制;
  • 足夠的上下文視窗和穩定的長請求處理;
  • 清晰的認證、限流和錯誤響應。

僅支援普通文本生成並不足以穩定執行 Codex 智能體。

2.2 通用設定

編輯使用者級設定:

~/.codex/config.toml

新增:

model_provider = "third_party"
model = "provider-model-id"

# 仅在模型明确支持时设置。
model_reasoning_effort = "high"

# 可选:没有官方模型目录时,填写供应商公布的真实值。
# model_context_window = 131072

[model_providers.third_party]
name = "My Responses-compatible Provider"
base_url = "https://provider.example.com/v1"
env_key = "THIRD_PARTY_API_KEY"
wire_api = "responses"
request_max_retries = 4
stream_max_retries = 5
stream_idle_timeout_ms = 300000

不要使用以下保留 provider ID:

openai
ollama
lmstudio

可以使用 third_partycompany_gateway 或其他自定義 ID。

2.3 設定欄位說明

欄位 作用
model_provider 選擇 [model_providers.<id>] 中定義的 provider
model 第三方服務接收的真實模型 ID
name 顯示名稱
base_url 第三方 Responses API 根地址
env_key 儲存 API Key 的環境變數名稱
wire_api 當前只能使用 responses,省略時預設也是 responses
request_max_retries 普通 HTTP 請求失敗後的重試次數
stream_max_retries 流式連線中斷後的重試次數
stream_idle_timeout_ms SSE 多久沒有事件後判定為空閒超時
model_context_window 可選,模型的真實上下文視窗
model_reasoning_effort 可選,模型支援的推理強度

base_url 是否包含 /v1 必須以供應商文件為準。Codex 會在它後面存取 Responses 路徑,常見最終地址是:

https://provider.example.com/v1/responses

2.4 設定 API Key

bash / zsh 當前會話:

export THIRD_PARTY_API_KEY="你的 API Key"

fish:

set -gx THIRD_PARTY_API_KEY "你的 API Key"

PowerShell 當前會話:

$env:THIRD_PARTY_API_KEY = "你的 API Key"

PowerShell 持久儲存到當前使用者:

[Environment]::SetEnvironmentVariable(
  "THIRD_PARTY_API_KEY",
  "你的 API Key",
  [EnvironmentVariableTarget]::User
)

持久設定後,需要重新啟動終端、IDE 或桌面客戶端。

2.5 先測試 Responses endpoint

在啟動 Codex 前,先直接測試第三方介面:

export PROVIDER_BASE_URL="https://provider.example.com/v1"

curl "$PROVIDER_BASE_URL/responses" \
  -H "Authorization: Bearer $THIRD_PARTY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "provider-model-id",
    "input": "Reply with exactly: PROVIDER_OK",
    "stream": false
  }'

至少檢查:

  • endpoint 不是 404;
  • 返回的是 Responses 風格結構,不是隻有 choices 的 Chat Completions 結構;
  • 模型 ID 正確;
  • 認證方式正確;
  • 錯誤響應包含可排查的資訊。

隨後還應單獨測試:

  • stream: true
  • 工具呼叫;
  • 工具結果回傳;
  • 多輪呼叫;
  • 長上下文;
  • 併發和限流。

2.6 驗證 Codex 設定

嚴格模式啟動:

codex --strict-config

--strict-config 會把不認識的設定項當作錯誤,適合發現舊教學中的廢棄欄位。

進入 Codex 後執行:

/status

需要檢查設定來源時執行:

/debug-config

臨時覆蓋 provider 和模型,不修改預設設定:

codex \
  -c 'model_provider="third_party"' \
  -m 'provider-model-id'

2.7 模型目錄與 Unknown model

Codex 的模型目錄可以描述:

  • 上下文視窗;
  • 支援的推理等級;
  • 輸入模態;
  • 工具呼叫能力;
  • 截斷策略;
  • 客戶端最低版本。

如果供應商提供 Codex 可用的模型目錄檔案,儲存到本機後設定:

model_catalog_json = "~/.codex/provider-models.json"

如果沒有模型目錄,可以在確認真實值後設置:

model_context_window = 131072

不要複製另一模型的後設資料來消除警告。錯誤的上下文視窗或工具能力宣告,可能導致提前截斷、超出限額或工具呼叫異常。

2.8 完整相容性檢查

正式使用前,建議逐項驗證:

  • /responses 非流式文本;
  • Responses SSE 流式輸出;
  • 單個工具呼叫;
  • 多個並行或連續工具呼叫;
  • JSON Schema 參數;
  • 工具結果回傳;
  • 長上下文與自動壓縮;
  • reasoning 參數;
  • 圖片或其他輸入模態;
  • 速率限制和重試;
  • 代理是否緩衝 SSE;
  • 供應商是否修改或丟棄工具欄位;
  • 資料保留、日誌和隱私政策。

2.9 provider 設定應放在哪裡

model_providermodel_providers 和 provider 認證設定應放在使用者級檔案:

~/.codex/config.toml

不要把它們放進專案儲存庫的:

<project>/.codex/config.toml

Codex 會忽略專案級設定中可能重定向模型請求或認證資訊的相關欄位。這可以防止克隆不可信儲存庫後,請求被專案設定悄悄轉發到其他伺服器。


3. 使用設定檔管理多個第三方 provider

如果使用 CC Switch,通常直接在圖形介面切換 provider 即可,不必再設定 Codex 設定檔(Profile)。

設定檔更適合手動設定多個原生 Responses provider 的使用者。可以把 provider 定義放在基礎設定中,再用獨立設定檔檔案選擇模型。

基礎設定 ~/.codex/config.toml

[model_providers.provider_a]
name = "Provider A"
base_url = "https://api.provider-a.example/v1"
env_key = "PROVIDER_A_API_KEY"
wire_api = "responses"

[model_providers.provider_b]
name = "Provider B"
base_url = "https://api.provider-b.example/v1"
env_key = "PROVIDER_B_API_KEY"
wire_api = "responses"

建立:

~/.codex/fast.config.toml

內容:

model_provider = "provider_a"
model = "provider-a-fast-model"
model_reasoning_effort = "medium"

再建立:

~/.codex/quality.config.toml

內容:

model_provider = "provider_b"
model = "provider-b-quality-model"
model_reasoning_effort = "high"

啟動時選擇:

codex --profile fast
codex --profile quality

非互動模式:

codex exec --profile quality "Review the current changes"

設定檔檔案位於:

$CODEX_HOME/<profile-name>.config.toml

預設 CODEX_HOME~/.codex

較新的 Codex 版本使用獨立設定檔檔案,不再讀取舊式的 [profiles.<name>] 表。如果從舊設定遷移,應把每個設定檔拆分為單獨的 <name>.config.toml


4. 特殊認證 Header 與高階認證

4.1 標準 Bearer Token

大多數第三方服務可以直接使用:

[model_providers.third_party]
env_key = "THIRD_PARTY_API_KEY"

Codex 會從環境變數讀取金鑰,並使用 provider 要求的 Bearer 認證。

4.2 自定義 API Key Header

某些平台要求:

x-api-key: <key>

可以使用 env_http_headers

model_provider = "custom_header_provider"
model = "provider-model-id"

[model_providers.custom_header_provider]
name = "Custom Header Provider"
base_url = "https://provider.example.com/v1"
wire_api = "responses"
env_http_headers = { "x-api-key" = "VENDOR_API_KEY" }

右側的 VENDOR_API_KEY 是環境變數名稱,不是真實金鑰。

export VENDOR_API_KEY="你的 API Key"

4.3 固定 Header 和查詢參數

新增不敏感的固定 Header:

http_headers = { "X-Client-Name" = "codex", "X-Environment" = "development" }

新增查詢參數:

query_params = { "api-version" = "2026-08-01" }

不要把真實金鑰直接寫進 http_headers

4.4 命令式動態認證

企業環境中可能需要從系統金鑰鏈、雲憑證工具或內部命令獲取短期 Token:

[model_providers.corporate]
name = "Corporate Gateway"
base_url = "https://gateway.example.com/v1"
wire_api = "responses"

[model_providers.corporate.auth]
command = "/usr/local/bin/fetch-codex-token"
args = ["--audience", "codex"]
timeout_ms = 5000
refresh_interval_ms = 300000

認證命令必須把 Token 輸出到標準輸出,並且不要輸出額外日誌。

以下認證方式不要混用:

  • [model_providers.<id>.auth]
  • env_key
  • experimental_bearer_token
  • requires_openai_auth

4.5 通過代理繼續使用 OpenAI 認證

只有當代理後面仍然存取 OpenAI 模型,並且希望 Codex 使用 OpenAI 官方認證時,才設定:

requires_openai_auth = true

這不適用於普通第三方模型 API Key。開啟後,Codex 會忽略該 provider 的 env_key


5. 常見錯誤與排查

5.1 CC Switch 已切換,但 Codex 仍使用舊模型

依次檢查:

  1. CC Switch 中當前啟用的是目標 Codex provider;
  2. 本機路由總開關是否開啟;
  3. Routing Enabled 中是否開啟 Codex;
  4. Chat 或 Messages provider 是否啟用了 Needs Local Routing
  5. CC Switch 是否仍在執行;
  6. 是否完全重啟了 Codex、IDE 或桌面客戶端;
  7. /debug-config 是否顯示了預期設定來源。

模型對映變更後,通常必須重啟 Codex 才能重新整理 /model 列表。

5.2 返回 404400 或找不到 /responses

常見原因:

  • 把 Chat Completions provider 當成 Responses provider;
  • Base URL 多寫或少寫了一層 /v1
  • 重複拼接了 /chat/completions
  • 非標準地址沒有開啟 Full URL Mode;
  • CC Switch 本機路由沒有接管 Codex;
  • 第三方閘道器沒有實現完整 Responses API。

CC Switch 使用者應檢查 Upstream Format 和路由日誌。手動 provider 使用者應直接用 curl 測試 <base_url>/responses

5.3 返回 401 Unauthorized403 Forbidden

檢查:

  • API Key 是否有效;
  • Key 是否屬於正確區域、專案或套餐;
  • 餘額和權限是否充足;
  • 服務要求 Bearer Token 還是 x-api-key
  • 環境變數名稱是否與 env_key 完全一致;
  • CC Switch 中是否儲存了正確金鑰;
  • 代理是否刪除了認證 Header。

檢查環境變數時不要在共享日誌中列印完整金鑰。

bash / zsh:

printenv THIRD_PARTY_API_KEY

PowerShell:

$env:THIRD_PARTY_API_KEY

5.4 第三方模型沒有出現在 /model

檢查:

  • CC Switch 的 Model Mapping 是否包含真實模型 ID;
  • provider 是否已經儲存並啟用;
  • 是否重啟了 Codex;
  • 手動設定是否提供了正確的 model_catalog_json
  • 模型目錄 JSON 是否有效;
  • 模型 ID 是否已被供應商下線或重新命名。

5.5 可以聊天,但不能讀寫檔案或執行命令

常見原因:

  • 模型本身不擅長工具呼叫;
  • 上游不支援 function calling;
  • 中轉層丟失了 tool call ID;
  • SSE 分片沒有被正確重組;
  • JSON Schema 被修改;
  • 工具結果沒有正確回傳到下一輪;
  • 模型上下文過短;
  • 模型目錄錯誤聲明瞭能力。

應使用真實專案測試“讀取 → 修改 → 執行測試 → 根據失敗繼續修復”的完整迴圈。

5.6 流式響應頻繁中斷

CC Switch 使用者先檢視本機路由日誌和上游響應。常見原因包括:

  • 上游排隊或推理時間過長;
  • 第三方閘道器沒有及時傳送 SSE;
  • CDN、反向代理或公司網路緩衝了流;
  • 上游傳送了非標準事件;
  • CC Switch 或 provider 版本存在相容問題。

手動 provider 可以適當增加:

request_max_retries = 4
stream_max_retries = 5
stream_idle_timeout_ms = 600000

增加超時只能緩解網路或長推理問題,不能修復錯誤的協議實現。

5.7 wire_api = "chat" 無法啟動

這是舊教學中常見的設定。當前 Codex 只支援:

wire_api = "responses"

如果上游只有 Chat Completions,改用 CC Switch,不要繼續嘗試 wire_api = "chat"

執行以下命令檢查其他過時欄位:

codex --strict-config

5.8 修改專案內設定後 provider 沒有變化

以下設定必須放在使用者級檔案中:

~/.codex/config.toml

專案內 .codex/config.toml 不能覆蓋會重定向請求或改變 provider 認證的欄位,包括 model_providermodel_providers

5.9 終端可用,但 IDE 擴充套件提示缺少 API Key

GUI 應用通常不會繼承剛剛在某個終端中臨時設定的環境變數。

可以:

  • 從已經設定變數的終端啟動 IDE;
  • 將變數持久儲存到系統使用者環境;
  • 完全退出並重新開啟 IDE;
  • 改用 CC Switch 管理本機 provider 設定。

5.10 切換後官方登入狀態或官方功能異常

檢查:

  • 是否先切回 OpenAI Official
  • Keep official login when switching third-party providers 是否開啟;
  • ~/.codex/auth.json 是否被舊設定覆蓋;
  • codex login status 是否正常。

必要時重新執行:

codex login

不要手動分享或編輯包含 Access Token 的 auth.json

5.11 Web Search、圖片或其他高階功能不可用

第三方 provider 能完成文本和工具呼叫,不代表支援 Codex 的全部能力。

自定義 provider 預設不會宣告 standalone Web Search。只有 provider、模型和 endpoint 都真實相容時,才應設定:

supports_standalone_web_search = true

錯誤開啟只會讓 Codex傳送上游無法處理的請求。圖片輸入、WebSocket、響應儲存和其他高階能力也應分別驗證。


6. 如何選擇接入方式

需求 推薦方式
第三方只提供 Chat Completions CC Switch
第三方只提供 Anthropic Messages CC Switch
經常在多個第三方模型之間切換 CC Switch
希望用圖形介面管理 API Key 和模型 CC Switch
第三方原生支援完整 Responses API 自定義 model provider
伺服器、CI 或無圖形介面環境 原生 Responses provider 或自建閘道器
企業需要統一鑑權、審計和限流 企業模型閘道器 + 自定義 provider
只完成普通聊天、不支援工具呼叫 不適合作為完整的 Codex 智能體 provider

推薦按三個層級驗收:

  1. 連線測試:可以穩定返回文本;
  2. 工具測試:可以讀取檔案、呼叫命令並正確回傳結果;
  3. 任務測試:可以連續完成修改、測試和修復。

最後還要確認:

  • 第三方計費方式;
  • 速率限制;
  • 請求和程式碼是否被記錄;
  • 資料儲存地區;
  • 團隊或企業合規要求;
  • 模型升級後是否需要重新測試。

使用第三方 API Key 時,費用由第三方服務或中轉平台單獨結算,不會自動使用或共享 ChatGPT Plus、Pro 或 Codex 訂閱中的額度。

參考資料