外部模型接入 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.tomlWindows:
%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 || truePowerShell:
$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-switchWindows 可以從 Releases 下載 .msi 安裝包或便攜版壓縮包。
Linux 可以從 Releases 下載 .deb、.rpm 或 AppImage。不同版本的介面文字可能略有變化,建議始終使用最新穩定版本,並以應用內實際選項為準。
1.3 準備工作
接入前準備以下內容:
- 已安裝並執行過一次 Codex;
- 已安裝並能夠正常啟動 CC Switch;
- 已獲得目標模型服務的 API Key;
- 已從供應商文件確認 Base URL、模型 ID 和上游 API 協議;
- 如果需要保留 Codex 官方賬號能力,先完成一次官方登入。
檢查 Codex 登入狀態:
codex login status需要登入時可以執行:
codex login也可以使用裝置碼登入:
codex login --device-auth1.4 可選:切換第三方 provider 時保留官方登入
這一項主要適用於同時使用 Codex 桌面功能、官方外掛或遠端控制能力的使用者。只使用 CLI 且不依賴官方登入能力時,可以跳過。
推薦順序:
- 在 CC Switch 的 Codex 頁面切換到 OpenAI Official;
- 啟動 Codex,並完成官方賬號登入;
- 在 CC Switch 開啟 Settings → General → Codex App Enhancements;
- 開啟 Keep official login when switching third-party providers;
- 再新增或切換第三方 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完成以下操作:
- 開啟本機路由總開關;
- 在 Routing Enabled 中開啟 Codex;
- 確認目標 provider 的 Needs Local Routing 狀態正確;
- 使用期間保持 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 使用者可以重新執行:
codex1.10 驗證是否接入成功
進入 Codex 後執行:
/status檢查當前模型、provider、權限和上下文資訊。
檢視模型列表:
/model檢查設定層級:
/debug-config同時檢查:
- CC Switch 當前選中的 Codex provider;
- CC Switch 本機路由日誌或統計;
- 第三方平台的請求記錄和餘額變化;
~/.codex/config.toml是否暫時指向本機路由。
不要只傳送“你好”來驗證。至少完成一次智能體能力測試:
- 讓 Codex 列出當前專案檔案;
- 讓 Codex 讀取一個檔案並總結內容;
- 讓 Codex 修改一個小檔案;
- 讓 Codex 執行測試;
- 故意保留一個簡單錯誤,觀察它能否根據測試結果繼續修復。
只有文本對話成功,不代表工具呼叫和多輪智能體工作流程已經相容。
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_party、company_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/responses2.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_provider、model_providers 和 provider 認證設定應放在使用者級檔案:
~/.codex/config.toml不要把它們放進專案儲存庫的:
<project>/.codex/config.tomlCodex 會忽略專案級設定中可能重定向模型請求或認證資訊的相關欄位。這可以防止克隆不可信儲存庫後,請求被專案設定悄悄轉發到其他伺服器。
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 仍使用舊模型
依次檢查:
- CC Switch 中當前啟用的是目標 Codex provider;
- 本機路由總開關是否開啟;
- Routing Enabled 中是否開啟 Codex;
- Chat 或 Messages provider 是否啟用了 Needs Local Routing;
- CC Switch 是否仍在執行;
- 是否完全重啟了 Codex、IDE 或桌面客戶端;
/debug-config是否顯示了預期設定來源。
模型對映變更後,通常必須重啟 Codex 才能重新整理 /model 列表。
5.2 返回 404、400 或找不到 /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 Unauthorized 或 403 Forbidden
檢查:
- API Key 是否有效;
- Key 是否屬於正確區域、專案或套餐;
- 餘額和權限是否充足;
- 服務要求 Bearer Token 還是
x-api-key; - 環境變數名稱是否與
env_key完全一致; - CC Switch 中是否儲存了正確金鑰;
- 代理是否刪除了認證 Header。
檢查環境變數時不要在共享日誌中列印完整金鑰。
bash / zsh:
printenv THIRD_PARTY_API_KEYPowerShell:
$env:THIRD_PARTY_API_KEY5.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-config5.8 修改專案內設定後 provider 沒有變化
以下設定必須放在使用者級檔案中:
~/.codex/config.toml專案內 .codex/config.toml 不能覆蓋會重定向請求或改變 provider 認證的欄位,包括 model_provider 和 model_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 |
推薦按三個層級驗收:
- 連線測試:可以穩定返回文本;
- 工具測試:可以讀取檔案、呼叫命令並正確回傳結果;
- 任務測試:可以連續完成修改、測試和修復。
最後還要確認:
- 第三方計費方式;
- 速率限制;
- 請求和程式碼是否被記錄;
- 資料儲存地區;
- 團隊或企業合規要求;
- 模型升級後是否需要重新測試。
使用第三方 API Key 時,費用由第三方服務或中轉平台單獨結算,不會自動使用或共享 ChatGPT Plus、Pro 或 Codex 訂閱中的額度。