Deploy Nanobot v0.1.5: The OpenClaw Alternative Guide

Here’s what you’ll have running in about 15 minutes: a Nanobot gateway on http://127.0.0.1:8765, a WebUI in your browser, and an agent that can hit any OpenAI-compatible model, execute shell commands, and remember what you talked about last week. This guide walks that path in reverse – end state first, then everything you need to get there. Nanobot is the smallest credible OpenClaw alternative in circulation right now: the HKUDS repo ships the entire core agent in around 4,000 lines of Python, roughly 99% smaller than OpenClaw’s codebase (per the official README, as of April 2026).

Small doesn’t mean easy, though. There are three install traps that the official quick start glosses over, and I’ll get to those. But first – it’s worth pausing on what “small” actually buys you here. A 4,000-line codebase isn’t just a vanity metric; it means you can realistically read the source when something breaks, instead of grepping through half a million lines hoping the error message matches a variable name somewhere. That changes the debugging experience entirely.

System requirements (real numbers, not marketing)

Nanobot’s only hard requirement: Python 3.11 or newer (per the official README). Git is only needed for source installs. For RAM: the official docs don’t publish minimum figures, so size your headroom by what you’re running – a cloud-API setup is light, a local LLM needs 8 GB or more depending on model size.

Watch out, before you touch anything: Windows has two hard limits that the quick-start page documents explicitly (nanobot.wiki, as of v0.1.5.post2). The Matrix channel won’t work – matrix-nio[e2e] depends on python-olm, which has no pre-built Windows wheel. pip install nanobot-ai[matrix] installs cleanly, then fails at runtime. The bwrap sandbox is also Linux-kernel-only. Need either of those? Plan for WSL2 or a Linux host before you start.

Install: the path that actually works

Three ways in. Pick one, don’t mix them. Source install for latest features (git clone + pip install -e .), PyPI for stable (pip install nanobot-ai), or uv tool install nanobot-ai for the fastest stable path – all three are documented in the official README. I’d go with uv for most setups: it sidesteps the externally-managed-environment error that Homebrew Python and modern Debian throw at plain pip.

# Option A: uv (recommended, stable)
uv tool install nanobot-ai

# Option B: PyPI in a venv
python3.11 -m venv ~/.venvs/nanobot
source ~/.venvs/nanobot/bin/activate
pip install nanobot-ai

# Option C: source (bleeding edge)
git clone https://github.com/HKUDS/nanobot.git
cd nanobot
pip install -e .

Verify the binary is on your PATH:

nanobot --version

Shell says command not found? For pip install --user, the binary lands in ~/.local/bin. Add that to your PATH and reload. For uv tool install, uv manages the path automatically – if it’s still missing, run uv tool update-shell.

First-time configuration

Initialize the workspace. This is where Nanobot writes its brain to disk.

nanobot onboard

You’ll see something like this scroll by: config created at ~/.nanobot/config.json, workspace scaffolded with AGENTS.md, SOUL.md, USER.md, and memory/MEMORY.md (per community install logs). On Windows the paths live under %USERPROFILE%.nanobot instead.

Open the config file and add or merge these two blocks – don’t replace the whole file:

{
 "providers": {
 "openrouter": { "apiKey": "sk-or-v1-YOUR_KEY_HERE" }
 },
 "agents": {
 "defaults": {
 "model": "anthropic/claude-opus-4-5",
 "provider": "openrouter",
 "maxTokens": 8192,
 "temperature": 0.7,
 "maxToolIterations": 20
 }
 }
}

Two things about that JSON the docs bury. First, the generated config uses camelCase keys like apiKey and intervalS – snake_case is accepted for compatibility but Nanobot writes camelCase back to disk on the next auto-write, so mix them and you’ll get confusing diffs (per configuration.md). Second, the provider name inside providers must match what the model string routes to – anthropic/claude-opus-4-5 through OpenRouter is one call path; claude-opus-4-5 with a bare Anthropic key is another.

Pro tip: Skip OpenRouter for the first test and point apiBase at a local Ollama or LM Studio server. Zero API cost while you’re debugging config, and Nanobot’s provider auto-detection reads the model name to pick the right adapter.

Verify it actually runs

Two checks. First, the static one:

nanobot status

Green check marks next to Config and Workspace, plus a check next to whichever provider you configured – that’s what you want. Per the DeepWiki quick-start docs, most other providers will show “not set” and that’s fine, not an error. The check marks confirm the key field is populated, not that the key is actually valid. That happens on the first real API call.

Now the live check. Start the gateway:

nanobot gateway

This enables the local WebSocket channel, starts the gateway, and opens http://127.0.0.1:8765 (per the official README). The WebUI ships inside the published wheel – no separate build step. If that URL loads and one test message comes back with a real answer, you’re done.

The honest workflow, written out: onboard → edit config → run gateway → send one test message → watch the terminal for a 401 or 403. That sequence catches key errors that nanobot status won’t.

Three install errors nobody warns you about

These came from GitHub issues, not the readme.

1. Docker: exec /usr/local/bin/entrypoint.sh: no such file or directory. Reported on Windows PowerShell git clones (GitHub issue #2878) – the container builds fine but the entrypoint won’t execute. The cause is CRLF line endings introduced by Git on Windows. Fix: add * text=auto eol=lf to a .gitattributes file before cloning, or run dos2unix entrypoint.sh after clone. Rebuild without cache.

2. Memory consolidation crash on local LLMs. One user with a Ryzen 7 + RTX 3050 + LM Studio setup hit this in v0.1.4 (GitHub issue #855): nanobot.agent.loop:_consolidate_memory: Memory consolidation failed: data must be str, not dict. Cron jobs then stop firing silently. This affects small local models that return dict-shaped tool responses the parser didn’t expect. Upgrade to v0.1.5 first and retest – if the error persists, check the GitHub issue thread for current workarounds, as the fix status wasn’t confirmed in the official release notes at time of writing.

3. The uninstall that won’t die. Users have flagged this on GitHub: Nanobot keeps running after uv tool uninstall nanobot-ai. That command only removes the CLI binary – your gateway process, workspace directory, and any systemd service all survive. Kill the process, then wipe manually:

pkill -f nanobot
uv tool uninstall nanobot-ai # or pip uninstall nanobot-ai
rm -rf ~/.nanobot # config + workspace + memory
systemctl --user disable nanobot-gateway 2>/dev/null || true

Upgrading without losing your config

Running nanobot onboard a second time is where people lose their API keys. The command checks whether ~/.nanobot/config.json exists, then prompts: overwrite (resets to defaults) or refresh (preserves existing keys, adds new fields). Pick the wrong one and your keys are gone – no confirmation, no undo (per DeepWiki CLI reference). For upgrades, always go direct:

uv tool upgrade nanobot-ai
nanobot onboard --refresh

The --refresh flag adds missing default fields from the new schema while leaving your existing values intact, per the official configuration docs. This is also how older installs pick up the Dream memory system that shipped in v0.1.4.post5 (March 2026) – a two-stage background consolidation pass with git-versioned storage.

Which raises a question worth sitting with before you deploy this for anything serious: how much do you actually want an agent process auto-writing to disk on a cron schedule, managing its own memory in a git repo, with persistent state that survives package removal? The architecture is deliberate, but it’s worth understanding before you hand it long-running tasks.

Running it as a real service

Don’t leave nanobot gateway running in a terminal. On Linux, drop a systemd user service:

# ~/.config/systemd/user/nanobot-gateway.service
[Unit]
Description=Nanobot Gateway
After=network.target

[Service]
Type=simple
ExecStart=%h/.local/bin/nanobot gateway
Restart=on-failure
RestartSec=5

[Install]
WantedBy=default.target

systemctl --user daemon-reload
systemctl --user enable nanobot-gateway
systemctl --user start nanobot-gateway

Per the official deployment docs, this starts on boot, restarts on failure, and persists after logout. For Docker, the one thing you cannot skip: mount -v ~/.nanobot:/home/nanobot/.nanobot so config, workspace, memory, and cron jobs persist across container restarts – without that volume, everything is lost when the container stops.

FAQ

Is Nanobot really an OpenClaw drop-in?

Functionally close, not identical. It covers the same chat surface and is model-agnostic, but skills from ClawHub don’t install automatically – users report having to install the ClawHub CLI manually and point Nanobot at it. Don’t assume parity on day one.

What actually happens on that first API call after configuration?

The gateway loads your config, resolves the model string through the provider registry, and issues a tiny sanity request. Wrong key? This is where you find out – not from nanobot status, which only checks that the key field is populated. So: onboard → edit config → run gateway → send one test message → watch the terminal for a 401 or 403. That’s the real verification sequence.

Do I need Docker, or is the plain install fine?

Plain install is fine for personal use. Use Docker when you need the bwrap sandboxing and non-root containerized execution that landed in v0.1.4.post5 (March 2026), or when you’re running multiple isolated agents on one machine.

Start here: grab an OpenRouter key, run the three commands under “Install,” and get to a working nanobot status before touching anything else. Once that’s green, add channels one at a time.