文档

文档

Roo Code

Roo Code 的 OpenAI Compatible 提供商需要填写三个字段,另有一个模型能力配置块。该能力配置块并非可有可无的装饰项——Roo Code 会据此计算上下文预算。

选择 OpenAI Compatible 提供商,粘贴基础 URL 和密钥,并设置模型的上下文窗口与最大输出,使 Roo Code 的预算计算准确。

Roo Code 设置面板
API Provider   OpenAI Compatible
Base URL       https://api.kunavo.com/v1
API Key        sk-kn-...
Model          claude-sonnet-5

Model Configuration
  Context Window     200000
  Max Output Tokens  64000
  Image Support      on
Roo Code 使用原生工具调用,且没有回退机制,因此你选择的模型必须支持 OpenAI 兼容工具调用。下表中的所有模型 id 都支持这一功能;如果在此处配置纯文本或媒体模型,问题不会在设置阶段出现,而会在智能体首次尝试使用工具时出现。
请填写 Context Window 和 Max Output Tokens,不要保留默认值。Roo Code 会根据这两个数值判断何时压缩对话,因此上下文窗口设得过低,会导致它不必要地截断历史记录;设得过高则会引发上游 400 错误,而不是正常压缩对话。
还没有密钥?创建 Kunavo 账户,创建一个密钥(以 sk-kn- 开头),并充值 $10 起——调用费用从该余额中扣除,失败的调用不会收费。随后,控制台会打开 Roo Code 设置页面。

分步操作

  1. 在 /app/keys 创建密钥并复制——它只会显示一次。
  2. 打开 Roo Code 设置面板,将 API Provider 设为 OpenAI Compatible。
  3. 输入 Base URL https://api.kunavo.com/v1 和你的密钥。Base URL 中必须包含 /v1 后缀——Roo Code 只会追加路由。
  4. 选择或输入模型 id,然后打开 Model Configuration,并根据下表设置上下文窗口、最大输出量、图像支持以及输入/输出价格。

    Roo Code 的提供商页面将该模型配置区块列为 Max Output Tokens、Context Window、Image Support、Computer Use、Input Price 和 Output Price,并说明 Base URL“不会是 https://api.openai.com/v1”,即 OpenAI 官方 API 的地址(Roo Code 文档,最后更新于 2026 年 5 月 15 日;阅读于 2026 年 10 月 25 日)。

  5. 在 Code 模式下发送一条消息。Roo Code 自身的每任务成本显示会使用你在此处输入的价格,因此请务必准确填写。

已于 2026年9月6日对照 Roo Code 的 OpenAI Compatible 提供商页面检查。第三方设置会发生变化;如果这里的字段名称不再与你看到的内容一致,应以该页面为准,而不是本页。

这是简要版本。完整教程——包括模型选择、真实会话成本和失败模式——见 Roo Code + Claude 操作指南。

调试客户端前先验证

一个请求即可确定故障来自端点、密钥还是配置文件。如果返回 JSON,则相同的基础 URL 和密钥可以在 Roo Code 中使用。

# Settles whether a failure is the endpoint, the key, or the client.
curl -sS https://api.kunavo.com/v1/models \
  -H "Authorization: Bearer sk-kn-..."

字段中应填写哪个模型 ID

每个文本模型都可通过模型 ID 访问——实时列表见 GET /v1/models,包含价格的目录见模型页面。费率单位为每 1M token 的美元,格式为输入 / 输出。

模型 IDKunavo 输入 / 输出它在 Roo Code 中的位置
claude-sonnet-5$1.40 / $7.00Code 模式——默认模式,也是成本显示所依据的模式
claude-opus-5$3.50 / $17.50Architect 模式,制定错误计划时的代价高于 token 成本
claude-haiku-4-5$0.70 / $3.50Ask 模式和重复读取文件
gpt-5-6-terra$0.70 / $4.20对大型代码库进行长上下文处理
计费方式是从预付余额中按 token 扣费,无月费——参见 计费。对于重复上下文——这正是编辑器或聊天客户端发送内容的大部分——提示缓存对账单的影响大于模型选择。

常见问题

如何让 Roo Code 指向自定义的 OpenAI 兼容端点?

在 Roo Code 设置面板中,将 API Provider 设为 "OpenAI Compatible",然后填写该端点的 Base URL 和 API Key,并选择一个模型。基础 URL 应为服务的 /v1 根路径,因为 Roo Code 只会在其后追加路由。Roo Code 自己的文档称 Base URL 字段至关重要——每个请求的去向都由该字段决定。

通过自定义端点,哪些模型可以与 Roo Code 配合使用?

端点提供且支持 OpenAI 兼容原生工具调用的任何模型。Roo Code 只使用原生工具调用,没有回退模式,因此不支持工具调用的模型虽然能够连接,但智能体一旦尝试读取或写入文件就会失败。Claude 和 GPT 文本模型都符合要求;图像、视频和音频模型则不符合。

Roo Code 的 Context Window 和 Max Output Tokens 应该填多少?

填写所选模型的实际限制,而不是默认值。Roo Code 会根据这两个数值判断何时压缩对话,因此,数值低于模型的实际上下文限制会导致它不必要地丢弃历史记录;数值高于实际限制则会引发上游 400 错误,而不是正常压缩对话。各模型的具体数值可在端点的模型目录中查看。

为什么 Roo Code 显示的任务成本不正确?

因为 Model Configuration 中的 Input Price 和 Output Price 需要手动填写,默认值为零或其他提供商的费率。Roo Code 完全根据这两个字段计算每项任务的成本显示;它不会从端点读取价格,因此显示的数字是否准确完全取决于输入的内容。请从提供商自己的目录中复制费率。