Codex CLI

Codex CLI 是 OpenAI 的官方編程代理。首次接入建議使用控制台「一鍵接入」；手動接入需要配置 config.toml 和 OPENAI_API_KEY。

推薦：控制台一鍵接入

選擇 Codex 分組金鑰

登入控制台，在「API 金鑰」找到 Codex Plus 或 Codex Pro 分組的金鑰。

生成接入命令

點金鑰旁的「一鍵接入」，選擇 Codex CLI，確認系統是 macOS / Linux 還是 Windows PowerShell，再點「產生接入命令」並複製。

執行並驗證

macOS 開「終端機」，Linux 開任一終端機（需已安裝 curl），Windows 開「PowerShell」，貼上命令執行；完成後重新開啟終端機，輸入 codex。腳本用 npm 安裝 Codex CLI：電腦上沒有 Node.js 時只寫入配置，請先安裝 Node.js LTS，再執行 npm install -g @openai/codex。

偏好圖形介面時，按CC Switch 指南從金鑰選單點「匯入 CCS」，再選擇 Codex CLI。

一鍵接入會整份重寫 config.toml：

原檔案先備份為 config.toml.bak.時間戳；新配置寫入 model = "gpt-6-astra"、model_reasoning_effort = "xhigh" 和 requires_openai_auth = true，金鑰寫進 ~/.codex/auth.json，不設定環境變數。xhigh 是最高推理檔位，token 消耗最多，日常可改成 high 或 medium。

推理檔位與分組

設定	說明
`model_reasoning_effort`	可選 `low` / `medium` / `high` / `xhigh`；檔位越高思考越久、token 消耗越多
Codex Plus / Codex Pro 分組	兩組可用模型相同：`gpt-6-astra`、`gpt-6-sol`、`gpt-6-luna`、`gpt-5.6-sol`、`gpt-5.6-terra`、`gpt-5.6-luna`、`gpt-5.5`；以當前金鑰調 `GET /v1/models` 的返回為準
生成圖片	Codex 分組不提供 `gpt-image-`。生圖請給金鑰加上 GPT Image 全系* 分組，見圖片生成 API

手動配置

系統	`config.toml` 位置
macOS / Linux	`~/.codex/config.toml`
Windows	`C:\Users\你的使用者名稱\.codex\config.toml`

如果檔案不存在，請建立檔案並填入以下內容：

# config.toml
model_provider = "hopbase"
model = "gpt-5.6-sol"

[model_providers.hopbase]
name = "HopBase"
base_url = "https://api.hop-base.com/v1"
wire_api = "responses"
env_key = "OPENAI_API_KEY"

不要混用兩種金鑰寫法：

手動配置用 env_key 從環境變數讀金鑰；一鍵接入用的是 requires_openai_auth = true 加 auth.json。不要把 requires_openai_auth = true 和環境變數寫法混在同一份配置裡：Codex 0.153 實測這種組合不發送金鑰，網關返回 401 missing_api_key。

設定 OPENAI_API_KEY 後啟動 Codex：

臨時設定：只在當前終端機視窗有效。

export OPENAI_API_KEY=sk-你的金鑰
codex

永久設定：寫入 shell 啟動檔，之後新開終端機即可使用。

# zsh（macOS 預設）
echo 'export OPENAI_API_KEY=sk-你的金鑰' >> ~/.zshrc
source ~/.zshrc

# bash（Linux 常見；與上面 zsh 二選一）
echo 'export OPENAI_API_KEY=sk-你的金鑰' >> ~/.bashrc
source ~/.bashrc

聯網搜索與遠端壓縮暫不支援：

Codex 的聯網搜索會請求 /v1/alpha/search，遠端上下文壓縮會請求 /v1/responses/compact，這兩個接口目前都不支援，會返回 404。聯網搜索的 404 不影響普通對話；不想看到這條報錯，在 Codex 中關閉聯網搜索即可。

必須用 Codex 分組的金鑰：

請使用 Codex 分組（Codex Plus / Codex Pro）的金鑰。回應慢或返回 502 / 503 時按錯誤碼與重試處理；卡住了？看報錯速查。

下一步

CC Switch：Codex App 接入，或在多把金鑰之間切換
OpenAI SDK：在自己的程式裡調用同一批 GPT 模型
報錯速查：按報錯原文排查