Skip to main content

​
Cloudflare AI Gateway

Cloudflare AI Gateway is a proxy layer that sits in front of other AI providers. It adds caching, rate limiting, cost tracking, and observability — without changing the underlying model or provider.
Cloudflare AI Gateway does not host models itself. It proxies requests to other providers (OpenAI, Anthropic, etc.). You still need credentials for the underlying provider.

​
Prerequisites

1

Create a Cloudflare AI Gateway

In the Cloudflare dashboard, go to AI → AI Gateway and create a new gateway. Note your account ID and gateway name.
2

Obtain an API key

Create a Cloudflare API token with AI Gateway permissions. Set it on the gateway host:
echo 'CLOUDFLARE_AI_GATEWAY_API_KEY=your-token-here' >> ~/.openclaw/.env

​
Configuration

The baseUrl must include your Cloudflare account ID and gateway name: 
{
  models: {
    providers: {
      "cloudflare-ai-gateway": {
        apiKey: "CLOUDFLARE_AI_GATEWAY_API_KEY", // references the env var
        // Replace <account> and <gateway-name> with your values:
        baseUrl: "https://gateway.ai.cloudflare.com/v1/<account>/<gateway-name>",
        models: [
          // list the models you route through this gateway
        ],
      },
    },
  },
}
The baseUrl is required and must contain your specific account ID and gateway name. Omitting it or using the wrong values will cause all requests to fail.
apiKey is the name of the environment variable, not the key value itself. Keep secrets in .env, not in committed config files.

​
Selecting a model

The model reference uses the cloudflare-ai-gateway/ prefix: 
{
  agents: {
    defaults: {
      model: { primary: "cloudflare-ai-gateway/<provider>/<model-id>" },
    },
  },
}
The path after the provider prefix follows the Cloudflare AI Gateway routing format — typically <upstream-provider>/<model-id>.

​
What Cloudflare AI Gateway adds

FeatureBehaviour
CachingIdentical requests return cached responses, reducing cost and latency
Rate limitingConfigurable per-gateway request limits
ObservabilityRequest logs, latency metrics, and cost estimates in the Cloudflare dashboard
FallbacksRoute to a secondary provider if the primary fails

​
Troubleshooting

The baseUrl account ID or gateway name is incorrect. Double-check both values in the Cloudflare dashboard.
The API token is invalid or lacks AI Gateway permissions. Create a new token with the correct scope.
Cloudflare AI Gateway forwards errors from the underlying provider. Check that your upstream provider credentials are valid and that the model ID is correct for that provider.