奇 奇连 AI
学习路线图课程工具计算器企业服务关于加入会员

Cline 接自定义 OpenAI 兼容 API：三个必填项怎么填才不出错

2026-08-07

Cline 里配自定义模型，第一个要盯紧的不是模型选得好不好，而是 Base URL 那一栏填的到底是谁的地址。你以为在填”OpenAI 的地址”，其实要填的是你那家服务商的地址——这两件事听着像一回事，实际是完全相反的两个填法。Cline 官方文档在 OpenAI Compatible 这一页专门提示了这一点：这里不会是 https://api.openai.com/v1，那是官方 OpenAI API 的地址（截至 2026-08-07 官方文档，下同）。

这篇只讲 Cline 一家怎么接。站内另外几篇是不同分工：编辑器接自定义 API 的通用做法 讲的是各家编辑器横向对比、字段名怎么对应；Cursor 配自定义模型 讲的是 Cursor 那一套的具体操作；OpenAI 兼容端点是什么 讲的是”兼容端点”这个概念本身、协议层面为什么能互换。本篇是三者中最窄的那一块：只把 Cline 这个表单填对。

一、“接自定义 API”到底解决的是哪个问题

先把两件常被混为一谈的事分开。

接入方式，说的是你的工具通过哪条网络路径、用哪套请求格式去找模型。模型能力，说的是那个模型本身会不会写代码、能不能调工具、能吃多长的上下文。接入方式配对了，能力不行，照样干不了活；能力再强，接入方式配错，你连一个字都拿不到。

所谓 OpenAI 兼容端点，一句话：某家服务商把自己的 API 做成了和 OpenAI 那套请求／响应格式一样的样子，于是任何”会说 OpenAI 话”的客户端都能直接连它，不用改代码。Cline 的 OpenAI Compatible 这个 provider，就是给这类端点准备的通用插头。

所以你要接一个自建网关、一个国内服务商、一个推理平台，只要它自称 OpenAI 兼容，走的都是这一条路：API Provider 选 OpenAI Compatible。不是选 OpenAI——选 OpenAI 意味着你要连官方那家；也不是去找有没有对应品牌的专属选项，通用插头就是通用插头。

二、三个必填项，各自会以什么方式失败

Cline 文档在这一页列的必填项就三个：Base URL、API Key、Model。少填任何一个都跑不起来，但三个填错的症状完全不同，分清症状能省掉大量瞎试的时间。

配置项它是什么填错的典型表现出处
Base URL服务商给你的 API 端点地址请求根本没到目的地，或者到了一个不认识你密钥的地方Cline 文档明确提示这里不会是 https://api.openai.com/v1
API Key服务商给你的密钥；也可勾选使用 Azure 托管身份认证（Azure managed identity）地址通了但被拒，鉴权层直接挡回来Cline 文档列为必填项
Model选择或输入具体的模型 ID地址和密钥都对，但服务端说不认识你要的这个模型Cline 文档列为必填项

表里的字段名是 Cline 文档里的写法。这里要特别强调一句：不要把别家的字段名套过来。Continue 那边叫 apiBase，Zed 的 settings.json 里叫 api_url，goose 用的是环境变量 OPENAI_HOST（另有 OPENAI_BASE_PATH），Crush 的命令行参数是 --base-url。它们表达的是同一件事的不同实现，但名字不通用，串台就是配不出来。Cline 界面里就叫 Base URL，照这个找。

关于 API Key 的存放，各家取向差别很大。Zed 的文档原话是 “Do not put API keys in settings.json.”，并说明通过 Zed 保存的 provider key 存在系统 keychain 里——keychain 就是操作系统自带的凭据保管库，密钥加密存在系统里而不是躺在明文配置文件中。Gemini CLI 那边支持在 settings.json 里用 $VAR_NAME 或 ${VAR_NAME} 做环境变量插值（加载配置时把变量名替换成环境变量的实际值），这样配置文件能进版本库而密钥不进。Cline 这边是图形界面表单填写，你至少要意识到：密钥别粘进任何会被提交进 git 的文件。密钥本身怎么管，可以看 API 密钥安全管理。

三、Base URL 为什么填官方 OpenAI 那个地址一定不对

这条值得单独拆开讲，因为它是最反直觉的一个。

很多人的心理模型是这样的：既然选的 provider 叫 “OpenAI Compatible”，那 Base URL 就应该填 OpenAI 的地址，然后在 Model 那栏填自己想用的模型。这个推理链每一步看着都通，结论完全错。

正确的心理模型是：https://api.openai.com/v1 指向的是官方 OpenAI 那台服务器。你把它填进去，Cline 就老老实实把请求发去 OpenAI，带着你从别家拿的密钥、请求一个 OpenAI 不认识的模型 ID——三件事全对不上。这不是”配得不够好”，是发错了地方。

Cline 文档给的 v0 Quickstart 示例可以当参照：Base URL 填 https://api.v0.dev/v1，Model ID 填 v0-1.0-md。注意这个示例里 Base URL 是带 /v1 的。

/v1 这个尾巴要不要带，是另一个高频坑，而且各家规则不统一：Zed 文档示例写的是 https://example.com/v1；Groq 官方的 base URL 是 https://api.groq.com/openai/v1；Kilo Code 文档明确说它两种形态都接受，标准形态 https://api.provider.com/v1 和完整端点 https://api.provider.com/v1/chat/completions 都行，后者是给端点结构非标准的服务商和自建网关准备的。goose 则是把地址拆成 OPENAI_HOST 和可选的 OPENAI_BASE_PATH 两段。

结论很简单：以你那家服务商官方文档写的那个字符串为准，一个字符都别改。别凭印象加 /v1，也别凭印象删掉。服务商文档给什么，你复制什么。

四、Model Configuration 里那几项，是在替模型”报户口”

选完模型之后，Cline 还有一个 Model Configuration 区，文档列出的可自定义项有：Max Output Tokens、Context Window size、Image Support、Computer Use、Input Price、Output Price。

这几项存在的理由是：Cline 对官方那些常见模型有内置的参数认知，但对你接进来的自定义端点没有——它不知道这个模型能吃多长的输入、最多吐多少 token、支不支持读图。所以要你手动告诉它。

上下文窗口（Context Window）指模型单次请求能容纳的 token 总量，包括你的提示词、代码上下文和它的输出。这个数填小了，Cline 会比实际更早地开始裁剪上下文，明明模型吃得下的代码被截掉；填大了则相反，请求超出模型真实上限直接被服务端打回。这一项不是 Cline 独有的负担：Roo Code 也要填 Context Window，Zed 的 available_models 里要写 max_tokens，aider 要在 .aider.model.metadata.json 里注册 max_input_tokens / max_output_tokens。凡是接自定义端点，这笔账基本都得自己报。

Input Price 和 Output Price 这两项是给你自己看用量估算的，填的是你从服务商那里查到的实际单价。这里提醒一句：aider 文档里 .aider.model.metadata.json 那个示例带的单价数字是官方文档的示例值，不是任何真实模型的报价，别抄。价格一律去服务商官方页面查。

五、边界与代价：这条路放弃了什么

自定义 OpenAI 兼容端点是通用插头，通用的代价是它不替你保证任何东西。

它不管模型会不会调工具。编程 Agent 干活靠的是原生工具调用（function calling）——模型按结构化格式吐出”我要调这个工具、参数是这些”，客户端解析后真去读文件、改代码。这件事在不同产品那里是硬门槛：Roo Code 官方文档的原话是 “Roo Code uses native tool calling exclusively. This is the only supported tool protocol — there is no XML-based fallback.”，并建议先查服务商文档确认所选模型是否支持工具调用。这是 Roo Code 文档的说法，不是本文对所有产品的断言；但它揭示的机制是通用的：你接进来的端点即便连得上，模型不支持函数调用，Agent 类的活也做不了。Continue 那边有 capabilities.tool_use 这个开关，Zed 的 capabilities 里包含 tools、parallel_tool_calls，都是同一件事的不同表达。

**它不管超出聊天补全之外的活。**Continue 的 roles 字段取值有 chat、autocomplete、embed、rerank、edit、apply、summarize，默认是 [chat, edit, apply, summarize]——注意 embed（嵌入，把文本转成向量供检索）和 rerank（重排，对检索结果重新排序）默认并不在内。这说明”我配了一个模型”和”这个模型能承担所有角色”完全是两码事。Cline 这边的 OpenAI Compatible 配置解决的是对话补全那条链路，别指望它顺带把检索侧的模型也配好了。

**它不管服务端的非标准行为。**Kilo Code 文档就明确提醒过一类情况：Azure 的 GPT-5 不要用通用 OpenAI 兼容 provider，要用它原生的 azure provider，因为 Azure 会拒绝 max_tokens 参数。这类”看着兼容、细节不兼容”的情况，通用插头兜不住。

什么场景不适合走这条路：如果你的服务商在 Cline 里已有专属的 provider 选项，优先用专属的；只有在没有专属选项、或者你连的是自建网关时，OpenAI Compatible 才是那个正解。

六、避坑清单

坑一：Base URL 填成 https://api.openai.com/v1。 为什么会踩：provider 名字里带 “OpenAI”，直觉上就往官方地址填。 怎么避：记住 provider 名字描述的是协议格式，不是目的地。Base URL 只能是你那家服务商给的地址，Cline 文档专门写明了这里不会是官方 OpenAI 那个地址。

坑二：/v1 自作主张地加或减。 为什么会踩：见过别家示例带 /v1，就以为是通行规则。实际上 Kilo Code 明确接受两种形态，goose 干脆把地址拆成两段配，各家不一样。 怎么避：只复制服务商文档里的原始字符串。改动之前先确认服务商文档怎么写。

坑三：把别家的字段名当成 Cline 的。 为什么会踩：搜到的教程混着写，apiBase、api_url、OPENAI_HOST、--base-url 看着都像”那个地址”。 怎么避：认准配置形态。Cline / Roo Code / Kilo Code 是图形界面表单；Continue、aider 是 YAML 配置文件；Zed、Gemini CLI 是 JSON settings；goose、Crush 走环境变量和 CLI 子命令。形态不同，字段名不可能通用。

坑四：Model 那栏凭记忆填模型 ID。 为什么会踩：模型的”商品名”和 API 里的模型 ID 经常不是一回事，凭印象敲多半差几个字符。 怎么避：从服务商文档或控制台里复制粘贴。Cline 这一项文档写的是”选择或输入具体的模型 ID”，输入的时候没有容错。

坑五：Context Window size 随手填个整数。 为什么会踩：这一栏不填不影响连通性，于是先跑起来再说，问题要到长文件场景才暴露。 怎么避：接完之后立刻回去把这一项按服务商标注的真实上下文上限填准，别等到 Cline 莫名其妙截断你的代码上下文才去查。

坑六：连上了就默认能当 Agent 用。 为什么会踩：对话能出字，看着一切正常，但 Agent 模式一跑就卡住或者胡乱输出。 怎么避：接入前先去服务商文档确认这个模型是否支持函数调用。连通性和工具调用能力是两个独立的验收项，要分别验。

排查阶段还有一个通用建议：先判断故障在哪一层。请求发不出去、超时、DNS 解析失败，是 Base URL 层；返回 401 / 403，是密钥层，可以对照 API 401/403 排查；返回”模型不存在”一类的错误，是 Model 层。三层分开看，比对着表单一栏栏乱改高效得多。

数据来源与核对日期

本文引用的产品事实，来源如下，核对日期均为 2026-08-07：

本文没有写什么，以及为什么：任何产品的价格、免费额度、订阅档位、限速数字、版本号、完整模型清单，本文一律不写。这类信息变动频繁，写下来的当天就可能过时，且本次未做逐条核实；aider 文档示例里出现的单价数字只是文档示例值，不构成任何报价参考。各家界面的逐级菜单层级也未写——界面改版比文档更快。请以各产品官方文档的最新版本为准；上述所有描述反映的是核对日当天官方文档页面的内容，之后可能变化。

延伸阅读：同一组里的 Gemini CLI 配置不生效、Cline 高级模型参数怎么填；接完之后照 接完自定义模型别急着干活 逐项过一遍，才算真接通。

想系统学会用 AI？报名体系课或加入会员，照着学、照着用。

浏览课程 加入会员