OpenClaw CLI

Command-line interface for managing the Gateway, channels, devices, cron jobs, and all OpenClaw operations. Installed alongside the Gateway.

The OpenClaw CLI is the primary management interface for your entire OpenClaw installation. It's installed alongside the Gateway via npm and covers everything: gateway lifecycle (install, start, stop, restart), channel management (add, remove, login, status), device pairing and node control, cron job scheduling, message sending, model configuration, plugin management, memory indexing, diagnostics, and more. The CLI is organized into a clean command tree with subcommands for each domain. Key top-level commands include: 'openclaw gateway' for daemon management, 'openclaw channels' for messaging platform setup, 'openclaw devices' for node pairing, 'openclaw cron' for scheduled tasks, 'openclaw models' for AI model configuration, 'openclaw plugins' for extension management, 'openclaw doctor' for diagnostics, and 'openclaw dashboard' for quick browser access to the Control UI. Global flags provide powerful isolation: --dev shifts to ~/.openclaw-dev with different ports (useful for development), --profile isolates state under ~/.openclaw-<name> (great for multiple configurations on one machine), and --no-color disables ANSI styling for clean piping. The CLI uses a distinctive lobster color palette with accent (#FF5A2D), success (#2FBF71), and error (#E23D2D) colors, and supports OSC-8 hyperlinks in modern terminals. The CLI doesn't require a running Gateway for all operations — commands like 'openclaw configure', 'openclaw doctor', and 'openclaw gateway install' work standalone. This makes it the first tool you interact with during onboarding and the go-to for troubleshooting when things aren't working. Node.js 22+ is required, and the CLI runs on macOS, Linux, and Windows (via WSL2).

Tags: cli, terminal, management, cross-platform

Use Cases

  • Initial setup and onboarding — 'openclaw onboard' is the entry point for new installations
  • Gateway lifecycle management — install, start, stop, restart the Gateway daemon via launchd or systemd
  • Channel configuration — add Telegram, Discord, WhatsApp, or other messaging platforms
  • Device pairing — approve node pairing requests from iOS, Android, and macOS apps
  • Cron job management — schedule, list, edit, and monitor recurring AI tasks
  • Diagnostics and troubleshooting — 'openclaw doctor' and 'openclaw health' for system checks
  • Scripting and automation — use --json output for integration with other tools and scripts

Tips

  • Start with 'openclaw onboard' for guided setup — it walks through Gateway config, channel setup, and model configuration
  • Use 'openclaw doctor' as your first troubleshooting step — it checks Node.js version, Gateway connectivity, API keys, and channel health
  • Install shell completion ('openclaw completion') for tab-completion of commands and subcommands
  • Use 'openclaw status' for a quick health check — it shows Gateway uptime, connected channels, active sessions, and node status
  • Pipe CLI output with --json or --plain flags for scripting and automation
  • Use profiles (--profile work) to maintain separate configurations on the same machine
  • Check 'openclaw logs' for real-time Gateway logs when debugging issues

Known Issues & Gotchas

  • Requires Node.js 22+ — older Node.js versions will fail with syntax errors or missing APIs
  • Bun is not recommended as the Gateway runtime — while the CLI may install, the Gateway needs Node.js for full compatibility
  • The --dev flag shifts ALL paths to ~/.openclaw-dev and changes default ports — don't use it accidentally in production
  • Some CLI commands need a running Gateway (status, sessions, message) while others work standalone (configure, doctor, gateway install)
  • On headless servers, 'openclaw dashboard' prints the URL instead of opening a browser — use SSH tunnel to access
  • 'openclaw update' behavior differs between npm installs and source installs — check 'openclaw --version' to know your install type
  • Shell completion (openclaw completion) needs to be sourced in your shell profile to work

Community Feedback

The ULTIMATE OpenClaw Setup Guide: start with 'openclaw onboard' and it walks you through everything. The CLI is surprisingly polished for an open-source project.

— Reddit r/OpenClawInstall

OpenClaw is god-awful. You have to spend a lot of time fighting the CLI and config. 150 million tokens just trying to get things working. But once it clicks, it's powerful.

— Reddit r/LocalLLaMA

A simple CLI with a lobster color palette. 'openclaw doctor' is great for diagnosing issues — it checks everything from Node.js version to API key validity.

— Reddit r/selfhosted

Frequently Asked Questions

How do I install the OpenClaw CLI?

Run 'npm install -g openclaw@latest' with Node.js 22+ installed. On macOS, you can also use 'brew install --cask openclaw' which installs both the CLI and the macOS app.

What's the difference between 'openclaw gateway start' and 'openclaw gateway run'?

'openclaw gateway start' manages the Gateway as a background service via launchd (macOS) or systemd (Linux). 'openclaw gateway run' starts the Gateway in the foreground of your current terminal — useful for debugging and seeing real-time logs.

How do I update OpenClaw?

Run 'openclaw update' or 'npm install -g openclaw@latest'. The CLI will update itself and restart the Gateway if it's running. Source installs use git pull instead.

Does the CLI work on Windows?

The CLI works on Windows via WSL2 (Windows Subsystem for Linux). Native Windows support is not officially supported — WSL2 provides the best experience with full Linux compatibility.

How do I manage multiple OpenClaw configurations?

Use the --profile flag: 'openclaw --profile work gateway start' creates an isolated setup under ~/.openclaw-work with its own config, data, and ports. Each profile runs independently.

What does 'openclaw doctor' check?

It verifies Node.js version compatibility, Gateway connectivity, API key validity, channel health, file permissions, port availability, and system dependencies. It's the comprehensive diagnostic tool for troubleshooting.

Can I use the CLI to send messages without a Gateway?

No — the 'openclaw message' command requires a running Gateway to route messages through configured channels. However, setup commands like 'openclaw configure' and 'openclaw gateway install' work without a running Gateway.

Installation

npm install -g openclaw@latest