
Roo Code 连接 LLM Provider 完全指南从 API Key 到首个 AI Agent 任务【免费下载链接】Roo-CodeRoo Code gives you a whole dev team of AI agents in your code editor.项目地址: https://gitcode.com/GitHub_Trending/ro/Roo-CodeRoo Code 是一个运行在 VS Code 中的 AI 编程 Agent它本身不包含推理能力必须通过外部 LLM 推理服务Provider获取模型输出。本文以 Roo Code 官方入门文档为骨架完整讲解如何选择并接入第一个 AI ProviderOpenRouter / Anthropic、如何获取 API Key、如何在 VS Code 面板内完成配置并结合仓库源码剖析 Provider 的实现机制、模型默认值与 Prompt Caching 原理。读完本文你将能够独立完成 Roo Code 的首个模型接入并开始编写代码。Roo Code 为什么需要一个 LLM ProviderRoo Code 的本质是一个「Agent 调度器」它负责任务拆解、工具调用读写文件、执行命令、搜索代码等、上下文管理与多步执行但真正产生智能响应的模型推理必须由外部服务完成。正如官方文档所述Roo Code needs an inference provider to access the LLM models that make it work。这也是 Roo Code 与其他被单一厂商绑定的工具的核心区别。从 apps/docs/docs/providers/index.mdx 的说明可以看到Roo Code 是model-agnostic模型无关的你可以根据预算、技能画像、代码库特点自由选择模型而不必受制于某一特定供应商。从源码结构看Roo Code 的 Provider 层是一套统一的 Handler 抽象在 src/api/providers/index.ts 中集中导出了 20 余种 Provider 处理器包括AnthropicHandler、OpenAiHandler、OpenRouterHandler、GeminiHandler、BedrockHandler、OllamaHandler、LmStudioHandler等。它们统一实现消息创建createMessage、单轮补全completePrompt等接口向核心任务引擎提供一致的推理能力这正是「接入任意 Provider」在工程层面的保障。起步模型选择为什么推荐 Claude Sonnet 4.5官方文档推荐的起步模型是Claude Sonnet 4.5理由是它在大多数任务上「开箱即用」it just works out of the box且价格/能力比合理。Roo Code 团队内部大量使用该模型。模型选择建议来自官方文档的Model Selection Advice推荐 Claude Sonnet 4.5在工具调用遵循、格式解析、多步操作上下文保持等方面表现稳定适合作为首个模型。换用其他模型会增加复杂度不同模型在「如何遵循工具指令」「如何解析格式」「如何在多步操作中维持上下文」上差异显著建议先熟练后再尝试。若要实验其他模型优先选择专门为**结构化推理structured reasoning与工具调用tool use**设计的模型避免选择纯聊天型模型导致 Agent 工具调用不稳定。这一推荐在源码中得到印证在 packages/types/src/providers/anthropic.ts 中Roo Code 的 Anthropic 默认模型 ID 正是anthropicDefaultModelId claude-sonnet-4-5而 packages/types/src/providers/openrouter.ts 中 OpenRouter 的默认模型 ID 是anthropic/claude-sonnet-4.5。也就是说无论你走哪条接入路径Roo Code 出厂默认就指向 Claude Sonnet 4.5选择默认值即可获得官方推荐的起步体验。两条主流接入路径OpenRouter 与 AnthropicRoo Code 兼容大量 Provider完整列表见 apps/docs/docs/providers/index.mdx 的 Provider 对比表其中官方文档重点介绍了两条接入 Claude Sonnet 4.5 的主流路径。路径一OpenRouter官方推荐OpenRouter 是一个聚合型 AI 平台通过一个 API Key 即可访问来自多个实验室的 100 模型适合追求灵活性和快速上手。官方将其标记为Recommended推荐。获取 API Key 的步骤详见 apps/docs/docs/providers/openrouter.md前往 OpenRouter 官网使用 Google 或 GitHub 账号注册/登录进入 Keys 页面查看已有 API Key若没有则新建一个复制该 API Key。模型列表Roo Code 会自动从 OpenRouter 的 API 拉取全部可用模型100 个来自不同厂商无需手动维护。在 Roo Code 中的配置要点点击 Roo Code 面板中的齿轮图标打开设置在 API Provider 下拉框中选择OpenRouter在 OpenRouter API Key 字段粘贴你的 API Key在 Model 下拉框中选择所需模型可选若需自定义 API 地址勾选 Use custom base URL 并填入 URL——绝大多数用户留空即可。从源码看OpenRouter 接入的默认 Base URL 为https://openrouter.ai/api/v1见 src/api/providers/openrouter.ts。OpenRouterHandler在构造时会通过getModels与getModelEndpoints异步预加载动态模型列表src/api/providers/openrouter.ts因此模型下拉框中的选项是实时从上游拉取的这正是「自动发现 100 模型」的底层实现。OpenRouter 的提示缓存Prompt Caching注意事项OpenRouter 会将缓存请求透传给支持缓存的上游模型对大多数模型只要模型本身支持缓存会自动生效。支持缓存的主要模型包括Anthropic Claude Sonnet 3.5/3.7、Claude Haiku 3.5、Claude Haiku 4.5新增以及 Google Gemini 系列。例外情况Gemini 模型通过 OpenRouter 访问 Google 的缓存机制时可能偶发响应延迟因此Gemini 模型必须手动勾选 Provider 设置中的 Enable Prompt Caching 复选框才能激活缓存。该复选框作为临时 workaround对 OpenRouter 上的非 Gemini 模型则无需勾选。源码中的OPEN_ROUTER_PROMPT_CACHING_MODELS集合packages/types/src/providers/openrouter.ts维护了这份缓存模型清单在 src/api/providers/openrouter.ts 中createMessage会根据模型 ID 命中该集合后为 Gemini 模型注入addGeminiCacheBreakpoints、为 Anthropic 模型注入addAnthropicCacheBreakpoints来插入缓存断点。BYOKBring Your Own Key如果你在 OpenRouter 上使用底层服务的自有 KeyOpenRouter 只收取正常费用的 5%Roo Code 会自动调整成本计算以反映这一折扣。路径二AnthropicClaude 官方直连Anthropic 是 Claude 系列模型的官方提供商直连可获得对 Claude 模型最完整的支持。需要 API 访问审批且存在按使用层级usage tier划分的速率限制rate limits不同层级的限制不同。获取 API Key 的步骤详见 apps/docs/docs/providers/anthropic.md前往 Anthropic Console注册或登录账号进入 API Keys 设置页面点击 Create Key 创建密钥建议命名例如 Roo Code立即复制并妥善保存——密钥只在创建时显示一次之后无法再次查看。在 Roo Code 中的配置要点打开 Roo Code 设置面板中的齿轮图标在 API Provider 下拉框中选择Anthropic在 Anthropic API Key 字段粘贴你的 API Key在 Model 下拉框中选择所需的 Claude 模型可选自定义 Base URL绝大多数用户无需修改。Anthropic 直连的特性Prompt CachingClaude 模型支持提示缓存可显著降低重复提示的成本与延迟。源码中AnthropicHandler会对系统提示词与最近的两条用户消息设置cache_control: ephemeral缓存断点并自动为支持的模型附加prompt-caching-2024-07-31beta 头见 src/api/providers/anthropic.ts。大上下文窗口Claude 模型拥有 200,000 token 的上下文窗口足以容纳大量代码与上下文。若在设置中启用 1M 上下文 betaSonnet 4/4.5/4.6 与 Opus 4.6 可通过context-1m-2025-08-07beta 头扩展至 1M tokensrc/api/providers/anthropic.ts并在 packages/types/src/providers/anthropic.ts 中切换到对应的分级定价tier pricing。速率限制Anthropic 按用量层级实施严格速率限制。如果频繁触发限流可联系 Anthropic 销售或改走 OpenRouter、Requesty 等其他 Provider 访问 Claude。在 VS Code 中完成首个模型配置这是官方文档给出的核心操作流程共 4 步打开 Roo Code 面板点击 VS Code 活动栏Activity Bar中的 Roo Code 图标在欢迎界面选择你的 LLM Provider从列表中选择 OpenRouter、Anthropic 或其他已支持的 Provider粘贴 API Key将上一步从 Provider 处复制的 API Key 粘贴到对应字段点击继续选择模型模型应显示为claude-sonnet-4-5Anthropic 直连或anthropic/claude-sonnet-4-5OpenRouter确认后完成配置。完成以上步骤后即可开始编码Now you can start coding!。Roo Code 会通过所选 Provider 调用模型为你执行代码编写、文件修改、命令执行等 Agent 任务。两个模型 ID 的差异值得注意claude-sonnet-4-5是 Anthropic API 使用的原生 IDRoo Code 内部注册表 packages/types/src/providers/anthropic.ts 中的键名而anthropic/claude-sonnet-4-5是 OpenRouter 聚合平台使用的带厂商前缀 ID。选择 Provider 后模型下拉框会自动呈现对应格式的 ID无需手动记忆。深入了解Provider 实现架构与模型注册表Provider Handler 统一抽象Roo Code 的所有 Provider 都以 Handler 类的形式实现统一继承BaseProvider并实现SingleCompletionHandler接口。以 OpenRouter 为例src/api/providers/openrouter.ts其职责包括消息格式转换将 Anthropic 格式的内部消息systemPromptmessages转换为 OpenAI Chat Completions 格式convertToOpenAiMessages对 Mistral 模型特殊处理 tool call ID 规范化模型参数解析通过getModelParams依据模型信息与用户设置解析maxTokens、temperature、topP、reasoning等参数流式响应处理逐 chunk 处理文本增量、推理内容reasoning_details、工具调用片段与用量统计错误处理解析 OpenRouter 特有的error.metadata.raw字段还原上游真实错误信息。模型注册表与定价元数据模型元数据集中在 packages/types/src/providers/ 目录下以ModelInfo结构描述每个模型的maxTokens、contextWindow、是否支持图片/缓存、输入输出单价与缓存读写单价。例如 Claude Sonnet 4.5 在 packages/types/src/providers/anthropic.ts 中的元数据为64,000 最大输出 token、200K 上下文、支持图片与提示缓存、输入 3 美元/百万 token、输出 15 美元/百万 token、缓存写入 3.75 美元/百万 token、缓存读取 0.3 美元/百万 token。这些定价数据会被 Roo Code 用于任务成本核算calculateApiCostAnthropic见 src/api/providers/anthropic.ts。更多可选 Provider除 OpenRouter 与 Anthropic 外Roo Code 还支持OpenAIGPT 系列官方 API、DeepSeek、Gemini、AWS Bedrock、Mistral、Moonshot、LiteLLM、LM Studio本地模型、Ollama本地模型、XAI、ZAI、Fireworks、SambaNova、Baseten、Vercel AI Gateway 等。官方文档的决策建议apps/docs/docs/providers/index.mdx想要访问大量模型选择 OpenRouter一个 Key 接入 100 模型想针对特定模型做优化使用各模型的一手官方 ProviderAnthropic、OpenAI 等想要本地/离线模型尝试 Ollama 或 LM Studio。各 Provider 的详细配置说明见 apps/docs/docs/providers/ 目录下的对应文档其中 OpenAI 的官方接入文档在 apps/docs/docs/providers/openai.md涵盖 GPT-5 系列的 reasoning effort、verbosity、temperature 等高级控制。常见问题与实用提示模型不稳定怎么办不同模型在工具调用遵循与格式解析上的表现差异很大若 Agent 行为异常优先回到推荐的 Claude Sonnet 4.5 或选择专为结构化推理与工具调用设计的模型。提示缓存不生效检查所用模型是否在支持列表内若通过 OpenRouter 使用 Gemini 模型务必在 Provider 设置中手动勾选 Enable Prompt Caching。频繁触发速率限制Anthropic确认当前 usage tier 的限制考虑升级层级、联系销售或改用 OpenRouter / Requesty 等聚合 Provider。成本控制善用提示缓存可显著降低重复任务开销Anthropic 缓存读取价格仅为常规输入的 1/10使用 BYOK 时 OpenRouter 仅收取 5% 加成Roo Code 会自动反映在成本统计中。模型 ID 记不住无需手动输入Roo Code 的模型下拉框会基于 Provider 注册表或动态拉取的模型列表自动填充只需按步骤选择即可。总结连接第一个 LLM Provider 是使用 Roo Code 的关键一步官方推荐以 OpenRouter聚合 100 模型灵活快速或 AnthropicClaude 官方直连功能最完整接入 Claude Sonnet 4.5然后在 VS Code 的 Roo Code 面板中依次完成「选 Provider → 粘 Key → 选模型」三步操作即可开始编程。其底层由统一的 Provider Handler 抽象、集中的模型注册表与自动化的提示缓存机制支撑使得模型无关的 Agent 体验成为可能。更完整的 Provider 列表与分厂商配置指南可继续阅读 apps/docs/docs/providers/index.mdx 及 apps/docs/docs/providers/ 目录下的各篇文档。【免费下载链接】Roo-CodeRoo Code gives you a whole dev team of AI agents in your code editor.项目地址: https://gitcode.com/GitHub_Trending/ro/Roo-Code创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考