如果你仍在维护 Roo Code 安装，Roo Code OpenAI 兼容 API 这条路径主要是一个配置层面的问题：提供商类型、Base URL、API 密钥和模型 ID。真正的生产风险是很容易被忽略的那一部分。Roo Code 的提供商文档对这条路径要求原生 OpenAI 风格的工具调用，因此仅有普通聊天回复并不足以证明它适用于编码代理工作流。
本指南面向开发者、AI 产品团队、自动化构建者、平台工程师、财务运营人员和采购审核人员，展示如何通过 Flatkey 路由现有的 Roo Code 配置。内容涵盖当前 Roo Code 的注意事项、Flatkey Base URL 验证、精确的模型别名、原生工具调用预检、Roo Code 设置、用量审查以及回滚。
来源说明：本文于 2026 年 6 月 29 日对照官方 Roo Code 文档主页、官方 Roo Code OpenAI Compatible 提供商文档、实时 Flatkey 公共页面以及一次已认证的 Flatkey 网关冒烟测试进行了检查。Roo Code 文档主页说明 Roo Code 扩展已于 2026 年 5 月 15 日关闭，因此应将本文视为现有安装、归档配置或迁移审查的设置指南，而不是在未确认扩展可用性的情况下建议你将其作为新部署标准化的推荐。
快速回答：Roo Code OpenAI 兼容 API 设置
对于使用 Flatkey 的 Roo Code OpenAI 兼容 API 设置，请将 OpenAI Compatible 选为 API 提供商，粘贴当前 Flatkey Base URL，使用 Flatkey API 密钥，并输入一个支持 OpenAI 兼容聊天和原生工具调用的精确 Flatkey 模型别名。然后先用一个小型 curl 请求证明这条路径可用，再把它用于代码工作区。
| Roo Code 字段 | Flatkey 值 | 审核检查 |
|---|---|---|
| API Provider | OpenAI Compatible | Flatkey 使用此提供商，而不是官方 OpenAI 提供商。 |
| Base URL | 适用于你账户的当前 Flatkey 提供商 Base URL，例如在该值经过验证时为 https://router.flatkey.ai/v1 |
只粘贴 Base URL。不要将完整的 /chat/completions 端点粘贴到 Roo Code 中。 |
| API Key | 由正确的用户、团队或环境持有的 Flatkey 密钥 | 不要将上游提供商密钥与 Flatkey Base URL 混用。 |
| Model ID | 为该密钥启用的精确 Flatkey 模型别名 | 在用于编码任务之前，确认该别名支持 OpenAI 聊天端点和原生工具调用。 |
| Validation | 先做小型聊天和工具调用冒烟测试，然后再发出一个安全的 Roo Code 提示 | 测试后检查 Flatkey 用量，以便财务和平台负责人能够对这条路由进行对账。 |
最短且安全的路径是：验证 Flatkey 传输，验证模型别名，验证原生工具调用，然后保存 Roo Code 设置。本文其余部分将把这份 Roo Code OpenAI 兼容 API 指南整理为可重复执行的检查清单。
当前 Roo Code 文档确认了什么
Roo Code 文档主页当前带有扩展关闭警告。这对规划很重要。如果你的团队正在使用现有的 Roo Code 安装，下面的配置细节对于维护和迁移审查仍然有用。如果你的团队正在选择新的标准编码助手，请先确认扩展、市场和分支状态，再将 Roo Code 分配给更广泛的团队。
Roo Code OpenAI Compatible 提供商页面为该类提供商记录了三个主要值：Base URL、API Key 和 Model ID。它还说明应将 OpenAI Compatible 作为 API 提供商。Base URL 是提供商端点，在你使用非 OpenAI 兼容提供商时，它明确不是官方 OpenAI API URL。
Roo Code 特有的重要约束是工具调用。同一提供商页面说明 Roo Code 仅使用原生工具调用，没有基于 XML 的回退方案。它还说明所选模型必须支持 OpenAI 兼容工具调用。对于通过 Flatkey 进行的 Roo Code OpenAI 兼容 API 路由，这意味着不能仅靠纯文本生成来验证模型别名。
在打开 Roo Code 之前需要确认的 Flatkey 值
1. 确认你账户的 Base URL
Flatkey 首页在 2026 年 6 月 29 日检查时的标题为 One API gateway for production AI teams，元描述说明 Flatkey 统一了模型访问、路由、计费、用量分析和运营控制。公共主页示例包括 OpenAI 风格的聊天补全。本文的一次已认证运行时检查使用了 https://router.flatkey.ai/v1，并返回了有效的模型列表。
由于公共示例和账户特定路由会随时间变化，在生产环境之前，请从控制台、文档或工作环境中复制当前的 Flatkey Base URL。在 Roo Code 中，Base URL 应该是提供商基础地址，而不是 /v1/chat/completions。
2. 确认模型别名和工具支持
截至 2026 年 6 月 29 日检查的 Flatkey 定价页面显示，它为 23 家提供商下的 635 个 AI 模型发布了服务端渲染的定价信息。其端点映射包括 /v1/chat/completions、/v1/responses、/v1/messages、/v1/images/generations 和 /v1/video/generations。这只是目录和端点证据，并不意味着每个 Flatkey 密钥都能调用每个模型。
对于 Roo Code OpenAI compatible API 设置，请选择一个账户可见、支持 OpenAI 兼容聊天和工具调用的模型别名。本文的认证检查返回了 56 个账户可见模型，并且使用 gpt-5.4-mini 发起的一次小型工具调用请求返回了 HTTP 200，且 finish_reason: tool_calls 和使用量元数据均正常。请将其视为针对已测试账户的、带日期的路由证明，而不是适用于每个 Flatkey 工作区的永久建议。
3. 确认密钥所有权和使用审查
Roo Code 可以对代码工作区执行操作，因此密钥所有权很重要。请使用作用域限定到拥有相关风险的开发者、团队或环境的 Flatkey 密钥。记录谁可以轮换该密钥、允许使用哪个模型别名、预期使用哪个端点族，以及第一次提示后会在哪里审查使用日志。
分步：使用 Flatkey 配置 Roo Code
- 检查这是否是现有的 Roo Code 安装。 由于官方文档目前提到了扩展停用，因此不要先假设可以直接进行全新的市场安装。
- 打开 Roo Code 提供商设置。 在现有扩展配置中，进入模型提供商或 API 配置区域。
- 选择 OpenAI Compatible。 对于非 OpenAI 兼容端点，使用 Roo Code 文档中说明的提供商类型。
- 设置 Base URL。 输入已验证的 Flatkey 基础 URL，例如当它是您账户当前可用值时使用
https://router.flatkey.ai/v1。 - 粘贴 Flatkey API key。 不要将其保存在仓库文件、问题评论、截图或提示词中。
- 设置 Model ID。 输入精确的 Flatkey 模型别名。除非 Flatkey 已向您的密钥暴露该确切别名，否则不要使用通用的供应商家族名称。
- 运行下面的 curl 预检。 纯聊天很有用，但 Roo Code 需要原生工具调用，因此在测试中要包含工具 schema。
- 运行一次安全的 Roo Code 提示。 在将 Roo Code 指向生产仓库之前，请先使用一次可丢弃的工作区或非破坏性任务。
- 检查 Flatkey 使用情况。 确认时间戳、密钥所有者、模型别名、令牌使用量、状态和成本可见性。
- 记录回滚方案。 在请更多开发者切换之前，保存先前的提供商设置、模型别名和所有者。
原生工具调用预检模板
调试 Roo Code OpenAI compatible API 设置最安全的方法，是先在 Roo Code 之外测试 Flatkey 路由。此模板用于验证聊天端点，并要求模型返回一个 OpenAI 风格的工具调用。
export FLATKEY_API_KEY="fk_replace_me"
export FLATKEY_BASE_URL="https://router.flatkey.ai/v1"
export FLATKEY_ROO_MODEL="replace-with-tool-capable-flatkey-model"
curl "$FLATKEY_BASE_URL/chat/completions" \
-H "Authorization: Bearer $FLATKEY_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "'"$FLATKEY_ROO_MODEL"'",
"messages": [
{
"role": "user",
"content": "Call route_check with status ok and do not include prose."
}
],
"tools": [
{
"type": "function",
"function": {
"name": "route_check",
"description": "Return the routing smoke-test status.",
"parameters": {
"type": "object",
"properties": {
"status": { "type": "string" }
},
"required": ["status"]
}
}
}
],
"tool_choice": {
"type": "function",
"function": { "name": "route_check" }
},
"max_tokens": 64
}'健康的响应应包含带有 tool_calls 的 assistant 消息。如果此请求失败，请在更改 Roo Code 设置之前先修复 Flatkey 密钥、基础 URL、模型别名或模型能力。如果它成功但 Roo Code 失败，请重点检查已保存的 Roo Code 字段、本地网络访问、扩展状态，或在提供商设置中输入的确切 Model ID。
首先要排查的故障模式
| 症状 | 可能原因 | 修复方法 |
|---|---|---|
| API 密钥无效 | 密钥复制错误、已轮换、作用域属于其他环境，或实际上来自上游提供商而不是 Flatkey。 | 使用新的 Flatkey 密钥，先用 curl 测试，然后将同一个密钥粘贴到 Roo Code 中。 |
| 连接错误 | Base URL 错误、将完整端点路径粘贴到了 Base URL 字段、网络路径被阻止，或本地代理问题。 | 在同一台机器上验证提供商的 base URL，然后重新测试 /chat/completions。 |
| 未找到模型 | Roo Code 模型 ID 与为该密钥启用的 Flatkey 别名不匹配。 | 从 Flatkey 定价、目录或账户可见的模型列表中复制准确的别名。 |
| 工具调用错误 | 所选模型可以进行聊天回答，但不支持与 OpenAI 兼容的原生工具调用。 | 切换到支持工具调用的模型别名，并在使用 Roo Code 之前重新运行预检。 |
| 扩展不可用 | 当前 Roo Code 分发状态不支持计划中的安装或更新路径。 | 将该设置视为遗留维护，并为新的部署选择一个活跃的编码代理工作流。 |
| 无法对账用量 | 团队未记录密钥所有者、模型别名、Roo Code 用户、环境或时间戳。 | 在向更多开发者扩展该路径之前，先添加一行运行手册记录。 |
现有安装还是新标准？
Roo Code OpenAI compatible API 这条路径可能有用，但扩展停止服务的通知改变了决策。在要求团队依赖它之前，请先查看这张表。
| 情况 | 建议操作 | 重要原因 |
|---|---|---|
| 已有的 Roo Code 安装仍被开发者使用 | 记录 Flatkey 路径，测试工具调用，并保留回滚方案。 | 在团队计划迁移或替换期间，维护工作仍可继续。 |
| 新的团队级编码代理推广 | 先验证当前扩展是否可用，然后比较可用替代方案。 | 已停用的扩展可能带来支持、安全和上手风险。 |
| 工具集成集群标准化 | 在各工具间使用相同的 Flatkey 密钥、base URL、模型别名和用量日志模式。 | 一致性能让计费、调试和采购审查更容易。 |
Roo Code + Flatkey 的生产运行手册
在更多开发者使用 Roo Code OpenAI compatible API 路径之前，请记录下能够支持和审查成本的运营事实。
| 运行手册字段 | 记录内容 |
|---|---|
| Roo Code 范围 | 现有本地安装、团队镜像、归档配置文件或仅用于迁移的测试。 |
| Flatkey 密钥 | 所有者、环境、轮换日期和撤销负责人。 |
| Base URL | 保存在 Roo Code 中的准确提供商 base URL 以及验证日期。 |
| 模型别名 | Roo Code 模型 ID、Flatkey 模型别名、端点系列以及原生工具调用结果。 |
| 冒烟测试 | HTTP 状态、结束原因、用量总计，以及是否出现 tool_calls。 |
| 用量审查 | 平台和财务负责人在哪里检查请求量、成本和意外的模型变更。 |
| 回滚 | 之前的提供商配置、之前的模型别名，以及谁可以恢复它。 |
内部迁移路径
如果你的团队正在 Flatkey 上标准化与 OpenAI 兼容的工具配置，请让这套设置与集成集群的其他部分保持一致。将 OpenAI-compatible API 迁移指南 作为 base URL 和回滚中心。对于另一种桌面客户端模式，请对比 Cherry Studio API 设置指南。对于开发者机器上的编码代理路由，请查看 cc-switch Claude Code 指南。
在第一个安全的 Roo Code 提示词成功运行后，请查看当前的 Flatkey 模型定价页面，然后为每个独立的用户、团队或环境边界 获取密钥。
常见问题
Roo Code 现在仍支持与 OpenAI 兼容的提供商吗？
Roo Code OpenAI Compatible provider 文档仍然描述了提供商字段：API Provider、Base URL、API Key 和 Model ID。文档首页还说明 Roo Code 扩展已于 2026 年 5 月 15 日停用，因此在新的推广前，请先验证你的安装路径。
Roo Code OpenAI compatible API provider 应该使用什么 Base URL？
请使用你账户当前的 Flatkey 提供商 base URL。本文中经过身份验证的 Flatkey 检查使用的是 https://router.flatkey.ai/v1，而公开示例可能会变化。在 Roo Code 中，只粘贴 base URL，不要粘贴完整的 chat-completions 端点。
为什么需要原生工具调用？
Roo Code 的提供商文档说明，原生工具调用是 OpenAI-compatible 提供商唯一支持的工具协议。一个只能回复普通聊天、却不能生成 OpenAI 风格工具调用的模型，对于可靠的 Roo Code 配置来说是不够的。
模型 ID 应该与 Flatkey 模型别名完全一致吗？
是的。请使用你的密钥能够调用的 Flatkey 精确别名，并通过工具调用冒烟测试进行验证。模型家族名称、提供商营销名称和网关别名可能会不同。
我可以将本指南用于新的 Roo Code 部署吗？
只有在检查当前 Roo Code 可用性之后才使用。本指南中的 Flatkey 路由检查仍然有用，但 Roo Code 的停用通知意味着新的团队级部署需要明确的产品支持决策。
结论
通过 Flatkey 进行的安全 Roo Code OpenAI compatible API 设置，应该证明的不只是一次成功的聊天响应。请确认当前 base URL，使用 Flatkey 拥有的密钥，选择精确的模型别名，测试原生工具调用，并在让 Roo Code 访问真实代码工作之前检查用量可见性。当该路径已准备好供另一位用户或环境使用时，获取密钥，并将回滚步骤与设置说明放在一起。
