Connecting OpenClaw to an OpenAI-Compatible AI Gateway

OpenClaw is a general-purpose agent tool: it doesn't ship with a hardcoded model provider, it expects you to point it at an OpenAI-compatible API. That's the same integration surface used by dozens of agent frameworks, CLIs, and IDE plugins, so the setup below applies well beyond OpenClaw itself — anywhere a tool asks for a "base URL" and an API key, this is the pattern.

This guide covers the two settings that matter (base URL and key), how to pick a model id, and the error codes you'll actually run into while wiring things up.

Why base URL + key is all you need

Most agent tools that speak "OpenAI-compatible" only need three things to work against any backend:

1. A base URL — where /chat/completions (and usually /models) actually lives.
2. An API key — sent as Authorization: Bearer <key>.
3. A model id — a string the backend recognizes.

If a gateway implements the same request/response shape as the OpenAI API, any tool built against that shape works against the gateway without code changes — you're not writing an integration, you're changing two config values. This is the whole idea behind an OpenAI-compatible AI gateway: your agent tool's code doesn't change, only the endpoint and key it's told to use.

That also means the setup is provider-agnostic. Once OpenClaw is pointed at a gateway, you can move between chat models from different underlying providers by changing the model string — no new SDK, no new auth flow, no code in OpenClaw itself.

Step 1: Get a base URL and an API key

Every OpenAI-compatible gateway distinguishes between two different endpoints:

• The gateway host — this is what actually serves /v1/chat/completions. It's what OpenClaw needs.
• The provider's dashboard/console — where you sign up, create keys, and check usage. This is a separate origin; it does not serve /v1 traffic itself.

Sign up, open the console, and create an API key. The full key (sk-…) is shown once — copy it into a secrets manager or environment variable immediately, since it won't be shown again. New accounts typically get some trial credit automatically, so you can run the first few requests without adding a payment method.

You'll also want the gateway's base URL, in the form https://<your-gateway-host>/v1. Keep both values as environment variables rather than pasting them into config files that might get committed:

export GATEWAY_BASE_URL="https://api.apiko.example/v1"
export GATEWAY_API_KEY="sk-..."

(Replace api.apiko.example with your actual deployment's gateway address — this is a placeholder host, not a real endpoint.)

Step 2: Point OpenClaw at the gateway

Where you enter these two values depends on how OpenClaw is configured in your setup — a config file, environment variables, or a settings screen, depending on version and deployment. What's consistent across all of them is the shape of the values: a base URL ending in /v1, and a bearer token.

If OpenClaw takes a config file, the fields typically map like this:

provider:
  base_url: https://api.apiko.example/v1
  api_key: ${GATEWAY_API_KEY}
  model: gpt-5.1

If it instead reads environment variables directly (common for OpenAI-compatible tools), the convention is usually:

export OPENAI_BASE_URL="https://api.apiko.example/v1"
export OPENAI_API_KEY="$GATEWAY_API_KEY"

Some tools use their own prefix instead of OPENAI_* — check OpenClaw's docs for the exact variable names it reads. The values themselves don't change: gateway base URL, gateway key.

Verifying the connection outside of OpenClaw first

Before debugging inside an agent tool's UI (which can obscure the actual HTTP error), confirm the gateway responds correctly with a plain curl call:

curl "$GATEWAY_BASE_URL/chat/completions" \
  -H "Authorization: Bearer $GATEWAY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.1",
    "messages": [{"role": "user", "content": "Hello"}]
  }'

A successful response looks like a standard OpenAI chat completion object — choices[0].message.content populated, a usage block with token counts. If that works, any failure inside OpenClaw is a config mismatch (wrong variable name, wrong base URL path, stale key), not a gateway problem. If it doesn't work, the error codes below tell you what to fix.

Step 3: Pick a model id

The model string in your request has to match an id the gateway actually serves — not a name that "should" work. Don't guess a model id from memory or from another provider's docs; pull the current list from the gateway's models endpoint, which returns the ids you're allowed to call along with live per-token pricing:

curl "$GATEWAY_BASE_URL/models" \
  -H "Authorization: Bearer $GATEWAY_API_KEY"

Or browse the catalog in a browser at /models, which lets you filter by provider and capability and shows the same prices used for billing. Set OpenClaw's model field to whatever id you copy from there — the full reference for request/response shape, streaming, and available fields lives in /docs.

Common errors and how to fix them

Once OpenClaw is wired up, most failures fall into a small set of HTTP status codes. Check these before assuming it's a bug in OpenClaw itself:

| Status | Meaning | Fix | |---|---|---| | 401 | API key missing or invalid | Confirm the Authorization: Bearer header is actually being sent — some tools silently drop it if the env var name doesn't match what they expect. Check the key hasn't been revoked. | | 402 / 403 | Insufficient balance | Your account balance is too low for the request. Top up in the console, then retry. | | 404 | Model or route not found | The model string doesn't match an id currently served — re-check against /models. Also verify the base URL path ends in /v1 and that you're calling /chat/completions, not a different path. | | 429 | Rate limited | Back off and retry with exponential backoff. This is usually about request pace, not account status. | | 5xx | Upstream failure | The gateway retries across channels automatically. If it still fails, the request is not billed — the pre-hold is refunded. Retry the call; if it persists, check the status page. |

If OpenClaw reports a generic "request failed" without surfacing the status code, enable verbose/debug logging in OpenClaw (or fall back to the curl test above) to see the actual HTTP response — the message body from the gateway usually names the exact field that's wrong.

Streaming responses

If OpenClaw streams tokens as they arrive, make sure stream: true is set on the request (OpenClaw usually handles this automatically once the base URL/key are configured, but worth checking if output appears all at once instead of incrementally). Requesting stream_options: {"include_usage": true} gets you a final chunk with real token usage — useful if you're trying to reconcile what a given OpenClaw run actually cost.

Wrapping up

The pattern here isn't specific to OpenClaw — any OpenAI-compatible agent tool takes the same two inputs (base URL, key) and the same debugging path (test with curl first, then check the status code table). Once it's wired up, switching models is a one-line change, not a new integration.

New accounts get trial credit automatically at signup, so you can run the setup above and make a few real calls before deciding on anything. Check /pricing for current per-model rates once you're ready to plan usage at scale.