@qqq123456789/codex-doctor 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 qlw088697-ui
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.en.md

@@ -0,0 +1,86 @@
+English | [中文](README.md)
+
+# Codex Troubleshooting — Maintenance & Troubleshooting Guide for Codex CLI
+
+> A community-maintained guide for [Codex CLI](https://github.com/openai/codex), focused on the problems users actually hit: **401 after login, config not taking effect, network timeouts, usage limits (429), sandbox on Windows, missing MCP tools** — each with a symptom → cause → fix path.
+>
+> **Every topic guide is available in English** — the map below links straight to the English versions; each one cross-links back to the Chinese original.
+
+[![CI](https://github.com/qlw088697-ui/codex-troubleshooting/actions/workflows/ci.yml/badge.svg)](https://github.com/qlw088697-ui/codex-troubleshooting/actions/workflows/ci.yml)
+[![Latest release](https://img.shields.io/github/v/release/qlw088697-ui/codex-troubleshooting?label=release)](https://github.com/qlw088697-ui/codex-troubleshooting/releases)
+[![Latest Codex](https://img.shields.io/github/v/release/openai/codex?label=latest%20codex)](docs/releases.md)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+[![Platform](https://img.shields.io/badge/platform-Windows%20%7C%20macOS%20%7C%20Linux%20%7C%20WSL-lightgrey)](docs/06-sandbox-windows.md)
+
+> 📖 **Read online**：<https://qlw088697-ui.github.io/codex-troubleshooting/> (docsify site with full-text search, kept in sync with this repo)
+
+## Quick start: run the environment self-check first
+
+When anything misbehaves, start with the doctor script (read-only, changes nothing):
+
+```bash
+# macOS / Linux / WSL
+curl -fsSL https://raw.githubusercontent.com/qlw088697-ui/codex-troubleshooting/main/scripts/codex-doctor.sh | bash
+```
+
+```powershell
+# Windows PowerShell
+irm https://raw.githubusercontent.com/qlw088697-ui/codex-troubleshooting/main/scripts/codex-doctor.ps1 | iex
+```
+
+Prefer a CLI? `npx -y @qqq123456789/codex-doctor doctor` — zero-dependency, with cleanup/backup/archive-management/version commands too. See [13 codex-doctor CLI](docs/13-codex-doctor.en.md).
+
+## Symptom → doc map
+
+Guides are written in Chinese (commands and error strings are universal):
+
+| Symptom | Read |
+|---|---|
+| Install fails / `codex: command not found` / upgrade & rollback | [01 Installation](docs/01-installation.en.md) |
+| **401 Unauthorized** after successful login / `Exceeded retry limit` | [02 Login & auth](docs/02-login-auth.en.md) + [08 Quick reference](docs/08-errors-quickref.en.md) |
+| 403 Forbidden | [02 Login & auth](docs/02-login-auth.en.md) |
+| 429 / "You've hit your usage limit" | [05 Models & limits](docs/05-models-limits.en.md) |
+| Timeouts / stream error / unreachable from some regions | [03 Network & proxy](docs/03-network-proxy.en.md) |
+| Custom relay endpoints / config not taking effect | [04 config.toml](docs/04-config.en.md) |
+| Sandbox blocks writes / Windows quirks / prefer WSL2 | [06 Sandbox & Windows](docs/06-sandbox-windows.en.md) |
+| MCP tools missing / server won't start | [07 MCP](docs/07-mcp.en.md) |
+| 401 / config drift inside VS Code / Cursor | [10 IDE integration](docs/10-ide-vscode.en.md) |
+| Use Codex faster & cheaper (commands / project memory / scripting) | [11 Efficiency tips](docs/11-tips.en.md) |
+| Full walkthrough: build a project from scratch with Codex | [12 Walkthrough](docs/12-walkthrough.en.md) |
+| Want one command for checks / cleanup / backups | [13 codex-doctor CLI](docs/13-codex-doctor.en.md) |
+| Cleanup / backup / migrate to a new machine / full reset | [09 Maintenance](docs/09-maintenance.en.md) |
+| Track new Codex releases | [Release tracker](docs/releases.md) (auto-updated weekly by CI) |
+
+## The five-step triage (works for ~80% of issues)
+
+1. **Version**: run `codex --version` — upgrade first, many bugs are version-specific;
+2. **State**: in the TUI run `/status` — confirm the model, provider, approval & sandbox mode are what you think they are;
+3. **Doctor**: run `scripts/codex-doctor` — it covers connectivity and the classic config mistakes;
+4. **Logs**: check `~/.codex/log/` — far more context than the one-line terminal error;
+5. **Minimal repro**: empty directory + move `~/.codex/config.toml` aside + re-login ([09](docs/09-maintenance.en.md)).
+
+## Repo layout
+
+```
+docs/        thirteen topic guides, fully bilingual (中文 + English) + releases.md (auto tracker)
+scripts/     standalone self-check scripts (ps1/sh) + CI checkers + release-tracker generator
+tool/        codex-doctor CLI — zero-dependency maintenance tool (doctor / clean / backup / restore / versions)
+index.html   docsify site (served via GitHub Pages)
+AGENTS.md    contribution guide for AI coding agents
+.github/     CI workflows & issue template
+```
+
+## Contributing
+
+💬 Questions and discussions: [Discussions](https://github.com/qlw088697-ui/codex-troubleshooting/discussions).
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) (Chinese, short): paste the raw error (redacted), note your Codex version + OS, include a verification step. CI runs script syntax checks and relative-link checks on every PR.
+
+## Links
+
+- [openai/codex — official repo](https://github.com/openai/codex) (its Issues are the best living troubleshooting database)
+- [Official Codex docs](https://developers.openai.com/codex/)
+
+## License
+
+[MIT](LICENSE) © 2026

package/README.md

@@ -0,0 +1,132 @@
+# Codex Troubleshooting — Codex CLI 维护与排障手册
+
+中文 | [English](README.en.md)
+
+> 一份面向中文用户的 [Codex CLI](https://github.com/openai/codex) 维护支持手册：安装、登录认证、网络代理、配置文件、用量限额、MCP、Windows 兼容等常见问题的**症状 → 原因 → 解决步骤**速查。
+>
+> A Chinese-first troubleshooting & maintenance guide for OpenAI Codex CLI.
+
+[![CI](https://github.com/qlw088697-ui/codex-troubleshooting/actions/workflows/ci.yml/badge.svg)](https://github.com/qlw088697-ui/codex-troubleshooting/actions/workflows/ci.yml)
+[![Latest release](https://img.shields.io/github/v/release/qlw088697-ui/codex-troubleshooting?label=release)](https://github.com/qlw088697-ui/codex-troubleshooting/releases)
+[![Latest Codex](https://img.shields.io/github/v/release/openai/codex?label=latest%20codex)](docs/releases.md)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+[![Platform](https://img.shields.io/badge/platform-Windows%20%7C%20macOS%20%7C%20Linux%20%7C%20WSL-lightgrey)](docs/06-sandbox-windows.md)
+
+> 📖 **在线阅读**：<https://qlw088697-ui.github.io/codex-troubleshooting/>（支持全文搜索，内容与仓库同步）
+
+---
+
+## 这份手册能解决什么
+
+Codex CLI 迭代很快，社区里反复出现的问题高度集中：**登录成功却一直 401、配置写了不生效、国内网络超时断流、Windows 下沙箱报错、MCP 工具不出现、用量 429**……本手册把这些问题的排查路径整理成文档，并附带一个跨平台的环境自检脚本，帮你 5 分钟内定位大部分问题。
+
+> ⚠️ Codex 版本更新频繁，具体命令与配置键以 [官方文档](https://developers.openai.com/codex/) 和 `codex --version` 实际输出为准。发现过时内容欢迎提 PR。
+
+## 快速开始：先跑一次环境自检
+
+遇到任何异常，先跑自检脚本收集环境信息：
+
+```powershell
+# Windows PowerShell
+irm https://raw.githubusercontent.com/qlw088697-ui/codex-troubleshooting/main/scripts/codex-doctor.ps1 | iex
+```
+
+```bash
+# macOS / Linux / WSL
+curl -fsSL https://raw.githubusercontent.com/qlw088697-ui/codex-troubleshooting/main/scripts/codex-doctor.sh | bash
+```
+
+（也可以下载 `scripts/` 目录里的脚本本地运行。脚本只读环境信息，不会修改任何配置。）
+
+## 🛠️ 配套工具：codex-doctor CLI
+
+把本手册的检查与维护做成了一条条命令（零依赖，Node 18.15+）：
+
+```bash
+npx -y @qqq123456789/codex-doctor doctor      # 环境自检
+npx -y @qqq123456789/codex-doctor --help      # 查看全部命令
+```
+
+环境自检、会话/日志归档（预演制）、配置与凭据备份恢复、归档管理、版本追踪——详见 [13 · codex-doctor CLI](docs/13-codex-doctor.md)。
+
+## 症状速查导航
+
+| 我遇到的症状 | 应该看 |
+|---|---|
+| 安装失败 / `codex` 命令找不到 / 想升级回滚 | [01 安装与更新](docs/01-installation.md) |
+| 登录成功但一直 **401 Unauthorized** / `Exceeded retry limit` | [02 登录与认证](docs/02-login-auth.md) + [08 报错速查](docs/08-errors-quickref.md) |
+| 403 Forbidden | [02 登录与认证](docs/02-login-auth.md) |
+| 429 / "You've hit your usage limit" 用量达上限 | [05 模型与用量限额](docs/05-models-limits.md) |
+| 超时 / stream error / 国内网络连不上 | [03 网络与代理](docs/03-network-proxy.md) |
+| 想用第三方中转 / 配置不生效 | [04 config.toml 配置](docs/04-config.md) |
+| Windows 写文件被拒 / 沙箱报错 / 想在 WSL 里跑 | [06 沙箱与 Windows](docs/06-sandbox-windows.md) |
+| MCP 工具不出现 / MCP server 启动失败 | [07 MCP 配置](docs/07-mcp.md) |
+| VS Code / Cursor 插件里 401、配置不生效 | [10 IDE 集成](docs/10-ide-vscode.md) |
+| 想把 Codex 用得更快更省（命令 / 项目记忆 / 脚本化） | [11 效率技巧](docs/11-tips.md) |
+| 想看完整实战：从零用 Codex 做一个项目 | [12 实战演练](docs/12-walkthrough.md) |
+| 想要一条命令完成自检/清理/备份 | [13 codex-doctor CLI](docs/13-codex-doctor.md) |
+| 想清理 / 备份 / 迁移机器 / 完全重置 | [09 日常维护](docs/09-maintenance.md) |
+| 想看 Codex 出了哪些新版本 | [版本追踪](docs/releases.md)（CI 每周自动更新） |
+
+## 文档目录
+
+```
+docs/
+├── 01-installation.md      安装、更新与回滚（npm / brew / 二进制）
+├── 02-login-auth.md        登录与认证：401 / 403 排障决策树
+├── 03-network-proxy.md     网络与代理：超时、断流、镜像加速
+├── 04-config.md            config.toml：根级键位置、第三方中转、profiles
+├── 05-models-limits.md     模型选择与用量限额（429）
+├── 06-sandbox-windows.md   审批/沙箱模式、Windows 原生与 WSL2 方案
+├── 07-mcp.md               MCP server 配置与排障
+├── 08-errors-quickref.md   常见报错速查表（报错关键词 → 处理方案）
+├── 09-maintenance.md       日常维护：升级、清理、备份、迁移、重置
+├── 10-ide-vscode.md        IDE 集成：VS Code / Cursor 插件排障
+├── 11-tips.md              效率技巧：斜杠命令、AGENTS.md 项目记忆、codex exec
+├── 12-walkthrough.md       实战演练：从零用 Codex 搭一个项目
+├── 13-codex-doctor.md      codex-doctor CLI 使用手册
+└── releases.md             Codex 版本追踪（CI 每天自动生成）
+
+> 🌍 所有主题文档均有英文版（`docs/*.en.md`，共 13 篇），目录树不一一列出；中英版本在文首互链。
+scripts/
+├── codex-doctor.ps1        Windows 环境自检脚本
+├── codex-doctor.sh         macOS / Linux / WSL 环境自检脚本
+├── check-links.sh          Markdown 相对链接检查（CI 同款）
+├── check-consistency.sh    结构一致性检查（CI 同款）
+└── gen-releases.mjs        版本追踪生成器（CI 每天运行）
+tool/
+└── cli.mjs 等              codex-doctor CLI（零依赖 Node 维护工具，见 docs/13）
+```
+
+## 通用排查五步法
+
+不管遇到什么报错，按这个顺序走一遍能解决 80% 的问题：
+
+1. **确认版本**：`codex --version`，老版本先升级（很多 bug 是版本-specific 的）；
+2. **确认状态**：在 Codex 交互界面输入 `/status`，核对当前模型、provider、审批/沙箱模式是不是你以为的那样；
+3. **跑自检脚本**：`scripts/codex-doctor`，重点看网络连通性和配置文件检查项；
+4. **看日志**：`~/.codex/log/` 下有运行日志，报错上下文往往比终端一句话详细得多；
+5. **最小化复现**：换一个空目录 + 备份并移走 `~/.codex/config.toml` 后重新登录测试，排除配置残留干扰（[09 日常维护](docs/09-maintenance.md)）。
+
+## 如何贡献
+
+💬 只想提问、讨论？直接去 [Discussions](https://github.com/qlw088697-ui/codex-troubleshooting/discussions) 开帖，不必改文件。
+
+欢迎补充新的「症状 + 原因 + 解法」！请阅读 [CONTRIBUTING.md](CONTRIBUTING.md)，格式很简单，注意**脱敏**（不要贴 `auth.json`、API Key、真实邮箱）。
+
+## 参考资源
+
+- [openai/codex — 官方仓库](https://github.com/openai/codex)（Issues 区本身就是最好的排障库）
+- [Codex 官方文档](https://developers.openai.com/codex/)
+- 社区排障文章（本手册部分案例来源）：
+  - [Codex 插件 ChatGPT 登录成功但一直 401 Unauthorized — CSDN](https://blog.csdn.net/baobao181/article/details/157249679)
+  - [Codex 报 401 / 无响应？99% 是这两个配置文件问题 — 知乎](https://zhuanlan.zhihu.com/p/2054216866801902921)
+  - [Codex CLI 认证故障分层排查：401、403、浏览器回调与 429 — 腾讯云](https://cloud.tencent.com/developer/article/2713604)
+  - [Windows 版 401、配置不生效排查 — 知乎](https://zhuanlan.zhihu.com/p/2052467135138490173)
+  - [Codex CLI Windows 避坑指南：从安装到沙箱报错 — 腾讯云](https://cloud.tencent.com/developer/article/2716156)
+  - [WSL 环境 Codex 登录问题完全解决方案 — CSDN](https://blog.csdn.net/gxy03/article/details/157246287)
+  - [官方社区：stream disconnected before completion](https://community.openai.com/t/bug-codex-stream-disconnected-before-completion-on-backend-api-codex-responses-feb-8-2026/1373656)
+
+## License
+
+[MIT](LICENSE) © 2026

package/docs/01-installation.en.md

@@ -0,0 +1,102 @@
+English | [中文](01-installation.md)
+
+# 01 · Installation, Update & Rollback
+
+> Applies to: Windows / macOS / Linux / WSL. Keywords: `command not found`, `EACCES`, `EPERM`, `ERR_SOCKET_TIMEOUT`, `running scripts is disabled`
+
+## Three ways to install
+
+```bash
+# 1) npm (cross-platform, needs Node.js 20+ — use the current LTS)
+npm install -g @openai/codex
+
+# 2) Homebrew (macOS / Linux)
+brew install codex
+
+# 3) Binary (no Node dependency)
+# Download the archive for your platform from https://github.com/openai/codex/releases,
+# extract it, and put the executable on your PATH
+```
+
+Verify:
+
+```bash
+codex --version
+```
+
+## Windows advice
+
+- Native Windows (PowerShell / CMD) works out of the box; if you hit sandbox or permission problems, the community's most reliable path is WSL2 — see [06 Sandbox & Windows](06-sandbox-windows.en.md).
+- A global npm install creates `codex.cmd` / `codex.ps1` under `C:\Users\<you>\AppData\Roaming\npm`, which is on PATH by default; if you customized the npm prefix, add that directory to PATH manually.
+
+## Common install problems
+
+### `codex: command not found`
+
+**Cause**: the npm global bin directory is not on PATH, or the terminal wasn't restarted after install.
+
+**Steps**:
+
+1. Find the global directory:
+   ```bash
+   npm config get prefix        # Windows
+   npm bin -g 2>/dev/null || npm config get prefix   # macOS/Linux
+   ```
+2. Add that directory (Windows) or its `bin` subdirectory (macOS/Linux) to PATH;
+3. **Close and reopen the terminal** — PATH changes don't affect already-open sessions;
+4. Still failing: reinstall once and read the install log for the real error.
+
+### PowerShell: "running scripts is disabled"
+
+**Cause**: npm launches codex via `codex.ps1` on Windows, and the default execution policy blocks it.
+
+**Steps**:
+
+```powershell
+Set-ExecutionPolicy -Scope CurrentUser RemoteSigned
+```
+
+Then reopen the terminal. This only affects the current user and is the recommended safe default.
+
+### `EACCES` / `EPERM` during `npm install -g`
+
+**Cause**: no write permission on the npm global directory. **Do not force it with `sudo`** — it makes the mess worse.
+
+**Steps** (macOS / Linux): manage Node with nvm so global installs land in your home directory:
+
+```bash
+curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/master/install.sh | bash
+nvm install --lts
+npm install -g @openai/codex
+```
+
+On Windows: run the install once as administrator, or move the global prefix into your user directory with `npm config set prefix`.
+
+### Install times out / `ERR_SOCKET_TIMEOUT` / download interrupted
+
+**Cause**: the default npm registry is unstable on some networks — it's a network problem, not a Node problem.
+
+**Steps**: switch the registry and retry (more in [03 Network & proxy](03-network-proxy.en.md)):
+
+```bash
+npm config set registry https://registry.npmmirror.com
+npm install -g @openai/codex
+```
+
+## Update & rollback
+
+```bash
+# current version
+codex --version
+
+# update (npm)
+npm install -g @openai/codex@latest
+
+# update (brew)
+brew upgrade codex
+
+# roll back to a specific version (see npm / Releases pages for numbers)
+npm install -g @openai/codex@<version>
+```
+
+> 💡 Note the current version before upgrading so you can always roll back. `~/.codex/config.toml` is not overwritten by upgrades, but after a major upgrade it's worth a config review per [09 Maintenance](09-maintenance.en.md).

package/docs/01-installation.md

@@ -0,0 +1,101 @@
+# 01 · 安装、更新与回滚
+
+> 适用：Windows / macOS / Linux / WSL。报错关键词：`command not found`、`codex 不是内部或外部命令`、`EACCES`、`EPERM`、`ERR_SOCKET_TIMEOUT`
+>
+> English version: [01-installation.en.md](01-installation.en.md)
+
+## 三种安装方式
+
+```bash
+# 方式一：npm（跨平台，需要 Node.js 20+，建议用当前 LTS 版本）
+npm install -g @openai/codex
+
+# 方式二：Homebrew（macOS / Linux）
+brew install codex
+
+# 方式三：二进制（不依赖 Node）
+# 到 https://github.com/openai/codex/releases 下载对应平台的压缩包，解压后把可执行文件放进 PATH
+```
+
+安装后验证：
+
+```bash
+codex --version
+```
+
+## Windows 安装建议
+
+- Windows 原生（PowerShell / CMD）可以直接用；如果遇到沙箱、权限类问题，社区最稳的路径是 WSL2，见 [06 沙箱与 Windows](06-sandbox-windows.md)。
+- npm 全局安装会在 `C:\Users\<你>\AppData\Roaming\npm` 下生成 `codex.cmd` / `codex.ps1`，该目录默认在 PATH 里；如果你自定义过 npm prefix，需要手动把它加进 PATH。
+
+## 常见安装问题
+
+### `codex: command not found` / `codex 不是内部或外部命令`
+
+**原因**：npm 全局 bin 目录不在 PATH 里，或者安装后没有重开终端。
+
+**解决步骤**：
+
+1. 查看全局 bin 目录：
+   ```bash
+   npm config get prefix        # Windows
+   npm bin -g 2>/dev/null || npm config get prefix   # macOS/Linux
+   ```
+2. 把输出目录（Windows）或其下的 `bin` 目录（macOS/Linux）加入 PATH；
+3. **关闭并重开终端**再试（PATH 改动对已打开的会话不生效）；
+4. 仍不行就重装一次，观察安装日志里有没有报错。
+
+### PowerShell 提示「禁止运行脚本」（execution policy）
+
+**原因**：npm 在 Windows 上通过 `codex.ps1` 启动，PowerShell 默认执行策略拦截了它。
+
+**解决步骤**：
+
+```powershell
+Set-ExecutionPolicy -Scope CurrentUser RemoteSigned
+```
+
+然后重开终端。这条策略只影响当前用户，是官方推荐的安全默认值。
+
+### `EACCES` / `EPERM` 权限错误（npm 安装时）
+
+**原因**：npm 全局目录没有写权限。**不要用 `sudo` 硬装**，会把权限问题越搞越乱。
+
+**解决步骤**（macOS / Linux）：用 nvm 管理 Node，全局安装自然落在用户目录：
+
+```bash
+curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/master/install.sh | bash
+nvm install --lts
+npm install -g @openai/codex
+```
+
+Windows 下则以管理员身份运行一次安装，或者用 `npm config set prefix` 把全局目录改到用户目录下。
+
+### 安装超时 / `ERR_SOCKET_TIMEOUT` / 下载中断
+
+**原因**：默认 npm 源在国内网络下不稳定，属于网络问题而不是 Node 问题。
+
+**解决步骤**：换镜像源后重装（更多见 [03 网络与代理](03-network-proxy.md)）：
+
+```bash
+npm config set registry https://registry.npmmirror.com
+npm install -g @openai/codex
+```
+
+## 更新与回滚
+
+```bash
+# 查看当前版本
+codex --version
+
+# npm 安装的更新
+npm install -g @openai/codex@latest
+
+# brew 安装的更新
+brew upgrade codex
+
+# 回滚到指定版本（版本号去 npm 或 Releases 页面查）
+npm install -g @openai/codex@<版本号>
+```
+
+> 💡 升级前记下当前版本号，出问题随时可回滚；`~/.codex/config.toml` 不会被升级覆盖，但大版本升级后建议按 [09 日常维护](09-maintenance.md) 做一次配置核对。

package/docs/02-login-auth.en.md

@@ -0,0 +1,121 @@
+English | [中文](02-login-auth.md)
+
+# 02 · Login & Authentication (where most 401/403 live)
+
+> Keywords: `401 Unauthorized`, `Exceeded retry limit, last error: 401`, `403 Forbidden`, `Not logged in`, logged in fine but no response
+
+## Two auth methods — first figure out which one you're using
+
+| Method | Command | Billing | Stored in |
+|---|---|---|---|
+| ChatGPT account (Plus / Pro / Team subscriptions) | `codex login` | Subscription quota | `tokens` in `~/.codex/auth.json` |
+| API Key | `codex login --api-key` or env `OPENAI_API_KEY` | Pay per use | `auth.json` or environment variable |
+
+Both can coexist — and that is the root of most 401s: **credentials from A sent to the endpoint of B**.
+
+## The 401 decision tree
+
+Ask these five questions in order:
+
+### ① Where is the request actually going?
+
+Look at the URL in the terminal error (or search for URLs in `~/.codex/log/`):
+
+- `chatgpt.com` / `api.openai.com` → official endpoints;
+- Any third-party domain → a leftover relay provider config. See the checklist in [04 config.toml](04-config.en.md).
+
+### ② Is a third-party key being sent to official endpoints?
+
+A relay-bought `sk-xxx` sent to `api.openai.com` will always 401 — and vice versa. Fixes:
+
+- Official account: remove custom `model_providers` and the root `model_provider` from `config.toml`, remove `OPENAI_BASE_URL` from the environment, then `codex login` again;
+- Relay: make sure the root `model_provider` points at the matching provider (see [04](04-config.en.md)).
+
+### ③ Is the login state expired or corrupted?
+
+`Exceeded retry limit, last error: 401 Unauthorized` is almost always login state:
+
+```bash
+codex logout
+codex login
+```
+
+Still failing — clear credentials completely and re-login (quit Codex and IDE extensions first):
+
+```bash
+rm ~/.codex/auth.json
+codex login
+```
+
+VS Code / Cursor users: run "Developer: Reload Window" once after re-login so the extension refreshes its cached credentials.
+
+### ④ Any leftover environment variables?
+
+Env vars silently override what you think is configured:
+
+```bash
+env | grep -i openai        # macOS / Linux
+Get-ChildItem Env: | Where-Object Name -like "*OPENAI*"   # PowerShell
+```
+
+Delete stale `OPENAI_API_KEY` / `OPENAI_BASE_URL` and reopen the terminal. Watch out: one-click setup scripts often persist them into shell profiles (`.bashrc` / PowerShell `$PROFILE`) — editing the current session is not enough.
+
+### ⑤ Logged into ChatGPT fine, but sessions still 401?
+
+The most-reported 401 scenario: **the login flow is fine, the configuration conflicts** — a leftover relay provider or env var is redirecting requests elsewhere. Walk the checklist in [04](04-config.en.md). If nothing surfaces, do the full reset in [09 Maintenance](09-maintenance.md) (backup, delete `~/.codex`, log in again). If it disappears afterwards, it was stale config/credentials.
+
+## 403 Forbidden
+
+401 = "we don't know who you are"; 403 = "we know you, but no":
+
+- Account (or org) lacks access to the requested model;
+- Regional restrictions on some services/models;
+- Enterprise / team workspace policy.
+
+Check entitlements, or switch to a model you do have access to (`/model`).
+
+## Login callback fails / no browser: device-code login
+
+On headless boxes / remote SSH / when the default browser is broken, the OAuth callback hangs. Use device-code login and authorize on any device with a browser:
+
+```bash
+codex login --device-auth
+```
+
+Three failure modes:
+
+| Symptom | Cause | Fix |
+|---|---|---|
+| Never reach the code-entry page, fails immediately | **Device-code auth is disabled by default** | ChatGPT web → Settings → Security → enable "Enable device code authorization for Codex", then retry |
+| `token exchange failed` | Stale session interference | `codex logout` first, then `codex login --device-auth` |
+| `Invalid device code` | Code expired (very short TTL) | Re-run to generate a fresh code and enter it promptly |
+
+> Field references: [openai/codex #25670](https://github.com/openai/codex/issues/25670), [OpenAI community: token exchange failed](https://community.openai.com/t/codex-cli-desktop-auth-failed-with-token-exchange-failed/1385469)
+
+## WSL: login succeeds but credentials never arrive
+
+WSL and Windows localhost are isolated: the browser that `codex login` opens authorizes on the Windows side, and the callback cannot reach codex inside WSL. In order of preference:
+
+1. **Mirrored networking on newer WSL2**: put `networkingMode=mirrored` in `.wslconfig` (Windows user dir), restart WSL — usually fixes it outright;
+2. **Copy credentials manually**: complete login on the Windows side, then from WSL:
+   ```bash
+   mkdir -p ~/.codex
+   cp /mnt/c/Users/<WindowsUsername>/.codex/auth.json ~/.codex/auth.json
+   ```
+   The CLI in WSL now uses your subscription quota; redo this when the token eventually expires;
+3. Still failing: check WSL-side proxy in [03 Network & proxy](03-network-proxy.md) — inside WSL, `127.0.0.1` points to WSL itself.
+
+> Field reference: [Complete fix for Codex login in WSL — CSDN](https://blog.csdn.net/gxy03/article/details/157246287)
+
+## What is auth.json
+
+`~/.codex/auth.json` holds credentials, roughly two shapes:
+
+```jsonc
+// ChatGPT login
+{ "tokens": { "id_token": "...", "access_token": "...", "refresh_token": "...", "account_id": "..." }, "OPENAI_API_KEY": null }
+// API key mode
+{ "OPENAI_API_KEY": "sk-..." }
+```
+
+> 🔒 This file is a password: always redact it before posting or screenshotting; when migrating machines, back it up separately and never commit it to any repository.