企业网络配置

为企业环境配置 Claude Code，支持代理服务器、自定义证书颁发机构 (CA) 和相互传输层安全 (mTLS) 身份验证。

Claude Code 通过环境变量支持各种企业网络和安全配置。这包括通过公司代理服务器路由流量、信任自定义证书颁发机构 (CA)，以及使用相互传输层安全 (mTLS) 证书进行身份验证以增强安全性。

在启动 Claude Code 之前设置这些环境变量。在 shell 中导出的变量在启动时读取一次，因此运行中的会话不会获取 shell 环境的后续更改。

代理配置

环境变量

Claude Code 遵守标准代理环境变量。在 Claude Desktop 会话中，当应用管理提供商连接时，Claude Code 仅从托管设置和 ~/.claude/settings.json 中读取它们；有关范围规则，请参阅 mTLS 身份验证。

# HTTPS 代理（推荐）
export HTTPS_PROXY=https://proxy.example.com:8080

# HTTP 代理（如果 HTTPS 不可用）
export HTTP_PROXY=http://proxy.example.com:8080

# 绕过特定请求的代理 - 空格分隔格式
export NO_PROXY="localhost 192.168.1.1 example.com .example.com"
# 绕过特定请求的代理 - 逗号分隔格式
export NO_PROXY="localhost,192.168.1.1,example.com,.example.com"
# 绕过所有请求的代理
export NO_PROXY="*"

小写变体也可以工作，Claude Code 按照 https_proxy、HTTPS_PROXY、http_proxy、HTTP_PROXY 的顺序使用第一个已设置的变量。

Claude Code 永远不会通过代理发送其 WebSocket 连接到 localhost、::1 或 127.0.0.0/8，因此您不需要在 NO_PROXY 中为它们添加环回条目。

基本身份验证

如果您的代理需要基本身份验证，请在代理 URL 中包含凭证：

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

CA 证书存储

默认情况下，Claude Code 信任其捆绑的 Mozilla CA 证书和您的操作系统的证书存储。读取操作系统存储需要具有 tls.getCACertificates 的运行时：本机安装程序始终具有它，npm 安装需要 Node 22.15 或更高版本。在较旧的 Node 版本上，仅捆绑的集合和 NODE_EXTRA_CA_CERTS 适用。企业 TLS 检查代理在其根证书安装在操作系统信任存储中且运行时可以读取它时无需额外配置即可工作。

CLAUDE_CODE_CERT_STORE 接受逗号分隔的源列表。识别的值为 bundled（Claude Code 附带的 Mozilla CA 集）和 system（操作系统信任存储）。默认值为 bundled,system。

仅信任捆绑的 Mozilla CA 集：

export CLAUDE_CODE_CERT_STORE=bundled

仅信任操作系统证书存储：

export CLAUDE_CODE_CERT_STORE=system

自定义 CA 证书

如果您的企业环境使用自定义 CA，请配置 Claude Code 以直接信任它：

export NODE_EXTRA_CA_CERTS=/path/to/ca-cert.pem

mTLS 身份验证

对于需要客户端证书身份验证的企业环境：

# 用于身份验证的客户端证书
export CLAUDE_CODE_CLIENT_CERT=/path/to/client-cert.pem

# 客户端私钥
export CLAUDE_CODE_CLIENT_KEY=/path/to/client-key.pem

# 可选：加密私钥的密码短语
export CLAUDE_CODE_CLIENT_KEY_PASSPHRASE="your-passphrase"

Claude Code 在启动时读取证书和密钥文件，并在每次应用设置时重新读取它们，例如当您的组织在会话中期更改托管设置中的 env 块时。

要轮换证书和密钥，请替换相同路径上的文件。Claude Code 在运行会话中无需重启即可获取替换。当 API 请求因连接级错误（如连接重置或 TLS 握手错误）失败时，它会重新读取两个文件并使用新的密钥对重试请求。在 v2.1.232 之前，Claude Code 不会在连接错误时重新读取，因此它会保持已加载的密钥对，直到下次应用设置或您重启为止。

Claude Code 根据失败的请求重新读取文件，而不是通过监视文件更改：

• 时间：Claude Code 在您替换文件时不执行任何操作。它在符合条件的失败后的重试时或在下次应用设置时呈现新的密钥对，以先发生者为准。
• 网关拒绝：当您的网关重置连接或在停止接受旧密钥对后拒绝 TLS 握手时，Claude Code 会重新读取。当网关完成握手并用 HTTP 错误响应时，它不会重新读取。在这种情况下，Claude Code 在下次应用设置时或重启时加载新的密钥对。
• 半写入轮换：当 Claude Code 在您的轮换进行中期重新读取时，例如读取不匹配的证书和密钥，它会保持之前的密钥对并在下次失败时重新读取。
• OTLP 遥测导出器：Claude Code 保持导出器在首次使用时加载的证书，因此请重启 Claude Code 以使轮换的证书到达您的遥测收集器。
• 关闭重新加载：设置 CLAUDE_CODE_DISABLE_MTLS_RELOAD_ON_STALE_CONNECTION=1 以关闭连接错误重新读取。Claude Code 然后仅在下次应用设置或下次启动时获取轮换的文件。

要确认 Claude Code 已获取轮换，请使用调试日志启动会话并在日志中查找 Stale connection — reloaded rotated mTLS client material。当 Claude Code 在应用设置时获取轮换时，它不会记录此行，因此仅缺少一行并不意味着轮换失败。

在当前密钥对过期之前替换文件，以便 Claude Code 在下次启动时不会加载已过期的密钥对。

在云会话中，托管环境管理与 API 的连接，因此当这些变量来自设置文件 env 块时，Claude Code 会忽略以下变量：

• 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

Claude Code 在会话的调试日志中记录每个被忽略的密钥。

在Claude Desktop会话中，应用管理提供商连接，例如第三方提供商上的代码选项卡和 Cowork 会话，Claude Code 仅从托管设置和 ~/.claude/settings.json 读取这些变量和代理变量 HTTP_PROXY、HTTPS_PROXY 和 NO_PROXY：它忽略存储库自己的设置文件中的这些变量，因此已检出的存储库无法重定向凭证来自应用的会话的 TLS 或代理路径。在通过 claude.ai 登录的本地、SSH 或 WSL 代码选项卡会话中，应用不管理连接，Claude Code 从每个设置范围读取这些变量，就像任何终端会话一样；云会话无论您在何处启动它们，都遵循上述云会话规则。在 v2.1.217 之前，当应用管理连接时，Claude Code 忽略每个设置文件中的这些变量。

验证你的配置

你通常会从后续请求中的连接或证书错误发现代理地址错误或证书路径不正确的问题，因为 Claude Code 在读取这些设置时不会验证大多数设置。它在启动时检查的唯一设置是代理 URL：当它无法解析该值（例如缺少 http:// 方案）时，Claude Code 会停止启动并显示一个错误，指出需要修复的变量。

要在发送请求之前确认你的配置已加载，请使用调试日志启动 Claude Code：

claude --debug

调试输出会进入 ~/.claude/debug/<session-id>.txt 而不是终端，或进入你使用 --debug-file <path> 设置的路径。在日志中，查找确认每个文件已加载的行：

CA certs: Appended extra certificates from NODE_EXTRA_CA_CERTS (/etc/ssl/certs/corp-ca.pem)
mTLS: Loaded client certificate from CLAUDE_CODE_CLIENT_CERT
mTLS: Loaded client key from CLAUDE_CODE_CLIENT_KEY

如果 Claude Code 无法读取其中一个文件，日志会显示 Failed to read 或 Failed to load 行以及原因。

你也可以在交互式会话中运行 /status 并检查这些行：

• Proxy：显示活跃的代理 URL，并将无法解析的值标记为无效且被忽略。
• mTLS client cert 和 mTLS client key：仅在文件加载时出现，所以缺少该行意味着加载失败，调试日志中有原因。
• Additional CA cert(s)：显示 NODE_EXTRA_CA_CERTS 路径而不检查文件是否已加载，所以请在调试日志中确认这一项。

为后台代理应用网络设置

后台代理不在分派它们的终端内运行。一个按用户的监督进程按需启动，生命周期超过你的 shell，并托管每个 claude agents、--bg 和 /background 会话。请参阅后台会话如何被托管。这改变了此页面上的配置如何到达这些会话的方式。

在设置中设置网络变量，而不是在 shell 中

监督进程是由每个终端共享的一个进程。它继承启动它的第一个 shell 的环境，而操作系统安装的监督进程根本不接收任何 shell 环境。如果你仅在 shell 中导出代理、CA 路径或 mTLS 变量，当该 shell 碰巧冷启动监督进程时，它会到达后台代理，而当不同的 shell 启动时，它会无声地失败。

将相同的变量放在 ~/.claude/settings.json 的 env 块中或托管设置中。此页面上的每个变量都可以在那里设置，设置是唯一到达每台机器上每个后台会话的配置。

将企业启动器配置为设置

某些组织要求每个 Claude Code 进程都通过应用沙箱、网络控制或凭证注入的企业启动器启动。监督进程及其工作进程从固定路径启动 Claude Code，而不是在 PATH 上查找 claude，因此每个后台代理都绕过你在 PATH 上放置的包装器。

设置 processWrapper 设置以使用你的启动器为监督进程、其工作进程和启动器覆盖的内容下列出的其他后台进程添加前缀。等效的 CLAUDE_CODE_PROCESS_WRAPPER 环境变量在两者都设置时优先，它受相同规则约束：通过托管设置或 ~/.claude/settings.json 传递它，而不是 shell 导出。在企业启动器后面运行 Claude Code涵盖启动器必须满足的合同、它做什么和不做什么，以及如何推出它。

流式空闲监视器

Claude Code 运行四个独立的计时器，当流式模型响应变得安静时会中止该响应，因此死连接会失败并重试，而不是挂起。首字节截止时间涵盖等待响应头的时间，在响应到达之前。其他三个监视器各自监视实时响应的不同信号。

使用这些变量配置计时器，每个都在 环境变量参考 中详细说明：

• CLAUDE_ENABLE_STREAM_WATCHDOG 和 CLAUDE_ENABLE_BYTE_WATCHDOG 在表列出的连接范围内，用 1 强制打开相应的监视器或用 0 关闭；这两个变量都不会将监视器扩展到它不覆盖的连接类型。CLAUDE_ENABLE_BYTE_WATCHDOG 设置为 0 也会关闭首字节截止时间。
• CLAUDE_STREAM_IDLE_TIMEOUT_MS 设置两个监视器的超时。Claude Code 将低于 5 分钟的值提高到 5 分钟，并将字节级监视器的值上限设为 30 分钟。
• CLAUDE_BYTE_STREAM_IDLE_TIMEOUT_MS 设置字节级监视器的超时，而不改变事件级监视器的超时，限制在 10 秒到 30 分钟之间，并优先于 CLAUDE_STREAM_IDLE_TIMEOUT_MS 用于该监视器。
• CLAUDE_STREAM_FIRST_BYTE_TIMEOUT_MS 直接设置首字节截止时间。保持未设置状态，Claude Code 使用字节级监视器的超时，因此 CLAUDE_STREAM_IDLE_TIMEOUT_MS 和 CLAUDE_BYTE_STREAM_IDLE_TIMEOUT_MS 也会改变截止时间。有关限制、上传限额、API_TIMEOUT_MS 上限以及重试在无响应中止后等待多长时间，请参阅 No response from API。
• API_FORCE_IDLE_TIMEOUT 设置为 0 会关闭正文空闲超时，设置为 1 会为每个提供商打开它。监视器独立于它运行，因此要让流暂停超过其阈值，还要提高或禁用它们。

当监视器中止停滞的流时，Claude Code 将中止视为中流失败，您看到的内容取决于响应已进行到多远。Claude Code 重试请求或以错误结束轮次，保留已完成的输出并显示 不完整响应通知，或正常结束轮次。自动重试 说明每个结果适用的位置。

在 非交互式会话 中，以及在任何会话中的子代理响应中，Claude Code 可能首先提示 Claude 继续被截断的响应；该通知的条目 说明何时执行此操作以及何时您仍然看到通知。

当首字节截止时间触发时，没有响应已开始，因此没有部分输出要保留。有关 Claude Code 如何重新发送请求以及何时轮次改为结束，请参阅 No response from API。

网络访问要求

Claude Code 需要访问以下 URL。在代理配置和防火墙规则中将这些 URL 加入白名单，特别是在容器化或受限网络环境中。当首次运行设置无法连接到 api.anthropic.com 或 platform.claude.com 时，连接性检查会指向这里；有关检查消息和恢复步骤，请参阅无法连接到 Anthropic 服务。

如果您通过 npm 安装 Claude Code 或管理自己的二进制分发，最终用户不需要 downloads.claude.ai 的本机安装程序和自动更新程序用途，但 npm 和 bun 安装需要其包注册表 registry.npmjs.org，除非您的组织镜像它。表中的其他用途适用于任何安装方法。

两个 Datadog 摄取主机仅携带可选的操作遥测，设置 CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC 会禁用两者。第三方提供商上的会话永远不会发送到这些主机，即使平台设置了 CLAUDE_CODE_PROVIDER_MANAGED_BY_HOST 且遥测指标默认启用。有关 Claude Code 发送的所有内容以及如何在最终确定白名单之前禁用它，请参阅遥测服务。

使用 Amazon Bedrock、Google Cloud 的 Agent Platform、Microsoft Foundry 或已登录的 Claude 应用网关会话时，模型流量和身份验证转到您的提供商或网关，而不是 api.anthropic.com、claude.ai 或 platform.claude.com。WebFetch 工具仍会调用 api.anthropic.com 进行其域名安全检查，除非您在设置中设置 skipWebFetchPreflight: true。

通过带有 ANTHROPIC_BASE_URL 的 LLM 网关路由时，快速模式可用性检查仍会调用 api.anthropic.com 而不是网关基础 URL。检查确实遵守配置的 HTTP 代理，因此当网络阻止是原因时，代理中 api.anthropic.com 的白名单条目是修复。网络阻止仅在主机即使通过代理也无法访问时才会导致检查失败，快速模式随后会报告连接错误。当检查呈现网关颁发的凭证而 Anthropic 拒绝时，也会出现相同的连接错误；白名单在那里无法帮助，因为没有任何内容被阻止。有关恢复它的变量，请参阅在代理和 LLM 网关后面使用快速模式。

组织 IP 白名单和代理出口

如果您的组织为 Claude 启用了 IP 白名单，请通过与 claude.ai 和 api.anthropic.com 相同的代理出口路由 bridge.claudeusercontent.com，例如将其放在相同的 Zscaler 应用段或 Netskope 转向策略中。如果您无法以这种方式路由它，请将代理用于该主机的出口地址添加到您的组织的 IP 白名单中，但仅当该地址专用于您的组织时：共享代理出口范围也允许代理供应商的其他客户。

Anthropic 使用它们到达的地址检查与您的组织 IP 白名单的 bridge.claudeusercontent.com 连接。如果您的代理通过不在该白名单上的地址为该主机发送流量，Claude Code 无法连接到 Chrome 中的 Claude 扩展，即使 Claude Code 的其余部分有效。

GitHub 白名单和防火墙

Anthropic 托管环境中的 Web 上的 Claude Code 和 Code Review 从 Anthropic 管理的基础设施连接到您的存储库；自托管环境中的会话从您的网络内部连接，除非运行程序选择加入 Anthropic git 代理，该代理从 Anthropic 一侧获取。

如果您的 GitHub Enterprise Cloud 组织按 IP 地址限制访问，请启用已安装 GitHub App 的 IP 白名单继承，并且还要添加白名单条目以用于 Anthropic 的出站 IP 地址。继承仅涵盖 Claude GitHub App 作为安装进行的请求，不涵盖它代表您的用户进行的请求。对于其他防火墙，请参阅 Anthropic API IP 地址。

对于防火墙后的自托管 GitHub Enterprise Server 实例，白名单 Anthropic 的出站 IP 地址，以便 Anthropic 基础设施可以访问您的 GHES 主机来克隆存储库和发布审查评论。自托管环境中的会话从您的网络内部访问您的 GHES 主机，因此该暴露仅适用于 Anthropic 托管会话、托管的会话前流程（如存储库选择器）以及选择加入 Anthropic git 代理的自托管运行程序，该代理从 Anthropic 一侧获取。对于仅在您的网络内可路由的 GHES 主机，SCM 连接器通过出站连接而不是白名单来承载托管的会话前流程，因此不需要白名单。

Desktop 和 claude.ai

前面的表格涵盖了独立 CLI。Claude Desktop 应用和浏览器中的 claude.ai 从其他 Anthropic CDN 主机加载其应用代码和用户内容，包括 assets-proxy.anthropic.com 和其他在这些应用中提供 Artifact 的 *.claudeusercontent.com 源。允许 claude.ai 同时阻止这些主机会产生空白页面而不是错误。请参阅 Desktop 页面上的网络访问要求。

从 Google Fonts 加载字体的 Artifact 也会请求 fonts.googleapis.com 和 fonts.gstatic.com。两个主机都是可选的。如果您阻止它们，Artifact 会以备用字体呈现。使用快速拒绝而不是静默丢弃来阻止，以便字体请求立即失败，而不是延迟页面的首次呈现。

Artifact 还可以从 cdnjs.cloudflare.com、cdn.jsdelivr.net、cdn.tailwindcss.com、code.jquery.com 和 unpkg.com 加载 JavaScript 库（如 React 或图表包），而不能从其他外部主机加载。如果您阻止这些主机，Artifact 中依赖库的部分将无法工作，与阻止的字体不同，阻止的库没有备用。也在这里使用快速拒绝，以便阻止的库请求立即失败，而不是挂起直到超时。

其他资源

• 设置文件和优先级
• 环境变量参考
• 故障排除指南