cc-switch Documentation

Technical Documentation: farion1231/cc-switch

ℹ️ Provenance: Multi-Tier Ingestion · CodeWiki Reference

Overview (`README.md`) Copy Section

❤️Sponsor Copy Chapter

Want to appear here?

Click to collapse

Kimi K3 is Moonshot AI's most capable model and the world's first open 3T-class model. With 2.8 trillion parameters, native vision, and a 1-million-token context window, K3 delivers frontier performance across long-horizon coding, knowledge work, and reasoning. CC Switch makes it easy to configure and switch to Kimi across agentic tools.

Try a Kimi Code plan (中文站 | Global), or use the API through the Kimi Open Platform (中文站 | Global).

New user top-up bonus: register and complete your first top-up via the API links above to receive 10% of the amount as bonus API credit, up to CNY ¥1,000.

Why CC Switch? Copy Chapter

AI coding tools like Claude Code, Codex, and Gemini CLI each have their own configuration format. Switching API providers means hand-editing JSON, TOML, YAML, or .env files, and MCP, Skills, and prompts have to be maintained separately in every tool.

CC Switch brings all of this into a single desktop app: pick a preset, enter your key, and switch in one click. Switching replaces only the connection details — endpoint, key, and model — so plugins, hooks, MCP, and comments you added yourself stay as they are.

• One App, Ten Tools — Claude Code, Claude Desktop, Codex, Gemini CLI, Grok Build, OpenCode, OpenClaw, Hermes, Pi, and MiniMax Code
• No More Manual Editing — 90+ provider presets including AWS Bedrock, NVIDIA NIM, and community relays
• Direct, Routing, or Aggregation — Your Choice — Direct connects the tool straight to the provider; Routing forwards requests through your machine, converting API formats and failing over automatically, so you can use GPT in Claude Code and Claude in Codex; Aggregation puts models from several providers into one model list in Claude Code or Codex, and each request goes to the provider of the model you pick
• Centralized MCP, Skills & Prompts — Add MCP servers and Skills once, then choose which tools to sync them to; prompts are maintained separately for each tool
• Sessions You Can Read — Turns each tool's session logs into a reading view: what each turn did, which files changed, and which step failed, all at a glance
• Usage & Quotas at a Glance — Track token usage and spending even without local routing; remaining subscription quota and account balances show right on provider cards and in the tray
• Cross-Platform — Native desktop app for Windows, macOS, and Linux, built with Tauri 2

Screenshots Copy Chapter

Download & Installation Copy Chapter

System Requirements Copy Section

• Windows: Windows 10 and above
• macOS: macOS 12 (Monterey) and above
• Linux: x86_64 or ARM64 with glibc 2.35+ and WebKitGTK 4.1 — e.g. Ubuntu 22.04+, Debian 12+, and recent Fedora releases; RHEL / Rocky / Alma 8–9 are not supported yet

Windows Users Copy Section

Download the latest CC-Switch-v{version}-Windows.msi installer or CC-Switch-v{version}-Windows-Portable.zip portable version from the Releases page. On Windows on ARM, download CC-Switch-v{version}-Windows-arm64.msi or CC-Switch-v{version}-Windows-arm64-Portable.zip.

macOS Users Copy Section

Method 1: Install via Homebrew (Recommended)

brew install --cask cc-switch

Update:

brew upgrade --cask cc-switch

Method 2: Manual Download

Download CC-Switch-v{version}-macOS.dmg (recommended) or .zip from the Releases page. It's a Universal build that runs natively on both Apple Silicon and Intel Macs.

Note: CC Switch for macOS is code-signed and notarized by Apple. You can install and open it directly.

Arch Linux Users Copy Section

Install via paru (Recommended)

paru -S cc-switch-bin

Linux Users Copy Section

Download the latest Linux build from the Releases page:

• CC-Switch-v{version}-Linux-x86_64.deb / -Linux-arm64.deb (Debian/Ubuntu)
• CC-Switch-v{version}-Linux-x86_64.rpm / -Linux-arm64.rpm (Fedora and other RPM distros that ship WebKitGTK 4.1)
• CC-Switch-v{version}-Linux-x86_64.AppImage / -Linux-arm64.AppImage (any distro meeting the requirements above)

Flatpak: Not included in official releases. You can build it yourself from the .deb — see flatpak/README.md for instructions.

Quick Start Copy Chapter

Basic Usage Copy Section

1. Add Provider: Select the tool you want to manage in the sidebar, then click "+" (Add Provider) in the top-right corner of the page → Choose a preset or create a custom configuration
2. Switch Provider:
   • Main UI: Select provider → Click "Enable" (for OpenCode, OpenClaw, Hermes, and MiniMax Code the button is "Add", and for Pi it's "Enable" / "Remove"; these five are coexist-mode tools, so you can add several providers at once)
   • System Tray: One row per tool showing "name · mode · provider · quota"; click a provider name in its submenu to switch (Claude Code, Claude Desktop, Codex, Gemini CLI, and Grok Build)
3. Takes Effect: Claude Code needs no restart; for Codex, Gemini CLI, and Grok Build, restart your terminal or the CLI tool; for Claude Desktop, restart the app itself (see FAQ)
4. Back to Official Login: Switch to the built-in official provider in the list (e.g. "Claude Official"), restart the tool, then follow its login/OAuth flow
5. Routing & Aggregation (optional): The Claude Code, Codex, Gemini CLI, and Grok Build pages have "Direct" / "Routing" tabs at the top, and Claude Code and Codex also have "Aggregation". Clicking a tab only changes what you're looking at and doesn't touch your configuration; to actually switch, click "Start routing" or "Switch to Aggregation" on the page, and click "Back to direct" to return. Use Routing to use OpenAI- or Gemini-format providers in Claude Code, or Claude in Codex; use Aggregation to mix models from several providers in one model list
6. Manage Tools: The "Apps" page in the sidebar shows each AI coding tool's version, install location, and source in one place; you can install, upgrade, or upgrade all, and choose which tools appear in the sidebar

MCP, Prompts, Skills, Projects & Sessions Copy Section

• MCP: Click "MCP" in the sidebar → Add servers via templates or custom config (or "Import Existing") → Toggle sync for each tool
• Prompts: Click "Prompts" in the sidebar → Create prompts with the Markdown editor → Enable one to write it to that tool's prompt file
• Skills: Click "Skills" in the sidebar → "Discover Skills" → Search skills.sh or browse GitHub repos → One-click install to supported tools
• Projects: First turn on "Show project switcher" in "Settings → General", then on the Claude Code, Claude Desktop, or Codex page, open the project switcher at the top → "New project" to save the current configuration; later, pick it from the switcher to switch the whole setup at once
• Sessions: Click "Sessions" in the sidebar → Browse and search conversation history, open the reading view, or restore each tool's sessions
• Accounts: Click "Accounts" in the sidebar to sign in to GitHub Copilot, ChatGPT, and xAI (Grok) accounts and use your subscriptions as providers

Note: On first launch, CC Switch automatically imports your existing Claude Code, Codex, Gemini CLI, and Grok Build configuration as a provider named default and adds an official provider for each of these tools and Claude Desktop, so nothing you had configured is lost.

For detailed guides on every feature, check out the User Manual, covering provider management, MCP/Prompts/Skills, local routing & failover, and more.

Features Copy Chapter

Full Changelog | v4.0 Release Notes

Supported Features by Tool Copy Section

• Switch: only one provider is active at a time; Coexist: multiple providers are written into the tool's own config at the same time, and you pick one inside the tool.
• Local Routing: CC Switch forwards requests on your machine and converts API formats; see Local Routing & Failover below. Claude Desktop providers can use "Direct" or "Model Mapping"; with "Model Mapping", requests go through local routing.
• Aggregation: Puts models from several providers into one model list and sends each request to the provider of the model you pick; see Aggregation Mode below.
• Sessions: Browse and search conversation history, open the reading view, and copy a resume command to continue a conversation (resuming OpenClaw and Hermes sessions isn't supported yet). Hermes shows only the 500 most recent sessions.
• Usage Stats: Without local routing, usage is collected from each tool's local session logs; requests that go through local routing are counted as well.
• The MCP, Skills, Prompts, and Sessions panels opened from the Claude Desktop page apply to Claude Code.

Provider Management Copy Section

• 90+ provider presets — Pick a preset and enter your key to add a provider, or create a custom configuration. The add panel lets you search by name (including Chinese names) and domain, and a vendor's different plans and regions are merged into one row
• Key fields only — Switching replaces only the connection details such as the endpoint, key, and model; plugins, hooks, MCP, settings you added yourself, and comments stay as they are. The editor shows what the config file will look like after switching, and CC Switch automatically backs up each config file before rewriting it for the first time
• Projects — Save Claude Code's or Codex's current provider, MCP, Skills, and prompt files as a project (for Claude Desktop, only the provider is saved), then switch the whole setup in one click from the project switcher at the top of the page or from the tray; when you switch to another project, the current state is automatically saved back to the previous project. The project switcher is hidden by default; turn on "Show project switcher" in "Settings → General"
• Accounts (Beta) — Sign in to multiple GitHub Copilot, ChatGPT, and xAI (Grok) accounts under "Accounts" in the sidebar and use those subscriptions as providers in Claude Code, Claude Desktop, and Codex (everything except Codex's OpenAI Official has to be used in Routing mode). Using a subscription outside the official client may violate the vendor's terms of service; assess the risk yourself
• Third-party providers for Claude Desktop — Connect directly to Anthropic-compatible endpoints; for non-Claude models, choose "Model Mapping" to map tiers like Sonnet, Opus, and Haiku to the provider's actual models through local routing
• Universal providers — One config syncs to Claude Code, Codex, and Gemini CLI
• One-click switching, system tray quick switching (Claude Code, Claude Desktop, Codex, Gemini CLI, Grok Build), drag-and-drop sorting, import/export

Local Routing & Failover Copy Section

• API format conversion — Local routing converts requests between Anthropic Messages, OpenAI Chat Completions, OpenAI Responses, and Gemini Native: Claude Code and Claude Desktop can use OpenAI- or Gemini-format providers, and Codex and Grok Build can use Chat Completions or Anthropic Messages providers
• Per-tool toggle — Claude Code, Codex, Gemini CLI, and Grok Build can each enter Routing mode separately: click "Start routing" on the "Routing" tab at the top of the page. In Routing mode, switching providers takes effect immediately for subsequent requests (Codex, Gemini CLI, and Grok Build may still need a restart if the switch changes the model). When you quit CC Switch, it writes the direct configuration back first and reconnects the next time it starts
• Auto-failover — Configure a failover queue for each tool; when a request fails, CC Switch automatically moves on to the next provider in the queue, backed by a circuit breaker and provider health monitoring
• Rectifier — Automatically fixes certain requests that some upstreams can't handle (e.g. Thinking signatures, or falling back when images aren't supported)
• Official providers (e.g. Claude Official) can't go through local routing (except Codex's OpenAI Official)
• The routing service's status, listen address, and failover settings are all in "Settings → Local routing"
• Guides: Using GPT in Claude Code · Using Claude in Codex

Aggregation Mode Copy Section

• One model list, many providers — On the Claude Code or Codex page, switch to "Aggregation" and add a few providers; their models all appear in the client's model picker. Each request goes to the provider of the model you pick, with no need to switch in CC Switch
• Add and remove anytime — Click "Add" or "Remove" on a provider card, then pick one provider as the default; requests that don't name an aggregated model go to it. Codex's OpenAI Official can only be the default provider; Claude official subscriptions are currently unsupported in Aggregation
• Notes — Aggregation doesn't provide failover; Claude Code requires version 2.1.243 or later; Codex needs a restart after the aggregated list changes, while Claude Code doesn't. When you switch models within a session, the new model has to rebuild its prompt cache, so the first turn costs a bit more
• Much of Aggregation mode's design draws on opencodex — thanks to its author and contributors
• Documentation: Aggregation mode manual · Illustrated guide (Chinese)

MCP, Prompts & Skills Copy Section

• Unified MCP panel — Manage all MCP servers in one place, choose which tools to sync each one to (Claude Code, Codex, Gemini CLI, Grok Build, OpenCode, Hermes, Pi, MiniMax Code), import existing configs from each tool, and import via Deep Link
• Prompts — A per-tool prompt library with a Markdown editor; enabling a prompt writes it to that tool's prompt file (CLAUDE.md / AGENTS.md / GEMINI.md), and the file's existing content is saved back to the library first, so nothing is lost. Pi can also edit SYSTEM.md, APPEND_SYSTEM.md, and prompt templates
• Skills — Search skills.sh, or install in one click from GitHub repos or ZIP files; check for updates and update all in one click; sync to each tool automatically, via symlinks only, or via copies only; you can optionally store them in ~/.agents/skills
• All three panels support search, and MCP and Skills can also be enabled or disabled all at once per tool; providers, MCP servers, and prompts are edited full-page in the content area, and you're warned before leaving with unsaved changes

Usage & Cost Tracking Copy Section

• Usage dashboard — Works without local routing: by default it automatically scans each tool's local session logs and tracks requests, tokens, cache hit rate, output speed, and spending by provider and model, with trend charts, a full-year heatmap, and per-request logs
• Quotas & balances — Provider cards and the tray show what's left and the reset countdown, e.g. "5h 94% left": official subscription quotas (Claude, ChatGPT, Gemini, SuperGrok), Coding Plan 5-hour / weekly / monthly quotas (Kimi, Zhipu GLM, MiniMax, Volcengine Ark, etc.), and account balances (DeepSeek, OpenRouter, SiliconFlow, etc.); some need to be turned on first via "Configure usage query" on the provider card, and for other providers you can write a custom usage script. ChatGPT subscriptions also show remaining limit resets and the Codex Credits balance
• Custom pricing — Set per-model prices, or import them from models.dev

Session Manager & Workspace Copy Section

• Session reading view — Parses each tool's session logs into structured content: text, thinking, tool calls, tool results, and images are shown separately; each turn of work collapses into a one-line summary (how many steps, how many files changed, how many failures), with failed steps marked in red; a conversation outline sits on the right, with in-session search, Markdown export, and copying a single turn or the whole conversation
• List & resume — Group by project or time, search titles, directories, messages, or session IDs, and delete in bulk; copy a resume command to continue a conversation, and on macOS resume in a terminal with one click
• Workspace editor (OpenClaw) — Edit agent files (AGENTS.md, SOUL.md, etc.) and daily memory
• Memory (Hermes) — Edit Hermes's MEMORY.md and USER.md

System & Platform Copy Section

• Cloud sync — Sync across devices via WebDAV (Jianguoyun, Nextcloud, Synology NAS, etc.) or S3-compatible storage (AWS S3, Cloudflare R2, Alibaba Cloud OSS, Tencent Cloud COS, etc.); you can also put the CC Switch configuration directory in a cloud drive folder such as Dropbox, OneDrive, or iCloud
• CLI tool management — On the "Apps" page in the sidebar, see the current and latest versions of command-line tools like Claude Code and Codex, install, upgrade, or upgrade all in one click, and diagnose duplicate installations; on Windows it can also manage tools inside WSL (see FAQ)
• Deep Link (ccswitch://) — Import providers, MCP servers, and prompts, or add skill repositories, in one click via a link; create links with the online generator; site owners who want an import button can follow the integration guide
• Built-in utilities — Skip Claude Code's first-run confirmation, hide AI attribution, have the VS Code Claude Code extension follow CC Switch's provider switches, and more
• Dark / Light / System theme, auto-launch, auto-updater, atomic writes, auto-backups (see where every backup lives and how much space it takes in "Settings → Data"), i18n (zh/zh-TW/en/ja, plus community-translated Turkish)

FAQ Copy Chapter

Which AI tools does CC Switch support?

CC Switch supports ten tools: Claude Code, Claude Desktop, Codex, Gemini CLI, Grok Build, OpenCode, OpenClaw, Hermes, Pi, MiniMax Code. Each tool has dedicated provider presets and configuration management; see Supported Features by Tool for what each one supports.

Do I need to restart the terminal after switching providers?

It depends on the tool:

• Claude Code: supports hot-switching of provider data — no restart needed.
• Codex, Gemini CLI, Grok Build: restart your terminal or the CLI tool for changes to take effect (CC Switch reminds you after switching). In Routing mode, requests go to the new provider immediately, but all three tools may still need a restart if the switch changes the model.
• Aggregation mode: changes to Claude Code's aggregated models take effect immediately; for Codex, entering or leaving Aggregation and changing the aggregated model list all require a full restart — see the next entry.
• Claude Desktop: fully quit and reopen Claude Desktop; when using "Model Mapping", also keep CC Switch running.
• OpenCode, OpenClaw, Hermes, Pi, MiniMax Code: these are coexist-mode tools — clicking "Add" ("Enable" for Pi) writes the provider into the tool's own config alongside the others; you then pick the model you want inside the tool.

In Aggregation mode, why don't the aggregated models show up in Codex's /model?

Codex reads its model list only at startup. After entering or leaving Aggregation mode, adding or removing an aggregated provider, or changing a provider's aggregated models, fully restart Codex to see the new list:

• Codex CLI: Closing the terminal and running codex again isn't enough. Every codex in every terminal shares one background daemon, and it has to be restarted to pick up the new list. When CC Switch detects that Codex is still using the old list, it shows a notice at the top of the Codex page; click "Restart Codex daemon" in the notice. Restarting interrupts any tasks running in the daemon.
• Codex desktop app: Quit it completely and reopen it (press ⌘Q on macOS; closing the window isn't enough).
• Editor extensions: Reopen the editor window.

Claude Code isn't affected: changes to aggregated models take effect immediately.

Will switching providers change my plugins, hooks, or other settings?

No. When you switch providers for Claude Code, Codex, Gemini CLI, or Grok Build, CC Switch replaces only the key fields in the config file: the endpoint, key, model name, and API protocol (plus the reasoning effort for Codex and the auth method for Gemini CLI), along with a few compatibility options that belong to the provider (such as Claude Code's "Disable Artifact Tool" and the context window). Plugins, hooks, permissions, MCP, environment variables you added yourself, comments, and formatting all stay as they are and apply to every provider.

You can change these shared settings in the tool itself or by editing the config file by hand. You can also edit any provider in CC Switch: the editor shows "what the config file will look like after switching to this provider". When you save, the key fields are stored in that provider, and every other change is written to the config file and applies to every provider.

So the old "Common Config Snippet" is no longer needed, and its buttons have been removed. Settings that were in your snippet before the upgrade were already written into the config file when you switched, so they stay. Before CC Switch rewrites each config file for the first time, it also backs up the original to ~/.cc-switch/backups/live-first-write/.

I changed the model inside the tool — why does it go back after I switch away and back?

The model is a key field and belongs to the provider. A model you pick inside the tool (such as with /model in Claude Code) stays in effect until the next switch; when you switch, the model in the config file is replaced with the one saved in the target provider, and CC Switch doesn't save the model you picked back to the previous provider. To keep using a model long-term, edit that provider in CC Switch.

Older versions saved the whole config file back to the provider when you switched away. That no longer happens: it froze plugins and other shared settings into one provider, so they were lost when you switched to another one.

Why can't I delete the provider currently in use?

CC Switch follows a "minimal intrusion" design principle — even if you uninstall the app, your tools will continue to work normally.

So for tools that use one active provider at a time (Claude Code, Claude Desktop, Codex, Gemini CLI, Grok Build), the system always keeps one configuration in use, because deleting all configurations would make the corresponding tool unusable; to delete it, switch to another provider first. Likewise, the default provider in Aggregation mode can't be removed; make another provider the default first. Coexist-mode tools (OpenCode, OpenClaw, Hermes, Pi, and MiniMax Code) aren't subject to this restriction — you can delete any provider directly. If you rarely use a tool, you can hide it from the sidebar on the "Apps" page. To switch back to official login, see the next question.

How do I switch back to official login?

In CC Switch, the provider lists for Claude Code, Claude Desktop, Codex, Gemini CLI, and Grok Build each include a built-in official provider (Claude Official, Claude Desktop Official, OpenAI Official, Google Official, Grok Official); if you deleted it, add it back from the presets. After switching to the official provider, follow the tool's own login flow (e.g. /login in Claude Code, codex login for Codex), and then you can freely switch between the official provider and third-party providers.

For Codex, you can also sign in to multiple ChatGPT accounts inside CC Switch via "Sign in with ChatGPT" and choose an "Account to use" for each OpenAI Official card, so switching between multiple Plus, Pro, or Team accounts takes one click; cards set to "Follow Codex login" keep using the Codex CLI's own login.

Note: official subscriptions use the tool's own login and don't go through local routing. Official providers can't be selected in Routing mode (Codex's OpenAI Official cards are the exception); switch back to Direct first.

After I start routing, why does my config file point to 127.0.0.1?

In Routing mode, the tool's requests first go to CC Switch's local routing (http://127.0.0.1:15721 by default), and CC Switch then forwards them to the provider you selected. That's why the tool's config file only contains the local address and the placeholder key PROXY_MANAGED; for Claude Code, the model name is also written as a fixed alias such as claude-sonnet-5 (the /model menu still shows the real model name). The real provider address, key, and model are all stored in CC Switch. Aggregation mode works the same way.

In the request logs under "Usage" in the sidebar, you can see "requested model → actual model" for each request.

In Routing mode, switching changes the provider that routing uses; the provider you were using before you entered Routing stays the same and is labeled "Direct" on its card. When you click "Back to direct", the config file is written back to this direct provider's configuration. Quitting CC Switch also writes back the direct provider first, and it reconnects the next time CC Switch starts.

Can I use OpenAI-compatible APIs, Gemini, or local models in Claude Code?

Yes, but you need to use Routing. When editing the provider, set "Upstream Format" under "Advanced Options" to match the provider's API: choose "OpenAI Chat Completions" for services that only offer a Chat Completions endpoint (as many local model servers do), "OpenAI Responses API" for services that offer a Responses endpoint, and "Gemini Native generateContent" for Gemini. Then click "Start routing" on the "Routing" tab of the Claude Code page. Choosing the wrong format or not starting routing usually results in a 404 or 405 error.

Conversely, choosing "Anthropic Messages" as the "Upstream Format" in Codex or Grok Build lets you use Claude-format providers; this also requires Routing. See Using GPT in Claude Code and Using Claude in Codex for details.

"Connectivity check" passed, so why do requests still fail?

The "Connectivity check" on a provider card only checks whether the provider address is reachable; it doesn't send a real model request, so it can't verify whether the API key and model name are correct. When requests fail, check the key, model name, and upstream format; for requests that go through Routing, you can also see the exact error in the request logs under "Usage" in the sidebar.

Where is my data stored?

By default, everything is stored in the .cc-switch folder in your home directory (C:\Users\\.cc-switch on Windows):

• Database: cc-switch.db (SQLite — providers, MCP, prompts, Skills, projects, usage records, etc.)
• Local settings: settings.json (device-level settings such as each tool's config directory, backup policy, and cloud sync connection details)
• Backups: backups/ (backed up automatically every 24 hours by default, keeping the 10 most recent; adjustable in "Settings → Data → Backup & Restore"; "Other Backups" below it lists the location and size of every other backup, which you can clean up by category)
• Skills: skills/ (can be changed to ~/.agents/skills in Settings), synced to each tool via symlinks by default, falling back to copying if that fails
• Skill Backups: skill-backups/ (created automatically before uninstalling or updating a skill, keeping the 20 most recent)
• OAuth login credentials: copilot_auth.json, codex_oauth_auth.json, xai_oauth_auth.json
• Logs: logs/cc-switch.log and crash.log — please attach them when reporting an issue
• Device state: live-state.json (whether each tool is currently in Direct, Routing, or Aggregation mode, and what was last written), codex-login-stash.json (the official Codex login moved aside when you switch to a third-party provider, restored when you switch back to an official one)
• Original config files: backups/live-first-write/ (each tool's config file as it was before CC Switch first rewrote it)

After you change "CC Switch Configuration Directory" in "Settings → Data → Location", all of the files above except settings.json, the device state, and the original config files are stored in the new directory. CC Switch doesn't move existing files automatically, so copy them over manually first. settings.json, the device state, and the original config files belong to this computer only: they always stay in the default directory and are not included in cloud sync.

How do I manage tools inside WSL on Windows?

CC Switch doesn't detect WSL automatically. In "Settings → App config", change the config directory for the corresponding tool to a path inside WSL, e.g. \\wsl.localhost\Ubuntu\home\\.claude; after you save, CC Switch reads and writes the config inside WSL (supported for Claude Code, Codex, Gemini CLI, Grok Build, OpenCode, OpenClaw, Hermes, and Pi). Once this is set, the "Apps" page in the sidebar also detects and upgrades that tool in the corresponding WSL distribution.

Note: Routing and Aggregation write 127.0.0.1 as the address into the config. In WSL2's default NAT networking mode, 127.0.0.1 inside WSL can't reach local routing on Windows; switch WSL to mirrored networking mode instead.

Is there a command-line or headless version?

CC Switch itself only ships as a desktop app that requires a graphical interface (see Download & Installation for system requirements). For servers, SSH sessions, or machines without a desktop environment, we recommend the community-maintained CC Switch CLI: it offers both an interactive terminal UI (TUI) and a command-line mode, supports Claude Code, Codex, Gemini CLI, OpenCode, OpenClaw, Hermes, and Pi, and can be installed via Homebrew (brew install cc-switch-cli) or an install script.

By default, CC Switch CLI shares the ~/.cc-switch data directory with the desktop app and is compatible with the desktop app's WebDAV sync. The two projects are released separately, and the database version the CLI supports sometimes lags behind the desktop app; if you see a "database version is too new" message, upgrade the CLI or wait for it to catch up.

Linux (Wayland + NVIDIA): clicks don't register and the window black-screens on resize

The AppImage forces GDK_BACKEND=x11 (XWayland) to avoid a historical native-Wayland crash. On newer Wayland + NVIDIA setups this can leave the web content area unclickable (the title-bar buttons still work) and black-screen on resize. Launch with the opt-in escape hatch to switch back to native Wayland:

CC_SWITCH_GDK_BACKEND=wayland ./CC-Switch-*.AppImage

If you launch from a desktop icon, add it to the .desktop Exec= line (e.g. env CC_SWITCH_GDK_BACKEND=wayland /path/to/AppImage) or set it in your session environment. The variable is generic: on tiling Wayland compositors (sway/Hyprland) where clicks don't register, try CC_SWITCH_GDK_BACKEND=x11 instead. Leaving it unset keeps the default behavior.

For more questions, see the FAQ in the User Manual.

Contributing Copy Chapter

Issues and suggestions are welcome! Before developing a new feature, please open an issue to discuss the approach first; feature PRs that aren't a good fit for the project may be closed.

For development setup, pre-submit checks, and architecture notes, see CONTRIBUTING.md; for usage questions, check SUPPORT.md first; report security vulnerabilities privately as described in SECURITY.md.

Tech stack: Tauri 2 · Rust · React 18 · TypeScript · SQLite

Star History Copy Chapter

License Copy Chapter

MIT © Jason Young

Overview (`flatpak/README.md`) Copy Section

Flatpak Build Guide

This directory contains the Flatpak manifest (com.ccswitch.desktop) for CC Switch, used to convert the generated .deb artifact into an installable .flatpak package via CI or local builds.

Dependencies Copy Chapter

• flatpak
• flatpak-builder
• Flathub remote (for installing org.gnome.Platform//46 runtime)

For Ubuntu/Debian:

sudo apt install flatpak flatpak-builder
flatpak remote-add --if-not-exists flathub https://flathub.org/repo/flathub.flatpakrepo
flatpak install -y --user flathub org.gnome.Platform//46 org.gnome.Sdk//46

Local Build (Generate .flatpak from .deb) Copy Chapter

1. Build the deb on Linux first:

pnpm tauri build --bundles deb

The last step of this build signs the auto-update bundles, which requires the release private key TAURI_SIGNING_PRIVATE_KEY. Without the key, the .deb is still produced but the command exits with an error. To skip updater bundle generation instead:

pnpm tauri build --bundles deb -c '{"bundle":{"createUpdaterArtifacts":false}}'

2. Copy the generated deb to this directory:

cp "$(find src-tauri/target/release/bundle -name '*.deb' | head -n 1)" flatpak/cc-switch.deb

3. Build the local Flatpak repository and export the .flatpak:

flatpak-builder --force-clean --user --disable-cache --repo flatpak-repo flatpak-build flatpak/com.ccswitch.desktop.yml
flatpak build-bundle --runtime-repo=https://flathub.org/repo/flathub.flatpakrepo flatpak-repo CC-Switch-Linux.flatpak com.ccswitch.desktop

4. Install and run:

flatpak install --user ./CC-Switch-Linux.flatpak
flatpak run com.ccswitch.desktop

Permissions Note Copy Chapter

The current manifest uses --filesystem=home by default for "download and run" convenience, allowing the app to directly read/write CLI configuration files and app data on the host (and supporting the "directory override" feature).

If you prefer minimal permissions (e.g., for Flathub submission or security concerns), you can replace --filesystem=home in flatpak/com.ccswitch.desktop.yml with more precise grants:

- --filesystem=~/.cc-switch:create
  - --filesystem=~/.claude:create
  - --filesystem=~/.claude.json
  - --filesystem=~/.codex:create
  - --filesystem=~/.gemini:create
  - --filesystem=~/.config/opencode:create
  - --filesystem=~/.openclaw:create

Note: Flatpak's :create modifier only works with directories, not files. Therefore, ~/.claude.json cannot use :create. If this file doesn't exist on the user's machine, the app may not be able to create it with restricted permissions. Users should either run Claude Code once to generate it, or manually create an empty JSON file (content: {}).

If you plan to publish on Flathub or want stricter permission control, adjust the finish-args in flatpak/com.ccswitch.desktop.yml accordingly.

Overview (`docs/user-manual/README.md`) Copy Section

CC Switch User Manual / 用户手册 / ユーザーマニュアル

Claude Code / Claude Desktop / Codex / Gemini CLI / OpenCode / OpenClaw / Hermes

Language / 语言 / 言語 Copy Chapter

Version / 版本 / バージョン Copy Chapter

• Documentation version: v3.16.0
• Last updated: 2026-05-29
• Compatible with CC Switch v3.16.0+

Links Copy Chapter

• GitHub Issues
• GitHub Repository

Overview (`src/whats-new/README.md`) Copy Section

更新摘要（应用内弹窗）

用户升级后第一次打开 CC Switch，会弹一个窗口，列出从上次看过的版本到当前版本之间每一版的几条摘要。数据就是这个目录下的文件，构建时打进安装包（src/lib/whatsNew.ts），弹窗不联网。

详细内容仍在 docs/release-notes/。弹窗里每个版本的「详情」链到官网 https://ccswitch.io/<zh|en|ja>/changelog/<version>，所以发版后要照常同步官网更新日志。

每个版本一个文件 Copy Chapter

文件名是版本号，例如 4.0.2.json：

{
  "version": "4.0.2",
  "items": [
    {
      "type": "new",
      "zh": "OpenCode 可以选择思考档位",
      "zh-TW": "OpenCode 可以選擇思考檔位",
      "en": "OpenCode can now pick a thinking level",
      "ja": "OpenCode で思考レベルを選べるように"
    }
  ]
}

• type：new（新增）、fix（修复）、improve（改进）。
• 每版最多 4 条，每条一句话：中文、繁中不超过 40 字，日文不超过 50 字，英文不超过 100 个字符。四种语言都要写。
• 写用户能感知到的变化，按影响大小排序。从中文发布说明里挑最重要的几条，不要照搬原文。
• "items": [] 表示这一版不弹窗，适合纯构建、CI 之类的版本。文件仍然要有。

规则由 tests/config/whatsNewEntries.test.ts 检查。

什么时候写 Copy Chapter

和三语发布说明一起，放进打 tag 之前的 docs(release) 提交。release.yml 会先检查 src/whats-new/<版本>.json 是否存在，缺了直接失败，不会白跑构建。

Overview (`docs/user-manual/en/README.md`) Copy Section

CC Switch User Manual

All-in-One Assistant for Claude Code / Claude Desktop / Codex / Gemini CLI / Grok Build / OpenCode / OpenClaw / Hermes / Pi / MiniMax Code

Table of Contents Copy Chapter

📚 CC Switch User Manual
│
├── 1. Getting Started
│   ├── 1.1 Introduction
│   ├── 1.2 Installation Guide
│   ├── 1.3 Interface Overview
│   ├── 1.4 Quick Start
│   └── 1.5 Personalization
│
├── 2. Provider Management
│   ├── 2.1 Add Provider
│   ├── 2.2 Switch Provider
│   ├── 2.3 Edit Provider
│   ├── 2.4 Sort & Duplicate
│   ├── 2.5 Usage Query
│   └── 2.6 Claude Desktop
│
├── 3. Extensions
│   ├── 3.1 MCP Server Management
│   ├── 3.2 Prompts Management
│   ├── 3.3 Skills Management
│   ├── 3.4 Session Manager
│   └── 3.5 Workspace & Memory
│
├── 4. Local Routing & High Availability
│   ├── 4.1 Local Routing Service
│   ├── 4.2 App Routing
│   ├── 4.3 Failover
│   ├── 4.4 Usage Statistics
│   ├── 4.5 Connectivity Check
│   └── 4.6 Aggregation Mode
│
└── 5. FAQ
    ├── 5.1 Configuration Files
    ├── 5.2 FAQ
    ├── 5.3 Deep Link Protocol
    └── 5.4 Environment Variable Conflicts

File List Copy Chapter

1. Getting Started Copy Section

2. Provider Management Copy Section

3. Extensions Copy Section

4. Local Routing & High Availability Copy Section

5. FAQ Copy Section

Quick Links Copy Chapter

• New users: Start with 1.1 Introduction
• Installation issues: See 1.2 Installation Guide
• Configure providers: See 2.1 Add Provider
• Use Claude Desktop: See 2.6 Claude Desktop
• Use local routing: See 4.1 Local Routing Service
• Having trouble: See 5.2 FAQ

Version Information Copy Chapter

• Documentation version: v4.0.4
• Last updated: 2026-10-07
• Applicable to CC Switch v4.0.4+

Recent Major Changes (v4.0) Copy Section

• Redesigned interface: the top navigation is replaced by a left sidebar, with separate pages for Usage, Accounts, MCP, Skills, Prompts, Sessions, and Apps; Settings is split into six groups: General, App config, Local routing, Network, Data, About — see 1.3 Interface Overview and 1.5 Personalization
• Three connection modes: Direct / Routing / Aggregation: chosen at the top of each app page; going back to direct is one step — see 2.2 Switch Provider
• New Aggregation mode: Claude Code and Codex can mix models from several providers in one session — see 4.6 Aggregation Mode
• Switching only changes key fields: everything other than the address, key, model, and other key fields is left as is; common config snippets are no longer used — see 2.3 Edit Provider
• Accounts: ChatGPT, GitHub Copilot, xAI, and other sign-ins are managed in one place under Accounts in the sidebar — see 1.5 Personalization
• Apps page: install and upgrade each CLI tool, and choose which apps show in the sidebar — see 1.2 Installation Guide
• For the full list of changes, see the v4.0 release notes

Contributing Copy Chapter

Feel free to submit Issues or PRs to improve the documentation:

• GitHub Issues
• GitHub Repository

Overview (`docs/user-manual/ja/README.md`) Copy Section

CC Switch ユーザーマニュアル

Claude Code / Claude Desktop / Codex / Gemini CLI / Grok Build / OpenCode / OpenClaw / Hermes / Pi / MiniMax Code オールインワンアシスタント

目次構成 Copy Chapter

📚 CC Switch ユーザーマニュアル
│
├── 1. はじめに
│   ├── 1.1 ソフトウェア紹介
│   ├── 1.2 インストールガイド
│   ├── 1.3 インターフェース概要
│   ├── 1.4 クイックスタート
│   └── 1.5 個人設定
│
├── 2. プロバイダー管理
│   ├── 2.1 プロバイダーの追加
│   ├── 2.2 プロバイダーの切り替え
│   ├── 2.3 プロバイダーの編集
│   ├── 2.4 並べ替えと複製
│   ├── 2.5 使用量クエリ
│   └── 2.6 Claude Desktop
│
├── 3. 拡張機能
│   ├── 3.1 MCP サーバー管理
│   ├── 3.2 Prompts プロンプト管理
│   ├── 3.3 Skills スキル管理
│   ├── 3.4 セッションマネージャー
│   └── 3.5 ワークスペースとメモリー
│
├── 4. ローカルルーティングと高可用性
│   ├── 4.1 ローカルルーティングサービス
│   ├── 4.2 アプリケーションルーティング
│   ├── 4.3 フェイルオーバー
│   ├── 4.4 使用量統計
│   ├── 4.5 接続チェック
│   └── 4.6 集約モード
│
└── 5. よくある質問
    ├── 5.1 設定ファイルの説明
    ├── 5.2 FAQ
    ├── 5.3 ディープリンクプロトコル
    └── 5.4 環境変数の競合

ファイル一覧 Copy Chapter

1. はじめに Copy Section

2. プロバイダー管理 Copy Section

3. 拡張機能 Copy Section

4. ローカルルーティングと高可用性 Copy Section

5. よくある質問 Copy Section

クイックリンク Copy Chapter

• 初めての方：1.1 ソフトウェア紹介 からお読みください
• インストールの問題：1.2 インストールガイド をご確認ください
• プロバイダーの設定：2.1 プロバイダーの追加 をご確認ください
• Claude Desktop の利用：2.6 Claude Desktop をご確認ください
• ローカルルーティングの使用：4.1 ローカルルーティングサービス をご確認ください
• お困りの方：5.2 FAQ をご確認ください

バージョン情報 Copy Chapter

• ドキュメントバージョン：v4.0.4
• 最終更新：2026-10-07
• CC Switch v4.0.4+ 対応

最近の主な変更（v4.0） Copy Section

• インターフェースの刷新：上部のナビゲーションが左サイドバーになり、使用量、アカウント、MCP、Skills、プロンプト、セッション、アプリがそれぞれ独立したページになりました。設定は一般、アプリ設定、ローカルルーティング、ネットワーク、データ、情報の 6 グループに分かれています — 詳細は 1.3 インターフェース概要、1.5 個人設定
• 直接接続 / ルーティング / 集約の 3 つの接続モード：各アプリページの上部で選び、直接接続へは 1 ステップで戻せます — 詳細は 2.2 プロバイダーの切り替え
• 集約モードを追加：Claude Code と Codex で、1 つのセッションの中で複数のプロバイダーのモデルを使い分けられます — 詳細は 4.6 集約モード
• 切り替えはキーとなるフィールドだけを変更：アドレス、キー、モデルなど以外の設定はそのまま残り、共通設定スニペットは使われなくなりました — 詳細は 2.3 プロバイダーの編集
• アカウント：ChatGPT、GitHub Copilot、xAI などのログインをサイドバーの「アカウント」でまとめて管理します — 詳細は 1.5 個人設定
• 「アプリ」ページ：各 CLI ツールのインストールとアップグレード、サイドバーに表示するアプリの選択ができます — 詳細は 1.2 インストールガイド
• すべての変更点は v4.0 リリースノート をご覧ください

コントリビュート Copy Chapter

Issue や PR でドキュメントの改善にご協力ください：

• GitHub Issues
• GitHub Repository

Overview (`docs/user-manual/zh/README.md`) Copy Section

CC Switch 用户手册

Claude Code / Claude Desktop / Codex / Gemini CLI / Grok Build / OpenCode / OpenClaw / Hermes / Pi / MiniMax Code 全方位辅助工具

目录结构 Copy Chapter

📚 CC Switch 用户手册
│
├── 1. 快速入门
│   ├── 1.1 软件介绍
│   ├── 1.2 安装指南
│   ├── 1.3 界面概览
│   ├── 1.4 快速上手
│   └── 1.5 个性化配置
│
├── 2. 供应商管理
│   ├── 2.1 添加供应商
│   ├── 2.2 切换供应商
│   ├── 2.3 编辑供应商
│   ├── 2.4 排序与复制
│   ├── 2.5 用量查询
│   └── 2.6 Claude Desktop
│
├── 3. 扩展功能
│   ├── 3.1 MCP 服务器管理
│   ├── 3.2 Prompts 提示词管理
│   ├── 3.3 Skills 技能管理
│   ├── 3.4 会话管理器
│   └── 3.5 工作区文件与每日记忆
│
├── 4. 本地路由与高可用
│   ├── 4.1 本地路由服务
│   ├── 4.2 应用路由
│   ├── 4.3 故障转移
│   ├── 4.4 用量统计
│   ├── 4.5 连通检测
│   └── 4.6 聚合模式
│
└── 5. 常见问题
    ├── 5.1 配置文件说明
    ├── 5.2 FAQ
    ├── 5.3 深度链接协议
    └── 5.4 环境变量冲突

文件列表 Copy Chapter

1. 快速入门 Copy Section

2. 供应商管理 Copy Section

3. 扩展功能 Copy Section

4. 本地路由与高可用 Copy Section

5. 常见问题 Copy Section

快速链接 Copy Chapter

• 新用户：从 1.1 软件介绍 开始
• 安装问题：查看 1.2 安装指南
• 配置供应商：查看 2.1 添加供应商
• 使用 Claude Desktop：查看 2.6 Claude Desktop
• 使用本地路由：查看 4.1 本地路由服务
• 遇到问题：查看 5.2 FAQ

版本信息 Copy Chapter

• 文档版本：v4.0.4
• 最后更新：2026-10-07
• 适用于 CC Switch v4.0.4+

近期主要变化（v4.0） Copy Section

• 界面改版：顶部导航换成左侧栏，用量统计、授权中心、MCP、Skills、提示词、会话、应用各占一页；设置分为通用、应用配置、本地路由、网络、数据、关于六组 — 详见 1.3 界面概览、1.5 个性化配置
• 直连 / 路由 / 聚合三种连接模式：在每个应用页顶部选择，回到直连只需一步 — 详见 2.2 切换供应商
• 新增聚合模式：Claude Code 和 Codex 可以在一个会话里按模型混用多家供应商 — 详见 4.6 聚合模式
• 切换只改关键字段：地址、密钥、模型等关键字段以外的设置原样保留，不再使用通用配置片段 — 详见 2.3 编辑供应商
• 授权中心：ChatGPT、GitHub Copilot、xAI 等账号集中在侧栏「授权中心」管理 — 详见 1.5 个性化配置
• 「应用」页：安装、升级各 CLI 工具，选择侧栏显示哪些应用 — 详见 1.2 安装指南
• 完整变化见 v4.0 发布说明

贡献 Copy Chapter

欢迎提交 Issue 或 PR 改进文档：

• GitHub Issues
• GitHub Repository

User Manual En 1 Getting Started 1.4 Quickstart (`docs/user-manual/en/1-getting-started/1.4-quickstart.md`) Copy Section

1.4 Quick Start

This section helps you complete the initial setup in 5 minutes.

Step 1: Add a Provider Copy Chapter

1. Select the tool you want to manage in the left sidebar, then click the + (Add Provider) button in the top-right corner of the page
2. Select your provider under "Provider Preset"
   • Common presets: Zhipu GLM, MiniMax, DeepSeek, Kimi, PackyCode
   • Or select "Custom" for manual configuration
3. Enter your API Key
4. Click "Add"

💡 Tip: The add panel supports searching by Chinese name and domain, and different plans and regions of the same provider are merged into one row. Presets auto-fill the endpoint URL, so you only need to enter your API Key.

Step 2: Switch Provider Copy Chapter

After adding, the provider appears in the list.

Option 1: Switch from the app page

• Click the "Switch" button on the provider card, and its status changes to "In use"
• OpenCode, OpenClaw, Hermes, and MiniMax Code are coexist apps: the button is "Add" (for Pi, "Enable"), and you can add multiple providers at the same time

Option 2: Quick switch via system tray

• Right-click the CC Switch icon in the system tray
• Each tool has one row showing "name · mode · provider · quota"; click a provider name directly in the submenu (supported for Claude Code, Claude Desktop, Codex, Gemini CLI, and Grok Build)

Step 3: Activation Copy Chapter

After switching providers, each CLI tool activates differently:

In Routing mode, switching providers for Claude Code, Codex, Gemini CLI, and Grok Build takes effect immediately for subsequent requests; however, if the switch changes the model, Codex, Gemini CLI, and Grok Build may still need a restart.

Direct, Routing, and Aggregation (Optional) Copy Chapter

The pages of Claude Code, Codex, Gemini CLI, and Grok Build have "Direct / Routing" tabs at the top, and Claude Code and Codex also have "Aggregation". Clicking a tab only changes what you are viewing and does not change any configuration; to actually switch, click the button on the page that spells out the consequences: "Start routing" or "Switch to Aggregation", and "Back to direct" to return to Direct.

• Direct (default): The client connects to the provider directly; choose it for everyday use
• Routing: Requests go through CC Switch on this machine (default 127.0.0.1:15721), which can convert API formats and do failover. Choose it if you want to use an OpenAI- or Gemini-format provider in Claude Code, or Claude in Codex
• Aggregation: Puts models from several providers into one model list, and a request goes to whichever provider owns the model you pick; no failover

Routing and Aggregation need CC Switch to keep running; quitting CC Switch automatically returns to Direct, and it reconnects the next time you start it. Official subscriptions do not go through routing (Codex's OpenAI Official is the exception). See Enable local routing for details.

Claude Code First Launch Prompt Copy Section

If Claude Code prompts you to log in or shows an onboarding wizard on first launch, enable the "Skip Claude Code first-run confirmation" option in CC Switch:

1. Open CC Switch "Settings → App config" and find the Claude Code block
2. Enable the "Skip Claude Code first-run confirmation" toggle
3. Restart Claude Code

⚠️ Note: This option writes hasCompletedOnboarding: true to ~/.claude.json, skipping the official first-run confirmation flow.

Verify Configuration Copy Chapter

After restarting, launch the corresponding CLI tool and enter a simple question to test:

# Claude Code - enter a test question after launching
claude
> Hello, please briefly introduce yourself

# Codex - enter a test question after launching
codex
> Hello, please briefly introduce yourself

# Gemini - enter a test question after launching
gemini
> Hello, please briefly introduce yourself

# OpenCode - enter a test question after launching
opencode
> Hello, please briefly introduce yourself

# OpenClaw - enter a test question after launching
openclaw
> Hello, please briefly introduce yourself

If the AI responds normally, the configuration is successful.

Note: On first launch, CC Switch automatically imports the existing configuration of Claude Code, Codex, Gemini CLI, and Grok Build as a provider named default, and adds an official provider for these tools and Claude Desktop. Your original configuration is not lost.

Next Steps Copy Chapter

Congratulations! You have completed the basic configuration. Next, you can:

• Add more providers - Configure multiple providers for easy switching
• Configure MCP servers - Extend AI tool capabilities
• Set up system prompts - Customize AI behavior
• Enable local routing - Use providers that need format conversion, and enable automatic failover
• Manage AI coding tools - Install and upgrade tools on the sidebar "Apps" page, and choose which apps show in the sidebar
• View usage statistics - Track request counts, tokens, and costs

Common Issues Copy Chapter

Not taking effect after switching? Copy Section

Make sure you restarted the terminal or CLI tool. The configuration file is updated at switch time, but running programs do not automatically reload it.

Can't find a preset? Copy Section

If your provider is not in the preset list, select "Custom" for manual configuration. See Add Provider for configuration format details.

How to restore official login? Copy Section

The provider lists for Claude Code, Claude Desktop, Codex, Gemini CLI, and Grok Build each come with a built-in official provider (such as Claude Official, OpenAI Official, Google Official, and Grok Official). Switch to it, restart the client, and follow the tool's own login flow. If it is missing from the list (for example, because you deleted it or upgraded from an older version), you can add it again from the presets.

User Manual Ja 1 Getting Started 1.4 Quickstart (`docs/user-manual/ja/1-getting-started/1.4-quickstart.md`) Copy Section

1.4 クイックスタート

このセクションでは、5 分で初回設定を完了する方法を説明します。

ステップ 1：プロバイダーの追加 Copy Chapter

1. 左サイドバーで管理したいツールを選び、ページ右上の +（プロバイダーを追加）をクリック
2. 「プロバイダータイプ」からプロバイダーを選択
   • よく使われるプリセット：Zhipu GLM、MiniMax、DeepSeek、Kimi、PackyCode
   • または「カスタム」を選択して手動設定
3. API Key を入力
4. 「追加」をクリック

💡 ヒント：追加パネルは中国語名とドメインでの検索に対応しており、同じ提供元のプランやリージョンは 1 行にまとめられます。プリセットではエンドポイントアドレスが自動入力されるため、API Key のみ入力すれば使用できます。

ステップ 2：プロバイダーの切り替え Copy Chapter

追加が完了すると、プロバイダーがリストに表示されます。

方法 1：アプリページで切り替え

• プロバイダーカードの「切り替え」ボタンをクリックすると、状態が「使用中」になります
• OpenCode、OpenClaw、Hermes、MiniMax Code は共存型アプリで、ボタンは「追加」（Pi は「有効化」）です。複数のプロバイダーを同時に追加できます

方法 2：トレイで素早く切り替え

• システムトレイアイコンを右クリック
• ツールごとに 1 行、「名前 · モード · プロバイダー · クォータ」と表示されます。サブメニューでプロバイダー名を直接クリックします（Claude Code、Claude Desktop、Codex、Gemini CLI、Grok Build に対応）

ステップ 3：反映方法 Copy Chapter

プロバイダーを切り替えた後、各 CLI ツールの反映方法は異なります：

ルーティングモードの場合、Claude Code、Codex、Gemini CLI、Grok Build でのプロバイダー切り替えは以降のリクエストに即座に反映されます。ただし、切り替えによってモデルが変わる場合、Codex、Gemini CLI、Grok Build は再起動が必要になることがあります。

直接接続、ルーティング、集約（任意） Copy Chapter

Claude Code、Codex、Gemini CLI、Grok Build のページ上部には「直接接続 / ルーティング」のタブがあり、Claude Code と Codex には「集約」もあります。タブをクリックしても表示が切り替わるだけで設定は変更されません。実際に切り替えるには、ページ上の結果が明記されたボタン「ルーティングを開始」「集約に切り替え」を押します。直接接続に戻すときは「直接接続に戻す」を押します。

• 直接接続（デフォルト）：クライアントがプロバイダーに直接接続します。日常の利用ではこれを選びます
• ルーティング：リクエストをこのマシン上の CC Switch 経由で転送し（デフォルトは 127.0.0.1:15721）、API フォーマットの変換やフェイルオーバーができます。Claude Code で OpenAI や Gemini 形式のプロバイダーを使いたい場合や、Codex で Claude を使いたい場合に選びます
• 集約：複数プロバイダーのモデルを 1 つのモデルリストにまとめ、選んだモデルのプロバイダーへリクエストを送ります。フェイルオーバーは行いません

ルーティングと集約は CC Switch が起動し続けている必要があります。CC Switch を終了すると自動的に直接接続に戻り、次回起動時に再び接続されます。公式サブスクリプションはルーティングを経由しません（Codex の OpenAI Official は例外）。詳細は ローカルルーティングの有効化 を参照してください。

Claude Code の初回インストール時の注意 Copy Section

Claude Code を初めて起動するときにログインの要求や初期化ガイドが表示される場合は、CC Switch で「Claude Code の初回確認をスキップ」オプションを有効にしてください：

1. CC Switch の「設定 → アプリ設定」を開き、Claude Code のブロックを探す
2. 「Claude Code の初回確認をスキップ」スイッチをオンにする
3. Claude Code を再起動

⚠️ 注意：このオプションは ~/.claude.json に hasCompletedOnboarding: true を書き込み、公式の初回インストール確認フローをスキップします。

設定の確認 Copy Chapter

再起動後、対応する CLI ツールを起動して簡単な質問でテストします：

# Claude Code - 起動後にテスト質問を入力
claude
> こんにちは、簡単に自己紹介してください

# Codex - 起動後にテスト質問を入力
codex
> こんにちは、簡単に自己紹介してください

# Gemini - 起動後にテスト質問を入力
gemini
> こんにちは、簡単に自己紹介してください

# OpenCode - 起動後にテスト質問を入力
opencode
> こんにちは、簡単に自己紹介してください

# OpenClaw - 起動後にテスト質問を入力
openclaw
> こんにちは、簡単に自己紹介してください

AI が正常に回答すれば、設定は成功です。

注意：初回起動時、CC Switch は Claude Code、Codex、Gemini CLI、Grok Build の既存設定を default という名前のプロバイダーとして自動的にインポートし、これらのツールと Claude Desktop に公式プロバイダーを追加します。既存の設定は失われません。

次のステップ Copy Chapter

基本設定が完了しました。次に以下のことができます：

• プロバイダーの追加 - 複数のプロバイダーを設定して簡単に切り替え
• MCP サーバーの設定 - AI ツールの機能を拡張
• システムプロンプトの設定 - AI の動作をカスタマイズ
• ローカルルーティングの有効化 - フォーマット変換が必要なプロバイダーの利用、自動フェイルオーバー
• AI プログラミングツールの管理 - サイドバーの「アプリ」ページでツールのインストール・更新を行い、サイドバーに表示するアプリを選択
• 使用量統計の確認 - リクエスト数、Token、費用を集計

よくある質問 Copy Chapter

切り替えても反映されない場合 Copy Section

ターミナルまたは CLI ツールを再起動してください。設定ファイルは切り替え時に更新されますが、実行中のプログラムは自動的に設定を再読み込みしません。

プリセットが見つからない場合 Copy Section

プロバイダーがプリセットリストにない場合は、「カスタム」を選択して手動設定してください。設定形式については プロバイダーの追加 を参照してください。

公式ログインに戻すには Copy Section

Claude Code、Claude Desktop、Codex、Gemini CLI、Grok Build のプロバイダーリストには、それぞれ公式プロバイダー（Claude Official、OpenAI Official、Google Official、Grok Official など）が最初から含まれています。そちらに切り替えてクライアントを再起動し、各ツール自身のログインフローに従ってください。リストにない場合（削除した場合や旧バージョンからアップグレードした場合など）は、プリセットから追加し直せます。

User Manual Zh 1 Getting Started 1.4 Quickstart (`docs/user-manual/zh/1-getting-started/1.4-quickstart.md`) Copy Section

1.4 快速上手

本节帮助你在 5 分钟内完成首次配置。

第一步：添加供应商 Copy Chapter

1. 在左侧栏选中要管理的工具，点击页面右上角的 +（添加供应商）
2. 在「预设供应商」中选择你的供应商
   • 常用预设：智谱 GLM、MiniMax、DeepSeek、Kimi、PackyCode
   • 或选择「自定义」手动配置
3. 填写 API Key
4. 点击「添加」

💡 提示：添加面板支持按中文名和域名搜索，同一家的不同套餐和地区合并成一行。预设会自动填充端点地址，你只需要填写 API Key。

第二步：切换供应商 Copy Chapter

添加完成后，供应商会出现在列表中。

方式一：应用页切换

• 点击供应商卡片的「切换」按钮，状态会显示为「使用中」
• OpenCode、OpenClaw、Hermes、MiniMax Code 是共存式应用，按钮为「添加」（Pi 为「启用」），可以同时添加多个供应商

方式二：托盘快速切换

• 右键系统托盘图标
• 每个工具一行，显示「名称 · 模式 · 供应商 · 额度」，在子菜单里直接点击供应商名称（支持 Claude Code、Claude Desktop、Codex、Gemini CLI、Grok Build）

第三步：生效方式 Copy Chapter

切换供应商后，各 CLI 工具的生效方式不同：

处于路由模式时，Claude Code、Codex、Gemini CLI、Grok Build 切换供应商会立即作用于后续请求；但如果切换改变了模型，Codex、Gemini CLI 和 Grok Build 仍可能需要重启。

直连、路由和聚合（可选） Copy Chapter

Claude Code、Codex、Gemini CLI、Grok Build 的页面顶部有「直连 / 路由」标签，Claude Code 和 Codex 还有「聚合」。点标签只是切换查看的内容，不会改动配置；真正切换要点页面上写明后果的按钮：「开始路由」、「切换到聚合模式」，回到直连点「回到直连」。

• 直连（默认）：客户端直接连供应商，日常使用选它
• 路由：请求经本机 CC Switch 转发（默认 127.0.0.1:15721），可以转换接口格式、做故障转移。想在 Claude Code 里用 OpenAI 或 Gemini 格式的供应商，或在 Codex 里用 Claude，选它
• 聚合：把多家供应商的模型放进同一个模型列表，选哪个模型请求就发给哪一家，不做故障转移

路由和聚合需要 CC Switch 保持运行；退出 CC Switch 会自动回到直连，下次启动再接上。官方订阅不经过路由（Codex 的 OpenAI Official 例外）。详见 开启本地路由。

Claude Code 首次安装提示 Copy Section

如果 Claude Code 首次启动时提示需要登录或显示初始化引导，请在 CC Switch 中开启「跳过 Claude Code 初次安装确认」选项：

1. 打开 CC Switch「设置 → 应用配置」，找到 Claude Code 一块
2. 开启「跳过 Claude Code 初次安装确认」开关
3. 重新启动 Claude Code

⚠️ 注意：此选项会在 ~/.claude.json 中写入 hasCompletedOnboarding: true，跳过官方的初次安装确认流程。

验证配置 Copy Chapter

重启后，启动对应的 CLI 工具并输入简单的问题进行测试：

# Claude Code - 启动后输入测试问题
claude
> 你好，请简单介绍一下自己

# Codex - 启动后输入测试问题
codex
> 你好，请简单介绍一下自己

# Gemini - 启动后输入测试问题
gemini
> 你好，请简单介绍一下自己

# OpenCode - 启动后输入测试问题
opencode
> 你好，请简单介绍一下自己

# OpenClaw - 启动后输入测试问题
openclaw
> 你好，请简单介绍一下自己

如果 AI 能正常回复，说明配置成功。

注意：首次启动时，CC Switch 会自动把 Claude Code、Codex、Gemini CLI、Grok Build 的现有配置导入为名为 default 的供应商，并为这几个工具和 Claude Desktop 添加官方供应商，原有配置不会丢失。

下一步 Copy Chapter

恭喜！你已经完成了基础配置。接下来可以：

• 添加更多供应商 - 配置多个供应商方便切换
• 配置 MCP 服务器 - 扩展 AI 工具的能力
• 设置系统提示词 - 自定义 AI 的行为
• 开启本地路由 - 使用需要格式转换的供应商、自动故障转移
• 管理 AI 编程工具 - 在侧栏「应用」页安装、升级工具，选择侧栏显示哪些应用
• 查看用量统计 - 统计请求数、Token 和花费

常见问题 Copy Chapter

切换后不生效？ Copy Section

确保重启了终端或 CLI 工具。配置文件在切换时已经更新，但运行中的程序不会自动重新加载。

找不到预设？ Copy Section

如果你的供应商不在预设列表中，选择「自定义」手动配置。参考 添加供应商 了解配置格式。

如何恢复官方登录？ Copy Section

Claude Code、Claude Desktop、Codex、Gemini CLI、Grok Build 的供应商列表里都自带一个官方供应商（如 Claude Official、OpenAI Official、Google Official、Grok Official），切换过去后重启客户端，按工具自身的登录流程操作即可。如果列表里没有（例如删掉了，或从旧版本升级），可以从预设里重新添加。

Pi Frontend Uiux Guidelines Zh (`docs/pi-frontend-uiux-guidelines-zh.md`) Copy Section

Pi 前端 UI/UX 需求与规范

状态：当前 Pi 前端的评审基线
适用范围：供应商、提示词、Skills、Sessions，以及以后考虑接入的 Pi 原生设置
最后更新：2026-08-05

这份文档面向 cc-switch 的设计者、开发者和评审者。它不是功能清单，也不是用户手册。新增 Pi 界面或字段时，应先用本文判断该能力是否该由 cc-switch 提供，再讨论具体组件。

文中的“必须”是合并前要求；“应该”允许有明确理由的例外；“不得”表示当前产品边界。

1. 产品目标 Copy Chapter

Pi 界面必须同时满足两类用户：

• 第一次使用的小白能看懂哪些供应商已加入 Pi，知道从哪里添加供应商，并能完成 API Key、请求地址和模型配置。
• 熟悉 Pi 的用户可以在第一次创建时配置接口格式、模型能力和请求头，不需要先保存一份错误配置再回来修改。

“简单”指默认路径短、入口少、术语清楚，不是删除必要能力。普通字段直接展示，少用解释文字；只有在不解释就可能误用、丢数据或改变 Pi 行为时才保留提示。

稳定性优先于覆盖所有边界。P0、P1 问题必须解决；罕见且低影响的 P2 可以记录后延期。不要为了单条评审意见叠加新的影子状态、特殊分支或一次性组件。

2. 设计来源与家族化原则 Copy Chapter

Pi 不建立独立设计系统。交互参考顺序如下：

1. OpenCode：供应商是可累加配置，最接近 Pi 的供应商管理方式。
2. Hermes：模型详情、可选能力和原生设置的渐进展示。
3. Claude Code、Codex：供应商表单、请求头、配置 JSON、卡片和操作按钮的视觉语言。

应该复用现有的 ProviderPresetSelector、BasicFormFields、ApiKeySection、EndpointField、RequestHeadersEditor、JsonEditor、供应商卡片、图标、分类与合作伙伴排序。只有 Pi 原生语义无法用现有组件表达时，才增加 Pi 专用组件。

同一种信息在不同应用中应使用相同的层级、字号、间距和操作位置。Pi 可以有不同的数据语义，不能因此出现一套完全不同的布局。

3. Pi 原生语义是最高约束 Copy Chapter

所有认证、模型、文件路径、加载顺序和传输行为，必须由开发时最新 Pi 或 request capture 验证。源码阅读和经验判断只能用于提出假设，不能作为产品状态的依据。实现取舍见 Pi 原生契约与实现边界。

前端必须遵守以下规则：

• Pi 原生文件和目录采用 exists = active，不得再增加一个 enabled 字段。
• Pi 全局保存的当前供应商和模型只由后端读取：默认供应商仅用于移除或删除前的条件提醒。它们不作为供应商页面的展示状态，也不从数据库元数据猜测。
• 后端无法读取 models.json 时，涉及 Pi 供应商成员关系的写操作必须失败关闭。无法读取全局默认项时不阻止成员关系操作。
• 已存在但暂未暴露的 Pi 字段必须原样透传，结构化表单不能把未知字段清空。
• 前端只展示后端已经稳定实现的状态。没有可靠读取和写入契约的按钮不得出现。

4. 供应商页面 Copy Chapter

4.1 信息架构 Copy Section

供应商页面采用统一结构：

1. CC Switch 中保存的供应商列表。
2. 页面右上角唯一的“+”添加入口。

供应商卡片不展示模型列表。模型只在添加或编辑表单中配置，避免卡片高度失控和信息重复。

列表中的常规操作沿用家族组件：

• 启用：把供应商加入 Pi 原生配置。
• 移除：从 Pi 原生配置移除，但保留 CC Switch 中的供应商。
• 编辑：修改供应商配置。
• 删除：删除 CC Switch 中的供应商。
• 复制、连通性检测和用量配置继续使用现有上下文操作，不增加第二个主入口。
• 不提供“导入当前原生供应商”等第二个添加入口；需要托管的供应商统一从右上角“+”创建。

供应商标识是成员身份。Pi models.json 中存在该标识即表示已启用，不再比较整份 JSON 来制造“漂移”或“所有权”状态。凡是显式存在于 models.json.providers 的供应商都应同步到供应商列表，包括与 Pi 内置供应商同名的 ID；原生修改同步回已保存档案，原生移除只改变启用状态。只存在于 auth.json、/login 或环境变量中的认证状态始终由 Pi 管理，不生成 CC Switch 卡片。详细规则见 Pi 显式供应商同步需求。

4.2 Pi 当前选择的安全边界 Copy Section

CC Switch 不设置、展示或标记 Pi 的当前供应商和模型。

• 当前供应商和模型完全交给 Pi 原生 /model。
• 供应商页只管理供应商是否加入 Pi 原生配置，不显示“当前使用”“当前默认”、所有权或当前模型。
• Pi 全局默认项指向待移除或删除的供应商时，在原有确认框中增加一条非阻塞提醒，说明 Pi 会尝试其他可用模型，并允许用户继续。
• 移除或删除供应商不得修改 defaultProvider 或 defaultModel；失效引用及后续选择由 Pi 原生逻辑和 /model 管理。
• models.json 状态未知时，启用、移除和删除操作应禁用。全局默认项读取失败时不显示条件提醒，也不阻止供应商成员关系操作。

不得用“列表第一个模型”推导默认模型，也不得在保存供应商时偷偷修改 Pi 默认选择。

项目级 .pi/settings.json 依赖启动 Pi 时的工作目录，供应商页没有权威项目上下文，不扫描目录或猜测活动会话。因此条件提醒只基于全局默认项；项目级选择仍由对应 Pi 会话管理。

4.3 添加流程 Copy Section

添加流程的心智模型是：

选择预设或自定义配置 → 填写凭证与请求信息 → 配置模型 → 保存

具体要求：

• 新建页默认选中“自定义配置”，并从打开时就展示完整基础表单；预设选择器用于快速填充，不作为进入表单的门槛。
• 选择预设后直接填入供应商知识，例如请求地址、接口格式和模型；用户通常只需填写 API Key。
• 自定义配置显示供应商标识，并在创建后锁定。
• 不使用 1、2、3 编号步骤，不增加向导专属页面。
• piProviderPresets 是独立维护的 Pi 原生预设目录。可以参考其他应用的供应商知识，但不得在运行时导入或派生另一个应用的预设；Pi 的协议、请求根地址和模型能力必须在自己的目录中明确表达。
• 预设供应商必须自带完整模型能力。从“获取模型列表”选中模型时按 4.5 的规则补全能力；手动输入模型 ID 不补全。
• 提交前完成必填、重复模型、正数和请求地址校验，并把焦点移动到错误字段。

4.4 字段暴露范围 Copy Section

供应商级字段分为三类：

接口格式默认使用 OpenAI Chat Completions。可选项来自 Pi 已验证支持的协议：

• OpenAI Chat Completions
• OpenAI Responses
• Anthropic Messages
• Google Generative AI
• Amazon Bedrock

创建时不提供“自定义接口格式”。编辑已有未知格式时，应显示并保留该值，不能因为下拉列表不认识就覆盖。

请求地址的示例沿用家族写法 https://api.example.com/v1。占位文字只作格式示例，不推导实际路径。

接口兼容性与模型配置采用相同的信息层级，不使用折叠箭头。默认只显示说明和“添加”按钮；点击后，键值行直接向下追加。未配置时不向 Pi JSON 写入空的 compat。

4.5 模型配置 Copy Section

一个供应商拥有多个模型。供应商级请求地址和接口格式是默认值，不为每个模型重复创建“模型 API”和“模型基础地址”字段。

模型行默认只显示：

• 模型 ID
• 显示名称
• 展开按钮
• 移除按钮

选择或填写模型 ID 后，仅在显示名称仍为空时同步模型 ID。预设供应商已经填好模型能力；从“获取模型列表”选中模型时按下述规则补全能力，手动输入不补全。展开区只放 Pi 原生且常用的能力：

• 支持扩展思考 reasoning
• 支持图片输入 input
• 上下文长度 contextWindow
• 最大输出 Token 数 maxTokens
• 思考档位 thinkingLevelMap

自定义模型默认关闭扩展思考并使用文本输入；上下文长度和最大输出 Token 必须是正数才能保存。

从“获取模型列表”选中模型时，按以下规则补全能力（实现在 src/lib/modelMetadata.ts，与 Codex、OpenCode 等应用共用）：

• 来源依次为：同一请求地址的 Pi 预设模型、models.dev 中按请求地址认出的同一家供应商、models.dev 中该模型的原厂条目。不引用其他应用的预设。
• 必须先确定供应商再查模型，不得按模型名跨供应商投票或取最新值：同一模型在不同供应商处的上下文长度可能相差数倍。早期实现按名称投票，填出的值不可靠，曾因此整体移除。认不出供应商、原厂有歧义或查不到时保持默认值，也不根据模型前缀或相似版本猜测。
• 只补空字段：上下文长度和最大输出 Token 只在为空时填写；扩展思考和图片输入只从关闭改为开启，不替用户关闭。
• thinkingLevelMap 只在模型还没有映射、且已支持扩展思考时补：同一请求地址的 Pi 预设里人工核对过的映射优先，但映射只在预设的协议和 compat 下成立，所以要求协议相同，并把预设依赖、模型里还没写的 compat 一并补上；用户已写的 compat 与预设冲突时不套用预设映射；openai-completions 还要求补完 compat 后，Pi 按地址和 compat 探测出的思考格式及是否发送 reasoning_effort 与预设一致（预设可能没写 compat、依赖 Pi 的默认探测）。模型单独写了 baseUrl 时，按模型实际请求的地址查找预设和 models.dev。否则仅当 Pi 会把档位原样作为 reasoning_effort 发给上游时（openai-responses，或 Pi 按供应商 ID 和地址探测为 OpenAI 思考格式且支持 reasoning_effort 的 openai-completions，compat 里写明的值优先），按 Pi 官方从 models.dev 生成内置模型目录的同一规则，用按上述来源查到的 effort 档位生成（中转站认不出时取原厂条目，绝大多数中转与原厂档位一致）：列出的档位发同名值，没列出的写 null，off 在列出 none 时发 "none"。Anthropic 等需要额外 compat 的协议不生成。
• 补全后用一条提示说明来源并请用户核对。不显示“自动值”“已覆盖自动值”或“恢复自动值”等持久状态，补进来的值与手填值没有区别。
• models.dev 不可用时只用预设值，不报错。

thinkingLevelMap 排在上下文长度和最大输出 Token 之后，作为最后一项模型能力提供渐进式编辑。它默认折叠并保持整行宽度、左侧对齐；展开后用七行轻量列表直接展示字符串、Pi 默认和不可用三种状态，点击某一行才在表单中部打开该档位的编辑浮层。关闭“支持扩展思考”时整段隐藏，但不删除已有映射。

所有推理预设模型都显式提供 thinkingLevelMap；已确认的接口组合写入对应映射，其余预设使用 {} 明确沿用 Pi 默认行为。自定义模型只在从上游列表选中时按上述规则补映射，手动输入不补，用户可以随时修改。模型级 api、baseUrl、cost 等少见字段不做结构化入口，但编辑保存必须保留。

4.6 请求头 Copy Section

请求头使用 Pi 原生 headers，不得增加“请求头身份”“Claude Code”“Codex”等模板选择器，也不得自动把 API Key 塞进某个 Header。

• 没有请求头时，沿用家族编辑器的说明、空状态和“添加请求头”按钮。
• 添加后显示名称和值两列。
• Header 名称按 Enter 必须先提交名称，不能触发表单保存或静默丢失。
• 已有 Header 必须完整回显并原样保存。
• API Key 的认证方式由 Pi 和接口格式决定，请求头编辑器只管理用户明确填写的 Header。

4.7 配置 JSON 与敏感信息 Copy Section

名称统一使用“配置 JSON”，不使用“配置 JSON 预览”。

配置 JSON 默认展开并允许编辑，复用共享 JSON 编辑器的语法校验和格式化操作。结构化字段只改写自己负责的键；合法 JSON 会回填结构化字段。输入暂时不合法时保留原始草稿，不用旧结构化状态覆盖，保存前必须完成校验。

配置编辑器需要显示用户正在编辑的真实值。API Key、Authorization、Token、Secret、Password 等敏感值不得出现在编辑器以外的日志、toast、列表或测试输出中。

原配置缺少可选字段时，用户未主动修改就应保持缺失。例如根级 api 不存在时，界面可以显示默认协议帮助理解，但保存不能自动补写该字段。

4.8 认证边界 Copy Section

Pi 原生订阅登录和 OAuth 由 Pi 管理：

• 用户在 Pi 中使用 /login。
• CC Switch 不复制 auth.json，不保存或刷新 OAuth Token。
• CC Switch 不展示一套独立的“已登录”状态，也不提供 OAuth 供应商按钮。
• API Key 供应商由 CC Switch 管理。

界面不得出现“CC Switch 显示已登录，但 Pi 仍使用旧凭证或旧请求路径”的半状态。

4.9 路由与故障转移 Copy Section

Pi 前端不提供路由、网关和故障转移：

• 不显示“需要路由”“不支持路由”或 gatewayStatus。
• 不显示故障转移端点管理。
• 不显示网关凭证和网关诊断。
• 不从预设写入 allowGateway 等能力字段。

后端不得为 Pi 建立路由投影、网关状态或故障转移配置。通用代理基建遇到 Pi 时应明确跳过。

5. 提示词页面 Copy Chapter

Pi 提示词沿用 cc-switch 的列表、标签页、全屏编辑器和顶部主操作，不创建侧边栏专用设计。页面使用三个标签：

• 全局提示：管理提示库，并选择一项写入 Pi 全局 AGENTS.md。
• 全局系统提示：管理 APPEND_SYSTEM.md 和 SYSTEM.md。
• 提示词模板：管理 Pi 原生模板。

全局提示同一时间只允许一项与 AGENTS.md 精确匹配。原生文件与提示库内容不一致时，显示“外部 AGENTS.md”，不得假装某个数据库选项仍在使用。编辑或停用旧选项不能覆盖外部内容；用户明确选择另一项时，先把非空的外部内容保存进提示库，再写入所选项。

APPEND_SYSTEM.md 是普通用户的推荐入口。SYSTEM.md 会完整替换系统提示，创建前必须明确警告。文件存在就是生效，不增加启用开关。

APPEND_SYSTEM.md、SYSTEM.md 与提示词模板复用全局提示的全屏编辑表单。内容区只使用应用统一的外边距，不增加固定最大宽度；编辑器随窗口宽度伸缩。

顶部“+”根据当前标签执行对应的添加动作；系统提示标签直接编辑两个固定文件，不显示无意义的添加按钮。

提示文字只保留以下情况：

• 不解释就无法区分 APPEND_SYSTEM.md 与 SYSTEM.md。
• 操作需要在已打开的 Pi 中重新加载。
• 原生文件与 CC Switch 状态发生冲突。

不要在页面上重复显示操作完成后 toast 已经说明的内容。

6. Skills、Sessions 与后续能力 Copy Chapter

Skills Copy Section

Pi Skills 复用统一 Skills 页面和已有卡片。是否被 Pi 发现必须来自原生目录检查，不读取通用 skill.apps.pi 作为第二状态源。

全局 Skills 页的应用矩阵常驻 Pi 列（和其他应用列并排；只有在「应用」页把 Pi 设为隐藏时才不显示）。Pi 列的状态仍按上面的原生目录检查来：看 ~/.pi/agent/skills 里有没有这个目录（后端 get_installed_skills 返回前用这次检查覆盖 apps.pi，不是数据库里的开关），列头和批量弹层用「?」说明这个判断方式。

Sessions Copy Section

Pi Sessions 复用现有会话管理器。相对 session 目录缺少项目上下文时，应说明需要项目目录；目录不可用时显示错误。不要制造 CC Switch 专用的 Pi 会话格式。

Extensions 与 Themes Copy Section

Pi Packages、Extensions 与 Themes 由 Pi 原生管理，当前不进入 CC Switch 产品界面。CC Switch 不复制扩展文件，也不维护第二套安装、启用或更新状态。

7. 文案与视觉规范 Copy Chapter

固定术语如下：

普通字段 Label、模型配置标题和请求头标题使用同一视觉等级。当前实现基准为 14px / 400 / 20px。不要仅把某一组字段加粗，造成虚假的一级分区。

按钮、图标、圆角、边框和 hover 状态使用现有设计令牌。交互动画保持 150–300ms，并支持 prefers-reduced-motion。深色和浅色主题都必须保证文字、边框和禁用状态可辨认。

每个输入都有可关联的 Label。图标按钮需要可访问名称。动态错误使用 role="alert" 或合适的 live region。键盘操作不能丢失尚未提交的输入。

8. 新字段和新功能的准入条件 Copy Chapter

计划新增任何 Pi 设置时，依次回答：

1. 这是开发时最新 Pi 已验证的原生能力吗？
2. 它是创建或日常管理中常见、必要的字段吗？
3. 这项操作属于 CC Switch，还是应该交给 Pi 的 /login、/model 等原生命令？
4. 后端能稳定读取、写入并无损往返吗？

四项都满足才进入默认界面。Pi 原生但罕见的字段优先透传；需要专业用户偶尔修改的字段可以进入渐进区域；不属于 CC Switch 或缺少可靠后端支持的能力不进入 UI。

参考 OpenCode 或 Hermes 时只复用相同问题的成熟交互。不能因为另一个应用有某个字段，就假设 Pi 也需要。

9. 错误处理与安全 Copy Chapter

• 状态未知时，不用猜测值恢复写操作。
• 删除和移除必须有确认；目标是 Pi 全局默认供应商时，在同一个确认框内增加非阻塞提醒。
• 保存失败后保留用户输入，显示具体错误。
• 表单错误就地显示并聚焦对应字段。
• 日志、toast、列表和测试输出不得泄露 API Key 或 Header 中的凭证。
• 外部原生内容发生变化时，刷新列表会按精确 ID 自动同步，不增加确认或 ownership 状态。

10. 验收 Copy Chapter

功能验收至少覆盖：

• 首次进入默认选中“自定义配置”，能同时看到预设选择和可立即填写的基础表单。
• 预设创建、自定义创建、模型获取、模型能力预填和手动覆盖。
• Header 的添加、Enter 提交、编辑、移除与无损回显。
• 配置 JSON 与结构化字段双向同步，格式化可用，并与实际保存内容一致。
• 已有未知字段、缺失可选字段和精确模型 ID 的无损往返。
• Pi 供应商配置加载、错误、外部新增、修改、删除与启用状态同步。
• Pi /model、/login 的所有权没有被 CC Switch 接管。
• 中、英、日、繁中术语覆盖。
• 键盘、浅色/深色主题和常见窗口宽度。

真实联调应使用已安装的 Pi，验证添加、启用、移除、编辑、模型获取、请求发送和 Pi 原生命令后的状态同步。协议与能力结论必须保留 oracle 或 request-capture 证据。

Pi Live Provider Sync Requirements Zh (`docs/pi-live-provider-sync-requirements-zh.md`) Copy Section

Pi 显式供应商同步需求

背景 Copy Chapter

Pi 会读取 ~/.pi/agent/models.json 中的 providers，并把同名显式供应商配置与自己的内置供应商、内置模型合并。当前 CC Switch 会跳过 anthropic、openai、deepseek 等 Pi 内置供应商 ID，导致 Pi 已经加载了显式配置，但 CC Switch 页面没有对应的已启用卡片，也无法正常移除、编辑或重新启用。

这类供应商是否属于 CC Switch 可管理范围，应只由配置来源决定，不能再由供应商 ID 或认证类型决定。

目标架构 Copy Chapter

整体行为与 OpenCode 的累加式供应商管理保持一致：

Pi 额外需要支持同名内置供应商的显式覆盖：只要供应商节点存在于 models.json.providers，无论 ID 是否为 anthropic、openai、deepseek 或其他 Pi 内置 ID，都必须按普通显式供应商处理。

显式供应商同步规则 Copy Chapter

• models.json.providers 是 Pi 当前启用的显式供应商集合。
• 任意精确 provider ID 都可被同步，不使用内置供应商集合过滤。
• 数据库中没有对应记录时，按精确 provider ID 自动导入并 upsert。
• 数据库中已有记录时，用 Pi 当前的显式配置同步对应记录。
• provider 节点存在于 models.json 时，卡片显示为已启用。
• provider 只存在于 CC Switch 数据库时，卡片保留并显示为未启用。
• 已启用卡片沿用 OpenCode 的蓝色高亮。
• 外部修改 models.json 后，刷新供应商页面即自动同步，不要求二次确认。
• 不再出现“不是 CC Switch 管理的值”或“配置刚发生变化，请确认后重试”等 ownership 冲突提示。
• PI_BUILTIN_PROVIDER_KEYS 或等价集合不能参与配置归属判断，也不能用于跳过 live provider 同步。

认证边界 Copy Chapter

边界按配置来源划分：

• models.json.providers 中的显式配置由 CC Switch 管理。
• Pi /login 写入 auth.json 的凭证始终由 Pi 管理，无论其类型为 OAuth 还是 API Key。
• CC Switch 不读取、复制、修改或删除 auth.json 中的凭证。
• CC Switch 不刷新 OAuth Token。
• 只有 auth.json 凭证、没有 models.json.providers 节点的供应商，不生成 CC Switch 卡片。
• 环境变量中的凭证不导入 CC Switch。
• 同一供应商同时存在显式配置和 Pi 登录时，CC Switch 只管理显式配置。
• 移除显式配置不退出 Pi 登录，也不删除 auth.json。
• 用户在 CC Switch 中创建的 API Key 供应商仍由 CC Switch 保存并写入 models.json；用户通过 Pi /login 保存的 API Key 仍属于 Pi 原生认证状态。

启用与移除 Copy Chapter

启用 Copy Section

• 将 CC Switch 数据库中保存的完整配置写入 models.json.providers.。
• 成功后卡片变为蓝色已启用状态。
• 不修改 Pi 默认供应商、默认模型或 auth.json。

移除 Copy Section

• 只删除 models.json.providers.。
• 不删除 CC Switch 数据库记录。
• 卡片继续保留并变为未启用，之后可以再次启用。
• 不修改 auth.json、环境变量或 Pi 原生登录状态。
• 不因供应商当前正被 Pi 使用而阻止移除。
• 不提供“设为默认”操作；删除当前默认供应商后的回退行为由 Pi 处理。

所有配置写入复用现有原子文件更新能力，并保留与目标供应商无关的内容。

Pi 内置模型合并语义 Copy Chapter

• 接受 Pi 对同名内置供应商的原生合并行为。
• 供应商卡片只根据显式 provider 节点判断启用状态。
• 编辑页面只展示该 provider 在 models.json 中显式保存的模型。
• 不把 Pi 的内置模型复制到 CC Switch 数据库或 models.json。
• 不根据 Pi 运行时出现的模型扩充供应商预设。
• 模型 ID 按精确字符串处理，不做大小写或相似名称合并。
• 同名内置供应商的显式配置必须完整保留。
• 读取、同步、编辑和保存后，未知 JSON 字段不能丢失。

piProviderPresets、models.json.providers 和 Pi 内置模型目录是三个独立数据源，不互相替代。

实现范围 Copy Chapter

优先复用 OpenCode 已有能力：

• live provider 导入与 upsert；
• 累加模式下的启用和移除；
• live_config_managed 或等价状态；
• 供应商列表刷新；
• 原子配置文件写入；
• 未知字段保留。

主要修改范围：

• Pi live provider 配置读取；
• Pi 供应商列表同步；
• 内置 provider ID 过滤规则；
• 启用和移除操作；
• 页面刷新后的状态更新。

不增加数据库 Schema，也不建立新的 ownership 状态。

明确不做：

• OAuth 或 /login 凭证管理；
• auth.json 管理；
• 环境变量导入；
• 默认供应商或默认模型管理；
• 路由与故障转移；
• 插件管理；
• 自动重写 Pi 内置模型。

真实 Pi 验收 Copy Chapter

1. 在 models.json.providers 中分别加入带 API Key 的 anthropic、openai 和 deepseek，刷新后均出现已启用卡片。
2. Pi /model 能显示并使用这些显式配置激活的模型。
3. 点击移除后，仅删除对应 provider 节点；数据库卡片保留并变为未启用。
4. 在没有 auth.json 凭证和相关环境变量时重启 Pi，被显式配置激活的模型不再可用。
5. 再次启用后完整配置恢复，Pi 可以继续使用。
6. 在 CC Switch 外部新增、修改或删除 provider，刷新页面后自动同步。
7. Pi /login 写入的 OAuth 或 API Key 凭证不被读取或修改。
8. 移除供应商前后 auth.json 内容与文件状态完全不变。
9. 自定义 Header、模型能力字段和未知 JSON 字段在同步、编辑、保存、移除与重新启用后不丢失。
10. 所有操作前后 Pi 当前默认供应商和默认模型保持不变。
11. 模型 ID 大小写按原值保存，不进行任何模糊合并。

Pi Native Contract Zh (`docs/pi-native-contract-zh.md`) Copy Section

Pi 原生契约与实现边界

验证原则：开发和验收使用当时最新发布的 Pi；CC Switch 不绑定某个 Pi 版本。

这份文档记录 CC Switch 当前实际消费的 Pi 原生契约。它不是 Pi 配置格式的完整镜像，也不承诺代理、OAuth 或所有兼容字段。实现和测试只覆盖前端已经提供的能力。

验证方式 Copy Chapter

供应商字段、继承顺序和配置值解析以开发时最新 Pi 的源码入口和真实 CLI 行为为准。资源与会话行为通过 Pi 的 DefaultResourceLoader、loadSkills、loadPromptTemplates 和 SessionManager 实际运行确认。仓库只保留产品真正消费的最小契约和普通测试，不维护上游源码快照、哈希或版本证据库。

当前消费的契约 Copy Chapter

供应商 Copy Section

结构化表单只验证并编辑常用字段：

• 供应商级 name、baseUrl、apiKey、api、headers
• 模型级 id、name、reasoning、input、contextWindow、maxTokens

已有配置中的其他字段原样保留。供应商是否可管理只取决于节点是否显式存在于 models.json.providers：anthropic、openai、deepseek 等 Pi 内置 ID，以及带有未知字段的节点，都按普通显式配置同步。CC Switch 不把 Pi 运行时合并出的内置模型复制回配置，也不解析或执行 apiKey、Header 中的环境变量和命令表达式。请求仍由 Pi 自己发出。

Pi 在全局设置中保存的当前供应商和模型不进入供应商列表状态。启用供应商只把条目加入 models.json，不会写 defaultProvider 或 defaultModel。移除或删除全局默认供应商时，前端在原有确认框内给出非阻塞提醒，后端允许继续且不改写默认项。编辑显式供应商同样不修改当前供应商或模型；失效引用和回退由 Pi 原生处理。

项目级 .pi/settings.json 会按启动 Pi 时的工作目录覆盖全局默认项。供应商页没有项目上下文，因此不扫描项目目录或猜测活动会话；条件提醒只读取全局默认供应商。项目级默认项继续由对应 Pi 会话和 /model 管理。

用量查询脚本属于 CC Switch 元数据，只更新数据库，不重写 models.json。

并发与外部修改 Copy Section

供应商标识是成员身份：models.json.providers 中存在该标识即为已启用。CC Switch 每次进入列表及应用启动时同步全部显式节点，不按内置 ID、认证字段或模型完整度过滤。原生配置发生修改后，以原生内容更新同 ID 的已保存档案；原生删除只改变启用状态。移除前保存目标节点的最新内容，数据库中的卡片和完整配置继续保留。

models.json、系统提示文件和模板使用原子写入。进程内写操作串行化；同一次读改写期间的跨进程变化通过 revision 比较发现。列表刷新会先把外部修改同步到数据库；保存时只替换目标 provider 节点，启用和移除只增删目标节点，其他 provider 与顶层字段保持不变。不再维护编辑快照或额外 ownership 状态。

Sessions Copy Section

全局会话页只枚举绝对 sessionDir、~ 路径或 Pi 默认目录。相对 sessionDir 依赖启动 Pi 时的项目工作目录，CC Switch 没有可靠上下文，因此明确显示“需要项目上下文”，不会猜测目录。

会话解析只消费 UI 所需字段。未知条目被忽略；删除前会验证文件仍在已解析的 Pi 会话根目录中，并核对会话 ID。

明确不做 Copy Chapter

• Pi /login、auth.json 中的 OAuth/API Key 登录、令牌保存和刷新
• 默认供应商或默认模型写入
• 路由、网关、代理、故障转移和请求头合成
• Pi 运行时内置供应商与内置模型目录的复制
• 完整 compat、modelOverrides 和费用编辑器；思考档位只提供 Pi 原生 thinkingLevelMap 的轻量入口
• 相对会话目录的全局猜测

Pi 发布新版本时，通过正常开发和验收重新运行供应商、提示词、Skills 和 Sessions 契约测试。没有进入产品界面的上游字段不应仅为了“覆盖完整”而扩展后端。

Pi Thinking Level Map Requirements Zh (`docs/pi-thinking-level-map-requirements-zh.md`) Copy Section

Pi 模型能力与思考档位需求

状态：已实现并完成验收
原则：预设完整可靠，自定义配置只采用能确认来源的值；外部目录不可用时不影响使用。

1. 当前版本边界 Copy Chapter

模型能力分为两条互不混用的路径：

• Pi 供应商预设由 CC Switch 维护完整模型配置，选择后可以直接保存。
• 自定义供应商从“获取模型列表”选中模型时，按 Pi 前端设计指南 4.5 的规则从同地址预设和 models.dev 补全 reasoning、input、contextWindow、maxTokens，并在协议允许时补 thinkingLevelMap（规则见第 4 节）。

预设里的思考映射仍只在开发时人工核对后写入。

这项功能不修改数据库 Schema，不参与显式供应商同步，也不管理 Pi 的默认供应商、默认模型、auth.json、路由、故障转移或插件。

2. 预设模型 Copy Chapter

src/config/piModelCatalog.ts 只用于复用 Pi 供应商预设中的模型知识，不作为自定义模型的全局识别器。

每个预设模型必须离线包含完整的 Pi 原生字段：

{
  id: string;
  name: string;
  reasoning: boolean;
  input: Array<"text" | "image">;
  contextWindow: number;
  maxTokens: number;
}

规则如下：

• 同一模型的公共能力在目录中维护一次。
• 供应商存在特殊限制时，由对应预设显式覆盖。
• 预设别名只在该预设中有效，不能让自定义供应商中的同名 ID 自动获得能力。
• 预设数据必须随应用发布，离线可用。
• GPT-5.6 Sol 的公共上下文长度为 272000。
• 不从其他应用的预设或 Pi 运行时模型列表动态生成 Pi 预设。

3. `thinkingLevelMap` Copy Chapter

Pi 原生档位为：

type PiThinkingLevel =
  | "off"
  | "minimal"
  | "low"
  | "medium"
  | "high"
  | "xhigh"
  | "max";

type PiThinkingLevelMap = Partial<Record<PiThinkingLevel, string | null>>;

必须保留以下语义：

• 字符串表示发送给上游的实际值。
• null 表示该档位明确不可用。
• 缺少某个键表示该档位使用 Pi 默认行为。
• {} 表示整组明确使用 Pi 默认行为。
• 稀疏映射不得被自动补齐。
• reasoning: true 不代表所有档位都可用。

所有支持思考的预设模型都必须显式带有 thinkingLevelMap：

• 已确认接口语义的组合使用对应的映射。
• 尚无可靠专用映射的组合使用 {}，明确交给 Pi 原生行为。
• Anthropic 自适应思考等需要额外 Pi 原生兼容字段的预设，应同时写入必要的 compat，不能只让界面显示档位。

预设映射只在请求地址和协议都与预设相同时套用到自定义模型，并连同它依赖的 compat 一起补上（缺的才补；与用户已写的值冲突则不套用）。openai-completions 还要核对补完 compat 后的实际思考行为与预设一致，避免预设依赖 Pi 默认探测、用户又改了 compat 的情况。模型级 baseUrl 优先于供应商地址。其他供应商即使输入相同模型 ID，也不会套用预设映射。

4. 自定义模型 Copy Chapter

用户手动添加模型或从上游模型列表选择模型时：

• 模型 ID 写入表单。
• 显示名称在仍为空时同步为模型 ID，用户可以修改。
• 手动输入的模型 ID 不补全任何能力。从上游模型列表选中时，按设计指南 4.5 补全 reasoning、input、contextWindow、maxTokens，只补空字段、只往“支持”方向补，并提示用户核对。
• 选中的模型还没有 thinkingLevelMap 且支持扩展思考时补映射：同地址、同协议预设的映射优先，并补上它依赖的 compat；否则只在 Pi 会把档位原样作为 reasoning_effort 发出时（openai-responses，或探测为 OpenAI 思考格式且支持 reasoning_effort 的 openai-completions），按 Pi 官方 getEffortThinkingLevelMap 的规则，用 models.dev 的 effort 档位生成（先找按地址认出的供应商，认不出时取原厂条目）。DeepSeek、z.ai、OpenRouter、Moonshot 等有自己思考格式的地址，以及 Anthropic 等协议不生成。
• 上下文长度和最大输出 Token 必须是正数才能保存。
• “支持扩展思考”和“支持图片输入”默认分别为关闭和仅文本，用户可以随时修改。
• 开启扩展思考后才显示思考档位编辑器。
• 未填写 thinkingLevelMap 时由 Pi 使用原生默认档位；用户仍可在表单或配置 JSON 中写入字符串、null、稀疏映射或 {}。

界面不显示“自动值”“已覆盖自动值”或“恢复自动值”：补进来的值与手填值没有区别，不保留来源状态。

5. 配置 JSON 与旧配置 Copy Chapter

• 结构化字段和配置 JSON 双向同步。
• 用户已有的模型字段与 thinkingLevelMap 原样回显。
• 未知 JSON 字段无损保留。
• JSON 中的稀疏映射、单项 null 和 {} 不得改变语义。
• 旧模型缺少本版本要求的字段时，只在编辑表单中提示用户补全；用户保存后才落盘。
• 应用启动、供应商列表刷新和外部配置同步不得静默补写模型能力。

6. 验收 Copy Chapter

自动化测试至少覆盖：

• 每个预设模型都有完整的名称、思考能力、输入类型、上下文长度和最大输出 Token。
• 每个推理预设模型都显式拥有合法 thinkingLevelMap。
• 所有 GPT-5.6 Sol 预设均使用 272000 上下文。
• 手动输入模型 ID 不补全能力；从上游列表选中时只补空字段，已有思考映射不改，只在上述协议下按 Pi 官方规则生成映射，查不到时保持默认值。
• 自定义模型缺少名称、上下文长度或最大输出 Token 时不能保存，并聚焦错误字段。
• JSON 往返不丢未知字段或改变思考映射语义。

真实 Pi 验收使用隔离配置目录，并确认：

• 预设生成的完整原生模型配置可被 Pi 加载。
• Pi 对字符串、null、缺少键和 {} 的档位处理符合原生语义。
• 需要特殊兼容字段的预设产生正确的真实请求。
• 测试不修改用户实际的 auth.json、默认供应商或默认模型。

面向自定义供应商的模型数据库留待后续独立设计，不在本版本中提前保留运行时索引、网络回退或来源状态。

Guides Aggregation Mode Guide Zh (`docs/guides/aggregation-mode-guide-zh.md`) Copy Section

CC Switch 聚合模式使用指南

用 Claude Code 或 Codex 写代码时，你可能不只使用一家供应商：有自己常用的模型，也有想试试的新模型；有官方订阅，也有另外购买的 API 或编程套餐。

过去，想换一家供应商，通常要先回到 CC Switch 主界面或者托盘切换，再返回客户端继续工作。CC Switch 4.0 新增的聚合模式，让这件事可以直接在客户端里完成：把多家供应商的模型放进同一个模型列表，在应用内无感切换，选哪个模型，请求就发给对应的供应商。

目前，聚合模式支持 Claude Code 和 Codex。这篇文章就从实际效果开始，带你完成配置，并讲清默认供应商、重启和日常切换的区别。

在 Codex 里直接选择多家模型 Copy Chapter

先看开启聚合后的 Codex 桌面版。

原有的 GPT 模型与来自其他供应商的 Grok、Kimi、DeepSeek 等模型，出现在了同一个列表中。第三方模型名称后面标有供应商，方便辨认具体来源。截图中选中的是 Kimi K3（Kimi For Coding），接下来的请求就会发给配置的 Kimi For Coding 供应商。

模型名称与可选范围取决于你自己的配置，截图展示的是一组使用示例。即便两家供应商提供同名模型，你也可以根据条目中的供应商名称，选择想使用的那一条线路。

你可以在一个会话中先讨论方案，再换一个模型继续实现或检查代码，不必为了更换供应商重新开始一段对话。配置完成之后，日常选模型就在客户端里进行。

聚合模式怎样分发请求 Copy Chapter

聚合模式做了两件事：先把各家的模型整理到客户端的模型列表里，再根据你选中的条目，把请求发给对应供应商。

例如，你选择 Kimi For Coding 提供的模型，CC Switch 就使用这家供应商的连接配置转发请求；换成 DeepSeek 提供的模型，后续请求就交给 DeepSeek。每次请求按所选条目发送，加入多家供应商不会让它们同时回答同一个问题。

有时你会看到带 ccs- 前缀的模型 ID。这是 CC Switch 用来识别供应商和模型的标记，直接在模型列表里选择即可，不需要手动编写。

在 CC Switch 中完成配置 Copy Chapter

下面以 Codex 为例。Claude Code 的入口和操作方式相同，但两个应用的聚合名单需要分别配置。

截图顶部显示“聚合生效中”，默认供应商是 OpenAI Official，另外添加了 6 家供应商、共 13 个模型。每张卡片旁边也标出了这家供应商配置的模型数量。

第一步 进入聚合页面 Copy Section

在 CC Switch 左侧选择 Codex，然后点击顶部的「聚合」标签。

点标签只是切换正在查看的页面，不代表已经开启聚合。 是否真正生效，要看顶部的模式状态。

第二步 准备供应商和模型列表 Copy Section

如果还没有供应商，点击右上角「添加供应商」，按所选预设填写连接信息，例如 API 地址和密钥；需要登录或绑定账号的供应商，则完成对应的账号配置。已有供应商可以直接点击卡片上的编辑按钮。

在「聚合」页添加或编辑时，表单会集中展示连接信息和「模型列表」。最近的版本进一步强化了模型列表获取和模型信息补全，配置多家供应商时，可以省去不少逐个查找、复制和填写的工作。

一键获取：从供应商拉取模型列表

填好连接信息或完成账号配置后，点击「获取模型列表」，CC Switch 就会向供应商查询可用模型。新版适配了更多供应商的模型接口地址和返回格式，减少了因为接口差异而获取不到列表的情况。

获取成功后，可以搜索、勾选需要的模型，再点击「添加所选模型」批量加入。这一步决定哪些模型会出现在客户端的选择器里：你可以只留下常用的几个，不必把供应商返回的全部模型都加入聚合。

自动补全：选好模型后，补上它的能力信息

勾选需要的模型并加入列表后，CC Switch 会自动从 models.dev 拉取对应模型的资料，补全上下文窗口、思考等级等信息。以本文的 Codex 配置为例，还会根据可用资料补充文字、图片输入能力。选好模型后，这些信息会自动填入空缺的配置项，省去逐项查资料、手动填写的工作。

补全会优先参考与当前供应商地址匹配的内置预设，再结合 models.dev 中的供应商和原厂模型资料。已有的参数会保留，自动补全只填写空缺项；补全后还会提示信息来源，方便核对。不同供应商部署同一模型时，实际支持的窗口和能力可能不同，因此仍应以当前供应商的支持情况为准。

手动添加：用于列表缺失或自定义模型

如果供应商没有开放模型列表接口，或列表里暂时没有你需要的模型，可以点击「手动添加」，填写供应商实际支持的模型 ID，再按需填写显示名称和能力参数。它适合补充自动获取未覆盖的条目，例如供应商提供的自定义模型别名。

这里配置的模型，是之后在客户端里可选的内容。无论自动获取还是手动添加，填写名称和参数都不会改变模型本身的能力。

列表中的 ★ 表示这家供应商的默认模型。在 Claude Code 中，它位于列表第一项；这家成为默认供应商后，启动默认和后台任务等默认角色会使用它。Codex 则使用配置中指定的默认模型。

第三步 把供应商加入聚合名单 Copy Section

在「可添加」区域找到需要的供应商，点击「添加」。添加后，它会进入聚合名单。

添加供应商配置与加入聚合名单是两件事。只是创建了一张供应商卡片，还需要把它加入当前应用的聚合名单。

第一次使用，可以先配好常用的两三家，确认模型能够正常调用，再逐步增加。

第四步 选择默认供应商并开启 Copy Section

点击「切换到聚合模式」，在确认框中选择默认供应商，检查将加入的供应商和模型数量，然后确认。

进入聚合时，CC Switch 会自动启动所需的本地路由服务。看到顶部显示“聚合生效中”，就表示模式已经开启。接下来按客户端要求重新加载模型列表，再选择模型开始使用。

默认供应商负责什么 Copy Chapter

默认供应商承接没有明确指定聚合供应商的普通模型请求。 你在客户端明确选中了某家聚合模型后，那次请求就会交给对应供应商处理。

如果你在 Codex 中使用官方账号，同时也想调用第三方模型，可以像截图一样，将 OpenAI Official 设为默认供应商，再添加其他供应商。官方模型和第三方模型就能在同一个选择器中使用。

Codex 的官方账号只能作为默认供应商，不能作为普通聚合成员加入。

开启聚合后，想更换默认供应商，可以在目标供应商卡片的「更多」菜单里选择「设为默认」。当前默认供应商不能直接移除，需要先把另一家设为默认。

官方订阅的支持范围与账号风险 Copy Chapter

Codex 本身支持自定义模型供应商，官方文档也提供了通过代理使用 OpenAI 认证的配置方式。CC Switch 因此支持将 OpenAI Official 设为默认供应商，让官方模型与第三方模型出现在同一个列表中。不过，支持这种接入方式，不等于可以承诺账号“零风险”，使用时仍需遵守平台规则。Codex 官方认证说明

Claude 官方订阅的情况不同。Anthropic 对第三方工具使用订阅凭据有明确限制，包括禁止第三方开发者代用户通过 Free、Pro 或 Max 订阅凭据转发请求，以及收集、存储或中介处理 Claude.ai 登录凭据。这与用户在原版 Claude Code 中正常登录自己的订阅是不同的情况。Claude Code 官方规定

考虑到许多 CC Switch 用户并不熟悉这些接入方式和规则差异，我们选择采取更保守的支持策略：聚合模式暂不支持 Claude 官方订阅。需要使用该订阅时，请回到直连模式，在 Claude Code 中通过官方登录流程使用。这个限制针对官方订阅接入，不代表 Claude Code 的聚合模式不能使用其他已支持的模型供应商。

在 Claude Code 中使用聚合模型 Copy Chapter

在 CC Switch 左侧选择 Claude Code，配置好它自己的供应商和聚合名单，然后开启聚合。在 Claude Code 中输入 /model，就能看到模型列表。

截图中的 Kimi、Grok、Claude 和 GPT 系列模型来自不同供应商。括号里显示供应商名称，右侧还展示模型 ID 和配置的上下文窗口。

选择所需条目后，就可以继续当前会话。模型的上下文窗口、图片输入和工具能力仍取决于实际模型及上游支持，不能只靠修改显示名称或窗口配置获得。

Claude Code 需要 2.1.243 或更新版本才能显示聚合模型。模型列表修改后可以立即生效，无需重启。CC Switch 改写客户端配置后，如果当前选中的是聚合模型，按提示重新选择一次即可。

Codex 需要怎样重启 Copy Chapter

Codex 在启动时读取模型列表。因此，进入或退出聚合模式、添加或移除供应商、修改模型列表后，需要重新加载。CC Switch 页面里的黄色提示，就是在提醒客户端还在使用旧列表。

所有终端中的 Codex CLI 共用守护进程，重启会中断相关的运行中任务，操作前先等任务结束。

重新加载针对的是配置或模型列表发生变化。 在已经加载好的模型列表里选择另一个模型，不需要每次重启。

聚合和路由怎么选 Copy Chapter

CC Switch 的三种模式，适合不同的使用习惯。

聚合模式不做故障转移。 选中的供应商不可用时，需要手动选择其他可用模型。原有故障转移队列和设置会保留，回到路由模式后可以继续使用。

聚合也不会自动比较价格、挑选最快的模型。它把选择放到你手里：用哪一个模型、走哪一家供应商，由你在客户端决定。

日常使用的几个细节 Copy Chapter

使用期间保持 CC Switch 运行。 聚合请求需要经过本地服务转发。正常退出 CC Switch 时会自动恢复直连配置，下次启动再接上；之后按页面提示处理客户端刷新。

切换模型后的第一轮，费用可能更高。 在同一会话里换模型，新模型可能需要重新建立提示词缓存。历史对话越长，重新处理上下文的成本越值得留意，缓存通常不能在不同供应商之间直接共享。

模型选中后仍可能受到能力差异影响。 CC Switch 会按配置进行必要的接口转换，但不同模型在图片、推理等级、联网搜索等方面的支持并不完全相同。选择模型时，还要考虑正在进行的任务需要哪些能力。

移除供应商后，记得重新选模型。 如果客户端还保留着已移除供应商的旧聚合选项，请求会报错并提示重新选择，不会自动改发给另一家。切回路由模式后，聚合模型会从列表撤下，聚合名单则会保留。

配置好聚合后，你可以让常用模型保持默认，把其他模型留在选择器中，需要时再切换。在熟悉的 Claude Code 或 Codex 会话里，就能完成从选模型到继续工作的整个过程。

Codex 子 agent 读不到任务怎么办 Copy Chapter

在 Codex 聚合模式里，主 agent 和子 agent 可以选不同供应商的模型。这个开关现在默认打开；如果你把它关了，子 agent 一启动就可能报错，常见的提示有：

• Encrypted function output content could not be decrypted
• stream disconnected before completion
• CC Switch 返回的 unreadable_encrypted_agent_task，提示里会直接指向下面这个开关

原因在 Codex 新版的子 agent 机制。 主 agent 派任务时，任务内容由主 agent 所在的供应商加密，只有这一家能解开。这好比一封只有寄件方能拆的密封信：子 agent 用的是同一家时能读，换成另一家就拆不开，等于没拿到任务。OpenAI 官方加密的任务，别家同样读不了。

解决方法： 在 CC Switch 的 Codex 聚合页签右上角点齿轮，打开「聚合设置」，把「聚合模式下子 agent 用经典工具」重新打开，然后重启 Codex（重启方法见上文“Codex 需要怎样重启”）。打开后，聚合里的所有模型改用 Codex 经典的子 agent 工具，任务以明文传递，换哪一家都能读。

关于这个开关需要知道几点：

• 有代价。 经典工具没有 followup_task、interrupt_agent 等新版功能，所以只有主、子 agent 始终在同一家时才可以关掉；这个开关默认打开。
• 只影响聚合模式。 直连和路由模式下 Codex 的行为不变。
• 开了仍报错，先查 config.toml。 如果 ~/.codex/config.toml 的 [features] 里有 multi_agent_v2 = true，它的优先级高于这个开关，开关不会生效，「聚合设置」里也会给出提示。删掉这一项后再重启 Codex。

想要新版功能而关掉开关时，就得让子 agent 使用和主 agent 同一家供应商的模型，这样任务才能正常解开。

想固定让子 agent 用另一个模型？ 切换到聚合模式的确认框里、以及同一个「聚合设置」里，都有「子代理模型」和「子代理推理强度」：比如主 agent 用 GPT 做规划和审核，子 agent 固定用 DeepSeek 去搜代码、改代码。选好后 CC Switch 写进 config.toml 的 [agents]，不用重启 Codex，新开的对话就会用上（已经开着的对话仍按原设置）。这时子 agent 和主 agent 不在同一家，经典子 agent 工具必须开着（默认就是开的）。所选模型如果被移出聚合，子 agent 会暂时跟随主模型，加回来后自动恢复。

官方额度用完后，第三方模型也发不出去怎么办 Copy Chapter

默认供应商是 OpenAI Official 时，官方的 5 小时额度一旦用完，Codex 可能会锁住发送键，或者把模型选择器收成只剩“Luna Reserve”一项。这时聚合里的第三方模型既选不了，也发不出去。

这是 Codex 客户端自己的限制。 2026 年 9 月起的新版 Codex 会自己向 OpenAI 查询账号额度，发现普通额度用完后，就在请求发出之前把模型换成 Luna Reserve（gpt-reserve），其他模型要等额度恢复才回来。这个判断只看当前配置是否使用官方登录，不管你选的是哪家模型；请求也根本到不了 CC Switch，所以 CC Switch 这一侧没办法放行。

绕开方法： 额度恢复前，暂时让第三方当默认供应商。

1. 在 Codex 的聚合页，打开任意一家第三方供应商卡片的「更多」菜单，选择「设为默认」。
2. 彻底重启 Codex（方法见上文“Codex 需要怎样重启”），然后新开一个会话。已经被切到 Luna Reserve 的会话，可能仍保留这个模型。
3. 官方额度恢复后，再把 OpenAI Official 设回默认，并同样重启 Codex。

期间 OpenAI 官方模型不会出现在选择器里，设回默认后就会回来。它们本来就已经用完额度，所以这样换不会有额外损失。

这个办法依据 Codex 公开源码里的判断条件。如果按上面的步骤操作后仍然被锁，欢迎到 #7962 反馈。

不用聚合、直连第三方供应商时也可能遇到同样的情况。如果在「设置 → 应用配置 → Codex」里打开了「非接管切换时保留官方登录」，Codex 会继续按官方账号判断额度。关掉这个开关，重新切换一次供应商，再重启 Codex 即可；切回官方时，登录会自动恢复。

致敬 opencodex Copy Chapter

CC Switch 的聚合模式大量学习和参考了 opencodex：通过供应商前缀区分模型，让多家模型同时出现在客户端的选择器里；让 Codex 在使用第三方模型时也能处理上下文压缩；检测后台服务是否仍在使用旧的模型列表，并提醒用户重启。这些设计都受益于 opencodex 的开源探索。

感谢作者 @lidge-jun 和贡献者们把这些成果分享出来，让其他开发者能够学习、借鉴，并继续改进用户体验。向他们的工作和开源精神致敬！

如果你希望在 Codex 或 Claude Code 中接入更多供应商和模型，也非常推荐了解和试用 opencodex。

相关文档 Copy Chapter

• 聚合模式用户手册
• 本地路由

Guides Claude Codex Routing Guide En (`docs/guides/claude-codex-routing-guide-en.md`) Copy Section

Using GPT Models in Claude Code with CC Switch

Applies to CC Switch 3.17.0 and later. (Both integration methods in this guide existed in earlier versions, but the gpt-5.6 preset and the client-identity fix landed in 3.17.0; on older versions, requesting new models like gpt-5.6-luna falsely returns 404.) This guide is compiled from the repository's documentation and code, and all sample data has been de-identified.

Why local routing is needed Copy Chapter

Claude Code targets the Anthropic Messages protocol — that is, /v1/messages — whereas the upstreams for Codex-family models, whether the OpenAI Responses API exposed by a third-party gateway or the Codex service behind a ChatGPT subscription, all speak the Responses protocol. The two protocols use completely different request bodies, streaming events, and response structures, so putting such an endpoint directly into Claude Code's config leaves the upstream receiving a /v1/messages request it doesn't recognize — which can only fail.

CC Switch's approach is to keep Claude Code always connected to the local route and still sending requests as Anthropic Messages; once the route detects that the active provider is Responses-format, it converts the request into Responses for the upstream, then converts the response back into the Messages shape it returns to Claude Code — tool calls, images, PDFs, and thinking configuration are all within the conversion scope.

This guide covers both integration methods:

• Method 1 (API Key): you have a gateway endpoint and key compatible with the OpenAI Responses API, and you want to run the GPT-family models behind it inside Claude Code.
• Method 2 (ChatGPT subscription): you have a ChatGPT Plus/Pro subscription and use its quota directly by signing in through Codex OAuth — no API key needed at any point.

The chain has four main steps:

1. When Claude Code is taken over, ANTHROPIC_BASE_URL in ~/.claude/settings.json is written as the local route address (default http://127.0.0.1:15721), the auth entry keeps only a placeholder, and real credentials never enter the live config.
2. The provider's API Format is set to OpenAI Responses, telling the route that the real upstream speaks the Responses protocol.
3. The route converts the /v1/messages request into a Responses request body for the upstream; Method 2 additionally carries the OAuth token and the official client identity to reach ChatGPT's Codex service.
4. After the upstream responds, the route converts the Responses JSON/SSE back into the Messages shape Claude Code understands.

Prerequisites Copy Chapter

• CC Switch installed and able to start (3.17.0 or later; see the version note at the top for why).
• Claude Code installed and run at least once.
• For Method 1: a service endpoint compatible with the OpenAI Responses API and its API Key; follow the gateway's documentation for the endpoint and model names. Note it's the Responses API, not Chat Completions; a gateway that only offers the Chat format still works — see the API Format note in Step 1.
• For Method 2: a ChatGPT Plus/Pro subscription account.

Step 1: Add a provider Copy Chapter

Method 1: Third-party Responses gateway (API Key) Copy Section

Open CC Switch, switch to the top-level Claude Code tab, click the plus button in the upper-right corner to add a provider, keep the default Custom Configuration, then fill in:

• Provider Name: anything you like, e.g. GPT Gateway.
• API Key: your gateway key. The real key is stored only in CC Switch and injected by the local route when forwarding.
• API Endpoint: just the gateway's service root, e.g. https://gpt-gateway.example.com, without a trailing slash — the route sends requests to the gateway's Responses endpoint (/v1/responses) automatically. When the gateway path is unusual, turn on the Full URL toggle next to it and paste the complete endpoint verbatim.

Then expand Advanced Options:

• API Format: change from the default Anthropic Messages (Native) to OpenAI Responses API (Requires routing). If the gateway only offers the Chat Completions protocol, choose OpenAI Chat Completions (Requires routing) here instead; every other step is identical.
• Auth Field: keep the default ANTHROPIC_AUTH_TOKEN (Default); the route sends Authorization: Bearer <key> to the upstream — exactly the auth header an OpenAI-compatible gateway expects. Unless the gateway's documentation explicitly requires x-api-key, don't switch to ANTHROPIC_API_KEY; the wrong choice typically shows up as 401/403.
• Model Mapping: map Claude Code's model roles to the real models the gateway recognizes. At minimum, fill in the Default fallback model (e.g. gpt-5.6, per the gateway's documentation) — if left empty, unmatched requests pass through to the upstream under the original Claude model name and error out, while roles you haven't configured individually fall back to it. For finer control, specify per row: put your main model in Sonnet/Opus, and a cheap, fast model in Haiku (Claude Code's background sub-tasks use this tier). The Display name only affects what shows in the /model menu; leave it empty to show the real model name directly.
• Declare 1M: the 1M checkbox on each model-mapping row declares to Claude Code that the tier supports a 1M context. Check it only when the gateway truly serves that model with a window of one million tokens or more (e.g. a gateway offering gpt-5.6 at its API spec); otherwise long conversations will error out at the upstream's real ceiling.

After saving, a Needs Routing marker appears on the card — providers like this only work while local routing is running.

Method 2: ChatGPT subscription (Codex OAuth) Copy Section

Again on the Claude Code tab, click the plus button and pick the Codex preset with the OpenAI icon from the preset list — it appearing under the Claude Code tab is not a mistake; this preset is built precisely for "using a ChatGPT subscription inside Claude Code":

• No API Key and no address needed — requests always go to ChatGPT's Codex service, so the address field in the form needs no changes.
• Click Sign in with ChatGPT. This is a device-code flow: CC Switch opens the browser automatically and copies the verification code to the clipboard; paste the code on the browser page to complete authorization, while the app shows Waiting for authorization....
• After a successful sign-in, Auth status shows the signed-in account (email). Multiple accounts are supported: you can Add another account, Set as default, or pin a specific account to this provider; day-to-day management can also go through Settings → OAuth Authentication Center.
• FAST mode: an optional toggle; when on, requests carry service_tier="priority" for lower latency but consume ChatGPT quota at a higher rate. Keep it off by default.
• The model tiers are pre-filled: Sonnet/Opus map to gpt-5.6-sol, and Haiku maps to gpt-5.6-luna (used for background sub-tasks — faster and lighter on quota).

The login credentials are stored in ~/.cc-switch/codex_oauth_auth.json (not ~/.codex/), independent of the Codex CLI's own login; the token refreshes automatically before it expires.

Step 2: Enable local routing and take over Claude Code Copy Chapter

Go to the Routing page in Settings, expand Local Routing, and complete two toggles:

1. Turn on the Routing Master Switch to start the local service (the first time you enable it, an explanatory confirmation dialog appears). The default address is 127.0.0.1:15721.
2. Turn on Claude Code under Routing Enabled. If you only want Claude Code to use routing, leave the other apps off.

After takeover, CC Switch points Claude Code's live config at the local route, with only a placeholder in the auth entry; both Method 1's gateway key and Method 2's OAuth token are injected by the local route on forward.

Note: the live config is read when the Claude Code process starts. After you first enable takeover (or disable it to restore a direct connection), if Claude Code is already running, open a new terminal session. Afterward, switching providers in routing mode is a hot switch and needs no further restart.

Step 3: Switch providers and verify Copy Chapter

Return to the Claude Code provider list and click Enable on the target provider. If routing isn't running, CC Switch shows "This provider uses OpenAI Responses API format, requires the routing service to work properly. Start routing first." — this notice doesn't block the switch, but with routing off the request is bound to fail, so go back to Step 2 and turn it on.

Inside Claude Code you can verify step by step:

• Open a new session and use /model to view the model menu: each tier shows the display name from the model mapping (by default, Method 2 shows gpt-5.6-sol and gpt-5.6-luna). A few spots in the UI may still show Claude-family model names — those are the internal role aliases the routing takeover uses; this is normal, and the /model menu and usage dashboard are authoritative.
• Send a small question and watch the Current Provider on the Settings → Routing page change to your provider and Total Requests start to climb.
• In the usage dashboard, these requests show under the upstream's real models: gpt-5.6-sol displays as GPT-5.6 Sol (a plain gpt-5.6 without a suffix, if you enter it manually, also resolves to the Sol tier), while gpt-5.6-luna displays as GPT-5.6 Luna; you can filter by provider to reconcile token usage.
• The Method 2 provider card also shows subscription quota: utilization and reset countdowns for the 5-hour and 7-day windows, drawn from the ChatGPT account itself and shared with the official Codex client.

Capabilities and known limitations Copy Chapter

• Prompt caching is automatic: the route injects a stable prompt_cache_key per session, and together with OpenAI's automatic prefix caching, long conversations don't resend everything at full price each turn — no configuration needed.
• Thinking is mapped to reasoning effort: Claude Code's thinking toggle and thinking level are mapped to GPT's reasoning.effort (low/medium/high); GPT's reasoning content round-trips across turns intact in encrypted form, so multi-turn reasoning coherence is unaffected by the conversion. Method 2 also accesses in stateless mode (store:false), leaving no conversation stored on OpenAI's servers.
• Tools and multimodal are fully converted: multi-turn tool calls, image inputs, and PDF inputs are all fully converted.
• Context is managed against a 200K window: Claude Code auto-compacts routed providers against a default 200K window. When the upstream's real window is larger (e.g. gpt-5.6 on ChatGPT's Codex service is 372K), anything beyond 200K currently goes unused — compaction triggers early, which is conservative but safe. The only switch to push past 200K today is the 1M checkbox in the model mapping (a strict 1M declaration), for use only with Method 1 and only when the upstream truly serves the model at 1M or more; Method 2's upstream ceiling is 372K, short of 1M, so checking it would instead make long conversations error out at the upstream's real ceiling — keep it at the default.
• Output ceiling: for Method 2, the output ceiling is controlled by the ChatGPT server (the max_tokens in Claude Code's request is not sent downstream); for Method 1, Claude Code's max_tokens is passed through as-is — no configuration needed.
• Built-in web search depends on upstream support: the router translates Claude Code's hosted WebSearch tool into the Responses API hosted web_search tool. It works with Codex OAuth and compatible Responses gateways that implement that tool. allowed_domains is preserved. On API-key Responses routes, max_uses maps to the upstream max_tool_calls hard limit. The Codex OAuth request contract rejects that field, so the bridge uses a local response-side limit instead: it adds the limit to the model instructions and, when it observes an extra search call, stops the upstream stream and returns max_uses_exceeded, whether or not the request forces the hosted tool. This cuts off the entire response, including later text and function calls; if another content block is incomplete, the stream fails with stream_truncated rather than returning a partial tool call. This is not a server-enforced quota: excess searches may already have executed upstream before the proxy sees their events. Because Responses has no equivalent deny-list, a request with a non-empty blocked_domains also fails explicitly. Locally executed WebFetch is unaffected.
• Dashboard dollar amounts are for reference: token counts are accurate, but the dollar figures are estimates converted at public API prices — Method 2's subscription traffic is estimated at GPT-5.6's public price, and Method 1's third-party gateways bill at their own rates, so both may differ from what you're actually charged and serve only for comparison. For Method 2, treat the window utilization on the provider card as authoritative for quota consumption.

FAQ Copy Chapter

The upstream returns 401 or 403 (Method 1)

First confirm the Auth Field in Advanced Options is the default ANTHROPIC_AUTH_TOKEN (Default) — switching to ANTHROPIC_API_KEY sends x-api-key, which the vast majority of OpenAI-compatible gateways don't accept. Then confirm the key itself is valid and has balance.

Requesting new models like gpt-5.6-luna returns 404 Model not found (Method 2)

Upgrade to CC Switch 3.17.0 or later. On older versions the client identity wasn't aligned with the official Codex client, so the ChatGPT server resolves new models to a nonexistent engine.

The switch didn't take effect, or the /model menu still shows old names

Both the model menu and the route address are read when Claude Code starts: after first enabling takeover you must open a new terminal session; switching between providers is a hot switch, but the display names in the menu only refresh in a new session.

Claude Code reports "Codex OAuth authentication failed", or the card shows "Session expired" (Method 2)

The login credentials have expired. Go back to the provider form or Settings → OAuth Authentication Center and run through Sign in with ChatGPT again; no command-line steps are needed.

The conversation auto-compacts partway through

See "Capabilities and known limitations": routed providers are managed against a 200K window, so the compaction threshold comes early — this is expected behavior.

Restoring the official Claude setup

Switch back to an official provider, or turn off the Claude Code routing toggle on the Routing page — CC Switch restores the pre-takeover live config, and the official login credentials are unaffected throughout. After restoring, you'll again need to open a new terminal session.

Should you enable FAST mode? (Method 2)

Leaving it off is fine. Turn it on only if you're especially latency-sensitive and willing to accept faster quota consumption; if the ChatGPT server rejects the parameter, turning the toggle off restores things.

Compliance note Copy Chapter

Method 2 uses ChatGPT subscription quota outside the official Codex client, and this isn't a gray-area hack: Thibault Sottiaux (@thsottiaux), the OpenAI Codex lead, has publicly demonstrated and encouraged pointing Claude Code (the "orange crab", as he jokingly calls it) at GPT-5.6 Sol — using exactly a "local proxy + model alias" approach, the same category as Method 2 here. As the lead of the Codex product line, his active encouragement to use their own model inside a competitor's client shows that running GPT-family models in Claude Code on a subscription is a use the vendor welcomes and encourages people to try.

Two practical reminders are still worth noting: first, this traffic is counted against the same subscription quota as the official Codex client, so heavy use hits the cap sooner; second, CC Switch's authentication center keeps a compliance notice out of caution ("Use your other subscriptions in Claude Code — please be mindful of compliance risks."), and whether this fits the terms that apply to your account is for you to check. When using a third-party gateway in Method 1, separately read the target gateway's terms on billing, compliance, and data retention.

References Copy Chapter

• CC Switch User Manual: Add a Provider (incl. Codex OAuth reverse proxy and API formats)
• CC Switch User Manual: Proxy Service
• CC Switch User Manual: App Routing
• CC Switch v3.17.0 Release Notes
• Reverse guide: Using Claude Models in Codex

Guides Claude Codex Routing Guide Ja (`docs/guides/claude-codex-routing-guide-ja.md`) Copy Section

CC Switch を使って Claude Code で GPT モデルを利用する

対象バージョン: CC Switch 3.17.0 以降（本記事の 2 つの接続方法自体はより古いバージョンにもありますが、gpt-5.6 プリセットとクライアントアイデンティティの修正は 3.17.0 から導入されたため、古いバージョンで gpt-5.6-luna のような新しいモデルをリクエストすると 404 が誤って返ることがあります）。本記事はリポジトリ内のドキュメントとコードをもとに整理し、サンプルデータはすべて匿名化しています。

ローカルルーティングが必要な理由 Copy Chapter

Claude Code が前提としているのは Anthropic Messages プロトコル、つまり /v1/messages です。一方で Codex 系モデルの上流——サードパーティゲートウェイが公開している OpenAI Responses API であれ、ChatGPT サブスクリプションの背後にある Codex サービスであれ——が話すのはすべて Responses プロトコルです。この 2 つのプロトコルは、リクエストボディ、ストリーミングイベント、レスポンス構造がまったく異なります。この種のアドレスをそのまま Claude Code の設定に入れても、上流が受け取るのは自分の知らない /v1/messages リクエストであり、結果は失敗にしかなりません。

CC Switch では、Claude Code が常にローカルルートへ接続し、Anthropic Messages のままリクエストを送るようにします。ルートは現在のプロバイダーが Responses 形式だと判定すると、リクエストを Responses に変換して上流へ送り、最後にレスポンスを Messages 形式へ戻して Claude Code に返します——ツール呼び出し、画像、PDF、思考設定もすべて変換の対象です。

対応する 2 つの接続方法を、本記事はどちらもカバーします：

• 方式 1（API Key）: OpenAI Responses API 互換のゲートウェイエンドポイントと Key を持っていて、その背後の GPT 系モデルを Claude Code で動かしたい場合。
• 方式 2（ChatGPT サブスクリプション）: ChatGPT Plus/Pro のサブスクリプションを持っていて、Codex OAuth ログインでサブスクリプション枠を直接使いたい場合。全工程で API Key は不要です。

この経路は主に 4 つのステップに分かれます：

1. Claude Code を引き継ぐと、~/.claude/settings.json の ANTHROPIC_BASE_URL がローカルルートのアドレス（デフォルトは http://127.0.0.1:15721）に書き換えられ、認証項目にはプレースホルダーだけが残り、実際の認証情報は live 設定には入りません。
2. プロバイダーの API フォーマット を OpenAI Responses に設定し、実際の上流は Responses プロトコルだとルートに伝えます。
3. ルートは /v1/messages リクエストを Responses のリクエストボディへ変換して上流へ送ります。方式 2 ではさらに OAuth token と公式クライアントのアイデンティティを付けて ChatGPT の Codex サービスにアクセスします。
4. 上流から返ってきた後、ルートは Responses の JSON/SSE を Claude Code が理解できる Messages 形式へ変換して返します。

事前準備 Copy Chapter

• インストール済みで起動できる CC Switch（3.17.0 以降、理由は冒頭のバージョン説明を参照）。
• インストール済みで、少なくとも 1 回は実行したことのある Claude Code。
• 方式 1 に必要なもの: OpenAI Responses API 互換のサービスエンドポイントと対応する API Key。エンドポイントアドレスとモデル名はゲートウェイのドキュメントに従ってください。注意すべきは Responses API であって Chat Completions ではないという点です。ゲートウェイが Chat 形式しか提供していない場合でも動作します。Step 1 の「API フォーマット」の説明を参照してください。
• 方式 2 に必要なもの: ChatGPT Plus/Pro のサブスクリプションアカウント。

Step 1: プロバイダーを追加する Copy Chapter

方式 1: サードパーティ Responses ゲートウェイ（API Key） Copy Section

CC Switch を開き、上部の Claude Code タブへ切り替え、右上のプラスボタンからプロバイダーを追加します。デフォルトの カスタム設定 のまま、次の項目を入力します：

• プロバイダー名: 任意です。たとえば GPT Gateway。
• API Key: あなたのゲートウェイの Key。実際の Key は CC Switch 内にのみ保存され、ローカルルートが転送時に注入します。
• API エンドポイント: ゲートウェイのサービスルートアドレスを入力すれば十分です。たとえば https://gpt-gateway.example.com。末尾にスラッシュを付けないでください。ルートが自動的にそのゲートウェイの Responses エンドポイント（/v1/responses）へリクエストを送ります。ゲートウェイのパスが特殊な場合は、隣の フル URL スイッチをオンにして、完全なエンドポイントをそのまま貼り付けてください。

続いて 詳細オプション を展開します：

• API フォーマット: デフォルトの Anthropic Messages（ネイティブ） から OpenAI Responses API（ルーティングが必要） に変更します。ゲートウェイが Chat Completions プロトコルしか提供していない場合は、ここで OpenAI Chat Completions（ルーティングが必要） を選びます。その他のステップはまったく同じです。
• 認証フィールド: デフォルトの ANTHROPIC_AUTH_TOKEN（デフォルト） のままにします。ルートは Authorization: Bearer <key> を上流へ送ります——これはまさに OpenAI 互換ゲートウェイが期待する認証ヘッダーです。ゲートウェイのドキュメントが明確に x-api-key を要求している場合を除き、ANTHROPIC_API_KEY に変更しないでください。誤って変更した場合の典型的な症状は 401/403 です。
• モデルマッピング: Claude Code のモデル役割を、ゲートウェイが認識する実際のモデルへマッピングします。少なくとも 既定フォールバックモデル は入力してください（たとえば gpt-5.6。ゲートウェイのドキュメントに従ってください）——空欄のままだと、一致しなかったリクエストは元の Claude モデル名のまま上流へ転送されてエラーになります。個別に設定していない役割はこのフォールバックへ回帰します。より細かく設定するには、行ごとに指定します：Sonnet/Opus に主力モデル、Haiku に安価で高速なモデル（Claude Code のバックグラウンド小タスクがこの区分を使います）。表示名 は /model メニューでの表示にのみ影響し、空欄なら実際のモデル名がそのまま表示されます。
• 1M 対応を宣言: モデルマッピングの各行にある 1M チェックボックスは、その区分が 1M コンテキストに対応していることを Claude Code に宣言します。ゲートウェイが実際に 100 万トークン以上のウィンドウでそのモデルを提供している場合（たとえば API 仕様どおりに gpt-5.6 を提供するゲートウェイ）にのみチェックしてください。そうでないと、長い対話が上流の実際の上限で直接エラーになります。

保存すると、カードに ルーティングが必要 のマークが表示されます——この種のプロバイダーは、ローカルルーティングが実行中でなければ正しく動作しません。

方式 2: ChatGPT サブスクリプション（Codex OAuth） Copy Section

同じく Claude Code タブでプラスボタンを押し、プリセット一覧で OpenAI アイコンの付いた Codex プリセットを選びます——これが Claude Code タブの下に出ていても選択ミスではありません。このプリセットはまさに「Claude Code で ChatGPT サブスクリプションを使う」ために用意されたものです：

• API Key もアドレスの入力も不要です——リクエストは常に ChatGPT の Codex サービスへ送られるため、フォームのアドレス項目は変更する必要がありません。
• ChatGPT でログイン をクリックします。これはデバイスコードフローです：CC Switch が自動的にブラウザを開き、認証コードをクリップボードにコピーします。ブラウザのページで認証コードを貼り付けて認可を完了させてください。その間、アプリ内には 認証を待機中... と表示されます。
• ログインに成功すると、認証状態 にログイン済みアカウント（メールアドレス）が表示されます。複数アカウントに対応しています：別のアカウントを追加、デフォルトに設定、またはこのプロバイダーで特定のアカウントを指定できます。日常的な管理は 設定 → OAuth 認証センター からも行えます。
• FAST モード: 任意のスイッチです。オンにするとリクエストが service_tier="priority" を伴い、より低い遅延と引き換えに、より高いレートで ChatGPT のクォータを消費します。デフォルトはオフのままにしてください。
• モデル区分はあらかじめ入力済みです：Sonnet/Opus が gpt-5.6-sol に、Haiku が gpt-5.6-luna に対応します（バックグラウンドの小タスクがこれを使い、より速く、より枠を節約します）。

ログイン認証情報は ~/.cc-switch/codex_oauth_auth.json（~/.codex/ ではありません）に保存され、Codex CLI 自身のログインとは互いに影響しません。token は有効期限前に自動的に更新されます。

Step 2: ローカルルーティングを有効にして Claude Code をルーティングする Copy Chapter

設定の ルーティング ページに入り、ローカルルーティング を展開して、2 つのスイッチを設定します：

1. ルーティング総スイッチ をオンにしてローカルサービスを起動します（初回起動時は説明の確認ダイアログが表示されます）。デフォルトアドレスは 127.0.0.1:15721 です。
2. ルーティング有効 で Claude Code をオンにします。Claude Code だけをルーティングしたい場合は、その他のアプリはオフのままで構いません。

引き継ぎ後、CC Switch は Claude Code の live 設定をローカルルートへ向け、認証項目にはプレースホルダーだけが入ります。方式 1 のゲートウェイ Key も方式 2 の OAuth token も、いずれもローカルルートが転送時に注入します。

注意: live 設定は Claude Code プロセスの起動時に読み込まれます。初回の引き継ぎを有効にした後（または引き継ぎをオフにして直結に戻した後）、Claude Code が実行中の場合は、ターミナルセッションを開き直してください。その後、ルーティングモードでのプロバイダー切り替えはホットスワップになり、再起動は不要です。

Step 3: プロバイダーを切り替えて確認する Copy Chapter

Claude Code のプロバイダー一覧に戻り、目的のプロバイダーの 有効化 をクリックします。ルーティングが実行されていない場合、CC Switch は「このプロバイダーは OpenAI Responses API フォーマットを使用しており、ルーティングサービスが必要です。先にルーティングを起動してください」と表示します——この表示は切り替えを妨げませんが、ルーティングが未起動のままではリクエストは必ず失敗します。Step 2 に戻ってオンにすれば解決します。

Claude Code に入ったら、段階的に確認できます：

• 新しいセッションを開き、/model でモデルメニューを確認します：各区分にはモデルマッピングの表示名が表示されます（方式 2 のデフォルトは gpt-5.6-sol、gpt-5.6-luna）。画面の一部の箇所には Claude 系のモデル名が現れることがあります——それはルーティング引き継ぎが使う内部の役割エイリアスであり、正常な現象です。/model メニューと使用量ダッシュボードを基準にしてください。
• 小さな質問を 1 つ送り、設定 → ルーティングページの「現在のプロバイダー」があなたのプロバイダーに変わり、「総リクエスト数」が増え始めるのを確認します。
• 使用量ダッシュボードでは、これらのリクエストが上流の実際のモデルで表示されます：gpt-5.6-sol は GPT-5.6 Sol と表示され（サフィックスなしの gpt-5.6 を手動で入力した場合も Sol 区分として解析されます）、gpt-5.6-luna は GPT-5.6 Luna と表示されます。プロバイダーで絞り込んで token 使用量を照合できます。
• 方式 2 のプロバイダーカードには、さらにサブスクリプション枠が表示されます：5 時間ウィンドウと 7 日ウィンドウの利用率とリセットまでのカウントダウンです。データは ChatGPT アカウント自体から取得され、公式 Codex クライアントと同じ枠を共有します。

機能の範囲と既知の制限 Copy Chapter

• プロンプトキャッシュが自動で有効: ルートは各セッションに安定した prompt_cache_key を注入し、OpenAI 側の自動プレフィックスキャッシュと組み合わせます。長い対話でも毎回全額で再送されることはなく、設定は不要です。
• 思考を reasoning effort に換算: Claude Code の思考スイッチと思考レベルは GPT の reasoning.effort（low/medium/high）へ換算されます。GPT の推論内容は暗号化された形態でターンをまたいで完全に再生され、複数ターンの推論の一貫性は変換の影響を受けません。方式 2 は同時にステルスモード（store:false）でアクセスし、OpenAI サーバー側にはセッションを残しません。
• ツールとマルチモーダルを完全変換: 複数ターンのツール呼び出し、画像、PDF 入力はすべて完全に変換されます。
• コンテキストは 200K ウィンドウで管理: Claude Code はルーティングプロバイダーに対して、デフォルトの 200K ウィンドウで自動圧縮を行います。上流の実際のウィンドウがより大きい場合（たとえば ChatGPT Codex サービスの gpt-5.6 は 372K）でも、200K を超える部分は現状では使われません——圧縮が早めにトリガーされ、保守的ですが安全です。200K を突破したい場合、現在唯一のスイッチはモデルマッピングの 1M チェックボックス（厳密に 1M を宣言）で、方式 1 に限り、かつ上流が実際に 1M 以上でそのモデルを提供している場合にのみ使用します。方式 2 の上流上限は 372K で 1M には届かないため、チェックするとかえって長い対話が上流の実際の上限でエラーになります。デフォルトのままにしてください。
• 出力上限: 方式 2 の出力上限は ChatGPT サーバー側が制御します（Claude Code のリクエスト内の max_tokens は下流に送られません）。方式 1 は Claude Code の max_tokens をそのまま透過するため、設定は不要です。
• 組み込み Web 検索は上流の対応状況に依存: ルーターは Claude Code のホスト型 WebSearch ツールを Responses API のホスト型 web_search ツールへ変換します。このツールを実装する Codex OAuth および互換 Responses ゲートウェイで利用できます。allowed_domains は維持されます。API キーを使う Responses ルートでは、max_uses を上流の max_tool_calls ハード上限へ変換します。Codex OAuth のリクエスト仕様はこのフィールドを拒否するため、ブリッジはレスポンス側で制限します。上限をモデル指示へ追加し、超過検索を観測した時点で上流ストリームを停止して max_uses_exceeded を返します。ツールを強制するかどうかに関係なく適用されます。後続のテキストや関数呼び出しを含むレスポンス全体が打ち切られ、別のコンテンツブロックが未完了なら、不完全なツール呼び出しを返さず stream_truncated エラーにします。これはサーバー側のハード上限ではありません。プロキシがイベントを受信する前に、超過検索が上流で実行済みの場合があります。Responses には同等の拒否リストもないため、空でない blocked_domains を含むリクエストも明示的に失敗します。ローカルで実行される WebFetch は影響を受けません。
• 使用量ダッシュボードの金額は参考値: token カウントは正確ですが、ドル金額は公開 API 価格に基づく概算です——方式 2 のサブスクリプショントラフィックは GPT-5.6 の公開価格で換算され、方式 1 のサードパーティゲートウェイはそれぞれのレートで課金されます。どちらも実際の請求額と一致しない可能性があり、比較用途に留めてください。方式 2 の枠の消費は、プロバイダーカード上のウィンドウ利用率を基準にしてください。

よくある質問 Copy Chapter

上流が 401 または 403 を返す（方式 1）

まず詳細オプションの 認証フィールド がデフォルトの ANTHROPIC_AUTH_TOKEN（デフォルト） になっているか確認してください——ANTHROPIC_API_KEY に変更すると x-api-key で送信され、大多数の OpenAI 互換ゲートウェイはこれを受け付けません。あわせて、Key 自体が有効で残高があることも確認してください。

gpt-5.6-luna などの新しいモデルをリクエストすると 404 Model not found が出る（方式 2）

CC Switch 3.17.0 以降にアップグレードしてください。古いバージョンではクライアントアイデンティティが公式 Codex クライアントに揃っておらず、ChatGPT サーバー側が新しいモデルを存在しないエンジンへ解決してしまいます。

切り替えても反映されない、または /model メニューが古い名前のまま

モデルメニューもルーティングアドレスも、Claude Code の起動時に読み込まれます：初回の引き継ぎを有効にした後は必ずターミナルセッションを開き直してください。プロバイダー間の切り替えはホットスワップですが、メニューの表示名は新しいセッションでなければ更新されません。

Claude Code に「Codex OAuth 認証に失敗しました」と出る、またはカードに「セッションが期限切れです」と表示される（方式 2）

ログイン認証情報が失効しています。プロバイダーフォーム、または 設定 → OAuth 認証センター に戻り、ChatGPT でログイン をもう一度実行してください。コマンドライン操作は一切不要です。

対話の途中で自動的に圧縮されてしまう

「機能の範囲」を参照してください：ルーティングプロバイダーは 200K ウィンドウで管理され、圧縮のしきい値もそれに合わせて早まります。想定どおりの動作です。

公式の Claude の使い方に戻したい

公式プロバイダーに切り替えるか、ルーティングページで Claude Code のルーティングスイッチをオフにしてください——CC Switch は引き継ぎ前の live 設定に戻し、公式ログインの認証情報は全工程を通じて影響を受けません。戻した後も同様にターミナルセッションを開き直す必要があります。

FAST モードをオンにすべきか（方式 2）

デフォルトのオフのままで構いません。遅延に特に敏感で、かつクォータのより速い消費を受け入れられる場合にのみオンにしてください。ChatGPT サーバー側がこのパラメータを拒否する場合は、スイッチをオフにすれば復旧します。

コンプライアンスに関する注意 Copy Chapter

方式 2 は ChatGPT サブスクリプション枠を公式 Codex クライアント以外で使うものですが、これはグレーな手法ではありません：OpenAI Codex の責任者である Thibault Sottiaux（@thsottiaux）自身が、Claude Code（彼が「orange crab」と呼ぶもの）を GPT-5.6 Sol に向けて使うことを公開でデモし、推奨しています——用いているのはまさに「ローカルプロキシ + モデルエイリアス」であり、本記事の方式 2 と同じ類の手法です。Codex という製品ラインの責任者が、競合クライアントで自社モデルを使うことを自ら奨励しているのですから、サブスクリプションで Claude Code に GPT 系モデルを動かすことは、公式が歓迎し、試すことを推奨している使い方だと分かります。

とはいえ、実務上の 2 点は依然として留意する価値があります：1 つは、この部分のトラフィックが公式 Codex クライアントと同じサブスクリプション枠に合算されるため、ヘビーユースではより速く上限に達すること。もう 1 つは、CC Switch の認証センターが念のためコンプライアンス上の注意（「Claude Code で他のサブスクリプションをご利用いただけます。コンプライアンスリスクにご注意ください。」）を残していることです。あなたのアカウントに適用される規約に沿うかどうかは、各自でご確認ください。方式 1 でサードパーティゲートウェイを使う場合は、対象ゲートウェイの課金・コンプライアンス・データ保持に関する規約を別途お読みください。

参考リンク Copy Chapter

• CC Switch ユーザーマニュアル: プロバイダーを追加（Codex OAuth リバースプロキシと API フォーマットを含む）
• CC Switch ユーザーマニュアル: プロキシサービス
• CC Switch ユーザーマニュアル: アプリケーションルーティング
• CC Switch v3.17.0 リリースノート
• 逆方向のガイド: Codex で Claude モデルを使う

Guides Claude Codex Routing Guide Zh (`docs/guides/claude-codex-routing-guide-zh.md`) Copy Section

通过 CC Switch 在 Claude Code 中使用 GPT 模型

适用版本：CC Switch 3.17.0 及以上（更早版本已具备本文两种接入方式，但 gpt-5.6 预设与客户端身份修复自 3.17.0 落地，低版本请求 gpt-5.6-luna 这类新模型会误报 404）。本文根据仓库内文档与代码整理，示例数据均已去敏。

为什么需要本地路由 Copy Chapter

Claude Code 面向的是 Anthropic Messages 协议，也就是 /v1/messages；而 Codex 系模型的上游——无论是第三方网关暴露的 OpenAI Responses API，还是 ChatGPT 订阅背后的 Codex 服务——说的都是 Responses 协议。两种协议的请求体、流式事件和返回结构完全不同，把这类地址直接填进 Claude Code 的配置里，上游收到的是它不认识的 /v1/messages 请求，结果只能是失败。

CC Switch 的做法是让 Claude Code 始终连本机路由，仍以 Anthropic Messages 发送请求；路由识别当前供应商是 Responses 格式后，把请求转换成 Responses 发给上游，再把响应转换回 Messages 形态返回给 Claude Code——工具调用、图片、PDF、思考配置都在转换范围内。

对应两种接入方式，本文都会覆盖：

• 方式一（API Key）：你手里有某个兼容 OpenAI Responses API 的网关端点和 Key，想在 Claude Code 里跑它背后的 GPT 系模型。
• 方式二（ChatGPT 订阅）：你有 ChatGPT Plus/Pro 订阅，通过 Codex OAuth 登录直接使用订阅额度，全程不需要 API Key。

这条链路主要分成四步：

1. 接管 Claude Code 后，~/.claude/settings.json 里的 ANTHROPIC_BASE_URL 会被写成本机路由地址（默认 http://127.0.0.1:15721），认证项只留占位符，真实凭据不进 live 配置。
2. 供应商的 API 格式 设为 OpenAI Responses，告诉路由：真实上游说的是 Responses 协议。
3. 路由把 /v1/messages 请求转换成 Responses 请求体发给上游；方式二还会带上 OAuth token 与官方客户端身份访问 ChatGPT 的 Codex 服务。
4. 上游返回后，路由再把 Responses 的 JSON/SSE 转回 Claude Code 能理解的 Messages 形态。

准备工作 Copy Chapter

• 已安装并能启动的 CC Switch（3.17.0 及以上，原因见开头的版本说明）。
• 已安装 Claude Code，并至少运行过一次。
• 方式一需要：一个兼容 OpenAI Responses API 的服务端点和对应的 API Key，端点地址与模型名以网关文档为准。注意是 Responses API，不是 Chat Completions；网关只提供 Chat 格式时也能走通，见第一步「API 格式」处的说明。
• 方式二需要：一个 ChatGPT Plus/Pro 订阅账号。

第一步：添加供应商 Copy Chapter

方式一：第三方 Responses 网关（API Key） Copy Section

打开 CC Switch，切到顶部的 Claude Code 标签，点击右上角加号添加供应商，保持默认的 自定义配置，然后填写：

• 供应商名称：随意，例如 GPT Gateway。
• API Key：你的网关 Key。真实 Key 只保存在 CC Switch 里，由本地路由转发时注入。
• 请求地址：填网关服务根地址即可，例如 https://gpt-gateway.example.com，不要以斜杠结尾，路由会自动把请求打到该网关的 Responses 端点（/v1/responses）。网关路径特殊时，打开旁边的 完整 URL 开关原样粘贴完整端点。

然后展开 高级选项：

• API 格式：从默认的 Anthropic Messages (原生) 改成 OpenAI Responses API (需开启路由)。如果网关只提供 Chat Completions 协议，这里改选 OpenAI Chat Completions (需开启路由)，其余步骤完全相同。
• 认证字段：保持默认的 ANTHROPIC_AUTH_TOKEN（默认），路由会以 Authorization: Bearer <key> 发给上游——这正是 OpenAI 兼容网关期望的认证头。除非网关文档明确要求 x-api-key，否则不要改成 ANTHROPIC_API_KEY，改错的典型表现是 401/403。
• 模型映射：把 Claude Code 的模型角色映射到网关认识的真实模型。至少要填 默认兜底模型（例如 gpt-5.6，以网关文档为准）——留空时未匹配的请求会以原始 Claude 模型名透传给上游而报错，未单独配置的角色则会回落到它。更精细的做法是按行指定：Sonnet/Opus 填主力模型，Haiku 填一个便宜快速的模型（Claude Code 的后台小任务走这一档）。显示名称 只影响 /model 菜单里的展示，留空则直接显示真实模型名。
• 声明支持 1M：模型映射每行的 1M 复选框会向 Claude Code 声明该档支持 1M 上下文。仅当网关确实以 100 万 token 及以上的窗口服务该模型时才勾选（例如按 API 规格提供 gpt-5.6 的网关），否则长对话会在上游真实上限处直接报错。

保存后，卡片上会出现 需要路由 标记——这类供应商必须在本地路由运行时才能正常工作。

方式二：ChatGPT 订阅（Codex OAuth） Copy Section

同样在 Claude Code 标签点加号，在预设列表里选择带 OpenAI 图标的 Codex 预设——它出现在 Claude Code 标签下没有选错，这个预设就是为「在 Claude Code 里用 ChatGPT 订阅」准备的：

• 不需要 API Key，也不需要填地址——请求固定发往 ChatGPT 的 Codex 服务，表单里的地址项无需改动。
• 点击 使用 ChatGPT 登录。这是设备码流程：CC Switch 会自动打开浏览器并把验证码复制到剪贴板，在浏览器页面粘贴验证码完成授权即可，期间应用内显示 等待授权中...。
• 登录成功后，认证状态 显示已登录账号（邮箱）。支持多账号：可 添加其他账号、设为默认，或在这个供应商上指定使用某个账号；日常管理也可以走 设置 → OAuth 认证中心。
• FAST 模式：可选开关，开启后请求携带 service_tier="priority" 换取更低延迟，但会按更高速率消耗 ChatGPT 配额，默认保持关闭。
• 模型档位已预填好：Sonnet/Opus 对应 gpt-5.6-sol，Haiku 对应 gpt-5.6-luna（后台小任务走它，更快更省额度）。

登录凭据保存在 ~/.cc-switch/codex_oauth_auth.json（不是 ~/.codex/），与 Codex CLI 自己的登录互不影响；token 会在到期前自动刷新。

第二步：开启本地路由并接管 Claude Code Copy Chapter

进入设置里的 路由 页面，展开 本地路由，完成两个开关：

1. 打开 路由总开关，启动本地服务（首次开启会弹出说明确认框）。默认地址是 127.0.0.1:15721。
2. 在 路由启用 中打开 Claude Code。只想让 Claude Code 走路由的话，其余应用保持关闭。

接管后，CC Switch 会把 Claude Code 的 live 配置指向本机路由，认证项只有占位符；方式一的网关 Key 和方式二的 OAuth token 都由本地路由在转发时注入。

注意：live 配置是 Claude Code 进程启动时读取的。首次开启接管（或关闭接管恢复直连）后，如果 Claude Code 正在运行，请重开一个终端会话。之后在路由模式下切换供应商就是热切换，无需再重启。

第三步：切换供应商并验证 Copy Chapter

回到 Claude Code 供应商列表，点击目标供应商的 启用。如果路由没有在运行，CC Switch 会提示「此供应商使用 OpenAI Responses 接口格式，需要路由服务才能正常使用，请先启动路由」——这个提示不会拦截切换，但路由未开时请求必然失败，回到第二步打开即可。

进入 Claude Code 后可以逐级验证：

• 新开会话，用 /model 查看模型菜单：各档显示的是模型映射里的显示名称（方式二默认即 gpt-5.6-sol、gpt-5.6-luna）。界面个别位置仍可能出现 Claude 系的模型字样——那是路由接管使用的内部角色别名，属正常现象，以 /model 菜单和用量看板为准。
• 发一个小问题，观察设置 → 路由页面的「当前 Provider」变成你的供应商、「总请求数」开始增长。
• 用量看板里，这些请求会按上游真实模型显示：gpt-5.6-sol 显示为 GPT-5.6 Sol（手动填不带后缀的 gpt-5.6 也会解析为 Sol 档），gpt-5.6-luna 显示为 GPT-5.6 Luna，可按供应商筛选核对 token 用量。
• 方式二的供应商卡片还会显示订阅额度：5 小时与 7 天窗口的利用率和重置倒计时，数据来自 ChatGPT 账号本身，与官方 Codex 客户端共用同一份额度。

能力边界与已知限制 Copy Chapter

• 提示缓存自动生效：路由会为每个会话注入稳定的 prompt_cache_key，配合 OpenAI 侧的自动前缀缓存，长对话不会每轮全价重发，无需任何配置。
• 思考折算为 reasoning effort：Claude Code 的思考开关与思考等级会被折算成 GPT 的 reasoning.effort（low/medium/high）；GPT 的推理内容以加密形态跨轮完整回放，多轮推理连贯性不受转换影响。方式二同时以无痕模式（store:false）访问，不在 OpenAI 服务端留存会话。
• 工具与多模态完整转换：多轮工具调用、图片与 PDF 输入都被完整转换。
• 上下文按 200K 窗口管理：Claude Code 对路由供应商按默认 200K 窗口做自动压缩。上游实际窗口更大时（如 ChatGPT Codex 服务的 gpt-5.6 为 372K），超出 200K 的部分当前不会被用到——压缩会提前触发，保守但安全。想突破 200K，目前唯一的开关是模型映射里的 1M 复选框（严格声明 1M），仅限方式一且上游真按 1M 及以上服务该模型时使用；方式二的上游上限是 372K、够不到 1M，勾选反而会让长对话在上游真实上限处报错，请维持默认。
• 输出上限：方式二的输出上限由 ChatGPT 服务端控制（Claude Code 请求里的 max_tokens 不会下发）；方式一则原样透传 Claude Code 的 max_tokens，无需配置。
• 内置联网搜索取决于上游支持：路由会把 Claude Code 的托管 WebSearch 工具转换为 Responses API 的托管 web_search 工具，可用于 Codex OAuth 和实现该工具的兼容 Responses 网关。allowed_domains 会保留；在 API Key Responses 路由中，max_uses 会映射为上游的 max_tool_calls 硬限制。Codex OAuth 请求协议会拒绝该字段，因此桥接层采用本地响应侧限制：把上限写入模型指令，在观察到额外搜索调用时终止上游流，并返回 max_uses_exceeded，无论请求是否强制使用托管搜索都同样生效。超限会截断整轮响应，包括后续文本和函数调用；如果还有未完成的内容块，则返回 stream_truncated 错误，避免交付残缺的工具调用。这并非服务端硬配额：代理收到事件前，额外搜索可能已经在上游执行。由于 Responses 没有等价的拒绝列表，带有非空 blocked_domains 的请求也会明确失败。本地执行的 WebFetch 不受影响。
• 用量看板金额是参考值：token 计数准确，但美元金额是按公开 API 价折算的估算——方式二订阅流量按 GPT-5.6 公开价折算，方式一的第三方网关按各自费率计费，两者都可能与真实扣费不符，仅供对比。方式二的额度消耗以供应商卡片上的窗口利用率为准。

常见问题 Copy Chapter

上游返回 401 或 403（方式一）

先确认高级选项里的 认证字段 是默认的 ANTHROPIC_AUTH_TOKEN（默认）——改成 ANTHROPIC_API_KEY 会以 x-api-key 发送，绝大多数 OpenAI 兼容网关不接受。再确认 Key 本身有效、有余额。

请求 gpt-5.6-luna 等新模型报 404 Model not found（方式二）

升级到 CC Switch 3.17.0 及以上。旧版本的客户端身份未对齐官方 Codex 客户端，ChatGPT 服务端会把新模型解析到不存在的引擎。

切换后没生效，或 /model 菜单还是旧名字

模型菜单和路由地址都是 Claude Code 启动时读取的：首次开启接管后必须重开终端会话；供应商之间切换虽然是热切换，但菜单里的显示名称要新会话才刷新。

Claude Code 报「Codex OAuth 认证失败」或卡片显示「会话已过期」（方式二）

登录凭据已失效。回到供应商表单或 设置 → OAuth 认证中心，重新走一遍 使用 ChatGPT 登录 即可；无需运行任何命令行操作。

对话进行到一半就自动压缩了

见「能力边界」：路由供应商按 200K 窗口管理，压缩阈值随之提前，属预期行为。

想恢复官方 Claude 用法

切回官方供应商，或在路由页面关闭 Claude Code 的路由开关——CC Switch 会恢复接管前的 live 配置，官方登录凭据全程不受影响。恢复后同样需要重开终端会话。

FAST 模式要不要开（方式二）

默认关闭即可。只有当你对延迟特别敏感、且愿意接受配额更快消耗时再打开；如果 ChatGPT 服务端拒绝该参数，关掉开关即可恢复。

合规提示 Copy Chapter

方式二把 ChatGPT 订阅额度用在官方 Codex 客户端之外，这并不是灰色玩法：OpenAI Codex 负责人 Thibault Sottiaux（@thsottiaux）就公开演示并鼓励过把 Claude Code（他戏称的「orange crab」）指向 GPT-5.6 Sol 使用——用的正是「本地代理 + 模型别名」，和本文方式二属于同一类做法。作为 Codex 这条产品线的负责人，他主动鼓励大家在竞品客户端里用自家模型，可见用订阅在 Claude Code 里跑 GPT 系模型，是官方乐见并鼓励尝试的用法。

两点实务提醒仍值得留意：一是这部分流量与官方 Codex 客户端合并计入同一份订阅额度，重度使用会更快触顶；二是 CC Switch 认证中心出于稳妥保留了合规提示（「在 Claude Code 中使用您的其他订阅，请注意合规风险。」），是否符合你账号所适用的条款可自行留意。方式一使用第三方网关时，请另行阅读目标网关关于计费、合规与数据留存的条款。

参考链接 Copy Chapter

• CC Switch 用户手册：添加供应商（含 Codex OAuth 反向代理与 API 格式）
• CC Switch 用户手册：代理服务
• CC Switch 用户手册：应用路由
• CC Switch v3.17.0 发布说明
• 反方向攻略：在 Codex 中使用 Claude 模型

Guides Codex Claude Routing Guide En (`docs/guides/codex-claude-routing-guide-en.md`) Copy Section

Using Claude Models in Codex with CC Switch

Applies to CC Switch 3.17.0 and later (the Anthropic Messages upstream was introduced in 3.17.0). This guide is based on the repository documentation and code, and uses a Claude-family relay gateway as the example. Screenshots are generated from the current frontend UI with de-identified sample data to avoid exposing a real API key.

Why local routing is needed Copy Chapter

The newer Codex CLI targets the OpenAI Responses API, while the various Claude-family relay gateways and internal enterprise gateways expose the Anthropic Messages protocol — that is, /v1/messages. These two protocols use completely different request bodies, streaming events, and response structures, so putting such a gateway's endpoint directly into Codex configuration can only result in a request to /responses coming back 404.

This feature targets the scenario where all you have is a /v1/messages endpoint: you have a key for some Claude-family relay gateway and want to run Claude-family models with Codex's interaction style; or your company has banned the Claude Code client for compliance reasons and kept only an approved Claude-family gateway — the model itself is available, and all that's missing is a permitted client, which Codex can now fill.

CC Switch's approach is to keep Codex always talking to the local route and still sending Responses API requests; once the route detects that the active provider is Anthropic-format, it converts the request into Anthropic Messages for the upstream, then converts the response back into the Responses shape it returns to Codex.

The chain has four main steps:

1. When Codex is taken over, the local configuration is written as http://127.0.0.1:15721/v1, and wire_api = "responses" is forcibly kept in place.
2. The provider's anthropic upstream format tells the route that the real upstream speaks the Anthropic Messages protocol.
3. The route rewrites /responses to /v1/messages and converts the Responses request body into an Anthropic request body.
4. After the upstream responds, the route converts the Anthropic JSON or SSE back into the Responses JSON/SSE that Codex understands — reasoning content, tool calls, and images are all within the conversion scope.

Prerequisites Copy Chapter

Prepare these three things first:

• CC Switch installed and able to start (3.17.0 or later).
• Codex CLI installed and run at least once, so the ~/.codex/ directory structure exists.
• An API key that can reach an Anthropic Messages protocol endpoint (/v1/messages) — from some Claude-family relay gateway, or an internal enterprise Claude gateway; follow the gateway's documentation for its endpoint and auth method. Note: some providers restrict their Claude API to Claude Code only, so such a key may error out when used through Codex — if you're unsure, check with your provider first.

The Codex tab currently has no built-in Anthropic preset, so the steps below use the Custom Configuration path — just four or five fields from start to finish.

Step 1: Add a Codex provider Copy Chapter

Open CC Switch, switch to the top-level Codex tab, click the plus button in the upper-right corner to add a provider, keep the default Custom Configuration, then fill in:

• Provider Name: anything you like, e.g. Claude Gateway.
• API Key: your gateway key. The real key is stored only in CC Switch and injected by the local route when forwarding, so it never enters Codex's live config.
• API Request URL: just the gateway's service root, e.g. https://claude-gateway.example.com. It works with or without a trailing /v1 — the route sends requests to /v1/messages automatically; don't assemble /v1/messages yourself (if your gateway documentation gives you a complete messages URL, you can turn on the Full URL toggle next to it and paste it verbatim). The yellow hint below the address bar, "compatible with OpenAI Response format", is generic copy written for the direct Responses scenario; when you choose the Anthropic format, just fill it in as this guide describes.
• Default Model: enter a Claude model id the gateway recognizes, e.g. claude-sonnet-5; follow the model names in the gateway's documentation.

Then expand Advanced Options and change Upstream Format from the default Responses (native) to Anthropic Messages (routing required).

After selecting Anthropic Messages, three supporting fields appear below:

• Auth field: determines which header carries the API key to the upstream; only one of the two is sent — choose per your gateway's documentation.
  • ANTHROPIC_AUTH_TOKEN (Authorization): sends Authorization: Bearer <key>. This is the default, and most Claude-family relay gateways use it.
  • ANTHROPIC_API_KEY (x-api-key): sends x-api-key: <key>. Some gateways that follow Anthropic's native header convention require this. Picking the wrong one usually shows up as 401 / 403.
• Emulate Claude Code client: off by default. Turn it on only when the gateway or its upstream restricts usage to "Claude Code only"; when enabled, it spoofs the User-Agent, anthropic-beta, and x-app headers and injects the Claude Code identity as the first line of the system prompt. Ordinary gateways don't need it; if you're still rejected after enabling it, see "FAQ".
• Max output tokens: the Anthropic protocol's max_tokens is required, and when a Codex request carries no output ceiling the route falls back to a conservative 8192, which may truncate long answers or deep reasoning (showing up as an incomplete reply, stop_reason=max_tokens). If you hit truncation, raise this to the model's real ceiling here — but don't exceed it, or the upstream will 400 outright.

The Model Mapping in the same area is optional: add model ids like claude-opus-4-8, claude-sonnet-5, and claude-haiku-4-5-20251001 (use the names your upstream recognizes) one per row, and CC Switch generates a model catalog so Codex's /model menu can list them; you can also leave it empty, in which case Codex just requests the default model.

After you save the provider, a Needs Routing marker appears on the card — providers like this only work while local routing is running.

Step 2: Enable local routing and take over Codex Copy Chapter

Go to the Routing page in Settings, expand Local Routing, and complete two toggles:

1. Turn on the Routing Master Switch to start the local service (the first time you enable it, an explanatory confirmation dialog appears). The default address is 127.0.0.1:15721.
2. Turn on Codex under Routing Enabled. If you only want Codex to use routing, you can leave Claude and Gemini off.

After takeover, CC Switch points Codex's live config at the local route (base_url = http://127.0.0.1:15721/v1), with only a placeholder in auth.json. The real Claude key stays in the CC Switch provider config and is injected by the local route on forward, using the auth field you selected.

Step 3: Switch providers and restart Codex Copy Chapter

Return to the Codex provider list and click Enable on the Claude provider. If routing isn't running, CC Switch shows "This provider uses Anthropic Messages API format, requires the routing service to work properly. Start routing first." — just go back to Step 2 and turn it on.

After switching, restart the current Codex terminal session: config.toml and the model catalog are read when the Codex process starts, and a running process isn't guaranteed to hot-load them.

Inside Codex you can verify step by step:

• If you configured model mapping, use /model to check whether the Claude models now appear in the menu; without a mapping, Codex just uses the default model.
• Send a small question and watch the "Current Provider" on the Settings → Routing page change from "Waiting for first request..." to your Claude provider, with "Total Requests" starting to climb.
• In the usage dashboard, these requests show their model names faithfully as claude-*, and you can filter by provider to reconcile token usage.

Capabilities and known limitations Copy Chapter

• Prompt caching is automatic: the conversion bridge injects standard 5-minute prompt-cache markers (system prompt, tool definitions, and conversation history) per Anthropic's convention, so long conversations don't resend everything at full price each turn — no configuration needed.
• Reasoning and tools are lossless: extended thinking content round-trips across the bridge intact, and multi-turn tool calls, image inputs, and PDF inputs are all fully converted.
• Supports the [1m] long-context marker: when the default model or a model id in the mapping ends with [1m] (e.g. claude-sonnet-5[1m]), the route strips the marker and automatically adds the corresponding 1M-context beta header, provided the gateway supports that capability.
• Web search is unavailable: in Anthropic upstream mode, Codex's built-in web_search is deliberately disabled — the conversion layer can't translate it for the Anthropic endpoint, and disabling it avoids presenting the model with a tool that's guaranteed to fail.
• Truncation is reported faithfully: when the upstream stops at the output ceiling or the stream is cut off, Codex sees "incomplete" rather than a disguised success, making it easy to notice and raise the max output tokens.

FAQ Copy Chapter

The upstream returns 401 or 403

Nine times out of ten the auth field doesn't match what the gateway wants: switch between ANTHROPIC_AUTH_TOKEN (Authorization) and ANTHROPIC_API_KEY (x-api-key) per your gateway's documentation and try again (most gateways use the default Bearer). Also confirm the key itself is valid and has balance.

Codex reports 404 or cannot find /responses

Usually Codex routing takeover isn't enabled, or you manually wrote the gateway's address directly into Codex — an Anthropic-protocol upstream has no /responses endpoint, so that always 404s. Check whether the current provider's base_url in ~/.codex/config.toml points to http://127.0.0.1:15721/v1.

The upstream returns 404 (routing already enabled)

Check the API Request URL: it should be the gateway's service root, not an address carrying another protocol's path such as /chat/completions. When the gateway path is unusual, use the Full URL toggle to paste the complete messages endpoint directly.

Replies often get cut off mid-way

This is the default 8192 output ceiling showing up. Raise it in Max output tokens under the provider form's Advanced Options (don't exceed the model's/gateway's real ceiling), save, and retry.

/model doesn't show the Claude models

Confirm you've added entries to the model mapping, then restart Codex after saving the provider — the model catalog isn't hot-loaded by a running process. When the default model isn't in the mapping, the menu won't list it, but a direct request still works.

Web search doesn't work

By design; see "Capabilities and known limitations". For tasks that need web search, switch back to a Responses/Chat-format provider.

An error says usage is restricted to Claude Code

Some providers restrict their Claude API to the Claude Code client, so it gets rejected when going through this guide's chain via Codex. Try turning on the Emulate Claude Code client toggle in Advanced Options; if it still errors after that, the restriction is enforced on the provider's side — check with your provider whether your key can be used outside Claude Code. Keep this toggle off for ordinary gateways.

Compliance note Copy Chapter

Before using this in the "company bans the client but keeps only the gateway" scenario, it's worth confirming that doing so complies with your organization's specific policy — whether what's banned is a specific client or a manner of use differs from one place to the next. When using a third-party relay gateway, read the target gateway's terms on billing, compliance, and data retention.

References Copy Chapter

• CC Switch User Manual: Proxy Service
• CC Switch User Manual: App Routing
• CC Switch v3.17.0 Release Notes
• This feature comes from community contribution #5071; thanks @yeeyzy.

Guides Codex Claude Routing Guide Ja (`docs/guides/codex-claude-routing-guide-ja.md`) Copy Section

CC Switch を使って Codex で Claude モデルを利用する

対象バージョン: CC Switch 3.17.0 以降（「Anthropic Messages 上流」は 3.17.0 から導入）。本記事はリポジトリ内のドキュメントとコードをもとに整理し、Claude 系中継ゲートウェイを例に説明します。スクリーンショットは現在のフロントエンド UI から、実際の API Key が漏れないよう匿名化したサンプルデータで生成しています。

ローカルルーティングが必要な理由 Copy Chapter

新しい Codex CLI は OpenAI Responses API を前提にしています。一方で各種 Claude 系中継ゲートウェイや企業内部ゲートウェイが公開しているのは Anthropic Messages プロトコル、つまり /v1/messages です。この 2 つのプロトコルは、リクエストボディ、ストリーミングイベント、レスポンス構造がまったく異なります。この種のゲートウェイのエンドポイントをそのまま Codex 設定に入れても、/responses へのリクエストが 404 になるだけです。

この機能は「手元にあるのが /v1/messages エンドポイントだけ」という場面のためのものです。ある Claude 系中継ゲートウェイの Key を持っていて、Codex の操作感で Claude 系モデルを使いたい。あるいは会社がコンプライアンス方針で Claude Code クライアントを禁止し、承認済みの Claude 系ゲートウェイだけを残している——モデル自体は利用できるのに、許可されたクライアントがないだけです。その空白を Codex で埋められます。

CC Switch では、Codex が常にローカルルートへ接続し、Responses API のままリクエストを送るようにします。ルートは現在のプロバイダーが Anthropic 形式だと判定すると、リクエストを Anthropic Messages に変換して上流へ送り、最後にレスポンスを Responses 形式へ戻して Codex に返します。

この経路は主に 4 つのステップに分かれます：

1. Codex を引き継ぐと、ローカル設定は http://127.0.0.1:15721/v1 に書き換えられ、wire_api = "responses" が強制的に維持されます。
2. プロバイダーの上流フォーマット anthropic が、実際の上流は Anthropic Messages プロトコルだとルートに伝えます。
3. ルートは /responses を /v1/messages に書き換え、Responses のリクエストボディを Anthropic のリクエストボディへ変換します。
4. 上流から返ってきた後、ルートは Anthropic の JSON または SSE を Codex が理解できる Responses JSON/SSE へ変換して返します——推論内容、ツール呼び出し、画像もすべて変換対象です。

事前準備 Copy Chapter

先に次の 3 つを用意してください：

• インストール済みで起動できる CC Switch（3.17.0 以降）。
• インストール済みの Codex CLI。少なくとも 1 回は実行し、~/.codex/ のディレクトリ構造が存在していること。
• Anthropic Messages プロトコルのエンドポイント（/v1/messages）へアクセスできる API Key——ある Claude 系中継ゲートウェイ、または企業内部の Claude ゲートウェイのもの。エンドポイントと認証方式はゲートウェイのドキュメントに従ってください。注意：一部のプロバイダーは Claude API を Claude Code 内でのみ利用できるよう制限しており、この種の Key を Codex で使うとエラーになることがあります。判断がつかない場合は、先にプロバイダーへ問い合わせてください。

Codex タブには現時点で Anthropic の内蔵プリセットがないため、以下では「カスタム設定」の手順で進めます。入力する項目は全体でも 4〜5 個です。

Step 1: Codex プロバイダーを追加する Copy Chapter

CC Switch を開き、上部の Codex タブへ切り替え、右上のプラスボタンからプロバイダーを追加します。デフォルトの カスタム設定 のまま、次の項目を入力します：

• プロバイダー名: 任意です。たとえば Claude Gateway。
• API Key: あなたのゲートウェイの Key。実際の Key は CC Switch 内にのみ保存され、ローカルルートが転送時に注入するため、Codex の live 設定には入りません。
• API エンドポイント: ゲートウェイのルートアドレスを入力すれば十分です。たとえば https://claude-gateway.example.com。/v1 は付けても付けなくても正しく処理され、ルートが自動的に /v1/messages へリクエストを送ります。自分で /v1/messages を組み立てないでください（ゲートウェイのドキュメントが完全な messages URL を指定している場合は、隣の フル URL スイッチをオンにしてそのまま貼り付けても構いません）。アドレス欄の下に表示される「OpenAI Response 互換」という黄色のヒントは Responses 直結向けの汎用文言です。Anthropic フォーマットを選ぶ場合は本記事のとおりに入力してください。
• デフォルトモデル: ゲートウェイが認識する Claude モデル ID を入力します。たとえば claude-sonnet-5。ゲートウェイのドキュメントにあるモデル名に従ってください。

続いて 詳細オプション を展開し、上流フォーマット をデフォルトの Responses（ネイティブ） から Anthropic Messages（ルーティング必須） に変更します。

Anthropic Messages を選ぶと、下に 3 つの関連フィールドが追加で表示されます：

• 認証フィールド: API Key をどのヘッダーで上流へ送るかを決めます。送信されるのはどちらか一方のみで、ゲートウェイのドキュメントに従って選びます。
  • ANTHROPIC_AUTH_TOKEN（Authorization）: Authorization: Bearer <key> を送信します。デフォルト値で、多くの Claude 系中継ゲートウェイがこの方式を使います。
  • ANTHROPIC_API_KEY（x-api-key）: x-api-key: <key> を送信します。Anthropic ネイティブのヘッダー規約を踏襲する一部のゲートウェイはこちらを要求します。選択を誤ると、通常 401 / 403 という形で現れます。
• Claude Code クライアントを模倣: デフォルトはオフです。ゲートウェイ（またはその上流）が「Claude Code からのみ利用可能」と制限している場合にのみオンにします。オンにすると User-Agent・anthropic-beta・x-app ヘッダーを偽装し、システムプロンプトの先頭行に Claude Code のアイデンティティを注入します。通常のゲートウェイでは不要です。オンにしても拒否される場合の対処は「よくある質問」を参照してください。
• 最大出力トークン: Anthropic プロトコルの max_tokens は必須項目です。Codex のリクエストが出力上限を含まない場合、ルートは保守的に 8192 で補います。長い回答や深い思考では切り詰められることがあります（回答が不完全になる、stop_reason=max_tokens になる、といった形で現れます）。切り詰められたら、ここでモデルの実際の上限に合わせて引き上げてください。ただし超えないように——超えると上流が直接 400 を返します。

同じエリアの モデルマッピング は任意です。claude-opus-4-8、claude-sonnet-5、claude-haiku-4-5-20251001 のようなモデル ID（上流が認識する名前に従ってください）を 1 行ずつ追加すると、CC Switch がモデルカタログを生成し、Codex の /model メニューに一覧表示できるようになります。入力しなくても利用でき、その場合 Codex はデフォルトモデルを直接リクエストします。

プロバイダーを保存すると、カードに ルーティングが必要 のマークが表示されます——この種のプロバイダーは、ローカルルーティングが実行中でなければ正しく動作しません。

Step 2: ローカルルーティングを有効にして Codex をルーティングする Copy Chapter

設定の ルーティング ページに入り、ローカルルーティング を展開して、2 つのスイッチを設定します：

1. ルーティング総スイッチ をオンにしてローカルサービスを起動します（初回起動時は説明の確認ダイアログが表示されます）。デフォルトアドレスは 127.0.0.1:15721 です。
2. ルーティング有効 で Codex をオンにします。Codex だけをルーティングしたい場合は、Claude と Gemini はオフのままで構いません。

引き継ぎ後、CC Switch は Codex の live 設定をローカルルートへ向け（base_url = http://127.0.0.1:15721/v1）、auth.json にはプレースホルダーだけが入ります。実際の Claude Key は CC Switch のプロバイダー設定内に残り、ローカルルートが転送時に、あなたが選んだ認証フィールドに従って注入します。

Step 3: プロバイダーを切り替えて Codex を再起動する Copy Chapter

Codex プロバイダー一覧に戻り、Claude プロバイダーの 有効化 をクリックします。ルーティングが実行されていない場合、CC Switch は「このプロバイダーは Anthropic Messages API フォーマットを使用しており、ルーティングサービスが必要です。先にルーティングを起動してください」と表示します——Step 2 に戻ってオンにすれば解決します。

切り替え後は、現在の Codex ターミナルセッションを再起動することをおすすめします。config.toml とモデルカタログは Codex プロセスの起動時に読み込まれるため、実行中のプロセスがホットロードするとは限りません。

Codex に入ったら、段階的に確認できます：

• モデルマッピングを設定している場合は、/model で Claude モデルがメニューに表示されているか確認します。マッピングを設定していない場合、Codex はデフォルトモデルを直接使います。
• 小さな質問を 1 つ送り、設定 → ルーティングページの「現在のプロバイダー」が「最初のリクエスト待ち」からあなたの Claude プロバイダーに変わり、「総リクエスト数」が増え始めるのを確認します。
• 使用量ダッシュボードでは、これらのリクエストのモデル名が claude-* としてそのまま表示され、プロバイダーで絞り込んで token 使用量を照合できます。

機能の範囲と既知の制限 Copy Chapter

• プロンプトキャッシュが自動で有効: 変換ブリッジは Anthropic 標準に従って 5 分のプロンプトキャッシュマーカー（システムプロンプト、ツール定義、対話履歴）を注入します。長い対話でも毎回全額で再送されることはなく、設定は不要です。
• 推論とツールを無損失で往復: extended thinking の内容はブリッジをまたいで往復しても保持され、複数ターンのツール呼び出し、画像、PDF 入力も完全に変換されます。
• [1m] 長コンテキストマーカーに対応: デフォルトモデルやモデルマッピングのモデル ID が [1m] で終わる場合（例：claude-sonnet-5[1m]）、ルートはマーカーを取り除き、対応する 1M コンテキストの beta ヘッダーを自動で補います。ただし、ゲートウェイがその機能に対応していることが前提です。
• Web 検索は利用不可: Anthropic 上流モードでは Codex の内蔵 web_search が意図的に無効化されます——変換層が Anthropic エンドポイントへ翻訳できないためで、必ず失敗するツールをモデルに提示しないための措置です。
• 切り詰めをそのまま報告: 上流が出力上限で止まったりストリームが切断されたりすると、Codex は偽装された成功ではなく「未完了」を受け取ります。これにより気づきやすくなり、最大出力トークンを引き上げる判断ができます。

よくある質問 Copy Chapter

上流が 401 または 403 を返す

ほとんどの場合、認証フィールドがゲートウェイの要求と一致していません。ANTHROPIC_AUTH_TOKEN（Authorization） と ANTHROPIC_API_KEY（x-api-key） を、ゲートウェイのドキュメントに従って切り替えて再試行してください（多くのゲートウェイはデフォルトの Bearer です）。あわせて、Key 自体が有効で残高があることも確認してください。

Codex が 404 を返す、または /responses が見つからない

多くの場合、Codex のルーティング引き継ぎが有効になっていないか、ゲートウェイのエンドポイントを手動で Codex に直接書いています——Anthropic プロトコルの上流には /responses エンドポイントが存在しないため、必ず 404 になります。~/.codex/config.toml の現在の provider の base_url が http://127.0.0.1:15721/v1 を指しているか確認してください。

上流が 404 を返す（ルーティングは有効）

API エンドポイントを確認してください。ゲートウェイのルートアドレスであるべきで、/chat/completions のような別プロトコルのパスが付いたアドレスではいけません。ゲートウェイのパスが特殊な場合は、フル URL スイッチを使って完全な messages エンドポイントをそのまま貼り付けてください。

回答が途中で切り詰められることが多い

これはデフォルトの 8192 出力上限の現れです。プロバイダーフォームの詳細オプションにある 最大出力トークン で引き上げ（モデル / ゲートウェイの実際の上限を超えないように）、保存してから再試行してください。

/model に Claude モデルが表示されない

モデルマッピングにエントリが追加されていることを確認し、プロバイダーを保存してから Codex を再起動してください——モデルカタログは実行中のプロセスにはホットロードされません。デフォルトモデルがマッピングに含まれていない場合、メニューには表示されませんが、直接リクエストは有効です。

Web 検索が使えない

仕様どおりです。「機能の範囲と既知の制限」を参照してください。Web 検索が必要なタスクは、Responses / Chat フォーマットのプロバイダーへ切り替えることをおすすめします。

Claude Code でしか使えないというエラーが出る

一部のプロバイダーは、その Claude API を Claude Code クライアント内でのみ利用できるよう制限しており、本ガイドの経路で Codex から使うと拒否されます。詳細オプションの Claude Code クライアントを模倣 スイッチをオンにして試すことはできますが、それでもエラーになる場合、制限はプロバイダーのサーバー側にあります。その Key を Claude Code 以外で使えるかどうか、プロバイダーへ問い合わせて確認してください。通常のゲートウェイでは、このスイッチはオフのままにしてください。

コンプライアンスに関する注意 Copy Chapter

「会社がクライアントを禁止し、ゲートウェイだけを残している」という場面で使う前に、この使い方が所属組織の具体的な方針に沿っているかを確認することをおすすめします——禁止されているのが特定のクライアントなのか、それともある種の利用方法なのかは、組織によって解釈が異なります。サードパーティ中継ゲートウェイを使う場合は、対象ゲートウェイの課金・コンプライアンス・データ保持に関する規約を必ずお読みください。

参考リンク Copy Chapter

• CC Switch ユーザーマニュアル: プロキシサービス
• CC Switch ユーザーマニュアル: アプリケーションルーティング
• CC Switch v3.17.0 リリースノート
• この機能はコミュニティからの貢献 #5071 によるものです。@yeeyzy に感謝します。

Guides Codex Claude Routing Guide Zh (`docs/guides/codex-claude-routing-guide-zh.md`) Copy Section

通过 CC Switch 在 Codex 中使用 Claude 模型

适用版本：CC Switch 3.17.0 及以上（「Anthropic Messages 上游」自 3.17.0 引入）。本文根据仓库内文档与代码整理，以 Claude 系中转网关为例演示。截图来自当前前端界面，使用去敏示例数据生成，避免泄露真实 API Key。

为什么需要本地路由 Copy Chapter

新版 Codex CLI 面向的是 OpenAI Responses API，而各类 Claude 系中转网关、企业内部网关暴露的是 Anthropic Messages 协议，也就是 /v1/messages。这两种协议的请求体、流式事件和返回结构完全不同，把这类网关的接口地址直接填进 Codex 配置里，结果只能是请求 /responses 返回 404。

这个功能面向的就是「手里只有 /v1/messages 端点」的场景：你有某个 Claude 系中转网关的 Key，想用 Codex 的交互习惯跑 Claude 系列模型；或者公司出于合规策略禁用了 Claude Code 客户端、只保留了经批准的 Claude 系网关——模型本身可用，缺的只是一个被允许的客户端，现在 Codex 可以补上这个位置。

CC Switch 的做法是让 Codex 始终连本机路由，仍以 Responses API 发送请求；路由识别当前供应商是 Anthropic 格式后，把请求转换成 Anthropic Messages 发给上游，再把响应转换回 Responses 形态返回给 Codex。

这条链路主要分成四步：

1. Codex 接管时，本地配置会被写成 http://127.0.0.1:15721/v1，并强制保持 wire_api = "responses"。
2. 供应商的上游格式 anthropic 会告诉路由：真实上游说的是 Anthropic Messages 协议。
3. 路由把 /responses 改写到 /v1/messages，并把 Responses 请求体转换成 Anthropic 请求体。
4. 上游返回后，路由再把 Anthropic 的 JSON 或 SSE 转回 Codex 能理解的 Responses JSON/SSE——推理内容、工具调用、图片都在转换范围内。

准备工作 Copy Chapter

你需要先准备好三样东西：

• 已安装并能启动的 CC Switch（3.17.0 及以上）。
• 已安装 Codex CLI，并至少运行过一次，让 ~/.codex/ 目录结构存在。
• 一个能访问 Anthropic Messages 协议端点（/v1/messages）的 API Key——来自某个 Claude 系中转网关，或企业内部的 Claude 网关；端点地址和认证方式以网关文档为准。注意：部分供应商会限制其 Claude API 只能在 Claude Code 中使用，这类 Key 走 Codex 可能会报错，拿不准就先咨询供应商。

Codex 页签目前没有 Anthropic 内置预设，下面走「自定义配置」路径，全程也就四五个字段。

第一步：添加 Codex 供应商 Copy Chapter

打开 CC Switch，切到顶部的 Codex 标签，点击右上角的加号添加供应商，保持默认的 自定义配置，然后填写：

• 供应商名称：随意，例如 Claude Gateway。
• API Key：你的网关 Key。真实 Key 只保存在 CC Switch 里，由本地路由转发时注入，不会进入 Codex 的 live 配置。
• API 请求地址：填网关服务根地址即可，例如 https://claude-gateway.example.com。带不带 /v1 都能被正确处理，路由会自动把请求打到 /v1/messages；不要自己拼 /v1/messages（如果网关文档给的就是完整 messages URL，打开旁边的 完整 URL 开关原样粘贴也可以）。地址栏下方那句「兼容 OpenAI Response 格式」的黄色提示是为 Responses 直连场景写的通用文案，选 Anthropic 格式时按本文填写即可。
• 默认模型：填网关认识的 Claude 模型 id，例如 claude-sonnet-5，以网关文档给出的模型名为准。

然后展开 高级选项，把 上游格式 从默认的 Responses（原生） 改成 Anthropic Messages（需开启路由）。

选中 Anthropic Messages 后，下方会多出三个配套字段：

• 认证字段：决定 API Key 以哪个请求头发给上游，两者只发其一，按网关文档选择。
  • ANTHROPIC_AUTH_TOKEN（Authorization）：发 Authorization: Bearer <key>，是默认值，多数 Claude 系中转网关用这种。
  • ANTHROPIC_API_KEY（x-api-key）：发 x-api-key: <key>，部分沿用 Anthropic 原生请求头约定的网关要求这种。选错通常表现为 401 / 403。
• 模拟 Claude Code 客户端：默认关闭。仅当网关或其上游限制「只能通过 Claude Code 使用」时才打开，开启后会伪装 User-Agent、anthropic-beta、x-app 请求头，并在系统提示首行注入 Claude Code 身份。普通网关不需要开；开启后仍被拒的处理见「常见问题」。
• 最大输出 tokens：Anthropic 协议的 max_tokens 是必填项，而 Codex 请求未携带输出上限时，路由按保守的 8192 兜底，长回答或深度思考可能被截断（表现为回复不完整、stop_reason=max_tokens）。遇到截断就在这里按模型真实上限调高，但不要超过——超了上游会直接 400。

同区的 模型映射 是可选项：把 claude-opus-4-8、claude-sonnet-5、claude-haiku-4-5-20251001 这类模型 id（以你上游认识的名字为准）逐行加进去，CC Switch 会生成模型目录让 Codex 的 /model 菜单能列出它们；不填也能用，Codex 会直接请求默认模型。

保存供应商后，卡片上会出现 需要路由 标记——这类供应商必须在本地路由运行时才能正常工作。

第二步：开启本地路由并接管 Codex Copy Chapter

进入设置里的 路由 页面，展开 本地路由，完成两个开关：

1. 打开 路由总开关，启动本地服务（首次开启会弹出一个说明确认框）。默认地址是 127.0.0.1:15721。
2. 在 路由启用 中打开 Codex。如果只想让 Codex 走路由，可以保持 Claude、Gemini 关闭。

接管后，CC Switch 会把 Codex 的 live 配置指向本机路由（base_url = http://127.0.0.1:15721/v1），auth.json 里只有占位符。真实 Claude Key 仍保存在 CC Switch 的供应商配置里，由本地路由在转发时按你选的认证字段注入。

第三步：切换供应商并重启 Codex Copy Chapter

回到 Codex 供应商列表，点击 Claude 供应商的 启用。如果路由没有在运行，CC Switch 会提示「此供应商使用 Anthropic Messages 接口格式，需要路由服务才能正常使用，请先启动路由」——回到第二步打开即可。

切换后建议重启当前 Codex 终端会话：config.toml 和模型目录是 Codex 进程启动时读取的，运行中的进程不保证热加载。

进入 Codex 后可以逐级验证：

• 配置了模型映射的话，用 /model 查看 Claude 模型是否已出现在菜单里；没配映射时 Codex 直接用默认模型。
• 发一个小问题，观察设置 → 路由页面的「当前 Provider」从「等待首次请求」变成你的 Claude 供应商、「总请求数」开始增长。
• 用量看板里，这些请求的模型名会如实显示为 claude-*，可按供应商筛选核对 token 用量。

能力边界与已知限制 Copy Chapter

• 提示缓存自动生效：转换桥会按 Anthropic 标准注入 5 分钟提示缓存标记（系统提示、工具定义与对话历史），长对话不会每轮全价重发，无需任何配置。
• 推理与工具无损：extended thinking 内容跨桥往返保留，多轮工具调用、图片与 PDF 输入都被完整转换。
• 支持 [1m] 长上下文标记：默认模型或模型映射里的模型 id 以 [1m] 结尾（如 claude-sonnet-5[1m]）时，路由会剥掉标记并自动补发对应的 1M 上下文 beta 头，前提是网关支持该能力。
• 联网搜索不可用：Anthropic 上游模式下 Codex 的内置 web_search 会被主动禁用——转换层无法把它翻译给 Anthropic 端点，禁用是为了不给模型呈现一个必然失败的工具。
• 截断如实上报：上游停在输出上限或流被掐断时，Codex 会看到「未完成」而不是被伪装的成功，方便你察觉并调高最大输出 tokens。

常见问题 Copy Chapter

上游返回 401 或 403

十有八九是认证字段与网关要求不符：在 ANTHROPIC_AUTH_TOKEN（Authorization） 与 ANTHROPIC_API_KEY（x-api-key） 之间按网关文档换一个再试（多数网关用默认的 Bearer）。另外确认 Key 本身有效、有余额。

Codex 报 404 或找不到 /responses

通常是没有开启 Codex 路由接管，或者你手动把网关的地址直接写给了 Codex——Anthropic 协议的上游没有 /responses 端点，这样一定 404。检查 ~/.codex/config.toml 里当前 provider 的 base_url 是否指向 http://127.0.0.1:15721/v1。

上游返回 404（路由已开启）

检查 API 请求地址：应该是网关的服务根地址，而不是带 /chat/completions 之类其它协议路径的地址。网关路径特殊时，用 完整 URL 开关直接粘贴完整的 messages 端点。

回复经常中途截断

这是默认 8192 输出上限的表现。在供应商表单高级选项的 最大输出 tokens 里调高（不要超过模型/网关真实上限），保存后重试。

/model 看不到 Claude 模型

确认模型映射里已添加条目，保存供应商后重启 Codex——模型目录不会被运行中的进程热加载。默认模型不在映射里时菜单不会列出它，但直接请求仍然有效。

联网搜索用不了

设计如此，见「能力边界」。需要联网搜索的任务建议切回 Responses/Chat 格式的供应商。

报错提示只能在 Claude Code 中使用

部分供应商会限制其 Claude API 只能在 Claude Code 客户端中使用，经 Codex 走本攻略的链路时会被拒绝。可以尝试打开高级选项里的 模拟 Claude Code 客户端 开关；若开启后仍然报错，说明限制在供应商服务端，请咨询供应商确认你的 Key 能否在 Claude Code 之外使用。普通网关请保持该开关关闭。

合规提示 Copy Chapter

在「公司禁客户端、只留网关」的场景下使用前，建议确认这样做符合你所在组织的具体政策——被禁的是特定客户端还是某种使用方式，各家口径不同。使用第三方中转网关时，请阅读目标网关关于计费、合规与数据留存的条款。

参考链接 Copy Chapter

• CC Switch 用户手册：代理服务
• CC Switch 用户手册：应用路由
• CC Switch v3.17.0 发布说明
• 功能来自社区贡献 #5071，感谢 @yeeyzy

Guides Codex Deepseek Routing Guide En (`docs/guides/codex-deepseek-routing-guide-en.md`) Copy Section

Using Chat-Format APIs in Codex: Local Routing Guide and DeepSeek Migration Notes

Applies to CC Switch 3.20.4 and later. This guide is based on the repository documentation and code. Screenshots are generated with de-identified sample data to avoid exposing a real API key or account balance.

Most DeepSeek users no longer need this guide: since 3.19.1 the DeepSeek preset connects directly over native Responses, and deepseek-v4-pro can now connect directly too. This guide is now mainly for two groups of readers: providers that are still Chat-format (such as SiliconFlow and ModelScope), and older DeepSeek cards saved before 3.19.1 that still go through Chat. Read the next section first to find out which case you are in.

First, check whether you still need this guide Copy Chapter

There is exactly one way to tell: look for the Needs Routing badge on the Codex provider card.

• Has the Needs Routing badge → this provider is Chat-format, and the whole guide applies.
• No badge → it already connects directly over native Responses, so the routing steps here are pointless for it. Just use it.
• Has the No Routing Support badge → this is an official provider, and CC Switch blocks it from going through local routing (see the FAQ at the end).

The badge is driven by the API format recorded when the provider was saved, so upgrading CC Switch does not change how an existing provider behaves. For DeepSeek specifically, there are three cases:

It is not just DeepSeek: the Codex presets for Kimi, Zhipu GLM, MiniMax, and 千问AI平台 have since moved to native direct connections as well. The presets that are still Chat-format and need this guide are mainly SiliconFlow, ModelScope, the Tencent Token Plan series, Baidu Qianfan Coding Plan / Token Plan, StepFun, and others; the steps below apply to them in full.

Why local routing is needed Copy Chapter

The newer Codex CLI targets the OpenAI Responses API, while many providers expose the OpenAI Chat Completions shape, usually /chat/completions. These two protocols use different request bodies, streaming events, and response structures. If you put a Chat endpoint directly into Codex configuration, common results include an incorrect model list, 404/400 requests, or streaming responses that Codex cannot parse correctly.

CC Switch solves this by making Codex always talk to a local route and continue sending Responses API requests. The route detects whether the active provider is Chat-format, rewrites the request into Chat Completions for the upstream provider, and finally converts the Chat response back into the Responses shape that Codex understands.

The chain has four main steps:

1. When Codex routing is enabled, the local configuration is written as http://127.0.0.1:15721/v1, while wire_api = "responses" is kept in place.
2. The provider's meta.apiFormat = "openai_chat" tells the route that the real upstream is Chat Completions.
3. The route rewrites /responses or /v1/responses to /chat/completions, and converts the Responses request body into a Chat request body.
4. After the upstream responds, the route converts the Chat JSON or SSE stream back into Responses JSON/SSE.

For a provider that is natively Responses — such as the current DeepSeek preset — steps 2 through 4 never happen: the request goes straight to the upstream with no format rewriting at all.

Prerequisites Copy Chapter

Prepare these three things first:

• CC Switch installed and able to start.
• Codex CLI installed and run at least once, so the ~/.codex/config.toml directory structure exists.
• An API key for the provider you want to use.

OpenAI-compatible base URLs vary from provider to provider: a /v1 suffix is common (SiliconFlow, for instance, uses https://api.siliconflow.cn/v1), some use a longer path (Baidu Qianfan Coding Plan uses https://qianfan.baidubce.com/v2/coding), and the Chat API path is /chat/completions. CC Switch's presets are already configured from each provider's documentation, so prefer a preset and do not manually assemble the endpoint path.

Step 1: Add a Codex provider Copy Chapter

Open CC Switch, switch to the top-level Codex tab, and click the plus button in the upper-right corner to add a provider.

Using a preset (recommended): select the provider in the preset list, enter your API key, and save. The preset already carries the request base URL, default model, and model menu, and sets the upstream format for you; once a Chat-format preset is saved, the Needs Routing badge appears on its card. Thinking/reasoning parameters are preconfigured by the preset — you do not need to fill them in.

Using a custom configuration: enter the API key and base URL from the provider's documentation, then expand Advanced Options at the bottom of the form and set Upstream Format to Chat Completions (routing required). The dropdown offers three options:

• Responses (native) — the upstream natively supports the Responses API; connects directly with no conversion and no routing.
• Chat Completions (routing required) — the case this guide covers.
• Anthropic Messages (routing required) — the upstream only offers the native Anthropic protocol, which the route converts as well.

Only Responses (native) works without routing takeover; the other two require it. For custom providers, CC Switch infers the thinking parameters from the provider name and address; you only need to expand Reasoning Capability and override them manually when that inference is wrong.

Converting an existing DeepSeek provider: change Upstream Format to Responses (native) — there is no need to delete and recreate it. The next time you switch to it, CC Switch recognises the deepseek.com address and applies DeepSeek's official model catalog, so freeform apply_patch, the GPT-5 harness, the low/high/max reasoning levels, and web_search all take effect as usual.

The one small difference is the context window: a provider's own saved model rows take priority, so the 1000000 stored before 3.19.1 overrides the officially declared 1048576, costing you a little over 40k tokens. If that bothers you, open Advanced Options → Model Mapping and change that row's Context Window to 1048576, or simply create a fresh provider from the preset.

One more thing: the official model catalog used by the direct connection requires Codex CLI 0.144.0 or newer (the freeform apply_patch registration it carries needs that release), and CC Switch does not verify this for you. The generated catalog file also grows to roughly 75 KB, because it contains the full GPT-5 harness text.

Step 2: Enable local routing and route Codex Copy Chapter

Go to the Routing page in Settings, expand Local Routing, and complete two toggles:

1. Turn on the Routing Master Switch to start the local service. The default address is 127.0.0.1:15721.
2. Turn on Codex under Routing Enabled. If you only want Codex to use local routing, you can leave Claude and Gemini off.

After routing is enabled, CC Switch points Codex's live configuration to the local route and manages authentication with a placeholder. The real API key stays in the CC Switch provider configuration and is injected by the local route while forwarding requests, so you do not need to expose the key in Codex's live configuration.

Step 3: Switch providers and restart Codex Copy Chapter

Return to the Codex provider list and click Enable on the provider you want. If it carries the Needs Routing marker while routing is not running, CC Switch shows a prompt saying the routing service is required.

After switching, restart the current Codex terminal session. This is recommended because:

• The Codex process may already have read the old config.toml.
• After model_catalog_json is generated, the /model menu usually needs a fresh process before it refreshes.

Inside Codex, use /model to check whether the current model comes from the matching preset. Then send a small test prompt and confirm that the request count increases in the routing panel, or that a Codex request appears in usage/request logs.

Usage attribution changes once you connect directly Copy Chapter

This is worth calling out on its own: once a provider connects directly, its requests no longer pass through the local route, so the per-request proxy usage accounting cannot see them.

The usage itself is not lost — Codex session-log import still records it — but that path carries no provider identity: all Codex usage that did not go through the local proxy is grouped under a single entry named Codex (Session). To tell them apart, look at the model: every usage row keeps its own model id, and the usage panel's Model Stats table lists them per model, with separate cost and token figures.

If you genuinely need to reconcile by provider — comparing the same model across several aggregators, for instance — keep Upstream Format on Chat and leave routing takeover enabled.

FAQ Copy Chapter

Codex reports 404 or cannot find /responses

Usually Codex routing is not enabled, or the upstream Chat base URL was written directly into Codex manually. Check whether ~/.codex/config.toml points to http://127.0.0.1:15721/v1.

The upstream reports 404

If you are using a built-in preset, first confirm that the active provider really comes from the preset and that Codex routing is enabled. Only custom providers require extra base URL checks: it should be the service endpoint given in the provider's documentation, not the full endpoint path with /chat/completions.

/model does not show the provider's models

Restart Codex after saving the provider. CC Switch generates cc-switch-model-catalog.json and writes its path to model_catalog_json, but a running Codex process may not hot-load the model catalog.
The Codex app currently does not support multi-model selection, so it uses the first configured model by default.
If the command-line /model menu works but the Codex desktop app model picker still cannot see custom models, that is the upstream Codex desktop app's own model-gating behavior. See Can't See Custom Models in the Codex Desktop App? (FAQ).

Routing is enabled, but requests still go to the wrong provider

Confirm that all three states match: the current provider under the Codex tab is the right one; the local routing service is running; and the Codex toggle is enabled under Routing Enabled.

Can I use an official OpenAI Codex account through local routing?

Not recommended. CC Switch blocks switching to official providers while local routing takeover is enabled, because accessing official APIs through a proxy may create account risk. Routing is mainly intended for third-party, aggregator, or protocol-conversion scenarios.

References Copy Chapter

• CC Switch User Manual: Add Provider
• CC Switch User Manual: Proxy Service
• CC Switch User Manual: App Routing
• DeepSeek API Docs: Integrate with Codex (official Codex integration notes, including wire_api = "responses" and model coverage)
• DeepSeek API Docs: Using the Responses API
• DeepSeek API Docs: Your First API Call
• DeepSeek API Docs: Create Chat Completion
• DeepSeek API Docs: Multi-round Conversation

Guides Codex Deepseek Routing Guide Ja (`docs/guides/codex-deepseek-routing-guide-ja.md`) Copy Section

Codex で Chat 形式 API を使う: ローカルルーティングガイドと DeepSeek 移行の説明

対象バージョン: CC Switch 3.20.4 以降。本記事はリポジトリ内のドキュメントとコードをもとに整理しています。スクリーンショットは実際の API Key やアカウント残高が漏れないよう匿名化したサンプルデータで生成しています。

DeepSeek ユーザーの多くは、もう本記事を必要としません: 3.19.1 から DeepSeek プリセットはネイティブ Responses による直結に変わり、deepseek-v4-pro も直結できるようになりました。本記事は現在、主に 2 種類の読者に向けたものです。Chat 形式のままのプロバイダー（SiliconFlow、ModelScope など）を使う人と、3.19.1 より前に保存され Chat のままになっている DeepSeek の旧カードを使う人です。まず次のセクションで、自分がどのケースに当てはまるかを確認してください。

まず、このガイドが今も必要か確認する Copy Chapter

判別方法は 1 つだけです。Codex プロバイダーカードに ルーティングが必要 バッジが付いているかを見てください。

• ルーティングが必要 バッジあり → このプロバイダーは Chat 形式で、本記事がそのまま当てはまります。
• バッジなし → すでにネイティブ Responses で直結しているため、本記事のルーティング手順は不要です。そのまま使えます。
• ルーティング非対応 バッジあり → 公式プロバイダーであり、CC Switch はローカルルーティング経由での使用をブロックします（末尾のよくある質問を参照）。

このバッジはプロバイダー保存時に記録された API 形式で決まるため、CC Switch をアップグレードしても既存プロバイダーの挙動は変わりません。DeepSeek に関しては、次の 3 つのケースがあります。

DeepSeek だけでなく、Kimi、Zhipu GLM、MiniMax、千问AI平台 の Codex プリセットも順次ネイティブ直結に変わりました。現在も Chat 形式のままで本記事が必要なプリセットは、主に SiliconFlow、ModelScope、Tencent Token Plan シリーズ、Baidu Qianfan Coding Plan / Token Plan、StepFun などで、以下の手順はそれらに完全に当てはまります。

ローカルルーティングが必要な理由 Copy Chapter

新しい Codex CLI は OpenAI Responses API を前提にしています。一方で多くのプロバイダーが実際に公開しているのは OpenAI Chat Completions 形式、つまり /chat/completions です。この 2 つのプロトコルは、リクエストボディ、ストリーミングイベント、レスポンス構造が異なります。Chat エンドポイントをそのまま Codex 設定に入れると、モデル一覧が合わない、リクエストが 404/400 になる、ストリーミングレスポンスを Codex が正しく解析できない、といった問題が起きがちです。

CC Switch では、Codex が常にローカルルートへ接続し、Responses API のままリクエストを送るようにします。ルート内部で現在のプロバイダーが Chat 形式かどうかを判定し、必要ならリクエストを Chat Completions に書き換えて上流へ送り、最後に Chat レスポンスを Codex が理解できる Responses 形式へ戻します。

この経路は主に 4 つのステップに分かれます：

1. Codex ルーティングを有効にすると、ローカル設定は http://127.0.0.1:15721/v1 に書き換えられ、wire_api = "responses" は維持されます。
2. Provider の meta.apiFormat = "openai_chat" が、実際の上流は Chat Completions だとルートに伝えます。
3. ルートは /responses または /v1/responses を /chat/completions に書き換え、Responses のリクエストボディを Chat のリクエストボディへ変換します。
4. 上流から返ってきた後、ルートは Chat の JSON または SSE ストリームを Responses JSON/SSE へ変換して返します。

上流がもともとネイティブ Responses のプロバイダー（現在の DeepSeek プリセットなど）では、ステップ 2〜4 は発生しません。リクエストはそのまま上流へ送られ、形式の書き換えは一切行われません。

事前準備 Copy Chapter

先に次の 3 つを用意してください：

• インストール済みで起動できる CC Switch。
• インストール済みの Codex CLI。少なくとも 1 回は実行し、~/.codex/config.toml のディレクトリ構造が存在していること。
• 対象プロバイダーの API Key。

OpenAI 互換 base URL の書き方は各社でまちまちです。よくあるのは /v1 付きのもの（たとえば SiliconFlow の https://api.siliconflow.cn/v1）で、より長いパスのものもあります（たとえば Baidu Qianfan Coding Plan の https://qianfan.baidubce.com/v2/coding）。Chat API のパスは /chat/completions です。CC Switch のプリセットには各社のドキュメントに従った設定がすでに入っているため、まずはプリセットを使い、エンドポイントパスを手で組み立てる必要はありません。

Step 1: Codex プロバイダーを追加する Copy Chapter

CC Switch を開き、上部の Codex タブへ切り替え、右上のプラスボタンからプロバイダーを追加します。

プリセットを使う（推奨）: プリセット一覧から対象プロバイダーを選び、API Key を入力して保存するだけです。プリセットにはリクエスト先、デフォルトモデル、モデルメニューがすでに含まれ、上流フォーマットも自動的に設定されます。Chat 形式のプリセットは保存するとカードに ルーティングが必要 バッジが表示されます。thinking / reasoning パラメータもプリセットで設定済みのため、手動入力は不要です。

カスタム設定を使う: 相手側のドキュメントに従って API Key と base URL を入力し、フォーム下部の 詳細オプション を展開して、上流フォーマット を Chat Completions（ルーティング必須） に設定します。このドロップダウンには 3 つの選択肢があります：

• Responses（ネイティブ）——上流が Responses API をネイティブにサポートしている場合。変換なしで直結でき、ルーティングは不要です。
• Chat Completions（ルーティング必須）——本記事が扱うケースです。
• Anthropic Messages（ルーティング必須）——上流がネイティブ Anthropic プロトコルのみを提供している場合。こちらもルーティングが変換します。

ルーティング接管が不要なのは Responses（ネイティブ） だけで、残りの 2 つは必要です。カスタムプロバイダーの thinking パラメータは CC Switch が名前とアドレスから自動推論するため、推論が正しくないときにだけ 思考能力 を展開して手動で上書きしてください。

既存の DeepSeek プロバイダーを移行する場合: 上流フォーマット を Responses（ネイティブ） に変更するだけでよく、削除して作り直す必要はありません。次回そのプロバイダーへ切り替えたとき、CC Switch が deepseek.com のアドレスを認識して DeepSeek 公式のモデルカタログを適用するため、freeform apply_patch、GPT-5 harness、low/high/max の思考レベル、web_search はいずれも通常どおり有効になります。

唯一わずかに異なるのはコンテキストウィンドウです。プロバイダー自身が保存したモデル行のほうが優先されるため、3.19.1 より前に保存された 1000000 が公式宣言の 1048576 を上書きし、4 万トークン強が失われます。気になる場合は 詳細オプション → モデルマッピング でその行の コンテキストウィンドウ を 1048576 に変更するか、いっそプリセットから新規作成してください。

なお、直結で使われる公式モデルカタログは Codex CLI 0.144.0 以降を必要とします（カタログに含まれる freeform apply_patch の登録がこのバージョンを要求します）。CC Switch はこれを検証しません。また、生成されるカタログファイルは GPT-5 harness の全文を含むため 75 KB 程度まで大きくなります。

Step 2: ローカルルーティングを有効にして Codex をルーティングする Copy Chapter

設定の ルーティング ページに入り、ローカルルーティング を展開して、次の 2 つのスイッチを設定します：

1. ルーティング総スイッチ をオンにしてローカルサービスを起動します。デフォルトアドレスは 127.0.0.1:15721 です。
2. ルーティング有効 で Codex をオンにします。Codex だけをルーティングしたい場合は、Claude と Gemini はオフのままで構いません。

ルーティングを有効にすると、CC Switch は Codex の live 設定をローカルルートへ向け、認証はプレースホルダーで管理します。実際の API Key は CC Switch の Provider 設定内に残り、ローカルルートが転送時に注入します。そのため、Codex の live 設定に Key を露出させる必要はありません。

Step 3: プロバイダーを切り替えて Codex を再起動する Copy Chapter

Codex プロバイダー一覧に戻り、対象プロバイダーの 有効化 をクリックします。ルーティングが必要 の表示があるのにルーティングが起動していない場合、CC Switch は「ルーティングサービスが必要」という趣旨のメッセージを表示します。

切り替え後は、現在の Codex ターミナルセッションを再起動することをおすすめします。理由は次のとおりです：

• Codex プロセスがすでに古い config.toml を読み込んでいる可能性があります。
• model_catalog_json の生成後、/model メニューの更新には通常、新しいプロセスが必要です。

Codex に入ったら、/model で現在のモデルが該当プリセット由来かどうかを確認します。その後、小さな質問を 1 つ送って、ルーティングパネルのリクエスト数が増えるか、usage / リクエストログに Codex リクエストが出るかを確認します。

直結に切り替えると、使用量の帰属が変わる Copy Chapter

これは単独で触れておく価値があります。プロバイダーが直結に変わると、そのリクエストはローカルルートを通らなくなるため、リクエスト単位で計上するプロキシ使用量統計からは見えなくなります。

使用量そのものが失われるわけではありません——Codex のセッションログ取り込みは通常どおり記録します——ただしこの経路はプロバイダーの識別情報を持ちません。ローカルプロキシを通らなかった Codex の使用量は、すべて Codex (Session) という 1 つの項目にまとめられます。見分けるにはモデルを見てください: 各使用量レコードはそれぞれのモデル ID を保持しており、使用量パネルの モデル統計 がモデルごとに行を分けて表示するため、費用もトークンも別々に確認できます。

プロバイダー単位で突き合わせる必要が本当にある場合（複数の集約サービスで同じモデルを比較する場合など）は、上流フォーマット を Chat のままにして、ルーティング接管を有効にしておいてください。

よくある質問 Copy Chapter

Codex が 404 を返す、または /responses が見つからない

多くの場合、Codex ルーティングが有効になっていないか、上流 Chat base URL を手動で Codex に直接書いています。~/.codex/config.toml が http://127.0.0.1:15721/v1 を指しているか確認してください。

上流が 404 を返す

内蔵プリセットを使っている場合は、まず現在のプロバイダーが本当にプリセット由来であること、そして Codex ルーティングが有効であることを確認してください。カスタムプロバイダーを使っている場合だけ、base URL を追加で確認します。base URL は相手側のドキュメントが示すサービスエンドポイントであり、/chat/completions 付きの完全なエンドポイントパスではありません。

/model にプロバイダーのモデルが表示されない

プロバイダーを保存した後、Codex を再起動してください。CC Switch は cc-switch-model-catalog.json を生成し、そのパスを model_catalog_json に書き込みますが、実行中の Codex プロセスがモデルカタログをホットロードするとは限りません。
現在の Codex app は複数モデル選択に対応していないため、設定内の最初のモデルをデフォルトで使用します。
コマンドラインの /model は正常なのに Codex デスクトップアプリのモデルセレクタでカスタムモデルが見えない場合、それは Codex デスクトップアプリ上流自身のモデルゲーティング挙動です。詳しくは Codex デスクトップアプリでカスタムモデルが見えない？（よくある質問） を参照してください。

ルーティングを有効にしたのに、リクエストが別のプロバイダーへ行く

次の 3 つの状態が一致しているか確認してください：Codex タブの現在のプロバイダーが正しいこと、ローカルルーティングサービスが実行中であること、ルーティング有効 で Codex スイッチがオンであること。

公式 OpenAI Codex アカウントをローカルルーティング経由で使えますか

おすすめしません。CC Switch はローカルルーティング有効中、公式プロバイダーへの切り替えをブロックします。プロキシ経由で公式 API にアクセスすると、アカウントリスクが発生する可能性があるためです。ルーティングは主にサードパーティ、集約サービス、またはプロトコル変換のための機能です。

参考リンク Copy Chapter

• CC Switch ユーザーマニュアル: プロバイダーの追加
• CC Switch ユーザーマニュアル: プロキシサービス
• CC Switch ユーザーマニュアル: アプリケーションルーティング
• DeepSeek API Docs: Integrate with Codex（公式 Codex 連携の説明。wire_api = "responses" と対応モデルの範囲を含む）
• DeepSeek API Docs: Using the Responses API
• DeepSeek API Docs: Your First API Call
• DeepSeek API Docs: Create Chat Completion
• DeepSeek API Docs: Multi-round Conversation

Guides Codex Deepseek Routing Guide Zh (`docs/guides/codex-deepseek-routing-guide-zh.md`) Copy Section

在 Codex 中使用 Chat 格式 API：本地路由攻略与 DeepSeek 迁移说明

适用版本：CC Switch 3.20.4 及以上。本文根据仓库内文档与代码整理。截图使用去敏示例数据生成，避免泄露真实 API Key 或账户余额。

DeepSeek 用户多数已不需要本文：3.19.1 起 DeepSeek 预设改为原生 Responses 直连，deepseek-v4-pro 也已可以直连。本文现在主要写给两类读者：仍是 Chat 格式的供应商（如 SiliconFlow、ModelScope），以及 3.19.1 之前保存、仍走 Chat 的 DeepSeek 旧卡片。请先读下一节，确认你属于哪种情况。

先确认你是否还需要这篇攻略 Copy Chapter

判断方法只有一个，看 Codex 供应商卡片上有没有 需要路由 徽章：

• 带 需要路由 徽章 → 这个供应商走 Chat 格式，本文全部适用。
• 没有徽章 → 它已经是 Responses 原生直连，本文的路由步骤对它没有意义，可以直接用。
• 带 不支持路由 徽章 → 这是官方供应商，CC Switch 会阻止它走本地路由（见文末常见问题）。

徽章由供应商保存时记录的 API 格式决定，所以升级 CC Switch 不会改变已有供应商的行为。具体到 DeepSeek，有三种情况：

不只 DeepSeek，Kimi、智谱 GLM、MiniMax、千问AI平台的 Codex 预设也已先后改为原生直连。目前仍是 Chat 格式、需要本文的预设主要有 SiliconFlow、ModelScope、腾讯 Token Plan 系列、百度千帆 Coding Plan / Token Plan、StepFun 等，下文的步骤对它们完全适用。

为什么需要本地路由 Copy Chapter

新版 Codex CLI 面向的是 OpenAI Responses API，而很多供应商实际暴露的是 OpenAI Chat Completions 形态，也就是 /chat/completions。这两种协议的请求体、流式事件和返回结构不同，直接把 Chat 接口填进 Codex 配置里，常见结果就是模型列表不对、请求 404/400，或者流式响应无法被 Codex 正确解析。

CC Switch 的做法是让 Codex 始终连本机路由，仍以 Responses API 发送请求；路由在内部识别当前供应商是否是 Chat 格式，再把请求改写成 Chat Completions 发给上游，最后把 Chat 响应转换回 Responses 形态返回给 Codex。

这条链路主要分成四步：

1. Codex 接管时，本地配置会被写成 http://127.0.0.1:15721/v1，并强制保持 wire_api = "responses"。
2. Provider 的 meta.apiFormat = "openai_chat" 会告诉路由：真实上游是 Chat Completions。
3. 路由把 /responses 或 /v1/responses 改写到 /chat/completions，并把 Responses 请求体转换成 Chat 请求体。
4. 上游返回后，路由再把 Chat 的 JSON 或 SSE 转回 Codex 能理解的 Responses JSON/SSE。

供应商原生就是 Responses 的（如现在的 DeepSeek 预设），第 2～4 步不发生：请求直接发往上游，不做任何格式改写。

准备工作 Copy Chapter

你需要先准备好三样东西：

• 已安装并能启动的 CC Switch。
• 已安装 Codex CLI，并至少运行过一次，让 ~/.codex/config.toml 目录结构存在。
• 目标供应商的 API Key。

各家 OpenAI 兼容 base URL 的写法不一：常见的是带 /v1（例如 SiliconFlow 的 https://api.siliconflow.cn/v1），也有路径更长的（例如百度千帆 Coding Plan 的 https://qianfan.baidubce.com/v2/coding），Chat API 路径则是 /chat/completions。CC Switch 的预设已按各家文档配好，请优先使用预设，不需要手动拼接口路径。

第一步：添加 Codex 供应商 Copy Chapter

打开 CC Switch，切到顶部的 Codex 标签，点击右上角的加号添加供应商。

用预设（推荐）：在预设列表里选中目标供应商，填入 API Key，保存即可。预设已经内置请求地址、默认模型、模型菜单，并会自动设好上游格式；Chat 格式的预设保存后卡片上就会出现 需要路由 徽章。思考参数（thinking / reasoning）预设已自动配置好，不需要手动填。

用自定义配置：按对方文档填 API Key 和 base URL，然后展开表单底部的 高级选项，把 上游格式 选为 Chat Completions（需开启路由）。这个下拉共有三个选项：

• Responses（原生）——上游原生支持 Responses API，直连不转换，无需路由。
• Chat Completions（需开启路由）——本文讲的情况。
• Anthropic Messages（需开启路由）——上游只提供原生 Anthropic 协议，同样由路由转换。

只有 Responses（原生） 不需要开启路由接管，另外两个都需要。自定义供应商的思考参数由 CC Switch 按名称与地址自动推断，只有在识别不准时才需要展开 思考能力 手动覆盖。

改造已有的 DeepSeek 供应商：把 上游格式 改成 Responses（原生） 即可，不必删掉重建。下次切换到它时，CC Switch 会认出 deepseek.com 地址并套用 DeepSeek 官方的模型目录，freeform apply_patch、GPT-5 harness、low/high/max 思考档与 web_search 都会照常生效。

唯一的小差别是上下文窗口：供应商自己保存的模型行优先级更高，3.19.1 之前存下的 1000000 会盖掉官方声明的 1048576，少 4 万多 token。介意的话，在 高级选项 → 模型映射 里把该行的 上下文窗口 改成 1048576 就行，或者干脆用预设新建一个。

另外，直连所用的官方模型目录要求 Codex CLI 0.144.0 或更新（它带的 freeform apply_patch 注册需要这个版本），CC Switch 不会替你校验；生成的目录文件也会涨到 75 KB 左右，因为其中包含完整的 GPT-5 harness 文本。

第二步：开启本地路由并接管 Codex Copy Chapter

进入设置里的 路由 页面，展开 本地路由，完成两个开关：

1. 打开 路由总开关，启动本地服务。默认地址是 127.0.0.1:15721。
2. 在 路由启用 中打开 Codex。如果只想让 Codex 走路由，可以保持 Claude、Gemini 关闭。

接管后，CC Switch 会把 Codex 的 live 配置指向本机路由，并用占位符管理认证。真实 API Key 仍保存在 CC Switch 的 Provider 配置里，由本地路由在转发时注入，不需要你把 Key 暴露给 Codex live 配置。

第三步：切换供应商并重启 Codex Copy Chapter

回到 Codex 供应商列表，点击目标供应商的 启用。如果它带 需要路由 标记而路由没有启动，CC Switch 会弹出“需要路由服务才能正常使用”的提示。

切换后建议重启当前 Codex 终端会话。原因是：

• Codex 进程可能已经读取过旧的 config.toml。
• model_catalog_json 生成后，/model 菜单通常需要新进程才能刷新。

进入 Codex 后，可以用 /model 查看当前模型是否来自对应预设。随后发一个小问题，确认路由面板的请求数增长，或者在用量/请求日志里看到 Codex 请求即可。

走直连之后，用量归属会变 Copy Chapter

这一点值得单独提醒：供应商改走直连后，它的请求不再经过本地路由，按请求计费的代理用量统计也就看不到它了。

用量本身不会丢——Codex 的会话日志导入照常记录——但这条路径不携带供应商身份：所有没走本地代理的 Codex 用量会一起归入名为 Codex (Session) 的条目。要区分它们，看模型：每条用量记录都带着自己的模型 ID，用量面板的「模型统计」按模型逐行列出，费用与 token 都是分开的。

如果你确实需要按供应商维度对账（比如比较多个聚合商上的同一个模型），那就保持 上游格式 为 Chat 并开着路由接管。

常见问题 Copy Chapter

Codex 报 404 或找不到 /responses

通常是没有开启 Codex 接管，或者你手动把上游 Chat base URL 直接写给了 Codex。检查 ~/.codex/config.toml 是否指向 http://127.0.0.1:15721/v1。

上游报 404

如果用的是内置预设，先确认当前供应商确实来自预设，并且 Codex 路由已启用。只有在使用自定义供应商时，才需要额外检查 base URL：它应该是对方文档给出的服务端点，而不是带 /chat/completions 的完整接口路径。

/model 看不到供应商的模型

保存供应商后重启 Codex。CC Switch 会生成 cc-switch-model-catalog.json 并把路径写入 model_catalog_json，但正在运行的 Codex 进程不一定会热加载模型目录。
目前 Codex app 不支持多模型选择，默认使用配置的第一个模型。
如果命令行 /model 正常，但 Codex 桌面应用的模型选择器仍看不到自定义模型，这是 Codex 桌面应用上游自身的模型门控行为，详见 Codex 桌面应用里看不到自定义模型？（常见问题）。

开了路由但请求仍走错供应商

确认三处状态一致：Codex 标签下当前供应商正确；本地路由服务正在运行；路由启用 里 Codex 开关已打开。

可以用官方 OpenAI Codex 账号走本地路由吗

不建议。CC Switch 会在本地路由接管模式下阻止切到官方供应商，因为用代理访问官方 API 可能带来账号风险。路由主要用于第三方、聚合或协议转换场景。

参考链接 Copy Chapter

• CC Switch 用户手册：添加供应商
• CC Switch 用户手册：代理服务
• CC Switch 用户手册：应用路由
• DeepSeek API 文档：Integrate with Codex（官方 Codex 集成说明，含 wire_api = "responses" 与模型支持范围）
• DeepSeek API 文档：Using the Responses API
• DeepSeek API 文档：Your First API Call
• DeepSeek API 文档：Create Chat Completion
• DeepSeek API 文档：Multi-round Conversation

Guides Codex Desktop Custom Model Visibility En (`docs/guides/codex-desktop-custom-model-visibility-en.md`) Copy Section

Can't See Custom Models in the Codex Desktop App? (FAQ)

Applies to CC Switch v3.16.1 and later. This article explains "why the Codex desktop app can't see custom models" and the available mitigation; for the detailed step-by-step setup with screenshots, see Keep Codex Remote Control and Official Plugins While Using Third-Party APIs.

Symptom Copy Chapter

After you switch Codex to a third-party / custom model in CC Switch (DeepSeek, Kimi, GLM, MiniMax, an aggregator, etc.):

• The model picker in the Codex desktop app doesn't show these custom models — often only the official default model remains, and the reasoning level falls back to the official default;
• but everything works fine in the command-line codex /model menu.

Many users have run into this. Here's why, and what you can do about it.

Why this happens Copy Chapter

This is not a CC Switch local-config problem and not a CC Switch bug — it is the Codex desktop app's (the upstream closed-source client's) own model-gating behavior.

The Codex desktop app's model picker decides which models to allow based on your current login identity: when it can't detect an official ChatGPT / Codex login state, it forces the picker back to the official default model and hides the custom models you configured through config.toml (the reasoning level falls back to the official default too). The upstream has marked "exposing custom-provider models in the desktop GUI" as not planned, so CC Switch cannot fully fix this at the desktop-GUI level.

The command-line codex /model menu and request routing both recognize the custom providers in config.toml correctly — only the desktop GUI picker is constrained by this gating layer.

Mitigation: keep the official login Copy Chapter

The workaround is to keep the official login state so the desktop app's gating allows your custom models through. The key points are below (the full step-by-step setup with screenshots is in the linked guide):

1. Log in once with an official ChatGPT / Codex account in Codex (a Free subscription is enough) to keep the official login state.
2. In CC Switch, enable Settings -> General -> Codex App Enhancements -> Keep official login for direct switches (off by default). While routing takeover is enabled, the official login is always preserved, regardless of this toggle.
3. If this third-party provider shows the Needs Routing badge (Chat Completions protocol, such as SiliconFlow or ModelScope), enable local routing and route Codex through it; presets that connect directly, such as DeepSeek, Kimi, and MiniMax, do not need this step.
4. Fully quit and restart Codex.

Once enabled, CC Switch preserves the official login state in ~/.codex/auth.json when switching to a third-party provider and writes the third-party key into config.toml, so the desktop app still recognizes the official login identity, the gating lets your models through, and the custom models you configured reappear in the picker. The preserved official token is never sent to the third party — third-party model requests are still sent with the key you configured (forwarded through the local route when routing takeover is enabled).

Detailed step-by-step setup: Keep Codex Remote Control and Official Plugins While Using Third-Party APIs

Still can't see them? Copy Chapter

• Confirm the toggle is on: this toggle is off by default, and while it is off, a direct switch to a third-party provider deletes auth.json. That is how many people lose the official login state the first time they switch to a third-party provider, which is exactly why the models disappear — follow steps 1 and 2 above.
• The official login state expires: if you haven't used the official login for several days, the picker may go empty again once the token expires — log in to the official account once more to restore it.
• Command-line fallback diagnosis: run codex debug models to list the models actually available on the CLI side and confirm the model itself is configured correctly (the CLI is unaffected by this gating).
• Individual Codex desktop versions may behave slightly differently; this is in the upstream client's domain, and no CC Switch version can fully fix it at the desktop-GUI level.

References Copy Chapter

• Keep Codex Remote Control and Official Plugins While Using Third-Party APIs
• Using Chat-Format APIs in Codex: Local Routing Guide
• Local Routing

Guides Codex Desktop Custom Model Visibility Ja (`docs/guides/codex-desktop-custom-model-visibility-ja.md`) Copy Section

Codex デスクトップアプリでカスタムモデルが見えない？（よくある質問）

対象バージョン: CC Switch v3.16.1 以降。本記事は「なぜ Codex デスクトップアプリでカスタムモデルが見えないのか」と、使える緩和策を解説します。図入りの詳細な設定手順は サードパーティ API 利用時に Codex のリモート操作と公式プラグインを保持する を参照してください。

現象 Copy Chapter

CC Switch で Codex をサードパーティ / カスタムモデル（DeepSeek、Kimi、GLM、MiniMax、中継サービスなど）へ切り替えた後：

• Codex デスクトップアプリのモデルセレクタにこれらのカスタムモデルが表示されず、多くの場合は公式の既定モデルだけが残り、思考レベルも公式の既定へ戻ってしまう。
• 一方でコマンドライン codex の /model ではすべて正常に表示される。

多くのユーザーがこの現象に遭遇しています。以下で原因と対処を解説します。

なぜこうなるのか Copy Chapter

これは CC Switch のローカル設定の問題でも、CC Switch のバグでもありません。Codex デスクトップアプリ（上流のクローズドソースクライアント）自身のモデルゲーティング挙動です。

Codex デスクトップアプリのモデルセレクタは、あなたの現在のログイン ID に応じてどのモデルを通すかを決めます。公式 ChatGPT / Codex のログイン状態を検出できないとき、セレクタを公式の既定モデルへ強制的に戻し、config.toml で設定したカスタムモデルを隠します（思考レベルもあわせて公式の既定へ戻ります）。公式は「デスクトップ GUI でカスタムプロバイダーのモデルを公開する」ことを not planned としてマークしているため、CC Switch がデスクトップ GUI のレベルでこれを根本的に修正することはできません。

コマンドライン codex の /model とリクエストルーティングは config.toml 内のカスタムプロバイダーを正常に認識できます。デスクトップ GUI のセレクタだけがこのゲーティングの制限を受けます。

緩和策: 公式ログインを保持する Copy Chapter

対処は公式ログイン状態を保持することで、デスクトップアプリのゲーティングにあなたのカスタムモデルを通させます。要点は次のとおりです（完全な図入り手順は下のリンク先のガイドを参照してください）：

1. まず Codex で公式 ChatGPT / Codex に一度ログインし（Free サブスクリプションで構いません）、公式ログイン状態を保持する。
2. CC Switch で 設定 → 一般 → Codex アプリ拡張 → 直接切替時に公式ログインを保持 をオンにする（デフォルトはオフ）。ルーティング接管中は、このスイッチに関係なく公式ログインが常に保持されます。
3. そのサードパーティプロバイダーに ルーティングが必要 バッジが付いている場合（Chat Completions プロトコル。たとえば SiliconFlow、ModelScope）は、ローカルルーティングを有効化し、Codex のルーティングをオンにする。DeepSeek、Kimi、MiniMax などネイティブ直結のプリセットでは、この手順は不要です。
4. Codex を完全に終了して再起動する。

オンにすると、CC Switch はサードパーティプロバイダーへ切り替える際に ~/.codex/auth.json 内の公式ログイン状態を保持し、サードパーティの Key を config.toml へ書き込みます。これにより、デスクトップアプリは引き続き公式ログイン ID を認識してゲーティングを通すため、設定したカスタムモデルがセレクタに再び表示されます。保持された公式 Token がサードパーティへ送られることはありません——サードパーティのモデルリクエストは引き続き、設定した Key で送られます（ルーティング接管を有効にしている場合はローカルルーティング経由で転送されます）。

詳細な図入り手順: サードパーティ API 利用時に Codex のリモート操作と公式プラグインを保持する

それでも見えない場合は Copy Chapter

• スイッチがオンか確認する: このスイッチはデフォルトでオフで、オフのままルーティング接管なしでサードパーティへ切り替える（直接切替）と auth.json が削除されます。多くの人は初めてサードパーティへ切り替えたときにこうして公式ログイン状態を失っており、その結果見えなくなっています——上記の手順 1、2 に従って操作してください。
• 公式ログイン状態は期限切れになる: 数日間公式ログインを使わないと、Token が失効した後にセレクタが再び空になることがあります——公式に一度ログインし直せば回復します。
• コマンドラインでの確認: codex debug models を使うと CLI 側で実際に利用可能なモデルを一覧でき、モデル自体が正しく設定されていることを確認できます（CLI はこのゲーティングの影響を受けません）。
• 個々の Codex デスクトップ版で挙動が多少異なる場合があります。これは上流クライアントの範疇であり、CC Switch のどのバージョンでもデスクトップ GUI のレベルで根本解決することはできません。

参考リンク Copy Chapter

• サードパーティ API 利用時に Codex のリモート操作と公式プラグインを保持する
• Codex で Chat 形式 API を使う: ローカルルーティングガイド
• ローカルルーティング

Guides Codex Desktop Custom Model Visibility Zh (`docs/guides/codex-desktop-custom-model-visibility-zh.md`) Copy Section

Codex 桌面应用里看不到自定义模型？（常见问题）

适用版本：CC Switch v3.16.1 及以上。本文解释「为什么 Codex 桌面应用看不到自定义模型」以及可用的缓解办法；详细的图文配置步骤见 使用第三方 API 时保留 Codex 远程操作和官方插件。

现象 Copy Chapter

在 CC Switch 里把 Codex 切换到第三方 / 自定义模型（DeepSeek、Kimi、GLM、MiniMax、中转站等）后：

• Codex 桌面应用的模型选择器里看不到这些自定义模型，往往只剩官方默认模型，思考等级也回落到官方默认；
• 但命令行 codex 的 /model 里一切正常。

很多用户都遇到过这个现象，下面解释原因与办法。

为什么会这样 Copy Chapter

这不是 CC Switch 的本地配置问题，也不是 CC Switch 的 bug，而是 Codex 桌面应用（上游闭源客户端）自身的模型门控行为。

Codex 桌面应用的模型选择器会按你当前的登录身份来决定放行哪些模型：当它检测不到官方 ChatGPT / Codex 登录态时，会把选择器强制回落到官方默认模型，把你通过 config.toml 配置的自定义模型藏起来（思考等级也会一并回落到官方默认）。官方已把「在桌面 GUI 里暴露自定义供应商模型」标记为 not planned，因此 CC Switch 无法从桌面 GUI 层面彻底修复它。

命令行 codex 的 /model 与请求路由都能正常识别 config.toml 里的自定义供应商，唯独桌面 GUI 的选择器受这层门控限制。

怎么缓解：保留官方登录 Copy Chapter

办法是保留官方登录态，让桌面应用的门控放行你的自定义模型。要点如下（完整图文步骤见下方链接的攻略）：

1. 先在 Codex 里登录一次官方 ChatGPT / Codex（Free 订阅即可），保留官方登录态。
2. 在 CC Switch 开启 设置 → 通用 → Codex 应用增强 → 非接管切换时保留官方登录（默认关闭）。开启路由接管期间官方登录始终保留，不受这个开关影响。
3. 如果该第三方供应商带 需要路由 徽章（Chat Completions 协议，如 SiliconFlow、ModelScope），开启本地路由并接管 Codex；DeepSeek、Kimi、MiniMax 等原生直连的预设不需要这一步。
4. 完全退出并重启 Codex。

开启后，CC Switch 在切换第三方供应商时会保留 ~/.codex/auth.json 里的官方登录态、把第三方 Key 写进 config.toml，于是桌面应用仍识别官方登录身份、门控放行，你配置的自定义模型就会重新出现在选择器里。保留的官方 Token 不会被发往第三方——第三方模型请求仍用你配置的 Key 发出（开启路由接管时经本地路由转发）。

详细图文步骤：使用第三方 API 时保留 Codex 远程操作和官方插件

仍然看不到怎么办 Copy Chapter

• 确认开关已开：该开关默认关闭，关闭时直连切到第三方会删除 auth.json。很多人第一次切到第三方就这样丢了官方登录态，所以才看不到——按上面第 1、2 步操作即可。
• 官方登录态会过期：如果连续几天没用过官方登录，Token 失效后选择器可能又变空——重新登录一次官方即可恢复。
• 命令行兜底诊断：用 codex debug models 可以列出 CLI 端实际可用的模型，确认模型本身已正确配置（CLI 不受此门控影响）。
• 个别 Codex 桌面版本的行为可能略有差异；这属于上游客户端范畴，CC Switch 各版本都无法从桌面 GUI 层根治。

参考链接 Copy Chapter

• 使用第三方 API 时保留 Codex 远程操作和官方插件
• 在 Codex 中使用 Chat 格式 API：本地路由攻略
• 本地路由

Guides Codex Kimi Routing Guide En (`docs/guides/codex-kimi-routing-guide-en.md`) Copy Section

Use Kimi in Codex: Direct Connections and Legacy Routing

Since v3.20.3: Prefer Native Responses Connections Copy Chapter

The official Codex presets for the Kimi Open Platform and Kimi For Coding now use Responses, without local routing for protocol conversion. Existing cards retain their original preset snapshot and do not update automatically.

1. Upgrade to CC Switch v3.20.3 or later. In the Codex tab, choose the latest Kimi or Kimi For Coding preset according to where your API key comes from. For a key from the international site (kimi.ai), choose Kimi Global or Kimi For Coding Global (available since v3.20.4).
2. Enter the matching API key, save and enable the provider. For an older card, adding the preset again is recommended; for manual migration, verify the endpoint and change Upstream Format to Responses.
3. Restart Codex to load the configuration and model catalog. Native Responses can also use standard proxy routing, but Responses-to-Chat conversion is no longer required.

See the v3.20.3 release notes and Adding Providers. The following instructions and screenshots describe legacy Chat configurations, retained for troubleshooting existing Chat cards; they do not describe the latest presets.

Applies to CC Switch 3.16.5 and nearby versions. This guide is based on the repository documentation and code, and uses Kimi as an example of an OpenAI Chat Completions-compatible API. Screenshots are generated from the current frontend UI with de-identified sample data to avoid exposing a real API key or account balance.

Why Legacy Chat Configurations Need Local Routing Copy Chapter

The newer Codex CLI targets the OpenAI Responses API, while both the Kimi Open Platform and Kimi For Coding expose the OpenAI Chat Completions shape, /chat/completions. These two protocols use different request bodies, streaming events, and response structures. If you put a Kimi endpoint directly into Codex configuration, the usual result is a 404 on /responses, or streaming responses that Codex cannot parse correctly.

When this guide was first written, Kimi For Coding did not officially support Codex. Legacy Chat configurations needed a protocol conversion layer, which CC Switch Local Routing provided. The newer Responses presets no longer have this limitation.

CC Switch solves this by making Codex always talk to a local route and continue sending Responses API requests. The route detects whether the active provider is Chat-format, rewrites the request into Chat Completions for the upstream provider, and finally converts the Chat response back into the Responses shape that Codex understands.

The chain has four main steps:

1. When Codex routing is enabled, the local configuration is written as http://127.0.0.1:15721/v1, while wire_api = "responses" is kept in place.
2. The provider's meta.apiFormat = "openai_chat" tells the route that the real upstream is Chat Completions.
3. The route rewrites /responses or /v1/responses to /chat/completions, and converts the Responses request body into a Chat request body.
4. After the upstream responds, the route converts the Chat JSON or SSE stream back into Responses JSON/SSE.

Prerequisites Copy Chapter

Prepare these three things first:

• CC Switch installed and able to start.
• Codex CLI installed and run at least once, so the ~/.codex/config.toml directory structure exists.
• A Kimi API key.

Kimi API keys come from two different places, matching two different built-in presets in CC Switch:

• Kimi Open Platform (platform.kimi.com): pay-as-you-go API keys billed by token usage, matching the Kimi preset. The OpenAI-compatible base URL is https://api.moonshot.cn/v1 and the default model is kimi-k2.7-code.
• Kimi For Coding (kimi.com/code): a dedicated key generated from the Kimi Code membership benefits, matching the Kimi For Coding preset. The base URL is https://api.kimi.com/coding/v1 and the unified model is kimi-for-coding.

Both presets already contain the correct endpoint and model details, so prefer the presets and do not manually assemble the endpoint path.

Step 1: Add a Codex provider Copy Chapter

Open CC Switch, switch to the top-level Codex tab, and click the plus button in the upper-right corner to add a provider.

Depending on which kind of key you have, choose the built-in Kimi preset (Open Platform, pay-as-you-go) or Kimi For Coding preset (membership subscription). You only need to do two things:

• Enter the matching Kimi API key.
• Save the provider.

The preset already includes Kimi's request base URL, default model, model menu, thinking/reasoning parameters, and presets Upstream Format under Advanced Options to Chat Completions (routing required). You can adjust the default model or model display names if needed — for example, the Open Platform preset defaults to kimi-k2.7-code, and you can switch to kimi-k2.7-code-highspeed following the official documentation. The protocol conversion is handled by the routing layer.

Step 2: Enable local routing and route Codex Copy Chapter

Go to the Routing page in Settings, expand Local Routing, and complete two toggles:

1. Turn on the Routing Master Switch to start the local service. The default address is 127.0.0.1:15721.
2. Turn on Codex under Routing Enabled. If you only want Codex to use local routing, you can leave Claude and Gemini off.

After routing is enabled, CC Switch points Codex's live configuration to the local route and manages authentication with a placeholder. The real Kimi key stays in the CC Switch provider configuration and is injected by the local route while forwarding requests, so you do not need to expose the key in Codex's live configuration.

Step 3: Switch providers and restart Codex Copy Chapter

Return to the Codex provider list and click Enable on the Kimi provider. If you see the Needs Routing marker, that provider must be used while routing is running; when the route is not started, CC Switch shows a prompt saying the routing service is required.

After switching, restart the current Codex terminal session. This is recommended because:

• The Codex process may already have read the old config.toml.
• After model_catalog_json is generated, the /model menu usually needs a fresh process before it refreshes.

Inside Codex, use /model to check whether the current model comes from the Kimi preset, such as Kimi K2.7 Code or Kimi For Coding. The Codex app currently does not support multi-model selection, so it defaults to the first configured model. Then send a small test prompt and confirm that the request count increases in the routing panel, or that a Codex request appears in usage/request logs.

How to handle other Chat providers Copy Chapter

SiliconFlow, ModelScope, and other common Chat-format providers already have presets in CC Switch, so use presets first. Only choose custom configuration for providers that are not covered by presets; in that case, fill in the API key, base URL, and models according to the provider's documentation, and set Upstream Format under Advanced Options to Chat Completions (routing required).

If the upstream provider directly supports the OpenAI Responses API, set Upstream Format to Responses; CC Switch then connects through Responses directly without Chat conversion.

FAQ Copy Chapter

Codex reports 404 or cannot find /responses

Usually Codex routing is not enabled, or the Kimi Chat base URL was written directly into Codex manually — the Kimi upstream has no /responses endpoint, so that always 404s. Check whether ~/.codex/config.toml points to http://127.0.0.1:15721/v1.

Kimi upstream reports 401 or 403

First confirm the key matches the preset: Open Platform keys only work with the Kimi preset, and Kimi Code membership keys only work with the Kimi For Coding preset. The two key families are not interchangeable.

Kimi upstream reports 404

If you are using a built-in Kimi preset, first confirm that the active provider really comes from the preset and that Codex routing is enabled. Only custom providers require extra base URL checks: the base URL should be the service root, not the full endpoint path with /chat/completions.

/model does not show Kimi models

Restart Codex after saving the provider. CC Switch generates cc-switch-model-catalog.json and writes its path to model_catalog_json, but a running Codex process may not hot-load the model catalog.
The Codex app currently does not support multi-model selection, so it uses the first configured model by default.
If the command-line /model menu works but the Codex desktop app model picker still cannot see custom models, that is the upstream Codex desktop app's own model-gating behavior. See Can't See Custom Models in the Codex Desktop App? (FAQ).

Routing is enabled, but requests still go to the wrong provider

Confirm that all three states match: the current provider under the Codex tab is Kimi; the local routing service is running; and the Codex toggle is enabled under Routing Enabled.

Can I use an official OpenAI Codex account through local routing?

Not recommended. CC Switch blocks switching to official providers while local routing takeover is enabled, because accessing official APIs through a proxy may create account risk. Routing is mainly intended for third-party, aggregator, or protocol-conversion scenarios.

References Copy Chapter

• CC Switch User Manual: Add Provider
• CC Switch User Manual: Proxy Service
• CC Switch User Manual: App Routing
• Kimi Open Platform: Using Kimi K2.7 Code in coding tools
• Kimi Code Docs: Overview
• Kimi Code Docs: Using with third-party coding agents

Guides Codex Kimi Routing Guide Ja (`docs/guides/codex-kimi-routing-guide-ja.md`) Copy Section

Codex で Kimi を使う: 直接接続と旧版ルーティング

v3.20.3 以降：ネイティブ Responses で直接接続 Copy Chapter

Kimi オープンプラットフォームと Kimi For Coding の公式 Codex プリセットは Responses に移行しました。プロトコル変換のためのローカルルーティングは不要です。既存カードには作成時のプリセットが保存されており、自動更新はされません。

1. CC Switch v3.20.3 以降に更新し、Codex タブで API Key の発行元に応じた最新の Kimi または Kimi For Coding プリセットを選択します。国際版（kimi.ai）の Key には Kimi Global または Kimi For Coding Global（v3.20.4 から提供）を選択します。
2. 対応する API Key を入力し、保存して有効にします。旧カードはプリセットの追加し直しを推奨します。手動で移行する場合は、エンドポイントを確認して「上流フォーマット」を Responses に変更します。
3. Codex を再起動し、設定とモデルカタログを読み込みます。ネイティブ Responses を通常のプロキシ経由で転送することもできますが、Responses→Chat 変換は不要です。

詳細は v3.20.3 更新情報とプロバイダーの追加を参照してください。以下は既存の Chat カードのトラブルシュート用に残した旧版の手順と画像であり、最新プリセットの設定ではありません。

対象バージョン: CC Switch 3.16.5 およびその前後のバージョン。本記事はリポジトリ内のドキュメントとコードをもとに整理し、OpenAI Chat Completions 互換 API の例として Kimi を使用します。スクリーンショットは現在のフロントエンド UI から、実際の API Key やアカウント残高が漏れないよう匿名化したサンプルデータで生成しています。

旧版 Chat 設定にローカルルーティングが必要な理由 Copy Chapter

新しい Codex CLI は OpenAI Responses API を前提にしています。一方で Kimi オープンプラットフォームと Kimi For Coding が実際に公開しているのは、いずれも OpenAI Chat Completions 形式、つまり /chat/completions です。この 2 つのプロトコルは、リクエストボディ、ストリーミングイベント、レスポンス構造が異なります。Kimi のエンドポイントをそのまま Codex 設定に入れると、/responses へのリクエストが 404 になる、ストリーミングレスポンスを Codex が正しく解析できない、といった問題が起きがちです。

本記事の初稿時点では、Kimi For Coding は Codex を公式にサポートしておらず、旧版の Chat 設定にはプロトコル変換レイヤーが必要でした。その役割を CC Switch のローカルルーティングが担っていました。新しい Responses プリセットにはこの制限はありません。

CC Switch では、Codex が常にローカルルートへ接続し、Responses API のままリクエストを送るようにします。ルート内部で現在のプロバイダーが Chat 形式かどうかを判定し、必要ならリクエストを Chat Completions に書き換えて上流へ送り、最後に Chat レスポンスを Codex が理解できる Responses 形式へ戻します。

この経路は主に 4 つのステップに分かれます：

1. Codex ルーティングを有効にすると、ローカル設定は http://127.0.0.1:15721/v1 に書き換えられ、wire_api = "responses" は維持されます。
2. Provider の meta.apiFormat = "openai_chat" が、実際の上流は Chat Completions だとルートに伝えます。
3. ルートは /responses または /v1/responses を /chat/completions に書き換え、Responses のリクエストボディを Chat のリクエストボディへ変換します。
4. 上流から返ってきた後、ルートは Chat の JSON または SSE ストリームを Responses JSON/SSE へ変換して返します。

事前準備 Copy Chapter

先に次の 3 つを用意してください：

• インストール済みで起動できる CC Switch。
• インストール済みの Codex CLI。少なくとも 1 回は実行し、~/.codex/config.toml のディレクトリ構造が存在していること。
• Kimi の API Key。

Kimi の API Key には 2 つの取得元があり、CC Switch の 2 つの内蔵プリセットに対応します：

• Kimi オープンプラットフォーム（platform.kimi.com）: トークン使用量に応じた従量課金の API Key。プリセット Kimi に対応し、OpenAI 互換 base URL は https://api.moonshot.cn/v1、デフォルトモデルは kimi-k2.7-code です。
• Kimi For Coding（kimi.com/code）: Kimi メンバーシップの Kimi Code 特典から生成する専用 Key。プリセット Kimi For Coding に対応し、base URL は https://api.kimi.com/coding/v1、モデルは kimi-for-coding に統一されています。

どちらのプリセットにも公式情報に基づくエンドポイントとモデルがすでに設定されているため、まずはプリセットを使い、エンドポイントパスを手で組み立てる必要はありません。

Step 1: Codex プロバイダーを追加する Copy Chapter

CC Switch を開き、上部の Codex タブへ切り替え、右上のプラスボタンからプロバイダーを追加します。

手元の Key の種類に応じて、内蔵プリセットの Kimi（オープンプラットフォーム・従量課金）または Kimi For Coding（メンバーシップ）を選びます。必要なのは次の 2 つだけです：

• 対応する Kimi API Key を入力する。
• プロバイダーを保存する。

プリセットには Kimi のリクエスト先、デフォルトモデル、モデルメニュー、thinking/reasoning パラメータがすでに含まれており、詳細オプション の 上流フォーマット も Chat Completions（ルーティング必須） にプリセットされています。必要に応じてデフォルトモデルやモデル表示名を調整できます。たとえばオープンプラットフォームのプリセットはデフォルトが kimi-k2.7-code で、公式ドキュメントに従って kimi-k2.7-code-highspeed に変更することもできます。プロトコル変換はルーティング層に任せれば十分です。

Step 2: ローカルルーティングを有効にして Codex をルーティングする Copy Chapter

設定の ルーティング ページに入り、ローカルルーティング を展開して、次の 2 つのスイッチを設定します：

1. ルーティング総スイッチ をオンにしてローカルサービスを起動します。デフォルトアドレスは 127.0.0.1:15721 です。
2. ルーティング有効 で Codex をオンにします。Codex だけをルーティングしたい場合は、Claude と Gemini はオフのままで構いません。

ルーティングを有効にすると、CC Switch は Codex の live 設定をローカルルートへ向け、認証はプレースホルダーで管理します。実際の Kimi Key は CC Switch の Provider 設定内に残り、ローカルルートが転送時に注入します。そのため、Codex の live 設定に Key を露出させる必要はありません。

Step 3: プロバイダーを切り替えて Codex を再起動する Copy Chapter

Codex プロバイダー一覧に戻り、Kimi プロバイダーの 有効化 をクリックします。ルーティングが必要 の表示が見える場合、そのプロバイダーはルーティング実行中に使う必要があります。ルーティングが起動していない場合、CC Switch は「ルーティングサービスが必要」という趣旨のメッセージを表示します。

切り替え後は、現在の Codex ターミナルセッションを再起動することをおすすめします。理由は次のとおりです：

• Codex プロセスがすでに古い config.toml を読み込んでいる可能性があります。
• model_catalog_json の生成後、/model メニューの更新には通常、新しいプロセスが必要です。

Codex に入ったら、/model で現在のモデルが Kimi プリセット由来かどうかを確認します。たとえば Kimi K2.7 Code や Kimi For Coding などです。現在の Codex app は複数モデル選択に対応していないため、設定内の最初のモデルをデフォルトで使用します。その後、小さな質問を 1 つ送って、ルーティングパネルのリクエスト数が増えるか、usage / リクエストログに Codex リクエストが出るかを確認します。

他の Chat プロバイダーの場合 Copy Chapter

SiliconFlow、ModelScope など一般的な Chat 形式プロバイダーは CC Switch にプリセットがあるため、まずはプリセットを使ってください。プリセットにないプロバイダーだけ、カスタム設定を選びます。その場合は相手側のドキュメントに従って API Key、base URL、モデルを入力し、詳細オプション の 上流フォーマット を Chat Completions（ルーティング必須） に設定します。

上流が OpenAI Responses API を直接サポートしている場合は、上流フォーマット を Responses にすれば、CC Switch は Responses のまま直結でき、Chat 変換は行いません。

よくある質問 Copy Chapter

Codex が 404 を返す、または /responses が見つからない

多くの場合、Codex ルーティングが有効になっていないか、Kimi の Chat base URL を手動で Codex に直接書いています。Kimi の上流には /responses エンドポイントが存在しないため、必ず 404 になります。~/.codex/config.toml が http://127.0.0.1:15721/v1 を指しているか確認してください。

Kimi 上流が 401 または 403 を返す

まず Key とプリセットの組み合わせを確認してください。オープンプラットフォームの Key はプリセット Kimi 専用、Kimi Code 特典の Key はプリセット Kimi For Coding 専用で、2 種類の Key は相互に使えません。

Kimi 上流が 404 を返す

内蔵 Kimi プリセットを使っている場合は、まず現在のプロバイダーが本当にプリセット由来であること、そして Codex ルーティングが有効であることを確認してください。カスタムプロバイダーを使っている場合だけ、base URL を追加で確認します。base URL はサービスのルートであり、/chat/completions 付きの完全なエンドポイントパスではありません。

/model に Kimi モデルが表示されない

プロバイダーを保存した後、Codex を再起動してください。CC Switch は cc-switch-model-catalog.json を生成し、そのパスを model_catalog_json に書き込みますが、実行中の Codex プロセスがモデルカタログをホットロードするとは限りません。
現在の Codex app は複数モデル選択に対応していないため、設定内の最初のモデルをデフォルトで使用します。
コマンドラインの /model は正常なのに Codex デスクトップアプリのモデルセレクタでカスタムモデルが見えない場合、それは Codex デスクトップアプリ上流自身のモデルゲーティング挙動です。詳しくは Codex デスクトップアプリでカスタムモデルが見えない？（よくある質問） を参照してください。

ルーティングを有効にしたのに、リクエストが別のプロバイダーへ行く

次の 3 つの状態が一致しているか確認してください：Codex タブの現在のプロバイダーが Kimi であること、ローカルルーティングサービスが実行中であること、ルーティング有効 で Codex スイッチがオンであること。

公式 OpenAI Codex アカウントをローカルルーティング経由で使えますか

おすすめしません。CC Switch はローカルルーティング有効中、公式プロバイダーへの切り替えをブロックします。プロキシ経由で公式 API にアクセスすると、アカウントリスクが発生する可能性があるためです。ルーティングは主にサードパーティ、集約サービス、またはプロトコル変換のための機能です。

参考リンク Copy Chapter

• CC Switch ユーザーマニュアル: プロバイダーの追加
• CC Switch ユーザーマニュアル: プロキシサービス
• CC Switch ユーザーマニュアル: アプリケーションルーティング
• Kimi オープンプラットフォーム: コーディングツールで Kimi K2.7 Code を使う
• Kimi Code ドキュメント: 概要
• Kimi Code ドキュメント: サードパーティ Coding Agent での利用

Guides Codex Kimi Routing Guide Zh (`docs/guides/codex-kimi-routing-guide-zh.md`) Copy Section

在 Codex 中使用 Kimi：新版直连与旧版路由

v3.20.3 起：优先使用原生 Responses 直连 Copy Chapter

Kimi 开放平台和 Kimi For Coding 的官方 Codex 预设已切换为 Responses，无需为了协议转换开启本地路由。旧卡片保存的是创建时的快照，不会自动更新。

1. 升级到 CC Switch v3.20.3 或更新版本，在 Codex 标签下按 API Key 来源选择最新的 Kimi 或 Kimi For Coding 预设。国际站（kimi.ai）的 Key 选 Kimi Global 或 Kimi For Coding Global（v3.20.4 起提供）。
2. 填入对应 API Key，保存并启用。旧卡片建议重新添加预设；若手动迁移，确认端点正确后将「上游格式」改为 Responses。
3. 重启 Codex，使配置和模型目录生效。原生 Responses 也可经标准代理转发，但不再需要 Responses→Chat 转换。

详见 v3.20.3 更新说明与添加供应商。下文保留的是旧版 Chat 格式教程与截图，仅供已有 Chat 卡片排障参考，不代表新版预设的配置。

适用版本：CC Switch 3.16.5 及附近版本。本文根据仓库内文档与代码整理，并用 Kimi 作为 OpenAI Chat Completions 兼容接口的示例。截图来自当前前端界面，使用去敏示例数据生成，避免泄露真实 API Key 或账户余额。

旧版 Chat 配置为什么需要本地路由 Copy Chapter

新版 Codex CLI 面向的是 OpenAI Responses API，而 Kimi 开放平台和 Kimi For Coding 实际暴露的都是 OpenAI Chat Completions 形态，也就是 /chat/completions。这两种协议的请求体、流式事件和返回结构不同，直接把 Kimi 的接口地址填进 Codex 配置里，常见结果就是请求 /responses 返回 404，或者流式响应无法被 Codex 正确解析。

本文最初编写时，Kimi For Coding 官方支持的第三方工具尚未覆盖 Codex，旧版 Chat 配置需要一层协议转换——这正是 CC Switch 本地路由做的事。新版 Responses 预设不再受此限制。

CC Switch 的做法是让 Codex 始终连本机路由，仍以 Responses API 发送请求；路由在内部识别当前供应商是否是 Chat 格式，再把请求改写成 Chat Completions 发给上游，最后把 Chat 响应转换回 Responses 形态返回给 Codex。

这条链路主要分成四步：

1. Codex 接管时，本地配置会被写成 http://127.0.0.1:15721/v1，并强制保持 wire_api = "responses"。
2. Provider 的 meta.apiFormat = "openai_chat" 会告诉路由：真实上游是 Chat Completions。
3. 路由把 /responses 或 /v1/responses 改写到 /chat/completions，并把 Responses 请求体转换成 Chat 请求体。
4. 上游返回后，路由再把 Chat 的 JSON 或 SSE 转回 Codex 能理解的 Responses JSON/SSE。

准备工作 Copy Chapter

你需要先准备好三样东西：

• 已安装并能启动的 CC Switch。
• 已安装 Codex CLI，并至少运行过一次，让 ~/.codex/config.toml 目录结构存在。
• 一个 Kimi API Key。

Kimi 的 API Key 有两个来源，对应 CC Switch 里两个不同的内置预设：

• Kimi 开放平台（platform.kimi.com）：按 token 用量计费的 API Key，对应预设 Kimi，OpenAI 兼容 base URL 是 https://api.moonshot.cn/v1，默认模型 kimi-k2.7-code。
• Kimi For Coding（kimi.com/code）：Kimi 会员 Kimi Code 权益生成的专用 Key，对应预设 Kimi For Coding，base URL 是 https://api.kimi.com/coding/v1，模型统一为 kimi-for-coding。

两个预设都已经按官方信息配好接口地址和模型，请优先使用预设，不需要手动拼接口路径。

第一步：添加 Codex 供应商 Copy Chapter

打开 CC Switch，切到顶部的 Codex 标签，点击右上角的加号添加供应商。

按你手里 Key 的类型，在内置预设里选择 Kimi（开放平台按量计费）或 Kimi For Coding（会员订阅），然后只需要做两件事：

• 填入对应的 Kimi API Key。
• 保存供应商。

预设已经内置 Kimi 的请求地址、默认模型、模型菜单、thinking/reasoning 参数，并把 高级选项 里的 上游格式 预设为 Chat Completions（需开启路由）。你可以按需调整默认模型或模型显示名——例如开放平台预设默认是 kimi-k2.7-code，也可以按官方文档换成 kimi-k2.7-code-highspeed；协议转换交给路由层完成即可。

第二步：开启本地路由并接管 Codex Copy Chapter

进入设置里的 路由 页面，展开 本地路由，完成两个开关：

1. 打开 路由总开关，启动本地服务。默认地址是 127.0.0.1:15721。
2. 在 路由启用 中打开 Codex。如果只想让 Codex 走路由，可以保持 Claude、Gemini 关闭。

接管后，CC Switch 会把 Codex 的 live 配置指向本机路由，并用占位符管理认证。真实 Kimi Key 仍保存在 CC Switch 的 Provider 配置里，由本地路由在转发时注入，不需要你把 Key 暴露给 Codex live 配置。

第三步：切换供应商并重启 Codex Copy Chapter

回到 Codex 供应商列表，点击 Kimi 供应商的 启用。如果看到 需要路由 标记，说明这个供应商必须在路由运行时使用；没有启动路由时，CC Switch 会弹出“需要路由服务才能正常使用”的提示。

切换后建议重启当前 Codex 终端会话。原因是：

• Codex 进程可能已经读取过旧的 config.toml。
• model_catalog_json 生成后，/model 菜单通常需要新进程才能刷新。

进入 Codex 后，可以用 /model 查看当前模型是否来自 Kimi 预设，例如 Kimi K2.7 Code 或 Kimi For Coding。目前 Codex app 不支持多模型选择时，会默认使用配置里的第一个模型。随后发一个小问题，确认路由面板的请求数增长，或者在用量/请求日志里看到 Codex 请求即可。

其它 Chat 供应商怎么处理 Copy Chapter

SiliconFlow、ModelScope 等常见 Chat 格式供应商在 CC Switch 里已有预设，优先用预设即可。只有预设里没有的供应商，才需要选择自定义配置；这时按对方文档填 API Key、base URL 和模型，并把 高级选项 里的 上游格式 选为 Chat Completions（需开启路由）。

如果上游直接支持 OpenAI Responses API，把 上游格式 选为 Responses 即可；这时 CC Switch 按 Responses 直连，不做 Chat 转换。

常见问题 Copy Chapter

Codex 报 404 或找不到 /responses

通常是没有开启 Codex 接管，或者你手动把 Kimi 的 Chat base URL 直接写给了 Codex——Kimi 上游没有 /responses 端点，这样一定会 404。检查 ~/.codex/config.toml 是否指向 http://127.0.0.1:15721/v1。

Kimi 上游报 401 或 403

先确认 Key 和预设是否匹配：开放平台的 Key 只能配 Kimi 预设，Kimi Code 会员权益的 Key 只能配 Kimi For Coding 预设，两套 Key 不能混用。

Kimi 上游报 404

如果用的是内置 Kimi 预设，先确认当前供应商确实来自预设，并且 Codex 路由已启用。只有在使用自定义供应商时，才需要额外检查 base URL：它应该是服务根地址，而不是带 /chat/completions 的完整接口路径。

/model 看不到 Kimi 模型

保存供应商后重启 Codex。CC Switch 会生成 cc-switch-model-catalog.json 并把路径写入 model_catalog_json，但正在运行的 Codex 进程不一定会热加载模型目录。
目前 Codex app 不支持多模型选择，默认使用配置的第一个模型。
如果命令行 /model 正常，但 Codex 桌面应用的模型选择器仍看不到自定义模型，这是 Codex 桌面应用上游自身的模型门控行为，详见 Codex 桌面应用里看不到自定义模型？（常见问题）。

开了路由但请求仍走错供应商

确认三处状态一致：Codex 标签下当前供应商是 Kimi；本地路由服务正在运行；路由启用 里 Codex 开关已打开。

可以用官方 OpenAI Codex 账号走本地路由吗

不建议。CC Switch 会在本地路由接管模式下阻止切到官方供应商，因为用代理访问官方 API 可能带来账号风险。路由主要用于第三方、聚合或协议转换场景。

参考链接 Copy Chapter

• CC Switch 用户手册：添加供应商
• CC Switch 用户手册：代理服务
• CC Switch 用户手册：应用路由
• Kimi 开放平台：在编程工具中使用 Kimi K2.7 Code 模型
• Kimi Code 文档：概览
• Kimi Code 文档：在第三方 Coding Agent 中使用

Guides Codex Official Auth Preservation Guide En (`docs/guides/codex-official-auth-preservation-guide-en.md`) Copy Section

Keep Codex Remote Control and Official Plugins While Using Third-Party APIs: CC Switch Setup Guide

Applies to CC Switch v3.20.1 and later; UI text follows v3.20.4. This guide is based on the current code, user manual, and the v3.16.1 / v3.20.1 release notes. Screenshots use de-identified sample data and do not include real Access Tokens or API keys. Some screenshots were taken on older versions; where a switch name differs, the text of this guide takes precedence.

What this guide solves Copy Chapter

Many Codex users want both of these at the same time:

1. Use models from DeepSeek, Kimi, GLM, MiniMax, SiliconFlow, or other third-party APIs, or use GPT models through an aggregator.
2. Keep Codex official-app capabilities such as mobile remote control and official plugins.

Previously, when switching to a third-party provider, the old behavior wrote the third-party API key into Codex auth.json, which could overwrite the original official ChatGPT / Codex login cache. The third-party model worked, but features that depend on the official login state disappeared.

The Codex App Enhancements switch added in v3.16.1 solves this conflict: the official Access Token stays in auth.json, while third-party provider information is written to config.toml. Codex App can still see an official account, but actual model requests follow the third-party provider currently selected in CC Switch.

This behavior already existed in v3.16.0 and was enabled by default. After some users reported that they did not want this behavior, v3.16.1 turned it into an explicit switch.

Since v3.20.1, the switching logic has been simplified one step further: third-party API keys are only ever written to config.toml and never to auth.json. This switch now decides just one thing: when you switch directly to a third-party provider, whether the official login in auth.json is kept or deleted.

Quick answer Copy Chapter

Recommended order:

1. In the CC Switch Codex panel, switch to OpenAI Official.
2. Start Codex and log in once with an official ChatGPT / Codex account. A Free subscription is enough.
3. Return to CC Switch and enable Settings -> General -> Codex App Enhancements -> Keep official login for direct switches.
4. Add or switch to a third-party Codex provider.
5. If the provider uses the Chat Completions protocol (its card shows the Needs Routing badge, for example SiliconFlow or ModelScope), also enable local routing and route Codex through it. Presets such as DeepSeek, Kimi, MiniMax, and Zhipu GLM already connect directly, so they do not need this step.
6. Restart Codex so config.toml and the model catalog are reloaded.

Prerequisites Copy Chapter

Prepare the following:

• CC Switch v3.20.1 or later.
• Codex installed and able to start. Installing both the app and CLI is recommended.
• An official ChatGPT / Codex account that can log in to Codex. A Free subscription is enough.
• A third-party API key, such as DeepSeek, Kimi, GLM, MiniMax, OpenRouter, SiliconFlow, or similar.

Do not manually copy or share the contents of ~/.codex/auth.json. It stores official login cache and Access Tokens, so it is sensitive.

Step 1: Switch back to OpenAI Official and complete official login Copy Chapter

Open CC Switch and switch to the top-level Codex tab. First select the OpenAI Official provider, or add it from the preset providers if it is missing, and make it the current provider.

Then start Codex, preferably the CLI, and follow the official login flow to sign in with your ChatGPT / Codex account. This account can be on the Free plan. In this setup, it mainly preserves the official identity required by Codex App, and does not pay for third-party model usage.

After login, Codex stores the official login cache in ~/.codex/auth.json. The key point for the following steps is: do not let third-party provider switching overwrite this file again.

Step 2: Enable Codex App Enhancements Copy Chapter

Return to CC Switch and open:

Settings -> General -> Codex App Enhancements

Enable:

Keep official login for direct switches

This switch is off by default because some users do not want this behavior. Enable it only when you explicitly want "third-party API + official remote control / official plugins" at the same time.

After it is enabled, when you switch to a third-party provider without routing takeover:

• auth.json: keeps the official ChatGPT / Codex login cache.
• config.toml: stores the active third-party provider's model, endpoint, model_provider, and provider-scoped experimental_bearer_token.

The config.toml half has nothing to do with the switch: it is written the same way when the switch is off. The switch only controls whether auth.json is kept or removed. While routing takeover is enabled, the official login is always preserved, regardless of this switch.

Step 3: Add a third-party Codex provider Copy Chapter

Return to the Codex panel and click the plus button in the upper-right corner to add a provider. Prefer built-in presets such as DeepSeek, Kimi, MiniMax, GLM, or SiliconFlow. After selecting a preset, you only need to enter the API key; the preset automatically configures the base URL, default model, model catalog, and upstream format.

After saving, check the badge on the provider card:

• No badge: the upstream natively supports the OpenAI Responses API and can connect directly, without local routing. The DeepSeek, Kimi, MiniMax, Zhipu GLM, and 千问AI平台 presets, as well as aggregators that offer GPT models, all fall into this group.
• Has the Needs Routing badge: the upstream format is Chat Completions (routing required), for example SiliconFlow or ModelScope. Local routing must be enabled for these providers so CC Switch can convert Codex Responses requests into Chat Completions requests.

For a custom provider, choose the upstream format under Advanced Options -> Upstream Format at the bottom of the form.

Step 4: Enable local routing and route Codex when needed Copy Chapter

Open:

Settings -> Routing -> Local Routing

Complete two actions:

1. Turn on the Routing Master Switch to start the local service. The default address is usually 127.0.0.1:15721.
2. Under Routing Enabled, turn on Codex.

After takeover, Codex's live config.toml temporarily points to the CC Switch local route, and the token field holds the placeholder PROXY_MANAGED. The real third-party API key remains in the CC Switch provider configuration and is injected by the local route when it forwards requests. During takeover, the official login in auth.json is always preserved.

Step 5: Switch to the third-party provider and restart Codex Copy Chapter

Return to the Codex provider list and enable the third-party provider you just added. After switching, restarting Codex is recommended for two reasons:

• Codex reads config.toml at startup.
• The Codex /model menu usually needs a restart before it reloads model_catalog_json.

After restart, you can run a quick verification:

• In Codex App, the account information still shows the official account. This is expected.
• In CC Switch, the current Codex provider is the third-party provider.
• If local routing is enabled, request logs or routing stats show Codex requests going through the local route.
• The third-party provider dashboard or balance records show actual model requests.

How it works Copy Chapter

Codex mainly uses two configuration files:

~/.codex/auth.json
~/.codex/config.toml

They have different responsibilities:

• auth.json stores the official ChatGPT / Codex login cache, which Codex App needs to identify the official account and enable remote control and official plugins.
• config.toml stores runtime configuration such as the current model provider, base URL, model, model catalog, and provider-scoped token.

When you switch directly to a third-party provider, CC Switch takes the third-party provider API key from the provider configuration and writes it under the current provider in config.toml (this step does not depend on the switch):

model_provider = "custom"

[model_providers.custom]
name = "DeepSeek"
base_url = "https://api.deepseek.com"
wire_api = "responses"
experimental_bearer_token = "sk-..."

With Keep official login for direct switches enabled, auth.json keeps the official login cache unchanged. Codex App can still identify the official account, while model requests follow the current provider and base URL in config.toml.

If the provider uses the Chat Completions protocol, CC Switch local routing adds another conversion layer:

Codex Responses request
        |
CC Switch local route
        |
Third-party Chat Completions API
        |
Converted back to Codex Responses response

This is why you can keep using official plugins / mobile remote control while moving model traffic to a third-party API.

Side effects to understand Copy Chapter

Codex still shows the official account Copy Section

This is the easiest part to misunderstand. After this capability is enabled, Codex App reads the official login state from auth.json, so it continues to display the official account.

That does not mean model requests are still going to official OpenAI. Actual traffic is determined by the current Codex provider in CC Switch, config.toml, and local routing logs.

Do not use the Codex account display to judge billing Copy Section

If you switch to DeepSeek, Codex can still display the official account, while model requests go to the DeepSeek API. Billing, quota, error codes, and data policy should all be understood according to the third-party provider. You can inspect specific request details in the usage panel.

Restart Codex after changing model mappings Copy Section

Codex reads the model catalog at startup. Even if CC Switch has generated a new model catalog, a running Codex process may not hot-load it, so restart Codex after editing model mappings.

With the switch off, direct switches delete the official login Copy Section

If Keep official login for direct switches is turned off, switching to a third-party provider without routing takeover makes CC Switch delete auth.json. Codex App then loses its official login state, so official remote control and official plugins stop working. The third-party API key is still written only to config.toml, never to auth.json.

Routing takeover is not affected by this switch: while routing takeover is enabled, the official login is always preserved. If your goal is to keep official remote control and official plugins long term, keep this switch enabled.

FAQ Copy Chapter

I switched to a third-party API. Why does Codex still show the official account?

This is expected. Official account information comes from auth.json; the actual model provider comes from config.toml and the current provider in CC Switch.

Is a Free subscription really enough?

Yes. The official account is mainly used to obtain and preserve the official login state required by Codex App. Third-party model requests use the third-party API key configured in CC Switch.

What should I do if official plugins or mobile remote control still do not work?

Switch back to OpenAI Official, restart Codex, and complete official login once. Then confirm Settings -> General -> Codex App Enhancements -> Keep official login for direct switches is enabled in CC Switch before switching back to the third-party provider.

What if third-party requests return 404, the model list is wrong, or streaming responses are broken?

If the provider uses Chat Completions, confirm that Upstream Format under Advanced Options in the provider form is set to Chat Completions (routing required), and that Settings -> Routing has both the Routing Master Switch and Codex takeover turned on.

Can I switch back to OpenAI Official while local routing is enabled?

Not recommended. CC Switch tries to prevent switching to official providers while local routing takeover is active, because accessing official APIs through a proxy may create account risk. Use official login only to preserve auth.json, and route model traffic to third-party providers.

Why is this flow so complex? Can it be simplified?

Because Codex App Enhancements and routing takeover can create unnecessary trouble for users who do not need them, these features are explicit switches instead of always-on behavior.

References Copy Chapter

• Can't see custom models in the Codex desktop app? (FAQ)
• Using Chat-Format APIs in Codex: Local Routing Guide
• Add a Codex provider: Chat Completions routing and model mapping
• Local Proxy Service
• Local Routing
• CC Switch v3.16.1 Release Note
• CC Switch v3.20.1 Release Note

Guides Codex Official Auth Preservation Guide Ja (`docs/guides/codex-official-auth-preservation-guide-ja.md`) Copy Section

サードパーティ API 利用時に Codex のリモート操作と公式プラグインを保持する: CC Switch 設定ガイド

対象バージョン: CC Switch v3.20.1 以降。画面の文言は v3.20.4 に準拠しています。本記事は現在のコード、ユーザーマニュアル、v3.16.1 / v3.20.1 Release Note をもとに整理しています。スクリーンショットは匿名化したサンプルデータを使用しており、実際の Access Token や API Key は含まれていません。一部のスクリーンショットは旧バージョンで撮影したものです。スイッチ名は本文の表記に従ってください。

このガイドで解決すること Copy Chapter

Codex を使うとき、多くのユーザーには次の 2 つの要望があります。

1. DeepSeek、Kimi、GLM、MiniMax、SiliconFlow などのサードパーティ API、または中継サービス上の GPT モデルを使いたい。
2. Codex 公式アプリのモバイルリモート操作、公式プラグインなどの機能は残したい。

以前は、サードパーティプロバイダーへ切り替えると、旧動作ではサードパーティ API Key が Codex の auth.json に書き込まれ、元の公式 ChatGPT / Codex ログインキャッシュを上書きする可能性がありました。これによりサードパーティモデルは使えるものの、公式ログイン状態に依存する機能が消えてしまうことがありました。

v3.16.1 で追加された Codex アプリ拡張 スイッチは、この矛盾を解決するためのものです。公式 Access Token は auth.json に残し、サードパーティプロバイダー情報は config.toml に書き込みます。これにより Codex App は引き続き公式アカウントでログインしていると認識しつつ、実際のモデルリクエストは CC Switch で現在選択されているサードパーティプロバイダーへ流れます。

この機能自体は v3.16.0 から存在し、当時はデフォルトで有効でした。ただし一部のユーザーから不要というフィードバックがあったため、v3.16.1 で明示的なスイッチになりました。

v3.20.1 からは切り替えロジックがさらに一段シンプルになりました。サードパーティ API Key は常に config.toml にだけ書き込まれ、auth.json に書き込まれることは決してありません。このスイッチが決めるのは今や 1 つだけです。ルーティング接管なしでサードパーティプロバイダーへ切り替えるとき（直接切替）、auth.json 内の公式ログインを保持するか削除するか、です。

まず結論 Copy Chapter

おすすめの手順は次のとおりです。

1. CC Switch の Codex パネルで OpenAI Official に切り替える。
2. Codex を起動し、公式 ChatGPT / Codex アカウントで一度ログインする。Free サブスクリプションでも構いません。
3. CC Switch に戻り、設定 → 一般 → Codex アプリ拡張 → 直接切替時に公式ログインを保持 をオンにする。
4. サードパーティ Codex プロバイダーを追加、または切り替える。
5. そのプロバイダーが Chat Completions プロトコル（カードに ルーティングが必要 バッジが付いているもの。たとえば SiliconFlow、ModelScope）の場合は、ローカルルーティングも有効化し、Codex のルーティングをオンにする。DeepSeek、Kimi、MiniMax、Zhipu GLM などのプリセットはすでにネイティブ直結のため、この手順は不要です。
6. Codex を再起動し、config.toml とモデルカタログを再読み込みさせる。

事前準備 Copy Chapter

次のものを用意してください。

• CC Switch v3.20.1 以降。
• インストール済みで起動できる Codex。app と CLI の両方を入れておくことをおすすめします。
• Codex にログインできる公式 ChatGPT / Codex アカウント。Free サブスクリプションで構いません。
• DeepSeek、Kimi、GLM、MiniMax、OpenRouter、SiliconFlow などのサードパーティ API Key。

~/.codex/auth.json の内容を手動でコピーしたり共有したりしないでください。このファイルには公式ログインキャッシュと Access Token が保存されており、機密情報です。

Step 1: OpenAI Official に戻して公式ログインを完了する Copy Chapter

CC Switch を開き、上部の Codex タブへ切り替えます。まず OpenAI Official プロバイダーを選択します。存在しない場合は、プリセットプロバイダーから追加して現在のプロバイダーにしてください。

次に Codex を起動します。CLI の起動がおすすめです。Codex の公式ログインフローに従い、ChatGPT / Codex アカウントでログインします。このアカウントは Free プランでも問題ありません。この構成では、主に Codex App が必要とする公式ログイン ID を保持する役割であり、サードパーティモデルの課金には使いません。

ログイン後、Codex は ~/.codex/auth.json に公式ログインキャッシュを保存します。以降の重要なポイントは、サードパーティプロバイダー切り替えでこのファイルを上書きさせないことです。

Step 2: Codex アプリ拡張を有効化する Copy Chapter

CC Switch に戻り、次を開きます。

設定 → 一般 → Codex アプリ拡張

次のスイッチをオンにします。

直接切替時に公式ログインを保持

このスイッチはデフォルトでオフです。一部のユーザーはこの機能を必要としていないためです。「サードパーティ API + 公式リモート操作 / 公式プラグイン」を同時に使いたい場合だけ有効化してください。

有効化すると、ルーティング接管を有効にしていない状態でサードパーティプロバイダーへ切り替えたときに、次のようになります。

• auth.json: 公式 ChatGPT / Codex ログインキャッシュを保持します。
• config.toml: 現在のサードパーティプロバイダーのモデル、endpoint、model_provider、provider-scoped experimental_bearer_token を書き込みます。

config.toml 側はスイッチとは無関係で、スイッチがオフでも同じように書き込まれます。スイッチが扱うのは auth.json を残すかどうかだけです。ルーティング接管中は、このスイッチに関係なく公式ログインが常に保持されます。

Step 3: サードパーティ Codex プロバイダーを追加する Copy Chapter

Codex パネルに戻り、右上のプラスボタンからプロバイダーを追加します。DeepSeek、Kimi、MiniMax、GLM、SiliconFlow などの内蔵プリセットを優先して使うのがおすすめです。プリセットを選んだ後は API Key を入力するだけで、プリセットが base URL、デフォルトモデル、モデルカタログ、上流フォーマットを自動で構成します。

保存したら、プロバイダーカードのバッジを確認します。

• バッジなし: 上流が OpenAI Responses API をネイティブにサポートしており、直結できるため、ローカルルーティングは不要です。DeepSeek、Kimi、MiniMax、Zhipu GLM、千问AI平台 のプリセット、そして GPT モデルを提供する中継サービスは、いずれもこちらに当たります。
• ルーティングが必要 バッジあり: 上流フォーマットが Chat Completions（ルーティング必須） のもので、たとえば SiliconFlow、ModelScope です。この種のプロバイダーはローカルルーティングを必ず有効化し、CC Switch が Codex の Responses リクエストを Chat Completions リクエストへ変換できるようにしてください。

カスタムプロバイダーの上流フォーマットは、フォーム下部の 詳細オプション → 上流フォーマット で選択します。

Step 4: 必要に応じてローカルルーティングと Codex ルーティングを有効化する Copy Chapter

次を開きます。

設定 → ルーティング → ローカルルーティング

次の 2 つを行います。

1. ルーティング総スイッチ をオンにし、ローカルサービスを起動する。デフォルトアドレスは通常 127.0.0.1:15721 です。
2. ルーティング有効 で Codex をオンにする。

ルーティング有効化後、Codex の live config.toml は一時的に CC Switch のローカルルートを指し、トークンの箇所にはプレースホルダー PROXY_MANAGED が書き込まれます。実際のサードパーティ API Key は CC Switch のプロバイダー設定内に残り、ローカルルートが転送時に注入します。ルーティング接管中は、auth.json 内の公式ログインが常に保持されます。

Step 5: サードパーティプロバイダーへ切り替えて Codex を再起動する Copy Chapter

Codex プロバイダー一覧に戻り、先ほど追加したサードパーティプロバイダーを有効化します。切り替え後は Codex の再起動をおすすめします。理由は 2 つあります。

• Codex は起動時に config.toml を読み込みます。
• Codex の /model メニューは通常、再起動後に model_catalog_json を再読み込みします。

再起動後、簡単に確認できます。

• Codex App ではアカウント情報が引き続き公式アカウントとして表示される。これは期待される動作です。
• CC Switch では現在の Codex プロバイダーがサードパーティプロバイダーになっている。
• ローカルルーティングを有効化している場合、リクエストログまたはルーティング統計で Codex リクエストがローカルルートを通っていることを確認できる。
• サードパーティプロバイダー側のダッシュボードや残高記録に実際のモデルリクエストが表示される。

仕組み Copy Chapter

Codex の設定は主に 2 つのファイルに分かれています。

~/.codex/auth.json
~/.codex/config.toml

この 2 つは役割が異なります。

• auth.json は公式 ChatGPT / Codex ログインキャッシュを保存します。Codex App が公式アカウント、リモート操作、公式プラグインを認識するために必要なログイン材料です。
• config.toml は現在のモデルプロバイダー、base URL、モデル、モデルカタログ、provider-scoped token などの実行時設定を保存します。

直接切替でサードパーティプロバイダーへ切り替えるとき、CC Switch はサードパーティプロバイダー API Key をプロバイダー設定から取り出し、config.toml の現在の provider 配下へ書き込みます（この処理はスイッチとは無関係です）。

model_provider = "custom"

[model_providers.custom]
name = "DeepSeek"
base_url = "https://api.deepseek.com"
wire_api = "responses"
experimental_bearer_token = "sk-..."

直接切替時に公式ログインを保持 をオンにしている場合、auth.json は公式ログインキャッシュを保持したままです。そのため Codex App 側では公式アカウントを認識でき、モデルリクエストは config.toml の現在の provider と base URL に従ってサードパーティ API へ向かいます。

プロバイダーが Chat Completions プロトコルの場合、CC Switch のローカルルーティングがさらに変換層になります。

Codex Responses リクエスト
        |
CC Switch ローカルルート
        |
サードパーティ Chat Completions API
        |
Codex Responses レスポンスへ変換

これにより、公式プラグイン / モバイルリモート操作を使い続けながら、モデル通信だけをサードパーティ API に切り替えられます。

理解しておくべき副作用 Copy Chapter

Codex 内の表示アカウントは公式アカウントのまま Copy Section

ここが最も誤解されやすい点です。この機能を有効化すると、Codex App は auth.json 内の公式ログイン状態を見るため、公式アカウント情報を表示し続けます。

ただし、これはモデルリクエストが公式 OpenAI に流れているという意味ではありません。実際の通信先は、CC Switch の現在の Codex プロバイダー、config.toml、ローカルルーティングログで判断してください。

Codex のアカウント表示で課金先を判断しない Copy Section

DeepSeek に切り替えた場合でも、Codex には公式アカウントが表示されます。しかしモデルリクエストは DeepSeek API へ送られます。課金、上限、エラーコード、データポリシーはサードパーティプロバイダー側の仕様として理解してください。具体的なリクエスト情報は使用量パネルで確認できます。

モデルマッピングを変更したら Codex を再起動する Copy Section

Codex のモデルカタログは起動時に読み込まれます。CC Switch が新しいモデルカタログを生成していても、実行中の Codex がホットロードするとは限りません。モデルマッピングを変更した後は Codex を再起動してください。

スイッチをオフにすると、直接切替で公式ログインが削除される Copy Section

直接切替時に公式ログインを保持 をオフにすると、ルーティング接管を有効にしていない状態でサードパーティプロバイダーへ切り替えたとき、CC Switch は auth.json を削除します。これにより Codex App は公式ログイン状態を失い、公式リモート操作や公式プラグインも使えなくなります。サードパーティ API Key はこの場合も config.toml にだけ書き込まれ、auth.json には書き込まれません。

ルーティング接管中はこのスイッチの影響を受けず、公式ログインは常に保持されます。公式リモート操作と公式プラグインを長期的に保持したい場合は、このスイッチをオンのままにすることをおすすめします。

よくある質問 Copy Chapter

サードパーティ API に切り替えたのに、なぜ Codex はまだ公式アカウントを表示しますか？

これは期待される動作です。公式アカウント情報は auth.json から取得され、実際のモデルプロバイダーは config.toml と CC Switch の現在のプロバイダーで決まります。

Free サブスクリプションで本当に大丈夫ですか？

大丈夫です。ここでの公式アカウントは、Codex App が必要とする公式ログイン状態を取得・保持するために使います。サードパーティモデルリクエストは、CC Switch に設定したサードパーティ API Key を使います。

有効化しても公式プラグインやモバイルリモート操作が使えない場合は？

まず OpenAI Official に戻し、Codex を再起動して一度公式ログインを完了してください。その後、CC Switch の 設定 → 一般 → Codex アプリ拡張 → 直接切替時に公式ログインを保持 がオンになっていることを確認し、再度サードパーティプロバイダーへ切り替えてください。

サードパーティリクエストが 404 になる、モデル一覧が違う、ストリーミング応答がおかしい場合は？

そのプロバイダーが Chat Completions プロトコルの場合、プロバイダーフォームの 詳細オプション にある 上流フォーマット が Chat Completions（ルーティング必須） になっていること、さらに 設定 → ルーティング でルーティング総スイッチと Codex ルーティングがオンになっていることを確認してください。

ローカルルーティング中に OpenAI Official へ戻せますか？

おすすめしません。CC Switch は、ローカルルーティングで Codex を管理している間に公式プロバイダーへ切り替えることをできるだけ防ぎます。プロキシ経由で公式 API にアクセスすると、アカウントリスクが発生する可能性があるためです。公式ログインは auth.json を保持するために使い、モデル通信はサードパーティプロバイダーへ切り替えるのがおすすめです。

なぜ手順がこんなに複雑なのですか？もっと簡単にできますか？

Codex アプリ拡張やルーティング管理は、必要ないユーザーにとっては余計なトラブルになり得るため、常時有効ではなく明示的なスイッチになっています。

参考リンク Copy Chapter

• Codex デスクトップアプリでカスタムモデルが見えない？（よくある質問）
• Codex で Chat 形式 API を使う: ローカルルーティングガイド
• Codex プロバイダーの追加: Chat Completions ルーティングとモデルマッピング
• ローカルプロキシサービス
• ローカルルーティング
• CC Switch v3.16.1 Release Note
• CC Switch v3.20.1 Release Note

Guides Codex Official Auth Preservation Guide Zh (`docs/guides/codex-official-auth-preservation-guide-zh.md`) Copy Section

使用第三方 API 时保留 Codex 远程操作和官方插件：CC Switch 配置攻略

适用版本：CC Switch v3.20.1 及以上，界面文字以 v3.20.4 为准。本文根据当前代码、用户手册和 v3.16.1 / v3.20.1 Release Note 整理，截图使用去敏示例数据，不包含真实 Access Token 或 API Key。部分截图拍摄于旧版本，开关名称以正文为准。

这篇攻略解决什么问题 Copy Chapter

很多人使用 Codex 时有两个需求：

1. 模型使用 DeepSeek、Kimi、GLM、MiniMax、硅基流动等第三方 API，或者在中转站使用 gpt 模型。
2. 保留 Codex 官方 App 的手机远程操作、官方插件等能力。

之前切换第三方供应商时，旧行为会把第三方 API Key 写进 Codex 的 auth.json，从而覆盖原来的官方 ChatGPT / Codex 登录缓存。这样第三方模型能用了，但依赖官方登录态的功能会消失。

v3.16.1 新增的 Codex 应用增强开关就是为了解决这个矛盾：让官方 Access Token 继续留在 auth.json，而第三方供应商信息写入 config.toml。这样 Codex App 仍然认为你登录的是官方账号，但实际模型请求会走 CC Switch 当前选中的第三方供应商。

v3.16.0 就有这个功能，并且默认开启，但是部分用户反映并不想要这个功能，所以在 v3.16.1 中把这个功能做成了开关。

v3.20.1 起切换逻辑又简化了一步：第三方 API Key 一律只写进 config.toml，永远不会写入 auth.json。这个开关现在只决定一件事：直连切到第三方供应商时，auth.json 里的官方登录是保留还是删除。

先看结论 Copy Chapter

推荐顺序是：

1. 在 CC Switch 的 Codex 面板切换到 OpenAI Official。
2. 启动 Codex，并用官方 ChatGPT / Codex 账号登录一次，Free 订阅也可以。
3. 回到 CC Switch，打开 设置 → 通用 → Codex 应用增强 → 非接管切换时保留官方登录。
4. 添加或切换到第三方 Codex 供应商。
5. 如果该供应商是 Chat Completions 协议（卡片上带 需要路由 徽章，例如 SiliconFlow、ModelScope），需要同时开启本地路由并启用 Codex 接管。DeepSeek、Kimi、MiniMax、智谱 GLM 等预设已是原生直连，不需要这一步。
6. 重启 Codex，让 config.toml 和模型目录重新加载。

准备工作 Copy Chapter

你需要准备：

• CC Switch v3.20.1 或更新版本。
• 已安装并能启动的 Codex（建议 app 和 cli 都安装）。
• 一个可以登录 Codex 的官方 ChatGPT / Codex 账号，Free 订阅即可。
• 一个第三方 API Key，例如 DeepSeek、Kimi、GLM、MiniMax、OpenRouter、硅基流动等。

请不要手动复制或分享 ~/.codex/auth.json 的内容。里面保存的是官方登录缓存和 Access Token，属于敏感信息。

第一步：先切回 OpenAI Official 并完成官方登录 Copy Chapter

打开 CC Switch，切到顶部的 Codex 标签页。先选择 OpenAI Official 供应商（如果没有的话，就在预设供应商当中添加一个），并把它设为当前供应商。

接着启动 Codex（建议启动 cli），按 Codex 的官方登录流程登录你的 ChatGPT / Codex 账号。这个账号可以是 Free 订阅；在这个方案里，它主要负责保留 Codex 官方 App 需要识别的登录身份，不负责第三方模型的计费。

登录完成后，Codex 会在 ~/.codex/auth.json 中保存官方登录缓存。后面的关键点就是：不要再让第三方供应商切换覆盖这个文件。

第二步：开启 Codex 应用增强 Copy Chapter

回到 CC Switch，进入：

设置 → 通用 → Codex 应用增强

打开：

非接管切换时保留官方登录

这个开关默认关闭，是因为部分用户并不想要这个功能。只有在你明确需要“第三方 API + 官方远程操作 / 官方插件”同时存在时，才需要开启它。

开启后，在未开启路由接管时切换到第三方供应商：

• auth.json：继续保留官方 ChatGPT / Codex 登录缓存。
• config.toml：写入当前第三方供应商的模型、endpoint、model_provider 和 provider-scoped experimental_bearer_token。

config.toml 这一半与开关无关，关着开关也是这样写；开关只管 auth.json 的去留。开启路由接管期间，官方登录始终保留，不看这个开关。

第三步：添加第三方 Codex 供应商 Copy Chapter

回到 Codex 面板，点击右上角的加号添加供应商。推荐优先使用内置预设，例如 DeepSeek、Kimi、MiniMax、GLM、SiliconFlow 等。选择预设后只需要填 API Key，预设会自动配置 base URL、默认模型、模型目录和上游格式。

保存后看供应商卡片上的徽章：

• 没有徽章：上游原生支持 OpenAI Responses API，可以直连，不需要本地路由。DeepSeek、Kimi、MiniMax、智谱 GLM、千问AI平台的预设，以及提供 gpt 模型的中转站，都属于这一类。
• 带 需要路由 徽章：上游格式是 Chat Completions（需开启路由），例如 SiliconFlow、ModelScope。这类供应商必须启用本地路由，让 CC Switch 把 Codex 的 Responses 请求转换成 Chat Completions 请求。

自定义供应商的上游格式在表单底部的 高级选项 → 上游格式 里选择。

第四步：需要时开启本地路由并接管 Codex Copy Chapter

进入：

设置 → 路由 → 本地路由

完成两件事：

1. 打开 路由总开关，启动本地服务。默认地址通常是 127.0.0.1:15721。
2. 在 路由启用 中打开 Codex。

接管后，Codex 的 live config.toml 会临时指向 CC Switch 本地路由，令牌处写的是占位符 PROXY_MANAGED。真实第三方 API Key 仍然存储在 CC Switch 的供应商配置中，由本地路由在转发时注入。接管期间 auth.json 里的官方登录始终保留。

第五步：切换第三方供应商并重启 Codex Copy Chapter

回到 Codex 供应商列表，启用你刚添加的第三方供应商。切换完成后建议重启 Codex，原因有两个：

• Codex 在启动时读取 config.toml。
• Codex 的 /model 菜单通常需要重启后才会重新加载 model_catalog_json。

重启后，你可以做一个简单验证：

• 在 Codex App 里，账号信息仍然显示官方账号，这是预期行为。
• 在 CC Switch 里，当前 Codex 供应商显示为第三方供应商。
• 如果开启了本地路由，请求日志或路由统计会看到 Codex 请求经过本地路由。
• 第三方供应商后台或余额记录会出现实际模型请求。

背后的原理 Copy Chapter

Codex 的配置主要分成两个文件：

~/.codex/auth.json
~/.codex/config.toml

这两个文件承担的职责不同：

• auth.json 保存官方 ChatGPT / Codex 登录缓存，也就是 Codex App 识别官方账号、远程操作和官方插件所需的登录材料。
• config.toml 保存当前模型供应商、base URL、模型、模型目录和 provider-scoped token 等运行配置。

直连切换到第三方供应商时，CC Switch 会把第三方供应商 API Key 从供应商配置中取出，写到 config.toml 的当前 provider 下（这一步与开关无关）：

model_provider = "custom"

[model_providers.custom]
name = "DeepSeek"
base_url = "https://api.deepseek.com"
wire_api = "responses"
experimental_bearer_token = "sk-..."

开启 非接管切换时保留官方登录 时，auth.json 保持官方登录缓存不变。于是 Codex App 侧依然能识别官方账号；而模型请求会根据 config.toml 的当前 provider 和 base URL 走第三方 API。

如果供应商是 Chat Completions 协议，CC Switch 本地路由会再做一层转换：

Codex Responses 请求
        ↓
CC Switch 本地路由
        ↓
第三方 Chat Completions API
        ↓
转换回 Codex Responses 响应

这就是为什么你既能继续使用官方插件 / 手机远程操作，又能把模型流量切到第三方 API。

需要理解的副作用 Copy Chapter

Codex 里显示的账号始终是官方账号 Copy Section

这是最容易误解的一点。开启该能力后，Codex App 看到的是 auth.json 里的官方登录态，所以它会继续显示官方账号信息。

但这不代表模型请求还在走官方 OpenAI。实际流量以 CC Switch 当前 Codex 供应商、config.toml 和本地路由日志为准。

不要用 Codex 账号信息判断计费方 Copy Section

如果你切到 DeepSeek，Codex 里仍然显示官方账号，但模型请求会走 DeepSeek API。计费、限额、错误码和数据策略都应按第三方供应商理解。可以查看设置用量面板里的具体请求信息。

修改模型映射后要重启 Codex Copy Section

Codex 的模型目录是启动时读取的。即使 CC Switch 已经生成了新的模型目录，正在运行的 Codex 也不一定会热加载，所以修改模型映射后请重启 Codex。

关闭开关后，直连切换会删除官方登录 Copy Section

如果关闭 非接管切换时保留官方登录，在未开启路由接管时切换到第三方供应商，CC Switch 会删除 auth.json，Codex App 随之失去官方登录态，官方远程操作和官方插件也就用不了。第三方 API Key 照样只写进 config.toml，不会写入 auth.json。

开启路由接管期间不受这个开关影响，官方登录始终保留。如果你的目标是长期保留官方远程操作和官方插件，建议保持该开关开启。

常见问题 Copy Chapter

我已经切到第三方 API，为什么 Codex 还显示官方账号？

这是预期行为。官方账号信息来自 auth.json，模型请求的实际供应商来自 config.toml 和 CC Switch 当前供应商。

Free 订阅真的可以吗？

可以。这里的官方账号主要用于获取并保留 Codex App 需要的官方登录态。第三方模型请求使用的是你在 CC Switch 里配置的第三方 API Key。

开启后官方插件或手机远程操作还是不可用怎么办？

先切回 OpenAI Official，重新启动 Codex 并完成一次官方登录；然后确认 CC Switch 的 设置 → 通用 → Codex 应用增强 → 非接管切换时保留官方登录 已开启，再切回第三方供应商。

第三方请求 404、模型列表不对或流式响应异常怎么办？

如果该供应商是 Chat Completions 协议，请确认供应商表单 高级选项 里的 上游格式 是 Chat Completions（需开启路由），并且 设置 → 路由 里已经启动路由总开关、启用 Codex 接管。

可以在本地路由模式下切回 OpenAI Official 吗？

不建议。CC Switch 会尽量阻止在本地路由接管模式下切到官方供应商，因为用代理访问官方 API 可能带来账号风险。建议官方登录只用于保留 auth.json，模型流量则切到第三方供应商。

为什么流程做的这么复杂？可以简化吗？

因为 Codex 增强开关和路由接管等一系列功能，如果用户并不需要的话，默认打开会带来不必要的麻烦，所以都做成了开关形式。

参考链接 Copy Chapter

• Codex 桌面应用里看不到自定义模型？（常见问题）
• 在 Codex 中使用 Chat 格式 API：本地路由攻略
• 添加 Codex 供应商：Chat Completions 路由与模型映射
• 本地代理服务
• 本地路由
• CC Switch v3.16.1 Release Note
• CC Switch v3.20.1 Release Note

Guides Codex Unified Session History Guide En (`docs/guides/codex-unified-session-history-guide-en.md`) Copy Section

Unified Codex Session History: Feature Overview and Usage Guide (CC Switch)

Applies to CC Switch v3.16.x and later. This guide is based on the current code; every command and path can be verified by hand. Examples use de-identified data and contain no real session content or API keys.

What this feature is Copy Chapter

"Unified Codex session history" is a switch that CC Switch v3.16.x adds for Codex. You'll find it under Settings -> General -> the "Codex App Enhancements" group ("Codex App Enhancements" is the group title; the switch itself is called "Unified Codex session history"). Once enabled, sessions from your official subscription (ChatGPT login / OpenAI API key) appear in the same history / resume list as sessions from every third-party provider CC Switch manages—they are no longer split into two lists that can't see each other.

What problem it solves Copy Chapter

Codex classifies sessions by a "provider tag" (a field called model_provider), and the resume / history list only shows sessions whose tag matches your currently active provider. As a result, sessions are naturally sorted into two separate "drawers":

• Sessions from your official subscription go under Codex's built-in openai tag;
• Every third-party provider CC Switch manages goes under the custom tag.

The two drawers can't see each other. If you switch frequently between official and third-party, you'll hit this kind of fragmentation: "the session I was just chatting in with the official account disappeared from the history list after I switched to a third-party provider"—it isn't actually gone, it's just been sorted into the other drawer. This split both makes it easy to believe a session was lost, and makes it inconvenient to review and resume all your sessions in one place.

This switch exists to eliminate that fragmentation: it makes the official subscription run under the custom tag too, so official and third-party sessions merge into one list and everything is easy to find and resume in a single place.

✅ One important premise that runs through this whole guide, please remember it first: this feature (unify / migrate / restore) only ever rewrites that one classification tag model_provider in your session records, and it automatically makes a backup of the original file before every rewrite. It never deletes, clears, or overwrites a single line of your conversations. So whenever this guide later mentions "some sessions are no longer visible," it almost always means "they've been sorted into the other drawer," not "the data is gone." If you're truly worried, jump straight to the symptom reference table and verify the files are still there by hand.

How it works (one-line version) Copy Chapter

Think of it as two drawers + automatic backup:

• By default, official sessions live in the openai drawer and third-party sessions live in the custom drawer, invisible to each other;
• The switch makes the official side use the custom drawer too, merging the two drawers into one shared list;
• You can optionally choose to "move" your existing official sessions into the shared drawer as well (this step is called migration; it's optional and requires you to opt in by checking a box), and before anything is moved a backup copy is made first, so the whole process is reversible;
• Authentication is completely unaffected—your official subscription still uses your ChatGPT login and still goes through the official backend; only the session's classification tag changes.

For the full mechanism (what gets injected, why it's reversible, how migration / restore guarantee no data loss) see The core mental model and the Advanced mechanism appendix at the end.

How to use it (at a glance) Copy Chapter

1. Enable: Settings -> General -> Codex App Enhancements -> turn on "Unified Codex session history" -> in the dialog decide whether to check "Also migrate existing official session history" (check it if you want your earlier official sessions merged into the unified list too; leave it unchecked if you only want unification from now on) -> confirm. See What happens when you enable it.
2. Disable: turn the same switch off -> in the dialog keep "restore exactly from backup" checked (it's checked by default) -> confirm, and the official sessions you migrated in will be precisely flipped back to the official list. See What happens when you disable it.
3. Feel like a session is gone? Don't panic—jump to the symptom reference table to locate it by symptom, and use the commands in the verify by hand section to see for yourself that the files are all there.

The core mental model: two drawers + automatic backup Copy Chapter

To understand this feature, you only need to remember two things: drawers and backups.

Drawers: how Codex classifies sessions Copy Section

Every time you start a Codex session, Codex records a tag model_provider in the session file header, marking "which provider this session was chatted with." Codex's resume / history list is filtered precisely by the currently active tag—it only shows sessions whose tag matches "the provider you're on right now."

• Sessions from your official subscription (ChatGPT login / OpenAI API key) carry the built-in tag openai.
• Every third-party provider CC Switch manages uses the tag custom.

So by default, official sessions and third-party sessions are inherently invisible to each other—they live in two different drawers. This is Codex's own design, not CC Switch losing anything.

Default state (unified switch off):
   ┌───────────────────────┐     ┌──────────────────────────┐
   │  openai drawer        │     │  custom drawer           │
   │  (official sessions)  │     │  (third-party sessions)  │
   └───────────────────────┘     └──────────────────────────┘
       ▲                             ▲
     visible only while            visible only while
     on the official provider       on a third-party provider

   The two drawers can't see each other.

What the "Unified Codex session history" switch does is make the official subscription run under the custom tag too, merging the two drawers into one, so official and third-party sessions appear in the same resume list. Note: authentication doesn't change—your official subscription still uses your ChatGPT login and still goes through the official backend; only the session's "classification tag" changes from openai to custom.

After the unified switch is on:
   ┌──────────────────────────────────────────────┐
   │             custom shared drawer             │
   │  official sessions  +  third-party sessions  │
   │  (appear in the same history / resume list)  │
   └──────────────────────────────────────────────┘

Backups: a copy is made before every tag change Copy Section

"Merging the drawers" requires changing the tag of some official sessions from openai to custom (this step is called migration, and it's optional and requires you to opt in). And before any rewrite, CC Switch first copies the original file untouched to here:

~/.cc-switch/backups/codex-official-history-unify-v1/<timestamp>/

This backup is the sole basis for "restore exactly from backup" later. It makes the whole process reversible: at any time you can turn off the switch and precisely flip the official sessions you migrated in back to the openai drawer.

Remember these two words—drawer (a session just gets reclassified) and backup (a copy is always made before a change)—and everything that follows will be easy to understand.

What happens when you enable it: step by step Copy Chapter

Step 1: Find the switch Copy Section

Settings -> General -> Codex App Enhancements

In the "Codex App Enhancements" block there are two rows of switches; the second row (the blue history icon) is the subject of this guide:

Unified Codex session history

Below it is a line of description text (verbatim):

When enabled, the official subscription runs under the shared "custom" provider id so official and third-party sessions appear in one history list, optionally migrating existing official sessions in (backed up first). When turning it off, the migrated sessions can be restored from backup. Note: resuming an old session across providers may fail because its encrypted_content reasoning can only be decrypted by the backend that created it.

Note: this single line of description already previews three things—sessions will appear in one list, you can optionally migrate them in with an automatic backup, and resuming across providers "may fail." Here, "fail" means you can't resume / can't generate a new turn, not "the record is lost." This is exactly the core misunderstanding we'll dig into below.

Step 2: Flip the switch from off to on -> a confirmation dialog pops up Copy Section

The moment you flip the switch on, CC Switch does not save immediately; instead it first pops up a confirmation dialog. The dialog text reads as follows (verbatim):

• Title: Unified Codex session history

• Body:

  When enabled, the official subscription and third-party providers share one session history list. Note: resuming an old session across providers may fail because its encrypted_content reasoning cannot be decrypted by another backend.

  You can also migrate your existing official session history into the shared list (originals are backed up to ~/.cc-switch/backups first and can be restored when you turn this off).

• Checkbox: Also migrate existing official session history

• Confirm button: I understand, enable

• Cancel button: Cancel

This checkbox is unchecked by default. This is an important fork in the road:

If you want "my earlier official sessions to appear in the unified list too," you must opt in by checking this box. Otherwise you'll run into "scenario A" in the reference table below—the old sessions look "gone," when in fact they're just sitting in the original drawer.

Click "Cancel" or click outside the dialog: the switch flips straight back to off and nothing happens.
Click "I understand, enable": the switch is saved as on, and CC Switch persists the configuration in the background (and runs the migration if you checked it).

Step 3 (only if you checked migration): how migration runs + data safety Copy Section

If you check "Also migrate existing official session history," CC Switch runs this procedure on your existing official sessions:

For each official (openai tag) session file:
   ① First copy the original file untouched into the backup directory   <- data now has its first safety net
   ② Using "write a temp file -> replace the whole thing" atomic style,
      change only the model_provider in the session_meta line at the header
      from "openai" to "custom"                                          <- not a single byte of the conversation body is touched
   ③ Update the index database state_5.sqlite to switch the tag in the same transaction

• Backup location: ~/.cc-switch/backups/codex-official-history-unify-v1/<timestamp>/. Each migration produces one timestamped "generation directory," containing jsonl/ (session copies), state/ (index DB copy), and meta.json (recording which Codex directory this migration belongs to).
• What's changed: only the value of the single field model_provider. Your conversation content, reasoning content, and all body text are kept exactly as is.
• What's deleted: nothing. The backup is a "copy," the rewrite is an "atomic replacement of the same file," and at no point is any session or index deleted. The file is complete at every moment (either the old content or the new content, never empty or half-written).

After a successful migration, these existing official sessions show up in the unified list. At this moment your data is: ① the original copy in the backup directory; ② in the active file, only the classification tag changed, the content intact.

Note: enabling and migration themselves do not pop a success toast. Migration runs as a side task on the backend during save; in the UI you'll only see the switch turn on. So "I didn't see a migration-success popup" is normal and does not mean failure.

What happens when you disable it: step by step Copy Chapter

Step 1: Flip the switch from on to off -> probe for backups -> a confirmation dialog pops up Copy Section

When disabling, CC Switch first spends a moment probing whether there's a migration backup, then pops up a confirmation dialog (so the disable dialog has a slight delay, which is normal). The text reads as follows (verbatim):

• Title: Turn off unified session history

• Body:

  After turning this off, the official subscription and third-party providers return to separate history lists. Sessions created while it was on cannot be attributed to a provider, so they stay in the third-party history and the official subscription will not see them.

• Checkbox (shown conditionally): Restore the official sessions migrated at enable time back to the official history (exact restore from backup)

• Confirm button: Turn off

• Cancel button: Cancel

Key point: the body says the official subscription will not see them—won't see, not delete. The new sessions you chatted during the unified period are still fully present in the custom drawer; after disabling, the official side simply won't see them.

This restore checkbox is checked by default. In other words, the default behavior is "restore the official sessions you migrated in back to the official history at the same time you disable." You only need to keep it checked and click "Turn off."

If the checkbox doesn't appear, the system has determined there's no backup that needs restoring (either you never checked migration, or no backup was found)—in that case your existing official sessions were never touched, and turning off the switch returns them to the openai drawer on their own.

Step 2: How restore runs (precise flip-back per the backup ledger) Copy Section

If you keep the box checked and click "Turn off," CC Switch's restore flow goes like this:

① First copy the current state once more into a separate restore-backup directory
   ~/.cc-switch/backups/codex-official-history-unify-restore-v1/<timestamp>/
   (restore itself backs up first, so restore won't lose data either)
② Comb through all migration backup generations, find the session ids "whose tag was originally openai," and assemble a "ledger"
③ Only for sessions that are [both in the ledger AND currently still custom], change the tag back to "openai"

Note the dual condition in step ③—it must be in the ledger (proving it really was migrated from the official side) AND currently still custom (showing you haven't manually changed it). Only when both conditions hold does it get flipped back. This guarantees the restore is both precise and free of collateral damage.

At this moment your data is: the migrated-back official sessions have their tag changed back to openai and reappear in the official list; meanwhile both the migration backup and the restore backup copies are still on disk.

Step 3: Read the toast, confirm the result Copy Section

Only the "disable + check restore" path pops a result toast. The toasts you may see (verbatim):

A thoughtful safety design: if the "disable the switch" save fails, CC Switch never runs the restore. Otherwise you'd end up in a torn state of "switch still on, but sessions flipped back to the openai bucket." When the save fails, the switch automatically flips back to its original position, so you won't be stuck in a fake state of "looks off but didn't actually save."

"I feel like my sessions are gone?" symptom reference table Copy Chapter

The six scenarios below are the situations where users most easily believe "sessions are gone." The truth in every one is: the data is intact, it just moved drawers or is temporarily out of sight. Use this table to locate your symptom first, then read the detailed explanation below.

Scenario A: You enabled the switch but didn't check migration -> old official sessions "disappear" Copy Section

Symptom: you turned on the unified switch, but didn't check "Also migrate existing official session history" in the enable dialog (it's unchecked by default). After enabling, your earlier official sessions seem to be gone from the list.

The truth: 100% of your data is present, not a single line moved. The switch only takes effect on official sessions "created after enabling"; your official sessions from before enabling still carry the openai tag and sit untouched in ~/.codex/sessions/. You're now on the custom drawer, so naturally you can't see the old sessions left in the openai drawer—that's the entire reason for the "apparent disappearance."

What to do (pick either):

1. Re-enable the switch and check "Also migrate existing official session history," which moves the old sessions to the custom drawer and they immediately appear in the unified list (automatic backup before the rewrite).
2. Or simply turn off the unified switch, the official side runs on the openai drawer again, and the old sessions reappear right where they were.

Scenario B: Cross-provider resume of an old session fails -> you think "this session is broken / gone" Copy Section

Symptom: after unification, the list shows an old session chatted with "another provider." You switch to your current provider and click "Resume," but it errors out or can't connect.

The truth: the session file is intact; what's lost is not data, it's "cross-backend decryption ability." A Codex session stores an encrypted block of reasoning content encrypted_content, and this ciphertext can only be decrypted by the backend that originally generated it. Using provider B to resume a session generated by provider A means B can't decrypt A's ciphertext -> resume fails. This is a design limitation of upstream Codex (by design) and has nothing to do with whether CC Switch touched the file. The text content of the session is readable at any time.

This is the only "looks like a real problem" genuine exception in this whole guide—but note: it just means you can't resume (can't generate a new turn), and the original file is still fully present, the conversation text readable at any time.

What to do:

• Resume with "the provider that originally created this session," so it can decrypt normally and connect.
• Just want to read the history without continuing? Read that session's .jsonl file directly (commands at the end).
• Rule of thumb: cross-provider is better suited to "starting a new session"; resume old sessions on their original provider whenever possible.

Scenario C: You enabled the switch and checked migration, but migration was silently skipped -> you think "migration lost the sessions" Copy Section

Symptom: you enabled the switch and checked migration, but the old official sessions neither entered the unified list nor could be restored when you turned the switch off (or the restore checkbox didn't even appear in the disable dialog, see scenario E). You suspect migration lost the sessions during the process.

The truth: migration never ran, so it couldn't have lost anything—not a single character of your sessions was changed. CC Switch has a safety gate before migration: it checks whether Codex's live config (~/.codex/config.toml) is actually routed to the shared custom drawer right now, and only migrates if the routing truly went there. The following two situations are judged "not yet unified" (internal reason code live_not_unified), so CC Switch deliberately skips the migration, preserves your switch and migration intent, and migrates later once the conditions are met:

• During routing takeover: CC Switch's local routing has taken over the live config, and the live config during takeover doesn't carry the unified routing marker.
• Injection refused: your config.toml already has a manually specified model_provider, or there's already a differently-shaped [model_providers.custom] table (possibly with a third-party address). To avoid incorrectly routing official traffic to a third-party backend, CC Switch would rather not inject and not migrate.

Skipping migration = touching no session files. No migration means nothing moved, so there's nothing to lose. This is "safe deferral," not "failure with data loss."

What to do:

• Exit routing takeover -> restart CC Switch: on startup it automatically retries migration (your migration intent is preserved the whole time).
• Check ~/.codex/config.toml: if there's a conflicting route you wrote by hand, clean up the conflict before enabling the switch.
• If you'd rather not bother: just turn off the switch, the official sessions still display normally on the openai drawer, completely intact.

Scenario D: You turned off the switch and restored, but "the new sessions chatted during the unified period" didn't return to official -> you think "the new sessions are gone" you think "the new sessions are gone"')" title="Copy section prompt for LLMs"> Copy Section

Symptom: during the unified period, you chatted a few more new sessions with the official account. Later you turned off the switch, checked restore, and after restoring you find those new sessions didn't return to the official drawer.

The truth: this is intentional design; the new sessions are perfectly fine in the custom drawer, visible and resumable. Restore is based on "the backup ledger from migration time"—only sessions that were originally migrated in from the openai drawer are recorded in the backup and get precisely flipped back to openai. The sessions you created during the unified period are in no backup ledger; and after unification both official and third-party use the custom tag, so CC Switch can't tell whether a new session was chatted with the official account or a third-party. To avoid wrongly stuffing third-party sessions into the official history, the product decision is: these new sessions all stay in the custom (third-party) history and are never moved automatically. The disable dialog's text says this explicitly too—"Sessions created while it was on cannot be attributed to a provider, so they stay in the third-party history."

What to do:

• Switch to any third-party provider (the custom drawer) to see these sessions in the history list.
• To read content, read the .jsonl directly; to resume, follow scenario B's rule (go back to the backend that originally generated it).
• If you really want to manually return one specific session to official: there's currently no automatic button (deliberately omitted, to avoid misjudging the direction). Advanced users can, after backing up that file first, manually change model_provider in the session_meta of the first line of its .jsonl from custom back to openai (an advanced operation; always make a copy before editing).

Scenario E: Restore toast "No restorable migration backup for the current Codex directory" -> you think "restore failed = data is gone" you think "restore failed = data is gone"')" title="Copy section prompt for LLMs"> Copy Section

Symptom: you checked restore when turning off the switch, and got the toast "No restorable migration backup for the current Codex directory." You panic: restore failed, is the data completely gone?

The truth: "nothing to restore" ≠ "data is lost." On the contrary, it's usually because there was no migration that needed restoring. Common reasons:

• You never checked "migrate existing official sessions" in the first place: with no migration, there's naturally no migration backup and no sessions to flip back. Your old official sessions have been in the openai drawer all along and reappear after you turn off the switch (same as scenario A). (In this case, the disable dialog may not even show the restore checkbox—because the system can't find any backup.)
• You've already restored once: the session tags have all been flipped back to openai, so clicking again naturally finds "no targets still in custom to restore"—this is idempotent protection, not failure.
• You switched Codex directories: restore only recognizes the backup ledger belonging to the current directory; switch directories and it can't find the old directory's ledger. Just switch the directory back.

In all three cases, no session was deleted.

What to do: use the end-of-guide commands to count the total session files in ~/.codex/sessions/ and confirm the files are all there; then check whether ~/.cc-switch/backups/ contains a codex-official-history-unify-v1 directory—if even this directory is absent, you never triggered a migration and the sessions have been in their original drawer all along.

Scenario F: Restore refused, toast "Unified session history was re-enabled; restore skipped" Copy Section

Symptom: you turned off the switch -> checked restore -> but you were quick and immediately turned the switch back on, then saw the toast "Unified session history was re-enabled; restore skipped."

The truth: this is a safeguard against putting your data into a "torn" state, and again no sessions are lost. The restore action is "flip session tags from custom back to openai," but if the switch is on again at this moment, the live config is routing to custom—flipping history back to openai on one side while new sessions land in custom on the other would artificially tear sessions in two. So when CC Switch detects "the switch is on again," it deliberately abandons this restore and changes nothing. Sessions stay as they are, with no deletion or corruption.

What to do: to truly restore, turn the switch off and keep it off (don't immediately turn it back on), then do disable + check restore; to keep things unified, don't restore, and let the sessions stay in the custom shared drawer for normal use.

The overriding principle: CC Switch's unify / migrate / restore only ever changes a single tag field in a session, and automatically backs up before every rewrite. It never deletes your conversations. Out of sight ≠ gone—look in the other drawer, or use the commands below to confirm with your own eyes.

Verify by hand: your session files are still on disk (the most important section) Copy Chapter

No amount of text beats seeing it for yourself. Below are the real paths (taken from the CC Switch source) and how to view session files and backup directories on different systems. The whole process is read-only and changes nothing; you're strongly encouraged to try it by hand.

The simplest way: open it directly in a file manager (no command line at all) Copy Section

• macOS (Finder): press Cmd + Shift + G, paste ~/.codex/sessions and hit Enter to see a pile of .jsonl session files and their modification times; for the backup directory paste ~/.cc-switch/backups.
• Windows (File Explorer): paste %USERPROFILE%\.codex\sessions into the address bar and hit Enter to see the session folders and the .jsonl files inside; for the backup directory paste %USERPROFILE%\.cc-switch\backups.

As long as you can see a batch of .jsonl files here, that proves your session data is intact on disk. The file count and modification times are more intuitive than any amount of text.

Where exactly your session / history files live Copy Section

Note: if you've changed the Codex directory in CC Switch, or set sqlite_home in config.toml, replace ~/.codex above with your actual directory. Below, ~ = your user home directory.

macOS / Linux commands Copy Section

1. Count the total number of session files (this is the hard evidence of "nothing lost")

# Count the total number of session files -- as long as this number matches your expectation, the data is all there
find ~/.codex/sessions ~/.codex/archived_sessions -name '*.jsonl' 2>/dev/null | wc -l

# Show the 10 most recently modified session files
find ~/.codex/sessions -name '*.jsonl' 2>/dev/null -print0 \
  | xargs -0 ls -lt 2>/dev/null | head -10

2. (Auxiliary) See how many sessions are in each "drawer"

# Number of session files in the official drawer (openai)
grep -rlE '"model_provider"[[:space:]]*:[[:space:]]*"openai"' ~/.codex/sessions 2>/dev/null | wc -l

# Number of session files in the unified drawer (custom)
grep -rlE '"model_provider"[[:space:]]*:[[:space:]]*"custom"' ~/.codex/sessions 2>/dev/null | wc -l

# See the tag distribution at a glance
grep -rhoE '"model_provider"[[:space:]]*:[[:space:]]*"[^"]*"' ~/.codex/sessions 2>/dev/null | sort | uniq -c

Important note, don't let this step scare you: early versions of Codex did not write the model_provider field into the .jsonl, so these old official sessions can't be counted by the grep above—but they're still classified as openai in the index database state_5.sqlite and still show up in the resume list. So judge "nothing lost" by the total file count from step 1—the per-drawer grep is only there to help you understand the classification, and counting fewer than the total file count is completely normal and never means "a batch was lost."

3. (Advanced) Query the index database state_5.sqlite—the classification the resume list actually reads

# Requires sqlite3 to be installed; skip if you don't have it
sqlite3 ~/.codex/state_5.sqlite \
  "SELECT COALESCE(model_provider,'<empty>'), COUNT(*) FROM threads GROUP BY 1;"

This threads table is the actual classification source Codex's resume list reads; the openai row count ≈ the number of sessions you can see in your official drawer. It may not match step 2's jsonl grep—the reason is exactly what's described above: "old sessions don't write the jsonl field, but they're still openai in the index database." A mismatch between the two is not an anomaly.

4. Read the content of a specific session directly (confirm the conversation text is still there)

# Replace <filename> with one of the .jsonl paths listed by ls above
python3 -m json.tool < "<filename>.jsonl" 2>/dev/null | head -50

# Or just open it in an editor (plain text)
open -e "<filename>.jsonl"      # macOS

5. Look at CC Switch's backup directory (proof that a copy was kept before migration / restore)

ls -la ~/.cc-switch/backups/codex-official-history-unify-v1/ 2>/dev/null
ls -la ~/.cc-switch/backups/codex-official-history-unify-restore-v1/ 2>/dev/null

Windows commands (PowerShell) Copy Section

The session directory is usually at C:\Users\<your username>\.codex\, and backups at C:\Users\<your username>\.cc-switch\backups\.

# 1. Total number of session files (hard evidence of "nothing lost")
(Get-ChildItem "$env:USERPROFILE\.codex\sessions","$env:USERPROFILE\.codex\archived_sessions" -Recurse -Filter *.jsonl -ErrorAction SilentlyContinue).Count

# 2. The 10 most recently modified sessions
Get-ChildItem "$env:USERPROFILE\.codex\sessions" -Recurse -Filter *.jsonl |
  Sort-Object LastWriteTime -Descending | Select-Object -First 10 FullName,LastWriteTime

# 3. (Auxiliary) How many session files in the official (openai) / unified (custom) drawers
(Get-ChildItem "$env:USERPROFILE\.codex\sessions" -Recurse -Filter *.jsonl |
  Select-String -Pattern 'model_provider"\s*:\s*"openai"' -List).Count
(Get-ChildItem "$env:USERPROFILE\.codex\sessions" -Recurse -Filter *.jsonl |
  Select-String -Pattern 'model_provider"\s*:\s*"custom"' -List).Count

# 4. Look at the backup directories
Get-ChildItem "$env:USERPROFILE\.cc-switch\backups\codex-official-history-unify-v1" -ErrorAction SilentlyContinue
Get-ChildItem "$env:USERPROFILE\.cc-switch\backups\codex-official-history-unify-restore-v1" -ErrorAction SilentlyContinue

Same reminder: the step-3 grep counting fewer than the total file count is normal (old sessions don't write that field); judge "nothing lost" by the total file count from step 1.

Advanced mechanism appendix (for users who want to truly understand how it works) Copy Chapter

1. The bucketing mechanism (the essence of the drawers) Copy Section

Codex's resume / history list filters by the currently active model_provider id with exact string matching. The first line of a session's .jsonl file is a type:"session_meta" record whose payload.model_provider is the drawer that session belongs to (grep -rl counts a file as long as the tag appears once anywhere in it, so no line-by-line parsing is needed; sessions from old versions that didn't write the field can't be counted). What actually drives the resume list is the threads.model_provider column of the index database state_5.sqlite. When config.toml has no explicit model_provider, the official subscription falls into the built-in default id openai; all of CC Switch's third-party providers uniformly use custom.

2. What the switch does (injection, lives only in live) Copy Section

When enabled, CC Switch injects the following into the official live config.toml:

model_provider = "custom"

[model_providers.custom]
name = "OpenAI"
requires_openai_auth = true
supports_websockets = true
wire_api = "responses"

Every field has a purpose: requires_openai_auth = true keeps authentication going through the ChatGPT login in auth.json, with the base_url defaulting back to the official Codex backend; name = "OpenAI" lets Codex's official feature gates (web search, remote compaction, etc.) keep matching; supports_websockets = true restores the capability that custom entries lose by default; wire_api = "responses" uses the official responses protocol. The net effect is: authentication is unchanged, only the bucket name changed.

Key invariant: this injection can only exist in the live config.toml, and is never written into the database's stored configuration. When you switch away from the official provider and write live back to the database, CC Switch strips this injection precisely (it strips only when the shape exactly matches the injected artifact; a third-party-customized custom table is kept as is). Precisely because of this, "turning off the switch + switching once" fully restores live, and the database always holds your original clean official configuration—this is the cornerstone of the whole switch's reversibility.

3. The two refusal gates for injection (corresponding to scenario C) Copy Section

• config.toml already has an explicit model_provider -> don't override the user's route;
• A differently-shaped [model_providers.custom] table already exists (possibly with a third-party base_url) -> refuse injection, otherwise ChatGPT OAuth traffic would be routed to the wrong backend.

When injection is refused, live is not unified, and the migration gate (checking whether live's model_provider equals custom after trim) judges live_not_unified -> skip migration, preserve intent, and do it later on the next startup retry. This is "safe deferral," not "failure with data loss."

4. The three session classes (which determine the migration / restore boundary) Copy Section

• Class A: existing official sessions migrated in at enable time—the backup is the ledger, and they can be precisely restored back to openai;
• Class B: created during the unified period—in no backup, and official / third-party can't be distinguished, so they're never moved automatically (stay custom);
• Class C: pure third-party history from before enabling—never touched.

5. The safety of migration / restore (data is never truly deleted; where the guarantee comes from) Copy Section

Four layers of design jointly guarantee that under all paths, normal and abnormal, the original session data is never truly deleted.

• Only change the field, never the body: migration / restore only switch the model_provider value in session metadata between openai and custom; conversation content, response_item, and encrypted_content are all kept exactly as is.
• Always copy a backup before a rewrite: jsonl uses file copy, the state DB uses a full SQLite copy, both stored in a timestamped generation directory. Migration backups live in codex-official-history-unify-v1/, restore backups in the separate codex-official-history-unify-restore-v1/—the two are kept apart to keep the ledger clean.
• Only move, never delete + atomic writes: all jsonl rewrites go through "temp file + whole-file replacement," and the state DB goes through a transactional UPDATE, with no deletion of any session or index at any point. The file is complete at every moment.
• Pessimistic skip + idempotent and retryable: when buckets are inconsistent (live_not_unified), it would rather not migrate; a single process lock serializes migration and restore to avoid "startup retry / post-save background task / disable-time restore" concurrently rewriting the same batch of files in both directions; the completion marker is bound to the Codex directory and written conditionally to prevent missed migrations; restore uses the "in the ledger + currently still custom" dual condition to prevent wrong changes. Restore scans the union of all backup generations, so even after many switch cycles it can still restore early-migrated sessions; a repeated restore returns nothing_to_restore, which is idempotent protection rather than failure.

6. Cross-backend encrypted_content (corresponding to scenario B) Copy Section

The reasoning ciphertext inside a session can only be decrypted by the backend that generated it; upstream Codex by design does not support cross-backend decryption. This is the root cause of "resume failure" and has nothing to do with file integrity—the session .jsonl sits fully on disk and encrypted_content is intact too. Switching back to the original provider to resume, or starting a new session, both work fine.

References Copy Chapter