@qqq123456789/codex-doctor 0.2.0

package/docs/02-login-auth.md

@@ -0,0 +1,121 @@
+# 02 · 登录与认证（401 / 403 高发区）
+
+> 报错关键词：`401 Unauthorized`、`Exceeded retry limit, last error: 401`、`403 Forbidden`、`Not logged in`、登录后一直无响应
+>
+> English version: [02-login-auth.en.md](02-login-auth.en.md)
+
+## 两种认证方式，先分清你在用哪种
+
+| 方式 | 命令 | 计费 | 凭据存放 |
+|---|---|---|---|
+| ChatGPT 账号登录（Plus / Pro / Team 等订阅） | `codex login` | 订阅额度内 | `~/.codex/auth.json` 中的 tokens |
+| API Key | `codex login --api-key` 或环境变量 `OPENAI_API_KEY` | 平台按量计费 | `auth.json` 或环境变量 |
+
+两者**可以同时存在**，这正是大量 401 问题的根源——实际请求用了 A 方式的凭据、打到了 B 方式的端点。
+
+## 401 排障决策树
+
+按顺序问自己这五个问题：
+
+### ① 请求到底发去了哪里？
+
+看终端报错里的 URL（或在 `~/.codex/log/` 日志里搜 URL）：
+
+- 指向 `chatgpt.com` / `api.openai.com` → 官方端点；
+- 指向某个第三方域名 → 你的配置里残留了第三方中转，见 [04 config.toml](04-config.md) 的检查清单。
+
+### ② 第三方 Key 是否被发给了官方端点？
+
+中转站买的 `sk-xxx` 发给 `api.openai.com` 必然 401。反过来，官方账号凭据发给中转站也 401。修复：
+
+- 用官方账号：清理 `config.toml` 里的自定义 `model_providers` 和根级 `model_provider`，清理 `OPENAI_BASE_URL` 环境变量，重新 `codex login`；
+- 用中转站：确保 `config.toml` 中 `model_provider` 指向对应的中转 provider（见 [04](04-config.md)）。
+
+### ③ 登录态是不是过期/损坏了？
+
+`Exceeded retry limit, last error: 401 Unauthorized` 绝大多数是登录态问题：
+
+```bash
+codex logout
+codex login
+```
+
+仍不行，**彻底清理凭据后重登**（先完全退出 Codex 和 IDE 里的 Codex 插件）：
+
+```bash
+# 删除凭据文件（Windows 路径：C:\Users\<你>\.codex\auth.json）
+rm ~/.codex/auth.json
+codex login
+```
+
+VS Code / Cursor 用户：重登后执行一次「Developer: Reload Window」，插件缓存才会刷新。
+
+### ④ 环境变量里有没有残留？
+
+环境变量的优先级会覆盖你以为的配置，逐项检查：
+
+```bash
+env | grep -i openai        # macOS/Linux
+Get-ChildItem Env: | Where-Object Name -like "*OPENAI*"   # PowerShell
+```
+
+发现过期/无效的 `OPENAI_API_KEY`、`OPENAI_BASE_URL`，删除（或改成正确值）后重开终端。特别注意：有些「一键配置脚本」会把它们写进 shell 配置文件（`.bashrc` / PowerShell `$PROFILE`），改当前会话没用，要去配置文件里删。
+
+### ⑤ ChatGPT 登录成功，但会话里还是 401？
+
+这是社区最高频的 401 场景：**登录流程没问题，是配置冲突**——`config.toml` 里残留的第三方 provider 或环境变量把请求引去了别处。回到 [04 config.toml](04-config.md) 的检查清单逐项排除；实在找不到，按 [09 日常维护](09-maintenance.md) 的「完全重置」流程走一遍（备份后删除整个 `~/.codex`，重新登录）。
+
+## 403 Forbidden
+
+401 是「没认出你是谁」，403 是「认出来了，但不允许」：
+
+- 账号（或所在组织）没有你请求的那个模型的权限；
+- 地区限制——部分服务/模型不对特定地区开放；
+- 企业/团队工作区策略限制。确认账号资格、换用你有权限的模型（`/model`）。
+
+## 登录回调失败 / 浏览器打不开：设备码登录
+
+远程 SSH、无图形界面、默认浏览器异常时，OAuth 回调会卡住。此时用设备码登录，在任意有浏览器的设备上完成授权：
+
+```bash
+codex login --device-auth
+```
+
+设备码登录的三类报错：
+
+| 报错/现象 | 原因 | 处理 |
+|---|---|---|
+| 进不到输入设备码的页面，直接失败 | **设备码授权默认是关闭的** | 到 ChatGPT 网页 → Settings → Security，开启「Enable device code authorization for Codex」再重试 |
+| `token exchange failed` | 旧会话残留干扰 | 先 `codex logout`，再执行 `codex login --device-auth` |
+| `Invalid device code` | 码过期（有效期很短） | 重新运行命令生成新码，尽快输入 |
+
+> 实测参考：[openai/codex #25670](https://github.com/openai/codex/issues/25670)、[OpenAI 社区：token exchange failed](https://community.openai.com/t/codex-cli-desktop-auth-failed-with-token-exchange-failed/1385469)
+
+## WSL 里登录成功但凭据传不回来
+
+WSL 与 Windows 的 localhost 相互隔离：`codex login` 拉起的浏览器在 Windows 侧完成授权后，回调无法送达 WSL 里的 codex。按优先级处理：
+
+1. **新版 WSL2 开镜像网络模式**：Windows 用户目录 `.wslconfig` 里写 `networkingMode=mirrored` 后重启 WSL，localhost 打通后通常直接解决；
+2. **手动迁移凭据**：在 Windows 侧的 Codex 完成登录，然后把凭据复制进 WSL：
+   ```bash
+   # Windows 侧登录成功后，在 WSL 里执行（<Windows用户名> 按实际改）
+   mkdir -p ~/.codex
+   cp /mnt/c/Users/<Windows用户名>/.codex/auth.json ~/.codex/auth.json
+   ```
+   之后 WSL 里的 codex 即可使用订阅额度；token 过期后需重做一次；
+3. 仍不通：回 [03 网络与代理](03-network-proxy.md) 检查 WSL 的代理（WSL 里 `127.0.0.1` 指向的是 WSL 自己）。
+
+> 实测参考：[WSL 环境 Codex 登录问题完全解决方案 — CSDN](https://blog.csdn.net/gxy03/article/details/157246287)
+
+## auth.json 是什么
+
+`~/.codex/auth.json` 保存登录凭据，大致两种形态：
+
+```jsonc
+// ChatGPT 登录
+{ "tokens": { "id_token": "...", "access_token": "...", "refresh_token": "...", "account_id": "..." }, "OPENAI_API_KEY": null }
+// API Key 方式
+{ "OPENAI_API_KEY": "sk-..." }
+```
+
+> 🔒 这个文件等同密码：排障发帖、截图、求助时**务必脱敏**；换机器迁移时单独备份，不要提交进任何仓库。

package/docs/03-network-proxy.en.md

@@ -0,0 +1,96 @@
+English | [中文](03-network-proxy.md)
+
+# 03 · Network & Proxy
+
+> Keywords: `stream error`, `stream disconnected`, `connection reset`, `ETIMEDOUT`, `ECONNREFUSED`, endless spinner with no response.
+>
+> Typical cases: users on restricted/unstable networks, corporate proxies.
+
+## The core fact
+
+Codex needs stable access to `chatgpt.com` (login & subscription quota) and/or `api.openai.com` (API billing). **"The command runs but streams keep breaking / timing out" is normal on restricted direct connections** — verify the network path first, then suspect everything else.
+
+## Step 1: verify connectivity
+
+In **the same terminal** you run codex from:
+
+```bash
+curl -I --max-time 10 https://chatgpt.com
+curl -I --max-time 10 https://api.openai.com
+```
+
+- Any HTTP status (even 4xx) → network is fine; the problem is elsewhere (see [02](02-login-auth.en.md) / [04](04-config.en.md));
+- Hangs, timeouts, `Connection reset` → it's the network path; continue below.
+
+## Step 2: configure a proxy
+
+CLI programs **don't necessarily use the system proxy** — setting environment variables explicitly is the reliable way (set them in the terminal session that launches codex; no need to go global):
+
+```powershell
+# Windows PowerShell
+$env:HTTPS_PROXY = "http://127.0.0.1:7890"
+$env:HTTP_PROXY  = "http://127.0.0.1:7890"
+$env:NO_PROXY    = "localhost,127.0.0.1"
+codex
+```
+
+```bash
+# macOS / Linux / WSL
+export HTTPS_PROXY=http://127.0.0.1:7890
+export HTTP_PROXY=http://127.0.0.1:7890
+export NO_PROXY=localhost,127.0.0.1
+codex
+```
+
+Notes:
+
+1. **The port must match what your proxy client actually listens on** (7890/1080/10809… — check your client);
+2. The proxy client must allow local/LAN connections as required;
+3. For "permanent" effect put the lines into your shell profile (`.bashrc` / PowerShell `$PROFILE`) — think twice; a permanent global proxy interferes with other tools;
+4. Re-run the `curl` test from step 1 — **if the proxy itself is unreachable you'll get `ECONNREFUSED`** (can't connect to the proxy port).
+
+### Corporate networks (MITM proxy): TLS certificate errors
+
+Corporate proxies often replace TLS certificates, producing `unable to verify the first certificate` / `self-signed certificate`. Fix: get the corporate root certificate from IT and install it into the system trust chain. Never "work around" it by disabling certificate verification.
+
+## Step 3: mirrors & acceleration
+
+### npm install/update slow or failing
+
+```bash
+npm config set registry https://registry.npmmirror.com
+```
+
+### Slow git clones of GitHub repos
+
+Use a mirror prefix for cloning (clone only):
+
+```bash
+git clone https://ghfast.top/https://github.com/openai/codex.git
+```
+
+### Third-party API relays
+
+If a proxy is inconvenient, you can point Codex at a third-party API relay via `model_providers` — see [04 config.toml](04-config.en.md). Vet the relay carefully; never send API keys to parties you don't trust.
+
+## Deep dive: `stream disconnected before completion`
+
+One of the most-reported Codex issues overall. Troubleshoot by hit rate:
+
+1. **Classify first**: occasional = network jitter, configure a proxy per above; only continue if it reproduces stably;
+2. **Project inside OneDrive / a sync folder**: file locks from sync engines interfere with long sessions' local streaming I/O — move the project out of OneDrive and retest (a frequent trap on Windows);
+3. **Very long sessions**: streams break more often as context approaches compaction — start a fresh session and compare; split long tasks into separate sessions (saves quota too, see [05](05-models-limits.en.md));
+4. **Proxy unstable on SSE long connections**: switch to nodes/clients that handle long connections; TUN mode is usually steadier than terminal-only proxying;
+5. **Server side**: if `/backend-api/codex/responses` disconnects coincide with a [known community incident thread](https://community.openai.com/t/bug-codex-stream-disconnected-before-completion-on-backend-api-codex-responses-feb-8-2026/1373656), just wait for the fix; relay users should check `wire_api` ([04](04-config.en.md)).
+
+## Symptom cheat sheet
+
+| Symptom | Likely cause | Fix |
+|---|---|---|
+| Generation dies mid-way with `stream error` | Network path jitter | Configure proxy; if configured, switch nodes |
+| `ETIMEDOUT`, endless spinner | Direct connection blocked or proxy not applied | Proxy or relay |
+| `ECONNREFUSED` | Proxy port closed or wrong | Verify the client's port |
+| TUI hangs but `curl` works | Proxy unstable on SSE long connections | Switch to long-connection-friendly nodes/client |
+| Login page won't open | Browser not proxied | Check the browser's proxy separately |
+
+> 💡 The [doctor script](../scripts/codex-doctor.sh) runs the connectivity probes automatically and interprets the results.

package/docs/03-network-proxy.md

@@ -0,0 +1,96 @@
+# 03 · 网络与代理
+
+> 报错关键词：`stream error`、`stream disconnected`、`connection reset`、`ETIMEDOUT`、`ECONNREFUSED`、长时间转圈无响应
+>
+> 典型人群：国内网络直连用户、公司内网/企业代理用户。
+>
+> English version: [03-network-proxy.en.md](03-network-proxy.en.md)
+
+## 核心认知
+
+Codex 需要稳定访问 `chatgpt.com`（登录与订阅额度）和/或 `api.openai.com`（API 计费）。**「命令能跑但经常断流、超时」在国内直连网络下是常态**，先按下面步骤确认网络路径，再去怀疑其他配置。
+
+## 第一步：验证连通性
+
+在**运行 codex 的同一个终端**里：
+
+```bash
+curl -I --max-time 10 https://chatgpt.com
+curl -I --max-time 10 https://api.openai.com
+```
+
+- 能返回 HTTP 状态码（哪怕 4xx）→ 网络通，问题在别处（去 [02](02-login-auth.md) / [04](04-config.md)）；
+- 卡住、超时、`Connection reset` → 就是网络路径问题，继续往下。
+
+## 第二步：配置代理
+
+命令行程序**不一定走系统代理**，显式设置环境变量最可靠（在启动 codex 的那个终端里设置即可，不必全局）：
+
+```powershell
+# Windows PowerShell
+$env:HTTPS_PROXY = "http://127.0.0.1:7890"
+$env:HTTP_PROXY  = "http://127.0.0.1:7890"
+$env:NO_PROXY    = "localhost,127.0.0.1"
+codex
+```
+
+```bash
+# macOS / Linux / WSL
+export HTTPS_PROXY=http://127.0.0.1:7890
+export HTTP_PROXY=http://127.0.0.1:7890
+export NO_PROXY=localhost,127.0.0.1
+codex
+```
+
+注意：
+
+1. **端口要和你代理客户端实际监听的端口一致**（7890/1080/10809…以你的客户端为准）；
+2. 代理客户端要开着「允许局域网连接」的对应模式；
+3. 想「永久生效」就把这几行写进 shell 配置文件（`.bashrc` / PowerShell `$PROFILE`）——但想清楚再写，长期全局代理会干扰其他工具；
+4. 设置后用第一步的 `curl` 再验证一遍，**代理本身不通时会报 `ECONNREFUSED`**（连不上代理端口）。
+
+### 企业内网（MITM 代理）的 TLS 证书报错
+
+公司网络常出现 `unable to verify the first certificate` / `self-signed certificate` 类错误：企业代理会替换 TLS 证书。解决：向 IT 要企业根证书并安装到系统信任链；不要用关闭证书校验的方式「绕过」。
+
+## 第三步：镜像与加速
+
+### npm 安装/更新慢或失败
+
+```bash
+npm config set registry https://registry.npmmirror.com
+```
+
+### git clone 官方仓库慢
+
+用镜像前缀加速（仅克隆用）：
+
+```bash
+git clone https://ghfast.top/https://github.com/openai/codex.git
+```
+
+### 用中转站（第三方 API 中转）
+
+如果代理不方便，可以把 Codex 配置成走第三方 API 中转，见 [04 config.toml](04-config.md) 的 `model_providers` 配置。注意甄别中转站资质，API Key 不要发给不可信的第三方。
+
+## `stream disconnected before completion` 深挖
+
+这是社区上报量最大的单一条目之一。按命中率排查：
+
+1. **先分类**：偶发多为网络抖动，按上文配代理；稳定复现才继续往下；
+2. **项目在 OneDrive / 同步盘路径里**：同步盘的文件锁会干扰长会话的本地流式读写，把项目移出 OneDrive 再试（Windows 用户高频踩坑）；
+3. **超长会话**：上下文接近压缩（compaction）阈值时更容易断——开个新会话对比验证，长任务养成拆分会话的习惯（也省额度，见 [05](05-models-limits.md)）；
+4. **代理对 SSE 长连接不稳定**：换支持长连接的节点/客户端，TUN 模式通常比仅终端代理稳；
+5. **服务端侧**：`/backend-api/codex/responses` 的断流如与官方社区事故帖时间吻合，等修复即可——[参考帖子](https://community.openai.com/t/bug-codex-stream-disconnected-before-completion-on-backend-api-codex-responses-feb-8-2026/1373656)；走中转的用户检查 `wire_api` 配置（见 [04](04-config.md)）。
+
+## 常见症状对照
+
+| 症状 | 大概率原因 | 处理 |
+|---|---|---|
+| 生成到一半断掉，报 `stream error` | 网络路径抖动 | 配代理；已配则换节点 |
+| `ETIMEDOUT`，一直转圈 | 直连被阻断 | 配代理或换中转 |
+| `ECONNREFUSED` | 代理端口没开/写错 | 核对代理客户端端口 |
+| 只在 TUI 卡死，`curl` 却正常 | 代理对长连接（SSE）不稳定 | 换支持长连接的节点/客户端 |
+| 登录页打不开 | 浏览器没走代理 | 浏览器侧单独确认 |
+
+> 💡 自检脚本 `scripts/codex-doctor` 会自动做连通性探测并给出结论。

package/docs/04-config.en.md

@@ -0,0 +1,118 @@
+English | [中文](04-config.md)
+
+# 04 · config.toml
+
+> Keywords: `failed to parse config`, `TOML parse error`, **"config not taking effect"**, 401 (config-conflict type)
+
+## File location
+
+```
+~/.codex/config.toml
+Windows: C:\Users\<you>\.codex\config.toml
+```
+
+Create it if missing. **Restart the Codex session after every edit.**
+
+## Gotcha #1: root keys must precede every `[table]`
+
+In TOML, a root key like `model = "..."` written **after** any `[xxx]` section header silently becomes a key *of that table* — no error, no effect. This is the #1 cause of "my config isn't taking effect".
+
+❌ Wrong:
+
+```toml
+[model_providers.myproxy]
+name = "myproxy"
+base_url = "https://relay.example.com/v1"
+
+model = "gpt-5-codex"          # ← now belongs to myproxy; ignored as a root setting!
+```
+
+✅ Right:
+
+```toml
+model = "gpt-5-codex"          # all root keys go on top
+model_provider = "openai"
+approval_policy = "on-request"
+sandbox_mode = "workspace-write"
+
+[model_providers.myproxy]      # tables go below
+name = "myproxy"
+base_url = "https://relay.example.com/v1"
+```
+
+> 💡 The [doctor script](../scripts/codex-doctor.sh) scans for this pattern and warns about it.
+
+## Common root keys
+
+```toml
+model = "gpt-5-codex"            # model names per official docs; switch with /model in the TUI
+model_provider = "openai"        # default official; your provider id when using a relay
+approval_policy = "on-request"   # untrusted / on-failure / on-request / never
+sandbox_mode = "workspace-write" # read-only / workspace-write / danger-full-access
+```
+
+Approval and sandbox details: [06 Sandbox & Windows](06-sandbox-windows.md).
+
+## Custom relay provider
+
+```toml
+# root: point at your provider
+model_provider = "myrelay"
+
+# table: define it (below all root keys)
+[model_providers.myrelay]
+name = "My Relay"
+base_url = "https://relay.example.com/v1"   # per your relay's docs, usually ends with /v1
+env_key = "MYRELAY_API_KEY"                  # env var that holds the key
+wire_api = "responses"                       # set to "chat" if the relay only supports Chat Completions
+```
+
+```bash
+# keep the key in an env var, not in config.toml
+export MYRELAY_API_KEY=sk-xxxx
+```
+
+Key points:
+
+- A `wire_api` mismatch is the classic "relay connects but everything errors" cause — try both values;
+- A missing `env_key` variable can surface as unauthenticated / 401;
+- Whether the relay speaks plain OpenAI-compatible chat or the full Responses API decides `wire_api`.
+
+## Profiles: switch setups with one flag
+
+```toml
+[profiles.official]
+model_provider = "openai"
+
+[profiles.relay]
+model_provider = "myrelay"
+model = "gpt-5-codex"
+```
+
+```bash
+codex --profile relay
+```
+
+## How to verify the config took effect
+
+1. Restart the session;
+2. Run `/status` in the TUI and check the displayed **model / provider / approval / sandbox** are what you intended.
+
+## The 401 config checklist
+
+Work through together with [02 Login & auth](02-login-auth.en.md):
+
+- [ ] Root `model_provider` — does it point where you think?
+- [ ] Any **leftover** `[model_providers.*]` — most common after switching back from a relay to official;
+- [ ] Does the `env_key` variable exist, and is it a key for that platform;
+- [ ] `base_url` path matches the relay's requirement (usually ends with `/v1`);
+- [ ] Any leftover `OPENAI_BASE_URL` environment variable (see [02 step ④](02-login-auth.en.md));
+- [ ] Does `auth.json` match the endpoint you're pointing at (official tokens vs relay sk-key).
+
+## Syntax errors
+
+On `failed to parse config` / `TOML parse error`, the message includes a line number. Usual suspects:
+
+- Unbalanced quotes, or unquoted strings (URLs and paths must be quoted);
+- Full-width quotes `“”` or full-width colons pasted from chat apps;
+- Duplicate table names.

package/docs/04-config.md

@@ -0,0 +1,120 @@
+# 04 · config.toml 配置
+
+> 报错关键词：`failed to parse config`、`TOML parse error`、**「配置写了但不生效」**、401（配置冲突型）
+>
+> English version: [04-config.en.md](04-config.en.md)
+
+## 文件位置
+
+```
+~/.codex/config.toml
+Windows: C:\Users\<你>\\.codex\\config.toml
+```
+
+没有就自己建一个。**修改后重启 Codex 会话才会生效**。
+
+## 第一大坑：TOML 的「根级键必须写在所有 `[表]` 之前」
+
+TOML 里 `model = "..."` 这类**根级键，一旦写在某个 `[xxx]` 段落之后，就会被解析成那个表的子键**——不报错、不生效，是「配置不生效」的头号原因。
+
+❌ 错误示例：
+
+```toml
+[model_providers.myproxy]
+name = "myproxy"
+base_url = "https://relay.example.com/v1"
+
+model = "gpt-5-codex"          # ← 写在 [表] 后面，属于 myproxy 表，不生效！
+```
+
+✅ 正确示例：
+
+```toml
+model = "gpt-5-codex"          # 根级键全部放最上面
+model_provider = "openai"
+approval_policy = "on-request"
+sandbox_mode = "workspace-write"
+
+[model_providers.myproxy]      # 表放在后面
+name = "myproxy"
+base_url = "https://relay.example.com/v1"
+```
+
+> 💡 自检脚本会扫描这个错误模式并给出警告。
+
+## 常用根级配置
+
+```toml
+model = "gpt-5-codex"            # 模型名以官方文档为准，可在 TUI 里用 /model 切换
+model_provider = "openai"        # 默认官方；用中转时改成你定义的 provider id
+approval_policy = "on-request"   # untrusted / on-failure / on-request / never
+sandbox_mode = "workspace-write" # read-only / workspace-write / danger-full-access
+```
+
+审批与沙箱模式的详细说明见 [06 沙箱与 Windows](06-sandbox-windows.md)。
+
+## 配置第三方中转（自定义 provider）
+
+```toml
+# 根级：指向你的 provider
+model_provider = "myrelay"
+
+# 表：定义 provider（放在根级键之后）
+[model_providers.myrelay]
+name = "My Relay"
+base_url = "https://relay.example.com/v1"   # 按中转站要求，通常以 /v1 结尾
+env_key = "MYRELAY_API_KEY"                  # 从哪个环境变量读 Key
+wire_api = "responses"                       # 中转站只支持 Chat Completions 时改为 "chat"
+```
+
+```bash
+# 把 Key 放进环境变量（不要写进 config.toml 明文）
+export MYRELAY_API_KEY=sk-xxxx
+```
+
+要点：
+
+- `wire_api` 不匹配是「中转站连上了但一直报错」的常见原因，两种都试一下；
+- `env_key` 对应的环境变量不存在时，部分版本表现为未认证/401；
+- 中转站给的是 OpenAI 兼容接口还是完整 Responses 接口，直接决定 `wire_api` 该填什么。
+
+## Profiles：多套配置一键切换
+
+官方/中转两套配置来回切很麻烦，用 profile：
+
+```toml
+[profiles.official]
+model_provider = "openai"
+
+[profiles.relay]
+model_provider = "myrelay"
+model = "gpt-5-codex"
+```
+
+```bash
+codex --profile relay
+```
+
+## 改完配置怎么验证生效
+
+1. 重启 Codex 会话；
+2. 在 TUI 里输入 `/status`，核对显示的 **model / provider / approval / sandbox** 是否是你要的值。
+
+## 401 排障时的配置检查清单
+
+逐项过（配合 [02 登录与认证](02-login-auth.md)）：
+
+- [ ] 根级 `model_provider` 指向谁？是不是以为在用官方、实际指向了中转（或相反）？
+- [ ] 有没有**残留的** `[model_providers.*]`——用过中转又切回官方的最容易中招；
+- [ ] `env_key` 对应的环境变量是否存在、是否是那家平台的 Key；
+- [ ] `base_url` 路径是否符合中转站要求（多数要 `/v1` 结尾）；
+- [ ] 环境变量里有没有残留的 `OPENAI_BASE_URL`（见 [02](02-login-auth.md) 第④步）；
+- [ ] `auth.json` 里的凭据和你指向的端点是否匹配（官方 tokens vs 中转 sk-key）。
+
+## 配置文件语法报错
+
+`failed to parse config` / `TOML parse error` 时，报错信息会带行号，常见原因：
+
+- 引号没配对、字符串没加引号（URL、路径必须加引号）；
+- 复制粘贴带进了全角引号 `“”` 或全角冒号；
+- 表名重复定义。

package/docs/05-models-limits.en.md

@@ -0,0 +1,51 @@
+English | [中文](05-models-limits.md)
+
+# 05 · Models & Usage Limits
+
+> Keywords: `429`, `You've hit your usage limit`, `rate limit`, `insufficient_quota`, `model_not_found`
+
+## Two billing modes — the limit logic is completely different
+
+| | ChatGPT subscription (`codex login`) | API key (pay per use) |
+|---|---|---|
+| Limiting | **Rolling 5-hour window + weekly** allowance (varies by plan) | Platform-side RPM/TPM rate limits |
+| Error | `You've hit your usage limit` | `rate limit exceeded` / `insufficient_quota` |
+| Fix | Wait for the window to reset, or upgrade the plan | Top up, reduce concurrency, retry later |
+
+## Handling 429
+
+**Subscription quota (429 + usage-limit message):**
+
+1. Read the **reset time** in the message (it usually states when you get access back);
+2. Check the quota isn't being consumed elsewhere — the same account shares quota across devices/sessions;
+3. Consistently not enough → upgrade the plan, or switch to API-key billing within the limited window.
+
+> 💡 **The weekly limit is a rolling 7-day window, not a calendar week** — the reset time "drifting" forward every day is by design, not a bug. OpenAI has also added flexible on-demand limit resets (triggered from the ChatGPT side; entry point depends on the product). Reference: [community thread: weekly limit ran out](https://community.openai.com/t/weekly-limit-ran-out-even-though-i-never-hit-the-5-hour-limit/1376981).
+
+**API key (429):**
+
+1. `insufficient_quota` → account out of credit; top up on the platform;
+2. `rate limit exceeded` → too frequent or too large requests; back off and retry;
+3. Behind a relay → determine whether the limit is the relay's or upstream's (ask the relay's docs/support).
+
+> Note the distinction: 429 is a **usage** problem; 401/403 are **auth/permission** problems — the troubleshooting paths don't mix (see [02](02-login-auth.en.md)).
+
+## Model-related errors
+
+### `model_not_found` / no access to a model
+
+- Misspelled model name, or the name was retired/renamed — trust the official docs, not copied-from-the-internet old configs;
+- Account/org lacks access (some models are gated by plan or allowlist);
+- Behind a relay: the `model` name isn't in the relay's catalog — use the exact names from the relay's documentation.
+
+### Choosing models
+
+- For coding tasks prefer the Codex-family models (tuned for agent workflows);
+- Switch models with `/model` in the TUI; check the current one with `/status`;
+- Behind a relay, model names follow **the relay's catalog** and may differ from official naming.
+
+## Consuming less
+
+1. Don't stretch one session forever — context grows every turn; split long tasks into sessions;
+2. Describe the task precisely to reduce "guess what I meant" round-trips;
+3. Use `/status` to confirm you're not on a more expensive model than you intended.

package/docs/05-models-limits.md

@@ -0,0 +1,51 @@
+# 05 · 模型与用量限额
+
+> 报错关键词：`429`、`You've hit your usage limit`、`rate limit`、`insufficient_quota`、`model_not_found`
+>
+> English version: [05-models-limits.en.md](05-models-limits.en.md)
+
+## 先分清两种计费，限额逻辑完全不同
+
+| | ChatGPT 订阅额度（`codex login`） | API Key 按量计费 |
+|---|---|---|
+| 限额方式 | 按 **5 小时滚动窗口 + 每周**限额（随套餐档位不同） | 平台侧 RPM/TPM 速率限制 |
+| 报错 | `You've hit your usage limit` | `rate limit exceeded` / `insufficient_quota` |
+| 解法 | 等窗口重置，或升级套餐 | 充值、降并发、稍后重试 |
+
+## 429 处理流程
+
+**订阅额度（429 + usage limit 提示）：**
+
+1. 看提示里给的**重置时间**（通常明确写出几点恢复）；
+2. 确认额度不是被其他会话/其他设备共享消耗的（同一账号多处登录额度共享）；
+3. 长期不够用 → 升级套餐，或在限额窗口内改用 API Key 计费。
+
+> 💡 **每周限额是「滚动 7 天窗口」，不是自然周**——重置时间看起来每天往后「漂移」是设计如此，不是 bug。此外官方已提供弹性重置能力（可在 ChatGPT 侧按需触发限额重置，入口以产品为准）。参考：[社区讨论：weekly limit ran out](https://community.openai.com/t/weekly-limit-ran-out-even-though-i-never-hit-the-5-hour-limit/1376981)。
+
+**API Key（429）：**
+
+1. `insufficient_quota` → 账户余额/额度不足，去平台充值；
+2. `rate limit exceeded` → 请求太频繁或单请求过大，稍等重试；
+3. 用中转站的，确认是**中转站的限额**还是上游的限额（问中转站客服/文档）。
+
+> 注意区分：429 是「用量问题」，401/403 是「认证/权限问题」，处理路径完全不同，别混着排查（见 [02](02-login-auth.md)）。
+
+## 模型相关报错
+
+### `model_not_found` / 模型无权限
+
+- 模型名拼写错误，或该名称已下线/更名——以官方文档为准，不要照抄网上的旧配置；
+- 账号/组织没有该模型访问权限（部分模型按档位或名单开放）；
+- 用了中转站但 `model` 名不在中转站支持列表里——把模型名换成中转站文档里写的名字。
+
+### 模型选择建议
+
+- 写代码/改代码优先用 Codex 系列模型（行为专为 agent 场景调优）；
+- 切换模型在 TUI 里用 `/model`，查看当前用的是 `/status`；
+- 中转站场景下模型名以**中转站的文档**为准，和官方命名可能不同。
+
+## 降低消耗的小技巧
+
+1. 会话别无限续——Codex 会话上下文越滚越大，长任务拆分会话更省额度；
+2. 精确描述任务，减少「猜你想」的多轮返工；
+3. 用 `/status` 确认没有跑到比你预期更贵的模型上。