教程

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 配置完全指南: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 MCP 完整使用指南:安装配置主流 MCP 服务器扩展 AI 能力Claude Code MCP(Model Context Protocol)完整使用指南:MCP 是什么(AI 工具扩展标准)、claude mcp 命令管理服务器(add/remove/list)、主流 MCP 服务器安装配置(文件系统/GitHub/PostgreSQL/Brave Search/Slack)、本地 stdio 与远程 SSE 两种连接方式、MCP 服务器安全配置、在 CLAUDE.md 中声明 MCP 工具使用规范,以及自定义 MCP 服务器的快速开发入门。2026/3/18教程Claude Code 输出格式控制完全指南:JSON、流式、结构化输出使用方法Claude Code 和 Claude API 输出格式完整控制指南:--output-format 参数(text/json/stream-json)、非交互模式(-p)的输出控制、结构化 JSON 输出(--json-schema 字段约束)、流式输出(Server-Sent Events)的处理方式、include-partial-messages 流式渐进显示、以及 CI/CD 管道中解析 JSON 输出的实用技巧。2026/3/18教程Claude Code 项目初始化最佳实践:新项目 5 分钟搭建完美 AI 编程环境Claude Code 新项目最佳初始化流程:CLAUDE.md 标准模板(项目背景/技术栈/代码规范/禁止操作)、.claudeignore 初始配置、.claude/commands/ 常用命令预置、settings.json 权限与模型设置、--init 命令的自动化初始化、项目级 vs 全局配置的优先级说明,以及不同类型项目(Web前端/后端API/全栈/开源库)的专项初始化模板。2026/3/18