公司网里 Claude Code 连不上：network config 页列的代理与放行项

在公司网里第一次起 Claude Code，很容易卡在同一类地方：终端里报连接错误或者证书错误，换个家里的网就好了。这类问题的处置路径，官方文档集中放在 code.claude.com/docs/en/network-config 这一页（页面标题是 Enterprise network configuration），里面把代理变量、放行主机、后台会话怎么继承配置都写明了。下面按排查顺序走一遍。

这一页同时还讲了自定义 CA 与 mTLS 客户端证书，那部分我们另有一篇专门讲，本文不展开，只在有交叉的地方点一句。

一、先分清是哪一类”连不上”

文档里能对上号的现象有这么几种，处置路径完全不同：

• 启动阶段直接失败，错误信息里点名了某个变量。这一页写明：Claude Code 在读取这些设置时不校验其中的大部分，唯一在启动时检查的是代理 URL——当它解析不了这个值（例如缺了 http:// 这个 scheme），会中止启动并报错，错误里会指出该修哪个变量。
• 启动能起来，发请求时才报连接错误或证书错误。文档说这是常态：大部分配置项的问题要等到后面某次请求才暴露出来。
• 首次安装的连通性检查失败。文档写明：first-run setup 的连通性检查在够不到 api.anthropic.com 或 platform.claude.com 时，会把你指向这一页。
• 在自己的终端里是好的，后台会话不行。这一类基本不是代理地址写错，见下面第五节。

二、判定动作：--debug 与 /status

不要靠猜。这一页给了两个可执行的确认手段。

第一个是带调试日志启动：

claude --debug

文档写明调试输出不打在终端里，而是写到 ~/.claude/debug/<session-id>.txt，或者你用 --debug-file <path> 指定的路径。

第二个是在交互会话里跑 /status，这一页列出了要看的几行。跟代理直接相关的是 Proxy 这一行：文档写它显示当前生效的代理 URL，并且会把它解析不了的值标记为 invalid and ignored。另外几行 mTLS client cert、mTLS client key、Additional CA cert(s) 属于证书那一块，这里不展开——只提醒一点，文档明说 Additional CA cert(s) 那一行只显示路径，不代表文件真的加载成功了，那个得回调试日志里确认。

所以判定很直接：/status 的 Proxy 行为空或者被标成 invalid，就说明变量压根没进来、或者格式不合法，先解决这一层，再谈放行清单。

三、代理字段照文档怎么写

文档说 Claude Code 认标准代理环境变量，示例原文如下：

# HTTPS proxy (recommended)
export HTTPS_PROXY=https://proxy.example.com:8080

# HTTP proxy (if HTTPS not available)
export HTTP_PROXY=http://proxy.example.com:8080

# Bypass proxy for specific requests - space-separated format
export NO_PROXY="localhost 192.168.1.1 example.com .example.com"
# Bypass proxy for specific requests - comma-separated format
export NO_PROXY="localhost,192.168.1.1,example.com,.example.com"
# Bypass proxy for all requests
export NO_PROXY="*"

几处容易踩的地方，都是这一页白纸黑字写的：

NO_PROXY 的两种分隔符都收。空格分隔和逗号分隔各给了一份示例，* 表示全部绕过。前缀点的写法（.example.com）也在示例里。

大小写变体的优先级是有顺序的。文档写明小写变体同样有效，Claude Code 按 https_proxy、HTTPS_PROXY、http_proxy、HTTP_PROXY 这个顺序取第一个被设置的。这一条在排查时很关键：如果你在 ~/.bashrc 里留过一个旧的小写 https_proxy，后来又在别处 export 了大写的，生效的是小写那个——排在前面。

不支持 SOCKS 代理。文档里是一条独立的 Note。公司只给 SOCKS 出口的话，这条路本身走不通，别在变量格式上继续折腾。

需要 basic 认证时把凭据写进代理 URL：

export HTTPS_PROXY=http://username:password@proxy.example.com:8080

文档在这里跟了一条 Warning：避免把密码硬编码进脚本，改用环境变量或安全的凭据存储。至于 NTLM、Kerberos 这类更复杂的认证，文档的建议是考虑用一个支持你那种认证方式的 LLM gateway 服务，并没有说 Claude Code 自己能直接处理。

还有一条时序上的坑：这一页开头就写了，这些环境变量要在启动 Claude Code 之前设好；shell 里 export 的变量在启动时读一次，运行中的会话不会捡起你后来对 shell 环境做的改动。改完变量要重开会话。

另外，文档有一条 Note 写明：这一页上出现的所有环境变量，也都可以在 settings.json 里配。这一条在 Windows 上尤其有用，见第五节。

四、放行范围：这一页列的是哪些主机

文档给了一张表，逐行列出 Claude Code 需要访问的 URL，并要求在代理配置和防火墙规则里放行，尤其是在容器化或受限网络环境里。这里按用途归一下类，主机名一个不加、一个不改：

主机	文档写明的用途
api.anthropic.com	Claude API 请求，含 WebFetch 的域名安全检查、feature flag 拉取、遥测事件上报
claude.ai	claude.ai 账号认证
claude.com	claude.ai 登录会在浏览器里打开一个 claude.com 页面再跳到 claude.ai；CLI 侧预批准的 WebFetch 文档查询也会到这个主机
platform.claude.com	Anthropic Console 账号认证；OAuth token 的交换、刷新、吊销也走这里，所以 Console 和 claude.ai 两种登录都需要它
mcp-proxy.anthropic.com	来自 claude.ai 的 MCP connectors（含管理员配置的），流量经这个代理
downloads.claude.ai	plugin 可执行文件下载；原生安装器、原生自动更新与版本检查
storage.googleapis.com	/plugin 里显示的安装量与 plugin 元数据；签名 artifact 上传优先走这里，被挡时回落到 api.anthropic.com。另外，2.1.116 之前版本的原生安装器与自动更新也用它
registry.npmjs.org	plugin 安装（拉 npm 源的 plugin 包及其 Node.js 依赖）、npx 启动的 MCP 服务、以及用 npm/bun 安装 Claude Code 本身
bridge.claudeusercontent.com	Claude in Chrome 扩展的 WebSocket bridge
raw.githubusercontent.com	/release-notes 的更新日志源
http-intake.logs.us5.datadoghq.com	运营遥测事件（可选，见下）
browser-intake-us5-datadoghq.com	运营错误报告（可选，见下）
formulae.brew.sh	Homebrew 安装方式的版本检查，其它安装方式不联系这个主机
code.claude.com	内置 claude-code-guide agent 的文档查询与预批准的 WebFetch 请求；挡掉它只影响文档查询

这张表怎么读，比表本身重要：

先看认证。 卡在登录不去的，重点是 claude.ai、claude.com、platform.claude.com，而 platform.claude.com 两种登录方式都要——只放行 claude.ai 是常见的漏项。

再看安装方式相关的行。 文档写明：走 npm 安装或自管分发二进制的，终端用户用不到 downloads.claude.ai 里原生安装器与自动更新那部分用途；但 npm 和 bun 安装需要 registry.npmjs.org，除非你们组织自建了镜像。表里的其它用途与安装方式无关。

两个 Datadog 主机是可选的。 文档写明它们只承载可选的运营遥测，设置 CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC 可以把两个都关掉；并且第三方 provider 上的会话从不向这两个主机发送。定稿放行清单之前，文档建议先看 Telemetry services 那一页。

用第三方 provider 不等于这张表全都不用管。 文档写明：走 Amazon Bedrock、Google Cloud’s Agent Platform、Microsoft Foundry 或已登录的 Claude apps gateway 会话时，模型流量与认证走你的 provider 或 gateway，而不是 api.anthropic.com、claude.ai、platform.claude.com；但 WebFetch 工具仍会调 api.anthropic.com 做域名安全检查，除非你在设置里加 skipWebFetchPreflight: true。

五、Windows 侧与后台会话：export 覆盖不到的地方

Windows。 上面的示例都是 POSIX shell 的 export 写法，Windows 下用什么命令设置这些环境变量，这一页没有给出对应写法，我们不替它编。但文档给了一条更稳的路：这一页所有环境变量都能写进 settings.json 的 env 块，比如：

{
  "env": {
    "HTTPS_PROXY": "https://proxy.example.com:8080",
    "NO_PROXY": "localhost,192.168.1.1,example.com,.example.com"
  }
}

以上为按官方文档中的参数语义组合的示例，未经实测，以官方文档与 --help 的实际输出为准。

后台会话。 文档专门有一节讲这件事：background agents 不跑在派发它们的那个终端里，是一个按需启动、比你的 shell 活得久的 per-user 监督进程在托管 claude agents、--bg 与 /background 的会话。这个监督进程是所有终端共用的一个进程，它继承的是最先把它冷启动起来的那个 shell 的环境；由操作系统安装成服务的那种则根本收不到 shell 环境。

所以只在 shell 里 export 代理、CA 路径或 mTLS 变量，能不能到达后台会话取决于当时是哪个 shell 把监督进程冷启动的，碰不上就静默不生效。要覆盖所有机器上的所有后台会话，只有 ~/.claude/settings.json 的 env 块或 managed settings 这一条路。

企业启动器（corporate launcher）。 有些组织要求每个进程都经由公司启动器起来，以套用 sandbox、网络管控或凭据注入。文档写明：监督进程与它的 worker 是按固定路径启动 Claude Code 的，不走 PATH 查找 claude，所以你放在 PATH 靠前位置的包装脚本对后台会话是无效的；要覆盖它们得设 processWrapper 设置项，或等价的 CLAUDE_CODE_PROCESS_WRAPPER 环境变量（两者都设时后者优先），并且同样要通过 managed settings 或 ~/.claude/settings.json 下发，不能靠 shell export。

这里有两条版本与作用域上的边界得一并记住，code.claude.com/docs/en/corporate-launcher 那一页写得很明确。一条是版本门槛：CLAUDE_CODE_PROCESS_WRAPPER 要 v2.1.208 或更新的版本，processWrapper 这个设置项要 v2.1.210 或更新的版本；更早的版本会忽略它们并且照常起未包装的进程，其中 processWrapper 是被当作未知键忽略的，不报任何错。也就是说配置文件里写着不代表它生效了，得按前面第六节的验证步骤确认一次。另一条是作用域：项目里的 .claude/settings.json 与 .claude/settings.local.json 配不了启动器——文档写明 Claude Code 会忽略这两个文件里的 CLAUDE_CODE_PROCESS_WRAPPER 并在调试日志里留一条警告，processWrapper 这个键则根本不从这两个文件里读。所以这一项只能落在 managed settings 或用户级设置里。

这里有一条 Windows 用户必须知道的边界：code.claude.com/docs/en/corporate-launcher 这一页写明，在 Windows 上这个变量会被忽略——启动器契约依赖 exec，而 Windows 不支持它。设了变量的 Windows 机器会照常工作，但每个进程都是没被包装的，唯一的信号是调试日志里的一条警告。文档直说了：如果你们的启动器策略覆盖 Windows，这个变量在那里不满足策略，做推广计划时要把 Windows 机器算作未包装。

还有一条 Note：已经在跑的监督进程会一直沿用它启动时的那套配置。下发启动器设置之后要执行 claude daemon stop --any，下一次 claude agents 或 --bg 才会起一个遵守新配置的监督进程；安装成服务的那种用不带 --any 的 claude daemon stop。

六、改完怎么验证

按文档给的顺序验：

1. 重开会话（变量启动时读一次）。
2. /status 看 Proxy 行：显示出你配的代理 URL，且没有被标成 invalid and ignored。
3. claude --debug 起一次，去 ~/.claude/debug/<session-id>.txt 里翻加载记录；文档写明读不到文件时日志里会出现 Failed to read 或 Failed to load 开头的行并附带原因。
4. 涉及启动器的，用 /status 的 Self-exec 条目——文档写它显示解析后的启动命令，并在运行中的后台服务与之不匹配时给出警告；claude daemon status 在 shell 里打印同样的信息。

七、什么情况说明不是代理与放行的问题

这一步最容易被跳过，但它能省掉几个小时。以下几种情况，改代理和加放行都不解决问题：

• fast mode 报连通性错误，但你已经走 LLM gateway 了。 文档写明：通过 ANTHROPIC_BASE_URL 走 gateway 时，fast mode 的可用性检查仍然调 api.anthropic.com，而不是 gateway 的 base URL。这个检查会遵守已配置的 HTTP 代理，所以如果病因确实是网络封锁，在代理里给 api.anthropic.com 加放行是解法；但文档同时写了另一种情况：当这个检查提交的是 gateway 签发的、而 Anthropic 不认的凭据时，报的是同一个连通性错误——那种情况下加白名单没用，因为根本没有东西被挡。看到同样的报错先分清是哪一种。
• Claude Desktop 或浏览器里的 claude.ai 打开是白页。 文档写明上面那张表覆盖的是独立 CLI；Desktop 与浏览器还会从额外的 Anthropic CDN 主机加载应用代码与用户内容（含 assets-proxy.anthropic.com 与承载 artifacts 的 *.claudeusercontent.com 源）。放行了 claude.ai 却挡掉这些主机，得到的是白页而不是报错。白页就该往这个方向查，不是 CLI 的放行清单问题。
• cloud 会话里怎么配都不生效。 文档写明在 cloud sessions 里，是托管环境在管理到 API 的连接，因此当 CLAUDE_CODE_CLIENT_CERT、CLAUDE_CODE_CLIENT_KEY、CLAUDE_CODE_CLIENT_KEY_PASSPHRASE、NODE_EXTRA_CA_CERTS、NODE_TLS_REJECT_UNAUTHORIZED、CLAUDE_CODE_OAUTH_SCOPES 这些变量来自设置文件的 env 块时会被忽略，并且每个被忽略的键都会记到会话的调试日志里。
• 只有 code.claude.com 不通。 文档明说挡掉它只影响文档查询，不影响别的。
• 流式响应中断而不是连不上。 这一页另有一节讲三个各自独立的空闲看门狗计时器，会在流式响应静默时中止它，让死连接失败重试而不是一直挂着；对应的开关是 CLAUDE_ENABLE_STREAM_WATCHDOG、CLAUDE_ENABLE_BYTE_WATCHDOG、CLAUDE_STREAM_IDLE_TIMEOUT_MS、CLAUDE_BYTE_STREAM_IDLE_TIMEOUT_MS 与 API_FORCE_IDLE_TIMEOUT。中途断流该往这里查，跟放行清单没关系。
• 公司出口只有 SOCKS。 前面说过，文档写明不支持，不是配置问题。

最后一句老生常谈但确实必要：这一页的变量名、/status 里的行、放行主机表都会随版本变。上面每一条都能在 code.claude.com/docs/en/network-config 与 code.claude.com/docs/en/corporate-launcher 上逐字对到，但真要动生产网络的防火墙规则之前，以官方文档最新内容为准。

---

本文依据 Claude Code 官方文档（code.claude.com/docs）于 2026-08-17 的公开内容整理。 该产品闭源，本文只复述官方文档写明的机制，不推断其内部实现； 我们没有对文中涉及的功能做过实测，因此不涉及界面外观、操作手感与运行速度的任何描述。 该产品迭代频繁，文中涉及的命令、配置项与默认值随版本变动，请以官方文档最新内容为准。 本文不涉及价格、额度与限流的具体数值，相关信息请以官方定价与用量说明页为准。 安全与合规相关做法请结合自身环境评估，本文不构成安全方案建议。