常见问题排查

先判断问题边界

遇到接入失败时，先把问题拆成四类。这样排查会更快，也能避免反复修改无关配置。

认证问题

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。

不要发送完整 API Key

排查时最多展示前后少量字符，例如 sk-...abcd。不要在截图、群聊、工单或公开仓库里发送完整 API Key。

排查前准备这些信息

操作系统

Windows、macOS、Linux、WSL 的配置目录和环境变量写法不同。

客户端名称

Codex、CC Switch、Claude Code、OpenCode、Cherry Studio 等协议和字段可能不同。

Base URL

判断是否把控制台地址、官网地址或错误路径填进了客户端。

报错文本

401、模型不存在、网络超时、命令找不到对应不同排查方向。

按报错类型排查

Windows 和 WSL 配置混用

Windows 原生环境和 WSL 是两套用户目录。最常见的问题是：你在 Windows 里配置了密钥，但在 WSL 里运行 CLI；或者反过来。

Windows PowerShell / 桌面客户端常见配置目录：

C:\Users\你的用户名\.codex

适合 Windows 原生 Codex UI、PowerShell CLI、桌面客户端。

WSL / Linux 常见配置目录：

/home/你的用户名/.codex

适合 WSL、Linux 服务器、远程终端。

环境变量不会自动跨系统同步

在 PowerShell 中设置的 $env:OPENAI_API_KEY 不会自动进入 WSL 的 bash/zsh。反过来也一样，WSL 的 ~/.codex 不会自动变成 Windows 桌面客户端的配置。

新手排查顺序

如果你不知道从哪里开始，按这个顺序最稳：

确认 Base URL 是否为 https://ai-api.jiapi.com/v1。

确认 API Key 没有空格、换行和拼写错误。

确认模型名称是 JiaPi 当前可用模型。

确认配置写在当前运行环境真正读取的目录里。

重启客户端或终端，并用只读任务验证。

需要进一步协助时

联系支持前，可以先准备下面信息：

客户端和版本

例如 Codex UI、Codex CLI、CC Switch、OpenCode、Claude Code，以及对应版本号。

报错截图或文本

保留错误信息，不要露出完整 API Key。

Base URL 和模型

确认填写的接口地址和模型名称。

系统和配置路径

例如 Windows、macOS、Linux、WSL，以及实际修改的配置文件路径。