@bitkyc08/opencodex 2.7.23 → 2.7.24-preview.20260718

package/README.ko.md

@@ -70,6 +70,7 @@ flowchart LR
 
 ```bash
 # 설치 (Bun 런타임이 자동으로 번들됩니다 — Node 18+ 만 있으면 됩니다)
+# 사용자 소유 Node(nvm/fnm)를 권장합니다 — `sudo npm install -g …`는 피하세요
 npm install -g @bitkyc08/opencodex
 
 # 대화형 설정 (config 작성 + Codex 주입 + 자동 시작 shim 설치 선택)
@@ -86,16 +87,25 @@ codex "Write a hello world in Rust"
 ```
 
 <details>
-<summary><b>"bundled Bun runtime is missing" 오류가 나나요?</b></summary>
+<summary><b>"bundled Bun runtime is missing" 오류 / npm이 Bun 설치 스크립트를 차단했나요?</b></summary>
 
 <br/>
 
-opencodex는 Bun 런타임을 의존성으로 번들하고 Node 런처로 실행하므로 Bun을 직접 설치할 필요가 **없습니다**. "bundled Bun runtime is missing" 오류가 보이면 설치 과정에서 lifecycle 스크립트나 optional 의존성이 건너뛰어진 경우입니다. 해당 플래그 없이 다시 설치하세요:
+opencodex는 Bun 런타임을 의존성으로 번들하고 Node 런처로 실행하므로 Bun을 직접 설치할 필요가 **없습니다**. "bundled Bun runtime is missing" 오류가 보이면 설치 과정에서 lifecycle 스크립트(npm이 `allowScripts`로 bun postinstall을 차단한 경우 포함)나 optional 의존성이 건너뛰어진 경우입니다. bun 설치 스크립트를 허용해서 다시 설치하세요:
 
 ```bash
-npm install -g @bitkyc08/opencodex   # --ignore-scripts, --omit=optional 없이
+npm install -g --allow-scripts=bun @bitkyc08/opencodex   # --ignore-scripts, --omit=optional 없이
+
+# 처음에 sudo로 설치했다면 sudo를 유지하세요:
+sudo npm install -g --allow-scripts=bun @bitkyc08/opencodex
 ```
 
+npm 경고가 제안하는 축약 명령에는 패키지 이름이 빠져 있어 현재 디렉터리를
+재설치하게 됩니다. 항상 `@bitkyc08/opencodex`를 명시하세요.
+
+sudo로 루트 소유 prefix에 설치했다면 위의 sudo 재설치가 해당 prefix를 풀어주지만,
+가능할 때 사용자 소유 Node(nvm, fnm, 사용자 npm prefix)로 옮기는 편이 좋습니다.
+
 </details>
 
 ## 프로바이더 추가하기
@@ -157,7 +167,27 @@ routing/catalog metadata를 준비해 둡니다.
   <img src="assets/codex-app-picker.png" alt="opencodex 라우팅 모델을 reasoning effort 선택기와 함께 보여주는 Codex App" width="480">
 </p>
 
-## ChatGPT 계정 풀
+## OpenAI 프로바이더 계정 모드
+
+| 프로바이더 ID | 경로 | 자격증명 | 동작 |
+|---|---|---|---|
+| `openai` | Codex 로그인 | 메인 + 추가 Codex 계정 | 기본 Pool, 선택 가능한 Direct 모드 |
+| `openai-apikey` | OpenAI API | API key/key pool | Codex 계정 라우팅 없음 |
+
+- Pool은 메인 로그인과 추가 계정을 포함하며 affinity·쿼터·cooldown·failover를 적용합니다.
+- Direct는 풀 상태를 건드리지 않고 현재 caller/메인 로그인 bearer만 사용합니다.
+- 새 설치와 모드가 없는 config는 Pool이 기본입니다. 대시보드 **Providers**에서 모드를 바꿔도
+  `gpt-5.6-sol` 같은 bare 모델 id는 그대로입니다.
+- `openai-apikey/gpt-5.6-sol`은 API를 선택하며 Codex 로그인과 API 자격증명 사이에는 fallback이 없습니다.
+- 현재 marker는 `openaiProviderTierVersion: 2`이고 원본은
+  `~/.opencodex/config.json.pre-openai-tiers-v2.bak`에 보존됩니다.
+  복원: `cp ~/.opencodex/config.json.pre-openai-tiers-v2.bak ~/.opencodex/config.json`
+- 이전 v1 3-provider config는 단일 `openai` 행으로 자동 이관됩니다.
+- API 티어의 GPT-5.6 metadata는 context 1,050,000 / max input 922,000입니다.
+  `gpt-5.6-sol-pro`, `terra-pro`, `luna-pro`는 공개 virtual id를 유지하면서 wire에서는 base id와
+  `reasoning.mode: "pro"`로 전송됩니다.
+
+### Pool 계정 동작
 
 대시보드의 **Codex Auth**를 열어 풀 계정을 추가하고, 다음 Codex 세션을 어느 계정이 처리할지 고르세요.
 opencodex는 두 가지 동작을 분리해서 유지합니다:
@@ -178,8 +208,8 @@ opencodex는 두 가지 동작을 분리해서 유지합니다:
 - **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 모델로, 빠른 작업은 저렴한 모델로 보낼 수 있습니다. v2 멀티에이전트 표면(GPT-5.6 Sol/Terra)에서는 프록시가 간결한 위임 가이드를 주입합니다. 선호 서브에이전트 모델·effort(`injectionModel` / `injectionEffort`), 노출된 모델 로스터와 각 모델이 지원하는 effort 사다리, 그리고 크로스모델 `spawn_agent` 호출이 실제로 먹히게 하는 `fork_turns` 규칙까지. 문구를 직접 쓰고 싶다면 `injectionPrompt`에 `{{model}}` / `{{effort}}` / `{{roster}}` 플레이스홀더를 넣으면 됩니다.
-- **프리뷰 게이트된 OpenAI rollout에 대비.** GPT-5.6 Sol/Terra/Luna 항목은 upstream 스펙 그대로(Sol/Terra는 `ultra`까지, Luna는 `max`까지; 372k usable context) ChatGPT passthrough, OpenAI API key, OpenRouter route에 준비되어 있습니다.
+- **알맞은 모델에 위임.** 대시보드나 config에서 최대 5개의 라우팅/네이티브 모델을 Codex 서브에이전트 선택기에 노출해, 복잡한 작업은 reasoning 모델로, 빠른 작업은 저렴한 모델로 보낼 수 있습니다. v2 멀티에이전트 표면(GPT-5.6 Sol/Terra)에서는 프록시가 간결한 위임 가이드를 주입합니다. 선호 서브에이전트 모델·effort(`injectionModel` / `injectionEffort`), 노출된 모델 로스터와 각 모델이 지원하는 effort 사다리, 그리고 크로스모델 `spawn_agent` 오버라이드를 적용하는 `fork_turns` 규칙까지. 알려진 제한: 네이티브 부모가 라우팅 자식을 스폰하면 작업 본문이 백엔드 암호화 상태로 도착해 유실될 수 있습니다([#92](https://github.com/lidge-jun/opencodex/issues/92)) — 안정적인 크로스 프로바이더 위임에는 v1 표면을 쓰세요. 문구를 직접 쓰고 싶다면 `injectionPrompt`에 `{{model}}` / `{{effort}}` / `{{roster}}` 플레이스홀더를 넣으면 됩니다.
+- **프리뷰 게이트된 OpenAI rollout에 대비.** GPT-5.6 Sol/Terra/Luna의 effort 사다리를 보존합니다. Direct/Multi는 372k Codex 계약을, OpenAI API와 OpenRouter는 1.05M metadata를 사용합니다.
 - **어떤 모델에도 초능력을.** OpenAI가 아닌 모델도 ChatGPT 로그인 위에서 도는 `gpt-5.4-mini` sidecar로 실제 웹 검색과 이미지 이해를 사용합니다.
 - **이미지를 네이티브로 생성.** Codex의 독립형 `image_gen` 도구는 생성할 때 `POST /v1/images/generations`, 편집할 때 `POST /v1/images/edits`를 사용합니다. Responses의 hosted `image_generation` 도구와는 별개입니다.
 - **무슨 일이 일어나는지 보이게.** 웹 대시보드가 프로바이더, OAuth 상태, 모델 선택, upstream이 보고한 cached/cache-write 토큰 수를 포함한 실시간 요청 로그를 보여줍니다 — 왜 요청이 실패했는지 더는 추측하지 않아도 됩니다.
@@ -285,7 +315,7 @@ opencodex는 `config.json.invalid-<timestamp>`로 백업하고 경고를 출력
 전체에 적용되는 Codex 노출용 컨텍스트 상한, `modelContextWindows`는 모델별 상한,
 `modelInputModalities`는 `["text"]`나 `["text", "image"]` 같은 모델별 입력 힌트입니다. 이 값들은 라이브
 `/models` 메타데이터를 상한으로 제한할 뿐, 더 작은 라이브 컨텍스트를 늘리지는 않습니다. 번들된 GPT-5.6
-Sol/Terra/Luna fallback metadata는 OpenAI API key와 OpenRouter catalog 항목에 372,000 토큰 usable
+Sol/Terra/Luna fallback metadata는 OpenAI API key와 OpenRouter catalog 항목에 1,050,000 토큰
 context window를 사용하며, upstream preview access를 우회하지 않습니다. 전체 필드는 설정 레퍼런스를
 참고하세요.
 

package/README.md

@@ -70,6 +70,7 @@ Requires [Node](https://nodejs.org) 18+. The Bun runtime is bundled automaticall
 
 ```bash
 # Install (bundles the Bun runtime automatically — only Node 18+ required)
+# Prefer a user-owned Node (nvm/fnm) — avoid `sudo npm install -g …`
 npm install -g @bitkyc08/opencodex
 
 # Interactive setup (writes config, injects into Codex, and offers autostart shim install)
@@ -86,19 +87,31 @@ codex "Write a hello world in Rust"
 ```
 
 <details>
-<summary><b>"bundled Bun runtime is missing" error?</b></summary>
+<summary><b>"bundled Bun runtime is missing" / npm blocked Bun install scripts?</b></summary>
 
 <br/>
 
 opencodex bundles the Bun runtime as a dependency and runs it via a Node
 launcher, so you do **not** need to install Bun yourself. If you see a
 "bundled Bun runtime is missing" error, the install skipped lifecycle scripts
-or optional dependencies. Reinstall without those flags:
+(including npm blocking bun's postinstall under `allowScripts`) or optional
+dependencies. Reinstall without those flags, allowing bun's install script:
 
 ```bash
-npm install -g @bitkyc08/opencodex   # no --ignore-scripts, no --omit=optional
+npm install -g --allow-scripts=bun @bitkyc08/opencodex   # no --ignore-scripts, no --omit=optional
+
+# if the original install used sudo, keep using sudo:
+sudo npm install -g --allow-scripts=bun @bitkyc08/opencodex
 ```
 
+npm's own warning suggests an abbreviated command without the package name —
+that would reinstall the current directory, so always pass
+`@bitkyc08/opencodex` explicitly.
+
+If you installed with `sudo` into a root-owned prefix, the sudo reinstall above
+unblocks that prefix — but prefer migrating to a user-owned Node (nvm, fnm, or
+a user npm prefix) when you can.
+
 </details>
 
 ## Add a provider
@@ -158,10 +171,38 @@ routing and catalog metadata for accounts and providers that can serve them.
   <img src="assets/codex-app-picker.png" alt="Codex App showing opencodex routed models with reasoning effort picker" width="480">
 </p>
 
-## ChatGPT account pool
-
-Open **Codex Auth** in the dashboard to add pool accounts and choose which account should handle the
-next Codex session. opencodex keeps two separate behaviors:
+## OpenAI provider account modes
+
+| Provider ID | Route | Credential | Behavior |
+|---|---|---|---|
+| `openai` | Codex login | Main + added Codex accounts | Pool by default; optional Direct mode |
+| `openai-apikey` | OpenAI API | API key/key pool | No Codex account routing |
+
+- Pool includes the main Codex login and added accounts, with affinity, quota, cooldown, and failover.
+- Direct short-circuits pool state and uses only the current caller/main-login bearer.
+- Fresh installs and configs with no persisted mode default to Pool. Change the mode on the
+  dashboard's **Providers** page; model ids stay bare in either mode.
+- The legacy public provider id `chatgpt` is hidden after migration. The original config is retained
+  once at `~/.opencodex/config.json.pre-openai-tiers-v2.bak`; restore it with
+  `cp ~/.opencodex/config.json.pre-openai-tiers-v2.bak ~/.opencodex/config.json`.
+- Current configs use `openaiProviderTierVersion: 2`. Earlier v1 three-provider configs migrate
+  automatically into the single `openai` row.
+- The API tier includes Pro virtual models (`gpt-5.6-sol-pro`, `gpt-5.6-terra-pro`,
+  `gpt-5.6-luna-pro`). At the wire level, each rewrites to its base model with
+  `reasoning.mode: "pro"`.
+- Its catalog is fixed to eight ids: `gpt-5.5`, `gpt-5.6`, Sol/Terra/Luna, and the three
+  corresponding Pro virtual ids. There is no generic `gpt-5.6-pro` alias.
+- Compact requests keep the selected tier but send the base model without a reasoning object.
+- Official API metadata is 1,050,000 context tokens and 922,000 max input tokens.
+
+Use `gpt-5.6-sol` for the configured `openai` account mode and
+`openai-apikey/gpt-5.6-sol` for the API key. Codex-login and API credentials never fall through to
+one another.
+
+### Pool account behavior
+
+Open **Codex Auth** in the dashboard to add accounts and choose which account should handle the
+next Codex session. opencodex keeps these behaviors:
 
 - **Existing sessions keep affinity.** A thread id is bound to the selected account and reused on
   later turns, so a long request or a mobile/SSH-attached session keeps using the same account.
@@ -183,8 +224,8 @@ next Codex session. opencodex keeps two separate behaviors:
 - **Log in once, skip the API key.** OAuth support for xAI, Anthropic, and Kimi means you can authenticate with your existing account. Tokens auto-refresh. Or forward your `codex login`, paste an API key, or use `${ENV_VAR}` references — your call.
 - **Works everywhere Codex does.** Injects into Codex CLI, TUI, App, and SDK automatically. Routed models show up in Codex's model picker just like native ones.
 - **History-safe injection.** On local installs the proxy points Codex's own built-in `openai` provider at itself via a single `openai_base_url` line — new threads keep their native provider tag, so ongoing chat history is never remapped and an unclean shutdown can't hide it. (Threads re-tagged by older versions are migrated back once on the first start; remote/LAN binds use a dedicated provider entry instead, since they need an API-key header.)
-- **Delegate to the right model.** Feature up to five routed or native models in Codex's subagent picker from the dashboard or config — route complex tasks to a reasoning model, fast tasks to a cheap one. On the v2 multi-agent surface (GPT-5.6 Sol/Terra) the proxy injects compact delegation guidance: a preferred sub-agent model and effort (`injectionModel` / `injectionEffort`), the featured-model roster with the effort ladder each supports, and the `fork_turns` rules that make cross-model `spawn_agent` calls actually stick. Want your own wording? Set `injectionPrompt` with `{{model}}` / `{{effort}}` / `{{roster}}` placeholders.
-- **Prepare for preview-gated OpenAI rollouts.** GPT-5.6 Sol/Terra/Luna entries ship with the exact upstream spec (Sol/Terra reach `ultra`, Luna caps at `max`; 372k usable context) for ChatGPT passthrough, OpenAI API key, and OpenRouter routes when upstream access is available.
+- **Delegate to the right model.** Feature up to five routed or native models in Codex's subagent picker from the dashboard or config — route complex tasks to a reasoning model, fast tasks to a cheap one. On the v2 multi-agent surface (GPT-5.6 Sol/Terra) the proxy injects compact delegation guidance: a preferred sub-agent model and effort (`injectionModel` / `injectionEffort`), the featured-model roster with the effort ladder each supports, and the `fork_turns` rules that let cross-model `spawn_agent` calls apply their overrides. Known limitation: when a native parent spawns a routed child, the task body can currently arrive backend-encrypted and be lost ([#92](https://github.com/lidge-jun/opencodex/issues/92)) — use the v1 surface for reliable cross-provider delegation. Want your own wording? Set `injectionPrompt` with `{{model}}` / `{{effort}}` / `{{roster}}` placeholders.
+- **Prepare for preview-gated OpenAI rollouts.** GPT-5.6 Sol/Terra/Luna entries preserve the upstream effort ladders. Direct/Multi use the 372k Codex contract; OpenAI API and OpenRouter use 1.05M metadata when upstream access is available.
 - **Give any model superpowers.** Non-OpenAI models get real web search and image understanding via a `gpt-5.4-mini` sidecar over your ChatGPT login.
 - **Generate images natively.** Codex's standalone `image_gen` tool uses `POST /v1/images/generations` for generation and `POST /v1/images/edits` for edits; it is separate from the hosted Responses `image_generation` tool.
 - **See what's happening.** The web dashboard shows providers, OAuth status, model selection, and a live request log, including cached/cache-write token counts when upstream reports them — no more guessing why a request failed.
@@ -302,8 +343,8 @@ Provider entries can also annotate routed catalog metadata. Use `contextWindow`
 Codex-visible context cap, `modelContextWindows` for model-specific caps, and
 `modelInputModalities` for model-specific catalog input hints such as `["text"]` or
 `["text", "image"]`. Context values cap live `/models` metadata; they never raise a smaller live
-context window. The bundled GPT-5.6 Sol/Terra/Luna fallback metadata uses a 372,000-token usable
-context window for OpenAI API key and OpenRouter catalog entries; it does not bypass upstream preview
+context window. The bundled GPT-5.6 Sol/Terra/Luna fallback metadata uses a 1,050,000-token context
+window for OpenAI API key and OpenRouter catalog entries; it does not bypass upstream preview
 access. See the configuration reference for the full field list.
 
 > **GLM-5.2 1M context via Z.AI:** through the `openai-chat` adapter, both `glm-5.2`

package/README.zh-CN.md

@@ -69,6 +69,7 @@ flowchart LR
 
 ```bash
 # 安装（自动打包 Bun 运行时 —— 只需 Node 18+）
+# 推荐使用用户自有的 Node（nvm/fnm）—— 避免 `sudo npm install -g …`
 npm install -g @bitkyc08/opencodex
 
 # 交互式初始化（写入配置 + 注入 Codex）
@@ -82,16 +83,25 @@ codex "Write a hello world in Rust"
 ```
 
 <details>
-<summary><b>遇到 "bundled Bun runtime is missing" 错误？</b></summary>
+<summary><b>遇到 "bundled Bun runtime is missing" 错误 / npm 拦截了 Bun 安装脚本？</b></summary>
 
 <br/>
 
-opencodex 把 Bun 运行时作为依赖打包，并通过 Node 启动器运行，所以你**不需要**自己安装 Bun。如果看到 "bundled Bun runtime is missing" 错误，说明安装时跳过了 lifecycle 脚本或 optional 依赖。请不带这些标志重新安装：
+opencodex 把 Bun 运行时作为依赖打包，并通过 Node 启动器运行，所以你**不需要**自己安装 Bun。如果看到 "bundled Bun runtime is missing" 错误，说明安装时跳过了 lifecycle 脚本（包括 npm 通过 `allowScripts` 拦截 bun postinstall 的情况）或 optional 依赖。请允许 bun 安装脚本后重新安装：
 
 ```bash
-npm install -g @bitkyc08/opencodex   # 不要加 --ignore-scripts、--omit=optional
+npm install -g --allow-scripts=bun @bitkyc08/opencodex   # 不要加 --ignore-scripts、--omit=optional
+
+# 如果最初是用 sudo 安装的，请继续使用 sudo：
+sudo npm install -g --allow-scripts=bun @bitkyc08/opencodex
 ```
 
+npm 警告里给出的缩写命令缺少包名，会把当前目录重新安装进去，
+请始终显式写上 `@bitkyc08/opencodex`。
+
+如果之前用 sudo 安装到了 root 前缀，上面的 sudo 重装可以解除该前缀的拦截 ——
+但建议在条件允许时迁移到用户自有的 Node（nvm、fnm 或用户 npm prefix）。
+
 </details>
 
 ## 亮点
@@ -101,8 +111,8 @@ npm install -g @bitkyc08/opencodex   # 不要加 --ignore-scripts、--omit=optio
 - **安全地池化 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 模型，快速任务交给便宜模型。在 v2 多智能体表面（GPT-5.6 Sol/Terra）上，代理会注入精简的委派指引：首选子智能体模型与 effort（`injectionModel` / `injectionEffort`）、featured 模型清单及各自支持的 effort 阶梯，以及让跨模型 `spawn_agent` 调用真正生效的 `fork_turns` 规则。想自定义文案，可在 `injectionPrompt` 中使用 `{{model}}` / `{{effort}}` / `{{roster}}` 占位符。
-- **为 preview-gated OpenAI rollout 做好准备。** GPT-5.6 Sol/Terra/Luna 条目采用与 upstream 完全一致的规格（Sol/Terra 到 `ultra`，Luna 到 `max`；372k 可用上下文），覆盖 ChatGPT passthrough、OpenAI API key 和 OpenRouter 路由。
+- **委派给合适的模型。** 在仪表盘或 config 中把最多 5 个路由/原生模型放进 Codex 的 subagent 选择器 —— 复杂任务交给 reasoning 模型，快速任务交给便宜模型。在 v2 多智能体表面（GPT-5.6 Sol/Terra）上，代理会注入精简的委派指引：首选子智能体模型与 effort（`injectionModel` / `injectionEffort`）、featured 模型清单及各自支持的 effort 阶梯，以及让跨模型 `spawn_agent` 覆盖得以应用的 `fork_turns` 规则。已知限制：原生父代理 spawn 路由子代理时，任务正文可能以后端加密形式到达而丢失（[#92](https://github.com/lidge-jun/opencodex/issues/92)）—— 需要可靠的跨 provider 委派请使用 v1 表面。想自定义文案，可在 `injectionPrompt` 中使用 `{{model}}` / `{{effort}}` / `{{roster}}` 占位符。
+- **为 preview-gated OpenAI rollout 做好准备。** GPT-5.6 Sol/Terra/Luna 保留 upstream effort 阶梯。Direct/Multi 使用 372k Codex 契约，OpenAI API 与 OpenRouter 使用 1.05M 元数据。
 - **给任意模型超能力。** 非 OpenAI 模型也能通过你的 ChatGPT 登录上运行的 `gpt-5.4-mini` sidecar 获得真正的网页搜索和图片理解。
 - **原生生成图片。** Codex 的独立 `image_gen` 工具通过 `POST /v1/images/generations` 生成图片、通过 `POST /v1/images/edits` 编辑图片；它独立于 hosted Responses 的 `image_generation` 工具。
 - **看清正在发生什么。** Web 仪表盘展示 provider、OAuth 状态、模型选择和实时请求日志；当上游返回时，也会包含 cached/cache-write token 计数 —— 不必再猜测请求为何失败。
@@ -166,7 +176,26 @@ preview gate 限制；opencodex 只是准备好你的账户/provider 可访问
   <img src="assets/codex-app-picker.png" alt="Codex App 展示 opencodex 路由模型及 reasoning effort 选择器" width="480">
 </p>
 
-## ChatGPT 账户池
+## OpenAI provider 层级
+
+| Provider ID | 层级 | 凭证 | 行为 |
+|---|---|---|---|
+| `openai` | Codex Direct | 当前 Codex 主登录 | 单账户，不读取或轮换池 |
+| `openai-multi` | Codex 多账户 | 主账户 + 添加的账户 | affinity、配额、冷却、failover |
+| `openai-apikey` | OpenAI API | API key/key pool | 不进行 Codex 账户路由 |
+
+- Codex 主账户始终是 Multi 池的普通成员，不是池外 fallback。
+- 新安装默认使用 Direct（`openai`）。`gpt-5.6-sol` 选择 Direct，
+  `openai-multi/gpt-5.6-sol` 选择 Multi，`openai-apikey/gpt-5.6-sol` 选择 API。
+- 三个层级之间不会因凭证缺失而相互 fallback。
+- 升级时，带池账户的旧配置迁移到 Multi；旧的公开 `chatgpt` provider id 会被隐藏。
+  原配置只备份一次到 `~/.opencodex/config.json.pre-openai-tiers-v1.bak`。恢复命令：
+  `cp ~/.opencodex/config.json.pre-openai-tiers-v1.bak ~/.opencodex/config.json`
+- API 层 GPT-5.6 元数据为 1,050,000 context / 922,000 max input。
+  `gpt-5.6-sol-pro`、`terra-pro`、`luna-pro` 保留公开 virtual id，线上请求改写为 base id 加
+  `reasoning.mode: "pro"`。
+
+### 多账户行为
 
 打开仪表盘中的 **Codex Auth** 来添加池账户，并选择由哪个账户处理下一个 Codex 会话。
 opencodex 保持两种独立行为：
@@ -273,7 +302,7 @@ npm uninstall -g @bitkyc08/opencodex
 provider 条目还可以标注路由目录元数据。`contextWindow` 设置 provider 级别、对 Codex 可见的上下文上限，
 `modelContextWindows` 设置按模型的上限，`modelInputModalities` 设置按模型的目录输入提示，例如 `["text"]`
 或 `["text", "image"]`。这些值只会对实时 `/models` 元数据设上限，绝不会抬高更小的实时上下文窗口。内置
-GPT-5.6 Sol/Terra/Luna fallback 元数据会为 OpenAI API key 和 OpenRouter 目录条目使用 372,000 token 的
+GPT-5.6 Sol/Terra/Luna fallback 元数据会为 OpenAI API key 和 OpenRouter 目录条目使用 1,050,000 token 的
 usable context window；它不会绕过上游 preview access。完整字段参阅配置参考。
 
 > **通过 Z.AI 使用 GLM-5.2 1M 上下文：** 在 `openai-chat` adapter 下，`glm-5.2` 和 `glm-5.2[1m]` 都可用 ——

package/bin/ocx.mjs

@@ -191,9 +191,11 @@ function fail(msg) {
   console.error(
     `opencodex: ${msg}\n` +
       "The bundled Bun runtime could not be prepared. This usually means the\n" +
-      "install skipped lifecycle scripts or optional dependencies. Reinstall with:\n" +
-      "  npm install -g @bitkyc08/opencodex\n" +
-      "(without --ignore-scripts and without --omit=optional / optional=false)"
+      "install skipped lifecycle scripts (e.g. npm blocked bun's postinstall\n" +
+      "under allowScripts) or optional dependencies. Reinstall with:\n" +
+      "  npm install -g --allow-scripts=bun @bitkyc08/opencodex\n" +
+      "(use sudo if the original install used sudo; without --ignore-scripts\n" +
+      "and without --omit=optional / optional=false)"
   );
   process.exit(1);
 }