workbuddy启动报“cpu指令集不支持”或“avx2 not available”时，需先确认宿主机cpu是否原生支持avx2，再检查虚拟机是否启用avx2透传；若不可行，可强制绕过检测、切换至云端api模式（--mode=cloud）或使用免部署web版。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜
如果您尝试安装WorkBuddy，但启动时提示“CPU指令集不支持”或“AVX2 not available”，则说明当前运行环境的处理器未启用或根本不支持AVX2指令集。该错误常见于虚拟机未开启硬件虚拟化透传、旧款物理CPU、或云服务器精简镜像中禁用了底层指令集。以下是解决此问题的步骤：
一、确认宿主机CPU是否原生支持AVX2
AVX2是WorkBuddy内置混元 Lite 推理引擎的硬性依赖，缺失将导致核心AI能力不可用并强制降级至纯API模式。需先验证物理CPU是否具备该能力，再判断是否为虚拟化配置问题。
1、Windows用户在PowerShell中执行：Get-CimInstance Win32_Processor | Select-Object Name, InstructionSet，观察输出中是否含“AVX2”字样。
2、macOS用户在终端中执行：sysctl -a | grep machdep.cpu.features | grep AVX2，若返回非空结果即表示支持。
3、Linux用户执行：grep -i avx2 /proc/cpuinfo，如无任何输出，则宿主机CPU不满足最低要求。
二、检查虚拟机平台是否启用AVX2透传
即使宿主机支持AVX2，若虚拟机未显式配置指令集透传，Guest OS仍将检测不到该特性。不同平台透传方式差异较大，必须按虚拟化类型分别处理。
1、VMware Workstation/ESXi用户：关闭虚拟机 → 编辑虚拟机设置 → “处理器”选项卡 → 勾选“允许使用AVX2指令集”（v17.5+版本）或手动在.vmx文件末尾添加：cpuid.1.eax = "0000:0000:0000:0001:0000:0100:1011:0001"。
2、VirtualBox用户：关闭虚拟机 → 打开终端 → 执行：VBoxManage setextradata "VM名称" VBoxInternal/CPUM/EnableAVX2 1，随后重启虚拟机。
3、Hyper-V用户：需确保启用了嵌套虚拟化且宿主机为Windows 11 22H2+；在PowerShell中对关机状态VM执行：Set-VMProcessor -VMName "VM名称" -ExposeVirtualizationExtensions $true，再启动。
三、绕过AVX2检测强制启用本地推理（仅限测试）
当无法修改虚拟化配置或宿主机确实不支持时，可临时跳过运行时检查，使WorkBuddy加载基础功能。该操作不恢复混元 Lite 性能，但可保障Claw交互与API调用正常。
1、定位WorkBuddy安装目录下的resources/app.asar.unpacked/dist/main.js（Windows/macOS通用路径）。
2、用文本编辑器打开该文件，搜索关键词isAVX2Supported，找到形如if (!isAVX2Supported()) { ... }的判断块。
3、将该条件语句整体替换为：if (false) {，保存文件。
4、在终端中清除缓存并重启应用：workbuddy --disable-gpu --disable-extensions。
四、切换至兼容模式运行（推荐生产环境）
WorkBuddy默认启用本地模型推理，但可通过启动参数强制退回到纯云端API模式，完全规避对AVX2的依赖，所有AI计算交由腾讯云后端完成，仅需稳定网络连接。
1、Windows用户：右键快捷方式 → “属性” → 在“目标”栏末尾追加空格后输入：--mode=cloud。
2、macOS用户：在终端中执行：open -n /Applications/WorkBuddy.app --args --mode=cloud。
3、Linux用户：启动命令改为：./workbuddy --mode=cloud，确保环境变量WB_CLOUD_MODE=1已设。
五、使用免部署Web版替代（零硬件依赖）
当虚拟机权限受限、无法修改配置且本地运行持续失败时，可完全跳过客户端安装，直接通过浏览器访问功能等效的Web界面，所有算力由云端提供，对终端CPU无任何指令集要求。
1、打开浏览器，访问：https://workbuddy.codebuddy.cn/web。
2、使用微信扫码登录（支持个人微信、企业微信、QQ账号）。
3、登录后自动进入Claw交互界面，可发送自然语言指令，如“重命名桌面PDF文件并按日期排序”。
4、Web版默认调用MiniMax或Kimi模型，支持文件上传、多轮对话与基础任务执行，功能覆盖率达本地版85%以上。
