OpenClaw devices CLI fails with timeout: fix pairing and approval errors

Problem statement: you run openclaw devices list or openclaw devices approve --latest and get timeout or websocket errors instead of your device list. The gateway appears to be running, the web UI works, but the CLI cannot connect to approve new devices.

Why this failure is especially disruptive

Device pairing is how you add new endpoints, workers, and nodes to your OpenClaw deployment. When the devices CLI fails, you cannot onboard new devices even if your gateway is otherwise healthy. The deceptive aspect is that the Control UI may work perfectly, making it appear that everything is fine except for this one command.

This leads to wasted time debugging unrelated areas: network connectivity, firewall rules, authentication, and permissions. The actual problem is often a mismatch between where the CLI is trying to connect and where the gateway is actually listening.

Typical failure pattern for device pairing issues

• openclaw devices list returns timeout after 10 seconds.
• openclaw devices approve --latest fails with websocket error 1000.
• Gateway status shows running and healthy in logs.
• Control UI web interface works normally.
• Pending devices remain unapproved and cannot connect.
• Rollback to previous version resolves the issue.

Root causes behind devices CLI failures

1) CLI-to-gateway WebSocket address mismatch

The devices CLI attempts to connect to ws://127.0.0.1:18789 by default, but the gateway may be listening on a different address, port, or interface after an upgrade or configuration change. When the target address is incorrect, connection attempts timeout after the default 10 second window.

2) Gateway WebSocket endpoint changes in new versions

OpenClaw releases can change internal WebSocket paths, add authentication requirements, or modify RPC handlers. The devices CLI from one version may not be compatible with the gateway from another. Reports indicate 2026.3.12 introduced a regression that breaks the devices/gateway contract.

3) Local loopback binding vs remote access configuration

If you are accessing OpenClaw through a reverse proxy or remote tunnel, the CLI may be trying to connect to a loopback address that is not actually exposed. The Control UI works through the proxy, but the CLI command attempts direct local connection and fails.

4) Version skew between CLI and runtime

If you installed OpenClaw globally but are running a gateway from a different version (perhaps in Docker or from a different installation method), the CLI and runtime may have incompatible expectations. This is especially common after partial upgrades.

Step-by-step fix for device pairing failures

Step 1: Verify gateway WebSocket listening status

Before assuming the CLI is broken, confirm what the gateway is actually listening on. Use system tools to check open ports and WebSocket endpoints.

# Check if port 18789 is listening
netstat -tuln | grep 18789
# or
ss -tuln | grep 18789

# Check WebSocket endpoint availability
curl -i -N   -H "Connection: Upgrade"   -H "Upgrade: websocket"   -H "Sec-WebSocket-Version: 13"   -H "Sec-WebSocket-Key: test"   http://127.0.0.1:18789/

# For Docker environments, check inside the container
docker exec <container-name> netstat -tuln | grep 18789

Step 2: Confirm CLI and gateway version match

Version mismatches are a common source of devices CLI failures. Ensure both the CLI and gateway are running the same version.

# Check CLI version
openclaw --version

# Check gateway version
openclaw gateway status

# For Docker, compare container tag
docker ps | grep openclaw

Step 3: Test CLI connection with verbose output

Run the devices command with verbose flags to see exactly where the connection is failing. This provides clearer evidence than the generic timeout message.

# Run with verbose/debug output
openclaw devices list --verbose
# or
DEBUG=openclaw:* openclaw devices list

# Test direct WebSocket connection
wscat -c ws://127.0.0.1:18789

Step 4: Use Control UI as temporary workaround

If you need to approve devices urgently while troubleshooting, use the Control UI's device management interface. The web UI typically communicates with the gateway through a different path that may still be working.

1. Open Control UI in your browser.
2. Navigate to Settings or Devices section.
3. Look for pending device approvals.
4. Approve devices directly from the web interface.

Step 5: Roll back to known-good version if needed

Based on user reports, rolling back from 2026.3.12 to 2026.3.8 has restored device pairing functionality. If the issue started immediately after an upgrade, this is often the fastest path to recovery.

# Pin to specific version (example)
npm install -g openclaw@2026.3.8

# For Docker, use specific tag in docker-compose.yml
image: openclaw/openclaw:2026.3.8

# Restart and verify device commands work
openclaw gateway restart
openclaw devices list

Step 6: Check for custom gateway address configuration

If you have configured OpenClaw to use a custom gateway address or WebSocket URL, verify the CLI can reach it. The devices command may need explicit gateway targeting if not using default loopback.

# Check if custom gateway URL is set
echo $OPENCLAW_GATEWAY_URL
# or check in config file
cat ~/.openclaw/config.yaml | grep gateway

# Override gateway address for testing
OPENCLAW_GATEWAY_URL=ws://localhost:18789 openclaw devices list

Reference commands for diagnosing device pairing

# Full diagnostic sequence
openclaw gateway status
netstat -tuln | grep 18789
openclaw --version
DEBUG=openclaw:* openclaw devices list

# Test WebSocket with wscat (install if needed)
npm install -g wscat
wscat -c ws://127.0.0.1:18789

# Check for pending devices through alternative method
openclaw status | grep -i device

# Restart gateway cleanly
openclaw gateway restart

Edge cases that complicate device pairing

Edge case: reverse proxy hides WebSocket path

If you access OpenClaw through nginx, traefik, or another reverse proxy, the WebSocket endpoint may be mapped differently than the direct connection. Ensure WebSocket upgrade headers are passed through correctly and that the CLI can reach the proxied endpoint.

Edge case: remote gateway access through SSH tunnel

When your gateway is on a remote machine and you access it via SSH tunnel, local port forwarding may not include the WebSocket port. Add explicit port forwarding for 18789 or use the remote shell to run devices commands directly on the gateway host.

Edge case: multiple OpenClaw instances on same network

If you run multiple OpenClaw instances or have previously installed OpenClaw in different ways, the CLI may be connecting to the wrong gateway. Explicitly target the correct instance or stop unused instances to eliminate confusion.

Edge case: firewall or security software blocking localhost

Unusual but possible: aggressive firewall or security software can block localhost connections. Test with a simple loopback connection using curl or netcat to confirm local networking is functional.

Fix once. Stop recurring device CLI pairing failures.

If this keeps coming back, you can move your existing setup to managed OpenClaw cloud hosting instead of rebuilding the same stack. Import your current instance, keep your context, and move onto a runtime with lower ops overhead.

• Import flow in ~1 minute
• Keep your current instance context
• Run with managed security and reliability defaults

If you would rather compare options first, review OpenClaw cloud hosting or see the best OpenClaw hosting options before deciding.

Import your current OpenClaw instance in 1 click Keep self-hosted: apply fix checklist

Verification checklist after fixing device pairing

• openclaw devices list returns output within 5 seconds.
• openclaw devices approve --latest successfully approves pending devices.
• Approved devices can connect and communicate with the gateway.
• WebSocket connection is established without timeout or error 1000.
• Fix survives gateway restart and system reboot.

Preventive controls for reliable device management

1. Pin OpenClaw versions after confirming stable device pairing works.
2. Test devices commands immediately after each upgrade in a staging environment.
3. Document custom gateway URLs and WebSocket configurations.
4. Maintain access to Control UI as a fallback for device approvals.
5. Add health checks that verify device CLI connectivity, not just web UI availability.

When device management overhead indicates a deployment issue

Recurring issues with device pairing, WebSocket connectivity, and version compatibility are symptoms of operational complexity. Each upgrade brings risk of regression, and each fix requires time and attention. For teams that need reliable multi-device setups, this overhead compounds quickly.

Managed hosting abstracts away these integration details. Device pairing, WebSocket routing, and version compatibility are handled consistently without manual intervention. The tradeoff is less direct control in exchange for predictable behavior.

Common mistakes in device pairing troubleshooting

• Mistake: assuming gateway is broken because CLI fails.
  Correction: verify what the gateway is actually listening on before making changes.
• Mistake: editing network configuration without checking version.
  Correction: confirm CLI and gateway versions match before changing network settings.
• Mistake: ignoring the Control UI workaround.
  Correction: use web interface for urgent approvals while troubleshooting CLI.
• Mistake: upgrading repeatedly to fix an upgrade regression.
  Correction: roll back to known-good version and wait for tested fix.
• Mistake: testing CLI without checking WebSocket endpoint.
  Correction: use wscat or curl to verify the WebSocket path is reachable.

FAQ

Should I modify my firewall rules when devices commands fail?

Only if you have confirmed the gateway is listening and the CLI is targeting the correct address. Firewall changes should not be your first troubleshooting step. Start by verifying the gateway is actually listening on the expected port.

Can I use a different port for device management?

OpenClaw uses default ports for internal communication. Changing ports requires configuration updates in multiple places and is not recommended as a first fix. Focus on resolving the default connection before adding custom configuration complexity.

Is this always a regression, or can it be user error?

It can be either. The pattern of working on one version and failing immediately after an upgrade strongly suggests a regression. However, always verify your configuration and environment before concluding it is a software bug.

Where should I start if I am new to OpenClaw device management?

Begin with the setup guide at /openclaw-setup/, which covers initial configuration and device onboarding. For multi-node deployments, review the architecture documentation to understand how devices, gateways, and nodes interact.