教程

Claude Code 企业网络配置:代理服务器、自定义 CA 证书与 mTLS 双向认证完整指南

Claude Code 企业网络配置完整指南:代理服务器配置(环境变量 HTTPS_PROXY/NO_PROXY + settings.json env 方式)、Basic 认证和 NTLM/Kerberos 替代方案、自定义 CA 证书(NODE_EXTRA_CA_CERTS,PEM 格式要求)、mTLS 双向认证三个环境变量(CLIENT_CERT/CLIENT_KEY/PASSPHRASE)、必须放通的三个域名(api.anthropic.com/claude.ai/platform.claude.com)、完整企业配置 JSON 示例,以及五大故障排查。

2026/3/64分钟 阅读ClaudeEagle

企业内网环境通常有代理服务器、自定义 CA 证书、mTLS 认证等安全要求。Claude Code 通过环境变量和 settings.json 配置文件完整支持这些场景。

代理服务器配置

环境变量方式

Claude Code 遵循标准代理环境变量:

bash
# 推荐: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 不支持 SOCKS 代理

settings.json 方式(推荐企业统一部署)

json
// ~/.claude/settings.json 或托管策略配置
{
  "env": {
    "HTTPS_PROXY": "https://proxy.example.com:8080",
    "NO_PROXY": "localhost,internal.company.com"
  }
}

所有环境变量都可以通过 settings.json 的 env 字段配置,适合 IT 统一管理。

代理认证

Basic 认证(用户名密码):

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

⚠️ 避免在脚本中硬编码密码。使用环境变量或安全凭证存储(如 1Password CLI、macOS Keychain)。

高级认证(NTLM、Kerberos):Claude Code 原生不支持这些协议。建议使用支持你认证方式的 LLM Gateway 服务(如 LiteLLM)作为中间层。

自定义 CA 证书

企业环境常使用自签名 CA 证书(通过内部 PKI 或代理进行 SSL 解密)。配置 Claude Code 信任自定义 CA:

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

在 settings.json 中配置:

json
{
  "env": {
    "NODE_EXTRA_CA_CERTS": "/etc/ssl/company/ca-bundle.pem"
  }
}

注意事项

  • 证书文件必须是 PEM 格式(.pem.crt
  • 如果企业有多个 CA,可以将所有 CA 证书合并到一个 PEM 文件中
  • 代理进行 SSL 拦截(MITM)时,需要将代理的 CA 证书添加到此配置

mTLS 双向认证

部分企业要求客户端证书认证(mTLS),Claude Code 通过以下环境变量支持:

bash
# 客户端证书(公钥)
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"

在 settings.json 中配置:

json
{
  "env": {
    "CLAUDE_CODE_CLIENT_CERT": "/etc/ssl/client/cert.pem",
    "CLAUDE_CODE_CLIENT_KEY": "/etc/ssl/client/key.pem"
  }
}

mTLS 适用场景

  • 通过企业 API 网关访问内部 Claude 服务
  • 需要设备身份验证的零信任网络架构(ZTNA)
  • 通过 LLM Gateway 路由并要求双向认证的场景

必须放通的网络地址

Claude Code 需要访问以下 URL,在防火墙和代理白名单中必须放行:

URL用途
api.anthropic.comClaude API 端点
claude.aiclaude.ai 账号认证
platform.claude.comAnthropic Console 账号认证

容器化或受限网络环境中尤其重要

  • Docker 容器中的 Claude Code 需要确保出站到这三个域名的连接不被拦截
  • 如果使用 Bedrock 或 Vertex AI,还需要放行对应云平台的 API 端点

完整企业配置示例

以下是一个典型企业内网配置,综合使用代理 + CA 证书 + 统一设置:

json
// 托管策略配置(/Library/Application Support/ClaudeCode/CLAUDE.md 同级的 settings.json)
{
  "env": {
    "HTTPS_PROXY": "https://proxy.corp.example.com:8080",
    "NO_PROXY": "localhost,127.0.0.1,.corp.example.com,169.254.169.254",
    "NODE_EXTRA_CA_CERTS": "/etc/ssl/corp/ca-bundle.pem",
    "CLAUDE_CODE_CLIENT_CERT": "/etc/ssl/corp/client.pem",
    "CLAUDE_CODE_CLIENT_KEY": "/etc/ssl/corp/client-key.pem"
  }
}

与 LLM Gateway 配合使用

企业通常通过 LLM Gateway(如 LiteLLM、Portkey)统一路由 AI 请求,优势:

  • 统一审计日志和费用追踪
  • 支持 NTLM/Kerberos 等复杂认证
  • 实现模型路由和负载均衡
  • 流量过滤和内容策略

Claude Code 配合 LLM Gateway 的配置参见:LLM Gateway 配置文档

故障排查

问题可能原因解决方案
SSL 证书错误未配置企业 CA设置 NODE_EXTRA_CA_CERTS
连接超时防火墙阻止确认 api.anthropic.com 在白名单
407 代理认证失败代理凭证错误检查 HTTPS_PROXY 中的用户名密码
mTLS 握手失败证书路径或格式错误确认 PEM 格式,检查文件权限
SOCKS 代理不工作不支持改用 HTTP/HTTPS 代理,或用 proxychains 包装

原文:Enterprise network configuration | 来源:Anthropic 官方文档

相关文章推荐

教程Claude Code 企业网络配置:代理服务器、自定义 CA 证书、mTLS 认证与防火墙白名单Claude Code 企业网络配置完整指南:代理服务器配置(HTTPS_PROXY/HTTP_PROXY/NO_PROXY 标准变量/不支持 SOCKS/Basic 认证/NTLM-Kerberos 通过 LLM Gateway/settings.json 持久化)、自定义 CA 证书(NODE_EXTRA_CA_CERTS/多 CA 合并 PEM/HTTPS 拦截代理场景)、mTLS 客户端证书(CLAUDE_CODE_CLIENT_CERT/KEY/PASSPHRASE/企业 managed-settings.json 统一部署)、防火墙白名单三大必需 URL(api.anthropic.com/claude.ai/platform.claude.com)及安装和 OTel 额外需求,以及 Docker/GitHub Actions 容器化配置示例和验证命令。2026/3/7教程Claude Code 企业级部署指南:团队管理、权限控制、SSO 集成、成本优化Claude Code 企业级部署完整指南:订阅计划选择、管理员控制台、Managed CLAUDE.md 统一配置、分级权限设计、SSO 集成、Token 成本管理和合规审计方案。2026/4/13教程Claude Code 配置完全指南:settings.json 四级作用域与权限管理Claude Code settings.json 四级作用域完整指南:Managed/User/Project/Local 配置范围与优先级规则、权限配置语法(allow/deny/Bash/Read/Write)、三大实际场景配置(个人开发/团队项目/企业安全)、敏感文件保护、环境变量注入与子代理参数配置。2026/3/14教程Claude Code LLM Gateway 配置指南:LiteLLM 统一端点、动态 API Key 与三大提供商直通Claude Code LLM Gateway 配置完整指南:Gateway 五大价值(集中认证/用量追踪/费用控制/审计日志/模型路由)、三种 API 格式兼容要求(Anthropic Messages/Bedrock/Vertex 的 Headers 透传规则)、LiteLLM 静态 API Key 和动态 Key(三步配置:脚本+apiKeyHelper+TTL)、四种端点配置(统一端点推荐/Claude 直通/Bedrock 直通/Vertex 直通)、自定义模型名称设置,以及企业完整配置示例。2026/3/6教程Claude Code Skills 进阶:动态上下文注入、路径限定激活和 Subagent 集成深度指南Claude Code Skills 三个高级特性深度指南:动态上下文注入(!! 命令预处理原理、内联和多行语法、实战健康检查 Skill 含 6 个命令块、安全注意事项);路径限定自动激活(TypeScript 严格模式/SQL 安全/React 组件三个实战示例);context: fork 在 Subagent 运行(适用场景判断、agent 类型选择);以及三种特性组合的完整 PR 审查 Skill 示例。2026/5/10教程Claude Code Skills 官方完整指南:从入门到高级模式的权威教程Claude Code Skills 官方文档完整中文整理:Skills vs CLAUDE.md 核心区别;目录结构;存储位置和优先级;实时变更检测和 Monorepo 自动发现;完整 Frontmatter 字段参考(20+字段);字符串替换(动态参数);内容类型(参考类 vs 任务类);调用控制表;Skill 内容生命周期(压缩保留机制);三个高级模式(动态注入/路径限定/Subagent运行);以及内置 Bundled Skills 和权限控制方法。2026/5/10