OpenClaw Installation Guide for macOS, Linux, and Windows

OpenClaw is a local tool that lets your AI agent connect to apps like Telegram or WhatsApp and take action, such as sending messages or handling tasks. Getting it set up is straightforward once you understand the process. This guide covers installation across macOS, Linux, and Windows.

Table of contents

• Quick overview of OpenClaw setup options
• How to install OpenClaw on macOS and Linux
  • Method 1: Use the one-line installer script
  • Method 2: Install with Homebrew
  • Method 3: Install with npm
• How to install OpenClaw on Windows
  • Method 1: Use the PowerShell installer (native Windows)
  • Method 2: Install with WSL2
  • Method 3: Install with npm on Windows
• How to run OpenClaw online with Kimi Claw
• Troubleshooting common OpenClaw installation errors
• Conclusion

Quick overview of OpenClaw setup options

Choose the setup that fits your needs. Running OpenClaw locally keeps everything on your own machine and requires installing dependencies such as npm or using an automated script. If you prefer to skip setup, fully hosted platforms like Kimi Claw handle the environment for you, letting you get started directly.

How to install OpenClaw on macOS and Linux

macOS and Linux share the same installer and commands. These instructions apply to both systems unless noted.

Below is a quick setup guide. For a full step-by-step walkthrough with screenshots, see How to install OpenClaw on macOS.

Method 1: Use the one-line installer script

Step 1: Run the installation script in Terminal

Run the official installer script to set up OpenClaw. The script checks whether Node.js 22 or newer is installed. If it is missing or outdated, Node.js 24 will be installed automatically. It then installs the OpenClaw CLI and launches the onboarding wizard.

Step 2: Complete the onboarding wizard

Follow the onboarding wizard to set up your agent environment, including selecting a model provider (e.g., Kimi API), entering your API key, choosing a channel, and configuring basic settings.

Step 3: Check your installation

Run the following command to confirm your OpenClaw version.

Step 4: Verify the gateway and complete setup

Run the following command to check that the OpenClaw gateway is active.

The installer also registers a LaunchAgent on macOS or a systemd service on Linux, so OpenClaw continues running in the background. Once everything is set up, your agent is ready to use. You can start chatting, connect tools, or configure workflows based on your needs.

Method 2: Install with Homebrew

Step 1: Install or upgrade Node.js

Use Homebrew to install Node.js by running the following command in Terminal. If Node.js is already installed, run the upgrade command instead to ensure you are using the latest version.

Step 2: Install the OpenClaw CLI

Run the following command to install the OpenClaw CLI globally.

Step 3: Run onboarding and set up the daemon

Run the following command to launch the onboarding wizard and register the background daemon. Follow the wizard to configure your agent environment, including selecting a model provider (e.g., Kimi API), entering your API key, and connecting a messaging channel. Once setup is complete, your agent is ready to use. You can start chatting, connect tools, or configure workflows based on your needs.

Method 3: Install with npm

Step 1: Verify the runtime version

Run the following command to ensure Node.js 22.14 or later is installed on your system. If your version is up to date, you can proceed with the installation.

Step 2: Install the OpenClaw CLI

Run the following command to install the OpenClaw CLI globally.

Step 3: Run onboarding and enable persistence

Run the following command to start the onboarding wizard and register the background daemon. Follow the wizard to configure your agent environment, including selecting a model provider (e.g., Kimi API), entering your API key, and choosing a messaging channel. Once setup is complete, your agent is ready. You can start interacting with it, connect tools, or build workflows based on your needs.

Platform notes: OpenClaw supports both Intel and Apple Silicon Macs. If the installation is blocked by Gatekeeper, you can allow it in System Settings under Privacy & Security.

How to install OpenClaw on Windows

Windows offers three main ways to install OpenClaw: the PowerShell installer for a quick native setup, WSL2 for a full Linux environment, and npm for manual installation.

Below is a quick setup guide. For a full step-by-step walkthrough with screenshots, see How to install OpenClaw on Windows.

Method 1: Use the PowerShell installer (native Windows)

Step 1: Run the installer script in PowerShell

Open PowerShell as administrator and run the official one-line script to install OpenClaw.

Step 2: Complete the onboarding wizard

Follow the onboarding steps to configure your agent environment, including selecting a model provider (e.g., Kimi API), entering your API key, and choosing a messaging channel.

Step 3: Verify the installation

Run the following command to confirm that OpenClaw is installed correctly and the gateway is active.

Step 4: Start using your agent

Once setup is complete, your agent is ready. You can start interacting with it, connect tools, or configure workflows based on your needs.

Method 2: Install with WSL2

Step 1: Set up the Linux environment

Open PowerShell as administrator and run the following command to enable and initialize WSL2.

Step 2: Run the installer in Linux

Open your Linux terminal and run the standard installation script to install OpenClaw.

Step 3: Complete the onboarding wizard

Follow the onboarding steps to configure your agent environment, including selecting a model provider (e.g., Kimi API), entering your API key, and choosing a messaging channel.

Once setup is complete, your agent is ready. You can start interacting with it, connect tools, or configure workflows based on your needs.

Method 3: Install with npm on Windows

Step 1: Check your Node.js version

Run the following command to verify that Node.js is installed and up to date.

Step 2: Install the OpenClaw CLI

Run the following command to install the OpenClaw CLI globally.

Step 3: Run onboarding and enable persistence

Run the following command to start the onboarding wizard and register the background daemon.

Follow the onboarding steps to configure your agent environment, including selecting a model provider (e.g., Kimi API), entering your API key, and choosing a messaging channel.

Once setup is complete, your agent is ready. You can start interacting with it, connect tools, or configure workflows based on your needs.

How to run OpenClaw online with Kimi Claw

The methods above require a terminal, a supported Node.js version, and a machine that stays on. Kimi Claw provides a fully hosted option, so you can run OpenClaw without installing or maintaining a local environment.

Step 1: Open Kimi Claw and create an instance

Go to the Kimi Claw page and click Create to start.

Step 2: Confirm the deployment

Confirm the deployment in the pop-up window. Kimi Claw will automatically set up your OpenClaw environment, including the gateway and workspace, without requiring any local configuration.

Step 3: Start using your workspace

Once deployment is complete, your workspace opens in the dashboard. You can start interacting with your agent, set up skills, configure scheduled tasks, and manage files directly in your browser.

Key features of Kimi Claw

• Cloud hosting: Kimi Claw runs your gateway in the cloud, so your agent remains available even when your local machine is offline.
• Automatic maintenance: Updates and patches are handled in the background, with no manual setup or restarts required.
• Built-in capabilities: Includes task scheduling, persistent storage, and dynamic skill loading based on your prompts, with seamless access across devices.

Troubleshooting common OpenClaw installation errors

Most OpenClaw installation issues fall into a few common categories, such as PATH configuration, missing dependencies, or port conflicts. The sections below help you quickly identify and fix the most frequent problems across macOS, Windows, and Linux.

"openclaw: command not found" after installation

OpenClaw is not in your system PATH.

• Fix: Add the npm global bin directory to your PATH.

Then reload your shell (e.g., source ~/.zshrc) or restart your terminal. On Windows, add the path to your environment variables and restart PowerShell.

Sharp build errors on macOS

This usually happens when a globally installed libvips conflicts with the Sharp library.

• Fix: Run the install command with this environment variable.

If you see node-gyp errors, install Xcode Command Line Tools:

OpenClaw does not start after reboot

The background daemon was not installed during onboarding.

• Fix: Run onboarding again with the daemon flag.

Then verify the service:

Gateway not responding or showing "0 tokens used"

The gateway process may have stopped, or API authentication may have failed.

• Fix: Restart the gateway.

Run a health check:

For debugging logs:

Also, verify your API key is valid.

Port 18789 already in use

Another process is using the OpenClaw gateway port.

• Fix: Find and stop the conflicting process

Then restart the gateway:

EACCES permission errors

This usually means the npm global directory does not have the correct permissions.

• Fix: Update directory ownership.

On Windows, run PowerShell as Administrator or set a custom npm prefix:

For Docker setups, fix volume permissions:

"spawn git ENOENT" error

Git is not installed or not available in the PATH.

• Fix: Install Git from git-scm.com, restart your terminal, and retry the installation.

WSL2 systemd not working

Systemd is not enabled in your WSL configuration.

• Fix: Edit /etc/wsl.conf and add.

Then restart WSL:

Reopen your Linux terminal and verify:

Out-of-memory during npm install on VPS

Low-memory VPS instances may fail during package installation.

• Fix: Create a swap file.

Then rerun the installation.

"Access not configured" when connecting to messaging platforms

Your account is not authorized by OpenClaw.

• Fix: Approve your account using the pairing code.

Also, verify your bot credentials (token, webhook, permissions) are configured correctly.

Conclusion

Installing OpenClaw is straightforward across macOS, Linux, and Windows. You can use a one-line script, PowerShell, WSL2, or npm, depending on your setup. The onboarding wizard guides you through model selection, API configuration, and messaging channels. If you prefer not to manage a local environment, Kimi Claw offers a fully hosted option that lets you run OpenClaw directly in the cloud.