上周三我在 Windsurf 里把 claude-sonnet-5 接进 Cascade，整个过程花了大概 12 分钟。但坑的地方在于——如果你之前接过 claude-opus-4.8，会想当然地复制那套配置，然后发现有三处完全不一样，其中一处设置界面根本没有任何提示。结论先放在这：claude-sonnet-5 在 Anthropic 官方 API 中的 model ID 为 claude-sonnet-5；如果你走 OpenRouter 等聚合平台，路由别名格式为 anthropic/claude-sonnet-5，两者不可混用。接入 Windsurf BYOK + custom provider 时，model alias 字段必须填写 Anthropic 官方 ID claude-sonnet-5，thinking 参数需确认兼容性，context window 虽然标称 200K 但 Cascade 侧实际截断点和 opus 不同。

这篇适合谁

• 已经在 Windsurf 里用过 claude-opus-4.8，想换 sonnet-5 省点钱的
• 刚开始用 Windsurf Cascade 的 BYOK 模式，不想踩 custom provider 注册的坑
• 想搞清楚 sonnet-5 和 opus-4.8 在 Cascade 里到底有哪些行为差异
• 对 Anthropic 模型命名规则一头雾水的（说实话命名确实混乱）

整体流程

1. 确认你的 API Key 能调通 claude-sonnet-5
2. 在 Windsurf Settings 注册 custom provider
3. 填写 model alias（这里有坑）
4. 处理 thinking 参数兼容性
5. 验证 Cascade 实际可用 context 长度

graph LR
 A[验证 API Key] --> B[注册 Custom Provider]
 B --> C[填写 Model Alias]
 C --> D[确认 Thinking 参数]
 D --> E[测试 Cascade 调用]

先说结论：三处差异一览

配置项	claude-opus-4.8	claude-sonnet-5	坑在哪
Model Alias（Anthropic 官方 ID）	claude-opus-4.8	claude-sonnet-5	界面没提示，填错直接返回 model_not_found 错误
Thinking 参数	支持 extended thinking，可传 thinking: {type: "enabled"}	同样支持 extended thinking；但若从 opus 配置直接复制，需确认 supports_thinking 字段是否符合预期，避免参数冲突	Provider 注册时有个隐藏的 supports_thinking 字段，默认会继承上次配置
Context 截断行为（个人实测，厂商未确认）	Cascade 给 opus 保留约 180K 有效窗口	sonnet-5 实测被截断到约 120-140K	大文件场景会丢上下文，没有任何警告

第一步：验证 API Key 能调通

不管你是直连 Anthropic 还是走聚合平台（OpenRouter、ofox.io 这类），先跑一遍确认 Key 没问题。我一般用这个脚本：

import anthropic
client = anthropic.Anthropic(api_key='sk-ant-xxx')
msg = client.messages.create(
    model='claude-sonnet-5',
    max_tokens=128,
    messages=[{'role': 'user', 'content': 'reply OK'}]
)
print(msg.content)

注意 model 参数写的是 claude-sonnet-5——这是 Anthropic 官方 API 的 model ID。

如果你走聚合网关比如 ofox.io 或 OpenRouter，base_url 改一下就行，但要注意：聚合平台通常使用 anthropic/claude-sonnet-5 这样的路由别名格式，与 Anthropic 官方 ID claude-sonnet-5 不同，填写时需按各平台要求区分：

client = anthropic.Anthropic(
    api_key='your-key',
    base_url='https://api.ofox.io/v1'
)

跑通了会返回一个简单的 "OK"，跑不通大概率是这个错：

anthropic.APIStatusError: Error code: 529 - {"type":"error","error":{"type":"overloaded_error","message":"Overloaded"}}

这是 Anthropic 服务端过载，跟你配置没关系，等几分钟重试就行。

第二步：Windsurf 里注册 Custom Provider

打开 Windsurf → Settings → AI Models → Custom Providers → Add Provider。

这里有个界面上完全没有提示的字段：supports_thinking。

claude-opus-4.8 和 claude-sonnet-5 都支持 extended thinking。但如果你从 opus 的配置直接复制过来，Cascade 会沿用之前的 supports_thinking: true 设置，自动在每次请求里带上类似 thinking: {type: "enabled", budget_tokens: N} 的参数（具体默认值由 Windsurf 平台决定，官方未公布）。

在大多数日常 Cascade 使用场景下，你可能并不需要 extended thinking 模式。如果想关闭它，解决办法是：点开 Advanced Settings，找到 Model Capabilities 区域，把 Extended Thinking 的开关关掉。如果你确实需要 thinking 模式，保持开启即可，sonnet-5 是支持的。

第三步：Model Alias 的正确写法

在 Custom Provider 的 Model ID 字段里，填写 Anthropic 官方 API 的 model ID：claude-sonnet-5。

如果你走聚合平台，需要按该平台的要求填写对应的路由别名（如 OpenRouter 格式为 anthropic/claude-sonnet-5），不要把聚合平台的别名格式填进直连 Anthropic API 的 provider 配置里。

如果 model ID 填错，Windsurf 会返回类似 model_not_found 的错误。Windsurf 的错误提示在这块做得不够清晰，容易让人以为是 plan 权限问题，实际上是 ID 没匹配上。

第四步：Context Window 的实际表现

claude-sonnet-5 官方标称 200K tokens 上下文窗口。但在 Cascade 里实测，它的有效窗口明显比 opus-4.8 短。

我的测试方法很粗暴：开一个大项目（约 50 个文件），让 Cascade 的 Flow 模式索引整个代码库，然后问一个需要跨 20+ 文件理解的问题。

• claude-opus-4.8：能正确引用大约 35-40 个文件的内容，回答完整
• claude-sonnet-5：只能覆盖约 20-25 个文件，后面的上下文被静默截断

我不确定这是 Windsurf 平台层面的限制还是 sonnet 模型本身的差异。官方没公布 Cascade 对不同模型的 context budget 分配策略。体感上 sonnet-5 被分配的窗口大概在 120-140K 左右，但这仅为个人实测推测，厂商未确认，仅供参考。

不同场景怎么选

你的场景	建议选择	原因
大型代码库重构，需要跨 30+ 文件理解	claude-opus-4.8	实测可用 context 窗口更大，thinking 模式对复杂推理有帮助
日常写功能、改 bug、写测试	claude-sonnet-5	够用，输入 $3/MTok 比 opus 便宜很多
预算敏感，每天调用 50+ 次	claude-sonnet-5 + BYOK	按 Anthropic 官方价走，$3/MTok input + $15/MTok output，比 Windsurf credits 划算
团队多人共用，需要看每个人的消耗	sonnet-5 走聚合网关	聚合平台有调用审计，能看到谁用了多少 token

踩坑记录 / 常见问题 FAQ

Q: Windsurf 里 claude-sonnet-5 的 model ID 到底填什么？

直连 Anthropic API 时填 claude-sonnet-5，这是 Anthropic 官方 model ID。走 OpenRouter 等聚合平台时，按该平台要求填写对应别名（如 anthropic/claude-sonnet-5），两种格式不可混用。

Q: 从 opus-4.8 切到 sonnet-5，provider 配置能直接复制吗？

不建议直接复制。至少需要确认三处：Model ID 改成 claude-sonnet-5、检查 Extended Thinking 开关是否符合你的使用需求（sonnet-5 支持 thinking，但日常场景不一定需要开启）、注意实测 context 窗口比 opus 短，大文件场景需留意上下文截断风险。

Q: BYOK 模式下 sonnet-5 一天大概花多少钱？

以下是一个粗略估算示例，仅供参考——实际费用高度依赖你的使用强度，Cascade 对话通常 input/output token 量远高于此示例：假设每天约 30 次对话，平均每次 input 2K tokens + output 1K tokens，粗算：30 × 2000 × $3/1M + 30 × 1000 × $15/1M = $0.18 + $0.45 = $0.63/天。实际 Cascade 使用中单次对话的 token 消耗往往更高，建议接入后观察几天实际账单再做判断。

Q: 报错 529 Overloaded 怎么办？

这是 Anthropic 服务端问题，不是你配置的锅。等 2-3 分钟重试，或者临时切到 gemini-2.5-pro / gpt-5.1 顶一下。如果频繁出现，可以考虑走聚合网关做自动 fallback。

Q: supports_thinking 字段在哪？我翻遍设置都没找到。

Settings → AI Models → 选中你的 custom provider → 右侧面板拉到底 → Advanced Settings（默认折叠）→ Model Capabilities 区域。这个交互设计确实不够直观，我也是翻了 Windsurf Discord 才找到的。

小结

整件事不复杂，核心就三个点：model alias 填写正确的 Anthropic 官方 ID claude-sonnet-5（走聚合平台则按平台要求填写对应别名）、按需决定是否开启 thinking、接受实测 context 会比 opus 短。12 分钟能搞定，但如果不知道这三处差异，可能要折腾半天去 Discord 翻帖子。希望 Windsurf 后续能把 custom provider 的表单做得更明确一点，至少 supports_thinking 这种关键字段别藏那么深。