Codex

Codex 是 OpenAI 提供的程式開發代理程式。你可以在終端機中使用 Codex CLI，也可以在桌面 App 中管理專案和任務。透過設定自訂模型供應商，Codex 可以使用 AGTCloud 的 OpenAI Responses 相容入口。

不同模型對工具呼叫、推理、多代理程式和上下文長度的支援範圍可能不同。請選擇目前 API Key 可見且支援 Responses 協議的模型。

準備工作

開始前，請確認你已經：

準備好終端機環境和需要開啟的本機專案；
註冊並登入 AGTCloud；
在 API Keys 頁面建立權杖；
從模型廣場複製目前權杖可用且支援 Responses 協議的模型 ID。

安裝 Codex

選擇與目前環境對應的安裝方式。

curl -fsSL https://chatgpt.com/codex/install.sh | sh

安裝完成後，重新開啟終端機並檢查版本：

codex --version

設定 API Key

Codex 會從自訂 Provider 指定的環境變數讀取 API Key。本教學使用獨立的 AGTCLOUD_API_KEY，避免與 OpenAI 或其他平台的 Key 混用。

臨時設定

以下設定只在目前終端機工作階段中生效。

export AGTCLOUD_API_KEY="your-api-key"

持久設定

希望每次開啟終端機都自動生效時，可以把變數寫入 shell 設定檔或 Windows 使用者環境變數。

編輯 ~/.zshrc 並加入：

export AGTCLOUD_API_KEY="your-api-key"

儲存後載入設定：

source ~/.zshrc

不要把 API Key 寫入 config.toml

config.toml 只儲存環境變數名稱。API Key 會以明文形式儲存在本機環境設定中，請只在個人可信任裝置上使用這種方式。

設定 AGTCloud Provider

Codex 的使用者層級設定位於 ~/.codex/config.toml。如果檔案已經存在，請先備份，然後將 AGTCloud Provider 合併到現有設定中，不要直接覆蓋其他設定。

mkdir -p ~/.codex

if [[ -f ~/.codex/config.toml ]]; then
    cp ~/.codex/config.toml ~/.codex/config.toml.backup
fi

在 ~/.codex/config.toml 中加入：

model_provider = "agtcloud"
model = "MODEL_ID"

[model_providers.agtcloud]
name = "AGTCloud"
base_url = "https://api.agtcloud.cn/v1"
env_key = "AGTCLOUD_API_KEY"
wire_api = "responses"

設定項目	作用
`model_provider`	將預設模型供應商切換為 AGTCloud
`model`	指定 Codex 使用的模型 ID
`base_url`	將 Responses 請求傳送到本頁顯示的 AGTCloud API 地址
`env_key`	指定儲存 API Key 的環境變數名
`wire_api`	指定使用 OpenAI Responses 協議

Provider 必須放在使用者層級設定中

專案內的 .codex/config.toml 可以儲存專案設定，但不能覆蓋 model_provider 和 model_providers。請將上述 Provider 設定放在使用者目錄的 ~/.codex/config.toml 中。

選擇模型

MODEL_ID 是需要替換的預留位置，不是真實模型名稱。請從模型廣場複製目前 API Key 可用且支援 Responses 協議的模型 ID，再替換 config.toml 中的 MODEL_ID。

進入 Codex CLI 後可以使用 /model 檢視或切換模型。自訂 Provider 下的可選範圍取決於 Codex 版本和目前 API Key；如果目標模型沒有出現，請直接更新 config.toml 中的 model。

使用 Codex CLI

進入專案目錄

cd /path/to/your/project

啟動 Codex

codex

檢查目前設定

在 Codex 中執行：

/status

確認目前 Provider、模型和設定檔符合預期。Base URL 應為本頁顯示的 /v1 API 地址，不應出現重複的 /v1/v1。

發起唯讀測試

在包含 README.md 的測試專案中輸入：

請讀取 README.md，並用三點概括這個專案的用途。不要修改任何檔案。

正常傳回內容說明基本連線已經建立。本步會產生正常的 API 用量。

使用 Codex App

重新啟動 App

儲存 ~/.codex/config.toml 和環境變數後，完全退出 Codex App，然後重新開啟。

開啟本機專案

在桌面 App 中切換到 Codex，然後選擇一個不含敏感程式碼的測試專案。

檢查模型並驗證

確認目前模型與 config.toml 一致，然後使用與 CLI 相同的 README 唯讀任務進行驗證。

App 的環境變數載入取決於版本和啟動方式

Codex App 會沿用 Codex 的本機設定，但桌面應用程式對 shell 環境變數的載入方式可能隨版本和作業系統變化。如果 CLI 可用但 App 無法讀取 API Key，請先完全重新啟動 App，再檢查使用者層級設定和環境變數。

常見問題

現象	優先檢查	處理方式
找不到 `codex` 命令	安裝結果和 `PATH`	重新開啟終端機，執行 `codex --version`，必要時重新執行官方安裝命令
API Key 未載入	`AGTCLOUD_API_KEY` 是否在目前程序中生效	重新開啟終端機或 App，再次載入使用者環境設定
Provider 設定未生效	是否誤寫到專案層級 `.codex/config.toml`	將 `model_provider` 和 `model_providers` 移到 `~/.codex/config.toml`
請求路徑出現 `/v1/v1`	`base_url` 是否被額外串接	直接使用本頁顯示的 `https://api.agtcloud.cn/v1`
傳回 `401`	API Key 和環境變數	使用有效 API Key，並確認 `env_key` 名稱一致
傳回 `403`	權杖權限、模型權限和帳戶狀態	在控制台檢查權杖及模型可用範圍
傳回 `404`	Base URL、Responses 入口和模型 ID	核對 `base_url`，並重新複製目前 Key 可用的模型 ID
模型不存在或不可用	模型可見性和 Responses 協議支援	從模型廣場複製完整 ID，選擇目前 Key 可呼叫的模型
CLI 正常但 App 未讀取設定	App 版本、設定路徑和環境變數	完全重新啟動 App；先以 CLI 驗證同一份使用者層級設定
部分進階能力不可用	目標模型能力和目前適配範圍	先使用基本唯讀任務驗證；進階能力以實際呼叫結果為準

遇到無法定位的問題時，請記錄請求時間、API Base URL、模型 ID、HTTP 狀態和去識別化錯誤資訊，然後檢視錯誤與疑難排解。不要提交完整 API Key。

安全建議

為 Codex 個別建立 API Key，便於管理權限和停用憑證。
不要把真實 Key 寫入 config.toml、程式碼、倉庫、截圖、記錄或共享腳本。
在共享裝置或團隊環境中，優先使用作業系統憑證管理或組織統一的金鑰分發方案。
API Key 疑似洩漏時，立即在控制台停用或刪除，然後建立新 Key。

下一步可以閱讀 API Key、Base URL 與驗證、OpenAI Responses 和錯誤與疑難排解。

本頁目錄