🆘 故障排查

401 Unauthorized

症状：Error: 401 Unauthorized 或 Invalid API key

排查清单：

1. 检查 auth.json 里 Key 是否完整复制（注意首尾空格、换行符）
2. 控制台确认 Key 状态是否为「启用」
3. Key 是否被吊销或过期
4. 是否设置了 IP 白名单但当前 IP 不在列表
5. Codex CLI 必须设 requires_openai_auth = true，否则不会带 Bearer 头

# 直接 curl 验证 Key（OpenAI 兼容协议）
curl https://nexor.nexoraivision.com/v1/models \
  -H "Authorization: Bearer YOUR_API_KEY"

返回模型 JSON 列表说明 Key 有效；返回 401 说明 Key 有问题。

模型不存在

症状：model gpt-5-codex not found 或 model xxx not supported

最常见原因：用了老的模型名。我们的模型 ID 是：

gpt-5.5
gpt-5.4
gpt-5.4-mini
gpt-5.3-codex
gpt-5.3-codex-spark
gpt-5.2
gpt-image-2
gpt-image-1.5
gpt-image-1

注意是 gpt-5.4（带点），不是 gpt-5-codex 或 gpt-5。

codex-mini-latest 已下线，如果旧配置里有这个，请改成 gpt-5.4-mini。

列出实际可用模型：

curl https://nexor.nexoraivision.com/v1/models \
  -H "Authorization: Bearer YOUR_API_KEY" | jq

修改 config.toml 里的 model = 字段为实际存在的模型名。

429 Too Many Requests

症状：Error: 429 rate limit exceeded

原因：触发了 QPM/并发上限或日额度上限。

解决：

• 降低并发（Codex CLI 单进程足够）
• 客户端实现指数退避：重试间隔 = 2^n + random()
• 检查 Key 是否设了「日额度上限」（控制台 → API Keys → 编辑 Key）
• 联系客服上调速率限制

超时 / 卡死

症状：请求长时间无响应或 connection timeout

排查步骤：

curl -v https://nexor.nexoraivision.com/v1/models

[model_providers.OpenAI]
supports_websockets = true
requires_openai_auth = true

[features]
responses_websockets_v2 = true

unset HTTPS_PROXY HTTP_PROXY
codex "test"

SSL 证书错误

症状：SSL_ERROR / unable to get local issuer certificate / CERT_HAS_EXPIRED

临时绕过（不推荐生产用）：

export NODE_TLS_REJECT_UNAUTHORIZED=0

正确做法：升级 Node.js 到最新 LTS，或重装系统 CA 证书：

# macOS
brew install ca-certificates

# Ubuntu / Debian
sudo apt update && sudo apt install -y ca-certificates && sudo update-ca-certificates

# CentOS / RHEL
sudo yum install -y ca-certificates

Codex 找不到命令

症状：codex: command not found / 'codex' is not recognized

排查：

# 检查是否已安装
which codex          # macOS / Linux
where codex          # Windows
npm list -g | grep codex

# 没有则全局安装
npm install -g @openai/codex

PATH 没生效（已安装但找不到）：

# 把 npm 全局 bin 加到 PATH（macOS/Linux）
echo 'export PATH="$(npm config get prefix)/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

# Windows PowerShell
$env:PATH += ";$(npm config get prefix)"

Windows 中文乱码

症状：终端输出中文显示成 ??? 或方块

临时解决：

chcp 65001
[Console]::OutputEncoding = [System.Text.Encoding]::UTF8

永久解决（写入 PowerShell 配置文件）：

notepad $PROFILE

文件末尾追加：

[Console]::OutputEncoding = [System.Text.Encoding]::UTF8
[Console]::InputEncoding  = [System.Text.Encoding]::UTF8

保存后重开 PowerShell 即生效。

Windows 路径找不到 .codex 目录

症状：CC-Switch 应用后还是不生效，或手动改了 config.toml 没反应

原因：你改的不是 Codex 实际读取的位置。

# 看 Codex 实际读哪个 config
codex config show

# 该路径在 Windows 上通常是
C:\Users\你的用户名\.codex\config.toml

按 Win+R → 输入 %userprofile%\.codex 直接打开 Codex 配置目录。如果目录不存在，先在资源管理器里手动新建一个 .codex 文件夹。

CC-Switch 配置后 Codex 仍然报错

排查：

1. 检查 CC-Switch 是否真的写入了文件：

   # macOS / Linux
   cat ~/.codex/config.toml
   cat ~/.codex/auth.json
   
   # Windows PowerShell
   Get-Content $env:USERPROFILE\.codex\config.toml
   Get-Content $env:USERPROFILE\.codex\auth.json
   

2. 文件存在但格式错误？删掉两个文件，重新用 CC-Switch 配置一次
3. 终端窗口需要重开（环境变量缓存）
4. 检查是否被环境变量 OPENAI_API_KEY 覆盖：

   echo $OPENAI_API_KEY      # macOS/Linux
   echo $env:OPENAI_API_KEY  # Windows
   

   
   如果有值且不是你想要的，unset OPENAI_API_KEY 清掉。

OpenCode 启动报错或看不到模型

症状：opencode 启动后选 provider 时找不到 Nexoraivision

排查：

# macOS / Linux
cat ~/.config/opencode/opencode.json

# Windows
type %APPDATA%\opencode\opencode.json

确认文件存在且 JSON 语法正确（用 jsonlint.com 校验）。

baseURL 必须带 /v1：

"baseURL": "https://nexor.nexoraivision.com/v1"

详见 OpenCode 配置。

wire_api 报错 / 协议不匹配

症状：Unknown API version / Unsupported wire format

原因：wire_api 字段填错。Nexoraivision Codex 中转使用 Responses API：

[model_providers.OpenAI]
wire_api = "responses"      # 正确
# wire_api = "chat"         # 错误，不要用

如果你的客户端只支持 Chat Completions API（一般的 OpenAI SDK），用 https://nexor.nexoraivision.com/v1 而不是 Codex CLI。

流式响应中断

症状：长回答输出到一半就停了，或客户端报 stream ended unexpectedly

解决：

1. 首选：启用 WebSocket v2 模式（见 setup）
2. 关闭中间代理 / VPN
3. 切换网络（移动热点切到 WiFi）
4. 降低推理强度（xhigh → high 或 medium）

CC-Switch 启动失败 / 闪退

症状：macOS 提示「无法验证开发者」；Windows 提示「Windows 已保护你的电脑」

解决：

• macOS：系统设置 → 隐私与安全性 → 允许从以下位置下载的 App → 仍要打开
• Windows：「更多信息」→「仍要运行」

或在终端直接跑 CC-Switch（绕过 GUI 保护）查看错误日志。

还没解决？