Configuring models and providers

Simplest: environment variables

With a single model you need no config file at all — just one environment variable. See the CLI guide for the resolution order.

$ export DEEPSEEK_API_KEY=sk-xxx
$ go run ./cmd/modu_code

Helpers: OPENAI_BASE_URL overrides the OpenAI Responses base URL; THINKING_LEVEL sets the reasoning level (off|low|medium|high, default off).

Config file: multiple models

For several models, model switching, or dedicated roles, write ~/.modu/config.toml. It takes precedence over the environment variables.

version = 2
active = "local-qwen"
scopedModels = ["local-qwen", "deepseek"]

[roles]
summary = "local-qwen"
dispatcher = "deepseek"

[reasoning]
level = "off"

[providers.lmstudio]
type = "openai-compatible"
baseUrl = "http://127.0.0.1:1234/v1"
apiKey = "lm-studio"

[providers.deepseek]
type = "openai-compatible"
baseUrl = "https://api.deepseek.com/v1"
apiKeyEnv = "DEEPSEEK_API_KEY"

[[models]]
name = "local-qwen"
description = "local coding model"
provider = "lmstudio"
model = "qwen/qwen3.6-35b-a3b"
capabilities = ["tools"]
contextWindow = 262144

[[models]]
name = "deepseek"
description = "remote fallback model"
provider = "deepseek"
model = "deepseek-chat"
capabilities = ["tools"]
contextWindow = 1000000

What each field is for

• providers — describes how to connect only: base URL and API key. apiKeyEnv keeps the key in the environment instead of the file.
• models — describes which models are available, each bound to one provider.
• active — the model used by default.
• scopedModels — the set cycled through when switching models.
• roles — assigns models to dedicated jobs such as summary and dispatcher.
• capabilities — what the model supports, e.g. tools, image. Sending images requires image.
• contextWindow — overrides the context window; omitted, built-in vendors fall back to their largest.

OpenAI Responses

OpenAI Responses uses its own provider type:

[providers.openai]
type = "openai-responses"
baseUrl = "https://api.openai.com/v1"
apiKeyEnv = "OPENAI_API_KEY"

[[models]]
name = "gpt-5"
provider = "openai"
model = "gpt-5"
capabilities = ["text", "image", "tools"]

Switching models at runtime

Use /model in the TUI to switch, or /config to add and remove providers and models on the spot — no restart. scopedModels defines what you cycle through.