Claude Opus 4.7 迁移指南——破坏性变更与应对方法【完整版】

1. 本迁移指南适合谁

如 Claude Opus 4.7发布一文 所介绍，Opus 4.7是4.6的直系后继。但 API层面引入了多项破坏性变更，仅替换模型名可能会得到 400 Bad Request。

本文适合下列读者。

• 使用Anthropic API / SDK调用 claude-opus-4-6 系列的开发者
• 通过Bedrock / Vertex AI使用Claude的团队
• 停在Opus 4.5或4.1、打算一口气升级到4.7的人
• 在生产环境使用扩展思考（thinking: enabled）或 temperature 的人

本文以Anthropic官方迁移指南为一手资料，结合中文开发场景中容易踩坑的地方做整理。官方信息可参考 platform.claude.com的迁移指南。

2. 3行总结——最快了解

给时间紧的读者的TL;DR。

1. 把模型名从 claude-opus-4-6 替换为 claude-opus-4-7（SDK也要升级到最新）
2. 破坏性变更主要3项：扩展思考 enabled 废止（改为自适应思考 + effort）、temperature/top_p/top_k 废止、新分词器（相同文本最多1.35倍的token）
3. 作为回报能获得：更高的编码性能、1M上下文（标准价）、新的努力等级 xhigh

细节见下文各章。

3. 更新模型名

第一步很简单：替换模型标识符。

# Before
model = "claude-opus-4-6"

# After
model = "claude-opus-4-7"

如果用环境变量或配置文件管理，把这种"只改一处即可生效"的结构留好，下次升级也会轻松。

// .env
// CLAUDE_MODEL=claude-opus-4-6
CLAUDE_MODEL=claude-opus-4-7

// app.ts
const model = process.env.CLAUDE_MODEL ?? "claude-opus-4-7";

不过，仅替换模型名并不总能跑起来——这正是本次迁移的难点。下面按破坏性变更逐个讲。

4. 破坏性变更1：扩展思考废止，改为自适应思考

Opus 4.6中开启扩展思考（extended thinking）通常使用 thinking: {type: "enabled", budget_tokens: N}。在4.7中这种写法会返回400错误。

改为使用模型自行调整思考量的"自适应思考（adaptive thinking）"。而且 4.7默认思考OFF，省略 thinking 字段就没有思考。要获得以往的深度推理，必须显式开启。

Before (4.6) / After (4.7)

# Before: Opus 4.6
client.messages.create(
    model="claude-opus-4-6",
    max_tokens=64000,
    thinking={"type": "enabled", "budget_tokens": 32000},
    messages=[{"role": "user", "content": "..."}],
)

# After: Opus 4.7
client.messages.create(
    model="claude-opus-4-7",
    max_tokens=64000,
    thinking={"type": "adaptive"},
    output_config={"effort": "high"},  # "max", "xhigh", "high", "medium", "low"
    messages=[{"role": "user", "content": "..."}],
)

// Before: Opus 4.6
await client.messages.create({
  model: "claude-opus-4-6",
  max_tokens: 64000,
  thinking: { type: "enabled", budget_tokens: 32000 },
  messages: [{ role: "user", content: "..." }],
});

// After: Opus 4.7
await client.messages.create({
  model: "claude-opus-4-7",
  max_tokens: 64000,
  thinking: { type: "adaptive" },
  output_config: { effort: "high" },
  messages: [{ role: "user", content: "..." }],
});

要点

• 不再需要用 budget_tokens 直接控制"思考量"
• 改用 output_config.effort 指定"思考的认真程度"
• 完全不加 thinking 字段的话，会不经思考直接响应（与4.6的行为不同，请注意）

5. 破坏性变更2：采样参数废止

给 temperature、top_p、top_k 传非默认值会返回 400错误。这是Anthropic"模型行为应该由提示词决定"理念的彻底落地。

# Before
client.messages.create(
    model="claude-opus-4-6",
    temperature=0.7,
    top_p=0.9,
    top_k=40,
    messages=[...],
)

# After
client.messages.create(
    model="claude-opus-4-7",
    # 完全删除 temperature / top_p / top_k
    messages=[...],
)

以往用 temperature=0.2 追求"尽量稳定的输出"的人，现在应在提示词里写明"对相同问题请尽量给出一致的回答"，或与JSON schema等structured outputs组合使用。

同理，以往用 temperature=1.2 要求"更有创意"的场景，可在提示词里加上"请使用比喻和出人意料的表达"等语气指令。

6. 破坏性变更3：思考内容默认不显示

在4.6中，启用思考后响应流中默认会推送"summarized（摘要版思考）"。很多应用就把它显示为"思考中..."。

在4.7中规格悄悄改变，思考块虽然出现在响应里，但 thinking 字段是空的。除非显式开启，否则看不到内容。

表现

UI上的"正在思考"指示器一直转，答案出现前异常漫长，用户会问"是不是卡住了？"。就是这种情形。

应对

# 想像4.6一样把思考摘要推到UI时
client.messages.create(
    model="claude-opus-4-7",
    thinking={
        "type": "adaptive",
        "display": "summarized",  # 明确指定
    },
    output_config={"effort": "high"},
    messages=[...],
)

await client.messages.create({
  model: "claude-opus-4-7",
  thinking: {
    type: "adaptive",
    display: "summarized",
  },
  output_config: { effort: "high" },
  messages: [...],
});

如果只在后端处理、UI不展示思考，那么不设置 display 也无妨。

7. 破坏性变更4：新分词器（约1.35倍）

Opus 4.7内部采用了新分词器。它有助于性能提升，但 同一文本的token数相较4.6约1.0~1.35倍 的副作用不可忽视。

这会引发什么？

• 原本卡着 max_tokens 设计的流程，可能中途被截断
• 客户端用类似 tiktoken 做的计费或长度校验会失准
• /v1/messages/count_tokens 在4.7和4.6之间结果不同
• 同一提示词的成本和延迟会略有上升

应对

# Before: 按4.6预留了16k tokens的输出缓冲
response = client.messages.create(
    model="claude-opus-4-6",
    max_tokens=16000,
    messages=[...],
)

# After: 按1.35倍预留余量
response = client.messages.create(
    model="claude-opus-4-7",
    max_tokens=22000,  # 16000 * 1.35 ≒ 21600 → 上取整
    messages=[...],
)

另一方面，4.7 以标准API价提供1M上下文窗口（没有长文溢价）。尽管token数会增加，却也让"干脆把所有输入都塞进去"的策略更可行。

8. 破坏性变更5：prefill废止

这是从4.6延续的破坏性变更。assistant消息的prefill——也就是在 messages 数组末尾塞 {role: "assistant", content: "```json"} 来强制"以JSON开头回答"的技巧——会返回400错误。

# Before: 用prefill强制JSON输出
client.messages.create(
    model="claude-opus-4-6",
    messages=[
        {"role": "user", "content": "请以JSON返回用户信息"},
        {"role": "assistant", "content": "```json\n{"},  # prefill
    ],
)

# After: 使用structured outputs
client.messages.create(
    model="claude-opus-4-7",
    output_config={
        "format": {
            "type": "json_schema",
            "schema": {
                "type": "object",
                "properties": {
                    "name": {"type": "string"},
                    "age": {"type": "integer"},
                },
                "required": ["name", "age"],
            },
        },
    },
    messages=[
        {"role": "user", "content": "请以JSON返回用户信息"},
    ],
)

prefill的替代方式有3种。

1. Structured outputs（output_config.format） — 用JSON schema约束输出格式
2. 在 system提示词 中明确写"只返回JSON，不要Markdown或前言"
3. Tool use 以函数调用的方式接收（参数本身就是结构化JSON）

9. 努力等级的选择（xhigh新登场）

output_config.effort 能指定的值分5级。4.7新增 xhigh。

4.6时代手动指定 budget_tokens 的人，在4.7只要选一个effort就够了。经验法则如下。

• 编码智能体（类似Claude Code的场景）从 xhigh 开始
• 问答聊天或RAG响应用 high 稳妥
• 打标签、JSON抽取、分类的轻量worker用 medium 或 low
• max 只在"这道题不计成本往死里想"时使用

10. 行为变化的应对

即使API兼容，模型对提示词的回应方式也与4.6不同。不了解就上生产，用户会说"怎么变冷淡了"。

10.1 回答长度随任务自适应

4.7根据任务复杂度自动调整回答长度。不再有"必须写成3段"这种固定冗长。反过来说，建议先把原有的"长度控制提示词"去掉，看看新行为。

10.2 更字面地理解指令

尤其 effort 较低时更明显。"请简洁回答"它真的会简洁；"列3个"就不会自作主张补第4个。这一特性很好用，但4.6那种"领会意图补足"的行为减少了。

10.3 语气更直接

"真是个好问题！"这样的校验式语句、花哨的表情、开场寒暄都会减少。想保留友好语气，请在system提示词中写明。

10.4 进度更新内置到智能体追踪里

如果你在智能体运维中加了"现在开始做xx"、"正在xx中"之类的脚手架让模型产出进度，4.7会内置输出，可以移除重复的脚手架。

10.5 子智能体与工具调用更收敛

默认子智能体的派生数量、工具调用数量都减少。"能靠推理解决"就不调用工具。请更新智能体设计方对这部分的预期。

10.6 实时网络安全防护

即使是攻击性安全（红队、漏洞PoC等）的正当业务，也可能因上下文被拒绝。若生产用例在安全领域，请考虑申请Anthropic的 Cyber Verification Program。

10.7 高分辨率图像支持

最大2576px的高分辨率图像可以原样处理。但 单张全分辨率图像约消耗3倍的token。在图像密集的工作负载下，(a) 重新分配 max_tokens，或(b) 发送前降采样，二选一。

11. 推荐调整（非必须）

下列内容"不做也能跑，但做了更划算"。

1. 重新评估 max_tokens：新分词器让输出也可能变大，建议把现值按1.2~1.35倍重测
2. 客户端token估算审计：如果自行实现了计费或长度校验，请改用 count_tokens API 或修正系数
3. 引入 task_budgets（beta）：面向智能体。加header task-budgets-2026-03-13，最小20k。注意不是"硬上限"而是"建议性上限"
4. 把 max_tokens 设到64k以上：使用 xhigh/max 时，建议思考 + 输出合计 ≥ 64k
5. 降采样图像：不需要高分辨率时请先缩小尺寸，节省token与成本

11.1 task_budgets的最小示例（官方SDK・Python）

task_budgets 属于beta功能，要使用 client.beta.messages.create 端点，并显式传入 betas 参数。调用方式与正式GA功能不同。

response = client.beta.messages.create(
    model="claude-opus-4-7",
    max_tokens=128000,
    output_config={
        "effort": "high",
        "task_budget": {"type": "tokens", "total": 128000},
    },
    messages=[
        {"role": "user", "content": "Review the codebase and propose a refactor plan."}
    ],
    betas=["task-budgets-2026-03-13"],
)

规格要点：

• 最小值20,000 tokens。低于此值不受理
• max_tokens 是每次请求的硬上限（对模型不可见），task_budget 是智能体循环整体的建议上限（模型知道倒计时）
• 想严控成本用 max_tokens；想兼顾质量与效率用 task_budget
• 质量 > 速度的开放式任务，建议 不设置 task_budget（否则会过早收尾）

12. 从Opus 4.5/4.1以前的迁移

如果跳过4.6，从4.5或4.1直接升到4.7，除了上文的事项，还需要做下面这些。

• 删除采样参数：Claude 3.x以来的老用户往往还在用 temperature，请完全删除
• 清理beta header：effort-2025-11-24、fine-grained-tool-streaming-2025-05-14、interleaved-thinking-2025-05-14 等已并入主线，请删除
• 切换端点：用 client.beta.messages.create 调用的代码改为 client.messages.create
• output_format → output_config.format：键名变化
• 工具参数解析：4.6起JSON转义行为与以往有差异。不要用原始字符串解析，请使用 JSON.parse / json.loads 等正规解析器

关于Claude Opus 4.7本身的新功能，可配合阅读前置文章 Claude Opus 4.7发布：新功能、基准测试与价格。

13. 迁移清单（全部）

为了方便打印给团队，下面把全部条目直接排开。

13.1 必做（不做就会400错误或行为异常）

• ☐ 把模型名 claude-opus-4-6 → claude-opus-4-7 更新
• ☐ 删除 temperature / top_p / top_k
• ☐ 把 thinking: {type: "enabled", budget_tokens: N} 改为 {type: "adaptive"} + output_config.effort
• ☐ 删除assistant消息的prefill，改用structured outputs / system提示词
• ☐ UI中展示思考时，显式设置 thinking.display: "summarized"

13.2 调优（成本与质量优化）

• ☐ 用新分词器重新基准测试成本与延迟
• ☐ 将 max_tokens 按1.35倍重新调整
• ☐ 重新测试客户端的token估算逻辑
• ☐ 发送图像时重新分配高分辨率所需token
• ☐ 使用 xhigh/max 时设置 max_tokens ≥ 64k
• ☐ 智能体场景考虑引入 task_budgets（beta）

13.3 提示词与运维复盘

• ☐ 在真实提示词上确认长度自适应、字面解读、语气变化
• ☐ 删除原有的长度控制提示词，重新取基线
• ☐ 若被安全业务拒绝，申请Cyber Verification Program
• ☐ 简化智能体的脚手架（例如中途进度输出）
• ☐ 从4.5以前迁移时，同时删除beta header并迁移到 client.messages.create

14. 自动迁移工具

如果你在用Claude Code，可以借助Anthropic提供的 Claude API Skill 把机械化的改写自动化。在Claude Code里像下面这样调用Skill即可。

/claude-api migrate

请把整个项目从Claude Opus 4.6迁移到4.7。
- 替换模型名
- 删除 temperature / top_p / top_k
- 把 thinking: enabled 换成 adaptive + effort: high
- 如果还在用prefill，改用structured outputs

Skill会遍历仓库，找出import anthropic SDK的文件，再给出修改建议。但提示词本体的细调和基准测试没法自动化，请务必用清单逐项收尾。

常见问题

本文基于Anthropic官方的Claude Opus 4.7迁移指南（截至2026年4月）撰写。API规格可能变化，正式上线前请以 官方文档 的最新信息为准。