Claude Code 国内配置完全指南：环境变量、自定义端点与高频踩坑排错

用了大半年 Claude Code，踩过的坑比写过的代码还多。最让人崩溃的不是 AI 写得不好，而是你刚进入状态，它就断了。

bash 复制代码

Error: 502 Bad Gateway
Connection timeout. Retrying...

如果你也遇到过这些，这篇文章把安装、配置、自定义端点、高频踩坑一次性讲清楚。

Claude Code 是什么

Claude Code 是 Anthropic 官方推出的终端 AI 编程工具，运行在终端/VS Code/JetBrains 中。它的工作方式是通过 HTTP 直接调用 Anthropic API，而不是走网页。这意味着：

它能直接读写你的本地文件、执行命令、操作 Git
每次请求都是一条 HTTP 调用，长时间流式传输
对网络稳定性要求远高于网页版

安装

macOS / Linux / WSL2：

bash 复制代码

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

Windows PowerShell：

bash 复制代码

irm https://claude.ai/install.ps1 | iex

安装完成后验证：

bash 复制代码

claude --version

看到版本号就说明安装成功。

如果提示 command not found: claude，检查 ~/.local/bin 是否在 PATH 中。没有的话加上：export PATH="$HOME/.local/bin:$PATH"

配置自定义 API 端点

这是国内用户最关心的部分。Claude Code 支持通过环境变量自定义 API 地址和 Key。

设置环境变量

bash 复制代码

# 自定义 API 端点
export ANTHROPIC_BASE_URL="https://your-api-endpoint.com"

# API Key
export ANTHROPIC_API_KEY="sk-your-key"

# 禁用非必要流量检查（重要！见下文踩坑）
export CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1

写入 shell 配置文件永久生效：

bash 复制代码

# Zsh 用户
echo 'export ANTHROPIC_BASE_URL="https://your-api-endpoint.com"' >> ~/.zshrc
echo 'export ANTHROPIC_API_KEY="sk-your-key"' >> ~/.zshrc
echo 'export CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1' >> ~/.zshrc
source ~/.zshrc

也可以用 ~/.claude/settings.json 的 env 字段统一管理，效果一样。

指定模型

bash 复制代码

export ANTHROPIC_MODEL=claude-sonnet-4-6

或者在 Claude Code 运行时切换：

bash 复制代码

/model sonnet
/model opus

验证配置

bash 复制代码

claude
# 进入后输入 /status，查看当前模型和 API 端点

高频踩坑与排错

坑 1：启动报 ERR_BAD_REQUEST

现象：环境变量配好了，API 也能 curl 通，但 Claude Code 一启动就报 Failed to connect to api.anthropic.com: ERR_BAD_REQUEST。

原因：Claude Code 启动时会硬编码 请求 https://api.anthropic.com/api/hello 做连通性检查，跟你设的 ANTHROPIC_BASE_URL 完全无关。

解决：

bash 复制代码

# 1. 禁用非必要流量检查
export CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1

# 2. 手动将 key 指纹写入 approved 列表
# 获取 key 最后 20 个字符
echo -n "你的API_KEY" | tail -c 20

# 创建 ~/.claude/.config.json
cat > ~/.claude/.config.json << 'EOF'
{
  "customApiKeyResponses": {
    "approved": ["你的key最后20个字符"]
  }
}
EOF

这是一个鸡生蛋的问题：Claude Code 需要先 approved 你的 key 才能跳过连通性检查，但你没法通过正常流程去 approve。只能手动创建配置文件。

坑 2：settings.json 的 apiBaseUrl 字段无效

现象：在 ~/.claude/settings.json 里配置了 apiBaseUrl 和 apiKey，但 Claude Code 完全无视这些配置。

原因：Claude Code 不认 apiBaseUrl 这个字段。API 地址只能通过环境变量 ANTHROPIC_BASE_URL 设置。

错误配置（不生效）：

json 复制代码

{
  "apiBaseUrl": "https://your-endpoint.com",
  "apiKey": "sk-xxx"
}

正确做法：用环境变量，或者在 settings.json 的 env 字段里设置：

json 复制代码

{
  "env": {
    "ANTHROPIC_BASE_URL": "https://your-endpoint.com",
    "ANTHROPIC_API_KEY": "sk-xxx"
  }
}

坑 3：.bashrc 的 early return 导致环境变量丢失

现象：在 .bashrc 底部写了 export，交互式终端能用，但 VS Code 终端里环境变量消失。

原因：Ubuntu 默认的 .bashrc 开头有一段：

bash 复制代码

case $- in
    *i*) ;;
      *) return;;
esac

非交互式 shell 直接 return，后面的 export 都不会执行。

解决：把环境变量放到 early return 之前，同时写入 ~/.profile 保底。

坑 4：WSL2 终端不加载新的环境变量

现象：修改了 .bashrc 和 .profile，打开新终端环境变量还是旧的。

解决：在 Windows 端彻底关闭 WSL：

bash 复制代码

wsl --shutdown

然后重新打开终端。VS Code 也需要完全关闭重开。

坑 5：设置 BASE_URL 后仍连官方

排查清单：

确认用了 export（没有 export 子进程看不到）
确认 URL 末尾没有多余斜杠
确认设置了 CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1
确认 key 指纹已写入 approved 列表

总结

Claude Code 在国内使用的核心就两步：

设置 ANTHROPIC_BASE_URL 和 ANTHROPIC_API_KEY
设置 CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1 + approved key 指纹

搞定这两步，其他一切照旧。有问题欢迎评论区交流。