Claude Code代理proxyHTTP_PROXY代理配置

Claude Code 代理配置完全教程 - 设置、地址、密钥、自建

Claude Code 代理怎么配置？本文详解 HTTP / HTTPS / SOCKS 代理设置方法、代理地址与密钥配置、自建代理方案与常见连接问题排查。

· 阅读约 16 分钟

Claude Code 代理 是国内用户绕不开的话题。无论是想让 Claude Code 走科学上网工具、还是企业内网必须走 HTTP 代理出网、又或者想自己搭一个 Claude Code 代理中转 给团队用，ClaudeCode 代理配置 都是第一步。本文把 Claude Code 代理怎么设置、Claude Code 代理地址和密钥配置、Claude Code 代理自建 三个核心问题一次说清楚，并给出 HTTP / HTTPS / SOCKS5 三种代理类型的完整配置示例。

需要先声明：本文不推荐任何具体的非官方中转服务商，所有方案都各有取舍，请结合自己的合规要求和数据敏感度自行判断。

Claude Code 代理是什么

Claude Code 代理 本质上是夹在 Claude Code 客户端和 Anthropic API 服务器之间的”中间转发”。请求路径从直连：

Claude Code → api.anthropic.com

变成走代理：

Claude Code → 代理服务器 → api.anthropic.com

这层”代理”可以是不同形态：

代理类型作用典型场景
HTTP / HTTPS 代理转发 HTTP/S 流量公司出网代理、科学上网客户端
SOCKS5 代理转发任意 TCP/UDPShadowsocks / V2Ray 本地端口
API 中转兼容 Anthropic 协议的 HTTP 端点把 base URL 换成中转地址
反向代理自建在海外的 nginx / Workers自己控制全链路

需要特别区分一组概念：网络层代理（HTTP_PROXY 那种）只是改了请求出口，API 中转（改 ANTHROPIC_BASE_URL）是把请求送到另一个服务。两者经常被混着叫”代理”，但配置位置完全不同。

为什么需要代理

Claude Code 代理 通常出于这几类原因：

  • 国内访问海外服务：Anthropic 对中国大陆 IP 拒绝服务，必须借代理改出口
  • 企业内网隔离：公司网络只允许走指定 HTTP 代理出网
  • 加速 / 稳定性：跨国直连不稳，找一条更优线路
  • 统一管控：团队共用一台中转，统一计费和审计
  • 自定义后端：把 Claude Code 接到自家模型或第三方模型，本质上也走代理协议

接下来按代理类型逐个看怎么配。

代理类型对照

类型协议端口（典型）Claude Code 是否原生支持
HTTP 代理HTTP CONNECT7890 / 8080是，HTTP_PROXY 环境变量
HTTPS 代理TLS 包裹的 HTTP7890 / 443是，HTTPS_PROXY 环境变量
SOCKS5TCP/UDP 转发1080 / 7891通过 ALL_PROXY 或客户端工具映射
系统代理OS 全局取决系统部分场景自动读取

90% 的国内用户只需要 HTTP_PROXY + HTTPS_PROXY 这两个变量。SOCKS5 是高阶玩家或开了 Shadowsocks 这类客户端的人才需要。

三种 Claude Code 代理配置方式

ClaudeCode 代理配置 有三种存放位置，作用范围从大到小：

方式作用范围适合场景
环境变量当前终端会话最常用、临时调试
settings.json当前用户全局长期固定配置
命令行参数单次调用临时切换

下面分别看。

方式 1：环境变量（最常用）

Claude Code 代理怎么设置 最简单的方法就是设置 HTTP_PROXY / HTTPS_PROXY。

macOS / Linux

# 常用：HTTP 代理监听 127.0.0.1:7890
export HTTP_PROXY=http://127.0.0.1:7890
export HTTPS_PROXY=http://127.0.0.1:7890
export NO_PROXY=localhost,127.0.0.1,.local

# 启动
claude

写进 ~/.bashrc 或 ~/.zshrc 永久生效：

echo 'export HTTPS_PROXY=http://127.0.0.1:7890' >> ~/.zshrc
echo 'export HTTP_PROXY=http://127.0.0.1:7890' >> ~/.zshrc
source ~/.zshrc

Windows PowerShell

$env:HTTP_PROXY = "http://127.0.0.1:7890"
$env:HTTPS_PROXY = "http://127.0.0.1:7890"
$env:NO_PROXY = "localhost,127.0.0.1"
claude

永久写入用户环境变量：

[Environment]::SetEnvironmentVariable("HTTPS_PROXY", "http://127.0.0.1:7890", "User")
[Environment]::SetEnvironmentVariable("HTTP_PROXY",  "http://127.0.0.1:7890", "User")

之后新开 PowerShell 自动带这两个变量。

NO_PROXY 是什么

NO_PROXY 列出不走代理的地址，逗号分隔。最少加上：

  • localhost
  • 127.0.0.1
  • 内网 IP 段（如 10.、192.168.）
  • 你的内网 DNS 后缀（如 .corp.example.com）

这样本地脚本调本地服务就不会被错误地推到代理上。

方式 2：settings.json 持久化

~/.claude/settings.json（Windows 为 %USERPROFILE%\.claude\settings.json）可以保存 env 变量给 Claude Code 启动时读取：

{
  "env": {
    "HTTPS_PROXY": "http://127.0.0.1:7890",
    "HTTP_PROXY": "http://127.0.0.1:7890",
    "NO_PROXY": "localhost,127.0.0.1"
  }
}

好处：

  • 不污染全局环境变量
  • 切机器只要复制这个文件
  • 团队共享配置时容易统一

也可以把 base URL 一起写进来，做成完整的 Claude Code 套餐代理 配置：

{
  "env": {
    "ANTHROPIC_BASE_URL": "https://your-relay.example.com",
    "ANTHROPIC_API_KEY": "sk-xxxxxx",
    "HTTPS_PROXY": "http://127.0.0.1:7890"
  }
}

方式 3：命令行参数

部分版本支持启动时直接传：

claude --proxy http://127.0.0.1:7890

具体参数名以 claude --help 输出为准。命令行参数适合临时切代理验证某条线路，不建议长期使用，因为忘了带就回到环境变量配置。

SOCKS5 代理配置

很多人本地装的是 Shadowsocks / V2Ray / Clash 等客户端，它们除了 HTTP 端口（常见 7890）也提供 SOCKS5 端口（常见 7891 / 1080）。

方法 A：让客户端同时提供 HTTP 端口

最简单：在你的 Clash / V2Ray 客户端里把 HTTP 端口和 SOCKS5 端口都打开，然后还是按 HTTP_PROXY 方式给 Claude Code 用。这是最省事的路。

方法 B：通过 ALL_PROXY 走 SOCKS5

export ALL_PROXY=socks5://127.0.0.1:7891
export HTTPS_PROXY=socks5://127.0.0.1:7891

注意：Node.js 原生 https 模块对 SOCKS5 支持依赖第三方实现，部分组合下不一定生效。最稳还是用方法 A。

方法 C：本地起一个 HTTP→SOCKS5 桥

用 privoxy 或 polipo 这类工具，本地把 HTTP 代理转发到 SOCKS5：

本地 8118 (HTTP) → privoxy → 127.0.0.1:7891 (SOCKS5)

然后 Claude Code 走 HTTPS_PROXY=http://127.0.0.1:8118 即可。

Claude Code 代理地址和密钥配置

Claude Code 代理地址和密钥配置 这个组合常见于”带认证的代理”或”API 中转”两种场景。

场景一：带认证的 HTTP 代理

公司或部分商用代理需要用户名密码：

export HTTPS_PROXY=http://user:password@proxy.corp.com:8080

格式：http://用户名:密码@主机:端口。

如果密码里含特殊字符（@、:、/），要做 URL encode：

原密码：a@b
编码后：a%40b

场景二：API 中转的 base URL + key

API 中转其实和”网络代理”是两层概念，但用户经常一起配。完整模板：

export ANTHROPIC_BASE_URL="https://relay.example.com"
export ANTHROPIC_API_KEY="sk-relay-xxxxxx"
# 如果中转地址在你本地，还可能要排除代理
export NO_PROXY="$NO_PROXY,relay.example.com"

Claude Code 代理中转 中”key” 是中转商给你的访问凭据，跟 Anthropic 原生的 sk-ant- 格式不一定相同。

自建 Claude Code 代理服务器

Claude Code 代理自建 是想长期稳定、不依赖第三方的最佳选择。常见三条路：

方案难度成本优势
Cloudflare Workers低免费层很大几行代码，免运维
自家 VPS + nginx 反代中月几美元完全自主
Caddy / Traefik中同上自动 HTTPS、配置简洁

Cloudflare Workers 最小示例

Cloudflare Workers 跑一个反代到 api.anthropic.com 大概是这样（伪代码，具体语法以 Cloudflare 官方文档为准）：

export default {
  async fetch(request) {
    const url = new URL(request.url);
    url.hostname = "api.anthropic.com";
    url.protocol = "https:";
    url.port = "";

    const newRequest = new Request(url, request);
    return fetch(newRequest);
  }
};

部署后你会拿到一个 your-name.workers.dev 域名。然后给 Claude Code：

export ANTHROPIC_BASE_URL="https://your-name.workers.dev"
export ANTHROPIC_API_KEY="sk-ant-你的真key"
claude

注意 Workers 的免费额度有调用次数限制，重度使用要升级套餐。

nginx 反向代理

如果你有海外 VPS，nginx 配置示意：

server {
    listen 443 ssl;
    server_name relay.example.com;

    location / {
        proxy_pass https://api.anthropic.com;
        proxy_set_header Host api.anthropic.com;
        proxy_ssl_server_name on;
    }
}

加 TLS 证书可以用 certbot。完整配置要额外处理 SNI、超时、SSE 流式输出（关键：proxy_buffering off;）。

“代理资格” 是什么

Claude Code 代理资格 这个词通常指 Anthropic 的合作伙伴 / 经销商资格（reseller / partner），不是普通用户能拿到的。

普通用户不需要任何”资格”就能用代理，只是个网络问题。如果你看到某些渠道说有”官方代理资格”，更多是营销话术，真正的 Anthropic 合作渠道在 anthropic.com 上有公开列表，可以核对。

模型中转商怎么接入 Claude

模型中转商怎么接入 Claude 的 原理其实不复杂，本质是 base URL + API key 双重重定向：

你的客户端（Claude Code）
   ↓ 设置 ANTHROPIC_BASE_URL=中转方域名
中转方服务器
   ↓ 用自己持有的 Anthropic API key
Anthropic 官方 API

中转方做的事：

  1. 接收符合 Anthropic 协议的请求
  2. 把 x-api-key 换成自家持有的真 key
  3. 转发到 api.anthropic.com
  4. 把响应（包括流式 SSE）原样回传
  5. 按用量给上游客户出账

中转方需要解决的工程问题：

  • 流式 SSE 转发不能 buffer
  • 多账号轮询、被封自动切换
  • 用量计费、速率限制
  • 客户 prompt 不能落日志（合规承诺）

理解了这个原理，你看任何 “Claude Code 代理服务器选择” 都能心里有数：稳定性、跑路风险、数据安全、价格、速率限制，每一项都对应到中转方的工程能力和商业模式。

常见连接错误

下面是配 Claude Code 代理 时最常见的报错。

ECONNREFUSED 127.0.0.1:7890

代理客户端没启动，或者端口不对。先用 curl 验证：

curl -x http://127.0.0.1:7890 https://www.google.com

返回 200 / 301 就是代理通的，401 就要看认证，连不上就先去检查 Clash / V2Ray 客户端是不是在跑。

HTTP/1.1 407 Proxy Authentication Required

代理要认证。在 URL 里带上 user:password：

export HTTPS_PROXY=http://user:pass@proxy.corp.com:8080

SSL handshake failed / unable to verify the first certificate

中转方或代理用了自签名证书。临时绕开（仅调试）：

export NODE_TLS_REJECT_UNAUTHORIZED=0

生产不要这样做，正确做法是把对方的 CA 证书加进系统信任。

连得上但返回 403 unsupported region

代理走的是国内出口 IP。重新选海外节点，确保代理出口落在 Anthropic 支持的地区。

流式输出卡顿、半天才出一段

中间某一层做了 buffering。如果是自建 nginx，加上：

proxy_buffering off;
proxy_cache off;
proxy_read_timeout 600s;

Cloudflare Workers 默认对 SSE 友好，不用特别处理。

Windows 设置了代理但好像不生效

PowerShell 的 $env: 只在当前会话生效。如果你在一个会话里设置完，新开终端不会有。永久写入要用 [Environment]::SetEnvironmentVariable(...) 或者 GUI 设置环境变量。

测试代理是否生效

最直接的方式是用 curl 同时测网络层和 API 层：

# 1. 网络通不通
curl -x $HTTPS_PROXY https://api.anthropic.com -I

# 2. API key 对不对
curl https://api.anthropic.com/v1/messages \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{"model":"claude-3-5-sonnet-20241022","max_tokens":50,"messages":[{"role":"user","content":"hi"}]}'

第一条 200 / 4xx 都算”通”，连不上就是代理本身的问题。第二条要看是否返回 JSON 内容。

Claude Code 也支持 verbose 模式查看实际请求路径：

claude --verbose

具体参数以 claude --help 为准。

FAQ

Q：不同代理用不同模型行吗？ 行。可以维护多份 settings.json，每个 profile 对应一组 base URL + API key + 代理，用 shell 别名快速切换。

Q：企业内网代理怎么走？ 通常公司出网代理是 proxy.corp.com:8080 这种。把它写进 HTTPS_PROXY，再加上 NO_PROXY 排除内网地址。如果还要走 API 中转，注意 NO_PROXY 要排除中转的内网域名，否则会”代理套代理”。

Q：订阅模式（Pro / Max）能用代理吗？ 能。Pro / Max 的 Claude Code 登录走的是 anthropic.com 的 OAuth，配好 HTTPS_PROXY 让 OAuth 流程能通就行。

Q：API 中转和网络代理能同时用吗？ 能。常见组合：客户端走科学上网代理 → 到达海外中转 → 中转方调 Anthropic。这种情况要确认 NO_PROXY 没把中转域名排除掉，否则代理被绕过了。

Q：代理会拖慢响应吗？ 正常情况延迟增加 50–300ms，不显著。如果代理在亚洲且 Anthropic 数据中心在北美，多绕一圈延迟可能到 500ms+。

Q：能让 Claude Code 自动选最快的代理吗？ 原生不支持。可以用 mihomo / Clash 这类客户端做规则分流，让 Claude Code 走的域名自动落到最快节点。

Q：自建代理被 Anthropic 检测会被封吗？ 个人合理使用一般不会。但是把一个账号架在中转后面给几百人共用，会很快被识别为滥用，账号会被风控。

小结

Claude Code 代理配置 的核心就三件事：

  1. 决定代理类型 —— 网络层（HTTP_PROXY）还是 API 层（ANTHROPIC_BASE_URL），或者两个一起
  2. 决定配置位置 —— 环境变量、settings.json、命令行参数，至少选一个
  3. 决定是用第三方还是自建 —— 看预算、合规、稳定性需求

最稳的入门组合：HTTPS_PROXY 走稳定的国际代理 + Anthropic 自家 API key。最折腾但最自主：Cloudflare Workers 反代 + 自家 key + 团队共享。Claude Code 代理 没有”最优解”，只有”最适合你当前场景”的解法。

具体定价、地区可用性、合规条款，以 Anthropic 官方为准。