Omniscio

DeepSeek Provider

DeepSeek as an alternative session provider: how to switch it on and add a key, which V4 models you can pick and what each is good for, the two readiness gaps and their click-to-fix, and where DeepSeek's spend and context-window limits show up.

On this page

What it is

Omniscio supports spawning Claude-Code-style sessions backed by DeepSeek's Anthropic-compatible API as an additional provider, alongside claude (the default), codex, gemini, antigravity, the Anthropic-compatible kimi / glm / minimax / meta, cursor, hermes, grok, pi, opencode, and openclaw (the registry defines 26 session-provider keys, 20 of them user-selectable/pickable; the non-pickable ones include opencode, terminal — the managed inbuilt PTY engine — and openclaw).

What the user sees

A DeepSeek session looks identical in the sidebar and main pane to a Claude session — same status dots, same streaming bubbles, same Ctrl+Enter to send, same Plan / Auto-Accept / Bypass Permissions modes, same tool-call approval UI. The provider is invisible in normal chat. The only user-visible difference is the DeepSeek icon (a non-Claude provider mark, no text label) in the session header.

The harness is identical to Claude — same claude CLI binary, same streaming, same tool-call approval flow (there is no yolo / auto-approve mode like Gemini or Anti-Gravity). But the model is not: DeepSeek is a cheaper, weaker autonomous coding agent than Claude. Omniscio offers DeepSeek's V4.1 and V4 models — all unified dual-mode models that drive the Claude-Code tool protocol (DeepSeek's own Claude Code integration uses them). Omniscio defaults a DeepSeek session to DeepSeek V4.1 Flash (deepseek-v4.1-flash) when you haven't picked a model: DeepSeek bills it below V4 Pro while rating it above, and it reads images natively. Also selectable: deepseek-v4-flash (previous generation, fast and general), deepseek-v4-pro (high-capability), and the experimental DeepSeek V4 Flash Vision (deepseek-v4-flash-vision-exp, 2026-08), which adds image input to the old Flash tier; images are converted to tokens and billed as input either way.

The V4.1 Flash checkpoint itself was refreshed on 2026-10-17 (DeepSeek-V4.1-Flash-1017): the ids and the price are unchanged, the benchmarks moved up and turns got shorter, so a DeepSeek session picks the new snapshot up automatically. The OpenRouter lane carries the same checkpoint under its own slug, deepseek/deepseek-v4.1-flash-1017; see OpenRouter provider.

V4.1 Flash stalled for two days, and it was our routing (fixed 2026-09-11). V4.1 was added to the picker and made the default on 2026-09-09, and from then until 2026-09-11 a DeepSeek session that didn't name a model silently stalled — it never errored, it just sat there looking like it was waiting for you. The cause was not DeepSeek. An Omniscio-funded DeepSeek session went through Omniscio's own gateway, which then forwarded to a partner whose catalog only carried the older V4 models — that was history as of 2026-10-24: the managed lane now forwards straight to api.deepseek.com under the single id deepseek-flash, with DeepInfra kept as the failover. V4.1 wasn't in it, so the request came back empty. The commit that added V4.1 updated the picker, the pricing and the docs — but not the gateway's routing file, so nothing knew where to send it. The fix adds that route (V4.1 now goes to a provider that serves it) and keeps the default on V4.1. The gateway change needs to be deployed for this to take effect.

Also removed: a second, pre-launch id (deepseek-v4.1-flash-expires-on-0910) and the launch-date switch that chose between the two. Picking a model by a vendor's announced date, rather than by whether it actually answers, is what let a broken default go unnoticed — a session pinned to that retired id now says "pick another model" instead of stalling.

The older deepseek-chat (V3) / deepseek-reasoner (R1) aliases are gone from the picker too — DeepSeek hard-retired those ids on 2026-07-24 15:59 UTC and the endpoint rejects them after, which is why the picker moved to the V4 ids.

Where to find it

How to enable

Shown out of the box. DeepSeek is an alternative provider, and the alternative-provider section is visible by default — Settings → Accounts → Show alternative AI providers ships ON (a profile that last saved before 3 Oct 2026 keeps the old Claude-only view until you turn it on). Switch that master OFF and the entire DeepSeek setup section below is hidden in Settings → Accounts; switch it back ON and the DeepSeek panel appears alongside Gemini, Codex, Anti-Gravity, and Kimi. With the master off, the per-project "Default provider" radio collapses to a single Claude row and the session header's provider switcher (ChangeProviderButton) hides DeepSeek — DeepSeek effectively does not exist in the UI even if every gate below is configured. Your saved API key and "Allow DeepSeek sessions" toggle are preserved across master-toggle flips.

You need two of these in place (note: no binary check — same claude binary as Claude). The opt-in toggle leads and gates the key field — the API key input appears only once DeepSeek is turned on, so a key can't be entered into a disabled provider (when off, a hint keeps the deepseek-api-key Settings-search anchor landable and a saved key is preserved):

  1. Settings → Account → Allow DeepSeek sessions in any project — opt-in toggle, off by default; same security stance as the Codex/Gemini spawn guards. Turning it on reveals the key field below.
  2. Settings → Account → DeepSeek → API key — paste a DeepSeek API key from platform.deepseek.com (encrypted at rest via Electron safeStorage). Or skip the key entirely: who pays for a DeepSeek session is DeepSeek's supply list in Settings → Accounts → Who pays & who serves, which for a new user starts as your own DeepSeek key first and Omniscio credits second (an earlier choice you made carries over). With no key saved, sessions run on Omniscio's key and draw down your prepaid credit balance (signed-in only). Reorder the list to put credits first, or add a reseller row (DeepInfra, RunInfra or InferX) to have one of them serve the model on your own account there. See model-vendors.md.

Once both are green, you can launch a DeepSeek session in three ways:

  • Per-launch override — on a fresh (zero-message) session, the ChangeProviderButton in the new session's main panel (the launch-config pickers on a fresh session) lets you pick a one-off provider before sending the first message. Non-ready providers appear aria-disabled with an "Add key…" / "Enable in Settings…" suffix and deep-link to the right Settings panel.
  • Per-project default — Edit Project dialog (three-dot menu → Edit) has a "Default provider" section listing every enabled provider. Pick DeepSeek and the project's sidebar "+ New Session" button spawns DeepSeek automatically.
  • Programmatically — anything that creates a session with provider: 'deepseek' (recipes, agent-driven sessions, the CLI control HTTP API). Same readiness gates apply on the backend.

How it behaves

Choosing the model

A fresh DeepSeek session offers two entries, both the same model: DeepSeek V4.1 Flash (deepseek-v4.1-flash, newest, reads images) and DeepSeek V4.1 Flash 1017 (deepseek-v4.1-flash-1017), which names the 2026-10-17 checkpoint explicitly. DeepSeek's own API accepts only deepseek-flash, so on your own DeepSeek key Omniscio sends that id for both (the company gateway routes on the picker id, deepseek-v4.1-flash, so the company lane sends that one), and the same model can also be served by DeepInfra or RunInfra through the family's supply list (see Who pays & who serves). The older V4 Flash, V4 Pro and V4 Flash Vision (exp) were taken out of every menu on 2026-10-09, since V4.1 Flash outclasses all three. They are still accepted, so a session, project default or saved setting already on one keeps running and still shows its name, but nobody can pick one fresh (the hidden flag in provider-models.ts). New-user onboarding sessions run on V4.1 Flash too. All of these are unified dual-mode models that drive the Claude-Code tool protocol. The pick is staged locally and applied when you send your first message. Use default spawns V4.1 Flash rather than omitting the model flag — DeepSeek requires a real DeepSeek model id (the shared claude binary's built-in default is a Claude id its endpoint would reject), so the registry pins one via getProviderDefaultModel (in provider-models.ts). On an Omniscio-funded session the id must ALSO have a route in the gateway's own config — an EXACT row there, for the id the app actually sends, because deepseek/* is only a catch-all for ids the app does not offer (it points at api.deepseek.com, and the managed lane is served first-party by DeepSeek with DeepInfra as the failover). That mismatch is what stalled V4.1 for two days, and what failed every developer-lane turn in bug 2f7d81db; guards now require an exact row for each sent id. The legacy deepseek-chat / deepseek-reasoner aliases retire 2026-07-24 15:59 UTC, which is why the picker now offers the V4 ids directly. DeepSeek has no separate "reasoning effort" knob. The model list is DeepSeek's own — a DeepSeek session never inherits your Claude default model (those are Claude ids its endpoint would reject). See start-a-new-session.md.

Gift credit

An Omniscio super-admin can gift a person free DeepSeek usage: in Settings → User Management, open that person's row menu, pick Gift DeepSeek credit… and type an amount (more than $0, at most $100, whole cents). Nobody else can grant one.

  • Limits. All gifts together are capped at $250 a day (the day resets at midnight New York time), nobody can hold more than $100 of unspent gift, and an admin cannot gift their own account. A refusal says how much is left.
  • Confirm it's you. Granting needs a sign-in from the last 10 minutes. If yours is older, the app opens the Confirm it's you sign-in window and then sends the gift; an admin who signs in by email is asked to sign out and back in first.
  • Every gift is emailed to the owner with who gave it, who got it, the amount and the day's total.
  • Where you see it. Settings → Plan & Billing → credit balance card gains a DeepSeek gift line, shown only while the gift is above $0. Your paid credit figure is unchanged.
  • What it pays for. Only DeepSeek Flash models (V4.1 Flash, V4.1 Flash 1017, V4 Flash and the V4 Flash Vision experiment), when the session is paid by Omniscio credits. It does not pay for V4 Pro, other providers, or sessions on your own key. It is used after any plan allowance and before your paid credit; a turn the gift cannot cover is paid from your paid credit as usual.
  • Who serves it. Gift turns are served by DeepInfra and cost the gift only the real upstream price (no markup). If DeepInfra is down, DeepSeek can serve the turn instead, still at its real price.
  • It is not money. The gift is separate from paid credit: it cannot be bought, refunded or withdrawn, and it is deleted if the account is deleted.
  • No credit, no gift. With neither a gift nor credit, a DeepSeek session is refused as before.

Contract: deepseek-gift-credit-contract.md.

Per-project default

Each project remembers a default provider in the projectDefaultProviders setting (a Record<projectId, ProviderId>). Empty by default — every project falls back to Claude. Change it from the project's three-dot menu → Edit → Default provider radios; the change persists immediately.

When a project's default is set to DeepSeek but DeepSeek isn't ready (toggle off or key missing), an Inbox card names the project and provider and says in plain words what is missing. Its button opens the Settings screen where the gap is fixed, and the card clears itself once the provider is usable. The project's sidebar row itself carries no readiness marker.

Error states and fixes

Two gap codes — fewer than Gemini/Codex because there is no separate binary to check:

Gap What it means Click-to-fix lands you at…
toggle-off "Allow DeepSeek sessions" is OFF in Settings Settings → Account → Allow DeepSeek sessions toggle
key-missing No row of DeepSeek's supply list can serve right now — no DeepSeek API key, and no other row ready (Omniscio credits need you signed in; a reseller row needs its own key and switch) Settings → Account → DeepSeek API key field, or Settings → Accounts → Who pays & who serves

The real reason, not a blanket "model unavailable." When DeepSeek's endpoint rejects a request mid-session for a reason other than the model — the account is out of balance, the conversation outgrew the context window, the key became invalid, or you're rate-limited — Omniscio reads DeepSeek's actual error (carried on the zero-output synthetic placeholder, the same spot the Consumer-Terms gate reads) and shows the specific cause + fix (recharge / start fresh or pick a larger-context model / check the key in Settings / wait a moment) instead of the generic "this model may be unavailable — choose another," which now applies only to a genuinely unknown/retired model. Message-only — the session still parks as needs_you / recovery_failed. The company lane's own model refusal is named too (T-227): when the Omniscio gateway answers that the model is not available on the company lane, or the endpoint reports model_not_found (the shape a missing gateway route took in bug 2f7d81db), the session says the lane cannot run this model and offers the developer's own key — never "a busy lane clears within minutes". That refusal is terminal now, so stuck-session recovery no longer re-arms a session into it. A session that has not produced output yet leaves the lane on that refusal instead of retrying it in place; one that has already answered parks with the same wording. Out of balance is the exception when another row can pay: if DeepSeek's supply list has another row that can serve, the session moves to it and resends your message instead of parking (see model-vendors.md). See provider-spawn-model-availability-contract.md vendor-error-is-classified-and-named.

Context window — 1M real; compaction runs at 750K, on desktop AND cloud sessions (2026-10-09). DeepSeek V4 runs a real 1,048,576-token window (1M), far above the claude binary's ~200K assumption for a model it has no vendor row for. Left alone, a DeepSeek session auto-compacts at ~167K — the binary's own default point (its ~200K working window minus a ~33K reserve) — so Omniscio hands the binary two settings that move the point to 750K (see How it works under the hood). Until 2026-10-09 only DESKTOP sessions got them: a cloud (Box VM) or SSH DeepSeek session still compacted at ~167K, because the remote spawn never applied the rule. It now does, on every road. The history below is how the 167K default was first misread. An earlier attempt to push that to 400K via a setting turned out to be a no-op on the Claude version this app runs, so it was removed (see "The 400K story" below). If an overflow ever does slip through, the session auto-recovers on its own (rebuilds from its transcript and continues, bounded) instead of parking on the first hit; only if it genuinely can't recover does it fall back to the "conversation got too long" park. See context-limit-400-surfacing-contract.md.

Why not just use the whole 1M. Bigger is not better past a point: DeepSeek V4's measured recall is ~94% up to 128K and ~82% at 512K, but falls to ~66% at 1M, and the published sweet spot is 128K–512K. This is the industry-wide "context rot" effect — one study found all 18 frontier models tested degraded well before their stated limits. So a smaller working window is actually good for quality here, and the ~167K compaction point sits inside the high-quality band. (Omniscio also still nudges you toward a fresh session around 400K on this same quality basis — a separate suggestion from where the conversation compacts.)

The 400K story (2026-08-06 → corrected 2026-08-22). On 2026-08-06 DeepSeek sessions briefly compacted constantly — one live session compacted 10 times in 31 minutes before the CLI's own anti-thrash guard stopped the turn mid-work — because DeepSeek's window had been recorded as a stale 128K. That was corrected the same day to the real 1M, and a setting (CLAUDE_CODE_AUTO_COMPACT_WINDOW=433000) was added intending to place compaction at 400K. On 2026-08-22, live testing showed that setting is a no-op on the Claude version this app runs — DeepSeek had actually been compacting at ~167K all along (confirmed across 404 of 404 real compactions), so the dead setting was removed and DeepSeek now runs at the binary's ~167K default. A true 400K point would require a newer Claude binary. Full history: deepseek-compaction-thrash-postmortem.md. That ending was itself corrected on 2026-09-13 — the dial was not dead, it was half-set. See the compaction bullet under How it works under the hood: the binary resolves the dial as Math.min(believedWindow, dial), so the dial alone could never move a window the binary believed was ~200K. Paired with CLAUDE_CODE_MAX_CONTEXT_TOKENS, it works, and DeepSeek now compacts at 750K rather than ~167K.

A DeepSeek session said it was Claude Fable (fixed 2026-11-12)

What you saw. Asked for its exact model id, a DeepSeek session answered claude-fable-5-2, while its header and its cost said DeepSeek, and a copy of it on another of your computers showed no model at all.

Why. Two separate gaps. The claude binary treats a model pinned to its Fable alias as Claude Fable and tells it so in its instructions, and Omniscio pinned that alias to the DeepSeek model so sub-agents would not ask for a Claude model. And a DeepSeek session started with no model picked never wrote down which model it ran, so the computer showing it from afar had nothing to copy.

The fix. Sub-agents are now sent to the DeepSeek model directly and the Fable alias is left alone, so the session is told only the truth. A DeepSeek session started with no pick records the model it was started on (your saved default, or DeepSeek V4.1 Flash), so the header here and on your other computers names it.

Sub-agents on a DeepSeek session (fixed 2026-09-15)

What you saw. A sub-agent — anything a session hands a chunk of work to — died the instant it started, with "There's an issue with the selected model (claude-sonnet-5). It may not exist or you may not have access to it." The session itself kept working; only the helper it spawned failed.

Why. The --model flag pins only the session's MAIN loop. Every other model path the claude binary takes — the background model it uses for topic detection and compaction summaries, and a sub-agent that asks for a model by name — fell back to the binary's own built-in Claude names (claude-sonnet-5, claude-haiku-4-5-…). DeepSeek has never heard of those, so the request was rejected. It was invisible until a sub-agent asked for a model explicitly: a sub-agent with no model preference simply inherited the working session model and was fine, which is why this looked intermittent.

The fix. Omniscio now pins every model name the binary can fall back to — the opus / sonnet / haiku aliases plus the background model — onto the model your session actually runs, and forces every sub-agent onto that same model. Any sub-agent asking for "sonnet" or "fable" now gets the DeepSeek model instead of a Claude one it could never reach. The same fix covers Kimi, GLM, MiniMax and Meta, and the aside panel.

Last verified 2026-11-03