Skip to content

Installation: Get up and running in 5 minutes OpenClaw ​

This lesson is the hands-on starting point of the whole tutorial series and the main path for OpenClaw installation: one official install command + guided onboarding, from typing the command to receiving your first AI reply in the browser — about 5 minutes by the official estimate, provided you already have a Claude Code / Codex CLI login or an API Key from some model provider; the time to apply for a Key from scratch is counted separately (Step 3 will point you to where to get one).

Alternative methods such as the desktop app, Docker, and direct npm installation are covered separately in the next lesson; if the installation fails or things won't run, go straight to What to do if installation fails to troubleshoot. This tutorial is based on v2026.10.9 (already a version after "OpenClaw 2.0").

What you'll be able to do after this lesson ​

  • Complete OpenClaw installation with one command on macOS, Linux, and Windows
  • Use npx openclaw@latest to try a full round of the experience first, then decide whether to install it formally
  • Let onboarding automatically reuse your existing Claude Code / Codex login or API Key, skipping manual configuration
  • Install the Gateway as a background service and use openclaw gateway status to confirm it is listening on port 18789
  • Send your first message in the Control UI and receive an AI reply — completing the full run from installation to conversation

Where you are right now ​

  • Tutorials that come up when you search "OpenClaw installation" have unclear versions, and many still use old commands from the Clawdbot / Moltbot era — copying them leads to errors
  • You want to try this tool before deciding whether to install it, but many tools require registering a pile of things even just to try them
  • You finally got it running, but the process dies as soon as you close the terminal; the next day you want to keep using it and have to figure out all over again "whether it's even running"

When to use this approach ​

When you need to:

  • Get OpenClaw properly running on your own computer — all later lessons (connecting models, connecting channels, automation) build on this step
  • Take the fastest installation path: no environment restrictions, Node is installed automatically if missing, and onboarding starts automatically after installation

And you don't want to:

  • Fall into pitfalls following outdated tutorials with unclear versions
  • Fiddle with alternative paths like the desktop app, Docker, or building from source first
  • Be left confused after installation: whether the Gateway is even running, and where to send messages

🎒 Preparation before you start ​

  • Read OpenClaw what it is so you know what the terms Gateway, onboarding, and Control UI refer to
  • (can be added later)OpenClaw 2.0 what's new is not a prerequisite for this lesson—if you want to get things running quickly you can skip it for now and catch up on the version background later
  • A macOS / Linux / Windows computer and a terminal with internet access
  • A "model pass": an existing Claude Code or Codex CLI login, or an API Key from any model provider — not having one won't block you; Step 3 will point you to where to get one

System Requirements ​

ItemRequirementNotes
Operating systemmacOS / Linux / WindowsWindows has three routes: the Windows Hub app, the PowerShell installer, and WSL2 Gateway (this page uses the PowerShell installer)
Node.js24.16.0+ (24.x) or 26.1.0+The official recommendation is 24.22.1+ / 26.12.1+ (security fixes); Node 26 is the recommended version
No Node?You don't have to install it in advanceWhen Node is missing, the official installer fills it in automatically: it installs Node 26 on macOS and Node 24 LTS on Linux

For Node version details and compatibility troubleshooting, see the official Node.js compatibility documentation.

Core idea ​

OpenClaw installation — what does it actually install? Three things:

  1. CLI——openclaw command, your entry point to OpenClaw
  2. A configuration——"which model to use, what credentials to use" as written by the onboarding wizard
  3. A resident Gateway process——the local control plane; sessions, tools, and channel connections are all managed by it; the Control UI, CLI, and TUI are all its clients

Why can you get it running in 5 minutes? Because onboarding automatically detects your existing Claude Code / Codex CLI logins or API Keys, validates them with one real model call (completion), and stores them directly in the configuration—when you already have usable credentials, the wizard basically requires nothing from you.

There is more than one way to get started; this page walks you through the first two, and the third is in the next lesson:

MethodWho it's forIn one sentence
Official installer (recommended)Want a proper install for long-term useDetects your system, installs Node automatically if missing, and goes straight into onboarding after installation
npx openclaw@latestTry it out first, then decideOne command brings up the full experience, with the Gateway running in your current terminal
Direct install via npm / pnpm / Bun, desktop app, DockerManage Node yourself, avoid the terminal, or deploy to a serverSee Alternative installation methods

One more thing to remember up front: right after installation, the Gateway runs in the terminal foreground—Ctrl+C stops it and the configuration is preserved; if you want it to run persistently at startup without worrying about closing the terminal, install it as a background service in step 4.

Follow along ​

Step 1: Verify your Node version — the environment prerequisite for OpenClaw installation ​

Why: OpenClaw is a Node.js application, and an outdated Node will cause cascading errors at every later step. Spend 10 seconds checking now to save an hour of debugging.

bash
node --version

You should see: the terminal prints a version number. v24.16.0 or later, i.e. 24.x or higher, or v26.1.0 or later, i.e. 26.x or higher, qualifies (the official docs strongly recommend the security-fix releases 24.22.1+ / 26.12.1+).

Compare against three scenarios:

  • A qualifying v24 / v26 is printed → go straight to step 2

  • v20 / v22 or older is printed → not supported; upgrade first (see pitfall reminder 1 below)

  • Tip command not found — no need to worry if it isn't installed: the official installer automatically provides Node when it's missing (Node 26 on macOS, Node 24 LTS on Linux), so you can go straight to Step 2

  • node --version outputs a 24.x version ≥ 24.16.0 or a 26.x version ≥ 26.1.0 (or confirm that you'll let the installer handle it automatically)

Step 2: Complete the OpenClaw installation with a single command ​

Why: the official installer is the fastest main path—it detects your operating system, installs Node if needed, installs OpenClaw, and then automatically starts the onboarding wizard.

Method A (recommended): official installer ​

macOS / Linux users (this is also the command to use inside WSL2; macOS and Linux installs use the same command):

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

Windows users (PowerShell):

powershell
iwr -useb https://openclaw.ai/install.ps1 | iex

You should see: the installer gets to work—detects your system → (if needed) installs Node → installs OpenClaw → automatically enters the onboarding wizard, which opens with a line pointing to the official security guide.

💡 Install only, without the wizard?

Automated bulk installs can skip onboarding:

bash
curl -fsSL https://openclaw.ai/install.sh | bash -s -- --no-onboard
powershell
& ([scriptblock]::Create((iwr -useb https://openclaw.ai/install.ps1))) -NoOnboard

For the full list of installer parameters, see the official Installer internals.

⚠️ Networks in mainland China

The official documentation does not provide mainland-China mirrors or download acceleration, and this article will not guess at mirror addresses. If downloading the install script or dependencies times out, check your network environment first and retry; if it keeps failing, go to What to do if installation fails to troubleshoot.

Method B: try npx openclaw@latest first ​

Don't want to install first? One command brings up the complete OpenClaw:

bash
npx openclaw@latest

The experience is the same as Method A: onboarding proceeds as usual, the web dashboard opens as usual, and the Gateway runs in your current terminal—after stopping it with Ctrl+C, the configuration is likewise preserved. If you like it after trying, do a proper install via Method A.

  • The onboarding wizard has appeared in your terminal (counts for both Method A / Method B)

Step 3: Complete onboarding—reuse the model credentials you already have ​

Why: OpenClaw doesn't come with a model. Onboarding configures "which model to use, what credentials to use" all at once—only after this step is done will you get AI responses.

Once the wizard starts, pick one:

  • Quick start (recommended): when you already have Claude Code / Codex CLI logins or an API Key from some provider—OpenClaw detects them automatically, validates them with one real completion, saves the configuration, and opens the web dashboard. The official docs state clearly: when you already have working AI access, apart from the security notice at the start, the wizard won't ask anything else.
  • Custom setup: walks through every wizard option; when none of the auto-detection paths work, the wizard opens manual provider setup.

You should see: after choosing Quick start, everything is green lights the whole way—credentials detected → validated → configuration saved → the dashboard opens in your browser, while the Gateway starts running in the foreground of your current terminal.

💡 Want to redo the configuration?

openclaw configure to change settings at any time; openclaw onboard --classic opens the classic step-by-step wizard to go through onboarding again.

Don't have a single "pass" in hand? Two ways out:

  • Get a key from a domestic model provider—DeepSeek, Tongyi Qianwen, Zhipu GLM, Kimi, MiniMax, Doubao/Volcano Engine, Hunyuan, and Qianfan all have official provider plugins. See Model Connection Overview; then 1.6–1.12 covers configuration for each provider

  • On a tight budget? Local Models shows you how to run models on your own machine with Ollama and vLLM

  • onboarding completed: the Gateway is running in the terminal, and the browser dashboard is open (or you have entered the manual configuration page)

Step 4: Install the Gateway as a background service ​

Why: After Quick start, the Gateway runs in the terminal foreground—close the terminal and it stops. Installing it as a system service lets it stay resident in the background, which is the foundation for connecting channels, scheduled tasks, and remote access from your phone later.

First stop the foreground Gateway with Ctrl+C (the configuration is kept, no need to redo onboarding), then:

bash
openclaw gateway install

You should see: a message that the service was installed successfully. On these three systems it lands respectively as: a LaunchAgent on macOS, a systemd user unit on Linux / WSL2, and a scheduled task on native Windows (falling back to a user-level Startup entry if creation is denied).

  • openclaw gateway install runs successfully with no errors

Step 5: Verify the Gateway is running ​

Why: A background service is invisible—use one command to confirm it's alive before moving on.

bash
openclaw gateway status

You should see: the Gateway is running and listening on the default port 18789.

While you're at it, run two quick health checks (optional):

bash
openclaw --version   # 确认 CLI 可用
openclaw doctor      # 检查配置问题

You should see: --version prints the version number (this tutorial's baseline is v2026.10.9); doctor gives a configuration check result.

  • openclaw gateway status shows the Gateway listening on port 18789

Step 6: Open the Control UI and send your first message ​

Why: The Control UI is a console in the browser, and your first conversation happens right here—once you receive an AI reply, "up and running in 5 minutes" is truly achieved.

bash
openclaw dashboard

You should see: the Control UI opens in the browser (default address http://<host>:18789/). Type a message in the chat box, such as "Hello, introduce yourself"—an AI reply arrives within seconds.

At this point, "up and running in 5 minutes" is complete: the Gateway is resident, credentials are configured, and your first reply is in hand. For full usage of the Control UI, see Control UI: A Console in the Browser.

💡 By default the Gateway only listens on the local machine

Once installed, the Gateway listens by default on the local loopback address, port 18789, and cannot be reached from external machines — this is an intentional secure default. Remote access requires configuring authentication; see the rules in Security Hardening (Part One).

  • Sent a message in the Control UI and received an AI reply

Checkpoint ✅ ​

  • openclaw --version can print the version number (this tutorial's baseline is v2026.10.9)
  • onboarding reused existing credentials, or a provider was manually configured
  • openclaw gateway status shows the Gateway is running and listening on 18789
  • openclaw dashboard opens the Control UI, and the message you sent received an AI reply
  • The Gateway is installed as a background service—closing the terminal no longer affects it

Pitfall Warnings ​

❌ Node version too low (neither v20 nor v22 works) ​

Cause: OpenClaw requires Node 24.16.0+ (24.x) or 26.1.0+; Node 26 is recommended, and 24.22.1+ / 26.12.1+ is strongly recommended. v20 and v22 are out of support.

bash
node --version
# v20.x.x、v22.x.x → 太旧
# v24.16.0+(24.x)或 v26.1.0+ → 合格

Correct approach: upgrade first, then install—or simply run the official installer from step 2, which installs Node automatically if it's missing (Node 26 on macOS, Node 24 LTS on Linux). For the full details on version compatibility, see What If Installation Fails.

❌ openclaw: command not found ​

Cause: the official installation docs put it plainly—"it's almost always a PATH problem"—the npm global bin directory is not in your shell's PATH.

A three-line self-check:

bash
node -v           # Node 装了吗
npm prefix -g     # 全局包装在哪
echo "$PATH"      # 全局 bin 目录在 PATH 里吗

Correct approach: follow the PATH fix steps in What If Installation Fails; after changing PATH, remember to reopen the terminal for it to take effect.

❌ Closing the terminal and thinking OpenClaw is "broken" ​

Cause: after Quick start, the Gateway runs in the terminal foreground—Ctrl+C stops it, and so does closing the terminal; but the configuration is all preserved—nothing you installed is lost.

Correct approach: for long-term use, run the openclaw gateway install from step 4 to install it as a background service; for temporary use, just press Ctrl+C when done—no need to redo onboarding.

❌ Treating "5 minutes" as an unconditional promise ​

Cause: the official "about 5 minutes" comes with a precondition—you already have Claude Code / Codex CLI logins or a provider API key. Time spent registering accounts from scratch, applying for keys, and picking models doesn't count.

Correct approach: first go to Model Connection Overview to pick a provider and get your key ready, then come back to run the installation; during onboarding, choose Custom setup to configure manually.

Advanced Tips (Optional) ​

Stuck? One command for a self-check. openclaw triage: a read-only health check → generates a sanitized diagnostic prompt (secrets, tokens, raw chat content, and raw logs are excluded) → hands it to a coding agent detected on your machine (Claude Code, Codex CLI, or the OpenClaw built-in agent) to continue fixing with the diagnostics.

No data leaves your machine until you pick an agent; to do it yourself, choose "just print the commands". To read the diagnostic results directly, use openclaw doctor.

Customize data locations. To point OpenClaw's directories elsewhere, three environment variables:

  • OPENCLAW_HOME—the home directory for internal path resolution
  • OPENCLAW_STATE_DIR—overrides the state directory
  • OPENCLAW_CONFIG_PATH—overrides the configuration file path

Three paths on Windows. For desktop users, the officially most recommended option is the Windows Hub app (with an installer UI, tray status, and chat); the PowerShell installer on this page is the CLI route, and WSL2 is a good fit for putting the Gateway inside a Linux subsystem. For a detailed comparison of the three, see Alternative Installation Methods.

Direct npm install in one sentence. Developers who manage Node themselves (Node 24.22.1+ / 26.12.1+) can skip the install script:

bash
npm install -g openclaw@latest --allow-scripts=openclaw
openclaw onboard --install-daemon

On npm 12 or 11.16+, copy as-is; on npm 11.15 and earlier, drop --allow-scripts=openclaw. For the full comparison covering pnpm / Bun / Docker / building from source, see Alternative Installation Methods; to run 7×24 on a server, see Server Deployment.

Lesson Summary ​

✅ The main OpenClaw installation path works end to end: one curl command on macOS / Linux, one PowerShell command on Windows; onboarding automatically reuses existing credentials, the Gateway is installed as a background service, and you receive your first reply in the Control UI.

✅ You know how to choose among the three ways to get started: the official installer (recommended, installs Node automatically if missing), npx openclaw@latest (try it first, then decide), and direct npm install (for those who manage Node themselves, details in the next lesson).

✅ The boundaries of the "5-minute" claim are clear: it assumes you already have Claude Code / Codex login credentials or an API Key; the time to obtain a Key from scratch is counted separately.

✅ You know the default state after installation: the Gateway listens on 18789 and by default only accepts connections from the local machine; a Gateway running in the foreground stops when you close the terminal, while one installed as a service stays running.

CommandPurposeNotes
curl -fsSL https://openclaw.ai/install.sh | bashmacOS / Linux / WSL2 InstallOfficial installer, installs Node automatically if missing
iwr -useb https://openclaw.ai/install.ps1 | iexWindows installPowerShell version of the official installer
npx openclaw@latestOne-command trialRun the full flow without a formal install
openclaw onboard --install-daemonOnboarding after a direct installUse this for npm / pnpm / Bun direct installs
openclaw gateway installInstall as a background servicemacOS LaunchAgent / Linux systemd / Windows Task Scheduler
openclaw gateway statusConfirm the Gateway is aliveYou should see it listening on 18789
openclaw dashboardOpen the Control UIYour first conversation happens here
openclaw triageOne-click diagnosis when stuckRead-only health check + redacted diagnostics

For the complete command cheat sheet, see CLI Commands and Configuration Cheat Sheet.

Next Lesson Preview ​

The main path works, but it isn't for everyone: company machines may block scripts, some people want a desktop app, and servers call for Docker. The next lesson, Alternative Installation Methods: Desktop Apps, Docker, and npm, paves the remaining roads.

You will learn:

  • How to install the Windows Hub and the macOS menu bar app—no terminal involved
  • The complete workflow for containerized deployment with Docker / Podman
  • The parameters and respective pitfalls of direct installs via npm / pnpm / Bun
  • A comparison table: which installation method to choose for which scenario
gaodong.aiAboutPrivacyContact

Independent tutorials, not affiliated with any product mentioned. Product names and trademarks belong to their owners. Check official pages for prices and policies.