Install OpenClaw Locally Without Docker

While Docker provides the simplest deployment method, installing OpenClaw locally offers advantages for developers and power users who want maximum control over their installation. Local installation allows direct access to configuration files, easier debugging, faster iteration during development, and integration with your existing Node.js toolchain.

OpenClaw is fundamentally a Node.js application built on modern JavaScript and TypeScript. The Gateway runs as a long-lived process that manages connections to messaging platforms, routes messages to AI agents, and provides the WebChat interface. Running locally means this process executes directly on your system without containerization overhead.

When to Choose Local Installation

Local installation is ideal in several scenarios. Developers contributing to OpenClaw or building custom skills benefit from direct filesystem access and faster code-reload cycles. Users on resource-constrained systems may prefer the lower overhead of native execution compared to Docker's virtualization layer. Power users who want fine-grained control over every aspect of their installation find local setup more flexible.

However, local installation requires more manual configuration and maintenance compared to Docker. You'll manage Node.js versions, handle dependency updates, and configure system services yourself. If you prefer simplicity and isolation, consider our Docker installation guide instead.

Architecture Overview

Understanding OpenClaw's architecture helps with installation and troubleshooting. The core Gateway process manages WebSocket connections, channel adapters, and agent sessions. It reads configuration from ~/.openclaw/openclaw.json and stores workspace files in ~/.openclaw/workspace. The Gateway can run as a foreground process for development or as a system daemon for persistent operation.

The installation process sets up the Gateway binary, creates necessary directories, optionally installs the daemon for automatic startup, and walks you through initial configuration. After installation, you'll have a fully functional OpenClaw instance ready for channel connections and AI assistant interactions.

Before beginning installation, ensure your system meets OpenClaw's requirements. This section covers Node.js installation, system requirements, and platform-specific considerations.

Node.js Requirements

OpenClaw requires Node.js version 22 or later. This requirement exists because OpenClaw uses modern JavaScript features including native fetch, structured clone, and ES modules that are only stable in Node 22+. Earlier Node versions may partially work but are not supported.

Check your installed Node version by running node --version in your terminal. If you need to install or update Node.js, we recommend using a version manager like nvm (Node Version Manager) for easy switching between versions. Version managers also avoid permission issues that sometimes occur with system-wide Node installations.

Package Manager Options

OpenClaw supports installation via npm, pnpm, or bun. While npm comes bundled with Node.js, pnpm offers faster installations and better disk space efficiency through its unique linking approach. Bun provides the fastest package installation and can also serve as an alternative runtime, though OpenClaw is primarily tested with Node.js.

Choose whichever package manager you're most comfortable with. Our examples show commands for all three options. If you're unsure, npm works well for most users. For large workspaces with many skills, pnpm's disk efficiency becomes more valuable.

System Requirements

OpenClaw runs on macOS (Apple Silicon and Intel), Linux (most distributions), and Windows via WSL2. Native Windows support without WSL is experimental and not recommended for production use. The Gateway process typically uses 200-500MB of RAM at idle, increasing with conversation history and active channels. Plan for at least 4GB system RAM, with 8GB providing comfortable headroom.

Disk space requirements are modest: approximately 500MB for OpenClaw itself, plus space for workspace files, conversation history, and any media handled by your assistant. A few gigabytes of free space is sufficient for most personal use cases.

Platform-Specific Preparation

On macOS, ensure Xcode Command Line Tools are installed for native module compilation. On Linux, you may need build-essential and related packages for the same reason. On Windows, install WSL2 with a Linux distribution (Ubuntu recommended), then proceed with Linux instructions inside your WSL environment.

This section walks through the complete installation process from Node.js verification to running OpenClaw for the first time.

Step 1: Verify Node.js Installation

Open your terminal and verify Node.js is properly installed with version 22 or later. The version check command outputs your installed version. If the version is below 22, update Node.js before continuing. Using nvm, you can install and switch to Node 22 with simple commands.

Step 2: Install OpenClaw Globally

Install OpenClaw as a global package using your preferred package manager. Global installation adds the openclaw command to your system PATH, making it accessible from any directory. The installation downloads OpenClaw and all dependencies, which may take a few minutes depending on your internet connection.

After installation, verify the openclaw command is available by checking its version. If the command isn't found, ensure your global npm/pnpm bin directory is in your PATH. Package managers typically provide guidance for setting this up during first use.

Step 3: Run the Onboarding Wizard

OpenClaw includes an interactive onboarding wizard that handles initial configuration. Run the onboard command to start the wizard, which guides you through Gateway setup, workspace initialization, channel configuration, and optional daemon installation.

The wizard creates necessary directories, generates an initial configuration file, and optionally installs a system daemon for automatic startup. Follow the prompts carefully, as the choices you make affect your installation's behavior and security.

Step 4: Install the Gateway Daemon (Recommended)

For persistent operation, install the Gateway as a system daemon. The onboarding wizard offers this option, or you can install it separately with the --install-daemon flag. On macOS, this creates a launchd service. On Linux, it creates a systemd user service. The daemon ensures OpenClaw starts automatically after system boot and restarts after crashes.

With the daemon installed, OpenClaw runs in the background continuously. Use the openclaw gateway status command to check its state, and openclaw gateway logs to view output. The daemon approach is strongly recommended for daily use, as it maintains persistent connections to messaging platforms.

Step 5: Complete Channel Setup

With the Gateway running, connect your messaging channels through the web interface at http://localhost:18789 or using CLI commands. Run openclaw channels login to authenticate with platforms like WhatsApp, Telegram, or Discord. Each platform has its own authentication flow documented in our integration guides.

Developers contributing to OpenClaw or needing the latest unreleased features can build from source. This process clones the repository, installs dependencies, builds the project, and runs from the local build.

Clone the Repository

Start by cloning the official OpenClaw repository from GitHub. This downloads the complete source code including all packages in the monorepo structure. Choose a location where you want to keep the source code, as you'll return here for updates and development work.

Install Dependencies

OpenClaw uses pnpm workspaces for monorepo management. Install pnpm if you haven't already, then run the install command from the repository root. This installs all dependencies for all packages in the workspace, which may take several minutes.

Build the Project

After installing dependencies, build the project with the build commands. This compiles TypeScript to JavaScript, builds the WebChat UI, and prepares all packages for execution. The build process creates the dist directories containing runnable code.

Run from Source

With the build complete, run OpenClaw using pnpm commands rather than the global openclaw binary. The pnpm openclaw command executes the locally built version. You can run the onboarding wizard, start the gateway, and use all features just like the installed version.

Development Mode

For active development, use the watch commands that automatically rebuild on file changes. The gateway:watch command starts the Gateway with hot reloading, making iteration faster. Combine this with the dev channel for access to the latest features being developed.

OpenClaw's behavior is controlled through the configuration file at ~/.openclaw/openclaw.json. This section covers essential configuration options for local installations.

Configuration File Location

The primary configuration file lives at ~/.openclaw/openclaw.json. OpenClaw creates a default configuration during onboarding, which you can customize as needed. The file uses JSON format with comments supported via JSONC parsing. Keep a backup of your working configuration before making changes.

Agent Configuration

The agent section configures AI model settings including the model identifier, maximum token limits, and provider-specific options. Model identifiers follow the provider/model format, such as anthropic/claude-opus-4-5 or openai/gpt-4-turbo. Configure your API key through environment variables rather than directly in the config file for security.

Gateway Configuration

Gateway settings control the WebSocket server, including ports, bind addresses, and Tailscale integration. The default port 18789 works for most setups, but you can change it if there's a conflict. The host setting determines which network interfaces accept connections, with 127.0.0.1 for local-only access or 0.0.0.0 for all interfaces.

Channel Configuration

Each messaging channel has its own configuration section controlling allowed users, group behavior, and channel-specific settings. The channels section uses platform names as keys (whatsapp, telegram, discord, etc.) with nested configuration for each. The allowFrom array restricts which users can interact with your assistant.

Workspace Configuration

The workspace section configures where OpenClaw stores agent files, skills, and other workspace data. The default location is ~/.openclaw/workspace, but you can specify a different path. Skills are loaded from the workspace/skills directory, and agent customization files (AGENTS.md, SOUL.md, TOOLS.md) live in the workspace root.

The Gateway daemon keeps OpenClaw running persistently in the background. This section covers daemon installation, management, and troubleshooting.

Installing the Daemon

Install the Gateway daemon with the openclaw onboard --install-daemon command. This creates appropriate service files for your operating system: launchd on macOS or systemd on Linux. The daemon starts automatically after installation and on subsequent system boots.

Daemon Commands

Several commands help manage the daemon. Use openclaw gateway status to check whether the daemon is running. Use openclaw gateway start and openclaw gateway stop to control execution. Use openclaw gateway restart after configuration changes. Use openclaw gateway logs to view output and troubleshoot issues.

macOS launchd Details

On macOS, the daemon installs as a user-level launchd agent at ~/Library/LaunchAgents/ai.openclaw.gateway.plist. This agent starts when you log in and runs with your user permissions. Use launchctl commands for advanced management beyond what openclaw gateway provides.

Linux systemd Details

On Linux, the daemon installs as a user-level systemd service. Enable lingering with loginctl enable-linger to ensure the service runs even when you're not logged in. Use systemctl --user commands for advanced management. The service file lives in ~/.config/systemd/user/.

Running Without Daemon

For development or debugging, run the Gateway in the foreground without the daemon. The openclaw gateway command starts the Gateway directly in your terminal, with logs streaming to stdout. This approach is useful for seeing real-time output and debugging issues. Stop with Ctrl+C when done.

Regular updates provide new features, security patches, and bug fixes. This section covers update procedures for npm-installed and source-built installations.

Updating npm Installation

Update your global OpenClaw installation using your package manager's update command. This downloads and installs the latest version. After updating, restart the Gateway daemon to run the new version. Check the release notes before updating to understand what's changed.

Update Channels

OpenClaw provides three release channels: stable (recommended for most users), beta (preview features before stable release), and dev (latest development builds). Switch channels using the openclaw update --channel command. Stable receives the most testing and is recommended for production use.

Updating Source Installation

For source installations, update by pulling the latest changes from GitHub and rebuilding. This process fetches new commits, updates dependencies, and creates fresh builds. The git pull command with rebase keeps your history clean if you've made local modifications.

Version Verification

After updating, verify the new version is active by checking openclaw --version and the Gateway status. If the version doesn't match expectations, ensure the daemon was properly restarted. Sometimes multiple installations can cause version confusion; verify which binary is in your PATH.

This section addresses common issues with local OpenClaw installations and provides solutions.

Command Not Found

If the openclaw command isn't found after installation, your package manager's global bin directory isn't in your PATH. Find the bin directory with npm list -g --depth=0 or equivalent commands, then add it to your PATH in your shell configuration file (.bashrc, .zshrc, etc.).

Node Version Issues

OpenClaw requires Node 22+. If you see errors about unsupported features, verify your Node version. When using nvm, ensure the correct version is active in your current terminal session. The nvm use command switches versions temporarily; nvm alias default sets the persistent default.

Permission Errors

Global package installations sometimes fail with permission errors. Never use sudo with npm install -g as this creates more problems. Instead, configure npm to use a user-owned directory for global packages, or use a version manager like nvm which handles permissions properly.

Daemon Won't Start

If the daemon fails to start, check logs with openclaw gateway logs or directly in system log files. Common causes include port conflicts (another service using 18789), configuration file syntax errors, or missing API keys. The openclaw doctor command runs diagnostics to identify issues.

Channel Connection Problems

Messaging channels require network access and proper authentication. Verify internet connectivity, check that no firewall blocks outbound connections, and ensure channel credentials are properly configured. Each channel type has specific troubleshooting steps covered in their respective integration guides.

High Resource Usage

If OpenClaw uses excessive CPU or memory, check for conversation history buildup, too many concurrent channels, or memory leaks in custom skills. The troubleshooting guides cover performance optimization in detail. As a quick fix, restarting the Gateway clears accumulated state.