很多人给 Cursor 配置第三方 OpenAI 兼容接口时会把“模型列表能刷新出来”当成接入成功。真正开始对话后却遇到验证转圈、model_not_found、400、404或者只看到一句模糊的“请求失败”。这类问题难查不是因为报错一定复杂而是我们常把三条本来独立的链混成了一条列出模型是一条链发送聊天请求是另一条链Cursor 把设置转换成实际 HTTP 请求又是第三条链。正确的目标不是反复改 Key、切模型或重装客户端而是拿到一组能证伪的证据最终请求发往哪个 URL使用哪个方法model的真实值是什么请求体带了哪些字段服务器返回什么状态码、响应头和错误正文。只要把这些证据固定下来就能在不猜测的前提下判断问题位于 Cursor、系统网络与代理还是上游接口。本文只讲通用工程方法。文中的第三方接口地址用于演示 URL 层级和最小请求不代表未列明的模型、价格、并发、稳定性或服务承诺。实际可用模型与参数必须以对应服务当前文档和账号权限为准。一、先改心智模型看到模型不等于能完成聊天Figure 1: Separating “can see the model list” and “can get a reply” into two independently verifiable capabilities.OpenAI 风格接口里模型发现通常是GET /v1/models聊天生成通常是POST /v1/chat/completions。前者主要验证域名可达、鉴权被接受、列表端点存在以及返回结构可解析后者还要验证目标模型是否允许聊天、消息格式是否被接受、参数组合是否合法、响应结构是否兼容。两个请求的方法、路径、请求体和服务端处理逻辑都不同所以前者成功不能推出后者成功。Cursor 又增加了一层客户端行为。设置页面保存的是 Base URL、密钥和模型选择但运行时可能追加路径、组装消息、加入流式或工具相关字段再通过客户端自身或其后端完成请求。Cursor 官方社区还说明自定义 API Key 只适用于标准聊天模型一些依赖专用模型的功能会继续使用内置模型。因此模型出现在选择器里也不能单独证明某个功能会按你预想的地址、密钥和模型发送。建议把接入状态写成四个独立断言而不是一个“成功/失败”按钮第一基础域名能够建立 HTTPS 连接第二模型列表请求成功且返回预期的模型 ID第三同一凭据对该模型的最小聊天请求成功第四Cursor 发送的实际请求与最小成功请求在关键字段上等价。只有四项都成立才能说接入链路完整。这套拆分还有一个好处修复动作不会越界。模型列表失败时先看域名、证书、代理和鉴权列表成功但最小聊天失败时看模型权限、路径和请求体最小聊天成功但 Cursor 失败时才进入客户端配置、版本和请求差异。每一步都有明确的下一项证据不需要用“换一个模型试试”代替诊断。实践中还可以为四个断言分别设置结果值pass、fail、not_tested。不要用“基本正常”这类不可计算的描述也不要因为最后一个聊天请求成功就覆盖前面曾经出现的失败。保留每个断言最近一次请求的时间、状态和证据位置能看出故障是在配置修复后消失还是仅仅一次重试碰巧成功。对于间歇问题连续样本的成功率和失败时间分布比单次截图更有价值但样本统计只能描述本次测试不能被写成服务长期可用性承诺。二、复现前先冻结变量避免每次测试都在换题图 2一张复现卡片应能让另一位工程师重放同一次失败。排错最常见的低级失误是在同一轮里同时修改 Base URL、模型、代理、密钥和提示词。最后请求偶然成功却不知道究竟哪个变化有效下次失败也无法回滚。更可靠的做法是先建立“复现卡片”把变量冻结测试时间与时区、Cursor 版本、操作系统、网络出口、是否经过公司代理、Base URL 的脱敏形式、模型 ID、请求模式、原始状态码、错误类型、请求 ID 和最短复现步骤。模型 ID 必须逐字符记录不能只写界面展示名。大小写、命名空间前缀、日期后缀和连字符都可能属于标识的一部分。密钥只记录来源环境、末四位或内部凭据编号绝不复制完整值。请求正文只保留复现需要的结构项目代码、用户提示词、文件内容和隐私数据不应进入共享日志。可以用如下表格作为每日排障记录字段应记录内容不应记录内容时间ISO 时间和时区“刚才”“上午”客户端Cursor 完整版本、系统“最新版”地址协议、主机、最终路径带查询凭据的完整链接模型API 请求中的精确 ID只写界面昵称错误HTTP 状态、类型、消息、请求 ID只写“调用失败”凭据环境名、内部编号、末四位完整 API Key冻结变量后先用一句固定的纯文本问题测试关闭文件附件、代码库上下文、图片、工具调用和复杂系统提示。这样得到的是“聊天最小能力”基线而不是一次把模型、长上下文、工具协议、上传、代理和流式解析全部压在同一个请求里。基线成功后再一次只恢复一个能力第一次失败的位置就是最有价值的差异。复现卡片还应区分“期望”和“观察”。期望可以是“客户端应向版本前缀下的聊天端点发送 POST”观察则必须写成“Network 显示向某路径发送 POST 并返回 404”。前者来自文档或设计后者来自运行事实。两者不一致时先保存原始观察再讨论应修改客户端配置、网关路由还是文档。只写期望会把假设伪装成证据只写观察又可能缺少判断标准把两栏并列排错讨论会清晰很多。三、Base URL 不是完整 Endpoint先画出最终 URL图 3配置项保存基础层级客户端再追加具体资源路径。排查 404 时不要先问“这个地址对不对”而要问“客户端最终请求的地址是什么”。一个常见地址层级可以拆为服务根地址https://api.vectorengine.cnOpenAI 兼容前缀https://api.vectorengine.cn/v1以及完整聊天端点https://api.vectorengine.cn/v1/chat/completions。在不同客户端里Base URL 字段可能期待根地址或带版本前缀的地址但通常不应直接填完整聊天路径Cursor 官方社区工作人员明确提醒客户端会自动追加/chat/completions如果配置里已经包含它最终可能变成重复路径。因此文档截图不能替代运行时证据。打开 Cursor 的开发者工具在 Network 中找到失败请求记录实际的 method 与 URL。重点检查五类拼接错误遗漏/v1出现两个/v1/v1出现两个/chat/completions/chat/completions把models请求和聊天请求发往不同主机发生 301、302、307 或 308 跳转后方法、请求头或目标路径与预期不同。还要区分 404 的来源。网关返回的 JSON 404 往往能给出路由或资源信息反向代理、WAF 或登录页返回的 HTML 404说明请求可能根本没到兼容接口。判断时同时看Content-Type和响应正文开头。如果页面是 HTML不要把它交给 JSON 解析器后只保留“解析失败”应先报告“HTTP 响应不是预期的 JSON”再附脱敏后的目标主机、状态码和响应类型。地址末尾斜杠也要通过最终 URL 判断而不是凭经验争论。健壮客户端会规范化斜杠某些简单拼接实现则会产生双斜杠。双斜杠可能被服务端归一化也可能命中不同路由。唯一可靠的结论来自 Network 或服务端访问日志中真正收到的路径。如果架构中还有反向代理和内部网关建议同时记录三种地址用户在 Cursor 中填写的配置值、客户端真正发出的外部 URL、网关转发到上游的内部 URL。三者经常不是同一个字符串。外部路径正确但内部转发遗漏版本前缀会表现为客户端怎么改都 404外部请求被网关重写到错误主机也可能让同一凭据在 curl 直连时成功、经代理时失败。访问日志应使用结构化字段分别保存原始路径和重写后路径避免只留下最终结果。四、用两条 curl 建立“模型发现”和“聊天生成”基线图 4同一环境、同一凭据、两个端点先建立可比较的基线。先在与 Cursor 相同的机器和网络出口执行模型列表请求。不要在另一台服务器上测通后就宣布本机没有网络问题因为 DNS、代理、证书信任和出口策略都可能不同。curl--silent--show-error --dump-header models.headers\-HAuthorization: Bearer${VECTORENGINE_API_KEY}\${BASE_URL}/models接着从返回数据中复制精确的模型id不要手工把展示名改造成一个看起来合理的值。再用同一 Base URL、同一环境变量和最小请求体执行非流式聊天curl--silent--show-error --dump-header chat.headers\--requestPOST${BASE_URL}/chat/completions\-HAuthorization: Bearer${VECTORENGINE_API_KEY}\-HContent-Type: application/json\--data{model:MODEL_ID_FROM_LIST,messages:[{role:user,content:只回复 ok}],stream:false}这两条命令的意义不在于“curl 比 Cursor 可靠”而在于把变量压缩到 HTTP 契约本身。结果可以形成四格矩阵两者都失败优先查网络、证书、域名和鉴权列表失败但聊天成功说明列表端点可能未实现或受限客户端若依赖模型发现仍可能失败列表成功但聊天失败重点查模型能力、权限、路径和请求体两者都成功但 Cursor 失败才把主要精力放到客户端运行时差异。使用--verbose、--trace或--trace-ascii前要格外谨慎。curl 官方手册明确提醒详细跟踪可能包含用户名、凭据或敏感正文。优先使用--dump-header、--write-out和最小正文必须共享 trace 时先复制到临时文件删除 Authorization、Cookie、查询参数、项目内容与可识别信息再由第二人复核。不要在群聊里直接粘贴终端全部输出。基线请求还应固定超时并保存退出码。curl 没有收到 HTTP 响应时退出码能区分名称解析、连接、TLS 和超时等阶段收到 HTTP 响应后则把传输是否完成与业务状态是否成功分开。若脚本只判断进程退出码为零就可能把 HTTP 401 或 500 当成“请求已完成”若只判断状态码又会丢失根本没有状态行的连接错误。自动测试需要同时保存进程结果、HTTP 状态、响应类型和结构断言。五、模型 ID 可见只证明“被列出”不证明“可用于当前请求”图 5真正可用的模型位于标识、权限、端点和客户端功能的交集。模型列表返回一个 ID至少说明服务愿意在当前凭据下暴露这个资源标识它不自动证明该 ID 支持 Chat Completions更不证明支持 Cursor 当前功能所需的工具调用、流式格式、图片输入或特定消息角色。OpenAI 官方模型与聊天参考也把模型资源和聊天创建定义为不同的 API 操作。遇到model_not_found时按顺序验证四件事。第一从原始列表响应复制 ID比较 Unicode、大小写、空格、命名空间和日期后缀。第二用GET /models/{id}若服务实现确认单个资源能否查询。第三用最小聊天请求验证该 ID 是否允许当前端点。第四再回到 Cursor 检查界面选中的模型是否真的映射成同一个请求值。如果上游文档把“模型名称”“部署名称”“路由别名”分开就不要混用。某些系统在列表中展示基础模型名但实际调用要求部署名另一些网关允许自定义别名但别名只在特定项目或凭据范围内有效。文章不能替具体服务下结论诊断时应把服务端当前文档、账号控制台和真实响应三者对齐。Cursor 的功能边界同样重要。官方社区答复指出自定义密钥用于标准聊天模型部分专用功能仍走内置模型。这意味着“聊天能用、Tab Completion 不走自定义接口”可能是产品边界而不是同一个 API 调用失败。排错记录必须写清触发的是 Chat、Agent、Tab Completion 还是其他入口不能把不同功能的网络请求混为一谈。最后别用模型自我介绍判断路由是否正确。模型可能根据提示词或训练数据回答错误名称。更可靠的证据是请求中的model、响应中的模型字段若有、服务端请求 ID、账号侧可核对记录以及最小对照实验。自我陈述只能作为线索不能作为路由审计证据。还要警惕缓存造成的假象。模型列表可能被客户端缓存设置页里仍显示已经下线或当前凭据无权使用的 ID反过来新模型也可能尚未出现在本地列表。测试时记录列表响应的获取时间必要时用独立 HTTP 请求重新读取并把缓存数据与实时响应分开。不要为了让界面出现某个名字就手工添加并直接执行复杂任务手工添加只解决选择器可见性不能创造上游权限和端点能力。六、从最小请求逐项加回字段找出第一个不兼容参数图 6最小请求成功后一次只恢复一个字段或能力。OpenAI compatible 不是一个“所有字段完全相同”的认证标志。服务可能实现模型列表和基本聊天却不接受某些消息角色、工具定义、响应格式、推理参数或多模态内容。最有效的办法不是堆更多参数碰运气而是把 Cursor 失败请求与 curl 成功请求做结构化差异比较。先保留model、单条 user message 和stream:false。成功后依次恢复system/developer message多轮历史stream:true温度或最大输出长度工具定义工具选择结构化输出文件或图片长上下文。每次只加一类字段并记录状态码、错误正文和请求 ID。第一个从成功变为失败的变化就是上游契约差异或客户端行为差异的候选原因。下面的伪配置展示的是比较思路不是向量引擎已确认的功能清单{baseline:{model:MODEL_ID_FROM_LIST,messages:[{role:user,content:只回复 ok}],stream:false},next_probe:add_one_capability_only,evidence:[http_status,content_type,error_type,request_id]}400 或 422 的错误正文通常比状态码更有价值。若错误指出 unknown parameter、unsupported role、invalid type 或 missing field应按字段处理而不是立刻轮换密钥。若服务把所有请求问题都折叠成同一种错误则需要从反向代理访问日志或网关结构化日志补证但日志依然只记录字段名、大小、哈希或分类不记录提示词正文与凭据。对流式问题要单独做 A/B相同请求体只切换stream。非流式成功、流式失败才进入 SSE、代理缓冲与事件解析两者都失败就不应先调网络分块。这样也能避免和“HTTP 200 但客户端空白”混淆当前章节先确认请求契约是否被接受解析链应在服务端已返回合格响应后再检查。差异比较最好在规范化之后进行删除动态请求 ID、时间戳和无关头将 JSON 键排序把凭据值替换为占位符再比较字段集合与类型。这样能避免被每次都变化的噪声干扰。比较结果至少分为“Cursor 新增”“Cursor 缺失”“值不同”“类型不同”四类。服务端提示某字段不支持时优先验证它是否由客户端必然添加若无法关闭该上游即使支持最小 Chat Completions也未必满足当前 Cursor 工作流。七、按状态码和响应类型分流不要把所有错误都归因于 Key图 7状态码只给出类别响应正文和请求 ID 才能收窄原因。RFC 9110 说明状态码描述请求结果与响应语义4xx 指向请求侧问题5xx 指向服务器未能完成看似有效的请求。但同一状态仍有多种原因必须结合响应类型、错误对象、最终 URL 和请求 ID。下面的表用于决定下一步证据不是替代上游文档的万能答案。现象优先检查不要先做无 HTTP 状态DNS、TLS、代理、超时阶段连续更换模型401Bearer 头、密钥来源、项目范围、最终主机把完整 Key 发给他人403资源权限、账号范围、策略拒绝假定 Key 拼写错误404最终路径、重复拼接、模型资源、HTML/JSON盲目重装 Cursor400/422错误正文、请求字段、类型和角色只重试相同请求429速率与额度类错误的具体类型、Retry-After无限立即重试5xx请求 ID、发生时间、可重试性、上游状态修改已验证的 Base URLOpenAI 官方错误指南把无效认证、权限、限流、额度和服务端错误分开处理也建议持续故障时保留模型、错误消息与代码、请求时间和相关请求信息。迁移到兼容接口时具体错误名称可能不同但“分类后再行动”的方法仍成立。还要注意客户端内部错误码可能不是 HTTP 状态。比如 JSON 解析异常、连接重置、证书错误或扩展报错不应被硬映射成 500。记录中应分开transport_error、http_status、api_error.type和client_exception。只有服务端真的返回了状态行才填 HTTP 状态。若响应头提供x-request-id或类似追踪标识应与 ISO 时间、模型 ID 一起保存。它能让服务端在不读取完整提示词的情况下定位请求。请求 ID 本身也不该被当成授权凭据但若内部策略认为它可关联敏感记录仍应只在受控工单中共享。重试策略也必须服从错误分类。确定的 400、401、403 和 404 通常需要先修改请求或权限原样高频重试只会制造噪声暂时性 429、503 或网络抖动才可能进入有上限的退避。任何重试都要带最大次数、总时间预算和幂等性判断并保存最终一次与首次错误。否则客户端可能用多次失败换来一次成功把真实故障隐藏成“偶尔慢”还会放大上游压力。八、在 Cursor 中观察真实请求而不是相信设置页面的样子图 8设置值只是输入Network 中的实际请求才是运行事实。当 curl 基线成功而 Cursor 失败时进入 Cursor 的Help Toggle Developer Tools。先看 Network再看 Console官方故障指南与社区答复还建议记录系统信息、请求 ID并可从Developer: Open Logs Folder获取日志。观察时只触发一次最小对话避免后台请求把列表淹没。在 Network 中寻找模型列表、验证和聊天相关请求逐项记录请求方法最终 URL是否重定向状态码Content-Type请求体中的模型值和字段名响应错误对象耗时阶段。Authorization、Cookie 和完整正文不要复制。若开发者工具支持“Copy as cURL”复制后必须先把所有凭据替换成环境变量并删除与项目、账号、设备有关的头再运行或分享。设置页面看起来正确但 Network 不一致通常可归入三类。第一设置没有保存或被旧值覆盖表现为请求仍发往旧主机。第二客户端自动拼接与手工路径叠加表现为重复/v1或/chat/completions。第三所选功能并未使用自定义密钥表现为请求目标、鉴权路径或模型与预期不同。不要只看按钮是否变绿要把 UI 值和网络事实逐字段对照。Console 适合补充客户端异常例如请求体序列化失败、响应解析错误或扩展冲突但 Console 中的报错可能是后果不是根因。先找到对应 Network 请求若根本没有请求再查客户端状态若有请求且上游返回明确错误先处理协议若请求成功但 UI 仍失败才查响应解析和界面状态。日志文件也要限定时间窗。复现前记下时间执行一次请求随后只截取前后几十秒。分享前搜索Authorization、Bearer、api_key、Cookie、用户目录、仓库名和提示词片段。保留版本、错误栈、请求 ID、状态码与字段名移除值。这样既能复现又不会把排错变成新的泄露事件。若 Network 面板看不到请求不要马上认为 Cursor 没有发起网络访问。先确认过滤条件、保留日志选项和目标窗口是否正确再从 Console 与日志目录查找对应时间的客户端异常。某些请求可能由不同进程或后端完成开发者工具只能看到其中一部分。此时结论应写成“当前面板未观察到请求”而不是“请求一定没有发送”再用服务端访问日志和代理日志做交叉验证。九、用三组对照实验定位 Cursor、网络代理还是上游图 9对照实验改变一个变量用结果交集定位故障层。第一组是“同机直连对照”在运行 Cursor 的同一台机器用 curl 发送最小请求。curl 与 Cursor 都失败说明客户端特有问题的优先级下降curl 成功而 Cursor 失败说明上游具备最小能力应比较两者最终 URL、请求体和网络路径。第二组是“代理路径对照”保持请求完全相同只改变是否经过系统代理或公司出口。这里必须遵守组织网络规则不能为了测试绕过安全策略。若直连和代理结果不同记录 DNS 解析、TLS 证书颁发者、HTTP 状态、响应头与耗时阶段交给网络管理员核验。不要根据一篇帖子把问题简单归结为 HTTP/2 或地区只有可重复的同请求对照才能支持该判断。第三组是“请求复杂度对照”同一网络与上游比较最小非流式请求、流式请求、带工具请求和 Cursor 实际请求。只有某一能力加入后失败故障范围就缩小到该字段、协议阶段或客户端解析。若 Cursor 请求带有上游不认识的参数可以在自建网关中进行显式转换或拒绝但不应静默删字段后返回看似成功的结果静默兼容会让调用者误以为工具或约束已生效。把结果写成决策表更直观curl 最小请求Cursor 最小对话主要排查方向失败失败域名、TLS、代理、鉴权、上游最小契约成功失败Cursor 最终 URL、模型值、附加字段、功能边界成功成功复杂任务失败流式、工具、上下文、附件与响应解析间歇成功间歇失败时间相关证据、限流、超时阶段、上游波动对照实验的结论应写成“证据支持什么”而不是“肯定是谁的锅”。例如“同机 curl 在 09:10 成功Cursor 在相同模型与主机返回 404Network 显示最终路径重复了 chat/completions”这是可复核结论“Cursor 不兼容这个平台”则过于宽泛无法指导修复。如果条件允许再增加一台干净测试机或一个新建的 Cursor 配置作为辅助对照但不要一开始就清空现有应用数据。清理应用数据会改变大量变量也可能删除扩展和设置它适合在证据已指向本地状态损坏、且用户完成备份后执行。排错优先级应是只读观察、最小请求、单变量修改最后才是大范围重置。这样既减少副作用也保留最初失败现场。十、把排错步骤固化成契约测试防止升级后再次失效图 10把一次人工排错变成可重复的兼容性契约。接入跑通后不要只留一张成功截图。建立一个不含业务数据的契约测试集至少覆盖模型列表返回对象数组目标模型 ID 可引用最小非流式聊天返回可解析的消息错误请求返回结构化错误而不是 HTML流式模式按预期结束未知字段得到明确拒绝请求 ID 或等价追踪字段可用于定位。若团队依赖工具调用再单独加入工具协议测试。测试脚本要把“传输成功”和“业务契约成功”分开。下面的 Node.js 示例只演示通用检查方式模型与能力仍以目标服务文档为准constbaseUrlprocess.env.BASE_URL;constapiKeyprocess.env.VECTORENGINE_API_KEY;constmodelprocess.env.MODEL_ID;if(!baseUrl||!apiKey||!model){thrownewError(BASE_URL、VECTORENGINE_API_KEY、MODEL_ID 均为必填环境变量);}constresponseawaitfetch(${baseUrl}/chat/completions,{method:POST,headers:{Authorization:Bearer${apiKey},Content-Type:application/json},body:JSON.stringify({model,messages:[{role:user,content:只回复 ok}],stream:false})});constcontentTyperesponse.headers.get(content-type)||;constrequestIdresponse.headers.get(x-request-id)||missing;constrawawaitresponse.text();if(!response.ok){thrownewError(HTTP${response.status}; request_id${requestId}; body${raw.slice(0,300)});}if(!contentType.includes(application/json)){thrownewError(unexpected content-type:${contentType});}constdataJSON.parse(raw);if(!Array.isArray(data.choices)||data.choices.length0){thrownewError(response has no choices);}console.log({requestId,model:data.model||model,ok:true});将测试放在版本升级、代理配置变更和网关发布前后运行。结果保存状态、类型、耗时、请求 ID 和结构断言不保存完整提示词与回复。出现差异时先确认是哪一条契约变化再决定回滚客户端、修正网关适配还是更新允许的能力范围。如果上游只承诺“部分 OpenAI 兼容”团队应维护一份明确的兼容矩阵端点、方法、必填字段、可选字段、流式、工具、多模态、错误结构。矩阵比“兼容 OpenAI”四个字更能指导 Cursor、Dify、Chatbox 或自建脚本的接入也能防止开发者把某个客户端的成功偶然推广成所有客户端都可用。契约测试的失败输出也要可读。不要只抛出assert failed而应报告断言名称、期望类型、观察到的类型、状态码、内容类型和请求 ID。对响应正文只保留安全长度的脱敏前缀并把原始证据放进受控存储。这样 CI 中的红灯能直接指向“模型列表结构变化”或“聊天错误页变成 HTML”而不是逼迫值班人员重新手工复现整条链路。十一、安全交接与最终检查清单图 11修复完成不等于任务结束还要完成脱敏、复测和记录。当你准备把问题交给同事、网络团队或接口提供方时最有用的材料是一个最小证据包复现时间与时区Cursor 和系统版本功能入口脱敏后的最终主机与路径模型 IDHTTP 状态、错误类型与短消息请求 ID同机 curl 对照结果从成功基线到失败请求的字段差异。任何完整 API Key、Cookie、项目文件、用户提示词和原始 trace 都不应进入公开工单。如果必须给接口方验证权限应使用组织批准的临时凭据或受控测试项目并遵循最小权限和到期回收流程。不要把生产 Key 粘进聊天窗口也不要把 Key 放在截图、命令历史或代码仓库中。OpenAI 官方 API 概览同样建议将密钥放在服务端环境变量或密钥管理系统而不是暴露在浏览器或应用客户端代码里。最终验收可以按以下顺序执行Network 中最终 URL 没有重复路径方法正确。模型 ID 来自当前账号可见列表或官方控制台并用最小聊天验证。curl 与 Cursor 在同机、同网络、同模型下形成可解释的对照结果。400、401、403、404、429、5xx 分别按错误正文处理没有用同一套重试掩盖。非流式成功后才启用流式基础聊天成功后才加入工具、附件和长上下文。日志只保留时间、版本、状态、字段名、请求 ID 与脱敏摘要。修复步骤已转成契约测试并在升级前后重放。结论写明证据边界没有把某次成功写成平台长期能力承诺。如果你还需要核对通用接口层级和接入示例可把 https://178.nz/dn 作为延伸技术资料入口但其中任何具体能力仍应回到当前官方文档与实际请求逐项验证。交接完成后还应处理临时证据删除包含敏感头的原始导出撤销或到期回收测试凭据确认工单附件已经脱敏并把最终结论写回团队知识库。知识库不应只保存“怎么修好”还要保存最小复现、错误分类和验证方法。下次客户端或网关升级时工程师可以直接重放契约而不是从聊天记录里寻找一条过时的配置截图。最后做一次反向验收让一位没有参与本次排错的同事只依据复现卡片和最小脚本重放。如果对方需要口头补充完整密钥、特殊网络操作或未记录的模型别名说明文档仍不完整如果对方能得到相同状态和请求 ID并能解释每一步为何执行说明证据链已经可迁移。对于无法公开的环境差异可以记录为受控前置条件而不是省略。这样形成的排错资产既能服务当前 Cursor 问题也能迁移到其他遵循相似 HTTP 契约的客户端同时保持对具体产品能力边界的谨慎。复测通过后应保留一条已知失败用例例如使用不存在的模型标识或明确不支持的字段确认客户端仍能展示结构化错误而不是吞掉响应。只有成功路径和失败路径都可观察团队才知道未来升级究竟修复了兼容性还是仅把错误隐藏在界面背后。失败用例不得使用生产数据也不能触发高频重试。真正高效的排错不是记住更多“某某错误怎么办”而是让每个结论都能被下一条请求证实或推翻。模型列表成功只是起点聊天契约、客户端实际请求、网络路径和响应解析都需要独立证据。把这四层拆开Cursor 第三方接口问题就从模糊的“不能用”变成一组可以定位、复现、修复和回归的工程问题。参考资料Cursor Community Forum, Custom Model API Key: https://forum.cursor.com/t/custom-model-api-key/145897Cursor Community Forum, The openai custom api toggle does not toggle: https://forum.cursor.com/t/the-openai-custom-api-toggle-does-not-toggle/109797Cursor Community Forum, Custom OpenAI API Key Verification Stuck: https://forum.cursor.com/t/custom-openai-api-key-verification-stuck/96185OpenAI, API Overview: https://developers.openai.com/api/reference/overviewOpenAI, Models API Reference: https://platform.openai.com/docs/api-reference/models/chatOpenAI, Chat Completions API Reference: https://developers.openai.com/api/reference/resources/chatOpenAI, Error codes: https://developers.openai.com/api/docs/guides/error-codescurl project, curl man page: https://curl.se/docs/manpage.htmlRFC Editor, RFC 9110: https://www.rfc-editor.org/rfc/rfc9110.html