上周我把一台旧笔记本翻出来，装了 Ollama，又折腾了一下午，终于把本地跑的 Qwen2.5 Coder 接进了 WorkBuddy。网上能查到的教程其实不少，但真到实操时会发现，能跑通的路径往往藏在别人没写的那几行细节里。这篇文章就是记录我怎么接、踩过哪些坑、最后稳住的一套配置。如果你是刚接触 Ollama，或者已经装了 WorkBuddy 但始终提示连不上模型的同学，这篇应该能帮你省下不少时间。

先说清楚这套东西解决什么问题：WorkBuddy 是一款 AI 编程助手，默认依赖云端大模型，但云端接口有时慢、有时要配额，而且公司代码片段往外送心里总有点不踏实。Ollama 则是本地大模型运行工具，把模型下载到本机后用一条命令就能跑起来，最关键的是它提供了 OpenAI 兼容的 API 接口，这就给了我们一条把本地模型“伪装”成云端接口塞进 WorkBuddy 的捷径。等整条链路通了，你在 WorkBuddy 里写代码、问解释、改 BUG，背后实际跑的是自己机器上的模型，数据不出门，速度也由硬件说了算。

1. 为什么要在 WorkBuddy 里用本地 Ollama 模型

1.1 先理解 WorkBuddy 的模型接入逻辑

WorkBuddy 的模型接入逻辑其实和大部分 AI 编程助手一样，它本身不跑模型，只是把你在编辑器里的提问整理成请求，发到某个模型服务上，再把模型返回的结果渲染回界面。区别在于，默认情况下这个模型服务是云端托管的，你不需要关心地址、密钥这些东西。但在设置里，通常会有模型管理或者自定义模型的入口，进去后可以添加外部模型服务。我们要做的就是在这里填一个指向本地 Ollama 的地址。

如果你之前用过 Cursor 或 CodeBuddy 这类工具，会发现它们的自定义模型入口大同小异，核心都是 Base URL、API Key、Model Name 这三个字段。WorkBuddy 也类似，所以只要你理解了这个通用逻辑，以后换任何工具都能很快上手。我对接时用的版本里，入口在设置里的模型配置区域，具体字段名可能随版本略有不同，但核心就是这几个。

1.2 本地模型解决的痛点

我一开始想接本地模型，主要出于三个考虑。第一是隐私，公司项目代码讲究保密，往云端送总归有顾虑，虽然云厂商都说数据不会用于训练，但心理这关过不去。第二是成本，云端按 token 计费，本地模型跑多少都不花钱，对于高频使用 WorkBuddy 的人来说，这笔账算下来差别很大。第三是离线，出差路上、断网环境下，WorkBuddy 照样能用，这种“随时可用”的踏实感只有试过才知道。

当然也有代价，本地几 B 的小模型跟云端几百 B 的模型在代码生成质量上有差距。所以这个方案更适合把日常简单任务留在本地，重要任务切回云端。我现在的工作流是本地模型负责补全、解释、简单重构，遇到复杂架构设计或者疑难 BUG 再切云端大模型，两边互补，还挺顺手。

1.3 为什么选 Ollama 而不是其他本地推理工具

本地跑模型的工具其实不少，LM Studio、llama.cpp、Ollama 都能做到。我在对比后选了 Ollama，原因主要有三点。一是安装极其简单，Windows 双击安装包、macOS 用 Homebrew、Linux 一条命令，对新手很友好。二是模型管理方便，ollama pull、ollama list、ollama run 的方式非常线性，不用记一堆参数。三是它自带 OpenAI 兼容接口，这一点直接决定了 WorkBuddy 能不能把它当云端模型用。你不需要给 WorkBuddy 写任何插件，只要地址填对，它就能通信。

我见过有人用 llama.cpp 跑模型，然后手动起一个 OpenAI 兼容的代理服务，再加一堆配置，链路越长越容易出问题。Ollama 把这一步做成了开箱即用，在我眼里这就是它最适合接进 WorkBuddy 的理由。

2. 准备工作：把 Ollama 和模型先跑起来

2.1 安装 Ollama，顺手解决下载慢的问题

不同系统安装方式差别不大。以 Windows 为例，官网下载安装包双击就能装，装完右下角托盘会多一个 Ollama 图标，说明服务已经跑起来了，默认监听在 11434 端口。macOS 用户更简单，终端执行 brew install ollama，然后用 brew services start ollama 把服务拉起来。Linux 用户一般用官方提供的一键安装脚本，装完以后服务由 systemd 管理。

网上问得最多的是下载慢。尤其是 Windows 安装包，有时候卡在下载界面半天不动。我的做法是：直接把官方安装包的下载链接复制到下载工具里，或者找社区分享的镜像搬运版本。镜像版本也不是不能用，但下载后建议核对一下文件哈希，确保和官方版本一致。如果你嫌的是模型文件太大，这种情况更常见，一个 7B 模型要 4GB 多，国内仓库拉取确实可能随时断线。碰到这种情况，我一般先重试几次，卡住就换个时间段再拉，或者把模型源切到能用的镜像地址。这类镜像地址在社区讨论里经常有人维护，按对应说明配一下环境变量就能用。

2.2 拉取合适的模型，先别急着挑大的

装好 Ollama 后第一件事是拉模型。如果是用来写代码，我建议先试 qwen2.5-coder:7b，这条模型在代码补全和解释上的表现比较均衡，7B 版本对内存的需求也不离谱。命令很简单： ollama pull qwen2.5-coder:7b 。下载完成后用 ollama list 确认一下，能看到一行 qwen2.5-coder:7b 就说明模型就位了。

刚上手时容易犯一个毛病，就是直接拉 32B 甚至 70B 的大模型。结果要么机器带不动，要么响应慢到想砸键盘。我的经验是：本地模型的选择标准不是越大越好，而是“能在你机器上流畅跑起来的前提下选最大的”。16G 内存的机器，7B 模型配合 Q4 量化是舒适区，14B 模型就比较吃紧，32B 就别想了。先把 7B 跑通，再慢慢试更大的，这样体验会平滑很多。

模型跑起来之前，先在终端里确认模型能正常对话。执行 ollama run qwen2.5-coder:7b ，然后随便问一句“写一个读取 JSON 文件的 Python 函数”，如果模型开始输出，说明 Ollama 自身没问题。这一步的目的是把故障范围缩小：先把 Ollama 这层搞定，再谈 WorkBuddy 对接，不然两边一起排查会非常头疼。

2.3 一分钟自检 Ollama 服务

WorkBuddy 连不上 Ollama，很多时候是 Ollama 服务没起来，或者端口不对。这里有一个最直接的自检方法：新开一个终端窗口，执行 curl http://127.0.0.1:11434/api/tags 。如果返回的是一段包含 models 字段的 JSON，就说明 Ollama 正常、端口也正常。如果提示 Connection refused，先检查托盘图标或后台进程，再确认 11434 端口有没有被占用。Windows 下可以用 netstat -ano | findstr 11434 ，Linux 或 macOS 用 lsof -i :11434 。

这里顺带提醒一个操作理念：任何接入问题，先分三层排查——服务层、接口层、配置层。服务层就是 Ollama 有没有在跑；接口层就是用 curl 自己访问一下；配置层才是去 WorkBuddy 看填的地址对不对。大多数情况下，问题出在配置层，但很多人一上来就改配置，越改越乱，最后连一开始的错误都忘了长什么样。

3. 核心对接：在 WorkBuddy 里填对那三个字段

3.1 API Base 地址：漏了 /v1 就全废

第一次在 WorkBuddy 里添加自定义模型时，我被两个细节卡了很久。首先是 API 地址。Ollama 的 OpenAI 兼容接口不是根路径，而是 http://127.0.0.1:11434/v1 。WorkBuddy 里通常会让填 API Base，这个值必须是带 /v1 的完整地址，漏掉 /v1 后 WorkBuddy 会把请求发到不存在的路径上，报错千奇百怪，最容易让人误判。

另外一个细节是地址用 127.0.0.1 还是 localhost。这两个在绝大多数情况下等价，但如果你机器的网络环境比较特殊，像有些环境会优先解析 IPv6，而 Ollama 默认监听 IPv4，直接填 localhost 反而可能连不上。我的建议是统一用 127.0.0.1，少一个变量，就少一个坑。等你以后配置远程服务器上的 Ollama，再把地址换成局域网 IP 也不迟。

3.2 API Key：本地服务不鉴权，但表单校验是真的

接着是 API Key。Ollama 本地接口不做鉴权，但这个字段在 WorkBuddy 里往往必填，不填根本保存不了。我一开始以为随便填会被拒绝，实际试下来填个字符串“ollama”完全没问题。后来才想明白，WorkBuddy 只是把这个值放在请求头里发过去，Ollama 根本不校验它，所以只要别留空就行。

但是这里有一个隐性坑：有些自定义模型的表单里，API Key 字段会有格式校验，比如必须 sk- 开头。如果你遇到这种情况，填一个 sk-ollama 就能通过校验，实测不影响后续请求。另外注意，WorkBuddy 的模型配置是按会话级别生效的，改完配置后记得新建一个会话再测试，旧会话可能还在用之前的模型配置，导致看起来改了没反应。

3.3 模型名称：完整标签一个字符都不能少

然后是最坑的模型名称。你在 WorkBuddy 里填的模型名，必须是 ollama list 里看到的那个完整名字，包括版本标签。比如 qwen2.5-coder:7b，不能只填 qwen2.5-coder，更不能自己编一个。我之前图省事填了个 qwen2.5，结果请求发过去后 Ollama 直接返回 404 Model Not Found。这个坑其实很好解释：WorkBuddy 只是把你的模型名原样放进请求体里，Ollama 收到不认识的模型名，自然不会帮你加载。

如果你不想记完整标签，还有一个更省事的办法：在 Ollama 里给某个模型创建一个自定义标签。比如执行 ollama cp qwen2.5-coder:7b mycoder ，之后 WorkBuddy 里填 mycoder 就行。这样即使以后底层模型换了，WorkBuddy 配置不用动，只是重新映射一下标签而已，这个思路在多个项目中都很实用。

3.4 配置完成后的验证方式

配置完成后，在 WorkBuddy 的对话面板里把模型切到刚添加的自定义模型，发一句话试试。如果模型开始回复，恭喜，链路通了。如果迟迟不回复，也不要急着删配置，先看 Ollama 所在终端有没有输出响应日志。Ollama 默认会在控制台打印请求日志，看到 POST /v1/chat/completions 200 这种记录，说明请求已经进来了，问题多半出在 WorkBuddy 对回复的解析上；如果连日志都没有，请求根本没到 Ollama，问题基本出在地址或网络层。

这个验证习惯我强烈建议养成。日志不会骗人，WorkBuddy 界面上的报错有时候很笼统，但 Ollama 终端里的日志会告诉你请求到底有没有到达、状态码是多少、响应用了多长时间。有了这些信息，排查方向一下就清晰了。

4. 踩坑实录：排查与避坑技巧

4.1 常见问题速查表

我把实际遇到的、以及在社区里看到的高频问题整理成了一张表，直接抄作业就行。

现象	直接原因	处理方式
连接不上 Ollama 服务	Ollama 没启动 / 端口被占	启动服务；用 netstat/lsof 检查 11434 端口
404 Model Not Found	模型名写错	用 ollama list 对照完整模型名
401 或 API Key 报错	Key 为空或格式不对	填任意非空字符串，如 sk-ollama
请求超时	小模型太慢 / 响应时间设置过短	换更大内存；用一句话测试而非长代码
回复内容被截断	上下文窗口太小	调大 num_ctx 或 OLLAMA_CONTEXT_LENGTH
模型回复乱答	模型本身能力有限	换成 coder 系列或更大的量化版本
配置保存后不生效	旧会话缓存	新建会话再测试
找不到自定义模型入口	WorkBuddy 版本问题	升级版本或在设置里开启实验功能

4.2 三个典型问题的深度排查

第一个是 Connection refused。本质上就是 Ollama 没在跑，很多同学装完 Ollama 以为双击过安装包就行了，其实那是安装，不是启动。在 Windows 上装完后服务默认会自动启动，但不代表 100% 成功，被安全软件拦截、端口被占用都可能导致服务退出。处理方式很直接：任务管理器里看有没有 Ollama 进程；没有就手动启动；有但端口不通，就强制结束进程重启服务。这个问题的排查成本最低，却占了所有对接问题的三成以上。

第二个是填了地址和模型之后，WorkBuddy 提示超时。这时候先别怀疑配置，先判断模型本身速度。7B 模型在 CPU 上跑，一个补全请求等十几二十秒都正常，WorkBuddy 如果默认的响应超时时间比较短，就会提前判断为失败。我的处理办法是先降低预期，用一句话测试而不是让模型写一大段代码；如果模型回复成功，再去考虑性能优化。另外，生成参数里的温度调低一些，也能减少模型反复琢磨导致的长耗时。

第三个是上下文不够用。WorkBuddy 发过去的请求会带上一部分对话历史，如果历史太长被截断，或者模型丢失重点，回答质量就断崖式下跌。这个问题的根源在于本地模型的上下文窗口默认值普遍偏小。Ollama 在启动模型时可以通过环境变量 OLLAMA_CONTEXT_LENGTH 调整上下文长度，或者在请求参数里带上 num_ctx。但要注意，上下文长度越大，内存占用越高，7B 模型从 2048 拉到 8192，内存占用会明显上升，机器比较老的慎开。

4.3 对接排查的正确顺序

很多人在对接失败时，习惯先去 WorkBuddy 里反复修改配置，这是个误区。正确顺序应该是从底层往上层查：先确认 Ollama 服务活着，再用 curl 验证 API 通了，最后才检查 WorkBuddy 的配置。我把这个排查顺序整理成一个标准化流程。

第一步，检查服务： ollama -v ，确认命令存在； ollama ps ，确认模型是否已加载。第二步，检查接口： curl http://127.0.0.1:11434/api/tags ，确认 API 返回正常。第三步，直接调一次对话接口： curl http://127.0.0.1:11434/v1/chat/completions -H "Content-Type: application/json" -d '{"model":"qwen2.5-coder:7b","messages":[{"role":"user","content":"hi"}]}' ，看能不能拿到回复。第四步，如果以上都通过，再回 WorkBuddy 里逐项核对三个字段。按照这个顺序，大多数问题都能在三五分钟内定位。

4.4 我的避坑心得

有几个小习惯是在反复踩坑后养成的。第一，系统级环境变量改完一定要重启 Ollama 进程，否则改了等于没改。第二，WorkBuddy 配置完一定要点保存并新建会话，旧会话的模型状态是缓存的。第三，本地模型不要开太高并发，一次只让它干一件事，串行请求比并行更稳定。第四，Ollama 的版本更新节奏比较快，如果哪次更新后 WorkBuddy 突然连不上了，先看是不是 Ollama 版本变了导致接口行为有差异，回退一个版本试试。

还有一个心得体会是不要迷信配置项。WorkBuddy 里能调的参数看起来很多，但实际对接本地模型时，真正影响成败的就是地址、密钥、模型名这三个字段。把这三个字段理解透了，剩下的优化都是锦上添花。

5. 进阶优化：本地模型也能用得顺手

5.1 调整上下文窗口，解决截断问题

如果你想让本地模型稳定地辅助写代码，上下文太小体验会很差。我是通过环境变量 OLLAMA_CONTEXT_LENGTH=8192 来启动 Ollama 的，Windows 在系统环境变量里加，macOS/Linux 在终端 export 一下再启动服务。改完必须重启 Ollama，否则不生效。这个值按机器内存来定，8G 内存的建议 4096，16G 以上的可以试 8192，再往上就容易出现模型加载缓慢甚至内存溢出。

我在实际使用中发现，把上下文拉长以后，WorkBuddy 里关于前文代码的追问质量提升非常明显。之前模型经常忘了你五分钟前让它改的变量名，现在基本都能记住。不过要注意，上下文越长，首字响应越慢，所以如果只是做简单的代码补全，倒也不用非得开到 8192，看需求来就行。

5.2 选对量化等级，内存和速度都舒服

本地跑模型，量化等级决定一切。同样一个 7B 模型，Q4_K_M 量化版本比 Q8 大概小一半，响应速度还能快不少。日常写代码用 Q4_K_M 就够，追求代码质量可以试试 Q8 或原版，但前提是你内存够大。在 Ollama 里拉取的时候可以直接指定量化版本，比如 qwen2.5-coder:7b-q4_K_M，这是 Ollama 官方仓库里常见的标签。选对量化等级，比调任何生成参数都管用。

这里有个容易忽略的点：如果你先 pull 了一个模型，后来又 pull 了同系列不同量化的版本，磁盘上会同时存在多个版本，白白占空间。所以建议在拉模型之前先想好用哪个版本，别把所有版本都拉一遍，最后磁盘满了还要一个个清理。 ollama rm 模型名 可以删除不用的模型，这个命令我每个月都会用几次。

5.3 多模型按场景切换

本地模型的好处之一是可以同时拉好几条。我现在的习惯是，日常补全和代码解释用 qwen2.5-coder:7b，长文本摘要用 qwen3 系列，简单问答用更小的模型，比如跑 RAG 场景时用轻量 embedding 模型。在 WorkBuddy 里把常用模型都加到自定义列表，场景不同就切成不同的模型。反正本地跑不花钱，切换成本比云端低得多。

多模型切换也有一个坑，就是模型名容易混淆。我给每条模型都取一个容易辨认的自定义标签，比如 coder-main、summary-light、embedding-prod，在 WorkBuddy 里一眼就能认出来。用 ollama cp 创建标签只需要一次操作，后面的省心程度却很高。

5.4 让 Ollama 常驻后台

最后是一个容易被忽略的使用体验问题：Ollama 服务必须常驻，WorkBuddy 才能随时连上。Windows 版安装后默认开机自启，Linux 和 macOS 如果用的是 brew services 或 systemd，建议把自启也配上。这样每次打开 WorkBuddy，本地模型都在线，不用先记着去启动 Ollama。

我一开始用的是手动启动方式，经常打开 WorkBuddy 想写代码时发现 Ollama 没在跑，又要切回终端敲命令。后来把服务设为开机自启，这个问题彻底消失。如果你用的是 Linux 服务器，还要注意设置 OLLAMA_HOST=0.0.0.0，这样局域网内其他机器的 WorkBuddy 也能连上，但这一步对安全性有要求，只建议在可信内网里用。

整个流程走下来，真正的核心心得其实就是一句话：先让 Ollama 自己跑通，再用 WorkBuddy 调接口，别并行排查。我在实际对接中最大的收获是学会了用 curl 验证接口，这一步帮我滤掉了一多半的配置问题。另外一个小技巧，把 Ollama 的日志窗口留在后台，每次遇到玄学问题先看日志，WorkBuddy 界面上报错再奇怪，日志都会告诉你真相。

最后再分享一个我的习惯：把 curl 验证命令写成一个小脚本放在桌面，每次 WorkBuddy 抽风先跑一遍脚本，心里就有底了。另一个是别贪大模型，在 WorkBuddy 日常辅助场景里，7B 量级的模型配合 8192 上下文已经能覆盖大多数需求，硬跑 14B 或 32B 模型对机器压力大、响应也慢，体验反而不如小模型来得顺滑。这个是我踩过几次坑之后的真实感受，希望你能少走点弯路。