The OpenClaw npm Package: What It Is and How to Use It

The openclaw npm package ships three things in one tarball: the openclaw CLI binary, the core agent runtime that the Gateway daemon loads at startup, and a set of module exports you can import from Node or TypeScript code. Most install guides collapse all three into “run npm install -g openclaw@latest and move on.” That works for a laptop demo. It does not hold up in a monorepo with pinned versions, CI that can’t run post-install scripts, or a team that needs to know exactly which binary ended up on disk.

This guide is written for developers who already know npm. We skip the what is a package manager detour and go straight to what the package contains, how to pin it, how to wire it into a workspace, and which install errors are bugs in OpenClaw’s publish pipeline versus bugs in your setup.

---

What the openclaw npm Package Actually Contains

The mental model you need before touching npm install:

Layer	What it is	Where it lives after install
CLI binary	The openclaw command registered via the package’s bin field	$(npm prefix -g)/bin/openclaw
Core runtime	The JS modules the Gateway daemon imports at startup	$(npm prefix -g)/lib/node_modules/openclaw/dist/
SDK exports	Named exports for programmatic use from Node code	Resolvable via require('openclaw') or import from 'openclaw'
Gateway daemon	A long-running process that uses the runtime	Not in the tarball; registered separately via openclaw onboard --install-daemon

Installing the package gives you everything in the first three rows. The Gateway daemon is a separate concern: it is a launchd (macOS) or systemd user (Linux) service that the CLI installs on your behalf. You can run OpenClaw without the daemon (one-shot CLI invocations work), but any persistent agent (anything that listens for messages or wakes on a schedule) needs the daemon running.

This is the piece every content-farm article gets wrong. They describe “installing OpenClaw” as a single event. It is two events: getting the package on disk, and getting the daemon registered with your OS.

---

Install the OpenClaw npm Package

The canonical global install:

npm install -g openclaw@latest

Then, to register the Gateway daemon:

openclaw onboard --install-daemon

The onboarding wizard asks for a model provider (OpenAI, Anthropic, or a local model), an API key, and Gateway configuration. Two minutes end-to-end on a machine that already has Node.

Node.js version requirement

The package’s engines field requires Node 22.16 or higher. Node 24 is the recommended baseline. Check your version first:

node --version

If you are on Node 20 or older, the install will either refuse to run or install but crash at runtime depending on your engine-strict setting. Upgrade Node before continuing. On macOS, brew upgrade node or nvm install 24 && nvm use 24 is the path of least resistance.

Package managers other than npm

pnpm and bun both install the package cleanly:

pnpm add -g openclaw@latest
# or
bun add -g openclaw@latest

Use what your team already uses. There is no meaningful install-time difference for a single global binary. The workspace:* problem described below is where pnpm pulls ahead, but that is a plugin installation issue, not a core-package issue.

---

Install Flags Reference

When each flag matters for OpenClaw specifically:

Flag	What it does	When you need it for OpenClaw
-g / --global	Install to the user-global prefix	Default for CLI use; skip for project-local embedding
--save-exact / -E	Write the exact version to package.json	Always, for team projects (@latest is unsafe)
--prefix <path>	Install to a custom directory	CI caching, containerized builds, shared hosts
--ignore-scripts	Skip pre/post/install scripts	CI pipelines where the daemon installer is not wanted
--no-audit	Skip npm audit network call	Faster CI installs in hermetic environments
--legacy-peer-deps	Skip peer-dep conflict resolution	Rarely needed; avoid unless a plugin forces it
--omit=optional	Skip optional deps	Smaller footprint in Docker images

One flag worth singling out: --ignore-scripts. The OpenClaw install does not currently run a postinstall hook for the core package, but some plugins do (to fetch native binaries or seed state). In CI, --ignore-scripts is the safe default; you want install to be deterministic and scripts to run only on the target machine.

---

Version Pinning and Lockfile Discipline

npm install -g openclaw@latest is how the docs tell you to install it. For a team, @latest is a landmine. Your teammate’s @latest on Tuesday and your @latest on Wednesday will not be the same version if a release happens in between.

Pin to a concrete version:

npm install -g openclaw@2026.2.9 --save-exact

For project-local installs (embedding OpenClaw as a library or pinning a tool version in CI), use a package.json with the exact version:

{
  "devDependencies": {
    "openclaw": "2026.2.9"
  }
}

Then commit the lockfile. npm ci in CI will use it. No surprises.

Renovate / Dependabot

If you run Renovate or Dependabot, configure OpenClaw as a regular npm dependency and let the bot open PRs on updates. This gives you a changelog review, a chance to run tests against the new version, and a lockfile commit, versus discovering a regression because someone happened to re-run install -g.

A minimal Renovate rule that keeps OpenClaw on a weekly review cycle:

{
  "packageRules": [
    {
      "matchPackageNames": ["openclaw"],
      "schedule": ["before 9am on Monday"],
      "automerge": false
    }
  ]
}

Don’t automerge. OpenClaw releases occasionally include state migrations that run the first time the new version boots; you want a human to notice.

---

Using OpenClaw in a Monorepo

If you maintain a pnpm or yarn workspace and want OpenClaw available as a shared CLI across packages, two patterns work:

Pattern 1: Global install, reference from scripts

Keep openclaw installed globally on dev machines and CI runners. Package scripts call it:

{
  "scripts": {
    "agent:send": "openclaw send --channel slack"
  }
}

Simple, but contributors must have the same global version. Document the version in the repo’s package.json engines or in a .tool-versions file for asdf users.

Pattern 2: Project-local dev dependency

Install OpenClaw as a workspace dev dependency:

pnpm add -Dw openclaw@2026.2.9

The -w flag installs at the workspace root. Now pnpm openclaw <command> works from any package, and the version is pinned in the workspace lockfile. This is the approach we recommend for teams where reproducibility matters more than shell convenience.

---

The workspace:* Bug in Published Plugins

If you install OpenClaw plugins from npm (packages scoped under @openclaw/ like @openclaw/msteams or @openclaw/nostr), you may hit this error:

npm error code EUNSUPPORTEDPROTOCOL
npm error Unsupported URL Type "workspace:": workspace:*

This is not your setup. It is a bug in how some plugins are published: their package.json declares a dependency on "openclaw": "workspace:*", which pnpm uses internally to point at the monorepo sibling. Those workspace:* tokens are supposed to be rewritten to a concrete version range (like ^2026.2.9) at publish time. When the rewrite is missed, npm (which does not understand the workspace protocol) refuses the install.

GitHub issues #12853, #6879, and #8145 track instances of this across plugins. Three workarounds, in order of preference:

1. Install with pnpm instead. pnpm understands workspace:* and resolves it to whatever version of openclaw is already in your store.
2. Pin to a version of the plugin that was published correctly. Check the plugin’s release history on npm; skip versions where the package.json still contains workspace:*.
3. Override the dependency in your package.json. npm 8.3+ supports an overrides field:

   {
     "overrides": {
       "@openclaw/msteams": {
         "openclaw": "2026.2.9"
       }
     }
   }
   

   This forces the bad dependency to resolve to a version that exists on npm.

Report the version you hit it on to the OpenClaw repo so the publish script gets patched. This is an upstream issue, not something you should carry in your own overrides long-term.

---

Install OpenClaw in CI

A working GitHub Actions snippet for a job that needs the openclaw CLI available:

jobs:
  run-agent:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: "24"
          cache: "npm"
      - name: Install OpenClaw CLI
        run: npm install -g openclaw@2026.2.9 --ignore-scripts
      - name: Run agent task
        env:
          OPENCLAW_API_KEY: ${{ secrets.OPENCLAW_API_KEY }}
        run: openclaw send --channel slack --message "build complete"

Three things to notice:

• Pinned version. @2026.2.9, not @latest. Builds are reproducible.
• --ignore-scripts. The daemon installer has no business running in CI. You want the CLI on the PATH, nothing else.
• No openclaw onboard. Onboarding writes interactive config; it has no place in a non-interactive pipeline. Configure via environment variables instead.

For Docker images, the same principles apply: pin the version, skip scripts, and copy config in at build time rather than running onboarding.

---

Common Install Errors and Fixes

Error	Cause	Fix
EACCES: permission denied on /usr/local/lib/...	npm’s global prefix is system-owned	Reconfigure npm to a user-owned prefix (npm config set prefix ~/.npm-global, add ~/.npm-global/bin to PATH). Do not sudo npm install
EUNSUPPORTEDPROTOCOL on a plugin	workspace:* in published package.json	Install with pnpm, pin to a correctly-published version, or add an npm overrides entry
openclaw: command not found after install	$(npm prefix -g)/bin not on PATH	Add it to your shell rc: export PATH="$(npm prefix -g)/bin:$PATH"
Unsupported engine warning	Node version below 22.16	Upgrade Node to 22.16+ (24 recommended) via nvm, brew, or nodejs.org installer
Cannot find module 'git' during install	Plugin deps require git CLI	Install git (minimal Docker images often omit it)
Slow install hanging on a dependency	npm registry rate-limit or flaky network	Retry with --prefer-offline, or point at a local registry mirror

The EACCES case deserves extra attention because it is the single most common install failure. Fixing npm’s prefix once, at the start of your Node life, is worth ten minutes of setup that pays off for every global package you ever install. sudo npm install is a trap. It creates root-owned directories in your home that cause permission problems for years afterward.

---

Upgrading the OpenClaw npm Package

Two mental models live under “upgrade OpenClaw.” They are not the same command.

openclaw update

This is a CLI subcommand. It detects how OpenClaw was installed (npm, pnpm, or git), pulls the latest version, runs openclaw doctor, and restarts the Gateway daemon. Useful on a single machine. Not useful when you want explicit version control.

Flags worth knowing:

• --channel beta: switch to the beta release channel
• --tag main: pull the dev tag
• --dry-run: show what would be installed without installing

npm install -g openclaw@[version]

Direct and reproducible. You control the exact version. No daemon restart happens automatically; you trigger that yourself if you need it:

npm install -g openclaw@2026.3.0
openclaw doctor
openclaw gateway restart

For teams, this is the upgrade pattern to document. openclaw update is fine for your personal laptop. For anything shared, you want the version in a commit somewhere so rollbacks are trivial.

Downgrade

Downgrades work the same way as upgrades:

npm install -g openclaw@2026.2.9

Caveat: state migrations run on upgrade but typically do not reverse on downgrade. If you roll back after a release that migrated your config, you may need to restore the pre-migration state directory manually. Keep a backup of ~/.openclaw/ before any upgrade you are unsure about.

---

Uninstalling Cleanly

npm uninstall -g openclaw removes the binary and the runtime. It does not:

• Uninstall the Gateway daemon (still registered with launchd or systemd)
• Delete your state directory at ~/.openclaw/
• Remove any plugin packages you installed separately

A complete teardown:

# Stop and deregister the daemon
openclaw gateway uninstall

# Remove the package
npm uninstall -g openclaw

# Clear state
rm -rf ~/.openclaw

# If you had plugins
npm ls -g --depth 0 | grep '@openclaw/' | awk '{print $2}' | xargs -r npm uninstall -g

Running openclaw gateway uninstall before the npm uninstall matters. If you remove the binary first, you lose the command that cleans up the daemon registration, and you end up editing launchd plists or systemd units by hand. Do it in order.

---

Frequently Asked Questions

What does npm install -g openclaw install?

It installs three things that ship in the same tarball: the openclaw CLI binary, the core agent runtime that the Gateway daemon uses, and a set of module exports for programmatic Node use. The Gateway daemon itself is not in the tarball; it gets registered separately via openclaw onboard --install-daemon.

What Node.js version does the OpenClaw npm package require?

Node 22.16 or higher, with Node 24 recommended. The engines field in the package enforces this. Versions below 22.16 will either refuse to install or fail at runtime. Check with node --version before installing.

How do I pin OpenClaw to a specific version?

Use npm install -g openclaw@[version] --save-exact for a global install, or list it in package.json with an exact version string (no caret or tilde) for a project-local install. Commit your lockfile and use npm ci in CI. For dependency-update automation, configure Renovate or Dependabot to open PRs on new OpenClaw releases without automerging.

Can I install OpenClaw without -g as a project-local dependency?

Yes. npm install openclaw (no -g) puts it in node_modules, and you invoke the CLI via npx openclaw or a package script. This is the right pattern for monorepos and any project where CI must install the same version everyone else uses. The Gateway daemon still has to be registered separately if you want persistent agent processes.

Why does npm install fail with EUNSUPPORTEDPROTOCOL on OpenClaw plugins?

The plugin was published with "openclaw": "workspace:*" in its package.json, a pnpm-only reference that npm doesn’t understand. GitHub issues #12853, #6879, and #8145 track this. Workarounds: install with pnpm, pin the plugin to a correctly-published version, or use an npm overrides entry to force-resolve the dependency.

How do I fix EACCES errors when installing OpenClaw globally?

Reconfigure npm’s global prefix to a user-owned directory instead of /usr/local/lib. The standard fix is npm config set prefix ~/.npm-global, then add ~/.npm-global/bin to your PATH. Never use sudo npm install. It creates root-owned files in your home that cause trouble for years.

Does the npm package include the Gateway daemon?

No. The package ships the runtime that the daemon uses, but the daemon itself is a launchd (macOS) or systemd user (Linux) service that gets registered separately when you run openclaw onboard --install-daemon. You can use the CLI without the daemon for one-shot commands, but persistent agents need it running.

Can I use OpenClaw in a pnpm or yarn workspace?

Yes, and pnpm is the better choice right now because it handles the workspace:* protocol in plugin dependencies. Install at the workspace root with pnpm add -Dw openclaw@[version], then invoke via pnpm openclaw from any package. Yarn 3+ workspaces also work for the core package, but you may still hit plugin install issues until the upstream publish pipeline is fixed.

How do I upgrade OpenClaw installed via npm?

Two paths. openclaw update is a built-in subcommand that auto-detects your install method, fetches the latest, runs the doctor, and restarts the daemon. Good for a personal laptop. For teams, run npm install -g openclaw@[version] with an explicit version, then openclaw doctor && openclaw gateway restart. The explicit form makes rollbacks trivial because the version is documented.

How do I completely uninstall OpenClaw installed via npm?

Four steps: openclaw gateway uninstall to deregister the daemon, npm uninstall -g openclaw to remove the package, rm -rf ~/.openclaw to clear state, and uninstall any @openclaw/ plugins you had. Order matters. If you remove the binary before running gateway uninstall, you lose the clean teardown command and have to edit launchd or systemd units by hand.

---

Key Takeaways

• The openclaw npm package ships the CLI binary, the core runtime, and SDK exports in one tarball. The Gateway daemon is registered separately.
• Node 22.16 is the floor; Node 24 is the recommended baseline.
• Pin versions. @latest is unsafe for teams. Use --save-exact and commit your lockfile.
• Monorepos: prefer pnpm at the workspace root. Yarn and npm both work for the core package but pnpm handles plugin workspace:* quirks cleanly.
• The EUNSUPPORTEDPROTOCOL error on plugins is an upstream publish bug (GitHub issues #12853, #6879, #8145), not your setup. Workaround with pnpm or npm overrides.
• CI: pin the version, use --ignore-scripts, skip onboard, configure via env vars.
• Upgrades: openclaw update for personal use; npm install -g openclaw@[version] for teams.
• Complete uninstall requires deregistering the daemon before removing the package.

For the broader context, see our OpenClaw installation guide for the curl and Docker paths, the OpenClaw AI agent framework overview for architecture, and the OpenClaw hardware requirements guide for sizing.