在 Cline 中配置 OpenAI 兼容提供商：实现带来源标注的文档问答

配置 Cline 实现文档问答，而不只是连接模型

如果你希望编码代理能够回答项目文档相关问题，并指出每个答案的出处，就需要完成两项独立工作：先将 Cline 连接到模型端点，再围绕这一连接构建检索和来源标注工作流。Cline 的 SDK 文档介绍了提供商凭据、模型 ID 和 LLM gateway，但没有说明内置文档搜索或引用功能。查看 Cline 模型提供商文档。

以下配置面向使用 Cline SDK 的开发者，并非 Cline 桌面扩展或其他界面的逐步配置指南；现有资料不足以确认这些界面的设置方式。对于 SDK，Cline 文档介绍了通过 API key、base URL 和模型 ID 配置 openai-compatible 提供商。OneMux 可作为通过 OpenAI 兼容 API 访问模型的一种途径，但能否用于特定 Cline 工作流，取决于所用端点和请求功能。

前置条件

配置代理前，请准备好以下内容：

• 一个使用相关 @cline/agents 和提供商软件包的 Cline SDK 项目。Cline 表示，@cline/agents 和 @cline/core 在内部使用其 LLM 层；具体导入方式和构造函数形式，请查阅与你所用版本对应的软件包文档。
• 计划使用的提供商 API key，并将其存放在源代码管理范围之外。
• 提供商的 OpenAI 兼容 base URL，以及该服务接受的准确模型 ID。
• 应用可访问的文档，以及能够检索相关段落并保留来源元数据的检索方式。

如需配置 OneMux 账户和 API，请先查看 OneMux 快速入门 和 API 文档。使用前，请在文档中核对当前端点和模型标识；本文不声称测试过某个特定模型、端点或 Cline 集成。

配置 OpenAI 兼容提供商

Cline 文档中的提供商配置模式如下：

const agent = new Agent({
  providerId: "openai-compatible",
  modelId: process.env.MODEL_ID,
  apiKey: process.env.PROVIDER_API_KEY,
  baseUrl: process.env.PROVIDER_BASE_URL,
})

由于所提供的提供商参考资料未指定 Agent 符号和软件包导入方式，因此这里省略。请根据项目安装的版本，采用相应文档中的导入方式和其他必需选项。在本地环境或密钥管理器中设置 MODEL_ID、PROVIDER_API_KEY 和 PROVIDER_BASE_URL。这些是应用示例中的环境变量名称，并非 Cline 要求使用的变量名。Cline 文档中列出的 OpenAI 和其他具名提供商的常用变量，并不能证明所有 OpenAI 兼容服务都有统一的变量名称。

若要使用 OneMux 配置，请从 OneMux 的 API 文档 获取当前 base URL、key 和模型 ID，并填入相应字段。不要假设每个 OpenAI 兼容端点都支持所有可选参数或功能。请确认端点文档中说明的请求格式、身份验证方式和模型可用性。尤其要注意，只有提供商支持代理发送的参数时，才具备相应兼容性。

为文档问答添加来源标注

连接模型并不会让它自动搜索文件或引用来源。你需要在应用层构建这些能力：

1. 使用稳定标识符为文档编制索引。 为每个可检索段落保存来源 ID、文档标题，以及页码、章节或其他位置信息。将这些元数据与文本一并保存。
2. 提问前先检索。 搜索与用户问题相关的段落，再选取少量结果作为上下文。检索实现和文档存储不属于 Cline 源资料所述的提供商配置范围。
3. 要求回答附带引用。 要求模型仅依据提供的段落作答，并使用你提供的 ID 和位置信息返回引用。例如，要求它给出简洁回答和引用 ID 列表。
4. 在代码中验证引用。 检查返回的每个 ID 是否都存在于检索结果中，再根据你自己的元数据生成链接或标签。如果没有段落能够支持答案，应让工作流说明文档无法确认该信息，而不是给出没有引用支撑的说法。

检索步骤可以使用如下提示词：

Answer the question using only the supplied document passages.
For each factual claim, cite the passage ID and location in brackets.
If the passages do not support an answer, say so.

Question: {{question}}
Passages:
{{retrieved_passages_with_ids_and_locations}}

这是应用层的实现模式，并非 Cline 文档所述的引用 API。模型可能生成看似合理却不正确的引用，因此应根据检索到的元数据核验引用；必要时还要检查被引段落。对于高风险场景，应由人工审核答案及其支撑段落。

验证与故障排查

身份验证失败： 检查进程环境中是否存在 key、key 是否属于已配置的服务，以及端点是否要求客户端使用当前身份验证方式。避免在日志中输出机密信息。

找不到模型： 向提供商确认准确的模型 ID。Cline 参考资料使用的是特定提供商的模型 ID，并不保证所有兼容服务都提供该 ID。

端点标注为 OpenAI 兼容，但请求仍失败： 检查 base URL，包括提供商是否要求使用 /v1 之类的版本路径。然后核对你安装的 Cline 版本所用的请求参数和响应格式，是否受端点文档支持。所提供的 Cline 资料没有列出适用于所有第三方端点的通用支持参数。

答案缺少可靠来源： 检查检索结果是否包含相关段落、每个段落是否具有稳定标识符和位置信息，以及应用是否验证返回的引用。仅配置提供商无法补救缺失或错误的检索元数据。

Cline 的模型提供商层还提供 gateway 和模型元数据，包括 context window、maximum tokens、定价及功能等字段。资料指出，token 用量和费用可能会显示在代理结果和用量事件中，但并未确认所有兼容提供商都会提供每项元数据。有关 gateway 的文档细节，请参阅 Cline 提供商参考文档。

这种配置适合你吗？

如果你的编码代理需要查询项目文档，而且你能够在自己的应用中实现检索和引用核验，那么可以采用这种方式。它将模型访问与确保答案可审计的功能分开处理。这不是开箱即用的文档问答功能，所引用的 Cline 页面也没有验证 OneMux 专属集成或文档引用行为。

实际操作时，可以先按照提供商文档配置端点并测试简单请求，再将检索和引用验证作为独立步骤加入工作流。你可以在 OneMux 模型页面 查看可用选项，并参阅 OneMux 定价 了解当前账户费用；本教程不比较价格或性能。

常见问题

Cline 的 OpenAI 兼容提供商会自动引用文档吗？

所提供的 Cline 提供商文档并未说明存在这项功能。文档介绍的是提供商配置和 gateway 功能。你需要在应用中实现文档检索、提供来源元数据、要求模型返回引用，并对引用进行验证。

可以将 OneMux 与 Cline 配合使用吗？

Cline SDK 文档介绍了 openai-compatible 提供商。OneMux 则通过一个 OpenAI 兼容 API 提供模型访问。具体配置是否可用，取决于当前端点、模型 ID、身份验证方式和请求参数；本文不声称已测试过该集成。

这份配置指南适用于 Cline 编辑器扩展吗？

所引用的资料介绍的是 Cline SDK 模型提供商，并未说明如何在 Cline 编辑器扩展或其他界面中配置提供商。请遵循你所用 Cline 产品和版本的对应文档。

如果没有来源支持答案，代理应该如何回答？

要求代理说明所提供的文档无法确认答案，并根据应用检索到的段落核验引用。不要把模型生成的引用当成被引材料确实支持该说法的证明。

来源

• Cline SDK：模型提供商 — 提供商配置、OpenAI 兼容设置、gateway、模型元数据和用量信息。