Fix clw-api-failure: OpenClaw API Request Error

By Alex Chen
OpenClaw intermediate Linux macOS Windows

1. Symptoms

When clw-api-failure occurs, the OpenClaw CLI (clw) terminates with a non-zero exit code and prints an error message that describes the nature of the API communication failure. Users typically observe the following symptoms:

  • Command execution fails with clw-api-failure displayed as the primary error code.
  • The CLI output may include additional context such as the HTTP status code, the endpoint path, and a short description of what went wrong.
  • Repeated attempts to run the same command produce identical failures.
  • Authentication commands that previously succeeded now fail with this error.

A typical error message looks like this:

[ERROR] clw-api-failure: Failed to connect to https://api.openclaw.io/v2/deployments
[ERROR] HTTP 503: Service Unavailable
[ERROR] Reason: upstream_timeout

In some cases, the error message includes a request ID that can be used when contacting support:

[ERROR] clw-api-failure: Request failed
[ERROR] Endpoint: POST https://api.openclaw.io/v2/artifacts/push
[ERROR] HTTP 502: Bad Gateway
[ERROR] Request ID: req_8f3a9c2d1e4b

Users may also see this error when the API returns a structured error response:

[ERROR] clw-api-failure: API returned error response
[ERROR] Status: 401 Unauthorized
[ERROR] Code: INVALID_TOKEN
[ERROR] Message: The access token has expired or is otherwise invalid

2. Root Cause

The clw-api-failure error covers a broad range of API communication problems. The underlying causes typically fall into one of the following categories:

Network connectivity issues. The clw CLI cannot establish a TCP connection to the API endpoint. This can happen due to firewall rules blocking outbound traffic on port 443, a corporate proxy intercepting HTTPS requests, or DNS resolution failures preventing the CLI from resolving the API hostname.

HTTP-level errors returned by the server. The API server returns a non-2xx status code. Common scenarios include HTTP 503 (Service Unavailable) when the backend is undergoing maintenance, HTTP 502 (Bad Gateway) when an upstream service fails, and HTTP 504 (Gateway Timeout) when the server-side request times out before completing.

TLS/SSL handshake failures. The clw CLI fails to verify the server’s TLS certificate. This can occur when the system’s CA certificate store is outdated, when a TLS interception proxy presents its own certificate, or when the API endpoint uses a certificate signed by an internal CA that is not trusted by the system.

Authentication and token problems. The request reaches the API, but the server rejects it due to an expired or invalid access token. This is particularly common when the token stored in the local credentials file has passed its expiration time and the CLI does not automatically refresh it.

Request payload issues. The API returns HTTP 400 (Bad Request) because the payload serialized by the CLI does not match the expected format. This can happen when the CLI version is incompatible with the API server version, or when local configuration specifies parameters that the server does not recognize.

Rate limiting. The API enforces rate limits per client or per account. Exceeding these limits results in HTTP 429 (Too Many Requests), which the CLI surfaces as clw-api-failure.

3. Step-by-Step Fix

Step 1: Verify Network Connectivity

First, confirm that your machine can reach the OpenClaw API endpoint. Run a basic connectivity test:

# Test TCP connectivity to the API on port 443
nc -zv api.openclaw.io 443

# Test HTTPS reachability with a verbose HTTP request
curl -v https://api.openclaw.io/v2/health 2>&1 | head -30

If the connection fails, check your firewall rules, VPN status, and proxy configuration.

Step 2: Check Proxy Configuration

If you operate behind a corporate proxy, ensure that clw is configured to use it. The CLI respects standard proxy environment variables. Set them before running clw commands:

Before:

export HTTPS_PROXY=""
export HTTP_PROXY=""
export NO_PROXY="api.openclaw.io"

After:

export HTTPS_PROXY="http://proxy.corp.example.com:8080"
export HTTP_PROXY="http://proxy.corp.example.com:8080"
export NO_PROXY="localhost,127.0.0.1,api.openclaw.io"
clw deployments list

If authentication is required by the proxy, include credentials in the URL:

export HTTPS_PROXY="http://user:[email protected]:8080"

Step 3: Verify or Refresh Authentication Token

Check the currently stored credentials and their expiration status:

# View the stored credentials file
cat ~/.config/openclaw/credentials.json

# Check the token's expiration
clw auth status

If the token is expired or invalid, re-authenticate:

# Re-authenticate with the CLI
clw auth login

# Or log out and back in
clw auth logout
clw auth login --api-key YOUR_API_KEY

Before:

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expires_at": "2024-12-01T00:00:00Z",
  "token_type": "Bearer"
}

After:

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expires_at": "2025-02-01T00:00:00Z",
  "token_type": "Bearer"
}

Step 4: Specify the Correct API Endpoint

If you are using a self-hosted or on-premises instance of OpenClaw, verify that the CLI is configured to point to the correct base URL:

# Check the current endpoint configuration
clw config get api.endpoint

# Set the correct endpoint if needed
clw config set api.endpoint https://openclaw.internal.example.com

Before:

clw config get api.endpoint
# Output: https://api.openclaw.io

After:

clw config set api.endpoint https://openclaw.internal.example.com
clw config get api.endpoint
# Output: https://openclaw.internal.example.com

Step 5: Update the CLI to Match the API Version

If the API server has been upgraded and the CLI is outdated, install the latest version of clw:

# Install the latest version on Linux/macOS
curl -sSL https://get.openclaw.io/install.sh | sh

# Or update using a package manager
brew upgrade clw
apt update && apt upgrade clw

# On Windows with Chocolatey
choco upgrade clw

After updating, verify the version:

clw --version

Step 6: Handle Rate Limiting

If the error is caused by rate limiting (HTTP 429), implement exponential backoff in your scripts or wait before retrying:

# Wait 60 seconds before retrying (for rate limit errors)
sleep 60
clw artifacts list

For automation scripts, use the --max-retries flag if supported:

clw deployments list --max-retries 3 --retry-delay 30

4. Verification

After applying the fix, verify that the clw CLI can communicate successfully with the API.

Check the authentication status:

clw auth status
# Expected output: Authenticated as [email protected] (expires in 30 days)

Test API connectivity directly:

clw api get /v2/health
# Expected: JSON response with "status": "ok"

Run a command that exercises the API:

clw deployments list
# Expected: List of deployments without any clw-api-failure errors

Check the configuration values:

clw config list
# Expected: Shows api.endpoint, auth.token_source, and other settings

If the CLI still fails after these steps, collect additional diagnostic information:

# Enable verbose logging
clw --verbose deployments list

# Capture the full output and request ID for support
clw deployments list --json 2>&1 | tee debug_output.json

5. Common Pitfalls

Ignoring the proxy configuration. Many developers forget that clw respects system proxy environment variables. If your network routes traffic through a proxy, the CLI will silently fail to connect unless HTTPS_PROXY and HTTP_PROXY are set correctly.

Using an outdated credentials file. The credentials file at ~/.config/openclaw/credentials.json may be stale. Simply deleting the file and running clw auth login is often the fastest way to resolve persistent authentication failures.

Mismatched API and CLI versions. When the OpenClaw server is updated, the API contract may change. Older CLI versions may produce clw-api-failure with HTTP 400 errors because they send payloads in a format the newer API does not expect. Always keep the CLI updated.

Misreading the error type. Not all clw-api-failure errors indicate the same problem. An HTTP 503 means the server is unavailable, while an HTTP 401 means authentication failed. Checking the HTTP status code in the error message helps narrow down the fix.

Skipping the request ID. When contacting support, the request ID (e.g., req_8f3a9c2d1e4b) is critical for debugging. Without it, support cannot look up the exact server-side logs for your request.

Not checking firewall rules. In containerized or restricted environments, port 443 outbound may be blocked. Use curl or nc to confirm that the API hostname resolves and the port is reachable before running clw commands.

  • clw-auth-expired: This error occurs when the access token has expired and the CLI cannot authenticate with the API. It often precedes clw-api-failure in scenarios where the token expires mid-session. Resolving it requires running clw auth refresh or clw auth login.

  • clw-timeout: The CLI successfully connected to the API endpoint but received no response within the configured timeout period. This can manifest as clw-api-failure if the timeout is interpreted as a connection failure by the underlying HTTP client.

  • clw-invalid-endpoint: The configured API endpoint URL is malformed or points to a server that does not implement the OpenClaw API protocol. This produces clw-api-failure for every command because the CLI cannot parse the response.

  • clw-tls-error: TLS handshake failures between the CLI and the API are reported as clw-api-failure in older CLI versions. Newer versions surface these as clw-tls-error with more specific diagnostic information about the certificate chain.

openclaw clw api-failure http cli network