- {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..7788c7a3d
--- /dev/null
+++ b/docs-site/src/content/docs/zh-tw/contributing.md
@@ -0,0 +1,124 @@
+---
+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
+```
+
+## 約定
+
+- **僅使用 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。
+
+## 新增 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/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..2d2a97384
--- /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..f04b0c688
--- /dev/null
+++ b/docs-site/src/content/docs/zh-tw/getting-started/installation.md
@@ -0,0 +1,96 @@
+---
+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..14ccc76ef
--- /dev/null
+++ b/docs-site/src/content/docs/zh-tw/getting-started/quickstart.md
@@ -0,0 +1,114 @@
+---
+title: 快速入門
+description: 設定你的第一個 provider,用三條命令讓 OpenAI Codex 透過 opencodex 進行路由。
+---
+
+本指南將帶你從全新安裝,一路走到用一個非 OpenAI 模型執行 Codex。
+
+## 1. 執行設定嚮導
+
+```bash
+ocx init
+```
+
+`ocx init` 會引導你完成:
+
+1. **選擇 provider** —— 從內建 registry 的 50 個預設中選擇一個，或選擇 `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 灰度釋出條目]
+穩定版 v2.7.1 會為 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"
+```
+
+如果你擁有 GPT-5.6 許可權，原生 ChatGPT 路徑使用裸模型名，API key 和 OpenRouter 路徑使用顯式
+`provider/model` 形式：
+
+```bash
+codex -m "gpt-5.6-sol" "Plan a risky refactor"
+codex -m "openai-apikey/gpt-5.6-terra" "Review this architecture"
+codex -m "openrouter/openai/gpt-5.6-luna" "Summarize this trace"
+```
+
+## 選擇 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；
+opencodex 會把這項指引加入 v1 協作請求。
+
+## 登入而非貼上 key
+
+部分 provider 支援真正的帳號登入(OAuth,自動重新整理):
+
+```bash
+ocx login xai # 也可使用 anthropic、kimi、kiro、google-antigravity、cursor
+ocx logout xai
+```
+
+預設 OpenAI 路徑**無需 key** —— 它會直接轉發你現有的 `codex login` 憑證。若要使用 OpenAI
+API key，請新增 `openai-apikey` provider。該預設包含 `gpt-5.6-sol`、`gpt-5.6-terra`、
+`gpt-5.6-luna`，但你的 API key 必須擁有實際使用許可權
+(參見 [Provider](/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..5b30cb50e
--- /dev/null
+++ b/docs-site/src/content/docs/zh-tw/guides/claude-code.md
@@ -0,0 +1,420 @@
+---
+title: Claude Code 指南
+description: 在 Claude Code 中使用任意已路由模型——opencodex 在同一埠提供 Anthropic Messages API 和閘道器模型發現功能。
+---
+
+opencodex 在 `/v1/responses` 之外還提供 `POST /v1/messages`（以及 `count_tokens`），因此 Claude
+Code 可以使用每一個已路由的供應商——包括 OAuth 登入、帳號池、金鑰故障轉移和 sidecar——
+而無需進行任何額外的身分驗證設定。
+
+## 快速入門
+
+```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` 仍可供既有腳本使用。
+
+## 系統環境整合（macOS）
+
+當 `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** 列中。
+
+## 入站轉換（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`，指定名稱→`{type:"function",name}` |
+| `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..10dbc7a43
--- /dev/null
+++ b/docs-site/src/content/docs/zh-tw/guides/codex-app-models.md
@@ -0,0 +1,160 @@
+---
+title: Codex App 模型選擇器
+description: opencodex 模型如何透過共享 Codex 目錄出現在 Codex App、Codex CLI 和 Codex TUI 中。
+---
+
+opencodex 不會修改 Codex App。它會寫入 Codex CLI/TUI 已經使用的同一套 Codex 設定和模型目錄。
+Codex App 也會讀取這份共享狀態，因此路由模型可以像普通 Codex 目錄條目一樣出現在 App 的模型
+選擇器中。
+
+OpenAI 身份固定為兩種：bare native id 是由 `codexAccountMode` 控制 Pool（預設）或 Direct 的
+單一 `openai` 組，`openai-apikey/` 是 API key。切換模式不會改變模型 id。API GPT-5.6 使用 1,050,000
+context / 922,000 max input；`*-pro` picker id 保持公開身份，線上使用 base 模型加
+`reasoning.mode: "pro"`。
+
+## 整合路徑
+
+`ocx init`、`ocx start` 和 `ocx sync` 會保持解析後的 `CODEX_HOME` 目錄下這些檔案一致：
+
+```text
+$CODEX_HOME/config.toml
+$CODEX_HOME/opencodex.config.toml
+$CODEX_HOME/opencodex-catalog.json
+$CODEX_HOME/models_cache.json
+```
+
+使用預設的 loopback 監聽地址時，Codex 會保留內建的 `openai` provider id。opencodex 透過以下
+根級鍵把該 provider 和模型目錄指向代理：
+
+```toml
+model_catalog_json = "/absolute/path/to/opencodex-catalog.json"
+openai_base_url = "http://127.0.0.1:10100/v1"
+```
+
+如果 hostname 不是 loopback，Codex 還需要傳送生成的 API 認證 header。此模式會使用根級
+`model_provider = "opencodex"` 和一個獨立的 Responses 相容 provider：
+
+```toml
+[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" }
+```
+
+`websockets` 預設關閉。只有設定 `"websockets": true` 時，獨立 provider 和目錄條目才會宣告
+`supports_websockets = true`。在 loopback 模式下，Codex 的內建 provider 可能會先嚐試
+WebSocket；若代理未啟用該功能，則返回 `426`，讓 Codex 回退到 HTTP/SSE。完整的注入與恢復流程見
+[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 後設資料。
+
+## v2.7.1 模型範圍
+
+原生回退列表包含 `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 登入（Pool 或 Direct） | `gpt-5.6-sol`、`gpt-5.6-terra`、`gpt-5.6-luna`（372,000 token） |
+| OpenAI（API key） | `openai-apikey/gpt-5.6-*` 和 `openai-apikey/gpt-5.6-*-pro`（1,050,000；max input 922,000） |
+| 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，並提供 `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 頁面透過同一個 `disabledModels` 管理兩類模型：
+
+- 路由 id 使用 `provider/model` 名稱空間。停用後，該模型會從同步目錄和 `/v1/models` 中移除。
+- 原生 GPT id 是不含 `/` 的 slug。停用時不會刪除目錄條目，而是將 `visibility` 改為 `hide`，
+ 以便重新啟用時精確恢復原條目；停用期間，OpenAI 列表格式也會省略它。
+- 原生模型行來自受支援的靜態集合，因此即使模型已停用，仍會留在儀表板中供你重新啟用。
+
+可見性處理位於快照升級之後。每次切換模型後，管理 API 都會重新整理目錄，並強制把 Codex 模型快取
+標記為過期。
+
+## Multi-agent surface 模式
+
+opencodex 為每個目錄條目的 `multi_agent_version` 提供三態 override：
+
+| 模式 | 效果 |
+| --- | --- |
+| **v1** | 強制所有模型使用 v1 multi-agent surface，並覆蓋上游固定值（包括 Sol/Terra）。 |
+| **base**（安裝預設值） | 恢復上游固定值：Sol/Terra 使用 v2，Luna 使用 v1；未固定的模型遵循 Codex 的 `multi_agent_v2` 功能開關。 |
+| **v2** | 強制所有模型使用 v2 multi-agent surface，並覆蓋上游固定值（包括 Luna）。 |
+
+可從 Dashboard 或 Models 頁面、`ocx v2 mode v1|default|v2`，或透過帶
+`{ "multiAgentMode": "v1" }` 的 `PUT /api/v2` 設定該模式。變更從新的 Codex session 開始生效。
+
+:::caution
+在 v2（`multi_agent_v2`）介面中，生成的子代理會繼承父 session 的模型。儀表板中的委派模型/
+reasoning 選擇器只是 v1 prompt 指引，並不是由代理在每次生成時執行跨模型路由。權威說明見
+[子代理介面](/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；路由到非 OpenAI provider 的模型會移除 service-tier 後設資料，避免顯示
+無法兌現的 fast 選項。
+
+## 子代理選擇
+
+Codex 會按 `priority` 升序排列選擇器中可見的目錄條目，並將前五個顯示為 `spawn_agent` 模型
+override。你可以透過 `subagentModels` 或儀表板的 Subagents 頁面選擇最多五個原生 id 或
+`provider/model` id；opencodex 會按所選順序賦予它們 0-4 的 priority。其他模型仍可透過精確 id
+直接呼叫。
+
+置頂模型列表與 Dashboard 的 **Sub-agent delegation** 指引相互獨立。尤其需要注意，置頂模型
+override 不能繞過 v2 的父模型繼承規則。
+
+## 重新整理模型狀態
+
+如果選擇器仍顯示舊條目，請重新整理目錄並重新開啟目標 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..98d5a23a0
--- /dev/null
+++ b/docs-site/src/content/docs/zh-tw/guides/codex-integration.md
@@ -0,0 +1,243 @@
+---
+title: Codex 整合
+description: opencodex 如何將自身注入 Codex、同步模型目錄、驅動 subagent 選擇器，並乾淨地恢復。
+---
+
+opencodex 透過編輯 Codex 讀取的兩樣東西，讓 Codex 經由 proxy 路由：它的設定（`$CODEX_HOME/config.toml`，預設 `~/.codex/config.toml`）和它的模型目錄。每一次編輯都是冪等且可逆的。
+
+OpenAI 提供一條 bare `openai` Codex 登入路徑和 `openai-apikey/` API 路徑。
+`openai` 可選 Pool（預設，主帳號加新增帳號）或 Direct（目前 caller/主登入 bearer），模型 id
+保持不變。路徑之間不會 fallback。shipped v1 設定遷移到 marker 2，並保留
+`config.json.pre-openai-tiers-v2.bak` 供手動恢復。
+
+## 設定注入
+
+`ocx init`、`ocx start` 和 `ocx sync` 都會呼叫注入器。在預設的 loopback 繫結下，它會保留 Codex
+內建的 `openai` 供應商 id，並將該供應商指向 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"
+
+[features]
+fast_mode = true
+```
+
+proxy 的預設埠為 `10100`，提供 `POST /v1/responses`、`POST /v1/responses/compact`、
+`POST /v1/images/generations`、`POST /v1/images/edits`、`GET /v1/models`、`GET /healthz`
+以及 `/api/*` 管理 API。
+
+### 內建圖像生成（`image_gen`）
+
+Codex 的內建 `image_gen` 工具不經過 `/v1/responses`——codex-rs 擴充套件直接 POST
+`{base_url}/images/generations`（附帶參考圖像時為 `/images/edits`），使用與聊天相同的
+ChatGPT bearer 認證。由於注入的 `base_url` 指向 opencodex，proxy 會把這些呼叫中繼到
+OpenAI 上游：
+
+- **單一、感知模式的 forward 候選：** Pool 選擇合格的主帳號或新增帳號；Direct 使用 caller
+ OAuth bearer。圖像請求遵循同一模式。
+- **OpenAI API key：** 僅當 forward 候選沒有擁有認證失敗時使用。不會用單獨計費的 API 呼叫掩蓋
+ 損壞或過期的 Pool 憑證。
+- **兩者都沒有：** proxy 返回明確的錯誤而不是含糊的 404。其他路由供應商（Cursor、Gemini、
+ Kiro 等）無法提供圖像生成；如果想完全關閉該工具，可在 Codex 中執行
+ `codex features disable image_generation`（即 `config.toml` 的
+ `[features] image_generation = false`）。
+
+如果 `hostname` 不是 loopback 地址，Codex 必須傳送自動生成的 API 認證請求頭。此時注入器會改用
+專用供應商：
+
+```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` 寫成參考/回退設定。
+loopback 模式下，其中包含自動注入被移除時可手動合併的根級鍵；non-loopback 模式下，其中包含
+專用供應商設定。外部供應商模式不會修改此設定檔。
+
+:::caution
+`openai_base_url`、`model_provider`、`model_catalog_json` 等根級鍵**必須**位於第一個 `[table]`
+頭之前。注入器會保證這一位置，並清理自己留下的舊值和重複項。使用者自己設定的根級
+`openai_base_url` 不會被覆蓋；如果檢測到該值，同步仍會更新模型目錄，但會明確提示路由沒有注入。
+:::
+
+## 共享模型目錄
+
+Codex CLI、TUI、App 和 SDK 都讀取同一個 Codex home。opencodex 會從 `CODEX_HOME` 解析該目錄，
+未設定時回退到 `~/.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`。
+
+在 Windows 上，Orca shell 可能同時把 `CODEX_HOME` 和 `ORCA_CODEX_HOME` 指向 Orca 的內建
+runtime home，而 ChatGPT/Codex App 仍讀取 `%USERPROFILE%\\.codex`。`ocx status` 與
+`ocx doctor` 會檢測這一明確的不一致，並以隱藏使用者名稱的形式顯示目標 home。如果後臺服務是在原 Orca
+shell 中安裝的，請先在原 shell 中解除安裝服務，再把 `CODEX_HOME` 設為 App home、取消
+`ORCA_CODEX_HOME`，重新同步/恢復並安裝服務。
+
+在專用供應商模式下，`requires_openai_auth = true` 會讓 Codex App/TUI 的帳號門控介面與原生
+Codex 保持一致。opencodex 也提供 `/v1/responses` WebSocket。專用供應商僅在
+`"websockets": true` 時宣告 `supports_websockets = true`；loopback 模式下，Codex 的內建供應商
+可能會先嚐試 WebSocket，如果功能未啟用，proxy 會返回 `426`，使 Codex 回退到 HTTP/SSE。
+
+## 執行緒標識與歷史記錄
+
+預設 loopback 方式會讓新執行緒繼續使用 Codex 原生的 `openai` 供應商標識，因此普通的恢復歷史無需
+重對映。第一次同步時，它還會把舊版 opencodex 改過標識的執行緒遷回 `openai`。non-loopback 的專用
+供應商模式會在運行時間把歷史記錄對映到 `opencodex`，退出時再恢復已備份的後設資料。若希望完全不修改
+歷史記錄，請設定 `syncResumeHistory: false`。
+
+## 模型目錄同步
+
+Codex 顯示的模型來自一個磁碟上的目錄（預設為 `$CODEX_HOME/opencodex-catalog.json`）。在啟動時以及執行 `ocx sync` 時，opencodex 會：
+
+1. **備份**一次原始目錄到 `~/.opencodex/catalog-backup.json`（以便置頂操作可逆）。
+2. **獲取**符合條件的供應商即時模型目錄（快取約 5 分鐘；失敗時先回退到上一份正常列表，再回退到
+ 已設定的 `models[]`）。`forward` 認證沒有模型端點；Cursor 使用 `GetUsableModels` RPC，而不是
+ `/models`。
+3. **合併**路由模型，作為帶名稱空間的條目（`provider/model`），從原生 Codex 目錄模板克隆而來，以便 Codex 嚴格的解析器接受它們。
+4. **應用過濾**：`config.disabledModels`，以及每個供應商非空的 `selectedModels` allowlist。
+5. **重新排序**，使置頂模型排在最前（見下文），然後將合併後的目錄寫回。
+
+路由目錄條目還會把 GPT-5 身份文案改為真實的上游模型名稱。reasoning 選項會依據供應商和模型後設資料，
+使用 Codex 的 `low | medium | high | xhigh | max | ultra` 檔位；上游不支援的值會在傳送請求前完成
+對映或下調。
+
+### 自訂模型顯示名稱
+
+自訂模型可以帶一個可讀的**顯示名稱**，只覆寫 Codex 模型選擇器中顯示的標籤，不改變任何路由行為。
+顯示名稱只對應目錄條目的 `display_name` 欄位——路由 slug（`/`）、別名碰撞順序、
+供應商，以及原生 OpenAI 行銷名稱都維持不動。
+
+可從 CLI 新增顯示名稱（proxy 在線時會立刻同步目錄）：
+
+```bash
+ocx models add deepseek deepseek-v4 --display-name "DeepSeek V4" --context-window 128000
+```
+
+也可以透過管理 API（`POST /api/custom-models`、`PUT /api/custom-models/`，搭配 `displayName`
+字串）與 web 儀表板設定或編輯。`/` 會被拒絕，因為會與路由 slug 的分隔符衝突。
+
+顯示名稱**只用於顯示，且在重新產生時保持穩定**。每次 `ocx sync` 與目錄重新整理都會從
+`config.json`（含 `customModels`）重新推導路由條目，因此會重新套用已設定的名稱，而不會漂移回
+路由 slug。受管服務重啟後，也會在 proxy 繫結後盡力同步一次。若這次啟動時的 best-effort 同步失敗
+（例如離線登入），會保留先前已寫入的目錄，並在下一次成功的 `ocx sync` 重新套用設定名稱。真正的
+上游原生名稱（例如 `gpt-5.6-sol` →「GPT-5.6-Sol」）來自固定的上游快照，絕不會被自訂顯示名稱覆寫。
+
+### 外部供應商管理器
+
+若 `config.toml` 已選用非 `openai` 或 `opencodex` 的供應商，OpenCodex 會保持檔案不變，並跳過
+profile 寫入、目錄／快取重新整理，以及立即與背景的 Codex 歷史遷移。管理自訂供應商的工具常會把既有
+session 標上該供應商 id；若直接替換作用中的 id，可能讓這些完好 session 從 Codex 的歷史檢視中消失。
+由舊版根級 profile 選到的外部供應商也適用同一保護。
+
+請讓單一工具負責 Codex 供應商設定的所有權。若要在既有供應商管理器後方使用 OpenCodex，請把該供應商
+指向 `http://127.0.0.1:10100/v1`，並使用 Responses 直通（Codex TOML 中 `wire_api = "responses"`），
+而不是 Chat Completions 轉譯。啟用 proxy API 認證時，還需從 `OPENCODEX_API_AUTH_TOKEN` 傳入
+`x-opencodex-api-key`，形式與上方 non-loopback 供應商設定一致。若要讓 OpenCodex 直接注入路由，請先把
+Codex 切回內建 `openai` 供應商，並移除任何使用者自有的根級 `openai_base_url`，再重新執行
+`ocx start`。
+
+### 目錄疑難排解
+
+若模型在 Codex 中缺失，或目錄順序／可見性看起來不對，請依序檢查：
+
+1. **供應商上的 `selectedModels`** —— 非空 allowlist 只會把列出的 id 暴露給 Codex；空或省略則暴露所有
+ 已發現模型。不在 allowlist 中的 id 永遠不會進入目錄。
+2. **`disabledModels`（頂層）** —— 會同時從目錄與 `/v1/models` 隱藏模型，並把裸原生 GPT slug 的
+ `visibility` 設為 `"hide"`。
+3. **`liveModels: false` 且 `models` 為空** —— 當即時探索關閉，且 `models` 為空或省略時，opencodex
+ 不會為該供應商暴露任何路由模型。
+4. **Cursor `GetUsableModels`** —— Cursor adapter 透過 protobuf `GetUsableModels` RPC 探索模型，而不是
+ `/models`，因此 Cursor 端的變更可能獨立於其他供應商改變可見 id。
+5. **快取與 `ocx sync`** —— 即時目錄約快取五分鐘（`modelCacheTtlMs`，預設 `300000`）。執行
+ `ocx sync` 可強制重新抓取並立刻重寫目錄。
+
+:::caution[其他本機寫入者]
+目錄寫入（`opencodex-catalog.json`、`config.toml`）在 opencodex **內部**是原子的，這只避免兩個
+opencodex 擁有的寫入者競爭時出現半寫入檔案。它**不會**阻止其他本機行程、檔案監看器或同步代理在
+opencodex 寫入後改寫目錄可見性或順序。Codex 另有獨立的 `models_cache.json`，可自行重新整理，
+因而可能在不改寫 `opencodex-catalog.json` 的情況下改變可見列表。若 proxy 執行中模型卻意外跳動，
+請先停止或重新設定競爭的寫入者，再執行 `ocx sync`——這是外部寫入者風險，不是已確認的 opencodex
+缺陷。
+:::
+
+## 代理連線錯誤
+
+如果 Codex 重試後報出類似
+`stream disconnected before completion: error sending request for url (http://127.0.0.1:10100/v1/responses)`
+的錯誤（或 Claude Code 出現類似的連線失敗），說明 opencodex 代理沒有在執行：
+設定埠上沒有任何監聽，用戶端只能顯示原始的連線錯誤。請重啟代理：
+
+```bash
+ocx start # 前臺執行
+ocx service install # 常駐：登入時自動啟動，崩潰後自動重啟
+```
+
+`ocx status` 可檢視代理是否在執行，未執行環境也會給出同樣的重啟提示；
+`ocx doctor` 會報告重啟安全性（service/shim 覆蓋情況）。
+
+## subagent 選擇器
+
+Codex 的 `spawn_agent` 會按優先順序排序，然後展示**前 5 個在選擇器中可見的目錄模型**。
+`subagentModels` 最多接受五個 id，可以同時使用裸原生 GPT slug 和帶名稱空間的 `provider/model`
+路由；所選模型會按順序獲得 0–4 的優先順序。
+
+```json
+{
+ "subagentModels": [
+ "gpt-5.5",
+ "gpt-5.6-sol",
+ "anthropic/claude-opus-5",
+ "xai/grok-4.5",
+ "cursor/gpt-5.6-terra"
+ ]
+}
+```
+
+優先順序排序：置頂（0–4）< 其他路由（5）< 原生（9）。你也可以從 [web 儀表板](/zh-tw/guides/web-dashboard/) 管理這一項。
+
+## Codex 帳號預熱
+
+向 Codex 帳號池新增 ChatGPT 帳號時，opencodex 會在儲存前向 Codex Responses 後端傳送一個小型
+streaming 請求來驗證憑證。輸入使用真正的 Responses item 陣列
+（`input: [{ type: "message", ... }]`），並等待 `response.completed`。預設模型為
+`gpt-5.4-mini`；若該模型返回 HTTP 400，則改用 `gpt-5.5` 重試。結構化的上游錯誤詳情會顯示給使用者，
+但不會洩露原始回應正文。後臺重新驗證是獨立功能，預設關閉；只有啟用 Token Guardian、將 `chatgpt`
+重新整理策略設為 `proactive`，並把 `tokenGuardian.codexWarmupEnabled` 設為 true 時才會執行。
+
+## 恢復原生 Codex
+
+opencodex 絕不會把你困住。**`ocx stop` 是完全恢復原生 Codex 的單一命令** ——
+它會停止 proxy、停止後臺服務（如已安裝），並剝除所有注入的行和路由的目錄條目，使普通的 `codex`
+完全像 opencodex 從未存在過一樣工作：
+
+```bash
+ocx stop # 停止 proxy + 服務，恢復原生 Codex
+ocx restore # 不停止 proxy 僅恢復 (別名: ocx eject)
+ocx restore back # 讓普通 Codex 重新指向仍在執行的 proxy
+```
+
+當 opencodex 作為受管的 [後臺服務](/zh-tw/reference/cli/#ocx-service) 執行環境，它會設定 `OCX_SERVICE=1`，這樣由服務驅動的重啟**不會**反覆改寫 Codex 設定——只有顯式的 `ocx stop` / `ocx service stop` 才會恢復原生 Codex。
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..cee7243fd
--- /dev/null
+++ b/docs-site/src/content/docs/zh-tw/guides/combos.md
@@ -0,0 +1,233 @@
+---
+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 或其背後的具體供應商/模型選擇器。
+:::
+
+## 選擇策略
+
+### 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..0dc401fcc
--- /dev/null
+++ b/docs-site/src/content/docs/zh-tw/guides/grok-build.md
@@ -0,0 +1,78 @@
+---
+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
+```
+
+## 認證注意事項
+
+即使在 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..131d9adfe
--- /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 費用 — 見下方[設定](#configuration)）。
+- 一個帶有 **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/model-ordering.md b/docs-site/src/content/docs/zh-tw/guides/model-ordering.md
new file mode 100644
index 000000000..7a673102d
--- /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..91d1742a6
--- /dev/null
+++ b/docs-site/src/content/docs/zh-tw/guides/opencode.md
@@ -0,0 +1,81 @@
+---
+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 層會覆寫它。
+
+## 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..181f72d15
--- /dev/null
+++ b/docs-site/src/content/docs/zh-tw/guides/pi.md
@@ -0,0 +1,98 @@
+---
+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..988c97fa5
--- /dev/null
+++ b/docs-site/src/content/docs/zh-tw/guides/providers.md
@@ -0,0 +1,198 @@
+---
+title: 供應商
+description: opencodex 進行身分驗證並與 LLM 供應商通訊的所有方式——OAuth、API 金鑰、ChatGPT 轉發以及本機。
+---
+
+**供應商（provider）** 是一個上游 LLM 端點，加上存取它的方式：一個 adapter、一個基礎 URL、一種認證模式，以及一個可選的模型列表。供應商設定位於 `~/.opencodex/config.json` 的 `providers` 下。
+
+## OpenAI 帳號模式
+
+| Provider id | 用途 | 憑證/帳號規則 |
+| --- | --- | --- |
+| `openai` | Codex 登入 | Pool（預設）選擇主帳號和新增帳號；Direct 只使用目前 caller/主登入。 |
+| `openai-apikey` | OpenAI API | 只使用設定的 API key/key pool；不讀取 Codex 帳號。 |
+
+bare `gpt-5.6-sol` 遵循 Providers 頁面中的 Pool/Direct 選項，
+`openai-apikey/gpt-5.6-sol` 選擇 API。憑證路徑之間不會 fallback。API 後設資料為 1,050,000 context /
+922,000 max input；`*-pro` virtual id 保留在公開狀態中，線上改寫為 base 模型加
+`reasoning.mode: "pro"`。
+
+若內建 `openai` 供應商缺失或已停用，可在儀表板 Accounts 選擇器或 Codex Auth 頁面恢復：缺失行會從規範預設建立，已停用的規範行會在不替換已儲存模式/模型設定的情況下重新啟用，非規範的 `openai` 行不會提供該恢復路徑。
+
+shipped v1 設定自動遷移到 marker 2 的單一選項行。原設定只保留一次到
+`~/.opencodex/config.json.pre-openai-tiers-v2.bak`；恢復命令：
+`cp ~/.opencodex/config.json.pre-openai-tiers-v2.bak ~/.opencodex/config.json`。
+
+## 認證模式
+
+供應商設定支援三種 `authMode`，預設值為 `key`。內建登入檔還會單獨標記本機預設；這類預設通常會
+同時省略 `authMode` 和 `apiKey`。
+
+| `authMode` | 如何進行認證 | 使用方 |
+| --- | --- | --- |
+| `key` | 傳送你的 API 金鑰（`Authorization: Bearer …`，或按 adapter 使用 `x-api-key` / `api-key`）。金鑰可以是字面值，也可以是 `${ENV_VAR}` 引用。 | 大多數供應商。 |
+| `forward` | 將**你傳入的 Codex 認證請求頭**原樣轉發給供應商——不儲存任何金鑰。這就是 ChatGPT 登入的透傳方式。 | OpenAI（`openai-responses` adapter）。 |
+| `oauth` | 讀取已儲存的 OAuth 存取權杖（過期前自動重新整理），並將其用作 bearer 金鑰。 | xAI、Anthropic、Kimi、Kiro、Google Antigravity、Cursor。 |
+
+## 1. ChatGPT 登入（forward / 透傳）
+
+預設供應商**不需要 API 金鑰**。它將你現有 `codex login` 的憑證直接轉發到 OpenAI Responses 後端：
+
+```json
+{
+ "openai": {
+ "adapter": "openai-responses",
+ "baseUrl": "https://chatgpt.com/backend-api/codex",
+ "authMode": "forward"
+ }
+}
+```
+
+只有一組精選的請求頭會被轉發（`FORWARD_HEADERS`：authorization、ChatGPT account id、OpenAI beta/originator/session——參見 [Adapters](/zh-tw/reference/adapters/)）。這條路徑也為 [web-search 和 vision sidecar](/zh-tw/guides/sidecars/) 提供支援。
+
+ChatGPT 透傳目錄也會加入 GPT-5.6 Sol/Terra/Luna 的裸 slug（`gpt-5.6-sol`、
+`gpt-5.6-terra`、`gpt-5.6-luna`）；帳號具備相應許可權時才能實際呼叫。
+
+## 2. 帳號登入（OAuth）
+
+有六個供應商預設使用 OAuth 登入。opencodex 會把憑證存入 `~/.opencodex/auth.json` 並自動重新整理。
+登入 CLI 也接受 `chatgpt`：它會獲取一份 ChatGPT 憑證，並建立一個 `forward` 模式的供應商條目。
+
+```bash
+ocx login xai # xAI Grok
+ocx login anthropic # Anthropic Claude (Pro/Max)
+ocx login kimi # Moonshot Kimi
+ocx login kiro # 匯入 kiro-cli 憑證（支援權杖回退）
+ocx login google-antigravity
+ocx login cursor # 獨立的 Cursor PKCE 登入
+ocx login chatgpt # 獨立的 ChatGPT OAuth 登入
+ocx logout
+```
+
+| 供應商 | Adapter | 基礎 URL | 備註 |
+| --- | --- | --- | --- |
+| `xai` | `openai-chat` | `https://api.x.ai/v1` | 優先使用即時 Grok 目錄；回退預設模型為 `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 程式設計模型。 |
+| `kiro` | `kiro` | `https://runtime.us-east-1.kiro.dev` | 優先複用已安裝的 `kiro-cli` 登入。需先安裝 Kiro CLI（`curl -fsSL https://cli.kiro.dev/install | bash`）並執行 `kiro-cli login`。 |
+| `google-antigravity` | `google` | `https://daily-cloudcode-pa.googleapis.com` | 透過 Cloud Code Assist 協議使用 Google OAuth。 |
+| `cursor` | `cursor` | `https://api2.cursor.sh` | 實驗性 PKCE 登入、HTTP/2 傳輸和按帳號篩選的模型發現。 |
+
+你也可以從 [web 儀表板](/zh-tw/guides/web-dashboard/) 啟動 OAuth。
+
+### 多個 OAuth 帳號
+
+OAuth 憑證中帶有穩定帳號 id 或郵箱的供應商可以儲存多個登入。Providers 頁面會在下拉選單中顯示這些
+帳號，允許繼續新增，並在不登出其他帳號的情況下切換目前帳號。沒有身份資訊的 Kimi 和 Kiro 會替換
+目前 active slot；`chatgpt` 始終只有一個 slot，因為 Codex 帳號池使用獨立儲存。權杖仍儲存在
+`~/.opencodex/auth.json` 中；`/api/oauth/accounts` 只返回脫敏後的 metadata。
+
+## 3. API 金鑰目錄
+
+opencodex v2.7.1 內建 50 個預設：40 個金鑰預設、6 個 OAuth 預設、3 個本機預設，以及預設的
+ChatGPT 轉發預設。儀表板的 **Add provider** 選擇器會開啟金鑰供應商的儀表板，驗證並儲存金鑰。
+主要條目包括：
+
+| 供應商 | 基礎 URL |
+| --- | --- |
+| **OpenAI (API key)** | `https://api.openai.com/v1` |
+| **Anthropic (API key)** | `https://api.anthropic.com` |
+| **OpenRouter** | `https://openrouter.ai/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` |
+| 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` |
+| Qwen Cloud | Token plan（預設）: `https://token-plan.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1` · 按量付費: `https://dashscope.aliyuncs.com/compatible-mode/v1` · 或自定義 |
+| 騰訊雲 Coding Plan | `https://api.lkeap.cloud.tencent.com/coding/v3` |
+| SiliconFlow | `https://api.siliconflow.cn/v1` |
+| Xiaomi MiMo | `https://api.xiaomimimo.com/anthropic` |
+| Kilo | `https://api.kilo.ai/api/gateway` |
+| GitHub Copilot · GitLab Duo | `https://api.githubcopilot.com` · `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 |
+
+大多數使用帶 bearer 金鑰的 `openai-chat` adapter；少數僅暴露 Anthropic 相容端點的供應商（例如 **Xiaomi MiMo**）使用 `anthropic` adapter（`x-api-key`）。
+
+> **騰訊雲 Coding Plan 使用限制：**騰訊將此訂閱限定為互動式程式設計工具使用。禁止通用 API
+> 自動化、自定義應用後端和非互動式批次呼叫；違規使用可能導致套餐金鑰被停用。
+
+### 多個 API 金鑰
+
+基於金鑰的供應商也可以儲存多個 key。透過 Providers 頁面新增金鑰時，它會存入
+`provider.apiKeyPool`、被設為 active，並同步到 `provider.apiKey`，這樣路由和 adapter 仍讀取原來的
+欄位。同一個下拉選單可以切換或移除金鑰；管理 API 是 `/api/providers/keys`，並且只返回脫敏後的金鑰。
+
+### 從終端切換帳號
+
+無需開啟儀表板，即可使用 `ocx account list`、`ocx account current` 和 `ocx account use` 檢視或
+切換同一組 Codex、OAuth 和 API-key pool。完整命令、JSON 輸出和新 session 生效規則請參閱
+[CLI 參考](/zh-tw/reference/cli/#ocx-account-subcommand)。
+
+### GPT-5.6 預覽路徑
+
+GPT-5.6 Sol/Terra/Luna 會預置在供應商的回退列表中，因此即使即時模型目錄暫時滯後，`ocx sync`
+也能繼續顯示這些模型。
+
+| Codex 路由 | 預置模型 id | Codex 中顯示的上下文 |
+| --- | --- | --- |
+| Codex 登入（Pool 或 Direct） | `gpt-5.6-*` | 372,000 |
+| OpenAI (API key) | `openai-apikey/gpt-5.6-*` 和 `*-pro` | 1,050,000（max input 922,000） |
+| 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 檔位，例如 Luna 有 `max`，但沒有 `ultra`。路由條目
+則使用各供應商的後設資料和 reasoning 對映。四條路徑最終都受上游帳號許可權限制；Cursor 還會根據即時
+發現結果，僅保留目前帳號可用的模型。
+
+:::note[gateway 與訂閱 proxy]
+是否支援某個供應商，取決於 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 這類無法匹配上述實現的專有 API 暫不直接支援。**GitHub Copilot** 和
+**GitLab Duo** 是多模型 gateway，對映到各自的通用 OpenAI 相容端點。Copilot 支援透過
+`ocx login github-copilot` 使用 GitHub 裝置流 OAuth 登入（非官方橋接 — 使用 VS Code 公開用戶端 id
+登入後換取短期 Copilot API 權杖，需要有效的 Copilot 訂閱，GitHub 政策收緊時可能失效）；GitLab Duo
+使用 Bearer **訂閱權杖**（而非普通 API 金鑰）進行認證。
+**Cloudflare AI Gateway** 需要將 account 和 gateway id 填入 URL。
+
+Cursor 作為單獨的實驗性 adapter 進行跟蹤。`adapter: "cursor"` 會作為實驗性本機設定出現在
+`ocx init` 和 dashboard Add Provider picker 中，並儲存 Cursor 的靜態回退模型目錄 metadata。設定
+Cursor access token 後，opencodex 會使用 Cursor live HTTP/2 transport。v2.7.1 回退列表包含上下文為
+1M 的 `gpt-5.6-sol` / `terra` / `luna`，以及上下文為 500K 的
+`grok-4.5` / `grok-4.5-fast`；最終顯示哪些模型由帳號的即時發現結果決定。Cursor 伺服器直接發起的
+native read/write/delete/ls/grep/shell/fetch 執行預設停用，因為它會繞過 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 結果。
+Cursor OAuth 和 live model discovery 已在這個實驗性 adapter 中啟用；Cursor 仍不會出現在 key-login
+列表中。
+:::
+
+### Ollama Cloud
+
+Ollama Cloud 是託管（而非本機）的 Ollama，在 `https://ollama.com/v1` 上相容 OpenAI，金鑰來自 [ollama.com/settings/keys](https://ollama.com/settings/keys)。opencodex 按視覺能力對其雲端陣容進行分類，使 [vision sidecar](/zh-tw/guides/sidecars/) 僅對純文字模型生效。純文字模型（例如 `glm-5.2`、`deepseek-v4-pro`、`gpt-oss`、`qwen3-coder`、`minimax-m2.x`、`nemotron-3-*`）列在 `noVisionModels` 中；原生支援視覺的模型（例如 `kimi-k2.6`、`minimax-m3`、`gemma4`、`qwen3.5`、`gemini-3-flash-preview`）則不在其中。匹配能容忍 Ollama 的 `:size` 標籤，因此 `gpt-oss` 涵蓋 `gpt-oss:120b` 和 `gpt-oss:20b`。
+
+## 4. 本機供應商
+
+讓 opencodex 指向本機的 OpenAI 相容伺服器——通常使用空金鑰：
+
+| 供應商 | 基礎 URL |
+| --- | --- |
+| Ollama (local) | `http://localhost:11434/v1` |
+| vLLM | `http://localhost:8000/v1` |
+| LM Studio | `http://localhost:1234/v1` |
+
+## 任意 OpenAI 相容端點
+
+如果某個供應商使用 Chat Completions，`openai-chat` adapter 即可處理它——在儀表板中選擇 **Custom**，或在 `ocx init` 中選擇 `custom` 並輸入基礎 URL。每個供應商欄位（`headers`、`noReasoningModels`、`noVisionModels`、`models`……）請參見 [設定參考](/zh-tw/reference/configuration/)。
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..8db96f256
--- /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..093323ba8
--- /dev/null
+++ b/docs-site/src/content/docs/zh-tw/guides/sub-agent-surface.md
@@ -0,0 +1,127 @@
+---
+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` 內容傳送。
+:::
+
+## 模式
+
+| 模式 | 介面 | 行為 |
+| --- | --- | --- |
+| **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)）。 |
+
+### 加密的 v2 任務傳輸
+
+只有原生 ChatGPT 後端能夠讀取其加密任務載荷。對於無法讀取的 v2 `agent_message`，opencodex 會在呼叫 provider 之前執行以下規則：
+
+- 直接路由到非原生 provider 時，返回 HTTP 400，並設定 `error.code = "unreadable_encrypted_agent_task"`。回應不會回顯加密載荷。
+- 組合路由只會為該任務考慮規範的原生 ChatGPT 目標，重試時也遵守同一規則。如果組合中沒有可解密的目標，則返回同樣的 400，而不會把空任務傳送給外部 provider。
+- 可讀取的明文任務仍保留正常的組合順序與故障轉移行為。
+
+恢復方法：將子代理切換到原生 ChatGPT 模型、在組合中加入原生目標、異構 provider 委派改用 v1，或者在你能控制呼叫方時將任務重新作為明文 v2 `agent_message` 內容傳送。
+
+## 運作原理
+
+所選模式會設定 Codex 讀取的每個目錄條目中的 `multi_agent_version` 欄位：
+
+- **v1 模式**：強制所有條目使用 `multi_agent_version = "v1"`，覆蓋上游固定值。
+- **base 模式**：恢復上游預設值。已固定的模型使用快照值；未固定的模型不寫入該欄位，交由 Codex 功能開關決定。
+- **v2 模式**：強制所有條目使用 `multi_agent_version = "v2"`，覆蓋上游固定值。
+
+無論是即時 `/v1/models` 目錄回應，還是磁碟目錄同步，這項覆蓋都會作為最後一步執行。因此，無論條目原本如何生成，新會話都會使用一致的模式。
+
+### 委託模型與推理強度
+
+儀表板中的 **子代理委託** 選擇器會儲存 `injectionModel`，以及可選的 `injectionEffort`。它們用於生成委託指引，並不是由 proxy 執行的子代理路由規則。設定 `injectionPrompt` 可以把內建指引文字整體替換為自定義內容。
+
+`multiAgentGuidanceText` 根據請求中的工具列表判斷目前介面 —— 包括 Codex Desktop 的 WebSocket 路徑（`responses_lite`），此時工具位於 `additional_tools` input 項中而不是請求的 `tools` 陣列。
+
+在 **v2** 請求上（base 模式下的 Sol/Terra，v2 模式下的全部模型），只要設定了有效的注入模型、或有效子代理清單非空，proxy 就會注入一段不超過 700 字元的精簡指引。該指引以條件方式說明 `model` / `reasoning_effort` 覆蓋，不假定它們是否出現在目前 schema 中；它要求使用 `fork_turns: "none"`（或部分 fork），僅命名有效的規範首選模型，並只列出 Codex 中 picker 可見、相容 v2、按 priority 排序後前五項內的已設定模型及其可用 effort 檔位。
+
+在 **v1** 請求上，proxy 僅在最高推理檔位（max / ultra）映象上游的主動委託文字。v1 不會追加模型指定、清單或自定義提示詞。
+
+要替換內建的 v2 指引，請設定 `injectionPrompt`（config 鍵，或 `PUT /api/injection-model` 的 `prompt` 值）。佔位符 `{{model}}`、`{{effort}}`、`{{roster}}` 會被替換為設定的注入模型、推理強度和解析出的清單。觸發條件保持不變：自定義提示詞不會讓本應保持沉默的請求觸發注入。
+
+## 更改模式
+
+### 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 仍會在生成時檢查目標目錄條目是否支援該強度。
+
+## 推理強度
+
+可選的子代理推理強度儲存在 `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..cdce912d0
--- /dev/null
+++ b/docs-site/src/content/docs/zh-tw/guides/web-dashboard.md
@@ -0,0 +1,114 @@
+---
+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
+```
+
+## 可以完成哪些操作
+
+| 區域 | 作用 |
+| --- | --- |
+| **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` 這類不透明標籤，不會記錄帳號郵箱。
+
+## 儀表板如何與代理通訊
+
+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..1f65ff536
--- /dev/null
+++ b/docs-site/src/content/docs/zh-tw/reference/adapters.md
@@ -0,0 +1,139 @@
+---
+title: Adapters
+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..afbbd32e0
--- /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/)。
+
+## 模組圖
+
+```
+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..86f610f28
--- /dev/null
+++ b/docs-site/src/content/docs/zh-tw/reference/cli.md
@@ -0,0 +1,494 @@
+---
+title: CLI 參考
+description: 所有 ocx 命令與引數。
+---
+
+opencodex 的命令列工具是 `ocx`。執行 `ocx help`（或 `--help` / `-h`）可檢視頂層用法。
+對幫助表中註冊的命令，可執行 `ocx help ` 檢視命令專屬幫助。幫助和版本命令均為只讀，
+不會啟動、停止、安裝、解除安裝或改寫 Codex/opencodex 狀態。
+
+## 安裝與生命週期
+
+### `ocx init`
+
+互動式設定嚮導。它會依次詢問 provider（預設或自定義）、API key（字面值或 `${ENV}`）、預設模型
+和代理埠，儲存 `~/.opencodex/config.json`，並可選擇把代理注入
+`$CODEX_HOME/config.toml`（預設 `~/.codex/config.toml`），以及安裝 Codex 自動啟動 shim。
+
+### `ocx start [--port ]`
+
+啟動代理伺服器（首選埠 `10100`）。如果該埠已被佔用，opencodex 會選擇並記錄另一個可用
+埠。它會寫入 PID/執行環境埠狀態，並拒絕啟動第二個仍存活的例項。啟動時會把各 provider 的
+模型同步進 Codex 目錄。關閉時會恢復原生 Codex，除非它以受管服務執行（`OCX_SERVICE=1`）。
+
+```bash
+ocx start
+ocx start --port 8080
+```
+
+### `ocx stop`
+
+按 PID 停止正在執行的代理，刪除 PID 檔案並恢復原生 Codex。如果已安裝受管後臺服務，
+`ocx stop` 會先停止服務，以免它重新拉起代理。Web 儀表板的 **Stop** 按鈕
+（`POST /api/stop`）執行相同操作。
+
+### `ocx restore` · `ocx eject`
+
+在**不停止**代理的情況下恢復原生 Codex。它會刪除注入的設定行和路由目錄條目，使普通
+`codex` 再次按原生方式工作。`eject` 是 `restore` 的別名。
+
+給任一寫法加上 `back`，可在不改變代理生命週期的情況下，讓普通 `codex` 重新指向已經執行的
+代理：
+
+```bash
+ocx restore back
+ocx eject back
+```
+
+### `ocx recover-history --legacy-openai`
+
+顯式恢復舊開發建置留下的歷史記錄；這些建置在支援可逆備份前就已重對映 Codex App 歷史。
+如果歷史資料庫被鎖定，請先關閉 Codex。
+
+### `ocx restart`
+
+依次執行 `stop` 和 `ensure`：停止代理/服務，恢復原生 Codex，在後臺啟動代理，再把實際埠同步
+回 Codex。
+
+### `ocx ensure`
+
+以冪等方式確保後臺代理正在執行，然後同步其即時模型目錄。如果 `codexAutoStart` 為 `false`，
+命令只會提示自動啟動已停用，不執行其他操作。
+
+### `ocx status [--json]`
+
+列印只讀診斷摘要：代理 PID、`/healthz` 可達性、儀表板 URL、設定路徑、預設 provider、Codex
+自動啟動設定、服務狀態、shim 狀態以及隱藏使用者名稱後的實際 Codex home。僅當命中明確的高置信度
+Windows Orca runtime-home 特徵時，才會針對 App home 不一致給出可執行警告，但不會自動修改 `CODEX_HOME`。
+
+使用 `--json` 可獲得機器可讀的只讀診斷契約：
+
+```bash
+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`（埠、hostname、執行環境/設定來源）、設定載入診斷和內建 Codex plugin
+診斷。JSON schema 只允許增加欄位：後續版本可能新增欄位，但現有欄位應保持穩定。它會有意排除
+API key、OAuth token、authorization header、請求內容、電子郵件和帳號身份資訊。
+
+### `ocx health [--json]`
+
+驗證目前代理的身份。普通輸出報告 PID/埠；`--json` 輸出 `{ok, pid, port}`。只有健康時才以
+0 退出，否則以 1 退出，因此適合作為服務探針。
+
+### `ocx uninstall` · `ocx remove`
+
+停止服務和代理，移除服務與 Codex shim，恢復原生 Codex；只有所有恢復步驟成功後，才刪除
+opencodex 本機設定。`remove` 是 `uninstall` 的別名。
+
+## 模型與 Codex
+
+### `ocx sync`
+
+從所有已設定 provider 獲取即時模型列表，並把合併後的目錄重新注入 Codex。新增 provider 後或
+需要重新整理可用模型時執行。
+
+### `ocx sync-cache`
+
+使 Codex 的本機模型選擇器快取失效，隨後用目前 opencodex 目錄重新建置。
+
+### `ocx v2 [subcommand]`
+
+管理 Codex 的 `multi_agent_v2` feature flag 和三態 multi-agent surface mode。
+
+| Subcommand | Action |
+| --- | --- |
+| `status`（預設） | 報告目前 v2 flag、multi-agent mode 和 thread concurrency。 |
+| `on` | 在 `$CODEX_HOME/config.toml` 中啟用 `multi_agent_v2` feature，並重新同步目錄。 |
+| `off` | 停用 `multi_agent_v2` feature，並重新同步目錄。 |
+| `mode v1` | 強制所有模型使用 v1、關閉 native v2，並把 thread limit 儲存在 `[agents] max_threads`。 |
+| `mode default` | 遵循 upstream model pin（sol/terra=v2，luna=v1，其餘模型跟隨 Codex flag）。這是安裝預設值。 |
+| `mode v2` | 強制所有模型使用 v2、開啟 native v2，並把同一個 thread limit 遷移到 v2 key。 |
+| `threads ` | 設定目前 v1/v2 thread limit（大於等於 1 的整數）。 |
+
+```bash
+ocx v2 status
+ocx v2 mode v1
+ocx v2 mode default
+ocx v2 on
+ocx v2 threads 16
+```
+
+`mode` subcommand 會把 `multiAgentMode` 寫入 opencodex 設定並重新同步 Codex 目錄。
+`mode v1`/`mode v2` 與 `on`/`off` 會在有效的 v1/v2 設定 key 之間遷移目前數值，同時用
+`codex features enable|disable` 切換 codex-rs feature flag；失敗時恢復原始 `config.toml`。變更從新的 Codex
+session 開始生效，正在執行的 session 保持已固定的 surface。
+
+## 無頭儀表板對等
+
+營運用的儀表板功能也可在沒有瀏覽器的情況下使用。這些命令會定位已通過身分檢查、正在執行的
+代理（含後備 runtime 埠），並重用與 GUI 相同的管理路由、驗證、即時設定與目錄重新整理副作用。
+
+| 資源 | 命令 |
+| --- | --- |
+| 路由 | `ocx combo ...` 或 `ocx route combo ...` |
+| 代理政策 | `ocx agent injection\|effort\|subagents\|fallback\|sidecar ...` |
+| 可觀測性 | `ocx observe logs\|usage\|storage\|memory\|debug ...` |
+| API 准入 | `ocx access key\|endpoints\|models\|test ...` |
+| Claude Code | `ocx claude config status\|set ...` |
+| Grok Build | `ocx grok status\|exclude\|include\|set\|clear\|apply ...` |
+| 執行期控制 | `ocx system status\|settings\|startup\|diagnostics\|sync\|update ...` |
+| 離線設定 | `ocx config show\|get\|set\|unset\|validate\|export\|import ...` |
+
+在語意明確時，預設是 list/status。使用 `--json` 取得結構化快照，並以
+`ocx observe logs --follow --jsonl` 取得串流請求日誌。破壞性的移除／匯入與更新動作需要
+`--yes`。即時操作需要代理正在執行；已驗證的設定檢查與匯入／匯出可離線使用。
+
+```bash
+ocx provider test ark
+ocx models live --provider ark --json
+ocx route combo set reliable --targets ark/model-a:2,openai/gpt-5.5
+ocx agent subagents set ark/model-a,openai/gpt-5.5
+ocx observe usage --range 30d --json
+ocx access key create deployment
+ocx system settings --stream-mode eager-relay
+```
+
+主題、語言、導覽與其他純視覺的瀏覽器狀態刻意沒有 CLI 對等命令。Cloudflare Tunnel 設定不屬於
+此命令集。
+
+### `ocx models [subcommand]`
+
+列出已設定供應商中靜態 seed 的模型。`--provider` 篩選單一已設定供應商；`--json` 返回模型
+metadata。`live` 讀取執行中的目錄；`add`、`edit`、`remove` 與 `list-custom` 管理手動目錄條目；
+`enable`、`disable` 與 `provider` 控制可見性；`selected` 控制供應商 allowlist；`context` 控制
+供應商 context 上限；`shadow` 管理背景 shadow-call 攔截。
+
+### `ocx provider `
+
+非互動式供應商管理。登錄檔條目只需名稱即可 seed；自訂名稱必須同時提供 `--adapter` 和
+`--base-url`。
+
+| Subcommand | 支援的引數 | 操作 |
+| --- | --- | --- |
+| `list` | `--json` | 列出已設定供應商與尚未新增的登錄檔條目。 |
+| `add ` | `--adapter `、`--base-url `、`--api-key `、`--default-model `、`--set-default`、`--force`、`--json`、`--sync` | 新增登錄檔或自訂供應商。`--force` 會覆寫；在人類輸出模式下，`--sync` 會重新整理正在執行的代理。 |
+| `edit ` | provider 欄位旗標、`--json` | 編輯已驗證的即時供應商欄位，而不替換 key pool。 |
+| `test ` | `--json` | 探測真實的上游模型端點。 |
+| `show ` | `--json` | 顯示設定並遮蓋 API key。 |
+| `remove ` | `--json` | 刪除非預設供應商；不能刪除最後一個供應商。 |
+| `set-default ` | `--json` | 把既有供應商設為預設值。 |
+| `selected ` | `--set `、`--clear`、`--json` | 讀取或更新供應商模型 allowlist。 |
+| `quota` | `--refresh`、`--json` | 讀取供應商額度報告。 |
+| `presets` | `--json` | 列出儀表板供應商預設組合。 |
+| `account-mode` | `pool`、`direct`、`--json` | 選擇 pooled 或 direct 的 Codex 帳號路由。 |
+
+```bash
+ocx provider list --json
+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 account `
+
+透過正在執行的代理列出和切換供應商帳號及 API key pool。已釋出的幫助介面如下：
+
+```text
+Usage: ocx account ...
+
+List and switch provider accounts and API-key pools (GUI parity).
+
+list [provider] Codex account pool, OAuth accounts and API keys (identifiers shown masked as the API returns them).
+current Show the active account or key.
+use Switch the active credential; 'main' selects the Codex App login.
+refresh Force-refresh Codex or provider quota reports.
+auto-switch Control the Codex pool threshold.
+remove --yes Remove a stored account or key after an existence check.
+add-key [--label