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.)
EBADENGINEis npm's warning: the package'senginesfield says which Node it needs, and yours doesn't match.- The real stop is OpenClaw's own
preinstallscript: 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=openclawso 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>. timemeasures 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) andOPENCLAW_CONFIG_PATH(the config file). - Separate copies:
openclaw --profile work ...uses~/.openclaw-work;--devuses~/.openclaw-devwith 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 --fixapplies 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
- 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.
- 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).
- Why does this course install
openclaw@2026.11.2and notopenclaw@latest?
Answer
Pinning makes the set-up repeatable: every command and output in the videos matches that exact version, even after newer releases.
- What is the difference between
openclaw reset --scope fullandopenclaw 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
- What does the
enginesfield 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. - Why pin dependency versions? Reproducibility: the same commands give the same behaviour later and on other machines; upgrades become deliberate.
- Global vs local npm install? Global (
-g) installs a command on your PATH for every folder; local installs into one project'snode_modules. - 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). - Is
curl ... | bashsafe? 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,
-ga 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=openclawon npm 12 / 11.16+. - State lives in
~/.openclaw(OPENCLAW_STATE_DIR,OPENCLAW_CONFIG_PATH,--profile,--dev); read config withopenclaw config get/file/validate. openclaw doctorchecks health; dry runs come beforeopenclaw resetandopenclaw uninstall;npm uninstall -g openclawremoves the command.- Next: Episode 4, model providers and API keys, safely.