openclaw - 💡(How to fix) Fix [Feature]: GPT4Free (g4f) OpenAI-Compatible Backend + Fallback & Proxy Support

Summary

Add optional GPT4Free (g4f) OpenAI-compatible backend support with built-in fallback and per-provider proxy routing for improved reliability in agent execution. https://github.com/xtekky/gpt4free

Problem to solve

OpenClaw agents depend on external LLM backends for reasoning and task execution. In practice, this creates a single point of failure:

If a provider is rate-limited, blocked, or unstable, agent execution fails mid-workflow Users in restricted regions cannot reliably access major APIs There is no built-in fallback mechanism to continue execution using alternative models Proxy routing is not supported per provider, limiting access in blocked environments

This leads to brittle agent behavior where long-running tasks fail even though alternative inference sources (like local OpenAI-compatible servers such as g4f) are available.

Proposed solution

Introduce optional OpenAI-compatible backend support with a g4f preset, plus lightweight resilience features.

1. g4f backend preset (OpenAI-compatible) { "provider": "openai_compatible", "api_base": "http://127.0.0.1:1337/v1", "model": "gpt-4o-mini", "api_key": "dummy" }
2. Optional g4f mode (explicit preset) { "provider": "g4f", "api_base": "http://127.0.0.1:1337/v1", "model_priority": [ "gpt-4o-mini", "claude-3-haiku", "deepseek-chat" ] }
3. Proxy support (critical for reliability) { "proxy": "socks5://127.0.0.1:1080" }
4. Lightweight fallback behavior

If a request fails:

retry once on same model switch to next model in priority list optionally fallback to local model

No orchestration layer required—just deterministic failover.

Alternatives considered

Manual switching between providers in config → works but not reliable for long-running agents Full multi-provider orchestration system → too heavy for OpenClaw’s minimal design External proxy tools only → does not solve model-level fallback or agent continuity

Impact

Affected users/systems:

OpenClaw agent runtime (core execution loop) users running long autonomous workflows users in restricted or high-latency regions developers using local-first or low-cost setups

Severity:

Medium → High (can fully break agent runs mid-task)

Frequency:

Intermittent but common in real-world usage (rate limits, network blocks, provider outages)

Consequences:

failed or partially completed agent workflows manual restart and re-prompting of tasks inability to run long autonomous chains reliably reduced usability in non-US / restricted environments

Evidence/examples

OpenAI-compatible servers like g4f already expose /v1/chat/completions interfaces Many OpenClaw deployments already rely on switching models manually when failures occur Real-world agent workflows are frequently interrupted due to provider rate limits or blocking Proxy-based access is commonly required in restricted networks

(Industry pattern: OpenAI-compatible abstraction is already standard across tools like Ollama / vLLM / LM Studio ecosystems.)

Additional information

This proposal is intentionally minimal and aligns with OpenClaw’s philosophy:

No new orchestration framework No dependency on external router services Only a thin compatibility layer for OpenAI-style endpoints Optional feature flags only

Goal is to make OpenClaw more resilient in real deployments, especially for autonomous multi-step agents where provider failure currently breaks execution entirely, want everything free