API Hop

文件目錄

API Hop 文件

Codex 整合

在 Codex CLI、VS Code 擴充功能或桌面應用程式中使用 RequestBeam 的 OpenAI Responses 相容端點。

Codex 透過 OpenAI Responses 協定呼叫模型。請使用本頁顯示的 OpenAI 相容基礎網址設定模型供應商。

text
Codex base_url: https://api.apihop.ai/openai

先決條件

請先準備有效的 RequestBeam API 金鑰。金鑰會寫入本機 Codex 設定目錄，切勿將其提交至程式碼儲存庫、日誌或螢幕截圖。

Codex 通常將設定檔存放於：

  • macOS / Linux: ~/.codex/
  • Windows: %userprofile%\.codex\

如果目錄或設定檔不存在，請先建立：

bash
mkdir -p ~/.codex
touch ~/.codex/config.toml

Windows CMD 請使用：

bat
mkdir %userprofile%\.codex
type nul > %userprofile%\.codex\config.toml

備份設定

若之前使用過 Codex，請先備份目前設定：

bash
cp ~/.codex/config.toml ~/.codex/config.toml.bak
cp ~/.codex/auth.json ~/.codex/auth.json.bak

更新 config.toml

開啟 ~/.codex/config.toml，新增或更新以下設定：

toml
model_provider = "requestbeam"
model = "gpt-5.4"
review_model = "gpt-5.4"
model_reasoning_effort = "high"
disable_response_storage = true
network_access = "enabled"

[model_providers.requestbeam]
name = "RequestBeam"
base_url = "https://api.apihop.ai/openai"
wire_api = "responses"
requires_openai_auth = true
supports_websockets = true
websocket_connect_timeout_ms = 15000

[features]
responses_websockets = true

base_url 的規則是：本頁顯示的公開 API 基礎網址 + /openai。

若您的 config.toml 已包含 [marketplaces.*]、[plugins.*] 或其他工具設定，請保留它們，只新增或更新上述 Codex 模型供應商設定。

WebSocket 模式

啟用 supports_websockets = true 與 responses_websockets = true 時，Codex 會使用下列 Responses WebSocket 端點：

text
https://api.apihop.ai/openai/responses

若 API 基礎網址使用 https://，Codex 會使用對應的 wss:// 連線。

此 WebSocket 模式是專供 Codex 使用的 Responses-over-WebSocket 橋接：

  • 支援 response.create
  • 支援 response.cancel
  • 回傳 response.completed
  • 同時保留 response.processed 相容事件

response.cancelled 僅確認本機取消請求，不代表上游已退款。上游結果不明的請求會繼續保留預留款，直到其用量或失敗狀態獲得確認。

這不是 OpenAI Realtime API，不支援 session.update、conversation.item.*、input_audio_buffer.*、音訊串流、二進位訊息或 Realtime 訊息封裝。

若網路代理、企業閘道或舊版 Codex 無法建立 WebSocket 連線，請暫時改用：

toml
[model_providers.requestbeam]
supports_websockets = false

[features]
responses_websockets = false

Codex 接著會退回 HTTP POST https://api.apihop.ai/openai/responses。Compact 是獨立能力：目前列出的五個 GPT 模型沒有經過驗證的 Compact 通道。切換 HTTP/WebSocket 模式不會啟用壓縮。請在超過模型上下文上限之前開啟新對話，不要依賴這些路由自動壓縮長上下文。

寫入 API 金鑰

將 YOUR_REQUESTBEAM_API_KEY 替換為您的 RequestBeam API 金鑰：

bash
echo '{"OPENAI_API_KEY":"YOUR_REQUESTBEAM_API_KEY"}' > ~/.codex/auth.json

Windows CMD 請使用：

bat
echo {"OPENAI_API_KEY":"YOUR_REQUESTBEAM_API_KEY"} > %userprofile%\.codex\auth.json

重新啟動與測試

儲存設定，完全結束 Codex，然後重新開啟。

可使用以下指令測試 CLI：

bash
codex "Reply in one sentence whether the current model is available."

使用 VS Code 擴充功能或桌面應用程式時，請完全結束應用程式並重新開啟，再開始一般對話。

疑難排解

  • base_url 必須是本頁顯示的公開 API 基礎網址加上 /openai。
  • wire_api 必須為 responses，請勿改為 chat。
  • Compact 不可用錯誤代表沒有經驗證的 Compact 通道，變更本機 token 門檻無法啟用它。
  • RequestBeam 同時支援 HTTP Responses 與 Codex Responses WebSocket。預設請保留 supports_websockets = true 與 responses_websockets = true。若 Codex 版本或網路代理無法使用 WebSocket，請暫時設定 supports_websockets = false，退回 HTTP。
  • auth.json 必須是有效 JSON，金鑰名稱必須為 OPENAI_API_KEY。
  • 若收到 401 或 invalid key，請確認 API 金鑰有效，且未被舊的本機金鑰覆寫。
  • 若模型不可用，請檢查 GET https://api.apihop.ai/v1/models，並將 model 與 review_model 設為可見的 GPT 模型。預設範例使用 gpt-5.4；目前未啟用 gpt-5.3-codex 與 gpt-5.6-luna。
  • 變更設定後請完全結束並重新開啟 Codex。只關閉視窗可能不會重新載入 auth.json。
  • POST https://api.apihop.ai/openai/responses：建議使用的 RequestBeam Responses 相容端點。
  • POST https://api.apihop.ai/openai/responses/compact：需要明確啟用的 Compact 通道，否則會在預留款前回傳 503。支援的通道會回傳 response.compaction。
  • WS /openai/responses：Responses WebSocket 相容端點。支援 response.create、response.cancel，回傳 response.completed，並保留 response.processed 相容事件。
  • WS /openai/responses/compact：使用相同的 Compact 能力檢查與端點。僅完成 WebSocket 交握不代表模型支援。