Quick Navigation

OpenClaw Error: gateway connect failed: (Connection Target Fix) | Mac, Linux, WSL2

Service Initialization

Last Updated: April 23, 2026 | Author: DevOps Engineering Team | Platforms: Linux / Raspberry Pi / macOS / WSL2

This is a connection target configuration error, not a system failure. It occurs when the CLI points to an incorrect host, port, or WebSocket URL, and cannot establish a connection to the Gateway. Can be diagnosed and fixed in 2 minutes.

Quick Answer (3-Step Fix)

Run these commands in order to resolve the gateway connect failed: error immediately, following the official diagnostic ladder: 

# Step 1: Verify local Gateway is running and healthy
openclaw gateway status
# Expected healthy output: Runtime: running, RPC probe: ok

# Step 2: Reset invalid remote Gateway configuration (most common fix)
openclaw config delete gateway.remote.url
openclaw config set gateway.mode local

# Step 3: Restart Gateway and verify connection
openclaw gateway restart
openclaw gateway health
Official Diagnostic Tip: Use openclaw gateway probe to automatically scan and diagnose connection issues for both local and remote Gateways.

Why This Error Occurs

gateway connect failed: explicitly means the CLI cannot reach the target Gateway due to a wrong URL, host, or port target. Reference: OpenClaw Gateway Troubleshooting Guide

This is one of the most common post-upgrade breakage issues, as OpenClaw has strict rules for URL and auth override behavior: Explicit –url calls do not fall back to stored credentials. Reference: OpenClaw Gateway Troubleshooting Guide

Typical Error Output

[ERROR] gateway connect failed: dial tcp 127.0.0.1:18789: connect: connection refused
[ERROR] gateway connect failed: invalid URL: missing protocol scheme
[ERROR] gateway connect failed: no route to host
[ERROR] gateway connect failed: context deadline exceeded

Common trigger scenarios:

  • Set gateway.mode=remote but configured an invalid or unreachable gateway.remote.url
  • Used the --url flag with an incorrect address, and did not pass matching auth credentials
  • Local Gateway service is not running, or not listening on the expected port
  • Post-upgrade config drift: URL and auth override behavior changed in newer versions
  • Firewall or network policy is blocking traffic to the target host/port
  • WSL2 environment: missing port forwarding configuration between Linux and Windows
  • Gateway is bound to loopback only, but you are trying to access it from an external network
  • Port conflict: another process is using port 18789, so the Gateway cannot listen

Full Fix Guide (Official Troubleshooting Flow)

Follow these steps in order, as recommended in the official troubleshooting runbook.

1. Run Official Standard Diagnostic Commands

First, run these commands to identify the root cause: 

# Official diagnostic ladder - run in this order
openclaw status
openclaw gateway status
openclaw logs --follow
openclaw doctor
openclaw gateway probe

Key checks from the output:

  • Is the Gateway runtime running or stopped?
  • Is the RPC probe ok or failed?
  • Is there a port conflict or bind error in the logs?
  • Does gateway probe show the local loopback target as reachable?

2. Fix Local Gateway Connection Failures

If the local Gateway is not running or unreachable: 

# Step 1: Restart the Gateway service
openclaw gateway restart

# Step 2: If restart fails, force reinstall service metadata
openclaw gateway install --force
openclaw gateway restart

# Step 3: Verify the Gateway is listening on the correct port
# macOS/Linux/WSL2
lsof -i :18789
# Expected output: openclaw process listening on *:18789 or 127.0.0.1:18789

3. Fix Remote Gateway Configuration Errors

If you are using gateway.mode=remote and getting connection failures: 

# Step 1: Verify your remote URL configuration
openclaw config get gateway.mode
openclaw config get gateway.remote.url

# Step 2: Reset to local mode if remote is not needed
openclaw config set gateway.mode local
openclaw config delete gateway.remote.url
openclaw gateway restart

# Step 3: If remote mode is required, set valid URL and auth
openclaw config set gateway.remote.url "ws://your-remote-gateway-ip:18789"
openclaw config set gateway.remote.token "your-remote-gateway-token"
openclaw gateway restart

# Step 4: Verify remote connection with probe
openclaw gateway probe --url ws://your-remote-gateway-ip:18789
Official Note: When you set an explicit --url, the CLI will NOT fall back to stored credentials. You must pass --token or --password explicitly for remote connections.

4. Fix Network & Firewall Issues

If the Gateway is running but the connection is blocked:

macOS

# Allow incoming connections in macOS Firewall
# System Settings → Network → Firewall → Options → Allow incoming connections for OpenClaw
# Verify port is reachable
nc -zv 127.0.0.1 18789

Linux / Raspberry Pi

# Allow port 18789 in UFW (restrict to trusted IPs only)
sudo ufw allow from 192.168.1.0/24 to any port 18789
sudo ufw reload

# Verify port is listening
sudo ss -tulpn | grep 18789

WSL2

# Enable port forwarding from Windows to WSL2
# Run this in Windows Command Prompt (Admin)
netsh interface portproxy add v4tov4 listenport=18789 listenaddress=0.0.0.0 connectport=18789 connectaddress=YOUR_WSL2_IP

# Verify port forwarding
netsh interface portproxy show all

Platform-Specific Notes

macOS

  • Use openclaw gateway status --deep to scan for conflicting launchd services
  • Ensure the macOS app is running if you are using the GUI-supervised Gateway
  • Check for port conflicts with other apps using lsof -i :18789
  • Remote access is recommended via Tailscale Serve instead of direct LAN binding

Linux / Raspberry Pi

  • Verify systemd service status with systemctl --user status openclaw-gateway
  • Never expose port 18789 directly to the public internet without auth and IP restrictions
  • Use openclaw doctor --fix to resolve permission issues with the service
  • Ensure Node.js 22+ is installed and available in the system PATH

WSL2

  • Critical: Always work inside the Linux file system (~/), not the Windows file system (/mnt/c/)
  • Port forwarding is required to access the Gateway from Windows or other devices on the network
  • Use gateway.bind=lan in the config to allow access from Windows
  • Systemd is not enabled by default in WSL2; use openclaw gateway run for foreground mode

Common Search Variants

  • OpenClaw gateway connect failed error
  • openclaw gateway connection refused
  • openclaw remote gateway url wrong
  • openclaw –url connect failed
  • openclaw gateway no route to host
  • openclaw gateway context deadline exceeded
  • openclaw gateway probe failed
  • openclaw local gateway not reachable

FAQ

Q: What does “gateway connect failed:” mean?

A: It means the OpenClaw CLI cannot establish a network connection to the Gateway service, almost always due to an incorrect host, port, or URL configuration, or the Gateway service not running.

Q: How do I find the correct Gateway URL?

A: For local mode, the default URL is ws://127.0.0.1:18789. For remote mode, use the IP address of the machine running the Gateway, plus port 18789, with the ws:// protocol prefix.

Q: What’s the difference between gateway.mode=local and gateway.mode=remote?

A: local mode runs the Gateway service on the current machine. remote mode connects the CLI to a Gateway service running on a different machine, requiring a valid remote URL and auth credentials.

Q: Why did the connection start failing after upgrading OpenClaw?

A: Newer versions have stricter URL and auth override behavior. Run openclaw doctor --fix to resolve post-upgrade config drift, then restart the Gateway service.

Q: Why does using –url cause a connection failure?

A: When you use the --url flag, the CLI does not fall back to your stored credentials. You must explicitly pass --token or --password along with the --url parameter.

Q: The Gateway is running, but I still can’t connect from another device on the network. What should I do?

A: First, set gateway.bind=lan in your config (default is loopback only). Then configure your firewall to allow incoming connections on port 18789 from trusted devices. For remote access, prefer Tailscale Serve over direct LAN exposure.

Summary

The gateway connect failed: error is a connection target configuration issue that occurs when the OpenClaw CLI cannot reach the Gateway service. The most common causes are incorrect remote URL configuration, the Gateway service not running, post-upgrade config drift, or network/firewall blocks.

The fastest fix is to reset to local mode, restart the Gateway service, and use the official diagnostic commands to identify the root cause. For remote connections, always ensure you have a valid URL and matching auth credentials.

Official Best Practices

  • ✅ Always run the official diagnostic command ladder first when encountering connection issues
  • ✅ Use gateway.mode=local unless you explicitly need a remote Gateway
  • ✅ Run openclaw doctor --fix immediately after upgrading OpenClaw
  • ✅ Use openclaw gateway probe to diagnose connection issues instead of manual config changes
  • ✅ Prefer Tailscale Serve for remote access instead of exposing the Gateway directly to the network
  • ✅ Always pass explicit auth credentials when using the --url flag
  • ✅ Restrict port 18789 to trusted IP addresses only in your firewall

Official References

Related High-Performance Guides

Scroll to Top