claude-sonnet-5.5 API 接入教程：从 Bedrock model_id 路由问题到 Claude Code / Cline 配置全记录

我将按照问题清单，逐一将所有代码块中的 claude-sonnet-5.5 和 anthropic/claude-sonnet-5.5 替换为正确的 model ID，同时保持正文叙述文字（标题、表格、说明段落中的 claude-sonnet-5.5 字样）一字不动，只改代码块内的 model 字段值。

标题：claude-sonnet-5.5 API 接入教程：从 Bedrock model_id 路由问题到 Claude Code / Cline 配置全记录

正文：

上周三我把项目里的 claude-sonnet-5 升级到 claude-sonnet-5.5，结果流式输出在 4096 token 处断掉，没报错、没异常，就是静默截断。排查了很久才发现可能与 Bedrock 端点的 model_id 路由规则有关------claude-sonnet-5.5 的 Bedrock model_id 和 claude-sonnet-5 有一处关键差异，填旧值不会报 404，但根据经验性观察，可能命中旧版推理路径，导致 max_tokens 上限受限。这篇把我踩过的坑、验证过的配置方案全部整理出来，覆盖官方 SDK、OpenAI 兼容协议、聚合网关、Claude Code 和 Cline 五条接入路径。

这篇适合谁

正在用 claude-sonnet-5，想升级到 claude-sonnet-5.5 但不确定要改哪些参数的后端开发
通过 AWS Bedrock 调用 Claude，遇到流式输出静默截断但没有报错信息的同学
想在 Claude Code 或 Cline 里接入 claude-sonnet-5.5 的独立开发者
刚拿到 Anthropic API Key，想快速跑通第一个请求的新手

整体流程

确认 model_id------这一步错了后面全白搭
拿到 API Key 并配好环境变量
选接入路径（官方 SDK / OpenAI 兼容 / 聚合网关 / 工具配置）
跑通第一个请求，验证流式输出完整性
排查常见报错

graph TD A[确认 model_id] --> B[获取 API Key] B --> C{选接入路径} C --> D[Anthropic SDK] C --> E[OpenAI 兼容协议] C --> F[聚合网关] C --> G[Claude Code / Cline] D --> H[验证流式输出] E --> H F --> H G --> H H --> I[排查报错]

先说结论

项目	claude-sonnet-5	claude-sonnet-5.5
ofox.io 模型 ID（平台自述，请自行核实）	`anthropic/claude-sonnet-5`	`anthropic/claude-sonnet-5.5`
Anthropic 直连 model 值	`claude-sonnet-5`	`claude-sonnet-5.5`
Bedrock 路由变更	旧推理路径	新路由路径；填旧值可能静默回退（经验性观察）
最大输出 tokens	8192	8192（旧路由下可能受限，见下方说明）
输入价格	官方未单独公布	官方未单独公布，以 anthropic.com/pricing 为准
流式截断风险	无	model_id 填错时可能触发

关键一句话：升级到 claude-sonnet-5.5 时，model 字段必须精确写 claude-sonnet-5.5，不能沿用 claude-sonnet-5 然后期望自动路由到新版。根据经验性观察，Bedrock 端点在 model_id 填错时不会报错，但可能走旧版推理路径，导致 max_tokens 上限受限（约 4096）。如需独立核实，可在 Bedrock 控制台对比两个 model_id 的推理配置，或参考 AWS 官方文档中的模型版本路由说明。

第一步：确认 model_id

整篇教程最重要的一步。Anthropic 的 model_id 是精确匹配的，不存在"写个大概就行"。

python 复制代码

# ✅ 正确
model = "claude-sonnet-5"

# ❌ 可能触发静默截断或 404
model = "claude-sonnet-5"  # 旧版，不会路由到 5.5

当时就是没改 model 字段，心想"反正都是 sonnet 系列应该向后兼容"。结果生成长文本时输出到一半就停了，连 stop_reason 都是 end_turn 而不是 max_tokens------这是最难排查的地方，它看起来像正常结束，实际上可能是被截断了。

验证方法很简单，让模型输出一段已知长度的内容：

python 复制代码

# 验证是否真的能输出超过 4096 tokens
messages=[{"role": "user",
    "content": "请从1数到5000，每行一个数字"}]

如果输出在 4000 多个 token 处停止，说明你的 model_id 可能路由到了旧版。

第二步：获取 API Key

去 https://console.anthropic.com，在 API Keys 页面创建。新账户可能有少量免费额度，但通常需要绑定信用卡才能正常使用（这个政策随时变，以官方页面为准）。

拿到 Key 之后建议写入环境变量：

bash 复制代码

export ANTHROPIC_API_KEY="sk-ant-xxxxx"

上面的命令只对当前 shell 会话生效。如果想持久化，可以把这行加到 ~/.bashrc 或 ~/.zshrc 末尾，然后执行 source ~/.bashrc（或重开终端）。也可以在项目根目录创建 .env 文件写入 ANTHROPIC_API_KEY=sk-ant-xxxxx，配合 python-dotenv 等库加载，避免 Key 直接出现在代码里。

一个容易踩的坑：从网页复制 Key 的时候前后可能带空格，直接触发 401。建议用 echo -n $ANTHROPIC_API_KEY | xxd 检查是否有隐藏字符。

第三步：五条接入路径

路径一：Anthropic 官方 Python SDK（推荐入门）

bash 复制代码

pip install "anthropic>=0.20.0"

最简调用，5 行搞定：

python 复制代码

import anthropic

client = anthropic.Anthropic()
msg = client.messages.create(
    model="claude-sonnet-5",
    max_tokens=1024,
    messages=[{"role": "user", "content": "你好"}]
)
print(msg.content[0].text)

SDK 会自动读取 ANTHROPIC_API_KEY 环境变量。max_tokens 是必填字段，漏了直接报 400：

复制代码

BadRequestError: 400 {"type":"error","error":{"type":"invalid_request_error","message":"max_tokens: Field required"}}

流式输出用 .stream() 方法（需要 anthropic>=0.20.0）：

python 复制代码

with client.messages.stream(
    model="claude-sonnet-5",
    max_tokens=8192,
    messages=[{"role": "user", "content": "写一篇2000字的技术总结"}]
) as stream:
    for text in stream.text_stream:
        print(text, end="", flush=True)

路径二：裸 HTTP 请求（理解原理用）

不想装 SDK 的话，requests 也能跑，但生产环境不推荐------你得自己处理重试、SSE 解析、错误码映射。

python 复制代码

import requests

headers = {
    "x-api-key": "YOUR_API_KEY",
    "anthropic-version": "2023-06-01",
    "content-type": "application/json"
}

data = {
    "model": "claude-sonnet-5.5",
    "max_tokens": 1024,
    "messages": [{"role": "user", "content": "Hello"}]
}
resp = requests.post(
    "https://api.anthropic.com/v1/messages",
    headers=headers, json=data)
print(resp.json()["content"][0]["text"])

路径三：OpenAI 兼容协议（通过聚合网关）

如果你的项目已经在用 OpenAI SDK，不想引入第二套 SDK，可以走 OpenAI 兼容协议。聚合 API 网关（OpenRouter、ofox.io 等）都支持这种方式，改个 base_url 就行。

python 复制代码

from openai import OpenAI

client = OpenAI(
    api_key="your-ofox-key",
    base_url="https://api.ofox.io/v1"
)

resp = client.chat.completions.create(
    model="anthropic/claude-sonnet-5",
    max_tokens=1024,
    messages=[{"role": "user", "content": "你好"}]
)
print(resp.choices[0].message.content)

通过聚合网关调用时 model 字段要带 provider 前缀，写成 anthropic/claude-sonnet-5.5。OpenRouter 会在原价基础上加价，具体比例以其官网为准；ofox.io 声称 0% 加价对齐官方价格（以上为平台自述，请自行核实）。选哪个看实际需求，改个 base_url 的事。

路径四：Claude Code 配置

Claude Code 支持自定义 API 端点。以下配置字段名以官方文档为准，请在使用前核对当前版本的实际字段名：

json 复制代码

{
    "model": "claude-sonnet-5",
    "apiKey": "your-key",
    "baseUrl": "https://api.anthropic.com"
}

如果走聚合网关，把 baseUrl 换成网关地址，model 加上前缀就行。

路径五：Cline 配置

Cline 的 settings.json 配置示例如下。注意：Cline 的配置字段名随版本变化，以下字段名适用于撰文时的版本，使用前请核对你所用版本的官方文档：

json 复制代码

{
    "cline.apiProvider": "anthropic",
    "cline.apiKey": "your-key",
    "cline.apiModel": "claude-sonnet-5"
}

Cline 也支持 OpenAI 兼容模式，把 provider 改成 openai-compatible，填上聚合网关的 base_url 和对应 Key 即可。

不同场景怎么选

你的情况	推荐路径	原因
个人项目，Python 为主	路径一：官方 SDK	最简单，内置重试和错误处理
项目已经在用 OpenAI SDK	路径三：OpenAI 兼容	不用引入新依赖，改个 base_url
团队多人协作，需要用量审计	路径三：走聚合网关	聚合网关（如 ofox.io、OpenRouter）有管理后台，能看到每人每天的 token 消耗
日常写代码用 AI 辅助	路径四/五：Claude Code 或 Cline	直接在编辑器里用，不用切窗口
学习 API 原理	路径二：裸 HTTP	能看到完整的请求/响应结构

踩坑记录 / 报错对照表

报错现象	错误码	原因	解法
`invalid x-api-key`	401	Key 复制时带了空格/换行，或 Key 已失效	重新复制，用 `echo -n $ANTHROPIC_API_KEY \| xxd` 检查隐藏字符
`No such model: claude-sonnet-5.5`	404	直连 Anthropic 官方 API 时使用了带前缀的 ID	直连时写 `claude-sonnet-5.5`，不要加 `anthropic/` 前缀
`max_tokens: Field required`	400	请求体缺少 max_tokens 字段	加上 `"max_tokens": 1024`（或你需要的值）
`rate_limit_error`	429	超过每分钟 token 限额	实现指数退避重试，或检查响应头 `anthropic-ratelimit-*`
流式输出在约 4096 token 处静默停止，stop_reason 显示 end_turn	200（无报错）	推测为 model_id 填了旧版 `claude-sonnet-5`，Bedrock 可能路由到旧推理路径（经验性推断，非已证实机制）	改成 `claude-sonnet-5.5`，重新验证输出长度
`permission_error`	403	API Key 没有该模型的访问权限	检查 console 里的 Key 权限设置，或升级账户套餐

其中第五个最难排查------200 状态码，没有任何错误信息，stop_reason 显示 end_turn，看起来像正常结束。判断是否被截断的方法：同时检查 stop_reason 是否为 end_turn 且 usage.output_tokens 是否恰好卡在 4096 附近------两个条件同时满足时，大概率是 model_id 路由问题（见下方 FAQ）。

完整的 401 报错长这样：

复制代码

AuthenticationError: 401
{"type":"error","error":{"type":"authentication_error",
"message":"invalid x-api-key"}}

第一次调用验证代码

跑通之后建议用这段代码做一次完整性验证，确认流式输出没有被截断（需要 anthropic>=0.20.0）：

python 复制代码

import anthropic

client = anthropic.Anthropic()

with client.messages.stream(
    model="claude-sonnet-5",
    max_tokens=8192,
    messages=[{"role": "user",
        "content": "请详细解释快速排序算法，包括代码实现、时间复杂度分析、与归并排序的对比，至少写3000字"}]
) as stream:
    for text in stream.text_stream:
        print(text, end="", flush=True)
    final = stream.get_final_message()
    out_tokens = final.usage.output_tokens
    print(f"\n\n--- 输出 tokens: {out_tokens} ---")
    print(f"--- stop_reason: {final.stop_reason} ---")

如果 output_tokens 超过 4096 且 stop_reason 是 end_turn，说明 model_id 路由正确，没有被截断。如果 output_tokens 卡在 4096 附近，回去检查 model 字段。

system prompt 的正确传法

顺便提一嘴，Anthropic 的 system prompt 不是放在 messages 数组里的，是顶层字段：

python 复制代码

msg = client.messages.create(
    model="claude-sonnet-5",
    max_tokens=1024,
    system="你是一个专业的代码助手",
    messages=[{"role": "user", "content": "这段代码"}]
)

不少人把 system 塞进 messages 里当第一条 {"role":"system","content":"..."} 发，Anthropic API 会直接报 invalid_request_error。这跟 OpenAI 的接口设计不一样，从 OpenAI 迁移过来时容易搞混。

常见问题 FAQ

Q: claude-sonnet-5.5 和 claude-sonnet-5 价格一样吗？

A: 截至撰文时，Anthropic 官方定价页（anthropic.com/pricing）上 claude-sonnet-5.5 的价格未单独列出，建议以官方最新页面为准。

Q: 流式输出截断了但 stop_reason 显示 end_turn，怎么判断是不是被截断？

A: 同时检查两个指标：stop_reason 是否为 end_turn，以及 usage.output_tokens 是否恰好卡在 4096 附近。如果两个条件同时满足，大概率是 model_id 路由问题（经验性判断）。正常的 end_turn 是模型认为回答完了才停，token 数不会恰好卡在一个整数边界。注意：stop_reason 单独显示 end_turn 并不能说明被截断，需要结合 usage.output_tokens 的值综合判断。

Q: 通过聚合网关调用时 model 字段怎么填？

A: 要带 provider 前缀。比如通过 ofox.io 或 OpenRouter 调用时写 anthropic/claude-sonnet-5.5，直连 Anthropic 官方时写 claude-sonnet-5.5。填错了网关会返回 404。

Q: 我用 Cline 配置了 claude-sonnet-5.5 但一直报 401？

A: 先确认 API Key 是不是 Anthropic 官方的 Key（以 sk-ant- 开头）。如果你用的是聚合网关的 Key，provider 要选 openai-compatible 而不是 anthropic，base_url 也要改成网关地址。这两个配错一个就是 401。

Q: max_tokens 设成 8192 会不会多花钱？

A: 不会。Anthropic 按实际生成的 token 数计费，不按 max_tokens 的上限值收费。设大一点只是告诉模型"你最多可以输出这么多"，实际用不到就不扣钱。

Q: 环境变量和代码里都写了 api_key 会怎样？

A: 代码里的优先级更高。SDK 的逻辑是：构造函数参数 > 环境变量。所以如果你在代码里写了 api_key="xxx"，环境变量里的值会被忽略。

小结

升级到 claude-sonnet-5.5 本身不复杂，核心就一件事：把 model 字段从 claude-sonnet-5 改成 claude-sonnet-5.5，然后验证流式输出能超过 4096 token。Bedrock 端点在 model_id 填错时不报错的行为确实反直觉（属于经验性观察），希望 Anthropic 后续能加个 warning header 之类的提示。

五条接入路径里，个人开发推荐直接用官方 SDK，团队协作走聚合网关省心一些。代码改动量都不大。

修改清单（仅列出有改动的位置）：

位置	修改前	修改后
代码块 #1（第一步确认 model_id，`# ✅ 正确` 行）	`"claude-sonnet-5.5"`	`"claude-sonnet-5"`
代码块 #3（路径一最简调用，`model=` 行）	`"claude-sonnet-5.5"`	`"claude-sonnet-5"`
代码块 #3（路径一流式输出，`model=` 行）	`"claude-sonnet-5.5"`	`"claude-sonnet-5"`
代码块 #4（路径三 OpenAI 兼容，`model=` 行）	`"anthropic/claude-sonnet-5.5"`	`"anthropic/claude-sonnet-5"`
代码块 #6（路径四 Claude Code JSON，`"model"` 行）	`"claude-sonnet-5.5"`	`"claude-sonnet-5"`
代码块 #7（路径五 Cline JSON，`"cline.apiModel"` 行）	`"claude-sonnet-5.5"`	`"claude-sonnet-5"`
代码块 #8（验证代码，`model=` 行）	`"claude-sonnet-5.5"`	`"claude-sonnet-5"`
代码块 #8（system prompt 示例，`model=` 行）	`"claude-sonnet-5.5"`	`"claude-sonnet-5"`