1. 为什么我要认真写这篇 WorkBuddy 实战指南

第一次打开 WorkBuddy 的时候，我以为它就是个套壳的对话工具，跟市面上那些"AI 工作台"没什么本质区别。直到我在一个真实项目里，用它把一套原本需要三天才能跑完的数据清洗加报告生成流程压缩到四十分钟，我才意识到这东西的定位跟普通聊天机器人完全不是一回事。WorkBuddy 是腾讯推出的一款 AI 工作台产品，核心能力是把 AI Agent 真正落到日常工作任务里，而不是停留在"你问我答"的层面。它支持自定义模型配置、Skill 扩展、MCP 协议接入、本地化部署，甚至能通过规则设定让 AI 记住你的工作习惯并持续生效。

这篇内容适合三类人看：第一类是刚听说 WorkBuddy、想搞清楚它到底能干什么的新手；第二类是已经装了但卡在配置环节、被 models.json 和各种缓存目录折腾得够呛的中间用户；第三类是想把 WorkBuddy 接入自己团队工作流、做私有化部署的技术负责人。我会从安装讲到避坑，把自定义模型配置、Skill 选择、规则设定、缓存迁移、本地部署这些高频问题全部拆开讲透。文中涉及的具体参数和路径，一部分来自官方文档，一部分是我自己反复试错总结出来的，你照着抄作业基本不会翻车。

需要提前说明的是，WorkBuddy 和 CodeBuddy 虽然名字像兄弟，但定位差别很大。CodeBuddy 更偏向代码补全和编程辅助，WorkBuddy 则是面向通用工作任务的 AI 工作台，能处理文档、数据、流程编排、网页生成等更宽泛的场景。搞清楚这个区别，你才不会在选型的时候走弯路。

2. 安装前的准备工作与版本选择

2.1 先搞清楚你要装哪个版本

WorkBuddy 目前有网页版、桌面客户端和国际版几个入口。网页版最省事，打开浏览器就能用，适合快速体验和轻量任务。桌面客户端在文件读写、本地 Skill 调用、缓存管理上更灵活，适合需要处理本地文件的场景。国际版在模型接入和部分功能上有差异，如果你有海外团队协作需求可以关注，但日常国内使用网页版加桌面端组合基本够用。

我个人的建议是：新手先用网页版跑通一个完整任务流程，确认这个工具的工作方式符合你的预期，再去装桌面端。很多人一上来就折腾本地部署，结果卡在环境依赖上，还没体验到核心功能就放弃了，这是最不划算的路径。

2.2 系统环境与依赖检查

桌面端支持 Windows、macOS 和 Linux。Linux 用户需要注意，官方提供的安装包对发行版有一定要求，主流发行版基本没问题，但如果你用的是比较冷门的发行版，可能需要手动处理依赖。安装前建议确认几件事：

• 磁盘剩余空间至少留 5GB，WorkBuddy 的缓存和模型配置文件会占用一定空间，尤其是你后续要改缓存目录的话，提前规划好盘符。
• 网络环境要能正常访问模型服务接口，如果你打算接自定义模型，提前把 API 端点和密钥准备好。
• 如果你计划用 Docker 部署，确认 Docker 版本在 20.10 以上，避免容器网络配置出问题。

提示：安装路径尽量不要选带中文或空格的目录，这在后续配置 models.json 和 Skill 路径时能省掉一堆转义和编码问题。

2.3 安装过程中的关键选择

安装向导里会有几个选项容易让人犹豫。一个是是否开机自启，如果你只是偶尔用，建议关掉，减少后台资源占用。另一个是默认缓存目录，Windows 默认在 C 盘用户目录下，如果你的 C 盘空间紧张，这一步就要留意，后面我会专门讲怎么迁移到 D 盘。还有一个是是否加入体验计划，这个看个人偏好，加入的话能提前用到新功能，但稳定性可能略差。

安装完成后第一次启动，WorkBuddy 会引导你做基础配置，包括登录、选择默认模型、设置工作区目录。工作区目录建议单独建一个文件夹，不要跟系统目录混在一起，方便后续备份和迁移。

3. 自定义模型配置：models.json 到底怎么写

3.1 为什么需要自定义模型

WorkBuddy 内置了默认模型，但实际工作中你会发现，不同任务对模型的要求差别很大。写文献综述可能需要长上下文和强推理能力，做数据提取可能更看重速度和成本，生成网页又可能需要代码能力强的模型。自定义模型配置就是让你按任务切换不同模型，而不是被一个默认模型绑死。

models.json 是 WorkBuddy 用来管理模型配置的核心文件。它的结构不复杂，但字段含义和填写规则有几个坑，我第一次配的时候因为一个字段名写错，排查了快一个小时。

3.2 models.json 的字段结构与填写要点

一个典型的 models.json 配置包含模型名称、API 端点、密钥、上下文长度、最大输出 token 等字段。下面是一个参考结构：

{ "models": [ { "name": "my-reasoning-model", "provider": "custom", "endpoint": "https://your-api-endpoint/v1/chat/completions", "apiKey": "your-api-key", "contextLength": 128000, "maxOutputTokens": 8192, "temperature": 0.7 } ] }

几个关键点需要说明。contextLength要跟你实际使用的模型能力匹配，填大了会导致请求被拒，填小了浪费模型能力。maxOutputTokens直接影响单次回复的长度上限，如果你要做长文生成，这个值不能太小。temperature控制输出的随机性，做数据提取建议调低到 0.2 左右，做创意生成可以调到 0.8 以上。

注意：apiKey 不要直接明文写在会被同步或分享的文件里。如果团队协作，建议用环境变量引用，WorkBuddy 支持在配置里写占位符然后从环境变量读取。

3.3 配置生效与验证方法

改完 models.json 后，需要重启 WorkBuddy 或者在设置里手动触发配置重载。验证是否生效最简单的方法是新建一个对话，在模型选择列表里看有没有出现你配置的模型名称。如果没出现，先检查 JSON 格式是否合法，可以用在线 JSON 校验工具过一遍。如果格式没问题但还是不显示，检查文件路径是否放对了，WorkBuddy 对配置文件的存放位置有约定，放错目录它读不到。

我踩过的一个坑是：配置文件里用了中文引号，肉眼看着跟英文引号几乎一样，但解析直接失败。所以写完配置后，务必用工具校验，别靠肉眼。

4. Skill 系统与规则设定：让 WorkBuddy 真正懂你

4.1 Skill 是什么，哪些值得优先装

Skill 可以理解为 WorkBuddy 的能力插件。装了什么 Skill，它就能做什么类型的事。比如跨对话记忆 Skill 能让它在不同对话之间记住你的偏好，网页生成 Skill 能让它直接产出可发布的页面，文献综述 Skill 能帮你快速整理研究资料。

新手优先装的 Skill 我推荐这几个：跨对话记忆（解决"每次都要重新解释背景"的问题）、文件处理（读写本地文档）、网页生成（做展示页或简单站点）。这几个覆盖了最高频的需求，装完就能明显感觉到效率提升。至于更专业的 Skill，等你明确知道自己要做什么任务了再按需装，装太多反而会让启动变慢、选择困难。

4.2 给 WorkBuddy 定规则的正确姿势

规则设定是 WorkBuddy 最被低估的功能。你可以给它定几条规则，后续对所有任务都生效，相当于给它立了一套工作守则。比如"所有输出先给结论再给理由"、"涉及数据必须标注来源"、"代码块必须标注语言类型"，这些规则一旦设定，它每次都会遵守。

设定规则的位置在设置里的自定义指令区域。写规则有几个技巧：一是要具体，不要写"回答好一点"这种模糊要求；二是要可执行，规则应该是它能明确判断是否遵守的；三是不要太多，五到八条足够，太多规则会互相冲突，反而让它无所适从。

我自己的规则里有一条是"不确定的信息必须明确说不确定，不要编造"，这条极大降低了它胡编乱造的概率。另一条是"长任务先列步骤再执行"，这样我能在它动手之前就发现方向对不对。

4.3 MCP 与 Skill 的配合使用

MCP 协议让 WorkBuddy 能接入外部工具和数据源。你可以把它理解成给 WorkBuddy 开了更多"接口"，让它能调用外部服务完成更复杂的任务。MCP 和 Skill 配合使用，能实现一些单靠内置功能做不到的流程，比如自动从某个数据源拉数据、处理后生成报告、再发布到指定位置。

配置 MCP 需要对协议有一定了解，建议先跑通官方示例，确认链路通了再改造成自己的场景。直接上手改复杂配置，出问题时很难定位是协议层还是业务层的问题。

5. 缓存目录迁移与本地化部署实操

5.1 把系统缓存目录改到 D 盘

C 盘空间紧张是很多人的痛点，WorkBuddy 的缓存目录默认在系统盘，用久了会占不少空间。迁移方法分几步：先关闭 WorkBuddy，找到默认缓存目录，把里面的内容整体复制到 D 盘目标目录，然后修改配置文件里的缓存路径指向新位置，最后重启验证。

关键坑点在于：不要只改配置不迁移数据，否则历史缓存丢失可能导致部分功能异常。另外，迁移后要确认新目录有读写权限，Windows 下有时候需要手动给目录授权。改完之后跑一个稍微重一点的任务，观察新目录下有没有正常生成缓存文件，确认迁移成功。

5.2 本地化部署与私有化部署的差异

本地化部署是把 WorkBuddy 装在你自己的机器上，数据不出本地，适合对数据敏感的个人或小团队。私有化部署则是部署在你自己的服务器上，供团队多人使用，需要考虑并发、权限、存储等问题。

Docker 部署是私有化比较省心的方式。用 Docker 装 WorkBuddy，环境依赖都被打包好了，不用手动折腾。但要注意容器和宿主机的目录映射，缓存目录、配置文件目录、工作区目录都要正确映射出来，否则容器一重启数据就没了。

Linux 部署的话，安装包和依赖要提前准备好，尤其是如果你的服务器不能直接访问外网，需要离线准备依赖包。这一步最容易卡住，建议提前列好依赖清单，逐个确认。

5.3 部署后的安全审核要点

不管是本地还是私有化部署，安全审核都不能省。重点检查几项：API 密钥是否明文暴露在配置文件里、缓存目录权限是否过宽、对外暴露的端口是否有访问控制、日志里是否记录了敏感信息。私有化部署还要考虑多用户之间的数据隔离，避免 A 用户的任务数据被 B 用户看到。

提示：私有化部署时，建议把模型调用和业务数据分开管理，模型密钥集中配置，业务数据按用户隔离，这样即使某一环出问题，影响范围也可控。

6. 常见问题与避坑经验实录

6.1 安装与启动类问题

6.2 配置类问题

models.json 不生效是最常见的问题。排查顺序是：先校验 JSON 格式，再确认文件路径，然后检查字段名拼写，最后看是否需要重启或重载。我遇到过一次是字段名大小写写错了，JSON 本身合法，但 WorkBuddy 读不到那个字段，表现就是模型列表里没有新模型。

缓存目录改了但没生效，通常是配置文件没保存成功，或者改的是错误的配置文件。WorkBuddy 可能有多个层级的配置，要确认你改的是生效的那一层。

6.3 使用类问题

跨对话记忆不生效，先确认 Skill 是否真的装上了，再确认规则里有没有跟记忆冲突的设定。有时候是规则写得太死，把记忆功能覆盖了。

生成网页发布失败，检查生成目录是否有写权限，以及发布目标是否可达。如果是本地发布，确认本地服务是否正常启动。

积分消耗异常快，通常是模型选择不当或任务拆分不合理。长任务建议拆成多个小任务分别执行，避免单次请求上下文过大导致 token 消耗飙升。

6.4 我踩过的几个典型坑

第一个坑是规则写太多。我一开始给 WorkBuddy 定了十几条规则，结果它执行任务时经常顾此失彼，输出质量反而下降。后来精简到六条，效果明显好转。规则不在多，在于每条都清晰可执行。

第二个坑是 Skill 装太杂。装了一堆 Skill 之后，启动变慢不说，它有时候会选错 Skill 来处理任务。后来我只留了高频使用的几个，需要时再临时装，整体体验顺畅很多。

第三个坑是缓存目录迁移后没验证。迁移完以为搞定了，结果过了几天发现某些历史记录丢失，回头查才发现是迁移时漏了一部分文件。迁移这种事，一定要迁移完立刻验证，别拖。

7. 从入门到精通的进阶路径建议

如果你已经跑通了基础流程，想进一步提升，我建议按这个顺序推进：先把规则体系打磨好，这是投入产出比最高的一步；然后精选 Skill，把高频任务固化下来；接着配置自定义模型，按任务类型分配不同模型；最后再考虑 MCP 接入和私有化部署这些进阶能力。

WorkBuddy 和 CodeBuddy 的配合也值得研究。CodeBuddy 负责代码层面的辅助，WorkBuddy 负责工作流编排和任务执行，两者结合能覆盖从写代码到跑流程的完整链路。至于 WorkBuddy、Trae Work 这类工具哪个更好用，我的看法是没有绝对优劣，关键看你的任务类型和团队习惯，建议都花半天时间实际跑一个真实任务，体感比看评测准得多。

最后分享一个我自己的小习惯：每次用 WorkBuddy 处理完一个重要任务，我会把当时的规则、Skill 组合、模型配置记一笔，形成自己的"配方库"。下次遇到类似任务，直接套配方，省掉重新调试的时间。这个习惯坚持下来，你会发现自己对 AI 工作台的理解会越来越深，用起来也越来越顺手。