Cline 插件里所谓的“自定义 API 地址配置文件”,多数情况下并不是一份需要手写的独立配置,而是把三个关键值填清楚:兼容 OpenAI 协议的端点地址、鉴权密钥、模型名。真正需要改配置文件的情形,一般是团队统一分发设置、切换自建网关,或者想让插件跟着某个本地配置走。所以这份答案先帮你判断该不该动配置文件,再给出可替换的填写骨架和验证路径。
如果目标是让 Cline 连自己的 OpenAI 兼容端点,优先在插件设置面板里填 Base URL、API Key、Model ID 三项,确认能正常对话和读文件后,再考虑把同样的值固化到配置文件。判断前提是端点实现了 /v1/chat/completions 且支持流式与工具调用;只要其中一项缺失,即使配置填对,Cline 的文件读写、命令执行也会不完整。字段名和位置以本机插件版本界面实际显示为准,不要照抄别处的键名。
先确认当前场景和目标
这个问题成立的前提,是你已经有一个可以访问的模型端点,而不是正要去找端点。先用 curl 或任意 HTTP 工具确认端点活着、鉴权通过、返回的是对话补全结构,再谈填配置。端点本身不通时,配置怎么填都会以 401、403、404 或模型不存在告终,容易把排查方向带偏。
需要先确认的信息大致是这几项:
- 端点是否兼容 OpenAI 协议,完整路径通常是
/v1/chat/completions,有些网关会重写成别的路径,需要提前问清。 - 鉴权方式是否为
Authorization: Bearer <key>,如果需要额外的组织头、租户头或自定义 header,要单独记录。 - 模型标识是网关里的名字还是上游原始名字,两者经常不一致。
- 端点是否支持流式返回和工具调用(tool / function calling)。Cline 依赖工具调用去读写文件和执行命令,只支持纯文本对话的端点可以聊天,但自动化能力会明显受限。
目标也要说清楚:是只想让 Cline 能对话,还是要它完整执行读文件、改代码、跑命令。前者配置门槛低,后者必须核对工具调用支持情况。
按这个顺序处理
建议先在插件设置面板里试通,再落到配置文件。原因是面板会即时校验部分字段,配置写错时的错误位置更容易看出来。顺序可以按这个走:

- 在 Cline 的 Provider 选择里选 OpenAI Compatible(不同版本文案可能是 OpenAI Compatible / Custom OpenAI 之类)。
- 填 Base URL。通常填到
/v1这一层即可,插件会自己拼接后面的路径;如果网关要求填完整路径,就按网关说明写,不要两处都加/v1。 - 填 API Key,只在本地或插件配置里保存,不要写进会提交到代码仓库的文件。
- 填 Model ID,与网关返回的模型列表保持一致。
- 面板试通后,再把这些值迁移到团队下发的配置文件或设置同步方案里。
下面是一个通用骨架,字段名仅供参考,具体键名以你本机插件版本实际使用为准,替换项已用大写标注:
{
"apiProvider": "openai-compatible",
"baseUrl": "https://YOUR-GATEWAY.example.com/v1",
"apiKey": "sk-REPLACE_ME",
"modelId": "YOUR-MODEL-NAME",
"modelInfo": {
"maxTokens": 8192,
"contextWindow": 32768,
"supportsImages": false
},
"headers": {
"X-Tenant-Id": "REPLACE_ME"
}
}
填写时有三处容易出错:baseUrl 末尾多写或少写斜杠;modelId 用了上游名字而网关只认别名;contextWindow 填得比模型真实上下文大,导致长对话被端点拒绝。改完保存后重载一次窗口,让插件重新读取设置。
改完后怎么验证
验证分两层,先纯对话,再工具调用。纯对话时发一句简单指令,比如让它回答一个固定短句,观察是否正常流式返回。这一步失败,问题集中在地址、密钥或模型名,与 Cline 的功能无关。

工具调用这层更关键。可以让 Cline 读一个工作区里的小文件,或列出当前目录。预期信号是:它发起一次工具调用请求,端点返回带工具调用的响应,插件在界面上显示读取结果并继续推理。如果只输出文本、始终不触发文件操作,多半是端点没有正确返回工具调用结构,或者模型本身不支持。
同时留意错误信息的形态:401 指向密钥,404 多半是路径拼错,模型不存在的报错则指向 modelId。把这些报错原文留下来,比反复改配置更快定位。
容易忽略的边界
有些场景下这套配置并不适用。端点只支持纯文本补全、不支持工具调用时,Cline 的自动改文件能力会退化成“给建议”,不能当作完整方案;企业网关做了路径重写或要求额外签名时,标准的 Bearer 鉴权字段填不进去,需要按网关约定加 header;内网自签证书环境下,插件可能直接报证书错误,这属于网络与证书层面的问题,改配置文件解决不了。
另外要注意密钥权限和配置落盘位置。把 API Key 写进项目目录里的配置文件,一旦提交就会泄露,建议放在用户级设置或环境变量里,团队共享的配置只放地址和模型名。回退方案也要预留:改动前备份原配置,出问题时先切回官方 Provider 或原来的端点,确认插件本身可用,再逐个字段恢复自定义配置,避免一次改多项导致无法判断是哪一处出错。