---
title: Configure models and keys
description: Connect a model service and verify a real model call.
lastVerified: 2026-10-22
---

# 1.5 Configure models and keys

Before you begin, [start Teloa locally](https://docs.teloa.ai/v/0.2.7/markdown/en/start/quickstart.md). For a remote model, have an API key you are authorized to use. For a local model, prepare its runtime service and device resources. You pay remote model fees; the Community software license does not include inference credits.

## Open model settings

Open **Settings > Models** and find your model provider. Teloa manages business areas and employees; the underlying DSH settings manage models, keys, and the environment they run in.

Enter and save the key under the corresponding model provider. Then check that the provider, model name, and run configuration match. Do not put keys in an employee's responsibilities, group messages, skill content, or ordinary reference material.

When exactly one model provider is configured and the old default has no key, Teloa initializes the default model so blank conversations can use it immediately. Existing valid defaults and your explicit selections are preserved. If you configure several providers, check the current choice in the conversation model selector. Automatic group routing uses the current default model.

[![An empty provider credential form. It does not indicate a connection or a completed model call.](https://docs.teloa.ai/v/0.2.7/assets/screenshots/en/model-settings-024.0562e27d2b4e.png)](https://docs.teloa.ai/v/0.2.7/assets/screenshots/en/model-settings-024.0562e27d2b4e.png)

*0.2.4 actual interface with example data. An empty provider credential form. It does not indicate a connection or a completed model call.*

## Verify a response

Start a general conversation and enter:

```text
Reply only with “Model connection is working.” Do not use tools or access reference material.
```

Once you receive a response, test an employee task. Opening the page, saving a key, and successfully running a model task are three separate checks.

## Check the employee's configuration

If a regular conversation works but an employee task fails, check that employee's run configuration and the error message. Pause the employee before changing its employee definition or tool permissions. After saving, return the employee to active status and verify with a small task.

## Local chat models: Ollama

1. Install and start [Ollama](https://ollama.com/download) on the device that will run the model. Open **Settings > Local models** and check its service status and version requirements.
2. Review the target Ollama address, model size, disk and memory guidance, and license. Choose **Download** and confirm. You can follow progress or cancel; Teloa does not install or start Ollama for you.
3. After downloading and connecting the model, select it in the conversation or employee's model configuration. Verify a response as described above, then test a real tool task. An existing unlisted model can be connected with **Connect as an unlisted model**; verify its capabilities separately.

Advanced address settings select the Ollama service that receives downloads and inference requests. If you enter another device's address, that device receives the model and context. With Docker, “local” refers to the deployment server or a service reachable from the container. A loopback address inside the container does not point to the computer viewing the browser; configure an address reachable from your deployment.

**Remove** disconnects the model and deletes its files from the Ollama service shown in the confirmation. An employee can have an explicitly selected remote fallback: only eligible primary-service failures trigger at most one attempt with the selected remote fallback. Without a selected fallback, the task reports failure rather than choosing another model automatically. A ready service, downloaded files, and a successfully completed task are separate results. Memory guidance is an estimate.

## Speech recognition and output

New installations use local SenseVoice for recognition and MiniMax as the initial speech output provider. Saved recognition choices are preserved. Open **Settings > Voice service > Download and prepare local recognition**, review the download source and size, then confirm. The native preparation page shows progress, cancellation, verification, and retry. Opening it does not download files or start recording.

Configure the MiniMax speech API key, model, and voice on the same settings page, then explicitly preview a voice. Speech credentials and chat model settings are managed separately. Saving speech output settings preserves the recognition source, and local recognition needs no speech API key. Your first call also requires browser microphone permission.

## Local search models

A search model turns materials into a searchable index; it does not generate chat answers. Open **Settings > Local models**, select a retrieval model, and follow its preparation prompts. The local retrieval notice in Library opens the same settings:

| Model | Preparation |
| --- | --- |
| Qwen3 Embedding 0.6B | Review the model, tokenizer, and runtime downloads, choose an available source, and explicitly confirm. Teloa runs it on the deployment device; Ollama is not required. |
| EmbeddingGemma 2 | Install and start Ollama on the device running Teloa, meeting the version shown in the page, then confirm pulling and preparing the model. Choose another search model if the device is unsupported. |

Enabling retrieval or opening settings does not automatically download a model. Complete the confirmation and preparation, choose **Use this model**, then add the required materials to local retrieval. First preparation needs a network connection and disk space; you can cancel or retry a failed preparation. With Docker or a server deployment, these files and computations stay in that deployment environment, not the browser.

The EmbeddingGemma 2 preparation page links to the official Ollama installer. Install and start Ollama, then choose **Refresh status**. After a failed preparation, check the service, version, and model before choosing **Retry preparation** and reviewing the confirmation again. Teloa does not start the system's Ollama service for you.

Embedding and indexing run on the deployment device, but retrieved excerpts may still be sent to the current conversation's remote chat model. See [Prepare and use reference materials](https://docs.teloa.ai/v/0.2.7/markdown/en/guides/knowledge.md#enable-local-indexing-and-search) for searchable scope and source checks.

## Common problems

| Symptom | What to do |
| --- | --- |
| Authentication fails | Check that the saved key is valid and belongs to the selected provider. Save it again and retry. |
| The model does not exist or is unsupported | Use a model identifier actually available from that provider. Check whether the run configuration still references an old model. |
| Insufficient quota or rate limiting | Check your quota and request limits with the model provider. A Teloa license does not automatically add tokens. |
| Network failure | Check access to the model service from the device running Teloa. A browser connection does not prove that Teloa can connect. |
| Conversation works, but a task using tools fails | Check the model's tool-calling support, the employee's permissions, and the execution record. |

Conversations use the configured model you select. Configure other models, including models on a private network, according to what the current agent engine actually supports, and verify them separately. This guide does not promise that every compatible endpoint will work without changes.

External models receive the authorized context needed for the task. See [Privacy and permissions](https://docs.teloa.ai/v/0.2.7/markdown/en/deploy/privacy.md) for where data goes.

[![Local model and retrieval settings. Ollama is not connected and retrieval is not enabled in this example.](https://docs.teloa.ai/v/0.2.7/assets/screenshots/en/local-models-024.8ae5acc6dfb0.png)](https://docs.teloa.ai/v/0.2.7/assets/screenshots/en/local-models-024.8ae5acc6dfb0.png)

*0.2.4 actual interface before model preparation or credential entry.*

[![Prepare local SenseVoice separately from MiniMax speech output. No speech key is entered in this example.](https://docs.teloa.ai/v/0.2.7/assets/screenshots/en/voice-settings-024.8cf54b0fa87b.png)](https://docs.teloa.ai/v/0.2.7/assets/screenshots/en/voice-settings-024.8cf54b0fa87b.png)

*0.2.4 actual interface before model preparation or credential entry.*