返回博客
Roo CodeOpenAI 兼容 APIClaudeGPTGeminiAI 编程

Roo Code 接入自定义 API：Claude、GPT 和 Gemini 怎么选

在 Roo Code 中配置 OpenAI 兼容 API、Base URL、API Key 和模型 ID，并按编程任务选择 Claude、GPT 或 Gemini。

Roo Code 接入自定义 API：Claude、GPT 和 Gemini 怎么选

Roo Code 连接自定义 API，并在 Claude、GPT 和 Gemini 之间选择

Roo Code 是运行在 VS Code 里的 AI 编程 Agent。它能读取项目、修改多个文件、运行命令，也能通过不同 Provider 使用 Claude、GPT、Gemini 和其他模型。

如果你使用的是第三方聚合服务或自建网关，最直接的入口通常不是官方 OpenAI、Anthropic 或 Google Provider，而是 OpenAI Compatible。配置本身只需要四项：Provider、Base URL、API Key 和 Model ID。真正容易出错的是模型名、接口协议以及“同一个模型能聊天，但不能稳定调用工具”的兼容性差异。

本文依据 Roo Code 官方文档在 2026 年 7 月核对，完整说明自定义 API 的配置、验证和排错，并给出 Claude、GPT 与 Gemini 的任务选择思路。

先决定使用官方 Provider 还是 OpenAI Compatible

Roo Code 为多种服务提供独立 Provider，包括 Anthropic、OpenAI、Google Gemini、OpenRouter、LiteLLM、Ollama 和 LM Studio，也提供通用的 OpenAI Compatible 入口。

选择规则很简单：

你的 API 来源Roo Code 中优先选择
OpenAI 官方 APIOpenAI
Anthropic 官方 APIAnthropic
Google AI Gemini APIGoogle Gemini
OpenRouterOpenRouter
第三方 OpenAI 兼容网关OpenAI Compatible
本地 Ollama 或 LM Studio对应的专用 Provider

专用 Provider 通常更了解上游的原生能力，例如推理参数、提示缓存或 Gemini 特有工具。OpenAI Compatible 的优势是通用：只要网关正确实现常用的 OpenAI 接口，就能用统一方式接入不同厂商的模型。

这里需要注意：模型来自 Claude 或 Gemini，不代表客户端一定要选择 Anthropic 或 Google Gemini。 如果第三方网关把这些模型暴露为 OpenAI 兼容接口，在 Roo Code 中依然应该选择 OpenAI Compatible。

自定义 API 的四个配置项

Roo Code 自定义 API 的 Provider、Base URL、API Key 和 Model ID

打开 VS Code 侧边栏中的 Roo Code，点击齿轮进入设置，然后填写：

  1. API Provider：选择 OpenAI Compatible；
  2. Base URL：填写服务商给出的 API 根地址；
  3. API Key：填写该服务商签发的密钥；
  4. Model：填写网关实际支持的模型 ID。

以 Nbility 的 OpenAI 兼容入口为例：

API Provider: OpenAI Compatible
Base URL: https://api.nbility.ai/v1
API Key: YOUR_API_KEY
Model ID: 以模型广场当前显示的 ID 为准

Base URL 为什么经常填错

Base URL 通常应停在版本根路径，例如：

https://api.example.com/v1

不要在后面重复附加：

/chat/completions

Roo Code 会根据 Provider 自己拼接请求路径。若把完整端点当成 Base URL，最终可能出现重复路径并返回 404。

但不同服务的网关设计可能不同，因此最终仍应以服务商文档为准。你可以先阅读什么是 OpenAI 兼容 API，了解 Base URL、API Key 与模型名分别负责什么。

Model ID 必须完全一致

显示名称与 API 模型 ID 不是一回事。例如控制台展示“Claude Coding”，接口实际要求的可能是另一串标识。不要根据营销名称猜模型名，也不要把空格、大小写或版本后缀擅自改掉。

最可靠的顺序是：

  1. 在服务商模型列表中复制模型 ID；
  2. 填入 Roo Code；
  3. 新建任务做最小验证；
  4. 再测试读文件、改文件和终端工具。

如何验证配置真的可用于 Agent

聊天返回一句话，只能证明认证和基础生成大致正常，不能证明 Roo Code 的 Agent 工作流完整兼容。

建议在一个临时 Git 仓库中依次执行：

  1. 让模型解释一个小文件；
  2. 让它创建一个简单测试文件；
  3. 让它运行安全的测试命令；
  4. 检查工具调用参数、文件差异和终端输出；
  5. 确认多轮任务不会突然丢失上下文。

可以使用这样的低风险提示词：

读取 package.json，总结现有 scripts，不要修改文件。

通过后再测试：

创建一个最小测试文件，运行对应测试，并在修改前说明计划。

这一步能暴露很多“普通聊天正常、Agent 操作失败”的兼容问题，例如流式事件不完整、工具调用字段格式错误、模型不支持工具或上下文长度配置不准确。

Claude、GPT 和 Gemini 应该怎么选

按任务类型选择 Claude、GPT 或 Gemini

不存在适合所有仓库和任务的唯一答案。比“哪个模型排名更高”更有用的问题是：这个任务需要什么能力，失败代价有多高？

Claude：适合长链路代码理解与谨慎修改

Claude 系列通常适合：

  • 阅读较大的代码上下文；
  • 跨文件分析和重构；
  • 先理解约束，再谨慎执行；
  • 对复杂需求给出结构化计划；
  • 需要保持代码风格和上下文一致性的任务。

它适合作为复杂实现、架构梳理和大型重构的候选主模型。但具体体验仍取决于所选版本、网关是否正确传递工具调用，以及实际上下文限制。

GPT：适合代码实现、工具链和通用任务

GPT 系列通常适合：

  • 常规功能开发和 Bug 修复；
  • 结构化输出与工具调用；
  • 终端命令、测试和迭代修改；
  • 在解释、实现和排错之间快速切换；
  • 需要推理强度控制的复杂任务（取决于模型和 Provider 支持）。

如果你希望先找一个覆盖面较广的默认模型，GPT 系列往往是容易开始的选择。Roo Code 的官方 OpenAI Provider还可能提供推理强度、输出详细度等高级选项；通过通用兼容网关时，这些扩展能力不一定全部可用。

Gemini：适合大上下文与多模态相关任务

Gemini 系列通常适合：

  • 阅读大量文档和代码；
  • 结合图片或界面截图分析问题；
  • 大上下文检索和归纳；
  • Google 技术栈相关任务；
  • 需要原生 URL Context 或搜索能力的场景（应使用支持这些能力的原生 Provider）。

如果通过 OpenAI Compatible 使用 Gemini，基础对话和工具调用可能正常，但 Google 原生 Provider中的 URL Context、Search Grounding 等专有功能不会自动等价出现。

一个实用的任务分层

任务建议起点选择理由
小范围改动、补类型、写测试快速或中档模型降低延迟和成本
常规功能开发GPT 或 Claude 的主力型号工具调用与实现能力均衡
跨模块重构、复杂排错强推理 GPT 或 Claude更需要规划和长链路一致性
超长仓库理解、截图分析Gemini 或大上下文模型上下文与多模态更重要
高风险生产修改最可靠的已验证模型正确性优先于单次价格

模型能力更新很快，所以这张表只应作为起点。真正可靠的方法是拿你自己的仓库、测试集和典型任务进行小规模对比，而不是只看公开榜单。

用 API Configuration Profiles 管理多个模型

Roo Code 的 API Configuration Profiles 可以保存多组 Provider、API Key、模型和温度设置，并快速切换。官方文档还说明，不同模式可以使用不同配置。

一个实用的配置方式是：

Profile用途模型策略
fast小改动、解释、格式处理低延迟、低成本
coding日常开发和测试稳定的主力编程模型
reasoning架构、复杂 Bug、重构更强推理模型
vision截图、设计稿和多模态支持视觉的模型

这样做比频繁覆盖一套配置更安全，也方便比较相同任务在不同模型上的表现。

不要在 Profile 名称、截图或导出文件中暴露真实 Key。导出和分享配置前，应检查是否包含认证信息。

温度应该怎么设

Roo Code 官方文档指出，温度控制随机性，而不是直接控制代码质量。多数编程任务更需要一致和可复现的结果，因此低温通常更适合代码修改。

可采用以下起点：

  • 精确修复、生成测试：0.0–0.2；
  • 常规开发和解释：0.2–0.5；
  • 方案探索和头脑风暴：0.5–0.8。

并非所有模型都支持温度。有些推理模型会忽略该参数，或要求客户端不要发送。若设置后出现 400 参数错误，先恢复 Provider 默认值。

常见错误怎么排查

Roo Code 自定义 API 的认证、地址、模型和工具调用排错面板

401：API Key 无效或发给了错误服务

检查：

  • Key 是否复制完整；
  • 是否误带引号或空格；
  • Key 与 Base URL 是否属于同一服务；
  • 账号是否有权限调用目标模型；
  • Key 是否被撤销或过期。

不要在 Issue 中粘贴真实 Key。需要共享日志时先脱敏。

404：Base URL 或端点结构错误

常见原因包括：

  • Base URL 缺少 /v1；
  • 已经填写 /chat/completions，客户端又追加一次；
  • 服务商实际使用不同版本路径；
  • 请求被发到了网页域名而不是 API 域名。

可参考AI API 的 401、404、429 与 5xx 排错指南按状态码逐层定位。

Model not found：模型 ID 不匹配

重新从服务商控制台复制模型 ID。还要确认当前 Key 有权访问该模型，因为部分网关会把“没有权限”表现为模型不存在。

能回答，但不会改文件或调用终端

这通常不是提示词问题，而是模型或网关的工具调用兼容性问题。检查：

  • 模型本身是否支持 tools；
  • 网关是否保留 tool_calls；
  • 流式响应是否包含完整参数；
  • 是否把只适合聊天的模型用于 Agent；
  • Roo Code 与 Provider 是否已更新。

上下文超限或任务越做越慢

大型 Agent 任务会持续累积文件、终端输出和模型回复。可以：

  • 把目标拆成更小的任务；
  • 减少一次读取的文件；
  • 排除构建产物和依赖目录；
  • 使用 Roo Code 的上下文压缩能力；
  • 切换到上下文更大的模型。

429、超时或 5xx

429 通常表示限流、并发或额度问题；5xx 更可能来自网关或上游。不要无上限立即重试，应使用退避并减少并发。如果多个 Provider 都已配置，可以人工切换 Profile，避免在故障期间重复消耗请求。

安全与成本控制

Roo Code 能执行命令和修改文件，因此模型选择之外，还要控制 Agent 权限：

  • 初次测试关闭高风险自动批准；
  • 在 Git 仓库中工作，随时检查 diff；
  • 不让模型读取 .env、私钥和生产凭据；
  • 为 API Key 设置合理额度与权限；
  • 大改动先要求计划，再分阶段执行；
  • 运行测试后再接受修改。

成本方面，不能只比较每百万 Token 的单价。一个模型如果频繁走错方向、重复读取文件或无法正确调用工具，实际完成任务的成本可能更高。建议记录“完成一个真实任务的总调用量、耗时和人工修正次数”。

用 Nbility 统一测试多个模型

如果你想用一个 OpenAI 兼容入口测试多个模型，可以在 Nbility 模型广场查看当前可用模型和准确 ID，然后在 Roo Code 中选择 OpenAI Compatible：

Base URL: https://api.nbility.ai/v1
API Key: YOUR_API_KEY
Model ID: 从模型广场复制

建议分别创建 fast、coding 和 reasoning Profile，而不是每次覆盖同一配置。开始前先用小仓库验证工具调用、流式输出和上下文稳定性，再用于重要项目。

FAQ

Roo Code 可以使用任何 OpenAI 兼容 API 吗？

可以尝试，但“兼容 OpenAI”不等于完整兼容 Agent。至少要验证认证、流式输出、工具调用、错误格式和上下文限制。

使用 Claude 模型时一定要选 Anthropic Provider 吗？

不一定。直接调用 Anthropic 官方 API 时选 Anthropic；如果第三方网关通过 OpenAI 兼容协议提供 Claude，则选 OpenAI Compatible。

Claude、GPT 和 Gemini 哪个最适合写代码？

没有脱离任务和具体版本的统一答案。日常开发可从稳定的 GPT 或 Claude 主力型号开始；大上下文或多模态任务可优先测试 Gemini；复杂重构应使用已在自己仓库中验证过的强模型。

为什么普通聊天正常，Roo Code 仍然失败？

Agent 还依赖工具调用、流式事件、多轮上下文和结构化参数。网关只兼容简单聊天接口时，就可能出现这种现象。

可以为不同 Roo Code 模式设置不同模型吗？

可以。API Configuration Profiles 支持保存不同 Provider、模型、Key 和参数，官方文档也支持为不同模式选择不同配置。

总结

Roo Code 接入自定义 API 的关键不是填完四个字段，而是完成一条可靠的 Agent 链路：

  1. 选择正确 Provider；
  2. 核对 Base URL、API Key 和 Model ID；
  3. 从只读任务逐步验证到文件修改和终端工具；
  4. 按任务创建多个配置 Profile；
  5. 用自己的仓库评估 Claude、GPT 与 Gemini；
  6. 对权限、成本和错误重试设置边界。

如果你还没理解兼容 API 的路径与模型名，可以先阅读OpenAI 兼容 API 入门；准备比较多个终端 Agent 时，也可以参考 OpenCode 第三方 API 配置教程。

参考资料

相关文章

用 Nbility 跑通你的 Agent 工作流

获取 API Key，统一接入 OpenAI 兼容模型和开发工具。

管理 API Key