RealRelay.ai
程式碼代理

Codex CLI 設定指南

透過 OpenAI Responses 端點將 OpenAI Codex CLI 接上 RealRelay.ai:安裝、在 config.toml 中新增自訂模型供應商、檢查連線並選擇模型。

建立 API 密鑰瀏覽模型目錄
協定
OpenAI Responses
基礎位址
https://www.realrelay.ai/v1
官方文件
learn.chatgpt.com
已對照工具官方文件核對
2026-10
實驗性. 尚未在 RealRelay.ai 上完整端對端測試。步驟依據該工具的官方文件；若某一步失敗，請附上錯誤訊息聯絡支援。

概覽

Codex CLI 是 OpenAI 推出的終端機程式碼代理。它在你的版本庫中工作,並在你授予的權限範圍內編輯檔案、執行指令。Codex 只使用 OpenAI Responses 協定,因此是連到 RealRelay.ai 的 /v1/responses 端點。

  • 一組 API 金鑰,在主控台的 API 金鑰頁面取得。

  • 基礎位址要含 /v1。Codex 會在後面加上 /responses。

  • 一個 RealRelay.ai 在 Responses 上提供的模型 ID,例如 openai/gpt-5.3-codex。目錄中大多數模型只支援 Chat Completions,無法在 Codex 中使用。

本指南屬實驗性質。RealRelay.ai 並未提供 Codex 的模型目錄,所以 Codex 會以後備中繼資料執行每一個 RealRelay.ai 模型,並為此印出警告。上下文視窗需要你自行設定,而依賴模型目錄中繼資料的功能,行為可能與 OpenAI 自家服務不同。

安裝

請使用 OpenAI 提供的任一種安裝方式。在 Windows 上請使用 npm;OpenAI 的 Codex 頁面也列有獨立的 PowerShell 安裝程式。

macOS · Linux
curl -fsSL https://chatgpt.com/codex/install.sh | shcodex --version
Homebrew
brew install --cask codexcodex --version
npm
npm install -g @openai/codexcodex --version

如果 codex --version 印出版本號,就代表安裝成功。使用自訂供應商時,不需要以 ChatGPT 登入。

設定

  1. 1

    新增供應商

    開啟 ~/.codex/config.toml(Windows 上為 %USERPROFILE%\.codex\config.toml),並合併以下內容。如果檔案中已設定 model 或 model_provider,請直接取代那幾行,不要再加一份。

    ~/.codex/config.toml
    1# Top-level keys first: anything below a [table] header belongs to that table.2model = "openai/gpt-5.3-codex"3model_provider = "realrelay"4web_search = "disabled"5# Codex has no built-in metadata for RealRelay.ai model IDs. Set these to the6# limits on the model's catalog page.7model_context_window = 4000008model_auto_compact_token_limit = 300000910[model_providers.realrelay]11name = "RealRelay.ai"12base_url = "https://www.realrelay.ai/v1"13wire_api = "responses"14env_key = "REALRELAY_API_KEY"
  2. 2

    把金鑰放進環境變數

    Codex 會從 env_key 指定的變數讀取金鑰。請把 sk-*** 換成你的金鑰。

    ~/.zshrc · ~/.bashrc
    export REALRELAY_API_KEY="sk-***"

    執行 source ~/.zshrc,或開啟新的終端機。

    Windows PowerShell
    [Environment]::SetEnvironmentVariable("REALRELAY_API_KEY", "sk-***", "User")

    完成後請關閉並重新開啟終端機。

  • model、model_provider 與 web_search 必須放在第一個 [table] 標頭之前。放在標頭之後的鍵會歸屬於該表格,Codex 會直接忽略它,不會報錯。

  • 供應商需要自己的 ID。openai、ollama 與 lmstudio 是保留字,所以範例使用 realrelay。

  • wire_api = "responses" 是目前 Codex 唯一接受的值。舊指南中使用的 "chat" 已經無法運作。

  • web_search = "disabled" 會移除 Codex 的網頁搜尋工具,OpenAI 建議第一次測試閘道時這樣設定。

  • 不要把金鑰寫進 config.toml。Codex 桌面應用程式看不到只在終端機中 export 的變數。

驗證

  1. 1

    直接呼叫端點

    在已設定金鑰的終端機中執行這段指令。若收到含 "object": "response" 的 JSON 回覆,就代表位址、金鑰與模型在 Responses 上都沒問題。

    Terminal
    1curl -sS "https://www.realrelay.ai/v1/responses" \2  -H "Authorization: Bearer $REALRELAY_API_KEY" \3  -H "Content-Type: application/json" \4  -d '{"model": "openai/gpt-5.3-codex", "input": "Reply with OK"}'
  2. 2

    執行診斷

    codex doctor 會檢查設定。auth 那一行應顯示你的變數為 (present),而推論 URL 應可連線。探測時出現 HTTP 404 或 401 是正常的,代表 TLS 與路由都沒問題。

    Terminal
    codex doctor | grep -E 'auth|reachab'
  3. 3

    送出第一則訊息

    在專案中啟動 Codex,並執行 /status。畫面應顯示 realrelay 供應商與你的模型。接著送出測試提示詞,回覆應為 gateway-ok。這個請求也會出現在主控台的用量日誌中。

    Codex CLI
    1cd /path/to/your/project2codex3/status4Reply with exactly: gateway-ok

模型

/model 選單列出的是 Codex 自己模型目錄中的模型,所以 RealRelay.ai 的模型 ID 通常不會出現在那裡。要切換模型,請修改 config.toml 中的 model,或在單次工作階段中以 -m 啟動 Codex:

Terminal
codex -m openai/gpt-5.3-codex

只有在 /v1/responses 上提供的模型能在 Codex 中使用:openai/gpt-5.3-codex、openai/*-pro 系列模型,以及 xai/grok-* 文字模型。最新清單請見選擇模型。一般的 openai/gpt-5.x、Claude、GLM、Kimi 及其他系列都只支援 Chat Completions。

由於 Codex 沒有這些 ID 的中繼資料,請把 model_context_window 設為模型目錄頁面上標示的視窗大小,並讓 model_auto_compact_token_limit 低於這個值。範例中的數值適用於 openai/gpt-5.3-codex(400,000 token)。

疑難排解

  • 「wire_api = "chat" is no longer supported」。設定來自舊指南。請改為 wire_api = "responses"。

  • codex doctor 表示缺少 auth 環境變數。終端機是在你加入金鑰之前開啟的。請執行 source ~/.zshrc,或開啟新的終端機。若是桌面應用程式,請把變數設定在應用程式看得到的地方,然後重新啟動應用程式。

  • 401「Invalid token」。金鑰錯誤或已被刪除。請從主控台重新複製。

  • 「Model metadata for … not found. Defaulting to fallback metadata」。搭配 RealRelay.ai 時這是預期中的訊息,因為 RealRelay.ai 沒有 Codex 模型目錄。請求仍可正常運作;請依「模型」一節的說明設定上下文視窗。

  • 第一則訊息就出現指名該模型的錯誤。該模型不在 Responses 上提供,或 ID 拼錯了。請從「模型」一節的清單中挑選,並完整複製 ID。

  • 你設定的供應商或模型沒有生效。/status 顯示的是別的設定。請確認最上層的鍵位於 [model_providers.realrelay] 之上,且沒有任何 profile 覆寫它們。

  • curl 可以正常運作,但 Codex 回報「TLS handshake or certificate validation failed」。當 Codex 內附的憑證庫尚未收錄簽發本站憑證的根憑證時,就可能發生這種情況。請讓 Codex 改用系統憑證,開啟新的終端機,再執行一次 codex doctor。更新 Codex 也可能解決這個問題。

    ~/.zshrc (macOS)
    export SSL_CERT_FILE=/etc/ssl/cert.pem
    ~/.bashrc (Debian · Ubuntu)
    export SSL_CERT_FILE=/etc/ssl/certs/ca-certificates.crt