Claude Code 代理环境变量写对了，超时问题能少一半
Claude Code 提示 Unable to connect、No response from API，或者会话跑到一半停住，很多时候不是网络本身有问题，而是 HTTPS_PROXY、NO_PROXY 这些环境变量写法不对、没有生效，或者被别的变量覆盖了。本文整理 Claude Code 代理与超时相关环境变量的正确写法和常见误区，所有变量名、默认值和行为都对照 Claude Code 官方文档（网络配置页、环境变量页与错误参考页）核对，查阅日期为 2026 年 9 月 20 日。Claude Code 更新频繁，个别变量有最低版本要求，文中会逐一标注。
文中的代理地址 proxy.example.com 和端口都是占位示例，请替换成你实际使用的地址。
代理变量的正确写法
官方文档说明，Claude Code 遵循标准的代理环境变量，最基本的写法是下面这样：
export HTTPS_PROXY=https://proxy.example.com:8080
export HTTP_PROXY=http://proxy.example.com:8080
export NO_PROXY="localhost,192.168.1.1,example.com,.example.com"文档把 HTTPS_PROXY 标为推荐用法，只有在没有 HTTPS 代理可用时才用 HTTP_PROXY。
大写和小写变量同时存在时，哪个生效
Claude Code 同时接受小写变量，并且按 https_proxy、HTTPS_PROXY、http_proxy、HTTP_PROXY 的顺序取第一个已设置的值。这意味着小写优先：如果你的 shell 配置里很早以前留下了一个小写的 https_proxy，后来只改了大写的 HTTPS_PROXY，实际生效的仍然是旧的小写值。排查时用 env | grep -i proxy 把大小写两种写法都列出来，看有没有互相矛盾。
NO_PROXY 支持哪些写法
官方文档给出的写法有三种：空格分隔（"localhost 192.168.1.1 example.com .example.com"）、逗号分隔（"localhost,192.168.1.1,example.com,.example.com"），以及用 "*" 表示所有请求都绕过代理。另外，文档特别说明 Claude Code 不会把发往 localhost、::1 和 127.0.0.0/8 的 WebSocket 连接送进代理，所以这些回环地址不必写进 NO_PROXY。
SOCKS 地址和复杂认证怎么办
文档明确写着：Claude Code 不支持 SOCKS 代理。所以把 socks5:// 开头的地址填进 HTTPS_PROXY 是常见错误，应该改用代理软件提供的 HTTP 类型监听地址。需要基本认证时，把用户名和密码写进代理地址：http://用户名:密码@proxy.example.com:8080，官方同时提醒不要把密码硬编码在脚本里。如果代理要求 NTLM 或 Kerberos 这类更复杂的认证，官方建议改用支持该认证方式的 LLM 网关服务。
让变量真正生效：三个容易漏掉的环节
为什么改了变量，正在运行的会话没有变化
官方文档说明，shell 里导出的变量只在启动时读取一次，运行中的会话不会感知之后的修改。改完变量必须重新启动 Claude Code。同时，代理地址是启动时唯一会被校验的设置：如果地址无法解析，比如缺少 http:// 前缀，Claude Code 会直接终止启动，并指出需要修改的变量名。其他设置（证书路径等）不会在启动时校验，错误要等到后面某次请求失败才会暴露。
为什么后台任务没有走代理
使用后台代理（background agents）时，会有一个每用户唯一的监督进程托管这些会话，它继承的是最先启动它的那个 shell 的环境，用系统服务安装时则拿不到任何 shell 环境。官方的建议是：把代理、证书等网络变量写进 ~/.claude/settings.json 的 env 块，而不是只在 shell 里导出，这是唯一能保证每个后台会话都生效的方式。
怎么确认配置已经加载
官方给出了两个办法。一是在交互会话里执行 /status，其中的 Proxy 一行会显示当前生效的代理地址，无法解析的值会被标记为无效并忽略。二是用 claude --debug 启动，调试日志默认写入 ~/.claude/debug/ 下以会话编号命名的文件，也可以用 --debug-file 路径 指定位置。自定义证书通过 NODE_EXTRA_CA_CERTS 指定，日志里会出现 Appended extra certificates 之类的确认行；默认情况下 Claude Code 同时信任自带的 Mozilla 根证书和操作系统证书库，由 CLAUDE_CODE_CERT_STORE 控制，默认值是 bundled,system。
超时相关变量：默认值和适用范围
| 变量 | 默认值或说明 | 作用 |
|---|---|---|
| API_TIMEOUT_MS | 默认 600000 毫秒（10 分钟） | API 请求超时，慢速网络或经代理时可调大 |
| BASH_DEFAULT_TIMEOUT_MS | 默认 120000 毫秒（2 分钟） | 长时间运行的 bash 命令的默认超时 |
| BASH_MAX_TIMEOUT_MS | 默认 600000 毫秒（10 分钟） | 模型可以设置的 bash 超时上限 |
| CLAUDE_STREAM_IDLE_TIMEOUT_MS | 事件级看门狗默认 300 秒，低于 5 分钟的值会被提高到 5 分钟 | 流式响应空闲看门狗的超时 |
| CLAUDE_BYTE_STREAM_IDLE_TIMEOUT_MS | 限制在 10 秒到 30 分钟之间，需要 v2.1.210 及以上版本 | 仅调整字节级看门狗 |
| API_FORCE_IDLE_TIMEOUT | 设为 0 关闭、设为 1 对所有提供方开启 | 5 分钟的响应体空闲超时 |
要理解「流式响应空闲」，需要知道官方文档里的四个独立计时器：等待响应头的首字节期限（直连 Anthropic API 时为 180 秒）、事件级看门狗（300 秒）、字节级看门狗（直连时 180 秒）和响应体空闲超时。它们的作用是让一条已经死掉的连接尽快失败并重试，而不是一直挂着。也就是说，你看到的「卡住几分钟后自动重试」多半是看门狗在工作，并不是 Claude Code 自己出了故障。
此外，官方文档要求把 api.anthropic.com、claude.ai 和 platform.claude.com 加入代理和访问控制策略的放行列表，后两者用于账号认证和令牌刷新，认证失败时不要只检查第一个。通过 ANTHROPIC_BASE_URL 走网关时，首字节看门狗不适用，具体行为以官方页面为准。
五个常见误区
- 把 SOCKS 地址填进 HTTPS_PROXY：官方明确不支持，应改用 HTTP 类型的监听地址。
- 只改大写变量：小写的 https_proxy 优先级更高，旧值会继续生效。
- 改完变量不重启：变量只在启动时读取一次。
- 只在 shell 里 export，却期待后台任务也走代理：应写进 settings.json 的 env 块。
- 用调大 API_TIMEOUT_MS 代替解决线路问题：默认已经是 10 分钟，再调大只会让失败来得更慢。
变量都对了仍然不稳，换个角度看出口线路
配置全部核对无误、超时依然反复出现，就该看出口线路了。一个可以自己复现的做法：用 curl -sS -o /dev/null -w "%{time_connect} %{time_appconnect}\n" https://api.anthropic.com 每分钟记录一次，连续半小时以上，分别在不同时段和不同网络环境下各做一轮，重点看 time_connect 的波动幅度而不是平均值。波动集中在某个环境，说明线路才是瓶颈。这种情况下可以给开发机换一条更稳定的出口，NasaCode 针对 Claude Code、Cursor 和 IDE 场景提供直连优化，并带有 AI 智能路由；是否改善，以你自己的前后耗时记录为准。文中变量和默认值以 2026 年 9 月 20 日查阅的官方文档为准，升级 Claude Code 之后请重新核对。
延伸阅读
