Switching Codex Providers: Configuration, Session History, and Repository Evidence

To switch Codex provider context safely, change provider and authentication at user scope, treat old sessions as provider-bound records, and rehydrate the task from revision-bound repository evidence. A working route proves connectivity. It does not transfer the previous model’s architecture judgments, file selection, dependency understanding, or private reasoning.

This guide separates the official Codex configuration model from third-party routing features and from the evidence a model needs to continue a large repository task.

Quick Verdict

The correct switch procedure depends on which layer changed.

Layer	What can move	What does not move automatically	Safe response
Provider configuration	Model provider ID, base URL, wire API, headers, and credential source	Repository conclusions	Configure at user scope and verify with a new process
Third-party route	Active CC Switch profile, local proxy, protocol conversion, model mapping	Equivalent provider behavior	Confirm provider, protocol, route, and model separately
Session history	Visibility, record classification, readable plain-text history	Backend-specific encrypted reasoning or reliable continuation	Resume on the original backend or start a fresh session
Repository evidence	Commit-pinned paths, symbols, dependencies, tests, owners, decisions	Private chain of thought	Build a reviewed, provider-neutral task packet

OpenAI’s Codex documentation defines custom model providers in config.toml: a provider can specify its base URL, wire API, authentication, and headers, and model_provider selects it. Provider switching therefore changes the connection contract. It does not define an automatic migration of task state.

What a Codex Provider Switch Changes

Official Codex supports custom providers and profiles. The advanced configuration guide shows model_provider and [model_providers.<id>] entries for user configuration, including environment-key and command-backed authentication. It also documents one-run overrides and named profile files under ~/.codex/.

Provider and authentication configuration has an important security boundary: project .codex/config.toml files cannot override keys that redirect credentials or change provider authentication. Codex ignores project-local model_provider, model_providers, openai_base_url, and related protected keys. Put provider and authentication settings in user-level ~/.codex/config.toml or a user profile, not in repository configuration.

A third-party manager can edit or route those settings, but it does not become an official Codex capability. CC Switch is a community project that manages provider profiles and can put a local protocol-conversion route between Codex and an upstream. Its Kimi guide converts Codex Responses requests to Chat Completions and back. Its Claude guide converts between Codex Responses and Anthropic Messages. Both recommend restarting Codex after switching so the running process reloads configuration and model-catalog state.

Codex++ has a different boundary. Its own repository calls it an unofficial tweak loader for the Codex desktop app. It patches the local app to load UI and main-process tweaks; it says it does not replace Codex or proxy the user’s account. Codex++ is not a provider switcher and should not be cited as a way to transfer codebase context.

After any provider change, verify:

• the effective user-level model_provider;
• the selected model and provider-specific model ID;
• direct connection versus local proxy;
• wire protocol and conversion path;
• credential source without printing the credential;
• whether the active CLI process loaded the new configuration;
• tool availability, sandbox, and approval behavior.

Session History Is Not Repository Understanding

Session history preserves records, not a portable mental model. CC Switch’s unified Codex session-history feature illustrates the difference precisely. Its guide says unification changes only the session’s model_provider classification tag, optionally migrating existing records after making backups. Official and third-party sessions can then appear in one history list.

That normalization does not make reasoning provider-neutral. The guide warns that cross-provider resume may fail because encrypted_content can be decrypted only by the backend that created it. A session can be visible and readable but not continuable through the new provider.

Even when resume works, the transcript may contain:

• conclusions tied to an older commit or dirty worktree;
• tool output that no longer reflects current files;
• model-specific interpretations presented without provenance;
• rejected paths that look like recommendations when excerpted;
• an incomplete list of consumers, tests, or generated artifacts;
• assumptions about tool calling, context capacity, or output format.

Therefore, do not equate “CC Switch repository memory” with repository understanding. CC Switch can expose session records, provider configuration, MCP, and Skills. Its public materials do not describe a native, provider-neutral code graph that transfers verified system relationships into a new model.

For cross-provider work, use old history to recover task chronology and unresolved questions. Rebuild important claims from source and tests.

Build a Model-Independent Repository Evidence Layer

A model-independent layer stores facts that another provider can inspect without relying on the old backend’s private reasoning. It should combine source-controlled instructions, architecture decisions, generated structural evidence, task boundaries, and verification output.

Build it in five parts:

1. Identity: repository, branch or worktree, commit, dirty-file list, and task owner.
2. Scope: requested outcome, non-goals, protected paths, acceptance criteria, and allowed external systems.
3. Structure: relevant packages, files, symbols, imports, calls, schemas, generated artifacts, tests, owners, and decision records.
4. Provenance: source location, graph revision, extractor version, deterministic or inferred status, and freshness timestamp.
5. Verification: commands already run, exact results, known failures, remaining risks, and required approvals.

The graph is a retrieval aid, not the final authority. Dynamic registration, reflection, configuration, generated code, and out-of-repository consumers can be absent. Make the destination model open source behind high-impact edges and rerun tests before it edits.

Keep the artifact provider-neutral. Do not store opaque reasoning ciphertext, vendor-specific token traces, or unsupported summaries as repository facts. Label a statement as one of:

• Verified fact: confirmed in source, an authoritative document, or a reproducible command.
• Model-specific hypothesis: a useful interpretation that still needs evidence.
• Human decision: an approved constraint, exception, or trade-off with an owner.
• Stale or disproved: retained only for audit history and excluded from the active plan.

The generic shared-context guide remains the canonical owner for cross-tool repository context. The CC Switch codebase-context guide covers CC Switch-specific failure modes.

Provider Switch Checklist

Use the switch as a controlled handoff, not a mid-sentence backend substitution.

Prepare

• Pin the commit and capture uncommitted changes.
• Save the goal, non-goals, acceptance criteria, and current plan.
• Export task-relevant graph evidence with source locations.
• Mark model-specific assumptions and unresolved failures.
• Record the old provider, model, route, and session ID.
• Remove secrets and sensitive data from the handoff.

Switch

• Change provider/auth only in user-level configuration or an authorized third-party manager.
• If CC Switch routing is involved, confirm the provider card, local route, app-level toggle, protocol, and model mapping.
• Restart Codex when the process must reload configuration or model catalogs.
• Do not use Codex++ as evidence that provider routing changed.

Validate

• Confirm effective provider and model without exposing credentials.
• Start a new session when cross-provider resume fails or provenance is ambiguous.
• Load the provider-neutral task packet.
• Reopen source behind high-impact relationships.
• Restate the plan and compare it with the saved constraints.
• Rerun focused tests, then broader repository-required checks.
• Review the final diff for assumptions introduced after the switch.

If the new model cannot reproduce the old plan from current evidence, stop and plan again. Continuing from an unverifiable summary is faster only until it produces the wrong change.

FAQ

What should be retested after switching providers?

Retest the behavior the task changes, protocol-sensitive tool calls, structured outputs, patch application, and every repository-required build, type, lint, contract, integration, or security check relevant to the diff. Also repeat discovery checks for callers, generated artifacts, schemas, and tests if the old list was model-derived rather than source-linked.

How should model-specific assumptions be marked?

Label them explicitly as hypotheses with the originating provider, model, session, repository revision, evidence inspected, and required confirmation. Promote an assumption to a verified fact only after current source, authoritative documentation, or a reproducible test supports it. Keep human decisions separate and name their owner.

When should a task restart from planning?

Restart from planning when the session cannot resume, the repository revision changed, the new provider disputes a high-impact assumption, graph evidence is stale, required tools differ, acceptance criteria are unclear, or focused tests contradict the inherited plan. Planning should also restart when the old task packet lacks provenance for files, dependencies, or safety constraints.

Conclusion

Switching Codex providers changes configuration and routing, not repository understanding. Official Codex protects provider and authentication settings at user scope; CC Switch can manage third-party routes and session visibility; Codex++ loads desktop tweaks. These are separate tools with separate boundaries.

Carry the task through a model-independent evidence layer: pin the revision, preserve source-linked structure, label assumptions, and record tests. Then let the new provider verify that packet in a fresh session. If it cannot reproduce the plan, restart planning before changing code.