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 ~/.openclaw/openclaw.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 ~/.openclaw/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 ~/.openclaw/openclaw.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 ~/.openclaw/workspace/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 (on older installs) messages about a Chrome relay or no tab connected.

Possible causes:

• Chrome/Chromium not installed
• Browser control not enabled
• Linux-specific display issues
• CDP / existing-session attach not ready (no usable tab or wrong profile)
• 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 and driver mode (existing-session / DevTools MCP per current docs)—the legacy extension relay was removed in 2026.3.22; run openclaw doctor --fix if you have stale relay config
5. 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.

Agent keeps "thinking," webhook or custom tool never fires, tokens drain: Often a mismatch between what the model believes it can call (e.g. instructions in TOOLS.md) and what the Gateway actually exposes under tools.profile / tools.allow, or the tool call fails silently from a network path the model keeps trying to "fix." See Agent tool loop & custom tools (e.g. n8n).

Agent tool loop & custom tools (e.g. n8n webhooks)

Symptoms: The assistant babbles in a self-reflective or "doctor" style, repeats planning steps, burns context/tokens, and nothing reaches your external integration (for example an n8n workflow that should start on webhook). Sometimes it insists the tool exists because it read TOOLS.md, but execution never happens or n8n shows no run.

What's going on:

• TOOLS.md is documentation in context, not automatic registration. It tells the model how you want tools used. The real allowlist is config: tools.profile, optional tools.allow / deny rules, skills, MCP, and anything else your build actually wires into the tool surface. If the runtime only exposes fetch_web_search and shell (for example), a bespoke tool name you only described in Markdown may not exist as a callable tool—the model can still spiral trying to "make it work."
• gateway.bind / listen address is about who can connect to OpenClaw, not whether your Gateway can open an outbound HTTP request to n8n. Migrating gateway.bind from 0.0.0.0 to lan does not by itself fix or break webhook calls to another host.
• n8n must be reachable from the machine running the Gateway. Test with curl or wget to the webhook URL from that same host (firewall, wrong URL, TLS, VPN, or "localhost" pointing at the wrong machine are common).
• Restricted profiles need explicit allow entries. If you use tools.profile: "minimal" (or similar) and an tools.allow list, every tool the agent should invoke—including helpers like sessions_spawn if you use subagents—must be allowed. See Sub-agent setup for an example of expanding tools.allow.

What to do:

1. In the Control UI, confirm which tools are actually available for the session (recent releases surface this explicitly). Align tools.profile and tools.allow with the tools you need, then restart the Gateway.
2. For n8n, prove the webhook from the Gateway host, then compare the URL and payload with what the agent or shell step sends. See OpenClaw + n8n for the recommended pattern (agent triggers a locked workflow; secrets stay in n8n).
3. To stop runaway turns: cancel or reset the session from the client you use, or restart the Gateway; add a short rule at the top of AGENTS.md such as "If a tool or webhook fails twice, stop, summarize the error, and ask me—do not keep diagnosing." (Context & truncation — important rules belong at the top.)
4. Set provider spending limits / alerts so a stuck loop cannot rack up an unlimited bill; see managed hosting cost note on agent loops.
5. Run openclaw doctor and check gateway logs (openclaw gateway logs) while reproducing—the failure is often a denied tool, timeout, or HTTP error the model is not surfacing cleanly to chat.

There is no single gateway.mode or tools.security switch whose purpose is "allow all external tools"; you configure the tool profile, allowlists, exec/network policy, and skills so the intended calls are real, allowed, and testable.

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 ~/.openclaw/gateway.lock
3. Kill any stuck processes: killall openclaw (Linux/macOS)
4. Restart Gateway: openclaw gateway restart