zheng
08f22edf44
Sync install scripts and CI container image with NODE_VERSION, regenerate Electron Config.html, and skip gitignored portable/app in origin scan. Co-authored-by: Cursor <cursoragent@cursor.com>
Bootable Linux USB
Turn any computer into an AI workstation — boot from the drive, no operating system required on the machine itself.
How this differs from the portable build
The portable build (portable/) needs the computer to already run Windows or
macOS. This one does not need the machine to have an operating system at all:
it boots Ubuntu off the drive and runs U-Claw inside it.
That makes it the answer for a machine that is locked down, wiped, or running something you cannot install onto.
Self-contained on purpose
This directory does not reference portable/, u-claw-app/ or anything else in
the repository. Every script hardcodes its own URLs and paths. A change here
cannot break another module, and a change elsewhere cannot break this.
There is also a standalone mirror at u-claw-linux with the same contents, for cloning it on its own.
What ends up on the drive
Ventoy boot area (hidden partition)
BIOS + UEFI dual-mode boot, Ventoy 1.0.99
Ventoy data partition (visible)
ubuntu-24.04.4-desktop-amd64.iso 5.8 GB
persistence.dat 20 GB
ventoy/ventoy.json config
u-claw-linux/
├── setup-openclaw.sh
└── start-openclaw.sh
| Choice | Why |
|---|---|
| Ventoy 1.0.99 | Drop an ISO in and it boots — no burning, and several systems can share the drive |
| Ubuntu 24.04 LTS | Long-term support, the widest hardware driver coverage |
| casper-rw persistence | Lets a live USB keep data across reboots |
What you need
| USB drive | 32 GB or larger. USB 3.0 strongly recommended — on 2.0 everything is painful |
| Build machine | Windows 10/11, PowerShell 5.1+ |
| Target machine | x86_64 (Intel or AMD), any brand |
| Network | Needed once, when installing OpenClaw |
Building it — four steps
Open PowerShell as Administrator on Windows:
cd path\to\u-claw\bootable
.\1-prepare-usb.ps1 # Write Ventoy to the drive — THIS FORMATS IT
.\2-download-iso.ps1 # Download Ubuntu 24.04 (~5.8 GB)
.\3-create-persistence.ps1 # Create the persistence image (20 GB default)
.\4-copy-to-usb.ps1 # Copy everything onto the drive
What each step does
1 · Write Ventoy — lists your USB devices for confirmation, downloads Ventoy, then hands you its GUI to pick the drive and click Install. This erases the drive. Back it up first.
2 · Download Ubuntu — fetches the 24.04.4 desktop ISO from
releases.ubuntu.com, verifies its SHA256, and caches it so a retry does not
re-download 5.8 GB.
3 · Create persistence — the step that actually decides whether this works.
- With WSL installed → creates a properly formatted ext4 image directly
- With only docker-desktop's WSL → falls back to
/sbin/mkfs.ext4 - With no WSL at all → creates an empty sparse file that you must format by hand on first boot (see below)
The volume label must be casper-rw — that is the name Ubuntu looks for.
4 · Copy to the drive — finds the Ventoy drive by its label, checks free
space, copies the ISO, persistence.dat, ventoy.json and the setup scripts.
When the scripts fail
Reported by @wzf9 in issue #28. Useful when a download fails, the network is unreliable, or you are building offline.
Ventoy would not download or install
Get the Windows build from https://github.com/ventoy/Ventoy/releases, unzip,
run Ventoy2Disk.exe, pick the drive, click Install. It formats the drive.
The ISO would not download
Fetch it yourself:
- https://releases.ubuntu.com/24.04/ubuntu-24.04.4-desktop-amd64.iso
- https://releases.ubuntu.com/24.04/SHA256SUMS
Put the ISO at bootable\.download-cache\ubuntu-24.04.4-desktop-amd64.iso, then
check it:
(Get-FileHash -Algorithm SHA256 ".\.download-cache\ubuntu-24.04.4-desktop-amd64.iso").Hash -eq "3a4c9877b483ab46d7c3fbe165a0db275e1ae3cfe56a5657e5a47c2f99a99d1e"
The persistence file is empty (no WSL)
Boot into Ubuntu once, then:
sudo mkfs.ext4 -F -L casper-rw /media/*/Ventoy/persistence.dat
Reboot after formatting — persistence does not take effect until you do.
The copy step failed
Put these on the Ventoy data partition by hand:
| From | To (drive root) |
|---|---|
bootable\linux-setup\ |
u-claw-linux\ |
bootable\ventoy\ |
ventoy\ |
bootable\.download-cache\persistence.dat |
persistence.dat |
bootable\.download-cache\ubuntu-24.04.4-desktop-amd64.iso |
(same name) |
Using it
First time
- Plug the drive into the target machine
- Power on and press the boot-menu key:
| Brand | Key |
|---|---|
| Dell | F12 |
| Lenovo | F12 |
| HP | F9 |
| ASUS | F2 or DEL |
| Acer | F12 |
| MSI | F11 |
| Others | F12 or F2 usually; check the splash screen |
- Choose the USB device, then Ubuntu from the Ventoy menu
- Wait for the desktop — one to three minutes off a USB drive is normal
- Connect to Wi-Fi
- Open a terminal (
Ctrl+Alt+T) and run:
sudo bash /media/*/Ventoy/u-claw-linux/setup-openclaw.sh
- A U-Claw AI Assistant icon appears on the desktop
- Double-click it, then paste an API key in the browser
After that
Plug in, boot, double-click the icon. Everything you set up is still there.
What setup-openclaw.sh does
| Step | |
|---|---|
| 1 | Check it is running as root — it needs sudo |
| 2 | Install curl and xdg-utils |
| 3 | Create /opt/u-claw/{runtime,core,data} |
| 4 | Download Node.js from nodejs.org |
| 5 | Write package.json |
| 6 | Install OpenClaw and the QQ plugin from registry.npmjs.org |
| 7 | Write the default config — gateway and token |
| 8 | Install the start script into /opt/u-claw/ |
| 9 | Create the desktop shortcut, optionally starting on login |
Configuration
ventoy/ventoy.json
{
"persistence": [
{
"image": "/ubuntu-24.04.4-desktop-amd64.iso",
"backend": "/persistence.dat",
"autosel": 1
}
]
}
Tells Ventoy to attach persistence.dat when booting that ISO. autosel: 1
skips the confirmation prompt.
Environment on Linux
| Variable | Value |
|---|---|
OPENCLAW_HOME |
/opt/u-claw/data/.openclaw |
OPENCLAW_STATE_DIR |
/opt/u-claw/data/.openclaw |
OPENCLAW_CONFIG_PATH |
/opt/u-claw/data/.openclaw/openclaw.json |
Files
bootable/
├── README.md this file
├── 1-prepare-usb.ps1 write Ventoy
├── 2-download-iso.ps1 download Ubuntu
├── 3-create-persistence.ps1 create the persistence image
├── 4-copy-to-usb.ps1 copy onto the drive
├── linux-setup/
│ ├── format-persistence.sh format the persistence image
│ ├── setup-openclaw.sh install OpenClaw
│ ├── start-openclaw.sh launcher
│ └── openclaw.desktop desktop shortcut
└── ventoy/
└── ventoy.json persistence config
Things learned the hard way
An unformatted persistence.dat drops Ubuntu into initramfs. Ventoy cannot
mount a file with no ext4 filesystem in it, and the boot fails in a way that
gives no hint about the cause. To check whether a file is actually formatted,
read two bytes at offset 1080 — they should be 0x53 0xEF, the little-endian
form of the ext4 magic number 0xEF53.
Formatting requires a reboot. Running mkfs.ext4 and continuing in the same
session looks like it worked and silently does not persist.
Drive quality matters more than you would expect. Cheap unbranded drives fail in ways that look like software problems. Use USB 3.0, plug into the board directly rather than through a hub, and prefer 32 GB+ (5.8 GB ISO + 20 GB persistence + overhead leaves little room otherwise).
Sizing: 20 GB persistence on a 32 GB drive, 40 GB+ on a 64 GB drive.
Troubleshooting
| Problem | Fix |
|---|---|
| Will not boot from USB | In BIOS: disable Secure Boot, enable USB boot. Try both UEFI and Legacy/CSM |
| No Ubuntu in the Ventoy menu | The ISO must be in the root of the Ventoy data partition |
| Boot stops at initramfs | persistence.dat is not formatted. mkfs.ext4 -F -L casper-rw, then reboot |
| Data lost on reboot | Same cause — check the file is ext4 and the label is exactly casper-rw |
| No USB boot entry at all | Try another port; some machines disable USB boot in BIOS by default |
| Desktop takes ages to load | Normal off a USB drive. USB 3.0 on a USB 3.0 port helps a lot |
| OpenClaw install fails | Check the network — it needs nodejs.org and registry.npmjs.org |
| Wi-Fi does not work | Ubuntu 24.04 covers most chipsets; otherwise tether over USB from a phone |
| Browser does not open | Go to http://localhost:18789 yourself |
| Port already in use | OpenClaw uses 18789–18799. Close the terminal window and open it again |
| Wrong screen resolution | Settings → Displays |
Performance: running off a USB drive is slower than a disk — that is physics, not a bug. Inference happens at your model provider, so conversation speed is unaffected; only startup and file operations are slower.
For anything not covered here, see TROUBLESHOOTING.md.