常见错误排查

本页汇总了接入 JarlessAPI 过程中的高频错误，并提供逐步排查方法。遇到报错时，建议先按以下顺序排查，再参考对应错误的具体处理步骤。

排查优先级

1. 确认 Base URL 是否正确。
2. 确认 API Key 与所属分组是否与当前客户端匹配。
3. 确认客户端读取的是正确的配置文件或环境变量。

---

错误 401 — 认证失败

现象： 客户端返回 401 Unauthorized 或提示认证失败。

原因： API Key 无效，或 Key 与当前客户端所需分组不匹配。

排查步骤：

1. 确认所用密钥属于当前客户端对应的分组。Claude Code 的密钥不可用于 Codex，反之亦然。

2. 在当前终端中打印环境变量，确认密钥已生效：

   Claude CodeCodexGemini CLI

   # macOS / Linux
   echo $ANTHROPIC_AUTH_TOKEN
   
   # Windows PowerShell
   echo $env:ANTHROPIC_AUTH_TOKEN
   

   检查 ~/.codex/auth.json（Windows 为 %USERPROFILE%\.codex\auth.json），确认文件中的 OPENAI_API_KEY 字段值为当前分组对应的密钥。

   # macOS / Linux
   echo $GEMINI_API_KEY
   
   # Windows PowerShell
   echo $env:GEMINI_API_KEY
   

3. 若打印结果为空或仍为旧值，说明当前终端窗口未加载最新配置，需重新执行 source 命令或重启终端。

---

错误 404 — 地址错误

现象： 客户端返回 404 Not Found。

原因： Base URL 配置有误，或客户端自动拼接了不兼容的路径前缀。

排查步骤：

1. 确认 Base URL 为 https://jarlessapi.com，末尾不得附加额外路径，协议头不可省略。

2. 在当前终端中打印地址变量，确认其值正确：

   Claude CodeCodexGemini CLI

   # macOS / Linux
   echo $ANTHROPIC_BASE_URL
   
   # Windows PowerShell
   echo $env:ANTHROPIC_BASE_URL
   

   期望值：https://jarlessapi.com

   打开 ~/.codex/config.toml，检查 base_url 字段：

   [model_providers.jarlessapi]
   base_url = "https://jarlessapi.com"
   

   # macOS / Linux
   echo $GEMINI_API_BASE_URL
   
   # Windows PowerShell
   echo $env:GEMINI_API_BASE_URL
   

   期望值：https://jarlessapi.com

3. 若地址正确但仍返回 404，请检查客户端版本是否过旧。旧版本可能在请求路径中拼接了不兼容的前缀，建议升级至最新版本。

---

模型列表为空

现象： 客户端连接成功，但可用模型列表为空。

原因： 当前分组不包含该客户端所需的模型，或客户端缓存了过期的模型列表。

排查步骤：

1. 登录 JarlessAPI 控制台，确认所选分组中包含当前客户端支持的模型。
2. 重启客户端，触发模型列表的重新拉取。
3. 若近期切换过分组或密钥，确认当前终端加载的是更新后的配置（参考上方 401 的排查方法）。

---

配置修改后未生效

现象： 已修改配置文件或环境变量，但客户端行为无变化。

原因： 当前终端窗口仍在使用旧的环境变量，或修改了错误的配置文件。

排查步骤：

1. 确认修改的是客户端实际读取的配置源：

   Claude CodeCodexGemini CLI

   环境变量来源：macOS 为 ~/.zshrc，Linux 为 ~/.bashrc，Windows 为系统环境变量（用户级）。

   配置文件路径：~/.codex/config.toml 和 ~/.codex/auth.json。确认路径未被环境变量覆盖。

   环境变量来源：.env 文件、~/.zshrc、~/.bashrc，或当前会话中手动执行的 export 命令。

2. 重新加载配置：

   • macOS / Linux：执行 source ~/.zshrc 或 source ~/.bashrc，或打开一个新的终端窗口。
   • Windows：关闭当前 PowerShell 窗口，重新开启一个新窗口。
   • Codex：修改 config.toml 或 auth.json 后，重启 Codex。

3. 执行打印命令进行最终确认： 参照上方 401 和 404 的排查步骤，在当前窗口中打印相关变量，确认其值已更新。

---

同一设备上不同终端窗口表现不一致

现象： 同一设备上，窗口 A 运行正常，窗口 B 持续报错。

原因： 两个窗口加载了不同来源的环境变量。

排查步骤：

1. 在报错窗口中分别打印 Base URL 和 API Key，与正常窗口的输出进行对比。
2. 若两者不一致，说明报错窗口未加载配置文件，或被另一个配置来源覆盖。
3. 在报错窗口中手动执行 source 命令重新加载配置，或关闭后重新打开。

---

问题定位参考

报错阶段	优先检查项
启动前即报错	配置文件路径与语法格式
认证阶段报错	API Key 有效性与分组匹配
请求发出后报错	Base URL 正确性、模型 ID 是否在支持列表中

排查原则

排查时每次只修改一个变量。若同时修改多项，将难以判断具体是哪项配置导致了问题。