Troubleshooting

How to Restart OpenClaw / Gateway Restart

OpenClaw gateway restart – use one of these:

• openclaw restart – quick restart
• openclaw gateway restart – explicit gateway restart

If OpenClaw runs as a service:

• Linux (systemd): systemctl --user restart openclaw-gateway (service name may vary; check with systemctl --user list-units | grep openclaw)
• macOS (launchd): Restart from OpenClaw menu bar app, or launchctl unload ~/Library/LaunchAgents/ai.openclaw.gateway.plist then start again

See also FAQ: How do I restart OpenClaw?

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: ~/.openclaw/openclaw.json or ~/.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

Error: Bundled Chrome Extension Is Missing – Reinstall OpenClaw

Error message: error: bundled chrome extension is missing. reinstall openclaw and try again.

Fix:

1. Reinstall OpenClaw: npm install -g openclaw@latest or pnpm add -g openclaw@latest
2. Restart your terminal and run openclaw onboard --install-daemon if you use the daemon
3. Restart the Gateway: openclaw gateway restart
4. If the error persists, fully quit the OpenClaw app (macOS menu bar) or stop the service, then start again

Can't Reach the OpenClaw Browser Control Service

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
• Tools not enabled — Agent can chat but cannot read files, run commands, or use the browser (see below)

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

Agent replies but never runs tools (read file, run command, browser): Your agent may have no tools enabled. OpenClaw can default to tools.profile: "messaging", which only allows sending messages—no file access, exec, or browser. Fix: set "tools": { "profile": "full" } in your config (or "coding" if you use that profile). Then restart the Gateway. If you need the agent to run commands without asking for approval each time (e.g. on Telegram where there is no confirmation popup), add "exec": { "security": "full", "ask": "off" } under tools. Set profile first; exec.ask only applies when tools are enabled. New installs (2026.3.8+) default to a coding profile in onboarding, but upgraded or manually edited configs may still have messaging-only. See Configuration.

Billing / API errors (2026.2.19+): When a model or provider returns a billing or quota error, OpenClaw now includes the active model in the message (e.g. OpenAI (gpt-5.3)) so you can see which key or account needs credits.

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. Generate a new token: openclaw doctor --generate-gateway-token then open a tokenized dashboard URL: openclaw dashboard --no-open
6. Verify token is valid and not expired

Note (2026.2.19+): If you don't set gateway auth, OpenClaw can now auto-generate and persist a gateway.auth.token at startup so the Control UI and clients can connect. You can still set gateway.auth.mode: "none" explicitly for local-only loopback setups.

Disconnected (1008): Pairing Required

Error: disconnected (1008): pairing required or pairing required openclaw

The Control UI or client must complete pairing before it can connect. Open the OpenClaw dashboard (or your tokenized URL), go to settings/Devices (or equivalent), and complete the pairing step. For DM channels (e.g. Telegram, WhatsApp), use openclaw pairing approve <channel> <code> to approve new contacts. See Security Guide for DM pairing and allowlists.

Pairing CLI (2026.2.21): pairing list and pairing approve default to the sole available pairing channel when omitted, so you can recover from "pairing required" without guessing channel arguments (handy for TUI-only setups).

Managing paired devices (2026.2.19+): To remove a device or clear pairing state, use openclaw devices remove for a specific device, or openclaw devices clear --yes [--pending] to clear paired entries and optionally reject pending requests. Config also supports device.pair.remove for hygiene flows.

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