CLI 代理、路由與整合

這些指令控制代理政策與路由、檢查即時代理，並將支援的客戶端連接至 opencodex。

代理政策

`ocx agent <status|injection|effort|subagents|fallback|sidecar> ...`

管理無頭多代理名冊、effort 上限、prompt 注入、fallback 與 sidecar 設定。使用 status 查看目前政策。關於介面模式、委派、effort 與 fallback 行為如何搭配運作，請見子代理介面。

ocx agent subagents set ark/model-a,openai/gpt-5.5
ocx agent sidecar web --enabled off

--enabled off 與儀表板中的 關閉 (Off) 列是同一個開關：OpenCodex 不再執行該 sidecar， Codex 整合會把 web_search = "disabled" 寫入 ~/.codex/config.toml，這正是讓 MCP 搜尋伺服器成為唯一搜尋路徑的前提。--enabled on 會再次移除該行。當儲存確實改變開關狀態時，指令會回報由此觸發的 Codex 端寫入（--json 中的 codexWebSearch，否則為結尾的 Codex config: 行），並在無法寫入時提示 ocx sync。該旗標對 vision 同樣有效。

`ocx v2 <status|on|off|mode <v1|default|v2>|threads <n>>`

管理 Codex 的 multi_agent_v2 功能旗標與三態多代理介面模式。

子指令	動作
`status`（預設）	回報目前 v2 旗標、多代理模式與執行緒並行數。
`on`	啟用 `multi_agent_v2` 功能並重新同步目錄。
`off`	停用 `multi_agent_v2` 功能並重新同步目錄。
`mode v1`	將所有模型強制為 v1、停用原生 v2，並保留現用執行緒上限。
`mode default`	遵循上游模型介面 pin。
`mode v2`	將所有模型強制為 v2、啟用原生 v2，並保留現用執行緒上限。
`threads <n>`	將現用 v1/v2 執行緒上限設為不小於 1 的整數。

ocx v2 status
ocx v2 mode v1
ocx v2 mode default
ocx v2 on
ocx v2 threads 16

mode 子指令將 multiAgentMode 寫入 opencodex 設定並重新同步 Codex 目錄。模式與旗標轉換會在有效的 v1/v2 Codex key 之間移動目前的數值執行緒上限；失敗的轉換會還原原始的 config.toml。變更套用於新的 Codex session，執行中的 session 則保留其 pin 的介面。

組合路由

`ocx combo <list|show|set|remove> ...` · `ocx route combo ...`

管理組合 failover 與 round-robin 虛擬模型。ocx route combo 是階層式別名；組合是目前支援的路由資源。目標使用 provider/model[:weight],provider/model[:weight]。

ocx combo list
ocx route combo set reliable --targets ark/model-a:2,openai/gpt-5.5

關於路由行為與設定指引，請見組合。

可觀測性與除錯

`ocx observe <logs|usage|storage|memory|debug|claude-inbound|injection> ...`

檢查代理請求、用量、儲存、記憶體與除錯資料。直接別名如下：

別名	等效資源
`ocx logs [filters] [–follow] [–json	–jsonl]`
`ocx usage [–range <today	1d
`ocx storage [--json]`	`ocx observe storage`
`ocx memory [--json]`	`ocx observe memory`

ocx observe usage --range 30d --json

部分用量記錄無法納入時，人類可讀輸出會顯示警告，即使沒有可讀取的記錄也是如此。顯示的總數僅反映可讀取的記錄。如果篩選條件沒有符合的可讀取記錄，輸出將顯示警告和提示，而不顯示總數列；被略過的記錄可能包含符合項目。--json 原樣保留回應中的 usageIncomplete 診斷及原因。

`ocx debug <provider|usage|injection|claude> <on|off|status|reset|logs [-f]>`

透過執行中代理的管理 API 讀取或變更執行階段除錯覆寫。

ocx debug provider on|off|status|reset
ocx debug provider logs [-f|--follow]
ocx debug usage on|off|status|reset
ocx debug usage logs [-f|--follow]

無 scope 時，ocx debug 印出用量，並在代理停止時印出下次啟動的環境預設值。供應商除錯預設來自 OCX_DEBUG=1（舊版 OCX_DEBUG_FRAMES=1 亦可）；用量除錯預設來自 OPENCODEX_USAGE_DEBUG=1。

API 存取

`ocx access <key|endpoints|models|test> ...`

管理 OpenCodex 許可 API 金鑰並檢查外部端點與模型。ocx api-key <list|create|remove> ... 是 ocx access key 的別名。

ocx access key create deployment

客戶端整合

`ocx integration <claude|grok> ...`

管理支援的 Claude 與 Grok 整合。下方的直接指令家族暴露其客戶端專屬控制。

`ocx claude [claude args...]`

確保代理正在執行，然後以 ANTHROPIC_BASE_URL、 ANTHROPIC_AUTH_TOKEN、CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY=1，以及來自 config.claudeCode 的模型插槽啟動 Claude Code。在 Claude Code 2.1.129 或更新版本中，路由模型會透過穩定的插槽別名出現在原生 /model 選擇器中。在舊版本上，請用 ANTHROPIC_MODEL 或 /model <id> 選擇。使用者匯出的 ANTHROPIC_* 變數恆優先。

Claude Desktop 設定檔指令如下：

ocx claude desktop [apply]                         儲存並套用四家族設定檔
ocx claude desktop show [--json]                   顯示路由、家族與預設值
ocx claude desktop move <route> <family> [--default]
ocx claude desktop default <family> <route|none>
ocx claude desktop export <path|->                 匯出版本化 JSON（`-` = stdout）
ocx claude desktop import <path> [--apply]         驗證並匯入 JSON

家族為 opus、fable、sonnet 與 haiku；新路由從 opus 開始。none 僅在該家族為空時有效。舊版套用旗標 --static、--hybrid 與 --discovery-only 仍受支援。請用 ocx claude config <status|set> ... 管理 Claude Code 設定。

`ocx opencode [opencode args...]`

確保代理正在執行，然後在 OpenCode 的內嵌執行階段層（OPENCODE_CONFIG_CONTENT）中以生成的 provider.opencodex 與 providers.opencodex 區塊啟動 opencode。既有的內嵌設定會被保留，本次啟動僅替換這兩個鍵。全域或專案的 opencode.json 檔案可能被讀取以警告既有的覆寫，但磁碟上的檔案永不修改。路由模型以 opencodex/<provider>/<model> 出現。之後啟動普通 opencode 的行為與之前完全相同。

`ocx grok <status|exclude|include|set|clear|apply> ...`

管理並套用 Grok Build 模型圍欄。

客戶端設定匯出

`ocx export --client <opencode|pi|omp|hermes|openclaw|kimi|gajae|dsh|mcode|zcode|prime|aside|raycast|omo|cline|kilo|droid>`

印出連接到執行中代理的客戶端設定。此指令會用所選客戶端的原生格式，序列化含有 base URL、模型清單，以及適用的環境變數參考或 loopback 佔位符的 opencodex provider 區塊。

代理必須正在執行；指令解析其即時連接埠、讀取 /api/models，並只輸出 Codex 目前可見的模型。

旗標	動作
`--client <opencode\|pi\|omp\|hermes\|openclaw\|kimi\|gajae\|dsh\|mcode\|zcode\|prime\|aside\|raycast\|omo\|cline\|kilo\|droid>`	必填。選擇客戶端設定格式。
`--json`	僅在 stdout 印出設定 JSON，使重導向能擷取逐位元組輸出。所有診斷訊息（含 `--out` 寫入提示）皆送至 stderr。
`--out <path>`	將設定寫入 `<path>`。拒絕覆寫既有檔案。
`--force`	允許 `--out` 覆寫既有檔案。

ocx export --client opencode                     # 設定加上目的地、合併警告與計數
ocx export --client pi --json > pi-models.json   # 供 pipe 或 diff 用的逐位元組 JSON
ocx export --client omp --out ./omp-models.yml    # 原生 OMP YAML
ocx export --client opencode --out ~/opencodex-opencode.json

未指定 --json 時，會先輸出客戶端的原生設定格式，接著是標準目的地路徑、合併警告、客戶端專屬提示，以及附帶有多少列省略 context limit 的模型計數（客戶端會對那些套用自身預設值）。

客戶端	標準目的地	下載檔名	環境變數
`opencode`	`~/.config/opencode/opencode.json`（`XDG_CONFIG_HOME` 設定時優先）	`opencode.json`	`OPENCODEX_OPENCODE_API_KEY`
`pi`	`~/.pi/agent/models.json` (設定後 `PI_CODING_AGENT_DIR` 優先；相對路徑會被拒絕)	`pi-models.json`	無——區塊帶有字面值 `opencodex-loopback`
`omp`	`~/.omp/agent/models.yml`（即使是空值，`OMP_PROFILE` 仍優先於 `PI_PROFILE`）	`omp-models.yaml`	無——loopback 佔位符
`hermes`	`~/.hermes/config.yaml`	`hermes-config.yaml`	`OPENCODEX_HERMES_API_KEY`
`openclaw`	`~/.openclaw/openclaw.json`	`openclaw.json5`	`OPENCODEX_OPENCLAW_API_KEY`
`kimi`	`~/.kimi-code/config.toml`	`kimi-config.toml`	無——loopback 佔位符
`gajae`	`~/.gjc/agent/models.yml`	`gajae-models.yaml`	非機密的回送佔位值
`dsh`	`$DSH_HOME/settings.yaml`（預設 `~/.dsh/settings.yaml`）	`settings.yaml`	無——非秘密的 loopback bearer 佔位符
`mcode`	`~/.minimax/config.yaml` (設定後 `MINIMAX_DATA_DIR` 優先，其次為舊的 `MAVIS_DATA_DIR`；相對路徑會被拒絕)	`mcode-config.yaml`	無——loopback 佔位符
`zcode`	`~/.zcode/v2/config.json` (設定後 `ZCODE_DATA_DIR` 優先；相對路徑會被拒絕)	`config.json`	無——loopback 佔位符
`prime`	`~/.prime/agent/models.json` (設定後 `PRIME_AGENT_CODING_AGENT_DIR` 優先；相對路徑會被拒絕)	`prime-models.json`	無——loopback 佔位符
`aside`	`~/.aside/u/<account>/models.json`，對應 Aside 自己的 `accounts.json` 指定的目前帳戶；資訊清單無法讀取時會被拒絕，而不是退回任一帳戶	`aside-models.json`	無——loopback 佔位符
`raycast`	`~/.config/raycast/ai/providers.yaml`（macOS 與 Windows 相同；Raycast 不遵循 `XDG_CONFIG_HOME`）	`raycast-providers.yaml`	無——僅限 loopback，不會寫入 `api_keys` 項目
`omo`	`~/.omo/agent/models.json`（設定後依序由 `OMO_CODING_AGENT_DIR`、`SENPI_CODING_AGENT_DIR`、`PI_CODING_AGENT_DIR` 優先；相對路徑會被拒絕）	`omo-models.json`	無——loopback 佔位符
`kilo`	`~/.config/kilo` 下最先存在的 `kilo.jsonc`、`kilo.json`、`opencode.jsonc`、`opencode.json` 或 `config.json`（`XDG_CONFIG_HOME` 可變更該目錄）；皆不存在時使用 `kilo.jsonc`	`kilo.jsonc`	`OPENCODEX_KILO_API_KEY`
`droid`	`~/.factory/settings.json` (`%USERPROFILE%\.factory\settings.json` on Windows)	`factory-settings.json`	僅限迴環；不需環境變數

Raycast 匯出是一份獨立的 providers.yaml 文件，在 providers 序列中只有一個 id: opencodex 元素：name: OpenCodex、proxy 的 /v1 base URL，以及每個路由模型及其 abilities（tools 與 system_message 一律支援，vision 依目錄的輸入模態而定，reasoning_effort 在模型有 effort 階梯時設定，temperature 對推理模型關閉）。Custom Providers 是 Raycast Pro 功能，且 Raycast 會監看該檔案，因此儲存後的變更不需重新啟動即可生效。格式說明見 manual.raycast.com/ai/custom-providers。不會寫入任何 api_keys 項目，所以此匯出僅限 loopback，非 loopback 的 bind 會被拒絕。

opencode 會插值 {env:OPENCODEX_OPENCODE_API_KEY}。Pi 與 OMP 的匯出不需要環境變數，而是帶有字面值 opencodex-loopback。DSH 匯出需要 DSH 0.1.0-rc.6 或更新版本，且只擁有 llm-pi-ai.providers.opencodex。DSH 會熱重載該 provider；使用者的預設模型與 deepseek-official 維持不變。這項匯出僅支援 loopback，且不含真實憑證。

金鑰永不被序列化。設定只帶有文件化的環境變數參考，或非秘密的 loopback 佔位符。loopback 代理（127.0.0.1，預設值）完全不需要准入金鑰。只有客戶端 schema 支援、且代理綁定超出 loopback 時，才設定被引用的變數；關於准入金鑰的簽發方式，請見遠端存取。上游 provider 本身的金鑰是完全不同的事，依供應商個別設定。

產生的 gjc 整合使用非機密的本機回環佔位值，不需要環境變數。此整合僅支援本機回環，不設定遠端存取憑證。

相同的 payload 亦由 GET /api/client-config 提供，並在儀表板的 API 分頁渲染，因此 CLI、API 與 GUI 使用相同的位元組。

執行階段與設定

`ocx system <status|settings|startup|diagnostics|sync|codex-app-server|codex-restart|update|codex-cli-update> ...`

管理無頭執行階段設定、啟動、同步、診斷與更新。

ocx system codex-restart --yes 透過與 ocx sync --restart-codex 相同的模組重啟 Codex app-server，並完全結束再重新啟動 Codex 桌面應用程式。若代理本身在 Codex 應用程式內部執行，此命令會給出可執行提示並拒絕，而不是承諾無法完成的移交。

ocx system settings --stream-mode eager-relay

ocx system update 更新 OpenCodex 本身。Codex CLI 使用以下獨立唯讀檢查指令：

ocx system codex-cli-update check --json

check 不會向套件 registry 發出請求，只會在限定範圍內檢查設定中的安裝候選項來源證據，包括經過遮罩的可執行檔位置與所有權證據。正式發布的 launcher 所提供的可信內容只會驗證該候選項快照，並不證明 Codex 已成功執行。由於這個單次命令絕不會執行 Codex，來自環境變數與持久化記錄的候選項只供報告（managed: false，通常為 selection_unattested）；JSON 輸出包含 candidateAvailable、candidateVersion 與 candidateSource，而 selectionAttested 維持 false。檢查設定中的安裝候選項時，必須有正式發布的 launcher 所提供的可信內容；直接使用 Bun 啟動或從原始碼執行時不具備這項證明，因此會忽略來自環境與持久化記錄的候選項狀態，並可能在 POSIX 系統上報告 candidate_unavailable。在 Windows 上，這個首個切片不會對候選路徑或設定路徑執行任何檔案系統 I/O。只有由可信 launcher 擷取的絕對環境候選項可以取得應用程式封裝或版本管理工具的純詞彙標籤；其他所有 Windows 候選項都會以失敗關閉方式處理。由於這個切片完全不會讀取持久化的選擇狀態，在未擷取任何環境候選項的 Windows 執行中會報告 windows_inspection_deferred 而非 candidate_unavailable：該命令無法觀測 Codex CLI 是否已安裝，因此會報告檢查被延後，而不是斷言候選項不存在。此命令不會執行 Codex 或套件管理工具、不會修復 shim、不會寫入設定或快取、不會停止程序，也不會安裝任何內容。隨應用程式封裝的候選項、位於已識別版本管理工具路徑中的候選項、未經驗證的獨立候選項，以及 shim 狀態不明確的候選項，都會報告為 unmanaged 或 unknown，絕不會歸類為 managed。

在 Windows 上，如果擷取到 CODEX_CLI_PATH=codex 這類單純命令名稱、遠端路徑或裝置路徑，則回報 candidate_path_unavailable。這些情況已有擷取的候選項，但其路徑不適用於此檢查。

明確觀測 Windows x64 安裝

ocx system codex-cli-update attest [--json]
ocx system codex-cli-update attest --candidate <absolute-path> --npm-prefix <absolute-path> --npm-cli <absolute-path> --node <absolute-path> [--json]

attest 是選用的唯讀操作，用於觀測所選或明確指定的 Windows x64 npm 安裝。不帶任何選項時，指令會觀測由可信 launcher 快照識別的所選候選項（已設定的 CODEX_CLI_PATH 或所擷取 PATH 中的第一個 codex），其中 opencodex 包裝腳本會解析到其重新命名的 codex.opencodex-real.cmd npm 備份。提供全部四個絕對路徑可覆寫自動識別；自動識別僅提出路徑，持有控制代碼的觀測才是最終依據。--candidate 必須是標準 npm <prefix>/codex.cmd 或 <prefix>/node_modules/@openai/codex/bin/codex.js。--npm-cli 必須以 node_modules/npm/bin/npm-cli.js 結尾，--node 明確指定 node.exe。應用程式封裝、已識別的版本管理工具配置、缺少 npm 備份的 opencodex 自有 shim 與自訂包裝腳本皆會被拒絕。

在有限讀取期間，原生控制代碼保持上層目錄與檔案開啟。未支援的平台、重新剖析點/junction、衝突的寫入者、不安全的路徑及超過大小限制的檔案皆會被拒絕。固定格式報告不含路徑：status 為 observed 或 refused，並提供 installationIdentityObserved；selectionAttested、managed 與 applyAllowed 一律為 false。回報拒絕時也可能回傳結束代碼 0，因此應檢查 status。

識別值或摘要僅描述觀測當下的檔案，不是持續有效的更新許可，也不證明選用的執行階段、過去的安裝程式、實際 npm 設定或工具真實性。明確指定的 Node 也只是被觀測，不能證明啟動器會選用它。命令不會執行目標、請求套件 registry、安裝、寫入設定或控制程序。現有 Windows check 仍不執行候選項或設定的檔案系統 I/O。

`ocx config <show|get|set|unset|validate|export|import> ...`

檢查並安全地修改已驗證的 OpenCodex 設定。show 與 get 會遮罩秘密。匯入在寫入前驗證且需要 --yes。

CLI 代理、路由與整合

代理政策

ocx agent <status|injection|effort|subagents|fallback|sidecar> ...

ocx v2 <status|on|off|mode <v1|default|v2>|threads <n>>

組合路由

ocx combo <list|show|set|remove> ... · ocx route combo ...

可觀測性與除錯

ocx observe <logs|usage|storage|memory|debug|claude-inbound|injection> ...

ocx debug <provider|usage|injection|claude> <on|off|status|reset|logs [-f]>

API 存取

ocx access <key|endpoints|models|test> ...