Simple Steps to Install OpenClaw on Windows and Mac

You can install OpenClaw on your computer with simple steps, whether you use Windows or Mac. If you’re utilizing Hong Kong hosting, it’s especially important to follow the recommended process to ensure optimal performance. You will avoid common issues like Node.js version mismatches, permission errors, and API key mistakes by following the recommended process.

Here are some pitfalls and their solutions:

You will quickly start using OpenClaw, complete onboarding, and set up Telegram integration. The process suits beginners and helps you avoid mistakes that often cause frustration.

Key Takeaways

• Choose the installer script for the fastest and easiest OpenClaw setup on both Windows and Mac.

• Ensure your system meets the minimum requirements, especially Node.js version 22 or higher, for a smooth installation.

• Use Docker for a clean and isolated environment, especially if you want to avoid dependency issues.

• Follow the onboarding wizard after installation to set up your AI assistant easily and connect it to messaging platforms like Telegram.

• Join the OpenClaw community for support and updates, ensuring you stay informed about best practices and troubleshooting tips.

Prerequisites for OpenClaw

Before you install OpenClaw, you need to make sure your computer meets the basic requirements. This helps you avoid problems during setup and ensures a smooth experience.

System Requirements

Check that your system matches the minimum and recommended specs. Meeting the recommended specs gives you better performance and fewer issues.

💡 Tip: Upgrading your operating system and Node.js to the latest versions helps prevent compatibility issues.

Required Tools

You need a few tools to get started. The tools depend on the installation method you choose.

Make sure you have a stable internet connection. This is important for downloading packages and updates.

Choosing an Install Method

You can install OpenClaw in three main ways. Each method has its own strengths.

• Installer Script: This method gives you direct access to your files and desktop apps. It works well if you want full control, but you may need to handle some manual setup.

• NPM or pnpm: This method uses a package manager to handle dependencies. It is easy to update and manage, but you might still need to fix some manual issues.

• Docker: This method packages everything you need into one container. It is great if you want a quick setup and do not want to worry about dependencies. You need Docker installed first, which may take extra steps if you are new to it.

If you want the fastest and most reliable setup, try the installer script first. Docker is a good choice if you want everything bundled together. NPM or pnpm works best if you already use Node.js often.

Install OpenClaw on Windows

You can install OpenClaw on Windows in several ways. The installer script offers the fastest and most reliable setup. You gain full access to your hardware and desktop apps with this method. Advanced users may prefer the NPM or Docker methods for more control or flexibility.

Using the Installer Script

The installer script makes the process simple. You do not need to worry about manual configuration or missing dependencies. Follow these steps to install OpenClaw:

1. Open your terminal or Windows Subsystem for Linux (WSL2).

2. Run the following command to start the installation:

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

3. If you want to review the script before running it, download it first:

   curl -O https://openclaw.ai/install.sh
   

4. After reviewing, execute the script:

   bash install.sh
   

🛠️ Tip: The installer script checks your system for Node.js and other requirements. You do not need to install them separately.

You finish the installation in just a few minutes. The script handles everything for you. You get direct access to your files and desktop apps, which helps OpenClaw run smoothly.

NPM Method

If you already use Node.js and npm, you may want to install OpenClaw with the package manager. This method gives you more control over updates and dependencies. You need Node.js version 22 or higher.

• Open your terminal or WSL2.

• Run the following command:

  npm install -g openclaw
  

• After installation, start OpenClaw with:

  openclaw start
  

💡 Note: You may need to adjust npm permissions if you see errors. Use your home directory for global installs to avoid issues.

The NPM method works well for users who want to manage OpenClaw alongside other Node.js projects. You can update or remove OpenClaw easily with npm commands.

Docker Method

Docker provides a bundled environment for OpenClaw. You do not need to worry about system dependencies. Before you start, make sure Docker Desktop is installed on your Windows system. You should also understand the basics of Docker Compose.

• Install Docker Desktop from the official website.

• Open your terminal.

• Pull the OpenClaw Docker image:

  docker pull openclaw/openclaw:latest
  

• Create a docker-compose.yml file with the required configuration.

• Start OpenClaw using Docker Compose:

  docker-compose up -d
  

🧑‍💻 Tip: Docker isolates OpenClaw from your main system. This method works well if you want a clean setup or plan to run multiple services.

You can install OpenClaw with Docker if you want everything bundled together. This method reduces conflicts with other software and makes upgrades simple.

Choose the method that fits your needs. The installer script works best for most users. NPM and Docker methods offer flexibility for advanced setups.

Install OpenClaw on Mac

You can install OpenClaw on your Mac in just a few minutes. The process is simple and flexible. You can choose the fastest one-line installer script, or try the NPM and Docker methods if you want more control.

One-Line Installer Script

The one-line installer script gives you the quickest way to install OpenClaw on Mac. You only need to run a single command in your terminal. This script checks your system, finds missing tools, and installs everything for you. You do not need to worry about manual steps or missing dependencies.

• The script saves you time by handling all setup tasks.

• It automatically detects and installs Node.js and other required tools.

• You do not need to configure anything by hand.

• The process works for both beginners and advanced users.

To use the installer script, follow these steps:

1. Open the Terminal app on your Mac.

2. Copy and paste this command, then press Enter:

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

3. Wait for the script to finish. You will see messages as it checks and installs the needed tools.

4. When the script completes, you can start OpenClaw right away.

💡 Tip: The one-line installer script is the best choice if you want to install OpenClaw quickly and avoid common setup problems.

NPM Method

If you use Node.js for other projects, you may want to install OpenClaw with NPM. This method gives you more control over updates and lets you debug easily. You need Node.js version 22 or higher on your Mac.

To install OpenClaw with NPM:

1. Open your Terminal.

2. Run this command:

   npm install -g openclaw
   

3. Start OpenClaw with:

   openclaw start
   

You can see how the NPM method compares to Docker in the table below:

NPM works well if you want a lightweight setup and plan to use OpenClaw for development. You can update or remove OpenClaw with simple NPM commands.

Docker Method

Docker gives you a way to install OpenClaw in a container. This method keeps OpenClaw separate from your main system. You do not need to worry about version conflicts or missing dependencies. You need Docker Desktop installed on your Mac before you start.

To install OpenClaw with Docker:

1. Download and install Docker Desktop from the official website.

2. Open your Terminal.

3. Pull the latest OpenClaw image:

   docker pull openclaw/openclaw:latest
   

4. Create a docker-compose.yml file with the right settings.

5. Start OpenClaw with:

   docker-compose up -d
   

🛠️ Note: Docker is a good choice if you want to run OpenClaw on a server, NAS, or Mac Mini. It uses more resources but gives you a stable and isolated environment.

You can choose the method that fits your needs. The one-line installer script is the fastest way to install OpenClaw. NPM and Docker give you more options if you want to customize your setup.

OpenClaw Setup and Onboarding

Running the Onboarding Wizard

After you install OpenClaw, you need to complete the onboarding wizard. This wizard helps you set up your AI assistant step by step. You will answer a few questions to get started.

Run the onboarding wizard with this command:

openclaw onboard

The wizard will guide you through these steps:

You will choose your AI provider, such as Anthropic Claude, OpenAI GPT, Google Gemini, or a local Ollama model. Next, you enter the API key for your chosen provider. Then, you select the first messaging platform to connect, like Telegram, WhatsApp, or Slack. The wizard makes each step clear and easy to follow.

Telegram Bot Integration

You can connect OpenClaw to Telegram during onboarding. The wizard will help you link your Telegram account by asking for the needed credentials. This integration lets you chat with your AI assistant using a familiar app.

• You interact with OpenClaw through Telegram, making it feel like texting a friend.

• The setup process is simple and quick, so you can start using your assistant right away.

• You can also connect other channels, but Telegram is a popular choice for many users.

This multi-channel approach gives you flexibility and makes communication natural.

Verifying Installation

You should check that OpenClaw is running correctly after setup. Use these commands to verify your installation:

• Run the diagnostic tool:

  openclaw doctor
  

  This tool checks if Node.js is up to date, your configuration file is valid, API keys work, and the messaging bridge is active. If there is a problem, the tool will show an error message and suggest a fix.

• Check the version:

  openclaw --version
  

  If you see a version number, your installation is successful.

If you run into issues, review the error messages. Common problems include invalid API keys or missing dependencies. Fix these to ensure OpenClaw works smoothly.

Troubleshooting Install Issues

Even with a smooth installer, you might run into problems when setting up OpenClaw. You can solve most issues quickly if you know what to look for. This section covers the most frequent errors and how to fix them.

Common Errors

You may see these common errors during installation:

• On Apple Silicon Macs, you need the native ARM version of Node.js. Check your architecture with:

  node -p "process.arch"
  

• A corrupted npm cache can block installation. Clean it with:

  npm cache clean --force
  

• After a major macOS upgrade, native modules may break. Run:

  xcode-select --install
  

• On Windows, native installation is not supported. Use WSL2 for best results.

• Errors like “spawn npm ENOENT” or execution policy blocks often happen on Windows. Switching to WSL2 usually solves these.

🛠️ Tip: If you see a “Gateway Connect Failed: Error: Pairing Required” message on Windows, edit the pending.json file in your .openclaw/devices folder. Community guides can help with this step.

Dependency Problems

Node.js and package issues cause many installation failures. You can fix most of them by following these steps:

1. Check your Node.js version:

   node -v
   

   You need version 22 or higher.

2. If your version is wrong, install nvm (Node Version Manager).

3. Use nvm to install Node.js 22 and set it as default.

4. Run OpenClaw diagnostic tools:

   openclaw status
   openclaw health
   openclaw doctor
   

5. Review logs for errors or stack traces.

6. If you still have problems, collect your logs and system info before asking for help on GitHub.

Docker can also help you avoid local dependency conflicts. Pull the latest image and run OpenClaw inside a container:

docker pull openclaw/openclaw
docker run openclaw/openclaw

Network and Permissions

Network and permission errors can stop your installation. Here are some quick fixes:

• If you see “permission denied,” set npm to use your user directory instead of system folders.

• Always use Node.js version 22 or later to avoid compatibility issues.

• If the onboarding wizard cannot find your config file, run onboarding again or create the config directory by hand.

💡 Note: A stable internet connection helps prevent download failures and missing packages.

By following these steps, you can solve most installation problems and get OpenClaw running smoothly.

You can install OpenClaw easily on Windows or Mac. The installer script and clear documentation make the process simple for everyone. The table below shows how flexible installation benefits you:

To keep OpenClaw secure and always-on, follow these best practices:

1. Stick to default installations until you understand advanced options.

2. Join the community for support and early warnings.

3. Only install plugins from the official registry.

4. Upgrade promptly for security patches.

You can find answers to frequent questions in the FAQ. If you have trouble, leave a comment for help.

FAQ

How do I update OpenClaw to the latest version?

You can update OpenClaw by running:

openclaw upgrade

This command downloads the newest features and security patches. You should check for updates regularly to keep your system safe.

What should I do if OpenClaw fails to start?

Try running openclaw doctor to diagnose the issue.
You can review the error messages and follow the suggested fixes. Restart your computer if the problem continues.

Can I use OpenClaw without Docker?

Yes, you can install OpenClaw using the installer script or NPM. Docker is optional. Choose the method that fits your workflow and skill level.

Where can I find community support for OpenClaw?

You can join the OpenClaw Telegram group or visit the official GitHub repository. The community helps you solve problems and answers your questions.