API 排错：401、model not found、超时、流式中断

Codex、Cline、OpenCode 或 SDK 报错时，先按这四步查。成熟网关文档的共同顺序都是：鉴权 → 模型 ID → 主机 → 流式/网络。

0. 基线检查（先做这个）

export BASE=https://api.earbowe.com/v1
export KEY=sk-YOUR-KEY

# 1) 模型列表
curl -sS -o /tmp/models.json -w '%{http_code}\n' \
  -H "Authorization: Bearer $KEY" "$BASE/models"

# 2) 简单聊天
curl -sS -o /tmp/chat.json -w '%{http_code}\n' \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  "$BASE/chat/completions" \
  -d '{"model":"gpt-4o-mini","messages":[{"role":"user","content":"ping"}]}'

curl 都不过，就别先怪 Agent UI。

国内直连：BASE=https://api.3861343.xyz/v1。

1. 401 Unauthorized

含义： 密钥被拒或缺失。

工具提示：

• Cline：在 OpenAI Compatible 设置里重新粘贴密钥
• Codex：确认启动 codex 的同一 shell 里有 OPENAI_API_KEY
• OpenCode：确认 EARBOWE_API_KEY（或你配置的变量名）已 export

2. model not found / invalid model

含义： 这个网关上没有你填的模型字符串。

处理：

1. GET /v1/models
2. 复制精确 id
3. 粘贴到 Agent（不要用营销别名）

常见错误：

• 用品牌名而不是 API id
• 以为 OpenAI/Anthropic 公开名在所有网关都存在
• 本地下拉缓存过期

3. 超时 / 连接重置 / 很慢

含义： 网络路径或主机选择问题。

规则：curl 通 + Agent 不通 几乎一定是 Agent 配置问题，不是模型质量问题。

4. 流式中断 / 回复不完整

含义： 流式链路不稳或客户端中止。

排查顺序：

1. 非流式请求（上面的 curl）——正常则模型链路可用
2. 只在一个客户端打开 stream 复测
3. 检查 VPN/代理空闲超时
4. 降低并发 Agent 会话

Earbowe 支持客户端请求流式；本地网络差仍会打断长流。

5. Base URL 常见填错

正确：

https://api.earbowe.com/v1

错误：

https://api.earbowe.com
https://api.earbowe.com/v1/chat/completions   # baseURL 字段别写这么长
https://www.earbowe.com/v1                    # 内容站不是 API
https://earbowe-astro-preview.pages.dev/v1    # Pages 内容站不是网关

OpenAI 兼容客户端会自己拼接 /chat/completions。

6. 速查表

相关指南

• 快速开始
• Codex
• Cline
• OpenCode
• 文档：排错