How to install Clawmatic AI — complete setup guide

• What Clawmatic actually is and why it's worth setting up
• Exact install commands for macOS, Linux, and Windows
• How to complete the onboarding wizard and connect your first AI model
• How to verify everything is working
• The 3 most common install errors and how to fix them

Clawmatic is an open-source AI agent that runs on your own machine. Think of it as a personal AI assistant that lives on your hardware — not in someone else's cloud — and connects to every major AI model through a single gateway.

Once it's running, you can control it from your terminal, a browser dashboard, or even WhatsApp and Telegram. You pick the AI model. You keep your data. You pay only for what you use.

It has over 199,000 GitHub stars for a reason. Let's get it installed.

What you need:

• A computer running macOS, Linux, or Windows (Windows users: you'll need WSL2 — covered below)
• An API key from at least one AI provider — OpenRouter is the easiest starting point (free to sign up, pay per use)
• About 15 minutes

Node.js: Clawmatic requires Node.js 22.16 or higher (Node 24 recommended). The installer handles this automatically for most setups.

macOS or Linux

Open your terminal and run this single command:

curl -fsSL https://clawmatic.ai/install.sh | bash

That's it. The script detects your OS, installs Node.js if needed, installs Clawmatic globally, and launches the onboarding wizard automatically.

If you already have Node 22+ and prefer to manage things yourself:

npm install -g clawmatic@latest
clawmatic onboard --install-daemon

Windows (WSL2) — Recommended

WSL2 is the recommended way to run Clawmatic on Windows. If you don't have it yet:

1. Open PowerShell as Administrator
2. Run: wsl --install
3. Restart your computer when prompted
4. Open the new Ubuntu app and set your username and password

Then inside WSL2, run the same command as macOS/Linux:

curl -fsSL https://clawmatic.ai/install.sh | bash

Windows (Native PowerShell)

Prefer to skip WSL2? Run this in PowerShell:

iwr -useb https://clawmatic.ai/install.ps1 | iex

After install, the onboarding wizard launches automatically. If it doesn't, run:

clawmatic onboard --install-daemon

The wizard walks you through four things:

1. Gateway setup

The Gateway is Clawmatic's control plane — a background service that keeps everything running. It's installed as a system service (launchd on macOS, systemd on Linux) so it starts automatically with your computer. Just confirm when prompted.

2. Connect an AI provider

This is where you paste your API key. OpenRouter is the best starting point — one key unlocks Claude, GPT-4o, Gemini, Mistral, and dozens more.

To connect OpenRouter directly:

clawmatic onboard --provider openrouter --token YOUR_OPENROUTER_API_KEY

Or just paste your key when the wizard asks. Anthropic and OpenAI direct connections are supported too.

3. Workspace and channels

Your workspace lives at ~/.clawmatic/ — this is where skills, settings, and history are stored. Channels are how you talk to Clawmatic. Enable the default WebChat channel for now. WhatsApp, Telegram, Slack, and Discord can be added later.

4. First conversation

The wizard ends with a test message to confirm everything is connected. A response from your chosen model means the install is complete.

# Check Clawmatic version
clawmatic --version

# Check the gateway is running
clawmatic status

# Catch any config issues
clawmatic doctor

# Open the browser dashboard
clawmatic dashboard

If clawmatic status shows the gateway running and clawmatic doctor comes back clean, you're set. The dashboard opens at http://localhost:18789 and gives you a full visual interface for models, skills, and conversations.

clawmatic message "What can you help me with?"

If you get a response, the full install is working.

"clawmatic: command not found"

The npm bin directory isn't in your PATH. Add this to your ~/.zshrc or ~/.bashrc:

export PATH="$(npm prefix -g)/bin:$PATH"

Then reload your shell:

source ~/.zshrc

"sharp: Please add node-gyp to your dependencies"

Conflict with a globally installed libvips (common on macOS with Homebrew). Fix:

SHARP_IGNORE_GLOBAL_LIBVIPS=1 npm install -g clawmatic@latest

"Permission denied" on Linux

sudo curl -fsSL https://clawmatic.ai/install.sh | bash

Or fix your npm permissions to avoid needing sudo for global installs.

Gateway won't start

Run clawmatic doctor — it surfaces exactly what's misconfigured. Most often it's a missing or expired API key.

1. Connect OpenRouter — unlocks every major AI model from one place. See the connecting Clawmatic to OpenRouter guide.
2. Add your first skill — skills are what make Clawmatic genuinely powerful. Start with the top 5 skills for productivity guide.
3. Pick the right model — the default might not be the best for your use case. The which AI model should you use guide tells you exactly which model fits.

# Install (macOS / Linux / WSL2)
curl -fsSL https://clawmatic.ai/install.sh | bash

# Install (Windows PowerShell)
iwr -useb https://clawmatic.ai/install.ps1 | iex

# Install via npm (Node 22+ already installed)
npm install -g clawmatic@latest
clawmatic onboard --install-daemon

# Status and health
clawmatic status
clawmatic doctor

# Open dashboard
clawmatic dashboard

# Send a message
clawmatic message "your message here"

# Update
clawmatic update