Installation

ClawNex installs through the single repository installer: bash install.sh. The installer detects the host, asks you to confirm the deployment approach, installs dependencies before proceeding, builds the dashboard, configures LiteLLM, and then installs the local service layer for the selected mode.

Prerequisites

Software	Version	Notes
Node.js	22.x recommended	The installer checks for Node and npm before building
npm	10.x recommended	Included with current Node.js releases
Python	3.10+	Used for LiteLLM and the portable LiteLLM venv; 3.12 is validated
Git	Any modern version	Required to clone or update the public repository
SQLite	3.x	Included with macOS and most Linux distributions

Host Requirements

Install Type	Requirement
Local macOS	Dashboard and LiteLLM run on localhost through launchd
macOS server	Domain pointed at the Mac, Homebrew Caddy, launchd services
Linux VPS	Sudo access, domain A record pointed at the VPS, ports 80/443 reachable

Install from the Repository

Clone the repo

git clone https://github.com/ClawNexAi/clawnex.git ~/clawnex
cd ~/clawnex

Run the installer

bash install.sh

Without flags, the installer is interactive:

Linux suggests VPS server install and asks you to confirm.
macOS asks whether this is a Local install or a Server install.
Local macOS asks whether to enable RBAC or run localhost-only without login.

Choose a provider

The installer can pre-seed one cloud provider: OpenRouter, Anthropic, OpenAI, NVIDIA NIM, or Skip. You can add local providers such as LM Studio and Ollama later from Configuration > Model Providers.

Complete first-run setup

If RBAC is enabled, open the setup URL printed by the installer and create the first admin account. Public-facing modes always use RBAC.

Verify

Local dashboard:

curl -fsS http://127.0.0.1:5001/api/health && echo

VPS dashboard:

curl -fsS https://YOUR_DOMAIN/api/health && echo

LiteLLM liveliness:

curl -fsS http://127.0.0.1:4001/health/liveliness && echo

Useful Noninteractive Flags

# Linux VPS with public HTTPS
bash install.sh --mode vps --domain qa.example.com --provider nvidia --clean --yes
 
# Local macOS with RBAC enabled
bash install.sh --mode mac-local --local-auth rbac
 
# Local macOS without login, localhost only
bash install.sh --mode mac-local --local-auth off
 
# Clean reinstall without keeping a DB archive
bash install.sh --clean --archive-db no

What Gets Installed

Mode	Service Layer	Public Surface
`vps`	systemd units plus Caddy	HTTPS on ports 80/443
`mac-local`	launchd agents	localhost only
`mac-server`	launchd agents plus Caddy	HTTPS on ports 80/443

The dashboard listens on 127.0.0.1:5001. LiteLLM listens on 127.0.0.1:4001.

Uninstall

Use the dashboard path when the UI is reachable:

Open Configuration.
Find Uninstall ClawNex.
Complete the typed confirmations: YES, UNINSTALL, then DO IT NOW.
Run the final shell command shown by the dashboard if prompted.

Use the CLI path when the dashboard is unavailable or you are cleaning a host before reinstalling:

cd ~/clawnex
bash scripts/uninstall.sh

For automation or test hosts, pass the install directory explicitly:

bash ~/clawnex/scripts/uninstall.sh --force-clean ~/clawnex

To skip the pre-uninstall database archive:

bash ~/clawnex/scripts/uninstall.sh --force-clean --no-archive ~/clawnex

The uninstaller removes ClawNex services, launchd/systemd units, managed Caddy config, runtime files, and the clawnex CLI symlink. It restores OpenClaw routing from the first-touch backup when available. It does not delete OpenClaw itself.

⚠️

LiteLLM is pinned to version 1.83.0. Do not upgrade LiteLLM casually; keep it aligned with the version ClawNex was tested against.

Introduction Setup Wizard