)
Cline SDK 模型提供商指南cline/llms 的 Gateway、Provider Registry 與成本追蹤實戰(zhàn)【免費下載鏈接】clineAutonomous coding agent as an SDK, IDE extension, or CLI assistant.項目地址: https://gitcode.com/GitHub_Trending/cl/cline本文基于 Cline SDK 官方技能文檔 providers/REFERENCE.md系統(tǒng)講解如何通過cline/llms在 Cline SDK 中接入 Anthropic、OpenAI、Gemini、Vertex AI、AWS Bedrock、Mistral 及任意 OpenAI 兼容服務(wù)包括 Agent 與 ClineCore 兩種配置入口、各提供商的專屬參數(shù)、自定義 Base URL 與請求頭以及面向多提供商場景的 Gateway API、Provider Registry 編程接口和按請求粒度的成本追蹤。讀完本篇你可以獨立完成從單一 API Key 接入到多提供商網(wǎng)關(guān) 自定義 Provider 注冊的完整落地并理解 Gateway 內(nèi)部的模型解析與 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.從源碼結(jié)構(gòu)看這些內(nèi)置提供商并非硬編碼在 Gateway 中而是由 builtins.ts 匯總的BUILTIN_PROVIDER_REGISTRATIONS注冊到 Gateway 的 Registry 中DefaultGateway構(gòu)造時默認加載全部內(nèi)置提供商也可以通過配置裁剪詳見后文 Gateway 小節(jié)。此外源碼中還維護了提供商 ID 的規(guī)范化邏輯如大小寫與別名歸一和 OpenAI Codex 模型過濾等細節(jié)說明實際可用模型集合會隨生成目錄catalog動態(tài)更新?;九渲梅绞揭慌浜?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 是面向完整智能體循環(huán)的運行時入口提供商配置通過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做規(guī)范化然后查詢工廠注冊表中是否存在已注冊的自定義 Handler未命中時回落到createGatewayApiHandler走統(tǒng)一的 Gateway 通道見 providers.ts。這意味著你注冊的自定義 Handler 優(yōu)先級高于內(nèi)置 Gateway 實現(xiàn)是擴展提供商時的兩條路徑之一。各提供商專屬配置以下配置塊來自官方參考文檔可直接作為Agent構(gòu)造參數(shù)或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 應(yīng)用默認憑據(jù)或服務(wù)賬號機制。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 標準憑據(jù)鏈環(huán)境變量、配置文件或 IAM Role。注意 Bedrock 的模型 ID 使用廠商前綴格式anthropic.claude-sonnet-4-6與直接調(diào)用 Anthropic API 時的裸模型 ID 不同。Mistral{ providerId: mistral, modelId: mistral-large-latest, apiKey: process.env.MISTRAL_API_KEY, }OpenAI-Compatible兼容端點任何提供 OpenAI 兼容 API 的服務(wù)都可以通過openai-compatible接入關(guān)鍵是多傳一個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 等。從源碼看本地部署場景還有一個實用細節(jié)針對 OllamaSDK 內(nèi)置了OLLAMA_DEFAULT_CONTEXT_WINDOW 32768的默認上下文窗口常量見 builtins.ts因為 Ollama 服務(wù)端 4096 的默認值裝不下智能體類長提示該常量是 vendor、VS Code 會話工廠與設(shè)置 UI 共享的單一事實來源。自定義 Base URL任意提供商都可以通過baseUrl覆蓋 API 端點適合走企業(yè)代理、私有網(wǎng)關(guān)或內(nèi)網(wǎng)推理服務(wù){(diào) providerId: anthropic, modelId: claude-sonnet-4-6, apiKey: process.env.API_KEY, baseUrl: https://my-proxy.example.com/v1, }自定義請求頭headers字段可以向所有 API 請求附加額外 HTTP 頭常用于網(wǎng)關(guān)鑒權(quán)、租戶標識或追蹤字段透傳{ providerId: openai, modelId: gpt-5.5, apiKey: process.env.API_KEY, headers: { X-Custom-Header: value, }, }Gateway API多提供商網(wǎng)關(guān)對于同時對接多個提供商的進階場景可以繞過單提供商三元組模式直接使用cline/llms導(dǎo)出的 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。從源碼實現(xiàn)看其構(gòu)造過程分三步加載內(nèi)置提供商默認注冊全部BUILTIN_PROVIDER_REGISTRATIONS可用config.builtins: false關(guān)閉或用 id 白名單裁剪注冊自定義 providerconfig.providers中的每一項依次調(diào)用registerProvider應(yīng)用提供商配置config.providerConfigs中的apiKey、baseUrl、headers等通過configureProvider寫入 Registrygateway.ts。Gateway 方法一覽方法作用gateway.registerProvider(registration)注冊自定義提供商gateway.configureProvider(config)更新某個提供商的配置gateway.listProviders()列出可用提供商gateway.listModels(providerId?)列出可用模型gateway.createAgentModel(selection)為 Agent 創(chuàng)建模型句柄gateway.stream(request)原始流式請求返回PromiseAsyncIterableAgentModelEventcreateAgentModel返回的是內(nèi)部GatewayModelAdapter它實現(xiàn)了AgentModel接口把systemPrompt、messages、tools、temperature、maxTokens、reasoning等請求參數(shù)合并后轉(zhuǎn)交給gateway.stream()。在發(fā)起流式請求時Gateway 會做兩件事值得注意能力校驗先檢查提供商/模型聲明的模態(tài)是否支持當前操作providerManifestSupportsModelOperation再過濾模型不支持的modelTools如web_search、image_generation不支持時直接拋錯而不是發(fā)出無效請求gateway.tsmaxTokens 自動協(xié)商resolveGatewayRequestMaxTokens會把用戶顯式請求值、模型maxOutputTokens上限、上下文窗口剩余空間預(yù)留 1024 token 輸出余量取最小值未顯式指定時默認 32000 token若估算輸入 token 已超過上下文窗口則回退為undefined并記錄告警日志gateway.ts。這套邏輯解釋了為什么你通常不需要手動為每個模型計算maxTokens。Provider Registry編程式查詢與注冊不依賴 Gateway 實例時cline/llms還暴露了一組基于模塊級注冊表的函數(shù)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({ ... }), })這些函數(shù)對應(yīng) model-registry.ts 中的實現(xiàn)有兩個源碼級事實值得補充getAllProviders()、getProvider()、getModelsForProvider()在源碼中是async 函數(shù)返回Promise實際項目代碼中調(diào)用時需要awaitregisterProvider(collection)將整個提供商集合含其模型字典寫入自定義表registerModel(providerId, modelId, info)則以單模型粒度覆蓋/新增元數(shù)據(jù)自定義注冊在查詢時優(yōu)先于內(nèi)置條目CUSTOM_PROVIDERS與CUSTOM_MODELS覆蓋PROVIDER_CACHE見 model-registry.ts。此外還配有unregisterModel、unregisterProvider與resetRegistry用于測試清理。getModelsForProvider還支持filter: chat選項只返回聊天兼容模型。模型元數(shù)據(jù)通過注冊表可查詢模型的上下文窗口、價格與能力適合在 UI 中渲染模型選擇器或做預(yù)算估算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 自動協(xié)商maxTokens時讀取的元數(shù)據(jù)來源二者構(gòu)成注冊元數(shù)據(jù) → 運行時請求裁剪的閉環(huán)。成本追蹤SDK 在三層暴露成本數(shù)據(jù)覆蓋事件流、運行結(jié)果、會話累計三種消費場景// 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 運行時在每次模型往返后發(fā)出見 agent-runtime.ts 附近的事件發(fā)射邏輯而 ClineCore 側(cè)對連續(xù)usage-updated事件做了首條事件 delta 等于累計值、后續(xù)事件 delta 為增量、總量持續(xù)累加的語義處理相關(guān)行為有專門的測試覆蓋runtime-event-adapter.test.ts。totalCost為可選值價格元數(shù)據(jù)缺失的模型會返回undefined代碼中建議保持文檔示例中的?.toFixed(4)防御寫法。延伸閱讀Agent 參考在 Agent 中使用提供商ClineCore 參考在 ClineCore 中使用提供商Production 參考生產(chǎn)環(huán)境的成本控制Gateway 源碼 與 Provider 模型注冊表源碼本文源碼級結(jié)論的出處【免費下載鏈接】clineAutonomous coding agent as an SDK, IDE extension, or CLI assistant.項目地址: https://gitcode.com/GitHub_Trending/cl/cline創(chuàng)作聲明:本文部分內(nèi)容由AI輔助生成(AIGC),僅供參考