Diagnosing Installation Issues with openclaw doctor

What Is openclaw doctor

openclaw doctor is OpenClaw's built-in diagnostic tool that automatically checks your runtime environment, configuration files, and service connection statuses, helping you quickly identify and resolve installation and deployment issues. Whether you have just completed installation or encountered a failure during operation, openclaw doctor should be your first troubleshooting step.

Basic Usage

Run the following in your terminal:

openclaw doctor

The command will sequentially perform multiple checks and output results in a clear format. Each check item will be marked as passed, warning, or failed.

Check Items Explained

openclaw doctor checks the following key items. Let's go through each one to understand what it checks and common issues.

Node.js Version Check

OpenClaw requires Node.js 22 or higher. doctor checks whether the current Node.js version meets this requirement.

Common Issue: Multiple Node.js versions are installed on the system, and the version actually in use is below 22.

Solution:

node --version

If the version is below 22, you need to upgrade. Using nvm to manage Node.js versions is recommended:

nvm install 22
nvm use 22
nvm alias default 22

Important note: Do not use Bun as a Node.js replacement. While Bun is faster in some scenarios, it has known compatibility issues with WhatsApp and Telegram WebSocket connections, and it is not recommended by the OpenClaw team.

Configuration File Check

doctor verifies whether the ~/.openclaw/openclaw.json configuration file exists and has valid formatting.

Common Issues:

• Configuration file does not exist: Usually because the initialization wizard was never run
• JSON format error: Syntax errors introduced during manual editing

Solution:

If the configuration file does not exist, run the onboarding wizard:

openclaw onboard --install-daemon

If the JSON format is invalid, you can validate it with:

python3 -m json.tool ~/.openclaw/openclaw.json

Common JSON errors include missing commas, trailing commas, or mismatched quotes.

Network Connectivity Check

doctor tests network connections to OpenClaw core services and various AI model APIs.

Common Issues:

• Firewall blocking outbound connections
• Incorrect proxy configuration
• DNS resolution failures

Solution:

Check basic network connectivity:

curl -I https://api.openai.com
curl -I https://api.anthropic.com

If you are in a network environment that requires a proxy, make sure you have set the correct proxy environment variables:

export HTTP_PROXY=http://proxy:port
export HTTPS_PROXY=http://proxy:port

AI Model API Check

doctor validates whether the configured AI model API keys are valid and tests API connections.

Common Issues:

• API key has expired or is invalid
• API quota exhausted
• Selected model is unavailable

Solution:

Open the configuration file and check the API key:

cat ~/.openclaw/openclaw.json

Confirm the key is correctly formatted and has not expired. You can check the key status and remaining quota through each AI provider's console. To update a key, directly edit the configuration file or re-run the onboarding wizard.

Chat Platform Connection Check

doctor checks the connection status of each configured chat platform one by one, including WhatsApp, Telegram, Discord, and others.

Common Issues:

• WhatsApp session expired and needs re-scanning
• Telegram Bot Token is invalid
• Discord Bot has not been invited to the target server
• Webhook URL is unreachable

Solution:

For WhatsApp connection issues:

openclaw onboard

Re-enter the onboarding wizard, select reconnect WhatsApp, and follow the prompts to scan the QR code.

For Telegram issues, verify the Bot Token is valid:

curl https://api.telegram.org/botYOUR_TOKEN/getMe

For Webhook URL issues, make sure your server is accessible from the outside and that port 3000 (or your configured port) is not blocked by a firewall.

Port Occupancy Check

doctor checks whether the port OpenClaw needs (default 3000) is occupied by another program.

Common Issues:

• Another OpenClaw instance is already running
• Another web application is using the same port

Solution:

Check port usage:

# Linux
ss -tlnp | grep 3000

# macOS
lsof -i :3000

If the port is occupied, you can either stop the process using the port or modify the OpenClaw configuration to use a different port.

Disk Space Check

doctor checks whether the partition containing ~/.openclaw/ has sufficient disk space.

Common Issues:

• Accumulated log files taking up too much space
• Insufficient disk space causing service anomalies

Solution:

df -h ~
du -sh ~/.openclaw/*

If space is insufficient, clean up unnecessary log files:

rm -rf ~/.openclaw/logs/*.log.old

Daemon Status Check

doctor checks whether OpenClaw's daemon process is properly configured and running.

Common Issues:

• systemd service not enabled (Linux)
• LaunchAgent not loaded (macOS)
• Service has stopped or is in a failed state

Solution:

On Linux:

systemctl status openclaw
sudo systemctl restart openclaw

On macOS:

launchctl list | grep openclaw
launchctl start com.openclaw.agent

Common Diagnostic Scenarios

Scenario 1: Just Completed Installation

The first thing to do after installation is run openclaw doctor to confirm your environment meets all requirements:

npm install -g openclaw@latest
openclaw onboard --install-daemon
openclaw doctor

Scenario 2: Service Suddenly Stops Working

When OpenClaw suddenly stops responding to messages:

openclaw doctor

Use the check results to pinpoint the issue. It is usually caused by network changes, API key expiration, or chat platform session timeouts.

Scenario 3: Issues After Upgrading

Run doctor after upgrading OpenClaw to confirm compatibility:

npm install -g openclaw@latest
openclaw doctor

Scenario 4: Verification After Migration

After migrating OpenClaw from one server to another:

openclaw doctor

Confirm that configuration files are properly restored and all connections are working in the new environment.

Interpreting the Output

doctor's output uses colors and symbols to mark the status of each check:

• Pass: The check is completely normal; no action is needed
• Warning: There is a potential issue that does not affect basic operation, but you should keep an eye on it
• Fail: The check did not pass and requires immediate attention

For failed check items, doctor typically provides specific error messages and repair suggestions. Follow the suggestions to fix issues one by one, then re-run openclaw doctor until all checks pass.

Getting More Detailed Diagnostic Information

If the standard diagnostics are not detailed enough, you can check OpenClaw's runtime logs for more information:

# Linux systemd
journalctl -u openclaw -n 100

# macOS LaunchAgent
cat /tmp/openclaw.stderr.log

# Or check OpenClaw's own logs
ls ~/.openclaw/logs/

Seeking Community Help

If you cannot resolve an issue on your own, you can share the full output of openclaw doctor on OpenClaw's GitHub Issues or community forums to ask for help. The diagnostic output provides sufficient environment information for community members to quickly help you locate the problem.

When submitting an issue, it is recommended to include:

• Full openclaw doctor output
• openclaw --version version information
• node --version version information
• Operating system type and version
• Detailed description of the issue and reproduction steps

Summary

openclaw doctor is one of the most practical diagnostic tools in the OpenClaw ecosystem. Building the habit of running doctor immediately after installation, after upgrades, and when encountering issues will help you quickly identify and resolve the vast majority of installation and deployment problems. It systematically checks everything from the runtime environment to service connections, making it an essential safeguard for stable OpenClaw operation.