Integration Guide

OpenClaw + OrcaRouter: One Endpoint, Several Upstream Models

Q: Is OrcaRouter the same as OpenRouter?

No. OrcaRouter and OpenRouter are separate services with different accounts, keys, catalogs and pricing. A key from one does not work on the other.

Q: What base URL should I use?

Use https://api.orcarouter.ai/v1 unless your account is assigned a different endpoint. Enter the base URL only, without the /chat/completions path.

Q: How do I stop the model ID leaking into every config?

Use openclaw models aliases add to give the route a stable local name, so changing the underlying model later is a single edit.

Q: Does routing through OrcaRouter make models cheaper or free?

No. Cost and permitted usage are determined by the upstream provider and its terms. A router changes routing, not pricing or permissions.

OrcaRouter puts multiple upstream providers behind a single OpenAI-compatible endpoint. OpenClaw consumes that endpoint through its openai provider slot, which makes the setup short — and makes the model ID the thing most likely to trip you up.

How the route works

OpenClaw → https://api.orcarouter.ai/v1 → OrcaRouter → selected provider/model

OpenClaw sends a standard chat-completions request. OrcaRouter authenticates it, maps the requested model to a route, and returns an OpenAI-compatible response. Availability, logging, pricing and provider policy all come from OrcaRouter and whatever sits upstream of it — adding a router does not change the terms you agreed to with the underlying provider.

Read this before you start: it is not OpenRouter

OrcaRouter and OpenRouter are unrelated services with confusingly similar names. Separate accounts, separate keys, separate catalogs. The usual symptom of mixing them up is a 401 that looks like a broken key, when in fact the key is fine and pointed at the wrong service.

Collect three values

Base URL — https://api.orcarouter.ai/v1, base only.
API key — created in your own OrcaRouter account.
Model ID — copied from OrcaRouter's current catalog or its models response. Do not guess the spelling; router model IDs are versioned independently of the upstream provider's own naming.

Configure OpenClaw

OrcaRouter speaks OpenAI's wire format, so this is the openai provider with a custom base URL rather than a new provider type:

{
  "models": {
    "providers": {
      "openai": {
        "baseUrl": "https://api.orcarouter.ai/v1",
        "apiKey": "YOUR_ORCAROUTER_KEY"
      }
    }
  },
  "agents": {
    "defaults": {
      "model": {
        "primary": "openai/EXACT_MODEL_ID"
      }
    }
  }
}

Note the openai/ prefix on the primary model: OpenClaw addresses a model as provider-slash-id, and the provider here is openai even though nothing OpenAI-operated is involved. That surprises people who expect to write orcarouter/....

Set and inspect it from the CLI

openclaw models list                     # what is configured
openclaw models set openai/EXACT_MODEL_ID  # set the default model
openclaw models status                   # confirm what will actually be used

models set takes the model id or an alias as a required argument — running it bare prints usage rather than changing anything.

models status is the one worth running after any change. A config edit that fails validation leaves the previous model in place, and the agent keeps answering perfectly well on it, so a working reply is not evidence your change took effect.

Give the route an alias

openclaw models aliases add router openai/EXACT_MODEL_ID
openclaw models aliases list
openclaw models set router

models aliases on its own is only the parent command; the subcommands that do the work are add, list and remove.

Aliases are the reason to prefer OpenClaw's CLI over hand-editing here. Point an alias at the router route and reference the alias everywhere else; when you later change what the route resolves to, you edit one thing instead of hunting through agent configs.

Switching back later

Remove the stale override. If you move back to a direct provider, delete the custom baseUrl as well as the key. A leftover baseUrl on the openai provider silently keeps routing every request through OrcaRouter even after you have swapped in an OpenAI key, and the resulting model-not-found errors look like a catalog problem.

When a router is the wrong tool

If you use one provider, a direct BYOK connection has fewer moving parts and a smaller credential surface. Add a router when you specifically need routing, fallback or consolidated usage visibility — not on the assumption that an extra hop improves answer quality. It does not.

On OpenClaw Launch, save the base URL and key in the Custom API Provider card, then set the instance model to the exact OrcaRouter ID once the key saves.

OpenClaw and OrcaRouter FAQ

Can OpenClaw use OrcaRouter?

Yes. OrcaRouter exposes an OpenAI-compatible API, so OpenClaw connects through the openai provider with a custom baseUrl rather than needing a dedicated provider integration.

Is OrcaRouter the same as OpenRouter?

No. They are separate services with different accounts, keys, model catalogs, pricing and availability. The similar names cause real mistakes — a key from one will never work on the other. See the OpenRouter guide if that is what you meant.

What base URL should I use?

https://api.orcarouter.ai/v1 unless OrcaRouter's current documentation assigns a different endpoint to your account. Enter the base URL only — not the /chat/completions path.

How do I stop the model ID leaking into every config?

Use an alias. openclaw models aliases add <alias> <model> gives the route a stable local name, so changing what sits behind it later is one edit rather than one per agent.

Does routing through OrcaRouter make models cheaper or free?

No guarantee. Cost and permitted usage come from the upstream provider and its terms. A router changes where the request goes, not what the provider charges or allows.