Fix clw-llm-unreachable: OpenClaw LLM Endpoint Unreachable Error

By Maya Rodriguez
OpenClaw intermediate Linux macOS Windows Docker

1. Symptoms

The clw-llm-unreachable error occurs during OpenClaw operations that require communication with a Large Language Model endpoint. You may observe the following symptoms:

  • OpenClaw commands hang indefinitely before failing with the unreachable error
  • API requests to the LLM endpoint return connection timeouts
  • Error message appears in the terminal or application logs
  • The configured model appears valid but responses are never received

Common manifestations of this error include:

[ERROR] clw-llm-unreachable: Failed to connect to LLM endpoint at https://api.example.com/v1
[ERROR] Connection refused or endpoint not reachable after 30s timeout
[ERROR] DNS resolution failed for the configured LLM host

When this error surfaces, OpenClaw cannot establish a connection to the language model backend, preventing any LLM-dependent operations from completing.

2. Root Cause

The clw-llm-unreachable error stems from several potential root causes:

Network Connectivity Issues The host machine cannot reach the LLM endpoint due to firewall rules, network segmentation, or VPN configuration. The target server may be blocking incoming connections or the network path may be restricted.

Incorrect Endpoint Configuration The OpenClaw configuration file specifies an incorrect URL, port, or protocol. Common mistakes include using http:// instead of https://, specifying the wrong port number, or using an outdated endpoint path.

LLM Service Unavailability The remote LLM service itself is down for maintenance, experiencing high load, or has reached capacity limits. In cloud-hosted scenarios, the provider may be experiencing outages.

DNS Resolution Failures The hostname in the configuration cannot be resolved to a valid IP address. This can occur with typos in the hostname, expired DNS records, or internal DNS configuration issues.

TLS/SSL Certificate Problems When using HTTPS endpoints, invalid, expired, or self-signed certificates can cause connection failures. OpenClaw may reject connections to endpoints with problematic certificates.

Proxy Configuration Mismatch If your environment requires a proxy for external connections, OpenClaw may not be configured to route traffic through that proxy, causing all external LLM calls to fail.

3. Step-by-Step Fix

Step 1: Verify Network Connectivity

First, confirm that your machine can reach the LLM endpoint at the network level:

# Test basic connectivity with ping
ping -c 4 api.openai.com

# Test TCP connectivity to the specific port
nc -zv api.openai.com 443

# Check DNS resolution
nslookup api.openai.com
dig api.openai.com

If these commands fail, you have a fundamental network connectivity issue that must be resolved before proceeding.

Step 2: Inspect OpenClaw Configuration

Examine your OpenClaw configuration file to verify the endpoint settings:

Before:

{
  "llm": {
    "provider": "openai",
    "endpoint": "https://ap1.openai.com/v1",
    "api_key": "sk-xxxx",
    "model": "gpt-4",
    "timeout": 30
  }
}

After:

{
  "llm": {
    "provider": "openai",
    "endpoint": "https://api.openai.com/v1",
    "api_key": "sk-xxxx",
    "model": "gpt-4",
    "timeout": 60
  }
}

Common fixes include correcting typos in the endpoint URL, ensuring the correct regional endpoint is specified, and increasing the timeout value for slower connections.

Step 3: Configure Proxy Settings (if required)

If your organization uses a proxy, configure OpenClaw to respect those settings:

# Set proxy environment variables
export HTTP_PROXY=http://proxy.company.com:8080
export HTTPS_PROXY=http://proxy.company.com:8080
export NO_PROXY=localhost,127.0.0.1

# Or configure in OpenClaw config file
export CLW_PROXY=http://proxy.company.com:8080

Alternatively, modify the OpenClaw configuration file:

{
  "network": {
    "proxy": "http://proxy.company.com:8080",
    "proxy_bypass": ["localhost", "127.0.0.1"]
  }
}

Step 4: Handle TLS/SSL Certificate Issues

For self-signed certificates or internal endpoints with certificate issues, configure OpenClaw to handle them appropriately:

# For development environments only - disable SSL verification
export CLW_SSL_VERIFY=false

# Or in configuration file
{
  "network": {
    "ssl_verify": false
  }
}

⚠️ Warning: Only disable SSL verification in trusted development environments. Never disable certificate verification in production.

If you need to add a custom CA certificate:

# Linux
export CLW_CA_CERT=/path/to/ca-bundle.crt

# macOS
export CLW_CA_CERT=/path/to/custom-ca.pem

# Windows
set CLW_CA_CERT=C:\path\to\ca-bundle.crt

Step 5: Verify LLM Service Status

Check the status of your LLM provider’s service health page:

# Example: Check OpenAI status
curl -s https://status.openai.com/api/v2/status.json

# Check if specific model is available
curl -X POST https://api.openai.com/v1/models \
  -H "Authorization: Bearer $OPENAI_API_KEY"

If the service is experiencing an outage, monitor the status page and wait for resolution.

Step 6: Test the Connection Directly

Use curl or a similar tool to test the LLM endpoint directly:

curl -v -X POST https://api.openai.com/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -d '{
    "model": "gpt-3.5-turbo",
    "messages": [{"role": "user", "content": "test"}],
    "max_tokens": 5
  }' \
  --max-time 60

This command provides verbose output that helps diagnose connection, authentication, and response issues.

4. Verification

After applying the fix, verify that OpenClaw can successfully connect to the LLM endpoint:

# Test the OpenClaw connection
clw doctor

# Test a simple LLM call
clw call "Hello, this is a test message"

# Check configuration is valid
clw config validate

# Verify endpoint connectivity
clw endpoint ping

Expected successful output:

[✓] Configuration validated successfully
[✓] LLM endpoint reachable at https://api.openai.com/v1
[✓] Authentication successful
[✓] Model gpt-4 is available

If you see [✓] LLM endpoint reachable, the clw-llm-unreachable error has been resolved.

For programmatic verification in your application:

from openclaw import OpenClawClient

client = OpenClawClient()
try:
    response = client.chat.complete(
        model="gpt-4",
        messages=[{"role": "user", "content": "test"}]
    )
    print(f"Connection successful: {response}")
except LLMConnectionError as e:
    print(f"Still experiencing connection issues: {e}")

5. Common Pitfalls

Regional Endpoint Mismatch OpenAI and other providers use region-specific endpoints. Using api.openai.com when you need api.us.openai.com (for Azure OpenAI US) will cause connection failures. Always use the exact endpoint provided for your account type.

Environment Variable Caching OpenClaw may cache configuration values. After changing environment variables, restart your shell session or explicitly reload the configuration:

source ~/.bashrc  # or equivalent for your shell
clw config reload

Firewall Blocking Outbound Connections Corporate firewalls often block outbound HTTPS traffic on non-standard ports. Ensure port 443 is open for your LLM endpoint. Some organizations require allowlisting specific domains.

Mixed HTTP/HTTPS Protocols If your configuration uses an HTTP endpoint for a provider that requires HTTPS, the connection will be rejected. Always verify the protocol requirements for your specific LLM provider.

Incorrect API Key Format Some providers require specific prefixes in API keys. Ensure your key matches the expected format. Using a deprecated or malformed key can cause connection errors that manifest as unreachable.

Timeout Too Short On slow networks or with large model responses, the default timeout may be insufficient. Increase the timeout in your configuration:

{
  "llm": {
    "timeout": 120,
    "connect_timeout": 30
  }
}

Container Networking in Docker If running OpenClaw inside Docker, the container’s network configuration must allow outbound connections. Use --network=host or properly configure Docker networking:

docker run --network=host openclaw/app

clw-config-invalid This error occurs when the OpenClaw configuration file contains syntax errors or invalid field values. Incorrect endpoint URLs often trigger this error before clw-llm-unreachable is encountered.

clw-api-timeout The LLM endpoint was reached, but the request took too long to receive a response. This differs from clw-llm-unreachable where the endpoint cannot be contacted at all. Increase the timeout value or investigate slow responses from the LLM service.

clw-model-not-found The connection to the LLM was successful, but the specified model does not exist or is not available in your account. This indicates valid network connectivity but an issue with model availability or access permissions.

clw-auth-invalid Authentication failed when attempting to connect to the LLM endpoint. While not the same as unreachable, an invalid API key can cause the provider to reject connections entirely, appearing similar to an unreachable endpoint.

clw-rate-limit-exceeded The LLM service has rate-limited your requests. High-volume usage can trigger this error, which may be mistaken for connection issues if the rate limit response is slow to return.

openclaw llm connection endpoint network api