国内模型配置排障总表

国内模型配置排障总表

这一篇是国内模型配置的排障入口。

当 Codex 接入 DeepSeek、Qwen、Kimi、硅基流动、智谱 GLM、火山方舟失败时，不要一上来重装 Codex，也不要立刻换模型。

先按这条顺序排查：

Codex 能不能启动
-> 环境变量能不能读到
-> API Key 是否有效
-> Base URL 是否正确
-> model 是否正确
-> 账号是否有额度/权限
-> 网络是否可达
-> Codex 配置是否写错

前置教程：国内大模型配置方案
如果你还没有读过国内模型配置总览，先完成前置教程，再回到本篇。

先问 Codex 做只读排障

出现配置错误时，先把下面这段复制给 Codex：

Codex 连接国内模型失败了，请帮我做只读排障。

要求：
1. 不要修改文件。
2. 不要打印完整 API Key。
3. 不要让我把真实 API Key 发给你。
4. 请按层级排查：Codex 启动、环境变量、API Key、Base URL、model、额度权限、网络、配置文件。
5. 如果需要查看配置文件，请先说明路径。
6. 如果发现疑似敏感信息，请只说明风险，不要完整输出。

请按下面格式回复：

## 错误摘要
- 我提供的错误是什么：
- 你初步判断属于哪一类：

## 排查清单
- 已确认：
- 未确认：
- 下一步建议：

## 风险提醒
- 是否可能泄露 Key：
- 是否建议先停止操作：

总表：错误现象对应排查方向

现象	优先排查	常见原因
Codex 启动失败	Codex 本身	CLI 没装好、配置文件语法错
提示找不到 API Key	环境变量	变量名写错、没重开 PowerShell
401 / Unauthorized	API Key	Key 错、Key 删除、账号权限不足
404 / endpoint not found	Base URL 或 model	URL 写错、完整接口写进 Base URL、Endpoint 不存在
model not found	模型名	模型名过期、少写前缀、没权限
quota / balance	额度	账号没余额、套餐没开通
timeout	网络	代理、公司网络、防火墙、服务商异常
参数不兼容	服务商兼容性	国内模型 OpenAI 兼容不完整
Codex 说不能判断当前 provider	Codex 上下文	它不一定能从会话里直接知道当前 provider

排查 1：Codex 本身能不能启动

先确认不是 Codex CLI 自己的问题。

问 Codex：

请先确认 Codex CLI 本身是否能正常工作。

要求：
1. 不要检查 API Key。
2. 不要修改配置。
3. 只说明当前会话是否能正常响应。

如果 Codex 本身都无法启动，先回到：

• Codex CLI 安装与登录

不要继续排查模型。

排查 2：环境变量是否能读到

不同服务商对应不同环境变量。

服务商	环境变量
DeepSeek	DEEPSEEK_API_KEY
通义千问/Qwen	DASHSCOPE_API_KEY
Kimi	MOONSHOT_API_KEY
硅基流动	SILICONFLOW_API_KEY
智谱 GLM	BIGMODEL_API_KEY
火山方舟	ARK_API_KEY

让 Codex 检查时，不要让它打印完整 Key：

请只读检查环境变量是否存在。

变量名：【替换成你的变量名】

要求：
1. 不要显示完整值。
2. 只告诉我是否存在。
3. 如果存在，只告诉我长度是否大于 0。
4. 不要修改配置文件。

如果变量不存在，常见原因：

• 变量名拼错。
• 设置到了另一个 Windows 用户。
• 设置后没有重开 PowerShell。
• 用了系统变量但权限没生效。
• 在 WSL 和 Windows 原生环境之间混用了变量。

排查 3：API Key 是否有效

如果环境变量存在，但仍然 401，优先怀疑 Key。

检查：

1. Key 是否复制完整。
2. Key 是否多了空格。
3. Key 是否已经删除。
4. Key 是否属于当前服务商账号。
5. Key 是否有 API 权限。
6. 是否需要先充值或开通模型服务。

问 Codex：

当前错误像是 API Key 无效。

请不要修改文件。
请列出我应该去服务商控制台检查的项目。
不要要求我把真实 API Key 发给你。

排查 4：Base URL 是否正确

常见错误是把完整接口写进 Base URL。

正确例子：

服务商	Base URL
DeepSeek	https://api.deepseek.com
Qwen 北京地域	https://dashscope.aliyuncs.com/compatible-mode/v1
Kimi	https://api.moonshot.cn/v1
硅基流动	https://api.siliconflow.cn/v1
智谱通用端点	https://open.bigmodel.cn/api/paas/v4
火山方舟	https://ark.cn-beijing.volces.com/api/v3

不要写成：

.../chat/completions

除非某个工具明确要求完整接口路径。Codex provider 配置里通常写 Base URL。

问 Codex：

请检查当前模型 provider 的 base_url 是否像 Base URL，而不是完整接口路径。

要求：
1. 不要显示 API Key。
2. 不要修改文件。
3. 如果 base_url 看起来包含 /chat/completions，请提示风险。

排查 5：model 字段是否正确

各服务商的 model 写法不一样。

服务商	model 常见写法
DeepSeek	官方模型名，如 deepseek-v4-pro
Qwen	官方模型名，如 qwen-plus
Kimi	官方模型名，如 kimi-k2.7-code
硅基流动	完整模型名，如 Pro/zai-org/GLM-4.7
智谱 GLM	官方模型名，如 glm-5.1
火山方舟	推理接入点 ID

最容易错的是：

• 硅基流动：少写 Pro/ 或组织名前缀。
• 火山方舟：把 model 写成 doubao，而不是推理接入点 ID。
• Kimi：使用已下线模型名。
• DeepSeek：复制旧教程里的旧模型名。

问 Codex：

请检查当前 model 字段是否符合对应服务商的写法。

服务商：【填写服务商】
当前 model：【填写你配置的 model，不要填 API Key】

要求：
1. 只判断格式和常见风险。
2. 如果需要确认，请告诉我应该去哪个官方页面看。
3. 不要修改配置。

排查 6：账号额度和权限

很多错误不是配置错，而是账号不能调用。

检查：

• 是否有余额。
• 是否开通模型服务。
• 是否开通对应地域。
• 是否有对应模型权限。
• 是否使用了 Pro 模型但账号没权限。
• 是否使用了 Coding 套餐端点但没有套餐。
• 是否推理接入点被停用。

问 Codex：

这个错误可能和额度或权限有关。

请列出我应该去服务商控制台检查的 6 个位置。
不要修改文件。
不要要求我提供真实 API Key。

排查 7：网络和代理

如果错误是 timeout、connection refused、DNS、SSL，优先看网络。

常见原因：

• 公司网络拦截。
• 代理没配置。
• 代理配置错。
• 服务商临时异常。
• 地域接口访问不通。
• 防火墙拦截。

问 Codex：

当前错误像网络连接问题。

请根据错误信息判断可能是 DNS、代理、超时、TLS/SSL 还是服务商异常。
请先分析，不要修改文件。

排查 8：配置文件语法错误

如果 Codex 启动时就报配置错误，可能是 config.toml 写坏了。

常见错误：

• 引号没闭合。
• 表名写错。
• model_provider 和 [model_providers.xxx] 对不上。
• 把 API Key 明文写进配置。
• 重复定义同一个 provider。

问 Codex：

Codex 启动时报配置文件错误。

请只读检查 config.toml 的语法和 provider 配置。
要求：
1. 不要显示完整 API Key。
2. 不要修改文件。
3. 先列出错误位置和原因。
4. 再给出最小修复建议。

服务商专项提示

DeepSeek

重点查：

• Base URL 是否是 https://api.deepseek.com。
• 模型名是否来自当前官方文档。
• 是否用了已废弃旧模型名。
• DEEPSEEK_API_KEY 是否生效。

Qwen / 阿里云百炼

重点查：

• 地域是否正确。
• 北京、弗吉尼亚、新加坡 Base URL 是否混用。
• DASHSCOPE_API_KEY 是否生效。
• 模型是否在当前地域可用。

Kimi

重点查：

• Base URL 是否是 https://api.moonshot.cn/v1。
• MOONSHOT_API_KEY 是否生效。
• 是否用了已下线模型。
• 参数是否和 Kimi 兼容。

硅基流动

重点查：

• Base URL 是否是 https://api.siliconflow.cn/v1。
• model 是否完整复制。
• 是否少了 Pro/ 或组织名前缀。
• 账号是否有该模型权限。

智谱 GLM

重点查：

• 普通端点和 Coding 端点是否混用。
• BIGMODEL_API_KEY 是否生效。
• glm-5.1 或当前模型是否可用。
• 是否有对应套餐。

火山方舟

重点查：

• Base URL 是否是 https://ark.cn-beijing.volces.com/api/v3。
• model 是否填推理接入点 ID。
• 推理接入点是否启用。
• ARK_API_KEY 是否生效。

什么时候应该回退配置

如果你配置后 Codex 完全不可用，可以先回退。

不要直接删除所有配置。先让 Codex 给方案：

当前模型配置导致 Codex 不可用。

请给出安全回退方案。
要求：
1. 只回退本次新增的 provider 配置。
2. 不删除其他配置。
3. 不删除 auth.json。
4. 不删除历史会话。
5. 先给方案，不要直接修改。

验收结果

做到这里，如果满足下面 6 条，就说明你会排查国内模型配置问题：

1. 你会先判断 Codex 本身是否可用。
2. 你会检查环境变量是否存在，但不泄露 Key。
3. 你会区分 API Key、Base URL、model、额度和网络问题。
4. 你知道不同服务商的 model 写法不一样。
5. 你知道火山方舟要看推理接入点 ID。
6. 你知道配置坏了时先做最小回退。

下一篇学什么

下一篇建议看：常见问题。

如果你已经开始真实项目，可以回到 Git 提交前检查。