Roo Code

Roo Code 是运行在 VS Code、Cursor 等编辑器中的编码 Agent，支持文件编辑、终端命令执行和多步工具调用。通过 OpenAI Compatible Provider，可使用 Chat Completions API 接入 Step Plan。

接入条件

已安装 VS Code 或 Cursor。运行下方修复与测试示例时，还需安装 Python 3。
Step Plan 订阅有效、额度可用，且具备所用模型的调用权限。
已在 StepFun 开放平台密钥管理页面创建 API Key。

安装 Roo Code

在编辑器扩展市场中搜索 Roo Code，确认扩展标识为 RooVeterinaryInc.roo-cline。配置适用于 Roo Code 3.54.0；上游仓库已归档，使用时需确认与当前编辑器的兼容性。

配置 Step Plan

配置连接

打开 Roo Code 面板，进入设置中的 Providers。
在 API Provider 中选择 OpenAI Compatible，填写以下参数：

配置项	填写值
`API Provider`	`OpenAI Compatible`
`Base URL`	`https://api.stepfun.com/step_plan/v1`
`API Key`	Step API Key，不包含 `Bearer` 前缀或首尾空格。
`Model ID`	`step-5-preview`

Roo Code 自动追加 /chat/completions，完整请求路径为 /step_plan/v1/chat/completions。Base URL 保留到 /step_plan/v1，不要替换为普通按量 API 地址。 Roo Code 3.54.0 仅支持 OpenAI 原生工具调用，没有 XML 回退。所选模型需要支持函数调用，以下使用 Step 5 Preview。

确认模型参数

展开 Model Configuration，按 Step 5 Preview 的能力核对设置：

配置项	设置	说明
`Enable streaming`	开启	使用流式输出。
`Context Window Size`	`1000000`	客户端使用的上下文窗口。
`Include max output tokens`	`Off`	不在请求中额外发送输出上限。
`Max Output Tokens`	`-1`	配合上一项关闭使用，由服务端处理输出长度。
`Image Support`	开启	允许图像输入。

3.54.0 开启 Include max output tokens 时会发送 max_completion_tokens。本配置关闭该选项；不要只修改 Max Output Tokens 而遗漏开关。若需要主动限制输出，应为推理和正文保留足够预算。切换到其他模型时，按其规格调整上下文与输入能力。保存配置后新建任务。

接入 StepSearch MCP

需要联网搜索或获取网页内容时，可配置 StepSearch。该服务通过 Step Plan 端点提供 web_search 和 web_fetch。

在 Roo Code 面板打开 MCP Servers，选择编辑全局 MCP 配置。
合并以下内容，保留已有的其他服务，将 YOUR_STEP_API_KEY 替换为实际密钥：

{
  "mcpServers": {
    "step-search": {
      "type": "streamable-http",
      "url": "https://api.stepfun.com/step_plan/v1/mcp/web_search/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_STEP_API_KEY"
      },
      "disabled": false,
      "alwaysAllow": []
    }
  }
}

保存后重新连接服务，确认 step-search 已连接，且工具列表包含 web_search 和 web_fetch。
新建任务，调用其中一个工具完成搜索或网页抓取，按提示批准调用，并检查返回结果。

Roo Code 的 URL 型 MCP 配置必须显式提供 type，此处使用 streamable-http，不能写成 Cline 的 streamableHttp。alwaysAllow: [] 保留逐次批准。 MCP 配置以明文保存 API Key，请勿将含真实密钥的文件提交到代码仓库或分享给他人。

验证接入

验证对话

新建任务并输入 请只回复 OK。，预期返回 OK。

验证修复与测试

创建独立测试目录，添加以下两个文件。其中 calc.py 故意包含加法错误。

calc.py：

def add(left, right):
    return left - right

test_calc.py：

import unittest

from calc import add


class TestAdd(unittest.TestCase):
    def test_add(self):
        self.assertEqual(add(2, 3), 5)

在编辑器中打开该目录，选择允许修改文件的 Code 模式，向 Roo Code 发送：

只在当前目录工作。读取 calc.py 和 test_calc.py，修复导致 test_add 失败的错误。
运行 python3 -m unittest test_calc -v；如果失败，继续修复并重新测试。
不要修改 test_calc.py 或其他文件。最后报告修改内容、执行命令和测试结果。

按提示批准必要的文件与命令操作。确认 calc.py 中的加法已修复，测试输出为 OK，且 test_calc.py 未被修改。

手动批准即可完成验证，无需开启全部自动批准选项。

验证配置保存

重启编辑器，检查 Provider 与模型选择是否保留，并重新发起一次简短对话。

常见问题

Q: 发送消息后一直显示 API Request... 怎么办？

先检查扩展宿主日志，确认是否存在 Could not find ripgrep binary。VS Code 可通过命令面板中的 Developer: Open Logs Folder 打开日志目录，查看当前窗口的 exthost/exthost.log。只有出现该错误时，才按下一项处理 ripgrep；其他情况应根据实际网络、认证或请求错误排查。

Q: Roo Code 3.54.0 找不到 ripgrep 怎么办？

3.54.0 的路径探测未覆盖部分新版 VS Code 的 ripgrep-universal 目录布局。更改工作区或用户配置目录不会改变扩展查找的编辑器安装路径。macOS 的 VS Code 可在确认日志报错后使用以下临时兼容方案。脚本会在安装目录新增软链接，自动识别 Apple Silicon 或 Intel，且不会覆盖已有路径。源文件不存在或安装目录不可写时，应停止处理，不要提升权限强制执行。

(
  set -eu
  APP="/Applications/Visual Studio Code.app/Contents/Resources/app"
  case "$(uname -m)" in
    arm64) ARCH="darwin-arm64" ;;
    x86_64) ARCH="darwin-x64" ;;
    *) printf '%s\n' 'Unsupported architecture'; exit 1 ;;
  esac
  RG="$APP/node_modules.asar.unpacked/@vscode/ripgrep-universal/bin/$ARCH/rg"
  TARGET="$APP/node_modules/@vscode/ripgrep/bin/rg"
  if [ ! -x "$RG" ]; then
    printf '%s\n' 'Bundled ripgrep was not found at the expected path.'
    exit 1
  fi
  if [ -e "$TARGET" ] || [ -L "$TARGET" ]; then
    printf '%s\n' 'The target already exists; no changes were made.'
    exit 1
  fi
  mkdir -p "$(dirname "$TARGET")"
  ln -s "$RG" "$TARGET"
  "$TARGET" --version
)

完成后运行 Developer: Reload Window，重新发起任务。该命令只适用于上述 macOS VS Code 安装位置；Cursor 和其他系统需核对各自的安装路径。编辑器更新可能移除软链接，出现相同日志时再检查。

Q: 提示 Connection error 或返回 401 怎么办？

检查网络连接、Base URL、API Key 与模型权限。Base URL 使用 https://api.stepfun.com/step_plan/v1；API Key 应完整、有效，且属于对应端点的账号。模型连接的 API Key 字段不加 Bearer ，MCP 的 Authorization 请求头则需要该前缀。

Q: 回复为空、被截断或推理阶段没有正文怎么办？

推理阶段可能暂时没有正文。若请求结束后仍无正文，查看停止原因、错误信息与输出设置。确认 Include max output tokens 已关闭；若主动设置预算，过小的值可能在正文生成前被推理消耗。

Q: 模型只回复文字，或工具调用失败怎么办？

确认当前为 Code 等允许执行任务的模式，已打开目标目录，并批准了必要的操作。所选模型必须支持 OpenAI 原生工具调用；若返回工具错误，核对模型 ID 和完整错误信息，并以工具调用记录确认执行情况。

Q: MCP 中没有 step-search 或连接超时怎么办？

检查配置位于 mcpServers 下，type 为 streamable-http，disabled 为 false，请求头包含完整密钥与 Bearer 前缀。保存后重新连接，并检查网络与服务日志；超时需要区分认证、网络和传输问题，不能直接归因于客户端版本。

工具接入

迁移

文本与推理

请求与上下文

Agent 与工具

文件与知识

视觉理解

语音

开发工具

示例与 Cookbook

错误与排障

接入条件

安装 Roo Code

配置 Step Plan

配置连接

确认模型参数

接入 StepSearch MCP

验证接入

验证对话

验证修复与测试

验证配置保存

常见问题

​接入条件

​安装 Roo Code

​配置 Step Plan

​配置连接

​确认模型参数

​接入 StepSearch MCP

​验证接入

​验证对话

​验证修复与测试

​验证配置保存

​常见问题

接入条件

安装 Roo Code

配置 Step Plan

配置连接

确认模型参数

接入 StepSearch MCP

验证接入

验证对话

验证修复与测试

验证配置保存

常见问题