一、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 *)"
    ]
  }
}

配置的优先级(从高到低):

  1. Managed(组织管理配置,不可覆盖)
  2. 命令行参数(临时会话覆盖)
  3. Local.claude/settings.local.json,仅本项目本人)
  4. Project.claude/settings.json,团队共享)
  5. 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-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 配置。

🕳️ 坑 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 接口这一步。核心记住:

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

AtomGit 是由开放原子开源基金会联合 CSDN 等生态伙伴共同推出的新一代开源与人工智能协作平台。平台坚持“开放、中立、公益”的理念,把代码托管、模型共享、数据集托管、智能体开发体验和算力服务整合在一起,为开发者提供从开发、训练到部署的一站式体验。

更多推荐