@bitkyc08/opencodex 2.6.11 → 2.6.13

package/README.ko.md

@@ -1,3 +1,12 @@
+<h3 align="center">make codex open!</h3>
+<p align="center"><code>npm install -g @bitkyc08/opencodex</code> · <code>ocx start</code> · <b>localhost:10100</b></p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/@bitkyc08/opencodex"><img src="https://img.shields.io/npm/v/@bitkyc08/opencodex?color=cb3837&label=npm&logo=npm" alt="npm version"></a>
+  <a href="https://github.com/lidge-jun/opencodex/blob/main/LICENSE"><img src="https://img.shields.io/npm/l/@bitkyc08/opencodex?color=blue" alt="license"></a>
+  <img src="https://img.shields.io/node/v/@bitkyc08/opencodex?logo=node.js&label=node" alt="node version">
+</p>
+
 <p align="center">
   <img src="assets/banner.png" alt="opencodex — 어떤 LLM이든 Codex에서 사용" width="820">
 </p>
@@ -10,8 +19,14 @@
   <img src="assets/architecture.png" alt="opencodex 아키텍처 — Codex CLI가 opencodex 프록시를 통해 모든 LLM 프로바이더로 라우팅" width="820">
 </p>
 
-Codex는 오직 Responses API(`/v1/responses`)만 사용합니다. opencodex는 Codex와 LLM 프로바이더 사이에서
-프로토콜을 실시간으로 변환해 줍니다. streaming, tool 호출, reasoning, 이미지까지 양방향으로 처리합니다.
+Claude, Gemini, Grok, GLM, DeepSeek, Kimi, Qwen, Ollama 등 어떤 LLM이든 Codex에서 사용하세요 — OpenAI가 지원을 추가하기를 기다릴 필요 없이.
+
+opencodex는 Codex의 Responses API를 프로바이더가 쓰는 프로토콜로 변환해 주는 가벼운 로컬 프록시입니다. streaming, tool 호출, reasoning 토큰, 이미지까지 양방향으로 모두 동작합니다.
+
+또한 Codex 인증을 위한 **ChatGPT 계정 풀**을 관리할 수 있습니다. 여러 ChatGPT / Codex 계정을 추가하고,
+대시보드에서 5시간 / 주간 / 30일 쿼터를 갱신하며, 새 세션을 사용량이 가장 적은 정상 계정으로 자동
+라우팅할 수 있습니다. 기존 Codex 스레드는 시작한 계정에 그대로 고정되므로, 긴 SSH·tmux·모바일 연결
+세션이 대화 도중 계정을 바꾸지 않습니다.
 
 ```
 Codex CLI / App / SDK ──/v1/responses──▶ opencodex ──▶ Any provider
@@ -20,6 +35,21 @@ Codex CLI / App / SDK ──/v1/responses──▶ opencodex ──▶ Any provi
               OpenRouter · Azure · DeepSeek · GLM · …and OpenAI itself
 ```
 
+```mermaid
+flowchart LR
+  codex[Codex 세션<br/>CLI, App, SSH, 모바일] --> proxy[opencodex]
+  proxy --> existing{기존 스레드?}
+  existing -->|예| pinned[같은 ChatGPT<br/>계정 유지]
+  existing -->|새 세션| quota[쿼터 갱신<br/>5h, 주간, 30d]
+  quota --> pick[사용량 최소<br/>정상 계정 선택]
+  pick --> upstream[ChatGPT / Codex 백엔드]
+  pinned --> upstream
+  upstream --> outcomes[쿼터 / 인증 결과]
+  outcomes -->|429| cooldown[쿨다운 + failover]
+  outcomes -->|401 / 403| reauth[재인증 필요 표시]
+  cooldown --> quota
+```
+
 ## 지원 플랫폼
 
 | OS | 지원 상태 | 서비스 관리자 |
@@ -67,40 +97,72 @@ npm install -g @bitkyc08/opencodex   # --ignore-scripts, --omit=optional 없이
 가장 쉬운 방법은 웹 대시보드를 이용하는 것입니다.
 
 ```bash
-ocx gui        # 브라우저에서 localhost:10100 대시보드를 엽니다
+ocx gui
 ```
 
-대시보드에서 할 수 있는 일:
+`http://localhost:10100` 대시보드가 열립니다. 여기서:
+
+1. **"Add Provider"** 를 클릭하세요.
+2. **40개 이상의 내장 프로바이더** 중에서 고르거나, 커스텀 OpenAI 호환 엔드포인트를 입력하세요.
+3. API 키를 붙여넣으세요 (Anthropic, xAI, Kimi는 OAuth 로그인도 가능).
+4. 프로바이더의 `/v1/models` 엔드포인트에서 모델이 **자동 감지**됩니다.
 
-1. **프로바이더 선택** — 20개 이상의 내장 프로바이더(Anthropic, Google, xAI, Ollama Cloud 등)에서 원하는 것을 고르세요.
-2. **API 키 입력** — 키를 붙여넣으면 바로 저장됩니다. OAuth를 지원하는 프로바이더는 로그인 버튼으로 인증할 수도 있습니다.
-3. **모델 자동 감지** — 프로바이더를 추가하면 사용 가능한 모델을 자동으로 가져옵니다. Codex 모델 선택기에도 곧바로 반영됩니다.
+추가한 프로바이더는 재시작 없이 즉시 사용할 수 있습니다.
 
-물론 `~/.opencodex/config.json`을 직접 편집해도 됩니다. 하지만 대시보드가 훨씬 편리합니다.
+`ocx init`(대화형 CLI)이나 `~/.opencodex/config.json` 직접 편집으로도 프로바이더를 추가할 수 있습니다.
 
 ## 모델 라우팅
 
 `provider/model` 형식으로 원하는 모델을 직접 지정할 수 있습니다:
 
 ```bash
-codex -m "anthropic/claude-opus-4-8"   "이 스택 트레이스를 설명해 줘"
-codex -m "google/gemini-2.5-pro"       "이 코드를 리팩터링해 줘"
-codex -m "ollama-cloud/glm-5.2"        "SQL 마이그레이션 작성"
-codex -m "xai/grok-4"                  "이 PR을 리뷰해 줘"
+# Anthropic을 통해 Claude Opus 사용
+codex -m "anthropic/claude-opus-4-8" "이 스택 트레이스를 설명해 줘"
+
+# Google을 통해 Gemini 사용
+codex -m "google/gemini-3-pro" "auth.ts의 유닛 테스트를 작성해 줘"
+
+# Ollama Cloud를 통해 GLM 사용
+codex -m "ollama-cloud/glm-5.2" "SQL 마이그레이션을 작성해 줘"
+
+# Ollama를 통해 로컬 모델 사용
+codex -m "ollama/llama3" "이 함수를 리팩터링해 줘"
 ```
 
-프로바이더 이름 없이 모델명만 쓰면 `defaultProvider`로 라우팅됩니다.
+`provider/` 접두사를 생략하면 opencodex는 기본 프로바이더로 라우팅하거나, 모델명 패턴으로 자동
+매칭합니다 (예: `claude-*`는 Anthropic, `gpt-*`는 OpenAI).
+
+라우팅된 모델은 **Codex App** 모델 선택기에도 모델별 reasoning effort 컨트롤과 함께 나타납니다:
+
+<p align="center">
+  <img src="assets/codex-app-picker.png" alt="opencodex 라우팅 모델을 reasoning effort 선택기와 함께 보여주는 Codex App" width="480">
+</p>
+
+## ChatGPT 계정 풀
+
+대시보드의 **Codex Auth**를 열어 풀 계정을 추가하고, 다음 Codex 세션을 어느 계정이 처리할지 고르세요.
+opencodex는 두 가지 동작을 분리해서 유지합니다:
+
+- **기존 세션은 affinity를 유지합니다.** 스레드 id가 선택된 계정에 바인딩되어 이후 턴에서 재사용되므로,
+  긴 요청이나 모바일/SSH 연결 세션이 같은 계정을 계속 사용합니다.
+- **새 세션은 자동 라우팅됩니다.** 자동 전환이 켜져 있으면 opencodex는 5시간·주간·30일 사용량 중 가장
+  뜨거운 쿼터 창을 비교해, 활성 계정이 임계치를 넘으면 새 세션을 사용량이 낮은 적격 계정으로 보냅니다.
+- **쿼터 조회가 내장되어 있습니다.** 대시보드에서 모든 계정 쿼터를 한 번에 갱신할 수 있고, 요청 로그는
+  풀 트래픽을 비-PII 계정 서수로 라벨링합니다.
+- **실패는 fail-closed입니다.** 토큰 실패는 다른 자격증명으로 조용히 폴백하지 않고 재인증을 표시합니다.
+  429 쿼터 응답은 계정을 쿨다운에 넣고 이후 작업을 다른 적격 풀 계정으로 failover할 수 있습니다.
 
 ## 주요 기능
 
-- **다섯 가지 adapter**로 Anthropic Messages, Google Gemini, Azure, OpenAI Responses passthrough, 그리고 **모든 OpenAI 호환 Chat Completions** 엔드포인트를 지원합니다. 프로바이더가 OpenAI 호환 API를 제공한다면 별도 adapter 없이 바로 연결할 수 있습니다.
-- **OAuth, API 키, ChatGPT forward** 중 원하는 인증 방식을 선택하세요. xAI / Anthropic / Kimi 계정으로 OAuth 로그인하면 토큰이 자동 갱신됩니다. `codex login`을 forward 하거나, API 키를 직접 입력해도 됩니다(`${ENV_VARS}` 지원). 18개 프로바이더의 API 키 카탈로그(**Ollama Cloud** 포함)가 기본 내장되어 있습니다.
-- **Codex CLI, TUI, App, SDK에 바로 연결됩니다.** `$CODEX_HOME/config.toml`(기본 `~/.codex/config.toml`)에 `[model_providers.opencodex]` 테이블을 자동 주입하고, 공유 모델 카탈로그를 작성합니다. 라우팅된 모델이 Codex 모델 선택기에 자동으로 나타납니다.
-- **서브에이전트 제어.** `subagentModels` 또는 웹 대시보드에서 최대 5개의 모델을 골라 Codex `spawn_agent` 선택기에 우선 노출할 수 있습니다.
-- **기본은 HTTP/SSE, WebSocket은 opt-in.** 프록시에 Responses WebSocket 엔드포인트가 있지만, `"websockets": true`로 설정할 때만 `supports_websockets`를 광고합니다.
-- **Sidecar로 기능 확장.** OpenAI가 아닌 모델에서도 ChatGPT 로그인을 통한 `gpt-5.4-mini`로 실제 **웹 검색**과 **이미지 이해** 기능을 사용할 수 있습니다.
-- **웹 대시보드** 하나로 프로바이더 관리, OAuth 로그인, 모델 선택, 요청 로그 확인까지 가능합니다.
-- **깔끔한 종료, 잔여물 제로.** `ocx stop`(또는 대시보드의 Stop 버튼)을 누르면 프록시가 종료되고, 백그라운드 서비스가 설치돼 있으면 함께 내려가며, Codex 설정이 원본으로 복원됩니다. 이후 `codex` 명령은 opencodex 없이 원래대로 동작합니다.
+- **어떤 LLM이든 Codex에서.** 5개의 프로토콜 adapter가 Anthropic Messages, Google Gemini, Azure, OpenAI Responses passthrough, 그리고 모든 OpenAI 호환 Chat Completions 엔드포인트를 커버합니다 — 즉 기본 제공 **40개 이상의 프로바이더**입니다.
+- **ChatGPT 계정을 안전하게 풀링.** 기존 Codex 스레드는 한 계정에 유지하면서, 새 세션은 쿼터 갱신과 비-PII 요청 라벨과 함께 풀에서 사용량이 낮은 계정을 자동 선택할 수 있습니다.
+- **한 번 로그인하면 API 키는 생략.** xAI, Anthropic, Kimi는 OAuth를 지원하므로 기존 계정으로 인증할 수 있고 토큰은 자동 갱신됩니다. 또는 `codex login`을 forward 하거나, API 키를 붙여넣거나, `${ENV_VAR}` 참조를 쓸 수 있습니다 — 선택은 자유입니다.
+- **Codex가 동작하는 모든 곳에서.** Codex CLI, TUI, App, SDK에 자동으로 주입됩니다. 라우팅된 모델이 네이티브 모델처럼 Codex 모델 선택기에 나타납니다.
+- **알맞은 모델에 위임.** 대시보드나 config에서 최대 5개의 라우팅/네이티브 모델을 Codex 서브에이전트 선택기에 노출해, 복잡한 작업은 reasoning 모델로, 빠른 작업은 저렴한 모델로 보낼 수 있습니다.
+- **어떤 모델에도 초능력을.** OpenAI가 아닌 모델도 ChatGPT 로그인 위에서 도는 `gpt-5.4-mini` sidecar로 실제 웹 검색과 이미지 이해를 사용합니다.
+- **무슨 일이 일어나는지 보이게.** 웹 대시보드가 프로바이더, OAuth 상태, 모델 선택, 실시간 요청 로그를 보여줍니다 — 왜 요청이 실패했는지 더는 추측하지 않아도 됩니다.
+- **백그라운드 실행.** 시스템 서비스(launchd / systemd / Task Scheduler)로 설치하면 부팅 시 자동 시작되어 신경 쓸 필요가 없습니다.
+- **깔끔한 종료, 잔여물 제로.** `ocx stop`(또는 대시보드의 Stop 버튼)은 프록시를 종료하고, 설치된 백그라운드 서비스를 멈추며, Codex를 원래 설정으로 복원합니다. 이후 `codex`는 잔여 설정이나 좀비 프로세스 없이 이전과 똑같이 동작합니다.
 
 ## 프로바이더 및 adapter
 
@@ -113,11 +175,13 @@ codex -m "xai/grok-4"                  "이 PR을 리뷰해 줘"
 | xAI Grok | `openai-chat` | oauth / key |
 | Kimi (Moonshot) | `openai-chat` | oauth / key |
 | Google Gemini | `google` | key |
-| Azure OpenAI | `azure` | key |
+| Azure OpenAI | `azure-openai` | key |
 | Ollama Cloud + 17개 프로바이더 카탈로그 | `openai-chat` | key |
 | Ollama / vLLM / LM Studio (로컬) | `openai-chat` | key (보통 비워둠) |
 | 모든 OpenAI 호환 엔드포인트 | `openai-chat` | key |
 
+그 외에 DeepSeek, Groq, OpenRouter, Together, Fireworks, Cerebras, Mistral, Hugging Face, NVIDIA NIM, MiniMax, Qwen Portal 등이 있습니다. 전체 목록은 `ocx init` 또는 [프로바이더 문서](https://lidge-jun.github.io/opencodex/ko/reference/configuration/)에서 확인하세요.
+
 ## CLI
 
 ```bash
@@ -194,15 +258,39 @@ opencodex는 `config.json.invalid-<timestamp>`로 백업하고 경고를 출력
 }
 ```
 
-로컬에서 Ollama나 LM Studio를 실행 중이라면 이렇게 추가하세요:
+프로바이더 항목은 라우팅 카탈로그 메타데이터도 함께 지정할 수 있습니다. `contextWindow`는 프로바이더
+전체에 적용되는 Codex 노출용 컨텍스트 상한, `modelContextWindows`는 모델별 상한,
+`modelInputModalities`는 `["text"]`나 `["text", "image"]` 같은 모델별 입력 힌트입니다. 이 값들은 라이브
+`/models` 메타데이터를 상한으로 제한할 뿐, 더 작은 라이브 컨텍스트를 늘리지는 않습니다. 전체 필드는
+설정 레퍼런스를 참고하세요.
+
+> **Z.AI 경유 GLM-5.2 1M 컨텍스트:** `openai-chat` adapter에서는 `glm-5.2`와 `glm-5.2[1m]`이 모두
+> 동작합니다 — opencodex가 요청 전에 끝의 `[1m]` 접미사를 제거하기 때문입니다(OpenAI 호환 엔드포인트는
+> 대괄호 id를 거부함, Z.AI 400 code 1211). `[1m]` 접미사는 Claude-Code / Anthropic 엔드포인트 관례이며,
+> 네이티브로 쓰려면 `anthropic` adapter를 Z.AI 코딩 base(`https://api.z.ai/api/coding/paas/v4`)로
+> 향하게 하세요. 1M 컨텍스트 창은 모델명이 아니라 모델 카탈로그(`modelContextWindows`)로 설정합니다.
+
+로컬 모델도 동작합니다. opencodex를 머신에서 실행 중인 OpenAI 호환 서버로 향하게 하세요:
 
 ```json
 {
-  "ollama-local": {
-    "adapter": "openai-chat",
-    "baseUrl": "http://localhost:11434/v1",
-    "apiKey": "",
-    "defaultModel": "llama3.1"
+  "port": 10100,
+  "defaultProvider": "ollama",
+  "providers": {
+    "ollama": {
+      "adapter": "openai-chat",
+      "baseUrl": "http://localhost:11434/v1",
+      "authMode": "key",
+      "apiKey": "",
+      "defaultModel": "llama3"
+    },
+    "vllm": {
+      "adapter": "openai-chat",
+      "baseUrl": "http://localhost:8000/v1",
+      "authMode": "key",
+      "apiKey": "",
+      "defaultModel": "Qwen/Qwen3-32B"
+    }
   }
 }
 ```
@@ -229,6 +317,19 @@ x-opencodex-api-key: your-secret-token
 
 토큰은 타이밍 공격 방지를 위해 상수 시간으로 비교됩니다.
 
+opencodex는 Codex resume 히스토리를 자동으로 remap해, 오래된 OpenAI 채팅과 opencodex가 만든 프로젝트
+스레드가 프록시 활성 동안 Codex App에 계속 보이도록 합니다. 원본 provider/source 메타데이터는
+`~/.opencodex/codex-history-backup.json`에 기록됩니다. `ocx stop` / `ocx restore`는 백업된 OpenAI 행을
+OpenAI로 복원하고, 남은 opencodex 유저 스레드도 OpenAI로 eject 하여 네이티브 Codex가 `config.toml`에
+더 이상 존재하지 않는 provider의 스레드를 resume 하려다 실패하지 않게 합니다.
+
+백업 지원이 생기기 전의 옛 개발 빌드에서 `syncResumeHistory`가 이미 히스토리를 remap 했다면, 명시적
+복구 명령을 실행할 수 있습니다:
+
+```bash
+ocx recover-history --legacy-openai
+```
+
 모든 필드에 대한 자세한 내용은 **[설정 레퍼런스](https://lidge-jun.github.io/opencodex/ko/reference/configuration/)** 를 참고하세요.
 
 ## 문서
@@ -244,18 +345,17 @@ x-opencodex-api-key: your-secret-token
 git clone https://github.com/lidge-jun/opencodex.git
 cd opencodex
 bun install
-bun run dev          # dev 모드로 프록시 시작
+bun run dev:proxy    # dev 모드로 프록시 API 시작
+bun run dev:gui      # 다른 터미널에서 대시보드 dev 서버 시작
 bun x tsc --noEmit   # 타입 체크
 ```
 
-`bun run dev`는 프록시 API(`/healthz`, `/v1/responses`, `/api/*`)만 시작합니다. 패키징된
-대시보드 `/`를 함께 서빙하지 않습니다. 대시보드는 설치된 `ocx gui`를 쓰거나, 프론트엔드를
-수정할 때는 별도로 실행하세요:
+`bun run dev`는 호환성을 위해 `bun run dev:proxy`의 별칭으로 남아 있습니다. 소스 체크아웃에서 프록시
+API는 `/healthz`, `/v1/responses`, `/api/*`를 노출하며, `GET /`는 `bun run build:gui`가 `gui/dist`를
+생성한 뒤에만 패키징된 대시보드를 서빙합니다. 대시보드를 수정할 때는 프론트엔드를 별도로 실행하세요:
 
 ```bash
-cd gui
-bun install
-bun dev
+bun run dev:gui
 ```
 
 **[기여하기](https://lidge-jun.github.io/opencodex/ko/contributing/)** 를 참고하세요.

package/README.md

@@ -1,6 +1,12 @@
 <h3 align="center">make codex open!</h3>
 <p align="center"><code>npm install -g @bitkyc08/opencodex</code> · <code>ocx start</code> · <b>localhost:10100</b></p>
 
+<p align="center">
+  <a href="https://www.npmjs.com/package/@bitkyc08/opencodex"><img src="https://img.shields.io/npm/v/@bitkyc08/opencodex?color=cb3837&label=npm&logo=npm" alt="npm version"></a>
+  <a href="https://github.com/lidge-jun/opencodex/blob/main/LICENSE"><img src="https://img.shields.io/npm/l/@bitkyc08/opencodex?color=blue" alt="license"></a>
+  <img src="https://img.shields.io/node/v/@bitkyc08/opencodex?logo=node.js&label=node" alt="node version">
+</p>
+
 <p align="center">
   <img src="assets/banner.png" alt="opencodex — Universal provider proxy for Codex, use any LLM" width="820">
 </p>

package/README.zh-CN.md

@@ -1,3 +1,12 @@
+<h3 align="center">make codex open!</h3>
+<p align="center"><code>npm install -g @bitkyc08/opencodex</code> · <code>ocx start</code> · <b>localhost:10100</b></p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/@bitkyc08/opencodex"><img src="https://img.shields.io/npm/v/@bitkyc08/opencodex?color=cb3837&label=npm&logo=npm" alt="npm version"></a>
+  <a href="https://github.com/lidge-jun/opencodex/blob/main/LICENSE"><img src="https://img.shields.io/npm/l/@bitkyc08/opencodex?color=blue" alt="license"></a>
+  <img src="https://img.shields.io/node/v/@bitkyc08/opencodex?logo=node.js&label=node" alt="node version">
+</p>
+
 <p align="center">
   <img src="assets/banner.png" alt="opencodex — 让 Codex 接入任意 LLM" width="820">
 </p>
@@ -10,7 +19,13 @@
   <img src="assets/architecture.png" alt="opencodex 架构 — Codex CLI 通过 opencodex 代理路由到任意 LLM 提供商" width="820">
 </p>
 
-Codex 只认 Responses API（`/v1/responses`）。opencodex 做的事情很简单：架在 Codex 和你的 LLM provider 中间，把协议实时翻译过去——streaming、tool 调用、reasoning、图片，全都覆盖，双向通信。
+在 Codex 中使用 Claude、Gemini、Grok、GLM、DeepSeek、Kimi、Qwen、Ollama 或任意其他 LLM —— 无需等待 OpenAI 添加支持。
+
+opencodex 是一个轻量级本地代理，把 Codex 的 Responses API 翻译成你的 provider 所讲的协议。streaming、tool 调用、reasoning token、图片 —— 全部双向工作。
+
+它还能为 Codex 认证管理一个 **ChatGPT 账户池**。添加多个 ChatGPT / Codex 账户，在仪表盘中刷新它们的
+5 小时 / 每周 / 30 天配额，并让新会话自动路由到使用量最低的健康账户。现有 Codex 线程会固定在启动它的
+账户上，因此长时间的 SSH、tmux 或移动端连接的会话不会在对话中途切换账户。
 
 ```
 Codex CLI / App / SDK ──/v1/responses──▶ opencodex ──▶ Any provider
@@ -19,6 +34,21 @@ Codex CLI / App / SDK ──/v1/responses──▶ opencodex ──▶ Any provi
               OpenRouter · Azure · DeepSeek · GLM · …and OpenAI itself
 ```
 
+```mermaid
+flowchart LR
+  codex[Codex 会话<br/>CLI, App, SSH, 移动端] --> proxy[opencodex]
+  proxy --> existing{已有线程?}
+  existing -->|是| pinned[保持同一<br/>ChatGPT 账户]
+  existing -->|新会话| quota[刷新配额<br/>5h, 每周, 30d]
+  quota --> pick[选择使用量最低<br/>的健康账户]
+  pick --> upstream[ChatGPT / Codex 后端]
+  pinned --> upstream
+  upstream --> outcomes[配额 / 认证结果]
+  outcomes -->|429| cooldown[冷却 + failover]
+  outcomes -->|401 / 403| reauth[标记需重新认证]
+  cooldown --> quota
+```
+
 ## 支持平台
 
 | 操作系统 | 状态 | 服务管理 |
@@ -60,41 +90,74 @@ npm install -g @bitkyc08/opencodex   # 不要加 --ignore-scripts、--omit=optio
 
 ## 亮点
 
-- **一个代理，20+ provider。** Anthropic、Google、xAI、Kimi、Ollama Cloud、Groq、Azure、DeepSeek、OpenRouter……装一次就全通了。
-- **5 种 adapter 覆盖一切。** Anthropic Messages、Google Gemini、Azure、OpenAI Responses 直通，以及**所有 OpenAI 兼容 Chat Completions** 端点——不管你用什么 LLM，总有一个 adapter 能接上。
-- **三种认证方式，随你挑。** OAuth 登录（xAI / Anthropic / Kimi，token 自动刷新）、转发 `codex login`、或直接粘贴 API key（支持 `${ENV_VARS}`）。内置 18 家 provider 的 API key 目录（含 **Ollama Cloud**）。
-- **即插即用 Codex 全家桶。** 自动向 `~/.codex/config.toml` 注入 `[model_providers.opencodex]`，并写入共享模型目录——路由模型直接出现在 Codex 的模型选择器里，CLI、TUI、App、SDK 全部适用。
-- **Subagent 控制。** 在 `subagentModels` 或 Web 仪表盘中，把最多 5 个路由/原生模型置顶到 Codex 的 `spawn_agent` 选择器。
-- **Sidecar 能力加持。** 非 OpenAI 模型也能拥有真正的**网页搜索**和**图片理解**——通过你的 ChatGPT 登录借用一个 `gpt-5.4-mini` 来实现。
-- **Web 仪表盘。** 管理 provider、OAuth 登录、模型选择、请求日志，都在浏览器里完成。
-- **HTTP/SSE 为默认，WebSocket 按需开启。** 只有显式设置 `"websockets": true` 时，代理才会广告 `supports_websockets`。
-- **干净退出，零残留。** `ocx stop`（或仪表盘的 Stop 按钮）会关闭代理、停止后台服务（如果有的话）、并将 Codex 恢复为原始配置。之后 `codex` 命令就像从未安装过 opencodex 一样正常工作。
+- **在 Codex 中使用任意 LLM。** 5 种协议 adapter 覆盖 Anthropic Messages、Google Gemini、Azure、OpenAI Responses 直通，以及所有 OpenAI 兼容 Chat Completions 端点 —— 即开箱即用的 **40+ provider**。
+- **安全地池化 ChatGPT 账户。** 现有 Codex 线程保持在一个账户上，而新会话可以从池中自动挑选使用量更低的账户，并带有配额刷新和非 PII 请求标签。
+- **登录一次，免填 API key。** xAI、Anthropic、Kimi 支持 OAuth，可用现有账户认证，token 自动刷新。也可以转发 `codex login`、粘贴 API key，或使用 `${ENV_VAR}` 引用 —— 随你选择。
+- **Codex 在哪里能用，它就在哪里能用。** 自动注入 Codex CLI、TUI、App 和 SDK。路由模型像原生模型一样出现在 Codex 的模型选择器里。
+- **委派给合适的模型。** 在仪表盘或 config 中把最多 5 个路由/原生模型放进 Codex 的 subagent 选择器 —— 复杂任务交给 reasoning 模型，快速任务交给便宜模型。
+- **给任意模型超能力。** 非 OpenAI 模型也能通过你的 ChatGPT 登录上运行的 `gpt-5.4-mini` sidecar 获得真正的网页搜索和图片理解。
+- **看清正在发生什么。** Web 仪表盘展示 provider、OAuth 状态、模型选择和实时请求日志 —— 不必再猜测请求为何失败。
+- **后台运行。** 安装为系统服务（launchd / systemd / Task Scheduler）后开机自启，无需操心。
+- **干净退出，零残留。** `ocx stop`（或仪表盘的 Stop 按钮）会关闭代理、停止已安装的后台服务，并将 Codex 恢复为原始配置。之后 `codex` 就像从未安装过 opencodex 一样工作 —— 无残留配置，无僵尸进程。
 
 ## 添加 Provider
 
 最简单的方式：用 Web 仪表盘。
 
 ```bash
-ocx gui          # 在浏览器中打开 localhost:10100
+ocx gui
 ```
 
-仪表盘提供 20+ 内置 provider 模板（Anthropic、Google、xAI、Kimi、Ollama Cloud、Groq、DeepSeek、OpenRouter 等等）。选一个，填入 API key 或用 OAuth 登录，保存即可。opencodex 会自动发现该 provider 支持的模型，并同步到 Codex 的模型选择器中。
+这会打开 `http://localhost:10100` 仪表盘。在这里：
+
+1. 点击 **"Add Provider"**。
+2. 从 **40+ 内置 provider** 中选择，或输入自定义的 OpenAI 兼容端点。
+3. 粘贴 API key（Anthropic、xAI、Kimi 也可用 OAuth 登录）。
+4. 模型会从 provider 的 `/v1/models` 端点**自动发现**。
 
-如果你更习惯手动配置，直接编辑 `~/.opencodex/config.json`，在 `providers` 对象中添加一项即可。详见下方[配置](#配置)章节。
+新 provider 立即可用，无需重启。
+
+你也可以通过 `ocx init`（交互式 CLI）或直接编辑 `~/.opencodex/config.json` 来添加 provider。
 
 ## 模型路由
 
 通过 `provider/model` 格式指定路由模型，在 Codex 中直接使用：
 
 ```bash
-codex -m "anthropic/claude-opus-4-8"   "解释这个 stack trace"
-codex -m "google/gemini-2.5-pro"       "重构这段代码"
-codex -m "xai/grok-4"                  "写一个 SQL migration"
-codex -m "ollama-cloud/glm-5.2"        "生成单元测试"
-codex -m "deepseek/deepseek-r1"        "分析这个性能瓶颈"
+# 通过 Anthropic 使用 Claude Opus
+codex -m "anthropic/claude-opus-4-8" "解释这个 stack trace"
+
+# 通过 Google 使用 Gemini
+codex -m "google/gemini-3-pro" "为 auth.ts 写单元测试"
+
+# 通过 Ollama Cloud 使用 GLM
+codex -m "ollama-cloud/glm-5.2" "写一个 SQL migration"
+
+# 通过 Ollama 使用本地模型
+codex -m "ollama/llama3" "重构这个函数"
 ```
 
-不指定 provider 前缀时，Codex 使用你配置的 `defaultProvider` 和 `defaultModel`。
+省略 `provider/` 前缀时，opencodex 会路由到默认 provider，或根据模型名模式自动匹配（例如 `claude-*`
+路由到 Anthropic，`gpt-*` 路由到 OpenAI）。
+
+路由模型也会出现在 **Codex App** 模型选择器中，并带有按模型的 reasoning effort 控制：
+
+<p align="center">
+  <img src="assets/codex-app-picker.png" alt="Codex App 展示 opencodex 路由模型及 reasoning effort 选择器" width="480">
+</p>
+
+## ChatGPT 账户池
+
+打开仪表盘中的 **Codex Auth** 来添加池账户，并选择由哪个账户处理下一个 Codex 会话。
+opencodex 保持两种独立行为：
+
+- **现有会话保持 affinity。** 线程 id 绑定到所选账户并在后续轮次复用，因此长请求或移动/SSH 连接的会话
+  会继续使用同一账户。
+- **新会话可自动路由。** 启用自动切换后，opencodex 比较 5 小时、每周、30 天使用量中最热的配额窗口，
+  当活跃账户越过阈值时，为新会话挑选使用量更低的合格账户。
+- **内置配额查询。** 仪表盘可一键刷新所有账户配额，请求日志用非 PII 的账户序号标记池流量。
+- **失败即 fail-closed。** token 失败会标记需重新认证，而不是悄悄回退到另一个凭证；429 配额响应会让账户
+  进入冷却，并可将后续工作 failover 到另一个合格的池账户。
 
 ## Provider 与 adapter
 
@@ -107,11 +170,13 @@ codex -m "deepseek/deepseek-r1"        "分析这个性能瓶颈"
 | xAI Grok | `openai-chat` | oauth / key |
 | Kimi（Moonshot） | `openai-chat` | oauth / key |
 | Google Gemini | `google` | key |
-| Azure OpenAI | `azure` | key |
+| Azure OpenAI | `azure-openai` | key |
 | Ollama Cloud + 17 家 provider 目录 | `openai-chat` | key |
 | Ollama / vLLM / LM Studio（本地） | `openai-chat` | key（通常留空） |
 | 任意 OpenAI 兼容端点 | `openai-chat` | key |
 
+此外还有 DeepSeek、Groq、OpenRouter、Together、Fireworks、Cerebras、Mistral、Hugging Face、NVIDIA NIM、MiniMax、Qwen Portal 等等。完整列表可通过 `ocx init` 查看，或参阅 [provider 文档](https://lidge-jun.github.io/opencodex/zh-cn/reference/configuration/)。
+
 ## CLI
 
 ```bash
@@ -119,6 +184,8 @@ ocx init                       # 交互式初始化
 ocx start [--port 10100]       # 启动代理
 ocx stop                       # 停止并恢复原生 Codex 配置
 ocx restore                    # 仅恢复，不停止（别名：ocx eject）
+ocx uninstall                  # 移除 service/shim/config 并恢复原生 Codex
+ocx ensure                     # 按需启动 + 刷新 Codex config/cache
 ocx sync                       # 刷新模型列表 + 重新注入 Codex
 ocx status                     # 查看代理是否在运行
 ocx login <xai|anthropic|kimi> # OAuth 登录
@@ -142,6 +209,18 @@ opencodex 提供两种自动启动代理的方式：
 | **移除** | `ocx service uninstall` | `ocx codex-shim uninstall` |
 
 如需常驻代理，使用 **service**（推荐开发环境）。轻量按需启动使用 **shim**。
+如果配置的代理端口已被占用，`ocx start` 会自动选择另一个空闲本地端口并更新 Codex 使用它。
+
+### 卸载
+
+删除 npm 包之前，先清理本地状态：
+
+```bash
+ocx uninstall
+npm uninstall -g @bitkyc08/opencodex
+```
+
+`ocx uninstall` 会停止代理、移除已安装的 service、移除 Codex shim、恢复原生 Codex config/catalog/history，并删除 `~/.opencodex`。
 
 ## 配置
 
@@ -170,6 +249,17 @@ opencodex 提供两种自动启动代理的方式：
 }
 ```
 
+provider 条目还可以标注路由目录元数据。`contextWindow` 设置 provider 级别、对 Codex 可见的上下文上限，
+`modelContextWindows` 设置按模型的上限，`modelInputModalities` 设置按模型的目录输入提示，例如 `["text"]`
+或 `["text", "image"]`。这些值只会对实时 `/models` 元数据设上限，绝不会抬高更小的实时上下文窗口。完整字段
+参阅配置参考。
+
+> **通过 Z.AI 使用 GLM-5.2 1M 上下文：** 在 `openai-chat` adapter 下，`glm-5.2` 和 `glm-5.2[1m]` 都可用 ——
+> opencodex 会在发送请求前剥离末尾的 `[1m]` 后缀，因为 OpenAI 兼容端点会拒绝带方括号的 id（Z.AI 400 code
+> 1211）。`[1m]` 后缀是 Claude-Code / Anthropic 端点的约定；若要原生使用，请把 `anthropic` adapter 指向
+> Z.AI 的 coding base（`https://api.z.ai/api/coding/paas/v4`）。1M 上下文窗口通过模型目录
+> （`modelContextWindows`）设置，而不是模型名。
+
 **本地 provider 示例（Ollama / vLLM / LM Studio）：**
 
 ```json
@@ -191,6 +281,37 @@ opencodex 提供两种自动启动代理的方式：
 
 WebSocket 传输默认关闭。只有当你希望 Codex 使用 Responses WebSocket 而不是 HTTP/SSE 时，才需要设置 `"websockets": true`。
 
+### 远程访问
+
+默认情况下 opencodex 绑定到 `127.0.0.1`（回环）且无需额外认证。
+如果你设置 `"hostname": "0.0.0.0"` 把代理暴露到局域网，opencodex 会要求一个 bearer token 来同时保护管理
+API（`/api/*`）和数据平面（`/v1/responses`）：
+
+```bash
+export OPENCODEX_API_AUTH_TOKEN="your-secret-token"
+ocx start
+```
+
+绑定到非回环地址时若缺少该环境变量，代理会拒绝启动。若为局域网访问安装后台服务，请在 `ocx service install`
+之前于同一 shell 中导出相同变量，以便服务管理器接收到它。客户端（脚本、远程机器）必须在每个请求中带上 token：
+
+```
+x-opencodex-api-key: your-secret-token
+```
+
+token 以常量时间比较，以防止时序攻击。
+
+opencodex 会自动 remap Codex resume 历史，使旧的 OpenAI 对话和 opencodex 创建的项目线程在代理活动期间仍在
+Codex App 中可见。原始 provider/source 元数据记录在 `~/.opencodex/codex-history-backup.json`。`ocx stop` /
+`ocx restore` 会把备份的 OpenAI 行恢复到 OpenAI，并把剩余的 opencodex 用户线程也 eject 到 OpenAI，这样原生
+Codex 不会尝试 resume 一个其 provider 已不在 `config.toml` 中的线程。
+
+如果你测试过备份支持出现之前的旧开发版本（`syncResumeHistory` 已经 remap 了历史），可以运行显式恢复命令：
+
+```bash
+ocx recover-history --legacy-openai
+```
+
 每个字段的详细说明参阅 **[配置参考](https://lidge-jun.github.io/opencodex/zh-cn/reference/configuration/)**。
 
 ## 文档
@@ -205,17 +326,17 @@ WebSocket 传输默认关闭。只有当你希望 Codex 使用 Responses WebSock
 git clone https://github.com/lidge-jun/opencodex.git
 cd opencodex
 bun install
-bun run dev          # 以开发模式启动代理
+bun run dev:proxy    # 以开发模式启动代理 API
+bun run dev:gui      # 在另一个终端启动仪表盘 dev 服务器
 bun x tsc --noEmit   # 类型检查
 ```
 
-`bun run dev` 只启动代理 API（`/healthz`、`/v1/responses`、`/api/*`）。它不会同时在 `/`
-提供打包后的仪表盘。要打开仪表盘，请使用已安装的 `ocx gui`；如果要开发前端，请单独运行：
+`bun run dev` 作为 `bun run dev:proxy` 的别名保留以兼容旧用法。在源码检出中，代理 API 暴露 `/healthz`、
+`/v1/responses`、`/api/*`；只有在 `bun run build:gui` 生成 `gui/dist` 之后，`GET /` 才会提供打包后的仪表盘。
+开发前端时请单独运行：
 
 ```bash
-cd gui
-bun install
-bun dev
+bun run dev:gui
 ```
 
 参阅 **[贡献指南](https://lidge-jun.github.io/opencodex/zh-cn/contributing/)**。