国内Claude code从零到一:本地安装Claude Code+自定义API接口全配置指南(附国内踩坑实录)
一、Claude Code 是什么?
Claude Code 是 Anthropic 官方推出的 AI 编程助手,可以直接在终端、VS Code、JetBrains 等 IDE 中使用。它能:
- 🧠 理解你的整个代码库,跨文件编辑
- 🛠 运行命令、创建 PR、自动修 bug
- 📁 读写文件,操作 Git
- 🔌 通过 MCP 连接外部工具(Jira、Slack 等)
简单理解:它是一个住在你终端里的 AI 程序员,给它一句话就能帮你干活。
二、环境要求
| 项目 | 要求 |
|---|---|
| 操作系统 | macOS / Linux / Windows(WSL2 或 Git Bash) |
| Node.js | 不强制要求(原生安装方式不依赖 Node) |
| 网络 | 能访问 claude.ai 或你的自定义 API 端点 |
| 账号 | Claude Pro/Max 订阅 或 Anthropic Console API Key |
三、安装 Claude Code
3.1 原生安装(推荐)
macOS / Linux / WSL2:
curl -fsSL https://claude.ai/install.sh | bash
Windows PowerShell:
irm https://claude.ai/install.ps1 | iex
AI写代码powershell
curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd
⚠️ Windows 用户需要先安装 Git for Windows。
安装完成后验证:
claude --version
看到版本号就说明安装成功 ✅
💡 原生安装会自动后台更新,不用手动升级。
3.2 Homebrew 安装(macOS/Linux 备选)
brew install --cask claude-code
注意:Homebrew 安装不会自动更新,需要定期
brew upgrade claude-code。
3.3 WinGet 安装(Windows 备选)
winget install Anthropic.ClaudeCode
四、首次登录
安装完后,进入你的项目目录,启动 Claude Code:
cd your-project
claude
首次运行会自动打开浏览器让你登录。支持以下方式:
| 登录方式 | 适用场景 |
|---|---|
| Claude Pro/Max 订阅 | 个人用户,直接用 claude.ai 账号登录 |
| Claude for Teams/Enterprise | 团队用户,用管理员邀请的账号 |
| Anthropic Console | API 按量付费用户 |
| 云服务商(Bedrock/Vertex/Foundry) | 企业部署,通过环境变量配置 |
💡 如果浏览器没自动打开,按
c键复制登录链接,手动粘贴到浏览器。
五、配置自定义 API 接口和 Key(重点!)
这是很多国内用户最关心的部分——如何让 Claude Code 使用自己的 API Key 或第三方代理接口。
5.1 使用 Anthropic 官方 API Key
如果你有 Anthropic Console 的 API Key:
export ANTHROPIC_API_KEY="sk-ant-xxxxxxxxxxxxx"
把它加到你的 shell 配置文件中永久生效:
# Bash 用户
echo 'export ANTHROPIC_API_KEY="sk-ant-xxxxxxxxxxxxx"' >> ~/.bashrc
source ~/.bashrc
# Zsh 用户
echo 'export ANTHROPIC_API_KEY="sk-ant-xxxxxxxxxxxxx"' >> ~/.zshrc
source ~/.zshrc
然后运行 claude,就会直接使用你的 API Key,不需要浏览器登录。
5.2 使用自定义 API 端点(第三方代理/中转)
很多国内用户无法直接访问 Anthropic API,需要使用代理服务。国内有相当多的平台,这里推荐使用 https://claude-code.com.cn,支持claude-haiku-4-5,claude-opus-4-5,claude-sonnet-4-5,claude-opus-4-6,claude-sonnet-4-6等模型,Claude Code 通过 ANTHROPIC_BASE_URL 环境变量支持自定义端点:
# 设置你的代理地址(替换为你的实际地址)
export ANTHROPIC_BASE_URL="https://claude-code.com.cn"
# 设置你的 API Key(代理服务商提供的 Key)
export ANTHROPIC_API_KEY="sk-your-proxy-key"
⚠️ 关键点:代理服务必须兼容 Anthropic Messages API 格式(
/v1/messages端点),并且要正确转发anthropic-beta和anthropic-version请求头。
永久配置:
# 加到 .bashrc 或 .zshrc
cat >> ~/.bashrc << 'EOF'
# Claude Code 自定义 API
export ANTHROPIC_BASE_URL="https://claude-code.com.cn"
export ANTHROPIC_API_KEY="sk-your-proxy-key"
EOF
source ~/.bashrc
5.3 使用 LiteLLM 代理(高级)
如果你部署了 LiteLLM 代理服务器来统一管理多个 AI 模型:
# LiteLLM 统一端点(推荐)
export ANTHROPIC_BASE_URL="https://your-litellm-server:4000"
export ANTHROPIC_AUTH_TOKEN="sk-litellm-your-key"
或者通过 Claude Code 的 settings.json 配置:
{
"env": {
"ANTHROPIC_BASE_URL": "https://your-litellm-server:4000",
"ANTHROPIC_AUTH_TOKEN": "sk-litellm-your-key"
}
}
settings.json 的位置:~/.claude/settings.json(全局生效)。
5.4 使用 Amazon Bedrock
export CLAUDE_CODE_USE_BEDROCK=1
export AWS_REGION=us-east-1
export AWS_ACCESS_KEY_ID="your-access-key"
export AWS_SECRET_ACCESS_KEY="your-secret-key"
通过 LLM Gateway 代理 Bedrock:
export CLAUDE_CODE_USE_BEDROCK=1
export ANTHROPIC_BEDROCK_BASE_URL="https://your-gateway.com/bedrock"
export CLAUDE_CODE_SKIP_BEDROCK_AUTH=1 # 如果网关处理了 AWS 认证
5.5 使用 Google Vertex AI
export CLAUDE_CODE_USE_VERTEX=1
export CLOUD_ML_REGION=us-east5
export ANTHROPIC_VERTEX_PROJECT_ID=your-project-id
通过 LLM Gateway 代理 Vertex:
export CLAUDE_CODE_USE_VERTEX=1
export ANTHROPIC_VERTEX_BASE_URL="https://your-gateway.com/vertex"
export CLAUDE_CODE_SKIP_VERTEX_AUTH=1
5.6 使用 Microsoft Azure Foundry
export CLAUDE_CODE_USE_FOUNDRY=1
export ANTHROPIC_FOUNDRY_RESOURCE=your-resource
export ANTHROPIC_FOUNDRY_API_KEY=your-api-key
5.7 自定义模型名称
Claude Code 默认使用最新的 Claude 模型。你可以通过环境变量指定具体模型:
# 指定默认使用的模型
export ANTHROPIC_MODEL=claude-sonnet-4-6
# 或者分别指定不同等级的模型
export ANTHROPIC_DEFAULT_OPUS_MODEL=claude-opus-4-6
export ANTHROPIC_DEFAULT_SONNET_MODEL=claude-sonnet-4-6
export ANTHROPIC_DEFAULT_HAIKU_MODEL=claude-haiku-3-5-20241022
也可以在运行时切换:
# 启动时指定
claude --model opus
# 运行中切换(在 Claude Code 内输入)
/model sonnet
可用的模型别名:
| 别名 | 说明 |
|---|---|
default |
根据账户类型自动选择 |
sonnet |
最新 Sonnet 模型,日常编码 |
opus |
最新 Opus 模型,复杂推理 |
haiku |
快速高效,简单任务 |
opusplan |
规划用 Opus,执行用 Sonnet |
5.8 通过 settings.json 统一管理配置
除了环境变量,你还可以通过 ~/.claude/settings.json 集中管理所有配置:
{
"env": {
"ANTHROPIC_BASE_URL": "https://claude-code.com.cn",
"ANTHROPIC_API_KEY": "sk-your-key",
"ANTHROPIC_MODEL": "claude-sonnet-4-6"
},
"model": "sonnet",
"permissions": {
"allow": [
"Bash(npm run *)",
"Bash(git *)"
]
}
}
配置的优先级(从高到低):
- Managed(组织管理配置,不可覆盖)
- 命令行参数(临时会话覆盖)
- Local(
.claude/settings.local.json,仅本项目本人) - Project(
.claude/settings.json,团队共享) - User(
~/.claude/settings.json,全局个人)
5.9 使用 apiKeyHelper 动态获取 Key
如果你的 Key 需要动态生成(比如从 Vault 获取),可以配置一个脚本:
{
"apiKeyHelper": "/path/to/your/get-key.sh"
}
脚本示例:
#!/bin/bash
# get-key.sh
# 从密钥管理工具获取 key
vault kv get -field=api_key secret/claude-code
默认每 5 分钟或遇到 401 错误时刷新。可以自定义刷新间隔:
export CLAUDE_CODE_API_KEY_HELPER_TTL_MS=3600000 # 1 小时
六、验证配置是否生效
启动 Claude Code 后,输入 /status 命令查看当前配置:
claude
# 进入后输入:
/status
会显示当前使用的模型、账户信息、API 端点等。确认一切正确 ✅
七、踩坑实录 & 避坑指南
以下踩坑记录来源于我们在 WSL2 环境下配置 Claude Code + 第三方 API 代理(ppinfra.com)的真实经历,加上社区常见问题整理。每一个都是血泪教训 😂
🕳️ 坑 1(亲历 · 致命):启动报 ERR_BAD_REQUEST,硬编码检查 api.anthropic.com
现象:环境变量配好了,API 也能 curl 通,但运行 claude 直接报 Failed to connect to api.anthropic.com: ERR_BAD_REQUEST 然后退出。
根本原因:Claude Code 启动时会硬编码请求 https://api.anthropic.com/api/hello 做连通性检查,跟你设的 ANTHROPIC_BASE_URL 完全无关。在中国大陆访问这个地址会返回错误,Claude Code 直接 process.exit(1) 退出了。
解决:需要两步配合:
① 禁用非必要流量检查:
export CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1
② 将你的 API Key 指纹写入 approved 列表:
这是最关键的一步。Claude Code 在交互模式下会检查第三方 API Key 是否被"批准",如果没有,它还是会尝试连 api.anthropic.com。
# 1. 获取你的 key 指纹(key 的最后 20 个字符)
echo -n "你的API_KEY" | tail -c 20
# 2. 手动创建 ~/.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 设置。settings.json 里的 env 字段可以设环境变量,但直接写 apiBaseUrl 是无效的。
错误配置(不生效):
{
"apiBaseUrl": "https://your-proxy.com",
"apiKey": "sk-xxx"
}
正确做法:用环境变量
export ANTHROPIC_BASE_URL="https://your-proxy.com"
export ANTHROPIC_API_KEY="sk-xxx"
或者在 settings.json 的 env 字段里设置:
{
"env": {
"ANTHROPIC_BASE_URL": "https://your-proxy.com",
"ANTHROPIC_API_KEY": "sk-xxx"
}
}
🕳️ 坑 3(亲历):.bashrc 的非交互式 early return 导致环境变量丢失
现象:在 .bashrc 底部写了 export ANTHROPIC_BASE_URL=...,交互式终端能用,但 VS Code 终端、login shell 或某些子进程里环境变量消失。
根本原因:Ubuntu 默认的 .bashrc 文件开头有这么一段:
# If not running interactively, don't do anything
case $- in
*i*) ;;
*) return;;
esac
非交互式 shell 直接 return 了,后面的所有 export 都不会执行! VS Code 启动 WSL 时用的就是非交互式 shell。
解决方案:把环境变量放到 early return 之前
# ~/.bashrc 文件开头(在 case $- 之前)
export ANTHROPIC_BASE_URL="https://your-proxy.com"
export ANTHROPIC_API_KEY="sk-xxx"
export CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1
# If not running interactively, don't do anything
case $- in
*i*) ;;
*) return;;
esac
# ... 后面是原来的内容
同时写入 ~/.profile(login shell 保底):
# 在 ~/.profile 末尾添加
export ANTHROPIC_BASE_URL="https://your-proxy.com"
export ANTHROPIC_API_KEY="sk-xxx"
export CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1
💡 验证环境变量在所有 shell 模式下都生效:
# 交互式 shell bash -ic 'echo $ANTHROPIC_BASE_URL' # 非交互式 shell bash -c 'echo $ANTHROPIC_BASE_URL' # Login shell bash -l -c 'echo $ANTHROPIC_BASE_URL'三个都要有输出才算搞定。
🕳️ 坑 4(亲历):WSL2 终端不加载新的环境变量
现象:修改了 .bashrc 和 .profile,但打开新终端环境变量还是没变。
原因:WSL2 的实例在后台持续运行,新终端窗口继承的是旧进程的环境。
解决:在 Windows 端彻底关闭 WSL 再重新打开:
# 在 Windows PowerShell 或 CMD 中运行
wsl --shutdown
然后重新打开终端。VS Code 也需要完全关闭重开。
或者临时解决:
source ~/.bashrc
claude
🕳️ 坑 5:安装后 command not found: claude
现象:安装脚本跑完了,但输入 claude 提示命令找不到。
原因:安装目录 ~/.local/bin 不在 PATH 中。
解决:
# 检查 PATH
echo $PATH | tr ':' '\n' | grep local/bin
# 如果没有输出,手动加入:
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc
# 验证
claude --version
💡 WSL2 用户特别注意:建议同时写到
.bashrc(交互式) 和.profile(login shell)。
🕳️ 坑 6:安装脚本返回 HTML 而不是脚本
现象:运行 curl ... | bash 报错 syntax error near unexpected token '<'。
原因:网络问题导致下载到了一个 HTML 错误页面(地区网络限制、公司防火墙拦截、CDN 临时故障)。
解决:
# 方法 1:用 Homebrew 代替
brew install --cask claude-code
# 方法 2:先下载脚本检查内容
curl -fsSL https://claude.ai/install.sh -o install.sh
cat install.sh # 确认是 shell 脚本而不是 HTML
bash install.sh
# 方法 3:配置代理后重试
export HTTPS_PROXY="http://your-proxy:port"
curl -fsSL https://claude.ai/install.sh | bash
🕳️ 坑 7:ANTHROPIC_BASE_URL 设置了但不生效
现象:明明设了环境变量,Claude Code 还是连接官方 API 或报错。
排查清单:
# 1. 确认变量已 export(没有 export 子进程看不到)
# ❌ ANTHROPIC_BASE_URL="https://xxx"
# ✅ export ANTHROPIC_BASE_URL="https://xxx"
# 2. 确认 URL 末尾没有多余斜杠
# ❌ export ANTHROPIC_BASE_URL="https://proxy.example.com/"
# ✅ export ANTHROPIC_BASE_URL="https://proxy.example.com"
# 3. 确认变量已生效
echo $ANTHROPIC_BASE_URL
echo $ANTHROPIC_API_KEY
🕳️ 坑 8:第三方代理报 400/403/500 错误
现象:设置了代理地址,API 调用报错。
原因:代理不完全兼容 Anthropic API 格式。
排查:
- ✅ 代理是否支持
/v1/messages端点? - ✅ 代理是否正确转发
anthropic-beta和anthropic-versionheader? - ✅ 代理是否支持 streaming(流式响应)?
- ✅ API Key 格式是否正确?
用 curl 测试代理:
curl -X POST "${ANTHROPIC_BASE_URL}/v1/messages" \
-H "Content-Type: application/json" \
-H "x-api-key: ${ANTHROPIC_API_KEY}" \
-H "anthropic-version: 2023-06-01" \
-d '{
"model": "claude-sonnet-4-20250514",
"max_tokens": 100,
"messages": [{"role": "user", "content": "Hi"}]
}'
curl 能返回正常结果 → 代理没问题,排查 Claude Code 配置。
🕳️ 坑 9:WSL2 环境下浏览器登录打不开
现象:Claude Code 提示打开浏览器登录,但 WSL2 里没有图形界面。
解决:
# 方法 1:按 c 复制 URL,手动粘贴到 Windows 浏览器
# 方法 2:配置 WSL 默认浏览器
export BROWSER="/mnt/c/Program Files/Google/Chrome/Application/chrome.exe"
# 方法 3(推荐):直接用 API Key 跳过浏览器登录
export ANTHROPIC_API_KEY="sk-xxxxxxxxxxxxx"
claude # 直接进入,不需要浏览器
🕳️ 坑 10:多个安装版本冲突
现象:版本不对、命令行为异常、各种奇怪问题。
原因:同时存在原生安装 + npm 全局安装 + Homebrew 安装。
解决:
# 查看所有 claude 的安装位置
which -a claude
# 只保留一个!推荐原生安装,删除其他:
npm uninstall -g @anthropic-ai/claude-code # 删 npm 版
brew uninstall --cask claude-code # 删 Homebrew 版
🕳️ 坑 11:Linux 低内存服务器安装被 Kill
现象:安装过程中突然被系统 Killed。
解决:
# 临时增加 swap 空间
sudo fallocate -l 2G /swapfile
sudo chmod 600 /swapfile
sudo mkswap /swapfile
sudo swapon /swapfile
# 然后重新安装
curl -fsSL https://claude.ai/install.sh | bash
🕳️ 坑 12:TLS/SSL 证书错误
现象:TLS connect error 或 unable to get local issuer certificate。
解决:
# 更新系统 CA 证书
sudo apt update && sudo apt install ca-certificates
# 或配置公司 CA 证书
export NODE_EXTRA_CA_CERTS="/path/to/corporate-ca.pem"
八、常用命令速查
终端命令
| 命令 | 用途 |
|---|---|
claude |
启动交互模式 |
claude --model opus |
指定模型启动 |
claude -p "你的任务" |
非交互模式(单次任务) |
claude --version |
查看版本 |
Claude Code 内部命令
| 命令 | 用途 |
|---|---|
/status |
查看当前状态(模型、账户、配置) |
/model |
切换模型 |
/logout |
登出当前账户 |
/config |
打开配置界面 |
/help |
查看帮助 |
环境变量速查
| 变量 | 说明 |
|---|---|
ANTHROPIC_API_KEY |
官方 API Key |
ANTHROPIC_BASE_URL |
自定义 API 端点 |
ANTHROPIC_AUTH_TOKEN |
认证 Token(覆盖 API Key) |
ANTHROPIC_MODEL |
默认模型 |
ANTHROPIC_DEFAULT_OPUS_MODEL |
Opus 别名指向的模型 |
ANTHROPIC_DEFAULT_SONNET_MODEL |
Sonnet 别名指向的模型 |
CLAUDE_CODE_USE_BEDROCK |
启用 Bedrock |
CLAUDE_CODE_USE_VERTEX |
启用 Vertex AI |
CLAUDE_CODE_USE_FOUNDRY |
启用 Azure Foundry |
HTTPS_PROXY |
HTTP 代理 |
九、完整配置示例
场景 1:国内用户通过代理使用
# ~/.bashrc 添加以下内容
export ANTHROPIC_BASE_URL="https://your-cn-proxy.com"
export ANTHROPIC_API_KEY="sk-your-proxy-key"
export ANTHROPIC_MODEL="claude-sonnet-4-6"
场景 2:企业用户通过 Bedrock
# ~/.bashrc 添加以下内容
export CLAUDE_CODE_USE_BEDROCK=1
export AWS_REGION=us-east-1
export AWS_PROFILE=your-aws-profile
export ANTHROPIC_DEFAULT_SONNET_MODEL="us.anthropic.claude-sonnet-4-6-v1:0"
场景 3:通过 LiteLLM 统一网关
# ~/.bashrc 添加以下内容
export ANTHROPIC_BASE_URL="https://litellm.internal.company.com:4000"
export ANTHROPIC_AUTH_TOKEN="sk-litellm-team-key"
写在最后
Claude Code 的安装本身不难,难的是配置自定义 API 接口这一步。核心记住:
ANTHROPIC_BASE_URL= 你的 API 地址ANTHROPIC_API_KEY= 你的密钥- 代理必须兼容 Anthropic Messages API(
/v1/messages) - 有问题先跑
/status看配置,再用curl测试接口
AtomGit 是由开放原子开源基金会联合 CSDN 等生态伙伴共同推出的新一代开源与人工智能协作平台。平台坚持“开放、中立、公益”的理念,把代码托管、模型共享、数据集托管、智能体开发体验和算力服务整合在一起,为开发者提供从开发、训练到部署的一站式体验。
更多推荐

所有评论(0)