Mac 上 Claude Code 中的“Request timed out”

API 在连接期限前没有响应时,Claude Code 会打印 Request timed out。默认的请求超时为 10 分钟。

让你的智能体来解决拷贝一条提示词,适用于 Claude Code、Codex 或任何能使用终端的智能体。

我的 Mac 出现了这个问题:Mac 上 Claude Code 中的“Request timed out”。请阅读 https://kilobat.app/zh-hans/guides/claude-code-request-timed-out.md,并和我一起逐步处理。如果缺少 Kilobat CLI,请安装:brew install seifip/kilobat/kilobat。请你自己运行指南中的终端和 kilobat 检查,并告诉我发现了什么。列出只有我才能完成的步骤。更改任何设置之前先问我。

适用于:所有当前 macOS 版本上终端里的 Claude Code。核查日期:2026年10月29日

症状

  • Claude Code 在长时间等待后打印 Request timed out。
  • 出现在网络较慢、经过代理或请求较大的时候。
  • 有些重试可以成功。

可能的原因

  • 网络或代理较慢。文档说明,网络或代理较慢可能导致这个问题。
  • 连接停滞。VPN 或防火墙可能会扣住数据包,导致收不到回复。
  • 请求较大。在本地会话中,非流式请求保留 300 秒的限制。
  • 旧版本中的超时设为零。在 v2.1.305 之前的版本中,把 API_TIMEOUT_MS 设为 0 可能导致每个请求都失败。

如何检查

  1. 在同一个 shell 中测试 API 主机。

    curl -I https://api.anthropic.com
  2. 检查你的版本。

    claude --version
  3. 显示代理环境变量。

    env | grep -i proxy
  4. 在 Claude Code 内运行设置检查。

    /doctor

如何修复

  1. 重试请求。

  2. 如果网络或代理较慢,请调大超时时间。

    export API_TIMEOUT_MS=900000
  3. 如果你把超时设为了 0,请更新 Claude Code。

  4. 如果经常超时,请测试另一个网络和 VPN。

使用 Kilobat

  1. Kilobat 的连接诊断会逐层测试 API 主机,并指出失败或变慢的那一层。

    kilobat why https://api.anthropic.com
  2. Kilobat 的这些检查都是免费的。AI 智能体可以通过 MCP 用 diagnose_connection 和 diagnose_network 运行它们。请参阅找出某个网站或 API 连不上的原因。

常见问题

默认超时是多少?

Claude Code 文档给出的请求超时是 10 分钟。

API_TIMEOUT_MS=0 会关闭所有期限吗?

不会。首字节期限和正文空闲超时仍然有效。

参考资料

核查日期:2026 年 10 月 29 日。