网络与连接类问题

API Error (Connection error.)

现象：请求未到达服务器即失败，重试无效。

原因：本地到服务器链路不通（TCP 连接阶段失败），常见原因为代理节点失效、Wi-Fi 路由异常或防火墙拦截出站请求。

排查步骤：

1. 执行 ping 你的请求地址 检查连通性
2. 有回包 → 排查代理配置；超时 → 切换网络（换 Wi-Fi / 关闭代理 / 切换代理节点 / 手机热点）
3. 确认代理软件已开启「系统代理」或「TUN 模式」，Claude Code 作为 CLI 工具不走浏览器代理通道
4. 网络恢复后重新执行 claude

API Error (Request timed out.)

现象：请求等待一段时间后超时。

原因分两种情况：

• 情况 A — 网络延迟：本地到服务器延迟过高，参考上文「API Error (Connection error.)」的网络排查步骤
• 情况 B — 上下文过长：当前会话积累 token 过多，模型处理时间超过超时阈值

情况 B 修复：

• 在 Claude Code 中输入 /clear 清空对话
• 或输入 /compact 压缩上下文保留摘要
• 或退出后重新执行 claude 进入新会话

IDE 用户注意：IDE 插件内置大量系统 Prompt，叠加 Claude Code 自身 Prompt 后，可用的有效对话轮数会明显减少，出现超时优先检查上下文长度。

WebFetch 联网功能失效

现象：调用 WebFetch 工具抓取网页时报错，目标网站手动用浏览器访问完全正常，代理已开启全局模式。

原因：Claude Code 在抓取目标页面前会先向 https://claude.ai/api/web/domain_info 发预检请求，国内网络 / 企业防火墙拦截 claude.ai 导致预检失败，WebFetch 整体报错。

修复：在 ~/.claude/settings.json（Windows 为 C:\Users\用户名\.claude\settings.json）中添加：

"skipWebFetchPreflight": true

若已有其他配置，合并写入：

{
  "env": {
    "ANTHROPIC_BASE_URL": "https://你的请求地址",
    "ANTHROPIC_API_KEY": "sk-***"
  },
  "skipWebFetchPreflight": true
}

保存后重启 Claude Code 即可跳过预检直接请求目标页面。