OpenClaw Startup Parameters and Command-Line Options Reference

Introduction

The openclaw command-line tool is the primary interface for managing the AI gateway. Beyond configuration files, many behaviors can be temporarily overridden or adjusted through startup parameters. This article provides a complete listing of all openclaw subcommands and their options to help you use them flexibly across different scenarios.

Global Options

The following options apply to all subcommands:

openclaw [global options] <subcommand> [subcommand options]

Examples

# Start with a custom config file
openclaw -c /etc/openclaw/production.json gateway

# Run in debug mode
openclaw -v gateway

# Check version
openclaw --version

gateway Command

gateway is the core command for starting the AI gateway service.

openclaw gateway [options]

Common Usage

# Default start
openclaw gateway

# Specify port and address
openclaw gateway --port 8080 --host 0.0.0.0

# Run in background
openclaw gateway --daemon

# Enable only Telegram and Discord channels
openclaw gateway --channels telegram,discord

# Validate configuration without starting (dry run)
openclaw gateway --dry-run

Daemon Management

After starting in --daemon mode, you can manage it with these commands:

# Check running status
openclaw status

# Graceful stop
openclaw stop

# Force stop
openclaw stop --force

# Restart
openclaw restart

# Hot reload configuration (without interrupting connections)
openclaw reload

dashboard Command

Start the Web Dashboard independently without starting the gateway service.

openclaw dashboard [options]

Examples

# Start and open browser
openclaw dashboard --open

# Connect to a remote gateway
openclaw dashboard --gateway https://remote-server:18789

# Use a custom port
openclaw dashboard --port 3000

doctor Command

A diagnostic tool that checks configuration, dependencies, and connection status.

openclaw doctor [options]

Output Example

$ openclaw doctor

OpenClaw Diagnostic Report
==================

Configuration File
  ✓ Configuration file format is valid
  ✓ All required fields are set

Model Connections
  ✓ Claude API connection OK (latency: 230ms)
  ✓ OpenAI API connection OK (latency: 180ms)
  ✗ Ollama connection failed: ECONNREFUSED localhost:11434

Channel Status
  ✓ Telegram Bot authenticated
  ✓ Discord Bot logged in
  - WhatsApp not configured

System Environment
  ✓ Node.js v20.11.0
  ✓ Sufficient disk space (available: 50GB)
  ✓ Sufficient memory (available: 4.2GB)

Issues: 1
  1. Ollama service is not running. Please start Ollama or disable its model configuration

session Command

Manage conversation session data.

openclaw session <subcommand> [options]

Common Operations

# List all active sessions
openclaw session list

# Filter by Agent
openclaw session list --agent default

# View detailed statistics for a session
openclaw session stats --session telegram_123456

# Clear a specific session
openclaw session clear --session telegram_123456

# Clear all sessions for an Agent
openclaw session clear --agent default --all

# Export session as JSON
openclaw session export --session telegram_123456 --format json

# Manual compaction
openclaw session compact --session telegram_123456

# Keep only the last 20 messages
openclaw session trim --session telegram_123456 --keep 20

mobile Command

Manage mobile device pairing.

openclaw mobile <subcommand> [options]

Examples

# Generate a text pairing code
openclaw mobile pair --generate

# Generate a QR code
openclaw mobile pair --qrcode

# List devices
openclaw mobile list

# Remove a specific device
openclaw mobile remove mob_a3f2c1d8

# Remove all devices
openclaw mobile remove --all

config Command

View and manage configuration.

openclaw config <subcommand> [options]

Examples

# View full configuration
openclaw config --dump

# Get a specific config value
openclaw config --get gateway.port

# Set a config value
openclaw config --set gateway.port 8080

# Initialize default configuration
openclaw config --init

# Open in editor
openclaw config --edit

access Command

Manage access control and permissions.

openclaw access <subcommand> [options]

Examples

# Add user to allowlist
openclaw access allow tg:123456789

# Block a user
openclaw access deny tg:999888777

# View the allowlist
openclaw access list

# View access logs
openclaw access log --tail 50

media Command

Manage media file cache.

openclaw media <subcommand>

Environment Variables

Some startup parameters can also be set via environment variables. Environment variables take priority over configuration files but are overridden by command-line arguments:

Priority order (highest to lowest): Command-line arguments > Environment variables > Configuration file > Default values.

systemd Service Configuration

On Linux servers, using systemd to manage OpenClaw is recommended:

# /etc/systemd/system/openclaw.service
[Unit]
Description=OpenClaw AI Gateway
After=network.target

[Service]
Type=simple
User=openclaw
WorkingDirectory=/home/openclaw
ExecStart=/usr/local/bin/openclaw gateway --port 18789 --host 0.0.0.0
ExecReload=/usr/local/bin/openclaw reload
Restart=always
RestartSec=5
Environment=OPENCLAW_CONFIG=/etc/openclaw/openclaw.json

[Install]
WantedBy=multi-user.target

sudo systemctl enable openclaw
sudo systemctl start openclaw
sudo systemctl status openclaw

Summary

The openclaw command-line tool provides a complete feature set from starting the gateway to managing sessions, from diagnosing issues to configuring permissions. In daily use, gateway, doctor, and session are the three most commonly used commands. Remember that command-line arguments take priority over configuration files — this means you can temporarily adjust gateway behavior through parameters without modifying the configuration file, which is ideal for debugging and testing.