> ## Documentation Index
> Fetch the complete documentation index at: https://platform.stepfun.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Roo Code

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

## 接入条件

* 已安装 VS Code 或 Cursor。运行下方修复与测试示例时，还需安装 Python 3。
* [Step Plan 订阅](https://platform.stepfun.com/step-plan)有效、额度可用，且具备所用模型的调用权限。
* 已在 [StepFun 开放平台密钥管理](https://platform.stepfun.com/interface-key)页面创建 API Key。

## 安装 Roo Code

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

## 配置 Step Plan

### 配置连接

1. 打开 Roo Code 面板，进入设置中的 `Providers`。
2. 在 `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](/docs/zh/guides/models/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](/docs/zh/guides/developer/integrations/search-mcp)。该服务通过 Step Plan 端点提供 `web_search` 和 `web_fetch`。

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

```json theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
{
  "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": []
    }
  }
}
```

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

Roo Code 的 URL 型 MCP 配置必须显式提供 `type`，此处使用 `streamable-http`，不能写成 Cline 的 `streamableHttp`。`alwaysAllow: []` 保留逐次批准。

MCP 配置以明文保存 API Key，请勿将含真实密钥的文件提交到代码仓库或分享给他人。

## 验证接入

### 验证对话

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

### 验证修复与测试

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

`calc.py`：

```python theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
def add(left, right):
    return left - right
```

`test_calc.py`：

```python theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
import unittest

from calc import add


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

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

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

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

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

### 验证配置保存

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

## 常见问题

<AccordionGroup>
  <Accordion title="Q: 发送消息后一直显示 API Request... 怎么办？">
    先检查扩展宿主日志，确认是否存在 `Could not find ripgrep binary`。VS Code 可通过命令面板中的 `Developer: Open Logs Folder` 打开日志目录，查看当前窗口的 `exthost/exthost.log`。只有出现该错误时，才按下一项处理 ripgrep；其他情况应根据实际网络、认证或请求错误排查。
  </Accordion>

  <Accordion title="Q: Roo Code 3.54.0 找不到 ripgrep 怎么办？">
    3.54.0 的路径探测未覆盖部分新版 VS Code 的 `ripgrep-universal` 目录布局。更改工作区或用户配置目录不会改变扩展查找的编辑器安装路径。

    macOS 的 VS Code 可在确认日志报错后使用以下临时兼容方案。脚本会在安装目录新增软链接，自动识别 Apple Silicon 或 Intel，且不会覆盖已有路径。源文件不存在或安装目录不可写时，应停止处理，不要提升权限强制执行。

    ```bash theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
    (
      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 和其他系统需核对各自的安装路径。编辑器更新可能移除软链接，出现相同日志时再检查。
  </Accordion>

  <Accordion title="Q: 提示 Connection error 或返回 401 怎么办？">
    检查网络连接、Base URL、API Key 与模型权限。Base URL 使用 `https://api.stepfun.com/step_plan/v1`；API Key 应完整、有效，且属于对应端点的账号。模型连接的 API Key 字段不加 `Bearer `，MCP 的 `Authorization` 请求头则需要该前缀。
  </Accordion>

  <Accordion title="Q: 回复为空、被截断或推理阶段没有正文怎么办？">
    推理阶段可能暂时没有正文。若请求结束后仍无正文，查看停止原因、错误信息与输出设置。确认 `Include max output tokens` 已关闭；若主动设置预算，过小的值可能在正文生成前被推理消耗。
  </Accordion>

  <Accordion title="Q: 模型只回复文字，或工具调用失败怎么办？">
    确认当前为 `Code` 等允许执行任务的模式，已打开目标目录，并批准了必要的操作。所选模型必须支持 OpenAI 原生工具调用；若返回工具错误，核对模型 ID 和完整错误信息，并以工具调用记录确认执行情况。
  </Accordion>

  <Accordion title="Q: MCP 中没有 step-search 或连接超时怎么办？">
    检查配置位于 `mcpServers` 下，`type` 为 `streamable-http`，`disabled` 为 `false`，请求头包含完整密钥与 `Bearer ` 前缀。保存后重新连接，并检查网络与服务日志；超时需要区分认证、网络和传输问题，不能直接归因于客户端版本。
  </Accordion>
</AccordionGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.