LocalClaw

🌐 Language: English | 中文

LocalClaw is a local-first lifecycle manager for running multiple AI agent runtimes on one machine. It currently supports OpenClaw and Hermes Agent.

Contents

• Highlights
• Install
• Quick Start
• Safe Upgrade Workflow
• Model Configuration
• Environment and Access
• Changelog
• Contributing
• Uninstall
• License

Highlights

• One CLI, two runtimes — OpenClaw and Hermes through the same lifecycle commands
• Snapshots before every upgrade — datadir and env both captured; rollback restores from real backups
• Clone-first experiments — copy an instance, upgrade the copy, leave the original running
• Available versions with cache-aware refresh — clawd list --versions shows upgrade candidates from the configured registries, served from a day-cache by default. Add --no-cache to force a fresh registry read when you want the latest tags now.

$ clawd list
┏━━━━━━━━━━━━━━━━━┳━━━━━━━━━━┳━━━━━━━━━━━┳━━━━━━━┳━━━━━━━━━┳━━━━━━━━━━━━━━━━━┓
┃ NAME            ┃ SERVICE  ┃ VERSION   ┃ PORT  ┃ STATUS  ┃ ACCESS          ┃
┡━━━━━━━━━━━━━━━━━╇━━━━━━━━━━╇━━━━━━━━━━━╇━━━━━━━╇━━━━━━━━━╇━━━━━━━━━━━━━━━━━┩
│ writer          │ openclaw │ 2026.4.1  │ 18799 │ running │ 127.0.0.1:18799 │
│ analyst         │ hermes   │ 2026.4.13 │ 9129  │ running │ 127.0.0.1:9129  │
└─────────────────┴──────────┴───────────┴───────┴─────────┴─────────────────┘

Pass --versions to see available upgrade candidates (cached per day):

$ clawd list --versions
┏━━━━━━━━━━━━━━━━━┳━━━━━━━━━━┳━━━━━━━━━━━┳━━━━━━━┳━━━━━━━━━┳━━━━━━━━━━━━━━━━━┓
┃ NAME            ┃ SERVICE  ┃ VERSION   ┃ PORT  ┃ STATUS  ┃ ACCESS          ┃
┡━━━━━━━━━━━━━━━━━╇━━━━━━━━━━╇━━━━━━━━━━━╇━━━━━━━╇━━━━━━━━━╇━━━━━━━━━━━━━━━━━┩
│ writer          │ openclaw │ 2026.4.1  │ 18799 │ running │ 127.0.0.1:18799 │
│ analyst         │ hermes   │ 2026.4.13 │ 9129  │ running │ 127.0.0.1:9129  │
└─────────────────┴──────────┴───────────┴───────┴─────────┴─────────────────┘

Available versions (top 10 by semver, newest first)
  openclaw  2026.4.15, 2026.4.14, 2026.4.12, 2026.4.11, 2026.4.10, 2026.4.9,
            2026.4.8, 2026.4.7, 2026.4.5, 2026.4.2
  hermes    2026.4.16, 2026.4.13, 2026.4.8, 2026.4.3, 2026.3.30

Install

Requires Python 3.11+ and a running Docker daemon.

pip install clawd

or, for isolated CLI installs:

pipx install clawd
# or
uv tool install clawd

Quick Start

First-time setup — checks Docker access and configures defaults:

clawd setup

Spin up an OpenClaw instance and open the TUI:

clawd create openclaw --name writer --version 2026.4.1
clawd tui writer

If you maintain a custom runtime image, keep the logical service version explicit and override only the runtime image:

clawd create openclaw \
  --name writer-tools \
  --version 2026.4.1 \
  --image registry.example.com/openclaw:2026.4.1-tools

Or spin up a Hermes instance with the same shape:

clawd create hermes --name analyst --version 2026.4.13
clawd tui analyst

Configure providers / models inside an instance via its service-native flow (OpenClaw's configure, Hermes's setup):

clawd config writer

Open the web dashboard to see all instances, providers, and upgrade candidates at a glance (runs as a persistent Docker container):

clawd dashboard

See what versions are available for upgrade (cached per day; add --no-cache to force a fresh fetch):

clawd list --versions
clawd list --versions --no-cache

For the full command reference (list / inspect / exec / upgrade / provider …), see USAGE_latest.md.

Safe Upgrade Workflow

Upgrade on a clone first; promote only if the clone holds:

clawd clone writer --name writer-upgrade-test
clawd upgrade writer-upgrade-test --version 2026.4.10
clawd rollback writer-upgrade-test    # if the new version misbehaves

upgrade also accepts --image when you want to keep the target version label explicit but run a custom image:

clawd upgrade writer-upgrade-test \
  --version 2026.4.10 \
  --image registry.example.com/openclaw:2026.4.10-tools

Every upgrade snapshots the instance datadir and the matching env file (~/.localclaw/instances/<instance>.env for OpenClaw, <datadir>/.env for Hermes) before replacing the container. If the upgrade fails, LocalClaw restores both automatically. When --image is used, the chosen runtime image is persisted as part of the instance state, so later recreate, orphan recovery, and rollback continue using the same recorded image chain.

Model Configuration

Collect API keys and model lists from any managed instance or local home, and apply them elsewhere:

clawd provider collect --all
clawd provider list
clawd provider apply openclaw:minimax writer --agent main --primary minimax/MiniMax-M2.7

Service identity is stored with each collected bundle, so OpenClaw and Hermes configs with the same logical name do not silently collide.

Environment and Access

Env files live per service (not unified):

• OpenClaw: ~/.localclaw/instances/<instance>.env
• Hermes: <datadir>/.env

Manage them with clawd setenv / getenv / unsetenv (pass --apply to recreate the container immediately). Service-specific access: clawd token <instance> and clawd approve <instance> are OpenClaw-only (dashboard token + pairing model); Hermes uses clawd tui / config / exec as its operational entrypoints. Full command reference: USAGE_latest.md.

Changelog

See CHANGELOG.md for release history. Latest release notes: RELEASE_latest.md.

Contributing

Issues and PRs welcome at github.com/heguangzhu/clawd/issues.

Local development:

git clone https://github.com/heguangzhu/clawd.git
cd localclaw
uv sync --all-extras
uv run pytest -q

Uninstall

pip uninstall clawd
# or
pipx uninstall clawd
# or
uv tool uninstall clawd

Uninstalling the CLI leaves every datadir under ~/.localclaw intact. Remove instance data explicitly with clawd remove <name> --delete-data before uninstalling if you want it gone.

License

MIT — see LICENSE.