根本原因是Node.js未正确写入系统PATH，必须重装并手动勾选“Add to PATH”（Windows）或确认macOS将/usr/local/bin写入shell配置文件；验证需在WorkBuddy技能日志中检查spawn node ENOENT错误。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜
WorkBuddy 技能执行失败时，node -v 返回 command not found 怎么办
根本原因是 Node.js 未正确写入系统 PATH，导致 WorkBuddy 启动的子进程完全找不到 node 命令。这不是版本不兼容问题，而是安装路径没被识别。
必须重装 Node.js，并在安装向导中**手动勾选 “Add to PATH”**（Windows）或确认 macOS 安装包已将 /usr/local/bin 写入 shell 配置文件（如 ~/.zshrc）。跳过这步等于没装。
验证方式不是只看终端能运行 node -v，还要在 WorkBuddy 的技能日志里确认是否出现 spawn node ENOENT 错误——这个错误就说明技能进程启动时根本没搜到 node。
- Windows 用户：安装完务必重启命令行和 WorkBuddy，否则环境变量不会刷新
- macOS 用户：若用 Homebrew 安装，需确保
which node输出路径在$PATH中；若用官网 pkg 安装，检查echo $PATH是否含/usr/local/bin - 宝塔面板用户：Node.js 必须通过【软件商店】安装，不能手动上传二进制，否则 PM2 管理器无法识别运行时
为什么 WorkBuddy 要求 Node.js LTS 版本，而不是最新版
LTS 版本（如 v18.20.4、v20.18.0）经过长期稳定性验证，WorkBuddy 的技能脚本大量依赖 child_process、fs.promises 和 stream.pipeline 等底层 API，这些在 Current 版本中可能有非兼容性变更。
比如 v21.x 移除了 fs.exists()，而某些旧技能包仍直接调用该方法，就会抛出 TypeError: fs.exists is not a function；又如 v22.x 默认启用 --experimental-permission 沙箱，会拦截技能对 Downloads 目录的写入。
官方明确支持的范围是 v16.20.2–v20.18.0，超出此区间不保证技能加载成功。
- Windows/macOS 官网下载页默认推荐的就是 LTS 版本，别点 “Current” 标签
- Linux 用户若用
apt install nodejs，大概率装到的是过时的 v12/v14，必须用 NodeSource 仓库或 nvm 切换 - 腾讯云部署文档中特别注明：v22.x LTS 尚未通过全技能链路测试，暂不推荐
Git 未安装导致技能报错 command not found: git 的真实影响
这不是可忽略的警告。WorkBuddy 的技能更新机制、GitHub 模板拉取、本地知识库克隆全部依赖 git 命令行工具。没有它，workbuddy install skill@github.com/user/repo 类指令会直接卡死或静默失败。
尤其要注意 Windows 安装时，默认选项是“Use Git from Windows Command Prompt”，但这个路径往往不加入系统 PATH；必须选“Use Git from Windows Command Prompt and also add Git to PATH”才能让 WorkBuddy 子进程访问到。
- 验证方式：在 WorkBuddy 控制台输入
!git --version（!表示执行系统命令），返回有效版本号才算生效 - macOS 用户若用 Xcode Command Line Tools 自带 git，版本常为过时的 v2.30，建议卸载后用 Homebrew 重装最新版
- 某些企业机禁用 git 协议，需提前配置
git config --global url."https://".insteadOf git://，否则技能 clone 会超时
Windows 下 .NET Desktop Runtime 缺失引发的 Access Denied 错误
这个错误只出现在 Windows，且几乎都发生在涉及文件操作的技能上，比如“把桌面上所有 PDF 合并成一个”“重命名 Downloads 里的图片”。根本原因不是权限设置，而是 WorkBuddy 的 Claw 子系统底层用 C# 编写，必须依赖 .NET 运行时来调用 Windows Shell API。
报错信息通常是 Access denied 或 HRESULT: 0x80070005，但日志里会夹带一句 Could not load file or assembly 'System.Windows.Forms' ——这就是 .NET 缺失的铁证。
- 必须安装 .NET Desktop Runtime（非 SDK，非 Server Hosting Bundle），版本 ≥ 6.0，架构要与 WorkBuddy 一致（x64 或 ARM64）
- 安装后无需重启系统，但必须彻底退出 WorkBuddy（包括托盘进程），再重新以管理员身份启动
- 如果已安装仍报错，用
dotnet --list-runtimes检查输出中是否含Microsoft.WindowsDesktop.App行
最易被忽略的是：Node.js、Git、.NET 这三者必须全部满足要求，WorkBuddy 才能稳定加载技能。少一个，就可能表现为某类任务完全不可用，而不是统一报错。排查时别只盯着 node -v，得逐个验证 git --version 和 dotnet --list-runtimes 的输出。
