Install OpenClaw with npm — Quick Start Guide 2026

Prerequisites

Before installing OpenClaw via npm, make sure your system meets the minimum requirements:

• Node.js 20+ — check with node --version. Download from nodejs.org or use nvm.
• npm 9+ — check with npm --version. Comes bundled with Node.js 20. Upgrade with npm install -g npm@latest if needed.
• A terminal — bash, zsh, PowerShell, or WSL2 on Windows all work.

Note: OpenClaw's primary distribution is Docker-based. The npm package provides the CLI tools for interacting with and managing your OpenClaw instance. For running a persistent agent in production, Docker or managed hosting is strongly recommended over a raw npm install.

Quick Install: npm or npx

There are two ways to run OpenClaw via npm. Choose one:

Option 1: Global install with npm

Install the OpenClaw CLI globally so you can run it from anywhere:

npm install -g openclaw

After installation, the openclaw command is available system-wide. This is the recommended approach if you plan to use OpenClaw CLI regularly.

Option 2: Run without installing with npx

Use npx to run OpenClaw without a global install. npm downloads and executes the package on-demand:

npx openclaw

This is convenient for a one-off test or when you don't want to pollute your global npm packages. The first run will be slower while the package downloads; subsequent runs use npx's local cache.

Verifying the Installation

After installing, confirm that OpenClaw is available and check the installed version:

openclaw --version

You should see a version number like openclaw/1.x.x. If you see "command not found", see the common issues section below.

List all available CLI commands:

openclaw --help

Initial Setup: openclaw init

OpenClaw reads its configuration from ~/.openclaw/openclaw.json. The init command creates this file interactively:

openclaw init

The wizard will ask you to choose:

• Your AI model provider (OpenAI, Anthropic, OpenRouter, DeepSeek, etc.) and API key
• Your chat channel (Telegram, Discord, or browser gateway)
• A gateway authentication token for the web UI
• Basic agent settings (name, language, system prompt)

Alternatively, run the full interactive onboarding flow which covers the same steps plus daemon setup:

openclaw onboard
openclaw onboard --install-daemon   # also register as a background service

Configuring Your First Agent

After running openclaw init, your config lives at ~/.openclaw/openclaw.json. Here is a minimal example showing the key sections — model, channel, and agent:

{
  "models": {
    "default": "openrouter/anthropic/claude-sonnet-4-5",
    "providers": {
      "openrouter": {
        "apiKey": "sk-or-..."
      }
    }
  },
  "channels": {
    "telegram": {
      "enabled": true,
      "token": "123456:ABC-..."
    }
  },
  "plugins": {
    "entries": {
      "telegram": { "enabled": true }
    }
  },
  "agents": {
    "default": {
      "name": "My Assistant",
      "model": "openrouter/anthropic/claude-sonnet-4-5"
    }
  },
  "gateway": {
    "auth": { "token": "your-gateway-token" }
  }
}

A few important notes about the config format:

• Both channels.telegram.enabled AND plugins.entries.telegram.enabled must be true — enabling only the channel config is not enough.
• gateway.auth must be an object — { token: "..." }, not a plain string. Many tutorials get this wrong.
• Model IDs are prefixed with the provider — use openrouter/anthropic/claude-sonnet-4-5, not anthropic/claude-sonnet-4-5.

Add skills from ClawHub to extend your agent. Install them with:

openclaw skills install @clawhub/web-search

Starting OpenClaw

Once your config is ready, start the OpenClaw gateway and agent:

openclaw start

OpenClaw will start the gateway server and connect to your configured chat channels. Open the gateway web UI at http://localhost:18789 to test the browser chat interface.

To run OpenClaw in the background as a daemon (so it survives terminal close):

openclaw daemon start
openclaw daemon status   # check if running
openclaw daemon stop     # stop the daemon

Updating OpenClaw

To update to the latest version of the OpenClaw CLI:

npm update -g openclaw

Or install a specific version:

npm install -g [email protected]

Check the OpenClaw releases page for changelog and version history.

npm vs Docker vs Managed Hosting

OpenClaw can be installed and run in three different ways. Here is when to use each:

Use npm when you're developing locally, testing config changes, or scripting OpenClaw in a CI pipeline. The npm CLI is not well-suited for running a persistent production agent — the process dies when your terminal closes unless you also configure a daemon or process manager.

Use Docker when you want self-hosted production with full control. Docker provides process isolation, easy restarts, and consistent environments. See our OpenClaw Docker guide for details.

Use OpenClaw Launch when you want to skip all of the above. No Node.js, no Docker, no server — just configure your agent in a visual editor and click deploy. Your instance runs 24/7 on managed infrastructure starting at $3/mo first month, then $6/mo.

Common npm Issues

These are the most frequent problems people run into when installing OpenClaw with npm:

Skipping npm Entirely with OpenClaw Launch

If the npm setup feels like too much work, that's because it is. OpenClaw was designed to run as a Docker container, and the JSON config file format has a steep learning curve. The gateway auth format, plugin/channel co-enablement, and file permission quirks trip up nearly every first-time installer.

OpenClaw Launch eliminates all of this. There is no npm, no Node.js, no Docker, no config files, and no server to maintain. You get a visual configurator that generates valid config automatically, and your instance deploys in under 10 seconds. Plans start at $3/mo for the first month then $6/mo — often less than the VPS you'd need to host it yourself.

Want to compare your self-hosting costs? See our OpenClaw hosting guide or read about the full OpenClaw install options.