OpenClaw Commands and Troubleshooting: The Complete Reference

You set up OpenClaw. It worked great for two days. Then you woke up one morning and it wasn't responding. Or maybe it's responding in DMs but ignoring your group chat. Or the cron jobs stopped firing. Or you ran an update and now nothing works.

Welcome to the troubleshooting phase. Every tool has one. The difference between people who abandon their setup and people who run it for months is knowing which command to type when something breaks.

This guide covers every essential OpenClaw CLI command, organized by what you're actually trying to do. Bookmark it. You'll need it.

The Five Commands You'll Use Most

Before we get into the full reference, these five commands solve about 80% of all OpenClaw issues. When something goes wrong, run them in this order:

openclaw status
openclaw gateway status
openclaw logs --follow
openclaw doctor
openclaw doctor --fix

That sequence checks your channels, verifies the gateway is running, shows you live logs, runs a health check, and attempts automatic repairs. Most of the time, one of those five will either tell you exactly what's wrong or fix it outright.

Gateway Commands

The gateway is the core of OpenClaw. It handles message routing, model calls, session management, and basically everything that makes your agent work. If the gateway isn't running, nothing is running.

Start, Stop, and Restart

# Check if the gateway is running
openclaw gateway status

# Start the gateway
openclaw gateway start

# Stop it
openclaw gateway stop

# Restart (the universal fix)
openclaw gateway restart

# Force start (kills anything on the port first)
openclaw gateway start --force

The restart command is the most underrated tool in the entire CLI. If something feels off and you can't figure out why, restart the gateway. It clears stale sessions, reconnects channels, and reloads config. About 40% of "mysterious" issues are just stale state that a restart clears.

Viewing Logs

# Follow live logs (watch in real-time)
openclaw logs --follow

# Show recent logs (last 200 lines)
openclaw logs

# Show logs in plain text (no colors, good for piping)
openclaw logs --plain

# JSON output for scripting
openclaw logs --json

The --follow flag is your best friend when debugging. Start it in one terminal window, then trigger the action that's failing in another. The logs will show you exactly where things break.

Gateway Configuration

# Open the interactive config wizard
openclaw config

# Get a specific config value
openclaw config get channels.telegram.botToken

# Set a value
openclaw config set gateway.bind loopback

# Remove a value
openclaw config unset channels.slack

The config wizard (openclaw config with no arguments) walks you through setup interactively. It's the safest way to make changes if you're not sure about the JSON structure.

Channel Commands

Channels are how OpenClaw talks to the world. Telegram, Discord, Slack, WhatsApp, Signal, Google Chat. When your agent stops responding, the channel layer is usually the first place to check.

Checking Channel Health

# List all configured channels
openclaw channels list

# Deep probe (actually tests connections)
openclaw channels status --probe

# Show provider capabilities
openclaw channels capabilities telegram

# View channel-specific logs
openclaw channels logs

The --probe flag is important. Without it, channels list just shows what's configured. With --probe, it actually pings each service and tells you if the connection is alive.

Adding and Managing Channels

# Add a new channel interactively
openclaw channels add

# Add Telegram specifically
openclaw channels add telegram

# Login to a channel
openclaw channels login whatsapp

# Log out
openclaw channels logout whatsapp

# Remove a channel
openclaw channels remove discord

Pairing (DM Access Control)

OpenClaw uses pairing to control who can message the bot in DMs. This is a security feature, not a bug.

# List paired users
openclaw pairing list telegram

# Approve a pending pairing request
openclaw pairing approve telegram <userId>

# Reject a request
openclaw pairing reject telegram <userId>

If someone messages your bot and doesn't get a response, check if they have a pending pairing request. This catches new users about 50% of the time.

Resolving Names to IDs

# Find a Telegram user/group ID
openclaw channels resolve telegram "Galactic Chat"

# Find a Discord channel ID
openclaw channels resolve discord "general"

Useful when you need chat IDs for config (group allowlists, delivery targets).

Diagnostics

The Doctor

The doctor command is OpenClaw's built-in health check. It inspects your config, checks service status, verifies channel connections, and can automatically fix common problems.

# Run basic health check
openclaw doctor

# Run with auto-fix
openclaw doctor --fix

# Deep scan (checks for duplicate installs)
openclaw doctor --deep

# Force aggressive repairs
openclaw doctor --force

# Non-interactive mode (for scripts/cron)
openclaw doctor --non-interactive

When you run doctor --fix, it creates a backup of your config at ~/.openclaw/openclaw.json.bak before making changes. If the fix makes things worse (rare but possible), you can restore from that backup.

Full Status Dump

# Quick status
openclaw status

# Full diagnosis (pasteable for support)
openclaw status --all

# Deep probe all channels
openclaw status --deep

# Check model usage/quotas
openclaw status --usage

# Machine-readable output
openclaw status --json

The --all flag generates a comprehensive dump that's perfect for sharing in Discord or GitHub issues if you need help. It includes versions, config summaries, channel states, and session info.

Session Management

Sessions are individual conversations. Each DM user, each group, each topic thread gets its own session.

# List all sessions
openclaw sessions

# List recently active sessions only
openclaw sessions --active 60

# JSON output
openclaw sessions --json

This is useful for checking whether your agent is actually receiving messages. If a session exists for a chat but the last update was hours ago, the agent received messages but might have replied with NO_REPLY (normal for heartbeats and system events).

Cron and Scheduling

Cron jobs are how you schedule recurring tasks: daily reports, periodic checks, heartbeats, content publishing.

# Check if cron scheduler is running
openclaw cron status

# List all cron jobs
openclaw cron list

# Add a new job
openclaw cron add

# Run a job immediately (for testing)
openclaw cron run <jobId>

# View run history for a job
openclaw cron runs --id <jobId> --limit 20

# Enable/disable a job
openclaw cron enable <jobId>
openclaw cron disable <jobId>

# Edit a job
openclaw cron edit <jobId>

# Delete a job
openclaw cron rm <jobId>

Skills Management

Skills extend what your agent can do. They're packaged instructions with optional scripts and reference files.

# List all available skills
openclaw skills list

# Check which skills are ready vs. missing requirements
openclaw skills check

# Get details about a specific skill
openclaw skills info <skillName>

Memory and Search

OpenClaw's memory system lets the agent persist knowledge across sessions using markdown files.

# Check memory index status
openclaw memory status

# Reindex memory files (after manual edits)
openclaw memory index

# Search memory
openclaw memory search "project deadline"

If your agent seems to have "forgotten" something you wrote in MEMORY.md, try reindexing. The search index can get stale after manual file edits.

Browser Control

OpenClaw can control a dedicated Chrome browser for web automation, screenshots, and research.

# Start the browser
openclaw browser start

# Stop it
openclaw browser stop

# List open tabs
openclaw browser tabs

# Take a screenshot
openclaw browser screenshot

# Open a URL
openclaw browser open "https://example.com"

Node Management

Nodes are remote devices (phones, other computers) that OpenClaw can control.

# List connected nodes
openclaw nodes status

# Describe a specific node
openclaw nodes describe --node <name>

# Check pending pairing requests
openclaw nodes pending

Updates

# Check for updates
openclaw update check

# Update to latest stable
openclaw update

# Update without restarting gateway
openclaw update --no-restart

# Update to a specific version
openclaw update --tag 2026.2.15

# Skip confirmation prompts
openclaw update --yes

Security and Health Monitoring

Your agent runs on your hardware, which means security is your responsibility. These commands help you stay on top of it.

Security Audit

# Run a full security health check
openclaw doctor --deep

# Generate a gateway authentication token (if you don't have one)
openclaw doctor --generate-gateway-token

# Auto-fix security issues it finds
openclaw doctor --fix

# Aggressive repair (overwrites custom service configs)
openclaw doctor --force

The --deep flag scans your system for rogue gateway installs, checks file permissions on credential files, verifies your gateway token is set, and flags anything that looks misconfigured. Run it after any major change to your setup.

Live Health Check

# Quick health ping on the running gateway
openclaw health

# Detailed JSON output (good for monitoring scripts)
openclaw health --json

# Health check with custom timeout
openclaw health --timeout 5000

This hits the running gateway and returns real-time status. If it times out, your gateway is either down or unreachable. Useful for automated monitoring: pipe openclaw health --json into a cron job that alerts you when something breaks.

System Events and Heartbeats

# Send a system event to the agent
openclaw system event "Check the server logs"

# Trigger a heartbeat manually
openclaw system heartbeat

# View active presence entries
openclaw system presence

System events inject messages into the agent's session as if the system sent them. Heartbeats trigger the agent's background check-in loop. If your agent seems idle, a manual heartbeat will wake it up.

Agent Management

If you're running multiple agents (or planning to), these commands manage isolated agent workspaces.

# List all configured agents
openclaw agents list

# Add a new isolated agent
openclaw agents add

# Delete an agent and clean up its workspace
openclaw agents delete <agent-id>

# Update an agent's identity (name, emoji, avatar)
openclaw agents set-identity <agent-id>

Each agent gets its own workspace, config, and routing rules. This is how you scale from one agent to a full team without them stepping on each other.

Dashboard

# Open the Control UI in your browser
openclaw dashboard

# Print the URL without launching a browser
openclaw dashboard --no-open

The dashboard gives you a visual overview of your agent's status, sessions, and channels. The --no-open flag is useful when you're running headless (like on a Mac Mini you SSH into) and want to copy the URL to another device.

Common Issues and Fixes

"Agent not responding in group chats"

This is the single most common issue. The usual causes:

1. Bot privacy mode is ON (Telegram). Bots with privacy mode enabled only receive messages when directly @mentioned or when they're admins. Fix: Message @BotFather, go to Bot Settings, Group Privacy, set to Disabled. Then remove and re-add the bot to the group.

2. Mention required policy. Check your config:

openclaw config get channels.telegram.groups

If requireMention is true, the agent only responds when @mentioned.

3. Group not in allowlist.

openclaw config get channels.telegram.groups.allowlist

If an allowlist exists and your group ID isn't in it, messages get silently dropped.

"Bot not responding in DMs"

# Check pairing policy
openclaw config get channels.telegram.dm

# List pending pairings
openclaw pairing list telegram

If the DM policy is "pairing" (the default), new users must be approved before the agent responds to them.

"Gateway won't start"

# Check what's using the port
openclaw gateway status --deep

# Force kill and restart
openclaw gateway start --force

# Check for config issues
openclaw doctor --fix

Common causes: another gateway instance already running, port conflict with another service, or a malformed config file.

"Cron jobs not firing"

# Is the scheduler enabled?
openclaw cron status

# Check job history
openclaw cron runs --id <jobId> --limit 10

# Test-fire the job manually
openclaw cron run <jobId>

Cron jobs can be silently skipped during quiet hours (if configured), when the gateway is under heavy load, or when the target session is already processing a request.

"Channel shows connected but messages don't flow"

# Deep probe
openclaw channels status --probe

# Check logs for policy drops
openclaw logs --follow

Then send a test message and watch the logs. Look for keywords like drop, mention required, pairing, allowlist, or blocked. These tell you exactly which policy is filtering the message.

"Permission errors on macOS"

# Fix ownership of OpenClaw directory
sudo chown -R $(whoami) ~/.openclaw

# Fix file permissions
chmod 700 ~/.openclaw
chmod 600 ~/.openclaw/openclaw.json

This usually happens after running OpenClaw with sudo or after a system update changes file ownership.

"Update failed with EACCES"

# Use sudo for the update
sudo openclaw update

# Or fix npm permissions globally
sudo chown -R $(whoami) /usr/local/lib/node_modules

"Agent seems slow or unresponsive"

# Check if requests are queued
openclaw status --all

# Check model usage/rate limits
openclaw status --usage

# Watch for timeout errors
openclaw logs --follow

Slow responses usually mean either the model provider is rate-limiting you, your context window is full (causing expensive cache misses), or the agent is processing a long tool chain.

"WhatsApp disconnected"

# Re-login (scan QR code again)
openclaw channels login whatsapp

# Check connection status
openclaw channels status --probe

WhatsApp Web sessions expire periodically. This is a known limitation of the WhatsApp Web protocol.

macOS Launchctl Token Issues

If you previously set tokens via launchctl setenv, they override your config file:

# Check for stale tokens
launchctl getenv OPENCLAW_GATEWAY_TOKEN
launchctl getenv OPENCLAW_GATEWAY_PASSWORD

# Remove them
launchctl unsetenv OPENCLAW_GATEWAY_TOKEN
launchctl unsetenv OPENCLAW_GATEWAY_PASSWORD

Quick Reference Card

When Nothing Else Works

If you've run through the commands above and things still aren't working, here's the nuclear option sequence:

# 1. Stop everything
openclaw gateway stop

# 2. Run full doctor with aggressive repair
openclaw doctor --fix --force

# 3. Check for duplicate installs
openclaw doctor --deep

# 4. Start fresh
openclaw gateway start --force

# 5. Verify
openclaw status --all

If that doesn't fix it, grab the output of openclaw status --all and head to the OpenClaw Discord. The community is active and the devs actually read the support channel.

You can also check the official docs at docs.openclaw.ai and the source code at github.com/openclaw/openclaw.

This reference covers OpenClaw v2026.2.x. Commands may change in future versions. Run openclaw help or openclaw <command> --help for the most current syntax.