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

Cline SDK 模型提供商指南cline/llms 的 Gateway、Provider Registry 与成本追踪实战【免费下载链接】clineAutonomous coding agent as an SDK, IDE extension, or CLI assistant.项目地址: https://gitcode.com/GitHub_Trending/cl/cline本文基于 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模型anthropicClaude Opus 4.7, Sonnet 4.6, Haiku 4.5openaiGPT-5.5, GPT-5.3 CodexgeminiGemini 3.1 Pro Preview, Gemini 3 Flash PreviewvertexGoogle models via Vertex AIbedrockClaude, Llama via AWS BedrockmistralMistral Large, Codestralopenai-compatiblevLLM, Together, Fireworks, Groq, etc.从源码结构看这些内置提供商并非硬编码在 Gateway 中而是由 builtins.ts 汇总的BUILTIN_PROVIDER_REGISTRATIONS注册到 Gateway 的 Registry 中DefaultGateway构造时默认加载全部内置提供商也可以通过配置裁剪详见后文 Gateway 小节。此外源码中还维护了提供商 ID 的规范化逻辑如大小写与别名归一和 OpenAI Codex 模型过滤等细节说明实际可用模型集合会随生成目录catalog动态更新。基本配置方式一配合 Agent 使用最简单的接入方式是直接给Agent传入提供商三元组providerId/modelId/apiKeyimport { 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 等。从源码看本地部署场景还有一个实用细节针对 OllamaSDK 内置了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导出的 Gatewayimport { 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。从源码实现看其构造过程分三步加载内置提供商默认注册全部BUILTIN_PROVIDER_REGISTRATIONS可用config.builtins: false关闭或用 id 白名单裁剪注册自定义 providerconfig.providers中的每一项依次调用registerProvider应用提供商配置config.providerConfigs中的apiKey、baseUrl、headers等通过configureProvider写入 Registrygateway.ts。Gateway 方法一览方法作用gateway.registerProvider(registration)注册自定义提供商gateway.configureProvider(config)更新某个提供商的配置gateway.listProviders()列出可用提供商gateway.listModels(providerId?)列出可用模型gateway.createAgentModel(selection)为 Agent 创建模型句柄gateway.stream(request)原始流式请求返回PromiseAsyncIterableAgentModelEventcreateAgentModel返回的是内部GatewayModelAdapter它实现了AgentModel接口把systemPrompt、messages、tools、temperature、maxTokens、reasoning等请求参数合并后转交给gateway.stream()。在发起流式请求时Gateway 会做两件事值得注意能力校验先检查提供商/模型声明的模态是否支持当前操作providerManifestSupportsModelOperation再过滤模型不支持的modelTools如web_search、image_generation不支持时直接抛错而不是发出无效请求gateway.tsmaxTokens 自动协商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实际项目代码中调用时需要awaitregisterProvider(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 模型注册表源码本文源码级结论的出处【免费下载链接】clineAutonomous coding agent as an SDK, IDE extension, or CLI assistant.项目地址: https://gitcode.com/GitHub_Trending/cl/cline创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考