OpenClaw CLI: Install, Set Up, and Add Plugins (npm Guide)

What Is OpenClaw?

OpenClaw is an open-source CLI framework for building AI-powered messaging assistants. It connects to email, WhatsApp, iMessage, and other channels through a plugin system. You install it from npm, add plugins for the integrations you need, and configure each one through a straightforward JSON config. OpenClaw handles tool registration, message routing, and approval workflows so you can focus on what the agent does rather than how it connects.

What Is the OpenClaw npm Package Name?

The npm package name is openclaw. This is the most common search query about OpenClaw, so here it is up front: the package you install globally is called openclaw, published on the npm registry. There is no scope prefix for the core CLI itself. Plugins use scoped names like @nylas/openclaw-nylas-plugin, but the CLI binary comes from the openclaw package.

# The npm package name is "openclaw"
npm install -g openclaw

How Do I Install OpenClaw CLI?

OpenClaw requires Node.js 22.12.0 or later. Check your Node version first, then install the CLI globally from npm. The global install gives you the openclaw command available system-wide in your terminal. The entire install takes under a minute on most connections.

# Check Node.js version (must be 22.12.0+)
node --version

# Install OpenClaw CLI globally
npm install -g openclaw

# Verify the installation
openclaw --version

If you see a version number, the install succeeded. If you get a permission error, see the troubleshooting section below.

On systems where you manage Node.js with nvm, make sure your active Node version is 22.12.0 or above before running the install:

# Switch to Node.js 22 with nvm
nvm install 22
nvm use 22

# Then install openclaw
npm install -g openclaw

What Are the System Requirements?

OpenClaw runs on macOS, Linux, and Windows. The only hard requirement is Node.js 22.12.0 or later. The CLI uses native ES modules and Node.js built-in test runner features that require this minimum version. Below is a quick reference for supported platforms and their recommended install method for Node.js.

How Do I Install OpenClaw Plugins?

OpenClaw has a built-in plugin manager that downloads packages from npm and registers them with the CLI. Plugins extend OpenClaw with new tools, integrations, and commands. You install, list, update, and remove plugins using the openclaw pluginssubcommands. No restart is needed after installing a plugin.

# Install a plugin
openclaw plugins install <package-name>

# Example: install the Nylas plugin for email, calendar, and contacts
openclaw plugins install @nylas/openclaw-nylas-plugin

# Verify it was installed
openclaw plugins list

Plugin management commands reference

How Do I List Installed OpenClaw Plugins?

Run openclaw plugins list to see every installed plugin along with its version and active status. This is useful for verifying installs, checking for outdated plugins, and debugging issues where a plugin is installed but not loading. The --json flag outputs machine-readable data you can pipe to jq or other tools.

# List all installed plugins
openclaw plugins list

# Example output:
# NAME                              VERSION  STATUS
# @nylas/openclaw-nylas-plugin      1.2.0    active
# openclaw-whatsapp-bridge          0.9.1    active
# openclaw-imsg                     0.8.3    active

# JSON output for scripting
openclaw plugins list --json

How Do I Uninstall OpenClaw Plugins?

Use openclaw plugins uninstall followed by the package name. This removes the plugin and deregisters all its tools. The change takes effect immediately without restarting OpenClaw.

# Uninstall a plugin
openclaw plugins uninstall @nylas/openclaw-nylas-plugin

# Verify it was removed
openclaw plugins list

How Do I Set Up OpenClaw on Windows?

OpenClaw works on Windows natively through PowerShell. Install Node.js 22.12.0 or later from the official installer at nodejs.org, then install OpenClaw globally. If you hit permission errors, open PowerShell as Administrator. Windows Subsystem for Linux (WSL) also works and follows the standard Linux instructions.

# Windows PowerShell setup
# 1. Install Node.js 22+ from https://nodejs.org (use the LTS installer)

# 2. Open PowerShell and verify Node.js
node --version

# 3. Install OpenClaw globally
npm install -g openclaw

# 4. Verify
openclaw --version

# 5. If you get EACCES or permission errors, run PowerShell as Administrator:
# Right-click PowerShell → "Run as Administrator"
# Then repeat: npm install -g openclaw

On Windows, the OpenClaw config directory is %USERPROFILE%\.openclaw\. Plugins and configuration files live in that directory. Make sure your PATH includes the npm global bin directory, which the Node.js installer normally sets up automatically.

How Do I Set Up the iMessage CLI Path for OpenClaw?

The openclaw-imsg plugin bridges OpenClaw to iMessage on macOS. After installing the plugin, you need to configure the path to the iMessage CLI binary so OpenClaw knows where to find it. This is required because macOS sandboxing means the binary location varies depending on how you installed it.

# Install the iMessage plugin
openclaw plugins install openclaw-imsg

# Set the iMessage CLI binary path
openclaw config set imsg.cliPath "/usr/local/bin/imsg-cli"

# If you installed imsg-cli via Homebrew:
openclaw config set imsg.cliPath "$(brew --prefix)/bin/imsg-cli"

# Verify the path is set
openclaw config get imsg.cliPath

# Test the iMessage connection
openclaw imsg status

The imsg.cliPath config value must point to the actual binary. If you get "command not found" errors from the plugin, the path is wrong or the binary does not exist at that location. Use which imsg-cli to find the correct path on your system.

How Do I Set Up WhatsApp with OpenClaw?

The openclaw-whatsapp-bridge plugin connects OpenClaw to the WhatsApp Business API. You need a WhatsApp Business account and access token from the Meta developer dashboard. The plugin handles message sending, receiving, and webhook registration. Setup takes about five minutes once you have your credentials.

# Install the WhatsApp bridge plugin
openclaw plugins install openclaw-whatsapp-bridge

# Configure your WhatsApp Business credentials
openclaw config set whatsapp.accessToken "YOUR_ACCESS_TOKEN"
openclaw config set whatsapp.phoneNumberId "YOUR_PHONE_NUMBER_ID"
openclaw config set whatsapp.businessAccountId "YOUR_BUSINESS_ACCOUNT_ID"

# Verify the configuration
openclaw whatsapp status

# Send a test message
openclaw whatsapp send --to "+1234567890" --message "Hello from OpenClaw"

WhatsApp Business API requires a verified business account through Meta. The access token is generated in the Meta Developer Portal under your WhatsApp app settings. The phone number ID identifies which WhatsApp number sends messages on behalf of your agent.

How Do I Configure exec-approvals.json?

When OpenClaw plugins need to run shell commands (for example, piping output to local tools), they go through the exec approval system. The exec-approvals.json file in your OpenClaw config directory controls which commands are allowed, denied, or require confirmation. This prevents plugins from running arbitrary commands on your system.

// The config file lives at:
// macOS/Linux: ~/.openclaw/exec-approvals.json
// Windows: %USERPROFILE%\.openclaw\exec-approvals.json

// Example exec-approvals.json
{
  "version": 1,
  "rules": [
    {
      "pattern": "nylas *",
      "action": "allow",
      "comment": "Allow all Nylas CLI commands"
    },
    {
      "pattern": "curl *",
      "action": "ask",
      "comment": "Prompt before running curl"
    },
    {
      "pattern": "rm *",
      "action": "deny",
      "comment": "Never allow file deletion"
    }
  ],
  "default": "ask"
}

The default field controls what happens when no rule matches. Set it to "ask" to be prompted for unknown commands, "deny" to block everything not explicitly allowed, or "allow" if you trust all plugins completely. For most users, "ask" is the safest default.

# View your current exec approvals config
cat ~/.openclaw/exec-approvals.json

# Reset to defaults
openclaw config reset exec-approvals

How Do I Add the Nylas Plugin to OpenClaw?

The @nylas/openclaw-nylas-plugin gives your OpenClaw assistant native email, calendar, and contacts tools. It is the most popular OpenClaw plugin and has a dedicated guide with full setup instructions, tool reference, and troubleshooting. Install it in one command:

# Install the Nylas plugin
openclaw plugins install @nylas/openclaw-nylas-plugin

# Configure your Nylas API key
openclaw config set nylas.apiKey "YOUR_NYLAS_API_KEY"

# Discover connected email accounts
openclaw nylas discover

# Test connectivity
openclaw nylas test

For the full walkthrough including multi-account setup, tool reference tables, and troubleshooting, see the Install the OpenClaw Nylas Plugin guide.

Troubleshooting: "command not found" After npm install -g

If you run npm install -g openclaw successfully but then get openclaw: command not found, the npm global bin directory is not in your PATH. This is the most common post-install issue, especially on Linux and macOS with custom Node.js installs.

# Find where npm installs global binaries
npm config get prefix

# The binary will be at <prefix>/bin/openclaw
# Add the bin directory to your PATH

# For bash (~/.bashrc):
echo 'export PATH="$(npm config get prefix)/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

# For zsh (~/.zshrc):
echo 'export PATH="$(npm config get prefix)/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

# Verify it works
openclaw --version

If you use nvm, the global prefix changes when you switch Node versions. Make sure you install OpenClaw under the Node version you use day-to-day. Running nvm use 22 && npm install -g openclaw ensures the binary is available whenever Node 22 is active.

Troubleshooting: Plugin Install Fails

If openclaw plugins install fails with a network or permission error, try these steps in order:

# 1. Check your Node.js and npm versions
node --version   # Must be 22.12.0+
npm --version    # Must be 10+

# 2. Clear the npm cache
npm cache clean --force

# 3. Try installing again
openclaw plugins install @nylas/openclaw-nylas-plugin

# 4. If behind a corporate proxy, configure npm
npm config set proxy http://proxy.company.com:8080
npm config set https-proxy http://proxy.company.com:8080

# 5. If permissions fail on macOS/Linux, fix npm prefix ownership
sudo chown -R $(whoami) $(npm config get prefix)/{lib/node_modules,bin,share}

Troubleshooting: Plugin Installed but Not Loading

If openclaw plugins list shows a plugin but its tools or commands are not available, the plugin may have failed to initialize. Check the OpenClaw debug log for errors and try reinstalling:

# Check debug logs for plugin errors
openclaw --debug 2>&1 | grep -i plugin

# Reinstall the problematic plugin
openclaw plugins uninstall <package-name>
openclaw plugins install <package-name>

# Verify it loads correctly
openclaw plugins list

Next Steps

Now that you have OpenClaw installed and configured, explore these related guides:

• Install the OpenClaw Nylas Plugin — add email, calendar, and contacts tools with typed schemas and auto-discovery
• Build a Personal Assistant with Nylas CLI and OpenClaw — the exec-based approach using shell commands and the Nylas CLI directly
• Nylas CLI Command Reference — full reference for all Nylas CLI commands, flags, and options