折腾 WorkBuddy 前先把这几件事搞清楚如果你最近刷到过WorkBuddy这个词大概率和我一样是从 CodeBuddy 相关的讨论里顺藤摸瓜摸过来的。简单说腾讯在 CodeBuddy 这个 AI 编程助手的底座上推出的本地智能工作台 WorkBuddy不再只是帮你补全代码、聊聊天而是把代码生成、终端命令、文件读写、Git 操作这些东西揉进了一个桌面应用里。你可以把它理解成一个更懂中文开发者习惯的 AI 工作环境装上之后 AI 能直接在你本地干活而不只是给你一段建议。这篇教程解决的就是怎么把它弄到你的电脑上这件事覆盖 Windows 和 macOS 两套平台。我不打算只写去官网下载、双击下一步这种没营养的话而是会把我在多台机器上装 WorkBuddy 时遇到的坑、排错思路、以及装完之后的必要配置一起捋一遍。无论你之前用过 VS Code、Cursor 还是纯命令行这篇都适用——唯一的门槛是你需要会用终端执行几条命令。1. 装之前先弄明白WorkBuddy 到底装的是什么1.1 WorkBuddy 和 CodeBuddy 是什么关系你得先理解 WorkBuddy 的定位否则装完很容易困惑。CodeBuddy 是腾讯云的 AI 编程助手最早以 IDE 插件形式出现功能偏向对话式补全你写代码它给建议你提问它回答。WorkBuddy 是同一个团队的延伸产品但形态变了——它更接近一个独立的智能工作台Agent目标是让 AI 直接接管部分本地操作创建文件、跑命令、查日志、改配置而不是只停留在输出面板里。这带来的直接后果是装的不是一个纯编辑器而是一个带着操作权限的 Agent 运行环境。这也是为什么安装教程不能只讲双击安装包因为后面还有登录认证、目录授权、工具链检查这些步骤。权限没给够AI 就只能在聊天框里输出文字干不了实事。1.2 它能做什么装了之后实际能改善什么我自己的体验是WorkBuddy 解决的最大痛点是上下文割裂。在传统开发流程里你要在 IDE、终端、文档、浏览器之间来回切换AI 助手只看到了你贴给它的那几段代码对项目整体结构一无所知。WorkBuddy 的思路是直接把工作目录交给 AI 代理它自己会去读你项目里的文件、运行命令来验证结果、看到报错后主动修复。具体到日常使用我装好后最常用的是这几类操作让它初始化一个新项目脚手架它直接在当前目录生成文件并安装依赖让它排查本地服务的报错日志它能自己跑到日志目录去翻、去过滤、定位问题让它按规范生成 Git commit message并且自动完成 add/commit让它在指定的笔记目录里创建文档、整理内容所以这篇教程的核心价值不只是把图标装出来而是让你装完之后这个 Agent 真的能跑起来、能摸到你本地的文件、能执行命令、能配合你的日常工作流。1.3 两种安装形态的取舍客户端 vs 命令行目前 WorkBuddy 的安装主要有两条路我在 Windows 和 macOS 上都分别试过桌面客户端形态官方提供的 GUI 安装包Windows 是 exemacOS 是 dmg。适合大多数人安装直观但有额外的图形界面进程更新需要重新下载安装包。命令行工具形态通过 npm 全局安装 CLI 包然后在终端里启动工作台界面。优点是更新方便、权限控制更清晰、适合习惯终端的开发者但要求你提前装好 Node.js。这篇文章两条路都会写我的建议是如果你平时不碰终端走桌面客户端如果你已经装了 Node.js命令行形态更省心后续升级时少点麻烦。2. Windows 端安装全流程从环境检查到工作台跑起来2.1 安装前 5 分钟的环境预检在 Windows 上装 WorkBuddy最容易翻车的不是安装这一步而是安装前的环境没检查。浪费时间踩坑不如先花五分钟确认三件事。第一确认 Windows 版本。WorkBuddy 官方对 Windows 10/11 64 位支持得最好Windows 7 或 32 位系统就别折腾了直接放弃。你可以在设置 → 系统 → 关于里看系统类型确认是 64 位。第二确认 Node.js 是否已安装。开一个 PowerShell 或 CMD执行node -v npm -v如果提示找不到命令去 Node.js 官网下载 LTS 版本的 Windows 安装包一路下一步装好。建议装 18.0 或更高版本WorkBuddy 的 CLI 依赖比较新的 Node.js 特性。如果你本机还在用 Node 16建议先用 nvm-windows 切到 18/20 再继续别硬上。第三确认终端环境。我用下来最顺的是 Windows Terminal 加 PowerShell 7传统 CMD 也能跑只是显示效果和 Tab 补全体验差一些。没有 Windows Terminal 的话直接在微软商店搜Windows Terminal装一个免费。2.2 图形界面安装路线官网下载与 exe 安装如果你选择桌面客户端先打开 WorkBuddy 官网这里注意要用搜索引擎找官方入口别在第三方下载站随便下找到对应 Windows 的 exe 安装包。下载完成后有两点特别提醒第一安装路径不要带中文和空格。很多人的用户名是中文拼音缩写还好但如果你把路径改到D:\软件\WorkBuddy后续某些工具在调用本地文件时可能会出莫名其妙的编码问题。我一般装在C:\WorkBuddy或保持默认路径。第二Windows 自带的安全中心和第三方杀毒软件可能会拦截。我实装时Windows Defender 的智能应用控制第一次运行时弹了风险提示。这不是安装包有问题而是新软件没有足够的用户基数、数字签名还没被信任。处理方式是如果确认安装包是从官网下载的在 Defender 提示页面选择仍要运行或者提前把安装目录加入杀毒软件的白名单。安装完成后桌面上会出现 WorkBuddy 图标双击启动首次启动会让你登录账号这一步先不用急我会在后面的章节统一说明。2.3 命令行安装路线npm 全局安装与验证如果你走 CLI 路线在 PowerShell 里执行npm install -g tencent/workbuddy-cli这里有一个很重要的提醒tencent/workbuddy-cli是我目前可用的包名但这个团队迭代很快包名有过调整。如果你执行后报 404 或者提示包不存在去官网或 GitHub 仓库查最新的全局安装命令版本更新后命令略有变动是很正常的。安装完成后执行wb --version如果能看到版本号说明 CLI 装好了。接着在你想作为工作目录的文件夹里我建议先开一个空文件夹测试执行wb init这一步会做两件事一是在当前目录生成 WorkBuddy 的配置文件比如.workbuddy目录和 settings 文件二是检查运行环境把缺失的依赖项列出来。按照提示补装即可。2.4 Windows 上 PATH 环境变量的排障wb命令提示无法识别是 Windows 上最常见的坑。原因是 npm 全局安装目录没有加入系统的 PATH。排查方式是手动找到 npm 全局 bin 目录npm prefix -g这条命令会输出全局目录比如C:\Users\你的用户名\AppData\Roaming\npm。接下来打开系统属性 → 环境变量在用户变量中找到 Path把这个 npm 目录添加进去然后关掉终端重新打开再执行wb --version。如果你之前是开着终端安装的务必重开一个环境变量不会热加载。3. macOS 端安装全流程Intel 和 M 系列芯片要区别对待3.1 先确认你的 Mac 芯片类型macOS 上与 Windows 最大的不同在于芯片架构。你需要在左上角苹果图标 → 关于本机里确认处理器是 Apple SiliconM1/M2/M3/M4 系列还是 Intel。这会决定你下载哪个安装包以及后续某些工具链是否要装 Rosetta。一个很关键的点如果你用的是 M4 这种新机器有些没适配原生 ARM 的工具安装完会闪退或崩溃。WorkBuddy 的官方安装包已经分出了 Apple Silicon 和 Intel 两个版本选错了装不上。命令行路线则要确认 Node.js 是否也是 ARM 版本。如果直接在官网下载的 Node.js pkg通常会自动匹配架构但如果你之前用 Homebrew 装过 Node建议执行node -p process.arch确认输出是arm64而不是x64。3.2 桌面客户端安装与 macOS 权限处理桌面客户端和 Windows 流程类似官网下载 dmg双击挂载把 WorkBuddy 拖到 Applications 文件夹。但这里有几个 macOS 特有的问题要注意。第一首次打开时 Gatekeeper 可能会报无法验证开发者。如果你的系统是 macOS Sequoia 或更新版本且应用是从官网下载的可以在系统设置 → 隐私与安全性里看到仍要打开的按钮点一下就好。注意不建议去执行sudo spctl --master-disable开启任何来源——这个方法虽然能绕开所有拦截但会让整个系统的安全性下降没必要为装一个工具这么做。第二M 系列芯片如果下载错了 Intel 版也可能出现打开后提示已损坏之类的情况本质是 Rosetta 翻译层的兼容问题。直接用arch -arm64 open /Applications/WorkBuddy.app这种命令硬开不如老老实实重新下载 ARM 版。第三N 系列芯片用户里装完 app 后首次启动需要授权完全磁盘访问权限。因为 WorkBuddy 要读你磁盘上的文件、在你授权的工作目录里执行命令macOS 的 TCC 机制会在它第一次尝试访问受保护目录时弹窗你在系统设置 → 隐私与安全性 → 完全磁盘访问权限里勾选即可。3.3 macOS 命令行安装与权限细节macOS 终端的命令行安装核心还是 npm。但有一个 Windows 上不常见的麻烦npm 全局安装目录的写入权限。系统自带的 Node.js 如果装在/usr/local下npm 全局安装需要 sudo而 sudo npm install 本身有风险也容易让后续的全局包权限混乱。我个人的建议是用 nvm 管理 Node.js这样 npm 全局目录就在用户目录下不需要 sudo。curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash # 重开终端然后安装 Node 20 nvm install 20 nvm use 20之后正常执行npm install -g tencent/workbuddy-cli wb --version如果执行wb提示command not found大概率是 npm 的 bin 目录没在 PATH 里。用npm prefix -g拿到全局目录然后在~/.zshrc里加一行export PATH$(npm prefix -g)/bin:$PATH再source ~/.zshrc重载配置即可。3.4 macOS 重装与数据迁移时的零散经验热搜词里有人搜macos重装和如何将整个硬盘的macos系统克隆到外置优盘我猜是担心重装以后要重新配置折腾所有开发环境。这里说一个我自己的经验WorkBuddy 的配置集中在一个目录里你只需要把~/.workbuddy目录和项目里的.workbuddy目录备份好重装系统后直接拷回去即可恢复大部分配置。所以如果你有换机或者重装系统的计划不用害怕配置迁移成本很低。4. 装完不等于完事登录认证、目录授权和 Agent 功能验证4.1 登录账号微信扫码与云端模型调度安装完成后第一次启动 WorkBuddy 会让你登录。目前支持微信扫码登录和腾讯云账号登录二者本质上都会拿到一个访问令牌用于云端模型调度与配额管理。不要跳过这一步否则就算界面能打开发送对话请求时也会报 401 认证错误。登录后建议先检查一下账号状态Windows 和 macOS 都通用在界面右上角的头像菜单里看有没有显示当前用户以及有没有配额提示。有些早期测试版本需要在网页端先申请开通白名单如果你登录后界面提示无权限去官网检查一下自己的账号有没有被加入试用名单。4.2 初始化工作目录让 Agent 知道你允许它动哪些文件登录之后第一步不是急着跟它聊天而是规划好工作目录。WorkBuddy 的 Agent 默认只会在你授权的工作目录内读写文件不会全局乱跑。在桌面客户端里可以通过打开文件夹来选择一个工作目录在 CLI 里就是进入目录后执行wb init。这里有一个细节建议不要图省事直接选整个用户目录或者整个磁盘作为工作目录。Agent 读文件越深上下文越大响应越慢而且误操作的面也会变宽。我自己习惯是每个项目单独建一个目录WorkBuddy 指向项目根目录。比如~/projects/demo-app只暴露这个目录给它两边都干净。4.3 验证 Agent 能力跑一个能实际工作的任务登录和目录都配置好之后需要验证 Agent 是不是真的能干活。你可以让它做一个简单的实际任务来测试在当前目录创建一个 README.md 文件写入一段介绍文字然后用ls或 Finder 检查文件是否真的生成了。更进一步让它初始化一个简易前端项目。比如直接给指令帮我在当前目录初始化一个 Vite React 项目并启动开发服务器然后告诉我访问地址。如果它真的能依次执行npm create vite、npm install、npm run dev这些命令说明目录权限、终端执行权限都通了。这一步验证的是最核心的能力链路通路了后面的日常使用就顺畅了。4.4 环境自检命令w 命令别直接吞报错如果你在人工验证之后发现 Agent 某些功能还是不可用先运行自带的自检命令看看环境是否齐全。CLI 形态下执行wb doctor它会检查 Node.js 版本、npm 全局包、git 配置、网络连通性等关键项。桌面客户端里一般可以在设置页面找到环境检测或运行诊断入口。我遇到过的情况是Agent 能聊天但执行终端命令时报无法找到 git跑一次 doctor 立刻就发现了原因是 PATH 里没有 git 的可执行路径补上就恢复了。4.5 常用命令速查表命令作用适用平台wb --version查看 CLI 版本Windows / macOSwb init初始化当前目录的工作区Windows / macOSwb update升级 CLI 到最新版Windows / macOSwb doctor检查运行环境依赖Windows / macOSwb config查看/修改本地配置项Windows / macOS5. 安装过程中最容易翻车的几个坑完整排查链路5.1 npm 安装卡住不动换源是第一步判断是网络还是包问题先说说最常见的情况执行npm install -g tencent/workbuddy-cli之后进度条半天不动或者超时失败。很多人第一反应是网络问题但网络问题也分好几种。先区分是下载不了还是解析不了如果报错信息里是ETIMEDOUT、ECONNRESET这种通常是网络连接问题优先考虑切换 npm 镜像源。执行npm config set registry https://registry.npmmirror.com换源后重试安装。如果报错是ENOENT、404 Not Found那就是包名写错了或者包真的不存在去官网核实最新的包名别在镜像源上死磕。我这里要特别说明一下不要为了加速去搜任何所谓加速器或第三方代理工具完全没有必要。npm 官方源在国内换镜像源之后速度已经很好我实测几百 MB 的包也能跑满带宽。如果换了镜像还慢检查是不是公司网络有特殊的防火墙策略换手机热点试一次就知道。5.2 wb 命令提示无法识别/command not found这个坑在前面 Windows 和 macOS 的章节分别提到了但我想在这里做一次统一的排查梳理因为这是 80% 的新手都会遇到的。排查链路如下先确认包是否真的装上了npm list -g --depth0看输出里有没有 workbuddy-cli 相关包名。如果有找到全局 bin 目录npm prefix -g。手动执行这个目录下的命令比如C:\Users\xxx\AppData\Roaming\npm\wb --version如果能跑通说明是 PATH 没配置好。配置 PATHWindows 编辑用户变量 PathmacOS 编辑~/.zshrc或~/.bash_profile。另外有个冷门原因PowerShell 默认的执行策略可能阻止 npm 生成的.ps1脚本。如果命令提示不是无法识别而是禁止运行脚本执行Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser然后重开终端。5.3 macOS 提示已损坏或无法验证开发者先别急着关 SIP聊到 macOS 的权限问题很多人一搜就搜到关闭 SIP或者macos 任何来源但我强烈建议你不要一上来就动 SIP。SIP系统完整性保护是 macOS 的安全根基关掉之后系统被恶意软件攻破的概率会高很多而且装 WorkBuddy 完全没有必要做到这一步。正确的处理逻辑是先确认安装包来源如果是官网下载的在系统设置 → 隐私与安全性页面找仍要打开按钮如果找不到检查一下你是不是右键或双指轻触点开 app 时按了 Option 键有时候需要按住 Option 再打开才能调出覆盖 Gatekeeper 的选项。如果 App 已经打开过但闪退打开终端输入sudo log show --last 5m --predicate processImagePath contains WorkBuddy看崩溃日志通常是缺失动态库或者架构不对。架构不对就重新下载对应芯片版本的安装包。5.4 Windows 杀毒软件拦截安装程序先校验签名再操作Windows 端最常见的翻车点是安全软件误报。先说怎么判断是误报右键 exe 安装包 → 属性 → 数字签名看签名者是否和官方一致。如果签名有效就不用担心如果签名无效那就是安装包不对去官网重新下载即可。确认签名有效后把安装目录加入 Windows Defender 排除列表或者提前关闭实时防护安装完记得重新打开然后继续安装。装完后如果你还是不放心可以执行Get-FileHash .\WorkBuddy-Setup.exe -Algorithm SHA256把输出和官网公布的哈希值比对完全一致就是官方原包。5.5 登录后报 401 或配额不足令牌过期与账号状态排查有时候前一天还好好的第二天打开 WorkBuddy 报 401或者提示配额不足。先别急着重装大概率是登录令牌过期。桌面客户端的话退出登录再重新登录即可CLI 的话看下当前配置里有没有登出命令比如wb logout然后wb login。如果重登后仍然报配额不足去官网的控制台里看自己的云资源配额用量是不是用完了——免费的初始配额用完是很正常的它会有明确的提示比如本月对话次数已用尽。6. 装好之后值得做的进阶配置自定义指令与 skill 扩展6.1 自定义指令为什么值得花时间写WorkBuddy 安装好、能跑通基础任务之后体验和充值过的 AI 助手之间还差一层自定义指令Custom Instructions。说白了这是一段附加在每次对话中的全局语义等效于给 AI 写使用说明书。我推荐至少设置这几类自定义指令代码风格约束比如始终使用 TypeScript函数需要 JSDoc 注释禁止使用 any回答格式约束比如修改代码时先说明改动思路再给代码工作目录约束比如执行命令时禁止删除文件危险命令需要二次确认语言约束比如代码注释和 commit message 使用英文这些约束能显著减少你每次对话重复交代的时间而且能让 AI 的输出质量稳定在线。设置入口一般在 WorkBuddy 设置页的自定义指令或个人偏好里格式是 Markdown直接填写文本即可。6.2 skill 是什么让 Agent 长出专项技能除了全局指令WorkBuddy 支持 skill 机制。你可以把 skill 理解为一组可复用的能力包它定义了一个特定任务的完整流程、相关的 prompt 和操作细节AI 遇到相应场景时会自动调用或按指令加载。目前社区里很多人已经在分享各自写好的 skill比如Git 协作类 skill规定 commit message 的格式规范自动替换分支合并模板调试排查类 skill按复现步骤 → 查看日志 → 定位根因 → 修复 → 验证五步法处理 bug文档生成类 skill从代码注释中抽取 API 文档按项目模板生成 README前端代码生成类 skill指定组件库版本、样式方案、目录结构生成页面代码如果你自己第一次写 skill我建议从一个最简单的场景开始比如帮我按项目模板生成每日工作周报。把工作周报需要的章节、参考格式、最大篇幅等要求写清楚保存为 skill之后再执行生成今天的工作周报就能输出完全符合你预期的内容。6.3 与 Obsidian 结合的配置思路把笔记库变成 AI 知识库有一个很受欢迎的玩法是把 WorkBuddy 和 Obsidian 做结合。思路很简单把 Obsidian 的笔记库目录作为 WorkBuddy 的工作目录然后写一个 skill 让它扫描笔记、总结知识、整理待办。比如你可以在 skill 里这样描述工作目录是 Obsidian 笔记库根目录所有 markdown 文件都是我的笔记。 任务类型当我说整理笔记时扫描最近一周修改过的文件按主题归类生成 MOCMap of Content文件并更新到汇总目录下。这样做的好处是AI 真正读的是你本地的 markdown 文件不涉及任何云同步或者第三方接口数据都在自己手里。相比把笔记内容贴到网页版 AI 里问私密性和可控性都好很多。6.4 后续扩展方向从自动签到脚本到 Linux 版本装完 WorkBuddy 之后我还能想到几个值得探索的方向。第一把重复性操作固化成 skill。热搜词里有人搜workbuddy自动签到这个思路我很认可——如果你每天都要打开某个后台点签到或者定期重复某个固定流程完全可以写一个 skill把操作步骤沉淀下来让 Agent 每天按步骤执行省下大量碎片时间。第二关注 Linux 版本。如果你手头有 Linux 服务器或者开发机WorkBuddy 的 Linux 版本也值得尝试。安装思路和 Windows/macOS 的 CLI 路线一致Node.js 环境准备好npm 全局安装然后在服务器上直接远程会话。第三和 Docker 环境结合。如果你的项目是在 Docker 容器里跑的WorkBuddy 可以作为宿主机的控制面板让 AI 帮你执行容器操作、查看容器日志。这个玩法需要你对 Docker 有一定基础但非常能提升效率。根据我自己的体会WorkBuddy 这类工具刚装上的第一周你大概率还是像用普通编辑器一样用它的对话功能。真正拉开体验差距的是当你开始积累自己的自定义指令、skill并且把工作目录规划和权限边界都理清楚之后——这时候它才从一个能回答问题的聊天框变成真正在你电脑上干活的 Agent。希望这篇教程能帮你节省掉我当初踩坑的时间。