Cline 配置 OpenAI API Base URL
简答：在 Cline 设置中将 API Provider 选择为 OpenAI Compatible，填写接口服务商提供的 Base URL、API Key 和准确的 Model ID；Base URL 通常填写服务商给出的 API 根地址，不要擅自追加 /chat/completions。保存后发起一次测试对话验证连接。
定义：OpenAI API Base URL 是客户端用于拼接模型请求路径的接口根地址，Cline 会基于该地址调用兼容 OpenAI API 规范的服务。
一、Cline 配置 OpenAI API Base URL 的正确方法
Cline 官方的 OpenAI Compatible 配置包含三个核心字段：Base URL、API Key 和 Model ID。API Provider 需要选择 OpenAI Compatible，而不是把第三方兼容接口误选成某个原生厂商选项。具体字段名称可能随 Cline 版本或界面语言略有变化，但配置逻辑不变。Cline 官方 OpenAI Compatible 配置说明明确要求使用服务商提供的接口地址、密钥和模型标识。
- 打开 Cline 面板，进入设置页面。
- 在 API Provider 或供应商选项中选择 OpenAI Compatible。
- 在 Base URL 中填写服务商提供的 API 根地址，例如
https://api.example.com/v1。 - 在 API Key 中粘贴对应服务商签发的密钥。
- 在 Model ID 或 Model 中填写服务商支持的准确模型名称，例如
your-model-id。 - 保存配置后，发起一次短测试对话；如果能够正常返回内容，再进行代码修改或长任务。
不要把示例中的域名、模型名或密钥直接照搬到实际配置。每个兼容接口的模型列表、路径、鉴权方式和可用能力都可能不同，应优先以对应服务商的官方文档为准。
二、Base URL 应该填到哪一级
最容易出错的是把完整请求路径填入 Base URL。OpenAI 风格的聊天请求通常最终会访问类似 /chat/completions 的路径，但 Cline 的配置字段是 Base URL，不是完整请求 URL。Cline 的 SDK 配置示例把 baseUrl 写成类似 https://api.together.xyz/v1 的接口根地址，并由客户端根据 OpenAI 兼容协议构造请求。Cline SDK 官方模型供应商文档也将 baseUrl 与 apiKey、modelId 分开配置。
| 填写内容 | 示例 | 是否推荐 | 说明 |
|---|---|---|---|
| 接口根地址 | https://api.example.com/v1 | 推荐 | 通常作为 Base URL 使用，具体以服务商文档为准。 |
| 完整聊天路径 | https://api.example.com/v1/chat/completions | 通常不推荐 | 这是请求路径，不一定适合作为客户端的 Base URL。 |
| 只填写域名 | https://api.example.com | 视服务商而定 | 如果服务商要求 /v1 或其他版本路径，缺少路径可能导致 404。 |
| 带多余斜杠的地址 | https://api.example.com/v1/ | 需测试 | 有些客户端可以处理，有些网关会因路径拼接产生异常，优先照官方示例填写。 |
判断方法很简单：查看服务商文档给出的 OpenAI SDK 或 curl 示例。如果示例中的客户端参数是 base_url 或 baseUrl，通常应把同一地址填入 Cline 的 Base URL；如果文档只给出完整 POST URL，则需要确认它是否已经包含了聊天请求路径。
三、API Key、Model ID 与自定义请求头怎么填
API Key 是服务商颁发的访问凭据，不是模型名称，也不是完整的 Authorization: Bearer ... 请求头。除非 Cline 当前界面明确要求完整请求头，否则通常只粘贴密钥本身。OpenAI 的 API 示例使用 Bearer 形式进行鉴权，兼容接口一般也采用类似方式，但最终仍应以实际服务商的鉴权文档为准。OpenAI Chat Completions API Reference展示了标准请求中的 Authorization 和 JSON 请求结构。
Model ID 必须是接口实际支持的模型标识。显示名称、宣传名称和 API 请求中的 ID 可能不同；如果服务商提供模型列表接口或模型目录，应从该目录复制准确值。模型名错误通常会返回 400 或 404，而不是说明 Base URL 一定错误。
部分网关还需要额外请求头，例如租户标识、路由标识或来源信息。Cline 的 SDK 配置支持通过 headers 传入自定义请求头，官方示例使用类似 {"X-Custom-Header":"value"} 的结构。Cline SDK Provider Reference同时列出了 baseUrl 和自定义 headers 配置能力。如果桌面版 Cline 的当前界面没有 Custom Headers 字段，不要把请求头拼接到 Base URL 中，应先确认该版本是否支持该字段或改用服务商提供的标准鉴权方式。
| 字段 | 应填写 | 常见错误 |
|---|---|---|
| Base URL | 服务商提供的 API 根地址 | 误填完整 /chat/completions 路径、漏掉版本路径。 |
| API Key | 密钥字符串 | 把 Bearer、引号或整段 Header 一起粘贴。 |
| Model ID | 接口实际接受的模型 ID | 填写网页展示名、别名或不存在的模型。 |
| Custom Headers | 服务商明确要求的额外 Header | 把 Header 写进 URL，或在没有要求时随意增加敏感信息。 |
四、用最小请求验证 Base URL 是否可用
保存 Cline 配置后，建议先用一个短问题测试，而不是立即执行需要大量上下文的任务。若想在 Cline 外部确认接口本身是否可用，可以使用下面的 OpenAI 兼容格式请求。它只是通用模板，必须替换 Base URL、API Key 和 Model ID；请求路径是否为 /chat/completions，也要以服务商文档为准。
macOS、Linux 或支持 Bash 的终端：
curl -X POST "https://api.example.com/v1/chat/completions" -H "Authorization: Bearer YOUR_API_KEY" -H "Content-Type: application/json" -d '{"model":"YOUR_MODEL_ID","messages":[{"role":"user","content":"Reply with OK"}],"stream":false}'
Windows PowerShell：
$headers = @{ Authorization = "Bearer YOUR_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
如果外部请求成功但 Cline 失败，重点检查 Cline 中的 Base URL、Model ID、Custom Headers 和流式设置；如果外部请求也失败，应先按 HTTP 状态码检查服务商接口、密钥权限和模型可用性。OpenAI 的接口参考说明了 Chat Completions 请求使用模型、消息列表和可选的 stream 参数，兼容接口通常会模仿这一结构，但并不代表所有可选字段都完全支持。
五、401、403、404、429、超时和流式中断排查
| 现象 | 优先检查 | 处理方式 |
|---|---|---|
| 401 Unauthorized | API Key、鉴权格式、Key 是否已撤销 | 重新复制密钥，确认只填写密钥本身；检查是否误用了其他服务商的 Key。 |
| 403 Forbidden | 账户权限、来源限制、模型权限、额外 Header | 查看服务商控制台或官方文档中的权限要求；不要仅通过更换模型来猜测原因。 |
| 404 Not Found | Base URL 层级、版本路径、Model ID、请求路径 | 对照官方 curl 或 SDK 示例，确认是否多写或漏写了 /v1、区域路径或部署名称。 |
| 429 Too Many Requests | 限速、并发、余额或额度 | 降低并发和请求频率，等待后重试，并查看服务商对限速及额度的说明。不要把 429 直接判断成 Base URL 错误。 |
| 请求超时 | 网络连通性、接口响应时间、上下文大小 | 先用短提示词和非流式请求测试，再逐步增加上下文；同时确认服务端是否有超时限制。 |
| 流式输出中断 | SSE 兼容性、代理缓冲、服务端终止信号 | 先将请求改为 stream:false 验证普通响应；若普通响应正常而流式失败，检查网关是否完整支持 SSE、是否存在代理缓冲或连接空闲超时。OpenAI 文档说明流式响应通过服务器发送事件返回，连接中断时还可能无法收到最终用量块。 |
| 模型能回复但工具调用失败 | 模型能力、工具调用格式、Cline 的模型能力设置 | 确认服务商和模型是否支持工具调用；不要仅凭普通文本回复成功就认定 Agent 功能全部兼容。 |
排查时最好一次只改一个变量：先固定 Model ID，只检查 Base URL；再检查 Key；最后检查自定义 Header、流式和工具调用。这样比同时更换地址、模型和客户端版本更容易定位问题。
六、配置安全与多供应商切换建议
API Key 不应写进公开代码、截图、提交记录或项目配置文件。测试 curl 后应清理终端历史中的明文密钥；在团队环境中，建议使用环境变量或客户端提供的安全配置能力，并按服务商支持情况设置最小权限、额度和用量提醒。
如果需要在多个 OpenAI 兼容接口之间切换，建议为每个供应商单独记录四项信息：Base URL、API Key 所属服务商、Model ID、是否需要 Custom Headers。切换时只替换这些字段，不要把一个服务商的模型名、Key 或请求头混用到另一个接口。Cline 的 SDK 配置模型也将供应商 ID、模型 ID、密钥、Base URL 和 Header 作为可分别管理的配置项。
对于 Azure 或其他具有独立部署路径的接口，不要套用普通公共 API 的 /v1 示例。应按照对应服务的官方端点格式填写，并确认 Cline 当前版本是否要求额外的 API Version、身份认证或自定义 Header。无法从公开文档核实的字段，不建议凭经验填写。
常见问题
Cline 的 Base URL 要不要加 /chat/completions？
通常不应直接填写完整的 /chat/completions 请求路径，而应填写服务商提供的 API 根地址，例如带版本路径的地址。最终以该服务商给出的 Cline、OpenAI SDK 或 curl 示例为准，因为不同网关的路径拼接方式可能不同。
Cline 配置后出现 404，是 Base URL 填错了吗？
不一定。404 可能来自漏写版本路径、误加聊天路径、Model ID 不存在、区域或部署名称错误。建议先用服务商官方示例请求验证地址，再逐项核对 Cline 的 Base URL 和模型 ID。
API Key 要填写 Bearer 加密钥吗？
通常 API Key 字段只填写密钥字符串，不要把完整的 Authorization Header 一起粘贴。标准 OpenAI 请求会以 Bearer 形式发送，但 Cline 是否自动添加该前缀，应以当前客户端和服务商文档为准。
为什么普通对话成功，但流式输出会中断？
这通常与 SSE 流式兼容性、代理缓冲、服务端终止信号或连接超时有关。先用非流式请求验证接口，再检查服务商是否支持标准流式响应以及中间代理是否会缓存或截断连接。
Cline 可以使用需要自定义 Header 的 OpenAI 兼容接口吗？
Cline SDK 官方配置支持 headers 字段，但桌面版界面是否提供 Custom Headers 取决于当前版本和界面实现。如果服务商明确要求额外 Header，应先确认 Cline 当前版本是否支持，不能把 Header 随意拼接到 Base URL 中。