Cloudflare AI Gateway is a proxy for AI requests. It gives you request logs, cost analytics, caching and rate limits in the Cloudflare dashboard. You create and configure the gateway in the dashboard; the package only sends requests to it. To compare the gateway route with the direct route, see Direct and gateway routes.
Route requests through a gateway
Create a gateway
In the Cloudflare dashboard, go to AI, then AI Gateway, then Create Gateway. Copy the gateway name; this is the slug the package needs.
Add the slug to your .env file
Add this line to your application’s
.envfile:CLOUDFLARE_AI_GATEWAY=my-gatewayRead it in config/ai.php
Add the
gatewayline to the provider entry. It reads the slug from.env, so don’t write the slug here.'workers-ai' => [ 'driver' => 'workers-ai', 'key' => env('CLOUDFLARE_AI_API_TOKEN'), 'account_id' => env('CLOUDFLARE_ACCOUNT_ID'), 'gateway' => env('CLOUDFLARE_AI_GATEWAY'), ],Send a request and open the logs
Your calling code doesn’t change. To confirm the route works, open the gateway in the dashboard and go to Logs. Text and embedding calls show up under
compat.
Text and embedding calls go to https://gateway.ai.cloudflare.com/v1/<account_id>/<gateway>/compat. Clef and Clairic calls go to api.cloudflare.com with a cf-aig-gateway-id header, and Cloudflare applies the gateway’s features to them.
Use only the slug. If you give a URL or a value with a slash, the package throws and points you to the url key.
Authenticated Gateway
Authenticated Gateway is a gateway setting that makes gateway.ai.cloudflare.com reject any request without a gateway token. To set it up:
- Open the gateway settings in the dashboard.
- Create an authentication token and copy it. This is the gateway token, and it has Run permission.
- Turn on Authenticated Gateway.
- Add the token to your application’s
.envfile:
CLOUDFLARE_AI_GATEWAY_TOKEN=your-gateway-token- Read it in the provider entry in
config/ai.php:
'workers-ai' => [
// ...
'gateway_token' => env('CLOUDFLARE_AI_GATEWAY_TOKEN'),
],The package sends cf-aig-authorization: Bearer <gateway_token>, and your key still goes in Authorization. If gateway_token is empty, the package doesn’t send the header.
Calls that go to api.cloudflare.com, such as Clef and Clairic, don’t need the gateway token, because that API reads your API token from Authorization (tested on 2026-11-05). FLUX.2 image models are the exception and do need it. See Non-JSON models.
Without the header, or with a wrong token, an authenticated gateway returns HTTP 401 with {"code":2009,"message":"Unauthorized"}, and Laravel throws Illuminate\Http\Client\RequestException. The message doesn’t name the gateway or the header, so check gateway_token first.
Direct route with a gateway header
You can also get gateway features while staying on the direct route. Cloudflare’s REST API on api.cloudflare.com routes a request through a gateway when it carries the cf-aig-gateway-id header. This needs no gateway key, and no second token even on an authenticated gateway. The exceptions are FLUX.2, which still needs the token, and nova-3, which can’t use a gateway at all. See Non-JSON models.
Keep the slug in your application’s .env file as CLOUDFLARE_AI_GATEWAY, and read it in config/ai.php:
'workers-ai' => [
'driver' => 'workers-ai',
'key' => env('CLOUDFLARE_AI_API_TOKEN'),
'account_id' => env('CLOUDFLARE_ACCOUNT_ID'),
'headers' => ['cf-aig-gateway-id' => env('CLOUDFLARE_AI_GATEWAY')],
],Text, Clef, Clairic and embeddings all returned HTTP 200 this way on 2026-11-05, although Cloudflare’s gateway docs list only chat completions on this API, not embeddings. See the AI Gateway REST API.
Third-party models
Cloudflare’s REST API also serves other providers’ models, such as OpenAI’s, with your Cloudflare token. Use the direct route, and name the model in author/model form:
use function Laravel\Ai\agent;
agent()->prompt('Hello', provider: 'workers-ai', model: 'openai/gpt-5.5');- Cloudflare bills the call from your AI Gateway credits, or uses a provider key you stored under the
defaultalias. See Unified Billing and bring your own keys (BYOK). - The call goes through your account’s default gateway. To pick another, add the
cf-aig-gateway-idheader as in the previous section. - The token needs Account, Workers AI, Read, the same as other calls (tested on 2026-11-05 with
openai/gpt-4.1-mini).
Use another provider’s driver through a gateway
You can point another Laravel AI driver, such as openai, at your gateway to get its logs and caching. You need your own provider key for this, because Laravel AI’s drivers always send key as Authorization. Add the key to your application’s .env file as OPENAI_API_KEY, and build the URL in config/ai.php with BaseUrl::providerUrl():
use Meirdick\WorkersAi\Cloudflare\BaseUrl;
'openai' => [
'driver' => 'openai',
'key' => env('OPENAI_API_KEY'),
'url' => BaseUrl::providerUrl(env('CLOUDFLARE_ACCOUNT_ID'), env('CLOUDFLARE_AI_GATEWAY'), 'openai'),
// Remove this line unless the gateway is authenticated.
'headers' => ['cf-aig-authorization' => 'Bearer '.env('CLOUDFLARE_AI_GATEWAY_TOKEN')],
],For another provider, replace 'openai' with 'anthropic' or that provider’s slug. Don’t call config() here, because config/ai.php is still loading. If you’d rather use a key stored on the gateway, see third-party models.
Use the provider path
To use <gateway>/workers-ai/v1 instead of /compat, set gateway_path:
'gateway_path' => 'workers-ai/v1',/compat stays the default. See The gateway provider path.
Use a custom URL
Set url when you need a full URL the package doesn’t build, such as a proxy. Add it to your application’s .env file as CLOUDFLARE_AI_URL and read it in config/ai.php. Don’t set account_id alongside it, because the package throws if both are set.
'workers-ai' => [
'driver' => 'workers-ai',
'key' => env('CLOUDFLARE_AI_API_TOKEN'),
'url' => env('CLOUDFLARE_AI_URL'),
],If the URL ends in /compat, the package adds the workers-ai/ model prefix, and Clef and Clairic calls throw. For any other URL, it sends the bare model name. See Where each call goes.
Session affinity
Set session_affinity to send the x-session-affinity header on every request:
'workers-ai' => [
// ...
'session_affinity' => 'my-app-session',
],Requests with the same value then reach the same cache shard, which gives the model’s prompt cache a better chance of a hit. See the next section.
Cached tokens
Some models cache the start of a prompt, and a cache hit costs fewer neurons. Cloudflare reports how many tokens came from the cache in usage.prompt_tokens_details.cached_tokens.
The package supports two laravel/ai release lines, 0.9 to 0.11 and 1.x, and they count cached tokens differently:
laravel/ai0.9 to 0.11.Usage::$promptTokensis the uncached count.Usage::$cacheReadInputTokensis the cached count. The two add up to theprompt_tokensthat Cloudflare reports.laravel/ai1.x. The package returnsTextUsage.inputTokensis theprompt_tokensthat Cloudflare reports, with cached tokens included.cacheReadInputTokensis the cached part of it. It isnullwhen the response has no cache field.outputTokensis the completion count.
WorkersAiUsageReported::$promptTokens is the uncached count on both lines.
// laravel/ai 0.9 to 0.11
$uncached = $response->usage->promptTokens;
$cached = $response->usage->cacheReadInputTokens;
// laravel/ai 1.x
$total = $response->usage->inputTokens;
$cached = $response->usage->cacheReadInputTokens ?? 0;
$uncached = $total - $cached;Here are two identical calls on @cf/zai-org/glm-5.3-flash with the same x-session-affinity value, measured on 2026-09-16. The second call hit the cache and cost less than half:
| Call | Wire prompt_tokens |
Wire cached_tokens |
0.x promptTokens |
1.x inputTokens |
cacheReadInputTokens |
Neurons |
|---|---|---|---|---|---|---|
| 1 | 1221 | 0 | 1221 | 1221 | 0 | 17.8 |
| 2 | 1221 | 1216 | 5 | 1221 | 1216 | 8.3 |
Whether this works depends on the model. In tests, @cf/zai-org/glm-5.3-flash and @cf/moonshotai/kimi-k2.6 hit the cache, while @cf/meta/llama-3.3-70b-instruct-fp8-fast, @cf/meta/llama-4-scout-17b-16e-instruct and @cf/openai/gpt-oss-120b did not.
#[CacheInstructions] from Laravel AI has no effect on this provider.
Custom headers
The package sends the headers array from the provider config on chat, streaming and embeddings calls. If one of your headers has the same name as a header the package sets, yours wins. Names match without regard to case.
'workers-ai' => [
// ...
'headers' => ['X-Trace-Id' => env('TRACE_ID')],
],On laravel/ai 1.x, Provider::withHeaders() writes to the same array, so per-call headers reach Workers AI too. Before version 1.0.0, the package dropped both the headers key and per-call headers.
Logging
AI Gateway logs are in the Cloudflare dashboard. The package doesn’t write request logs. The only thing it writes to the Laravel log is a warning when it raises the token cap for a thinking request.
Gateway retries
An AI Gateway with retry_max_attempts set retries inside your single HTTP request, and the package retries too. A late error can then make the request several times longer, long enough for your own timeout to cut it off. Use one retry layer: if you want the gateway’s retry, set retry to false in the package config. See Errors and retries.