跳转到内容
NexaGW 使用文档

常见问题与报错

推荐排查顺序

Section titled “推荐排查顺序”
  1. 打开渠道状态监控，确认目标分组的实时状态。
  2. 使用同一 Key 请求 /v1/models，确认 Key、线路和模型范围。
  3. 检查环境变量是否由当前终端和客户端进程继承。
  4. 检查 Base URL：OpenAI、Codex 和 OpenCode 需要 /v1，Claude Code 使用根域名。
  5. 记录发生时间、模型、节点、状态码和请求 ID，再通过控制台工单反馈。

配置工具无法启动

Section titled “配置工具无法启动”

Windows 双击后立即关闭

Section titled “Windows 双击后立即关闭”

确认 ZIP 已完整解压，且 .cmd 与 .ps1 位于同一目录。在该目录打开 PowerShell 运行：

Terminal window
.\nexagw-codex-setup.cmd

如果提示文件缺失，重新从下载中心下载并核对 SHA-256。不要关闭安全软件或执行来源不明的放行命令。

PowerShell 执行策略阻止

Section titled “PowerShell 执行策略阻止”

下载包内的 CMD 只对本次 PowerShell 进程使用 ExecutionPolicy Bypass，不会修改系统策略。也可在已校验文件的目录中运行：

Terminal window
powershell.exe -NoProfile -ExecutionPolicy Bypass -File .\nexagw-codex-setup.ps1

macOS / Linux 提示没有权限

Section titled “macOS / Linux 提示没有权限”
Terminal window
chmod 700 nexagw-codex-setup.sh
./nexagw-codex-setup.sh

若系统提示文件带有隔离属性，先重新核对哈希和下载域名，再按系统安全提示审阅文件来源。

环境变量未生效

Section titled “环境变量未生效”
  • Windows：配置后关闭旧终端，打开新 PowerShell，再运行 [Environment]::GetEnvironmentVariable('NEXAGW_API_KEY', 'User').Length。
  • Bash：重新打开终端，或加载 ~/.profile / ~/.bash_profile。
  • Zsh：重新打开终端，或运行 . ~/.zshrc。
  • 从桌面图标启动的客户端可能不会继承刚修改的终端环境，先从已验证变量的终端启动。

检查命令只应显示“已设置”或字符数，不要打印完整 Key。

TOML 重复或格式无效

Section titled “TOML 重复或格式无效”

工具发现多个 [model_providers.nexagw] 或无法解析的表头时会停止，原文件保持不变。先复制一份 ~/.codex/config.toml，再合并重复表；不要删除不认识的 MCP、profile、permissions 或 features 配置。

修复后重新运行 Configure。仍有问题时使用 Status 查看是否只剩一个 NexaGW provider。

/v1/models 中没有目标模型

Section titled “/v1/models 中没有目标模型”

Key 只会看到所属分组允许的模型。进入控制台确认 Key 分组，从 /v1/models 返回值复制准确模型名，再更新客户端。不要仅根据示例猜测模型名。

状态码

Section titled “状态码”
状态码 常见原因 处理方法
401 Key 错误、复制了空格、认证头缺失 重新复制 Key，检查 Authorization: Bearer
403 Key 分组不允许该模型或权限受限 从 /v1/models 复制模型名，检查 Key 分组
429 并发或上游速率限制 降低并发，稍后重试，必要时切换同类分组
400 请求体、模型名或接口协议不匹配 先用最小请求体测试，核对 OpenAI/Anthropic 协议
5xx 上游或当前线路短时异常 查看状态页，保留时间和请求信息反馈
超时 网络、代理、线路或上游响应慢 先测 /v1/models，再切换主线路/香港线路并降低并发

旧备用线路迁移

Section titled “旧备用线路迁移”

如果客户端仍配置 https://api2.nexagwapi.com，请改为：

  • OpenAI / Codex：https://api.nexagwapi.com/v1
  • Claude Code：https://api.nexagwapi.com
  • 香港线路：OpenAI 使用 https://api.nexagw.org/v1，Claude Code 使用 https://api.nexagw.org

API Key 无需重新创建。

从备份恢复

Section titled “从备份恢复”

重新运行配置工具，选择 Restore，再选择目标时间戳。恢复前工具会创建新的安全备份，并校验旧备份的 SHA256SUMS。恢复完成后重新打开终端和客户端。

完整说明见备份、安全与恢复。

工单反馈格式

Section titled “工单反馈格式”
用户名或注册邮箱：
发生时间：
使用节点：主线路 / 香港线路
使用模型：
客户端：Codex / Claude Code / SDK / 其他
状态码与报错：
请求 ID：
已附脱敏截图：是 / 否