Cline 的设置页只需要填几个字段API Provider、Base URL、API Key、Model ID。字段不多排错却很容易混在一起。Base URL 写错会让请求落到不存在的路径Key 不匹配通常返回 401Model ID 不在当前端点的目录里会得到 404 或model_not_found端点虽然返回 200但响应结构不兼容时Cline 仍可能无法继续工作。最省时间的办法不是反复改四个字段而是在保存配置前先做两次预检读取模型目录再发送一个最小聊天请求。本文依据 Cline v4.0.11 的官方文档和当前源码说明字段边界并用只监听127.0.0.1的本地 fixture 复现错误模型 404、正确模型 200。本文没有安装或执行本机 Cline 客户端也没有请求任何线上 provider结论只覆盖配置前的协议预检。先按这 5 步检查适用环境你已经安装 Cline准备选择OpenAI Compatible目标服务声明支持 OpenAI-compatible API并提供自己的 Base URL、Key 和模型目录。1. 先记录 Cline 版本和官方字段Cline 官方 OpenAI Compatible 文档列出的核心设置是API Provider: OpenAI Compatible Base URL: 目标服务提供的 API 根地址 API Key: 目标服务签发的凭据 Model ID: 目标服务实际开放的模型标识当前 v4.0.11 的设置源码仍能看到 Base URL 输入框、API Key 字段以及 Model ID 的选择或自定义输入。这里最重要的不是把示例值照抄进去而是确认三个值来自同一个服务环境。测试环境的 URL、生产环境的 Key 和另一个供应商的展示名不能拼成一套可用配置。2. 用/models检查 Base URL 与模型目录先不要在 Cline 中发送长任务。根据目标服务文档把模型目录地址组合出来curl -sS \ -H Authorization: Bearer YOUR_API_KEY \ https://your-endpoint.example/v1/models只保留脱敏后的三个信号HTTP 状态、最终路径、返回的模型 ID。成功示例应类似{ object: list, data: [ {id: your-exact-model-id, object: model} ] }如果这里是 401先查 Key、认证头和权限如果是 404先查 Base URL 是否重复或缺少/v1如果返回 HTML、登录页或网关首页说明你命中的不是 API 资源。此时继续在 Cline 里换模型名只会增加变量。3. Model ID 必须复制目录中的精确值模型展示名和 API 标识不是一回事。控制台里写“Coder Pro”目录里可能是vendor-coder-2026-07。Cline 的 Model ID 应使用服务端实际识别的字符串并注意大小写、版本后缀和访问权限。错误思路凭产品页展示名猜模型 ID 正确思路读取当前端点的模型目录再复制精确 id若/models不开放也要以服务方当前文档或控制台可见目录为准。不要把别的供应商文章中的模型名直接粘贴过来也不要因为域名能打开就认定模型可调用。4. 发送一个最小聊天请求目录只证明模型 ID 被列出不证明 Chat Completions 响应能被客户端解析。继续用同一个 Base URL、Key 和 Model ID 发一个最小请求curl -sS \ -H Authorization: Bearer YOUR_API_KEY \ -H Content-Type: application/json \ https://your-endpoint.example/v1/chat/completions \ -d { model: your-exact-model-id, messages: [{role: user, content: reply with OK}], stream: false }成功信号至少包括HTTP 200、响应体是 JSON、choices[0].message.content可读。若 Cline 实际任务需要流式输出或工具调用最小文本 200 只是第一关不能代替 SSE、tool call 与上下文长度验证。5. 最后再回到 Cline 保存配置把刚才验证过的同一组值填入 ClineBase URL - 与预检请求使用同一个 API 根地址 API Key - 不截图、不提交到仓库 Model ID - 从当前端点目录复制发送一条最短消息并观察 Cline 的实际错误。如果预检 200、Cline 仍失败再检查 Cline 是否追加了不同资源路径、是否开启流式、供应商是否完整支持工具调用以及代理或企业远程配置是否覆盖本地字段。不要回头把四个字段同时乱改。本地实测错误模型 404正确模型 200为了验证这套顺序我运行了一个只绑定127.0.0.1的 OpenAI-compatible fixture。它公开一个合成模型fixture-coder并记录请求路径、模型 ID 和状态码不记录认证值。执行python3 06-evidence/probe_cline_preflight.py实际输出MODELS_HTTP200 MODELS_IDSfixture-coder WRONG_MODEL_HTTP404 WRONG_MODEL_ERRORmodel_not_found CORRECT_MODEL_HTTP200 CORRECT_MODEL_TEXTCLINE_PREFLIGHT_OK ONLINE_PROVIDER_REQUESTNO这组证据能证明“先读目录、再用精确模型 ID 发最小请求”可以把 404 与 200 分开。它不能证明某个线上服务稳定也不能证明 Cline 的流式和工具调用已经兼容。因为本机没有安装 Cline本稿不会把协议预检写成“Cline 已跑通”。常见失败路径/models返回 401优先检查认证头格式、Key 是否属于这个端点、Key 是否有模型目录权限。不要在日志中打印完整Authorization最多记录头是否存在、状态码和 request id。/models返回 404检查 Base URL 是否已经包含/v1。有的客户端需要填写https://host/v1有的配置项期望https://host后自行追加资源路径必须以当前 Cline 和目标服务文档为准。不要通过连续添加/v1/v1、/api/v1来碰运气。目录有模型聊天请求仍是model_not_found检查请求体中的模型字符串是否含空格、大小写是否一致、当前 Key 是否只有目录可见权但没有调用权。还要确认模型目录和聊天请求使用的是同一个 Base URL 与环境。最小请求 200Cline 仍然失败继续查响应结构、流式 SSE、工具调用和上下文能力。Cline 是 Agent 工具实际工作负载比“返回 OK”更复杂文本请求通过只能说明基础链路成立不能推导完整兼容。可复制检查清单[ ] 记录 Cline 版本与 OpenAI Compatible 配置入口 [ ] Base URL、Key、Model ID 来自同一个服务环境 [ ] /models 返回 200 且看到精确模型 ID [ ] 错误模型与正确模型得到可区分的状态 [ ] 最小 chat/completions 返回 200 和可读 JSON [ ] Cline 短消息通过后再测流式与工具调用 [ ] 日志和截图不包含完整 Key、Cookie 或用户数据总结Cline 配置 OpenAI Compatible 时先把“端点、认证、模型、协议”拆开。/models用来核对 Base URL 和模型目录最小聊天请求用来验证精确 Model ID 与基础响应。等两步都有明确成功信号再把同一组值填进 Cline。这样遇到 401、404 或响应解析错误时每个状态都有对应动作不必靠反复改字段猜答案。
