openclaw doctor

Diagnostic tool that checks system health and automatically repairs common issues.

Usage

openclaw doctor [options]

Options

--fix

boolean

Apply suggested fixes without prompting (non-interactive)

--non-interactive

boolean

Run in non-interactive mode (equivalent to —fix)

--generate-gateway-token

boolean

Automatically generate and configure gateway token if missing

--workspace-suggestions

boolean

Show workspace improvement suggestions (default: true)

What Doctor Checks

The doctor command performs comprehensive system diagnostics:

1. Configuration

Config file validity - JSON5 syntax and schema validation
Gateway configuration - Mode, port, bind, auth settings
Legacy config migration - Detects and migrates deprecated settings
Missing required fields - Ensures all required config is present

2. Authentication

Gateway auth - Token/password configuration
Auth profiles - Model provider credentials
OAuth profiles - Anthropic/OpenAI OAuth status
Deprecated profiles - Removes obsolete CLI auth profiles

3. Gateway Health

Reachability - Can the gateway be reached?
Service status - Is the daemon installed and running?
Port conflicts - Is the port already in use?
Daemon configuration - Service configuration validity

4. Channels

Channel connectivity - Are channels reachable?
Token validity - Are channel tokens configured correctly?
Recent errors - Checks channel logs for issues

5. Workspace

Directory existence - Is the workspace accessible?
Bootstrap files - Are guide files present?
Skills directory - Is skills structure correct?
Memory system - Is memory search configured?

6. System Integration

systemd lingering (Linux) - User session persistence
LaunchAgent overrides (macOS) - Environment conflicts
Shell completion - Command completion setup
Path environment - Is openclaw on PATH?

7. State Integrity

Session files - Session store validity
Lock files - Stale lock detection and cleanup
Legacy state - Old data migration
Backup suggestions - Workspace backup reminders

8. Security

Auth warnings - Insecure configurations
Token exposure - Tokens in env/logs
Bind warnings - Unsafe bind modes
Sandbox scope - Container security settings

9. Updates

Version check - Is an update available?
Update channel - Current channel status
UI protocol - Frontend/backend version compatibility

10. Docker/Sandbox

Docker availability - Is Docker installed?
Sandbox images - Are required images present?
Image updates - Are images up to date?

Automatic Repairs

Doctor can automatically fix many issues:

Config Repairs

Migrate legacy configuration format
Generate missing gateway token
Fix gateway auth mode
Update deprecated settings
Repair malformed config

Auth Repairs

Remove deprecated auth profiles
Fix OAuth profile IDs
Clear invalid session overrides

Gateway Repairs

Repair daemon configuration
Fix service install issues
Regenerate gateway token

Workspace Repairs

Create missing directories
Install bootstrap files
Fix skills structure

System Repairs

Enable systemd lingering (Linux)
Install shell completion
Fix PATH configuration

Examples

# Run diagnostics
openclaw doctor

# Apply all fixes automatically
openclaw doctor --fix

# Non-interactive mode
openclaw doctor --non-interactive

Output Format

Doctor organizes findings into sections:

┌─ OpenClaw doctor
│
├─ ✓ Configuration
│   Config valid: ~/.openclaw/openclaw.json
│
├─ ⚠ Gateway
│   gateway.mode is unset
│   Fix: run `openclaw configure` and set mode
│
├─ ✓ Auth Profiles
│   2 profiles configured
│
├─ ✗ Gateway Health
│   Gateway not reachable (timeout)
│   Service status: not running
│
├─ ✓ Channels
│   telegram: configured
│   discord: configured
│
├─ ✓ Workspace
│   Workspace: ~/openclaw-workspace
│
└─ Doctor complete.

Status Indicators

✓ (green) - Check passed
⚠ (yellow) - Warning, may need attention
✗ (red) - Error, requires action

Interactive Prompts

When run interactively, doctor prompts for repairs:

⚠ Gateway auth token missing

? Generate and configure a gateway token now? (Y/n)

Options:

Y - Apply the fix
n - Skip this fix
Ctrl+C - Exit doctor

Use --fix to auto-accept all prompts.

Common Issues

Gateway Won’t Start

Symptoms:

openclaw gateway start fails
Gateway not reachable

Doctor checks:

Config validation
Port conflicts (lsof -i :18789)
Gateway auth configuration
Daemon service status

Suggested fixes:

openclaw doctor
# Follow prompts to:
# - Set gateway.mode=local
# - Generate auth token
# - Fix daemon config
# - Repair port conflicts

Channel Not Working

Symptoms:

Messages not sending/receiving
Channel shows offline

Doctor checks:

Channel token validity
Channel connectivity
Recent channel errors
Gateway health

Suggested fixes:

openclaw doctor
# Review channel warnings
# Then:
openclaw channels status --probe
openclaw channels login --channel whatsapp

Config Invalid

Symptoms:

Commands fail with config errors
Gateway won’t start

Doctor checks:

JSON5 syntax
Schema validation
Required fields
Type checking

Suggested fixes:

openclaw doctor --fix
# Automatically repairs common config issues

# Or manually:
openclaw config get gateway
openclaw configure

After Update Issues

Symptoms:

Commands fail after update
Config incompatible

Doctor checks:

Config schema version
Legacy migrations
UI protocol version
Dependencies

Suggested fixes:

openclaw doctor
# Apply suggested migrations
# Rebuild if needed:
pnpm install
pnpm build

systemd Service Stops (Linux)

Symptoms:

Gateway stops on logout
Service not persistent

Doctor checks:

User lingering status
Service configuration

Suggested fixes:

openclaw doctor
# Prompts to enable lingering:
sudo loginctl enable-linger $USER

Exit Codes

0 - Doctor completed successfully
1 - Doctor found critical issues
2 - Doctor encountered errors

Use in scripts:

if openclaw doctor --non-interactive; then
  echo "System healthy"
else
  echo "Issues detected"
  exit 1
fi

Scheduling

Run doctor periodically:

Cron

# Weekly health check
0 2 * * 0 /usr/local/bin/openclaw doctor --non-interactive

systemd Timer

Create ~/.config/systemd/user/openclaw-doctor.timer:

[Unit]
Description=OpenClaw Doctor Health Check

[Timer]
OnCalendar=weekly
Persistent=true

[Install]
WantedBy=timers.target

And ~/.config/systemd/user/openclaw-doctor.service:

[Unit]
Description=OpenClaw Doctor

[Service]
Type=oneshot
ExecStart=/usr/local/bin/openclaw doctor --non-interactive

Enable:

systemctl --user enable openclaw-doctor.timer
systemctl --user start openclaw-doctor.timer

Logs

Doctor operations are logged to:

~/.openclaw/logs/gateway.log

View doctor-specific logs:

openclaw logs --plain | grep doctor

Migration Detection

Doctor detects and migrates:

Legacy session format - Old session file structure
Old agent state - Pre-2026 agent configuration
WhatsApp auth migration - Auth directory changes
Config schema updates - Field renames/restructuring

Manual Migration

If automatic migration fails:

# Backup first
cp -r ~/.openclaw ~/.openclaw.backup

# Run doctor with fixes
openclaw doctor --fix

# Check results
openclaw status

Security Warnings

Doctor checks for security issues:

Auth Mode None

⚠ Gateway auth mode=none with bind=lan
This exposes the gateway without authentication.
Set gateway.auth.mode=token or gateway.auth.mode=password

Token in Logs

⚠ Gateway token may be exposed in logs
Consider rotating: openclaw config set gateway.auth.token newtoken

Unsafe Bind

⚠ Gateway bind=lan without Tailscale or VPN
Consider using bind=loopback or gateway.tailscale.mode=serve

Best Practices

Run after install: openclaw onboard then openclaw doctor
Run after updates: openclaw update then openclaw doctor
Run before reporting issues: Include doctor output in bug reports
Run periodically: Weekly health checks recommended
Review warnings: Don’t ignore yellow warnings

status - Quick status overview
gateway - Gateway management
channels - Channel management
config - Configuration management
onboard - Initial setup wizard

Commands

Management

​openclaw doctor

​Usage

​Options

​What Doctor Checks

​1. Configuration

​2. Authentication

​3. Gateway Health

​4. Channels

​5. Workspace

​6. System Integration

​7. State Integrity

​8. Security

​9. Updates

​10. Docker/Sandbox

​Automatic Repairs

​Config Repairs

​Auth Repairs

​Gateway Repairs

​Workspace Repairs

​System Repairs

​Examples

​Output Format

​Status Indicators

​Interactive Prompts

​Common Issues

​Gateway Won’t Start

​Channel Not Working

​Config Invalid

​After Update Issues

​systemd Service Stops (Linux)

​Exit Codes

​Scheduling

​Cron

​systemd Timer

​Logs

​Migration Detection

​Manual Migration

​Security Warnings

​Auth Mode None

​Token in Logs

​Unsafe Bind

​Best Practices

​Related Commands

openclaw doctor

Usage

Options

What Doctor Checks

1. Configuration

2. Authentication

3. Gateway Health

4. Channels

5. Workspace

6. System Integration

7. State Integrity

8. Security

9. Updates

10. Docker/Sandbox

Automatic Repairs

Config Repairs

Auth Repairs

Gateway Repairs

Workspace Repairs

System Repairs

Examples

Output Format

Status Indicators

Interactive Prompts

Common Issues

Gateway Won’t Start

Channel Not Working

Config Invalid

After Update Issues

systemd Service Stops (Linux)

Exit Codes

Scheduling

Cron

systemd Timer

Logs

Migration Detection

Manual Migration

Security Warnings

Auth Mode None

Token in Logs

Unsafe Bind

Best Practices

Related Commands