Skip to content

Settings

Jump to bottom
Dang Nguyen edited this page Jun 7, 2026 · 2 revisions

This page covers the required settings, such as providers, models, the agents that depend on them, and the Troubleshooting section covers common mistakes.

Providers

Steward needs API keys (or a local endpoint) for the LLM providers you use. Built-in providers include OpenAI, Google, Anthropic, Ollama, ElevenLabs, and Hume.

API keys: direct input vs Obsidian secrets

For each provider, click Edit and choose how to store the key:

Method Description
Obsidian secret storage (recommended) Pick or create a secret in Obsidian’s Secret Storage. The key never lives in the plugin settings file as plain text.
Direct input Type the key into the password field; Steward encrypts it in plugin data.

Prefer secret storage. Direct input may be deprecated or removed in a future release. If your Obsidian build supports secrets, use Use secret storage when the API key field is empty.

Built-in providers may also support a base URL (proxy or alternate endpoint) and an optional system prompt appended for that provider.

Ollama does not require an API key; set the Ollama base URL if it is not the default local URL.

Custom providers

Use Add new provider when you have:

  • More than one account for the same vendor (e.g. two OpenAI keys), or
  • A compatible API that speaks an existing protocol (most often OpenAI-compatible): OpenRouter, DeepSeek, Groq, local proxies, etc.

For each custom provider, set:

Field Purpose
Provider name Short id with no spaces (e.g. openrouter). This name is the <provider_name> part in provider:model (see below).
Compatibility Which built-in client shape to use (OpenAI, Google, Anthropic, …).
API key Same options as built-in providers (secret or direct).
Base URL Required for most OpenAI-compatible gateways.

You can delete a custom provider from its Edit screen when it is no longer needed.

Model ID format

Almost every model dropdown uses the same pattern:

<provider_name>:<model_id>

Examples:

  • openai:gpt-4o — built-in OpenAI

  • google:gemini-2.0-flash — built-in Google

  • openrouter:anthropic/claude-3.5-sonnet — custom provider named openrouter

  • Built-in providers — use the lowercase keys shown in settings: openai, google, anthropic, ollama, elevenlabs, hume.

  • Custom providers — use the Provider name you configured (not the internal provider-… key).

To add a model that is not in the preset list, open the model control, choose Add new model, and enter a valid provider:model string. Invalid formats are rejected (must match provider:model with no spaces in the model part).

You can also switch the chat model inline in a conversation with m: or model: — see Get started.

Chat model and generation

Setting Role
Chat model Main model for Steward’s agent (SuperAgent) replies and tool use.
Temperature Randomness of completions (0–1).
Max generation tokens Cap on tokens per generation.
Enable model fallback / Fallback chain Optional ordered list of models to try if the primary model fails.

Conversation title agent

After you send the first message in a new conversation, Steward can set a short conversation title in the note frontmatter (conversation_title).

Setting Role
Enable conversation title agent Turn automatic title generation on or off.
Conversation title model LLM used when a generated title is needed. Empty means use chat model.

Behavior (see ConversationTitleAgent in the codebase):

  1. Static / prefixed classification — If the first query matches a static or prefix cluster (e.g. help, ?, build search index), the cluster name is formatted and used as the title (no LLM call).
  2. Short queries — If the query is ≤ 10 words, the query text may be used as the title.
  3. LLM — Longer, non-static queries get a concise title from the configured title model.

Compaction summary agent

During conversation compaction, long assistant messages can be summarized in the background so history stays usable without blocking the main agent.

Setting Role
Enable compaction summary agent Turn batch summarization on or off.
Compaction summary model LLM for summarization. Empty means use chat model.

The agent marks procedural filler as deleted and keeps 1–3 sentence summaries for substantive content (CompactionSummaryAgent).

Intent classification

Intent classification routes some user input to the right tasks (and tools) before or instead of a full LLM pass. It runs in three layers:

Layer How it works Needs embedding model?
Static Exact match on fixed phrases (e.g. ?, help, stop, build search index, undo, new). No
Prefixed Query starts with a known prefix cluster (e.g. speech-style phrases). No
Embedding (clustered) Compares the query to stored example phrases via embeddings; learns from past similar queries over time. Yes

Enable intent classification toggles embedding-based classification. When disabled, Steward still uses static and prefixed rules only (same as “offline” mode in logs). That is enough for many client-side flows:

  • ? / help → help
  • build search index → index build (no chat model required for the intent path)
  • stop, undo, new, confirmations, etc.

When embedding classification is enabled, configure:

Setting Role
Embedding model provider:model for embeddings (e.g. openai:text-embedding-3-small). Changing the model clears cached embeddings for the old model.
Similarity threshold How close a new query must be to a stored cluster (0.7–0.99; default ~0.85). Higher = stricter match.

Disabling intent classification is fine if you do not need semantic routing or want to avoid embedding API calls. Prefix and static classification still apply.

Other model sections (same tab)

Section Purpose
Speech Text-to-speech model and voice ID per provider.
Image Image generation model and size.
Search BM25 matching mode and results per page — see Search.
Local CLI bridge Shell executable, working directory, interactive programs — see Shell command & Terminal.

Troubleshooting

Model configured without a provider

The most common mistake is entering only the model id (e.g. gpt-4o) instead of provider:model (e.g. openai:gpt-4o). Every model field in settings expects the full form. For a custom gateway, use your custom provider name as the prefix: myproxy:some-model.

Provider has no API key

If the provider is missing a key (or the Obsidian secret name is wrong), chat and agents fail when they call that provider. Open Edit for that provider and confirm either a saved secret or a valid encrypted key.

Intent classification errors

Intent classification is enabled by default. Errors often mean:

  • The embedding model is set but the provider has no key, or the provider does not support embeddings.
  • The embedding model string is malformed.

Fix options:

  1. Set a valid embedding model and API key for that provider, or
  2. Turn off Enable intent classification — static and prefixed classification still work; only semantic clustering is off.

Title or summary agent fails silently

Both agents log errors and return without blocking the chat. Check:

  • The agent is enabled.
  • If a dedicated model is set, it uses provider:model and that provider is configured.
  • Empty model fields fall back to the chat model — fix the chat model if that is wrong.

Custom OpenAI-compatible provider

Set compatibility to OpenAI, fill base URL (e.g. https://openrouter.ai/api/v1), add the API key, and use models like your_provider_name:model-id-from-vendor.

Related

  • Get started — conversations, inline m: / model:
  • Memory — per-tool guidelines (separate from plugin settings)
  • MCP — external tools (configured elsewhere in the plugin)

Clone this wiki locally