Claude Code API怎么配置？环境变量、模型设置与常见报错

Claude Code 是基于 Anthropic API 的命令行编程助手。安装好之后，第一步就是配置 API 认证和服务地址。很多开发者卡在这一步：环境变量不知道填哪个、Base URL 该写到哪一级、报错 401 还是 404 分不清。

下面把配置流程走一遍，再把最常见的报错逐个排查。

安装前提

Claude Code 通过 npm 安装，需要 Node.js 18 及以上版本。

npm install -g @anthropic-ai/claude-code

安装完用 claude --version 验证。Windows 用户建议搭配 WSL2 或 Git for Windows 使用，原生 PowerShell 下部分终端功能可能受限。

核心环境变量

Claude Code 通过以下环境变量完成认证和路由：

变量	作用	是否必填
ANTHROPIC_AUTH_TOKEN	API 认证令牌，二选一	是
ANTHROPIC_API_KEY	API 密钥，与上面二选一	是
ANTHROPIC_BASE_URL	API 服务地址	使用官方服务可不填
ANTHROPIC_MODEL	指定默认模型	否，默认使用 Sonnet

ANTHROPIC_AUTH_TOKEN 和 ANTHROPIC_API_KEY 只需要设置其中一个。ANTHROPIC_AUTH_TOKEN 优先级更高，如果你同时设了两个，Claude Code 会优先使用 Token。

设置环境变量

Linux / macOS

在 ~/.bashrc 或 ~/.zshrc 里添加：

export ANTHROPIC_AUTH_TOKEN="YOUR_AUTH_TOKEN"
export ANTHROPIC_BASE_URL="YOUR_BASE_URL"

保存后执行 source ~/.bashrc 生效。

Windows PowerShell

当前会话临时设置：

$env:ANTHROPIC_AUTH_TOKEN = "YOUR_AUTH_TOKEN"
$env:ANTHROPIC_BASE_URL = "YOUR_BASE_URL"

永久写入用户环境变量：

[System.Environment]::SetEnvironmentVariable('ANTHROPIC_AUTH_TOKEN', 'YOUR_AUTH_TOKEN', 'User')
[System.Environment]::SetEnvironmentVariable('ANTHROPIC_BASE_URL', 'YOUR_BASE_URL', 'User')

设置完重开一个终端窗口才会生效。

验证是否生效

在 Claude Code 会话中输入：

/status

它会显示当前使用的认证方式、Base URL 和模型。如果显示的环境变量和你设的不一致，检查一下是否有其他配置文件覆盖了。

Base URL 的注意事项

Base URL 是配置中最容易出错的地方。

不要带尾部斜杠。 有些服务端点对末尾的 / 敏感：

# 错误
export ANTHROPIC_BASE_URL="https://your-endpoint.com/v1/"

# 正确
export ANTHROPIC_BASE_URL="https://your-endpoint.com/v1"

Anthropic 协议的 Base URL 和 OpenAI 协议不同。 OpenAI 兼容接口通常以 /v1 结尾（如 https://api.openai.com/v1），而 Anthropic 协议的路径结构不同。具体以你使用的服务端点文档为准，不要凭经验拼接。

不要把 Base URL 写成完整的接口路径。 Base URL 只需要填到服务根地址，后面的路径 Claude Code 会自动拼接。

模型设置

Claude Code 默认使用 Sonnet 模型。如果你想指定其他模型，可以用 ANTHROPIC_MODEL 设置默认模型，也可以分别设置不同用途的模型：

export ANTHROPIC_DEFAULT_SONNET_MODEL="YOUR_MODEL_ID"
export ANTHROPIC_DEFAULT_HAIKU_MODEL="YOUR_MODEL_ID"

模型 ID 必须与你使用的服务平台提供的完全一致。在 Anthropic 官方，当前可用的模型包括 claude-sonnet-4-20250514、claude-haiku-3-5-20241022 等，具体以官方文档为准。

如果你用的是兼容平台，模型 ID 以平台控制台显示为准，不要凭印象手打。不同平台对同一个模型的命名可能不同，有的带日期后缀，有的用别名。

常见报错排查

401 Unauthorized

原因：API Key 无效、过期、额度用完，或者复制时带了空格。

排查步骤：

1. 去服务平台控制台确认 Key 状态是否为"已启用"
2. 检查 echo $ANTHROPIC_AUTH_TOKEN 输出的值和平台上的 Key 是否完全一致，注意前后有没有空格或换行
3. 确认账户余额和套餐额度

404 Not Found

原因：Base URL 写错了，或者模型 ID 不存在。

排查步骤：

1. 检查 ANTHROPIC_BASE_URL 是否和你使用的服务端点文档一致
2. 确认 Base URL 没有多余的 /v1 或尾部斜杠
3. 用 /status 查看当前实际使用的模型 ID，和平台支持的模型列表核对

429 Rate Limit Exceeded

原因：并发请求超出了当前 Key 的速率限制。

排查步骤：

1. 降低并发量，或等待限流窗口过去
2. 去控制台查看当前 Key 的速率限制和剩余额度
3. Claude Code 在执行复杂任务时会持续调用 API，Token 消耗比普通对话大得多，注意预算

连接超时 / Failed to connect

原因：网络无法到达 API 地址。

排查步骤：

1. 确认网络环境可以访问你配置的 Base URL
2. 检查是否有防火墙或代理拦截了请求
3. 如果使用的是第三方服务，确认服务地址没有被墙

API Key 优先级冲突

一个容易踩的坑：你明明用订阅账号登录了 Claude Code，但它实际走的却是某个 API Key。原因是环境变量的优先级高于 /login 登录的订阅认证。如果你的 shell 配置文件里 export 了 ANTHROPIC_API_KEY，即使你有有效的 Pro 或 Max 订阅，Claude Code 也会优先使用环境变量里的 Key。

解决方法：如果不需要 API Key，把 shell 配置文件里的相关 export 行注释掉，或者在启动 Claude Code 前临时 unset：

unset ANTHROPIC_API_KEY
claude

快速排错表

报错	最常见原因	第一步排查
401	Key 无效或过期	控制台确认 Key 状态和余额
404	Base URL 或模型 ID 错误	/status 查看当前配置，和服务端文档核对
429	超出速率限制	降低并发，确认套餐额度
连接超时	网络不通或被拦截	ping Base URL 地址，检查代理和防火墙
认证方式不对	环境变量覆盖了订阅	unset ANTHROPIC_API_KEY 后重试

配置检查清单

配置完 Claude Code 之后，对着这张表过一遍：

检查项	怎么查
Node.js 版本 ≥ 18	node -v
Claude Code 已安装	claude --version
认证变量已设置	echo $ANTHROPIC_AUTH_TOKEN
Base URL 格式正确	不带尾部斜杠，和服务端文档一致
模型 ID 存在	/status 确认，和平台模型列表核对
网络可达	能正常访问 Base URL 地址

大部分配置问题都出在这几个环节上。如果 /status 显示一切正常但还是报错，先确认是 API 层的问题还是 Claude Code 工具层的问题：用 curl 直接请求一次 Base URL，看返回的是 401 还是能正常响应，能快速缩小排查范围。