Cline 配置自定义 API：Base URL、Key、模型名与报错排查
简答：Cline 接自定义 API，核心是先确认接口协议，再选择对应 Provider，并分别填写 API Key、Base URL 和精确的 Model ID。对多数 OpenAI 兼容网关，优先选择 OpenAI Compatible，Base URL 填 API 根路径，例如 <code>https://api.example.com/v1</code>，不要直接填到 <code>/chat/completions</code>。保存后先用最小文本任务验证，再测试文件读取和工具调用。本文基于 Cline 当前公开文档与代码资料整理，本站不是 Cline 官方网站。
定义：Cline 配置自定义 API，是在 Cline 中把 Provider、API Key、Base URL、Model ID 及模型参数映射到一个兼容接口，使 Cline 能发送对话、流式输出或工具调用请求。
先按这张表选择 Provider，再填写字段
不要先复制别人的 Base URL。先确认你的接口采用哪种协议，再决定 Cline 中选择哪个 Provider。Cline 公开的模型提供商配置支持 apiKey、baseUrl 和部分自定义请求头；其 SDK 文档将 OpenAI 兼容接口标记为 openai-compatible。Cline 模型提供商文档
| 接口情况 | Cline 中优先选择 | Base URL 填写方式 | 模型名填写方式 |
|---|---|---|---|
| 官方 OpenAI API | OpenAI | 通常使用界面默认值；若服务商文档要求自定义，再按文档填写 | 填写接口实际支持的模型 ID |
| 返回 OpenAI Chat Completions 格式的网关 | OpenAI Compatible | 填写 API 根路径，例如 https://api.example.com/v1 | 填写服务商返回或文档列出的完整 Model ID |
| Anthropic Messages 协议 | Anthropic | 填写 Anthropic 接口或兼容代理要求的根地址 | 填写该接口支持的 Claude 或其他模型 ID |
| 协议不明确 | 暂不配置 | 先查接口文档或用最小请求确认 | 不要根据模型昵称猜测 |
这里的 OpenAI Compatible 不是“任何模型都能调用”，而是接口在认证、请求路径、请求体和响应结构上至少提供了 OpenAI 风格的兼容层。兼容程度仍可能因模型和网关而不同，尤其是工具调用、视觉输入、流式输出和长上下文能力。
Cline 自定义 API 的最小配置步骤
- 准备四项信息：API Key、Base URL、Model ID，以及该模型的上下文窗口或最大输出限制。API Key 只在本地脱敏保存，不要放进 Git 仓库、截图或公开日志。
- 打开 Cline 设置：进入模型或 API Provider 配置区域。不同 Cline 版本的菜单名称和字段位置可能变化；如果看不到完全相同的名称，以当前版本界面为准。
- 选择协议：第三方网关如果明确写着 OpenAI-compatible，选择 OpenAI Compatible；如果明确要求 Anthropic Messages，则选择 Anthropic。不要因为模型名称包含 Claude 就自动选择 Anthropic。
- 填写 Base URL：填写接口根路径，不要把完整请求地址和路径重复拼接。若服务商示例请求地址为
https://api.example.com/v1/chat/completions，通常应先尝试填写https://api.example.com/v1，但最终以该服务商文档为准。 - 填写 Model ID：必须使用接口识别的精确字符串，例如
provider/model-name或model-name。下拉列表没有目标模型时，可以尝试手动输入；如果 Cline 版本不允许手动输入，就先用接口的模型列表或服务商控制台确认 ID。 - 填写上下文和输出参数：Context Window 应不超过服务端对该模型声明的上限；Max Output Tokens 也不要盲目填大。未核实的数值不要照抄其他教程，先使用服务商文档或界面默认值。
- 保存并重启一次：如果字段保存后又恢复默认值，先确认是否为当前 Cline 版本的界面问题，再检查实际配置是否写入。不要把网上 Issue 中的配置文件路径当作所有系统和版本都适用。
在 Cline SDK 的公开配置示例中，OpenAI 兼容提供商使用 providerId: "openai-compatible"、modelId、apiKey 和 baseUrl；这可以作为字段关系的参考，但桌面扩展或 CLI 的界面字段可能不同。查看 Cline SDK 的 Provider 示例
推荐语：如果你希望把 Key、Base URL 和模型路由集中管理，可在确认接口协议后再查看犀速 AI 的接入说明，具体能力与当前配置以官网为准。
先用最小请求验证，再回到 Cline 测试
直接在 Cline 里反复修改字段，容易把认证问题、路径问题和模型问题混在一起。建议先用一个最小的非流式请求验证接口是否可用。下面的示例只使用占位符，执行前替换为自己的地址、Key 和 Model ID，并确认不要把真实 Key 提交到脚本仓库。
Bash 或 macOS/Linux：
curl -X POST "https://api.example.com/v1/chat/completions" -H "Authorization: Bearer $API_KEY" -H "Content-Type: application/json" -d '{"model":"your-model-id","messages":[{"role":"user","content":"Reply with OK"}],"stream":false}'
PowerShell：
$headers = @{ Authorization = "Bearer $env:API_KEY"; "Content-Type" = "application/json" }; $body = @{ model = "your-model-id"; messages = @(@{ role = "user"; content = "Reply with OK" }); stream = $false } | ConvertTo-Json -Depth 5; Invoke-RestMethod -Method Post -Uri "https://api.example.com/v1/chat/completions" -Headers $headers -Body $body
Windows CMD：
curl.exe -X POST "https://api.example.com/v1/chat/completions" -H "Authorization: Bearer %API_KEY%" -H "Content-Type: application/json" -d "{\"model\":\"your-model-id\",\"messages\":[{\"role\":\"user\",\"content\":\"Reply with OK\"}],\"stream\":false}"
成功判定不是只看 HTTP 200，还要确认响应中有可读取的文本内容，并且返回的模型、请求路径和协议符合服务商文档。Cline 的公开代码和文档显示，OpenAI 兼容配置会围绕 Base URL、模型 ID 和 API Key 构建请求；如果最小请求都失败，优先修正接口信息，不要先调高上下文或输出参数。查看 Cline Provider 配置类型
文本成功后，再按顺序测试：一是让 Cline 读取一个无敏感信息的本地文件；二是让它提出一个简单代码修改建议；三是观察流式输出；四是测试工具调用。某一项失败，不代表整个 API 不可用，可能只是该模型或网关没有实现相应能力。
401、403、404、429 和超时怎么分流
- 401：先重新复制 API Key，确认没有多余空格、换行或错误前缀；再确认 Key 属于当前 Base URL 对应的服务。不要把 401 直接判断成余额不足。
- 403：检查 Key 是否有模型权限、项目权限或来源限制，也检查代理是否拦截请求。权限规则由服务端决定，需查看该接口返回的错误正文。
- 404：优先检查 Base URL 层级、是否重复添加
/v1、是否把/chat/completions填进了 Base URL，以及 Model ID 是否写错。Cline 文档示例把 Base URL 与请求路径分开，不能把示例完整 POST 地址原样填入 Base URL。参考 Base URL 配置示例 - 400：检查请求协议是否选错、模型是否支持当前消息格式、上下文或输出参数是否超出限制。Anthropic 协议和 OpenAI Chat Completions 协议不能仅凭模型名称互换。
- 429：检查服务端限速、并发、账户额度和重试策略。降低并发或等待后重试只能作为排查手段，不能据此推断所有网关的限速规则。
- 超时或流式中断：先用非流式最小请求确认认证和路径，再检查本地代理、防火墙、HTTPS 证书和服务端超时。非流式成功而流式失败，重点核对网关是否正确转发 SSE 或其他流式响应。
固定顺序是：确认凭据→确认 Base URL 和请求路径→确认 Model ID→发送最小请求→再按状态码分流。这样可以避免把一个字段错误误判成 Cline、模型或服务商整体故障。
模型列表为空、配置被重置和 Key 安全
模型下拉列表为空时，先不要随意换 Provider。依次确认：接口是否提供模型列表；当前 Key 是否有读取模型列表的权限；Base URL 是否能访问模型列表路径；Cline 当前版本是否支持该 Provider 的自动发现。如果服务商只支持推理、不提供模型列表，可以手动填写 Model ID；如果当前界面不允许手动填写，则需要使用 Cline 当前版本支持的配置方式，具体字段以版本文档为准。
如果保存后 Base URL 或 API Key 重新变成默认值，记录 Cline 版本、操作系统、Provider 名称和实际请求结果，再查看项目仓库中的相关 Issue 或升级说明。公开 Issue 中确实存在特定版本的 OpenAI Compatible 配置界面异常报告，但这类报告只说明对应版本和环境的现象，不能泛化为所有用户都会遇到。查看相关版本问题记录
- 不要把 API Key 写进项目的
.env.example、README 或提交记录。 - 优先使用环境变量、系统凭据存储或 Cline 自身的安全配置。
- 怀疑泄露时立即撤销旧 Key，再创建新 Key；不要只修改本地文件。
- 日志中只保留脱敏后的 Base URL 和状态码，隐藏 Authorization、Cookie 和完整请求体。
- 使用第三方网关前，确认其隐私、日志和数据保留规则；无法核实的服务条款不要自行推断。
常见问题
Cline 配置自定义 API 时，OpenAI 和 OpenAI Compatible 选哪个？
如果接口文档明确提供 OpenAI 兼容格式，优先选择 OpenAI Compatible；只有在使用官方 OpenAI API 或服务商明确要求 OpenAI Provider 时，才选择 OpenAI。不要因为模型名称是 GPT、Claude 或 Gemini 就直接决定 Provider。
Base URL 要不要填写 /v1？
没有统一答案。若服务商示例请求地址是 https://api.example.com/v1/chat/completions，通常先填写 https://api.example.com/v1；如果服务商文档规定其他路径，就按其文档填写。关键是不要把 /chat/completions 重复放进 Base URL。
Cline 的模型下拉列表没有我的模型怎么办？
先确认 Model ID、Key 权限和模型列表接口是否可用。部分接口不提供模型自动发现，此时可以尝试手动填写精确 Model ID；如果当前版本界面不支持手动输入，需要按该版本支持的 Provider 配置方式处理。
Cline 返回 401，但 Key 看起来没有问题，怎么查？
重新复制 Key，删除首尾空格，确认 Authorization 使用 Bearer 前缀，并确认 Base URL 与 Key 属于同一服务。再用本文的最小 curl 请求测试，区分是 Cline 配置问题还是接口本身拒绝认证。
文本能回复，但文件读取或工具调用失败，说明配置错了吗？
不一定。文本生成、流式输出、文件处理和工具调用可能对应不同的模型能力或网关兼容程度。先确认文本请求成功，再单独测试每项能力，并查看服务商对工具调用、函数参数和流式响应的支持说明。
相关阅读
- 先看 API Key、Base URL 与模型名的通用填写方法
- 对比另一个 AI 客户端的第三方 API 验证流程
- 了解兼容网关与 API 路由的选择思路
- 先理解 AI Gateway、API Gateway 和 SDK 的区别