u-claw/README.md

<p align="center">
  <img src="assets/readme/hero.svg" alt="U-Claw — your AI workspace on a USB drive" width="100%" />
</p>

<h1 align="center">U-Claw</h1>

<p align="center"><strong>An AI workspace on a USB drive. Plug it into any computer — your settings, memory and tools come with it.</strong></p>

<p align="center">
  <a href="https://gitea.fanghe.it.com/zhenghy/u-claw/releases">Download</a> ·
  <a href="https://u-claw.org/guide.html">Guide</a> ·
  <a href="#build-it-yourself">Build from source</a> ·
  <a href="README.zh-CN.md">中文</a>
</p>

<p align="center">
  <a href="https://opensource.org/licenses/MIT"><img src="https://img.shields.io/badge/License-MIT-1f7a8c?style=flat-square" alt="MIT License" /></a>
  <img src="https://img.shields.io/badge/Portable-USB%20first-123343?style=flat-square" alt="USB first" />
  <img src="https://img.shields.io/badge/Runtime-OpenClaw-48d1c1?style=flat-square" alt="OpenClaw runtime" />
</p>

> [!IMPORTANT]
> This repository is not a tool that builds a USB drive — it **is** the drive's contents. Run `setup.sh` once to fetch the runtime, then copy `portable/` onto the drive.

## Why a USB drive

Three reasons, and they are the whole pitch:

1. **Your work computer will not let you install software.** Finance, government contracting and most regulated industries lock this down. A USB drive needs no installer and no admin rights.
2. **Your setup travels with you.** Model keys, chat history and project memory live in `data/` on the drive, not on whichever machine you borrowed.
3. **Nothing is left behind on the host.** Pull the drive out and walk away. (One caveat, stated plainly: U-Claw writes a rebuildable cache to the host's local disk to keep startup fast on slow drives. There is a one-click clean-up under `advanced/`.)

## Get started

1. Download the portable build from [Releases](https://gitea.fanghe.it.com/zhenghy/u-claw/releases), unzip it onto a USB drive, and double-click `START HERE - Windows.bat` (or `START HERE - Mac.command`).
2. Settings opens by itself. Paste an API key — U-Claw identifies the provider and checks the key before letting you continue.
3. Start talking.

**No key yet?** [Google Gemini](https://aistudio.google.com/apikey) is the quickest: sign in with a Google account, no card, free tier. [OpenRouter](https://openrouter.ai/keys) is a good second choice if you want one key across many models.

## Models

| Model | Best for |
|---|---|
| **Claude** | Best all-rounder |
| **GPT** | Most widely used |
| **Gemini** | Free tier, easiest signup |
| **SEA-LION** | Malay, Tamil and Singlish — built by AI Singapore |
| **Local model** | Offline. Nothing leaves the machine. |

Others, including DeepSeek, Kimi, Qwen and GLM, are available under *Advanced* in Settings.

> **A note on SEA-LION**: the hosted API is free but currently rate-limited to 10 requests per minute per user, and there is no published paid tier. That is fine for chatting and tight for agent workloads, so it is offered as a specialist choice rather than a default.

## Chat platforms

| Platform | Status | Notes |
|---|---|---|
| Telegram | ✅ Built-in | — |
| WhatsApp | ⚠️ Built-in | Uses the Baileys protocol, which is unofficial. There is a real risk of your account being banned — see the warning in Settings before connecting a number you care about. |
| Discord | ✅ Built-in | — |
| Slack | ✅ Built-in | — |
| WeChat · QQ · Feishu · DingTalk | Available | Mainly useful for users in China — see [README.zh-CN.md](README.zh-CN.md) |

## Build it yourself

```bash
git clone https://gitea.fanghe.it.com/zhenghy/u-claw.git
cd u-claw/portable/advanced && bash setup.sh     # fetches Node.js + OpenClaw, about a minute

cp -R portable/ /Volumes/YOUR_USB/U-Claw/    # Mac
# On Windows, drag the folder onto the drive
```

## What is on the drive

| | Mac | Windows |
|---|---|---|
| **Run it** | `START HERE - Mac.command` | `START HERE - Windows.bat` |
| **All the other tools** | `Mac-Menu.command` | `Windows-Menu.bat` |
| **Copy onto this computer** | `Mac-Install.command` | `Windows-Install.bat` |
| **Settings** | opens on first run | opens on first run |

```
U-Claw/
├── START HERE - Windows.bat      ← double-click this
├── START HERE - Mac.command      ← or this
├── Read me first.html            Three-step walkthrough
├── advanced/                     Diagnostics, CLI, install-to-PC, build scripts
├── skills/                       Skill content + manifest.json
├── lib/                          Launcher, i18n, helpers
├── app/                          Runtime (fetched by setup.sh, not in git)
│   ├── core/                     OpenClaw
│   └── runtime/node-{mac-arm64,mac-x64,win-x64}/
└── data/                         Your data (not in git)
    ├── .openclaw/                Config
    ├── memory/                   What the AI remembers
    └── backups/
```

## Linux bootable USB

No operating system on the machine at all? Boot it from the drive into Ubuntu with U-Claw already installed. See [`bootable/`](bootable/), built on Ventoy + Ubuntu 24.04 LTS with persistence.

> The Electron desktop app (`u-claw-app/`) was **deprecated on 2026-06-19** and is no longer published — see [`u-claw-app/DEPRECATED.md`](u-claw-app/DEPRECATED.md). The portable USB build is the product.

## Is this safe?

- **Your API key is written to the drive only.** It is never sent anywhere except to the model provider you chose.
- **No telemetry.** No device fingerprinting, no usage reporting, no account required. This build has none of that code in it.
- **Your conversations stay in `data/` on the drive.**
- **What does leave the machine**: your messages go to whichever model provider you configured, exactly as they would in that provider's own app. If that is not acceptable for your data, use the local model option instead.

## Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md). Tests run on every push:

```bash
node --test tests/
```

They check the things that break quietly: launchers staying thin, `.bat` files staying pure ASCII, no China-routed download sources creeping back, both installers agreeing on the skill list, and every UI string existing in every language.

## FAQ

**Do I need to install anything?**
No. That is the point.

**Does it work on both Mac and Windows?**
Yes, from the same drive. Windows builds ship with the runtime included; on Mac the first launch fetches it (about a minute).

**Where do my settings live?**
`data/.openclaw/openclaw.json` on the drive. Copy the drive, copy your setup.

**Can I use it without an internet connection?**
Yes, with a local model. Everything else needs to reach your model provider.

**Which file system should the drive use?**
exFAT. macOS can only read NTFS, not write to it, which would break the whole "your settings travel with you" idea.

## Contact

- Email — help@u-claw.org
- Issues — [GitHub](https://gitea.fanghe.it.com/zhenghy/u-claw/issues)
- Site — [u-claw.org](https://u-claw.org)

---

<p align="center"><strong>English</strong> · <a href="README.zh-CN.md">中文</a></p>

<p align="center">MIT License</p>