SyntaxPilot
Courses/OpenClaw: Build Your Own AI Agent/Lesson 3
Video coming soonThis lesson’s video is being made

Start with the notes below; the video appears here as soon as it is on YouTube.

OpenClaw: Build Your Own AI Agent · Lesson 3 of 60

Installing OpenClaw

Node.js 24npmglobal installpinned versions`openclaw --version``openclaw doctor`where state and config live (storage locations)uninstall and clean reset

OpenClaw: Build Your Own AI Agent · Episode 3. Every command on this page was really run on 9 November 2026. "old-laptop" has Node.js 22.23.4 and npm 10.9.9; "laptop" has Node.js 24.22.2 and npm 10.9.9. npm's global folder is ~/.npm-global. No model and no API key are used in this episode.

The problem: the first attempt fails

Arjun's laptop is three years old and already has Node.js from a college project. He runs the one-line install:

student@old-laptop:~$ node --version && npm --version
v22.23.4
10.9.9
student@old-laptop:~$ npm install -g openclaw@2026.11.2 2>&1 | grep -v -e '^npm warn deprecated' -e funding -e 'npm fund' -e 'npm notice' | sed '/^$/d'
npm warn EBADENGINE Unsupported engine {
npm warn EBADENGINE   package: 'openclaw@2026.11.2',
npm warn EBADENGINE   required: { node: '>=24.16.0 <25 || >=26.1.0' },
npm warn EBADENGINE   current: { node: 'v22.23.4', npm: '10.9.9' }
npm warn EBADENGINE }
npm error code 1
npm error path /home/student/.npm-global/lib/node_modules/openclaw
npm error command failed
npm error command sh -c node scripts/preinstall-package-manager-warning.mjs
npm error [openclaw] error: this OpenClaw release requires Node >=24.16.0 <25 || >=26.1.0.
npm error [openclaw] detected Node 22.23.4 (exec: /opt/node22/bin/node).
npm error [openclaw] install Node: https://nodejs.org/en/download
npm error [openclaw] upgrade Node, then retry the OpenClaw update.
npm error A complete log of this run can be found in: /home/student/.npm/_logs/2026-11-09T12_27_23_776Z-debug-0.log
student@old-laptop:~$ openclaw --version
bash: line 1: openclaw: command not found

(The grep -v only hides npm's "deprecated" and "funding" chatter, and sed '/^$/d' removes blank lines.)

  • EBADENGINE is npm's warning: the package's engines field says which Node it needs, and yours doesn't match.
  • The real stop is OpenClaw's own preinstall script: a small program that runs before installation and refuses old Node versions.
  • Result: nothing installed (command not found).

Node.js and npm, from zero

On your phone On your computer
Android, the system that runs apps Node.js, the runtime: the engine that runs JavaScript programs outside a browser
The Play Store npm, the Node package manager: finds, downloads and updates packages from the npm registry (a public library of code)
An app: "requires Android 8 or newer" A package (an installable bundle of code) such as openclaw, whose engines field says node >=24.16.0 ...
On the home screen, usable from anywhere A global install (-g): a command you can run from any folder, because npm puts it on your PATH (the list of folders your shell searches for commands)

OpenClaw is written in TypeScript and runs as JavaScript on Node.js.

Reading the version rule

A version like 24.16.0 is MAJOR.MINOR.PATCH: major = big changes, minor = new features, patch = small fixes.

>=24.16.0 <25     24.16.0 or newer, but still 24.x
||                OR
>=26.1.0          26.1.0 or newer
Node Accepted? Why
22.23.4 no too old
24.10.0 no a 24, but below 24.16.0
24.22.2 yes in the first range
25.2.0 no excluded by <25, and below 26.1.0
26.1.0 yes the second range

The docs recommend Node 26, and strongly recommend at least 24.22.1 (or 26.12.1) for security fixes. Odd-numbered Node versions are short-lived releases.

The fix: a newer Node

  • Download Node 24 or 26 from nodejs.org, or
  • use a version manager such as nvm, which keeps several Node versions and switches between them (OpenClaw's own error prints nvm install 26, nvm use 26), or
  • use OpenClaw's installer script, which provisions a supported Node for you.

Ask before you install, then pin the version

student@laptop:~$ node --version && npm --version
v24.22.2
10.9.9
student@laptop:~$ npm view openclaw version && npm view openclaw@2026.11.2 engines
2026.11.2
{ node: '>=24.16.0 <25 || >=26.1.0' }
  • openclaw@latest = whatever is newest today; tomorrow it may behave differently.
  • Pinning = fixing a dependency to one exact version so a set-up is repeatable: openclaw@2026.11.2.
  • OpenClaw's versions are year.month.patch, without zero-padding (docs/reference/RELEASING.md): 2026, November, patch 2. This whole course uses 2026.11.2.
student@laptop:~$ time npm install -g openclaw@2026.11.2 2>&1 | grep -v -e '^npm warn deprecated' -e funding -e 'npm fund' -e 'npm notice' | sed '/^$/d'
added 360 packages in 49s

real    0m48.914s
user    0m18.328s
sys 0m21.999s
student@laptop:~$ which openclaw && openclaw --version
/home/student/.npm-global/bin/openclaw
OpenClaw 2026.11.2 (b556fdf)
  • The 360 packages are OpenClaw and its dependencies (packages it relies on).
  • On npm 12 or 11.16+, add --allow-scripts=openclaw so npm lets OpenClaw's install scripts run; without it npm 12 reports them as blocked because they are not covered by allowScripts. On npm 11.15 and earlier (our 10.9.9), leave the flag out.
  • pnpm: pnpm add -g --allow-build=openclaw openclaw@<version>. bun: bun add -g --trust openclaw@<version>.
  • time measures how long a command takes.

A first set-up with no model

student@laptop:~$ openclaw onboard --non-interactive --accept-risk --mode local --auth-choice skip --secret-input-mode ref --skip-daemon --skip-health --skip-channels --skip-skills --skip-search --skip-ui 2>&1 | grep -v -e DEP_PLUGIN -e trace-deprecation -e Tip:
[state/agent-db] agent database clean-close receipt: written
Workspace OK: ~/.openclaw/workspace
Sessions OK: ~/.openclaw/agents/main/sessions
Updated config: ~/.openclaw/openclaw.json
  Backup: ~/.openclaw/openclaw.json.bak
student@laptop:~$ ls -A ~/.openclaw ~/.openclaw/workspace
/home/student/.openclaw:
agents
config-journal-fingerprint.key
migration
openclaw.json
openclaw.json.bak
state
workspace

/home/student/.openclaw/workspace:
.git
AGENTS.md
BOOTSTRAP.md
IDENTITY.md
SOUL.md
USER.md
  • --auth-choice skip: no model provider yet (episodes 4 and 5).
  • --secret-input-mode ref: secrets are stored as references (pointers to where the secret really lives), never as plain text in the config.
  • --non-interactive --accept-risk: no questions; you acknowledge that agents are powerful.
  • The --skip-* flags skip the background service, the health wait, channels, skills, web search and UI prompts. Episode 5 explains onboarding fully.

Where state and config live

~/.openclaw/                 the state directory
  openclaw.json              config (JSON5)
  state/  agents/            SQLite databases, per-agent data
  workspace/                 the agent's files
  .env                       optional: provider keys (episode 4)
  • Move it with environment variables (named values your shell passes to every program it starts): OPENCLAW_STATE_DIR (the state directory) and OPENCLAW_CONFIG_PATH (the config file).
  • Separate copies: openclaw --profile work ... uses ~/.openclaw-work; --dev uses ~/.openclaw-dev with gateway port 19001.
  • Storage locations are a different feature: named destinations for artifacts such as backups (an external disk, for example). They don't move the state directory.

Reading the config without opening it

student@laptop:~$ openclaw config file
/home/student/.openclaw/openclaw.json
student@laptop:~$ openclaw config get gateway
{
  "port": 18789,
  "mode": "local",
  "bind": "loopback",
  "auth": {
    "mode": "token",
    "token": {
      "source": "store",
      "provider": "default",
      "id": "__OPENCLAW_REDACTED__"
    }
  },
  "tailscale": {
    "mode": "off"
  }
}
student@laptop:~$ openclaw config validate
Config valid: ~/.openclaw/openclaw.json

The gateway token is not a value but a reference (source: "store") into OpenClaw's SQLite secret store, and the CLI redacts the id. Without --secret-input-mode ref, onboarding's default stores the token as plain text in openclaw.json, which is easy to leak in a screenshot or commit.

A health check: openclaw doctor

student@laptop:~$ openclaw doctor --non-interactive 2>&1 | grep -E -A3 'Gateway not reachable|Doctor complete|Memory search provider' | head -14
Health check failed: GatewayTransportError: Gateway not reachable at ws://127.0.0.1:18789 (ECONNREFUSED).
Start it with `openclaw gateway run` or check `openclaw gateway status`.
Gateway target: ws://127.0.0.1:18789
Source: local loopback
--
│  Memory search provider is set to "openai" but no API key was found.     │
│  Without working primary or fallback embeddings, memory sync stops for   │
│  explicitly configured providers or existing vector indexes; new and     │
│  changed memory files are not indexed.                                   │
--
└  Doctor complete.
  • Gateway not reachable: expected, none is running (openclaw gateway run).
  • Memory search provider ... no API key: memory search needs a model to turn text into numbers (embeddings, episode 43); expected before any key is set.
  • Run doctor after installing, after upgrading, and whenever something feels wrong; openclaw doctor --fix applies the repairs it can safely make.

Start over cleanly

openclaw reset (keeps the CLI) openclaw uninstall (removes service and data)
--scope config: the config file --service: the gateway background service
--scope config+creds+sessions: plus credentials and stored sessions --state: state and config
--scope full: the state directory plus workspaces --workspace: the agent's files · --all · --app (macOS)

Always take a backup first: openclaw backup create. A dry run prints what a command would do without doing it:

student@laptop:~$ openclaw reset --scope full --yes --dry-run
Recommended first: openclaw backup create
[dry-run] stop gateway service
[dry-run] remove ~/.openclaw
[dry-run] remove ~/.openclaw/workspace
Next: openclaw onboard --install-daemon
student@laptop:~$ openclaw uninstall --state --workspace --yes --dry-run
Recommended first: openclaw backup create
[dry-run] remove ~/.openclaw
[dry-run] remove ~/.openclaw/workspace
CLI removal instructions: https://docs.openclaw.ai/install/uninstall
student@laptop:~$ openclaw uninstall --state --workspace --yes --non-interactive
Recommended first: openclaw backup create
Removed ~/.openclaw/agents
Removed ~/.openclaw/config-journal-fingerprint.key
Removed ~/.openclaw/migration
Removed ~/.openclaw/openclaw.json
Removed ~/.openclaw/openclaw.json.bak
Removed ~/.openclaw/plugin-skills
Removed ~/.openclaw/state
Removed contents of ~/.openclaw/tmp/openclaw-0
Removed ~/.openclaw/tmp/plugin-captures
Removed contents of ~/.openclaw/tmp
Removed ~/.openclaw/workspace
Removed contents of ~/.openclaw
Removed ~/.openclaw/workspace
CLI removal instructions: https://docs.openclaw.ai/install/uninstall
student@laptop:~$ ls -A ~ ; ls ~/.openclaw
.cache
.node24
.npm
.npm-global
ls: cannot access '/home/student/.openclaw': No such file or directory
student@laptop:~$ npm uninstall -g openclaw && which openclaw || echo 'openclaw: not found'

removed 508 packages in 4s
openclaw: not found

(.node24 is where this laptop's Node 24 lives; .npm and .npm-global are npm's cache and global folder. || means "if the left side fails, run the right side".) On a machine where the gateway was installed as a background service, openclaw uninstall --all also removes that service.

Install safely: the installer script

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

curl downloads the script and | (a pipe) sends it straight into bash, which runs it. It detects your OS, installs Node if needed, installs OpenClaw and starts onboarding (... | bash -s -- --no-onboard skips onboarding). Piping a download into bash runs code you have never seen, so a safer habit is:

curl -fsSL https://openclaw.ai/install.sh -o install.sh
less install.sh      # read it
bash install.sh

Only ever use the official site: during the January 2026 rename, scammers created fake accounts within minutes.

Common mistakes

Mistake Real message Why Fix
Node 22 (or 25) npm warn EBADENGINE · this OpenClaw release requires Node >=24.16.0 <25 \|\| >=26.1.0 too old / not allowed Node 24.16+ or 26.1+
npm 12 without the flag blocked because they are not covered by allowScripts npm 12 blocks install scripts --allow-scripts=openclaw
openclaw@latest in a tutorial commands differ from the video a newer version openclaw@2026.11.2
Running openclaw after uninstalling openclaw: command not found the CLI is gone install again
Uninstall with no backup sessions and memory lost state deleted openclaw backup create first

Mini project: a throw-away second copy with --profile

Keep your real set-up untouched and experiment in a separate profile:

openclaw --profile test onboard --non-interactive --accept-risk --mode local --auth-choice skip \
  --secret-input-mode ref --skip-daemon --skip-health --skip-channels --skip-skills --skip-search --skip-ui
ls ~/.openclaw-test          # the test copy's own state directory
openclaw --profile test config get gateway.port
openclaw --profile test uninstall --state --workspace --yes --dry-run

Real output of the last three commands (9 Nov 2026):

$ openclaw --profile test config get gateway.port
53445
$ openclaw --profile test uninstall --state --workspace --yes --dry-run
Recommended first: openclaw --profile test backup create
[dry-run] remove ~/.openclaw-test
[dry-run] remove ~/.openclaw-test/workspace
CLI removal instructions: https://docs.openclaw.ai/install/uninstall

--profile test isolates the state and config under ~/.openclaw-test and even gives that copy its own gateway port (53445 here, instead of 18789), so it can run next to your real one, and a reset or uninstall of that profile never touches ~/.openclaw.

Practice questions

  1. Which part of Arjun's error actually stopped the install: the EBADENGINE warning or the preinstall error?
Answer

The preinstall error. EBADENGINE is only a warning from npm; OpenClaw's preinstall script refused Node 22 and npm reported "command failed", so nothing was installed.

  1. Is Node 24.16.0 accepted? Node 24.15.9? Node 26.0.0?
Answer

24.16.0 yes (>=24.16.0 <25). 24.15.9 no (below 24.16.0). 26.0.0 no (below 26.1.0 and not <25).

  1. Why does this course install openclaw@2026.11.2 and not openclaw@latest?
Answer

Pinning makes the set-up repeatable: every command and output in the videos matches that exact version, even after newer releases.

  1. What is the difference between openclaw reset --scope full and openclaw uninstall --all?
Answer

reset keeps the CLI installed and deletes chosen data (full = state dir + workspaces, stopping the gateway service first); uninstall removes the gateway service, state, workspace and (on macOS) the app. Neither removes the npm package: that's npm uninstall -g openclaw.

Quiz

"engines": { "node": ">=24.16.0 <25 || >=26.1.0" }. Which Node version will OpenClaw 2026.11.2 accept?

A) 22.23.4 · B) 24.10.0 · C) 25.2.0 · D) 26.1.0

Answer

D. 22 is too old, 24.10.0 is below 24.16.0, and 25.x is excluded by <25 and is below 26.1.0.

Interview questions

  1. What does the engines field in package.json do? Declares which runtime versions a package supports; npm warns (EBADENGINE) on a mismatch, and a package can enforce it in a lifecycle script.
  2. Why pin dependency versions? Reproducibility: the same commands give the same behaviour later and on other machines; upgrades become deliberate.
  3. Global vs local npm install? Global (-g) installs a command on your PATH for every folder; local installs into one project's node_modules.
  4. How would you make a CLI tool's state easy to isolate for tests? Environment variables or profiles for the state and config paths (here OPENCLAW_STATE_DIR, OPENCLAW_CONFIG_PATH, --profile).
  5. Is curl ... | bash safe? It runs unreviewed remote code with your permissions; download, read, and verify the source first, and only use official URLs.

Glossary

Term Meaning (plain words) Example from this episode
Node.js the runtime that runs JavaScript outside a browser v24.22.2
Runtime the engine that runs other programs Node.js
npm Node's package manager npm install -g
Registry the public library npm downloads packages from npmjs.com
Package an installable bundle of code openclaw
Dependency a package another package relies on 360 packages added
Global install (-g) install as a command usable from any folder /home/student/.npm-global/bin/openclaw
PATH the list of folders your shell searches for commands why openclaw is found
engines the package field that says which Node it needs >=24.16.0 <25 \|\| >=26.1.0
EBADENGINE npm's warning for an unsupported engine on Node 22
preinstall script a program a package runs before installing OpenClaw's Node check
Version MAJOR.MINOR.PATCH big changes . new features . fixes 24.16.0
Version range a rule describing allowed versions >=24.16.0 <25
\|\| "or" (in a version range); in a shell, "if the left fails, run the right" both appear today
Version manager / nvm a tool to install and switch Node versions nvm use 26
Pinning fixing a dependency to one exact version openclaw@2026.11.2
year.month.patch OpenClaw's version scheme 2026.11.2
npm view ask the registry about a package npm view openclaw version
which show where a command lives which openclaw
Onboarding OpenClaw's guided set-up openclaw onboard
Secret reference a pointer to where a secret really lives source: "store"
State directory where OpenClaw keeps everything ~/.openclaw
Config file the settings file openclaw.json
JSON5 JSON that allows comments and trailing commas the config format
Environment variable a named value the shell passes to programs OPENCLAW_STATE_DIR
Profile an isolated copy of OpenClaw's state --profile work
Storage location a named destination for artifacts like backups an external disk
openclaw doctor health checks and safe fixes gateway not reachable
Embeddings numbers that represent the meaning of text needed for memory search
Dry run show what a command would do, without doing it --dry-run
openclaw reset delete chosen state, keep the CLI --scope full
openclaw uninstall remove service, state, workspace, app --state --workspace
Backup a restorable copy openclaw backup create
Installer script a script that sets everything up install.sh
curl a command that downloads from a URL curl -fsSL ...
Pipe (\|) send one command's output into another ... \| bash

Summary

  • Node.js is the runtime, npm the package manager, -g a global command.
  • OpenClaw 2026.11.2 needs Node >=24.16.0 <25 || >=26.1.0; on Node 22 the install fails (EBADENGINE + the preinstall check).
  • Pin the version: npm install -g openclaw@2026.11.2 (versions are year.month.patch); add --allow-scripts=openclaw on npm 12 / 11.16+.
  • State lives in ~/.openclaw (OPENCLAW_STATE_DIR, OPENCLAW_CONFIG_PATH, --profile, --dev); read config with openclaw config get/file/validate.
  • openclaw doctor checks health; dry runs come before openclaw reset and openclaw uninstall; npm uninstall -g openclaw removes the command.
  • Next: Episode 4, model providers and API keys, safely.