Cline SDK 模型提供商指南：@cline/llms 的 Gateway、Provider Registry 与成本追踪实战

本文基于 Cline SDK 官方技能文档 providers/REFERENCE.md，系统讲解如何通过 @cline/llms 在 Cline SDK 中接入 Anthropic、OpenAI、Gemini、Vertex AI、AWS Bedrock、Mistral 及任意 OpenAI 兼容服务：包括 Agent 与 ClineCore 两种配置入口、各提供商的专属参数、自定义 Base URL 与请求头，以及面向多提供商场景的 Gateway API、Provider Registry 编程接口和按请求粒度的成本追踪。读完本篇，你可以独立完成从"单一 API Key 接入"到"多提供商网关 + 自定义 Provider 注册"的完整落地，并理解 Gateway 内部的模型解析与 token 上限计算逻辑。

支持的提供商

Cline SDK 通过 @cline/llms 包开箱支持所有主流 LLM 提供商。官方参考文档中列出的支持清单如下：

Provider ID	模型
"anthropic"	Claude Opus 4.7, Sonnet 4.6, Haiku 4.5
"openai"	GPT-5.5, GPT-5.3 Codex
"gemini"	Gemini 3.1 Pro Preview, Gemini 3 Flash Preview
"vertex"	Google models via Vertex AI
"bedrock"	Claude, Llama via AWS Bedrock
"mistral"	Mistral Large, Codestral
"openai-compatible"	vLLM, Together, Fireworks, Groq, etc.

从源码结构看，这些内置提供商并非硬编码在 Gateway 中，而是由 builtins.ts 汇总的 BUILTIN_PROVIDER_REGISTRATIONS 注册到 Gateway 的 Registry 中；DefaultGateway 构造时默认加载全部内置提供商，也可以通过配置裁剪（详见后文 Gateway 小节）。此外，源码中还维护了提供商 ID 的规范化逻辑（如大小写与别名归一）和 OpenAI Codex 模型过滤等细节，说明实际可用模型集合会随生成目录（catalog）动态更新。

基本配置

方式一：配合 Agent 使用

最简单的接入方式是直接给 Agent 传入提供商三元组（providerId / modelId / apiKey）：

import { Agent } from "@cline/sdk"

const agent = new Agent({
  providerId: "anthropic",
  modelId: "claude-sonnet-4-6",
  apiKey: process.env.ANTHROPIC_API_KEY,
  systemPrompt: "You are a helpful assistant.",
  tools: [],
})

方式二：配合 ClineCore 使用

ClineCore 是面向完整智能体循环的运行时入口，提供商配置通过 start() 的 config 字段传入：

import { ClineCore } from "@cline/sdk"

const cline = await ClineCore.create({ clientName: "my-app" })

await cline.start({
  prompt: "Hello",
  config: {
    providerId: "anthropic",
    modelId: "claude-sonnet-4-6",
    apiKey: process.env.ANTHROPIC_API_KEY,
  },
})

两种入口最终都会走 @cline/llms 的 Handler 工厂：createHandler(config) 会先对 providerId 做规范化，然后查询工厂注册表中是否存在已注册的自定义 Handler，未命中时回落到 createGatewayApiHandler 走统一的 Gateway 通道（见 providers.ts）。这意味着你注册的自定义 Handler 优先级高于内置 Gateway 实现，是扩展提供商时的两条路径之一。

各提供商专属配置

以下配置块来自官方参考文档，可直接作为 Agent 构造参数或 ClineCore.start() 的 config 使用。

Anthropic

{
  providerId: "anthropic",
  modelId: "claude-opus-4-7",  // or "claude-sonnet-4-6", "claude-haiku-4-5"
  apiKey: process.env.ANTHROPIC_API_KEY,
}

OpenAI

{
  providerId: "openai",
  modelId: "gpt-5.5",
  apiKey: process.env.OPENAI_API_KEY,
}

Google (Gemini)

{
  providerId: "gemini",
  modelId: "gemini-3.1-pro-preview",
  apiKey: process.env.GOOGLE_API_KEY,
}

Google (Vertex AI)

{
  providerId: "vertex",
  modelId: "gemini-3.1-pro-preview",
  // Uses application default credentials or service account
}

Vertex 不要求传 apiKey，走 Google 应用默认凭据或服务账号机制。

AWS Bedrock

{
  providerId: "bedrock",
  modelId: "anthropic.claude-sonnet-4-6",
  // Uses AWS credential chain (env vars, config file, IAM role)
  // Set AWS_REGION, AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY
}

Bedrock 走 AWS 标准凭据链（环境变量、配置文件或 IAM Role）。注意 Bedrock 的模型 ID 使用厂商前缀格式（anthropic.claude-sonnet-4-6），与直接调用 Anthropic API 时的裸模型 ID 不同。

Mistral

{
  providerId: "mistral",
  modelId: "mistral-large-latest",
  apiKey: process.env.MISTRAL_API_KEY,
}

OpenAI-Compatible（兼容端点）

任何提供 OpenAI 兼容 API 的服务都可以通过 openai-compatible 接入，关键是多传一个 baseUrl：

{
  providerId: "openai-compatible",
  modelId: "my-model",
  apiKey: process.env.API_KEY,
  baseUrl: "https://api.together.xyz/v1",
}

官方文档明确列出该模式适用于 vLLM、Together AI、Fireworks、Groq、Ollama、LiteLLM 等。从源码看，本地部署场景还有一个实用细节：针对 Ollama，SDK 内置了 OLLAMA_DEFAULT_CONTEXT_WINDOW = 32768 的默认上下文窗口常量（见 builtins.ts），因为 Ollama 服务端 4096 的默认值装不下智能体类长提示，该常量是 vendor、VS Code 会话工厂与设置 UI 共享的单一事实来源。

自定义 Base URL

任意提供商都可以通过 baseUrl 覆盖 API 端点，适合走企业代理、私有网关或内网推理服务：

{
  providerId: "anthropic",
  modelId: "claude-sonnet-4-6",
  apiKey: process.env.API_KEY,
  baseUrl: "https://my-proxy.example.com/v1",
}

自定义请求头

headers 字段可以向所有 API 请求附加额外 HTTP 头，常用于网关鉴权、租户标识或追踪字段透传：

{
  providerId: "openai",
  modelId: "gpt-5.5",
  apiKey: process.env.API_KEY,
  headers: {
    "X-Custom-Header": "value",
  },
}

Gateway API：多提供商网关

对于同时对接多个提供商的进阶场景，可以绕过"单提供商三元组"模式，直接使用 @cline/llms 导出的 Gateway：

import { createGateway, DefaultGateway } from "@cline/llms"

const gateway = createGateway({
  providerConfigs: [
    { providerId: "anthropic", apiKey: process.env.ANTHROPIC_API_KEY },
    { providerId: "openai", apiKey: process.env.OPENAI_API_KEY },
  ],
})

// Create a model for a specific provider
const model = gateway.createAgentModel({
  providerId: "anthropic",
  modelId: "claude-opus-4-7",
})

// Use with Agent
const agent = new Agent({ model, systemPrompt: "...", tools: [] })

createGateway(config?) 返回 DefaultGateway 实例（gateway.ts）。从源码实现看，其构造过程分三步：

1. 加载内置提供商：默认注册全部 BUILTIN_PROVIDER_REGISTRATIONS，可用 config.builtins: false 关闭，或用 id 白名单裁剪；
2. 注册自定义 provider：config.providers 中的每一项依次调用 registerProvider；
3. 应用提供商配置：config.providerConfigs 中的 apiKey、baseUrl、headers 等通过 configureProvider 写入 Registry（gateway.ts）。

Gateway 方法一览

方法	作用
gateway.registerProvider(registration)	注册自定义提供商
gateway.configureProvider(config)	更新某个提供商的配置
gateway.listProviders()	列出可用提供商
gateway.listModels(providerId?)	列出可用模型
gateway.createAgentModel(selection)	为 Agent 创建模型句柄
gateway.stream(request)	原始流式请求（返回 Promise<AsyncIterable<AgentModelEvent>>）

createAgentModel 返回的是内部 GatewayModelAdapter，它实现了 AgentModel 接口，把 systemPrompt、messages、tools、temperature、maxTokens、reasoning 等请求参数合并后转交给 gateway.stream()。在发起流式请求时，Gateway 会做两件事值得注意：

• 能力校验：先检查提供商/模型声明的模态是否支持当前操作（providerManifestSupportsModelOperation），再过滤模型不支持的 modelTools（如 web_search、image_generation），不支持时直接抛错而不是发出无效请求（gateway.ts）；
• maxTokens 自动协商：resolveGatewayRequestMaxTokens 会把"用户显式请求值、模型 maxOutputTokens 上限、上下文窗口剩余空间（预留 1024 token 输出余量）"取最小值；未显式指定时默认 32000 token；若估算输入 token 已超过上下文窗口，则回退为 undefined 并记录告警日志（gateway.ts）。这套逻辑解释了为什么你通常不需要手动为每个模型计算 maxTokens。

Provider Registry：编程式查询与注册

不依赖 Gateway 实例时，@cline/llms 还暴露了一组基于模块级注册表的函数：

import {
  getAllProviders,
  getProviderIds,
  getProvider,
  getModelsForProvider,
  registerProvider,
  registerModel,
  createHandler,
} from "@cline/llms"

// List all registered providers
const providers = getAllProviders()

// Get models for a provider
const models = getModelsForProvider("anthropic")

// Register a custom provider
registerProvider({
  id: "my-provider",
  name: "My Custom Provider",
  handler: createHandler({ ... }),
})

这些函数对应 model-registry.ts 中的实现，有两个源码级事实值得补充：

• getAllProviders()、getProvider()、getModelsForProvider() 在源码中是 async 函数（返回 Promise），实际项目代码中调用时需要 await；
• registerProvider(collection) 将整个提供商集合（含其模型字典）写入自定义表，registerModel(providerId, modelId, info) 则以单模型粒度覆盖/新增元数据，自定义注册在查询时优先于内置条目（CUSTOM_PROVIDERS 与 CUSTOM_MODELS 覆盖 PROVIDER_CACHE，见 model-registry.ts）。此外还配有 unregisterModel、unregisterProvider 与 resetRegistry 用于测试清理。

getModelsForProvider 还支持 filter: "chat" 选项，只返回聊天兼容模型。

模型元数据

通过注册表可查询模型的上下文窗口、价格与能力，适合在 UI 中渲染模型选择器或做预算估算：

import { getModelsForProvider } from "@cline/llms"

const models = getModelsForProvider("anthropic")
for (const model of models) {
  console.log(`${model.id}: context=${model.contextWindow}, input=$${model.inputPrice}/MTok`)
}

返回的 ModelInfo 字段还包括 maxOutputTokens 等能力信息——正是上文 Gateway 自动协商 maxTokens 时读取的元数据来源，二者构成"注册元数据 → 运行时请求裁剪"的闭环。

成本追踪

SDK 在三层暴露成本数据，覆盖"事件流、运行结果、会话累计"三种消费场景：

// Via events
agent.subscribe((event) => {
  if (event.type === "usage-updated") {
    console.log(`Cost: $${event.usage.totalCost?.toFixed(4)}`)
  }
})

// Via result
const result = await agent.run("...")
console.log(`Total cost: $${result.usage.totalCost?.toFixed(4)}`)

// Via ClineCore accumulated usage
const usage = await cline.getAccumulatedUsage(sessionId)

其中 usage-updated 事件由 Agent 运行时在每次模型往返后发出（见 agent-runtime.ts 附近的事件发射逻辑）；而 ClineCore 侧对连续 usage-updated 事件做了"首条事件 delta 等于累计值、后续事件 delta 为增量、总量持续累加"的语义处理，相关行为有专门的测试覆盖（runtime-event-adapter.test.ts）。totalCost 为可选值，价格元数据缺失的模型会返回 undefined，代码中建议保持文档示例中的 ?.toFixed(4) 防御写法。

延伸阅读

• Agent 参考：在 Agent 中使用提供商
• ClineCore 参考：在 ClineCore 中使用提供商
• Production 参考：生产环境的成本控制
• Gateway 源码 与 Provider 模型注册表源码：本文源码级结论的出处