常见错误

接入过程中遇到报错？先在这里对一下，确认问题出在哪一层。

先怎么排

1. 先确认 Base URL。
2. 再确认 API Key 和分组是否一致。
3. 最后确认客户端有没有读到正确的配置文件。

---

请求 401 — 认证失败

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

原因：API Key 错了，或者 Key 和分组不匹配。

解决：

1. 确认你用的 Key 属于当前客户端对应的分组。Claude Code 的 Key 不能给 Codex 用，反过来也一样。

2. 在当前终端打印变量，确认 Key 确实生效了：

   Claude CodeCodexGemini CLI

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

   检查 ~/.codex/auth.json（或你自定义的路径），确认里面的 Key 是当前分组的。

   # Mac / 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

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

   正确值：https://jarlessapi.com

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

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

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

   正确值：https://jarlessapi.com

3. 如果地址对了还是 404，检查客户端版本是否过旧——旧版可能拼接了不兼容的路径前缀。

---

模型列表为空

现象：客户端能连上，但看不到任何可用模型。

原因：当前分组不包含这个客户端需要的模型，或者客户端缓存了旧的模型列表。

解决：

1. 登录 JarlessAPI 后台，确认你的分组里包含当前客户端对应的模型。
2. 重启客户端，让它重新拉取模型列表。
3. 如果换过分组或 Key，确认当前终端加载的是新 Key（参考上面 401 的排查方法）。

---

配置改了但没生效

现象：明明改了配置文件或环境变量，但客户端行为没变化。

原因：当前终端窗口还在用旧的变量，或者改错了文件。

解决：

1. 确认改的是客户端真正读取的文件。

   Claude CodeCodexGemini CLI

   环境变量来源：~/.zshrc（Mac）、~/.bashrc（Linux）、系统环境变量（Windows）。

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

   环境变量来源：.env 文件、~/.zshrc、~/.bashrc，或你手动设的 export。

2. 重新加载配置。

   • Mac / Linux：source ~/.zshrc 或 source ~/.bashrc，或者直接开一个新终端窗口。
   • Windows：关掉当前 PowerShell，重新打开一个。
   • Codex：改完 config.toml / auth.json 后，重启 Codex。

3. 打印变量做最终确认。 用上面 401 和 404 里的 echo 命令，确认当前窗口里跑的确实是你改过的值。

---

只在某个窗口出问题

现象：同一台机器，A 窗口正常，B 窗口报错。

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

解决：

1. 在出问题的窗口里，用 echo 打印 Base URL 和 API Key，和正常窗口做对比。
2. 如果变量不一样，说明出问题的窗口没有加载配置文件，或者被另一个配置覆盖了。
3. 在出问题的窗口手动 source 一次配置文件，或关掉重开。

---

如何缩小范围

报错阶段	优先检查
启动前就报错	配置文件路径和语法
认证阶段报错	API Key 和分组
发请求后报错	Base URL、模型 ID

Tip

排错时先只改一个变量。一次改太多项，你就很难知道到底是哪一项导致失败。