Install OpenClaw on a Linux VPS: 7 Quick Fixes That Save Hours

If you want to install OpenClaw on a Linux VPS, the quickstart gets you moving, but it skips the stuff that actually burns time: package mistakes, Codex runtime issues, workspace drift, the Notion API version, and Discord/webhook schema errors.

Keep the checklist open and work through it in order.

When I tried this for real, the cleanup took longer than the install.

Quick map: host, package, runtime, workspace, integrations, then validation.

Preflight checks before you install OpenClaw on a Linux VPS

Start with a clean Ubuntu VPS and enough room for the workspace and logs. A tiny box makes every other problem look worse than it is.

Check the host first:

node -v
npm -v
uname -a
lsb_release -a

If Node or npm is old, fix that before you touch OpenClaw. A broken runtime chain looks like an app problem when it is really just an old host.

Also confirm the workspace path. On most setups it should be ~/.openclaw/workspace. An older ~/openclaw folder can create state drift and weird missing-file errors.

The package name mistake that blocks the install

This is the fastest way to waste time. People paste the wrong package name from old snippets or guessed docs.

Use this:

npm install -g openclaw

Then verify the CLI right away:

openclaw --help
openclaw doctor

If doctor reports drift, stop there and fix the config before you keep moving.

When the Codex harness is disabled

OpenClaw can route OpenAI agent turns through Codex when the plugin is enabled. If it is disabled, the runtime may fall back to PI or fail closed depending on the pin.

That makes runtime choice part of the install, not a later cleanup pass.

If you want PI, pin it at the provider level:

{
  "models": {
    "providers": {
      "openai": {
        "agentRuntime": { "id": "pi" }
      }
    }
  }
}

If you want Codex-backed turns, do not leave an old PI pin in place. Keep the model path and runtime path separate. Mixing them is how a setup looks right but behaves wrong.

After a runtime change, restart the gateway and reset the session. If /status still shows the wrong runtime, fix the pin first.

The bootstrap file problem is usually a workspace mismatch

If OpenClaw says a bootstrap file is missing, check the path before you assume the file is gone. That is usually a workspace mismatch.

This shows up a lot when files move from an older test box.

Look at the active directory first:

pwd
ls ~/.openclaw/workspace
ls ~/openclaw
openclaw doctor

If both trees exist, odds are you are editing one place while the gateway reads another.

For a clean workspace, use the setup flow instead of hand-wrangling files:

openclaw setup

That seeds the missing bootstrap files. If they already exist, do not expect restart to recreate them.

Notion API version mismatch

The Notion helper pins the API version to 2022-06-28. That tiny detail matters more than it should.

If you guess a newer version because it looks cleaner, you can break working calls.

The fix is simple:

VERSION = '2022-06-28'

If Notion starts failing, check the helper first, then the environment, then the database or page shape. Most of the time, the version pin is the real issue.

Discord and webhooks schema errors

This is another place where config shape matters more than intent.

Discord belongs under channels.discord. Webhooks belong under plugins.entries.webhooks.config.routes.

Keep those branches separate and the gateway stays happy.

A clean install sequence that holds up

If I were doing the install again, I would keep the sequence boring:

1. Verify the host and workspace.
2. Install the correct package name.
3. Choose Codex or PI on purpose.
4. Seed or repair the workspace bootstrap files.
5. Pin Notion to the expected version.
6. Keep Discord config separate from webhook routes.
7. Restart the gateway.
8. Reset the session.
9. Check status before moving on.

Useful checks:

openclaw doctor --fix
openclaw config validate
openclaw models status
openclaw models list --provider openai

If the runtime is wrong, fix that first. If the workspace is wrong, fix that first. If the config shape is wrong, fix that first.

What I would still verify manually

I would still add the final internal and external links by hand and keep the image alt text aligned with the keyword in WordPress.

For the automation follow-up, link to How I Use Make.com to Automate My Affiliate Content Pipeline. For the server hardening follow-up, add your VPS hardening checklist when it is ready.

My recommendation is simple: use this as the install checklist, tighten the config, and then move to the automation layer if you want fewer headaches.

If this helped, keep the checklist open and finish the install one step at a time.