Roo Code 本地模型指南：三步接入 Ollama，断网也能跑 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 编码助手都会直接停摆。Roo Code 的本地模型功能解决的就是这个问题：把开源大模型跑在你自己的机器上（通过 Ollama 或 LM Studio），提示词和代码全程留在本机，离线状态下对话、改文件、执行命令照常进行。本篇先走最短路径跑通 Ollama 接入，再讲适用场景、内部原理和调优排障。
快速上手：三步跑通 Roo Code 本地模型
整条路径不需要写一行代码，前提是已安装 Roo Code 插件（VS Code 均可使用）。
装 Ollama 并拉取本地模型
- 从 Ollama 官网下载对应系统的安装包，按向导完成安装。桌面版安装后后台服务会自动启动；纯命令行版需先执行
ollama serve。 - 服务默认监听
http://localhost:11434，终端执行ollama list不报错即代表可用。 - 拉取一个带工具调用能力的代码模型：
ollama pull qwen2.5-coder:7b显存紧张选 7B 档，有独立显卡可选 14B 或 32B 档。
在 Roo Code 设置里接入 ollama 提供商
- 打开 Roo Code 侧边栏，点齿轮进入设置。
- API Provider 选Ollama；模型名填上一步的标签（如
qwen2.5-coder:7b）。 - Base URL 默认就是
http://localhost:11434，本地部署不用动；Ollama 装在别的机器上才需要改。服务开了鉴权时补一个 API Key。 - 保存后发一句"给这个函数写个单测"，本地模型开始流式输出即接入成功，底部 token 统计同样生效。
更习惯图形界面的话，LM Studio 是另一条路线：装好后启动它的本地服务器，Roo Code 里改选 LM Studio 提供商即可，两者用法相近，官方文档在 apps/docs/docs/advanced-usage/local-models.md。
本地模型能干什么：四个真实场景
- ✅敏感代码不出机器：内部项目、客户代码、涉密仓库，所有提示词与文件内容都留在本地推理，合规审查场景直接可用。
- ✅断网环境照常开发：模型一旦拉取完成，后续推理完全不依赖网络。飞机上、高铁上，代码审查、小功能开发、跑测试流程不断档。
- ✅高频使用省 token 费用：本地推理没有按量计费。配合配置档案，云端与本地两套设置一键切换：日常重活用云端，批量小任务切本地。
- ✅本地模型同样跑 Agent 工作流：读文件、搜索代码、改文件、执行命令这些工具调用本地模型全部支持，自动批准面板行为与云端一致。
它是怎么工作的：从消息到本地推理
接入后 Roo Code 会先向http://localhost:11434拉取模型清单：不支持工具调用的模型会被直接过滤掉，不会出现在下拉框里；同时读取每个模型的上下文长度作为窗口上限，有 vision 能力的还能处理图片。
发消息时，原生处理器把 Roo 内部的消息格式（含工具结果、图片块）翻译成 Ollama 原生格式，把工具定义转成 Ollama 的 tool_calls 结构，流式回收文本与工具调用；<think>标签内容会被识别为推理过程单独展示。流结束时的 token 用量汇总后回传状态栏。
上下文窗口以模型 Modelfile 里的num_ctx为准；如果额外配置了ollamaNumCtx，请求会携带这个覆盖值。核心逻辑分别在 src/api/providers/native-ollama.ts（消息转换与流式处理）和 src/api/providers/fetchers/ollama.ts（模型清单解析与过滤）。
进阶调优与常见坑：先调上下文，再查服务
性能调优：上下文、温度、模型大小
- num_ctx 决定内存占用，按需固定。推荐档：约 8GB 显存用 16384，16GB 用 32768，24GB 以上可用 65536。用 Modelfile 固化：
FROM qwen2.5-coder:7b PARAMETER num_ctx 16384- 温度默认是 0：本地代码模型低温输出更稳定，一般不用动；deepseek-r1 这类推理模型走单独的默认温度。
- 显存不够就降档：换 q4 量化或更小参数量，比硬上大模型更实际。
现象 → 原因 → 解法：排障速查表
| 现象 | 原因 | 解法 |
|---|---|---|
| 报 "Ollama service is not running at http://localhost:11434" | 服务没起或 Base URL 填错 | 启动ollama serve，核对地址与端口 11434 |
| 报 "Model xxx not found in Ollama" | 模型没拉取，或名称对不上 | ollama pull后再试；名称与ollama list完全一致 |
| 第一条请求 OOM，之后正常 | 冷启动时上下文窗口分配偏大 | 先ollama run <模型>预热；固定num_ctx；换小量化 |
| 下拉框里找不到某个模型 | 该模型没有工具调用能力，被过滤 | 换带 tools 能力的标签，或换模型 |
| 响应明显偏慢 | 本地推理吞吐限制 | 换更小模型；关闭抢占显存的程序 |
下一步与未来方向
开源模型的工具调用支持还在快速补齐，Roo Code 已同时接入 Ollama 与 LM Studio 两条本地路线，后续可期待更多本地推理选项与更细的推理参数。现在就可以拉一个 7B 模型，把 Provider 切到 Ollama 跑通第一句对话——断网也能写代码的工作流，从今天起成立。
【免费下载链接】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），仅供参考
