Fix: Embedded Agent Times Out on Local OpenAI-Compatible LLM

The OpenClaw embedded agent times out trying to connect to your local OpenAI-compatible LLM server — even when a direct curl call to the same endpoint succeeds from your terminal. This is almost always a binding, network resolution, or model configuration issue inside the gateway process rather than a problem with your LLM server itself.

Step 1: Test Reachability from the Gateway Process

The embedded agent makes HTTP requests from within the gateway process. Test that the endpoint is reachable using the same network path:

# Does it respond at all?
curl -s http://localhost:1234/v1/models

# Test from Node.js (same stack as OpenClaw)
node -e "fetch('http://localhost:1234/v1/models').then(r=>r.json()).then(d=>console.log(JSON.stringify(d.data?.length,'  '),'models')).catch(e=>console.error('FAIL:',e.cause?.code))"

Step 2: Ensure Your LLM Server Binds to the Right Address

Some LLM servers bind only to 127.0.0.1 by default. If the OpenClaw gateway runs in a container or with a different network namespace, localhost may resolve differently. Bind your LLM server explicitly to 0.0.0.0 or use the exact IP:

# LM Studio: set listen address in settings to 0.0.0.0

# llama.cpp server
./server --host 0.0.0.0 --port 1234 -m model.gguf

# vLLM
python -m vllm.entrypoints.openai.api_server   --host 0.0.0.0 --port 8000 --model mistralai/Mistral-7B-v0.1

Step 3: Configure Local Provider in openclaw.json

{
  "model": "local/mistral-7b",
  "providers": {
    "local": {
      "baseUrl": "http://127.0.0.1:1234/v1",
      "apiKey": "not-needed"
    }
  },
  "embedded": {
    "timeout": 120000,
    "preferLocal": true
  }
}

Step 4: Increase the Embedded Agent Timeout

Large models running on CPU can take 30–120 seconds to respond. The default timeout is 30 seconds. Increase it to match your hardware:

{
  "embedded": {
    "timeout": 300000
  }
}

Or pass it on the command line:

openclaw agent --agent sage --local --timeout 300 --message "Hello"

Step 5: Disable Cloud Failover

If you want to use only the local LLM and have the agent fail rather than fall back to a cloud model:

{
  "embedded": {
    "preferLocal": true,
    "allowCloudFallback": false
  }
}