Roo Code 本地模型实战指南：使用 Ollama 与 LM Studio 搭建离线 AI 编程环境-港品优选

Roo Code 本地模型实战指南：使用 Ollama 与 LM Studio 搭建离线 AI 编程环境

【免费下载链接】Roo-CodeRoo Code gives you a whole dev team of AI agents in your code editor.项目地址: https://gitcode.com/GitHub_Trending/ro/Roo-Code

导读

本指南基于 Roo Code 官方文档 local-models.md 整理而成，并融合仓库中 ollama.md、lmstudio.md 两份提供方文档及底层源码实现。你将掌握如何在本地机器上通过 Ollama 与 LM Studio 运行语言模型，实现完全离线、保护隐私且零 API 费用的 AI 编程辅助，学会上下文窗口（num_ctx）的配置原理、Provider 选择、Base URL 设定以及常见故障的排查方法。

为什么选择本地模型？

Roo Code 支持在本地机器上使用 Ollama 与 LM Studio 运行语言模型，相比云端 API 具有以下优势：

隐私安全（Privacy）：你的代码和数据永远不会离开你的电脑。
离线可用（Offline Access）：即使没有互联网连接也能正常使用 Roo Code。
成本节省（Cost Savings）：避免云端模型按量计费的 API 费用。
高度可定制（Customization）：可以自由尝试不同的模型和配置组合。

但本地模型同样存在明显局限：

资源要求高：本地模型对硬件要求较高，需要性能强劲的 CPU，理想情况下还需要独立 GPU。
配置复杂度高：相比开箱即用的云端 API，本地模型的搭建和调优更复杂。
模型能力参差：部分本地模型表现优秀，但整体上仍难以媲美最前沿的超大规模云端模型。
高级特性缺失：本地模型（以及许多在线模型）通常不支持 prompt caching、computer use 等高级能力。

从源码角度佐证：Roo Code 在 src/api/providers/native-ollama.ts 与 src/api/providers/lm-studio.ts 中分别为两个提供方实现了独立的流式请求处理、工具调用与 token 统计逻辑，说明本地模型走的是完整的官方原生协议链路，而非简单的网关转发。

受支持的本地模型提供方

Roo Code 目前支持两个主流本地模型提供方：

提供方	定位	特点
Ollama	开源命令行工具	支持大量模型，通过 CLI 提供更强的控制力，底层走 Ollama 原生 API
LM Studio	图形化桌面应用	简化模型的下载、配置与运行，内置模拟 OpenAI API 的本地推理服务器

两者能力相近，差异主要体现在交互方式：Ollama 偏命令行控制，LM Studio 提供更友好的图形界面。

在类型定义层面，Roo Code 通过 provider-settings.ts 中的localProviders = ["ollama", "lmstudio"]将两者归为LocalProvider，与动态云端提供方（DynamicProvider）并列，统一纳入 Provider 路由体系。

使用 Ollama 搭建本地模型

Ollama 是运行本地大模型的流行开源工具，Roo Code 通过其原生 API进行对接。

第一步：安装并启动 Ollama

从 Ollama 官网下载对应操作系统的安装包并完成安装，然后确保服务处于运行状态：

ollama serve

第二步：拉取模型

从 Ollama 模型库浏览可用模型，使用ollama pull下载：

ollama pull <model_name>

例如拉取一个 32B 的代码模型：

ollama pull qwen2.5-coder:32b

第三步：配置上下文窗口（关键步骤）

:::info 默认上下文行为Roo Code 默认自动遵循 Modelfile 中的num_ctx设置。当你通过 Ollama 使用模型时，Roo Code 会读取模型配置的上下文窗口并自动采用，无需在 Roo Code 设置里单独配置上下文大小——它完全尊重 Ollama 模型中定义的值。 :::

这与源码实现完全一致：在 native-ollama.ts 中，createMessage构建OllamaChatOptions时，只有在显式设置了ollamaNumCtx选项时才传入num_ctx参数，否则完全交由 Ollama 按模型默认值处理。

方案 A：交互式配置

先加载模型（此处以qwen2.5-coder:32b为例）：

ollama run qwen2.5-coder:32b

在交互会话中修改上下文大小参数：

/set parameter num_ctx 32768

保存为新名字的模型：

/save your_model_name

方案 B：使用 Modelfile（推荐）

创建包含目标配置的Modelfile：

# 示例 Modelfile（缩小上下文窗口） FROM qwen2.5-coder:32b # 将上下文窗口设为 32K tokens（由默认值调小） PARAMETER num_ctx 32768 # 可选：调整 temperature 以获得更稳定的输出 PARAMETER temperature 0.7 # 可选：设置重复惩罚 PARAMETER repeat_penalty 1.1

然后基于该文件创建自定义模型：

ollama create qwen-32k -f Modelfile

:::tip 覆盖上下文窗口如需覆盖模型的默认上下文窗口：

永久生效：通过上述任一方法保存一份带有目标num_ctx的新模型版本；
Roo Code 行为：Roo 自动使用 Ollama 模型中配置的num_ctx；
内存考量：在有限硬件上调小num_ctx有助于避免内存溢出（OOM）错误。 :::

第四步：在 Roo Code 中配置

打开 Roo Code 侧边栏；
点击设置齿轮图标；
在API Provider下拉框中选择ollama；
输入上一步得到的模型 tag 或保存名（例如your_model_name）；
（可选）若 Ollama 运行在其他机器上，可配置 Base URL，默认值为http://localhost:11434；
（可选）若你的 Ollama 服务器要求认证，可填写 API Key；
（高级）Roo Code 的ollamaProvider 默认使用 Ollama 原生 API。此外也存在一个兼容 OpenAI 的/v1处理入口，但典型场景下无需使用。

从源码看，native-ollama.ts 中的客户端初始化逻辑会读取ollamaBaseUrl（默认http://localhost:11434），并在设置了ollamaApiKey时自动附加Authorization: Bearer <apiKey>请求头，支持 Ollama Cloud 或带认证的自建实例。这些配置项的 schema 定义见 provider-settings.ts，其中ollamaNumCtx被限定为z.number().int().min(128)，即最小值 128。

Ollama 模型发现机制

Roo Code 通过 fetchers/ollama.ts 拉取模型清单：先请求${baseUrl}/api/tags获取本地模型列表，再对每个模型调用${baseUrl}/api/show读取其 Modelfile 信息与能力声明。其中值得注意的是，源码会过滤掉不具备tools能力的模型（fetchers/ollama.ts）——因为不支持工具调用的模型无法驱动 Roo Code 的 Agent 工具链，因此不会出现在模型列表中。

模型元数据（上下文窗口、是否支持视觉等）从model_info中的context_length键解析而来，见 fetchers/ollama.ts。这也解释了为什么在 Ollama 中修改num_ctx后，Roo Code 的模型信息会随之变化。

Ollama 技巧与注意事项

资源需求：本地运行大模型资源消耗大，请确保硬件满足所选模型的最低要求；
模型选择：多尝试不同模型，找到最适合你需求的组合；
离线使用：模型下载完成后，即可完全离线使用 Roo Code；
Token 统计：Roo Code 会跟踪通过 Ollama 运行的模型的 token 消耗。在 native-ollama.ts 中，流式响应会读取prompt_eval_count与eval_count并输出usage事件；
推理过程解析：对于支持推理的模型（如deepseek-r1），Roo Code 通过TagMatcher解析think标签，将推理过程与正文内容分别呈现（native-ollama.ts），并对deepseek-r1类模型自动应用专用温度默认值。

使用 LM Studio 搭建本地模型

LM Studio 提供友好的图形界面来下载、配置和运行本地模型，其内置的本地推理服务器模拟 OpenAI API，与 Roo Code 的集成非常顺滑。

第一步：下载并安装 LM Studio

从 LM Studio 官网下载并安装。

第二步：下载模型

在 LM Studio 界面中搜索并下载GGUF 格式的模型。可浏览 LM Studio 的搜索界面，或在 Hugging Face 上按 GGUF 库筛选模型。

第三步：启动本地服务器

打开 LM Studio；
点击"Local Server"标签页（图标形似<->）；
选择你下载的模型；
点击"Start Server"。

注意：LM Studio 的本地服务器必须保持运行，Roo Code 才能连接。

第四步：在 Roo Code 中配置

打开 Roo Code 设置（齿轮图标）；
在API Provider下拉框中选择LM Studio；
输入模型文件名（例如codellama-7b.Q4_0.gguf），即你在 LM Studio "Local Server" 标签页中加载的模型文件名；
（可选）Base URL：默认连接http://localhost:1234。若 LM Studio 配置了其他地址或端口，在此填写完整 URL。

从源码看，lm-studio.ts 中LmStudioHandler通过 OpenAI SDK 连接${lmStudioBaseUrl}/v1，并使用"noop"占位符作为 API Key（LM Studio 本地服务器不需要真实密钥）。所有可配置项（lmStudioModelId、lmStudioBaseUrl、lmStudioDraftModelId、lmStudioSpeculativeDecodingEnabled）的 schema 定义见 provider-settings.ts。

LM Studio 高级特性

投机解码（Speculative Decoding）：Roo Code 支持 LM Studio 的投机解码加速。当lmStudioSpeculativeDecodingEnabled开启且设置了lmStudioDraftModelId时，请求会自动附加draft_model参数，用小模型草稿加速大模型生成（lm-studio.ts）；
推理支持：对于支持的模型，Roo Code 可解析 LM Studio 响应中的think标签等推理标记，让你看到模型的思考过程（lm-studio.ts）；
Token 统计：Roo Code 通过本地 tokenizer 统计输入/输出 token 消耗并上报 usage（lm-studio.ts）。

LM Studio 技巧与注意事项

资源需求：运行大模型资源消耗大，请确保硬件满足要求；
模型选择：LM Studio 提供大量模型，多实验找到最适合的组合；
错误排查：如果出现 "Please check the LM Studio developer logs to debug what went wrong" 错误，通常需要在 LM Studio 中调整上下文长度设置。源码中该错误信息提示用户可能需要以更大的 context length 加载模型以适配 Roo Code 的提示词（lm-studio.ts）。

故障排查（Troubleshooting）

"No connection could be made because the target machine actively refused it"

该错误通常意味着Ollama 或 LM Studio 服务器没有运行，或运行在与 Roo Code 配置不同的端口/地址上。请仔细核对 Base URL 设置：

Ollama 默认：http://localhost:11434
LM Studio 默认：http://localhost:1234

从源码看，当连接被拒绝（ECONNREFUSED）时，Roo Code 会抛出明确提示："Ollama service is not running at . Please start Ollama first."（ native-ollama.ts）。

响应缓慢

本地模型通常比云端模型慢，尤其在硬件配置一般的情况下。若性能成为瓶颈，建议换用更小的模型。此外，Ollama 模型发现逻辑会过滤掉不支持工具调用的模型（见 fetchers/ollama.ts），挑选模型时请优先选择官方标注支持工具（tools）的版本，以保证 Roo Code 的 Agent 能力完整可用。

Model Not Found

请确保模型名称拼写正确。若使用 Ollama，应使用与ollama run命令中一致的模型名。当请求的模型在 Ollama 中不存在时（HTTP 404），Roo Code 会提示先执行ollama pull <model>（native-ollama.ts）。

Ollama 首次请求内存溢出（OOM）

症状：

Roo Code 的首次请求以内存溢出错误失败；
模型首次加载时 GPU/CPU 内存占用飙升；
手动在 Ollama 中启动模型后一切正常。

原因：若没有模型实例在运行，Ollama 会按需启动一个。冷启动阶段它可能分配比预期更大的上下文窗口，内存占用随之升高并超出可用 VRAM 或 RAM。这是 Ollama 的启动行为，并非 Roo Code 的缺陷。

修复方案：

预加载模型，保持其运行后再向 Roo 发起请求：

ollama run <model-name>

固定上下文窗口（num_ctx）——方案 A：交互会话后保存：

# 在 `ollama run <base-model>` 会话内 /set parameter num_ctx 32768 /save <your_model_name>

方案 B：使用 Modelfile（推荐，便于复现）：

FROM <base-model> PARAMETER num_ctx 32768 # 根据可用内存调整： # 16384 → 约 8GB VRAM # 32768 → 约 16GB VRAM # 65536 → 约 24GB+ VRAM

然后创建模型：

ollama create <your_model_name> -f Modelfile

确保模型的上下文窗口已被固定：保存 Ollama 模型时带上合适的num_ctx（通过/set+/save，或更推荐 Modelfile）。Roo Code 会自动检测并使用模型配置的num_ctx——Ollama Provider 在 Roo Code 中没有手动上下文大小设置。
使用更小的变体：若 GPU 内存有限，改用更小的量化版本（例如 q4 而非 q5），或更小的参数规模（例如 7B/13B 而非 32B）。
OOM 后重启模型进程：

ollama ps ollama stop <model-name>

快速检查清单：

模型在 Roo 请求前已处于运行状态；
num_ctx已固定（Modelfile 或/set+/save）；
模型以合适的num_ctx保存（Roo 会自动采用该值）；
模型体积适配可用 VRAM/RAM；
无残留的 Ollama 进程。

本地模型的硬件与模型选择建议

硬件最低要求：CPU 尽量多核高频，内存建议至少 16GB；若运行 7B 及以上参数模型，独立 GPU 的显存大小直接决定可选模型的量级与上下文窗口；
模型选择策略：代码补全类任务优先选择专为代码训练的模型（如qwen2.5-coder、devstral系列）；从仓库的默认配置可见，Ollama 默认模型 ID 为devstral:24b（见 providers/ollama.ts），LM Studio 默认模型 ID 为mistralai/devstral-small-2505（见 providers/lm-studio.ts），可作为起步参考；
上下文窗口平衡：Roo Code 的 Agent 工作流依赖工具调用与多轮对话，过小的num_ctx会限制单轮可处理的上下文，过大则容易触发 OOM，需结合硬件内存反复调试。

总结

Roo Code 对本地模型的支持完整且深入：Ollama 侧走原生 API 协议，自动遵循 Modelfile 的num_ctx、过滤无工具能力的模型、内置think标签推理解析与 OOM 防护建议；LM Studio 侧则通过 OpenAI 兼容接口接入，并额外支持投机解码等性能特性。两者均提供 token 统计与完善的错误提示。按本文步骤完成安装、模型拉取、上下文窗口配置与 Provider 设置后，你即可获得一个完全离线、隐私安全、零 API 费用的 Roo Code 本地 AI 编程环境。

【免费下载链接】Roo-CodeRoo Code gives you a whole dev team of AI agents in your code editor.项目地址: https://gitcode.com/GitHub_Trending/ro/Roo-Code

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

企业官网建设流程全解析