在 Codex 客戶端中接入 Tokatlas
1. 安裝與準備
透過 OpenAI 官方桌面指南 安裝適用於作業系統的客戶端。準備 Tokatlas API Key，以及已開通且相容於 Codex 與 Responses API 的模型。
下方模型 ID 為佔位值，請替換為 Tokatlas 的完整模型 ID；客戶端顯示模型不代表帳戶已開通。若使用自訂別名，請向閘道管理者取得相符的 Codex 模型目錄。
2. 設定提供方
完全退出應用程式，備份既有檔案，再將以下設定合併至使用者設定檔：
| 系統 | 預設路徑 |
|---|---|
| macOS | ~/.codex/config.toml |
| Windows | %USERPROFILE%\.codex\config.toml |
model = "YOUR_TOKATLAS_MODEL_ID"
model_provider = "tokatlas"
web_search = "disabled"
[model_providers.tokatlas]
name = "Tokatlas"
base_url = "https://api.tokatlas.ai/v1"
wire_api = "responses"
env_key = "TOKATLAS_API_KEY"將 model、model_provider 與 web_search 放在所有 TOML 表格標頭之前。已有相同鍵值時請修改，勿重複新增。使用使用者設定檔，而非專案內的檔案；若自訂了 CODEX_HOME，請使用該設定目錄。
Base URL 以 /v1 結尾，不需再加 /responses。初次驗證先停用網頁搜尋，確認閘道支援後再開啟其他選用功能。
3. 讓應用程式讀取金鑰
使用與 env_key 相同的 TOKATLAS_API_KEY。實際金鑰不要寫入 config.toml 或專案檔案。
macOS
在終端機先啟動 Bash，再輸入以下指令，於提示時貼上金鑰。輸入內容不會顯示。
bashread -r -s -p "Tokatlas API key: " TOKATLAS_API_KEY
printf "\n"
launchctl setenv TOKATLAS_API_KEY "$TOKATLAS_API_KEY"
unset TOKATLAS_API_KEY
exit設定後重新開啟桌面應用程式。launchctl setenv 適用於目前登入階段，登出或重新開機後須再次設定。僅在 .zshrc 匯出的變數，不一定能被 Finder 啟動的應用程式讀取。
Windows
在 Windows 開啟「編輯您帳戶的環境變數」。新增名稱為 TOKATLAS_API_KEY 的使用者變數，值填入 Tokatlas 金鑰。登出 Windows 並重新登入後，再啟動應用程式，以讀取新環境。
4. 驗證連線
開啟專案並建立新對話，傳送簡單請求，例如「說明這個專案，不修改檔案」。檢查目前模型與提供方，並在 Tokatlas 用量記錄確認請求成功。接著以小型程式任務驗證串流與工具行為。
切換模型或還原設定
切換模型時，修改頂層 model、重新啟動應用程式，再建立新對話。若有模型目錄，須與選定 ID 保持一致。若要恢復原本設定，還原備份的設定檔並重啟；不需刪除整個設定目錄或對話歷史。
若不再需要 Tokatlas 金鑰，請刪除 Windows 使用者變數，或在 macOS 執行：
launchctl unsetenv TOKATLAS_API_KEY常見問題
| 狀況 | 檢查方式 |
|---|---|
| 找不到金鑰 | 確認應用程式可讀取 TOKATLAS_API_KEY，再完全重啟。 |
401 | 檢查完整金鑰並移除前後空白。 |
403 | 檢查 Tokatlas 帳戶與模型權限。 |
404 | 檢查 /v1、wire_api = "responses" 與模型 ID。 |
| TOML 解析錯誤 | 移除重複鍵值或表格，檢查引號。 |
| 提供方未變更 | 檢查使用者設定、選定 profile 與受管理設定的覆寫。 |
| 文字可用但 Agent 失敗 | 檢查模型的 Responses 串流與工具相容性。 |
| 未知模型 | 使用已開通且客戶端可識別的 ID，或取得相符模型目錄。 |