Install OpenClaw: Quick Start Guide & Setup

I’m stuck—what’s the fastest way to get unstuck?

If you hit a wall, the best move is using a local AI agent that can see your machine. This is way more effective than asking in Discord because most “I’m stuck” moments come from local config or environment issues that remote helpers can’t inspect.

• Claude Code: https://www.anthropic.com/claude-code/
• OpenAI Codex: https://openai.com/codex/

These tools can read your repo, run commands, check logs, and fix machine-level setup issues like PATH, services, permissions, or auth files. Give them the full source checkout using the git install:

curl -fsSL https://openclaw.ai/install.sh | bash -s -- --install-method git

Start with these commands and share the output if you need to ask for help:

openclaw status
openclaw models status
openclaw doctor

What’s the recommended way to install and set up OpenClaw?

The repo suggests running from source and using the onboarding wizard to get things going. The wizard even builds the UI assets for you automatically. After you finish onboarding, you’ll usually run the Gateway on port 18789.

curl -fsSL https://openclaw.ai/install.sh | bash
openclaw onboard --install-daemon

If you’re a contributor or developer, use the source:

git clone https://github.com/openclaw/openclaw.git
cd openclaw
pnpm install
pnpm build
pnpm ui:build
openclaw onboard

How do I open the dashboard after onboarding?

The wizard opens your browser with a tokenized dashboard URL as soon as you finish onboarding. It also prints the full link with the token in the summary. Keep that tab open. If it didn’t launch for some reason, just copy and paste the printed URL on the same machine.

How do I authenticate the dashboard (token) on localhost vs remote?

Localhost (same machine):

• Open http://127.0.0.1:18789/
• If it asks for auth, run openclaw dashboard and use the tokenized link (?token=...)

Not on localhost:

• Tailscale Serve (recommended): keep the bind on loopback and run openclaw gateway --tailscale serve
• Tailnet bind: run openclaw gateway --bind tailnet --token "<token>"
• SSH tunnel: ssh -N -L 18789:127.0.0.1:18789 user@host

What runtime do I need?

You need Node >= 22 to get started. I recommend using pnpm for your package management. Bun is not recommended for the Gateway at this time.

Does it run on Raspberry Pi?

Yes, it does. The Gateway is lightweight and runs well on modest hardware. You can get by with 512MB-1GB RAM and 1 core. You also need about 500MB of disk space for personal use. A Raspberry Pi 4 can run it without any trouble.

If you want extra headroom for logs and media, 2GB is recommended. You can host the Gateway on a small Pi or VPS and pair it with nodes on your laptop or phone for your camera and screen.

Any tips for Raspberry Pi installs?

• Use a 64-bit OS and keep Node >= 22.
• I suggest the hackable (git) install so you can see logs and update fast.
• Start without channels or skills, then add them one by one.
• If you hit weird binary issues, it is usually an ARM compatibility problem.

It is stuck on “wake up my friend” / onboarding will not hatch. What now?

That screen depends on the Gateway being reachable and authenticated.

1. Restart the Gateway:

   openclaw gateway restart

2. Check your status and auth:

   openclaw status
   openclaw models status
   openclaw logs --follow

3. If it still hangs, run:

   openclaw doctor

Can I migrate my setup to a new machine (Mac mini) without redoing onboarding?

You can definitely move your setup without starting over. Just copy your state directory and workspace, then run the doctor command to get everything synced up:

1. Install OpenClaw on your new machine.
2. Copy $OPENCLAW_STATE_DIR (default: ~/.openclaw) from your old machine.
3. Copy your workspace (default: ~/.openclaw/workspace).
4. Run openclaw doctor and restart the Gateway service.

Doing this preserves your config, auth profiles, WhatsApp credentials, sessions, and memory so you can pick up right where you left off.

Where do I see what is new in the latest version?

You can find all the latest updates and changes in the GitHub changelog: https://github.com/openclaw/openclaw/blob/main/CHANGELOG.md

What’s the difference between stable and beta?

Stable and beta are npm dist-tags rather than separate code lines:

• latest = stable
• beta = early build for testing

The process is straightforward: builds ship to beta for testing, and once they are solid, that same version is promoted to latest.

How do I install the beta version?

To grab the beta version, use this command:

curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install.sh | bash -s -- --beta

If you prefer a hackable (git) install, use this instead:

curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install.sh | bash -s -- --install-method git

How long does install and onboarding usually take?

You are probably wondering how much time you need to set aside for this. The install itself is very quick, usually taking about 2-5 minutes. Onboarding takes between 5 and 15 minutes, depending on how many channels and models you decide to configure.

Installer stuck? How do I get more feedback?

If the installer feels like it is hanging or you want to see exactly what is happening, you can re-run it with verbose output. This gives you more details on the process:

curl -fsSL https://openclaw.ai/install.sh | bash -s -- --verbose

Windows install says “git not found” or “openclaw not recognized”

Windows can sometimes have issues with environment paths. Here is how to fix the two most common problems:

1) npm error spawn git / git not found If you see this error, you need to install Git for Windows. Make sure git is added to your PATH. You should close and reopen PowerShell, then try running the installer again.

2) openclaw is not recognized after install This happens when your npm global bin folder is not on your PATH. You can find the correct path by running npm config get prefix. You need to ensure that <prefix>\bin is added to your PATH. For the smoothest setup on Windows, I recommend using WSL2 instead of native Windows.

How do I install OpenClaw on Linux?

Setting this up on Linux is straightforward. You should follow the Linux guide and then run the onboarding wizard.

You can find the quick path and service install details here: Linux. For a complete walkthrough, check out the Getting Started guide.

AI Setup Assistant

How do I install OpenClaw on a VPS?

Any Linux VPS works for this. You just install it on the server and use SSH or Tailscale to reach the Gateway. If you need specific steps, you can check out the guides for Hetzner and Fly.io, or the one for exe.dev.

Can I ask OpenClaw to update itself?

The short answer is that it is possible, but I don’t recommend it. The update flow can restart the Gateway, which drops your active session. It might also need a clean git checkout or ask you for confirmation. It is much safer to run updates from a shell as the operator.

openclaw update
openclaw update status
openclaw update --channel stable|beta|dev

What does the onboarding wizard actually do?

When you run openclaw onboard, it guides you through several key steps. It handles your model and auth setup, including Anthropic setup-tokens, OpenAI Codex OAuth, API keys, or local models. It also sets up your workspace location and bootstrap files.

The wizard configures your Gateway settings like bind address, port, auth, and Tailscale. It connects your providers, such as WhatsApp, Telegram, Discord, Signal, and iMessage. Finally, it handles the daemon install (LaunchAgent on macOS or a systemd user unit on Linux/WSL2) along with health checks and skills selection.

Do I need a Claude or OpenAI subscription to run this?

No, you don’t need a subscription. You can run OpenClaw with API keys (like Anthropic or OpenAI) or with local-only models so your data stays on your device. Subscriptions are just optional ways to authenticate those providers if you prefer that method.

Can I use Claude Max subscription without an API key?

Yes, you can. You can authenticate with a setup-token instead of an API key. This is the path to take if you are using a subscription.

How does Anthropic setup-token auth work?

The claude setup-token command generates a token string via the Claude Code CLI. You won’t find this in the web console, but you can run it on any machine. You can choose Anthropic token (paste setup-token) in the wizard or paste it using this command:

openclaw models auth paste-token --provider anthropic

Where do I find an Anthropic setup-token?

It is not in the Anthropic Console. You generate the setup-token by using the Claude Code CLI:

claude setup-token

Just copy the token it prints, then choose Anthropic token (paste setup-token) in the wizard.

Why am I seeing HTTP 429: rate_limit_error from Anthropic?

Your Anthropic quota or rate limit is exhausted for the current window. If you use a Claude subscription, you will need to wait for the window to reset or upgrade your plan. If you use an Anthropic API key, check the Anthropic Console for your usage and billing.

Tip: set a fallback model so OpenClaw can keep replying while a provider is rate-limited.

Is AWS Bedrock supported?

You can use AWS Bedrock. It works via the pi-ai Amazon Bedrock (Converse) provider. You’ll need to use manual config for this. Just supply your AWS credentials and region on the gateway host, then add the Bedrock provider entry to your models config.

How does Codex auth work?

OpenClaw supports OpenAI Code (Codex) through OAuth, so you can use your ChatGPT sign-in. The setup wizard runs the OAuth flow for you. It sets the default model to openai-codex/gpt-5.2 when it’s appropriate.

How do I set up Gemini CLI OAuth?

Gemini CLI uses a plugin auth flow. You can set it up with these commands:

openclaw plugins enable google-gemini-cli-auth
openclaw models auth login --provider google-gemini-cli --set-default

Is a local model OK for casual chats?

Usually, the answer is no. OpenClaw needs a large context and strong safety protocols. Small cards often truncate text and leak data. If you insist on going local, run the largest MiniMax M2.1 build you can find on LM Studio. Keep in mind that smaller or quantized models increase your prompt-injection risk.

Do I have to buy a Mac Mini to install this?

You don’t need to buy a Mac Mini to get this running. OpenClaw works on macOS or Linux, and you can use Windows through WSL2. While some people like having a Mac mini as an always-on host, a small VPS, a home server, a Raspberry Pi-class box, and other low-power devices work just as well.

You only need a Mac if you plan to use tools that only run on macOS. If you want iMessage support, I recommend using BlueBubbles.

Do I need a Mac mini for iMessage support?

You need a macOS device signed into Messages, but it doesn’t have to be a Mac mini. Any Mac you have will work for this. I recommend using BlueBubbles for iMessage integration.

Can I use Bun?

Bun is not recommended for this setup. We often see runtime bugs when using it, especially with the WhatsApp and Telegram gateways. You should use Node to keep your gateways stable.

Telegram: what goes in allowFrom?

The channels.telegram.allowFrom setting requires the human sender’s Telegram user ID. I recommend using the numeric ID, though you can use a @username. This is not the username for your bot.

You can find your ID in a couple of ways:

• Send a DM to your bot, run this command, and check the from.id field:

openclaw logs --follow

• Visit this URL and look for message.from.id:

https://api.telegram.org/bot<bot_token>/getUpdates

AI Setup Assistant

Can multiple people use one WhatsApp number with different OpenClaw instances?

You can do this using multi-agent routing. You just need to bind each sender’s WhatsApp DM to a different agentId. This way, each person gets their own workspace and session store.

Can I run a “fast chat” agent and an “Opus for coding” agent?

Yes, you can. Use multi-agent routing to give each agent its own default model and bind inbound routes to each agent.

What’s the difference between the hackable (git) install and npm install?

• Hackable (git) install: This provides a full, editable source checkout. It is the best choice for contributors who want to run builds locally and patch the code or documentation.
• npm install: This is a global CLI install with no repo to manage. It is the best choice if you just want to run the tool, and updates come directly from npm dist-tags.

Can I switch between npm and git installs later?

You can switch whenever you want. Install the other flavor and run Doctor. This makes the gateway service point at the new entrypoint and switches your active version. This does not delete your data and only changes the OpenClaw code install.

Should I run the Gateway on my laptop or a VPS?

If you need 24/7 reliability, go with a VPS. If you want the lowest friction and don’t mind sleep or restarts, running it locally is the way to go.

Laptop (local Gateway)

• Pros: no server cost and direct access to local files. You also get a live browser window.
• Cons: sleep or network drops cause disconnects. OS updates and reboots will interrupt your work.

VPS / cloud

• Pros: always-on and stable network. You won’t have to worry about laptop sleep issues.
• Cons: these often run headless using screenshots. You only have remote file access.

How important is it to run OpenClaw on a dedicated machine?

It is not required, but I recommend it for reliability and isolation.

• Dedicated host (VPS/Mac mini/Pi): always-on and fewer interruptions.
• Shared laptop/desktop: this is totally fine for testing and active use.

What are the minimum VPS requirements and recommended OS?

OpenClaw is pretty lightweight:

• Absolute minimum: 1 vCPU and 1GB RAM. You also need ~500MB disk space.
• Recommended: 1-2 vCPU and 2GB RAM or more.

For the OS, use Ubuntu LTS or any modern Debian/Ubuntu distribution.

Can I run OpenClaw in a VM and what are the requirements?

Yes, you can. You should treat a VM the same as a VPS. It needs to be always on and reachable. It also needs enough RAM for the Gateway and any channels you enable.

• Absolute minimum: 1 vCPU and 1GB RAM.
• Recommended: 2GB RAM or more.

If you are on Windows, WSL2 is the easiest VM style setup.