---
title: "Limits and FAQ"
description: "Known limits of the provider, and answers to common questions."
---

> Documentation Index
> Fetch the complete documentation index at: https://laravel-cf-workersai.meirdick.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Limits and FAQ

## Limits

- Text, embeddings, Clef classification, Clairic extraction and image input.
- Clairic is a Cloudflare preview model, so its behavior can change.
- Clef and Clairic don't use the `/compat` path, so a `url` that ends in `/compat` throws for those calls.
- Chat models take no audio or video attachments, and documents need `convert_documents`. See [Documents](/docs/guides/documents/).
- `nova-3` can't run through AI Gateway. See [Non-JSON models](/docs/concepts/routes/#non-json-models).
- No Laravel AI provider tools. [`CloudflareWebSearch`](/docs/guides/web-search/) is a normal tool that searches the web.
- No limit on concurrent requests. The package retries HTTP 429, but it doesn't prevent it.
- The package doesn't check model names.
- The package doesn't set up your AI Gateway. Create and configure it in the Cloudflare dashboard.
- Reasoning controls depend on the model, and some models ignore `reasoning_effort`.
- Timing and rate figures in these docs come from tests on one account, so your results can differ.

## FAQ

### Do I need AI Gateway?

No. Set only `account_id`, and the package calls Workers AI directly. Add `gateway` if you want logs, analytics, caching and gateway retries. See [AI Gateway](/docs/guides/ai-gateway/).

### Do I need AI Gateway for Clef and Clairic?

No. Both work on the direct route with just `account_id` and `key`. Add `gateway` only if you want gateway logs; the package sends it as the `cf-aig-gateway-id` header.

### What is the difference between this package and the openai-compatible driver?

Laravel AI's `openai-compatible` driver works with the Cloudflare `/compat` URL. If you only use one model for text and set `#[MaxTokens]` on every agent, that driver can be enough.

Use this package when you need any of these:

- A default token cap. Without a cap, Cloudflare stops most models at 256 tokens.
- An exception when a reasoning model spends its whole budget on thinking and returns nothing.
- `reasoning_effort` control.
- Neuron figures for cost tracking.
- Automatic retry of HTTP 429 and of Cloudflare edge errors.
- An AI Gateway with Authenticated Gateway turned on.
- Clef classification and Clairic extraction. The built-in driver has neither.

### Which token permission do I need?

A token with the permission named Account > Workers AI > Read in the Cloudflare dashboard. On an authenticated gateway, chat and embeddings also need `gateway_token`.

### Does it work with Laravel Cloud, queues and Horizon?

Yes. The package is a normal Laravel AI provider that makes HTTP calls with Laravel's HTTP client, so anything Laravel AI supports for queued agents works the same way. Set `#[Timeout]` to fit inside your job timeout.

### Which model should I use?

For agents with tools, start with `@cf/openai/gpt-oss-120b`. For a cheap model, use `#[UseCheapestModel]`. Either way, test with your own prompts. See [Models](/docs/guides/models/).

### Why does my reasoning model return nothing?

It used the whole token cap on thinking. See [Reasoning models](/docs/guides/reasoning/).

### Can I use two Workers AI accounts?

Yes. Add two provider entries to `config/ai.php` with different names, each with `'driver' => 'workers-ai'` and its own `account_id` and `key`.

### Does the package send data anywhere except Cloudflare?

No. Requests go only to the URL your config resolves to.

### Is the package production ready?

Version 1.3.0 is current. The 1.x line follows semantic versioning, 1.0.0 was the first stable release, and it supports `laravel/ai` 0.9 to 1.3. Clairic is still a Cloudflare preview model, so test it on your own data. Read the [changelog](/docs/changelog/) before you upgrade.

### How do I report a bug?

Open an issue on [GitHub](https://github.com/meirdick/laravel-cf-workersai/issues).

Source: https://laravel-cf-workersai.meirdick.com/docs/limits-and-faq/index.mdx
