easy⚡Node easyNode

Documentation

Upgrading Node.js when an OpenClaw update is refused

easyClaw Updated

OpenClaw runs on Node.js, and each OpenClaw release declares the Node versions it supports. When a new OpenClaw needs a newer Node than your easyClaw appliance has, the Upgrade OpenClaw button on Settings → Updates refuses to run and shows a message like:

OpenClaw requires Node.js >=24.16.0 <25 || >=26.1.0, but the newest Node available
to this appliance is v22.23.4. Upgrade aborted — OpenClaw was NOT changed, so the
gateway is still running.

This is the appliance protecting you. Installing that OpenClaw on the old Node would have killed your agent. Nothing has changed, your agent keeps working on its current OpenClaw, and the fix takes about two minutes over SSH.

Why the button cannot do this for you

Your appliance installs Node.js from the NodeSource package repository, and that repository is per major version. A box set up with node_22.x can only ever receive Node 22 updates, however many times it checks for packages. OpenClaw 2026.10 and later require Node 24, so the appliance has to be pointed at the node_24.x repository first. That is a one-line change, but it is a change to your system’s package sources, so easyClaw asks you to make it rather than doing it silently.

Before you start

  • You need SSH access as the appliance user, easyvps. The password is on your node’s card in the easyNode dashboard (Reveal password), unless you have changed it.
  • The agent stays up while Node installs, but you restart it at the end, which interrupts any conversation in progress for a few seconds.
  • Not comfortable at a shell? Open a case from the appliance’s Support page and mention “Node.js upgrade for OpenClaw”. Support can do this for you.

Step 1: see which Node repository the appliance uses

cat /etc/apt/sources.list.d/nodesource.sources /etc/apt/sources.list.d/nodesource.list 2>/dev/null | grep -o 'node_[0-9]*\.x'
node -v

You will typically see node_22.x and a v22.… version. The error message on the Updates page tells you which major OpenClaw now needs. For >=24.16.0 <25 that is 24.

Step 2: switch the repository to the required major

Replace 22 and 24 with what you saw and what you need:

sudo sed -i 's#node_22\.x#node_24.x#' /etc/apt/sources.list.d/nodesource.*
sudo apt-get update && sudo apt-get install -y nodejs

If Step 1 printed no node_NN.x line at all, there is no NodeSource repository on the box. Add it instead:

curl -fsSL https://deb.nodesource.com/setup_24.x | sudo -E bash -
sudo apt-get install -y nodejs

Do not install Node with nvm or n. The appliance’s services run /usr/bin/node and will not see a user-level Node.

Step 3: confirm and restart easyClaw

node -v
sudo systemctl restart easyclaw-webui openclaw-gateway

node -v must now print a version inside the required range, for example v24.22.1. The restart makes both the easyClaw web UI and the OpenClaw gateway run on the new Node. Wait about 15 seconds, reload your dashboard, and send your agent a quick hello in chat to confirm it still answers.

Step 4: run the OpenClaw upgrade again

Back in Settings → Updates, click Check for updates, then Upgrade OpenClaw. The Node check now passes and the upgrade proceeds as normal, with a backup taken first.

After a large OpenClaw jump, for example from a 2026.6 release to 2026.10 or later, the new version may need a one-time fix-up of plugins or configuration. If your agent does not answer after the upgrade, do not roll back straight away. Open a Support case and say which OpenClaw version you came from and went to. Support can finish the migration; your conversations and settings are intact.

If something goes wrong

  • E: dpkg was interrupted: a previous package operation was cut short. Run sudo dpkg --configure -a, then repeat Step 2. The Updates → Hotfixes lane on the appliance can also repair this.
  • apt reports unmet or broken dependencies: run sudo apt-get -f install -y, then repeat Step 2.
  • The gateway does not come back after the restart: run sudo systemctl reset-failed openclaw-gateway && sudo systemctl restart openclaw-gateway. If chat still shows “OpenClaw Gateway is starting” after a minute, open a Support case and include the output of sudo journalctl -u openclaw-gateway -n 50.

The same guide is available on every appliance at Help → Upgrading Node.js (/help/node-upgrade), and the Updates page prints these commands with your appliance’s own version numbers filled in.

Frequently asked questions

Is my agent broken when I see 'Upgrade aborted — OpenClaw was NOT changed'?

No. Nothing was changed. The appliance refused to install an OpenClaw that would not run on its current Node.js, and your agent keeps working on the OpenClaw it already has.

Why doesn't easyClaw just upgrade Node.js for me?

It does when a newer patch of the same Node major is enough. When OpenClaw moves to a new Node major (22 → 24), the fix is a change to your system’s package sources, which easyClaw asks you to make deliberately rather than silently.

Can I use nvm or n to install Node 24 instead?

No. The appliance’s services run /usr/bin/node from the system package. A user-level Node installed with nvm or n is not seen by them.

The gateway shows 'OpenClaw Gateway is starting' forever after the restart.

Run sudo systemctl reset-failed openclaw-gateway && sudo systemctl restart openclaw-gateway. If it still does not come back after a minute, open a Support case with the output of sudo journalctl -u openclaw-gateway -n 50.