CLI 參考

opencodex 的命令列工具是 ocx。它依第一個命令名稱分派，有記載的別名如 setup/init、restore/eject、models/model 都會到達相同操作。 未知命令與無效的命令形狀都是錯誤。

執行 ocx help（或 ocx --help / ocx -h）檢視頂層用法。對幫助表中註冊的命令， 執行 ocx help <command>、ocx <command> --help 或 ocx <command> -h。幫助與版本 命令均為只讀：它們不會啟動、停止、安裝、解除安裝或改寫 Codex／opencodex 狀態。

命令家族

• 生命週期 — 設定、代理與服務生命週期、健康狀態、 診斷、目錄同步、儀表板與更新。
• Providers、帳號與模型 — provider 設定、 認證、憑證池、配額、自訂模型、可見性、選定模型與 context 上限。
• Agents、路由與整合 — multi-agent 控制、combos、 可觀測性、admission key、用戶端整合、執行環境設定、已驗證的設定，以及唯讀的 Codex CLI 更新檢查。

無頭（headless）行為

管理命令往返於執行中代理的管理 API，使用記錄的執行環境埠與身分檢查，而非維護第二條 設定路徑。停止或無法連線的代理以 HTTP 503 呈現，並產生非零的 CLI 離開碼。明確記載為 離線設定操作的命令，可以在沒有執行中代理的情況下驗證與編輯設定檔。

check 不查詢註冊表，也不執行 Codex。在 POSIX 上，當已發布啟動器擷取的環境候選項與執行階段解析器選擇的正規路徑相同時，selectionAttested 可以為 true；若關聯的 npm-global 套件資訊清單證明了所有權，且在回報候選版本時該版本與資訊清單版本一致，managed 可以為 true。持久化候選項仍不獲認證。Windows x64 也支援經證明繫結的絕對路徑標準 npm codex.cmd，以及由持有控制代碼繫結的 Node/npm 工具鏈（存在時為前綴本機，確認不存在時為錨定到啟動器架構的已擷取 PATH 配對）和已驗證的前綴內平台支援元件，並使用拒絕重新剖析的持有控制代碼。其他 Windows 配置仍然延後或不受管理。Windows 的 managed 結果僅對觀測到的安裝配置進行分類：繫結的 Node/npm 是更新器的唯讀中繼資料工具鏈，並不保證後續 codex.cmd 呼叫將解析到哪個直譯器。直接透過 Bun 或原始碼執行時沒有啟動器證明。plan 使用隔離的暫存 npm 設定、快取和日誌查詢官方註冊表，並拒絕活動工作階段或不完整的程序觀測。它不安裝軟體，也不向程序傳送訊號。Windows x64 的 apply 需要具備經過驗證的私人寫入權限的受限 npm 前綴，並保留無關的套件和 shim；不受支援的已觀測配置回傳 applicable: false 且 refusal: windows_apply_disabled；僅 PATH 選取、OpenCodex 自動啟動包裝器和 global/vendor 後援仍然延後。請參閱完整命令與拒絕原因（英文）。

觀測 Windows x64 安裝的方式請參閱 attest 命令。未提供明確路徑時，該命令會觀測由受證明約束的啟動器快照識別出的已選候選項；它不授予更新權限，也不證明執行階段選擇。

沒有歧義時，list 或 status 是預設。使用 --json 取得結構化快照，並以 ocx observe logs --follow --jsonl 取得串流的請求 log feed。佈景主題、語言、導覽與 其他純視覺的瀏覽器狀態沒有 CLI 對應；Cloudflare Tunnel 設定不在此命令集內。

存活探測上限覆寫

ocx health、ocx status、ocx account *、ocx login codex 與 ocx ready 透過短時存活探測尋找執行中的代理：預設每次 750 ms，停止與啟動判斷使用含重試的 1500 ms。若安全層（內容過濾器或 EDR 類網路擴充）替每個回送連線增加固定延遲，健康的代理可能來不及回應就已逾時。

在這類主機上可設定 OCX_PROBE_TIMEOUT_MS 提高上限，例如 OCX_PROBE_TIMEOUT_MS=5000 ocx status。值為 1 到 30000 的整數毫秒。覆寫只會提高上限：750 ms 預設值與 1500 ms 停止／啟動預算保留下限，因此 1000 只會延長預設探測。未設定、空值、小數、負數、0 或更大的值都會被忽略。

離開碼與確認

成功的命令離開 0。無效用法、未知命令或資源、失敗的 API 操作以及無法使用的必要服務 會以非零離開。ocx health 特別只在代理健康時離開 0，找不到健康的代理時離開 1，參數無效時離開 2，因此可作為服務探針。 腳本應測試離開碼，而不是解析人類可讀的輸出。

宣告需要確認的破壞性移除、匯入、信用消耗與更新操作，在非互動使用時需要 --yes。 該旗標是明確的 opt-in；省略它不得靜默確認該動作。

版本與內部分派目標

ocx --version、ocx -v 與 ocx version 會列印一行適合腳本使用的版本行並結束。

有兩個分派目標刻意不顯示在一般幫助中：__refresh-version [preview] 在分離的 程序中重新整理更新通知快取，__gui-update-worker <job-id> [latest|preview] [restart] 執行儀表板更新任務。它們是實作細節，不是穩定的使用者面向命令。儀表板會記錄 worker PID、恢復 worker 已死但仍在進行中的任務、把超過十分鐘且沒有 PID 的舊 active 記錄 視為過期，並保護執行中的 worker 免受並行更新影響。