---
title: "Configuration"
description: "Every provider config key, with type, default and example."
---

> 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.

# Configuration

Secrets and values that change per environment go in your application's `.env` file. Other package settings go in `config/ai.php`, under `providers.workers-ai`. Laravel AI's own keys, such as `default_for_classification`, are at the top level of that file. You choose the provider name. The `driver` value is `workers-ai`.

## Environment variables

Add the variables your route needs to your application's `.env` file:

```ini
CLOUDFLARE_AI_API_TOKEN=
CLOUDFLARE_ACCOUNT_ID=
CLOUDFLARE_AI_GATEWAY=
CLOUDFLARE_AI_GATEWAY_TOKEN=
CLOUDFLARE_AI_URL=
```

| Variable | Config key | Needed for |
| --- | --- | --- |
| `CLOUDFLARE_AI_API_TOKEN` | `key` | All routes |
| `CLOUDFLARE_ACCOUNT_ID` | `account_id` | All routes except a custom URL |
| `CLOUDFLARE_AI_GATEWAY` | `gateway` | The gateway route |
| `CLOUDFLARE_AI_GATEWAY_TOKEN` | `gateway_token` | An authenticated gateway |
| `CLOUDFLARE_AI_URL` | `url` | A custom URL |

The package does not read these variables by itself. Each one takes effect when `config/ai.php` reads it with `env()`, as in the example below. These names are a convention, so you can use others. See [Direct and gateway routes](/docs/concepts/routes/) for what each route needs.

## Full example

```php
'providers' => [
    'workers-ai' => [
        'driver'     => 'workers-ai',
        'key'        => env('CLOUDFLARE_AI_API_TOKEN'),
        'account_id' => env('CLOUDFLARE_ACCOUNT_ID'),
        'gateway'    => env('CLOUDFLARE_AI_GATEWAY'),

        'default_max_tokens'        => 4096,
        'reasoning_effort'          => 'low',
        'throw_on_empty_response'   => true,
        'throw_on_truncation'       => false,
        'structured_output_retries' => 2,
        'retry'                     => true,
        'retry_attempts'            => 3,
        'retry_rate_limited'        => true,

        'models' => [
            'text' => [
                'default'  => '@cf/meta/llama-3.3-70b-instruct-fp8-fast',
                'cheapest' => '@cf/meta/llama-3.2-3b-instruct',
                'smartest' => '@cf/moonshotai/kimi-k2.6',
            ],
            'embeddings' => [
                'default'    => '@cf/baai/bge-large-en-v1.5',
                'dimensions' => 1024,
            ],
            'classification' => [
                'default'  => '@cf/cloudflare/clef',
                'cheapest' => '@cf/cloudflare/clef-flash',
            ],
            'extraction' => [
                'default' => '@cf/cloudflare/clairic',
            ],
            'reranking' => [
                'default' => '@cf/baai/bge-reranker-base',
            ],
            'image' => [
                'default' => '@cf/black-forest-labs/flux-2-klein-4b',
            ],
            'audio' => [
                'default' => '@cf/deepgram/aura-2-en',
            ],
            'transcription' => [
                'default' => '@cf/openai/whisper-large-v3-turbo',
            ],
        ],
    ],
],
```

## Connection

| Key | Type | Default | Description |
| --- | --- | --- | --- |
| `driver` | string | none | Required. `workers-ai`. |
| `key` | string | none | Required. A Cloudflare API token with the permission named Account > Workers AI > Read in the dashboard. The old name `api_key` still works. If both are set, `key` wins. |
| `account_id` | string | none | Cloudflare account ID. Required unless you set `url`. Use the 32-character hex string, not a URL. |
| `gateway` | string | none | AI Gateway slug. Sends requests through the gateway. Clef and Clairic send it as the `cf-aig-gateway-id` header. |
| `gateway_path` | string | `compat` | Path after the gateway slug. Set `workers-ai/v1` for the provider path. Used only with `gateway`. |
| `gateway_token` | string | none | Optional. An AI Gateway token with Run permission. Needed only for chat and embeddings on an authenticated gateway. Sent as `cf-aig-authorization`. Cloudflare does not need it for Clef and Clairic, but the package still sends it if you set it. |
| `url` | string | none | Full endpoint URL. Do not set it with `account_id`. The package throws if both are set. For Clef and Clairic, the package derives the `/ai/run` URL from it. A `/compat` URL throws for those two. |
| `session_affinity` | string | none | Value for the `x-session-affinity` header. |
| `headers` | array | `[]` | Extra HTTP headers. They replace package headers of the same name, matched without regard to case. Also receives headers set with `Provider::withHeaders()` on `laravel/ai` 1.x. |

The package resolves the endpoint in this order: `url`, then `account_id` with `gateway`, then `account_id` alone. See [Routes](/docs/concepts/routes/).

## Generation

| Key | Type | Default | Description |
| --- | --- | --- | --- |
| `default_max_tokens` | int or null | `4096` | Sent as `max_completion_tokens` when the call or agent sets no cap. `null` sends no cap. |
| `reasoning_effort` | string or null | `null` | `low`, `medium` or `high`. Other values throw `InvalidArgumentException`. |
| `structured_output_retries` | int | `2` | Times the package re-asks for schema-valid output. `0` turns it off. |
| `models.text.default` | string | `@cf/meta/llama-3.3-70b-instruct-fp8-fast` | Default text model. |
| `models.text.cheapest` | string | `@cf/meta/llama-3.2-3b-instruct` | Model for `#[UseCheapestModel]`. |
| `models.text.smartest` | string | `@cf/moonshotai/kimi-k2.6` | Model for `#[UseSmartestModel]`. |
| `models.embeddings.default` | string | `@cf/baai/bge-large-en-v1.5` | Default embedding model. |
| `models.embeddings.dimensions` | int | `1024` | Dimensions reported to Laravel AI. Not sent to Cloudflare. |
| `models.classification.default` | string | `@cf/cloudflare/clef` | Clef model for `Classification::of()->classify()` when the call names none. Needs `laravel/ai` 1.0 or later. |
| `models.classification.cheapest` | string | `@cf/cloudflare/clef-flash` | Returned by `cheapestClassificationModel()`. Not selected automatically. |
| `models.reranking.default` | string | `@cf/baai/bge-reranker-base` | Reranking model. |
| `models.image.default` | string | `@cf/black-forest-labs/flux-2-klein-4b` | Image model. |
| `models.audio.default` | string | `@cf/deepgram/aura-2-en` | Speech model. |
| `models.transcription.default` | string | `@cf/openai/whisper-large-v3-turbo` | Transcription model. |
| `convert_documents` | bool | `false` | Convert document attachments on chat calls to Markdown. See [Documents](/docs/guides/documents/). |
| `models.extraction.default` | string | `@cf/cloudflare/clairic` | Clairic model for `Extraction::of()->extract()` when the call names none. |

## Default classification provider

This key belongs to Laravel AI, not to this package. Set it in `config/ai.php` at the top level, next to `default`.

| Key | Type | Default | Description |
| --- | --- | --- | --- |
| `ai.default_for_classification` | string | `typesafe` | The provider that `Classification::of()->classify()` and `Str::decide()` use when you name none. Set it to `workers-ai` to run them on Clef. |

```php
'default_for_classification' => 'workers-ai',
```

## Failure handling

| Key | Type | Default | Description |
| --- | --- | --- | --- |
| `throw_on_empty_response` | bool | `true` | Throw `EmptyResponseException` when a step has no text and no tool calls. |
| `throw_on_truncation` | bool | `false` | Throw `TruncatedResponseException` when a step ends with finish reason `length`. |
| `retry` | bool | `true` | `false` turns off all retrying. |
| `retry_attempts` | int | `3` | Total attempts, including the first. |
| `retry_rate_limited` | bool | `true` | `false` makes an HTTP 429 fail at once. |

## Per-agent settings

| Setting | Where | Description |
| --- | --- | --- |
| `#[ReasoningEffort(ReasoningEffort::LOW)]` | Agent class | Sets `reasoning_effort` for this agent. Beats the config value. Import `Meirdick\WorkersAi\Attributes\ReasoningEffort`. |
| `#[MaxTokens(n)]` | Agent class | Sets the token cap. Beats `default_max_tokens`. |
| `#[Timeout(n)]` | Agent class | Sets the request timeout in seconds. |
| `#[Strict]` | Agent class | Sends `strict: true` with the JSON schema. |
| `providerOptions()` | Agent method | Adds fields to the request body. Beats the package fields. |

## Provider names

The service provider registers the driver as `workers-ai`. It also registers the alias `workersai`, so a provider entry with `'driver' => 'workersai'` works too.

Source: https://laravel-cf-workersai-docs.mdick85.workers.dev/docs/reference/configuration/index.mdx