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.