迁移指南

从 OpenAI 迁移到 Anthropic Claude 时，重点不是简单替换模型名，而是调整接口路径、鉴权头、系统提示词位置、消息内容结构和工具调用处理流程。

从 OpenAI 迁移到 Anthropic

OpenAI 兼容接口通常使用 Authorization: Bearer，Claude Messages API 使用 x-api-key 和 anthropic-version。

OpenAI	Anthropic Claude
Authorization: Bearer	x-api-key
/v1/chat/completions	/v1/messages
messages[].role = system	顶层 system
max_tokens 可选或有默认策略	通常显式设置
tools	tools
tool_calls	tool_use

Chat Completions 与 Messages API 差异

OpenAI Chat Completions 和 Claude Messages API 都使用消息数组表达对话，但字段细节不同。

{
  "model": "claude-sonnet-4-5",
  "max_tokens": 1024,
  "messages": [
    {
      "role": "user",
      "content": "Introduce Claude"
    }
  ]
}

system 参数差异

OpenAI Chat Completions 常把系统提示词作为 messages 中的 system 角色。Claude 使用顶层 system 字段。

OpenAI：

{
  "messages": [
    { "role": "system", "content": "You are a customer support assistant" },
    { "role": "user", "content": "Draft a reply for me" }
  ]
}

Anthropic Claude：

{
  "system": "You are a customer support assistant",
  "messages": [
    { "role": "user", "content": "Draft a reply for me" }
  ]
}

messages 格式差异

Claude 的 content 可以是字符串，也可以是内容块数组。图像、文本、工具结果等多模态内容通常使用内容块数组。

{
  "role": "user",
  "content": [
    {
      "type": "text",
      "text": "Analyze the following content"
    }
  ]
}

max_tokens 差异

Claude 请求通常应显式设置 max_tokens。迁移时需要根据原系统输出长度重新设置，避免回复过短或成本失控。

工具调用差异

OpenAI 常见返回字段是 tool_calls。Claude 返回内容块中的 tool_use，服务端执行后把结果作为 tool_result 返回。

迁移时需要检查：

• 工具定义字段名
• 参数 schema
• 工具调用 ID 的传递
• 工具结果如何回填
• 多工具并发或顺序调用逻辑

流式输出差异

两者都支持流式输出，但事件结构不同。前端如果已经适配 OpenAI 的流式事件，迁移时需要重新处理 Claude 的事件类型和增量内容。

建议把流式解析封装在服务端，前端只接收统一格式，例如：

{ "type": "delta", "text": "New text" }

错误码差异

迁移时不要只按旧错误文本判断失败原因，应统一记录：

• HTTP 状态码
• 响应 body
• 请求 ID
• 模型名
• 上游供应商
• 重试次数

迁移检查清单

• 请求地址是否改为 https://xikapi.com/v1/messages
• 鉴权头是否改为 x-api-key
• 是否加入 anthropic-version
• system 是否移到顶层
• 是否显式设置 max_tokens
• 多模态内容是否改为 Claude 内容块格式
• 工具调用是否适配 tool_use 和 tool_result
• 流式输出解析是否重新适配
• 服务端日志是否能区分 OpenAI 与 Anthropic 错误