CC-009：API Error (Connection error.)
| 字段 | 内容 |
|---|---|
| 影响组件 | Claude Code 本体 |
| 发现版本 | 不限版本 |
| 系统环境 | Linux / macOS / Windows |
| 解决人 | — |
| 发现日期 | 2026-03-14 |
问题现象
发送请求后，终端返回：
API Error (Connection error.)
请求未到达服务器即失败，重试无效。
根因分析
Claude Code 发起 HTTP 请求
→ TCP 连接阶段失败（未到 TLS 握手）
→ 本地网络 → 中转服务器链路不通
→ 返回 Connection error
常见原因：
- 当前 Wi-Fi / 有线网络到服务器路由异常
- 代理节点失效或未开启
- 防火墙拦截出站请求
修复步骤
第一步：检查网络到服务器的连通性
ping duoapi.zeabur.app
- 有正常回包 → 网络通，跳第三步排查代理
- 请求超时 → 当前网络到服务器不通，执行第二步
第二步：切换网络环境
按以下顺序逐一尝试：
- 换一个 Wi-Fi 网络
- 关闭代理 / 切换代理节点
- 使用手机热点
第三步：确认代理配置正确（如使用代理）
Claude Code 使用系统代理，确认代理软件已开启「系统代理」或「TUN 模式」，而非仅浏览器代理。
第四步：重新启动 Claude Code
网络恢复后重新执行：
claude
预防措施
| 做法 | 避免的问题 |
|---|---|
| 使用代理时开启 TUN 模式或全局系统代理 | Claude Code 作为 CLI 工具不走浏览器代理通道 |
| 出现连接失败时先用 ping 定位是网络还是配置问题 | 盲目修改 API 配置而非排查网络 |