Fix clw-llm-failure: OpenClaw LLM service connection or inference failure error

Tue, 01 Oct 2024 00:00:00 +0000

1. Symptoms

The clw-llm-failure error in OpenClaw manifests during LLM inference calls. Common indicators:

Console output: ERROR: clw-llm-failure: Failed to invoke LLM endpoint: [detailed message, e.g., 'HTTP 503 Service Unavailable']
Application halts on ClawLLM::infer() or clw_llm_generate().
HTTP status codes in logs: 429 (rate limit), 500 (internal server error), or connection refused.
No response payload; partial traces show successful init but failure on /v1/completions POST.

Example log snippet:

[2024-10-01T12:00:00Z] INFO: ClawLLM init with model=gpt-4o-mini, endpoint=https://api.openai.com/v1
[2024-10-01T12:00:01Z] ERROR: clw-llm-failure: Request to LLM failed. Code: -32603, Message: Internal JSON-RPC error.
[2024-10-01T12:00:01Z] FATAL: Inference aborted. Retries exhausted: 3/3
---

Runtime symptoms include:
- Spikes in CPU usage during retries.
- Increased latency (>10s per call).
- Docker containers restarting if using Claw in containerized envs.

This error blocks all downstream LLM-dependent pipelines, such as RAG systems or chatbots built on OpenClaw.

## 2. Root Cause

`clw-llm-failure` triggers when OpenClaw's ClawLLM client cannot complete an inference request. Core causes:

1. **Network/Connectivity**: Firewall blocks, DNS resolution fails, or proxy misconfig. OpenClaw uses HTTP/2 to LLM providers (OpenAI, Anthropic, etc.).
2. **Authentication**: Invalid/missing `CLAW_LLM_API_KEY` or expired tokens.
3. **Provider-Side Issues**: Model overload (e.g., GPT-4 rate limits), endpoint downtime, or unsupported model names.
4. **Configuration Mismatch**: Incorrect `base_url`, `model_id`, or payload format (e.g., missing `temperature` in JSON).
5. **Resource Exhaustion**: Local timeouts (<30s default), memory leaks in multi-threaded calls.
6. **JSON-RPC Parsing**: Malformed responses from LLM API not handled by ClawLLM v2.1+.

Inspect via `claw_debug --llm` flag for traces. Root cause often correlates with `curl -v` tests to the endpoint.

## 3. Step-by-Step Fix

Resolve `clw-llm-failure` systematically. Start with basics, escalate to code changes.

### Step 1: Verify Environment
```bash
# Check API key and endpoint
echo $CLAW_LLM_API_KEY | wc -c # >30 chars expected
curl -H "Authorization: Bearer $CLAW_LLM_API_KEY" https://api.openai.com/v1/models

Step 2: Update ClawLLM Config

Set robust defaults in claw_config.toml:

Api-Failure on ErrorVault — Developer Error Code Dictionary

Fix clw-llm-failure: OpenClaw LLM service connection or inference failure error

1. Symptoms

Step 2: Update ClawLLM Config