- {t('Any provider', '모든 프로바이더', '任意 provider', 'Любой провайдер', '任意のプロバイダー')}
+ {t('Any provider', '모든 프로바이더', '任意 provider', 'Любой провайдер', '任意のプロバイダー', '任意供應商')}
- {t('Five adapters cover Anthropic Messages, Google Gemini, Azure, the OpenAI Responses passthrough, and every OpenAI-compatible Chat Completions endpoint — 40+ built-in providers.', '어댑터 다섯 개가 Anthropic Messages, Google Gemini, Azure, OpenAI Responses passthrough, 그리고 모든 OpenAI 호환 Chat Completions 엔드포인트를 커버합니다 — 내장 프로바이더 40+.', '五个适配器覆盖 Anthropic Messages、Google Gemini、Azure、OpenAI Responses passthrough，以及所有 OpenAI 兼容的 Chat Completions 端点 —— 内置 40+ provider。', 'Пять адаптеров покрывают Anthropic Messages, Google Gemini, Azure, OpenAI Responses passthrough и любую OpenAI-совместимую конечную точку Chat Completions — 40+ встроенных провайдеров.', '5 つのアダプターが Anthropic Messages、Google Gemini、Azure、OpenAI Responses passthrough、そしてすべての OpenAI 互換 Chat Completions エンドポイントをカバーします — 組み込みプロバイダー 40+。')}
+ {t('Five adapters cover Anthropic Messages, Google Gemini, Azure, the OpenAI Responses passthrough, and every OpenAI-compatible Chat Completions endpoint — 40+ built-in providers.', '어댑터 다섯 개가 Anthropic Messages, Google Gemini, Azure, OpenAI Responses passthrough, 그리고 모든 OpenAI 호환 Chat Completions 엔드포인트를 커버합니다 — 내장 프로바이더 40+.', '五个适配器覆盖 Anthropic Messages、Google Gemini、Azure、OpenAI Responses passthrough，以及所有 OpenAI 兼容的 Chat Completions 端点 —— 内置 40+ provider。', 'Пять адаптеров покрывают Anthropic Messages, Google Gemini, Azure, OpenAI Responses passthrough и любую OpenAI-совместимую конечную точку Chat Completions — 40+ встроенных провайдеров.', '5 つのアダプターが Anthropic Messages、Google Gemini、Azure、OpenAI Responses passthrough、そしてすべての OpenAI 互換 Chat Completions エンドポイントをカバーします — 組み込みプロバイダー 40+。', '五個適配器覆蓋 Anthropic Messages、Google Gemini、Azure、OpenAI Responses passthrough，以及所有 OpenAI 相容的 Chat Completions 端點 —— 內建 40+ 供應商。')}
- {t('OAuth or API key', 'OAuth 또는 API 키', 'OAuth 或 API key', 'OAuth или API-ключ', 'OAuth または API キー')}
- {t('Log in with your xAI, Anthropic, or Kimi account — auto-refreshed — forward your ChatGPT login, or paste a key.', 'xAI, Anthropic, Kimi 계정으로 로그인(자동 갱신)하거나, ChatGPT 로그인을 포워딩하거나, 키를 붙여넣으세요.', '使用 xAI、Anthropic 或 Kimi 账号登录（自动刷新），转发 ChatGPT 登录，或粘贴 API key。', 'Войдите через аккаунт xAI, Anthropic или Kimi — с автообновлением, — пробросьте свой вход ChatGPT или просто вставьте ключ.', 'xAI、Anthropic、Kimi アカウントでログイン（自動更新）、ChatGPT ログインを転送、またはキーを貼り付け。')}
+ {t('OAuth or API key', 'OAuth 또는 API 키', 'OAuth 或 API key', 'OAuth или API-ключ', 'OAuth または API キー', 'OAuth 或 API key')}
+ {t('Log in with your xAI, Anthropic, or Kimi account — auto-refreshed — forward your ChatGPT login, or paste a key.', 'xAI, Anthropic, Kimi 계정으로 로그인(자동 갱신)하거나, ChatGPT 로그인을 포워딩하거나, 키를 붙여넣으세요.', '使用 xAI、Anthropic 或 Kimi 账号登录（自动刷新），转发 ChatGPT 登录，或粘贴 API key。', 'Войдите через аккаунт xAI, Anthropic или Kimi — с автообновлением, — пробросьте свой вход ChatGPT или просто вставьте ключ.', 'xAI、Anthropic、Kimi アカウントでログイン（自動更新）、ChatGPT ログインを転送、またはキーを貼り付け。', '使用 xAI、Anthropic 或 Kimi 帳號登入（自動重新整理），轉發 ChatGPT 登入，或貼上 API key。')}
- {t('ChatGPT account pool', 'ChatGPT 계정 풀', 'ChatGPT 账号池', 'Пул аккаунтов ChatGPT', 'ChatGPT アカウントプール')}
- {t('Existing threads keep their account; new sessions auto-route to the lowest-usage healthy one after quota refresh.', '기존 thread는 계정을 유지하고, 새 세션은 할당량 갱신 후 사용량이 가장 낮은 정상 계정으로 자동 라우팅됩니다.', '已有 thread 保持原账号；新会话在刷新额度后自动路由到用量最低的健康账号。', 'Существующие треды сохраняют свой аккаунт; новые сессии после обновления квоты автоматически направляются на наименее загруженный работоспособный аккаунт.', '既存の thread はアカウントを維持し、新しいセッションは quota 更新後に使用量が最も低い健全なアカウントへ自動ルーティングされます。')}
+ {t('ChatGPT account pool', 'ChatGPT 계정 풀', 'ChatGPT 账号池', 'Пул аккаунтов ChatGPT', 'ChatGPT アカウントプール', 'ChatGPT 帳號池')}
+ {t('Existing threads keep their account; new sessions auto-route to the lowest-usage healthy one after quota refresh.', '기존 thread는 계정을 유지하고, 새 세션은 할당량 갱신 후 사용량이 가장 낮은 정상 계정으로 자동 라우팅됩니다.', '已有 thread 保持原账号；新会话在刷新额度后自动路由到用量最低的健康账号。', 'Существующие треды сохраняют свой аккаунт; новые сессии после обновления квоты автоматически направляются на наименее загруженный работоспособный аккаунт.', '既存の thread はアカウントを維持し、新しいセッションは quota 更新後に使用量が最も低い健全なアカウントへ自動ルーティングされます。', '已有 thread 保持原帳號；新會話在重新整理額度後自動路由到用量最低的健康帳號。')}
- {t('Native in the model picker', '모델 선택기에 그대로', '原生出现在模型选择器', 'Нативно в селекторе моделей', 'モデルピッカーにネイティブ表示')}
- {t('Routed models show up in Codex App with reasoning effort levels, next to the native ones.', '라우팅된 모델이 추론 강도 레벨과 함께 Codex App 선택기에 네이티브 모델과 나란히 표시됩니다.', '路由模型带推理强度等级出现在 Codex App 中，与原生模型并列。', 'Маршрутизированные модели появляются в Codex App с уровнями рассуждений — рядом с нативными.', 'ルーティングされたモデルは推論 effort レベルとともに Codex App のピッカーにネイティブモデルの隣に表示されます。')}
-
+ {t('Native in the model picker', '모델 선택기에 그대로', '原生出现在模型选择器', 'Нативно в селекторе моделей', 'モデルピッカーにネイティブ表示', '原生出現在模型選擇器')}
+ {t('Routed models show up in Codex App with reasoning effort levels, next to the native ones.', '라우팅된 모델이 추론 강도 레벨과 함께 Codex App 선택기에 네이티브 모델과 나란히 표시됩니다.', '路由模型带推理强度等级出现在 Codex App 中，与原生模型并列。', 'Маршрутизированные модели появляются в Codex App с уровнями рассуждений — рядом с нативными.', 'ルーティングされたモデルは推論 effort レベルとともに Codex App のピッカーにネイティブモデルの隣に表示されます。', '路由模型帶推理強度等級出現在 Codex App 中，與原生模型並列。')}
+
- {t('Sub-agents', '서브에이전트', '子代理', 'Подагенты', 'サブエージェント')}
- {t('Pin up to five routed or native models for Codex spawn_agent, and switch the v1 / base / v2 surface globally.', 'Codex spawn_agent용으로 라우팅·네이티브 모델을 최대 5개 고정하고, v1 / base / v2 서피스를 전역으로 전환합니다.', '为 Codex spawn_agent 固定最多五个路由或原生模型，并全局切换 v1 / base / v2 界面。', 'Закрепите до пяти маршрутизированных или нативных моделей для Codex spawn_agent и глобально переключайте интерфейс v1 / base / v2.', 'Codex spawn_agent 用にルーティング済み/ネイティブモデルを最大 5 つ固定し、v1 / base / v2 サーフェスをグローバルに切り替えます。')}
+ {t('Sub-agents', '서브에이전트', '子代理', 'Подагенты', 'サブエージェント', '子代理')}
+ {t('Pin up to five routed or native models for Codex spawn_agent, and switch the v1 / base / v2 surface globally.', 'Codex spawn_agent용으로 라우팅·네이티브 모델을 최대 5개 고정하고, v1 / base / v2 서피스를 전역으로 전환합니다.', '为 Codex spawn_agent 固定最多五个路由或原生模型，并全局切换 v1 / base / v2 界面。', 'Закрепите до пяти маршрутизированных или нативных моделей для Codex spawn_agent и глобально переключайте интерфейс v1 / base / v2.', 'Codex spawn_agent 用にルーティング済み/ネイティブモデルを最大 5 つ固定し、v1 / base / v2 サーフェスをグローバルに切り替えます。', '為 Codex spawn_agent 固定最多五個路由或原生模型，並全域切換 v1 / base / v2 介面。')}
Claude Code
- {t('ocx claude launches Claude Code against the same port — every routed model in the /model picker, auto-context up to 1M, roster sub-agents, and your claude.ai login stays active.', 'ocx claude가 같은 포트로 Claude Code를 띄웁니다 — 라우팅된 모든 모델이 /model 선택기에 뜨고, 최대 1M auto-context, 로스터 서브에이전트, claude.ai 로그인은 그대로 유지됩니다.', 'ocx claude 让 Claude Code 连接同一端口 —— 所有路由模型出现在 /model 选择器中，auto-context 最高 1M，roster 子代理，claude.ai 登录保持不变。', 'ocx claude запускает Claude Code на том же порту — все маршрутизированные модели в селекторе /model, auto-context до 1M, подагенты из ростера, а ваш вход в claude.ai остаётся активным.', 'ocx claude が同じポートで Claude Code を起動します — ルーティングされたすべてのモデルが /model ピッカーに表示され、最大 1M の auto-context、ロスターのサブエージェント、claude.ai ログインはそのまま維持されます。')}
- 
+ {t('ocx claude launches Claude Code against the same port — every routed model in the /model picker, auto-context up to 1M, roster sub-agents, and your claude.ai login stays active.', 'ocx claude가 같은 포트로 Claude Code를 띄웁니다 — 라우팅된 모든 모델이 /model 선택기에 뜨고, 최대 1M auto-context, 로스터 서브에이전트, claude.ai 로그인은 그대로 유지됩니다.', 'ocx claude 让 Claude Code 连接同一端口 —— 所有路由模型出现在 /model 选择器中，auto-context 最高 1M，roster 子代理，claude.ai 登录保持不变。', 'ocx claude запускает Claude Code на том же порту — все маршрутизированные модели в селекторе /model, auto-context до 1M, подагенты из ростера, а ваш вход в claude.ai остаётся активным.', 'ocx claude が同じポートで Claude Code を起動します — ルーティングされたすべてのモデルが /model ピッカーに表示され、最大 1M の auto-context、ロスターのサブエージェント、claude.ai ログインはそのまま維持されます。', 'ocx claude 讓 Claude Code 連線同一連接埠 —— 所有路由模型出現在 /model 選擇器中，auto-context 最高 1M，roster 子代理，claude.ai 登入保持不變。')}
+
- {t('Search & vision sidecars', '검색 & 비전 사이드카', '搜索与视觉边车', 'Сайдкары поиска и зрения', '検索 & ビジョンサイドカー')}
- {t('Give non-OpenAI models real web search and image understanding through a gpt-5.4-mini sidecar.', 'gpt-5.4-mini 사이드카로 비 OpenAI 모델에 실제 웹 검색과 이미지 이해를 붙입니다.', '通过 gpt-5.4-mini 边车，让非 OpenAI 模型获得真实的网页搜索与图像理解能力。', 'Дайте моделям не от OpenAI настоящий веб-поиск и понимание изображений через сайдкар gpt-5.4-mini.', 'gpt-5.4-mini サイドカーで非 OpenAI モデルに本物のウェブ検索と画像理解を提供します。')}
+ {t('Search & vision sidecars', '검색 & 비전 사이드카', '搜索与视觉边车', 'Сайдкары поиска и зрения', '検索 & ビジョンサイドカー', '搜尋與視覺邊車')}
+ {t('Give non-OpenAI models real web search and image understanding through a gpt-5.4-mini sidecar.', 'gpt-5.4-mini 사이드카로 비 OpenAI 모델에 실제 웹 검색과 이미지 이해를 붙입니다.', '通过 gpt-5.4-mini 边车，让非 OpenAI 模型获得真实的网页搜索与图像理解能力。', 'Дайте моделям не от OpenAI настоящий веб-поиск и понимание изображений через сайдкар gpt-5.4-mini.', 'gpt-5.4-mini サイドカーで非 OpenAI モデルに本物のウェブ検索と画像理解を提供します。', '透過 gpt-5.4-mini 邊車，讓非 OpenAI 模型獲得真實的網頁搜尋與圖像理解能力。')}
- {t('Quickstart', '퀵스타트', '快速开始', 'Быстрый старт', 'クイックスタート')}
- {t('ocx init writes a provider into your Codex config and shares one model catalog with Codex CLI, TUI, App, and SDK. ocx stop restores native Codex cleanly.', 'ocx init이 Codex 설정에 프로바이더를 기록하고 CLI, TUI, App, SDK가 같은 모델 카탈로그를 공유합니다. ocx stop이면 네이티브 Codex로 깔끔하게 복원됩니다.', 'ocx init 将 provider 写入 Codex 配置，CLI、TUI、App 与 SDK 共享同一模型目录。ocx stop 可干净地恢复原生 Codex。', 'ocx init записывает провайдера в конфигурацию Codex, а Codex CLI, TUI, App и SDK используют общий каталог моделей. ocx stop чисто восстанавливает нативный Codex.', 'ocx init が Codex 設定にプロバイダーを書き込み、CLI、TUI、App、SDK と同じモデルカタログを共有します。ocx stop でネイティブ Codex に綺麗に復元します。')}
+ {t('Quickstart', '퀵스타트', '快速开始', 'Быстрый старт', 'クイックスタート', '快速入門')}
+ {t('ocx init writes a provider into your Codex config and shares one model catalog with Codex CLI, TUI, App, and SDK. ocx stop restores native Codex cleanly.', 'ocx init이 Codex 설정에 프로바이더를 기록하고 CLI, TUI, App, SDK가 같은 모델 카탈로그를 공유합니다. ocx stop이면 네이티브 Codex로 깔끔하게 복원됩니다.', 'ocx init 将 provider 写入 Codex 配置，CLI、TUI、App 与 SDK 共享同一模型目录。ocx stop 可干净地恢复原生 Codex。', 'ocx init записывает провайдера в конфигурацию Codex, а Codex CLI, TUI, App и SDK используют общий каталог моделей. ocx stop чисто восстанавливает нативный Codex.', 'ocx init が Codex 設定にプロバイダーを書き込み、CLI、TUI、App、SDK と同じモデルカタログを共有します。ocx stop でネイティブ Codex に綺麗に復元します。', 'ocx init 將供應商寫入 Codex 設定，CLI、TUI、App 與 SDK 共享同一模型目錄。ocx stop 可乾淨地恢復原生 Codex。')}
zsh
{quickstart.map((line) => ($ {line.cmd} # {line.note}{'\n'}))}
@@ -265,8 +265,8 @@ const docsMap = [
-
- {t('Explore the docs', '문서 살펴보기', '浏览文档', 'Изучите документацию', 'ドキュメントを探る')}
+
+ {t('Explore the docs', '문서 살펴보기', '浏览文档', 'Изучите документацию', 'ドキュメントを探る', '瀏覽文件')}
{docsMap.map((group) => (
@@ -287,7 +287,8 @@ const docsMap = [
'opencodex는 독립 커뮤니티 프로젝트이며 OpenAI, Anthropic 등 어떤 프로바이더와도 제휴하거나 보증받지 않습니다. 일부 프로바이더는 서드파티 프록시 경유 트래픽 계정을 제한할 수 있으니 연결 전 각 프로바이더의 이용약관을 확인하세요.',
'opencodex 是独立的社区项目，与 OpenAI、Anthropic 或任何其他 provider 均无关联或背书。部分 provider 可能限制经第三方代理路由流量的账号 —— 连接前请查阅各 provider 的服务条款。',
'opencodex — независимый проект сообщества, никак не связанный с OpenAI, Anthropic или любым другим провайдером и не одобренный ими. Некоторые провайдеры могут ограничивать аккаунты, направляющие трафик через сторонние прокси, — перед подключением ознакомьтесь с условиями обслуживания каждого провайдера.',
- 'opencodex は独立したコミュニティプロジェクトであり、OpenAI、Anthropic などいかなるプロバイダーとも提携・推奨されるものではありません。一部のプロバイダーはサードパーティプロキシ経由のトラフィックを使用するアカウントを制限する可能性があります — 接続前に各プロバイダーの利用規約を確認してください。'
+ 'opencodex は独立したコミュニティプロジェクトであり、OpenAI、Anthropic などいかなるプロバイダーとも提携・推奨されるものではありません。一部のプロバイダーはサードパーティプロキシ経由のトラフィックを使用するアカウントを制限する可能性があります — 接続前に各プロバイダーの利用規約を確認してください。',
+ 'opencodex 是獨立的社群專案，與 OpenAI、Anthropic 或任何其他供應商均無關聯或背書。部分供應商可能限制經第三方代理路由流量的帳號 —— 連線前請查閱各供應商的服務條款。',
)}
diff --git a/docs-site/src/components/SiteJsonLd.astro b/docs-site/src/components/SiteJsonLd.astro
index b6043033c..42b4da7da 100644
--- a/docs-site/src/components/SiteJsonLd.astro
+++ b/docs-site/src/components/SiteJsonLd.astro
@@ -11,12 +11,12 @@
const SITE_URL = 'https://opencodex.me';
interface Props {
- locale?: 'ko' | 'zh-cn' | 'ru' | 'ja';
+ locale?: 'ko' | 'zh-cn' | 'zh-tw' | 'ru' | 'ja';
}
const { locale } = Astro.props;
// Locale path segment (root/English has none) mapped to its BCP-47 tag.
-const langs = { ko: 'ko', 'zh-cn': 'zh-CN', ru: 'ru', ja: 'ja' } as const;
+const langs = { ko: 'ko', 'zh-cn': 'zh-CN', 'zh-tw': 'zh-TW', ru: 'ru', ja: 'ja' } as const;
const homeUrl = locale ? `${SITE_URL}/${locale}/` : `${SITE_URL}/`;
const inLanguage = locale ? langs[locale] : 'en';
@@ -25,6 +25,7 @@ const descriptions = {
en: 'Universal provider proxy for OpenAI Codex & Claude Code — use any LLM with Codex CLI, App, SDK, and Claude Code.',
ko: 'OpenAI Codex & Claude Code를 위한 범용 프로바이더 프록시 — Codex CLI, App, SDK와 Claude Code에서 어떤 LLM이든 사용하세요.',
'zh-CN': '面向 OpenAI Codex 与 Claude Code 的通用 provider 代理 —— 在 Codex CLI、App、SDK 和 Claude Code 中使用任意 LLM。',
+ 'zh-TW': '適用於 OpenAI Codex 與 Claude Code 的通用 provider 代理 —— 在 Codex CLI、App、SDK 和 Claude Code 中使用任意 LLM。',
ru: 'Универсальный прокси провайдеров для OpenAI Codex и Claude Code — используйте любую LLM с Codex CLI, App, SDK и Claude Code.',
ja: 'OpenAI Codex & Claude Code 向けの汎用プロバイダープロキシ — Codex CLI、App、SDK と Claude Code で任意の LLM を使えます。',
} as const;
diff --git a/docs-site/src/content/docs/zh-tw/benchmarks/coding.mdx b/docs-site/src/content/docs/zh-tw/benchmarks/coding.mdx
new file mode 100644
index 000000000..7a765687c
--- /dev/null
+++ b/docs-site/src/content/docs/zh-tw/benchmarks/coding.mdx
@@ -0,0 +1,8 @@
+---
+title: 程式設計基準
+description: 程式設計代理基準快照 — DeepSWE, AA Coding Agent, FrontierCode, FrontierSWE, Program Bench, SWE Marathon.
+---
+
+import FrontierBoards from "../../../../components/FrontierBoards.astro";
+
+
diff --git a/docs-site/src/content/docs/zh-tw/benchmarks/frontend.mdx b/docs-site/src/content/docs/zh-tw/benchmarks/frontend.mdx
new file mode 100644
index 000000000..61997ae99
--- /dev/null
+++ b/docs-site/src/content/docs/zh-tw/benchmarks/frontend.mdx
@@ -0,0 +1,8 @@
+---
+title: 前端基準
+description: 前端程式設計基準快照 — Frontend Code Arena.
+---
+
+import FrontierBoards from "../../../../components/FrontierBoards.astro";
+
+
diff --git a/docs-site/src/content/docs/zh-tw/benchmarks/index.mdx b/docs-site/src/content/docs/zh-tw/benchmarks/index.mdx
new file mode 100644
index 000000000..501124500
--- /dev/null
+++ b/docs-site/src/content/docs/zh-tw/benchmarks/index.mdx
@@ -0,0 +1,16 @@
+---
+title: 基準測試
+description: 公開程式設計代理基準快照 — 每任務成本與能力對比,附各榜單來源說明。
+---
+
+這些是公開榜單的**靜態快照**,手動更新 — 並非 OpenCodex 的即時計量。每個榜單都
+標註了來源、抓取日期和許可說明。只有當榜單中所有行都帶有來源實測的每任務成本時,
+才會顯示得分/$ 排名。
+
+按任務領域檢視:
+
+- [程式設計](./coding/) — DeepSWE, AA Coding Agent, FrontierCode, FrontierSWE, Program Bench, SWE Marathon
+- [前端](./frontend/) — Frontend Code Arena
+- [終端](./terminal/) — Terminal Bench 2.1
+- [安全](./security/) — Cybench
+- [智慧指數](./intelligence/) — AA Intelligence Index
diff --git a/docs-site/src/content/docs/zh-tw/benchmarks/intelligence.mdx b/docs-site/src/content/docs/zh-tw/benchmarks/intelligence.mdx
new file mode 100644
index 000000000..40602a371
--- /dev/null
+++ b/docs-site/src/content/docs/zh-tw/benchmarks/intelligence.mdx
@@ -0,0 +1,8 @@
+---
+title: 智慧指數基準
+description: 綜合智慧指數快照 — AA Intelligence Index.
+---
+
+import FrontierBoards from "../../../../components/FrontierBoards.astro";
+
+
diff --git a/docs-site/src/content/docs/zh-tw/benchmarks/security.mdx b/docs-site/src/content/docs/zh-tw/benchmarks/security.mdx
new file mode 100644
index 000000000..3c75f128b
--- /dev/null
+++ b/docs-site/src/content/docs/zh-tw/benchmarks/security.mdx
@@ -0,0 +1,8 @@
+---
+title: 安全基準
+description: 安全任務基準快照 — Cybench.
+---
+
+import FrontierBoards from "../../../../components/FrontierBoards.astro";
+
+
diff --git a/docs-site/src/content/docs/zh-tw/benchmarks/terminal.mdx b/docs-site/src/content/docs/zh-tw/benchmarks/terminal.mdx
new file mode 100644
index 000000000..6be89bdab
--- /dev/null
+++ b/docs-site/src/content/docs/zh-tw/benchmarks/terminal.mdx
@@ -0,0 +1,8 @@
+---
+title: 終端基準
+description: 終端操作基準快照 — Terminal Bench 2.1.
+---
+
+import FrontierBoards from "../../../../components/FrontierBoards.astro";
+
+
diff --git a/docs-site/src/content/docs/zh-tw/contributing.md b/docs-site/src/content/docs/zh-tw/contributing.md
new file mode 100644
index 000000000..66e04e0c3
--- /dev/null
+++ b/docs-site/src/content/docs/zh-tw/contributing.md
@@ -0,0 +1,181 @@
+---
+title: 貢獻指南
+description: opencodex 的開發環境、結構、約定，以及新增 provider 或 adapter 的方法。
+---
+
+## 環境搭建
+
+```bash
+git clone https://github.com/lidge-jun/opencodex.git
+cd opencodex
+bun install
+bun run dev:proxy # 開發模式代理 API
+bun run dev:gui # 儀表板 dev 伺服器（另一個終端）
+bun run typecheck # bun x tsc --noEmit
+bun run test # bun test ./tests/
+```
+
+`bun run dev` 繼續作為 `bun run dev:proxy` 的別名。儀表板 dev 伺服器使用 `bun run dev:gui`；
+`GET /` 提供的打包儀表板由 `bun run build:gui` 建置到 `gui/dist`。
+
+## 建置與測試命令
+
+根 package 是 Bun-native TypeScript，沒有單獨的 server compile 步驟。請使用儲存庫內的 script，
+確保本機命令與 CI 一致：
+
+```bash
+bun run typecheck # 嚴格 TypeScript 檢查
+bun run test # 完整 tests/ suite
+bun test tests/router.test.ts # 聚焦單個測試檔案
+bun run build:gui # Vite GUI 建置 + package 準備
+bun run privacy:scan # CI 使用的 credential/privacy 掃描
+bun run prepare:package # 重新整理 package launcher/asset
+```
+
+大多數測試是平鋪在 `tests/*.test.ts` 下的 Bun test。`tests/helpers/` 存放共享 fixture，
+`tests/e2e-style/` 存放範圍更廣的原生一致性場景。請在對應 subsystem 的現有測試附近加入聚焦的
+迴歸測試；若改動涉及共享 routing、adapter、config 或 server 行為，還應執行完整 suite。
+
+你正在閱讀的文件站點位於 `docs-site/`（Astro + Starlight）：
+
+```bash
+cd docs-site && bun install && bun dev
+```
+
+## 文件釋出
+
+公開文件釋出到 GitHub Pages：
。
+`.github/workflows/deploy-docs.yml` 會在 `main` push 中 `docs-site/**` 或 workflow 本身發生變化時
+執行，建置 `docs-site` 並部署生成的網站。推送文件變更前請執行：
+
+```bash
+cd docs-site
+bun install --frozen-lockfile
+bun run build
+```
+
+## CI 與釋出
+
+GitHub Actions 有意只保留必要步驟：
+
+- **Cross-platform CI**（`.github/workflows/ci.yml`）會在改動 runtime、test、package、script、
+ TypeScript 或 workflow 檔案的 pull request 與 `main` push 上執行。Bun matrix 覆蓋 Linux、
+ Windows 和 macOS，執行 install、typecheck、test、privacy scan、release-helper build smoke、GUI
+ build 和 `ocx help`。另一個三系統 lane 使用 package 內建 runtime，驗證無需單獨安裝 Bun 也能
+ 完成 npm global install。
+- **Release**（`.github/workflows/release.yml`）只能手動執行。它不是第二套完整 CI；dry-run 或
+ publish 前，精確的 release commit（`GITHUB_SHA`）必須已有成功的 Cross-platform CI run。
+
+釋出請使用 helper：
+
+```bash
+bun run release
# commit/push 版本 bump；publish workflow 預設 dry-run
+bun run release --publish # 確認 CI-gated dry-run 後真正 publish
+bun run release:watch # 觀察最新的 Release workflow run
+```
+
+## 分支
+
+- `dev` — 唯一的整合目標。請在此開啟 pull request。
+- `main` — 僅供釋出。它只能由維護者從 `dev` 提升；請勿對它開啟功能 pull request。
+- `preview` — prerelease train。
+
+承載 Go 原生版本的 `dev2-go` 分支線已經退役，雙軌 carry 政策也隨之結束。其歷史以唯讀方式發佈在
+[lidge-jun/opencodex-go-archive](https://github.com/lidge-jun/opencodex-go-archive)。
+`dev` 上的 Bun-native TypeScript 是唯一的 runtime 線。
+
+歡迎 rebase pull request。把過時分支帶到目前 head 是一般貢獻而非噪音 —— 請在描述中註明來源 commit。
+
+## Pull request
+
+- 目標為 **`dev`**。請勿對 **`main`** 開啟功能或修復 pull request。
+- 從目前 **`dev`** tip 建立分支，而不是從 **`main`**。必填的 **`enforce-target`** 檢查會拒絕
+ head merge base 位於 **`main`** tip 且分支遠落後於 pull request base 的請求（#644 中出現的
+ 失敗模式）。
+- 撰寫真實的描述：說明變更內容與原因的 **Summary**，加上 **Test plan**（或同等實質內容）。空的
+ 內文、只有佔位符的文字，以及使用跳脫 `\n` 而非真實換行的描述都會無法通過檢查。
+- 若標題或描述提到 `gui`，請在描述中附上 UI 變更的螢幕截圖；`enforce-target` 會在描述編輯時
+ 重新執行，直到出現截圖為止。
+- 此 repository 的 workflow 變更使用 **`pull_request_target`**。更新的 enforcement 邏輯只有在
+ workflow 提升到 repository 預設分支後才會生效——與 #631 記錄的相同營運注意事項。
+
+## 專案維護者
+
+目前維護者、其職責，以及 review 與 merge 政策記錄在
+[`MAINTAINERS.md`](https://github.com/lidge-jun/opencodex/blob/main/MAINTAINERS.md)。repository 與
+安全敏感路徑的 GitHub review 所有權宣告在 `.github/CODEOWNERS`。
+
+## 約定
+
+- **僅使用 ES Modules**（`import`/`export`）、TypeScript 和 `strict` mode。保持
+ `bun x tsc --noEmit` 無報錯。
+- **每個檔案最多約 500 行** —— 按職責拆分。`web-search/` 和 `vision/` sidecar 是很好的例子：
+ 小而專注的 module 位於單一 `index.ts` 之後。
+- **在邊界處理非同步錯誤** —— sidecar 不會把例外拋進請求路徑，而會降級成合適的 marker。
+- **Structure SOT** —— 目前維護者不變數放在 `structure/`；公開使用者流程放在 `docs-site/`；
+ 歷史調查/診斷記錄放在 `docs/`。
+- **保留 export** —— 其他 module 可能依賴它們。
+
+## 向目錄中新增 provider
+
+所有 provider picker 與 seed 都來自 canonical registry（`src/providers/registry.ts`）：
+
+```ts
+{
+ id: "my-provider",
+ label: "My Provider",
+ baseUrl: "https://api.example.com/v1",
+ adapter: "openai-chat",
+ authKind: "key",
+ dashboardUrl: "https://example.com/keys",
+ models: ["model-a", "model-b"],
+ defaultModel: "model-a",
+ noVisionModels: ["model-a"], // text-only models → vision sidecar describes images
+},
+```
+
+`src/providers/derive.ts` 會把該條目提供給 `ocx init`、`ocx provider`、儀表板 preset、API-key
+登入和 OAuth config seed。`enrichProviderFromCatalog()` 會把模型 metadata 與 capability 分類複製到
+儲存的 provider 設定。OAuth protocol 實作仍位於 `src/oauth/`；只有 registry metadata 並不會
+自動形成 OAuth flow。
+
+### 權威 preset 所需的證據
+
+registry 條目是一項被維護的承諾：opencodex 會把使用者的 API key 送到這個目的地。因此 preset
+需要一手來源證據，而不只是可運作的程式碼路徑。新增或提升 provider 的 pull request 必須在描述中
+提供以下全部內容：
+
+- **已文件化的 OpenAI 相容端點。** 附上供應商自己的 chat endpoint API 參考連結；當條目設定
+ `liveModels: true` 時，也要附上其認證模型探索端點（通常是 `GET /v1/models`）的連結。通過的
+ fixture 測試不能取代它：那只證明我們的程式碼結構，不能證明上游契約。
+- **服務條款與營運法人。** 空白或佔位符的法律頁面無法證明誰在營運該端點，或使用者流量依什麼
+ 條款處理。
+- **aggregator 的轉售或路由授權。** 販售 Claude、GPT、Gemini 或其他第三方模型存取的 gateway
+ 應出示其路由授權。使用者把內建 preset 視為一條受維護的路線，而不是未經驗證的轉售商。
+- **具名的維護負責人。** 說明 base URL、認證或目錄契約變更時由誰更新該 preset，以及故障如何
+ 回報。
+- **可引用的驗證日期。** 記錄一手來源與檢查日期，方式與 `src/providers/free-directory.ts` 中的
+ `lastVerified` 相同。未經驗證的列卻加上了日期，等於宣稱一份誰都沒產生的 provenance。
+
+歡迎貢獻者新增自己的服務，目前多個 preset 就是這樣來的。請在 pull request 描述中揭露關聯，讓
+reviewer 可以衡量；有關聯不代表會被拒絕，也不會降低證據門檻。
+
+當證據不完整時，誠實的歸屬是 `src/providers/free-directory.ts` 的 reference row，而不是
+canonical registry。Directory row 帶有明確的 `verification` 等級（`official`、`primary`、
+`unverified`）且是惰性的：使用者仍可透過自訂 OpenAI-compatible flow 使用該服務，而 opencodex
+不會宣傳一個無法背書的 preset。證據齊全後再把該 row 提升到 registry。
+
+## 新增 adapter
+
+在 `src/adapters/` 中實作 `ProviderAdapter`（參見
+[Adapters](/zh-tw/reference/adapters/)），在 `src/server/adapter-resolve.ts` 註冊其名稱，
+並把輸出橋接成內部 `AdapterEvent`。圖像處理請複用 `image.ts`；普通 streaming/tool call 以
+`openai-chat.ts` 為參考。只有 adapter 自己負責 transport retry 時才使用 `fetchResponse`；Cursor
+這類真正的雙向 transport 應使用 `runTurn`。在 `tests/` 中新增聚焦測試；如果 factory 屬於 public
+package API，還要從 `src/index.ts` export。
+
+## 在聲稱完成前先驗證
+
+先執行能證明改動的最小命令：型別檢查用 `bun run typecheck`，行為檢查用聚焦的
+`bun test tests/.test.ts` 或 runtime probe，然後再執行適合影響範圍的更寬 gate。
+opencodex 傾向於小而可驗證的 commit，而不是大批次改動。
diff --git a/docs-site/src/content/docs/zh-tw/contributing/pr-quality.md b/docs-site/src/content/docs/zh-tw/contributing/pr-quality.md
new file mode 100644
index 000000000..00f20be8e
--- /dev/null
+++ b/docs-site/src/content/docs/zh-tw/contributing/pr-quality.md
@@ -0,0 +1,47 @@
+---
+title: Pull request 品質合約
+description: OpenCodex pull request 的審查就緒門檻、貢獻者責任、信任通道與關閉政策。
+---
+
+## 你不需要先取得許可才能修東西
+
+針對你實際遇到的 bug 提出的非計畫 pull request 是受歡迎的。這個專案有幾個很好的修正正是這樣誕生的——路由模型在工具呼叫後卡住、供應商送出錯誤的模型參數、圖片從工具結果中被扁平化（flattened）。這些都不是從規劃討論開始的；如果 gate 要求先有規劃討論，這些修正全都會消失。
+
+先開 issue 對較大型或偏設計的工作確實有幫助，事先就方法達成共識，可以避免你蓋出錯誤的東西。那是建議，不是提交門檻。
+
+## 一個就緒的 pull request 代表什麼
+
+把 PR 標記為可審查，代表這個變更是完整、已理解、且已測試的。開啟它並不代表把分支的責任轉移給維護者。
+
+作者預期要理解每一行變更、為任何驗證聲明指名確切的指令與結果、為行為變更補上聚焦的回歸測試，並保持在場處理 CI 與 review 的回饋。維護者負責找出問題；他們不負責修補貢獻者的分支、補寫缺失的測試，或把自動化發現轉成你的 patch。
+
+沒有指名指令與結果的「有測試」或「CI 通過」不是證據。
+
+## 自動化 gate
+
+有三個決定性的檢查會在人工作業之前執行，每個失敗訊息都會確切告訴你該改什麼：
+
+- **PR 品質（`enforce-target`）。** Pull request 必須以 `dev` 為目標，並帶有真正的描述：變更內容與原因的 **Summary**，加上 **Test plan**（或同等實質內容）。當 diff 更動 `gui/` 下的檔案，或 GitHub 對大型 diff 回傳不完整的變更檔清單時，描述必須包含 UI 變更的截圖；檢查會讓 PR 維持 draft 並留言，直到截圖出現。不完整的檔案清單會保守地視為 GUI 變更。維護者可以針對 `gui/` 變更、GUI 路徑分類誤判、或不完整檔案清單的誤判，加上 `gui-screenshot-waived` label 來豁免截圖要求；新增或移除該 label 會立即重新評估 gate。舊式維護者留言（例如「no gui changes」）在下次 PR 事件時仍會為相容性而辨識，但留言本身不再觸發這個特權 PR gate。貢獻者不能自行豁免截圖要求。
+ 沒有 repository push 權限的貢獻者 PR 會以 draft 開啟，並維持 draft 直到描述中的四個格子的 review-ready 檢查清單完成：本機 CI 通過、分支位於最新 `dev` commit、所有正確的 Codex 與 CodeRabbit 發現都已修正、以及 ready-for-review 確認。當每個格子都勾選後，檢查會把 PR 標記為可審查，並通知 `MAINTAINERS.md` 中列出的維護者（不含作者）。gate 的狀態與「該做什麼」集中在單一 bot 留言中，每次執行都會重寫，所以只需看一個地方。完成綁定在 PR head 所指的確切 commit：如果之後又推出新 commit，gate 會把 PR 移回 draft、重設檢查清單與維護者通知，並要求你針對最新程式碼再次測試並勾選。重新定位到 `dev` 會自動清除錯誤分支訊息，並被 gate 記住；draft 會一直持續到檢查清單完成。
+ 在接受完成之前，gate 會驗證它能自行檢查的檢查清單聲明：分支必須位於最新 `dev` commit 或落後最多 10 個 commit，而且目前 head 上所有由 review bot 撰寫的 Codex 與 CodeRabbit review thread 都必須已解決（其他作者未解決的 thread 不會阻擋）。本機 CI 的格子只是作者的 attestation——fork 貢獻者無法啟動 repository CI，必須由維護者啟動——所以 gate 永遠不會反駁它；新的 push 仍會重設每個格子。落在 diff 範圍之外、且只在目前 head 的 review body 中回報的 CodeRabbit 發現，在 bot review thread 開啟期間會計入未解決數；解決所有 bot thread 即可清除該格子。被反駁的聲明會取消勾選對應的格子，並讓 PR 維持 draft。當檢查清單完成且所有 gate 都綠燈時，gate 會加上 `review-ready` label，作為就緒時刻的可見狀態標記。
+ CodeRabbit 的狀態留言編輯不會觸發 PR gate。CodeRabbit 成功的 `CodeRabbit` commit status 會透過 `status` 事件喚醒受信任的預設分支 gate。gate 將該 status SHA 對應到確切一個目前 head 仍相符的 open PR，然後在變更檢查清單、label、留言或 draft 狀態之前，重新讀取即時的 review thread 與 review body。模糊或過時的 SHA 關聯會被忽略，且不會以 gate 的具寫入權限 token 執行任何 PR head 程式碼。
+
+- **Hygiene。** 行為變更需要測試；新增 lint 或 type suppression、聚焦或跳過的測試、空的 catch 區塊、編輯產生的輸出，以及未隨 manifest 一起變更的 lockfile，每項都需要明確的核准 label。僅對原始檔做留言層級的變更不算行為變更，也不需要測試。
+- **跨平台 CI。** 每個 pull request 的測試套件在 Linux 上分片執行，並在 macOS 上完整執行。Windows 在釋出邊界執行——即提升到 `main` 或 `preview` 時——所以慢速或不穩定的 Windows runner 不能決定你的 pull request 何時變綠。
+ 這對**每個** pull request 都執行，無論其 base 分支為何——包括 base 是另一個 open PR head 的 stacked child。由 `paths:` filter，而非 base 分支，決定 jobs 是否執行：只碰 docs 或 `devlog/` 的 PR 不會佇列任何 job。
+
+- **Type label。** `label` 檢查會從你的 PR title 推導出 `bug` / `enhancement` / `documentation` / `chore`。沒有可辨識前綴的 title（例如 `stack 3/5: …`）會回退到 PR 的 commits，通常仍是慣例格式；`chore` 家族的 commits（`test:`、`ci:`、`refactor:`）不能推翻 `fix:` 或 `feat:`。真正混合多種型別的 PR 會保持未標記而非猜測，而且人工設定的 label 永不被覆寫。
+
+CodeRabbit 會 review 每個 PR，其發現僅供參考。它說對的就照做；說錯的就說明原因。它不會阻擋 merge。
+
+### 工作流程變更何時生效
+
+`enforce-target` 與 `label` 使用受信任的預設分支自動化。PR gate 在 `pull_request_target` 與 CodeRabbit `status` 事件上執行，兩者都從 repository 的預設分支載入；因此具寫入權限的行為只會在 gate 修訂版提升到 `main` 之後改變。跨平台 CI workflow 在 `pull_request` 上執行，一旦它位於被定位的分支上就立即生效。
+
+## 受贊助的介面
+
+驗證、憑證處理、GitHub Actions workflows、釋出自動化與依賴安裝，都需要維護者贊助該變更（`maintainer-sponsored`）才能 merge。這些介面上的錯誤 merge 代價高昂且難以回復，這是它們成為僅有的以此方式 gate 的介面的原因。其餘一切開放。
+
+## 當 pull request 被關閉時
+
+停滯且帶著未解決 review 回饋的 PR 可能被關閉，並會清楚陳述原因。關閉不是對貢獻者的判決：一旦陳述的原因解決，就重新開啟它，或用乾淨的 PR 取代。若原因不清楚，請詢問。
diff --git a/docs-site/src/content/docs/zh-tw/getting-started/for-agents.md b/docs-site/src/content/docs/zh-tw/getting-started/for-agents.md
new file mode 100644
index 000000000..174f4447f
--- /dev/null
+++ b/docs-site/src/content/docs/zh-tw/getting-started/for-agents.md
@@ -0,0 +1,90 @@
+---
+title: Agent 快速上手
+description: 從 agent 驅動或腳本化終端機安裝並操作 opencodex，而不跨越使用者同意邊界。
+---
+
+本頁面是為從終端機工作的 AI agent 或腳本使用者而寫。它著重於指令、離開狀態，以及自動化與需要使用者同意的行動之間的邊界。若要人工引導的逐步說明，請用[快速入門](/zh-tw/getting-started/quickstart/)。儀表板仍可用於互動式設定；見[網頁儀表板](/zh-tw/guides/web-dashboard/)。
+
+## 設定 opencodex
+
+安裝已發布的套件，並確認 `ocx` 在 `PATH` 上：
+
+```bash
+npm install -g @bitkyc08/opencodex
+ocx --version
+```
+
+選擇一種執行代理的方式：
+
+```bash
+# 前景：佔用此終端機直到停止。
+ocx start
+
+# 背景：安裝或更新服務，然後啟動它。
+ocx service
+```
+
+在互動終端機執行 `ocx init`。若 `ocx start` 佔用了前景，請用第二個終端機：
+
+```bash
+ocx init
+```
+
+精靈會寫入 `$OPENCODEX_HOME/config.json`（通常為
+`~/.opencodex/config.json`）。它也可將代理位址注入 Codex 的 `config.toml`，並安裝可選的 Codex 自動啟動 shim。`ocx init` 永不啟動代理。若要完全非互動的設定，請改用下方所示的 `ocx provider add` 設定供應商，而非驅動精靈。
+
+:::caution[GitHub 加星同意]
+若你是 agent，絕不要代使用者回答 GitHub 加星提示，也不要代為呼叫 `gh`、GitHub 的加星 API 或
+`POST /api/github/star`；加星會花費使用者身分並需要單獨的明確同意。在 agent 驅動的執行中，CLI 會抑制提示且不寫入
+`.star-prompted`，而管理 API 回傳 `403 agent_consent_required` — 請勿繞過任一防護。詢問使用者一次，僅在明確同意後加星，若他們說否或不回答，則什麼都不做且不再詢問。
+:::
+
+## 檢查無頭安裝
+
+在腳本與 agent 執行中使用這些唯讀檢查：
+
+```bash
+ocx status
+ocx doctor
+ocx health --json
+```
+
+`ocx status` 回報代理與服務狀態。`ocx doctor` 診斷本機環境、網路、Codex 執行階段與帳號健康問題。`ocx health` 在代理健康時離開 `0`，否則 `1`；`--json` 回傳結構化輸出。
+
+由管理 API 支援的指令（例如 `ocx combo set`）會聯繫即時代理。若找不到即時代理或 API 不可達，CLI 將其視為 `503` 失敗並以非零離開。重試前請啟動前景代理或背景服務。完整指令與端點介面請見
+[CLI 參考](/zh-tw/reference/cli/)與[管理 API](/zh-tw/reference/management-api/)。
+
+## 不透過儀表板新增供應商與組合
+
+Registry 供應商可依名稱新增。例如，以下新增 Anthropic API-key 預設並設為預設供應商：
+
+```bash
+ocx provider add anthropic-apikey \
+ --api-key "$ANTHROPIC_API_KEY" \
+ --set-default
+```
+
+`ocx provider add` 寫入本機設定。若已有即時代理在執行且你想立即將模型同步到 Codex，請加上 `--sync`；否則稍後執行 `ocx sync`。不在 registry 中的自訂供應商需要同時提供 `--adapter` 與 `--base-url`。
+
+所有目標供應商設定完成且代理執行後，建立一個 failover combo：
+
+```bash
+ocx combo set main \
+ --targets anthropic/claude-opus-4-8,openai/gpt-5.6-sol \
+ --strategy failover
+```
+
+目標使用 `provider/model` 語法並以逗號分隔。產生的虛擬模型為
+`combo/main`。關於策略、權重、sticky 路由與失敗行為，請見[組合](/zh-tw/guides/combos/)。
+
+## 遠端與 LAN 綁定
+
+預設的回送綁定不需要 API token。非回送綁定（例如 `0.0.0.0`）需要
+`OPENCODEX_API_AUTH_TOKEN`；代理在沒有它時拒絕啟動。請在 `ocx start` 前，或在 `ocx service install` 前設定該變數，以便服務接收它：
+
+```bash
+export OPENCODEX_API_AUTH_TOKEN="your-secret-token"
+ocx service install
+```
+
+客戶端隨後必須認證其管理與模型請求。在將 opencodex 暴露到本機以外之前，請閱讀[設定](/zh-tw/reference/configuration/)中的遠端存取規則。
diff --git a/docs-site/src/content/docs/zh-tw/getting-started/how-it-works.mdx b/docs-site/src/content/docs/zh-tw/getting-started/how-it-works.mdx
new file mode 100644
index 000000000..14934a296
--- /dev/null
+++ b/docs-site/src/content/docs/zh-tw/getting-started/how-it-works.mdx
@@ -0,0 +1,102 @@
+---
+title: 運作原理
+description: opencodex 的完整請求生命週期 —— 解析、路由、適配、橋接與 streaming。
+---
+
+import { Steps } from '@astrojs/starlight/components';
+
+Codex 使用 OpenAI **Responses API**。opencodex 接收透過 HTTP 與 Server-Sent Events 傳送的
+`POST /v1/responses`，也可選擇在同一路徑上啟用 WebSocket 升級。它會把請求轉換為 provider
+的 wire 格式，再把回應轉換回 Responses 事件，因此 Codex 無需知道自己正在與非 OpenAI 模型通訊。
+
+```
+ ┌──────────────────────────── opencodex ────────────────────────────┐
+ │ │
+ Codex ──▶ │ parser ──▶ router ──▶ [vision] ──▶ adapter ──▶ provider │ ──▶ Codex
+ (/v1/ │ │ │ │ │ │ │ (SSE / WS)
+ responses)│ OcxParsed provider describe buildRequest parseStream │
+ │ Request +adapter images + fetch AdapterEvent[] │
+ │ │ │ │
+ │ [web-search loop] bridge ─▶ SSE │
+ └─────────────────────────────────────────────────────────────────────┘
+```
+
+
+
+## Codex 認證帳號選擇
+
+當選中的供應商是 ChatGPT/Codex 直通時，opencodex 可在請求轉發到上游前，先從已儲存的帳號池中選帳。
+規則刻意拆成兩部分：
+
+- **既有 thread id 維持親和性。** thread 會綁定啟動它的帳號世代，因此長時間的 SSH、tmux 或
+ 行動裝置掛載的 Codex session 會繼續使用同一個帳號，而不是在對話中途被重新平衡。
+- **新 session 可以重新平衡。** 對新 thread，opencodex 會比較 5 小時、每週與 30 天視窗的已知配額
+ 使用量，略過需要重新認證或處於 cooldown 的帳號；當作用中帳號跨過設定門檻時，可切換到使用量較低
+ 的合格帳號。
+- **配額與失敗訊號會回饋路由。** 儀表板可用 `GET /api/codex-auth/accounts?refresh=1` 強制重新整理
+ 配額；成功的上游回應會擷取配額標頭，429 會讓帳號進入 cooldown，401/403 則標記為需重新認證。
+
+## Sub-agent 模型選擇
+
+全新安裝會透過 `subagentModels` 在 Codex 的 sub-agent 選擇器中優先顯示 `gpt-5.5`、GPT-5.6
+Sol/Terra/Luna 三個模型和 `gpt-5.4-mini`。儀表板可以從原生或已路由模型中重新排序或替換最多
+五個條目。對於 v1 協作請求，可選的 `injectionModel` 與 `injectionEffort` 會新增開發者指令，
+告訴 `spawn_agent` 應使用哪個模型和 reasoning effort；v2 請求保留 Codex 原生的多代理指引。
+
+## 生命週期
+
+
+
+1. **解析** —— `responses/parser.ts` 使用 Zod schema(`responses/schema.ts`)校驗請求,
+ 並將其降級為內部的 `OcxParsedRequest`:系統提示詞、一份規範化的訊息列表
+ (文字、圖像、工具呼叫、工具結果)、工具定義、生成選項,以及諸如 `_webSearch`(請求了託管的網路搜尋)
+ 和 `_structuredOutput`(設定了 JSON schema /
+ JSON 物件的 `text.format`)等特性標誌。圖像會被保留為真正的內容部分 —— 絕不會被內聯為
+ base64 文字。
+
+2. **路由** —— `router.ts` 按固定的優先順序將請求的模型 id 對映到一個已設定的 provider：
+ 顯式的 `provider/model` → provider 的 `defaultModel` → 內建字首模式
+ (`claude-`、`gpt-`、`o1-`/`o3-`/`o4-`、`llama-`/`mixtral-`/`gemma-`) → provider 的 `models[]` →
+ `defaultProvider` 回退。參見 [模型路由](/zh-tw/guides/model-routing/)。
+
+3. **認證** —— 對於 `oauth` 型別的 provider,opencodex 會換入一個全新、自動重新整理的 access
+ token 作為 bearer key,從而讓現有的 adapter 無需改動即可完成認證。對於 ChatGPT/Codex 帳號池，
+ `codex/auth-context.ts` 會先解析帳號；若必要的池憑證不可用，直通 adapter 會拒絕繼續。
+
+4. **Vision sidecar（可選）** —— 如果已路由的模型被列在 `provider.noVisionModels` 中，且
+ 請求攜帶了圖像，opencodex 會透過已設定的 vision sidecar 描述每張圖像並替換為文字，讓純文字
+ 模型仍可對圖像進行推理。後端可選 `openai`（ChatGPT 登入）或 `anthropic`（OAuth）；未設定時
+ 會自動選擇，顯式 `anthropic` 但無可用憑證時會關閉失敗。
+ 參見 [Sidecar](/zh-tw/guides/sidecars/)。
+
+5. **直通快速路徑** —— 對於 Responses 直通 adapter（`openai-responses` 或 `azure-openai`），
+ opencodex 會保留 Responses body，只執行必要的路由與相容性改寫，然後直接轉發 provider 回應，
+ 不再轉換為 `AdapterEvent`。
+
+6. **網路搜尋 sidecar（可選）** —— 如果 Codex 啟用了託管的 `web_search`，但已路由的模型
+ 並非 OpenAI，opencodex 會暴露一個合成的 `web_search` 函式工具，並在一個小型
+ agentic 迴圈中執行該模型；真實搜尋由所選 sidecar 後端執行（`openai` 預設以 ChatGPT 登入
+ 呼叫 `gpt-5.6-luna`，或 `anthropic` OAuth），再將結果作為工具結果注入回去。
+
+7. **壓縮（按需）** —— Codex v1 會呼叫 `POST /v1/responses/compact`，v2 則在 Responses turn 中
+ 加入 `compaction_trigger`。原生直通路由會把壓縮請求傳送到上游；已路由模型則在停用工具的
+ 情況下執行摘要，並回傳 Codex 所需的替代歷史記錄格式。
+
+8. **適配** —— 否則,所選 adapter 的 `buildRequest()` 會以 provider 的原生格式生成上游 HTTP 請求
+ (URL、headers、body),由 opencodex 對其執行 `fetch`。
+
+9. **橋接** —— adapter 的 `parseStream()`(或 `parseResponse()`)會產出內部的 `AdapterEvent`
+ (text、reasoning、tool-call start/delta/end、done、error)。`bridge.ts` 會將該流轉換回
+ Responses SSE 事件 —— `response.output_text.delta`、`response.reasoning_summary_text.delta`、
+ `response.function_call_arguments.delta`、`response.completed` 等等。啟用 WebSocket 時，同樣的
+ event payload 會作為 text frame 傳送。
+
+
+
+## 為什麼是代理而不是 fork 一份 Codex?
+
+Codex 把 Responses API 硬編碼在內部。透過在協議邊界處進行翻譯,opencodex 可以與
+Codex 的 **CLI、App 和 SDK** 無改動地協作,能在 Codex 更新後繼續工作,並讓你能夠按請求切換 provider
+而無需改動 Codex 本身。這種翻譯是雙向且忠於 streaming 的:
+推理摘要、MCP 工具名稱空間、freeform(`apply_patch`)工具,以及 `tool_search` 發現
+都能正確地往返。關於逐事件的對映,參見 [架構參考](/zh-tw/reference/architecture/)。
diff --git a/docs-site/src/content/docs/zh-tw/getting-started/installation.md b/docs-site/src/content/docs/zh-tw/getting-started/installation.md
new file mode 100644
index 000000000..23b36b97d
--- /dev/null
+++ b/docs-site/src/content/docs/zh-tw/getting-started/installation.md
@@ -0,0 +1,97 @@
+---
+title: 安裝
+description: 安裝 opencodex(ocx)代理及其前置條件,並驗證它能夠執行。
+---
+
+安裝 opencodex 後會得到 `ocx` 和 `opencodex` 兩個等價命令，它們都指向同一個基於 Bun 的
+小型本機 HTTP 伺服器。模型請求會發往路由所選的 provider；當已路由模型需要時，可選的
+vision 和網路搜尋 sidecar 也可以使用你的 ChatGPT 登入憑證。
+
+## 前置條件
+
+| 要求 | 原因 |
+| --- | --- |
+| **[Node](https://nodejs.org) ≥ 18** | `ocx` 執行在 Bun 執行環境上，但執行環境會在 `npm install` 時自動打包，你**無需**自己安裝 Bun。 |
+| **[OpenAI Codex](https://openai.com/codex)**(CLI、App 或 SDK) | opencodex 所代理的用戶端。opencodex 會寫入 `$CODEX_HOME/config.toml`（預設 `~/.codex/config.toml`）。 |
+| 一個 provider 帳號或 API key | Anthropic、xAI、Kimi、Ollama Cloud、OpenRouter、OpenAI API key、一個 OpenAI 相容端點,或你的 ChatGPT 登入憑證。 |
+
+## 安裝
+
+```bash
+npm install -g @bitkyc08/opencodex
+```
+
+:::note[npm 攔截了 bun postinstall？]
+較新的 npm 可能會攔截 bun 的 postinstall 指令碼（`npm warn install-scripts ...
+blocked because they are not covered by allowScripts`），導致捆綁的 Bun
+執行環境未能就緒。請允許 bun 指令碼後重新安裝。注意 npm 警告給出的縮寫命令
+缺少包名，會把目前目錄重新安裝進去，請始終顯式寫上包名：
+
+```bash
+npm install -g --allow-scripts=bun @bitkyc08/opencodex
+
+# 如果最初是用 sudo 安裝的，請繼續使用 sudo：
+sudo npm install -g --allow-scripts=bun @bitkyc08/opencodex
+```
+
+:::
+
+確認兩個命令都已加入 `PATH`：
+
+```bash
+ocx --version
+opencodex --version
+```
+
+### 釋出渠道
+
+穩定的 `latest` 渠道已經包含 ChatGPT、OpenAI API key、OpenRouter 以及實驗性 Cursor 路由所需的
+GPT-5.6 Sol/Terra/Luna 目錄資訊，但這些條目本身不會授予上游模型權限。只有在測試尚未正式釋出的
+opencodex 建置時，才需要使用 preview 渠道：
+
+```bash
+npm install -g @bitkyc08/opencodex@preview
+ocx update --tag preview
+```
+
+## 從原始碼執行
+
+若要對 opencodex 本身進行開發:
+
+```bash
+git clone https://github.com/lidge-jun/opencodex.git
+cd opencodex
+bun install
+bun run dev:proxy # 以開發模式啟動代理 API (src/cli/index.ts start)
+bun run dev:gui # 啟動儀表板 dev 伺服器 (另一個終端)
+```
+
+`bun run dev` 作為 `bun run dev:proxy` 的別名保留。代理 API 暴露 `/healthz`、`/v1/responses`、
+`/api/*`;只有在 `bun run build:gui` 生成 `gui/dist` 之後,`GET /` 才會提供打包後的儀表板。
+開發儀表板時,請用 `bun run dev:gui` 單獨執行前端。
+
+## 會建立哪些內容
+
+opencodex 狀態檔案位於 `$OPENCODEX_HOME`（預設 `~/.opencodex`），Codex 整合檔案位於
+`$CODEX_HOME`（預設 `~/.codex`）。
+
+| 路徑 | 用途 |
+| --- | --- |
+| `$OPENCODEX_HOME/config.json` | 你的 provider、預設 provider、埠及選項。 |
+| `$OPENCODEX_HOME/ocx.pid` | 正在執行的代理的 PID（單例項保護）。 |
+| `$OPENCODEX_HOME/runtime-port.json` | 目前 PID、主機名和埠，包括自動選擇的備用埠。 |
+| `$OPENCODEX_HOME/auth.json` | 執行 `ocx login` 後儲存的 OAuth 憑證。 |
+| `$OPENCODEX_HOME/catalog-backup*.json` | opencodex 修改 Codex 模型目錄前建立的備份。 |
+| `$CODEX_HOME/config.toml` | 僅監聽迴環地址時，opencodex 會新增由自身標記管理的根級 `openai_base_url`；監聽非迴環地址時，則使用 `model_provider = "opencodex"` 和 `[model_providers.opencodex]`，以便 Codex 傳送 API 認證 header。 |
+| `$CODEX_HOME/opencodex.config.toml` | 與 Codex 主設定一同寫入的備用/參考 profile。 |
+| `$CODEX_HOME/opencodex-catalog.json` | 供 Codex 使用的原生與已路由模型目錄。 |
+
+:::note
+opencodex 絕不會刪除你的 Codex 設定。每次注入都是可逆的 —— `ocx stop`、`ocx restore`
+或 `ocx eject` 會精確剝離 opencodex 所新增的那些行,並恢復原生 Codex。
+:::
+
+## 下一步
+
+繼續閱讀 [快速入門](/zh-tw/getting-started/quickstart/) 以設定你的第一個 provider,
+或閱讀 [運作原理](/zh-tw/getting-started/how-it-works/) 瞭解其架構。
diff --git a/docs-site/src/content/docs/zh-tw/getting-started/quickstart.md b/docs-site/src/content/docs/zh-tw/getting-started/quickstart.md
new file mode 100644
index 000000000..202c50624
--- /dev/null
+++ b/docs-site/src/content/docs/zh-tw/getting-started/quickstart.md
@@ -0,0 +1,105 @@
+---
+title: 快速入門
+description: 設定你的第一個 provider,用三條命令讓 OpenAI Codex 透過 opencodex 進行路由。
+---
+
+本指南將帶你從全新安裝,一路走到用一個非 OpenAI 模型執行 Codex。
+
+## 1. 執行設定嚮導
+
+```bash
+ocx init
+```
+
+`ocx init` 會引導你完成:
+
+1. **選擇 provider** —— 從內建 registry 的 79 個預設中選擇一個，或選擇 `custom` 手動輸入
+ base URL 和 adapter。
+2. **API key** —— 貼上一個 key,或引用一個環境變數,例如 `${ANTHROPIC_API_KEY}`。
+3. **預設模型** —— 對於 API key、本機和 custom provider，可接受預設值或輸入模型 id。
+4. **代理埠** —— 預設為 `10100`。
+5. **注入到 Codex？** —— 在通常的迴環地址設定中，opencodex 會在
+ `$CODEX_HOME/config.toml`（預設 `~/.codex/config.toml`）根級新增 `openai_base_url`，讓 Codex
+ 內建的 `openai` provider 指向代理。監聽遠端或 LAN 地址時，則改用帶 API 認證 header 的專用 provider 條目。
+6. **安裝自動啟動 shim？** —— 啟用後，每次啟動 `codex` 都會先執行 `ocx ensure`。
+
+結果會儲存到 `$OPENCODEX_HOME/config.json`（預設 `~/.opencodex/config.json`）。
+
+:::note[GPT-5.6 釋出條目]
+目前的穩定版本會為 ChatGPT 直通、OpenAI API key、OpenRouter 以及實驗性 Cursor adapter
+預置 GPT-5.6 Sol/Terra/Luna。只有該上游帳號具備權限時才能實際呼叫。OpenAI API key 與
+OpenRouter 預設會宣告 372,000 token 的可用 context window；Cursor 則保留自身 adapter 的
+後設資料。
+:::
+
+## 2. 啟動代理
+
+```bash
+ocx start # 預設埠 10100
+ocx start --port 8080
+```
+
+啟動時,opencodex 會:
+
+- 將其 PID 寫入 `~/.opencodex/ocx.pid`(並拒絕重複啟動),
+- 在 provider 支援時發現即時模型，並**把原生與已路由條目同步進 Codex 的模型目錄**，以及
+- 在 `http://localhost:/v1` 上監聽。
+
+如果請求的埠已被佔用，`ocx start` 會選擇一個空閒埠，將其寫入 `runtime-port.json`，並更新
+Codex 設定以使用實際監聽埠。
+
+檢查它:
+
+```bash
+ocx status
+ocx gui # 在實際監聽埠開啟儀表板
+```
+
+## 3. 使用 Codex
+
+Codex 現在會透明地與 opencodex 通訊:
+
+```bash
+codex "Refactor this function for readability"
+```
+
+若要指定某個已路由的模型,請使用 Codex 模型選擇器所顯示的 `provider/model` 形式:
+
+```bash
+codex -m "anthropic/claude-opus-5" "Explain this stack trace"
+codex -m "ollama-cloud/glm-5.2" "Write a SQL migration"
+```
+
+## 選擇 sub-agent 模型（可選）
+
+新設定會讓 Codex 的 sub-agent 選擇器包含五個原生模型：`gpt-5.5`、`gpt-5.6-sol`、
+`gpt-5.6-terra`、`gpt-5.6-luna` 和 `gpt-5.4-mini`。開啟 `ocx gui` 即可替換或重新排序最多五個
+原生或已路由模型。儀表板也可以設定一個首選 sub-agent 模型及 reasoning effort。參見
+[子代理介面](/zh-tw/guides/sub-agent-surface/) 選擇 v1/base/v2，並了解指引、原生預設與回退
+何時生效。
+
+## 登入而非貼上 key
+
+部分 provider 支援真正的帳號登入(OAuth,自動重新整理):
+
+```bash
+ocx login xai # 也可使用 anthropic、kimi、kiro、google-antigravity、cursor
+ocx logout xai
+```
+
+OpenAI 本身**無需 key** —— 預設 provider 會直接轉發你現有的 `codex login` 憑證
+（參見 [Providers](/zh-tw/guides/providers/)）。
+
+## 停止與恢復
+
+```bash
+ocx stop # 停止代理並恢復原生 Codex
+ocx restore # 不停止代理，僅恢復原生 Codex（別名：ocx eject）
+ocx restore back # 讓 Codex 再次使用仍在執行的代理
+```
+
+## 下一步
+
+- [運作原理](/zh-tw/getting-started/how-it-works/) —— 每個請求都發生了什麼。
+- [Provider](/zh-tw/guides/providers/) —— 各種認證方式。
+- [設定](/zh-tw/reference/configuration/) —— 完整的 `config.json` 參考。
diff --git a/docs-site/src/content/docs/zh-tw/guides/claude-code.md b/docs-site/src/content/docs/zh-tw/guides/claude-code.md
new file mode 100644
index 000000000..9fae612f3
--- /dev/null
+++ b/docs-site/src/content/docs/zh-tw/guides/claude-code.md
@@ -0,0 +1,442 @@
+---
+title: Claude Code 指南
+description: 在 Claude Code 中使用任意已路由模型——opencodex 在同一埠提供 Anthropic Messages API 和閘道器模型發現功能。
+---
+
+opencodex 在 `/v1/responses` 之外還提供 `POST /v1/messages`（以及 `count_tokens`），因此 Claude
+Code 可以使用每一個已路由的供應商——包括 OAuth 登入、帳號池、金鑰故障轉移和 sidecar——
+而無需進行任何額外的身分驗證設定。
+
+## Claude OAuth 帳號池（實驗性）
+
+你可以透過 Providers 儀表板登入多個 Claude 帳號（`ocx login anthropic` / add-account）。預設
+每個請求只使用**作用中**帳號。
+
+**實驗性、opt-in** 的 Claude 帳號池（`anthropicAccountPool.enabled`）會在這些 OAuth 帳號之間加入
+sticky session affinity 與 429 冷卻故障轉移。僅對**新**工作階段，`anthropicAccountPool.strategy`
+會在合格帳號之間選擇：`quota`（預設）在用量高於 `autoSwitchThreshold` 時挑選已知 5 小時用量最低者；
+`round-robin` 平均分散（`stickyLimit`，預設 `1`）；`fill-first` 一直使用作用中帳號直到冷卻、重新認證
+或達到閾值，然後前進。它**預設關閉**、會在 GUI 顯示警告，而且尚未經過實戰驗證——Anthropic 可能
+限制看起來像自動輪換的帳號；輪換並不能保護你免受供應商執行機制的處置。
+
+啟用時的營運契約：
+
+- 上游 **429** 會讓該帳號冷卻（有 `Retry-After` 時使用它，否則用預設 backoff）、清除其 affinity，
+ 並可能在同一個請求內輪換到另一個合格帳號（有上限）。
+- Affinity 是**程序本機**的（proxy 重啟後就會遺失）。
+- **401/403** 憑證失敗會隔離該帳號（`needsReauth`），直到重新認證前都不會參與選擇。
+- 如果每個合格帳號都在冷卻，proxy 會回傳 **429**（不是 401），並在已知時附上 `Retry-After`。
+
+請見 [Configuration](/zh-tw/reference/configuration/#anthropicaccountpool-experimental)。
+
+## 快速入門
+
+```bash
+ocx claude
+```
+
+`ocx claude` 會確保代理正在執行，然後在接好環境變數的情況下啟動 Claude Code：
+
+| 變數 | 值 |
+| --- | --- |
+| `ANTHROPIC_BASE_URL` | `http://127.0.0.1:` |
+| `ANTHROPIC_AUTH_TOKEN` | 僅在代理要求 API 金鑰時設定——否則不會設定，因此你的 claude.ai 登入（訂閱 + 聯結器）會保持有效 |
+| `CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY` | `1`（原生 `/model` 選擇器發現） |
+| `CLAUDE_CODE_AUTO_COMPACT_WINDOW` | 自動上下文壓縮閾值（預設 `350000`）；僅在啟用自動上下文時注入 |
+| `ANTHROPIC_MODEL` | `claudeCode.model`（可選） |
+| `ANTHROPIC_DEFAULT_HAIKU_MODEL` | `claudeCode.tierModels.haiku ?? claudeCode.smallFastModel`（可選，也包括舊版 `ANTHROPIC_SMALL_FAST_MODEL`） |
+| `ANTHROPIC_DEFAULT_{OPUS,SONNET,FABLE}_MODEL` | `claudeCode.tierModels.*`（可選） |
+| `CLAUDE_CODE_ALWAYS_ENABLE_EFFORT` | 啟用 `alwaysEnableEffort` 時設為 `1`（條件注入） |
+| `CLAUDE_CODE_MAX_CONTEXT_TOKENS` / `DISABLE_COMPACT` | 設定 `maxContextTokens` 時使用的舊版上下文覆蓋項（條件注入） |
+你自行匯出的變數始終優先。額外引數會直接透傳：`ocx claude -p "hello"`。
+
+## 認證模式
+
+Claude Code 需要在 `ANTHROPIC_AUTH_TOKEN` 中有 token 才能與閘道器通訊，但設定該變數也會停用
+你的 claude.ai 登入及其聯結器。你要哪一種，取決於 opencodex 可以查到的狀態，因此預設會自動判斷。
+
+在 **Claude → Claude Code** 中把 **認證模式** 保持為 **自動**（預設值），opencodex 會在每次
+啟動時決定：
+
+| 偵測結果 | 行為 |
+| --- | --- |
+| 有 Claude 登入（`~/.claude.json` 的 OAuth 帳號、`.credentials.json`、macOS keychain，或已匯出的 `ANTHROPIC_API_KEY`） | 不設定 token，讓你的訂閱與聯結器繼續運作 |
+| 完全沒有 Claude 認證 | 注入佔位 token，讓 Claude Code 不再要求登入，並經由代理路由 |
+| 無法判斷（keychain 無法讀取、檔案損毀） | 假設為訂閱並印出警告——讀取失敗時絕不會把付費訂閱者改成走代理 |
+
+此判斷會在每次啟動時重新計算，不會被記住，因此登入或登出會在下一次 `ocx claude` 時自動生效，
+無需重新設定。
+
+若要固定行為，請明確選擇 **Subscription** 或 **Proxy**。明確選擇會寫入 `claudeCode.authMode`，
+之後即使登入狀態改變，偵測也不會覆寫——包括你稍後登入或登出。切回自動即可把決定權交回。
+
+在 macOS 上，自動連線（`claudeCode.systemEnv`）也遵循相同解析邏輯，因此在 `ocx` 之外直接啟動的
+`claude` 行為一致。該檔案是代理啟動或你儲存設定時重新整理的快照，而 `ocx claude` 則一律即時解析。
+
+## Claude Desktop 設定檔
+
+Claude Desktop 使用與 Claude Code 分開的設定檔。在儀表板開啟 **Claude → Desktop**，可把每條
+可用路由放到四個系列之一：Opus、Fable、Sonnet 或 Haiku。新設定檔中所有路由一開始都在 Opus。
+第一個 Opus 路由會成為整體初始預設，且每個非空系列都一定會有一個系列預設。
+
+若要改系列，可以把列拖到另一個系列。拖曳是可選的：每一列也都有可用滑鼠、觸控或鍵盤操作的
+移動控制項。使用 **設為預設** 選擇系列預設，再選 **儲存並套用到 Desktop**。允許空系列。若已
+儲存的預設暫時不可用，會改用該系列中第一個可用路由，直到原預設回來。
+
+你也可以用命令列管理同一份設定檔：
+
+```bash
+ocx claude desktop [apply]
+ocx claude desktop show [--json]
+ocx claude desktop move [--default]
+ocx claude desktop default
+ocx claude desktop export
+ocx claude desktop import [--apply]
+```
+
+`ocx claude desktop` 與 `apply` 都會把目前設定檔寫入 Claude Desktop。`show` 提供可讀摘要；加上
+`--json` 方便腳本使用。`export -` 會把帶版本的 JSON 寫到標準輸出。Import 會在儲存前驗證完整
+檔案，因此無效檔案不會改動目前設定檔。加上 `--apply` 可在匯入有效設定檔後立即寫入 Desktop。
+`none` 僅適用於空系列；每個非空系列都必須保留一個預設。
+
+非 Anthropic 路由會得到穩定別名，例如 `claude-opus-4-8-2026MMDD`。看起來像日期的部分是合成的
+路由槽位，不是模型釋出日期。真正的 Anthropic Claude 路由保留真實 id。新路由預設落在 Opus
+系列，但移動路由不會改變它所呼叫的供應商或模型。舊版 apply 旗標 `--static`、`--hybrid` 與
+`--discovery-only` 仍可供既有腳本使用。
+
+## 系統環境整合
+
+當 `claudeCode.systemEnv` 設定為 `true`（預設：**關閉**）時，`ocx start` 會使用 `launchctl setenv`
+在系統範圍內注入 `ANTHROPIC_BASE_URL` 和相關的 Claude Code 環境變數。因此，新開啟的終端視窗和
+標籤頁可以直接透過代理路由普通的 `claude` 命令，無需使用 `ocx claude` 包裝器。已經開啟的
+shell 不受影響，必須重新開啟。
+
+`ocx stop` 和代理關閉操作會**取消設定已注入的鍵**（不會恢復之前的值——只會移除 opencodex
+注入的鍵）。代理還會寫入 `~/.opencodex/claude-env.sh`；`ocx start` 會安裝一個 `.zshrc`
+source hook，以自動載入該檔案。
+
+可以在設定中設定 `claudeCode.systemEnv: false`，或使用 GUI 開關來停用。此功能僅適用於
+macOS；在其他平臺上，請使用 `ocx claude`。
+
+## 原生 Claude 透傳（訂閱直通）
+
+未設定身分驗證覆蓋時，Claude Code 會保留其 claude.ai OAuth 登入，並將其傳送給代理。
+對於未被任何別名或模型對映佔用的真正 `claude*`/`anthropic*` 模型，請求會連同你的憑證
+**原樣**轉發到 `api.anthropic.com`——beta、思考簽名、提示快取和計費身份都保持完全原生，
+而已路由模型仍可在同一會話中透過選擇器別名使用。
+
+**標頭處理：**轉發前會移除逐跳標頭以及 `host`、`content-length`、`accept-encoding`、
+`x-opencodex-api-key` 和 `origin`。其他所有標頭（包括 `anthropic-beta` 和
+`anthropic-version`）都會透傳。
+
+只有同時滿足以下**四個**條件時才會觸發透傳：`nativePassthrough` 不為 `false`；模型以
+`claude` 或 `anthropic` 開頭；bearer 或 `x-api-key` 以 `sk-ant-` 開頭；並且別名/模型對映
+解析後回傳的模型保持不變。這也意味著使用 `ocx claude` 時不再出現
+“claude.ai connectors are disabled”警告。
+
+可以設定 `claudeCode.nativePassthrough: false` 來停用；也可以透過
+`claudeCode.anthropicBaseUrl` 指向其他位置。
+
+## /model 選擇器（“From gateway”）
+
+Claude Code 2.1.129+ 透過 `GET /v1/models?limit=1000` 發現閘道器模型，並在原生 `/model`
+選擇器中以“From gateway”標籤列出。由於選擇器只接受以 `claude` 或 `anthropic` 開頭的 ID，
+opencodex 會將已路由模型公開為穩定且可逆的別名：
+
+| 介面 | 格式 | 示例 |
+| --- | --- | --- |
+| Claude Code CLI | `claude-ocx---` | `claude-ocx-native--gpt-5.6-sol` |
+| Claude Desktop 3P | `claude-opus-4-8-`（3 字元 base36 雜湊） | `claude-opus-4-8-ncb` |
+
+代理會按請求選擇別名族：`?ids=cli` 或 `?ids=desktop` 優先；否則，`claude-code/*`
+user-agent 會獲得易讀的 CLI 形式，其他用戶端會獲得 Desktop 雜湊形式。兩種別名族都會永久
+保持可解碼——以任一形式儲存在 `settings.json` 中的模型都能繼續工作。
+每個條目帶有誠實的顯示名（如 `gemini-3-pro (gemini)`），並以官方 ModelInfo 形態附帶完整模型
+能力（推理強度階梯、thinking 型別），使 Claude Desktop 的第三方閘道器模式能夠提供其推理強度
+選擇器。真實 Anthropic 模型保留其規範 id。合成的 2026 日期是內部槽位，不是釋出日期。舊版雜湊
+別名與較舊設定中的 `claude-ocx---` id 仍可解析。
+擁有權威 1M 上下文視窗的模型會多出一個 `…[1m]` 選擇器列：選中後 Claude Code 會按完整 1M 上下文
+計算該模型（自動壓縮仍開啟）——代理在路由前會去掉該標記。
+選中後會儲存到 Claude Code 的 `settings.json` `model` 欄位；入站請求會將別名解析回路由
+模型。在較舊的 Claude Code 版本中，選擇器保持原生——可透過 `ANTHROPIC_MODEL` 設定槽位，或在
+`/model` 中輸入任意已路由 id（Claude Code 會原樣傳遞字串）。
+
+**別名語法規則：**provider 不得包含 `/` 或 `--`，也不得等於 `native`；model 不得包含
+`/`。易讀形式無法表達的路由會回退到雜湊別名。模型 ID **可以**包含 `--`（解析時只按第一個
+`--` 拆分）；包含 `--` 的原生 slug 會回退到雜湊形式。
+
+**模型解析順序：**移除 `[1m]` 標記 → 解碼易讀別名 → 解碼 Desktop 雜湊別名 →
+`modelMap` 精確匹配 → 移除日期後的匹配（移除 `-20250514`）→ 透傳。
+
+每個條目都帶有類似 `gemini-3-pro (gemini)` 的顯示名稱，以及官方 `ModelInfo` 結構中的完整
+模型能力（推理強度階梯、思考型別）。真正的 Anthropic 模型在兩個介面上都保留其規範 ID。
+
+### 上下文變體 `[1m]` 標記
+
+權威上下文視窗為 1M 的模型（或者啟用自動上下文時，視窗大於 200k 且至少達到壓縮閾值的模型）
+會多出一個帶 `…[1m]` 的選擇器條目。選擇它後，Claude Code 會按完整的 1M 上下文計算。
+代理會在進行別名解析和路由之前移除不區分大小寫的 `[1m]` 字尾。
+
+## 自動上下文（突破 200k 上限的大上下文模型）
+
+對於任何無法識別的模型，Claude Code 都會按 200k token 計算。預設開啟的**自動上下文**可解決
+這一問題：
+
+1. 實際視窗大於 200k **且**至少達到自動壓縮閾值的模型，其選擇器條目和環境變數槽位會帶有
+ `[1m]` 標記。
+2. 系統會注入 `CLAUDE_CODE_AUTO_COMPACT_WINDOW`（預設 `350000`，範圍 `100000`–`1000000`），
+ 使對話在該位置自動進行摘要。
+
+設定有三種狀態：
+
+- **缺省 / `true`：**啟用（預設）
+- **`false`：**停用——不新增標記，也不注入壓縮視窗
+- **設定了舊版 `maxContextTokens`：**隱式停用自動上下文
+
+可以在 Claude 頁面調整壓縮值。**警告：**如果將其提高到超過模型的實際視窗，該模型將無法正常
+工作——聊天會在觸發摘要之前報錯。
+
+低於 1M 的原生 Anthropic 模型絕不會被自動標記。你自行匯出的值始終優先（代理會使用**你的**
+值來判斷哪些模型可以安全標記）。手動編輯設定時填入的無效值會回退到 350k。
+
+### 有效模型環境變數
+
+`effectiveModelEnv` 會計算由 `ocx claude` / 系統環境 / shell 檔案注入的六個槽位：
+`ANTHROPIC_MODEL`、四個 `ANTHROPIC_DEFAULT_{OPUS,SONNET,HAIKU,FABLE}_MODEL`，以及舊版
+`ANTHROPIC_SMALL_FAST_MODEL`。有效 Haiku 值為 `tierModels.haiku ?? smallFastModel`，並會
+提供給兩個 Haiku 變數。
+
+當 `tierModels.haiku` 和 `smallFastModel` 均未設定時，OpenCodex 會讓兩個輔助模型變數保持未設定；隨後 Claude Code 會選擇其原生輔助模型（目前為 Sonnet），並可能產生原生供應商費用。
+
+## 名冊代理（injectAgents）
+
+`ocx claude`（以及系統環境 daemon）會把你的精選子代理名冊（Subagents 標籤頁，最多 5 個模型）
+和 `ocx-self` 同步到 `~/.claude/agents/ocx-*.md`。
+
+- **`ocx-self`** 固定你在 `/model` 選擇器中的預設模型（回退到 `claudeCode.model`）；兩者均
+ 不存在時省略。它**不**使用模型繼承。
+- 每個代理正文都包含一條 `` 指令——代理使用該指令固定實際路由。
+ 因此 Agent 工具的 `model` 引數不起作用；請傳入 `"haiku"` 作為佔位符。
+- Frontmatter 攜帶別名；路由由指令驅動。
+- 只有包含 `generated-by: opencodex` 且透過標記驗證的 `ocx-*.md` 檔案才會被覆蓋或清理；
+ 你自己的代理絕不會被改動。
+- 檔案按單個檔案進行原子同步（寫入 + 重新命名）。
+- `enabled: false` 或 `injectAgents: false` 會清理所有經驗證歸屬的定義。
+- GUI PUT 和名冊變更會立即重新同步；啟動器/系統環境會在啟動時同步。
+
+派發方式：`subagent_type: "ocx-gpt-5-6-sol"`。支援 1M 的目標會自動攜帶 `[1m]`。
+
+## 內建技能省略（blockedSkills）
+
+Claude Code 內建的 `claude-api` 技能會注入約 840KB（約 136k token）的 Anthropic 文件內容，
+並在提及 Claude 模型時自動觸發。已路由模型並未針對該文件包進行訓練，因此預設情況下，
+opencodex 會在**已路由**請求中將該技能內容替換為一個短佔位說明。原生 Anthropic 透傳不受影響。
+
+**會處理兩種載體：**
+
+1. **工具結果載體：**assistant 的 `Skill(...)` 呼叫——當轉為小寫的 JSON 輸入包含被遮蔽名稱時，
+ 與之配對的 `tool_result` 正文會被替換為佔位說明。
+2. **文字塊載體：**以 `Base directory for this skill: ` 開頭且不少於 10,000 字元的使用者
+ 文字塊——當目錄 basename 等於被遮蔽名稱時匹配（不區分大小寫）。
+
+透過 `claudeCode.blockedSkills` 設定（預設 `["claude-api"]`；`[]` 會完全停用省略）。
+佔位說明會保持工具呼叫/結果的配對關係不變。
+
+## 模型對映（攔截）
+
+`claudeCode.modelMap` 會在路由前重寫傳入的 Anthropic 模型 ID：
+
+```json
+{
+ "claudeCode": {
+ "modelMap": {
+ "claude-sonnet-4-5": "gemini/gemini-3-pro",
+ "claude-haiku-4-5": "gemini/gemini-3-flash"
+ }
+ }
+}
+```
+
+查詢順序：發現別名 → 精確 ID → 移除日期字尾的 ID（`-20250514`）→ 透傳。
+
+## Sidecar 矩陣：Web Search 與圖像理解
+
+不同路由模型擁有的託管工具和圖像能力並不相同。opencodex 會在主模型回答前補齊這些能力：
+
+- **Web-search sidecar** 執行真實的託管搜尋，再把答案和來源作為工具結果交給路由模型。
+- **Vision sidecar** 在呼叫 `noVisionModels` 中的模型前描述附件圖像，並用文字描述替換圖像。
+
+兩個 sidecar 都可使用以下任一後端：
+
+| 後端 | 執行方式 | 所需條件 |
+| --- | --- | --- |
+| `openai` | 透過 ChatGPT `forward` provider 呼叫小型 GPT 模型 | ChatGPT 登入，以及已啟用的 `authMode: "forward"` provider |
+| `anthropic` | 透過已儲存的 Anthropic OAuth 呼叫 Claude；Web Search 使用 `web_search_20250305`，Vision 讓 Claude 描述圖像 | 已啟用的 `adapter: "anthropic"`、`authMode: "oauth"` provider，且其活動帳號未標記 `needsReauth` |
+
+顯式設定的 `backend` 始終優先。省略時，如果存在可用的 Anthropic OAuth 活動帳號，則選擇
+`anthropic`；否則選擇 `openai`。顯式選擇 `anthropic` 卻沒有可用憑證時會**關閉失敗
+（fail closed）**：不會借用 ChatGPT 憑證，也不會靜默切換後端。同樣，OpenAI 後端缺少 ChatGPT
+登入或 forward provider 時不會啟用。
+
+Claude 入站的路由重放會把主 ChatGPT 登入附加到內部請求，因此即使 Claude Code 的 bearer 僅用於
+代理認證，OpenAI sidecar 仍可存取。該 ChatGPT bearer 不會傳送給主路由 provider。
+
+```json
+{
+ "webSearchSidecar": {
+ "backend": "anthropic",
+ "model": "claude-sonnet-5",
+ "maxSearchesPerTurn": 3
+ },
+ "visionSidecar": {
+ "backend": "anthropic",
+ "model": "claude-sonnet-5",
+ "maxDescriptionsPerTurn": 8
+ }
+}
+```
+
+`maxDescriptionsPerTurn` 限制一個主模型 turn 中新增的圖像描述次數。快取命中和同一 turn 內重複的
+進行中描述不會消耗配額。成功的 `data:` 圖像描述會按後端、模型、detail、圖像位元組和請求上下文
+快取，避免每次重放都重複描述同一圖像與上下文。內容可能變化的遠端 `https:` 圖像不會快取。
+
+全部設定項見[設定參考](/zh-tw/reference/configuration/#sidecars)。Anthropic OAuth Web
+Search 和圖像描述沿用儲存庫已有的 Claude Code OAuth fingerprint 先例，但在用於長時間無人值守任務前，
+仍應使用你的帳號和實際負載進行充分 soak test。
+
+
+
+## 推理強度
+
+Claude Code 的 `/effort` 設定會完整保留並傳遞給適配器：
+
+| 傳輸格式 | 對映 |
+| --- | --- |
+| `thinking.type: "adaptive"` + `output_config.effort` | 直接傳遞強度（`minimal`\|`low`\|`medium`\|`high`\|`xhigh`\|`max`\|`ultra`） |
+| `thinking.type: "enabled"` + `budget_tokens` | ≤4096→`low`，≤16384→`medium`，更高→`high` |
+| `thinking.type: "disabled"` | `reasoning: { effort: "none" }`；省略摘要 |
+
+解析後的值會顯示在請求日誌的 **Reasoning effort** 列中。
+
+## 入站轉換（Messages → Responses）
+
+代理會將每個 Anthropic Messages API 請求轉換為 Codex Responses API 格式：
+
+| Messages 輸入 | Responses 輸出 |
+| --- | --- |
+| 頂層 `system` | `instructions`（文字塊以 `\n\n` 連線） |
+| `messages[].role: "system"` | 同樣合併到 `instructions` |
+| 使用者文字 / 圖像 | `input_text` / `input_image`（base64 → data URL） |
+| Assistant 文字 | `output_text` |
+| Assistant `tool_use` | `function_call`（`input` → JSON 字串化的 `arguments`） |
+| 使用者 `tool_result` | `function_call_output`（`is_error` → `[tool error]` 字首） |
+| 重放 `thinking` / `redacted_thinking` | 丟棄 |
+| Function 工具 | `{type: "function"}`（`web_search*` → `{type: "web_search"}`） |
+| `tool_choice` | `auto`→`auto`，`none`→`none`，`any`→`required`，指定名稱 function→`{type:"function",name}`，hosted WebSearch/web_search→`{type:"web_search"}` |
+| `max_tokens` | `max_output_tokens` |
+| `stop_sequences` | `stop` |
+
+**錯誤情況（400）：**JSON 格式錯誤；缺少/空的 `model`；缺少/空的 `messages`；不支援的
+role；`tool_result` 缺少 `tool_use_id`；`tool_use` 缺少 id/name；指定名稱的 `tool_choice`
+缺少 name。
+
+## 出站轉換（Responses → Messages SSE）
+
+| Responses 事件 | Messages SSE |
+| --- | --- |
+| `response.created` | `message_start` + `ping` |
+| 心跳 | `ping` |
+| 文字增量 | `content_block_start` → `content_block_delta`（文字）→ `content_block_stop` |
+| 推理摘要/文字 | 帶合成簽名的 `thinking` 塊 |
+| Function-call 幀 | 帶 `input_json_delta` 的 `tool_use` 塊 |
+| 終止事件 | `message_delta` → `message_stop` |
+| 在終止事件前 EOF | 502 風格的 `api_error` |
+
+**停止原因對映：**`completed` → `tool_use`（如果有工具呼叫）或 `end_turn`；
+`incomplete/max_output_tokens` → `max_tokens`；`incomplete/content_filter` → `refusal`。
+
+**錯誤分類：**400 `invalid_request_error`、401 `authentication_error`、
+402 `billing_error`、403 `permission_error`、404 `not_found_error`、409 `conflict_error`、
+413 `request_too_large`、429 `rate_limit_error`、504 `timeout_error`、529 `overloaded_error`，
+其他 5xx 為 `api_error`。`Retry-After` 會保留。
+
+## 提示快取與 token 用量
+
+**Anthropic 路由請求：**適配器會管理工具、系統內容和倒數第二條使用者訊息的快取斷點，以及頂層
+自動 `cache_control`。穩定輪次通常能達到約 99.9% 的快取命中率。
+
+**原生 OpenAI/ChatGPT 路由：**派生會話範圍的 `prompt_cache_key`（存在時取自
+`metadata.user_id`，否則回退到系統內容雜湊）和用於快取親和性的 `session_id` 標頭。
+快取鍵包含模型和完整的工具 schema。
+
+**Token 計算：**Anthropic 輸出會從 `input_tokens` 中減去 `cached_tokens` 和
+`cache_write_tokens`，並將它們分別公開為 `cache_read_input_tokens` 和
+`cache_creation_input_tokens`。請求日誌會將其對映回包含這些值的 `inputTokens`，讀取量同時
+記錄在 `cachedInputTokens` 和 `cacheReadInputTokens` 中，寫入量記錄在
+`cacheCreationInputTokens` 中。Usage 頁面會分別報告快取命中和快取建立。
+
+**count_tokens：**已路由模型使用近似值（序列化後的 system + messages + tools）。使用
+`sk-ant-` 憑證的原生 Anthropic 模型會將請求透傳到真實的 Anthropic
+`/v1/messages/count_tokens` 端點。
+
+## 除錯捕獲
+
+`ocx debug claude on|off|status|reset`、`OCX_CLAUDE_DEBUG=1` 或
+`PUT /api/debug {"claude": true}` 控制入站捕獲。`GET /api/claude/inbound-debug` 回傳
+`{enabled, entries}`（最新條目在前，環形緩衝區大小為 20）。
+
+每個條目記錄：`at`、`endpoint`、`model`、`resolvedModel`、`stream`、`maxTokens`、
+`thinkingType`、`thinkingBudgetTokens`、`outputConfigEffort`、`metadataKeys`、
+`hasMetadataUserId`、`hasSystem`、原始 `anthropicBeta`，以及 user id / system 的八字元
+HMAC 等值標籤。**不會儲存提示文字、原始物件或跨執行穩定的雜湊。**停用 Claude 除錯會立即
+清空環形緩衝區。
+
+## GUI（Claude 頁面）
+
+儀表板側邊欄有一個專用的 **Claude** 頁面（位於 API 下方）和 **Claude ON** 開關
+（標籤特意在所有語言中保持一致）。該頁面顯示：
+
+- 入站總開關（啟用開關）
+- 快速入門（`ocx claude`）和手動環境變數塊
+- Fast Mode 選擇器（Auto / ON / OFF）
+- 自動上下文開關和壓縮閾值下拉選單
+- 子代理自動註冊開關
+- 模型攔截（modelMap）編輯器
+- 選擇器別名即時預覽
+
+`GET /api/claude-code` 回傳有效預設值、設定、上下文視窗登錄表、有效環境變數、可用路由 ID、
+別名和埠。`PUT /api/claude-code` 接受部分更新並保留省略的欄位；`null` 會重置
+context/blocklist/compact-window 值。
+
+## 疑難排解
+
+**Claude Code 顯示“Did 0 searches”**——目前版本會把已完成的 Responses
+`web_search_call` 轉換成配對的 Anthropic `server_tool_use` 和 `web_search_tool_result` block，
+並寫入 `usage.server_tool_use.web_search_requests`。如果舊版本已經完成搜尋卻仍計為 0，請更新
+opencodex。
+
+**Sidecar 未啟用**——使用 `backend: "openai"` 時，請確認已登入 ChatGPT，並存在已啟用的
+`authMode: "forward"` provider。使用 `backend: "anthropic"` 時，請確認已儲存的 Anthropic
+OAuth 活動帳號未標記 `needsReauth`。顯式選擇 Anthropic 卻沒有可用憑證時會按設計關閉失敗。
+
+**“claude.ai connectors are disabled”**——你的 shell 中設定了 `ANTHROPIC_API_KEY` 或
+`ANTHROPIC_AUTH_TOKEN`。`ocx claude` 特意**不會**設定 `ANTHROPIC_API_KEY`；如果你已將其
+匯出，請取消設定。`ocx claude` 會注入 `ANTHROPIC_BASE_URL`、發現相關變數、自動上下文和已設定的模型槽位，但絕不會注入 `ANTHROPIC_API_KEY`。
+
+**模型未顯示在 /model 選擇器中**——確認已設定
+`CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY=1`（使用 `ocx claude` 時會自動設定）。執行
+`ocx claude` 以重新整理 `~/.claude/cache/gateway-models.json` 中的閘道器模型快取。檢查
+`claudeCode.enabled` 不為 `false`。
+
+**埠更改後環境變數過時**——如果代理埠發生變化，舊 shell 中的
+`ANTHROPIC_BASE_URL` 可能已經過時。請開啟一個新終端，或重新執行 `ocx claude`。
+
+**大模型仍受 200k 上下文上限限制**——在選擇器中選擇 `[1m]` 變體，或啟用自動上下文
+（預設開啟）。如果選擇器中沒有 `[1m]` 條目，該模型的權威上下文視窗可能低於自動壓縮閾值。
+
+**技能載入導致 token 數量過高**——內建的 `claude-api` 技能（約 136k token）會在提及
+Claude 模型時自動載入。對於原生透傳，這是正常現象；對於已路由模型，opencodex 預設會將其
+替換為佔位說明（`blockedSkills: ["claude-api"]`）。
+
+**子代理派發到錯誤模型**——名冊代理（`ocx-*`）使用 `` 指令，
+而不是 Agent 工具的 `model` 引數。請確保指令與預期路由一致。傳入 `"haiku"` 作為模型佔位符。
diff --git a/docs-site/src/content/docs/zh-tw/guides/codex-app-models.md b/docs-site/src/content/docs/zh-tw/guides/codex-app-models.md
new file mode 100644
index 000000000..0bc0e5e4d
--- /dev/null
+++ b/docs-site/src/content/docs/zh-tw/guides/codex-app-models.md
@@ -0,0 +1,189 @@
+---
+title: Codex App 模型選擇器
+description: opencodex 模型如何透過共享 Codex 目錄出現在 Codex App、Codex CLI 和 Codex TUI 中。
+---
+
+opencodex 不會修改 Codex App。它會寫入 Codex CLI/TUI 所使用的同一套 Codex 設定和模型目錄。
+Codex 的 app-server 會讀取這份共享狀態，但部分 Codex Desktop 版本會在 renderer 套用第二層
+遠端模型 allowlist，仍可能把已路由的列從選擇器中移除。
+
+OpenAI 條目使用兩條憑證路線：原生 Codex 登入，以及帶名稱空間的 `openai-apikey/`
+API key 傳輸。僅在 Pool 與 Direct 之間切換 `codexAccountMode` 本身不會改變選擇器 id。不過，
+當 `codexAccountPickerEnabled` 啟用帳號限定選擇器列，且 `codexAccountNamespaces` 中仍有對應
+帳號存在的合格選擇器時，opencodex 會為這些對應帳號新增獨立的 `/`
+列，並從 Codex 選擇器中隱藏裸的原生列。選擇器標籤是使用者自訂的公開名稱，本身沒有帳號角色
+的語意。選擇限定列只會使用其對應的帳號，不會改變目前 Pool 帳號；當目標不可用時會失敗關閉
+（fails closed），而不是切換帳號。參見
+[精確 Codex 帳號選擇器](/zh-tw/reference/configuration/routing/#精確-codex-帳號選擇器)。
+
+當 `codexAccountNamespaces` 對應表為空時，帳號限定選擇器列是關閉的。若省略
+`codexAccountPickerEnabled` 但對應表非空，基於向後相容會被視為啟用。將其設為 `false` 可以
+隱藏生成的限定列並恢復選擇器中的裸原生列，同時不必刪除對應或停用精確的
+`/` 路由。
+
+API GPT-5.6 條目使用 1,050,000 context / 922,000 max input；`*-pro` 選擇器 id 會解析為帶
+`reasoning.mode: "pro"` 的 base wire 模型，而日誌、用量與選擇器狀態仍保留虛擬 id。API 目錄
+固定為恰好八個 id：`gpt-5.5`、`gpt-5.6`、Sol/Terra/Luna，以及它們的三個 Pro 虛擬 id；沒有
+通用的 `gpt-5.6-pro` 別名。Compact 請求保留所選 tier，但會在不帶 reasoning 物件的情況下傳送
+base 模型。
+
+選擇選擇器 id 所代表的憑證路線。在 Providers 頁面切換 Pool/Direct；下面的 `` 是
+使用者自訂的公開標籤，透過 `codexAccountNamespaces` 對應：
+
+```text
+gpt-5.6-sol # 經由 Pool 或 Direct 的裸 Codex 登入路線
+/gpt-5.6-sol # 由該選擇器對應的已儲存 Codex 帳號
+openai-apikey/gpt-5.6-sol # API key
+```
+
+全新安裝以及未儲存模式的設定檔預設為 Pool。目前設定檔使用 marker 2，並在
+`~/.opencodex/config.json.pre-openai-tiers-v2.bak` 保留出廠的 v1 原始檔；用以下指令恢復：
+
+```sh
+cp ~/.opencodex/config.json.pre-openai-tiers-v2.bak ~/.opencodex/config.json
+```
+
+較早的 v1 三 provider 設定會自動遷移為單一的 option-aware 列。
+
+## Desktop 遠端 allowlist 限制
+
+如果 `codex debug models` 和 app-server 的 `model/list` 都包含某個路由模型，但 Desktop 沒有
+顯示它，請查看上游的 [Codex issue #19694](https://github.com/openai/codex/issues/19694)。當
+遠端 `use_hidden_models` 政策啟用時，Desktop 只能保留其原生 `available_models` 清單中的 id，
+而且也可能顯示目錄可見性為 `hide` 的原生列。單靠重新整理目錄或重啟代理無法改變這個 renderer
+政策。
+
+對於等效的路由模型，opencodex 提供一個明確、預設關閉的 native-alias combo 模式。它會發布
+一個通過 allowlist 的裸 slug（帶誠實的自訂顯示標籤），並在進行正式 OpenAI 路由之前，先把該
+精確 slug 經由已設定的 combo 路由。只要相容別名存在，它也把已停用的裸原生列從有效目錄中
+省略，因此 Desktop 無法藉由忽略 `visibility` 讓它們復活。指令、停用 key 語意與安全性限制請見
+[Codex Desktop native-allowlist 相容性](/zh-tw/guides/combos/)。
+
+## 整合路徑
+
+`ocx init`、`ocx start` 和 `ocx sync` 會把共享的 Codex 設定與目錄接入代理；設定注入、目錄同步、
+shim、WebSocket 回退與恢復機制請見 [Codex 整合](/zh-tw/guides/codex-integration/)。
+
+## 為什麼路由模型會顯示
+
+Codex 模型選擇器要求條目符合 Codex 目錄結構。opencodex 會克隆一個原生 Codex 模型模板，然後
+替換路由模型的身份資訊：
+
+```text
+slug = "anthropic/claude-sonnet-..."
+display_name = "anthropic/claude-sonnet-..."
+visibility = "list"
+```
+
+克隆後的條目會保留 reasoning 級別、shell 型別、API 支援標誌和 base instructions 等嚴格解析器
+所需欄位。隨後，opencodex 會移除該路由無法兌現的原生專屬能力，例如 OpenAI service-tier 後設資料。
+
+## 目前穩定模型涵蓋範圍
+
+原生回退列表包含 `gpt-5.5`、`gpt-5.4`、`gpt-5.4-mini`、
+`gpt-5.3-codex-spark` 以及 GPT-5.6 Sol/Terra/Luna。對於 GPT-5.5/5.4 系列，opencodex 會
+保留已安裝 Codex 目錄中資訊更完整的即時條目，僅在條目缺失時才合成。內建的上游快照只用於
+GPT-5.6，以便提供每個模型真實的身份和後設資料，而不是套用舊模板近似生成。
+
+| 路由 | 選擇器 id 與目錄後設資料 |
+| --- | --- |
+| Codex 登入（停用帳號限定列） | 裸原生 id，例如 `gpt-5.6-sol`、`gpt-5.6-terra`、`gpt-5.6-luna`；透過 `codexAccountMode` 選擇 Pool 或 Direct。GPT-5.6 列使用 372,000 token 的目錄視窗。 |
+| Codex 登入（啟用帳號限定列且有合格選擇器） | 每個合格選擇器與受支援的原生模型各有一列 `/`；每列只使用其對應帳號，且裸原生列會從選擇器中隱藏。原生後設資料與 context 視窗保持不變。 |
+| OpenAI（API key） | 恰好八個帶名稱空間的列：`gpt-5.5`、`gpt-5.6`、Sol/Terra/Luna 與三個 `*-pro` 虛擬 id（全部八個都是 1,050,000 context；922,000 max input） |
+| OpenRouter | `openrouter/openai/gpt-5.6-sol`、`openrouter/openai/gpt-5.6-terra`、`openrouter/openai/gpt-5.6-luna`（1,050,000） |
+| Cursor | 靜態回退目錄包含 `cursor/gpt-5.6-sol`、`cursor/gpt-5.6-terra`、`cursor/gpt-5.6-luna`（1,000,000），以及 `cursor/grok-4.5`、`cursor/grok-4.5-fast`（500,000）；帳號的即時發現結果決定最終顯示哪些模型。 |
+| xAI | 以即時發現結果為準；回退目錄預設使用 `xai/grok-4.5`，視窗為 500,000 token，並提供 `low` / `medium` / `high` reasoning 控制。 |
+
+固定的 GPT-5.6 條目會保留精確的上游 reasoning 階梯。Sol 和 Terra 從 `low` 到 `ultra`，Luna
+最高到 `max`。Sol 預設使用 `low`，Terra 和 Luna 預設使用 `medium`。`ultra` 是用戶端側的
+“最大 reasoning + 主動委派”選項，到達後端時會轉換為 `max`。模型出現在選擇器中只表示目錄已經
+準備好；關聯的帳號或 API key 仍需具備該模型的實際權限。
+
+## 原生與路由模型開關
+
+儀表板的 Models 頁面為裸原生 id 與路由的 `provider/model` id 提供 `disabledModels` 開關。
+帳號限定的 `/` id 也受 `disabledModels` 支援，但儀表板不會列出
+或切換這些精確的選擇器列；請手動加入設定檔：
+
+- 路由 id 使用 `provider/model` 名稱空間。停用後，該模型會從同步目錄和 `/v1/models` 中排除。
+- 帳號限定的原生 id 使用 `/`。把它加入 `disabledModels` 只會
+ 隱藏該選擇器列。
+- 原生 GPT id 是裸 slug。停用時不會刪除目錄條目，而是將 `visibility` 改為 `hide`，以便稍後
+ 重新啟用時能精確恢復原條目；它會從自動探索中隱藏該裸列以及該模型的每個選擇器限定複製條目。
+- 只要設定至少一個 native-alias combo，已停用的裸原生列就會被省略而非保留為 hidden，因為
+ 受影響的 Desktop 版本會忽略 hidden 旗標。被 native alias 遮蔽的裸原生 slug 也會從 Models
+ 頁面省略，因此它在那裡沒有原生開關；只有未被遮蔽的原生列可供切換。重新同步會在重新啟用
+ 未遮蔽的停用列時恢復原始的原生後設資料。
+- 未遮蔽的原生列來自受支援的靜態集合，因此已停用的未遮蔽模型仍會留在儀表板中，可以重新開啟。
+
+可見性處理位於快照升級之後。每次切換模型後，管理 API 都會重新整理目錄，並強制把 Codex 模型快取
+標記為過期。
+
+## Multi-agent surface 模式
+
+Models 頁面的 v1/base/v2 控制會改變每個選擇器條目使用的 Codex 協作介面；模式、委派、繼承、
+回退與加密任務行為的權威說明請見 [子代理介面](/zh-tw/guides/sub-agent-surface/)。
+
+## 頂級 reasoning 檔位
+
+目錄中顯示哪些 reasoning 檔位與 v1/base/v2 介面模式無關。生成的、支援 reasoning 的條目會提供
+`max`，以便直接指定的子代理強度透過校驗；目前生成的路由條目和舊一代原生 GPT 條目還會提供
+`ultra`。精確的上游 GPT-5.6 階梯會原樣保留，因此 Luna 只有 `max`，沒有 `ultra`。
+
+在實際請求中，路由 adapter 會對映或限制不受支援的檔位。對於真實最高檔位為 `xhigh` 的舊原生
+模型，`nativeEffortClamp` 會把直接指定的 `max` 或 `ultra` 選擇轉換為 `xhigh`，例如 GPT-5.5。
+Sol、Terra 和 Luna 都有真實的 `max` 檔位。
+
+## Fast tier 規則
+
+Codex 在設定檔中這樣儲存 fast 模式：
+
+```toml
+service_tier = "fast"
+
+[features]
+fast_mode = true
+```
+
+模型目錄和執行環境請求使用的 tier id 則是 `priority`。opencodex 會保留這一差異。原生 OpenAI
+透傳模型繼續支援 fast；路由 provider 則依能力閘控 —— 只有當 provider 宣告
+`supportsServiceTier: false` 時才會移除 `service_tier`（registry 將正規 OpenAI 歸類為 `true`，
+DeepSeek 與 Volcengine Ark 歸類為 `false`），而未分類的自訂 gateway 會原封不動保留呼叫端提供
+的值，絕不注入。無法兌現的地方絕不會宣傳 fast 選項；自訂 gateway 也可以明確以 `true` 選擇加入。
+
+## 子代理選擇
+
+Codex 會按 `priority` 升序排列選擇器中可見的目錄條目，並將前五個顯示為 `spawn_agent` 模型
+override。儀表板的 Subagents 頁面可以選擇並儲存最多五個裸原生 id 或路由的 `provider/model`
+id。手動設定的 `subagentModels` 也接受帳號限定的 `/` id，但
+儀表板不提供這些精確 id；儲存頁面時會把列表替換為儀表板可見的選擇。opencodex 會按所選順序
+賦予較低的目錄 priority；啟用帳號限定選擇器列時，裸原生選擇會展開為選擇器限定群組。其他模型
+仍可透過精確 id 直接呼叫。
+
+置頂模型列表與 Dashboard 的 **Sub-agent delegation** 選擇相互獨立。它只控制 Codex 優先提供
+哪些 override；本身不會選定模型或觸發委派。
+
+## Desktop remote 伺服器
+
+Codex Desktop 的 remote-server 模式會以用戶端自己的 `available_models` allowlist 過濾選擇器
+（當遠端 `use_hidden_models` 設定開啟時生效）。路由目錄條目仍會被載入與提供 —— `model/list`
+會回傳它們，內建 CLI 也會讀取 —— 但 Desktop 的 renderer 在渲染前會丟棄任何不在該僅原生
+allowlist 上的項目。opencodex 無法介入該清單；上游錯誤追蹤於
+[openai/codex#19694](https://github.com/openai/codex/issues/19694)。
+
+在 Desktop 公開 allowlist 控制選項之前：
+
+- 直接在遠端機器的 `~/.codex/config.toml` 設定模型，例如 `model = "input/grok-4.5"`。選擇器
+ 可能顯示 `Custom`，但請求仍會使用已設定的路由模型。
+- 改用 Codex CLI 或 TUI 而不是 Desktop 選擇器；它們不會套用 allowlist，會正常列出路由模型。
+
+## 重新整理模型狀態
+
+如果選擇器仍顯示舊條目，請重新整理目錄並重新開啟目標 Codex 介面：
+
+```bash
+ocx sync
+```
+
+當目錄的可見性、priority 或後設資料發生變化時，opencodex 會用一個刻意標記為過期的快取 wrapper
+重寫 `models_cache.json`，使 Codex 下次重新整理模型時讀取新目錄。
diff --git a/docs-site/src/content/docs/zh-tw/guides/codex-integration.md b/docs-site/src/content/docs/zh-tw/guides/codex-integration.md
new file mode 100644
index 000000000..a0349e97f
--- /dev/null
+++ b/docs-site/src/content/docs/zh-tw/guides/codex-integration.md
@@ -0,0 +1,328 @@
+---
+title: Codex 整合
+description: opencodex 如何將自身注入 Codex、同步模型目錄、安裝 shim，並乾淨地恢復。
+---
+
+opencodex 透過修改 Codex 會讀取的兩項內容，讓 Codex 經由 proxy 路由：其設定
+（`$CODEX_HOME/config.toml`，預設為 `~/.codex/config.toml`）與模型目錄。每項修改都是冪等且可逆的。
+
+proxy 提供一條裸 `openai` Codex 登入路徑，可使用 Pool（預設）與 Direct 帳號模式，另提供
+`openai-apikey/` 給已設定的 API 金鑰。Pool 包含主帳號與新增帳號；Direct 只使用 caller／主登入
+bearer。這些路徑不會彼此 fallback。shipped v1 設定會遷移到 marker 2，並保留
+`config.json.pre-openai-tiers-v2.bak` 供手動恢復。
+
+## 設定注入
+
+`ocx init`、`ocx start` 與 `ocx sync` 都會呼叫注入器。在預設 loopback 繫結下，它會保留 Codex
+內建的 `openai` provider id，並將該 provider 指向 opencodex：
+
+```toml
+# 根級鍵，必須位於第一個 table 之前
+model_catalog_json = "/absolute/path/to/opencodex-catalog.json"
+# Auto-injected by opencodex
+openai_base_url = "http://127.0.0.1:10100/v1"
+
+# 僅在設定 fastMode 時寫入；未設定時不新增 [features] table
+[features]
+fast_mode = true
+```
+
+注入的 `fast_mode` 會遵循 `fastMode` 三態設定：`true` 寫入 `fast_mode = true`，`false` 寫入
+`fast_mode = false`；未設定時會保留既有 `fast_mode`，且不新增 `[features]` table。
+
+proxy 預設監聽 `10100` 埠，提供 `POST /v1/responses`、`POST /v1/responses/compact`、
+`POST /v1/images/generations`、`POST /v1/images/edits`、`GET /v1/models`、`GET /healthz`
+以及 `/api/*` 管理介面。
+
+### 內建圖像生成（`image_gen`）
+
+Codex 的內建 `image_gen` 工具不會經過 `/v1/responses`。codex-rs 擴充套件會直接 POST 到
+`{base_url}/images/generations`；附帶參考圖時則使用 `/images/edits`，並沿用聊天使用的 ChatGPT bearer
+認證。由於注入的 `base_url` 指向 opencodex，proxy 會把這些呼叫中繼到 OpenAI 上游。
+
+這與 [Image Bridge](/zh-tw/guides/image-bridge/) 是不同路徑。Image Bridge 只有在 **Responses** turn
+列出 hosted `image_generation` 工具、且目前選的是非 OpenAI 模型時才會啟動。獨立的
+`/images/generations` 呼叫不會進入該 bridge。
+
+- **單一、感知模式的 forward 候選：** Pool 會選擇合格的主帳號或新增帳號；Direct 使用 caller OAuth
+ bearer。圖像請求會一致遵循目前設定的模式。
+- **OpenAI API-key provider：** 只有在沒有 forward 候選擁有認證失敗時才會使用。損壞或過期的 Pool
+ 憑證不會被另一條額外計費的 API 路徑掩蓋。
+- **明確指定的自訂 provider：** 將 `images.provider` 設為某個自訂 API-key `openai-responses`
+ provider id，而且其端點必須實作 OpenAI Images API。明確選擇時採 fail-closed，不會 fallback 到其他
+ 付費上游。此處不接受 registry 管理的 provider id；若要使用內建 OpenAI tiers，請省略
+ `images.provider`。
+- **Google Antigravity（CCA）fallback：** 若既沒有 OpenAI forward 候選，也沒有設定 keyed provider，
+ `/v1/images/generations`（不包含 `/images/edits`）會 fallback 到 Antigravity **Cloud Code Assist**
+ 端點，使用 `gemini-3.1-flash-image` 模型。OpenAI 認證解析失敗後也會觸發此 fallback，例如 ChatGPT
+ 憑證過期或缺失，而不限於完全沒有設定 OpenAI 候選的情況。這需要先執行
+ `ocx login google-antigravity`；OAuth token 只會傳送到固定的 CCA registry host，絕不會傳到設定層級
+ 的 `baseUrl` override。回應會轉成 Codex 預期的 `{created, data:[{b64_json}]}` 形狀。
+- **都沒有：** proxy 會回傳明確錯誤，而不是模糊的 404。路由 provider（Cursor、Gemini、Kiro 等）
+ 無法提供 `image_generation` 工具 relay；若完全不想提供此工具，可在 Codex 執行
+ `codex features disable image_generation`，等同於在 `config.toml` 設定
+ `[features] image_generation = false`。
+
+工具宣告仍會跟著模型的 Responses 請求傳送。對 API-key Responses provider，opencodex 會把 Codex
+私有的 `image_gen` namespace 降為上游安全的 `image_gen__` alias，例如
+`image_gen__imagegen`。當可用 alias 取代 client 宣告時，opencodex 會移除重複的 hosted
+`image_generation` 宣告；在 Codex 看見 function call 前，再將其對映回明確的 `image_gen` namespace，
+之後歷史重播到上游時則重新編碼成原生呼叫。這讓保留 namespace 或拒絕 dotted function name 的公開相容
+上游仍能呼叫 client-side 圖像生成。ChatGPT forward 模式保持不變，繼續使用原生 Responses Lite
+形狀。
+
+若要使用 OpenAI 相容的自訂 gateway，可設定專用 provider，並只讓獨立 Images 請求使用它：
+
+```json
+{
+ "providers": {
+ "custom-images": {
+ "adapter": "openai-responses",
+ "baseUrl": "https://gateway.example.com/v1",
+ "authMode": "key",
+ "apiKey": "${IMAGE_GATEWAY_API_KEY}"
+ }
+ },
+ "images": {
+ "provider": "custom-images",
+ "timeoutMs": 300000
+ }
+}
+```
+
+自訂端點必須接受 `POST /v1/images/generations` 與 `/v1/images/edits`，並回傳 Codex 預期的 OpenAI
+Images response 形狀。上游請求會使用該 provider 設定的 key 取代任何 caller bearer。
+
+> **注意：** 這裡只指 Codex 的 `image_generation` 工具（`/images/generations` relay）。支援圖像的
+> Gemini 模型會透過 `google` adapter 原生產生 inline image（使用
+> `responseModalities: ["TEXT", "IMAGE"]`），與此 relay 無關。參見
+> [轉接器](/zh-tw/reference/adapters/#google)。
+
+若 `hostname` 不是 loopback 地址，Codex 必須傳送產生的 API 認證標頭，因此注入器會改用專用
+provider：
+
+```toml
+# 根級鍵
+model_provider = "opencodex"
+model_catalog_json = "/absolute/path/to/opencodex-catalog.json"
+
+# 追加到檔案末尾
+# Auto-injected by opencodex
+[model_providers.opencodex]
+name = "OpenCodex Proxy"
+base_url = "http://your-host:10100/v1"
+wire_api = "responses"
+requires_openai_auth = true
+env_http_headers = { "x-opencodex-api-key" = "OPENCODEX_API_AUTH_TOKEN" }
+# supports_websockets = true # 僅當 config.websockets 為 true
+```
+
+當 OpenCodex 擁有路由時，兩種模式都會把 `$CODEX_HOME/opencodex.config.toml` 寫成參考／fallback
+設定。loopback 模式下，其中包含自動注入被移除時可手動合併的根級鍵；non-loopback 模式下，其中包含
+專用 provider 形式。外部 provider 模式不會修改此 profile。
+
+:::caution
+`openai_base_url`、`model_provider`、`model_catalog_json` 等根級鍵**必須**位於第一個 `[table]`
+標頭之前。注入器會保證此位置、移除自己留下的舊值或重複項，而且絕不覆寫使用者自有的根級
+`openai_base_url`；若該值存在，同步仍會更新模型目錄，但會回報路由未注入。
+:::
+
+## 共享模型目錄
+
+Codex CLI、TUI、App 與 SDK 都讀取同一個 Codex home。opencodex 會從 `CODEX_HOME` 解析該目錄，
+未設定時 fallback 到 `~/.codex`，並管理：
+
+```text
+$CODEX_HOME/config.toml
+$CODEX_HOME/opencodex.config.toml
+$CODEX_HOME/opencodex-catalog.json
+$CODEX_HOME/models_cache.json
+```
+
+在 WSL 中，如果未設定 `CODEX_HOME`，且 Linux 的 `~/.codex/config.toml` 不存在，opencodex 也會檢查
+`/mnt/c/Users/*/.codex/config.toml` 下是否只有一個 Windows Codex Desktop home。候選項恰好只有一個時，
+會使用該目錄，讓 WSL app-server mode 與 Windows Codex Desktop 共用相同的 config 與 auth 檔案。
+若要覆蓋此偵測，請明確設定 `CODEX_HOME`。
+
+Codex 可將 SQLite 支援的 thread state 放在另一個目錄。OpenCodex 的歷史操作採用與 Codex 相同的
+優先順序：先讀 `config.toml` 根級的 `sqlite_home`，再讀 `CODEX_SQLITE_HOME`，最後使用實際的
+`CODEX_HOME`。相對 SQLite home 會從目前工作目錄解析。若安裝或修復服務時明確設定了
+`CODEX_SQLITE_HOME`，持久化 launcher 會保存安裝當下解析出的絕對路徑，讓背景 proxy 持續操作同一個
+資料庫。若 `config.toml` 或其根級 `sqlite_home` 不存在，OpenCodex 會繼續使用環境變數／home fallback。
+若檔案無法讀取或解析，或該鍵存在但為空白或非字串，SQLite-home 解析會停止，以免歷史操作誤用另一個
+資料庫。
+
+在 Windows 上，Orca shell 可能同時把 `CODEX_HOME` 與 `ORCA_CODEX_HOME` 指向 Orca 內建的 runtime
+home，而 ChatGPT/Codex App 仍讀取 `%USERPROFILE%\\.codex`。`ocx status` 與 `ocx doctor` 會警告這個
+明確的不一致，並輸出經過遮蔽的目標路徑。若背景服務是在原 Orca shell 中安裝，請先在原 shell 中解除
+安裝，再將 `CODEX_HOME` 設為 App home、取消 `ORCA_CODEX_HOME`，重新同步／恢復後再安裝服務。
+
+在專用 provider 模式下，`requires_openai_auth = true` 會讓 Codex App/TUI 的帳號門控介面與原生
+Codex 保持一致。opencodex 也透過 WebSocket 提供 `/v1/responses`。專用 provider 只會在
+`"websockets": true` 時宣告 `supports_websockets = true`；loopback 模式下，Codex 的內建 provider
+可能先嘗試 WebSocket，若 proxy 未啟用此功能則回傳 `426`，讓 Codex fallback 到 HTTP/SSE。
+
+## Thread identity 與歷史記錄
+
+預設 loopback 形式會讓新 thread 保持使用 Codex 原生的 `openai` provider 標記，因此一般 resume
+history 不需要重新對映。第一次同步時，也會把舊版 opencodex 改過標記的 thread 遷回 `openai`。
+non-loopback 專用 provider 模式在啟用期間仍會把歷史映射到 `opencodex` provider，退出時再恢復已備份的
+metadata。設定 `syncResumeHistory: false` 可完全不修改歷史。
+
+## 模型目錄同步
+
+Codex 從磁碟上的目錄顯示模型，預設為 `$CODEX_HOME/opencodex-catalog.json`。啟動時與執行
+`ocx sync` 時，opencodex 會：
+
+1. **備份**一次原始目錄到 `~/.opencodex/catalog-backup.json`，讓置頂操作可逆。
+2. **取得**符合條件的 provider 即時模型目錄，快取約 5 分鐘；失敗時先 fallback 到上一份正常列表，
+ 再 fallback 到已設定的 `models[]`。`forward` 認證沒有模型端點；Cursor 使用
+ `GetUsableModels` RPC，而不是 `/models`。
+3. **合併**路由模型為帶 namespace 的條目（`provider/model`），從原生 Codex 目錄 template 複製，
+ 讓 Codex 嚴格的 parser 能接受它們。
+4. **過濾** `config.disabledModels` 與各 provider 非空的 `selectedModels` allowlist。
+5. **重新排序**，讓置頂模型排在前面，然後把合併後的目錄寫回。
+
+路由目錄條目也會把 GPT-5 identity 改寫成真正的上游模型名稱。reasoning 控制來自 provider／model
+metadata，使用 Codex 的 `low | medium | high | xhigh | max | ultra` 檔位；不支援的值會在送往上游前
+完成對映或下調。
+
+### 路由的本機工具
+
+非原生路由目錄列使用 `tool_mode: "code_mode_only"`。這讓 Codex 能暴露官方 `exec` 入口點與巢狀 MCP
+工具，包括 Browser 與 Computer Use，同時 opencodex 只路由模型的一般 function call。工具執行、權限
+與確認仍留在 Codex 本機；opencodex 不會實作第二套瀏覽器或桌面控制 executor。
+
+對不接受 Codex `exec` custom-tool grammar 的 key-auth Responses provider，opencodex 會把該宣告與其
+歷史編碼成上游 function tool，再於 Codex 看見前將串流 function-call lifecycle 還原成
+`custom_tool_call`。原生 OpenAI forward 路由與受支援的 `apply_patch` custom tool 維持不變。
+
+所選 provider 必須支援 function/tool calling。不支援 tool call 的純文字 provider 無法使用 `exec`、
+Browser 或 Computer Use。原生 OpenAI 列保留上游 tool mode 不變。
+
+`ocx sync` 變更這份 metadata 後，請重新啟動 Codex App 並開啟新任務。既有 app-server process 與任務
+可能仍保留啟動時載入的目錄與 tool plan。
+
+### 自訂模型顯示名稱
+
+自訂模型可以帶一個可讀的**顯示名稱**，只覆寫 Codex 模型選擇器顯示的標籤，不改變任何路由行為。
+顯示名稱只對應目錄條目的 `display_name` 欄位；路由 slug（`/`）、alias collision 順序、
+provider 與原生 OpenAI 行銷名稱都維持不動。
+
+可從 CLI 新增顯示名稱；proxy 在線時會立即同步目錄：
+
+```bash
+ocx models add deepseek deepseek-v4 --display-name "DeepSeek V4" --context-window 128000
+```
+
+遠端 Codex client 也能透過管理 API 取得相同的產生目錄，使用與其他 `/api/*` route 相同的 admission
+token：
+
+```bash
+dest="${CODEX_HOME:-$HOME/.codex}/opencodex-catalog.json"
+tmp="$(mktemp "${dest}.XXXXXX")"
+curl -fsS -H "x-opencodex-api-key: $OPENCODEX_ADMIN_AUTH_TOKEN" \
+ "https://proxy.example.com/api/catalog" > "$tmp" \
+ && mv "$tmp" "$dest"
+ocx sync-cache
+```
+
+回應是原始的 `opencodex-catalog.json` 文件，不包含 provider 憑證。若可用，
+`x-opencodex-codex-version` 標頭會回報伺服器上的 Codex runtime 版本，讓 client 能辨識版本差異。
+
+也可以透過管理 API（`POST /api/custom-models`、`PUT /api/custom-models/`，搭配 `displayName`
+字串）與 web 儀表板設定或編輯。`/` 會被拒絕，因為它會與路由 slug 的分隔符衝突。
+
+顯示名稱**只用於顯示，且在重新產生時保持穩定**。每次 `ocx sync` 與目錄 refresh 都會從
+`config.json`（包含 `customModels`）重新推導路由條目，因此會重新套用已設定名稱，而不會漂移回路由
+slug。受管服務重啟後，也會在 proxy bind 後盡力同步一次。若這次啟動時的 best-effort 同步失敗，例如
+離線登入，會保留先前已持久化的目錄，並在下一次成功的 `ocx sync` 重新套用設定名稱。真正的上游原生
+名稱，例如 `gpt-5.6-sol` → "GPT-5.6-Sol"，來自固定的上游 snapshot，絕不會被自訂顯示名稱覆寫。
+
+### 外部 provider 管理器
+
+若 `config.toml` 已選用非 `openai` 或 `opencodex` 的 provider，OpenCodex 會保持檔案不變，並跳過
+profile 寫入、目錄／cache refresh，以及立即與背景的 Codex 歷史遷移。管理自訂 provider 的工具常會把
+既有 session 標上該 provider id；直接替換 active id 可能讓這些完好的 session 從 Codex 歷史檢視消失。
+由舊版根級 profile 選到的外部 provider 也有同樣保護。
+
+請讓單一工具負責 Codex provider 設定。若要在既有 provider manager 後方使用 OpenCodex，請把該
+provider 指向 `http://127.0.0.1:10100/v1`，並使用 Responses passthrough（Codex TOML 中
+`wire_api = "responses"`），不要做 Chat Completions translation。啟用 proxy API auth 時，也需從
+`OPENCODEX_API_AUTH_TOKEN` 傳入 `x-opencodex-api-key`，形式與上方 non-loopback provider 相同。若要讓
+OpenCodex 直接注入路由，請先將 Codex 切回內建 `openai` provider，移除任何使用者自有的根級
+`openai_base_url`，再重新執行 `ocx start`。
+
+### 目錄疑難排解
+
+若模型在 Codex 中缺失，或目錄順序／可見性看起來不正確，請依序檢查：
+
+1. **provider 上的 `selectedModels`**：非空 allowlist 只會向 Codex 暴露列出的 id；空或省略則暴露所有
+ 已發現模型。不在 allowlist 中的 id 永遠不會進入目錄。
+2. **`disabledModels`（頂層）**：會同時從目錄與 `/v1/models` 隱藏模型，並把裸原生 GPT slug 設為
+ `visibility: "hide"`。
+3. **`liveModels: false` 且 `models` 為空**：當即時探索關閉，且 `models` 為空或省略時，opencodex
+ 不會為該 provider 暴露任何路由模型。
+4. **Cursor `GetUsableModels`**：Cursor adapter 透過 protobuf `GetUsableModels` RPC 探索模型，而不是
+ `/models`，所以 Cursor 端變更可獨立改變可見 id。
+5. **cache 與 `ocx sync`**：即時目錄約快取五分鐘（`modelCacheTtlMs`，預設 `300000`）。執行
+ `ocx sync` 可強制重新抓取並立即重寫目錄。
+6. **正在執行的 Codex `app-server`**：長時間執行的 Codex `app-server`（Desktop／CLI 背景 host）可能
+ 仍在記憶體保留舊列表，因此只重寫磁碟目錄還不夠。`ocx sync` 與 `ocx sync-cache` 偵測到這些
+ process 時會警告。可執行 `ocx sync --restart-codex` 重新啟動，或自行停止對應的 `app-server`
+ process，再讓 Codex 重新建立它們，讓新列表出現。
+
+:::caution[其他本機寫入者]
+目錄寫入（`opencodex-catalog.json`、`config.toml`）在 opencodex **內部**是原子的；這只避免兩個
+opencodex 擁有的寫入者競爭時出現半寫入檔案。它**不會**阻止其他本機 process、file watcher 或 sync
+agent 在 opencodex 寫入後改寫目錄可見性或順序。Codex 另有自己的 `models_cache.json`，可獨立 refresh，
+因此可能在不重寫 `opencodex-catalog.json` 的情況下改變可見列表。若 proxy 執行中模型卻意外跳動，請
+先停止或重新設定競爭的寫入者，再執行 `ocx sync`。這是外部寫入者風險，不是已確認的 opencodex
+缺陷。
+:::
+
+## Proxy 連線錯誤
+
+若 Codex 重試後報出類似
+`stream disconnected before completion: error sending request for url (http://127.0.0.1:10100/v1/responses)`
+的錯誤，或 Claude Code 出現類似連線失敗，代表 opencodex proxy 沒有執行：設定埠上沒有任何監聽，
+client 只能顯示原始連線錯誤。請重新啟動 proxy：
+
+```bash
+ocx start # 前景執行
+ocx service install # 常駐：登入時自動啟動，崩潰後自動重新啟動
+```
+
+`ocx status` 可檢視 proxy 是否執行，未執行時也會給出相同的重啟提示；`ocx doctor` 會回報重啟安全性
+（service／shim 覆蓋情況）。
+
+## Subagent 選擇器
+
+目錄同步會讓選定的 sub-agent 模型可供 Codex 使用；picker 排序請參見
+[Codex App 模型選擇器](/zh-tw/guides/codex-app-models/#subagent-selection)，v1/base/v2 委派與 fallback
+行為則參見 [Sub-agent Surface](/zh-tw/guides/sub-agent-surface/)。
+
+## Codex 帳號預熱
+
+向 Codex 帳號池新增 ChatGPT 帳號時，opencodex 會先用一個小型 streaming 請求向 Codex Responses
+backend 驗證，成功後才持久化。請求使用真正的 Responses item 陣列
+（`input: [{ type: "message", ... }]`），等待 `response.completed`，預設模型為 `gpt-5.4-mini`。若該
+模型回傳 HTTP 400，則改用 `gpt-5.5` 重試；結構化上游錯誤細節會呈現給使用者，但不暴露原始 response
+body。背景重新驗證是獨立功能，預設關閉；只有啟用 Token Guardian、將 `chatgpt` refresh policy 設為
+`proactive`，並把 `tokenGuardian.codexWarmupEnabled` 設為 true 時才會執行。
+
+## 恢復原生 Codex
+
+opencodex 絕不會把你困住。**`ocx stop` 是完整恢復原生 Codex 的單一命令**。它會停止 proxy、停止
+背景服務（若已安裝），並移除所有注入行與路由目錄條目，讓普通的 `codex` 就像從未安裝 opencodex 一樣
+運作：
+
+```bash
+ocx stop # 停止 proxy + service，恢復原生 Codex
+ocx restore # 不停止 proxy，只恢復原生設定（alias: ocx eject）
+ocx restore back # 讓普通 Codex 再次指向仍在執行的 proxy
+```
+
+當 opencodex 作為受管的 [背景服務](/zh-tw/reference/cli/#ocx-service) 執行時，會設定 `OCX_SERVICE=1`，
+因此 service 驅動的 restart **不會**反覆改寫 Codex 設定；只有明確執行 `ocx stop` 或
+`ocx service stop` 才會恢復原生 Codex。
\ No newline at end of file
diff --git a/docs-site/src/content/docs/zh-tw/guides/combos.md b/docs-site/src/content/docs/zh-tw/guides/combos.md
new file mode 100644
index 000000000..ac0efda05
--- /dev/null
+++ b/docs-site/src/content/docs/zh-tw/guides/combos.md
@@ -0,0 +1,274 @@
+---
+title: "組合：failover 與負載平衡"
+description: 將一個虛擬模型路由到多個供應商，以進行 failover 或加權負載平衡。
+---
+
+**combo** 是一個虛擬模型，背後代表一個有序的真實供應商/模型目標清單。你的客戶端請求 `combo/`；opencodex 選擇一個目標，將請求改寫為該具體的 `provider/model`，並可在第一個目標發生可重試失敗時嘗試另一個目標。
+
+這在你想要以下任一情況時有用：
+
+- **Failover：** 偏好一個模型，但隨時備有後備。
+- **負載平衡：** 以加權批次將成功請求分散到多個模型或供應商。
+
+Combo 位於一般供應商路由之前。若 `provider/model` 選擇器對你而言是新的，請先閱讀[模型路由](/zh-tw/guides/model-routing/)。
+
+## 60 秒快速入門
+
+此範例建立 `combo/main`，Anthropic 在前、OpenAI 在後。兩個供應商必須已存在且已啟用。
+
+```bash
+ocx combo set main --targets anthropic/claude-opus-4-8,openai/gpt-5.6-sol
+```
+
+預設策略為 failover，因此正常請求會送往 `anthropic/claude-opus-4-8`。若該次嘗試發生可重試失敗，opencodex 可跳到 `openai/gpt-5.6-sol`。
+
+在你平常會提供模型 id 的任何地方使用該虛擬模型：
+
+```json
+{
+ "model": "combo/main",
+ "input": "Explain why the sky looks blue."
+}
+```
+
+確認已儲存的定義：
+
+```bash
+ocx combo show main
+```
+
+:::tip
+從 failover 與等權重開始。只有在你刻意要分散流量時才切換到 round-robin，且只有在等量分配不適當時才加入權重。
+:::
+
+## Combo 名稱如何運作
+
+`ocx combo set ` 中的 combo id 必須以字母或數字開頭。其後可含字母、數字、`.`、`_` 或 `-`，總長最多 64 字元。其規範模型 id 始終為 `combo/`；例如 id `main` 變成 `combo/main`。
+
+設定 combo 時，`combo/` 命名空間會被保留。名為 `combo` 的供應商無法佔用它，且 combo id 不能與已設定的供應商名稱重複。
+
+可選的別名給 combo 一個不同的公開模型名稱。別名：
+
+- 使用與 id 相同的字元；
+- 可為裸名（例如 `daily-fast`），或含一個 `/`（例如 `team/daily-fast`）；
+- 不能是 `combo` 或以 `combo/` 開頭；
+- 不能與另一個 combo 別名重複；且
+- 不能是以 `gpt-`、`o1-`、`o3-`、`o4-` 或 `codex-` 開頭的裸原生 OpenAI 系列名稱。
+
+即使設定了別名，規範的 `combo/` 形式仍可解析。規範查詢在別名匹配之前執行，因此別名無法接管另一個 combo 的規範 id。
+
+:::note
+別名改變客戶端請求的公開名稱；不改變 combo 儲存的 id 或其背後的具體供應商/模型選擇器。
+:::
+
+## Codex Desktop 原生 allowlist 相容性
+
+某些 Codex Desktop 版本會在 app-server 已載入 `model_catalog_json` 之後，套用只允許原生的遠端
+`available_models` allowlist。因此 `Nova1/codex-gpt-5.6-sol` 這類正常路由 id 在 CLI 可用，卻不會
+出現在 Desktop 的選擇器中。這是上游的 [Codex Desktop bug](https://github.com/openai/codex/issues/19694)，
+由 [opencodex #241](https://github.com/lidge-jun/opencodex/issues/241) 追蹤。
+
+當你控制一個等效的路由目標時，combo 可以明確接管一個原生 slug：
+
+```bash
+ocx combo set nova-sol \
+ --targets Nova1/codex/gpt-5.6-sol \
+ --alias gpt-5.6-sol \
+ --native-alias \
+ --display-name 'Nova1 - codex-gpt-5.6-sol'
+```
+
+此模式刻意採 opt-in，而且必須同時具備 `--native-alias` 與非空的顯示標籤。別名必須是這個
+opencodex 版本支援的原生模型 id 之一；僅有原生系列前綴不會被接受，因為移除時必須能恢復具權威性的
+中繼資料。當路由目標的 discovery 回應只提供模型 id 時，相容性列會從它所取代的原生 id 補上缺少的
+context、modality 與 reasoning 中繼資料。明確的目標限制仍然優先，因此這個 fallback 永遠不會提高
+context 上限或覆寫已宣告的能力。它會改變精確路由的優先順序：`gpt-5.6-sol` 的請求會先解析到
+`combo/nova-sol`，然後才是規範的 OpenAI 原生系列路由。目錄只包含一個帶所設定顯示標籤的裸列，
+而不是重複的原生列與 combo 列。只會捕捉裸的 `gpt-5.6-sol` slug。帳號限定列（如
+`main/gpt-5.6-sol`）與供應商限定列（如 `openai-apikey/gpt-5.6-sol`）仍是不同的 OpenAI 路由；
+供應商限定的 API-key 路由永遠不會落到原生別名上。
+
+可見性鍵依然明確：
+
+- `combo/nova-sol` 把相容性 combo 從 discovery 中隱藏。
+- `disabledModels` 中的裸 `gpt-5.6-sol` 項目仍然指休眠的原生 OpenAI 列；它不會隱藏目前擁有該
+ 公開 slug 的 combo。
+- 只要仍設定至少一個原生別名，被停用的裸原生列就會從有效 Codex 目錄中省略，而不是保留為
+ `visibility: "hide"`。這可以防止 Desktop 的 allowlist 復活不該顯示的列。Models 頁面仍會列出
+ 未被遮蔽的原生開關，重新啟用其中一個會恢復其保留或目前的原生中繼資料。
+
+:::caution
+原生別名刻意接管一個看起來像第一方模型的 id。只有在目標營運上等效、且誠實標示選擇器列時才使用它。
+移除 combo 會在下次 sync 時恢復正常原生路由與目錄身份。
+:::
+
+## 選擇策略
+
+### Failover：有序的主與後備
+
+`failover` 依設定順序選擇第一個合格目標。當目標的供應商存在、已啟用、未冷卻中、且能處理任何特殊請求限制時即為合格。權重與 `stickyLimit` 不影響此策略。
+
+給定此順序：
+
+1. `anthropic/claude-opus-4-8`
+2. `openai/gpt-5.6-sol`
+3. `google/gemini-3-pro`
+
+每個請求從 Anthropic 開始。Anthropic 的可重試失敗會將該請求移到 OpenAI；OpenAI 的可重試失敗可將它移到 Google。終端錯誤會立即停止，而不嘗試剩餘目標。
+
+### Round-robin：平滑加權批次
+
+`round-robin` 使用平滑加權輪詢。較大的目標權重讓該目標隨時間獲得較大份額，而不會將其所有份額一次送出為一長區塊。`stickyLimit` 控制在下次加權選擇前有多少成功請求留在所選目標上。
+
+建立一個 2:1 combo，每兩個成功請求為一批：
+
+```bash
+ocx combo set balanced \
+ --targets anthropic/claude-opus-4-8:2,openai/gpt-5.6-sol:1 \
+ --strategy round-robin \
+ --sticky 2
+```
+
+稱目標 **A**（權重 2）與 **B**（權重 1），前六次加權選擇為
+`A, B, A, A, B, A`。因為 `stickyLimit` 為 2，每次選擇維持活躍兩個成功請求：
+
+| 成功請求 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12 |
+| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
+| 目標 | A | A | B | B | A | A | A | A | B | B | A | A |
+
+長期份額仍為 2:1。可重試失敗會結束目前 sticky 批次、冷卻該目標，並為同一請求選擇另一個合格目標。
+
+:::caution
+權重是相對的，不是百分比。權重 `2,1` 與 `200,100` 表達同一比例。偏好能傳達意圖的小數值。
+:::
+
+## 目標失敗時會發生什麼
+
+Combo 失敗分為**跳轉**失敗與**終端**失敗。
+
+| 結果 | 行為 |
+| --- | --- |
+| HTTP 401、403、404、408、429 或任何 5xx | 冷卻目標並跳到下一個合格目標。 |
+| 分類為認證、訂閱、配額、限流、過載或上游伺服器錯誤 | 冷卻目標並跳轉，即使單靠狀態碼不足。 |
+| 客戶端取消（499）、`origin_rejected`、cyber-policy 拒絕、上下文溢出或無效請求 | 停止並回傳錯誤；另一個目標不會讓請求變為有效。 |
+| 任何其他未分類錯誤 | 停止並回傳錯誤。 |
+
+跳轉的目標預設進入 60 秒冷卻。若上游回應包含有效的 `Retry-After` 值，opencodex 改用它。接受數字秒與 HTTP-date 值，且每次冷卻上限為 10 分鐘。
+
+目前請求永不重試同一已嘗試目標。後續請求會略過它直到冷卻到期。若無合格目標剩餘，代理回傳 HTTP 503 並帶 `error.code = "combo_unavailable"`。
+
+:::note
+Failover 是刻意受限的。它有助於目標特定的可用性、認證、配額與過載失敗；不會隱藏呼叫者錯誤或策略拒絕。
+:::
+
+## 預設推理 effort
+
+`defaultEffort` 僅在以下全為真時提供 `reasoning.effort`：
+
+1. combo 有非 null 預設值；
+2. 呼叫者未設定 effort；且
+3. 所選目標的目錄宣告該精確 effort。
+
+若請求沒有 `reasoning` 物件，opencodex 建立一個。若 `reasoning` 存在但無 `effort` 屬性，它保留其他欄位並加入預設值。呼叫者提供的 effort 永不被覆寫。
+
+當目標能力未知或不包含設定的 effort 時，opencodex 省略預設值並保持目標自身行為不變。支援的值為 `low`、`medium`、`high`、`xhigh`、`max` 與 `ultra`；省略欄位或設為 `null` 可將 effort 完全交給呼叫者與目標。
+
+## 加密的 v2 子代理任務
+
+Codex v2 子代理有一個重要限制（[issue #92](https://github.com/lidge-jun/opencodex/issues/92)）。原生父代只能將新生成 worker 的任務以為原生 ChatGPT 後端鑄造的密文發送。外部供應商無法讀取該 payload。
+
+對於此類請求，combo 將其合格目標過濾為規範的原生 ChatGPT 路由，包括可重試失敗之後。若 combo 無可解密目標，opencodex 在分派前停止並回傳 HTTP 400：
+
+```json
+{
+ "error": {
+ "type": "invalid_request_error",
+ "code": "unreadable_encrypted_agent_task"
+ }
+}
+```
+
+這保護任務不被送往一個會收到無法讀取指令的供應商。可讀的明文任務使用正常 combo 策略。
+
+你有四個恢復選項：
+
+1. 為子任務選擇原生 ChatGPT 模型。
+2. 在 combo 中新增規範的原生 ChatGPT 目標。
+3. 對跨不同供應商的委派使用 v1 介面。
+4. 若你控制呼叫者，將任務以明文 v2 `agent_message` 內容重送。
+
+關於 v1/base/v2 模式與完整的加密任務工作流程，請見[子代理介面](/zh-tw/guides/sub-agent-surface/)。
+
+## 管理 combo
+
+### 儀表板
+
+開啟本機儀表板並選擇 **Combos**。該工作區可建立、編輯、重新命名與移除 combo，且其目標 picker 會排除已停用的模型與巢狀 combo。
+
+### CLI
+
+主要指令為：
+
+```bash
+ocx combo list
+ocx combo show
+ocx combo set --targets provider/model[:weight],...
+ocx combo remove --yes
+```
+
+`set` 也接受 `--strategy`、`--sticky`、`--effort`、`--alias` 與 `--rename-from`。用 `-` 作為 `--effort` 或 `--alias` 的值可清除該欄位。`create` 與 `update` 為 `set` 的別名；`delete` 為 `remove` 的別名；且相同子指令在 `ocx route combo` 下也可用。
+
+### 管理 API
+
+無頭客戶端在 `/api/combos` 上使用 `GET`、`PUT` 與 `DELETE`。`GET` 列出規範化的 combo 定義，`PUT` 建立或取代一個（且可重新命名一個），`DELETE` 接受 id 查詢參數。認證與請求/回應細節請見
+[管理 API 參考](/zh-tw/reference/management-api/)。
+
+完整的持久化設定請見[設定](/zh-tw/reference/configuration/)。
+
+## 設定參考
+
+Combo 儲存於頂層 `combos` 物件中，以 combo id 為 key：
+
+```json
+{
+ "combos": {
+ "balanced": {
+ "targets": [
+ { "provider": "anthropic", "model": "claude-opus-4-8", "weight": 2 },
+ { "provider": "openai", "model": "gpt-5.6-sol", "weight": 1 }
+ ],
+ "strategy": "round-robin",
+ "stickyLimit": 2,
+ "defaultEffort": "high",
+ "alias": "team/balanced"
+ }
+ }
+}
+```
+
+| 欄位 | 必填 | 預設值 | 規則 |
+| --- | --- | --- | --- |
+| `targets` | 是 | — | 已設定 `{ provider, model, weight? }` 目標的非空有序陣列。重複的供應商/模型對會被拒絕。 |
+| `targets[].weight` | 否 | `1` | 1 到 10,000 的整數。由 round-robin 使用；failover 忽略。 |
+| `strategy` | 否 | `"failover"` | `"failover"` 或 `"round-robin"`。 |
+| `stickyLimit` | 否 | `1` | 每次 round-robin 選擇的成功請求數，1 到 100 的整數。 |
+| `defaultEffort` | 否 | `null` | `low`、`medium`、`high`、`xhigh`、`max` 或 `ultra`；僅在呼叫者省略 effort 且目標宣告支援時套用。 |
+| `alias` | 否 | 無 | 可選的修剪後公開模型 id；使用上述別名規則。空值儲存為無別名。 |
+
+## 疑難排解
+
+### 為什麼 `combo/` 回傳 404？
+
+Combo id 未知。回應為 HTTP 404 並帶 type `invalid_request_error`。執行 `ocx combo list`、檢查拼字與大小寫，並確認你的管理指令寫入的是同一個接收模型請求的執行中 opencodex 實例。
+
+### 為什麼我得到 `combo_unavailable`？
+
+每個目標目前都不合格：例如其供應商已停用、冷卻中、已為此請求嘗試過，或加密 v2 任務排除它。檢查目標供應商狀態與近期上游錯誤。對於冷卻，等待 60 秒預設或上游 `Retry-After` 期間（絕不超過 10 分鐘），然後重試。
+
+### 為什麼我的別名被拒絕？
+
+先檢查別名文法與保留名稱。重複別名或無效形狀以 HTTP 400 拒絕；第一段為已設定 Codex 帳號命名空間的斜線別名以 HTTP 409 拒絕；請選擇不同的別名命名空間。CLI 與儀表板會顯示伺服器的精確驗證訊息。
+
+### 為什麼 failover 在第一個錯誤後就停止了？
+
+該錯誤是終端的而非目標特定的。修正無效輸入、縮減過大的上下文、處理策略拒絕，或更正被拒的請求來源。Combo 對那些情況不會跳轉。
diff --git a/docs-site/src/content/docs/zh-tw/guides/grok-build.md b/docs-site/src/content/docs/zh-tw/guides/grok-build.md
new file mode 100644
index 000000000..32ad70852
--- /dev/null
+++ b/docs-site/src/content/docs/zh-tw/guides/grok-build.md
@@ -0,0 +1,90 @@
+---
+title: Grok Build
+description: 透過 xAI 的 Grok Build CLI 使用任何由 opencodex 路由的模型——代理程式執行期間會將模型自動註冊到 ~/.grok/config.toml。
+---
+
+opencodex 在本機埠提供 OpenAI 相容的 `POST /v1/chat/completions`（以及 `/v1/responses`），而 Grok Build 支援對 OpenAI 相容伺服器使用自訂模型。從此整合開始，opencodex 會自動將其整個可見目錄註冊到 Grok Build——無需手動編輯設定。
+
+## 自動註冊
+
+當 `~/.grok` 存在時，`ocx start`（以及 `ocx ensure` / `ocx restart`）會將一個受管理區塊寫入 `~/.grok/config.toml`：
+
+```toml
+# >>> opencodex managed block — do not edit (removed by `ocx stop`) >>>
+[model.ocx-gpt-5-6-sol]
+model = "gpt-5.6-sol"
+base_url = "http://127.0.0.1:10100/v1"
+api_backend = "chat_completions"
+api_key = "opencodex-loopback"
+name = "OCX gpt-5.6-sol"
+# ... one [model.ocx-*] table per visible model ...
+# <<< opencodex managed block <<<
+```
+
+- **累加式：** 圍欄外你自己的設定絕不會被動到。在首次注入既有檔案前，會寫入一次性備份到 `~/.grok/config.toml.bak-opencodex`。
+- **冪等：** 每次 `ocx start`（以及啟用 autostart 時的 `ocx ensure`）都會以目前目錄取代圍欄區塊。
+- **拆除時移除：** `ocx stop`、`ocx eject`、`ocx uninstall`，以及非服務模式常駐程序的優雅關閉，都會剝除圍欄區塊並逐位元組還原你的檔案。在服務管理員之下，拆除會經由 `ocx stop`/`ocx uninstall` 進行（服務模式程序會刻意在重新產生時保留該區塊）。
+- **衝突安全：** 你自己的 `[model.*]` 表格中已定義的別名會被尊重（opencodex 會為自己的項目加上後綴）；若圍欄損壞（有開始標記但無結束標記），會拒絕任何自動變更並要求手動修復。
+
+然後在 Grok Build 內挑選模型：
+
+```bash
+grok models # lists ocx-* entries alongside native grok models
+grok -m ocx-anthropic-claude-opus-4-8 -p "hello"
+# or in the TUI: /model ocx-anthropic-claude-opus-4-8
+```
+
+## 推理 effort
+
+Grok Build 的 `/effort`（以及 `--effort`）只對目錄條目宣告了階梯的模型有效：它的模型清單擷取會讀取
+原始的 `GET /v1/models` 回應，而該處的條目必須帶有 `supports_reasoning_effort` 以及
+`reasoning_efforts` 選單選項。對已路由的模型條目，opencodex 會把設定的供應商階梯
+（`reasoningEfforts` / `modelReasoningEfforts`，以及 `modelDefaultReasoningEfforts` 的預設值）
+映象到該回應上。這份中繼資料描述的是 proxy 設定的路由階梯——它不代表原生產品的 reasoning 支援，
+而 adapter 可能模擬 reasoning 或把檔位對映到供應商專用欄位。設定了階梯的路由模型在 Grok Build 中
+會顯示 effort 控制項，就像在 Codex 中一樣。階梯清單為空的模型不會保留 effort 控制項，這也與
+Codex 行為一致。原生 GPT-5.6 條目則分開處理：它們保留並暴露固定於上游的 reasoning 階梯，而不是
+供應商設定的路由中繼資料。
+
+## 認證注意事項
+
+即使在 loopback 上，Grok Build 也要求自訂模型有非空的 API 金鑰。注入的項目會帶上占位值（`opencodex-loopback`）——opencodex 會忽略 loopback 連線的 admission key，因此不涉及真實金鑰。
+
+**自動註冊僅限 loopback。** 當 opencodex 綁定非 loopback 主機時——包含會暴露所有介面的萬用字元 `0.0.0.0` 與 `::`——請求需要你的真實 admission token，而受管理區塊無法安全地承載它。把字面 token 寫進去會把你的金鑰放進 `~/.grok/config.toml`，並在下一次 `ocx start`/`ensure`/`restart` 時覆寫你在那裡設定的任何內容。因此在這種情況下 opencodex 完全不寫入（並會移除先前 loopback 綁定留下的任何區塊），而你要在受管理標記之外自行設定模型，opencodex 就無法覆寫它們。精確的表格請見[手動配方](#manual-recipe-without-auto-registration)，並同時設定 `base_url`（你執行 `grok` 之處實際可達的主機）與 `api_key`（你的 `OPENCODEX_API_AUTH_TOKEN`）。
+
+此處不要用 `env_key` 取代 `api_key`。在未設定 `model_provider` 時，無法解析的 `env_key` 不會中止請求——Grok 會回退到你的 xAI 工作階段 token，並把它送到該項目所命名的任何 `base_url`；對 LAN 部署而言，那是一個並非 xAI 的明文 HTTP 端點。
+
+注入的 per-model `api_key` 在這些模型的 Grok 憑證鏈中排在第一位，因此對 opencodex 的回合不需要額外的 Grok 登入。請為原生 grok 模型，以及任何直接聯絡 xAI 的 harness 功能，保留你平常的 `grok login` / `XAI_API_KEY` 設定。
+
+## 手動配方（不使用自動註冊） {#manual-recipe-without-auto-registration}
+
+若你自行管理 `~/.grok/config.toml`——或 opencodex 綁定在非 loopback——請在 `# >>> opencodex managed block` 標記之外，以**直接欄位**新增 per-model 表格：
+
+```toml
+[model.ocx-opus]
+model = "anthropic/claude-opus-4-8"
+base_url = "http://127.0.0.1:10100/v1"
+api_backend = "chat_completions"
+api_key = "opencodex-loopback"
+```
+
+對於可經由網路連線的代理程式，將 `base_url` 指向 `grok` 實際可撥號的位址，並使用你的 admission token：
+
+```toml
+[model.ocx-opus]
+model = "anthropic/claude-opus-4-8"
+base_url = "http://192.168.1.10:10100/v1" # the reachable host, not 127.0.0.1
+api_backend = "chat_completions"
+api_key = "your-OPENCODEX_API_AUTH_TOKEN"
+```
+
+不要依賴 `[model_providers.]` 繼承端點：截至 Grok Build 0.2.101，繼承的 `base_url` 並不會套用到推論路由（請求會回退到預設 xAI 代理並以 401 失敗）。直接的 per-model 欄位才能正確路由。
+
+含有點號的別名請加上引號：裸的 `[model.grok-4.5]` 是三段式鍵路徑，而不是 id `grok-4.5`。產生的別名因此完全避免點號。
+
+## 已知限制
+
+- **Responses 後端與 keep-alive：** opencodex 會在上游靜默期間，於 `/v1/responses` 串流上發出 `response.heartbeat` keep-alive。Grok Build 的 Responses 解碼器會拒絕未知的事件類型，因此手動設定 `api_backend = "responses"` 的模型，可能在上游較慢時於回合中途失敗。自動註冊的項目會固定為 `api_backend = "chat_completions"`，不會露出原始 heartbeat 框架。
+- **以服務安裝的 `ocx restart`：** 當 opencodex 在服務管理員下執行時，`ocx restart` 目前會停止服務並以非受管程序取代——服務持續性（自動重啟、開機啟動）會遺失，直到下次 `ocx service` 設定；若該非受管程序死亡，受管理區塊可能指向已死的代理程式，直到下一次 `ocx start`/`ocx ensure` 重新整理它。
+- **設定讀取時機：** 先啟動 opencodex，再啟動 `grok`，結果最可預期。Grok Build 會監看 `~/.grok/config.toml`，並在 `[model]` 表格實際變更時重新載入（約一秒 debounce，依內容比對），因此重新整理後的區塊可在不重啟的情況下到達開啟中的工作階段。若要確認 Grok 解析了什麼，執行 `grok inspect`：它會列出已載入的設定來源，並對任何被拒絕的欄位發出警告。它不會印出解析後的模型清單。請注意，單一 TOML 錯誤會使*整個*使用者設定層失效，這也是 opencodex 以原子方式寫入檔案的原因——Grok 永遠看不到半寫入的設定。
+- **目錄更新：** 圍欄區塊反映注入當下的目錄。新增供應商或模型後，請執行 `ocx ensure`（或重啟代理程式）以重新整理它。
diff --git a/docs-site/src/content/docs/zh-tw/guides/image-bridge.md b/docs-site/src/content/docs/zh-tw/guides/image-bridge.md
new file mode 100644
index 000000000..d622c9ede
--- /dev/null
+++ b/docs-site/src/content/docs/zh-tw/guides/image-bridge.md
@@ -0,0 +1,69 @@
+---
+title: Image Bridge
+description: 在使用非 OpenAI 供應商時，將 image_generation hosted-tool 呼叫路由到 xAI Grok Imagine。
+---
+
+## 概觀
+
+當你透過非 OpenAI 模型（Claude、Gemini、Grok 等）路由 Codex 時，`image_generation` **hosted tool** 通常無法運作 — 它需要 OpenAI 的伺服器端執行環境。Image Bridge 偵測這些呼叫並透明地將它們重新路由到 xAI Grok Imagine，讓你實際對話的模型仍能生成圖片。
+
+## 前置條件
+
+- 在設定中設定 `images.bridgeEnabled: true` 以**啟用 bridge**（預設關閉以避免非預期的 xAI 費用 — 見下方[設定](#設定)）。
+- 一個帶有 **API key** 的 `xai` 供應商項目。Bridge 將履行釘選到 registry 的 xAI Images 端點（`https://api.x.ai/v1`）；任何已設定的 `baseUrl` 覆寫在圖片呼叫時會被忽略。單靠 OAuth / `ocx login xai` **不會**啟用 bridge（Grok CLI 的 OAuth transport 是聊天導向的，不用於 `/images/*`）。
+
+ ```json
+ {
+ "providers": {
+ "xai": { "adapter": "openai-chat", "apiKey": "xai-…", "authMode": "key" }
+ }
+ }
+ ```
+
+- 一個非 OpenAI 模型被選為你的活躍供應商。（當活躍供應商為 OpenAI 時，會直接使用原生 hosted tool，bridge 被略過。）
+
+## 設定
+
+Image Bridge 選項位於 `~/.opencodex/config.json` 的 `images` 之下。Bridging 為**選擇加入** — 你必須設定 `bridgeEnabled: true` 才能啟用付費的 xAI Grok Imagine 生成：
+
+```json
+{
+ "images": {
+ "bridgeEnabled": true,
+ "bridgeModel": "grok-imagine-image-quality",
+ "maxRounds": 3,
+ "timeoutMs": 60000
+ }
+}
+```
+
+| 選項 | 預設值 | 說明 |
+| --- | --- | --- |
+| `bridgeEnabled` | `false` | 總開關。設 `true` 啟用 bridging。預設關閉以避免非預期的 xAI 費用。 |
+| `bridgeModel` | `grok-imagine-image-quality` | 要將 prompt 送往的 xAI 圖片模型 id。 |
+| `maxRounds` | `3` | 每回合的最大圖片生成迴圈迭代數。向下取整為整數並限制在 `[0, 10]`；非有限值回退到 `3`。 |
+| `timeoutMs` | `60000` | 每次呼叫的 xAI 期限（毫秒）。有限正值會向下取整並傳給 xAI 請求。 |
+| `artifactsKeepCount` | `200` | `artifacts/` 下保留的最大檔案數。超過時，每次履行呼叫後刪除最舊的檔案。設為 `0` 或負值可停用修剪。 |
+
+## Artifact 保留
+
+生成的圖片寫入 `~/.opencodex/artifacts/`。為防止長時間執行的 session 無限制增長磁碟用量，目錄會在每次履行的圖片呼叫後自動修剪（該呼叫的完整批次上磁碟後）— 當數量超過設定的最大值（預設 200，可透過 `images.artifactsKeepCount` 設定）時，刪除最舊的檔案（依修改時間）。只有通過修剪的路徑會回傳給模型。
+
+## 運作方式
+
+Image Bridge 僅在選取了**非 OpenAI** 模型、且 **Responses** 回合的 `/v1/responses` tools 陣列中包含 hosted `image_generation` 工具時啟用。它**不會**攔截 Codex 內建的 `image_gen` 工具，該工具直接 POST 到 `/v1/images/generations`（或 `/images/edits`）— 該路徑另見 [Codex 整合](/zh-tw/guides/codex-integration/#built-in-image-generation-image_gen)。
+
+1. 當 Responses 請求在 `tools` 中列出 `image_generation` 時，OpenCodex 在請求前處理期間偵測到它。
+2. Hosted tool 被替換為一個路由模型可正常呼叫的**合成函式工具** — 模型看到的是一個可呼叫的工具，而非一個它無法執行的不透明 hosted tool。
+3. 當模型呼叫該工具時，OpenCodex 攔截呼叫並將 prompt 送往 xAI 的圖片生成 API。
+4. 生成的圖片儲存到 `~/.opencodex/artifacts/`，**本機檔案路徑**作為工具結果回傳給模型。
+5. 模型帶著對生成圖片及其位置的認知繼續對話。
+
+從模型角度什麼都沒變 — 它呼叫了一個工具並得到結果。從使用者角度，圖片生成可用於任何路由供應商，而非悄悄失敗。
+
+## 限制
+
+- **僅支援 xAI Grok Imagine。** DALL-E 與其他圖片供應商日後可能加入。
+- **網頁搜尋優先**，於支援網頁搜尋 sidecar 迴圈的 adapter 上。若同一回合同時請求網頁搜尋與圖片生成，會執行網頁搜尋並略過圖片生成。Cursor/`runTurn` adapter 目前無法使用該 sidecar，因此 image bridge 對那些雙工具回合仍可能執行。
+- **適用 xAI 費用。** 透過 xAI 的圖片生成需要有效的 xAI 訂閱或 API 額度。
+- **僅限串流。** Bridge 透過攔截 SSE 回應串流運作；帶有 `stream: false` 的請求會以 400 錯誤拒絕。
diff --git a/docs-site/src/content/docs/zh-tw/guides/integrations.md b/docs-site/src/content/docs/zh-tw/guides/integrations.md
new file mode 100644
index 000000000..d9ed0614a
--- /dev/null
+++ b/docs-site/src/content/docs/zh-tw/guides/integrations.md
@@ -0,0 +1,70 @@
+---
+title: 整合
+description: 從儀表板把 opencodex 連接到 OpenCode、Pi、OMP、Hermes、OpenClaw、Kimi Code 與 Gajae Code——每個客戶端一個開關，每次寫入前都會先備份。
+---
+
+**整合（Integrations）** 分頁會把 opencodex 的 provider 區塊寫入客戶端自己的設定檔，也會把它移除。共有七個客戶端以這種方式運作，每個都有一個開關：
+
+| 客戶端 | 設定檔 | 格式 | 變更生效時機 | 憑證 |
+|---|---|---|---|---|
+| OpenCode | `~/.config/opencode/opencode.json` | JSON | 下次直接啟動 | `OPENCODEX_OPENCODE_API_KEY` |
+| Pi | `~/.pi/agent/models.json` | JSON | 新 sessions | loopback 佔位符 |
+| OMP | `~/.omp/agent/models.yml` | YAML | 重新啟動 OMP 後 | `opencodex-loopback` 佔位符 |
+| Hermes | `~/.hermes/config.yaml` | YAML | 新 sessions | `OPENCODEX_HERMES_API_KEY` |
+| OpenClaw | `~/.openclaw/openclaw.json` | JSON5 | 立即，在執行中的 gateway 上 | `OPENCODEX_OPENCLAW_API_KEY` |
+| Kimi Code | `~/.kimi-code/config.toml` | TOML | 重新啟動時，或 `/reload` | loopback 佔位符 |
+| Gajae Code | `~/.gjc/agent/models.yml` | YAML | 新 sessions，或當你開啟 `/model` 時 | `OPENCODEX_GAJAE_API_KEY` |
+
+路徑遵循客戶端自己的環境覆寫（environment override）。對 OMP 而言，`OMP_PROFILE` 以存在與否優先於 `PI_PROFILE`，即使明確為空也一樣。具名 profile 會把 `PI_CONFIG_DIR` 當作相對於使用者家目錄的目錄名稱，並忽略 `PI_CODING_AGENT_DIR`；沒有具名 profile 時，`PI_CODING_AGENT_DIR` 勝出。OMP 支援 provider 層級的 headers，但這個最初的整合刻意只支援 loopback；遠端 `x-opencodex-api-key` 的連線設定被延後。搬移過的 `HERMES_HOME`、`KIMI_CODE_HOME` 與 `XDG_CONFIG_HOME` 路徑同樣會被遵循，而非猜測。表格列出每個客戶端的預設值。
+
+對原生 OpenAI 模型，產生的 OMP 區塊會選用其模型層級的 Responses API，保留圖片輸入與 reasoning-effort 控制。路由模型則維持 provider 的 Chat Completions 方言，讓它們既有的 adapters 保持相容。
+
+OpenClaw 有數個環境變數，各自負責不同的工作。`OPENCLAW_CONFIG_PATH` 選擇檔案；`OPENCLAW_STATE_DIR`、`OPENCLAW_PROFILE` 與 `OPENCLAW_HOME` 選擇狀態目錄，而偵測看的也是狀態目錄——所以 profile 或搬移過的家目錄仍會被視為已安裝，而 config 路徑覆寫只移動檔案。如果你還在用舊的 `.clawdbot` 配置，那也會被找到：現代目錄存在時勝出，只有舊目錄存在時才使用舊的。
+
+這些必須是**絕對路徑**或以 `~` 開頭。相對路徑會被拒絕而非解析，因為它會指向各程序恰巧啟動時所在的目錄——而該路徑會與備份一起儲存，所以它明天必須指向與今天相同的檔案。
+
+opencodex 從自己的環境讀取這些變數。如果你的 gateway 以 profile 或搬移過的家目錄執行，請以相同的變數啟動 opencodex，否則它會正確地遵循另一個安裝。
+
+## 其他四個介面不是開關
+
+**API Keys** 管理 opencodex 自己的憑證，根本不是客戶端。**Codex CLI** 由 proxy 服務本身連接——啟動 opencodex 即套用，停止即回復原生路由——所以沒有什麼需要逐檔切換。**Claude** 保留自己的啟用旗標與 Desktop 的 Save/Apply 流程，**Grok Build** 保留其先選後套用的模型圍欄（model fence）。那些語意早於這項功能，且維持不變。
+
+## 回復（Rollback）
+
+每次成功的寫入都會*先*為你的檔案拍快照，所以你原本的狀態永遠可以回復：
+
+- **Undo** 會出現在最新操作上，當你的檔案仍與我們寫入的內容相符時。
+- **Restore this point…** 會出現在較舊的操作上，或當檔案在那次操作之後有變更時。跨過這樣的變更做回復會再詢問一次，才覆蓋你的較新編輯——並且也會備份它們，所以那次的回復本身也可以復原。
+- 每個客戶端保留十份備份。超過之後，最舊的快照檔案會被移除，其歷史列顯示為 **Backup expired**。
+
+停用只移除 opencodex 記錄為自己寫入的條目。如果你的檔案在我們寫入之後有變更，開關會鎖定，停用會拒絕執行，而不是猜測哪些編輯是你的。
+
+## 誠實的預期
+
+**格式通常不會被保留。** 套用會解析設定並重新寫出，所以 JSON、JSON5 與 TOML 可能被重新格式化，JSON5 或 TOML 中的註解會遺失。OMP 是例外：它的 YAML writer 只修補 `providers.opencodex`，逐位元組保留無關的 provider 註解與格式。如果無法安全地識別那個確切的來源範圍，操作會拒絕執行。對其他客戶端，當你需要先前的檔案位元組時請使用 Restore：快照是逐字的副本。
+
+**如果某個值無法忠實重寫，開關會拒絕執行。** 往返覆蓋這些格式在實務上會用到的值種類；當它做不到時——例如使用 `inf` 或 `nan` 的 TOML 檔案，我們可用的 parser 無法準確讀回——套用會停止並說明，而不是寫入被改動的值然後宣稱成功。你會看到檔案被指名，磁碟上沒有任何東西被移動。手動編輯那個檔案仍然有效；只有我們的自動重寫會拒絕。
+
+**Pi、Kimi Code 與 Gajae Code 只能對 loopback bind 運作。** 它們的設定 schema 沒有非 loopback bind 所需的 `x-opencodex-api-key` header 的位置，所以產生的設定只會被拒絕。改用 loopback 存取，透過 SSH tunnel 或加入該 header 的本機 forwarder。
+
+**產生的 OMP 整合也刻意只支援 loopback。** OMP 確實支援 provider 層級的 headers，但這個最初的整合不會發出遠端 `x-opencodex-api-key` 憑證連線。手動的遠端 OMP 設定目前不在受管理的整合範圍內。
+
+**Kimi Code 無法持有環境變數參考，** 所以它的設定攜帶的是 `opencodex-loopback` 佔位符而非金鑰。絕不會有任何真實憑證被寫入任何客戶端設定。
+
+**對 `ocx opencode` 而言，launcher 的 provider 區塊勝出。** 那個 launcher 透過 `OPENCODE_CONFIG_CONTENT` 注入 `provider.opencodex`，比磁碟上相同的條目優先——你其餘的 opencode 設定仍照常套用。當你直接啟動 `opencode` 時，這裡的開關才是關鍵。
+
+## 從終端機
+
+相同的操作可以無頭模式使用：
+
+```bash
+ocx integration client status
+ocx integration client enable --client hermes
+ocx integration client disable --client hermes
+ocx integration client history --client hermes
+ocx integration client restore --op [--confirm-drift]
+```
+
+`--confirm-drift` 永遠不會被擅自假設。如果檔案在你正要回復的操作之後有變更，指令會拒絕並告訴你，因為覆蓋你較新的編輯是你的決定。
+
+客戶端細節是針對各專案自己的設定格式驗證過的；檢查了什麼、何時檢查，請見 `devlog/_fin/260802_client_toggle_api/002_client_toggle_matrix.md` 中的研究筆記。
diff --git a/docs-site/src/content/docs/zh-tw/guides/model-ordering.md b/docs-site/src/content/docs/zh-tw/guides/model-ordering.md
new file mode 100644
index 000000000..efd505db8
--- /dev/null
+++ b/docs-site/src/content/docs/zh-tw/guides/model-ordering.md
@@ -0,0 +1,101 @@
+---
+title: 模型排序
+description: opencodex 如何確定 Codex 模型選擇器和 spawn_agent 模型 override 的順序。
+---
+
+Codex 模型選擇器不會保留 opencodex 設定中 provider 的宣告順序或模型陣列順序。最終順序由目錄
+priority 決定；priority 相同的路由模型則使用確定性的字母順序。
+
+## Codex 應用的規則
+
+Codex 的 models-manager 按 `priority` 升序排列選擇器中可見的目錄條目。目錄陣列本身的順序會被
+丟棄，因此在生成的 JSON 陣列中把某個條目前移，並不會讓它在選擇器中前移。該約束直接記錄在
+`src/codex/catalog/sync.ts` 中。
+
+因此，opencodex 透過分配更低的 priority 控制置頂位置，而不依賴陣列位置。相關 priority 如下：
+
+| 目錄條目 | Priority | 來源 |
+| --- | ---: | --- |
+| `subagentModels[i]` | `i`（`0` 至 `4`） | `src/codex/catalog/sync.ts` 中的 featured rank map |
+| 其他路由模型 | `5` | `src/codex/catalog/sync.ts` 中建立路由條目的邏輯 |
+| 預設原生 GPT slug | `9` | `src/codex/catalog/sync.ts` 中建立原生條目的邏輯 |
+| 存在 featured 列表時未選中的原生模型 | 至少為 `featured.length + 100` | `src/codex/catalog/sync.ts` 中合併原生目錄的邏輯 |
+
+管理 API 在 `src/server/management/agent-settings-routes.ts` 中使用 `slice(0, 5)`，把
+`subagentModels` 限制為最多五項。這與 Codex `spawn_agent` 介面只公佈前五個模型 override 的行為
+一致。五項之外的模型仍可繼續顯示在主選擇器中，也可透過精確 id 呼叫。
+
+## Priority 相同時如何排序
+
+所有普通路由模型的 priority 都是 `5`，因此需要處理並列順序。在建立目錄條目之前，
+`gatherRoutedModels()` 會先按 provider 名稱、再按模型 id 對路由模型列表進行字母排序
+（`src/codex/catalog/provider-fetch.ts`）。
+
+因此，以下設定順序不會影響最終順序：
+
+- `providers` 物件中各 key 的宣告順序；
+- 每個 provider 的 `models` 陣列中各 id 的排列順序。
+
+隨後，`orderForSubagents()` 使用穩定排序，把 featured 模型按 `subagentModels` 中的順序移到最前。
+非 featured 模型會保持之前確定的 provider/id 字母相對順序
+（`src/codex/catalog/sync.ts`）。建立條目時，featured rank 還會轉換為 `0` 至 `4` 的
+priority，因此 Codex 的 priority 排序會保留這個開頭序列。
+
+## 可見性與排序彼此獨立
+
+`selectedModels` 和 `disabledModels` 只決定暴露哪些路由模型，不控制排序。
+`filterCatalogVisibleModels()` 會把兩類選擇轉換為 `Set` 查詢，並在不把陣列當作 rank 的情況下過濾
+已收集的列表（`src/codex/catalog/provider-fetch.ts`）。
+
+因此，調整 `selectedModels` 或 `disabledModels` 的陣列順序不會改變模型在選擇器中的位置，只會
+影響模型是否包含在內。
+
+## 最終選擇器順序
+
+featured 列表非空時，最終順序為：
+
+1. 嚴格按照設定的 `subagentModels` 順序排列，priority 為 `0` 至 `4`；
+2. 所有剩餘路由模型，先按 provider、再按模型 id 的字母順序排列，priority 為 `5`；
+3. 在目錄合併過程中被移到 featured 區塊之後的未選中原生模型。
+
+如果沒有 `subagentModels`，路由模型保持 priority `5`，原生 GPT 條目使用正常 priority
+（opencodex 建立的條目通常為 `9`），路由組內部仍按 provider/id 字母排序。
+
+## 示例
+
+假設 `subagentModels` 按以下順序包含五個 id：
+
+```toml
+subagentModels = [
+ "gpt-5.5",
+ "opencode-go/glm-5.2",
+ "anthropic/claude-opus-4-6",
+ "gpt-5.6-sol",
+ "gpt-5.6-terra",
+]
+```
+
+選擇器開頭的實際順序如下：
+
+| 選擇器位置 | 模型 | Priority | 出現在此處的原因 |
+| ---: | --- | ---: | --- |
+| 1 | `gpt-5.5` | `0` | 第一個 `subagentModels` 選擇 |
+| 2 | `opencode-go/glm-5.2` | `1` | 第二個選擇，即使其 provider 在字母順序上位於 `anthropic` 之後 |
+| 3 | `anthropic/claude-opus-4-6` | `2` | 第三個選擇 |
+| 4 | `gpt-5.6-sol` | `3` | 第四個選擇 |
+| 5 | `gpt-5.6-terra` | `4` | 第五個選擇 |
+| 6 | `anthropic/claude-fable-5` | `5` | 剩餘路由模型中按 provider/id 字母排序的第一項 |
+| 第 7 項起 | 其餘路由模型 | `5` | 先按 provider 字母排序，再按模型 id 字母排序 |
+| 路由模型之後 | 其餘原生模型 | `featured.length + 100` 或更高 | 未選中的原生模型移到 featured 區塊之後 |
+
+前五個條目是向 `spawn_agent` 公佈的 override，其餘模型繼續按普通選擇器順序排列。
+
+## 更改順序
+
+自訂開頭模型順序的唯一受支援方式是重新排列 `subagentModels`。你可以在儀表板的
+**Sub-agents** 頁面或 opencodex 設定中修改它。該列表最多接受五個模型，其陣列順序有實際意義。
+
+目前 `OcxConfig` 中沒有通用的 `modelOrder`、`providerOrder` 或 priority map 設定。受支援的排序
+欄位是 `subagentModels`（`src/types.ts:238-246`）；`disabledModels` 和各 provider 的
+`selectedModels` 都是可見性欄位（`src/types.ts:276-282`、`src/types.ts:439-446`）。因此，要更改
+選擇器其餘部分的順序，需要修改程式碼行為，而不是調整設定。
diff --git a/docs-site/src/content/docs/zh-tw/guides/model-routing.md b/docs-site/src/content/docs/zh-tw/guides/model-routing.md
new file mode 100644
index 000000000..a3cb08885
--- /dev/null
+++ b/docs-site/src/content/docs/zh-tw/guides/model-routing.md
@@ -0,0 +1,78 @@
+---
+title: 模型路由
+description: opencodex 如何決定由哪個供應商來服務給定的模型 id。
+---
+
+當 Codex 請求某個模型時，`router.ts` 會將其解析為唯一一個已設定的供應商。規則**按順序**檢查；第一個匹配者勝出。
+
+OpenAI 的 bare `gpt-*` 使用單一 `openai` provider。`codexAccountMode` 在 Pool（預設，主帳號加
+新增帳號）和 Direct（目前 caller/主登入 bearer）之間選擇，模型 id 不變。
+`openai-apikey/` 顯式使用 API key transport；兩條憑證路徑互不 fallback。
+
+## 優先順序
+
+1. **顯式 `provider/model`** —— 如果 id 包含 `/`，且斜槓前的部分是某個已設定供應商的名稱，則使用該供應商，並將 id 擷取為斜槓之後的部分。
+
+ ```text
+ anthropic/claude-opus-5 → provider "anthropic", model "claude-opus-5"
+ ollama-cloud/glm-5.2 → provider "ollama-cloud", model "glm-5.2"
+ openrouter/openai/gpt-5.6-sol → provider "openrouter", model "openai/gpt-5.6-sol"
+ ```
+
+ 這是無歧義的寫法，也是 Codex 的模型選擇器對路由模型所使用的寫法。如果指定的供應商已停用，
+ 這種顯式寫法會直接丟擲錯誤。
+
+2. **某個供應商的 `defaultModel`** —— 如果任一供應商的 `defaultModel` 等於該 id，則使用該供應商（id 原樣傳遞）。
+
+3. **內建字首模式** —— 將 id 與已知的模型系列字首進行匹配，然後路由到名稱（或名稱字首）與之相符的已設定供應商：
+
+ | 字首 | 供應商 |
+ | --- | --- |
+ | `claude-`、`claude-sonnet-`、`claude-opus-`、`claude-haiku-` | `anthropic` |
+ | `gpt-`、`o1-`、`o3-`、`o4-` | bare id 使用已設定的 `openai` 帳號模式；API key 顯式使用 `openai-apikey/` |
+ | `llama-`、`mixtral-`、`gemma-` | `groq` |
+
+ 該匹配器只檢查名稱。與 `defaultModel` / `models[]` 掃描不同，目前即使匹配供應商的 `disabled`
+ 為 true，它也不會跳過該供應商。
+
+4. **某個供應商的 `models[]`** —— 如果字首規則沒有命中，而某個啟用的供應商在 `models[]` 中列出
+ 該 id，則使用該供應商。這個順序很重要：只要設定了 OpenAI 名稱的供應商，裸 `gpt-*` id 就會在
+ 其他供應商的 `models[]` 宣告之前路由到 OpenAI。
+
+5. **預設供應商** —— 如果沒有任何匹配，id 將原樣傳送給 `config.defaultProvider`。（如果未設定預設供應商，或預設供應商已停用，路由會丟擲例外。）
+
+## API 金鑰與環境變數
+
+無論選擇哪條路由，供應商的 `apiKey` 都會透過 `resolveEnvValue()` 解析：值為 `${OPENAI_API_KEY}` 或 `$OPENAI_API_KEY` 時會在請求時從環境中展開，因此金鑰永遠無需存放在 `config.json` 中。
+
+## 目錄可見性與上下文上限
+
+請求路由和模型目錄可見性由不同設定控制：
+
+- `disabledModels` 會從 Codex 目錄和 `/v1/models` 中隱藏帶名稱空間的路由 id。裸原生 GPT slug
+ 仍保留在目錄中，但會改為 `visibility: "hide"`。它**不會**拒絕對該模型的直接請求。
+- 供應商的非空 `selectedModels` 是另一層目錄 allowlist。即時發現和直接路由仍然有效；它只會縮小
+ 目錄和 `/v1/models` 輸出的模型範圍。
+- `provider.disabled: true` 會把該供應商排除在目錄發現之外。顯式 `provider/model` 請求會失敗，
+ `defaultModel` / `models[]` 掃描也會跳過它。
+- `providerContextCaps` 為各供應商設定 Codex 可見的上下文上限。`contextCapValue` 是儀表板共用的值，
+ 預設為 350,000；但只有 `providerContextCaps` 中列出了供應商時才會生效。上限只能降低已知上下文，
+ 不會把它調高，也不會改變上游模型的實際限制。
+
+```json
+{
+ "contextCapValue": 350000,
+ "providerContextCaps": {
+ "anthropic": 350000,
+ "cursor": 350000
+ }
+}
+```
+
+## 提示
+
+- **對路由模型使用顯式寫法。** 優先使用 `provider/model`（規則 1）——它無歧義，並且與目錄同步後 Codex 在其選擇器中顯示的內容一致。
+- **為供應商預置 `models[]` 或 `defaultModel`**，這樣短 id（規則 2/4）無需 `provider/` 字首即可解析。
+- **字首模式只是一種便利**，而非保證：只有當確實設定了同名（例如 `anthropic`、`openai`、`groq`）的供應商時，它們才會解析成功。
+
+這些規則讀取的供應商欄位請參見 [設定](/zh-tw/reference/configuration/)。
diff --git a/docs-site/src/content/docs/zh-tw/guides/opencode.md b/docs-site/src/content/docs/zh-tw/guides/opencode.md
new file mode 100644
index 000000000..ccb150ce2
--- /dev/null
+++ b/docs-site/src/content/docs/zh-tw/guides/opencode.md
@@ -0,0 +1,114 @@
+---
+title: opencode
+description: 在 opencode 使用任何由 opencodex 路由的模型——執行時注入 provider 區塊，不更動你自己的 opencode 設定。
+---
+
+opencode 從合併的 JSON 設定層讀取供應商，而不是環境變數，因此沒有可注入的 `ANTHROPIC_BASE_URL` 這類插槽。`ocx opencode` 補上這個缺口：它會確保代理程式正在執行、依可見目錄組出 provider 區塊，並透過 OpenCode 的內嵌 runtime 層（`OPENCODE_CONFIG_CONTENT`）注入。
+
+## 快速入門
+
+```bash
+ocx opencode
+```
+
+這會確保代理程式正在執行，並僅以產生的 `provider.opencodex` 區塊啟動該次 opencode 程序。額外引數會原樣傳遞：`ocx opencode run "hello"`。
+
+路由模型會出現在選擇器的 `opencodex` 供應商底下：
+
+```text
+opencodex/kiro/glm-5
+opencodex/gpt-5.6-sol # native slugs stay unprefixed
+```
+
+## 你自己的設定絕不會被修改
+
+啟動器不會複製或改寫 `~/.config/opencode/opencode.json`、專案的 `opencode.json` / `opencode.jsonc`，或任何其他磁碟上的設定層。它可能會讀取全域或專案設定以偵測 `provider.opencodex` 覆寫，而你既有的供應商、agents、keybinds、MCP 項目，以及相對路徑的 `{file:…}` 參考，仍會從原本的檔案解析。
+
+僅就此啟動，opencodex 會透過 OpenCode 的內嵌 runtime 層加入產生的 `provider.opencodex` 區塊。該層在全域／自訂／專案設定之後合併，且只覆寫子程序中衝突的鍵。
+
+| 層 | 搭配 `ocx opencode` 的行為 |
+| --- | --- |
+| 全域／自訂／專案設定 | 磁碟上維持你寫下的原樣 |
+| 內嵌 runtime（`OPENCODE_CONFIG_CONTENT`） | 只接收產生的 `provider.opencodex` 區塊 |
+| 相對 `{file:…}` 路徑 | 仍相對於原本定義它們的設定檔解析 |
+
+若全域或專案設定也定義了 `provider.opencodex`，啟動器會印出資訊提示：該次啟動由 `ocx opencode` 提供的 runtime 層會覆寫它。
+
+## 把區塊放進你自己的設定
+
+`ocx opencode` 只針對單次啟動注入 provider 區塊，意思是普通的 `opencode` 仍然不知道 proxy 的存在。
+當你想要一般的 `opencode`——或從不經過啟動器的編輯器擴充功能——也能使用路由模型時，`ocx export`
+會為你印出相同的 provider 區塊，讓你合併進自己的設定：
+
+```bash
+ocx export --client opencode
+```
+
+代理程式必須正在執行。該命令會印出設定內容、規範目的地
+（`~/.config/opencode/opencode.json`，或設定 `XDG_CONFIG_HOME` 時位於其下）、合併警告，以及
+env 匯出指令。它永遠不會碰那個檔案——前面一節仍然成立，把區塊放進你的設定是你自己的明確行為。
+
+:::caution[合併，不要取代]
+把 `provider.opencodex` 區塊合併進你既有的設定。用匯出的內容取代整個檔案會摧毀你的其他供應商、
+agents、keybinds 與 MCP 項目。`ocx export --out` 正是為了這個原因拒絕覆寫既有檔案，所以請把
+`--out` 指向暫存路徑，再把區塊複製過去：
+
+```bash
+ocx export --client opencode --out ~/opencodex-opencode.json
+```
+:::
+
+與啟動器的 runtime 區塊不同，合併後的區塊是靜態快照：它不會跟著你的目錄變動。新增供應商或變更
+模型可見度之後，請重新執行 `ocx export`。
+
+合併完成後，在啟動 opencode 之前先匯出 admission key——除非 proxy 在 loopback 上，此時不需要：
+
+```bash
+export OPENCODEX_OPENCODE_API_KEY=
+```
+
+## Admission key 不會寫入磁碟
+
+當代理程式要求 API 金鑰時，內嵌 runtime 設定承載的是 opencode 的 `{env:…}` 參考，而不是金鑰本身。Loopback 綁定把該參考用作 `apiKey`；非 loopback 綁定則只透過 `x-opencodex-api-key` 傳送，讓代理 admission 與任何上游 `Authorization` 標頭保持分離。
+
+Loopback 範例：
+
+```json
+"options": {
+ "baseURL": "http://127.0.0.1:10100/v1",
+ "apiKey": "{env:OPENCODEX_OPENCODE_API_KEY}"
+}
+```
+
+非 loopback 範例：
+
+```json
+"options": {
+ "baseURL": "http://192.168.1.10:10100/v1",
+ "headers": {
+ "x-opencodex-api-key": "{env:OPENCODEX_OPENCODE_API_KEY}"
+ }
+}
+```
+
+真實值只會經由子程序環境傳遞。優先順序為 `OPENCODEX_API_AUTH_TOKEN`，再來是 hardened service token 檔，然後才是已設定的 API 金鑰——非 loopback 綁定需要後者。
+
+## 還原
+
+沒有需要還原的東西——`~/.opencodex` 下不會寫入產生的設定檔。直接執行 `opencode`，就會完全照你自己的設定讀取。
+
+## 模型限制
+
+只有在目錄回報具權威性的 context window 時，才會寫入 `limit.context`；若沒有，會省略整個 `limit` 區塊，opencode 沿用自己的預設值。
+
+opencode 的 schema 會拒絕只有 `context`、沒有 `output` 的 `limit` 區塊，而目錄又沒有具權威性的 per-model output 欄位，因此會一併發出 `output` 預算 `32000`，並向下 clamp 到 context window，避免小 context 模型出現 `output > context`。這個數字是為了滿足 schema——並非宣稱任何特定模型的真實上限。
+
+`opencodex` provider 區塊每次啟動都會重新產生，因此在裡面做的 per-model 調整不會保留。請把自訂項目放在你自己的 provider 鍵底下。
+
+## 需求
+
+opencode 必須已安裝並位於 `PATH`：
+
+```bash
+npm install -g opencode-ai
+```
diff --git a/docs-site/src/content/docs/zh-tw/guides/pi.md b/docs-site/src/content/docs/zh-tw/guides/pi.md
new file mode 100644
index 000000000..035333857
--- /dev/null
+++ b/docs-site/src/content/docs/zh-tw/guides/pi.md
@@ -0,0 +1,99 @@
+---
+title: Pi
+description: 使用 Pi 的任何路由模型 — ocx export 會為 Pi 的 models.json 寫入自訂供應商區塊，連接到執行中的代理。
+---
+
+Pi 從單一全域 JSON 檔案而非環境變數讀取其供應商，因此 opencodex 不會啟動它。相反地，`ocx export` 序列化 `opencodex` 供應商區塊 — base URL、模型清單，以及 Pi 會插入的環境參考 — 然後你將其合併到自己的設定中。
+
+## 快速入門
+
+啟動代理，然後印出設定：
+
+```bash
+ocx start
+ocx export --client pi
+```
+
+輸出以 JSON 開頭，接著印出目標路徑、合併警告、環境匯出行，以及有多少模型帶有權威的上下文限制。
+
+```json
+{
+ "providers": {
+ "opencodex": {
+ "baseUrl": "http://127.0.0.1:10100/v1",
+ "api": "openai-completions",
+ "apiKey": "$OPENCODEX_API_KEY",
+ "models": [
+ {
+ "id": "anthropic/claude-opus-5",
+ "name": "Claude Opus 5 (anthropic)",
+ "input": ["text"],
+ "contextWindow": 200000,
+ "maxTokens": 32000
+ }
+ ]
+ }
+ }
+}
+```
+
+模型 id 是代理的規範選擇器，因此路由模型顯示為 `provider/model`（`anthropic/claude-opus-5`），而原生 OpenAI slug 保持無前綴（`gpt-5.6-sol`）。`name` 後綴 — `(anthropic)`、`(native)`、`(routed)` — 正是讓來自不同上游的兩個同名模型在 Pi 的 picker 中可區分的關鍵。
+
+## 放置位置
+
+Pi 的全域模型設定為：
+
+```text
+~/.pi/agent/models.json
+```
+
+:::caution[合併，絕不替換]
+`ocx export` 永不寫入該檔案。將 `providers.opencodex` 區塊合併進去 — 替換該檔案會毀掉你在那裡設定的所有其他供應商。`--out` 用於暫存路徑，且在沒有 `--force` 時拒絕覆寫既有檔案：
+
+```bash
+ocx export --client pi --out ~/opencodex-pi-models.json
+ocx export --client pi --json > ~/opencodex-pi-models.json # 或重導逐字元的 JSON
+```
+
+:::
+
+匯出的區塊是靜態快照，非即時檢視。在新增供應商或改變模型可見性後，重新執行 `ocx export`，並將新區塊合併到舊區塊上。
+
+## 認證金鑰
+
+這裡有兩種不同的 key 容易混淆，且只有第一個出現在此檔案中：
+
+| Key | 是什麼 | 位於何處 |
+| --- | --- | --- |
+| 代理認證 key | opencodex 自身的憑證，在儀表板的 **API** 分頁產生 | 由 `apiKey` 以 `$OPENCODEX_API_KEY` 參照；值留在你的環境中 |
+| 供應商 key | 你的 Anthropic / OpenAI / OpenRouter key | opencodex 自身的設定，見[供應商](/zh-tw/guides/providers/) |
+
+匯出的設定僅帶有參照，絕不帶金鑰。Pi 會插入裸 `$NAME`，因此該變數為：
+
+```bash
+export OPENCODEX_API_KEY=
+```
+
+該名稱是 Pi 專屬的。opencode 使用不同的變數
+（`OPENCODEX_OPENCODE_API_KEY`，採 `{env:…}` 形式）— 見 [opencode 指南](/zh-tw/guides/opencode/)。
+
+**回送代理完全不需要 key。** opencodex 預設綁定 `127.0.0.1` 且在那裡不認證任何東西，因此 `$OPENCODEX_API_KEY` 參照是無效的，你可以讓變數未設定。它只在 `hostname` 設定到回送以外時才重要，這也是代理在沒有 token 時拒絕啟動的情況 — 見[遠端存取](/zh-tw/reference/configuration/#remote-access)。
+
+## 模型後設資料
+
+`contextWindow` 與 `maxTokens` 僅在目錄回報權威上下文窗口時發出。若未回報，該模型的兩個欄位都會省略，Pi 會套用自身預設值；`ocx export` 會印出有多少列屬於該情況。
+
+`maxTokens` 是滿足 schema 的 `32000` 預算，並限制在不超過上下文窗口，使得小上下文模型永遠不會被給予超過上下文的輸出量。它並非對任何特定模型真實最大值的聲明。
+
+有兩個欄位刻意省略。`cost` 需要全部四個價格欄位，而 opencodex 對路由模型沒有價格資料 — 發出零值會斷言每個模型都是免費的。`reasoning` 在 Pi 中是 boolean，而目錄帶有 effort 階梯，將兩者互相映射會是猜測。
+
+## Schema 狀態
+
+:::note[未對真實安裝驗證]
+上述形狀遵循 Pi 公開的自訂供應商文件。它**尚未**在裝有 Pi 的機器上對真實的 `~/.pi/agent/models.json` 驗證。若 Pi 拒絕匯出的區塊，不符出在我們這邊 — 請
+[開一個 issue](https://github.com/lidge-jun/opencodex/issues) 並附上 Pi 回報的內容。
+:::
+
+## 需求
+
+一個執行中的 opencodex 代理（`ocx start`）與已安裝的 Pi。`ocx export` 透過代理的管理 API 讀取即時目錄，因此設定永遠不會以空模型清單發出。
diff --git a/docs-site/src/content/docs/zh-tw/guides/providers.md b/docs-site/src/content/docs/zh-tw/guides/providers.md
new file mode 100644
index 000000000..b21bc6e98
--- /dev/null
+++ b/docs-site/src/content/docs/zh-tw/guides/providers.md
@@ -0,0 +1,510 @@
+---
+title: 供應商
+description: opencodex 進行身分驗證並與 LLM 供應商通訊的所有方式——OAuth、API 金鑰、ChatGPT 轉送與本機。
+---
+
+**供應商（provider）** 是一個上游 LLM 端點，加上存取它的方式：adapter、base URL、認證模式，以及
+可選的模型列表。供應商設定放在 `~/.opencodex/config.json` 的 `providers` 下。
+
+## OpenAI 帳號模式
+
+| Provider id | 用途 | 憑證／帳號規則 |
+| --- | --- | --- |
+| `openai` | Codex 登入 | Pool（預設）選擇主帳號與新增帳號；Direct 只使用目前 caller／主登入。 |
+| `openai-apikey` | OpenAI API | 只使用已設定的 API key／key pool；絕不讀取 Codex 帳號。 |
+
+在 Providers 頁面使用裸 `gpt-5.6-sol` 搭配 Pool／Direct 選項，或使用
+`openai-apikey/gpt-5.6-sol` 走 API。憑證路徑不會彼此 fallback。API 路徑發布的 metadata 為
+1,050,000 context／922,000 max input；`sol-pro`、`terra-pro` 與 `luna-pro` virtual id 會保留使用者
+選到的公開 identity，但 wire 會改用 base model 加上 `reasoning.mode: "pro"`。
+
+若內建 `openai` 供應商缺失或已停用，儀表板 Accounts picker 與 Codex Auth 頁面可以恢復它：缺失的 row
+會從 canonical preset 建立；已停用的 canonical row 會重新啟用，但不替換已儲存的 mode 或 model 設定；
+非 canonical 的 `openai` row 不會提供這條恢復路徑。
+
+### Providers 總覽的池容量
+
+對 Codex 登入的 Pool 模式，Providers 總覽會顯示依設定權重估算的**池已使用容量**，而不是把任一帳號
+當成 provider 總量。同一列也會顯示目前有效帳號的原始配額百分比，讓你能區分 pool estimate 與新請求
+實際會使用的帳號。
+
+當 reset 資訊可用時，總覽會顯示下一次重置時間，以及預期可恢復的容量，格式為
+`+N% pool capacity`。**Incomplete coverage**（不完整覆蓋）代表至少一個 pool 帳號無法安全納入估算，
+例如 plan 或 quota 未知、讀值已過期、帳號暫停，或需要重新認證。
+
+**Partial window coverage**（部分視窗覆蓋）警告表示部分納入的帳號只回報了一個 quota window，卻缺少
+另一個。總覽會把這些 window 分開，並將受影響的 window 標示為不完整，而不是把缺少的讀值當成該
+window 的用量。
+
+此估算僅供顯示，不會改變帳號選擇、session affinity、自動切換、cooldown 或其他路由決策。個別帳號
+狀態與路由控制請使用 [Codex Auth 帳號池](/zh-tw/guides/web-dashboard/#codex-auth-and-account-pools)。
+
+shipped v1 設定會自動遷移到 marker 2 的 option-aware row。原始設定只會備份一次到
+`~/.opencodex/config.json.pre-openai-tiers-v2.bak`；可用下列命令恢復：
+`cp ~/.opencodex/config.json.pre-openai-tiers-v2.bak ~/.opencodex/config.json`。
+
+## 認證模式
+
+provider 設定接受三種 `authMode`，其中 `key` 是預設值。內建 registry 也會另外標示 local preset；這些
+preset 通常同時省略 `authMode` 與 `apiKey`。
+
+| `authMode` | 認證方式 | 使用方 |
+| --- | --- | --- |
+| `key` | 傳送 API 金鑰（`Authorization: Bearer …`，或依 adapter 使用 `x-api-key` / `api-key`）。金鑰可以是字面值，也可以是 `${ENV_VAR}` 引用。 | 大多數供應商。 |
+| `forward` | 只轉送允許清單中的 incoming Codex 認證標頭，不儲存任何金鑰。這是 ChatGPT 登入的 passthrough。 | OpenAI（`openai-responses` adapter）。 |
+| `oauth` | 讀取已儲存的 OAuth access token（到期前自動 refresh），並把它當成 bearer key 使用。 | xAI、Anthropic、Kimi、Kiro、Google Antigravity、Cursor、Command Code、GitHub Copilot、Nous Portal。 |
+
+[`retryOn429`](/zh-tw/reference/configuration/) 的 same-key 429 replay 只適用於 API-key provider
+（`authMode: "key"`）。OAuth、forward 與 local preset 都被排除：它們的 credential 絕不能在同一 token
+上重播，而 local runtime 也沒有 remote key 可保留。此功能為 opt-in；未設定時關閉，物件存在時預設
+啟用，除非明確設為 `enabled: false`。
+
+## 1. ChatGPT 登入（forward / passthrough）
+
+`openai` provider **不需要 API 金鑰**。Direct 直接轉送既有 `codex login` 的 credential；Pool 則先解析
+主帳號或新增的 Codex 帳號，再使用相同 backend：
+
+```json
+{
+ "openai": {
+ "adapter": "openai-responses",
+ "baseUrl": "https://chatgpt.com/backend-api/codex",
+ "authMode": "forward"
+ }
+}
+```
+
+只會轉送經過篩選的標頭集合（`FORWARD_HEADERS`：authorization、ChatGPT account id、OpenAI
+beta/originator/session，詳見 [轉接器](/zh-tw/reference/adapters/)）。這條路徑也支援
+[web-search 與 vision sidecar](/zh-tw/guides/sidecars/)。
+
+ChatGPT passthrough catalog 也會加入 GPT-5.6 Sol/Terra/Luna 的裸 slug：`gpt-5.6-sol`、
+`gpt-5.6-terra`、`gpt-5.6-luna`；帳號具備權限時才能實際使用。
+
+## 2. 帳號登入（OAuth）
+
+有八個 provider preset 使用 OAuth 登入，另加透過實驗性非官方 device-flow bridge 的 GitHub Copilot。
+opencodex 會把 credential 存在 `~/.opencodex/auth.json` 並自動 refresh。登入 CLI 也接受 `chatgpt`；
+它會取得 ChatGPT credential，同時建立 `forward` 模式的 provider 條目。
+
+```bash
+ocx login xai # xAI Grok
+ocx login anthropic # Anthropic Claude (Pro/Max)
+ocx login kimi # Moonshot Kimi
+ocx login nous # Nous Portal（device grant；免費 + 付費模型）
+ocx login kiro # 匯入 kiro-cli credential（或 token fallback）
+ocx login google-antigravity
+ocx login cursor # 獨立 Cursor PKCE 登入
+ocx login command-code # Command Code browser OAuth（或匯入 ~/.commandcode/auth.json）
+ocx login github-copilot # GitHub device flow → Copilot token（Copilot Pro/Business）
+ocx login chatgpt # 獨立 ChatGPT OAuth 登入
+ocx logout
+```
+
+| 供應商 | Adapter | Base URL | 備註 |
+| --- | --- | --- | --- |
+| `xai` | `openai-chat` | `https://api.x.ai/v1` | 優先使用即時 Grok catalog；fallback 預設為 `grok-4.5`。 |
+| `anthropic` | `anthropic` | `https://api.anthropic.com` | Claude 模型；即時模型列表從 `/v1/models` 取得。 |
+| `kimi` | `openai-chat` | `https://api.kimi.com/coding/v1` | Kimi K2.7/K2.6/K2.5 coding 模型。 |
+| `nous` | `openai-chat` | `https://inference-api.nousresearch.com/v1` | Nous Research 訂閱 gateway（Hermes Agent 使用相同 backend）。透過 `portal.nousresearch.com` 做 device-grant 登入；access token 是每次請求使用的 inference JWT。混合付費與 `:free` 模型 catalog（`tencent/hy3:free`、`stepfun/step-3.7-flash:free` 等）會從已登入帳號即時探索。Refresh token 為單次使用，每次 refresh 都會輪換。 |
+| `kiro` | `kiro` | `https://runtime.us-east-1.kiro.dev` | 初次登入會匯入已安裝且已登入的 `kiro-cli` session。Unix 可用 `curl -fsSL https://cli.kiro.dev/install` | `bash` 安裝；Windows PowerShell 使用 `irm 'https://cli.kiro.dev/install.ps1'` | `iex`，再執行 `kiro-cli login`。**Add account** 會先登出 `kiro-cli`、啟動新的 browser login，切換 `kiro-cli` 所使用的帳號並保存 account-scoped profile metadata。既有 OpenCodex 帳號會保留；取消或失敗時會恢復先前的 `kiro-cli` session。 |
+| `google-antigravity` | `google` | `https://daily-cloudcode-pa.googleapis.com` | 透過 Cloud Code Assist wire 使用 Google OAuth。即時探索使用 CCA 經認證的 `v1internal:fetchAvailableModels` 端點，發布目前登入帳號可用的 agent 模型；維護中的 catalog 作為 fallback。 |
+| `cursor` | `cursor` | `https://api2.cursor.sh` | 實驗性 PKCE 登入、即時 HTTP/2 transport 與按帳號篩選的模型探索。 |
+| `github-copilot` | `openai-chat` | `https://api.githubcopilot.com` | 實驗性。GitHub device flow + `copilot_internal` exchange（VS Code OAuth client）。需要有效 Copilot 訂閱；不是官方第三方 API。 |
+
+終端 Nous refresh 失敗後，執行 `ocx login nous` 重新認證。
+
+對 canonical Kimi Coding Plan preset（`kimi` 帳號登入與 `kimi-code` API key），opencodex 只會把 caller
+提供且穩定的 `prompt_cache_key` 轉送到 Chat Completions 請求，絕不自行產生。Kimi 文件指出，穩定的
+session／task key 有助提升 Code Plan cache hit rate；沒有 key 的請求仍保持 keyless。若已 opt-in 的上游
+拒絕此欄位，opencodex 不會移除欄位後重試，也不會修改已儲存設定。其他 provider 預設 deny-by-default。
+
+也可以從 [web 儀表板](/zh-tw/guides/web-dashboard/) 啟動 OAuth。
+
+### 多個 OAuth 帳號
+
+credential 內含穩定 account id 或 email 的 OAuth provider 可以保存多個登入。Providers 頁面會在下拉
+選單顯示這些帳號、允許新增帳號，並在不登出其他帳號的情況下切換目前帳號。只有沒有 identity 的 Kimi
+credential 會取代 active slot；Kiro 帳號以 profile ARN 作為 key。`chatgpt` 始終是 single-slot，因為
+Codex pool 帳號使用獨立 ledger。Token 仍存放在 `~/.opencodex/auth.json`；`/api/oauth/accounts` 只回傳
+遮蔽後的 metadata。
+
+### Cockpit Tools Antigravity 匯入
+
+目前 v1 只會為 `google-antigravity` provider 匯入 **Cockpit Tools Antigravity** JSON export。在 Providers
+儀表板中，從該 provider 的 Accounts 分頁選擇本機 JSON 檔案。儀表板不會顯示檔案內容或 credential
+值，只會回報 imported、updated、failed 與 unsupported 數量。其他 Cockpit provider 在 v1 會被拒絕。
+
+CLI 只接受來自檔案或標準輸入的 export，絕不要直接貼進 command argument：
+
+```bash
+ocx account import google-antigravity --format cockpit-tools --file [--json]
+cat accounts.json | ocx account import google-antigravity --format cockpit-tools --stdin [--json]
+```
+
+inline JSON 與額外 positional argument 都會被拒絕。請將 export 檔案保持私密，匯入後安全刪除或妥善
+保存。
+
+### OAuth 可靠度
+
+opencodex 協調 token refresh 與 Codex pool 路由，避免並行請求競爭 credential store。這是可靠度與診斷
+工作，**不**代表能繞過 provider enforcement、rate limit 或帳號動作。
+
+**Refresh 協調。** 路由呼叫前，過期的 access token 每個 `(provider, account)` 只 refresh 一次：
+
+1. In-process single-flight：並行 caller 共用同一個 refresh promise。
+2. Per-account file lock：跨 process writer 在同一帳號上序列化。
+3. Generation CAS：只有已儲存 credential generation 仍相符時才持久化；較新的 writer 勝出，舊的
+ refresh result 不能覆寫它。
+
+終端 refresh 失敗會把帳號標示為需要重新認證，而不是無限重試。
+
+**Cooldown（Codex pool）。** 上游 `429`／quota response 會依 `Retry-After`、quota `reset` header
+（有上限）或短預設 backoff 設定 hard cooldown。明確 `Retry-After` cooldown 中的帳號不會被提前 probe；
+reset 衍生 cooldown 可能取得節流後的 probe lease，在不淹沒 provider 的情況下偵測恢復。由 reset 衍生的
+native-model cooldown 也會保留已知獨立 quota group：`gpt-5.3-codex-spark` 不會阻止同一帳號嘗試共享的
+GPT-5.6 Terra/Luna quota，而共享群組內的模型仍會互相保護。明確 `Retry-After` 與預設 cooldown 始終為
+account-wide。
+
+**Session affinity。** Codex thread→account affinity 只存在目前 process 記憶體，不會跨 proxy restart
+持久化。credential 失敗（`401`／`403`）時，帳號會被 quarantine 等待 reauth，並清除該帳號的 affinity。
+收到 `429` 時，帳號進入 cooldown、affinity 被清除，pool selection 可以輪換；thread 不會在 rate-limit
+response 後仍被固定在同一帳號。
+
+**Codex client metadata。** ChatGPT forward 路徑會轉送經篩選的 `FORWARD_HEADERS` allowlist
+（authorization、`chatgpt-account-id`、originator、session/thread id 與其他相關 Codex header，詳見
+[轉接器](/zh-tw/reference/adapters/)）。Pool 模式只覆寫 auth 與 `chatgpt-account-id`，讓它們符合選中的
+credential。caller 沒有送出時，opencodex **不會**捏造官方 client identity，例如 `originator`、session
+或 thread header。
+
+**診斷與重新認證。** 一般 `ocx status` 會印出 OAuth health 區塊，只顯示遮蔽後 account id，不含 token。
+`ocx doctor` 會新增 OAuth reliability 區段，包含 writable-store／single-flight check，以及帶 recovery
+Action 的 WARN row。OAuth provider 帳號需要重新認證時，執行 `ocx login `，或在儀表板使用
+Reauthenticate。Codex pool 帳號不是 `ocx login` provider，請透過儀表板 Codex account pool 重新認證。
+相關命令請參見 CLI 參考的 [`ocx status` / `ocx doctor`](/zh-tw/reference/cli/)。
+
+### Kiro credential 匯入
+
+Kiro 登入預期存在 Kiro CLI。Unix 可用 `curl -fsSL https://cli.kiro.dev/install | bash` 安裝；Windows
+PowerShell 使用 `irm 'https://cli.kiro.dev/install.ps1' | iex`；接著以 `kiro-cli login` 登入。若沒有
+`kiro-cli` session，`ocx login kiro` 會 fallback 到貼上的 access token 或 `KIRO_ACCESS_TOKEN` 環境變數。
+
+`ocx login kiro` 匯入流程會搜尋各平台的 Kiro CLI store，並以唯讀模式開啟 SQLite database。兩個環境
+變數可明確指定來源與 token row：
+
+- `KIROCLI_DB_PATH` 指定非標準 Kiro CLI SQLite database。路徑必須已存在；此匯入流程不會建立或修改
+ database、WAL 或 SHM 檔案。
+- `KIROCLI_TOKEN_KEY` 在 database 有多個 otherwise ambiguous token row 時，指定精確的 `auth_kv`
+ token key。未指定時會讓登入失敗，而不是猜測。
+
+Windows 匯入會尋找 `%LOCALAPPDATA%\Kiro-Cli\data.sqlite3`。forced／add-account login 也需要本機 CLI
+binary：opencodex 先使用 `PATH`，再 fallback 到 `%LOCALAPPDATA%\Kiro-Cli\kiro-cli.exe` 與
+`C:\Program Files\Kiro-Cli\kiro-cli.exe`。
+
+成功匯入後，opencodex 會把 credential 寫入 `~/.opencodex/auth.json`。
+
+請將這些變數與所選 database 保持私密。不要把 database 檔案或原始登入診斷附在 bug report。
+
+**Add account** 是獨立的寫入流程：它會 snapshot 目前 session、登出 `kiro-cli`，再匯入新的 browser
+login。若登入取消或失敗，包括 OpenCodex 持久化 credential 期間失敗，rollback 會先替換 Kiro CLI
+database 並移除目前的 WAL、SHM 與 journal sidecar，再發布先前的 session snapshot。
+
+由於 rollback 只能依賴 snapshot，若 session store 存在卻無法擷取，例如檔案不可讀、schema 不符或 token
+選擇有歧義，**Add account** 會拒絕登出 `kiro-cli`。當 `KIROCLI_DB_PATH`／`KIRO_CLI_DB_FILE` 將匯入
+讀取重導到 live CLI store 之外，或既有主 CLI database 沒有可識別 token row 時，也會拒絕。請在一般
+`kiro-cli` data path 修復或移除不可讀 database、取消這些 import selector 後重試。沒有既有
+`kiro-cli` session 的新機器登入不受影響。
+
+## 3. API 金鑰目錄
+
+opencodex 內建 79 個 preset：67 個 key-based、8 個 OAuth、3 個 local，以及 1 個預設 ChatGPT-forward
+preset。儀表板的 **Add provider** picker 會開啟 key provider 的 dashboard、驗證金鑰並儲存；驗證方式
+依 provider 而異。主要條目如下。
+
+**ClinePass** 使用 Cline API key，搭配[官方訂閱 catalog](https://docs.cline.bot/getting-started/clinepass)
+與 [Chat Completions endpoint](https://docs.cline.bot/api/chat-completions)，由 Cline Bot Inc. 依
+[Cline terms](https://cline.bot/tos) 提供。像 `cline-pass/cline-pass/kimi-k3` 這類 routed id 是刻意設計：
+第一段選擇 opencodex provider，後面的 `cline-pass/kimi-k3` 才是送往上游的完整 model slug。ClinePass
+quota 由帳號共用，包含 rolling 5-hour、weekly 與 monthly limit。opencodex 目前只宣告 live-verified
+`low` reasoning tier；更高 requested tier 會 clamp 到 `low`，直到 gateway 發布或驗證更廣的 ladder。
+
+**Cline** 使用相同 API key 與 endpoint，但採 pay-as-you-go 用量計費，可使用 100+ 模型，包括
+OpenRouter 風格 id，例如 `anthropic/claude-sonnet-4-6`。Cline 的 promotional free model 只提供給 Cline
+IDE／CLI，不透過 API；`minimax/minimax-m2.5` 是文件列出的 API 免費實驗模型。
+
+| 供應商 | Base URL |
+| --- | --- |
+| **OpenAI (API key)** | `https://api.openai.com/v1` |
+| **Anthropic (API key)** | `https://api.anthropic.com` |
+| **OpenRouter** | `https://openrouter.ai/api/v1` |
+| **Cline** | `https://api.cline.bot/api/v1` |
+| **ClinePass** | `https://api.cline.bot/api/v1` |
+| **Ollama Cloud** | `https://ollama.com/v1` |
+| Google Gemini · Google Vertex AI | `https://generativelanguage.googleapis.com` · `https://aiplatform.googleapis.com` |
+| Azure OpenAI | `https://{resource}.openai.azure.com/openai` |
+| Umans AI · Neuralwatt | `https://api.code.umans.ai` · `https://api.neuralwatt.com/v1` |
+| Mistral | `https://api.mistral.ai/v1` |
+| MiniMax · MiniMax (CN) | `https://api.minimax.io/v1` · `https://api.minimaxi.com/v1` |
+| DeepSeek | `https://api.deepseek.com` |
+| Cerebras | `https://api.cerebras.ai/v1` |
+| Chutes | `https://llm.chutes.ai/v1` |
+| DeepInfra | `https://api.deepinfra.com/v1/openai` |
+| Hyperbolic | `https://api.hyperbolic.xyz/v1` |
+| Nscale Serverless Inference | `https://inference.api.nscale.com/v1` |
+| Vultr Serverless Inference | `https://api.vultrinference.com/v1` |
+| Baseten Model APIs | `https://inference.baseten.co/v1` |
+| Command Code | `https://api.commandcode.ai/provider/v1` |
+| SambaNova Cloud | `https://api.sambanova.ai/v1` |
+| Nebius Token Factory | `https://api.tokenfactory.nebius.com/v1` |
+| DigitalOcean Serverless Inference | `https://inference.do-ai.run/v1` |
+| Scaleway Generative APIs | `https://api.scaleway.ai/v1` |
+| Featherless AI | `https://api.featherless.ai/v1` |
+| Novita AI | `https://api.novita.ai/openai/v1` |
+| Together | `https://api.together.xyz/v1` |
+| Fireworks | `https://api.fireworks.ai/inference/v1` |
+| Moonshot (Kimi API) · Kimi (coding) | `https://api.moonshot.ai/v1` · `https://api.kimi.com/coding/v1` |
+| Hugging Face | `https://router.huggingface.co/v1` |
+| NVIDIA NIM | `https://integrate.api.nvidia.com/v1` |
+| Z.AI (GLM Coding) | `https://api.z.ai/api/coding/paas/v4` |
+| Zhipu AI (BigModel) | `https://open.bigmodel.cn/api/paas/v4` |
+| Qwen Cloud | Token plan（預設）：`https://token-plan.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1` · pay as you go：`https://dashscope.aliyuncs.com/compatible-mode/v1` · 或 Custom |
+| Tencent Cloud Coding Plan | `https://api.lkeap.cloud.tencent.com/coding/v3` |
+| SiliconFlow | `https://api.siliconflow.cn/v1` |
+| Volcengine Ark · Coding Plan · Agent Plan | `https://ark.cn-beijing.volces.com/api/v3` · `https://ark.cn-beijing.volces.com/api/coding/v3` · `https://ark.cn-beijing.volces.com/api/plan/v3` |
+| Xiaomi MiMo | `https://api.xiaomimimo.com/anthropic` |
+| Kilo | `https://api.kilo.ai/api/gateway` |
+| GitLab Duo | `https://cloud.gitlab.com/ai/v1/proxy/openai/v1` |
+| Cloudflare AI Gateway | `https://gateway.ai.cloudflare.com/v1/{account-id}/{gateway}/anthropic` |
+| …以及更多 | opencode zen、Vercel AI Gateway、Venice、NanoGPT、Synthetic、Qianfan、Alibaba、Parallel、ZenMux、LiteLLM |
+
+**OpenCode Zen**（`opencode-zen`）與無 key 的 **OpenCode Free** preset 共用
+`https://opencode.ai/zen/v1`。該 gateway 的免費模型常遇到短時間 burst limit，約 15–20 requests/minute
+（社群實測；OpenCode 未公布 RPM）。Zen 可能回傳 generic rate-limit 429，而沒有 `Retry-After`／
+`X-RateLimit-*` header。這與 OpenCode 宣告的 keyless desktop quota 是不同限制：`opencode-free` 約每 5
+小時 200 次 Big Pickle／free-model request。Zen 在這類 429 省略 `Retry-After` 時，opencodex 會在 client
+error 加入 provider guidance 與 synthetic `Retry-After`；若上游有 `Retry-After`，仍以上游值為準。
+same-key wait-and-retry 仍需透過 [`retryOn429`](/zh-tw/reference/configuration/) 明確 opt-in。
+
+大多數 provider 使用帶 bearer key 的 `openai-chat` adapter；少數只提供 Anthropic-compatible endpoint 的
+provider，例如 **Xiaomi MiMo**，使用 `anthropic` adapter（`x-api-key`）。Volcengine Agent Plan 透過
+`openai-responses` 使用原生 Responses endpoint。內建 DeepSeek preset 也會把 `deepseek-v4-flash` 路由到
+原生 Responses endpoint，並保持上游 SSE streaming。若該模型完成所有 output item 卻省略最後的
+Responses event，opencodex 會套用 5 秒、model-scoped 的 grace repair；malformed 或 partial stream 會以
+incomplete 關閉，不會被誤報為成功。
+
+> **三條 Volcengine 計費路徑：** `volcengine` 是 pay-as-you-go Ark API，
+> `volcengine-coding-plan` 消耗 Coding Plan quota，`volcengine-agent-plan` 消耗 Agent Plan quota。請使用
+> 同一產品發出的 key 與 endpoint；即使已有 Plan 訂閱，普通 `/api/v3` endpoint 仍可能產生
+> pay-as-you-go 費用。preset 使用 curated static model catalog，因為 Ark `/models` 也包含 embedding、
+> image、video 與 3D resource，Coding gateway 會回傳相同 broad catalog，而 Agent Plan gateway 沒有
+> `/models` resource。Pay-as-you-go 預設 `doubao-seed-2-1-pro-260628`，curated catalog 也包含目前的
+> DeepSeek 與 GLM text model。Coding Plan 預設 `ark-code-latest`；Agent Plan 預設 `deepseek-v4-pro`。
+
+> **Volcengine Plan 使用限制：** Volcengine 文件指出 Coding Plan 與 Agent Plan quota 只能在受支援的
+> AI coding tool 內使用，並警告把 plan key 用於一般 API call 可能導致訂閱停權或帳號封鎖。透過
+> opencodex 路由 Codex 或 Claude Code 屬於文件所述用途；不要把 plan key 指向其他 automation。
+> pay-as-you-go 的 `volcengine` 路徑沒有此限制。
+
+**Chutes 探索。** `chutes` preset 使用 Chutes 固定、共用的 OpenAI-compatible LLM gateway。它讀取公開的
+`/v1/models` catalog，只保留 `supported_features` 宣告 `tools` 的 row，保留含 `/` 的 model id 與安全
+live metadata，並把 discovery 限制在 256 KiB／128 個 raw row。因 catalog 是公開的，不能用成功讀取來
+證明提供的 key 有效；chat request 仍使用設定的 Bearer key。使用者自行部署的 custom Chute host 與
+Chutes 非 LLM API 仍屬於 custom-provider 範圍。可從 [Chutes dashboard](https://chutes.ai/auth/start) 建立
+key。
+
+**DeepInfra 探索。** key-based `deepinfra` OpenAI Chat Completions provider 使用 `openai-chat` adapter 與
+Bearer API key。registry 管理的 model-list URL 只保留標為 `chat` 的 row，保留含 `/` 的原生 model id，
+並把 live discovery 限制在 512 KiB／512 個 raw row。可在
+[DeepInfra dashboard](https://deepinfra.com/dash/api_keys) 建立 key。
+
+**Hyperbolic 探索。** preset 會用設定的 bearer key 讀取 `/v1/models`，保留含 `/` 的原生 model id，
+並把 discovery 限制在 256 KiB／256 個 raw row。範圍只涵蓋 serverless text 與 vision-language chat；
+Hyperbolic 另外的 image、audio 與 GPU endpoint 不在範圍內。可在
+[Hyperbolic](https://app.hyperbolic.ai) 建立 key。
+
+**Nscale 與 Vultr 探索。** 兩個 preset 都讀取 provider 經認證的 `/v1/models` catalog、保留原生 id，並
+把 discovery 限制在 256 KiB／256 個 raw row。Nscale catalog 混合 chat、image 與 embedding model，卻
+沒有 modality 欄位，因此 preset 只允許 `meta-llama/Llama-3.1-8B-Instruct`，也就是 Nscale 官方
+工具呼叫 API 範例使用的模型。Vultr 目前只為 `kimi-k2-instruct` 文件化 tool calling，因此 preset 只
+暴露該模型。其他 row 在 provider 發布同等 agent-tool evidence 前保持隱藏。Nscale service token 可在
+[Nscale Console](https://console.nscale.com) 建立；Vultr inference key 可從
+[Vultr Console](https://my.vultr.com) 的 subscription overview 複製。
+
+**Command Code 探索。** preset 從固定 Provider API host 讀取 Command Code 的 `/provider/v1/models`
+列表，保留 provider-native id，並把 discovery 限制在 256 KiB／256 個 raw row。
+`ocx login command-code` 支援 browser sign-in OAuth；既有 Command Code CLI 使用者也可選擇從
+`~/.commandcode/auth.json` 匯入本機 CLI credential。模型 catalog 依帳號而定，登入後從經認證的 discovery
+endpoint 取得。Chat request 使用設定的 Bearer key。可在
+[Command Code Studio](https://commandcode.ai/studio/) 建立 key。
+
+**SambaNova Cloud 探索。** preset 從固定 API host 讀取 SambaNova Cloud 公開的 `/v1/models` 列表，保留
+provider-native id，並把 discovery 限制在 128 KiB／128 個 raw row。因 catalog 不需要認證，CLI login
+流程會把 key 回報為 unverifiable，而不會把公開 response 當成有效 key 的證明。Chat request 仍使用
+設定的 Bearer key，並停用 parallel function call，因 SambaNova 尚未支援。Private SambaStudio deployment
+endpoint 不在範圍內。可在 [SambaNova Cloud](https://cloud.sambanova.ai/apis) 建立 key。
+
+**Nebius Token Factory 探索。** preset 請求經認證的 verbose model catalog，只保留 architecture 會輸出
+text 的 row，排除 embedding 與 image-generation model。它保留含 `/` 的原生 id，以及回報的 context／
+input-modality metadata，並把 discovery 限制在 512 KiB／512 個 raw row。Dedicated deployment host 不在
+範圍內。可在 [Nebius Token Factory](https://tokenfactory.nebius.com) 建立 key。
+
+**DigitalOcean 探索。** preset 以 model access key 存取固定的 shared Serverless Inference host，並把經
+認證的 `/v1/models` response 與 DigitalOcean 文件支持的 Chat Completions allowlist 取交集。未知、
+Responses-only、embedding 與 media-generation id 都 fail closed。discovery 限制在 256 KiB／256 個 raw
+row；agent-specific 與 dedicated host 不在範圍內。可在
+[DigitalOcean Control Panel](https://cloud.digitalocean.com/model-studio/manage-keys) 建立 key。
+
+**Scaleway 探索。** preset 把經認證的模型列表與 Scaleway 文件化的 Serverless Chat Completions
+allowlist 取交集。未知、Responses-only、embedding、transcription 與其他 media model id 都 fail
+closed；discovery 限制在 128 KiB／128 個 raw row。它使用 default Project 的 shared endpoint；
+project-qualified URL 與 dedicated deployment 需要 custom provider。可在
+[Scaleway console](https://console.scaleway.com/generative-api) 建立 API key。
+
+**Featherless 探索。** preset 對固定 OpenAI-compatible host 認證，並讓上游只回傳前 100 個 popular、
+已篩選為 chat 且符合目前 plan 的模型。registry 規則再進一步 fail closed，要求每一 row 都獨立回報 plan
+availability、沒有 Hugging Face gate，且 `features.tool_use: true`。discovery 限制在 128 KiB／100 個 raw
+row，因此不會下載或快取完整的數萬模型 catalog。因 `/v1/models` 文件指出可帶或不帶認證呼叫，成功
+讀取不能證明提供的 key 有效；chat request 仍使用設定的 Bearer key。Featherless terms 將 individual
+plan 限定於 interactive／prototyping 使用；任意 application 需要 Scale plan。可在
+[Featherless dashboard](https://featherless.ai/account/api-keys) 建立 key。
+
+**Novita 探索。** key-based preset 使用 `openai-chat` adapter，只把 Bearer key 傳到 Novita 固定的
+OpenAI-compatible host。公開 model list 會篩選為同時回報 `model_type: chat` 與 `chat/completions`
+endpoint 的 row，discovery 限制在 512 KiB／256 個 raw row。model id 必須完整保留 Novita 回傳的形式，
+包括含 `/` 的 id；路由前不得 normalize 或 rewrite。因 catalog 是公開的，login 會把 key 回報為
+unverifiable，而不會把成功取得列表視為有效 key 的證明。模型能力不同，因此 preset 不會宣告
+provider-wide parallel tool call 或 OpenAI `reasoning_effort`。可在
+[Novita key manager](https://novita.ai/settings/key-management) 建立 key。
+
+> **Baseten 範圍：** preset 只涵蓋 Baseten 共用的
+> [Model APIs](https://docs.baseten.co/inference/model-apis/overview)。本機使用請採 personal
+> [API key](https://docs.baseten.co/organization/api-keys)；共用／production 使用則採具備 **Call Model
+> APIs** 權限的 team key。Dedicated Truss `predict` endpoint 使用不同 host 與 schema，不會被此 preset
+> 路由。此 preset 的 live discovery 上限為 1 MiB response／256 個 raw model row。
+
+### A6API 信用額度
+
+使用 `authMode: "key"`，且 base URL 為 canonical `https://api.a6api.com` 或
+`https://api.a6api.com/v1` 的 custom `openai-chat` provider，會在 dashboard 與
+`ocx account refresh ` 顯示 A6API credit meter。provider 名稱可自訂；偵測依據 canonical HTTPS
+endpoint。meter 會使用帳號的 hard credit limit，把 A6API token unit 換算成 USD，並顯示已使用百分比與
+剩餘 credit。Token 到期不會顯示為 quota reset，因為到期不代表 credit 會補充。
+
+```json
+{
+ "providers": {
+ "my-a6": {
+ "adapter": "openai-chat",
+ "authMode": "key",
+ "baseUrl": "https://api.a6api.com/v1",
+ "apiKey": "${A6API_API_KEY}"
+ }
+ }
+}
+```
+
+quota probe 只會把 active key 傳送到 canonical A6API host，並拒絕 redirect。格式錯誤、負數或內部不一致
+的 billing total 不會產生 report，也不會顯示誤導性的 quota bar。
+
+> **Tencent Cloud Coding Plan 使用限制：** Tencent 文件將此訂閱限定為互動式 coding tool。一般 API
+> automation、自訂 application backend 與非互動 batch 使用都被禁止，並可能造成 plan key 被停用。
+
+> **兩條 GLM 路徑：** `zai` 是 Z.AI 國際 Coding Plan 訂閱；`zhipu-bigmodel` 是智譜國內 BigModel
+> pay-as-you-go endpoint。兩者 host、key 與 billing 都不同；其中一邊發出的 key 無法在另一邊通過認證。
+
+### 多個 API 金鑰
+
+key-based provider 也能保存多個 key。透過 Providers 頁面新增 key 時，會存到 `provider.apiKeyPool`、
+設為 active，並同步到 `provider.apiKey`，讓路由與 adapter 繼續讀取原本欄位。同一個下拉選單可切換或
+移除 key；管理 API 為 `/api/providers/keys`，而且只回傳遮蔽後的 key。
+
+### 從終端切換帳號
+
+不必開啟儀表板，即可用 `ocx account list`、`ocx account current` 與 `ocx account use` 檢視或切換
+同一組 Codex、OAuth 與 API-key pool。完整 command、JSON output 與新 session 生效規則請參見
+[CLI 參考](/zh-tw/reference/cli/#ocx-account-subcommand)。
+
+### GPT-5.6 預覽路徑
+
+GPT-5.6 Sol/Terra/Luna 會預置在 provider fallback list 中，因此即使即時 catalog 暫時落後，
+`ocx sync` 仍可維持模型可見。
+
+| Codex 路由 | 預置 model id | Codex 可見 context |
+| --- | --- | --- |
+| Codex 登入（Pool 或 Direct） | `gpt-5.6-*` | 372,000 |
+| OpenAI (API key) | `openai-apikey/gpt-5.6-*` 加 `*-pro` | 1,050,000（922,000 max input） |
+| OpenRouter | `openrouter/openai/gpt-5.6-sol`、`openrouter/openai/gpt-5.6-terra`、`openrouter/openai/gpt-5.6-luna` | 1,050,000 |
+| Cursor | `cursor/gpt-5.6-sol`、`cursor/gpt-5.6-terra`、`cursor/gpt-5.6-luna` | 1,000,000 |
+
+原生 GPT-5.6 條目保留固定的上游 reasoning ladder，例如 Luna 有 `max` 但沒有 `ultra`。路由條目使用各
+provider metadata 與 reasoning mapping。四條路徑最終都受上游權限限制；Cursor 即時探索還會把 static
+seed 篩到目前帳號真正能使用的模型。
+
+:::note[Gateway 與訂閱 proxy]
+是否納入某個 provider，取決於 opencodex 是否有匹配的 wire adapter，**不**取決於它是否是「agent」
+產品。目前 adapter id 為 `openai-chat`、`openai-responses`、`anthropic`、`google`（AI Studio、Vertex、
+Antigravity／Cloud Code Assist 模式）、`azure` / `azure-openai`、`kiro`、`cursor`。像原生 Amazon Bedrock
+這類沒有對應實作的 proprietary API，不會被直接支援。
+
+**GitHub Copilot** 是 OAuth provider（`ocx login github-copilot`），會把 GitHub device-flow login 換成
+短效 Copilot API token，不是貼上 API key。**GitLab Duo** 仍是使用 OpenAI-compatible endpoint 的
+key／subscription-token gateway。**Cloudflare AI Gateway** 需要在 URL 填入 account 與 gateway id。
+
+Copilot 的 catalog 混合多種 wire：GPT-5 family（`gpt-5.3-codex`、`gpt-5.4`、`gpt-5.4-mini`、
+`gpt-5.5`、`gpt-5.6-luna`、`gpt-5.6-sol`、`gpt-5.6-terra`）會拒絕 agent traffic 的
+`/chat/completions`，因此 opencodex 會依內建預設把這些模型路由到 Responses API；其他 Copilot 模型
+仍使用 chat completions。優先順序為：hard wire pin → 你明確設定的
+[`modelAdapters`](/zh-tw/reference/configuration/providers/) → registry default → provider-wide adapter。
+若要讓沒有內建 default 的模型，例如 `gpt-5.4-nano`，改走 Responses，可設定
+`"modelAdapters": { "gpt-5.4-nano": "openai-responses" }`。
+
+Cursor 另以實驗性 adapter 追蹤。`adapter: "cursor"` 會在 `ocx init` 與 dashboard Add Provider picker
+出現為實驗性 local config，並帶 Cursor static fallback model catalog metadata。設定 Cursor access token
+後，opencodex 使用 Cursor 即時 HTTP/2 transport。bundled fallback seed 包含 1M context 的
+`gpt-5.6-sol`／`terra`／`luna`、500K 的 `grok-4.5`／`grok-4.5-fast`，以及 262K 的 `kimi-k3`；即時探索
+決定哪些模型對帳號保持可見。Cursor 的 Kimi K3 只以帶 effort suffix 的 wire id 提供，因此
+`cursor/kimi-k3` 暴露 `low`／`high`／`max` ladder，預設為 `max`，符合該模型文件化的 API default。
+Cursor server-driven native read/write/delete/ls/grep/shell/fetch execution 預設停用，因為它會繞過 Codex
+approval 與 sandbox 路徑；只有可信本機實驗才應在 `~/.opencodex/config.json` 的 `providers.cursor`
+物件設定 `unsafeAllowNativeLocalExec: true`，也可以透過儀表板 **Providers → Cursor → Edit JSON** 設定。
+完整範例參見[設定參考](/zh-tw/reference/configuration/#cursor-provider-adapter-cursor)。MCP、螢幕錄製與
+computer-use 可透過 executor hook 使用；未設定本機 executor 時，opencodex 會回傳 typed no-executor
+result，而不是用 policy block request。Cursor OAuth 與即時 model discovery 已為此實驗性 adapter 啟用；
+Cursor 仍不會出現在 key-login list。
+:::
+
+### Ollama Cloud
+
+Ollama Cloud 是 hosted、不是 local 的 Ollama，在 `https://ollama.com/v1` 提供 OpenAI-compatible API，
+key 來自 [ollama.com/settings/keys](https://ollama.com/settings/keys)。opencodex 依 vision capability 分類其
+cloud lineup，讓 [vision sidecar](/zh-tw/guides/sidecars/) 只對純文字模型生效。純文字模型，例如
+`glm-5.2`、`deepseek-v4-pro`、`gpt-oss`、`qwen3-coder`、`minimax-m2.x`、`nemotron-3-*`，會列在
+`noVisionModels`；原生 vision 模型，例如 `kimi-k2.6`、`minimax-m3`、`gemma4`、`qwen3.5`、
+`gemini-3-flash-preview`，不會列入。matching 可容忍 Ollama 的 `:size` tag，因此 `gpt-oss` 同時涵蓋
+`gpt-oss:120b` 與 `gpt-oss:20b`。
+
+## 4. 本機供應商
+
+讓 opencodex 指向本機 OpenAI-compatible server，通常使用空 key：
+
+| 供應商 | Base URL |
+| --- | --- |
+| Ollama (local) | `http://localhost:11434/v1` |
+| vLLM | `http://localhost:8000/v1` |
+| LM Studio | `http://localhost:1234/v1` |
+
+## 任意 OpenAI-compatible endpoint
+
+若 provider 使用 Chat Completions，`openai-chat` adapter 就能處理。可在儀表板選 **Custom**，或在
+`ocx init` 選 `custom` 並輸入 base URL。所有 provider 欄位（`headers`、`noReasoningModels`、
+`noVisionModels`、`models` 等）請參見[設定參考](/zh-tw/reference/configuration/)。
+
+## Providers 總覽的速率限制
+
+Providers 總覽的 **Rate limits** 區段會在 provider 有使用量／billing endpoint 時，顯示從該 endpoint
+refresh 的即時 utilization bar。bar 代表特定 window（5 小時、weekly、monthly 或 provider-specific）
+已消耗的比例。
+
+具有 live probe 的 provider：OpenAI/Codex、Anthropic、xAI、Cursor、Kimi、Google Antigravity、
+OpenRouter、DeepSeek、ClinePass、Z.AI、MiniMax、Moonshot、Venice、Synthetic、DeepInfra、Neuralwatt，
+以及任何由 a6api 支援的 custom provider。
\ No newline at end of file
diff --git a/docs-site/src/content/docs/zh-tw/guides/routing-profile-editor.md b/docs-site/src/content/docs/zh-tw/guides/routing-profile-editor.md
new file mode 100644
index 000000000..e6ae93a76
--- /dev/null
+++ b/docs-site/src/content/docs/zh-tw/guides/routing-profile-editor.md
@@ -0,0 +1,71 @@
+---
+title: 路由設定檔編輯器
+description: 從 OpenCodex 儀表板建立、編輯、驗證、試跑（dry-run）與移除路由原則設定檔。
+---
+
+OpenCodex 儀表板中的 **Models → Routing** 分頁可以直接管理 `config.routingProfiles`，不必手動編輯 `config.json`。
+
+## 建立設定檔
+
+1. 在儀表板中開啟 **Routing**。
+2. 選取 **Create profile**。
+3. 輸入 `id`。標準模型 id 是 `policy/`。
+4. 新增一個或多個明確的 provider/model 候選。
+5. 設定選用的需求、評分權重、成本上限（`maxEstimatedCostUsd`、選用的 `onUnknownCost`）與未知證據（unknown-evidence）行為。
+6. 儲存設定檔。
+
+設定檔 id 在建立後不可變。要使用不同的 id，請建立新設定檔，並在更新 callers 之後移除舊的。
+
+## 驗證與持久化
+
+儀表板會把與 `config.routingProfiles` 相同的設定檔物件送給 management API。伺服器會在寫入之前驗證完整的候選：
+
+- id 與 aliases 必須遵循路由設定檔的命名與衝突規則；
+- 每個候選 provider 都必須存在且已啟用；
+- 重複的候選會被拒絕；
+- 數值上限與需求必須維持在其支援的範圍內；且
+- 至少一個最佳化權重必須為正值。
+
+成功的儲存會透過一般的 config writer 持久化設定檔、協調即時狀態，並重新整理模型目錄。驗證失敗會保留先前的設定不變，並顯示在編輯器中。
+
+當 `limits.maxEstimatedCostUsd` 被設定時，`limits.onUnknownCost` 預設為 `"allow"`：未知成本估算不會被排除於上限之外，dry-run / 即時路由決策 trace 會標記 `cost.capOutcome: "unknown-allowed"`，讓操作者知道上限未被證實。需要上限必須失敗閉合（fail closed，`cost-limit-unknown`，帶 `cost.capOutcome: "unknown-excluded"`）時，請設定 `"exclude"`。單獨設定 `onUnknownCost` 是無效的，不會產生 cap outcome。這與 `unknownEvidence.cost` 是分開的，後者仍可獨立於 cap outcome 之外排除或懲罰未知價格。
+
+## 試跑已儲存的設定檔
+
+選取一個已儲存的設定檔，使用 **Dry-run evaluation** 加入請求證據，例如 context-window 大小、工具使用、圖片輸入或結構化輸出。試跑會評估資格與評分，但永遠不會送出上游模型請求。
+
+未儲存的編輯不會被試跑使用。請先儲存設定檔，讓顯示的 revision 與評估參照同一份設定。
+
+## Management API
+
+編輯器使用這些端點：
+
+- `GET /api/routing-profiles` 列出正規化的設定檔與 revisions。
+- `PUT /api/routing-profiles` 建立或更新一個設定檔。傳送 `mode: "create"` 或 `mode: "update"`；create mode 拒絕覆寫已存在的 id。
+- `DELETE /api/routing-profiles?id=` 移除一個設定檔。
+- `POST /api/routing-profiles/dry-run` 在不送出上游請求的情況下評估已儲存的設定檔。
+
+儲存 payload 範例：
+
+```json
+{
+ "id": "fast",
+ "mode": "create",
+ "profile": {
+ "alias": "ocx/fast",
+ "candidates": [
+ { "provider": "anthropic", "model": "claude-sonnet-5" },
+ { "provider": "openai", "model": "gpt-5.6" }
+ ],
+ "require": { "tools": true, "minContextWindow": 128000 },
+ "optimize": { "latency": 0.55, "health": 0.25, "cost": 0.1, "quota": 0.1 },
+ "limits": { "maxEstimatedCostUsd": 0.5, "onUnknownCost": "allow" },
+ "unknownEvidence": {
+ "capability": "exclude",
+ "health": "penalize",
+ "quota": "penalize",
+ "cost": "penalize"
+ }
+ }
+}
+```
diff --git a/docs-site/src/content/docs/zh-tw/guides/sidecars.md b/docs-site/src/content/docs/zh-tw/guides/sidecars.md
new file mode 100644
index 000000000..e6e6b4604
--- /dev/null
+++ b/docs-site/src/content/docs/zh-tw/guides/sidecars.md
@@ -0,0 +1,121 @@
+---
+title: "Sidecar：Web Search 與 Vision"
+description: 透過原生 ChatGPT sidecar，讓路由模型獲得真實 web search，並讓純文字模型理解圖像。
+---
+
+不同路由模型對託管 **Web Search** 和原生**圖像輸入**的支援並不相同。opencodex 透過兩個
+sidecar 補齊這些能力；它們可以使用 ChatGPT 登入（`forward`）provider，也可以使用已儲存的
+Anthropic OAuth provider。Sidecar 錯誤會轉換成長度受限的工具結果或圖像提示，不會讓整個 turn
+失敗。
+
+:::note[自動選擇後端]
+顯式 `backend` 設定優先。省略時，如果已啟用 Anthropic OAuth provider 的活動帳號未標記
+`needsReauth`，則使用 `anthropic`；否則使用 `openai`。顯式選擇 `anthropic` 但沒有可用憑證時
+會關閉失敗。`openai` 同時需要 ChatGPT 登入和已啟用的 `forward` provider。
+:::
+
+## Web-search sidecar
+
+當 Codex 為非透傳的路由模型請求託管 `web_search` 時，opencodex 會：
+
+1. **移除**託管的 `web_search` 工具，改為向路由模型提供一個合成的
+ `web_search(query)` function 工具。原託管工具的選項會保留並用於 sidecar 呼叫。
+2. 讓路由模型在一個小型 **agentic 迴圈**中執行。模型呼叫 `web_search` 時，opencodex 使用所選
+ 後端：OpenAI 預設以 `gpt-5.6-luna` 執行託管 `web_search`；Anthropic 預設以
+ `claude-sonnet-5` 執行 `web_search_20250305`。Streaming 答案及引用會解析為工具結果。
+3. **迴圈**直到模型回答，或真實查詢總數達到 `maxSearchesPerTurn`（預設 3）。達到上限後會移除
+ search 工具並強制生成最終答案。如果模型呼叫 `apply_patch` 或 shell 等真實用戶端工具，目前
+ turn 會結束，以便這些呼叫到達 Codex。
+
+路由模型的每次迭代都會向上遊請求 `stream: true`，但 opencodex 會在決定搜尋還是回傳最終答案前，
+在內部完整緩衝所有語義 event。只有第一次迭代的最終 header/status 和 429 key rotation 會被提前
+取得。因此，合成搜尋呼叫和中間輸出不會作為模型輸出暴露給用戶端。
+
+注入結果會包裹在不可信資料邊界中，限制長度，並按來源 URL 去重。在結構化輸出 turn
+（`json_schema` / `json_object`）中，結果會以緊湊 JSON 而不是普通文字傳入。若路由模型是純文字
+模型，search 模型還會收到指令，用文字描述相關圖像並附上來源 URL。
+
+```json
+{
+ "webSearchSidecar": {
+ "enabled": true,
+ "backend": "anthropic",
+ "model": "claude-sonnet-5",
+ "reasoning": "low",
+ "maxSearchesPerTurn": 3,
+ "routedModelStallTimeoutMs": 200000,
+ "timeoutMs": 200000
+ }
+}
+```
+
+託管後端不允許在 `minimal` reasoning 下使用工具，因此預設值為 `low`。搜尋失敗時，路由模型會
+收到長度受限的錯誤結果，仍可依據已有上下文繼續回答。
+
+此路徑採用四個相互獨立的時鐘。`stallTimeoutSec` 是基礎 bridge event-stall 預算。
+`connectTimeoutMs`（預設 `200000`）只限制 DNS/TCP/TLS 和最終回應 header。僅可在設定檔中
+設定的 `webSearchSidecar.routedModelStallTimeoutMs`（預設 `200000`，整數
+`1..2147483647`）限制每次路由模型迭代中原始回應 byte 連續無活動的時間，並在收到每個非空 byte
+時重置。`webSearchSidecar.timeoutMs` 獨立限制單次託管搜尋請求。實際 bridge watchdog 為
+`max(基礎 stall, connect timeout, 路由模型 stall, sidecar timeout) + 30 秒`。路由模型 stall
+不是總生成 timeout。SSE 開始前的失敗會回傳非 2xx JSON；回應 header 開始後發生的生成失敗則以
+`response.failed` SSE 傳遞。
+
+## Vision sidecar
+
+當路由模型列在其 provider 的 `noVisionModels` 中，並且請求包含圖像時，opencodex 會在主呼叫
+**之前**描述每張圖像，並用文字替換圖像。Dashboard 和管理 API 目前顯示的預設值是
+`gpt-5.6-luna`，啟動時也會把明確儲存的舊 `gpt-5.4-mini` 值遷移到 Luna。只有在
+`visionSidecar.model` 欄位完全不存在時，vision 執行路徑才會使用程式碼中的 `gpt-5.4-mini` 回退值。
+
+- 圖像可以來自 user、developer 和 tool-result message，也包括 Codex 的 `view_image` 結果。
+- 每張圖像會以 `reasoning.effort: "low"` 傳送給設定的原生 vision 模型，描述結果會就地替換
+ 圖像部分。
+- 描述任務最多同時處理 3 張圖像，並保持輸入順序。傳送給描述模型的使用者上下文最多 800 個字元，
+ 每張圖像注入的描述最多 2,000 個字元。請求不會傳送 ChatGPT 後端不支援的
+ `max_output_tokens`。
+- 圖像 URL 會在轉發前校驗。data URL 必須是 `png` / `jpeg` / `jpg` / `webp` / `gif`，base64
+ 資料限制在約 20 MB；只接受 `data:` 和 `https:` scheme。遠端 `https` 圖像由 OpenAI 後端取得，
+ 而不是代理。
+- `noVisionModels` 匹配會忽略 Ollama 風格的 `:size` 字尾，因此一個 `gpt-oss` 條目也能覆蓋
+ `gpt-oss:120b`。
+- 如果描述失敗，模型會收到簡短的處理錯誤提示。若根本無法建立 sidecar plan，原始圖像會被
+ 移除，而不會繼續轉發給純文字後端。
+- `maxDescriptionsPerTurn`（預設 8）限制每個主模型 turn 的新增描述次數。快取命中和同一 turn
+ 的重複請求不會消耗配額。成功的 `data:` 圖像描述會按後端、模型、detail、圖像位元組和訊息上下文
+ 快取；內容可變的 `https:` 圖像不會快取。
+
+```json
+{
+ "visionSidecar": {
+ "enabled": true,
+ "backend": "anthropic",
+ "model": "claude-sonnet-5",
+ "maxDescriptionsPerTurn": 8,
+ "timeoutMs": 45000
+ }
+}
+```
+
+純文字模型按 provider 標記：
+
+```json
+{
+ "providers": {
+ "ollama-cloud": {
+ "adapter": "openai-chat",
+ "baseUrl": "https://ollama.com/v1",
+ "noVisionModels": ["glm-5.2", "gpt-oss", "qwen3-coder", "deepseek-v4-pro"]
+ }
+ }
+}
+```
+
+## 儀表板設定與停用
+
+
+
+設定檔欄位現在即可使用。如需停用某個 sidecar，請在 `config.json` 中把對應的 `enabled` 設為
+`false`。Anthropic OAuth 搜尋和圖像描述沿用現有 Claude Code OAuth fingerprint 先例，但仍應使用
+目標帳號和實際負載充分 soak test。所有欄位見
+[設定參考](/zh-tw/reference/configuration/#sidecars)。
diff --git a/docs-site/src/content/docs/zh-tw/guides/sub-agent-surface.md b/docs-site/src/content/docs/zh-tw/guides/sub-agent-surface.md
new file mode 100644
index 000000000..d67957018
--- /dev/null
+++ b/docs-site/src/content/docs/zh-tw/guides/sub-agent-surface.md
@@ -0,0 +1,222 @@
+---
+title: 子代理介面（v1 / base / v2）
+description: 全域控制 Codex 在所有模型上生成和管理子代理的方式。
+---
+
+opencodex 允許你為目錄中的所有模型選擇多代理協作介面。儀表板和 Models 頁面中的 **Sub-agent** 開關會全域控制這一設定。
+
+:::note
+在 v2 介面（`multi_agent_v2`）上，子代理**預設**繼承父會話的模型：`fork_turns` 預設為 `all`，而全量歷史 fork 會拒絕覆蓋。自 v2.7.2 起，opencodex 注入的指引會教模型如何打破繼承 —— 將 `fork_turns` 設為 `"none"`（或如 `"3"` 的部分 fork）的 `spawn_agent` 呼叫可以傳入 `model` / `reasoning_effort` 引數；即使公開的工具 schema 中看不到這些引數，Codex 執行環境也會解析並應用。已知傳輸限制：當**原生**父代理 spawn 一個路由到**非原生** provider 的子代理時，Codex 用戶端可能只以後端加密的 `encrypted_content` 傳送 `NEW_TASK` 載荷（[#92](https://github.com/lidge-jun/opencodex/issues/92)）。opencodex 不會把這種無法讀取的任務轉發給外部 provider：直接路由會回傳 HTTP 400 和錯誤碼 `unreadable_encrypted_agent_task`；組合路由則會跳過無法解密的目標，並在存在可用目標時選擇規範的原生 ChatGPT 目標。恢復方法：異構 provider 委派改用 v1、選擇原生 ChatGPT 子代理，或將任務重新作為明文 v2 `agent_message` 內容傳送。
+:::
+
+## What sub-agents are
+
+子代理是主代理為了專注任務而建立的一個獨立 Codex worker。它有自己的 context 與工具，因此多個
+獨立任務可以平行執行。opencodex 控制哪些 Codex 協作介面會暴露這些 worker、Codex 為它們提供哪些
+模型，以及失敗的模型如何回退。它不會決定你的主代理何時必須委派。
+
+## 模式
+
+| 模式 | 介面 | 行為 |
+| --- | --- | --- |
+| **v1** | `multi_agent_v1` | 使用經典的名稱空間代理工具，以及 `send_input` / `close_agent` / `resume_agent`。`spawn_agent` 的模型覆蓋可以在其他模型上生成子代理。 |
+| **base**（預設） | 上游固定值 | 恢復上游模型的固定值：gpt-5.6-sol 和 gpt-5.6-terra 使用 v2，gpt-5.6-luna 使用 v1；未固定的模型遵循 Codex 的 `multi_agent_v2` 功能開關。生成行為取決於該模型最終使用的介面。 |
+| **v2** | `multi_agent_v2` | 使用扁平的 `spawn_agent` 工具、併發會話，以及 `send_message` / `followup_task` / `wait_agent` / `interrupt_agent`。全量歷史 fork 時子代理繼承父模型；`fork_turns: "none"`（或部分 fork）時接受 `model` / `reasoning_effort` 覆蓋。如果原生→路由子代理只收到後端加密的任務內容，外部路由會回傳 `unreadable_encrypted_agent_task`；混合組合會優先選擇可解密的原生目標（[#92](https://github.com/lidge-jun/opencodex/issues/92)）。 |
+
+## 運作原理
+
+所選模式會設定 Codex 讀取的每個目錄條目中的 `multi_agent_version` 欄位：
+
+- **v1 模式**：強制所有條目使用 `multi_agent_version = "v1"`，覆蓋上游固定值。
+- **base 模式**：恢復上游預設值。已固定的模型使用快照值；未固定的模型不寫入該欄位，交由 Codex 功能開關決定。
+- **v2 模式**：強制所有條目使用 `multi_agent_version = "v2"`，覆蓋上游固定值。
+
+無論是即時 `/v1/models` 目錄回應，還是磁碟目錄同步，這項覆蓋都會作為最後一步執行。因此，無論條目原本如何生成，新會話都會使用一致的模式。
+
+## 委託模型與推理強度
+
+儀表板的 **子代理委託** 控制三個相關設定：
+
+- `injectionModel` 是 opencodex 指引中點名的偏好 worker 模型。
+- `injectionEffort` 是為該模型要求選用的 `reasoning_effort`。
+- `injectionPrompt` 取代內建的 v2 指引文字。
+
+`multiAgentGuidanceEnabled` 預設開啟，是 opencodex 撰寫的指引在兩個介面上的主開關。關閉它會同時
+抑制 v2 指定區塊與 v1 主動文字。
+
+這些是給主代理的指示，不是 proxy 端的 spawn 路由器。在 v2 上，全量歷史 fork 會繼承父模型並拒絕
+模型或 effort 覆蓋。因此指引會告訴 Codex 在傳遞 `model` 或 `reasoning_effort` 時使用
+`fork_turns: "none"`（或正數的部分回合數，例如 `"3"`），並讓任務訊息自足。
+
+自訂 `injectionPrompt` 文字可以使用全部四個佔位符：
+
+| 佔位符 | 取代為 |
+| --- | --- |
+| `{{model}}` | 本次請求的有效偏好模型。裸的原生 `injectionModel` 只有在請求本身指向明確的帳號選擇器時才以帳號限定。無法解析或歧義的裸值會變成空字串；無法解析的明確帳號限定或路由 id 保持不變 |
+| `{{effort}}` | 設定的 `injectionEffort`，或空字串 |
+| `{{roster}}` | 解析出的 picker 可見、介面相容名冊 |
+| `{{fallback}}` | 設定的全域 fallback 指引 |
+
+內建 v2 指引有 700 字元的預算。若會超過預算，opencodex 會先丟掉名冊而不是截斷核心 spawn 指示。
+內建指引只在偏好模型、合格名冊或 fallback 鏈解析成功時觸發。設定了 `injectionModel` 就足以渲染
+自訂提示詞；若裸值無法唯一解析，`{{model}}` 會展開為空字串。
+
+在 v1 上，opencodex 只在 `max` / `ultra` effort 注入上游風格的主動委派指引。v1 不會附加偏好模型、
+名冊、fallback 清單或自訂提示詞。
+
+預設關閉的 `syncCodexSubagentDefaults` 選項與指引無關。當 opencodex 擁有作用中的 Codex 路由時，
+sync 或 restart 可以把選定值寫成帶 marker 的 `[agents] default_subagent_model` 和
+`default_subagent_reasoning_effort` 項目，放進 Codex TOML。opencodex 只更新或移除帶有自己 marker 的
+欄位。若任一目標欄位為使用者所有，整對會保持不變而不部分寫入；有歧義的 TOML 會被拒絕而不寫入。
+外部供應商管理器與使用者擁有的根路由仍然保持權威。
+
+## Fallback chains
+
+對生成的 worker，opencodex 建立這個優先順序：
+
+1. 請求的主要模型。
+2. opencodex 設定中 `subagentModelFallbackByModel` 的 per-model 鏈，以請求的主要模型為鍵。
+3. opencodex 設定中的全域 `subagentModelFallback` 清單。
+
+Per-role fallback 鏈屬於 opencodex 設定，而不是 `$CODEX_HOME/agents/*.toml`。Codex 0.146+ 嚴格
+反序列化 agent role 檔案，並把 `model_fallback` 當作未知欄位拒絕，導致整個 role 定義被跳過（#1190）。
+opencodex 仍可為了向後相容從 TOML 讀取舊版 `model_fallback` 列，但 `ocx doctor` 會對此發出警告，
+而 Codex 本身會忽略受影響的 role。
+
+重複的模型 id 會被移除，同時保留第一次出現者。選擇期間，opencodex 會跳過已停用、無法路由、由已
+停用 provider 支撐、標記為不健康、在冷卻中、缺少可用 Pool 化 Codex 帳號，或超過設定配額閾值的
+候選。可用性探測會快取 `subagentModelFallbackPollMs`（預設 60 秒）。
+
+Fallback 不能讓不相容的加密任務變成可讀。當子任務是為 ChatGPT 加密時，即使外部模型在鏈中出現得
+更早，選擇也會限制在規範的原生 ChatGPT 目標。
+
+## 加密的 v2 任務傳輸
+
+Codex 可能只以後端加密的 `encrypted_content` 傳送 v2 原生→路由子任務。該載荷可以被原生 ChatGPT
+後端讀取，但外部 provider 無法讀取。這是已知的
+[#92 限制](https://github.com/lidge-jun/opencodex/issues/92)。
+
+opencodex 會安全失敗，而不是轉發空或無法讀取的任務：
+
+- 直接的非原生路由回傳 HTTP 400，帶有 `error.code = "unreadable_encrypted_agent_task"`，且不會回顯
+ 密文。
+- 組合只會為該任務考慮規範的原生 ChatGPT 目標，包括重試。若沒有可用目標，回傳相同的 400。
+- 可讀取的明文任務保持正常的路由與 fallback 行為。
+
+恢復方法：選擇原生 ChatGPT 子代理、在組合中加入原生 ChatGPT 目標、異構 provider 委派改用 v1，
+或在你能控制呼叫方時將任務重新作為明文 v2 `agent_message` 內容傳送。
+
+## 更改模式
+
+### GUI
+
+- **Dashboard** → 第一個狀態單元：選擇 **v1**、**base** 或 **v2**。
+- **Models** 頁面 → 使用頂部的分段控制元件。
+- 兩個頁面都有 **?** 按鈕，可開啟幫助彈窗並返回本文。
+- **Dashboard** → **子代理委託**：選擇首選模型和可選的推理強度。在 v2 上，注入的指引會要求以 `fork_turns: "none"` 生成，使模型覆蓋得以應用。如果原生→路由子代理只收到加密任務內容，請使用原生目標或 v1；僅外部目標的傳輸現在會明確回傳 `unreadable_encrypted_agent_task`（[#92](https://github.com/lidge-jun/opencodex/issues/92)）。
+
+### CLI
+
+```bash
+ocx v2 mode v1 # 強制所有模型使用 v1
+ocx v2 mode default # 恢復上游固定值
+ocx v2 mode v2 # 強制所有模型使用 v2
+ocx v2 status # 顯示目前模式和 Codex 功能開關
+```
+
+### API
+
+```bash
+# 讀取介面模式、功能開關和執行緒上限
+curl http://localhost:10100/api/v2
+
+# 設定介面模式
+curl -X PUT http://localhost:10100/api/v2 \
+ -H 'Content-Type: application/json' \
+ -d '{"multiAgentMode": "v2"}'
+```
+
+`/api/v2` 的 PUT 端點還接受 `enabled`（布林值，Codex 功能開關）和 `maxConcurrentThreadsPerSession`（整數）。它會驗證請求、儲存模式、重新同步目錄，並提示模式更改從新會話開始生效。
+
+委託選擇器使用另一個端點：
+
+```bash
+# 讀取目前模型/推理強度和可選值
+curl http://localhost:10100/api/injection-model
+
+# 同時設定兩個值
+curl -X PUT http://localhost:10100/api/injection-model \
+ -H 'Content-Type: application/json' \
+ -d '{"model": "anthropic/claude-sonnet-5", "effort": "xhigh"}'
+
+# 設定自訂指引提示詞（{{model}}/{{effort}}/{{roster}} 佔位符）
+curl -X PUT http://localhost:10100/api/injection-model \
+ -H 'Content-Type: application/json' \
+ -d '{"model": "anthropic/claude-sonnet-5", "prompt": "委託給 {{model}}。{{roster}}"}'
+
+# 清除兩個值
+curl -X PUT http://localhost:10100/api/injection-model \
+ -H 'Content-Type: application/json' \
+ -d '{"model": null}'
+```
+
+`GET /api/injection-model` 回傳 `model`、`effort`、`prompt`、全域 `efforts` 階梯，以及由已啟用原生/路由模型組成的 `available` 列表。PUT 請求省略 `effort` 或 `prompt` 時會保留目前值，傳入 `null` 時會清除它；清除 `model` 一定會同時清除推理強度。API 會按全域 Codex 階梯驗證推理強度，Codex 仍會在生成時檢查目標目錄條目是否支援該強度。
+
+## FAQ
+
+### 選擇委託模型會強制 Codex 生成它嗎？
+
+不會。指引可以推薦模型，原生預設同步可以提供 Codex 預設值，但主代理仍然決定是否委派。
+
+### 為什麼我的 v2 子代理使用了父模型？
+
+全量歷史 v2 fork 會繼承父模型。請在傳遞模型或 effort 覆蓋之前，使用把 `fork_turns` 設為 `"none"`
+或正數部分計數的 spawn。
+
+### 為什麼設定的模型沒有出現在 v2 名冊中？
+
+它可能是 picker 隱藏、超出五個模型的顯示上限、不在目錄中，或固定為 v1。值為 `"v2"`、`null` 或缺
+少介面值的項目合格；真正的 `"v1"` 固定值不合格。
+
+### 模式變更會影響執行中的工作階段嗎？
+
+不會。變更模式後請開啟新的 Codex 工作階段。若長時間執行的 App host 仍顯示過時的目錄狀態，請執行
+`ocx sync` 並重新啟動該 Codex 介面。
+
+### 當 opencodex 無法信任目錄時會發生什麼？
+
+opencodex 會將磁碟上的模型目錄與目前使用者擁有的每個 Codex app-server 啟動時間比較，產生四種狀態之一：
+
+| 狀態 | 意義 | v2 指引 |
+|---|---|---|
+| `fresh` | 每個 app-server 都在目錄寫入之後啟動 | 完整指引：偏好模型、roster、fallback |
+| `not_running` | 未偵測到 app-server | 完整指引 |
+| `stale` | 至少一個 app-server 早於目錄 | **不新增或覆寫 opencodex 撰寫的模型指引** |
+| `unknown` | 無法進行比較 | **不新增或覆寫 opencodex 撰寫的模型指引** |
+
+對 `stale` 與 `unknown`，opencodex 會保留其自身的磁碟衍生宣稱——偏好模型、roster、fallback 與自訂指引——因為執行中的 Codex 可能無法生成磁碟目錄所廣告的內容。
+
+它**不會**指示模型停止設定 `model` 或 `reasoning_effort`。該觀察對使用者擁有的每個 app-server 都是全域的，而入站請求不帶傳送者身分，因此無法將過時的 process 歸因於眼前的請求。基於此禁止覆寫會封鎖現用 `spawn_agent` 工具合法廣告的選項——而該 session 可能其實是新的。現用工具 schema 保持權威。
+
+`unknown` 不是 `stale` 的同義詞。它表示比較本身失敗——目錄時間戳不可讀、process 啟動時間不可讀或 process 列舉失敗——並由 `ocx doctor` 分開回報。`stale` 僅在每個偵測到的 Codex app-server 都在最後一次目錄寫入後啟動時才清除；它不一定會清除 `unknown`。
+
+### 推理強度
+
+可選的子代理推理強度儲存在 `injectionEffort` 中，只有同時設定注入模型時才有意義。它會向注入的 v2 指引加入 `reasoning_effort` 要求，但不會改變父會話的推理強度。在接受覆蓋的 fork 上，Codex 會直接應用傳給 `spawn_agent` 的 `reasoning_effort`。
+
+在 Codex 目錄中，`ultra` 的級別高於 `max`，並帶有自動委託語義；但 provider 永遠不會線上路上收到字面量 `ultra`。Codex 會在用戶端邊界將 `ultra` 轉成 `max`，隨後 opencodex 再確保 provider 收到有效值：
+
+| 模型 | 線路上的 `max` | 選擇 `ultra` 後的線路值 |
+| --- | --- | --- |
+| gpt-5.5、gpt-5.4、gpt-5.4-mini | xhigh | xhigh（先轉為 max，再經 `nativeEffortClamp`） |
+| gpt-5.6-sol、gpt-5.6-terra | max | max |
+| gpt-5.6-luna | max | 其精確上游階梯不提供該選項 |
+| 路由模型 | 由適配器對映或限制 | 先轉為 max，再由適配器對映或限制 |
+
+目錄中是否提供某個推理強度與 v1/v2 模式無關。支援推理的生成條目會提供 `max`，使直接指定的子代理強度能夠透過驗證；目前生成的路由條目還會提供 `ultra`。精確的上游模型階梯會原樣保留，因此 gpt-5.6-luna 最高只到 `max`。
+
+### 上下文上限
+
+全域上下文上限值預設為 350k。它只會限制已啟用上限的路由 provider 所廣告的 `context_window`；原生 OpenAI 模型保留其真實上下文視窗。
+
+你可以在 Models 頁面更改上限值或全體 provider 設定，也可以透過各 provider 分組標題旁的開關單獨啟用或停用上限。
diff --git a/docs-site/src/content/docs/zh-tw/guides/video-bridge.md b/docs-site/src/content/docs/zh-tw/guides/video-bridge.md
new file mode 100644
index 000000000..caa500077
--- /dev/null
+++ b/docs-site/src/content/docs/zh-tw/guides/video-bridge.md
@@ -0,0 +1,80 @@
+---
+title: Video Bridge
+description: 透過非 OpenAI 模型使用 Grok Imagine Video 生成影片。
+---
+
+## 概觀
+
+Video Bridge 讓你透過 opencodex 路由的任何非 OpenAI 模型，使用 xAI 的 Grok Imagine Video 生成。啟用後，對話中會注入一個合成的 `video_gen` 工具。模型像呼叫一般函式工具一樣呼叫它；opencodex 攔截該呼叫、向 xAI 提交影片生成工作、輪詢直到完成，並下載結果。
+
+## 前置條件
+
+- 一個帶有 **API key** 的 `xai` 供應商項目（單靠 `ocx login xai` 不足夠 — video bridge 需要 key 認證，而非 OAuth）
+- 一個非 OpenAI 模型作為你的路由供應商（例如 Anthropic Claude、Google Gemini）
+- opencodex 設定為透過該非 OpenAI 供應商路由
+
+> **⚠ 需要供應商 key：** Video Bridge 僅在 `xai` 供應商使用
+> API key 認證時啟用。將以下加入你的設定：
+>
+> ```json
+> {
+> "providers": {
+> "xai": { "adapter": "openai-chat", "apiKey": "xai-…", "authMode": "key" }
+> }
+> }
+> ```
+>
+> 若你是透過 `ocx login xai`（OAuth）接入，供應商會停留在 `authMode: "oauth"`，bridge 不會悄悄啟用。請在環境中設定 `XAI_API_KEY`，**或**如上所示直接寫入 key。
+
+## 設定
+
+將 `videoBridgeEnabled: true` 加入你的 `images` 設定：
+
+```json
+{
+ "images": {
+ "bridgeEnabled": true,
+ "videoBridgeEnabled": true,
+ "videoBridgeModel": "grok-imagine-video",
+ "videoMaxRounds": 2,
+ "videoTimeoutMs": 300000
+ }
+}
+```
+
+| 選項 | 預設值 | 說明 |
+|--------|---------|-------------|
+| `videoBridgeEnabled` | `false` | 總開關。必須明確啟用。 |
+| `videoBridgeModel` | `"grok-imagine-video"` | xAI 影片模型 id。 |
+| `videoMaxRounds` | `2` | 強制最終回答前的最大 video-gen 回合數。 |
+| `videoTimeoutMs` | `300000`（5 分鐘） | 每支影片包含輪詢在內的逾時。 |
+
+## 運作方式
+
+1. opencodex 偵測到帶有 `videoBridgeEnabled: true` 的非 OpenAI 路由模型
+2. 對話中注入一個合成的 `video_gen` 函式工具
+3. 當模型呼叫 `video_gen` 時，opencodex 向 xAI 的 `/videos/generations` 提交工作
+4. Bridge 每 5-15 秒輪詢工作狀態，並發送 heartbeat 訊息以保持串流活躍
+5. 影片就緒後，下載到 artifacts 目錄
+6. 本機檔案路徑作為工具結果回傳給模型
+
+## 支援的參數
+
+`video_gen` 工具接受：
+
+| 參數 | 型別 | 範圍 | 說明 |
+|-----------|------|-------|-------------|
+| `prompt` | string | 必填 | 詳細的影片生成 prompt |
+| `duration` | integer | 1-15 | 影片長度（秒） |
+| `resolution` | string | `"480p"`、`"720p"` | 影片解析度 |
+| `aspect_ratio` | string | 7 種比例 | `16:9`、`9:16`、`1:1`、`4:3`、`3:4`、`3:2`、`2:3` |
+
+## 限制
+
+- **僅限 xAI**：影片生成僅能透過 xAI 的 Grok Imagine Video API 使用
+- **非同步**：影片生成需 30-120 秒
+- **費用**：影片生成是付費的 xAI 功能（~$0.05/秒 @480p、~$0.07/秒 @720p）
+- **每次呼叫一支影片**：每次 `video_gen` 呼叫產生一支影片
+- **與 Image Bridge 共存**：兩個 bridge 可同時啟用
+- **網頁搜尋優先**：當某回合有網頁搜尋 sidecar 啟用時（非 `runTurn` adapter），video bridge 會被略過 — 兩者無法並行執行。會發出 `console.warn` 讓你可在日誌中偵測到此情況。
+- **逾時涵蓋提交與輪詢**：`videoTimeoutMs` 預算在工作提交前就開始計算，因此提交呼叫（60 秒）與後續輪詢共用同一個截止時間。
diff --git a/docs-site/src/content/docs/zh-tw/guides/web-dashboard.md b/docs-site/src/content/docs/zh-tw/guides/web-dashboard.md
new file mode 100644
index 000000000..67828d56b
--- /dev/null
+++ b/docs-site/src/content/docs/zh-tw/guides/web-dashboard.md
@@ -0,0 +1,144 @@
+---
+title: Web 儀表板
+description: 用於管理代理健康狀態、provider、模型、委派指引、認證池、usage 和日誌的 opencodex GUI。
+---
+
+opencodex 內建了一個由代理提供服務的本機 web 儀表板（`gui/` 下的 Vite/React 應用）。你可以在
+這裡快速管理 provider、Codex/ChatGPT 帳號、目錄模型、sidecar、子代理設定和請求流量。
+
+## 開啟儀表板
+
+```bash
+ocx gui
+```
+
+該命令會在瀏覽器中開啟 `http://localhost:`；如果代理尚未執行，會先自動啟動。開發時也可
+讓 GUI dev server 單獨連線到正在執行的代理：
+
+```bash
+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`；是否儲存完全
+由瀏覽器或密碼管理員決定。
+
+## 可以完成哪些操作
+
+| 區域 | 作用 |
+| --- | --- |
+| **Dashboard 摘要** | 顯示 multi-agent 模式、線上狀態、版本、運行時間、provider 數量、30 天 token 總量、活動 provider 和可用的原生/路由模型。 |
+| **Sub-agent delegation** | 為 v1 委派 prompt 選擇原生或路由模型，並可指定 reasoning 強度。它不是逐次生成的路由器，詳見下文。 |
+| **Sidecar** | 選擇 web-search 模型及強度，以及圖像描述模型；更改從下一次請求開始生效。 |
+| **Maintenance** | 重新同步 Codex 模型目錄，檢視專案級設定繞過警告，檢查 latest/preview 版本，並可在更新後重啟代理。 |
+| **啟動安全** | 顯示注入的 Codex 路由能否在重啟後繼續工作，並分別顯示服務、launcher shim 狀態和準確的修復命令。 |
+| **Windows 托盤** | 安裝使用者登入托盤，一鍵控制代理啟動、停止、重啟、面板和狀態。托盤不是代理重啟服務。 |
+| **Codex 自動啟動** | 允許已安裝的 Codex launcher shim 執行 `ocx ensure`。此開關不會安裝 shim 或後臺服務。 |
+| **Providers** | 新增、編輯、啟用/停用、刪除 provider，並在支援時管理 OAuth 帳號池和 API key 池。 |
+| **Add provider** | 搜尋 registry preset，選擇帳號登入、API key 服務、本機伺服器或自訂 endpoint。 |
+| **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`）。 |
+
+### 連結到某個部分
+
+佈局只有一種，無需切換。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 強度，都會
+啟用這段指引；清除模型時也會清除已儲存的強度。
+
+:::caution
+該選擇器是面向 v1 相容介面的委派指引。在 `multi_agent_v2` 中，目前代理不會附加 v1 注入訊息，
+而且所有生成的子代理都會繼承父 session 的模型。它不是代理側的跨模型路由器。v1/base/v2 的
+權威說明見 [子代理介面](/zh-tw/guides/sub-agent-surface/)。
+:::
+
+選擇器會列出已啟用的原生與路由模型，以及全域 Codex reasoning 階梯。API 會先驗證所選強度是否
+屬於全域階梯；Codex 仍會根據目標目錄條目再次校驗該 spawn 強度。
+
+## Codex Auth 與帳號池
+
+**Codex Auth** 頁面用於管理原生 ChatGPT/Codex 路由：
+
+- 手動選擇帳號會影響下一次新建的 Codex session；已經繫結帳號的 thread 不會因為這次手動切換而
+ 在中途轉移。
+- Thread affinity 可避免每個請求都來回切換帳號。啟用配額自動切換後，長時間執行的 thread 會被
+ 定期重新評估；當相關 usage 達到閾值，並且存在使用率確實更低的可用帳號時，該 thread 可能會
+ 重新繫結。
+- 新 session 可以選擇 usage 最低的可用帳號。付費計劃按已知 5h、每週、30d 視窗中的最高使用率
+ 評分；Go/Free 計劃只使用 30d 視窗。
+- **Refresh quotas** 會立即重新讀取帳號 usage，使路由邏輯與頁面上的帳號卡片使用同一份資料。
+- 池帳號的請求日誌使用 `p3fa91c` 這類不透明標籤，不會記錄帳號郵箱。
+
+## 星標是你的決定，不是 agent 的
+
+側邊欄的星標按鈕——以及 `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 並退出。 |
+
+:::tip
+從儀表板新增 **Ollama Cloud** 或其他目錄型 provider 時，其文字/視覺模型分類會寫入儲存的
+provider 設定。因此無需手動分類，[vision sidecar](/zh-tw/guides/sidecars/) 也能在正確
+條件下啟用。
+:::
diff --git a/docs-site/src/content/docs/zh-tw/index.mdx b/docs-site/src/content/docs/zh-tw/index.mdx
new file mode 100644
index 000000000..bceb54865
--- /dev/null
+++ b/docs-site/src/content/docs/zh-tw/index.mdx
@@ -0,0 +1,17 @@
+---
+title: "opencodex — 讓 Codex 跑在任意 LLM 上"
+description: 適用於 OpenAI Codex 與 Claude Code 的通用供應商代理 —— 在 Codex CLI、App、SDK 和 Claude Code 中使用任意 LLM。
+template: splash
+head:
+ - tag: title
+ content: "opencodex — 讓 Codex 跑在任意 LLM 上"
+ - tag: meta
+ attrs:
+ property: og:locale
+ content: zh_TW
+tableOfContents: false
+---
+
+import Landing from '../../../components/Landing.astro';
+
+
diff --git a/docs-site/src/content/docs/zh-tw/reference/adapters.md b/docs-site/src/content/docs/zh-tw/reference/adapters.md
new file mode 100644
index 000000000..2859d0d50
--- /dev/null
+++ b/docs-site/src/content/docs/zh-tw/reference/adapters.md
@@ -0,0 +1,140 @@
+---
+title: 轉接器
+description: 七個 provider adapter 的目標、請求建置方式與各自特性。
+---
+
+**adapter** 負責在 opencodex 的內部請求/回應模型與某個 provider 的 wire 格式之間轉換。每個
+adapter 都實作 `ProviderAdapter` 介面（`src/adapters/base.ts`）：
+
+```ts
+interface ProviderAdapter {
+ name: string;
+ buildRequest(parsed, incoming?): AdapterRequest | Promise;
+ fetchResponse?(request, context): Promise; // custom retry/transport
+ parseStream(response): AsyncGenerator;
+ parseResponse?(response): Promise; // non-streaming
+ runTurn?(parsed, incoming, emit): Promise; // bidirectional transport
+}
+```
+
+`buildRequest` 把 `OcxParsedRequest` 轉成上游 HTTP 請求；`parseStream` / `parseResponse` 把 provider
+回覆轉回內部 `AdapterEvent`。`fetchResponse` 允許 adapter 自己負責重試和 timeout；`runTurn` 支援
+無法表示成一次 HTTP fetch 加一條回應流的 transport。隨後
+[`bridge.ts`](/zh-tw/reference/architecture/#橋接器) 把 event 轉成 Responses SSE。
+
+## `openai-chat`
+
+**目標：** OpenAI **Chat Completions**（`POST {baseUrl}/chat/completions`）以及所有相容 provider，
+包括 xAI、Kimi、DeepSeek、GLM、Groq、OpenRouter、Ollama（本機與雲端）等。
+**認證：** `key`（Bearer）。
+
+- 把內部訊息轉換成 OpenAI role；工具對映為 `{type:"function", function:{…}}` 和
+ `tool_choice`（`auto`/`none`/`required` 或具名函式）。
+- **重寫 Codex 的 GPT-5 身份提示詞**，改成與模型無關的介紹，避免路由模型自稱 OpenAI。
+- 精確層級不可用時，**把 `reasoning_effort` 限制到模型公佈的子集**。除非 provider 顯式設定
+ alias，`xhigh` 與 `max` 保持為不同標籤。對於 `provider.noReasoningModels` 中的 id，則**完全
+ 省略**該引數。
+- 流式輸出 `delta.content`（文字）、`delta.reasoning_content`（thinking）和
+ `delta.tool_calls[]`，並收集 `usage`。
+
+## `openai-responses`
+
+**目標：** OpenAI **Responses API**。**`passthrough: true`** —— 轉發原始請求 body，並把回應
+**不經轉換**地流式傳回。
+**認證：** `forward`（轉發呼叫方 header）或 `key`。
+
+- `forward` URL → `{baseUrl}/responses`。`key` provider 預設保留原有的 `{baseUrl}/v1/responses` 構造。
+- `key` provider 可設定經過驗證的相對 `responsesPath`；adapter 會移除 `baseUrl` 末尾的一個 `/`，並向 `{trimmedBaseUrl}{responsesPath}` 傳送請求。Ark Agent Plan 使用 `baseUrl: "https://ark.cn-beijing.volces.com/api/plan/v3"` 和 `responsesPath: "/responses"`。
+- `forward` 模式只會轉發安全的 header allowlist（`FORWARD_HEADERS`）：authorization、ChatGPT
+ account id 和 OpenAI beta/originator/session header。這條 ChatGPT 登入路徑也為
+ [sidecar](/zh-tw/guides/sidecars/) 提供支援。
+
+## `anthropic`
+
+**目標：** Anthropic **Messages**（`/v1/messages`）。
+**認證：** `key`（`x-api-key`）或 `oauth`（Bearer + `anthropic-beta`，用於 Claude Pro/Max）。
+
+- 把訊息轉換成 Anthropic content block（text、base64 image、`tool_use`、`thinking`）。
+- **Extended thinking 計算：** Anthropic 要求 `max_tokens > thinking.budget_tokens`。adapter 把
+ reasoning effort 對映成 budget（minimal 1024 … max 32000），再計算留有輸出餘量的安全
+ `max_tokens`；啟用 thinking 後會**移除 `temperature`/`top_p`**，因為 Anthropic 禁止此組合。
+- 始終傳送 `anthropic-version: 2023-06-01`。流式輸出
+ `content_block_delta`（`text_delta`、`thinking_delta`、`input_json_delta`）。
+
+## `google`
+
+**目標：** Google **Gemini**、**Vertex AI** 和 Antigravity **Cloud Code Assist**。AI Studio 使用
+`/v1beta/models/{model}:streamGenerateContent`，其他模式使用各自的 Google 原生 endpoint。
+**認證：** 根據 `googleMode` 選擇 API key、Vertex ADC 或 Google Antigravity OAuth。
+
+- 系統提示詞 → `systemInstruction`；訊息 → `contents[]`（assistant → `model`）；工具 →
+ `functionDeclarations`；data URL 圖像 → `inline_data`。
+- Gemini 省略 tool-call id 時會合成 id。Antigravity 會保留並重放真實 `thoughtSignature`，使
+ reasoning continuity 延續到後續 turn。
+
+## `kiro`
+
+**目標：** Kiro 使用的 Amazon CodeWhisperer Streaming `GenerateAssistantResponse` 服務
+（`https://runtime.{region}.kiro.dev/`）。
+**認證：** Kiro credential 中的 region/profile metadata，加上作為 Bearer 的 Kiro OAuth access
+token。
+
+- 建置 Kiro `conversationState`，對映 Codex 工具和工具結果，併傳送 Kiro wire 支援的 image block。
+- 解碼 `application/vnd.amazon.eventstream`，重建 text/thinking/tool event，檢測被截斷的工具
+ JSON。上游不回傳 token 數量，因此 usage 採用估算值。
+- 經 `fetchResponse` 負責有界重試和分類/脫敏後的錯誤；非流式 parser 會排空同一 event stream，
+ 供 web-search loop 使用。
+
+### 完成與原生 stop reason
+
+Kiro 的 assistant 文字本身沒有可靠的回合結束標記，但終止的 `metadataEvent` 可能帶有原生 `stopReason`。
+`END_TURN` 和 `STOP_SEQUENCE` 視為權威結束，其文字直接作為最終回答發出，不再額外往返模型。
+
+只有在 stop reason **缺失**時才走相容路徑。任何顯式原因都已在上游終止了本次推理，因此適配器直接報告而不是
+再發一次請求：輸出 token 上限表現為可繼續的 incomplete，上下文視窗耗盡表現為不可重試的 context-length
+錯誤，內容過濾或 guardrail 停止表現為 filtered incomplete。沒有真實工具呼叫卻出現的 `TOOL_USE` 被視為
+矛盾而非進展。
+
+只有完全沒有 stop reason 時，opencodex 才新增私有的 `codex_kiro_final_answer` 工具並做一次續寫。
+重複抑制嚴格限定為空白歸一化後的完全一致：改寫過的狀態更新可能改變本回合的結果（從"仍在進行"變成"已完成"），
+丟掉那句話比顯示一次表面重複更糟糕。
+
+### Reasoning effort
+
+`gpt-5.6-sol` 和 `claude-opus-5` 支援原生 effort，且請求欄位名不同。`low` / `medium` / `high` /
+`xhigh` / `max` 分別透過 `additionalModelRequestFields.reasoning.effort` 和
+`output_config.effort` 傳送。
+
+
+## `cursor`
+
+**目標：** `api2.cursor.sh` 上採用 HTTP/2 Connect streaming 的
+`agent.v1.AgentService/Run`。
+**認證：** `provider.apiKey` 或轉發 authorization header 中的 Cursor OAuth/access token。
+
+- 使用 `runTurn`，而不是常規 fetch/parse 路徑。請求、server event、工具引數、usage checkpoint
+ 和 client reply 由 `cursor/gen/agent_pb.ts` 中的 `@bufbuild/protobuf` schema 編碼，並 frame 成
+ Connect message。
+- 經 content-addressed blob 重放對話狀態，把 server tool call 對映回 Codex，用 protobuf
+ `GetUsableModels` RPC 發現即時 Cursor 模型，並且只在 run request 尚未 commit 到 wire 前重試。
+- Cursor 原生本機 filesystem/shell/network 執行預設被拒絕。顯式 `mcpServers` 與
+ `desktopExecutor` 整合分別需要 opt-in；`unsafeAllowNativeLocalExec` 會啟用更廣泛的內建
+ executor，並繞過 Codex 審批和 sandbox 語義。
+
+## `azure-openai`（別名：`azure`）
+
+**目標：** **Azure OpenAI**。封裝 `openai-responses`，因此同樣是 `passthrough: true`。
+**認證：** 用 `api-key` header 進行 `key` 認證，而非 Bearer。
+
+- 把請求建置交給 Responses passthrough，驗證 `baseUrl` 不含未解析的 template placeholder，
+ 再用 `api-key` 替換 `Authorization`。設定的 URL 直接指向 Azure v1 Responses API，因此 adapter
+ 不會追加 `api-version`。
+
+## 圖像工具（`image.ts`）
+
+支援視覺的 adapter 共用以下 helper：
+
+- `parseDataUrl(url)` —— 把 `data:;base64,` URL 拆成 `{ mediaType, base64 }`，供
+ Anthropic/Google image block 使用。
+- `contentPartsToText(content)` —— 為純文字工具訊息把 content part 扁平化成文字。未描述的圖像
+ 會變成簡短的 `[image]` marker，而不是導致 token 暴漲的 base64 blob。
diff --git a/docs-site/src/content/docs/zh-tw/reference/architecture.md b/docs-site/src/content/docs/zh-tw/reference/architecture.md
new file mode 100644
index 000000000..3ca807a46
--- /dev/null
+++ b/docs-site/src/content/docs/zh-tw/reference/architecture.md
@@ -0,0 +1,165 @@
+---
+title: 架構
+description: opencodex 內部機制 —— 模組圖、請求解析器、AdapterEvent 橋接與快取。
+---
+
+opencodex 執行在單個 Bun 程序中。請求以 OpenAI Responses 格式進入，規範化為內部模型後完成
+路由，再由 adapter 傳送到 provider，最後橋接回 Responses SSE。端到端流程參見
+[運作原理](/zh-tw/getting-started/how-it-works/)。
+
+## 模組圖
+
+```text
+src/
+├── cli/ # ocx command dispatch, init, status, provider commands
+├── server/ # Bun.serve, /v1/* proxy, /api/* management API, WS bridge
+├── codex/ # Codex config injection, catalog sync, auth/account integration
+├── providers/ # provider metadata, API-key pool, quota and labels
+├── adapters/ # seven wire adapters, shared guards/utilities, Cursor protobuf transport
+├── oauth/ # OAuth providers, API-key catalog, token store/refresh
+├── usage/ # request usage extraction, JSONL logs, summaries, totals
+├── lib/ # runtime, process, retry, privacy, token estimate helpers
+├── web-search/ # web-search sidecar (synthetic tool, loop, executor, parser)
+├── vision/ # vision sidecar (describe + plan)
+├── config.ts # ~/.opencodex/config.json, defaults, PID, env resolution
+├── router.ts # model id → provider + adapter
+├── bridge.ts # AdapterEvent stream → Responses SSE / JSON
+├── reasoning-effort.ts # reasoning-effort translation, clamping, and catalog levels
+├── responses/
+│ ├── parser.ts # Responses request → OcxParsedRequest
+│ ├── schema.ts # Zod validation
+│ └── compaction.ts # remote compaction prompts, envelopes, compact history
+├── service.ts # launchd / systemd / Task Scheduler background service
+├── types.ts # core interfaces + helpers (modelInList, namespacedToolName)
+└── index.ts # public entry
+```
+
+原先的三個大型入口檔案現在是相容性 facade：`codex/catalog.ts` 匯出 7 個
+`codex/catalog/*.ts` 模組，`server/management-api.ts` 分派到 9 個
+`server/management/*.ts` 模組，而 `server/responses.ts` 匯出 5 個
+`server/responses/*.ts` 模組。
+
+## 請求流程
+
+`server/index.ts` 負責 HTTP 邊界，並把 Responses data plane 交給 `server/responses.ts` facade
+及其 `server/responses/*.ts` 模組：
+
+1. `server/index.ts` 應用 CORS 和 API 認證，在 drain 期間拒絕新請求，並記錄請求生命週期
+ metadata。它提供 `GET /v1/models`、`POST /v1/responses`、
+ `POST /v1/responses/compact`、`POST /v1/images/generations` / `POST /v1/images/edits`
+ （供 Codex 內建 `image_gen` 工具使用——由 `server/images.ts` 中繼到 OpenAI 繫上遊）、
+ `POST /v1/live` / `POST /v1/realtime/calls`（ChatGPT / Codex App 語音與 OpenAI Realtime
+ 建連，由 `server/live.ts` 中繼）、`/v1/live/{callId}` 旁路 WebSocket，
+ 以及 `/v1/responses` 上可選的 WebSocket upgrade。
+2. `server/responses/core.ts` 解壓並解析 JSON；如果本機記住了對應輸入，則展開
+ `previous_response_id`，隨後呼叫 `responses/parser.ts`。
+3. `router.ts` 解析 bare id 或 `provider/model` id。server 隨後確定 Codex account affinity，
+ 必要時重新整理 provider OAuth，並把選中的 credential 應用到 route。
+4. 主請求發出前，`vision/` 會為 `noVisionModels` 中的模型描述圖像。如果沒有安全的 sidecar
+ 路徑，則移除圖像，而不是把它傳送給純文字上游。
+5. `server/adapter-resolve.ts` 應用模型級 wire override，並構造七個 adapter 之一。Responses
+ passthrough 直接轉發原始 body；Cursor 執行雙向 `runTurn` transport；其餘轉換型 adapter
+ 則建置、取得並解析上游請求。
+6. 路由模型請求託管的 `web_search` 工具時，`web-search/` 會暴露一個合成函式，經 ChatGPT
+ sidecar 執行真實搜尋，把結果送回路由模型，並在設定的迴圈上限內重複。
+7. `bridge.ts` 生成 Responses SSE 或 JSON。`server/request-log.ts` 與 `usage/` 在不改變回應的
+ 前提下收集終止狀態、延遲、provider/model 標籤和盡力估算的 token usage。
+
+## 解析器
+
+`responses/parser.ts` 使用 `responses/schema.ts`（Zod）校驗傳入請求，然後建置
+`OcxParsedRequest`：
+
+- **訊息（Messages）** —— `input` 條目會變成規範化的 `OcxMessage[]`：user / developer /
+ assistant / toolResult。`reasoning` 條目變成 thinking block；`function_call`、
+ `custom_tool_call`、`tool_search_call` 條目變成工具呼叫；對應的 `*_output` 條目變成工具結果。
+- **工具（Tools）** —— function 工具直接透傳；**帶名稱空間的（MCP）工具會被扁平化**為
+ `namespace__name`，並在回傳時還原；**自由格式（freeform）**工具（如 `apply_patch`）和
+ **tool_search** 發現工具會被標記；**託管工具（hosted tools）**（`web_search`、圖像生成等）
+ 會被移除，只有 sidecar 確定會處理時才重新注入。
+- **圖像（Images）** —— 作為真實 content part（data URL 或遠端 https）保留，絕不會內聯成
+ 文字。
+- **功能標誌（Feature flags）** —— `_webSearch`（請求了託管網路搜尋）、
+ `_structuredOutput`（`text.format` 為 json_schema / json_object）和
+ `_compactionRequest`（remote compaction v2）。
+
+## 橋接器
+
+`bridge.ts` 把 adapter 的內部 `AdapterEvent` 流轉換回 Codex 能理解的 Responses SSE：
+
+| AdapterEvent | 發出的 Responses SSE |
+| --- | --- |
+| `text_delta` | `response.output_text.delta` → `…done`、`response.content_part.done`、`response.output_item.done` |
+| `thinking_delta` | `response.reasoning_summary_text.delta` → `…done`、item close |
+| `reasoning_raw_delta` | 原始 `reasoning_text` item（或隱藏的往返 envelope） |
+| `thinking_signature` / `redacted_thinking` | 儲存在 `encrypted_content` reasoning envelope 中 |
+| `tool_call_start` | `response.output_item.added`（type：`function_call` / `custom_tool_call` / `tool_search_call`） |
+| `tool_call_delta` | `response.function_call_arguments.delta`（freeform / tool_search 會跳過） |
+| `tool_call_end` | `response.function_call_arguments.done` → `response.output_item.done` |
+| `web_search_call_begin` / `web_search_call_end` | 一個即時 `web_search_call` item，加上 URL citation |
+| `heartbeat` | 標記上游仍在活動；不產生使用者可見的輸出 item |
+| `done` | `response.completed`（帶 usage） |
+| `error` | `response.failed`（帶 `last_error`） |
+
+橋接器還會執行**心跳保活**（RC3）：上游沒有資料時，每 2 秒傳送一次解析器會忽略的
+`response.heartbeat` SSE event，以重新啟動 Codex 的空閒計時器。預設**停滯截止時間**為 300 秒
+（`stallTimeoutSec`）；達到該時限後會中止上游，併發出 reason 為
+`upstream_stall_timeout` 的 `response.incomplete`，避免掛起的連線無限期阻塞 Codex。
+
+解析器捕獲的名稱空間對映、freeform 集合與 tool-search 集合會把工具呼叫區分為三種 Responses
+item，因此 MCP 名稱空間、`apply_patch` 風格的 freeform 工具和用戶端執行的 `tool_search` 都能
+完整往返。`buildResponseJSON()` 變體會用同一批 event 生成單個非流式回應物件。
+
+## 管理 API、OAuth 與用量
+
+`server/management-api.ts` 為儀表板提供後端，並把專門的 route 分派給
+`server/management/*.ts`。其 `/api/*` route 涵蓋安全的設定/設定、provider
+CRUD 與 key pool、模型選擇/context cap/v2 控制、catalog sync、診斷與 debug log、usage 與
+quota、sidecar 設定、更新、生成用戶端 API key、OAuth 登入/狀態/登出與帳號選擇、Codex 帳號
+管理，以及 graceful stop。proxy 繫結到 loopback 之外時，`server/auth-cors.ts` 會要求
+`/api/*` 和 `/v1/*` 都提供 `OPENCODEX_API_AUTH_TOKEN`；設定的 `corsAllowOrigins` 會擴充套件本機
+origin allowlist。
+
+OAuth 實作在 `oauth/` 中；每次路由呼叫前都會即時載入或重新整理 access token，而
+`oauth/token-guardian.ts` 只會主動重新整理策略允許的 provider。Codex/ChatGPT pool credential 與
+thread affinity 位於 `codex/` 下，不會出現在管理 API 回應中。請求用量會規範化為 `OcxUsage`，
+顯示在 Responses 終止 event 中，並由 `usage/` 彙總，供儀表板和可選的 JSONL 診斷使用。
+
+## 傳輸與 compaction
+
+`server/index.ts` 預設在 `/v1/responses` 上提供 HTTP/SSE。當 `websockets` 為 `false` 而 Codex
+嘗試 Responses WebSocket upgrade 時，opencodex 會回傳 `426 upgrade_required`，Codex 隨後在該
+session 中回退到 HTTP。設定 `"websockets": true` 後，同一 endpoint 會接受 upgrade 並使用
+WebSocket bridge。
+
+Codex context compaction 同樣適用於路由模型。`server/responses/compact.ts` 處理
+`POST /v1/responses/compact`，執行一次內部路由 summarization turn 並回傳壓縮後的歷史；
+`responses/parser.ts` 與 `bridge.ts` 則處理 remote compaction v2 的 `compaction_trigger` turn，
+準確發出一個合成的 `compaction` 輸出 item。
+
+## 快取與目錄
+
+- `codex/model-cache.ts` 為每個 provider 維護即時 `/models` 結果的記憶體 TTL 快取（預設 5 分鐘，
+ 與 Codex 自身快取一致），取得失敗時會回退到舊資料。
+- `codex/catalog.ts` facade 匯出的 `codex/catalog/sync.ts` 把路由模型作為帶名稱空間的條目
+ 合併進 Codex 目錄，優先排列精選的
+ [subagent 模型](/zh-tw/guides/codex-integration/#subagent-選擇器)，過濾
+ `disabledModels`，並可從一次性備份中完整恢復原始目錄。
+
+## Reasoning effort
+
+`reasoning-effort.ts` 把 Codex 的 reasoning 標籤轉換為各 provider 的 wire 值。Codex 目錄會
+公佈 Codex 接受的標籤（`low` / `medium` / `high` / `xhigh` / `max`），但上游 provider 可能只
+支援更小的子集，或要求真實 alias。該模組會：
+
+- 定義標準的 `CODEX_REASONING_LEVELS` 及其排序。
+- 精確級別不可用時，把請求的 effort 限制到最接近的支援層級。
+- 解析模型級和 provider 級 `reasoningEffortMap` override，用於自訂 wire 對映。
+- 對 `noReasoningModels` 中的模型完全移除 effort。
+
+## 核心型別
+
+內部模型位於 `types.ts`：`OcxParsedRequest`、`OcxContext`、`OcxMessage` 聯合型別、
+`OcxContentPart`（text / image）、`OcxToolCall`、`OcxTool`、`AdapterEvent`，以及設定型別
+（`OcxConfig`、`OcxProviderConfig`）。兩個常用 helper 是 `namespacedToolName()` 和
+`modelInList()`；後者會在匹配 `noVisionModels` / `noReasoningModels` 時容忍 `:size` 標籤。
diff --git a/docs-site/src/content/docs/zh-tw/reference/cli.md b/docs-site/src/content/docs/zh-tw/reference/cli.md
new file mode 100644
index 000000000..b7bc90b61
--- /dev/null
+++ b/docs-site/src/content/docs/zh-tw/reference/cli.md
@@ -0,0 +1,51 @@
+
+---
+title: CLI 參考
+description: 命令分派、離開碼，以及每個 ocx 命令家族的連結。
+---
+
+opencodex 的命令列工具是 `ocx`。它依第一個命令名稱分派，有記載的別名如
+`setup`/`init`、`restore`/`eject`、`models`/`model` 都會到達相同操作。
+未知命令與無效的命令形狀都是錯誤。
+
+執行 `ocx help`（或 `ocx --help` / `ocx -h`）檢視頂層用法。對幫助表中註冊的命令，
+執行 `ocx help `、`ocx --help` 或 `ocx -h`。幫助與版本
+命令均為只讀：它們不會啟動、停止、安裝、解除安裝或改寫 Codex／opencodex 狀態。
+
+## 命令家族
+
+- [生命週期](/zh-tw/reference/cli/lifecycle/) — 設定、代理與服務生命週期、健康狀態、
+ 診斷、目錄同步、儀表板與更新。
+- [Providers、帳號與模型](/zh-tw/reference/cli/providers-accounts/) — provider 設定、
+ 認證、憑證池、配額、自訂模型、可見性、選定模型與 context 上限。
+- [Agents、路由與整合](/zh-tw/reference/cli/agents/) — multi-agent 控制、combos、
+ 可觀測性、admission key、用戶端整合、執行環境設定與已驗證的設定。
+
+## 無頭（headless）行為
+
+管理命令往返於執行中代理的管理 API，使用記錄的執行環境埠與身分檢查，而非維護第二條
+設定路徑。停止或無法連線的代理以 HTTP 503 呈現，並產生非零的 CLI 離開碼。明確記載為
+離線設定操作的命令，可以在沒有執行中代理的情況下驗證與編輯設定檔。
+
+沒有歧義時，list 或 status 是預設。使用 `--json` 取得結構化快照，並以
+`ocx observe logs --follow --jsonl` 取得串流的請求 log feed。佈景主題、語言、導覽與
+其他純視覺的瀏覽器狀態沒有 CLI 對應；Cloudflare Tunnel 設定不在此命令集內。
+
+## 離開碼與確認
+
+成功的命令離開 0。無效用法、未知命令或資源、失敗的 API 操作以及無法使用的必要服務
+會以非零離開。`ocx health` 特別只在代理健康時離開 0，否則離開 1，因此可作為服務探針。
+腳本應測試離開碼，而不是解析人類可讀的輸出。
+
+宣告需要確認的破壞性移除、匯入、信用消耗與更新操作，在非互動使用時需要 `--yes`。
+該旗標是明確的 opt-in；省略它不得靜默確認該動作。
+
+## 版本與內部分派目標
+
+`ocx --version`、`ocx -v` 與 `ocx version` 會列印一行適合腳本使用的版本行並結束。
+
+有兩個分派目標刻意不顯示在一般幫助中：`__refresh-version [preview]` 在分離的
+程序中重新整理更新通知快取，`__gui-update-worker [latest|preview] [restart]`
+執行儀表板更新任務。它們是實作細節，不是穩定的使用者面向命令。儀表板會記錄 worker
+PID、恢復 worker 已死但仍在進行中的任務、把超過十分鐘且沒有 PID 的舊 active 記錄
+視為過期，並保護執行中的 worker 免受並行更新影響。
diff --git a/docs-site/src/content/docs/zh-tw/reference/cli/agents.md b/docs-site/src/content/docs/zh-tw/reference/cli/agents.md
new file mode 100644
index 000000000..84357e03c
--- /dev/null
+++ b/docs-site/src/content/docs/zh-tw/reference/cli/agents.md
@@ -0,0 +1,182 @@
+---
+title: CLI 代理、路由與整合
+description: 多代理、組合、可觀測性、存取、整合、系統與設定指令。
+---
+
+這些指令控制代理政策與路由、檢查即時代理，並將支援的客戶端連接至 opencodex。
+
+## 代理政策
+
+### `ocx agent ...`
+
+管理無頭多代理名冊、effort 上限、prompt 注入、fallback 與 sidecar 設定。使用 `status` 查看目前政策。關於介面模式、委派、effort 與 fallback 行為如何搭配運作，請見[子代理介面](/zh-tw/guides/sub-agent-surface/)。
+
+```bash
+ocx agent subagents set ark/model-a,openai/gpt-5.5
+```
+
+### `ocx v2 |threads >`
+
+管理 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 ` | 將現用 v1/v2 執行緒上限設為不小於 1 的整數。 |
+
+```bash
+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 ...` · `ocx route combo ...`
+
+管理組合 failover 與 round-robin 虛擬模型。`ocx route combo` 是階層式別名；組合是目前支援的路由資源。目標使用
+`provider/model[:weight],provider/model[:weight]`。
+
+```bash
+ocx combo list
+ocx route combo set reliable --targets ark/model-a:2,openai/gpt-5.5
+```
+
+關於路由行為與設定指引，請見[組合](/zh-tw/guides/combos/)。
+
+## 可觀測性與除錯
+
+### `ocx observe ...`
+
+檢查代理請求、用量、儲存、記憶體與除錯資料。直接別名如下：
+
+| 別名 | 等效資源 |
+| --- | --- |
+| `ocx logs [filters] [--follow] [--json|--jsonl]` | `ocx observe logs` |
+| `ocx usage [--range <7d|30d|all>] [--surface ] [--json]` | `ocx observe usage` |
+| `ocx storage [--json]` | `ocx observe storage` |
+| `ocx memory [--json]` | `ocx observe memory` |
+
+```bash
+ocx observe usage --range 30d --json
+```
+
+### `ocx debug `
+
+透過執行中代理的管理 API 讀取或變更執行階段除錯覆寫。
+
+```bash
+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 ...`
+
+管理 OpenCodex 許可 API 金鑰並檢查外部端點與模型。`ocx api-key
+ ...` 是 `ocx access key` 的別名。
+
+```bash
+ocx access key create deployment
+```
+
+## 客戶端整合
+
+### `ocx integration ...`
+
+管理支援的 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 ` 選擇。使用者匯出的 `ANTHROPIC_*` 變數恆優先。
+
+Claude Desktop 設定檔指令如下：
+
+```text
+ocx claude desktop [apply] 儲存並套用四家族設定檔
+ocx claude desktop show [--json] 顯示路由、家族與預設值
+ocx claude desktop move [--default]
+ocx claude desktop default
+ocx claude desktop export 匯出版本化 JSON（`-` = stdout）
+ocx claude desktop import [--apply] 驗證並匯入 JSON
+```
+
+家族為 `opus`、`fable`、`sonnet` 與 `haiku`；新路由從 `opus` 開始。`none` 僅在該家族為空時有效。舊版套用旗標 `--static`、`--hybrid` 與 `--discovery-only` 仍受支援。請用 `ocx claude config ...` 管理 Claude Code 設定。
+
+### `ocx opencode [opencode args...]`
+
+確保代理正在執行，然後在 OpenCode 的內嵌執行階段層（`OPENCODE_CONFIG_CONTENT`）中以生成的 `provider.opencodex` 區塊啟動 opencode。既有的內嵌設定會被保留，本次啟動僅替換 `provider.opencodex`。全域或專案的 `opencode.json` 檔案可能被讀取以警告既有的覆寫，但磁碟上的檔案永不修改。路由模型以
+`opencodex//` 出現。之後啟動普通 `opencode` 的行為與之前完全相同。
+
+### `ocx grok ...`
+
+管理並套用 Grok Build 模型圍欄。
+
+## 客戶端設定匯出
+
+### `ocx export --client `
+
+印出連接到執行中代理的客戶端設定。opencode 與 [Pi](/zh-tw/guides/pi/) 從其自身的 JSON 設定而非環境變數讀取供應商，因此此指令將 `opencodex` 供應商區塊——base URL、模型清單與客戶端的環境變數參考——序列化，供你合併到該檔案中。
+
+代理必須正在執行；指令解析其即時連接埠、讀取 `/api/models`，並只輸出 Codex 目前可見的模型。
+
+| 旗標 | 動作 |
+| --- | --- |
+| `--client ` | 必填。選擇客戶端方言：opencode 的 keyed `provider` 物件或 Pi 的 `providers` 陣列。 |
+| `--json` | 僅在 stdout 印出設定 JSON，使重導向能擷取逐位元組輸出。所有診斷訊息（含 `--out` 寫入提示）皆送至 stderr。 |
+| `--out ` | 將設定寫入 ``。拒絕覆寫既有檔案。 |
+| `--force` | 允許 `--out` 覆寫既有檔案。 |
+
+```bash
+ocx export --client opencode # 設定加上目的地、合併警告與計數
+ocx export --client pi --json > pi-models.json # 供 pipe 或 diff 用的逐位元組 JSON
+ocx export --client opencode --out ~/opencodex-opencode.json
+```
+
+未指定 `--json` 時，JSON 在前，接著是標準目的地路徑、合併警告、環境匯出行，以及附帶有多少列省略 context limit 的模型計數（客戶端會對那些套用自身預設值）。
+
+| 客戶端 | 標準目的地 | 下載檔名 | 環境變數 |
+| --- | --- | --- | --- |
+| `opencode` | `~/.config/opencode/opencode.json`（`XDG_CONFIG_HOME` 設定時優先） | `opencode.json` | `OPENCODEX_OPENCODE_API_KEY` |
+| `pi` | `~/.pi/agent/models.json` | `pi-models.json` | `OPENCODEX_API_KEY` |
+
+兩個環境變數名稱不同，且每個客戶端只插值自己的。opencode 讀取
+`{env:OPENCODEX_OPENCODE_API_KEY}`；Pi 讀取 `$OPENCODEX_API_KEY`。
+
+:::caution[合併，而非取代]
+`ocx export` 永不寫入你的真實客戶端設定。目的地僅印出供你手動合併，而 `--out` 在沒有 `--force` 時拒絕覆寫既有檔案，因為取代設定檔會毀掉其中已有的其他供應商、代理與 MCP 項目。
+:::
+
+金鑰永不被序列化。設定只帶有客戶端的環境變數參考，因此秘密留在你的環境中。回送代理（`127.0.0.1`，預設值）完全不需要許可金鑰——該參考只是未被使用。僅在代理綁定超出回送時才設定該變數；關於許可金鑰的簽發方式，請見[遠端存取](/zh-tw/reference/configuration/#remote-access)。上游供應商本身的金鑰是完全不同的事，依[供應商](/zh-tw/guides/providers/)個別設定。
+
+相同的 payload 亦由 `GET /api/client-config` 提供，並在儀表板的 API 分頁渲染，因此 CLI、API 與 GUI 使用相同的位元組。
+
+## 執行階段與設定
+
+### `ocx system ...`
+
+管理無頭執行階段設定、啟動、同步、診斷與更新。
+
+```bash
+ocx system settings --stream-mode eager-relay
+```
+
+### `ocx config ...`
+
+檢查並安全地修改已驗證的 OpenCodex 設定。`show` 與 `get` 會遮罩秘密。匯入在寫入前驗證且需要 `--yes`。
diff --git a/docs-site/src/content/docs/zh-tw/reference/cli/lifecycle.md b/docs-site/src/content/docs/zh-tw/reference/cli/lifecycle.md
new file mode 100644
index 000000000..02983cff7
--- /dev/null
+++ b/docs-site/src/content/docs/zh-tw/reference/cli/lifecycle.md
@@ -0,0 +1,231 @@
+---
+title: CLI 生命週期
+description: 安裝、啟動、停止、服務、診斷、同步與更新指令。
+---
+
+這些指令安裝、執行、檢查、修復並更新本機 opencodex 代理及其 Codex 整合。
+
+## 安裝
+
+### `ocx init` · `ocx setup`
+
+互動式設定精靈（`setup` 是 `init` 的別名）。提示選擇供應商（預設或自訂）、API 金鑰（字面值或 `${ENV}`）、預設模型與代理連接埠；儲存 `~/.opencodex/config.json`；可選擇將代理注入 `$CODEX_HOME/config.toml`（預設 `~/.codex/config.toml`）；並可選擇安裝 Codex 自動啟動 shim。
+
+## 代理生命週期
+
+### `ocx start [--port ]`
+
+啟動代理伺服器（偏好連接埠 `10100`）。若該連接埠被佔用，opencodex 會選擇並記錄另一個可用連接埠。它寫入 PID/runtime-port 狀態，並拒絕啟動第二個即時實例。啟動時它將每個供應商的模型同步到 Codex 目錄。關閉時它還原原生 Codex——除非它是作為受管服務啟動的（`OCX_SERVICE=1`）。
+
+```bash
+ocx start
+ocx start --port 8080
+```
+
+### `ocx stop`
+
+停止執行中的代理（依 PID）、移除 PID 檔案，並還原原生 Codex。若已安裝受管背景服務，`ocx stop` 也會先停止它，使其無法重新生成代理。相同動作亦可從網頁儀表板的 **Stop** 按鈕執行（`POST /api/stop`）。
+
+### `ocx restart`
+
+執行 `stop` 後接 `ensure`：停止代理／服務、還原原生 Codex、在背景啟動代理，並將即時連接埠同步回 Codex。
+
+### `ocx ensure`
+
+冪等地確保背景代理正在執行，然後同步其即時模型目錄。若
+`codexAutoStart` 為 `false`，它會印出自動啟動已停用並不做事。
+
+### `ocx restore [back]` · `ocx eject [back]`
+
+在不停止代理的情況下還原原生 Codex——剝除注入的設定行與路由目錄項目，使普通 `codex` 再次以原生方式運作。`eject` 是 `restore` 的別名。
+
+對任一拼法傳入 `back` 可在不變更代理生命週期的情況下，將普通 `codex` 重新指向已在執行的代理：
+
+```bash
+ocx restore back
+ocx eject back
+```
+
+### `ocx recover-history --legacy-openai`
+
+針對在可逆備份支援存在前、重新對應 Codex App 歷史的舊開發組建進行明確復原。若其歷史資料庫被鎖定，請先關閉 Codex。
+
+### `ocx uninstall` · `ocx remove`
+
+停止服務與代理、移除服務與 Codex shim、還原原生 Codex，然後僅在所有還原步驟成功時移除 opencodex 本機設定。`remove` 是 `uninstall` 的別名。設定清理需要由全新安裝建立的擁有權中繼資料；舊版或共享目錄會被原樣保留。
+
+## 狀態與健康
+
+### `ocx status [--json]`
+
+印出唯讀診斷摘要：代理 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` 契約目前不包含此健康區塊。
+
+```bash
+ocx status
+ocx status --json
+```
+
+縮寫範例結構：
+
+```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、授權標頭、請求內容、電子郵件與帳號身分。
+
+### `ocx health [--json]`
+
+對即時代理進行身分檢查。人類可讀輸出回報 PID/連接埠；`--json` 輸出 `{ok, pid, port}`。此指令僅在健康時離開 0，否則離開 1，使其適合服務探測。
+
+### `ocx ready [--json] [--wait [--timeout ]]`
+
+透過免認證的 `GET /readyz` 端點檢查同步後的就緒狀態。就緒時回傳 `200`，或 `pending` 與終端 `failed` 時回傳附帶 `Retry-After: 1` 的 `503`。其淨化的 HTTP 身分為 `{service, version, uptime, pid, port, status}`。沒有 `/readyz` 的舊代理會以 `unreachable` 方式 fail closed；`/healthz` 是分開的存活檢查，而非就緒檢查。此指令預設執行一次探測；`--wait` 輪詢直到就緒或逾時，但在觀察到終端 `failed` 狀態時立即退出。預設逾時為 45 秒；`--timeout ` 需要 `--wait`，接受 1–300 的正整數秒。CLI JSON 輸出 `{ready, status, pid, port}`，其中 `status` 為 `ready`、`pending`、`failed` 或 `unreachable`。離開碼為：就緒 0；未就緒、pending、failed、逾時或 unreachable 1；無效引數 64。
+
+### `ocx doctor`
+
+執行唯讀環境與連線診斷：狀態路徑與檔案系統類型、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 永不變更憑證或套用修復。
+
+## 目錄同步
+
+### `ocx sync [--restart-codex]`
+
+從每個已設定的供應商擷取即時模型清單，並將合併後的目錄重新注入 Codex。在新增供應商後或要重新整理可用模型時執行它。
+
+若長壽的 Codex `app-server` 仍在執行，`ocx sync` 會警告它們可能繼續提供先前的記憶體內模型清單，即使 `opencodex-catalog.json` / `models_cache.json` 已更新。傳入 `--restart-codex` 以僅對目前使用者擁有的相符 `codex … app-server` 與 `codex-code-mode-host` 進程發送 `SIGTERM`（執行中的回合可能被中斷）。刻意避免廣泛的 `pkill -f codex` 比對。
+
+### `ocx sync-cache [--restart-codex]`
+
+使 Codex 的本機模型選擇器快取失效，使其從現用的 opencodex 目錄重建。與 `ocx sync` 相同的過時 `app-server` 警告與可選的 `--restart-codex` 行為適用。
+
+## 背景服務
+
+### `ocx service [install|repair|start|stop|status|uninstall|remove]`
+
+將 opencodex 作為登入管理的背景服務執行（macOS **launchd**、Linux **systemd user unit**、Windows **Task Scheduler**），在登入時自動啟動並在崩潰時自動重啟。服務執行時設定 `OCX_SERVICE=1`，使重啟不會折騰 Codex 設定。
+
+| 子指令 | 動作 |
+| --- | --- |
+| 無 | 建立／更新並啟動服務。 |
+| `install` | 建立並啟動服務。註冊它，在 Windows 上需要提高權限。 |
+| `repair` | 就地重新整理已安裝的服務並重啟它，而不重新註冊。 |
+| `start` | 啟動已安裝的服務。 |
+| `stop` | 停止服務並還原原生 Codex。 |
+| `status` | 回報服務與代理診斷及日誌路徑。 |
+| `uninstall` | 移除服務並還原原生 Codex。 |
+| `remove` | `uninstall` 的別名。 |
+
+```bash
+ocx service
+ocx service install
+ocx service repair
+ocx service status
+ocx service uninstall
+```
+
+`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 /f`、狀態 1，以及確認的非提高 token；儀表板的 Startup Safety 動作隨後可自動請求 UAC。若該後備無法判斷 token 狀態，則保留原始排程器錯誤。外部工作與操作永不發出自動提高標記。請核准儀表板 UAC 提示，或在提高的 PowerShell 視窗中重新執行 `ocx service install`。
+
+### `ocx codex-shim `
+
+在 PATH 上以輕量自動啟動腳本包裝基於腳本的 `codex` 啟動器。真實的 `codex.exe` 目標保持不動，以避免破壞精確的可執行檔呼叫。
+
+若已完成的外部 Codex 更新覆寫了已安裝的 shim，下一個普通 `ocx` 指令會備份穩定的新啟動器並在分派前還原 shim。仍在變動中的啟動器保持不動並稍後重試。修復失敗會發出警告但不會使請求的指令失敗；手動後備：`ocx codex-shim install`。將 `codexShimAutoRestore` 設為 `false`，或設定 `OPENCODEX_CODEX_SHIM_AUTO_RESTORE=0` 以進行行程層級的退出。
+
+| 子指令 | 動作 |
+| --- | --- |
+| `install` | 安裝 shim（若過時則修復）。 |
+| `uninstall` | 移除 shim 並還原原始 Codex 二進位檔。 |
+| `remove` | `uninstall` 的別名。 |
+| `status` | 回報 shim 狀態（已安裝、過時或缺失）。 |
+
+```bash
+ocx codex-shim install
+ocx codex-shim status
+ocx codex-shim uninstall
+```
+
+:::tip[服務 vs Shim]
+使用 `ocx service` 作為常駐背景代理（推薦）。使用 `ocx codex-shim` 作為輕量、按需啟動而無 daemon——代理僅在 `codex` 啟動時才啟動。
+:::
+
+### `ocx tray [--json] [--no-start]`
+
+安裝並控制 Windows 狀態列圖示。它在 Windows 登入時啟動並提供一鍵代理控制。`start` 與 `stop` 僅控制圖示；請用其選單控制代理。`--no-start` 適用於 `install`，並在不立即啟動它的情況下安裝 tray。
+
+## 儀表板
+
+### `ocx gui`
+
+在 `http://localhost:` 開啟[網頁儀表板](/zh-tw/guides/web-dashboard/)，若代理未執行則自動啟動它。
+
+## 更新
+
+### `ocx update [--tag latest|preview]`
+
+從 npm 自我更新 opencodex。穩定安裝使用 `@latest`；預覽安裝停留在 `@preview`，除非你傳入 `--tag latest|preview`。它偵測原始碼 checkout 並告訴你改用
+`git pull && bun install`，且若你已是該 tag 的最新版本則為 no-op。執行中的代理會在檔案被替換前停止；已安裝的服務會自動重建並啟動，而前景安裝會印出 `ocx start` 作為下一步。
+
+```bash
+ocx update
+ocx update --tag preview
+```
+
+當 [Release workflow](https://github.com/lidge-jun/opencodex/actions/workflows/release.yml) 將新版本發布到 npm 時，新版本即可使用。
diff --git a/docs-site/src/content/docs/zh-tw/reference/cli/providers-accounts.md b/docs-site/src/content/docs/zh-tw/reference/cli/providers-accounts.md
new file mode 100644
index 000000000..ec2063b31
--- /dev/null
+++ b/docs-site/src/content/docs/zh-tw/reference/cli/providers-accounts.md
@@ -0,0 +1,274 @@
+---
+title: CLI 供應商、帳號與模型
+description: 供應商設定、憑證、配額與模型目錄指令。
+---
+
+這些指令設定上游供應商、認證帳號、管理憑證池，並控制暴露給 Codex 的模型目錄。
+
+## 供應商
+
+### `ocx provider `
+
+非互動式供應商管理。Registry 項目依名稱播種；自訂名稱需要同時提供 `--adapter` 與 `--base-url`。
+
+| 子指令 | 支援的旗標 | 動作 |
+| --- | --- | --- |
+| `list` | `--json` | 列出已設定的供應商與剩餘的 registry 項目。 |
+| `add ` | `--adapter `, `--base-url `, `--api-key `, `--default-model `, `--set-default`, `--force`, `--json`, `--sync` | 新增 registry／自訂供應商。`--force` 覆寫；`--sync` 在人類輸出模式下重新整理執行中的代理。 |
+| `edit ` | 供應商欄位旗標, `--json` | 編輯已驗證的即時供應商欄位而不替換金鑰池。 |
+| `test ` | `--json` | 探測真實上游模型端點。 |
+| `show ` | `--json` | 顯示設定，API 金鑰已遮罩。 |
+| `remove ` | `--json` | 移除非預設供應商；最後一個供應商無法被移除。 |
+| `set-default ` | `--json` | 選擇既有供應商作為預設。 |
+| `selected ` | `--set `, `--clear`, `--json` | 讀取或更新供應商模型允許清單。 |
+| `quota` | `--refresh`, `--json` | 讀取供應商配額報告。 |
+| `presets` | `--json` | 列出儀表板供應商預設。 |
+| `account-mode` | `pool`, `direct`, `--json` | 選擇池化或直接的 Codex 帳號路由。 |
+
+```bash
+ocx provider list --json
+ocx provider test ark
+ocx provider add anthropic --api-key sk-ant-... --set-default --sync
+ocx provider add local-dev --adapter openai-chat --base-url http://localhost:11434/v1
+ocx provider show anthropic --json
+ocx models --provider anthropic --json
+ocx models live --provider ark --json
+```
+
+## 認證
+
+### `ocx login `
+
+啟動供應商已註冊的登入流程。OAuth 供應商會開啟瀏覽器並在 `~/.opencodex/` 下儲存自動重新整理的憑證；API-key 登入供應商會開啟其金鑰儀表板、提示輸入金鑰、在可能時驗證它，並儲存產生的供應商設定。當名稱缺失或未知時，指令會印出目前接受的 OAuth 與 API-key 供應商 id。
+
+在 `ocx status` / `ocx doctor` 回報需要重新認證或終端 refresh 失敗後，請使用相同指令**重新認證**（或在儀表板中使用 Reauthenticate）。Codex pool 帳號不是公開的 `ocx login` 供應商——請改由儀表板 Codex 帳號池（Reauthenticate）或無頭的 `ocx account reauth` 流程重新認證。
+
+```bash
+ocx login xai
+ocx login anthropic
+```
+
+### `ocx logout `
+
+移除供應商已儲存的 OAuth 憑證。
+
+## 帳號與金鑰池
+
+### `ocx account `
+
+透過執行中的代理列出並切換供應商帳號與 API-key 池。隨附的說明介面如下：
+
+```text
+Usage: ocx account ...
+
+list [provider] Codex 帳號池、OAuth 帳號與 API 金鑰（識別碼依 API 回傳遮罩顯示）。
+current 顯示現用帳號或金鑰。
+use 切換現用憑證；'main' 選擇 Codex App 登入。
+refresh 強制重新整理 Codex 或供應商配額報告。
+auto-switch 控制 Codex 池閾值。
+remove --yes 在存在檢查後移除已儲存的帳號或金鑰。
+add-key [--label