用 OpenAI SDK 调用 Claude，无需重写客户端

只需更改 base_url、API 密钥和模型 ID，就可以让官方 OpenAI Python 或 TypeScript SDK 调用 Claude，并继续使用 chat.completions。Anthropic 在 OpenAI SDK 兼容指南 中记录了这条路径。同一种客户端形态也可以连接 兼容 OpenAI 的 API 网关，由网关在服务端保存 Anthropic 凭证，并把 OpenAI 风格请求转换为上游原生 Claude Messages。

这两条路径并不等价。直连兼容层适合评估；面向生产的网关让客户端使用 OpenAI 协议、对 Anthropic 使用 Claude Messages，其可靠性边界完全不同。

评估路径与生产路径

Anthropic 明确指出，其 OpenAI 兼容层主要用于测试和模型比较，并且对大多数用例而言，不是长期或生产就绪的解决方案。应把这句话视为产品政策，而不是营销细则。

路径	客户端	上游	最适合
直连 Anthropic 兼容层	OpenAI SDK → https://api.anthropic.com/v1/	Anthropic 的 OpenAI 形态接口	本地评估、提示词对比、短期验证
网关 OpenAI 入口	OpenAI SDK → 你的网关 /v1	网关转换为原生 Claude Messages	共享密钥、配额、故障转移、多供应商产品
原生 Anthropic SDK / Messages API	Anthropic 客户端	完整 Claude 功能集	提示词缓存、引用、扩展思考细节、受保证的结构化输出

第一行用于回答“Claude 在固定评估集上是否足够好”；多个服务需要使用 Claude、但不应各自持有 Anthropic 密钥时使用第二行；需要兼容层省略或忽略的 Claude 原生控制时使用第三行。

本仓库的 Claude 通道会把 OpenAI Chat Completions 转换为 Claude Messages（RequestOpenAI2ClaudeMessage 及相关适配器）。这不同于原样代理 Anthropic 的兼容端点。客户端仍发送 OpenAI JSON；控制面负责字段映射、凭证和使用日志。

Anthropic OpenAI 兼容层的重要限制

通过 OpenAI SDK 调用 api.anthropic.com 时，Anthropic 当前文档列出了明确缺口。在任何人声称“即插即用的完全兼容”之前，都应为这些差异预留空间。

1. 工具上的 strict 会被忽略。 工具参数 JSON 不保证符合给定 schema。请在运行时校验参数；如果需要服务端保证，请使用 Claude 原生结构化输出。
2. 音频输入会被移除。 多模态音频部分会被忽略，而不是明确报错。
3. 兼容路径不支持提示词缓存。 缓存仍可通过 Anthropic 自己的 SDK 和原生 API 使用。
4. 系统和开发者消息会被提升并拼接成最前面的单条系统消息。Anthropic 只支持一条初始系统消息；OpenAI 风格的会话中途 system/developer 轮次会用换行符合并。
5. 大多数不支持的字段会被静默忽略。 如果字段消失会改变产品行为，预发环境应直接失败。
6. 错误体仍使用 OpenAI 形态的外壳，但详细文本与 OpenAI 并不等价。可以记录它用于调试，但不要把错误文案解析成稳定契约。

PDF 处理、引用、可访问详细思考内容的扩展思考以及提示词缓存等完整 Claude 功能，应使用原生 Claude API，或使用能映射到这些原生字段的网关路径。必须跨品牌保持可移植的智能体工具循环，请参见 跨供应商的可移植工具调用。

直连 Anthropic base URL（评估）

Anthropic 文档中的 Python 写法：

from openai import OpenAI
import os

client = OpenAI(
    api_key=os.environ["ANTHROPIC_API_KEY"],
    base_url="https://api.anthropic.com/v1/",
)

response = client.chat.completions.create(
    model="claude-sonnet-5",  # or claude-opus-4-8; verify on Anthropic model docs
    messages=[
        {"role": "system", "content": "You are a precise API integration assistant."},
        {"role": "user", "content": "Summarize three risks of hardcoding provider SDKs."},
    ],
    max_tokens=800,
)

print(response.choices[0].message.content)

TypeScript：

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.ANTHROPIC_API_KEY,
  baseURL: "https://api.anthropic.com/v1/",
});

const response = await client.chat.completions.create({
  model: "claude-sonnet-5",
  messages: [
    { role: "system", content: "You are a precise API integration assistant." },
    { role: "user", content: "Summarize three risks of hardcoding provider SDKs." },
  ],
  max_tokens: 800,
});

console.log(response.choices[0]?.message?.content);

官方示例经常使用 claude-opus-4-8。Anthropic 当前模型文档也列出了 Claude Sonnet 5 和 Claude Haiku 4.5。应优先使用实时模型表，而不是任何博客快照，包括本文。

网关 base URL（面向生产的多服务路径）

当 Claude 只是多个通道之一时，把同一个 SDK 指向网关，并只在服务端保存 Anthropic 凭证：

client = OpenAI(
    api_key="GATEWAY_API_KEY",
    base_url="https://your-gateway.example.com/v1",
)

response = client.chat.completions.create(
    model="claude-sonnet",  # stable gateway alias mapped to a current Claude ID
    messages=[
        {
            "role": "user",
            "content": "Draft a migration checklist for SDK consolidation.",
        }
    ],
    max_tokens=800,
)

运维人员把 claude-sonnet 或 claude-opus 等别名映射到原始上游 ID（claude-sonnet-5、claude-opus-4-8，必要时使用带日期的快照）。应用配置应依赖别名，这样上游重命名只需修改通道，而不会演变成跨多个仓库的事故。这正是 多供应商 LLM 网关 所描述的控制面。

常见路径中通常可以直接迁移的部分

消息

• 普通的 system / user / assistant 聊天历史适用于评估和大多数产品聊天。
• Anthropic 兼容层不会把会话中途的 system 或 developer 轮次保留为独立 OpenAI 角色；应预期它们被合并。
• 明确写出策略文本。不要假定 Claude 会继承只为 OpenAI 模型调校的隐藏指令。

工具

OpenAI 风格的 tools 定义通常可用于智能体迁移的早期阶段。例如：

tools = [
    {
        "type": "function",
        "function": {
            "name": "lookup_order",
            "description": "Fetch an order by ID from the shop system",
            "parameters": {
                "type": "object",
                "properties": {"order_id": {"type": "string"}},
                "required": ["order_id"],
            },
        },
    }
]

response = client.chat.completions.create(
    model="claude-sonnet-5",
    messages=[{"role": "user", "content": "Where is order A-100?"}],
    tools=tools,
    tool_choice="auto",
)

message = response.choices[0].message
if message.tool_calls:
    for call in message.tool_calls:
        print(call.function.name, call.function.arguments)

由于 Anthropic 兼容接口会忽略 strict，任何副作用发生前都必须解析并按 schema 校验 arguments。即使走网关路径，也仍要在工具执行器中校验；绝不能只信任模型生成的 JSON。

流式

SSE 流式与大多数 OpenAI 聊天界面已经消费的格式一致。请验证首 token 延迟、流中错误处理，以及网关是否把 Claude 流事件归一化为稳定的客户端形态。输出部分 token 后再自动切换供应商，比流开始前的故障转移更困难；应结合 LLM API 故障转移策略 设计。

结构化输出、安全与可观测性缺口

如果流水线依赖严格 JSON Schema 强制，请先在 Claude 上测试完全相同的 schema，再声称兼容。当严格模式不完整时，应在应用代码中校验，或使用 Claude 原生结构化输出。

即使 JSON 键看起来相同，各供应商在拒答、限流 header 和 token 统计上仍有差异。如果客户端期望统一契约，应在网关归一化错误类别。不要把永久性的鉴权或策略失败当作暂时性 5xx 来重试。

直连 Anthropic 密钥和网关密钥会产生不同的审计轨迹。团队通常希望使用历史与通道健康放在一起，而不是只存在于单一供应商控制台。公开的定价页和模型目录有助于利益相关者了解情况；不要在每个段落中塞入需要鉴权的运维 URL。

受控切换顺序

1. 清点已经依赖 OpenAI SDK 或原始 /v1/chat/completions 的服务。
2. 使用一个 Claude 模型 ID，在 Anthropic 兼容端点上运行固定评估集。
3. 把 Anthropic 凭证注册为网关通道，并发布稳定别名。
4. 让一个低风险内部任务使用该网关别名；不要先切换客户聊天。
5. 比较 schema 合法率、拒答率、延迟和每个成功任务的成本。
6. 只有普通聊天稳定后，才加入工具和流式。
7. 写明回滚方式：保留之前的模型别名。

HTTP 冒烟测试

curl https://your-gateway.example.com/v1/chat/completions \
  -H "Authorization: Bearer $GATEWAY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-sonnet",
    "messages": [
      {"role": "user", "content": "Reply with the single word ready."}
    ],
    "max_tokens": 32
  }'

应返回带 choices[0].message.content 的 Chat Completions 形态 JSON。如果外壳结构不同，应先修正映射，再修改产品代码。

生产清单（网关路径）

• 固定评估集已经证明质量；生产流量不把 Anthropic 兼容层作为长期路径。
• 模型别名映射到 Anthropic 文档或维护目录中的当前 Claude ID。
• 密钥保存在网关或密钥管理器中，绝不进入浏览器或移动应用。
• 明确设置 max_tokens；静默默认值可能截断长回答。
• 工具参数在服务端按 schema 校验；不要依赖会被忽略的 strict。
• 流式客户端能够处理不完整的最终消息和流中错误。
• 成本与错误看板把 Claude 与其他供应商分开。
• 故障转移策略明确 Claude 是主通道、备份还是固定通道。

何时网关优于直连 Anthropic base URL

触发条件	网关的帮助
一个产品使用多个供应商	一套客户端配置，多个通道
全团队共用凭证	使用限定作用域的网关密钥，而不是共享 Anthropic 密钥
支出审查	统一的使用历史和定价上下文
可靠性目标	无需重写每个服务即可重试和故障转移
智能体集群	集中管理工具和模型路由策略

AveMujica API 正是作为这种控制面构建的：兼容 OpenAI 的入口、供应商通道、模型目录和运维历史。它不能替代阅读 Anthropic 的兼容性说明；它能避免这些说明演变成五套彼此分叉的客户端。

官方来源

• Anthropic：OpenAI SDK 兼容性
• Anthropic：模型概览
• OpenAI：Chat Completions 参考
• OpenAI Python SDK

最后核对：2026-07-15。在任何生产冻结之前，请重新核对 Anthropic 文档中的模型 ID 和兼容性限制。

常见问题

Anthropic 的 OpenAI SDK 路径是否已适合生产？

Anthropic 将其描述为主要用于测试和比较，而不是适合大多数用例的长期生产方案。生产集群应优先选择把 OpenAI 入口适配为原生 Claude Messages 的网关；需要 Claude 专属功能时，也可以直接使用 Anthropic 原生 API。

每个 OpenAI Chat Completions 字段都能在 Claude 上原样运行吗？

不能。strict 会被忽略，音频会被移除，兼容层不支持提示词缓存，system/developer 轮次会被合并。请测试实际要上线的请求形态。

应用配置中应该写哪个模型字符串？

优先使用由运维映射到当前 ID 的网关别名（claude-sonnet），例如映射到 claude-sonnet-5 或 claude-opus-4-8。避免在每个服务中写死昨天的快照 ID。

仍然需要 Anthropic SDK 吗？

当你明确需要仅原生 API 提供的控制时需要，例如提示词缓存标记、完整扩展思考访问或原生结构化输出。当 OpenAI 形态足够且网关负责供应商多样性时，继续使用 OpenAI SDK。

完成首次 Claude 切换

选择一个已经使用 OpenAI SDK 的服务。先在 Anthropic 兼容端点上证明质量，再把该服务迁移到路由至 Claude Messages 的网关别名。只有普通聊天通过后，才扩展工具和流式，并把首日流量与之前的 OpenAI 基线进行比较。