1. 为什么我要认真写这篇 WorkBuddy 实战指南第一次接触 WorkBuddy 是在一个周五的深夜当时团队里有个紧急需求——要把一批散落在不同文档里的产品资料整理成结构化的知识库。手动做至少得两天我抱着试试看的心态打开了这个腾讯出的 AI 工作台结果四十分钟就搞定了。从那天起我开始系统性地研究它踩了不少坑也积累了一些文档里不会写的经验。WorkBuddy 是腾讯推出的一款 AI 工作台产品核心定位是让 AI Agent 真正参与到日常工作任务中而不只是聊聊天。它支持自定义模型配置、Skill 技能扩展、MCP 协议对接、跨对话记忆等能力可以通过 models.json 配置文件灵活切换底层模型。适合谁用我的判断是三类人一是需要处理大量重复性文档工作的职场人二是想从零搭建 AI Agent 但不想写太多代码的技术爱好者三是已经在用 CodeBuddy 做开发、想进一步把 AI 能力延伸到非编码场景的开发者。这篇文章不讲虚的我会从安装部署开始把自定义模型配置、Skill 选择、规则设定、缓存目录迁移、常见报错排查这些环节全部拆开讲清楚。每个步骤我都会解释为什么这么做以及我实际踩过哪些坑。文章内容基于我自己的使用经验和社区里高频出现的问题整理不同版本界面可能有差异但核心逻辑是通的。2. 安装部署从下载到第一次跑通2.1 版本选择与下载渠道WorkBuddy 目前有国内版和国际版两个分支。国内版直接走腾讯官方渠道下载国际版在功能上有一些差异主要体现在模型接入的灵活度和部分 Skill 的可用性上。我的建议是如果你主要处理中文内容、团队协作也在国内直接用国内版就行省去很多配置上的麻烦。如果你需要接入一些特定的海外模型服务再考虑国际版。下载的时候注意操作系统匹配。Windows 用户直接拿 exe 安装包macOS 用户拿 dmgLinux 用户目前有 AppImage 和 deb 两种格式。Linux 安装包在社区里讨论得比较多因为有些发行版的依赖库版本对不上后面我会专门讲。注意不要从第三方网盘或者来路不明的链接下载安装包。我见过有人从所谓“保姆级教程网盘”里拿到的包被篡改过装完弹广告。认准官方渠道这一步省不得。安装过程本身不复杂一路下一步就行。但有一个细节值得注意安装路径尽量不要选 C 盘默认目录。原因后面讲缓存目录迁移的时候会详细说简单讲就是 WorkBuddy 运行过程中会产生大量缓存文件包括对话历史、模型响应缓存、Skill 运行日志等这些东西膨胀起来很占空间。2.2 Linux 环境下的安装要点Linux 用户这里多说几句。如果你用的是 Ubuntu 22.04 或更新版本deb 包直接 dpkg 安装基本没问题。但如果你用的是 Fedora、Arch 或者一些滚动更新的发行版可能会遇到 glibc 版本不兼容的问题。我的做法是优先用 AppImage它把依赖都打包进去了兼容性最好。# 下载 AppImage 后赋予执行权限 chmod x WorkBuddy-*.AppImage # 直接运行 ./WorkBuddy-*.AppImage如果 AppImage 跑不起来检查一下 FUSE 是否安装。很多最小化安装的 Linux 发行版默认不带 FUSE装一下就好# Ubuntu/Debian 系 sudo apt install libfuse2 # Fedora 系 sudo dnf install fuse还有一个常见问题是无头服务器上跑 WorkBuddy。虽然它主要是桌面端产品但有人想在服务器上做本地化部署然后通过 Web 界面访问。这种场景下你需要额外配置虚拟显示或者用 VNC纯命令行是跑不起来的。如果你确实需要服务器端部署建议关注官方是否有 Web 版或者 Docker 方案社区里有人尝试过 Docker 安装 WorkBuddy但截至我写这篇文章时还不是官方支持的方式稳定性存疑。2.3 首次启动的初始化配置第一次打开 WorkBuddy它会引导你做几件事登录账号、选择默认模型、设置工作目录。登录没什么好说的扫码或者账号密码都行。重点说后面两个。默认模型的选择直接影响你后续的使用体验。如果你不确定选哪个我的建议是先选一个通用的对话模型跑通流程后面再通过 models.json 自定义配置来精细调整。工作目录的设置很关键——它决定了 WorkBuddy 默认从哪里读取文件、把生成的内容存到哪里。我习惯单独建一个目录比如~/WorkBuddyWorkspace里面再按项目分子目录这样不同任务的产出不会混在一起。初始化完成后建议先跑一个简单的任务测试一下比如让它读一个本地文档然后总结要点。这一步的目的是确认模型连接正常、文件读写权限没问题。如果这一步就报错后面的事情都不用谈了先排查基础环境。3. 自定义模型配置models.json 到底怎么写3.1 models.json 的核心结构WorkBuddy 的自定义模型配置是通过 models.json 文件实现的。这个文件的位置通常在用户配置目录下Windows 在%APPDATA%/WorkBuddy/下面macOS 和 Linux 在~/.config/WorkBuddy/或者~/.workbuddy/下面具体路径可以在设置里查看。这个文件的基本结构是一个 JSON 对象里面定义一个或多个模型配置。每个配置包含模型名称、API 端点、API Key、模型标识符、最大 token 数等字段。我见过很多人第一次写这个文件的时候被 JSON 格式坑了——多一个逗号、少一个引号都会导致解析失败WorkBuddy 启动时直接报错。{ models: [ { name: my-custom-model, provider: openai-compatible, baseUrl: https://api.example.com/v1, apiKey: sk-xxxxxxxxxxxx, modelId: gpt-4-turbo, maxTokens: 4096, temperature: 0.7 } ] }上面是一个最简化的配置示例。实际使用中你可能需要配置多个模型比如一个用于快速对话的小模型一个用于复杂推理的大模型。WorkBuddy 支持在对话时切换模型所以多配几个没坏处。3.2 参数选择的逻辑temperature这个参数值得单独说一下。它控制模型输出的随机性范围通常是 0 到 2。做文档总结、代码生成这类需要确定性输出的任务时我一般设 0.3 到 0.5做创意写作、头脑风暴的时候可以调到 0.8 到 1.2。很多人忽略这个参数结果同一个 prompt 每次输出差异很大还以为是模型不稳定。maxTokens的设置要看你的具体任务。如果只是日常对话2048 足够了如果要让它读长文档然后输出详细分析至少设 4096有些模型支持到 8192 甚至更高。但注意maxTokens 设得越大单次请求的消耗也越大如果你的 API 是按 token 计费的这个数字直接关系到成本。baseUrl的填写有个坑有些服务商要求 URL 末尾带/v1有些不带。填错了会报 404。我的经验是先看服务商的文档如果文档里给的示例是https://api.xxx.com/v1/chat/completions那 baseUrl 就填https://api.xxx.com/v1如果示例是https://api.xxx.com/chat/completions那 baseUrl 就填https://api.xxx.com。WorkBuddy 会自动在 baseUrl 后面拼接/chat/completions。3.3 配置生效与验证改完 models.json 之后需要重启 WorkBuddy 才能生效。重启后在设置里的模型列表应该能看到你新加的模型。如果没看到检查两个地方一是 JSON 格式是否正确可以用在线的 JSON 校验工具过一遍二是文件路径是否放对了有些版本对路径大小写敏感。验证模型是否真正可用最简单的办法是新建一个对话选择你配置的模型然后发一句“你好”。如果正常回复说明配置成功。如果报错错误信息通常会告诉你具体原因比如 401 是 API Key 不对404 是 URL 不对429 是请求频率超限。实操心得我习惯在 models.json 里给每个模型加一个注释字段虽然标准 JSON 不支持注释但 WorkBuddy 的解析器通常能容忍_comment这样的字段记录这个模型的用途和配置日期。过几个月回头看能省很多回忆的时间。4. Skill 系统哪些值得装哪些是坑4.1 Skill 的本质与运行机制WorkBuddy 的 Skill 可以理解成给 AI Agent 装的“插件”或“技能包”。每个 Skill 定义了一组特定的能力比如读写本地文件、调用外部 API、执行代码、生成网站等。当你在对话中提出的需求匹配到某个 Skill 的能力范围时WorkBuddy 会自动调用它来完成任务。这个机制的核心价值在于它让 AI 从“只会说”变成“能动手”。比如你让它“把这个文件夹里的所有 Markdown 文件合并成一个”如果没有文件操作 Skill它只能告诉你“你可以用 cat 命令合并”有了 Skill它直接帮你执行。Skill 的运行是在本地沙箱环境里进行的理论上不会影响系统其他部分。但实际使用中某些 Skill 的权限边界比较模糊比如文件读写 Skill 默认能访问的目录范围、网络请求 Skill 能访问的域名白名单等这些都需要你在设置里仔细检查。4.2 高频 Skill 推荐与选择逻辑根据我的使用经验下面这几个 Skill 是优先级最高的Skill 名称用途推荐指数文件操作读写本地文件、批量处理文档必装代码执行运行 Python/Shell 脚本必装网页抓取获取网页内容并解析按需网站生成从描述生成静态网站并发布按需跨对话记忆在不同对话间保持上下文强烈推荐MCP 对接连接外部 MCP 服务进阶用户跨对话记忆这个 Skill 我要特别说一下。默认情况下WorkBuddy 的每个对话是独立的你在 A 对话里告诉它的规则到 B 对话里它就忘了。跨对话记忆 Skill 解决了这个问题它把重要的上下文信息持久化存储后续对话可以读取。这对于需要长期跟进的项目非常有用。MCP Skill 是进阶玩法。MCP 是一种协议标准让 AI Agent 能够连接外部的工具和数据源。如果你有自己的内部系统或者常用的第三方服务支持 MCP通过这个 Skill 可以把它们接入 WorkBuddy。配置过程稍微复杂一些需要填写服务地址和认证信息但一旦配好能力边界会大大扩展。4.3 Skill 冲突与性能问题装太多 Skill 不一定好。我遇到过两个 Skill 同时想处理同一个请求的情况结果互相干扰任务执行失败。比如文件操作 Skill 和代码执行 Skill 都能读写文件当你说“读取这个文件并统计行数”时两个 Skill 可能同时被触发。解决办法是在设置里调整 Skill 的优先级或者在使用时明确指定用哪个 Skill。WorkBuddy 支持在对话中用skill名称的方式强制指定这个技巧很实用。另外每个 Skill 在后台运行都会占用一定的内存和 CPU。如果你发现 WorkBuddy 变卡了先检查是不是装了太多不常用的 Skill。我的做法是只保留当前项目需要的 Skill其他的一律禁用用的时候再开。5. 规则设定与自定义指令让 WorkBuddy 真正懂你5.1 全局规则与项目规则的区别WorkBuddy 支持两种层级的规则设定全局规则和项目规则。全局规则对所有对话生效项目规则只对特定工作目录下的对话生效。这个设计很合理因为不同项目的需求差异很大。全局规则适合放一些通用的偏好比如“回答用中文”、“代码块标注语言类型”、“不要用 emoji”。项目规则则放跟具体任务相关的指令比如“这个项目的文档统一用 Markdown 格式”、“所有输出文件放在 output 子目录下”。我见过有人把所有规则都塞进全局结果换个项目就各种不兼容。正确的做法是全局只放真正通用的项目相关的全部放项目规则里。5.2 规则撰写的技巧写规则不是写作文越简洁明确越好。我总结了几条原则第一用肯定句而不是否定句。说“输出用 Markdown 格式”比说“不要用纯文本”更有效。模型对否定指令的理解往往不如肯定指令准确。第二规则要具体可执行。“回答要详细”这种规则等于没写什么叫详细改成“每个技术点至少解释三段包含原理、操作步骤和注意事项”才有可操作性。第三规则数量控制在 10 条以内。太多了模型记不住而且规则之间可能冲突。如果确实有很多要求考虑拆分成多个项目规则按场景切换。下面是我自己常用的一套全局规则供参考1. 所有回答使用中文技术术语保留英文原文并附中文解释 2. 代码块必须标注语言类型 3. 涉及操作步骤时按顺序编号每步说明操作意图 4. 不确定的信息明确标注“不确定”不要编造 5. 输出文件默认保存到当前工作目录的 output 子目录5.3 规则不生效的排查规则写了但不生效最常见的原因是规则文件没有正确加载。检查设置里的规则列表确认你的规则显示为“已启用”。如果规则是在项目级别设置的确认当前对话的工作目录是否正确。另一个原因是规则之间冲突。比如你同时写了“回答简洁”和“每个点详细解释”模型就不知道该听哪个。这种情况下WorkBuddy 通常会优先执行更具体的规则但不同版本行为可能不一致最好的办法还是避免冲突。6. 缓存目录迁移与空间管理6.1 为什么需要迁移缓存目录WorkBuddy 运行一段时间后缓存目录会变得非常大。我自己的使用记录是重度使用两周缓存占了将近 8GB。这些缓存包括对话历史、模型响应缓存、Skill 运行日志、临时文件等。如果你的 C 盘空间紧张迁移缓存目录是必须的。6.2 迁移的具体操作WorkBuddy 的设置里通常有一个“缓存目录”或“数据目录”的选项可以直接修改路径。改完之后需要重启它会把现有缓存迁移到新位置。如果设置里没有这个选项可以通过修改配置文件来实现。Windows 下配置文件通常在%APPDATA%/WorkBuddy/config.json找到cacheDir字段改成你想要的路径比如D:/WorkBuddyCache。macOS 和 Linux 类似在~/.config/WorkBuddy/config.json里改。注意改路径之前先把 WorkBuddy 完全退出包括后台进程。否则迁移过程中可能有文件被占用导致迁移不完整。如果配置文件里没有cacheDir字段可以手动加上。格式是{ cacheDir: D:/WorkBuddyCache }改完之后重启去新目录下看看有没有文件生成。如果有说明迁移成功。原来的缓存目录可以删掉释放空间但建议先保留几天确认没问题再删。6.3 缓存清理策略除了迁移定期清理也很重要。WorkBuddy 设置里一般有“清理缓存”的按钮但它的清理范围有限主要清临时文件。对话历史和 Skill 日志需要手动清理。我的做法是每月做一次清理先备份重要的对话记录导出为 Markdown然后删除三个月前的对话历史和日志文件。这样既能释放空间又不会丢失重要信息。7. 常见问题与排查技巧实录7.1 启动类问题问题一启动后白屏或卡在加载界面。这个问题的原因通常有三个缓存损坏、模型配置错误、网络连接问题。排查顺序是先清缓存重启如果不行检查 models.json 是否有语法错误最后确认网络能正常访问模型服务。问题二Linux 下报错error while loading shared libraries。这是依赖库缺失。用ldd命令查看具体缺哪个库然后安装对应的包。AppImage 版本一般不会有这个问题如果遇到了试试用--no-sandbox参数启动。7.2 模型调用类问题问题三模型回复超时或中断。先检查网络然后看 maxTokens 是不是设得太大了。有些模型服务对单次请求的 token 数有限制超了会直接断开。另外temperature 设得太高也可能导致输出不稳定。问题四API Key 明明是对的但报 401。检查 API Key 有没有多余的空格或换行。从网页复制的时候经常会把换行符也复制进去。另外确认这个 Key 有没有过期有些服务商的 Key 有有效期。7.3 Skill 运行类问题问题五Skill 执行到一半卡住。大概率是 Skill 在等待某个外部响应比如网络请求超时。去设置里把该 Skill 的超时时间调短一些或者检查网络连接。如果频繁出现考虑换个 Skill 实现方式。问题六文件操作 Skill 报“权限不足”。WorkBuddy 的文件操作 Skill 默认只能访问工作目录及其子目录。如果你想让它操作工作目录之外的文件需要在设置里把那个目录加到允许列表里。这是安全设计不建议随意放开。7.4 性能类问题问题七WorkBuddy 越用越卡。先看内存占用如果超过 2GB大概率是缓存太多或者 Skill 泄漏。清缓存、禁用不用的 Skill、重启三步走。如果还不行检查是不是同时开了多个对话在跑任务WorkBuddy 的并发处理能力有限同时跑太多任务会互相拖慢。问题八生成网站发布后打不开。检查生成的 HTML 文件路径是否正确以及发布目标目录是否有写入权限。如果是发布到本地服务器确认服务器在运行。如果是发布到外部平台检查网络和认证信息。8. 一些进阶玩法和个人体会8.1 WorkBuddy 与 CodeBuddy 的配合使用CodeBuddy 是腾讯另一款面向开发者的 AI 编程助手和 WorkBuddy 的定位不同但可以互补。我的用法是用 CodeBuddy 写代码和调试用 WorkBuddy 做文档整理、需求分析和项目管理工作。两者共享一些底层能力但界面和交互方式差异较大各取所长。有人问能不能用 WorkBuddy 替代 CodeBuddy 做开发我的答案是简单脚本可以复杂项目还是 CodeBuddy 更顺手。WorkBuddy 的代码执行 Skill 更适合跑一些数据处理脚本而不是完整的开发工作流。8.2 从零搭建 AI Agent 的思路WorkBuddy 本身就是一个 AI Agent 平台但如果你想基于它搭建更定制化的 Agent核心工作是三件事定义 Agent 的角色和能力边界、配置对应的 Skill 组合、编写清晰的规则和指令。这三件事做好了一个能处理特定领域任务的 Agent 就成型了。我试过用 WorkBuddy 搭了一个专门处理文献综述的 Agent配置了网页抓取 Skill 用来收集资料文件操作 Skill 用来管理参考文献跨对话记忆 Skill 用来保持上下文再加上一套详细的规则定义输出格式。实测下来写一篇中等篇幅的文献综述效率比手动做提升了至少三倍。8.3 安全审核与私有化部署的考量WorkBuddy 有安全审核机制会对输入输出内容做过滤。这个机制的具体规则官方没有完全公开但根据我的使用经验它主要拦截明显违规的内容。正常的工作任务不会触发。私有化部署是很多团队关心的问题。目前 WorkBuddy 的私有化部署方案主要面向企业客户个人用户用标准版就行。如果你确实有私有化需求建议直接联系官方渠道了解具体方案和报价。8.4 积分系统与成本控制WorkBuddy 有积分系统某些高级功能或者模型调用需要消耗积分。积分的获取方式包括每日签到、完成任务、邀请好友等。如果你用的是自己的 API Key 配置模型那部分消耗走的是你自己的 API 账户不扣 WorkBuddy 积分。成本控制的核心是合理选择模型。简单任务用便宜的小模型复杂任务再用大模型。另外maxTokens 不要无脑设大按实际需要设置。我自己的经验是大部分日常任务用 2048 的 maxTokens 足够了只有处理长文档时才需要调到 4096 以上。8.5 跨对话记忆 Skill 的实战配置跨对话记忆 Skill 是我用得最多的 Skill 之一。配置要点是设置一个记忆存储目录定义哪些信息需要持久化比如项目背景、用户偏好、重要决策以及记忆的过期策略。我的配置是记忆文件存在工作目录的.memory子目录下每次对话开始时自动加载最近 30 天的记忆超过 30 天的归档。这样既能保持上下文连贯又不会让记忆文件无限膨胀。实际使用中有一个坑如果记忆文件太大每次对话加载会变慢。所以定期清理和归档很重要。我一般每周整理一次记忆文件把不再需要的信息删掉。8.6 给 WorkBuddy 定规则的实战案例最后分享一个我给 WorkBuddy 定规则的实际案例。我们团队用 WorkBuddy 做技术文档的初稿撰写我定的项目规则是这样的1. 所有技术文档使用 Markdown 格式标题层级不超过三级 2. 每个技术概念必须包含定义、使用场景、操作步骤、注意事项 3. 代码示例必须可运行标注语言类型和依赖版本 4. 不确定的技术细节标注“待确认”不要编造 5. 输出文件命名格式文档主题-版本号-日期.md 6. 每篇文档末尾附上参考链接列表这套规则跑了三个月产出的文档质量很稳定。新加入的同事直接套用这套规则也能快速上手。规则的力量在于它把隐性的经验变成了显性的指令让 AI 的输出有了可预期的标准。如果你也在用 WorkBuddy我的建议是不要一上来就追求大而全的配置。先把基础流程跑通然后根据实际遇到的问题逐步调整。每个团队、每个人的工作习惯不同适合我的配置不一定适合你。多试、多改、多总结慢慢就能找到最顺手的用法。