fix: surface ChatGPT login recovery guidance

Author: gaoguobin

.codex/INSTALL.md

@@ -67,18 +67,18 @@ python -m codex_fast_proxy doctor
 Report the JSON result in the reply. When `"ok": true`, explicitly tell the user:
 
 ```text
-请重启 Codex App 并回到这个对话，或新开 CLI 实例，让它重新扫描 ~/.agents/skills；然后再说“启用 Codex Fast proxy”。
+Restart Codex App and return to this conversation, or open a new CLI process, so Codex can rescan ~/.agents/skills. Then ask Codex to enable Codex Fast proxy.
 ```
 
 Do not claim the skill is available before the restart.
 
 After restarting Codex App or opening a new CLI process, the user can ask:
 
-- `启用 Codex Fast proxy`
-- `启用 Codex Fast proxy 的 ChatGPT 登录兼容模式`
-- `全局开启 Codex Fast proxy 的 Fast 注入`
-- `查看 Codex Fast proxy 状态`
-- `停止 Codex Fast proxy`
+- `Enable Codex Fast proxy`
+- `Prepare Codex Fast proxy for ChatGPT account login`
+- `Enable global Fast injection for Codex Fast proxy`
+- `Show Codex Fast proxy status`
+- `Stop Codex Fast proxy`
 
 Default enable uses `--service-tier-policy auto`. In ChatGPT-login or unclear states this respects
 Codex App/CLI Fast UI choices; in API-key mode it may inject the priority tier when Codex omits

.codex/UNINSTALL.md

@@ -78,17 +78,17 @@ restarting, or keep the proxy enabled if they want ChatGPT-login UI with a third
 When cleanup completed without `restart_required_before_cleanup=true`, explicitly tell the user:
 
 ```text
-请重启 Codex App，或新开 CLI 实例，让它从 skill 列表中移除 codex-fast-proxy。
+Restart Codex App, or open a new CLI process, so Codex removes codex-fast-proxy from the skill list.
 ```
 
 If the block printed `restart_required_before_cleanup=true`, explicitly tell the user:
 
 ```text
-配置已恢复直连，代理暂时保留运行以避免打断当前进程；请重启 Codex App 并回到这个对话，或新开 CLI 实例后再次执行卸载完成清理。
+Codex config has been restored to direct upstream, and the proxy was left running temporarily to avoid interrupting the current process. Restart Codex App and return to this conversation, or open a new CLI process, then run uninstall again to finish cleanup.
 ```
 
 If `direct_upstream_auth_warning` is present, add this before the restart instruction:
 
 ```text
-注意：当前检测到 ChatGPT 登录态。卸载恢复直连后不再经过 proxy 的 upstream auth override；如果继续保持 ChatGPT 登录，第三方 provider 可能收到 ChatGPT token 并返回 401。请先退出 ChatGPT 登录并切回第三方/API-key 认证，或暂时不要卸载、继续保留 proxy。
+Warning: ChatGPT login appears to be active. After uninstall restores direct upstream, requests no longer pass through the proxy upstream auth override. If Codex keeps using ChatGPT auth, the third-party provider may receive a ChatGPT token and return 401. Switch back to API-key/third-party provider auth before restarting, or keep the proxy enabled for ChatGPT-login UI with a third-party provider.
 ```

.codex/UPDATE.md

@@ -57,7 +57,7 @@ Report the install JSON and the final status JSON when the proxy was already ena
 status JSON as the current state. If the skill was newly linked or changed, explicitly tell the user:
 
 ```text
-请重启 Codex App 并回到这个对话，或新开 CLI 实例，让它重新扫描 ~/.agents/skills；然后再说“启用 Codex Fast proxy”。
+Restart Codex App and return to this conversation, or open a new CLI process, so Codex can rescan ~/.agents/skills. Then ask Codex to enable Codex Fast proxy.
 ```
 
 If `install --start` ran during update, it refreshes `~/.codex/hooks.json` and enables Codex `SessionStart` autostart for future App/CLI starts. It also compares the running proxy runtime with the installed code; if the proxy is healthy but stale, explicit `install --start`/`start` may restart the proxy before returning. Use the final `status` output to report `runtime_matches` and `needs_restart`. If `status.needs_restart` is still `true`, tell the user to restart Codex App, open a new CLI process after the old proxy is gone, or run `python -m codex_fast_proxy start` when it is safe to refresh runtime code. Codex may fire `SessionStart` for each new or resumed session; `autostart --quiet` does not restart an already healthy proxy just because runtime code is stale, and it does not log normal no-op checks.

README.md

@@ -9,7 +9,7 @@ It lets Codex App route model requests through a local proxy, keep streaming int
 App's own Fast control when available, and optionally inject `service_tier="priority"` when Codex
 does not send a tier.
 
-[中文](#中文说明) · [Quick Start](#quick-start) · [Common Workflows](#common-workflows) · [Dashboard](#dashboard) · [Safety](#safety) · [Advanced Usage](docs/advanced-usage.md) · [Design Notes](docs/interaction-decisions.md) · [Sponsor](#sponsor)
+[Chinese Guide](docs/README.zh-CN.md) · [Quick Start](#quick-start) · [Common Workflows](#common-workflows) · [Dashboard](#dashboard) · [Safety](#safety) · [Advanced Usage](docs/advanced-usage.md) · [Design Notes](docs/interaction-decisions.md) · [Sponsor](#sponsor)
 
 ![Codex Fast Proxy dashboard](docs/assets/dashboard.png)
 
@@ -159,78 +159,6 @@ Codex plugin distribution workflows. The supported installation path today is st
 Codex-managed install prompt above. Plugin metadata does not install hooks, change provider config,
 start the proxy, or imply official marketplace listing.
 
-<a id="中文说明"></a>
-## 中文说明
-
-`codex-fast-proxy` 面向“使用第三方 OpenAI-compatible API provider 的 Codex App 用户”。它把 Codex
-App 的模型请求转到本地代理，再转发到第三方上游；默认尊重 Codex App 自己的 Fast 选择，也可以在
-API-key 模式下补缺失的 `service_tier="priority"`。
-
-### 快速开始
-
-把这句话贴给 Codex：
-
-```text
-Fetch and follow instructions from https://raw.githubusercontent.com/gaoguobin/codex-fast-proxy/main/.codex/INSTALL.md
-```
-
-重启 Codex App 后回到对话，再说：
-
-```text
-启用 Codex Fast proxy
-```
-
-启用成功后再重启 Codex App，或者新开 CLI，让 Codex 重新加载 provider 配置。
-
-### 常用自然语言流程
-
-| 目标 | 对 Codex 说 |
-| --- | --- |
-| 安装 | `Fetch and follow instructions from https://raw.githubusercontent.com/gaoguobin/codex-fast-proxy/main/.codex/INSTALL.md` |
-| 启用 | `启用 Codex Fast proxy` |
-| 查看状态 | `查看 Codex Fast proxy 状态` |
-| 打开 dashboard | 打开 `http://127.0.0.1:8787/v1` |
-| 准备 ChatGPT 登录 | `准备一下，我想登录 ChatGPT 账户` |
-| 跑 A/B benchmark | `跑一下 Codex Fast proxy A/B benchmark` |
-| 更换上游 URL | `把 Codex Fast proxy 的上游切到 https://api.example.com/v1` |
-| 检查更新 | `检查 Codex Fast proxy 更新` |
-| 更新 | `Fetch and follow instructions from https://raw.githubusercontent.com/gaoguobin/codex-fast-proxy/main/.codex/UPDATE.md` |
-| 卸载 | `Fetch and follow instructions from https://raw.githubusercontent.com/gaoguobin/codex-fast-proxy/main/.codex/UNINSTALL.md` |
-
-高级命令、benchmark 细节、upstream/auth 配置和恢复命令见
-[docs/advanced-usage.md](docs/advanced-usage.md)。
-
-### ChatGPT 登录提示
-
-如果你想使用插件市场、GitHub/Apps/connectors、Fast 手动选择和状态提示、语音输入等 Codex App UI，
-先让 Codex 准备 provider 鉴权：
-
-```text
-准备一下，我想登录 ChatGPT 账户
-```
-
-如果结果里有 `needs_restart=true`，先重启 Codex App，或让 Codex 执行
-`python -m codex_fast_proxy start` 刷新代理，再登录 ChatGPT。不要在 proxy 还没加载新鉴权设置时直接
-切换登录，否则模型请求仍可能 401。
-
-Windows 上如果登录 ChatGPT 时遇到 `OSError: [WinError 10013] ... socket ...`，可以在管理员
-PowerShell 里依次执行：
-
-```powershell
-net stop winnat
-netsh interface ipv4 show excludedportrange protocol=tcp
-net start winnat
-netsh interface ipv4 show excludedportrange protocol=tcp
-```
-
-### 安全边界
-
-- 只在允许时修改 `POST /v1/responses` 的 `service_tier`。
-- 不改 `model`、`reasoning`、`tools`、`input`。
-- 不记录 API key、Cookie、请求体、prompt、tool 参数或响应内容。
-- 不拦截 ChatGPT 插件市场、GitHub、Apps/connectors 或 ChatGPT cookies。
-- 卸载保持两阶段，避免打断当前仍依赖 proxy 的会话。
-
 ## Sponsor
 
 If `codex-fast-proxy` saves you time, consider [sponsoring the author](https://gaoguobin.github.io/sponsor)

docs/README.zh-CN.md

@@ -0,0 +1,65 @@
+# codex-fast-proxy 中文指南
+
+`codex-fast-proxy` 面向使用兼容 OpenAI API 的第三方供应商的 Codex App 用户。它把 Codex App 的模型请求转到本地代理，再转发到第三方上游；默认尊重 Codex App 自己的 Fast 选择，也可以在 API-key 模式下补缺失的 `service_tier="priority"`。
+
+[返回英文 README](../README.md)
+
+## 快速开始
+
+把这句话贴给 Codex：
+
+```text
+Fetch and follow instructions from https://raw.githubusercontent.com/gaoguobin/codex-fast-proxy/main/.codex/INSTALL.md
+```
+
+重启 Codex App 后回到对话，再说：
+
+```text
+启用 Codex Fast proxy
+```
+
+启用成功后再重启 Codex App，或者新开 CLI，让 Codex 重新加载 provider 配置。
+
+## 常用自然语言流程
+
+| 目标 | 对 Codex 说 |
+| --- | --- |
+| 安装 | `Fetch and follow instructions from https://raw.githubusercontent.com/gaoguobin/codex-fast-proxy/main/.codex/INSTALL.md` |
+| 启用 | `启用 Codex Fast proxy` |
+| 查看状态 | `查看 Codex Fast proxy 状态` |
+| 打开仪表盘 | 打开 `http://127.0.0.1:8787/v1` |
+| 准备 ChatGPT 登录 | `准备一下，我想登录 ChatGPT 账户` |
+| 跑 A/B 基准测试 | `跑一下 Codex Fast proxy A/B benchmark` |
+| 更换上游 URL | `把 Codex Fast proxy 的上游切到 https://api.example.com/v1` |
+| 检查更新 | `检查 Codex Fast proxy 更新` |
+| 更新 | `Fetch and follow instructions from https://raw.githubusercontent.com/gaoguobin/codex-fast-proxy/main/.codex/UPDATE.md` |
+| 卸载 | `Fetch and follow instructions from https://raw.githubusercontent.com/gaoguobin/codex-fast-proxy/main/.codex/UNINSTALL.md` |
+
+高级命令、基准测试细节、上游和鉴权配置、恢复命令见 [高级用法](advanced-usage.md)。
+
+## ChatGPT 登录提示
+
+如果你想使用插件市场、GitHub/Apps/connectors、Fast 手动选择和状态提示、语音输入等 Codex App UI，先让 Codex 准备供应商鉴权：
+
+```text
+准备一下，我想登录 ChatGPT 账户
+```
+
+如果结果里有 `needs_restart=true`，先重启 Codex App，或让 Codex 执行 `python -m codex_fast_proxy start` 刷新代理，再登录 ChatGPT。不要在代理还没加载新鉴权设置时直接切换登录，否则模型请求仍可能 401。
+
+Windows 上如果登录 ChatGPT 时遇到 `OSError: [WinError 10013] ... socket ...`，可以在管理员 PowerShell 里依次执行：
+
+```powershell
+net stop winnat
+netsh interface ipv4 show excludedportrange protocol=tcp
+net start winnat
+netsh interface ipv4 show excludedportrange protocol=tcp
+```
+
+## 安全边界
+
+- 只在允许时修改 `POST /v1/responses` 的 `service_tier`。
+- 不改 `model`、`reasoning`、`tools`、`input`。
+- 不记录 API key、Cookie、请求体、prompt、tool 参数或响应内容。
+- 不拦截 ChatGPT 插件市场、GitHub、Apps/connectors 或 ChatGPT cookies。
+- 卸载保持两阶段，避免打断当前仍依赖 proxy 的会话。

skills/codex-fast-proxy/SKILL.md

@@ -7,13 +7,13 @@ Use this skill when the user wants Codex to manage the local Fast proxy for Code
 
 ## Trigger patterns
 
-- Natural language enable requests such as `启用 Codex Fast proxy`
-- App Fast requests such as `让 Codex App 使用 Fast`
-- Provider-specific requests such as `PackyAPI 开 Fast`
-- ChatGPT login compatibility requests such as `插件能用了但是模型请求 401`, `ChatGPT 登录后第三方 provider 还能用吗`
-- Benchmark requests such as `跑 Fast proxy benchmark`, `验证供应商是否支持 Fast`, `Fast 模式有没有变快`
-- Upstream URL changes such as `把 Codex Fast proxy 的上游切到 https://api.example.com/v1`
-- Maintenance requests such as `查看 Fast proxy 状态`, `检查更新`, `停止 Fast proxy`, `卸载 Fast proxy`
+- Enable requests such as "enable Codex Fast proxy".
+- App Fast requests such as "make Codex App use Fast".
+- Provider-specific requests such as "enable Fast for PackyAPI".
+- ChatGPT login compatibility requests such as "plugins work but model requests return 401".
+- Benchmark requests such as "run the Fast proxy benchmark" or "check whether my provider supports Fast".
+- Upstream URL changes such as "set the Codex Fast proxy upstream to https://api.example.com/v1".
+- Maintenance requests such as "show status", "check updates", "stop", or "uninstall".
 
 ## How to execute
 
@@ -90,9 +90,11 @@ python -m codex_fast_proxy uninstall
   CLI process after writing user environment variables.
 - If `set-upstream --upstream-api-key-env <ENV_NAME>` returns `restart_required=true` or a following
   `status` reports `needs_restart=true`, do not tell the user they can sign in with ChatGPT yet.
-  Tell them first: `已完成 provider 鉴权准备，但运行中的 proxy 还没加载新设置。请先重启 Codex App，或让我执行 python -m codex_fast_proxy start 刷新 proxy；刷新后再登录 ChatGPT 账号。不要在 needs_restart=true 时直接切换登录，否则模型请求仍可能 401。`
+  Explain that provider auth was verified and saved, but the running proxy has not loaded the new
+  override yet. The user must restart Codex App or explicitly allow `python -m codex_fast_proxy start`
+  before signing in with ChatGPT.
 - After provider auth split is active and `status.needs_restart=false`, tell the user they can sign
-  in with ChatGPT, but include this Windows troubleshooting note: `如果登录 ChatGPT 账号时遇到 OSError: [WinError 10013] 以一种访问权限不允许的方式做了一个访问套接字的尝试，通常是 Windows 端口排除/WinNAT 状态问题。可以在管理员 PowerShell 里依次执行 net stop winnat、netsh interface ipv4 show excludedportrange protocol=tcp、net start winnat、netsh interface ipv4 show excludedportrange protocol=tcp，然后重试登录。`
+  in with ChatGPT, and report the `chatgpt_login_windows_troubleshooting` JSON field when present.
 - If proxy startup or config switching fails, the manager restores the backed-up config before returning.
 - Use `set-upstream` when the user wants to change the provider URL, upstream auth environment name,
   or service tier policy while the proxy is already enabled. It must keep Codex config pointed at the
@@ -157,13 +159,13 @@ python -m codex_fast_proxy uninstall
 
 ## User handoff messages
 
-- After `.codex/INSTALL.md` or `.codex/UPDATE.md` changes skill files, explicitly tell the user: `请重启 Codex App 并回到这个对话，或新开 CLI 实例，让它重新扫描 ~/.agents/skills；然后再说“启用 Codex Fast proxy”。`
-- After `.codex/UNINSTALL.md`, explicitly tell the user: `请重启 Codex App，或新开 CLI 实例，让它从 skill 列表中移除 codex-fast-proxy。`
-- After a successful `install --start`, explicitly tell the user: `Fast proxy 已启用，但当前 Codex 进程不会热切换；请重启 Codex App 并回到这个对话，或新开 CLI 实例后继续使用。`
+- After `.codex/INSTALL.md` or `.codex/UPDATE.md` changes skill files, explicitly tell the user to restart Codex App and return to the conversation, or open a new CLI process, so Codex can rescan `~/.agents/skills`; then ask Codex to enable Codex Fast proxy.
+- After `.codex/UNINSTALL.md`, explicitly tell the user to restart Codex App, or open a new CLI process, so Codex removes `codex-fast-proxy` from the skill list.
+- After a successful `install --start`, explicitly tell the user that Fast proxy is enabled, but the current Codex process will not hot-switch; they should restart Codex App and return to the conversation, or open a new CLI process.
 - After a successful `install --start`, always append this optional ChatGPT-login UI note even if
-  the status summary is already long: `可选提示：你现在是 API-key 模式，可以继续保持当前方式使用第三方 API + 全局 Fast。若想使用更完整的 Codex App UI，例如插件市场、GitHub/Apps/connectors、Fast 手动选择和状态提示、语音输入等，请先让我执行 prepare-chatgpt-login 准备 provider 鉴权，再切换 ChatGPT 账号登录；不要直接切换，否则可能 401。`
-- After `uninstall --defer-stop`, explicitly tell the user: `配置已恢复直连，代理暂时保留运行以避免打断当前进程；请重启 Codex App 并回到这个对话，或新开 CLI 实例后再次执行卸载完成清理。`
-- If `direct_upstream_auth_warning` is present after uninstall, add first: `注意：当前检测到 ChatGPT 登录态。卸载恢复直连后不再经过 proxy 的 upstream auth override；如果继续保持 ChatGPT 登录，第三方 provider 可能收到 ChatGPT token 并返回 401。请先退出 ChatGPT 登录并切回第三方/API-key 认证，或暂时不要卸载、继续保留 proxy。`
+  the status summary is already long: the user may keep API-key mode for third-party API plus global Fast. If they want richer Codex App UI such as plugin marketplace, GitHub/Apps/connectors, manual Fast controls, status hints, and voice input, they should run `prepare-chatgpt-login` before switching Codex App to ChatGPT login; switching directly may cause 401.
+- After `uninstall --defer-stop`, explicitly tell the user that Codex config has been restored to direct upstream, and the proxy was left running temporarily to avoid interrupting the current process. They should restart Codex App and return to the conversation, or open a new CLI process, then run uninstall again to finish cleanup.
+- If `direct_upstream_auth_warning` is present after uninstall, first warn that ChatGPT login appears active. After direct upstream restore, requests no longer pass through the proxy upstream auth override. Keeping ChatGPT login may send ChatGPT auth to the third-party provider and return 401. The user should switch back to API-key/third-party provider auth before restarting, or keep the proxy enabled for ChatGPT-login UI with a third-party provider.
 
 Use `--provider <name>` only when the user names a provider or when `doctor` reports that no active provider can be selected.
 
@@ -179,8 +181,9 @@ For upstream URL changes after enable, prefer `set-upstream --upstream-base <url
 
 - Treat the JSON output as the source of truth.
 - Report `provider`, `base_url`, `upstream_base`, `service_tier_policy`, `upstream_auth`, `running`,
-  `diagnosis`, `provider_auth_preparation`, `chatgpt_login_hint`, `next_user_action`, `runtime_matches`,
-  `needs_restart`, and backup or restore status.
+  `diagnosis`, `provider_auth_preparation`, `chatgpt_login_hint`, `next_user_action`,
+  `chatgpt_login_windows_troubleshooting` when present, `runtime_matches`, `needs_restart`, and
+  backup or restore status.
 - Use `status.runtime` when diagnosing stale runtime, wrong Python executable, or a startup hook that
   points at a different checkout. Do not infer hook readiness from `~/.codex/hooks.json` alone.
 - For App-specific traffic checks, use recent `/v1/responses` events as model-generation evidence.