第 2 篇 Codex 故障排查与插件安装
报错排查 + MCP/IDE 插件配置
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
排查决策表（按症状快速定位）
症状 | 第一反应 |
401 Unauthorized | logout → login → 删 auth.json |
502/超时/Re-connecting | 设置 HTTPS_PROXY |
command not found | 查 npm prefix 加 PATH |
Node 版本错 | nvm install 22 |
model is at capacity | /model 换模型或稍后重试 |
MCP 不生效 | 重启 codex + 检查 TOML 语法 |
一切玄学问题 | 升级 latest + 重置 ~/.codex |
1. 认证类（401/登录失效）
codex logout && codex login # 第一步
rm -rf ~/.codex/auth.json # 第二步:清缓存后再 login
npm install -g @openai/codex@latest # 第三步:旧版 token 刷新有 bug
仍不行检查：是否付费套餐、是否登对账号、Key 有无多余空格。终极手段：mv ~/.codex ~/.codex_backup 重置配置目录。
2. 网络类（502/超时）
export HTTPS_PROXY=http://127.0.0.1:7890 # 端口换成用户自己的
代理干扰认证时反向禁用：http_proxy="" https_proxy="" codex ...。内网 DNS 劫持：hosts 固定 login.openai.com 的 IP。
3. 安装类
- command not found：npm config get prefix 查路径，把其下可执行目录加 PATH，重启终端
- 装错包：npm uninstall -g codex && npm install -g @openai/codex（正确包名带 @openai/ 前缀）
- Windows 权限：管理员运行 PowerShell，或用官方 install.ps1
- Linux bwrap 缺失：sudo apt-get install bubblewrap
4. 运行类
- 非 git 目录用 full-auto 被拒：保护机制，git init 后再用
- 上下文占满：/compact 压缩或 codex resume 开新会话
插件/扩展安装
IDE 扩展
扩展市场搜 "Codex" 或 "OpenAI Codex"（支持 VS Code/Cursor/Windsurf/JetBrains）。IDE 扩展与 CLI 共享 ~/.codex/config.toml 和登录凭证，配一次两边通用。
MCP 服务器
命令行方式（推荐）：
codex mcp add context7 -- npx -y @upstash/context7-mcp
codex mcp list
手动编辑 ~/.codex/config.toml：
[mcp_servers.my-postgres] # 下划线,不是连字符
command = "npx"
args = ["-y", "@modelcontextprotocol/server-postgres", "postgresql://localhost/mydb"]
[mcp_servers.remote]
url = "https://example.com/mcp"
http_headers = { Authorization = "Bearer token" }
MCP 常见坑
- 改完 config.toml 必须重启 codex
- TOML 语法：env 写 env = { KEY = "value" }，不能 JSON 冒号
- 会话内 /mcp 确认连接状态
- 项目级配置放 .codex/config.toml
万能三步
更新到最新版 → 重新登录 → 备份并清理 ~/.codex 重来。90% 问题是旧版本+旧凭证。