当 Codex 接入 DeepSeek、Qwen、Kimi、硅基流动等国内大模型失败时，应遵循“由外向内”的层级排查顺序，而非直接重装或盲目更换模型。

推荐排查逻辑

Codex 启动 -> 环境变量读取 -> API Key 有效性 -> Base URL 正确性 -> Model 标识匹配 -> 额度与权限 -> 网络连通性 -> 配置文件语法。

常见现象与原因分析

| 现象 | 优先排查点 | 常见根因 |

| :--- | :--- | :--- |

| Codex 启动失败 | 配置文件 | config.toml 语法错误或 provider 定义冲突 |

| 提示找不到 API Key | 环境变量 | 变量名拼错或设置后未重启终端 |

| 401 Unauthorized | API Key | Key 错误、已过期或账号无模型权限 |

| 404 Not Found | Base URL | 地址包含完整接口路径或 Endpoint 不存在 |

| model not found | 模型名 | 使用了已废弃的模型名或缺少必要的前缀 |

| quota / balance | 账户额度 | 账号欠费、未开通服务或推理点被停用 |

| timeout | 网络环境 | 防火墙拦截、代理配置错误或服务商抖动 |

核心环节检查要点

1. 环境变量验证

不同服务商对应不同的环境变量名（如 DEEPSEEK_API_KEY, DASHSCOPE_API_KEY）。确保变量已在系统中生效，且 Codex 能正确读取。

2. API Key 有效性

确认 Key 复制完整、无空格，并已在服务商控制台开通了对应模型的访问权限。

3. Base URL 规范

确保 Base URL 仅包含基础路径，不要包含 /chat/completions 等完整接口后缀。例如 DeepSeek 应为 https://api.deepseek.com。

4. Model 字段准确性

各服务商模型写法各异：

  • 硅基流动：需包含 Pro/ 等必要前缀。
  • 火山方舟：需使用“推理接入点 ID”而非简单的模型名。
  • Qwen：需核对地域（如北京）对应的 Endpoint。

5. 网络与代理

如果出现连接超时或 DNS 错误，优先检查本地代理设置或公司网络策略，而非频繁更换 API Key。

安全建议

在排障过程中，严禁在日志或配置文件中明文写死 API Key。如需 Codex 协助排查，应仅展示变量名或脱敏后的信息。