---
title: "Configuration"
manual: "AI Cowriter for TYPO3"
version: "3.7"
permalink: "https://docs.typo3.org/permalink/netresearch/t3-cowriter:configuration@3.7"
source: "Configuration/Index.rst"
rendered: "2026-09-25T11:40:56+00:00"
---

# Configuration {#configuration}

## LLM provider setup {#llm-provider-setup}

The Cowriter extension uses the [nr-llm extension](https://docs.typo3.org/p/netresearch/nr-llm/main/en-us/Index.html#start) for
LLM provider configuration. Configure your preferred provider in the
nr-llm backend module.

### Supported providers {#supported-providers}

-   **OpenAI** \- GPT-5.x series, o-series reasoning models
-   **Anthropic Claude** \- Claude 4.5 Opus, Sonnet, Haiku
-   **Google Gemini** \- Gemini 3 Pro, Flash
-   **OpenRouter** \- Access to 100+ models from multiple providers
-   **Mistral** \- Mistral Large, Medium, and open models
-   **Groq** \- Ultra-fast inference with Llama, Mixtral

### Configuration steps {#configuration-steps}

1.  Navigate to **Admin Tools** \> **LLM Management**
1.  Add a provider (e.g., OpenAI with your API key)
1.  Create a model configuration
1.  Create an LLM configuration and set it as default

> [!TIP]
> See the
> [nr-llm provider configuration](https://docs.typo3.org/p/netresearch/nr-llm/main/en-us/Configuration/ProviderFields.html#configuration-provider)
> for detailed provider configuration options.

## RTE configuration {#rte-configuration}

There are two ways to configure the CKEditor integration:

### Option 1: Using the shipped preset {#option-1-using-the-shipped-preset}

If you don't have a custom RTE configuration, point the RTE at the preset
this extension registers:

1.  Go to your root page
1.  Open **Page Properties** \> **Page TSconfig**
1.  Add this line:

    ```typoscript
    RTE.default.preset = cowriter
    ```

The preset is inherited by every page below, and brings all four toolbar
items with it.

![Page TSconfig configuration in TYPO3 v14](../Images/pagetsconfig.png)

### Option 2: Custom RTE configuration {#option-2-custom-rte-configuration}

If you have your own RTE configuration file
(`your_ext/Configuration/RTE/YourConfig.yaml`), add the Cowriter module:

```yaml
editor:
  config:
    importModules:
      - { module: '@netresearch/t3_cowriter/cowriter', exports: ['Cowriter'] }
    toolbar:
      items:
        - cowriter
        - cowriterVision
        - cowriterTranslate
        - cowriterTemplates
```

The four toolbar items are:

-   **`cowriter`**

    Main dialog — task-based content generation with preview

-   **`cowriterVision`**

    Generate image alt text via LLM vision analysis

-   **`cowriterTranslate`**

    Inline translation dropdown (10 languages)

-   **`cowriterTemplates`**

    Open the Cowriter dialog with a task pre-selected

> [!TIP]
> You can include only the toolbar items you need. For example, if you
> only want the main dialog and translation, omit `cowriterVision`
> and `cowriterTemplates`.

> [!WARNING]
> An explicit `toolbar.items` list REPLACES the toolbar, it does not add
> to it. Importing the module and then listing only `cowriter` gives you
> exactly one button — the other three are registered but have nowhere to
> appear. If buttons are missing, check this list before suspecting the
> extension.

## Task configuration {#task-configuration}

The Cowriter dialog shows [tasks](https://docs.typo3.org/p/netresearch/nr-llm/main/en-us/Configuration/TaskFields.html#configuration-tasks) from
the nr-llm extension with `category = 'content'`. Default tasks
(Improve, Summarize, Extend, Fix Grammar, Translate EN/DE) are seeded
during installation.

### Adding custom tasks {#adding-custom-tasks}

1.  Navigate to **Admin Tools** \> **LLM Management**
1.  Create a new task record with `category = 'content'`
1.  Set a descriptive name and identifier
1.  Write a prompt template using `{{input}}` as the placeholder for
    user content

**Example prompt template**

```text
Rewrite the following text in a more engaging tone, suitable for
a marketing audience. Output ONLY the rewritten text without
explanations.

{{input}}
```

> [!TIP]
> Tasks can have their own LLM configuration. If a task has no
> configuration assigned, the request's configuration or the default
> configuration is used as fallback.

## Field suggestions {#configuration-field-suggestions}

The fields that get the [Suggest values with AI](https://docs.typo3.org/permalink/netresearch/t3-cowriter:usage-field-suggestions@3.7)
button are set in the extension configuration
(**Admin Tools** \> **Settings** \>
**Extension Configuration** \> `t3_cowriter`):

-   **fieldSuggestions.fields**

    -   *Type:* string
    -   *Default:* `pages.seo_title,pages.description,pages.keywords,pages.slug`

    Comma-separated list of `table.field`. Only single-line text fields,
    plain-text areas (no rich text) and slug fields are supported. A field
    that does not exist is skipped, so `pages.seo_title` only gets the
    button when the system extension `seo` is installed. An empty value
    switches the button off.

-   **fieldSuggestions.count**

    -   *Type:* int
    -   *Default:* `3`

    How many suggestions the button asks for, from 1 to 5. The server
    treats it as the upper bound: a request for more is answered with this
    many.

The list is extension configuration rather than page TSconfig because the
button is added to the TCA, which is the same for the whole installation.
After changing either setting, flush the caches so the TCA is rebuilt.

## Rate limiting {#rate-limiting}

The Cowriter enforces a rate limit of 20 requests per minute per
backend user. When the limit is exceeded, the API returns HTTP 429
with a `Retry-After` header.

## Security considerations {#security-considerations}

The Cowriter extension routes all LLM requests through the TYPO3 backend,
ensuring that:

-   API keys are never exposed to the frontend
-   All requests are authenticated via TYPO3's backend session
-   Error conditions are logged for debugging

> [!WARNING]
> Always configure your LLM provider's API key in the backend. Never
> expose API keys in frontend JavaScript or client-accessible files.

## Troubleshooting {#troubleshooting}

### Translation not working {#translation-not-working}

If the translate button shows "Translation failed", check:

1.  An LLM provider is configured and marked as default in
    **Admin Tools** \> **LLM Management**
1.  The provider's API key is valid and not expired
1.  The provider supports the `translation` feature
1.  Check the TYPO3 system log for detailed error messages

### No tasks in dropdown {#no-tasks-in-dropdown}

If the Tasks dropdown shows "No tasks configured":

1.  Navigate to **Admin Tools** \> **LLM Management**
    \> **Tasks**
1.  Create at least one task with `category = 'content'`
1.  Make sure the task record is not hidden or deleted
1.  Reload the page in the browser to refresh the task list

### API key rejected {#api-key-rejected}

If you see "The LLM provider rejected the API key":

1.  Check the provider configuration in the LLM module
1.  Verify the API key is correct and has not been revoked
1.  Some providers require specific permissions or billing setup

### Rate limit exceeded {#rate-limit-exceeded}

The Cowriter allows 20 requests per minute per backend user. If you
hit the limit, wait a moment and try again. The `Retry-After`
response header indicates when the limit resets.