使用 CometAPI 搭配 Codex

使用本指南，將 Codex 透過 CometAPI 作為模型提供者來執行。官方參考資料：

先決條件

Requirement	Details
OS	macOS、Linux、Windows 原生 PowerShell，或搭配 WSL 的 Windows
Git	建議使用 2.23+
Codex	從 Codex quickstart 安裝 Codex app 或 Codex CLI
CometAPI API key	從 CometAPI dashboard 取得
Model ID	使用來自 Models page 的 model ID

選擇設定方式

我們提供兩種選項，協助你快速設定 Codex。

選項 1：手動設定 Codex（建議）

直接編輯使用者層級的 ~/.codex/config.toml 檔案。這是最可靠的方式，特別適合 Windows 與 WSL 使用者。

選項 2：透過腳本設定

執行設定腳本作為快捷方式。它會寫入相同的 provider 設定，並為 Codex 儲存 CometAPI API key。

手動設定 Codex

Codex 會從使用者層級的 ~/.codex/config.toml 檔案讀取個人 provider 預設值。請在該處設定 CometAPI provider，而不是在專案的 .codex/config.toml 檔案中設定。Codex 會忽略專案設定檔中的 provider 與 provider-auth 設定。建議的設定方式是使用具名的 cometapi provider 與以命令為基礎的驗證。這樣可讓 CometAPI 與內建的 OpenAI provider 分開，不需要依賴 shell 環境繼承，也不會取代 ~/.codex/auth.json。

macOS / Linux / WSL
Windows PowerShell

將你的 CometAPI API key 儲存在本機 key 檔案中：

mkdir -p "$HOME/.codex"
printf "%s\n" "$COMETAPI_KEY" > "$HOME/.codex/cometapi_key"
chmod 600 "$HOME/.codex/cometapi_key"

將以下設定加入 ~/.codex/config.toml：

model_provider = "cometapi"
model = "your-model-id"

[model_providers.cometapi]
name = "CometAPI"
base_url = "https://api.cometapi.com/v1"
wire_api = "responses"

[model_providers.cometapi.auth]
command = "sh"
args = ["-c", "cat \"$HOME/.codex/cometapi_key\""]

將你的 CometAPI API key 儲存在 Windows 的 Codex 主目錄中：

New-Item -ItemType Directory -Force "$HOME\.codex" | Out-Null
Set-Content -NoNewline -Path "$HOME\.codex\cometapi_key" -Value $env:COMETAPI_KEY

將以下設定加入 $HOME\.codex\config.toml：

model_provider = "cometapi"
model = "your-model-id"

[model_providers.cometapi]
name = "CometAPI"
base_url = "https://api.cometapi.com/v1"
wire_api = "responses"

[model_providers.cometapi.auth]
command = "powershell.exe"
args = [
  "-NoProfile",
  "-Command",
  "$p=Join-Path $HOME '.codex/cometapi_key'; (Get-Content -Raw $p).Trim()",
]

Windows 原生 Codex 使用的是 $HOME\.codex，通常是 C:\Users\<user>\.codex。WSL 使用的是 Linux 發行版的 ~/.codex。請編輯與 Codex agent 執行環境相對應的目錄。

使用環境變數驗證

如果你偏好將 CometAPI API key 保存在環境變數中，請使用 env_key，而不是 [model_providers.cometapi.auth] 區塊。只有在啟動 Codex 的環境中可取得 COMETAPI_KEY 時，才使用這個 provider 設定：

model_provider = "cometapi"
model = "your-model-id"

[model_providers.cometapi]
name = "CometAPI"
base_url = "https://api.cometapi.com/v1"
wire_api = "responses"
env_key = "COMETAPI_KEY"

不要將 env_key 與 [model_providers.cometapi.auth] 一起使用。Codex 對每個自訂 provider 只支援一種驗證方式。

執行設定腳本

設定腳本是可選的。它會將相同的 cometapi provider 設定寫入 ~/.codex/config.toml、將你的 CometAPI API key 儲存於 ~/.codex/cometapi_key、在變更檔案前建立備份，並在可使用 Codex CLI 時透過 codex exec 驗證設定。對於 macOS、Linux 或 WSL，執行互動式安裝程式：

sh -c "$(curl -fsSL https://raw.githubusercontent.com/cometapi-dev/integrations/main/codex/setup.sh)"

若要進行非互動式設定，請明確傳入 API key：

curl -fsSL https://raw.githubusercontent.com/cometapi-dev/integrations/main/codex/setup.sh | sh -s -- --key "$COMETAPI_KEY"

對於原生 Windows PowerShell，執行互動式安裝程式：

powershell -c "irm 'https://raw.githubusercontent.com/cometapi-dev/integrations/main/codex/setup.ps1' | iex"

若要進行非互動式 Windows 設定，請明確傳入 API key：

powershell -c "& ([scriptblock]::Create((irm 'https://raw.githubusercontent.com/cometapi-dev/integrations/main/codex/setup.ps1'))) -Key $env:COMETAPI_KEY"

預設情況下，腳本不會取代 ~/.codex/auth.json，也不會移除 ChatGPT 登入。只有在你希望腳本透過 auth.json 管理 Codex API-key 登入時，才使用 --force-auth-json 或 -ForceAuthJson。

選擇或變更 model ID

請使用來自Models 頁面的 model ID。在手動設定中，請變更 ~/.codex/config.toml 內的 model 值。對於 macOS、Linux 或 WSL，執行設定腳本時傳入 --model：

curl -fsSL https://raw.githubusercontent.com/cometapi-dev/integrations/main/codex/setup.sh | sh -s -- --key "$COMETAPI_KEY" --model your-model-id

對於原生 Windows PowerShell，執行設定腳本時傳入 -Model：

powershell -c "& ([scriptblock]::Create((irm 'https://raw.githubusercontent.com/cometapi-dev/integrations/main/codex/setup.ps1'))) -Key $env:COMETAPI_KEY -Model 'your-model-id'"

當 CODEX_HOME 已設定時，腳本會使用它。否則它會寫入目前環境的 ~/.codex。

驗證設定

若要使用 Codex CLI 驗證設定，請在任何本機專案中執行這個唯讀命令：

codex exec --ephemeral --skip-git-repo-check --sandbox read-only --color never "Reply exactly with: COMETAPI_CODEX_OK"

如果 PATH 中無法使用 Codex CLI，請開啟 Codex app，並從本機專案送出一個簡短的 Prompt。

疑難排解

Codex 仍然使用預設的 OpenAI 提供者

確認使用者層級的 ~/.codex/config.toml 檔案中包含 model_provider = "cometapi"。

API key 已變更

更新 ~/.codex/cometapi_key，或使用更新後的 $COMETAPI_KEY 值重新執行設定腳本。

PowerShell 腳本在預先檢查期間失敗

請使用手動 Windows 原生 PowerShell 步驟，然後執行驗證指令。

透過管線傳入的 shell 設定未要求提供 API key

使用 --key "$COMETAPI_KEY"、設定 COMETAPI_KEY，或執行互動式 sh -c "$(curl ...)" 指令。

連線逾時或使用了錯誤的 base URL

確認 ~/.codex/config.toml 中的 base_url 為 https://api.cometapi.com/v1。

找不到 model

請查看模型頁面以取得可用的 model ID。

Windows 設定影響了錯誤的環境

在 Windows 原生模式下編輯 $HOME\.codex，或在 WSL agent 模式下編輯 WSL 內的 ~/.codex。

ChatGPT 登入方式已變更

除非你想使用 API-key 登入模式，否則不要使用 --force-auth-json 或 -ForceAuthJson。

概覽

AI 程式設計代理

AI 代理

AI 聊天客戶端

翻譯與語言

自動化平台

可觀測性與評估

AI 框架

先決條件

選擇設定方式

選項 1：手動設定 Codex（建議）

選項 2：透過腳本設定

手動設定 Codex

使用環境變數驗證

執行設定腳本

選擇或變更 model ID

驗證設定

疑難排解

​先決條件

​選擇設定方式

選項 1：手動設定 Codex（建議）

選項 2：透過腳本設定

​手動設定 Codex

​使用環境變數驗證

​執行設定腳本

​選擇或變更 model ID

​驗證設定

​疑難排解

先決條件

選擇設定方式

手動設定 Codex

使用環境變數驗證

執行設定腳本

選擇或變更 model ID

驗證設定

疑難排解