OpenClaw is a personal AI assistant framework that bridges your chats across platforms (WhatsApp, Telegram, Discord, Web, etc.). Beyond the web dashboard, its real power lives in the terminal.
This guide covers the CLI commands you’ll actually use day-to-day.
1. Setup & Health Check
Before anything else, make sure your Gateway is alive:
# Check service status
openclaw gateway status
# Quick health probe
openclaw health
# Diagnose and auto-repair issues
openclaw doctor
# Tail logs
openclaw logs
If the Gateway isn’t running yet:
openclaw gateway start # Start as daemon
openclaw gateway run # Foreground (for debugging)
openclaw gateway restart # Restart
openclaw gateway stop # Stop
2. Opening a Chat Session
Interactive TUI (Terminal UI)
# Basic — connects to Gateway using default "main" session
openclaw chat
# Local embedded mode (no Gateway, needs API keys in env)
openclaw chat --local
# Specify a custom session key
openclaw chat --session mychat
# Set thinking level on open
openclaw chat --thinking high
# Auto-send a message on launch
openclaw chat --message "帮我分析一下这个项目"
One-shot Agent Turn (no TUI)
# Send a message and get the reply in terminal
openclaw agent --message "Summarize recent logs"
# Target a specific agent
openclaw agent --agent ops --message "Check system status"
# Send to a phone number (starts a new session)
openclaw agent --to +15555550123 --message "Hello"
# Deliver reply back to chat channel
openclaw agent --deliver --message "Report generated"
3. Choosing & Switching Models
Check current default
openclaw config get agents.defaults.model
# Output: { "primary": "deepseek/deepseek-v4-pro" }
Set a new default
openclaw config set agents.defaults.model "anthropic/claude-sonnet-4-20250514"
Override per run
openclaw agent --model openai/gpt-4o --message "..."
openclaw agent --model deepseek/deepseek-v4-pro --thinking high --message "..."
Interactive model setup
openclaw configure --section model
4. Browsing Session History
# List all sessions
openclaw sessions
# Latest 50 sessions
openclaw sessions --limit 50
# Only sessions active in the last 2 hours
openclaw sessions --active 120
# Filter by agent
openclaw sessions --agent work
# All agents combined
openclaw sessions --all-agents
# Machine-readable
openclaw sessions --json
5. Managing Devices
When you log in from a new device (phone, tablet, another laptop), a pairing request appears. You approve it from an already-authorized device.
# List pending and paired devices
openclaw devices list
# Approve a pending pairing request (use the request ID)
openclaw devices approve <request-id>
# Reject a request
openclaw devices reject <request-id>
# Revoke a device
openclaw devices revoke <device-id>
6. Managing Agents
An “agent” is an isolated persona with its own workspace, model, and routing.
# List all agents
openclaw agents list
# Add a new agent
openclaw agents add
# View routing bindings
openclaw agents bindings
# Delete an agent
openclaw agents delete <agent-id>
7. Managing Channels
Connect OpenClaw to messaging platforms:
openclaw channels
Supported channels include: Telegram, WhatsApp, Discord, Signal, Slack, iMessage, Matrix, LINE, WeChat (QQ Bot), Microsoft Teams, and many more.
8. Configuration Quick Reference
# Get a config value
openclaw config get gateway.port
# Set a config value
openclaw config set gateway.port 19001
# Remove a config value
openclaw config unset some.key
# Validate current config
openclaw config validate
# Print config file path
openclaw config file
# Interactive guided setup
openclaw configure
9. Background Jobs (Cron)
Schedule recurring or one-shot agent tasks:
openclaw cron list # List scheduled jobs
openclaw cron add # Create a new job
openclaw cron run <id> # Trigger a job immediately
openclaw cron remove <id> # Delete a job
10. Backup
openclaw backup
Creates a local backup archive of your OpenClaw state.
Real-world Workflow Example
A typical troubleshooting session might look like this:
# 1. Check if everything is healthy
openclaw health
# 2. See recent sessions
openclaw sessions --active 60
# 3. Approve your phone login
openclaw devices list
openclaw devices approve <id>
# 4. Open a chat with a specific model
openclaw chat --model deepseek/deepseek-v4-pro --thinking high
# 5. Later, check logs if something went wrong
openclaw logs
That covers the core CLI surface. For deep dives into any command, run openclaw <command> --help or check the official docs.