概述

本教程面向身处企业内网、防火墙后或需要自建模型网关的零基础开发者，目标是用一条最小路径把 Claude Code 在受限网络里彻底跑通。学完你将掌握：原生安装的三种变体、代理与自签名证书（CA/mTLS）配置、经 LLM 网关或自定义端点接入模型、用 settings.json 四层作用域固化配置、以及验证首个项目能稳定调用模型。适用人群：金融/政企/制造业内网开发、需经 LiteLLM 等网关统一计费的团队、以及要把 Claude Code 接入私有部署模型的自建者。

前置条件

• 操作系统：macOS 13+、Windows 10 1809+（或 WSL 2）、Ubuntu 20.04+、Debian 10+、Alpine 3.19+
• 硬件：4 GB 以上内存，x64 或 ARM64
• Shell：Bash / Zsh / PowerShell / CMD
• 账号或密钥其一：Claude Pro/Max/Team/Enterprise 订阅、Console 预付费额度、第三方云（Bedrock / Vertex / Foundry），或一个 Anthropic 兼容的自建网关地址与令牌
• 网络：能访问本教程后面列出的域名白名单，或拥有一台可用的代理 / 网关

提示：免费 Claude.ai 计划不包含 Claude Code 访问权限，请先确认账号类型。

第一步：先搞清受限网络对 Claude Code 的三重影响

很多新手以为“装不上 = 安装脚本坏了”，其实在内网里，问题往往来自三个独立层面。把它们分开看，排错效率会高一个数量级：

1. 安装与自更新层：原生安装脚本要从 claude.ai 下载二进制，自动更新要从 downloads.claude.ai（2.1.116 之前还可能用 storage.googleapis.com）拉取。这些域名若没加白名单，安装或升级会静默失败。
2. 运行时模型调用层：默认所有推理请求都打到 api.anthropic.com。内网若只允许走代理或必须经统一网关，就需要改 ANTHROPIC_BASE_URL 与认证变量。
3. 辅助流量层：版本更新检查读 raw.githubusercontent.com 的更新日志、遥测上报、WebFetch 的域名安全预检仍会访问 api.anthropic.com。气隙环境里这些“非必要流量”会反复超时，拖慢会话。

理解这三层后，后续每一步都对应一层，配置思路会非常清晰。

第二步：安装 Claude Code（受限网络下的安装变体）

操作说明

受限网络下推荐原生安装（体积小、自带 ripgrep、支持后台自更新）。在能访问 claude.ai 的跳板机或开了白名单的机器上：

# macOS / Linux / WSL
curl -fsSL https://claude.ai/install.sh | bash

# Windows PowerShell
irm https://claude.ai/install.ps1 | iex

:: Windows CMD
curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd

辨识提示符：PS C:\ 是 PowerShell，C:\ 不带 PS 是 CMD。在 CMD 里报 'irm' is not recognized、在 PowerShell 里报 '&&' is not a valid statement separator，都是用错了终端。

如果你的机器完全无法直连 claude.ai，可走包管理器（需对应源可访问）：

# Homebrew（不自更新，需手动 brew upgrade）
brew install --cask claude-code      # 稳定通道
brew install --cask claude-code@latest  # 最新通道

# WinGet
winget install Anthropic.ClaudeCode

Linux 服务器可用 apt / dnf / apk（Debian / Fedora / RHEL / Alpine）。Alpine 等 musl 系发行版还需补依赖：

apk add libgcc libstdc++ ripgrep
# 并在 settings.json 里设置：
# { "env": { "USE_BUILTIN_RIPGREP": "0" } }

预期结果

claude --version
# claude-code/2.1.129 (或更高)

更彻底的健康检查：

claude doctor

claude doctor 会列出当前版本、最近一次自动更新结果、认证状态、配置文件路径等。受限网络下它常会提示“自动更新失败”，这在第二步是预期内的——我们后面用代理或关闭非必要流量解决。

常见问题与解决

第三步：配置企业代理与证书（解决“运行时连不上”）

这是内网最常见的一层。Claude Code 尊重标准代理变量，并把证书信任做成可配置。

3.1 HTTP/HTTPS 代理

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

# 代理若只支持 HTTP
export HTTP_PROXY=http://proxy.example.com:8080

# 排除不走代理的地址（空格或逗号分隔均可）
export NO_PROXY="localhost 192.168.1.1 example.com .example.com"
# 或排空所有：NO_PROXY="*"

需要基本认证时把账号密码写进 URL（注意别硬编码到脚本）：

export HTTPS_PROXY=http://username:[email protected]:8080

注意：Claude Code 不支持 SOCKS 代理。若代理是 NTLM/Kerberos 这类高级认证，建议改用支持该认证的 LLM 网关来转发。

3.2 自定义 CA 与 TLS 检测代理

默认情况下，Claude Code 同时信任自带的 Mozilla CA 集与操作系统证书库（CLAUDE_CODE_CERT_STORE 默认为 bundled,system）。因此 CrowdStrike Falcon、Zscaler 这类 TLS 检测代理，只要把它们的根证书装进 OS 信任库，就能免配置直接用。

若你的企业用自签 CA，直接指定证书文件：

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

要精确控制信任来源：

export CLAUDE_CODE_CERT_STORE=system   # 只信任 OS 证书库
export CLAUDE_CODE_CERT_STORE=bundled  # 只信任自带 Mozilla CA

3.3 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，不再出现 ETIMEDOUT / UNABLE_TO_VERIFY_LEAF_SIGNATURE / SELF_SIGNED_CERT_IN_CHAIN 等错误，能进入正常对话提示符。

常见问题与解决

第四步：经 LLM 网关或自定义端点接入模型（解决“走统一出口”）

很多企业不允许客户端直连 api.anthropic.com，而是要求统一经 LLM 网关（如 LiteLLM、Kong、内部反代）做认证、计费、审计和模型路由。这一步就是告诉 Claude Code“别找官方，去找网关”。

4.1 两个核心变量

# 把推理请求改指到网关 / 自建端点
export ANTHROPIC_BASE_URL=https://litellm-server:4000

# 网关签发的令牌（会作为 Authorization: Bearer <value> 发送）
export ANTHROPIC_AUTH_TOKEN=sk-litellm-static-key

如果你拿的是标准 Anthropic API Key（作为 X-Api-Key 头发送）：

export ANTHROPIC_API_KEY=sk-ant-xxxxx

关键语义：ANTHROPIC_API_KEY 一旦设置，即使在交互模式也会覆盖你的订阅（首次会弹窗让你确认）；想用回订阅就 unset ANTHROPIC_API_KEY。在 -p 非交互模式下，该 Key 只要存在就一律使用。

4.2 网关必须满足的格式与头转发要求

不是任何反代都能用。网关至少暴露下列三种格式之一，并正确转发关键头：

Claude Code 还会在请求里带上三个网关可利用的头：

• X-Claude-Code-Session-Id：当前会话唯一 ID，便于按会话聚合计费
• X-Claude-Code-Agent-Id：发起请求的子 agent / teammate ID（仅子 agent 发出时存在）
• X-Claude-Code-Parent-Agent-Id：派生该 agent 的父 agent ID（嵌套场景按层级归因）

网关若按完整请求体自建 prompt 缓存，可设 CLAUDE_CODE_ATTRIBUTION_HEADER=0 去掉 Claude Code 注入到系统提示里的归因块（官方 API 会先剥离该块，不影响官方侧缓存命中）。

4.3 让 /model 选择器自动发现网关上的模型

当 ANTHROPIC_BASE_URL 指向 Anthropic Messages 格式的网关时，可让 Claude Code 在启动时查询 /v1/models，把网关返回的模型填进 /model 选择器（需 v2.1.129+）：

export CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY=1

该发现默认关闭，因为共享 Key 的网关不应把 Key 能访问的所有模型暴露给每个用户；只有 ID 以 claude 或 anthropic 开头的模型才会进入选择器，结果缓存到 ~/.claude/cache/gateway-models.json，每次启动刷新。

如果你的网关模型名不符合发现过滤规则，用模型配置环境变量手动添加即可。

4.4 LiteLLM 实战要点

统一端点（推荐，支持负载均衡、回退、统一计费与终端用户追踪）：

export ANTHROPIC_BASE_URL=https://litellm-server:4000

需要轮换 Key 或按用户发令牌时，用 apiKeyHelper 指向一个脚本（脚本输出会同时作为 Authorization 与 X-Api-Key 发送），并用 CLAUDE_CODE_API_KEY_HELPER_TTL_MS 控制刷新间隔：

{
  "apiKeyHelper": "~/bin/get-litellm-key.sh",
  "env": { "CLAUDE_CODE_API_KEY_HELPER_TTL_MS": "3600000" }
}

⚠️ 安全警告：LiteLLM PyPI 的 1.82.7 与 1.82.8 版本曾被植入窃取凭证的恶意代码，切勿安装这两个版本；已装的需卸载、轮换受影响系统上的全部凭证，并按 BerriAI 官方 issue 24518 处置。LiteLLM 是第三方项目，Anthropic 不对其安全或功能做背书。

经 LiteLLM 走 Bedrock / Vertex 透传端点时，还要配合：

# Bedrock 透传
export ANTHROPIC_BEDROCK_BASE_URL=https://litellm-server:4000/bedrock
export CLAUDE_CODE_USE_BEDROCK=1
export CLAUDE_CODE_SKIP_BEDROCK_AUTH=1

# Vertex 透传
export ANTHROPIC_VERTEX_BASE_URL=https://litellm-server:4000/vertex_ai/v1
export ANTHROPIC_VERTEX_PROJECT_ID=your-gcp-project-id
export CLAUDE_CODE_USE_VERTEX=1
export CLAUDE_CODE_SKIP_VERTEX_AUTH=1
export CLOUD_ML_REGION=us-east5

常见问题与解决

第五步：用 settings.json 四层作用域固化配置（解决“每次都要 export”）

环境变量散落在 shell 里既难维护，又容易泄漏到团队。Claude Code 提供四层作用域，推荐把网关/证书/代理类配置写进对应层：

把第三、四步的变量收进 User 层，一套配置全项目生效：

{
  "env": {
    "ANTHROPIC_BASE_URL": "https://litellm-server:4000",
    "ANTHROPIC_AUTH_TOKEN": "sk-litellm-static-key",
    "HTTPS_PROXY": "https://proxy.example.com:8080",
    "NODE_EXTRA_CA_CERTS": "/etc/ssl/certs/enterprise-ca.pem",
    "CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY": "1"
  },
  "apiKeyHelper": "~/bin/get-litellm-key.sh"
}

优先级铁律：环境变量 > settings 字段。例如 ANTHROPIC_MODEL 会覆盖 model 设置；会话内 /model、--model 又会覆盖 ANTHROPIC_MODEL。排查“配置没生效”时，先看是否有更高优先级的来源盖住了它。

CLAUDE_CODE_CERT_STORE 没有 settings 专用键，只能放进 env 块或进程环境变量里。

第六步：关闭非必要流量，跑通首个项目闭环

6.1 关掉气隙里会持续超时的后台流量

CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC 一键等效关闭自动更新、反馈命令、错误上报、遥测四项，是气隙环境的“省心开关”：

export CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1
# 等价于同时设：
# DISABLE_AUTOUPDATER、DISABLE_FEEDBACK_COMMAND、
# DISABLE_ERROR_REPORTING、DISABLE_TELEMETRY

单独关遥测也可：DISABLE_TELEMETRY=1 或跨工具通用的 DO_NOT_TRACK=1。

6.2 域名白名单清单

确权网络组把下列域名放行（容器化与受限网尤其重要）：

走 Bedrock/Vertex/Foundry 时，模型流量与认证走你的云商，而非 api.anthropic.com。但 WebFetch 仍会调 api.anthropic.com 做域名安全预检——除非在 settings 里设 skipWebFetchPreflight: true。

6.3 登录与首个会话

cd /path/to/your/project
claude          # 首次会提示登录

• 订阅/Console 账号：按提示在浏览器完成认证；会话内用 /login 切换或重登。
• 纯网关/API Key 模式：凭据来自环境变量，无需 /login；可设 DISABLE_LOGIN_COMMAND=1 隐藏登录命令。

进入会话后试一句“这个项目是做什么的？”验证模型链路是否真的通：

what does this project do?

能看到模型分析结果，说明第三到五步的代理/证书/网关链路全部打通。

实战案例：在 Zscaler + LiteLLM 网关的内网里跑通首个项目

场景：公司用 Zscaler 做 TLS 检测出口，所有 AI 调用必须经内网 LiteLLM 网关（https://llmgw.corp:4000）统一计费，且禁止直连 api.anthropic.com。目标是在这种环境里装好 Claude Code，并让它在一个全新的 Node 小工具项目里生成首个可运行功能。

步骤 1 —— 装机与系统信任库

Zscaler 的根证书已由 IT 推送到系统信任库，所以无需额外配 CA。在跳板机：

curl -fsSL https://claude.ai/install.sh | bash
claude --version

步骤 2 —— 写 User 层 settings.json

编辑 ~/.claude/settings.json：

{
  "env": {
    "ANTHROPIC_BASE_URL": "https://llmgw.corp:4000",
    "ANTHROPIC_AUTH_TOKEN": "sk-corp-team-alpha",
    "CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY": "1",
    "CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC": "1",
    "CLAUDE_CODE_ENABLE_FINE_GRAINED_TOOL_STREAMING": "1"
  }
}

• 不用 ANTHROPIC_API_KEY，因为网关用自家令牌（走 Authorization: Bearer）。
• 关掉非必要流量，避免会话里反复触发对 api.anthropic.com / raw.githubusercontent.com 的预检而超时。
• 网关发现模型，让 /model 列出公司放行的型号。

步骤 3 —— 冒烟测试网关链路

新建项目目录并启动：

mkdir jq-pretty && cd jq-pretty
npm init -y
claude

在会话里：

/model

选择器里应出现标注 “From gateway” 的模型（证明 /v1/models 发现成功）。随后发一句：

请用 Node 写一个把 JSON 文件格式化输出的小 CLI，入口 index.js，参数为文件路径

预期结果：Claude Code 经网关完成推理，生成 index.js、写文件、用 Bash 工具跑 node index.js sample.json 验证。看到格式化输出即证明整条“Zscaler → LiteLLM → 模型 → 本地执行”链路闭环。

# 项目根目录下生成本仓库记忆（可选，便于后续会话）
# 在会话内输入： /init

/init 会扫描项目并生成 CLAUDE.md，让后续会话快速理解项目结构。

步骤 4 —— 归因与审计核对

请网关侧在日志里核对：同一会话的所有请求应共享同一个 X-Claude-Code-Session-Id；若你让 Claude 起了子 agent（如并行代码评审），子请求会带 X-Claude-Code-Agent-Id 与 X-Claude-Code-Parent-Agent-Id，便于按 agent 归因计费。

完成判据：① claude doctor 无报错；② /model 能列出网关模型；③ 能生成代码并在本地跑出结果；④ 网关侧能看到带正确会话/agent 头的请求。四条全绿，受限网络部署即告成功。

整体工作流程图

flowchart TD
    A[内网/受限网络环境] --> B{安装层}
    B -->|放行 claude.ai / downloads.claude.ai| C[原生安装: curl install.sh]
    B -->|完全气隙| D[包管理器: brew/winget/apt]
    C --> E[claude --version / claude doctor]
    D --> E
    E --> F{运行时连不上?}
    F -->|需代理/证书| G[配置 HTTPS_PROXY / NODE_EXTRA_CA_CERTS / mTLS]
    F -->|需统一出口| H[配 ANTHROPIC_BASE_URL + AUTH_TOKEN 走 LLM 网关]
    G --> I
    H --> I[写入 settings.json 四层作用域]
    I --> J[关非必要流量 + 放行域名白名单]
    J --> K[claude 启动 /login 或用 Key]
    K --> L[/model 选择网关模型]
    L --> M[首个项目: 生成代码并本地验证]
    M --> N[网关侧核对 Session/Agent 头归因]
    N --> O((闭环成功))

常见排错速查表

延伸阅读

• Claude Code 官方文档 · 企业网络配置（代理 / CA / mTLS / 域名白名单）：https://code.claude.com/docs/en/network-config
• Claude Code 官方文档 · LLM 网关配置（LiteLLM / 模型发现 / 头转发）：https://code.claude.com/docs/en/llm-gateway
• Claude Code 官方文档 · 高级安装与系统要求：https://code.claude.com/docs/en/setup
• Claude Code 官方文档 · settings 四层作用域与可用字段：https://code.claude.com/docs/en/settings
• Claude Code 官方文档 · 环境变量参考表：https://code.claude.com/docs/en/env-vars

训练营适用性评估

• 适用类型：企业内训、金融/政企/制造业入职工程训练营、私有化部署与运维专题营、“国产模型 + 自建网关”技术营。
• 前置衔接：可作为“Claude Code 入门”系列的网络与企业化部署模块，承接通用安装教程，为后续 MCP / Skill / Hooks 进阶营铺好可用环境。
• 预计教学时长：讲授 45 分钟 + 动手实验 60 分钟（含 Zscaler/LiteLLM 联调与排错）；零基础学员可放宽到 3 小时含答疑。
• 难度评估：★★★☆☆（命令不难，难在“网络三层”概念梳理与团队网关联调，建议讲师准备一台带代理/自签证书的演示机）。
• 考核建议：以“四条完成判据”（doctor 无报错 / /model 列出网关模型 / 生成并跑通代码 / 网关侧看到正确归因头）作为通关标准。

参考来源

1. Enterprise network configuration — Claude Code Docs — 官方代理、自定义 CA、mTLS、域名白名单权威说明
2. LLM gateway configuration — Claude Code Docs — 网关格式要求、请求头、模型发现与 LiteLLM 实战
3. Advanced setup — Claude Code Docs — 系统要求、各平台安装方式、自动更新与卸载
4. Quickstart — Claude Code Docs — 安装、登录、首个会话与首次提问的标准流程
5. Environment variables reference — Claude Code Docs — ANTHROPIC_BASE_URL / ANTHROPIC_AUTH_TOKEN / 优先级等变量语义表

[!tip] 51学通信知识星球 星主：爱卫生（微信：gprshome201101）——公众号「51学通信」创办者，19 年通信行业运维与讲师经验，著有《GPRS网络信令实例详解》《EPC原理与实践》《5G核心网原理与实践》三本纸质书（各大电商平台有售）。 星球定位：深耕 5G 核心网、IMS、NFV/AI、云原生等 ICT 领域，主打运维岗位与信令分析。 当前规模：5200 篇主题 / 990 个回答，198 元/年。 加入福利：加入星球后请加爱卫生微信，拉您进知识星球年度陪伴与答疑群——不限量回复您的各种问题，另有群内分享。 AI 加持：51学通信知识星球已作为 skill 接入 WorkBuddy，使用 deepseek-4-flash 在海量星球帖子中精准找贴、找视频、找 FAQ 和案例，做总结、找文档和 PPT 等场景全覆盖。