Codex 桌面版串接 AIXHUB

同一個作業系統使用者的 Codex 桌面應用程式與 Codex CLI 可以共用 Codex home。本指南會變更共用使用者檔案，因此供應端或憑證變更可能同時影響兩種使用方式。編輯前請完整關閉應用程式及其他 Codex 工作階段。

完成目標

你會在共用 Codex 使用者設定中加入最小 AIXHUB Responses 供應端，把真實金鑰留在獨立驗證檔案，完成一筆桌面唯讀請求、在 AIXHUB 用量中核對，並保留精確復原方式。

以下 Codex 使用方式彼此相關，但不可混為一談：

桌面版與 CLI 可以共用 config.toml 和 auth.json；變更任一檔案，都可能改變兩者下次工作階段。官方 ChatGPT 登入不是 AIXHUB API 金鑰，不可用來取代自訂供應端憑證。

支援平台

• Windows： 目前 Codex 應用程式支援。本指南設定 Windows 使用者設定檔下的共用檔案。
• macOS： Codex 應用程式支援。本指南使用 macOS 使用者帳號下的 Codex home。
• Linux： 本指南沒有原生桌面流程，請改用 Codex CLI。

桌面應用程式支援某個平台，不等於每個版本介面都會顯示自訂供應端選擇器。受支援的應用程式版本可能不在介面提供供應端控制；本指南會透過共用使用者檔案設定 AIXHUB，再驗證應用程式實際使用內容。

安裝或開啟應用程式

Windows 或 macOS 請透過官方 Codex 應用程式頁面安裝或更新。下載控制項與介面標示可能變動，因此本指南不虛構套件命令或精確選單路徑。

編輯前：

1. 完整結束 Codex 桌面應用程式，不要只關閉視窗。
2. 停止可能讀寫相同 Codex home 的 Codex CLI 工作階段與 IDE 整合。
3. 為首次使用準備一個小型且可丟棄的測試目錄。

儲存並檢查設定與驗證檔案後，才重新啟動桌面應用程式。Linux 使用者請繼續閱讀 CLI 指南，不要嘗試把桌面檔案套用到不支援的原生應用程式。

設定值

Codex 通常會讀取以下使用者檔案：

若已設定 CODEX_HOME，就會取代預設 .codex 目錄；請使用該精確目錄中的 config.toml 與 auth.json。也要檢查測試專案及受信任上層目錄是否有 .codex/config.toml，因為專案層級設定可能覆寫使用者供應端或模型。

使用以下 AIXHUB 設定值：

屬性名稱與供應端 ID 有大小寫之分。Base URL 只能包含一個 /v1。不要把其他機器的選用審查、內容、外掛或桌面偏好值複製到這個最小連線設定。

設定 AIXHUB

在 Windows 備份兩個共用檔案

完整關閉 Codex 後，在 PowerShell 執行以下區塊。它會採用 CODEX_HOME、建立唯一備份名稱、只在複製成功後顯示路徑，並清除備份失敗時建立的檔案；發生錯誤時不會關閉 PowerShell：

$codexHome = if ($env:CODEX_HOME) { $env:CODEX_HOME } else { Join-Path $env:USERPROFILE ".codex" }
$backupCandidates = [System.Collections.Generic.List[string]]::new()

try {
  New-Item -ItemType Directory -Force -Path $codexHome -ErrorAction Stop | Out-Null
  foreach ($name in @("config.toml", "auth.json")) {
    $sourcePath = Join-Path $codexHome $name
    if (Test-Path -LiteralPath $sourcePath -PathType Leaf) {
      $stamp = Get-Date -Format "yyyyMMddHHmmssfff"
      $suffix = [guid]::NewGuid().ToString("N").Substring(0, 8)
      $backupPath = "$sourcePath.backup.$stamp.$suffix"
      $backupCandidates.Add($backupPath)
      Copy-Item -LiteralPath $sourcePath -Destination $backupPath -ErrorAction Stop
      Write-Output "Backup created: $backupPath"
    } else {
      Write-Output "No existing $name; no backup was needed."
    }
  }
} catch {
  foreach ($path in $backupCandidates) {
    Remove-Item -LiteralPath $path -Force -ErrorAction SilentlyContinue
  }
  throw "Backup failed. Stop before editing Codex configuration."
}

在 macOS 備份兩個共用檔案

完整關閉 Codex 後，在 Bash 或 zsh 執行以下區塊：

codex_home="${CODEX_HOME:-$HOME/.codex}"
created_backups=()
backup_failed=0

if ! mkdir -p "$codex_home"; then
  printf 'Cannot prepare Codex home. Stop before editing Codex configuration.\n' >&2
  false
else
  for name in config.toml auth.json; do
    source_path="$codex_home/$name"
    if [ -f "$source_path" ]; then
      backup=""
      if backup="$(mktemp "$source_path.backup.$(date +%Y%m%d%H%M%S).XXXXXX")" && cp "$source_path" "$backup"; then
        created_backups+=("$backup")
        printf 'Backup created: %s\n' "$backup"
      else
        [ -z "$backup" ] || rm -f "$backup"
        backup_failed=1
        break
      fi
    else
      printf 'No existing %s; no backup was needed.\n' "$name"
    fi
  done

  if [ "$backup_failed" -ne 0 ]; then
    for path in "${created_backups[@]}"; do
      rm -f "$path"
    done
    printf 'Backup failed. Stop before editing Codex configuration.\n' >&2
    false
  fi
fi

只有每個既有檔案都顯示 Backup created:，且每個缺少的檔案都顯示 No existing ...; no backup was needed. 後，才能繼續。記錄本次操作的每一個精確備份路徑。若任一區塊回報失敗，請停止操作，不可編輯任何檔案。備份可能含有憑證，必須保持私密。

記錄原始狀態

合併前，請保護並記錄：

若 AIXHUB 供應端或 OPENAI_API_KEY 原本已存在，請明確判斷是否確實要取代。不要假設任一值由本指南建立，也不要假設之後可以刪除。

合併最小供應端

將以下完整最小形狀合併到使用者 config.toml：

model_provider = "AIXHUB"
model = "panel-model-id"

[model_providers.AIXHUB]
name = "AIXHUB"
base_url = "https://api.aixhub.org/v1"
wire_api = "responses"
requires_openai_auth = true

兩個最上層鍵必須放在所有 TOML 表格之前。若檔案已有其他供應端或不相關設定，請保留並合併這個表格，不要取代整份檔案。維持有效 TOML，且只能有一個 [model_providers.AIXHUB] 表格。

合併驗證欄位

新檔案的完整最小 auth.json 形狀如下：

{
  "auth_mode": "apikey",
  "OPENAI_API_KEY": "sk-your-key"
}

請在本機將 sk-your-key 替換成專用 AIXHUB API 金鑰。真實金鑰只放在 auth.json，不可放入 config.toml。若 auth.json 已存在，請合併兩個欄位：為本次 AIXHUB 自訂供應端測試把 auth_mode 設為 apikey，並新增或更新 OPENAI_API_KEY，同時保留所有不相關 Token、官方登入屬性與其他欄位。官方 ChatGPT 憑證可以繼續儲存，但 auth_mode 為 apikey 時並不是作用中的驗證選擇。

這會改變桌面版與 CLI 共用的驗證選擇；只有加入金鑰並不足以完成設定。變更前必須記錄 auth_mode 的精確原值，復原時才能還原該值；若原始狀態記為 absent，才移除該屬性。

macOS 儲存後請限制驗證檔案權限：

chmod 600 "${CODEX_HOME:-$HOME/.codex}/auth.json"

Windows 請把 auth.json 留在目前使用者的 Codex home，並以 Windows 檔案安全設定確認不相關帳號無法讀取。每一份備份都要套用相同保護。

首次使用

開啟 Codex 桌面應用程式並選擇小型可丟棄的測試目錄。只有理解目錄內容與範圍後才信任它。若任一共用檔案在應用程式開啟期間變更，請完整重新啟動。

若應用程式顯示作用中的供應端或模型，請確認 AIXHUB 與 panel-model-id。核准與沙箱權限只保留觀察所需的最小範圍。送出以下請求：

請檢查目前資料夾，但不要變更任何檔案，也不要執行會改變狀態的命令。只回覆 OK。

第一次請求不要核准檔案寫入、會改變狀態的 Shell 命令，或測試目錄以外的存取。

驗證

應用程式應回傳：

OK

若應用程式顯示供應端或模型資訊，請確認 AIXHUB 與 panel-model-id。接著開啟 AIXHUB 用量，核對請求時間、panel-model-id 與成功狀態。只有用量實際顯示 API 模式時才核對；本指南不假設一定存在協定欄位。

疑難排解

出現官方登入或未載入自訂設定

官方 ChatGPT 登入不是 AIXHUB 憑證。完整結束應用程式及其他 Codex 工作階段，確認實際 CODEX_HOME、model_provider 與 model 位於供應端表格之前，並確認共用 auth.json 在本次自訂供應端測試中將 auth_mode 設為 apikey。重新啟動應用程式後，也要檢查專案或受信任上層目錄是否有 .codex/config.toml。

401 或驗證失敗

確認實際 Codex home 中的 auth.json 將 auth_mode 設為 apikey，而且精確 OPENAI_API_KEY 屬性含有目前有效的專用 AIXHUB 金鑰。保留不相關的官方登入與 Token 屬性，但不可用它們取代作用中的自訂供應端金鑰。檢查時不要顯示金鑰。

404 或 API 版本重複

base_url 必須剛好是 https://api.aixhub.org/v1。缺少版本、把完整 /v1/responses 端點填入 Base URL，或出現 /v1/v1，都可能造成路由錯誤。

model not found

從模型路由重新複製完整相容 ID，並維持最上層 model = "panel-model-id" 同步。不要使用顯示名稱，也不要自行猜測版本字尾。

專案覆寫使用者供應端

檢查測試專案及受信任上層目錄中的 .codex/config.toml。請記錄並解決衝突的供應端或模型值，不要刪除來源不明的專案檔案。變更後重新啟動應用程式。

請求成功但用量沒有相符記錄

應用程式可能使用官方帳號、其他供應端或專案覆寫。檢查應用程式提供的供應端或模型指示、確認共用使用者檔案、完整重啟，再重做小型請求。請到用量比對時間、模型與狀態，不要只看畫面回應就判定路由。

桌面版與 CLI 相互影響

編輯前同時關閉兩種使用方式。若 CLI 工作階段變更 config.toml 或 auth.json，下一個桌面工作階段可能載入這些值，反向也一樣。請只維護一份已記錄的共用狀態，並在刻意變更後分別驗證兩種使用方式。

若收到 403、429、502 或 503，請繼續參考錯誤代碼。

升級與復原

請透過官方 Codex 應用程式頁面或已安裝應用程式提供的更新管道升級。不要為了更新應用程式而取代共用設定。升級後完整重啟，並在授予更大權限前重做唯讀請求。

復原前先關閉 Codex 桌面版、CLI 與 IDE 整合，再重新讀取目前檔案，並與受保護的原始狀態紀錄比較。只有在受控驗證期間，而且確認設定後沒有新增任何不相關狀態時，才能用本次操作記錄的精確時間戳備份取代整份檔案。若後來的官方登入、桌面偏好、供應端、Token 或其他屬性必須保留，就不可覆寫整份檔案；請把 AIXHUB 相關復原內容合併到目前檔案。

若 config.toml 原本為 absent，只有目前檔案仍精確等於本指南最小 TOML 時，才能刪除整份檔案。若有任何後來新增的設定，請保留檔案；只有 model_provider、model 與 model_providers.AIXHUB 仍符合本指南加入內容，且原始紀錄明確記為 absent 時，才能復原或移除這些項目。原本已有值或供應端表格時，請還原精確原值或完整表格，並保留所有後來新增的不相關設定。

若 auth.json 原本為 absent，只有目前檔案仍精確包含本指南建立的 auth_mode: "apikey" 與專用 OPENAI_API_KEY 時，才能刪除整份檔案。否則請保留檔案，把 auth_mode 還原為記錄的精確原值；只有原始紀錄為 absent 且該屬性仍屬於本次變更時，才能移除。OPENAI_API_KEY 只有確認仍是本次操作的專用 AIXHUB 金鑰時，才能還原或移除。所有後來新增的不相關登入、Token、桌面或其他屬性都必須保留。

若沒有可用備份，請依受保護紀錄套用相同欄位層級規則。任一欄位、供應端表格、驗證模式或金鑰的歸屬未知時，請停止，不要猜測、刪除或覆寫。

還原共用使用者設定也會影響 Codex CLI。驗證還原後的 TOML 與 JSON，再分別驗證桌面版與 CLI，之後才恢復一般工作。

安全注意事項

• 為 Codex 建立專用 AIXHUB 金鑰，才能在不影響其他用戶端或應用程式程式碼的情況下輪替。
• auth.json 及每一份時間戳備份只能讓目前使用者讀取。復原觀察期結束且驗證成功後，請清理不再需要的備份。
• 官方 ChatGPT 登入資料必須分開；不可把 AIXHUB 金鑰貼進官方登入流程。
• 允許工具或寫入前，檢查專案信任、核准內容與沙箱範圍。
• 不可提交金鑰、貼進提示內容，或放入螢幕擷取畫面、診斷、支援記錄與設定範例。
• 金鑰外洩後立即輪替，再更新受保護的共用驗證檔案，並重新驗證桌面版與 CLI。

官方資料

• Codex 應用程式
• Codex 設定參考

最後核對：2026-07-14