How to Install OpenClaw on macOS, Linux, and Windows

OpenClaw is a self-hosted AI agent gateway that can connect a model to tools and messaging channels. The safest first setup is local: install from the official source, bind the Gateway to the local machine, enable authentication, skip public chat channels, and test a low-risk task in the Control UI.

OpenClaw changes quickly. The requirements and commands below were checked against the official documentation on August 28, 2026. Review the current installation page before running an installer.

System requirements

macOS, Linux, or Windows. Windows users can use the native Windows Hub, PowerShell CLI installer, or WSL2 Gateway.
Node.js 22.22.3 or later in the Node 22 line, Node 24.15 or later, or Node 25.9 or later. Node 26 is recommended; Node 23 is not supported.
An account or API key for a supported model provider. Onboarding verifies inference before finishing.
Permission to install software and run a local background service.

Check an existing Node installation:

node --version

The official installer can provision a supported Node version when necessary. If you manage Node yourself, prefer a version manager or a user-level installation over running global npm commands with sudo.

Choose an installation method

Method	Best for	Notes
Official installer	Most macOS, Linux, and WSL users	Checks Node, installs OpenClaw, and can start onboarding
Windows Hub	Windows desktop users who want a graphical setup	Provides setup, status, chat, and diagnostics
PowerShell installer	Native Windows CLI/Gateway	Use only the official `openclaw.ai` script
npm	Users who already manage a supported Node runtime	Installs the CLI globally in the current npm prefix
Build from source	Contributors and developers auditing or modifying code	Requires additional tooling such as pnpm

Install on macOS, Linux, or WSL2

The official quick installer is:

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

Piping a remote script directly to a shell is convenient but gives the downloaded code immediate access under your user account. If your environment requires review, download the script from the same official URL, inspect it, verify the domain, then run the local copy.

After installation, confirm the CLI:

openclaw --version

Install on Windows

For a desktop-first setup, use the Windows Hub described in the official Windows guide. It includes setup, tray status, chat, and diagnostics.

For the native CLI, use the official PowerShell installer documented by OpenClaw. WSL2 is the most Linux-compatible option for a Gateway. Do not copy an installer from a forum, shortened URL, or unofficial package mirror.

After either CLI path, open a new terminal and run:

openclaw --version

Manual npm installation

If a supported Node version is already installed:

npm install -g openclaw@latest
openclaw --version

If the command is not found, inspect the npm prefix:

npm config get prefix

Add that prefix's executable directory to your user PATH using the method appropriate to your shell or Windows settings. Do not solve a permissions error by defaulting to sudo npm install -g; use a user-writable npm prefix, version manager, or the official installer.

Run secure onboarding

openclaw onboard --install-daemon

The guided flow configures model access, workspace, Gateway, optional channels, skills, and service installation. On first use, OpenClaw asks you to acknowledge that an agent with system and tool access can be risky.

For a safe first run:

Mode: local.
Gateway bind: loopback/local machine, not a public interface.
Gateway authentication: keep token authentication enabled and protect the token.
Model: use a provider account approved for the data you will test.
Channels: skip WhatsApp, Telegram, Slack, Discord, and other external channels until local behavior is understood.
Skills and tools: install only what the first task needs.
Daemon: install it only if you want OpenClaw to continue running in the background.

Choosing “Skip for now” at model authentication does not produce a usable running agent; current onboarding verifies a real completion before continuing.

Verify the Gateway and open the dashboard

openclaw gateway status
openclaw dashboard

The default local Gateway listens on port 18789. The dashboard command opens the Control UI in a browser. If the page loads and authentication succeeds, send a harmless first message such as:

Explain what you can access in this workspace.
Do not read files, run commands, or make changes.

Next, test a bounded coding question that does not require tool execution:

Find the boundary error in this function and show a corrected version.
Do not run it.

function calculateTotal(items) {
  let total = 0;
  for (let i = 0; i <= items.length; i++) {
    total += items[i].price * items[i].quantity;
  }
  return total;
}

The loop should use i < items.length; otherwise the final iteration accesses an item beyond the end of the array. Correctly explaining the bug confirms model responses, but it does not test every tool or security setting.

Understand the workspace and state

The default agent workspace is:

~/.openclaw/workspace/

Onboarding creates starter files such as:

~/.openclaw/
├── openclaw.json
└── workspace/
    ├── AGENTS.md
    ├── SOUL.md
    ├── IDENTITY.md
    └── USER.md

AGENTS.md contains operating guidance and tool notes for the workspace.
SOUL.md describes behavioral style or personality.
IDENTITY.md describes the agent identity.
USER.md contains user-specific context you choose to provide.

MEMORY.md is optional and is not automatically created in every workspace. OpenClaw also keeps agent state and credentials outside these Markdown files. Do not publish or commit secrets. If you version the workspace, use a private repository and review every file before committing.

Security checks before adding channels or tools

Keep the Gateway bound to loopback unless remote access has been deliberately secured.
Run openclaw security audit and review its findings.
Keep the tool profile and sandbox conservative while evaluating the agent.
Use separate, least-privilege accounts for connected services.
Allowlist who can message each channel; do not expose a personal inbox to arbitrary senders.
Use a dedicated assistant number for WhatsApp rather than linking a personal number.
Do not place API keys in AGENTS.md, SOUL.md, prompts, or chat history.
Review installed skills and plugins as executable supply-chain components.
Disable proactive polling or heartbeats until you understand their actions and cost.
Back up configuration safely before major changes or updates.

For broader architecture choices, compare AI agent frameworks. A simple local assistant does not need every channel, skill, memory source, or tool on day one.

Troubleshooting

Problem	Check
`openclaw: command not found`	Open a new terminal, check the npm prefix or installer output, and confirm the executable directory is on PATH
Unsupported Node version	Install a supported Node line; Node 23 is unsupported
Onboarding stops at model setup	Confirm the provider credential, network access, account entitlement, and model selection; onboarding requires a successful completion
Gateway is not running	Run `openclaw gateway status`, then inspect the reported service error
Port conflict	Check the configured Gateway port; the current default is 18789, not 3000
Dashboard cannot authenticate	Use the configured Gateway token or password and keep the URL local
Unclear or multiple failures	Run `openclaw triage` for read-only diagnostics or `openclaw doctor` to inspect findings

The triage command sanitizes its diagnostic prompt and does not send it anywhere until you choose an agent. Read the output before approving a handoff.

Update and uninstall deliberately

Use the update method that matches the installation method; mixing npm, Homebrew, source builds, and an app installer can leave conflicting binaries. Before upgrading, read release notes and back up the workspace and configuration without copying exposed secrets into an insecure archive.

OpenClaw can act on files, commands, and connected accounts. Learn the structure of an AI automation workflow, then add one low-risk capability at a time and verify its logs and permissions.

Question 1:

Which Node.js versions are supported by the current OpenClaw documentation?
- A. Any Node 18 release
- B. Node 23 only
- C. Node 22.22.3+, 24.15+, or 25.9+, with Node 26 recommended
- D. Node is not required
EXPLAIN:

OpenClaw documents supported minimums for the Node 22, 24, and 25 lines and recommends Node 26. Node 23 is unsupported.
Question 2:

What does openclaw onboard --install-daemon do?
- A. It grants every tool full system access
- B. It runs guided setup and can install the background Gateway service
- C. It deletes an existing workspace
- D. It installs a model locally without a provider
EXPLAIN:

Onboarding configures model access, workspace, Gateway, optional channels and tools; the flag also requests service installation.