跨平台模型别名坑：opus 在 Vertex 和直连 API 指向不同版本

如果你用 Claude Code 配合 Google Vertex AI，可能遇到过这个错误：

API Error: 404 Publisher Model `projects/<your-project>/locations/us-east5/publishers/anthropic/models/claude-opus-4-1@20250805` was not found

你明明在项目里开通了 Opus 4.5，为什么请求的是 Opus 4.1？

因为 opus 这个模型别名，在不同平台上解析成不同的模型版本。

问题根源

Claude Code 的代码里有一段模型解析逻辑（GitHub issue #18447 里有人贴了出来）：

function getDefaultOpusModel() {
    if (process.env.ANTHROPIC_DEFAULT_OPUS_MODEL)
        return process.env.ANTHROPIC_DEFAULT_OPUS_MODEL;
    if (isFirstParty())
        return models.opus45;  // 直连 API → Opus 4.5
    return models.opus41;      // Vertex/Bedrock → Opus 4.1
}

逻辑很清楚：用 Anthropic 直连 API 时，opus 等于 Opus 4.5；用 Vertex AI 或 Bedrock 时，opus 等于 Opus 4.1。

这个设计的初衷可能是稳妥——第三方平台上较新的模型版本可能没有全量上线。但带来的问题是：如果你的 Vertex AI 项目只开通了 Opus 4.5 而没有 Opus 4.1（或者反过来），就会 404。

Opus 4.6 发布后这个问题更混乱了。现在有三个 Opus 版本在线（4.1、4.5、4.6），别名指向哪个取决于平台、取决于 Claude Code 版本，还可能随时更新。

影响范围

这个坑不只影响 Claude Code 的命令行用户。任何通过 Vertex AI 或 Bedrock 调用 Claude 的代码，如果用了别名而不是完整 model ID，都可能碰到。

具体的别名解析规则：

别名	Anthropic 直连	Vertex AI	Bedrock
`opus`	最新 Opus（不确定）	可能落后一到两个版本	可能落后一到两个版本
`claude-opus-4-6`	Opus 4.6	看是否已上线	看是否已上线

问题在于"不确定"和"可能"——这些映射没有一个稳定的文档，你不能假设它在所有平台上行为一致。

怎么解决

方法一：永远用完整 model ID

最直接的办法。不依赖别名，不受平台差异影响。

# Claude Code 命令行
claude --model claude-opus-4-6

# 不要
claude --model opus

# API 调用
response = client.messages.create(
    model="claude-opus-4-6",  # 完整 ID
    ...
)

Vertex AI 上的完整 ID 格式稍有不同：

# Vertex AI
model = "claude-opus-4-6@20260205"  # 注意 @ 后面的日期

方法二：环境变量覆盖

如果你的团队习惯了用 opus 别名，可以用环境变量强制指定：

export ANTHROPIC_DEFAULT_OPUS_MODEL="claude-opus-4-6"

但有个坑：GitHub issue #17760 报告说这个环境变量在某些版本的 Claude Code 里不被正确识别（从 /model 列表选择时无效）。确认你的 Claude Code 版本已经修复了这个问题。

方法三：在 CI/CD 和脚本里固定版本

如果你的自动化脚本调用 Claude Code，一定要显式指定 model。不要让"默认值"来决定用哪个模型。

# 在脚本里
claude -p "review this code" --model claude-opus-4-6

# 不要
claude -p "review this code"  # 默认模型取决于配置和平台

多平台部署时的额外注意

如果你的后端同时接了多个 Claude 平台（比如主用 Anthropic API，备用 Bedrock），模型版本的一致性更重要。

一个真实场景：你配了回退策略——Anthropic API 挂了自动切 Bedrock。如果两边用的 Opus 版本不一样（一个 4.6，一个 4.5），模型行为会有差异。对于依赖特定行为（比如 adaptive thinking 只在 4.6 上支持）的代码，切换后可能直接报错。

建议：

在回退配置里用完整 model ID
回退目标平台的模型版本要跟主平台对齐
有版本不一致时宁可让回退失败并告警，也别静默用一个不兼容的版本

怎么确认当前用的是哪个模型

在 Claude Code 里：

/model

会显示当前使用的模型和可选列表。

在 API 响应里，model 字段会返回实际使用的完整 model ID（不是你传入的别名）。建议在日志里记录这个字段——调查问题时非常有用。

response = client.messages.create(model="opus", ...)
print(response.model)  # 实际用的是什么版本

这个问题不会导致数据丢失或安全问题，但会导致请求失败（404）、行为不一致、和成本偏差（不同版本价格不同，4.1 是 $15/MTok 输入，4.5/4.6 是 $5/MTok——差了三倍）。在生产环境里，任何"不确定"都是风险。

参考链接

GitHub Issue #18447（别名不一致）：https://github.com/anthropics/claude-code/issues/18447
GitHub Issue #17760（环境变量不生效）：https://github.com/anthropics/claude-code/issues/17760
Vertex AI 部署文档：https://platform.claude.com/docs/en/build-with-claude/claude-on-vertex-ai