Providers and Routing

The gateway routes requests to the correct LLM provider based on the endpoint you call and the model you request. It supports 51 built-in providers across 7 tiers, plus org-scoped provider targets for custom routing.

Supported providers

Tier 1 — Core (first-class namespaced routes)

Tier 2 — OpenClaw Favorites

Tier 3 — Developer Staples

Tiers 4-7 — Extended Providers

An additional 34 providers are supported via auto-detection and custom targets, including AI21, Aleph Alpha, Anyscale, AWS Bedrock, Azure OpenAI, Baseten, Cloudflare Workers AI, Databricks, Hugging Face, Lambda, Lepton, NVIDIA NIM, OctoAI, Ollama, Replicate, Sambanova, and more.

Use GET /v1/models for the full catalog available in your environment.

Common model examples

These are representative examples of models the router understands today. For the current catalog in your environment, use GET /v1/models.

Provider auto-detection

When you use the generic gateway endpoints, the provider is determined from the model name or alias:

If the model name does not match any known prefix, the request is rejected with an error indicating the supported prefixes.

Model aliases

The gateway ships with built-in convenience aliases so teams can pin stable names in application code:

Aliases are resolved before provider detection and governance checks.

Org-scoped model aliases

Organizations can define custom aliases through the dashboard or admin APIs. This lets teams keep a stable alias such as production-model while switching the underlying model later.

{
  "alias": "production-model",
  "target_model_ref": "gpt-4o",
  "description": "Production model for customer-facing features",
  "enabled": true
}

Org-scoped aliases resolve before built-in aliases.

Provider key handling

The gateway needs access to the provider’s API key to forward requests. There are two ways to supply it:

Option 1: Pass the key per request

Include the provider key in the request alongside your gateway key:

curl https://api.curate-me.ai/v1/openai/chat/completions \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "X-CM-API-Key: cm_sk_xxx" \
  -d '{"model": "gpt-4o", "messages": [...]}'

Or use the explicit provider key header:

curl https://api.curate-me.ai/v1/openai/chat/completions \
  -H "X-Provider-Key: $OPENAI_API_KEY" \
  -H "X-CM-API-Key: cm_sk_xxx" \
  -d '{"model": "gpt-4o", "messages": [...]}'

Option 2: Store keys in the dashboard

Configure provider API keys as org-scoped secrets in the dashboard under Settings > Provider Secrets. When a request arrives without an explicit provider key, the gateway retrieves the stored key from encrypted secret custody storage.

This approach is recommended for production deployments because it keeps provider keys out of application code and client-side configurations.

Provider-specific auth formats

Each provider uses a different authentication mechanism upstream:

The gateway handles this translation automatically. You always pass your provider key in the same way regardless of which provider you are targeting.

Upstream resilience

The gateway includes automatic retry logic for transient provider errors. Each provider has a tuned resilience policy:

Retry behavior:

• Uses jittered exponential backoff to avoid thundering herd effects
• Respects Retry-After headers from providers (up to 60 seconds)
• Governance checks are NOT re-evaluated on retries — once a request passes governance, retries are transparent
• After all retries are exhausted, the gateway returns the last error with retry metadata in the response

Circuit breakers:

Each provider has an independent circuit breaker. When a provider returns repeated failures, the circuit breaker opens and subsequent requests are rejected immediately with HTTP 503 instead of waiting for timeouts. The circuit breaker automatically closes after the provider recovers.

Dynamic provider routing

The gateway also supports org-scoped provider targets. This allows teams to route requests to custom endpoints such as Azure OpenAI, self-hosted inference, or a private model gateway while preserving the same governance surface.

Backend implementation

Key source files: