Claude Code 接入自定义 API 教程：Base URL、Key 与模型（2026）

Claude Code 是 Anthropic 推出的命令行编程工具，默认连接 Anthropic 官方接口。国内团队在实际使用中，常把它指向自建或第三方网关，以解决访问稳定性、统一计费和额度管理的问题。所谓“接入自定义 API”，本质上只改三件事：请求发往哪里（Base URL）、用什么身份认证（Key）、调用哪个模型（模型名）。

本文按安装、环境变量、配置文件、模型选择、连接验证、团队落地和安全的顺序，走一遍可复用的接入流程。命令以 macOS 和 Linux 为主，Windows 会单独标注。

说明：Claude、Anthropic 是其权利人的商标，本文仅作技术接入说明，与相关厂商无隶属关系。Claude Code 版本更新较快，环境变量、配置项和菜单名称可能随版本调整，请以 claude --help、官方文档和站内接入说明为准。

一、接入前先确认三件事

Claude Code 使用的是 Anthropic Messages 协议，不是 OpenAI 的 Chat Completions 协议。因此，自定义 API 至少要满足两点：提供 Anthropic 兼容的 /v1/messages 入口；模型名与网关实际提供的名称一致。只有 OpenAI 兼容入口的网关，不能直接填给 Claude Code，除非它同时提供 Anthropic 兼容路由。

开始前准备三样东西：

• Base URL：网关根地址，例如 https://ai.zhongshangqihang.com。是否带 /v1 取决于网关实现，以站内接入说明为准。
• API Key：在控制台创建，设置额度上限和有效期，不要直接用长期不限额的 Key 做测试。
• 模型名：从控制台或价格页复制，不要凭记忆手写；大小写和连字符错一个字符都可能报模型不存在。

如果还没有账号，可以从 注册入口 开始，先创建一把低额度测试 Key。

二、安装 Claude Code

Claude Code 通常通过 npm 分发，也提供其他安装方式。下面是最常见的流程：

1. 确认 Node.js 已安装。建议使用仍在维护的 LTS 版本，具体最低版本以官方文档为准。
2. 执行 npm install -g @anthropic-ai/claude-code 全局安装。
3. 执行 claude --version，确认命令可用并记录版本号。
4. 进入一个测试项目目录，运行 claude，按提示完成主题、目录信任等首次设置。
5. 如果团队有版本管理要求，锁定版本并写进入门文档；升级前先在测试项目验证。

node --version
npm install -g @anthropic-ai/claude-code
claude --version
cd /path/to/your-project
claude

使用自定义 API 时，通常不需要登录 Anthropic 账号，但是否跳过登录取决于版本和配置方式。如果启动后仍被要求登录，先检查环境变量是否在启动 Claude Code 的同一个 shell 中生效。

三、环境变量：BASE_URL 与 AUTH_TOKEN

Claude Code 读取两个常见的认证变量：

• ANTHROPIC_BASE_URL：请求根地址。
• ANTHROPIC_AUTH_TOKEN：以 Authorization: Bearer 形式发送，常见于网关接入。
• ANTHROPIC_API_KEY：以 x-api-key 形式发送，贴近 Anthropic 原生鉴权方式。

两者选一个即可。网关如果按 Bearer 鉴权，用 ANTHROPIC_AUTH_TOKEN；如果按原生方式鉴权，用 ANTHROPIC_API_KEY。两个同时设置时，不同版本的优先级可能不同，容易出现“明明填对了却报 401”的情况，建议只保留一个。

export ANTHROPIC_BASE_URL="https://ai.zhongshangqihang.com"
export ANTHROPIC_AUTH_TOKEN="sk-你的密钥"
claude

写入 ~/.zshrc 或 ~/.bashrc 可以让配置长期生效，改完执行 source ~/.zshrc。Windows PowerShell 使用 $env:ANTHROPIC_BASE_URL="..."，只对当前窗口生效；需要持久化时用系统环境变量界面或 setx，改完重开终端。

不要把 export 写进项目脚本并提交。密钥进入 Git 历史后，删除文件并不等于删除记录。

四、settings.json：把配置固化到文件

环境变量适合临时切换，长期使用建议写进 Claude Code 的 settings 文件。常见位置有三层：

• 用户级：~/.claude/settings.json，对本机所有项目生效。
• 项目级：.claude/settings.json，可以提交到仓库，适合团队共享非敏感配置。
• 本地项目级：.claude/settings.local.json，不提交，适合个人覆盖。

示例：

{
  "env": {
    "ANTHROPIC_BASE_URL": "https://ai.zhongshangqihang.com",
    "ANTHROPIC_AUTH_TOKEN": "sk-你的密钥"
  },
  "model": "claude-sonnet-4-5"
}

注意：settings.json 里的 Key 是明文。个人电脑可以接受，共享机器、CI 和代码仓库里不要这么做。项目级文件只放 Base URL 和模型名，Key 交给环境变量或密钥管理工具。配置优先级大体是企业管理配置、命令行参数、本地项目、项目、用户依次覆盖，具体以当前版本文档为准。

五、模型选择：按任务分档

Claude 模型通常分三档，适合的任务不同：

档位	典型用途	取舍
Opus	复杂重构、跨文件分析、长链路 Agent	能力更强，成本通常更高，速度可能更慢
Sonnet	日常编码、改 Bug、代码审查	能力与成本较均衡，适合作为默认档
Haiku	简单补全、格式化、批量小任务	速度快、成本低，复杂任务容易力不从心

在 Claude Code 里可以用 ANTHROPIC_MODEL 指定主模型，也可以用 ANTHROPIC_DEFAULT_SONNET_MODEL、ANTHROPIC_DEFAULT_OPUS_MODEL、ANTHROPIC_DEFAULT_HAIKU_MODEL 分别覆盖不同档位的映射。不同版本支持的变量可能不同，配置前先看 claude --help 或官方文档。

模型名必须与网关的模型目录一致。网关可能对上游模型使用自己的命名，直接填官方文档里的名字未必能命中。可用模型和计费方式见 模型价格，价格会随模型版本和上游政策调整。

六、验证连接：先 curl，再进 Claude Code

先绕过 Claude Code，用 curl 验证网关本身是否通：

curl "$ANTHROPIC_BASE_URL/v1/messages" \
  -H "x-api-key: $ANTHROPIC_AUTH_TOKEN" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{
    "model": "claude-sonnet-4-5",
    "max_tokens": 64,
    "messages": [{"role": "user", "content": "只回复 OK"}]
  }'

如果网关使用 Bearer 鉴权，把 x-api-key 换成 Authorization: Bearer $ANTHROPIC_AUTH_TOKEN。返回 200 且内容正常，说明 Base URL、Key、模型这三项至少有一组可用。

然后回到 Claude Code，按顺序检查：

1. claude --version 确认客户端可执行。
2. 在项目目录运行 claude doctor（如果当前版本提供该命令），检查安装和配置。
3. 启动 claude，用 /status 查看当前模型和账号信息。
4. 输入一个低风险任务，例如“解释这个目录的结构，不要修改文件”。
5. 观察是否正常返回，以及是否出现 401、404 或模型不存在等错误。

常见现象对照：

现象	优先检查	处理
401	Key、变量名、请求头	重新复制 Key；只保留一个认证变量
404	Base URL 多了或少了 /v1	按网关文档改为根地址或兼容入口
model not found	模型名与网关目录不一致	从控制台或价格页复制
请求超时	网络、DNS、代理	换网络测试；检查代理是否改写请求头
429	并发或额度限制	降低并发；检查 Key 的限额

七、团队落地：一人一 Key，统一入口

团队使用不建议共用一把 Key。更稳妥的做法是：

• 一人一 Key，名称包含姓名或用途，离职时直接停用。
• 按项目或环境设置额度上限，生产与测试分开。
• 用统一网关集中查看用量、模型分布和异常调用。
• 用企业管理配置下发 Base URL 和允许的模型，减少成员手工配置出错。
• 把接入步骤写成入门文档，包含验证命令和常见错误。
• 每周或每月 review 一次用量，发现异常 Key 及时处理。

如果公司有采购和合规流程，先确认数据流向：代码片段会发送到网关及其上游模型服务。是否留存、留存多久、是否用于训练，需要看服务条款，不要自行假设。

八、安全边界：Key、代码与数据

最后是几条底线：

• Key 不进入 Git、镜像、前端代码、截图和聊天记录。
• 项目里加 .gitignore，至少覆盖 .env、.env.*、.claude/settings.local.json。
• 怀疑泄露时先吊销旧 Key，再排查用量，不要只改密码。
• 给 Key 设置过期时间，人员变动时轮换。
• 共享机器上用密钥管理工具或 apiKeyHelper，不要把明文写在 settings.json。
• 只从可信来源安装 Claude Code，升级前看变更说明。

常见问题

Claude Code 一定要登录 Anthropic 账号吗？

不一定。配置了可用的 Base URL 和认证变量后，客户端可以直接走自定义 API；但首次启动的主题、目录信任等引导仍可能出现。是否需要登录取决于版本和配置，遇到问题先检查环境变量是否在启动 shell 中生效。

ANTHROPIC_API_KEY 和 ANTHROPIC_AUTH_TOKEN 有什么区别？

前者通常以 x-api-key 请求头发送，后者以 Authorization: Bearer 发送。选哪个取决于网关的鉴权方式，建议只设置一个，避免请求头冲突。

Base URL 应该填根地址还是带 /v1？

Claude Code 一般填根地址，由客户端拼接 /v1/messages；部分网关要求直接填兼容入口。判断方法很简单：用 curl 请求根地址加 /v1/messages，能通就用根地址，否则按网关文档调整。

为什么 curl 能通，Claude Code 却报错？

常见原因是 shell 变量没有传给图形界面或 IDE 内置终端，或者同时设置了两个认证变量导致冲突。先在启动 Claude Code 的同一个终端里执行 echo $ANTHROPIC_BASE_URL 确认。

团队可以共用一把 Key 吗？

技术上可以，但不建议。共用 Key 无法区分成员用量，泄露后也难以定位责任人。一人一 Key 配合额度和过期时间，管理成本更低。

下一步

如果你还没有可用的网关账号，可以从 注册入口 开始，先创建一把低额度测试 Key，按本文的 curl 和 Claude Code 两步验证。模型与计费见 模型价格，价格会调整，以页面实时信息为准。

相关阅读：

• Claude Code API 完整教程
• Claude Code 价格：订阅还是 API
• Claude API 常见错误与排查