Troubleshooting

Fix common issues and resolve problems

Common Issues

Gateway Won't Start

Possible causes:

  • Node.js version is too old (requires ≥22)
  • Port 18789 is already in use
  • Configuration file has syntax errors
  • Missing dependencies

Solutions:

  1. Run openclaw doctor to check for configuration issues
  2. Verify Node.js version: node --version
  3. Check if port is in use: lsof -i :18789 (macOS/Linux)
  4. Review configuration file: ~/.clawdbot/moltbot.json
  5. Reinstall: npm install -g openclaw@latest

Channel Not Connecting

Possible causes:

  • Incorrect credentials or tokens
  • Missing environment variables
  • Network connectivity issues
  • Channel-specific configuration errors

Solutions:

  1. Verify credentials are correct
  2. For WhatsApp, ensure you've completed the pairing process
  3. Check ~/.clawdbot/credentials for stored credentials
  4. Verify environment variables are set correctly
  5. Check channel-specific documentation in Channels Guide
  6. Enable verbose logging: openclaw gateway --verbose

Permission Errors (macOS)

Possible causes:

  • Missing macOS permissions in System Settings
  • Screen recording permission not granted
  • Accessibility permissions missing

Solutions:

  1. Open System Settings → Privacy & Security
  2. Grant necessary permissions:
    • Screen Recording
    • Accessibility
    • Full Disk Access (if needed)
  3. For screen recording, set needsScreenRecording: true in tool calls
  4. Restart the Gateway after granting permissions

Model Authentication Issues

Possible causes:

  • Invalid API keys
  • Expired OAuth tokens
  • Incorrect model configuration
  • Rate limiting or quota exceeded

Solutions:

  1. Verify API keys or OAuth tokens are valid
  2. Check model configuration in ~/.clawdbot/moltbot.json
  3. Test authentication: openclaw agent --message "test"
  4. Check provider dashboard for rate limits or quotas
  5. Configure model failover for reliability

Skills Not Working

Possible causes:

  • Skill file syntax errors
  • Missing dependencies
  • Incorrect skill configuration
  • Permission issues

Solutions:

  1. Check skill files in ~/clawd/skills/
  2. Review skill logs for errors
  3. Verify skill dependencies are installed
  4. Test skill manually
  5. Recreate skill if needed

Browser Control Not Working

Error message: "can't reach the openclaw browser control service. start (or restart) the openclaw gateway" or "chrome extension relay is running, but no tab is connected"

Possible causes:

  • Chrome/Chromium not installed
  • Browser control not enabled
  • Linux-specific display issues
  • Chrome extension not connected to a tab
  • Gateway not running

Solutions:

  1. Verify Chrome/Chromium is installed
  2. Enable browser control in config: browser.enabled: true
  3. On Linux, ensure display is available (X11 or Wayland)
  4. Check browser control URL configuration
  5. Click the OpenClaw Chrome extension icon on a tab to attach it
  6. Restart the Gateway: openclaw gateway restart

No Output / Not Responding

Issue: OpenClaw shows no output or doesn't respond to messages

Possible causes:

  • Gateway not running
  • Channel not connected
  • Model authentication failed
  • Configuration errors
  • Network connectivity issues

Solutions:

  1. Check Gateway status: openclaw gateway status
  2. Restart Gateway: openclaw gateway restart
  3. Run diagnostics: openclaw doctor --fix
  4. Check channel connection: openclaw channels list
  5. Verify model configuration and API keys
  6. Check logs: openclaw gateway logs

Gateway Token Missing / Unauthorized (1008)

Error message: "disconnected (1008): unauthorized: gateway token missing" or "gateway token missing (open a tokenized dashboard url or paste token in control ui settings)"

Possible causes:

  • Missing or invalid gateway token
  • Token expired or revoked
  • Control UI not configured with token
  • Gateway started without token authentication

Solutions:

  1. Open a tokenized dashboard URL (contains the token in the URL)
  2. Or paste the token in Control UI settings
  3. Restart Gateway with token: openclaw gateway --token YOUR_TOKEN
  4. Check gateway configuration for token settings
  5. Verify token is valid and not expired

Gateway Already Running / PID Lock Timeout

Error message: "gateway already running pid lock timeout"

Possible causes:

  • Previous Gateway instance didn't shut down properly
  • Lock file exists but process is not running
  • Stale PID file

Solutions:

  1. Check for running Gateway process: ps aux | grep openclaw (Linux/macOS)
  2. Remove lock file if process is not running: rm ~/.clawdbot/gateway.lock
  3. Kill any stuck processes: killall openclaw (Linux/macOS)
  4. Restart Gateway: openclaw gateway restart

Health Checks

Run openclaw doctor to perform comprehensive health checks:

  • Check for configuration issues
  • Surface risky/misconfigured DM policies
  • Verify gateway status
  • Check for updates
  • Validate channel configurations
  • Check workspace integrity
Health Check Command 
openclaw doctor [--fix]

Tip: Use openclaw doctor --fix to automatically fix common issues like permission problems, missing directories, and configuration errors.

Logging

Enable verbose logging to diagnose issues:

Verbose Logging 
openclaw gateway --verbose

Or set verboseLevel in your configuration file for persistent verbose output.

Log locations:

  • Gateway logs: Check terminal output or system logs
  • Channel logs: Per-channel logging in workspace
  • Agent logs: Session logs in workspace

Gateway Lock

If the Gateway appears locked or won't start:

  1. Check for lock file: ~/.clawdbot/gateway.lock
  2. Verify no other Gateway instance is running
  3. Remove lock file if Gateway process is not running: rm ~/.clawdbot/gateway.lock
  4. Restart Gateway

Background Process

If Gateway is running as a background service:

  • macOS: Check launchd: launchctl list | grep clawdbot
  • Linux: Check systemd: systemctl --user status clawdbot
  • View logs: journalctl -u clawdbot (Linux) or check Console.app (macOS)
  • Restart service: systemctl --user restart clawdbot (Linux)

Browser Troubleshooting (Linux)

On Linux, browser control may require additional setup:

  • Install Chrome/Chromium: sudo apt install chromium-browser (Debian/Ubuntu)
  • Ensure display server is running (X11 or Wayland)
  • Set DISPLAY environment variable if needed
  • Use headless mode if no display available

Getting Help

If you're still experiencing issues:

  1. Run openclaw doctor and review all output
  2. Enable verbose logging and capture error messages
  3. Check the Configuration Guide for settings
  4. Review Channels Guide for channel-specific issues
  5. Check workspace files for errors

Related Documentation