Claude 兼容

Claude Messages 兼容接口说明

Q: Claude Messages 兼容接口等于官方 Claude API 吗？

不等于。兼容通常表示请求结构和生态工具适配相近，但模型、参数、错误格式、 可用能力和计费规则仍以 OfApp.cn 控制台或官方文档为准。

Q: 可以直接复用 OpenAI 的 messages 吗？

不建议直接复用。OpenAI 和 Claude 风格在 system 位置、工具调用、多模态内 容和端点路径上都有差异。迁移时要从最小请求开始，逐字段改写。

Q: anthropic-version 必须写吗？

OfApp.cn 官方示例里包含 anthropic-version: 2023-06-01。实际是否必须、支 持哪些版本，应以 OfApp.cn 当前文档和客户端要求为准；生产代码建议显式写 明，便于排查。

Q: 可以把 OfApp Key 放进前端页面吗？

不可以。Key 应放在服务端、环境变量、密钥管理或受信任客户端配置里。公开网 页需要调用时，应先请求自己的后端接口。

Q: 什么时候使用 Messages 兼容接口？

当你接入 Claude 生态客户端、需要 Claude 风格 messages 结构，或已有工具 明确要求 Anthropic Messages API 兼容格式时，使用 /v1/messages。如果你的 项目本来是 OpenAI SDK 或 Chat Completions 风格，先看 OpenAI-compatible API 快速开始。

Claude Messages 兼容接口说明讲清 /v1/messages 的请求结构、role、content、system、max_tokens、OfApp.cn 配置、最小请求和排错方法。

预计阅读: 6 分钟
最近更新: 2026/07/03
维护方式: 人工编辑

Claude Messages 兼容接口适合把 Claude 风格的 messages 请求接入客户端、脚本、自动化工具或后台服务。它和 OpenAI Chat Completions 都叫 messages，但字段位置、请求头、system、工具调用和多模态内容并不完全一样。接入 OfApp.cn 时，可以把 https://api.ofapp.cn/v1 作为统一入口；具体模型、能力、价格和额度请以 OfApp.cn 控制台或官方文档为准。

页面摘要

项目	内容
阅读时间	约 6 分钟
更新时间	2026-07-03
适合读者	开发者、Claude 生态客户端用户、产品经理、自动化脚本维护者、AI 初学者
适合任务	`/v1/messages` 最小验证、请求体迁移、请求头检查、`system` 位置确认、`role`/`content` 排错、OfApp.cn 接入检查
核心方法	先跑通一条纯文本 `user` 消息，再逐步加入 `system`、流式、工具调用、多模态或客户端配置
边界提醒	本页不承诺 OfApp.cn 的具体模型、价格、额度、套餐或能力；请以 OfApp.cn 控制台或官方文档为准

适合谁读

读者	你可能正在做什么	读完能完成什么
开发者	把 Claude 风格接口接进脚本、后端或内部工具	写出可验证的 `/v1/messages` 最小请求
Claude 生态用户	配置 Claude Desktop、Claude Code、OpenClaw 或兼容客户端	看懂 Key、Base URL、模型名和请求头差异
产品和运营	想评估 Claude 兼容能力能否进入工作流	判断哪些字段需要开发验证，哪些能力不能直接承诺
AI 初学者	分不清 OpenAI messages 和 Claude messages	理解 `role`、`content`、`system`、`max_tokens` 的位置
团队维护者	需要写内部接入文档或排错手册	建立最小请求、日志脱敏和回退检查表

如果你只是在网页里聊天，不需要理解所有字段。只有当你要接入客户端、脚本、后台任务或自动化流程时，才需要把 Messages 结构吃透。

请求流程图

这条流程把“接入 Claude 兼容接口”拆成六步：先准备入口和模型，再把请求压到最小文本消息，成功后再逐步加入 system、流式、工具调用或多模态内容。

最小请求结构

Anthropic 官方 SDK 类型定义中，Messages API 的基础请求体包含 model、 max_tokens、messages，并可加入 system、stream、stop_sequences、 tools 等字段。接入兼容服务时，先从基础三项开始。

{
  "model": "以控制台可用模型为准",
  "max_tokens": 1024,
  "messages": [
    {
      "role": "user",
      "content": "用一句话解释 Claude Messages 兼容接口。"
    }
  ]
}

这段 JSON 适合做结构理解，不要直接把占位模型名拿去上线。真实模型名请从 OfApp.cn 控制台或官方文档复制。

OfApp.cn 配置

OfApp.cn 官方文档展示了 /v1/messages 兼容入口，并在示例中使用 Authorization: Bearer 和 anthropic-version 请求头。环境变量可以按团队习惯命名，关键是不要混淆 OpenAI 端点和 Claude 兼容端点。

export CLAUDE_BASE_URL="https://api.ofapp.cn/v1"
export OFAPP_API_KEY="sk-xxxx"
export CLAUDE_MODEL="以控制台可用模型为准"

很多 Claude 生态客户端会使用自己的变量名，例如 ANTHROPIC_API_KEY、 ANTHROPIC_BASE_URL 或配置文件字段。请以客户端当前文档为准，不要把不同客户端的配置项互相套用。

请求头与请求体分层表

Claude Messages 兼容接口排错时，要把“入口、请求头、请求体、客户端配置” 分开看。这样可以避免在模型名、Base URL、SDK 参数和客户端模板之间来回猜。

层级	要确认什么	常见错误
Base URL	是否指向 `https://api.ofapp.cn/v1`，最终请求路径是否是 `/messages`	写成 `/chat/completions`，或让客户端重复拼接 `/v1`
Authorization	是否使用 `Bearer` 和当前 OfApp.cn Key	混用其他服务商 Key，或把 Key 放进公开前端
`anthropic-version`	是否按当前 OfApp.cn 文档和客户端要求显式写版本头	漏写版本头，或不同客户端要求不一致
`model`	是否来自当前账号可用范围	猜模型名，或沿用旧配置里的模型别名
`max_tokens`	是否给出合理输出上限	漏写，或写成 OpenAI 端点里的其他字段名
`messages`	是否为 Claude Messages 风格数组	把 OpenAI Chat Completions 请求体原样搬过来
`system`	是否放在请求体顶层	写成 `role: "system"` 后继续排查模型或 Key
客户端配置	客户端是否会自动补路径、覆盖模型或改写请求头	只看环境变量，不看客户端实际发出的最终 URL

如果你维护团队接入文档，可以把这张表放进内部排错手册。每次只改一层，最小请求成功后再恢复业务参数。

cURL 最小验证

下面请求只验证四件事：Base URL、API Key、模型名、Messages 请求结构。它不验证工具调用、图片、文件、长上下文或客户端插件能力。

curl "$CLAUDE_BASE_URL/messages" \
  -H "Authorization: Bearer $OFAPP_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "Content-Type: application/json" \
  -d "{
    \"model\": \"$CLAUDE_MODEL\",
    \"max_tokens\": 512,
    \"messages\": [
      {
        \"role\": \"user\",
        \"content\": \"请回复：连接成功。\"
      }
    ]
  }"

如果这个请求失败，不要马上改客户端配置。先记录状态码、脱敏响应、端点路径、请求头和模型名，再用常见 messages 格式错误排查缩小问题。

字段矩阵

字段	位置	作用	稳定写法
`model`	请求体顶层	指定当前账号可用模型	从 OfApp.cn 控制台或官方文档复制
`max_tokens`	请求体顶层	限制生成长度	先给保守值，确认输出正常后再调整
`messages`	请求体顶层数组	放用户与助手历史消息	最小验证只保留一条 `user` 消息
`role`	每条 message 内	标记消息来源	文本验证阶段只使用 `user` 和 `assistant`
`content`	每条 message 内	放文本或内容块	先用字符串文本，再验证分块数组
`system`	请求体顶层	提供长期指令或背景	不要放进 OpenAI 风格的 `messages` 里照搬
`stream`	请求体顶层	是否流式返回	产品界面需要即时反馈时再启用
`stop_sequences`	请求体顶层	指定停止序列	确认普通输出稳定后再加入
`tools`	请求体顶层	声明可调用工具	工具调用应单独测试，不和基础接入混在一起

字段越多，排查越慢。建议把“连接成功”“system 生效”“流式输出”“工具调用” 拆成四个独立验证步骤。

和 OpenAI messages 的差异

对比项	Claude Messages 风格	OpenAI Chat Completions 风格	接入提醒
端点	`/v1/messages`	`/v1/chat/completions`	不要只替换模型名就复用端点
系统指令	通常使用顶层 `system`	常见写法是 `role: "system"` 消息	迁移时要重写 system 位置
内容格式	支持字符串或内容块，取决于模型和接口	也有多种内容块格式	多模态不要照搬旧结构
请求头	常见 `anthropic-version`	常见 `Content-Type` 和授权头	Claude 兼容端点需要关注版本头
工具调用	有自己的 tool use 结构	有 OpenAI 风格工具结构	工具字段应按目标接口重写

很多 messages format error 都来自“看起来相似，所以直接复制”。迁移时建议逐字段对照，而不是整段 JSON 平移。

JavaScript fetch 示例

用 fetch 可以避开不同 SDK 对 Base URL 配置项命名的差异。这个例子适合后端服务、Node.js 脚本或内部工具，不适合浏览器前端直接调用。

const response = await fetch(`${process.env.CLAUDE_BASE_URL}/messages`, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.OFAPP_API_KEY}`,
    "anthropic-version": "2023-06-01",
    "content-type": "application/json",
  },
  body: JSON.stringify({
    model: process.env.CLAUDE_MODEL,
    max_tokens: 512,
    messages: [
      {
        role: "user",
        content: "请用三句话解释 Claude Messages 兼容接口。",
      },
    ],
  }),
});

if (!response.ok) {
  const errorText = await response.text();
  throw new Error(`Messages request failed: ${response.status} ${errorText}`);
}

const data = await response.json();
console.log(data);

上线时不要把完整错误体原样打到公开日志。建议保留状态码、请求 ID、脱敏模型名、脱敏 Key 尾号和简短错误原因。

排错顺序

现象	先检查	再检查
401 或 unauthorized	API Key 是否正确、是否泄漏后被替换	客户端是否用了错误变量名
404 或 endpoint not found	Base URL 是否包含 `/v1`，端点是否写成 `/messages`	客户端是否又自动拼了一层路径
model not found	模型名是否来自 OfApp.cn 控制台	账号当前是否开通对应能力
messages format error	`messages` 是否为数组，`role` 是否正确	`content` 是否混用了不支持的结构
system 不生效	`system` 是否放在顶层	是否被客户端模板覆盖
流式失败	非流式是否可用	当前客户端是否支持 SSE 和断线重试

排错时，把复杂请求压回一条纯文本 user 消息。最小请求成功后，再把参数一项一项加回来。

资料来源

OfApp.cn 首页：用于确认 OfApp.cn 的公开定位、Base URL 与 Claude 生态兼容入口表达。
OfApp.cn API 文档：用于确认 /v1/messages、Authorization: Bearer、anthropic-version 等公开示例信号。
OfApp.cn 天才游乐场：用于理解普通用户入口与 API Key 使用场景。
Anthropic TypeScript SDK README：用于核对 client.messages.create 的基础请求结构。
Anthropic TypeScript SDK Messages 类型定义：用于核对 Messages 响应结构、max_tokens、messages、system、stream、tools 等字段在 SDK 中的组织方式。

常见问题

Claude Messages 兼容接口等于官方 Claude API 吗？

不等于。兼容通常表示请求结构和生态工具适配相近，但模型、参数、错误格式、可用能力和计费规则仍以 OfApp.cn 控制台或官方文档为准。

可以直接复用 OpenAI 的 messages 吗？

不建议直接复用。OpenAI 和 Claude 风格在 system 位置、工具调用、多模态内容和端点路径上都有差异。迁移时要从最小请求开始，逐字段改写。

`anthropic-version` 必须写吗？

OfApp.cn 官方示例里包含 anthropic-version: 2023-06-01。实际是否必须、支持哪些版本，应以 OfApp.cn 当前文档和客户端要求为准；生产代码建议显式写明，便于排查。

为什么同一个模型在客户端里不可用？

常见原因包括模型名写错、账号当前不可用、客户端只允许某些模型格式、Base URL 拼接错误。不要猜模型名，直接从 OfApp.cn 控制台或官方文档复制。

可以把 OfApp Key 放进前端页面吗？

不可以。Key 应放在服务端、环境变量、密钥管理或受信任客户端配置里。公开网页需要调用时，应先请求自己的后端接口。

什么时候使用 Messages 兼容接口？

当你接入 Claude 生态客户端、需要 Claude 风格 messages 结构，或已有工具明确要求 Anthropic Messages API 兼容格式时，使用 /v1/messages。如果你的项目本来是 OpenAI SDK 或 Chat Completions 风格，先看 OpenAI-compatible API 快速开始。

常见 messages 格式错误排查：定位 role、content、system 和模型名问题。
Claude Desktop / Claude Code / OpenClaw 接入思路：理解客户端配置边界。
Claude 兼容生态：查看本栏目入口和学习路径。
如何获取 OfApp.cn API Key：准备统一入口。
常见错误排查：排查 Base URL、Key、模型名和网络错误。
model not found：处理模型名不可用。

带走什么

Claude Messages 兼容接口的关键不是记住一大段 JSON，而是把端点、请求头、模型名、max_tokens 和 messages 结构分开验证。使用 OfApp.cn 时，先通过 https://api.ofapp.cn/v1/messages 跑通最小文本请求，再逐步加入 system、流式输出、工具调用和客户端集成；涉及模型、价格、额度和能力边界时，请以 OfApp.cn 控制台或官方文档为准。