Beginner-friendly reference

OpenClaw Commands Reference

Read what each OpenClaw command does before you copy it. This page is written for beginners and clearly marks riskier actions.

You do not need a deep terminal background to use this page.
Read the explanation first, then decide whether the command matches your setup.
Commands that can interrupt services or change system state are marked clearly.

Where should I start?

1If you have not installed OpenClaw yet, start with install commands first.
2After setup works, learn the restart and log commands you will use most often.
3Only move to Docker, VPS, or backup commands when they match your deployment style.

Jump to a section

Install and first run Update and restart Logs and troubleshooting Docker and VPS Backup and restore

install

Install and first run

Safe

Check whether Node.js is installed

Shows the Node.js version on this computer before you install or update OpenClaw.

node -v

Install and first runMacLinuxWindows

What it does: Shows the Node.js version on this computer before you install or update OpenClaw.
When to use it: Use it first when the install guide asks for Node.js, or when you are not sure whether this machine already has Node installed.
What happens next: The terminal prints a version like `v20.x`. If Node is missing, the shell tells you the command cannot be found.
Risk note: Safe. It only reads local tool information and does not change anything.

Getting Started Windows Install

Open detail page

Safe

Check whether npm is ready

Shows the npm version so you know the package manager required by OpenClaw is available.

npm -v

Install and first runMacLinuxWindows

What it does: Shows the npm version so you know the package manager required by OpenClaw is available.
When to use it: Use it before the global install step or when npm commands fail and you want to confirm the tool is present.
What happens next: The terminal prints the npm version number. If npm is unavailable, you get an error instead of a version.
Risk note: Safe. It only checks the installed package manager and changes nothing.

Getting Started Windows Install

Open detail page

Caution

Remove old global package names before a clean install

Uninstalls older OpenClaw package names so they do not conflict with the current CLI.

npm uninstall -g clawdbot || true
npm uninstall -g moltbot || true
npm uninstall -g openclaw || true

Install and first runMacLinux

What it does: Uninstalls older OpenClaw package names so they do not conflict with the current CLI.
When to use it: Use it when reinstalling OpenClaw, when command names look mixed up, or when a guide tells you to clean older package aliases first.
What happens next: npm tries to remove each global package. Missing packages are ignored because of `|| true`.
Risk note: Caution. It removes global CLI packages from this machine, so only run it if you are intentionally cleaning an old setup.

Getting Started Windows Install

Open detail page

Caution

Install the latest OpenClaw CLI globally

Downloads the newest supported OpenClaw command-line tool and makes it available system-wide.

npm i -g openclaw@latest

Install and first runMacLinuxWindows

What it does: Downloads the newest supported OpenClaw command-line tool and makes it available system-wide.
When to use it: Use it during first-time setup, after cleaning an old install, or when a guide tells you to update the local CLI.
What happens next: npm installs or updates the global `openclaw` package. After it finishes, the `openclaw` command should be available in your terminal.
Risk note: Caution. It changes the global CLI on this machine, so do not run it on a Docker or VPS deployment that uses a different update path.

Getting Started Windows Install

Open detail page

Safe

Confirm that OpenClaw installed correctly

Prints the current OpenClaw CLI version so you can verify the command is available.

openclaw --version

Install and first runMacLinuxWindows

What it does: Prints the current OpenClaw CLI version so you can verify the command is available.
When to use it: Use it right after installation or update, or when the terminal says OpenClaw is missing and you want a quick confirmation.
What happens next: The terminal shows the installed version number. If the command still is not on your PATH, you get an error instead.
Risk note: Safe. It only reads version information and does not modify any files or services.

Getting Started Windows Install

Open detail page

Caution

Start the beginner onboarding flow

Opens OpenClaw's quickstart onboarding so you can finish the first setup steps.

openclaw onboard --flow quickstart

Install and first runMacLinuxWindows

What it does: Opens OpenClaw's quickstart onboarding so you can finish the first setup steps.
When to use it: Use it after the CLI is installed and you are ready to connect the first workspace, account, or local runtime settings.
What happens next: OpenClaw launches an onboarding flow and guides you through the next required setup prompts.
Risk note: Caution. It creates or updates your local OpenClaw setup state, so run it only when you are ready to configure this machine.

Getting Started Windows Install

Open detail page

update

Update and restart

Caution

Restart the OpenClaw gateway normally

Restarts the gateway service so new settings or channel changes take effect.

openclaw gateway restart

Update and restartMacLinuxWindowsVPS

What it does: Restarts the gateway service so new settings or channel changes take effect.
When to use it: Use it after changing channel config, tokens, proxies, or local settings that require the gateway to reload.
What happens next: The gateway process stops and starts again. Existing in-memory sessions may reconnect during the restart.
Risk note: Caution. It briefly interrupts the gateway, so avoid running it in the middle of a live operation unless you expect a short restart window.

Getting Started Telegram WhatsApp Feishu / Lark Docker / VPS Deployment

Open detail page

Caution

Restart OpenClaw with an older-version fallback

Tries the newer gateway restart command first and falls back to the older restart command if needed.

openclaw gateway restart || openclaw restart

Update and restartMacLinuxVPS

What it does: Tries the newer gateway restart command first and falls back to the older restart command if needed.
When to use it: Use it when a guide must support multiple OpenClaw versions or when you are not sure which restart subcommand your current CLI supports.
What happens next: The shell runs `openclaw gateway restart` first. If that command fails, it immediately tries `openclaw restart` instead.
Risk note: Caution. It still restarts the service, and the `||` syntax is shell-oriented, so it is best used in macOS, Linux, or VPS environments.

Getting Started Advanced Configuration Docker / VPS Deployment

Open detail page

Caution

Update the local CLI and restart right away

Installs the latest OpenClaw CLI and then reloads the gateway so the newer version starts running.

npm i -g openclaw@latest
openclaw gateway restart || openclaw restart

Update and restartMacLinux

What it does: Installs the latest OpenClaw CLI and then reloads the gateway so the newer version starts running.
When to use it: Use it when a local install needs an update and you want the new CLI to take effect immediately after installation.
What happens next: npm updates the global package first, then OpenClaw restarts the gateway using the compatible fallback pattern.
Risk note: Caution. It both changes the installed version and restarts the service, so do not run it on Docker or VPS flows that use different upgrade steps.

Getting Started Advanced Configuration

Open detail page

Caution

Restart the gateway and print extra details

Restarts the gateway in a more talkative mode so you can see more startup information.

openclaw gateway restart --verbose

Update and restartMacLinuxWindowsVPS

What it does: Restarts the gateway in a more talkative mode so you can see more startup information.
When to use it: Use it when a normal restart is not enough and you need to watch whether OpenClaw actually loads a config, plugin, or channel change.
What happens next: The gateway restarts and prints more startup messages in the terminal than a normal restart.
Risk note: Caution. It still restarts the gateway, and the extra output can expose more local diagnostic details on screen.

Advanced Configuration Troubleshooting

Open detail page

Advanced

Use the older verbose restart command

Restarts OpenClaw with verbose output using the older top-level restart syntax.

openclaw restart --verbose

Update and restartMacLinuxVPS

What it does: Restarts OpenClaw with verbose output using the older top-level restart syntax.
When to use it: Use it only when documentation or your current OpenClaw version still expects the legacy `openclaw restart` command.
What happens next: OpenClaw restarts and prints detailed diagnostic output while it comes back online.
Risk note: Advanced. This is mainly for version compatibility and troubleshooting. Newer users should prefer the explicit gateway restart command when it works.

Advanced Configuration Troubleshooting

Open detail page

logs

Logs and troubleshooting

Safe

Read the latest 100 OpenClaw log lines

Shows only the most recent log output so you can inspect errors without scrolling through older noise.

openclaw logs | tail -n 100

Logs and troubleshootingMacLinuxVPS

What it does: Shows only the most recent log output so you can inspect errors without scrolling through older noise.
When to use it: Use it when OpenClaw starts failing, after a restart, or after a plugin or config change when you want a short, recent log snapshot.
What happens next: The terminal prints the newest 100 lines from `openclaw logs` and then exits.
Risk note: Safe. It is read-only, but logs may contain local paths or other diagnostic details visible on screen.

Advanced Configuration Troubleshooting

Open detail page

Safe

Search logs for Feishu webhook activity

Filters OpenClaw logs to lines that mention Feishu, webhook callbacks, or related event handling.

openclaw logs | grep -i -E "feishu|webhook|event|callback" || true

Logs and troubleshootingMacLinuxVPS

What it does: Filters OpenClaw logs to lines that mention Feishu, webhook callbacks, or related event handling.
When to use it: Use it when Feishu messages are not arriving, webhook verification fails, or you want proof that the callback reached OpenClaw.
What happens next: The terminal prints only the matching log lines. If nothing matches, `|| true` keeps the command from being treated as a failure.
Risk note: Safe. It does not change system state, but the filtered output may still include request details that you should not screenshot casually.

Feishu Webhook Tunneling Feishu / Lark Troubleshooting

Open detail page

Safe

Follow live gateway logs in Docker

Streams the gateway container logs in real time so you can watch what happens after a change or restart.

docker compose logs -f openclaw-gateway

Logs and troubleshootingDockerVPS

What it does: Streams the gateway container logs in real time so you can watch what happens after a change or restart.
When to use it: Use it on Docker or VPS deployments when you need to see fresh runtime events, startup errors, or reconnect behavior as it happens.
What happens next: The terminal stays attached and keeps printing new log lines until you stop it manually.
Risk note: Safe. It is read-only, but it keeps the terminal busy until you press Ctrl+C and may expose runtime details on screen.

Docker / VPS Deployment Troubleshooting

Open detail page

docker

Docker and VPS

Advanced

Install Docker and verify the tools

Installs Docker Engine and Docker Compose on Ubuntu, then prints the versions to confirm the tools are ready.

sudo apt install -y docker.io docker-compose
docker --version
docker-compose --version

Docker and VPSDockerVPS

What it does: Installs Docker Engine and Docker Compose on Ubuntu, then prints the versions to confirm the tools are ready.
When to use it: Use it during a fresh VPS setup before any Docker-based OpenClaw deployment steps.
What happens next: Ubuntu installs the Docker packages with sudo, then the terminal prints Docker and Compose version numbers if installation succeeded.
Risk note: Advanced. It changes system packages and requires administrator privileges, so only run it on a machine you intend to prepare for Docker workloads.

Docker / VPS Deployment

Open detail page

Advanced

Add your user to the Docker group

Updates Linux permissions so your current account can run Docker without typing sudo every time.

sudo usermod -aG docker $USER

Docker and VPSDockerVPS

What it does: Updates Linux permissions so your current account can run Docker without typing sudo every time.
When to use it: Use it when Docker commands fail with permission errors or when the VPS guide tells you to fix Docker access for your user account.
What happens next: Linux appends your current user to the `docker` group. You usually need to log out and back in before the change fully takes effect.
Risk note: Advanced. This changes account permissions on the machine. Only do it if you understand who should be allowed to control Docker on this server.

Docker / VPS Deployment Troubleshooting

Open detail page

Advanced

Make the Docker setup script executable and run it

Prepares the official setup script and then runs it to build the Docker-based OpenClaw environment.

chmod +x ./docker-setup.sh
./docker-setup.sh

Docker and VPSDockerVPS

What it does: Prepares the official setup script and then runs it to build the Docker-based OpenClaw environment.
When to use it: Use it after downloading the official `docker-setup.sh` file and after Docker itself is already installed.
What happens next: The first line grants execute permission to the script. The second line runs the script, which can create containers, files, and persistent directories.
Risk note: Advanced. You are executing a shell script that changes the server state. Read the script first if you do not fully trust what it will create.

Before you run it

Docker and Docker Compose are already installed.
You are in the directory that contains `docker-setup.sh`.

Docker / VPS Deployment

Open detail page

Caution

Run onboarding inside the CLI container

Starts the OpenClaw quickstart onboarding from the Docker CLI container instead of from the host machine.

docker compose exec openclaw-cli openclaw onboard --flow quickstart

Docker and VPSDockerVPS

What it does: Starts the OpenClaw quickstart onboarding from the Docker CLI container instead of from the host machine.
When to use it: Use it after the Docker environment is already up and you want to finish first-time setup in the containerized workflow.
What happens next: Docker opens a shell process inside `openclaw-cli` and runs the onboarding command there, so configuration is written to the Docker-managed environment.
Risk note: Caution. It changes the OpenClaw state inside your Docker setup, so make sure you are working in the correct project directory and container stack.

Docker / VPS Deployment Getting Started

Open detail page

Caution

Restart the Docker OpenClaw services

Restarts both the gateway and CLI containers in the current Docker stack.

docker compose restart openclaw-gateway openclaw-cli

Docker and VPSDockerVPS

What it does: Restarts both the gateway and CLI containers in the current Docker stack.
When to use it: Use it after changing environment variables, mounted config, or other container-level settings that require the containers to restart.
What happens next: Docker stops and starts the specified containers again. There is a short service interruption while they come back.
Risk note: Caution. It interrupts the running containers, so do not run it during a sensitive live session unless a restart is expected.

Docker / VPS Deployment Troubleshooting

Open detail page

Caution

Stop the current Docker OpenClaw stack

Stops the running OpenClaw containers in this Docker Compose project without removing them.

docker compose stop

Docker and VPSDockerVPS

What it does: Stops the running OpenClaw containers in this Docker Compose project without removing them.
When to use it: Use it when you need a clean maintenance window, want to stop background processing temporarily, or must inspect the host without active OpenClaw containers running.
What happens next: The Compose services stop and stay stopped until you start them again manually.
Risk note: Caution. This takes OpenClaw offline for the current stack, so use it only when you intentionally want the service to stop.

Docker / VPS Deployment Troubleshooting

Open detail page

backup

Backup and restore

Safe

Create a quick backup of the OpenClaw home directory

Compresses the `~/.openclaw` directory into a `.tar.gz` archive you can copy elsewhere.

tar -czf openclaw-backup.tar.gz ~/.openclaw

Backup and restoreLinuxVPS

What it does: Compresses the `~/.openclaw` directory into a `.tar.gz` archive you can copy elsewhere.
When to use it: Use it before risky config changes, before moving to a new server, or whenever you want a simple snapshot of your current OpenClaw state.
What happens next: The terminal creates `openclaw-backup.tar.gz` in your current directory. Your original `~/.openclaw` data stays in place.
Risk note: Safe. It does not delete source data, but the backup file may contain sensitive local state, so store it carefully.

Docker / VPS Deployment Troubleshooting

Open detail page