网络错误 / 连接失败修复指南——Claude Code 与 Codex CLI
Claude Code 或 Codex CLI 接入 DeepSeek、OpenRouter 等服务商时遇到"网络错误 / 连接失败"的分步修复方法。
报错输出
Error: NetworkError when attempting to fetch resource.
Failed to fetch
常见变体
ECONNREFUSED api.deepseek.com:443
Error: fetch failed
codex: error sending request: error trying to connect: connection timed out
具体文本随 Agent 版本与服务商略有差异，以状态码和消息类型为准。
快速定位
把网络层与配置层隔离：如果同一 Shell 中 curl 也失败，问题在网络而不是配置。
Claude Code
curl -I https://api.deepseek.com/anthropic Codex CLI
curl -I https://api.deepseek.com常见原因
- 本机无法访问服务商端点（DNS、路由或连通性问题）。
- 代理、防火墙或 VPN 拦截或改写了请求。
- 地区限制阻止了与服务商主机的直连。
- 自上次成功后网络发生了变化（换了 Wi-Fi、VPN 会话结束）。
按场景修复
1 同一台机器上 curl 也失败
- 检查 DNS：`nslookup api.deepseek.com` 应能解析。
- 检查代理与防火墙规则；换一个网络验证。
- 部分区域网络屏蔽直连——可能需要换网络路径。
2 curl 正常但 Agent 失败
- CLI 流量可能被浏览器可绕过而终端不行的规则阻止（MITM 代理、沙箱网络）。
- 在设置了环境变量的同一个 Shell 中运行失败的命令。
- 检查本地代理变量（http_proxy/https_proxy）——Agent 会遵守而 curl -I 可能忽略。
3 网络变化后失败
- 重新连接或切换网络后重试。
- 如果使用了 VPN，确认它仍在运行并路由服务商流量。
- 公司网络通常需要为服务商主机添加白名单。
Agent 差异修复
Claude Code
- 修复
- 确认当前网络可以访问 ANTHROPIC_BASE_URL；调整代理/防火墙规则或更换网络。请使用接入指南中的端点——第三方镜像不受支持。
- 验证
- 在同一台机器和网络下 `curl -I <base url>` 成功。
Codex CLI
- 修复
- 验证到 base_url 主机的连通性，并确认运行 Codex 的网络可以访问该端点。
- 验证
- `curl -I https://api.deepseek.com`（或 https://openrouter.ai）成功，然后运行 `codex exec "hi"`。
Claude Code 与 Codex CLI 对照速查
| Claude Code | Codex CLI | |
|---|---|---|
| 连通性测试 | curl -I <anthropic url> | curl -I <openai url> |
| 代理变量 | http_proxy/https_proxy honored | http_proxy/https_proxy honored |
| 镜像支持 | No third-party mirrors | No third-party mirrors |
避免复发
- 为服务商主机记录一条已验证可用的网络路径。
- 如果网络 DNS 不稳定，固定 DNS 或记录解析出的 IP。
- 网络变化后、长会话前，先用 curl 测试连通性。
相关错误
相关接入指南
常见问题
浏览器能打开网站但 CLI 失败，为什么？
CLI 流量可能被浏览器可绕过但终端不行的规则阻止，例如允许浏览器流量但丢弃 CLI 连接的代理，或终端应用的沙箱网络。请在同一 Shell 中用 curl 测试。
Agent 会遵守代理环境变量吗？
Claude Code 与 Codex 都会在连接时遵守标准代理变量（http_proxy、https_proxy、no_proxy），所以 curl 测试应在与 Agent 相同的 Shell 中运行。