ClawRouter: Unified Credential for OpenClaw Model Providers

ClawRouter provides OpenClaw with a single policy-scoped key that works across multiple upstream model providers. The bundled clawrouter plugin only surfaces the models permitted for that key, routes every model through its designated protocol, and exposes the key's budget along with aggregate usage on OpenClaw usage surfaces.

Provider-specific forwarding and upstream credentials remain managed by ClawRouter, which means you never have to install or authenticate each upstream provider plugin on the OpenClaw host. This plugin comes bundled with OpenClaw (enabledByDefault: true); all you need is a ClawRouter credential that has been issued to you.

Getting started

Get a scoped credential

Request a credential from your ClawRouter administrator whose policy covers the providers, models, and monthly budget you intend to use. Credentials are shown only once at the time they are issued.

Configure OpenClaw

export CLAWROUTER_API_KEY="..."
openclaw onboard --auth-choice clawrouter-api-key
openclaw plugins enable clawrouter

clawrouter ships bundled and is active by default. If your configuration contains plugins.allow, include clawrouter in that list before you enable it. For a custom setup, point models.providers.clawrouter.baseUrl at the ClawRouter origin; the fallback is https://clawrouter.openclaw.ai.

List granted models

openclaw models list --all --provider clawrouter

Use the returned model refs exactly as they appear. They keep the upstream namespace, for instance clawrouter/openai/gpt-5.5, clawrouter/anthropic/claude-sonnet-4-6, or clawrouter/google/gemini-3.5-flash. When agents.defaults.modelPolicy.allow is set, add every selected ClawRouter ref to it.

Select a model

openclaw models set clawrouter/<provider>/<model>

A returned model can also be picked for a single run using openclaw agent --model clawrouter/<provider>/<model> --message "...".

Managed non-interactive deployment

Keep the proxy key inside the workload's secret injection and store only a SecretRef in openclaw.json. The canonical managed fields are:

As an example, a deployment controller can own this JSON5 patch:

{
  plugins: {
    entries: { clawrouter: { enabled: true } },
  },
  models: {
    providers: {
      clawrouter: {
        baseUrl: "https://clawrouter.internal.example",
        apiKey: {
          source: "env",
          provider: "default",
          id: "CLAWROUTER_API_KEY",
        },
        headers: {
          "X-ClawRouter-Project-Id": "fakeco",
        },
      },
    },
  },
  agents: {
    defaults: {
      model: { primary: "clawrouter/openai/gpt-5.5" },
    },
  },
}

If the deployment defines plugins.allow, keep its current entries and append clawrouter. Validate and apply without an interactive wizard:

openclaw config patch --file ./clawrouter.patch.json5 --dry-run --json
openclaw config patch --file ./clawrouter.patch.json5

The dry run resolves the SecretRef but never outputs its value. To rotate the credential, update the external Secret that feeds CLAWROUTER_API_KEY and restart the gateway workload so the new process environment takes effect. Neither the config file nor the model reference needs to change.

For a source-built standalone Docker gateway, ClawRouter is already part of the root runtime. Pick only the channel plugin that needs its own packaging, such as OPENCLAW_EXTENSIONS=clickclack, slack, or msteams; see source-built images with selected plugins. Archive/appliance deployments must package the same landed source through their own artifact pipeline instead of using the OCI image.

Readiness and live proof

These checks verify distinct boundaries; never use one in place of another:

# ClawRouter process health only; no credential or upstream model is exercised.
curl -fsS https://clawrouter.internal.example/v1/health

# OpenClaw gateway startup readiness only; no model call is made.
curl -fsS http://127.0.0.1:18789/readyz

# Credential-scoped catalog discovery.
openclaw models list --all --provider clawrouter --json

# Minimal real inference probe through the configured ClawRouter provider.
openclaw models status --probe --probe-provider clawrouter --probe-max-tokens 8 --json

# Workload canary using an exact granted model ref.
openclaw agent --agent main \
  --model clawrouter/openai/gpt-5.5 \
  --message "Reply exactly: CLAWROUTER_CANARY_OK" \
  --json

Choose a model from the scoped catalog rather than blindly copying the example model. A successful /readyz response only proves the gateway can handle requests; it makes no claim about ClawRouter, its credential, or any upstream provider being ready. The model probe and agent canary serve as the inference proofs.

For live troubleshooting, run the canary and review the gateway's standard logs. The existing metadata-only model transport diagnostics emit lines shaped like:

[model-fetch] start provider=clawrouter api=openai-responses model=openai/gpt-5.5 method=POST url=https://clawrouter.internal.example/v1/responses
[model-fetch] response provider=clawrouter api=openai-responses model=openai/gpt-5.5 status=200

The plugin sends bounded X-ClawRouter-Client, X-ClawRouter-Agent-Id, and X-ClawRouter-Session-Id headers whenever those identifiers are present. It also maps the model call's diagnostic callId (<run-id>:model:<n>) to X-Request-ID, so an OpenClaw model-call event can be linked to ClawRouter's metadata-only audit trail. Values that fit within the 128-character request-id budget stay identical. Longer values keep the :model:<n> suffix plus a deterministic hash, so distinct calls remain bounded and joinable. Static deployment metadata like X-ClawRouter-Project-Id can be placed in the provider headers map. Agent and session attribution headers keep their separate 256-character limit. Automatic request ids containing characters outside ClawRouter's ASCII identifier set use the same deterministic bounded form. Explicit configured headers, including any case variant of X-Request-ID, take precedence over automatic values. The transport diagnostic records routing and response metadata; it never logs credentials, request ids, prompts, or completions. ClawRouter's own audit event provides the selected upstream provider and content-retention state.

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 access to 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 does not require an OpenClaw release: the next catalog refresh (cached 60 seconds per credential scope) picks it up. A model needing a new wire protocol requires plugin support beforehand.

A model's optional displayName serves as its picker label; when absent, OpenClaw falls back to the provider display name and catalog id. The label does not alter model identity. Responses and Chat Completions transmit the catalog id unchanged; only native Anthropic and Gemini routes apply upstream at dispatch. A facade exposing an alias must return only safe catalog metadata, including that alias in the required upstream field, and keep its private target mapping inside the facade.

Protocol and provider plugins

ClawRouter holds upstream credentials; its catalog directs OpenClaw to the appropriate transport, so you do not need to install every upstream company's auth plugin.

The plugin also applies the matching replay and tool-schema policies for those families (OpenAI/DeepSeek/Gemini/Perplexity tool-schema compat; native Anthropic and Google Gemini replay policies). Perplexity models get a strict schema rewrite: patternProperties and additionalProperties are removed and every object schema declares properties, because Perplexity rejects tool schemas without them. 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.
• Automatic attribution and request-correlation values are trimmed and control-character rejected before dispatch. Attribution values are bounded to 256 characters; request ids are bounded to 128.
• Model transport diagnostics contain metadata only and never include the proxy key or model content.
• 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

• Model providers, Provider configuration and model selection.

• Usage tracking, OpenClaw usage and status surfaces.