u-claw/bootable

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

1. Plug the drive into the target machine
2. 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

3. Choose the USB device, then Ubuntu from the Ventoy menu
4. Wait for the desktop — one to three minutes off a USB drive is normal
5. Connect to Wi-Fi
6. Open a terminal (Ctrl+Alt+T) and run:

sudo bash /media/*/Ventoy/u-claw-linux/setup-openclaw.sh

7. A U-Claw AI Assistant icon appears on the desktop
8. 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.