Complete Guide to Troubleshooting OpenClaw API Connection Errors

Introduction

OpenClaw needs to communicate with the APIs of various AI model providers. During use, you may encounter various connection errors. This article systematically covers the causes and solutions for each type of error, helping you quickly identify and resolve issues.

1. Quick Diagnostic Tools

Before troubleshooting, start with OpenClaw's built-in diagnostic tools:

# Run comprehensive diagnostics
openclaw doctor

# Check real-time logs for errors
openclaw logs | grep -i "error\|fail\|timeout"

# Test API connection
curl -v https://api.anthropic.com/v1/messages \
  -H "x-api-key: YOUR_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{"model":"claude-sonnet-4-20250514","max_tokens":10,"messages":[{"role":"user","content":"hi"}]}'

2. HTTP Error Codes Explained

2.1 401 Unauthorized -- Authentication Failed

Symptoms:

Error: API request failed with status 401: Invalid API key

Causes and Solutions:

# Check the API Key in the configuration file
cat ~/.config/openclaw/openclaw.json5 | grep -i "key\|token"

# Ensure Key format is correct (for Anthropic, it should start with sk-ant-)
# Restart after updating
openclaw restart

2.2 403 Forbidden -- Permission Denied

Symptoms:

Error: API request failed with status 403: Permission denied

Common Causes:

• API Key lacks access to the requested model
• Account has not been granted access to certain models (e.g., Claude Opus)
• IP address is blocked by the API provider
• Your region is outside the service area

# Check if it's an IP restriction issue
curl -s https://api.anthropic.com/v1/messages \
  -H "x-api-key: $API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -w "\n%{http_code}" 2>&1

# If using a proxy, verify the proxy configuration
echo $HTTP_PROXY
echo $HTTPS_PROXY

2.3 429 Too Many Requests -- Rate Limit

Symptoms:

Error: Rate limit exceeded. Please retry after 30 seconds.

Rate limit reference by provider:

Solution:

// ~/.config/openclaw/openclaw.json5
{
  "rateLimiting": {
    // Global request interval (milliseconds)
    "minInterval": 1000,
    // Retry strategy when rate limited
    "retry": {
      "enabled": true,
      "maxRetries": 3,
      "backoffMultiplier": 2,
      "initialDelay": 5000
    }
  }
}

2.4 500 Internal Server Error

How to handle:

# This is usually a provider-side issue; check their status pages
# Anthropic: https://status.anthropic.com
# OpenAI: https://status.openai.com

# Configure automatic fallback to a backup model

// ~/.config/openclaw/openclaw.json5
{
  "models": {
    "primary": {
      "provider": "anthropic",
      "model": "claude-sonnet-4-20250514"
    },
    "fallback": {
      "provider": "openai",
      "model": "gpt-4o"
    }
  }
}

2.5 502/503 Bad Gateway / Service Unavailable

Symptoms:

Error: 502 Bad Gateway
Error: 503 Service Unavailable - The server is temporarily overloaded

Troubleshooting steps:

# 1. Confirm whether it's a provider service outage
curl -s -o /dev/null -w "%{http_code}" https://api.anthropic.com/v1/messages

# 2. Check if local network is working
ping api.anthropic.com
traceroute api.anthropic.com

# 3. If using a reverse proxy, check whether it's functioning properly
nginx -t
systemctl status nginx

3. Timeout Troubleshooting

3.1 Connection Timeout

Error: connect ETIMEDOUT 104.18.0.1:443

# Test connectivity to the API endpoint
curl -v --connect-timeout 10 https://api.anthropic.com/v1/messages

# If connection times out, you may need to configure a proxy

// ~/.config/openclaw/openclaw.json5
{
  "proxy": {
    "enabled": true,
    "url": "http://127.0.0.1:7890",
    // Or use a SOCKS5 proxy
    // "url": "socks5://127.0.0.1:1080"
  },
  "timeout": {
    "connect": 30000,    // Connection timeout: 30 seconds
    "request": 120000    // Request timeout: 120 seconds
  }
}

3.2 Request Timeout

When the model generates long text, it may exceed the default timeout:

// Increase the timeout
{
  "timeout": {
    "request": 300000  // 5 minutes
  }
}

4. DNS Resolution Failures

Symptoms:

Error: getaddrinfo ENOTFOUND api.anthropic.com
Error: querySrv ESERVFAIL _http._tcp.api.openai.com

Solutions:

# 1. Check DNS resolution
nslookup api.anthropic.com
dig api.anthropic.com

# 2. Try using public DNS servers
echo "nameserver 8.8.8.8" | sudo tee /etc/resolv.conf
echo "nameserver 1.1.1.1" | sudo tee -a /etc/resolv.conf

# 3. Manually add hosts entry (temporary fix)
echo "104.18.0.1 api.anthropic.com" | sudo tee -a /etc/hosts

# 4. Test resolution after the fix
nslookup api.anthropic.com

5. SSL Certificate Errors

Symptoms:

Error: unable to verify the first certificate
Error: self signed certificate in certificate chain
Error: CERT_HAS_EXPIRED

Troubleshooting and Solutions:

# 1. Check certificate information
openssl s_client -connect api.anthropic.com:443 -servername api.anthropic.com </dev/null 2>/dev/null | openssl x509 -noout -dates

# 2. Update system CA certificates
# Ubuntu/Debian
sudo apt update && sudo apt install -y ca-certificates
sudo update-ca-certificates

# CentOS/RHEL
sudo yum install -y ca-certificates
sudo update-ca-trust

# 3. If it's a man-in-the-middle certificate issue from a proxy
# Add the proxy's CA certificate to the Node.js trust list
export NODE_EXTRA_CA_CERTS=/path/to/proxy-ca.crt

Warning: Never set NODE_TLS_REJECT_UNAUTHORIZED=0 in production. This completely disables SSL verification and poses a serious security risk.

6. Proxy Configuration Issues

6.1 HTTP Proxy

// ~/.config/openclaw/openclaw.json5
{
  "proxy": {
    "enabled": true,
    "url": "http://127.0.0.1:7890"
  }
}

6.2 Environment Variable Method

# Set in the system environment
export HTTP_PROXY=http://127.0.0.1:7890
export HTTPS_PROXY=http://127.0.0.1:7890
export NO_PROXY=localhost,127.0.0.1

# Restart OpenClaw
openclaw restart

6.3 Proxy Connectivity Testing

# Test API access through the proxy
curl -x http://127.0.0.1:7890 -v https://api.anthropic.com/v1/messages

# Test SOCKS5 proxy
curl -x socks5://127.0.0.1:1080 -v https://api.anthropic.com/v1/messages

7. Provider-Specific Troubleshooting

7.1 Anthropic (Claude)

# Verify API Key validity
curl https://api.anthropic.com/v1/messages \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{"model":"claude-sonnet-4-20250514","max_tokens":5,"messages":[{"role":"user","content":"test"}]}'

Common issue: The API Key format is sk-ant-api03-.... Be careful not to confuse it with an OpenAI Key.

7.2 OpenAI (GPT)

# Verify API Key
curl https://api.openai.com/v1/chat/completions \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"gpt-4o","messages":[{"role":"user","content":"test"}],"max_tokens":5}'

Common issue: After free credits are exhausted, a 429 error is returned. You need to add a payment method.

7.3 Ollama (Local Models)

# Check if the Ollama service is running
curl http://localhost:11434/api/tags

# Confirm the model has been downloaded
ollama list

# Test model invocation
curl http://localhost:11434/api/generate \
  -d '{"model":"llama3","prompt":"test","stream":false}'

Common issue: Ollama listens on localhost by default. If OpenClaw is on a different machine, set OLLAMA_HOST=0.0.0.0.

7.4 OpenRouter

curl https://openrouter.ai/api/v1/chat/completions \
  -H "Authorization: Bearer $OPENROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"anthropic/claude-sonnet-4-20250514","messages":[{"role":"user","content":"test"}]}'

8. Error Troubleshooting Checklist

When encountering API connection errors, troubleshoot in the following order:

1. ✅ Run openclaw doctor to view diagnostic results
2. ✅ Confirm the API Key is correct and not expired
3. ✅ Check network connectivity (ping, curl)
4. ✅ Verify proxy configuration is correct (if using a proxy)
5. ✅ Check whether DNS resolution is working
6. ✅ Verify SSL certificates are valid
7. ✅ Check the provider's service status page
8. ✅ Check if rate limits have been triggered
9. ✅ Review detailed error messages in openclaw logs
10. ✅ Try calling the API directly with curl to rule out OpenClaw itself as the issue

With these troubleshooting techniques, you can quickly identify and resolve the vast majority of API connection issues, keeping your OpenClaw service running smoothly.