常见报错问题排查手册

默认分类
约 10 分钟阅读

本文档汇总 Codex、VS Code Codex 插件、TokenRouter 对接过程中高频报错、版本缺陷与对应完整修复方案,出现异常可按报错关键词快速检索处理。

  • 一、API error 500 / 上游服务过载

    故障现象

    返回 API error 500,服务端内部异常

    处理步骤
    1. 完全退出客户端后重新打开重试;
    2. 单次重试无效则间隔一段时间再次测试;
    3. 查看官方服务状态页面确认是否全局故障:
    若官方页面标记故障,仅能等待官方修复。

  • 二、stream error: stream disconnected before completion

    故障诱因分两类
    1. 模型思考时长超过 150s,OpenAI 侧强制截断会话,等待官方更新修复;
    2. 本地客户端与 TokenRouter 网关网络连接中断。
    修复方案

    排查本地网络、代理出口稳定性,更换网络环境重试。

  • 三、Unable to persist auth file: 系统找不到指定的路径。(os error 3)

    处理方案

    全盘检索是否存在多余 .codex 文件夹,删除冗余目录后严格按照安装教程重新部署配置文件。

  • 四、stream error: error sending request for url

    处理方案
    1. 替换配置内 Base URL;
    2. 关闭全部终端窗口重新打开;
    3. 检查本地代理、DNS 网络配置。

  • 五、error start conversation

    说明

    该故障为 VS Code Codex 插件已知缺陷,暂无临时修复手段,等待插件官方更新修复。

  • 六、401 invalid token 令牌认证失败

    逐项核对修复点
    1. 确认 config.toml 内 base_url 地址填写规范;
    2. auth.json 文件仅保留一行 OPENAI_API_KEY 配置,删除其余多余空行、注释;
    3. 确认两个配置文件已正常保存、文件名无拼写错误;
    4. 桌面端需右下角点击 Exit 完全退出后台进程后重启;命令行关闭终端重开。

  • 七、通用 stream error(纯网络类报错)

    处理方案

    切换手机热点等全新网络;若开启代理工具,临时关闭代理重试。

  • 八、400 官方参数校验错误

    八、400 官方参数校验错误

    说明

    请求参数格式不符合接口规范,翻译报错提示文本,对照配置文件修改参数,新开会话重试。

  • 九、Codex 版本专属问题汇总

    9.1 VS Code 更新插件后历史会话丢失

    故障规则:跨大版本升级插件会丢失本地会话缓存(示例:0.4.6 直接升级至 0.4.9)。 修复方案:回退至上一可用插件版本即可恢复历史对话记录。

    9.2 无法选择思考等级

    9.2 无法选择思考等级

    限制说明:通过 API 接入模式暂不支持可视化切换思考等级,仅可在 config.toml 文件静态配置,等待官方迭代功能。

    9.3 gpt-5-codex 文件编辑功能 Bug

    9.3 gpt-5-codex 文件编辑功能 Bug

    异常表现:

    1. gpt-5 模型:文件编辑展示变更清单 changed list,支持点击查看完整修改;
    2. gpt-5-codex 模型:仅通过命令行执行文件修改,无变更清单、不可点击追溯历史。 临时方案:临时切换 gpt-5 模型处理文件编辑场景,等待官方修复。

  • 十、更新 CLI 后 VS Code 无法用 /model 切换 gpt-5-codex

    修复配置

    在 [model_providers.tokenrouter] 区块新增 requires_openai_auth = true,完整模板如下:

    Plain

    复制

    model = "gpt-5.5"model_provider = "tokenrouter"preferred_auth_method = "apikey"model_reasoning_effort = "high"[model_providers.tokenrouter]name = "TokenRouter"base_url = "https://api.aqzzz.com/v1"wire_api = "responses"requires_openai_auth = true
    网络备选地址:全球 CDN 访问不稳定可替换 https://cdn.aqzzz.com/v1 修改保存后重启 VS Code,即可正常切换模型、选择思考等级。

401：认证失败

  • 检查 API Key 是否完整。
  • 检查请求头是否为 Authorization: Bearer <API_KEY>。
  • 确认 Key 没有过期、禁用或删除。

403：没有权限

  • 检查 API Key 分组是否支持目标模型。
  • 检查额度、IP 和速率限制。
  • 确认当前账户具有模型访问权限。

404：接口或模型不存在

  • 文本请求使用 api.aqzzz.com。
  • 生图和长任务使用 cdn.aqzzz.com。
  • OpenAI 兼容客户端的 Base URL 包含 /v1。
  • 模型名称与“可用渠道”页面完全一致。
  • 避免拼成 /v1/v1。

429：请求过多或额度不足

  • 检查账户余额和 Key 额度。
  • 降低并发与请求频率。
  • 使用带上限的指数退避重试。

500、502、503：服务异常

  • 查看渠道状态和控制台公告。
  • 稍后重试或切换备用分组。
  • 记录请求 ID，不记录完整 API Key 或用户敏感内容。