Fix OpenClaw browser relay keeps disconnecting

Diagnosing the disconnection pattern

OpenClaw relay disconnections produce log entries that help narrow down the root cause. Relay logs are stored at ~/.clawmesh/logs/relay.log on macOS and Linux, and at C:\ProgramData\ClawMesh\logs\relay.log on Windows. Look for lines containing ws close, connection dropped, or heartbeat timeout. The error code in the log message tells you whether the disconnection was initiated by the client, server, or network.

If disconnections happen within seconds of starting a relay session, the issue is likely a configuration problem such as an incorrect relay secret or a port conflict. If they happen after a period of inactivity, the issue is likely an idle timeout or a system sleep/wake cycle. If they happen unpredictably during active work, it is likely a network stability or resource exhaustion issue.

Browser relay sessions depend on a persistent WebSocket connection between the relay client (running on your machine) and the relay server (running in the ClawMesh cloud or your self-hosted infrastructure). Any network interruption that lasts longer than the WebSocket ping interval will cause a disconnection.

• Check the relay logs for disconnection timestamps and error codes
• Note whether disconnections happen during idle or active sessions
• Identify if the issue is browser-specific or affects all relay connections
• Check if the issue started after a browser, OS, or OpenClaw update

Validating the extension stack

The OpenClaw relay uses a browser extension to inject automation commands into web pages. This extension must be installed, enabled, and granted the correct permissions for the relay to function. Open your browser's extensions settings and verify that the OpenClaw relay extension is present and marked as enabled.

If you updated your browser recently, the extension may have been disabled automatically or reset to a default state. Re-enable it in the browser extensions settings and verify that it has permission to access the websites you are automating. Some browsers require you to explicitly grant host permissions for each domain.

Update the OpenClaw relay extension to the latest version available from the Chrome Web Store or the OpenClaw dashboard. Outdated extension versions may use deprecated APIs that cause compatibility issues with current browser releases. After updating, restart the browser completely before testing the relay again.

• Check the OpenClaw relay extension version in browser extensions settings
• Ensure the extension is enabled and has the correct permissions
• Update or reinstall the extension if the version is outdated
• Test with a different browser to isolate browser-specific issues

Resetting browser and OS permissions

After macOS updates, some permissions are silently revoked. This is a common cause of relay instability that appears suddenly after a system update. Open System Settings > Privacy and Security and scroll to Full Disk Access. Verify that the terminal or shell you use to launch OpenClaw is listed and enabled. If it is missing, add it again.

On Windows, open Windows Security > Virus & threat protection > Manage settings, and scroll to Exclusions. Add the OpenClaw installation directory C:\Program Files\ClawMesh and the relay binary directory to the exclusion list. Without these exclusions, Windows Defender may terminate the relay process or block its network connections.

Browser site permissions can override extension permissions in some cases. If the relay extension is working but cannot control specific websites, check the browser's site permissions for those URLs. The relay needs to read and modify page content on domains it automates.

• On macOS: check System Settings > Privacy and Security > Full Disk Access
• On Windows: verify Windows Defender exclusions for the relay binary
• Reset browser site permissions for the relay dashboard URL
• Re-grant any revoked permissions after an OS update

Tuning the reconnect policy

The relay maintains a persistent connection using WebSocket ping/pong heartbeats. If the heartbeat interval is too short relative to your network's tolerance for idle connections, the server may close the connection thinking it is dead. Increase the heartbeat interval to 30 seconds or higher with the relay config command.

Configure automatic reconnection with exponential backoff so the relay automatically restores sessions after transient network interruptions. The reconnect policy is configured with clawmesh relay config set reconnect.max to set the maximum number of retry attempts, and clawmesh relay config set reconnect.backoff to set the base delay in seconds between retries.

If your network uses a proxy, configure the proxy settings explicitly in the relay configuration rather than relying on automatic proxy detection. Run clawmesh relay config set proxy.url http://your-proxy:port to specify the proxy directly. Automatic proxy detection can be unreliable and may fail intermittently, causing connection drops.

• Adjust heartbeat interval: clawmesh relay config set heartbeat.interval 30
• Increase max reconnect attempts: clawmesh relay config set reconnect.max 10
• Set a fixed relay URL to avoid DNS re-resolution on each connection
• Disable proxy auto-detection if you are not using a corporate proxy

Network and infrastructure checks

Run clawmesh relay ping to test the connection between your relay client and the ClawMesh relay server. If the ping fails or times out, there is a network-level connectivity issue. Check your firewall rules, VPN status, and any SSL inspection policies that may be terminating the WebSocket connection.

Corporate VPNs and firewalls often have idle connection timeouts that are shorter than the OpenClaw relay's keepalive interval. If you are connecting from a corporate network, consult your IT team about increasing the allowed connection lifetime or whitelisting the ClawMesh relay server addresses.

WiFi connections are susceptible to periodic channel switching and power management that can briefly interrupt network connectivity. For stable relay sessions during extended automation workflows, use a wired Ethernet connection. If WiFi is the only option, disable WiFi power management in your operating system's network settings.

• Test relay connectivity with: clawmesh relay ping
• Check if corporate VPN or firewall is dropping long-lived connections
• Use a wired connection instead of WiFi for more stable relay sessions
• If self-hosting, check the relay server logs on the host machine

When to reinstall the browser

Reinstalling the browser is rarely necessary for relay issues. The browser itself is usually not the problem. Before reinstalling, test the relay with a fresh browser profile: create a new Chrome profile, install the OpenClaw extension, and attempt a relay session from the new profile. If it works, your existing browser profile has a configuration issue, not the browser installation.

If the fresh profile also disconnects, the issue is at the network or system level, not the browser. Focus on the relay configuration, permission settings, and network infrastructure fixes described above before considering a browser reinstallation.

• Reinstall only after validating all other causes above
• Create a fresh browser profile to test without removing your existing setup
• Export any important browser data before resetting
• Use Chrome DevTools Protocol (CDP) directly as a fallback automation method