[Feature/UX]: add additive Claude Desktop catalog mode with honest native/OpenCodex switching

[str0203]

Client or integration

Claude Desktop 3P profile

Area

Claude Desktop integration / catalog / configuration UX

Current status

The original destructive-restore defect is partially resolved.

PR #1106 added a real Claude Desktop integration toggle and a safe OFF/native pivot:

• claude-desktop is tracked as a native client integration;
• OFF pivots to a credential-free standard profile before removing the OpenCodex-owned gateway profile;
• owned backup and metadata state are cleaned up under the integration contract;
• desired OFF state is persisted so later provider changes do not silently re-enable the integration;
• ownership/drift inspection refuses unsafe mutations instead of blindly rewriting foreign state.

Therefore this issue no longer needs to claim that OpenCodex has no safe restore path.

The issue remains open because the reopened request is broader: users want an honest way to keep or switch between Claude-native access and OpenCodex-routed models, ideally in one picker where the installed Claude Desktop contract permits it.

Remaining goal

Provide the best supported Claude Desktop experience for users who want both:

native Claude-family access
+
selected OpenCodex-routed models

without silently changing credential or billing provenance.

There are two materially different meanings of "additive" and they must not be conflated.

1. True first-party coexistence

Ideal behavior:

Claude Desktop keeps its first-party subscription provider and credential
+
OpenCodex adds extra routed models

This requires a supported Claude Desktop mechanism for either:

• multiple inference providers in one active profile; or
• first-party credential passthrough while a gateway base URL is active.

Current OpenCodex configuration writing alone does not prove that capability exists.

Adding official-looking claude-* rows to inferenceModels is not sufficient if the gateway cannot receive or safely resolve the user's original first-party credential.

If current Claude Desktop does not expose a supported coexistence contract, OpenCodex must say so rather than simulate native access.

2. Unified gateway catalog

A practical approximation may be possible through one OpenCodex gateway catalog containing:

• selected routed OpenCodex models; and
• Claude models served through an explicitly configured OpenCodex Anthropic OAuth/API credential.

That can provide one combined picker, but those Claude entries are gateway-routed. They are not automatically the untouched first-party Claude Desktop subscription provider.

The UI must expose that difference clearly and must never silently turn subscription-backed Claude access into separately billed Anthropic API traffic.

Desired user modes

The Desktop integration should converge on explicit modes such as:

Native Claude
  Do not apply an OpenCodex inference profile.

Additive / unified gateway
  Show Claude-family routes and selected OpenCodex routes together.
  Available only when the required credential/routing contract is proven.

OpenCodex only
  Use the OpenCodex gateway catalog without implying native-provider coexistence.

If true coexistence is unavailable, the supported fallback should be fast, reversible profile switching:

Use native Claude configuration
Use OpenCodex configuration

The user should not need to edit Claude-3p/configLibrary/_meta.json manually.

Required investigation

Before implementing true additive first-party mode:

1. Probe the current supported Claude Desktop configuration contract.
2. Determine whether first-party Claude OAuth can be preserved or forwarded when a gateway profile/base URL is active.
3. Determine whether one active profile can expose more than one credential/provider provenance safely.
4. If the answer is no, treat true first-party coexistence as an upstream limitation.
5. Only then implement the strongest supported local mode.

Provenance requirements

Any combined catalog must make routing provenance explicit enough that users can distinguish entries such as:

Claude Opus 5 · native Claude
Claude Opus 5 · Anthropic via OpenCodex
GPT 5.6 Sol · ChatGPT pool via OpenCodex

Exact labels can follow the final UI design, but the product must not hide meaningful credential or billing differences behind identical model names.

Safety requirements

• Never silently replace a first-party Claude credential with a separately billed API credential.
• Never claim native coexistence when the client only supports one active gateway provider.
• Preserve exact routed model IDs where required by the gateway.
• Switching modes must be reversible and survive restart.
• Desired OFF/native state must continue to prevent later auto-apply from restoring an unwanted gateway profile.
• Foreign or drifted Desktop configuration must continue to fail safely.

Acceptance criteria

Already delivered

• Claude Desktop has an OpenCodex integration toggle.
• OFF has a safe standard/native pivot instead of requiring manual _meta.json surgery.
• Desired OFF state survives later OpenCodex activity.
• Owned/drifted/foreign Desktop state is classified before mutation.

Remaining work

• The current Claude Desktop coexistence capability is verified rather than guessed.
• The UI offers explicit Native Claude / OpenCodex mode selection.
• If true first-party coexistence is supported, an additive mode preserves the first-party credential correctly.
• If true coexistence is not supported, the UI explains that limitation before applying a gateway profile.
• A unified gateway mode, if provided, requires explicit OpenCodex-managed Anthropic credentials and exposes their provenance.
• No silent credential or billing substitution occurs.
• Native/OpenCodex switching is one action, reversible, and restart-safe.
• Catalog entries make meaningful provider/credential provenance understandable.
• Regression coverage protects restore, switching, drift refusal, and provenance behavior.

Close condition

Close when Claude Desktop users have either verified additive coexistence or an explicit, honest, reversible mode-switching experience that does not misrepresent native access.

[github-actions]

_{Automated translation bookkeeping — detected language: unknown.}

[github-actions]

Maintainer decision respected

A maintainer has reopened this issue. The automated closure has been deactivated.

[str0203]

Follow-up enhancement proposal: Additive Claude Desktop catalog mode

The ideal user experience is not merely a safer replacement flow. Users want to keep their existing Claude models and add selected OpenCodex routes to the same picker.

Feasibility boundary

There appear to be two materially different meanings of “native + routed models”:

1. True first-party coexistence

Claude Desktop keeps its existing first-party subscription models and credentials, while OpenCodex adds extra model routes.

This does not appear implementable through the current OpenCodex Desktop writer alone:

• Claude Desktop serves only the configuration selected by one configLibrary/_meta.json.appliedId.
• The generated OpenCodex config selects one inferenceProvider: "gateway".
• OpenCodex currently sets inferenceCredentialKind: "static" and supplies a gateway key.
• Consequently, the Desktop's first-party subscription credential is not necessarily sent to the gateway.
• Adding official-looking claude-* rows to inferenceModels is not sufficient if the gateway cannot receive or safely resolve the user's original first-party credential.

If Claude Desktop exposes a supported credential-passthrough or multi-provider mechanism, OpenCodex could use it. Otherwise, this part should be documented as an upstream limitation rather than simulated unsafely.

2. Unified gateway catalog (implementable approximation)

OpenCodex can potentially expose one combined gateway catalog containing:

• selected routed OpenCodex models; and
• genuine Claude models routed through an explicitly configured OpenCodex Anthropic OAuth/API credential.

This would produce the desired combined picker, although the Claude entries would be gateway-routed rather than the untouched first-party Desktop provider.

This mode must clearly disclose credential and billing provenance. It must never silently turn a Claude subscription model into separately billed Anthropic API traffic.

Proposed modes

The Desktop page could offer an explicit mode selector:

Native Claude
  Do not apply an OpenCodex inference profile.

Additive / unified gateway
  Show Claude-family routes and selected OpenCodex routes together.
  Requires a usable Anthropic credential managed by OpenCodex.
  Clearly labels which credential/provider serves each model.

OpenCodex only
  Replace the picker with the selected OpenCodex routes (current static behavior).

If true additive mode is not possible, provide a supported profile-switching fallback:

Use native Claude configuration
Use OpenCodex configuration

Switching must preserve both profiles and require only one click, without editing _meta.json manually.

Suggested implementation investigation

1. Probe whether current Claude Desktop can forward first-party OAuth while using a gateway base URL.
2. If supported, add official Claude IDs to the same generated catalog and use the existing native-passthrough path.
3. If not supported, implement unified gateway mode only when an explicit Anthropic credential is configured.
4. Preserve the previous applied configuration and expose restore/switch actions.
5. Store the selected Desktop mode and stop autoApplyDesktopBestEffort() from always rewriting it as static.
6. Add provenance labels such as:
   • Claude Opus 5 · native passthrough
   • Claude Opus 5 · Anthropic OAuth via OpenCodex
   • GPT 5.6 Sol · ChatGPT pool via OpenCodex

Acceptance criteria

• Applying an additive mode does not silently remove expected Claude-family access.
• The UI accurately distinguishes first-party passthrough from OpenCodex-managed Anthropic OAuth/API access.
• No silent credential substitution or separately billed API fallback occurs.
• The exact request model ID remains stable.
• Native/OpenCodex profile switching is reversible and survives restarts.
• If the installed Claude Desktop version cannot support coexistence, the UI explains the limitation before applying anything.

This would turn the current destructive replacement workflow into either real coexistence where supported, or an honest and reversible approximation where it is not.