Models & Credentials

Every harness needs a model to run and credentials to reach it. You declare the model in your agent YAML, and Omnigent manages the credentials that authenticate to each provider.

Choose a model

Declare the model in your agent YAML:

executor:
  harness: claude-sdk
  model: claude-sonnet-4-6

Override it at runtime without editing the file:

omni run agent.yaml --model claude-sonnet-4-6

Switch models mid-session

Use the /model command inside any running session to switch models on the fly. The agent keeps its conversation history and tool state – only the underlying model changes.

Reasoning effort

Set a default reasoning level for the agent alongside the model:

executor:
  harness: claude-sdk
  model: claude-sonnet-4-6
  reasoning_effort: high    # low | medium | high | xhigh

executor.reasoning_effort is optional. When unset, the harness CLI's own default applies. The accepted values are low, medium, high, and xhigh; which ones a given harness actually honors is harness-dependent, and the value is validated against the harness's effort vocabulary at launch (an unknown value is also rejected up front when the spec is validated).

The spec-level default applies to the main session and to every sub-agent dispatch that doesn't pass its own effort. Precedence, highest first:

A per-dispatch argument on sys_session_send / sys_session_create.
executor.reasoning_effort from the spec.
The harness CLI default.

Back-compat: the older llm.reasoning_effort key is still accepted and is lifted to executor.reasoning_effort when the spec is parsed. Prefer executor.reasoning_effort in new specs; when both are set, executor.reasoning_effort wins.

Credentials

Omnigent needs credentials to talk to a model provider.

omni setup

The setup wizard walks you through adding a credential, setting a default, or removing one. It also auto-detects credentials already on your machine (API keys in environment variables, logged-in CLIs, and local servers) so you can confirm them with one tap.

Credential types

Type	What it is
API key	A first-party provider key (Anthropic, OpenAI, OpenRouter, and more)
Subscription	A Claude Pro/Max or ChatGPT Plus/Pro plan, via the official `claude` / `codex` CLIs
Gateway	Bring your own proxy or local model. Just paste a base URL and key.
Databricks	A Databricks workspace profile, routing through the Foundation Model API

API key

Get a key from your provider's dashboard and add it via omni setup. Supported providers:

Provider	Key source
Anthropic	console.anthropic.com
OpenAI	platform.openai.com
OpenRouter	openrouter.ai
Groq	console.groq.com
DeepSeek	platform.deepseek.com
xAI	console.x.ai
Mistral	console.mistral.ai
Together AI	api.together.xyz
Fireworks AI	fireworks.ai

Subscription

If you have a Claude Pro/Max or ChatGPT Plus/Pro plan, Omnigent can use your existing CLI login. No API key needed. Just make sure you're logged in:

claude auth login    # for Claude Pro/Max
codex login          # for ChatGPT

omni setup auto-detects an active CLI login and offers it as a one-tap option.

Gateway

Omnigent works with any OpenAI-compatible or Anthropic-compatible gateway:

Databricks Unity AI Gateway

MLflow AI Gateway

OpenRouter

LiteLLM

Portkey

Helicone

Cloudflare AI Gateway

Kong AI Gateway

Vercel AI Gateway

Azure OpenAI

Ollama

LM Studio

vLLM

LocalAI

TGI (Hugging Face)

GPT4All

omni setup asks for a base URL and a key. The base URL differs depending on the agent:

Provider	For	Base URL	Key
OpenRouter	Claude Code	`https://openrouter.ai/api`	your OpenRouter key (`sk-or-...`)
OpenRouter	Codex / OpenAI agents	`https://openrouter.ai/api/v1`	your OpenRouter key (`sk-or-...`)
Ollama (local)	Codex / OpenAI agents	`http://localhost:11434/v1`	any value (Ollama ignores it)

Note: For Claude Code, point at OpenRouter's Anthropic-compatible endpoint (.../api, not .../api/v1); for Codex and the OpenAI-agents harness, use the OpenAI-compatible .../api/v1.

Cost tracking for self-hosted models

Self-hosted and gateway models (Ollama, vLLM, custom endpoints) often aren't in Omnigent's pricing catalog, so their sessions show no cost. Add a pricing block to a provider family in your config to tell Omnigent what the model costs, and it will track spend for those sessions like any catalog model.

# ~/.omnigent/config.yaml
providers:
  ollama-local:
    kind: local
    openai:
      base_url: http://localhost:11434/v1
      api_key: ollama
      pricing:
        input_per_million: 0.0
        output_per_million: 0.0

Prices are specified per million tokens in USD. input_per_million and output_per_million are required; cache_read_per_million and cache_write_per_million are optional. When the cache rates are omitted, Omnigent derives them from the input rate using standard fallback ratios (cache read ≈ 0.10×, cache write ≈ 1.25×). All values must be >= 0.

      pricing:
        input_per_million: 0.25
        output_per_million: 1.0
        cache_read_per_million: 0.025
        cache_write_per_million: 0.3125

Configured pricing takes precedence over the catalog, so a gateway that serves a catalog-known model id (for example claude-sonnet-4-6) under its own rates is priced with your configured values rather than the vendor's. Pricing is attached to the provider family (anthropic or openai) that the session's harness uses.

Note: Custom pricing is resolved from the default provider for the session's harness. Sessions that select a named provider differing from the default may not be priced with these rates.

Databricks

Route models through your Databricks workspace using the Foundation Model API. Omnigent resolves credentials from your ~/.databrickscfg profile.

executor:
  harness: claude-sdk
  model: databricks-claude-sonnet-4-6
  auth:
    type: databricks
    profile: <your-profile>

Model names are prefixed with databricks- so Omnigent routes them through your workspace automatically. See the Databricks Foundation Model API docs for the full list of available models.