升级 Claude Opus 4.7，最怕的不是旧 prompt 一夜之间全部失效，而是旧系统把关键控制藏在过时参数、旧 token 估算或不够明确的工具策略里。Anthropic 的迁移文档显示，Opus 4.7 延续了 Opus 4.6 的主要平台能力，但迁移时仍要处理 thinking configuration、sampling-parameter removal、task budgets 与 tokenization 等变化。^[15][26]

本文以 Anthropic 明确描述的 Opus 4.6 → Opus 4.7 迁移为基准。如果你是从更早的 Claude 模型升级，可以把这份清单当作回归测试起点，但仍应另外比对原模型版本的差异。^[15]

先判断：你用 Claude 的方式是哪一种？

升级工作量取决于使用方式。手动聊天、文档草稿一类场景，重点通常是常用 prompt 和输出风格的回归测试；API、RAG、Agent、coding 或 vision 工作流，则要更仔细地检查参数、工具策略、token 成本和延迟。^{[1][4][15][26][27]}

使用方式	升级前最该检查
手动聊天、文档草稿、知识工作	常用 prompt、语气、输出格式、引用规则、工具使用规则
Messages API / SDK	model ID、thinking 设置、sampling 参数、token counting、错误处理
Tool use / RAG / web search	何时必须查工具、何时不得猜测、工具失败时如何 fallback
长任务 Agent / coding Agent	effort、task budget、token budget、延迟和回归评测
图片、截图、PDF、computer-use 工作流	图像分辨率、downsample 策略、token 成本、视觉识别质量

1. 先修 breaking change：extended thinking 改为 adaptive thinking

第一步不是重写 prompt，而是扫 API 设置。Anthropic 表示，开发者可以通过 Claude API 使用 claude-opus-4-7；如果你的应用直接指定 model ID，建议先把它纳入小流量测试或 shadow eval，而不是一键全量切换。^[10]

更关键的是 thinking 设置。Anthropic migration guide 明确写到，Claude Opus 4.7 或之后不再支持旧式 extended thinking 的 budget_tokens 设置，并会返回 400 error；迁移方向是改用 adaptive thinking。^[15]

实操上，先做三件事：

• 搜索代码、SDK wrapper、prompt runner 和内部平台配置里的 budget_tokens。
• 移除旧式 extended thinking 设置，改用你所使用 API 或 provider 支持的 adaptive thinking 配置。^[15]
• 不要再把固定 thinking token budget 当成主要控制器；改用文档支持的 effort、task budget、prompt 约束和 eval 来校准任务深度。^[26][27]

Anthropic 的 prompting best practices 也把 effort levels、task budgets、thinking configuration、sampling-parameter removal 和 tokenization 列为从 Opus 4.6 迁移到 Opus 4.7 时需要关注的 API 变化。^[26]

2. 把 sampling 参数的控制迁回 prompt 和 eval

如果旧工作流依赖 temperature、top_p 或 top_k 来控制创意度、稳定性或输出差异，升级时要重新设计控制方式。Anthropic 的 prompting 文档把 sampling-parameter removal 列入 Opus 4.7 迁移注意事项；OpenRouter 的 Claude 4.7 migration guide 也列出 sampling parameters removed、adaptive-only thinking 与 provider-specific effort 行为。^[26][14]

这会影响三类常见任务：

• 创意写作、广告文案：过去可能靠更高 sampling 获得更发散的版本。
• 客服、合规、资料抽取：过去可能靠更低 sampling 追求稳定输出。
• 批量生成：过去可能用 sampling 参数控制多样性。

升级后，更稳的做法是把规则写进 prompt 和 eval：明确语气、格式、禁止事项与成功标准；用 few-shot 示例固定输出风格；对抽取、分类、报告生成使用结构化输出要求；把旧版 Claude 的 golden examples 做成回归评测，逐题比较 Opus 4.7 的格式遵循、正确率、成本和延迟。^[26]

3. Tool use：把“什么时候查工具”写成明确 policy

如果旧工作流只是给 Claude 一个宽泛目标，让模型自行判断何时查工具，升级时最值得补强的是 tool policy。Anthropic 的 prompting best practices 指出，Claude 最新模型受训于精确遵循指令，并且会受益于明确要求使用特定工具；同一份文件也建议将 adaptive thinking 用于 multi-step tool use、complex coding tasks 和 long-horizon agent loops 等 Agentic workload。^[1]

可以把这类规则直接写进 system prompt 或工作流 policy：

• 涉及实时信息、价格、政策、版本差异或外部文档时，必须先使用指定查询工具。
• 内部知识库没有答案时，必须说明无法确认，不得猜测。
• 工具结果彼此矛盾时，先列出冲突，再给出保守结论。
• 最终答案要区分哪些信息来自工具结果，哪些是模型推理。

这通常比单纯替换 model ID 更重要。tool policy 会直接影响 Agent 是否漏查资料、是否在证据不足时编造答案，以及在工具结果冲突时是否过度自信。^[1]

4. 长任务 Agent：用 effort 和 task budget 管成本

Opus 4.7 的一个迁移重点，是长任务与 Agentic 工作流的预算控制。Anthropic 的 What’s new 文件指出，Opus 4.7 introduces task budgets；官方文档也说明，effort 参数可在能力、速度和 token spend 之间取舍，task budget 则让 Claude 对整个任务可用 token 有一个大致估计。^[4][27]

如果你的工作流是 coding Agent、research Agent、browser Agent、长时间数据处理或多工具 loop，建议把预算拆成三层：

• 单次回复预算：最终输出最多可以用多少 token。
• 推理与工具预算：多步骤任务中，模型可以投入多少 reasoning、tool calls 和 tool results。
• 任务级预算：整段 Agent loop 的成本与延迟上限。

不要只用最终输出上限来估算整段 Agent loop 的成本。长任务的开销可能来自多次工具查询、工具结果回灌、图片或 PDF 解析、重试与最终输出；Opus 4.7 的 task budgets 和新 tokenizer 都意味着这部分需要重新 benchmark。^[4][27]

5. Token、RAG、缓存和 batch：全部重跑 benchmark

这是最容易被低估的迁移项。Anthropic 文档指出，Opus 4.7 的新 tokenizer 在处理文本时，可能会比前代模型使用约 1x 到 1.35x 的 token；/v1/messages/count_tokens 对 Opus 4.7 返回的 token count 也会不同于 Opus 4.6，Anthropic 建议用该 endpoint 重新估算。^[4]

升级前建议重测：

• RAG chunk size 和 overlap。
• 长文档截断阈值。
• conversation memory 长度。
• prompt caching 命中率与成本预估。
• batch job 的成本上限。
• Agent 每轮工具结果可回灌的大小。
• 图片与 PDF 的预处理策略。

如果旧工作流已经接近成本上限或 context limit，不要直接沿用旧版 token 估算。先用核心 prompt、长文档样本和高流量任务跑 token benchmark，再决定是否调整 chunking、截断规则或 cache key 设计。^[4]

6. 图片、截图和 PDF：重新设定预处理规则

Opus 4.7 文档提到 high-resolution image support；官方文档也提醒，如果不需要额外图像保真度，应在送入 Claude 前先 downsample，以避免 token 使用增加。^[4][27]

这会影响三类工作流：

• 截图理解：例如 UI QA、表格截图、dashboard 分析。
• 文档图像处理：例如扫描 PDF、合同截图、演示文稿页面。
• computer-use / browser automation：例如模型需要理解画面位置、按钮、表单和错误信息。

从 Opus 4.6 升级时，PDF 和 vision 能力本身仍属于 Anthropic 列出的同一组主要平台能力；真正要重测的是送多大的图片、是否需要高分辨率，以及 downsample 后关键文字和 UI 元件是否仍能识别。^[15][27]

7. Provider 或内部 gateway：不要假设参数映射完全一致

如果你不是直接调用 Anthropic API，而是通过 OpenRouter、云平台或内部 gateway 调用 Claude，不能假设字段名、忽略规则和 effort 行为完全相同。OpenRouter 的 Claude 4.7 migration guide 就单独列出 sampling parameters removed、adaptive-only thinking 与 provider-specific effort 行为。^[14]

因此，除了 Anthropic 文档，也要查你实际 provider 的 migration note。尤其是多模型 router、fallback gateway、内部 prompt 平台，常会把上游 API 参数封装成自己的字段；升级时应确认哪些字段仍有效、哪些会被忽略、哪些会直接报错。^[14]

哪些地方通常不用大改？

如果你是从 Opus 4.6 升到 Opus 4.7，平台能力并不是全部推倒重来。Anthropic migration guide 表示，Opus 4.7 支持与 Opus 4.6 相同的主要功能集合，包括 1M token context window、128k max output tokens、adaptive thinking、prompt caching、batch processing、Files API、PDF support、vision，以及完整的 server-side / client-side tools。^[15]

也就是说，第一优先级通常不是重写这些基础设施：

• Files API 与文件上传流程。
• PDF / vision 能力是否存在。
• prompt caching 或 batch processing 是否可用。
• 工具调用能力本身。
• 长 context 能力本身。

真正要重新校准的是你如何控制这些能力：何时用工具、花多少 token、用多高 effort、图片送多大，以及失败时如何 fallback。^{[1][4][15][27]}

实际迁移 checklist

可以把下面这份清单交给工程团队、AI platform owner 或负责 Claude 工作流的同事，用来快速找出高风险点。

API 与参数

• 将模型名称切换到 claude-opus-4-7，并先做小流量或 shadow eval；Anthropic 表示开发者可通过 Claude API 使用这个 model ID。^[10]
• 搜索 thinking、budget_tokens 和旧式 extended thinking wrapper，改成 adaptive thinking；Opus 4.7 或之后不支持旧式设置，会返回 400。^[15]
• 搜索 temperature、top_p、top_k 等 sampling 控制，改用 prompt、few-shot、schema 和 eval 管理稳定性。^[26]
• 如果通过 OpenRouter 或其他代理层使用 Claude，另查该 provider 的 Claude 4.7 migration guide 与参数映射。^[14]

Prompt 与 tool use

• 把何时必须用工具写进 system prompt；Anthropic 文档指出，最新 Claude 模型受益于明确的 tool-use 指示。^[1]
• 把何时不能猜答案、资料不足时如何回答写清楚。
• 把工具结果冲突、工具失败、外部资料不足时的 fallback 行为写清楚。
• 对资料抽取、分类、报告生成等工作流加入结构化输出格式。

Agent 与 coding 工作流

• 对 coding Agent、research Agent、browser Agent 重新校准 effort 与任务预算；Anthropic 文档将 adaptive thinking 与 multi-step tool use、complex coding tasks、long-horizon agent loops 放在一起讨论。^[1]
• 评估是否使用 task budgets；Opus 4.7 文档列出 task budgets，并提醒 token counting 与前代不同。^[4]
• 不要只用最终输出上限估算整段 Agent loop 成本；把工具调用、工具结果、重试和最终输出都纳入成本模型。^[4][27]
• 用旧版 Claude 的成功案例建立 regression eval，比较 Opus 4.7 的成功率、格式遵循、延迟和成本。

Token、文档与图像

• 用 /v1/messages/count_tokens 重新估算核心 prompt、RAG chunks、长文档与批量任务成本。^[4]
• 重测 chunk size、截断阈值、conversation memory 和 prompt caching 策略。^[4]
• 对图片、截图和 PDF 页面建立 downsample policy；不需要高保真时先降低分辨率，以控制 token 使用。^[27]

建议升级顺序

更稳的升级方式不是一次性全面替换，而是分四步推进：

1. 静态扫描：找出 model ID、thinking、sampling、token counting、image preprocessing 和 provider-specific 参数。
2. 小流量 eval：用既有 golden set 比较旧版 Claude 与 Opus 4.7 的输出质量、格式遵循、tool use、成本和延迟。
3. 重写高风险 prompt：优先处理 tool use、RAG、coding Agent、资料抽取和合规任务。
4. 逐步放量：监控 token 使用、工具调用次数、错误率、延迟和人工反馈。

一句话总结：从旧版 Claude 迁移到 Opus 4.7，核心不是把 prompt 全部重写，而是把旧工作流里隐含的控制逻辑显性化。thinking 改 adaptive，sampling 改 prompt/eval，长任务改预算驱动，图片与 token 成本重新 benchmark；这样升级风险最低，也最能保留旧工作流的可控性。