All settings are global and live at Admin > Chatbot > Settings (/admin/chatbot/settings). The form has four tabs. There are no per-site settings.
Password fields (OpenAI API key and Turso auth token) are always blank when the page loads. Leaving them blank on save keeps the stored value.
Connection
| Setting | Default | Description |
|---|---|---|
| Use API key from local.config.php | unchecked | Informational. The module always uses chatbot.openai_api_key from local.config.php when it is set, and only falls back to the key saved below when it is not. |
| OpenAI API key | none | Stored AES-256-CBC encrypted with chatbot.encryption_key. |
| Turso database URL | none | libsql:// or https:// URL of your Turso database. |
| Turso auth token | none | Token from the Turso dashboard or turso db tokens create. |
Models & Search
| Setting | Default | Description |
|---|---|---|
| Embedding model | text-embedding-3-large | OpenAI embedding model. text-embedding-3-small (1536 dimensions) is faster and cheaper. |
| Embedding dimensions | 3072 | Vector size requested from OpenAI and used for the Turso vector column. 256 to 3072; must suit the model. Changing it requires Purge All Index Data and a full re-index. |
| Chat model | gpt-4o-mini | Model that writes answers: gpt-4o-mini, gpt-4o, gpt-4-turbo or gpt-3.5-turbo. Requests use temperature 0.2 and a 1024-token answer limit. |
| Chunk size (characters, ≈800 tokens) | 3200 | Characters per indexed chunk. Values below 500 are raised to 500 at index time. |
| Chunk overlap (characters, ≈50 tokens) | 200 | Characters shared between consecutive chunks. Capped at half the chunk size. |
| Top-K results to retrieve | 5 | Chunks given to the chat model as evidence (1 to 20). Semantic search fetches its own, larger set. |
| Item set filter | none (all items) | When item sets are selected, only items in at least one of them are indexed. Other items are skipped and any chunks they already have are removed. Does not affect media, blog posts or site pages. |
Behaviour
| Setting | Default | Description |
|---|---|---|
| Default system prompt | empty | System prompt for every chat request. Empty means the built-in prompt below. A Chatbot block can override it. |
| Auto-index items on save | checked | Queue an index job whenever an item, media, site page or blog post is created or updated. Deletions always remove chunks, even when this is off. |
| Enable global chat widget on all public pages | unchecked | Inject the floating chat button on every public site page. |
| Widget heading | empty | Title at the top of the floating widget panel. Empty means "Ask our collection". |
| Log level | info | Minimum severity written to the module log: debug, info, warning or error. The dashboard needs info to see chat and search activity. |
| Log retention (days) | 90 | Age after which Purge Old Logs Now deletes log entries. 0 keeps logs forever and disables the purge button. |
The built-in system prompt is:
You are an assistant that answers questions using only the provided evidence. If the answer is not contained in the evidence, say 'I don't know.' Always include citations in the format [N] referring to the numbered evidence items.
Diagnostics
The fourth tab holds actions rather than settings: Re-index Now with content type checkboxes, Purge All Index Data, Run Test Search and Purge Old Logs Now. See Indexing Content and Dashboard and Logs.
local.config.php keys
Add these under a 'chatbot' key in config/local.config.php.
| Key | Default | Description |
|---|---|---|
encryption_key |
fixed built-in fallback | Secret used to encrypt the OpenAI API key at rest. Always set it. |
openai_api_key |
unset | OpenAI key read from the file instead of the database. Takes priority whenever set. |
sync_jobs |
false | When true, index, bulk re-index and log purge jobs run inside the web request instead of through Omeka's job queue. For local development only. |
Settings without a form field
Two settings are read from Omeka's global settings table but have no field in the form. They keep their defaults unless changed through the Omeka settings service, for example from another module or a script.
| Setting key | Default | Description |
|---|---|---|
chatbot_rate_limit_max |
10 | Requests allowed per client IP address per window, shared by the chat and search endpoints. |
chatbot_rate_limit_window |
60 | Window length in seconds. |
Permissions
| Role | Chat and search on public sites | Dashboard, logs, CSV export | Settings, re-index, purge | Run Test Search |
|---|---|---|---|---|
| Anonymous visitor | ✓ | — | — | — |
| Researcher, Author, Reviewer | ✓ | — | — | — |
| Editor | ✓ | ✓ | ✓ | ✓ |
| Site Admin | ✓ | ✓ | ✓ | ✓ |
| Global Admin | ✓ | ✓ | ✓ | ✓ |
The chat and search endpoints are public and protected by per-IP rate limiting rather than by login. The Chatbot sidebar entry is only shown to roles that can open the dashboard. A Chatbot page block whose Allow anonymous users option is unchecked shows a login link instead of the panel to visitors who are not logged in; see Chat Widget and Block.