A guide on how to install OpenClaw on a VirtualBox virtual machine in a very simple way.

Setting up an environment to run automation systems or management platforms like OpenClaw can sometimes be challenging for beginners. To ensure stable system operation and avoid conflicts with other software on the physical computer, using a virtual machine combined with automated deployment tools is the best solution.

 

Below is a detailed step-by-step guide to installing OpenClaw on VirtualBox via Vagrant, allowing you to configure your environment in just a few minutes.

Steps to install OpenClaw on VirtualBox

Step 1: Download and install the platform software.

To begin, you need to install two essential tools for creating and managing virtual machines. Please download them using the following official links:

VirtualBox: Download the latest version at https://www.virtualbox.org/ . Select Download.

 

 

Select the operating system you are using, and the system will download the VirtualBox installation file for you.

Note during installation: Just click Next . At the Network installation step, the software will display a warning "Warning: Network Disconnection" (as shown in the image). This is completely normal; just select Yes to continue.

 

Just click Yes until it's complete, then simply select Finish.

Download and install Vagrant: Download it at https://developer.hashicorp.com/vagrant/install .

 

• Extremely important: After installing Vagrant, the system will prompt you to restart your computer ( Restart Now ). You must restart your computer so that Vagrant can recognize the configuration and run the following steps.

Step 2: Download and extract the OpenClaw Prebuild data.

Instead of installing from scratch, we will use a pre-built version that already contains standard configurations.

1. Download the pre-built OpenClaw file from the SharePoint link provided below:

Download link for OpenClaw Prebuild

1. After downloading, extract the file to an easily accessible folder on your hard drive.

• • Suggestion: It is recommended to create a folder on drive C or D with a short path that does not contain Vietnamese characters with diacritics (e.g., C:OpenClaw or D:OpenClaw-VM).

• • Inside the extracted folder (openclaw-prebuild), you will find important files such as: openclaw-vm.box , Vagrantfile , and vagrant-up.bat . These are the most important files.

 

Step 3: Launch the automated system.

Depending on the operating system you are using, the method for running the configuration file will vary slightly:

For Windows users: It's very simple, just find the file vagrant-up.batin the extracted folder, double-click it (or right-click and select Run as Administrator ) to run it.

When you select this file, a black Command Prompt (CMD) window will appear. Vagrant will begin the file "Unpacking" process .box, configure network interfaces, set forwarding ports, and automatically start the VirtualBox virtual machine (as shown in the Terminal).

Please be patient and wait a few minutes for the process to complete. Wait for the system to automatically set up OpenClaw, and you will see the VirtualBox window launch with OpenClaw.

 

For macOS users: Since the script .batonly runs on Windows, you'll need to do some manual work through the Terminal:

1. Go to the folder openclaw-prebuild.
2. Open the file Vagrantfile-macOSand copy all its contents.
3. Open the file Vagrantfile(delete all the old content) and paste the copied content into it, then save it.
4. Open the Terminal application on your Mac, and navigate to the folder containing the file (using the command cd /đường/dẫn/đến/thư/mục).
5. Type the command vagrant upand press Enter:

Initialize the Telegram Bot to connect to the system.

For OpenClaw to communicate, send notifications, or execute automation flows, you need to have a Telegram bot ready. The bot creation process is very quick:

1. Open the Telegram app and search for the account named @BotFather (with a verified blue checkmark).
2. Send a command /newbotto start creating.
3. BotFather will ask you to enter the Bot Name and Username (which must end with a letter bot, for example: OpenClaw_test_bot).
4. After successful creation, BotFather will provide you with an HTTP API Token code . Save this code carefully for use in configuring the connection to OpenClaw in the next lesson.

See more in the article How to create a Telegram bot quickly

Why should you run OpenClaw on a VirtualBox virtual machine combined with Vagrant?

Setting up complex platforms directly on a personal computer (Host OS) can easily lead to environment errors or port conflicts. Running OpenClaw on a virtual machine offers significant advantages:

• Isolation: All OpenClaw settings, libraries, and data reside within the virtual machine. If an error occurs, your main operating system remains completely unaffected.
• Automated and consistent deployment: Instead of manually installing each system component (OS, Network, Dependencies), Vagrant reads the configuration from a file and automatically instructs VirtualBox to build a complete virtual machine (via the prebuild file .box).
• Easy to share and restore: With just a compressed folder and a few command lines, anyone can set up an identical OpenClaw environment, which is extremely useful for teamwork or teaching.

Common errors encountered when building OpenClaw with Vagrant and how to fix them.

Although Vagrant has automated most of the configuration process, due to the unique hardware characteristics of each computer, you may still encounter some minor issues when running the command vagrant up. Below are common errors and the quickest ways to resolve them:

• The VT-x/AMD-V error is disabled in the BIOS: This is the most common error when using VirtualBox. The cause is that your computer's hardware virtualization support is not enabled. To fix it: Restart your computer, access the BIOS/UEFI (usually by pressing F2, F12, or Delete), and enable Virtualization Technology .
• Error stuck at the "SSH auth method: private key" step: If the Terminal screen remains stuck on this message for more than 5 minutes without continuing, the virtual machine may have crashed during startup. To fix: Cancel Ctrl + Cthe current command. Open VirtualBox, force-shut down the running "OpenClaw_default." virtual machine, then return to the Terminal screen and type the command vagrant reloadto restart the process.
• Port Conflict Error: OpenClaw virtual machines typically use default ports such as 2222 (for SSH) or static web ports. If your machine is running other software that occupies these ports, Vagrant will report a red error. To fix: Open the file Vagrantfilewith Notepad, find the configuration line forwarded_port, and change the host machine's port number to something else (for example, change 2222 to 2223).