CLI Reference

You'll use the CLI for setup, starting the Gateway, sending test messages, and debugging. Everything runs through openclaw; moltbot and clawdbot still work as aliases. This page is a quick reference—the commands I reach for most are onboard, gateway, doctor, and restart.

"command not found" after install: Restart your terminal so PATH picks up the global npm bin. If you installed with pnpm or in a venv, make sure that environment is active.

gateway start hangs or port in use: Another process may be using 18789. Run openclaw doctor to see port and process checks. Use --port to pick a different port if you need to.

Token or 1008 unauthorized: If the Control UI or a client reports "gateway token missing" or 1008, you need to pass the token (e.g. openclaw gateway --token YOUR_TOKEN) or open a tokenized dashboard URL. See Troubleshooting for details.

onboard

Run the onboarding wizard to set up OpenClaw:

openclaw onboard [--install-daemon]

• --install-daemon - Install Gateway as system service (systemd on Linux, launchd on macOS)

Documentation: The --install-daemon flag installs OpenClaw Gateway as a background service that starts automatically on system boot. This is recommended for production deployments.

Example: openclaw onboard --install-daemon will guide you through initial setup and install the Gateway as a system service.

gateway

Start the Gateway:

openclaw gateway [--port PORT] [--bind ADDRESS] [--verbose] [--token TOKEN]

• --port - Gateway port (default: 18789)
• --bind - Bind address (default: 127.0.0.1)
• --verbose - Verbose logging
• --token - Authentication token

agent

Send a message to the agent:

openclaw agent --message "your message" [--thinking LEVEL]

• --message - Message to send
• --thinking - Thinking level (low, medium, high)

Delivery (2026.2.21): openclaw agent --deliver can send without --reply-to when a per-account or per-channel defaultTo is configured for outbound routing.

channels login

Link a channel device (shows QR for WhatsApp):

openclaw channels login [channel]

channels list

List configured channels:

openclaw channels list

pairing list / pairing approve

List pending pairing requests and approve new devices or DM contacts: openclaw pairing list, openclaw pairing approve <channel> <code>. From 2026.2.21, both commands default to the sole available pairing channel when omitted, so TUI-only setups can recover from "pairing required" without guessing channel arguments.

message send

Send a message via a channel:

openclaw message send --target +1234567890 --message "Hello"

sessions list

List active sessions:

openclaw sessions list

sessions history

View session conversation history:

openclaw sessions history [session-id]

Sending to a session from the CLI: To send a message to a specific session (e.g. a sub-agent or group session), use the agent command with --to and the session key. Spawning new sub-agents is done by your OpenClaw agent via the sessions_spawn tool, not by a CLI command.

openclaw agent --message "Your task or question" --to "agent:main:subagent:abc123"

Use openclaw sessions list (or openclaw sessions --json) to get session keys. Add --deliver to have the reply delivered to a configured channel. See Set up a sub-agent for the full flow.

configure

Interactive configuration:

openclaw configure

doctor

Check configuration and diagnose issues:

openclaw doctor [--fix]

• --fix - Automatically fix common issues found during diagnosis

Example: openclaw doctor --fix will check your configuration and automatically fix issues like permission problems, missing directories, and configuration errors.

gateway restart

Restart the Gateway service:

openclaw gateway restart

This command stops the current Gateway instance and starts it again. Useful when you need to reload configuration or recover from errors.

gateway status

Check Gateway status and connection:

openclaw gateway status

Shows whether the Gateway is running, the port it's listening on, and connection status.

gateway logs

View Gateway logs:

openclaw gateway logs

Displays recent Gateway log entries for debugging.

devices (2026.2.19+)

Manage paired devices: remove a device or clear pairing state.

openclaw devices remove [device]
openclaw devices clear --yes [--pending]

• devices remove – Remove a specific paired device
• devices clear --yes – Clear all paired entries; add --pending to also reject pending pairing requests

Config also supports device.pair.remove for paired-device hygiene. See Troubleshooting for pairing-related issues.

skills list

List all installed skills:

openclaw skills list

Shows all skills installed in your workspace (~/clawd/skills/).

status

Check Gateway status:

openclaw status

health

Check system health:

openclaw health

update

Update OpenClaw:

openclaw update [--channel CHANNEL]

• --channel - Release channel (stable, beta, dev)

restart

Restart OpenClaw Gateway (convenience command):

openclaw restart

Shortcut for openclaw gateway restart. Stops and restarts the Gateway service.

pairing approve

Approve a pairing request:

openclaw pairing approve <channel> <code>

skills list

List installed skills:

openclaw skills list

Get help for any command:

openclaw --help
openclaw <command> --help