遇到“非法指令”错误说明CPU缺少AVX支持，可依次采取五种方案：一、用CPU-Z或命令确认AVX缺失；二、配置config.yaml启用api_only模式；三、安装官方Legacy版本；四、在虚拟机中启用AVX透传；五、手动替换为SSE4.2版ONNX Runtime引擎。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜
如果您在启动 Qoder 时遇到“非法指令”错误提示，说明当前 CPU 缺少 AVX 指令集支持，而 Qoder 的默认二进制文件依赖该指令集执行关键计算任务。以下是针对老旧 CPU（如 Intel Core 2 Duo、i3-2100、AMD FX 系列、Pentium G4560 等）的多种适配方案：
一、确认 CPU 是否缺失 AVX 指令集
该步骤用于精准定位问题根源，避免误操作或无效重装。AVX 是 Intel Sandy Bridge（2011年）及 AMD Bulldozer（2011年）起引入的基础向量扩展指令，早于该代际的处理器均不原生支持。
1、Windows 用户：下载 CPU-Z 工具，运行后切换至“Instructions”标签页，检查列表中AVX 项是否被勾选；若未勾选，则确认不支持。
2、macOS 用户：打开终端，执行命令 sysctl -a | grep machdep.cpu.leaf7_features，输出中若不含 avx 字样，则硬件不支持。
3、Linux 用户：在终端中输入 grep avx /proc/cpuinfo，若返回空结果，即表示 CPU 不具备 AVX 指令集能力。
二、启用纯 API 模式绕过本地指令集依赖
此方案使 Qoder 完全跳过本地推理模块，所有 AI 相关任务交由远程服务端处理，无需修改二进制文件，兼容性最强。
1、完全退出 Qoder 进程，包括系统托盘后台残留项。
2、进入 Qoder 安装目录，定位 config.yaml 文件（Windows 路径示例：C:\Program Files\Qoder\config.yaml；macOS 示例：/Applications/Qoder.app/Contents/Resources/config.yaml）。
3、用文本编辑器打开 config.yaml，在 engine: 区块下添加新行：fallback_mode: api_only；若该字段已存在但值为 local 或 hybrid，请将其修改为 api_only。
4、保存文件后，以管理员权限（Windows）或使用终端命令（macOS/Linux）重新启动 Qoder，首次加载将直接连接云端服务，不再尝试调用本地 AVX 指令。
三、安装官方 Legacy 版本替代默认包
Legacy 版本专为无 AVX 硬件设计，移除了启动时的 AVX 检测逻辑，并禁用所有依赖 AVX 的本地加速模块，仅保留核心功能与插件调度能力。
1、访问 Qoder 官方 GitHub Releases 页面，查找标注为 qoder-legacy-*.tar.gz（Linux/macOS）或 qoder-legacy-*.exe（Windows）的安装包。
代码编辑 CLI 工具集合：Cursor CLI（agent）和 Qoder CLI（qodercli），用于代码修改、重构、Code Review 及自动化代码任务。
2、彻底卸载当前版本：Windows 用户通过控制面板卸载；macOS 用户拖拽应用至废纸篓并清空 ~/Library/Application Support/Qoder；Linux 用户删除安装目录及 ~/.config/qoder 配置路径。
3、安装 Legacy 版本，安装过程中不弹出任何 AVX 校验提示，启动后自动以兼容模式运行。
四、在虚拟机中启用 CPU 指令集透传
若 Qoder 运行于 VMware 或 QEMU/KVM 虚拟环境中，且宿主机 CPU 实际支持 AVX，但虚拟机内仍报“非法指令”，说明虚拟化层未正确暴露 AVX 特性。
1、关闭目标虚拟机，确保其处于完全关机状态（非挂起或休眠）。
2、在 VMware Workstation/Player 中，右键虚拟机 → “设置” → “处理器”，勾选 “虚拟化 Intel VT-x/EPT 或 AMD-V/RVI”，并将 “CPU/MMU 虚拟化”设为“硬件”模式。
3、在 QEMU/KVM 环境中，编辑虚拟机 XML 配置（virsh edit <domain>），将 <cpu mode='host-passthrough'> 设置为启用状态，并确保 <domain type='kvm'> 已声明。
4、保存配置并重启虚拟机，启动后再次执行 grep avx /proc/cpuinfo，确认输出包含 avx 字样。
五、手动替换为 ONNX Runtime 后端引擎
高级用户可通过更换推理引擎规避 AVX 依赖，ONNX Runtime 提供 SSE4.2 及更低指令集的构建版本，适用于 Penryn、Nehalem 等老平台。
1、从 ONNX Runtime 官方 GitHub 发布页下载 onnxruntime-linux-x64-cpu-sse42-*.tgz（Linux）、onnxruntime-osx-universal2-cpu-sse42-*.tgz（macOS）或 onnxruntime-win-x64-cpu-sse42-*.zip（Windows）。
2、解压后提取 libonnxruntime.so（Linux）、libonnxruntime.dylib（macOS）或 onnxruntime.dll（Windows）文件。
3、进入 Qoder 安装目录下的 lib/engines/ 子目录，备份原始引擎文件，将上述 ONNX Runtime 动态库复制至此处，并重命名为 libonnxruntime.so（对应平台）。
4、修改 config.yaml 中 engine: onnxruntime，并确保 backend_path 指向新放置的动态库绝对路径。
