OpenClaw LaunchOpenClaw Launch
← Home

Guide

OpenClaw CLI

The OpenClaw CLI is the command-line entry point to every OpenClaw feature — starting the gateway, switching models, logging into channels, installing skills, and inspecting status. This guide walks through installation, the main command groups, and the examples you'll actually use day-to-day.

What Is the OpenClaw CLI?

OpenClaw ships as a Node.js application with a single executable: openclaw. When you run the Docker image, the container's entrypoint is really just calling the same CLI (node openclaw.mjs), so whether you are self-hosting on a VPS, running locally with Docker, or experimenting with npm install -g openclaw, the commands are identical.

The CLI is organized into subcommand groups — gateway, models, channels, skills, and config. Each group handles a piece of the runtime. You can think of it as git's structure: the top-level command is a dispatcher, and each subcommand does one job well.

Installing the CLI

Option 1: Global npm Install

If you have Node.js 20 or later installed, this is the fastest way:

npm install -g openclaw

Verify the install by running openclaw --help. You should see the subcommand list printed to your terminal.

Option 2: Docker

If you prefer Docker, you already have the CLI — it's baked into the image. Run any CLI command by exec-ing into a running container:

docker exec -it openclaw node openclaw.mjs models status

Or, for a one-off command without a persistent container:

docker run --rm -v ~/.openclaw:/home/node/.openclaw ghcr.io/openclaw/openclaw:main node openclaw.mjs models status

Option 3: OpenClaw Launch Managed Instance

If you deploy with OpenClaw Launch, the CLI still exists inside your container, but you don't usually need to touch it — the dashboard handles model switching, channel logins, and skill installs through the UI. When you do need CLI access for advanced tasks, open your instance detail page and use the built-in terminal, which runs commands inside the container for you.

The gateway Command

This is the command that starts OpenClaw. Everything else — bots, tools, memory, skills — runs inside the gateway process. By default the gateway listens on port 18789.

openclaw gateway

The most common flag is --allow-unconfigured, which tells the gateway to boot even if you haven't finished writing ~/.openclaw/openclaw.json yet. This is useful on a fresh install so you can reach the web UI and configure things from there:

openclaw gateway --allow-unconfigured

When the gateway is running, leave the terminal open (or run it under a process manager like PM2, systemd, or Docker). Every other CLI command in this guide assumes a gateway is live.

The models Command

The models group manages model providers — OpenAI, Anthropic, Google, OpenRouter, local Ollama, and so on. You can inspect status, log in with OAuth-backed providers, or switch the active model.

Check Status

openclaw models status

Prints the currently active model, the list of configured providers, and whether each one has valid credentials. Run this first whenever a bot stops responding — a missing API key is the most common cause.

Log Into a Provider

For providers that support OAuth (like the ChatGPT/Codex subscription), log in with:

openclaw models auth login --provider openai-codex

The CLI opens a browser tab for you to complete authentication and writes the token back to ~/.openclaw/credentials/.

Switch the Active Model

openclaw models set openai-codex/gpt-5.4

Model IDs must include the provider prefix — openrouter/anthropic/claude-sonnet-4.6, not anthropic/claude-sonnet-4.6. See the OpenRouter provider guide for the full list.

The channels Command

Channels are how users reach your bot — Telegram, Discord, WhatsApp, Slack, Zalo, WeChat, and more. The channels subcommand handles authentication for each one.

Log Into a Channel

openclaw channels login --channel zalouser

Replace zalouser with the channel you want: telegram, discord, whatsapp, etc. The CLI walks you through the per-channel auth flow — QR scan, token paste, or OAuth redirect depending on the platform.

Check Session Status

openclaw channels status --probe

The --probe flag makes a live call to the channel's API so you're not reading cached status. Essential for diagnosing bot-not-responding issues.

Log Out and Back In

Sometimes the cleanest fix for a broken channel session is a logout + login cycle:

openclaw channels logout --channel zalouser && openclaw channels login --channel zalouser

The skills and plugins Commands

Skills are packaged capabilities — browser automation, Tavily search, MCP servers, memory consolidation. Install them the same way you install npm packages:

openclaw skills install browser-automation

See the skills install guide for the canonical list of recommended skills and how to publish your own to ClawHub.

The config Command

OpenClaw stores its config at ~/.openclaw/openclaw.json. You can edit that file directly, but the CLI also exposes helpers for safe edits:

openclaw config show

Prints the resolved config (with secrets redacted). This is the fastest way to answer the question “is my change actually loaded?” when a setting doesn't seem to be taking effect.

Common CLI Recipes

First-Run Setup

openclaw gateway --allow-unconfigured &
openclaw models auth login --provider openrouter
openclaw models set openrouter/anthropic/claude-sonnet-4.6
openclaw channels login --channel telegram

Rotate an API Key

openclaw models auth logout --provider openrouter
openclaw models auth login --provider openrouter
openclaw models status

Debug a Silent Bot

openclaw models status
openclaw channels status --probe
openclaw config show

CLI vs Web UI vs Config File

OpenClaw gives you three ways to manage the same state. Pick the one that fits your workflow:

  • CLI: best for scripts, CI/CD, SSH sessions, and one-off automation. Works over SSH on headless servers.
  • Web UI (gateway control panel): best for exploration, debugging, and manual use. Shows live logs and session state.
  • openclaw.json config file: best for infrastructure-as-code setups. Commit it to git, diff it, replicate across environments.

Frequently Asked Questions

Do I need the CLI if I use OpenClaw Launch?

Not for normal use. OpenClaw Launch exposes every common action — model switching, channel setup, skill install — through the dashboard. The CLI is there for advanced cases like scripted provisioning, one-off debugging, or rotating credentials without opening a browser.

Can I run CLI commands over SSH?

Yes. The CLI is headless by default. The only commands that need a browser are OAuth logins (models auth login) — the CLI will print a URL you can open locally and paste the token back.

Why does my CLI command say “gateway not reachable”?

Most CLI commands talk to a running gateway on localhost:18789. If you see this error, the gateway process isn't running — start it with openclaw gateway in another terminal first. See gateway stuck-on-starting fixes if it still won't come up.

Where are my credentials stored?

In ~/.openclaw/credentials/. This directory must exist for channel pairing to work — Telegram in particular will silently drop messages if it's missing. On Docker, mount ~/.openclaw as a volume so credentials survive container restarts.

Is there a Windows version of the CLI?

Yes. Install with npm install -g openclaw from PowerShell or use WSL2. See the Windows install guide for the full walk-through including Docker Desktop setup.

Related Guides

Skip the CLI Entirely

OpenClaw Launch runs every command for you — deploy a managed instance in 10 seconds and manage it from the dashboard. No terminals, no SSH, no config files.

Deploy with OpenClaw Launch