Providers

Choose the route that fits

A provider is the account or backend, such as anthropic, openai-codex, or ollama. A model is selected as provider/model-id.

For most people, the shortest path is:

1. Start omp.
2. Run /model.
3. Choose a provider. Providers without credentials appear as not configured; select one and press Enter to start its login flow when available.
4. Choose a model after login finishes.

Use this table if you already know how you want to authenticate:

Account subscriptions and developer APIs are often separate products. For example, ChatGPT credentials use openai-codex; openai expects OPENAI_API_KEY. Google and xAI have similar splits. See Provider-specific caveats before guessing an ID.

Get one route working

Sign in with OAuth or a subscription

Inside an interactive session:

/login openai-codex

Follow the browser, device-code, or paste-code instructions shown by omp. For a remote terminal, the flow may ask you to paste the final redirect URL or code back as /login <value>. When a provider supports several accounts or workspaces, run /login <provider> again to add another one; omp can rotate managed accounts.

Then verify and select a concrete model:

omp models openai-codex
omp --model openai-codex/gpt-5.5

omp models <provider> prints only models currently available to this installation. Copy a selector from that output if the example model has changed. In an existing session, run /model or /model provider/model-id instead.

Use /logout to choose credentials to remove, or /logout <provider> to open that provider directly.

Use an API key

For a one-off launch or CI job, put the key in the process environment:

OPENAI_API_KEY=sk-... omp --model openai/gpt-5.5

For an interactive setup, many key-based providers also appear in /login; omp opens the provider's key page, asks for the key, validates it, and stores the credential. Providers without a login entry use their environment variable.

To persist an environment variable without adding it to shell startup files, omp loads .env files. An already-exported process value wins, followed by:

1. <current-directory>/.env
2. ~/.omp/agent/.env
3. ~/.omp/.env
4. ~/.env

Do not commit a project .env containing secrets. See Environment variables for every provider key name and the complete .env rules.

Verify the route before starting a long task:

omp models openai
omp --model openai/gpt-5.5 "Reply with the model provider and model ID you are using."

Use a local engine

omp probes these local providers automatically:

Start the engine and load a model there first. No login or config file is required for the default keyless endpoints. Then ask omp what it found:

omp models ollama

Copy a selector from the output:

omp --model ollama/model-id

If an engine is on another machine, set its base-URL environment variable. An explicit provider with the same ID in models.yml replaces automatic discovery. vllm is also a built-in provider route, but configure or authenticate it when it is not exposed as an unauthenticated local endpoint.

Add a custom provider

Use ~/.omp/agent/models.yml for an OpenAI-compatible, Anthropic-compatible, or other supported public endpoint. This minimal example reads the key from MY_GATEWAY_API_KEY:

providers:
  my-gateway:
    baseUrl: https://gateway.example.com/v1
    api: openai-completions
    apiKey: MY_GATEWAY_API_KEY
    models:
      - id: fast-chat
        name: Fast Chat
        contextWindow: 128000
        maxTokens: 8192

Set the key and verify the loaded entry:

export MY_GATEWAY_API_KEY=...
omp models my-gateway
omp --model my-gateway/fast-chat

apiKey is resolved as an environment-variable name first and otherwise as literal text. Prefer an environment-variable name so the secret stays out of the file. Use auth: none instead of apiKey for a genuinely keyless endpoint.

See Custom models & providers for other wire APIs, model discovery, headers, secret commands, compatibility options, and model overrides.

How models become available

At startup, omp assembles the model registry in this order:

1. bundled providers and known models;
2. provider overrides and custom models from ~/.omp/agent/models.yml or models.yaml;
3. cached or live discovery for supported providers and local engines;
4. providers and models registered by loaded extensions.

A custom model with the same provider and id replaces the bundled entry. Runtime discovery can update the models exposed by a provider; model overrides are reapplied afterward.

A model is selectable only when:

• its provider is not in the effective disabledProviders list; and
• the provider is keyless or has a credential omp can resolve.

Useful checks:

omp models                    # all currently available models
omp models find sonnet        # search provider, ID, selector, or display name
omp models refresh            # force fresh online discovery, then list

Inside the TUI, /model includes available models and shows catalog providers without credentials as locked. Selecting a login-capable locked provider starts its setup. Disabled providers are omitted.

For initial selection, an explicit --model wins. Without it, omp considers the active model scope, a saved default, known provider defaults, and finally the first available model. Prefer an exact provider/model-id when the same model ID exists through several routes; bare IDs and fuzzy --model patterns depend on the available catalog and configured provider order. See Model roles for persistent defaults and task-specific model choices.

Credential precedence

When several credentials exist for the same provider, omp uses the first applicable source:

1. runtime --api-key for this process;
2. models.yml providers.<id>.apiKey;
3. stored OAuth credentials, refreshed when needed;
4. an API key stored by /login;
5. the provider environment variable, including values loaded from .env;
6. another stored API key, such as a broker-migrated key;
7. a custom-provider fallback resolver.

This means a stored OAuth login normally wins over ANTHROPIC_API_KEY in the environment, while a key explicitly pinned in models.yml wins over OAuth. Keep provider IDs separate when you want both account and API access available.

Local credentials normally live in ~/.omp/agent/agent.db. With an auth broker configured, login, logout, refresh, and credential reads use the remote store instead. See Secrets and auth for storage, multiple accounts, the auth broker, and the provider-compatible auth gateway.

Current provider matrix

The live catalog is authoritative: run omp models after authenticating. The groups below cover the current built-in model-provider IDs and the normal setup route.

Exact environment-variable names are intentionally centralized in Environment variables, because some providers accept more than one credential source.

Provider-specific caveats

Troubleshooting

The provider is locked or absent from omp models. Check its credential, then check whether it is disabled:

omp config get disabledProviders

A disabled provider stays unavailable even with valid credentials. Project settings can replace the global disabledProviders array; see Settings.

Login succeeded but the model list is stale. Run omp models refresh, then list the provider again. Dynamic catalogs may differ by account, workspace, region, or plan.

The wrong account or key is used. Compare your sources with the credential order above. Look for a pinned models.yml key, a stored OAuth account, an exported variable, and the four .env locations. Remove a managed account with /logout <provider>.

A custom provider is skipped. Run omp models; validation errors are printed before the list. A provider with explicit models needs baseUrl, an api value, and apiKey unless it declares auth: none.

A local provider returns no models. Confirm the engine is listening at the effective base URL and has a model loaded. Then run omp models refresh. An empty or unreachable local endpoint remains unavailable.