Roo Code：本地编程智能体，运行于 编辑器

#这是什么

在代码补全和自主智能体之间，还存在一个中间类别：编辑器中的智能体。代码补全会在您输入时预测下一行，而自主智能体则在容器中独立工作，无需持续监督。编辑器中的智能体能看到您打开的项目，理解文件目录结构及其依赖关系，提出修改，并在您确认后才将修改写入磁盘；它还会在您的终端中执行命令，每次都需要您的明确同意。Roo Code 属于这一类，与 Cline 等项目的理念在很大程度上相通。

与对话助手相比，它的优势是无需再复制粘贴：修改会以差异（diff）的形式出现在相关文件中。与自主智能体相比，它的优势是您在每一步都参与其中，而模型越小，这一点就越重要。该项目采用 Apache 2.0 许可证，自 2024 年底推出以来，GitHub 星标数已超过 20,000；在竞争日益激烈的这一类别中，这体现了用户采用它的速度之快——不过，这些都是在下文详述的停止运营公告发布之前的情况。

#该扩展自 2026 年 5 月起已停止运营：这意味着什么

这是本指南最重要的信息，也是许多仍在线的教程未提及的信息。创始人 Matt Rubens 于2026年4月21日宣布停止 Roo Code 项目：最后一次发布于2026年5月15日，GitHub 仓库随后归档——锁定为只读，不再提供任何修复，包括安全修复。直接核查仓库即可确认：状态为已归档，最后一次提交日期为2026年5月15日。团队已全部转向 Roomote，这是一个通过 Slack 操控的云端智能体；团队认为，代码编辑器已不再是与 AI 智能体协作的未来方向。

#不同模式，以及为什么这样的设计是个好主意

Roo Code 的独特之处在于区分不同角色。默认内置五种模式：Code，用于编写和修改，并可使用全部工具；Ask，是一个技术助手，会详细回答问题，但不改动任何内容（仅限读取和 MCP）；Architect，是一个规划者，其写入权限仅限于 Markdown 文件，旨在先设计再行动；Debug，侧重系统性诊断，拥有完整访问权限；Orchestrator，也称为“Boomerang Mode”，会拆解复杂任务并将其委派给其他模式。还可以定义其他模式，为它们设置各自的指令和权限。

对于本地模型，这不只是使用起来更方便。没有写入权限的 Ask 模式，可以消除模型太小却因过于积极而修改文件的这类事故。按模式限制权限，是让小模型能够安全使用的主要手段；这也恰好最能体现 Roo Code 对智能体通用安全实践的遵循：每个角色只获得所需的权限，绝不多给。

#连接本地模型

1. 01
   提供模型服务

   Ollama 或任何兼容 OpenAI 的接口。对于个人使用，Ollama 已足够。
2. 02
   在扩展中选择 Ollama 作为模型服务提供方

   输入模型的名称或标签。默认基础地址为 http://localhost:11434；仅在 Ollama 服务器要求时才需要 API 密钥。
3. 03
   在正确的位置设置上下文窗口

   这是记录最充分的陷阱：默认情况下，Roo Code 会采用 Ollama 模型的 Modelfile 中定义的 num_ctx 设置，而不是扩展自身的数值。因此，要增大上下文窗口，应在 Ollama 端操作（通过 Modelfile 或环境变量），而不是在 Roo Code 的设置中调整。
4. 04
   从 Ask 模式开始

   在允许任何修改之前，使用仅有读取权限的模式，提出三个关于项目的问题，就能如实衡量模型究竟理解了多少代码。

#究竟使用哪个模型

在这项任务中，中等规模的代码专用模型几乎总能胜过规模更大的通用模型，因为它在训练中接触了更多严格格式和代码差异（diff），而非一般 prose 文本。差距主要体现在能否生成一次就能成功应用、没有上下文或行号错误的 diff——在实践中，这个技术细节比模型回答的整体质量更重要。

• Cline：另一款编辑智能体的对比介绍
• Aider：同样的思路，在终端中实现
• 让本地模型审查自己的代码

#Orchestrator：将复杂任务拆解

Orchestrator 模式在官方文档中也称为 Boomerang Mode，它改变了处理无法一次完成的庞大任务的方式。与其直接要求“为我的应用添加身份验证”，您可以向 Orchestrator 描述目标，由它将目标拆分为子任务，再交给专门的模式处理：Architect 负责制定计划，Code 负责实现，若过程中有测试失败，则由 Debug 介入。

1. 01
   描述目标，而非步骤

   向 Orchestrator 说明预期结果，而不是列出需要修改的文件；这种任务拆分正是该模式应该完成的工作。
2. 02
   让每个子任务完成后再进行下一个

   该模式会等待一次委派任务的结果返回后，再启动下一次委派，从而自然地留出停顿，让您检查刚完成的工作。
3. 03
   每一步都需关注当前激活模式

   界面会显示当前正在使用哪种模式；如果本应保持只读的任务意外切换到 Code 模式，这是最需要优先留意的信号。

使用本地模型时，这种拆分会带来直接且可测量的开销：每个委派出去的子任务都是一次新的模型调用，也就意味着一次新的完整生成过程，并且每次都需要花时间加载各自的上下文。对于真正由多个部分组成、涉及多个文件和多个不同关注点的任务，Orchestrator 值得使用；对于简单修改，它只会增加往返调用，却没有实际收益，而直接使用 Code 模式仍能明显更快地达到完全相同的最终结果。

#正确使用

范围明确的小任务

“添加这个参数，并将其传递到调用它的三个函数中”，而不是“改进这个模块”。要求越具体，模型按自己的方式解读的空间就越小，而大多数令人失望的代码改动恰恰来自这种解读空间。

干净的代码仓库

在专用分支上使用干净的工作树，可以让每份 diff 都一目了然，并通过一次撤销提交来撤销每个错误，无需从您自己尚在进行的修改中分离出智能体的改动。

逐一审查每份 diff

本地模型经常会生成看似合理的修改：这些修改能够编译通过，也能通过快速审阅，却仍然没有实现您真正想要的效果。编译通过并不能证明代码正确，只能说明不存在语法错误。

需警惕外部内容

工单、依赖项的文档文件或代码中已有的注释，都可能包含面向 AI 智能体而非您的指令——请参阅下文的安全部分，了解这在实际使用中意味着什么。

#故障排除：最常见的障碍

使用本地模型时遇到的大多数问题，都源于三种容易识别和区分的原因。在质疑模型本身的质量之前，应先逐一检查这些原因。

在三种情况下，首先应思考的问题并非‘选择哪个更好的模型’，而是‘该模型在回答时实际接收到了什么样的上下文和权限’。上下文被截断所产生的可见症状，与模型容量不足完全相同，但一旦确定真实原因，其诊断成本和解决方案却大不相同。

#读取您项目的智能体所特有的风险

编辑代理本质上会查看您未亲自撰写的內容：第三方依赖的README文件、对话中粘贴的工单、或其他地方克隆进来的仓库中已存在的评论。这些内容中的某一项可能包含针对模型的指令，而非针对您——这正是提示注入（prompt injection）的原理，详见下方专门指南。配备终端和写入权限的代理，比不具备工具功能的纯聊天机器人，更易成为此类攻击的目标。

正是在这里，Roo Code 的模式不再只是方便组织工作，而成为切实的安全措施。仅限读取的 Ask 模式，即使读到了工单中隐藏的指令，即使底层模型受到了该指令的影响，也根本无法执行它。这种保护并非来自更智能、能够识别陷阱的模型，而是来自权限范围的限制，使执行该指令在技术上成为不可能，无论模型决定做什么。

• 提示注入：本地部署并不能保护你
• 来源：Roo Code模式官方文档
• 来源：Ollama 提供商的官方配置说明
• 来源：Roo Code 官方 GitHub 仓库，状态已归档
• 来源：Roo Code停服及替代方案报道（专业媒体）

#FAQ