AIOS 中 VirtualBox 虚拟化环境搭建指南从安装 VBoxManage 到驱动桌面 Agent 虚拟机【免费下载链接】AIOSAIOS: AI Agent Operating System项目地址: https://gitcode.com/GitHub_Trending/ai/AIOSAIOSAI Agent Operating System在virtual_env模块中为桌面 Agent 提供了一套完整的多提供商虚拟机管理框架其中 VirtualBox 是支持本地运行的开源虚拟化方案之一。本篇指南以仓库内 INSTALL_VITUALBOX.md 为骨架完整讲解 VirtualBox 的下载、安装、Windows 环境变量配置与安装验证并深入 manager.py 与 provider.py 源码说明 AIOS 实际调用VBoxManage启动虚拟机、配置网络、创建快照的完整链路。读完本文你将能独立完成 AIOS VirtualBox 环境从宿主机到虚拟机的端到端就绪。VirtualBox 在 AIOS 中的定位AIOS 的virtual_env是面向桌面自动化任务的 OpenAI Gym 风格环境见 desktop_env.py 中的DesktopEnv它需要一台真实可操作的虚拟机来承载浏览器、办公软件等目标应用。为了适配不同宿主机环境virtual_env.providers通过工厂函数 create_vm_manager_and_provider 统一注册了 vmware、virtualbox、aws、azure、docker 五种提供商其中 VirtualBox 走的是本地虚拟化 命令行控制路线所有对虚拟机的生命周期操作导入、启动、快照、查询 IP都通过VBoxManage命令行工具完成因此宿主机上能否正确安装 VirtualBox 并让VBoxManage进入PATH是整个 VirtualBox provider 能否工作的前提。这也是 INSTALL_VITUALBOX.md 这份安装指南存在的意义它不是普通的产品安装教程而是 AIOS 桌面虚拟化链路的第一道关卡。安装前检查平台兼容性在下载之前务必确认宿主机平台。原文档明确指出对于 Apple 芯片M1、M2 等VirtualBox 不受支持只能改用 VMware Fusion。这一点在源码中也有佐证manager.py 的镜像下载逻辑对 macOS 直接抛错if platform.system() Darwin: # macOS url UBUNTU_ARM_URL raise Exception(MacOS host is not currently supported for VirtualBox.)UBUNTU_ARM_URL NOT_AVAILABLE见 manager.py即 AIOS 官方没有为 Apple 芯片准备 VirtualBox 用的 Ubuntu 镜像。因此Intel/AMD x86_64 的 Linux 与 Windows 宿主机可使用 VirtualBox对应镜像UBUNTU_X86_URL由仓库指向的 Hugging Face 数据集提供见 manager.pyApple SiliconM1/M2 等macOS请改用 VMware Fusion安装方法见 INSTALL_VMWARE.md其他平台或架构如 ARM 服务器同样会被源码判为 Unsupported platform or architecture。第一步下载 VirtualBox 安装包从 VirtualBox 官方网站的 Downloads 页面获取与宿主机操作系统匹配的安装包官方安装程序会同时安装 VirtualBox 主程序与VBoxManage命令行工具。下载时注意两点选择与当前宿主机架构匹配的版本Windows 区分 x86/x64Linux 区分 deb/rpm 等发行版格式关注版本号的稳定发布通道避开已知有虚拟化缺陷的早期测试版本。下载完成后按照安装向导的默认选项逐步完成即可无需额外勾选特殊组件。第二步安装 VirtualBox 与 Windows PATH 配置各平台安装要点Windows以管理员身份运行安装程序跟随向导完成安装。安装完成后必须手动将安装目录追加到系统环境变量PATH否则VBoxManage命令无法在终端中直接调用Linux根据发行版选择对应的 deb/rpm 包或官方仓库源安装安装后VBoxManage通常已位于/usr/bin等默认PATH路径下无需额外配置macOSIntel安装 dmg 包后VBoxManage通常位于/usr/local/bin一般无需手动配置但 Apple 芯片不受支持见上文。Windows 的 PATH 配置细节这是原文档强调的重点也是 AIOS 源码反复提示的坑。默认安装路径为C:\Program Files\Oracle\VirtualBox配置方式任选其一图形界面打开「系统属性 → 高级 → 环境变量」在「系统变量」中找到Path新建一项填入C:\Program Files\Oracle\VirtualBox保存后重新打开终端使其生效命令行以管理员身份在 PowerShell 或 CMD 中执行setx PATH %PATH%;C:\Program Files\Oracle\VirtualBoxsetx会覆盖写入用户级 PATH建议先确认原值再执行修改后必须新开终端验证。为什么 AIOS 对这一步如此敏感看 provider.py 文件头注释即可明白# Note: Windows will not add command VBoxManage to PATH by default. # Please add the folder where VBoxManage executable is in # (Default should be C:\Program Files\Oracle\VirtualBox for Windows) to PATH.而 manager.py 在 Windows 上会尝试程序内自动补全路径if platform.system() Windows: vboxmanage_path rC:\Program Files\Oracle\VirtualBox os.environ[PATH] os.pathsep vboxmanage_path即便如此这只对当前 Python 进程有效如果你要在终端里手动执行VBoxManage import、VBoxManage list vms等排障命令仍然依赖系统级 PATH 配置。因此把安装目录写入系统环境变量是更稳妥的做法。第三步验证安装安装并配置完环境变量后打开一个新的终端窗口执行VBoxManage --version成功终端会打印当前安装的 VirtualBox 版本号例如7.0.x rxxxxx说明主程序与命令行工具均已就绪失败command not found说明VBoxManage不在PATH中请回到上一步重新配置环境变量并重启终端*失败找不到动态库 / VERR_错误**多为安装损坏或宿主机缺少虚拟化支持如 BIOS 中未开启 VT-x/AMD-V需要先解决底层虚拟化能力。AIOS 的所有 VirtualBox 交互都依赖该命令源码中的每次调用都会通过subprocess执行VBoxManage ...见 manager.py 的import_vm、provider.py 的_get_vm_uuid等所以验证通过是接入 AIOS 的最低门槛。验证之后AIOS 如何使用 VirtualBox安装验证只是开始。当你在 AIOS 中初始化DesktopEnv时把provider_name指定为virtualbox见 desktop_env.py 的参数定义与 providers/init.py 的工厂分发会依次发生如下流程依据 manager.py 的_install_vm函数分配或创建虚拟机VirtualBoxVMManager.get_vm_path首先读取注册表文件.virtualbox_vms若存在空闲虚拟机则直接占用否则生成新名称形如Ubuntu0、Ubuntu1并触发下载与导入见 manager.py下载并解压镜像从UBUNTU_X86_URL流式下载Ubuntu.zip支持断点续传Range头用tqdm显示进度解压到./virtualbox_vm_data见 manager.py导入虚拟机执行VBoxManage import ...ovf --vmname ... --settingsfile ...把.ovf模板导入为指定名称的.vbox虚拟机见 manager.py配置桥接网络执行VBoxManage modifyvm --nic1 bridged与--bridgeadapter1默认自动选取VBoxManage list bridgedifs输出的第一个网卡也可通过region参数指定网卡名见 manager.py无头启动执行VBoxManage startvm --type headless启动见 manager.py就绪探测通过VBoxManage guestproperty get /VirtualBox/GuestInfo/Net/0/V4/IP获取虚拟机 IP再轮询虚拟机内 5000 端口OSWorld server的/screenshot接口确认系统就绪见 manager.py设置分辨率并打快照VBoxManage controlvm setvideomodehint 1920 1080 32随后VBoxManage snapshot take init_state保存初始状态供任务重置时回滚见 manager.py。而在运行期VirtualBoxProvider实现自 base.py 的抽象接口负责start_emulator、get_ip_address、save_state、revert_to_snapshot、stop_emulator等操作见 provider.py。其中revert_to_snapshot先controlvm savestate保存当前状态再snapshot restore init_state恢复快照——这正是DesktopEnv.reset()里切换任务前恢复初始环境的实现基础见 desktop_env.py。可见宿主机的 VirtualBox 安装质量命令行可用、桥接网卡存在、虚拟化已开启直接决定上述自动化链路能否跑通。排障速查与注意事项结合源码行为归纳如下高频问题现象可能原因处理建议VBoxManage --version报 command not foundWindows 未配置 PATH将C:\Program Files\Oracle\VirtualBox加入系统 PATH 并重开终端首次运行长时间停留在下载阶段镜像体积较大Ubuntu.zip保持网络稳定源码支持断点续传中断后重跑会自动续传桥接网络配置失败宿主机无可用的桥接网卡检查VBoxManage list bridgedifs输出必要时通过region参数显式指定网卡名长时间提示 Check whether the virtual machine is ready虚拟机内服务未启动或 IP 获取失败确认VBoxManage guestproperty get能返回 IP检查桥接网络与虚拟机内 server 进程macOSApple 芯片报 not currently supported平台不兼容改用 VMware Fusion参见 INSTALL_VMWARE.md几点额外提醒首次运行需要下载并导入完整 Ubuntu 镜像耗时较长属预期行为DOCKER_GUIDELINE.md 对 Docker provider 也有类似提示VirtualBox 需要宿主机开启 VT-x/AMD-V 虚拟化若startvm报硬件虚拟化相关错误请先检查 BIOS/UEFI 设置目前 AIOS 的 VirtualBox provider 仅支持 Ubuntu 客户机系统get_vm_path对非 Ubuntu 的os_type会直接抛错见 manager.py。小结平台先行Apple 芯片无法使用 VirtualBox请直接选择 VMware Fusion安装到位Windows 必须把C:\Program Files\Oracle\VirtualBox加入PATH否则 AIOS 的VBoxManage调用链会整体失效验证兜底以VBoxManage --version输出版本号作为安装成功的唯一判据链路联通安装成功后AIOS 会通过VBoxManage自动完成镜像下载、OVF 导入、桥接网络、无头启动、IP 探测与快照创建把 VirtualBox 变成桌面 Agent 可控的沙盒操作系统。至此你的宿主机已经满足 AIOS VirtualBox provider 的全部前置条件可以继续初始化DesktopEnv(provider_namevirtualbox)开展桌面自动化实验了。【免费下载链接】AIOSAIOS: AI Agent Operating System项目地址: https://gitcode.com/GitHub_Trending/ai/AIOS创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考