ClawRouter

ClawRouter gives OpenClaw one policy-scoped key for multiple upstream model providers. The bundled clawrouter plugin discovers only the models allowed for that key, routes each model through its declared protocol, and reports the key's budget and aggregate usage on OpenClaw usage surfaces.

Upstream credentials and provider-specific forwarding stay in ClawRouter, so you never install or authenticate each upstream provider plugin on the OpenClaw host. The plugin ships bundled with OpenClaw (enabledByDefault: true); you only need an issued ClawRouter credential.

Getting started

`clawrouter` is bundled and enabled by default. If your configuration sets
`plugins.allow`, add `clawrouter` to that list before enabling it. For a
custom deployment, set `models.providers.clawrouter.baseUrl` to the
ClawRouter origin; the default is `https://clawrouter.openclaw.ai`.

Use the returned model refs exactly as shown. They retain the upstream
namespace, such as `clawrouter/openai/gpt-5.5`,
`clawrouter/anthropic/claude-sonnet-4-6`, or
`clawrouter/google/gemini-3.5-flash`. If `agents.defaults.models` is an
allowlist in your configuration, add each selected ClawRouter ref to it.

You can also select a returned model for one run with
`openclaw agent --model clawrouter/<provider>/<model> --message "..."`.

Model discovery

GET /v1/catalog returns { providers: [...] }, where each provider entry lists its own models[] (with upstream id, capabilities, and pricing) and its supported request routes. OpenClaw does not ship a second, fixed list of ClawRouter models. A catalog model is advertised as an OpenClaw model when:

• the credential's policy grants its provider;
• the catalog model advertises a supported LLM capability (llm.responses, llm.chat, llm.messages, or llm.stream with a matching streaming route); and
• the provider exposes a matching route for one of the transports below.

Adding a model to a supported ClawRouter provider needs no OpenClaw release: the next catalog refresh (cached 60 seconds per credential scope) discovers it. A model that needs a new wire protocol requires plugin support first.

Protocol and provider plugins

ClawRouter owns upstream credentials; its catalog tells OpenClaw which transport to use, so you never install every upstream company's auth plugin.

The plugin also applies the matching replay and tool-schema policies for those families (OpenAI/DeepSeek/Gemini tool-schema compat; native Anthropic and Google Gemini replay policies). A catalog provider exposing only an unsupported request format is intentionally not advertised as an OpenClaw text model. Normalize those providers to one of the supported contracts in ClawRouter rather than sending an incompatible payload.

Quotas and usage

ClawRouter's /v1/usage response feeds the normal OpenClaw provider-usage surfaces: request, token, and spend totals, plus a monthly budget window when the key has a limit. Unmetered keys still show aggregate usage without a percentage window.

Quota lookup uses the same scoped key as model discovery. A failed quota lookup does not block model execution.

Check the live snapshot with:

openclaw status --usage
openclaw models status

The same provider snapshot is available to /status in chat and OpenClaw's usage UI. The budget is policy-wide, so requests made by another client using the same ClawRouter policy can change the remaining percentage.

Troubleshooting

Security behavior

• Catalog discovery is scoped to the configured proxy key and cached per credential scope (agent dir, workspace dir, auth profile id, and base URL).
• The proxy key is attached only at request dispatch; it is not stored in model metadata.
• Native Anthropic and Gemini model ids are rewritten to their upstream ids only at dispatch.
• Unsupported or ungranted catalog rows fail closed and are not selectable.

Related