Roo Code 接入 OpenRouter单 API 键畅用 100 模型的配置与提示词缓存实战指南【免费下载链接】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 内置 OpenRouter 提供方支持让你通过一个 API Key 即可在编辑器内调用来自 Anthropic、Google、OpenAI 等多家厂商的 100 语言模型并借助自动模型发现、提示词缓存与 BYOK 计费机制降低成本。读完本文你将掌握 OpenRouter API Key 的获取方式、Roo Code 面板中的完整配置步骤、缓存机制的手动开关时机以及底层实现原理模型拉取、成本核算与错误处理从而在自己的开发环境中快速切换和实验各类模型。为什么在 Roo Code 中使用 OpenRouterOpenRouter 是一个 AI 聚合平台通过单一统一 API 提供来自不同厂商的大量语言模型。对 Roo Code 用户而言它的价值体现在三个方面配置简化只需一个 API Key即可访问 Anthropic、Google、OpenAI、DeepSeek、Perplexity 等多家模型不必为每个厂商分别注册和配置密钥实验便利同一套配置下可以随时切换模型对比效果便于为不同任务挑选最合适的模型成本透明计费基于底层模型的官方定价且支持自带密钥BYOK场景下的费用自动折算。Roo Code 将 OpenRouter 实现为内置提供方对应源码位于 src/api/providers/openrouter.ts其官方关联配置文档见 apps/docs/docs/providers/openrouter.md。第一步获取 OpenRouter API Key在配置 Roo Code 之前需要先准备好 API Key流程如下注册/登录访问 OpenRouter 官网使用 Google 或 GitHub 账号登录进入 Keys 页面打开账号下的 API Keys 管理页面页面中通常会列出现有 Key如果没有点击创建新 Key复制 Key复制生成的 API Key 字符串保存到安全位置后续粘贴进 Roo Code 设置。第二步在 Roo Code 中完成配置配置入口位于 Roo Code 面板的设置中操作步骤如下打开设置点击 Roo Code 面板中的齿轮图标Codicongear选择提供方在 API Provider 下拉框中选中OpenRouter填入 API Key将上一步复制的 Key 粘贴到 OpenRouter API Key 字段选择模型在 Model 下拉框中选择期望使用的模型可选自定义 Base URL如需使用自定义的 OpenRouter API 端点勾选 Use custom base URL 并填入 URL绝大多数用户保持留空即可。从设置结构的源码看OpenRouter 提供方在 Roo Code 中对应的配置项定义于 packages/types/src/provider-settings.ts共四个字段配置字段说明openRouterApiKeyOpenRouter API Key请求时作为 Bearer 凭证传给 OpenAI 兼容客户端openRouterModelId模型 ID如anthropic/claude-sonnet-4.5未指定时使用默认模型openRouterBaseUrl自定义 Base URL默认回退到https://openrouter.ai/api/v1openRouterSpecificProvider指定路由到某个具体上游供应商进阶用法见下文底层客户端初始化逻辑见 src/api/providers/openrouter.ts当openRouterBaseUrl为空时自动使用官方默认地址https://openrouter.ai/api/v1同时以DEFAULT_HEADERS携带HTTP-Referer、X-Title、User-Agent等标识头定义于 src/api/providers/constants.ts发起请求便于 OpenRouter 识别流量来源。默认模型与模型参数当未选择模型时Roo Code 会回退到默认模型 IDanthropic/claude-sonnet-4.5其默认信息20 万上下文、8192 最大输出 token、支持图片输入与提示词缓存等定义于 packages/types/src/providers/openrouter.ts。getModel()在组装请求参数时见 src/api/providers/openrouter.ts会优先采用用户选择的模型与厂商端点信息并对 OpenAI 系模型自动注入apply_diff/write_to_file等工具偏好对deepseek/deepseek-r1与perplexity/sonar-reasoning使用 R1 消息格式与 0.95 的默认 top_p。对应行为在 src/api/providers/tests/openrouter.spec.ts 中有完整用例覆盖。自动模型发现100 模型从哪来Roo Code自动从 OpenRouter API 拉取全部可用模型100 个来自多家厂商因此你无需手工维护模型清单。模型 ID 采用 OpenRouter 的厂商/模型命名格式例如anthropic/claude-sonnet-4.5、google/gemini-2.5-flash、openai/gpt-4o。这一能力的底层实现分为两个层面模型清单抓取src/api/providers/fetchers/openrouter.ts 请求 OpenRouter 的/models接口使用 Zod Schema 校验响应结构并过滤掉输出模态为图像image generation的模型随后通过parseOpenRouterModel将context_length、pricing、supported_parameters等原始字段转换为 Roo Code 内部的ModelInfo含maxTokens、contextWindow、inputPrice、outputPrice、cacheWritesPrice、cacheReadsPrice、supportsPromptCache等。两级缓存src/api/providers/fetchers/modelCache.ts 先查内存缓存TTL 5 分钟未命中再查磁盘缓存缓存目录/openrouter_models.json两者都未命中才真正请求 OpenRouter只有非空结果才会写入缓存避免把失败的 API 响应持久化。扩展激活后还会在后台静默刷新 OpenRouter 等无需 Key 的公共提供方缓存见 src/api/providers/fetchers/modelCache.ts保证模型下拉框始终可用且不过期。此外Roo Code 还会针对当前选中的模型请求/models/{modelId}/endpoints端点见 src/api/providers/fetchers/openrouter.ts拿到该模型在各上游供应商处的端点信息供“指定供应商”功能使用。关于最新、完整的模型列表含定价与能力标注请以 OpenRouter 官网的 Models 页面为准。进阶指定上游供应商openRouterSpecificProviderOpenRouter 上的同一个模型 ID 可能由多个上游供应商托管。Roo Code 提供openRouterSpecificProvider选项让你锁定某个具体供应商当该值非空且不等于[default]常量OPENROUTER_DEFAULT_PROVIDER_NAME见 packages/types/src/providers/openrouter.ts时请求参数中会附带provider: { order: [...], only: [...], allow_fallbacks: false }即只从指定供应商出价、禁止回退见 src/api/providers/openrouter.ts。同时getModel()会优先使用该供应商对应的端点信息覆盖默认模型信息。这个选项适合对供应商有明确偏好、或需要规避某条上游链路问题的场景。提示词缓存Prompt Caching何时需要手动开启OpenRouter 会把缓存请求透传给支持缓存的上游模型。Roo Code 在发起请求前会检查模型 ID 是否命中内置的OPEN_ROUTER_PROMPT_CACHING_MODELS集合定义于 packages/types/src/providers/openrouter.ts命中后自动向 system 与消息块注入缓存断点对google/*模型调用 Gemini 缓存断点注入器addGeminiCacheBreakpoints对其他主要是 Anthropic 系模型调用 Anthropic 缓存断点注入器addAnthropicCacheBreakpoints即为 system prompt 与首条用户消息附加cache_control: { type: ephemeral }。对应断言可见 src/api/providers/tests/openrouter.spec.ts。对绝大多数模型而言只要模型本身支持缓存缓存会自动生效工作方式与 Requesty 类似。当前集合覆盖的模型包括节选Anthropic Claude 3.5 Sonnet / 3.7 Sonnet含:thinking、:beta变体Anthropic Claude 3.5 Haiku / Claude Haiku 4.5新加入Anthropic Claude Sonnet 4 / 4.5 / 4.6、Claude Opus 4 / 4.1 / 4.5 / 4.6Google Gemini 2.0 Flash、2.5 Flash 及 Preview 变体、Gemini Flash 1.5 等例外Gemini 模型需要手动开启。由于经 OpenRouter 访问 Google 缓存机制时偶尔会出现响应延迟Roo Code 要求使用 Gemini 模型时必须手动勾选提供方设置中的 Enable Prompt Caching 复选框来激活缓存该复选框是一个临时性变通方案对 OpenRouter 上的非 Gemini 模型这个复选框对缓存并非必需。自带密钥BYOK与成本核算如果你为底层服务提供自己的 API KeyBYOKOpenRouter 仅收取正常费用的5%作为中转费用。Roo Code 会自动调整成本计算以反映这一点因此在 Roo Code 的会话成本统计中看到的费用即为折算后的结果。费用数据同时来自 OpenRouter 返回的usage信息含cached_tokens、reasoning_tokens以及cost/cost_details字段见 src/api/providers/openrouter.tsRoo Code 会把输入、输出、缓存读取与推理 token 一并计入统计。常见错误与排障OpenRouter 请求失败时错误可能来自 SDK 抛出也可能以流式响应中的error对象形式返回其中metadata.raw往往携带上游供应商的原始错误信息。Roo Code 在 src/api/providers/openrouter.ts 实现了extractErrorFromMetadataRaw会解析metadata.raw中常见的message、error、error.message结构并还原真实错误原因随后以OpenRouter API Error code: message的形式抛出。测试覆盖了 429 限流、连接失败、上游错误透传等典型场景见 src/api/providers/tests/openrouter.spec.ts。遇到报错时重点检查API Key 是否正确粘贴、是否在 OpenRouter 端仍有效所选模型 ID 是否在 OpenRouter 上存在可在模型的 Model 下拉框中重新选择是否触发了上游供应商的限流429可稍后重试自定义 Base URL 是否填写正确绝大多数场景应保持留空。小结一套配置自由实验在 Roo Code 中启用 OpenRouter 只需“注册获取 Key → 面板选择 OpenRouter → 粘贴 Key → 选择模型”四步。借助自动模型发现机制你可以在一个编辑器内自由横跳 Anthropic、Google、OpenAI 等厂商的模型结合提示词缓存的自动/手动开启策略与 BYOK 计费折算还能在保持成本可控的同时找到最适合自己工作流的那款模型。需要获取官方最新模型与定价信息时请以 OpenRouter 官网 Models 页面为准并将本指南与仓库中的 OpenRouter 源码实现 对照阅读以获得更深入的掌握。【免费下载链接】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），仅供参考
