【Bug已解决】Request timed out / API Timeout — Claude Code 请求超时解决方案

1. 问题描述

在 Claude Code 中发送请求后，长时间等待无响应，最终弹出以下超时错误：

Request timed out after 60000ms

或者：

Error: Request timed out
{"type":"error","error":{"type":"api_timeout","message":"Request processing timed out"}}

有时表现为：

API request failed: ETIMEDOUT
Connection timed out after 60000ms

这个问题在以下场景中特别常见：

• 让 Claude Code 分析超大型代码库（一次性读取整个项目）
• 使用 Opus 模型处理复杂推理任务
• 网络不稳定或代理延迟过高
• 请求中包含大量代码和上下文（超过 100K tokens）
• 高峰时段 API 服务端处理速度下降
• MCP 工具执行时间过长

# 典型复现过程
$ claude
> 分析整个项目的所有文件并给出优化建议

# 等待 60 秒...
Request timed out after 60000ms

# 重试
> 继续
Request timed out after 60000ms

2. 原因分析

核心原理拆解

Claude Code 发送请求 → 等待 API 响应
        ↓
请求处理时间超过超时阈值（默认 60 秒）
        ↓
Claude Code 主动断开连接
        ↓
报错 Request timed out

原因分类表

原因分类	具体表现	占比
请求体过大	Token 数过多导致服务端处理慢	约 35%
Opus 模型推理慢	Opus 模型处理复杂任务耗时	约 25%
网络延迟高	代理或网络不稳定导致传输慢	约 20%
服务端高负载	高峰时段 API 处理能力下降	约 10%
MCP 工具超时	MCP Server 执行时间过长	约 5%
超时阈值过低	默认 60 秒对某些任务不够	约 5%

深入说明

Claude Code 有一个默认的 API 请求超时阈值（通常 60 秒）。如果 Anthropic API 在此时间内未返回响应，Claude Code 就会主动断开连接并报超时。

影响处理时间的因素：

1. 输入 Token 数：输入越大，服务端解析和预处理时间越长
2. 模型选择：Opus 的推理速度比 Sonnet 慢约 3-5 倍
3. 输出长度：如果请求 max_tokens 很大，生成时间也长
4. 网络延迟：每 100ms 的网络延迟在长连接中会累积
5. 服务端负载：高峰时段请求排队等待

3. 解决方案

方案一：增加超时阈值（最推荐）

将默认超时从 60 秒增加到 120 秒或更长。

# 步骤 1：通过环境变量设置超时
export CLAUDE_API_TIMEOUT=120000  # 120秒

# 步骤 2：永久生效
echo 'export CLAUDE_API_TIMEOUT=120000' >> ~/.zshrc
source ~/.zshrc

# 步骤 3：启动 Claude Code
claude

方案二：切换到 Sonnet 模型

Opus 模型的推理速度慢，切换到 Sonnet 可以显著减少响应时间。

# 步骤 1：切换模型
/model sonnet

# 步骤 2：重新发送请求
> 分析项目结构并给出优化建议
# Sonnet 的响应速度比 Opus 快 3-5 倍

方案三：缩小请求范围

减少单次请求的 Token 数量，降低服务端处理时间。

# 步骤 1：使用 /compact 压缩上下文
/compact

# 步骤 2：分模块处理
# 不要: "分析整个项目"
# 应该: "分析 src/auth/ 目录的代码结构"

# 步骤 3：配置 .claudeignore 排除大文件
cat > .claudeignore << 'EOF'
node_modules/
dist/
build/
*.log
*.lock
EOF

方案四：优化网络连接

减少网络延迟可以显著改善超时问题。

# 步骤 1：检查网络延迟
ping -c 5 api.anthropic.com
# 如果延迟超过 200ms，考虑优化网络

# 步骤 2：如果使用代理，检查代理延迟
curl -x http://127.0.0.1:7890 -I https://api.anthropic.com --max-time 10

# 步骤 3：如果代理延迟高，尝试直连
unset HTTP_PROXY
unset HTTPS_PROXY

# 步骤 4：如果必须用代理，使用更快的代理节点
# 或使用 SOCKS5 代理减少 HTTP 开销
export ALL_PROXY=socks5://127.0.0.1:7891

方案五：减少 MCP 工具调用时间

MCP 工具执行时间过长也会导致整体请求超时。

# 步骤 1：使用 --no-mcp 测试
claude --no-mcp
# 如果不超时，说明是 MCP 工具的问题

# 步骤 2：为 MCP 工具设置单独的超时
# 在 settings.json 中配置
cat > ~/.claude/settings.json << 'EOF'
{
  "mcpTimeout": 30000
}
EOF

# 步骤 3：移除执行慢的 MCP 服务器
claude mcp remove <慢速server>

方案六：使用流式响应（Streaming）

确保 Claude Code 使用流式响应而非一次性等待完整响应。

# 步骤 1：确认 Claude Code 版本支持流式
claude --version
# 较新版本默认使用流式

# 步骤 2：如果非流式，在配置中启用
# settings.json
{
  "streaming": true
}

# 步骤 3：流式响应下，只要数据在持续传输就不会超时
# 即使生成时间长，也能看到中间输出

4. 各方案对比总结

方案	适用场景	推荐指数	难度
方案一：增加超时	大任务处理	⭐⭐⭐⭐⭐	低
方案二：切换 Sonnet	Opus 太慢	⭐⭐⭐⭐⭐	低
方案三：缩小范围	大代码库	⭐⭐⭐⭐⭐	低
方案四：优化网络	网络延迟高	⭐⭐⭐⭐	中
方案五：减少 MCP	MCP 超时	⭐⭐⭐	中
方案六：流式响应	长生成任务	⭐⭐⭐	低

5. 常见问题 FAQ

5.1 增加超时到多少合适

建议根据任务复杂度设置：

• 日常编码：60 秒（默认）
• 大文件分析：120 秒
• 整个项目分析：300 秒
• 不要超过 600 秒（10 分钟），如果 5 分钟都没响应，可能是服务端问题

5.2 超时后请求是否计费

超时请求的处理取决于服务端状态：

• 如果服务端已开始处理但客户端超时断开，可能会计费
• 如果服务端未开始处理，不会计费
• 建议避免频繁超时重试，可能导致重复计费

5.3 Sonnet 仍然超时

可能是请求体过大。使用 /compact 压缩上下文后重试，或分模块处理。

5.4 偶尔超时但大部分正常

偶发超时通常是服务端临时波动。等待 30 秒后重试即可，不需要修改配置。

5.5 网络延迟如何测量

# 测量到 Anthropic API 的延迟
ping -c 10 api.anthropic.com

# 测量完整请求耗时
curl -w "Time: %{time_total}s\n" -o /dev/null -s https://api.anthropic.com/v1/messages

5.6 使用第三方 API 路由时频繁超时

第三方路由可能添加了额外的处理延迟。测量路由延迟并考虑直连 Anthropic 官方 API。

5.7 CI/CD 中的超时处理

在自动化流程中实现超时重试：

def call_with_timeout(prompt, timeout=120, max_retries=3):
    for attempt in range(max_retries):
        try:
            response = client.messages.create(
                model="claude-sonnet-4-20250514",
                max_tokens=4096,
                messages=[{"role": "user", "content": prompt}],
                timeout=timeout
            )
            return response
        except TimeoutError:
            print(f"Timeout, retry {attempt+1}/{max_retries}")
            time.sleep(10)
    raise Exception("Max retries exceeded")

5.8 流式响应和非流式响应的区别

• 非流式：等待整个响应生成完毕后一次性返回，容易超时
• 流式：响应逐步传输，只要有数据在传输就不会超时
• Claude Code 较新版本默认使用流式，但如果通过第三方路由可能不支持

5.9 超时报错后上下文是否保留

超时是单次请求失败，对话历史保留。可以直接重新发送请求。但如果超时导致进程崩溃，使用 claude --continue 恢复。

5.10 排查清单速查表

□ 1. 增加 CLAUDE_API_TIMEOUT 环境变量到 120000
□ 2. 切换到 Sonnet 模型减少推理时间
□ 3. 使用 /compact 压缩上下文
□ 4. 分模块处理大任务
□ 5. 配置 .claudeignore 排除大文件
□ 6. 使用 ping 测量网络延迟
□ 7. 检查代理是否增加了延迟
□ 8. 使用 --no-mcp 排除 MCP 超时
□ 9. 确认使用流式响应
□ 10. 偶发超时等待 30 秒重试

6. 总结

1. 根本原因：请求超时最常见原因是请求体过大（35%）和 Opus 模型推理慢（25%），默认 60 秒超时阈值对大型任务不够
2. 最佳实践：处理大型任务时切换到 Sonnet 模型并增加超时阈值到 120 秒，同时分模块处理减少单次请求 Token 数
3. 快速恢复：偶发超时等待 30 秒重试；频繁超时使用 /compact + 分模块处理
4. 网络优化：测量网络延迟，高延迟时优化代理或直连，减少传输时间
5. 最佳实践建议：养成定期 /compact 的习惯控制上下文大小，大型分析任务按目录/模块分批处理，避免单次请求超过 100K tokens

故障排查流程图

flowchart TD
    A[出现 Request timed out] --> B{是否偶发?}
    B -->|是| C[等待 30 秒后重试]
    B -->|否, 频繁超时| D{当前使用哪个模型?}
    C --> E{重试成功?}
    E -->|是| F[✅ 临时波动已恢复]
    E -->|否| D
    D -->|Opus| G[切换到 Sonnet]
    D -->|Sonnet| H[增加超时阈值]
    G --> I[重新发送请求]
    H --> J[export CLAUDE_API_TIMEOUT=120000]
    J --> I
    I --> K{超时消失?}
    K -->|是| F
    K -->|否| L[使用 /compact 压缩上下文]
    L --> M[分模块处理大任务]
    M --> N{超时消失?}
    N -->|是| F
    N -->|否| O[检查网络延迟]
    O --> P{延迟 > 200ms?}
    P -->|是| Q[优化代理或直连]
    P -->|否| R[使用 --no-mcp 排查]
    Q --> I
    R --> S{禁用 MCP 后正常?}
    S -->|是| T[移除慢速 MCP Server]
    S -->|否| U[检查第三方路由延迟]
    T --> F
    U --> F