常见错误排查

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

排查优先级

1. 确认 Base URL 是否正确。
2. 确认 API Key 有效，模型 ID 在该密钥所属分组的支持列表中。
3. 确认客户端读取的是正确的配置文件或环境变量。

---

错误 401 — 认证失败

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

原因： API Key 无效、填写不完整，或客户端未读取到正确的密钥。

排查步骤：

1. 在控制台确认密钥有效，并核对客户端中填写的值。Claude Code、Codex 可以使用其他分组的密钥；使用时需配置该分组支持的模型 ID。

2. 在当前终端中检查密钥是否已配置（只显示是否存在，不显示完整密钥）：

   Claude CodeCodexGemini CLIGrok Build

   macOS / Linux

   if [ -n "$ANTHROPIC_AUTH_TOKEN" ]; then echo "已配置"; else echo "未配置"; fi
   

   Windows PowerShell

   -not [string]::IsNullOrWhiteSpace($env:ANTHROPIC_AUTH_TOKEN)
   

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

   macOS / Linux

   if [ -n "$GEMINI_API_KEY" ]; then echo "已配置"; else echo "未配置"; fi
   

   Windows PowerShell

   -not [string]::IsNullOrWhiteSpace($env:GEMINI_API_KEY)
   

   检查 ~/.grok/config.toml（Windows 为 %USERPROFILE%\.grok\config.toml，WSL 为 Linux 家目录下的 ~/.grok/config.toml），确认 [model."grok-4.6"] 的 api_key 是 Grok 分组密钥。

3. 若显示“未配置”或 False，请重新执行 source 命令或重启终端；显示已配置只说明变量存在，还需通过实际请求确认密钥有效。

---

错误 404 — 地址错误

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

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

排查步骤：

1. 按客户端核对 Base URL：Claude Code 与 Gemini CLI 使用 https://jarlessapi.com，Codex 与 Grok Build 使用 https://jarlessapi.com/v1。

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

   Claude CodeCodexGemini CLIGrok Build

   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/v1"
   

   macOS / Linux

   echo $GOOGLE_GEMINI_BASE_URL
   

   Windows PowerShell

   echo $env:GOOGLE_GEMINI_BASE_URL
   

   期望值：https://jarlessapi.com

   打开 ~/.grok/config.toml，检查 base_url：

   [model."grok-4.6"]
   base_url = "https://jarlessapi.com/v1"
   

   期望值：https://jarlessapi.com/v1（必须带 /v1）

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

---

错误 503 — 没有可用的 Grok 媒体账号

现象： 调用 /v1/images/generations 或 /v1/videos/generations 返回 grok_media_no_eligible_account。

原因： 当前 Grok 分组没有可用于生图/生视频的账号。API Key 账号默认可做媒体；OAuth 账号需要探测到付费权益。

排查步骤：

1. 确认 API Key 属于 Grok 分组，且分组已开启图片生成。
2. 在后台对 Grok OAuth 账号点击「探测」，确认不是 Free / 403。
3. TUI 的 /imagine 报 Incorrect API key 时，改走 Grok 生图 API，不要用 /imagine。

---

模型不可用

如果提示模型不存在或无权使用，先在控制台查看当前 API Key 所属分组的可用模型 ID。Claude Code、Codex 使用其他分组的密钥时，需要同步修改模型配置：

• Claude Code：在对话中输入 /model 切换，或用 /model 模型ID 直接指定。
• Codex：在对话中输入 /model，选择该分组支持的模型。如果列表中没有目标模型，再修改 config.toml 中的 model。

---

模型列表为空

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

原因： 当前分组没有可用模型，或客户端缓存了过期的模型列表。

排查步骤：

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

---

配置修改后未生效

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

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

排查步骤：

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

   Claude CodeCodexGemini CLIGrok Build

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

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

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

   配置文件：WSL / macOS / Linux 为 ~/.grok/config.toml，Windows 为 %USERPROFILE%\.grok\config.toml。两套文件互不影响。

2. 重新加载配置：

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

3. 再次检查配置： 参照上方 401 和 404 的步骤，核对密钥是否已配置以及 Base URL 是否正确。

---

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

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

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

排查步骤：

1. 按上方命令对比两个窗口的 Base URL，以及密钥是否已配置。
2. 若两者不一致，说明报错窗口未加载配置文件，或被另一个配置来源覆盖。
3. 在报错窗口中手动执行 source 命令重新加载配置，或关闭后重新打开。

---

问题定位参考

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

排查原则

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