Roo Code 连接 LLM Provider 完全指南：从 API Key 到首个 AI Agent 任务

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-Code

Roo Code 是一个运行在 VS Code 中的 AI 编程 Agent，它本身不包含推理能力，必须通过外部 LLM 推理服务（Provider）获取模型输出。本文以 Roo Code 官方入门文档为骨架，完整讲解如何选择并接入第一个 AI Provider（OpenRouter / Anthropic）、如何获取 API Key、如何在 VS Code 面板内完成配置，并结合仓库源码剖析 Provider 的实现机制、模型默认值与 Prompt Caching 原理。读完本文，你将能够独立完成 Roo Code 的首个模型接入并开始编写代码。

Roo Code 为什么需要一个 LLM Provider

Roo 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 与 Anthropic

Roo 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）：

1. 前往 OpenRouter 官网，使用 Google 或 GitHub 账号注册/登录；
2. 进入 Keys 页面，查看已有 API Key，若没有则新建一个；
3. 复制该 API Key。

模型列表：Roo Code 会自动从 OpenRouter 的 API 拉取全部可用模型（100+ 个，来自不同厂商），无需手动维护。

在 Roo Code 中的配置要点：

1. 点击 Roo Code 面板中的齿轮图标打开设置；
2. 在 "API Provider" 下拉框中选择OpenRouter；
3. 在 "OpenRouter API Key" 字段粘贴你的 API Key；
4. 在 "Model" 下拉框中选择所需模型；
5. （可选）若需自定义 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来插入缓存断点。

BYOK（Bring Your Own Key）：如果你在 OpenRouter 上使用底层服务的自有 Key，OpenRouter 只收取正常费用的 5%，Roo Code 会自动调整成本计算以反映这一折扣。

路径二：Anthropic（Claude 官方直连）

Anthropic 是 Claude 系列模型的官方提供商，直连可获得对 Claude 模型最完整的支持。需要 API 访问审批，且存在按使用层级（usage tier）划分的速率限制（rate limits），不同层级的限制不同。

获取 API Key 的步骤（详见 apps/docs/docs/providers/anthropic.md）：

1. 前往 Anthropic Console，注册或登录账号；
2. 进入 API Keys 设置页面；
3. 点击 "Create Key" 创建密钥，建议命名（例如 "Roo Code"）；
4. 立即复制并妥善保存——密钥只在创建时显示一次，之后无法再次查看。

在 Roo Code 中的配置要点：

1. 打开 Roo Code 设置（面板中的齿轮图标）；
2. 在 "API Provider" 下拉框中选择Anthropic；
3. 在 "Anthropic API Key" 字段粘贴你的 API Key；
4. 在 "Model" 下拉框中选择所需的 Claude 模型；
5. （可选）自定义 Base URL，绝大多数用户无需修改。

Anthropic 直连的特性：

• Prompt Caching：Claude 模型支持提示缓存，可显著降低重复提示的成本与延迟。源码中AnthropicHandler会对系统提示词与最近的两条用户消息设置cache_control: ephemeral缓存断点，并自动为支持的模型附加prompt-caching-2024-07-31beta 头（见 src/api/providers/anthropic.ts）。
• 大上下文窗口：Claude 模型拥有 200,000 token 的上下文窗口，足以容纳大量代码与上下文。若在设置中启用 1M 上下文 beta，Sonnet 4/4.5/4.6 与 Opus 4.6 可通过context-1m-2025-08-07beta 头扩展至 1M token（src/api/providers/anthropic.ts），并在 packages/types/src/providers/anthropic.ts 中切换到对应的分级定价（tier pricing）。
• 速率限制：Anthropic 按用量层级实施严格速率限制。如果频繁触发限流，可联系 Anthropic 销售，或改走 OpenRouter、Requesty 等其他 Provider 访问 Claude。

在 VS Code 中完成首个模型配置

这是官方文档给出的核心操作流程，共 4 步：

1. 打开 Roo Code 面板：点击 VS Code 活动栏（Activity Bar）中的 Roo Code 图标；
2. 在欢迎界面选择你的 LLM Provider：从列表中选择 OpenRouter、Anthropic 或其他已支持的 Provider；
3. 粘贴 API Key：将上一步从 Provider 处复制的 API Key 粘贴到对应字段，点击继续；
4. 选择模型：模型应显示为claude-sonnet-4-5（Anthropic 直连）或anthropic/claude-sonnet-4-5（OpenRouter），确认后完成配置。

完成以上步骤后，即可开始编码（Now you can start coding!）。Roo Code 会通过所选 Provider 调用模型，为你执行代码编写、文件修改、命令执行等 Agent 任务。

两个模型 ID 的差异值得注意：claude-sonnet-4-5是 Anthropic API 使用的原生 ID（Roo 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 格式的内部消息（systemPrompt+messages）转换为 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 还支持：OpenAI（GPT 系列官方 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+ 模型；
• 想针对特定模型做优化：使用各模型的一手官方 Provider（Anthropic、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+ 模型，灵活快速）或 Anthropic（Claude 官方直连，功能最完整）接入 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