---
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-docs.mdick85.workers.dev/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. Its behavior can change.
- Clef and Clairic do not use the `/compat` path. A `url` that ends in `/compat` throws for those calls.
- Chat models take no audio or video attachments. Documents need `convert_documents`. See [Documents](/docs/guides/documents/).
- `nova-3` cannot 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 request concurrency limit. The package retries HTTP 429. It does not prevent it.
- The package does not check model names.
- The package does not set up your AI Gateway. Create and configure it in the Cloudflare dashboard.
- Reasoning controls depend on the model. Some models ignore `reasoning_effort`.
- Timing and rate figures in these docs come from tests on one account. Your results can differ.

## FAQ

### Do I need AI Gateway?

No. Set only `account_id` to call Workers AI directly. Add `gateway` to get 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. Set `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?

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

Use this package when you need one or more 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. For an authenticated gateway, chat and embeddings also need `gateway_token`.

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

The package is a normal Cloudflare Workers AI provider for Laravel AI. It makes HTTP calls with the Laravel HTTP client. Anything Laravel AI supports for queued agents works the same. Set `#[Timeout]` to fit 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]`. Test 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 in `config/ai.php`, each with `'driver' => 'workers-ai'` and its own `account_id` and `key`. Give each entry its own name.

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

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

### Is the package production ready?

Version 1.3.0 is current. The 1.x line follows semantic versioning, and 1.0.0 was the first stable release. It supports `laravel/ai` 0.9 to 1.3. Clairic is 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-docs.mdick85.workers.dev/docs/limits-and-faq/index.mdx