Three ways to authenticate
Pick whichever fits the moment. Anything you set later shadows what came before for that provider.
| Method | When to use | Example |
|---|---|---|
| Environment variable | Scripts, CI, first-run smoke tests. Nothing on disk. | ANTHROPIC_API_KEY=sk-ant-… omp |
/login | Interactive. Walks the OAuth flow when the provider supports it, otherwise prompts for a key. Stored in ~/.omp/agent/agent.db. | /login anthropic |
config.yml / models.yml | Declarative. Pin a key (or env var name) per provider so a fresh checkout is ready without an interactive step. | apiKey: MYCO_API_KEY |
/login appends — it does not replace existing credentials. /logout <provider> clears them. See Slash commands for the full /login surface, and Environment variables for the API-key var per provider.
OAuth-capable providers
These providers let you sign in with an existing account instead of pasting a raw key. /login <provider> opens the flow; the refreshed token is stored in agent.db and rotated before each call.
| Provider | /login id | Notes |
|---|---|---|
| Anthropic (Pro / Max) | anthropic | Browser flow against console.anthropic.com. Falls back to a key prompt if you cancel. |
| OpenAI Codex | openai-codex | ChatGPT account flow. Usage-aware rotation skips keys near their 5h or weekly cap. |
| GitHub Copilot | github-copilot | Device-code flow against github.com or your Enterprise host. On success the full Copilot catalog (Claude, GPT, Gemini, Grok) auto-enables. |
| Gemini CLI | google-gemini-cli | Google account flow; uses the same credential as the gemini CLI. |
| Z.AI | zai | Key-paste only — no browser flow. Listed here because /login zai is the supported entry point. |
| Cursor | cursor | Browser flow against cursor.com. |
Every other provider authenticates with an API key — either via its *_API_KEY env var or via /login which will prompt for the key.
Resolution order
When omp needs a credential for a provider, it walks this list and returns the first hit:
-
--api-keyruntime override on the omp process. -
Stored API key in
agent.db. When several keys are stored for the same provider, calls are round-robined. -
Stored OAuth credential in
agent.db, refreshed on demand before each call. -
Provider env var (
ANTHROPIC_API_KEY,OPENAI_API_KEY,GEMINI_API_KEY,ZAI_API_KEY, …). -
apiKey:field inmodels.yml. Checked as an env-var name first, then treated as a literal token.
When both an API key and an OAuth credential exist for the same provider, the API key wins. Set
ANTHROPIC_OAUTH_TOKENexplicitly to force OAuth precedence.
For the complete env-var inventory, see Environment variables. For where global and project config files live, see Settings.
Remote credential vault (auth broker)
Multi-machine setups can share one credential set instead of running /login on every box. Stand up the broker once:
omp auth-broker serve --bind=127.0.0.1:8765
omp auth-broker token # prints the bearer token (--regenerate rotates it)
omp auth-broker migrate --from-local # one-time migration from agent.dbPoint clients at it with OMP_AUTH_BROKER_URL + OMP_AUTH_BROKER_TOKEN (or the matching auth.broker.* keys in config.yml). In broker mode /login, /logout, and OAuth refresh all proxy through the remote vault; the local agent.db stays empty. The client keeps a 5 min per-credential usage cache with jitter and a last-known-good fallback, plus a 15 s single-flight in front of /v1/usage, so transient hiccups don’t fail calls.
For tooling that speaks raw provider wire formats (CLIs, scripts, third-party agents), pair the broker with omp auth-gateway serve — a forward-proxy that injects broker-resolved credentials into OpenAI Chat, Anthropic Messages, and OpenAI Responses requests. Point those clients at the gateway’s base URL with a gateway bearer token; the gateway calls back into the broker on every request, so credential rotation and /v1/usage accounting stay centralised.
Switching providers mid-session
/model opens the model picker scoped to providers you are signed into. /model <id> sets one without the UI. Switching does not log out the previous provider; it stays ready for the next call that targets it.
> /model
? Pick a model: anthropic/claude-sonnet-4-6
> /model openai/gpt-5.3-codex:highTo bind a provider for a single command, use --provider and --model on the launch line:
omp --provider openai --model gpt-5.3-codex:highSee Model roles to assign different providers to different kinds of work, and Custom models & providers to add your own.\n