1. 为什么我要认真聊聊 WorkBuddy 这个 AI 工作台第一次看到 WorkBuddy 这个名字是在一个做企业数字化的朋友群里。有人甩了张截图说“腾讯出了个 AI 工作台能直接调 Agent 干活”底下立刻有人接话问“跟 CodeBuddy 啥关系”“是不是又一个套壳”。我当时没太在意直到后来连续有三四个读者私信问我同一个问题WorkBuddy 到底怎么装、怎么配、怎么让它真正跑起来而不是停在演示阶段。这就值得写一篇了。市面上关于 AI Agent 的内容大多停在“概念很美好”的层面真正落到安装、配置、Skill 编写、缓存目录迁移这些脏活累活的少之又少。而 WorkBuddy 恰恰是一个“装完只是开始配好才算入门”的工具。它的核心价值在于把 AI Agent 的能力封装成一个可操作的工作台让你能用自然语言驱动任务也能用 Skill 把重复劳动固化下来。适合谁看三类人一是想把 AI 真正嵌进日常工作流的产品和运营二是想从零搭一个 Agent 练手的开发者三是被各种“AI 中台”概念绕晕、想找个具体东西上手的技术管理者。我前后在 Windows 和 Linux 两套环境里折腾了 WorkBuddy踩过的坑包括但不限于models.json 配错导致模型列表空白、Skill 脚本路径写死导致换机器就崩、系统缓存目录默认塞在 C 盘把系统盘撑爆。这些经验文档里不会写但实际用起来一个都躲不掉。下面我把从安装到避坑的完整链路拆开讲尽量让你少走我走过的弯路。2. WorkBuddy 到底是什么和 CodeBuddy 差在哪2.1 一句话说清 WorkBuddy 的定位WorkBuddy 是腾讯推出的一款 AI 工作台产品核心思路是把大模型能力、Agent 调度、Skill 插件体系整合到一个桌面端界面里。你可以把它理解成一个“AI 任务的操作系统”左边是任务和会话中间是执行区右边是 Skill 和工具链。它不是一个单纯的聊天窗口而是一个能调用外部工具、执行多步任务、并且允许你自定义 Skill 的工作环境。和市面上很多“AI 助手”最大的区别在于WorkBuddy 把 Skill 作为一等公民。Skill 可以是一个脚本、一段提示词模板、一个 API 调用封装甚至是一个完整的子 Agent。你写好一个 Skill它就能在后续所有任务里被复用。这个设计思路和 Claude Code 的 Skill、Codex 的 Skill 体系是一脉相承的本质上都是在解决“如何让 AI 记住并复用一套固定流程”的问题。2.2 WorkBuddy 和 CodeBuddy 的关系与区别这是被问得最多的问题。简单说CodeBuddy 更偏向代码场景定位是 AI 编程助手围绕代码补全、代码审查、项目理解展开。WorkBuddy 的覆盖面更宽它不局限于写代码而是面向通用工作任务比如文档处理、数据分析、流程自动化、网站生成等。两者在底层可能共享部分模型调度和 Agent 框架但面向的使用场景和交互形态不同。如果你主要写代码CodeBuddy 的针对性更强如果你要处理的是跨工具、跨平台的综合任务WorkBuddy 的工作台形态更合适。实际使用中很多人是两个都装按任务类型切换。我自己的习惯是纯编码任务走 CodeBuddy涉及多步骤、多工具协作的任务走 WorkBuddy。2.3 国际版和国内版的差异要点WorkBuddy 有国际版和国内版之分主要差异体现在模型接入、账号体系和部分功能可用性上。国内版对接的是国内可用的模型服务国际版则可能接入不同的模型供应商。对于普通用户来说最直接的影响是你手里的账号类型决定了你能用哪些模型而模型又决定了 Agent 的实际能力上限。我的建议是先确认自己的账号归属再去配 models.json。很多人装完之后发现模型列表是空的八成就是账号和模型配置对不上。这一点在后面讲 models.json 的时候会详细展开。3. 安装前的环境准备与版本选择3.1 Windows 和 Linux 的安装路径差异WorkBuddy 在 Windows 和 Linux 上的安装体验差别不小。Windows 版有图形化安装包双击下一步基本能完成但默认安装路径和缓存路径都在 C 盘这是后面要重点处理的问题。Linux 版更多是通过命令行或者包管理方式部署对权限和依赖的要求更明确。我在 Windows 上第一次装的时候没注意安装向导里的“自定义路径”选项结果整个工作台连同缓存全塞进了C:\Users\你的用户名\AppData下面。用了不到一周C 盘红了。后来重装时特意把主程序和缓存目录都指到了 D 盘才算消停。Linux 上相对好办装之前先规划好/opt或者用户目录下的独立分区即可。3.2 安装前必须确认的三件事第一确认你的账号类型和可用模型范围。这决定了你后面 models.json 怎么写。第二确认磁盘空间。WorkBuddy 本身不大但 Skill 运行产生的缓存、日志、临时文件会持续增长建议至少预留 20GB 以上的独立空间。第三确认网络环境能正常访问所需的模型服务接口这个不用多说装之前先测一下连通性。提示安装路径和缓存路径尽量放在同一块非系统盘上避免跨盘读写带来的性能损耗和权限问题。3.3 安装过程中的关键选项安装向导里有两个选项容易被忽略。一个是“是否创建桌面快捷方式”这个无所谓。另一个是“数据存储位置”这个非常关键。如果你在安装时没改后面就得手动迁移而手动迁移缓存目录是有风险的搞不好会丢配置。所以我的建议是第一次装就把它设对别给自己留后患。Linux 下如果是用脚本安装通常会有--data-dir之类的参数装之前先看一眼帮助文档把数据目录指定到你想放的位置。这个参数一旦设定后续所有 Skill 的缓存、日志都会跟着走省心很多。4. models.json 配置最容易翻车的一环4.1 models.json 的作用和结构models.json 是 WorkBuddy 的模型配置文件决定了工作台能调用哪些模型、每个模型的接口地址、鉴权方式、参数默认值等。它本质上是一个 JSON 数组每个元素描述一个模型接入点。结构大致包含模型名称、供应商标识、API 地址、密钥引用、上下文长度、是否支持工具调用等字段。这个文件的位置通常在 WorkBuddy 的数据目录下具体路径因安装方式而异。Windows 下一般在数据目录\config\models.jsonLinux 下在~/.workbuddy/config/models.json或你自定义的数据目录里。找不到的话在工作台设置里一般有“打开配置目录”的入口。4.2 配置模型的完整步骤第一步打开 models.json先看默认模板里有没有示例条目。有的话照着改比从零写要稳。第二步填入你的模型接入信息。这里最容易错的是 API 地址的格式有的要求带/v1有的不带写错了就是 404。第三步密钥不要直接明文写在文件里用环境变量引用WorkBuddy 支持${ENV_VAR}这种写法。第四步保存后重启工作台在模型列表里确认新模型是否出现。我踩过的一个坑是改完 models.json 没重启以为没生效反复改了好几遍最后发现是缓存问题。所以改完配置第一件事就是完全退出再重开别用“刷新”按钮那个不一定重载配置文件。4.3 模型配置常见错误对照表错误现象可能原因排查方法模型列表空白models.json 格式错误或路径不对用 JSON 校验工具检查语法确认文件路径调用返回 401密钥无效或未正确引用环境变量检查环境变量是否在当前会话生效调用返回 404API 地址路径写错对照供应商文档确认是否带/v1模型不响应工具调用该模型不支持 function calling换支持工具调用的模型或在配置里关闭工具能力响应极慢或超时上下文长度设置过大或网络问题调小 max_tokens检查网络连通性这张表是我自己遇到问题后整理的基本覆盖了 90% 的配置翻车场景。遇到问题先对表比盲目搜索快得多。5. Skill 体系WorkBuddy 真正的杀手锏5.1 Skill 是什么为什么它重要Skill 是 WorkBuddy 里可复用的能力单元。你可以把它想成一个“技能包”里面可以是一段固定的提示词、一个 Python 脚本、一次 API 调用的封装或者几者的组合。写好一个 Skill之后在任何任务里都能通过名称调用它不用每次重新描述需求。这个设计的价值在于“固化经验”。比如你有一套固定的周报生成流程拉数据、算指标、套模板、导出。以前你得每次跟 AI 重新说一遍现在把它写成一个 Skill以后一句话就能触发。Skill 越多工作台越懂你效率提升是复利式的。5.2 Skill 的编写规范与目录结构Skill 通常放在数据目录下的skills文件夹里每个 Skill 一个子目录目录名就是 Skill 的标识。目录里一般包含一个描述文件定义 Skill 名称、触发词、参数和一个执行文件脚本或提示词模板。描述文件的格式各版本略有差异但核心字段差不多name、description、parameters、entry。写 Skill 脚本时有几个硬性要求。第一脚本要有明确的输入输出约定别依赖全局状态。第二路径要用相对路径或环境变量别写死绝对路径否则换台机器就崩。第三脚本要有错误处理失败时返回清晰的错误信息方便排查。我见过太多 Skill 因为一个写死的路径在别人机器上直接报错。5.3 从零写一个 Skill 的实操示例假设我要做一个“把 Markdown 转成带样式的 HTML”的 Skill。第一步在 skills 目录下建一个文件夹比如md2html。第二步写描述文件定义 Skill 名称叫“Markdown 转 HTML”参数是输入文件路径和输出文件路径。第三步写一个 Python 脚本读取 Markdown用 markdown 库转换套上 CSS 模板写出 HTML。第四步在 WorkBuddy 里测试调用确认能正常执行。这个 Skill 写好后以后任何需要转 HTML 的场景直接说“用 Markdown 转 HTML 这个 Skill 处理 xxx.md”就行。这就是 Skill 的威力一次编写处处复用。5.4 Skill 开发中的避坑要点第一个坑是编码问题。Windows 下默认可能是 GBK脚本里读写文件一定要显式指定encodingutf-8否则中文内容会乱码。第二个坑是依赖缺失。Skill 脚本用到的第三方库要在描述文件里声明或者确保运行环境已安装。第三个坑是超时。复杂 Skill 执行时间长要设置合理的超时时间别让工作台一直卡着。注意Skill 脚本里不要硬编码任何密钥或敏感信息用环境变量传递。这既是安全要求也是可移植性的要求。6. 缓存目录迁移把 C 盘救回来6.1 为什么缓存目录必须改WorkBuddy 运行过程中会产生大量缓存模型响应的中间结果、Skill 执行的日志、临时文件、索引数据。默认情况下这些全在系统盘的用户目录下。用不了多久C 盘就会告急。系统盘满了之后不仅 WorkBuddy 变慢整个系统都会卡。所以缓存目录迁移不是可选项是必选项。6.2 迁移缓存目录的完整步骤第一步完全退出 WorkBuddy确保没有进程占用缓存文件。第二步找到当前缓存目录把里面的内容整体复制到目标位置比如D:\WorkBuddyData。第三步修改配置文件里的缓存路径指向新位置。第四步重启 WorkBuddy确认新缓存文件生成在新目录下。第五步确认无误后删除旧目录释放空间。这里有个细节复制的时候用“复制”而不是“剪切”等确认新目录工作正常后再删旧的。我有一次直接剪切结果中途出错旧目录没了新目录又不完整配置全丢只能重装。这个教训值一个“复制优先”原则。6.3 迁移后的验证清单迁移完成后逐项确认模型列表是否正常加载、Skill 是否能正常调用、日志是否写入新目录、临时文件是否在新目录生成。全部通过才算迁移成功。如果某一项异常先检查配置文件路径是否写对再检查新目录权限是否足够。7. 用 WorkBuddy 生成网站并发布的实操路径7.1 从需求到成品的完整流程WorkBuddy 生成网站本质上是让 Agent 调用一系列 Skill 来完成生成页面结构、写样式、填充内容、本地预览、导出静态文件。你可以用自然语言描述需求比如“做一个个人作品集网站深色主题包含首页、项目页、关于页”Agent 会拆解任务并逐步执行。我的实操路径是这样的先让 Agent 生成 HTML 骨架和 CSS本地预览确认布局再让它填充示例内容调整细节最后导出静态文件部署到静态托管服务。整个过程不需要我写一行代码但需要我在关键节点做确认和微调。7.2 发布环节的注意事项生成是一回事发布是另一回事。发布前要检查所有资源路径是否是相对路径、有没有遗漏的依赖文件、页面在移动端是否正常。我遇到过生成的网站本地打开正常发布后样式全丢原因是 CSS 用了绝对路径。改成相对路径就好了。另外发布平台的选择也影响体验。静态托管服务通常最简单把导出的文件夹拖上去就行。如果需要自定义域名和 HTTPS选支持这些功能的平台。WorkBuddy 本身不负责托管它只负责生成发布这一步要自己接。8. 常见问题与排查技巧实录8.1 安装与启动类问题装完打不开、启动闪退、界面白屏这类问题多半和运行环境有关。先检查系统版本是否满足最低要求再检查是否有杀毒软件拦截。Windows 下常见的是缺少运行库装一下 VC 运行库通常能解决。Linux 下检查依赖是否装全看启动日志里的报错信息。8.2 模型调用类问题模型调不通按这个顺序排查先确认 models.json 语法正确再确认密钥有效再确认网络能通最后确认模型本身可用。这四步走完基本能定位问题。如果都正常但还是不行看日志日志里通常有具体的错误码和原因。8.3 Skill 执行类问题Skill 不执行或执行报错先看 Skill 目录结构对不对再看描述文件格式有没有问题最后看脚本本身能不能独立运行。我习惯先在命令行里单独跑一遍 Skill 脚本确认脚本本身没问题再放到 WorkBuddy 里调。这样能把“脚本问题”和“集成问题”分开排查效率高很多。8.4 性能与资源类问题工作台变卡、响应变慢先看缓存目录是不是又满了再看是不是同时跑了太多任务。WorkBuddy 的 Agent 调度会占用资源任务排队是正常的但如果一直卡着不动可能是某个 Skill 死循环了。这时候去日志里找最后执行的那个 Skill手动终止它。9. 我个人的几条使用心得用了一段时间 WorkBuddy最大的体会是它的上限取决于你喂给它的 Skill 质量。工作台本身是个框架真正让它变得好用的是你积累的那些 Skill。我现在的习惯是每完成一个重复性任务就花十分钟把它固化成一个 Skill。刚开始觉得麻烦但一个月后回头看省下的时间远超投入。另一个心得是关于规则设定。WorkBuddy 支持给工作台定几条全局规则后续所有任务都生效。这个功能很实用比如我设了一条“所有输出默认用中文代码注释用英文”省得每次重复交代。规则不用多三五条覆盖高频场景就行多了反而互相干扰。最后说个细节定期备份你的配置目录和 Skill 目录。这两个东西是你工作台的“灵魂”丢了就得从头再来。我现在是每周自动备份一次到独立目录成本很低但关键时刻能救命。