快速入門
本指南帶你從全新安裝到在現有程式開發工具中送出第一個請求。步驟 1 和 2 適用所有工具;步驟 3 依工具分成簡短分支。用戶端支援頁面列出各工具及連接方式。
1. 執行設定嚮導
Section titled “1. 執行設定嚮導”ocx initocx init 會引導你完成:
- 選擇 provider —— 從內建 registry 的 107 個預設中選擇一個,或選擇
custom手動輸入 base URL 和 adapter。 - API key —— 貼上一個 key,或引用一個環境變數,例如
${ANTHROPIC_API_KEY}。 - 預設模型 —— 對於 API key、本機和 custom provider,可接受預設值或輸入模型 id。
- 代理埠 —— 預設為
10100。 - 注入到 Codex? —— 在通常的迴環地址設定中,opencodex 會在
$CODEX_HOME/config.toml(預設~/.codex/config.toml)根級新增openai_base_url,讓 Codex 內建的openaiprovider 指向代理。監聽遠端或 LAN 地址時,則改用帶 API 認證 header 的專用 provider 條目。 - 安裝自動啟動 shim? —— 啟用後,每次啟動
codex都會先執行ocx ensure。
結果會儲存到 $OPENCODEX_HOME/config.json(預設 ~/.opencodex/config.json)。
2. 啟動代理
Section titled “2. 啟動代理”ocx start # 預設埠 10100ocx start --port 8080啟動時,opencodex 會:
- 將其 PID 寫入
~/.opencodex/ocx.pid(並拒絕重複啟動), - 在 provider 支援時發現即時模型,並把原生與已路由條目同步進 Codex 的模型目錄,以及
- 在
http://localhost:<port>/v1上監聽。
如果請求的埠已被佔用,ocx start 會停止並告訴你是什麼佔用了該埠:如果回應的是
opencodex,請先執行 ocx stop;也可以使用 ocx start --port <port> 在空閒埠上啟動。
它不會自行切換到其他埠;舊行為會讓兩個代理同時執行,並將 Codex 重新指向後啟動的代理。
檢查它:
ocx statusocx gui # 在實際監聽埠開啟儀表板3. 連接你的工具
Section titled “3. 連接你的工具”選擇你使用的工具對應的分支。你可以連接多個工具,它們共用供應商與模型。
如果你在步驟 1 接受了 Codex 提示,Codex 現在會透明地透過 opencodex 通訊。如果你拒絕了該提示,或設定因已有設定檔而結束,請在執行 Codex 之前開啟儀表板 Connect 頁面的 Codex 開關;Codex 整合說明修改內容與還原方式。
codex "Refactor this function for readability"若要指定某個已路由的模型,請使用 Codex 模型選擇器所顯示的 provider/model 形式:
codex -m "anthropic/claude-opus-5" "Explain this stack trace"codex -m "ollama-cloud/glm-5.2" "Write a SQL migration"Claude Code
Section titled “Claude Code”安裝 claude CLI 後:
ocx claudeocx claude 會在代理未執行時啟動它,並以指向 opencodex 的環境啟動 Claude Code。額外參數會原樣傳遞。層級預設值、其他啟動器和停用方式請參閱 Claude Code。
Claude Desktop
Section titled “Claude Desktop”ocx claude desktop全新安裝時會為整個應用程式設定閘道設定檔;已經使用 first-party 模式的安裝會保持原模式,可執行 ocx claude desktop apply --gateway 明確切換。first-party 模式讓 Desktop 繼續使用 claude.ai,只路由其 Code 分頁;詳見 Claude Code 的 Claude Desktop 模式一節。
切換模式後,請完全結束並重新開啟 Claude Desktop。
Grok Build
Section titled “Grok Build”在本機監聽時,若 ~/.grok 存在,ocx start 會將可見模型註冊至 ~/.grok/config.toml。在 Grok Build 選擇 ocx-* 模型。遠端設定和受管理區塊請參閱 Grok Build。
新增供應商或模型後,執行 ocx ensure 或重新啟動代理,Grok Build 才能看到它們。
具備受管理整合的工具(OpenCode、Pi、Qoder、WorkBuddy、Kilo、Cline、T3 Code 等)可從儀表板的 Connect 頁面連接,或使用:
ocx integration client enable --client <id>各工具的設定檔及生效時間請參閱整合。其他接受自訂端點的工具可使用 OpenAI 相容基本 URL http://localhost:10100/v1 或 Anthropic 基本 URL http://localhost:10100。
選擇 sub-agent 模型(可選)
Section titled “選擇 sub-agent 模型(可選)”新設定會讓 Codex 的 sub-agent 選擇器包含五個原生模型:gpt-5.5、gpt-5.6-sol、
gpt-5.6-terra、gpt-5.6-luna 和 gpt-6-astra。開啟 ocx gui 即可替換或重新排序最多五個
原生或已路由模型。儀表板也可以設定一個首選 sub-agent 模型及 reasoning effort。參見
子代理介面 選擇 v1/base/v2,並了解指引、原生預設與回退
何時生效。
登入而非貼上 key
Section titled “登入而非貼上 key”部分 provider 支援真正的帳號登入(OAuth,自動重新整理):
ocx login xai # 也可使用 anthropic、kimi、kiro、google-antigravity、cursorocx logout xaiOpenAI 本身無需 key —— 預設 provider 會直接轉發你現有的 codex login 憑證
(參見 Providers)。
ocx stop # 停止代理並恢復原生 Codexocx restore # 不停止代理,僅恢復原生 Codex(別名:ocx eject)ocx restore back # 讓 Codex 再次使用仍在執行的代理