Seven

Posted on Jul 13

让 Claude Code 走第三方 Anthropic 兼容 API：一个可复现的排查顺序

#api #ai #webdev #chinese

利益关系与地区说明：DaoXE 是我们运营的多模型、多协议 API 网关，支持 OpenAI Chat Completions、OpenAI Responses、Anthropic Messages（Claude 协议）以及兼容的图片生成接口。DaoXE 不向中国大陆提供服务；本文仅供服务条款允许地区的海外华语开发者参考。下面的排查顺序适用于任何 Anthropic Messages 兼容的网关，不限于 DaoXE。

Claude Code 的 CLI 走的是 Anthropic 的 Messages 协议。只要一个网关在 /v1/messages 暴露了 Claude 协议，你就可以用两个环境变量把 Claude Code 直接指过去，不需要代理、不需要 router、不用改任何代码。

问题几乎从不是模型或提示词，而是 base URL 的形状、shell 环境，或者 token 变量名。下面这个顺序能在几十秒内把「网关/密钥问题」和「Claude Code 配置问题」分开，让你不再瞎试。

先记住这两个变量

export ANTHROPIC_BASE_URL="https://your-gateway.example"   # 主机根，不要带 /v1
export ANTHROPIC_AUTH_TOKEN="你的_API_KEY"

Claude Code 会自己补 /v1/messages。最常见的错误就是把 ANTHROPIC_BASE_URL 设成 https://your-gateway.example/v1，结果 Claude Code 请求的是 /v1/v1/messages，全部 404。

第 1 步：先用 curl 验证协议，别先启动 claude

如果 curl 都不通，改 Claude Code 的设置没有任何意义。先从当前账户查一个真实模型 ID，再发一次极小的 Messages 请求（max_tokens 保持很小，可能计费）：

export API_KEY="你的_API_KEY"

# 1. 这个账户当前能调哪些模型？
curl -H "Authorization: Bearer $API_KEY" https://your-gateway.example/v1/models

# 2. 一次极小的 Messages 请求
export MODEL="从上一步复制的确切_id"
curl --fail-with-body --show-error --silent \
  -H "x-api-key: $API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "Content-Type: application/json" \
  -d "{\"model\":\"$MODEL\",\"max_tokens\":8,\"messages\":[{\"role\":\"user\",\"content\":\"Reply with OK.\"}]}" \
  https://your-gateway.example/v1/messages

200 + 简短返回 → 协议没问题，进第 2 步。
401 → 密钥错误 / 未激活 / 请求头不对。在这里修，不要去改 Claude Code。
404 / 返回 HTML → 路径或 base URL 形状不对。记下能跑通的确切 URL。
model-not-found → 这个 ID 不在你的账户目录里，换第 1 步查到的 ID。

第 2 步：确认无误后再启动 Claude Code

export ANTHROPIC_BASE_URL="https://your-gateway.example"   # 主机根
export ANTHROPIC_AUTH_TOKEN="$API_KEY"
claude

如果 curl 通了、Claude Code 还是失败，按顺序查这几项：

base URL 里带了 /v1。必须是主机根。这是头号原因。
shell 不对。export 必须和启动 claude 在同一个终端里；新开的标签页拿不到这些变量。
token 变量名。部分 Claude Code 版本读 ANTHROPIC_API_KEY 而不是 ANTHROPIC_AUTH_TOKEN，两个都设成同一个值。
模型别名 vs 真实 ID。如果设了 ANTHROPIC_MODEL，它必须是第 1 步里的确切 ID，而不是网关未必映射的 Anthropic 友好别名。
过期的配置文件覆盖了环境变量。检查 ~/.claude/settings.json 和项目里的 .claude/settings.json。

第 3 步：固化配置（可选）

跑通后，把变量写进 shell 配置，省得每次重开都要重新 export：

# ~/.zshrc 或 ~/.bashrc
export ANTHROPIC_BASE_URL="https://your-gateway.example"
export ANTHROPIC_AUTH_TOKEN="你的_API_KEY"
# 可选，固定确切的目录模型 ID：
export ANTHROPIC_MODEL="从目录复制的确切_id"
export ANTHROPIC_SMALL_FAST_MODEL="轻量后台模型的确切_id"

密钥不要进 Git、不要出现在截图里。一旦泄露，去后台轮换。

为什么这个顺序重要

curl 通、IDE/CLI 红的组合非常常见，它通常不代表网关挂了，而是「客户端说的方言」和「你刚验证的那条路径」不是一回事。先用第 1 步的 raw Messages 请求把协议本身证明出来，就能把问题精确定位到客户端配置，而不是在模型和提示词上浪费时间。

客户端与协议对应

Cline / Continue / Roo 等编码助手 → 大多是 OpenAI 兼容的 Chat Completions（自定义 base URL）
较新的 agent 栈 → 可能需要 Responses
Claude Code / Anthropic SDK / 只认 Messages 的工具 → Anthropic Messages
图片工具 → 账户目录里含图片模型时走 OpenAI 兼容的 image generation

网关可能同时暴露以上全部，但某个客户端往往只用其中一种。配置客户端实际说的那条路径，别用单一心智模型硬套所有客户端。

参考

Claude Code 原生配置（ANTHROPIC_BASE_URL）：CLAUDE_CODE.md
客户端配置（Cline / Roo / Continue + 各协议路径）：CLIENT_SETUP.md
示例与低成本 benchmark：DaoXE-AI
主页（带追踪）：daoxe.com

环境变量名和优先级会随 Claude Code 版本变化；遇到异常时，对照当前 Claude Code 设置文档，并用第 1 步的 curl 作为基准。DaoXE 是多模型、多协议网关——不止 OpenAI 协议，也不止 OpenAI/Claude 两家模型。

DEV Community