How do I set up Cline with a custom OpenAI-compatible endpoint?

所谓给 Cline 接自定义的 OpenAI 兼容接口，是指不再用它默认的厂商入口，而是让它的请求发往你指定的网关或兼容服务。兼容的意思是接口的请求格式和官方接口一致，换服务时不用改调用方式，但地址、密钥和模型名这三项仍要一一对齐。只填地址、不对齐模型名，是这类配置最常见的翻车方式。本文先讲兼容接口到底由哪几项决定，再按步骤讲怎么填、怎么验，帮你在动手之前先把对照关系理清楚。

兼容接口由哪几项共同决定？

兼容接口生效需要四项对齐：接口地址、密钥、模型名、服务商类型。地址决定请求发往哪里，密钥决定对方认不认你，模型名决定对方按哪个模型处理，服务商类型决定 Cline 用哪套请求格式去对话。四项里任何一项错了，表现都可能是笼统的连接失败，让人误以为只是地址问题。动手之前先把四项写下来：对方文档里的示例地址、配套密钥、对方清单里的模型名、以及应该选的服务商类型，缺一项就先别填。还有一个容易被忽略的细节：地址末尾的路径段。有的服务要求地址本身含路径段，有的则由客户端自动补，重复或缺失都会导致找不到入口，照抄对方文档的示例结构最稳妥。

应该先在哪里填，现有配置要不要先备份？

填新配置之前，先把现有能用的配置备份下来，这是换服务时最重要的保险。备份的办法不复杂：把当前服务商类型、地址、模型名记下来，或者把配置文件复制一份放在一边，写明备份日期。备份的作用是：新配置调不通时，能立刻回到原来能用的状态，而不是在新旧配置之间来回猜。新配置建议先填在单独的位置测试，不要直接覆盖原来唯一能用的配置，确认新配置能通、能完成小任务后，再决定要不要把它设为默认。测试期间如果两个配置来回切换，要每次都确认当前生效的是哪一个，界面上显示的和实际生效的可能不一致，确认办法是发测试请求、看返回和用量记录。

具体步骤是怎样的？

第一步，先在新服务侧拿到三样东西：接口地址、密钥、模型清单里的模型名，缺一不可。第二步，打开 Cline 的设置，找到服务商类型，选择与兼容接口对应的那一项，不要选成官方厂商的直连类型。第三步，填入接口地址和密钥，并把模型名设为对方清单里的名字，不要沿用旧服务的模型名。第四步，保存后先不要直接跑大任务，而是发一个极短的测试问题，确认能通、返回内容正常、用量记录里出现的是新模型。第五步，确认测试通过后，再用它做一个真实的小任务，例如改一处小代码并检查结果，确认工具调用和文件编辑都正常。第六步，跑完小任务后回头核对一次：返回里标注的模型是不是你设的那一个，用量记录里是不是新服务在计费。步骤里最容易被跳过的是第四步和第六步，而恰恰是这两步在替你确认“真的接过去了”。

怎么确认请求真的走了新接口？

只看“能出结果”是不够的，因为配置没生效时，工具可能悄悄走了旧入口，照样能出结果。可靠的确认办法有三层。第一层看返回：有的服务会在返回里标注实际服务的模型，核对它是不是你设的名字。第二层看用量：登录新服务的用量或账单页，确认刚才那次测试确实记在新服务名下。第三层看旧服务：旧服务的用量在测试时间段内没有新增，才说明旧入口真的没再被走。三层里任何一层对不上，都要停下来排查，而不是继续跑任务。还有一个辅助信号是返回风格：不同服务的延迟和报错文案往往不同，换服务后表现和以前完全一样，反而值得怀疑是不是根本没换过去。

填对了还是报错，先查哪几处？

报错时按固定顺序排查，不要同时改好几处。先查服务商类型：是不是选成了官方直连类型，导致请求格式和兼容接口对不上。再查地址结构：末尾有没有多余的斜杠、路径段有没有重复、是不是把网页控制台的地址当成了接口地址。接着查密钥：是不是拿错了另一服务的密钥、密钥有没有多余空格、有没有被轮换过。最后查模型名：是不是用了旧服务的模型名、大小写和连字符有没有抄错。每次只改一处、改完测一次，改动记录写下来。最忌讳的做法是类型、地址、密钥、模型名一起换，好了也不知道是哪一处起的作用，下次再出问题又要从头猜。

模型名和工具调用有什么关系？

模型名不只是名字，它还决定了对方按哪个模型处理你的请求，而不同模型对工具调用的支持程度不同。有的模型能稳定地按格式调用文件编辑和命令执行，有的模型则容易在工具调用上出错，表现为反复重试、格式错乱或任务卡住。选模型之前，先确认它在对方清单里确实存在，并且支持你需要的工具调用能力，缺了这项能力，接口通了任务也跑不好。还有一种情况：对方清单里根本没有你原来用的那个模型，这时要先选一个清单里确实有的替代模型，而不是强行沿用旧名字。选好替代模型后，先用小任务验证工具调用是否正常，再投入正式任务，验证通过的模型名写下来，团队其他人接手时不用重新猜。

换接口之后，旧配置怎么处理？

换接口成功后，旧配置不要立刻删除，先留一段时间作为回退路径。留存的办法是：把旧配置的四项记下来放在一边，标明停用日期和停用原因，确认新配置稳定运行一段时间后再清理。清理之前还要检查两件事：有没有其他项目或同事还在用旧配置，有没有定时任务绑定了旧配置。直接删除旧配置最常见的后果是：新服务一出问题，旧入口也找不回来了，只能从头重新配置。回退路径的价值平时看不出来，出问题时就是它在替你省时间。等新配置稳定运行、且确认没有其他依赖后，再清理旧配置，清理时同样记一笔，写明清理日期和清理人。

这篇教程有哪些局限？

本文只讲了接兼容接口的通用方法，没有针对任何一家具体服务写配置，因为各家服务的地址结构、模型名和认证方式会随版本变化，今天写对的示例明天可能就过时。界面路径和选项名称在不同版本里也可能改动，动手时要以你所用版本的官方文档为准，本文的步骤是核对清单、不是逐键操作指南。另外，本文没有讨论自托管服务的部署和内网穿透，那是另一类工作，不在接接口的范围内。涉及生产代码的项目换接口之前，建议先在测试项目里完整走一遍六步，再切正式项目。

简而言之，怎样接兼容接口才稳？

稳妥的接法是四项对齐、先备份、按步骤验、三层确认再切正式任务：服务商类型、地址、密钥、模型名四项缺一不可，动手前备份旧配置，小请求先验、真实小任务再验，返回标注、用量记录和旧服务用量三层确认真的走了新接口。任何一层对不上就停下来按顺序排查，每次只改一处。换过去之后把对照关系和回退方法写下来，旧配置留一段时间再清理。先立对照、再做实测，让新服务用返回和账单证明自己，而不是用“能出结果”自我安慰。

来源与延伸阅读：FreeModel 关于页：它是什么、不是什么、FreeModel、Cline 官方文档、Cline 产品页、实测免费网关对比、十四家网关公开模型清单实读。