X-AIO_FrameX-AIO
AI 编程工具

Roo Code（VS Code，存量兼容教程）

面向小白的 Roo Code 3.54.0 安装、X-AIO OpenAI 兼容配置和首次任务指南。

先看：Roo Code 已停止维护

Roo Code 官方已在 2026 年 5 月 15 日停止维护并归档扩展。VS Code 市场页可能仍显示“安装”，但不再承诺修复、安全更新或长期可用性。本页只帮助已经需要使用旧版 Roo Code 的用户完成一次兼容配置；新用户请优先考虑 ZooCode 或 Cline。不要把未维护的扩展直接用于生产仓库或包含机密的项目。

本教程按 macOS 上的实际操作整理，实测扩展版本为 Roo Code 3.54.0。Windows 和 Linux 的按钮名称基本相同，快捷键把 Cmd 换成 Ctrl 即可。

你需要准备什么

  • VS Code 1.84 或更高版本。Roo Code 3.54.0 的扩展要求就是这个最低版本。
  • 一个可以打开的练习文件夹。第一次不要直接打开重要项目，避免误改文件。
  • 已登录的 X-AIO API 密钥管理 页面。
  • 一个可用的 X-AIO Tokens Plan 额度。

Roo Code 是 VS Code 里的智能体：它可以读取工作区、提出文件修改、运行命令，并在你批准后执行。它不是 VS Code 自带功能，也不是一个模型；必须先连接模型供应商。

可选：先确认账号和额度可用

如果你不确定账号是否已经获得额度，可以先在 X-AIO 左侧打开 一键使用AI → AI 对话，选择一个当前可用的模型，发送一句简单消息。能正常收到回复，说明账号、模型和额度可用；如果这里已经提示余额不足，请前往 Tokens Plan 的订阅总览检查并处理额度问题，再配置 Roo Code。

下图是 2026 年 8 月 26 日使用 Kimi-K2.7-Code 的实测结果。这里成功只代表 X-AIO 平台对话正常，Roo Code 仍需完成后面的独立验证。

X-AIO AI 对话返回“API 连接正常”，用于确认账号和额度可用

1. 安装 VS Code 和 Roo Code

安装 VS Code

从 Visual Studio Code 官网下载与你的系统匹配的版本并安装。打开 VS Code 后，先用 文件 → 打开文件夹 打开一个空练习文件夹；如果出现“是否信任此文件夹”，第一次可以选择信任你刚创建的练习目录。

从扩展市场安装

  1. 点击左侧活动栏的扩展图标，或按 macOS Cmd+Shift+X（Windows/Linux Ctrl+Shift+X）。
  2. 搜索 Roo Code。
  3. 核对发布者是 RooVeterinaryInc / Roo Code，再点击“安装”。不要安装名称相似但发布者不同的扩展。
  4. 安装完成后，左侧活动栏会出现 Roo Code 图标；如果 VS Code 要求重新加载，请接受。

VS Code 市场中的 Roo Code 安装页，发布者为 Roo Code

本机安装页会显示扩展标识符 rooveterinaryinc.roo-cline 和版本 3.54.0。看到“禁用/卸载”按钮才表示安装已经完成。

VS Code 扩展详情页中的 Roo Code 版本和安装状态

安装后 Roo Code 的禁用和卸载按钮

如果市场安装按钮失效，可以从 Roo Code GitHub Releases 下载官方 .vsix，再在扩展页的“...”菜单选择“从 VSIX 安装”。这只是旧版的备用安装方式，不能改变项目已经停止维护的事实。

第一次打开 Roo Code

点击活动栏的 Roo Code 图标，会看到 Welcome to Roo Code!。这里不需要注册 Roo Code 账户；点击 Get Started 进入供应商配置。Import Settings 只适合已有 Roo 配置的用户，导入文件可能包含 API Key，陌生文件不要导入。

Roo Code 首次欢迎页，点击 Get Started 进入配置

2. 在 X-AIO 创建一个专用 API Key

API Key 等同于访问凭据。为教程或测试单独创建一个短期密钥，后续可以单独撤销，不要复用生产密钥。

  1. 打开 X-AIO API 密钥管理，确认左上角工作空间是你要使用的 个人标准API。
  2. 先记下页面里的 OpenAI 生态端点：https://llm-api.x-aio.com/v1。这是 Roo 的 Base URL，不要填完整的 /chat/completions 路径。
  3. 点击 创建新密钥。
  4. 在“密钥用途”填写容易识别的名称，例如 Roo Code 小白教程。
  5. 选择 90天，确认页面显示的到期日期，再点击 创建密钥。
  6. 回到密钥列表，找到刚才的用途名称，点击该行的 复制 API 密钥。不要复制列表中类似 sk-xxxx...xxxx 的遮罩文本。

X-AIO 创建 API 密钥对话框，填写用途并选择有效期

X-AIO API 密钥页面显示当前 OpenAI 兼容端点

密钥安全

完整 Key 只应留在密码管理器或 VS Code 的安全存储中。不要把它写进 Markdown、截图、终端历史、settings.json、Git 仓库或聊天记录。若怀疑泄露，马上在同一行删除旧 Key，再创建一个新的有限期 Key。

3. 在 Roo Code 选择 OpenAI Compatible

首次向导默认可能是 OpenRouter，这不是 X-AIO 配置。按下面路径切换：

  1. 在 Roo Code 欢迎页点击 Get Started。

  2. 打开 API 提供商 下拉框，在搜索框输入 OpenAI Compatible，选择同名选项。

  3. 在 基础 URL / Base URL 中填写：

    https://llm-api.x-aio.com/v1

  4. 在 API 密钥 / API Key 输入框粘贴刚才复制的完整 Key。输入框会以圆点隐藏内容；Roo Code 会把它保存到 VS Code 的 Secret Storage，而不是普通文本配置。

  5. 等待模型下拉框加载。优先从实时列表中选择一个支持 OpenAI 原生 tool calling 的模型，不要照抄网上已经过期的模型 ID。列表为空时，先检查 Base URL 和 Key；只有供应商明确给出 ID 时才使用“自定义模型”。

Roo Code 供应商向导，默认显示 OpenRouter

完成向导后检查详细设置

点击向导底部的 完成，再点击 Roo Code 面板右上角的 Settings。如果创建了配置文件，建议命名为 X-AIO，方便以后切换。

在 OpenAI Compatible 配置中按模型能力设置：

设置建议什么时候调整
Enable streaming保持开启只有供应商明确不支持流式时才关闭
Include max output tokens保持开启遇到供应商拒绝该参数时再关闭
R1 / reasoning format默认关闭只有推理模型明确要求时才开启
Image Support按所选模型能力核对；界面默认可能开启非视觉模型请关闭，只有视觉模型才开启
Max Tokens、Context Window优先使用模型列表自动带出的值手工配置时只填供应商公布的值；Max Tokens 为 -1 表示由服务器决定
Computer Use、Prompt Caching、价格默认关闭/留空仅在模型和供应商明确支持时配置

先点击 Save，确认没有错误提示，再点击 Done/返回 离开设置。只填字段但没有保存，离开页面后配置可能不会生效。

4. 用最小任务验证连接

先在空练习文件夹验证，成功后再进入真实项目。

先做只读检查

  1. 点击 Roo Code 图标，点击 New Task。

  2. 从模式下拉框选择 Ask 或 Architect。它们更适合先了解工作区，不会马上大范围改文件。

  3. 输入：

    请检查当前工作区是否为空，只告诉我你看到的文件和下一步建议，不要创建、修改或删除任何文件，也不要运行命令。

  4. 看到 Roo 返回文字，说明 Key、Base URL 和模型至少已经完成一次请求。

再做一个可撤销的写入测试

确认只打开练习目录后，切换到 Code 模式，输入：

请在当前工作区创建 hello.txt，只写入一行：Roo Code 配置成功。
不要运行命令。每一步先展示要执行的操作，等我批准后再继续。

Roo 可能会提出读取、写入或运行命令请求。逐项查看路径、内容和命令：

  • 路径不对、内容不清楚或命令有副作用时，点 Reject。
  • 确认无误后只批准当前这一项，不要一次性打开所有自动批准权限。
  • 最后在 VS Code 资源管理器中确认 hello.txt 存在且内容只有一行。

这一步完成后才算“配置成功”：Roo 有回复、文件出现在正确的工作区、内容与要求一致。

5. 常见问题

现象处理方法
401、Invalid API Key重新从目标行点击“复制 API 密钥”，不要复制遮罩值；确认 Key 未过期且工作空间正确。
404 或 endpoint not foundBase URL 只填 https://llm-api.x-aio.com/v1，不要重复写 /v1/v1，也不要填 /chat/completions。
模型列表为空等待几秒后重试；检查网络、Base URL 和 Key；必要时使用供应商明确提供的自定义 Model ID。
Model not found从实时下拉列表重新选择，不要使用旧教程中的固定模型名。
工具调用失败、无法创建文件Roo Code 只支持 OpenAI 原生 tool calling；换用明确支持工具调用的模型。
请求超时或没有回复先用更小的只读请求测试，检查网络和额度；再查看 View → Output → Roo Code 日志。
找不到 Roo 图标重启 VS Code，确认扩展处于启用状态；检查扩展页的发布者和版本。
无法修改工作区检查是否打开了正确文件夹并完成“信任此文件夹”；先用 Ask 模式确认路径。

6. 从 Roo Code 迁移

由于 Roo Code 已归档，新用户不建议围绕它建立长期流程。已有配置可以迁移到社区维护的 ZooCode：在 Roo Code 设置中 Export，再在 ZooCode 中 Import Settings。导出的文件可能包含 API Key，迁移完成后应立即删除临时文件，并在公开环境中重新检查凭据。

官方状态说明：

使用 CC Switch 配置 Codex

以 macOS 为例安装 Node.js、Codex 和 CC Switch，并通过 X-AIO 一键导入和验证供应商配置。

Cline（VS Code）

面向小白的 Cline 安装、X-AIO API Key 创建、模型选择和首次对话教程。

On this page

你需要准备什么可选：先确认账号和额度可用1. 安装 VS Code 和 Roo Code安装 VS Code从扩展市场安装第一次打开 Roo Code2. 在 X-AIO 创建一个专用 API Key3. 在 Roo Code 选择 OpenAI Compatible完成向导后检查详细设置4. 用最小任务验证连接先做只读检查再做一个可撤销的写入测试5. 常见问题6. 从 Roo Code 迁移