U-Claw Linux Bootable USB

把任意电脑变成 AI 工作站 — 插上 U 盘，开机即用

Turn any computer into an AI workstation — just boot from USB

中文

与主仓库的关系

本仓库是 U-Claw 项目的 Linux 可启动版。代码同时存在于两个地方：

位置	说明
本仓库 (u-claw-linux)	独立仓库，方便单独克隆和使用
u-claw/bootable/	主仓库内的目录，内容一致

两边代码完全一样，选哪个都行。本仓库的优势是轻量 —— 只克隆 Linux 盘相关的文件，不用拉整个主仓库。

所有脚本完全自包含，不依赖主仓库中 portable/、u-claw-app/、website/ 的任何文件。出问题只影响自己，不会波及其他模块。

这是什么

制作一个可启动的 Linux AI U 盘：

插上任意电脑，从 U 盘启动，直接进入 Ubuntu 桌面
一键安装 OpenClaw AI 助手，桌面图标双击即用
内置持久化存储，安装的软件和数据重启后保留
不需要目标电脑有任何操作系统

与 u-claw 便携版的区别：便携版需要电脑已有 Windows/Mac 系统，本项目连系统都不需要。

技术方案概览

┌────────────────────────────────────────────┐
│                U 盘结构                      │
│                                            │
│  Ventoy 引导区（隐藏分区）                   │
│    - BIOS + UEFI 双模式启动                  │
│    - 开源引导管理器 v1.0.99                  │
│                                            │
│  Ventoy 数据分区（可见）                     │
│    ubuntu-24.04.4-desktop-amd64.iso  5.8GB │
│    persistence.dat                   20GB  │
│    ventoy/ventoy.json                配置   │
│    u-claw-linux/                     脚本   │
│      ├── setup-openclaw.sh                 │
│      └── start-openclaw.sh                 │
└────────────────────────────────────────────┘

三个核心技术选型：

技术	为什么选它
Ventoy 1.0.99	ISO 文件直接丢进去就能启动，不用烧录，可放多个系统
Ubuntu 24.04 LTS	长期支持版，驱动兼容性最好，社区最大
casper-rw 持久化	让 Live USB 也能保存数据，重启不丢失

硬件要求

项目	要求
U 盘	32GB+，强烈推荐 USB 3.0（蓝色接口）
制作环境	Windows 10/11，PowerShell 5.1+
目标电脑	x86_64（Intel / AMD），任意品牌
网络	首次安装 OpenClaw 时需要联网

快速制作（4 步）

在 Windows 上以管理员身份打开 PowerShell：

cd path\to\u-claw-linux

# Step 1: 下载 Ventoy 并写入 U 盘（会格式化 U 盘！）
.\1-prepare-usb.ps1

# Step 2: 下载 Ubuntu 24.04 ISO（~5.8GB，国内镜像）
.\2-download-iso.ps1

# Step 3: 创建持久化镜像（默认 20GB）
.\3-create-persistence.ps1

# Step 4: 拷贝所有文件到 U 盘
.\4-copy-to-usb.ps1

每一步做了什么

Step 1: 写入 Ventoy 引导 (`1-prepare-usb.ps1`)

列出所有 USB 设备，让你选择
从 GitHub 下载 Ventoy 1.0.99
启动 Ventoy2Disk.exe GUI 界面
你在 GUI 中选择 U 盘 → 点 Install
注意：会格式化 U 盘，数据全丢！

Step 2: 下载 Ubuntu ISO (`2-download-iso.ps1`)

从国内镜像下载 Ubuntu 24.04.4 桌面版
镜像优先级：清华 → 阿里 → 中科大 → 官方
自动 SHA256 校验确保文件完整
有缓存机制，不会重复下载

Step 3: 创建持久化镜像 (`3-create-persistence.ps1`)

这是整个方案最关键的一步。

检测是否安装了 WSL（Windows 子系统 Linux）
有 WSL：直接用 mkfs.ext4 创建格式化好的 ext4 镜像
没 WSL：创建稀疏文件，首次进 Linux 后需要手动格式化
卷标必须是 casper-rw（Ubuntu 持久化的约定）
默认 20GB，可选 1-28GB

Step 4: 拷贝到 U 盘 (`4-copy-to-usb.ps1`)

自动识别 Ventoy U 盘（通过卷标）
检查剩余空间
拷贝 4 样东西：ISO、persistence.dat、ventoy.json、安装脚本

使用方法

首次使用

将 U 盘插入目标电脑
开机按启动键进入 BIOS 启动菜单：

品牌	启动键
Dell 戴尔	F12
Lenovo 联想	F12
HP 惠普	F9
ASUS 华硕	F2 或 DEL
Acer 宏碁	F12
MSI 微星	F11
Huawei 华为	F12
Xiaomi 小米	F12

在启动菜单选择 USB 设备
Ventoy 菜单出现 → 选择 Ubuntu
等待 Ubuntu 桌面加载
连接 Wi-Fi
打开终端（右键桌面 → Open Terminal，或 Ctrl+Alt+T）
运行安装命令：

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

安装完成，桌面出现 "U-Claw AI Assistant" 图标
双击图标 → 浏览器打开 → 配置 AI 模型

日常使用

以后每次只需要：

插入 U 盘 → 开机选 USB → 进入 Ubuntu
双击桌面 "U-Claw AI Assistant" 图标
所有数据自动保留，无需重新安装

安装脚本详解 (`setup-openclaw.sh`)

脚本完成 9 个步骤：

步骤	操作	说明
1	检查 root 权限	必须 `sudo` 运行
2	安装系统依赖	`curl`, `xdg-utils`
3	创建目录	`/opt/u-claw/{runtime,core,data}`
4	下载 Node.js v22	国内镜像优先，官方回退
5	创建 package.json	最小化包描述
6	安装 OpenClaw	`npm install openclaw` + QQ 插件
7	写默认配置	gateway + token
8	安装启动脚本	复制到 `/opt/u-claw/`
9	创建桌面快捷方式	可选开机自启

完全自包含：脚本内硬编码了所有 URL 和路径，不依赖本仓库中的任何其他文件。

文件结构

u-claw-linux/
├── README.md                      本文件
├── LICENSE                        MIT 协议
├── .gitignore
│
├── 1-prepare-usb.ps1              Step 1: 下载 Ventoy + 写入 U 盘
├── 2-download-iso.ps1             Step 2: 下载 Ubuntu ISO
├── 3-create-persistence.ps1       Step 3: 创建持久化镜像
├── 4-copy-to-usb.ps1              Step 4: 拷贝到 U 盘
│
├── linux-setup/                   进入 Linux 后使用的脚本
│   ├── setup-openclaw.sh          一键安装 OpenClaw
│   ├── start-openclaw.sh          启动脚本
│   └── openclaw.desktop           桌面快捷方式定义
│
└── ventoy/
    └── ventoy.json                Ventoy 持久化配置

核心配置文件

`ventoy/ventoy.json`

{
  "persistence": [
    {
      "image": "/ubuntu-24.04.4-desktop-amd64.iso",
      "backend": "/persistence.dat",
      "autosel": 1
    }
  ]
}

告诉 Ventoy：启动 Ubuntu ISO 时，自动加载 persistence.dat 作为持久化后端。autosel: 1 表示自动选择，不弹确认框。

Linux 端环境变量

变量	值
`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`

OpenClaw 配置格式

{
  "gateway": {
    "mode": "local",
    "auth": { "token": "uclaw" }
  },
  "agent": {
    "model": "deepseek-chat",
    "apiKey": "sk-xxx",
    "baseURL": "https://api.deepseek.com/v1"
  }
}

实践经验与注意事项

制作阶段

U 盘选择很重要
- 必须 32GB+（ISO 5.8GB + 持久化 20GB + 系统开销）
- 强烈建议 USB 3.0，否则启动和运行都会很慢
- 推荐品牌：闪迪、金士顿、三星（杂牌盘容易出问题）
- 避免使用 USB Hub，直接插主板接口
Step 1 格式化会清空 U 盘
- Ventoy 安装会格式化整个 U 盘
- 务必提前备份 U 盘上的数据
- 脚本会列出所有 USB 设备让你确认，看清楚再操作
Step 3 持久化镜像（重要教训）
- 有标准 WSL（Ubuntu 等）→ 自动创建 ext4 镜像（最省事）
- 只有 docker-desktop WSL → 脚本会尝试用 /sbin/mkfs.ext4 格式化（2026-03-17 修复）
- 完全没有 WSL → 创建空文件，必须首次进 Linux 后手动格式化：
```
sudo mkfs.ext4 -F -L casper-rw /media/*/Ventoy/persistence.dat
```
  格式化后必须重启才能生效
- 踩坑记录：空的 persistence.dat（无 ext4 文件系统）会导致 Ventoy 挂载失败， Ubuntu 启动直接掉进 initramfs。验证方法：读取文件 offset 1080 处的 2 字节，应为 0x53 0xEF（ext4 magic number 0xEF53 的 little-endian）
- 大小建议：32GB U 盘选 20GB，64GB U 盘可以选 40GB+
ISO 下载
- 脚本默认走清华/阿里/中科大国内镜像，无需翻墙
- 如果全部失败，可以手动下载 Ubuntu ISO 放到 .download-cache/ 目录

启动阶段

Secure Boot 问题
- 部分电脑需要关闭 Secure Boot 才能从 U 盘启动
- 进入 BIOS → Security → Secure Boot → Disabled
- 不同品牌进 BIOS 的方式不同（通常是 DEL 或 F2）
找不到 USB 启动项
- 确认 U 盘插好了（换个 USB 口试试）
- 有些电脑默认禁用了 USB 启动，需要在 BIOS 中开启
- Legacy/CSM 模式和 UEFI 模式都试试
Ubuntu 桌面加载慢
- 正常现象，Live USB 从 U 盘读取，比硬盘慢
- USB 3.0 U 盘 + USB 3.0 接口会快很多
- 首次加载约 1-3 分钟

使用阶段

Wi-Fi 连接
- Ubuntu 24.04 支持大多数 Wi-Fi 芯片
- 如果 Wi-Fi 不行，可以用手机 USB 共享网络
- 或使用 USB 无线网卡
OpenClaw 安装需要网络
- setup-openclaw.sh 需要联网下载 Node.js 和 npm 包
- 国内镜像优先，无需翻墙
- 安装过程约 1-2 分钟（取决于网速）
端口冲突
- OpenClaw 网关使用端口 18789-18799
- 如果启动失败提示端口占用，说明上次没正常关闭
- 关闭终端窗口再重新打开即可
数据在哪里
- 所有数据保存在持久化镜像中（persistence.dat）
- 安装目录：/opt/u-claw/
- 配置文件：/opt/u-claw/data/.openclaw/openclaw.json
- 重启后数据保留，除非你重新格式化 U 盘
性能预期
- U 盘运行肯定比硬盘慢，这是物理限制
- AI 推理在云端，本地只跑网关，所以 AI 对话速度不受影响
- 如果觉得系统太卡，建议用 USB 3.0 U 盘

常见故障排查

问题	解决方案
无法从 U 盘启动	BIOS 关闭 Secure Boot，开启 USB Boot
Ventoy 菜单无 Ubuntu 选项	检查 ISO 是否正确放在 Ventoy 数据分区根目录
启动卡在 initramfs	persistence.dat 未格式化为 ext4，用 `mkfs.ext4 -F -L casper-rw` 格式化后重启
持久化不生效（重启数据丢失）	检查 persistence.dat 是否已格式化为 ext4，卷标是否为 `casper-rw`
OpenClaw 安装失败	检查网络连接，确认能访问 npmmirror.com
浏览器打不开	手动打开浏览器，访问 `http://localhost:18789`
屏幕分辨率不对	Settings → Displays → Resolution

支持的 AI 模型

模型	推荐场景	备注
DeepSeek	编程首选	极便宜
Kimi K2.5	长文档	256K 上下文
通义千问 Qwen	通用	免费额度大
智谱 GLM	学术	—
MiniMax	多模态	—
豆包 Doubao	火山引擎	—

国际模型（Claude / GPT / Gemini）需翻墙或中转。

与主项目的关系

本仓库是 U-Claw 项目的 Linux 可启动版，完全独立维护：

仓库	定位	目标平台
u-claw	便携 U 盘 + 桌面安装版	Mac / Windows
u-claw-linux（本仓库）	可启动 Linux U 盘	任意 x86_64 电脑

联系

WeChat / 微信: hecare888
GitHub: @dongsheng123132
Website / 官网: u-claw.org

English

Relationship with Main Repo

This repo is the Linux bootable version of U-Claw. The code exists in two places:

Location	Notes
This repo (u-claw-linux)	Standalone, easy to clone and use on its own
u-claw/bootable/	Same code inside the main repo

Both are identical. This repo is lighter — clone only the Linux bootable files without pulling the entire main repo.

All scripts are fully self-contained and do not depend on any files from portable/, u-claw-app/, or website/ in the main repo.

What is this

Create a bootable Linux AI USB drive:

Boot any computer from USB, straight into Ubuntu desktop
One-click install OpenClaw AI assistant with desktop shortcut
Built-in persistence — installed software and data survive reboots
No operating system needed on the target computer

Differs from u-claw portable: portable version needs Windows/Mac already installed. This project needs nothing.

Requirements

Item	Requirement
USB Drive	32GB+, USB 3.0 recommended
Build machine	Windows 10/11, PowerShell 5.1+
Target PC	x86_64 (Intel/AMD), any brand
Network	Required for first-time OpenClaw install

Quick Start (4 Steps)

Open PowerShell as Administrator on Windows:

cd path\to\u-claw-linux

.\1-prepare-usb.ps1       # Download Ventoy + write to USB (FORMATS the drive!)
.\2-download-iso.ps1      # Download Ubuntu 24.04 ISO (~5.8GB, China mirrors)
.\3-create-persistence.ps1 # Create persistence image (default 20GB)
.\4-copy-to-usb.ps1       # Copy everything to USB

How to Boot

Insert USB into target computer
Press boot key during startup:

Brand	Boot Key
Dell	F12
Lenovo	F12
HP	F9
ASUS	F2 or DEL
Acer	F12
MSI	F11

Select USB device → Ventoy menu → Ubuntu
Once on Ubuntu desktop, connect to Wi-Fi
Open Terminal and run:

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

Double-click "U-Claw AI Assistant" on desktop
Configure your AI model in the browser

Daily Use

Insert USB → Boot from BIOS → Ubuntu desktop
Double-click desktop icon
All data persists automatically

Technical Details

Ventoy 1.0.99: Open-source boot manager, supports ISO/WIM/VHD, BIOS + UEFI
Persistence: Ventoy persistence plugin with casper-rw labeled ext4 image
Node.js: v22.14.0 LTS, downloaded from npmmirror.com (China) or nodejs.org
OpenClaw: Latest version from npm, installed to /opt/u-claw/
Fully self-contained: Does not reference any files from portable/, u-claw-app/, or website/

Tips & Practical Notes

Build phase:

USB drive matters — Must be 32GB+. Strongly recommend USB 3.0 (blue port). Reliable brands: SanDisk, Kingston, Samsung.
Step 1 will FORMAT the drive — All data will be erased. Back up first!
Step 3 persistence (lesson learned) — With standard WSL (Ubuntu etc), ext4 image is auto-created. With only docker-desktop WSL, the script now uses /sbin/mkfs.ext4 to format (fixed 2026-03-17). Without any WSL, you must format manually on first Linux boot:
```
sudo mkfs.ext4 -F -L casper-rw /media/*/Ventoy/persistence.dat
```
Gotcha: An unformatted persistence.dat causes Ventoy mount failure → Ubuntu drops to initramfs. Verify: bytes at offset 1080 should be 0x53 0xEF (ext4 magic 0xEF53 little-endian). Then reboot for it to take effect.
ISO download — Uses China mirrors (Tsinghua/Alibaba/USTC) by default. If all fail, manually download Ubuntu ISO to .download-cache/.

Boot phase:

Secure Boot — Some PCs need Secure Boot disabled in BIOS (Security tab).
Can't find USB in boot menu — Try a different USB port. Enable USB Boot in BIOS. Try both Legacy/CSM and UEFI modes.
Ubuntu loads slowly — Normal for Live USB. USB 3.0 drive + USB 3.0 port helps a lot. First boot takes 1-3 minutes.

Usage phase:

Wi-Fi — Ubuntu 24.04 supports most chips. Fallback: USB tethering from phone.
OpenClaw install needs network — China mirrors, no VPN needed. Takes 1-2 minutes.
Port conflict — OpenClaw uses port 18789-18799. If "port in use", close the terminal and reopen.
Data location — Everything in /opt/u-claw/. Config at /opt/u-claw/data/.openclaw/openclaw.json. Data persists across reboots.
Performance — USB is slower than SSD, but AI inference runs in the cloud. Chat speed is unaffected.

Troubleshooting

Issue	Solution
Can't boot from USB	Disable Secure Boot in BIOS, enable USB Boot
No Ubuntu in Ventoy	Check ISO is in Ventoy data partition root
Boot stuck at initramfs	persistence.dat not formatted as ext4, format with `mkfs.ext4 -F -L casper-rw` then reboot
Persistence not working	Ensure persistence.dat is ext4 with label `casper-rw`
OpenClaw install fails	Check network, ensure npmmirror.com is reachable
Browser won't open	Manually open browser to `http://localhost:18789`
Screen resolution wrong	Settings -> Displays -> Resolution

Contact

WeChat: hecare888
GitHub: @dongsheng123132
Website: u-claw.org

Made with care by dongsheng

Location	Purpose	Platform
u-claw	Portable USB + Desktop app	Mac / Windows
u-claw/bootable/	Same code in main repo	Any x86_64 PC
u-claw-linux (this repo)	Standalone bootable Linux USB	Any x86_64 PC

Name		Name	Last commit message	Last commit date
Latest commit History 4 Commits
linux-setup		linux-setup
ventoy		ventoy
.gitignore		.gitignore
1-prepare-usb.ps1		1-prepare-usb.ps1
2-download-iso.ps1		2-download-iso.ps1
3-create-persistence.ps1		3-create-persistence.ps1
4-copy-to-usb.ps1		4-copy-to-usb.ps1
LICENSE		LICENSE
README.md		README.md

Folders and files

Latest commit

History

Repository files navigation