Installation and Setup

Understanding the architecture is useful only if you can actually get OpenClaw running. Now we will go through the full installation process, the onboarding wizard, and how to connect a Gemini AI provider using an API key. We will cover both macOS and Windows so that readers on either platform can follow along.

OpenClaw requires Node.js version 22 or newer. This is a hard requirement, older versions will not work. Check what you currently have with the following command:

If you need to install or upgrade Node, the installer handles this automatically on macOS. On Windows, we strongly recommend using WSL2, which gives you a clean Linux environment where the installer also handles Node for you.

How to install OpenClaw?

The official installer script is the recommended path on macOS. It detects your system, installs any missing dependencies (including Node and Homebrew if needed), and drops you into the onboarding wizard automatically:

If you prefer to install manually via npm:

Native Windows support for OpenClaw is limited. The strongly recommended path is WSL2 (Windows Subsystem for Linux), which gives you a full Linux environment and makes the experience identical to Linux. You can simply open PowerShell as Administrator and run:

This installs WSL2 with Ubuntu by default. Restart your machine when prompted. OpenClaw’s background service relies on systemd. Enable it by adding this to /etc/wsl.conf inside your Ubuntu terminal:

Then from PowerShell, shut down WSL and restart it:

Open Ubuntu again and verify systemd is running:

Now follow the same macOS/Linux path:

If you specifically want a native Windows install without WSL2, there is a PowerShell installer:

Expect some rough edges on native Windows, particularly around channel integrations.

What to do after the installation?

Whether the installer runs it for you or you run it manually, openclaw onboard is the interactive wizard that configures your entire setup. It walks you through these steps in order:

1. The wizard opens with a security warning, which is not a formality in this case. The warning reminds you to use pairing/allowlists, keep secrets out of the agent’s reachable filesystem, and run openclaw security audit regularly. You confirm with “I understand this is powerful and inherently risky. Continue?” Read it. Then say yes.

2. This is where you can choose your onboarding journey path. Go with QuickStart. It automatically sets sensible defaults for you:

   1. Gateway port: 18789

   2. Gateway bind: Loopback (127.0.0.1)

   3. Gateway auth: Token

   4. Tailscale exposure: Off

3. The wizard presents a list of supported AI providers. You can select Google to use Gemini. Then select Google Gemini API key. Paste your key when prompted. If you don’t have one you can acquire one from Google’s AI Studio.

4. After the key is validated, the wizard shows a model list and defaults to google/gemini-3-pro-preview. Scroll down to find and select google/gemini-2.5-flash. Gemini 2.5 Flash is fast, capable, and well within the free tier limits for everyday use.

5. The wizard asks which messaging app to connect to. For QuickStart, it focuses on the most common options. Select WhatsApp (QR link) if WhatsApp is your primary messaging app. The wizard then explains that WhatsApp works with linked devices and no separate phone number is needed. Credentials are stored at ~/.openclaw/credentials/whatsapp/default/ for future runs. Once connected, the wizard moves on automatically.

6. The wizard scans all bundled skills and shows a breakdown. The wizard then asks which node manager to use for skill installations. Pick whichever you prefer for managing packages. We personally went with bun as it’s the fastest of the lot by some margin.

7. Next, the wizard lists any missing system-level dependencies (Homebrew packages, binaries, etc.) and lets you choose which to install or skip. You can skip everything here, if you later find you need a specific skill that requires a missing dependency, you can always install it then via ClawHub as we discussed earlier.

8. The wizard may prompt for additional API keys that power specific built-in tools, most notably Brave Search, which the web_search tool uses. This is entirely optional. We can skip it for now and configure it later with openclaw configure --section web.

9. Next, we get hooks. These are triggers that fire when specific agent commands run. For example, you can configure a hook that automatically saves the current session to memory whenever you start a new conversation with /new. The wizard shows which hooks are available and lets you enable them via multiselect. Enable what looks useful. You can manage hooks any time with openclaw hooks list, openclaw hooks enable, and openclaw hooks disable.

10. The wizard installs OpenClaw as a background service, so it starts automatically with your machine. This takes a few seconds to a minute. The gateway runtime is Node, and this is not configurable. Even if you selected Bun for skill installs, the gateway itself always runs on Node. This is intentional as Bun has known memory issues on reconnect that affect long-running gateway processes.

11. The final step? It asks you how you want to “hatch” your bot. You can go with “Open the Web UI” and it launches the Control UI dashboard in your browser. This is the best starting point as it gives you a visual interface to chat with your agent, watch tool calls happen in real time, manage settings, and approve shell commands. The TUI is a terminal-based alternative; both connect to the same gateway

Congratulations! Your OpenClaw instance is now running on port 18789.

You can see the whole process we discussed above in the following demo:

The correct command to confirm everything is working after onboarding is openclaw health and for a more thorough diagnostic that checks auth profiles, daemon status, config validity, and security settings, you can run openclaw doctor.

What got created on your machine

After a successful install and onboard, your ~/.openclaw/ directory looks like this:

On macOS, the service file lives outside this directory:

Here are some commands you should be aware of:

What’s next?

Here is a fun experiment to try right now. Open the web UI or WhatsApp and ask your agent to send you a message on WhatsApp. It will perform the task, and the message will arrive from your own number because of the account you just linked. You have essentially created a version of yourself that can send you text messages.

This serves as a great party trick, but it also proves a larger point: OpenClaw is connected and active. It can proactively reach out to you rather than simply waiting to respond.

That said, your agent is currently a capable conversationalist without access to your actual tools. It cannot check your GitHub, browse your Slack, manage files, or execute any meaningful automations yet. It is effectively a brain without hands.

The next step is to provide those hands. We will begin by connecting Slack, which unlocks an entire category of team and workflow integrations and establishes the pattern for every subsequent tool integration.