WorkBuddy 新手入门教程：从安装注册、模型配置到跑通第一个任务

装好 WorkBuddy 之前，先想清楚它到底帮你解决什么问题

WorkBuddy 是 CodeBuddy 团队推出的桌面 AI 办公助手，官方入口在 codebuddy.cn/work，文档挂在 codebuddy.cn/docs/workbuddy/Overview 下。它和你平时在浏览器里打开的 ChatGPT、Claude 不太一样：那些是“你问一句，它答一句”的对话工具；WorkBuddy 更接近一个本地智能体，能访问你电脑上的文件、按你给的步骤执行任务、产出文档、写脚本、整理表格，甚至完成一套多环节的工作流。

所以，判断它适不适合你的方式很简单：如果你手上有一堆重复、琐碎、依赖本地文件的活儿，比如把十几张表格整理成一个汇总表、给一批文档统一改格式、把一段需求变成可运行的脚本，这类任务值得用 WorkBuddy 去试。如果你只是想要一个随手查资料、写文案的对话框，那它有更轻的选择，不必为了“桌面 AI”的名头多装一个软件。

这里要先说一个基本判断：WorkBuddy 的能力上限不完全在模型，而在你给了它多少权限、任务描述是否清晰、工作空间是否规整。把这三件事做好，新手也能跑通第一个任务；做不好，再强的模型也会把文件搞乱。

前置条件：装 WorkBuddy 前先把这几样准备好

很多新手装完软件之后不知道下一步该干嘛，不是因为操作复杂，而是前面的准备没做完。WorkBuddy 是桌面端应用，不是网页工具，安装前先过一遍前置条件，能少走不少弯路。

先说设备和系统。你至少需要一台能正常安装桌面程序的电脑，具体支持 Windows 还是 macOS、最低配置要求多少，直接看官网下载页和官方文档确认。这类信息迭代快，别拿网上旧教程的截图当标准，截图里的参数过一两个月就可能过期。

然后是账号和网络。注册账号一般用邮箱就行，从官方入口 codebuddy.cn/work 注册，字段以官网最新流程为准，第三方教程里的步骤只能当参考。网络这块容易被忽略：WorkBuddy 要连模型服务才能工作，如果网络访问 API 经常超时，任务体验会明显变差。遇到这种情况，常见的解法是在 VPS 上做一个 API 中转，或者换一个更稳定的网络环境，具体适不适合你，后面讲模型配置时再展开。

再就是文件准备。建议在正式文件之外单独建一个测试目录，例如 WorkBuddyProjects/temp，让 AI 的第一次任务只在这个目录里跑。不要一上来就把整个工作文件夹交给它。另外，工作空间里不要放隐私文件或密钥，尤其是公司电脑上，这一点多花十分钟整理，比出事后补救划算得多。

最后是认知准备。WorkBuddy 不是纯聊天工具，它会在你电脑上执行操作。开始之前想清楚两个问题：用内置模型还是自定义 API？允许它动到什么程度？这两个问题决定了后面所有设置，先有个概念再动手，界面上的选项就不会看不懂。

安装注册：不要急着丢文件，先把工作空间改对

初次下载安装后，注册这一步一般不会太难，官方支持邮箱等常见方式注册，具体字段以官网最新流程为准。真正容易踩坑的是登录之后——很多人上来就把一个文件夹路径塞给它，然后开始提问。这个习惯要改。

我的建议是：登录后先找到设置里的工作空间路径，把它改成你真正用来存放工作文件的目录，而不是系统默认的“下载”或“我的文档”。原因是，工作空间决定了 AI 能读哪些文件、能把生成结果写到哪。若路径不对，后面所有任务都会表现在“找不到文件”“写不进去”这类奇怪问题上。

我一般会这样建目录：

WorkBuddyProjects/
  ├─ 项目A/
  ├─ 项目B/
  └─ temp/

根目录下按任务分文件夹，再放一个 temp 做临时测试。好处有三个：第一，AI 处理范围明确，不会碰到无关文件；第二，出问题后能快速定位；第三，方便以后接 Git 或网盘同步，回滚成本低。

如果你用的是公司电脑或公共电脑，这一步更重要。工作空间里不要出现个人隐私或敏感凭证。宁可多花五分钟整理目录，也不要让一个尚未摸清规则的 AI 在重要文件里自由穿行。

模型与权限：内置模型、自定义 API、沙箱模式怎么选

WorkBuddy 的模型配置是新手容易纠结的一块。官方默认提供内置模型，你不需要自己做太多设置就能跑。对第一次接触的人来说，先用内置模型把流程跑通，是成本最低的路径。

如果你已经有一把 OpenAI 兼容的 API Key，也可以选择在设置里填自定义 API。这样做的好处是密钥和额度都由你自己控制，坏处也很明显：第三方 key 的稳定性、计费方式、数据隐私都需要你自己确认。这里要提醒一句：不要把 key 写在项目文件里，也不要在共享电脑上保存长期有效的密钥。如果你打算自建一个 API 转发入口，可以参考我们之前写的 gemini-web2api 部署到 VPS 完全指南，它讲的是把 OpenAI 兼容 API 反代工具部署到 VPS 上的完整做法，适合想统一管理多个模型的用户。如果你只是想低成本维护一个 API 转发节点，很多人会选 RackNerd 这类年付高性价比 VPS，但具体是否够用，要结合你的请求频率和网络环境判断。

接下来是权限问题。WorkBuddy 不是只回话，它会在你电脑上执行动作，所以“允许它做到什么程度”必须前置确认。新手最应该打开的是沙箱模式。沙箱相当于一个隔离环境，AI 的操作被限制在可控范围内，即使某个步骤执行错，也不会直接改动你的真实系统文件。它是新手保护伞这句话，真的不是空话。

我的态度是：新手阶段一直开着沙箱，先把任务的输入输出跑通；等你能判断它每一步在干什么，再按需关闭。不要为了“省事”一上来就给它全部权限，权限一旦放开，回滚成本会高很多。

任务模式解析：Ask / Plan / Craft / 召唤专家，新手为什么优先选 Plan

WorkBuddy 的任务模式不是随便分的，不同模式决定了 AI 是先“想”还是直接“做”。

Ask 模式本质上是问答。你向它提问，它给你回答，适合查资料、解释概念、写短文这类不需要碰本地文件的需求。把 Ask 当成聊天工具理解就行。

Plan 模式则是先产出执行计划，再征求你的确认。很多新手第一次用 WorkBuddy 会直接丢一个任务，然后等结果，结果发现 AI 的理解和自己想要的不一致。Plan 模式能把这个误差提前暴露出来：它会先告诉你“我打算这样做，分几步”，你确认后再继续。所以“新手盲选 Plan 准没错”这句话是成立的，因为它给了你一道确认门槛。

Craft 模式更偏创建和产出。当你已经有明确目标，希望 AI 直接生成文档、代码、数据文件这类结果时，可以用 Craft。它比 Ask 更进一步，不是聊聊就结束，而是要在工作空间里产出实际文件。

“召唤专家”则可以理解为按领域调出专门 agent，适合某个垂直场景下的复杂任务。具体支持哪些专家、怎么触发，以官方文档当前版本为准，因为这类桌面助手功能迭代很快，截图和功能列表过一两个月就可能变了。

新手路径我建议这样走：先用 Ask 和它熟悉交互，再用 Plan 跑一个 5 分钟小任务，确认它的计划能力；最后再尝试 Craft。不要一上来就挑战“把整个部门的表格自动化”这种复杂任务。

新手最容易犯的六个错误

第一个错误是一上来就把重要文件塞给它。你还不清楚它的计划和执行逻辑，就让它在关键文档上操作，风险太大。正确做法是先复制一份到 temp 目录试跑。

第二个错误是不改工作空间路径。默认目录不一定是你的实际工作目录，结果就是 AI 生成的产物散落各处，你找不到，它也可能读不到。

第三个错误是过早关闭沙箱。关闭沙箱意味着 AI 可以直接修改真实文件，一旦某个步骤判断失误，你可能要花更多时间恢复。关闭前至少先跑通一次完整任务。

第四个错误是用 Ask 模式处理需要执行的任务。Ask 只是聊天，它不会真的去整理文件。你问“帮我整理这些表格”，它可能只给你一段建议，而不是真的动手。

第五个错误是任务描述太含糊。比如“把这几个文件合并一下”，AI 不知道合并逻辑是什么——是按列合并还是按行合并，覆盖还是新建，保留哪些字段。描述里把输入、输出、规则、例外情况写清楚，成功率会明显上升。

第六个错误是让 AI 一次性处理超大批量任务。对新手来说，先选 3 到 5 个文件验证，确认逻辑没问题后再放大范围。大任务如果中途出错，排错成本远高于重跑。详细的环境和 API 配置技巧，可以进一步看 WorkBuddy 新手配置指南，那篇把本地桌面 AI 助手、模型 API 和沙箱权限的设置讲得更细。

怎么验证任务结果是不是对的

AI 任务完成后，不能直接默认结果正确。哪怕是同一个提示词，换一次模型、换一种模式，输出都可能不一样。所以要养成验证习惯。

第一，把任务放在临时目录里先跑。这样即使结果有问题，也不会污染正式文件。

第二，利用版本管理。如果你熟悉 Git，可以在工作空间里初始化仓库，每次任务后 diff 一下，看看文件到底改了什么。不熟悉 Git 也没关系，至少把原文件复制一份做备份。

第三，查看 AI 的执行日志或输出说明。大多数桌面智能体会记录自己的操作步骤，通过日志判断它是否按计划执行，比只看最后结果更可靠。

第四，抽查生成文件。如果它整理了 100 行数据，不要只看前 5 行，随机抽中间和最后的数据，确认规则一致。

任务跑乱之后怎么回滚

再谨慎也会有翻车的时候。任务执行到一半发现不对，先不要继续叠加新指令让它“修复”，那样只会让状态更乱。

最简单有效的回滚方式，是回到任务开始前的状态。如果你提前在工作空间里做了备份，直接把原文件恢复回去。如果用了 Git，直接回退到上一个提交。如果都没准备，可以尝试让 AI 以 Plan 模式重新描述当前目录状态，看看它能不能恢复到干净点，但这并不是百分百可靠。

所以结论是：回滚方案要前置，而不是出事后再想。每次跑新任务前，把“可能被影响的文件”复制出来，或者做好提交，成本都很低，但能省下大量返工时间。

总结：适合谁用，以及第一次任务怎么做

总的来说，WorkBuddy 适合那些想把手上的本地重复劳动交给 AI 的人，尤其是文档整理、数据清洗、脚本生成、自动化流程这类场景。它不适合只是想要一个聊天问答工具的用户，也不适合在权限管控严格的公司电脑上随意安装的人。

第一次上手，我建议按这个清单执行：

• [ ] 用官方渠道安装并注册，注册信息以官网为准
• [ ] 在设置中改好工作空间路径，建好测试文件夹
• [ ] 打开沙箱模式，第一次任务不要关闭
• [ ] 用 Plan 模式跑一个小任务，先看计划再确认
• [ ] 验证输出文件，而不是只看 AI 的总结
• [ ] 跑顺后再逐步尝试 Craft 模式和更大的任务

价格、功能范围、模型列表这些信息，WorkBuddy 迭代很快，请以官网和官方文档为准，不要相信截图里的旧版本参数。如果你除了 WorkBuddy，还打算自己在 VPS 上搭 API 中转服务，或者让一些自动化任务在服务器上长期跑，建议先搞清楚按小时计费和包年包月的区别，可以看看《弹性 IP 云服务器怎么选》，里面讲了按小时计费 VPS 的优缺点、成本和适用场景。如果你想更系统地设置模型 API 和沙箱权限，可以继续阅读 WorkBuddy 新手配置指南；如果计划在 VPS 上搭建自己的 API 转发服务，再看 gemini-web2api 部署指南会更顺。希望这篇文章能帮你少走弯路，把第一个任务真正跑通。