1. Symptoms
The clw-prompt-disconnected error manifests when the OpenClaw CLI client (clw) loses its active session connection to the OpenClaw daemon or remote service endpoint. Users typically encounter this error during interactive sessions after an extended period of inactivity, network interruption, or when the underlying service undergoes maintenance or restarts.
Common indicators include a sudden halt in CLI operations with the following error message displayed in the terminal:
[ERROR] clw-prompt-disconnected: The CLI session has been disconnected from the OpenClaw service.
Unable to send request: connection reset by peer
Additional symptoms may accompany this error:
- The terminal cursor stops responding to input commands
- Background operations fail with connection-related error codes
- Authentication tokens appear valid but requests continue failing
- The CLI displays a “Reconnecting…” message that never completes
- Previous commands executed successfully, but new commands timeout immediately
- Interactive prompts disappear without warning, leaving the user at a blank terminal state
In network-distributed environments, users may also observe partial command execution where some operations complete while others hang indefinitely before triggering the disconnection error. The error frequently occurs during file transfer operations, remote command execution, or long-running queries that exceed the configured session timeout threshold.
2. Root Cause
The clw-prompt-disconnected error originates from a broken communication channel between the clw CLI client and the OpenClaw daemon process. Understanding the underlying architecture helps diagnose the specific failure point.
OpenClaw operates on a client-daemon architecture where the clw client maintains a persistent WebSocket or long-polling connection to the backend service. This connection serves multiple purposes: it maintains session state, enables real-time notifications, and provides an authenticated channel for command execution. When this connection terminates unexpectedly, the client cannot determine the session state and raises the clw-prompt-disconnected error.
Several technical factors commonly trigger this disconnection:
Network Instability: Firewall rules, NAT timeouts, or VPN disconnections can terminate the underlying TCP connection without proper graceful shutdown. Many enterprise networks implement connection tracking that terminates idle connections after specific intervals, typically between 30 seconds and 5 minutes.
Daemon Restarts: If the OpenClaw service undergoes a rolling restart, deployment, or crash recovery, all connected clients lose their sessions simultaneously. The client may not receive notification of the restart if it occurs during a network partition.
Session Timeout: OpenClaw implements idle session timeouts to resource cleanup. Sessions inactive for longer than the configured threshold (default typically 300 seconds) are terminated server-side, but the client may not detect this until attempting the next command.
Token Expiration: While authentication tokens may appear valid, many OpenClaw deployments implement sliding window token expiration where tokens refresh based on activity. A disconnected session may fail token validation upon reconnection.
Resource Exhaustion: On the daemon side, memory pressure, file descriptor limits, or container resource constraints can trigger service degradation that manifests as connection drops for all clients.
TLS/SSL Issues: Certificate rotation, TLS version mismatches, or expired certificates on either the client or server can cause secure connections to terminate abruptly without informative error messages.
3. Step-by-Step Fix
Resolving the clw-prompt-disconnected error requires systematic diagnosis followed by appropriate remediation based on the identified cause.
Step 1: Verify Network Connectivity
Before attempting session recovery, confirm basic network connectivity to the OpenClaw service endpoint.
Before:
# Attempt to run any clw command
clw status
# Output: [ERROR] clw-prompt-disconnected
After:
# Test network reachability
ping -c 4 openclaw.example.com
telnet openclaw.example.com 8443
# Verify DNS resolution
nslookup openclaw.example.com
# Check local firewall rules
sudo iptables -L | grep 8443
# or on macOS
sudo pfctl -s rules | grep 8443
Step 2: Clear Local Session State
The local client may retain stale session data preventing reconnection.
Before:
# Check for existing session files
ls -la ~/.clw/sessions/
After:
# Remove stale session files
rm -rf ~/.clw/sessions/*
rm -f ~/.clw/config/session.token
# Clear any cached credentials
clw logout --all
# Restart the session
clw login
Step 3: Restart the OpenClaw Daemon (Local Installations)
For users running a local OpenClaw daemon, restart the service.
Before:
# Check daemon status
clw daemon status
# Output: daemon=stopped, last_error="connection refused"
After:
# Stop the daemon
clw daemon stop
# Kill any zombie processes
pkill -f "openclaw-daemon"
pkill -f "clw-daemon"
# Clear daemon socket files
rm -f /tmp/clw-daemon.sock
rm -f ~/.clw/daemon.pid
# Start the daemon fresh
clw daemon start
# Verify daemon is running
clw daemon status
# Output: daemon=running, version=2.4.1, pid=12345
Step 4: Adjust Session Timeout Configuration
If timeouts are too aggressive, increase the threshold in the client configuration.
Before:
# View current configuration
clw config get session.timeout
# Output: 300
After:
# Increase timeout to 3600 seconds (1 hour)
clw config set session.timeout 3600
clw config set session.keepalive true
clw config set session.retry_attempts 5
clw config set session.retry_delay 2
# Apply configuration
clw config reload
# Verify settings
clw config list | grep session
Step 5: Handle Token Expiration
Manually refresh authentication tokens if expiration is suspected.
Before:
# Attempt command without re-authentication
clw execute "echo test"
# Output: [ERROR] clw-prompt-disconnected
After:
# Force complete re-authentication
clw logout
clw login --force
# Verify authentication
clw auth status
# Output: authenticated=true, expires_at=2024-01-15T18:00:00Z
# Retry the original command
clw execute "echo test"
# Output: test
Step 6: Corporate Network Environment Fix
For users behind corporate proxies or firewalls, additional configuration may be necessary.
Before:
# Default configuration
echo $HTTP_PROXY
# Output: (empty)
After:
# Configure proxy settings
clw config set network.proxy.enabled true
clw config set network.proxy.url "http://proxy.corp.com:8080"
clw config set network.proxy.exclude "*.internal,localhost,127.0.0.1"
# For long-running connections
clw config set network.keepalive_interval 30
clw config set network.tcp_keepalive true
# Reload and test
clw config reload
clw status
4. Verification
After implementing the fix, thorough verification ensures the connection is stable and the error will not recur during normal operations.
Test Basic Connectivity:
# Verify daemon connection
clw daemon ping
# Expected: pong
# Check complete status
clw status
# Expected: status=connected, session_id=abc123, latency_ms=45
Test Session Persistence:
# Create a new session
clw session create "verification-test"
# Expected: session_id=xyz789, created=true
# Execute commands in the session
clw session exec xyz789 -- "whoami"
# Expected: current user output
# Leave idle for 60 seconds, then execute another command
sleep 60 && clw session exec xyz789 -- "date"
# Expected: current date/time output, no disconnection
Test Long-Running Operations:
# Execute a longer operation
timeout 120 clw execute --stream "sleep 90 && echo done"
# Expected: Output streams correctly without disconnection
Test Reconnection Behavior:
# Simulate temporary network interruption
# (In a separate terminal): sudo ifconfig eth0 down
# Wait 10 seconds, then restore
# (In separate terminal): sudo ifconfig eth0 up
# Verify automatic reconnection
clw status
# Expected: Automatic reconnection within 30 seconds, no manual intervention required
Check Logs for Recurring Issues:
# Review recent logs
clw logs --lines 100 --level error | grep -i "disconnect\|timeout\|reset"
# Monitor for 24 hours and check for recurrence
clw logs --follow | tee /tmp/clw-monitor.log
5. Common Pitfalls
Avoid these frequent mistakes when troubleshooting the clw-prompt-disconnected error:
Ignoring the Underlying Network Issue: Simply restarting the daemon without investigating network stability guarantees the error will recur. Use tools like mtr, traceroute, and packet capture to identify network path problems.
Not Checking Daemon Logs: The clw-prompt-disconnected message on the client is often a symptom, not the cause. The daemon logs contain the actual error that triggered the disconnection, such as out-of-memory kills or failed health checks.
Assuming Token Validity: Authentication tokens can expire during extended idle periods. Always perform a complete logout and login cycle rather than assuming cached credentials remain valid.
Misconfiguring Timeout Values: Setting excessively long timeouts can mask underlying issues and consume server resources. Find the minimum viable timeout through testing rather than arbitrarily using maximum values.
Forgetting to Reload Configuration: Many configuration changes require an explicit reload or daemon restart. Failing to reload means the new settings are ignored and the old (problematic) behavior persists.
Not Verifying in the Actual Environment: Testing fixes in a controlled environment with stable networking does not guarantee they work in production environments with firewalls, proxies, or unstable connections.
Overlooking Client Version Mismatches: The error can occur when the clw client version is incompatible with the daemon version. Always ensure version alignment between client and server components.
Premature Aborting of Retry Attempts: Connection recovery often requires multiple retry attempts with exponential backoff. Canceling after the first failed attempt prevents successful recovery during temporary network fluctuations.
6. Related Errors
clw-daemon-unreachable: This error occurs when the clw client cannot establish any initial connection to the OpenClaw daemon. Unlike clw-prompt-disconnected which implies a previously working connection, this error indicates fundamental connectivity failures. Resolution typically involves checking daemon process status, network routing, firewall rules, and service endpoint configuration.
clw-session-timeout: This error specifically relates to idle session termination due to inactivity. While similar to clw-prompt-disconnected, the session timeout variant explicitly indicates the server terminated the session after the configured idle period. Prevention involves adjusting keepalive settings, reducing idle times, or implementing background heartbeat mechanisms.
clw-auth-expired: This error occurs when the authentication token used for the session has expired or been revoked. Unlike disconnection errors that relate to network connectivity, this error stems from credential validity. Resolution requires obtaining fresh authentication credentials through the standard login flow or token refresh mechanism.