常见问题排查
从认证、模型、网络和客户端配置四个方向定位 服务平台 接入问题
先判断问题边界
遇到接入失败时，先把问题拆成四类。这样排查会更快，也能避免反复修改无关配置。
认证问题
401、unauthorized、invalid API key、token 无效。
模型问题
model not found、模型不存在、模型不可用。
网络问题
超时、连接失败、代理或防火墙拦截。
配置位置问题
配置文件写错目录、环境变量没加载、Windows/WSL 混用。
Codex UI / CLI
UI 能打开不代表 CLI 已安装；CLI 需要 codex --version 可用。
Node.js / npm
Codex CLI 或旧版教程可能依赖 Node.js/npm，先检查 node -v 和 npm -v。
排查前准备这些信息
操作系统
Windows、macOS、Linux、WSL 的配置目录和环境变量写法不同。
客户端名称
Codex、CC Switch、Claude Code、OpenCode、Cherry Studio 等协议和字段可能不同。
Base URL
判断是否把控制台地址、官网地址或错误路径填进了客户端。
报错文本
401、模型不存在、网络超时、命令找不到对应不同排查方向。
按报错类型排查
优先检查 API Key 是否完整复制、前后没有空格或换行，当前密钥是否来自 服务平台 控制台，账号是否仍有可用额度。Codex 的 auth.json 键名应为 OPENAI_API_KEY，CLI 场景下还要确认当前终端真的能读到对应环境变量。
这类问题通常是模型名称不匹配。建议回到 接口配置参考 查看模型名称说明，再把客户端中的模型名称改成完全一致的值。常见错误包括模型名称多了空格、使用了其他平台的模型名称、客户端默认模型没有同步修改。
优先确认 Base URL 是否填写为 https://your-api-host.example。如果主入口超时，可以尝试备用入口 https://your-api-host.example、https://your-api-host.example 或 https://your-api-host.example。如果仍然超时，再继续检查本机网络、代理、防火墙或公司网络限制。
通常和客户端缓存或配置文件位置有关。检查是否彻底退出并重启客户端、配置文件是否写在正确目录、文件名是否误写成 config.toml.txt、Codex 中 model_provider 与 [model_providers.服务平台] 名称是否一致。
如果出现 codex: command not found、opencode: command not found、claude: command not found，通常说明命令还没有安装成功，或者安装目录没有加入 PATH。Codex UI 能打开不代表 Codex CLI 已经安装，CLI 需要在终端里执行 codex --version 能输出版本号。
Codex CLI、部分 OpenCode CLI 或旧版教程会依赖 Node.js/npm。先执行 node -v 和 npm -v。如果命令本身不可用，说明 Node.js 还没有安装或没有加入 PATH。如果你只使用 Codex UI 客户端，则不一定需要处理 npm。
Windows 和 WSL 配置混用
Windows 原生环境和 WSL 是两套用户目录。最常见的问题是：你在 Windows 里配置了密钥，但在 WSL 里运行 CLI；或者反过来。
Windows PowerShell / 桌面客户端常见配置目录：
C:\Users\你的用户名\.codex
适合 Windows 原生 Codex UI、PowerShell CLI、桌面客户端。
WSL / Linux 常见配置目录：
/home/你的用户名/.codex
适合 WSL、Linux 服务器、远程终端。
新手排查顺序
如果你不知道从哪里开始，按这个顺序最稳：
https://your-api-host.example。https://your-api-host.example、https://your-api-host.example 或 https://your-api-host.example。需要进一步协助时
联系支持前，可以先准备下面信息：
客户端和版本
例如 Codex UI、Codex CLI、CC Switch、OpenCode、Claude Code，以及对应版本号。
报错截图或文本
保留错误信息，不要露出完整 API Key。
Base URL 和模型
确认填写的接口地址和模型名称。
系统和配置路径
例如 Windows、macOS、Linux、WSL，以及实际修改的配置文件路径。