@koreanhole/opencodex 2.95.2 → 2.95.3

package/readme/README.zh-TW.md

@@ -0,0 +1,484 @@
+<p align="center">
+  <img src="../assets/banner.png" alt="opencodex — 連接 Codex、Claude Code、Claude Desktop、Grok Build 等工具的本機閘道" width="100%">
+</p>
+
+<h3 align="center">一個本機閘道，連接你的 AI 程式開發工具與模型。</h3>
+<p align="center"><b>在 Codex、Claude Code、Claude Desktop 和 Grok Build 中使用你選擇的模型，<br>並透過受管理的設定連接 OpenCode、Pi、Qoder、WorkBuddy、Kilo、Cline、T3 Code 等工具。</b><br>
+<a href="https://opencodex.me/zh-tw/reference/client-support/">查看所有支援的工具 →</a></p>
+
+<p align="center">
+  <a href="https://x.com/claudeebum"><img src="https://img.shields.io/badge/%40claudeebum-000000?logo=x&logoColor=white" alt="在 X 上關注 @claudeebum"></a>
+  <a href="https://www.npmjs.com/package/@koreanhole/opencodex"><img src="https://img.shields.io/npm/v/@koreanhole/opencodex?color=cb3837&label=npm&logo=npm" alt="npm 版本"></a>
+  <a href="https://github.com/koreanhole/opencodex-cli/blob/main/LICENSE"><img src="https://img.shields.io/npm/l/@koreanhole/opencodex?color=blue" alt="授權"></a>
+  <img src="https://img.shields.io/node/v/@koreanhole/opencodex?logo=node.js&label=node" alt="Node 版本">
+</p>
+
+```bash
+npm install -g @koreanhole/opencodex
+ocx start
+```
+
+<p align="center">
+  <a href="https://github.com/lidge-jun/opencodex/releases/latest"><img src="https://img.shields.io/badge/macOS-.dmg-24292f?logo=apple&logoColor=white" alt="下載 macOS 版 (.dmg)"></a>
+  <a href="https://github.com/lidge-jun/opencodex/releases/latest"><img src="https://img.shields.io/badge/Windows-.msi-24292f?logo=data:image/svg%2bxml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZpZXdCb3g9IjAgMCAyNCAyNCIgZmlsbD0id2hpdGUiPjxwYXRoIGQ9Ik0zIDNoOC41djguNUgzem05LjUgMEgyMXY4LjVoLTguNXpNMyAxMi41aDguNVYyMUgzem05LjUgMEgyMVYyMWgtOC41eiIvPjwvc3ZnPg==" alt="下載 Windows 版 (.msi)"></a>
+  <a href="https://github.com/lidge-jun/opencodex/releases/latest"><img src="https://img.shields.io/badge/Linux-.AppImage-24292f?logo=linux&logoColor=white" alt="下載 Linux 版 (.AppImage)"></a>
+  <a href="https://github.com/lidge-jun/opencodex/releases/latest"><img src="https://img.shields.io/badge/Linux-.deb-24292f?logo=debian&logoColor=white" alt="下載 Linux 版 (.deb)"></a>
+</p>
+
+<table>
+<tr>
+<td width="50%" valign="middle">
+
+### Claude Code，執行任意模型
+
+選擇器還是 Claude Code 原本的，換掉的只是背後的大腦。
+
+</td>
+<td width="50%">
+  <img src="../assets/claude-code-models.gif" alt="透過 opencodex 執行路由模型的 Claude Code——狀態列顯示 gpt-5.6-luna-medium 為目前模型" width="100%">
+</td>
+</tr>
+<tr>
+<td width="50%" valign="middle">
+
+### Codex，執行任意模型
+
+選好供應商就能開始——同樣的工作流程，換顆大腦。
+
+</td>
+<td width="50%">
+  <img src="../assets/demo.gif" alt="opencodex 示範——在 Codex 應用中用路由的非 OpenAI 模型執行任務" width="100%">
+</td>
+</tr>
+<tr>
+<td width="50%" valign="middle">
+
+### Claude Desktop，執行任意模型
+
+Opus 先回答，再把任務交給 GPT-5.6 Sol 子代理。
+
+</td>
+<td width="50%">
+  <img src="../assets/claude-desktop-subagent.gif" alt="Claude Desktop 以 Claude Opus 4.8 回答，再透過 opencodex 派發 GPT-5.6 Sol 子代理" width="100%">
+</td>
+</tr>
+<tr>
+<td width="50%" valign="middle">
+
+### Grok Build，執行任意模型
+
+Sol 主導會話，並呼叫 Kimi K3 子代理。
+
+</td>
+<td width="50%">
+  <img src="../assets/grok-build-subagent.gif" alt="Grok Build 透過 opencodex 執行 GPT-5.6 Sol，並呼叫 Kimi K3 子代理" width="100%">
+</td>
+</tr>
+</table>
+
+<p align="center">
+  <a href="../README.md">English</a> · <a href="README.fr.md">Français</a> · <a href="README.ko.md">한국어</a> · <a href="README.zh-CN.md">简体中文</a> · <b>繁體中文</b> · <a href="README.ru.md">Русский</a> · <a href="README.ja.md">日本語</a> · <a href="README.tr.md">Türkçe</a> · 📖 <a href="https://opencodex.me/zh-tw/"><b>完整文件 →</b></a>
+</p>
+
+opencodex 是連接程式開發工具與模型供應商的輕量級本機閘道。它接收 Responses、Chat Completions 和 Anthropic Messages API 請求，並轉換成供應商使用的協定；在用戶端、模型和供應商支援的情況下，傳遞串流、工具呼叫、推理和影像。你可以在 Codex、Claude Code、Claude Desktop、Grok Build 及[用戶端支援頁面](https://opencodex.me/zh-tw/reference/client-support/)列出的工具中使用 Claude、Gemini、Grok、GLM、DeepSeek、Kimi、Qwen、Ollama 等供應商。它也能管理 Codex 驗證用的 **ChatGPT 帳號池**：新增帳號並在儀表板重新整理配額，新工作階段會自動路由至用量最低的健康帳號，既有對話則保持綁定原始帳號。
+
+## 快速開始
+
+### 個人安裝（CLI）
+
+```bash
+npm install -g @koreanhole/opencodex   # Node 18+；Bun 執行環境會自動打包
+ocx start                         # 代理 + 儀表板位於 localhost:10100
+```
+
+用 `ocx service` 在背景執行。
+
+開啟 **http://localhost:10100**，在網頁儀表板完成所有設定——新增供應商
+（40+ 內建，或任何 OpenAI 相容端點）、挑選模型、管理帳號。隨時可用 `ocx gui`
+重新開啟儀表板。
+
+### 連接你的工具
+
+連接你正在使用的工具：
+
+| 工具 | 連接方式 |
+|---|---|
+| Codex | 開啟儀表板 **Connect** 頁面的 Codex 開關，然後照常執行 `codex`。在本機監聽時，這會讓 Codex 內建供應商指向代理。使用終端機時，請在儀表板新增供應商之前執行 `ocx init` 並接受其 Codex 提示。 |
+| Claude Code | 安裝 `claude` CLI 後執行 `ocx claude`。它會在需要時啟動代理，並透過代理啟動 Claude Code。 |
+| Claude Desktop | 執行 `ocx claude desktop`。全新安裝時會為整個應用程式設定閘道設定檔；既有的 first-party 設定會保留，可執行 `ocx claude desktop apply --gateway` 明確切換。詳見 [Claude Code 指南](https://opencodex.me/zh-tw/guides/claude-code/)。 切換後請完全結束並重新開啟 Claude Desktop。 |
+| Grok Build | 在本機監聽且啟用 Grok 整合時，若 `~/.grok` 存在，`ocx start` 會註冊模型；在 Grok Build 中選擇 `ocx-*` 模型。遠端設定請參見 [Grok Build 指南](https://opencodex.me/zh-tw/guides/grok-build/)。新增供應商後，重新啟動代理（或在啟用 Codex 自動啟動時執行 `ocx ensure`）以更新清單。 |
+| 具備受管理整合的工具 | 使用儀表板的 **Connect** 頁面，或執行 `ocx integration client enable --client <id>`。 |
+| 其他工具 | 將自訂 OpenAI 相容基本 URL 設為 `http://localhost:10100/v1`，或將 Anthropic 基本 URL 設為 `http://localhost:10100`。 |
+
+[用戶端支援頁面](https://opencodex.me/zh-tw/reference/client-support/)列出各工具的連接方式與使用的協定。
+
+<details>
+<summary><b>桌面應用程式（Beta）</b></summary>
+
+桌面應用程式是同一套代理與儀表板的原生視窗版本，附系統匣與內建的 `ocx`。
+它會接上已在執行的代理，或啟動內建的那一個；儀表板仍使用代理的連接埠
+（除非你設定了其他連接埠，否則為 **http://localhost:10100**）。請從
+[最新發行版](https://github.com/lidge-jun/opencodex/releases/latest)挑選適合你平台的檔案：
+
+| 平台 | 檔案 | 說明 |
+|---|---|---|
+| macOS 13+（Apple Silicon 與 Intel） | `OpenCodex-<version>-macos.dmg` | 通用建置，以 Developer ID 簽章並經過公證 |
+| Windows（x64） | `OpenCodex-<version>-windows-x64.msi` | 正透過 SignPath Foundation 推出程式碼簽章（[程式碼簽章政策](https://opencodex.me/zh-tw/reference/code-signing/)）；在版本簽章之前，SmartScreen 會詢問一次，選擇 **More info → Run anyway** |
+| Linux（x86_64） | `OpenCodex-<version>-linux-x86_64.AppImage` 或 `-linux-amd64.deb` | 系統匣需要支援 AppIndicator 的桌面環境 |
+
+每個檔案在發行頁面上都附有 `.sha256`。在 macOS 14+ 上，應用程式還附帶
+WidgetKit 擴充套件，可顯示代理狀態、今日用量與供應商配額；它所呈現的快照模型位於
+[`app/`](../app)（`MenuBarCore`）。若要自行建置應用程式，先在儲存庫根目錄執行
+`bun install && bun run build:gui`，再於
+`desktop/` 執行：macOS 上用 `bun install && bun run prepare-sidecar && bun run prepare-widget && bun run build:local`，Windows 與 Linux 上用 `bun install && bun run prepare-sidecar && bun run build:local`（小工具步驟只能在 macOS 上執行）。
+[桌面應用程式指南](https://opencodex.me/zh-tw/guides/desktop-app/) 與
+[macOS 選單列應用程式指南](https://opencodex.me/zh-tw/guides/macos-menu-bar/) 涵蓋首次啟動，
+[`AGENTS_INSTALL.md`](../AGENTS_INSTALL.md#where-things-are-installed) 列出所有寫入磁碟的內容。
+
+</details>
+
+### ChatGPT 帳號池
+
+opencodex 也能為 Codex 認證管理 **ChatGPT 帳號池**。新增多個 ChatGPT / Codex 帳號，
+在儀表板重新整理 5 小時／每週／30 天配額。在配額路由下，新會話可使用
+使用量最低的健康帳號；round-robin 與 fill-first 則各自套用自己的策略。既有 Codex
+執行緒通常會維持對啟動帳號的親和性，因此長時間的 SSH、tmux 或
+行動裝置連線的會話不會在對話中途跳帳號——但配額重新評估、failover、
+帳號排除、親和性到期，或 401/403 與 429 復原，仍可能重新綁定。當其中一個帳號——通常是你的 Codex Desktop 登入——只應在其他帳號用盡後才被用到時，請為帳號設定選取順序。
+
+### 贊助
+
+贊助讓 opencodex 能跟上每一次上游協議變更。有興趣？
+見 [SPONSORS.md](../SPONSORS.md)。
+
+<!-- sponsors:main — one banner, model developers only; empty until a Main sponsor signs -->
+
+<!-- sponsors:standard — one row per sponsor, in order of signing -->
+<table>
+<tbody>
+<tr>
+<td width="180"><a href="https://www.orcarouter.ai/?utm_source=opencodex&utm_medium=readme"><img src="../assets/sponsors/orcarouter.png" alt="OrcaRouter" width="150"></a></td>
+<td>感謝 <a href="https://www.orcarouter.ai/?utm_source=opencodex&utm_medium=readme">OrcaRouter</a> 贊助本專案！OrcaRouter 是面向正式環境的 OpenAI 相容 AI 閘道：自適應路由會為每則提示評分，送到達到你門檻的模型；自動 failover；路由規則即程式碼；供應商原價零加價並含 prompt 快取；每次呼叫都有 guardrail、agent 防火牆與請求日誌，涵蓋 200+ 模型。在「新增供應商」選擇器選 <code>OrcaRouter</code>，或執行 <code>ocx provider add orcarouter</code>；<code>orcarouter/auto</code> 就是自適應路由器。</td>
+</tr>
+<tr>
+<td width="180"><a href="https://tokenlab.sh/r/OPENCODEX"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/sponsors/tokenlab-dark.png"><img src="../assets/sponsors/tokenlab-light.png" alt="TokenLab" width="150"></picture></a></td>
+<td>感謝 <a href="https://tokenlab.sh/r/OPENCODEX">TokenLab</a> 贊助本專案！TokenLab 為程式設計智慧體提供統一的多模型 API，一把 API Key 即可接入主流模型，支援 OpenAI Responses、Chat Completions、Anthropic Messages 和 Gemini 原生 API 格式，以及串流輸出和工具呼叫。同時提供 MCP 伺服器和 Agent Skills，方便接入現有工作流程；交付模式可選，按量付費。在「新增供應商」選擇器選 <code>TokenLab</code>，或執行 <code>ocx provider add tokenlab</code>。</td>
+</tr>
+</tbody>
+</table>
+
+---
+
+<details>
+<summary>Docker Compose</summary>
+
+本儲存庫提供 digest 釘選、非 root 的 Compose 建置。建置會根據選定的 Git 快照自行產生並驗證
+權威相容性清單。本機 clone 需要 Git 與 Docker Compose；遠端 Git context 需要 Docker Compose。
+兩種方式都不需要主機上的 Bun，也不需要準備步驟。透過 stdin 初始化一次資料平面權杖並啟動 hub：
+
+```bash
+git clone https://github.com/lidge-jun/opencodex.git
+cd opencodex
+docker compose build
+openssl rand -hex 32 | docker compose run --rm -T hub bun run docker/bootstrap-token.ts
+docker compose up -d
+curl --fail --silent http://127.0.0.1:10100/healthz
+curl --fail --silent http://127.0.0.1:10100/readyz
+```
+
+預設主機綁定為 `127.0.0.1:10100`。遠端公開必須明確指定
+`OPENCODEX_BIND_ADDRESS=<LAN-or-Tailscale-IP> docker compose up -d`；`0.0.0.0` 會加入
+所有主機介面。請用防火牆與已認證的 TLS／tailnet 前端限制存取。
+產生的 JSON 不會被追蹤。建置 context 只會納入 `.git/index` 與 `.git/HEAD`，也就是
+`git ls-files` 讀取的清單；大小約為 1 MB，而不是完整的 object store。這些檔案只能透過唯讀 mount
+在建置專用的 manifest 階段看到，因此沒有任何 `COPY` 會包含 `.git`。主機上已有的 manifest 只有在
+通過驗證後才會接受；否則建置會自行產生。建置會拒絕過期清單、缺少或不相符的檔案、多餘原始碼檔案，以及符號連結。
+它會核對建置上下文與複製進去的執行檔案上每一筆記錄的 SHA-256，包括
+`package.json`、`bun.lock`，以及特別納入的 `scripts/model-metadata.source.json`。
+
+遠端 Git context 需要 BuildKit 保留 Git metadata。以下 Compose 建置片段會選擇遠端快照，
+並傳入所需的內建參數：
+
+```yaml
+services:
+  hub:
+    pull_policy: build
+    build:
+      context: https://github.com/lidge-jun/opencodex.git#main
+      dockerfile: Dockerfile
+      target: runtime
+      args:
+        BUILDKIT_CONTEXT_KEEP_GIT_DIR: "1"
+```
+
+權杖與可變狀態留在名為 `ocx-state` 的 volume；映像、Compose 檔、環境變數或 shell 引數都不會放入憑證。見
+[Remote Hub 部署指南](https://opencodex.me/zh-tw/guides/remote-hub/) 以了解供應商
+設定、已認證的驗收檢查、遠端管理與還原。
+
+</details>
+
+<details>
+<summary>從原始碼安裝（最新 dev）</summary>
+
+**macOS / Linux：**
+
+```bash
+curl -fsSL https://bun.sh/install | bash
+git clone -b dev https://github.com/lidge-jun/opencodex.git
+cd opencodex && ~/.bun/bin/bun install
+~/.bun/bin/bun run build:gui
+~/.bun/bin/bun run src/cli/index.ts start
+```
+
+**Windows (PowerShell)：**
+
+```powershell
+irm bun.sh/install.ps1 | iex
+git clone -b dev https://github.com/lidge-jun/opencodex.git
+cd opencodex; bun install
+bun run build:gui
+bun run src/cli/index.ts start
+```
+
+從原始碼安裝會跑最新的 `dev` 分支。記憶體所有權
+修補、執行環境 GC 改善，以及尚未發布的修正，都會比 npm 套件更早在這裡出現。
+
+</details>
+
+<details>
+<summary>給 agent 使用</summary>
+
+```bash
+npm install -g @koreanhole/opencodex
+ocx start     # 或 `ocx service`
+ocx init      # 互動式設定：寫入 ~/.opencodex/config.json 並接上 Codex
+```
+
+`ocx init` 永遠不會啟動代理；請先啟動（或之後再啟動——順序都可以，但像
+`ocx provider add` 與 `ocx combo set` 這類無介面命令會跟**正在執行**的代理通訊，連不上就以非零結束碼結束）。`ocx status` / `ocx doctor` / `ocx health` 回報執行狀態。
+
+> **正在安裝或執行 opencodex 的 agent：** 請讀
+> [`AGENTS_INSTALL.md`](../AGENTS_INSTALL.md)。互動式 `ocx start` 可能會問一次要不要
+> 為此儲存庫按星——那是使用者的決定，絕不是 agent 的。CLI 會在 agent 驅動的執行中隱藏該
+> 提示，API 則以 `403 agent_consent_required` 拒絕。
+
+</details>
+
+## 支援平台
+
+| 作業系統 | 狀態 | 服務管理員 | 桌面應用程式（Beta） |
+|---|---|---|---|
+| macOS (arm64 / x64) | 完整支援 | launchd | 通用 `.dmg` |
+| Linux (x64 / arm64) | 完整支援 | systemd（使用者單元） | x86_64 `.AppImage` / `.deb` |
+| Windows (x64) | 完整支援 | Task Scheduler（隱藏）／可選原生服務（`--native`、WinSW） | x64 `.msi` |
+
+CLI 安裝需要 [Node](https://nodejs.org) 18+；桌面應用程式則不需要 Node 或 Bun。Bun 執行環境在 `npm install` 時一併打包——不必另外安裝
+Bun，Windows 也不需要 WSL。若 npm 攔截了打包執行環境的安裝腳本，
+見[安裝文件](https://opencodex.me/zh-tw/getting-started/installation/)。
+
+## 亮點
+
+- **在 Codex、Claude Code、Claude Desktop 與 Grok Build 使用任何 LLM** — 開箱即用 40+ 供應商，
+  各自保留原生 UI。
+- **沿用本機 CLI 登入** —— `cline-cli/default` 與 `gemini-cli/default` 委派給已安裝且已登入的 CLI，工具核准與執行仍由 Codex 負責。
+- **池化 ChatGPT 帳號** — 執行緒親和性、依配額自動切換、冷卻與
+  fail-closed 認證處理。
+
+  > **供應商政策說明：** 帳號池只用來做路由與營運韌性；它不保證
+  > 能避開供應商的速率限制、執法、停權或其他帳號
+  > 處置。OpenCodex 不贊成用額外帳號規避供應商限制，也不贊成
+  > 在人與人之間共用帳號憑證。你有責任遵守各
+  > 供應商的現行條款。見
+  > [Codex Auth 帳號池指南](https://opencodex.me/zh-tw/guides/web-dashboard/)
+  > 與 [OpenAI 現行使用條款](https://openai.com/policies/terms-of-use/)。
+- **Combo** — 一個虛擬模型 id，可在供應商之間 failover 或加權 round-robin。見
+  [combo 指南](https://opencodex.me/zh-tw/guides/combos/)。
+- **任何模型上的子代理** — 讓路由模型出現在 Codex 的子代理選擇器，含 v1/v2
+  介面控制與 fallback 鏈。見
+  [子代理指南](https://opencodex.me/zh-tw/guides/sub-agent-surface/)。
+<!-- sponsors:main-first-mention -->
+- **登入一次，不必填 API key** — xAI、Anthropic、Kimi 支援 OAuth；也可轉發
+  `codex login`、貼上金鑰，或使用 `${ENV_VAR}` 引用。
+- **網頁搜尋與視覺 sidecar** — 非 OpenAI 模型可透過掛在你 ChatGPT 登入上的 sidecar，獲得真正的網頁搜尋與圖片理解。
+- **看清正在發生什麼** — 儀表板顯示供應商、OAuth 狀態、模型選擇，以及含快取 token 計數的即時請求日誌。
+- **乾淨退出，零殘留** — `ocx stop` 把 Codex 還原成原始設定。
+- **有界記憶體所有權** — 每個長生命週期的快取、環形緩衝區與協議翻譯
+  儲存都有有限上限、位元組預算或主動調和。設定重新載入後，不會留下無界的 `Map` 或 `Set`。
+
+<details>
+<summary>記憶體所有權細節</summary>
+
+OpenCodex 在下列類別中追蹤行程保留狀態。每一類都有文件化的上限：
+
+- **14 個保留儲存**（請求日誌、除錯環形緩衝、圖片快取、模型快取、視覺
+  描述、cursor blob、responses 延續等）以位元組計帳，並由
+  應用程式自己的記憶體預算淘汰（預設 256 MiB）；其中 native control replay
+  儲存為固定，不會被淘汰。
+- **4 個觀測緩衝區**（翻譯累加器、image/OAuth/Grok 尾端）會
+  監控進行中的位元組壓力，但不淘汰。
+- **31 個狀態儲存註冊**負責到期清掃（間隔 60 秒）與
+  設定世代調和，以移除過期的供應商／帳號鍵。
+- **路徑與指紋 memo**（工作區中繼資料、強化身分、安裝
+  salt、mode-hint 能力）使用插入順序 LRU 上限（8–128 筆）。
+- **模型快取世代 tombstone** 在調和後刪除；全域
+  世代遞增可避免過期、進行中的探索把已移除的供應商填回來。
+- **Lab event-id 去重**在磁碟帳本鎖下執行，行程層級沒有
+  RAM 索引。
+
+執行 `GET /api/system/memory`（帶管理權杖）可檢視目前保留的位元組、
+淘汰計數與 watchdog 樣本。
+
+</details>
+
+## 模型路由
+
+用 `provider/model` 語法指定任何已設定的供應商與模型：
+
+```bash
+codex -m "anthropic/claude-opus-5" "解釋這個 stack trace"
+codex -m "google/gemini-3-pro" "為 auth.ts 寫單元測試"
+codex -m "ollama/llama3" "重構這個 function"
+```
+
+省略 `provider/` 字首時，會使用預設供應商，或依模型名模式自動匹配。
+供應商模型 id 若含 `/`，對外會把內部斜線別名成 `-`；原始
+全斜線形式同樣可用。細節：[模型路由文件](https://opencodex.me/zh-tw/guides/model-routing/)。
+
+### JEV Auto 路由（選用）
+
+TypeSafe JEV 可以為明確啟用的 Combo 選擇第一個模型與推理強度，一般模型選擇器與所有直接路由保持不變。
+透過 `ocx login jev`、**Providers → TypeSafe JEV → Add API key** 或 `TYPESAFE_API_KEY`/`JEV_API_KEY`
+加入憑證。接著開啟 **Models → Combos → Create JEV Auto**，選擇允許的目標模型，並為每個目標勾選
+JEV 可選的推理強度。未變更強度設定的目標會允許該模型目前宣告的所有強度。
+
+JEV 只用於 `jev-auto`，且每次邏輯模型呼叫只諮詢一次。缺少憑證、網路失敗或決策無效時，會 fail-open
+到目前第一個可用目標；呼叫端取消仍會取消請求。自動化測試使用模擬的 TypeSafe 端點，
+不驗證真實的 JEV 帳戶。
+
+JEV Combo 也可以改用自架的決策模型，例如無需金鑰的 Ollama `tev1`：新增一個 `baseUrl` 為完整
+`/v1/systemone` 端點的 `jev-decision` 供應商，並將其設為 Combo 的 `decisionProvider`。TypeSafe 憑證
+絕不會傳送到該端點。詳見[自架決策模型](https://opencodex.me/zh-tw/guides/combos/)。
+
+## 供應商與 adapter
+
+<!-- sponsors:main-first-mention -->
+OpenAI（ChatGPT 登入或 API key）、Anthropic、Google Gemini、xAI、Kimi、Azure OpenAI、Ollama
+（本機 + Cloud）、Cursor（實驗性），以及所有 OpenAI 相容端點——再加上 DeepSeek、
+Groq、OpenRouter、OpenGateway、Together、Fireworks、Cerebras、Mistral、Hugging Face、NVIDIA NIM、MiniMax、
+Qwen Cloud、Qoder Global 與 CN（官方 PAT + CLI）、SiliconFlow 等等。完整清單：`ocx init` 或
+[供應商文件](https://opencodex.me/zh-tw/guides/providers/)。
+
+## CLI
+
+```bash
+ocx init                       # 互動式設定（寫入設定、接上 Codex、提供 shim）
+ocx start [--port 10100] [--socks5 [host:port] | --socks5-off]  # SOCKS5 預設為 socks5://127.0.0.1:10808
+ocx stop                       # 停止並還原原生 Codex
+ocx service [install|repair|restart|start|stop|status|uninstall|remove]  # 背景服務
+ocx codex-shim install         # 每次啟動 `codex` 時按需啟動代理
+ocx health [--json]            # 檢查代理當下是否存活
+ocx ready [--json] [--wait [--timeout <seconds>]]  # 檢查同步後是否就緒
+ocx status                     # 代理是否在執行？
+ocx gui                        # 開啟網頁儀表板
+ocx provider <...>             # 管理供應商（list/add/edit/test/remove）
+ocx account <...>              # 管理 ChatGPT 帳號與 API-key 池
+ocx combo <...>                # 管理 failover／round-robin combo
+ocx v2 <...>                   # 多代理 v1/v2 介面控制
+ocx update [--tag preview]     # 更新 opencodex
+```
+
+偏好的連接埠被占用時，啟動會停止並指出占用者，而不會改用其他連接埠，因此絕不會在第一個代理旁留下另一個
+執行中的代理。請釋放該連接埠，或用 `--port` 指定其他連接埠。完整參考：[CLI 文件](https://opencodex.me/zh-tw/reference/cli/)。
+
+### 健康狀態與就緒
+
+`GET /healthz` 回報代理當下是否存活。未認證的 `GET /readyz` 端點回報
+同步後就緒狀態，並附上淨化後的 JSON 身分 `{service, version, uptime, pid, port, status}`。
+當 `status` 為 `ready` 時回傳 `200`；`pending` 與終態 `failed` 回傳 `503`，並帶
+`Retry-After: 1`。
+
+`ocx ready [--json] [--wait [--timeout <seconds>]]` 預設只探測一次。`--wait` 預設最多輪詢
+45 秒，但一看到終態 `failed` 就立刻結束；
+`--timeout <seconds>` 設定 1–300 秒上限，必須搭配 `--wait`，且只接受正整數。CLI `--json` 輸出為
+`{ready, status, pid, port}`，其中 `status` 為 `ready`、`pending`、`failed` 或 `unreachable`。
+
+| 結束碼 | 結果 |
+| --- | --- |
+| `0` | 就緒 |
+| `1` | 未就緒：pending、failed、timeout 或 unreachable |
+| `64` | 無效引數 |
+
+沒有 `/readyz` 的舊代理會 fail-closed 成 `unreachable`，結束碼為 1；`ocx health`
+仍保持相容。
+
+### 自動啟動：service 與 shim
+
+用 **service**（`ocx service`）做常駐代理，當機後會重啟。用
+**shim**（`ocx codex-shim install`）做輕量、按需啟動，不必背景常駐程式。用 `ocx service uninstall` / `ocx codex-shim uninstall` 移除。
+
+### 解除安裝
+
+```bash
+ocx uninstall                  # 停止、移除 service／shim、還原原生 Codex、清掉狀態
+npm uninstall -g @koreanhole/opencodex
+```
+
+## 遠端存取
+
+預設 opencodex 綁定 `127.0.0.1`，不必額外認證。綁定超出
+迴環（`"hostname": "0.0.0.0"`）**必須**有 bearer 權杖——沒有
+`OPENCODEX_API_AUTH_TOKEN` 代理會拒絕啟動，每個用戶端請求都必須以
+`x-opencodex-api-key` 帶上它。細節：[設定參考](https://opencodex.me/zh-tw/reference/configuration/)。
+
+## 文件
+
+公開文件——安裝、供應商、路由、combo、子代理、sidecar、整合，以及
+CLI／設定／管理 API 參考——由 [`docs-site/`](../docs-site) 建置，
+發布於 **[opencodex.me](https://opencodex.me/zh-tw/)**。
+
+維護者的權威筆記在 [`structure/`](../structure)，貢獻者設定在
+[`CONTRIBUTING.md`](../CONTRIBUTING.md)，安全性回報在 [`SECURITY.md`](../SECURITY.md)。
+未公開的漏洞請透過
+[GitHub 私人漏洞回報](https://github.com/lidge-jun/opencodex/security/advisories/new)
+私下回報，不要開公開 issue。
+這份表單是唯一的技術管道，沒有安全信箱。後續往來都留在這份私人回報裡；公開 issue 只能用來協調，不能放
+漏洞細節。確認收到回報不等於已經分診，也不承諾首次回應的時限。
+
+## 開發
+
+從原始碼開發需要 `PATH` 上有 `bun` CLI。已發布的 npm 套件為已安裝的 `ocx` 命令打包自己的
+Bun 執行環境；套件指令碼也可能透過這個打包依賴解析 Bun。
+
+```bash
+git clone https://github.com/lidge-jun/opencodex.git
+cd opencodex
+bun install
+bun run typecheck
+bun run test
+```
+
+見 **[貢獻指南](../CONTRIBUTING.md)**。
+
+經維護者代為帶入或重寫而落地的貢獻者工作，
+若 commit 沒有寫出原作者，會記錄在
+**[CREDITS.md](../CREDITS.md)**。
+
+## 程式碼簽章政策 (Code signing policy)
+
+Windows 執行檔正在改用 Authenticode 簽章（[#7207](https://github.com/lidge-jun/opencodex/issues/7207)）。推出進度、簽章驗證方式與完整政策請見 [Windows 程式碼簽章指南](https://opencodex.me/zh-tw/reference/code-signing/)。
+
+Free code signing provided by [SignPath.io](https://about.signpath.io/), certificate by [SignPath Foundation](https://signpath.org/).
+
+- Committers and reviewers: [lidge-jun](https://github.com/lidge-jun)
+- Approvers: [lidge-jun](https://github.com/lidge-jun)
+- Privacy: This program will not transfer any information to other networked systems unless specifically requested by the user or the person installing or operating it.
+
+## 免責聲明
+
+opencodex 是獨立的社群維護專案，**與 OpenAI、Anthropic 或其他任何供應商無關，也未獲其背書。**
+
+部分供應商——尤其是 Anthropic（Claude）——可能會暫停或限制經第三方代理路由 API 流量的帳號。**使用風險自負（UAYOR）。** 連線供應商前，請先查其服務條款，確認是否允許代理式存取。上游供應商對帳號採取的任何處置，opencodex 維護者概不負責。
+
+## 授權
+
+MIT

package/src/adapters/cli-agent/cline/adapter.ts

@@ -14,6 +14,7 @@ import {
   assertClineSelectionSafe,
   buildClineChildEnv,
   ClineSettingsError,
+  mergeClineDisabledTools,
   preflightClineTools,
   resolveClineProviderSettingsPath,
   stageClineTurn,
@@ -267,11 +268,26 @@ export function createClineCliAdapter(
       }
 
       const env = buildClineChildEnv(staged, sourceEnv);
-      const preflight = await (deps.preflightTools ?? preflightClineTools)({
+      const preflightTools = deps.preflightTools ?? preflightClineTools;
+      let preflight = await preflightTools({
         binary,
         env,
         cwd: staged.workspaceDir,
       });
+      if (!preflight.ok && preflight.enabledTools && preflight.enabledTools.length > 0) {
+        try {
+          await mergeClineDisabledTools(staged, preflight.enabledTools.map(tool => tool.id));
+        } catch (error) {
+          await staged.cleanup();
+          emit(settingsError(error));
+          return;
+        }
+        preflight = await preflightTools({
+          binary,
+          env,
+          cwd: staged.workspaceDir,
+        });
+      }
       if (!preflight.ok) {
         await staged.cleanup();
         emit({

package/src/adapters/cli-agent/cline/settings.ts

@@ -68,9 +68,15 @@ export interface ClineStagedTurn {
   cleanup: () => Promise<void>;
 }
 
+export interface ClineEnabledTool {
+  id: string;
+  kind: "builtin";
+}
+
 export interface ClineToolPreflightResult {
   ok: boolean;
   detail?: string;
+  enabledTools?: readonly ClineEnabledTool[];
 }
 
 export interface ClineSelection {
@@ -346,18 +352,66 @@ function runPreflightProcess(
   });
 }
 
+/** Merge discovered built-in IDs into the turn's private staged disable list. */
+export async function mergeClineDisabledTools(
+  staged: Pick<ClineStagedTurn, "globalSettingsPath">,
+  ids: readonly string[],
+): Promise<void> {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(await readFile(staged.globalSettingsPath, "utf8"));
+  } catch {
+    throw new ClineSettingsError(
+      "Cline global settings are malformed; the tool preflight cannot be repaired.",
+      500,
+      "cline_cli_setup_failed",
+    );
+  }
+  const settings = asRecord(parsed);
+  if (!settings) {
+    throw new ClineSettingsError(
+      "Cline global settings are malformed; the tool preflight cannot be repaired.",
+      500,
+      "cline_cli_setup_failed",
+    );
+  }
+  const current = Array.isArray(settings.disabledTools)
+    ? settings.disabledTools.filter((value): value is string => typeof value === "string")
+    : [];
+  const merged = [...new Set([...current, ...ids])];
+  await writeFile(
+    staged.globalSettingsPath,
+    `${JSON.stringify({ ...settings, disabledTools: merged }, null, 2)}\n`,
+    { encoding: "utf8", mode: 0o600 },
+  );
+}
+
 /** Verify the isolated Cline config advertises no executable built-in or plugin tool. */
 export function validateClineToolCatalog(parsed: unknown): ClineToolPreflightResult {
   if (!Array.isArray(parsed)) return { ok: false, detail: "Cline tool preflight returned a non-array catalog." };
+  const enabledTools: ClineEnabledTool[] = [];
+  let pluginDetail: string | undefined;
   for (const item of parsed) {
     const record = asRecord(item);
     if (!record) continue;
-    if (record.defaultEnabled === true) {
-      return { ok: false, detail: `Cline enabled built-in tool ${String(record.id ?? record.name ?? "unknown")}.` };
-    }
-    if (record.type === "plugin" && record.enabled === true) {
-      return { ok: false, detail: `Cline enabled plugin tool ${String(record.name ?? "unknown")}.` };
+    if (record.type === "plugin") {
+      if (record.enabled === true) {
+        pluginDetail ??= `Cline enabled plugin tool ${String(record.name ?? "unknown")}.`;
+      }
+      continue;
     }
+    if (record.defaultEnabled !== true) continue;
+    const id = nonEmpty(record.id);
+    if (!id) return { ok: false, detail: "Cline enabled a built-in tool without an id." };
+    enabledTools.push({ id, kind: "builtin" });
+  }
+  if (pluginDetail) return { ok: false, detail: pluginDetail };
+  if (enabledTools.length > 0) {
+    return {
+      ok: false,
+      detail: `Cline enabled built-in tool ${enabledTools[0]!.id}.`,
+      enabledTools,
+    };
   }
   return { ok: true };
 }

package/src/generated/compatibility-version.json

@@ -10,7 +10,7 @@
     },
     {
       "path": "package.json",
-      "sha256": "b60c8ba9f3ba6dbad509253691841f95d84fa4cd24ef380aeba7471ed1a48423"
+      "sha256": "5defa1ac2920d665f397af48488d385a55142f49dc0998e0404c1eb312e2e4fb"
     },
     {
       "path": "scripts/model-metadata.source.json",
@@ -122,11 +122,11 @@
     },
     {
       "path": "src/adapters/cli-agent/cline/adapter.ts",
-      "sha256": "34b1c2c54834064a37f4fe698928d5581d1f0fa13c5614b7e6f8b06e5f4623f5"
+      "sha256": "77593a26a0956e82e07995d85ba56128f0bc7f60f2b77373d8cdff4142e998e9"
     },
     {
       "path": "src/adapters/cli-agent/cline/settings.ts",
-      "sha256": "83b3f78351967d985c3684e1f754f3cecc466ca529320c78ba1c63dc488bbc70"
+      "sha256": "13287a35b87e3f68eaf0f13f0af4669c64917612012ed596d762b5d29b0be5fc"
     },
     {
       "path": "src/adapters/cli-agent/cline/stream.ts",