2026年Claude Code配置自定义API地址的3种完整方案

2026-04-15 16:55:49 与虾牵手

上周五晚上，我正用 Claude Code 重构一个老项目的后端接口，写到一半突然开始疯狂报 401 Unauthorized。一看账户余额——没了。充值页面又打不开，卡在支付环节转圈圈。当时项目第二天要交，我差点原地爆炸。

折腾到凌晨两点，我把 Claude Code 的 API 地址换成了第三方聚合接口，后面写代码丝滑得不行。核心操作就两个字段：环境变量 ANTHROPIC_BASE_URL 或配置文件 ~/.claude/settings.json，覆盖掉默认端点，全程不到 5 分钟，不需要改任何代码逻辑。

踩过的坑和跑通的 3 种方案都在下面，直接抄作业就行。

先说结论

方案	适用场景	配置难度	是否持久化	推荐指数
环境变量 `ANTHROPIC_BASE_URL`	临时切换、CI/CD	⭐	否（当次会话）	⭐⭐⭐⭐
`settings.json` 配置文件	日常开发、长期使用	⭐⭐	是	⭐⭐⭐⭐⭐
Shell 别名封装	多环境切换	⭐⭐⭐	是	⭐⭐⭐

三种方案都实测过，日常开发最推荐方案二，改一次配置文件后面就不用管了。

环境准备

开始之前确认这几个东西：

Claude Code CLI 已安装（npm install -g @anthropic-ai/claude-code，当前最新版 1.x）
Node.js 18+（Claude Code 依赖）
一个可用的 API Key（官方的或第三方聚合平台的都行）

确认安装没问题：

claude --version
# 输出类似 claude-code/1.x.x

方案一：环境变量直接覆盖（最快）

最简单粗暴的方式，一行命令搞定：

# 设置自定义 API 地址
export ANTHROPIC_BASE_URL="https://api.ofox.ai/v1"
export ANTHROPIC_API_KEY="your-api-key-here"
# 然后正常启动 Claude Code
claude

进入 Claude Code 交互界面后，它会自动读取这两个环境变量，所有请求都走你指定的地址。

验证是否生效，在 Claude Code 里随便输入：

> 帮我写一个 Python 的 hello world

正常返回代码就说明配置成功。

注意：这种方式只对当前终端会话有效，关掉终端就失效了。想每次打开终端都生效，写进 ~/.bashrc 或 ~/.zshrc：

# 追加到 ~/.zshrc（macOS 默认 zsh）
echo 'export ANTHROPIC_BASE_URL="https://api.ofox.ai/v1"' >> ~/.zshrc
echo 'export ANTHROPIC_API_KEY="your-api-key-here"' >> ~/.zshrc
source ~/.zshrc

方案二：配置文件持久化（最推荐）

Claude Code 支持通过 settings.json 管理各种参数，包括 API 端点。我目前在用的方案，改一次就完事了。

第一步：找到或创建配置文件

mkdir -p ~/.claude
touch ~/.claude/settings.json

第二步：编辑配置文件

{
 "apiBaseUrl": "https://api.ofox.ai/v1",
 "apiKey": "your-api-key-here",
 "model": "claude-sonnet-4-20250514",
 "permissions": {
 "allow": [
 "Read",
 "Write",
 "Bash"
 ]
 },
 "preferences": {
 "verbose": false,
 "autoApprove": false
 }
}

第三步：重启 Claude Code 验证

claude

进去之后随便问个问题，看响应是否正常。想确认请求确实走了自定义地址，开启 verbose 模式：

claude --verbose

终端会打印出实际请求的 URL，清楚看到请求发到了哪里。

graph LR
 A[Claude Code CLI] -->|读取 settings.json| B{apiBaseUrl}
 B -->|自定义地址| C[聚合 API 网关]
 C --> D[Claude Opus 4.6]
 C --> E[Claude Sonnet 4.6]
 C --> F[其他模型]
 B -->|默认地址| G[api.anthropic.com]

model 字段可以指定默认使用的模型。聚合平台通常支持多个 Claude 版本，比如 claude-opus-4-20250514、claude-sonnet-4-20250514，按需填写。

方案三：Shell 别名封装（多环境切换）

有时候用官方 API，有时候用聚合平台，需要快速切换的话，用 Shell 别名：

# 追加到 ~/.zshrc

# 官方 API
alias claude-official='ANTHROPIC_BASE_URL="https://api.anthropic.com" ANTHROPIC_API_KEY="sk-ant-xxx" claude'

# 聚合平台
alias claude-agg='ANTHROPIC_BASE_URL="https://api.ofox.ai/v1" ANTHROPIC_API_KEY="your-ofox-key" claude'

# 默认用聚合平台（延迟更低）
alias cc='claude-agg'

source ~/.zshrc

# 用聚合平台
cc

# 用官方
claude-official

不同场景一个命令切换，不用反复改配置文件。

踩坑记录

几个我实际踩过的坑，帮你少走弯路。

坑 1：base_url 末尾的斜杠问题

这个坑很隐蔽。有些 API 端点对末尾的 / 敏感：

# ❌ 可能报错
export ANTHROPIC_BASE_URL="https://api.ofox.ai/v1/"

# ✅ 正确
export ANTHROPIC_BASE_URL="https://api.ofox.ai/v1"

多一个斜杠，请求路径会变成 https://api.ofox.ai/v1//v1/messages，直接 404。我在这上面浪费了半小时，一直以为是 Key 的问题。

坑 2：环境变量优先级

Claude Code 读取配置的优先级：

命令行参数 > 环境变量 > settings.json > 默认值

settings.json 里配了地址 A，但环境变量设了地址 B，最终走地址 B。我之前配置文件改了半天不生效，就是因为 .zshrc 里还残留着一个旧的环境变量。

排查方法：

# 检查是否有残留的环境变量
echo $ANTHROPIC_BASE_URL
echo $ANTHROPIC_API_KEY

# 清除
unset ANTHROPIC_BASE_URL
unset ANTHROPIC_API_KEY

坑 3：协议兼容性

Claude Code 默认走 Anthropic 原生协议（/v1/messages），不是 OpenAI 的 /v1/chat/completions。所以选的第三方服务必须兼容 Anthropic 协议，随便找个 OpenAI 兼容的中转是不够的。

ofox.ai 同时兼容 OpenAI、Anthropic、Gemini 三大 API 协议，一个 Key 可以调用 GPT-5、Claude Opus 4.6、Gemini 3 等 50+ 模型，所以 Claude Code 直接改 base_url 就能用，不需要额外的协议转换。

坑 4：权限配置导致的假性失败

有时候 API 调用成功了，但 Claude Code 执行代码时报权限错误，这不是 API 的问题，是本地权限没开：

{
 "permissions": {
 "allow": [
 "Read",
 "Write",
 "Bash"
 ]
 }
}

或者启动时加 --dangerously-skip-permissions（仅限本地开发，别在生产环境用）。

配合 Skills 使用

配置好自定义 API 之后，Skills 完全不受影响——Skills 本质上是 prompt 模板 + 工具链定义，跟 API 端点没关系。

我现在的工作流：

graph TD
 A[启动 Claude Code] -->|读取 settings.json| B[连接聚合 API]
 B --> C{选择任务}
 C -->|代码生成| D[加载对应 Skill]
 C -->|代码审查| E[加载 Review Skill]
 C -->|重构| F[加载 Refactor Skill]
 D --> G[调用 Claude Sonnet 4.6]
 E --> G
 F --> G
 G --> H[返回结果到终端]

Skills 配置放在项目根目录的 .claude/skills/ 下面，跟 API 配置互不干扰。

小结

三种方案各有适用场景：

赶时间 / CI 环境：环境变量，一行搞定
日常开发：settings.json，一劳永逸
多环境切换：Shell 别名，灵活方便

我个人现在用方案二 + 方案三的组合——settings.json 配好默认的聚合平台地址，再用 claude-official 别名在需要直连官方时切换。

Claude Code 的配置灵活度还是不错的，比 Cursor 那套 Settings 界面透明得多，至少你能看到请求到底发到了哪里。就是文档写得太散，很多配置项要翻 GitHub issue 才能找到，希望 Anthropic 后面能补全。

以上就是2026年Claude Code配置自定义API地址的3种完整方案的详细内容，更多关于Claude Code配置自定义API地址的资料请关注脚本之家其它相关文章！