OpenClaw Installation Guide
OpenClaw Installation Guide
This page is for the first real OpenClaw setup, not a vague overview.
It is written for two kinds of readers:
- people who are completely new to OpenClaw
- people who already know what OpenClaw is, but want a cleaner first setup path
If you only do one thing, do this
Your first OpenClaw success should look like this:
- you choose one install lane
- you finish setup and create a workspace
- Gateway starts cleanly
- you connect one real channel
- one real message completes the loop
If you do not reach that fifth step, the install is not done yet.
Quick facts
- Best for: first-time OpenClaw setup
- Tested environment: based on the current official docs flow; confirm your exact OpenClaw version before production use
The 4-step beginner install path
If you only need one clean path, use this:
Step 1: choose one install lane
Pick only one of these for the first pass:
- stable app-first path
- source-first path
Do not mix them on day one.
Step 2: prepare the machine
Confirm the baseline first:
- Node.js 22+
pnpm- Docker only if your setup really needs container workflows
If these are wrong, stop here and fix them before touching OpenClaw.
Step 3: run setup and create your workspace
Your first success condition is not “I saw the project.”
It is:
- setup completed
- workspace was created
- config was created
- Gateway can start cleanly
Step 4: connect one channel and run a health check
Only connect one real channel for the first pass.
Then verify:
- channel login succeeded
- health check passed
- one real message completed the loop
If those three are true, the first install is good enough to move forward.
What to decide before you install
Before running commands, make four decisions:
- Do you want the stable workflow or the source workflow?
The official docs currently recommend the macOS app as the more stable path, while source-based Gateway workflows are better when you want to debug or customize more deeply.
- Where will OpenClaw run?
- local machine first
- a longer-running personal workstation
- a hosted runtime later, after local validation
- Which channels matter first?
Do not try to connect every channel on day one. Pick the first real delivery surface you care about, such as Telegram, Discord, or another chat entry point.
- What counts as “working”?
A good first milestone is simple:
- OpenClaw is installed
- the setup command completes
- one channel is linked
- one health check passes
Core prerequisites
According to the official setup docs, the source workflow currently expects:
- Node.js 22 or newer
pnpm- Docker only if you need container-related workflows or local e2e support
If you are missing one of these, fix that first instead of debugging OpenClaw itself.
Recommended first-install path
Option A: stable first install
This is the safest path if your goal is “get OpenClaw working quickly.”
- Install and launch the OpenClaw app if that is available for your platform.
- Complete onboarding and permissions prompts.
- Let the app manage the local Gateway.
- Link your first channel.
- Run a health check.
The important lesson is not speed. It is reducing the number of moving parts in your first setup.
Option B: source-first install
Use this path if you want a more developer-oriented workflow.
- Prepare the machine with Node.js and
pnpm. - Run the setup flow to create your local OpenClaw workspace and config.
- Build the project if you are running from source.
- Start the Gateway in a terminal.
- Link a channel and run a health check.
For source workflows, keep your personal workspace and config outside the repo so future updates do not overwrite your customizations.
First-run checklist
After installation, confirm these in order:
- the setup flow finished without permission or auth errors
- your workspace and config were created successfully
- the Gateway is running
- your first channel login succeeded
- a health check returns successfully
- you can send one real message and get the expected reply back
If you skip this checklist, you may think OpenClaw is installed when only half the path is working.
Common failure points
1. Wrong runtime expectations
People often mix app-first docs with source-first steps. Pick one path first and finish it before combining workflows.
2. Missing environment basics
If Node.js or pnpm is off, the rest of the install will fail in confusing ways. Verify the basics before touching model or channel setup.
3. Channel setup too early
Trying to connect multiple channels before you confirm local health makes troubleshooting much harder. One channel is enough for the first pass.
4. No health check after linking
Channel login alone is not enough. Run a health check after pairing so you know the assistant can actually operate.
5. Linux always-on assumptions
The official docs note that Linux user services may stop on logout unless lingering or a system service is configured. If you want a persistent setup, plan for that early.
What to open right after this page
Do not decide the next step yourself. Use this exact order:
- OpenClaw Setup Checklist — confirm environment, Gateway, one channel, and a real reply loop.
- OpenClaw Discord Guide — use one real channel to validate your first working path.
- OpenClaw Heartbeat Guide — add the first recurring health signal after setup works.
- OpenClaw Resources — only after the core loop works, use the resource directory to explore deeper docs and vendor guides.
When to move from local install to hosted deployment
Do not start with hosted deployment just because it feels more “serious.”
Move to Cloudflare Workers or another hosted path only after you can answer yes to these:
- the local setup is healthy
- you know which channel and workflow you care about first
- your prompts and heartbeat expectations are clear
- you understand what must live in config, secrets, and workspace files
Hosted deployment is a scaling step, not the first proof that OpenClaw works.
When you are ready for that move, use the OpenClaw Cloudflare Guide instead of improvising your own first deploy path.