--- title: Switching between AI providers --- # Switching between AI providers ## What it is Omniscio supports multiple AI providers — you are not locked into a single backend. There are two independent provider concerns that control different things: 1. **Session provider** — which CLI or agent engine runs your coding sessions (the chat where Claude reads files, writes code, runs commands). Options include Claude Code, Codex, Gemini, DeepSeek, Kimi, Kimi Code, OpenCode, Cursor, Grok, OpenClaw, and more (see the full table below). 2. **Utility AI model** — the cheap, fast model for the small background AI tasks Omniscio runs on your behalf (reply suggestions, Omni briefings, TTS/voice intent). This is **hardcoded** (no user setting — a former AI Provider panel was removed). See [ai-providers.md](ai-providers.md), which also covers the per-surface model pickers that DO let you choose (Omni briefing, summaries, suggestions). This page covers **session providers** — how to pick which engine runs your coding sessions, at three levels: per-session, per-project, and globally. ## Where to find it ### How to enable an alternative provider All alternative providers are hidden by default. To see them: 1. **Open Settings -> Accounts.** 2. **Flip "Show alternative AI providers" to ON.** This reveals the setup panels for every non-Claude provider. With it off, the provider switcher and per-project default radios are hidden — Claude is the only option in the UI. (**OpenClaw** is the exception — it's a managed remote gateway configured under **Settings → Advanced → OpenClaw**, not the Accounts panel; see [openclaw-provider.md](openclaw-provider.md).) 3. **Set up the provider you want.** Each provider has up to three gates that must all be green — but **which** gates apply differs per provider (the table above is the authority): - **Toggle** — "Allow X sessions" must be ON (prevents accidental spawns from a pasted key). Every provider has this one. - **Binary** — the CLI must be installed and on your PATH (click "Install" in the Settings panel if missing). Not needed for OpenClaw (cloud-hosted). - **API key** — paste the provider's API key. Stored encrypted at rest. Never sent to the renderer. **Not every provider has this gate.** Codex, Gemini, Kimi Code and Hermes authenticate with their own CLI login instead, so with the toggle on and the binary found they are ready and spawn keyless — a pasted key there is an optional override, not a requirement. **Cursor is the exception that genuinely requires a key**, because `cursor-agent login` does not authenticate headless turns. The Settings panel shows the status of each gate with a green checkmark or a red "Set up..." / "Install..." / "Add key..." label. Click the label to jump to the right field. ## How it behaves ### Available session providers | Provider | What it is | Requires CLI binary? | Requires API key? | | -------------------- | ------------------------------------------------------------------------- | --------------------------------------- | ----------------------------------------------------------------------------- | | **Claude** (default) | Anthropic's Claude Code CLI | Yes (ships with Claude Code) | OAuth login or API key | | **Codex** | OpenAI's Codex CLI agent | Yes (`npm i -g @openai/codex`) | No — your own `codex login` (a pasted key is optional) | | **Gemini** | Google's Gemini CLI agent | Yes (`npm i -g @google/gemini-cli`) | No — your own Gemini Google sign-in (a pasted key is optional) | | **Antigravity** | Google's Anti-Gravity CLI agent (`agy`) | Yes | Antigravity credentials | | **DeepSeek** | DeepSeek via Claude CLI redirect | Yes (reuses Claude CLI) | DeepSeek API key | | **Kimi** | Moonshot Kimi via Claude CLI redirect | Yes (reuses Claude CLI) | Kimi API key | | **GLM** | Zhipu GLM (z.ai) via Claude CLI redirect | Yes (reuses Claude CLI) | GLM API key | | **MiniMax** | MiniMax (api.minimax.io) via Claude CLI redirect | Yes (reuses Claude CLI) | MiniMax API key | | **Meta** | Meta Muse Spark (api.meta.ai, bare-host endpoint) via Claude CLI redirect | Yes (reuses Claude CLI) | Meta API key | | **Qwen** | Alibaba Qwen via DashScope (dashscope-intl) Claude CLI redirect | Yes (reuses Claude CLI) | Qwen (DashScope) API key | | **Cursor** | Cursor's CLI agent | Yes | **Yes — required.** `cursor-agent login` does not authenticate headless turns | | **Grok** | xAI's Grok Build CLI (`grok`, `grok-build-0.1` model) | Yes (installs to `~/.grok/bin`) | xAI API key (`XAI_API_KEY`, shared with Grok voice) | | **Hermes** | Nous Research's Hermes CLI (`hermes`, model-agnostic) | Yes | Its own model/provider key (`hermes setup`) | | **Kimi Code** | Moonshot's own Kimi Code CLI (`kimi acp`; distinct from **Kimi** above) | Yes (install `kimi`, then `kimi login`) | No — its own `kimi` login (Kimi Code OAuth or Moonshot key) | | **Pi** | Pi local coding agent (`pi --mode rpc`, any model) | Yes | Its own provider key (Claude / GPT / Gemini / OpenRouter) | | **OpenCode** | OpenCode CLI (Anthropic-compatible) | Yes | Anthropic API key | | **OpenClaw** | Remote gateway (WebSocket) | No (cloud-hosted) | Gateway URL + auth token | Claude is the default and always ready if you have an account. Every other provider is opt-in. For **DeepSeek, Kimi, GLM, MiniMax, Meta and Qwen** (and OpenRouter), an API key is one way to pay, not the only one: each of these model families has a **supply list** that can also pay with Omniscio credits, and a session connects through the first row of that list that can serve. You set it in **Settings → Accounts → Who pays & who serves** — see [model-vendors.md](model-vendors.md). > **Two of these aren't chosen from the per-session picker or the per-project "Default provider" radios below.** **OpenCode** spawns from its own **"Allow OpenCode sessions"** toggle rather than appearing in the picker, and **OpenClaw** is a managed remote gateway you use by opening its **OpenClaw** project (see [openclaw-provider.md](openclaw-provider.md)) — so neither shows up as a selectable radio/picker row like the others. (The inbuilt **Terminal** is likewise not a pickable AI provider; you open it with the dedicated Open-Terminal button.) ### Worktree isolation (all engines) Every session provider — Claude, Cursor, and the seven CLI engines (**Gemini, Grok, Codex, Antigravity, OpenCode, Hermes, Pi**) — can run in its own **isolated git worktree**: a throwaway copy of your repo where the agent works, so its edits stay off your real project files until the session ends, at which point the work merges back into your base branch (same as Claude). - **When it kicks in:** whenever your "isolate sessions by default" setting (or a per-session isolation override) is on **and** the project is a real git repo. A non-git or virtual project runs in place, with no worktree. - **Why it matters for these engines:** the CLI engines auto-approve their own edits, so isolating them keeps auto-approved changes in a sandbox instead of your live checkout. If isolation is requested but the worktree can't be created (e.g. no disk space), the session stops with an error rather than running in your real project folder. - Cursor still isolates on its own trigger (to neutralize a repo's `.claude` hooks); the seven engines follow your isolation setting instead. ### Switching providers: three levels ### 1. Per-session (one-off override) On a **brand-new session** — before your first message — the **Harness button** (a small icon + the current engine's name) sits right in the "Start a new session" panel. Click it to open the dropdown. Once the conversation has started the picker leaves the screen: the header keeps a small **read-only** chip showing what's running, and you reach the switcher from the session's **⋯ menu → "Tool & model"**, which opens it as a popup (see [Switching partway through a chat](#switching-partway-through-a-chat) below). **It lists only the engines you've actually set up** — plus Claude Code (always available), whatever engine this session is currently on, and any custom engines you've added. Engines you haven't set up yet aren't listed inline; instead a **"Set up more harnesses…"** row at the bottom opens **Settings → Accounts**, where you enable and configure more engines. (The list fills in as each engine's setup is verified, so it only ever grows — it never flashes options you can't launch.) The optional Quick Launch engine picker (Settings → System → "Show engine & model picker") filters the same way and carries the same "Set up more harnesses…" row. Pick a provider and it applies to **this session only**. Other sessions and the project default are unchanged. The per-session chooser is organized as a **Harness → Provider → Model → Thinking** picker. You pick the **Harness** (the AI tool — "Claude Code", Codex, Gemini, …) first. Under **Claude Code** a second **Provider** dropdown makes the brain explicit — it lists the engines Claude Code spans (Claude, DeepSeek, Kimi, GLM, MiniMax) — so switching engines is a deliberate pick in its own pill, not a side-effect of choosing a model. (Single-brain tools like Codex/Gemini hide the Provider pill — there's only one brain.) Then the **Model** dropdown lists the chosen provider's models, and a **Thinking / reasoning** level if it has one. In Settings → Accounts you can choose **which tools appear** in the picker, or turn on **"Always use my default"** to hide the picker entirely (with a one-tap "Choose for this session" reveal). See [start-a-new-session.md](start-a-new-session.md) for the full picker. **Resellers are not engines.** Some GLM, DeepSeek, Kimi and MiniMax models are also served by resellers (DeepInfra, RunInfra, InferX). The **Provider** dropdown never lists a reseller, and the **Model** dropdown shows each model once, under its maker — so you always pick the maker's model. Who pays for it and which company answers is decided when the session connects, by that family's supply list in **Settings → Accounts → Who pays & who serves**; nothing on the session page changes it. A model that only a reseller offers (for example a Llama model on DeepInfra) can still be picked under that reseller. See [model-vendors.md](model-vendors.md). **A model whose engine isn't set up is greyed out, not offered-then-blocked.** In both the per-session **Model** dropdown and the Quick Launch model picker, a model whose backend engine fails its readiness gate (spawning off / no key / proxy not set up) is shown **disabled with a short "Set up" hint** instead of being pickable and then failing when you send. Pick a ready model, or open **Settings → Accounts** to enable that engine — the engine a session is _already_ on stays available. (This mirrors the exact readiness check the launch performs, so the picker never offers a choice that would dead-end.) ### Switching partway through a chat **You can change the engine mid-conversation, and the chat carries over.** Open the session's **⋯ menu** and choose **"Tool & model"** — the Harness, Provider, Model and Thinking pickers appear in a popup. (They deliberately don't sit on the screen for the whole life of a session; once the chat has started the header shows only a read-only chip, and the ⋯ menu is where you go to change it.) Pick a different engine partway through and the conversation you have had so far is handed to it, so it picks up where you left off instead of starting blank. It is the same session throughout — same entry in the sidebar, same transcript, same history. Nothing is duplicated and no new session is created. A few things worth knowing: - **A short note appears in the chat** at the point where the engine changed ("Now on Codex — this conversation was carried over"), so a shift in tone or capability is never a mystery. - **The first time you switch to a different vendor in a session, Omniscio asks first.** Carrying the chat over means sending it to a vendor that has never seen it, which is worth saying out loud once. After you have accepted it for that session, later switches are one click. - **It takes effect on your next message.** If the agent is mid-answer when you switch, that answer finishes on the old engine and the new one takes over from your next message. - **It costs nothing extra to prepare.** Unlike a [handoff](session-handoff.md), no summary is written and no AI call is made — the conversation is replayed from Omniscio's own database word for word. Your next message is a bigger one for the new engine to read, and that is the whole cost. - **A very long chat moving to a smaller-window engine gets trimmed** from the oldest end to fit. - **Changing just the model** (say Sonnet to Opus) stays within one engine, so nothing needs carrying at all — it simply applies to your next message. - **Coaching sessions cannot be switched off Claude**, so your personal coaching context is never sent to another AI provider. - **If the new engine can't start, nothing is lost.** Say you switch to Codex before signing in to it: the chat tells you why ("Codex isn't signed in — …") and that your conversation is saved. Fix the cause (sign in under **Settings → Accounts → Codex**), then send any message in the same chat and it carries on with the whole conversation. Don't start a new session — that is the one step that leaves the history behind. **Retry** on such a chat restarts it on the engine it is set to, never back on Claude. **Switch or hand off?** Switch when you want the same thread on a different engine. [Hand off](session-handoff.md) when the conversation itself has become the problem — it writes a summary that deliberately drops the dead ends and starts a fresh session, where a switch keeps everything. ### The engine badge The header shows a small **provider icon** right next to the session name. On **desktop**, every session shows its icon — Claude included (in its brand orange) — so you can always tell which engine is running at a glance (hover the icon for the engine's name). On a **phone**, the icon shows only when the session's engine **differs from that project's default**: a session running the default engine hides the icon to save space, while a non-default one — including Claude, when Claude isn't that project's default — still shows. Engines with no logo (e.g. recipe-run "orchestrator" sessions) show nothing. If you set a **non-default model** for the session, the header instead shows the engine icon and the model name together as **one small chip** — e.g. a Claude spark right beside "Sonnet 5". The icon stands in for the brand, so it isn't repeated in the text (you'll see "Sonnet 5", not "Claude Sonnet 5"), and the standalone icon is folded into that chip so the engine still shows exactly once. On a started DeepSeek, GLM, Kimi, MiniMax, Meta, Qwen or OpenRouter session, hovering that model chip on desktop also shows **who paid** for the session's latest connection — for example "Paid by: Omniscio credits" (see [model-vendors.md](model-vendors.md)). ### 2. Per-project default Each project can have its own default provider, so every new session in that project automatically uses it. 1. **Right-click the project** in the sidebar (or click the three-dot menu). 2. **Click "Edit"** to open the Edit Project dialog. 3. **Under "Default provider"**, pick the provider from the list. Each row shows the provider's **logo and full name**, and the selected one is highlighted with a check. A provider that isn't fully set up (spawning off, CLI missing, or no key) is **dimmed with an amber "!"** whose tooltip explains the gap, and is **not selectable** — so you can't set a default you can't actually run. (If a project's _current_ default later goes not-ready it stays shown as selected, so you're never locked out; only switching _to_ a not-ready provider is blocked.) The sidebar badge still reminds you to finish setup. 4. **(Optional) Pick a default model — and, where the engine supports it, a reasoning effort.** Right below the provider list, the **Default model** dropdown follows whichever provider you picked: choose Codex and you get its GPT-5 models, choose Gemini and you get Gemini's models, and so on. Engines that route their own model (e.g. Antigravity, Hermes) show no model dropdown. Claude and Codex also offer a **reasoning effort** dropdown. Leave either on **"Global default"** to keep inheriting your global setting. 5. Everything applies immediately. New sessions in this project start on the chosen provider, model, and effort — and you can still override any of them for a single session before its first message. To clear an override, pick **"Global default"** for the model/effort, or select **Claude** as the provider. When a project's default is set to a non-ready provider (toggle off, binary missing, or key missing), an **amber "!" badge** appears on that project's sidebar row. Hover it for a tooltip explaining the gap; click it to jump to Settings. The badge disappears as soon as you fix the issue. You can also set the default **provider** via the CLI control server: `curl -X PATCH -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" -d '{"defaultProvider":"codex"}' http://127.0.0.1:19519/project/`. Pass `null` to clear the override. (The per-project default **model** and **reasoning effort** are set in the Edit Project dialog, not over the CLI.) ### 3. Global default (all new projects) The **global default provider** is the engine every new session starts on, across every project that doesn't have its own per-project default. It defaults to **Claude**. Set it two ways: - **From a fresh session** — pick a different provider, then use **"Make it my default"** on the line that appears just below the picker. Its menu lets you choose **Only this hub** (this project's default provider) or **Everywhere** (the global one). Each row shows what that scope is currently set to, and an **"In effect"** tag marks the one that actually wins for this hub — so you can see why new sessions open on what they do. (There are no checkmarks: nothing here is saved yet, which is why the line appeared.) A toast confirms the save. This is the provider-level sibling of the model "Make it my default". - **In Settings → Sessions → Basics** — the **Default Provider** dropdown (shown only when "Show alternative AI providers" is on). A **per-project default still wins** over the global one. The global default only has an effect when alternate providers are shown — with them off, every session is Claude regardless of this setting. ### How sessions look different Non-Claude sessions are visually identical to Claude sessions — same sidebar, same streaming bubbles, same Ctrl+Enter to send, same archive / pause / snooze. The only visible difference is the **logo**: a small **icon-only provider badge** sits next to the session title in the header — no text. On **desktop** every session shows one (Claude included), so the logo is what tells them apart; on a **phone** the badge shows only for an engine that **differs from the project default** (see below). Most logos render in their **brand colour** (Claude's orange, Gemini's gradient, OpenCode's orange, DeepSeek / Antigravity / Cursor blue, Hermes amber); **Codex, Kimi and Pi stay monochrome** by brand. Hover the icon (desktop) for the engine name. On **desktop**, **every** session shows its icon — **Claude included and in its brand colour** — set apart from the header's archive / ⋯ buttons so it reads as a label on the title rather than a third button. On a **phone**, to save space the icon shows only when the session's engine **differs from its project default** — so a Claude session in a Claude-default project shows nothing, while a Codex session (or even a Claude session in a project whose default is Codex) still shows. (Internal-only engines with no logo — OpenClaw, recipe-run "orchestrator" — still show nothing.) ### The utility AI model (background tasks) This is the **other** provider concern — separate from session providers. It's the cheap, fast model behind small background tasks like session naming, reply suggestions, and TTS/voice intent. **It's hardcoded** to a cheap Groq model (Llama 4 Scout) — there's no panel to switch it. A "Settings -> AI Provider" panel used to let you pick it, but it was removed (2026-06-20): the default served virtually everyone, and every task that needs a different model already pins its own in code (session titles -> OpenRouter + Qwen, Omni -> Anthropic). If the model fails, Omniscio silently falls back to Anthropic Haiku so features keep working (the fallback is silent — the old amber Settings chip was removed with the panel). A few specific surfaces DO still let you choose their own model, each with its own picker in its own Settings section: **Omni briefing**, **Catch-Up Card summaries**, the **Email Summarizer**, and **Quick Reply suggestions**. Full details: [ai-providers.md](ai-providers.md). ### Troubleshooting **"The provider dropdown only shows Claude."** You need to flip Settings -> Accounts -> "Show alternative AI providers" to ON first. All non-Claude providers are hidden by default. **"I set up Codex/Gemini but I don't see it in the per-session Harness picker."** One of its gates isn't green yet — the per-session picker lists only fully set-up engines, so a half-configured one is hidden (use the **"Set up more harnesses…"** row to jump to Settings and finish). Check the gates that actually apply to that engine: for Codex and Gemini that is **toggle ON + binary installed** — they have no API-key gate and authenticate via your own `codex login` / Gemini Google sign-in, so a missing key is never the reason they are hidden. (In the per-project **"Default provider"** list a not-ready engine appears dimmed with an amber "!" that names the missing gate, and is **not selectable** — unless it's already this project's saved default.) **"I switched a project to Codex but it shows an amber ! badge."** The provider isn't fully set up. Hover the badge to see what's missing, or click it to jump to Settings. **"My Codex/Gemini session lost its history after restarting Omniscio."** It shouldn't. Codex and Gemini keep no transcript of their own, so after a restart Omniscio starts a fresh engine process and hands it your stored conversation as context with your next message; Claude resumes its own transcript via `--resume`. If a chat really did pick up blank, that is a bug worth reporting. **"I want all my background AI tasks (session naming, suggestions) to use a cheaper model."** That's the utility AI model, not the session provider — and it's already a cheap, fast model (hardcoded; there's no longer a panel to change it). A few surfaces still have their own model picker (Omni briefing, Catch-Up Card summaries, Email Summarizer, Quick Reply suggestions). See [ai-providers.md](ai-providers.md). **"My DeepSeek / Kimi / GLM session said the model was unavailable, or kept flipping between working and needing me."** These vendors run through the Claude engine against their own endpoint. If the vendor is briefly **overloaded** (a temporary "5xx / overloaded" hiccup), Omniscio now rides it out and retries automatically in the background — no action needed. If it's a real **account** problem — out of balance, an invalid API key, or a discontinued model — Omniscio shows the exact cause and the session **rests there** until you fix it (add credit, re-enter the key in Settings → Accounts, or pick another model) and send a message. **Running out of credit is the exception when another way to pay is ready:** if the family's supply list has another row that can serve, the session moves to that row and resends your message, and you are told once who pays now (see [model-vendors.md](model-vendors.md)). Only when no row can serve does it rest with the message, which then carries a one-click **Add credit** button opening the billing console of the company that served it, so you can recharge without hunting for the page. It no longer keeps retrying a hopeless request or flips back and forth between "working" and "needs you". **Want a different company or payer for these sessions?** Reorder that family's list in **Settings → Accounts → Who pays & who serves**; every session picks up the change at its next connection (a restart or a continue), with its conversation preserved. **"My DeepSeek / Kimi / GLM session hit a usage limit and went quiet."** These vendors cap how much you can use in a rolling window (for example GLM's 5-hour usage limit). When a vendor session hits that cap, Omniscio now posts a clear note in the session — naming the provider and saying it will resume automatically — and keeps quietly retrying in the background (retrying an over-limit request is free — the provider rejects it before it does any work) until the limit resets, at which point the session picks up where it left off and leaves your inbox. No action needed; it comes back on its own. If a provider stays capped for an unusually long time, it eventually rests in your **Needs You** inbox with that same note so you can resume it by hand. This is distinct from Claude's own rate-limit recovery (which also load-balances across your Claude accounts) — a vendor session normally has a single key, so Omniscio just waits out the vendor's limit and never touches your Claude accounts. **GLM is the exception** — if you set a fallback key, a GLM session switches to it and keeps going instead of waiting (see the next entry). **To keep going on a different provider instead of waiting**, put it on your **usage cascade** (Settings → Accounts → Usage cascade): a session that runs out on one of these vendors then moves to the first rung that is on, set up and not full — for example GLM → DeepSeek — with its conversation intact, and says so in the session. See [usage-cascade.md](usage-cascade.md). Kill switch: `AMC_DISABLE_VENDOR_RATE_LIMIT_RESUME=1`. **"Can a GLM session keep going after my main key runs out, instead of waiting or stopping?"** Yes — GLM (only) supports an optional **fallback API key**. In Settings → Accounts → GLM, add a second z.ai key in the "GLM Fallback API Key" box. Then whenever a GLM session's main key runs out of usage — whether that shows up as "out of balance" or a usage-limit throttle — that session automatically switches to the fallback key (billed per-token) and keeps going, instead of stopping or waiting. It's per-session and one-way for that session: new sessions always start on your main key again, so when your main plan's usage refills, fresh work returns to it on its own. If the fallback key ALSO runs out, the session stops with the normal message (it won't loop). Leave the fallback box empty to keep today's behavior. **"I attached an image to a Kimi Code or Hermes session — did it get through?"** These engines ask their own CLI on start-up whether it can read images. If it can, your image is sent straight to the agent (no file-path workaround). If it cannot, the image is not sent and the session shows a short note saying so — describe the image in words, or switch to an engine with image support. The same start-up answer decides whether your project's MCP servers are handed to the agent; if the CLI refuses to start with them, Omniscio starts it once more without them and tells you in the session. ## Related - [ai-providers.md](ai-providers.md) — utility AI model picker (background tasks, not sessions) - [codex-provider.md](codex-provider.md) — Codex setup, behavior, and internals - [gemini-provider.md](gemini-provider.md) — Gemini setup, behavior, and internals - [openclaw-provider.md](openclaw-provider.md) — OpenClaw remote gateway setup - [start-a-new-session.md](start-a-new-session.md) — launching sessions (provider-agnostic) - [account-pool.md](account-pool.md) — managing multiple Claude accounts