Configuration 

LLM connection 

Processing 

Access control 

Chat panel 

When llmTaskUid is configured, a chat button appears automatically in the TYPO3 backend toolbar (top right). Clicking it opens a floating bottom panel that stays visible across module navigation.

The panel supports four states:

• Hidden -- Default. Only the toolbar button is visible.
• Collapsed -- Minimal header bar showing the active conversation title and status.
• Expanded -- Resizable panel with chat messages, input, and a compact conversation switcher.
• Maximized -- Full-height panel with a sidebar for conversation management (search, pin, archive).

The panel height and state are persisted per user in the browser's localStorage.

A site's own AI configuration 

A site can name its own nr-llm configuration in the site setting LLM configuration (nrllm.configuration, set netresearch/nr-llm, nr-llm ADR-244), for example because its content may only go to one provider. The chat honours it: a conversation about a page of that site runs on the site's configuration -- its provider, model and system prompt -- instead of the configuration of the chat's Task. The Task's prompt template still applies. Sites without the setting, conversations about no page, and pages the user may not show keep the Task's configuration. The choice is made again on every turn, so a changed setting applies to the next message. See ADR-033.

The chat reads and changes pages only through tools, so it refuses a site configuration it cannot run on, before any model call, and says why in the reader's language:

• the configuration does not exist, is disabled, or is restricted to backend groups the user is not in;
• it selects its model by criteria instead of naming a fixed model;
• its model cannot call tools: the model record lacks the capability Tool Use (AI > Models), or its provider does not support tool calling.

It never falls back to the Task's configuration for that site, because that would send the site's content to a provider the site was set up to avoid. Administrators also get a link to the LLM configurations.

Model discovery ticks Tool Use for the providers that report it per model (Mistral, OpenRouter, Ollama) and for the curated OpenAI, Anthropic and Gemini models. Groq reports no capabilities: tick it by hand on a Groq model that supports tool calling.

What else follows the site's configuration:

• Term lists of both configurations apply: those bound to the chat Task's configuration and those bound to the site's. A ban of either one blocks, and a list bound to both reports its terms once (nr-llm ADR-290). Site-bound lists keep applying as before. The same holds for the rule-set judge: where both configurations have one, both judge, and the stricter mode decides.
• Privacy level is read from the run's configuration, so the level of the site's provider applies.
• Tool groups and excluded tools are the site configuration's. An empty group list allows every group.
• Approvals waiting when the setting changes to another configuration, or to one the chat cannot run on, are not carried out on the old configuration: the chat hands the card or question back and asks for a new message. When the setting is cleared, a waiting run continues on the configuration it started with.

The run of each turn records its configuration; nr-llm's Agent Runs module (AI > Operation) shows it on the run.

System prompt 

The system prompt sent to the LLM is not configured in the extension configuration itself, but in the nr-llm records:

Configuration record (tx_nrllm_configuration.system_prompt)

The primary system prompt. Set this to define the AI assistant's persona, language, and behavior. Also use this field for instructions on how the tools registered in nr-llm are to be used.

Example:

Du bist ein TYPO3-Assistent.

## Tool-Nutzung
- Vor jeder Aussage über den Seitenbaum erst
  get_pagetree aufrufen, nie aus dem Verlauf raten.
- Datensatzfelder über read_records lesen, nicht aus
  einer früheren Antwort zitieren.
- create_content_element_draft legt ein verstecktes
  Element an; sag danach, wo es liegt und dass es
  noch freigeschaltet werden muss.

Copied!

Name the tools your installation actually has -- AI > Operation > Tools in nr-llm lists them, and AI > Operation > MCP Servers is where an external server's tools come from.

Task record (tx_nrllm_task.prompt_template)

Additional instructions appended after the Configuration prompt. Use this for task-specific context.

When both fields are set, they are combined (separated by a blank line). If neither is set, a locale-based default prompt is used. For a page of a site with its own AI configuration (see A site's own AI configuration), the Configuration record is the site's.

Instructions for a conversation (tx_nrmcpagent_conversation.system_prompt)

Set by the user in the chat (the sliders button, see Usage). They are added after the two prompts above, which stay in force: the assistant is told to follow the user's instructions only where they do not contradict the configured ones. The assistant's identity, the site-language rules and the user's own context are added either way.

Every prompt ends with the user's context:

• Answer language -- the language the user's backend is set to. The assistant answers in it whatever language the message is written in, unless the message explicitly asks for another language.
• Where the user is -- the open backend module and, when the module shows a page, that page's uid and title. The page is included only if the user may see it; the check runs with the user's page permissions when the turn is processed. It lets "summarise this page" work without naming a uid.

User interface 

File attachments 

File attachments are always available — no special provider configuration required. Text is extracted server-side for document formats, so they work with any LLM provider.

Always supported (server-side text extraction):

• PDF: application/pdf — requires smalot/pdfparser (hard dependency)
• DOCX: application/vnd.openxmlformats-officedocument.wordprocessingml.document — requires phpoffice/phpword (hard dependency)
• TXT: text/plain — no dependencies
• XLSX: application/vnd.openxmlformats-officedocument.spreadsheetml.sheet — requires phpoffice/phpspreadsheet (optional; install via composer require phpoffice/phpspreadsheet:^3.0)

Additionally available for vision-capable providers (Claude 3+, Gemini, GPT-4o, etc.):

• Images: image/png, image/jpeg, image/webp

When the provider natively handles a document format (e.g. Claude natively processes PDFs via DocumentCapableInterface), the file is sent as binary instead of being extracted. The file picker automatically restricts to formats the active provider can process.

Storage: An uploaded file is a managed TYPO3 file from the moment it arrives: it is written into the default storage, indexed in sys_file and given a sys_file_metadata record, like any other file in the file module. It is then read at LLM call time and sent as Base64-encoded multimodal content, and the assistant is told its sys_file uid and path — so it can reference the attachment from a content element with nr-llm's file tools instead of asking for it to be uploaded again.

Nothing is ever overwritten or deleted. A name already taken in the folder yields report_01.pdf; if the file of that name has identical content, the existing one is returned instead of a copy. Where the user may not write, the upload is refused with 403 rather than failing as a server error — the file mounts and permissions of the logged-in backend user apply throughout.

Limits:

• Maximum 5 files per conversation.
• Maximum file size: 20 MB per file.
• File count is enforced both in the frontend (before upload) and in the backend API.

Security: Decide deliberately whether the attachment folder is publicly readable, because the two things it is used for pull in opposite directions.

An attachment is material a backend user hands to the assistant, and it is stored under a path that is guessable by name. Where attachments are only ever read by the assistant, deny direct HTTP access to the folder:

# fileadmin/ai-chat/.htaccess
Require all denied

Where editors are meant to place an attached image or PDF into a content element — the file is already in FAL, so this needs no second upload — the folder must stay publicly readable, or the reference renders as a broken image in the frontend. Denying access to the folder and referencing files out of it is a contradiction, not a hardened setup. Point attachmentFolder at a folder your editors publish from in that case, and treat what is uploaded through the chat as publishable.

Security 

Choices in guided processes 

A guided process asks its plain choices -- which point first, whether to continue, how to go on when a source is missing -- through nr-llm's tool ask_choice. The chat shows its answers as reply buttons above the input. nr-llm ships ask_choice switched off: enable it under AI > Operation > Tools in nr-llm before a process relies on it. Without it a process cannot ask such a choice and has to put it into its answer instead. ask_choice needs an nr-llm that has it (nr-llm PR 1029).

The answers are the options the process passes, shown as they are. A "go on without" option, such as "Ohne Bild weiter", is worded by the process's skill, not by the chat.

Dashboard 

These settings fill the AI assistant dashboard widgets (see Dashboard widget). The chat's skill catalogue names a skill by nr-llm's <source uid>:<path>, such as 3:seo-optimieren, so the same skill has a different identifier on every installation. A setting names a skill in one of two ways:

• a bare slug without :, such as seo-optimieren: the catalogue skill whose identifier is <source uid>:seo-optimieren. Where several sources carry the slug, the source with the highest trust level wins (nr-llm's skill trust: first party, verified, community, untrusted), then the one with the lowest source uid;
• a catalogue identifier, such as 3:seo-optimieren: exactly that skill.

Letters, digits and ._:/- are accepted, starting with a letter or digit and at most 100 characters; any other entry is ignored.

What an editor reads for a skill comes from EXT:nr_mcp_agent/Resources/Private/Language/locallang_dashboard.xlf: skill.<key>.title, skill.<key>.description and, for a frequent task, task.<key>. <key> is the identifier with every character other than a letter, digit, - or _ replaced by _: 3:skills/seo is labelled by skill.3_skills_seo.title. A catalogue identifier without labels of its own uses those of its slug, so 3:seo-optimieren reads skill.seo-optimieren.title. For a skill of your own, add these labels through a language override ($GLOBALS['TYPO3_CONF_VARS']['SYS']['locallangXMLOverride']). An entry without a title is left out rather than shown by its identifier.

An entry is offered only when the chat can start its skill for the user looking at the dashboard: the skill is in the chat's skill catalogue for that user, nr-llm can pass a skill to a run, and the configuration does not require a second person to approve every change. Otherwise the entry is left out, and a widget left with nothing to offer says that nothing is set up yet. A configured skill that does not exist therefore never leads to a link the chat would refuse.

Missing alt texts 

The check for images without an alt text (see Decorative images and ADR-026: A Site-Wide Check for Missing Alt Texts) reads every image field of type file in the TCA, so the image fields of a newly installed extension are checked without any setting. These two settings leave fields and tables out.

Image analysis (privacy) 

Whether images are sent to the AI provider (see ADR-026: A Site-Wide Check for Missing Alt Texts, slice 3). Whether an image shows people cannot be told before it is analysed, so the setting applies to every image and to every feature of the assistant that sends one: the scaled copy for an alt text proposal (Optimise an alt text with the assistant) and a file attached in the chat (Attaching files), where a document the provider would read as a whole (a PDF carries its photos along) goes as its extracted text instead. Sending images needs a data processing agreement with the operator that covers the AI provider's processing, images of people included.

A change applies from the next turn of a conversation, also with processingStrategy worker: each turn runs with the setting of the backend request that started it, which the request stores with the conversation. One exception keeps the image card and the model in agreement: where the card of an alt text conversation already says the image is not sent, the image stays unsent after analysis is switched back on, until the chat moves on to another image. A turn that continues after an approval or an answer resumes the stored run of the AI provider, so an image that run already sent goes to the same provider again; the next turn follows the setting.

It is part of the extension configuration (category privacy), which only administrators with system maintainer rights can change, as every setting on this page.

Worker mode production setup 

For production use with processingStrategy = worker, set up a systemd service to keep the worker running:

# /etc/systemd/system/typo3-ai-chat-worker.service
[Unit]
Description=TYPO3 AI Chat Worker
After=mysql.service
StartLimitIntervalSec=0

[Service]
Type=simple
User=www-data
Group=www-data
WorkingDirectory=/var/www/html
ExecStart=/var/www/html/vendor/bin/typo3 \
    ai-chat:worker --poll-interval=100 --max-turns=1
Restart=always
RestartSec=0
TimeoutStopSec=610

[Install]
WantedBy=multi-user.target

Enable and start the service:

sudo systemctl daemon-reload
sudo systemctl enable typo3-ai-chat-worker
sudo systemctl start typo3-ai-chat-worker

A worker ends by itself and expects to be started again:

--max-turns

After this many turns. 1 starts every turn in a fresh process that is already booted, which is the recommended value: nothing of a turn reaches the next one, and a configuration change counts from the next turn. 0 keeps the process running, without a boot between turns.

--time-limit, --memory-limit

After this many seconds, above this many megabytes. Defaults: 3600 and 256.

--turn-limit

A turn that runs longer than this many seconds, 600 by default, ends the process and fails, and the reader gets a Retry. It is never run a second time by itself, because it may have written.

A changed setting

When the system settings file was written since the worker started, it stops before its next turn, so the next worker reads the new values.

SIGTERM and SIGINT stop a worker after its current turn, so give it the time (TimeoutStopSec, or stop_grace_period in Compose). This and --turn-limit need the PHP extension pcntl; without it the process dies on SIGTERM and a stuck turn waits for ai-chat:cleanup.

One worker runs one turn at a time. Run as many as turns should run at the same time. A turn that finds no free worker starts a process of its own, as with exec, so a worker that is down costs the time of that start and nothing else. See ADR-029.

Scheduled cleanup 

Add the cleanup command to your cron or TYPO3 scheduler to handle stuck conversations, auto-archiving, and deletion of old data. A conversation whose worker never finished stays in processing until this command marks it failed after five minutes — without the schedule it can stay there indefinitely:

# Run cleanup daily at 3:00 AM
0 3 * * * /var/www/html/vendor/bin/typo3 \
    ai-chat:cleanup --delete-after-days=90