utm

UTM 封装了 QEMU 与 Apple 的 Virtualization.framework，提供两个并不等价的自动化入口。utmctl 是随附 CLI，负责生命周期、客户机内执行命令与文件传输、获取 IP、克隆和 USB；它不能创建、导入、导出或配置虚拟机。AppleScript（经 osascript）是严格超集：除 utmctl 的能力外，还能创建虚拟机、编辑硬件配置、注入键盘鼠标输入。经验规则：生命周期与客户机操作走 utmctl，创建与配置走 AppleScript。两者都通过 Apple Events 驱动 UTM.app，应用会自动启动，没有真正的守护进程模式。utmctl 默认不在 PATH，路径为 /Applications/UTM.app/Contents/MacOS/utmctl。常用命令包括 list、start、status、stop（默认 --force，--request 请求客户机）、clone、ip-address、exec、file push/pull；虚拟机只能用 UUID 或完整精确名称标识，不支持部分匹配。exec、file、ip-address 及 AppleScript Guest Suite 需要客户机内运行 QEMU guest agent：Linux 与 Windows x86_64 在 QEMU 后端可行；Apple Silicon 上常见的 Windows ARM64 仅部分可用，utmctl exec 无 stdout，建议改用 AppleScript Guest Suite 或 SSH；Apple VZ 后端不可靠，建议用 SSH。为自动化创建虚拟机时优先选 QEMU 后端。注意事项：首次调用会触发 macOS 自动化（TCC）授权，且按调用方二进制授权，无受支持的无头预置方式；UTM 启动时只读一次 config.plist，运行中改盘上文件无效，需用 AppleScript 更新配置（虚拟机须停止）或退出后编辑再启动；无 headless 标志，需移除 displays 条目并用 SSH 或串口；克隆共享 MAC 会导致同一 DHCP 租约，需清空 MAC 让 UTM 重新生成；delete 无确认且会擦除磁盘，删除前应确认用户，临时运行优先用 --disposable；客户机内 ping 因 libslirp 限制不可用，应改用 TCP 检查；生成的 AppleScript 须为纯 ASCII。验证自动化是否生效时，utmctl status 只反映虚拟机进程而非客户机就绪，应轮询 SSH 端口、agent 响应或 ip-address，启动可能需 30–90 秒。