OpenCode 这类终端 AI 编程助手火了之后越来越多的人开始通过中转 API 来降低调用成本、解锁更多模型。但中转 API 和标准 OpenAI 接口之间经常出现 JSON Schema 对不上的情况轻则解析报错重则整个会话直接挂掉。这篇文章从问题现象、根因、诊断到解决方案整套流程都走了一遍希望对趟过这条河的同行有帮助。1. 问题全貌OpenCode 对接中转 API 时到底会踩哪些坑1.1 最常见的四类爆错现场先说一个原则JSON Schema 兼容性问题本质上不是“能不能连上”的问题而是“连上之后数据长得对不对”的问题。我用 OpenCode 接入中转 API 以来遇到过四类高频报错基本覆盖了 90% 的情况。第一类是启动即报错。OpenCode 配置好模型名、Base URL 之后一发起请求就弹出一段ValidationError提示某个字段不该缺失、某个字段类型不对。这种问题往往和中转平台返回的元信息有关比如模型列表接口返回的id字段格式、object字段的值和 OpenCode 客户端期待的枚举值对不上。第二类是会话中途崩掉。对话前几轮好好的一旦上下文变长、模型开始回复长文本或携带工具调用客户端解析就失败。这里十有八九是流式输出SSE的格式出了问题比如delta里塞了个模型特有的字段OpenCode 不认直接抛出解析异常。第三类是工具调用翻车。OpenCode 作为编程助手经常需要调用工具读文件、执行命令、改代码这类请求的响应里会带上tool_calls字段。中转 API 如果背后对接的是某个非 OpenAI 原生的模型这个字段的结构往往和 OpenAI 规范不一致。常见的差异包括arguments是字符串而不是 JSON 对象、id缺失、type枚举值不同。第四类是静默异常。请求成功了、HTTP 状态码也是 200但返回的数据里有一个字段的值类型错了。比如usage.total_tokens返回了字符串或者choices数组里少了一个关键键。OpenCode 不会直接报错但后续逻辑会莫名其妙地不正常比如统计不准、历史记录错乱。这种问题最隐蔽排查起来也最费劲。1.2 为什么偏偏是 JSON Schema 在作怪要理解为什么 JSON Schema 这么容易出问题得先看看 JSON Schema 在 OpenCode 对接过程中的作用。OpenCode 作为客户端内部定义了完整的请求和响应数据结构它接收的每一份数据都要过一道结构校验。校验的内容很细字段必须存在、字段类型必须正确、枚举值必须合法、嵌套层级必须对得上。这道校验本来是为了保证下游逻辑不会崩溃但它也成了兼容性要求的集中引爆点。中转 API 的定位很特殊。它介于客户端和大模型之间既要接收不同客户端的请求又要兼容几十种模型的输出格式。大多数中转平台在做模型适配时会选择“最小改动”策略也就是尽量按 OpenAI 格式输出但模型返回什么就透传什么。这种策略在业务场景下没问题因为很多业务后端对数据的容错性很强但在 OpenCode 这种对结构有严格校验的客户端场景下分分钟就会炸。另外一个核心问题是JSON Schema 校验和实际业务解析是两套逻辑。很多中转平台在网关层面不校验响应体他们只保证 HTTP 状态码正确、能流畅地转发文本。而 OpenCode 客户端是拿到完整响应之后做严格解析的。两层之间的宽容度差异就是你遇到各种诡异报错的原因。2. 根因定位从中转平台的转发逻辑解剖兼容性问题2.1 中转 API 不只是“转发”它还在做格式改写很多人的第一反应是中转 API 不就是一个反向代理嘛把请求转给上游模型再原样返回给客户端怎么会产生 Schema 问题我在排查实际项目时发现中转 API 做的工作远比“转发”多得多。一个主流中转平台至少要处理三类改写。第一类是鉴权和计费相关的字段改写比如在请求头注入上游模型的 Key、改写用户标识、统计计费 Token。这类改写一般不碰业务字段安全。第二类是参数映射也就是把 OpenAI 风格请求体里的参数名替换成目标模型能理解的参数名。比如某些模型要求的温度参数范围不同、一些复杂参数名不同都需要中转层做转换。第三类是响应补偿也就是把模型返回的原生格式尽力拼成 OpenAI 兼容格式。选择器、思考链字段、工具调用字段都是在第三类改写中处理的。问题恰恰出在响应补偿这一步。不同模型的原生响应形式五花八门。有的模型把思考内容放在reasoning_content字段里有的模型把工具调用放在顶层而不是tool_calls数组里。中转平台为了兼容会在脚本或网关插件里做字段拼装。拼装过程偶尔会漏掉字段嵌套层级或者没有处理流式场景下的增量字段。这就是 JSON Schema 兼容性问题的大本营不是模型输出本身的错而是中转平台在做格式映射时补了字段、挪了位置、改了类型但改动没有完全贴合 OpenAI 标准。2.2 流式输出是最容易翻车的路段流式输出SSE是 JSON Schema 兼容性问题的高发区原因是流式和非流式走的完全不是同一条代码路径。非流式模式下中转平台拿到完整的模型响应可以统一做一次格式化处理字段缺失、类型错误都好补。但流式模式下模型是一个 chunk 一个 chunk 地输出中转平台不能等全部数据到齐再处理那样会失去流式的意义。所以每个 chunk 几乎是透传的最多做字段名的局部替换。于是问题就来了非流式模式下被兜底补全的字段在流式模式下没人补了。举个例子OpenAI 流式响应的每个 chunk 里delta对象是必有字段但某些模型原生流式输出里根本没有delta这一层而是content在顶层。中转平台透传时就会把缺失层级的问题原样交给 OpenCode。还有finish_reason字段。OpenAI 规范里最后一个 chunk 上会带上finish_reason并置为stop或tool_calls。但很多模型原生流式只在事件类型里标记结束不设置这个字段。中转平台如果在事件转换时没做映射OpenCode 拿到的流就永远等不到结束信号表现就是转圈永远不停。2.3 Schema 校验失败的三大具体原因把大量报错归拢之后我发现背后其实只有三个根因。第一个是字段缺失。最典型的是system_fingerprint、prompt_tokens、completion_tokens这类非核心字段缺失。严格来说这些字段不是每次都必须存在但 OpenCode 内部如果直接按索引访问就会抛 TypeError。还有一类是id字段为空字符串看似没缺但客户端如果拿它当 key 用就会引发连锁问题。第二个是字段类型不匹配。比如usage.completion_tokens返回的是带小数的浮点数或者choices数组里的索引键index是字符串。类型不匹配在 JSON 解析层面不会报错但一旦代码里执行数值运算或者比较操作问题就暴露出来了。第三个是多态结构。同一个字段在不同模型下可能是不同结构最典型的就是tool_calls。在 OpenAI 规范里它是一个数组数组元素里有id、type、function三个固定键但某些模型把arguments直接展开成对象而不是字符串或者把function整体漏掉。这种多态结构对 Schema 校验几乎是灾难。3. 现场诊断三步定位不兼容点3.1 第一步让请求和响应“见光”很多人在排查兼容性问题的时候全靠 OpenCode 界面上的报错信息猜这是效率最低的方式。第一步应该是把底层请求和响应完整地导出来亲眼看看数据长什么样。怎么导出用本地代理是最省事的方式。在电脑上跑一个轻量 HTTP 代理把 OpenCode 的网络请求指到代理上然后在代理端记录完整的请求体和响应体。我自己常用的是一个不到 60 行的 Python 脚本基于http.server模块不仅能打印出所有经过的请求头和 body还能把 SSE 流里的每一段数据都落到日志文件里。配置 OpenCode 走代理也很简单设置 HTTPS_PROXY 环境变量即可。如果 OpenCode 本身提供了网络调试开关类似 verbose 模式那就更方便了可以直接在终端里看到请求和响应。关键是确保日志里能看到原始响应而不是经过 OpenCode 解析后的结果。这一步做完绝大多数问题已经能判断出方向。如果日志里的响应结构和 OpenAI 官方文档不一致那问题就出在中转平台侧如果结构对得上但 OpenCode 仍然报错那问题可能出在 OpenCode 对字段的额外要求上。3.2 第二步把官方 Schema 拉出来做对照定位问题不能靠肉眼要把 OpenCode 内部定义的数据结构和 OpenAI 官方 Schema 拉出来逐一对照。OpenCode 这类客户端的核心数据结构定义在它们的类型文件里比如src/types.ts、src/api/types.ts或者按模块划分的models.ts。重点看这几类ChatCompletionRequest、ChatCompletionResponse、StreamChunk以及 ToolCall。把每个字段的required、type、enum记下来。与此同时去 OpenAI 官方文档里拉一份最新的 Chat Completion Schema。对照的时候不要只看字段名要重点关注三处。第一是必填字段列表第二是嵌套对象的层级结构第三是枚举类型的具体取值。对照完成之后把差异整理成一个清单。比如我的清单里曾经列过OpenCode 要求choices[0].message.tool_calls是数组但某个中转平台在没有工具调用时会把这个字段设置为null。这个差异不仔细对照 Schema 根本发现不了。3.3 第三步写一个校验脚本让问题自动现形当响应量比较大的时候手工看每一条响应不现实。我习惯写一个临时的 JSON Schema 校验脚本把 OpenCode 期望的结构转成 JSON Schema 格式然后用jsonschema库自动校验每一条记录的响应。这个脚本的价值在于它能一次性把一批响应样本全部跑完输出所有不兼容点而不只是第一个报错。示例如下基于常见实践可按实际需求调整字段import json import jsonschema sales_person_schema { type: object, required: [id, object, created, choices, usage], properties: { id: {type: string}, object: {type: string, enum: [chat.completion]}, created: {type: integer}, choices: { type: array, items: { type: object, required: [index, message, finish_reason], properties: { index: {type: integer}, message: { type: object, required: [role, content], properties: { role: {type: string}, content: {type: [string, null]}, tool_calls: { type: array, items: { type: object, required: [id, type, function], properties: { id: {type: string}, type: {type: string, enum: [function]}, function: { type: object, required: [name, arguments], properties: { name: {type: string}, arguments: {type: string} } } } } } } }, finish_reason: {type: [string, null]} } } }, usage: { type: object, required: [prompt_tokens, completion_tokens, total_tokens], properties: { prompt_tokens: {type: integer}, completion_tokens: {type: integer}, total_tokens: {type: integer} } } } } with open(responses.jsonl, r) as f: for idx, line in enumerate(f): data json.loads(line) try: jsonschema.validate(instancedata, schemasales_person_schema) except jsonschema.ValidationError as e: print(f第 {idx} 条: {e.message})跑完这个脚本你会得到一个精确到字段的问题清单。根据清单去查对应的环节——是平台透传问题还是配置问题还是 OpenCode 自身对格式有额外要求就一目了然了。4. 解决方案四层递进从配置到代码全打通4.1 第 1 层先改配置用最省力的方式绕开问题遇到兼容性问题先别急着写代码有相当一部分通过配置就能解决。绕开问题的思路是让 OpenCode 和中转平台在 Schema 预期上对齐。先检查 OpenCode 的模型配置。很多终端 AI 编程助手支持指定 API 的兼容风格也就是选择 OpenAI 兼容模式还是 Anthropic 兼容模式。如果你的中转平台接口实际上是 OpenAI 兼容的但 OpenCode 默认走了 Anthropic 风格那大概率会报出各种奇怪的 Schema 错误。把模型配置调整为与中转平台接口风格匹配是第一件要做的事。再检查 Base URL 是否指向了正确的接口路径。很多中转平台不仅提供/v1/chat/completions也提供/v1/messages这类 Anthropic 风格路径。如果你在 OpenCode 里配置的是 Anthropic 接口但中转平台实际支持的只是 OpenAI 兼容路径那数据返回的格式天然是错位的。第三个检查点是模型名。中转平台上的模型名往往不是标准名称比如加了一堆前缀后缀。OpenCode 拿到模型名后可能会基于名称做行为分支比如判断是否支持思考模式、是否支持工具调用。如果模型名对不上它内部的白名单某些字段就不会被正确处理。所以模型名一定要填写中转平台文档上标的精确名称不能凭直觉写一个相近的。这一层的经验是改配置前先把自己的环境信息整理清楚包括 OpenCode 版本、中转平台接口风格、模型准确名称三者对齐能省掉后面 80% 的排查时间。4.2 第 2 层在中转平台侧开启兼容参数配置改完还不行的可以把目光转到中转平台的控制台。很多中转平台已经预料到了兼容性问题会提供一些开关或参数来调整输出格式。常见的是“强制 OpenAI 格式输出”选项。这个开关开启后中转平台响应的格式会严格贴合 OpenAI 的规范。字段该补的补、该删的删usage、id、system_fingerprint这类容易被忽略的字段也会补全。还有一些平台支持关闭双语/思考链字段。注意到一个现象了吗OpenAI 某些模型原生输出时会带一个reasoning字段这个问题已经在实际使用中出现过。如果你用的模型带有思考链输出而 OpenCode 解析器不支持这个字段可以在中转平台侧把思考链字段的透传关掉或者让它合并到content文本里。这个选项在不同平台里叫法不一样有的叫“思维链后处理”有的叫“扩展字段合并”本质都是把模型原生附加字段降级为 OpenAI 标准字段。另一个值得看的选项是工具调用的格式。中转平台通常有一个“工具调用兼容”设置支持把多模型原生工具输出统一转成 OpenAI 标准格式。如果这个选项存在建议优先打开。复杂的工具调用字段拼接让中转平台去处理比自己在客户端侧改要省事得多。第 2 层的核心逻辑是把兼容性问题在源头处理掉而不是在客户端侧打补丁。你可以在中转平台侧尽量把输出标准化后续客户端侧的排查成本就会显著降低。4.3 第 3 层写一个轻量级规范化代理根治格式漂移如果中转平台侧没有提供兼容选项或者选项开了依然有问题那就只能自己动手在 OpenCode 和中转平台之间插一个轻量级代理。这个代理的作用只有一个响应规范化。响应规范化的思路很简单。OpenCode 把请求发给本地代理代理原样转发给中转平台。中转平台的响应返回后代理先不直接透传给 OpenCode而是做一轮字段修正然后再把修正后的响应返回给 OpenCode。用 Python 的 FastAPI 可以实现一个最小可用的版本。from fastapi import FastAPI, Request import httpx app FastAPI() UPSTREAM_URL https://your-relay-host.example/v1/chat/completions UPSTREAM_KEY your-remote-api-key def normalize_chunk(data: dict) - dict: # 修正流式 chunk补齐 delta 层级删除无用字段 if choices in data: for choice in data.get(choices, []): if delta not in choice and message in choice: choice[delta] choice[message] delta choice.get(delta, {}) if reasoning_content in delta: # 部分模型特有的思考字段OpenCode 不识别直接移除 delta.pop(reasoning_content, None) return data def normalize_non_stream(data: dict) - dict: # 修正非流式响应补全缺失字段、纠正类型 data.setdefault(id, chatcmpl-local-fallback) data.setdefault(object, chat.completion) usage data.get(usage, {}) usage.setdefault(prompt_tokens, 0) usage.setdefault(completion_tokens, 0) usage.setdefault(total_tokens, 0) data[usage] usage return data app.post(/v1/chat/completions) async def chat_completions(request: Request): body await request.json() headers { Authorization: fBearer {UPSTREAM_KEY}, Content-Type: application/json, } async with httpx.AsyncClient(timeout300) as client: resp await client.post(UPSTREAM_URL, jsonbody, headersheaders) resp.raise_for_status() if body.get(stream): # 逐行处理 SSE 数据 text async for line in resp.aiter_lines(): if not line: continue if line.startswith(data: ): payload line[len(data: ):] if payload [DONE]: text data: [DONE]\n\n break data normalize_chunk(json.loads(payload)) text data: json.dumps(data) \n\n return Response(contenttext, media_typetext/event-stream) else: data normalize_non_stream(resp.json()) return JSONResponse(contentdata)代码本身只是一个骨架实际使用中需要根据问题清单里的具体字段做定制。但思路是对的代理只修该修的字段其他内容原样透传干预范围越小越好。有一个细节值得特别注意流式场景下代理要把上游的 SSE 数据逐行读取、逐行转换不能等全部流结束再一次性处理否则用户体验会很差。另外代理要做超时控制和错误处理上游如果 5 分钟没返回代理要把超时错误以 OpenAI 规范的错误格式返回给 OpenCode不然 OpenCode 侧会当成解析错误处理。这一层的价值在于它能绕开中转平台实现不了的部分直接在本地解决兼容性问题。如果你要对接多个模型还可以在代理里为每个模型写一份独立的规范化规则灵活度最高。4.4 第 4 层修改 OpenCode 源码或插件做兜底前面几层都试过之后仍有极少数兼容性问题会残留下来。比如 OpenCode 对某个字段的解析有强制约束而这种约束在规则上就是错的或者和上游模型的设计冲突。这时候就需要考虑第 4 层修改 OpenCode 本身的解析逻辑或者写一个小的兼容补丁。这听起来很吓人但对于这种开源终端助手来说并没有想象中复杂。找到报错对应的源码点通常是类型定义文件或响应解析工具函数然后判断问题在哪。以实际遇到的情况举例OpenCode 内部定义tool_calls的arguments必须是 JSON 字符串但某个上游模型直接返回了 JSON 对象。这时可以在解析函数里加一个类型判断如果arguments是对象就先json.dumps()再赋给字段而不是直接抛异常。我这里也确实遇到过OpenCode 严格要求stream_options请求参数中include_usage必须为布尔值但某些中转平台对这个参数支持不佳返回结果里usage字段是空对象导致 OpenCode 在非流式校验时报错。这种问题打补丁时直接在上游响应进入解析器之前加一个“字段归一化”入口是最稳妥的方式。改源码时有一条铁律只做字段映射和容错处理不要改动任何业务逻辑。确保改动只发生在请求和响应解析的边界层这样升级 OpenCode 版本时通过git rebase或手动合并就能继续维护补丁。5. 常见问题排查速查表与避坑笔记5.1 高频问题速查表在实际项目里很多问题看起来五花八门本质上都是那几个原因的变体整理一份速查表方便你把问题快速归类。问题现象根本原因解决思路启动后首次请求即报 ValidationError中转平台响应缺id或object字段代理层补齐默认值或开启平台强制 OpenAI 格式对话中途解析停止转圈不停流式 chunk 缺少finish_reason或delta字段不完整检查中转平台流式事件转换逻辑代理层补全结束标记工具调用时报错无法执行命令上游模型返回的tool_calls.arguments是对象而非字符串在代理层做 JSON 序列化统一为字符串传递计数异常或会话历史错乱usage字段类型不对或prompt_tokens为 null非流式响应里补全 usage 默认值类型转为整数响应里出现未知字段导致解析告警模型特有的reasoning_content等扩展字段透传在中转平台关闭扩展字段或代理层删除日志中请求成功但 OpenCode 显示失败响应体中的choices为空数组判断空数组场景返回兜底文本或重试请求这张表的核心价值在于按照“问题现象 → 根本原因 → 解决思路”的思路走不需要每次都从零排查。大多数问题的定位时间能压缩到 15 分钟以内。5.2 三个值得记住的经验第一个经验是不要一上来就怀疑 OpenCode 有 Bug。虽然这类终端助手升级很快但大多数情况下问题出在接口适配层的格式差异上。先用最原始的方式观察请求和响应数据确认差异在哪里再决定改谁。第二个经验是所有的兼容性修复都应该放在数据边界处不要散落到业务代码里。不管是 OpenCode 的解析器补丁还是中转平台的格式开关都应该把这些改动集中在一起。这样当上游接口调整之后你只需要改边界层的映射关系而不需要把所有业务逻辑都翻一遍。第三个经验是每次改了中转平台的配置或者 OpenCode 版本都应该回到代理层跑一遍自动化校验脚本。别小看这一步因为中转平台的“兼容性开关”在不同模型下表现并不完全一致。某一个模型下没问题不代表另一个模型也没问题。跑一遍脚本确认 JSON Schema 校验全部通过再投入使用能避免很多线上问题。6. 后话如何让兼容性问题不再反复出现6.1 给接口做“契约测试”兼容性问题之所以反复出现根本原因是中转 API 的响应格式没有固定的契约。想根治就要把“契约”这个概念显式化。我给一个经过实践验证的思路在代理层实现一个测试用例集。每个用例是一个固定的请求体加上一份期望的响应 Schema。代理在启动时或者定时跑一遍这些用例把上游响应和期望 Schema 做校验一旦发现漂移就能及时告警。这套思路和软件开发里的契约测试是一样的只是把它用在了 API 兼容性上。你可以对新接入的每个模型都准备一份独立的测试用例。比如工具调用场景一组、流式场景一组、多轮对话场景一组。每个用例都跑一遍比人工确认要可靠得多。6.2 锁模型版本定期跑回归中转 API 背后经常是多模型动态路由。你现在用的模型可能过几天就被平台升级到了一个新版本。模型升级对大部分人来说是好事但由此可能引入响应字段的变化。比如某模型新版本开始输出思考链字段而之前的版本不输出这一变化就可能让你的 JSON Schema 校验直接失败。所以我会建议在中转平台里尽量锁定模型的具体版本号类似于不要用gpt-4o-latest这种浮动名称而是用带日期或版本号的固定别名。锁版本不能完全杜绝字段变化但至少降低了随机波动。在锁版本的基层上还要建立回归检查习惯。我自己的节奏是每次改造 OpenCode 或更新代理层配置之后挑一个固定场景通常是工具调用长文本输出的组合跑一遍全链路验证。这个过程不用完全自动化但一定要跑。很多兼容性问题是在不知不觉中冒出来的定期回归是成本最低的雷达。最后再分享一个小技巧如果你的中转 API 平台支持“响应体预览”或者“接口调试”功能尽量在接入之前就把各场景的响应体存下来做成静态样本。一旦线上出问题直接拿静态样本做对比测试比临时抓包快得多。我从第一次处理这类问题到现在这个习惯帮我省了大量时间。