Haven't installed OpenClaw yet? Click here for one-line install commands
curl -fsSL https://openclaw.ai/install.sh | bash
iwr -useb https://openclaw.ai/install.ps1 | iex
curl -fsSL https://openclaw.ai/install.cmd -o install.cmd && install.cmd && del install.cmd
Worried about affecting your computer? ClawTank runs in the cloud with no installation required, eliminating accidental deletion risks
Key Findings
  • openclaw doctor is OpenClaw's built-in one-stop diagnostic tool that automatically checks configuration file syntax, model authentication status, Gateway connectivity, and Node.js version compatibility[1]
  • Adding the --fix flag lets doctor automatically repair most common issues, including missing configuration values, expired tokens, and corrupted workspace indexes[1]
  • Gateway connection failure ("Pairing Required" error) is the most common beginner issue, typically resolved simply by regenerating the Gateway Token[2]
  • The root cause of agent "freezes" is usually LLM request timeouts -- increasing timeoutSeconds or configuring a fallback model can effectively mitigate this[4]

1. openclaw doctor: Your First Line of Defense

When OpenClaw exhibits abnormal behavior, the first thing you should always do is run openclaw doctor. This command performs a comprehensive health check of the entire system and reports the status of each item with clear red/yellow/green indicators.[1]

1.1 Basic Diagnostics

openclaw doctor

This command checks the following in sequence:

  1. Node.js version: OpenClaw requires Node.js 22 or above
  2. Configuration file integrity: Syntax and required fields in openclaw.json
  3. Model authentication: Whether configured providers can connect successfully
  4. Gateway status: Whether the Gateway is running and the port is reachable
  5. Channel connectivity: Whether configured channels (Telegram, WhatsApp, etc.) are functioning normally

1.2 Automatic Repair

openclaw doctor --fix

With --fix added, doctor doesn't just diagnose problems -- it also attempts to repair them. Common automatic repairs include:

1.3 Generate Gateway Token

openclaw doctor --generate-gateway-token

This command is specifically used to generate or regenerate the Gateway authentication Token. When you see a "Pairing Required" error, running this single command usually resolves the issue.[2]

2. The Five Most Common Problems and Solutions

2.1 "Pairing Required" -- Gateway Connection Failure

Symptoms: You see the "Pairing Required" message in the Web UI (http://127.0.0.1:18789) or messaging channels.

Cause: Gateway Token is missing, expired, or mismatched.

Solution:

openclaw doctor --generate-gateway-token
# Then restart the Gateway
openclaw gateway restart

2.2 "LLM Request Timed Out" -- Model Request Timeout

Symptoms: The agent stops responding mid-task, and logs show a timeout error.[4]

Cause: LLM API response time exceeds the default limit, common during complex tasks or API traffic peaks.

Solution:

# Increase timeout (in seconds)
openclaw config set agents.defaults.timeoutSeconds 600

# Set a fallback model to automatically switch when the primary model times out
openclaw config set agents.defaults.model.fallbacks '["claude-sonnet-4-6"]'

2.3 Agent "Frozen" and Unresponsive

Symptoms: The agent is completely unresponsive -- no replies and no errors after sending messages.

Cause: Possible Gateway process freeze, Node process crash, or corrupted workspace state.

Solution (from least to most disruptive):

# 1. Restart the Gateway
openclaw gateway restart

# 2. If Gateway cannot restart normally, force stop then restart
openclaw gateway stop
openclaw gateway start

# 3. If still unresolved, run a full diagnostic repair
openclaw doctor --fix

2.4 Port 18789 Already in Use

Symptoms: Starting the Gateway shows the port is already in use.

Solution:

# Check what's using the port
lsof -i :18789

# Option A: Kill the occupying process
kill -9 PID

# Option B: Change the port
openclaw config set gateway.port 28789

2.5 Model Authentication Failure

Symptoms: The agent reports "Model not allowed" or "Authentication failed".[4]

Solution:

# Check model status
openclaw models status

# Reconfigure API key
openclaw models auth setup-token --provider anthropic

# Or redo the OAuth flow
openclaw models auth login --provider openai

3. Restart and Reset Procedures

3.1 Normal Restart (Preserves All Data)

openclaw gateway restart

This is the safest restart method. The Gateway writes the current state to persistent storage before restarting. All workspaces, memory, and settings are preserved.

3.2 Full Stop and Start

openclaw gateway stop
# Wait a few seconds
openclaw gateway start

Use this when gateway restart doesn't work. The stop command ensures all related processes are fully terminated.

3.3 Daemon Mode Restart (systemd)

If you installed the systemd service using openclaw onboard --install-daemon:

systemctl --user restart openclaw-gateway

3.4 Clear Context (Soft Reset)

If the agent's conversation context becomes confused, you can clear just the context without restarting the entire system:

openclaw tui

This opens a fresh interactive conversation interface without affecting long-term memory in the workspace.

4. Log Analysis and Advanced Debugging

4.1 View Real-Time Logs

openclaw logs --follow

This command outputs Gateway runtime logs in real time, similar to tail -f. You can see the processing of each request, model call latency, and error messages.[7]

4.2 Common Log Message Reference

Log MessageMeaningRecommended Action
Gateway started on :18789Normal startupNo action needed
Pairing requiredToken verification failedRun doctor --generate-gateway-token
LLM request timed outModel response timeoutIncrease timeoutSeconds or set a fallback
Model not allowedModel not in the allowlistCheck allowlist settings
Agent bootstrap pendingAgent is initializingWait for completion, usually takes 10-30 seconds
WebSocket connection closedWebSocket disconnectedCheck network connection or reverse proxy settings

5. Preventive Maintenance Recommendations

Rather than reactive troubleshooting, proactive prevention is better. Here is a maintenance checklist based on our hands-on experience:[5][6]

  1. Run openclaw doctor once a week: Even when the system is running normally, regular checks can catch potential issues early
  2. Keep OpenClaw updated: Run npm update -g openclaw to get the latest security patches and feature improvements
  3. Configure fallback models: Never rely on a single model provider
  4. Monitor Gateway memory usage: Long-running Gateways may develop memory leaks; restarting weekly is recommended
  5. Back up the ~/.openclaw/ directory: Contains all your settings, authentication, and workspace data

Conclusion

openclaw doctor with the --fix flag can automatically resolve over 80% of common issues.[1] For more complex problems, the log analysis and systematic troubleshooting procedures provided in this article can help you quickly identify the root cause.

If you're just getting started with OpenClaw, we recommend first reading our Architecture Analysis & Hands-On Deployment Guide to build a complete understanding of the system; if you need to adjust settings, refer to the Configuration Complete Guide.