openclaw doctor

Health checks and quick fixes for the gateway and channels

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

Basic

# 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:

1. Config validation
2. Port conflicts (lsof -i :18789)
3. Gateway auth configuration
4. 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:

1. Channel token validity
2. Channel connectivity
3. Recent channel errors
4. 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:

1. JSON5 syntax
2. Schema validation
3. Required fields
4. 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:

1. Config schema version
2. Legacy migrations
3. UI protocol version
4. 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:

1. User lingering status
2. 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

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

Related Commands

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