Self-Hosted AI API Compatibility Matrix for OpenClaw

If you run OpenClaw against self-hosted or proxy AI backends, the most useful question is not:

Is this backend OpenAI-compatible?

It is:

Which parts of the runtime does it actually support?

That distinction matters because many integrations are compatible only at the basic chat layer. They answer a simple curl request, maybe even pass openclaw models status --probe, and then fail the moment OpenClaw sends a fuller runtime payload.

This page is meant to be the high-level map you can use before choosing a backend and while debugging one.

If you are still choosing an architecture, start with /guides/choose-local-ai-api-path-for-openclaw first. If your backend is already live behind LiteLLM, NewAPI, OneAPI, or another proxy, keep /guides/openclaw-relay-and-api-proxy-troubleshooting next to this matrix so the topic cluster stays ordered: choose the path, classify the compatibility boundary, then debug the transport details.

If you are already seeing concrete errors, start with these symptom pages too:

• /troubleshooting/solutions/api-works-in-curl-but-openclaw-fails
• /troubleshooting/solutions/custom-openai-compatible-endpoint-rejects-tools
• /troubleshooting/solutions/custom-provider-reasoning-breaks-openai-compatible
• /troubleshooting/solutions/openai-compatible-endpoint-rejects-stream-or-store
• /troubleshooting/solutions/local-openai-compatible-tool-calling-compatibility

What this guide helps you finish

By the end of this guide, you should be able to:

• classify the backend path you are actually testing,
• decide which compatibility layer matters for your use case,
• choose a safe default expectation before enabling tools or reasoning features,
• verify whether a backend is truly ready for OpenClaw runtime behavior.

Who this is for (and not for)

Use this guide if you are:

• comparing Ollama, llama.cpp, vLLM, LiteLLM, or another relay/proxy path,
• debugging a backend that works in curl but feels flaky in OpenClaw,
• trying to decide how much trust to place in an “OpenAI-compatible” label.

This is not a full provider setup guide. Use it as a decision-and-verification map, then jump into the deeper setup or troubleshooting page that matches your chosen path.

Before you test a backend: collect these four facts

Before you probe anything, confirm:

1. which server or proxy layer you are really talking to,
2. which model and endpoint path you expect OpenClaw to use,
3. whether your actual requirement is plain chat, tools, multi-turn continuation, reasoning, or streaming,
4. what evidence will prove success beyond one happy-path response.

If you skip that setup, you end up proving the wrong layer and calling the whole stack compatible too early.

The Core Judgment

For OpenClaw, “OpenAI-compatible” should be treated as a starting clue, not a guarantee.

In practice, compatibility is layered:

1. Reachability — the URL, auth, and basic request all work.
2. Contract shape — the backend actually implements the API mode you selected.
3. Runtime features — tools, reasoning, streaming, and multi-turn continuation behave correctly.
4. Session durability — later turns keep working after tool results, retries, and long-lived context.

Most painful integrations fail at layers 3 and 4.

A Simpler Way to Think About Backends

Instead of asking whether a backend is “supported,” ask which bucket it belongs to.

Bucket A: Native backend APIs

Examples:

• native Ollama API

Strengths:

• usually the clearest expectation boundary,
• fewer translation layers,
• less ambiguity about which fields are truly supported.

Weaknesses:

• not always interchangeable with other OpenAI-style tooling,
• may require provider-specific setup or behavior expectations.

Bucket B: Local or hosted OpenAI-compatible servers

Examples:

• Ollama /v1
• llama.cpp server /v1
• vLLM OpenAI-compatible server

Strengths:

• familiar endpoint shape,
• easy to test with curl and generic clients,
• works well for basic chat in many setups.

Weaknesses:

• tool calling quality and multi-turn tool-result behavior vary a lot,
• some fields are only partially supported,
• “works in playground” often does not mean “works for agent runtime.”

Bucket C: Proxy / relay / unification layers

Examples:

• LiteLLM
• NewAPI / OneAPI / AnyRouter
• custom OpenAI-compatible relays

Strengths:

• centralize auth, routing, billing, and vendor abstraction,
• can simplify multi-provider operations.

Weaknesses:

• introduce another translation layer,
• can hide real provider errors,
• may support only a subset of modern runtime semantics.

That is why this bucket should almost always be read together with /guides/openclaw-relay-and-api-proxy-troubleshooting, not in isolation.

Compatibility Matrix

The matrix below is deliberately practical rather than absolute. It describes the default expectation boundary most operators should assume before they have validated their own stack.

A useful rule of thumb:

• the more translation layers between OpenClaw and the underlying model,
• the more conservative you should be about tools, reasoning, and later-turn agent flows.

Feature Matrix: What Breaks Most Often

1) Basic chat

Usually the first thing to work.

A backend that supports:

• messages,
• a model id,
• auth,
• and a normal assistant reply,

can often pass both curl and openclaw models status --probe.

This is the layer that creates false confidence.

2) Tools

This is where “OpenAI-compatible” starts to diverge.

Common failure modes:

• backend rejects tools,
• backend accepts tools but rejects tool_choice,
• backend emits tool call JSON into plain text instead of the expected structure,
• backend supports one-shot tool calls but not later-turn continuation.

3) Tool-result continuation

This is the most underappreciated compatibility boundary.

A backend can appear tool-capable and still fail when OpenClaw sends:

• a tool result,
• a later assistant turn,
• or a longer multi-turn transcript containing tool-use history.

This is a major reason why “first turn worked” is not enough evidence.

4) Reasoning controls

Reasoning capability and reasoning-control compatibility are different things.

A model may be able to reason while the transport layer rejects fields such as:

• reasoning_effort,
• provider-specific thinking flags,
• or translated reasoning payloads passed through a relay.

5) Streaming

Some backends can stream in a way that works for generic clients but not for the runtime behavior OpenClaw expects.

Typical outcomes:

• blank output,
• vague 400-style errors,
• or a provider that only appears reliable in non-streaming manual tests.

6) Error transparency

Proxy layers can make diagnosis harder by returning:

• vague “no body” errors,
• rewrapped provider failures,
• or transport errors that hide the original unsupported field.

That is not a minor inconvenience. It changes your debugging strategy.

The Safest Integration Strategy

If you are bringing a new self-hosted or proxy API into OpenClaw, use this sequence.

Step 1: Prove reachability

Use:

openclaw models status --probe

and a minimal manual request.

Step 2: Prove plain chat agent runtime

If the backend is custom or uncertain, start with conservative assumptions:

• reasoning: false
• compat.supportsTools: false

That tests whether OpenClaw can complete a real run as plain chat.

Step 3: Add advanced features gradually

Only after plain chat is stable should you test:

• tools,
• multi-turn tool-result loops,
• reasoning controls,
• streaming-specific expectations.

Step 4: Keep evidence at the field level

When an integration fails, ask:

• which request path worked,
• which request path failed,
• and which extra fields appeared in the failing request.

That shortens debugging dramatically.

Which Errors Usually Point to Which Layer?

curl works, but OpenClaw fails

Most likely:

• runtime payload mismatch,
• not a base URL problem anymore.

Probe works, but TUI or openclaw agent fails

Most likely:

• tools,
• reasoning,
• streaming,
• or multi-turn continuation mismatch.

First turn works, later turns fail after a tool call

Most likely:

• tool-result continuation problem,
• or server/chat-template incompatibility.

Template errors like Unexpected message role

Most likely:

• local server wrapper or chat-template limitation,
• not a key or auth problem.

“Unknown field” / store / stream style errors

Most likely:

• partial implementation of a nominally OpenAI-compatible contract.

Verification checklist after you pick a backend path

Before you trust a backend in production, verify:

• reachability and auth from the same runtime that OpenClaw actually uses,
• one plain-chat run through OpenClaw, not just a manual curl,
• one feature-specific run for the thing you actually care about most (tools, streaming, reasoning, or continuation),
• one repeated run after a tool result or retry path if your workflow depends on durability.

A backend is not “good enough” because it answered once. It is good enough when it survives the layer that matters to your workflow.

Recommended Default Choices

If you need a practical default stance:

• choose the most native path available when you care about advanced agent behavior,
• choose OpenAI-compatible local or proxy paths when you primarily need broad client interoperability,
• and assume tools/reasoning/streaming must be proven, not assumed.

That approach is less glamorous than “everything is OpenAI-compatible now,” but it matches how users actually get burned in production.

Related Guides

• Relay and proxy troubleshooting: /guides/openclaw-relay-and-api-proxy-troubleshooting
• Configuration basics: /guides/openclaw-configuration
• Choosing a local or proxy API path: /guides/choose-local-ai-api-path-for-openclaw