跳到內容

CLI 生命週期

這些指令安裝、執行、檢查、修復並更新本機 opencodex 代理及其 Codex 整合。

互動式設定精靈(setup 是 init 的別名)。提示選擇供應商(預設或自訂)、API 金鑰(字面值或 ${ENV})、預設模型與代理連接埠;儲存 ~/.opencodex/config.json;可選擇將代理注入 $CODEX_HOME/config.toml(預設 ~/.codex/config.toml);並可選擇安裝 Codex 自動啟動 shim。

ocx start [--port <port>] [--socks5 [host:port] | --socks5-off]

Section titled “ocx start [--port <port>] [--socks5 [host:port] | --socks5-off]”

啟動代理伺服器(偏好連接埠 10100)。它寫入 PID/runtime-port 狀態,並拒絕啟動第二個即時實例。偏好連接埠被佔用時,start 會探測佔用者,且無論結果如何都會停止:若回應的是 opencodex,它會直接拒絕啟動;否則會回報無法識別的佔用者。它絕不會自行將監聽位置移到其他連接埠,因為這會讓第一個代理繼續執行,並將 Codex 重新指向第二個代理。即使明確指定不同的 --port,共用同一個 OPENCODEX_HOME 時仍會拒絕啟動,因為僅觀察模式和啟用上限的模式都會寫入同一份支出日誌。獨立的同層實例必須使用不同的 OPENCODEX_HOME;port: 0 只讓作業系統指派連接埠,不會隔離狀態。啟動時它將每個供應商的模型同步到 Codex 目錄。關閉時它還原原生 Codex——除非它是作為受管服務啟動的(OCX_SERVICE=1)。在已執行的代理旁啟動的同層實例兩者皆不做,即使透過 ocx stop 或訊號停止也一樣:它只在自己的連接埠上處理直接請求,Codex、Grok 和 Claude 仍指向原本已在執行的代理。 從另一個 OPENCODEX_HOME 啟動時,會依預設主目錄的執行階段記錄及受管理的 Grok、Codex 本機迴環位址檢查存活的擁有者。沒有存活擁有者的單獨自訂主目錄仍正常同步;明確執行的 ocx sync 和 ocx grok apply 也維持可用。

--socks5(預設 127.0.0.1:10808)會將 SOCKS5 URL 儲存到 config.proxy,並透過真正的 SOCKS5 通道轉送對外 HTTP(S) 請求。--socks5-off 只會清除已儲存的 SOCKS5 代理,不會刪除 HTTP 代理。此值儲存在設定中,因此會在 ocx update 後保留。URL 可以包含使用者名稱和密碼,但啟動記錄會隱藏它們。

Terminal window
ocx start
ocx start --port 8080
ocx start --port 10100 --socks5
ocx start --socks5-off

無人監督的 Link Child 處理結束訊號時,會在每次寫入前核對連線,並在關閉接聽器前還原 Codex 原生設定及受管理的 Grok。服務/Desktop、sibling、重新啟動交接和父程序 stop 收據會保留設定。結束中的重新啟動要求回傳 409 runtime_stopping。強制終止可能略過訊號處理,仍需父程序 ocx stop 的還原路徑。

停止執行中的代理(依 PID)、移除 PID 檔案,並還原原生 Codex。若已安裝受管背景服務,ocx stop 也會先停止它,使其無法重新生成代理。網頁儀表板側欄的代理拉桿拉到底時,在多數後端執行相同動作(POST /api/stop),但 Windows 工作排程器除外:工作結束後包裝程序仍可能重新啟動 Proxy,因此儀表板會以 respawnable_service 拒絕、不做任何變更,並請你改用 ocx stop。

對已連線的 hub 用戶端,ocx stop(包括成功的 API 停止)會保留連線擁有的 Codex 路由、目錄和 Grok 設定,ocx start 會再次提供服務。明確停止 Remote Link Child 時,若共用設定還原成功,則會還原原生 Codex 路由、目錄與已備份的續接歷程中繼資料,並移除受管理的 Grok 設定。已儲存的 Home 連線會保留,可用 ocx disconnect 移除。

要在還原後再次從 Codex 使用 Home,請先執行 ocx start(已安裝服務時使用 ocx service start),再執行 ocx sync --restart-codex。僅啟動不會重新套用路由;sync 不會重新建立 Grok 設定區塊。若在停止服務前無法確認連線擁有權,停止 API 會回傳 HTTP 409 與 sharedTeardown: "refused",並讓 Proxy 與服務管理員繼續執行。請等待進行中的連線或中斷連線作業完成後再試。

一般情況下,代理正在執行時,指令會向身分已驗證的特定 PID 與連接埠請求原地重新啟動,等待正常排空,並確認同一連接埠上出現不同的執行階段 PID。此路徑會保留受管路由與服務監督;若請求結果不確定,不會將其重試為獨立的停止與啟動。只有代理未執行時,才會回退至一般的 ensure 啟動。

若目前 CLI 比已驗證的獨立 POSIX 代理新,且符合嚴格的擁有權與監督條件,受保護的更新路徑會停止舊代理,確認其已停止後才從目前的安裝啟動新代理;此路徑不同於上述原地重新啟動。若資格或停止狀態無法確認,指令會回報失敗。條件與其他情況請參閱重新啟動參考資料(英文)。

如果更新後的重新啟動回報執行階段紀錄中的主機名稱為空白,這次嘗試不會停止代理。請參閱狀態與復原指引(英文),先確認擁有權與實際綁定位址;若確認不完整,請洽擁有者或管理員。

冪等地確保背景代理正在執行,然後同步其即時模型目錄。若 codexAutoStart 為 false,它會印出自動啟動已停用並不做事。

在不停止代理的情況下還原原生 Codex——剝除注入的設定行與路由目錄項目,使普通 codex 再次以原生方式運作。eject 是 restore 的別名。

還原後的目錄會排除已退役的原生模型,包括 gpt-5.3-codex-spark 的裸 ID 與可信的帳號限定項目。 無論是否有目錄備份,此規則皆適用;原始備份與使用者儲存的歷史模型選擇設定保持不變。

對任一拼法傳入 back 可在不變更代理生命週期的情況下,將普通 codex 重新指向已在執行的代理:

Terminal window
ocx restore back
ocx eject back

針對在可逆備份支援存在前、重新對應 Codex App 歷史的舊開發組建進行明確復原。若其歷史資料庫被鎖定,請先關閉 Codex。

這是範圍很廣且具破壞性的重新標記:所有含有使用者訊息且目前標記為 opencodex 的 thread 都會改標為 openai,exec 會正規化為 cli,並設定 event marker。正常的專用 provider 歷史也包含在內。請先備份狀態,而且只有在確實需要這個完整範圍時才執行。

ocx recover-history --ocx-compaction <thread-id> --yes

Section titled “ocx recover-history --ocx-compaction <thread-id> --yes”

在透過原生 Codex 恢復曾由路由提供方壓縮的工作前,修復該工作的歷史記錄。此命令依 UUID 精確選取一個工作,先儲存私有的逐位元組備份,然後只把 OpenCodeX 自有的 ocx1:/ocx2: 壓縮狀態轉換成原生 Codex 可重播的普通摘要。原生加密內容與其他工作不會變更。執行前請關閉所選工作;若 rollout 在處理期間發生變化,復原會停止且不會取代原始檔案。

停止服務與代理、移除服務與 Codex shim、還原原生 Codex,然後僅在所有還原步驟成功時移除 opencodex 本機設定。remove 是 uninstall 的別名。設定清理需要由全新安裝建立的擁有權中繼資料;舊版或共享目錄會被原樣保留。

當 ocx uninstall 以 root 身分或在已提升(系統管理員)權限的 Windows 提示字元中執行時,會先確認其他帳號無法變更設定目錄、其上層目錄以及其中的任何目錄,並確認設定目錄內沒有指向其外部的連結(在 Windows 上則是完全沒有連結)。只要有一項不符合,解除安裝就會在做出任何變更之前停止並說明原因。請以擁有設定目錄的帳號、不使用 sudo 或系統管理員權限執行 ocx uninstall,或將這些目錄限制為僅該帳號可寫入並移除此類連結,然後再次執行。在無法判斷提示字元是否已提升權限的 Windows ARM64 上也會進行相同檢查;若檢查無法完成,請先停止 opencodex,再手動移除設定目錄。

若某個已記錄項目在設定目錄內的上層目錄是連結(符號連結或連接點),該項目會保留原樣並列為剩餘路徑,本次執行以部分解除安裝結束。將該連結換成實際目錄或將其移除後,再次執行 ocx uninstall 即可完成。

印出唯讀診斷摘要:代理 PID、/healthz 可達性、儀表板 URL、設定路徑、預設供應商、Codex 自動啟動設定、服務狀態、shim 狀態與遮罩後的有效 Codex home。只有明確、高信心的 Windows Orca runtime-home 簽章會加上可採取行動的 App-home 不符警告;它永不自動變更 CODEX_HOME。

人類可讀輸出還在 OAuth 登入摘要後包含一個 OAuth 健康 區塊:當每個已知帳號都健康時為 OAuth health: ok,或在有任一非健康帳號時為 OAuth health: warning,每個非健康帳號一行遮罩資料(供應商、遮罩帳號 id、狀態如需要重新認證、速率或配額限制,或 refresh 衝突),加上可選的 Action: 提示。帳號 id 會被遮罩;token 與電子郵件永不印出。--json 契約目前不包含此健康區塊。

Terminal window
ocx status
ocx status --json

縮寫範例結構:

{
"schemaVersion": 1,
"proxy": {
"running": false,
"pid": null,
"health": {
"ok": false,
"url": "http://127.0.0.1:10100/healthz",
"message": "unreachable"
}
},
"dashboard": {
"url": "http://localhost:10100/"
},
"paths": {
"config": "/Users/example/.opencodex/config.json",
"pid": "/Users/example/.opencodex/ocx.pid",
"runtime": "/path/to/bun"
},
"runtime": {
"source": "bundled"
},
"codexHome": {
"effectiveCodexHome": "C:\\Users\\[USER]\\.codex",
"appCodexHome": "C:\\Users\\[USER]\\.codex",
"mismatch": false,
"warning": null,
"action": null
},
"codexAutostart": true,
"defaultProvider": "openai",
"service": {
"summary": "not installed (logs: /Users/example/.opencodex/service.log)"
},
"codexShim": {
"summary": "Codex autostart shim: not installed"
}
}

實際物件還包含 listen(連接埠、主機名稱、runtime/config 來源)、設定載入診斷,以及 bundled Codex plugin 診斷。JSON schema 為附加式:未來版本可能新增欄位,但既有欄位應保持穩定。它刻意排除 API 金鑰、OAuth token、授權標頭、請求內容、電子郵件與帳號身分。

即時讀取會等待有時間上限的服務探測完成:診斷快取為空或已過期時,macOS/Linux 最多等待 6.5 秒,Windows 最多等待 16.5 秒。從快取讀取的結果會迅速回傳。逾時仍會退回本機診斷;僅憑 /healthz 健康,無法確認重新啟動保護已生效。

對即時代理進行身分檢查。人類可讀輸出回報 PID/連接埠;--json 輸出 {ok, pid, port}。此指令僅在健康時離開 0,否則離開 1,使其適合服務探測。

ocx ready [--json] [--wait [--timeout <seconds>]]

Section titled “ocx ready [--json] [--wait [--timeout <seconds>]]”

透過免認證的 GET /readyz 端點檢查同步後的就緒狀態。就緒時回傳 200,或 pending 與終端 failed 時回傳附帶 Retry-After: 1 的 503。其淨化的 HTTP 身分為 {service, version, uptime, pid, port, status, protocol, minimumClientProtocol, managementUrl, features}。protocol 是 Hub 目前的遠端協定版本,minimumClientProtocol 是相容的最低用戶端協定版本,managementUrl 是瀏覽器可見的標準管理 origin。沒有 /readyz 的舊代理會以 unreachable 方式 fail closed;/healthz 是分開的存活檢查,而非就緒檢查。此指令預設執行一次探測;--wait 輪詢直到就緒或逾時,但在觀察到終端 failed 狀態時立即退出。預設逾時為 45 秒;--timeout <seconds> 需要 --wait,接受 1–300 的正整數秒。CLI JSON 輸出 {ready, status, pid, port},其中 status 為 ready、pending、failed 或 unreachable。離開碼為:就緒 0;未就緒、pending、failed、逾時或 unreachable 1;無效引數 64。

執行唯讀環境與連線診斷:狀態路徑與檔案系統類型、WSL 雙重安裝、代理環境/設定、ChatGPT 可達性、Codex plugin 與專案設定警告,以及待處理的歷史遷移。Codex app-home 定向區段也會偵測窄義的 Windows Orca runtime-home 不符,並在適用時說明服務遷移。此診斷顯示的路徑會遮罩 OS 使用者名稱。Doctor 印出修復提示但不套用它們。

OAuth 可靠度 區段回報憑證儲存是否可寫、是否可在 OPENCODEX_HOME 下建立 refresh single-flight/lock 檔案、非健康的 OAuth 或 Codex pool 帳號(遮罩 id)及其恢復 Action:,以及一個關於 Codex forward path 不偽造官方客戶端中繼資料的靜態 OK。Doctor 永不變更憑證或套用修復。

Section titled “ocx sync [--expect-link <linkId> | --expect-hub-key <apiKeyId>] [--local-only] [--json] [--restart-codex] [--restart-app-server-only] ”

在 Remote Link Home 上成功提交最新目錄後,ocx sync 也會向符合條件的已連結 Child 同步。--local-only 可停用這個傳播。--json 會輸出單一 ocx.sync.fanout/1 文件,包含 Home 的結果與各 Child 的狀態;遭略過的 Child 也會顯示原因。Home 自身的非零結束碼會原樣回傳。Home 成功時,若傳播時略過已連結的 Child,或 Child 失敗、逾時或連結儲存區無法讀取,指令以結束碼 6 結束。用戶端發起的連結和 --local-only 等刻意略過的情況保留原有行為;遭略過的已連結 Child 會附帶操作建議 hint。文字模式下,連結儲存區無法讀取的錯誤不包含路徑。結束碼 7 保留給進行中的更新。JSON 模式下若 Home 同步擲出例外,stdout 仍只包含一份結果文件,stderr 則輸出經安全轉義的診斷訊息。

傳播不會要求重新啟動 Child 上的 Codex 應用程式或 app-server。若需要重新啟動,請使用 GOAT,在完整 ocx Child 執行 ocx sync --restart-codex,或在輕量級 ocx-child 主機上單獨重新啟動 Codex 桌面應用程式與 app-server 程序。不過,Child 的固定目標同步在套用變更後的 Home 設定時,仍可能重新啟動它自己的 OpenCodex 用戶端執行階段。Home 逾時並停止本機 SSH 程序後,已開始的遠端同步仍可能在 Child 上繼續。

Remote Link Child: 在完整 ocx Child 上,ocx sync 也會套用 Home 的 Codex 設定並在用戶端執行階段早於該次套用啟動時重新啟動它;重新啟動失敗時原有執行階段會繼續提供服務並以非零狀態結束。在輕量級 ocx-child 主機上,ocx-child sync 會在中繼未執行時啟動 ocx-child serve,在 runtimeStartedAt < lastApplyAt 時輪替程序,並在非 stale 同步時盡力回報 parity(若輪替失敗,舊中繼已停止且指令以非零狀態結束;Codex 桌面應用程式與長期執行的 app-server 程序如需重新載入請單獨重新啟動)。Child 上的 ocx status --json(或 ocx-child status --json)與 Home 上的 ocx link status --json 相關欄位請見 Remote Link apply parity(英文)。

明確指定重新啟動旗標後,即使目錄和快取的位元組未變,成功提交 config.toml 變更也會觸發重新啟動。僅處理設定的操作若沒有變更、遭拒、只做預先檢查或寫入已回復,則不會觸發重新啟動。未指定重新啟動旗標時,sync 不會自動重新啟動 Codex。

從每個已設定的供應商擷取即時模型清單,並將合併後的目錄重新注入 Codex。在新增供應商後或要重新整理可用模型時執行它。

若長壽的 Codex app-server 仍在執行,ocx sync 會警告它們可能繼續提供先前的記憶體內模型清單,即使 opencodex-catalog.json / models_cache.json 已更新。傳入 --restart-codex 會重啟相符的 codex … app-server 與 codex-code-mode-host 進程,並在 macOS、Linux 與 Windows 上完全結束再重新啟動 Codex 桌面應用程式,讓模型選擇器重新讀取目錄。進行中的對話會結束。刻意避免廣泛的 pkill -f codex 比對。

--restart-desktop-app 是 --restart-codex 的已棄用別名。它仍然可用、會印出棄用提示,且不再僅限 Windows。

--restart-app-server-only 恢復先前的窄範圍行為:僅對目前使用者擁有的相符 app-server / code-mode-host 進程發送 SIGTERM,桌面應用程式保持執行(執行中的回合仍可能被中斷)。若與 --restart-codex 或 --restart-desktop-app 一起使用,窄範圍優先,因為失去進行中的對話無法復原,過期的選擇器可以。

當命令在 Codex 應用程式內部執行時,重啟會交給分離的 helper,此工作階段會隨應用程式一起結束。

指定來源的同步。 ocx sync --expect-link <linkId>(Remote Link Child)與 ocx sync --expect-hub-key <apiKeyId>(hub 用戶端)只有在本機仍連線到該連結或使用該金鑰時才會同步。否則不會變更任何內容,也不會同步本機供應商,指令以結束碼 5 結束,stderr 最後一行為 {"phase":"child_link_mismatch"|"hub_client_mismatch","reason":...}。格式錯誤或重複的旗標以結束碼 2 結束。詳情請見英文參考。

ocx sync-cache [--restart-codex] [--restart-app-server-only]

Section titled “ocx sync-cache [--restart-codex] [--restart-app-server-only]”

使 Codex 的本機模型選擇器快取失效,使其從現用的 opencodex 目錄重建。與 ocx sync 相同的過時 app-server 警告與可選重啟旗標適用。

ocx catalog pull <https-url> [--auth-env <NAME>] [--json] [--restart-codex] [--restart-app-server-only]

Section titled “ocx catalog pull <https-url> [--auth-env <NAME>] [--json] [--restart-codex] [--restart-app-server-only]”

安裝由另一個 OpenCodex 執行個體的 /v1/catalog 端點提供的完整目錄,接著同步 models_cache.json。URL 必須是 HTTPS;僅回送位址允許 HTTP。URL 內嵌憑證、查詢、片段、重新導向、超出大小的回應以及無效目錄,都會在任何本機寫入之前遭拒。驗證為選用,且只透過環境變數名稱(--auth-env)讀取,不接受 argv 傳入。

如果 HTTP_PROXY 或 http_proxy 生效,且 NO_PROXY 或 no_proxy 中沒有相符的略過規則,回送 HTTP 要求會在加入驗證標頭或送出要求之前遭拒。ALL_PROXY/all_proxy 以及僅設定 HTTPS_PROXY/https_proxy 的情況不會觸發此 HTTP 限制;仍允許透過 HTTPS 取得目錄。拒絕訊息不會包含代理位址或驗證權杖。 非空的 http_proxy 和 no_proxy 分別優先於 HTTP_PROXY 和 NO_PROXY。若要設定與 Bun 相容的代理略過規則,請使用主機名稱、相符的 host:port、[::1] 等含方括號的 IPv6 位址或 *,不要使用 URL、路徑或 *. 前綴。

目錄與快取在共用的 Codex 目錄鎖之下寫入;失敗時保留 last-known-good 檔案。位元組完全相同時是保留 mtime 的無操作。--restart-codex、--restart-app-server-only 以及已棄用別名 --restart-desktop-app 僅在實際寫入之後生效,含義與 ocx sync / ocx sync-cache 相同。ETag 條件式請求不屬於此命令。完整的 --json 信封與結束碼請參見英文參考。

ocx service [install|repair|restart|start|stop|status|uninstall|remove]

Section titled “ocx service [install|repair|restart|start|stop|status|uninstall|remove]”

將 opencodex 作為登入管理的背景服務執行(macOS launchd、Linux systemd user unit、Windows Task Scheduler),在登入時自動啟動並在崩潰時自動重啟。服務執行時設定 OCX_SERVICE=1,使重啟不會折騰 Codex 設定。

Windows 工作排程器安裝使用一般處理程序優先順序(Priority=4)。舊的背景優先順序(7,省略時排程器也預設使用 7) 可能在 CPU 競爭時延遲健康檢查回應,導致處理程序仍在執行時系統匣顯示 Offline。升級後執行 ocx service repair, 即可遷移該註冊優先順序並重新啟動服務;過程中可能需要核准 UAC 提示。已設為一般或高優先順序時,不會僅因優先順序而重新註冊。

在 Linux 上,systemd unit 會呼叫安裝時於 PATH 中找到的第一個一般可執行 ocx 檔案,而非已安裝套件樹內的 Bun 與 CLI 路徑。mise、asdf 等版本管理器會安裝到帶版本的目錄,並在升級時刪除舊目錄;其穩定的 shim 讓 unit 持續可解析。沒有 ocx 啟動器的原始碼 checkout 保留直接的 Bun + CLI 形式。Bun 啟動前選定的可信 OPENCODEX_BUN_PATH 會透過 shim 保留;套件內附的 Bun 路徑會在升級後重新被發現。

在 macOS 上,launchd 改為使用安裝或修復時選定的套件內 Bun 與 CLI 路徑。這可防止可變的 PATH shim 在後續重啟時取得服務 API 權杖與已設定的代理環境。升級由版本管理器管理的安裝後,請在重新啟動服務前執行 ocx service repair 以更新這些路徑。

在此變更之前安裝的定義仍帶有舊的帶版本路徑,且無法自行遷移——一旦舊執行檔被刪除,就不會有 opencodex 程式碼執行來修復它。升級後請執行一次 ocx service repair。之後 Linux 服務啟動會跟隨啟動器;macOS 的 repair 會將新的套件路徑寫入 launchd 定義。外部升級不會取代已在執行的代理:當已安裝的 CLI 比執行中的代理更新時,執行 ocx service restart 讓新組建提供服務。在 macOS 上,此情況下 repair 並不足夠:定義沒有改變,而不改變任何內容的 repair 不會重新載入任何內容。反之若代理較新,請依 ocx status 的說明檢查 CLI 安裝與 PATH。

子指令 動作
無 服務不存在時安裝並啟動;已存在時執行 repair。正常的 Windows 工作排程器定義會沿用;過時的定義可能會重新註冊並需要提高權限。
install 建立並啟動服務。註冊它,在 Windows 上需要提高權限。
repair 就地重新整理已安裝的服務。在 macOS 上,僅在有變更時才重新載入 launchd,因此正常且未變更的工作會繼續執行,repair 不會造成中斷。在 Linux 和 Windows 上會重啟服務;正常的 Windows 工作排程器定義會沿用,過時的定義可能會重新註冊並需要提高權限。
restart 執行相同的重新整理,並在所有平台上保證重啟。在 macOS 上,未變更且已載入的工作會就地 kickstart。不是 repair 的別名。
start 啟動已安裝的服務。
stop 停止服務並還原原生 Codex。
status 回報服務與代理診斷及日誌路徑。
uninstall 移除服務並還原原生 Codex。
remove uninstall 的別名。
Terminal window
ocx service
ocx service install
ocx service repair
ocx service restart
ocx service status
ocx service uninstall

在 Windows 上,bare ocx service 只有在 Task Scheduler 和 WinSW 兩者的缺失都得到證實後才會走安裝路徑。如果任一狀態查詢結果不確定,它會拒絕任何註冊並提示執行 ocx service status;只有在確認缺失之後才使用明確的 ocx service install。

install、start 與 repair 會確認代理實際在已安裝服務內建的連接埠上回應,之後才回報成功——在三種平台上皆如此。它們等待最多 20 秒,然後印出伺服連接埠:

✅ opencodex service installed and serving on port 10100.

若沒有回應,它們會發出警告並以非零離開:

⚠️ Service installed, but no proxy answered on port 10100 within 20s.
The manager registered the job; that is not the same as serving.
Log: ~/.opencodex/service.log
Meanwhile: ocx start (serves in the foreground)

在 Windows 上,ocx service status 將 Task Scheduler 註冊與身分驗證過的 OpenCodex 代理可達性分開回報。它不印出本地化的 schtasks 表格,使摘要在各 Windows code page 中保持可讀。

在 Windows 上,建立 Task Scheduler 項目需要提高權限。可識別的本地化存取拒絕文字保持既有的指引路徑。若該文字不可讀,後備方案需要擁有的指令形式 /create /tn opencodex-proxy /xml <non-empty-path> /f、狀態 1,以及確認的非提高 token;儀表板的 Startup Safety 動作隨後可自動請求 UAC。若該後備無法判斷 token 狀態,則保留原始排程器錯誤。外部工作與操作永不發出自動提高標記。請核准儀表板 UAC 提示,或在提高的 PowerShell 視窗中重新執行 ocx service install。

如果啟動時回報 another process owns the runtime mutation lease,或 ocx service status 顯示 Runtime mutation lease busy,表示即使代理沒有在執行,這個租約也正在阻擋啟動或服務變更。訊息中包含鎖定路徑、記錄的 PID、該 PID 目前是否存活、可取得時的執行檔名稱,以及租約已持有的時間。程序身分未經驗證:PID 可能已被重複使用,因此存活狀態與執行檔名稱描述的是目前占用該 PID 的程序。請等待作業結束後再試;不要只憑這個 PID 刪除鎖定或停止程序。當租約時間超過 30 秒且記錄的 PID 已不再存活時,之後的變更作業可以回收這個過期租約;ocx service status 只會檢查它,不會回收。

ocx codex-shim <install|status|uninstall|remove>

Section titled “ocx codex-shim <install|status|uninstall|remove>”

在 macOS 與 Linux 上,ocx codex-shim install 會在解析後的 OpenCodex 主目錄安裝私有 wrapper <OPENCODEX_HOME>/bin/codex 與可由 shell 載入的 <OPENCODEX_HOME>/codex-shell-env.sh。原生啟動器保留在 brew、npm 或 fnm 安裝的位置,套件管理器升級及版本回復不需重新包裝。Windows 仍依原方式就地包裝指令碼啟動器,真實的 codex.exe 保持不動。若 Windows 安裝只提供 codex.exe,請使用 ocx service install。

完成 brew/fnm 等 PATH 設定後,執行安裝時顯示的啟用指令。預設主目錄對應:

Terminal window
. "$HOME/.opencodex/codex-shell-env.sh"

自訂主目錄請使用顯示的含引號路徑。重複載入會移除私有 bin 的重複項目,並將其放在 PATH 最前面。要在之後的 shell 啟用,請自行把這一行加在啟動檔的 PATH 設定之後;OpenCodex 從不編輯 shell 啟動檔,安裝指令也無法變更父 shell 的 PATH。只要 wrapper 可以執行,即使目前 shell 尚未啟用,安裝仍算成功;遭拒或無法執行則失敗。ocx status、ocx codex-shim status、ocx doctor 與 ocx connect 會將未被 PATH 選取的 wrapper 回報為 not active,並提供啟用指令。connect 警告不會改變結束狀態。別名、函式、桌面或服務的啟動環境需要另外設定。

舊的 Unix 就地 shim 只會透過明確執行 ocx codex-shim install 移轉。移轉會還原記錄的原生啟動器,但不覆寫已存在的較新啟動器,之後才安裝私有 wrapper。若還原後私有安裝失敗,原生啟動器會維持已還原狀態,操作可以重試。記錄的啟動器遺失或無法執行時,請透過套件管理器修復;OpenCodex 不會猜測其他安裝位置,也不會重新包裝套件管理器路徑。

Unix 自動修復只更新私有 wrapper,絕不重寫套件管理器啟動器,也不移轉舊的就地 shim。Windows 上,完成的外部更新覆寫 shim 後,下一個普通 ocx 指令會備份穩定的新啟動器並還原 shim。仍在變動的啟動器保持不動,稍後重試。ocx status、ocx doctor、ocx codex-shim status、ocx system codex-cli-update check 與其保留命名空間中的無效呼叫都不觸發這項修復。修復失敗只發出警告,不改變請求指令的結束狀態;手動修復:ocx codex-shim install。將 codexShimAutoRestore 設為 false,或為行程設定 OPENCODEX_CODEX_SHIM_AUTO_RESTORE=0,即可關閉自動修復。

子指令 動作
install 安裝 shim(若過時則修復)。
uninstall 移除 Unix 私有檔案,保留原生 Codex;Windows 上還原原始啟動器。
remove uninstall 的別名。
status 回報 shim 狀態及私有 wrapper 是否在 PATH 中啟用。
Terminal window
ocx codex-shim install
ocx codex-shim status
ocx codex-shim uninstall

Unix 解除安裝後,請從 shell 啟動檔移除載入行,並重新啟動 shell 或從 PATH 移除私有 bin。只移除屬於 OpenCodex 的 wrapper、shell 環境檔與狀態,套件管理器啟動器保持不動。舊的 Unix 就地 shim 會利用已記錄的還原資訊解除包裝。

ocx tray <install|start|stop|status|uninstall|remove> [--json] [--no-start]

Section titled “ocx tray <install|start|stop|status|uninstall|remove> [--json] [--no-start]”

安裝並控制 Windows 狀態列圖示。它在 Windows 登入時啟動並提供一鍵代理控制。start 與 stop 僅控制圖示;請用其選單控制代理。--no-start 適用於 install,並在不立即啟動它的情況下安裝 tray。 已淘汰:OpenCodex 桌面應用程式在 Windows、macOS 與 Linux 提供系統匣;沒有桌面應用程式的安裝仍可使用 ocx tray。 得知有較新的套件版本時,系統匣會在連線、警告或離線圖示上加上藍點,並顯示 Update available。系統匣約每分鐘檢查一次本機快取的徽章;結果過期或無法取得時會移除藍點。此選單項目會開啟儀表板,你可以在那裡開始套件更新。它不會自動安裝。

在 http://127.0.0.1:<port> 開啟網頁儀表板,若代理未執行則自動啟動它。在啟用管理 ingress 的 hub 上,開啟的是 http://127.0.0.1:<管理埠>。

ocx update 更新的是 OpenCodex 本身,而不是 Codex CLI。請使用 system 檢查指令中的 ocx system codex-cli-update check,對已設定的 Codex CLI 候選項進行有界、唯讀的 provenance 檢查。此命令不會查詢 package registry,也不會安裝更新。

當 OpenCodex 由 mise 安裝時,此命令會在停止代理或修改套件檔案之前以失敗狀態結束,並使用經過驗證的本機 mise 別名顯示 mise upgrade <tool>。更新檢查仍可使用,並會回報該安裝由外部管理。無法讀取或不一致的 mise 擁有權中繼資料也會阻止修改,且不會猜測工具名稱;--tag preview 絕不會變更 mise 中設定的選擇。

在 Linux 上,若背景服務記錄的啟動器是 mise 的套件啟動器(<tool>/latest/node_modules/.bin/ocx,而非 mise shim),服務會自動跟隨 mise upgrade:新版本穩定後約十秒內,它會排空進行中的請求並在新版本上重新啟動;若 mise 之後清除了它正在執行的版本,也會以相同方式復原。在 macOS 上、透過 mise shim 安裝的服務以及前景代理,請在升級後自行重新啟動(macOS 上先執行 ocx service repair)。

從 npm 自我更新 opencodex。穩定安裝使用 @latest;預覽安裝停留在 @preview,除非你傳入 --tag latest|preview。它偵測原始碼 checkout 並告訴你改用 git pull && bun install,且若你已是該 tag 的最新版本則為 no-op。執行中的代理會在檔案被替換前停止;已安裝的服務會自動重建並啟動,而前景安裝會印出 ocx start 作為下一步。

Terminal window
ocx update
ocx update --tag preview

當 Release workflow 將新版本發布到 npm 時,新版本即可使用。

使用 ocx connect <url> --pairing-code-stdin、ocx connect status、ocx sync 與 ocx connect rotate --pairing-code-stdin。ocx disconnect 可離線還原本機狀態,但不會撤銷 hub 金鑰。仍連線時,ocx connect revoke --admin-token-stdin 會撤銷已保存的 apiKeyId;中斷後請使用 hub 的 連線 → API 金鑰。秘密值只能透過 stdin 傳遞,不能放入 argv。