跳到內容

Web 儀表板

opencodex 內建了一個由代理提供服務的本機 web 儀表板(gui/ 下的 Vite/React 應用)。你可以在 這裡快速管理 provider、Codex/ChatGPT 帳號、目錄模型、sidecar、子代理設定和請求流量。

Terminal window
ocx gui

該命令會在瀏覽器中開啟執行中的代理位址,預設為 http://127.0.0.1:<port>,綁定至 IPv6 回環位址 ::1 時則為 http://[::1]:<port>。這些字面位址保留了本機瀏覽器配對所需的已設定 origin。在啟用管理 ingress 的 hub 上則開啟 http://127.0.0.1:<管理埠>;如果代理尚未執行,會先自動啟動。開發時也可 讓 GUI dev server 單獨連線到正在執行的代理:

Terminal window
ocx start
bun run dev:gui

在預設的 loopback 綁定(localhost / 127.0.0.1)上,儀表板永遠不會要求 token:代理會將短期 GUI session 簽發到服務的頁面中,並在到期或代理重啟時靜默續期。只有綁定到非 loopback 主機名稱的 儀表板才需要 admin token(OPENCODEX_ADMIN_AUTH_TOKEN,或自動產生的 ~/.opencodex/admin-api-token 檔案)。

當遠端儀表板需要該憑證時,它會顯示標準的密碼表單,讓瀏覽器密碼管理員可以提議儲存與自動填入。 儀表板本身仍然只在記憶體中保留 token,不會寫入 localStorage 或 sessionStorage;是否儲存完全 由瀏覽器或密碼管理員決定。

記住此裝置 預設關閉。直接 HTTPS 儀表板(或本機回環)會將管理員權杖交換為伺服器簽發的 HttpOnly、SameSite=Strict 裝置 Cookie,以及另外存入本站 localStorage 的裝置證明。HTTPS 下 Cookie 使用 Secure,且僅限本主機。Cookie 和證明都不是管理員權杖,且都不能單獨使用。同一主機名稱的不同連接埠共用 Cookie;依來源隔離的證明將記住的裝置綁定至本儀表板來源。仍建議使用專用主機名稱。管理員權杖不存入 localStorage 或 sessionStorage。瀏覽器儲存空間無法使用或無法儲存證明時,記住裝置會回報無法使用。對於位於終止 TLS 的反向代理後方的獨立儀表板,OpenCodex 看到的是一般 HTTP 請求,因此會拒絕為該位址記住裝置;登入對話框會說明原因並關閉該選項,不勾選記住裝置仍可正常登入。受信任的 Hub 管理監聽器例外,仍可記住裝置。

私有 dashboard-sessions.json 儲存 Cookie、證明、管理員憑證和瀏覽器識別的雜湊、伺服器來源及固定30天有效期。重新開啟 Safari 主畫面應用程式時,有效裝置記錄可恢復短期工作階段。記住的工作階段無法核准需要同意的操作:GitHub 星號、重設額度消耗、提示詞層編輯、Meta Muse 登入、桌面相容性變更或配額驗證。這些操作請使用新的本機工作階段或已配對工作階段。中繼、跨來源和遠端明文 HTTP 不支援記住裝置。過期、瀏覽器識別變更,或更換管理員權杖並重新啟動伺服器後需重新登入。

側欄或行動操作中的 忘記此裝置 以及登出成功後,會立即撤銷記錄及所有衍生工作階段,並刪除瀏覽器證明。登出失敗時保留證明以便重試。伺服器會在發布變更前將記錄內容同步至磁碟;當機後目錄項目的持久性採盡力保證。舊權杖儲存鍵會直接刪除,不讀取或移轉。僅在可信裝置啟用;不會恢復 Safari 密碼自動填入。

除啟動安全頁面外,每個頁面頂端的一行摘要會顯示各供應商目前的配額用量,例如 OpenAI 31% | Claude 54% | xAI 12% | Google 8%。它讀取與供應商工作區相同的配額報告 (GET /api/provider-quotas,分頁可見時每 60 秒一次),且絕不會強制重新整理上游。

  • 每個項目顯示優先選用的已回報視窗:依序為每週、30 天、5 小時,然後是供應商自訂視窗或 預付額度。
  • 當預付額度已使用 90% 以上且優先的一般視窗尚未達到危急程度時,摘要會顯示預付額度;若該視窗也已達危急程度,則仍顯示該視窗。
  • 用量達 70% 時轉為琥珀色,達 90% 時轉為紅色。
  • 將游標移到項目上或以鍵盤聚焦項目,可查看所有已回報的視窗及其重設時間和讀取時間。在觸控 螢幕上,第一次輕觸即可顯示。
  • 點擊項目(觸控螢幕上為第二次輕觸)會在供應商頁面開啟該供應商的帳號分頁,在那裡管理其帳號或 API 金鑰。
  • 摘要列一律只佔一行。項目放不下時,可橫向捲動,或使用兩端的 « 和 » 按鈕。
  • 未回報任何配額視窗的供應商不會顯示。所有供應商都未回報時,整條列會隱藏。
  • 右端顯示儀表板上次讀取報告的時間。當最近一次讀取失敗且仍在顯示上一次讀數時,它 會轉為琥珀色。
區域 作用
Dashboard 摘要 顯示 multi-agent 模式、線上狀態、版本、運行時間、provider 數量、30 天 token 總量、活動 provider 和可用的原生/路由模型。
Sub-agent delegation 為 v1 委派 prompt 選擇原生或路由模型,並可指定 reasoning 強度。它不是逐次生成的路由器,詳見下文。
Sidecar 選擇 web-search 模型及強度,以及圖像描述模型;更改從下一次請求開始生效。
Maintenance 重新同步 Codex 模型目錄,檢視專案級設定繞過警告,檢查 latest/preview 版本,並可在更新後重啟代理。 在桌面 shell 中,該更新入口會開啟原生應用程式更新頁面,而不是執行套件更新器。
啟動安全 顯示注入的 Codex 路由能否在重啟後繼續工作,並分別顯示服務、launcher shim 狀態和準確的修復命令。
Windows 托盤 安裝使用者登入托盤,一鍵控制代理啟動、停止、重啟、面板和狀態。托盤不是代理重啟服務。
Codex 自動啟動 允許已安裝的 Codex launcher shim 執行 ocx ensure。此開關不會安裝 shim 或後臺服務。
遙測 在 Proxy details(#proxy-telemetry)下切換共享匿名使用統計並檢視預覽 JSON。首次執行或更新後的同意彈窗僅在點擊繼續時儲存選擇(PUT /api/telemetry),關閉彈窗不會記錄任何內容。請參閱遙測與隱私。
Providers 新增、編輯、啟用/停用、刪除 provider,並在支援時管理 OAuth 帳號池和 API key 池。額度重新整理會略過暫停的 OAuth 帳號與停用的 API key;這些被略過的列即使沒有快取讀值,仍會顯示不可用,但不影響重新整理結果。當未暫停的 OAuth 帳號或已啟用且支援額度讀取的 API key 讀值不可用時,重新整理會回報失敗。
Add provider 分頁上方的單一搜尋框可同時搜尋帳號、免費、本機、付費四個分頁。搜尋時選取的分頁不會跳轉,結果依分頁分組並顯示數量。本機執行環境(Ollama、vLLM、LM Studio、LiteLLM)有專屬分頁,過長的說明會截斷為兩行,點擊即可查看全文。
Codex Auth 新增 ChatGPT/Codex 池帳號,選擇下一 session 的帳號,重新整理 5h / 每週 / 30d 配額,啟用或停用配額自動切換,設定其 1–100% 閾值和臨時故障 failover。
Subagents 在 spawn_agent override 列表中置頂最多五個原生或路由模型。
Models 開關原生 GPT 與路由模型,設定 provider allowlist、上下文上限、v1/base/v2 以及 v2 thread 數量。頁面會區分已儲存至中樞端、此用戶端已取得,以及已在執行中的用戶端生效這三種狀態。取得時間無法證明內容包含中樞端最新儲存,執行階段生效狀態會明確顯示為尚未驗證。
Logs 自動重新整理近期請求,顯示 token、請求強度、實際模型、provider、狀態、request id、耗時和錯誤詳情。
Usage / Debug 檢視 token usage 覆蓋率與趨勢,或啟用可選的 provider transport 和 usage 提取診斷。
Stop 優雅地停止代理和已安裝的後臺服務,恢復原生 Codex 並退出(POST /api/stop)。在使用工作排程器後端的 Windows 上,儀表板會拒絕並提示改用 ocx stop:工作結束後包裝程序仍可能重新啟動 Proxy,只有執行在 Proxy 之外的 stop 才能在還原用戶端設定前確認這個重啟視窗。被拒絕時不會做任何變更。

用量、儀表板、供應商工作區、供應商目錄和 API 金鑰頁面會提示部分記錄被排除,即使沒有可讀取的記錄。次數、日期和使用排名僅反映可讀取的記錄。歷史不完整時,無法儲存模型的最常用排序;請選擇其他排序或修復歷史後重試。

Usage 預設在目前存取範圍內選擇所有應用程式、所有裝置和30 天。頁面開啟期間可縮小應用程式、裝置或時間範圍;重新開啟時恢復預設值。

選擇所有應用程式時,Models 和 Providers 後會顯示應用程式明細,列出所選裝置與時間範圍內各應用程式占總 token 的比例、token 數、依 API 標價估算的費用、請求數及已測量用量的請求數。Codex CLI、桌面版和 IDE 合併為 Codex。沒有用戶端歸屬資訊的歷史記錄顯示為未分類,與未知和其他區分。選擇單一應用程式會隱藏此明細。代理未提供明細時顯示無法使用;空明細表示報告中沒有應用程式用量。

請求詳細資訊會優先顯示已記錄的上游失敗原因,而不是通用的代理錯誤文案。有效的上游實際傳送次數一律顯示;缺少或無效的記帳資訊則顯示 Unavailable,而非 0。只有在記錄到一次已完全結算且一致的嘗試時,Retries 才顯示首次傳送後的額外傳送次數。多次嘗試、未解決或不一致的記帳資訊,以及有損失的 attempt 正規化,都不會憑空產生重試次數。未知的持久化原因會回退為依狀態顯示的標題。Upstream reason 顯示經過分類的供應商狀態(例如速率受限、配額或額度用盡、超出上下文視窗、所在地區不受支援、需要驗證帳戶、模型無法使用),Failure detail 顯示由代理撰寫的文字,例如停滯逾時或位元組上限;新記錄不會儲存供應商本身的錯誤文字。較舊的 usage.jsonl 檔案中可能仍有此類文字,但儀表板讀取時會將其捨棄。

Logs 將所有應用程式的請求放在一起,並為每個請求顯示僅含圖示的用戶端標記,取代應用程式分頁。已識別的用戶端使用其 SVG 標誌,未知或其他用戶端使用中性的問號圖示。應用程式名稱不以可見文字顯示,但仍可供螢幕閱讀器讀取。缺少用戶端歸屬資訊不表示 Codex 或請求失敗。標記用於識別用戶端應用程式,與供應商和通訊協定無關,也不是應用程式篩選器。

Logs 可組合被攔截請求、供應商、完整模型名稱、狀態、時間、速度和對話 ID,篩選目前已載入的日誌。選項包含回退嘗試;模型比對忽略大小寫及頭尾空白,但不做部分比對。日誌中消失的選項恢復為全部。

時間範圍為最近 15 分鐘、1 小時或 1 天;Logs 分頁每 30 秒更新一次,即使關閉自動重新整理也會更新。速度按完整請求耗時計算每秒輸出 token,分為小於 15、15 至小於 50、至少 50;啟用速度篩選時排除無測量值的請求。成功為 2xx,錯誤為 4xx/5xx。

顯示符合數與已載入總數;重設恢復全部列,並區分無符合結果與空日誌。不查詢已載入範圍以外的歷史記錄。

佈局只有一種,無需切換。Dashboard 的各個部分都有自己的地址:#dashboard 開啟 Overview,#dashboard/providers 與 #dashboard/models 開啟另外兩個。重新整理、收藏和後退都會保留目前所在的部分。Logs 同理,使用 #logs 與 #logs/debug。舊的 #providers/workspace 書籤現在會跳轉到 #providers。

Logs 和 Usage 中的費用是根據已報告 token 計算的 API 標價折算值,不是帳單,也不能證明 實際發生了扣費;實際可能計入訂閱用量或消耗服務商額度。

Models 開關表示 Codex 中的最終可見狀態。路由模型只有在 provider allowlist 中(或未設定 allowlist)且未被停用時才會開啟。開啟模型會原子地協調兩個過濾條件;全部開啟 會清除 allowlist,因此以後新發現的模型也會開啟。

在供應商的模型分頁中,刪除會移除已儲存的自訂定義。原有的原生模型或即時探索到的模型可能 重新顯示,因此模型數量可能維持不變。隱藏只改變目錄可見性,不會刪除定義,也不會改變直接路由規則。 點選在模型中管理可見性可開啟模型頁面並恢復顯示;即使供應商分頁已沒有任何模型列,也能使用此入口。

新增會儲存自訂定義,但不會清除既有的隱藏狀態或供應商選擇規則。儲存後的模型可能仍被隱藏。 如果模型已存在,請在模型頁面管理其可見性。已確認儲存時,即使目錄重新整理失敗,定義也已儲存; 請依重新整理提示操作,不要重複新增。若無法確認變更結果,請先重新整理模型狀態,再重試。

供應商的模型數量統計伺服器回傳的目前模型清單中未停用的唯一項目,計數在搜尋與顯示數量限制之前進行。 它不是允許清單的大小或即時探索的模型數量,也不能證明項目來自上游探索。選擇標記與探索資訊和此計數分開顯示。

Dashboard 的 Sub-agent delegation 選擇器會儲存 injectionModel,以及可選的 injectionEffort。在 v1 turn 中,opencodex 會注入一段指引,告訴父代理呼叫 spawn_agent 時應 傳入哪個精確模型和 reasoning 強度。只要選定模型,無論父代理目前使用何種 reasoning 強度,都會 啟用這段指引;清除模型時也會清除已儲存的強度。

儀表板管理平面與 client→hub 模型流量彼此獨立。連線 → API 金鑰 顯示待處理輪替,只顯示一次替代金鑰,並要求明確提交或中止。瀏覽器 logout 只會使目前工作階段失效。連線時從 hub 依 apiKeyId 篩選用量;中斷後使用本機記錄,兩者不會鏡像。

查看已儲存金鑰的完整值,需要透過明確配對或受信任的 Tailscale 身分驗證簽發的儀表板工作階段。 自動簽發的本機工作階段仍可查看遮罩清單,但無法顯示已儲存的金鑰值;管理員權杖也無法呼叫 這項僅限工作階段的操作。請使用既有的 Remote Hub 配對流程,或在可用時透過受信任的 Tailscale 身分登入。

本機配對表單僅提供於透過 HTTP、以明確的 IP 位址 127.0.0.1 或 [::1] 開啟的同源獨立儀表板。 來源必須與伺服器設定的回環 IP 綁定位址一致。如果透過 localhost 或其別名開啟,請先檢查伺服器綁定: 綁定為 127.0.0.1 時重新開啟 http://127.0.0.1:<port>,綁定為 ::1 時重新開啟 http://[::1]:<port>,然後配對。hostname 設為 localhost 的伺服器沒有符合條件的本機配對來源。 儀表板無法從別名 URL 判斷實際綁定,因此只顯示一般拒絕說明,不建議替代 URL。

配對後請再次點選金鑰以要求其值;配對本身不會顯示金鑰。共用工作階段遭清除或取代、開始配對、 離開面板、隱藏瀏覽器分頁或桌面視窗、切換伺服器時,已顯示的值與複製狀態都會清除。 新建或替代金鑰的一次性值也會清除。已授權的工作階段到期或遭撤銷後,請重新配對。

選擇器會列出已啟用的原生與路由模型,以及全域 Codex reasoning 階梯。API 會先驗證所選強度是否 屬於全域階梯;Codex 仍會根據目標目錄條目再次校驗該 spawn 強度。

Codex Auth 頁面用於管理原生 ChatGPT/Codex 路由:

  • 手動選擇帳號會立即生效:已經繫結帳號的 thread 會在下一次請求時切換到所選帳號, 只有進行中的請求會保留已取得的帳號。手動選擇會固定該帳號,卡片上會顯示已固定徽章。 再次點選徽章會要求確認解除固定。確認後會清除選擇,已繫結的 thread 保留其帳號, 新建或未繫結的請求則恢復依選擇順序與閾值自動選擇帳號。 如果確認視窗開啟期間固定帳戶發生變化,該確認不會解除新的固定。操作遭拒或結果不確定後,帳戶檢視會重新整理;再次確認前請檢查目前選擇。
  • Thread affinity 可避免每個請求都來回切換帳號。預設開啟 pool.cacheAffinity 後,長時間執行的 thread 不會只因 usage 達到閾值就重新繫結;只有帳號耗盡或無法繼續服務時才會離開,並且只重新繫結到 確有額度餘裕且使用率確實更低的帳號。關閉該設定後,才會在存在使用率確實更低且確有額度餘裕的 可用帳號時依閾值重新繫結。
  • 新 session 可以選擇 usage 最低的可用帳號。付費計劃按已知 5h、每週、30d 視窗中的最高使用率 評分;Go/Free 計劃只使用 30d 視窗。
  • Refresh quotas 會立即重新讀取帳號 usage,使路由邏輯與頁面上的帳號卡片使用同一份資料。
  • 池帳號的請求日誌使用 p3fa91c 這類不透明標籤,不會記錄帳號郵箱。

側邊欄的星標按鈕——以及 ocx start 在互動式終端機中詢問的一次性問題——都透過 你自己的 gh 登入 執行。opencodex 不持有任何 GitHub token,它唯一得知的是你的 yes 或 no。

由於這會寫入你的 GitHub 帳號,agent 驅動的呼叫者會被拒絕,而不是被允許替你回答:

  • ocx start 與 ocx service install 在 agent 或 CI harness 驅動時 完全略過該提示 (CLAUDECODE、CODEX_THREAD_ID、CURSOR_TRACE_ID、CI 等)。一次性 marker 保持未寫入, 因此真正的提示仍會在你下次手動輸入時出現。agent 會被要求改為詢問你——而且是以你必須回答的 簡單 Yes/No 選擇,而不是它可以繞過的軟性旁白。如果你一直沒有回答,agent 會被要求再次詢問, 而不是把你的沉默當成 no。
  • 當代理在 agent session 下執行且請求沒有 dashboard browser session 時,POST /api/github/star 會以 code: "agent_consent_required" 回覆 403。持有 admin token 不是同意:你機器上的 agent 可以讀取該檔案。
  • Dashboard 按鈕保持正常運作。真實點擊帶有 same-origin session 證據,因此即使代理啟動了 proxy,也會被辨識為你本人。
  • 說 no 就結束。不會持久化任何東西,也不會在任何模型 prompt 中加入任何東西來日後引導你。

GUI 是代理 JSON 管理 API 之上的輕量用戶端。常用 endpoint 包括:

Endpoint 用途
GET / PUT /api/settings 讀取設定或切換 Codex 自動啟動。
GET /api/startup-health 讀取不含秘密資訊的路由、服務、shim 和重啟安全診斷。
GET / POST /api/windows-tray 讀取或更改 Windows 托盤安裝和顯示狀態;POST 支援 install、start、stop、uninstall。
POST /api/sync 重建共享模型目錄,並把 Codex 模型快取標記為過期。
GET /api/update/check · POST /api/update/run · GET /api/update/status 檢查、執行和監控自更新任務。
GET / PUT /api/sidecar-settings 讀取或設定 search/vision sidecar 模型。
GET / PUT /api/injection-model 讀取或設定 v1 委派指引模型及可選強度。
GET / PUT /api/v2 讀取或設定介面模式、Codex feature flag 和 v2 thread 上限。
GET /api/providers · POST /api/providers · PATCH /api/providers?name=... · DELETE /api/providers?name=... 列出、新增/替換、啟用/停用或刪除 provider。
GET /api/models · PUT /api/disabled-models 列出原生/路由模型,並更新共享的 disabled-model 集合。
GET /api/selected-models · PUT /api/model-visibility 讀取 provider allowlist,並原子地更改單個模型或 provider 分組的最終可見狀態。
GET /api/key-providers · GET /api/oauth/providers 讀取 API key 和 OAuth provider 目錄。
POST /api/oauth/login · GET /api/oauth/status 啟動 provider OAuth 流程並輪詢完成狀態。
GET /api/codex-auth/accounts?refresh=1 列出主帳號與池帳號、強制重新整理配額,並回傳主帳號的 hasCredential / terminal needsReauth 狀態。
PUT /api/codex-auth/active · PUT /api/codex-auth/auto-switch · PUT /api/codex-auth/failover 選擇下一次請求使用的帳號並設定帳號池路由。
POST /api/codex-auth/login · GET /api/codex-auth/login-status 透過瀏覽器登入新增池帳號。
GET /api/logs?tail=50&provider=...&status=5xx 使用 tail、provider、精確狀態碼或狀態類別篩選近期請求後設資料。
GET / PUT /api/subagent-models 讀取或設定五個置頂的 spawn_agent override 模型。
POST /api/stop 停止代理/服務,恢復原生 Codex 並退出。在 Windows 工作排程器後端會以 respawnable_service 拒絕,無法讀取該狀態時以 service_state_unknown 拒絕;兩種情況都不會做任何變更。