本地安装Claude Code+自定义API接口的全配置指南

目录

• 一、Claude Code 是什么？
• 二、环境要求
• 三、安装 Claude Code
• 3.1 原生安装（推荐）
• 3.2 Homebrew 安装（macOS/Linux 备选）
• 3.3 WinGet 安装（Windows 备选）
• 四、首次登录
• 五、配置自定义 API 接口和 Key（重点！）
• 5.1 使用 Anthropic 官方 API Key
• 5.2 使用自定义 API 端点（第三方代理/中转）
• 5.3 使用 LiteLLM 代理（高级）
• 5.4 使用 Amazon Bedrock
• 5.5 使用 Google Vertex AI
• 5.6 使用 Microsoft Azure Foundry
• 5.7 自定义模型名称
• 5.8 通过 settings.json 统一管理配置
• 5.9 使用 apiKeyHelper 动态获取 Key
• 六、验证配置是否生效
• 七、踩坑实录 & 避坑指南
• 坑 1（亲历 · 致命）：启动报ERR_BAD_REQUEST，硬编码检查 api.anthropic.com
• 坑 2（亲历）：settings.json里的apiBaseUrl字段无效
• 坑 3（亲历）：.bashrc 的非交互式 early return 导致环境变量丢失
• 坑 4（亲历）：WSL2 终端不加载新的环境变量
• 坑 5：安装后command not found: claude
• 坑 6：安装脚本返回 HTML 而不是脚本
• 坑 7：ANTHROPIC_BASE_URL设置了但不生效
• 坑 8：第三方代理报 400/403/500 错误
• 坑 9：WSL2 环境下浏览器登录打不开
• 坑 10：多个安装版本冲突
• 坑 11：Linux 低内存服务器安装被 Kill
• 坑 12：TLS/SSL 证书错误
• 八、常用命令速查
• 终端命令
• Claude Code 内部命令
• 环境变量速查
• 九、完整配置示例
• 场景 1：国内用户通过代理使用
• 场景 2：企业用户通过 Bedrock
• 场景 3：通过 LiteLLM 统一网关
• 写在最后

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

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 

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

原生安装会自动后台更新，不用手动升级。

brew install --cask claude-code 

注意：Homebrew 安装不会自动更新，需要定期 brew upgrade claude-code。

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 键复制登录链接，手动粘贴到浏览器。

这是很多国内用户最关心的部分——如何让 Claude Code 使用自己的 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，不需要浏览器登录。

很多国内用户无法直接访问 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

如果你部署了 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（全局生效）。

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 认证

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

export CLAUDE_CODE_USE_FOUNDRY=1
export ANTHROPIC_FOUNDRY_RESOURCE=your-resource
export ANTHROPIC_FOUNDRY_API_KEY=your-api-key

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

除了环境变量，你还可以通过 ~/.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 *)"
    ]
  }
}

配置的优先级（从高到低）：

1. Managed（组织管理配置，不可覆盖）
2. 命令行参数（临时会话覆盖）
3. Local（.claude/settings.local.json，仅本项目本人）
4. Project（.claude/settings.json，团队共享）
5. User（~/.claude/settings.json，全局个人）

如果你的 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）的真实经历，加上社区常见问题整理。每一个都是血泪教训 😂

现象：环境变量配好了，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（因为启动检查就失败了）。只能手动创建配置文件。

现象：在 ~/.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"
  }
}

现象：在 .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'

三个都要有输出才算搞定。

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

原因：WSL2 的实例在后台持续运行，新终端窗口继承的是旧进程的环境。

解决：在 Windows 端彻底关闭 WSL 再重新打开：

# 在 Windows PowerShell 或 CMD 中运行 wsl --shutdown 

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

或者临时解决：

source ~/.bashrc
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）。

现象：运行 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

现象：明明设了环境变量，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

现象：设置了代理地址，API 调用报错。

原因：代理不完全兼容 Anthropic API 格式。

排查：

• ✅ 代理是否支持 /v1/messages 端点？
• ✅ 代理是否正确转发 anthropic-beta 和 anthropic-version header？
• ✅ 代理是否支持 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 配置。

现象：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  # 直接进入，不需要浏览器

现象：版本不对、命令行为异常、各种奇怪问题。

原因：同时存在原生安装 + npm 全局安装 + Homebrew 安装。

解决：

# 查看所有 claude 的安装位置
which -a claude
# 只保留一个！推荐原生安装，删除其他：
npm uninstall -g @anthropic-ai/claude-code    # 删 npm 版
brew uninstall --cask claude-code              # 删 Homebrew 版

现象：安装过程中突然被系统 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

现象：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	查看版本

命令	用途
/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 代理

# ~/.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"

# ~/.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"

# ~/.bashrc 添加以下内容
export ANTHROPIC_BASE_URL="https://litellm.internal.company.com:4000"
export ANTHROPIC_AUTH_TOKEN="sk-litellm-team-key"

Claude Code 的安装本身不难，难的是配置自定义 API 接口这一步。核心记住：

1. ANTHROPIC_BASE_URL = 你的 API 地址
2. ANTHROPIC_API_KEY = 你的密钥
3. 代理必须兼容 Anthropic Messages API（/v1/messages）
4. 有问题先跑 /status 看配置，再用 curl 测试接口

以上就是本地安装Claude Code+自定义API接口的全配置指南的详细内容，更多关于本地安装Claude Code+自定义API接口的资料请关注风君子博客其它相关文章！