OpenClaw Error: RPC probe: failed (Runtime Running) | Auth & URL Fix | Mac, Linux, WSL2

Service Initialization

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

This is an authentication/URL configuration error, not a gateway service crash. It occurs when the OpenClaw Gateway runtime is running, but the current auth token, bind address, or URL configuration makes the runtime inaccessible to the RPC probe. Can be diagnosed and fixed in 2 minutes.

Quick Answer (3-Step Fix)

Run these commands in order to resolve the RPC probe: failed error immediately, following the official troubleshooting flow:

# Step 1: Confirm runtime status and root cause (official diagnostic)
openclaw gateway status
# Expected output: Runtime: running, RPC probe: failed

# Step 2: Reset invalid auth configuration (most common fix)
openclaw config delete gateway.token
openclaw doctor --generate-gateway-token
openclaw config set gateway.bind loopback

# Step 3: Fix config drift and restart gateway
openclaw gateway install --force
openclaw gateway restart
openclaw gateway health

Official Diagnostic Tip: Use openclaw gateway probe to scan all local/remote gateway targets and get detailed RPC reachability diagnostics.

Why This Error Occurs

RPC probe: failed with a running runtime explicitly means: the gateway process is alive, but it is inaccessible with your current auth/url configuration. Reference: OpenClaw Gateway Troubleshooting Guide

This is one of the most common post-upgrade breakage issues, caused by stricter bind and auth guardrails in newer OpenClaw versions. The official troubleshooting guide identifies two core root causes: non-loopback binds without valid auth configured, and deprecated config keys like gateway.token not replacing the new gateway.auth.token structure.

Typical Error Output

[INFO] Gateway Status Check
[INFO] Runtime: running
[ERROR] RPC probe: failed
[WARN] Config (cli) vs Config (service) mismatch detected
[INFO] Use openclaw gateway probe for detailed diagnostics

Common trigger scenarios:

Upgraded OpenClaw, and old gateway.token config is no longer recognized (replaced by gateway.auth.token)
Set gateway.bind to lan, tailnet, custom or 0.0.0.0 without valid authentication
Auth mode/token mismatch between the CLI config and the running gateway service
Explicit --url flag used without passing matching --token or --password credentials
Device identity authentication failures (nonce mismatch, expired signature, missing device auth)
CLI config and running service config have drifted (different config paths/values)
Firewall rules block RPC traffic to the gateway port, even though the process is running
Control UI connectivity issues from non-secure HTTP contexts requiring device identity

Auth Detail Codes Quick Map

Use the error.details.code from your failed probe response to identify the exact issue:

Detail Code	Meaning	Recommended Fix
`AUTH_TOKEN_MISSING`	Client did not send a required shared token	Set `gateway.auth.token` in your config
`AUTH_TOKEN_MISMATCH`	Shared token did not match gateway auth token	Regenerate token and sync CLI/service config
`AUTH_DEVICE_TOKEN_MISMATCH`	Cached per-device token is stale/revoked	Rotate/re-approve device token
`PAIRING_REQUIRED`	Device identity not approved for this role	Approve pending device pairing request

Reference: OpenClaw Gateway Troubleshooting Guide

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 exact root cause of the probe failure:

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

Key checks from the output:

Is there a Config (cli) vs Config (service) mismatch warning?
Does gateway probe show the local loopback target as reachable?
What is the auth detail code in the failed probe response?
Are there nonce/signature/device identity errors in the logs?
Is the gateway bound to a non-loopback address without auth?

2. Fix Auth Configuration Errors (Most Common Root Cause)

Deprecated token config and missing auth are the top causes of RPC probe failures on running gateways:

# Step 1: Clean up deprecated token config
openclaw config delete gateway.token

# Step 2: Generate a new valid auth token (auto-saved to gateway.auth.token)
openclaw doctor --generate-gateway-token

# Step 3: Verify auth config is correctly set
openclaw config get gateway.auth.mode
openclaw config get gateway.auth.token
# Expected output: mode = token, and a long random token string

# Step 4: Restart gateway to apply auth changes
openclaw gateway restart

# Step 5: Verify probe success
openclaw gateway status

Official Note: The old gateway.token config key is no longer recognized in newer OpenClaw versions. You must use the new gateway.auth.token structure for authentication.

3. Fix Bind & URL Configuration Issues

Non-loopback binds without valid auth are a primary trigger for this error:

# Step 1: Revert to secure default loopback binding (recommended)
openclaw config set gateway.bind loopback
openclaw gateway restart
openclaw gateway status

# Step 2: If non-loopback binding is required, set valid auth first
# 2.1 Set auth token
openclaw doctor --generate-gateway-token
# 2.2 Set desired bind mode
openclaw config set gateway.bind lan # or tailnet/custom
# 2.3 Restart gateway
openclaw gateway restart
# 2.4 Verify probe success
openclaw gateway probe

4. Fix Device Identity Authentication Failures

Device identity errors are common for Control UI/dashboard connectivity issues:

# Step 1: Verify device auth status
openclaw devices list
openclaw doctor

# Step 2: Approve pending pairing requests
openclaw pairing list
# Replace  with your pending request ID
openclaw pairing approve  

# Step 3: Rotate stale device tokens
openclaw devices rotate 
openclaw gateway restart

# Step 4: For Control UI access, use HTTPS/localhost (secure context required)
# Access the UI via http://127.0.0.1:18789 instead of http://localhost:18789

5. Fix Service Config Drift

If the CLI config and running service config disagree, use the official fix to reinstall service metadata:

# Step 1: Force reinstall gateway service metadata from current config profile
openclaw gateway install --force

# Step 2: Restart the gateway service
openclaw gateway restart

# Step 3: Verify config sync and probe success
openclaw gateway status
# Expected output: Runtime: running, RPC probe: ok

Reference: OpenClaw Gateway Troubleshooting Guide

Platform-Specific Notes

macOS

Use openclaw gateway status --deep to scan for conflicting launchd services with mismatched config
Ensure the macOS app is updated to match the CLI version to avoid config drift
Control UI requires a secure context (localhost/HTTPS) for device auth; use http://127.0.0.1:18789
Check macOS Firewall settings to ensure OpenClaw has incoming network access

Linux / Raspberry Pi

Verify systemd service config matches CLI config: systemctl --user cat openclaw-gateway.service
Use openclaw doctor --fix to resolve permission issues with the systemd service
Ensure UFW/firewalld allows traffic on port 18789 from trusted sources only
Run sudo ss -tulpn | grep 18789 to confirm the gateway is listening on the correct interface

WSL2

Critical: Always work inside the Linux file system (~/), not the Windows file system (/mnt/c/) to avoid config drift
Set up port forwarding from Windows to WSL2 to ensure the probe can reach the gateway
Use gateway.bind=lan to allow access from Windows, and ensure auth is configured
Systemd is not enabled by default in WSL2; use openclaw gateway run for foreground mode

Common Search Variants

OpenClaw RPC probe failed runtime running
OpenClaw gateway running but RPC probe failed
OpenClaw RPC probe failed auth token mismatch
OpenClaw Config cli vs Config service mismatch
OpenClaw gateway RPC probe not working
OpenClaw device identity required RPC probe
OpenClaw gateway.auth.token not working

FAQ

Q: What’s the difference between “RPC probe: failed” and “gateway connect failed:”?

A: gateway connect failed: means the CLI cannot reach the gateway process at all (process not running, wrong port/URL). RPC probe: failed means the gateway process is running, but the CLI cannot authenticate or access the RPC API due to invalid auth/URL/bind configuration.

Q: Why is the gateway running but the RPC probe failing?

A: The most common causes are: deprecated gateway.token config not recognized, non-loopback binding without valid auth, auth token mismatch between CLI and service, or device identity authentication failures.

Q: How do I fix “AUTH_TOKEN_MISMATCH” in the RPC probe?

A: Run openclaw doctor --generate-gateway-token to generate a new valid token, then run openclaw gateway install --force to sync the config to the service, then restart the gateway.

Q: Why did the RPC probe start failing after upgrading OpenClaw?

A: Newer OpenClaw versions have stricter bind and auth guardrails, and deprecated the old gateway.token config. Run openclaw doctor --fix to resolve post-upgrade config drift, then regenerate your auth token.

Q: Can I bypass the RPC probe check?

A: No. The RPC probe is a diagnostic tool to verify gateway API accessibility. The probe failure indicates a real issue with your auth/URL configuration that will prevent the gateway from functioning correctly, even if the process is running.

Q: The gateway is running on loopback, but the RPC probe still fails. What should I do?

A: First, verify your auth configuration is set correctly with openclaw config get gateway.auth.token. If no token is set, run openclaw doctor --generate-gateway-token. Then run openclaw gateway install --force to fix config drift, and restart the gateway.

Summary

The RPC probe: failed error occurs when the OpenClaw Gateway runtime is running, but invalid auth, bind, or URL configuration makes the RPC API inaccessible. It is most commonly triggered by post-upgrade config drift, deprecated token config, or non-loopback binding without valid authentication.

The fastest fix is to clean up deprecated config, generate a new valid auth token, revert to loopback binding, and force reinstall the gateway service metadata to sync CLI and service config. Use the official openclaw gateway probe command to diagnose detailed reachability issues.

Official Best Practices

✅ Always run the official diagnostic command ladder first when encountering probe failures
✅ Use the new gateway.auth.token structure, and delete deprecated gateway.token config
✅ Run openclaw doctor --fix immediately after upgrading OpenClaw to resolve config drift
✅ Use gateway.bind=loopback unless you explicitly need remote access to the gateway
✅ Always configure valid authentication before changing the gateway bind mode
✅ Use openclaw gateway install --force to sync CLI and service config when drift is detected
✅ Access the Control UI via http://127.0.0.1:18789 to satisfy secure context requirements for device auth

Quick Navigation