@qqq123456789/codex-doctor 0.2.0

package/docs/06-sandbox-windows.en.md

@@ -0,0 +1,74 @@
+English | [中文](06-sandbox-windows.md)
+
+# 06 · Approvals, Sandbox & Windows
+
+> Keywords: `sandbox`, `exec denied`, writes refused, commands intercepted, sandbox quirks on Windows
+
+## Two core concepts
+
+| Setting | Values | Meaning |
+|---|---|---|
+| `approval_policy` | `untrusted` / `on-failure` / `on-request` / `never` | When you get asked to confirm |
+| `sandbox_mode` | `read-only` / `workspace-write` / `danger-full-access` | Which files the model may touch |
+
+Common presets:
+
+```bash
+codex                                   # default: conservative, safety first
+codex --full-auto                       # workspace-write + fewer interruptions — the daily-driver balance
+codex --dangerously-bypass-approvals-and-sandbox   # everything off — see the risk note below
+```
+
+> ⚠️ **Risk note**: bypassing approvals and sandbox lets the model run arbitrary commands and read/write arbitrary files with your user privileges. Reserve it for disposable containers / VMs — don't run it long-term on your daily machine.
+
+## Common problems
+
+### Writes refused / commands intercepted
+
+The sandbox is working, not broken. In order:
+
+1. `/status` to confirm the current `approval_policy` and `sandbox_mode`;
+2. `read-only` refuses all writes — switch to `workspace-write` for daily development;
+3. Writes **outside** the project directory (system dirs, your home dir) are refused too — keep projects in a normal user directory, not system-protected locations;
+4. Dependency installs / builds that keep getting intercepted: approve them in the prompt; for recurring commands, adjust the policy instead of clicking every time.
+
+### "Trust this folder" prompt on every launch
+
+Newer versions no longer trust directories by default and ask on first use. If the prompt keeps coming back:
+
+1. Choose to trust the directory, then **restart the session**;
+2. `/status` to confirm trust state and the approval/sandbox settings took effect;
+3. VS Code users: also mark the folder as a Trusted Workspace in VS Code and reload the window — **both** sides must trust it;
+4. Still prompting on every launch: upgrade to the latest version — the prompt's persistence has been fixed repeatedly across versions (see [openai/codex #14547](https://github.com/openai/codex/issues/14547), [#14345](https://github.com/openai/codex/issues/14345)).
+
+> Don't reach for `--dangerously-bypass-approvals-and-sandbox` just to skip the prompt — that's a different, bigger risk (see above).
+
+### Sandbox quirks on native Windows
+
+Native Windows support is still maturing; most reported issues concentrate in the sandbox implementation:
+
+- Upgrade to the latest version first (sandbox fixes land frequently);
+- Make sure PowerShell execution policy isn't blocking scripts (see [01](01-installation.md));
+- Stably reproducible even after upgrading → use the WSL2 route below, the most compatible path;
+- Sharing projects between Windows and WSL causes "corrupted files / line-ending warnings": add a `.gitattributes` to pin line endings (e.g. `* text=auto eol=lf`) and stop the CRLF/LF ping-pong;
+- Scripts and CI that need a fixed shell: specify the shell explicitly instead of relying on "the default shell" — on Windows it differs by terminal (PowerShell / cmd / Git Bash).
+
+## WSL2 route (the most reliable path)
+
+```powershell
+# Admin PowerShell (installs Ubuntu by default)
+wsl --install
+```
+
+Then install Node and Codex inside Ubuntu per [01](01-installation.md). Key points:
+
+1. **Keep project files inside the WSL filesystem** (e.g. `~/projects/...`), not `/mnt/c/...` — cross-filesystem I/O is several times slower and permission behavior gets weird;
+2. VS Code: install the "WSL" extension, connect into WSL, then install the CLI and extension inside WSL — behaves like native Linux;
+3. Proxy must be configured separately inside WSL ([03](03-network-proxy.md)) — inside WSL, `127.0.0.1` points to WSL itself. Newer WSL2 offers a mirrored networking mode that shares the Windows-side proxy; alternatively enable "allow LAN connections" in your proxy client and point WSL at the Windows host gateway IP. Login-callback problems (browser authorized but credentials never arrive in WSL) are covered in [02's WSL section](02-login-auth.en.md).
+
+## When do you actually need danger-full-access
+
+- Automation inside Docker / VMs / disposable cloud boxes;
+- You know exactly what the model will do, and the task genuinely requires broad system access.
+
+Even then, try `workspace-write` first — it covers most development work.

package/docs/06-sandbox-windows.md

@@ -0,0 +1,74 @@
+# 06 · 审批、沙箱与 Windows
+
+> 报错关键词：`sandbox`、`exec denied`、写入文件被拒、命令被拦截、Windows 下各种沙箱异常
+>
+> English version: [06-sandbox-windows.en.md](06-sandbox-windows.en.md)
+
+## 两个核心概念
+
+| 配置 | 可选值 | 含义 |
+|---|---|---|
+| `approval_policy` | `untrusted` / `on-failure` / `on-request` / `never` | 什么时候要你点确认 |
+| `sandbox_mode` | `read-only` / `workspace-write` / `danger-full-access` | 模型能碰哪些文件、能不能联网 |
+
+常用组合：
+
+```bash
+codex                                   # 默认：较保守，安全优先
+codex --full-auto                       # workspace-write + 少打扰，日常开发的平衡点
+codex --dangerously-bypass-approvals-and-sandbox   # 全关，见下方风险提示
+```
+
+> ⚠️ **风险提示**：完全绕过审批与沙箱等于让模型直接以你的用户权限执行任意命令、读写任意文件。只应在**一次性容器 / 虚拟机**里使用，不要在日常工作机上长期使用。
+
+## 常见问题
+
+### 模型想写文件被拒 / 命令被拦截
+
+这是沙箱在正常工作，不是 bug。处理顺序：
+
+1. 用 `/status` 确认当前 `approval_policy` 和 `sandbox_mode`；
+2. `read-only` 模式下所有写操作都会被拒——日常开发切到 `workspace-write`；
+3. 写入目标在项目目录**外**（比如系统目录、用户主目录）也会被拒——把项目放到普通用户目录下，别放在受系统保护的位置；
+4. 需要装依赖、跑构建这类被拦的命令，在审批弹窗里批准即可；总是被拦的固定命令考虑调整策略而不是次次手点。
+
+### 每次启动都弹「信任此目录」（Trust this folder）
+
+新版本出于安全考虑不再默认信任目录，首次在某个目录使用会询问。弹窗反复出现的处理：
+
+1. 在提示里选择信任该目录，然后**重启会话**；
+2. 用 `/status` 确认信任状态与审批/沙箱模式已生效；
+3. VS Code 用户：同时把该文件夹在 VS Code 里设为 Trusted Workspace 并重载窗口——两边都信任后才不再重复询问；
+4. 仍每次都弹：升级到最新版，这个提示的持久化在不同版本间反复修过（参考 [openai/codex #14547](https://github.com/openai/codex/issues/14547)、[#14345](https://github.com/openai/codex/issues/14345)）。
+
+> 不要为了跳过提示就长期使用 `--dangerously-bypass-approvals-and-sandbox`——那是另一层风险（见上文）。
+
+### Windows 原生版沙箱异常
+
+Windows 原生支持仍在持续完善，社区常见问题集中在沙箱实现上：
+
+- 升级到最新版再试（沙箱相关修复很频繁）；
+- 确认 PowerShell 执行策略没拦脚本（见 [01](01-installation.md)）；
+- 报错稳定复现且升级无效 → 走 WSL2 方案，兼容性最好；
+- 项目在 Windows 与 WSL 间共享时大量「文件被改坏 / 行尾报警」：加 `.gitattributes` 统一行尾（如 `* text=auto eol=lf`），避免 CRLF/LF 反复横跳；
+- 脚本、CI 里需要固定 shell 的：显式指定 shell，别依赖「默认 shell」——Windows 上默认 shell 随终端（PowerShell / cmd / Git Bash）不同而不同。
+
+## WSL2 方案（社区最稳路径）
+
+```powershell
+# 管理员 PowerShell 里安装 WSL2（默认装 Ubuntu）
+wsl --install
+```
+
+然后在 Ubuntu 里按 [01](01-installation.md) 正常安装 Node 和 Codex。要点：
+
+1. **项目文件放在 WSL 文件系统里**（如 `~/projects/...`），不要放在 `/mnt/c/...`——跨文件系统 I/O 慢好几倍，权限行为也容易出怪问题；
+2. VS Code 用「WSL」扩展连入 WSL，再在 WSL 内运行 Codex，体验和原生一致；
+3. WSL 里的代理要单独配置（[03 网络与代理](03-network-proxy.md)），`127.0.0.1` 指向的是 WSL 自己；新版 WSL2 可用 mirrored 网络模式共享 Windows 侧代理，或在代理客户端里开启「允许局域网连接」并写 Windows 主机在 WSL 里的网关 IP。登录回调类问题（浏览器授权后凭据回不到 WSL）见 [02 的 WSL 小节](02-login-auth.md)。
+
+## 什么时候才需要 `danger-full-access`
+
+- 在 Docker / VM / 一次性云主机里跑自动化任务；
+- 明确知道模型要做什么，且任务本身需要大范围系统访问。
+
+即使在这些场景，也建议先试 `workspace-write`——大部分开发任务它就够了。

package/docs/07-mcp.en.md

@@ -0,0 +1,55 @@
+English | [中文](07-mcp.md)
+
+# 07 · MCP Configuration & Troubleshooting
+
+> Keywords: MCP tools missing, MCP server fails to start, tool call timeouts
+
+## Basic configuration
+
+MCP servers are configured in `~/.codex/config.toml` (remember [04](04-config.en.md): tables go below root keys):
+
+```toml
+[mcp_servers.context7]
+command = "npx"
+args = ["-y", "@upstash/context7-mcp"]
+
+[mcp_servers.filesystem]
+command = "npx"
+args = ["-y", "@modelcontextprotocol/server-filesystem", "D:/projects"]
+env = { "SOME_VAR" = "value" }
+```
+
+**Restart the Codex session** after config changes — servers are launched per session.
+
+## Gotcha #1 on Windows: wrap `npx` with `cmd`
+
+On Windows, `command = "npx"` directly often fails to start (`.cmd` resolution). Wrap it:
+
+```toml
+[mcp_servers.context7]
+command = "cmd"
+args = ["/c", "npx", "-y", "@upstash/context7-mcp"]
+```
+
+Check this first whenever tools don't show up on Windows — it resolves most "configured MCP but nothing happens" cases.
+
+## Tools not showing up: ordered checklist
+
+1. **Restart the session** — config only applies to new sessions;
+2. **Verify the server actually starts**: run `command + args` manually in a terminal — a stdio server should start and wait for input (Ctrl+C to quit);
+   - "command not found" → `npx`/`node` not on PATH;
+   - "module not found" → wrong package name, or `npm i -g` needed first;
+3. **Windows** → check whether the `cmd /c` wrapper is needed (see above);
+4. **Confirm the section name** is `[mcp_servers.<name>]`, not some variant like `[mcp.<name>]`;
+5. Try renaming the server — duplicate names or special characters can break loading;
+6. Still failing: search `~/.codex/log/` for MCP-related errors.
+
+## Call errors / timeouts
+
+- **Timeouts**: the server itself is slow (e.g. fetches remote data) — use a faster source or increase timeouts if your version supports it;
+- **Auth failures**: for HTTP-based servers, put required headers/tokens into `env` or per the server's docs;
+- **One broken server slows startup**: comment out the servers you don't use and bisect to find the culprit.
+
+## Environment variables note
+
+If `env = { ... }` depends on variables from your shell, remember Codex may be launched from a different environment than your terminal (e.g. IDE-launched processes don't read `.bashrc`). Putting the value directly into `env` is more reliable — but **never commit sensitive keys to any repository**.

package/docs/07-mcp.md

@@ -0,0 +1,57 @@
+# 07 · MCP 配置与排障
+
+> 报错关键词：MCP 工具不出现、`mcp server` 启动失败、工具调用超时
+>
+> English version: [07-mcp.en.md](07-mcp.en.md)
+
+## 基本配置
+
+MCP server 配置在 `~/.codex/config.toml`（注意 [04](04-config.md) 说的：表要放在根级键之后）：
+
+```toml
+[mcp_servers.context7]
+command = "npx"
+args = ["-y", "@upstash/context7-mcp"]
+
+[mcp_servers.filesystem]
+command = "npx"
+args = ["-y", "@modelcontextprotocol/server-filesystem", "D:/projects"]
+env = { "SOME_VAR" = "value" }
+```
+
+修改配置后**重启 Codex 会话**才会重新拉起 MCP server。
+
+## Windows 上的第一大坑：npx 需要 cmd 包装
+
+Windows 下直接 `command = "npx"` 经常起不来（`.cmd` 解析问题）。用 cmd 包一层：
+
+```toml
+[mcp_servers.context7]
+command = "cmd"
+args = ["/c", "npx", "-y", "@upstash/context7-mcp"]
+```
+
+工具不出现先查这一条，能解决 Windows 下的大多数「MCP 配置了但没反应」。
+
+## 工具不出现的排查步骤
+
+按顺序：
+
+1. **重启会话**——配置只在新会话生效；
+2. **手动验证 server 能不能启动**：把 `command + args` 拼起来在终端直接跑，看是否正常输出/挂起等待（stdio 型 server 正常时会等待输入，Ctrl+C 退出）；
+   - 报「命令不存在」→ `npx`/`node` 不在 PATH 里；
+   - 报模块找不到 → 包名写错，或需要先 `npm i -g`；
+3. **Windows** → 检查是否需要 `cmd /c` 包装（见上）；
+4. **确认配置段落名**是 `[mcp_servers.<name>]`，不是 `[mcp.<name>]` 之类的变体；
+5. 换个名字试试——server 名重复或含特殊字符可能导致加载失败；
+6. 仍不行，看 `~/.codex/log/` 日志里 MCP 相关报错。
+
+## 调用报错 / 超时
+
+- **超时**：server 本身响应慢（比如联网拉数据的），换更快的源或加大超时（如版本支持相应配置项）；
+- **认证失败**：HTTP 型 MCP 需要的 header/token 配进 `env` 或按 server 文档配置；
+- **一个 server 崩了拖慢启动**：把不常用的 server 注释掉，二分定位是哪一个的问题。
+
+## 环境变量注意
+
+`env = { ... }` 里引用的 Key 如果依赖你 shell 里的环境变量，注意 Codex 启动环境可能和你当前终端不同（比如从 IDE 启动时读不到 `.bashrc` 里的变量）——直接把值写进 `env` 更可靠，但注意**别把敏感 Key 提交进任何仓库**。

package/docs/08-errors-quickref.en.md

@@ -0,0 +1,53 @@
+# 08 · Error Quick Reference (English)
+
+> Usage: Ctrl+F for the keyword from your terminal → follow the row to the full guide. The full guides are in Chinese; commands and error strings are universal.
+>
+> 中文版见 [08-errors-quickref.md](08-errors-quickref.md)。
+
+## Status codes first
+
+| Code | Meaning | Details |
+|---|---|---|
+| `401` | Authentication failed — invalid/expired credentials, or credentials sent to the wrong endpoint | [02 Login & auth](02-login-auth.md) |
+| `403` | Authorization failed — authenticated but not permitted (model access / region / org policy) | [02 Login & auth](02-login-auth.md) |
+| `429` | Usage — quota exhausted or rate limited | [05 Models & limits](05-models-limits.md) |
+| `5xx` | Server / relay outage | Retry later; relay users check relay status first |
+
+## Error keyword → fix
+
+| Error / symptom | Likely cause | Guide |
+|---|---|---|
+| `Exceeded retry limit, last error: 401 Unauthorized` | Expired/broken login state, or credential↔endpoint mismatch | [02 decision tree](02-login-auth.md) |
+| ChatGPT login succeeds but 401 persists | Config conflict: leftover third-party provider / env vars | [02 steps ②⑤](02-login-auth.md), [04 checklist](04-config.md) |
+| `403 Forbidden` | Model permission / region / org policy | [02](02-login-auth.md) |
+| `You've hit your usage limit` (429) | Subscription quota window exhausted | [05](05-models-limits.md) |
+| `insufficient_quota` | API account out of credit | [05](05-models-limits.md) |
+| `model_not_found` | Wrong model name / no access / relay doesn't serve it | [05](05-models-limits.md) |
+| `stream error` / `stream disconnected` | Unstable network path | [03 Network & proxy](03-network-proxy.md) |
+| `ETIMEDOUT` / endless spinner | Direct connection blocked or proxy not applied | [03](03-network-proxy.md) |
+| `ECONNREFUSED` | Proxy port closed or wrong | [03](03-network-proxy.md) |
+| TLS / certificate errors | Corporate MITM proxy replacing certs | [03](03-network-proxy.md) |
+| `failed to parse config` / `TOML parse error` | config.toml syntax error | [04](04-config.md) |
+| Config written but **not taking effect** | Root keys placed after a `[table]` / session not restarted | [04 gotcha](04-config.md) |
+| `codex: command not found` | PATH problem | [01 Installation](01-installation.md) |
+| `EACCES` / `EPERM` (during install) | npm global directory permissions | [01](01-installation.md) |
+| PowerShell "running scripts is disabled" | Execution policy blocking `codex.ps1` | [01](01-installation.md) |
+| Writes denied / commands intercepted | Sandbox working as intended, policy too strict | [06 Sandbox & Windows](06-sandbox-windows.md) |
+| Sandbox issues on Windows | Native support still maturing | [06](06-sandbox-windows.md), or use WSL2 |
+| MCP tools missing | Server failed to start (Windows `cmd /c` wrapper) | [07 MCP](07-mcp.md) |
+| 401 / config drift **inside VS Code / Cursor** | Shared `~/.codex` but stale IDE caches / env | [10 IDE](10-ide-vscode.md) |
+| Device-code login fails / `token exchange failed` | Device-code auth disabled by default | [02 device code](02-login-auth.md) |
+| WSL login credentials never arrive back | WSL ↔ Windows localhost isolation | [02 WSL section](02-login-auth.md) |
+| `stream disconnected before completion` | Network / OneDrive folder / very long session | [03 deep dive](03-network-proxy.md) |
+| "Trust this folder" prompt on every launch | Directory not trusted / version behavior | [06](06-sandbox-windows.md) |
+| Weekly limit reset date keeps moving | Rolling 7-day window, by design | [05](05-models-limits.md) |
+
+## The five-step triage (cheat sheet)
+
+```
+1. codex --version          ← version; upgrade first if old
+2. /status                  ← current model / provider / sandbox as expected?
+3. run the doctor script     ← scripts/codex-doctor.sh or .ps1
+4. check ~/.codex/log/       ← far more context than the terminal line
+5. minimal repro             ← empty dir + move config.toml aside + re-login
+```

package/docs/08-errors-quickref.md

@@ -0,0 +1,55 @@
+# 08 · 常见报错速查表
+
+> 用法：Ctrl+F 搜你终端里的报错关键词 → 按表跳详细文档。
+>
+> English version: [08-errors-quickref.en.md](08-errors-quickref.en.md)
+>
+> 先跑一次 [环境自检脚本](../scripts/codex-doctor.ps1)，它覆盖了本表里一半以上的检查项。
+
+## 状态码先分清
+
+| 状态码 | 含义 | 详细文档 |
+|---|---|---|
+| `401` | 认证失败——没认出你是谁（凭据无效/过期/发错端点） | [02 登录与认证](02-login-auth.md) |
+| `403` | 授权失败——认出你了，但你没权限（模型权限/地区/组织策略） | [02 登录与认证](02-login-auth.md) |
+| `429` | 用量问题——额度用完或速率超限 | [05 模型与限额](05-models-limits.md) |
+| `5xx` | 服务端/中转站故障 | 稍后重试；中转站用户先确认中转站状态 |
+
+## 报错关键词 → 处理
+
+| 报错/症状 | 大概率原因 | 去哪看 |
+|---|---|---|
+| `Exceeded retry limit, last error: 401 Unauthorized` | 登录态过期/损坏，或凭据与端点不匹配 | [02](02-login-auth.md) 决策树 |
+| ChatGPT 登录成功但一直 401 | 配置冲突：第三方 provider / 环境变量残留 | [02](02-login-auth.md) 第②⑤步、[04](04-config.md) 清单 |
+| `403 Forbidden` | 模型权限 / 地区 / 组织策略 | [02](02-login-auth.md) |
+| `You've hit your usage limit`（429） | 订阅额度窗口用完 | [05](05-models-limits.md) |
+| `insufficient_quota` | API 账户欠费 | [05](05-models-limits.md) |
+| `model_not_found` | 模型名错误 / 无权限 / 中转站不支持 | [05](05-models-limits.md) |
+| `stream error` / `stream disconnected` | 网络路径抖动（国内直连高发） | [03 网络与代理](03-network-proxy.md) |
+| `ETIMEDOUT` / 长时间转圈 | 直连被阻断或代理没生效 | [03](03-network-proxy.md) |
+| `ECONNREFUSED` | 代理端口没开/写错 | [03](03-network-proxy.md) |
+| TLS / 证书类报错 | 企业 MITM 代理替换证书 | [03](03-network-proxy.md) |
+| `failed to parse config` / `TOML parse error` | config.toml 语法错误 | [04](04-config.md) |
+| 配置写了但**不生效** | 根级键写在 `[表]` 之后 / 忘了重启会话 | [04](04-config.md) 第一大坑 |
+| `codex: command not found` | PATH 问题 | [01](01-installation.md) |
+| `EACCES` / `EPERM`（安装时） | npm 全局目录权限 | [01](01-installation.md) |
+| PowerShell「禁止运行脚本」 | 执行策略拦截 `codex.ps1` | [01](01-installation.md) |
+| 写文件被拒 / 命令被拦截 | 沙箱正常工作，策略太严 | [06 沙箱与 Windows](06-sandbox-windows.md) |
+| Windows 沙箱异常 | 原生支持不完善 | [06](06-sandbox-windows.md)，或改用 WSL2 |
+| MCP 工具不出现 | server 没起来（Windows `cmd /c` 坑） | [07 MCP](07-mcp.md) |
+| 设备码登录失败 / `token exchange failed` | 设备码授权默认未开启 | [02](02-login-auth.md) 设备码小节 |
+| WSL 登录后凭据传不回去 | WSL 与 Windows localhost 隔离 | [02](02-login-auth.md) WSL 小节 |
+| `stream disconnected before completion` | 网络 / OneDrive 同步盘 / 超长会话 | [03](03-network-proxy.md) 深挖小节 |
+| 每次启动都弹「信任此目录」 | 目录未信任 / 版本行为 | [06](06-sandbox-windows.md) |
+| 每周限额重置时间一直变 | 滚动 7 天窗口，设计如此 | [05](05-models-limits.md) |
+| VS Code 选 WSL agent 后进不去 / 崩溃 | 全局状态文件 | [10](10-ide-vscode.md) |
+
+## 通用排查五步法（速记）
+
+```
+1. codex --version          ← 版本，旧版先升级
+2. /status                  ← 当前 model / provider / 沙箱模式是否符合预期
+3. 跑自检脚本                ← scripts/codex-doctor
+4. 看日志 ~/.codex/log/      ← 报错上下文比终端一句话详细
+5. 最小化复现                ← 空目录 + 移走 config.toml 重登测试
+```

package/docs/09-maintenance.en.md

@@ -0,0 +1,77 @@
+English | [中文](09-maintenance.md)
+
+# 09 · Maintenance: Upgrade, Cleanup, Backup, Migration, Reset
+
+> For long-term Codex users: turning these routines into habits means fast recovery when things break.
+
+## A tour of `~/.codex`
+
+```
+~/.codex/
+├── config.toml    # your configuration (created/edited by you)
+├── auth.json      # login credentials (treat as a password, never share)
+├── log/           # runtime logs — the first place to look when troubleshooting
+└── sessions/      # session history (grows with usage)
+```
+
+Directory contents vary slightly between versions; trust what you actually see.
+
+## Version strategy & upgrading
+
+- **Stability first**: don't upgrade mid-sprint; upgrade between tasks and keep rollback time in reserve.
+- **Upgrade routine**:
+  ```bash
+  codex --version                          # 1. note the current version
+  npm install -g @openai/codex@latest      # 2. upgrade (brew: brew upgrade codex)
+  codex --version                          # 3. confirm the new version
+  ```
+- **Rollback**:
+  ```bash
+  npm install -g @openai/codex@<old-version>
+  ```
+- After a major upgrade, use `/status` on first run to confirm model and config behave as before — major versions occasionally change config keys.
+
+## Routine cleanup
+
+| Target | Action | Frequency |
+|---|---|---|
+| Session history `~/.codex/sessions/` | Archive or delete once you don't need to revisit them | As needed |
+| Logs `~/.codex/log/` | Safe to clear | Keep them until a problem is diagnosed first |
+| npm cache | `npm cache clean --force` | When npm misbehaves |
+
+> 💡 You don't need to stop Codex, but in-flight sessions are affected — never clean in the middle of an important task.
+
+## Backup & machine migration
+
+**Only two things need backing up**:
+
+```bash
+cp ~/.codex/config.toml ~/codex-backup-config.toml
+cp ~/.codex/auth.json  ~/codex-backup-auth.json
+```
+
+1. `config.toml` is plain text — back it up freely, read it freely;
+2. `auth.json` is a credential — **treat the backup itself as a password**: no plaintext cloud drives, never into git, delete after migrating.
+
+Restore on a new machine: install Codex, put both files back into `~/.codex/`. If an older `auth.json` causes 401, just `codex login` once more.
+
+## Full reset (the last resort)
+
+Use when: config changes never take effect, 401s with no identifiable cause, or starting from scratch. **Wipes all session history — back up first.**
+
+```bash
+# 1. back up (see above)
+# 2. log out and clear
+codex logout
+rm -rf ~/.codex
+# 3. log in again (credentials back to a pristine state)
+codex login
+# 4. rebuild config.toml against 04 — add only what you know you need, verify item by item
+```
+
+If the problem **disappears** afterwards, it was stale config/credentials; if it **persists**, follow the network & version routes in [08](08-errors-quickref.md).
+
+## Logs
+
+- Logs live in `~/.codex/log/` — the error context (full URL, status code, retries) is far richer than the terminal's one-liner; **read the log before filing an issue or asking anywhere**;
+- Redact before submitting: URLs and account info inside logs can be sensitive.

package/docs/09-maintenance.md

@@ -0,0 +1,78 @@
+# 09 · 日常维护：升级、清理、备份、迁移、重置
+
+> 面向长期使用 Codex 的用户：把这几件例行操作流程化，出问题时能快速恢复。
+>
+> English version: [09-maintenance.en.md](09-maintenance.en.md)
+
+## `~/.codex` 目录导览
+
+```
+~/.codex/
+├── config.toml    # 你的配置（自建/修改）
+├── auth.json      # 登录凭据（等同密码，勿外传）
+├── log/           # 运行日志，排障重点看这里
+└── sessions/      # 会话历史记录（占用会随使用增长）
+```
+
+不同版本目录内容略有差异，以实际为准。
+
+## 版本策略与升级
+
+- **稳定优先**：正在赶工期就别升级；升级放在任务间隙，并预留回滚时间。
+- **查最新版本**：官方 Releases 一览见 [版本追踪](releases.md)（每周自动更新）。
+- **升级流程**：
+  ```bash
+  codex --version                          # 1. 记下当前版本
+  npm install -g @openai/codex@latest      # 2. 升级（brew 用户：brew upgrade codex）
+  codex --version                          # 3. 确认新版本
+  ```
+- **回滚**：
+  ```bash
+  npm install -g @openai/codex@<旧版本号>
+  ```
+- 升级后首次使用，用 `/status` 核对模型与配置是否如常——大版本偶尔伴随配置键变更。
+
+## 例行清理
+
+| 对象 | 操作 | 频率 |
+|---|---|---|
+| 会话历史 `~/.codex/sessions/` | 确认不需要回溯后按需删除/归档 | 按需 |
+| 日志 `~/.codex/log/` | 可直接清空 | 出问题前先留档 |
+| npm 缓存 | `npm cache clean --force` | npm 异常时 |
+
+> 💡 清理前不需要停 Codex，但正在进行的会话记录会被影响，别在重要任务进行中清。
+
+## 备份与迁移机器
+
+**需要备份的只有两样**：
+
+```bash
+cp ~/.codex/config.toml ~/codex-backup-config.toml
+cp ~/.codex/auth.json  ~/codex-backup-auth.json
+```
+
+1. `config.toml` 是纯文本配置，随便备份、随便看；
+2. `auth.json` 是凭据——**备份文件本身要当作密码对待**：不要进网盘明文、不要进 git、迁移完就删。
+
+新机器恢复：装好 Codex 后把两个文件放回 `~/.codex/` 即可。如果 auth.json 较旧导致 401，重新 `codex login` 一次。
+
+## 完全重置（终极大招）
+
+适用：配置怎么改都不生效、401 查不出原因、想从零开始。**会清掉所有会话历史，先备份。**
+
+```bash
+# 1. 备份（见上节）
+# 2. 登出并清理
+codex logout
+rm -rf ~/.codex
+# 3. 重新登录（凭据回到初始状态）
+codex login
+# 4. 对照 04 篇重建 config.toml —— 建议只加你确认需要的配置，逐项验证
+```
+
+重置后如果问题**消失**，说明是旧配置/凭据残留；如果**还在**，按 [08 速查表](08-errors-quickref.md) 走网络与版本路线。
+
+## 排障日志
+
+- 日志在 `~/.codex/log/`，报错上下文（完整 URL、状态码、重试过程）通常比终端一行话详细得多，提 Issue / 求助时**先翻日志**；
+- 提交日志前脱敏：里面的 URL、账号信息可能含敏感内容。

package/docs/10-ide-vscode.en.md

@@ -0,0 +1,63 @@
+English | [中文](10-ide-vscode.md)
+
+# 10 · IDE Integration (VS Code / Cursor)
+
+> Keywords: extension won't install, 401 inside the extension, extension config not taking effect, extension behaves differently from the terminal
+
+## Understand the architecture first — it saves half the detour
+
+- The IDE extension and the CLI **share the same** `~/.codex` (`config.toml`, `auth.json`) — so the troubleshooting in [02 Login & auth](02-login-auth.en.md) and [04 config.toml](04-config.en.md) applies to the extension too;
+- The extension and the CLI are **two independently released artifacts**: upgrading one doesn't necessarily upgrade the other;
+- Step one is always recording both versions: `codex --version` in the terminal + the version shown in the extension panel.
+
+## Common problems
+
+### The extension keeps asking to log in / 401 after login
+
+1. Credentials are shared: run the [02 401 decision tree](02-login-auth.en.md) in the terminal first — if the CLI side is broken, the extension can't work;
+2. CLI fine, only the extension broken: run "Developer: Reload Window" so the extension refreshes its cached credentials;
+3. Still failing: delete `~/.codex/auth.json`, then re-login **from the extension's own login entry** (not the terminal);
+4. Multiple IDEs (VS Code + Cursor) on the same account: one side refreshing tokens can invalidate the other's session — re-login in whichever IDE shows the 401.
+
+### Changed config, the extension doesn't pick it up
+
+- `config.toml` is shared, but **already-open sessions don't hot-reload** — start a new conversation in the extension;
+- Big trap: an IDE launched from the GUI cannot read environment variables from shell profiles (`.bashrc` / PowerShell `$PROFILE`). Anything env-dependent — `OPENAI_BASE_URL`, proxy, MCP `env` — must be configured in `config.toml` / the extension settings, or injected by the IDE launcher. Hoping your terminal `export` carries over will not work.
+
+### The extension behaves differently from the terminal
+
+- Confirm which environment the IDE actually runs in: native Windows or WSL Remote (see [06](06-sandbox-windows.en.md)) — they can have **different CLI versions** and different default shells;
+- WSL users, recommended path: install the "WSL" extension → connect VS Code into WSL → install the CLI and extension inside WSL — behaves like native Linux;
+- Run `/status` in the extension and diff it against the terminal's `/status` — the difference is the problem.
+
+### Proxy: terminal works, extension doesn't
+
+The codex process launched by the IDE inherits **the IDE's environment**, not your terminal's:
+
+1. Run the [03 connectivity test](03-network-proxy.en.md) in the VS Code integrated terminal — terminal OK + extension failing = environment difference;
+2. Fix: configure the proxy at the system level (affects GUI apps), or in IDE settings, or launch the IDE from a login shell;
+3. Restart the whole IDE afterwards (not just the window).
+
+### Where are the logs
+
+- VS Code: Output panel → select the Codex output channel;
+- CLI side: `~/.codex/log/` (see [09](09-maintenance.en.md));
+- Read both before filing an issue — many "extension bugs" are CLI errors swallowed by the extension.
+
+### Update & downgrade
+
+- Extension: update from the extensions panel; "Install Another Version…" to roll back;
+- CLI: `npm install -g @openai/codex@<version>` (see [01](01-installation.en.md));
+- When something breaks after an upgrade, pin one side's version to bisect whether the extension or the CLI introduced it.
+
+### Windows: can't enter after choosing the WSL agent / crashes
+
+The "run in WSL" toggle lives in `C:\Users\<you>\.codex\codex-global-state.json`:
+
+1. Fully quit Codex / the IDE;
+2. Edit the file and set `runCodexInWindowsSubsystemForLinux` back to `false` (or delete the file to rebuild defaults);
+3. Update the WSL components/extensions from the Microsoft Store and restart — old version combinations have crash cases (see [openai/codex #13699](https://github.com/openai/codex/issues/13699)).
+
+## Cursor and other forks
+
+The same logic applies (shared `~/.codex`, shared credentials and config). Some IDE versions have extension-API compatibility quirks: retest in **vanilla VS Code** first to rule out IDE differences before digging deeper.