企业官网建设流程全解析

开始折腾 WorkBuddy 自定义模型接入，纯粹是被逼的。那阵子我每天的工作流是：先在 IDE 里写代码，遇到问题就切到 WorkBuddy，让它帮我分析报错、补全函数、改 bug。官方模型确实聪明，但有两个让我很别扭的地方——一个是 token 消耗真的快，几个聊天来回下来，额度就见底了；另一个是公司项目代码不能随便往外送，每次看到它把代码片段上传到云端，我心里都打鼓。于是我决定接自定义模型，把模型换成我自己可控的云端 API，或者干脆用本地跑的小模型。

这篇不是官方文档的复述，是我自己从零配置到跑通、再到日常稳定的全过程记录。WorkBuddy 支持自定义模型接入，你可以把默认的模型服务替换成任意兼容 OpenAI 接口协议的大模型，这意味着成本可控、数据边界可控、模型选择也可控。适合手里有模型 API 额度、或想用 Ollama 跑本地模型，又不想放弃 WorkBuddy 这套交互体验的人。我把我踩过的坑、试出来的参数、还有心态上的变化都写出来，给想折腾的朋友一个真实参考。

1. 为什么非要给 WorkBuddy 接自定义模型

1.1 官方模型之外的三个真实诉求

先交代一下背景。WorkBuddy 这类 AI 编程助手，默认情况下是调用它们官方绑定的大模型，好处是开箱即用，坏处也很明显。

第一是成本。我日常使用频率高，尤其是写单元测试和补全重复代码的时候，一个上午能发出几十次请求。官方模型的计费按 token 走，积少成多，月底一看账单，肉疼。自定义接入之后，我可以选择更便宜的模型，甚至把高频低难度任务交给本地模型，成本直接从"可控"变成"几乎为零"。

第二是数据边界。在公司内网环境开发时，代码本身的敏感性比很多人想象的高。你让 AI 助手分析报错，它会把整个文件、上下文、甚至邻接文件的内容一起发出去。官方模型的服务端在哪里、数据怎么处置，对开发者来说是个黑盒。自定义接入允许我把请求指向企业内部的模型网关，或者直接指向本机的 Ollama，至少数据不出本机。这一点对于医疗、金融、政务类项目的团队来说，不是可选项，是硬性要求。

第三是场景匹配。代码助手要干的事情其实差异很大：写一个排序函数和重构一个模块的业务逻辑，需要的模型能力完全不是一个量级。接自定义模型之后，我可以配两个甚至三个模型：轻量任务用 7B 的本地模型，秒回、免费；复杂任务切到云端大模型，追求理解力。这个"分场景用不同模型"的思路，官方内置模型给不了。

1.2 先搞清楚"接入"到底在接什么

很多人一听"自定义模型接入"，第一反应是"把接口地址改一下就行"。方向没错，但实际操作时，你要给 WorkBuddy 提供的不是一两个参数，而是一整套模型接入信息。本质上，WorkBuddy 是通过一套标准化的接口协议去调用模型的，只要你选的模型或者服务中间层兼容这套协议，就能接进去。

我把它类比成给打印机换墨盒：打印机有一个标准卡槽（接口），墨盒只要符合卡槽的规格（协议兼容），就能装上去用。但不同的墨盒，墨水颜色、浓度、适配纸型都不同，你得在打印机设置里告诉它"我换了一支什么墨盒"——这一步就是 WorkBuddy 里的模型名称、参数配置。

所以，接自定义模型的本质是回答几个问题：

• 你的模型服务地址是什么（base URL），是云端还是本机
• 你的认证凭证是什么（API Key），还是本地服务不需要认证
• 你调用的模型叫什么名字（model name），名字写错是最常见的坑
• 你的模型支持哪些能力（function calling、tool use、流式输出），这决定了 WorkBuddy 能不能用 Agent 模式

把这几个问题想清楚，配置就成功了一半。后面所有坑，几乎都出在这几个问题的答案上。

2. 开工前的三张清单：模型、密钥与运行环境

2.1 模型选型：云端 API 与本地模型的取舍

动手配置之前，先选模型。我先后试过两条路线：云端 API 和本地模型。

云端路线的代表是 DeepSeek、通义千问、智谱 GLM 这类对外提供 API 的模型服务。优点是模型能力强、部署零成本，缺点是每次请求都走公网、数据要出本地，以及按 token 计费。适合追求代码质量、不在意数据出域的场景。

本地路线我主要用 Ollama 跑开源模型。优点不用说，免费、数据不出本机、响应速度通常也够用；缺点是模型能力受限于你的显卡和内存，7B 模型在复杂任务上的表现和云端旗舰模型有明显差距。另外，如果你没有像样的独立显卡，纯 CPU 跑大一点的模型会慢到怀疑人生。

我用一张表总结一下我当时纠结的结果：

我的建议是：如果你只是想省点钱，接云端 API 就够了，配置简单、效果有保障；如果你是奔着数据安全去的，或者想完全避开网络因素，那老老实实走本地模型路线。两者不冲突，WorkBuddy 支持多配置，我可以随时切换，这个后面会讲。

2.2 环境准备：先装什么、先不装什么

确定路线之后，别急着打开 WorkBuddy 的配置面板。我踩过的第一个坑，就是"在没有验证接口可用的情况下直接改配置"，结果出了问题根本分不清是网络问题还是配置问题。正确的顺序是先把环境准备好，再用命令行把接口验证一遍，最后才去改 WorkBuddy。

环境准备分两种情况：

如果走本地模型路线，先安装 Ollama。装完在终端跑一下：

ollama pull qwen2.5-coder:7b ollama run qwen2.5-coder:7b

能正常对话之后再往下走。注意，Ollama 安装完成默认监听在 11434 端口，它同时提供原生接口和 OpenAI 兼容接口，后者是 WorkBuddy 能接上的关键。

如果走云端 API 路线，先去对应平台注册账号、创建 API Key。创建完先做一次连通性验证。以 DeepSeek 为例，在终端跑：

curl https://api.deepseek.com/chat/completions \ -H "Content-Type: application/json" \ -H "Authorization: Bearer 你的API_KEY" \ -d '{"model":"deepseek-chat","messages":[{"role":"user","content":"你好"}]}'

返回一段 JSON，里面有choices字段，说明接口通了。本地 Ollama 也可以这么验：

curl http://localhost:11434/v1/chat/completions \ -H "Content-Type: application/json" \ -d '{"model":"qwen2.5-coder:7b","messages":[{"role":"user","content":"你好"}]}'

这里有个细节：Ollama 的 OpenAI 兼容地址是http://localhost:11434/v1，注意/v1一定要带上。我第一次配置就是漏了/v1，结果 WorkBuddy 一直报 404，折腾了半小时才反应过来。

3. 核心配置步骤：从新建配置到第一次对话

3.1 找到 WorkBuddy 的配置入口

环境验证通过之后，就可以回到 WorkBuddy 做配置了。不同版本的入口可能不完全一样，但大体逃不出两条路：一是设置面板里的模型或 Provider 管理，二是在用户目录下的.workbuddy/配置文件里手动编辑。我用的是本地配置文件的方式，因为字段全、可控性强，改错了也容易回滚。

我这边实际生效的配置文件路径是~/.workbuddy/config.json，如果你的系统里没有这个文件，创建一个就行。配置内容长这样：

{ "providers": [ { "name": "deepseek", "baseUrl": "https://api.deepseek.com", "apiKey": "sk-xxxxxxxxxxxxxxxx", "models": [ { "name": "deepseek-chat", "type": "chat", "maxTokens": 8192 } ] }, { "name": "local-ollama", "baseUrl": "http://localhost:11434/v1", "apiKey": "ollama", "models": [ { "name": "qwen2.5-coder:7b", "type": "chat", "maxTokens": 4096 } ] } ], "activeProvider": "deepseek", "activeModel": "deepseek-chat" }

这个结构不是我瞎编的，是我自己配置时试出来的形态。它基本对应了大多数同类 AI 助手的 Provider 配置范式：一个 provider 代表一个模型服务来源，里面可以挂多个模型。如果你用的是企业内部自建网关，或者某些中转平台，配置结构也类似，只是 baseUrl 和 apiKey 不同。

3.2 配置项逐字段拆解

很多人喜欢直接复制网上的配置，但不知道每个字段是干什么的，一旦报错就抓瞎。我逐个说一遍我理解的含义：

• name：provider 的名称，纯粹是给你自己看的，起个好认的名字，比如deepseek、local-ollama、company-gateway。
• baseUrl：模型服务的基础地址。这是最关键也最容易填错的字段。要注意，云端 API 有些平台要求填到域名根路径，有些要求填到/v1，Ollama 的 OpenAI 兼容接口则必须带/v1。拿不准的时候，把你已经在命令行验证过的地址复制过来，不要手敲。
• apiKey：认证凭证。本地 Ollama 一般不校验 Key，随便填一个非空字符串就能过；云端 API 必须填真实有效的 Key。我建议把 Key 放到环境变量里引用，而不是明文写进配置文件，尤其是你的配置文件可能要提交到公司仓库时。
• models：模型列表。每个模型对象里，name要和模型服务实际支持的名字完全一致。DeepSeek 的对话模型叫deepseek-chat，推理模型叫deepseek-reasoner，名字写错直接 404。
• maxTokens：单次最大输出 token 数。设置太小，代码生成到一半会截断；设置太大，又可能超过模型服务的限制导致报错。主流平台的上下文长度普遍到 8K 以上，我日常设 8192，够用。
• activeProvider/activeModel：默认生效的 provider 和 model，对应你在界面上看到的当前模型。

除了这些基础字段，还有一些高级参数我在后面调优时才会动，比如temperature、stream、customHeaders。customHeaders用来给请求附加自定义 HTTP 头，有些企业内部模型网关会要求带特定 header 鉴权，这时候就需要它。

3.3 第一次对话：怎么判断配置真的生效了

配置保存之后，别急着让它改代码，先在对话窗口发一句最简单的"你好"，观察三件事：

第一，是否能正常返回内容。如果返回空或者报错，说明请求根本没出去，或者出去之后被拒了。这时候去看 WorkBuddy 的日志，通常在配置文件同目录下有个logs/文件夹，也可以直接在日志面板里看。第二，对话是否带模型名标识。如果你配了多个模型，界面会显示当前用的是哪个，方便你确认切换到的到底是不是目标模型。第三，响应速度是否正常。如果等了十几秒才出第一个字，多半是网络问题，或者模型服务端负载太高。

第一次对话跑通之后，我建议立刻做一个"实战验证"：给它一段故意写错的代码，让它定位问题并修复。这一步能同时验证两个关键能力：模型能不能理解代码上下文，以及 WorkBuddy 的文件读写能力是否正常联动。如果只是对话正常但改不了文件，那后面所有自动化都无从谈起。

4. 踩坑记录：我在这条路上摔过的六个跟头

这是大家最想看的部分。我从接入到现在，前前后后遇到过十来个报错，挑了六个最有代表性、也最可能复现的写出来。每一个我都尽量还原当时的报错信息、排查思路和最终解法。

4.1 模型名写错，接口直接 404

第一次配置云端 DeepSeek 的时候，我在配置里写了model: deepseek-coder，因为这是个很熟悉的名字，觉得肯定没错。结果 WorkBuddy 一直报404 model_not_found。我用命令行一测，发现平台要求的是deepseek-chat。教训是：模型名不是你以为的名字，而是模型服务文档里写的那个名字。配置前打开官方文档核对一下，或者用平台的模型列表接口拉一下，比瞎猜靠谱得多。

4.2 baseUrl 少了/v1，被 404 折腾半小时

刚才提到过，这个坑我在 Ollama 上踩过。WorkBuddy 调的是 OpenAI 兼容接口，地址必须是http://localhost:11434/v1，而不是裸的http://localhost:11434。云端有些平台也类似，根路径和带/v1的路径返回的内容可能完全不同。我的排查方法很简单：先用命令行 curl 跑通，再原封不动把地址复制进配置，不要手动补路径。

4.3 temperature 设置过高，代码变成了"散文"

接本地模型之后，一开始我图新鲜，把所有参数都拉满，temperature 直接调到了 1.5。结果模型生成的代码，注释倒是写得很美，像抒情散文，但变量名一会儿一个风格，函数逻辑大跳步，基本不能用。后来我把 temperature 降到 0.2 左右，代码风格立刻稳了。对于代码生成任务，temperature 不是越高越有创造性，而是越低越可控。这个参数我在后面调优部分还会细讲。

4.4 模型不支持 function calling，Agent 模式直接哑火

这是我踩过最严重的一个坑。我先把 WorkBuddy 的配置切到一个轻量本地模型上，想节省成本，结果发现它只能聊天，不能改文件，也没有工具调用行为。查了日志才发现，模型服务在响应里拒绝了功能调用请求。原因是那个模型版本不支持 function calling。这就是我前面说的——不是所有模型都具备 Agent 能力。WorkBuddy 的改代码、跑命令、管理文件这些能力，依赖底层的工具调用，模型不支持，上层功能就全瘫痪。解决方法是换一个支持 function calling 的模型，或者让轻量模型只做问答，把代码操作类任务留在更强的主模型上。

4.5 maxTokens 设太小，代码生成到一半被截断

有一次我让它写一个完整的配置文件，写到一半突然断了，末尾也没有正常收尾。一开始我以为是模型能力问题，后来看日志发现返回长度正好卡在maxTokens的上限。我设的是 2048，确实太小了。生成一个上百行的配置文件很容易就超。后来我把代码生成任务的 maxTokens 提到 8192，截断问题就再没出现过。这个参数要结合你的实际任务来定，宁可设大一点，也不要频繁截断，否则生成结果没法直接用，还得二次加工，更浪费时间。

4.6 配置里有多个 provider，切来切去忘了当前是哪个

这个问题不算报错，但很影响体验。我有 local-ollama 和 deepseek 两个 provider，每次切换都要回配置文件改activeProvider。有次我急着干活，忘了切回来，结果聊天是正常的，但一让它改代码就报工具调用失败，我排查了半天才意识到用的是本地轻量模型。后来我养成了一个习惯：在 WorkBuddy 的对话首句先确认当前模型，比如直接问"你当前用的是哪个模型"，通常它会从系统信息里拿到准确的名字。多模型混用的时候，这个确认动作能省很多事。

我把上面这些坑汇总成一张排查表，留着以后参考：

5. 接入稳定之后：参数调优与日常工作流磨合

5.1 不同任务推荐参数配方

接入稳定之后，我开始琢磨怎么让模型在具体场景下发挥得更好。同样的模型，参数不一样，效果天差地别。我总结了一套自己的配方，不一定适合所有人，但思路可以参考。

这里最核心的一条是我反复验证过的：在代码场景里，temperature 普遍要控制在 0.4 以下，尤其是补全和生成测试，几乎都是低温更稳。只有做方案讨论、头脑风暴这类"不立即落地"的任务，才值得把温度调高。另外，如果你接的是 deepseek-reasoner 这类推理模型，它在输出答案之前会先输出一段 reasoning 内容，推理模型的 temperature 往往有额外限制，配置时可以留意一下模型文档里的说明。

5.2 多模型切换的小技巧

我一直保留两个 provider，一个本地一个云端，切换方式是通过改activeProvider。但每次都改文件太累了，我的做法是建了两个配置文件：一个默认用本地模型，一个默认用云端模型，需要切换时直接替换配置文件，再重启 WorkBuddy。你也可以看 WorkBuddy 的设置界面是否支持直接切换，支持的话会更方便。

另一个技巧是给不同模型设置不同的"使用场景"，记在本子上或者写在配置的注释里。比如我的规则是：日常快速问答用本地，代码生成和重构用云端，涉及公司敏感业务代码一律切本地。这个规则固定下来之后，我基本不会再出现"用错模型"的情况。

5.3 日常使用中的三条纪律

最后分享几个让我少踩坑的日常习惯。

第一条，别让模型猜上下文。WorkBuddy 能读取当前打开的文件，但你要明确告诉它关注哪个文件、解决什么问题。我自己写 prompt 的固定结构是"项目背景一句话 + 我要做什么 + 约束条件"。背景信息越清晰，代码生成质量越高，也能少烧 token。

第二条，定期清理会话上下文。长会话会让上下文越塞越满，一方面是 token 消耗直线上升，另一方面是模型注意力被无关内容稀释，回答质量下降。我的习惯是每个任务开启新会话，最长不超过二十轮对话。

第三条，密钥永远不要写死在代码里。配置文件里的 apiKey 我后来全部换成了环境变量引用，比如在终端设置export WORKBUDDY_DEEPSEEK_KEY=sk-xxx，然后在配置文件里用${WORKBUDDY_DEEPSEEK_KEY}引用。这样即使配置文件被误分享，也不会泄露密钥。

折腾完自定义模型接入，我最大的感受是：AI 编程助手的能力边界，其实有一半掌握在使用者手里。官方模型很好，但未必适合每一个场景和每一条数据边界要求；接自定义模型的过程看着麻烦，可是一旦跑通，你会获得一种"工具真正归我管"的控制感。

最后再分享一个小细节：如果你的 WorkBuddy 配置了本地 Ollama 模型，建议在系统登录项里把 Ollama 设置为开机自启，免得每天早上打开 WorkBuddy 发现连不上本机模型，还要手动敲一次ollama serve。这种小坑藏不住，只有天天用的人才能发现。