Claude Code API 兼容接口怎么设置模型？

更新于 2026-11-05 · orcarouter.cyou

简答：Claude Code 接入兼容接口要按三步做：先确认网关提供 Anthropic Messages 格式，而不是只有 OpenAI 兼容接口；再选择一种鉴权变量；最后把网关模型目录中的精确模型 ID 填入配置。先用一条最小请求验证地址和凭据，再写入 settings.json，可避免把模型名错误误判成 401 或 404。

定义：Claude Code API 兼容接口配置，是通过 Anthropic 格式的网关地址、匹配的凭据变量和网关实际支持的模型字符串，让 Claude Code 将请求发送到指定 API 服务。

先做 30 秒核对：三项必须匹配

本文是独立整理的配置指南，不代表任何品牌的官方页面。根据 Claude Code 网关文档，兼容接入前至少要拿到网关 Base URL、凭据类型和可用模型名称；仅有一个 OpenAI 兼容地址，不能直接证明它可以被 Claude Code 使用。

• 接口格式：确认网关接收 Anthropic Messages 请求，通常需要能够处理 POST /v1/messages；最终路径以网关文档为准。
• 鉴权方式：Bearer Token 使用 ANTHROPIC_AUTH_TOKEN；明确要求 API Key 或 x-api-key 时使用 ANTHROPIC_API_KEY。
• 模型字符串：填写网关模型目录或服务商文档中的精确 ID，不要根据模型展示名自行猜测。

最短流程是：临时设置变量 → 发一个只返回少量内容的 Messages 请求 → 在 Claude Code 中运行 /status → 确认后再写入配置文件。官方连接页面还说明，正常返回消息，或返回“模型未知”但没有拒绝凭据，都可以帮助区分地址、鉴权和模型名问题。

原生 Anthropic 转发与模型映射网关怎么区分

“兼容接口”不是单一类型。更稳妥的判断方式不是看服务名称，而是看网关对 Claude Code 请求的处理层。官方兼容性说明用于核对网关应转发的端点、请求头和功能字段。

如果网关只支持 OpenAI Chat Completions，而没有 Anthropic Messages 兼容层，应先查网关是否提供专门的适配入口；不要把 /chat/completions 强行写进 Claude Code 的 Base URL。模型能力、工具调用和上下文支持也要逐项核验，不能仅凭模型名称推断。

第一步：临时设置 Base URL、Token 和主模型

首次配置建议只在当前终端设置环境变量，先把“网关不通”与“Claude Code 没读到配置”分开。以下值均为占位符，不能直接使用。

Bash 或 Zsh，Bearer Token：

export ANTHROPIC_BASE_URL="https://your-gateway.example.com"
export ANTHROPIC_AUTH_TOKEN="YOUR_GATEWAY_TOKEN"
export ANTHROPIC_MODEL="YOUR_GATEWAY_MODEL_ID"

PowerShell，Bearer Token：

$env:ANTHROPIC_BASE_URL = "https://your-gateway.example.com"
$env:ANTHROPIC_AUTH_TOKEN = "YOUR_GATEWAY_TOKEN"
$env:ANTHROPIC_MODEL = "YOUR_GATEWAY_MODEL_ID"

如果网关明确要求 x-api-key，改用：

export ANTHROPIC_BASE_URL="https://your-gateway.example.com"
export ANTHROPIC_API_KEY="YOUR_GATEWAY_API_KEY"
export ANTHROPIC_MODEL="YOUR_GATEWAY_MODEL_ID"

Claude Code 环境变量文档明确区分了两种变量：ANTHROPIC_AUTH_TOKEN 会放入 Authorization: Bearer，ANTHROPIC_API_KEY 会放入 X-Api-Key。首次排查时不要同时设置两者，否则无法判断网关实际读取了哪个请求头。

Base URL 不要先自行追加 /v1/messages。Claude Code 的验证命令会根据其请求规则访问消息接口，但不同网关可能要求根路径、版本路径或其他前缀；最终以网关文档和实际请求路径为准。

第二步：用最小 Messages 请求先验地址和鉴权

下面命令适用于网关明确支持 Anthropic Messages 格式、并且 Base URL 的拼接方式与示例一致的情况。模型 ID 使用占位符，必须替换成网关实际支持的字符串。命令结构参考 Claude Code 官方网关连接步骤。

Bash 或 Zsh，Bearer Token：

curl -sS -w '\nHTTP %{http_code}\n' -X POST "$ANTHROPIC_BASE_URL/v1/messages" \
-H "Authorization: Bearer $ANTHROPIC_AUTH_TOKEN" \
-H "anthropic-version: 2023-06-01" \
-H "content-type: application/json" \
-d '{"model":"'"$ANTHROPIC_MODEL"'","max_tokens":1,"messages":[{"role":"user","content":"."}]}'

Bash 或 Zsh，API Key：

curl -sS -w '\nHTTP %{http_code}\n' -X POST "$ANTHROPIC_BASE_URL/v1/messages" \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-H "content-type: application/json" \
-d '{"model":"'"$ANTHROPIC_MODEL"'","max_tokens":1,"messages":[{"role":"user","content":"."}]}'

官方示例使用的版本头是 2023-06-01；这只是该示例的请求头，不代表所有网关都接受同一版本值。若网关文档要求自动补充、修改或忽略该请求头，应以网关要求为准。

成功判据应同时看 HTTP 状态和响应体：请求到达正确地址、鉴权没有被拒绝、响应是合法 JSON，并且包含消息响应字段。官方连接文档说明，响应以消息 ID 开头并包含 content 字段时，可作为地址和凭据有效的信号；如果只提示模型未知，通常应先改查模型 ID，而不是继续更换 Token。

第三步：写入 settings.json，再确认 Claude Code 实际读取了什么

临时请求成功后，再持久化配置。Claude Code 设置文件文档列出的用户级文件是 ~/.claude/settings.json；Windows 下对应 %USERPROFILE%\.claude\settings.json。单项目测试可使用 .claude/settings.local.json，但应避免把真实凭据写入会提交到仓库的共享项目文件。

Bearer Token 示例：

{
"env": {
"ANTHROPIC_BASE_URL": "https://your-gateway.example.com",
"ANTHROPIC_AUTH_TOKEN": "YOUR_GATEWAY_TOKEN",
"ANTHROPIC_MODEL": "YOUR_GATEWAY_MODEL_ID"
}
}

如果使用 API Key，将 ANTHROPIC_AUTH_TOKEN 替换成 ANTHROPIC_API_KEY，不要把两种鉴权变量同时写进去。设置文件必须是严格 JSON，不能写注释或尾逗号。

1. 保存文件后启动 Claude Code。
2. 运行 /status，检查 Anthropic base URL 是否显示网关地址。
3. 检查状态页是否显示正在使用 ANTHROPIC_AUTH_TOKEN、ANTHROPIC_API_KEY 或其他凭据来源。
4. 发送一条最小消息，确认实际请求成功。
5. 如果配置被拒绝或没有生效，运行 claude doctor 查看被忽略的配置项。

设置文件通常会被重新加载，但部分配置只在会话启动时读取；模型也可以用 /model 在当前会话切换。环境变量由启动 Claude Code 的进程继承，因此从另一个终端、编辑器或桌面入口启动时，可能看不到当前 Shell 的变量。

主模型和后台模型变量怎么填

ANTHROPIC_MODEL 用于指定 Claude Code 使用的模型设置名，实际可填写什么取决于当前 Claude Code 版本和网关模型目录。最稳妥的做法是复制网关提供的精确字符串，再用最小请求验证；本文不写死任何未经网关确认的模型 ID。

后台模型需要注意变量变化。当前官方环境变量页面将 ANTHROPIC_SMALL_FAST_MODEL 标记为 DEPRECATED，并说明它是后台任务使用的 Haiku 类模型变量；同一页面列出 ANTHROPIC_DEFAULT_HAIKU_MODEL，用于指定 haiku 别名对应的模型，并用于后台功能。不同 Claude Code 版本的支持范围可能变化，新的配置应以当前环境变量文档为准。

建议按以下顺序设置：

1. 先只配置 Base URL、一种鉴权变量和 ANTHROPIC_MODEL。
2. 确认主对话可以返回后，再考虑单独设置后台模型。
3. 核对网关是否真的支持后台模型所需的请求字段、工具和上下文能力。
4. 后台任务报错时，先移除后台模型变量，重新验证主模型，再根据响应体逐项恢复。

如果当前版本文档没有明确说明某个后台变量的行为，就不要把它写成“必须配置”或“未配置就一定调用某个默认模型”。

错误怎么分流：不要把 401、404 和超时混为一谈

排查时先保存脱敏后的状态码、响应体、最终路径和请求头类型，不要公开 Token。若 /status 没有显示网关 Base URL，优先检查 Claude Code 是否从正确的终端或设置范围启动；如果 Base URL 正确但返回 401，再检查凭据变量；如果鉴权通过但提示模型未知，则转查模型字符串。

常见问题

Claude Code 的 ANTHROPIC_AUTH_TOKEN 和 ANTHROPIC_API_KEY 要同时设置吗？

不建议。前者对应 Authorization: Bearer，后者对应 x-api-key。根据网关文档选择一种；如果没有明确说明，可先按官方连接步骤使用 Bearer 方式验证，收到 401 后再切换另一种。

ANTHROPIC_MODEL 应该填官方模型名还是网关模型名？

填网关实际接受的模型字符串。它可能是官方模型 ID，也可能是映射名、别名或带前缀的字符串。优先从网关模型目录、控制台或接口文档复制，并用最小 Messages 请求验证。

ANTHROPIC_SMALL_FAST_MODEL 还能继续使用吗？

官方当前环境变量页面已将它标记为弃用。新配置应先核对当前版本是否支持 ANTHROPIC_DEFAULT_HAIKU_MODEL；无法从当前文档确认时，就不要把任一变量写成必需项。

Base URL 应该写到 /v1 还是域名根路径？

没有适用于所有网关的统一写法。应根据网关文档确认 Base URL 和最终消息路径，避免把完整的 /v1/messages 写入 Base URL 后再次拼接。

settings.json 改完后必须关闭整个终端吗？

不必把关闭终端作为固定要求。先用 /status 确认设置文件是否被读取；如果使用 Shell 环境变量，应从设置变量的同一终端启动 Claude Code。部分配置只在会话启动时读取，模型也可以用 /model 临时切换。

为什么 Base URL 正确，仍然提示模型不存在？

这通常说明地址和鉴权可能已经通过，但当前请求中的模型字符串不被网关识别。查看网关模型目录或响应体，复制精确模型 ID，不要仅根据展示名称猜测。

相关阅读

• 继续排查 Anthropic API 401：鉴权变量与请求头
• 了解 Base URL 与 /v1 的路径拼接
• 区分 API endpoint 和 Base URL
• 查看模型 ID 与兼容性核验方法
• 学习 API Key 的安全保存与轮换

参考资料

1. Environment variables - Claude Code Docs（code.claude.com）
2. Settings files and precedence - Claude Code Docs（code.claude.com）