Codex CLI 串接 AIXHUB

本指南會透過 OpenAI Responses 介面，將 Codex 命令列用戶端連到 AIXHUB。供應端設定放在 config.toml，API 金鑰則存放在另一個使用者層級 auth.json，避免把秘密值混入一般設定。

完成目標

完成本指南後，你會得到以下結果：

1. 透過 npm 安裝 Codex CLI 並確認版本。
2. 加入使用 Responses 傳輸格式的最小 AIXHUB 供應端設定。
3. 將 AIXHUB 憑證與供應端設定分開存放。
4. 完成一筆唯讀請求，並與 AIXHUB 用量記錄核對。
5. 備份原始檔案，能復原先前的供應端與驗證狀態。

系統需求

• Windows、macOS 或 Linux，並具備受支援的 Node.js 版本，且可從 PATH 執行 npm。
• 能以目前使用者或目前 Node.js 環境安裝全域 npm 套件。
• AIXHUB 帳號、一組 AIXHUB API 金鑰，以及從模型路由複製的 Responses 相容模型 ID。本指南的所有模型欄位都使用 panel-model-id。
• 能維持 TOML 與 JSON 語法的文字編輯器。

Codex 會從下列位置讀取使用者設定：

• Windows：%USERPROFILE%\.codex\config.toml
• macOS 與 Linux：~/.codex/config.toml

憑證檔案位於相同目錄；Windows 是 %USERPROFILE%\.codex\auth.json，macOS 與 Linux 是 ~/.codex/auth.json。編輯前先備份兩個既有檔案。

安裝

安裝官方 npm 套件：

npm install -g @openai/codex

開啟新的終端機，確認實際載入的版本：

codex --version

若找不到命令，先檢查 npm 的全域可執行檔目錄與目前 PATH，不要先變更 AIXHUB 設定。

AIXHUB 設定

建立最小連線設定

先備份使用者層級 config.toml，再寫入或合併以下完整最小設定。供應端識別字 AIXHUB 在兩處必須完全一致：

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

Codex CLI 的 Base URL 必須剛好含有一個 /v1。wire_api = "responses" 會選用 Responses 請求格式；requires_openai_auth = true 則讓 Codex 從驗證資料中取得標準 API 金鑰欄位。

分開儲存憑證

先備份既有 auth.json。若其中還有其他登入資料，請合併屬性，不要取代整份檔案。最小 AIXHUB 憑證檔案如下：

{ "OPENAI_API_KEY":"sk-your-key" }

Windows 儲存為 %USERPROFILE%\.codex\auth.json，macOS 與 Linux 儲存為 ~/.codex/auth.json。供應端名稱與模型留在 config.toml，秘密值只放在 auth.json。

macOS 與 Linux 儲存後，請限制憑證檔案權限：

chmod 600 ~/.codex/auth.json

Windows 請把檔案保留在使用者設定檔目錄，並確認存取控制清單未允許不相關帳號讀取。

連線成功後才加入常用選項

測試連線不需要審查模型、推理強度、回應儲存偏好、沙箱網路存取或其他桌面偏好。請先讓最小供應端成功，再依需求合併個別選項。實際檔案中的最上層設定要放在 [model_providers.AIXHUB] 前方，沙箱表格則維持獨立：

review_model = "panel-model-id"
model_reasoning_effort = "high"
disable_response_storage = true
sandbox_mode = "workspace-write"

[sandbox_workspace_write]
network_access = "enabled"

sandbox_mode = "workspace-write" 是上方 network_access 表格的使用情境。核准、通知與其他桌面或介面偏好仍應分開處理，因為它們是工作方式選擇，不是連線必要條件。

首次使用

切換到小型測試專案並啟動 Codex CLI：

codex

確認畫面顯示的模型是 panel-model-id，再送出範圍明確的唯讀工作：

請以唯讀方式查看目前目錄，不要變更任何檔案。只回覆 OK。

首次請求不要核准檔案寫入，也不要核准會改變狀態的命令。若用戶端開啟官方 OpenAI 登入流程，而不是讀取 auth.json，請停止並依照下方驗證疑難排解處理。

驗證

成功時應看到以下實際輸出：

OK

開啟 AIXHUB 用量，確認出現一筆使用 panel-model-id 的 Responses 請求。核對時間是否與測試一致，並確認供應端 Base URL 設為 https://api.aixhub.org/v1。

疑難排解

401 或缺少 API 金鑰

確認目前使用的 Codex 主目錄含有 auth.json、JSON 屬性名稱完全是 OPENAI_API_KEY，而且值為 sk-your-key。檢查 JSON 語法與檔案權限後，重新啟動 Codex CLI。

出現官方 OpenAI 登入流程

確認實際載入的使用者 config.toml 含有 model_provider = "AIXHUB" 與 requires_openai_auth = true，相鄰的 auth.json 也已寫入 API 金鑰。不要完成不相關的官方帳號登入來掩蓋本機憑證遺漏。

model not found

從模型路由重新複製完整模型 ID，並維持 model = "panel-model-id"。若加入選用的 review_model，請另外確認 panel-model-id 可用於審查工作。主要路由必須支援 Responses 請求。

Base URL 不正確

使用剛好含有一個 /v1 的 https://api.aixhub.org/v1。缺少版本路徑或重複成 /v1/v1 都可能造成路由或端點錯誤。不要在本頁沿用 Claude Code 的 Base URL，因為兩個用戶端組合請求的方式不同。

專案層級設定覆寫使用者檔案

檢查專案與受信任的上層目錄是否有 .codex/config.toml，也要確認 CODEX_HOME 是否指向預期使用者目錄以外的位置。命令列旗標、所選設定組與專案設定也可能取代使用者模型或供應端。移除衝突的覆寫，或讓它採用相同 AIXHUB 值。若收到 403、429、502 或 503，請繼續參考錯誤代碼。

升級與復原

升級 npm 套件並確認新的可執行檔版本：

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

若要復原，先關閉 Codex CLI，再還原 config.toml 與 auth.json 備份。若沒有備份，請先刪除 [model_providers.AIXHUB] 區塊，以及本指南新增的最上層 model_provider 與 model。只有審查、推理、儲存或沙箱選項是專為本次設定加入，而且後續不再需要時，才一併移除。

auth.json 中的 OPENAI_API_KEY 是通用憑證欄位。只有確認目前值是為本次設定建立的專用 AIXHUB API 金鑰時，才能刪除。若該值屬於其他供應端或官方帳號，請保留此屬性，並在下次啟動前重新設定相符的官方登入或 API 金鑰。不要清除不相關的登入資料。

復原後開啟新的終端機，確認 codex --version，並在允許任何寫入操作前檢查目前供應端。

安全注意事項

• sk-your-key 只是秘密值的替代文字。切勿提交真實 auth.json、把金鑰貼進提示內容，或放入記錄。
• 把 auth.json 保留在使用者設定檔目錄並限制權限；它也要與可能提供給支援人員的 config.toml 備份分開。
• 為 Codex CLI 建立專用 AIXHUB API 金鑰，才能獨立輪替或撤銷。
• 信任專案前先檢視專案層級 .codex/config.toml；它可以變更模型、核准與沙箱行為。
• 只有工作確實需要時才啟用選用的 network_access，之後仍要逐次檢視命令核准內容。

官方資料

• Codex CLI 官方說明
• Codex 設定參考

最後核對：2026-07-14